新一代 AI 编程工作流——从飞书需求到 Hermes/Codex 可回放交付

灏仟亿前端技术团队
0 阅读12分钟

作者：泽哥｜灏仟亿前端技术团队

把 AI 接入研发流程，难点不在于“能不能写代码”，而在于让每一步都有明确边界、可追溯证据和人工决策位置。本文记录一套当前正在使用的编码工作流：协作平台负责接收需求和反馈，Hermes 负责控制面，Codex runner 负责执行，人始终保留关键闸门。

它不会让 AI 绕过既有工程流程直接改代码，而是把需求进入、项目识别、来源索引、计划整理、人工确认、实现、QA、合并测试、完成确认与经验沉淀固定为一条可审计链路。尤其需要明确的是：实现完成后不会自动进入 QA；QA、合并测试和最终完成都必须由人显式触发。

先说结论：控制面与执行面分离。

这套 workflow 的核心边界是：Hermes 负责控制面，Codex runner 负责执行，飞书等协作入口承载输入和状态反馈，人保留关键闸门。

各部分职责如下：

  • 飞书 / Hermes Gateway：承载 /coding、/commands、Coding Mode 输入和用户反馈；不直接执行代码，也不直接决定发布。

  • Hermes 插件：解析入口、维护任务账本、运行状态机、生成执行产物、调度 runner、回写状态；不亲自完成业务实现，也不把非结构化 runner 输出视作成功。

  • Codex runner：在指定 RunMode 下读取代码、修改代码、运行测试并输出结构化报告；不拥有项目选择、任务状态、协作平台写回和发布决策。

  • 人：确认计划、补充信息、接受风险，并触发 QA、合并测试和完成；不需要重复搬运上下文或执行证据。

  • Task Ledger：保存任务事实、状态、run、绑定关系、人工决策和合并记录；不承担长期知识沉淀。

  • Run Artifacts：保存每次执行的 prompt、manifest、日志、report、summary 和 diff；不充当任务状态库。

  • LLM Wiki：沉淀项目画像、草稿知识、run summary 和 QA 经验；不保存 token、真实运行根内容或实时状态。

1. 入口与命令

当前 Hermes 插件不会吞掉普通聊天。进入 coding workflow 的入口只有以下几类：

  • /coding <action>：人类显式命令入口。Hermes Gateway 归一化后，按 route metadata 分发。

  • /commands：Hermes Gateway 命令列表入口。

  • “进入 coding”：开启当前会话的 Coding Mode，之后的自然语言请求会进入 rewrite。

  • “退出 coding”：关闭当前会话的 Coding Mode。

  • 原生工具：Hermes 主 agent 优先使用 coding_* 工具；slash command 是面向人的 fallback surface。

命令控制器只会把 /coding action 归一为内部 route，例如创建任务、实施、QA 或合并测试，再由对应 executor 调用 host callback。

Coding Mode 也有明确约束：LLM rewrite 只能把自然语言翻译为候选的 /coding <action>；结果必须命中允许的 command catalog action。置信度低于 0.85、信息不足或 needs_human_review=true 时，Hermes 插件不会执行，而是转交 Hermes 主 agent。对于 destructive 或 needs_confirmation=true 的 rewrite，则先保存为 pending rewrite，等待用户确认。

当前任务、当前项目、最近任务、媒体和 command catalog 都会进入 rewrite context，但最终仍由 Hermes Gateway route 和状态机校验。

当前可用的 action

当前 command catalog 覆盖以下动作。

  • 查看与诊断包括：/coding help、/coding list、/coding status <task_id>、/coding doctor、/coding lark-preflight、/coding source-resolve <url> 和 /coding project-mcp-preflight。

  • 项目上下文包括：/coding project list、/coding project init <project_path_or_name>、/coding project use <project_name>、/coding project status 和 /coding project clear。

  • 任务绑定包括：/coding use <task_id> 与 /coding exit。

  • 创建与规划包括：/coding task <需求>、/coding run <task_id>、/coding analyze <task_id>、/coding breakdown <task_id>、/coding approve-breakdown <task_id> 和 /coding materialize <task_id>。

  • 反馈与变更包括：/coding continue <反馈>、/coding change <反馈> 和 /coding bugfix <反馈>。

  • 执行动作包括：/coding implement <task_id> 与 /coding qa <task_id>。合并测试和完成动作包括：/coding prepare-merge-test <task_id>、/coding merge-test <task_id> 和 /coding complete <task_id>。生命周期还包括 /coding cancel <task_id>。

