Agent-System-Documents/docs/proposals/2026-10-02-agent-stack-completion.md

# 通用智能体、小队与意图：完善、借鉴与解耦

状态：**proposed（2026-10-02）**；owner：weichen；主任务：Dev 仓 `feature/agent-stack-blueprint`。
规范依据：Development-Guidelines（workflows/delivery.md、standards/collaboration.md、standards/agent-execution.md）；本文是项目级消费，不复制其正文。
撰写日期：2026-10-02。证据见 [2026-10-02-agent-stack-audit.md](../records/2026-10-02-agent-stack-audit.md)。
前序：[2026-10-01-agent-harness.md](2026-10-01-agent-harness.md) 定义了回合循环、完成判定和 P0–P4。那些阶段已经落在产品 Backend。本文把同一类能力收成三个可独立使用的库，并补上审计里的缺陷与对外借鉴。

本文只定义目标、裁定、分期和验收。不在本文实施。

---

## 1. 问题

三个库今天能跑，但换一个宿主就要重写一遍，而且库与库之间还互相依赖。

- **通用能力长在产品里。** 终轮验证、提醒、子代理画像、后台通知、评审、意图到工作流、critic 在 `modules/backend/internal/runtime` 与 `internal/runmgr`。直连、小队、子代理没有共用同一套门禁：`adapters/native` 不透传 Stop、Reminders、RepeatGuard、BeforeTool（审计 N31）。
- **测过的组合不是发布的组合。** Backend 编译用自己的 `deps/`（intent `7d9d505`、squad `5cbac00`）。Dev 指针是 intent `1dbbe81`、squad `590fd86`。Squad 自测用的 native 是 `a34689c`，不是产品里的 `c6d867c`（审计 X1）。
- **恢复不可靠。** 内核在工具预算用尽时留下没有结果的工具调用（N1）。Squad 的状态文件不是原子写，授权和修复预算不落盘，恢复会重跑正在执行的步骤，带 `RequiresApproval` 的步骤批准后再次挂起（Q1–Q5）。
- **实现级耦合。** 内核的 go.mod 为了没有调用方的 `adapters/intentgate` 依赖 Intent（X4）。Squad 的公开类型直接露出 `exec.Backend`、`*llm.Client`、`tools.*`（X5）。意图闸门有四套，动作键有四种（X8）。

编排裁定（本次已确认）：多智能体编排统一到 Agent-Squad。`core.WorkflowDef` 仍是插件作者面对的契约，Backend 把它编译成 Squad 的图，现有 `internal/workflow` 执行器退役。

## 2. 借鉴什么

只列会改这三个库的行为或接口的条目。链接是公开文档，版本以 2026-10-02 查阅为准。

### 2.1 回合循环（Agent-Native）

