很多项目留下了大量聊天记录，却没有一个人能准确回答：现在做到哪里？哪个文件才是事实源？上一次为什么失败？如果换一个人或 Agent，应该从哪一步继续？
这不是“缺少总结”，而是缺少可执行的知识结构。
我在 OpenDeepWiki / AACR 项目里尝试解决的，不是让 AI 为代码自动写一批看起来完整的说明，而是让散落项目进入一个可验证、可恢复的知识流程。
文件系统是事实源，聊天只是线索
聊天很适合记录意图和临时判断，却会受到上下文截断、任务切换和版本变化影响。长期项目必须把关键状态落回文件系统：README、状态页、决策记录、验证报告、运行手册和变更日志。
这意味着一次任务结束时，不能只说“已经完成”。还要更新：
- 实际改变了哪些文件；
- 运行了哪些验证；
- 哪些结果通过、哪些仍然阻塞；
- 是否引入了新的依赖或风险；
- 下一位执行者从哪里开始。
当聊天与文件冲突时，应优先相信可检查的文件和运行证据。
导入项目之前，先缩小噪声与风险
一个真实代码项目可能包含 .git、依赖目录、缓存、模型、构建产物和秘密配置。如果原样送进文档生成系统，不仅浪费上下文，还可能泄露不该进入知识库的内容。
因此，导入流程先创建隔离副本，明确排除规则，再以只读方式挂载。先用一个小型自有项目做 Smoke，确认路径、编码、目录扫描和文档落盘都正常，再处理更大的代码库。
“能读到所有文件”不是优势。只读取完成任务所需的最小集合，通常更安全，也更容易得到高信噪比结果。
自动生成文档之后，还必须检查完整度
生成界面显示“100%”，不代表文档真的完整。一次长任务中，进度计数已经走到末尾，但数据库检查发现只有部分页面真正写入，其余任务因超时而没有持久化。
因此，验收不能依赖一个进度条。至少要交叉检查：
- 目录项数量与实际文档数量是否一致；
- 每个目录项是否关联了非空正文；
- 处理日志里是否存在超时、配额或写入失败；
- 思维导图、引用和跨页链接是否真实生成；
- 随机抽取的页面是否以源码为依据，而不是合理猜测。
自动生成只是生产步骤，完整度检查才是交付步骤。
失败记录应该能直接导向恢复
好的失败记录不是一段报错截图。它应该包含：失败对象、最后成功位置、已保存资产、缺失清单、可能原因、恢复前置条件和推荐命令。
在模型配额耗尽、长任务超时或工具调用不兼容时，我会先保护已经成功的文档和数据库快照，再把缺失页面导出为清单。下一次可以只恢复缺失部分，而不是覆盖此前高成本生成的结果。
这也是“可恢复”比“自动重跑”更重要的原因。无条件重跑可能花费更多成本，还会丢掉诊断现场。
轻量结构可以先解决 80% 的交接问题
完整知识图谱很有吸引力，但在底层图谱生成不稳定时，项目不必停在概念上。目录、文档链接、显式依赖、状态标签和完整度报告已经可以形成一个轻量图谱：人能看到模块关系，也能定位缺口。
先交付一个可验证的 v0.1，再逐步增加语义关系和自动推理，通常比等待“完美知识大脑”更有价值。
判断交接是否成功的一个简单测试
把项目交给一个不了解前情的人或 Agent，不补充口头背景，看它能否在合理时间内回答：
目标是什么？当前事实是什么？哪些已经验证？哪些不能宣称完成？下一步最小安全动作是什么？
如果它能回答并继续工作，文档才真正完成了交接。项目知识不是对过去的纪念，而是下一次行动的基础设施。