其中，QA 的语义是“人工选择进入 QA；实现完成后不会自动进入测试”。prepare-merge-test 只记录人工准备动作，不会启动新的 implementation 或 QA。

Hermes 主 agent 可调用的原生工具包括任务创建、状态查询、任务执行、来源解析、协作平台预检、项目 MCP 预检，以及项目工作项搜索、创建、接入、WBS 和状态转换、缺陷接入等能力。涉及项目写操作时，工具 schema 和 service 都要求显式确认字段，例如 confirm_write。

2. 来源与项目上下文

来源 workflow 的重点是“把来源变成可恢复上下文”，而不是要求 Hermes 在创建 task 前必须读到正文。当前支持飞书 Project、Wiki 与 Docx 链接。

当消息包含来源链接时，Hermes 会索引 URL、token、项目 key、工作项类型、工作项 ID、读取命令和恢复动作等字段，并产出稳定的 SourceResult。如果来源正文尚未注入，计划阶段会把恢复动作交给 Codex session，让它根据 run context 中的读取命令获取正文。

预检会检查本地协作平台 CLI 配置、默认应用标识是否匹配、认证状态、Docx／Wiki／Sheet 的读取 scope。若 --verify 已证明凭据可自动刷新，needs_refresh 只作为 warning，而不默认阻断。

这个边界很重要：Hermes 不能因为自己没有提前读到正文就创建失败；Codex 也不能在只有链接时假设文档内容。读取失败时，runner 必须在结构化 report 中说明是授权、scope、网络还是工具问题，并给出恢复方案。

Feishu Project MCP：受控读写

项目 MCP 配置从本机运行配置读取。文档中只应引用配置位置和键名，不能写真实 token。

  • 配置位置：~/.hermes/coding-orchestration/mcp.json。

  • server ref：mcpServers.feishu-project。

  • token ref：mcpServers.feishu-project.env.MCP_USER_TOKEN。

  • 默认 domain：https://project.feishu.cn。

  • 默认 transport：stdio。

  • 默认 command：npx -y @lark-project/mcp。

项目 MCP adapter 默认只允许 read tools。写工具虽然存在，但必须通过 service 的确认参数控制；敏感字段如 Authorization、X-Mcp-Token 和 MCP_USER_TOKEN 形态的内容都会被遮蔽。

项目工作项与任务的绑定由工作项服务和身份对象维护。Project work item URL 会归一为稳定 key，其中包含 domain、space key、work item type 与 work item ID。intake sync 查到已有绑定时会复用既有 task，避免重复创建；bugfix intake 若能关联既有 story 或 root task，会继承 root branch，否则采用独立分支策略。WBS row 具有独立 identity，可绑定到子任务或交付拆解节点。

3. 主流程：从飞书需求到完成

当前 Hermes Gateway 的标准链路可以概括为：

  1. 接收飞书消息。

  2. 进入 pre_gateway_dispatch。

  3. 通过 /coding route 或 Coding Mode rewrite 识别动作。

  4. 由 TaskService 创建 task、绑定 active task，并索引 source。

  5. Hermes Gateway route 启动后台 plan-only。

  6. RunService 与 RunManifestService 生成 run 契约。

  7. RunnerRouter 选择 Codex runner。

  8. Codex 输出 report.json、summary.md、diff.patch 与日志。

  9. Hermes 校验 report、diff guard 和状态机 transition。

  10. Task Ledger、Run Artifacts 与 LLM Wiki 写入相应事实和摘要。

  11. 用户按需人工触发 implement、QA、合并测试与 complete。