| 借鉴 | 来源 | 落到本库 |
|---|---|---|
| 钩子先于规则；deny 在放行模式下仍然生效；allow 不能跳过 deny / ask；规则可按参数模式匹配；子代理继承父会话权限，插件里的智能体定义不能声明钩子、MCP 和权限模式 | [Claude Agent SDK hooks](https://code.claude.com/docs/en/agent-sdk/hooks)、[permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md)、[subagents](https://code.claude.com/docs/en/subagents) | HookBus。事件对齐 PreToolUse、PostToolUse、PostToolUseFailure、PostToolBatch、Stop、SubagentStart/Stop、PreCompact、PermissionRequest、SessionStart/End。决策为 allow / deny / ask / modify / block，带原因，并带「已在续跑中」标志防止递归 |
| 输入检查只作用于入口智能体，输出检查只作用于给出最终结果的那个，工具检查每次调用都跑 | [OpenAI guardrails](https://openai.github.io/openai-agents-python/guardrails/) | 三类 guardrail。Backend 的终轮验证下沉为输出 guardrail |
| span 名为 `invoke_agent`、`chat`、`execute_tool`、`plan`、`invoke_workflow`；提示词和工具参数默认不采集 | [OTel GenAI agent spans](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/gen-ai-agent-spans.md)、[可观测性说明](https://opentelemetry.io/blog/2026/genai-observability/) | 三库事件用同一套名字。层级是工作流包含智能体调用，智能体调用包含模型调用和工具执行 |
| 压缩、清理旧工具结果、记忆是三种不同手段；压缩后保留摘要和最近用过的文件；前缀稳定、只追加、序列化结果确定，才能吃到缓存；工具定义不在运行中增删；完整结果落文件，上下文里留可恢复的路径 | [上下文工程](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)、[cookbook](https://platform.claude.com/cookbook/tool-use-context-engineering-context-engineering-tools)、[Manus](https://manus.im/en/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus) | ContextManager。压缩按工具配对边界裁剪（同时修 N7）。system 段不放秒级时间戳。工具清单顺序固定。旧工具结果可替换成路径。计划提醒按成本节流：反复改写待办会占掉大量动作（[整理](https://rlancemartin.github.io/2025/10/15/manus/)） |
| 长任务先落功能清单和进度文件，之后每个会话只做一项并留下可交接的状态；有的模型需要清空上下文再交接，有的可以靠自动压缩连续跑 | [长任务 harness](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)、[harness 设计](https://www.anthropic.com/engineering/harness-design-long-running-apps) | 内核负责可恢复的 RunState。会话清空再交接是 Squad 的一种拓扑，不是内核默认行为 |
| 工具按需加载；模型写代码批量调用工具，中间结果不进上下文 | [advanced tool use](https://www.anthropic.com/engineering/advanced-tool-use)、[programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | 注册表支持延迟加载和 `tool_search`。Backend P4 的脚本宿主下沉为「代码编排工具」端口，产品只留开关和确认 |
| 只对写文件类工具做检查点，shell 改动不追踪 | [file checkpointing](https://code.claude.com/docs/en/agent-sdk/file-checkpointing) | write / edit / multi_edit 记录改前内容，可回滚到某条用户消息；同时改成临时文件再 rename（修 N15） |
| 子代理 frontmatter：说明、提示、工具、禁用工具、模型、权限、技能、轮次上限、记忆范围、力度、是否后台、是否隔离工作树 | [subagents](https://code.claude.com/docs/en/subagents) | AgentSpec 采用这些字段，再加 `outputSchema` |
| `SKILL.md` 的 name 与目录同名、小写连字符、description 说明何时使用；客户端扫描 `.agents/skills/` | [Agent Skills](https://agentskills.io/specification) | 加载器按该规范校验，并扫描 `.agents/skills/` |
| MCP 2026-07-28：无状态核心；长任务用 tasks/get、update、cancel；需要用户输入时返回 `input_required`，客户端重试原请求；工具 schema 放到 JSON Schema 2020-12 | [changelog](https://modelcontextprotocol.io/specification/2026-07-28/changelog.md)、[RC 说明](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) | 客户端认 `resultType`。`input_required` 接到审批端口。Tasks 接到后台任务。同时修 N3、N18 |

### 2.2 编排（Agent-Squad）

| 借鉴 | 来源 | 落到本库 |
|---|---|---|
| 工作流分五类：链式、路由、并行、编排者-工人、评估-优化 | [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) | 现有 standard / router / leader 分别覆盖前三类里的大部和编排者-工人。缺评估-优化循环和投票。critic 从 Backend 工作流收成一种拓扑 |
| 执行器加有类型的边；按 superstep 推进，步结束做检查点；恢复要求图结构不变。检查点以 thread 为键，并行分支里已成功的写入单独保存，崩溃不丢。挂起与恢复是同一对原语。持久化分退出时、异步、同步三档 | [MAF workflows](https://learn.microsoft.com/en-us/agent-framework/workflows/workflows)、[edges](https://learn.microsoft.com/en-us/agent-framework/workflows/edges)、[checkpoints](https://learn.microsoft.com/en-us/agent-framework/workflows/checkpoints)、[LangGraph checkpointers](https://docs.langchain.com/oss/python/langgraph/checkpointers)、[interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) | 图执行取代「相邻 Parallel 标记」。步骤带 attempt id。这一层同时修 Q1–Q5 和 Q7 |
| 内置顺序、并行、群聊、交接、Magentic。并行分支默认不共享对话，状态通过事件里的增量写入 | [MAF magentic](https://learn.microsoft.com/en-us/agent-framework/workflows/orchestrations/magentic)、[ADK parallel](https://adk.dev/agents/workflow-agents/parallel-agents/)、[ADK state](https://adk.dev/sessions/state/) | Topology 插件加这组内置实现。黑板改成可回放的增量 |
| 编排者维护任务账本（事实、猜测、计划）和进度账本（是否完成、是否卡住）；卡住就重规划，并限制轮数、连续卡顿和重置次数 | [Magentic-One](https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/magentic-one.html) | Squad 黑板已接近任务账本。leader 补进度账本、卡顿检测和重规划上限 |
| 终止条件可用 AND / OR 组合 | [AutoGen termination](https://microsoft.github.io/autogen/stable/user-guide/agentchat-user-guide/tutorial/termination.html) | 轮次、修复预算、唤醒次数、超时收成 Termination |
| 交接把最终回答的所有权交出去；当作工具调用则管理者保留所有权。能用一个智能体就先用一个 | [orchestration](https://developers.openai.com/api/docs/guides/agents/orchestration)、[handoffs](https://openai.github.io/openai-agents-python/handoffs/)、[Swarm](https://microsoft.github.io/autogen/0.7.3/user-guide/agentchat-user-guide/swarm.html) | handoff 原语带历史过滤器。TeamSpec 声明谁拥有最终回答 |
| 团队：每人独立上下文，共享可认领的任务表（依赖未完成不能领），点对点邮箱。别人发来的消息不能代替用户表示同意 | [agent teams](https://code.claude.com/docs/en/agent-teams) | platform 的队列改成 task-board 拓扑，加 mailbox。智能体消息不能携带用户授权，从根上去掉 wakeup 自动批准（Q8） |
| 委派要写清目标、输出格式、工具和边界；投入随问题伸缩。写操作保持单线程，因为动作带着别人看不见的决定；只读探索可以并行 | [多智能体研究系统](https://www.anthropic.com/engineering/multi-agent-research-system)、[Don't Build Multi-Agents](https://cognition.com/blog/dont-build-multi-agents)、[后续](https://cognition.com/blog/multi-agents-working) | 步骤声明自己写哪些工件。调度默认：只读可并行，写同一工件必须串行。委派模板结构化。上游产物落文件，下游拿路径和最新黑板（修 Q11） |
| A2A 1.0：Agent Card、每接口一个协议版本、任务有固定状态机 | [A2A 1.0](https://a2a-protocol.org/v1.0.0/specification/)、[v1 变化](https://a2a-protocol.org/latest/whats-new-v1/) | 适配器：远端智能体作为一种 Executor；本团队也可发布 Agent Card。跨库结果状态对齐 A2A 任务状态，不自造第四套词 |

### 2.3 理解（Agent-Intent）

| 借鉴 | 来源 | 落到本库 |
|---|---|---|
| 一次用户话可以产出多条命令：开始流程、填槽、改槽、取消、澄清、闲聊、转人工。规则触发排在模型之前 | [Rasa 对话理解](https://rasa.com/docs/learn/concepts/dialogue-understanding/)、[命令生成](https://rasa.com/docs/reference/config/components/llm-command-generators/)、[流程启动](https://rasa.com/docs/reference/primitives/starting-flows/) | 输出从「一个意图」改为命令列表。Start 带 ActionRef。现有规则漏斗仍是确定性第一层。模型层是可选端口，执行仍归宿主 |
| 用示例句的向量相似度做路由，低于阈值则不命中 | [semantic-router](https://github.com/aurelio-labs/semantic-router) | 规则层和模型层之间的语义端口。向量模型由宿主注入，核心不做 I/O。IntentSpec 增加 examples。用来减轻中文子串误命中（I3） |
| 只把相关流程交给生成器；评测逐轮写出期望命令 | [命令生成器](https://rasa.com/docs/pro/customize/command-generator/)、[评测](https://rasa.com/docs/reference/testing/e2e/dialogue-understanding-tests/) | Catalog 按相关度取 top-k，Metadata 白名单。`intentctl eval` 改为多轮并输出 precision / recall |

### 2.4 二次对照增补（2026-10-03）

2026-10-03 重新读了 [pi v1.0.1](https://github.com/earendil-works/pi)（`4c6fb7cf`，MIT）和 [ZCode v3.14.3](https://github.com/zai-org/ZCode)（`29628c9a`，Apache-2.0）。评级、本仓落点和拒绝理由见 [2026-10-03-pi-zcode-second-pass.md](../records/2026-10-03-pi-zcode-second-pass.md)。pi-durable 在 v1.0.1 的事实更正见 [2026-10-03-pi-durable-review.md](../records/2026-10-03-pi-durable-review.md) 文首。

这一节只把会改三个库或产品行为的新增条目收进来。不改变第 5 节的阶段顺序，也不把上游包引进来。

| 借鉴 | 来源 | 落到本库 | 阶段 |
|---|---|---|---|
| 溢出识别用模式表；Retry-After 解析失败时指数退避；只在还没向调用方发出增量时重试；`length` 或未写完的工具调用不执行 | pi `packages/ai`，v0.99–v1.0.1 | Native 的 provider 客户端与 SSE 解析。Backend 直连默认有限次重试。用量拆成上一请求和累计 | N3 的模型回退与流重试；本项先做 |
| 运行内把旧工具结果换成路径；压缩按工具配对边界；写文件前必须读过且文件未被改过 | ZCode `packages/core` 的 compact 与 read-file-state；pi durable 的 compaction-as-entry | Native 的 ContextManager 与会话压缩。提醒不再追加成 user 消息 | N2 |
| 权限分计划、默认、自动改文件三档；deny 先于 ask 先于 allow；钩子事件与决策走同一条总线 | ZCode `packages/core` 的 permission 与 hooks；本提案 §2.1 已列事件名 | Native 的 PermissionPolicy 与 HookBus。不提供绕过确认的档位 | N1 |
| 工具调用先记意图再记结果；只有两次声明都是 safe 才重放；写文件可回滚，shell 不追踪 | pi durable README 的 Tools 与 Compaction；ZCode `contracts/rewind` | Native 的 RunState 与文件检查点。不回滚对话历史，不做透明续跑 | N3 |
| 模型写脚本批量调用工具，中间结果不进上下文；MCP 工具可延迟暴露，首条提示不等服务器连上 | pi `packages/codemode` 与 `docs/mcp.md`；本提案 §2.1 的代码编排端口 | Native 的代码编排端口与 MCP 客户端。产品开关默认关 | N2 |

### 2.5 SillyTavern 对照里会改产品行为的条目（2026-10-04）

对照 [SillyTavern 1.19.0](https://github.com/SillyTavern/SillyTavern) `06bde939`。只借设计。许可证、评级、拒绝项和暂缓项见 [2026-10-04-sillytavern-review.md](../records/2026-10-04-sillytavern-review.md)。下列条目在同一任务里落地。

| 借鉴 | 来源设计 | 落到本仓 |
|---|---|---|
| 带标签的多密钥，同时只生效一把；读出只给掩码；迁入前先留设置快照 | 密钥与设置快照 | Backend `secret_keys` / `settings_snapshots`。运行时优先读生效密钥，否则仍读设置里的旧字段 |
| 个人指令和会话要求附在上下文末尾 | persona 与 Author's Note | `context.userInstructions` 与会话 `sessionNote`，经 `reminders.Attach` 注入 |
| 关键词或正则、次关键词、扫描最近 N 条、常驻、预算 | 世界书的精简子集 | `context_entries`。不做概率、递归、分组和定时 |
| 组装时给出分段估算和系统前缀哈希；估算为 UTF-8 字节 / 3.35，并用上一请求用量校准 | 提示词分段视图 | `ContextObservation.sections` / `prefixHash`。`context.contextWindow` 只丢掉最早的历史 |
| 合并相邻同角色；严格模式再收起多余的 system | 按 endpoint 做消息整形 | agent-native `PrepareMessages`，设置 `context.messageShape` |
| 复制、成组排除出上下文、追加式候选回复并联动文件回滚 | 对话操作 | 不删除消息。重新生成排除旧候选，新回复写入同一 `variantGroup` |
| 用户 `/` 命令展开成提示词 | 快捷指令 | `user_commands`，登记为 agent-command 的 `user` 来源。不自动触发 |

## 3. 解耦

三个库各自能单独编译、单独测试、单独被第三方使用。配合发生在组合根，不发生在核心模块里。

依赖规则：

- 核心模块互不依赖。只依赖 error-code-system 和 logging-system。
- 端口由使用方定义。Squad 定义 Executor、ModelClient、IntentGate、Store。Native 定义 Provider、Tool、Memory、Checkpoint、Telemetry。Intent 定义 Classifier、Embedder、CommandGenerator。
- 跨库适配器放在使用方仓库的独立子模块，各自有 go.mod。只有适配器可以同时依赖两个库。
- 互通格式由定义它的库发布 JSON Schema 和样例，不共享 Go 类型。AgentSpec 归 Native，IntentSpec / 命令 / ActionRef 归 Intent，TeamSpec / 图归 Squad。
- 共同词表直接用外部标准：事件名用 OTel GenAI，结果状态用 A2A 任务状态，trace 沿用 logging-system 的 trace_id。不新建共享协议模块。

模块布局：

```text
agent-native/          回合循环、HookBus、ContextManager、完成判定、
                       provider、tools、mcp、skills、session、
                       memory、checkpoint、telemetry。
                       exec 是唯一对外入口。schema/
agent-intent/          规则漏斗、命令列表、ActionRef、Catalog。schema/
agent-squad/           图执行、Topology、Termination、端口定义。schema/
  adapters/native/     独立 go.mod。实现 Executor 与 ModelClient
  adapters/intent/     独立 go.mod。实现 IntentGate 与目录映射（现 squadintent）
  adapters/a2a/        独立 go.mod
  adapters/sqlite/     独立 go.mod。现 platform 的持久层
  cmd/agent-squad/     独立 go.mod。CLI 与 HTTP 组合根
```

每个概念只留一处：

| 概念 | 唯一处 | 不再出现在 |
|---|---|---|
| 智能体定义 | AgentSpec | Backend 的 `agent-sub-*.md` 迁成 AgentSpec 文件。RoleSpec 只加团队属性 |
| 意图识别 | agent-intent | 删除 native 的 `adapters/intentgate`。Backend 闸门改为消费同一次识别结果 |
| 路由 | 宿主里的一个 Router，按 ActionRef 分发 | 命令、工作流、小队、普通回合四个分支不再各写一套判断 |
| 能力目录 | intent 的 Catalog | Squad 规划器和直连路径都注入这一份 |
| 工作流执行 | Squad 图执行 | Backend `internal/workflow` 退役。`core.WorkflowDef` 只作为编译输入 |
| 人工确认 | 宿主渲染并回填 | 库只发信号：权限请求、MCP `input_required`、图的 interrupt、Clarify 命令 |
| 预算 | Native 管一个智能体；Squad 管团队并分给步骤；Backend 管配额 | 三处不再各算各的 token 账 |

版本：

- 模块路径改为可 `go get` 的路径并打 semver。改路径会打断现有 import，与路线图第 4 节一样，单独发版，不塞进功能阶段。
- 库仓不再嵌套兄弟库的 gitlink。适配器子模块用 go.mod 版本钉依赖。
- Dev 根增加 `go.work`，让 `make test` 测的就是将要发布的组合。增加检查：Backend 编译用到的每个库 SHA 等于 Dev 指针。
- 这项会改变 `make build` 实际编译的代码来源。实施 R0 时要同时核对 Releases 仓从本仓固定提交导出的流程，避免导出物突然改用另一套 SHA。
- `lint-boundaries` 增加：核心模块的 `go list -deps` 不得出现兄弟库；agent-intent 只允许被 `adapters/intent` 和 Backend 的识别适配导入。

```mermaid
flowchart TB
  subgraph host [宿主]
    Router["按 ActionRef 分发"]
    Root["组合根装配适配器"]
  end
  subgraph intentCore [agent-intent]
    Commands["命令列表与 Catalog"]
  end
  subgraph squadCore [agent-squad]
    GraphExec["图执行"]
    SquadPorts["Executor / ModelClient / IntentGate / Store"]
  end
  subgraph nativeCore [agent-native]
    Loop["回合循环"]
  end
  subgraph adapters [agent-squad/adapters]
    AdNative["native"]
    AdIntent["intent"]
  end
  Router --> Commands
  Router --> GraphExec
  Router --> Loop
  Root --> AdNative
  Root --> AdIntent
  AdNative --> SquadPorts
  AdNative --> Loop
  AdIntent --> SquadPorts
  AdIntent --> Commands
```

## 4. 目标行为

一个智能体是一份 AgentSpec：工具、模型、轮次、技能、权限、钩子、输出 schema。直连会话、子代理、小队角色用同一份。小队角色只多团队属性（并发上限、是否拥有最终回答、可交接给谁）。

一次小队运行是一张图。调度按依赖和读写集决定谁可以并行。每步结束写检查点。需要人时挂起，同一入口恢复。进程死在任意步边界，恢复不重复已成功步骤的副作用，也不丢掉已批准的授权。

一次用户话先变成命令列表。规则层能确定的不过模型。宿主的 Router 只看 ActionRef：命令、工作流、小队或普通回合。Intent 不执行。

插件作者仍然写 `WorkflowDef`、意图 JSON 和工具声明。新增智能体写 AgentSpec 文件。新增小队写 TeamSpec。新增拓扑实现 Topology。这些入口在各阶段的验收里逐个对照，避免再长出第五套键。

沙箱仍由宿主负责。库声明自己不是操作系统沙箱。

## 5. 分期

每阶段单独任务。依赖：R0 先做。R1 在三个库内并行。R1 之后做 D1。D1 之后 N1、Q1、I1 可以同时做。它们完成后再做 N2、Q2、I2。N3 在 N2 之后。Q3 在 Q2、N1、I1 之后。

N1 / Q1 / I1 的实施方案见 [2026-10-07-agent-stack-n1q1i1-plans.md](2026-10-07-agent-stack-n1q1i1-plans.md)。

### R0 组合一致性

Dev 根 `go.work`。检查脚本对比 Backend `deps/` 与 Dev 指针。`lint-boundaries` 加上文第 3 节的依赖断言。核对 Releases 导出是否跟随 `go.work`。

验收：故意把 Backend 的 squad 指针留在旧 SHA 时检查失败；指针对齐时 `make test` 通过。文档写明 `make build` 编译的是哪一套 SHA。

### R1 缺陷

三个库各自独立 PR，只修审计中的 P0，外加安全向 P1：N13、N14、Q8、Q14、Q15、Q16。每条带回归测试。

验收：审计表里对应编号有测试名。Squad 的崩溃恢复至少覆盖「批准后能执行」「重启后授权还在」「running 步骤不执行第二次」。Native 的预算用尽用例里，历史中每个 tool_call 都有结果。

### D1 结构解耦

Native 去掉对 agent-intent 的依赖，合并 contract 与 exec，拆 Options。Squad 核心改为自有端口，跨库代码进 adapters 子模块，CLI 进 cmd。Intent 的校验器改为 Registry 作用域，并校验分类器输出。三库发布 JSON Schema 样例。删除嵌套兄弟库 gitlink 与改模块路径分开发版任务，本阶段只把依赖方向改对，路径可以仍用 replace。

验收：`go list -deps` 符合第 3 节。Squad 核心测试不链接 agent-native。用适配器子模块跑通现有 conformance。Backend 行为不变，用现有 `make test` 证明。

### N1 内核 harness

AgentSpec、HookBus、PermissionPolicy、三类 guardrail。CompletionGate 与提醒从 Backend 下沉。`adapters/native` 透传钩子。Backend 改为消费，A/B 对照直连行为。

验收：同一组脚本化模型输出，下沉前后的停止原因、提醒次数和工具拒绝一致。插件里的 AgentSpec 不能带钩子和权限模式。

### N2 上下文、协议与工具

ContextManager 与缓存友好规则。Anthropic 原生消息含 tool_use 与 thinking 签名。延迟加载工具、tool_search、代码编排工具端口。MCP 认 `resultType`。skills 按开放规范校验。子代理可后台、有独立转录、可恢复。

验收：选 anthropic 预设能完成一轮工具调用（可用录制的 HTTP 夹具，不要求真实密钥）。压缩后的历史不出现孤立 tool_call。MCP 取消不再留下第二个读者（修 N3 若 R1 未覆盖到协议层）。

### N3 持久与可观测

RunState 可恢复。文件检查点可回滚。Memory 端口。事件可导出为 OTel GenAI span。成本分「上一请求」与「累计」。模型回退链。流式错误默认重试。

验收：回合中途杀进程，恢复后工具配对仍成立。回滚只撤销 write / edit / multi_edit。span 名与约定一致，默认不含提示词正文。

### Q1 图执行

superstep、三档检查点、attempt id、interrupt / resume。`Needs` 驱动依赖。读写集。可组合 Termination。Store 接口。platform 的 SQLite 成为 Store 的一个实现，不再单独驱动一套运行。

验收：在每个 superstep 边界杀进程再恢复，已成功步骤的副作用次数为 1。两个写同一工件的步骤不会并行。文件 run 与 SQLite 不再各记一份步骤状态。

### Q2 拓扑

内置：sequential、parallel、loop、router、leader（含进度账本和重规划上限）、handoff、group-chat、review、evaluator-optimizer、long-running、task-board 与 mailbox。

验收：每种拓扑有一个脚本化后端的 conformance。review 等价于今天的「并行找问题、逐条验证、丢掉未验证」。mailbox 消息不能把挂起的权限批准掉。

### Q3 收敛与互通

Backend 把 `WorkflowDef` 编译成 Squad 的图。`internal/workflow` 与把小队步骤压成 `SpawnSubagent` 的路径退役。委派模板含目标、输出格式、工具和边界。`adapters/a2a` 双向。产品默认执行后端改为 agent-native，用同一批任务的 A/B 对照作门禁。

验收：现有示例插件 `demo.brief` 与 `demo.script` 经编译后的图跑通，行为与 P4 裁定一致（步数上限、确认、脚本开关）。A/B 对照记录差异，不要求字节级相同。

### I1 命令化识别

命令列表与 ActionRef。中文匹配的词界或最短词长。同分时可按 priority 决胜。Catalog 白名单与 top-k。Backend 唯一 Router 消费 ActionRef。

验收：审计 I1、I2、I3、I5 有回归。一条用户话可以产出 SetSlot 加 Start。命令 id、工作流 IntentID、小队 blueprint 都通过 ActionRef 到达 Router，插件清单不改字段名。

### I2 分层与评测

语义端口与 examples。模型命令生成端口，输出做与 I1 相同的校验。对话状态仍由宿主持有，库只提供「给定状态，产出命令」的函数。多轮评测输出 precision / recall。文档写明无繁简转换。

验收：分类器返回未知 ID 时结果保持 Ambiguous。eval 对一份不少于现有语料规模的多轮夹具给出指标，而不是只打印分支名。

状态回填（2026-10-08）：I2 已实施并合入（Dev #242，merge d308ed6；R1–R4 验收声明 PASS，
SELF；各组件仓 CI 在 merge 前 success，GATE）。本节是 I2 的唯一规划主记录——I2 任务卡
原先误引「N1/Q1/I1 实施案的 I2 部分」（该文档不含 I2），链接已在 Dev 侧修正指向本节。
剩余项：慢通道开启态的端到端灰度与阈值调参（原记随 RDM MS1 插件语料一并）、
SetSlot/Cancel/Handoff 命令的运行时消费（无阶段载体，见
[N1/Q1/I1 案回填 §7.3](2026-10-07-agent-stack-n1q1i1-plans.md)）。开启态完整用户验收未重放。

### E 评测（每阶段都带，不单列阻塞）

Native：配对、取消、预算、压缩。Squad：步边界杀进程。Intent：多轮语料。Dev 组合：少量真实任务加人工复核，不把模型自报当通过。

## 6. 不在本文范围

- 合入上述任何阶段。
- 操作系统级沙箱。宿主隔离责任保持现状，文档继续声明。
- 改模块路径和打 tag。那是发版动作，由所有者确认后执行。
- 为单一产品预造领域角色库。TeamSpec 只定义格式；角色内容仍由产品和插件提供。
- 把 PromptTrigger 关键词并进 Intent。技能触发仍是提示词装配。若两套同时命中，Router 的优先级在 I1 任务里写明，本文不预设谁赢。

## 7. 验收（本文）

- 本文件与审计记录互相链接。
- [2026-10-01-agent-harness.md](2026-10-01-agent-harness.md) 与 [2026-10-01-base-extension-roadmap.md](2026-10-01-base-extension-roadmap.md) 指向本文。
- 不改 Go 代码，不改三个库的指针。