# Harness 工作流 > **🔄 重构进行中**：Agent Gate Loop 重构 schema 已就绪（37 新模块），运行时接入进行中。详见 [重构计划](AGENT_GATE_LOOP_REFACTOR_PLAN.md)。激活新控制平面（接入完成后生效）：`KCODE_GATE_RUNNER_V2=1`。 KCode Harness 按任务风险选择阶段模式： ```text quick discuss -> plan -> execute -> verify normal discuss -> spec -> plan -> execute -> verify -> ship ``` run 允许包含一条明确需求，或同一目标下的一组需求。 模式控制约束强度：`quick` 保留工作区安全、PLAN 批准文件、编码规范检查和验证记录，优先快速实现并进入 UAT 修复闭环；`normal` 启用完整业务事实、数据源、SDK/TDD 和 evidence 硬门禁。 ## 创建 run 使用显式产品参数： ```text /kd cangqiong 实现采购订单保存校验 /kd quick 更新 README 文档说明 /kd normal enterprise 第三方 WMS 对接 ``` 支持直接提供需求文档来源，例如本地文件、目录或在线文档链接： ```text /kd E:\project\docs\需求说明.md /kd https://example.com/requirements ``` 在线文档要求登录或权限时，KCode 会要求提供可访问链接、导出文件路径或关键内容。 直接输入自然语言需求时，KCode 会自动创建 run，并进入 `discuss` 阶段分析需求来源和范围。 已有未完成需求时，`/kd` 继续当前需求；`/kd <文本>` 创建新需求。 `/kd check` 刷新检查；检查通过时直接继续当前需求。 已有一需求只需补产品或流程强度时，可以直接输入 `/kd cangqiong`、`/kd enterprise`、`/kd normal`。 当前只有一个待回答问题时，`/kd <答案>` 会记录为该问题答案。 默认模式选择： - `quick`：文档、只读分析和低风险小改。 - `normal`：常规产品实现、第三方对接、SQL/KSQL、数据修复、外部系统验证、生产发布和高风险改动。 出现第三方对接、SQL/KSQL、数据修复、外部系统验证、生产发布或高风险改动信号时，KCode 会强制要求 `normal`。该要求是门禁和写入拦截，不是提示建议。 显式切换当前需求的流程强度： ```text /kd mode ``` 切换模式不能让当前阶段落到该模式之外。例如已经进入 `ship` 的 normal 需求不能切换到 quick。 查看当前状态： ```text /kd status /kd check ``` 产品未知时，查看 [产品画像确认](PRODUCT_PROFILE.md)。 ## 阶段说明 ```text discuss 梳理需求、产品版本、目标对象、边界和开放问题 spec 明确验收标准、数据对象、异常、性能和风险 plan 检查当前项目结构，记录真实目标路径、待改文件、查证项和验证命令 execute 只实现 PLAN.md 中批准的内容 verify 运行检查、构建或领域验证并记录证据 ship 汇总变更、验证证据、风险和后续事项；仅 strict 模式要求 ``` 推进阶段： ```text /kd phase /kd phase spec /kd phase plan /kd phase execute /kd phase verify /kd phase ship ``` `/kd phase` 只能推进到当前模式包含的阶段。检查不通过时，按 `/kd check` 给出的原因补齐产品、文档、计划、证据或风险说明。 ## 阶段文档 每个 run 会落地到： ```text .pi/kd/runs// ``` 主要文件： ```text RUN.json CONTEXT.md SPEC.md PLAN.md EXECUTION.md VERIFY.md SHIP.md evidence/ evidence/index.json events/ events/ledger.jsonl ``` `quick` 不生成 `SPEC.md` 和 `SHIP.md`；`normal` 使用完整文件集合。 创建缺失阶段文档： ```text /kd doc plan ``` `/kd doc` 默认不会覆盖已有阶段文档。确认要整体替换时必须显式使用： ```text /kd doc plan <完整内容> --replace ``` ## 待确认问题 产品、目标单据、插件位置、高风险 SQL 或方案选择要求确认时，KCode 会记录待确认问题。未回答的阻断问题会阻止阶段推进。 手动回答： ```text /kd answer Q-001 采购订单 ``` 批量问题组可以一次结构化回答，每行一个问题编号： ```text Q-001: SAL_SaleOrder Q-002: FBillNo, FQty, FEntity ``` 原则： - 提问必须使用 `kd_ask_user`；同一事实组内可一次登记多个独立问题。 - 问题登记后保持 open；用户回答后必须用 `/kd answer`、`kd_answer_user action=answer` 或 `Q-001: <答案>` 结构化文本记录。 - 已有 open blocking question 时，禁止登记、展示或继续追问新问题，必须先记录当前问题答案。 - 登记阻塞问题必须带 `contextSummary`；读取过文件、提取过逻辑或形成过设计判断时，必须用 `sourceRefs` 记录来源，防止用户回答后丢失上下文。 - 需要解除门禁事实缺口的问题必须带结构化 `factLabel`；确认题必须用 `proposedFactValue` 表示候选事实值。 - 同一 `factLabel` 已有 open 问题或当前事实时禁止重复提问；用户更正事实时使用 `kd_answer_user action=revise`，旧事实会标记为 superseded。 - 当前只有一个 open blocking 问题时，用户下一条普通短答会自动记录；占位答案不会解除门禁。 - 数据源 FormId、字段/实体、插件事件和读写方式必须来自结构化 facts 或 evidence；PLAN 自由文本不能单独证明这些事实。 - 得到答案并刷新门禁后，再决定是否需要新的事实组问题；禁止在自由文本中展开问题清单。 ## 恢复断点 KCode 会把阻塞问题的提问前上下文、来源文件、门禁原因和下一动作写入 run 级 `resumeSnapshot`。每轮 prompt 会通过 `control frame` 先注入恢复断点和本轮输入策略，再处理用户本轮输入。 执行规则： - 最新用户消息只作为输入事件，不能覆盖恢复断点。 - 当前存在 open blocking question 时，优先判断用户是否在回答该问题。 - 用户回答后必须先记录答案，再刷新门禁并从断点继续，禁止重新开始分析或重复询问已确认事实。 - 子 agent 输出、工具结果或新话题不能覆盖恢复断点；除非用户明确要求废弃当前任务或修订事实。 ## 控制框架 KCode 每轮会先生成 `control frame`，再生成给 LLM 的工作流 prompt。`control frame` 不是额外提示词，而是运行时状态的统一视图： - 当前 run、模式、阶段序列和门禁结果。 - 当前最高优先级焦点：Harness 一致性错误、未回答阻断问题、恢复断点、门禁阻塞或当前阶段任务。 - 当前结构化 facts 和上下文优先级。 - 本轮输入策略：用户最新输入只能被解释为回答、事实修订、停止/改需求、门禁证据或当前阶段输入中的一种。 - 本轮唯一最高优先级动作。 LLM 只能在 `control frame` 的焦点下解释用户本轮输入。用户最新消息、工具输出或子 agent 输出不能直接改写当前任务状态。存在 consistency errors 时，`consistency` 焦点高于 open question；唯一动作是修复 run state、ledger 或重新创建 run，禁止继续提问、计划、推进阶段或写代码。 ## 动作意图路由 KCode 使用 `src/harness/action-router.ts` 在每轮 control frame 中生成结构化动作意图。意图路由不是替代 LLM，而是先把用户输入归类为可执行动作，再决定该动作是否被当前焦点允许。 - 当前存在 open blocking question 时，普通短答路由为 `answer-question`；“先写代码/实现/修复”等会路由为 `write-code` 并被阻断。 - 明确“更正/修订/改成”路由为 `revise-fact`，要求写入结构化事实更正。 - “读取/搜索/查找”路由为 `read-context`，要求使用真实文件和工具结果记录上下文。 - “验证/构建/npm run/exit code”路由为 `verify-result`，要求记录真实验证命令和 evidence。 - 门禁阻塞或非 execute 阶段时，`write-code` 必须被阻断，返回唯一下一动作。 ## 上下文编译器 KCode 使用 `src/harness/context-compiler.ts` 统一编译每轮 prompt 上下文。prompt 渲染层只消费编译结果，不直接决定读取哪些状态、事件或阶段资料。 - 编译器先生成 `control frame`，再按焦点选择上下文预算。 - `blocking-question` 和 `resume-snapshot` 会保留更多 run.contextEntries 和 ledger 事件，优先防止问答后丢失已读文件结论。 - `gate` 会保留更多阶段产物和门禁相关上下文。 - `phase` 使用较小最近上下文，避免普通阶段输入被历史长文本淹没。 - 阶段文档、项目上下文和上下文条目都会截断并标明“完整内容读取本地文件”，禁止把截断内容当完整事实。 - 编译结果包含上下文预算报告，说明当前焦点、各类上下文的 available/selected 数量、字符预算和截断状态。预算报告只解释裁剪边界，不作为业务事实源；被截断内容必须读取本地文件、run artifacts 或 evidence 后才能引用。 ## Handoff Capsule KCode 使用 `src/harness/handoff-capsule.ts` 生成固定交接包，用于新会话恢复、子 agent 委派、上下文压缩后接续和问题复盘。交接包不是新的事实源，而是从 run state、control frame、facts、ledger、阶段产物和项目上下文编译出的只读恢复材料。 包含内容： - 当前 run、阶段、模式、门禁和唯一下一动作。 - control frame 和结构化动作意图。 - 上下文预算报告，用于确认交接包中哪些内容被裁剪。 - 必需事实契约缺口。 - 当前 facts、open/answered questions。 - 最近 durable context entries 和 ledger 事件。 - 近邻阶段产物摘要、项目上下文和不可违反规则。 入口： ```text /kd handoff [说明] ``` 子 agent 委派现在统一消费 Handoff Capsule，禁止各角色再拼装一套不同的上下文摘要。 ## 一致性检查 KCode 使用 `src/harness/consistency.ts` 检查 active run 状态链路，目标是发现“用户已回答但 facts 没落盘”“ledger 坏行被静默忽略”“open question 缺少恢复上下文”“gate 快照陈旧”等会导致 LLM 误判或丢上下文的问题。 通过 `kcode doctor --deep` 触发（仅本地诊断使用）。 检查范围： - `active-run.json` 指向的 run 是否存在且可加载。 - `RUN.json`、active run 指针和 ledger 中的 run id 是否一致。 - ledger seq 是否连续，ledger 行是否满足事件结构。 - open blocking question 是否保留 `contextSummary`；问题过多时提示焦点分散风险。 - facts 是否使用集中定义 `factLabel`，事实值是否为可核验内容。 - 已回答的 fact question 是否写入对应 `run.facts`。 - 当前 phase 是否属于当前 Harness mode。 - `run.gate` 快照是否具备有效结构；完整检查结果仍以 `/kd check` 和运行时 `inspectGate` 为准。 一致性检查只报告错误和警告，不做旧状态迁移、不从历史 question 反推 facts、不自动解除门禁。坏状态必须修正或重新确认事实。 ## 状态内核与上下文包 KCode 的运行状态必须先落到 run 状态内核，再由上下文包统一提供给 prompt。prompt 不直接承担状态推断、旧字段兼容或问答恢复职责。 - `run.contextEntries` 记录用户输入、文件结论、设计决策和约束，带阶段、类型、来源和时间。 - `run.facts` 是唯一结构化事实源；questions 只作为问答审计，不能作为门禁事实反推来源。 - `resumeSnapshot` 保存 open blocking question 前的恢复断点；用户回答后先写入 answer/fact，再刷新门禁。 - `workingSet` 保存当前焦点、当前缺口、唯一下一动作、最近工具涉及文件和禁止漂移规则。 - 问题登记、问题回答和事实修订必须同步刷新 `workingSet`；回答后不得继续保留“等待旧问题答案”的动作，仍有 open question 时必须指向下一个问题，否则切回 gate 或当前阶段。 - `toolResults` 保存结构化工具结果，包括工具名、状态、类型、路径、证据路径、风险和下一动作。 - `actionCommits` 保存每轮 control frame 的动作承诺，记录本轮意图、允许/阻断原因和 requiredAction。 - `writeTransactions` 保存写入事务边界，记录写入前网关检查、阻断原因和后置校验结果。 - `sourceAnchors` 保存 `kd_anchor_read` 生成的文件锚点快照；source-like 生产源码写入事务会用它阻断缺失或陈旧锚点的编辑。 - `buildWorkflowContextPacket` 统一组合状态、control frame、Working Set、工具结果、动作承诺、写入事务、Source Anchors、Plan Readiness、Deep Context、上下文条目、阶段文档、facts/question、项目上下文和委派策略。 - `workflowPromptForRun` 只消费上下文包并渲染工程指令；禁止在 prompt 组装层重新读取旧状态或追加并行语义。 - 阶段文档仍用于正式产物；上下文条目用于保持讨论资料和文件结论可见；Working Set 和工具结果用于保持操作线程；结构化 facts/evidence 仍用于门禁事实。 - 上下文条目、Working Set、工具结果和事件账本不替代 FormId、字段标识、接口字段映射等可核验业务事实；这些事实必须进入 `run.facts` 或 evidence。 - 不做旧状态迁移兼容；缺失 `contextEntries` 或 `facts` 时按缺失事实处理，坏状态只过滤。 ## Source Anchors KCode 借鉴 Hash-Anchored Edits 的核心思想，但不替换 Pi 原生 `read/edit/write`，也不污染普通读取输出。写入或编辑 source-like 生产源码前必须使用 `kd_anchor_read`： ```text kd_anchor_read path=src/Integration/MesApiClient.cs ``` 该工具输出 `line#hash|content`，并把文件整体哈希和行锚点写入 `run.sourceAnchors`。后续 `write`/`edit` 会先进入 Write Transaction： - source-like 文件没有匹配锚点：事务阻断，要求先读取锚点。 - 文件自上次锚点读取后未变化：事务继续。 - 文件已变化、行锚点陈旧或整体哈希不匹配：事务阻断，要求重新读取锚点。 - 写入完成后，`tool_result` 会执行后置条件并将事务记录为 `verified` 或 `blocked`。 Source Anchors 只证明“这个文件仍是刚才读到的版本”，不证明业务事实正确。FormId、字段、实体、接口字段映射、幂等策略和验收数据仍必须来自 `run.facts` 或 evidence。 ## Deep Context KCode 借鉴分层上下文初始化，但不在业务目录生成 `AGENTS.md`。`kcode` 启动时自动生成 `.pi/kd/DEEP_CONTEXT.md`。该文件按真实目录、源码根、模块和构建文件生成 KCode 专属索引。Context Compiler 会根据 Working Set 最近文件、工具结果路径和 Source Anchors 自动摘取相关目录上下文。 Deep Context 的边界： - 用于让 LLM 了解相邻目录约定、模块结构和验证入口。 - 不替代项目真实文件读取；编辑前仍必须读取目标文件。 - 不替代业务 facts/evidence；业务标识和验收数据仍走事实门禁。 - 不做旧目录规则兼容；索引过期时重新启动 `kcode` 即可刷新。 ## Plan Readiness KCode 借鉴“动手前先过脑子”的规划约束，将其合并为 Harness 内置 Plan Readiness，而不是新增平行 planner 状态机。 Plan Readiness 每轮随 Context Pack 注入，综合检查： - 当前阶段是否允许执行。 - 是否存在 open blocking question。 - 当前门禁是否通过。 - Required Facts Contract 是否仍有实现契约、数据源上下文或第三方对接缺口。 状态为 `not-ready` 时，唯一下一动作是处理第一项 blocker；禁止生成模板代码或直接写产品源码。状态为 `ready-to-execute` 时，仍只能修改 `PLAN.md` 批准文件，并继续受写入事务、Source Anchors 和当前模式门禁约束；`normal` 会额外要求 SDK/TDD/evidence 证据闭环。 ## Context Pack Validation KCode 使用 `src/harness/context-validation.ts` 在 prompt 发送前验证上下文包。该层用于发现状态链路断裂，而不是补业务事实。 - 缺少 Harness 状态、Working Set 或预算报告与 control frame 不匹配时，prompt 会被阻断。 - `focus=blocking-question` 时必须存在 open question，并且 question facts 必须展示未回答问题。 - `focus=resume-snapshot` 时必须存在恢复断点。 - ledger 有 `tool.succeeded` 但没有 Tool Result Contracts 时会产生警告，提示工具观测链路不完整。 - 验证失败时唯一下一动作是修复上下文包生成链路或 run state；禁止继续业务计划、提问或编码。 ## 必需事实契约 KCode 使用 `Required Facts Contract` 表达编码前必须具备的业务事实，不为单个场景写死提示词。 - `implementation`：实现契约，包括触发入口、源对象、目标对象、数据变化、业务规则、失败处理和验收样例。 - `integration`：第三方对接上下文，包括接口文档、方向/触发时机、接口地址/认证、字段映射、并发幂等、超时重试限流、错误补偿、日志脱敏和样例。 - `data-source`：业务数据源上下文，包括 FormId/单据或表单、插件类型和事件、字段/实体/分录标识、读写方式，以及 SQL/KSQL 表名和字段名。 契约评估由 `evaluateRequiredFactsContract` 输出结构化缺口，再由门禁和写入策略生成阻断原因。API 文档、SDK 文档和知识库不能满足这些业务事实契约。 ## 事件账本与工具观测 KCode 使用 append-only 事件账本记录 run 内关键观测。事件账本用于审计、重放、回归评估和 prompt 可见的最近轨迹，不作为业务事实源。 - 账本路径：`.pi/kd/runs//events/ledger.jsonl`。 - 状态变更事件由 `src/harness/state.ts` 和 `src/harness/repair.ts` 写入，包括 run 创建、上下文记录、问题登记、问题回答、事实修订、阶段推进、门禁刷新和验证结果。 - 输入和工具事件由 `src/harness/observation.ts` 归一化，再由扩展适配层调用，包括用户输入、自动回答 open question、工具拦截和成功工具观测。 - 成功工具观测使用 `tool.succeeded` 事件记录短摘要；文件查找、目录列表、文档读取和 PowerShell 命令会把来源摘要写入 `run.contextEntries`，防止“成功定位/读取后，一轮问答后忘记来源”。 - 工具成功或阻断会同步生成 Tool Result Contract，并更新 Working Set 最近文件、当前动作或阻断原因。LLM 后续必须复用这些工具结果继续当前工作线程，禁止重新猜测路径。 - Action Commit Log 记录每轮 control frame 给出的动作意图和 requiredAction。用户回答问题后，后续 prompt 仍会看到先前的动作承诺，避免回到“重新分析/模板编码”。 - 内部 workflow prompt 注入通过 dispatch gate 去重；同一 run、阶段和输入在短窗口内只能注入一次，避免自动推进、验证修复和命令处理重复投递过期控制帧。 - Write Transactions 记录写入前网关检查和后置条件结果。工作区外路径、非 execute 源码写入、open blocking question、open resumeSnapshot、execute gate 阻塞、缺失/陈旧 Source Anchor 和未通过后置条件的写入必须以事务阻断形式留痕。 - Windows PowerShell 覆盖工具只允许只读探索和验证命令；文件变更必须使用 `write`/`edit`，禁止用 `Set-Content`、`Out-File`、重定向、Remove/Move/Copy 等命令绕过写入事务。 - `workflowPromptForRun` 会通过上下文包注入最近事件，并明确标记为只读观测；FormId、字段、接口字段映射、幂等策略等仍必须来自 `run.facts` 或 evidence。 - `/kd log [数量]` 输出当前需求最近事件，用于排查“用户已回答但 LLM 重问”“工具失败后注意力漂移”“外部路径写入被反复尝试”等问题。 - 扩展层只能捕获平台事件并调用 observation API；不得在工具拦截点各自拼装独立日志或事实推断。 ## 工具网关 KCode 使用 `src/harness/tool-gateway.ts` 统一评估工具调用。扩展层只负责传入工具名、路径、当前 run 和子 agent 角色，然后执行网关返回的 allow/block 决策。 - 工作区外写入、Windows 路径提示、Office/PDF 文档读取重定向、子 agent 工具边界、产品源码写入门禁均通过同一网关判断。 - 工具拦截结果统一写入事件账本，避免路径策略、子 agent 策略和源码写入策略在不同扩展分支中分叉。 - 新增工具或新平台适配时，先接入工具网关；禁止在扩展事件处理器里复制一份路径或阶段规则。 ## 工具错误与后置条件 KCode 使用 `src/harness/tool-error.ts` 对工具失败分类，避免 LLM 把所有失败都当作“换个方法猜一下”。 - 网络：`network-timeout`、`network-proxy`，恢复动作是记录网络问题、检查代理或要求用户提供离线产物。 - 文件和环境：`path-not-found`、`shell-unavailable`，恢复动作是用当前环境工具重新定位，禁止猜路径或把子 agent 当 shell 替代品。 - 参数和门禁：`schema-error`、`business-gate`，恢复动作是修正参数、查询合法枚举或按门禁唯一下一动作补齐事实。 - 外部验证：`external-verification`，恢复动作是要求用户提供可核验证据。 KCode 使用 `src/harness/tool-postcondition.ts` 定义工具后置条件。当前作为核心评估模块和回归断言使用，后续平台提供工具结果 hook 时接入运行时： - 写入后校验路径在工作区内、源码写入策略通过、文件存在、没有模板占位内容。 - 读取后校验文件存在且不越出工作区。 - 后置条件失败必须按失败原因修复或回到 plan，不能把工具成功等同于任务完成。 ## Ledger Replay 事件账本可以生成最小 replay 场景，用于把真实坏例子沉淀成确定性回归。该功能仅通过 `/kd-internal replay` 内部接口使用。 ## 多个需求 查看历史 run： ```text /kd list ``` 切换 run： ```text /kd use <需求id> ``` 完成当前 run： ```text /kd done ``` 同一目标下的一组需求允许放在同一个 run 中处理。无关目标创建新 run： ```text /kd cangqiong E:\project\docs\本轮采购订单改造.docx ``` ## 写代码规则 KCode 会阻止过早写入 Java/XML/SQL/C# 等产品代码： - 未进入 `execute` 阶段不能写产品代码。 - `execute` 只能写 `PLAN.md` 中批准的真实源码文件。 - 临时发现要改新文件，回到 `plan` 更新计划。 - 必须理解当前业务项目已有目录、模块、包名、基类和本地封装后再编码。 - API 文档、SDK 文档和知识库只能作为技术用法证据，不能替代 FormId、字段/实体、插件事件、SQL/KSQL 表名、数据库字段名、字段映射、并发/幂等、日志脱敏和验收数据等业务事实。 - 信息不足时使用 `kd_ask_user` 登记当前事实组结构化问题；禁止生成模板代码或占位实现。 - 内部插件、自动下推、第三方对接、字段改写和数据同步统一按实现契约、数据源上下文和对接上下文补齐事实，不为单个业务场景写死提示词。 - 工具使用必须匹配当前环境。Windows 项目默认使用 PowerShell、`rg`、`Get-ChildItem`、`Get-Content`；禁止假设 bash 可用，禁止猜测路径；PowerShell 不允许执行文件变更命令。 - 产品源码写入统一通过 `action-policy` 检查；主 agent、子 agent 和工具拦截不得分别实现不同写入规则。 ## 项目持久规则 `kcode init` 和 `kcode ctx --refresh` 会生成 `.pi/kd/PROJECT_CONTEXT.md`。新会话必须先读取该文件，再计划或编辑代码。 持久规则由 `src/harness/prompt-policy.ts` 集中管理，并自动写入项目上下文。规则要求： - `run.facts` 是唯一结构化事实源，已回答 questions 只作为审计记录。 - `factLabel` 必须使用集中定义的事实标签或别名。 - PLAN 自由文本不能单独证明 FormId、字段、插件事件或读写方式。 - 外部系统操作、BOS 注册、人工功能测试和生产验证必须由用户提供可核验证据。 - 数据库访问优先通过 `kcode db` 配置成熟 MCP server；只允许元数据读取和只读查询，修改类 SQL、数据修复和存储过程执行只能生成脚本交给用户。 - 工具不可用时必须说明阻塞原因和需要用户执行的命令；禁止反复自述工具失败或用 `kd_subagent` 代替基础文件搜索。 - 不做旧状态迁移兼容或旧问题答案推断；坏状态只过滤，缺失事实重新提问确认。 证据和门禁细节见 [证据和门禁](EVIDENCE_AND_GATES.md)。 行为回归和 transcript/eval 规则见 [Harness 行为评估](HARNESS_EVALS.md)。 ## 子 agent 委派 KCode 支持把局部任务委派给隔离子 agent，用来降低长上下文带来的注意力漂移。主 Harness 仍是唯一状态机，负责阶段推进、门禁、证据和风险记录。 触发方式有两种： - 自动：主 agent 在大量调研、独立交叉审查、长上下文复盘或可并行拆分时，允许主动调用 `kd_subagent`。 - 显式：用户用 `/kd-review` 或 `/kd-delegate` 指定委派任务。 常用入口： ```text /kd-review 审查当前实现是否有门禁绕过和测试缺口 /kd-delegate research 调研采购订单保存插件相关代码 /kd-delegate doc 更新当前阶段文档 --dry-run ``` 角色边界： - `research`、`review` 默认只读。 - `doc` 只写明确指定的文档或阶段产物。 - `code` 只能在 `execute` 阶段运行，并且只能修改 `PLAN.md` 批准文件。 - `verify` 只读分析验证命令、失败证据和风险；实际命令和结果记录仍由主 agent 执行。 - 子 agent 不是 shell、read、grep 失败的替代方案；主 agent 必须先使用当前环境可用工具定位文件。 `--dry-run` 会预览发送给子 agent 的上下文包，用来检查上下文是否过长、是否包含不该交给子 agent 的信息。 工具层支持并行和链式委派。并行只允许 `research`、`review`、`verify` 这类只读角色；`doc` 和 `code` 必须串行执行： ```text kd_subagent tasks=[{"role":"research","task":"查找模型层"},{"role":"review","task":"审查门禁"}] kd_subagent chain=[{"role":"research","task":"找相关代码"},{"role":"review","task":"基于上一输出审查风险"}] ```