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

2.2 编排（Agent-Squad）

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

2.3 理解（Agent-Intent）

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

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

2026-10-03 重新读了 pi v1.0.1（4c6fb7cf，MIT）和 ZCode v3.14.3（29628c9a，Apache-2.0）。评级、本仓落点和拒绝理由见 2026-10-03-pi-zcode-second-pass.md。pi-durable 在 v1.0.1 的事实更正见 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 06bde939。只借设计。许可证、评级、拒绝项和暂缓项见 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。不新建共享协议模块。

模块布局：

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 的识别适配导入。

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。

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）。开启态完整用户验收未重放。

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

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

6. 不在本文范围

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

7. 验收（本文）

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