Agent-System-Dev/docs/superpowers/plans/2026-10-21-agent-stack-audit-remediation-plan.md

title, type, date, artifact_contract, product_contract_source, execution

title	type	date	artifact_contract	product_contract_source	execution
Agent Stack Audit and Remediation - Plan	fix	2026-10-21	ce-unified-plan/v1	ce-plan-bootstrap	code

Agent Stack Audit and Remediation - Plan

Goal Capsule

对 Agent-Native、Agent-Squad、Agent-Intent、Agent-Command 及其 Backend 接入做源码审查和外部协议核对，先修复现有能力的契约缺陷，再补充影响实际使用的功能。 本次交付是待用户审阅的方案；业务实现、迁移、部署和发布尚未授权或执行。 建议保留现有四库分层，分批兑现可验证结果，不重写 Agent 平台、不迁移到新的编排框架。

• 第一批：执行边界、失败结果、权限缓存、意图校验、命令回执、用户/项目配置。
• 第二批：持久化适配、队列限额、过程事件。
• 后续增量：多轮意图闭环、恢复诊断、目录召回、外部互通。
• 停止条件：批准批次的回归和适用组合验证通过，完成对应 Review、PR/CI 与收口；未批准增量不顺带实施。

Product Contract

Scope and Evidence

审查日期为 2026-10-21。以下 SHA 是本次实际检出；Dev 启动检查确认与当次远端 main 一致、组件无漂移，不能据此声称各组件远端没有更新。

对象	路径	审查 SHA
Dev	仓库根	d9e9c0560a2767539f4415b579adbeff86a22ba6
Native	deps/agent-native	2fc66be65201232ea38ba64d457efad5565d869d
Squad	deps/agent-squad	c7121bda2a681dc46078350f7929e56e142db57f
Intent	deps/agent-intent	651a2e1e03c4326888ef9f742ce592140ae30ab8
Command	deps/agent-command	4f583ca3eeeb07a56a714c5086de84dcd6ad2980
Backend	modules/backend	f084d10aa5ea2e4ad2ab4e6eb1268d3e83c6e991

发现以当前源代码及现有测试的检查为依据，均给出触发条件；不是线上事故结论，也不是穷尽性安全认证。 研究子任务报告了 Native、Squad 的本地测试和仓外探针；主线程已核对关键源代码，但未重放这些执行，也未将其导入正式 evidence，故本方案不以这些报告作为通过凭证。 修复回归、组合测试、GATE、独立 REPLAY、生产验收均为 NOT_RUN。 旧 N1/N2/N3、Q1/Q2/Q3 和 I1/I2 提案只用于理解历史意图，不把旧“已完成”或“待实现”表述当作当前事实。

Existing Responsibilities

模块	当前已有能力	应保持的边界
Agent-Intent	规则/守卫/预期、槽位验证、语义裁决、生成兜底、目录与诊断	识别和提出动作；不授予执行权限
Agent-Command	命令资产/注册表、危险分级、执行四态、审计信封	保持无 I/O；实际授权、执行、幂等持久化由宿主负责
Agent-Native	模型流、Agent 循环、工具/MCP、预算/取消、会话、checkpoint、外部适配	执行一次受约束任务；路径授权不冒充 OS 沙箱
Agent-Squad	规划、图调度、leader、HITL、黑板/邮箱/移交/任务板、存储与队列适配	协作与步骤推进；依赖注入执行器，不复制单 Agent 内核

这些库并非一条固定串行流水线：普通对话可以直接执行 Native，系统命令由宿主消费 Intent 并经 Command 受理，多步任务才进入 Squad。 真正的问题集中在边界传递和失败路径，而不是缺少更多拓扑或工具数量。

Findings

严重级别按触发后的影响排序，生产暴露面另列。P1 不表示已观察到线上损害。 下列行号是本次基线定位，实施时还须按符号及新基线复核。

