muse-agent-example/.agent/docs/architecture/domains/06-质量与复利领域.md

质量与复利领域 SoT

数据权威已改订为 PostgreSQL：正式内容（Canonical）都在库里，待审候选（Shadow）也在库里，raw 进库可看全文，只读看板只查库渲染绝不写。本文档不再描述任何“作品内文件目录”作为质量证据的家。落库的横切合同见索引 §3，本文只引用、不重复定义。

1. 唯一职责

质量与复利领域拥有候选检查、语义审核、评分策略、失败终态合同和经验升格规则。它回答“候选有什么问题、是否可以交给用户裁决、某种写法是否稳定有效、哪些经验值得进入范式、Agent、Skill 或工具”。

本领域产出检查、审核、实验和升格结论，并把结论落库；它不拥有正文、实体事实、范式正文、模型运行底座，也不拥有用户的接受动作。一切检查输入与质量产出都必须落库可见，没落库的等于系统视角里不存在。

2. 四层质量链

机械正确性
  -> 语义正确性
  -> 创作质量
  -> 长期效果与复利

1. 机械检查：schema、字数合同、hash、引用、状态机、预算账本、确定性规则。
2. 语义检测：实体、关系、细纲硬约束、知情范围、时间线和来源支持。
3. 创作评审：通用底层指标 + 场景类型评分；指出具体可修问题。
4. 长期验证：跨章、跨场景或跨作品复核，结合用户决策和合法外部反馈判断方法是否有效。

机械失败不可被 Agent 主观覆判：机械层不过就是不过，语义和创作评审再高也不能把它盖过去。语义和创作评审也不能替代机械检查。

3. 评分结构

评分采用两层结构：

• 通用底层指标（四个通用维度）：设定与实体保真、规划忠实、文风一致、可读性。这些跨章节可比较。
• 场景类型策略（五类场景）：战斗、人物对话、转折、信息揭示、老角色回归，各有自己的重点、权重和锚点。

每章不能自创完全不同的量表，否则失去跨章比较；也不能用一套固定权重覆盖所有场景。量表、场景策略和阈值必须版本化——改了评分口径，要能读出“这次用的是哪一版量表”。

现有实现承认（各一句，不展开）：六类混淆项报告与新角色比例分层裁决由 optimize-content-quality 质量收敛环承载；卡三角色审核与金标准校准由 review-knowledge-cards 承载；AI 味案例的来源哈希、Shadow 捕获、来源重验证和反例前置门由 capture-ai-flavor-cases 承载。

4. 失败分类

安全报告至少区分五类（这是合同）：

• execution_invalid：调用、schema、hash、raw、预算、运行状态或适配器失败，无法形成质量结论。
• quality_failed：执行有效，但候选存在明确质量问题或硬约束残留。
• insufficient_evidence：样本或场景不足，不能形成方向结论。
• no_gain：执行有效且质量合格，但新策略没有证明增益。
• passed：满足对应质量或实验合同。

实现现状标注（诚实保留，不强改）：当前以四类终态承载——passed / failed / insufficient_evidence / no_gain，失败原因靠原因码表达。合同里的 execution_invalid 与 quality_failed 在实现中合并落 failed，靠原因码区分；这两类从合同五类到实现四类的精确映射待对齐。

运行器失败可以使 Gate 失败关闭，但报告必须保留失败类别与原因码，不能让用户把基础设施故障误解为正文不合格。

5. 库内证据

审核、实验、运行证据一律落库，并绑定它所评价的正文或候选哈希：

• 审核记录（reviews）：候选与章节的质量摘要、问题、修复与复验结论，落库并绑候选哈希。
• 实验记录（experiments）：baseline、假设、干预、预期、到期与结论，落库并绑被验证的正文或候选哈希。
• 运行回执（runs）：安全执行回执、预算账本与 raw 指针，落库；完整 Prompt/Response、供应商原始响应等 raw 进单独表、可看全文（访问控制见索引 §8）。
• 用户决策与正式状态：接受、合并、丢弃及其依据，落库。

正文发生变化后，旧审核不能继续作为接受依据——哈希一变，挂在旧哈希上的审核自动失效。

实现现状标注（诚实保留）：生产链审核证据已落库并绑候选哈希——机械门与语义检测结果随 persist_writer_execution 落 example_quality_result（candidate_sha256 绑定），语义状态另固化到候选行作为接受通道的 DB 兜底。回放评测链的审核报告仍散在 docs/ 的带日期报告里、不绑哈希，迁库待建。

6. 经验升格

经验升格的规则由本领域独家拥有。范式领域和 Agent 与 Skill 领域只描述各自在这条链上的那一段，并链接回这里。

单次观察
  -> 作品 review/experiment（落库证据）
  -> 重复出现的 lesson/win
  -> 范式 draft/evaluating
  -> active 范式
  -> 稳定 Skill / Tool / Agent 规则