关键状态不是一句“AI 完成了”，而是 TaskStatus 与 TaskPhase 的分层。

  • TaskStatus 描述业务任务下一步能做什么。例如 new、planned、running、blocked、ready_for_merge_test、merged_test 和 done。

  • TaskPhase 描述当前或最近阶段细节。例如 planning、plan_ready、implementing、qa_verifying、ready_to_merge_test 与 merged_test。

  • AgentRunStatus 描述单次 runner run 如何结束，例如 running、succeeded、blocked、failed、cancelled。

  • RunMode 描述本次 runner 被要求做什么，包括 decomposition、plan-only、implementation、qa 和 merge-test。

要特别区分：plan_ready 是 TaskPhase，而不是主 TaskStatus。plan-only 成功后，主状态是 planned，phase 才是 plan_ready。

4. 执行模型：RunMode、状态与策略

RunService.task_status_for_run_result() 的核心映射为：decomposition 和 plan-only 成功后，主状态进入 planned，phase 指向 plan_ready；implementation 与 qa 成功后，主状态进入 ready_for_merge_test，phase 指向 ready_to_merge_test；merge-test 成功后，主状态与 phase 都进入 merged_test。

失败或阻塞不会被硬转成功。非结构化输出会被投影为 blocked；timeout、runner failed、orphaned 等会投影到 failed 或 runner_failed 相关细节。取消的 task 不能继续启动 run，除非人工 restore；已有 active run 时，也不能重复启动下一次 run。

ready_for_merge_test 的中文展示是“等待手动执行 merge test”，merged_test 是“已合并 test，待人工完成”。两者之间仍有人工判断，不等同于 done。

Execution Policy：影响执行契约，不绕过状态机

Execution Policy 由执行策略模块归一化。Codex report 可给出 route、planning、context、implementation、verification、allow_browser_qa、require_human_confirmation、max_duration_seconds 等字段；缺失时使用标准变更策略。

当前实现会把 Execution Policy 写入 run context 和 manifest，用于在 prompt 中展示本轮动作与执行契约、根据 targeted verification 缩短 timeout、允许 inline planning 下的 implementation prompt 不依赖已确认计划产物，以及补充 run manifest 的权限、边界与审计说明。

它不是让 Hermes 跳过状态机的“自动驾驶规则”。implementation 仍要通过计划就绪与人工确认门禁，QA 仍需人工执行 /coding qa，合并测试也仍需人工执行 /coding merge-test。

5. 权限、workspace 与人工闸门

当前的 permission profile 按 RunMode 区分：decomposition 使用 decomposition_read_only；普通 plan-only 使用 plan_read_only；带未解析外部来源的 plan-only 使用 plan_source_read_elevated；implementation 使用 implementation_controlled_elevated；qa 使用 qa_controlled_elevated；merge-test 使用 merge_test_git_elevated。

plan-only 即使为了读取飞书、Swagger／OpenAPI 或私有 API 元数据而提权，也必须保持不写入项目文件。Hermes 的 diff guard 会审计计划阶段的写入。

implementation 会创建或复用 implementation workspace，并进入 gitops_preparing。QA 和 merge-test 必须使用已有 implementation workspace，缺失时直接阻断。QA 会准备 qa_checkpoint；merge-test 会准备 merge_test_checkpoint，目标分支是 test。

因此，runner 可以完成依赖安装、测试、浏览器 QA、git 元数据操作和 merge-to-test，但源码修改边界仍限制在 task workspace 内。

QA、合并测试与完成：人工作业闸门

workflow 的人工闸门是代码合同，而不是口头约定。

  • /coding implement <task_id>：计划就绪后启动 implementation；成功后进入 ready_for_merge_test。

  • /coding qa <task_id>：由人触发 QA，复用 implementation workspace；成功后仍保持 ready_for_merge_test。

  • /coding prepare-merge-test <task_id>：只记录人工准备动作。

  • /coding merge-test <task_id>：由人触发 merge-to-test；成功后进入 merged_test。

  • /coding complete <task_id>：在 merge-test 后由人标记为 done。