ID	优先级与触发条件	源码证据	后果与影响边界
F01	P1：reasoning 请求的 Targets 含 ../ 或指向根外的符号链接	Native adapters/native/backend.go:324-333 先直接写文件，后续才做交付校验	可先写出工作区再返回失败；应在任何副作用前拒绝非法目标。上层自行校验可降低暴露，不能代替库契约
F02	P1：同一 WorkDir 被不同 ContractRequest.SessionScope 复用；或设置 Workspace.Writable	Native adapters/native/contract.go:42-51 未映射这些约束；backend.go:260-273 使用固定 transcript，仅记录字符串 scope	跨 scope 上下文串读及写集约束失效。当前 Backend 未发现 Contract() 消费，不据此断言产品跨租户泄露
F03	P1：ExecConfig 已启用解释器但 Env 为 nil	Native runtime/tools/exec.go:25-26,139	nil 被交给 os/exec，继承宿主环境，与完整白名单合同不符。Backend 当前解释器装配显式给出 env，该具体入口已有缓解
F04	P1：崩溃留下半截 JSONL 尾行，随后续写	Native runtime/session/tree.go:155-181,194-207	Load 只在内存忽略尾行，Append 紧接损坏字节；下一次读取变为中段 JSON 错误。完整 JSON 无换行也需处理
F05	P1：Executor 成功仅含 patches、失败带 patches，或 running 步骤崩溃后自动恢复	Squad squad/workflow.go:403-418,455-464、squad/engine.go:1055-1109	正常路径成功未物化而失败、失败可被提升为成功；恢复路径文件齐全即判 completed，缺文件则直接重跑，未核对可信终态和外部副作用。Native 自行落盘只能掩盖其中的成功物化问题
F06	P1：同名 role/model/backend 的权限或并发配置更新	Squad squad/backend.go:38-48,86-123；adapters/native/register.go:104-106	缓存键忽略 BashPermission/其他配置，Register 也不清缓存；allow→deny 后可能继续复用旧执行器。产品每次新建 resolver 可缓解，长期服务/公共库使用仍受影响
F07	P1：调用方修改注册输入或公开返回的嵌套对象	Intent intent/fold.go:37-57、registry.go:289,494,531,557；Command registry.go:60,98,107	Intent.Action/Examples 与部分目录数据、Command.ParamsSchema/ExposeAsTool 共享引用；可在 revision/锁之外改变已验证定义。这是同进程 API 合同缺陷，不等于任意远端用户已能修改
F08	P1：启用意图生成兜底，并返回缺槽/非法槽值或异名 Action	Intent intent/recognizer.go:333-414、catalog.go	生成路径未共用完整槽位校验，Top 丢风险/确认/动作元数据，handler 槽位查表键不一致；显式 Action 的合法异名目标又会被拒。Backend 开关 runtime.intentGenerator 默认 false
F09	P1：规则识别到非法槽位，宿主收到 Start + Clarify	Backend internal/intentgate/gate.go:167-178、internal/route/route.go:66-72、internal/server/server.go:1206-1230	InvalidSlots 被丢弃，Router 只取 Start。命令入口还只传 text，未传已识别槽位；可能误路由或被后续 schema 拒绝。不能据此断言任何高危命令都能绕过 cmdbus 确认
F10	P1：handler 已有副作用后报错，或成功后审计存储失败	Command result.go:41-43；Backend internal/cmdbus/cmdbus.go:433-438,539-559	任意 handler error 被归为“无副作用 rejected”；审计失败改 unknown 却丢已生成 op ID，且库禁止 unknown 携带 ID，影响对账及安全重试
F11	P1/P2：使用 SQLiteStore 保存协作状态，或在 async/on_exit 模式退出时 checkpoint 失败	Squad adapters/sqlite/runstore.go:77-119；squad/workflow.go:41-53	Mailbox/Handoffs/Board 未持久化；相同 JSON 文本作 map key 会覆盖解码目标；flush 错误被吞。Checkpoint 失败不等于已完成外部动作回滚，应单独报告持久化失败
F12	P2：同一 runtime 下多个 agent 同时或连续领取任务	Squad adapters/sqlite/queue.go:226-239	只数 agent 的在途任务，取两种 cap 的最小值不能限制 runtime 总并发；当前产品是否启用该独立队列须在实施时核验
F13	P1：当前用户/项目有独立模型路由配置，进入 Squad	Backend internal/app/app.go:340-364、internal/runtime/squad_runner.go:83-95、internal/runtime/llm.go:604-608	小队从默认账户/空项目读取 base/key 等，入口只覆盖 model，可能把用户模型名与默认端点/凭据混用；ReasoningSplit、RouteContract 也与 direct 路径不一致
F14	P2：小队同名工具多次调用，或工具返回错误	Native runtime/loop.go:43-45,777-836、adapters/native/backend.go:405-418；Squad squad/port.go:66；Backend internal/runtime/squad_runner.go:49-54	CallID 在旧过程契约中丢失，宿主用工具名代替；结束事件实际文本在 Text，宿主读 Detail 并恒写 ok。结果归属、摘要与成功状态失真
F15	P2：执行工具输出大量数据；或 Contract 调用要求纯文本	Native runtime/tools/exec.go:149,175、adapters/native/contract.go:25,67-77	CombinedOutput 先全量缓冲再裁剪，64KiB 只是展示上限；声明 CapText 却不填 Text。分别并入 U1、U2 的合同修复
F16	P2：使用 A2A adapter 接入符合 1.0 的外部服务	Squad adapters/a2a/card.go:24-46、executor.go:19-25,135,171、conformance_test.go	声称 1.0，却仍用旧 message/send、tasks/get、小写状态与旧 Card；测试假服务复制了同一套自定义结构。当前 Backend 无该依赖，不阻塞本地核心修复，但不得声称 1.0 互通已验证

