#让文档更新跟着产品发布走：用 HiFox 搭一条自动化文档流水线

过去，更新帮助文档和 Changelog 通常靠人工记忆：产品同学发消息，研发补充说明，文档同学再去翻任务、找截图、确认发布时间。

忙起来之后，最容易出现两种情况：

• 新功能已经上线，帮助文档却还是旧的；

• 做过很多修复和改进，但用户没有地方知道。

后来，我们尝试把这件事交给 HiFox 里的自动化 Agent：每天定时检查已经发布的任务，先生成“应该改什么”的方案，再交给人审核，最后由文档 Agent 完成修改、提交代码并推送预览分支。这套流程的重点，不是让 Agent 直接改文档，而是把“发现变化”和“决定怎么写”提前自动化，同时保留人工审核。

整个流程可以概括为：

扫描已发布任务 → 生成文档计划 → 人工审核 → Agent 撰写与提交 → 人工 Review → 自动部署

#第一阶段：先让 Agent 生成文档计划

#创建一个文档计划 Agent

这个 Agent 的职责不是改文件，而是回答一个更重要的问题：最近发布的功能里，哪些真正需要更新文档？

为了回答好，它至少要同时看到三类信息：Hifox 中的发布任务、对应任务的详情和讨论，以及代码仓库里现有的帮助文档与 Changelog。

第一步，让 Agent 从 Hifox 任务列表中查找给定时段内状态为“已发布”的任务。Hifox 更新速度比较快，所以我们把时间窗口设为过去 24 小时。后面生成计划时，所有引用都直接链接回原任务，审核人不必再手动搜索上下文。

第二步，让 Agent 阅读代码与现有文档。仅看任务标题，很难判断一个改动是否影响用户；代码可以帮助 Agent 确认真实行为，现有文档则能告诉它应该新增页面、补充某个步骤，还是只需要修改一段说明。

这里的关键是把“判断”和“撰写”分开：计划 Agent 只提出修改位置、修改理由和内容方向，不直接写入仓库。

判断帮助文档是否需要更新时，重点看“用户怎么做”。如果发布任务带来了新入口、新配置项、操作流程变化、权限变化或使用限制，通常值得更新帮助文档。

判断是否进入 Changelog 时，重点看“用户感知到什么”。重要的新能力、明显的体验改进，以及真正影响用户的修复，更适合作为对外发布记录。内部重构、监控调整和没有用户感知的工程改动，一般不需要写进去。

第三步，让 Agent 把候选项汇总为一个 Hifox 任务，并指派给文档负责人，同时加入需要知会的关注人。任务正文中应包含本次扫描的时间范围、建议修改的文档位置、每项修改的原因、对应发布任务的链接，以及可直接使用的 Changelog 草稿。

在创建任务前，再要求 Agent 做一次反向 Review：逐项检查这些发布任务是否真的值得修改文档，删除仅影响内部实现、没有用户感知或已有文档已覆盖的内容。

这一步很重要。它能避免“为了更新而更新”，让人工审核看到的是一份收敛后的计划，而不是未经筛选的任务清单。

文档计划 Agent 的 Instruction 可以写成：

1. 查找指定时段内状态为“已发布”的 Hifox 任务。2. 阅读相关任务详情、实现代码和现有帮助文档。3. 判断哪些任务需要更新帮助文档，给出修改位置、原因和方案。4. 判断哪些任务适合进入 Changelog，并起草对应内容。5. 汇总后再 Review 一次，移除没有必要的修改。6. 创建一条“帮助文档更新”任务，指派给文档负责人并添加关注人。7. 引用原任务时，任务名称必须带有可点击链接。

#用 Hifox 自动化每天运行

Agent 配好之后，把它接入 Hifox 自动化。

触发方式选择“定时”，每天在团队工作开始前运行一次；执行动作选择刚才创建的文档计划 Agent。这样，每天运行结束之后就会生成一个新任务，并指派给负责人。

