让 Hermes 接管文档同步：代码变了，文档也跟着变

很多企业不是不会写文档。真正的问题是文档没有进入软件交付流程。开发改了接口API 文档还停在旧版本。 数据库字段变了数据字典没人同步。 部署方式调整了运维手册仍然是几个月前那一套。时间一长团队真正敢相信的只剩代码。 文档反而变成“仅供参考”。所以这篇文章想讲的不是“用 AI 多写几篇文档”。而是另一件更实际的事让 Hermes 监听代码变化判断文档是否受影响再把文档更新变成一次可追踪、可审查、可回滚的研发任务。一、文档失效通常不是写作问题在真实项目里代码和文档往往是两套节奏。代码每天都在变修改 API ↓ 提交 Git ↓ Pull Request ↓ Merge但文档没有对应动作。于是几个月以后团队看到的是三套版本代码最新版 文档旧版本 实际部署又是另一套这不是某个开发人员不负责。而是流程设计上缺了一环代码变更没有自动触发文档同步。二、正确做法先判断再更新我不建议让 Hermes 每天扫描整个项目然后重新生成所有文档。这样成本高也容易覆盖人工维护内容。更合理的链路是代码发生变化 ↓ Hermes 接收事件 ↓ 文档影响分析 ↓ 是否需要更新文档 ↓ 创建文档任务 ↓ Document Agent 更新 ↓ 自动校验 ↓ 创建 Docs PR ↓ 人工 Review这条链路里最关键的不是“写”。而是先判断这次代码变化到底影不影响文档。例如修改内部变量名 → 通常不需要 调整内部算法 → 可能不需要 新增 API → 需要 修改 API 参数 → 需要 新增数据库字段 → 需要 修改部署方式 → 需要 新增配置项 → 需要只有这样自动化才不会变成新的噪音。三、Hermes 在这里不是“写文档工具”这个场景里Hermes 更像一个调度器。它把几件事串起来Git / Webhook ↓ Hermes Gateway ↓ Kanban ↓ Document Profile ↓ MCP 工具集 ↓ 文档仓库每一层都有边界Gateway负责接收 GitHub、GitLab、Gitee、Jenkins 等事件。Kanban负责把一次文档同步变成可追踪任务。Document Profile负责让专门的文档 Agent 执行分析、生成和校验。MCP 工具集负责读取代码仓库、文件系统、文档仓库、数据库知识和配置文件。最后变更不是直接写进主分支。而是生成一次文档 PR。四、最关键的一步文档影响分析不要让 Agent 一看到 PR 就改 Markdown。先让它产出一份Document Impact Report它至少要回答三个问题这次代码变更属于什么类型哪些文档可能受影响建议怎么处理例如某次提交是feat: 增加用户登录失败重试机制代码变化集中在auth/login.ts auth/retry.ts tests/login.test.tsHermes 分析后可能得出API 文档 → 无影响 架构文档 → 无影响 部署文档 → 无影响 认证设计文档 → 有影响 故障排查手册 → 有影响于是它只创建两个文档更新任务。这比“重新生成整个项目文档”靠谱得多。五、Document Agent 只能按规则更新进入更新阶段以后也不能让 Agent 自由发挥。它应该按固定流程执行读取上下文 定位修改点 生成更新内容 内容校验 生成 PR这里有一个底线AI 只能修改应该修改的部分不能覆盖人工维护内容。比如这些内容默认应该被保护人工维护章节 重要业务规则 公司制度说明 安全与合规内容 历史记录与决策这也是企业落地时必须坚持的一条边界。AI 可以同步信息。但企业知识库不能被 AI 随意重写。六、文档同步任务要进入 Kanban文档同步不应该是一次“黑盒执行”。它应该有生命周期Backlog Ready In Progress Review Done Blocked这样团队至少能看清楚哪些文档任务刚被创建哪些任务已经完成影响分析哪些任务正在更新哪些任务在等待人工 Review哪些任务因为信息不足被阻塞。这一步很重要。因为自动化不是为了让人完全不管。而是让人只管真正需要判断的地方。七、自动校验决定这件事能不能长期跑文档 PR 创建前至少要做几类检查格式校验 链接校验 示例校验 内容一致性校验 规范校验尤其是示例和链接。很多文档失效表面上是“内容过期”。实际打开一看是命令跑不通、链接打不开、API 示例和真实接口不一致。如果这一步不做自动生成只会加速制造新问题。八、为什么一定要保留人工 Review我不建议让 AI 直接改 main 分支。特别是这些文档架构文档 接口规范 生产部署文档 安全合规说明 业务规则说明更稳妥的方式是代码变化 ↓ Hermes 分析 ↓ Document Agent 修改 ↓ 自动检查 ↓ 创建 Documentation PR ↓ 人工 Review ↓ Merge人审的重点也不是逐字改文案。而是确认三件事AI 为什么改AI 改了什么有没有漏掉或误改。九、企业先从 5 类文档落地不要一开始让 Hermes 管所有文档。优先做这五类① API 文档 ② 数据字典 ③ 架构说明 ④ 部署手册 ⑤ 故障排查手册原因很简单。它们和代码、数据库、配置、部署环境关联最强。会议纪要、产品规划、制度文件这类内容不一定适合由代码变化直接驱动。先把高频失效的技术文档接住收益更直接。写在最后很多企业做知识库最后都会遇到同一个问题知识库不是没有内容而是没有人维护。Hermes 在这个场景里的价值不是“替人写更多 Markdown”。而是把文档更新接入研发流程Git ↓ Issue / PR ↓ Kanban ↓ Document Profile ↓ MCP ↓ 文档影响分析 ↓ 自动更新 ↓ 质量校验 ↓ Documentation PR ↓ 人工 Review最终实现的不是“AI 写文档”。而是代码和文档一起演进。这才是企业真正值得落地的 AI 文档管理。