BotForge 1.1.4 · 纵向汇报网站

一、设计原则

1. 先讲环境交付问题，再讲工程化答案 叙事从初学者与团队管理者的环境需求开始，再进入首次安装、后台工程链、历史实测与交付价值。 每页只回答一个主要问题：标题先给结论，说明文字解释原因，内容块展示机制或证据。

2. 用同一次安装贯穿全场 用户只表达环境目标；平台、来源、依赖、资源与恢复随着同一次安装逐步展开。 各阶段必须明确接收什么、完成什么、向下一阶段交付什么，不能写成彼此无关的功能清单。

3. 前台简单与后台复杂始终同屏 每张机制页都说明“用户仍然在做什么”和“系统此刻正在处理什么”。 计划、获取、执行与提交沿同一条工程链展开，让听众理解系统为何承担这些工作，以及用户因此少做什么。

4. 同一事实只能有一个权威结论 初学者直接运行 bot-forge，选择环境级别后理解缺口、计划、进度和下一步；团队管理者通过固定配置与机器数据复用同一标准。 工具、版本、平台规则与依赖关系收敛为统一环境模型；终端进度与机器事件只是不同投影，不能改写执行计划或最终状态。

5. 抽象规则必须配具体实例 目标展开、缓存身份、依赖就绪、资源准入和恢复规则都要同时展示规则与可读实例。 Standard 依赖图、资源准入表和 18 tokens 分配过程是机制示意，不是完整工具清单、固定并发配置或新的测量证据。

6. 性能优化不能改变安装正确性 依赖图决定谁已就绪，资源准入决定现在能否启动，动态分配决定新任务启动时获得多少配额。 CPU、内存、网络、磁盘等容量资源与安装目标互斥共同决定任务能否启动。 动态再平衡只调整后续任务的资源配额，不重启运行中的构建，也不改变命令、依赖或提交规则。

7. 缓存复用必须通过身份与完整性校验 完整工件只有在构建身份、命令集合与文件校验和全部通过后才能复用；损坏工件隔离后重新获取或构建。 未命中完整工件时，仍可从只读 seed 初始化独立 Cargo Home，并复用同身份 target；不能把缓存存在直接写成安装完成。

8. 完成与恢复边界必须可解释 托管 Cargo / Git 的完成条件包括工具通过检测、结果妥善保存、命令已经可用和完成状态已记录；其他后端按适用规则安装后重新检测。 resume 要求原配置与计划哈希一致，按未完成组件重新执行并复用有效缓存，不承诺从日志阶段原地续跑或自动补登记。 abandon 只关闭旧事务，不撤销文件；命令可用但托管记录缺失时，必须先审计目标与记录。

9. 颜色表达用户路径与系统工作 全站使用冷白底色、深蓝正文、亮蓝关键强调和深蓝系统背景。 亮蓝表示用户路径和关键动作，深蓝承载后台机制，橙色表示中断、损坏或限制，绿色表示通过或完成。 配色保持 bot-forge 的蓝色视觉体系，同级卡片使用一致的颜色语义。

10. 视觉层级优先于装饰 标题、标题下说明、板块标题、正文、指标和注释使用稳定的字号层级。 关键结论不得放在低对比度小字中；同级卡片保持一致的边框、间距和阅读顺序，复杂图示必须有可读说明。

11. 一页是一张投影画布 网站面向桌面端和现场投影，最小宽度为 1180px；每页以 1080px 为基准高度，视口更高时自动铺满。 内容必须完整容纳在单页画布内；视口低于画布时可纵向滚动，不得横向溢出、底部裁切或文字重叠。

12. 导航表达叙事状态 顶部导航负责简单开始、工程化执行和价值回归三幕的章节跳转，页面顶端细线显示全局阅读进度。 右侧导航从 04 工程链入口开始，显示当前工作和已完成阶段；04–11 对应正文页码，不是独立的架构层级编号。 三幕直接衔接内容，不设置幕间分块页；进入价值回归后收起右侧导航。

13. 修改时保持现有叙事契约 调整文案、配色或卡片时，不得无意改变安装阶段职责、事实顺序、完成条件和恢复边界。 新内容先判断属于哪一幕、哪一页，再放入对应板块；技术细节必须落到少选择、少等待、真正完成和失败可继续的用户价值。

二、当前架构

