Coding Agent 工作流与长任务

• 任务状态持久化（目标、子任务、进度）的设计
• 已改文件与 diff 的落盘与版本管理
• Checkpoint 与恢复条件的判定逻辑

长周期 Agent 应采用"可恢复的状态机"而非单纯内存对话。核心是把状态写成结构化清单：任务目标（原始验收标准）、当前子任务、已完成/未完成步骤、已修改文件及其 diff、每次测试运行的 pass/fail 证据、访问过的工具结果。这些状态应持久化到磁盘（如 JSON/状态文件）并周期性打 Checkpoint，同时基于 git 提交每个通过验证的里程碑。恢复时先读取 Checkpoint 重建上下文，再逐项核对"目标是否仍满足、测试证据是否仍有效、已改文件是否与基线一致"，只有满足恢复条件（如测试仍通过、无冲突）才继续，否则回退到上一个有效 Checkpoint。

长任务最怕上下文丢失或 OOM 后从头再来，也怕恢复后基于过时状态做出错误决策。持久化状态 + 验证证据 + 恢复条件，让 Agent 能在任意点安全续跑，且恢复是"合并到已验证状态"而非盲目重放。

• 基于模块边界划分并行工作区（Worktree）
• 接口契约（API 签名、数据流）作为解耦边界
• 合并顺序与依赖关系的编排

并行前先做模块边界划分：按包/文件/服务维度把任务切到互不重叠的 Worktree，每个 Sub-Agent 独立分支工作，避免编辑同一文件。为解耦还须提前约定接口契约——模块间的函数签名、数据模型、消息格式先冻结，各 Agent 只对契约实现，不依赖对方内部实现。合并时按依赖拓扑排序：底层契约先合并并通过测试，再合入依赖它的模块；每批合并后跑集成测试，冲突时以"契约优先、一方重构"解决而非一方覆盖，避免多个 Agent 同时改同一接口。

并行收益来自"划分后互不阻塞"，而接口契约是让任务可并行、可单独验证的前提；合并顺序按依赖拓扑保证任何时刻合并进来的代码都能通过契约与集成测试，避免"全部完成后无法拼接"。

• 长任务拆解为有序阶段的必要性
• 每阶段产物的定义与准入条件
• 状态机如何阻止跳过关键步骤

把开发流程建模为显式状态机：Plan（形成实现方案与改动清单）→ Edit（按方案修改代码）→ Test（运行针对性测试验证）→ Review（对照验收标准与风格自查）→ Commit（小步提交）。每个阶段有明确的产物与准入条件：只有方案通过才进入 Edit，只有测试通过才进入 Review，只有 Review 通过才 Commit。状态机强制 Agent 不能从"读 Issue 直接跳到 Commit"，并在每个状态间校验前一步产物，防止跳跃式开发带来的未经验证的修改。用状态字段显式写入任务状态，便于审计与恢复。

跳跃式开发指 Agent 未理解需求就大改代码、改完不测就提交，产生大量返工。状态机把"必须验证"固化为结构约束，让每步可追踪、可回退，是工程化编码 Agent 的核心流程控制。

• 工具能力的最小权限裁剪（只暴露必要操作）
• 可信数据范围（哪些数据可被当作事实使用）
• 读/写分离与权限边界

接入时遵守最小权限：搜索工具只暴露 read 能力，Issue 工具区分"读 issue"与"改状态/创建"并默认关写，CI 工具只允许触发与读取有限状态而不允许改配置或删除。同时在 Host 端声明"可信数据范围"——明确哪些工具输出（如正式 CI 结果、主干代码）可被当作事实用于决策，哪些（如用户 issue 描述、第三方内容）只能作为参考，两者在提示中区分，避免注入内容被当权威。必要时对 Agent 可见的 MCP Server 做白名单，控制每次会话挂载哪些工具。

工具接入给 Agent 越权能力，若不加裁剪，一个恶意或误导的返回就能让 Agent 执行危险操作。限制能力（最小权限）+ 限定可信数据（区分事实与参考）是双层防护，既防越权也防注入。

