代码变了，站点应该怎样跟着变

假设 ToolExecutor 新增了输出大小限制。站点不能只写“完善 Tool 安全性”，因为读者不知道限制发生 在何处、超限时看见什么，也不知道代码在哪里。

一次有用的文档更新至少回答：

1. 用户或调用方会观察到什么变化；
2. 这条规则处在执行路径的哪一步；
3. 初学者为什么需要它；
4. 开发者到哪个文件和测试验证；
5. 它没有顺便实现哪些相邻能力。

但并非每个 Feature 都需要修改每一种页面。准备关闭 Feature 时，先对工程 docs/、初学者路线、 开发者文档和当前状态逐项判断：有影响就写更新路径；没有影响就写 N/A 和具体原因。内部重构没有 改变用户路径、代码阅读入口或当前能力时，不需要为了完成清单改写站点。

学习页、架构页、开发者页各有任务

页面	读者正在问什么	合适的写法
学习 Agent	这个问题为什么存在，一次任务中会怎样发生？	用一个连续例子和必要术语解释
BearAgent 架构	哪个模块负责，数据和信任边界在哪里？	展示调用方向、责任和当前/未来边界
开发者文档	我怎样顺着代码读懂或修改它？	给文件入口、关键分支、失败路径和测试
当前状态	这个版本现在到底能不能用？	只写已有代码和测试支持的事实

不要把同一段工程记录复制四遍。学习页也不需要展示内部评审流程；开发者页更不应按 Feature 文件的 标题逐节改写，而要帮助第一次进入仓库的人建立代码地图。

例如，Reducer 内部提取一个私有函数但 Event、状态和测试入口都没变，可以这样记录：

Engineering docs: N/A - no contract or architecture claim changed
Site beginner: N/A - observable behavior unchanged
Site developer: N/A - code entry and execution path unchanged
Current status: N/A - no capability or limitation changed

从一个测试开始写，比从抽象结论开始更清楚

例如 test_timeout_calls_tool_once_and_does_not_retry 能直接告诉读者三件事：Tool 有 deadline，超时 返回稳定错误，Executor 不会私自再调用一次。可以先把这个可观察行为写出来，再解释为什么有副作用 的动作不能盲目重试。

不推荐只写：

ToolExecutor 提供可靠的超时语义和安全失败保证。

更清楚的写法是：

Tool 超过自己的 timeout_ms 后，Executor 返回 TOOL_TIMEOUT。同一次请求只调用 Tool 一次， 因为第一次是否已经产生副作用可能无法确认。

第二段可以逐项对照测试，也自然引出后续恢复问题。

更新开发者页面时实际检查什么

1. 用 rg 找数据类型、port、Runtime 实现和 adapter 的全部引用；
2. 找到 unit、contract、integration、security 中覆盖它的测试；
3. 从入口函数顺着成功路径读一遍，再顺着至少一个失败路径读一遍；
4. 标出外部数据第一次被验证的位置；
5. 标出会产生副作用、写 Event 或 commit transaction 的位置；
6. 写明哪些相邻模块仍未接通。

如果一个页面只能告诉读者“有哪些文件”，却不能解释一次数据如何经过它们，内容仍然不够。

当前和未来必须放在同一段附近

介绍规划能力时，不要只在页面顶部放一次总警告，后面就全部使用现在时。最好在相关段落直接写：

• “当前 SqliteEventStore 能在重开后查询事实；启动恢复尚未实现。”
• “当前 Policy 使用固定 allowlist；用户 Approval 尚未实现。”
• “当前三种模型协议 adapter 已由 AgentLoop 和 CLI 调用；DeepSeek V4 已完成一次真实 5/5，但不代表 其他服务或协议已付费联调。”

这样读者从搜索结果直接进入中间段落时，也不容易把设计当成已有功能。

外部资料用来拓宽问题，不替仓库作证

论文、官方工程文章和参考项目适合解释：为什么 Agent 需要评测、上下文为什么有限、Prompt Injection 为什么危险、长任务为什么要保存进度。BearAgent 当前做到了什么，仍要回到代码和测试核对。

引用外部资料时，优先集中在参考资料，正文说明借鉴点。不要因为某个项目 支持多个 Agent、浏览器或 sandbox，就把这些能力写进 BearAgent 当前架构图的已实现部分。

提交文档前的通读顺序

1. 从首页进入学习路径，确认没有突然出现未解释术语；
2. 从架构页进入开发者页，确认链接和同一概念的说法一致；
3. 单独阅读当前状态，确认没有被规划内容抬高；
4. 搜索旧术语、过期 Feature 编号和已经删除的页面标题；
5. 运行链接检查和站点构建；
6. 运行 uv run python scripts/check_governance.py，确认 Spec、Plan、ADR、索引和内部引用一致；
7. 连续读完改动段落，修掉机械替换留下的生硬句子。

文档的完成标准不是“每个工程文件都有一页”，而是第一次看代码的人能回答：数据从哪里来，在哪 校验，谁做决定，哪里发生副作用，失败怎样出现，以及哪个测试能复现。