为了让自动化稳定工作，Agent 需要拥有对应代码库的读取权限，帮助文档和 Changelog 也需要与代码一起存放在仓库中。这样它才能同时理解产品实现、文档结构和历史写法，而不是只根据任务描述猜测。

最好再准备一台团队共享机，安装并登录 Hifox，用于持续执行定时 Agent。共享机比依赖某位成员的个人电脑更稳定，也方便团队统一维护仓库权限、运行环境和自动化状态。

还需要处理重复运行的问题。最简单的方式，是在计划任务中记录扫描区间和已覆盖的发布任务，并让下一次运行跳过已经引用过的任务。

自动化的目标不是每天机械地产生一条新任务，而是在确实有文档变化时，稳定地产出一份可审核的计划。

#第二阶段：审核计划，再把任务交给撰写 Agent

#创建一个文档撰写 Agent

第二个 Agent 专注执行。

它不再自行决定“哪些功能值得写”，而是读取已经审核过的 Hifox 任务，根据其中的修改方案更新帮助文档和 Changelog。这种职责分离可以显著降低误改：计划 Agent 负责发现和分析，撰写 Agent 负责按确认后的范围落地。

撰写 Agent 的 Instruction 要尽量具体。除了帮助文档和 Changelog 的仓库目录，还应写明 Changelog 的风格规范、目标预览分支、提交与推送要求，以及修改范围限制。

例如：

帮助文档：
/apps/docs.hifox.com/content/docs

Changelog：
/apps/docs.hifox.com/content/changelog

根据当前 Hifox 任务中已审核的方案修改文档。
书写 Changelog 时，遵循仓库中的产品 Changelog 规范。
完成后提交并推送到指定预览分支，供负责人预览。
不要扩大任务范围；遇到信息不足时，在任务中说明并停止猜测。

“遇到信息不足时停止猜测”值得单独写进 Instruction。文档看起来比代码更容易修改，但错误说明会直接误导用户。一个可靠的撰写 Agent 应该知道什么时候执行，也知道什么时候把问题退回给人。

#日常只保留四个动作

自动化建立之后，团队每天真正需要做的事情会变得很简单。

1. 先查看 Hifox 中由计划 Agent 创建的任务，确认修改范围、优先级和表述方向。这里的 Review 重点不是逐字润色，而是判断这些产品变化是否值得进入帮助文档或 Changelog，以及计划有没有遗漏关键用户场景。

2. 计划确认后，把任务指派给文档撰写 Agent。Agent 会读取任务里的上下文和修改方案，进入代码仓库更新对应文件，并把结果提交到预览分支。

3. 接下来由人 Review 预览结果。重点检查三件事：事实是否准确，操作步骤是否真的可执行，Changelog 是否表达了用户能获得的价值，而不是简单复述内部实现。

4. 审核通过并合并后，交给现有流程自动部署。这样，从发布任务到线上文档，中间不再需要复制任务内容、手工寻找文件、重新整理背景和本地执行提交等重复动作。

在这个流程里，人并没有退出。相反，人的注意力被放在了更有价值的位置：判断哪些变化值得告诉用户，以及最终内容是否准确。任务搜索、代码与文档对照、草稿整理、文件修改和分支提交，则交给 Hifox 自动化与 Agent 持续完成。

#重构 AI-native 的研发协作工作流

真正有价值的不是“让 AI 写一篇文档”，而是把一个人配置好的文档工作流，变成整个团队每天都能重复使用的能力。

这套实践的核心不是追求全自动，而是建立一条可控的半自动流水线：自动发现、自动分析、人工确认、自动执行、人工验收、自动部署。每一步都有清晰的输入和输出，也都能在 Hifox 任务中追溯。

当帮助文档和 Changelog 跟着“已发布”状态自然流动，文档就不再是发布后的补作业，而会成为产品交付的一部分。

Hifox 的作用，也不只是运行一个 Agent，而是把任务、自动化、代码库权限和人的审核连接起来，让这套能力真正进入团队的日常工作。