Add the Generative UI research and plugin proposal r1 with user rulings

Why: The user ruled on 2026-10-11 the three open product choices (first
pilot = full analysis page inside the conversation; enable/disable via a
trusted compiled plugin; U1 trial on MiniMax M3 + M2.7-highspeed with
sanitized materials and a CNY 200 cap), so the proposal now publishes as
the direction's master record instead of a local draft.

Evidence: Doc self-check receipts live in the Dev task card
feature/generative-ui-research; the rulings are recorded in the doc's
"用户裁定记录" section and mirrored in INDEX.md.

Impact: Documents-only change (new proposal + index entry). No runtime,
contract, or code changes; U1 trial start and deployment stay separately
reviewed.

Refs: Dev task feature/generative-ui-research

PROJECT.md

@@ -0,0 +1,19 @@
+# Agent-System-Documents 项目事实
+
+## 职责与边界
+
+本仓保存系统架构方案、使用指南、验证报告与实施记录。目录入口见 [README](README.md)。
+通用开发规范由 Dev 仓固定的 Development-Guidelines 提供；本仓不复制通用规则，
+不承载业务实现、凭证、运行数据或部署制品。
+
+方案、已实现、已验证、已合入与已部署分别记录；历史报告只证明其指定版本和环境。
+系统级记录关联组件 PR 与 Dev 组合 PR，不以文档状态代替运行事实。
+
+## 验证
+
+纯文档修改执行 `git diff --check`，核对受影响相对链接、引用来源、版本及规则一致性。
+报告中的通过断言关联真实命令、被测对象和证据来源；未验证事项写 NOT_RUN。
+修改运行提示词或有效策略时，按行为影响追加对应系统验证，不能按普通文字编辑验收。
+
+本仓没有可编译程序或独立业务测试套件。跨仓固定组合在 Dev 仓运行 `make test`；
+过程记录中的命令和环境须按当次任务核实，不能机械重放旧运维命令。

README.md

@@ -2,6 +2,9 @@
 
 系统文档与过程记录仓：架构决策、方案与验证记录、使用与插件开发指南；不含产品代码。
 
+从 [项目方向与规划索引](docs/proposals/INDEX.md) 查找主记录、里程碑、关联任务及待确认差异。
+索引给出固定版本的核验快照；方案批准、PR 合入和运行验收分别记录。
+
 ## 目录
 
 ```text

docs/guides/architecture-overview.md

@@ -0,0 +1,213 @@
+# Agent-System 系统结构与架构
+
+> 基准：Agent-System-Dev 组合 `218fc4b1ba00b0a03b5bb79f292b3eba6c987a58`（R0，2026-10-08 锚点核验）。
+> 行号为该提交下的函数入口位置（个别内部区段为约略范围），随代码演进漂移；文件与函数名是稳定锚点。
+> 文中路径均为 Dev 组合仓内相对路径。
+
+---
+
+## 1. 总体形态：一个父仓 + 12 个子模块仓的组合系统
+
+Agent-System 是**多仓组合（gitlink 固定指针）**的开发集成父仓，不是单一代码库。
+`.gitmodules` 定义了 12 个子仓，分两类：
+
+**modules/（5 个产品模块仓）**
+
+| 仓 | 目录 | 定位 | 技术栈 |
+|---|---|---|---|
+| Agent-System-Core | `modules/core` | 核心契约库：纯数据类型 + 线格式权威，零第三方依赖 | Go（附 `ts/types.ts` TS 镜像） |
+| Agent-System-Backend | `modules/backend` | 后端模块化单体，默认单二进制（内嵌前端 + 嵌入式 SQLite） | Go |
+| Agent-System-Frontend | `modules/frontend` | Web 前端 | React 19 + Vite + TypeScript |
+| Agent-System-UI | `modules/ui` | 纯展示组件库：props 进 events 出，不持状态不调 API | React + CSS 令牌 |
+| Agent-System-Documents | `modules/documents` | 文档过程仓（设计提案/记录/报告），无代码 | Markdown |
+
+**deps/（7 个基础库仓）**
+
+| 仓 | go module 名 | 一句话职责 |
+|---|---|---|
+| agent-native | `agent-native` | Agent 执行内核：ReAct 循环、LLM 客户端、工具注册表、会话转录、MCP、技能 |
+| agent-squad | `agent-squad` | 小队编排底座：规划器、Leader 委派、黑板、HITL 挂起恢复、调度 |
+| agent-intent | `agent-intent` | 确定性意图识别：四级漏斗（Guard→Expectation→Rules→Adjudicate） |
+| agent-command | `agent-command` | 命令总线基础库：命令 spec、危险分级、审计信封（零依赖） |
+| error-code-system | `error-code-system` | 跨系统错误码目录 + HTTP 错误信封 + 查询服务 |
+| logging-system | `logging-system` | 结构化日志库 + 采集服务 |
+| development-guidelines | —（非 Go） | 人与 Agent 共用的开发规范文档基线 |
+
+**依赖方向铁律**（`README.md`）：
+
+```
+frontend → core ← backend → { agent-native, agent-squad, agent-intent, agent-command }
+                                        ↘ error-code-system / logging-system
+```
+
+core 与各生态仓互不依赖；backend 对 8 个库的引用经自己仓内 `deps/` 子模块 +
+`modules/backend/go.mod` 的 `replace` 收敛（父仓顶层 `deps/` 与 `modules/backend/deps/`
+是同一批仓的两份 gitlink，`scripts/check-pins.sh` 核对一致）。仓库**不使用 go.work**
+（避免工作区最小版本选择抬高 backend 单独构建的依赖版本，见 `PROJECT.md`）。
+
+**三态一致的契约机制**：core 的每个契约同时存在 ① Go 类型（camelCase JSON）、
+② `modules/core/testdata/golden/*.json` 黄金样本（线格式权威）、③ `modules/core/ts/types.ts`
+手工 TS 镜像。父仓 `make contracts` 把 TS 镜像生成到 frontend 与 ui 的 `src/contracts.ts`。
+
+---
+
+## 2. Backend 功能分布（产品核心）
+
+单二进制入口：`modules/backend/cmd/agent-system/main.go`（子命令 serve/version/apikey/user/config）。
+组合根与装配顺序在 `modules/backend/internal/app/app.go` 的 `Run()`：
+存储 → 总线 → 工具注册 → settings/prompts/skills/profiles → runmgr（三个 runner + SquadRunner 注入）→
+intentgate → 插件宿主 + hostapi → workflow 注册表 → RAG → 可选 intentsem →
+cardsvc/cmdbus → server + 限流 + 认证 → HTTP 监听（默认 `127.0.0.1:8787`）。
+
+### internal 包职责一览（功能 → 代码分布）
+
+| 包 | 主文件 | 职责 |
+|---|---|---|
+| app | `internal/app/app.go` | 组合根：装配一切组件 |
+| config | `internal/config/config.go` | 启动配置单一管道：内置默认→`--config` JSON→环境变量→CLI |
+| store | `internal/store/store.go` | 持久化唯一入口；SQLite（默认，modernc 纯 Go）/ PostgreSQL 双档；`dialect.go` 方言收敛、`migrate.go` 版本化迁移 |
+| blobstore | `internal/blobstore/blobstore.go` | 工件对象存储抽象，默认本地目录 `<data>/artifacts/` |
+| bus | `internal/bus/bus.go` | 进程内事件总线：按会话转发已持久化事件给 SSE 订阅者 |
+| pgbus | `internal/pgbus/pgbus.go` | PG 档跨实例扇出：`NOTIFY/LISTEN agent_events` |
+| cmdbus | `internal/cmdbus/cmdbus.go` | 命令总线宿主：button/card/slash/chat 四入口归一分发、危险命令确认卡、审计 |
+| cardsvc | `internal/cardsvc/cardsvc.go` | 收件箱任务卡服务（card.* 事件投影） |
+| runmgr | `internal/runmgr/runmgr.go` | **Run 生命周期枢纽**：状态机、事件持久化+广播、HITL、子代理任务树、工具执行策略、取消级联 |
+| route | `internal/route/route.go` | 唯一意图 Router：命令总线 > 工作流 > 普通回合 |
+| intentgate | `internal/intentgate/gate.go` | 意图闸门：接入 agent-intent 库，插件意图 overlay |
+| intentsem | `internal/intentsem/scorer.go` `generator.go` | 意图慢通道：embedding 语义重排 + 轻量模型命令生成（默认关） |
+| runtime | `internal/runtime/runner.go` `llm.go` `llm_direct.go` `sub_loop.go` `workflow_compiled.go` `squad_runner.go` `model.go` | 四类 Runner（LLM/Mock/Sub/Squad）+ 工作流执行入口 + 模型路由 |
+| wfcompile | `internal/wfcompile/run.go` `compiler.go` | 工作流编译执行驱动：编译图 → 小队引擎装配 → 步进循环 → critic 终判 |
+| ctxasm | `internal/ctxasm/ctxasm.go` `finish.go` | 上下文组装与预算裁剪 |
+| prompts | `internal/prompts/service.go` | 提示词模块库：embed 内置 + DB 用户覆盖链 |
+| skills | `internal/skills/skills.go` | 内置技能种子（go:embed recipes → `<data>/skills/`） |
+| tools | `internal/tools/registry.go` | 统一工具注册表：内置/声明式 HTTP/插件工具同形态 |
+| plugins | `internal/plugins/host.go` `host_v2.go` | 插件宿主：fail-closed 热加载；sidecar 进程拉起 |
+| hostapi | `internal/hostapi/server.go` | sidecar 本机回调面 `/host/v1`（127.0.0.1 随机端口 + 随机 token） |
+| workflow | `internal/workflow/registry.go` | 工作流**定义**注册表（编译执行器在 wfcompile） |
+| ingest / docgen / rag / quality | 各主文件 | 文档摄取 → ParsedDocument IR；Markdown→docx；混合检索 rerank；交付物六维打分 |
+| profiles / settings / ratelimit | 各主文件 | 画像；system→user→project 分层设置；租户限流（内存/Redis） |
+
+### 其他目录
+
+- `modules/backend/pkg/extension/`：对下游仓的**公开扩展面**（下游只许依赖本包与 core，
+  `surface.txt` 锁导出面）；`link/` 把 extension.Main 接回组合根。
+- `modules/backend/web/embed.go`：`go:embed` 内嵌前端构建产物。
+- `modules/backend/deps/`：8 个库的 submodule 副本（replace 目标）。
+
+---
+
+## 3. 前端与 UI 分工
+
+- **frontend**（`modules/frontend/src/`）：`App.tsx` 四栏布局 —— 左（项目/会话树
+  `TaskSidebar.tsx`）、中（流式对话 `Conversation.tsx` + `ProcessTimeline.tsx`）、
+  预览区（`PreviewPane.tsx` / `ArtifactsPanel.tsx`）、右（工作台卡流 `Workbench.tsx`）。
+  职能文件：`api.ts`（HTTP 客户端）、`live.ts`（SSE 到达序投影纯逻辑）、
+  `store.ts`、`runstate.ts`、`pluginHost.ts`、`outbox.ts`。
+- **ui**（`modules/ui/src/`）：只渲染词汇有限的 UI schema —— `UIRenderer.tsx`、
+  `InboxList.tsx`、`InlineConfirmCard.tsx`（危险命令确认卡）、`ToolBlock.tsx`、
+  `tokens.css`（设计令牌唯一来源）。frontend 经 `@ui` 别名直接源码组合（`vite.config.ts`）。
+
+---
+
+## 4. 通信架构：HTTP + SSE，无 WebSocket
+
+- **全部 HTTP 路由**集中在 `modules/backend/internal/server/server.go` 的 `Handler()`
+  （约 90 条 `mux.HandleFunc`）：auth/users、projects/conversations/messages、cards、
+  artifacts/uploads、profiles/prompts/settings、tools/plugins、commands/audit、
+  plan/todos、knowledge、hitl 等。
+- **SSE** 是唯一增量通道：`GET /api/events?conversationId=...`（`server.go:171` 注册，
+  `server.go:275` 处理器），带 `Last-Event-ID`/`since` 游标重放；项目级流用伪会话键
+  `project:<id>`（`modules/core/events.go:30` `ProjectChannelKey`）。全仓 grep 无 websocket。
+- **事件三层转发**：
+  1. `runmgr/events.go` 事件缓冲：高频 delta 合并（150ms/64 条，`events.go:42-43`），先落
+     store（会话内单调 seq）再 `bus.Publish`（`events.go:83`）；
+  2. `internal/bus` 内存总线 → 在线 SSE 订阅者；
+  3. `internal/pgbus`（仅 PG 多实例档）：事务提交后 NOTIFY，其他实例 LISTEN 后按 seq 从库
+     取回转发本地 bus。
+- **事件词汇**全部定义在 `modules/core/events.go` 的 `StreamEvent` 信封
+  （message.delta / thinking.delta / tool.* / run.phase / hitl.request / plan.update /
+  agent.spawn / agent.progress / card.* / artifact.* 等 20+ 类型）。
+
+---
+
+## 5. 持久化与磁盘布局
+
+- 主库：`<data>/agent-system.db`（SQLite，FTS5 全文 + CJK LIKE 兜底）或 PostgreSQL
+  （`--dsn`，pgx 驱动）；迁移双方言可回滚；租户隔离靠 owner 列硬过滤。
+- 工件：`<data>/artifacts/`（blobstore 本地档，Put 原子落盘）+ store 登记。
+- 技能：`<data>/skills/`（内置种子 + 用户覆盖）。
+- 工作区沙箱：`<data>/workspaces/<owner>/<conversationID>/`（fs 工具根）。
+- 小队运行态：编排目录下 `runs/<run_id>/*.json`（磁盘即权威，见小队篇）。
+- 本机服务实例（`scripts/svc.sh` 管理）：`runtime/dev/`（agent 后端 + SQLite）、
+  `runtime/pg1/`（PostgreSQL）；`data/`、`data-test/` 为默认/测试数据目录。
+
+---
+
+## 6. 插件系统
+
+- 契约：`modules/core/plugin.go`（manifest v1：tools/workflows/intents/prompts/panels/
+  cards/commands 等 provides）；`modules/core/plugin_v2.go`（2.0-experimental 窗口：
+  PluginScope 可见性、PluginBackend{inproc|sidecar}、技能/MCP/知识集/解析器/代理声明）。
+- 宿主：`modules/backend/internal/plugins/host.go` —— 「manifest + 声明资产 + 可选代码」，
+  任一资产解析失败整批拒绝（fail-closed），支持热加载 `Reload`；`host_v2.go` 拉起 sidecar
+  进程（注入 `AGENT_HOST_API`/`AGENT_HOST_TOKEN` 环境变量）。
+- sidecar 回调经 `internal/hostapi/server.go` 的 `/host/v1`（kv/audit/commands/llm/search）；
+  进程内插件走 `pkg/extension`（EXT-1）+ `link` 包。
+- 示例：父仓 `plugins/example/`、`examples/sidecar-demo/`、`examples/downstream-rdm/`。
+
+---
+
+## 7. 端到端数据流（用户输入 → 结果返回）
+
+```
+用户输入（中栏）
+  │  POST /api/conversations/{id}/messages        server.go:574 postMessage
+  ├─ "/" 前缀 → cmdbus 命令总线（不启 run，server.go:623）
+  ├─ 附件   → ingest.Parse 文档摄取（并行，互不依赖，server.go:643）
+  ├─ 意图识别 → intentgate（agent-intent 四级漏斗，server.go:655）
+  ├─ 路由裁决 → route.Decide                      route.go:60
+  │     ├─ KindCommand   → cmdbus.Dispatch（直接执行命令）
+  │     ├─ KindWorkflow  → runmgr.StartClaimedWorkflowRun（:996）
+  │     └─ KindTurn      → runmgr.StartClaimedConversationRun（:991）
+  ├─ runmgr 建 Run（pending）落库 → 选 Runner（runmgr.go:918）→ go execute()
+  │     ├─ LLMRunner             → agent-native 内核 ReAct 循环（默认）
+  │     ├─ CompiledWorkflowRunner → wfcompile 编译执行（可由规划子代理生成）
+  │     └─ SquadRunner           → squadadapter → agent-squad 引擎
+  ├─ 一切增量皆事件 → runmgr 缓冲 → store（seq 权威）→ bus → SSE
+  └─ 前端 live.ts 到达序投影 → 中栏对话 / 右栏卡流 / AgentTracker
+```
+
+- HITL：`hitl.request` 卡片（choice/input/confirm/form）→ 用户 `POST /api/hitl/{id}/resolve`
+  → `runmgr.ResolveHITL`（runmgr.go:1261）恢复或转轨。
+- 工件：产物落 blobstore + store → `artifact.created` 事件 → 预览区；quality 六维打分。
+
+---
+
+## 8. 设计文档索引
+
+架构权威文档在 `modules/documents/docs/proposals/`：
+
+- 整体：`2026-09-29-system-skeleton-design-and-plan.md`（骨架设计 + D1–D16 决策，主设计）、
+  `2026-09-30-dual-tier-storage-and-multitenancy.md`（双档存储/多租户）、
+  `2026-10-01-base-extension-roadmap.md`（基座不可改、下游二开）。
+- Agent 栈：`2026-10-01-agent-harness.md`（回合循环、多代理编排）、
+  `2026-10-02-agent-stack-completion.md`（通用智能体/小队/意图）、
+  `2026-10-07-agent-stack-n1q1i1-plans.md`、`n2-plan.md`、`n3-plan.md`（N 系列阶段方案）。
+- 其他：卡片流/收件箱/命令总线/工作区（2026-09-30 三篇）、插件契约 v2、UI 重构等。
+
+---
+
+## 9. 关键文件速查
+
+| 想了解什么 | 看哪里 |
+|---|---|
+| 程序入口与装配 | `modules/backend/cmd/agent-system/main.go`、`internal/app/app.go` |
+| 全部 HTTP 路由 | `modules/backend/internal/server/server.go`（`Handler()`） |
+| Run 状态机与事件 | `modules/core/model.go`、`modules/core/events.go`、`internal/runmgr/runmgr.go` |
+| Agent 执行循环 | `deps/agent-native/runtime/loop.go`、`internal/runtime/llm_direct.go` |
+| 意图识别 | `deps/agent-intent/intent/`、`internal/intentgate/gate.go`、`internal/route/route.go` |
+| 小队引擎 | `deps/agent-squad/squad/`、`internal/squadadapter/adapter.go`、`entry.go` |
+| 工作流 | `internal/workflow/registry.go`（定义）、`internal/wfcompile/`（编译执行）、`internal/runtime/workflow_compiled.go`（入口） |
+| 工具体系 | `modules/core/tools.go`、`internal/tools/registry.go`、`internal/runmgr/runmgr.go:740` |
+| 提示词/技能 | `internal/prompts/service.go`、`internal/skills/skills.go` |
+| 前端投影 | `modules/frontend/src/live.ts`、`src/store.ts` |

docs/guides/intent-recognition.md

@@ -0,0 +1,292 @@
+# Agent 的意图识别：架构、模型与调用链
+
+> 基准：Agent-System-Dev 组合 `218fc4b1ba00b0a03b5bb79f292b3eba6c987a58`（R0，2026-10-08 锚点核验）。
+> 行号为该提交下的函数入口位置（个别内部区段为约略范围），随代码演进漂移；文件与函数名是稳定锚点。
+> `internal/` 指 `modules/backend/internal/`。
+
+---
+
+## 1. 一句话结论
+
+意图识别是**"确定性规则漏斗为主体、语义向量与 LLM 为可选慢通道（默认关闭）"的混合
+分层架构**：识别主体在独立库 `deps/agent-intent`（零 LLM 依赖），backend 通过
+`internal/intentgate` 闸门接入，识别结果由 `internal/route` 统一裁决为
+命令 / 工作流 / 普通回合三分支。
+
+---
+
+## 2. 识别架构：四级漏斗
+
+核心识别器 `FunnelRecognizer`（`deps/agent-intent/intent/recognizer.go:23`，
+入口 `Recognize` 在 `recognizer.go:41`，内部 `recognize` 在 `:71`），四级依次短路：
+
+| 级 | 名称 | 行为 | 代码 |
+|---|---|---|---|
+| Stage 0 | 守卫（guard_hit） | 守卫域 spec 命中即短路，表达"识别即拒绝" | `recognizer.go` 守卫分支 |
+| Stage 1 | 挂起预期（expectation_hit） | 多轮澄清场景：宿主注入 `ExpectationProvider` 声明上轮预期意图 | 接口 `intent/expectation.go:17` |
+| Stage 2+3 | 规则计分 + 置信度裁决 | 全部非守卫 spec 线性扫描（`intent/registry.go` 规则计分与裁决），`score = base + (正则命中 ? pattern_bonus : 0)`，上限 1.0；唯一过阈或前两名分差 ≥ margin（默认 0.1）→ **matched**，同分比 priority → 否则 **ambiguous**，无命中 → **fallback** | `intent/spec.go:17-29`（默认值）、`recognizer.go:146` 附近同分裁决 |
+| Stage 4 | 慢通道（可选） | ambiguous → 语义向量重排 `semanticRerank`（`recognizer.go:292`）；fallback → LLM 命令生成 `generateCommands`（`recognizer.go:333`） | 见下节 |
+
+识别分支共五种（`deps/agent-intent/intent/result.go`）：
+`guard_hit / expectation_hit / matched / ambiguous / fallback`。
+
+---
+
+## 3. 用什么模型：三层各自不同
+
+| 层 | 是否 LLM | 实现与模型来源 | 状态 |
+|---|---|---|---|
+| 规则层（守卫/计分/裁决） | **否，永不引入** | 纯 Go 确定性计算。设计文档明确规则层永不引入 LLM（`deps/agent-intent/docs/records/2026-09-29-decoupling-and-llm-layering.md` §2.1） | **主体，默认生效** |
+| 语义重排（SemanticScorer） | 向量模型（非生成式） | `modules/backend/internal/intentsem/scorer.go:18` `EmbeddingScorer`：对输入与 spec 的 examples 各取向量算最大余弦相似度。Provider 走 OpenAI 兼容 `/embeddings`（`internal/rag/embed.go`），模型/端点来自 settings `models.embedding.*`；默认阈值 0.8（`intent/spec.go`） | 可选，**默认关**（settings `runtime.intentSemantic`） |
+| 命令生成（CommandGenerator） | 生成式 LLM | `modules/backend/internal/intentsem/generator.go:18` `LightGenerator`：走 `agentllm.Client.Stream`，用**轻量档模型**（`internal/runtime/model.go:84` `ResolveLightweightModel`，settings `models.lightweight.model`，缺省回落主 chat 档），MaxTokens 默认 1024；system prompt 在 `generator.go:100-129`（只暴露 id/描述/槽位键，防提示词注入） | 可选，**默认关**（settings `runtime.intentGenerator`） |
+| Classifier（LLM 重打分，L2） | 生成式 LLM | 接口在 `intent/classifier.go:9` | **接口预留，backend 未接线** |
+
+慢通道装配点：`modules/backend/internal/app/app.go:351,357`（开关开启才
+`gate.SetSemantic(...)` / `gate.SetGenerator(...)`）。关闭时行为与纯规则版完全一致。
+
+**失败安全**：agent-intent 库本体零 LLM 依赖，只定义 `SemanticScorer`
+（`intent/semantic.go:9`）与 `CommandGenerator`（`intent/generator.go:14`）窄接口由
+宿主注入；所有慢通道失败均回退规则结论（fail-open/closed 到 safe 分支），识别永不因
+LLM 失败而失败。生成器幻觉有校验兜底：`validateGenerated`
+（`recognizer.go:368`）要求 action.id/槽位键必须都在目录内，否则 fail-closed 回 fallback。
+
+---
+
+## 4. 意图目录（Intent Catalog / Schema）
+
+意图定义 `IntentSpec`（`deps/agent-intent/intent/spec.go:74` 附近，Go 注册与 JSON overlay 共用）：
+
+- **标识**：`id`（必须 `domain.助记` 多段，`spec.go:122` 校验）、`domain`、`version`、
+  `description`、`priority`、`disabled`。
+- **matcher**（`spec.go:32-39`）：`includes_any / includes_all / excludes_any` 词表 +
+  `patterns` 正则 + `case_sensitive` + `boundary`（词界匹配，压制中文子串误命中）。
+- **slots**（`spec.go:44-62`）：`key/required/pattern(抽取正则)/group`，加 HITL 字段
+  `label/question`（建议澄清提问）与校验链 `enum/format/normalize/validator`。
+- **confidence**（`spec.go:66-70`）：base 默认 0.7、pattern_bonus 默认 0.2、threshold 默认 0.6。
+- **动作绑定**：`action`（kind ∈ command/workflow/blueprint/handler，`intent/command.go:32-43`）
+  优先，其次 `metadata["blueprint"]`、再次 `handler`，否则 auto（宿主在命令总线与工作流间裁决）。
+- **risk**（low/medium/high）+ `requires_confirm`（透传宿主做授权确认）。
+- **examples**：示例句数组——语义慢通道按它们算相似度。
+
+配置文件形态（`intent/loader.go:12-19`）：
+
+```json
+{ "intents": [ { …IntentSpec… } ], "disable": ["demo.run.status_query"] }
+```
+
+插件可经 `intents/*.json` overlay 注入（`internal/plugins/host.go:216-220` 采集）。
+样例：`deps/agent-intent/examples/specs/demo.json`。
+
+识别产物命令集（`intent/command.go:11-26`）：`start / set_slot / change_slot / cancel /
+clarify / chitchat / handoff`；规则漏斗只产出 start/set_slot/clarify（`deriveCommands`
+在 `command.go:85`）。能力目录 `Snapshot.Catalog()` / `CatalogMarkdown()`
+（`intent/catalog.go:36,68`）把启用意图渲染为 Markdown，供小队规划者/Leader 提示词注入
+（`deps/agent-squad/adapters/intent/catalog.go` 消费）。
+
+## 4.5 内置与默认意图：默认是空目录
+
+**系统默认不内置任何意图**：backend 组合根 `intentgate.New()`（`app.go:309`）起步是空注册表，
+`g.Match` 在空闸门下直接透传（未启用 = 行为回退，所有消息走普通回合）。意图只能经两条
+overlay 路径进入，且**两种路径的文件形态不同**：
+
+| 路径 | 文件形态 | 装载方 |
+|---|---|---|
+| 插件 overlay（产品路径） | **裸数组** `[ {…IntentSpec…}, … ]` | `plugins/host.go:216-220` 按元素透传 → `gate.Rebuild`（gate.go:104）逐个 unmarshal 成 IntentSpec |
+| registry/loader（库路径：intentctl、BuildFS） | 包装对象 `{"intents":[…], "disable":[…]}` | `intent/loader.go:21` `overlayDoc`，严格 JSON（未知字段报错） |
+
+仓库自带两份样例意图（即"默认能看到的意图"上限——装载对应插件/配置后生效）：
+
+- `plugins/example/intents/demo.json`（插件形态）：`demo.show`（命中"示例/演示"，无槽位）、
+  `demo.brief`（命中"简报"，必填槽位 `topic`，抽取正则 `主题[:：]\s*(\S+)`，缺槽问"主题是什么？"）。
+- `deps/agent-intent/examples/specs/demo.json`（loader 形态）：`demo.run.status_query`
+  （命中"进度/状态"、排除"配置"，槽位 `run_id`，base=0.8/threshold=0.7，handler=`taskrun.query_status`）、
+  `demo.run.restart`（需同时含"重启"+"任务"，`requires_confirm=true`，risk=medium）。
+
+---
+
+## 4.6 实测：一句话怎么被打分、填槽、命中
+
+以下全部为 `intentctl explain` 在样例配置上的**真实输出**（2026-10-08 实测；例 5/6 的配置目录
+= 两份样例意图合并）。打分公式：`score = base + (正则命中 ? pattern_bonus : 0)`（封顶 1.0），
+前两名分差 < `margin`（默认 0.1，`intent/registry.go:55`）判 ambiguous。
+
+**例 1｜命中 + 抽到槽位**（输入"查一下任务 run_42 的进度"）：
+
+```
+分支：matched
+Top：demo.run.status_query 置信度=0.8000 风险=low 确认=false handler=taskrun.query_status
+  槽位 run_id="run"
+候选（1）：
+  0.8000  demo.run.status_query        terms=进度
+裁决轨迹：
+  margin=0.1000
+  守卫：未评估
+  规则 命中 demo.run.status_query        0.8000 进度
+  规则 排除 demo.run.restart             no_positive_match
+```
+
+要点：`terms=进度` 命中词表加 0 分（base 已含）；`restart` 因 `includes_all:["任务"]` 缺"重启"
+被排除（`missing_includes_all`）。槽位 `run_id="run"` 是真实结果——槽位正则
+`(?:run|任务)[:# ]*([A-Za-z0-9-]+)` 的字符类不含下划线，捕获在 `run` 后被 `_` 截断：
+**规则识别完全确定性，槽位 pattern 的质量决定抽取质量**（写 `[A-Za-z0-9_-]+` 即可取到 `run_42`）。
+
+**例 2｜命中但缺必填槽位**（输入"写一份简报"，`demo.brief` 装载时）：
+
+```
+分支：matched
+Top：demo.brief 置信度=0.7000
+  缺失必填槽位：topic
+裁决轨迹：
+  规则 命中 demo.brief                   0.7000 简报
+  规则 排除 demo.run.restart             missing_includes_all:任务
+  规则 排除 demo.run.status_query        no_positive_match
+  规则 排除 demo.show                    no_positive_match
+```
+
+`Missing=[topic]` 连同 spec 的 `question:"主题是什么？"` 一起随 route 进入工作流 run，
+由 HITL 输入卡向用户澄清（见调用链第 10 步）。
+
+**例 3｜槽位填上**（输入"主题：核能 写一份简报"）：同一意图 matched，
+`槽位 topic="核能"`，Missing 为空——正则 `主题[:：]\s*(\S+)` 命中，直接启动。
+
+**例 4｜什么都不像**（输入"随便聊聊今天的天气"）：
+
+```
+分支：fallback
+裁决轨迹：
+  规则 排除 demo.run.restart             missing_includes_all:任务
+  规则 排除 demo.run.status_query        no_positive_match
+```
+
+无命中 → fallback；若装载了语义慢通道（`runtime.intentSemantic`，默认关）会先尝试 embedding
+重排，仍不达阈才 fallback。gate 把 fallback 折叠后 `route.Decide` 判 `KindTurn` → 普通对话回合。
+
+**例 5｜能力目录实测**（`intentctl catalog`，这段 Markdown 就是注入小队规划者/Leader
+提示词的内容，`squad/engine.go:44` 注释明示用途）：
+
+```
+# 系统能力目录（意图快照 revision=1）
+
+以下能力可直接调用，无需派智能体执行。子任务命中其一时，输出携带 intent_id 的步骤并填齐必填槽位；
+必填槽位信息不足时不要编造，改为向用户澄清（优先使用各槽位的提问建议）。
+
+## demo.brief — 写一份简报。必填槽位 topic，没写就问「主题是什么？」。
+- 风险：low；执行前需人工确认：否
+- 槽位 topic（必填，topic）
+  - 提问建议：主题是什么？
+```
+
+---
+
+## 4.7 一句话里有多个意图怎么办
+
+意图层的契约是**一条输入只产出一个 Decision**（top-1），不做多意图拆分。多个候选的
+裁决顺序固定为：
+
+1. **分差裁决**：唯一过阈，或第一名领先 ≥ margin → 直接 matched。
+2. **同分且 priority 不同 → 高优先级直接胜出**（I5，不标歧）。实测（"帮我生成一份报告"，
+   两个意图 base 都是 0.7、词表都命中"报告"）：template 设 `priority:10` 后
+   `分支：matched，Top：demo.report.template 置信度=0.7000`。
+3. **分差 < margin（含同分同优先级）→ ambiguous**，先走可选语义重排 `semanticRerank`
+   （`recognizer.go:292`，默认关）→ 再走 Classifier L2 重打分（backend 未接线）→ 都没有则
+   **保持 ambiguous**。实测同配置去掉 priority 后：
+   `分支：ambiguous，候选（2）：0.7000 demo.report.generate / 0.7000 demo.report.template`。
+4. ambiguous 经 gate 折叠 → `KindTurn` → **交给普通 LLM 回合**：模型在一次 ReAct 循环里
+   自行处理多个请求（这也是多数"一句话多个事"的实际归宿——意图层只接管高确定性的
+   命令/工作流类请求）。
+5. 多轮场景：Stage 1 挂起预期（`ExpectationProvider`）让澄清中的输入优先回到挂起意图；
+   HITL 自由输入命中其他意图时会**取消挂起 run 并转轨**（`runmgr.go:1261` `ResolveHITL`），
+   相当于允许用户中途改道。
+
+---
+
+## 5. 端到端调用链：用户输入一条消息后发生了什么
+
+| # | 步骤 | 调用方 → 被调方 | 位置 |
+|---|---|---|---|
+| 1 | HTTP 入口 | 路由注册 `POST /api/conversations/{id}/messages` | `internal/server/server.go:168`（注册）、`:574` `postMessage` |
+| 2 | slash 短路 | `/` 前缀非技能命令 → `handleCommand`（`server.go:756`）→ 命令总线，**不进意图识别** | `server.go:623` |
+| 3 | 附件摄取 | `ingest.Parse(name, mime, content)` → `core.ParsedDocument`（与意图识别并行、互不依赖） | `server.go:643`；`internal/ingest/ingest.go` |
+| 4 | 识别调用 | `s.recognize(ctx, text)`（端口 `NLIntentGate`，`server.go:79-85`） | `server.go:655` |
+| 5 | 进入闸门 | `intentgate.Gate.Recognize` | `internal/intentgate/gate.go:137` |
+| 6 | 四级漏斗 | `FunnelRecognizer.Recognize(ctx, input, reg.Snapshot())` | `gate.go:144` 附近 → `deps/agent-intent/intent/recognizer.go:41` |
+| 7 | 结果投影 | 库 `Result` → `MatchResult{Branch, ID, Slots, Missing, Commands}`；guard/expectation 折叠为 fallback；缺槽位附 spec 的 Question | `gate.go:148-176` |
+| 8 | 统一路由 | `route.Decide(recognized, route.Env{HasCommand, WorkflowFor, SquadReady})` | `server.go:656`；`internal/route/route.go:60` |
+| 9a | 命令分支 | KindCommand → `s.Bus.Dispatch`（Entrance="chat"，槽位透传 Params） | `server.go:701-717` |
+| 9b | 工作流分支 | KindWorkflow → `mgr.StartClaimedWorkflowRun`（缺槽位列表随行） | `server.go:725`；`internal/runmgr/runmgr.go:996` |
+| 9c | 回合分支 | KindTurn → `ClaimConversation` 抢槽 → `AppendMessageWithRequest` 落库 → `mgr.StartClaimedConversationRun` | `server.go:679, 727`；`runmgr.go:980, 991` |
+| 10 | 澄清/HITL | 工作流缺必填槽位 → 逐个发 `HITLCard{Kind:Input, AllowFreeInput}` 人工输入卡 | `internal/wfcompile/run.go:47` 起 `RunCompiled` 槽位补齐段 |
+| 11 | HITL 转轨 | `POST /api/hitl/{id}/resolve` → `mgr.ResolveHITL`：自由输入以 `/` 开头 → pivot=command；否则再过 `gate.Recognize` + `route.Decide`，命中其他意图则取消挂起 run 并 pivot | `server.go:883`；`runmgr.go:1261`（转轨判定 `:1293` 附近） |
+
+### 启动期装配链
+
+| # | 内容 | 位置 |
+|---|---|---|
+| A1 | `app.Run` 建 `gate := intentgate.New()` 并 `mgr.SetGate(gate)` | `internal/app/app.go:309-310`；`runmgr.go:142` |
+| A2 | 插件装载回调：`pluginHost.OnIntents = overlay → gate.Rebuild(overlay)`（fail-closed：解析失败保留上一快照） | `app.go:324`；`internal/plugins/host.go:216-220`；`gate.go:96` |
+| A3 | 开关开启时接线慢通道：`gate.SetSemantic(intentsem.EmbeddingScorer{…})` / `gate.SetGenerator(intentsem.LightGenerator{…})` | `app.go:351,357`；`gate.go:66,75` |
+
+---
+
+## 6. intentgate 与 intentsem 的分工
+
+- **intentgate**（`internal/intentgate/gate.go`）：宿主闸门适配器。持 Registry +
+  FunnelRecognizer；负责插件 overlay 装载（`Rebuild`，`:96`）、分支折叠（非
+  matched/ambiguous 一律折叠为 fallback，`gate.go:148-155`）、补槽位 Question、
+  类型投影（让 runmgr/route 只依赖本包表面）、慢通道接线（`:66,75`）。
+  **不做缓存**——识别是纯函数 Query，快照不可变无锁读（`intent/registry.go`）。
+- **intentsem**（`internal/intentsem/`）：慢通道实现包。`EmbeddingScorer` 出错原样上抛
+  （库保持 Ambiguous）；`LightGenerator` 解析失败/模型不可达返回错误（库保持 fallback）。
+
+---
+
+## 7. 识别结果的去向与失败路径
+
+- 识别结果 `Result`（`intent/result.go`）是**纯内存 Query 结果，不落库**（store 无
+  intent 表）。去向仅三处：① HTTP 响应；② logsys 结构化日志 `intent recognized`
+  （`recognizer.go:62` 附近，不记原文）；③ 作为 run 启动参数（workflow slots/missing、命令 ID）。
+- **ambiguous**（重排后仍歧义）→ gate 折叠 → `route.Decide` 返回 `KindTurn`
+  （`route.go:61-63`）→ 走普通 LLM 回合自由对话兜底（不是强制澄清）。
+- **matched 但缺必填槽位** → Commands=[start, clarify]（`intent/command.go:110` 附近）→
+  workflow 路径把 Missing（含建议 Question）传入 run → 发 HITL 输入卡澄清。
+- **guard_hit / expectation_hit** → 折叠为 fallback → turn。
+- **低置信度**（未过 threshold）→ fallback → turn。
+
+route 决策细节（`internal/route/route.go:55-114`）：优先级
+命令 > 工作流 > 普通回合；`blueprint` → `KindSquad`，但**当前不可达**——
+`server.go:664` 明确注释 `SquadReady 保持 false`（per-run entry 覆盖未就位），
+小队的实际启动走别的路径（见[小队与子 Agent 启动](squad-and-subagents.md)）。
+声明目标不可解析时不静默错配，回落 turn 并写 Reason。
+
+---
+
+## 8. 辅助工具与测试
+
+- `deps/agent-intent/cmd/intentctl/`：只读诊断 CLI（`lint` 校验配置+词条冲突、
+  `explain` 单条输入裁决轨迹（`recognizer.go:226` `Snapshot.Explain`）、
+  `eval` 语料评测 Precision/Recall、`catalog` 输出目录）。
+- `deps/agent-intent/conformance/conformance.go`：识别器公开契约行为验收
+  （分支/槽位断言 + 确定性 + 并发冒烟）。
+- `deps/agent-intent/catalogcheck/align_test.go`：断言库错误码与 Error-Code-System
+  intent 域种子码逐个相等，防两套平行权威。
+
+---
+
+## 9. 关键文件清单
+
+| 文件 | 职责 |
+|---|---|
+| `deps/agent-intent/intent/recognizer.go` | 四级漏斗识别器、语义重排（:292）、生成兜底（:333）、Explain 诊断（:226） |
+| `deps/agent-intent/intent/spec.go` | IntentSpec/MatchSpec/SlotSpec/ConfidenceSpec 定义与校验 |
+| `deps/agent-intent/intent/registry.go` | 编译、不可变 Snapshot、双源合并、原子 Reload |
+| `deps/agent-intent/intent/loader.go` | JSON overlay 加载 |
+| `deps/agent-intent/intent/command.go` | 命令模型 + deriveCommands（:85）展开 |
+| `deps/agent-intent/intent/catalog.go` | 能力目录与 Markdown 渲染（:36/:68/:128） |
+| `deps/agent-intent/intent/semantic.go` `generator.go` `classifier.go` `expectation.go` | 四个可注入端口 |
+| `deps/agent-intent/cmd/intentctl/main.go` | 诊断 CLI |
+| `modules/backend/internal/intentgate/gate.go` | 闸门适配器（overlay :96、投影、慢通道接线 :66/:75） |
+| `modules/backend/internal/intentsem/generator.go` `scorer.go` | LLM 命令生成（含 system prompt :100）/ embedding 重排 |
+| `modules/backend/internal/route/route.go` | 唯一 Router（Decide :60 三分支裁决） |
+| `modules/backend/internal/server/server.go` | 消息入口 postMessage(:574)、recognize(:655)、resolveHITL(:883)、SSE events(:275) |
+| `modules/backend/internal/plugins/host.go` | 插件 intents/*.json overlay 采集（:216-220） |
+| `modules/backend/internal/app/app.go` | 组合根装配（:309-310、:324、:351/:357） |

docs/guides/plugin-development.md

@@ -5,6 +5,8 @@
 
 参考实现：Dev 仓 `plugins/example`（覆盖全部五类能力，可直接复制改造）。
 
+契约 v2（声明 / 进程内编译 / sidecar / 前端 ESM，下游仓不得改基座）见提案 `docs/proposals/2026-10-01-plugin-contract-v2.md`。`make plugin-new NAME=<id>` 生成声明式骨架。
+
 ## 1. 目录结构
 
 ```

docs/guides/squad-and-subagents.md

@@ -0,0 +1,133 @@
+# 何时启动小队或子 Agent：触发条件与调用链
+
+> 基准：Agent-System-Dev 组合 `218fc4b1ba00b0a03b5bb79f292b3eba6c987a58`（R0，2026-10-08 锚点核验）。
+> 行号为该提交下的函数入口位置（个别内部区段为约略范围），随代码演进漂移；文件与函数名是稳定锚点。
+> `internal/` 指 `modules/backend/internal/`。
+
+---
+
+## 1. 一句话结论
+
+系统有两条"委派"线，都发生在**普通 run 的执行过程中**（小队不是独立的一层）：
+
+- **子代理（sub-agent）**：模型在回合中调用 `delegate_task` 工具 → runmgr 派生
+  `Kind=subagent` 的子 run（任务树）。
+- **小队（squad）**：三条触发路径 —— ① 设置 `runtime.entry=squad` 让**对话本身**
+  走 SquadRunner；② 模型调用 `squad_orchestrate` 工具；③ 演示消息含 `#squad`。
+  三者最终都汇入 `deps/agent-squad` 引擎。**成员执行统一走 agent-native 内核**
+  （legacy 的 agent-system 子 run 压缩路径已退役，`internal/squadadapter/adapter.go:289-292`
+  注释明示；后端缺席时 fail-closed，不静默降级）。
+
+另有第三种"规划委派"：`run_workflow` 触发的**规划子代理**（workflowPlannerID），
+见[任务规划与执行](task-planning-and-execution.md)第 7 节。
+
+---
+
+## 2. 子代理：`delegate_task` 触发链
+
+### 触发条件
+
+主对话模型判断某段工作适合独立完成（如长调研、批量整理）时，在 ReAct 循环里发出
+`delegate_task` 工具调用（工具名常量 `internal/runtime/llm.go:58`）。工具声明与门禁在
+`internal/runtime/llm.go:267-315`（编排型工具随上下文声明；子代理 spec 由 prompts 包提供
+tools/model/maxTurns 约束，**禁止子代理再持有派发类工具**，`internal/prompts/service.go`）。
+
+### 调用链
+
+| # | 步骤 | 位置 |
+|---|---|---|
+| 1 | 内核循环解析出 `delegate_task` 调用 → `runTool` 分派 | `internal/runtime/llm_direct.go:471` `runTool`，case 在 `:493` 起 |
+| 2 | 后台模式：经 rc 端口断言调 `SpawnBackground`；前台：`SpawnAgent` | `llm_direct.go:502, 516` 附近 |
+| 3 | runmgr 派生子 run | `internal/runmgr/runmgr.go:1348` `spawnSubagent` → `:1358` `startChild`（**深度检查**在此，注释 `:1356`） |
+| 4 | 建 `Kind=subagent` 子 run，`ParentRunID` 指向父 run（**任务树**） | `runmgr.go` startChild 内；契约 `modules/core/model.go:188` |
+| 5 | 发 `agent.spawn` 事件（前端 AgentTracker 可见） | `runmgr.go:1375` |
+| 6 | 独立 ctx 执行（后台模式 detach） | `runmgr.go` startChild 内 |
+| 7 | 子代理执行器 = `SubLLMRunner.Execute` —— 同样进入 `nruntime.Run` 内核循环（独立转录、按子代理 spec 收窄工具） | `internal/runtime/sub_loop.go:31` |
+| 8 | 完成回填 `AgentResultPayload`；结果截断 32000 字 | `runmgr.go:1401` `finishChild`；`runmgr.go:1780` `capSubagentResult` |
+
+### 后台子代理
+
+- `delegate_task` 可请求后台模式 → `spawnBackground`（`runmgr.go:1475`），
+  **每会话上限 3 个**（`runmgr.go` 常量）。
+- 后台子代理完成后不直接打扰当前回合，而是进通知队列：`deliverNotices`
+  （`runmgr.go:1560`）在会话空闲时以 system-reminder 消息启动一个新父回合汇报结果
+  （`startNoticeRun`，`runmgr.go:1616`）。
+- 取消级联：子 run 的 ctx 派生自父 run，`CancelRun`（`runmgr.go:1222`）取消根 run
+  即级联取消全部子 run。
+
+---
+
+## 3. 小队：三条触发路径
+
+### 路径 A：`squad_orchestrate` 工具调用（工具路径）
+
+| # | 步骤 | 位置 |
+|---|---|---|
+| A1 | 模型在回合中调用 `squad_orchestrate goal=...` | 工具名常量 `internal/runtime/llm.go:62`；声明 `llm.go:268` 附近 |
+| A2 | 声明门禁：settings `runtime.squad`（默认 true）开启才声明；**entry 已是 squad 时不再提供，避免套娃** | `internal/runtime/llm.go:467` `squadToolEnabled`；`:266` 注释 |
+| A3 | runTool 分派 → `squadadapter.Orchestrate(rc, dataDir, goalText)` | `internal/runtime/llm_direct.go:479` → `internal/squadadapter/adapter.go:47` `Orchestrate` |
+| A4 | 之后进入 agent-squad 引擎（规划→调度→质检） | 见[小队工作机制](squad-mechanics.md) |
+
+### 路径 B：对话入口模式（entry=squad）
+
+| # | 步骤 | 位置 |
+|---|---|---|
+| B1 | 灰度开关 `runtime.entry=squad`（默认 `direct`） | `internal/settings/settings.go:90` |
+| B2 | runmgr 选 Runner：`selectConversationRunner` 检查 `runtime.entry=="squad"` → 返回 SquadRunner | `internal/runmgr/runmgr.go:918`（注入点 `:908` `SetSquadRunner`，装配 `internal/app/app.go:306`） |
+| B3 | `SquadRunner.Execute`（`internal/runtime/squad_runner.go:26`）先做 **LLM 分诊**：`modelRouter.Route`（`:146`，轻量模型输出 JSON `direct|plan`，`parseRoute` :167）—— direct = 单步 assistant 直通（`deps/agent-squad/squad/router.go:55` `directAssistantPlan`）；plan = 进 Leader 委派（`router.go:29` `applyRoute` 设 `metadata["mode"]="leader"`） | |
+| B4 | plan 模式 → `squadadapter.RunEntry` → 引擎 leader 模式 | `internal/squadadapter/entry.go:42` `RunEntry`；`deps/agent-squad/squad/engine.go`（`RunOptions.Mode="leader"`，Options 注释 `engine.go:99-105`） |
+
+### 路径 C：演示/脚本
+
+用户消息含 `#squad` → MockRunner 走同样 `Orchestrate`（`internal/runtime/mock.go`）。
+
+### 一条"不可达"的路径（设计预留）
+
+意图识别绑定 `blueprint` 动作可路由到 `KindSquad`（`internal/route/route.go:96-97`），
+但当前**双重不可达**：`server.go:664` 明确注释 `SquadReady 保持 false`（per-run entry
+覆盖未就位）；且系统默认意图目录为空（见[意图识别](intent-recognition.md) 4.5 节），
+不装插件就没有意图可命中 blueprint。小队的实际启动走上面 A/B/C 三条路径；意图目录
+对小队的现实作用是注入规划者/Leader 提示词的能力目录（`deps/agent-squad/adapters/intent/catalog.go`）。
+
+---
+
+## 4. 装配（启动期）
+
+| 内容 | 位置 |
+|---|---|
+| runmgr 注入三个 runner（LLMRunner / SubLLMRunner / MockRunner），SquadRunner 经 `SetSquadRunner` | `internal/app/app.go:287-306` |
+| 角色指令来源接提示词库（`agent.squad.<kind>`） | `app.go:176` → `squadadapter.RoleInstructions`（`adapter.go:303`） |
+| agent-native 内核选项：模型路由、Tavily 搜索、解释器、MCP、技能根、Subagent 桥接、PermissionAsk、检查点 | `app.go:196` `squadadapter.AgentNativeOptions` |
+| 小队后端解析器：**只注册 `"agent-native"` 内核工厂**（legacy `"agent-system"` SpawnSubagent 压缩路径已退役删除；工厂缺席解析 fail-closed） | `internal/squadadapter/adapter.go:292` `BuildBackends`（退役注释 `:289-291`）；`entry.go:103` DefaultBackend="agent-native" |
+| 内核工厂注册 | `deps/agent-squad/adapters/native/register.go:61` `RegisterFull` |
+
+---
+
+## 5. 两条线的对比小结
+
+| | 子代理 delegate_task | 小队 squad |
+|---|---|---|
+| 触发者 | 主对话模型 | 设置开关 / 主对话模型 / 演示脚本 |
+| 执行单位 | 一个子 run（`Kind=subagent`） | 一组角色化步骤（每步一个 agent-native 内核 agent） |
+| 编排者 | 主对话（单层委派，子代理不可再委派） | agent-squad 引擎（DAG 调度 / Leader 循环） |
+| 并发 | 后台最多 3/会话 | 无写集冲突的步骤可并行 |
+| 深度 | 1 层（startChild 深度检查，`runmgr.go:1356-1358`；子代理 spec 禁派发工具） | 成员内核里的 `delegate_task` 经 `SubagentFactory`（`adapter.go:234`）桥回产品 `SpawnSubagent`，**深度恒为 1，子 run 不再嵌套小队** |
+| 汇总 | `AgentResultPayload` 回父 run | 交付物聚合 `output.md` → 主 run 工件（见[小队工作机制](squad-mechanics.md)） |
+
+---
+
+## 6. 关键文件清单
+
+| 职责 | 文件 |
+|---|---|
+| delegate_task 分派 | `internal/runtime/llm_direct.go:493` 起 |
+| 子 run 派生与任务树 | `internal/runmgr/runmgr.go:1348-1475`、`1560-1616` |
+| 子代理执行器 | `internal/runtime/sub_loop.go` |
+| 工具声明与门禁 | `internal/runtime/llm.go:267-315, 466-467` |
+| squad_orchestrate 分派 | `internal/runtime/llm_direct.go:479` |
+| 小队适配器（工具路径 + 后端组装 + Subagent 桥接） | `internal/squadadapter/adapter.go`（Orchestrate :47、SubagentFactory :234、BuildBackends :292、builtinRoles :306） |
+| 小队适配器（入口路径） | `internal/squadadapter/entry.go`（RunEntry :42、kernelRoles :177） |
+| 对话入口 Runner + LLM 分诊 | `internal/runtime/squad_runner.go`（Execute :26、Route :146） |
+| Runner 选择 | `internal/runmgr/runmgr.go:918` |
+| 灰度开关 | `internal/settings/settings.go:90` |
+| 装配 | `internal/app/app.go:176, 196, 287-306` |

docs/guides/squad-mechanics.md

@@ -0,0 +1,226 @@
+# 小队（Squad）工作机制：拆解、执行、汇总的完整调用链
+
+> 基准：Agent-System-Dev 组合 `218fc4b1ba00b0a03b5bb79f292b3eba6c987a58`（R0，2026-10-08 锚点核验）。
+> 行号为该提交下的函数入口位置（个别内部区段为约略范围），随代码演进漂移；文件与函数名是稳定锚点。
+> `internal/` 指 `modules/backend/internal/`；`squad/` 指 `deps/agent-squad/squad/`。
+
+---
+
+## 1. 一句话结论
+
+小队是 run 内的一种**编排执行模式**：由 agent-squad 引擎（`deps/agent-squad`）把目标
+拆成**角色化步骤 DAG**（规则规划器或蓝图模板），每一步交给一个"成员"执行——成员是
+按角色装配的 **agent-native 内核 agent**（独立执行循环；legacy 的 agent-system 子 run
+压缩路径已退役），无写集冲突的步骤并行推进，产出落子工作区并经**黑板**共享，收口时做
+六维质检与自动修复，交付物聚合回主 run。
+
+触发时机（何时启动）：settings `runtime.entry=squad`（对话即小队）、模型调用
+`squad_orchestrate` 工具、演示消息 `#squad`——详见[小队与子 Agent 启动](squad-and-subagents.md)第 3 节。
+
+---
+
+## 2. 概念模型（类型全部在 `deps/agent-squad/squad/models.go`）
+
+| 类型 | 位置 | 含义 |
+|---|---|---|
+| `RoleSpec` 角色 | models.go:25 | role/name、绑定执行后端 `Backend`（stub/llm/agent-native/…）、角色级 Model、工具白名单 Tools、技能 Skills、**BashPermission 三态 allow/ask/deny**、Keywords（规则规划器匹配用）、Instructions、HITL 策略、`MaxConcurrentTasks` 并发限流 |
+| `Goal` | models.go:48 | 目标文本 + Materials 附件 + Constraints + HITL 覆盖 |
+| `Blueprint` | models.go:64 | 任务模板：关键词命中即走基线步骤 |
+| `StepSpec` 步骤 | models.go:86 | Role、Targets（期望交付物文件，缺省 output.md）、`Writes` 写集（写集相交强制串行）、`Needs` 依赖、`Parallel`、`Critical`（失败即终止）、`MinScore` 质检门槛、`RequiresApproval`、`IntentID/IntentSlots`（系统功能步，不走智能体）、Attempts |
+| `WorkflowPlan` + `SquadConfig` | models.go:168, 179 | 拆解结果（与产品 squad workflow.json / squad.json 兼容） |
+| `BlackboardState` 黑板 | models.go:225 | Facts/Gaps/Implications/Assumptions/Fields —— 成员间协作的共享状态载体 |
+
+**小队成员 ≠ 常驻 agent**：成员 = 角色（RoleSpec）。每条步骤由
+`BackendResolver.Resolve`（`squad/backend.go`）解析出一个 Executor 并调用一次
+`Execute`。产品侧**只注册 agent-native 后端**（`internal/squadadapter/adapter.go:292`
+`BuildBackends`；`deps/agent-squad/adapters/native/register.go:61` `RegisterFull`），
+每步构造一个独立内核 agent 执行循环（模型/工具/搜索/MCP/技能根按 RoleSpec 装配）。
+
+---
+
+## 3. 小队 Run 状态机
+
+`squad/models.go:284` 起（`RunStatus`）：
+
+```
+created → planning → (awaiting_clarification | awaiting_confirmation)   ← HITL 挂起
+        → executing → (waiting_human | quality_review)                  ← HITL 挂起
+        → completed | degraded | failed | cancelled                     ← 终态
+```
+
+- 挂起态判定与适配：适配器 `isHoldStatus`（`internal/squadadapter/adapter.go:221`）据此进 HITL。
+- 挂起上下文 `HitlGate`（Request+Plan+PrevStatus）落盘 `pending.json`；`Respond`
+  （`squad/engine.go:637`）按多种 Kind 分派恢复：Clarification 答案并入 Goal 重新规划、
+  Confirmation、Gap、Escalation、Adjustment、Permission、QualityReview；执行态恢复走
+  `Resume`（`squad/engine.go:1127`）。
+
+**事件体系**：引擎 `squad.Event` 13 类（`squad/progress.go:10-24`：run_started /
+phase / step_started / completed / failed / skipped / detail / deliverable /
+human_input_required / human_responded / run_completed / failed / cancelled）。
+产品侧不直连 bus：`onSquadEvent`（`internal/squadadapter/adapter.go:185`）把 step_* 映射为
+`core.EvAgentProgress`，计划经 `mapPlan`（`adapter.go:200`）映射为 `rc.UpdatePlan` →
+`core.EvPlanUpdate`，成员子 run 发 `core.EvAgentSpawn` —— 统一进事件流，**前端可看到
+小队进展**（`modules/frontend/src/store.ts`、`contracts.ts` 消费 agent.spawn/plan.update/agent.progress）。
+
+**运行状态持久化（磁盘即权威）**：`workspace.json / workflow.json / squad.json /
+blackboard.json / pending.json / runstate.json / usage.json`
+（`squad/runstate.go:13` 注释、`:81` `persist`）；崩溃恢复 `Resume → recoverInterrupted`
+（产物已齐判完成防副作用翻倍）。支持运行中 Steering 与黑板字段注入自动唤醒 `SweepWakeups`。
+
+---
+
+## 4. 端到端调用链（以 `squad_orchestrate` 工具路径为主线）
+
+| # | 步骤 | 位置 |
+|---|---|---|
+| 1 | 触发：`llm_direct.go:479` case toolSquad → `squadadapter.Orchestrate` | `internal/runtime/llm_direct.go:479` → `internal/squadadapter/adapter.go:47` |
+| 2 | 编排进度卡（可选）：创建 `CardKindProgress` 卡，终态置态 | adapter.go `Orchestrate` 内（CardSink 端口 `:40`） |
+| 3 | 注册内置角色 `builtinRoles()`（`adapter.go:306`）：规划员/调研员/撰稿员/审校员，**全部 Backend=agent-native**；工具白名单按角色最小化（全员含 write_file，步骤须自己落盘交付物）；撰稿员 `BashPermission=ask` + docx/xlsx/pptx-author 技能，其余角色 Bash=deny；指令来源 `RoleInstructions`（:303，接提示词库 `agent.squad.<kind>`） | |
+| 4 | 组装后端 `BuildBackends`（`adapter.go:292`）：只注册 `"agent-native"` 内核工厂（组合根 `AgentNativeOptions`，`internal/app/app.go:196`）；legacy `"agent-system"` 已退役；工厂缺席 fail-closed | |
+| 5 | 组装引擎 `squad.NewEngine(Options{…})`：Planner=RulePlanner、Checker=quality.Checker、RepairBudget、HitlPolicy、Sink=ProgressFunc(onSquadEvent)；引擎默认 `DefaultBackend="stub"`（`squad/engine.go:169-170`）、单步超时默认 10 分钟（Options 注释 `:32`） | `adapter.go` Orchestrate 内；`squad/engine.go` |
+| 6 | `SquadEngine.Run`（`squad/engine.go:234`）：生成 `run_<UTC时间戳>` ID → `acquire`（`:213`，进程内 mutex + flock 文件锁，单 run 单控制操作）→ `EvRunStarted` → 可选**意图闸门**一次裁决（GuardHit→Reject；命中 blueprint→定向模板；否则不干预；实现 `deps/agent-squad/adapters/intent/gate.go`） | |
+| 7 | **任务拆解（规划）** `planAndExecute`（`squad/engine.go:335`）：先 Router 分诊；未 direct 则蓝图匹配 + `Planner.Plan`（`squad/planner_rule.go:20`）。产品用 **RulePlanner（确定性规则，非 LLM）**：命中 Blueprint 直接用模板步骤/编制（`fromBlueprint`，planner_rule.go:27）；未命中走四阶段骨架 **梳理(organizer)→专项(specialist)→成文(writer)→终审(leader)**（planner_rule.go:85 起），注册表缺角色时 `Registry.Derive` 现场派生并置 `NeedsConfirmation`。LLM 规划器已实现（`squad/planner_llm.go`，严格 JSON+重试+Fallback）但产品未接。拆解结果持久化 `runs/<run_id>/workflow.json + squad.json`（`squad/runstate.go:81` `persist`） | |
+| 8 | 澄清/确认挂起：规划歧义 → `awaiting_clarification`；派生编制 → `awaiting_confirmation`（leader 模式豁免）。适配器驱动循环（`adapter.go` Orchestrate 内）：hold 态 → `askHuman`（`adapter.go:150`，HumanRequest→core.HITLCard→`rc.AskHITL`）→ `engine.Respond`（`engine.go:637`）；执行态 → `engine.Resume`（`engine.go:1127`）。每次推进后 `mapPlan`（`adapter.go:200`）把 WorkflowPlan 映射为右栏计划快照 | |
+| 9 | **工作区物化**：`PrepareWorkspace`（`squad/workspace.go:27`）+ `BuildSubWorkspaces`（workspace.go:127）：每步建 `tasks/NN_<role>/` 子工作区，把 `context/`（goal.md、材料原文 + textextract 抽取文本、index.json）与 template.md 快照进去（`snapshotContextInto` workspace.go:160），并写 **TASK.md**（`writeTaskFile` workspace.go:182：黑板快照、权威等级资源表、产出要求——成员靠它读前序产出）与 **AGENTS.md**（`writeAgentsFile` workspace.go:224：角色指令） | |
+| 10 | **调度执行** `flowDriver.advance`（`squad/workflow.go:25`）：每轮从权威 Steps 现场编译调度图 `compileGraph`（`squad/graph.go:23`：Needs 依赖或相邻 Parallel 同层，环 fail-closed）→ 分并行/串行层 → **无写集冲突的步骤并行**（`runParallel` workflow.go:216，goroutine+WaitGroup，关键失败 cancel 全组），写集冲突按声明序串行 → `gateBeforeRun`（workflow.go:175：bash ask 角色授权 / 步骤审批的 HITL 门）→ `runOneStep` | |
+| 11 | **单步执行** `runOneStep`（`squad/workflow.go:262`）：置 running、Attempts++ → 写 TASK.md → 组装 ExecRequest（ToolAllowlist/Skills/SessionScope/Budget/OnEvent 过程帧）→ 后端 `Execute`（系统功能步改走 IntentRunner）→ 瞬态失败重试并注入重试提示 → **交付物落盘校验** `missingTargets`（workflow.go:1071）→ 完成：`mergeStepArtifacts` 把子工作区 `fields.json/gaps.json` 并入黑板（`squad/blackboard.go:43`）→ `checkBlockingGaps`（workflow.go:652：interactive 挂 HitlGap 卡、auto 记兜底假设继续）→ 每步后可动态调整（评估器加步/跳步）。superstep 边界写检查点快照，Resume 时校验图指纹防形态漂移 | |
+| 12 | **成员执行（统一 agent-native）**：`RegisterFull`（`adapters/native/register.go:61`）按角色构造独立内核 agent（模型/工具/搜索/MCP/技能根按 RoleSpec+BashPermission 装配），过程帧经 eventTap 桥为 `EvDetail`。内核里的 `delegate_task` 经 `SubagentFactory`（`adapter.go:234`，SpawnBackground `:266` / SpawnSubagent `:273`）桥回产品 SpawnSubagent，**深度恒为 1，子 run 不再嵌套小队** | |
+| 13 | **Leader 委派模式**（entry=squad 的 plan 分诊）：`RunOptions.Mode="leader"`（`squad/engine.go:99-105` Options 注释；轮次上限 `MaxLeaderTurns` 默认 8，`squad/leader.go:48` `DefaultMaxLeaderTurns`）——规划被委派循环取代：每轮重写 leader 的 TASK.md（目标+黑板+委派历史）与 AGENTS.md（协调契约），leader 后端执行产出 **delegation.json**（action=delegate/escalate/close/failed）；delegate：临时建 StepSpec、跑 runOneStep、交付快照进 leader 的 `inbox/<stepID>/`、再唤醒 leader 评估（一轮只委派一个成员）；escalate → HitlEscalation 挂起；超限按现有产出降级收口。核心状态与提示词装配：`LeaderState`（leader.go:57）、`DelegationRecord`（:81）、`delegation`（:91）、`leaderPrompt`（:126）、`leaderExecRequest`（:16） | |
+| 14 | **汇总与质检（收口）** `finalize`（`squad/workflow.go:784`）：最后 completed 步骤的主产出复制为 `output.md` → `Checker.Check`（`internal/quality/checker.go:16` 附近 → `score.go`：六维启发式评分——结论先行/结构/完整性/证据/可执行性/可读性；**Passed = 总分≥70 且无单维<40**，score.go:28,72；docx 走段落提取；可选 housestyle lint）→ 未过写 `quality-feedback.md`（checker.go:29）并自动修复 `rerunForRepair` 重跑交付步骤（workflow.go:913）→ 仍不过：interactive 转 `quality_review` 人工裁决（approve=manualPass、retry 追加预算但受上限 `MaxRepairGranted`，`squad/termination.go:14`）→ 写 `manifest.json`（全文件 sha256 防篡改）→ `EvRunCompleted` | |
+| 15 | **聚合回主 run**：`Orchestrate` 返回 summary，交付物经 `rc.WriteArtifact("squad-<runID>.md")` 登记为主 run 工件；`RunEntry` 返回 `EntryResult{Summary, Body}`（`entry.go:34`），SquadRunner 做**虚假交付检查**（`internal/runtime/squad_runner.go:95` 附近 `claimsFalseDeliverable`）后落工件并 `SetAssistantParts`（squad_runner.go:107）。所有 usage 按角色聚合进 `RunResult.Usage` | |
+
+---
+
+## 4.5 实测：离线小队演示（真实输出）
+
+`deps/agent-squad` 自带离线演示（`cmd/agent-squad demo -keep`，stub 脚本成员 + 规划脚本 +
+自动应答 HITL，无需 LLM/网络），以下为其 2026-10-08 实测输出摘录。**引擎机制与产品完全
+同一套**，差异只有三处：成员后端是脚本（产品是 agent-native 内核）、规划器是 MockPlanner
+（产品默认 RulePlanner）、HITL 自动应答（产品走 HITL 卡片）。
+
+```
+═══ agent-squad 离线演示（stub 智能体 + mock 规划器 + HITL）═══
+
+[1] 注册角色（手动注册，backend=demo 脚本智能体）
+    + researcher 调研专员   + writer 撰写专员   + reviewer 审核专员
+
+[2] 发起运行：调研便携式超声诊断仪并产出报告
+    ✔ step_01_research  researcher  市场与技术调研，回填事实与缺口
+      step_02_draft     writer      汇总调研产出，撰写报告初稿
+      step_03_review    reviewer    一致性终审并产出终版
+
+[3] ⏸ HITL 挂起（gap）：发现 1 个阻塞缺口，需要人工补充信息后才能继续：
+      - [gap_1] 目标年产量未提供，影响成本测算（owner=agent）
+     → 自动回应：choice="resolved" answer="年产量 10 万套"
+    ✔ step_01_research   ✔ step_02_draft   ✔ step_03_review
+
+[4] 运行终态：completed
+    步骤 3 个（完成 3/跳过 0/失败 0）。质检得分 100。
+    交付物: <dataDir>/runs/run_20261008T090457.882598947/output.md
+    黑板字段: {"annual_volume":"100000","budget":"15万","device_class":"二类",
+              "review":"passed","target_market":"中国"}
+```
+
+对应真实落盘的工作区（`runs/<run_id>/`）——与第 4 节调用链逐项对应：
+
+```text
+runs/run_20261008T090457.882598947/
+├── context/goal.md, context/index.json     # 9. 目标与材料快照
+├── tasks/01_researcher/                    # 9. 每步一个子工作区
+│   ├── TASK.md        # 步骤任务书（角色、期望产出、资源权威等级、黑板快照、产出要求）
+│   ├── AGENTS.md      # 角色指令
+│   ├── context/       # 快照进来的目标/材料
+│   ├── notes.md  fields.json  gaps.json     # 成员产出（黑板来源）
+│   └── execution.log
+├── tasks/02_writer/{TASK.md,AGENTS.md,context/,output.md,...}
+├── tasks/03_reviewer/{TASK.md,AGENTS.md,context/,output.md,fields.json,...}
+├── blackboard.json                          # 11. 黑板（字段在步骤间累积）
+├── workflow.json  squad.json  runstate.json # 7. 拆解结果与运行态（磁盘即权威）
+├── checkpoints/{001,002,latest}.json        # 11. superstep 检查点
+├── output.md  manifest.json                 # 14. 聚合交付物 + sha256 清单
+└── .lock                                    # 6. acquire 的 flock 文件锁
+```
+
+`tasks/01_researcher/TASK.md` 实拍（节选）：
+
+```markdown
+# 步骤任务：市场与技术调研，回填事实与缺口
+- 角色：调研专员（researcher）
+- 期望产出：[notes.md fields.json gaps.json]
+## 任务上下文资源与权威等级（已快照到本目录，只引用本地路径）
+| 资源路径 | 权威等级 | 用途说明 |
+| `context/goal.md` | **authoritative** | 运行目标 | 不可推翻 |
+## 黑板快照（共享状态）
+## 产出要求
+1. 按期望产出文件名落盘到本子目录；
+2. 结构化事实回填 `fields.json`（字符串键值）；
+3. 发现信息缺口且无法假设时写 `gaps.json`（[{"item":"…","blocking":true}]）。
+```
+
+产品的默认拆解（RulePlanner 四阶段骨架，`squad/planner_rule.go:79` 起）与演示计划同构，
+真实代码里的步骤与交付约定：
+
+```go
+// 通用四阶段骨架：梳理 → 专项 → 成文 → 终审
+{"step_01_organizer", "梳理目标背景与输入材料，产出事实与缺口", "organizer"},
+{"step_02_specialist", "围绕目标开展专业分析与推演", "specialist"},
+{"step_03_writer",     "汇总各角色产出，撰写交付物初稿", "writer"},
+{"step_04_leader",     "一致性终审与交付把关", "leader"},
+// 非末步 targets = ["notes.md","fields.json"]（事实经黑板传给后步）；末步 = ["output.md"]
+```
+
+注册表缺角色时 `Registry.Derive` 现场派生（名为"organizer 专员"等）并置
+`NeedsConfirmation` → `awaiting_confirmation` 挂起等用户确认编制。意图目录注入规划器/
+Leader 的形态见[意图识别](intent-recognition.md) 4.6 节例 5 的 catalog 实测输出。
+
+---
+
+## 5. 小队如何"协作"
+
+- **黑板（Blackboard）**是协作中枢：Facts（已确认事实）/Gaps（信息缺口）/
+  Implications/Assumptions/Fields。每步完成后子工作区的 `fields.json`/`gaps.json`
+  合并进黑板（`squad/blackboard.go:43` `mergeStepArtifacts`）；下一成员的 TASK.md 带
+  黑板快照，据此读前序产出。字段注入可自动唤醒挂起的 run（`SweepWakeups`）。
+- **材料溯源**：输入材料经 `deps/agent-squad/textextract/` 提取纯文本并注入页码锚点，
+  成员引用材料时可标注出处。
+- **防失控上限**：`squad/termination.go` 集中管理修复预算、Leader 轮数等终止条件。
+
+---
+
+## 6. 与 runmgr / workflow 的关系
+
+- 小队**不是独立的一层**：它是 conversation run 内的一种执行模式/入口（`runtime.entry`）
+  或 run 内 LLM 的一次工具调用，在 runCtx 上同步驱动。
+- 成员执行的子 run 经产品 `SpawnSubagent` 进任务树（仅限内核 `delegate_task` 桥接）；
+  工作流（`run_workflow` → wfcompile 编译执行）是另一条平行机制——注意 wfcompile 执行时
+  **也装配到 squad 引擎上步进**，entry=squad 时不再提供 `run_workflow` 声明（互斥，
+  `internal/runtime/llm.go:266-268`）。
+- 依赖方向：agent-squad 核心只依赖 error-code-system（不感知内核）；依赖由 adapters
+  层单向引入——`agent-squad/adapters/native` 同时依赖 agent-native 与 agent-squad；
+  backend require 两者并 replace 到自己 `deps/` 下的库副本。
+
+---
+
+## 7. 关键文件清单
+
+| 职责 | 文件 |
+|---|---|
+| 全部类型与状态机 | `deps/agent-squad/squad/models.go`（RoleSpec :25、StepSpec :86、BlackboardState :225、RunStatus :284） |
+| 门面（Run/Respond/Resume/Inspect/Steer） | `deps/agent-squad/squad/engine.go`（Run :234、acquire :213、planAndExecute :335、Respond :637、Resume :1127） |
+| 调度/单步/收口 | `deps/agent-squad/squad/workflow.go`（advance :25、gateBeforeRun :175、runParallel :216、runOneStep :262、checkBlockingGaps :652、finalize :784、rerunForRepair :913、missingTargets :1071） |
+| DAG 编译与图指纹 | `deps/agent-squad/squad/graph.go`（compileGraph :23） |
+| Leader 委派 | `deps/agent-squad/squad/leader.go`（DefaultMaxLeaderTurns :48、LeaderState :57、leaderPrompt :126） |
+| 规划器（规则/LLM/端口） | `squad/planner_rule.go`（Plan :20、fromBlueprint :27）、`planner_llm.go`、`planner.go` |
+| direct/plan 分诊 | `squad/router.go`（applyRoute :29、directAssistantPlan :55） |
+| 状态持久化（磁盘即权威） | `squad/runstate.go`（persist :81） |
+| 工作区/TASK.md/AGENTS.md | `squad/workspace.go`（PrepareWorkspace :27、BuildSubWorkspaces :127、writeTaskFile :182、writeAgentsFile :224） |
+| 黑板合并 | `squad/blackboard.go`（mergeStepArtifacts :43） |
+| 事件 | `squad/progress.go`、`store/eventsink.go` |
+| 后端解析器 / 防失控上限 | `squad/backend.go`、`termination.go` |
+| backend 工具路径适配 | `internal/squadadapter/adapter.go`（Orchestrate :47、askHuman :150、onSquadEvent :185、mapPlan :200、isHoldStatus :221、SubagentFactory :234、BuildBackends :292、builtinRoles :306） |
+| backend 入口路径适配 | `internal/squadadapter/entry.go`（RunEntry :42、kernelRoles :177） |
+| 对话入口 Runner + LLM 分诊 | `internal/runtime/squad_runner.go`（Execute :26、Route :146） |
+| 质检打分（六维） | `internal/quality/checker.go`、`score.go` |
+| 内核接成小队执行器 | `deps/agent-squad/adapters/native/register.go`（RegisterFull :61） |
+| 意图闸门/能力目录 | `deps/agent-squad/adapters/intent/gate.go`、`catalog.go` |
+| 独立 CLI（serve/run/demo） | `deps/agent-squad/cmd/agent-squad/` |

docs/guides/task-planning-and-execution.md

@@ -0,0 +1,246 @@
+# Agent 的任务规划与执行：架构与调用链
+
+> 基准：Agent-System-Dev 组合 `218fc4b1ba00b0a03b5bb79f292b3eba6c987a58`（R0，2026-10-08 锚点核验）。
+> 行号为该提交下的函数入口位置（个别内部区段为约略范围），随代码演进漂移；文件与函数名是稳定锚点。
+> `internal/` 指 `modules/backend/internal/`；`core/` 指 `modules/core/`；
+> `nruntime/` 指 `deps/agent-native/runtime/`。
+
+---
+
+## 1. 一句话结论
+
+系统有**两套并存的规划机制**：
+
+1. **默认主线 = LLM 自主规划（ReAct 循环）**：没有预置 DAG。普通消息由 backend
+   `LLMRunner` 驱动，进入 `deps/agent-native` 自研内核的单轮循环
+   （组装上下文 → 调 LLM → 解析工具调用 → 执行工具 → 回填 → 直到模型不再调工具），
+   模型可用 `update_plan` / `update_todos` 工具自主维护任务列表（右栏 Plan/Todos 面板）。
+2. **可选结构化路径 = WorkflowDef（数据化步骤列表）**：可由意图绑定启动，也可由模型
+   调用 `run_workflow goal=...` 触发"规划子代理生成步骤 → 用户 HITL 确认 → 编译执行"
+   （`internal/runtime/workflow_compiled.go:91` `planCompiledWorkflow`）。工作流的
+   编译与步进执行在 `internal/wfcompile` 包，执行时**装配到小队引擎上步进**
+   （挂起 → HITL 卡 → Respond；执行态 → Resume），收口带 critic 终判。
+
+执行主体分两层：backend 的 `runmgr`（Run 生命周期/事件/持久化/策略）+
+`internal/runtime`（各 Runner）；真正的智能体循环内核在 `deps/agent-native/runtime/loop.go`。
+
+---
+
+## 2. Run 生命周期与状态机
+
+契约定义在 `modules/core/model.go`：
+
+- `RunStatus`（model.go:166）：
+  `pending → running → (waiting_hitl ⇄ running) → completed | failed | cancelled | interrupted`
+- `RunPhase`（model.go:178）：`thinking → acting → responding → finalizing → done`
+- `RunKind`（model.go:158）：`conversation | subagent | tool`；
+  `Run` 结构体（model.go:188）含 `ParentRunID`（任务树）、Usage、Error。
+
+状态迁移代码位置（均在 `internal/runmgr/runmgr.go`）：
+
+| 迁移 | 代码位置 |
+|---|---|
+| 创建（pending） | `:1023` `startClaimedRun`（建 Run + `store.CreateRun`，`internal/store/messages.go:120`） |
+| 运行 | `:1055` 附近 `execute`（置 running/thinking） |
+| HITL 挂起/恢复 | `:449` `AskHITL` 置 waiting_hitl；`:1261` `ResolveHITL` 恢复 running |
+| 终态 | `:1087` `finishRun` → `internal/store/recovery.go:125` `SettleRun`（条件 UPDATE + 同事务写权威助手消息树，防并发双终态）→ 发 `run.completed/failed` |
+| 取消 | `:1222` `CancelRun`（根 run ctx 取消，子 run 派生自父 ctx 天然级联；并唤醒 HITL 等待） |
+| 停机中断/重启对账 | `:1655` `InterruptRunning`、启动时 `:1689` `ReconcileInterrupted` |
+| 会话并发控制 | `:980` `ClaimConversation`（一会话至多一个在途 run，忙返回 409，`server.go` 错误映射） |
+
+---
+
+## 3. 端到端调用链（普通消息 → 结果落库）
+
+| # | 步骤 | 位置 |
+|---|---|---|
+| 1 | HTTP 入口 `postMessage`：附件经 `ingest.Parse`；`/` 命令不启 run；意图识别 + `route.Decide` 三分支 | `internal/server/server.go:574`；路由调用 `:656` |
+| 2 | 抢会话槽位 + 消息落库（幂等 requestId） | `server.go:679` → `runmgr.go:980`；`server.go:686` 附近 `AppendMessageWithRequest` |
+| 3 | 启动 run：工作流回合 `StartClaimedWorkflowRun`（定义深拷贝进 Launch，插件卸载不影响在跑副本）；普通回合 `StartClaimedConversationRun` → `startClaimedRun`：建 Run 落库 → 注册 runHandle → `selectConversationRunner` → 附件原件落工作区 → `go m.execute(rc, runner)` | `server.go:725,727`；`runmgr.go:991, 996, 1023-1043`；runner 选择 `runmgr.go:918` |
+| 4 | `LLMRunner.Execute`（`internal/runtime/llm.go:198`）准备阶段：模型路由 `ResolveChatModel`（`internal/runtime/model.go:54`，settings `models.chat.*` + 画像 ModelRoute，密钥经 SecretLookup）；`@knowledge` 显式引用触发 RAG（llm.go:216 附近）；system 段 `prompts.Service.ResolveSystem`（`internal/prompts/service.go:290`）；上下文组装 `ctxasm.AssembleInput`/`FinishAssembly`（`internal/ctxasm/ctxasm.go:45`、`finish.go:97`，产出 `ContextObservation` 随 run.completed 下发）；工具声明（编排型内置 + 注册表过滤，llm.go:267-315；计划模式过滤 `filterPlanDecls` llm.go:332） | |
+| 5 | 进入内核：`l.runDirect(...)`（`internal/runtime/llm_direct.go:95`）把声明包成内核工具注册进 `agenttools.NewRegistry`、打开转录 journal（`<sandbox>/.agentx/transcript.jsonl`）、接线 Stop 钩子（交付物门禁 + 验证器）、调 `nruntime.Run(...)` | |
+| 6 | **内核 ReAct 单轮循环** `nruntime.Run`（`deps/agent-native/runtime/loop.go:196`，`for turn < cfg.MaxTurns` 默认 12）：① ctx/预算检查 → ② `prepareRequest`（loop.go:787：转录投影 + 窗口清理 + 记忆注入 + reminders）→ ③ `consume` 流式消费 LLM 事件（loop.go:492）→ ④ 持久化 assistant → ⑤ 有工具调用：`executeTools`（loop.go:595，可并行），每个 `runOne`（loop.go:709）走完整性校验 → `gateTool`（hooks PreToolUse，ask 决策交宿主 PermissionAsk）→ commitToolIntent（崩溃恢复配对）→ `cfg.Tools.Execute` → AfterTool，结果按 Role=tool 回填 → `continue` 下一轮 → ⑥ 无工具调用：`ContinueOnLength` 续写（loop.go:399）+ follow-up drain + Stop 钩子决定续跑（`stopDecision` loop.go:645；宿主侧做交付物门禁与验证，最多 3 次续跑）→ `settle` 结束；轮数耗尽报 max turns exceeded（loop.go:447） | |
+| 7 | 工具执行回落宿主：编排型工具在 runner 内消化——`squad_orchestrate` → squadadapter.Orchestrate（case 在 `llm_direct.go:479`）、`delegate_task` → rc 端口 `SpawnBackground`/`SpawnAgent`（`llm_direct.go:493` 起）、`update_plan/update_todos` → `rc.UpdatePlan/UpdateTodos`、`run_workflow`、`submit_card/card_*`（各 case 依次在 `llm_direct.go:471` `runTool` 内）；其余 → `rc.ExecuteTool`（`runmgr.go:740`）：画像三清单 → policy.Decide（计划模式 deny / ask→HITL 确认卡）→ `registry.Execute`（`internal/tools/registry.go:94`）→ 结果截断转工件 | |
+| 8 | 子代理 run（任务树）：`spawnSubagent/startChild`（`runmgr.go:1348/1358`，startChild 做深度检查）建 `Kind=subagent` 子 run（ParentRunID 指父）→ 发 `agent.spawn`（`runmgr.go:1375`）→ `finishChild`（`runmgr.go:1401`）跑 `SubLLMRunner.Execute`（`internal/runtime/sub_loop.go:31`，同样调 `nruntime.Run`）→ 子转录独立落盘 → 结果截断 32000 字（`runmgr.go:1780` `capSubagentResult`）。后台子代理：`spawnBackground`（`runmgr.go:1475`，每会话上限 3）；完成后 `deliverNotices`（`runmgr.go:1560`）在会话空闲时以 system-reminder 启动新父回合汇报（`startNoticeRun`，`runmgr.go:1616`） | |
+| 9 | 终态收敛：`finishRun`（`runmgr.go:1087`）usage 汇总 → 终态消息树（tool_call/tool_result/thinking/card 部件）→ `SettleRun` 单事务落库 → submit_card 回填锚点 → 发 `run.completed`（含 ContextObservation）/`run.failed`。工件：`runCtx.WriteArtifact` → `store.CreateArtifact` → `artifact.created` 事件 → 文本进检索索引；工件作为 `PartArtifactRef` 挂进助手消息树 | |
+
+完成判定者 = 内核循环 + 宿主 Stop 钩子组合：模型不再调工具且无 follow-up → Stop 钩子
+（交付物门禁说谎检测、可选验证器）决定续跑或放行 → 可选用主模型 `composeFinal` 重写
+最终回复（`nruntime/compose.go`）→ `finishRun` 落终态。
+
+---
+
+## 4. LLM 调用与流式
+
+- **不用第三方 SDK**，自研 HTTP 客户端 `deps/agent-native/runtime/llm/client.go`：
+  默认 OpenAI 兼容 `POST {base}/chat/completions` + `stream:true`；
+  `Protocol=anthropic` 走原生 Messages（`anthropic.go`，带 cache_control 断点与签名思考块）。
+- **Provider 预设**：`llm/providers.go`（anthropic/openai/google/deepseek/minimax/
+  openrouter/groq/azure）+ `models.json` 自定义；`ParseModelRef` 支持 `provider/model:thinking`。
+- **流式解析**：`llm/sse.go` `ParseSSE` → `emitParsed` 产出统一事件
+  （text_delta / reasoning_delta / tool_call_delta / message_end）。
+- **模型配置链**：settings 覆盖链（defaults→system→user→project）+ 画像 ModelRoute
+  （`internal/runtime/model.go:30-62`）；轻量档回落主档（model.go:84）；
+  `models.chat.fallbacks` 故障切换（`llm/fallback.go`，在 runDirect 内接线）；
+  重试（内核 `WithRetry`）。
+- **事件到前端**：内核事件 → `directRun.onEvent`（`llm_direct.go:278`）转 `rc.Emit(...)`
+  → `runmgr.emit`（`runmgr.go:1217`）→ 事件缓冲合并（150ms/64 条，`internal/runmgr/events.go:42-43,83`）
+  → `store.AppendEvents`（事务内分配会话内单调 seq，`internal/store/messages.go:243`）
+  → `bus.Publish` → SSE `GET /api/events`（`server.go:275`，Last-Event-ID 重放，15s 心跳）；
+  PG 多实例经 `internal/pgbus` NOTIFY/LISTEN 扇出。
+
+---
+
+## 5. 工具 / 技能 / 提示词体系
+
+**工具系统**
+- 契约：`modules/core/tools.go:16` `ToolDesc`（JSON Schema 参数、ReadOnly/Edits/Risk 权限声明）、
+  `tools.go:33` `HTTPToolSpec` 无代码声明式 HTTP 工具。
+- 注册：`internal/tools/registry.go:50` `Register`（后注册覆盖）、`:112` `RegisterBuiltin`
+  （time_now、knowledge_search、write_artifact、quality_review、跨会话 peers、ask_user 等）；
+  另有 fs / exec / search / 声明式 HTTP / `run_tool_script`（需开关）各文件。
+- 执行策略在 runmgr：`ExecuteTool`（`runmgr.go:740`）deny→错误、计划模式 deny、
+  confirm/ask→HITL 确认卡、执行后超长截断转工件。
+- 结果回填：内核侧作为 `Role=tool` 消息进转录；UI 侧由 onEvent 聚成 `PartToolCall`+
+  `PartToolResult` 终态落库；下一轮由 ctxasm `renderAssistantTurns`（`internal/ctxasm/ctxasm.go:174` 附近）
+  还原成 provider 原生配对消息。
+
+**skills 包 = 内置技能文件**：go:embed `recipes/**`（`internal/skills/skills.go:23` 附近），
+启动 `Seed`（skills.go:53）落 `<data>/skills/`，带 manifest 哈希做升级/drift 保护；
+供内核的 SKILL.md 加载器与 `load_skill` 渐进披露工具消费
+（`deps/agent-native/runtime/skills/skills.go`）。
+
+**prompts 包 = 提示词模块库**：embed `library/*.md` + DB 用户覆盖链。
+`ResolveSystem`（`internal/prompts/service.go:290`）：base/env 层按画像引用 →
+task 层全员触发匹配（command/intent/attachment 三类触发）→ 正文点名的 `method.*`
+辅助模块跟随注入 → 占位符填充（`{{date}}/{{model}}/{{skillsDir}}`）。
+另提供子代理 spec（tools/model/maxTurns，`service.go:81` 附近；**禁止子代理持有派发类工具**）、
+AgentPrompt、工具描述覆盖。
+
+**ctxasm 包 = 上下文组装**：`AssembleInput`（`internal/ctxasm/ctxasm.go:45`）=
+sys 段 → 历史窗口（默认 40 条，超出注入抽取式摘要）→ 卡片/工件正文回填
+（防"下一轮失忆"）→ 当前轮文本 + 附件解析全文（默认 48000 字符截断）+ knowledge 块；
+`FinishAssembly`（`finish.go:97`）追加条件注入；产出 Report（token 估算、裁剪记录、
+prefixHash）作为可观测 `ContextObservation`。记忆注入在内核按请求完成（`loop.go` prepareRequest 段）。
+
+---
+
+## 5.5 主对话模型手上有哪些工具
+
+模型每轮请求能看到的工具分三类（全部在 `LLMRunner.Execute` 声明阶段组装，`llm.go:267-315`）：
+
+| 类别 | 工具名（实测常量/注册名） | 来源 |
+|---|---|---|
+| **编排型**（在 runner 内消化，不走通用执行器） | `update_plan` / `update_todos`（维护右栏计划/待办）、`delegate_task`（派子代理）、`squad_orchestrate`（发起小队）、`run_workflow`（发起工作流）、`review_findings`、`submit_card`、`card_begin`/`card_append`/`card_commit`（流式产卡三段式） | `internal/runtime/llm.go:56-70` 常量 |
+| **内置产品工具** | `time_now`、`knowledge_search`（项目/插件知识全文检索）、`write_artifact`（写工件）、`quality_review`（交付物打分）、`ask_user`（主动提问=HITL）、跨会话 `peers` 系列 | `internal/tools/registry.go:112` `RegisterBuiltin` |
+| **内核工作区工具**（经 hostbridge 注入内核） | `read_file` / `write_file` / `edit_file` / `multi_edit` / `list_dir` / `grep` / `glob` / `load_skill` / `run_python` / `run_command` / `web_search` / `tavily_search` / `fetch_url` / `delegate_task` | `internal/runtime/hostbridge.go:15-21` `kernelToolNames`；`web_search`/`tavily_search` 仅在配置了搜索密钥时注册 |
+
+实际可见集 = 以上与**画像三清单**（allow/deny/confirm，`core/profile.go`）过滤后的交集；
+计划模式下 `filterPlanDecls`（llm.go:332）会再收窄。
+
+---
+
+## 5.6 实例：一个典型回合的机制走查
+
+> 走查基于上文全部代码锚点；模型输出为示意，机制、工具名与顺序均为代码实测。
+
+用户输入："把我会话里刚上传的季度数据整理成一份摘要文档，并告诉我三个关键结论。"
+
+1. **进入回合**：`postMessage` → 意图 fallback（没有装匹配意图）→ `route.Decide` 判
+   `KindTurn` → 抢会话槽位 → `startClaimedRun` 建 `Run{pending}` → 选 `LLMRunner` →
+   `go execute()`（`runmgr.go:1023, 918`）。
+2. **上下文组装**：`ctxasm.AssembleInput`（ctxasm.go:45）——system 段（base/env/task 提示词
+   模块，`prompts.ResolveSystem`）→ 历史窗口（默认 40 条）→ 当前轮文本 + **附件解析全文**
+   （ingest 已把 xlsx/csv 解成 ParsedDocument，默认 48000 字符截断）→ knowledge 块。
+3. **第 1 轮 LLM**：模型看到数据后先调 `update_todos`（拆 3 个待办）+ `read_file`（读附件
+   解析物）。两个工具经内核 `runTool` 回落宿主执行，结果以 `Role=tool` 消息回填转录
+   （loop.go `executeTools` 段），UI 侧聚成工具过程部件。
+4. **第 2 轮 LLM**：模型调 `write_artifact`（把摘要写成工件）。宿主执行 → `artifact.created`
+   事件 → 工件登记进会话。
+5. **第 3 轮 LLM**：模型输出三个结论的纯文本（无工具调用）→ 内核判定无工具调用 →
+   follow-up drain → **Stop 钩子**：宿主做交付物门禁（`deps/agent-native/runtime/gates/gates.go:52`
+   `ClaimGate`）——它抓三类"说谎"：① 回复正文出现工具调用标记但本轮没有真实调用；
+   ② 引用了不存在的工件 ID；③ **声称"已生成/已登记文件"但这轮没有产出对应工件**。
+   本例模型确实产出了工件，门禁放行；若模型只写了结论却声称"文件已生成"，
+   门禁拒绝结算并附原因让模型续跑（最多 3 次续跑，`loop.go` stopDecision + 宿主接线）。
+6. **收口**：可选用主模型 `composeFinal` 重写最终回复 → `finishRun`（runmgr.go:1087）→
+   `SettleRun` 单事务落 run 终态与助手消息树 → 发 `run.completed`（带 ContextObservation）。
+
+子代理变体：若第 2 轮模型改调 `delegate_task {agent:"researcher", task:"分析季度数据"}`，
+则走 `llm_direct.go:493` → `runmgr.go:1348` 派生 `Kind=subagent` 子 run（任务树 + `agent.spawn`
+事件）→ `SubLLMRunner` 用同一内核循环独立跑完 → 结果回填父轮。
+
+---
+
+## 6. HITL（人工介入）
+
+- 契约：`modules/core/hitl.go:33-36` 四种卡（choice/input/confirm/form）。
+- 挂起：`runCtx.AskHITL`（`runmgr.go:449`）存卡 → run 置 waiting_hitl → 发
+  `hitl.request` → 收件箱投影 → `waitHITL` 阻塞等恢复（支持超时）。
+- 恢复：`POST /api/hitl/{id}/resolve` → `runmgr.ResolveHITL`（`runmgr.go:1261`）
+  三分支：选项回填恢复；自由输入命中其他意图 → 取消挂起 run 并转轨；否则作澄清回答回填。
+- 触发时机：a) 工具确认（画像 confirm 清单 / policy ask，`runmgr.go:757` 附近与内核
+  `PermissionAsk` 端口）；b) 工作流缺槽位提问（`internal/wfcompile/run.go` 槽位补齐段）、
+  显式 hitl 步骤（`internal/wfcompile/host.go:138` `doHitl`）、动态计划执行前确认
+  （`RunOptions.RequireConfirm`，`internal/wfcompile/run.go:34`）；c) `ask_user` 工具。
+
+---
+
+## 7. workflow 体系与"规划器"
+
+- `internal/workflow/registry.go`：工作流**定义注册表**（只依赖 core）。
+  `Registry.Set` 整体替换快照、`ByIntent` 按意图查定义、`Launch` 产启动副本。
+- **编译执行器在 `internal/wfcompile/`**（Q3 WP1）：
+  - `run.go:39` `RunCompiled`：缺槽位逐个 HITL input 卡收齐 → `compiler.go:76` `Compile`
+    编译 WorkflowDef → **装配到小队引擎（squad）步进执行**（挂起 → HITL 卡片 → Respond；
+    执行态 → Resume）→ critic 终判 → outcome 汇总（run.go 文件头注释即此流程）。
+  - `RunOptions`（run.go:27）：`DynamicLimits`（模型生成上限：≤8 步、禁 script）、
+    `RequireConfirm`（模型生成工作流执行前强制 HITL 确认；注册的声明式工作流免确认）、
+    `ModelScript`（脚本步为模型提供，执行前单独确认）。
+- **"先规划任务列表再执行"的 planner 真实存在**：`internal/runtime/workflow_compiled.go:91`
+  `planCompiledWorkflow` —— `rc.SpawnAgent(workflowPlannerID, "规划", …)` 派**规划子代理**
+  输出 WorkflowDef JSON（"只输出 JSON，不要完成目标本身"）→ `wfcompile.ParseWorkflowDef`
+  解析校验 → `runLaunch` 以 `DynamicLimits:true, RequireConfirm:true` 执行（用户 HITL
+  确认计划后步进）。另有 `registeredWorkflowLaunch`（:117，注册定义 + 快照脚本正文）、
+  `modelScriptLaunch`（:138，模型脚本，单独确认）。入口 Runner 是
+  `CompiledWorkflowRunner`（workflow_compiled.go:30，`Execute` :39）。
+
+---
+
+## 8. deps/agent-native 内核的其他部件
+
+- `runtime/` 是**进程内自研内核**（不派子进程）：`loop.go` 循环、`llm/` 客户端、
+  `tools/` 内核注册表（deferred 延迟暴露 + tool_search）、`session/`（JSONL 转录树，
+  可 fork/clone）、`session_agent.go`（headless AgentSession：steer/follow_up/abort/换模型）、
+  `hooks/`、`memory/`、`skills/`、`promptx/`、`mcp/`、`checkpoint/`、`subagent/`、
+  `gates/`（验收+守卫）、`codeorch/`（Python 依序调工具的代码编排）、`policy/`。
+- `rpc/` 是本地 JSONL RPC（一行一命令，双向 pipe），把内核暴露给子进程/外部宿主；
+  **产品后端主路径不走 rpc**，直接进程内调 `nruntime.Run`。
+- `adapters/native/backend.go` 把内核包成 `exec.Backend`（`exec/backend.go` 接口），
+  供小队成员执行使用（见[小队与子 Agent 启动](squad-and-subagents.md)、
+  [小队工作机制](squad-mechanics.md)）；`adapters/pitransport/` 是远程 pi runner 的
+  HTTP/NDJSON 传输适配（产品未用为主）。
+
+---
+
+## 9. 关键文件清单
+
+| 职责 | 文件 |
+|---|---|
+| Run/消息/计划/工件契约 | `modules/core/model.go`、`events.go`、`hitl.go`、`tools.go` |
+| Run 生命周期枢纽 | `modules/backend/internal/runmgr/runmgr.go` |
+| 事件缓冲与 seq | `modules/backend/internal/runmgr/events.go` |
+| Runner 端口与四实现 | `internal/runtime/runner.go`、`llm.go`、`sub_loop.go`、`workflow_compiled.go`、`squad_runner.go` |
+| 内核桥接（工具/事件/Stop 钩子） | `internal/runtime/llm_direct.go`（runDirect :95、onEvent :278、runTool :471） |
+| 模型路由 | `internal/runtime/model.go` |
+| 工作流编译执行 | `internal/wfcompile/run.go`（RunCompiled :39）、`compiler.go`（Compile :76）、`host.go`（doHitl :138） |
+| 工作流入口与 planner | `internal/runtime/workflow_compiled.go`（CompiledWorkflowRunner :30、planCompiledWorkflow :91） |
+| 工作流定义注册表 | `internal/workflow/registry.go` |
+| 内核 ReAct 循环 | `deps/agent-native/runtime/loop.go` |
+| LLM 客户端/协议/预设 | `deps/agent-native/runtime/llm/client.go`、`providers.go`、`sse.go`、`anthropic.go` |
+| 上下文组装 | `internal/ctxasm/ctxasm.go`、`finish.go` |
+| 提示词库 | `internal/prompts/service.go` |
+| 技能种子 | `internal/skills/skills.go` |
+| 工具注册表 | `internal/tools/registry.go` |
+| run/事件/工件落库 | `internal/store/messages.go`、`recovery.go` |
+| HTTP 入口与 SSE | `internal/server/server.go` |

docs/guides/usage.md

@@ -85,7 +85,7 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve   # 环境变量
 - **长回复折叠**：终态后超过 800 字的回复自动收成「📄 长回复 · N 字（点击展开）」摘要行——流式期间全文可见，历史消息同样适用。
 - **长结果进右侧卡片（默认关）**：设置 → 界面 →「长结果进右侧卡片」开启后，报告/纪要/方案/对比/文档草稿等**产物型**长内容进右栏收件箱（result 卡，可置顶/收纳）；长正文优先流式三段式——`card_begin` 建卡（收件箱即时出现 active 卡）→ `card_append` 逐段追加（卡片实时刷新，事件按 250ms 窗口节流）→ `card_commit` 收尾（转 done 并锚定到对话）；一次性短产物走 `submit_card`。中栏保留结论摘要 + 锚点部件（`📄 标题 · N 字 ▸ 展开全文 · ↗ 收件箱`）——锚点可无跳转展开全文，右栏收起时阅读不残废；解释型长回答不进卡。下一轮对话上下文自动回填卡片全文（「🧩 上下文构成」可见 card(n) 条目）；run 异常终止时未收尾的流式卡自动置 done/failed 并标注「未正常收尾」，内容不丢。
 - **上下文构成观测**：每条助手消息尾部「🧩 上下文构成」折叠芯片——该轮模型实际看到什么（系统提示/历史条数/附件/知识命中）与裁剪记录（历史超窗/工具结果超限），输入规模可解释。
-- **附件**：📎 上传 md/txt/docx/pdf/图片——文档经内置解析器（确定性代码解析：md/txt 直读、docx 解 OOXML、pdf 提取文本层）转为中间表示注入对话；解析结果与警告显式可见（不静默）。
+- **附件**：📎 上传 md/txt/docx/pdf/xlsx/pptx/图片——文档经内置解析器（确定性代码解析：md/txt 直读、docx/xlsx/pptx 解 OOXML、pdf 提取文本层）转为中间表示注入对话；解析结果与警告显式可见（不静默）。
 - **输入增强**：`/` 唤起命令菜单（/new /mock /model /profile /help）；`@knowledge` 在消息中触发知识检索注入。
 
 ### 3.3 mock 演示指令（无需模型）
@@ -113,7 +113,8 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve   # 环境变量
 
 - 任务卡七类（progress/confirm/compare/review-list/result/error/status）：状态灯**形状+色双编码**（◆ 待处理 ● 完成 ✓ 已确认 ✕ 失败 ◌ 已关闭——不只靠颜色）；置顶不随滚动；`#upload` 演示摄取→完成→冲突对比卡全周期。
 - 卡上动作即命令（card 入口，见 §5）；确认结论以**回执消息**进对话时间线留痕。
-- **收纳**：🧹 一键收纳完成卡（done→关闭；已确认卡盖章留痕不动）；右栏收起时角标显示待处理数。
+- **收纳**：🧹 一键收纳完成卡（done→关闭；已确认卡盖章留痕不动）；右栏收起时角标显示待处理数（本会话 + 项目未决合计）。
+- **项目收件箱（CF3，跨会话待办不丢）**：收件箱内「本会话 / 项目」两级切换。会话卡点 🗂 **留档到项目**——复制为项目级卡（原卡关闭留痕，不移动时间线；HITL/命令确认卡不可留档），跨会话可见；`submit_card`/`card_begin` 也可带 `scope=project` 直产项目卡。项目视图聚合 = 项目级卡片 ∪ 其他会话未决卡（done 留在原会话防噪音），经独立项目事件流实时刷新。
 - 卡片↔消息**互定位**（D32）：消息内 `card:` 链接点击定位收件箱卡片；HITL/确认卡锚定发起消息内联双现。
 
 ### 4.3 工作区弹层（深读与治理视图，⌘1–9）
@@ -134,6 +135,7 @@ AGENT_SYSTEM_CONFIG=/etc/agent-system.json agent-system serve   # 环境变量
 - 上传与模型产出统一入 Artifacts；`write_artifact` 工具可被模型调用。
 - 查看：markdown 在线渲染；文本类可**编辑保存**；二进制（docx/pdf）下载；图片内联预览。
 - 文档工件与上传文本自动进**知识索引**（全文检索）。
+- **工件门面卡（与产物卡统一呈现）**：工具结果被截断超限时自动在收件箱留一张 `result` 门面卡（摘要 + 来源工具 + `doc-ref` 引用，点击直开查看器）——字节权威仍在工件（可编辑/下载），卡只做门面与锚；下一轮对话上下文会自动回填工件文本（上限与产物卡同为 12000 字，超限在「🧩 上下文构成」可见 `artifact(n)` 与截断记录），模型不再对工具大结果失忆。
 
 ### 4.6 知识检索
 

docs/proposals/2026-10-01-agent-harness.md

@@ -0,0 +1,132 @@
+# Agent harness：回合循环、结果把控与多代理编排
+
+状态：**proposed（2026-10-01）**；owner：weichen；主任务：Dev 仓 `feature/agent-harness-p0`。
+规范依据：Development-Guidelines（workflows/delivery.md、standards/collaboration.md、standards/agent-execution.md）；本文是项目级消费，不复制其正文。
+撰写日期：2026-10-01。对标来源：[zai-org/ZCode](https://github.com/zai-org/ZCode)（Apache-2.0，`apps/zcode-cli/packages/core`）、[Claude Code 公开文档](https://code.claude.com/docs/en/overview) 与其插件仓 [anthropics/claude-code](https://github.com/anthropics/claude-code)。
+
+本文只定义 harness 的职责、分期与验收。P0 随本文落地；P1–P4 各自另开任务，不在本文实施。
+
+后续：三个库如何补齐缺陷、吸收外部做法并彼此解耦，见 [2026-10-02-agent-stack-completion.md](2026-10-02-agent-stack-completion.md)。本文的 P0–P4 不因该提案作废。
+
+---
+
+## 1. 问题与证据
+
+2026-10-01，会话 `cnv_96f639abf03a` 第 26 轮（开发库 `runtime/dev/data/agent-system.db`）用户要求「重新总结纪要」。助手正文里出现了 `[调用工具 run_python(…)]`、`[工具结果 ok …]`、`[产出工件 …（二进制内容，正文见工件查看器）]`，并给出工件 ID `art_1a2b3c4d5e6f`。该轮落库部件只有 `thinking` 与 `text`，没有任何 `tool_call`；`artifacts` 表里没有这个 ID，所以界面显示「未找到该文件」。同会话第 16、20 轮的 `art_7b24c0b7e2f1`、`art_4f9d2c1a8b3e` 同样不存在。第 22、24 轮才是真实的工具调用与工件。
+
+直接原因在上下文组装：`modules/backend/internal/ctxasm/ctxasm.go` 把历史里的工具调用压成文本 `[调用工具 …]` / `[工具结果 …]` 写进助手消息。模型把这种文本当成「我以前就是这样调用工具的」格式，在正文里模仿。虚假交付守卫（`claimsFalseDeliverable`）只纠正一次，第二段「文件已正常生成并登记」既没有 `art_` 编号，也匹配不上「已生成….docx」正则，被当成最终回复放行。
+
+同一机制下还有这些结构性缺口（2026-10-01 只读梳理）：
+
+- 三套循环各自为政。直连走 `LLMRunner`；小队成员走 `agent-native` 的 `runtime.Run`（已有 `GetSteering` / `GetFollowUp`，直连没用）；`delegate_task` 背后的 `SubLLMRunner` 是单次调用、没有工具。
+- 是否完成由干活的模型自报。`quality_review` 与版式检查只靠提示词约定；`agent.sub.verify` 要求输出的 `VERDICT` 没有解析方；模型评分 `Judge` 只有类型、没有接线。
+- 没有逐轮提醒。计划和待办只给界面看，不回灌给模型。技能只按当前这条用户文本匹配一次。
+- 子 run 的助手消息落在同一会话，列表不按 run 过滤，下一轮会被当成主对话回放。
+- 插件工作流只有数据、没有执行器。`WorkflowDef.IntentID` 没有消费方。意图识别没有路由到工作流。
+- 预算耗尽时直接返回错误，已生成的部件不落库。工具结果按字节截断，可能切在 UTF-8 字符中间。
+
+## 2. 对标结论
+
+两边的共同点：工具调用按提供方的原生消息回放，而不是压成正文；完成与否由循环或另一个评估者判定，不由干活的模型宣布；子代理上下文隔离，只把摘要交回父会话；每条续跑路径都有次数上限。
+
+| 机制 | ZCode | Claude Code | 本基座采纳 |
+|---|---|---|---|
+| 历史回放 | `tool_calls` + `role=tool`；没有结果的调用补占位，并区分「未执行」与「副作用未知」 | 同形（公开文档描述为工具结果回传） | 采纳。占位文案按原因区分 |
+| 完成判定 | 同模型、不带工具，按证据清单输出 `{passed, reason, nextAction}`；拿不准判不通过。验证器自身出错时放行 | `/goal`：每轮结束后由另一个模型判断，不成立就开下一轮 | 采纳证据清单。交付物场景下验证器出错改为判不通过，并设次数上限 |
+| 结束门禁 | Stop hook 返回继续并注入上下文，最多 3 次 | Stop / SubagentStop 返回 `decision: block` + `reason`；`stop_hook_active` 防止死循环 | 采纳 `block + reason`，上限 3 |
+| 提醒 | 按来源节流，包在 `<system-reminder>` 里，位置不破坏工具消息配对 | 规范、待办、后台完成以 system-reminder 插入，不改 system 段 | 采纳 |
+| 异常 | 同名同参数连续 3 次给警告，不直接终止；输出被截断最多续写 3 次，续写提示不入库 | 公开文档未给出同等细节 | 采纳警告与续写 |
+| 子代理 | Markdown frontmatter 定义；调用方不能指定模型；嵌套深度从工具白名单上限制为 1；后台完成用通知回传，多条合并 | 同形。子代理只回传最终结果，中间过程不进父上下文 | 采纳 |
+| 评审 | expert 的 critic 用 JSON 判定，可按节点重开，每层有上限 | `code-review` 插件：并行找问题，每条再独立验证，未通过的丢弃 | 采纳「并行评审 → 逐条验证 → 过滤 → 汇总」 |
+| 工作流 | 阶段产物落盘，下游只传路径；确定性检查优先于模型自报；人工升级以单个节点为粒度 | feature-dev：阶段之间有人工门禁 | 采纳产物落盘与确定性检查优先。P4 同时做声明式工作流、模型生成的步骤和沙箱脚本 |
+
+## 3. 目标
+
+harness 是基座能力，不是某个下游的领域规则。它回答四件事：这一轮看到什么、循环何时继续或停止、怎样判定结果为真、多个代理怎样拉起、分配、评审和汇总。
+
+内核放在 `agent-native` 的 `runtime`，直连、小队和子代理共用同一套循环。`core.Part` 到模型消息的投影留在 backend：内核不认识 `core` 类型。
+
+```text
+agent-native runtime
+  TurnLoop          预算、输出续写、重复调用检测
+  Transcript        原生回放，没有结果的调用补占位
+  ReminderBus       按来源节流的提醒，不改 system 段
+  HookBus           PreTool / PostTool / Stop / SubagentStop
+  CompletionGate    确定性检查 + 不带工具的验证器
+  SubagentRuntime   profile、深度 1、只回传摘要、完成通知
+
+backend 适配
+  LLMRunner         薄适配：事件、部件、落库
+  ctxasm            core.Message 投影为模型消息
+  交付物门禁         工件存在、版式检查、quality_review
+  工作流执行器       引擎驱动步骤，IntentID 路由
+```
+
+## 4. 分期
+
+### P0 回放保真与守卫加固（本文随附实施）
+
+- 助手历史按 `assistant{ToolCalls}` 与 `tool{ToolCallID, Content, IsError}` 回放。没有结果的调用补「（无结果：运行中断）」；孤立的结果跳过；空 ID 用 `hist_<消息ID>_<序号>` 补上。
+- 参数超过 4000 字符时截断其中的长字符串，结果仍是合法 JSON。
+- 跳过被守卫降级的过程文本（`Process=true` 且后面紧跟的不是工具调用）。从助手历史文本里剔除存量的 `[调用工具 `、`[工具结果 `、`[产出工件 `。
+- 守卫改成 `deliverableGate(body, produced, rc) (block bool, reason string)`，形状与 P1 的 Stop 门禁一致，P1 时平移进内核。
+- 新增判定：正文里出现伪造调用标记；本轮没有工件时声称文件已生成、已登记或已保存。纠正上限 2 次。回灌用占位文本，不把伪造正文再塞给模型。两次之后仍谎称，终轮正文降为过程，并追加一条非过程提示，说明本轮没有实际生成文件。
+- 提示词 `base.deliverables` 写明：工具只能通过函数调用触发，不要在正文里书写调用标记。版本升到 5。
+
+验收：回放后的模型输入里不再出现 `[调用工具` 文本；用第 26 轮那种「只有伪造标记、没有真实工具调用」的输入，守卫会拦住，不会再登记一个不存在的工件 ID。
+
+### P1 内核原语
+
+给 `agent-native` 的 `runtime.Config` 加上 Stop 门禁、工具前后钩子、提醒通道、重复调用检测、输出被截断时的续写，以及预算耗尽时保留已有部件再收尾。`LLMRunner` 改为 `runtime.Run` 的薄适配。P0 的 `deliverableGate` 平移成一个 Stop 门禁。
+
+验收：backend 与 agent-native 的既有测试保持通过；直连与小队成员走同一个循环。
+
+风险：`agent-native` 在 Dev 仓 `deps/`、backend 的 `deps/`、agent-squad 的 `deps/` 各有一处 gitlink。P1 起要按依赖顺序推进指针，不能只改最外层。
+
+### P2 结果把控
+
+- 独立验证器：不带工具的一次模型调用，按证据清单输出 JSON `{passed, reason, nextAction}`。拿不准判不通过。验证器出错或返回无法解析的内容时也判不通过（与 ZCode 的放行不同），整个门禁最多 3 次。
+- 确定性检查排在模型自报之前：本轮登记的工件确实存在、`housestyle.lint` 没有 error、`quality_review` 达到通过线。
+- 计划和待办按节奏用提醒回灌。例如连续多轮没有更新待办才提醒一次，避免每轮都占上下文。
+
+验收：评测夹具里「声称已交付但没有工件」的用例全部被拦下，并留下可核对的原因。
+
+### P3 多代理
+
+- 子代理用 Markdown 加 frontmatter 声明（`name`、`description`、`tools`、`model`、`maxTurns`），复用现有 `agent-sub-*.md` 并补上 frontmatter。调用方不能指定模型。
+- `delegate_task` 改为带工具的子循环。工具白名单里去掉派发类工具，嵌套深度为 1。父会话只收到摘要和工件路径。
+- 支持后台运行。完成后用通知回传，多条合并成一次注入。
+- 子 run 的消息与父会话历史隔离，不再被下一轮当成主对话回放。
+- `squad_orchestrate` 与直连子代理用同一套运行时。评审走「并行找问题 → 每条独立验证 → 丢掉未验证的 → 汇总」。
+
+### P4 意图到工作流
+
+执行器驱动 `prompt` / `tool` / `hitl` / `artifact` / `card` / `script`。三种来源共用同一步骤循环：插件声明的工作流、模型生成并经过同一套校验的步骤、以及在会话沙箱里跑的 Python 脚本。
+
+- 路由先走命令总线，再看意图绑定的工作流，最后才是普通回合。小队入口不提供 `run_workflow`。
+- 工作流启动时拷贝定义。插件卸载不影响已经在跑的那一份。
+- 声明式工作流最多 20 步。模型生成的最多 8 步，不能含 `script`，执行前必须经用户确认。critic 每步最多重试 3 次、缺省 1 次，整条工作流最多重试 6 次。无法解析的 critic 结果按不通过处理。
+- 脚本最多回调 50 次，单行请求不超过 1MB，超时缺省 600 秒、最长 1800 秒，墙钟时间包含等待人工和子代理。开关 `runtime.workflowScripts` 缺省关闭。模型写的脚本运行前必须确认；插件自带的脚本不需要确认。
+- 脚本以当前用户身份运行，工作目录是会话沙箱，没有网络或文件系统隔离。回调一律经过工具执行入口，不能调用 `run_python`、`run_shell`、`run_workflow` 和派发类工具。
+
+## 5. 不在本文范围
+
+- 单份纪要的内容质量（例如「3 项决议」与表格行数对不上）。那是生成质量，不是回放与门禁。
+- 把直连路径并进小队入口。小队仍是一种入口，循环归内核。
+- 下游领域的阶段门禁、文档树和追溯关系。那些留在下游仓。
+
+## 6. 已知待查项
+
+以下来自同一次只读梳理，不在 P0 修改。各自另开任务前先复核当前代码。
+
+- `quality_review` 的工作区路径疑似用了全局根，而文件工具用的是 `<根>/<owner>/<会话>`。单测把根直接设成文件所在目录，可能测不出来。
+- 工具确认卡算出了参数预览，但没有放进卡片，用户看不到参数就要批准。
+- 小队入口读的是默认 owner 的设置，不是当前租户的。
+- 插件宿主 `SettingsSchema` 持读锁时再调用会再次取读锁，中间若有写锁等待，有死锁风险。
+
+## 7. 验收（P0）
+
+- `modules/documents`：本文与路线图第 3 阶段的链接。
+- `modules/backend`：`go test ./internal/ctxasm/ ./internal/runtime/ ./internal/prompts/` 通过；随后在 Dev 仓 `make test` 做组合验证。
+- 回放用例覆盖：真实工具调用变成原生消息、缺结果时补齐、超长参数仍是合法 JSON、降级文本被跳过、存量伪造标记被剔除、工件正文回填保持不变。
+- 守卫用例覆盖：只有伪造标记也会拦截、纠正两次后附系统提示、回灌的是占位文本、引用已存在的工件不算谎称。

docs/proposals/2026-10-01-base-extension-roadmap.md

@@ -0,0 +1,80 @@
+# 基座路线图修正：基座不可改，下游独立仓二次开发
+
+状态：**实施中（2026-10-01）**；owner：weichen；主任务：Dev 仓 `feature/base-extension-roadmap`。
+规范依据：Development-Guidelines（workflows/delivery.md、standards/collaboration.md）；本文是项目级消费，不复制其正文。
+撰写日期：2026-10-01。
+
+---
+
+## 1. 基准
+
+Agent-System 是通用智能体基座：提供入口、能力、接口和基础功能，并能理解需求、对话、完成任务。页面、功能、工具、技能、MCP、知识库等模组通过插件接入。
+
+`~/downloads/agent-system-design`（智能研发管理系统，9 篇文档）是**下游特别系统**。它将在一个或多个独立仓库里二次开发，**不得修改基座**。修改基座的唯一合法理由是新增基础能力或扩展接口，路径为：下游提出扩展点申请 → 基座实现并发版 → 下游升级。
+
+基座只提供引擎、注册点和公开接口。领域数据与领域规则留在下游。延续骨架设计 4.12：知识库是数据，检索引擎是基础设施。
+
+已拍板且本次不推翻的约束：非容器化、单二进制优先；不迁移老系统资产与数据格式；在途 run 不做透明恢复（标记 `interrupted`，用户重发）。
+
+## 2. 原差距清单的处置
+
+对照基准从「两树一网蓝图」改为「通用基座 + 下游不改基座」。原清单编号沿用讨论稿。
+
+### 2.1 留在基座
+
+| 编号 | 项 | 本次落点 |
+|---|---|---|
+| 3 | 持久化后台任务，与会话锁解耦 | `background_tasks` + `/api/tasks` |
+| 5 | 仅 cmdbus 待确认态持久化 | `pending_confirms`；run 仍不透明恢复 |
+| 6 | HITL 超时计时 | `AskHITL` 尊重 `TimeoutSec` |
+| 8 | 记忆实现 | `memory_entries` + `/api/memory` |
+| 9 | 默认可选嵌入 | `models.embedding.provider=hash` 本地档；未设置仍按 D23 退化为全文 |
+| 13 | 通用审计（不含领域依据包） | `audit_events` + `/api/audit` |
+| 17 | LLM 成本与预算告警 | 日 token 累计，超预算写审计 |
+| 20 | 命令双入口对拍 | 每个内置命令必须出现在 `command-pairs.json`，否则测试失败 |
+| 22 | logging / error-code 接线 | 启动日志走 `logging-system`；插件失败带 `sys.unavailable` |
+| 24 | 依赖边界 lint | `make test-boundaries` 并入 `make test` |
+
+上下文滚动压缩：`summarizeBeyond=true` 时，窗口外历史改为抽取式摘要注入，不再只丢弃。
+
+代码执行：沿用已有解释器沙箱（工作区、超时、`runtime.exec` 开关），不另开无沙箱执行器。
+
+### 2.2 交给下游仓
+
+版本链与三态关系边、两速管道、文档/切片并发编辑、切片标签 schema、加密与 OCR 档位、ABAC 四元组、审计依据包、飞书业务、通知聚合、领域模板与流程骨架、领域评测指标、三套环境与故障注入、领域导出导入，以及设计文档自己的数据模型欠账。
+
+基座只提供这些下游会用到的通用口：渠道声明、知识数据集声明、后台任务、审计写入、插件隔离存储、混合检索。
+
+### 2.3 不采纳
+
+- 容器编排交付（与骨架「非容器、单二进制」冲突）。
+- 旧系统资产导入（与「不迁移、不兼容老数据格式」冲突）。
+- 为单一领域预造版本链、三态边、时间点重建。出现第二个使用方再上提基座。
+
+## 3. 阶段
+
+1. **公开扩展面与兼容规则**（本提案第 4 节 + 同日兼容提案）。下游今天必须能依赖基座，而不是 fork。
+2. **插件契约 v2**（同日插件提案）：声明、进程内编译、sidecar、前端 ESM。
+3. **智能体质量回路**：后台任务、记忆、上下文摘要、本地嵌入档、HITL 超时、确认态持久化、LLM 预算、通用评测夹具。回合循环、完成判定与多代理编排见 [2026-10-01-agent-harness.md](2026-10-01-agent-harness.md)（P0 起实施，内核下沉到 agent-native）。三个库的缺陷、借鉴与解耦见 [2026-10-02-agent-stack-completion.md](2026-10-02-agent-stack-completion.md)。
+4. **工程基座**：日志与错误码、通用审计、边界 lint、命令对拍、会话导出。
+
+目标系统薄切片放在 `examples/downstream-rdm`。它只 import 公开包。独立远程仓库由 owner 另行创建；本次不 `git init` 新仓。
+
+## 4. 公开扩展面（不改模块路径）
+
+后端业务代码继续留在 `internal/`。新增可导入包：
+
+- `agent-system-backend/pkg/extension`：进程内注册、宿主 API 客户端、`Main`。
+- `agent-system-backend/pkg/extension/link`：把 `Main` 接到 `app.Run`（仅基座与下游 main 空白导入）。
+
+模块路径保持 `agent-system-backend` / `agent-system-core` / `agent-system-ui`。下游 `go.mod` 用 `replace` 指向检出或 Gitea SSH。改成可直接 `go get` 的路径会打断现有全部 import，留到单独发版任务。
+
+`agent-system-ui` 仍是源码组合（提案 D29：出现第二宿主再发 npm）。本次补上 `exports` 指向的插件 SDK 源文件，不执行 npm 发布。
+
+公开面版本：`extension.SurfaceVersion = 2.0.0-experimental`。契约快照测试锁定导出符号；增删导出必须改快照。
+
+版本 tag 与包发布是高后果操作。准备命令见兼容提案，由 owner 确认后执行。本次不打 tag、不推送。
+
+## 5. 扩展点申请
+
+下游缺能力时开任务卡，写清：调用场景、希望的公开符号或 HTTP 路径、不改基座时的阻碍。基座只在批准后加公开面并发版。下游禁止提交修改 `internal/` 的补丁作为交付。

docs/proposals/2026-10-01-extension-compat-policy.md

@@ -0,0 +1,63 @@
+# 扩展面兼容与演进
+
+状态：**实施中（2026-10-01）**；owner：weichen；主任务：Dev 仓 `feature/base-extension-roadmap`。
+撰写日期：2026-10-01。配套：[基座路线图修正](2026-10-01-base-extension-roadmap.md)、[插件契约 v2](2026-10-01-plugin-contract-v2.md)。
+
+## 1. 版本
+
+| 面 | 标识 | 规则 |
+|---|---|---|
+| 插件清单 | `apiVersion` | 接受 `1.0` 与 `2.0-experimental`。其他值整包拒绝（fail-closed） |
+| 公开 Go 包 | `extension.SurfaceVersion` | 实验系列 `2.x.0-experimental`（2026-10-09 v0.2.0 时为 `2.5.0-experimental`，每次加法升次版本号）。实验窗口内允许破坏性调整，但必须改契约快照并在提案里写一句 |
+| HTTP API | 路径前缀 `/api/` 与 `/host/v1/` | 已发布路径只加字段，不改语义、不删字段。新能力用新路径 |
+
+弃用：公开符号先标记注释 `Deprecated:`，至少一个下游可升级的版本之后才删除。实验窗口内的删除仍要改快照测试，不能静默。
+
+## 2. 兼容窗口对插件清单的具体含义
+
+- `1.0`：原有 tools/panels/cards/intents/prompts/settings/commands/workspaces 行为不变。`requires.network` 为空时出站仍放行（历史清单没有白名单）。
+- `2.0-experimental`：同上，并接受 skills、mcpServers、knowledge、parsers、agents、channels、pages、scope、backend。`requires.network` 为空时 **拒绝** 声明式 HTTP 出站。
+
+新增 JSON 字段一律 `omitempty`，避免 1.0 黄金清单的编码发生变化。
+
+## 3. 契约快照
+
+`modules/backend/pkg/extension/surface_test.go` 用 AST 列出 `pkg/extension` 的导出类型与函数，与 `surface.txt` 比较。CI 通过 `make test`（含 `go test ./...`）执行。未更新快照的导出变更会失败。
+
+导出**接口**同时记录其方法（`Host.ParseDocument` 形态）——只加方法、不改顶层名的变更同样触发快照失败（2026-10-06 EXT-5 起执行）。
+
+依赖边界：`make test-boundaries` 拒绝
+
+- `pkg/extension` 导入 `agent-system-backend/internal`
+- 本仓 `examples/` 导入 `agent-system-backend/internal`
+
+## 4. 下游依赖（replace，本次不改模块路径）
+
+```
+require agent-system-backend v0.0.0
+require agent-system-core v0.0.0
+
+replace agent-system-backend => ../Agent-System-Dev/modules/backend
+replace agent-system-core => ../Agent-System-Dev/modules/core
+```
+
+后端模块自身的 `replace`（agent-native、logging-system 等）不会被下游继承。下游若编译进 `pkg/extension/link`（会拉起整个后端），需要复制后端 `go.mod` 里的 replace，并把路径改到基座检出。只做声明式插件则不需要 Go 依赖。
+
+## 5. 发版命令（owner 执行，本次未执行）
+
+tag 名以 V1.2 实施推进方案批复的 `v0.2.0` 为准（2026-10-05 对齐；五仓 backend/core/frontend/ui/Dev 同打）。
+具体提交、tag 消息与核对命令以 [v0.2.0 发版记录](../records/2026-10-09-base-v0.2.0-release.md) 为准（消息里的 SurfaceVersion 写发版时的实际值）：
+
+```
+git tag -a v0.2.0 <该仓对应提交> -m "<发版记录里的消息>"
+git push origin v0.2.0
+```
+
+npm 发布 `agent-system-ui` 仍按 D29 推迟到第二宿主出现。不要在实验窗口把 `private` 改成 false 后直接发布。
+
+## 6. 扩展点申请模板
+
+- 场景：哪一个下游仓、哪条用户路径走不通。
+- 希望新增的公开符号或 `/api`、`/host/v1` 路径。
+- 为何不能用现有注册点、后台任务、审计、KV、命令总线组合出来。
+- 兼容：加字段还是新路径。

docs/proposals/2026-10-01-plugin-contract-v2.md

@@ -0,0 +1,79 @@
+# 插件契约 v2
+
+状态：**实施中（2026-10-01）**；owner：weichen；主任务：Dev 仓 `feature/base-extension-roadmap`。
+撰写日期：2026-10-01。配套：[路线图](2026-10-01-base-extension-roadmap.md)、[兼容规则](2026-10-01-extension-compat-policy.md)。
+
+## 1. 四种形态
+
+下游按需要选一种或组合。基座对四种形态使用同一份 manifest 与同一套 fail-closed：任一资产解析失败则整包拒绝，保留上一状态。
+
+| 形态 | 下游交付 | 基座职责 |
+|---|---|---|
+| 声明 | `plugin.json` + 资产目录 | 注册 tools/skills/mcp/knowledge/parsers/agents/channels/pages/commands/… |
+| 进程内编译 | 下游 `main` import `pkg/extension` 并 `RegisterCompiled` | `link` + builder 模式产出**下游自己的**单二进制 |
+| sidecar | 原生进程，manifest `backend.mode=sidecar` | 拉起、健康（进程存活）、停止；环境变量注入 Host API |
+| 前端 ESM | `pages/*.json` 指向模块 | UI SDK 只暴露命令、SSE 与 `@ui` 组件；页面不得另起设计令牌 |
+
+进程内编译适合要事务一致性的领域逻辑。sidecar 适合异构语言或强隔离。声明式 HTTP 工具仍然只描述调用，不携带任意代码。
+
+## 2. manifest 增补
+
+`apiVersion` 用 `2.0-experimental` 才强制网络白名单。字段见 `modules/core/plugin_v2.go`。
+
+- `provides.skills`：`skills/<name>.md`，宿主写入 `<data>/skills/plugin-<id>/`。
+- `provides.mcpServers`：并入小队 MCP 配置（与 `tools.mcp.servers` 合并）。
+- `provides.knowledge|parsers|agents|channels|pages`：声明登记，供清单 API 与前端加载。
+- `scope.tenants/projects`：空 = 全部可见。
+- `backend.command`：sidecar 可执行文件（相对插件目录或 PATH）。`schemaVersion` 记入 `plugin_schema`。
+
+密钥查找顺序：`secrets.<pluginId>.<authRef>`（按工具执行时的 `OwnerID`），再回落同名全局设置。不再在绑定期固定读 `OwnerDefault`。
+
+## 3. Host API（sidecar 与外部进程）
+
+监听由基座在本机拉起，令牌随进程环境变量 `AGENT_HOST_API`、`AGENT_HOST_TOKEN` 下发。
+
+| 方法 | 路径 | 作用 |
+|---|---|---|
+| PUT/GET | `/host/v1/kv/{key}` | 插件隔离 KV（带 owner 与 plugin id） |
+| POST | `/host/v1/audit` | 写通用审计 |
+| POST | `/host/v1/commands/{id}` | 走命令总线 |
+| POST | `/host/v1/llm` | 代理聊天补全；未配置模型返回 503，不静默伪造 |
+| GET | `/host/v1/knowledge/search` | 混合检索（引擎在基座） |
+
+插件故障不拖垮基座：sidecar 退出只记日志与审计，不退出主进程。
+
+## 4. 进程内注册
+
+```go
+func init() {
+    extension.RegisterCompiled(extension.InProc{
+        ID: "rdm",
+        Register: func(reg extension.Registry) error {
+            return reg.AddSkill("rdm-note", "# …")
+        },
+    })
+}
+```
+
+下游 main：
+
+```go
+import _ "agent-system-backend/pkg/extension/link"
+func main() { extension.Main(extension.Options{Addr: "127.0.0.1:8787"}) }
+```
+
+## 5. 前端
+
+`@ui` 导出 `createPluginBridge`：`execCommand` 与 `subscribeEvents`。插件页面模块默认导出 `mount(el, bridge)` / `unmount()`。宿主按 `pages[].module` 动态 `import()`。插件 TSX 与基座一样受 design-guard 约束（令牌、无私人 keyframes、无行内字号）。
+
+## 6. 生命周期
+
+- 启用：`POST /api/plugins/{id}/enabled`，按租户记 `plugin_grants`。
+- 升级：`backend.schemaVersion` 大于已记录版本时调用宿主迁移钩子（KV 命名空间不清空；钩子由进程内扩展提供）。版本只升不降，降级拒绝装载。
+- 管理面：`GET /api/plugins` 返回 manifest（含 v2 provides）以及技能/页面/渠道声明。既有设置页「插件」分组继续承担热重载。
+
+## 7. 开发体验
+
+- `make plugin-new NAME=<id>` 在 `examples/plugins/<id>` 生成声明式骨架。
+- `examples/plugins/decl-demo`、`examples/downstream-rdm`、`examples/sidecar-demo`、`examples/page-demo` 各覆盖一种形态。
+- 验收：`examples/downstream-rdm` 的测试不导入 `internal`，并由 `make test-boundaries` 卡住。

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

@@ -0,0 +1,278 @@
+# 通用智能体、小队与意图：完善、借鉴与解耦
+
+状态：**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 代码，不改三个库的指针。

docs/proposals/2026-10-05-ext-1-inproc-command-handler.md

@@ -0,0 +1,48 @@
+# EXT-1：进程内命令处理器与 owner 作用域宿主句柄（最小集）
+
+状态：**实施中（2026-10-05）**；owner：weichen；主任务：Dev 仓 `feature/ext-1-inproc-handler`（任务卡即本提案的申请卡）。
+撰写日期：2026-10-05。配套：[扩展面兼容与演进](2026-10-01-extension-compat-policy.md)、[基座路线图修正](2026-10-01-base-extension-roadmap.md)、V1.2 实施推进方案（批注 1 最小/完整集划分）。
+
+## 1. 申请卡（compat-policy §6 四要素）
+
+- **场景**：Agent-System-RDM 的 `rdm.ingest` 等命令经四入口（button/card/slash/chat）分发到 `cmdbus.Dispatch` 时被以 `no host handler bound` 拒绝——`Registry.AddCommand` 与 manifest `provides.commands` 只注册规格不绑处理器；进程内插件同时没有任何 owner 凭证与基座服务端回调身份（H4）。
+- **希望符号**：`pkg/extension` 新增 `Request` / `Handler` / `Host`（owner 作用域宿主句柄最小集）与 `Registry.AddCommandHandler(spec, h)`；基座侧配套 `cmdbus.Bus.RegisterPluginCommand`。
+- **为何现有注册点组合不出来**：`RegisterPluginCommands` 仅登记 spec；`HostClient` 走 sidecar HTTP 且需要进程内不可得的 host token；owner 作用域必须由基座在分发时构造，插件无法自造。
+- **兼容**：只加符号与方法，不改既有路径语义；`SurfaceVersion` 保持 `2.0.0-experimental`，实验窗口内的接口调整以本提案为记录。
+  （2026-10-09 注：此后 EXT-8/9/11/12 与执行原语硬开关按 compat-policy 逐次加法升级，v0.2.0 发版时为 `2.5.0-experimental`，见 [v0.2.0 发版记录](../records/2026-10-09-base-v0.2.0-release.md)。）
+
+## 2. 公开面变更（surface.txt 12 → 15 项）
+
+`pkg/extension` 新增导出符号 `Handler`、`Host`、`Request`（见 `host.go`）；`Registry` 接口追加 `AddCommandHandler` 方法（方法不计入快照）。
+
+**依赖变化**：根包自此 import `agent-system-core` 类型（`KnowledgeDoc`/`RetrievalHit`/`Artifact`/`ID`），此前为零外部依赖。声明式 Go 插件的 `go.mod` 需按 compat-policy §4 模板同时 require+replace `agent-system-core`。
+
+## 3. Host 接口（最小集）
+
+```
+PluginID() / Owner()
+KVPut / KVGet                    // 按 pluginID+owner 隔离
+Audit(action, target, evidence)  // owner 名下审计事件，Actor=plugin:<id>
+Complete(ctx, prompt)            // 经基座 LLM 路由（owner 模型配置生效）
+KnowledgeSearch(ctx, projectID, text, topK)
+KnowledgeWrite(ctx, docs, embed) // Owner 强制改写为本次分发 owner；Source 空则补 plugin:<id>；
+                                 // embed=false 只写全文，embed=true 建向量（失败降级纯全文）
+TaskCreate / TaskUpdate          // 后台任务台账（执行体由下游自跑）
+ArtifactGet / ArtifactContent    // 工件只读（R1-3 ingest 读原件）
+```
+
+artifacts **写入**属完整集，R1-7 前再评估（V1.2 批注 1）。
+
+## 4. 基座实现要点
+
+- `cmdbus.Bus.RegisterPluginCommand(spec, h)`：登记规格（SourcePlugin）+ 绑定处理器；高危命令的内联确认卡拦截位于 handler 查找之前，插件命令天然覆盖。
+- `internal/app.hostcaps`：聚合 store/检索管线/LLM 路由，同一实现同时服务 hostapi.Server 闭包与进程内 `inprocHost`（批注 1：复用 owner 作用域函数，不新造句柄）。
+- `inprocHost` 每次分发按 `req.Owner` 新建，所有 store 调用以该 owner 为第一参数。
+- `rag.Pipeline.IndexChunks` 自 `IndexDocument` 抽出：写全文（回填 ID）后建向量，embed 失败降级语义不变。
+
+## 5. 验证
+
+- cmdbus：处理器被 Dispatch 调用返回 committed；仅登记规格仍 rejected（no host handler bound）；高危插件命令先确认卡后执行。
+- internal/app（组合根级）：两 owner 各分发一次，审计/知识/KV/任务台账各落自己 owner 名下（D8 烟测的单元级前置）；`provider=hash` 档 `KnowledgeWrite(embed=true)` 写出向量行且 Owner/Source 被强制改写。
+- `examples/downstream-rdm` 增加 `rdm.ping` 处理器示范（读工件元数据 + 写审计）。
+- 权威验证源：CI 在 PR HEAD 上 `make test` + `make build`（.gitea/workflows/ci.yaml）。

docs/proposals/2026-10-06-ext-5-host-parse-document.md

@@ -0,0 +1,51 @@
+# EXT-5：宿主句柄开放内置文档解析（含 xlsx/pptx 内置解析器）
+
+状态：**实施中（2026-10-06）**；owner：weichen；主任务：Dev 仓 `feature/ext-5-host-parse`。
+规范依据：[扩展面兼容与演进](2026-10-01-extension-compat-policy.md)（§6 扩展点申请模板）；前序 [EXT-1](2026-10-05-ext-1-inproc-command-handler.md)（Host 最小集）。相关：EXT-4（下游注册 inproc 解析器，备选、未提交）——方向相反，本申请不依赖它。
+撰写日期：2026-10-06。
+
+## 1. 申请四要素（compat-policy §6）
+
+- **场景**：Agent-System-RDM 的 F1 上传主链（`rdm.upload`，PR #103）需要解析用户上传的文档；基座 `internal/ingest` 有内置解析器但没有经 `extension.Host` 开放——下游拿到的只有 `ArtifactGet/ArtifactContent`（原件字节），要解析就得自带一份解析代码（RDM 现状：自带 md/txt/docx 解析器，pdf/pptx/xlsx 一律回「不支持」）。MS1（W4，11-01）验收第 4 条要求「报价单 Excel + 图文混排 PPT 解析完整性核对」，当前两条路都走不通：句柄没有解析方法，基座自身也没有 xlsx/pptx 解析器。
+- **希望符号**：`pkg/extension` 的 `Host` 新增一个方法：
+
+  ```go
+  // ParseDocument 用基座内置解析器把文档字节解析为 ParsedDocument（EXT-5）。
+  ParseDocument(ctx context.Context, filename, mime string, content []byte) (core.ParsedDocument, error)
+  ```
+
+  同时 `internal/ingest` 新增 `builtin:xlsx`（xlsx/xlsm）与 `builtin:pptx`（pptx/pptm/ppsx）两个内置解析器——这两个是基座能力补齐，不依赖 EXT-5，上传/附件路径同步受益。
+- **为何现有注册点组合不出来**：`ParsersDescription` 只是注册表描述（设置页/文档用），没有执行入口；`PluginParserDecl.Tool` 仅接受内置名或 sidecar 工具名（core/plugin_v2.go 注释明示）；Host 最小集里与文档相关的只有工件只读两个方法。下游唯一替代是复制基座解析代码进自己仓库——违背「引擎在基座」的接缝表裁定。
+- **兼容**：只加符号。实验窗口内给 `Host` 接口加方法会破坏第三方 fake 的编译（compat-policy §1 允许，须改快照并在提案里写一句）；`SurfaceVersion` 保持 `2.0.0-experimental`。本次同时把契约快照升级为**记录导出接口的方法**（此前只记顶层名，加方法这类变更检测不到）。
+
+## 2. 接口语义
+
+- 分派按文件扩展名，与 `ingest.Parse` 完全一致（同一实现，`hostcaps.parse` 委托）。
+- 返回 error 的只有两种情况：`ctx` 已取消；输入超过 100 MiB（与上传端点 `io.LimitReader(file, 100<<20)` 同口径）。除此之外的「不可解析」都返回带 `Warnings` 的文档（显式失败，不静默），`Meta.Confidence` 相应降低。
+- 纯计算：不读写 owner 数据、不走存储。要解析工件原件，先调 `ArtifactContent`（owner 作用域由它保证），把字节传进来——不另造句柄、不新增凭证面。
+- 参数为位置参数（filename/mime/content），与 Host 既有方法风格一致；不引入 options 结构。
+
+## 3. 新解析器格式与限制
+
+**xlsx/xlsm（builtin:xlsx）**：工作表顺序取 `workbook.xml` 的 sheets 列表（不按文件名），target 经 rels 解析（相对/绝对路径）；共享字符串含富文本 run（排除注音 `rPh`）；单元格覆盖 `t=inlineStr/str/b/e/n`（布尔输出 TRUE/FALSE、错误值原样）、公式取缓存值（无缓存输出 `=公式`）、日期按内置格式 ID 与含 y/m/d/h/s 记号的自定义格式转 ISO（1900/1904 双日期系统）；稀疏列按单元格引用就位，去行尾空与全空行；隐藏工作表标题标「（隐藏）」；每个工作表产出一个 heading 块 + 一个 table 块，空表跳过。
+
+**pptx/pptm/ppsx（builtin:pptx）**：幻灯片顺序取 `presentation.xml` 的 `sldIdLst`；标题占位符（title/ctrTitle）产「幻灯片 N：标题」heading 块；正文形状每形状一个 para 块（`a:br` 换行）；组合形状递归；`mc:AlternateContent` 只取 Choice 分支；graphicFrame 表格产 table 块（合并单元格位置留空以保持列对齐）；备注页正文产「备注：…」；跳过页码/日期/页脚占位符。图片、SmartArt 不解析（无 OCR/图形理解，属远期档）。
+
+**旧二进制格式 doc/xls/ppt**：不做解析，Warnings 给可操作提示（请转存 docx/xlsx/pptx 后重传）。
+
+**上限**（包级变量，测试可覆盖）：单元格总数 200000、列数 1024、zip 内单部件解压 64 MiB（zip 炸弹防护，docx 一并受益）；超限保留已解析部分 + Warnings + `Confidence` 降 0.6，原件不受影响。
+
+## 4. 验证
+
+- 手工构造 OOXML zip 的单元测试：xlsx（表序/富文本/公式/日期/稀疏列/隐藏表）、pptx（sldIdLst 序/标题/组合/AlternateContent/表格/备注）、失败路径（损坏 zip/缺 workbook.xml/部件超限/超上限）。
+- openpyxl 与 python-pptx 现场生成真实文件的轮测（依赖缺失时 t.Skip；CI 已装这两个包）。
+- `internal/app` 走真实 `applyCompiled → cmdbus.Dispatch → inprocHost` 链路：alice 解析自己的 xlsx 工件成功、bob 同 ID 被拒（owner 作用域不因新方法放宽）；ctx 取消与超限两条 error 路径。
+- 上传端点 e2e：xlsx 上传返回 `parser=builtin:xlsx` 且无 Warnings，知识检索命中单元格文本。
+- surface 快照按「顶层名 + 接口方法」新口径重建并通过。
+
+## 5. 不在本文范围
+
+- sidecar `/host/v1` 的 HTTP 解析路由（sidecar 形态可继续读字节走自己的解析；出现真实需求再申请）。
+- MinerU 交叉验证、OCR、SmartArt、旧 OLE 格式解析。
+- 上传超过 100 MiB 被静默截断的问题、`kindOf` 与 `artifactKindOf` 口径不一致——已登记为 EXT-5 盘点发现的缺陷，另行修复。
+- 下游把上传链路切到 Host 解析、RDM pin 升级到 v0.2.0：RDM 仓自己的任务卡。

docs/proposals/2026-10-07-agent-stack-n1q1i1-plans.md

@@ -0,0 +1,383 @@
+# N1 / Q1 / I1 实施方案：内核 harness、图执行、命令化识别
+
+状态：**proposed（2026-10-07）**；owner：weichen；主任务：Dev 仓 `feature/agent-stack-n1q1i1-plans`。
+上游：[2026-10-02-agent-stack-completion.md](2026-10-02-agent-stack-completion.md) §5 分期（下称「总提案」，行号以该文件为准）；审计：[2026-10-02-agent-stack-audit.md](../records/2026-10-02-agent-stack-audit.md)。
+规范依据：Development-Guidelines（workflows/delivery.md、standards/collaboration.md、standards/agent-execution.md、standards/verification.md）；本文是项目级消费，不复制其正文。
+
+本文把总提案的 N1、Q1、I1 三个阶段落成可启动的实施方案：现状基线、工作包分解、文件级落点、测试与验收、风险。本文不实施代码；三个阶段的实现各走各的任务（总提案「每阶段单独任务」）。
+
+---
+
+## 1. 共同基线与三任务协调
+
+### 1.1 现状基线（撰写日实测）
+
+| 仓 | pin | 说明 |
+|---|---|---|
+| Agent-Native | `3a110a728cf520cfbbbafc0c4c75f14bf78bec3f` | durable-rewind-3 与 permission-hooks（PR #173）之后 |
+| Agent-Squad | `5a57636cc0b8426a86a72bbbdd5b7f30e4fcac88` | 同上 |
+| Agent-Intent | `65aaebca1ea69ab7d48eda51d33ef1d4eea5a0bf` | agent-stack-d1（R2）之后 |
+| Backend | `e7fb276ee9b3af51329a0c6df27517184b26edee` | v0.1.0-4 |
+| Core | `0b5c7747a3165bf0d0f2219204b7b70ec3ed7645` | v0.1.0 |
+
+两个要点：
+
+- **审计基线已旧**。审计写于 native `c6d867c` / squad `590fd86`；R1/R2 之后多条审计项在当前 pin 已修（native 侧 N1/N7/N8/N21/N22/N30/X4，squad 侧 Q1–Q5/Q7/Q14–Q16/Q18/Q19）。本文逐节标注「已修 / 仍开放」，实施时不得以审计原文为唯一依据，须以当前代码为准。
+- **D1 的借力点已成**：三库核心互不依赖（native `go.mod` 只依赖 error-code-system 与 logging-system）、Options 已按端口拆分、跨库类型只出现在 adapters 子模块。N1/Q1/I1 都假设这个地基，不再返工。
+
+### 1.2 分支与合入协调
+
+按 AGENTS.md「同批互不依赖的子任务用同一 R0 的兄弟分支」：
+
+- 三个任务分支：`feature/agent-stack-n1`、`feature/agent-stack-q1`、`feature/agent-stack-i1`，从同一权威 `origin/main`（同一 R0）切出，互不嵌套。
+- 每个任务的 PR 链固定为三段、按序合入：**库仓 PR → Backend 仓 PR（bump 嵌套 pin + 适配）→ Dev 仓 gitlink PR（bump 顶层 pin 与 modules/backend）**。R0 已落地的检查脚本核对 Backend `deps/` 与 Dev 指针一致，不允许只推一层。
+- 三任务并行时的冲突面：N1 与 I1 都动 Backend（N1 在 `internal/app`、`internal/runtime`、`internal/runmgr`；I1 在 `internal/server`、`internal/intentgate`、`internal/runmgr`），`internal/runmgr` 是唯一重叠文件，**后合入者按 `make task-sync` 并入最新 main 后解决**；Dev 仓 gitlink pin 同理，后到者 sync 后重指。
+- Q1 若涉及 `modules/backend/internal/squadadapter` 消费方适配，改动限制在「驱动循环跟上新引擎 API」范围内；编排收敛（WorkflowDef 编译、internal/workflow 退役）是 Q3，不在 Q1。
+
+### 1.3 共同验收纪律
+
+- 每阶段都带 E 评测（总提案 §5 E 节）：Native 的对照用脚本化模型输出，不把模型自报当通过。
+- 证据按 AGENTS.md「证据与验证门禁」：完成声明的 precheck / task-sync / 测试三段输出由 `make evidence` 写入任务卡；测试通过的权威源是 CI（PR HEAD 上 `make test`+`make build`），本地输出是 SELF 级辅助线索。
+- 各阶段验收条款在本文 §2.6 / §3.6 / §4.6 给出机器可核对的形式，与总提案对应条目逐条映射。
+
+---
+
+## 2. N1 内核 harness
+
+总提案原文（§5 N1）：「AgentSpec、HookBus、PermissionPolicy、三类 guardrail。CompletionGate 与提醒从 Backend 下沉。`adapters/native` 透传钩子。Backend 改为消费，A/B 对照直连行为。」
+
+### 2.1 现状与 gap
+
+| 需求项 | 现状（证据） | gap |
+|---|---|---|
+| AgentSpec | **不存在**（全库无此类型）。最接近的是 `deps/agent-native/runtime/subagent/subagent.go:21-33` 的委派 `Request`（Goal/Inputs/WriteScope/NonGoals/DoneCriteria/Deliverables + Deadline/MaxToolCalls）；backend 子代理画像是 `prompts.SubagentSpec` + `fallbackSubagentSpec`（`modules/backend/internal/runtime/sub_loop.go:18-27`） | 类型、文件格式、插件校验入口全缺 |
+| HookBus | 已有：`runtime/hooks/hooks.go:56-107`（On/Emit，决策优先级 block/deny>ask>modify>allow）。事件枚举 hooks.go:9-20 有 SessionStart/UserPromptSubmit/PreToolUse/PermissionRequest/PostToolUse/PostToolUseFailure/Stop/SubagentStart/SubagentStop/PreCompact。**实际发射点只有 3 处**：`runtime/loop.go:512`（Stop）、`:532`（PreToolUse）、`:557`（PostToolUse/Failure） | 缺 PostToolBatch、SessionEnd 两个事件；6 个已枚举事件无发射点；无「已在续跑中」防递归标志（hooks.go:33-43）；**Ask 决策被当拒绝处理**（loop.go:534-540），无 ask→宿主审批→放行回路 |
+| PermissionPolicy | 以函数式存在：`runtime/policy/policy.go` 三档 Mode（:9-13）、Rule（:30-34）、Decide（:55-93，deny>计划禁写>本会话放行>ask>auto_edit>allow）、TraitsFor（:113-128）、ClassifyCommand（:145-158）、Visible（:96-101）。backend 直接消费（`internal/runmgr/runmgr.go:681-685`） | 无 Policy 命名类型、无规则序列化形态；会话放行记忆在 backend 内存 map（runmgr.go:265-286），未下沉 |
+| 三类 guardrail | **不存在**（输入/输出/工具三层全无，grep 无命中）；内核只有 `RepeatGuard` 布尔（loop.go:93-95） | 三层端口与执行点全缺 |
+| CompletionGate 下沉 | 在 backend 直连路径三层串联：`deliverableGate`（`internal/runtime/llm.go:477-510`，上限 `maxDeliverableGuards=2`）→ `checkDeliverables`（`runtime/verify.go:48-84`，工件存在+非空+`quality.ScoreBytes`）→ `runVerifier`（verify.go:86-122，开关 `runtime.verify`，提示词 `aux.verify.final`）。经自建 hooks 总线挂一个 Stop 处理器注册进内核（`internal/runtime/llm_direct.go:162-172`） | 依赖 `core.ArtifactRef`、`rc.Artifact`、`quality.ScoreBytes`、提示词库——未端口化；**子代理（sub_loop.go:98-112 无 Stop/Hooks）与小队步骤（app.go:202-217 未注入 Stop）都无此门禁**；小队只有事后 `claimsFalseDeliverable` 判失败（`runtime/squad_runner.go:90-92`） |
+| 提醒下沉 | backend 侧 `directRun.reminders`（verify.go:223-250，连续 3 个工具轮未更新计划/待办则提醒，`reminderToolGap=3`、`maxChecklistReminders=3`，用库侧 `reminders.Bus` 节流去重）。内核有通用 `Reminders func(turn)` 回调（loop.go:90-92） | `rc.Todos()/Plan()` 与 `core.TodoList/PlanSnapshot` 是产品接口，未端口化；小队/子代理路径未注入 |
+| adapters/native 透传 | **库侧管道已修**：`GateOptions`（`adapters/native/backend.go:70-80`，含 BeforeTool/AfterTool/Stop/Reminders/RepeatGuard/Hooks/Ask）、透传（:370-372）、`gateBus`（:464-496）；squad 侧映射（`deps/agent-squad/adapters/native/register.go:39-49,92-96`） | **装配未接通（N31 剩余部分）**：backend 组合根只注入 `RepeatGuard:true` 与 plan 模式 BeforeTool（`internal/app/app.go:207-217`）；直连与子代理绕过 `exec.Backend` 直接调 `nruntime.Run`（llm_direct.go:173、sub_loop.go:98） |
+| Backend 改为消费 | `adapters/native.Backend` 只实现旧门面 `exec.Backend`（backend.go:130/140），未实现 `ContractBackend`；`conformance.Suite`（conformance/fake.go:106，三条用例）无真实实现调用方 | ContractBackend 实现与 conformance 接入 |
+
+### 2.2 工作包分解
+
+**WP1 AgentSpec 与插件校验**（新类型，库侧 `runtime/subagent` 或新 `runtime/agentspec` 包）
+
+- 定义 `AgentSpec{Name, Description, Prompt, Tools, DisallowedTools, Model, PermissionMode, Skills, MaxTurns, MemoryScope, Effort, Background, WorktreeIsolation, OutputSchema}`，字段对齐总提案 §2.1 子代理行（Claude subagents frontmatter 集 + `outputSchema`）。
+- 文件格式：Markdown frontmatter（`agent-*.md`），加载器在库侧；backend 现有 `prompts.SubagentSpec` 迁移为读 AgentSpec 文件，`fallbackSubagentSpec` 保留为内置兜底。
+- **校验红线**：插件清单里的 AgentSpec **不得声明 hooks、MCP、权限模式**（总提案 §2.1 权限行），校验在插件装载期 fail-closed。
+- 测试：字段 round-trip、缺省值、插件声明 hooks/权限模式被拒、backend 旧画像到 AgentSpec 的等价映射。
+
+**WP2 HookBus 补全与 ask 回路**
+
+- 事件枚举加 `PostToolBatch`、`SessionEnd`（对齐总提案 §2.1 事件名单）；`Call` 增加「已在续跑中」标志位，hook 触发续跑时下游可见、禁止递归触发 Stop 系事件。
+- 发射点补齐：`SessionStart`（Run 入口）、`UserPromptSubmit`（用户消息入列）、`PermissionRequest`（gateTool ask 时）、`SubagentStart/SubagentStop`（委派创建/收口）、`PreCompact`（compact 前）、`SessionEnd`（Run 出口）、`PostToolBatch`（工具批结束）。
+- **ask 回路（本阶段最关键的行为变化）**：`gateTool` 收到 ask 不再当拒绝（loop.go:534-540 现状），改为发 `PermissionRequest` 并等待宿主决策端口；宿主默认实现 = backend HITL 确认卡（runmgr.go:384-424 现有 AskHITL/waitHITL 机制接为端口实现）。`deny` 语义不变；`block` 不变。
+- 风险与兜底：ask 从「拒绝」变「挂起审批」是行为变化；用 A/B 对照（WP6）证明「无 hook 注册时行为与现状逐字节一致」，把行为变化严格限制在「注册了审批端点」的场景。
+- 测试：每个新发射点一例；ask→批准→执行、ask→拒绝→配对结果两条回路；续跑标志防递归；与既有 `ab_gate_test.go` 对照不回归。
+
+**WP3 PermissionPolicy 命名类型与会话放行下沉**
+
+- 在 `runtime/policy` 增加 `Policy` 结构体：`{Mode, Rules []Rule, SessionAllow AllowStore}`，`Decide` 收为方法；`AllowStore` 是端口（Get/Add/List，`key = 工具+参数模式`），库内给内存实现，backend 把 `sessionAllows`（runmgr.go:265-286）替换为该端口的实现（本会话内存即可，持久化形态留给 N3 的 Memory/RunState）。
+- `Visible`、模式切换（含 `ExitPlanMode`，runmgr.go:257-263）改走 `Policy`。
+- 测试：规则优先级矩阵在结构体形态下全等复现现有 `policy_test.go` 四例 + backend `perm_test.go`；会话放行跨调用存活。
+
+**WP4 三类 guardrail 端口**
+
+- 端口定义：`InputGuardrail`（只作用于入口智能体的用户输入）、`OutputGuardrail`（只作用于给出最终结果的那个智能体）、`ToolGuardrail`（每次工具调用）。形态 = `func(ctx, payload) (allow / deny / modify + 原因)`，与 HookBus 决策词汇一致。
+- 执行点：输入在 UserPromptSubmit 处、输出在 Stop 判定前、工具在 PreToolUse 链内。guardrail 与 hook 的关系写清：guardrail 是类型化语义层，hook 是通用事件层，guardrail 以 hook 实现注册。
+- 测试：三层各自 deny/modify/allow 各一例；只入口、只最终输出的作用域限定各一例。
+
+**WP5 CompletionGate 与提醒下沉**
+
+- 下沉的不是实现而是**组合点**：库侧新增「输出 guardrail 注册位 + 提醒源注册位」，产品依赖端口化：
+  - 工件存在/非空/质量分：端口 `ArtifactVerifier`（backend 用 `rc.Artifact` + `quality.ScoreBytes` 实现，verify.go:48-84 逻辑迁入 adapters 侧实现）；
+  - 独立验证器：端口 `FinalVerifier`（backend 用 `aux.verify.final` 提示词 + 独立模型调用实现，verify.go:86-122 迁入）；
+  - 计划/待办提醒源：端口 `ProgressProbe`（backend 用 `rc.Todos()/Plan()` 实现，verify.go:223-250 迁入）；`maxDeliverableGuards=2`、`maxVerifyContinuations=3`、`reminderToolGap=3`、`maxChecklistReminders=3` 等阈值随端口配置走，默认值不变。
+- 迁移后 `deliverableGate`/`checkDeliverables`/`runVerifier`/`directRun.reminders` 在 backend 只剩端口实现与装配，判定逻辑（正则族、续跑上限、节流）进库。
+- 测试：库内脚本化夹具复现 backend `llm_test.go`/`llm_verify_test.go` 的全部门禁用例（GuardTwiceThenNotice、验证器拒绝后通过、垃圾失败关闭、提醒节流等），确保下沉后逐条等价。
+
+**WP6 Backend 装配接通与 A/B 对照（N31 收口）**
+
+- `internal/app/app.go`：直连、子代理（sub_loop.go:98-112）、小队（squadadapter `AgentNativeOptions`，app.go:207-217）三条路径注入同一套 `Hooks/Stop/Reminders/Ask`；小队经 squad→native 两级 GateOptions 透传（管道已在，只装配）。
+- 直连与子代理改为经 `adapters/native` 消费（不再裸调 `nruntime.Run`）；`adapters/native.Backend` 实现 `ContractBackend`（补 Descriptor），`conformance.Suite` 挂到 native 后端跑（现有三条用例起步）。
+- **A/B 对照（提案验收核心）**：同一组脚本化模型输出（含停止、提醒、工具拒绝、HITL 分支），分别在「旧直连装配」与「新下沉装配」下跑，断言停止原因、提醒次数、工具拒绝序列一致。`runtime/ab_gate_test.go` 是库内雏形，本 WP 把它扩成 backend 侧对照。
+- 小队路径行为变化明示：小队步骤首次获得 Stop 门禁与提醒——这是本阶段有意的行为拉齐，写进 PR 影响段。
+
+### 2.3 涉及仓与落点汇总
+
+- Agent-Native：`runtime/hooks`、`runtime/policy`、`runtime/loop.go`、`runtime/subagent`（或新 agentspec 包）、新 `runtime/guardrails`（或并入 hooks）、`adapters/native`、`conformance`。
+- Backend：`internal/app/app.go`、`internal/runtime/{llm.go,llm_direct.go,verify.go,sub_loop.go,squad_runner.go}`、`internal/runmgr/runmgr.go`（AskHITL 接端口、sessionAllows 替换）、`internal/squadadapter`（透传配置）。
+- Dev：两层 pin。
+
+### 2.4 实施顺序
+
+WP2（ask 回路）与 WP3（Policy 类型）先行（其余都依赖决策与权限语义）→ WP1 AgentSpec、WP4 guardrail 端口 → WP5 下沉 → WP6 装配与 A/B。每 WP 单独提交，库内测试绿了再进下一 WP。
+
+### 2.5 风险
+
+- ask 语义变化是最大风险点：必须有 A/B 对照证明默认行为不变（见 WP2/WP6）。
+- 下沉搬移正则族与阈值时容易丢行为：WP5 的「逐条等价」测试先行（先在库内写好对现网行为的刻画，再搬）。
+- 小队首次上门禁可能暴露存量提示词的虚假交付习惯：`claimsFalseDeliverable` 与 Stop 门禁并存期要观察误报率，必要时给小队入口单独的宽松阈值（配置项，不硬编码）。
+
+### 2.6 N1 验收（对照总提案 §5 N1 验收逐条）
+
+| 总提案条款 | 机器可核对的验收 |
+|---|---|
+| 同一组脚本化模型输出，下沉前后停止原因、提醒次数、工具拒绝一致 | backend 侧 A/B 对照测试在 CI 通过；对照夹具覆盖 deliverableGate 命中/未命中、verifier 拒绝/通过/垃圾、提醒触发/节流、工具拒绝 |
+| 插件里的 AgentSpec 不能带钩子和权限模式 | 插件装载测试：声明 hooks/permissionMode 的 AgentSpec 被拒且错误可定位到字段 |
+
+## 3. Q1 图执行
+
+总提案原文（§5 Q1）：「superstep、三档检查点、attempt id、interrupt / resume。`Needs` 驱动依赖。读写集。可组合 Termination。Store 接口。platform 的 SQLite 成为 Store 的一个实现，不再单独驱动一套运行。」
+
+### 3.1 现状与 gap
+
+| 需求项 | 现状（证据） | gap |
+|---|---|---|
+| superstep | 无。执行是「线性步骤数组 + 状态机扫描」：`flowDriver.advance`（`deps/agent-squad/squad/workflow.go:22-101`）一个大循环扫到挂起/终态；leader 是独立大循环（leader.go:178-372）；`WorkflowPlan.CurrentStepIndex`（models.go:124）是从未写入的死字段 | 整个推进模型 |
+| 三档检查点 | 无 checkpoint 类型。最接近的是「步骤完成即 `st.save()` 全量落盘」（workflow.go:367-371，同步单档）+ 挂起时 pending.json。原子写已修（`AtomicWrite`，workspace.go:307-349） | 检查点类型与退出时/异步/同步三档全缺 |
+| attempt id | 只有计数器 `Attempts`（models.go:93-94）与不变的 `ExecutionID = runID+"-"+stepID`（workflow.go:286）；恢复靠「running + Attempts>=2 + HITL 模式」启发式（engine.go:879-925），无产物校验 | attempt id、幂等键、「副作用次数=1」的判定基础 |
+| interrupt/resume 同一对原语 | 挂起原语面向人：`hitlGate`/pending.json + `Respond`/`Resume`（engine.go:481,928）；事件唤醒是旁路 `WaitCondition` + `SweepWakeups`（engine.go:1080-1163）；`SweepExpired`（engine.go:1107-1130）**无调用方，是死代码** | 统一原语；SweepExpired 接线 |
+| Needs 驱动依赖 | 字段已声明（models.go:90）但**调度完全不读**（全仓唯一引用即声明行）；调度只看「相邻 Parallel 标记」（workflow.go:44-72） | DAG、拓扑排序全缺 |
+| 读写集 | 无 Reads/Writes 字段；「写同一工件必须串行」无判定；并行安全靠 `st.mu` 串行化写回 | 字段与调度判定全缺 |
+| 可组合 Termination | 无该类型。四个停止条件硬编码分散：leader 轮次（leader.go:207/371，达上限直接 leaderFail 无降级，Q23 仍开放）、修复预算（engine.go:36-37 默认 1，workflow.go:583-596 扣减，engine.go:698 人工 retry 加预算无上限，Q26 仍开放）、唤醒上限（hitl.go:68 `MaxWakeupFires=5`）、StepTimeout/HITL 超时（engine.go:32-33、hitl.go:23-30、hitl.go:119-137） | 类型与 AND/OR 组合全缺 |
+| Store 接口 | squad 核心无 Store 端口；运行状态由引擎直接管文件（runstate.go:52-76 一次写六文件）；`store.FileStore` 只管 roles/blueprints；`store/eventsink.go` 是事件 jsonl 装饰器 | 接口不存在 |
+| platform 收编 | `adapters/sqlite`（包名 platform）是**独立第二套运行系统**：23 张表无 run/step/checkpoint 表（db.go:51-149）；task 队列自有一套 Claim/FinishTask/RecoverOrphans（queue.go:194-348）；`RunInProcess` 绕过 Executor 端口直驱 agent-native（runtime.go:201-229，X6 仍开放）；与 squad 文件态 runs 双真相源并列挂载（cmd/agent-squad/server/server.go:31-41,94-96） | 双系统合一 + schema 扩展 + X6 |
+| 顺带瑕疵（Q1 会踩到） | 并行组 `wg.Wait()` 等全部结束才收口（workflow.go:172）；黑板是快照不是增量（blackboard.go:12-38）；动态调整直接 splice Steps（workflow.go:510-534）——与「图结构不变」的恢复要求冲突；产品侧消费方是 squadadapter 的外层 Run/Resume 循环（`modules/backend/internal/squadadapter/adapter.go:92-117`、entry.go:115-139） | 在设计中显式裁定，见 §3.2 WP1/WP4 |
+
+已修不再返工（R1/R2 已落）：原子写、授权/预算落盘、批准键写入（Q1）、中断步骤挂起分流（Q4 部分）、跨进程锁（Q5）、Respond 幂等（Q7）、WAL（Q19）、事件 seq 续号（Q18）。
+
+### 3.2 工作包分解
+
+**WP1 图模型与 Needs 调度**
+
+- `StepSpec` 增补 `Writes []string`（写集，工件路径）与 `Reads []string`（读集，可空=不声明）；`Needs` 从死字段激活为依赖声明。
+- 编译期（`planAndExecute` 入口）把 Steps 编译成图：节点=步骤，边=Needs；拓扑分层（Kahn），同层可并行。**兼容映射**：无 Needs 的旧蓝图按「相邻 Parallel」规则自动分层（相邻且 Parallel=true 的步骤入同层），行为不变量由现有测试保证。
+- **动态调整裁定**（与恢复语义冲突的解决）：`AllowDynamicAdjustment` 步骤的 splice（workflow.go:510-534）改为「追加节点生成新图版本」——图带 `version`，已完成的 superstep 结果按节点 id+图版本键保存；恢复时要求图版本与检查点一致，不一致则拒绝恢复并提示重新规划（对齐总提案 §2.2「恢复要求图结构不变」）。
+- 调度隔离：同层内**写同一工件（Writes 交集非空）的步骤强制串行**；只读步骤并行。交集判定在分层时做，拒绝或串行化在调度时做（默认串行化 + 事件提示，不拒绝）。
+- 测试：Needs 分层顺序、环检测拒绝、旧蓝图兼容映射等价、写集交集串行化、图版本不一致拒绝恢复。
+
+**WP2 superstep 推进**
+
+- `advance` 重写为 superstep 循环：每 superstep = 「取当前可执行层 → 层内调度（写集串行）→ 层结束做检查点」。leader 循环映射为「leader 节点 + 动态追加成员节点」的图形态（委派=追加，close=终止边），leader.json 的状态并入检查点。
+- `CurrentStepIndex` 死字段删除或改作「当前 superstep 序号」。
+- 并行组 fail-fast 裁定：保持 cancel 传播（现状），superstep 边界统一收口失败，不再 `wg.Wait()` 空等——失败即终止本 superstep 剩余节点。
+- 测试：多蓝图（standard/router/leader）在新循环下现有 engine_test/leader_test 全绿；层边界事件序列断言。
+
+**WP3 attempt id 与幂等**
+
+- 每次执行生成 `AttemptID = runID/stepID/N`（N=Attempts+1），随步骤状态落盘；执行事件、产物、副作用记录都挂 AttemptID。
+- 恢复判定升级：`recoverInterrupted`（engine.go:879-925）从启发式改为「attempt 记录 + 产物校验」——步骤标 running 且其 attempt 无完成记录时，按 HITL 模式分流（现状三分支保留），选择 retry 时新 attempt 执行前校验该步骤已登记副作用（产物文件存在性）并在事件流标注「第 N 次尝试」。
+- 验收硬指标「副作用次数=1」的判定基础：已完成（有完成记录）的 attempt 永不重跑；瞬态重试（MaxTransientStepInvocations=2，workflow.go:260）共享同一 AttemptID 的「子尝试」标记，不计为新 attempt。
+- 测试：杀进程于每个 superstep 边界（见 §3.6）；retry/skip/abort 三分支；瞬态重试不增 AttemptID。
+
+**WP4 Store 端口与三档检查点**
+
+- 新端口 `Store`（squad 包内）：`SaveRun/LoadRun/SaveStep/LoadStep/SaveAttempt/AppendEvent/LoadEvents/SaveCheckpoint/LoadCheckpoint/ListRuns`，以 run（thread）为键。
+- 现状文件态收编为 `FileStore`（runs/ 目录六文件 + pending.json + leader.json 的全部读写走 Store 接口）；检查点三档：`sync`（superstep 边界同步写，默认）、`async`（批量刷盘）、`on_exit`（进程退出时）——档位在 RunOptions 声明，默认 sync。
+- 黑板裁定：Q1 只把黑板快照纳入检查点载荷；「可回放增量」留给 Q2 拓扑（总提案 §2.2 把黑板增量列在拓扑行）。
+- 测试：三档各自的一致性；检查点以 run 为键的隔离；FileStore 与现状文件布局的读取兼容（老 runs 目录可恢复）。
+
+**WP5 SQLiteStore 与 platform 收编**
+
+- `adapters/sqlite` schema 增加 `run / step / attempt / checkpoint / event` 五表；`SQLiteStore` 实现 Store 端口。
+- **收编裁定**（双真相源合一）：platform 的 task 队列不再自行驱动执行——`Claim` 到的任务翻译为 squad run 并交给引擎（Store=SQLiteStore），`RunInProcess` 改走 `Executor` 端口（修 X6）；platform 的 wakeup 表与 squad 的 WaitCondition 合并为一处（保留 squad 语义，platform 表改为投影或下线，迁移期双写只读旧表）。
+- 过渡：platform 现有 23 表中非运行类（workspace/member/issue/skill/autopilot/webhook/chat/project 等）不动；本 WP 只合一「运行」这一层。
+- 测试：同一蓝图分别在 FileStore 与 SQLiteStore 上跑通 conformance（见 §3.6）；孤儿恢复（RecoverOrphans）在合并后语义不变；server 并列挂载改为单引擎。
+
+**WP6 可组合 Termination**
+
+- 新类型 `Termination = And(...)|Or(...)|MaxTurns(n)|RepairBudget(n)|MaxWakeups(n)|Timeout(d)|StepTimeout(d)`；四处硬编码收编为默认组合：`And(MaxLeaderTurns(8), RepairBudget(1), MaxWakeups(5))` + 步骤级 StepTimeout（默认 10min，语义不变：重试共享截止，Q24 维持现状并写进文档）。
+- 顺手关账：leader 达上限的降级收口（Q23：不再裸 leaderFail，走一次收口质检或挂起人工）；人工 retry 加预算设上限（Q26：默认累计不超过初始值的 2 倍，可配）；`SweepExpired` 接入 serve 周期循环（与 SweepWakeups 并列），补 Q6 另一半。
+- 测试：AND/OR 组合矩阵；三个关账项各一例回归。
+
+**WP7 interrupt/resume 统一原语**
+
+- 把「HITL 挂起（pending.json）」与「事件等待（WaitCondition/SweepWakeups）」统一为 `Interrupt{Kind: human|event|expired, Key, Payload}` / `Resume(Key, Response)` 一对原语；pending.json 与 wakeup 成为 interrupt 的两种持久化形态。
+- 对外 API（Respond/Resume/steer）语义不变，内部改走统一原语。
+- 测试：两种 interrupt 的挂起/恢复/过期三态；API 兼容（现有 server_test、engine_test 绿）。
+
+### 3.3 涉及仓与落点汇总
+
+- Agent-Squad：`squad/{workflow.go,engine.go,leader.go,models.go,runstate.go,blackboard.go,hitl.go}`（重写面大）、新 `squad/{graph.go,superstep.go,store.go,termination.go,interrupt.go}`、`adapters/sqlite`（schema+Store）、`store/`（FileStore 归位）、`cmd/agent-squad/server`（挂载合一、SweepExpired 接线）。
+- Backend：`internal/squadadapter`（驱动循环跟上引擎 API；入口/步进循环适配）。
+- Dev：两层 pin。
+
+### 3.4 实施顺序
+
+WP1 图模型 → WP2 superstep（旧行为兼容先绿）→ WP3 attempt id → WP4 Store+检查点 → WP7 统一原语 → WP6 Termination → WP5 SQLite 收编排最后（风险最高，前面 WP 已各自可独立交付）。
+
+### 3.5 风险
+
+- **advance 重写是心脏手术**：WP2 必须先建立「旧蓝图兼容等价」的测试网（现有 engine/leader/recovery/r2_regression 套件就是网底），重写中任何一绿变红即停。
+- 动态调整与图版本：产品端目前依赖动态调整的蓝图（如有）在恢复时会被要求重新规划——行为变化写进 PR 影响段，并把「图版本不一致」的报错做成可操作提示。
+- platform 收编（WP5）触及双系统合一与 X6，体量接近一个小阶段：允许 WP5 在 Q1 任务内再拆子 PR 序列（Store 实现先行、驱动合一随后），但不允许只交一半——「不再单独驱动一套运行」是验收条款。
+- 消费方只有 squadadapter 一处（backend）与 squad CLI/serve 一处，适配面可控。
+
+### 3.6 Q1 验收（对照总提案 §5 Q1 验收逐条）
+
+| 总提案条款 | 机器可核对的验收 |
+|---|---|
+| 在每个 superstep 边界杀进程再恢复，已成功步骤的副作用次数为 1 | 新测试：脚本化蓝图（≥3 个 superstep），逐边界 kill -9 后 Resume，断言每个已完成步骤的产物写入次数=1、事件流无重复完成记录 |
+| 两个写同一工件的步骤不会并行 | 调度测试：写集交集步骤的执行区间不重叠（事件时间戳断言） |
+| 文件 run 与 SQLite 不再各记一份步骤状态 | conformance 套件在 FileStore 与 SQLiteStore 双实现上通过；server 单引擎挂载；platform 侧无独立 run 状态表残留（schema 断言） |
+
+## 4. I1 命令化识别
+
+总提案原文（§5 I1）：「命令列表与 ActionRef。中文匹配的词界或最短词长。同分时可按 priority 决胜。Catalog 白名单与 top-k。Backend 唯一 Router 消费 ActionRef。」验收点名审计 I1、I2、I3、I5 有回归（I1/I2 在当前 pin 已修并有测试，I3/I5 开放，见下）。
+
+### 4.1 现状与 gap
+
+| 需求项 | 现状（证据） | gap |
+|---|---|---|
+| 命令列表 | **不存在**。`Result = {Input, Branch, Top *Candidate, Candidates, SnapshotRevision}`（`deps/agent-intent/intent/result.go:44-50`），输出是单 Top 意图；`ActionRef`/`Start`/`SetSlot` 全仓零代码命中 | 命令类型、序列化、校验全缺 |
+| ActionRef 统一 | **四种动作键并存**：(a) `IntentSpec.Handler`（spec.go:81，squadintent Runner 消费）；(b) `Metadata["blueprint"]`（adapters/intent/gate.go:123-131 → engine.go:228-237）；(c) `CommandSpec.ID`（agent-command，backend server.go:653-654 把意图 ID 当命令 ID）；(d) `WorkflowDef.IntentID`（core plugin.go:60，workflow/registry.go:40-42 索引） | 统一表示与迁移映射 |
+| Backend 唯一 Router | **不存在**。消费分散三处：chat 路由内联 if-else（`internal/server/server.go:647-660`，命令优先于工作流写死）、HITL 自由输入转轨（`internal/runmgr/runmgr.go:1203-1248`）、装配（`internal/app/app.go:300-301,316,381`）。squad 的蓝图意图链 backend **完全没接**（squadadapter/entry.go:98-110 不设 IntentGate/IntentCatalog/IntentRunner；全 backend grep `squadintent` 零命中） | Router 组件与优先级裁定 |
+| 中文词界/最短词长（I3） | 纯子串 `strings.Contains`（registry.go:142/147/154）；无词界设施、无最短词长告警（grep 零命中）；NFKC 已落地（fold.go:11-28）但**两个宿主都没开**（backend intentgate gate.go:57 只设 TopN；squadintent gate.go:37-44 只设 Guard/Protected 域）；语料中文负例只有一条靠 excludes_any 硬回避（testdata/corpus.json 第 6 行 + specs/base.json:10） | 词界设施、lint 告警、负例语料、宿主开 NFKC |
+| 同分 priority 决胜（I5） | `Priority` 字段已在（spec.go:74）且是排序第二键（registry.go:327-335、recognizer.go:172-183）；但裁决要求分差 ≥ margin（recognizer.go:92），`AmbiguityMargin <= 0` 强制回 0.1（registry.go:61-63）——**同分恒 ambiguous，priority 不参与决胜** | 裁决逻辑调整 |
+| Catalog 白名单与 top-k | Metadata 白名单已有（fold.go:61-64，只放 blueprint/guidance 两键）；但 `CatalogSpec.Handler` 仍进 JSON 视图（catalog.go:20-30）；目录全量输出无 top-k、无相关度（catalog.go:34-62） | top-k 与相关度参数；Handler 是否进目录的裁定 |
+| eval | `intentctl eval` 单轮（cmd/intentctl/main.go:229-292，recognizer 以 nil expectation/classifier 构建于 main.go:254）；语料 10 条（testdata/corpus.json）；输出只有 PASS/FAIL 计数（main.go:285-290） | 多轮夹具格式与逐轮命令期望（precision/recall 指标输出属 I2，I1 先扩格式） |
+| 命令层前置概念 | 否定只认 excludes_any（recognizer.go:66 注释明说「不要写入」交给命令层 Cancel——命令层尚不存在，审计 I12）；ExpectationProvider 接口在（expectation.go:7-19）但宿主侧零实现；L2 Classifier 同理（classifier.go:9-15，全部 NewRecognizer 传 nil） | I1 只需命令层与宿主编排；L2 实现、语义端口在 I2 |
+
+另外注意：overlay 解析 `DisallowUnknownFields`（loader.go:21-24、51）——spec 加字段不做显式注册会硬失败旧配置；backend 插件读的是**裸 spec 数组**（internal/plugins/host.go:216-222），不是 `{intents, disable}` overlayDoc——两种载体的兼容都要照顾。
+
+### 4.2 工作包分解
+
+**WP1 命令模型（库侧核心）**
+
+- 新类型：`Command` 联合 `{Kind, ...}`——`Start{ActionRef, Slots}` / `SetSlot{Name, Value}` / `ChangeSlot{Name, Value}` / `Cancel{Scope}` / `Clarify{Question, Missing}` / `Chitchat{}` / `Handoff{Target}`；`ActionRef{Kind: command|workflow|blueprint|handler, ID string}`。
+- `Result` 增加 `Commands []Command`（Branch/Top 保留作诊断与兼容，逐步退役由 Router 封装）；从候选到命令的展开规则：Top 命中 → Start（带 ActionRef 推导）；槽位缺失 → Clarify（或 ExpectationProvider 命中时 SetSlot/ChangeSlot）；多候选 → Clarify 消歧或 Ambiguous 保持（见 WP4/WP5 裁决）；否定/取消语义 → Cancel（命令层首次承认否定，收编 recognizer.go:66 的注释承诺）。
+- 命令的校验与现有候选校验同级（ID 集合、槽位作用域）；序列化进 schema 包并给 JSON 样例（对齐 D1 的「三库发布 JSON Schema 样例」做法）。
+- 测试：每种命令的展开路径；校验拒绝；round-trip。
+
+**WP2 ActionRef 推导与四种动作键迁移**
+
+- spec 增加显式字段承载 ActionRef（`action: {kind, id}`），`DisallowUnknownFields` 下注册；推导规则（兼容期）：`action` 缺省时按旧键推导——`Handler` → `{handler, <值>}`、`Metadata["blueprint"]` → `{blueprint, <值>}`、命中 backend 命令总线 → `{command, <ID>}`、命中 workflow 索引 → `{workflow, <IntentID>}`。
+- backend 插件装载（host.go:216-222 裸数组）与库 overlay 两种载体都接受新字段；旧字段在 I1 不删除（退役留给 I2 之后的发版任务）。
+- 测试：四种旧键的推导等价于现状路由结果（对照 server.go:647-660 现行为刻画测试先行）；新字段优先于旧键。
+
+**WP3 Backend 唯一 Router**
+
+- 新组件（建议 `internal/route`，或收进 `internal/server` 的独立文件）：输入 = 命令列表 + 会话状态，输出 = 路由决策（command 分发 / workflow 启动 / squad 入口 / 普通回合 / 澄清回问）。
+- 收编两处现有消费：server.go:647-660 的内联 if-else 与 runmgr.go:1203-1248 的 HITL 自由输入转轨，统一改调 Router；slash 命令（server.go:741-758）保持旁路不过在优先级文档里写明。
+- **优先级明文**（提案 §6 要求 I1 写明）：`command > workflow > blueprint > 普通回合`；`PromptTrigger`（技能触发）与 Intent 同命中时的裁定：**技能触发是提示词装配、不参与路由决胜；若 Intent 产出 Start/SetSlot 类命令则路由优先，纯提示词命中不产生命令**——写进 Router 文档与测试。
+- squad 蓝图链（`{blueprint, key}`）经 ActionRef 到达 Router 后，Router 调 squad 入口；**backend 接入 squadintent 适配器（entry.go:98-110 的缺口）在本 WP 一并补上**——这是「blueprint 经 ActionRef 到 Router」验收的必要条件，范围可控（装配 + 映射，不改 squad 库）。
+- 测试：命令优先于工作流（现有 `TestCommandBusBeatsWorkflow` 迁移）、workflow 经 ActionRef 启动、blueprint 经 ActionRef 进 squad 入口、HITL 自由输入转轨走同一路由、fallback 进普通回合。
+
+**WP4 中文词界与最短词长（I3）**
+
+- `MatchSpec` 增加 `boundary`（词界模式：CJK 按「非汉字或首尾」为界，拉丁按词字符边界）与 `min_len`（词条最短长度，低于则 lint 告警）——二选一还是并存由实施期原型定，但 lint 告警（`intentctl lint`）必须覆盖「短词条 + 无词界」组合。
+- 两宿主开启 NFKC：backend `intentgate.Rebuild`（gate.go:57）与 squadintent（gate.go:37-44）的 Options 显式开 `NFKC:true`，并补开启前后对照测试。
+- 语料补负例：中文子串误命中系列（如「配置」误中「配置项」、「写入」误中「不要写入」的否定场景交给 Cancel 的正例对照）。
+- 测试：词界开/关矩阵、最短词长告警、新负例全过、既有 10 条语料不回归。
+
+**WP5 同分 priority 决胜（I5）**
+
+- 裁决调整：前两名置信度同分（差 < margin）时，若 `Priority` 不同则高优先者判 `matched`；priority 也相同才 ambiguous。`AmbiguityMargin` 语义不变（仍防分数过近误判），margin 强制下限 0.1 保留。
+- 测试：同分高 priority 命中、同分同 priority 标歧、margin 边界三例；既有漏斗测试不回归。
+
+**WP6 eval 格式扩展**
+
+- 语料格式 v2：用例带 `turns: [{input, expect: {commands: [...]}}]`，逐轮期望命令列表；`intentctl eval` 读 v2 时构建 ExpectationProvider 夹具实现（库内给测试用 Provider），逐轮比对命令序列；v1 单轮格式兼容读取并自动映射为单 turn。
+- 指标输出在本阶段只加「逐轮命令匹配率」明细（precision/recall 的正式定义与输出属 I2，不在 I1 提前承诺）。
+- 测试：v2 多轮夹具端到端（含 SetSlot+Start 组合用例——验收条款的载体）、v1 兼容、误期望 FAIL。
+
+### 4.3 涉及仓与落点汇总
+
+- Agent-Intent：`intent/{result.go,recognizer.go,registry.go,spec.go,loader.go,catalog.go}`、新 `intent/command.go`、`schema/`、`cmd/intentctl`、`testdata/`。
+- Backend：`internal/server/server.go`、`internal/server/`（新 Router）、`internal/intentgate/`（Recognize 返回命令、NFKC 开启）、`internal/runmgr/runmgr.go`（HITL 转轨改调 Router）、`internal/squadadapter/entry.go`（接 squadintent）、`internal/plugins/host.go`（spec 新字段）。
+- Agent-Squad：`adapters/intent` 只在映射 ActionRef 时动（blueprint 键推导），核心不动。
+- Dev：两层 pin。
+
+### 4.4 实施顺序
+
+WP1 命令模型 → WP2 ActionRef 迁移（刻画测试先行）→ WP5 决胜 + WP4 词界（库内独立，可并行）→ WP3 Router（依赖 WP1/WP2）→ WP6 eval（收尾，验收载体）。
+
+### 4.5 风险
+
+- **路由行为变化面**：Router 收编两处消费 + squad 蓝图链接入，是产品可见行为。对策：WP2 的刻画测试先把现路由行为钉死，Router 切换后逐条等价；蓝图链接入属新增能力，单独一组测试，不改动有路由。
+- overlay 严格解析：spec 新字段必须同步注册进 loader 与 backend 裸数组装载两处，漏一边即硬失败——测试覆盖两种载体。
+- NFKC 默认开启是行为变化：只动两个宿主的显式配置，库默认不变（库保持 fail-closed 哲学，宿主显式选择）。
+- 命令列表与「单 Top」并存期，`Result.Top` 的消费方（squadintent gate 等）保持可用；退役由后续发版任务评估，不在 I1。
+
+### 4.6 I1 验收（对照总提案 §5 I1 验收逐条）
+
+| 总提案条款 | 机器可核对的验收 |
+|---|---|
+| 审计 I1、I2、I3、I5 有回归 | I1（分类器篡改拒绝，recognizer_test.go:188/238/269 现存）与 I2（作用域校验器，slots_catalog_test.go:70 现存）保持绿；I3 新增词界/负例测试；I5 新增决胜测试——四个测试名写进任务卡 |
+| 一条用户话可以产出 SetSlot 加 Start | eval v2 多轮夹具含该用例并通过 |
+| 命令 id、工作流 IntentID、小队 blueprint 都通过 ActionRef 到达 Router | Router 测试三条各一；插件清单字段名不变的 diff 断言（装载测试比对字段名清单） |
+| 插件清单不改字段名 | 插件装载兼容测试：现有插件 intents/workflows 清单零修改装载通过 |
+
+## 5. 三任务之外的说明
+
+- N2/Q2/I2 及更后的阶段不在本文范围；本文的 WP 划分假定 N1/Q1/I1 全部合入后才启动它们。
+- 三任务的验收都依赖「脚本化模型 + 库内夹具」，不依赖真实模型密钥；真实任务 A/B（总提案 E 节「少量真实任务加人工复核」）在各阶段验收时由所有者安排。
+- 本文档本身不修任何代码；如评审要求改设计，在本文档上修订后再启动对应任务。
+
+## 6. 验收（本文）
+
+- 三个阶段的实施方案各自满足：工作包可独立派生任务卡、验收条款可机器核对、与总提案逐条映射（§2.6 / §3.6 / §4.6 的表）。
+- 现状陈述均有 file:line 证据（撰写日 pin 见 §1.1）；评审重放 = 按表中证据抽查。
+- 三任务协调规则（§1.2）与 AGENTS.md 分支层级一致。
+
+## 7. 实施状态回填与范围差异（2026-10-08）
+
+本节回填三个阶段的实施结果与本文原设计的范围差异，来源为已归档任务卡（SELF 声明）与
+Dev main 的合入记录（2026-10-08 经 `git log --merges` 核对，#230/#231/#234/#235/#237/#240
+均在 main）。本节不重放各任务测试，不把闭卡文案升级为重新验收；「完成」指卡内验收条款
+声明 PASS 且 PR 已合入。每个转出/待做项标注依据、归属与适用版本，供 N2/Q3 之后的工作
+与 RDM 依赖判断使用。
+
+### 7.1 N1 内核 harness
+
+已合入：Dev #230（merge 42f5ac4）/ #231（merge b6974fa）；组件链 Agent-Native
+#17–#20、Agent-Squad #16–#18、Backend #69–#73（卡内记录，CI 在各 merge 前 success，GATE）。
+卡内验收两条（A/B 对照、插件 AgentSpec 校验）声明 PASS（SELF）。
+
+与本文 §2.2 的范围差异（依据：N1 卡增量三/四及「影响与剩余项」）：
+
+| 项 | 本文原设计 | 实施结果 | 状态 | 归属/载体 |
+|---|---|---|---|---|
+| WP6b 小队成员级 deliverable Stop/提醒拉齐 | §2.2 WP6「三条路径注入同一套…」的小队成员级部分 | 任务内裁定转出：需 adapters 成员级执行信号（工件产出追踪+工具轮计数） | 待做；原建议载体 Q1 未承接（Q1 卡剩余项无此项，Q2/Q3 亦未涉及） | owner weichen；载体待定 |
+| WP6c 直连/子代理改经 adapters 消费 | §2.2 WP6「不再裸调 nruntime.Run」 | 转出：需 exec.Request 表达 History/工件追踪/证据回收；ContractBackend+conformance 部分已落地（卡增量四②） | 待做；未承接 | owner weichen；载体待定 |
+| prompts.SubagentSpec 迁移 | §2.2 WP1「迁移为读 AgentSpec 文件」 | 裁定不迁移：与 agent-*.md 两套格式并存，新字段暂无消费者（卡增量三） | 有意搁置 | owner weichen；有消费者时再启动 |
+| runmgr 派生路径 Start/Stop | §2.2 WP2 发射点补齐的产品侧外延 | 裁定不覆盖：非工具调用、无总线上下文（卡增量三） | 有意搁置 | 同上 |
+| AllowStore 持久化 | §2.2 WP3「持久化形态留给 N3」 | N3 再转出（N3 卡「影响与剩余项」：memory 回合后抽取接线与 AllowStore 持久化转后续） | 待做；已经 N3 二次转出 | 见 N3 卡记录 |
+
+### 7.2 Q1 图执行
+
+已合入：Dev #237（merge 3bf2441）/ #240（merge ba36d47）；组件链 Agent-Squad #23–#26、
+Backend #79–#82。卡内验收三条声明 PASS（SELF）。
+
+与本文 §3 的范围差异（依据：Q1 卡增量四及「影响与剩余项」；Q2/Q3 卡对照）：
+
+| 项 | 本文原设计 | 实施结果 | 状态 | 归属/载体 |
+|---|---|---|---|---|
+| platform task 队列翻译成 squad run | §3.2 WP5 收编裁定「Claim 到的任务翻译为 squad run 并交给引擎」 | Store 层合一已做（SQLiteStore、X6 改走 Executor 端口、serve 单库挂载）；task 队列本身的翻译转出为「更深的产品合一，Q 系列/EXT 范畴」；Q2 卡明确记非目标（「平台队列桥接…（后续）」），Q3 未涉及 | 待做；Q 系列已收口仍未承接 | owner weichen；按 RDM 总案 §3.3 走 EXT 申请或后续产品任务 |
+| 黑板可回放增量与 Reads 读集 | §3.2 WP4「留给 Q2 拓扑」 | Q1 卡转出至 Q2；Q2 卡通篇无黑板/读集内容（实施为拓扑注册表等） | 待做；Q2 未承接 | owner weichen；载体待定 |
+| leader 模式 SQLite 端到端 | §3.2 WP2「leader.json 的状态并入检查点」 | Store 已实现 SaveLeader/LoadLeader；leader 模式回归在 FileStore 上证明（卡「影响与剩余项」） | 待做（回归补证） | owner weichen |
+| 验收表「schema 断言」 | §3.6 第三条「platform 侧无独立 run 状态表残留（schema 断言）」 | 卡内验证记录为 TestSQLiteStoreRoundTrip、TestEngineRunsOnSQLiteStore 与单库挂载；未见 schema 断言测试记录 | 证据口径差异；补断言或由负责人裁定豁免 | owner weichen |
+| 拓扑库 | Q1 卡转出至 Q2 | Q2 已落地（Dev #250/#251） | 完成（在 Q2） | — |
+
+### 7.3 I1 命令化识别
+
+已合入：Dev #234（merge 1f7217f）/ #235（merge eafe1e1）；组件链 Agent-Intent #6–#8、
+Agent-Squad #19–#22、Agent-Native #21/#22、Backend #74–#78。卡内验收四条声明 PASS（SELF）。
+
+与本文 §4.2 的范围差异（依据：I1 卡「影响与剩余项」；代码核对 command.go:18-25/78-84）：
+
+| 项 | 本文原设计 | 实施结果 | 状态 | 归属/载体 |
+|---|---|---|---|---|
+| blueprint per-run entry 覆盖 | §4.2 WP3 squad 蓝图链接入的延伸 | 裁定为独立设计项；blueprint 决策已达 Router | 待做 | owner weichen |
+| ambiguous→Clarify 产品化 | §4.2 WP1 消歧路径 | Router v1 保持普通回合；产品化需澄清 UI/HITL | 待做 | owner weichen |
+| SetSlot/Cancel/Handoff 的产出与消费 | §4.2 WP1「否定/取消语义 → Cancel（收编 recognizer.go:66 注释承诺）」与命令展开 | Command 类型已定义且有意裁定「规则漏斗不产出 Cancel/Handoff」（command.go:78-84 注释：留给声明 action 的意图与语义层）；运行时消费（会话槽位状态机）未做 | 待做；原记「I2 附近」，I2 已收口未承接（I2 卡同项转出） | owner weichen；无阶段载体，需排期 |
+
+### 7.4 对后续依赖的提示
+
+- N2/N3/Q2/Q3/I2 均已各自合入（见[规划索引](INDEX.md)阶段导航），但上表转出项无一被
+  这些阶段承接；引用「N1/Q1/I1 已完成」作依赖判断时，须扣除上表待做项。
+- RDM MS3 依赖的 Q1 图执行与 Q3 编排收敛不受上表影响；受影响的是「platform task 队列
+  合一」与「SetSlot/Cancel/Handoff 消费」两条产品化路径。
+- 本节维护规则与索引一致：状态再次变化时先更新本节并同步索引导航。

docs/proposals/2026-10-07-agent-stack-n2-plan.md

@@ -0,0 +1,148 @@
+# 方案：N2 上下文、协议与工具——现状核验与增量实施
+
+日期：2026-10-07。上游：[2026-10-02-agent-stack-completion.md](2026-10-02-agent-stack-completion.md)「N2 上下文、协议与工具」节（范围与三条验收的唯一权威）、[2026-10-02-agent-stack-audit.md](../records/2026-10-02-agent-stack-audit.md)（审计项逐条对当前代码复核后引用）。
+
+基线 pin：agent-native `ead690b`、backend `68addfd`、agent-squad `029edc0`、agent-intent `343b1e6`（均为已合入 main）。本文所有 file:line 以这些 SHA 为准；实施时先复核再引用（与 N1/Q1/I1 同一纪律：审计与本文都不是证据，当前代码才是）。
+
+依赖状态：N1/Q1/I1/I2 全部闭卡（任务卡归档）。总提案依赖序「N1/Q1/I1 → N2/Q2/I2；N3 在 N2 之后」满足，N2 开工。
+
+## 一、现状核验（六路侦察 + 关键处亲验）
+
+### 1. 上下文与压缩
+
+库层三件已就位且配对安全：
+
+- **会话压缩**：`runtime/session/compact.go:78-146`；`alignToolTail`（compact.go:148-154）回退 tailStart 至工具结果组之外，头段整体换摘要，不留孤立调用。回归：`TestR2CompactKeepsToolPair`、`TestCompactLeavesNoOrphanToolCall`（runtime/session/r2_regression_test.go:12-46,105-162）。
+- **微压缩**：`runtime/session/microcompact.go:44-70` 只改写旧工具结果正文为转录指针占位，不增删消息、不动配对（loop.go:759-776 接入）。
+- **适配层自动压缩**：`adapters/native/backend.go:95-103,412-470`。
+- **提醒**：`runtime/reminders/reminders.go:70-97` 并入最后一条消息，不新建 user 消息（审计 N22 已修）。
+
+仍开放：
+
+- **产品侧裁切破坏配对（验收②的真缺口）**：`modules/backend/internal/ctxasm/finish.go:200-242` `trimOldest→oldestDrop` 逐条丢弃「系统前缀后第一条」，无工具配对意识——丢掉带 tool_calls 的 assistant 会留下孤立结果，丢掉结果会留下悬空调用。渲染阶段（ctxasm.go:174-277）本是配对安全的，裁切在其后发生，把安全性破坏掉。
+- **旧工具结果没有落盘路径**：微压缩占位指向转录调用 ID（microcompact.go:58-68），不是文件路径；总提案 N2 行「运行内把旧工具结果换成路径」（ZCode compact 模式）未实现。
+- **缓存友好无契约**：全仓无 `cache_control`；系统文本+工具清单的稳定性是事实性而非设计（registry.go:136-148 注册序、loop.go:380-401 拼接），无测试钉住；backend 有 PrefixHash 观测（finish.go:252-277）但无稳定契约测试。
+- **`alignToolTail` 无直接单测**（仅经 Store.Compact 端到端覆盖，边界形态靠偶然）。
+- filestate 读后才能写只在 agent-native 路径（backend.go:210）；产品直连路径不过 `WorkspaceToolsTracked`（llm_direct.go:191-193）——划归 Q3 收敛范畴（见边界节）。
+
+### 2. Anthropic 原生协议（审计 N4 仍开放）
+
+- 线上 Client 只讲 OpenAI chat：`runtime/llm/client.go:14,71,76` 固定 POST `…/chat/completions` + Bearer。
+- `Protocol` 枚举五方言（providers.go:123-129），`ClientFor` 只实现 `openai-chat`，其余 fail-closed（providers.go:201-208）。审计 N4 的「选了不能用」已被缓解：anthropic/google 预设改指 OpenAI 兼容端点（providers.go:143,146）——但**原生方言不存在**。
+- 离线组包 `anthropicMessages`（providers.go:320-352）丢 tool_use/tool_result、不挂 tools（providers.go:270-289）；`Message`（types.go:48-57）无 thinking/signature 存储，签名块无法往返。
+- 无录制 HTTP 夹具机制（无 testdata/；现有测试全是内联 httptest 脚本）。
+- 审计 N4 验证结论：**部分缓解、主体仍开放**。
+
+### 3. 延迟工具 / tool_search / 代码编排（基座已在，剩收口）
+
+已就位（agent-native）：`ExposureDeferred` 两级暴露（runtime/tools/registry.go:56-73）、`tool_search`/`call_tool` 元工具（deferred.go:13-68）、激活持久化（deferred.go:94-128 → `.agentx/activated-tools.json`）、MCP 延迟连接 `StartBackground`（manager.go:124-135）与 >8 工具自动 deferred（manager.go:197-207）、代码编排 `run_tool_script`（code_tool.go:14；codeorch/host.go 进程外执行、中间结果不进上下文、50 次上限、禁名单）。backend 双路径接线：`runtime.codeOrchestration` 默认关（settings.go:95；app.go:241 agent-native 路径；codeorch_tool.go:15-78 + runmgr.go:348-355 直连路径）。
+
+仍开放/风险：
+
+- 激活恢复只记名字，激活工具永不进 `Decls()`（deferred.go:100 注释为有意设计，call_tool 间接层即机制）——**保持，不扩**。
+- 代码编排在两处各有一份实现（库 code_tool.go vs 产品 codeorch_tool.go），开关两点判定，可漂移；N2 只做「同一语义」契约测试，不做合并（合并属 Q3 退役直连路径时自然发生）。
+- 审计 N30（native.Options 单件）仍在；本阶段不做大重构，只在新端口上不再加字段。
+
+### 4. MCP（审计 N3/N18/N19 已修；2026-07-28 未对齐）
+
+- **验收③已满足**：stdio 单读循环按 id 分发（stdio.go:192-231），取消只 dropPending；回归 `TestStdioSlowCancelThenEcho`（mcp_test.go:78-105）断言 `Readers()==1`。审计 N3 关闭；N18（重连一次，manager.go:243-250）、N19（HTTP 会话 DELETE，http.go:95-119）同闭。
+- **未对齐 2026-07-28**：`ProtocolVersion="2024-11-05"`（protocol.go:16）且服务端协商版本从不检查；`callToolResult` 无 `resultType`（protocol.go:138-141）；`input_required` 只是成功结果里的内容块特例（ask.go:20-27），应答直接当终态返回（manager.go:254-264），不**重试原请求**；ask 端口（ask.go:7-18）接的是自由输入而非审批面；`tasks/get|update|cancel` 客户端面无；工具 schema 透传无 2020-12 声明（manager.go:174-177 合成默认 schema 时也未声明）。
+
+### 5. skills 校验（开放规范未对齐）
+
+- 现校验仅：目录名字符集 `[a-zA-Z0-9_-]`、64KiB 截断、描述 200 字截断、每根 100 个（runtime/skills/skills.go:22-26,140-186）。frontmatter 只按行前缀扫 `description:`（有意不引入 YAML 依赖，skills.go:4）；`name:` 被忽略（目录名权威）；未知键静默通过；不合规范式静默跳过（skills.go:79-81）。
+- 开放规范差距：name 必填且须 kebab-case 并与目录同名、description 必填（规范上限 1024）、已知键白名单（license/compatibility/metadata/allowed-tools）、字段形态校验、**错误上浮**而非静默。
+- backend 侧零校验：种子（internal/skills/skills.go:52-127）与插件技能落盘（plugins/host_v2.go:56-74）都不验；内置 recipes 只有 `description:`，缺 `name:`（dogfood 欠账）。
+
+### 6. 子代理后台/转录/恢复
+
+- **后台机制产品层已有**：`spawnBackground`（runmgr.go:1447-1474，上限 3、detached ctx、完成入 notice 队列、空闲合并投递）；模型经 delegate 工具 `background:true` 触发（llm_direct.go:459-492）。但 `AgentSpec.Background`（agentspec.go:28,156-161）**除测试外无消费者**；notice 队列是内存 map（runmgr.go:1487-1494），重启即丢。
+- **无独立转录**：子 run 共享父会话 messages 表、仅 `run_id` 分区（runmgr.go:1352,1426；store/messages.go:101-116 排除）；SubLLMRunner 直连 `nruntime.Run`（sub_loop.go:98），不建 workDir、不写 .agentx。
+- **零恢复**：`ReconcileInterrupted`（runmgr.go:1606-1634）对子 run 只 seal 成 interrupted，无续跑/重跑路径；恢复测试只覆盖会话 run。
+- `WorktreeIsolation/OutputSchema`（agentspec.go:29-30）declared-only——本阶段保持，记为边界。
+
+### 7. 审计 N2（并行工具事件竞争）——已修，仅引用
+
+`serializeHostCallbacks`（loop.go:468-480，Run 入口 :170 调用）用一把锁串行 OnEvent/BeforeTool/AfterTool；`GOWORK=off go test -race ./runtime/` 全绿（本方案亲验，2026-10-07）。不再安排工作，作为既有证据引用。
+
+## 二、工作包划分
+
+| WP | 内容 | 主要仓 | 对应验收 |
+|---|---|---|---|
+| WP1 | 上下文配对收口 + 工具结果落盘 + 前缀稳定契约 | backend + agent-native | ② |
+| WP2 | Anthropic 原生客户端 + 录制夹具端到端 | agent-native | ① |
+| WP3 | MCP 2026-07-28 对齐（版本协商 / resultType / input_required 重试 / approval 接线） | agent-native + backend | ③（回归引用） |
+| WP4 | skills 开放规范校验 + dogfood + 插件路径复用 | agent-native + backend | — |
+| WP5 | 子代理：Background 消费、独立转录、恢复与通知持久化 | backend（+agent-native 小面） | — |
+| WP6 | 装配收口 + A/B 验收证据 + 级联闭链 | backend + Dev | ①②③ 总验 |
+
+依赖：WP1 先行（验收②、风险最小、产品直接受益）；WP2 与 WP3/WP4 可并行；WP5 独立；WP6 收全部。每个 WP 走「库 PR → backend PR → 级联 → Dev gitlink PR」既有链式，逐 WP 合入，不做长分支。
+
+### WP1 上下文配对收口
+
+1. **ctxasm 裁切配对对齐**：`oldestDrop` 改为工具组对齐——候选索引落在 tool 结果组内或带 tool_calls 的 assistant 上时，整组同退（对齐 `alignToolTail` 语义，但方向是丢弃侧）。测试：构造带多轮工具调用的装配输出，裁切后断言（a）无孤立 tool_call（每个 call 有结果）、（b）无悬空结果（每个结果有 call）、（c）`Report.Truncations` 仍记录。**这是验收② 的机器证据。**
+2. **旧工具结果落盘**：微压缩清理时把旧结果写入 `<workDir>/.agentx/results/<toolCallID>.txt`，占位改为路径指引（「完整内容见 <路径>」）；保留 keepLastN 语义。库内实现 + 单测（写盘、占位、配对不变、文件可被 fs 工具读回）。
+3. **前缀稳定契约测试**：钉住系统文本与 `Decls()` 顺序在同一注册序列下逐字节确定（含 tool_search/call_tool 注入位置）；backend 侧钉 `PrefixHash` 在同输入下不变。只测不改行为。
+4. **`alignToolTail` 直接单测**：tail 恰落多调用 assistant、keepLastN 大于工具组、全为 tool 角色三种边界。
+
+### WP2 Anthropic 原生客户端
+
+1. **客户端**：`ClientFor` 增 `ProtocolAnthropic` 分支——POST `{base}/messages`，头 `x-api-key` + `anthropic-version`，SSE 解析 Anthropic 事件族（`message_start`/`content_block_start|delta|stop`/`message_delta`；`text_delta`/`input_json_delta`/`thinking_delta`/`signature_delta`），映射到既有 `Event` 类型；stop_reason `tool_use`→StopToolCalls、`end_turn`→StopEnd。
+2. **消息形态**：`anthropicMessages` 重写——assistant `tool_use` 块（id/name/input）、user `tool_result` 块（tool_use_id/content）、`tools` 数组（name/description/input_schema）；`Message` 增 thinking 块与 `signature`（含 `redacted_thinking`）存储与往返；system 与 tools 挂 `cache_control`（原生路径上的缓存友好，呼应 WP1-3）。
+3. **预设**：`anthropic` 预设切到 `ProtocolAnthropic`（用户预期即原生）；compat shim 经 `models.json` 自定义仍可配。`BuildBody` 的 Anthropic 分支与线上客户端统一（同一组包函数，消灭「离线/线上两张皮」的 N4 根因）。
+4. **录制夹具（验收①）**：新增 `runtime/llm/testdata/anthropic/` 录制字节流（非真实密钥、非线上依赖）：一轮完整工具调用——带 tools 请求 → SSE 含 `tool_use` → `tool_result` 请求 → 终文本。端到端断言：`ClientFor(Lookup("anthropic"))` 走通全程；第二次请求体中 thinking 块带原签名（签名往返）；请求头含 `anthropic-version`。
+5. 审计 N4 随本 WP 关闭（预设即真实客户端；未实现协议仍不出现在预设）。
+
+### WP3 MCP 2026-07-28 对齐
+
+1. **版本协商**：通告 `2026-07-28`；读取服务端 `initializeResult.protocolVersion`，按协商版本分流（低版本回落现行行为，不留半新半旧）。
+2. **resultType**：`callToolResult` 增判别字段；`input_required` 升格为协议级结果类型——经 ask 端口取得应答后**用原参数重试 `tools/call`**（不再把应答当终态内容返回）；重试次数有界（防循环）。
+3. **approval 接线**：ask 端口在 backend 接到审批/确认卡面（复用 N1 的 HITL 卡与 PermissionAsk 通路），自由输入与批准两类语义分清。
+4. **tasks 客户端面**：`Client` 增 `tasks/get|update|cancel` 方法 + 双传输实现 + 假服务器用例；产品侧映射只做最小集（run 中断时对进行中的 MCP task 发 `tasks/cancel`），完整后台任务映射记录为后续项（N3 持久化阶段）。
+5. **schema 2020-12**：合成默认 schema 时声明 `$schema: 2020-12`；透传保持不透明（不重写方言，注释记为有意）。
+6. 回归保持：`TestStdioSlowCancelThenEcho`（验收③）全程原样通过，作为 WP3 不得破坏的既有证据。
+
+### WP4 skills 开放规范校验
+
+1. **严格子集解析器**：坚持不引入 YAML 依赖（skills.go:4 的既有约束），手写支持规范字段形态的子集（标量、`metadata` 字符串映射、`allowed-tools` 空格分隔列表）；形态不合法即错误，不猜测。
+2. **校验规则**：`name` 必填 + kebab-case（小写、1–64、无连续/首尾连字符）+ 与目录同名；`description` 必填、≤1024（上限对齐规范，替换现 200 截断）；已知键白名单 `{name,description,license,compatibility,metadata,allowed-tools}`，未知键带字段定位拒绝；`compatibility` ≤500；不合规**错误上浮**（List 返回逐技能诊断；load_skill/declared-skill fail-closed 带错误正文，替换静默跳过）。
+3. **dogfood**：内置 recipes 全部补 `name:`；不合规目录改名随本 WP 同 PR（不另起 PR）。
+4. **backend 复用**：插件技能落盘（host_v2.go:56-74）过同一校验器，失败带字段定位拒绝装载（与 N1 插件 AgentSpec 拒禁键同款形态）；种子路径在校验失败时拒写并日志上浮。
+
+### WP5 子代理后台/转录/恢复
+
+1. **Background 消费**：`AgentSpec.Background=true` 时 factory 选择后台派生（squadadapter.SubagentFactory 与 delegate 工具同样语义：声明驱动，不再只靠模型参数）。`WorktreeIsolation/OutputSchema` 保持 declared-only，文档记为边界。
+2. **独立转录**：每个子 run 落独立转录文件（`<data>/workspaces/<owner>/<conv>/subagents/<runID>/transcript.jsonl`，由 finishChild 从 messages 表按 run_id 导出 + 后续增量直写）；父会话分区保持系统记录不变。SubLLMRunner 迁 exec.Backend 属 Q3，本 WP 不做（边界记明）。
+3. **恢复**：`ReconcileInterrupted` 对子 run 不再只 seal——有存储请求与转录的子 run 标记 resumable，父会话下一轮空闲时提示/自动续跑（续跑=以原请求+转录起新子 run，接续语义写清）；恢复测试补子代理场景。
+4. **通知持久化**：notice 队列落盘（SQLite 表或 JSONL，随 runmgr 既有存储面），重启后重投未投递的后台完成通知；内存 map 只做热缓存。
+
+### WP6 装配收口与 A/B 验收
+
+1. app 装配复核：新端口/开关全部有默认关或行为不变证明；需要设置项的（如 Anthropic 原生端点 key 环境约定）进 settings Schema。
+2. A/B 验收证据（写任务卡）：① anthropic 录制夹具端到端（WP2-4）；② 配对断言测试 + 既有 `TestCompactLeavesNoOrphanToolCall` 原样通过；③ `TestStdioSlowCancelThenEcho` 原样通过。三条全部 GATE（各仓 CI）+ Dev `make test` 收据。
+3. 级联 pin 收齐、Dev gitlink PR、任务卡闭链。
+
+## 三、验收总表
+
+| 总提案验收 | 机器证据 | 所在 WP | 现状 |
+|---|---|---|---|
+| ① 选 anthropic 预设能完成一轮工具调用（录制 HTTP 夹具，不要求真实密钥） | `runtime/llm/testdata/anthropic/*` 夹具 + `TestAnthropicPresetToolRound`（端到端：tools 请求→tool_use→tool_result→终文本→签名往返） | WP2 | 未实现 |
+| ② 压缩后的历史不出现孤立 tool_call | 库：`TestCompactLeavesNoOrphanToolCall`（既有，原样保持）；产品：`TestTrimOldestKeepsToolPairs`（新，WP1-1） | WP1 | 库已修 / 产品侧仍开放 |
+| ③ MCP 取消不再留下第二个读者 | `TestStdioSlowCancelThenEcho`（既有，`Readers()==1`，WP3 不得破坏） | WP3（回归引用） | 已满足 |
+
+## 四、边界与非目标
+
+- **不做** backend 直连路径的延迟工具层与 filestate 接线：该路径属 Q3 退役对象，避免双线建设；N2 的延迟工具成果经 agent-native 路径消费（已通）。
+- **不做** `SubLLMRunner` 迁 exec.Backend（Q3 范围）；WP5 的独立转录用产品侧导出实现。
+- **不做** native.Options 单件重构（审计 N30）；新端口不再往里加字段。
+- **不做** MCP tasks/* 的完整产品映射（最小集 only：客户端面 + 中断取消）；完整后台任务子系统归 N3。
+- **不做** token 计费口径拆分（审计 N20 残余）、RunState/OTel/模型回退链/流重试——全部是 N3 范围。
+- 激活工具不进 `Decls()` 保持现状（call_tool 间接层即设计）。
+- 审计 N2（事件竞争）、N3/N18/N19（MCP）、N22（提醒角色）、N7/N8（压缩配对/并发）已修，仅引用不返工；审计 N4 随 WP2 关闭。
+
+## 五、风险与回退
+
+- **Anthropic 方言漂移**：以录制夹具锁定请求/响应字节形态，预设切换属行为变化——任务卡明示；回落手段：models.json 自定义指回 compat 端点（无需改码）。
+- **skills 严格化拒旧内容**：bundled recipes 同 PR 修齐；用户/插件目录里的不合规技能从「静默可用」变「报错可见」——这是本 WP 的有意行为变化，验收时以插件演示技能全绿为门槛。
+- **ctxasm 裁切语义变化**：整组同退可能多丢一条 assistant——以配对安全为优先；`Report.Truncations` 文案同步更新。
+- **MCP 版本协商**：服务端低版本时必须逐字节回落现行行为（WP3-1 的回落用例为放行门槛）。

docs/proposals/2026-10-07-agent-stack-n3-plan.md

@@ -0,0 +1,170 @@
+# 方案：N3 持久与可观测——现状核验与增量实施
+
+日期：2026-10-07。上游：[2026-10-02-agent-stack-completion.md](2026-10-02-agent-stack-completion.md)「N3 持久与可观测」节（范围与三条验收的唯一权威）、[2026-10-02-agent-stack-audit.md](../records/2026-10-02-agent-stack-audit.md)（审计项逐条对当前代码复核后引用）。
+
+基线 pin：agent-native `74aa60b`、backend `7980a8a`、agent-squad `6306451`、core `0b5c774`（均为已合入 main）。本文所有 file:line 以这些 SHA 为准；实施时先复核再引用。
+
+依赖状态：N1/Q1/I1/I2/N2 全部闭卡（任务卡归档）。总提案依赖序「N3 在 N2 之后」满足，N3 开工。
+
+## 一、现状核验（五路侦察 + 关键处亲验）
+
+### 1. RunState 可恢复（验收①）
+
+已就位（库层、native 适配路径）：
+
+- **意图日志**：`runOne` 先 `commitToolIntent`（记 CallID/参数/Replay 声明）再执行（runtime/loop.go:649-654,738-749；session/intent.go:9-25）；执行失败于写意图即产 IsError 配对。
+- **恢复配对**：`recoverPending`（loop.go:707-736）对未配对意图——存储声明与注册表现行声明**双 safe 才重放**（completion doc row 75 的不变式），否则补「副作用未知，未重试」IsError 配对。任一情形配对不变式都成立。
+- **预算停配对**：`appendSkippedToolResults`（loop.go:452-469，N1 已修，回归 loop_budget_test.go:78）。
+- **毒化轮转**：`rotateIfPoisoned` + `.native-last-failure` 落盘（adapters/native/backend.go:529-593，N21 已修，跨进程回归 r2_regression_test.go:19）。
+- 回归测试：durable_test.go 四组（safe 重放一次/unsafe 不重放/存储 safe+现行 never 不重放/follow-up 持久序）。
+
+仍开放：
+
+- **崩溃窗口无保护**：`persist(assistant)`（loop.go:265）→ 首个 `commitToolIntent`（loop.go:650）之间被杀，转录留下带 tool_calls 的 assistant 且零意图；`recoverPending` 无计可施，新 user 消息追加在孤立尾巴后，下一个请求被提供方拒绝。**无任何与意图无关的尾部配对兜底**。
+- **产品会话路径零持久**：`llm_direct.go:172-193` 调 `nruntime.Run` 不传 `Session`——意图日志/恢复配对在产品会话 run 上全部不生效；中断后部分 parts 只存内存，seal 即丢。**这是验收① 对产品的真缺口。**
+- 无 mid-turn RunState 类型（turn 序号/在途调用/累计用量）；`runtime/checkpoint` 是文件回滚日志，不是循环状态（checkpoint.go:13-22）。
+- 无「杀进程中途」测试：现有 durable 测试手喂意图，没有覆盖 persist→intent 窗口。
+- **N6 残余**：`Stop.Replacement` 仍把内存 assistant 改为替换文（loop.go:339-347），磁盘上 assistant 是原文——内存/转录分叉跨重启可见（追加的 user 替换消息只缓解了「模型能看到」）。
+- **子代理优雅停机不续跑**：`InterruptRunning` 对所有子 run 写 `done.json{status:"interrupted"}`（runmgr.go:1658），而 `ResumeInterruptedChildren` 遇 done.json 即跳过（subagent_transcript.go:119）——WP5 续跑只对 SIGKILL 式死亡生效，优雅停机语义上反而不续。
+
+### 2. 文件检查点可回滚（验收②）
+
+已就位：
+
+- 库 checkpoint 包：append-only JSONL（Record{Seq,Anchor,Root,Path,Existed,Before,After}）、`Plan/Rewind`、内容漂移跳过（stateRestore/Already/Skip，checkpoint.go:194-229）、包注释与结构双重保证「shell/python 不追踪」。
+- write/edit/multi_edit 三工具经 `WorkspaceToolsCheckpointed` 挂 mark（registry.go:370-394；builtin.go:111-117,153-168,333-353）。
+- backend rewind：每会话 `.agentx/checkpoints.jsonl`（rewind.go:12-17）、anchor=用户消息 ID、HTTP 两路由（server.go:169-170）、regenerate 复用（borrow.go:218）、忙时 409。
+- ZCode 边界全符合：只动文件不回滚历史（追加 system 消息而非删除）、不透明续跑（regenerate 显式起新 run）。
+- 测试：checkpoint_test.go 两组、checkpoint_hook_test.go、rewind_test.go（backend 端到端）。
+
+仍开放（收口项，无根缺）：
+
+- 回滚资格**隐式**（struct 有 mark 字段即入集）：无导出断言/注册表查询，未来工具可静默入集或出集。
+- `restore` 用 `os.WriteFile` 跟随符号链接（checkpoint.go:241）——fs_write_file 有符号链接防护（fs.go:142-146），回滚路径没有。
+- `Rewind` 顺序恢复、首错即返（checkpoint.go:108）：中途失败留下部分恢复，且部分态不进 Result。
+- 无保留策略：`Record` 每次全读算 Seq（checkpoint.go:57-62），日志无界增长。
+- HTTP 层无测试；root 移动、空 `ordered` 边界（selected() checkpoint.go:146）未测。
+- backend 自家工具面只有 `fs_write_file` 挂检查点（tools/fs.go:158-162），无 fs_edit/fs_multi_edit（产品面不暴露编辑工具）——验收② 的 write/edit/multi_edit 语义在库与适配层成立，验收测试按层分配（见 WP3）。
+
+### 3. Memory 端口
+
+已就位（全是产品侧资产）：`memory_entries` 表（migrate v13）+ `PutMemory/ListMemory`（platform.go:137,157，仅 INSERT、无 scope 过滤无语义排序）；HTTP 手工面（server.go:245-246）；被动 recall（runmgr.go:409-426 全量过期过滤 + ctxasm.InjectMemory ≤20 条注入系统消息）；`session_note`、plans/todos；预置 prompts（aux-session-memory.md、agent-memory-extractor.md，**无消费者**）；`AgentSpec.MemoryScope` 已解析（agentspec.go:26,152-153）**零消费**。
+
+仍开放：库内零 memory 面（端口不存在）；无写回路径（模型不可自服务，回合后抽取未接线）；recall 无 scope 过滤；MemoryScope 无消费。
+
+### 4. OTel GenAI span（验收③）
+
+已就位：telemetry 包（Span/StartFunc/手写 OTLP HTTP JSON 导出，telemetry.go:18-106）；**`publicAttrs` 拒绝名单丢 prompt/messages/content 且被测试钉住**（telemetry.go:53-62,89；telemetry_test.go:35-41）——验收③「默认不含提示词正文」已满足且有机器证据；Trace 钩子三处 span（loop.go:174 invoke_agent、:407 chat、:655 execute_tool）；backend 全线注入（app.go:87,258,284-285 → llm.go/sub_loop）。
+
+仍开放：
+
+- **span 名无后缀**：约定是 `chat <model>`/`execute_tool <tool>`/`invoke_agent <agent>`，现名裸词。**这是验收③ 的主缺口。**
+- 属性未 `gen_ai.*`：缺 `gen_ai.system`、`gen_ai.request.model`、`gen_ai.tool.name`、`gen_ai.usage.input_tokens/output_tokens`（token 在循环有，从未进 span）。
+- 无 trace 关联：每 span 随机新 TraceID（telemetry.go:33），无 parentSpanId，Span 无 Parent/Status/Kind 字段。
+- 配置面只有环境变量 `OTEL_EXPORTER_OTLP_ENDPOINT`（telemetry.go:30），无 settings 项。
+- resource 无 `service.name`；导出错误丢弃（:46）；属性值全 string（token 应 intValue）。
+
+### 5. 成本「上一请求/累计」
+
+已就位：`Usage.Last*` 三字段（types.go:90-99）+ 循环覆盖（loop.go:262-264）；预算检查用 `LastPromptTokens`（loop.go:872-873，正确——prompt 成本按整段历史计）；`message_end` 事件带单请求值（loop.go:269）。
+
+仍开放：cache tokens 从不累计（loop.go:259-264 只动 Prompt/Completion/Total）；`"usage"` 事件只带累计（loop.go:853-855，且 budgetStop/错误路径不发）；`core.Usage` 无 Last*/cache 字段（modules/core model.go:205-213）；**子代理 run 零 token 记录**（runmgr.go:1399 只记 DurationMs；sub_loop 不调 AddUsage）；前端只显示 total（AgentTracker.tsx:79-83）；无逐请求台账。completion 预算用累计（loop.go:875）经复核为**正确语义**（run 级输出预算），不动。
+
+### 6. 模型回退链（基本已修，剩收口）
+
+已就位：库 `WithFallback`（llm/fallback.go:7-47——5xx 且未出增量才切换，测试 fallback_test.go 三组）；backend `ChatFallbacks` 解析（model.go:65-81）+ 消费（llm_direct.go:103、sub_loop.go:61 chat 档子代理）+ `noteModelSwitch` 通知与 servedModel 落账（llm_direct.go:210-240）。回退条目共享主端点（记录为有意）。
+
+仍开放（收口项）：verifier 与 lightweight 档未接；切换无可观测事件类型（仅 process part 文案）；agent-native CLI 未用 WithFallback。
+
+### 7. 流式错误默认重试
+
+已就位：`WithRetry`（providers.go:447-524——Retryable 分类 408/429/529/≥500 与容量文案、Retry-After 上限 30s、指数退避加抖动、**只在未出增量时重试**、上下文溢出不重试；providers_test.go 五组钉住）；backend `runtime.llmRetries` 默认 2 接直连（llm.go:208-209；settings.go:43,94）；agent-native CLI 接 2 次（main.go:121）。
+
+仍开放：**库循环无默认**——重试是宿主 opt-in，子代理/verifier/squad 路径未接（`sub_loop.go:52-59` 无 WithRetry）；`onEvent` 为 nil，重试不可观测；run 记录无重试次数。
+
+## 二、工作包划分
+
+| WP | 内容 | 主要仓 | 对应验收 |
+|---|---|---|---|
+| WP1 | RunState 收口：崩溃窗口尾部配对兜底 + 杀窗口测试 + N6 残余 + 子代理优雅停机续跑语义 | agent-native + backend | ①（库层） |
+| WP2 | 产品会话路径持久化：llm_direct 接 Session（transcript.jsonl），产品会话 run 获得意图日志与恢复配对 | backend | ①（产品层） |
+| WP3 | 检查点收口：资格断言、符号链接防护、部分恢复进 Result、保留策略、HTTP 与边界测试 | agent-native + backend | ② |
+| WP4 | OTel GenAI 对齐：span 名后缀、gen_ai.* 属性、trace 关联与 parent、resource、settings 面 | agent-native + backend | ③ |
+| WP5 | Memory 端口：runtime/memory 包 + 循环 recall 消费点 + MemoryScope + backend scope 实现 + memory_write 工具 | agent-native + backend | — |
+| WP6 | 计费拆分与回退/重试收口：cache 累计、usage 事件与 run 记录带 Last*/cache、子代理 token、库默认重试、可观测事件 | agent-native + core + backend + frontend | — |
+
+依赖：WP1 先行（验收① 库层核心，WP2 依赖其兜底语义）；WP2 随后（产品落点）；WP3/WP4/WP5 独立可并行；WP6 收尾（含 core 字段级联与重试语义变化，WP6 后做总装与 A/B）。每 WP 走既有链式（库 PR → 级联 → backend PR → Dev gitlink PR），逐 WP 合入。
+
+### WP1 RunState 收口（验收① 库层）
+
+1. **尾部配对兜底**：`recoverPending` 之后加 `repairOrphanTail`——Load 后若活动分支尾部是带 tool_calls 的 assistant 且其 ToolCalls 存在无结果项，对每个无结果调用补一条 `tool` 消息（`Content: "进程中断，该调用未执行"`, IsError: true）并 persist。与意图路径正交：意图已配对的调用不受影响（按 CallID 判重）。这样无论死在哪个窗口，下次 Run 前转录配对恒成立。**这是验收① 的机器核心。**
+2. **杀窗口测试**：循环测试钩子（在 persist(assistant) 之后、首个 intent 之前让测试能停住循环，或直接构造该转录形态——两态都测：窗口内死亡（无意图）与执行中死亡（有意图未配对）），断言：恢复后 assertToolPairs 双向成立 + 兜底结果文案正确 + 已配对项零重复。
+3. **N6 残余**：`Stop.Replacement` 不再改内存 assistant（只追加 user 替换消息）——内存与转录一致；`loop_harness_test.go:17-63` 同步改断言（替换文案不再出现在 res.Messages 的 assistant 上，而是新 user 消息）。行为变化入卡。
+4. **子代理优雅停机续跑语义**：done.json 按 status 分流——`completed/failed/cancelled` 挡续跑；`interrupted` 不挡（优雅停机=可续跑现场）。`ResumeInterruptedChildren` 改判据并补回归（模拟 InterruptRunning 路径后仍被续跑一次且仅一次）。
+
+### WP2 产品会话路径持久化（验收① 产品层）
+
+1. `llm_direct.go` 的 `directRun` 打开会话工作区 transcript：`<workspaceRoot>/<owner>/<conv>/.agentx/transcript.jsonl`，经 `runtime.Session` 传入 `nruntime.Run`——产品会话 run 获得意图日志、恢复配对与（WP1-1 的）尾部兜底。
+2. 历史来源对齐：现 `History` 来自 store 重放；Session 模式以 transcript 为准（库语义：Session 非空时 transcript 是权威，History 仅在 transcript 为空时作种子——llm.History 的既有语义 loop.go:76-78）。迁移语义：首次启用时 transcript 为空 → 用 store 历史种子；此后 transcript 权威。种子与续接的一致性测试（不丢不重）。
+3. **不做透明续跑**（ZCode 边界，入卡）：`ReconcileInterrupted` 对会话 run 仍 seal interrupted；配对修复在下一条用户消息触发的新 run 前完成（WP1-1 兜住），用户看到的是「中断」标记 + 可继续对话，不是自动重跑。
+4. 端到端测试：产品路径杀窗口形态 → 新 run 前配对成立 + 用户可继续发消息（种子不丢历史）。
+
+### WP3 检查点收口（验收②）
+
+1. **资格断言**：导出 `Registry.Checkpointed(name) bool`（struct mark 非空即真）或同语义测试辅助；测试钉住入集集合恰为 {write_file, edit_file, multi_edit}（库）与 {fs_write_file}（backend 自家面），防静默漂移。
+2. **符号链接防护**：`restore` 落盘前 `Lstat`——目标为符号链接时跳过并进 Skipped（与 fs_write_file 的防护同语义）+ 测试。
+3. **部分恢复进 Result**：`Rewind` 单文件失败不中止，记录 `Failed []string` 续跑其余；Result 增字段（additive）；测试（一个失败一个不失败）。
+4. **保留策略**：按 anchor 裁剪——`Log.Compact(keepAnchors int)` 只保留最近 N 个 anchor 的记录（重写日志文件）；backend 在 RewindFiles 成功后以 keepAnchors=200 调用；`Record` 的 Seq 改由文件尾行号维护（去全读）。
+5. **测试补齐**：HTTP happy + busy 409（server 层）；root 移动场景（restore 按记录内 Root 恢复，不窜根）；空 `ordered` 边界行为钉住；「外部同字节改写」分类为 Already 的语义钉住。
+
+### WP4 OTel GenAI 对齐（验收③）
+
+1. **span 名带后缀**：`invoke_agent <agent|agent-native>`、`chat <model>`、`execute_tool <tool>`（loop.go 三处改名；适配器/宿主传 agent 名——invoke_agent 的 agent 名用 Config.ExecutionID 或新增 Config.AgentName，默认 "agent-native"）。
+2. **`gen_ai.*` 属性**：`gen_ai.system`（openai/anthropic，由客户端协议名上抛——Stream 事件或 Config 显式字段，取后者简单：`Config.ProviderName string`，宿主可设，空=openai）；`gen_ai.request.model`（chat span）；`gen_ai.tool.name`（execute_tool span）；`gen_ai.usage.input_tokens/output_tokens`（chat span 结束时由该轮 Usage 填入）。
+3. **trace 关联**：一次 Run 共享一个 TraceID，`invoke_agent` 为根、`chat`/`execute_tool` 为其子（parentSpanId）。Trace 钩子签名扩展：`Trace func(name string, attrs map[string]string) func()` 保持，Span 增 ParentSpanID/TraceID 注入位（telemetry.StartFunc 返回的闭包按 name 层级维护栈——invoke_agent 入栈为根，出栈弹出；简单确定性强）。
+4. **resource 与导出**：resource 增 `service.name=agent-native`（宿主可覆盖：telemetry.StartFunc 的选项参数）；token 属性 intValue；导出失败记日志（不静默吞）。
+5. **settings 面**：`telemetry.otlpEndpoint`（默认 "" = 不导出，保持现状语义；环境变量继续有效，settings 覆盖环境）；`telemetry.serviceName`（默认 agent-native）。两处 default 的行为不变证明测试。
+6. **测试（验收③ 机器证据）**：span 名后缀与属性键枚举断言（钉住约定）；一次 Run 的 span 共享 TraceID 且 parent 链正确；token 进 chat span 且为 intValue；拒绝名单保持（prompt/content 永不序列化——既有测试原样通过）。
+
+### WP5 Memory 端口
+
+1. **runtime/memory 包**：`Entry{ID,Scope,ProjectID,Type,Content,Source,Confidence,CreatedAt,ExpiresAt}` + `RecallQuery{Scope,ProjectID,Limit}` + `Store interface{ Recall(ctx,q) ([]Entry,error); Append(ctx,e Entry) error }`。端口形态对齐 squad/runstore.go 的先例（库定义+宿主实现）。
+2. **循环消费点**：`Config.Memory memory.Store`（nil=不启用）+ `Config.MemoryScope string`（对应 AgentSpec.MemoryScope 的消费）；`prepareRequest` 时在系统前缀后追加 recall 注入块（替换文案形态与 ctxasm.InjectMemory 对齐：`[记忆]\n- (typ) content`，上限 20 条，确定性排序）——行为对齐测试（端口注入的条目出现在请求里、nil 时无变化）。
+3. **backend 适配**：`storeMemory{st, owner}` 实现端口（Recall=ListMemory scope/过期过滤+Limit；Append=PutMemory）；`llm.go` 装配把现 `Memories()` 断言路径（llm.go:231-233 + runmgr.go:409-426）迁到端口（语义等价：同条目同排序同文案——迁移前后注入文本一致的对照测试）。`AgentSpec.MemoryScope` 经 squad/native 适配传入 Config.MemoryScope（plugin agents 的画像驱动 scope）。
+4. **memory_write 工具**：库内工具（模型自服务写回；参数 {scope,type,content,expires_in_days?}，经 `Config.Memory.Append` 落库；未配置不注册）；scope 校验（user|project）与类型校验（fact|preference|decision|episode|procedure）fail-closed。
+5. 后续项（入卡剩余项，不在本 WP）：回合后抽取接线（agent-memory-extractor 子代理 + SessionEnd 事件驱动）、AllowStore 持久化形态（N1  deferred）。
+
+### WP6 计费拆分与回退/重试收口
+
+1. **cache tokens 累计**：loop.go:259-264 增 CacheRead/Write 累计与 Last* 对应位（Usage 增 LastCacheReadTokens/LastCacheWriteTokens?——决策：Last* 只对 Prompt/Completion/Total 已有三字段，cache 只入累计位，避免字段膨胀；记录决策依据）。
+2. **usage 事件与 run 记录**：`emitUsage` 带 Last*+cache；settle 之外的路径（budgetStop/错误）也发一次终态 usage（口径=当时累计，标注终止原因在既有错误面）；`core.Usage` 增 `LastPromptTokens/LastCompletionTokens/CacheReadTokens/CacheWriteTokens`（additive JSON，core 仓 PR+级联）；backend AddUsage 链路上抛新字段；**子代理 token 记账**（sub_loop AddUsage 接线，finishChild 写入 child.Usage 的 token 字段）。
+3. **前端**：contracts.ts Usage 增可选字段；UsageBadge 显示「上一请求 / 累计」（如 `+12.3k · 累计 98.1k`）。
+4. **库默认重试**：`Config.RetryAttempts`（默认 2，0=关）——`Run` 内包装 `cfg.Stream = llm.WithRetry(cfg.Stream, attempts, onEvent)`；backend 直连的显式包装退役（防双重），子代理/verifier/squad 经库默认获得（行为变化：这些路径从 0 次变 2 次重试——入卡；onEvent 接 runCtx 事件面，`auto_retry_start/end` 成为可见事件）。
+5. **可观测**：`auto_retry_start/end` 与 `model_fallback_switch` 事件类型入事件面（库 Event 类型 + backend 映射 + 前端展示沿用现有 process part 形态）。
+6. **回退链接 verifier/lightweight**：verifier 的流包 WithFallback（lightweight 档回落主档的既有语义不动）；CLI 记录边界（不接）。
+
+## 三、验收总表
+
+| 总提案验收 | 机器证据 | 所在 WP | 现状 |
+|---|---|---|---|
+| ① 回合中途杀进程，恢复后工具配对仍成立 | 库：`TestResumePairsOrphanTailAfterCrashWindow`（无意图窗口）+ 既有 durable 四组（原样保持）；产品：`TestDirectRunPairsAfterKillSeed`（种子不丢+配对成立） | WP1+WP2 | 库有意图路径覆盖、窗口无保护；产品零持久 |
+| ② 回滚只撤销 write / edit / multi_edit | 资格集合钉住测试（库 {write_file,edit_file,multi_edit}、backend {fs_write_file}）+ 既有 rewind/checkpoint 测试原样通过 + shell 文件存活断言（既有） | WP3 | 结构性成立、断言隐式 |
+| ③ span 名与约定一致，默认不含提示词正文 | `TestSpanNamesFollowGenAIConvention`（名称后缀+gen_ai.* 键枚举+intValue token+TraceID 共享+parent 链）+ 既有 publicAttrs 拒绝名单测试原样通过 | WP4 | 正文拒绝已有；名称/属性/关联未对齐 |
+
+## 四、边界与非目标
+
+- **不做透明续跑**（ZCode 边界）：配对修复后等新用户消息；会话 run 仍 seal interrupted。WP5 子代理续跑（重派新 run）是既有有意设计，不扩展到会话 run。
+- **不回滚对话历史**（ZCode 边界）：rewind 只动文件，WP3 不碰消息面。
+- **不做** memory 回合后抽取接线、AllowStore 持久化、RAG 语义检索 memory_entries（WP5 是端口与接线，召回排序升级留后续）。
+- **不做** OTel SDK 引入/gRPC/batch/采样（保留手写 HTTP JSON 导出；WP4 只做语义对齐与可靠化小修）。
+- **不做** completion 预算口径改动（loop.go:875 经复核为正确语义）、prompt 预算口径改动。
+- **不做** 回退条目独立端点（共享主端点记录为有意）、CLI 的 fallback 接线（记录边界）。
+- 审计 N1/N21 已修只引用；N6 随 WP1 关闭；N20 随 WP6 关闭（预算语义不动，展示/记录口径拆分）。
+
+## 五、风险与回退
+
+- **产品路径接 Session（WP2）**：transcript 成为权威是会话语义变化——种子迁移必须保「不丢不重」（WP2-2 的对照测试为放行门槛）；出问题回退 = 不传 Session（单点开关，代码内常量而非设置项，回退 PR 即可）。
+- **N6 行为变化（WP1-3）**：Stop.Replacement 的展示形态变化（assistant 不再显示替换文，替换文以 user 消息出现）——guardrails 消费方（verify 回路）逐一回归。
+- **WP6 重试默认化**：子代理/verifier/squad 从 0 变 2 次重试——超时/配额消耗上升；`RetryAttempts=0` 可全关（测试钉住 0=不重试）。
+- **core.Usage 加字段**：additive JSON 兼容旧记录；级联链 core PR → backend PR → frontend PR → Dev。
+- **done.json 语义分流（WP1-4）**：interrupted 从「挡续跑」变「可续跑」——优雅停机后重启会多一次重派；幂等由 resumed.json 保证，测试钉住「一次且仅一次」。

docs/proposals/2026-10-07-agent-stack-q2q3-plans.md

@@ -0,0 +1,100 @@
+# 方案：Q2 拓扑 + Q3 收敛与互通——现状核验与增量实施
+
+日期：2026-10-07。上游：[2026-10-02-agent-stack-completion.md](2026-10-02-agent-stack-completion.md)「Q2 拓扑」「Q3 收敛与互通」节（范围与验收的唯一权威）、[2026-10-01-agent-harness.md](2026-10-01-agent-harness.md) P4 裁定（Q3 行为等价的判据原文）。
+
+基线 pin：agent-squad `c462bc4`、agent-native `1ac21c6`、backend `6e02a1f`、core `a253a40`（均为已合入 main）。本文所有 file:line 以这些 SHA 为准；实施时先复核再引用。
+
+依赖状态：N1/N2/N3/Q1/I1/I2 全部闭卡。总提案依赖序「Q3 在 Q2、N1、I1 之后」满足。两阶段各自单独任务卡（本文覆盖两个方案；Q2 先实施，Q3 在 Q2 闭卡后开工）。
+
+## 第一部分：Q2 拓扑
+
+### 一、现状核验（三路侦察）
+
+引擎面：只有 `standard`/`leader` 两个 mode（engine.go:94-96,383-400，RunMetadata.Metadata 字符串），**无拓扑抽象**。Q1 图层可表达 sequential（graph.go:62-68 链式默认）与 parallel（Parallel/Needs 同层 + 写集串行，graph.go:56-61,165-182）；环 fail-closed（graph.go:71-73）。router 只有 pre-plan 分诊（router.go:24-52）。leader 有 delegation 循环（leader.go:180-385）但账本只有 `Delegations`（leader.go:51-66），无卡顿检测；轮次上限有（MaxLeaderTurns=8，termination.go），**无独立重规划上限**；leader 绕过图循环直接 runOneStep（leader.go:328-341）。Termination 的 Cond/And/Or 组合子（termination.go:59-120）已建但**休眠**（只有测试消费）。`FactItem.Verified`（models.go:148）声明未用。
+
+mailbox 攻击面：`RespondDecision`（hitl.go:99-108）**无 actor 归属**——任何能调 `engine.Respond` 的调用方发 `Choice:"approve"` 都清权限门。现有防线：fireWakeup 只自动决 gap/escalation（engine.go:1216-1227，回归 TestWakeupDoesNotApprovePermission）、自由文本不决议 choice 门、过期只合成 fail/cancel、wakeup 上限自动 abort。mailbox 若经 Respond 投递或扩 fireWakeup 白名单即破防。
+
+review 等价基线（backend runReview，review.go:41-92）：并行 N finder（semaphore 3，真并发被 review_test.go:16-33 钉住）→ 宽松 JSON 解析（首 `[` 末 `]`，丢空 issue）→ 按 (location,issue) 去重、上限 10 → 每条独立 verifier（VERDICT: PASS/FAIL/PARTIAL 尾行判定）→ 只留 PASS（fail-closed）→ severity 稳定排序 → 报告恒带「已丢弃 N 条未验证」。squad 侧今天只有质量 Checker+修复预算（单轮），无此拓扑。
+
+task-board/long-running：平台 SQLite 队列有 claim/lease/heartbeat/orphan 恢复（adapters/sqlite/queue.go:133-348）但未接 Steps 图；checkpoint 三档+图连续性+run 锁已就位（runstore.go:94-212）。conformance 基建齐全：scriptBackend/replayBackend/leaderScriptBackend + MockPlanner（engine_test.go:13-80、conformance_test.go:19-47、leader_test.go:15-90）。
+
+### 二、设计决策
+
+1. **拓扑一等化但不做大重构**：`Blueprint` 与 `RunOptions` 增 `Topology string`（空 = 现行 standard 图，零行为变化）；`squad/topology.go` 注册内置拓扑名与各自 Spec。图可表达的（sequential/parallel/loop/router/evaluator-optimizer/long-running）编译为 Steps+引擎旗标；需要独立驱动的（leader 增强/review/group-chat/task-board）走驱动分支；handoff/mailbox 是**跨拓扑原语**（任何拓扑可用）。
+2. **loop 不做图环**：保持环 fail-closed。`StepSpec.Loop *LoopSpec{MaxIterations, UntilField, UntilEquals}`——步骤完成后条件不满足且预算未尽时**重置为 pending 再武装**（推广 rerunForRepair 语义）；预算走 Termination（唤醒休眠的 Cond 组合子）。
+3. **router 进图**：`StepSpec.Branches []Branch{When{Field,Equals}, Then []stepID}`——router 步完成后按黑板字段/步骤输出判定，未选中分支的步骤置 skipped（skipped=依赖已满足，join 步照常推进）。
+4. **mailbox 的防线是构造性的**：投递路径**永不经过 Respond**；同时给 `RespondDecision` 加 `Actor`（human/system/agent，空=human 保持既有调用方语义），`applyDecision` 对 permission/confirmation/quality_review 三类门拒绝非 human 的 choice 决议（双保险）。
+5. **review 等价以报告字节形态为判据**：squad review 驱动复用 backend runReview 的解析/去重/判定/排序/文案常量（同一格式串），conformance 断言与 review_test.go 同款（并发找、去重后逐条验、丢弃计数、severity 序）。
+6. **task-board 做 squad 侧原语**（claim/lease/complete + 依赖门），语义与平台队列对齐；平台队列桥接记为后续项（completion doc 的「platform 队列改成 task-board」在桥接层，非本 WP 阻塞）。
+
+### 三、工作包
+
+| WP | 内容 | 验收对应 |
+|---|---|---|
+| Q2-WP1 | 拓扑面 + 图可表达五件：Topology 字段与注册表；sequential/parallel conformance；loop 再武装（LoopSpec+Cond 预算）；router 分支（Branches+skipped）；evaluator-optimizer（loop 复合：draft→evaluate→MinScore 不达标再武装，MaxRounds 预算）；long-running（Deadline 打包进 terminationOf + checkpoint 组合 conformance） | 验收一（6/12 拓扑） |
+| Q2-WP2 | leader 增强 + mailbox：进度账本（Progress 条目+卡顿检测 StuckTurns）、重规划上限（Replans/MaxReplans 独立于 MaxTurns，触顶降级收口）；mailbox 原语（RunState 邮箱、PostMessage、步前投递进任务书、永不触 Respond）+ RespondDecision.Actor + 非 human 决议拒绝 | 验收一（8/12）+ 验收三 |
+| Q2-WP3 | review + handoff + group-chat：review 驱动（并行 finder→解析去重→逐条 verify→fail-closed 过滤→等价报告）；handoff 原语（StepSpec.Handoff、所有权转移记录、finalize 取链尾输出、目标收过滤历史）；group-chat 驱动（共享转录、轮转/主持人选人、预算停机） | 验收一（11/12）+ 验收二 |
+| Q2-WP4 | task-board + 收口：claim/lease/complete 原语与依赖门、孤儿租约再武装；全 12 拓扑 conformance 汇总跑；级联（backend 嵌套 pin → Dev） | 验收一（12/12） |
+
+conformance 统一形态：脚本化后端（scriptBackend/replayBackend/leaderScriptBackend 家族扩展），零模型零网络；每拓扑一个 `TestTopologyConformance_<name>`。
+
+### 四、Q2 验收总表
+
+| 总提案验收 | 机器证据 | WP |
+|---|---|---|
+| 每种拓扑有一个脚本化后端的 conformance | 12 个 TestTopologyConformance_*（sequential/parallel/loop/router/leader/handoff/group-chat/review/evaluator-optimizer/long-running/task-board/mailbox） | WP1-4 |
+| review 等价于今天的「并行找问题、逐条验证、丢掉未验证」 | review conformance 断言与 backend review_test.go 同款：finder 真并发、去重后 verify 调用数=unique 数、只留 PASS、「已丢弃 N 条未验证」计数、severity 序 | WP3 |
+| mailbox 消息不能把挂起的权限批准掉 | TestMailboxCannotApprovePermission（挂 permission 门→投「approve」消息→门仍挂起）+ TestWakeupDoesNotApprovePermission 原样通过 + Actor 拒绝路径测试 | WP2 |
+
+### 五、Q2 边界与非目标
+
+- 不改 leader 绕过图循环的执行形态（记为已知债，统一驱动属后续重构）。
+- 平台队列桥接、backend review_findings 切换到 squad review 拓扑：后续项（Q3+ / RDM 阶段按需）。
+- group-chat 的发言人策略只做轮转与主持人两种（脚本可判定）；LLM 选人策略不进库。
+- Termination Cond 组合子被 loop/long-running 唤醒后，既有标量路径不动。
+
+## 第二部分：Q3 收敛与互通
+
+### 一、现状核验
+
+WorkflowDef 在 core（plugin.go:56-84）：六类步骤（prompt/tool/hitl/artifact/card/script）+ StepCritic，**无条件分支字段**；golden 样本 workflow_def.json。执行器 `runtime/workflow.go`（步循环 125-200、critic 重试 202-244、prompt 步压 SpawnSubagent 312-334）+ `workflow_script.go`（脚本宿主 38-56、限额 19-24、DeniedTools 180）。数据层 `internal/workflow/`（registry/render/validate，P4 上限 11-16）。**「压成 SpawnSubagent」退役对象**：squadadapter stepBackend "agent-system"（adapter.go:150-212，DefaultBackend adapter.go:79，内置四角色全部 agent-system 380-392）。
+
+P4 裁定原文（agent-harness.md:102-112）：声明式 ≤20 步；模型生成 ≤8 步、禁 script、执行前必须确认；critic 每步 ≤3（缺省 1）、整条 ≤6、无法解析按不通过；脚本回调 ≤50、单行 ≤1MB、超时 600/1800s 含等人；`runtime.workflowScripts` 默认关；模型脚本必须确认、**插件脚本免确认**；脚本禁 run_python/run_shell/run_workflow/派发类；小队入口无 run_workflow。代码落点齐全（validate.go:11-40,80-83；workflow.go:64-76；workflow_script.go:26-28,38-56,103-115）。
+
+demo 插件在 Dev 仓根 `plugins/example/`：demo.brief（意图 demo.brief，五步：hitl choice→prompt+critic「核对标记：P4」→artifact→card→hitl confirm）、demo.script（单 script 步 → demo.py：wf.tool/wf.ask/wf.artifact/wf.step）。host_test.go:214-256 直接装载它。
+
+a2a：**全仓不存在**，从零建（规划位置 agent-squad/adapters/a2a 独立 go.mod；A2A 1.0 Agent Card/任务状态机对齐，completion doc:54,102,239）。默认执行后端：`runtime.entry` 默认 direct（settings.go:39，灰度注释）；direct 已跑 agent-native 内核；squad 工具路径默认后端 "agent-system"（要切）；RunEntry 已是 agent-native（entry.go:103）。A/B：eval/switch.go 的 DecideSwitch 骨架 + N1 wp5_ab_test.go 先例；缺「同批任务双跑记录差异」harness。委派模板：内核 SubagentFactory 已有 目标/输入/可写范围/非目标/完成判据/交付物（adapter.go:299-343），**缺「输出格式」与「工具面」**两节。
+
+### 二、工作包
+
+| WP | 内容 | 验收对应 |
+|---|---|---|
+| Q3-WP1 | 编译器：core.WorkflowDef → squad Blueprint/Steps（prompt→agent-native 角色步、hitl→RequiresApproval/intent 步、tool/artifact/card→宿主工具步、script→codeorch 宿主步、critic→Checker+MinScore+RepairBudget；P4 全部上限与 DeniedTools 迁入编译器；计划确认与模型脚本确认保留、插件脚本免确认、workflowScripts 开关保留） | demo.brief/demo.script 经编译图跑通 |
+| Q3-WP2 | 退役与切换：删 internal/workflow 数据层执行依赖、runtime/workflow.go+workflow_script.go 退役（run_workflow 三分支改投编译图）、stepBackend "agent-system" 删除、DefaultBackend→agent-native、runmgr WorkflowRunner 分支移除 | P4 行为一致（步数上限/确认/脚本开关逐项测试） |
+| Q3-WP3 | 委派模板补全：任务书增「输出格式」「工具面」两节（SubagentFactory 与 stepBackend 遗产路径统一）；adapter_test 任务书断言扩展 | 委派模板含目标、输出格式、工具和边界 |
+| Q3-WP4 | adapters/a2a（新模块）：Agent Card 发布（描述本团队能力）+ 远端智能体 Executor 客户端（A2A 任务状态机对齐 ExecResult）；双向 conformance（本地起假 A2A 服务端） | adapters/a2a 双向 |
+| Q3-WP5 | A/B 对照与默认后端：任务级 direct vs squad(编译图) 双跑 harness（扩 eval/switch.go），同批任务（含 demo.brief 场景）记录差异（不要求字节级相同）；DecideSwitch 达标则 runtime.entry 默认切 squad 的证据入卡 | A/B 对照记录差异 |
+| Q3-WP6 | 级联闭链 + 任务卡验收证据 | — |
+
+### 三、Q3 验收总表
+
+| 总提案验收 | 机器证据 | WP |
+|---|---|---|
+| demo.brief 与 demo.script 经编译后的图跑通 | 装载 Dev 仓 plugins/example → 编译 → squad 引擎（脚本化后端）跑通两个工作流的 conformance | WP1 |
+| 行为与 P4 裁定一致（步数上限、确认、脚本开关） | 逐项测试：20/8 步上限、3/6 重试、计划确认卡、模型脚本确认、插件脚本免确认、workflowScripts 默认关、DeniedTools、小队入口无 run_workflow | WP1-2 |
+| A/B 对照记录差异，不要求字节级相同 | eval harness 输出差异报告入任务卡（DecideSwitch 判定 + 差异清单） | WP5 |
+
+### 四、Q3 边界与非目标
+
+- `runtime.entry` 默认值切换本身是**设置变更**：A/B 达标后由 WP5 证据支持、在卡上记录，若 DecideSwitch 不达标则保持 direct 并记录差异（验收只要求「对照记录差异」）。
+- a2a 只做库层双向（Card 发布 + Executor 客户端 + 假服务端 conformance）；产品暴露 A2A 端点属后续。
+- 平台 task 队列翻译成 squad run（更深的产品合一）不在 Q3（completion doc 归 Q 系列后续）。
+- internal/workflow 的**数据形态**（WorkflowDef 校验/渲染语义）迁入编译器后原包删除；golden 契约样本随迁。
+
+## 五、风险与回退（两阶段共用）
+
+- **Q2 loop 再武装**与修复重跑共用重置语义：以「预算独立计数」隔离（loop 迭代不占 RepairBudget），测试钉住互不侵占。
+- **Q2 router skipped 传播**：skipped=依赖满足的既有语义使 join 步在分支未选时照常推进——conformance 钉住 join 行为，防止「全分支跳过导致空转完成」被误判成功（报告需列 skipped 分支）。
+- **Q3 退役面大**：以「编译器先行、双轨并行一个增量、退役单独增量」推进；退役 PR 前 demo 插件双轨对照（旧 runner vs 编译图）记录差异。
+- **Q3 默认后端切换**：行为变化门禁是 A/B harness，不达标不切（settings 默认值不动即回退）。
+- mailbox/Actor 默认值兼容：空 Actor=human 保持全部既有调用方与测试语义不变（新增拒绝路径只影响显式非 human）。

docs/proposals/2026-10-07-rdm-phase-plan.md

@@ -0,0 +1,250 @@
+# 研发记忆与体系文档智能体：大阶段目标与实施方案（RDM 阶段总案）
+
+状态：**proposed（2026-10-07）**；owner：weichen；主任务：Dev 仓 `feature/rdm-phase-plan`。
+愿景依据：《智能体系统/further-objective》01–13（产品愿景文档，未入库；方案 10 已复制到下游仓 `Agent-System-RDM` 的 `docs/` 作奠基文档，本文以「愿景 01/02/03/04/08/10/11/12/13」引用）。
+上游：[2026-10-02-agent-stack-completion.md](2026-10-02-agent-stack-completion.md)（库分期）、[2026-10-07-agent-stack-n1q1i1-plans.md](2026-10-07-agent-stack-n1q1i1-plans.md)（N1/Q1/I1 实施方案）。
+规范依据：Development-Guidelines（workflows/delivery.md、standards/collaboration.md、standards/verification.md）；本文是项目级消费，不复制其正文。
+
+本文把 further-objective 描述的最终系统立为本系统下一个大阶段的目标，设定大方向与架构不变量，给出里程碑对齐的实施方案。本文不实施代码；各阶段的实现各走各的任务卡。
+
+---
+
+## 1. 大方向与大目标
+
+### 1.1 一句话目标
+
+把通用智能体基座二次开发为「**面向医疗器械研发企业的研发记忆与体系文档智能体**」：把项目全周期的一切资料持续沉淀为可追溯的研发记忆，让体系文档随项目推进渐进式清晰，并以人在环路的确认机制保证每一步受控（愿景 02 §1）。产品形态为三栏 + 卡片流 + 弹出层（愿景 05/06），数据心智为两树一网：笔记树 + 文档树 + 追溯网（愿景 08）。
+
+按新口径里程碑推进（愿景 10 §10.1，W1 = 2026-10-05~10-11）：
+
+| 里程碑 | 窗口 | 内容 |
+|---|---|---|
+| MS0' | W1（本周） | 需求定稿、双仓就位、决议闭环、v0.1.0 评估基线 tag |
+| v0.2.0 发版 | W2 末，最迟 W3 末（10-25） | 基座含 EXT-1，SurfaceVersion 2.0.0-experimental |
+| MS1 | W4（11-01） | 上传五步法 + 两速入库端到端 |
+| MS2 | W7（11-22） | 文档基线 + 三分类比对 + 版本链 |
+| MS3 | W11（12-20） | 两树一网 + 变更闭环 + 一键生成（结构事件日志先行） |
+| MS4 | W16（2027-01-24） | 自举全程运行、可对外演示（依赖 EXT-3 渠道） |
+
+### 1.2 三条架构不变量（大方向的约束）
+
+**INV-1 双仓纪律（二次开发原则）。** 领域逻辑（两树一网、模板、流程骨架、法规双通道、上传管道）只住在下游仓 `Agent-System-RDM` 与声明式插件规格里；基座（本仓五仓组合）只经「**扩展点申请 → 基座实现并发版 → 下游升级**」演进（愿景 10 §1.1、§七.1）。下游只 import `pkg/extension` 与 core 类型、不碰 internal；改基座 internal 的补丁一律拒绝。
+
+**INV-2 可退化不变量（退回通用智能体）。** RDM 的一切能力——命令处理器、意图规格、工作流、技能、页面、卡片、任务——以插件/声明式规格为唯一承载形态，挂在一个装载开关下。**禁用（或移除）RDM 插件时，系统行为恒等于基座发布物本身**：RDM 路由回落到普通回合、命令/页面/卡片不出现、既有通用场景全通。数据不删（下游自有库表，schemaVersion 自管迁移），重新启用即恢复可见。基座仓的任何 diff 不得出现 RDM 领域字样，评审与 CI 双重检查（见 §3.2）。
+
+**INV-3 证据与验收纪律。** 沿用 AGENTS.md「证据与验证门禁」：声明 ≠ 能力，每个里程碑的验收都是命令 × 对象 SHA × 可复核输出；任务卡、PR、证据收据随分支走；CI（PR HEAD 上 `make test`+`make build`）是测试通过的权威源。
+
+### 1.3 与库分期（基座演进线）的关系
+
+库分期（N1/Q1/I1 → N2/N3/Q2/Q3/I2）是「小队骨架执行、意图分层识别（规则→语义→LLM 的快慢分层）、恢复可靠性」的地基，**服务 RDM 但不阻塞 MS1**。它们的第一批真实消费者：
+
+- MS3 一键生成 ← Q1 图执行、Q3 编排收敛（愿景 03 F4、M10）；
+- 意图命令化与快慢分层（愿景 03 交互与意图层）← I1/I2；
+- 长任务可恢复（愿景 SR-E5/F4 长任务异步）← N3、Q1。
+
+排布原则：库分期按既定方案推进（N1 → Q1/I1 并行 → 后续），在 MS3 窗口前给出最迟合入点（§4.4）。
+
+---
+
+## 2. 现状基线（2026-10-07 实测）
+
+> **历史快照注记（2026-10-08）**：本节为 2026-10-07 撰写日快照，其中三处已随后游
+> 密集交付失效（下游功能为零、库分期进度、O1/O3/O7 阻塞）。原文保留不改写，
+> 逐行复核与现行状态见 §2.3；阅读与排期以 §2.3 为准。
+
+### 2.1 已就位
+
+| 项 | 状态 | 证据/位置 |
+|---|---|---|
+| 基座平台层 | 会话/工件/卡片/HITL/任务/审计、混合检索（向量 RAG + RRF）、PG 多租户档、认证、限流、多实例地基 | modules/backend（dual-tier 阶段 0–3 已合入） |
+| EXT-1 进程内命令处理器 + owner 作用域宿主句柄 | 已合入 main，**MS1 阻塞项解除** | Dev #207/#209；`pkg/extension/surface.txt` 含 `Handler`/`Host`/`Host.ArtifactContent`/`Host.Audit`/`Host.Complete`/`Host.KVGet` 等符号 |
+| EXT-5 宿主文档解析 | 已合入 main（含宽列修复） | Dev #222/#224 |
+| 界面形态 | 三栏 + 卡片流 + 弹出层、收件箱双现投影、交付物卡片与 docx 预览 | modules/frontend、modules/ui（与愿景 05/06 V2.2 原型一致） |
+| 下游仓 | `Agent-System-RDM` 已建仓，种子可编译（29MB 二进制），pins 落位（backend cb26e4c / core 0b5c774 / frontend 50c7244 / ui 27d5adb），8 条 deps replace 就位 | 愿景 13 建仓实录 |
+| v0.1.0 评估基线 tag | Dev / Documents / Backend / Core 等仓 tag 已打（backend 已 +4 提交） | 各仓 `git tag -l v0.1.0` |
+| v0.2.0 前置 | EXT-1 已合入；surface.txt 符号齐；EXT-1 提案已对齐 tag 名与 SurfaceVersion 2.0.0-experimental 兼容承诺 | 愿景 12 核对清单逐项可勾 |
+| 库分期 | R0/R1/R2/D1 已合入；N1 进行中（WP2/WP3 两增量 PR 已开：Agent-Native #17、Backend #69，CI 绿） | 2026-10-02 总提案 §5 |
+| 本大阶段的输入 | N1/Q1/I1 实施方案已评审合入 | Documents #40 / Dev #226 |
+
+### 2.2 缺口
+
+| 缺口 | 性质 | 影响 |
+|---|---|---|
+| v0.2.0 未发版 | owner 双钥匙动作（tag/push） | 下游升级、MS1 依赖的基座面定型；窗口 W2 末–W3 末（10-25 前） |
+| MS1 下游功能为零 | 下游开发未开始 | **当前真实关键路径**（W4=11-01，余约 3.5 周） |
+| O1/O3/O7 组织阻塞 | 评审会产出（权威文档树、标签字典、人选名单） | MS0' 退出条件；O3 阻塞 MS1 阶段映射 |
+| 库分期 N1 剩余、Q1/I1 未启动 | 基座演进 | MS3 一键生成与意图分层的前置 |
+| EXT-3 渠道未申请 | 基座扩展点（申请截止 W10 前） | MS4 飞书群入口 |
+
+### 2.3 现状复核（2026-10-08）
+
+本节为独立复核回填，不改写上文 10-07 快照。固定对象：`Agent-System-RDM` main
+`4feb2f0`（pins=四仓 v0.1.0 tag commit）。方法：`/tmp` 隔离克隆重放 + 归档任务卡与
+PR API 快照；一次性容器跑 PG 档。全部收据为 **SELF**（RDM 仓无 CI，不存在 GATE），
+收据与快照见 `docs/records/2026-10-08-rdm-status-*.json`。
+
+**§2.1/§2.2 逐行复核**：
+
+| 原（10-07） | 复核（10-08） | 证据 |
+|---|---|---|
+| EXT-1/EXT-5 已合入基座 main | 维持；但 **EXT-5 不在下游 pin**（pin=backend v0.1.0 `cb26e4c`，基座 main 已领先 83 提交） | `git submodule status` / `rev-list --count` |
+| 下游仓"种子可编译" | **已过时**：10-05~10-06 合入 103 个 PR、归档 51 张任务卡，P0–P4 各线均有首批实现 | 记录快照 pr_summary / cards |
+| v0.1.0 tag 已打 | 维持（五仓+RDM 六 tag 在位；RDM v0.1.0=`99bbf54`） | tag 核对 |
+| v0.2.0 未发版 | **维持，且为当前关键路径**：六仓远端均无 v0.2 tag（窗口 10-25 前，owner 双钥匙） | `ls-remote --tags` |
+| MS1 下游功能为零 | **失效（最严重失实）**：MS1 工作项大半已有首批——R1-2 骨架、R1-6 两速+SSE+工作台、R1-8 异步、R1-9 审计、D8 烟测、MS1 验收载具（`-ms1`）、R1-1 文档树/模板/提示词注册表大部、R1-3~R1-5/R1-7 的 F1 v1；P2（状态机/版本链/比对）、P3（追溯网/冲突/变更 UI/起草）、P4（周报/自举例程）各有超前首批 | 记录快照 cards 映射 |
+| O1/O3/O7 组织阻塞 | **已闭环**：RDM `docs/requirements/00-V2定稿决议.md`（10-06）——O1 以 ISO 13485 为主口径、O3 以种子字典为 v1（14 阶段/69 docTypes）、O7 owner 本人+系统外机制；P0 已关账（RDM #91） | RDM #89/#91 |
+| 库分期 N1 进行中、Q1/I1 未启动 | **已过时**：N1/Q1/I1/N2/N3/Q2/Q3/I2 全部合入 Dev main（转出项见 N1/Q1/I1 案 §7 回填） | 栈总案与阶段导航 |
+| EXT-3 未申请 | 维持（截止 W10 前） | proposals 目录 |
+
+**MS1 验收核对**（对 §4.2 七条；结论分级：满足=本轮重放通过 / 部分=能力在但有缺口 /
+未满足=该路径不通 / 口径不成立=判据无效）：
+
+| # | 条款 | 结论 | 证据与缺口 |
+|---|---|---|---|
+| 1 | 纪要+竞品 BP 60 秒出结论与初步归类 | **部分** | 真实纪要 0.78s 出回执（重放）；但判定=无关(疑似)零字典命中挂起，**无初步归类**；竞品 BP 无原件未测 |
+| 2 | 切片带标签锚点，笔记树视图可查 | **部分** | 标签+锚点在勾连卡可见（Linkage/Anchors）；独立笔记树视图未实现（web 无对应视图；领域 `NoteTree.Query` 存在但无 UI 消费） |
+| 3 | 无关文件存疑挂起，确认前不入库 | **满足（重放）** | 无关 txt→held；卡内挂起重启存活、reject 零切片测试 |
+| 4 | Excel/PPT 解析完整性；失败显式告知+原件可取回 | **阻塞** | 报价单 xlsx/构造 pptx→`rdm:unsupported`+留档；损坏 docx 显式告知+留档（负例路径满足）；xlsx/pptx 解析依赖 EXT-5，**不在 v0.1.0 pin**——需 v0.2.0 发版+RDM 升钉+上传链切 Host 解析 |
+| 5 | 阶段映射准确率 ≥80% | **口径不成立** | `-ms1` 报 100%（重放 PASS）但金标 `ms1Gold` 与自举打标 `docProfiles` 同表同源（代码注释自认），样本 5 文档全 BD 阶段；上传路径实测纪要零命中——准确率未经有效测度 |
+| 6 | 页面/对话双入口同源 | **未满足（钉入组合）** | 命令入口 200；对话入口发 `/rdm.ping` 得 400"未知命令"（插件命令注册不写 slash 别名，v0.1.0 与基座 main 同）；RDM 未声明 intents；另发现工作台 `sendChat` 调 `/api/chat`——该端点在 v0.1.0 pin、基座 main、RDM 三处均不存在（自由文本 404） |
+| 7 | PG 多用户档身份贯通 | **满足（重放）** | 一次性 PG 容器重放 pg-smoke：alice/bob 审计与知识各 1、零串号；multi-smoke 跨实例扇出+Redis 限流 PASS |
+
+**MS1 整体判定：部分满足，不可签收**。关键路径从"下游从零开发"变为：v0.2.0 发版
+（双钥匙）→ RDM 升钉 → 上传链切 `Host.ParseDocument`（第 4 条）；对话入口路由插件
+命令（第 6 条，需基座侧动作）；准确率金标独立化重测（第 5 条）；笔记树视图补齐（第 2 条）。
+
+**新缺口登记**（本轮只登记不修复；逐项带证据、影响、建议承接与归属）：
+
+| 缺口 | 证据 | 影响 | 建议承接 | 归属 |
+|---|---|---|---|---|
+| 插件命令无 slash 别名，对话入口不可达插件命令 | entrance2 收据（400/200 对照）；`cmdbus.RegisterPluginCommand` 不写 `b.slash`（v0.1.0 与基座 main 相同） | MS1 第 6 条、R3-6 四入口同源 | 基座侧：扩展申请或并入既有 EXT 案（含 intents 命中插件命令的路由） | weichen |
+| RDM 工作台自由文本端点错误（`/api/chat` 不存在） | entrance 收据 404×2；基座前端实际用 `/api/conversations/{id}/messages` | 工作台自由文本路径不可用 | RDM 侧小任务（改端点） | weichen |
+| INV-2 可退化机制未实现（装载开关、禁用态 e2e、基座领域词守护均无） | 两侧 grep 零命中；成因：RDM 10 号 V1.2 定稿（10-05）早于本总案 INV-2（10-07） | §3.2 判定四条均 NOT_RUN | 下游任务（开关+禁用态 e2e）+ 基座守护另行立项 | weichen |
+| 阶段映射准确率无有效测度（金标同源、样本全 BD） | `ms1.go` ms1Gold vs `bootstrap.go` docProfiles 对照 | MS1 第 5 条、MS2 质量基线 | 独立金标集+多阶段样本重测任务 | weichen |
+| RDM 仓无 CI | 仓内无 `.gitea/workflows`；PR status API 无 statuses | INV-3 的 GATE 来源不存在，下游证据止于 SELF | RDM 仓接 act_runner（同基座模式） | weichen |
+| 22 张归档卡「结果与验证」段为模板占位 | grep 模板串 22 命中；结论写在 PR 描述（抽样 6/6 含验证） | 台账完整性 | 低优先：随下一批 RDM 任务补齐或接受现状 | weichen |
+
+本节维护规则：状态再变化时先更新本节（或其后续修订版），并同步索引导航；
+复核不等于里程碑验收，MS2–MS4 的正式验收仍按 §4 各自条款执行。
+
+---
+
+## 3. 架构裁定
+
+### 3.1 二次开发的承载形态（三级，主辅保留）
+
+| 级 | 形态 | 用在哪 |
+|---|---|---|
+| A 进程内编译（主） | 下游仓 import `pkg/extension` + core，实现 EXT-1 `Handler` 命令处理器、`Host` 句柄消费（KV/audit/llm/knowledge search+write(embed)/tasks 台账/artifacts）、页面 SDK | RDM 命令（上传管道、入库、生成、变更）、知识写入、结构事件日志、页面 |
+| B 声明式规格（辅） | intents / workflows / skills / 页面规格文件，插件目录装载 | RDM 意图（闲聊/澄清/取消等命令层消费）、流程骨架 YAML、技能 |
+| C sidecar（保留） | 独立进程，经命令总线/工具被调 | 格式解析器（office/xlsx 深解析）、EXT-3 渠道执行体 |
+
+**裁定**：能用 A 就不用 C；解析器默认走「sidecar 工具或 LLM 抽取」，EXT-4（进程内解析器注册）不提交（愿景 10 §1.5）。
+
+### 3.2 可退化机制（INV-2 的工程形态）
+
+**装载开关**：RDM 插件的一切装载点——命令 Handler 注册、意图 spec、工作流定义、技能目录、页面路由、卡片投影——收在一个开关下（建议设置键 `plugins.rdm.enabled`，默认开启；缺省/禁用 = 通用基态）。禁用语义是**装载期跳过**，不是运行时逐点判断：装载器在开关关闭时不注册任何 RDM 项，路由自然回落到基座既有 fallback（普通回合）。
+
+**通用基态的判定**（机器可核对）：
+1. 禁插件启动后，通用场景 e2e 全绿（对话、工具、工件、卡片、HITL、工作流 demo 插件）——复用 backend 现有 e2e 套件在禁用态重跑；
+2. RDM 命令返回未知命令、RDM 页面 404、收件箱无 RDM 投影卡；
+3. 基座仓 diff 检查：任何 PR 的基座改动不含 RDM 领域标识（词表黑名单进 design-guard 类守护，或评审核对项）；
+4. 数据共存：禁用不触发任何删表/删数迁移；重新启用后 RDM 视图恢复原状（下游测试覆盖）。
+
+**测试形态**：下游仓测试套件固化「禁用态 e2e」一项；基座 CI 天然成立（基座不依赖下游，永远可独立构建测试）。
+
+### 3.3 扩展点申请流程（缺口 → EXT）
+
+下游发现基座面缺口时的唯一合法路径（愿景 10 §七.1）：
+
+1. 下游在任务卡里写明缺口（要的符号、语义、阻塞什么里程碑）；
+2. 基座侧建 EXT 申请卡 → 评审（是否属于通用能力、SurfaceVersion 影响）→ 基座实现并随下一段发版（v0.2.0 之后按 v0.3.0/v0.4.0… 节奏，同样走 12 号清单核对）；
+3. 下游升级动作：pins bump + go.mod replace 切回 tag pin（合入前必须切回，愿景 13）。
+
+已在案的扩展点：EXT-1（已落地）、EXT-3（渠道，W10 前申请，阻塞 MS4）、EXT-4（备选，默认不提交）。预计 MS1–MS3 期间可能出现的新需求（知识写入完整集、页面 SDK 增补、审计结构事件扩展）按本流程逐案评审，不预设全部进基座。
+
+### 3.4 数据模型落地裁定
+
+- 两树一网（笔记树/文档树/追溯网）在下游自建库表、schemaVersion 自管迁移（D-R1 选 A，愿景 10）；基座 core 不加领域实体。
+- **R3-1 结构事件日志最先做**（愿景 10 §五：「追溯网地基」，SR-G5 五硬规则：原文 append-only、软删除、边候选→生效→废止、统一结构事件日志、时间点可重建）。裁定：下游自管事件日志与重放，基座通用审计接口（`Host.Audit`）只写动作审计，不为结构追溯进基座。
+- 标签字典是两树唯一接口语言（愿景 08 §四）；字典实体为项目级资产、版本化，住下游；其字段集与取值枚举依赖组织项 O3，MS1 前先以草案字典起步（见 §5 风险 R-1）。
+
+---
+
+## 4. 阶段方案（里程碑对齐）
+
+每阶段给出：下游工作项 / 基座支撑项 / 组织依赖项 / 验收（机器可核对）。编号 R 沿用愿景 10。
+
+### 4.1 阶段 P0：MS0' 收尾与发版（W1–W3，当前窗口）
+
+- 下游：R0 奠基——文档树模板注册表骨架（阶段→文档→章节）、UR/SR 条目化导入需求大表雏形、建仓自检（`go test .` + link 构建）随仓常驻；奠基文档（方案 10）已就位。
+- 基座：v0.2.0 发版（owner 双钥匙，按愿景 12 清单：core 三处同 SHA、五仓 tag 指向一致、tag 消息固定文案）；N1 合入链走完（Agent-Native #17 → Backend #69 → Dev gitlink PR）并完成 N1 剩余（WP1 AgentSpec、WP4 guardrail、WP5 下沉、WP6 装配与 A/B）。
+- 组织项（MS0' 退出条件，非代码）：01 升 V2.0 定稿；O1/O3/O7 决议闭环；D-R1/D-R2 决议在案；EXT-1 申请卡已受理（已合入可视为闭环）；code review 机制首运行台账。
+- 验收：v0.2.0 五仓 tag 就位且指向一致（命令：各仓 `git tag` + Dev gitlink 比对）；N1 三段 PR 合入且 CI 绿；下游种子构建通过。
+
+### 4.2 阶段 P1：上传五步法 + 两速入库（W4 = MS1，11-01）
+
+上传五步：接入 → 相关性判定 → 结构化解析 → 阶段映射与标签 → 两速入库（愿景 03 F1、04 T1-x、10 §三）。
+
+| 工作项 | 内容 | 承载形态 |
+|---|---|---|
+| R1-1 上传接入 | 复用基座工件/上传端点；渠道记录（SR-A3）留 P1 后 | A（下游命令） |
+| R1-2 相关性判定 | 三态（相关/不相关/存疑），存疑挂起确认前不入库（SR-B1） | A |
+| R1-3 结构化解析 | 拆解为切片：原文锚点 + 结构化字段；office 深解析走 sidecar 工具或 LLM 抽取（EXT-4 不提交） | C 辅 |
+| R1-4 阶段映射与标签 | 按标签字典映射阶段/工作事项/主题簇，生成标签 JSON（M3 schema）；字典草案先行，O3 闭环后替换 | A + 字典资产 |
+| R1-5 两速入库 | **快通道**：60 秒首轮反馈——标签、锚点、一句话摘要即时可见；**慢通道**：向量与深度补齐异步走 EXT-1 `KnowledgeWrite(embed)` 句柄（意图分层「快规则/慢模型」之外产品的第二条快慢线） | A（慢速经 EXT-1 句柄） |
+| R1-6 入库完整性 | 失败显式告知、原件可取回、禁静默降级（SR-A5）；三类负例（报价单 Excel/图文 PPT/构造解析失败）回归 | A + 测试 |
+
+- 基座支撑：v0.2.0 已发版（前置）；`Host` 完整集（含 artifacts 写入）如 MS1 实测不足，走 §3.3 申请进 v0.3.0。
+- 验收（对齐愿景 10 §三 7 条）：上传五步法端到端跑通（三类真实文件）；60 秒首轮反馈实测；存疑挂起确认前库中无记录；标签+锚点在界面可见；SR-A5 三负例回归；**SR-E6 双入口同源早期证据**（页面/对话两个入口同一命令处理器实测）；PG 多用户档身份贯通烟测（D8）。
+
+### 4.3 阶段 P2：基线 + 三分类 + 版本链（W7 = MS2，11-22）
+
+- 下游：文档状态机（草稿→评审中→已基线→变更中→新版本）；三分类比对引擎（新增/更新/冲突）；版本链可溯；基线直改被拒；缺项提示只在评审/推进两触发点出现（SR-C5，上传节点禁止）。
+- 基座：无新需求预期；卡片/HITL 复用。
+- 验收（10 §四 R2-1~R2-5）：状态机迁移合法集测试；三分类对同一文件两版比对正确分类；版本链从任一章节回指到切片锚点；基线直改返回结构化拒绝；上传节点界面无缺项提示。
+
+### 4.4 阶段 P3：两树一网 + 变更闭环 + 一键生成（W11 = MS3，12-20）
+
+| 工作项 | 内容 | 依赖 |
+|---|---|---|
+| R3-1 结构事件日志 | **最先做**：SR-G5 五硬规则全落地；时间点可重建（事件重放 + 周期快照） | 无（下游自管） |
+| R3-2 追溯网 | 切片↔需求↔章节↔法规↔用例 有向边；模型候选边人工转正 | R3-1 |
+| R3-3 需求大表 | UR/SR 版本化条目；变更风险提示 | R3-1 |
+| R3-4 变更闭环 | 检测→影响分析→变更单七步→回写留痕；影响已基线内容的结构变更强制走变更流程 | R3-2 |
+| R3-5 一键生成 | 编写意图确认→小队骨架执行→逐节标源（无素材明示空缺不编造）；一拉一推（章节条件检索笔记树 / 切片标签映射文档树） | **基座 Q1/Q3、I1**（小队骨架与意图命令化）；标签字典 |
+
+- 基座支撑（**最迟合入窗口：W9 末**）：Q1 图执行合入、I1 命令化合入（退化路径：R3-5 先用流程骨架 YAML + 现有小队 standard 模式实现，不强等 Q3 编排收敛；该降级在愿景 03 F4 允许范围内，需任务卡明示）。
+- 验收（10 §五）：结构事件日志对两树一网增删改全程留痕且可重建指定时点；变更七步闭环跑通一次真实变更；一键生成产出的每个章节带切片级来源标注，无素材章节明示空缺；追溯链报告可导出。
+
+### 4.5 阶段 P4：自举与演示（W16 = MS4，2027-01-24）
+
+- 下游/联合：自举 B1–B7（元项目常驻 → 纪要入库 → 本批文档入库 → UR/SR 全部进需求大表 → 一句话生成自身可行性报告 V1 → 用系统管本计划执行 → 每周复盘）；EXT-3 渠道（飞书群收文件/推送，申请截止 W10 前，基座实现随当段发版）；测试群反馈闭环率 ≥80%。
+- 基座支撑：EXT-3（W10 前受理）；N2/N3/Q2 按实际拖累点排期；I2 语义端口（意图慢通道）如被意图误触发率卡脖子则提前。
+- 验收：自举项目全程在系统内运行（纪要入库→可行性报告→追溯链导出，无系统外补录）；反馈闭环率统计达标；owner 认定可对外演示。
+
+---
+
+## 5. 风险与缓解
+
+| # | 风险 | 缓解 |
+|---|---|---|
+| R-1 | MS1 时间紧（余约 3.5 周）且 O3 标签字典是组织阻塞 | 字典草案先行（下游资产、可迭代）；O1/O3/O7 列入 MS0' 评审必须产出的一句话（愿景 11 阻塞项表），评审前下游不赌字典内容 |
+| R-2 | 一键生成依赖基座 Q1/Q3 进度 | 设 W9 末最迟窗口 + 降级路径（YAML 骨架 + standard 模式，§4.4）；库分期优先级因此把 Q1 排在 N2/N3 之前 |
+| R-3 | 可退化不变量被侵蚀（领域逻辑渗入基座） | INV-2 的装载点集中 + 禁用态 e2e（下游常驻）+ 基座 diff 领域词黑名单检查（进评审核对项，必要时落 design-guard 类守护） |
+| R-4 | 双仓 pin 漂移 / replace 忘切回 tag | 愿景 13 规则进下游 AGENTS.md；基座 R0 检查脚本已核对 backend deps 与 Dev 指针；下游 pins 自检进 CI |
+| R-5 | EXT 申请节奏跟不上下游需求 | 缺口提前在任务卡登记（§3.3 第 1 步），发版节奏按里程碑倒排（v0.3.0 对准 MS2/MS3 之间） |
+
+## 6. 不在本方案范围
+
+- 医院端产品与行业输出的远期步（愿景 02 §7 路径第 ③④ 步）。
+- 模型无关性的完整抽象（SR-N5，P2 远期）；token 成本测算口径（待组织认可，愿景 11 #14）。
+- 微信等飞书以外的渠道（前瞻）。
+- 下游仓内部的详细任务分解（本方案是总案；下游按 §4 的阶段在 RDM 仓立各自任务卡，引用本文）。
+
+## 7. 验收（本文）
+
+- 大方向与三条不变量（INV-1/2/3）表述无歧义，可落成检查项。
+- §4 五阶段与愿景 10 §10.1 里程碑逐条映射；每阶段验收均为机器可核对形式；组织项与代码项分列、不混淆。
+- 可退化机制（§3.2）给出判定与测试形态，能直接派生下游测试任务。
+- 与既有方案无冲突：库分期按 2026-10-07 N1/Q1/I1 方案继续；本文只在其上排布消费者与窗口。

docs/proposals/2026-10-08-ext-c1-c7-rdm-shared-contracts.md

@@ -0,0 +1,166 @@
+# EXT 申请包 · C1–C7：RDM 多人共享契约的基座最小扩展（EXT-6…EXT-12）
+
+| 项目 | 内容 |
+|---|---|
+| 状态 | proposed（2026-10-08）；owner：weichen；任务：Dev `feature/ext-c1-c7-applications` |
+| 性质 | 扩展点申请包（extension-compat-policy 流程第 2 步：基座侧评审）。**本文只立申请，不实施**；各 EXT 实现另立任务卡 |
+| 需求依据 | RDM 仓 U0 主记录 `docs/proposals/2026-10-08-U0-baseline-and-shared-contracts.md` §5 契约 C1–C7（RDM main `ca72cfc` 已合入，含 D1–D9 裁定）；来源=用户 2026-10-08 会话批准的 U0 实施计划 |
+| 现状证据 | 均为 SELF·源码级，引用对象：Dev `34a2bbe`（backend gitlink `fe7c245`）；RDM pin backend `cb26e4c`（v0.1.0）相同结论者已注明。运行态 NOT_RUN |
+| 编号 | 按既有序列（EXT-1/3/4/5 在案）顺延 **EXT-6…EXT-12**；最终编号以受理评审为准 |
+
+## 0. 总则
+
+- **推荐路线**（U0 裁定 D1，修订 V2.1 草稿 J-09「基座不改动」）：领域规则（成员、角色、三权、
+  发布状态）住 RDM 下游仓；基座只补**通用、无领域词汇**的最小扩展面。每条申请遵守 INV-2：
+  基座代码与 diff 不出现 RDM 领域字样，全部以「资源授权/受管配置/投影过滤」等通用语义表述。
+- **事实依据（为何纯下游组合不出来）**：基座一切资源访问按 owner 硬边界
+  （`internal/store/projects.go:22-34`），EXT-1 Host 强制 owner 归属且**无知识删除/更新**
+  （`pkg/extension/host.go:43-46`、`internal/app/hostcaps.go:101`）。RDM 增加成员表不能改变
+  基座过滤；给每人复制知识库被 U0 §4 明确禁止。
+- **SurfaceVersion 影响**：EXT-6/7/9 触及 `pkg/extension` 导出面（Registry/Options/Host 方法），
+  属加法变更——按 extension-compat-policy 升 SurfaceVersion（2.0.0-experimental 内加法，
+  surface.txt 同步）；EXT-8/10/11/12 为 internal/HTTP 行为扩展，不动导出面。
+- **分期建议**（对齐 U0 §10）：EXT-8（授权适配器）与 EXT-9（索引发布）为序 4「项目范围与
+  授权基础」的硬前置；EXT-6/EXT-12 支撑序 4–5；EXT-7/EXT-10 可随后。EXT-8 建议最先评审。
+- **通用默认不变量**：每条扩展的缺省行为=现状（未注册/未配置时与今日基座完全一致），
+  RDM 产品部署显式启用；通用基座与既有下游不受影响。
+
+---
+
+## 1. EXT-6（←C1）可信身份：账号停用与会话吊销
+
+- **场景**：RDM R01 唯一管理员移交后旧凭证须立即失效；成员移除同理。现状基座账号只有
+  创建/改密/列表（`internal/server/accounts.go:184-261`），无停用语义，撤销账号后其 API key
+  与会话仍有效到自然过期。
+- **期望公开面**：①`POST /api/admin/users/{owner}/disable|enable`（requireAdmin 保护）；
+  ②users 表加 `disabled` 布尔（迁移，default false）；③认证链（API key 校验与会话校验，
+  `internal/server/auth.go:29-64`）与 `requireAdmin` 拒绝 disabled 账号并吊销其在途会话。
+  「全局唯一管理员」由 RDM 产品策略约束（部署约定+台账），不强制基座单管理员。
+- **为何组合不出**：无任何现有端点或设置键能改变账号认证状态；RDM 无法经 EXT-1 Host 触达
+  认证层（Host 无账号域能力，也不应有一—属平台面）。
+- **兼容方式**：纯加法（新端点+新列 default false）；未停用=现状。SurfaceVersion 不变
+  （不动 pkg/extension）。
+- **验收**：停用后该账号 API key 与 cookie 即刻 401；管理员功能不受影响；启用可恢复。
+
+## 2. EXT-7（←C2）受管系统配置：最终生效值受策略约束
+
+- **场景**：RDM R01——模型端点/密钥、工具上限、系统插件由管理员控制；个人偏好保留。现状
+  设置链 `defaults → system(启动注入) → user → project`（`internal/settings/settings.go:131-147`），
+  user/project 可覆盖一切；system 层不落库且组合根只注入 dataDir
+  （`internal/app/app.go:130`）——只藏设置页或只禁今后写入都处理不了既有覆盖。
+- **期望公开面**：①`extension.Options` 增受管注入：`ManagedSettings map[string]any`（键集+
+  值，由宿主二进制启动注入）；②设置服务按受管键集跳过 user/project 覆盖（Effective 尊重
+  策略）；③受控键的 user/project 写入返回结构化拒绝并附依据；④`GET /api/settings` 标注
+  哪些键受管。RDM 在自有二进制 main 里以管理员配置注入。
+- **为何组合不出**：Options 无注入口；`SetSystemOverride` 是组合根私有；下游无法让 Effective
+  忽略 user/project 的既有覆盖。
+- **兼容方式**：`ManagedSettings` 缺省 nil=现状（无受管键，行为不变）；pkg/extension Options
+  加字段=导出面加法，SurfaceVersion 与 surface.txt 同步升。
+- **验收**：预置 user 覆盖的受控键，注入策略后生效值=受管值；普通用户写受控键被拒且
+  `GET /api/settings` 可解释；未受管键的个人偏好不受影响。
+
+## 3. EXT-8（←C4）资源授权适配器：项目共享的读取通道 ⭐关键路径
+
+- **场景**：RDM R03/R04/R05——成员 B 依 RDM 成员表读取成员 A 提交的项目资料（工件原件、
+  检索、引用、下载、图查询）；撤销后停止。现状一切资源入口按 owner 过滤
+  （`internal/store/projects.go:22-34`；工件/知识/卡片同理），Host 读取族同样强制本人
+  owner（`pkg/extension/host.go:43-46`）。
+- **期望公开面**：①基座提供**授权适配器注册点**（HTTP 组合根）：`RegisterResourceAuthorizer(
+  func(owner, resourceProjectID core.ID) (allow bool, err error))` 形态的进程内回调，经
+  `extension.Options` 或 Registry 注入（具体挂点评审定）；②资源入口（项目/工件/知识检索/
+  卡片读取的 HTTP 层与 Host 读取族）在 owner 自有判定未命中时回调适配器：返回 true 则按
+  「项目共享」放行，false/未注册=现状 NotFound（不泄露存在性）；③适配器只回答布尔，
+  不接触基座内部状态；④放行日志入审计（owner×resource×decision）。
+- **为何组合不出**：owner 过滤在 SQL 层硬编码；无任何回调或配置可改变跨 owner 可见性；
+  回环 HTTP 模拟他人身份被认证中间件阻止（V1.1 教训，10 号方案已证）。
+- **兼容方式**：未注册适配器=现状零差异；回调失败按拒绝（fail-closed）。pkg/extension
+  加法→SurfaceVersion 升。**注意**：本 EXT 使基座首次具备跨 owner 授权读取语义，评审须
+  重点核对回调契约的最小性（仅 owner×projectID 两参，不透出对象细粒度——细粒度由 RDM
+  在自己的命令层做）。
+- **验收**：同项目两人+另一项目一人（RDM 成员表桩）：共享资源四入口（原件/检索/引用/下载）
+  一致放行；跨项目与替换引用拒绝且 NotFound 不泄露；撤销成员后新访问立即拒绝；审计可查。
+
+## 4. EXT-9（←C5）索引发布与撤销：留存 ≠ 可检索
+
+- **场景**：RDM R07——存疑资料确认前不得进入任何正式检索；发布有稳定版本、撤销即时生效。
+  现状基座上传端点在下游相关性判定**之前**即写检索索引
+  （`internal/server/server.go:1039-1046`；RDM pin 相同）；Host 知识面只有
+  `KnowledgeWrite`（强制 owner），无删除/更新（`pkg/extension/host.go:43-46`）。
+- **期望公开面**：①基座上传预索引开关（`Options` 或项目设置键 `uploads.autoIndex`，缺省
+  true=现状；RDM 部署关闭，索引决定移交其命令层）；②Host 增 `KnowledgeDelete(owner,
+  sourcePrefix string, versions …) / KnowledgeUpdate`（或等价发布令牌语义：写入带稳定
+  `PublishID`，删除按 PublishID 幂等）；③删除仅作用于插件来源（`Source` 前缀
+  `plugin:<id>`），公共 manual 来源不可被插件删。
+- **为何组合不出**：检索索引无删除面；上传索引行为硬编码；RDM 无法撤回已入索引的存疑内容。
+- **兼容方式**：开关缺省现状；Host 删除方法为导出面加法（surface.txt/SurfaceVersion 同步）。
+- **验收**：相关/存疑/拒绝三份样本：仅获准发布版本可检索；重试不重复建索引；撤销后检索与
+  上下文注入立即停止（含 Host 读取族）；manual 来源不可删。
+
+## 5. EXT-10（←C3）分发前校验钩子与会话归属
+
+- **场景**：RDM R18——对话/按钮/卡片/API 四入口同源且对象-会话-项目关联可校验；旧卡片/
+  重复确认不得操作新版本。现状 `POST /api/commands/{id}` 不校验 conversationId 归属
+  （`internal/server/server.go:823-836`），确认卡锚定客户端自报会话
+  （`internal/cmdbus/cmdbus.go:294-316`）；插件命令注册不写 slash 别名，对话入口不可达
+  `rdm.*`（`cmdbus.go:145-153`，v0.1.0 与 main 同——阶段总案 §2.3 已登记）。
+- **期望公开面**：①分发前校验钩子：`RegisterDispatchGuard(func(owner, conversationID string)
+  error)`（未注册=现状放行；RDM 注入「会话属该项目且属于该 owner」判定）；②
+  `RegisterPluginCommand` 增可选 slash 别名参数（或 manifest 字段），对话入口 `/rdm.*`
+  可解析；③别名与 intents 命中路由到插件命令的打通（阶段总案既有缺口，并入本 EXT 或
+  单列由评审定）。
+- **为何组合不出**：execCommand 对 conversationId 零校验也无回调点；slash 表只由内置与
+  用户命令登记写入（`cmdbus.go:109-127`），插件路径不写。
+- **兼容方式**：钩子/别名均缺省=现状；internal 行为扩展为主（Registry 签名若变则属
+  pkg/extension 加法，SurfaceVersion 升）。
+- **验收**：伪造他人会话/项目引用的命令被拒；`/rdm.ping` 在对话入口可达且回执与按钮入口
+  同源（同一审计信封）；陈旧卡片确认不生效（既有 ErrNotAwaiting 之上叠加对象版本校验）。
+
+## 6. EXT-11（←C6）按 owner 重建受限 Host：后台任务恢复
+
+- **场景**：RDM R10/R21——慢任务跨重启不丢不重；撤权后不越权续跑。现状 RDM 慢通道是进程
+  内存队列并把分发时 Host 句柄留在队列（RDM `internal/rdmapp/slow.go:53,66`，重启即丢、
+  撤权不重验）；基座任务台账仅记账（`pkg/extension/host.go:48-50`）。
+- **期望公开面**：基座侧缺口小——提供「按 owner+pluginID 构造受限 Host」的公开工厂
+  （如 `extension.NewScopedHost(owner, pluginID)` 形态或 Registry 上的查询），供下游在
+  恢复任务时重建执行上下文；任务体、输入版本、幂等与重验策略由 RDM 自管（U0 §7）。
+  **不序列化旧 Host**——重建受限上下文，天然以当前权限为准（配合 EXT-8 的授权适配器，
+  撤权即拒绝）。
+- **为何组合不出**：inprocHost 是 internal 类型按分发请求私有构造
+  （`internal/app/compiled.go:42`）；下游无任何入口可在分发期之外获得合法句柄。
+- **兼容方式**：纯加法工厂函数；不改变分发期语义。pkg/extension 加法→SurfaceVersion 升。
+- **验收**：下游以工厂重建的 Host 执行读/写，owner 作用域与分发期一致；重启后同任务不重复
+  执行（RDM 侧幂等）+ 撤权后重建 Host 的读取被适配器拒绝。
+
+## 7. EXT-12（←C7）卡片/事件投影过滤：私人事件与公共投影分离
+
+- **场景**：RDM R04/R18——私人会话卡不得进项目公共流；公共投影只含获准发布的状态；撤权
+  后重放不泄露。现状会话卡**全量镜像**到项目频道（`internal/cardsvc/cardsvc.go:41-60`，
+  注释自述「全量镜像换取口径简单」）——单 owner 下无害，多人项目即隐私泄露路径。
+- **期望公开面**：卡片镜像策略可配置：①按卡属性过滤（kind/来源）的内置开关，或②复用
+  EXT-8 适配器语义的投影可见性回调（`func(owner, card) bool`）——评审择一，倾向①最小。
+  RDM 部署关闭会话卡镜像，只用项目级卡承载公共投影。
+- **为何组合不出**：emitCard 镜像逻辑硬编码；无配置面。
+- **兼容方式**：缺省=现状全量镜像；internal/设置键扩展，不动导出面。
+- **验收**：关闭镜像后会话卡仅出现在本人会话流；项目流只含项目级卡；既有单用户部署行为
+  不变；SSE 重放遵循同一过滤。
+
+## 8. 不在本申请包（显式排除）
+
+- 需求条目化/模板/法规双通道/三权流程等 RDM 领域能力（U0 §2 R08–R16）——全部住下游。
+- 飞书渠道 EXT-3：既有在案申请，节奏不变（MS4 前）。
+- 命令审计跨租户修复：**不是扩展**，是缺陷修复，已另行（Backend PR #104 + Dev PR #262）。
+
+## 9. 受理建议
+
+| EXT | 前置的 U0 序 | 建议评审优先级 | SurfaceVersion |
+|---|---|---|---|
+| EXT-8 授权适配器 | 序 4 硬前置 | **P0 最先** | 升（加法） |
+| EXT-9 索引发布/撤销 | 序 4 硬前置 | P0 | 升（加法） |
+| EXT-6 账号停用 | 序 4–5 | P1 | 不变 |
+| EXT-11 Host 工厂 | 序 4 | P1 | 升（加法） |
+| EXT-10 分发守卫/别名 | 序 3 剩余半边（基座侧） | P1 | 视形状 |
+| EXT-7 受管配置 | 序 4–5（R01） | P2 | 升（加法） |
+| EXT-12 投影过滤 | 序 5 | P2 | 不变 |
+
+每条受理后按 extension-compat-policy 走「基座任务卡实现→发版→RDM 升钉」；预计随 v0.2.0
+之后的 v0.3.x 分批落地（对齐 RDM 阶段总案 §3.3 与风险 R-5）。

docs/proposals/2026-10-09-agent-quality-improvement-plan.md

@@ -0,0 +1,86 @@
+# 智能体工作流质量改进：诊断、裁定与分期计划
+
+状态：**已获实施授权（2026-10-09，六项裁定见 §3）**；owner：weichen；
+主任务：Dev 仓 `feature/agent-quality-phase01`（Phase 0+1 首个增量）。
+撰写日期：2026-10-09。诊断依据：dev 实例真实运行转录（PG pg1 13 次 run + 旧
+SQLite 53 次，共 62 条助手消息、263 次工具调用；模型 MiniMax-M2.7-highspeed，
+direct 入口），对照本机 ZCode v3.14.3 源码与 codex/opencode/pi/Kimi CLI/Cursor
+公开资料（2026-10-09 抓取）。诊断证据级别 SELF（本地观察与复算）。
+
+本文件是该改进方向的主记录：目标、裁定、分期与验收以本文为准；
+各阶段实施细节与结果记在对应任务卡，不回写复述。
+
+---
+
+## 1. 问题陈述
+
+与 codex / pi / kimi / cursor / zcode / opencode 相比，本系统直连对话路径在
+「工作细致、详细、完善」上存在可测差距。真实转录中定位到的失败链（均已复核）：
+
+1. **信息逐轮衰减**：跨轮上下文由界面消息有损重建——工具结果只回放 160 字
+   摘要、参数截断、二进制原件占位、思考内容丢弃；上传材料只在「本轮」注入。
+   后续轮次在摘要的摘要上工作，细节靠编造补齐（实测：「详细方案」中 85%/95%
+   准确率、8000–10000 字等数字在原始转录中不存在；日期星期错配）。
+2. **修改模型倒挂**：交付物由一次性整段生成脚本产出（docx 无源文件），任何
+   修改=整篇重写重跑（实测一轮 24 次工具调用 9 次失败、6KB 脚本重跑 8 次）。
+3. **检查失效且误报**：终轮评分的 lint 子进程无 PYTHONPATH 而静默失败（同一
+   docx 带 PYTHONPATH 9 个 error，评分器里 0 个）；终轮检查重评已被替代的旧
+   工件导致死循环；可读性规则把表格单元格「项目概述撰写」判成栏目式标题；
+   历史工件渲染格式 `[产出工件 …]` 与伪造标记检查同形，模型照抄即被拦。
+4. **最终答复与事实脱节**：composeFinal 只见 160 字摘要，产出了不存在的章节
+   列表和「我会调整后再提交」类未兑现承诺。
+5. **过程性根因**：无任务级评测。任务卡验证=单测+mock，真实模型被列为非目标；
+   evalgold 只有 1 条规则，eval/ab.go 无运行记录。
+
+## 2. 根因归纳（按影响排序）
+
+1. 上下文保真度不足（影响最大）——产品没有把内核的追加式会话记录当权威上下文。
+2. 工具与修改流程不适合交付物领域——没有「读源码→精确改→编译→看诊断」的对应物。
+3. 质量控制是事后把关而非让模型自己做好，且把关本身不可靠。
+4. 行为指引薄弱（何时建计划/失败换路/坚持到完成），工具描述只有一行。
+5. 没有以真实模型结果为准的评测回路。
+
+内核能力（read/edit/grep/glob、超长落盘、压缩、会话树）大多已在 agent-native
+就位，问题主要在产品组装层（`modules/backend/internal/runtime|ctxasm|quality`）。
+
+## 3. 用户裁定（2026-10-09，授权实施）
+
+| # | 事项 | 裁定 |
+|---|---|---|
+| 1 | 直连对话开放工具与能力 | **开放，尽可能实现和开放所有的工具和能力**（推翻 2026-09-30 预览案「fs 工具实现但不默认提供」的默认关闭裁定） |
+| 2 | 跨轮上下文以内核会话记录为准 | **同意**（重新生成/排除/回滚映射为会话树分支操作） |
+| 3 | 交付物 Markdown 源码化 + 构建器 | **可以，但必须保留生成各类文件（docx/xlsx/pptx/pdf/图片等）的能力** |
+| 4 | composeFinal 与关键词评分降级 | **按建议**：Phase 2/3 落地后 composeFinal 默认关闭（仅异常兜底）；关键词评分移出拦截路径、只作评测指标 |
+| 5 | 更强模型评测 | **可以，预算无上限** |
+| 6 | 行为面改动须附真实模型评测 | **按建议**：写入 Dev 仓 policy/delivery.md |
+
+## 4. 分期与验收
+
+每阶段独立任务卡 + PR；改动提示词/工具/上下文/门禁的 PR 须附 eval/live
+真实模型前后对照（裁定 6）。评测口径：`modules/backend/eval/live/`
+（golden 任务集 + 指标：工具失败率、整篇重跑数、是否读原件、计划使用率、
+检查误报/死循环、终轮与工件一致性、未核实数字）。
+
+| 阶段 | 内容 | 验收 |
+|---|---|---|
+| **P0 评测基线** | eval/live 运行器 + tasks.json + 指标报告；before/after 各跑一次 | 基线报告能复现 §1 失败链 |
+| **P1 缺陷修复** | §1.3 的检查失效与误报七项 | 检查误报清零；两条死循环链消失 |
+| **P2 上下文保真** | 内核会话记录为权威跨轮上下文；窗口按模型真实窗口（token，实测校准）；被清结果落盘留路径+预览；上传材料持久 `inputs/*.md`；交错思考模型回传 `<think>`；接上 9 段压缩模板 | 后续轮 100% 读原件；「更详细」不整篇重写；未核实数字显著下降 |
+| **P3 工具开放 + 交付物源码化** | 内核 read/edit/grep/glob 接入直连（沙箱=会话工作区）；交付物 = Markdown 源文件 + `housestyle.build` 确定性渲染（自动 lint，诊断指向源行）；写入即诊断；`housestyle.api` 签名查询；保留 run_python 全类型生成能力（裁定 3） | 工具失败率 ≤8%；修改请求整篇重建 ≤1 次；API 幽灵调用消失 |
+| **P4 行为指引** | 基座提示词「工作方法」段（建计划/失败两次换路/先查 API/坚持到完成/结论先行终稿）；重写高频工具描述；计划提醒常开；按模型分提示词（先 MiniMax） | 多步任务计划使用率 ≥80%；终稿承诺未兑现清零 |
+| **P5 门禁精简** | 拦截型检查只留硬事实（工件存在/lint 零 error/引用存在）；新增事实一致性检查（数字/日期/人名回溯材料）；验证器按需触发+异模型 | 检查死循环 0；未核实数字显著下降 |
+| **模型 A/B** | 同一评测集换更强主模型对照（裁定 5，无预算上限） | 区分模型与 harness 各自的贡献，输出选型建议 |
+
+## 5. 不在本文范围
+
+- 操作系统级沙箱、多租户隔离策略（沿用现状与既有声明）。
+- 小队（squad）路径的同批改造——先修直连主路径，squad 经 A/B 对照跟进。
+- AGENTS.md/DESIGN.md 层面的仓库治理变更。
+
+## 6. 记录与证据
+
+- 诊断细节与复现命令：2026-10-09 会话记录（本文件只留结论与指针）。
+- before 基线：`eval-live/before-main-1ebd46e.json`（任务卡 evidence 引用）。
+- 关联：[Agent 栈总案](2026-10-02-agent-stack-completion.md)（库分期不受本文影响）、
+  [文件预览与保留能力](2026-09-30-file-preview-and-reserved-capabilities.md)（其 §2.3
+  的 fs 工具默认关闭裁定被本文裁定 1 推翻，以本文为准）。

docs/proposals/2026-10-09-ext-g1-b1-b3-exec-backend.md

@@ -0,0 +1,124 @@
+# EXT 申请包 · G1：回合内共享检索、命令即工具、项目列表共享与执行后端接口（B-1/B-2/B-3 + B-5②）
+
+状态：**proposed（2026-10-09）**；owner：weichen；需求依据 = RDM 评审与实施方案 V1.1
+（`Agent-System-RDM docs/proposals/2026-10-09-V22-review-and-implementation-plan.md` §3.3/§3.4/§5.3，
+owner 2026-10-09 Q1–Q8 批复；Q4=方案 A，Q2=暂时禁用＋隔离档）。
+撰写日期：2026-10-09。配套：[扩展面兼容与演进](2026-10-01-extension-compat-policy.md)、
+[EXT 申请包 C1–C7](2026-10-08-ext-c1-c7-rdm-shared-contracts.md)（EXT-6…EXT-12）。
+
+## 0. 总则
+
+- 本包四条申请按既有序列顺延 **EXT-13…EXT-16**；最终编号以受理评审为准。
+- 分期（对齐 RDM 方案 §5.2）：B-1（EXT-13）与 B-3（EXT-15）为 **G1 序 4 的硬前置**
+  （成员智能体看不到项目知识 = R04 路径不通）；B-2（EXT-14）为 G2/V0.1 端到端的硬前置
+  （对话入口无法触达 `rdm.*`）；B-5②（EXT-16）为 G2-8 原型的前置。
+- SurfaceVersion 影响：EXT-14 触及 `pkg/extension` 导出面（命令规格新字段）→ 需升
+  SurfaceVersion 并同步 surface.txt；EXT-13/15/16 为 internal 行为扩展，不改导出面
+  （EXT-16 若只加 `Options` 字段则属加法，见 §4）。
+
+## 1. EXT-13（←B-1）回合内共享检索：智能体的检索遵循项目共享授权
+
+- **场景**：RDM R04/R05——成员 B 的智能体在**回合内**（ReAct 循环的 `knowledge_search`
+  工具与自动知识注入）必须能检索到成员 A 已发布的项目知识；现状只能看到本人 owner 的
+  知识。HTTP 面（`/api/…/search`）已走 `RetrieveShared`（EXT-8 余项，Dev #269/#273），
+  但回合内两条路径仍是 owner-only：
+  - `internal/runmgr/runmgr.go:726-736` `runCtx.Retrieve` → `retriever.Retrieve(ctx, c.run.Owner, q)`（owner-only）；
+  - `internal/app/hostcaps.go:64-66` `hostcaps.search`（进程内 `Host.KnowledgeSearch` 底座）→ `pipe.Retrieve(owner)`（owner-only）。
+  结果：同一个成员，页面搜索能看到共享知识，**智能体对话里看不到**——「所有用户的智能体
+  应当能够看到项目级的共享信息」（用户补充材料 §2树1图）走不通。
+- **希望公开面**：组合根把 EXT-8 适配器（`Server.ProjectAuthz` 同款判定函数）注入
+  runmgr 与 hostcaps：两条检索路径在本人 owner 两路（全文+向量）如常之外，追加
+  「经适配器放行的共享两路」——与 HTTP 面 `rag.Pipeline.RetrieveShared` 完全同一实现与
+  同一授权判定（复用 `sharedVisible`/`SearchKnowledgeShared`，不另造第二套语义）。
+  进程内 `Host.KnowledgeSearch` 同步走共享版。
+- **为何组合不出**：`RetrieveShared` 已存在，但 runmgr/hostcaps 没有适配器的引用——
+  适配器槽在 `internal/app/hostcaps.go` 的 `projectAuthz`，由组合根在装载扩展后注入
+  Server；runmgr 的构造早于扩展装载，且 `Manager` 无该依赖。下游无法经任何公开面把
+  「按 owner 判定共享」的回调递进回合执行路径。
+- **兼容方式**：适配器未注册＝现状（本人两路）；注册后共享命中追加、RRF 融合。
+  不动 `pkg/extension` 导出面，SurfaceVersion 不变。
+- **验收**：同项目两人＋另一项目一人（RDM 成员表桩）：成员 B 发起对话，模型经
+  `knowledge_search` 命中 A 已发布的知识切片（共享命中出现在工具结果）；未授权者与
+  跨项目者为零命中；`Host.KnowledgeSearch`（hostapi 与进程内两形态）行为一致；
+  未注册适配器时与现状逐字节一致（回归）。
+
+## 2. EXT-14（←B-2）插件命令即工具：`exposeAsTool`（Q4 方案 A）
+
+- **场景**：RDM V0.1 端到端（C-11）要求「从空项目创建到生成项目建议书，全对话完成」；
+  RDM 的全部能力（两树一网读写、上传、起草、追溯查询）都登记为 `rdm.*` 命令，而智能体
+  回合的工具清单里没有任何插件命令——模型既不能检索笔记树，也不能发起 `rdm.draft.compose`。
+  U0 §3.3/方案 §3.3 裁定走**方案 A**：命令经命令总线暴露为工具，四入口同源
+  （button/card/slash/chat）自然延伸出第五入口「智能体」。
+- **希望公开面**：命令规格（`agentcommand.CommandSpec` 经 `Registry.AddCommandHandler`
+  登记的 JSON）新增可选字段 `"exposeAsTool": {"risk": "low|medium|high"}`（缺省不暴露）。
+  runmgr 装配工具清单时，把带该字段的命令投影为工具描述（名称=命令 id，参数=命令
+  paramsSchema）；模型调用该工具时，**不分发为工具执行，而是构造 `cmdbus.Request` 经
+  命令总线分发**（Entrance="agent"，Actor=会话 owner，ConversationID=当前会话）——
+  同一审计信封、同一 HITL 内联确认卡（`risk=high` 或命令规格要求确认时照常弹卡）、
+  同一危险分级。
+- **为何组合不出**：`Registry` 只有 AddSkill/AddCommand/AddCommandHandler/Note/
+  RegisterResourceAuthorizer；工具注册表（`tools.Registry`）与命令总线之间没有任何
+  桥接；MCP 通道（方案 B）绕过命令总线与确认卡，与 SR-E6/HITL 门禁冲突，已被 Q4 否决。
+- **兼容方式**：`pkg/extension` 命令规格加可选字段＝导出面加法，SurfaceVersion 升
+  （建议 2.6.0-experimental）＋ surface.txt 同步。缺省（不写 exposeAsTool）＝现状零差异。
+- **验收**：带 `exposeAsTool` 的 `/rdm.ping` 出现在模型工具清单且调用返回回执，
+  审计信封 Entrance="agent" 与按钮入口同源；`risk=high` 的暴露命令在对话内触发内联
+  确认卡；不带字段的命令不出现；RDM 侧 `rdm.trace`/`rdm.baseline` 等只读命令可在
+  回合内被模型调用（成员 B 场景结合 EXT-13）。
+
+## 3. EXT-15（←B-3）项目列表与建会话的共享放行（SR-G10）
+
+- **场景**：RDM R03——成员 B 被加入项目后「界面自动出现该项目，可直接开始工作（新建
+  对话）」。基座 `projects` 表按 owner 硬隔离（`store/projects.go:22-34`）：
+  - `GET /api/projects`（`server.go:438-441` `listProjects`）只返回本人 owner 的项目——成员看不到共享项目；
+  - `POST /api/projects/{id}/conversations`（`store/projects.go:124-130`）校验「项目属于请求者」——成员在共享项目下建会话被 404。
+  EXT-8 已放行的入口（工件三入口、SSE 项目流、检索）不含这两处。
+- **希望公开面**：这两处入口在 owner 自有判定未命中时咨询同一 EXT-8 适配器：
+  `listProjects` 追加经适配器放行的项目（去重、标注 `shared: true` 字段供前端区分
+  展示）；`CreateConversation` 的归属校验放宽为「本人自有 **或** 适配器放行」。会话
+  本身仍归属创建者（owner 不变），只是创建权扩展到成员。
+- **为何组合不出**：`ListProjects(owner)` 的 SQL 按 owner 过滤，无回调；建会话校验在
+  store 层硬编码。与 C4（EXT-8）同因：纯下游无法改变基座 owner 过滤。
+- **兼容方式**：未注册适配器＝现状；放行结果带审计。internal 行为扩展，SurfaceVersion
+  不变。
+- **验收**：成员 B 的 `GET /api/projects` 含共享项目（shared 标注）且不含未授权项目；
+  B 在共享项目下 `POST conversations` 成功、会话 owner=B；撤销成员后两者立即拒绝；
+  项目拥有者视角无任何变化。
+
+## 4. EXT-16（←B-5②）执行后端接口：隔离执行档（Q2 阶段二，G2-8 原型）
+
+- **场景**：Q2 裁定「暂时禁用，但后续执行任务时肯定还是要代码执行能力」。v0.2.0 已
+  交付启动级硬关闭（`Options.DisableExecTools`，Backend #110）；隔离档是恢复执行能力的
+  路径：执行的是**模型生成的代码**，须按不可信代码对待（方案 §3.4）：只读系统根、仅挂
+  会话工作目录与技能目录、默认无网、cgroup 资源限额、硬超时、按项目 venv 只读挂载；
+  本机已实测 `bwrap --unshare-all` 可用（无特权 userns 被 AppArmor 限制，bwrap 专门
+  策略放行）。
+- **希望公开面**：`internal/tools/exec_interpreter.go` 的进程启动点抽象为「执行后端」
+  接口（`ExecBackend`：`Run(spec) → result`），启动参数选择后端：
+  `ExecBackend = direct | sandbox`（缺省 direct＝现状）。sandbox 后端以 bwrap 实现
+  （资源限额经 systemd-run/cgroup v2）。`extension.Options` 增加
+  `ExecBackend string`（加法；空＝direct）。`DisableExecTools` 保留为最终兜底，优先级
+  高于后端选择。
+- **为何组合不出**：现实现直接 `exec.Command`（`runInterpreter`），无后端抽象；沙箱
+  参数组装（bind 清单、网络命名空间、限额）属平台面，下游插件无法注入。
+- **兼容方式**：缺省 direct＝逐字节现状；`Options` 加字段＝SurfaceVersion 升。RDM 在
+  G3-7 才切换 sandbox；G1–G2 期间维持 `DisableExecTools=true`。
+- **验收**：sandbox 后端下逃逸负例全部被拦——读 `~/.secrets`、读其他会话目录、访问
+  外网、fork 炸弹、超时不可杀均为拒绝/杀灭；会话工作目录内 docx 生成任务成功且产物
+  可登记；direct 后端与现状一致（回归）。
+
+## 5. 不在本申请包（显式排除）
+
+- EXT-6/7/10/12 完整形态：仍在 C1–C7 包（EXT-6…12）受理轨道，节奏不变。
+- 提示词随执行可用性切换（`base.deliverables` 在禁用期的降级文案）：基座自有任务，
+  不占 EXT 编号。
+- UI 仓 nightly runner 修复：与代码无关（rolldown 原生绑定缺失），另立任务。
+
+## 6. 受理建议
+
+| 申请 | 内容 | 优先级 | 兼容 |
+|---|---|---|---|
+| EXT-13 回合内共享检索 | G1 序 4 硬前置（R04/R05） | **P0 最先** | 不变（internal） |
+| EXT-15 项目列表/建会话共享 | G1 序 4（R03/SR-G10） | P0 | 不变（internal） |
+| EXT-14 命令即工具 | G2/V0.1 端到端硬前置（Q4 方案 A） | P1 | 升（加字段） |
+| EXT-16 执行后端接口 | G2-8 原型（Q2 阶段二） | P1 | 升（加字段） |

docs/proposals/2026-10-10-agent-delegation-routing-sandbox.md

@@ -0,0 +1,242 @@
+# 子代理分工、模型分级路由与任务沙箱：调研与方案
+
+状态：**proposed（2026-10-10）**；owner：weichen；方向来源：用户 2026-10-10 会话
+（①充分利用子代理；②复杂任务用 dmxapi 的 Sonnet/Opus，常规任务用 MiniMax-M2.7-highspeed；
+③记录并规划毫秒/亚秒级任务沙箱，**暂不实现**；④对「体感不如 codex/claude code/kimi」的判断）。
+本文是这四件事的主记录；未经评审的部分一律为「待确认」，不因被记录而视为已批准。
+
+依据级别：本机实测为 **SELF**（命令与输出见任务卡 evidence 与 §7 复现脚本）；外部资料为
+一手页面抓取（访问日 2026-10-10，URL 在 §8）；推断明确标注「推断」。
+
+## 0. 结论先行
+
+1. **方向对，落点要改。** 子代理只在「读多写少、可并行、输出冗长」的环节净收益为正；
+   交付物的写作与关键决策保持单线程（单一写者）。把复杂任务**整单**交给 Claude，会把最贵、
+   最慢的模型放在 token 最多的工具循环里——A/B 里 opus-5-5 耗时约 4.7 倍、工具失败更多。
+   证据更支持**按阶段/角色路由**：Claude 只做 token 少、杠杆大的环节（复杂任务的规划简报、
+   终稿综合、独立核查），检索、阅读、抽取、跑 Python、排版留给 MiniMax。
+2. **「体感差」不能主要归因于 MiniMax。** 同一模型换 harness 的分差与相邻代际换模型同量级
+   （MiniMax-M2.1 换 harness 差 7.0 分；同 harness 换成 Opus 4.5 差 3.9–7.4 分 [H11]）。
+   本机实测还发现两处直接拖累体感的协议层问题（§1.2），应先修再下结论。
+3. **「编造数字」更像模型属性，但可以用机制压住。** 同 harness 下 7→0 支持这一点；但
+   24 个相关观测里「0 处」的 95% 置信上界约 12.5%，不足以宣称清零（§1.3）。数字溯源闸门
+   比换模型便宜，且两者可叠加。
+4. **沙箱：现在的需求表述里有三处需要修正**（§4.1）——overlay 不是快照、快照只是把冲突
+   推迟到合并、「立即销毁」必须先留存审计材料。修正后，本机条件下 **bwrap + 冻结基底 +
+   overlay** 能做到约 7ms 启动（实测），足够作为默认档；microVM 档只在需要更强隔离时启用。
+
+## 1. 现状核实（SELF，2026-10-10）
+
+### 1.1 已有能力（源码，backend `421fee8`，其 deps/agent-native `3b92cb6`）
+
+| 能力 | 现状 | 位置 |
+|---|---|---|
+| 子代理委派 | 模型可调 `delegate_task`，参数 `agent∈{general,explore,research,plan,verify,writer}`、`task`、`background`；深度 1（子不能再派） | `internal/runtime/llm.go:310`、`internal/runtime/llm_direct.go:668`、`internal/runmgr/runmgr.go:1462` |
+| 子代理模型 | 由画像 frontmatter 决定：`writer` 用 `chat` 档，其余 7 个用 `lightweight` 档；调用方**不能**指定模型 | `internal/prompts/library/agent-sub-*.md`、`internal/runtime/sub_loop.go:48` |
+| 模型档位 | 只有两档：`models.chat` 与 `models.lightweight`（轻量档空则回落主档），另有 `models.chat.fallbacks` 回退链 | `internal/runtime/model.go:54,84`、`internal/settings/settings.go:73-84` |
+| 评审/验证 | `review_findings` 并行 1–3 个审查子代理再逐条验证；验证子代理输出 `VERDICT` | `internal/runtime/llm.go:311`、`agent-sub-verify.md` |
+| LLM 协议 | 后端恒走 OpenAI chat 协议（`openLLMClient` 不设 `Protocol`）；内核已实现 Anthropic Messages 客户端（含 `cache_control`）但**产品未接线** | `internal/runtime/llm.go:491`、`deps/agent-native/runtime/llm/anthropic.go` |
+| 工具并行 | 内核支持 `ExecParallel`，直连路径未设置 → 默认**串行**执行同一回合的多个工具调用 | `deps/agent-native/runtime/loop.go:203,596`、`internal/runtime/llm_direct.go:268` |
+| 执行隔离 | EXT-16：`run_shell`/`run_python` 可选 bwrap 档（断网、只读根、tmpfs 遮蔽 `/home` `/tmp`、仅会话目录可写、ulimit、超时杀命名空间）；缺省 direct | `internal/tools/exec_backend.go` |
+
+### 1.2 本机实测发现的问题
+
+| # | 发现 | 影响 | 证据 |
+|---|---|---|---|
+| F1 | **子代理结论被压成 160 字**：直连路径 `delegate_task` 只把 `res.Summary` 回给父，而 `Summary` 是子代理全文的前 160 字（全文在 `res.Text` 里，被丢弃） | 子代理做完的检索/调研结论，父代理只看到开头一句；这与「上下文防火墙」的用法正好相反，也会诱发父代理凭摘要补细节 | `llm_direct.go:697-700`、`runmgr.go` finishChild（`Summary = truncate(fullText, 160)`） |
+| F2 | **MiniMax 思考内容混在正文流里**：OpenAI 兼容流式接口默认把思考放进 `content` 的 `<think>` 块；后端在回合结束时才剥离 | 回合进行中前端收到的 `message.delta` 先是一大段思考原文，界面上「正文」区域先显示推理过程；思考计时也不准。官方提供 `reasoning_split=true`，实测开启后思考改走独立的 `reasoning_content`/`reasoning_details` 字段（3/3 次），TTFT 中位数 0.69s | `llm_direct.go:418-475`；probe2 实测（§7） |
+| F3 | **sandbox 档下交付物生成跑不通**：python-docx/openpyxl/python-pptx 装在 `~/.local`，被 `--tmpfs /home` 遮蔽；`run_python` 描述里「缺失时 pip install --user」在断网档也失效 | RDM 计划 G3-7 切 sandbox 时，docx/xlsx/pptx 生成会直接失败；EXT-16 的「docx 生成任务成功」验收用的是 `printf` 桩，未覆盖真实库 | bench2/bench3 实测：EXT-16 同形参数下 `import docx` → ModuleNotFoundError；只读挂载依赖层后 `import docx, openpyxl, pptx` 成功 |
+| F4 | **Claude 走兼容协议丢能力**：经 dmxapi/lmuai 的 OpenAI 兼容接口，4 个 Claude 型号都不返回思考字段；改走 dmxapi 的 `/v1/messages` 原生接口，第二次调用 `cache_read_input_tokens=5043`（缓存生效） | A/B 中 Claude 一侧每步按全价重算前缀、没有思考回传——47 分钟的耗时与工具失败部分可归因于此（推断，需日志确认） | anthropic_probe 实测（§7） |
+| F5 | 直连路径工具串行 | 模型一次发出多个独立检索时逐个等待；4 个被测模型都能在一个回合里给出 2 个并行 tool_calls | probe 实测（§7） |
+
+### 1.3 A/B 数据的正确读法
+
+内部 A/B（`.task/model-ab/ab-opus.json` 对 `.task/phase05-eval/after-p5.json`，4 任务 6 回合）：
+MiniMax 编造数字 7、约 10 分钟、工具 97/失败 19；opus-5-5 编造 0、约 47 分钟、工具 99/失败 33。
+
+- 样本小且相关：「0 处」的 95% 置信上界约 3/24≈12.5%（rule of three）[R39]，不能宣称清零。
+- 两侧都不在最佳状态：Claude 一侧走兼容协议（F4）；MiniMax 一侧思考回传已实现
+  （`context.thinkReplay=auto`，`ctxasm.go:206`），但流式分流有 F2 问题。
+- 速度：公开测速两者相近（opus-5-5 约 96 t/s [H25]，M2.7-highspeed 官方约 100 TPS [H4]；
+  本机短文本实测 48.9 对 50.7 t/s），所以 4.7 倍耗时更可能来自思考量、步数、重试与无缓存（推断）。
+- Vectara 有据摘要幻觉率 M2.7 12.9%、Opus 4.6 12.2%、Sonnet 4.6 10.6% [R40]：「读懂原文」差距
+  不大；差距更可能出在「缺数据时去猜」（推断）。
+
+### 1.4 其余现状（补充核实，SELF）
+
+- 评测：`eval/live` 是 go test（env：`AGENT_EVAL_BASE` 实例地址、`AGENT_EVAL_TASKS` 过滤、
+  `AGENT_EVAL_TURN_TIMEOUT`），golden 任务 4 个（`tasks.json`）；A/B 工具 `eval/ab.go`、`switch.go`。
+- 打断/插话：有 `CancelRun`（停止按钮）与子代理中断续跑；**没有**「运行中用户输入排队、
+  当前工具结束后本轮送达」的 steering 队列（未找到实现）。
+- 检查点：文件写入有改前快照日志（`runmgr/rewind.go` `NoteFileCheckpoint`）。
+- 直连路径声明 13 个工具；提示词库 base-* 共约 6.7KB（base-deliverables 5.2KB 最大）。
+
+## 2. 子代理分工：证据与方案
+
+### 2.1 证据要点（外部，来源见 §8）
+
+- **有益面**：广度优先检索（Anthropic 多智能体研究系统：主+子比单 Opus 高 90.2%，复杂查询
+  耗时最多降 90%，代价 token 约 15 倍 [R13]）；上下文防火墙——18 个模型都随输入变长退化
+  [R14]，子代理只回 1–2k token 摘要 [R17]；fresh-context 审阅（Devin Review 均 2 bug/PR，
+  58% 严重 [R20]）。
+- **有害面**：写入耦合（并行写手风格冲突，「多代理贡献智能、写入保持单线程」是当前可行解
+  [R19][R20]）；顺序任务 −39%~−70%、单代理基线 >45% 时加代理为负收益、无中心校验时误差
+  放大 17.2 倍 [R21]；Claude Code 官方也建议迭代密集/共享上下文/延迟敏感时留在主会话 [R1]。
+- **契约**：委派带目标/输出格式/工具面/边界/预算；回传浓缩结论 + 证据指针（文件/行），
+  大产物落盘只回引用 [R13][R17]；限额：禁嵌套、并发 3–5、按复杂度分档 [R7][R13][R21]。
+
+### 2.2 方案（增量，每项独立任务卡）
+
+| # | 内容 | 验收（可判定） |
+|---|---|---|
+| D1 | **修 F1**：`delegate_task` 回传改为「子代理全文（上限 4k 字）+ 超长落盘 `subagent-result.txt` 只回指针 + 工件摘要行」——内核 `subagent.CapParentText` 已有此语义（backend 侧没走它） | eval/live 前后对照：父代理引用子代理结论的回合，其终稿中来自子代理的事实不再凭摘要补齐；单测覆盖超长截断 |
+| D2 | **委派简报规范**：`delegate_task` 描述与 base-method 提示补「简报四要素」（目标、输出格式、工具/来源边界、完成判据），禁止把大块原文粘进 task | 提示词 diff + eval/live 计划/委派质量指标不回退 |
+| D3 | **并行工具执行**：直连路径设置 `ToolExecution=parallel`（读类工具并发、写类串行的区分后续再议） | 同回合多工具调用 wall-time 下降（评测记录）；事件序号仍单调 |
+| D4 | **证据账本子代理**：research/explore 画像的输出格式改为「结论 + 原文引用（文件/页/行）+ source_id」，数字必须带 source_id 或 Python 计算 ID；终稿前由确定性校验拦截（接质量计划 P5 的事实一致性检查） | 编造数字在闸门处被拦且计数；子代理回传含引用率 100% |
+| D5 | **角色×模型矩阵**（依赖 §3 R2）：新增/调整画像的 `model:` 支持 `claude-*` 档；`writer` 保持 chat 档，新增 `composer`（终稿综合）与 `planner-complex`（复杂任务规划简报）画像走强模型档 | 画像 frontmatter 生效（SubagentSpec 解析）；评测 A3/A5 组可配置 |
+
+边界：子代理深度维持 1（现状即禁嵌套）；并发上限维持产品侧 3；本方案不引入子代理间通信。
+
+## 3. 模型分级路由：证据与方案
+
+### 3.1 证据要点
+
+- **整单路由不划算**：我们的 A/B 中 opus-5-5 耗时约 4.7 倍、工具失败 33 vs 19；公开测速两者
+  相近（§1.3）。Devin Fusion 的教训：强模型当全程主控只降本 33%，且「判断即交付物」的难题
+  上掉分 [R30][R31]。
+- **按阶段/角色路由有正证据**：Sonnet 执行 + Opus 顾问 +2.7pp 且降本 11.9%；Haiku + Opus 顾问
+  在 BrowseComp 19.7%→41.2% [R32]；Aider「强规划+便宜编辑」$13.29 得 64.0% 胜 o1 单跑 $186.5
+  得 61.7% [R12]。反例也存在（BrowseComp-Plus 上弱编排+强子代理更好 [R21]）——**放哪一层必须
+  实测**，这正是 R3 实验的目的。
+- **协议与缓存**：Claude 经 OpenAI 兼容层不回思考、不支持缓存、忽略 strict（官方文档 [H37]，
+  本机 F4 实测缓存恢复）；缓存按 tools→system→messages 前缀匹配，中途改工具集会整缓存失效
+  [R35][R36] → 模型切换只应发生在阶段边界，每角色固定 system/tools 前缀。
+
+### 3.2 方案
+
+| # | 内容 | 验收 |
+|---|---|---|
+| R1 | **Claude 原生协议接线**：`models.chat.protocol = openai-chat \| anthropic`（设置项），anthropic 时用内核现成的 `llm/anthropic.go` 客户端（base 指向 dmxapi `/v1/messages` 根），回传 thinking 块与 signature、挂 `cache_control` 断点、usage 记缓存读写（N3 计费拆分已有字段） | 同会话第二次调用 `cache_read_input_tokens>0`（SELF 复现 F4 的探针即验收集）；thinking 块原样回传（删改会 400 [H24]） |
+| R2 | **角色路由表**：设置新增 `models.<role>`（role∈composer/planner/verifier，缺省回落 chat 档）；画像 frontmatter `model: <role或具体型号>`。默认建议：chat=MiniMax-M2.7-highspeed（不变）、composer=claude-sonnet-5（dmxapi，原生协议）、verifier=异模型（deepseek-v4-flash 或 claude）、复杂任务 planner=claude。Opus 系列留给最难任务手动指定 | 角色解析链单测；`models` 列表来自各端点 `/v1/models`（已核实 dmxapi 有 sonnet-4-6/sonnet-5/opus-4-6/opus-5-5 等，见任务卡 evidence） |
+| R3 | **路由 A/B 实验**（扩展现有 eval/ab.go）：组别 A0 全 MiniMax / A2 MiniMax+数字闸门 / A3 A2+Claude 终稿 / A4 A2+Claude 核查 / A5 Claude 规划+终稿+核查、MiniMax 执行；关键组加 Sonnet 变体。指标：无来源数字占比、含编造交付物比例、pass^3、p50/p95 耗时、分角色成本（含缓存）、工具失败分类。样本：30–50 任务×3 次（宣称编造率<5% 需 ≥60 份零编造样本 [R39]）；<3pp 差异慎下结论 [R49] | 选型报告入任务卡，来源 GATE/SELF 标注 |
+| R4 | **升级规则进 harness**（不依赖模型自觉 [R20]）：连续 N 次工具失败、闸门拦截无来源数字、检索「未找到」三类事件触发 advisor 咨询或角色升级 | 评测中升级触发可观测；误升级率记录 |
+
+运维事实（2026-10-10，SELF）：lmuai 月额度已耗尽（$1303.32/$1300，2026-11-05 重置）——R1/R3
+的 Claude 侧建议先走 dmxapi（余额 ¥0.48，**需充值**，此前 A/B 卡估算全量对照 ¥50–100）。
+
+## 4. 任务沙箱：记录与规划（**不立即实现**）
+
+### 4.1 对原始思路的三处修正
+
+1. **「overlay 隔离他人变更」不成立**：内核文档明确「下层在挂载期间被修改的行为是未定义的」
+   [S1]；本机实测运行中的沙箱能看到下层后续修改（bench2 第 5 段）。**一致视图必须来自不可变
+   基底**（冻结副本或 git commit 物化），而不是叠在活动目录上的 overlay。
+2. **快照只是把冲突推迟到合并**：Codex cloud/container-use/Cursor 都以 diff/PR 回收，冲突在
+   写回时用基线校验暴露 [S23][S28][S26]。「互不影响」的成本是写回时的三方合并与人工兜底，
+   设计里必须显式包含这一步，否则快照只是把失败挪到了最后。
+3. **「立即销毁」与审计有张力**：销毁的应是计算资源与可写层；转录、diff、工件哈希、环境
+   清单要按 TTL 封存（Codex 删前存快照 [S23]、container-use 留命令史 [S28]、Cursor 留工件
+   [S26]）。本仓的证据门禁（AGENTS.md）同样要求可复核输出——封存记录是硬约束。
+
+另一处简化：硬链接克隆（cp -al）对「原子替换写入」是安全的（rename 换 inode），但对原地
+写入会穿透（共享 inode）——本机实测（bench3 第 3 段）。只可作为「可检测」方案并配
+sha256/mtime 清单复核，不可当作完整快照。
+
+### 4.2 目标形态（任务工作区沙箱）
+
+一次任务 = 冻结基底（会话/项目材料的不可变视图）+ 私有可写层 + 确定性依赖层 + 出口管控 +
+回收（diff 与工件清单）+ 封存后销毁。智能体在其中任意折腾不破坏原始资料；产出经校验写回。
+
+### 4.3 分层架构与延迟预算（本机实测，SELF）
+
+| 层 | 机制 | 启动 | 适用 | 备注 |
+|---|---|---|---|---|
+| L0 进程沙箱 | bwrap（EXT-16 现状）+ 依赖层只读挂载 | **p50 7.3ms**（/bin/true，n=30）；带 overlay 同为 ~7ms | 默认：解释器执行、交付物生成 | 修 F3 后 python-docx 全链路可用（import 60ms、1 页 docx 76ms） |
+| L0.5 工作区沙箱 | L0 + `--overlay-src <冻结基底> --overlay <宿主upper>` | ~7ms（实测） | **多任务并发、需要一致基底与可回收 diff 时** | upper 即增量；快照语义来自冻结基底而非 overlay |
+| L1 容器 | docker（overlayfs 驱动） | `run --rm` p50 142ms（redis:7 true，n=10） | 依赖隔离更强、镜像化环境 | 可加 warm pool 压冷启动；单机自托管无障碍 |
+| L2 microVM | Firecracker/gVisor | 未实测；E2B 等托管方当前文档只称 "fast Linux VM"（量化数字已不可得，**未经证实**） | 不可信代码、最强隔离 | 本机有 /dev/kvm；引入与维护成本高，暂缓 |
+
+支撑件（与层正交）：
+
+- **冻结基底**：git 材料以 commit SHA 物化（同 SHA 只物化一次、多任务只读共享）；非 git 材料
+  用 cp -al + sha256 清单（写回前复核，变了即判基底失效）。git worktree add 实测 192 文件
+  11ms，overlay 直接盖工作树 ~10ms，两者都够快。
+- **依赖层**：项目 venv / site-packages 只读 bind（实测修复 F3；RDM 方案 §3.4 原有此意）。
+- **数据库**：SQLite 用 `VACUUM INTO` 取一致快照 [S32]；PG 用零连接模板库克隆（PG18 XFS 上
+  有 CLONE，ext4 上是复制 [S11][S37]——量级以库大小为准，必要时评估独立 XFS 卷给 reflink）。
+- **网络**：默认无网（现状）；将来要放开时，按 sandbox-runtime 的形态做出口代理白名单 +
+  代理侧凭据注入（密钥不进沙箱）[S-RT]。
+- **回收与写回**：沙箱退出后读 upper → 生成 `git diff --binary` 补丁 + 工件 sha256 清单；
+  写回用 CAS（目标当前哈希==基底哈希 → 原子替换；不等 → `git merge-file` 三方合并，冲突停给
+  人）；写回前留前像。git 目标用 `update-ref <ref> <new> <old>`（本身就是 CAS）[S46]。
+- **封存**：base SHA、补丁、工件哈希、转录指针、环境清单（依赖层版本）、退出码，按 TTL 留存
+  后销毁工作区目录。
+
+### 4.4 与现网的关系
+
+- EXT-16 sandbox 档是**进程级**隔离（单次命令）；本节是**任务级工作区**，两者叠加而非替代。
+  首个落地形态：ExecSpec 增加工作区概念，sandbox 档把「会话目录 bind」换成「冻结基底 overlay
+  + 私有 upper」。
+- 已知缺口顺带记录：小队内核 ExecConfig、工作流 ScriptCommand 仍 direct（EXT-16 卡内遗留）；
+  沙箱档覆盖它们是前置条件之一。
+
+### 4.5 非目标与开放问题
+
+- 不做多租户硬隔离与 OS 级安全声明（沿用质量计划 §5 边界）。
+- 开放：是否划独立 XFS 卷换 reflink；gVisor 试用；warm pool 是否值得（L0 已 7ms，大概率不值）；
+  Windows/macOS 不在范围。
+
+## 5. 分期与验收总表
+
+| 增量 | 内容 | 依赖 | 备注 |
+|---|---|---|---|
+| E1（P0 快修）✅ | F1 委派回传、F2 reasoning_split、F5 并行工具、F3 依赖层 | 无 | **已完成（2026-10-10）**：Agent-Native #42/#43/#44 + Backend #127 + Dev PR（任务卡 feature/agent-e1-parallel-fixes）。验证：F2 实测正文 0 泄漏、F3 sandbox 实测 IMPORTS-OK、F5 实测同回合并发重叠；eval 对照工具失败 19→11，未核实数字 7→12（E3 待做，见任务卡） |
+| E2 | R1 Claude 原生协议 + 缓存观测 | E1（F2 同类协议改动可同批） | dmxapi 需充值 |
+| E3 ✅ | D4 证据账本 + 数字闸门 | 无（接质量计划 P5） | **已完成（2026-10-10）**：Backend #130、Dev #311（任务卡 feature/agent-e3-evidence-gate）。标注感知豁免（分句判定）+ 两轮修正（变化才二拦）+ base.deliverables v6 数字溯源规则 + 子代理引用格式；eval 对照未核实数字 12→5（未标注 3）、工具调用 93→63 |
+| E4 ✅（R4+账本） | R2 角色路由 + D5 画像 | E2 | **R4 与账本已完成（2026-10-11，MiniMax 版）**：Backend #131–#134、Dev #315（任务卡 feature/agent-e4-escalation-ledger）——滑窗失败提醒（端到端日志实证）、检索空命中提醒、source_id 账本（83 标记）；Claude 角色档按模型指示暂缓；eval 四轮对照无恶化 |
+| E5 ✅（R3 部分） | R3+R4 路由 A/B 与升级规则 | E2–E4 | **R3 已完成（2026-10-10，MiniMax 家族版）**：Dev #313（任务卡 feature/agent-e5-model-ab）三臂对照（hs / 全M3 / hs+M3轻量）——建议默认 chat=MiniMax-M3（未标注编造 1、失败最少、时长持平、单价减半）；R4 升级规则仍待做 |
+| S0-1 ✅ | §4.4 首个落地形态：冻结基底 overlay + CAS 回收 + 变更摘要（--exec-workspace overlay） | 用户 2026-10-11「继续完成下一步」 | **已完成（2026-10-11）**：Backend #135/#136、Dev #318（任务卡 feature/agent-s0-workspace-overlay）——bwrap 集成 3 + live 端到端（失败零落地/新增/修改/-ws 清理）；S0-2（fs 联合读/任务级工作区/封存）待授权 |
+
+## 6. 与既有规划的关系
+
+- [智能体工作流质量改进](2026-10-09-agent-quality-improvement-plan.md)：本文是其「模型 A/B」
+  结论的后续与 P4/P5 的延伸（D4 与 P5 合流；E5 继承 A/B 方法论并扩大样本）。
+- [EXT 申请包 G1](2026-10-09-ext-g1-b1-b3-exec-backend.md)：E1-F3 修复其 sandbox 档的交付物
+  缺口；§4 工作区沙箱是 EXT-16 的演进方向。
+- [RDM 阶段总案](2026-10-07-rdm-phase-plan.md)：G3-7 切 sandbox 前置依赖 F3 修复。
+- Agent 栈 N2 WP5（子代理/后台派生）：D1–D5 在产品层消费其内核端口，不改内核契约。
+
+## 7. 本机实测的复现要点（SELF，脚本存于任务卡 evidence 同目录说明）
+
+- 启动延迟：bwrap 命名空间 / +overlay / +持久 upper 各 30 次（bench.sh、bench2.sh §3）。
+- F2：`reasoning_split=true` 前后各 3 次流式（probe2.py，观察 delta 字段分布）。
+- F3：EXT-16 同形参数下 `import docx` 失败 vs 只读挂载 `~/.local/.../site-packages` 后成功
+  （bench2 §1–2、bench3 §1–2）。
+- F4：dmxapi `/v1/messages` 连续两次调用，第二次 `cache_read_input_tokens=5043`。
+- overlay 非快照：运行中沙箱读到下层并发修改（bench2 §5）；cp -al 对 rename 安全、对原地写
+  穿透（bench3 §3）。
+- docker 冷启动 10 次（bench.sh）。
+
+## 8. 来源（除标注 SELF 外均为 2026-10-10 抓取的一手页面）
+
+- [S1] Linux 内核 overlayfs 文档：https://docs.kernel.org/filesystems/overlayfs.html
+- [S11] BoringSQL instant database clones：https://boringsql.com/posts/instant-database-clones/
+- [S23] Codex environments/git-worktrees：https://learn.chatgpt.com/docs/environments/git-worktrees
+- [S26] Cursor cloud agent：https://cursor.com/docs/cloud-agent
+- [S28] container-use CLI：https://container-use.com/cli-reference.md
+- [S32] SQLite VACUUM INTO：https://www.sqlite.org/lang_vacuum.html
+- [S37] PostgreSQL 18 release notes：https://www.postgresql.org/docs/release/18.0/
+- [S46] git-update-ref：https://git-scm.com/docs/git-update-ref
+- [S-RT] Anthropic sandbox-runtime（Linux=bwrap+seccomp、网络默认全拒+代理白名单+凭据注入、
+  Apache-2.0）：https://github.com/anthropics/sandbox-runtime
+- [S-CX] Codex sandboxing（Linux 用 bwrap；read-only/workspace-write/danger-full-access）：
+  https://learn.chatgpt.com/docs/sandboxing
+- [H4] MiniMax 定价与速度：https://platform.minimax.io/docs/pricing/overview 、
+  https://platform.minimax.io/docs/guides/text-generation
+- [H24] Claude thinking 块回传要求：https://platform.claude.com/docs/en/build-with-claude/extended-thinking
+- [H25] Artificial Analysis（opus-5-5 96.4 t/s 等）：https://artificialanalysis.ai/models/claude-opus-5-5
+- [H37] Claude OpenAI SDK 兼容层限制：https://platform.claude.com/docs/en/api/openai-sdk
+- [R1][R12][R13][R14][R17][R19][R20][R21][R30][R31][R32][R35][R36][R39][R40][R49] 子代理与
+  路由调研来源清单见任务卡「调研来源」节（Claude Code docs、Anthropic/Cognition 工程博客、
+  arXiv 2512.08296 等，URL 全量随卡保存）。
+

docs/proposals/2026-10-10-generative-ui-plugin.md

@@ -0,0 +1,505 @@
+---
+title: Generative UI research and plugin proposal
+date: 2026-10-10
+type: feat
+revision: r1
+product_contract_source: user-request-and-current-source
+---
+
+# Generative UI 调研与插件方案
+
+确认状态：**三项关键取舍已由用户裁定（2026-10-11，见文末"用户裁定记录"）**；全文随发布 PR 评审。推进状态：方案成稿并进入发布评审；原型、业务实现、运行验收、部署均为 **NOT_RUN**。
+来源：2026-10-10 用户请求——先调研参考与仓库，再判断能否加入本系统，给出可随时启禁的插件方案。
+负责人：裁定与验收 weichen（用户）；方案整理与执行 Agent；更新时间：2026-10-11。
+本文是唯一主记录；任务卡引用本文。文内路径除相对链接外，均相对 Agent-System-Dev 根目录。
+用户授权本轮调研、思考和完整方案准备，不表示已批准本文的产品取舍、原型试验或后续实施。
+
+## 结论与目标
+
+**可以加入，而且当前系统已有合适基础。推荐新增独立的 Generative UI 插件，配合小范围、通用的宿主能力扩展。**
+Agent 负责决定何时需要页面、采用哪些组件、怎样排列内容与交互；宿主负责设计系统、身份权限、事实读取、渲染、动作执行和恢复。
+页面结构可以每次不同，组件实现与权限规则保持确定。
+
+首选路线：复用现有 Agent-Native、Go Backend、Core UINode 和 React UI；以版本化 Surface 表达可保存、可更新的动态页面。
+借鉴 A2UI 的组件目录与数据/交互协议，以及 json-render 的 catalog/registry 分工；首期不要求替换现有运行时或另起 Node 服务。
+外部 renderer 是否比扩展现有 UIRenderer 更划算，由受控试验决定，当前没有实际集成证据。
+
+建议先覆盖对话产出的完整阅读/分析页面，再加入交互表单与任务工作页，最后扩展到项目工作区。
+登录、项目切换、停止执行、设置和审批保留可预测的宿主入口；业务主内容可以动态组织。
+该演进顺序已于 2026-10-11 获用户确认：首试点为对话中的完整分析页（场景 1）；它不把长期目标缩减为“几个固定卡片模板”。
+
+插件首期采用**可信 Go 编译扩展 + 声明资产**（该交付方式已于 2026-10-11 获用户确认）：功能开关实时生效，安装/升级插件代码需要重新构建组合二进制并重启。
+“功能随时启禁”与“无需重启安装任意插件包”是不同能力；用户未把后者列为本期硬要求，sidecar 路线保留为备选并随实际需求重评。
+
+---
+
+## 外部调研
+
+调研日期：2026-10-10。引用来自官方文档或官方源码，说明的是当场文档/仓库状态；本轮未安装或运行这些项目。
+不以 star 数量、演示视频或作者自述推断生产可靠性；正式选依赖时仍须固定版本、审许可证与传递依赖并进行组合验证。
+
+### Generative UI 的不同层次
+
+| 类型 | Agent 实际决定什么 | 与本目标的关系 |
+|---|---|---|
+| 固定工具结果组件 | 调用什么工具、向预制组件传什么参数 | 适合起点，但单独使用不足以实现自由组织页面 |
+| 声明式生成页面 | 组件树、布局、内容重点、数据绑定与动作引用 | 本方案主路线；页面可变，执行边界明确 |
+| 可持续交互的生成工作区 | 页面随用户输入、任务进展和数据版本变化 | 本系统中期目标；需要状态、版本、权限与回放协议 |
+| 生成 HTML/JS/React 小应用 | 连组件实现和程序逻辑一起生成 | 表达力高；需独立沙箱、资源与网络边界，后续单独评估 |
+
+运行时按任务生成页面，与开发期间让 Agent 写前端代码不同。后者交付后仍可能是固定页面。
+AG-UI 这类事件协议、A2UI 这类 UI 描述协议、MCP Apps 这类嵌入式应用契约解决的层面也不同，不能互相替代。
+
+### 核心参考与采用判断
+
+| 参考/官方仓库 | 能力定位 | 本系统采用判断 |
+|---|---|---|
+| [A2UI](https://github.com/a2ui-project/a2ui) / [文档](https://a2ui.org/) | 声明式组件、Surface、数据绑定和用户动作；组件目录可映射自己的设计系统 | 最值得借鉴的协议。Go 可产生 JSON，前端可保持自身 UI。是否严格实现某版本，留给独立适配器与一致性测试 |
+| [json-render](https://github.com/vercel-labs/json-render) / [Catalog](https://json-render.dev/docs/catalog) | 为 AI 定义组件与动作词汇，由 registry 绑定真实 React 等实现 | 最值得试验的 renderer 依赖；可将目录映射到 @ui。不能未经比较就再建一套状态和渲染系统 |
+| [CopilotKit](https://github.com/CopilotKit/CopilotKit) / [AG-UI](https://github.com/ag-ui-protocol/ag-ui) | Agent 与应用之间的流式事件、状态与交互集成 | 参考工具 UI、共享状态和事件设计；现有系统已有 runtime/SSE/store，首期不整体替换。AG-UI 本身不定义完整页面布局 |
+| [Vercel AI SDK](https://github.com/vercel/ai) / [Generative UI 指南](https://ai-sdk.dev/docs/ai-sdk-ui/generative-user-interfaces) | 工具调用与结果驱动组件渲染，应用开发者实现组件 | 很好的最小入门与工具组件范例；不是整页自主规划的全部方案，不为此把 Go 后端迁到 TypeScript |
+| [assistant-ui](https://github.com/assistant-ui/assistant-ui) / [生成 UI 文档](https://www.assistant-ui.com/docs/tools/generative-ui) | 除工具 UI 外，当前有 present 工具生成组件 JSON 树、动作注册与流式 props | 借鉴显式 present 入口；不必替换聊天壳。官方明确 renderer 不按 props schema 执行校验，仍需自己的运行时验证 |
+| [Thesys OpenUI](https://github.com/thesysdev/openui) / [现行文档](https://www.openui.com/docs) | OpenUI Lang、parser、React 流式 renderer 与自定义组件；Crayon 旧仓已转向该仓 | 作为表达能力/流式体验备选。可用自己的模型；开源 runtime 与可选 OpenUI Cloud/Gateway（原 C1）分开评估，不把开源许可等同托管服务条款 |
+| [Tambo](https://github.com/tambo-ai/tambo) | 注册 React 组件与 schema，Agent 选择组件并更新状态；包含后端编排 | 设计参考。官方已公告 Tambo Cloud 将于 2026-10-31 关闭 API，2026-11-30 删除托管数据；开源可自托管，但不建议作为新系统的默认托管依赖 |
+| [MCP Apps](https://github.com/modelcontextprotocol/ext-apps) | 工具返回交互式 UI resource，宿主通过桥接在隔离容器内嵌应用 | 适合未来插件小应用与外部工具 UI 互通；它不自动生成页面，也不代表现有 Agent-Native MCP 工具支持已具备 Apps 宿主能力 |
+
+A2UI 官方主页当前列出 v0.9.1 为 current、v1.0 为 candidate；它的 [catalog 指南](https://a2ui.org/concepts/catalogs/) 建议成熟应用围绕现有设计系统定义目录。
+已有[官方 React renderer](https://a2ui.org/reference/renderers/)；这证明有实现可供验证，不证明该版本已经在本系统构建/运行通过。
+不能混合旧 v0.8 的消息字段和新版本字段后声称协议兼容。
+json-render 的 [registry 文档](https://json-render.dev/docs/registry) 将组件实现与动作处理留在应用侧，适合本系统“生成数据、宿主执行”的边界。
+Tambo 的停服状态以[官方仓库公告](https://github.com/tambo-ai/tambo#readme)为依据，旧教程中的 Cloud 快速接入方案已不适合作为新项目默认选型。
+
+许可初筛：A2UI、json-render、AI SDK 为 Apache-2.0；CopilotKit、AG-UI、Tambo、assistant-ui、OpenUI 的当前仓库为 MIT，具体包及附带资产在锁版本时再核对。
+[MCP Apps LICENSE](https://github.com/modelcontextprotocol/ext-apps/blob/main/LICENSE) 处于 MIT 向 Apache-2.0 迁移，部分旧贡献保留 MIT，文档另有 CC-BY-4.0，不能统一简写为“任选双许可”。
+当场仓库活动检查未发现上述候选被归档；活动不等于稳定或维护承诺，Tambo Cloud 公告说明需要把代码可用与运营持续性分开判断。
+AI SDK 的 [RSC 路径仍为实验状态](https://ai-sdk.dev/docs/ai-sdk-rsc/overview)，首期没有理由为此将现有 Vite 应用迁到 Next.js/RSC。
+
+### 三条可行路线
+
+| 路线 | 优点 | 主要代价 | 结论 |
+|---|---|---|---|
+| A. 原生 UINode/Surface 插件 | 复用权限、Agent、事件流、设计系统与部署形态；无强制新服务 | 要补齐 schema 校验、版本、交互和启禁 | **首选** |
+| B. json-render/A2UI renderer 嵌入插件 | 利用现成组件目录、绑定和流式能力 | React 集成之外还需 Go 校验、动作授权、版本与状态适配；可能重复 UIRenderer | 受控试验中的挑战方案；显著减少总维护成本才采用 |
+| C. 隔离的代码生成小应用或整套平台 | 表达力最高，适合复杂专用工具 | 沙箱、网络、会话桥、制品供应链、依赖升级和审计面明显增加 | 后续独立方向，不作为首个增量 |
+
+路线 A 不是从零重造外部框架：首期范围只包含本系统用得到的有限词汇、快照、授权动作和页面容器。
+若需求发展为大量复杂表单、表达式和跨平台 renderer，重新比较 B；不要不断扩展内部 DSL 以维持最初选型。
+
+---
+
+## 当前系统的可行性依据
+
+以下为 **SELF·源码级观察**，不是运行能力验收。审计基线为 Dev `104a4142c918f7325d3a78e3e6e270e46739baea`。
+
+| 组件 | 固定 SHA |
+|---|---|
+| Core | `a253a40b8e5563119b00c4e71fb61fe0d11d6d6a` |
+| Backend | `017b40f76156905eabe8323ae2bfe800f47fb8bd` |
+| Frontend | `339a9ebc2d827eaf990346b91d36f4ad5a13f090` |
+| UI | `76d6633736a7abb36ac1ecca42fe4e6f120d0558` |
+| Agent-Native | `c348441691e8bdab784a03aa9be64d53dacff341` |
+| Documents | `3a82eec74ce6b2b548a7a943f8382d64df14316e` |
+
+| 当前源码事实 | 依据（上述固定版本） | 设计影响 |
+|---|---|---|
+| React 19、Vite 6；Core 已有 16 种有限 UI 词汇 | `modules/frontend/package.json`；`modules/core/ui.go:9-50` | 不必另换技术栈或设计系统 |
+| UIRenderer 能画 table、compare、tabs、timeline 等 | `modules/ui/src/UIRenderer.tsx:22-35` 及各 case | 动态选择和组合已有组件有基础 |
+| submit_card 的 body 仍是字符串，包装成 Markdown | `modules/backend/internal/runtime/hostbridge.go:128-148` | 当前 Agent 还不能通过这个工具输出任意结构化页面 |
+| form 没有提交回传，节点按数组 index 作为 key；table 行 action 未渲染 | `modules/ui/src/UIRenderer.tsx:22-29,73-95,184-200` | 有类型不等于完整交互；稳定 nodeId、草稿与动作桥必须补 |
+| 卡片 body 渲染未传 onAction | `modules/ui/src/ActivityCardView.tsx:66-74` | 不能只把按钮塞进 body 就声称接通动作 |
+| cardsvc 有保存与事件发布；运行管理有卡片端口 | `modules/backend/internal/cardsvc/cardsvc.go:73-139`；`internal/runmgr/runmgr.go:637-715` | 复用其分层与持久化后发布原则，避免第二条无审计通道 |
+| 上下文回灌仅取卡片顶层 markdown/kv | `modules/backend/internal/ctxasm/ctxasm.go:373-411` | 需要递归语义投影；否则下一轮 Agent 不知道页面里有哪些内容 |
+| SSE 服务端先订阅再重放并按 seq 过滤；前端没有完整拒旧/切会话保护 | `modules/backend/internal/server/server.go:375-429`；`modules/frontend/src/api.ts:189-194`、`store.ts:375-414` | Surface 投影须明确 seq、revision 与 generation 防卫 |
+| enabled 写入 owner+plugin grants，主要被 ListFor 消费 | `modules/backend/internal/server/platform_api.go:130-142`；`internal/store/platform.go:13-32`；`internal/plugins/host_v2.go:160-175` | 现有“禁用”不能当作请求/执行禁用；新能力必须服务端闭环 |
+| ESM loader 存在，但未找到实际页面挂载调用；桥未接主认证/命名事件处理 | `modules/frontend/src/pluginHost.ts:9-13`；`modules/ui/src/pluginSdk.ts:9-25` | 首期不能依赖现成 ESM 页面宿主；动态 import 也不是代码沙箱 |
+| 公开扩展可注册命令 handler，命令可 exposeAsTool | `modules/backend/pkg/extension/extension.go:34-48`；`internal/cmdbus/cmdbus.go:47-64`；`internal/app/app.go:417-422` | 插件命令可供现有 Agent 调用，无须新增任意 native executor 插口 |
+| 公开 Host 缺会话/任务完整上下文及 Surface 发布端口 | `modules/backend/pkg/extension/host.go:26-68` | 需申请最小公开契约，不能从插件导入 Backend internal |
+
+现有 context assembler 可复用消息、附件、可见知识和用户偏好；不等于已经自动读取所有项目背景。
+跨会话读取仍须满足现有开关、同项目/租户与隐私限制（`internal/runmgr/runmgr.go:934-1005`）；生成页面不能扩大数据可见范围。
+当前 `Host.Complete` 是简单 prompt→string，且主要走 owner 路由，不能当作已有 project 级结构化/流式生成接口。
+
+本轮阅读了规划索引、基座路线图、插件 v2 与扩展兼容相关记录；没有发现既有 Generative UI 专项主记录。
+2026-10-10 本轮查询 Dev/Documents/Core/Backend/Frontend/UI 的 open PR，结果均为空；这是当时快照，后续开工须重验。
+规划索引中的 Agent 质量、模型路由、RDM 扩展仍有剩余范围，不因没有 open PR 就视为全部完成或不冲突。
+
+---
+
+## 需求与用户体验
+
+### 需求表
+
+所有实施需求当前为候选，待人工确认。符合度“需调整后符合”表示本方案指出了必需宿主改动，不表示已实现。
+
+| ID | 需求与来源 | 符合度 / 优先级 | 可判定验收条件 | 处理与依赖 |
+|---|---|---|---|---|
+| R1 | 根据内容、上下文、任务、项目背景自主组织页面（用户） | 需调整后符合 / P0 | 同一组事实分别完成“比较、风险分析、进度查看”，生成不同且合适的结构；不是同模板换标题 | 纳入试点；U1/U3/U4 |
+| R2 | 以插件封装，随时启禁（用户） | 需调整后符合 / P0 | 禁用后 UI、直接 API、旧按钮、在途发布均受控；原有系统仍可用；重启后保持禁用 | 纳入首期；U2/U3/U4 |
+| R3 | 页面可追溯事实与来源（本系统约束） | 符合 / P0 | 数据值来自授权数据引用；分析结论标为生成判断；能定位材料与版本 | 纳入首期；U2/U3 |
+| R4 | 使用本系统设计系统、易用且可访问（DESIGN） | 符合 / P0 | 令牌/动效/折叠守护通过；键盘与窄屏可完成主要流程；唯一预览落位 | 纳入首期；U4 |
+| R5 | 页面可保存、刷新恢复、版本可解释（长期工作流） | 需调整后符合 / P0 | 刷新恢复已保存视图；同版本可确定渲染；断线、旧帧与切项目不串页 | 纳入首期；U2/U4 |
+| R6 | 用户继续修改页面，Agent 理解当前结构（用户目标的闭环） | 需调整后符合 / P0 | “改为对比、突出风险”生成新 revision；上下文包含结构、来源与已确认用户输入 | 纳入首期；U3/U4 |
+| R7 | 动态表单和动作，沿用权限与审批（扩展交互） | 需调整后符合 / P1 | 表单可提交、校验、重试；旧 revision/越权/重复动作受控；必要审批不能由模型伪造 | 后续增量；U5 |
+| R8 | 任务/项目工作区随阶段组织（用户长期目标） | 需调整后符合 / P1 | 当前任务可组织计划/产物/待决策信息；项目聚合符合跨会话读取权限；固定布局可恢复 | 后续增量；U6 |
+| R9 | 外部协议可演进，禁用不丢历史（可维护性） | 符合 / P1 | 固定 schema/catalog/插件版本；不兼容时静态/文本降级；旧动作不自动重放 | U2/U7 |
+| R10 | 有真实收益与成本证据（交付规范） | 符合 / P0 | 对照固定 UI 的任务成功率、耗时、事实错误、延迟和 token 成本；真实模型结果可复核 | U1/U7；当前 NOT_RUN |
+
+### 三个试点场景
+
+1. **调研和文档分析页**：比较多个方案时，Agent 组织“结论→对比表→证据→风险”；用户改问实施顺序后，调整为阶段与依赖。数据与判断分开，来源能打开原工件。
+2. **当前任务工作页**：需求阶段突出待澄清项，执行阶段突出步骤和产物，验收阶段突出验证结果与缺项。完成状态取自真实任务记录，模型不能画一个绿色标记就更改任务状态。
+3. **方案选择和需求表单**：Agent 根据缺失信息组织输入项；用户填写后形成明确的结构化输入，再触发下一轮。表单提交不自动批准其后所有业务操作。
+
+首个完整增量以场景 1 为主；保留场景 2/3 的契约扩展空间，但不要求同时交付所有交互。
+普通文本回答仍是有效结果；没有可视化价值时 Agent 应保持文本，不强行生成页面。
+
+### 页面落位与自主程度
+
+对话中的卡片是生成页面的入口与简短摘要，完整页面进入现有预览位置的 Surface 模式；全屏是同一实例的放大。
+预览区关闭时，用户仍能从对话入口打开或在对话中继续操作，遵守 DESIGN 的“右栏收起零功能缺失”。
+之后的项目工作区只是同一 Surface 的另一种打开入口，不复制另一套事实与状态。
+可以保留多份页面，活动预览只有一个；新结果不抢占用户当前打开的其他对象。同一 Surface 的入口聚合到同一实例，用户从对话引用选择历史页面。
+
+建议提供三档产品行为：关闭；按需生成；自动建议/生成。
+首期默认关闭，启用后按需触发；用户明确请求页面时直接生成，Agent 在复杂比较/时间线等任务中可自主选择组件与结构。
+自动触发只监听明确任务阶段/材料完成等语义事件，后续增量再开启；不按每个 token 或每条 SSE 事件重排页面。
+用户可以固定布局、切回原视图、重新组织；“固定布局”冻结结构，授权范围内的数据仍可更新，需显示数据时间。
+用户正在输入、选择或执行动作时，结构更新暂存并提示应用，不挪动焦点或覆盖草稿。
+
+---
+
+## 架构与关键决策
+
+### KTD1. 插件策略与宿主执行分离
+
+插件拥有组件使用策略、生成提示、布局选择、schema 修复策略、试点场景与质量评估。
+宿主拥有授权上下文、持久化、稳定渲染容器、请求鉴权、事件序列、动作执行和插件启禁。
+通用组件实现归 UI；契约归 Core；前端投影与导航归 Frontend；Backend 实现受限公开接口。
+新目录/仓库位置建议为独立 Generative UI 组件仓，在 Dev 固定组合中引用；正式建仓和最终名称待实施前确认。
+
+```mermaid
+flowchart TB
+    A[用户任务与展示偏好] --> B[既有 Agent Runtime]
+    C[宿主授权上下文与组件能力] --> B
+    P[Generative UI 插件策略与命令] --> B
+    B --> D[插件 present 命令：声明式页面]
+    D --> E[宿主校验与 Surface 服务]
+    E --> F[保存快照与事件]
+    F --> G[Frontend 唯一状态投影]
+    G --> H[SurfaceHost 与 UI Renderer]
+    H --> I[用户交互]
+    I --> J[宿主动作校验与命令总线]
+    J --> B
+    K[插件启禁与资源权限] --> C
+    K --> E
+    K --> J
+```
+
+### KTD2. 复用现有 Agent，不增加独立 UI 模型调用
+
+首选由当前工作 Agent 根据插件提供的能力目录，通过公开命令的 `exposeAsTool` 生成并提交页面规格。
+插件命令可概念性分为“读取可用展示能力/上下文”“提交或替换页面”“恢复原视图”；准确命名在接口评审中确定。
+页面规格由主 Agent 作为工具参数产生；插件负责校验与发布编排，无需默认再调用一次 `Host.Complete`。
+工具返回已接受的 Surface/revision 与语义摘要，或者带字段路径的有限校验错误；后者允许原 Agent 至多重提一次。这会增加原回合的模型轮次，必须计入成本，不能宣称零额外 token。
+因此插件可以自主组织页面，而不接管主 Agent 的对话循环、模型凭据或任务执行权。
+后续只有真实评测显示收益，才加入专用 UI planner 或轻量模型修复；届时单独定义 project 级模型路由、预算与取消接口。
+
+### KTD3. Surface 是有版本的呈现产物
+
+方向性数据模型（不是已实现接口）：
+
+| 层 | 必需内容 | 权威来源 |
+|---|---|---|
+| 身份信封 | surfaceId、owner、projectId、conversationId、sourceRunId、pluginId | 服务端分配/从当前请求绑定；模型不能自报 owner |
+| 兼容标识 | schemaVersion、catalogVersion、pluginVersion、rendererCompatibility | 已安装组件与宿主协商 |
+| 版本 | revision、baseRevision、contextVersion、activationEpoch | 服务端事务与当前授权状态 |
+| 页面 | title、稳定 nodeId、受限 layout、UINode 内容及结构 | 模型提议，服务端验证 |
+| 数据 | resourceRef、源版本、字段白名单、读取时间 | 宿主解析后的授权数据 |
+| 交互 | 服务端保存的 action binding、参数 schema、执行级别 | 命令目录与当前授权；模型仅引用允许动作 |
+| 回放 | semanticText/结构摘要、来源、生成用途、静态降级文本 | 服务端递归投影为主，不能只信模型自述 |
+
+首期采用完整、经过校验的快照原子替换，不渲染半截 JSON，不把流式 token 当作结构更新。
+revision 单调递增，更新必须带 baseRevision；版本冲突拒绝并返回当前版本，不自动覆盖他人更新。
+发布以当前身份、插件、sourceRunId、toolCallId/发布请求 ID 建幂等键，重复工具结果返回已保存 revision，不能生成重复页面；相同键但不同规格拒绝。
+复杂的流式 patch、表达式求值和跨页面组件引用均后置；若后续引入 patch，必须保留同样的原子性与版本检查。
+现有卡片保存 Surface 引用与文本摘要，不把一份可交互页面同时复制进卡片 body、工件和工作区三处。
+
+持久化建议增加宿主通用 Surface 及 revision 记录，支持现有 SQLite/PG 档位；按 owner/project/conversation 建权限索引。
+页面快照、最小 action binding 与待发事件在同一事务落盘，再由宿主事件管道发布；发布失败靠持久事件或重建快照恢复，不能只依赖内存总线。
+业务实体仍由原业务服务维护，Surface 不成为项目/任务事实的第二份数据库。
+新表采用增量迁移，默认关闭功能时不影响老路径；回退应用不删除表和用户产物。保留周期沿用所属会话/工件策略，最终清理策略随数据契约评审，不在开关中隐式删除。
+
+### KTD4. 上下文是授权后的事实快照
+
+宿主根据当前身份和请求，提供任务目的、当前会话摘要、项目允许读取的背景、指定工件、相关检索结果、用户展示偏好与允许动作目录。
+浏览器只提供关注对象 ID 和偏好，不能提交可信权限声明或任意数据库查询。
+先按权限过滤再裁剪；只按当前任务相关度取必要字段；不直接将整个项目、原始系统提示或敏感凭据塞入模型。
+材料与工具结果作为不可信数据处理，不能覆盖组件目录、开关或动作权限；页面内容里的指令不能自行触发后续动作。
+上下文快照记录源版本与裁剪情况；缓存必须包含身份、权限版本、项目/会话、源版本、catalog 和配置，不按问题文本跨用户复用。
+已有跨会话读取限制保持有效；缺少授权时只生成当前会话范围的页面，并明确范围。
+
+事实字段尽量采用宿主数据绑定，展示值由服务端解析；模型生成的解释、建议和风险判断显式属于分析内容。
+快照记录完整来源集合，包括自由文本分析的来源。读取/导出/回放时任一来源权限失效，首版拒绝整份旧快照并提供重新生成入口，不能只隐藏引用链接而继续显示泄露内容。
+下一轮上下文提供经过权限复核的结构摘要、来源和确认过的交互结果；不只回灌 markdown/kv，也不把前端未提交草稿当作用户指令。
+禁用插件时不再注入生成策略/动作能力；历史语义内容按正常授权保留为普通文本上下文。
+
+### KTD5. 组件目录约束表达，不固定页面模板
+
+首期选取已有 section、markdown、kv、list、table、compare、timeline、steps、chart-lite、doc-ref；需要时扩展受控 row/grid 布局。
+每个节点必须有稳定 ID；组件目录定义 props、嵌套、数据类型和支持的动作，禁止任意 CSS、脚本、eval、远程组件 URL。
+只允许语义尺寸/密度/强调枚举，映射 @ui tokens；新视觉规则按 DESIGN 与 UI gitlink 组合变更评审。
+渲染器采用既有 safeHtml、Collapsible 和 motion 原语；表格提供溢出与分页/截断提示，不能静默丢数据。
+未知组件或版本产生可见降级原因与文本视图；未知动作一律拒绝。不能沿用“未知节点静默消失”作为新 Surface 成功状态。
+
+初始试验上限建议：每页 200 节点、8 层嵌套、256 KiB 规格、单表首屏最多 100 行；值为待测的资源预算，不是既有性能承诺。
+同时限制字符串、数据总量、图表点数、解析时间和外部资源；图片/链接沿用宿主来源策略。
+可访问性检查覆盖标签、标题层级、键盘顺序、焦点、屏幕阅读器状态提示和 reduced-motion；不能只验证 JSON 合法。
+
+### KTD6. 动作由宿主重新授权
+
+生成的按钮不是批准。模型只能选择已允许的 action 名称/资源引用，宿主解析为当前 Surface 的 binding。
+客户端提交 surfaceId、revision、actionId、requestId 与受限表单数据；服务端重新验证当前身份、项目、插件状态、参数、资源版本与命令权限。
+简单筛选、排序、页签切换留在客户端确定逻辑，不额外调用模型；需要重组织或分析时才进入现有 Agent 回合。
+业务变更通过既有命令总线和 HITL，表单通过不扩大其授权范围。
+幂等记录绑定身份、Surface、revision、action 和请求内容；重复点击返回已有结果，未知外部结果先查询，不因超时自动重做。
+同一 requestId 但不同参数必须拒绝；重试先做当前读权限/启禁检查，再查询已有执行回执，已执行回执不能因资源版本已变化而被当作新动作重放。
+
+```mermaid
+sequenceDiagram
+    participant U as 用户
+    participant F as SurfaceHost
+    participant S as 宿主 Surface 服务
+    participant C as 命令总线
+    participant A as 既有 Agent
+    U->>F: 提交输入或点击动作
+    F->>S: revision、action、requestId、data
+    S->>S: 当前权限、启禁、参数、资源版本和幂等检查
+    alt 需要业务审批
+      S->>C: 既有审批流程
+      C-->>U: 展示真实动作与参数
+    else 允许读取或已满足审批
+      S->>C: 执行已授权动作
+    end
+    C-->>S: 确定结果或未知结果状态
+    S-->>F: 动作状态与最新投影
+    S->>A: 必要时追加已确认交互结果
+    A->>S: 新页面提议
+    S-->>F: 已保存且校验后的新 revision
+```
+
+### KTD7. 真正可验证的插件启禁
+
+新插件默认关闭，不沿用现有“缺少 grant 默认 true”的行为。适用关系是安装存在、全局允许、owner 显式启用、manifest 范围与当前资源权限的交集。
+首期采用实例总开关 + owner opt-in；project 开关可后续新增，不能允许项目设置覆盖实例禁用或扩大 manifest 范围。
+管理员可以全局禁用；用户仅在管理员允许的范围控制自己的使用。
+
+| 状态/动作 | 必须发生的行为 |
+|---|---|
+| 关闭 | 不贡献可调用工具/提示策略，不启动生成，不接受写页面与动作；原有固定 UI 可用 |
+| 启用 | 校验组件兼容与配置，建立新的 activationEpoch，按请求授权能力；不重放旧动作 |
+| 禁用请求成功返回 | 先持久化禁用并提升 epoch，再通知前端；返回后新请求、旧按钮和旧 generation 的提交都应被拒绝 |
+| 禁用时有生成在途 | 取消该 owner/plugin 的独立宿主操作，撤销发布资格；提交前再次核对 epoch 并拒绝迟到页面。共享主模型回合继续，不调用 CancelRun 取消整个主任务 |
+| 禁用时已有动作在执行 | 尚未进入执行的动作拒绝；已提交业务操作按原命令记录收尾，不能承诺撤销既成副作用；结果不明则查询恢复 |
+| 历史页面 | 权限仍有效时以宿主通用静态渲染/文本查看，动作禁用；资源权限撤销后旧快照也不能继续泄露数据 |
+| 再次启用 | 重验 schema、来源与权限，创建新 capability/binding；保留产物，不自动执行先前点击 |
+| 卸载/升级 | 功能停用与代码包移除分开；旧产物靠宿主降级；代码升级走构建兼容验证 |
+
+```mermaid
+stateDiagram-v2
+    [*] --> Disabled
+    Disabled --> Enabled: 授权启用且兼容
+    Enabled --> Generating: 当前 Agent 请求页面
+    Generating --> Ready: 校验与事务提交
+    Generating --> Fallback: 无效规格或失败
+    Ready --> Generating: 请求重组织
+    Ready --> Disabled: 禁用并撤销动作
+    Generating --> Disabled: 撤销发布并拒绝旧 epoch 提交
+    Fallback --> Generating: 有限重试或用户重试
+    Fallback --> Disabled: 禁用
+```
+
+该状态图描述呈现能力，不等同业务任务状态。历史快照存在不代表插件 Enabled。
+主 Agent 已收到的生成提示和已发生的 token 成本不能在禁用后收回；下一次能力组装移除插件策略，当前回合即使继续提议页面也会被执行端拒绝并转为文本结果。
+epoch 核对与页面提交/新动作准入必须共享可证明的事务或串行化边界，不能“先查开关、释放锁、再执行”。禁用返回是准入截止点，截止点前已准入的操作按上表在途语义处理。
+启禁守卫覆盖发现、命令分发、工具执行、上下文能力注入、Surface 读取/提交与动作；标明归属的能力不能通过另一入口绕过。
+编译插件是可信代码扩展，不是恶意第三方代码的隔离边界。sidecar 目前继承环境并使用共享 Host token 的现状，不足以承担不可信插件沙箱。
+首期只补这条能力闭环及共享执行边界；通用热重载原子化、插件市场和所有旧插件资产清理另立任务，不无限扩大本次范围。
+
+### KTD8. 一个状态所有者，明确恢复规则
+
+后端是 Surface 与业务状态权威；Frontend store 维护一份投影；UI 只渲染 props 并发出用户事件。
+表单草稿、页签与展开状态归前端按 surfaceId/nodeId 管理；提交后成为服务器确认的输入，不能同时被模型与组件局部 state 无序覆盖。
+复用主认证与 SSE 通道，不另用现有未接完整的 pluginSdk EventSource 作为第二所有者。
+事件绑定会话/项目/Surface 与 seq；前端丢弃过期 seq、旧 revision、旧页面 generation；检测缺口后获取授权快照重建。
+切项目、退出登录、撤权或禁用立即作废在途请求和可见敏感投影；不同身份不复用浏览器缓存。
+撤权阻止继续访问和重新加载，不承诺抹去用户此前已合法下载的数据；敏感快照不写入持久浏览器存储。
+普通 reconnect 不重新调用模型，先恢复已保存的快照；重新生成是用户动作或经允许的策略动作。
+
+### KTD9. 可演进但不虚报标准兼容
+
+内部首版使用系统自己的版本化 Surface + UINode 扩展，不能命名为“A2UI 兼容实现”后省略协议测试。
+未来可加 A2UI 适配器：固定协议版本与目录版本，只支持明确子集，不支持的组件/动作显式报错，不静默损失含义。
+AG-UI 仅在需要跨 Agent 框架互通时评估事件适配；MCP Apps 仅在需要外部工具应用时评估宿主资源与沙箱能力。
+三者不作为首期串联依赖；避免为了 Generative UI 同时迁移模型运行、传输与前端框架。
+
+---
+
+## 最小宿主改动与插件交付边界
+
+| 模块 | 建议变更 | 明确保留的职责 |
+|---|---|---|
+| Core | Surface/版本/节点 ID/受控布局/动作信封与兼容标识；保持旧 UINode/卡片可读 | 跨仓公开类型权威；同步 Go、TS 及契约快照 |
+| Backend public extension | 授权 ContextSnapshot、Surface 读写/发布、插件 capability/activation；按需要增加受限上下文投影扩展 | 不暴露 raw DB、完整 session、通用任意 HTTP 或事件发射器 |
+| Backend internal | 实现上述端口、执行级启禁、事务存储、事件恢复与动作鉴权 | 服务端最终授权与业务事实 |
+| UI | 稳定节点与受控布局的通用 renderer；表单事件、行操作、无障碍、降级 | 纯展示、token/motion/Collapsible/safeHtml；不持网络状态 |
+| Frontend | SurfaceHost、单一状态投影、预览落位、开关、结构更新/草稿协调 | 身份、路由、事件、用户输入草稿 |
+| Generative UI 插件 | prompts/skills、目录选择、present/revise 等命令、生成校验编排、试点策略 | 只消费公开扩展，默认随当前 Agent 生成；无独立任务事实库 |
+| Documents/Dev | 契约申请、使用说明、评测结论、精确组件组合与索引 | 方案/实现/验证/部署状态分别记录 |
+
+公开扩展优先使用新增可选能力接口或版本协商，避免给现有必实现 Host 接口直接加方法而破坏所有消费者。
+修改公开导出时更新 `SurfaceVersion`、`pkg/extension/surface.txt` 与相关兼容快照；Core/UI/Frontend/Backend 的依赖 gitlink 同步验证。
+已有命令投影可以承载 Agent 工具，因此不申请通用 native executor 注册口作为前置。
+首期不需要开放任意前端 ESM 注入；插件只输出既有/新批准的通用 UI 词汇。
+
+如果要求“下载插件包后不重启安装”，则改为隔离 sidecar + 同一 Surface 契约。
+增加独立身份、最小环境、按插件/owner capability 令牌、健康检查、取消/退出协议、版本升级与回滚；前端仍可用通用 renderer，不必加载任意 JS。
+这属于另一档交付成本，不应通过当前 `exec.Command` 与共享 token 简单包装后宣称完成。
+
+---
+
+## 分阶段计划
+
+下列为可评审的实施候选，不是已经获准执行的待办。每个增量继续按 `policy/delivery.md` 人工评审；试验结果允许回改选型和范围。
+功能代码与生产实例本轮不变。近期 U1 具体，其余单元在试验评审后细化精确 API 与数据迁移。
+
+### U1. 受控价值与选型试验
+
+- 关联 R1/R4/R10；依赖：已满足——2026-10-11 用户批准试验范围（见文末“用户裁定记录”）；作为独立任务另行启动并评审。
+- 对象：固定当前组件 SHA，在隔离工作区用合成或获准的脱敏材料，覆盖调研比较、任务概览、需求输入三类。
+- 方法：先比较“固定 UI/文本”与“原生 UINode 动态组合”；再用少量相同样本比较 json-render/A2UI renderer 接 @ui 的复杂度与缺口。后者是 renderer 选型挑战，不另建全套后端。
+- 文件范围：专用实验目录、组件契约夹具与评测说明；全部明确为原型，不替换生产路径。
+- 试验预算：3–5 人日；30 个固定任务、每项至少 2 次模型运行；首轮最多 60 次/方案。费用上限已由用户指定为 **¥200**（2026-10-11）；模型限 MiniMax M3 与 M2.7-highspeed，材料限合成或已脱敏样本；超限即停。
+- 判据：结构选择确实随目标变化；信息来源可追溯；可通过现有设计令牌渲染；列出外部依赖节省与新增的实际代码/状态维护面。
+- 停止：出现越权数据、无法限制生成代码执行、超过预算、依赖要求替换既有 runtime，暂停该路线并提交调整。
+- 产物：A/B 结果、renderer 取舍、失败样本、建议目录与修订版方案；不是生产代码验收。
+
+### U2. 通用契约、启禁与持久化
+
+- 关联 R2/R3/R5/R9；依赖 U1 的设计评审。
+- 文件范围：`modules/core/ui.go`、Core 新 Surface 契约及对应测试；`modules/backend/pkg/extension/`、`internal/plugins/`、`internal/store/`、`internal/server/` 及对应测试/迁移。
+- 方法：先固定兼容与授权信封，再实现 owner 隔离的 Surface 存储、revision CAS、activationEpoch 和命令执行守卫；能力缺失明确拒绝。
+- 验证：旧消费者可用；关闭状态下 direct API/工具/旧 action 不绕过；并发更新有一方冲突；写快照后事件发布失败可恢复；SQLite/PG 路径一致。
+- 完成条件：最小公开契约审过，故障/拒绝路径有证据，插件能通过公开接口保存/读取页面；此时不宣称生成体验完成。
+
+### U3. 生成插件与上下文闭环
+
+- 关联 R1/R2/R3/R6；依赖 U2。
+- 文件范围：独立插件的 manifest、commands、prompts/skills、目录和测试；Backend `internal/ctxasm/` 的通用语义投影、授权快照适配及测试。
+- 方法：沿用 AddCommandHandler/exposeAsTool；当前 Agent 接收可用词汇和授权快照，产出页面参数；插件校验，宿主原子发布。解析/语义修复最多 1 次，失败回到文本，禁止无限自修复循环。
+- 验证：同素材换任务得到合适不同结构；伪造数据引用与未知动作被拒；下一轮可以解释并修改之前的 table/compare/tabs；禁用不再注入能力。
+- 完成条件：真实模型“任务→规格→保存→继续修改”闭环可回放，来源与成本被记录；不另造 Agent runtime。
+
+### U4. 只读生成页面与可恢复体验
+
+- 关联 R1/R2/R4/R5/R6；依赖 U2，最终集成依赖 U3。
+- 文件范围：`modules/ui/src/UIRenderer.tsx` 及测试、通用 Surface 展示组件、`modules/frontend/src/store.ts`、`api.ts`、预览/卡片入口、插件设置及对应组件/浏览器测试。
+- 方法：稳定 nodeId、布局语义、受控 renderer、唯一 SurfaceHost；加载/失败/回退/来源/重新组织入口；单一 store 校验 seq/revision/generation。
+- 验证：刷新/断线/切项目/迟到响应；关插件固定界面仍完整；页面未知版本可读；键盘、窄屏、暗浅主题；输入焦点与布局变化规则。
+- 完成条件：场景 1 可通过真实浏览器完整使用；此增量提供展示和重新组织，业务写动作未开放。
+
+### U5. 动态表单和动作闭环
+
+- 关联 R7，依赖 U2/U3/U4；必须先评审本阶段动作范围。
+- 文件范围：Core 动作/字段 schema、UI 表单与行操作及测试、Frontend 草稿/提交桥、Backend action service/cmdbus 适配及权限/幂等测试。
+- 方法：输入草稿由宿主管理；服务端绑定 action；必要时进入既有 HITL；失败留在当前页面并保留可恢复输入。
+- 验证：旧 revision、资源被删、撤权、关插件、双击、超时未知结果、两个标签页同时提交；无审批旁路；用户未提交输入不传给模型。
+- 完成条件：场景 3 可完成明确读取/决策动作，再逐类批准业务写动作，不能一次开放所有命令。
+
+### U6. 自适应任务与项目工作区
+
+- 关联 R8，依赖 U4/U5 的收益与可靠性证据。
+- 文件范围：Frontend workspace/任务页容器、插件上下文选择与触发策略、Backend 授权聚合适配、相关测试。
+- 方法：先当前任务，后项目；任务阶段触发有限更新；固定布局/恢复原视图；自动模式单独 opt-in。
+- 验证：不同阶段突出不同信息；任务事实不能被页面改写；私有会话不泄露；输入时不自动重排；自动触发有预算且不递归自激。
+- 完成条件：实际任务效率改善，关闭后原工作区完整，跨会话汇总授权能复核。
+
+### U7. 组合验收、兼容与交付
+
+- 关联 R2/R5/R9/R10；按每个可交付增量执行，不只在最后一次执行。
+- 文件范围：各模块相关测试、Documents 使用/评测记录、Dev 任务卡和精确 gitlink 组合；涉及治理脚本才追加治理测试。
+- 方法：先组件 PR，再组合 PR，固定 Dev SHA+组件 SHA+schema/catalog/model/profile；复放正常、异常、权限、禁用与恢复链路。
+- 验证：CI `make test`/`make build` 与独立重放；业务智能体改动附真实模型前后对照；本地 SELF 不升级为 GATE。
+- 完成条件：用户批准该增量、功能与回退均有证据、文档和开关说明完整；是否部署仍是独立授权与运行验收。
+
+粗估：U1 3–5 人日，U2–U4 首个可靠只读闭环再需约 10–18 人日，U5 约 5–8 人日，U6 约 5–10 人日。
+这些是范围估计，假设熟悉现有代码且使用可信编译插件；不含人工等待、全量外部协议兼容和不可信插件沙箱，不是交付承诺。
+
+---
+
+## 验证与评估
+
+### 试点评价方法
+
+采用相同材料、权限、模型/profile、任务和重复次数比较固定 UI/文本基线与生成 UI。
+分别记录冷启动/缓存、模型时间、验证时间、渲染时间、额外 token 与调用次数；不把缓存命中混作生成加速。
+默认观测记录规格/目录版本、耗时、字节数、token、错误码和回退原因；原始上下文、输入值与模型全文不进入普通日志，评测原始材料按既有 eval 规则保存在受控环境且不进仓。
+以下阈值为**建议评审目标**，本轮无实测结果：
+
+| 维度 | 建议目标/方法 |
+|---|---|
+| 任务有效性 | 任务成功率至少不低于基线；选定比较/梳理场景的人类中位完成耗时改善约 20% 才考虑扩大自动模式 |
+| 事实可靠性 | 验证集中的资源/数值引用可追溯；关键事实错误为 0；分析判断独立标注 |
+| 规格有效率 | 首次合法页面 ≥90%；最多一次修复后 ≥98%；最终失败 100% 有可用文本降级 |
+| 延迟 | 浏览器先给确定加载状态；本地校验+渲染 P95 目标 <300ms；模型生成单独统计。显式页面请求的初始展示等待预算为 20s，超时转文字等待/回退并撤销该次发布，不因此中断共享主 Agent 回合 |
+| 干扰 | 普通文本任务不额外调用 UI 模型；不会每个 token 重排；用户输入与焦点不丢失 |
+| 开销 | 展示额外 token、调用数、失败重试成本与收益；是否可接受在真实模型对照后决定，不先声称“更快更省” |
+| 开关正确性 | 禁用成功后所有新副作用入口拒绝；旧 epoch 页面不能提交；保留授权历史与原 UI |
+
+30 个任务的小试验用于发现问题和决策，不足以证明长期生产可靠率；报告样本量、失败数和每类任务结果，不只报百分比。
+若收益只体现在“更好看”而任务成功率/效率下降，保留按需模式，收窄场景或停止推广。
+
+### 必测故障与权限矩阵
+
+- 正常：同材料不同任务、纯文本无需页面、生成后改布局、来源打开、刷新恢复。
+- 结构：未知节点、循环/过深结构、超大表格、非法数据类型、畸形 JSON、未知 schema/catalog、非法 URL/脚本属性。
+- 权限：跨 owner/project/doc 引用、跨会话私有内容、生成后撤权、切账号/项目、直接 API 调用、伪造动作 ID。
+- 异步：重复/乱序/缺口事件、断线重放、两个标签页、旧 revision、切页后的迟到响应、保存成功但事件未发布。
+- 启禁：生成前/中/提交前禁用，动作前/审批后/执行中禁用，服务重启，重新启用，兼容版本缺失。
+- 交互：表单校验、重复提交、业务冲突、输入中更新、取消、失败后保留草稿、外部结果未知不重复执行。
+- 回退：插件完全缺失、模型不可用、预算耗尽、renderer 出错；固定 UI 和授权文本历史仍可用。
+- 回归：旧 UINode、卡片、命令、工件预览、侧栏关闭、单二进制构建、SQLite/PG、设计守护与可访问性。
+
+正式实现期按各组件 PROJECT 的命令验证，并在 Dev 精确组合运行 `make test`、`make build`。
+涉及智能体提示/工具/上下文变化时，按 `policy/delivery.md` 的真实模型任务级前后对照要求执行；mock 只能证明机制。
+证据由 `make evidence` 写入任务卡，保留 SELF/REPLAY/GATE 和固定对象，未运行项保持 NOT_RUN。
+本轮只检查方案差异、引用与链接、源码对应关系；没有运行上述功能试验或业务测试。
+
+---
+
+## 风险、待确认项与下一步
+
+| 风险 | 具体处置 |
+|---|---|
+| 页面自主性变成固定模板填充 | 用同事实不同目标的验证例证明结构变化；逐步开放组合能力，而非预设三种页面硬路由 |
+| 模型幻觉变成“业务事实” | 事实字段绑定授权源、生成判断标注、来源版本可回查；业务状态只走原服务 |
+| 自主重排破坏可用性 | 稳定宿主入口、布局固定、输入期间冻结结构、按语义事件有限更新 |
+| 声明式 schema 被误当安全边界 | 仍对资源、URL、动作、执行权限和数据泄露做服务端校验；可信插件代码另有信任边界 |
+| 禁用只藏按钮 | 执行端统一守卫、epoch 与提交前复核；直接 API 和在途测试列为必过项 |
+| 引入第二套状态/runtime | 复用主 Agent、主 SSE 和 Frontend store；外部包只在明确 renderer 边界试验 |
+| 公开接口扩大过快 | 小型能力接口、版本协商、兼容快照；不暴露内部 store，避免泛化插件市场 |
+| 外部项目快速变化 | 固定依赖版本，锁 catalog，保留适配层；Tambo Cloud 停服作为实际供应商生命周期样例 |
+
+### 用户裁定记录（2026-10-11）
+
+以下三项已由用户（weichen）裁定，原“进入试验前需确认”问题随之关闭：
+
+1. **接受“动态业务页面 + 稳定宿主入口”**：首试点为对话中的完整分析页（场景 1），随后推进任务/项目工作区。
+2. **“随时启禁”采用可信编译插件交付**：功能启禁无需重启，插件代码安装/升级需重建并重启；不要求本期免重启安装，sidecar 路线保留为备选。
+3. **试验参数**：裁定与验收负责人为用户（weichen），执行由 Agent 承担；模型限 MiniMax M3 + M2.7-highspeed；材料限合成或已脱敏样本；U1 费用上限 ¥200。
+
+注：裁定后权威 main 又合入前端三栏工作台（Dev PR #322）。本文“当前系统的可行性依据”按调研时固定 SHA 记录、不改写；U1 开工时须在新 HEAD 上重验该源码事实表。
+
+首选下一任务是 **U1 受控价值与选型试验**，不是直接实现所有宿主契约。
+其前置（批准试验范围与预算）已由 2026-10-11 裁定满足；产物为固定样本 A/B 报告、实际 renderer 取舍、失败清单与 r2 方案。
+验收依据为 R1/R4/R10 的可判定结果，随后再决定 U2–U4 的正式投入。
+U1 按独立任务启动并继续逐阶段人工评审；本文发布（推送、合入）随裁定记录一并进入 PR 评审，部署仍不在本轮范围。

docs/proposals/2026-10-11-collaboration-storage-and-distribution.md

@@ -0,0 +1,253 @@
+---
+title: 多人协作存储与分布式演进方案 - Plan
+type: refactor
+date: 2026-10-11
+execution: code
+product_contract_source: ce-plan-bootstrap
+---
+
+# 多人协作存储与分布式演进方案 - Plan
+
+修订：r1；确认状态：**已批准（2026-10-11 用户指示「按方案开始改造」）**；推进状态：方案获批发布，实施自首选增量 U1+U2 启动；业务实施/迁移/压测/部署仍为 NOT_RUN，逐项以实施任务卡为准。
+需求来源：2026-10-11 用户要求完善 SQLite、PostgreSQL/pgvector、Redis 分工；随后确认“10–100 人，多人多项目多会话并行，未来支持多服务分布式”。
+需求负责人：weichen；方案编制：Codex；实施及运维负责人：待指定。更新时间：2026-10-11（Asia/Shanghai）。
+关联任务：Dev `.task/feature-collaboration-storage-plan.md`（方案任务，已发布）；后续 U1+U2 实施由独立任务承接。
+正文中的源码路径以 Agent-System-Dev 为根；工作包中的 `internal/` 简写指 `modules/backend/internal/`；文内相对链接以本文为根。
+
+## 1. 推荐结论与边界
+
+团队部署以 PostgreSQL 作为共享业务状态的唯一权威，pgvector 承担数据库内向量查询，Redis 承担可丢失的缓存与限流。SQLite 保留给个人嵌入式使用、离线工具及可以重建的本机状态，不承载团队共享写入或跨主机运行所有权。
+
+第一阶段交付单应用实例的可靠团队部署；第二阶段补齐执行所有权、持久命令、共享工件与事件追赶，再开放多个应用实例和 Worker。通过接口和数据归属为服务拆分做准备，当前不要求微服务化、Kubernetes、分片或引入另一套消息中间件。
+
+“不会出现错误”不能成为无条件承诺。工程目标是：在定义的故障模型下，不静默丢失已确认数据、不覆盖他人的并发更新、不产生未经识别的重复副作用、不越权；异常可发现、可追踪、可恢复。冲突可以返回明确的 409，超载可以返回 429，依赖故障可以返回 503，它们必须有清楚的重试语义。
+
+本方案是[双档存储 D17–D24](2026-09-30-dual-tier-storage-and-multitenancy.md)的候选增补，批准前不改写原已采纳决策。拟调整的是团队部署的默认与必需条件，以及 D24 原来排除的跨实例执行能力；保留个人 SQLite 档、非容器部署、现有检索契约与序号语义。
+
+## 2. 当前事实与差距
+
+源码调查基线：Dev `73c901fa341a3653d6e0826d0da3497507995482`，Backend `eda90ed310f37f7352e24a8096d932dbf320cd73`，Documents `9a46785ee0f19540c79f83b4e4544572b5217ac2`，Agent-Squad `490b0b2dfa1567cb16ff7a7230fd78e52bc2938e`，Agent-Native `c348441691e8bdab784a03aa9be64d53dacff341`。
+来源均为 **SELF·源码/本机只读观察**；没有真实并发故障重放。命令、对象 SHA 和原始输出见[调查收据](../records/2026-10-11-collaboration-storage-audit-receipt.json)，启动收据见任务卡。
+
+| 对象 | 当前可核实事实 | 方案含义 |
+|---|---|---|
+| Dev 运行实例 | `runtime/dev/bin/agent-system`、8788 端口打开 `runtime/dev/data/agent-system.db` 及 WAL；二进制 build revision 为 `017b40f76156905eabe8323ae2bfe800f47fb8bd` | 当前服务确实使用 SQLite；运行版本与上述源码基线不同，源码缺陷不冒充已在该二进制重现 |
+| 本机安装 | Homebrew 列出 PostgreSQL 18.6、pgvector 0.8.7、Redis 8.10.2 | 仅证明安装；目标 PG 实例、目标库扩展启用、角色与可用性未验证，不据此批准切换 |
+| Backend 存储 | `internal/app/app.go:105` 按 DSN 选 PG，否则 SQLite；`store/store.go:50` SQLite WAL、busy_timeout=5000、单连接；PG 池固定 16/8 | 无需重写全部存储层；需团队档显式配置、连接预算和真实 PG 测试 |
+| 已有一致性基础 | `store/dialect.go:49` PG 事务咨询锁；消息 seq 唯一约束、requestId 去重和 HITL 条件更新 | 保留并扩展，不把已有能力列作全新建设；这些能力不等于跨实例运行互斥 |
+| Run 所有权 | `runmgr/runmgr.go:1113` 用进程内 map 占用会话；`store/messages.go:120` 直接创建 run | 两实例可能各自认为空闲；需共享占用和有效执行代次 |
+| 取消与审批 | `runmgr/runmgr.go:1326,1422` 依赖本实例 active 句柄；HITL 先落卡，再查句柄 | 请求落在非执行实例时存在命令不生效或卡已处理但执行未被唤醒的风险 |
+| 跨实例事件 | `pgbus/pgbus.go` 每批通知末 seq，Listener 只 `EventAt` 取末条；断线后对原连接继续 Wait | 静态可见批内中间事件遗漏及重连缺口；`server/server.go:376` 的 SSE 重放/去重不能修复已越过的游标 |
+| schema 迁移 | `store/migrate.go:migrate` 每次 Open 执行迁移；DDL 事务提交后另行插入迁移版本 | 并发启动与两步间崩溃存在风险；切 PG 前先改为单迁移入口与原子版本登记 |
+| 向量查询 | `store/vectors.go` 读取 BYTEA，应用内计算余弦；`migrate.go` 未把向量列建成 pgvector 类型 | 安装 pgvector 不代表启用；复用 RRF 管线，分阶段改为数据库 top-k |
+| Redis | `ratelimit/ratelimit.go:65` 独立 INCR/EXPIRE，EXPIRE 错误未处理；请求异常默认放行；app 默认限额 0 | 当前只是可选共享限流，需原子窗口、鉴权/TLS配置、容量保护与可观察的降级 |
+| 本地文件 | `blobstore` 默认本地目录；Backend Squad 入口未传 Store，回落 FileStore；checkpoint 写 `.agentx/checkpoints.jsonl` | PG DSN 不会迁走这些状态；工件、执行工作区、checkpoint 要分别处理 |
+| 独立 Squad | 独立 CLI 使用 `adapters/sqlite/runstore.go` 的 `orchestration.db`；这不是 Backend 实际接线 | 不把迁移该 SQLite 文件当作 Backend 分布式改造完成 |
+| 验证 | PG/Redis 集成由 `AGENT_PG_TEST_DSN`/`AGENT_REDIS_TEST_ADDR` 控制；当前 CI YAML 没有显式准备这两种服务 | 缺变量会跳过关键测试；CI 通过不能自动证明真 PG/Redis 或双进程链路通过 |
+
+已有规划衔接：Q1 已记录 Store 收敛但仍留 platform→squad 队列桥接等余项；N3 原案与归档卡的 JournalOnly 落地不同，应以当前接线确定权威。共享权限沿用 EXT-8 授权适配器与 RDM 的成员/角色职责，不新建第二套成员模型。历史报告用于定位，不能替代当前验收。远端调查发现 Backend [#135](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Backend/pulls/135) 正在增加 S0 工作区 overlay/frozen base/CAS apply；U5 必须复用并核对其契约，不能另造冲突的工作区实现。该 PR 尚未作为本案已合入依赖。其他被查仓当时未返回 open PR，详见收据；实施启动时重新核对。
+
+## 3. 需求与可判定结果
+
+| ID | 需求 | 优先级 | 验收条件 |
+|---|---|---|---|
+| R1 | 支持 10–100 人、多项目、多会话并行 | P0 | 在固定环境与下述负载下完成真实业务链路；容量结果绑定组件 SHA、配置和数据集 |
+| R2 | 团队数据有唯一共享权威 | P0 | 团队档无有效 PG 配置或连接失败时拒绝就绪，不自动建立本地 SQLite 继续服务 |
+| R3 | 并发提交和编辑不静默覆盖 | P0 | 同 requestId 返回同一逻辑结果；同版本竞争写入最多一个成功，其余明确冲突；不同会话并行 |
+| R4 | 跨实例运行与命令可恢复 | P1，多实例前置 | 同会话主 run 单一有效 owner；旧 epoch 写入拒绝；任意 API 实例取消/HITL 均到达执行者 |
+| R5 | 事件有序、可追赶 | P0/P1 | 批处理、掉通知、重连和慢消费者后可按游标补齐全部已提交事件；不因收到末 seq 而跳过中间事件 |
+| R6 | 项目权限在所有数据入口一致 | P0 | 读取、写入、SSE、检索、下载与工具入口均校验当前授权；撤权后的新请求无泄漏 |
+| R7 | 数据和运行状态可恢复 | P0 | SQLite→PG 演练无遗漏；备份恢复含文件与权限映射；未知副作用停在可见恢复状态，不盲目重试 |
+| R8 | 高负载下有界且可观察 | P0 | 队列、活跃 Agent、DB 连接、工具/模型请求都有上限；超载行为、等待时间和错误分类可观测 |
+| R9 | 向量检索随数据增长扩展 | P1 | 数据库 top-k 与原精确基线对照；授权过滤正确；模型/维度/版本不混用；ANN 有召回率与延迟证据 |
+| R10 | 支持未来多服务部署 | P1/P2 | 先验证两个真实 API/Worker 进程共享服务；业务表有模块 owner，后续服务通过契约操作他方数据 |
+
+R1 的人数及未来分布式方向由用户确认；下列量化指标是**建议的验收合同，待批准，不是当前性能结论**：
+
+- 基准环境建议：Linux、8 vCPU、32 GiB RAM、NVMe，记录 PG/应用的实际配额与网络；两实例验证分为同机多进程和后续双主机两种证据。
+- 阶梯负载：10→30→100 在线用户，最多 300 SSE 连接；初始全局活跃 Agent 执行预算 20（包含子代理）、每用户 2、索引任务 4。待执行队列最多 200，按用户/项目公平分配。已接纳 run 数与实际执行许可分别计数；父 run 等待子代理/HITL 时让出执行许可、保留会话所有权，恢复执行须重新获许可，避免额度用尽时父子互等。以上阈值由实测调整。
+- 数据量建议：100 万条消息/事件量级、10 万知识分块、多个项目与交叉授权用户；另测 100 万分块扩展档。记录数据分布与热点，不能只测空库。
+- 非模型普通 API：P95≤300ms、P99≤1s；SSE 持久事件可见延迟 P95≤1s；非预期失败率≤0.1%。预期限流/冲突单列，不能排除后不报告。
+- 先跑 60 分钟稳定负载，再跑 2 小时混合长稳；持续记录实际成功吞吐、排队、CPU/内存/IO、连接等待和模型配额。模拟模型用于容量基线，另保留真实模型少量全链路验证。
+- 数据正确性不变量在全部测试中零违反。数据库/Worker 故障恢复建议 RTO≤15 分钟；灾难恢复建议 RPO≤5 分钟、RTO≤60 分钟。主机/存储全毁不在单机“零丢失”承诺内；若要求该场景 RPO=0，需另行批准同步复制、故障域与可用性取舍。
+
+## 4. 技术决策与目标结构
+
+KTD1. **区分 local 与 team 部署档。** local 保留 SQLite；team 强制 PG、认证、独立实例 ID、受控工具执行和启动诊断。PG 暂时不可用时返回未就绪，不切回 SQLite。个人档不因浏览器人数变多而自动升级。
+
+KTD2. **PG 保存持久业务与调度事实。** 用户/项目/会话/消息/卡片/运行/幂等记录/命令/事件/checkpoint 元数据以 PG 为准。Redis 不成为任务完成、审批通过或永久幂等的唯一证据。初期使用同一 PG 实例和有归属的逻辑表/角色；后续拆服务时明确表的唯一写入模块，避免所有服务无约束共享整库。
+
+KTD2 的全部状态收敛以 U5 完成为界；此前有明确的单实例过渡边界，不能提前把本地状态当成缓存：
+
+| 数据 | 首期单实例团队版 | U5 后多实例版 |
+|---|---|---|
+| Backend 业务记录、幂等与恢复隔离标记 | PG 权威 | PG 权威 |
+| 尚未改造的 Squad FileStore、checkpoint、续跑标记 | 唯一实例的本地权威文件，联合备份，禁止跨机接管 | 版本/归属元数据在 PG，大内容在共享对象存储 |
+| 工件 | 本地对象目录，持久备份与 DB 清单绑定 | 共享不可变对象与 PG 发布记录 |
+| 临时执行目录 | 单实例/单 owner；先分类再清理 | owner+epoch 控制的可恢复工作区 |
+
+KTD3. **一个会话一次主执行，不同会话并行。** 推荐独立 conversation_execution 占用行，以 owner/会话唯一键、run_id、epoch、lease_until 约束；不对所有 runs 加“会话唯一”，以免禁止正常子代理。事务内完成权限检查、请求幂等、消息、主 run 和调度记录，接收成功以事务提交为准。
+
+KTD4. **短事务领取，租约与 fencing 配套。** Worker 通过 PG 行锁和 SKIP LOCKED 领取到期任务；事务提交后执行，模型/工具等待不得持有数据库事务。续租、事件追加、checkpoint、终态写入都校验 run+epoch。租约用 DB 时间，执行实例 ID 与每次启动的 generation 分开。旧 Worker 恢复后不能提交；租约过期也不等于外部命令已经停止。
+
+KTD5. **持久命令与提交事件同事务。** 取消/HITL/调度命令写入 PG inbox/outbox，带唯一 command_id、逻辑 run、执行代次与处理状态。运行级取消意图交给当前 owner，即使接受后发生接管也不能丢失；HITL 绑定稳定 gate_id+gate_version，新 owner 消费时重验 gate 与权限，过期审批明确拒绝而不静默丢弃。执行结果及确认仍须校验当前 epoch。批准数据与待投递命令原子提交，执行者幂等消费，处理确认与执行效果分别记录。关键外部动作必须有目标端幂等键、可查询凭据或人工恢复路径；超时结果未知时进入 recovering，不宣称任意工具 exactly-once。
+
+KTD6. **事件表是重放依据，NOTIFY 仅作唤醒。** 事件提交与 outbox 同事务；需要时在同事务使用 pg_notify。监听端维护每流连续 cursor，从 EventsAfter 分页追赶到通知水位；不能直接跳到末 seq。重建连接→LISTEN 生效→补查水位/积压，再转实时。增加周期补查，覆盖通知丢失、断线与通知前后竞争。只有落库事件才能发布可恢复的 SSE ID；纯瞬时进度明确可丢失，不冒充已确认业务数据。
+
+KTD7. **数据库乐观并发控制。** 项目设置、卡片、文档元数据等读改写带 version/expected_version；冲突返回 409 及新版本引用。重要唯一性/外键落在数据库，事务失败按错误类型有界重试整笔事务；提交结果未知先按幂等键查询。不能无限重试模型调用或发送动作。[PG 事务隔离与重试](https://www.postgresql.org/docs/current/transaction-iso.html)。
+
+KTD8. **数据库迁移独立于普通启动。** 单一 migrator 取得数据库锁，执行 append-only 版本；可事务化 DDL 与版本登记同事务。应用仅核对兼容版本和就绪状态。不能放入事务的在线索引变更单列可恢复运维步骤，不夹入普通迁移后声称原子。使用扩展→回填→切读写→收缩，保留兼容窗口。
+
+KTD9. **工件共享，工作区有执行 owner。** 先保留 blobstore 接口；跨主机上线前实现并验收 S3 兼容对象存储，DB 保存不可变对象键、校验和、版本与就绪状态。发布前先完整写对象再提交引用，失败孤儿可清理；删除采用标记和延迟 GC。工作区、检查点与 Squad 状态分开设计：checkpoint/调度版本入 PG，大内容入对象存储，本地工作区是受 owner/epoch 控制的暂存执行目录；需要接管时按清单恢复。共享目录和文件 rename 不能替代跨机所有权。
+
+KTD10. **Redis 只保存可恢复的加速状态。** 保留共享限流，改为 Lua 原子计数+过期或等价原子算法，键包含实例群/完整时间窗/owner，支持 ACL 凭据/TLS、连接与请求超时。故障时普通读取可降到本地保守限流；创建 Agent/昂贵工具等写入口仍受 PG admission 硬预算保护，不能无界放行。缓存带授权/内容版本，撤权同步失效或重新校验；先证明命中收益再加缓存。[Redis INCR 限流模式](https://redis.io/docs/latest/commands/incr/)、[分布式锁限制](https://redis.io/docs/latest/develop/clients/patterns/distributed-locks/)。
+
+KTD11. **pgvector 按“正确→测量→ANN”推进。** 复用现有全文+RRF+可选 rerank，先补 embedding profile/model/revision/dimension/content_hash/generation 身份，禁止同维不同模型混查；迁移为 vector 列并在 PG 做过滤和精确 top-k，再用基线对照决定 HNSW。权限适配器不能直接变成 SQL 时，由适配器提供受限授权候选集合或采用有界分批取候选+最终实时鉴权，不得无界加载所有 owner 后在内存过滤。授权过滤后的召回率单独验证；ANN 需要迭代扫描/分区等策略时以模型维度和版本实测选择。[pgvector 官方说明](https://github.com/pgvector/pgvector)。
+
+KTD12. **先管理连接池，再决定 PgBouncer。** 使 MaxOpen/Idle/IdleTime/Lifetime、查询超时可配置并输出脱敏有效值；总连接预算包含所有 API、Worker、LISTEN、migrator、监控与维护预留。100 在线用户不等于 100 DB 连接。未来接 PgBouncer transaction pooling 时 LISTEN 必须使用直连或 session pool 独立 DSN，迁移也走直连，并验证 pgx prepared statement 配置。[PgBouncer 兼容表](https://www.pgbouncer.org/features.html)。
+
+KTD13. **共享可读不等于可写或可批准。** 当前 EXT-8 `ProjectAuthz` 是只读 bool 契约。U3 先列 read/edit/approve/execute/admin 的动作授权矩阵，复用下游角色，不另建成员权威；需要共享写入时以版本化公开契约扩展 action-aware 授权，旧只读适配器不得自动获得写入能力。未配置的动作默认拒绝，Host/工具/API 均走同一授权结论；审批职责分离仍由下游规则判定。SSE 发送后续数据、异步任务开始和工件下载时重新校验当前授权，缓存失效不承担唯一安全责任。
+
+KTD14. **迁移副本按原数据敏感级别保护。** 备份、导出、WAL、工件和测试副本使用专用角色及受限目录；传输与静态备份加密，解密材料保存在独立受管秘密存储并纳入恢复演练。日志/报告只留统计与哈希，禁止正文、令牌及密钥明文；测试使用脱敏数据。U1 固定保留期限、存放位置、访问者与清理责任，未知项阻塞正式导出。正式恢复演练同时验证凭据可用性与非授权者无法访问副本。
+
+```mermaid
+flowchart LR
+  U[10–100 用户] --> G[入口与认证]
+  G --> A[API 实例 A / B]
+  A --> P[(PostgreSQL + pgvector)]
+  A --> R[(Redis 限流 / 可重建缓存)]
+  P --> W[Worker 领取任务 / 持久命令]
+  W --> P
+  W --> X[受控工具工作区 / 模型服务]
+  W --> O[(共享对象存储)]
+  A --> O
+  P --> E[事件追赶 / 本地订阅]
+  E --> U
+```
+
+```mermaid
+sequenceDiagram
+  participant C as 用户
+  participant A as 任意 API
+  participant P as PostgreSQL
+  participant W as 执行 Worker
+  C->>A: 提交 requestId / expected_version
+  A->>P: 短事务：鉴权、幂等、占用、消息、run、任务
+  P-->>A: commit / 冲突
+  A-->>C: 已受理与 runId / 明确冲突
+  W->>P: 领取任务并取得 epoch
+  W->>W: 事务外执行模型与工具
+  W->>P: 按 epoch 提交结果与事件
+  P-->>A: 唤醒后按 cursor 补齐
+  A-->>C: SSE 已提交事件
+```
+
+```mermaid
+stateDiagram-v2
+  [*] --> queued
+  queued --> running: 原子领取并分配 epoch
+  running --> waiting: 持久 HITL
+  waiting --> running: 幂等命令消费
+  running --> completed: 有效 epoch 原子结算
+  running --> recovering: 失联或副作用结果未知
+  waiting --> recovering: owner 失效
+  recovering --> queued: 已核对可安全重试
+  recovering --> interrupted: 需人工处理或不可恢复
+  queued --> cancelled: 取消命令生效
+  running --> cancelled: 执行者确认停止
+```
+
+## 5. 实施顺序与工作包
+
+每个阶段评审后再进入下阶段；以下均为待批准计划，不因写入文档取得实施授权。新测试文件标“新增”；现有测试只作为扩展入口，本次未运行。普通基座改动在 Backend；公开持久接口确需变化时才同步 Native/Squad/Core，并由 Dev 固定组合测试，不全库改造。
+
+### U1. 冻结目标、数据归属与基准环境
+
+对应 R1/R2/R7/R8。先确定目标为 Dev 团队实例及其实际发布制品，记录脱敏配置来源、DB 实例/版本/扩展、数据数量与归属、文件清单、磁盘容量、峰值和恢复目标。RDM 独立业务库、旧 Agent-System 治理库另列，不能把一次 DSN 切换宣称覆盖它们。
+范围：`runtime/dev` 部署配置（实施时核对文件位置）、`modules/backend/internal/config/config.go`、文档运行手册。
+产物：固定部署清单、迁移映射、容量合同（区分接纳与执行许可）、隔离测试库/目录/端口方案、KTD14 的副本保护与保留合同；确认暂态 Worker 文件哪些可重建，哪些必须迁移。
+验收：仅操作批准的实例和测试资源；共享数据凭据不打印；未知 owner 或未定位的权威文件阻塞迁移。测试：脱敏配置诊断及缺项校验，业务压测依后续 U7。
+
+### U2. 团队 PG 档、迁移器与真实数据库门禁
+
+依赖 U1；对应 R2/R3/R7。修改 `internal/config/config.go`、`internal/app/app.go`、`internal/store/store.go`、`internal/store/migrate.go` 及 CLI；按 KTD1/KTD8/KTD12 实施。
+CI 增加隔离原生 PG/Redis 生命周期及明确必跑标记，固定组件/扩展版本；缺少真实测试服务时该 job 失败而非跳过。
+测试：扩展 `internal/config/config_test.go`、`internal/store/store_test.go`；新增 `internal/store/migrate_atomic_test.go`。覆盖 team 缺 DSN/PG 故障拒绝启动、local SQLite 正常、两个 migrator 竞争、DDL 与账本中间崩溃、旧 schema 升级、PG bool/时间/空 JSON/唯一约束与全文扩展。
+出口：真 PG 完整 CRUD/认证/会话/SSE/检索/卡片链路通过；仅该出口不宣布多实例安全。schema 变更的组合测试与业务迁移是不同动作。
+
+### U3. 请求原子性、版本冲突与受控容量
+
+依赖 U2；对应 R3/R6/R7/R8。修改 `internal/server/server.go`、`internal/store/messages.go`、`internal/store/cards.go`、`internal/cardsvc/cardsvc.go`、设置读改写及 `internal/runmgr`。收口 KTD3/KTD7 的事务边界；保留现有 seq 约束。按 KTD10 完成 Redis 原子限流、配置与异常策略；PG 记录共享 admission 预算。按 KTD13 完成动作授权矩阵与所需公开扩展的兼容计划；涉及共享编辑时 Core/Host 与下游适配器一起验收。
+先补最小持久恢复隔离：为未知副作用记录 recovery hold，`ResumeInterruptedChildren` 等所有启动续跑入口必须跳过，人工核对后显式解除。概念状态 recovering 可以先由独立隔离记录表达；扩展 Core 枚举时走公开契约版本，不假定当前已有此状态。完整租约接管留 U5。
+测试：扩展 `internal/server/admission_test.go`、`internal/ratelimit/ratelimit_test.go`；新增 `internal/store/admission_pg_test.go`、`internal/store/card_version_test.go`、`internal/runmgr/recovery_hold_test.go`。覆盖相同请求重放、事务部分失败、同版本竞争、动作越权、子代理预算计入全局、所有父 run 占满额度后同时派生仍能前进、未知副作用重启不自动续跑、队列满、Redis 断连/恢复/键过期。
+出口：单 API 团队模式达到不变量与有界行为；不会把 20 个 Agent 配置值当作已证明容量。
+
+### U4. 可切换的迁移与恢复演练
+
+依赖 U2/U3；对应 R2/R7。新增 `modules/backend/cmd/storage-migrate/` 或等价受管运维入口，明确只处理 Backend 库；不得直接执行 SQLite dump 作为 PG SQL。迁移实例以 migration_id、source_snapshot_id、source_schema_version 固定来源，记录表级完成与最终验证完成标记；仅同一冻结快照可续传，其他非空目标拒绝。迁移报告包括每表计数、主键映射、按主键分批规范化内容校验和、外键/owner/权限检查及工件哈希。
+测试：新增迁移工具的 `main_test.go` 与 `integration_test.go`，固定脱敏 SQLite 夹具覆盖全部当前 schema、布尔/空值/时间/JSON/Unicode/二进制向量/秘密字段、幂等重复导入、缺文件、未知 owner、断点重试及目标已含数据拒绝。
+操作顺序与回退见第 6 节。出口：隔离环境迁移与恢复验证完成，由用户批准窗口后才切正式服务。
+
+### U5. 执行所有权、持久命令与共享状态
+
+依赖 U3，团队现网切换不必等待整个 U5；对应 R4/R6/R7/R10。修改 `internal/runmgr`、`internal/store/recovery.go`、`internal/squadadapter`、`internal/runtime/squad_runner.go`、`internal/blobstore`；新增 Store 的 lease/inbox/outbox 与 PG RunStore 适配器。
+按 KTD4/KTD5/KTD9 设计 Native checkpoint 接口，继续支持 local 文件实现；不把 JournalOnly 日志误当作业务上下文权威。Worker 工具沙箱与访问范围沿用现有方向，在执行端检查当前身份和 epoch。
+测试：新增 `internal/runmgr/multi_instance_test.go`、`internal/store/lease_pg_test.go`、`internal/blobstore/object_store_test.go`；扩展 `internal/runmgr/recovery_test.go`。必须启动两个真实进程：同会话争抢、不同会话并行、跨实例取消/HITL、命令提交后消费前 owner 换代、旧 gate 的审批明确失效、Worker 被杀、旧 Worker 迟到结算/写事件/写文件、失联重连、副作用结果未知、文件缺失/重复发布。
+出口：所有写入和工具副作用的失效 owner 处理有实证后，才允许第二实例承接写请求；故障状态可见，不能仅靠粘性路由。
+
+### U6. 事件追赶与数据库向量检索
+
+U6 内分三个交付切片，稳定工作包 ID 不变：事件追赶/重连修复依赖 U2，可与 U3 并行；事务 outbox 与投递闭环依赖 U5；向量 schema 与查询改造依赖 U2 迁移器及 U3 授权合同。对应 R5/R6/R9。
+事件：修改 `internal/pgbus/pgbus.go`、`internal/runmgr/events.go`、`internal/server/server.go`、Store 事件接口。扩展 `internal/pgbus/pgbus_test.go`，新增 `internal/server/sse_gap_test.go`：批次 64 条全部可见、断线补齐、通知丢失、订阅与补查竞争、1000+ 分页、慢消费者、撤权后新事件拒绝。第一切片完成只证明追赶修复，不声称 KTD6 的事务 outbox 已就位。
+向量：修改 `internal/store/vectors.go`、`internal/store/migrate.go` 与现有知识索引管线；新增 `internal/store/pgvector_test.go`。验证模型身份/维度隔离、内容更新/删除原子性、回填中重启、索引未完成可降级、中文全文混合、共享授权后 top-k、撤权、与精确检索 Recall@10 对照（建议≥0.95，待批准）。索引构建不得拖垮前台连接/IO。
+出口：先验证正确与有界，再按容量结果决定 HNSW 与缓存；绝不以 extension 存在替代查询计划/召回证据。
+
+### U7. 压测、故障验收与分布式放行
+
+依赖 U2/U3/U4；双实例验收另依赖 U5/U6。对应全部 R。首期单实例放行必须完整重放现有入口的 R6 权限矩阵（含 SSE 后续事件、共享检索、下载、Host/工具与撤权），并证明 U3 恢复隔离；不能等 U5/U6 才验证这些 P0 要求。跨实例传播与接管的新增验证随 U5/U6。新增 Dev `tests/load/collaboration/` 与 `tests/integration/multi-instance/`，由隔离测试入口负责启动/回收自己创建的资源。
+按第 3 节负载合同和第 7 节矩阵测量，记录原始 k6/pgbench、服务指标与数据不变量；pgbench 只测数据库能力，不能替代业务 API/SSE/Agent 验收。正式测试不打生产服务。
+出口：单实例团队、双进程、双主机分别出具结果；CI 身份/链接/SHA 或独立 REPLAY 可核验才用于放行。本地 SELF 只能作辅助。变更智能体行为时补真实模型前后任务级对照。
+
+远期 P2：需求达到后再拆 API/Worker/索引服务，按表归属收紧角色；引入 PG 高可用与自动故障转移、对象存储冗余、可选 PgBouncer。服务拆分与 DB 复制是两件事；Redis 集群、读副本和缓存不能替代主库一致性，读后写敏感路径保持主库读取或显式一致性令牌。
+
+## 6. SQLite → PostgreSQL 切换和恢复
+
+1. 固定源服务制品、全部数据库/文件路径与目标空库；指定迁移 owner、窗口、可接受中断和回退判据。先做只读盘点与隔离演练，不接触其他服务的数据。
+2. 为 SQLite 做一致性备份（应用已有 Backup/VACUUM INTO 或官方备份路径），同时生成工件/checkpoint/工作区清单。活跃 WAL 数据库不能只复制 `.db` 文件；检查备份可打开且内容与清单匹配。
+3. 预演使用独立测试目标 PG，由 migrator 建 schema/扩展，再按依赖顺序导入。显式保留 ID、幂等键、事件 seq、哈希/秘密、用户归属、共享范围、审批状态，调整序列值和类型。预演库不成为正式目标；所有副本遵守 KTD14。
+4. 最终窗口暂停新写与调度，等待或安全收口在途 run；无法确认外部副作用的 run 写入 U3 的持久 recovery hold。停止全部旧写者后取最终一致性快照，导入新空正式目标；按 U4 的同快照迁移身份续传。全量对账与验收抽样完成并写入完成标记后才可切入口，保留只读源备份及过渡期权威文件。目标已服务或身份不同的非空库不得覆盖。
+5. 仅一个入口切到 PG，检查版本/配置指纹、库身份与数据归属，执行用户登录、项目、会话、审批、检索、下载的冒烟；应用 fail-closed，不能故障后回 SQLite。原库不再写，不使用临时双写制造两个权威。
+6. **PG 接受新写入前**可撤回切换，确认目标未产生业务写后恢复 SQLite。**PG 接受新写入后**禁止直接指回旧 SQLite；优先保留 PG 回退兼容应用或向前修复。确需反向迁移，重新冻结写者、导出 PG 增量、对账并批准专门回迁方案。
+7. 建立 pg_dump 逻辑备份，以及 pg_basebackup（或等价物理基础备份）+ 连续 WAL 归档/PITR，并与对象存储版本/清单联合恢复；pg_dump 不能用作 WAL 回放的基础备份，保留足够不可变对象。每次演练恢复到新目标，核对应用可用与权限/文件完整性，不能把“备份命令成功”当作可恢复。
+
+SQLite 本身支持可靠事务与多人经同一应用访问；WAL 提升读写并发，但同一数据库仍只有一个 writer，且不适合多主机通过网络文件系统共享 WAL。取舍基于写负载、进程拓扑、恢复与运维目标，不用“超过某人数 SQLite 就出错”的判断。[SQLite WAL 官方文档](https://sqlite.org/wal.html)。
+
+## 7. 最小验收矩阵
+
+| 场景 | 必须观察到的结果 | 对应 |
+|---|---|---|
+| 同 requestId 并发/网络超时后重试 | 一个逻辑请求和同一 run，不重做已经确认的副作用 | R3/U3/U5 |
+| 两实例同会话不同请求 | 仅一个主执行；另一个排队或明确冲突，子代理不受错误唯一约束阻断 | R3/R4/U5 |
+| 多项目并行、热点会话、满额度父子派生 | 公平、有界；等待父 run 不阻塞子 run 获得许可，所有任务能前进或得到有界拒绝 | R1/R8/U3/U7 |
+| 并发修改同卡/设置 | 成功与冲突可辨认，无最后写入静默覆盖 | R3/U3 |
+| 在 B 提交 A 所有 run 的取消/HITL，消费前换 owner | 命令持久、唯一消费；取消随逻辑 run 生效，HITL 重验 gate 版本，卡片与 run 最终一致 | R4/U5 |
+| Worker 崩溃/暂停超过租约后恢复 | 新 owner 可受控接管；旧 epoch 不能提交；不明副作用不自动重放 | R4/R7/U5 |
+| PG 断连/提交响应丢失 | 依赖不可用有界失败；恢复按幂等记录核对，不自动切 SQLite | R2/R3/U3 |
+| Redis 断连/INCR 后崩溃 | 不改变业务事实；昂贵任务仍受硬预算；恢复无永久计数键错误 | R8/U3 |
+| 批事件/断开 LISTEN/通知丢失 | 所有已提交事件按连续 cursor 追赶，重放不跳洞 | R5/U6 |
+| 撤销成员权限/跨 owner 猜测 ID | 新请求、流后续事件与下载/检索/工具均不泄漏 | R6/U3/U5/U6 |
+| 多模型向量/过滤后 top-k | 不混模型，权限正确，召回/延迟达批准阈值 | R9/U6 |
+| 迁移崩溃/坏文件/未知 owner | 阻止切换；重试不重复导入，不隐式公开历史数据 | R7/U4 |
+| 磁盘满/备份恢复/整机失效 | 清楚拒绝写入和报警；在约定故障模型与 RPO/RTO 下恢复 | R7/U4/U7 |
+
+## 8. 工具、观测与交付
+
+本轮未安装软件、修改配置、运行迁移、重启服务或压测。brew 已有三项服务软件，当前瓶颈主要是接线与一致性机制，暂不重复安装。未来压测可通过 [brew 安装 k6](https://formulae.brew.sh/formula/k6)；PgBouncer 只在连接测量证明有必要后安装。安装授权不等于对共享数据库升级、创建扩展或变更服务的授权；执行前核对目标、版本与既有占用。
+
+必需观测：API P95/P99与预期/非预期错误，DB pool wait/连接数/慢查询/锁等待，队列长度/最老年龄，run 租约/过期写拒绝/未知副作用，SSE cursor lag/补查次数，Redis 错误与降级，检索耗时/召回抽样，备份时间与恢复结果。日志只记录 request/run/owner 的安全标识，不记录 DSN、密钥或文档正文。
+
+当前交付仅为 r1 方案与 SELF 调查记录。需求人数已确认；容量阈值、正式数据/部署目标、迁移窗口、灾难恢复等级和实施阶段尚待人工评审。没有业务测试 PASS、独立 REPLAY、CI GATE 或已部署声明。
+
+方案静态审阅及修订处置见[审阅记录](../records/2026-10-11-collaboration-storage-plan-review.md)。Agent 审阅不替代人工批准或实现验收。
+
+首选下一增量是 **U1 + U2 的详细实施与测试合同**：固定目标实例与 PG 测试环境，解决团队档、迁移原子性和真实数据库测试门禁。U6 的事件正确性修复可在单独授权后并行；不要先增加应用副本。各实现任务启动前复核在途 PR 与依赖 SHA，再按 Dev 的 evidence/task-sync/组合验证流程交付。

docs/proposals/INDEX.md

@@ -0,0 +1,160 @@
+# 项目方向与规划索引
+
+状态：**已获合入授权（2026-10-08）**。编制依据：用户同意整理既有规划主记录、确认状态、里程碑和关联任务；同日授权收尾并合入。
+本索引负责导航与差异提示，规划正文、批准范围和验收条件仍以链接的主记录及其批准版本为准。
+合入授权不批准新方向、不调整里程碑范围、不启动新的业务任务。
+
+## 先看哪一份
+
+新增方向（2026-10-11 用户已裁定关键取舍）：[Generative UI 调研与插件方案 r1](2026-10-10-generative-ui-plugin.md)。
+首试点为对话内完整分析页，交付采用可信编译插件；U1 试验限 MiniMax M3 + M2.7-highspeed、合成或脱敏材料、费用上限 ¥200，作为独立任务另行评审启动。
+此记录独立于下方历史核验快照，不改写历史方案/PR 数量或验收结论。
+
+| 要回答的问题 | 主记录导航 | 规划中的阶段 | 原文负责人 |
+|---|---|---|---|
+| 通用系统的原始边界与架构是什么 | [系统骨架](2026-09-29-system-skeleton-design-and-plan.md)，结合下表专题修订 | 骨架 P0–P5；D1–D16 | weichen |
+| 基座与下游如何分工，如何申请扩展 | [基座路线图](2026-10-01-base-extension-roadmap.md)，配套插件契约与兼容规则 | 公开扩展面、插件 v2、质量回路、工程基座 | weichen |
+| 三个智能体库如何继续演进 | [Agent 栈总案](2026-10-02-agent-stack-completion.md)，阶段细化见 N1/Q1/I1、N2、N3、Q2/Q3 | R0/R1/D1、N1–N3、Q1–Q3、I1–I2、阶段评测 | weichen |
+| RDM 下游的大目标和消费者里程碑是什么 | [RDM 阶段总案](2026-10-07-rdm-phase-plan.md) | P0–P4，对应 MS0'、MS1–MS4及发布前置 | weichen |
+| 10–100 人协作与未来分布式如何演进 | [协作存储与分布式方案](2026-10-11-collaboration-storage-and-distribution.md) | 团队 PG 档 → 迁移恢复 → 多实例执行与故障验收；r1 已批准（2026-10-11），实施自 U1+U2 启动 | 需求：weichen；实施/运维待指定 |
+
+以上是依据文内显式范围和引用形成的阅读入口，不是新增优先级或批准结论。N2 阶段案未单列 owner，
+应由负责人补齐；不能仅凭任务创建人推断全部规划的负责人。
+
+## 快照与状态口径
+
+本次只读核验时间：**2026-10-07 13:27 UTC**。来源均为 **SELF** 的文件、Git 与 API 观察，
+原始命令、对象和输出见 [核验收据](../records/2026-10-07-planning-index-source-receipt.json)，
+可检索字段见 [核验快照](../records/2026-10-07-planning-index-source.json)。
+
+- Dev 基线：`eb0d4b5a499322a23155c8d89a024247f6e7830d`。
+- 该基线固定的 Documents：`b8eaa1676f168ad64c437857e2607e2e213f6672`，包含下表前 18 份方案。
+- 查询时 Documents main：`5542319a0474fd4e866b6daacb937b587c833ede`；额外包含 N2 阶段案。
+  前 18 份文件在两个 Documents 版本中的 blob 完全相同。此候选索引基于该 Documents main 编制。
+  因此本地 Dev 候选指针同时包含 N2 方案文件；批准并采纳这个组合会纳入该文件，仍不等于批准其业务实施。
+  远端 Dev 是否采纳及在途 #244 的衔接，按实际合入时重新核对。
+- 查询的 55 个关联 PR 中，54 个已合入且合入提交属于各自固定 main；编制时 Dev #244 尚未合入。
+  所查 PR 的 reviews 数组均为空。这不能证明不存在会话批准，也不能补作人工批准依据。
+- 合入前同步（2026-10-08）：Documents `origin/main` =
+  `16795ed59820eee1d36efe6564e13a2f5a6387a6`，在上述查询版本之上新增 N3（Documents #43）
+  与 Q2/Q3（Documents #44）。Dev `origin/main` =
+  `7f1d87dbb976ebe02ceb632d5a657a416ffb50bc`。新增行与 N2/N3/Q2/Q3 阶段行只按
+  `git log --merges` 核对合入提交；没有重放各任务测试。合入不等于阶段验收重验。
+- 下表“原文确认/状态”保留作者声明；“已合入”只描述本次核实的 Git/PR 状态。
+  这份来源快照不包含业务里程碑、用户流程、部署或下游状态的复验，这些验收为 **NOT_RUN**。
+  本地候选组合的 `make test` 用于检查文档指针组合，不代替各规划的业务验收。
+
+使用更新版本时重新核对快照，不把这里的历史状态当实时任务台账。原文仍为 proposed/待审，
+或批准来源不能关联到确定版本的，保留待核实；已经归档的任务也须检查剩余范围。
+
+复核方法：读取 Gitea 的 `/api/v1/repos/weichen/{repo}/pulls/{number}` 及其 `/reviews`，
+再在对应仓运行 `git merge-base --is-ancestor <merge_sha> <固定 main SHA>`；文档采用情况按
+`git rev-parse <Documents SHA>:<文件路径>` 比较两个版本的 blob。API 状态与 Git 包含关系同时记录。
+
+## 全部规划与关联交付
+
+下表覆盖同步后 Documents main 中的 **21 份 Markdown 方案**（原查询版本 19 份，加上 N3 与 Q2/Q3），不含本索引自身。
+Dev 链接均指向对应任务 PR，可从其任务卡继续追溯组件 PR；不表示完整业务验收通过。
+
+| 主记录 | 角色、里程碑或范围 | 原文确认/状态（声明） | 关联合入记录与待核实项（SELF） |
+|---|---|---|---|
+| [系统骨架](2026-09-29-system-skeleton-design-and-plan.md) | 历史规划起点；P0–P5、D1–D16；后续有专题局部修订 | 待审 r4；决策勾选仍空 | [历史 P0–P5 实施记录](../records/2026-09-29-implementation.md)可定位阶段和提交；本轮未建立完整独立批准/验收链，不把记录勾选当当前验收 |
+| [双档存储与多租户](2026-09-30-dual-tier-storage-and-multitenancy.md) | 明确局部修订骨架：多租户/RAG 前移，SQLite 默认、PG 可选；D17–D24 | accepted，页首称实施完成 | [四阶段实施记录](../records/2026-09-30-dual-tier-implementation.md)及[历史测试报告](../reports/2026-09-30-dual-tier-test-report.md)；本轮未据此宣称当前多租户/RAG 已验收 |
+| [启动配置面](2026-09-30-configuration-surface.md) | 配置管道、实例隔离；配置专题 | 已批准（随实现交付） | Dev [#12](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/12) 已合入 |
+| [跨会话读取](2026-09-30-cross-session-reading.md) | 同项目 transcript 按需读取、权限和入口 | 已批准（随实现交付） | Dev [#67](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/67) 已合入 |
+| [交互底座](2026-09-30-ui-inbox-command-workspace.md) | T0–T5：基础、卡片/命令、收件箱、命令总线、工作区、体验收尾 | 已批准总体方案与 T0 计划 | Dev #14/#15/#19/#21/#23/[#25](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/25) 已合入；各 PR 见快照 |
+| [UI 重构与认证](2026-09-30-ui-redesign-and-auth.md) | 交互底座后的 R1–R4 与补充修订 | accepted（方向及 R2 范围）；页首管理员发放制覆盖旧注册方案 | Dev #30/#37/#43/#53/#61/[#71](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/71) 已合入；R3 与旧正文差异见下表 |
+| [卡流与过程分离](2026-09-30-cardflow-and-process-split.md) | CF0–CF2；D39–D43 | 已批准（原文记录用户五项裁定） | Dev [#79](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/79)、[#90](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/90) 已合入 |
+| [流式卡片、工件统一与项目收件箱](2026-09-30-card-stream-artifact-unify-project-inbox.md) | CF-S → CF-A → CF3；D44–D52；承接卡流案 | 已批准（声明） | Dev [#100](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/100)、[#103](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/103)、[#105](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/105) 已合入；保留后台 producer 等边界 |
+| [文件预览与保留能力](2026-09-30-file-preview-and-reserved-capabilities.md) | 工件管理后续；预览基座、Office、URL、fs | 已裁定（§5）；实施任务已命名 | Dev [#77](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/77)、[#94](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/94) 已合入；PPTX 与右栏口径待对齐 |
+| [基座路线图](2026-10-01-base-extension-roadmap.md) | 基座/下游边界总记录；显式引用 harness 与栈总案 | 实施中 | Dev [#132](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/132) 已合入；不能据此推断 tag、npm 或下游验收完成 |
+| [插件契约 v2](2026-10-01-plugin-contract-v2.md) | 路线图配套；声明、进程内、sidecar、前端 ESM 与生命周期 | 实施中 | 与路线图同任务、Dev #132；四种形态的当前运行状态未重验 |
+| [扩展兼容规则](2026-10-01-extension-compat-policy.md) | 路线图配套；兼容窗口、快照、版本发布与申请流程 | 实施中 | Dev #132；EXT-5 文档补充接口方法快照；发布动作另有双钥匙边界 |
+| [Agent harness](2026-10-01-agent-harness.md) | P0–P4 前序总案；明确后续栈总案不使 P0–P4 作废 | proposed | Dev #134/#136/#138/#140/#142/[#144](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/144) 已合入；参见阶段导航 |
+| [Agent 栈总案](2026-10-02-agent-stack-completion.md) | 当前库分期范围入口；承接 harness | proposed | 文档 Dev [#151](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/151)；R0/R1/R2/D1 及后续交付见阶段导航 |
+| [EXT-1](2026-10-05-ext-1-inproc-command-handler.md) | 扩展申请；owner 作用域 Host 与进程内命令最小集 | 实施中 | Dev [#207](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/207) 已合入；[#209](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/209) 是任务卡恢复/复核轮，不是第二次公开面实现 |
+| [EXT-5](2026-10-06-ext-5-host-parse-document.md) | 继 EXT-1 开放宿主文档解析；不依赖未提交的 EXT-4 | 实施中 | Dev [#222](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/222)、修复 [#224](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/224) 已合入；下游接入和发布不等于完成 |
+| [N1/Q1/I1 实施案](2026-10-07-agent-stack-n1q1i1-plans.md) | 栈总案 §5 的三个阶段细化；明确不包含 N2/Q2/I2 | proposed | 文档 Documents [#40](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/40)、Dev [#226](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/226) 已合入；实施范围差异见下表 |
+| [RDM 阶段总案](2026-10-07-rdm-phase-plan.md) | 下游大目标、双仓及可退化约束；P0–P4 / MS0'–MS4 | proposed；§2.3 现状复核已回填（2026-10-08） | 文档 Documents [#41](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/41)、Dev [#229](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/229) 已合入；不代表 RDM 各阶段获准实施 |
+| [N2 实施案](2026-10-07-agent-stack-n2-plan.md) | 栈总案 N2 的六 WP：上下文、协议、工具、skills、子代理、装配 | 未单列确认状态及 owner；正文称 N2 开工 | Documents [#42](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/42) 已合入；Dev [#244](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/244) 已合入（merge `7e3ba10`），闭卡 [#247](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/247)。卡内自述六 WP 落地；本索引未重放 |
+| [N3 实施案](2026-10-07-agent-stack-n3-plan.md) | 栈总案 N3：持久与可观测 | 页首未单列确认状态及 owner；正文称 N3 开工 | Documents [#43](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/43) 已合入；Dev [#248](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/248) 已合入（merge `2836a87`），闭卡 [#249](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/249)。卡内自述六 WP 落地；本索引未重放 |
+| [Q2/Q3 实施案](2026-10-07-agent-stack-q2q3-plans.md) | 栈总案 Q2 拓扑与 Q3 收敛互通 | 页首未单列确认状态及 owner | Documents [#44](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/44) 已合入；Dev [#250](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/250) 采纳方案，[#251](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/251)（merge `452c00a`）与 [#253](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/253)（merge `c8ce4eb`）已合入。卡内自述 Q2/Q3 落地；本索引未重放 |
+| [智能体工作流质量改进](2026-10-09-agent-quality-improvement-plan.md) | 直连主路径质量：诊断→六项裁定→P0–P5 分期 + 模型 A/B；推翻 fs 工具默认关闭裁定 | 已获实施授权（2026-10-09 六项裁定）；首个增量 feature/agent-quality-phase01 | 随本提案 PR；诊断 SELF（真实运行转录）；基线报告见任务卡 |
+| [EXT 申请包 C1–C7](2026-10-08-ext-c1-c7-rdm-shared-contracts.md) | RDM 多人共享契约的基座最小扩展申请（EXT-6…EXT-12）：身份停用/受管配置/授权适配器/索引发布/分发守卫/Host 工厂/投影过滤 | proposed；需求依据=RDM U0 主记录（D1–D9 裁定，2026-10-08 合入） | 随本提案 PR；每条现状证据为 SELF·源码级（Dev 34a2bbe/backend fe7c245），运行态 NOT_RUN；受理后逐条另立实现任务 |
+| [EXT 申请包 G1](2026-10-09-ext-g1-b1-b3-exec-backend.md) | EXT-13…16：回合内共享检索、命令即工具、项目列表共享、执行后端接口 | proposed；需求依据=RDM 方案 V1.1 §3.3/§3.4/§5.3（2026-10-09 批复） | Documents [#52](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/52) 已合入；EXT-16 已实施（Dev #285，见其任务卡），其余受理评审待定。本行由本次索引维护补充 |
+| [子代理分工、模型分级路由与任务沙箱](2026-10-10-agent-delegation-routing-sandbox.md) | 方向主记录：委派契约与角色路由方案（E1–E5 增量）+ 任务工作区沙箱设计（仅记录不实施）；修正 overlay≠快照等三处假设 | proposed（2026-10-10）；E1、E3、E4(R4+账本)、E5(R3)、S0-1 已完成（E4：Dev #315；S0-1：Backend #135/#136、Dev #318，2026-10-11）；E2 暂缓（模型指示）、S0-2 待授权 | 随本提案 PR；现状核查与启动延迟为 SELF（任务卡 evidence）；外部来源 URL 全量随任务卡 |
+
+原查询的 19 份原文中，14 份显式标注 owner 为 weichen。双档存储、启动配置面、跨会话读取、文件预览和
+N2 实施案这五份未单列 owner，其中预览案仅写“作者：weichen + Agent”。同步新增的 N3 与 Q2/Q3 案页首也未单列 owner。
+这些负责关系待确认，不能由作者、任务创建人或 PR 账号代填。确认状态只是上述版本原文的摘录，独立批准凭据需要另行关联。
+UI 的 [演示入口](ui-redesign-demos/index.html) 与四份样稿归属于 UI 重构方案，不是另外五个已批准规划。
+
+## Agent 栈的阶段与关联任务
+
+显式关系：基座路线图 → harness（前序，不作废）→ 栈总案 → N1/Q1/I1、N2、N3、Q2/Q3 阶段案。
+RDM 总案把库分期作为支撑与依赖，不覆盖库分期的原始范围。
+阶段 N2 指“上下文、协议与工具”，不是审计报告中同号的“并行工具事件竞争”缺陷。
+
+| 阶段 | 主记录与关联任务 | 核验结果与继续工作的边界 |
+|---|---|---|
+| harness P0–P4 | harness 对应 `feature/agent-harness-p0` 至 `p4`，含 p3b | 上表六个 Dev PR 已合入；旧卡“后续尚未实施”只属于当时快照 |
+| R0/R1、R2、D1 | 栈总案；`feature/agent-stack-r0-r1`、`r2`、`d1` | Dev [#152](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/152)、[#154](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/154)、[#156](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/156) 已合入；不得把同号审计缺陷误作阶段名 |
+| N1 | N1/Q1/I1 案 §2；`feature/agent-stack-n1` | Dev [#232](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/232) 已合入；状态与范围差异已于 2026-10-08 回填至[主记录 §7.1](2026-10-07-agent-stack-n1q1i1-plans.md)（WP6b/6c 等转出项带归属，均未被后续阶段承接） |
+| Q1 | 同案 §3；`feature/agent-stack-q1` | Dev [#237](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/237)、[#240](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/240) 已合入；platform task 与 squad run 的统一边界已厘清并回填至[主记录 §7.2](2026-10-07-agent-stack-n1q1i1-plans.md)（Store 层合一已做，队列翻译转出且 Q2/Q3 未承接） |
+| I1 | 同案 §4；`feature/agent-stack-i1` | Dev [#234](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/234)、[#235](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/235) 已合入；blueprint entry、SetSlot/Cancel/Handoff 等后续边界已回填至[主记录 §7.3](2026-10-07-agent-stack-n1q1i1-plans.md) |
+| I2 | 栈总案 §5/I2；`feature/agent-stack-i2` | Dev [#242](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/242) 已合入；主记录已加状态回填（[栈总案 I2 节](2026-10-02-agent-stack-completion.md)），I2 卡断链已在 Dev 侧修正；开启态完整用户验收未重放 |
+| N2 | N2 阶段案；Dev [#244](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/244)，闭卡 [#247](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/247) | 2026-10-08 同步时已在 Dev main。#244 标题是接入方案并开启任务；完成声明在已归档任务卡，本索引未重放其测试 |
+| N3 | [N3 实施案](2026-10-07-agent-stack-n3-plan.md)；Dev [#248](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/248)，闭卡 [#249](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/249) | 方案与任务卡已合入。完成声明在已归档任务卡，本索引未重放 |
+| Q2 | [Q2/Q3 实施案](2026-10-07-agent-stack-q2q3-plans.md) 第一部分；Dev [#250](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/250)、[#251](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/251) | #251 已合入。完成声明在已归档任务卡，本索引未重放 |
+| Q3 | 同案第二部分；Dev [#253](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/253) | #253 已合入。完成声明在已归档任务卡，本索引未重放 |
+
+原始任务卡在 Dev 仓 `.task/archive/`。任务主记录和既有分工优先复用，
+索引整理不重新领取或另建相同业务任务。
+
+## RDM 里程碑：规划目标与核验边界
+
+以下名称、窗口与依赖来自 RDM 总案 §1、§4，**只保留计划，不表示已承诺或已验收**。
+
+| 阶段 | 原规划目标 | 核验边界 |
+|---|---|---|
+| P0 / MS0' | 奠基、组织决议、基线与 v0.2.0 前置 | 复核（2026-10-08，[总案 §2.3](2026-10-07-rdm-phase-plan.md)）：v0.1.0 六 tag 在位、O1/O3/O7 已决议（RDM 00-V2定稿决议）、P0 已在下游关账（RDM #91）；**v0.2.0 仍未发版（owner 双钥匙，窗口 10-25 前）** |
+| P1 / MS1 | W4 上传五步与两速入库（原窗口 2026-11-01） | 复核（2026-10-08）：下游首批已落地（F1 v1、两速、D8 等）；七条验收 = 2 满足（重放）/2 部分/1 阻塞（EXT-5 不在 v0.1.0 pin）/1 口径不成立/1 未满足（对话入口），**不可签收**；详见总案 §2.3 MS1 核对表 |
+| P2 / MS2 | W7 基线、三分类与版本链（原窗口 2026-11-22） | 复核（2026-10-08）：状态机/版本链/三分类门控/需求大表等首批已在下游合入；MS2 正式验收 NOT_RUN（含 O2 提案待拍板） |
+| P3 / MS3 | W11 两树一网、变更闭环、一键生成（原窗口 2026-12-20） | 复核（2026-10-08）：追溯网/冲突/变更 UI/起草等首批已在下游合入；库分期前置（Q1/Q3/I1）已全部合入，其转出项见 N1/Q1/I1 案 §7；MS3 正式验收 NOT_RUN |
+| P4 / MS4 | W16 自举与演示（原窗口 2027-01-24） | 复核（2026-10-08）：自举语料/周报/立项例程等首批已在下游合入；EXT-3 仍未申请（截止 W10 前）；MS4 正式验收 NOT_RUN |
+
+~~总案引用未入本仓的 further-objective 01–13，以及下游仓的奠基材料。它们是明确的来源缺口。~~
+**来源缺口已关闭（2026-10-08 复核）**：further-objective 01–10 已权威迁入 RDM 仓
+`docs/requirements/`、11–13 迁入 `docs/materials/`（RDM #42）；抽查 08/10 号与原件逐字
+一致，01 号为 V2.0 定稿升版（属正常演进）。Dev 仓 `.tmp/` 私有目录仍被 exclude，未入 Dev 仓；
+引用愿景编号时以 RDM 仓内权威正文为准。
+
+## 待澄清与待同步项
+
+这些条目登记文档之间的差异，不代替产品裁定，也不静默重写原方案。
+原文已有明确后续裁定的，只需同步旧叙述；缺少可定位的范围变更依据时，才提交负责人确认。
+
+| 项 | 可复核位置 | 需要确认或补齐的内容 |
+|---|---|---|
+| 批准版本 | 各方案页首；核验快照的 reviews | 把原文 proposed/待审/accepted 与实际批准范围、版本和来源关联；PR 合入不能自动补齐实施授权 |
+| 负责人缺项 | 双档、配置、跨会话、预览及 N2 案页首 | 五份未单列 owner，预览只有作者；由项目负责人确认维护与决策职责后回填主记录 |
+| 骨架局部修订 | 骨架 §2.2/§7.2 与双档专题“方向修订”；骨架结尾 D1–D15 与新增 D16 | 保留双档专题明确修订关系，补齐决策范围与批准依据，避免继续照旧“多租户/RAG 远期”执行 |
+| UI/auth 与预览 | UI/auth 页首及 §5.1；预览 §3/§4/§5；交互底座 D25 | 页首管理员发放制已否决旧注册方向，但旧正文仍在；PPTX 全保真裁定与文本大纲叙述、右栏预览与纯收件箱边界需对齐 |
+| 卡流实施口径 | 卡流里程碑的旧 D34–D37 与 D39–D43 表；CF-A/CF3 任务卡剩余项 | 校正编号与阶段范围，保留 CF-A 前端零改动和 CF3 后台 producer 等实施边界 |
+| N1/Q1 完成口径 | **已处理（2026-10-08）**：[N1/Q1/I1 案 §7 回填](2026-10-07-agent-stack-n1q1i1-plans.md) | 各项“完成/转出/待做”已带依据、归属与适用版本；回填为 SELF 层记录，未重放各任务测试 |
+| I1/I2 归属 | **已处理（2026-10-08）**：I2 卡断链已修正（Dev 侧归档卡）；I2 状态回填至[栈总案 I2 节](2026-10-02-agent-stack-completion.md)；未接入消费者归属见 §7.3 | SetSlot/Cancel/Handoff 消费无阶段载体，需负责人排期 |
+| N2/N3/Q2/Q3 合入与验收 | Documents #42–#44；Dev #244/#247/#248/#249/#250/#251/#253 | 这些 PR 已在 2026-10-08 的 Dev main 上。本索引只登记 Git 合入，不把闭卡文案升级为重新验收 |
+| Q2/Q3 归档卡截断 | Dev `.task/archive/feature-agent-stack-q2.md` 与 `-q3.md` 的「影响与剩余项」行 | 两卡该行在归档中截断（106/97 字符，止于半句）；完整表述需对照 PR #251/#253 描述补齐或登记缺损 |
+| RDM 历史快照 | **已处理（2026-10-08）**：[RDM 总案 §2.3 现状复核](2026-10-07-rdm-phase-plan.md) | 逐行复核+MS1 七条核对+六项新缺口登记；收据 SELF（RDM 无 CI），见 records/2026-10-08-rdm-status-* |
+| RDM 双主记录关系 | RDM 仓 `docs/requirements/10-实施推进方案`（V1.2 定稿）与本仓 RDM 总案 | 裁定（2026-10-08，负责人确认）：前者为执行总案（下游任务在其仓内立卡引用），后者为基座侧消费记录（里程碑对齐、扩展点、库分期依赖）；下游执行细节冲突时以前者为准，里程碑与基座依赖以本仓总案为准；本仓总案不回写下游正文 |
+| RDM 仓无 CI | RDM 仓无 `.gitea/workflows`；PR status API 无 statuses | INV-3 的 GATE 来源不存在，下游完成声明止于 SELF；建议 RDM 接 act_runner 后，重大验收（MS1 签收等）以 CI 为权威源 |
+
+## 下一步建议与维护
+
+原首选任务（确认并修订 N1/Q1/I1/I2 阶段主记录的状态与范围差异）已于 2026-10-08 执行完毕：
+回填见 [N1/Q1/I1 案 §7](2026-10-07-agent-stack-n1q1i1-plans.md) 与栈总案 I2 节，I2 卡断链已修正。
+转出项清单显示 WP6b/6c、SetSlot/Cancel/Handoff 消费、platform task 队列合一、黑板可回放增量
+均无阶段载体，需负责人排期；「批准版本关联」与「负责人缺项」两栏仍待负责人确认。
+
+后续维护：主案或任务变化时先更新其唯一主记录，再更新这里的导航和核验快照。
+更换 Docs/Dev 基线后重新核对 PR、版本与在途任务；新的索引状态不自动产生实施授权。

docs/records/2026-10-02-agent-stack-audit.md

@@ -0,0 +1,169 @@
+# 记录：Agent-Native / Agent-Squad / Agent-Intent 只读审计
+
+日期：2026-10-02。任务主记录：Dev 仓 `feature/agent-stack-blueprint`。
+设计结论见 [2026-10-02-agent-stack-completion.md](../proposals/2026-10-02-agent-stack-completion.md)。本文只记证据，不实施修复。
+
+基线（Dev 顶层 `deps/`，`git rev-parse`）：
+
+- agent-native `c6d867cde7d87696feaf3073f097ca15b0145273`
+- agent-squad `590fd86f4c8bfada0ec76efbfb57133c61607bd6`
+- agent-intent `1dbbe8149c561b36282bf781e61a06d1284be3a1`
+
+方法：只读读码。P0 条目已对照源码复核。标注「待确认」的条目没有在本次复核中跑测试。路径相对各库根目录。
+
+## 1. 跨库与集成
+
+| 编号 | 级 | 现象 | 证据 | 影响 | 方向 |
+|---|---|---|---|---|---|
+| X1 | P0 | 测过的组合不等于发布的组合 | Backend `go.mod` replace 指向自己的 `deps/`：intent `7d9d505`、native `c6d867c`、squad `5cbac00`。Squad 自测钉 native `a34689c`、intent `3674dc4`。Dev 顶层是 intent `1dbbe81`、squad `590fd86`。Go 只认主模块的 replace | 各库测试全绿也不能证明产品编译的组合正确 | Dev 根 `go.work`；`make test` 断言 Backend 用到的 SHA 等于 Dev 指针 |
+| X2 | P1 | gitlink 递归嵌套 | `deps/agent-squad/deps/agent-native/deps/agent-intent` 等。agent-intent 在 Dev 检出里有多份副本，SHA 不完全一致 | 读码容易看错副本；磁盘上的嵌套仓不参与 Backend 编译 | 库仓不再嵌套兄弟库；适配器子模块用 go.mod 版本号钉依赖 |
+| X3 | P1 | 边界检查不管库与库 | `scripts/lint-boundaries.sh` 只禁止扩展 SDK 与示例 import `agent-system-backend/internal` | 实现级耦合没有门禁 | 用 `go list -deps` 断言核心模块不得依赖兄弟库 |
+| X4 | P1 | 内核为了一个没有调用方的包依赖 Intent | `deps/agent-native/go.mod` require `agent-intent`；唯一引用是 `adapters/intentgate`。Backend 零引用该包 | 内核不能单独使用 | 删除该适配器，或迁到独立子模块 |
+| X5 | P1 | Squad 公开 API 暴露内核类型 | `squad/backend.go`：`BackendFactory` 返回 `exec.Backend`；`AgentNativeConfig` 含 `*llm.Client`、`tools.SearchProvider`、`tools.ExecConfig`、`mcp.Manager`、`subagent.Factory`。`planner_llm.go` 的 `LLMPlanner.Client` 是 `*llm.Client`。`intent.go` 的 `IntentRunner` 返回 `*exec.Result` | 换执行器必须改 Squad 核心；编译期去不掉 agent-native | 核心只定义 Executor、ModelClient 端口；跨库代码进 `adapters/native` |
+| X6 | P1 | platform 绕过执行端口 | `platform/runtime.go` 的 `RunInProcess` 直接 `runtime.NewAgentSession` | 内核内部类型进入 platform 公开签名 | 经 Executor 端口 |
+| X7 | P1 | CLI 直接 import Intent | `deps/agent-squad/cli/cli.go` import `agent-intent/intent` | 与「只经 squadintent 接入」的约定不一致 | CLI 迁到独立 `cmd/`，经适配器装配 |
+| X8 | P1 | 同一概念多处定义 | 意图闸门：`squad.IntentGate`、`squadintent.Gate`、`adapters/intentgate`、`backend/internal/intentgate`。目录三套。HITL：Squad pending、Backend 卡片、命令确认、Intent 的 Question。预算：`exec.Budget`、Backend `RunBudget`、设置项。事件三套。工作流：`squad.WorkflowPlan` 与 `core.WorkflowDef`。结果状态：command 四态、intent 五分支、native 的 Success 布尔 | 扩展作者要对齐四套键：`handler`、`metadata.blueprint`、`CommandSpec.id`、`WorkflowDef.IntentID` | 每个概念一处定义，见提案第 4 节 |
+| X9 | P1 | 产品没有接上 Squad 的意图能力 | `modules/backend/internal/squadadapter` 未装配 IntentGate、Catalog、Runner | Squad 侧已做的目录注入与计划校验在产品路径不生效 | 组合根装配适配器 |
+| X10 | P2 | 模块路径是裸名 | `go.mod` 的 `module agent-native` / `agent-squad` / `agent-intent` | 第三方不能 `go get`，只能 replace | 改为可获取路径并打 semver tag。路线图已把改模块路径列为单独发版任务，不在本次 |
+
+## 2. Agent-Native（`c6d867c`）
+
+### P0
+
+| 编号 | 现象 | 证据 | 影响 | 方向 |
+|---|---|---|---|---|
+| N1 | 工具预算超限留下没有结果的 tool_calls | `runtime/loop.go` 先 `persist` 带 tool_calls 的 assistant，再在 `toolCalls+len > Max` 时 `budgetStop`。`budgetStop`（同文件约 542 行）不补工具结果 | 续跑时 OpenAI / Anthropic 会拒绝这段历史 | 超预算则不落盘该 assistant，或先写入合成的 error 结果再停 |
+| N2 | 并行工具的事件回调有数据竞争 | `executeParallel`（`loop.go` 约 366 行）每个工具一个 goroutine 调 `runOne`→`emit`。`adapters/native/backend.go` 约 332 行的 OnEvent 无锁写同一个 `strings.Builder` | `-race` 会报；日志交错 | 串行投递事件，或每工具私有缓冲再合并 |
+| N3 | MCP stdio 取消后读协程不退出 | `runtime/mcp/stdio.go` 的 `readResponseLine`：`ctx.Done` 返回后，后台 goroutine 仍在 `ReadBytes`。下次调用再起一个读者 | stdout 帧错乱、卡死 | 取消时关闭进程，或单读循环按 id 分发 |
+| N4 | 预设与真实客户端协议不一致 | `runtime/llm/client.go` 固定 POST `…/chat/completions`。`BuildBody` 的 Anthropic / Google 分支不被该 Client 使用。Anthropic body（`providers.go` 约 303 行）把 tool 结果收成普通 user 文本，不带 tool_use / thinking 签名，也不挂 tools | 选 anthropic / google 预设不能多轮工具 | 按 Protocol 分流真实客户端；未实现的协议不要出现在可用预设里 |
+
+### P1
+
+| 编号 | 现象 | 证据 | 方向 |
+|---|---|---|---|
+| N5 | token 预算只在回合开头检查，超限后本轮工具仍执行 | `loop.go` 用量在 consume 之后累加，执行工具前只查 `MaxToolCalls` | 累加后、执行工具前再查 token 预算 |
+| N6 | `Stop.Replacement` 只改内存 | `loop.go` 改最后一条消息内容，不 `persist` | 追加更正记录或提供改写 API |
+| N7 | compaction 按条数裁尾，可切断工具配对 | `runtime/session/compact.go` 的 `keepLastN` 不按 tool 组对齐。现有测试没有工具消息 | 裁切对齐 tool_calls 与 tool 结果 |
+| N8 | compact 与 append 有并发窗口 | compact 读完条目后解锁再摘要，再加锁追加 | 摘要期间禁止追加，或按版本号 CAS |
+| N9 | 会话追加无 fsync、无跨进程锁 | `runtime/session/tree.go` 用 `O_APPEND` 写，锁只在单进程内 | 可选 Sync；文档写明单写者，或加文件锁 |
+| N10 | 流式错误不落盘、默认不重试 | `loop.go` 遇到错误帧直接返回。`WithRetry` 只在 CLI 包装 | Backend 适配默认重试；写明错误帧是否落盘 |
+| N11 | SSE 不拼接多行 `data:` | `runtime/llm/sse.go` 逐行处理 | 按空行分事件再拼接 |
+| N12 | 取消一批工具时要等全部结束 | `executeParallel` 用 `Wait`；顺序路径工具之间不看 `ctx.Err()` | 批内协作取消；超时后仍写 error 结果以保持配对 |
+| N13 | fetch_url 有 DNS 重绑定窗口 | `runtime/tools/fetch.go` 先 `LookupIP` 校验，`client.Do` 再解析 | Dial 时连已校验的 IP |
+| N14 | 宿主自带 `CheckRedirect` 时跳过重定向校验 | `fetch.go` 仅在 `CheckRedirect==nil` 时包装 | 始终链式包装 |
+| N15 | write / edit 不是崩溃原子 | `runtime/tools/builtin.go` 直接 `os.WriteFile` | 临时文件再 rename |
+| N16 | 按字节截断，破坏 UTF-8 | `builtin.go`、`exec.go`、`mcp/manager.go` | 按 rune 回退 |
+| N17 | 工具 schema 校验过松 | `runtime/tools/registry.go` 不强制 `additionalProperties:false`，array / object 一律放行 | 至少拒绝未知键 |
+| N18 | MCP「失败重连一次」只有注释 | `runtime/mcp/manager.go` 注释与实现不符，失败只返回错误 | 实现或删注释 |
+| N19 | MCP HTTP `Close` 是空操作 | `runtime/mcp/http.go` | 发送 session terminate |
+| N20 | 用量把每轮完整历史的 prompt token 累加 | `loop.go` | 分开「上一请求」与「累计计费」 |
+| N21 | 毒化轮转状态只在内存 | `adapters/native/backend.go` 的 `lastFailure` | 旁路文件落盘 |
+| N22 | 提醒消息是追加的 user 角色 | `loop.go` 的 `withEphemeral`。OpenAI 在 tool 结果之后通常可接受。Anthropic Messages 是否拒绝，待确认 | 用提供方的 ephemeral / system 通道；补一条 Anthropic 往返测试 |
+
+### P2
+
+| 编号 | 现象 | 证据 | 方向 |
+|---|---|---|---|
+| N23 | `run_python` 的 `ScriptDir` 不经路径解析 | `runtime/tools/exec.go` 约 112 行：`filepath.Join(t.root, ScriptDir)`。该字段只能由宿主配置，模型参数改不了，因此从 P0 降为加固 | `Resolve` 后再用；单测覆盖 `..` |
+| N24 | grep / WalkDir 无文件数与总字节上限 | `builtin.go` 只有命中条数和单文件上限 | 加 maxFiles / maxBytes |
+| N25 | HTTP 客户端默认超时很长、无空闲读超时 | `runtime/llm/client.go` | ResponseHeaderTimeout 与读空闲超时 |
+| N26 | Registry 无锁 | `registry.go` 的 Register / Restrict 与 Execute 并发不安全 | 运行前冻结快照 |
+| N27 | SSE 工具名用 `+=` 拼接 | `sse.go` 若 delta 重复全名会拼重 | 仅空时写入 |
+| N28 | 绝对路径 jail 用未 Eval 的根做 Rel | `runtime/tools/jail.go`。symlink 根加绝对真实路径是否可绕，待确认 | 校验统一对已解析的根 |
+| N29 | `contract/` 与 `exec/` 两套契约 | `contract` 只有 conformance 的 fake 在用；native 实现的是 `exec.Backend` | 保留 `exec`，删除或并入 `contract` |
+| N30 | `native.Options` 汇集全部配置 | MCP、技能、压缩、宿主工具、执行、抓取、搜索在同一结构 | 按端口拆分 |
+| N31 | `adapters/native` 不透传 Stop / Reminders / RepeatGuard / BeforeTool | `adapters/native/backend.go` 的 run 不设置这些字段 | 小队路径拿不到直连的门禁。透传或由宿主显式配置 |
+
+缺测（本次未找到对应用例）：N1 配对、N2 race、N3 取消双读、N4 Anthropic 线上格式、N7 切断工具组、N13 DNS 重绑定、N6 持久化。
+
+## 3. Agent-Squad（`590fd86`）
+
+### P0
+
+| 编号 | 现象 | 证据 | 影响 | 方向 |
+|---|---|---|---|---|
+| Q1 | `RequiresApproval` 批准后再次挂起 | `squad/workflow.go` 约 60 行检查 `Approved["step:"+id]`。全仓只写 `Approved["role:…"]`（`engine.go` 约 578 行）。`Respond` 的确认只恢复挂起，不写 step 键 | 该步骤永不执行 | 批准时写入 `step:` 键并落盘；补回归 |
+| Q2 | 授权、修复预算、澄清、steering 不落盘 | `runState` 有这些字段（`squad/runstate.go`）。`save()` 只写 workspace、workflow、squad、blackboard、usage | 重启后授权丢失、修复预算归零 | 原子写入 `runstate.json`，Resume 必读 |
+| Q3 | 状态文件不是原子写 | `squad/workspace.go` 的 `writeJSON` 直接 `os.WriteFile`。只有黑板用临时文件再 rename（`blackboard.go`） | 崩溃留下半截 JSON，Resume 失败 | 统一 tmp + Sync + rename |
+| Q4 | Resume 会重跑 status=running 的步骤 | `advance` 只跳过 completed / skipped / failed（`workflow.go` 约 33 行）。崩溃可留下 running。`Resume` 无挂起则直接 `advance` | 写文件、工具、MCP 副作用重复 | 步骤 attempt id；恢复前把 running 标成待重试并校验产物 |
+| Q5 | 没有跨进程 run 锁 | `engine.go` 约 144 行只有进程内 `map` | 两进程可交错写同一 run 目录 | run 目录文件锁，或单写者 |
+
+### P1
+
+| 编号 | 现象 | 证据 | 方向 |
+|---|---|---|---|
+| Q6 | HITL 超时字段未实现 | `hitl.go` 有 `TimeoutAfter` / `ExpireAction`，无扫描 | sweeper 按到期动作合成决策 |
+| Q7 | `Respond` 先删 pending 再应用决策 | `engine.go` 约 477 行先 `saveGate(nil)`。二次回应走「无挂起」 | 先记 answered 再删 |
+| Q8 | wakeup 自动批准 confirmation / permission / quality | `engine.go` 约 901 行 | 高风险 kind 禁止自动批准 |
+| Q9 | `SweepWakeups` 在锁外改 `WakeupFires` | 先自增写盘再 `Respond`（锁在 Respond 内） | 整段放进 run 锁 |
+| Q10 | 并行组无 fail-fast，且丢掉 gate | `runParallel` 等全部结束；忽略 `runOneStep` 的 gate | 失败即取消兄弟 |
+| Q11 | 步骤间上下文是过期快照 | `BuildSubWorkspaces` 用当时黑板写 `TASK.md`，顺序执行不刷新 | 每步前用最新黑板和上游产物索引重写 |
+| Q12 | LLM 规划失败无回退、无规模上限、目标原文注入 | `planner_llm.go` fail-closed；prompt 直接拼 `Goal.Text` | 可配置回退；目标分段；硬上限 |
+| Q13 | intent 步要求注册表里存在名为 intent 的角色 | `materialize` 对每步 `Registry.Get(role)` | `IntentID` 非空时跳过普通角色检查 |
+| Q14 | Server 与 platform HTTP 无鉴权 | `server/server.go`、`platform/http.go` | 至少 API token |
+| Q15 | run id 未校验 | `filepath.Join(DataDir, "runs", runID)`，id 来自路径 | 拒绝非 `run_` 前缀的安全字符集 |
+| Q16 | 请求体无大小上限（webhook 除外） | `handleCreateRun` 无 `MaxBytesReader`；webhook 才有 256KiB | 全局 body 上限 |
+| Q17 | SSE 扇出关闭竞态、慢消费者丢帧 | `progress.go` default 丢帧；回放 goroutine 往已关闭 channel 写 | done 信号停回放 |
+| Q18 | 事件序号重启后从 1 重计 | `store/eventsink.go` 的 seq 只在内存 | 启动时读最后一行 |
+| Q19 | Claim 并发上限先查后改；未开 WAL | `platform/queue.go` 先 COUNT 再 UPDATE；`db.go` 只有 busy_timeout | 单条条件更新；`journal_mode=WAL` |
+| Q20 | 文件 runs 与 SQLite 两个真相源 | `platform/db.go` 注释；server 可同时挂两者 | platform 降为 Store 实现，状态以图执行为准 |
+| Q21 | `StepSpec.Needs` 未参与调度 | 只定义在 `models.go`。调度看相邻 `Parallel`（`workflow.go`） | 实现 DAG 或删除字段 |
+
+### P2
+
+| 编号 | 现象 | 证据 | 方向 |
+|---|---|---|---|
+| Q22 | leader 先 `Turns++` 再执行 | `leader.go` 约 242 行 | 成功后再递增 |
+| Q23 | `MaxLeaderTurns` 用尽直接失败，无降级收口 | `leader.go` | 可配置收口 |
+| Q24 | 步骤重试共享同一个 deadline | `workflow.go` 约 209 行。短超时下重试几乎无预算 | 文档写明，或每次重试单独预算 |
+| Q25 | 角色与蓝图写盘忽略错误 | `store.go` 的 `_ = os.WriteFile` | 原子写并返回错误 |
+| Q26 | 人工 retry 直接把修复预算加一 | `engine.go` 约 608 行。是否有意，待确认 | 设上限 |
+| Q27 | 拓扑写死 | standard / leader / router 在引擎内分支，无 Topology 接口 | 插件接口 |
+
+缺测：Q1 全路径、Q4 从 running 恢复、Q5 多进程、Q6 超时、Q8 自动批准、Q15 路径穿越。
+
+## 4. Agent-Intent（`1dbbe81`）
+
+### P0
+
+| 编号 | 现象 | 证据 | 影响 | 方向 |
+|---|---|---|---|---|
+| I1 | `Classifier.Refine` 返回值不校验 | `intent/recognizer.go` 约 97–123 行：不检查 ID 是否属于原候选，不把置信度限制在 0 到 1，不禁止改 Metadata / Handler。失败才保持 Ambiguous | LLM 分类器可以把任意 ID 抬成 Top | ID 集合必须相等；置信度钳制；禁止新增特权字段 |
+| I2 | 槽位校验器是进程级全局表 | `intent/slots.go` 的 `slotValidators sync.Map`，无注销、无命名空间 | 多 Registry 同名互相覆盖 | 挂到 Registry / Options |
+
+### P1
+
+| 编号 | 现象 | 证据 | 方向 |
+|---|---|---|---|
+| I3 | 中文子串匹配、无词界 | `intent/registry.go` 约 120 行 `strings.Contains`。语料只有正向命中 | 词界模式或最短词长告警；补假阳性负例 |
+| I4 | 只做 `ToLower`，无 NFKC / 全半角 / 繁简 | `recognizer.go` 折叠；slot normalize 仅 trim / lower / upper | 可选 NFKC；文档写明无繁简 |
+| I5 | 同分恒为 Ambiguous，priority 不参与裁决 | 分差小于 margin 即 Ambiguous（`recognizer.go`）。priority 只用于排序 | 允许 margin 为 0 时按 priority 决胜。当前 `<=0` 会被改回 0.1（`registry.go`） |
+| I6 | 分类器解歧后的 Top 可能没有槽位 | `candidatesOf(..., false)` 先不抽槽 | 裁决成功后再对 Top 抽槽 |
+| I7 | Snapshot 的 Metadata 浅拷贝 | `SpecByID` / `Catalog` 拷贝 map 但共享底层 | 深拷贝 |
+| I8 | Catalog 整表输出 Metadata 与 Handler | `intent/catalog.go` | 白名单键；默认不进 Markdown |
+| I9 | 闸门钉死旧 `*Snapshot` | `squadintent/gate.go`、`adapters/intentgate` 不持有 Registry | Reload 后须重建，或持有 Registry |
+| I10 | 识别是全量线性扫描 | `evalRules`，上限 2048 | 规模上来再做倒排；先写明上限 |
+| I11 | 多槽位各自第一次匹配，无重叠消解 | `intent/slots.go` | 文档写明；冲突时标歧义 |
+| I12 | 否定只靠 `excludes_any` 子串 | 语料 `negated_write_readonly` 依赖硬编码「配置」 | 不在库内做语义否定；交给命令层的 Cancel |
+
+### P2
+
+| 编号 | 现象 | 证据 | 方向 |
+|---|---|---|---|
+| I13 | pattern 无长度上限 | 条数上限 `MaxPatternsPerSpec=32`，单条无长度限制 | 构建期限制长度 |
+| I14 | 评测语料约 10 条，无 precision / recall | `testdata/corpus.json` | 多轮、逐轮期望命令，输出指标 |
+
+已核实相对健全：Snapshot 用原子指针交换且失败保留旧快照；正则在构建期编译（RE2）；同分排序稳定（score、priority、注册序）。
+
+## 5. 与产品侧的关系（不在三库内，供路线引用）
+
+这些能力今天在 Backend，提案主张下沉到库，本次不改：
+
+- 终轮验证与计划提醒：`modules/backend/internal/runtime/verify.go`
+- 评审流水线：`internal/runtime/review.go`
+- 工作流执行与 critic：`internal/runtime/workflow.go`、`internal/workflow/`
+- 子代理循环与 profile：`internal/runtime/sub_loop.go`、`internal/prompts/library/agent-sub-*.md`
+- 后台子代理通知：`internal/runmgr/runmgr.go`
+- 直连回合：`internal/runtime/llm_direct.go`（约 692 行）
+
+`core.WorkflowDef` 仍是插件作者面对的契约。执行器与 `squad.WorkflowPlan` 是两套编排。

docs/records/2026-10-03-pi-durable-review.md

@@ -0,0 +1,94 @@
+# 调研：pi `packages/durable`（Pico5）有什么可以借鉴
+
+## 更正（v1.0.1，2026-10-03）
+
+对照对象已从本地克隆 `c7cdb460`（2026-09-21）前进到 [earendil-works/pi](https://github.com/earendil-works/pi) `4c6fb7cfe8c538a668726f6f8b3554098c39faee`（2026-10-03，v1.0.1）。下面四条替换正文里对应的判断；正文保留，作为当时的证据。完整二次对照见 [2026-10-03-pi-zcode-second-pass.md](2026-10-03-pi-zcode-second-pass.md)。
+
+- **Packages 1–23 已经实现。** `packages/durable/docs/pico-v5-handoff.md` 的状态栏不再是 “No Pico5 implementation exists”。可运行的内容包括会话、工具回合、收件箱、中止、子代理句柄、结构化并发、压缩与溢出、扩展，以及生命周期和任务图。存储有内存、SQLite、JSONL 三套，并带一致性测试。正文 §1 的“只有记录契约和一份内存存储”只对 `c7cdb460` 成立。
+- **不把 `@earendil-works/pi-durable` 或 Chord 当依赖引进来，这个结论不变。** 包仍标 Experimental；Chord 仍声明不是稳定公开契约；实现是 TypeScript，本仓执行与存储在 Go。
+- **正文 §2.2 的试点规则升级为采纳设计。** 重放取交集、意图与结果分两次提交、先写者胜出的 memo、内存实现作语义参照、侧车提交标记、压缩只追加并带 head 指针，都已有可对照的实现。落地仍在后续批次，不在本更正里改代码。结果状态继续对齐 A2A，不新增 `faulted` 枚举。
+- **`packages/agent` 里的实验内核 pico3 已在 v1.0.0 删除。** 正文引用的 `effect_pending` 与 `replay: "never" | "safe"` 现位于 durable 的工具任务。不要再把 pico3 当参考入口。
+
+透明续跑仍然暂缓：骨架设计 §4.2 不做。服务端 steer、会话分叉和所有权级联改为条件试点，触发条件仍是正文 §2.3 写的那些产品需求。
+
+- 状态：记录（2026-10-03）；owner：weichen；任务：Dev 仓 `feature/pi-durable-borrow`
+- 对象：本机参考克隆 `/home/weichen/projects/Agent-System/.refs/pi`，`origin` 为 `https://github.com/earendil-works/pi.git`，HEAD `c7cdb460aa8a0cebef3446c4166729b8a0d97ead`（2026-09-21，`fix(coding-agent): reject bug reports offline`）。包版本 `@earendil-works/pi-durable` 0.86.1，MIT（仓库根 LICENSE 版权 2025 Mario Zechner；`packages/durable/package.json` 的 `license` 为 MIT）。
+- 对照的本仓事实以 Dev `a5c9fd3385` 为准。库层对照的是提案 [2026-10-02-agent-stack-completion.md](../proposals/2026-10-02-agent-stack-completion.md)（Documents PR #34，本记录合入时已经在 documents main）及其审计记录。
+
+结论先说：**不把这个包或 Chord 当成依赖引进来。** 它现在只有记录契约和一份内存存储。值得拿走的是几条恢复规则，而且用我们已有的表和事件词汇就能落地。本任务在 Backend 修四个已经核实的缺陷；库层规则写在这里。提案已经合入，在提案里加链接留到后续小任务，本记录不改提案正文。
+
+---
+
+## 1. 这个包实际有什么
+
+`packages/durable` 的 README 写明公开 API 是持久记录契约和一份脱离调用方的内存存储。交接文档 `docs/pico-v5-handoff.md` 的状态栏写着：旧的 pico、pico4 原型已删，pico3 还在，**No Pico5 implementation exists**。24 个实现包里，代码只覆盖第 1 包：
+
+| 文件 | 内容 |
+|---|---|
+| `src/types.ts` | `ConversationRecord`、`EntryRecord`（`model` / `data` / `head` / `edits`）、`Input` 四态、`TaskRecord` / `TaskState` / `TaskOutcome`、`DocumentRecord`、`Storage` |
+| `src/memory-storage.ts` | `MemoryStorage`：原子提交、只读副本、分叉历史扫描、任务整行替换 |
+| `test/memory-storage.test.ts` | 12 个存储行为测试 |
+| `docs/pico-v5.md` | 规范。Session、文档、任务、收件箱、存储后端都在这里，没有对应实现 |
+
+同仓里真正跑起来的同类代码在别的包，不在 `durable`：
+
+- `packages/agent/src/harness/pico3/`：实验内核，约 8000 行，导出路径是 `@earendil-works/pi-agent-core/experimental/pico3`。交接文档要求只把它当参考，不要搬它的外观接口。
+- `packages/agent/src/harness/session/types.ts`：工具调用状态含 `effect_pending`，并带 `replay: "never" | "safe"`。这是 Pico5「先记意图再执行」在现行 harness 里的落地，比规范更值得对照。
+- `packages/coding-agent` 的会话仍是 JSONL 树，**不依赖** `@earendil-works/pi-durable`。
+- 依赖的 `@earendil-works/chord` 0.86.1 也是 MIT，但 `packages/chord/PLANNING.md` 写明 **not a stable public API contract yet**。
+
+因此评级是 **Reject：不引入 `@earendil-works/pi-durable`，也不引入 Chord。** 语言栈是 TypeScript，我们的执行与存储在 Go；包本身没有 Session、调度器或 SQLite 后端可以链接。
+
+## 2. 规范里值得单独拿走的规则
+
+Pico5 的核心句（`docs/pico-v5.md` 开头）：一次 Session 提交原子地写下不可变条目、完整任务记录和文档；只有提交成功的状态可被观察到。下面每条都标了我们这边的落点。
+
+### 2.1 采纳，本任务在 Backend 实施
+
+这四条不改变骨架设计 §4.2「不做透明恢复」。它们补的是那条决策已经承诺、但硬杀路径没有做到的事。
+
+| 规则 | Pico5 出处 | 我们的缺口（修复前） | 落点 |
+|---|---|---|---|
+| 重开时把活着的任务收成终态 | 规范 §5.1：打开时把残留的 `running` 改回可调度；未知任务种类收成 `orphaned` | `InterruptRunning` 只在收到 SIGINT/SIGTERM 时遍历**内存里**的 run（`app.Run` 停机路径）。进程被硬杀后，库里的 `pending` / `running` / `waiting_hitl` 没有启动扫描。前端 `activeRun` 把一切非终态都当成进行中，outbox 因此不再发送 | 启动对账。SQLite 扫描全部；PostgreSQL 只扫描本实例（外加升级前 `instance_id` 为空的行）。收成 `interrupted`，未决 HITL 以 `cancelled` 关闭，发出已有的 `run.failed`（码 `run.interrupted`）。不新增 Core 状态 |
+| 输入先准入，再落库；用请求键去重 | 规范 §6：`requestId` 在写入前按会话去重；忙时 `reject` 则什么都不写 | `postMessage` 先 `AppendMessage` 再 `StartConversationRun`。槽位被占时返回 409，用户消息已经在库里。前端把同一条放回 outbox 队首，回合结束后再发一次，于是出现两条用户消息，第一条没有 run | 回合和工作流先抢槽位，忙则 409 且不写。`messages.request_id` 部分唯一索引。重复请求返回已有消息和 run。命令路由仍不占槽位 |
+| 终态一次提交 | 规范 §1 不变量 1、§5.3：终态任务、结果条目、输入结算在同一次提交 | `finishRun` 先 `UpdateRun`，再 `AppendMessage`；消息失败被跳过。可能留下 `completed` 且没有助手消息 | `SettleRun` 在一个事务里更新 run 并追加助手消息。失败则把 run 收成 `failed`（码 `run.settle_failed`）并发 `run.failed`，不再静默 |
+| 只发布已提交的状态；慢消费者靠持久游标收敛 | 规范 §1 不变量 2–3；§9.2 积压过多时用一份完整快照替换未送达的增量 | 事件是先落盘再 `Publish`，这一侧已经符合。缺口在总线：订阅缓冲满时直接丢掉，连接不断。浏览器不会带 `Last-Event-ID` 重连，注释里的「重放补齐」不会发生。另外 `EventsAfter` 只取一页 1000 条，更早的积压被跳过 | 缓冲满则关闭该订阅。SSE 看到通道关闭就结束响应，由 EventSource 重连。重放按页读到不足一页为止 |
+
+多实例约束来自 [双档存储提案](../proposals/2026-09-30-dual-tier-storage-and-multitenancy.md) 的 D24：run 在所属实例的内存里执行，跨实例不迁移。所以 PostgreSQL 上的对账不能扫描别的实例正在跑的 run。实例标识来自启动配置 `instance`（环境变量 `AGENT_SYSTEM_INSTANCE`），缺省是「主机名:监听地址」。
+
+### 2.2 试点，写给库层，本任务不改代码
+
+这些规则对得上 agent-stack 提案的 N3（可恢复 RunState）、Q1（图执行检查点）和审计 Q4（恢复会重跑 `running` 步骤）。提案合入后再开任务，在提案 §2.1 / §2.2 加链接。不要把 Pico5 的状态词原样加进我们的结果枚举：提案写了跨库结果状态对齐 A2A，不自造第四套词。下面的 `faulted` 用原因码表达。
+
+| 规则 | Pico5 出处 | 对应我们的缺口 | 试点时怎么用 |
+|---|---|---|---|
+| 重放取交集：存储时的策略和当前声明都是 safe 才重跑；否则写一条 interrupted 结果。当前的 safe 不能把当初的 unsafe 升级成可重跑 | 规范 §7.2；现行代码在 `harness/session/types.ts` 的 `effect_pending` | 审计 Q4：`Resume` 会把 `running` 步骤再执行一次。`contract` 有 `SideEffects`，但没有工具级的 replay 位，而且 contract 还没接到 runtime | Native 的工具声明加 replay 位，缺省 unsafe。Squad 的 attempt id 恢复时读这个位：unsafe 写中断结果，不调用执行器 |
+| 意图和结果分两次提交。一轮没有持久进展就失败 | 规范 §5.1 第 6 步、§5.2 effect sandwich | 审计 N1：预算用尽时 assistant 已经落盘，工具结果没有。重试会再打出副作用 | 工具调用先落「即将执行」再执行，执行后落结果。恢复时按上一行的交集决定重跑还是写中断结果。无进展用现有失败状态加原因码，不新增 `faulted` 枚举 |
+| 先写者胜出的 memo，和检查点分开，终态时丢掉 | 规范 §5.2 | 审计 Q1/Q2：批准和预算不是原子落盘，恢复后丢失或再次挂起 | 放在步骤记录上，候选插入和读出赢家同一次写入。批准、修复预算用它，不要再靠散落字段 |
+| 内存实现是语义参照，SQLite / JSONL 跑同一套一致性测试 | 规范 §10 末、§11.1；`MemoryStorage` 的测试就是这套测试的雏形 | Squad 的文件 run 和 platform SQLite 各记一份步骤状态（提案 Q1 验收已经要求合成一份） | 先有内存参照和共用测试，再写文件与 SQLite 后端。不要每个后端自己发明恢复语义 |
+| 多文件写入用「先写侧车、再写主标记、标记成功才对外可见」 | 规范 §11.3 | 审计 Q3：`writeJSON` 直接 `os.WriteFile`，崩溃留下半截 JSON | 文件档的检查点用这个协议。没有 fsync 时只承诺扛住进程崩溃，不承诺扛住断电；这一点写进文档，不要暗示成完整耐久 |
+| 压缩不改历史：追加一条带 `head` 的摘要，旧条目还在 | 规范 §2.1、§8 | 骨架设计：窗口外原文不删，滚动摘要是远期。Native 的 compaction 会按条数裁尾，审计 N7 指出可能切断工具配对 | 压缩产物是新条目加下界指针，回放从指针开始。不要重写 transcript 文件 |
+
+### 2.3 暂缓，以及什么情况下再看
+
+| 规则 | 为什么现在不拿 | 重新评估的条件 |
+|---|---|---|
+| 透明续跑（从检查点接着做，而不是标记中断后让用户重发） | 骨架 §4.2 明确不做，避免分布式续跑。N3 还没落地 | N3 的 RunState 可恢复已经合入，并且有「杀进程后工具配对仍成立」的测试 |
+| 服务端 steer / follow-up 队列 | 直连路径是 409 + 浏览器 outbox。`agent-native` 的 `AgentSession` 已有队列，但没有接到 HTTP | harness 提案 P1：直连和小队共用同一个回合循环 |
+| 崩溃后把未写完的助手输出收成一条 interrupted 消息 | 增量在 150ms 缓冲里，终态消息只在 run 结束时写。恢复它要定义「事件残片算不算消息」 | 终态原子提交稳定之后，如果用户确实需要看到半截回复 |
+| 把系统提示增量写进对话记录（`SystemMessage.sections` / `toolsAdded`） | 我们的系统段由 ctxasm 每次组装，不进消息表。pi-ai 已有这个类型，但是另一套回放 | 只有当我们要把「当时实际给模型的系统和工具」做成可回放事实时 |
+| 带作用域、历史和分叉策略的类型化文档，以及 Chord 增量订阅 | 我们已有持久 seq + Query 快照 + SSE 重放，订阅模型够用。Chord API 不稳定 | 出现真正的多文档、可分叉、要按历史时点读取的产品需求 |
+| 会话分叉（fork）和所有权树（owner 管中止，parent 管历史） | 领域模型没有会话分叉。子 run 用 `parent_run_id`，取消靠 context 级联 | 产品要做「从某一条消息开分支」或跨进程的子树取消 |
+
+## 3. 本任务实施了什么
+
+对应 §2.1，不改 Core 契约：
+
+- Backend 迁移 v14：`runs.instance_id`，`messages.request_id` 及 `(conversation_id, request_id)` 部分唯一索引。
+- 启动对账 `ReconcileInterrupted`，与停机时的 `InterruptRunning` 共用收尾。
+- 发消息先查 requestId、回合与工作流先抢槽位再落库。
+- `SettleRun` 单事务写 run 终态和助手消息。
+- 事件总线在订阅缓冲满时关闭连接；SSE 按页重放直到不足一页。
+- Frontend 数据层在发送和 outbox 重发时携带同一个 requestId。界面不变。
+
+不在本任务：透明续跑、服务端 steer、把半截输出收成消息、修改 Documents PR #34。

docs/records/2026-10-03-pi-zcode-second-pass.md

@@ -0,0 +1,79 @@
+# 调研：pi v1.0.1 与 ZCode v3.14.3 二次对照
+
+- 状态：记录（2026-10-03）；owner：weichen；任务：Dev 仓 `feature/pi-zcode-second-pass`
+- 对象：
+  - [earendil-works/pi](https://github.com/earendil-works/pi) `4c6fb7cfe8c538a668726f6f8b3554098c39faee`（2026-10-03，v1.0.1）。相对本机参考克隆 `c7cdb460`（2026-09-21）前进 239 个提交。MIT，仓库根 LICENSE 版权 2025 Mario Zechner。
+  - [zai-org/ZCode](https://github.com/zai-org/ZCode) `29628c9acdb81b703bbd4080c207a0e7ce5e276e`（2026-09-24，v3.14.3）。本机对照树 `/tmp/ZCode-study`。Apache-2.0，根目录 LICENSE、NOTICE.md、THIRD-PARTY-NOTICES.md。
+- 本仓事实以 Dev `7139e58df0` 为准。前序：[2026-10-01-agent-harness.md](../proposals/2026-10-01-agent-harness.md) 的 P0–P4、[2026-10-02-agent-stack-completion.md](../proposals/2026-10-02-agent-stack-completion.md)、[2026-10-02-agent-stack-audit.md](2026-10-02-agent-stack-audit.md)、[2026-10-03-pi-durable-review.md](2026-10-03-pi-durable-review.md)。
+- 提示词不逐字照搬。移植设计时在 NOTICE 里注明来源与修改；不把上游包、插件市场或技能正文整仓拷入。
+
+结论先说：P0–P4 已经借走回放、结束门禁、续写、验证器、子代理和工作流骨架。这一轮要补的是模型层健壮性、上下文工程、权限与钩子、文件回滚、代码编排端口。不引入 `@earendil-works/pi-durable`、Chord，也不移植 ZCode 的 TypeScript 动态工作流。
+
+---
+
+## 1. 来源现在是什么
+
+pi 仍是最小可扩展的 agent harness：交互、print、JSON、RPC 和 TypeScript SDK。v1.0.1 的实质增量是 codemode、MCP 产品化、虚拟模型、分类器基础设施，以及整棵 Pico5 运行时。`packages/durable` 仍标 Experimental；`packages/agent` 在 v1.0.0 删掉了实验内核 pico3。coding-agent 的实验 TUI 已迁到 durable。
+
+ZCode 是桌面、Web 和 CLI 共用的编程工作台。本记录只看 `apps/zcode-cli/packages/core` 与 `contracts` 里的 harness，以及产品壳里和运行态有关的协议。P0–P4 已经对齐的部分（原生工具回放、Stop 上限 3、输出续写 3 次、同名同参提醒、证据清单验证、子代理深度 1、声明式工作流）不再重复评级。
+
+## 2. 评级
+
+每条都标了本仓落点。阶段名沿用 agent-stack 提案的 N1、N2、N3；「批次」指本任务之后的实现批次。
+
+| 主题 | 上游 | 本仓 | 评级 | 批次 |
+|---|---|---|---|---|
+| 上下文溢出识别 | pi `packages/ai`：按供应商文案识别，含 Z.AI 中文站 | `deps/agent-native/runtime/llm/providers.go` 的 `ContextOverflow` 要求错误信息同时含 “context” 与 overflow/too long/length | adopt | 2，N3 |
+| Retry-After 与容量重试 | pi：解析失败则指数退避；“Selected model is at capacity” 可重试 | `runtime/llm/client.go` 对 429/5xx 标可重试，不读 Retry-After | adopt | 2，N3 |
+| 未完成的工具调用 | pi `1b2aa0ca0`：Responses 未完成的 tool call 拒绝执行 | `runtime/llm/sse.go` 的 `mapFinish`：finish 为 `length` 或空、且已有工具增量时返回 `StopToolCalls` | adopt | 2 |
+| 流式重试不吞增量 | pi 的重试发生在收到正文之前 | `WithRetry` 先缓冲整次尝试再转发。默认打开会让流式失效 | adopt | 2，N10 |
+| 用量拆分 | pi 会话成本区分请求与累计 | 循环把每轮 prompt token 累加（审计 N20） | adopt | 2，N20 |
+| 运行内清理旧工具结果 | ZCode compact：保留最近若干条，更早的 Read/Bash/Grep 结果可替换 | 产品回放保留全文；内核 `session/compact.go` 按条数裁尾，可切断工具配对（审计 N7） | adopt | 4，N2 |
+| 压缩与追加的竞态 | pi durable：压缩是新条目加 head，不改历史 | `compact.go` 读完解锁再摘要（审计 N8） | adopt | 4，N2 |
+| 先读后改、文件过期 | ZCode `tool/read-file-state.ts`、edit handler：未读或 mtime 变化则拒绝 | 内置 write/edit 与后端 `write_file` 无此检查 | adopt | 4，N2 |
+| 提醒不占 user 角色 | ZCode `system-reminder/source.ts`：按来源节流，不破坏工具配对 | `runtime/loop.go` 的 `withEphemeral` 追加 user 消息（审计 N22） | adopt | 4，N1/N2 |
+| 子代理结果上限 | ZCode agent handler 约 120KB | `modules/backend/internal/runtime/sub_loop.go` 把结果原文交回 | adopt | 4，N2 |
+| 默认工具 `+name/-name` | pi settings，`30a1d1849` | `runtime/tools/registry.go` 只有精确名和通配 | adopt | 4，N2 |
+| RPC 回执 | pi `e473b5cd8`：`started` / `queued` / `handled` | `rpc/server.go` 只返回 OK 与正文 | adopt | 4 |
+| 按字符截断 | ZCode 与审计 N16 | `runmgr.go` 的 `ExecuteTool` 用字节切片截断工具结果 | adopt | 4 |
+| 权限三档 | ZCode：plan / build / edit；另有未实现的 auto 与旁路 yolo | 画像策略 deny / confirm / allow；无计划档 | adopt 三档；reject 旁路档 | 6，N1 |
+| 钩子总线 | ZCode `contracts/hooks`：SessionStart、UserPromptSubmit、PreToolUse、PermissionRequest、PostToolUse、PostToolUseFailure、Stop、SubagentStart/Stop；决策 allow/deny/ask/modify/block；超时 60s | 内核只有 BeforeTool、AfterTool、Stop 回调；无配置 schema。`adapters/native/backend.go` 不透传（审计 N31） | adopt 进程内总线；hold 进程级钩子 | 6，N1 |
+| 向用户提问 | ZCode AskUserQuestion | HITL 有 choice/input/confirm/form，没有一等工具 | adopt | 6，N1 |
+| 计划模式工具闸 | ZCode EnterPlanMode / ExitPlanMode | `update_plan` 只写计划，不限制写工具 | adopt | 6，N1 |
+| 确认卡参数 | 本仓缺口，不是上游新能力 | `ExecuteTool` 算出 `argsPreview` 后丢弃 | adopt | 6 |
+| 意图与结果分两次提交 | pi durable Tools：`replay` 取存储时与当前声明的交集 | 工具结果在执行后一次写入；崩溃留下无结果的调用（审计 N1 的同类） | adopt | 7，N3 |
+| 只回滚写文件 | ZCode `contracts/rewind`；pi 文件检查点只追踪写 | 无文件回滚 | adopt | 7，N3 |
+| 请求只读已落盘投影 | pi `466db0fec`：prepareRequest 以持久投影为权威 | AgentSession 的队列在内存里进入下一次请求 | adopt | 7，N2 |
+| 模型回退链 | pi 虚拟模型是每请求路由器，不是静态链 | 无回退；溢出不重试 | adopt 静态链，默认空；hold 虚拟模型路由 | 7，N3 |
+| GenAI span | 提案 §2.1 已列名字；ZCode telemetry 默认少采正文 | 有 logging-system 的 trace_id，无这组 span | adopt | 7，N3 |
+| 代码编排工具 | pi `packages/codemode`：模型写 JS，跑在 QuickJS，中间结果不进上下文；bash 对脚本最多 1MiB | 后端 `workflow_script.go` 是工作流步骤，不是模型侧工具 | adopt 端口语义，不搬 QuickJS | 8，N2 |
+| MCP 延迟暴露 | pi `docs/mcp.md`：exposure、tool_search、首条提示不等服务器 | `runtime/mcp/manager.go` 启动即连接；stdio 取消后读协程不退出（审计 N3）；失败重连只有注释（N18）；HTTP Close 为空（N19） | adopt | 8，N2 |
+| 运行态单一所有者 | ZCode 协议把 in-flight 与 settled 分开；发送即 ack | 前端 `store.ts` 的 live 与 runs 分别更新。Dev #161 已修可见性回归 | adopt 剩余的单一状态源与事件穷举 | 5 |
+| 架构基线棘轮 | ZCode `architecture-policy.yaml` 与 knip | Dev 已有库间导入棘轮，不管 backend internal 分层，也不查死导出 | adopt | 3 |
+
+## 3. 拒绝，以及为什么
+
+| 项 | 理由 |
+|---|---|
+| 依赖 pi-durable 或 Chord | TypeScript、Experimental、Chord 不是稳定契约。只借鉴规则和测试意图 |
+| 透明续跑 | 骨架设计 §4.2 明确不做 |
+| 回滚对话历史 | 文件可以回到某条用户消息之前；消息树保持追加 |
+| 绕过确认的权限档 | ZCode 的 yolo 与本仓「deny 不能被 allow 跳过」冲突 |
+| 进程级钩子、MCP OAuth | 宿主是多租户后端，不是单用户 CLI。钩子先做进程内回调 |
+| ZCode 动态工作流 DSL | 编排已裁定归 Agent-Squad。不移植 TypeScript 沙箱脚本图 |
+| ZCode TUI、桌面、远程 SSH、CUA、cron、插件市场 | 产品形态是单二进制加 Web。CUA 在上游也是占位 |
+| pi 虚拟模型与分类器路由 | 当前没有「每个请求选模型」的产品需求。回退链用静态列表 |
+| Anthropic 原生协议与 thinking 签名回放 | 仍按提案 N2 单独做。本轮只堵住会执行未完成工具调用的解析 |
+
+## 4. 不回退的既有决定
+
+- 交付守卫失败即不通过。ZCode 在验证器自身出错时放行。见 harness 提案 §2。
+- 正文里的伪造工具调用要拦截。见 harness 提案 P0。
+- 动态工作流步数、脚本确认和回调白名单保持 P4 的数字。代码编排端口默认关闭。
+- 回合默认仍有轮次和预算上限。ZCode 的长任务哲学是不按工具次数硬停；本仓保留上限作安全阀。
+- 库声明自己不是操作系统沙箱。
+
+## 5. 本记录的验收
+
+- 本文件、pi-durable 记录文首更正、提案 §2.4 互相链接。
+- 不改 Go 或 TypeScript 代码，不改三个库的指针。

docs/records/2026-10-04-sillytavern-review.md

@@ -0,0 +1,71 @@
+# 调研：SillyTavern 1.19.0
+
+- 状态：记录（2026-10-04）；owner：weichen；任务：Dev 仓 `feature/sillytavern-review`
+- 对象：[SillyTavern/SillyTavern](https://github.com/SillyTavern/SillyTavern) `06bde939`（release 1.19.0，2026-09-14）。AGPL-3.0，另有标注 GPLv3 的 RisuAI 片段。按固定提交只读对照，不建长期克隆，不拷源码。
+- 本仓事实以任务起点 Dev `4fd03eee` 为准。前序：[2026-10-03-pi-zcode-second-pass.md](2026-10-03-pi-zcode-second-pass.md)、[2026-10-02-agent-stack-completion.md](../proposals/2026-10-02-agent-stack-completion.md)。
+- 规则与 pi / ZCode 两份记录相同：只借设计。不拷代码、提示词或界面文案。本仓各子仓没有 LICENSE、以单二进制分发，拷入 AGPL 代码会让整个产品落入 AGPL，网络使用条款同样生效。
+
+结论先说：上下文工程值得借的是「统一注入登记 + 按预算组装」，平台侧值得借的是带标签的密钥、设置快照、以及听口令时拒绝无认证的对外监听。本仓的 SSRF 与账户已经更严，不借。安全缺口（输出未清洗、缺响应头、不校验来源、对外监听无认证）和下面的采纳项在同一任务里落地。扩展系统、脚本宏、群聊、角色卡、自定义 CSS、JSONL 存储、删除消息和自动触发的快捷回复不借。
+
+---
+
+## 1. 来源现在是什么
+
+SillyTavern 把要注入模型的文本放进统一登记表：每条有位置、深度、角色、顺序和扫描范围，再由一次按 token 预算的组装把它们收成请求。预算不够时只裁最老的历史。世界书、作者注、记忆和向量库都走这条登记，而不是各写一条拼接。
+
+平台侧用带标签的多密钥（同一服务一把生效）、设置快照、以及「监听且未开认证就拒绝启动」。请求侧还有 Host / Origin 检查。聊天用 JSONL，带滑动候选和父指针检查点。扩展是未沙箱的同源脚本。
+
+本仓已经有更严的 SSRF（`fetch_url` 和链接预览在拨号时校验解析出的 IP，黑名单含 `0.0.0.0/8` 和 `100.64.0.0/10`）和账户（argon2id、重置密码即吊销服务端会话、登录限流）。这些不改。
+
+## 2. 对照时核实的安全缺口
+
+行号是任务起点那一版本仓源码，实施后位置会移动。
+
+| 缺口 | 起点位置 | 处置 |
+|---|---|---|
+| 模型输出、卡片和文档预览把 HTML 直接写入页面。`marked` 15.0.12 不清洗 | Frontend `Conversation.tsx`、`previewsetup.ts`；UI `UIRenderer.tsx`、`FilePreview.tsx` | `@ui` 的 `safeHtml` 成为唯一写入点。外部图片改成「外部图片 · 域名」链接。同源地址不再用 `allow-same-origin` 内嵌 |
+| 没有 CSP / nosniff。HTML 工件按页面直出 | Backend `server.go` 的静态页与 `artifactContent` | 页面 CSP、nosniff、`Referrer-Policy`。html/svg/xml 工件加 `sandbox` |
+| 不校验 Origin / Host。SQLite 档默认不开认证 | `app.go` 的认证开关 | `RequestGuard` 包在组合根。写请求核对 Origin 或 `Sec-Fetch-Site`。未开认证时 Host 只允许 IP、`localhost` 和 `allowedHosts` |
+| 对外监听且未开认证时照常启动 | `.env.dev` 曾把 dev 听在 `0.0.0.0:8788` | 非回环、未开认证、又没有 `--insecure-listen` 时，打开数据库之前拒绝启动 |
+
+## 3. 采纳并已在本任务实施
+
+原先记为后续批次。任务范围改为同一任务做完，落点如下。
+
+| 主题 | 上游设计 | 本仓落点 |
+|---|---|---|
+| 密钥独立存储 | `src/endpoints/secrets.js`：多把带标签的 key，一把生效，读出只给掩码，迁移前备份 | `secret_keys`。GET 只返回掩码。启动时先写设置快照，再把 `models.*.apiKey` 和 `tools.tavily.apiKeys` 迁入并从表单设置清掉。运行时优先用生效密钥 |
+| 设置快照 | 启动和保存后留档。上游恢复前不留档，这一点不照搬 | `settings_snapshots`。正文与上一份相同则跳过。保存间隔短于 10 分钟则跳过 |
+| 个人指令与会话要求 | persona 与 Author's Note | `context.userInstructions` 与会话 `sessionNote`。经 agent-native `reminders.Attach` 附在最后一条用户或工具消息上，系统前缀不动 |
+| 条件注入 | 世界书的关键词、次关键词逻辑、扫描深度、常驻、顺序、预算 | `context_entries`。`matchModule` 仍只看本轮子串；条目在组装末尾另判 |
+| 上下文快照 | 提示词分段视图 | `ContextObservation` 增加 `sections` 与 `prefixHash`。界面折叠条显示估算 token 和前缀哈希 |
+| 估算口径 | 上游按 token 预算裁历史 | 统一为 UTF-8 字节 / 3.35，再用上一请求的 prompt token 校准。`context.contextWindow` 进入 schema，默认 32000，只丢掉最早的历史 |
+| 消息整形 | `src/prompt-converters.js` | `PrepareMessages`。`merge` 合并相邻同角色。`strict` 再把第一条之后的 system 收成 user。工具调用和结果不合并 |
+| 复制、排除、候选回复 | 滑动候选与检查点 | 复制在界面完成。排除按消息及其同一 run 成组，记录仍在。重新生成不删旧回复，写入同一 `variantGroup`，并按用户消息做文件回滚 |
+| 用户 `/` 命令 | 快捷指令，但不做自动触发 | `user_commands`。名称符合 `user.<slug>` 时登记为 agent-command 的 `SourceUser`。发送时把模板展开成普通用户消息 |
+
+## 4. 暂缓
+
+- Claude 缓存断点：等 Anthropic 原生协议。
+- 编辑重发与会话分支：等候选回复用过再看父指针方案。
+- 窗口外同会话召回、用户级知识库：等会话经常超出窗口再看。
+- 世界书的概率、递归、包含组和定时效果。
+- 密钥静态加密。
+- i18n：真要做时不能拿原文当键。
+- 出站代理：只能用于模型端点。
+- 画像导入导出。
+
+## 5. 拒绝
+
+- 拷代码、提示词和界面文案。
+- 扩展系统（同源 JS、没有沙箱）和带完整 Node 权限的服务器插件。
+- STscript 和宏语言。
+- 群聊、角色卡、视觉小说。
+- 自定义 CSS 和平滑打字流式：与 DESIGN.md 冲突。
+- JSONL 整文件覆盖和逐行扫描搜索。
+- 删除消息。用「排除出上下文」代替。
+- 自动执行的快捷回复触发器。
+
+## 6. 不回退的既有决定
+
+认证默认仍是 `auto`：显式 `on`，或不是 `off` 且配置了 DSN，才开认证。不加 CSRF token，不加 CSP 上报端点。不改 SSRF 黑名单，不改账户哈希和会话吊销。

docs/records/2026-10-07-planning-index-source.json

@@ -0,0 +1,963 @@
+{
+  "source": "SELF",
+  "checked_at": "2026-10-07T13:27:59.195848+00:00",
+  "dev_base": "eb0d4b5a499322a23155c8d89a024247f6e7830d",
+  "docs_pin": "b8eaa1676f168ad64c437857e2607e2e213f6672",
+  "docs_main": "5542319a0474fd4e866b6daacb937b587c833ede",
+  "limits": "API/Git state only; no runtime testing or assertion of human implementation approval",
+  "proposals": [
+    {
+      "path": "docs/proposals/2026-09-29-system-skeleton-design-and-plan.md",
+      "source_blob": "2ba08d7017e7f45c6bc1493a46c050765613f7ac",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-09-30-card-stream-artifact-unify-project-inbox.md",
+      "source_blob": "0066c25a1f737fc6fe213cec677803d4d1163cbf",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-09-30-cardflow-and-process-split.md",
+      "source_blob": "fb737b396ec35d7d848b71f8c30c39779b64366b",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-09-30-configuration-surface.md",
+      "source_blob": "abd37122514d0aeded245a23167b78e12c7b0833",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-09-30-cross-session-reading.md",
+      "source_blob": "b96c0dae76b347841f46380d06d53806869e338a",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-09-30-dual-tier-storage-and-multitenancy.md",
+      "source_blob": "1880c2ac14e91f6db24d9b104f1f7bb2547fe166",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-09-30-file-preview-and-reserved-capabilities.md",
+      "source_blob": "f48af6d25937d2e5aacc946d0023a53e3c09bde4",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-09-30-ui-inbox-command-workspace.md",
+      "source_blob": "e78e19732856cbfc9d0105302aae2ff2c453c2d4",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-09-30-ui-redesign-and-auth.md",
+      "source_blob": "155cbf0993b40f4ea616aef95aaee7ff71d7db6b",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-01-agent-harness.md",
+      "source_blob": "b3b304c9f31fca632ffa47326c48556ee0ee7cca",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-01-base-extension-roadmap.md",
+      "source_blob": "b2b99878dd1fc95f86f28f0b007d012c5171d597",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-01-extension-compat-policy.md",
+      "source_blob": "1daba9f4f7441bdde8d648cd08f663ffa36cc7e9",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-01-plugin-contract-v2.md",
+      "source_blob": "08395fbf53a306b76d692e1ded8ee0d1f41716af",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-02-agent-stack-completion.md",
+      "source_blob": "a6e7cb732ae4c7b403b81e5597620b58644438fc",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-05-ext-1-inproc-command-handler.md",
+      "source_blob": "988e5516b4b3f7919071f667d543b55dcbdb08fe",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-06-ext-5-host-parse-document.md",
+      "source_blob": "2a54cfd98874e4f94d2b74967e0541fa27f4601d",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-07-agent-stack-n1q1i1-plans.md",
+      "source_blob": "ee44529a8c283693875f4bb1c11dde7b9939e60c",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    },
+    {
+      "path": "docs/proposals/2026-10-07-agent-stack-n2-plan.md",
+      "source_blob": "647b04848a6a77a68b1754f200ae61804d1a0740",
+      "present_in_dev_pin": false,
+      "same_blob_as_dev_pin": false
+    },
+    {
+      "path": "docs/proposals/2026-10-07-rdm-phase-plan.md",
+      "source_blob": "d2a491849ef8d04ea04bfeb885ba6a15a3bdc1f5",
+      "present_in_dev_pin": true,
+      "same_blob_as_dev_pin": true
+    }
+  ],
+  "pull_requests": [
+    {
+      "repo": "Agent-System-Dev",
+      "number": 12,
+      "title": "Pin backend with the configuration pipe and documents with its design",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/12",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T04:27:51Z",
+      "head_ref": "refs/pull/12/head",
+      "head_sha": "6f72c0d4dd99e5162339b57489446ef9b0b0534f",
+      "base_ref": "main",
+      "merge_sha": "a58f85e0d0ade6e8b4da3afe9985985a38bae47a",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 14,
+      "title": "Wire Agent-System-UI and Agent-Command into the Dev combo (T0)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/14",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T06:11:54Z",
+      "head_ref": "refs/pull/14/head",
+      "head_sha": "cc9d8ec66d2597f47b6c7bafc7a607957c2de188",
+      "base_ref": "main",
+      "merge_sha": "69e9471dafd275f98928ff005732b94c4b18b638",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 15,
+      "title": "T1: pin contracts combo (core cards/commands, agent-command v0) and guard task-finish",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/15",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T06:34:06Z",
+      "head_ref": "refs/pull/15/head",
+      "head_sha": "3ca7f374e63748e41476fbf0244b06ef0711d6dc",
+      "base_ref": "main",
+      "merge_sha": "69fd335deac237f5291298cb06a50bf03d11add7",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 19,
+      "title": "T2: pin the inbox combo (cardsvc backend, ui components, frontend wiring)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/19",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T07:36:09Z",
+      "head_ref": "refs/pull/19/head",
+      "head_sha": "d8dd604b8ab823f742c6e7b0f4ae43e23e4fda12",
+      "base_ref": "main",
+      "merge_sha": "10405f9479c83a7eccb9ab6133229d37013a9da5",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 21,
+      "title": "T3: pin the command-bus combo (cmdbus, InlineConfirmCard, symmetric entries)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/21",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T07:56:27Z",
+      "head_ref": "refs/pull/21/head",
+      "head_sha": "b9d4df056116128e450f163cb3de568c032f8d91",
+      "base_ref": "main",
+      "merge_sha": "7393d6b95850982043b5d31aa2db6953a5bcd031",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 23,
+      "title": "T4: pin the workspaces combo (OverlayHost, pure-inbox rail, Cmd shortcuts)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/23",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T08:09:48Z",
+      "head_ref": "refs/pull/23/head",
+      "head_sha": "4318a0bad8cb1025a3323d2942486812f7aeff5a",
+      "base_ref": "main",
+      "merge_sha": "b6822096834853942439a4069a78b519b354731c",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 25,
+      "title": "T5: pin the polish combo (zero-page walkthrough, tidy, guide) - proposal complete",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/25",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T08:18:34Z",
+      "head_ref": "refs/pull/25/head",
+      "head_sha": "61dc542e56fa64f78c5da3cdc69da2890db122f3",
+      "base_ref": "main",
+      "merge_sha": "3be968af731eecc7b9cd4699c54671b7a9c9cbd9",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 30,
+      "title": "界面重构与多用户认证设计提案（documents gitlink + 任务卡）",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/30",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T10:02:29Z",
+      "head_ref": "refs/pull/30/head",
+      "head_sha": "f9d2aaa2739f9678ee4df7040c7ca80afcfca180",
+      "base_ref": "main",
+      "merge_sha": "32bb3457d174e6c837ef9b411138d2b57f5839f6",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 37,
+      "title": "Task-centric sidebar R1 (option A): gitlinks + task card",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/37",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T10:46:46Z",
+      "head_ref": "refs/pull/37/head",
+      "head_sha": "6cfdb89f21945a0c9f5dae9451bde5c9f099d05b",
+      "base_ref": "main",
+      "merge_sha": "075c187be28c15b3b66c14adf3edcbeeafb5c05f",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 43,
+      "title": "Admin-issued accounts R2: gitlinks + task card",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/43",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T11:17:31Z",
+      "head_ref": "refs/pull/43/head",
+      "head_sha": "66eae890170c2373681384ddb1b8ae84454a4e87",
+      "base_ref": "main",
+      "merge_sha": "2f319ca0f5b86e12796042e72f65d3d939b97182",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 53,
+      "title": "R4 visual refresh: gitlinks + task card",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/53",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T12:44:52Z",
+      "head_ref": "refs/pull/53/head",
+      "head_sha": "73b2802b69eb23be4dd16db41f316f0ab8ac99ca",
+      "base_ref": "main",
+      "merge_sha": "b0699598191a51b912aae4e69e39d7d48a38188e",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 61,
+      "title": "UI capability platform: gitlinks + .gitignore + task card",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/61",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T14:23:41Z",
+      "head_ref": "refs/pull/61/head",
+      "head_sha": "0bf2f9beccb806f7201a5b069aebd259fab49320",
+      "base_ref": "main",
+      "merge_sha": "58f191189bf807c86bad3399fa295088ce26a5fa",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 67,
+      "title": "Deliver layered cross-session reading and pin the five module PRs",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/67",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T15:27:41Z",
+      "head_ref": "refs/pull/67/head",
+      "head_sha": "835e3ce187412298060a9fd0e7f60f158ed05796",
+      "base_ref": "main",
+      "merge_sha": "816b40e8f74d27218c2ed321dc88007fd298bed3",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 71,
+      "title": "Deliver part-order fidelity, artifact downloads, file management, and the settings shell fix",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/71",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T15:44:05Z",
+      "head_ref": "refs/pull/71/head",
+      "head_sha": "7e9cac8a40a479d1f4a4790db38fef370aa28724",
+      "base_ref": "main",
+      "merge_sha": "bb1bf06aec6d3f848ce6a1ca291c6ef6dc4da4ab",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 77,
+      "title": "Pin the file-preview proposal and restore the regressed module gitlinks",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/77",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T16:06:43Z",
+      "head_ref": "refs/pull/77/head",
+      "head_sha": "937c4ed9011dbc86dac85eaaa691335b9a2393e3",
+      "base_ref": "main",
+      "merge_sha": "a3f3cb0a841c7d918982b24590bb58bcf804a2ad",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 79,
+      "title": "Agent-System-Dev: review fixes for chat-process-split-r1 (symlink, live interleaving, artifact process)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/79",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T16:17:03Z",
+      "head_ref": "refs/pull/79/head",
+      "head_sha": "f3056cb9d6bdbb0061848661afb8b61a7d8dc06f",
+      "base_ref": "main",
+      "merge_sha": "eb1877b3f707fc5bc6e59cd531e6d9d69424129b",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 90,
+      "title": "Pin cardflow-r1 module combination (CF1: submit_card, card anchor, process split)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/90",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T17:14:50Z",
+      "head_ref": "feature/cardflow-r1",
+      "head_sha": "9451887c059fac7fe987544ac455b51f39911201",
+      "base_ref": "main",
+      "merge_sha": "75d5a1721e928eb832f54b5d4aaf1def304021e6",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 94,
+      "title": "Deliver file previews, dual-dock placement, and reserved delete/fs capabilities",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/94",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T17:21:30Z",
+      "head_ref": "feature/file-preview-caps",
+      "head_sha": "f958bfb326c7dae646fb1dd6dabc5faf2d63221d",
+      "base_ref": "main",
+      "merge_sha": "2c8e1b8d5762685256e2e9bb27eb29b4008d738e",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 100,
+      "title": "Land card streaming (CF-S: card_begin/card_append/card_commit)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/100",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T18:23:29Z",
+      "head_ref": "feature/card-stream-r1",
+      "head_sha": "e240f909113ccf96fd2241da6aeb3804fa6cb414",
+      "base_ref": "main",
+      "merge_sha": "a8faa967cdc0fe0d20a3cb20ed17f74518b6cff7",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 103,
+      "title": "Land artifact unification (CF-A: backfill symmetry + facade cards)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/103",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T18:44:17Z",
+      "head_ref": "feature/artifact-unify-r1",
+      "head_sha": "a4c0d1ad1b53f4c8831bcd8abfb824c112947802",
+      "base_ref": "main",
+      "merge_sha": "675e6f8483e11d67a49f3c68b8b98a44cb42b7e1",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 105,
+      "title": "Land cross-session project inbox (CF3: D48-D51)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/105",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T19:20:29Z",
+      "head_ref": "feature/project-inbox-r1",
+      "head_sha": "25f65559ae45751fea811f06955641345d56c1d9",
+      "base_ref": "main",
+      "merge_sha": "0b82976c66aaaaf0515fd31eaee9abfa5cde193c",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 132,
+      "title": "Pin the extension roadmap and downstream spike",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/132",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-01T10:47:14Z",
+      "head_ref": "feature/base-extension-roadmap",
+      "head_sha": "94b7de3a9f0debb5a5afb8e09974cc72a8a08e54",
+      "base_ref": "main",
+      "merge_sha": "db9c4690478b4fa4973efa1111e8764c73011ebb",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 134,
+      "title": "Pin the harness proposal and native tool-call replay",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/134",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-01T12:43:41Z",
+      "head_ref": "feature/agent-harness-p0",
+      "head_sha": "5e257192018c2d536ba4f16406e8ce9750c13952",
+      "base_ref": "main",
+      "merge_sha": "46b9e53f75f5383ea1ac961b8e6fa587f88ce64a",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 136,
+      "title": "Pin the harness turn loop across the three native checkouts",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/136",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-01T13:42:01Z",
+      "head_ref": "feature/agent-harness-p1",
+      "head_sha": "c5ab4c35e56bd762f37a22649fc94a4e2480bc5b",
+      "base_ref": "main",
+      "merge_sha": "def110d784dfeb0139062cb511a0b7de6e59ae81",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 138,
+      "title": "Pin backend to the final-turn result checks",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/138",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-01T14:00:59Z",
+      "head_ref": "feature/agent-harness-p2",
+      "head_sha": "7244f8c7305f075cc96c647021797677b4b804e8",
+      "base_ref": "main",
+      "merge_sha": "1939d50a7fcb61bdb4bc98cba84173e7e5fc9a11",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 140,
+      "title": "Pin backend to the depth-one subagent loop",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/140",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-01T14:51:02Z",
+      "head_ref": "feature/agent-harness-p3",
+      "head_sha": "8c43d4b16ce0d5aa700bfebb77b8a022de532b3d",
+      "base_ref": "main",
+      "merge_sha": "5096a052dcaef7ee08a3251ec50a47bf7f066618",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 142,
+      "title": "Pin P3b background subagents, review, and profile overrides",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/142",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-01T15:51:57Z",
+      "head_ref": "feature/agent-harness-p3b",
+      "head_sha": "79a6a73052920ba3bd2b4909d8287cf7e908a2e2",
+      "base_ref": "main",
+      "merge_sha": "ec4614322eaded96ee13f576992f016b47648200",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 144,
+      "title": "Add intent-to-workflow execution",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/144",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-02T01:04:03Z",
+      "head_ref": "feature/agent-harness-p4",
+      "head_sha": "cd984219da215db5978e7916c0439df74ce7b5aa",
+      "base_ref": "main",
+      "merge_sha": "3ba104c721013f63be249e2f810376d3d8b26ee3",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 151,
+      "title": "Pin documents to the agent stack completion proposal",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/151",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-03T14:15:52Z",
+      "head_ref": "refs/pull/151/head",
+      "head_sha": "83b2b0912e6e2e891f16590ca011fa374cb79478",
+      "base_ref": "main",
+      "merge_sha": "2a24d8418a7c0da0428481fd03c315a346eb597c",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 152,
+      "title": "Check nested library pins and test the three agent libraries",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/152",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-03T12:47:36Z",
+      "head_ref": "refs/pull/152/head",
+      "head_sha": "2e43703838a8fcb84cd00d669f28038b8a8d3efd",
+      "base_ref": "main",
+      "merge_sha": "7dd107bae40a203d684b0c9a3fd81ca316fd8c90",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 154,
+      "title": "Pin the R2 library and backend heads",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/154",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-03T13:22:55Z",
+      "head_ref": "refs/pull/154/head",
+      "head_sha": "a5377ec2347e08c84d428d980c652355fa7785be",
+      "base_ref": "main",
+      "merge_sha": "0a047db5c9c852539c6a839cf85589729f246019",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 156,
+      "title": "Pin the D1 library and backend heads",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/156",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-03T14:02:34Z",
+      "head_ref": "refs/pull/156/head",
+      "head_sha": "3cd83db5ca01de2227e8ab668355a431708193f9",
+      "base_ref": "main",
+      "merge_sha": "19b93ed09c0b80de78eed45763b482616b54ed06",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 167,
+      "title": "Add an architecture edge ratchet and waiting-state tokens",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/167",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-03T16:04:36Z",
+      "head_ref": "feature/architecture-baseline",
+      "head_sha": "4afccef8bd222355657da52ea1a9e07debfc3e8f",
+      "base_ref": "main",
+      "merge_sha": "e294729a44e11b15ab7ba2c70b04eafa235d5f95",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 207,
+      "title": "Add EXT-1 inproc command handler and owner-scoped host handle (minimal set)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/207",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-05T11:48:46Z",
+      "head_ref": "feature/ext-1-inproc-handler",
+      "head_sha": "4801a90319254bd8bbef5e22abf47acb10972014",
+      "base_ref": "main",
+      "merge_sha": "63a62a79ac52cc5d0b5d798dc586195ea842bd51",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 209,
+      "title": "Restore and complete the EXT-1 task card after branch recreation (verification round)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/209",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-05T12:07:12Z",
+      "head_ref": "feature/ext-1-inproc-handler",
+      "head_sha": "4801a90319254bd8bbef5e22abf47acb10972014",
+      "base_ref": "main",
+      "merge_sha": "15ec9bfbc57bbc1f9930ac4c3ef91edc8460ea4a",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 222,
+      "title": "Expose builtin document parsing through the host handle (EXT-5)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/222",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-06T15:14:31Z",
+      "head_ref": "refs/pull/222/head",
+      "head_sha": "f5c83534fe2cc3886842e66c2648362c5fa2af7c",
+      "base_ref": "main",
+      "merge_sha": "c06da5735904e63db4cbcdb75b3b10b48aeffc32",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 224,
+      "title": "Pin the wide-columns xlsx fix",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/224",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-06T15:39:48Z",
+      "head_ref": "refs/pull/224/head",
+      "head_sha": "12cda45fe8cd910253dacd75434efcf203f2ba0f",
+      "base_ref": "main",
+      "merge_sha": "c4985e96ce1c49da88f652e9a2d8ac2bec4a8b01",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 226,
+      "title": "Propose N1/Q1/I1 implementation plans (docs only)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/226",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T02:51:40Z",
+      "head_ref": "refs/pull/226/head",
+      "head_sha": "ddfd6a2b67209a1b9b2ba7810cb10919c0bb9743",
+      "base_ref": "main",
+      "merge_sha": "2147d5cb6566c301eaea3c65448bdda873093aea",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 229,
+      "title": "Propose the RDM phase plan (docs only)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/229",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T04:34:51Z",
+      "head_ref": "refs/pull/229/head",
+      "head_sha": "0384abc9aff3b30f23a4b95c6552e60071f5436d",
+      "base_ref": "main",
+      "merge_sha": "9c9483ac54ff5355c86824ac94097e65e59dcb5d",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 232,
+      "title": "Pin the merged WP5 gate-sinking combination",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/232",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T06:50:22Z",
+      "head_ref": "refs/pull/232/head",
+      "head_sha": "1a4053810acde922b68cca802ae2c7dba4e26ad7",
+      "base_ref": "main",
+      "merge_sha": "ae40cee917ca449fa8e75e6f2a665d94a18e3567",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 234,
+      "title": "Pin the merged I1 command-model and router combination",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/234",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T08:04:20Z",
+      "head_ref": "refs/pull/234/head",
+      "head_sha": "e793587677b73f9e0a8b7b200fb89cf002b71a5a",
+      "base_ref": "main",
+      "merge_sha": "1f7217f5bb2657418845d6bec6ae28c56920ddc8",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 235,
+      "title": "Pin the merged I1 eval-v2 combination",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/235",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T08:44:41Z",
+      "head_ref": "refs/pull/235/head",
+      "head_sha": "9c1cdbb10fe6237b80f40cf5184f2e3ae3378643",
+      "base_ref": "main",
+      "merge_sha": "eafe1e1fbf6874b58f851878c815c2c24e6f8db3",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 237,
+      "title": "Pin the merged superstep engine (Q1 WP1/WP2)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/237",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T09:12:58Z",
+      "head_ref": "refs/pull/237/head",
+      "head_sha": "8a1c84193922530c1489572ef6a1e136594bb1ef",
+      "base_ref": "main",
+      "merge_sha": "3bf2441b05489dfb55b3146aa4e0c53068d34b82",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 240,
+      "title": "Pin the merged SQLite convergence (Q1 WP5)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/240",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T10:38:59Z",
+      "head_ref": "refs/pull/240/head",
+      "head_sha": "1a02139026f412c90799bb01fe023bec173a2888",
+      "base_ref": "main",
+      "merge_sha": "ba36d47c2fbfdd0ba759fe251f87c403a5f7ffc7",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 242,
+      "title": "Take the backend intent slow lane and the I2 port pins (I2 WP3)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/242",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T11:58:02Z",
+      "head_ref": "refs/pull/242/head",
+      "head_sha": "733f3c74745ae46ae71a82b092867c7e4b45adf6",
+      "base_ref": "main",
+      "merge_sha": "d308ed66196b67970de19ad657410daffcca3740",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Dev",
+      "number": 244,
+      "title": "Take the N2 implementation plan and open the N2 task",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/244",
+      "state": "open",
+      "merged": false,
+      "merged_at": null,
+      "head_ref": "feature/agent-stack-n2",
+      "head_sha": "eae6992ae81335df5eb016223e2522fab952ae7f",
+      "base_ref": "main",
+      "merge_sha": null,
+      "merge_in_fixed_main": null,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 14,
+      "title": "界面重构与多用户认证设计提案 + HTML demo（方案 A/B/C + 认证）",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/14",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T10:02:04Z",
+      "head_ref": "refs/pull/14/head",
+      "head_sha": "e601b253bc0d6a3fc762c7495d235b68f3910eb6",
+      "base_ref": "main",
+      "merge_sha": "ab14f62534fc8831db694fa580a7d163a3cc19ff",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 27,
+      "title": "Propose card stream, artifact unification, and project inbox (D44-D52)",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/27",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-09-30T17:45:16Z",
+      "head_ref": "feature/cardflow-future-plan",
+      "head_sha": "4a698869521eaa60b2fba9bdb3196226691bf987",
+      "base_ref": "main",
+      "merge_sha": "437af31118814463cc44d379f7269afd7add62b5",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 31,
+      "title": "Document the base extension roadmap and plugin contract v2",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/31",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-01T10:47:11Z",
+      "head_ref": "feature/base-extension-roadmap",
+      "head_sha": "a0da588f9035e132bcfd1dcc0ac1dacb62924776",
+      "base_ref": "main",
+      "merge_sha": "f3a3a5deb48e5b1c6ceb1b666d71ed912606c49d",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 32,
+      "title": "Propose the agent harness and link it from the roadmap",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/32",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-01T12:43:26Z",
+      "head_ref": "feature/agent-harness-p0",
+      "head_sha": "a3f0b80759fa01094cb9ee26b2a17dba831317e2",
+      "base_ref": "main",
+      "merge_sha": "357e3fdb246a8a8d562e63e01d5170673bf4dcc6",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 34,
+      "title": "Propose the agent stack audit and completion design",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/34",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-03T14:12:17Z",
+      "head_ref": "refs/pull/34/head",
+      "head_sha": "233dfb54ea1cd8e8085769832eef18fb3eaa04b7",
+      "base_ref": "main",
+      "merge_sha": "76044b5895e8abe5bd1e3bf45ccfe3ea7edcdc42",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 39,
+      "title": "Restore the EXT-1 proposal and request EXT-5 host document parse",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/39",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-06T15:14:15Z",
+      "head_ref": "refs/pull/39/head",
+      "head_sha": "5825cd35f2cde87a737d2dacdd2e4a393063e3bc",
+      "base_ref": "main",
+      "merge_sha": "e53c6bf177ee9bfa2ae85e1baa35378e122577e3",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 40,
+      "title": "Propose N1/Q1/I1 implementation plans for the agent stack",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/40",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T02:51:31Z",
+      "head_ref": "feature/agent-stack-n1q1i1-plans",
+      "head_sha": "54ead4197f844b9547a9275dbf9ba8ff639cb5e9",
+      "base_ref": "main",
+      "merge_sha": "dd9c1ba558b9154a66e1d9bcab1d52dd09ad5a8e",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 41,
+      "title": "Propose the RDM phase plan: direction, invariants, and stage gates",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/41",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T04:34:51Z",
+      "head_ref": "feature/rdm-phase-plan",
+      "head_sha": "b8eaa1676f168ad64c437857e2607e2e213f6672",
+      "base_ref": "main",
+      "merge_sha": "0551d003000107a511f26642e68a947680956fc6",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    },
+    {
+      "repo": "Agent-System-Documents",
+      "number": 42,
+      "title": "Propose the N2 implementation plan: context, protocol, and tools",
+      "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/42",
+      "state": "closed",
+      "merged": true,
+      "merged_at": "2026-10-07T12:38:28Z",
+      "head_ref": "refs/pull/42/head",
+      "head_sha": "96fd6599d1f2b60f44830ddae1b21185713269d9",
+      "base_ref": "main",
+      "merge_sha": "5542319a0474fd4e866b6daacb937b587c833ede",
+      "merge_in_fixed_main": true,
+      "reviews": []
+    }
+  ],
+  "open_pull_requests": {
+    "Agent-System-Dev": [
+      {
+        "number": 244,
+        "head_ref": "feature/agent-stack-n2",
+        "head_sha": "eae6992ae81335df5eb016223e2522fab952ae7f",
+        "title": "Take the N2 implementation plan and open the N2 task",
+        "url": "https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/244"
+      }
+    ],
+    "Agent-System-Documents": []
+  }
+}

docs/records/2026-10-08-rdm-status-probe-summary.json

@@ -0,0 +1,83 @@
+{
+ "generated_at": "2026-10-08T09:17:18+00:00",
+ "object": "Agent-System-RDM @ 4feb2f0 (pins=v0.1.0 四仓)",
+ "replays": {
+  "make test": {
+   "exit": 0,
+   "receipt": "test.json",
+   "receipt_sha256_16": "beadcc1ee93646d5"
+  },
+  "-ms1 ./docs/requirements": {
+   "exit": 0,
+   "verdict": "PASS",
+   "detail": "fa-chain 1130 切片（含重启存活）；stage-accuracy 100%（5/5，金标与 docProfiles 同源，样本全 BD）；two-speed 快速 0ms/慢速 done",
+   "receipt": "ms1.json",
+   "receipt_sha256_16": "be64043ec470b100"
+  },
+  "make ms0-acceptance (PG_CONTAINER=rdm-review-pg 一次性容器)": {
+   "exit": 0,
+   "verdict": "PASS=9 SKIP=0 FAIL=0",
+   "receipt": "ms0-acceptance.json",
+   "receipt_sha256_16": "b6a2c946d4fe9e50"
+  }
+ },
+ "upload_probes": {
+  "minutes.docx（真实纪要原件，私有：收据仅存本地不入库）": {
+   "exit": 0,
+   "wall_s": 0.78,
+   "parse": "rdm:docx parsed=true",
+   "verdict": "held 无关(疑似)",
+   "labels": "stage= workItem= topics=[]",
+   "note": "零字典命中；快速回执时限达标但无初步归类",
+   "local_receipt_sha256_16": "a29912f84b0c51fe"
+  },
+  "quote.xlsx（旧仓报价单模板）": {
+   "exit": 0,
+   "verdict": "unparsed rdm:unsupported",
+   "note": "原件留档可取回——EXT-5 不在 v0.1.0 pin"
+  },
+  "plan.pptx（python-pptx 构造图文稿）": {
+   "exit": 0,
+   "verdict": "unparsed rdm:unsupported",
+   "note": "同上"
+  },
+  "irrelevant.txt": {
+   "exit": 0,
+   "verdict": "held 无关(疑似)",
+   "note": "零命中挂起，确认前不入库（MS1 第3条行为）"
+  },
+  "broken.docx": {
+   "exit": 0,
+   "verdict": "unparsed rdm:docx parsed=false",
+   "note": "显式告知 zip 无效+原件留档（SR-A5 负例）"
+  }
+ },
+ "entrance_probes": {
+  "POST /api/commands/rdm.ping": {
+   "http": 200,
+   "state": "committed",
+   "note": "命令入口通"
+  },
+  "POST /api/conversations/{id}/messages text=/help": {
+   "http": 200,
+   "note": "对话入口 slash 路由对内置命令通"
+  },
+  "POST /api/conversations/{id}/messages text=/rdm.ping": {
+   "http": 400,
+   "body": "未知命令 /rdm.ping（/help 查看）",
+   "note": "插件命令无 slash 别名——对话入口不可达 RDM 命令"
+  },
+  "POST /api/chat (RDM 工作台 sendChat 的目标端点)": {
+   "http": 404,
+   "note": "端点在 v0.1.0 pin、基座 main、RDM 三处均不存在；工作台自由文本路径 404"
+  },
+  "receipts": [
+   "entrance.json",
+   "entrance2.json"
+  ]
+ },
+ "notes": [
+  "全部收据为 SELF（本机隔离克隆重放；RDM 仓无 CI，不存在 GATE）",
+  "残留进程（非本任务所起，未处置）：PID 2784320 (18799, 主检出 ./data) 与 PID 3096018 (18810, /tmp/rdm-init.* 旧实例)"
+ ]
+}

docs/records/2026-10-09-base-v0.2.0-release.md

@@ -0,0 +1,102 @@
+# 基座 v0.2.0 发版记录
+
+| 项 | 内容 |
+|---|---|
+| 状态 | **候选已就绪，tag 待 owner 执行**（高后果操作双钥匙：发布版本由 owner 亲手打 tag 并推送） |
+| 发版授权 | owner 2026-10-09 会话：「越快越好，你来执行即可，我已同意」（Q3）。Agent 完成候选组合、验证与本记录；tag 创建与推送按 AGENTS.md 双钥匙规则由 owner 执行 |
+| 主任务 | Dev 仓 `feature/base-v020-release`（任务卡即本次发版的主记录） |
+| 规范依据 | Agent-System-RDM `docs/materials/12-基座发版核对清单.md`；[扩展面兼容与演进](../proposals/2026-10-01-extension-compat-policy.md) §5 |
+
+## 1. 范围
+
+v0.2.0 是第二段发版：在 v0.1.0 评估基线之上，附 experimental 兼容承诺（实验窗口内仍可破坏性调整，但须改快照并在提案记录）。
+
+相对 v0.1.0 的公开面（`pkg/extension`，SurfaceVersion `2.0.0-experimental` → **`2.5.0-experimental`**）：
+
+| 扩展 | 公开面 | 来源 |
+|---|---|---|
+| EXT-1 | `Handler`、`Host`、`Request`、`Registry.AddCommandHandler` | Backend #66 |
+| EXT-5 | `Host.ParseDocument`；内置 xlsx/pptx 解析 | Backend #67、#68 |
+| EXT-8 | `ResourceAuthorizer`、`Registry.RegisterResourceAuthorizer`；工件/检索/项目流/向量/hostapi 共享读取 | Backend #105、#107、#109 |
+| EXT-9 | `Host.KnowledgePublish`、`Host.KnowledgeDelete`、`Options.DisableUploadIndexing` | Backend #106 |
+| EXT-11 | `SetScopedHostFactory`、`NewScopedHost` | Backend #108 |
+| EXT-12 | `Options.DisableConvCardMirror` | Backend #107 |
+| 执行原语硬关闭 | `Options.DisableExecTools`；CLI `--disable-exec-tools`、配置键 `disableExecTools`、环境变量 `AGENT_SYSTEM_DISABLE_EXEC_TOOLS` | Backend #110 |
+
+同时包含的缺陷修复与行为变化（不改公开面）：
+
+- 命令审计按 owner 存储与查询（v0.1.0 的 `GET /api/commands/audit` 跨租户可见；Backend `e0b1c27`，随 #105 合入）；
+- DOCX 解析保留修订插入、超链接与域结果内的文字；删除/移走的原文与域代码不进正文；含修订时显式告警（Backend #110）；
+- agent-stack N1–N3、Q1–Q3、I1–I2 阶段的库与接线（见 Backend #69–#103）。
+
+**升级须知（下游）**：
+
+- 多用户共享部署在执行隔离就位前，应设置 `Options.DisableExecTools = true`。只关闭用户设置 `runtime.exec` 不够，因为任何用户都能经 `PUT /api/settings/user` 把它改回 true。
+- 下游 go.mod 的 8 条 deps replace 不变（compat-policy §4）。
+- 下游兼容验证：RDM PR #113 头 `d49d5c9` 的源码在 replace 指向本次 backend 候选时 `go build ./...` 与 `go test ./...` 通过（SELF，2026-10-09）。
+
+## 2. 候选组合
+
+| 仓 | 提交 | 依据 |
+|---|---|---|
+| Backend | 由 Dev 合入提交的 gitlink 决定（Backend main `f1c9cc0` 或其后） | Backend #110 合入；CI `ci / vet-and-test (push)` success |
+| Core | `a253a40b8e5563119b00c4e71fb61fe0d11d6d6a` | == Dev gitlink == backend `deps/agent-system-core`（同 commit 约束） |
+| Frontend | `84b73ab32848e623d0a0ab7ade552784dca8cf3c` | == Dev gitlink == Frontend main |
+| UI | `76d6633736a7abb36ac1ecca42fe4e6f120d0558` | == Dev gitlink == UI main |
+| Dev | 本任务 PR 合入 main 后的合入提交 | Dev CI（PR HEAD `make test` + `make build`） |
+
+最终 SHA 以 Dev 合入后 `git ls-tree <Dev 合入提交> modules/` 的实际输出为准，执行前按 §4 核对。
+
+**UI 仓自身 CI 现状**：UI 仓 `ci.yml` 跑在 `nightly` 运行器上，自 2026-10-04 起每次都失败于 vitest 启动（`Cannot find native binding`，rolldown 可选依赖），与代码无关。同一 UI 提交在 Dev 组合 CI 中 `npm ci && tsc && vitest` 通过（14 文件 / 103 用例；Dev run 1369），本地 Node 26 复验同样通过。v0.2.0 以 Dev 组合 CI 为 UI 的权威验证；UI 仓 runner 修复另列后续任务。
+
+## 3. tag 消息（五仓一致）
+
+```
+SurfaceVersion 2.5.0-experimental. Adds in-proc command handlers, the owner-scoped host handle, document parsing, resource authorization, knowledge publish/revoke, scoped host recovery, the card mirror switch and the exec hard switch.
+```
+
+## 4. owner 执行步骤
+
+先在 Dev 主检出确认合入后的组合（只读）：
+
+```bash
+cd /home/weichen/projects/Agent-System-Dev && git fetch origin && git checkout main && git pull --ff-only
+git status --porcelain                         # 必须为空
+DEV=$(git rev-parse origin/main); echo $DEV
+git ls-tree $DEV modules/backend modules/core modules/frontend modules/ui
+# core 同 commit：以下三行必须相同
+git ls-tree $DEV modules/core | awk '{print $3}'
+git -C modules/core rev-parse HEAD
+git -C modules/backend/deps/agent-system-core rev-parse HEAD
+```
+
+然后子仓先、Dev 后，逐仓打 tag（`<SHA>` 用上面 `ls-tree` 打印的该仓 gitlink）：
+
+```bash
+MSG='SurfaceVersion 2.5.0-experimental. Adds in-proc command handlers, the owner-scoped host handle, document parsing, resource authorization, knowledge publish/revoke, scoped host recovery, the card mirror switch and the exec hard switch.'
+for m in backend core frontend ui; do
+  SHA=$(git ls-tree $DEV modules/$m | awk '{print $3}')
+  git -C modules/$m fetch origin && git -C modules/$m tag -a v0.2.0 "$SHA" -m "$MSG" && git -C modules/$m push origin v0.2.0
+done
+git tag -a v0.2.0 "$DEV" -m "$MSG" && git push origin v0.2.0
+```
+
+推完核对（五处一致）：
+
+```bash
+for m in backend core frontend ui; do
+  echo "$m tag=$(git -C modules/$m rev-parse v0.2.0^{commit}) gitlink=$(git ls-tree v0.2.0 modules/$m | awk '{print $3}')"
+done
+git ls-remote --tags origin v0.2.0
+```
+
+## 5. 发版后（Agent 可执行，tag 在位后启动）
+
+- RDM 升钉到 v0.2.0 五仓 tag，并重定基合入 #113/#114（RDM 计划 G1-1）；
+- RDM 二进制设置 `DisableExecTools: true`（RDM 计划 G1-7）；
+- Releases 仓按 `scripts/build-release.sh 0.2.0` 构建制品与 manifest（另立任务，内部发布，不公开）。
+
+## 6. 不做的事
+
+- 不使用 `v0.2.0-experimental` 这类 tag 名；不在实验窗口发布 npm；不改 Go module path。
+- RDM 仓 v0.2.0 tag 不在本次范围（RDM 升钉完成后另行评估）。

docs/records/2026-10-11-collaboration-storage-plan-review.md

@@ -0,0 +1,31 @@
+# 协作存储方案 r1 静态审阅记录
+
+对象：[方案 r1](../proposals/2026-10-11-collaboration-storage-and-distribution.md)。
+日期：2026-10-11（Asia/Shanghai）。来源：SELF，Agent 辅助静态审阅。
+三个 Agent 分别兼任两个视角：coherence/scope-guardian、feasibility/adversarial、security/product。
+同一 Agent 的两个视角不互相独立；没有跨模型审阅、独立测试重放、CI GATE 或人工批准。
+使用 ce-doc-review 的检查视角，覆盖与边界以本记录为准，不声称已运行额外外部模型审阅。
+
+## 发现与处置
+
+| 发现 | 原方案后果 | 修订处置 | 复核 |
+|---|---|---|---|
+| 正式导入与非空目标拒绝冲突 | 预演后可能无法最终导入，或放宽规则混入其他快照 | U4/§6 分开预演与正式空目标；migration_id+快照身份，只有同快照可续传，验证完成后切入口 | 原审阅 Agent 已确认文本闭合 |
+| 恢复隔离晚于首期切换 | 现有 ResumeInterruptedChildren 可能自动重派未知副作用任务 | U3 前移持久 recovery hold，启动续跑跳过，U7 放行前验证 | 原审阅 Agent 已确认文本闭合 |
+| 命令只绑定旧 epoch | owner 切换后取消或审批意图可能丢失 | KTD5 区分逻辑 run 取消、gate/version 审批与按 epoch 验证的执行结果 | 原审阅 Agent 已确认文本闭合 |
+| 父子共享额度可能互等 | 父 run 占满许可并等待不能启动的子 run | §3/U3 区分接纳数与执行许可，等待父 run 让出许可但保留会话所有权 | 原审阅 Agent 已确认文本闭合 |
+| U6 先于 outbox 依赖 | 提前声明事务投递机制完成或重复建设 | U6 分追赶修复、outbox、向量三个切片并分别列前置 | 原审阅 Agent 已确认文本闭合 |
+| P0 权限检查落到后期 | 首期团队版可能未验证 SSE/检索/工具撤权 | U7 单实例放行前验证完整现有 R6 入口矩阵；新增跨机能力另验 | 原审阅 Agent 已确认文本闭合 |
+| 过渡期本地权威未说清 | 尚未迁移的 checkpoint/续跑文件可能被当缓存清除 | KTD2 增加首期与多实例期归属表，联合备份，U5 前禁止跨机接管 | 原审阅 Agent 已确认文本闭合 |
+| 只读适配器不足以判断写入/审批 | 可能把共享可读扩大成可写 | KTD13/U3 指定动作授权矩阵、版本化兼容与默认拒绝，不新建成员权威 | 原审阅 Agent 已确认文本闭合 |
+| 迁移/备份敏感副本保护未列 | 源库秘密可能经备份旁路暴露 | KTD14 指定访问、加密、密钥分离、保留与恢复验证；正式导出前缺项阻塞 | 原审阅 Agent 已确认文本闭合 |
+
+主编另依据 PostgreSQL 官方 PITR 文档修正备份描述：pg_dump 是逻辑备份，不能作为 WAL 回放基础；PITR 使用物理基础备份加连续 WAL。未改变用户确认的规模与未来分布式方向。
+
+## 剩余决策与验证边界
+
+- 10–100 人、多项目、多会话及未来多服务分布式：用户已确认需求方向。
+- 量化容量/恢复目标、正式实例和数据归属、迁移窗口、资源与实施阶段：待人工评审。
+- 本记录只说明文档中的九项问题已经改写并由原 Agent 复读，不说明实现缺陷已修复。
+- 实施、真实 PG/Redis 测试、压测、故障注入、数据迁移、恢复演练与部署：全部 NOT_RUN。
+- 方案正文与调查收据的字节摘要由文档检查命令写入 Dev 任务卡，作为本次候选身份；本文件不手写命令结果。