Diverse Lab · Agent Runtime Engineering

从需求事件到代码变更：构建 Event-driven Coding Agent Runtime

当飞书或企业微信出现验收 Bug、PRD 发生变化，Agent 如何可靠地发现事件、分析影响、修改代码、验证结果并创建 PR？从 MCP、Webhook 到任务状态机与安全闭环的架构设计。

思路 2026-10-09发表 2026-10-09作者 chengguruchunAgent RuntimeMCPWebhook

研发自动化的下一步，不只是让 Agent 能写代码，而是让需求和验收事件能够可靠地触发代码修改，并用可追踪的工程证据证明结果。

一、先把 MCP、Webhook、Runtime 的边界说清楚

假设验收同学在飞书群里发出一个 Bug，或产品经理修改了 PRD。理想的系统能够发现事件、理解上下文、定位代码、修改实现、运行测试，并提交一个可审查的 Pull Request。这条链路可以称为 Event-driven Coding Agent：由研发事件驱动的编码 Agent。

但它不是“给 Agent 接上几个 MCP”就自然出现的能力。它至少包含三个问题：事件如何被发现、Agent 如何可靠执行、如何证明修改有效。

MCP 解决工具连接，Webhook 解决变化通知，Agent Runtime 解决任务执行与治理，验证系统决定结果是否可信。
层职责典型技术
事件源记录需求、Bug、测试和代码变化飞书、企业微信、GitHub、CI
Event Gateway接收、鉴权、规范化、去重和投递Webhook、长连接、轮询、消息队列
MCP / Connector让 Agent 查询或操作外部系统文档、GitHub、测试平台工具
Agent Runtime调度任务、管理状态、控制权限和恢复状态机、Scheduler、Checkpoint、Policy
Coding Agent理解代码、规划并提出修改Codex、OpenCode、Pi 等
Verification判断补丁是否通过工程约束编译、单测、集成测试、E2E、CI

MCP 是 Agent 调用工具的协议。它可以让模型读取 PRD、搜索代码、创建 Issue 或 PR，但通常不会自动告诉常驻服务“某份文档刚刚被修改”。Webhook 或事件订阅解决通知问题；事件到达后，Runtime 再调用 MCP 或系统 API 拉取完整上下文，启动任务。

系统可以同时使用 MCP 与 REST API：MCP 适合给 Agent 提供结构化工具；事件入口、鉴权、幂等和任务持久化等基础设施则不必强行做成 MCP。

二、飞书和企业微信：不要把群机器人当作万能事件源

飞书：文档事件与群消息需要分开设计

飞书开放平台提供事件订阅能力，也支持通过 WebSocket 长连接接收事件。云文档变更通知还受到订阅身份、文档类型和权限范围等条件限制，不能假设应用天然能看到企业内所有文档的所有变化。

建议分成两条通道：

  • PRD 通道：对有权限的文档订阅可用事件；若无法覆盖目标文档，就定时读取版本或内容摘要，发现变化后再做差异分析。
  • 验收反馈通道：通过应用有权接收的消息事件、反馈表单或明确的 Bug 卡片收集问题。提取消息链接、截图、复现步骤、期望结果和实际结果。

文档事件到达时，不要直接把整份文档塞给模型。先取得文档标识、版本或更新时间，再读取新旧内容，生成可追踪的变更集。

企业微信：先确认具体的消息接收能力

企业微信中的机器人 Webhook 常见用途是向群里发送通知，它并不自动等于“读取群里所有人的消息”。实际能否接收消息取决于应用类型、企业授权和所用接口。

更稳妥的 MVP 是使用标准反馈入口：用户通过表单、应用命令或指定流程提交验收 Bug，Runtime 获得结构化事件。若业务必须从现有群聊自动提取消息，则先验证当前企业微信应用具备相应的接收能力，再设计适配器。

事件源要有明确授权、可追溯的来源和稳定的事件标识；不要靠非官方抓取或不透明的群聊监听来构建研发基础设施。