• 计划批准与执行允许集的边界
• 超出计划范围的变更（路径、依赖、命令）需重新批准
• 危险命令的二次确认机制

计划批准的是"要做的事"，执行时若超出计划范围必须重新审批，具体包括：路径扩大（写入计划未指定的目录、向外访问敏感路径）、依赖新增（引入新 npm/pip 包、修改 lockfile）、以及危险命令（rm -rf、curl|bash、git push、生产部署、权限修改等）。实现上把这些操作归类为"高影响操作"，执行时不去匹配已批准计划，而是单独评估是否修改了计划边界；一旦越界或属于危险命令，就抛出审批请求，只有人工确认后才继续。除此之外，被标记 needsApproval 的命令或命令 allowlist 之外的执行都需二次确认。

计划批准只能覆盖"已知的改动"，而路径扩大、加依赖、危险命令是"新增风险"，必须动态重新评估。把"批准"绑定到具体操作而非笼统计划，才能防止 Agent 在计划名义下悄悄扩大影响面。

• 上下文压缩/摘要的信息丢失风险
• 验收标准与失败证据的持久化
• 压缩后锚定关键事实的机制

把"不可丢失的硬事实"单独持久化，而不是依赖对话摘要：原始验收标准、已发现的失败日志、已确认的约束应写入结构化的任务状态文件（而非只留在上下文）。压缩时采用"摘要 + 关键事实锚点"策略：摘要描述过程，验收标准与失败证据用原文/哈希保留，并在摘要中显式引用这些锚点。压缩后 Agent 先核对锚点再继续，若发现摘要与锚点冲突以锚点为准。必要时在关键节点触发"重新确认验收标准"而不是默默继续。

上下文压缩会丢失细节，而这些细节（验收标准、失败证据）恰恰是最重要的决策依据。把关键事实与过程摘要分离持久化，压缩后锚定硬事实，能防止 Agent"忘事"而把失败当成功或偏离需求。

• Plan Mode 与 Act Mode 的职责分离
• 计划产物的结构与可审阅性
• 执行准入条件与回退机制

Plan Mode 只做分析与规划，不调用写操作工具，产出结构化计划（改动清单、涉及文件、风险、测试策略），供人工审阅与批准。Act Mode 只有在计划被批准后才进入，且其执行范围被限制在计划内。执行准入 = 计划已批准 + 计划内每一项都有明确实现与验证；一旦执行中遇到计划外情况或验证失败，回退机制触发：回滚单个文件或整体回到最近 Checkpoint，重新进入 Plan Mode 调整计划，而不是硬闯。整个切换过程记录在状态中。

分离的本质是"先想清楚再动手"，把决策交给人工审阅，把改动限定在已批准范围。回退机制保证执行失败的代价可控，避免 Agent 在计划错误时继续放大错误。

• 任务切分与小步提交
• 提交边界（何时算一个逻辑单元完成）
• 合并策略与可审查性

通过任务切分实现小 diff：把大的功能拆成多个可独立验证的小步骤，每个步骤对应一个逻辑提交，ideally 每个提交只做一件事（可编译、可测试、可回滚）。提交边界 = 一个逻辑单元完成且测试通过，而非"写很多再一起提交"。合并策略上按依赖顺序合入，每个 PR 控制在可审查规模，必要时用分段提交（feature branch 小步提交 + 最终 squash 合并）。设定规则：核心文件单次改动超过阈值即要求拆分，并把 diff 大小作为 Review 门禁信号。

大 diff 导致审查困难、冲突和回滚风险高。小步提交让每个改动可独立验证与回滚，是 Agent 代码可维护、可审查的基础工程纪律。

• 渐进式引入（低风险→高风险）的路径
• 人工接管点与退出条件设计
• 监控与回滚信号

采用渐进式引入：先从低风险、低影响的仓库（如内部工具、非核心库、测试代码）试点，Agent 只做建议或带强制 Review 的改动；验证稳定后逐步扩展到核心模块。每个阶段定义"人工接管条件"：Agent 连续失败、测试大面积失败、产生预期外大改动、涉及敏感路径时自动暂停并转人工。退出条件 = 明确的指标（如 Review 拒绝率、回归率、事故率）超过阈值即回退到人工开发或降低 Agent 权限。同时保留一键回滚到 Agent 介入前的基线。

