Compare commits
25
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 weichen
|
238f90e92a | ||
|
weichen
|
d3c9b4554e | ||
|
weichen
|
176db44c4b | ||
|
weichen
|
69360de5bb | ||
|
weichen
|
9995552152 | ||
|
weichen
|
4e57196a8e | ||
|
weichen
|
4ce8155161 | ||
|
weichen
|
09d968cb2f | ||
|
weichen
|
9505c7eadc | ||
|
weichen
|
cafd10b44b | ||
|
weichen
|
d630a040be | ||
|
weichen
|
ec5114d621 | ||
|
weichen
|
c39efdc501 | ||
|
weichen
|
b825945c1d | ||
|
weichen
|
b9590150cc | ||
|
weichen
|
16795ed598 | ||
|
weichen
|
a042edaa73 | ||
|
weichen
|
5ccbe027ca | ||
|
weichen
|
c13c79ebac | ||
|
weichen
|
f8cc211296 | ||
|
weichen
|
8366668e44 | ||
|
weichen
|
b87b929673 | ||
|
weichen
|
5542319a04 | ||
|
weichen
|
96fd6599d1 | ||
|
weichen
|
0551d00300 |
@@ -2,6 +2,9 @@
|
||||
|
||||
系统文档与过程记录仓：架构决策、方案与验证记录、使用与插件开发指南；不含产品代码。
|
||||
|
||||
从 [项目方向与规划索引](docs/proposals/INDEX.md) 查找主记录、里程碑、关联任务及待确认差异。
|
||||
索引给出固定版本的核验快照；方案批准、PR 合入和运行验收分别记录。
|
||||
|
||||
## 目录
|
||||
|
||||
```text
|
||||
|
||||
@@ -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` |
|
||||
@@ -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） |
|
||||
@@ -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` |
|
||||
@@ -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/` |
|
||||
@@ -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` |
|
||||
@@ -8,7 +8,7 @@
|
||||
| 面 | 标识 | 规则 |
|
||||
|---|---|---|
|
||||
| 插件清单 | `apiVersion` | 接受 `1.0` 与 `2.0-experimental`。其他值整包拒绝（fail-closed） |
|
||||
| 公开 Go 包 | `extension.SurfaceVersion` | `2.0.0-experimental`。实验窗口内允许破坏性调整，但必须改契约快照并在提案里写一句 |
|
||||
| 公开 Go 包 | `extension.SurfaceVersion` | 实验系列 `2.x.0-experimental`（2026-10-09 v0.2.0 时为 `2.5.0-experimental`，每次加法升次版本号）。实验窗口内允许破坏性调整，但必须改契约快照并在提案里写一句 |
|
||||
| HTTP API | 路径前缀 `/api/` 与 `/host/v1/` | 已发布路径只加字段，不改语义、不删字段。新能力用新路径 |
|
||||
|
||||
弃用：公开符号先标记注释 `Deprecated:`，至少一个下游可升级的版本之后才删除。实验窗口内的删除仍要改快照测试，不能静默。
|
||||
@@ -45,10 +45,11 @@ replace agent-system-core => ../Agent-System-Dev/modules/core
|
||||
|
||||
## 5. 发版命令（owner 执行，本次未执行）
|
||||
|
||||
tag 名以 V1.2 实施推进方案批复的 `v0.2.0` 为准（2026-10-05 对齐；五仓 backend/core/frontend/ui/Dev 同打）：
|
||||
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 "extension surface 2.0.0-experimental"
|
||||
git tag -a v0.2.0 <该仓对应提交> -m "<发版记录里的消息>"
|
||||
git push origin v0.2.0
|
||||
```
|
||||
|
||||
|
||||
@@ -252,6 +252,13 @@ Backend 把 `WorkflowDef` 编译成 Squad 的图。`internal/workflow` 与把小
|
||||
|
||||
验收：分类器返回未知 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 组合：少量真实任务加人工复核，不把模型自报当通过。
|
||||
|
||||
@@ -9,6 +9,7 @@
|
||||
- **希望符号**：`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 项）
|
||||
|
||||
|
||||
@@ -321,3 +321,63 @@ WP1 命令模型 → WP2 ActionRef 迁移（刻画测试先行）→ WP5 决胜
|
||||
- 三个阶段的实施方案各自满足：工作包可独立派生任务卡、验收条款可机器核对、与总提案逐条映射（§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 消费」两条产品化路径。
|
||||
- 本节维护规则与索引一致：状态再次变化时先更新本节并同步索引导航。
|
||||
|
||||
@@ -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 的回落用例为放行门槛）。
|
||||
@@ -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 保证，测试钉住「一次且仅一次」。
|
||||
@@ -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）。
|
||||
@@ -48,6 +48,10 @@
|
||||
|
||||
## 2. 现状基线（2026-10-07 实测）
|
||||
|
||||
> **历史快照注记（2026-10-08）**：本节为 2026-10-07 撰写日快照，其中三处已随后游
|
||||
> 密集交付失效（下游功能为零、库分期进度、O1/O3/O7 阻塞）。原文保留不改写，
|
||||
> 逐行复核与现行状态见 §2.3；阅读与排期以 §2.3 为准。
|
||||
|
||||
### 2.1 已就位
|
||||
|
||||
| 项 | 状态 | 证据/位置 |
|
||||
@@ -72,6 +76,57 @@
|
||||
| 库分期 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. 架构裁定
|
||||
|
||||
@@ -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）。
|
||||
@@ -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 推翻，以本文为准）。
|
||||
@@ -0,0 +1,153 @@
|
||||
# 项目方向与规划索引
|
||||
|
||||
状态：**已获合入授权（2026-10-08）**。编制依据：用户同意整理既有规划主记录、确认状态、里程碑和关联任务；同日授权收尾并合入。
|
||||
本索引负责导航与差异提示，规划正文、批准范围和验收条件仍以链接的主记录及其批准版本为准。
|
||||
合入授权不批准新方向、不调整里程碑范围、不启动新的业务任务。
|
||||
|
||||
## 先看哪一份
|
||||
|
||||
| 要回答的问题 | 主记录导航 | 规划中的阶段 | 原文负责人 |
|
||||
|---|---|---|---|
|
||||
| 通用系统的原始边界与架构是什么 | [系统骨架](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 |
|
||||
|
||||
以上是依据文内显式范围和引用形成的阅读入口，不是新增优先级或批准结论。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；受理后逐条另立实现任务 |
|
||||
|
||||
原查询的 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、版本与在途任务；新的索引状态不自动产生实施授权。
|
||||
File diff suppressed because one or more lines are too long
@@ -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": []
|
||||
}
|
||||
}
|
||||
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
File diff suppressed because one or more lines are too long
@@ -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.* 旧实例)"
|
||||
]
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because one or more lines are too long
@@ -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 升钉完成后另行评估）。
|
||||
Reference in New Issue
Block a user