Compare commits
4
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 weichen
|
238f90e92a | ||
|
weichen
|
d3c9b4554e | ||
|
weichen
|
176db44c4b | ||
|
weichen
|
69360de5bb |
@@ -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,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 推翻，以本文为准）。
|
||||
@@ -74,6 +74,7 @@ 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；受理后逐条另立实现任务 |
|
||||
|
||||
原查询的 19 份原文中，14 份显式标注 owner 为 weichen。双档存储、启动配置面、跨会话读取、文件预览和
|
||||
|
||||
@@ -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