Coding Agent 是高风险变更，直接全线启用会在出问题时难以定位。低风险试点 + 明确接管/退出条件 + 可回滚，让引入过程可控、可度量、可逆。

• 重复失败/相同错误的检测
• 循环辨识（错误签名、状态不进展）
• 强制人工干预的停止条件

通过检测"状态不进展"来识别循环：记录错误签名（错误消息/堆栈哈希）、执行次数、上下文变化，若多次尝试错误签名相同或状态无实质进展（如 diff 无变化、测试一直失败），则判定为循环。触发后强制停止并人工干预：停止自动重试、输出失败摘要与已有尝试，交由人分析根因或调整方案，而不是无限重试。可设定最大重试次数与"相同错误计数"阈值，配合冷却时间（backoff）。

盲目重试既浪费 token 又可能掩盖根因。用错误签名与进展检测识别"原地打转"，一旦判定就中断并转人工，避免死循环消耗资源与延误交付。

• Worktree 隔离
• 分支/命名策略
• 隔离环境与资源边界

每个并发 Agent 使用独立的 git worktree 与独立分支，分支采用带任务标识的命名（如 task- -），避免共享同一工作目录导致文件覆盖。系统层面用容器/沙箱隔离每个 Agent 的环境（文件系统、网络、依赖），限制其可见范围。合并时通过接口契约 + 依赖拓扑排序批量合入，冲突用"契约优先、重开分支"解决。所有 Agent 共享只读基线，写操作仅发生在各自 worktree。

并发冲突的根源是共享可变状态。worktree+分支实现"各自独立写、协作合入"，隔离环境限制互相影响，使并发成为可并行的资源而非互相踩踏。

• 任务清单的明确化与范围限定
• 验收标准（可判定成功/失败）
• 失败告警与自动中止机制

夜间任务是无人值守，须高度收敛：任务清单必须是明确、枚举、有界的（如"运行指定测试、检查告警、生成报告"），禁用探索性开发；每个任务附可自动判定的验收标准（exit code、测试结果、输出文件存在与内容校验）。失败时分级告警：差异小可自动重试并记录，重大失败（测试破坏、风险操作）立即停止、回滚并告警到人的通道（pager/IM），绝不静默继续。危险操作在夜间任务中默认禁用或强加二次批准。

无人值守意味着任何错误都会无监督放大。明确清单 + 自动验收 + 分级告警中止，保证夜间任务要么按预期完成小工作，要么安全停止并通知人，而不是在无人时做危险操作。

• lastMessageId / resume 续传机制
• 避免重放整段生成的策略
• reasoning part 的"不可重放"特殊性与处理

断线后客户端携带收到过的 lastMessageId 发起 reconnect，服务端据此恢复未发送完的部分，只续传从断点开始的新内容，而不是重放整段生成；这要求服务端在生成过程中为每个消息/part 分配稳定 ID 并缓存未确认部分。对 reasoning part（思考过程），因其在续传时通常不可重新可见（模型不重放思考或敏感），服务端应把 reasoning 作为"已消费"处理，续传时只补传 text/tool 等持久 part，并向客户端说明 reasoning 不可恢复，避免 UI 错误地等待或重复显示思考内容。

重放整段会浪费带宽、造成 UI 跳动与重复，且 reasoning 本身不可重放。精确续传需要稳定的消息 ID 与增量缓存，配合"reasoning 不算可续传内容"的约定，才能保证断线后体验一致且不泄露敏感思考。

• 多 MCP Server 的工具命名冲突处理
• 权限边界的隔离
• 按需挂载与白名单