这是本领域的设计目标合同。现状：承接物骨架已建——example_lesson 登记表（lesson_registry）承载 lesson/win 证据（绑 run_id 与候选哈希），状态机 proposed → reviewing → promoted/rejected 由 DB 触发器强制：跳过评审的自动升格被拒，promoted 必须指明目标类型（pattern/skill/tool）与落点，终态不可再流转。仍未建：证据的自动收集（当前靠人/agent 登记）、升格到范式卡与 Skill 合同的具体变更动作（promoted 之后的落地由各 owner 领域承接）。

AI 味案例是“单次观察”的一种证据载体：既有作品反向扫描和创作反馈都先自动落库为 shadow，不直接进入范式或生产规则。确认、样例投影和规则消费前必须重验来源哈希与位置锚点；哈希变化、来源不可得或锚点不一致时保留历史证据但 fail-closed。shadow 只在本卡/本作品作用域内作为待复核提示；只有跨作品重复、同时有“应修”和“不应修/边界/回归”证据，并完成回放与独立评审，才允许生成规则候选；规则候选仍不是 active。canonical 也不等于规则生效，rejected/archived 只保留审计。

与 02 的同名区分：本节“升格”指经验沿上面这条链从一次观察长成可复用的范式/Skill/Tool。02-实体领域 里的“作品面实体入库（也叫升格）”指拆书抽出的实体进入某部作品的正式事实库。两者只是都叫“升格”，对象、链路与 owner 都不同，引用时注意区分。

升格原则：

• 同类问题第 3 次复发，停止逐次修补，评估是否固化为检查项或 Skill。
• 单作品证据默认只能产生作品级范式。
• 跨作品规则变更必须做影响复核。
• 每项优化必须写明可证伪假设、观察窗口和替代解释。
• 可机械判断的经验优先固化为工具，不长期堆进 Prompt。
• 已被 Skill/Tool 完整拥有的执行步骤，范式和 lessons 只保留原理、证据与链接。

7. Gate A/B 边界

• Gate A 只验证离线评测链可运行，不能宣布正文层通过。
• Gate B 才对跨作品样本做正文能力和策略增益裁决。
• Gate A/B 是开发验收，不是正常用户写一章的线上质量流程。
• 离线 raw、标准答案和候选进库（单独表 + 访问控制），不要求留仓外。
• COMPLETED 判据（轮次封存）：一轮评测完成，必须核对“本轮声明要产出的 raw 集合”与“实际落库集合”一致才置完成；“有行落库了”不是判据——一道不可能失败的门不是门。
• 代价明账：评测证据与生产共享同一数据库信任根，是单用户场景的刻意取舍——换可观测性与防篡改，放弃证据底座独立性 / 外部可审计性。这是明账，不是纯收益。
• 常设不变量（从预防迁到发现）：没有评测质量结果出现在任何生产视图、没有正式正文来源能追溯到评测候选——持续跑、违反即报警。（harness 改造原则，见 docs/2026-08-01-评测harness改造设计）

现有实现承认（各一句，不展开）：预算账本合同与运行探针锁定由 access-database 与 record-run-evidence 承载，Gate B 通过回执的哈希链由 decide-candidate 承载。

实现现状标注（诚实保留）：当前只有一个作品且评测样本已预注册，Gate B 因此恒判 insufficient_evidence（跨作品样本不足）——这是目标态下的正确行为，不是 bug。

8. 可恢复性

可恢复性不在本领域定义，见 08-数据权威与可视化领域：质量证据与运行回执既然全部落库，可恢复性就跟随数据库备份、快照或可重建脚本，加上 Git 里的代码与 DDL 从零重建库结构。本领域不再单独主张“本地完备”。

9. 待建

• 经验升格链后半段：example_lesson 登记与状态机已建（见 §6），promoted 之后到范式卡/Skill 合同的具体变更动作、证据自动收集未建。
• 评测链审核证据落库绑哈希：生产链审核证据（机械门 + 语义报告）已随 example_quality_result 绑候选哈希落库；回放评测的审核报告仍在 docs/ 日期报告里，迁库绑哈希待建。
• eval 收敛环脚本：把评分、失败分类与升格触发串成可机械复跑的闭环。

10. 验收条件

1. 机械失败、运行失败和内容质量失败可以由原因码明确区分，脚本能从报告里读出类别。
2. 修改后的候选一定重新检查并绑定新 hash；旧 hash 上的审核对当前正文不再有效。AI 味案例在确认、样例投影或规则消费前必须有 verified 重验证回执。
3. 每个 active 范式或稳定规则都有可追溯到库内记录（含哈希）的证据。
4. 同一章用两套不同场景策略打分时，通用底层指标的分差能被脚本读出并比较；场景策略只改场景权重，不改四个通用维度的定义。
5. 任一审核、实验或运行回执，都能用库内一条记录定位到它所评价的正文或候选哈希。

11. 关联 SoT

• 数据权威、落库合同、raw 边界与可恢复性：索引 §2/§3/§4/§8，细则见 08-数据权威与可视化领域
• 范式生命周期：03-范式领域
• 实体入库“升格”（与本文经验升格不同义）：02-实体领域
• Agent/Skill 升格：07-Agent与Skill领域
• 离线 Gate 上级合同：专题-04