三、统一事件协议：让不同入口进入同一个 Runtime

飞书消息、企业微信反馈、PRD 更新和 CI 失败的原始格式不同，但可以转换为统一事件：

type DevEvent = {
  eventId: string;
  source: "feishu" | "wecom" | "prd" | "github" | "ci";
  eventType: "bug_reported" | "prd_changed" | "test_failed";
  projectId: string;
  sourceUrl: string;
  occurredAt: string;
  actorId?: string;
  payload: Record<string, unknown>;
  correlationId?: string;
};

事件协议应该包含来源、发生时间、稳定标识和原始链接。PRD 更新还要包含文档标识、旧版本和新版本；Bug 则应尽可能保存复现步骤、截图、环境、期望结果和实际结果。

事件本身不等于修复任务。Runtime 需要先分类和归并。同一个 Bug 被多人重复反馈，或者 PRD 在短时间内连续修改，都不应该不加判断地启动多个并发编码任务。

  1. 接收：校验签名、身份和来源权限。
  2. 规范化：转成统一的 DevEvent。
  3. 去重：用 eventId、源系统对象 ID 和版本识别重复事件。
  4. 归并：关联已有 Bug、PRD 变更、代码分支和正在执行的任务。
  5. 持久化：先写入任务存储，再异步调度。
  6. 投递：由队列和 Scheduler 选择适当的 Agent 执行。

四、从事件到 PR：完整的执行状态机

RECEIVED → TRIAGED → CONTEXT_READY → IMPACT_ANALYZED
   → PLAN_APPROVED → SANDBOX_RUNNING → VERIFYING
   → VERIFIED → PR_CREATED → AWAITING_REVIEW

异常路径：NEEDS_HUMAN / RETRYING / FAILED

每个状态都应有明确的进入条件和失败路径。任务表至少保存 taskId、sourceEventId、状态、输入版本、代码基线 SHA、分支、尝试次数、Checkpoint、测试结果和 PR URL。任务状态必须由持久化存储驱动，不能只存在 Agent 的上下文窗口里。

  • TRIAGED：识别是 Bug、需求变化、重复反馈还是信息不足。
  • CONTEXT_READY：取得关联 PRD、代码仓库、测试结果和相关 Issue。
  • IMPACT_ANALYZED：列出受影响模块、接口、数据模型和测试。
  • PLAN_APPROVED：根据风险决定自动执行，还是等待人工确认。
  • SANDBOX_RUNNING：在隔离的分支和工作目录中修改代码。
  • VERIFYING：执行编译、单元测试、集成测试和必要的端到端测试。
  • PR_CREATED：附上来源、变更摘要和测试证据。

五、PRD 变化和验收 Bug，应该使用不同的规划策略

场景 A：验收发现 Bug

  1. 解析复现步骤、日志、截图和运行环境。
  2. 在本地或测试环境尝试复现，先确认问题是否稳定。
  3. 搜索相关实现、调用链、历史提交和测试。
  4. 优先添加能够复现问题的回归测试。
  5. 修改实现，执行相关测试和回归测试。
  6. 创建 Draft PR，说明复现证据、根因假设、修改内容和验证结果。

能复现、能通过测试和真正解决用户问题是不同层级的证据。 测试通过只是必要条件之一；如果问题依赖真实环境或外部设备状态，还需要对应环境中的验证。

场景 B：PRD 发生变化

  1. 获取新旧版本并生成结构化差异。
  2. 区分文案、UI、接口、数据模型、权限和业务规则变化。
  3. 将变化映射到语义依赖图或代码索引，找出受影响模块和测试。
  4. 检查新需求是否与既有约束冲突，缺少验收条件时先请求澄清。
  5. 生成影响分析和实施计划。
  6. 对低风险且边界明确的修改自动执行；权限、数据迁移、删除或不可逆副作用要求人工审批。
  7. 生成或更新测试，验证新行为及旧行为没有被意外破坏。