Requirements

执行与权限

• R1. 不合法路径/写集/会话身份必须在模型或工具副作用发生前拒绝；支持空约束的既有兼容语义。
• R2. 后续运行采用新的权限配置；不能因旧缓存或错误配置作用域扩大能力或混用用户凭据。
• R3. 失败、取消、不确定、已完成保持真实语义；文件存在不是成功证据，未知不能无条件重试。

输入、恢复与可核对性

• R4. 规则与生成路径共用权威动作定义和槽位验证；缺失/非法/歧义必须保留到宿主。
• R5. 状态快照和注册表对外隔离可变数据，读者不能绕过更新协议改变定义。
• R6. 恢复后保留协作状态，保存失败可见；runtime/agent 并发上限独立生效。
• R7. 回执保留可信关联标识；事件保留工具调用身份、真实错误和实际输出；用户可分辨完成、等待与待核对。

功能增量

• R8. 在已批准修复收口后，单独选择下一批功能；不把提案中的全部建议自动视为实施范围。

---

Planning Contract

Technical Decisions

• KTD1. 保留四库边界和现有 Go 模块；通过当前接口增量修复。现有功能覆盖足够广，整体重写会扩大兼容性与验证成本。
• KTD2. 识别输出只作为动作建议。执行时按当前 actor/project 授权、命令 schema、确认凭证再判断；目录可见不代表允许执行。MCP 对工具 annotations 的不可信要求也支持这一边界，见 S1。
• KTD3. 以宿主当前运行的有效配置构造 model/base/key/协议及完成性规则，作为同一配置快照传入；不随意开通新的 provider 协议。工具权限可在执行前进一步收紧，不能由旧构造缓存恢复。
• KTD4. 先验证执行结果，再物化候选文件，再做交付检查；失败候选可以作为诊断保留，但不得发布为成功。结果 Unknown 与可重试性分别判断，不把 HTTP/网络错误等同于“尚未执行”。
• KTD5. Native 会话和 Squad 协作状态分别在原有存储上修复。检查点、工具副作用和产品聊天历史是不同记录；不新增统一分布式执行平台，不承诺跨外部系统 exactly-once。恢复设计参考 S2 的线程状态/跨线程存储区分。
• KTD6. Command 保持无 I/O。扩展可表达副作用不确定性的 handler 结果，并复用宿主已有 operation/outbox 存储；unknown 可携带已可信生成的 ID。可查询操作记录与权限检查必须真实存在，不能只改枚举注释。
• KTD7. 两个四态合同不强行合并：Command 描述动作受理/生效，Native 描述 Agent 执行终态；Squad 通过适配保留差异。命令 accepted 不是 Agent succeeded，创建确认卡也不是业务动作完成。
• KTD8. A2A 先明确支持版本并以官方独立 fixture 验证；需要兼容旧协议时显式分版本，不把旧协议重新标成 1.0。是否投入完整互通是后续增量决策，见 S3。