merge-test 对风险也有明确处理。它支持 --accept-risk 和 --confirm-qa-risk；blocked task 可进入风险评估，但缺 implementation run、缺 worktree、缺 source branch 或已取消仍属于硬阻断。缺 report、report 不完整、QA 缺失、浏览器受限、runner_failed、diff guard 越权等情况，都需要人工确认风险。人工放行后，风险细节仍应保留在 known gaps、verification limitations 与 merge record 中。

6. 长任务治理：拆解、回放与沉淀

需求拆解：父需求与执行任务分离

需求拆解链路包含：/coding analyze <task_id>、/coding breakdown <task_id>、/coding approve-breakdown <task_id>、/coding materialize <task_id> 与 /coding run <task_id> --next。

父级 requirement 保存原始诉求、交付拆解、验收口径、风险和整体进度；真正进入单项目、单仓库、单 workspace 实现链路的是 execution 子任务。拆解不等于直接创建代码任务：approve-breakdown 是人工确认，materialize 才将已确认的拆解物化为执行任务，run --next 只会选择依赖已满足的下一个 execution task。

Run Artifacts：每次执行都可以回放

当前 run 目录会围绕下列文件组织执行证据：

  • input-prompt.md：本轮给 runner 的入口 prompt。

  • run-instructions.md：RunMode 执行契约和报告要求。

  • execution-policy.json：执行策略。

  • run-manifest.json：task、run、workspace、权限、session、source、目标分支等事实。

  • report.schema.json：runner 结构化输出 schema。

  • report.json：runner 最终结构化报告。

  • summary.md：面向用户的可读摘要。

  • diff.patch：本轮变更证据。

  • stdout.log 与 stderr.log：原始执行日志。

  • run-log.md 与 events.compact.jsonl：Hermes 生成的精简操作记录。

  • wiki-context.md、context-index.json、confirmed-plan.md 与 implementation-context.md：按阶段生成的上下文 artifact。

PromptBuilder 不会把全部上下文塞进一条 prompt，而是把 Wiki refs、source block、confirmed plan、implementation context 和 run instructions 转成 artifact 引用，让 Codex session 按需读取。

Codex session 会在 manifest 与 task session 中记录 session_id、resume_session_id、attach_command 和 resume_command。后续的 plan retry、implementation、QA、bugfix 和 merge-test 可以优先续接同一 session。

LLM Wiki：长期记忆，不是状态库

LLM Wiki 写入的是可复用知识：project_profile 写入实体层，draft_knowledge 写入来源层，run_summary 和 qa_experience 写入综合层。运行状态、run 记录与 active binding 仍保留在 Task Ledger。

创建 task 时会写入需求草稿，run 完成后会把 summary 与 report 投影为 run summary。读取时，PromptBuilder 只取相关 Wiki refs 与上下文 artifact，不会把整个 Wiki 或运行根内容复制进 prompt。

这样划分是为了避免出现多个事实源：Task Ledger 回答“当前任务状态是什么、下一步能做什么”；Run Artifacts 回答“这一轮 runner 做过什么、证据在哪里”；LLM Wiki 回答“下次还能复用什么经验”。

7. 边界：当前明确不做的事

这套 workflow 只保留会影响执行边界和风险承接的“不做”项：

  • 不把协作平台或 MCP token 写进仓库、Wiki、prompt 或测试 fixture。

  • 不跳过人工闸门：implementation 不自动进入 QA，QA 不自动触发 merge-test，merge-test 成功也不自动标记 done。

  • 不让 runner 直接拥有协作平台状态机、Task Ledger 写入或 Project MCP 写回决策。

  • 不自动发布测试环境或生产环境。

这套流程的价值不在于让 AI 替代工程判断，而在于把工程判断放在可见、可审计、可回放的位置。当需求、计划、执行证据、风险确认和完成状态各归其位时，Codex 才能真正成为稳定的执行者，而不是不可控的黑盒。

8. 团队落地后的收益

该 AI 编码工作流在团队落地后取得了不错的效果。经测算，前端开发平均提效 44.9% ，前端产能平均提升 84.6% 。未来，灏仟亿大前端技术团队将继续保持 AI 编码工作流的创新性及领先性！

avatar
文章
阅读
粉丝