weichen
238f90e92a
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.
6.8 KiB
6.8 KiB
智能体工作流质量改进：诊断、裁定与分期计划
状态：已获实施授权（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 相比，本系统直连对话路径在 「工作细致、详细、完善」上存在可测差距。真实转录中定位到的失败链（均已复核）：
- 信息逐轮衰减：跨轮上下文由界面消息有损重建——工具结果只回放 160 字 摘要、参数截断、二进制原件占位、思考内容丢弃；上传材料只在「本轮」注入。 后续轮次在摘要的摘要上工作，细节靠编造补齐（实测：「详细方案」中 85%/95% 准确率、8000–10000 字等数字在原始转录中不存在；日期星期错配）。
- 修改模型倒挂：交付物由一次性整段生成脚本产出（docx 无源文件），任何 修改=整篇重写重跑（实测一轮 24 次工具调用 9 次失败、6KB 脚本重跑 8 次）。
- 检查失效且误报：终轮评分的 lint 子进程无 PYTHONPATH 而静默失败（同一
docx 带 PYTHONPATH 9 个 error，评分器里 0 个）；终轮检查重评已被替代的旧
工件导致死循环；可读性规则把表格单元格「项目概述撰写」判成栏目式标题；
历史工件渲染格式
[产出工件 …]与伪造标记检查同形，模型照抄即被拦。 - 最终答复与事实脱节：composeFinal 只见 160 字摘要，产出了不存在的章节 列表和「我会调整后再提交」类未兑现承诺。
- 过程性根因：无任务级评测。任务卡验证=单测+mock，真实模型被列为非目标； evalgold 只有 1 条规则，eval/ab.go 无运行记录。
2. 根因归纳（按影响排序）
- 上下文保真度不足（影响最大）——产品没有把内核的追加式会话记录当权威上下文。
- 工具与修改流程不适合交付物领域——没有「读源码→精确改→编译→看诊断」的对应物。
- 质量控制是事后把关而非让模型自己做好，且把关本身不可靠。
- 行为指引薄弱（何时建计划/失败换路/坚持到完成），工具描述只有一行。
- 没有以真实模型结果为准的评测回路。
内核能力（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 层面的仓库治理变更。