Component Flow

flowchart TB
  U[用户输入] --> H[Backend 身份与项目上下文]
  H --> I[Intent 识别与槽位验证]
  I --> C[Command 宿主授权与确认]
  I --> W[工作流或 Squad 编排]
  I --> N[Native 单 Agent 执行]
  W --> N
  N --> T[经授权工具与外部能力]
  C --> O[操作记录与回执]
  T --> E[真实结果与过程事件]
  W --> S[协作状态与 checkpoint]
  E --> H
  O --> H
  S --> H

这张图表达边界关系，不要求所有输入都逐一经过四个库。

Outcome Flow

flowchart TB
  R[请求] --> V{授权与参数有效}
  V -->|否| X[Rejected: 未开始动作]
  V -->|是| P{需要确认或异步处理}
  P -->|是| A[Accepted: 保留可查询 ID]
  P -->|否| E[执行动作]
  A -->|授权确认或继续| E
  E --> F{结果及记录是否确定}
  F -->|已完成并可核对| C[Committed 或执行 Succeeded]
  F -->|明确失败| D[Failed 或有依据的 Rejected]
  F -->|无法确认| Q[Unknown: 保留 ID 与待核对原因]
  Q --> Z[查询与对账: 禁止盲目重放]

取消请求同样需要确认执行侧状态；不能只因为本地 context 结束就声称远端动作已停止。

Delivery Order

第一批建议 U1-U7、U10：其中 U1-U4 先修 Native/Squad 执行与恢复基础，U5-U7 处理输入/命令合同；U10 的当前用户/项目配置问题与它们并行处理，不排在可选存储适配之后。 第二批 U8、U9、U11：恢复适配、队列和事件一致性。 每个批次在组件兼容提交落地后更新 Backend 嵌套 gitlink 和 Dev 组合指针，完成一次适用组合验证。 同批只读研究可以并行；每个仓库写入单元按 AGENT-EXECUTION.md 新 session、受控 transport/admit 进入候选，由 host 验证与交付。

实施前重新确认当前代码、在途任务与远端分流；本文不会覆盖后续已修复问题，也不会复用过期 CI 结论。 迁移脚本可以在隔离测试库验证，真实数据迁移、部署和发布另走授权边界。

---

Implementation Units

U1. Native Workspace and Process Boundaries

目标：修复 F01/F03 及 F15 的输出缓冲问题，落实 R1。 文件：deps/agent-native/adapters/native/backend.go、runtime/tools/exec.go、现有 runtime/tools/jail.go/atomic.go；测试放 adapters/native/backend_test.go、runtime/tools/exec_tools_test.go。 方案：复用已有工作区路径解析，目标在执行前预检，实际访问仍校验根内与 symlink；Env nil 归一为空白名单；子进程持续 drain 到有界头尾缓冲，不在结束后才限制内存。 验收：合法目标正常产出；../、绝对路径和 symlink 逃逸在零外部写入前拒绝；nil/空/显式 env 分别验证；大输出与取消后子进程退出且缓冲有界。 不把工作区路径检查描述为完整 OS 沙箱；并发敌对文件系统场景优先复用可提供根约束的文件 API。

