Compare commits

...
Author SHA1 Message Date
weichen 4a3ca0eb5a Backfill the S0-1 completion in the plan and index 2026-10-11 02:29:16 +00:00
weichen 9a46785ee0 Merge pull request 'Backfill the E4 completion in the plan and index' (#57) from feature/e4-progress into main 2026-10-11 01:34:48 +00:00
weichen cc54cdac76 Backfill the E4 completion in the plan and index 2026-10-11 01:34:07 +00:00
weichen b37f45ff61 Merge pull request 'Backfill the E5 MiniMax-family A/B result' (#56) from feature/e5-progress into main 2026-10-10 17:28:06 +00:00
weichen 077ebdf184 Backfill the E5 MiniMax-family A/B result in the plan and index 2026-10-10 17:27:25 +00:00
weichen e986a85436 Merge pull request 'Backfill the E3 completion in the plan and index' (#55) from feature/e3-progress into main 2026-10-10 16:39:56 +00:00
weichen 19b77a28bc Backfill the E3 completion in the plan and index 2026-10-10 16:39:02 +00:00
weichen 3a82eec74c Merge pull request 'Backfill the E1 increment completion in the plan and index' (#54) from feature/e1-progress into main 2026-10-10 10:03:49 +00:00
weichen 352b7aa540 Backfill the E1 completion status in the index row too 2026-10-10 09:47:50 +00:00
weichen a379a9fbe6 Backfill the E1 increment completion in the plan and index
Why: The E1 quick-fix increment landed (delegate full text, MiniMax
reasoning split, sandbox deps layer, parallel tool execution with kernel
ordering) and the proposal is the master record, so its stage table and
the index row must reflect the actual progress with links.

Evidence: Agent-Native #42/#43/#44, Backend #127, Dev task
feature/agent-e1-parallel-fixes (live verification receipts: F2 zero
think-leak, F3 sandbox IMPORTS-OK, F5 concurrent overlap; eval
toolFailures 19->11, unverifiedFacts 7->12 recorded honestly).

Impact: Documents-only progress backfill; E2-E5/S0 remain unauthorized.
2026-10-10 09:47:25 +00:00
weichen 0f6d6974ef Merge pull request 'Propose the delegation, model-routing and task-sandbox plan' (#53) from feature/agent-exec-routing-sandbox-plan into main 2026-10-10 07:40:41 +00:00
weichen 3947a12700 Propose the delegation, model-routing and task-sandbox plan
Why: The user asked for a researched design covering subagent use,
tiered model routing (Claude via dmxapi for complex work, MiniMax for
the rest), a millisecond/sub-second task sandbox (record-only), and a
verdict on why the agent still feels weaker than codex/claude-code/kimi.
Why: Four research threads (external frontier survey, subagent/routing
evidence, harness-vs-model attribution, local code audit and probes)
converge on role/stage routing instead of whole-task routing, and on
three corrections to the sandbox assumptions (overlay is not a snapshot;
snapshots defer conflicts to merge time; destroy must follow sealing).

Evidence: Local measurements are SELF receipts in the Dev task card
(bwrap namespace ~7ms, overlay same, docker ~142ms; MiniMax reasoning
split; dmxapi /v1/messages cache_read; EXT-16 sandbox missing the
python-docx layer). External claims carry per-item source URLs in the
proposal's section 8.

Impact: Documents-only addition: new proposal 2026-10-10 (E1-E5/S0
increments, D/R workstreams, sandbox tiers L0-L2) plus INDEX rows for it
and the previously unlisted G1 package. No product code changes; all
implementation increments stay unauthorized until approved.

Refs: proposals/2026-10-09-agent-quality-improvement-plan.md (P4/P5,
model A/B), 2026-10-09-ext-g1-b1-b3-exec-backend.md (EXT-16),
Dev task feature/agent-exec-routing-sandbox-plan.
2026-10-10 07:39:56 +00:00
weichen 3e43193f45 Merge pull request 'Propose the G1 extension package: EXT-13..16 (shared retrieval, commands-as-tools, shared project list, exec backend)' (#52) from feature/g1-ext-b1-b3-proposal into main 2026-10-09 14:50:07 +00:00
weichen 1f8ad3b99b Propose the G1 extension package: shared in-run retrieval, commands-as-tools, shared project list, exec backend
Why: RDM G1/G2 are blocked on four base capabilities - the member agent
cannot see published project knowledge inside a run, plugin commands are
unreachable as tools, members cannot see or open conversations in shared
projects, and the isolated exec tier needs a backend seam.
Evidence: SELF - code citations verified at Dev main (runmgr.go:726-736
owner-only Retrieve; hostcaps.go:64-66 owner-only search; server.go:438-441
owner-only listProjects; store/projects.go:124-130 owner-scoped conversation
creation); bwrap availability tested on this host (2026-10-09).
Impact: Docs only. New proposal docs/proposals/2026-10-09-ext-g1-b1-b3-exec-backend.md
registering EXT-13..EXT-16 per the compat-policy template; no code change.
Refs: RDM plan V1.1 sections 3.3/3.4/5.3; owner Q1-Q8 (Q4=option A, Q2)
2026-10-09 14:49:56 +00:00
weichen 9206e0d77c Merge pull request 'Record the agent quality improvement plan and six user rulings' (#51) from feature/agent-quality-plan into main 2026-10-09 14:12:56 +00:00
weichen 238f90e92a Record the agent quality improvement plan and its six user rulings
Why: The 2026-10-09 diagnosis on real run transcripts identified the direct
conversation path's failure chain and a phased plan was approved with six
explicit user rulings (open up tools, kernel-transcript-authoritative context,
markdown-source deliverables with all file types retained, gate demotions,
uncapped stronger-model evals, real-model eval required for behavior changes).
The plan needs a durable main record per the long-term-direction policy, and
the 2026-09-30 preview proposal's "fs tools hidden by default" ruling is
superseded by ruling 1, which must be discoverable from the index.

Evidence: SELF - the record cites the diagnosis session, the transcript
sources (pg1 + legacy SQLite, 62 assistant turns) and the before-baseline
report location on the task card; no code or pointers changed in this repo.

Impact: New proposal 2026-10-09-agent-quality-improvement-plan.md plus one
index row. Subsequent phase tasks reference this record instead of restating
the plan.

Refs: Dev task feature/agent-quality-phase01; supersedes the fs-tool default
in 2026-09-30-file-preview-and-reserved-capabilities.md §2.3.
2026-10-09 12:42:33 +00:00
weichen d3c9b4554e Merge pull request 'Record the v0.2.0 base release scope and owner tag steps' (#50) from feature/v020-release-notes into main 2026-10-09 10:46:32 +00:00
weichen 176db44c4b Record the v0.2.0 base release scope and owner tag steps
Why: v0.2.0 is the hard prerequisite for RDM shared work, and the release
checklist referenced a stale SurfaceVersion and tag message.
Evidence: SELF - scope lines are tied to merged Backend PRs (#66-#110);
Backend #110 CI success; UI composite run 1369 shows 14 files/103 tests.
Impact: Adds docs/records/2026-10-09-base-v0.2.0-release.md and points the
compat policy and the EXT-1 proposal at the actual 2.5.0-experimental line.
Tag creation and push stay with the owner (dual-key rule).
Refs: Dev feature/base-v020-release; Backend #110
2026-10-09 10:44:33 +00:00
weichen 69360de5bb Merge pull request 'Propose the C1-C7 base extension package for RDM shared contracts' (#49) from feature/ext-c1-c7-applications into main 2026-10-08 15:22:39 +00:00
weichen 9995552152 Propose the C1-C7 base extension package for RDM shared contracts
Why: U0 (merged in RDM) rules that domain logic stays downstream and the base needs seven minimal generic capabilities; the formal four-element applications are the only legal path to base changes.
Evidence: All current-state citations re-verified at Dev 34a2bbe (backend fe7c245); RDM requirement source pinned at RDM main ca72cfc.
Impact: New proposal doc + one INDEX row; no code, no surface change in this PR.
Refs: RDM U0 proposal section 5 / ruling D1; extension-compat-policy; phase-plan section 3.3.
2026-10-08 14:44:56 +00:00
weichen 4e57196a8e Merge pull request 'Add architecture guides with worked examples' (#48) from feature/architecture-guides into main 2026-10-08 09:37:36 +00:00
8 changed files with 729 additions and 3 deletions
@@ -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
```
@@ -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 项)
@@ -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,124 @@
# EXT 申请包 · G1:回合内共享检索、命令即工具、项目列表共享与执行后端接口(B-1/B-2/B-3 + B-5②)
状态:**proposed(2026-10-09)**;owner:weichen;需求依据 = RDM 评审与实施方案 V1.1
(`Agent-System-RDM docs/proposals/2026-10-09-V22-review-and-implementation-plan.md` §3.3/§3.4/§5.3,
owner 2026-10-09 Q1–Q8 批复;Q4=方案 A,Q2=暂时禁用+隔离档)。
撰写日期:2026-10-09。配套:[扩展面兼容与演进](2026-10-01-extension-compat-policy.md)、
[EXT 申请包 C1–C7](2026-10-08-ext-c1-c7-rdm-shared-contracts.md)(EXT-6…EXT-12)。
## 0. 总则
- 本包四条申请按既有序列顺延 **EXT-13…EXT-16**;最终编号以受理评审为准。
- 分期(对齐 RDM 方案 §5.2):B-1(EXT-13)与 B-3(EXT-15)为 **G1 序 4 的硬前置**
(成员智能体看不到项目知识 = R04 路径不通);B-2(EXT-14)为 G2/V0.1 端到端的硬前置
(对话入口无法触达 `rdm.*`);B-5②(EXT-16)为 G2-8 原型的前置。
- SurfaceVersion 影响:EXT-14 触及 `pkg/extension` 导出面(命令规格新字段)→ 需升
SurfaceVersion 并同步 surface.txt;EXT-13/15/16 为 internal 行为扩展,不改导出面
(EXT-16 若只加 `Options` 字段则属加法,见 §4)。
## 1. EXT-13(←B-1)回合内共享检索:智能体的检索遵循项目共享授权
- **场景**:RDM R04/R05——成员 B 的智能体在**回合内**(ReAct 循环的 `knowledge_search`
工具与自动知识注入)必须能检索到成员 A 已发布的项目知识;现状只能看到本人 owner 的
知识。HTTP 面(`/api/…/search`)已走 `RetrieveShared`(EXT-8 余项,Dev #269/#273),
但回合内两条路径仍是 owner-only:
- `internal/runmgr/runmgr.go:726-736` `runCtx.Retrieve` → `retriever.Retrieve(ctx, c.run.Owner, q)`(owner-only);
- `internal/app/hostcaps.go:64-66` `hostcaps.search`(进程内 `Host.KnowledgeSearch` 底座)→ `pipe.Retrieve(owner)`(owner-only)。
结果:同一个成员,页面搜索能看到共享知识,**智能体对话里看不到**——「所有用户的智能体
应当能够看到项目级的共享信息」(用户补充材料 §2树1图)走不通。
- **希望公开面**:组合根把 EXT-8 适配器(`Server.ProjectAuthz` 同款判定函数)注入
runmgr 与 hostcaps:两条检索路径在本人 owner 两路(全文+向量)如常之外,追加
「经适配器放行的共享两路」——与 HTTP 面 `rag.Pipeline.RetrieveShared` 完全同一实现与
同一授权判定(复用 `sharedVisible`/`SearchKnowledgeShared`,不另造第二套语义)。
进程内 `Host.KnowledgeSearch` 同步走共享版。
- **为何组合不出**:`RetrieveShared` 已存在,但 runmgr/hostcaps 没有适配器的引用——
适配器槽在 `internal/app/hostcaps.go` 的 `projectAuthz`,由组合根在装载扩展后注入
Server;runmgr 的构造早于扩展装载,且 `Manager` 无该依赖。下游无法经任何公开面把
「按 owner 判定共享」的回调递进回合执行路径。
- **兼容方式**:适配器未注册=现状(本人两路);注册后共享命中追加、RRF 融合。
不动 `pkg/extension` 导出面,SurfaceVersion 不变。
- **验收**:同项目两人+另一项目一人(RDM 成员表桩):成员 B 发起对话,模型经
`knowledge_search` 命中 A 已发布的知识切片(共享命中出现在工具结果);未授权者与
跨项目者为零命中;`Host.KnowledgeSearch`(hostapi 与进程内两形态)行为一致;
未注册适配器时与现状逐字节一致(回归)。
## 2. EXT-14(←B-2)插件命令即工具:`exposeAsTool`(Q4 方案 A)
- **场景**:RDM V0.1 端到端(C-11)要求「从空项目创建到生成项目建议书,全对话完成」;
RDM 的全部能力(两树一网读写、上传、起草、追溯查询)都登记为 `rdm.*` 命令,而智能体
回合的工具清单里没有任何插件命令——模型既不能检索笔记树,也不能发起 `rdm.draft.compose`。
U0 §3.3/方案 §3.3 裁定走**方案 A**:命令经命令总线暴露为工具,四入口同源
(button/card/slash/chat)自然延伸出第五入口「智能体」。
- **希望公开面**:命令规格(`agentcommand.CommandSpec` 经 `Registry.AddCommandHandler`
登记的 JSON)新增可选字段 `"exposeAsTool": {"risk": "low|medium|high"}`(缺省不暴露)。
runmgr 装配工具清单时,把带该字段的命令投影为工具描述(名称=命令 id,参数=命令
paramsSchema);模型调用该工具时,**不分发为工具执行,而是构造 `cmdbus.Request` 经
命令总线分发**(Entrance="agent",Actor=会话 owner,ConversationID=当前会话)——
同一审计信封、同一 HITL 内联确认卡(`risk=high` 或命令规格要求确认时照常弹卡)、
同一危险分级。
- **为何组合不出**:`Registry` 只有 AddSkill/AddCommand/AddCommandHandler/Note/
RegisterResourceAuthorizer;工具注册表(`tools.Registry`)与命令总线之间没有任何
桥接;MCP 通道(方案 B)绕过命令总线与确认卡,与 SR-E6/HITL 门禁冲突,已被 Q4 否决。
- **兼容方式**:`pkg/extension` 命令规格加可选字段=导出面加法,SurfaceVersion 升
(建议 2.6.0-experimental)+ surface.txt 同步。缺省(不写 exposeAsTool)=现状零差异。
- **验收**:带 `exposeAsTool` 的 `/rdm.ping` 出现在模型工具清单且调用返回回执,
审计信封 Entrance="agent" 与按钮入口同源;`risk=high` 的暴露命令在对话内触发内联
确认卡;不带字段的命令不出现;RDM 侧 `rdm.trace`/`rdm.baseline` 等只读命令可在
回合内被模型调用(成员 B 场景结合 EXT-13)。
## 3. EXT-15(←B-3)项目列表与建会话的共享放行(SR-G10)
- **场景**:RDM R03——成员 B 被加入项目后「界面自动出现该项目,可直接开始工作(新建
对话)」。基座 `projects` 表按 owner 硬隔离(`store/projects.go:22-34`):
- `GET /api/projects`(`server.go:438-441` `listProjects`)只返回本人 owner 的项目——成员看不到共享项目;
- `POST /api/projects/{id}/conversations`(`store/projects.go:124-130`)校验「项目属于请求者」——成员在共享项目下建会话被 404。
EXT-8 已放行的入口(工件三入口、SSE 项目流、检索)不含这两处。
- **希望公开面**:这两处入口在 owner 自有判定未命中时咨询同一 EXT-8 适配器:
`listProjects` 追加经适配器放行的项目(去重、标注 `shared: true` 字段供前端区分
展示);`CreateConversation` 的归属校验放宽为「本人自有 **或** 适配器放行」。会话
本身仍归属创建者(owner 不变),只是创建权扩展到成员。
- **为何组合不出**:`ListProjects(owner)` 的 SQL 按 owner 过滤,无回调;建会话校验在
store 层硬编码。与 C4(EXT-8)同因:纯下游无法改变基座 owner 过滤。
- **兼容方式**:未注册适配器=现状;放行结果带审计。internal 行为扩展,SurfaceVersion
不变。
- **验收**:成员 B 的 `GET /api/projects` 含共享项目(shared 标注)且不含未授权项目;
B 在共享项目下 `POST conversations` 成功、会话 owner=B;撤销成员后两者立即拒绝;
项目拥有者视角无任何变化。
## 4. EXT-16(←B-5②)执行后端接口:隔离执行档(Q2 阶段二,G2-8 原型)
- **场景**:Q2 裁定「暂时禁用,但后续执行任务时肯定还是要代码执行能力」。v0.2.0 已
交付启动级硬关闭(`Options.DisableExecTools`,Backend #110);隔离档是恢复执行能力的
路径:执行的是**模型生成的代码**,须按不可信代码对待(方案 §3.4):只读系统根、仅挂
会话工作目录与技能目录、默认无网、cgroup 资源限额、硬超时、按项目 venv 只读挂载;
本机已实测 `bwrap --unshare-all` 可用(无特权 userns 被 AppArmor 限制,bwrap 专门
策略放行)。
- **希望公开面**:`internal/tools/exec_interpreter.go` 的进程启动点抽象为「执行后端」
接口(`ExecBackend`:`Run(spec) → result`),启动参数选择后端:
`ExecBackend = direct | sandbox`(缺省 direct=现状)。sandbox 后端以 bwrap 实现
(资源限额经 systemd-run/cgroup v2)。`extension.Options` 增加
`ExecBackend string`(加法;空=direct)。`DisableExecTools` 保留为最终兜底,优先级
高于后端选择。
- **为何组合不出**:现实现直接 `exec.Command`(`runInterpreter`),无后端抽象;沙箱
参数组装(bind 清单、网络命名空间、限额)属平台面,下游插件无法注入。
- **兼容方式**:缺省 direct=逐字节现状;`Options` 加字段=SurfaceVersion 升。RDM 在
G3-7 才切换 sandbox;G1–G2 期间维持 `DisableExecTools=true`。
- **验收**:sandbox 后端下逃逸负例全部被拦——读 `~/.secrets`、读其他会话目录、访问
外网、fork 炸弹、超时不可杀均为拒绝/杀灭;会话工作目录内 docx 生成任务成功且产物
可登记;direct 后端与现状一致(回归)。
## 5. 不在本申请包(显式排除)
- EXT-6/7/10/12 完整形态:仍在 C1–C7 包(EXT-6…12)受理轨道,节奏不变。
- 提示词随执行可用性切换(`base.deliverables` 在禁用期的降级文案):基座自有任务,
不占 EXT 编号。
- UI 仓 nightly runner 修复:与代码无关(rolldown 原生绑定缺失),另立任务。
## 6. 受理建议
| 申请 | 内容 | 优先级 | 兼容 |
|---|---|---|---|
| EXT-13 回合内共享检索 | G1 序 4 硬前置(R04/R05) | **P0 最先** | 不变(internal) |
| EXT-15 项目列表/建会话共享 | G1 序 4(R03/SR-G10) | P0 | 不变(internal) |
| EXT-14 命令即工具 | G2/V0.1 端到端硬前置(Q4 方案 A) | P1 | 升(加字段) |
| EXT-16 执行后端接口 | G2-8 原型(Q2 阶段二) | P1 | 升(加字段) |
@@ -0,0 +1,242 @@
# 子代理分工、模型分级路由与任务沙箱:调研与方案
状态:**proposed(2026-10-10)**;owner:weichen;方向来源:用户 2026-10-10 会话
(①充分利用子代理;②复杂任务用 dmxapi 的 Sonnet/Opus,常规任务用 MiniMax-M2.7-highspeed;
③记录并规划毫秒/亚秒级任务沙箱,**暂不实现**;④对「体感不如 codex/claude code/kimi」的判断)。
本文是这四件事的主记录;未经评审的部分一律为「待确认」,不因被记录而视为已批准。
依据级别:本机实测为 **SELF**(命令与输出见任务卡 evidence 与 §7 复现脚本);外部资料为
一手页面抓取(访问日 2026-10-10,URL 在 §8);推断明确标注「推断」。
## 0. 结论先行
1. **方向对,落点要改。** 子代理只在「读多写少、可并行、输出冗长」的环节净收益为正;
交付物的写作与关键决策保持单线程(单一写者)。把复杂任务**整单**交给 Claude,会把最贵、
最慢的模型放在 token 最多的工具循环里——A/B 里 opus-5-5 耗时约 4.7 倍、工具失败更多。
证据更支持**按阶段/角色路由**:Claude 只做 token 少、杠杆大的环节(复杂任务的规划简报、
终稿综合、独立核查),检索、阅读、抽取、跑 Python、排版留给 MiniMax。
2. **「体感差」不能主要归因于 MiniMax。** 同一模型换 harness 的分差与相邻代际换模型同量级
(MiniMax-M2.1 换 harness 差 7.0 分;同 harness 换成 Opus 4.5 差 3.9–7.4 分 [H11])。
本机实测还发现两处直接拖累体感的协议层问题(§1.2),应先修再下结论。
3. **「编造数字」更像模型属性,但可以用机制压住。** 同 harness 下 7→0 支持这一点;但
24 个相关观测里「0 处」的 95% 置信上界约 12.5%,不足以宣称清零(§1.3)。数字溯源闸门
比换模型便宜,且两者可叠加。
4. **沙箱:现在的需求表述里有三处需要修正**(§4.1)——overlay 不是快照、快照只是把冲突
推迟到合并、「立即销毁」必须先留存审计材料。修正后,本机条件下 **bwrap + 冻结基底 +
overlay** 能做到约 7ms 启动(实测),足够作为默认档;microVM 档只在需要更强隔离时启用。
## 1. 现状核实(SELF,2026-10-10)
### 1.1 已有能力(源码,backend `421fee8`,其 deps/agent-native `3b92cb6`)
| 能力 | 现状 | 位置 |
|---|---|---|
| 子代理委派 | 模型可调 `delegate_task`,参数 `agent∈{general,explore,research,plan,verify,writer}`、`task`、`background`;深度 1(子不能再派) | `internal/runtime/llm.go:310`、`internal/runtime/llm_direct.go:668`、`internal/runmgr/runmgr.go:1462` |
| 子代理模型 | 由画像 frontmatter 决定:`writer` 用 `chat` 档,其余 7 个用 `lightweight` 档;调用方**不能**指定模型 | `internal/prompts/library/agent-sub-*.md`、`internal/runtime/sub_loop.go:48` |
| 模型档位 | 只有两档:`models.chat` 与 `models.lightweight`(轻量档空则回落主档),另有 `models.chat.fallbacks` 回退链 | `internal/runtime/model.go:54,84`、`internal/settings/settings.go:73-84` |
| 评审/验证 | `review_findings` 并行 1–3 个审查子代理再逐条验证;验证子代理输出 `VERDICT` | `internal/runtime/llm.go:311`、`agent-sub-verify.md` |
| LLM 协议 | 后端恒走 OpenAI chat 协议(`openLLMClient` 不设 `Protocol`);内核已实现 Anthropic Messages 客户端(含 `cache_control`)但**产品未接线** | `internal/runtime/llm.go:491`、`deps/agent-native/runtime/llm/anthropic.go` |
| 工具并行 | 内核支持 `ExecParallel`,直连路径未设置 → 默认**串行**执行同一回合的多个工具调用 | `deps/agent-native/runtime/loop.go:203,596`、`internal/runtime/llm_direct.go:268` |
| 执行隔离 | EXT-16:`run_shell`/`run_python` 可选 bwrap 档(断网、只读根、tmpfs 遮蔽 `/home` `/tmp`、仅会话目录可写、ulimit、超时杀命名空间);缺省 direct | `internal/tools/exec_backend.go` |
### 1.2 本机实测发现的问题
| # | 发现 | 影响 | 证据 |
|---|---|---|---|
| F1 | **子代理结论被压成 160 字**:直连路径 `delegate_task` 只把 `res.Summary` 回给父,而 `Summary` 是子代理全文的前 160 字(全文在 `res.Text` 里,被丢弃) | 子代理做完的检索/调研结论,父代理只看到开头一句;这与「上下文防火墙」的用法正好相反,也会诱发父代理凭摘要补细节 | `llm_direct.go:697-700`、`runmgr.go` finishChild(`Summary = truncate(fullText, 160)`) |
| F2 | **MiniMax 思考内容混在正文流里**:OpenAI 兼容流式接口默认把思考放进 `content` 的 `<think>` 块;后端在回合结束时才剥离 | 回合进行中前端收到的 `message.delta` 先是一大段思考原文,界面上「正文」区域先显示推理过程;思考计时也不准。官方提供 `reasoning_split=true`,实测开启后思考改走独立的 `reasoning_content`/`reasoning_details` 字段(3/3 次),TTFT 中位数 0.69s | `llm_direct.go:418-475`;probe2 实测(§7) |
| F3 | **sandbox 档下交付物生成跑不通**:python-docx/openpyxl/python-pptx 装在 `~/.local`,被 `--tmpfs /home` 遮蔽;`run_python` 描述里「缺失时 pip install --user」在断网档也失效 | RDM 计划 G3-7 切 sandbox 时,docx/xlsx/pptx 生成会直接失败;EXT-16 的「docx 生成任务成功」验收用的是 `printf` 桩,未覆盖真实库 | bench2/bench3 实测:EXT-16 同形参数下 `import docx` → ModuleNotFoundError;只读挂载依赖层后 `import docx, openpyxl, pptx` 成功 |
| F4 | **Claude 走兼容协议丢能力**:经 dmxapi/lmuai 的 OpenAI 兼容接口,4 个 Claude 型号都不返回思考字段;改走 dmxapi 的 `/v1/messages` 原生接口,第二次调用 `cache_read_input_tokens=5043`(缓存生效) | A/B 中 Claude 一侧每步按全价重算前缀、没有思考回传——47 分钟的耗时与工具失败部分可归因于此(推断,需日志确认) | anthropic_probe 实测(§7) |
| F5 | 直连路径工具串行 | 模型一次发出多个独立检索时逐个等待;4 个被测模型都能在一个回合里给出 2 个并行 tool_calls | probe 实测(§7) |
### 1.3 A/B 数据的正确读法
内部 A/B(`.task/model-ab/ab-opus.json` 对 `.task/phase05-eval/after-p5.json`,4 任务 6 回合):
MiniMax 编造数字 7、约 10 分钟、工具 97/失败 19;opus-5-5 编造 0、约 47 分钟、工具 99/失败 33。
- 样本小且相关:「0 处」的 95% 置信上界约 3/24≈12.5%(rule of three)[R39],不能宣称清零。
- 两侧都不在最佳状态:Claude 一侧走兼容协议(F4);MiniMax 一侧思考回传已实现
(`context.thinkReplay=auto`,`ctxasm.go:206`),但流式分流有 F2 问题。
- 速度:公开测速两者相近(opus-5-5 约 96 t/s [H25],M2.7-highspeed 官方约 100 TPS [H4];
本机短文本实测 48.9 对 50.7 t/s),所以 4.7 倍耗时更可能来自思考量、步数、重试与无缓存(推断)。
- Vectara 有据摘要幻觉率 M2.7 12.9%、Opus 4.6 12.2%、Sonnet 4.6 10.6% [R40]:「读懂原文」差距
不大;差距更可能出在「缺数据时去猜」(推断)。
### 1.4 其余现状(补充核实,SELF)
- 评测:`eval/live` 是 go test(env:`AGENT_EVAL_BASE` 实例地址、`AGENT_EVAL_TASKS` 过滤、
`AGENT_EVAL_TURN_TIMEOUT`),golden 任务 4 个(`tasks.json`);A/B 工具 `eval/ab.go`、`switch.go`。
- 打断/插话:有 `CancelRun`(停止按钮)与子代理中断续跑;**没有**「运行中用户输入排队、
当前工具结束后本轮送达」的 steering 队列(未找到实现)。
- 检查点:文件写入有改前快照日志(`runmgr/rewind.go` `NoteFileCheckpoint`)。
- 直连路径声明 13 个工具;提示词库 base-* 共约 6.7KB(base-deliverables 5.2KB 最大)。
## 2. 子代理分工:证据与方案
### 2.1 证据要点(外部,来源见 §8)
- **有益面**:广度优先检索(Anthropic 多智能体研究系统:主+子比单 Opus 高 90.2%,复杂查询
耗时最多降 90%,代价 token 约 15 倍 [R13]);上下文防火墙——18 个模型都随输入变长退化
[R14],子代理只回 1–2k token 摘要 [R17];fresh-context 审阅(Devin Review 均 2 bug/PR,
58% 严重 [R20])。
- **有害面**:写入耦合(并行写手风格冲突,「多代理贡献智能、写入保持单线程」是当前可行解
[R19][R20]);顺序任务 −39%~−70%、单代理基线 >45% 时加代理为负收益、无中心校验时误差
放大 17.2 倍 [R21];Claude Code 官方也建议迭代密集/共享上下文/延迟敏感时留在主会话 [R1]。
- **契约**:委派带目标/输出格式/工具面/边界/预算;回传浓缩结论 + 证据指针(文件/行),
大产物落盘只回引用 [R13][R17];限额:禁嵌套、并发 3–5、按复杂度分档 [R7][R13][R21]。
### 2.2 方案(增量,每项独立任务卡)
| # | 内容 | 验收(可判定) |
|---|---|---|
| D1 | **修 F1**:`delegate_task` 回传改为「子代理全文(上限 4k 字)+ 超长落盘 `subagent-result.txt` 只回指针 + 工件摘要行」——内核 `subagent.CapParentText` 已有此语义(backend 侧没走它) | eval/live 前后对照:父代理引用子代理结论的回合,其终稿中来自子代理的事实不再凭摘要补齐;单测覆盖超长截断 |
| D2 | **委派简报规范**:`delegate_task` 描述与 base-method 提示补「简报四要素」(目标、输出格式、工具/来源边界、完成判据),禁止把大块原文粘进 task | 提示词 diff + eval/live 计划/委派质量指标不回退 |
| D3 | **并行工具执行**:直连路径设置 `ToolExecution=parallel`(读类工具并发、写类串行的区分后续再议) | 同回合多工具调用 wall-time 下降(评测记录);事件序号仍单调 |
| D4 | **证据账本子代理**:research/explore 画像的输出格式改为「结论 + 原文引用(文件/页/行)+ source_id」,数字必须带 source_id 或 Python 计算 ID;终稿前由确定性校验拦截(接质量计划 P5 的事实一致性检查) | 编造数字在闸门处被拦且计数;子代理回传含引用率 100% |
| D5 | **角色×模型矩阵**(依赖 §3 R2):新增/调整画像的 `model:` 支持 `claude-*` 档;`writer` 保持 chat 档,新增 `composer`(终稿综合)与 `planner-complex`(复杂任务规划简报)画像走强模型档 | 画像 frontmatter 生效(SubagentSpec 解析);评测 A3/A5 组可配置 |
边界:子代理深度维持 1(现状即禁嵌套);并发上限维持产品侧 3;本方案不引入子代理间通信。
## 3. 模型分级路由:证据与方案
### 3.1 证据要点
- **整单路由不划算**:我们的 A/B 中 opus-5-5 耗时约 4.7 倍、工具失败 33 vs 19;公开测速两者
相近(§1.3)。Devin Fusion 的教训:强模型当全程主控只降本 33%,且「判断即交付物」的难题
上掉分 [R30][R31]。
- **按阶段/角色路由有正证据**:Sonnet 执行 + Opus 顾问 +2.7pp 且降本 11.9%;Haiku + Opus 顾问
在 BrowseComp 19.7%→41.2% [R32];Aider「强规划+便宜编辑」$13.29 得 64.0% 胜 o1 单跑 $186.5
得 61.7% [R12]。反例也存在(BrowseComp-Plus 上弱编排+强子代理更好 [R21])——**放哪一层必须
实测**,这正是 R3 实验的目的。
- **协议与缓存**:Claude 经 OpenAI 兼容层不回思考、不支持缓存、忽略 strict(官方文档 [H37],
本机 F4 实测缓存恢复);缓存按 tools→system→messages 前缀匹配,中途改工具集会整缓存失效
[R35][R36] → 模型切换只应发生在阶段边界,每角色固定 system/tools 前缀。
### 3.2 方案
| # | 内容 | 验收 |
|---|---|---|
| R1 | **Claude 原生协议接线**:`models.chat.protocol = openai-chat \| anthropic`(设置项),anthropic 时用内核现成的 `llm/anthropic.go` 客户端(base 指向 dmxapi `/v1/messages` 根),回传 thinking 块与 signature、挂 `cache_control` 断点、usage 记缓存读写(N3 计费拆分已有字段) | 同会话第二次调用 `cache_read_input_tokens>0`(SELF 复现 F4 的探针即验收集);thinking 块原样回传(删改会 400 [H24]) |
| R2 | **角色路由表**:设置新增 `models.<role>`(role∈composer/planner/verifier,缺省回落 chat 档);画像 frontmatter `model: <role或具体型号>`。默认建议:chat=MiniMax-M2.7-highspeed(不变)、composer=claude-sonnet-5(dmxapi,原生协议)、verifier=异模型(deepseek-v4-flash 或 claude)、复杂任务 planner=claude。Opus 系列留给最难任务手动指定 | 角色解析链单测;`models` 列表来自各端点 `/v1/models`(已核实 dmxapi 有 sonnet-4-6/sonnet-5/opus-4-6/opus-5-5 等,见任务卡 evidence) |
| R3 | **路由 A/B 实验**(扩展现有 eval/ab.go):组别 A0 全 MiniMax / A2 MiniMax+数字闸门 / A3 A2+Claude 终稿 / A4 A2+Claude 核查 / A5 Claude 规划+终稿+核查、MiniMax 执行;关键组加 Sonnet 变体。指标:无来源数字占比、含编造交付物比例、pass^3、p50/p95 耗时、分角色成本(含缓存)、工具失败分类。样本:30–50 任务×3 次(宣称编造率<5% 需 ≥60 份零编造样本 [R39]);<3pp 差异慎下结论 [R49] | 选型报告入任务卡,来源 GATE/SELF 标注 |
| R4 | **升级规则进 harness**(不依赖模型自觉 [R20]):连续 N 次工具失败、闸门拦截无来源数字、检索「未找到」三类事件触发 advisor 咨询或角色升级 | 评测中升级触发可观测;误升级率记录 |
运维事实(2026-10-10,SELF):lmuai 月额度已耗尽($1303.32/$1300,2026-11-05 重置)——R1/R3
的 Claude 侧建议先走 dmxapi(余额 ¥0.48,**需充值**,此前 A/B 卡估算全量对照 ¥50–100)。
## 4. 任务沙箱:记录与规划(**不立即实现**)
### 4.1 对原始思路的三处修正
1. **「overlay 隔离他人变更」不成立**:内核文档明确「下层在挂载期间被修改的行为是未定义的」
[S1];本机实测运行中的沙箱能看到下层后续修改(bench2 第 5 段)。**一致视图必须来自不可变
基底**(冻结副本或 git commit 物化),而不是叠在活动目录上的 overlay。
2. **快照只是把冲突推迟到合并**:Codex cloud/container-use/Cursor 都以 diff/PR 回收,冲突在
写回时用基线校验暴露 [S23][S28][S26]。「互不影响」的成本是写回时的三方合并与人工兜底,
设计里必须显式包含这一步,否则快照只是把失败挪到了最后。
3. **「立即销毁」与审计有张力**:销毁的应是计算资源与可写层;转录、diff、工件哈希、环境
清单要按 TTL 封存(Codex 删前存快照 [S23]、container-use 留命令史 [S28]、Cursor 留工件
[S26])。本仓的证据门禁(AGENTS.md)同样要求可复核输出——封存记录是硬约束。
另一处简化:硬链接克隆(cp -al)对「原子替换写入」是安全的(rename 换 inode),但对原地
写入会穿透(共享 inode)——本机实测(bench3 第 3 段)。只可作为「可检测」方案并配
sha256/mtime 清单复核,不可当作完整快照。
### 4.2 目标形态(任务工作区沙箱)
一次任务 = 冻结基底(会话/项目材料的不可变视图)+ 私有可写层 + 确定性依赖层 + 出口管控 +
回收(diff 与工件清单)+ 封存后销毁。智能体在其中任意折腾不破坏原始资料;产出经校验写回。
### 4.3 分层架构与延迟预算(本机实测,SELF)
| 层 | 机制 | 启动 | 适用 | 备注 |
|---|---|---|---|---|
| L0 进程沙箱 | bwrap(EXT-16 现状)+ 依赖层只读挂载 | **p50 7.3ms**(/bin/true,n=30);带 overlay 同为 ~7ms | 默认:解释器执行、交付物生成 | 修 F3 后 python-docx 全链路可用(import 60ms、1 页 docx 76ms) |
| L0.5 工作区沙箱 | L0 + `--overlay-src <冻结基底> --overlay <宿主upper>` | ~7ms(实测) | **多任务并发、需要一致基底与可回收 diff 时** | upper 即增量;快照语义来自冻结基底而非 overlay |
| L1 容器 | docker(overlayfs 驱动) | `run --rm` p50 142ms(redis:7 true,n=10) | 依赖隔离更强、镜像化环境 | 可加 warm pool 压冷启动;单机自托管无障碍 |
| L2 microVM | Firecracker/gVisor | 未实测;E2B 等托管方当前文档只称 "fast Linux VM"(量化数字已不可得,**未经证实**) | 不可信代码、最强隔离 | 本机有 /dev/kvm;引入与维护成本高,暂缓 |
支撑件(与层正交):
- **冻结基底**:git 材料以 commit SHA 物化(同 SHA 只物化一次、多任务只读共享);非 git 材料
用 cp -al + sha256 清单(写回前复核,变了即判基底失效)。git worktree add 实测 192 文件
11ms,overlay 直接盖工作树 ~10ms,两者都够快。
- **依赖层**:项目 venv / site-packages 只读 bind(实测修复 F3;RDM 方案 §3.4 原有此意)。
- **数据库**:SQLite 用 `VACUUM INTO` 取一致快照 [S32];PG 用零连接模板库克隆(PG18 XFS 上
有 CLONE,ext4 上是复制 [S11][S37]——量级以库大小为准,必要时评估独立 XFS 卷给 reflink)。
- **网络**:默认无网(现状);将来要放开时,按 sandbox-runtime 的形态做出口代理白名单 +
代理侧凭据注入(密钥不进沙箱)[S-RT]。
- **回收与写回**:沙箱退出后读 upper → 生成 `git diff --binary` 补丁 + 工件 sha256 清单;
写回用 CAS(目标当前哈希==基底哈希 → 原子替换;不等 → `git merge-file` 三方合并,冲突停给
人);写回前留前像。git 目标用 `update-ref <ref> <new> <old>`(本身就是 CAS)[S46]。
- **封存**:base SHA、补丁、工件哈希、转录指针、环境清单(依赖层版本)、退出码,按 TTL 留存
后销毁工作区目录。
### 4.4 与现网的关系
- EXT-16 sandbox 档是**进程级**隔离(单次命令);本节是**任务级工作区**,两者叠加而非替代。
首个落地形态:ExecSpec 增加工作区概念,sandbox 档把「会话目录 bind」换成「冻结基底 overlay
+ 私有 upper」。
- 已知缺口顺带记录:小队内核 ExecConfig、工作流 ScriptCommand 仍 direct(EXT-16 卡内遗留);
沙箱档覆盖它们是前置条件之一。
### 4.5 非目标与开放问题
- 不做多租户硬隔离与 OS 级安全声明(沿用质量计划 §5 边界)。
- 开放:是否划独立 XFS 卷换 reflink;gVisor 试用;warm pool 是否值得(L0 已 7ms,大概率不值);
Windows/macOS 不在范围。
## 5. 分期与验收总表
| 增量 | 内容 | 依赖 | 备注 |
|---|---|---|---|
| E1(P0 快修)✅ | F1 委派回传、F2 reasoning_split、F5 并行工具、F3 依赖层 | 无 | **已完成(2026-10-10)**:Agent-Native #42/#43/#44 + Backend #127 + Dev PR(任务卡 feature/agent-e1-parallel-fixes)。验证:F2 实测正文 0 泄漏、F3 sandbox 实测 IMPORTS-OK、F5 实测同回合并发重叠;eval 对照工具失败 19→11,未核实数字 7→12(E3 待做,见任务卡) |
| E2 | R1 Claude 原生协议 + 缓存观测 | E1(F2 同类协议改动可同批) | dmxapi 需充值 |
| E3 ✅ | D4 证据账本 + 数字闸门 | 无(接质量计划 P5) | **已完成(2026-10-10)**:Backend #130、Dev #311(任务卡 feature/agent-e3-evidence-gate)。标注感知豁免(分句判定)+ 两轮修正(变化才二拦)+ base.deliverables v6 数字溯源规则 + 子代理引用格式;eval 对照未核实数字 12→5(未标注 3)、工具调用 93→63 |
| E4 ✅(R4+账本) | R2 角色路由 + D5 画像 | E2 | **R4 与账本已完成(2026-10-11,MiniMax 版)**:Backend #131–#134、Dev #315(任务卡 feature/agent-e4-escalation-ledger)——滑窗失败提醒(端到端日志实证)、检索空命中提醒、source_id 账本(83 标记);Claude 角色档按模型指示暂缓;eval 四轮对照无恶化 |
| E5 ✅(R3 部分) | R3+R4 路由 A/B 与升级规则 | E2–E4 | **R3 已完成(2026-10-10,MiniMax 家族版)**:Dev #313(任务卡 feature/agent-e5-model-ab)三臂对照(hs / 全M3 / hs+M3轻量)——建议默认 chat=MiniMax-M3(未标注编造 1、失败最少、时长持平、单价减半);R4 升级规则仍待做 |
| S0-1 ✅ | §4.4 首个落地形态:冻结基底 overlay + CAS 回收 + 变更摘要(--exec-workspace overlay) | 用户 2026-10-11「继续完成下一步」 | **已完成(2026-10-11)**:Backend #135/#136、Dev #318(任务卡 feature/agent-s0-workspace-overlay)——bwrap 集成 3 + live 端到端(失败零落地/新增/修改/-ws 清理);S0-2(fs 联合读/任务级工作区/封存)待授权 |
## 6. 与既有规划的关系
- [智能体工作流质量改进](2026-10-09-agent-quality-improvement-plan.md):本文是其「模型 A/B」
结论的后续与 P4/P5 的延伸(D4 与 P5 合流;E5 继承 A/B 方法论并扩大样本)。
- [EXT 申请包 G1](2026-10-09-ext-g1-b1-b3-exec-backend.md):E1-F3 修复其 sandbox 档的交付物
缺口;§4 工作区沙箱是 EXT-16 的演进方向。
- [RDM 阶段总案](2026-10-07-rdm-phase-plan.md):G3-7 切 sandbox 前置依赖 F3 修复。
- Agent 栈 N2 WP5(子代理/后台派生):D1–D5 在产品层消费其内核端口,不改内核契约。
## 7. 本机实测的复现要点(SELF,脚本存于任务卡 evidence 同目录说明)
- 启动延迟:bwrap 命名空间 / +overlay / +持久 upper 各 30 次(bench.sh、bench2.sh §3)。
- F2:`reasoning_split=true` 前后各 3 次流式(probe2.py,观察 delta 字段分布)。
- F3:EXT-16 同形参数下 `import docx` 失败 vs 只读挂载 `~/.local/.../site-packages` 后成功
(bench2 §1–2、bench3 §1–2)。
- F4:dmxapi `/v1/messages` 连续两次调用,第二次 `cache_read_input_tokens=5043`。
- overlay 非快照:运行中沙箱读到下层并发修改(bench2 §5);cp -al 对 rename 安全、对原地写
穿透(bench3 §3)。
- docker 冷启动 10 次(bench.sh)。
## 8. 来源(除标注 SELF 外均为 2026-10-10 抓取的一手页面)
- [S1] Linux 内核 overlayfs 文档:https://docs.kernel.org/filesystems/overlayfs.html
- [S11] BoringSQL instant database clones:https://boringsql.com/posts/instant-database-clones/
- [S23] Codex environments/git-worktrees:https://learn.chatgpt.com/docs/environments/git-worktrees
- [S26] Cursor cloud agent:https://cursor.com/docs/cloud-agent
- [S28] container-use CLI:https://container-use.com/cli-reference.md
- [S32] SQLite VACUUM INTO:https://www.sqlite.org/lang_vacuum.html
- [S37] PostgreSQL 18 release notes:https://www.postgresql.org/docs/release/18.0/
- [S46] git-update-ref:https://git-scm.com/docs/git-update-ref
- [S-RT] Anthropic sandbox-runtime(Linux=bwrap+seccomp、网络默认全拒+代理白名单+凭据注入、
Apache-2.0):https://github.com/anthropics/sandbox-runtime
- [S-CX] Codex sandboxing(Linux 用 bwrap;read-only/workspace-write/danger-full-access):
https://learn.chatgpt.com/docs/sandboxing
- [H4] MiniMax 定价与速度:https://platform.minimax.io/docs/pricing/overview 、
https://platform.minimax.io/docs/guides/text-generation
- [H24] Claude thinking 块回传要求:https://platform.claude.com/docs/en/build-with-claude/extended-thinking
- [H25] Artificial Analysis(opus-5-5 96.4 t/s 等):https://artificialanalysis.ai/models/claude-opus-5-5
- [H37] Claude OpenAI SDK 兼容层限制:https://platform.claude.com/docs/en/api/openai-sdk
- [R1][R12][R13][R14][R17][R19][R20][R21][R30][R31][R32][R35][R36][R39][R40][R49] 子代理与
路由调研来源清单见任务卡「调研来源」节(Claude Code docs、Anthropic/Cognition 工程博客、
arXiv 2512.08296 等,URL 全量随卡保存)。
+4
View File
@@ -74,6 +74,10 @@ Dev 链接均指向对应任务 PR,可从其任务卡继续追溯组件 PR;
| [N2 实施案](2026-10-07-agent-stack-n2-plan.md) | 栈总案 N2 的六 WP:上下文、协议、工具、skills、子代理、装配 | 未单列确认状态及 owner;正文称 N2 开工 | Documents [#42](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/42) 已合入;Dev [#244](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/244) 已合入(merge `7e3ba10`),闭卡 [#247](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/247)。卡内自述六 WP 落地;本索引未重放 |
| [N3 实施案](2026-10-07-agent-stack-n3-plan.md) | 栈总案 N3:持久与可观测 | 页首未单列确认状态及 owner;正文称 N3 开工 | Documents [#43](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/43) 已合入;Dev [#248](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/248) 已合入(merge `2836a87`),闭卡 [#249](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/249)。卡内自述六 WP 落地;本索引未重放 |
| [Q2/Q3 实施案](2026-10-07-agent-stack-q2q3-plans.md) | 栈总案 Q2 拓扑与 Q3 收敛互通 | 页首未单列确认状态及 owner | Documents [#44](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/44) 已合入;Dev [#250](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/250) 采纳方案,[#251](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/251)(merge `452c00a`)与 [#253](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Dev/pulls/253)(merge `c8ce4eb`)已合入。卡内自述 Q2/Q3 落地;本索引未重放 |
| [智能体工作流质量改进](2026-10-09-agent-quality-improvement-plan.md) | 直连主路径质量:诊断→六项裁定→P0–P5 分期 + 模型 A/B;推翻 fs 工具默认关闭裁定 | 已获实施授权(2026-10-09 六项裁定);首个增量 feature/agent-quality-phase01 | 随本提案 PR;诊断 SELF(真实运行转录);基线报告见任务卡 |
| [EXT 申请包 C1–C7](2026-10-08-ext-c1-c7-rdm-shared-contracts.md) | RDM 多人共享契约的基座最小扩展申请(EXT-6…EXT-12):身份停用/受管配置/授权适配器/索引发布/分发守卫/Host 工厂/投影过滤 | proposed;需求依据=RDM U0 主记录(D1–D9 裁定,2026-10-08 合入) | 随本提案 PR;每条现状证据为 SELF·源码级(Dev 34a2bbe/backend fe7c245),运行态 NOT_RUN;受理后逐条另立实现任务 |
| [EXT 申请包 G1](2026-10-09-ext-g1-b1-b3-exec-backend.md) | EXT-13…16:回合内共享检索、命令即工具、项目列表共享、执行后端接口 | proposed;需求依据=RDM 方案 V1.1 §3.3/§3.4/§5.3(2026-10-09 批复) | Documents [#52](https://git-home.u1680832.nyat.app:30319/weichen/Agent-System-Documents/pulls/52) 已合入;EXT-16 已实施(Dev #285,见其任务卡),其余受理评审待定。本行由本次索引维护补充 |
| [子代理分工、模型分级路由与任务沙箱](2026-10-10-agent-delegation-routing-sandbox.md) | 方向主记录:委派契约与角色路由方案(E1–E5 增量)+ 任务工作区沙箱设计(仅记录不实施);修正 overlay≠快照等三处假设 | proposed(2026-10-10);E1、E3、E4(R4+账本)、E5(R3)、S0-1 已完成(E4:Dev #315;S0-1:Backend #135/#136、Dev #318,2026-10-11);E2 暂缓(模型指示)、S0-2 待授权 | 随本提案 PR;现状核查与启动延迟为 SELF(任务卡 evidence);外部来源 URL 全量随任务卡 |
原查询的 19 份原文中,14 份显式标注 owner 为 weichen。双档存储、启动配置面、跨会话读取、文件预览和
N2 实施案这五份未单列 owner,其中预览案仅写“作者:weichen + Agent”。同步新增的 N3 与 Q2/Q3 案页首也未单列 owner。
@@ -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 升钉完成后另行评估)。