命名冲突通过工具命名空间/前缀解决（每个 Server 的工具名带 Server 标识，如 browser_click、fs_read_file），Host 层统一去重并路由到正确 Server。权限边界上，每个 Server 声明自己的能力与范围并走最小权限，Host 维护"Server→工具→权限"的映射，禁止跨 Server 越权（如 Filesystem 不能读 Sentry 的密钥）。必要时按会话按需挂载 Server，只有需要的才启用，降低暴露面。工具调用审计记录每个 Server 的实际操作。

多 Server 并存带来命名与权限两重问题。命名空间解决冲突，权限边界解决越权，按需挂载缩小攻击面，三者结合才能安全地编排异构工具。

• abort signal 只终止前端消费的局限
• 服务端取消生成与计费的实际语义
• 网关层 abort 传播与对账机制

前端 abort 只中断本地消费，服务端若不支持取消，生成仍会跑到结束并按已生成 token 计费。因此团队必须把 abort 传播到网关与服务端：前端把 abort 转成服务端取消请求（如 HTTP 取消、流中断），服务端据此向底层 Provider 发 cancel 请求，真实停止生成并返回已用量。为了让"停止计费"可验证，网关要记录每次请求的最终 token 用量与取消状态，做对账（reconciliation）：对比前端声明 abort 的请求与 Provider 计费账单，识别"已 abort 但仍在计费"的异常并核查。对不可取消的 Provider，应提前在成本上按已生成 token 预算控制。

abort 的语义从前端扩展到全链路才算真正停止计费。前端信号只是第一步，网关传播取消 + 对账才能确认 Provider 确实停止且账单一致，避免"用户点了停止却仍按完整 token 收费"。

• 统一任务与等价环境
• 能力维度定义（计划、执行、工具、沙箱、审批）
• 控制变量与可复现评估

用同一任务、同一环境、同一验收标准做对照，避免因工具差异或 prompt 差异造成偏差。先定义统一的能力维度：任务理解与计划、多文件编辑、工具调用、测试验证、审批流程、错误恢复、沙箱安全。把任务设计成可自动判定的（结果、测试、diff 质量），并控制变量（相同模型、相同 seed、相同上下文）。记录每个工具的执行轨迹、步骤数、成功/失败与人工介入次数，用一致的评分标准汇总，而非只看"是否完成"。

工具各有侧重，直接比较总分数不科学。统一任务 + 明确能力维度 + 自动验收 + 控制变量，才能得到可复现、可解释的横向结论，帮助选型。

• 强类型 part 的独立渲染器
• 断线续传标识与增量渲染
• schema 版本控制与顺序无关渲染

前端为每个 part 类型声明独立渲染器（一个渲染器只处理一种 part），渲染时按 part 类型而非固定顺序采用，保证 part 顺序变化不影响布局；每个 part 带唯一 ID 与续传标识，断线续传时据此做增量更新而不是整条重渲染，避免闪烁。同时为 message part 的 schema 定义版本号，客户端按版本解析，兼容不同模型的字段差异。渲染采用"keyed 更新 + 合并"而非"整体替换"，同一 part 只重渲染其内容变化部分。

不同模型返回的 part 顺序可能不同，若前端强依赖顺序或整段重渲染，会抖动闪烁。独立渲染器 + keyed 增量更新 + schema 版本，让渲染对 part 顺序与模型差异不敏感，体验稳定。

• 审批请求的渠道路由
• 租户隔离与权限校验
• 审批意图的上下文与防泄露

审批请求应携带租户与用户上下文，服务端在路由前先做权限校验：确认该用户在目标租户内、且对该操作有审批权限，路由到该用户已绑定的渠道（IDE 内通知、Slack、邮件）。跨租户隔离上，审批请求只发往该租户/该用户的渠道，消息中不包含其他租户的敏感信息，审批 payload 用租户级密钥加密，请求 URL 带一次性、有期限的 token 而非可重放的永久链接。审批回调校验 token、租户与操作哈希，防止跨租户的审批意图泄露或越权批准。

审批是多租户场景的高风险操作，路由错误会泄露租户意图或导致越权。租户校验 + 按用户渠道路由 + 一次性鉴权 token 与操作哈希绑定，保证审批只能被正确的人、在正确租户、对正确操作执行。