U2. Native Session and Contract Fidelity

目标：修复 F02/F04 及 F15 的 CapText，落实 R1/R3/R6；依赖 U1 的文件访问边界。 文件：deps/agent-native/adapters/native/contract.go、backend.go、runtime/session/tree.go、exec/contract_spec.go；测试放 runtime/session/tree_test.go、adapters/native/contract_regression_test.go（新增）及 conformance/。 方案：将非空 SessionScope 绑定存储身份并在恢复前检查，Writable 限制贯穿可约束的文件工具；对于进程/MCP/宿主工具等无法兑现该写集的配置，本批在 preflight 明确拒绝非空 Writable，不假定根路径检查能限制任意进程。独占追加时修复半截尾记录/补齐合法无换行记录；中段损坏仍报错。保留真实文本输出，纯文本任务不强制隐式文件交付。 验收：同 root 不同 tenant/project/session 不串上下文；已有匹配 scope 可继续；身份不明的旧文件不得自动归给新身份；只允许写指定路径；半截尾行恢复后可再读再写；纯文本成功的 Text 非空。 兼容：空 scope 保持既有一次性/旧门面语义，不进行全库存量会话迁移；历史缺身份记录只在明确兼容路径读取。

U3. Squad Execution Results

目标：修复 F05，落实 R3；无先行依赖。 文件：deps/agent-squad/squad/workflow.go、leader.go、engine.go 的 recoverInterrupted、port.go、步骤状态持久化及 step_retry.go、adapters/native/register.go；必要的 deps/agent-native/exec/backend.go 与适配器映射；测试 squad/step_retry_test.go、squad/recovery_test.go、squad/attempt_test.go、squad/executor_result_contract_test.go（新增）。 方案：按 KTD4 统一普通步、IntentRunner 和 leader 委派的结果处理；显式处理 (nil,nil) 与物化错误。已有文件只能帮助诊断，不能覆盖执行器终态。 当前旧 ExecResult/exec.Result 只有 Success/Retryable，不能承接 Unknown/SideEffects。本单元先以兼容新增的可选字段或等价的类型化错误保留这些信息，再让 retry 层消费；缺少副作用证明的失败默认禁止自动重放，不能继续只按错误文本推断可重试。已有明确未派发或纯读取失败仍可有界重试；无需在本批整体替换所有 Executor 接口。 恢复入口同样消费持久化的终态与副作用证据。running 崩溃后，只有可信完成记录才能恢复为 completed，只有明确未执行或安全重放证据才能转 pending；其他情况保留待核对原因，禁止自动推进，沿现有中断恢复/HITL 入口处理。无交互模式明确返回需核对状态，不无限等待，也不伪称动作已失败。 验收：成功 patches-only 正常完成；失败带完整 patches 仍失败；空结果稳定失败而不 panic；部分/非法 patches 不成功；取消/Unknown 不自动变成可重试失败。外部动作完成、终态未保存时崩溃，分别测试目标文件齐全/缺失，两种情况均不伪成功或自动重复动作。检查重复尝试仍复用 ExecutionID 和截止时间。

U4. Squad Resolver Configuration

目标：修复 F06，落实 R2；无先行依赖。 文件：deps/agent-squad/squad/backend.go、adapters/native/register.go；测试 squad/backend_test.go、adapters/native/register_test.go。 方案：后端工厂和角色执行配置有明确版本/摘要，更新时使相关缓存失效；限流身份与执行器配置身份分开，不能换版本便绕过同一角色并发上限。 验收：allow→deny 收紧、deny→allow 显式放开、工厂替换、工具配置变化和限额变化正确；并行首次 Resolve 不重复构造；在途旧执行不会因新版本开启而突破总限额。 在途任务已开始动作不承诺回滚；需要即时撤权的宿主继续在每次工具执行前检查。

U5. Intent Snapshot and Generated Actions