把 PRD 差异转化成“目标行为和验收条件的变化”，而不是直接把整份新 PRD 当成编码 Prompt。

六、Coding Agent 不等于 Runtime

Codex、OpenCode、Pi 等可以承担代码理解、修改和命令执行，但外围系统仍需控制任务生命周期。具体产品的 SDK、工具能力和部署方式可能不同，选型前应对照当前版本验证。

能力Coding AgentRuntime
理解需求与代码主要负责提供上下文
生成代码补丁主要负责限制写入范围
执行命令通过工具执行配置沙箱与权限
事件去重与归并不应依赖模型负责
审批与风险门控可提出建议强制执行策略
测试结果可信度分析失败原因保存真实工具结果
创建 PR可通过工具完成控制何时允许执行

我倾向于让 Runtime 保持编码 Agent 可替换。MCP 适配器提供统一工具接口，Coding Agent 承担具体实现，Runtime 决定什么时候运行、能访问什么、失败后如何恢复，以及什么条件满足后才能创建 PR。

七、推荐的 MVP：先做 Bug 自动修复，再做 PRD 变更

  1. 飞书通过指定反馈入口提交 Bug。
  2. Event Gateway 校验并持久化事件。
  3. Runtime 创建任务，取得代码和必要上下文。
  4. Coding Agent 在独立分支中复现并修复。
  5. 沙箱执行测试；失败时有限重试，超限则转人工。
  6. 验证通过后创建 Draft PR。
  7. 将 PR 链接、测试结果和失败原因回写飞书。

第二阶段再加入 PRD 版本检测、差异分析、代码影响图和自动回归测试。第三阶段再考虑跨仓库、多 Agent 并行、长期任务和自动化需求到发布链路。

建议评估事件接收率、重复任务数、自动修复成功率、人工验收通过率、回归缺陷率、单任务耗时、模型成本、人工介入次数、恢复成功率和安全策略拦截情况。自动创建 PR 是流程节点，不是问题解决的最终证明。

八、研发系统会形成自己的控制平面

  • Desired State：PRD、验收条件和业务约束定义希望系统变成什么样。
  • Observed State：当前代码、测试、运行日志和验收反馈描述系统实际是什么样。
  • Controller：Runtime 比较期望与实际之间的差异，决定是否启动修复任务。
  • Executor：Coding Agent 在受控环境里执行修改。
  • Verifier：编译、测试、CI 和人工验收提供证据。
  • Feedback：新结果回流到任务状态与需求系统。

它与 Kubernetes 控制器有相似之处：系统不是执行一次命令就结束，而是持续比较 Desired State 与 Observed State，并在满足策略的前提下推动状态收敛。

但软件需求比容器副本数更复杂：目标可能含糊、验收条件可能缺失、不同需求可能冲突，代码修改也可能产生新缺陷。因此控制平面不能只靠自动重试，还必须有需求澄清、影响分析、风险策略和人工决策机制。

未来更有价值的系统未必是最会写代码的 Agent，而是能把需求变化转化成可执行任务、把执行过程转化成可验证证据，并且在失败时可靠停止或恢复的研发 Runtime。

结语

我倾向于把这套系统拆成四个可替换层：事件适配器、MCP / 工具适配器、Coding Agent 执行器，以及掌握状态和安全边界的 Agent Runtime。

飞书或企业微信不需要理解代码；GitHub MCP 不需要承担长任务调度；Coding Agent 不应该决定是否可以绕过安全策略。每一层有清晰职责，整个系统才容易扩展、调试和验证。

第一步不是追求完全无人值守，而是把“一个真实 Bug 从反馈到 PR”的链路做到可追踪、可恢复、可验证。等它稳定之后，再让 PRD 的变化驱动代码演进，最终形成从需求、实现、测试到反馈的持续闭环。

参考资料