01 封面：让开发环境标准化交付 02 用户：两类用户，一套环境标准 03 交互：一条命令收敛首次安装 04 工程链入口：简洁入口连接计划、获取、执行与提交 05 规划：目标展开形成唯一执行计划 06 获取：缓存优先，多类来源适配 07 规划：依赖图固化顺序并持续补位 08 执行：多维资源按阶段安全重叠 09 优化：动态分配兼顾吞吐与尾速 10 反馈：进度、资源等待与机器事件可解释 11 提交：验证完成条件并支持中断恢复 12 历史基准：保留单轮记录，区分当时工具集与当前配方 13 交付：一次选择形成可交付的开发环境

第 12 页数值保留 2026-08-05 的历史单轮记录和当时工具集，含 bot-compass，不表示 1.1.4 已重新测量。 当前 benchmarks/quality-install 已使用 bot-metric；比较本版时应重新多轮测量并归档报告。 依赖图、资源准入、动态分配与活动快照均为机制示意，不是当前完整配方或实际终端截图。

三、目录说明

index.html 13 页内容、页面结构、章节锚点和可访问性标记 styles.css 基础色板、字体和通用布局 layer-story.css 投影画布、阶段导航和共用版式 forge.css bot-forge 蓝色视觉、页面专属组件与覆盖规则，最后加载 app.js 阅读进度、顶部导航、后台工作导航和章节状态交互 README.txt 设计、运行、操作、维护、验收和部署约定

四、本地运行

cd ./docs/web python3 -m http.server 4170

浏览器访问：

http://localhost:4170/

网站是纯静态页面，不需要安装依赖或执行构建。修改 HTML、CSS 或 JavaScript 后刷新浏览器即可查看结果。

五、操作说明

上下滚动阅读完整汇报。 顶部导航可跳转到简单开始、工程化执行和价值回归三幕的首个内容页。 页面顶端细线显示全局阅读进度。 进入工程化执行后，右侧导航显示系统当前承担的工作和已完成阶段；点击阶段可直接跳转。 进入历史基准与交付页后收起右侧导航，避免遮挡正文。 页面元素进入视口时由下向上渐入，并以短间隔分批出现；首次出现后保持可见。 禁用 JavaScript 时仍可阅读全部正文，并使用原生章节锚点跳转。

六、维护流程

1. 先在 index.html 中确定新内容属于哪一页、哪个生命周期阶段。
2. 优先复用现有流程、卡片、状态块和资源图，不重复创建近似组件。
3. 基础颜色、字体和通用布局放在 styles.css；共用投影版式放在 layer-story.css；bot-forge 专属视觉与页面样式放在 forge.css。 保持 styles.css、layer-story.css、forge.css 的加载顺序，新增覆盖规则前先检查已有选择器。
4. 修改页面数量时，同步更新封面总页数、各页编号、CSS 页码后缀和本 README 的当前架构。
5. 修改章节 ID 时，同步更新顶部导航、后台工作导航和 app.js 状态映射。
6. 修改文案后检查标题下说明、卡片正文、指标和结论是否仍使用一致的字号层级。
7. 内容事实以当前源码、../../README.md 和 ../manual 为依据，不在网站维护第二套产品语义；机器事件名以 src/events.rs 为准。
8. 更新版本时同步页面标题、品牌栏和本 README；历史基准保留原始日期、工具集与测量边界。
9. 修改缓存、完成或恢复说明时，同时检查获取页、验证提交页和手册，保持身份校验、独立 Cargo Home、组件重试与人工处置边界一致。

七、验收要求

使用 1280×720 与 1440×900 桌面视口检查全部 13 页：

每页画布高度完整，底部内容不被裁切或下一页覆盖；低视口下可以纵向滚动阅读完整画布。 页面和任何内容块都没有横向溢出。 标题、命令和说明文字不重叠，关键正文在投影尺寸下清晰可读。 冷白、亮蓝与深蓝页面保持足够的文字与边框对比度，橙色与绿色状态含义一致。 顶部导航、后台工作导航和所有锚点可以正确跳转。 阅读进度、当前阶段和已完成阶段随滚动正确更新，进入第三幕后右侧导航正确收起。 禁用 JavaScript 后正文完整可见，原生章节锚点仍可使用。 历史基准保留原始日期、当时工具集与单轮限制，机制示意不被表述为当前实测。 浏览器控制台没有 JavaScript 错误或资源加载错误。 index.html、styles.css、layer-story.css、forge.css 和 app.js 均能从同一静态目录正常加载。

八、部署

docs/web 是独立的纯静态站点目录，可直接部署到 GitHub Pages、Cloudflare Pages、Netlify、Nginx 或任意静态文件服务器。 部署时将 docs/web 设置为站点根目录，并确保服务器默认返回 index.html；不需要复制 docs/manual，也不需要构建步骤。 网站使用相对路径加载样式与脚本。如果部署到子路径，应保持 docs/web 内部目录结构不变。