目标：修复 F07 的 Intent 部分与 F08，落实 R4/R5；无先行依赖。 文件：deps/agent-intent/intent/fold.go、registry.go、catalog.go、recognizer.go、slots.go；测试 intent/registry_test.go、intent/slots_catalog_test.go、intent/i2_test.go。 方案：补齐现有 clone 的输入/输出边界；目录保留权威 ActionRef；生成命令先解析回唯一 spec，再复用槽位校验和风险元数据；不得用 handler 字符串索引 spec-ID 槽位表。分类器输入同样隔离，拒绝非有限/越界分数并重检阈值。 验收：修改原始 spec、SpecByID/Catalog/Options 不影响生效快照；规则与生成同动作同槽位得到等价结果；必填缺失、非法枚举/格式、未知槽位及 handler 重名均稳定处理；Action 指向不同命令 ID 仍可正确路由；低置信度不转 matched。 拆成独立实施时沿“快照隔离”和“生成校验”两个有界 worker 包执行，不合成通用 schema 平台。

U6. Backend Intent Admission

目标：修复 F09，落实 R4；依赖 U5 的权威结果结构。 文件：modules/backend/internal/intentgate/gate.go、internal/route/route.go、internal/server/server.go、必要的 internal/workflow/ 消费点；测试 internal/intentgate/gate_test.go、internal/route/route_test.go、internal/server/intent_admission_test.go（新增）。 方案：传递 missing/invalid 及澄清信息；区分“可开始澄清的流程草稿”和“可执行副作用的完整动作”。命令槽位按已声明 schema 映射，不能无类型地复制所有字符串；已有 text handler 保持兼容。高危动作仍由 cmdbus 确认。 验收：缺槽和非法槽都不会直接执行业务动作；允许澄清的流程可挂起；校验通过后的槽位正确进入 handler；显式取消/纠正尚未实现时诚实回退，不能声明已支持。

U7. Command Isolation and Receipts

目标：修复 F07 的 Command 部分及 F10，落实 R3/R5/R7；与 U6 可独立。 文件：deps/agent-command/registry.go、result.go、conformance/；modules/backend/internal/cmdbus/cmdbus.go 及已有 operation/outbox 的最小存储接口；测试 deps/agent-command/registry_test.go、result_test.go（不存在时新增）、modules/backend/internal/cmdbus/cmdbus_test.go、account_write_fence_test.go。 方案：复制 ParamsSchema 与 ExposeAsTool；unknown 允许保留可信 OperationID；handler 区分明确未执行与执行后未知。优先按现有持久化记录提供经 owner/project 授权的查询；若所选命令没有操作记录，则把最小持久化与查询作为该命令适配的组成部分，不能宣布“有 ID 就可查询”。 验收：外部修改返回 spec 不改注册表；成功后 audit 失败返回 unknown 且保留 ID；明确校验拒绝为 rejected；副作用后报错不伪称未执行；未知操作只核对、不自动重放；重复确认/跨用户查询不会重复执行或泄露结果。 跨仓先落兼容库变更，再更新 Backend。完整通用幂等平台不在本批；新幂等键只在选定命令已有明确重复执行风险时设计。

U8. Squad Durable State

目标：修复 F11，落实 R6/R7；结果解释依赖 U3。 文件：deps/agent-squad/adapters/sqlite/runstore.go、迁移入口、squad/workflow.go 与现有 checkpoint writer；测试 adapters/sqlite/runstore_test.go、squad/checkpoint_test.go。 方案：SQLite 完整保存 Mailbox/Handoffs/Board；用明确字段到目标的序列解码，不用内容作 map key。终态保存、manifest 和 checkpoint flush 均检查错误，并在 EvRunCompleted/成功返回之前收敛；不能只在 defer 改 error 而此前已经发出完成事件。保存错误与业务终态分别可见，不能因此重复执行已完成业务动作。 验收：FileStore/SQLite 同一合同 round-trip；恢复后继续收信/移交/认领；相同 clarifications/steering 都保存；sync/async/on_exit 的失败注入均可见；终态保存/manifest 失败不发伪成功事件；旧 schema 升级保留原数据。真实库迁移另行授权。

