OctoDocsAssistant

解决什么问题 · Problem

文档腐烂是所有长期项目的宿命:代码改了文档没跟上,没人知道哪句还可信,交接包里的链接点开全是 404。

OctoDocsAssistant 把「事实」与「视图」分离:事实进账本,视图(产品概览、架构、近期变更、时间线、文档缺口、漂移报告、HTML 门户)随时可以 rebuild --from-ledger 重建;近期 commit 若没有同代码提交的文档会被标为疑似缺口;仓库里的 Markdown 与 commit message 一律按不可信数据对待,不会被当成指令执行。

怎么用 · How to use

核心命令一条链(README 中的真实命令):

octodocs init                    # 首次:初始化 .octodocs/
octodocs scan                    # 建立初始账本
octodocs update --changed        # 日常:编辑代码/文档后结算变更
octodocs review                  # 逐条 confirm / reject / ignore / pin
octodocs rebuild --from-ledger   # 验证视图可从账本完整重建

要把文档交给不持有仓库的人时:

octodocs package-handoff --out octodocs-handoff --zip --force

打包命令会复制文档视图、把源码链接改写为包内快照(_source_docs/)、生成 HANDOFF_GUIDE.md 并在 _HANDOFF_AUDIT.json 里记录链接核验结果。

适用场景 · When to use

• 长期项目的文档保鲜——把「文档说的」与「代码做的」的漂移显式化
• 新会话 / 新成员快速读懂项目(AGENT_HANDOFF.md 入口)
• 把文档打包移交给收购方、审阅者等不持有仓库的人
• 用 PROJECT_TIMELINE.md 追查哪些提交缺少同步文档