U9. Squad Queue Capacity

目标：修复 F12，落实 R6；可独立。 文件：deps/agent-squad/adapters/sqlite/queue.go；测试 adapters/sqlite/queue_test.go。 方案：一次原子 Claim 同时验证 agent 在途数和 runtime 总在途数，读取/计数错误拒绝认领；保留原租约和重领规则。 验收：runtime cap=1 下两个不同 agent 只能领取一个；同 agent 跨 runtime 仍受 agent cap；并发 Claim 不超限；释放后可继续领取。未接产品的队列模块不因此新接入产品。

U10. Backend Scoped Runtime Configuration

目标：修复 F13，落实 R2；无需等全部库修复。 文件：modules/backend/internal/app/app.go、internal/runtime/model.go、llm.go、internal/squadadapter/entry.go；测试 internal/app/squad_config_test.go（新增）、internal/runtime/model_test.go、route_contract_eof_test.go。 方案：从当前 rc.Settings、run owner、profile 解析完整路由，direct/squad 复用现有配置规则；必要时增加窄的工厂函数。保持项目来源观察/授权限制，不能为接线一致性重新开启被明确禁用的直连工具。 验收：两个用户不同配置与密钥来源不串用；项目覆盖生效；profile model 覆盖使用对应路由规则；MiniMax reasoning 分离和受限 EOF contract 一致；默认配置仍兼容；测试仅用合成密钥和本地 fake server。

U11. Tool Event Fidelity

目标：修复 F14，落实 R7；跨 Native→Squad→Backend。 文件：deps/agent-native/runtime/loop.go、exec/backend.go、adapters/native/backend.go；deps/agent-squad/squad/port.go、adapters/native/register.go；modules/backend/internal/runtime/squad_runner.go；测试各层现有 host-tools/adapter/runner 测试。 方案：向后兼容新增调用 ID 和真实错误/状态信息，按原语义传递 Text/Detail；宿主事件与最终 message parts 一致。并行回调使用受控串行聚合或局部锁，必要时修复共享 artifactList 的并发访问。 验收：同名工具两次调用各自配对；失败/拒绝/取消不显示 ok；摘要来自实际结果；并行事件/工件无丢失、无 race；旧适配器字段缺省不得被推断为已确认成功。 仅修事件合同，本单元不修改界面布局；若后续需要 UI 展示，先按 DESIGN.md 单列范围。

---

Functional Follow-Ups

以下是功能建议，不计入前述修复的默认实施范围。推荐顺序为 A1、A2、A3，A4 按真实外部对接需求启动。

ID	建议	用户收益	最小交付与验收
A1	多轮意图闭环	“把日期改到周五”“取消刚才的任务”能作用于明确对象	消费已有 set_slot/change_slot/cancel/expectation；绑定 owner/project/conversation/action/revision；歧义先澄清，过期回答不影响新任务；先覆盖一类真实业务动作
A2	执行与恢复诊断	看清卡在哪里、能否恢复、是否还要等人	在现有 run/operation 查询上提供当前责任角色、等待原因、最后稳定 checkpoint、已知副作用、下一步；先做授权读 API，不先造大型控制台
A3	能力目录召回与离线评测	不因目录固定 top-8 而遗漏低优先级能力，减少误启动	先建立脱敏评测集：否定/引用指令、多意图、错误槽位、过期确认、生成规则一致性；比较准确匹配、误执行、澄清率与成本，再决定是否需要检索或模型调整
A4	明确版本的 A2A 互通	外部 Agent 任务可查询、可取消并诚实报告状态	修 F16；采用官方 fixture/独立服务验证 Card、方法、状态与身份；持久化远端 task ID，处理 auth-required、未知态、超时和取消回执；不自动重发 message/send

现有 Makefile 已显式覆盖若干 Squad 嵌套 go.mod，但未列 A2A 子模块。 A4 启动时须纳入自己的验证入口，不能假设根 go test ./... 自动覆盖独立模块。 不建议本轮新增更多拓扑、动态角色市场、全自动自我改进或向量平台；先用评测证明新能力确有收益。

---

Verification Contract

实施先用各 F-ID 的具体触发条件形成最小回归，禁止只补“函数能调用”的测试。 不调用真实付费模型，不使用生产数据库，不将已设置的真实凭据输出到日志。

验证层	范围	通过判据
直接回归	U1-U11 各自文件/包	原触发条件被阻断，正常使用不退化
合同验收	现有 conformance 与 adapter 边界	Native 文本/文件/隔离合同，Squad 成功/失败/未知处理，Intent 规则/生成一致，Command 四态可对账
定向并发	注册表/缓存/队列/事件聚合	相关 -race 与原子认领用例通过，不机械扩大到所有包
故障恢复	截断 JSONL、存储错误、执行后响应丢失	恢复不丢协作状态，不伪称完成，不重复外部副作用
宿主集成	两个用户、项目覆盖、缺槽、确认、direct/squad	权限与配置作用域一致，确认后只执行一次，结果与事件一致
组合	固定组件及 Backend 嵌套 gitlink	每批最终候选执行项目规定的 make test 和必要构建，按当前门禁保存 SELF；当前 HEAD 必需 CI 为 GATE

库级测试成功不证明产品装配成功；fake 协议服务成功不证明外部协议兼容；启动 READY 不证明业务功能通过。 对于缺少真实后端的可选路径，清楚标注 NOT_RUN，不阻断已批准且不依赖它的本地修复交付。

Definition of Done

• 已批准批次的 F-ID 均有对应修复、反例与正常路径验证；被新基线消除的项记录来源，不重复实现。
• 变化的公共合同向后兼容或有明确迁移路径；错误语义和状态持久化可解释。
• 组件 SHA、Backend 嵌套引用与 Dev 组合一致；当前候选通过适用验证、独立 Review 和必需 CI 后按项目规范合入。
• 无未授权部署/真实数据迁移/发布；可选功能保持独立，用户业务验收不被工程自检替代。

Appendix

Primary Research

• S1. MCP Tools specification，核对版本 2025-11-25，研究日 2026-10-21：工具定义、结构化输入/输出与 annotations 信任边界。https://modelcontextprotocol.io/specification/2025-11-25/server/tools。影响 KTD2；未要求升级协议或引入 SDK。
• S2. LangGraph Persistence 官方文档，研究日 2026-10-21：checkpointer 的线程状态与 store 的跨线程数据各有作用域。https://docs.langchain.com/oss/python/langgraph/persistence。影响 KTD5；仅借鉴状态边界，不引入 LangGraph。
• S3. A2A v1.0.1 官方 specification 与 v1 变更说明，研究日 2026-10-21：协议方法、Agent Card 的 supportedInterfaces 和任务状态表示。https://a2a-protocol.org/v1.0.1/specification/、https://a2a-protocol.org/v1.0.1/whats-new-v1/。影响 F16/KTD8/A4；不混用开发中 PR 版本。

外部研究用于校验契约和改进方案，不能单凭行业实践宣判本项目缺陷。 进一步获取 Go os/exec 与 LangGraph interrupts 网页时检索工具连接失败；本方案未把未获取内容列为外部证据。

Remaining Decisions

建议批准第一批 U1-U7、U10 后连续实施到各自可验收的集成结果，再进入第二批 U8、U9、U11。 也可一次批准两批，但不因此纳入 A1-A4。 需要用户确定的是实施批次与后续功能优先级；具体函数、补充字段和回归组织由实施者在上述合同内确定，不再逐文件请求许可。 当前没有证据支持宣称线上已被利用；部署状态、真实模型行为和外部 A2A 互通仍待相应阶段验证。