From ffa5266a034f6509accc5dddb2f262404e3d075c Mon Sep 17 00:00:00 2001 From: zizi Date: Wed, 22 Jul 2026 15:28:04 +0800 Subject: [PATCH] =?UTF-8?q?=E8=AE=BE=E8=AE=A1:=20=E5=B0=81=E9=97=AD?= =?UTF-8?q?=E6=AD=A3=E6=96=87=E6=99=BA=E8=83=BD=E4=BD=93=E7=A6=BB=E7=BA=BF?= =?UTF-8?q?=E8=AF=84=E6=B5=8B=E6=89=A7=E8=A1=8C=E5=90=88=E5=90=8C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/2026-07-20-正文智能体正式优化架构.html | 56 +++- ...2026-07-20-正文智能体正式优化设计与计划.md | 266 ++++++++++++++---- 2 files changed, 255 insertions(+), 67 deletions(-) diff --git a/docs/2026-07-20-正文智能体正式优化架构.html b/docs/2026-07-20-正文智能体正式优化架构.html index 8533ccd..1588165 100644 --- a/docs/2026-07-20-正文智能体正式优化架构.html +++ b/docs/2026-07-20-正文智能体正式优化架构.html @@ -40,19 +40,30 @@ .loop { padding: 14px 16px; border-left: 4px solid #687d8a; background: white; } .loop b { display: block; margin-bottom: 6px; } .loop p { margin: 0; color: var(--muted); font-size: 13px; line-height: 1.55; } - .eval { display: grid; grid-template-columns: 1fr 1fr 1fr 1.2fr 1fr; gap: 12px; } + .eval { display: grid; grid-template-columns: repeat(6, 1fr); gap: 12px; } + .runtime { display: grid; grid-template-columns: 1fr 1.35fr 1fr; gap: 14px; align-items: stretch; } + .runtime-group { display: grid; gap: 10px; } + .runtime > .node, .runtime-group .node { min-height: 0; } + .runtime > .node::after, .runtime-group .node::after { display: none; } + .orchestrator { background: var(--cyan); border-width: 2px; } + .vault { background: var(--amber); } + .closed { background: var(--red); } + .contract { display: grid; grid-template-columns: repeat(3, 1fr); gap: 14px; margin-top: 14px; } + .contract article { padding: 15px; border: 1px solid var(--line); border-radius: 8px; background: white; } + .contract h3 { margin: 0 0 7px; font-size: 15px; } + .contract p { margin: 0; color: var(--muted); font-size: 13px; line-height: 1.55; } .evidence, .orders { display: grid; grid-template-columns: 1fr 1fr; gap: 14px; } .evidence article, .orders article { padding: 16px; border: 1px solid var(--line); border-radius: 8px; background: white; } .evidence h3, .orders h3 { margin: 0 0 7px; font-size: 15px; } .evidence p, .orders p { margin: 0; color: var(--muted); font-size: 13px; line-height: 1.55; } - @media (max-width: 980px) { .lane, .eval { grid-template-columns: 1fr 1fr; } .node::after { display: none; } .loops, .evidence, .orders { grid-template-columns: 1fr; } } - @media (max-width: 540px) { .lane, .eval { grid-template-columns: 1fr; } } + @media (max-width: 980px) { .lane, .eval, .runtime { grid-template-columns: 1fr 1fr; } .node::after { display: none; } .loops, .contract, .evidence, .orders { grid-template-columns: 1fr; } } + @media (max-width: 540px) { .lane, .eval, .runtime { grid-template-columns: 1fr; } }

正文智能体正式优化架构

-

卡负责定位，原文负责表现，正式设定负责事实，writer 只负责创作。生产链与离线评测链严格分离。

+

卡只负责定位原文，writer 不读取卡语义。Gate A 尚未 real-run；Gate B 通过前只实现离线评测闭环。

两个方向不能混用

@@ -63,14 +74,14 @@
-

生产链

+

产品化生产链（Gate B 通过后）

1. 已确认细纲硬事件、可调节拍、伏笔、钩子和新设定声明。
2. 检索规划与卡索引按 asOf 重建当前态，带出历史来源指针。
3. 连续四章 + 原文回读事实证据与表现证据分开装配，生成确定性 manifest。
4. 无工具 Writer只接收 WriterContext；可按预算请求补证。
5. Detector 硬门核细纲、事实、证据、时间线和输出合同，最多返修两轮。
-
6. Shadow 与用户三决策原样接受先做 accept_preflight；修改后合并生成新版本 → detector → 返回 Shadow → accept_preflight；通过后 confirm。
+
6. Shadow 与用户三决策第二阶段才实现。通过 accept_preflight 后 confirm，不属于 Gate A/B 前置范围。
补证环

Writer 可返回结构化 evidenceRequests；最多 3 次，累计新增上下文不超过检索预算 30%。

@@ -90,11 +101,34 @@

离线评测链

-
A/B/C 三臂原文线、卡线、双线；A/B 只作诊断，不能被接受。
-
统一 Detector授权、冻结、泄漏和候选结构门保持一致。
-
双独立盲评臂名掩码，第二评委反序，评分步长 0.5。
-
稳定性 / 第三评委同维差值超过 0.5 时最多增加一次第三评委。
-
Gate A / Gate BGate A：不足5章=insufficient；任一 schema/泄漏/系统/硬门失败=failed；其余 passed。Gate B：不足2书10章或不稳定>20%=insufficient；硬错或文风/张力退化=failed；保真均值≥+0.25且60%样本正增益=passed；其余 no_gain。仅 passed 解锁细纲。
+
A/C 核心比较 + B 负对照A=通用原文检索；C=卡索引后回读原文；同字符预算。B=card-only，仅诊断。全评测集统一分配顺序并平衡位置。
+
隔离 WriterA/C 只看到统一事实约束和选中原文，看不到卡、检索策略或轨迹。完整上下文只允许原文与派生 hash 不同。
+
统一 Detector严格真实报告逐项计算高严重度与硬约束覆盖率，禁止常量。
+
Oracle 盲评五维评分之外，逐 assertionId/constraintId 输出 pass/fail/unknown verdict；绑定 candidate hash 与受控证据，unknown 或 ID 不全即失败。
+
唯一 GateInputBuilder只比较 detector/judge 同类同 ID verdict，禁止用分数推 verdict；只从 manifest、receipts 和严格报告生成 gate-input.json。
+
Gate A / Gate B系统/schema/hash/泄漏/judge 异常先判 failed；只有预注册集合自身不足才是 insufficient。B 不进 Gate B 阈值，按新角色比例分层报告。
+
+
+ +
+

agent-example 离线评测 adapter

+
+
可信编排器唯一持有授权、臂映射、顺序表、oracle 和预算。直连固定 Claude CLI 是离线例外，不写 New-API 共享账本，也不是产品运行时方案。
+
+
隔离模型进程绝对 CLI 路径 + sha256 + 2.1.211 + 完整 model ID；stdin-only、fresh process、无工具/会话/hooks/plugins/MCP。
+
隔离 Semantic Detector 进程候选与硬约束 → 严格语义报告。报告绑定 candidate hash，指标由逐项结果计算。
+
sandbox-exec 边界cwd/HOME/TMPDIR 位于隔离目录；目录外文件读写拒绝，仅允许模型调用所需网络，环境字段白名单。
+
+
+
vault lease → /private/tmp用户/创始人批准；先写非敏感 lease，再写 0700/0600 raw。恢复扫描 lease 清孤儿，防 symlink/path escape。
+
gate-report → passed receiptwriter_gate.py 是唯一签发者；同一文件 CAS journal 中先落报告，只有 passed 才签 receipt，细纲入口验完整 hash 链。
+
任一异常失败关闭timeout、nonzero、schema、budget、model mismatch、invalid judge、unstable judge 都使样本 ok=false，禁止换模或跳臂。
+
+
+
+

固定调用面

print、bare、完整 model ID、effort、预算、deadline、JSON schema、无工具/会话，空 MCP 固定为 {"mcpServers":{}}。temperature/topP/seed 不作支持声明。

+

联合成功判定

exit=0、is_error=false、正常 terminal reason、完整 model 匹配、usage 可核账且 structured_output 合法才成功；result 不作业务 fallback。仍需一次成功探测。

+

两阶段硬边界

第一阶段实现 receipt 签发器与细纲入口守卫；第二阶段才用已验签 receipt 启动细纲 real-run。拒绝自算 JSON，dry-run 豁免。

diff --git a/docs/2026-07-20-正文智能体正式优化设计与计划.md b/docs/2026-07-20-正文智能体正式优化设计与计划.md index f583136..e913018 100644 --- a/docs/2026-07-20-正文智能体正式优化设计与计划.md +++ b/docs/2026-07-20-正文智能体正式优化设计与计划.md @@ -1,8 +1,8 @@ # 正文智能体正式优化设计与计划 -> 状态：评审修订版 +> 状态：评审修订版；Gate A 尚未 real-run > 日期：2026-07-20 -> 定位：本文是实验台“正文智能体正式优化”的任务 SoT；稳定概念仍以父仓 `design-docs/` 为准。评审通过后必须回填架构-04、专题-01/03/04/05/06/07、相关 API 契约、schema 和索引，本文完成蒸馏后删除。 +> 定位：本文是实验台“正文智能体正式优化”的任务 SoT；稳定概念仍以父仓 `design-docs/` 为准。Gate B 通过后才回填架构-04、专题-01/03/04/05/06/07、相关 API 契约、schema 和索引，本文完成蒸馏后删除。 > 历史：`2026-07-16-批9c-收官与优化方案.md` 的 run1-run3 只作实验记录。 > 可视化：[正文智能体架构图](2026-07-20-正文智能体正式优化架构.html) @@ -25,16 +25,16 @@ 2. 已有事实、人物声音和叙事质感分别有可追溯证据，不再靠 writer 自由猜测。 3. writer 保留真实创作空间，但不得改变细纲硬事件、结果方向和伏笔动作。 4. 生产链在交付候选前挡住可机械验证的硬错误；文学质量由独立 judge 评估，不由 detector 凭观感阻断。 -5. 生成候选能进入“接受/修改后合并/丢弃”三决策，采纳后成为 Canonical 正文并触发章后抽取。 +5. Gate B 通过后，生成候选才进入“接受/修改后合并/丢弃”三决策，采纳后成为 Canonical 正文并触发章后抽取。 6. 多章节、多作品、多场景验证，报告假阴、假阳和无卡实体影响。 ### 2.2 可信边界 -- writer 运行在**无工具、无会话持久化**的隔离进程，只接收序列化 `WriterContext`，不能使用 `Read/Grep/Glob`、数据库或搜索工具。 +- writer、semantic detector、blind judge 都由可信编排器启动为独立模型进程；模型进程只接收各自严格合同，不直接读文件、数据库或共享运行目录。 - 检索节点是唯一取数入口，负责授权、冻结、排序、预算、哈希和来源回显。 - 回放时卡与原文都只能使用 `chapter <= as_of` 的事实；目标章、未来章和标准答案不得进入 writer 进程。 - 卡的终态摘要、未来弧线和无法证明章号的字段不进入回放 `stateAsOf`。 -- 长原文片段只存在于本次临时上下文，不进入 git、长期报告、知识卡或评测摘要。 +- 长原文片段和候选正文只存在于本次受控临时数据区，不进入 git、长期报告、知识卡、日志或评测安全摘要。 ### 2.3 不做 @@ -45,7 +45,7 @@ ## 3. 两条独立链路 -### 3.1 生产链 +### 3.1 产品化生产链（Gate B 后第二阶段） ```mermaid flowchart LR @@ -69,28 +69,47 @@ flowchart LR E --> K[知识草稿与冲突队列] ``` -生产链不强制运行双盲 judge。用户可请求质量详情，或系统按抽样策略运行单次 judge，但 detector 硬门与用户三决策始终存在。 +本链是 Gate B=`passed` 后的产品化第二阶段，不属于 Gate A/B 前置实现范围。生产链不强制运行双盲 judge；用户可请求质量详情，或系统按抽样策略运行单次 judge，但 detector 硬门与用户三决策始终存在。 ### 3.2 离线评测链 ```mermaid flowchart LR - P[预注册样本/冻结点] --> A[原文线 A] - P --> B[卡线 B] - P --> C[双线 C] - A --> D[统一 detector] - B --> D - C --> D - D --> J1[盲评委 1] - D --> J2[盲评委 2/反序] - J1 --> ST[稳定性门] - J2 --> ST - ST -->|不稳定| J3[最多一次第三评委] - ST --> R[去盲汇总与归因] - J3 --> R + P[预注册样本/冻结点] --> O[可信编排器
授权·预算·文件 CAS] + O --> SCH[全评测集顺序表
位置计数差不超过 1] + SCH --> A[A 通用原文检索
不用卡] + SCH --> C[C 卡索引原文检索
卡不进 Writer] + SCH --> B[B card-only
诊断负对照] + A --> W[隔离 Writer 进程
stdin + 严格 JSON schema] + C --> W + B --> W + W --> D[隔离 Semantic Detector 进程
真实报告计算指标] + O --> T[Evaluator-only OracleTruthPack
与臂无关·不进 Writer] + D --> J1[隔离 Blind Judge 进程 1] + D --> J2[隔离 Blind Judge 进程 2/反序] + T --> J1 + T --> J2 + J1 --> JV{双评报告均合法?} + J2 --> JV + JV -->|否| F[失败关闭] + JV -->|是| ST{评分稳定?} + ST -->|是| R[去盲汇总与归因] + ST -->|否| J3[隔离 Blind Judge 进程 3
最多一次] + J3 --> J3V{报告合法且形成稳定配对?} + T --> J3 + J3V -->|是| R + J3V -->|否| F + R --> GB[唯一 GateInputBuilder
manifest + receipts] + GB --> G{Gate 裁决} + O -.仅编排器可写.-> V["/private/tmp raw vault
目录 0700·文件 0600"] + O --> S[安全摘要与原子结果] + W -->|任一调用失败| F + D -->|任一调用失败| F ``` -A/B 使用 `diagnostic_only` 策略：可以绕过“卡与原文必须同时存在”的生产充分性门，但仍必须通过授权、冻结、未来泄漏和候选结构门，且候选永不进入接受链路。C 使用生产策略。 +Gate 核心比较只有 A 与 C：A 不使用卡，以统一查询做通用历史原文检索；C 只用卡定位历史章节，再回读原文。两臂向 writer 提供完全相同的事实约束和原文字符预算，writer 都看不到卡摘要、里程碑语义或检索轨迹，因此 C-A 只能归因于“卡索引是否改善原文选择”。B 保留为 `card_only_diagnostic` 负对照，候选永不进入接受链路，也不参与 Gate B 通过阈值。 + +A/B/C 都使用 `mode=diagnostic_only`、`acceptanceEligible=false`；Gate 通过只形成离线证据，任何臂都不能直接进入产品接受链路。 ## 4. 细纲、创作自由与硬约束 @@ -136,7 +155,7 @@ writer 可以创造非 Canonical 的环境细节、动作、过渡、无名配 正向创作没有回放冻结点时，`asOf` 等于当前 Canonical 最新章。 -离线 eval_draft 的 `indexHint.content` 只允许保存卡名、类型和实际回读章号，不得透传里程碑台阶。这个收紧只作用于诊断评测卡，生产 Canonical 卡继续使用既有冻结状态提示。 +离线 eval_draft 的卡只在 C 臂检索器内部用于定位 `sourceRefs`，不得进入 A/C 的 WriterContext。B 负对照若保留 `indexHints`，`content` 只允许卡名、类型和实际回读章号，不得透传里程碑台阶。这个收紧只作用于离线诊断，生产 Canonical 卡继续使用既有冻结状态提示。 ### 5.3 根据卡回读原文 @@ -149,7 +168,9 @@ writer 可以创造非 Canonical 的环境细节、动作、过渡、无名配 3. 能力、物品或关系的代表性表现； 4. 与本章细纲同类的历史场景。 -若 eval_draft 卡没有持久化 `sourceRefs`，Gate A 可把冻结线内最近三个里程碑章的整章 Canonical block 作为降级代理。该来源必须同时标记 `sourceRef.sourceType=card_chapter_proxy` 和 `proseEvidence.purpose=card_chapter_proxy`，不能伪装成精确片段；每个代理章正文必须出现卡规范名或预注册合法别名，否则失败关闭。连续四章基线不可裁剪，代理等弱补充由 assembler 在固定预算内裁剪。 +若 eval_draft 卡没有持久化 `sourceRefs`，C 臂可把冻结线内最近三个里程碑章作为检索候选来源，但送入 writer 的仍只能是回读后的 Canonical 原文。该来源在 manifest 标记 `sourceRef.sourceType=card_chapter_proxy`，不能伪装成精确片段；每个代理章原文必须出现卡规范名或预注册合法别名，否则失败关闭。连续四章基线不可裁剪，A/C 选择性原文统一按同一 `proseCharBudget` 装配。 + +A/C 的 `proseCharBudget`、连续四章基线和规范化字符算法完全相同。除连续基线外，两臂都必须恰好装配预注册字符数；任一臂合格来源不足即样本失败，不得缩小一臂预算迁就另一臂。检索策略和完整 manifest 只留在编排器侧，不送入 writer。A/C WriterContext 的 allowlist diff 只允许所选原文 `sourceRefs/hash/content` 及其派生的上下文 hash 不同；事实约束、细纲、执行配置、篇幅合同和所有其他字段必须逐字节相同。 `RetrievalManifest` 保存 `planId`、查询、过滤、排序、来源版本、章号、片段 offset、内容哈希和裁剪原因。`manifestId` 对规范化来源集合计算 SHA-256，排除 `runId`、时间戳和执行节点；同一 `planId` 与索引版本必须产生相同 `manifestId`。 @@ -196,13 +217,13 @@ writer 可以创造非 Canonical 的环境细节、动作、过渡、无名配 | `sourceVersion` | string | 是 | 原始来源版本 | | `authorizationSnapshot` | object | 是 | 不可变授权 ID、用途、重验时间 | | `sourceStatus` | enum | 是 | 非允许状态失败关闭 | -| `retrievalPlan/manifest` | object | 是 | 版本、查询、过滤、排序、来源哈希 | +| `retrievalPlan/manifest` | object | 是 | 产品上下文为完整检索信息；A/C 离线 writer 仅保留中性的原文 sourceRefs/hash，不含检索策略、卡命中或卡来源 | | `fineOutline` | object | 是 | 硬约束、可调整节拍、新设定声明 | | `narrativeState` | object | 是 | 时间、地点、角色位置、即时局面 | | `factEvidence[]` | array | 是 | 事实 ID、来源类型、sourceRef、hash | | `proseEvidence[]` | array | 是 | 章号、offset、hash、用途、临时片段 | -| `indexHints[]` | array | 否 | 仅诊断上下文可用的冻结卡提示；严格字段为 `cardId/name/type/content/sourceId/sourceVersion/asOf` | -| `evidenceStrategy` | enum | 否 | 生产缺省视为 `production_dual_evidence`；正文 A/B/C 回放必须显式记录各臂证据策略 | +| `indexHints[]` | array | 否 | 仅 B 负对照可用；A/C 和产品生产上下文硬拒绝 | +| `evidenceStrategy` | enum | 否 | 产品生产缺省为 `production_dual_evidence`；离线三臂必须显式记录策略 | | `patternReferences[]` | array | 否 | 已授权范式卡，只作结构方法参考 | | `evidenceCoverage[]` | array | 是 | 细纲要素到证据的覆盖状态 | | `outputContract` | object | 是 | 篇幅、场景、frontmatter、申报规则 | @@ -210,9 +231,9 @@ writer 可以创造非 Canonical 的环境细节、动作、过渡、无名配 所有对象使用严格 schema，额外字段失败；引用的 ID、版本和 hash 必须存在且一致。 -Gate A 的公共控制还固定 `selectorVersion`、选择器规范 JSON 原始字节 SHA-256、`inputProvenance=oracle_reference_scaffold` 和 `maxContextChars=140000`。loader 在任何数据库读取前核对并原样沿用这些值，不得按真实输入扩大预算；若固定预算连细纲硬约束和连续四章全文基线都装不下，assembler 必须失败关闭。 +Gate A 的公共控制还固定 `selectorVersion`、选择器规范 JSON 原始字节 SHA-256、`writerInputProvenance=preregistered_fine_outline`、`oracleInputProvenance=oracle_reference_scaffold` 和 `maxContextChars=140000`。loader 在任何数据库读取前核对并原样沿用，不得按真实输入扩大预算；若固定预算连细纲硬约束和连续四章全文基线都装不下，assembler 必须失败关闭。 -`evidenceStrategy` 是兼容字段：生产上下文未填写时按 `production_dual_evidence` 校验；正文 A/B/C 回放不得使用缺省值，必须分别显式填写 `historical_prose_only`、`card_index_only`、`card_index_plus_prose`。`indexHints` 只能在 `mode=diagnostic_only`、`purpose=evaluation/diagnostic` 且 `acceptanceEligible=false` 时出现；生产上下文硬拒绝。其 `asOf` 不得超过上下文冻结点，`claimLedger` 不得引用 `indexHints`。只有显式填写 `evidenceStrategy=card_index_only` 的 B 臂允许在合同内跳过连续四章基线，并且必须保持 `proseEvidence=[]`；该例外不能用于生产。 +`evidenceStrategy` 是编排器侧字段：产品生产上下文未填写时按 `production_dual_evidence` 校验；离线 A/B/C manifest 必须分别填写 `generic_prose_retrieval`、`card_only_diagnostic`、`card_indexed_prose_retrieval`。A/C WriterContext 不携带该字段，都必须有相同 `proseCharBudget`、统一 `factEvidence` 且 `indexHints=[]`；这些事实约束只能来自正式设定、细纲声明和独立于被测卡构建的冻结事实台账。C 的卡命中只存在于编排器侧 manifest。只有 B 可在 `mode=diagnostic_only`、`purpose=evaluation/diagnostic`、`acceptanceEligible=false` 时携带严格 `indexHints` 并保持 `proseEvidence=[]`；`claimLedger` 不得引用 `indexHints`。该例外不能用于 A/C 或产品生产。 ### 7.2 `WriterOutput v1` @@ -265,7 +286,7 @@ accepted -> canonical_committed -> extraction_queued detector 只阻断可定位、可验证的问题：细纲硬约束漏项、事实冲突、证据引用缺失、时间地点/知情范围/能力代价矛盾、未来泄漏、输出合同错误。文风、张力和文笔只给建议或交 judge，不作为 detector 硬阻断。 -每个节点都有 deadline；超时先把当前 attempt 标为 `*_timeout`，取消下游，丢弃迟到结果。所有状态写入使用 compare-and-set：仅当数据库中的 `runId + attempt + candidateVersion + currentState` 与事件预期一致时转移；任何较小 attempt 或旧 candidateVersion 的成功、失败和迟到输出都忽略。终态不得回退，重试必须幂等。 +每个节点都有 deadline；超时标记当前 attempt，取消下游并丢弃迟到结果。产品化状态仍须 compare-and-set、终态不可回退和重试幂等，但不得直接复用第 11 节 agent-example 离线文件状态；具体持久化必须在 Gate B 通过后按父仓运行时边界设计或另立 ADR。 `accept_preflight` 必须实时校验：`mode=production`、`acceptanceEligible=true`、qualityPolicyVersion、detector 报告绑定的 candidateSha256/candidateVersion、授权快照仍有效、sourceStatus 未变化、contextSnapshot 未失效、`expectedRevision` 一致。用户修改后合并必须生成新 candidateVersion、重新跑 detector，再回到 Shadow 展示与接受前置校验。 @@ -275,27 +296,31 @@ detector 只阻断可定位、可验证的问题：细纲硬约束漏项、事 `qualityPolicyVersion = writer-eval-v1` -- 状态机：`preregistered -> generating -> detecting -> judging_pair -> stable_report`；双评不稳定时进入 `adjudicating -> adjudicated_report`，第三评委后仍无稳定配对则进入 `invalid_unstable`；授权、冻结、合同或模型失败进入对应 `failed_*` 终态。 +- 状态机：`preregistered -> generating -> detecting -> judging_pair -> stable_report`；双评不稳定时进入 `adjudicating -> adjudicated_report`；第三评委报告非法进入 `failed_judge_invalid`，第三评委后仍无稳定配对进入 `failed_judge_unstable`；授权、冻结、合同或模型失败进入对应 `failed_*` 终态。 - 离线优化允许最多 5 轮，且每轮只改一个变量；与生产两轮返修是两套状态机。 -- 三臂使用相同细纲、冻结点、模型、篇幅算法和最大生成预算。 -- 候选臂名映射为随机化 ID；顺序种子由预注册 `evaluationSetVersion + sampleId` 派生并固定。 -- judge 的可信输入边界是独立 `writer-blind-input-v1` 内容，包含 `blind-1/2/3` 候选正文/哈希，以及所有臂完全相同的 `sharedEvaluationReference`。共同参考的细纲只保留 `sourceRef/hardConstraints/adjustableBeats/declaredNewFacts` 四字段，不增加 `entities`；另带必需角色、伏笔、章末钩子和冻结点前连续四章历史原文基准，用于评价细纲忠实、设定、文风和卡索引正确性。它可在真实运行时临时传递，但不进入安全摘要。共同参考严禁包含 `indexHints`、各臂补充原文、卡 manifest、`evidenceStrategy`、真实映射或臂名，不能用被测卡本身给被测候选背书。真实 A/B/C 映射仅在编排器内存中存在，judge 不得访问各臂 WriterContext、原始运行目录或含 `candidate-A/B/C` 的路径。 +- 三臂使用相同细纲、冻结点、完整模型 ID、effort、单次预算、上下文上限、篇幅算法和输出 schema；A/C 还必须使用相同原文字符预算和统一事实约束。启动前对完整 WriterContext 执行 allowlist diff，只允许原文内容/来源及派生 hash 不同；出现其他差异即失败。 +- A/B/C 运行顺序由整个预注册评测集一次性生成：先按 `SHA-256(evaluationSetVersion + sampleId)` 排序全部样本，再按索引循环分配 `[A,B,C]`、`[B,C,A]`、`[C,A,B]`。生成完整顺序表后机械验证每个位置上的臂计数差不超过 1；禁止逐样本独立 shuffle。盲化映射使用同样的评测集级分配原则和独立命名空间。 +- judge 的可信输入边界是独立 `writer-blind-input-v2`：盲化候选/哈希、所有臂相同的细纲评测字段，以及 evaluator-only `oracleTruthPack`。真实 A/B/C 映射仅在编排器内存中存在，judge 不得访问各臂 WriterContext、原始运行目录或含臂名的路径。 - 两个评委使用独立无会话实例，第二评委反转顺序；评分步长为 0.5。 -- 同维分差 > 0.5 时判不稳定，最多增加一次第三评委。三评分中若至少一对差值 <=0.5，则该维最终分取三者中位数；若不存在稳定配对，则样本进入 `invalid_unstable`，不参与方向结论。 +- 同维分差 > 0.5 时判不稳定，最多增加一次第三评委。三评分中若至少一对差值 <=0.5，则该维最终分取三者中位数；若不存在稳定配对，则样本进入 `failed_judge_unstable`，顶层运行失败。 - 五维：设定与实体保真、情节与细纲忠实、叙事完整与张力、文风一致、文笔质量。 -- 离线达标不改变 detector 红线，也不允许评委看到 writer 未见的底牌。 +- 离线达标不改变 detector 红线。评委可以看到独立真值包，但不能看到被测卡、各臂检索轨迹或臂专属补充原文。 + +`oracleTruthPack` 固定为 `oracle-truth-pack-v1`，由可信 loader 在同一冻结快照内生成：全量 Canonical 历史中 `chapter <= asOf` 的事实断言，加上目标章 reference scaffold 中预注册的目标事实断言。它至少包含 `schemaVersion/evaluationSetVersion/sampleId/workId/asOf/sourceSnapshotSha256/authorizationSnapshotId/historicalAssertions[]/targetAssertions[]/packSha256`；每条断言带稳定 ID、来源版本、章号边界和内容 hash。包中不得包含被测卡、卡派生断言、A/B/C 检索 manifest、各臂原文或目标章文风答案。 + +`oracleTruthPack` 的授权快照必须固定 `allowedPurpose=offline_evaluation`、来源状态、来源版本和重验时间，只授权本次 evaluator；所有 judge 接收字节完全相同的 pack。它不进入 writer、detector、Gate 安全摘要或日志；原始包只在 raw vault 临时存在，长期只保留 schema/hash/授权回执。其历史断言用于核对远端历史事实，目标断言用于核对细纲和目标事实，不得用任一臂检索到的补充原文给候选背书。授权失效、schema/hash 不一致或三位评委 pack hash 不同，样本失败。 ### 10.1 两级验收门 | 门 | 有效样本 | 机械通过条件 | 其他终态 | |---|---|---|---| -| Gate A 链路可运行 | 深空 5 章，五类场景各 1；授权/冻结通过且评委稳定 | 5/5 schema 合法；未来泄漏 0；系统失败 0；C 臂 detector 最终高严重度 0；细纲硬约束覆盖率 100% | 有效样本 <5=`insufficient_evidence`；任一泄漏/系统失败/高严重度残留=`failed` | -| Gate B 正文层正式通过 | 至少 2 本书、每书 >=5 章、总计 >=10 章；五类场景均覆盖 | Gate A 已 passed；C-A 的“设定与实体保真”平均增量 >=0.25 且至少 60% 样本增量 >0；“文风一致/叙事张力”平均增量均 >=-0.25，且任一维下降 >0.5 的样本占比 <=20%；C 臂硬约束覆盖率 100%、高严重度 0 | 样本不足或不稳定样本 >20%=`insufficient_evidence`；无明显保真增益但无退化=`no_gain`；发生质量退化或硬错误=`failed` | +| Gate A 链路可运行 | 深空预注册 5 章，五类场景各 1 | 5/5 schema 合法且评委稳定；未来泄漏 0；系统失败 0；C 臂 detector 最终高严重度 0；细纲硬约束覆盖率 100% | 任一系统/schema/hash/泄漏/judge 异常=`failed`；仅预注册集合自身不足 5 或场景不全=`insufficient_evidence` | +| Gate B 正文层正式通过 | 至少 2 本书、每书 >=5 章、总计 >=10 章；五类场景均覆盖 | Gate A 已 passed；A/C 所有样本合法且稳定；C-A 的“设定与实体保真”平均增量 >=0.25 且至少 60% 样本增量 >0；“文风一致/叙事张力”整体及各非空新角色分层均不退化；C 臂硬约束覆盖率 100%、高严重度 0 | 任一系统/schema/hash/泄漏/judge 异常=`failed`；仅预注册作品/样本/场景自身不足=`insufficient_evidence`；无明显增益且无退化=`no_gain`；B 不参与通过阈值 | 裁决按以下顺序执行，命中即停止，保证每次只有一个终态： -1. **Gate A**：有效样本不足 5 -> `insufficient_evidence`；否则只要存在 schema 非法、未来泄漏、系统失败、C 臂高严重度残留或硬约束覆盖率 <100% -> `failed`；其余 -> `passed`。 -2. **Gate B**：Gate A=`insufficient_evidence` -> `insufficient_evidence`；Gate A=`failed` -> `failed`；否则若作品/样本/场景覆盖不足或不稳定样本占比 >20% -> `insufficient_evidence`；再判断硬错误或质量退化，命中 -> `failed`；再判断保真平均增量与正增益样本占比，达标 -> `passed`；其余 -> `no_gain`。 +1. **Gate A**：先检查预注册 manifest、顺序表、allowlist diff、全部预期调用回执、schema/hash、泄漏审计和 judge 稳定性，任一异常 -> `failed`；再检查预注册集合定义时是否已经不足 5 个样本或五类场景不全，命中 -> `insufficient_evidence`；再检查 C 臂硬门，命中 -> `failed`；其余 -> `passed`。 +2. **Gate B**：先检查本次 Gate B 的全部系统/schema/hash/泄漏/judge 状态，任一异常 -> `failed`；再继承 Gate A 终态，Gate A=`failed` -> `failed`，Gate A=`insufficient_evidence` -> `insufficient_evidence`；再检查预注册作品/样本/场景自身规模，不足 -> `insufficient_evidence`；再检查 A/C 硬错误、整体或任一非空新角色分层质量退化，命中 -> `failed`；再判断 C-A 保真增益，达标 -> `passed`；其余 -> `no_gain`。B 只进入诊断报告，不进入这些阈值。 只有 Gate B=`passed` 才解锁细纲智能体真实能力验收；`no_gain` 只形成“卡未证明增益”结论，不视为通过。 @@ -315,7 +340,7 @@ detector 只阻断可定位、可验证的问题：细纲硬约束漏项、事 新角色比例只统计具名 `requiredCharacters` 在冻结点前无记录的比例。真实 loader 在来源、授权、scaffold、卡和正文所在的同一个 `REPEATABLE READ READ ONLY` 事务内，直接扫描冻结历史 Canonical 正文并返回名字对应的首次命中章与命中章集合，再独立重算 `knownBeforeAsOf/absentBeforeAsOf/newCharacterRatio`，不得相信卡内是否出现该名字。489 的加特朗在 488 前无记录，因此为 1.0；321/199/523 的具名角色已有记录，因此为 0；544 的“内应”是泛称、无法机械判定具体身份，必须为 `null + unresolved_generic_role`，不允许默认成 0。 -真实装配保留目标章 reference scaffold，并以 `inputProvenance=oracle_reference_scaffold` 明示来源。它只用于固定本次正文层细纲输入和目标事实泄漏代理；这项验证不覆盖上游清洗、抽卡、范式、细纲生成或完整创作链，不能据此宣称整条创作链完成。 +真实装配把目标章 reference scaffold 分成两份：writer 只接收预注册细纲硬约束和统一事实约束；scaffold 的目标事实断言只进入 evaluator-only oracleTruthPack。完整 scaffold、目标断言和原文答案均不得进入 writer。这项验证不覆盖上游清洗、抽卡、范式、细纲生成或完整创作链，不能据此宣称整条创作链完成。 仓内配置不含原文全文。`writerContextInput.contentMode=sanitized_contract_fixture`，连续四章只放脱敏合成短文本，用于 dry-run 机械证明 WriterContext 合同、冻结边界、三臂差异、manifest 可复现和候选不可接受；不能据此声称历史原文完整、生成质量通过或 real-run 完成。 @@ -329,11 +354,132 @@ dry-run 命令： dry-run 只生成计划、manifest 和上下文摘要，不调用模型。测试注入路径虽可验证 writer、detector 与盲评编排，但 judge 只接收独立盲化内容和共同评测参考，不能取得 raw 目录、真实臂映射或任一臂专属证据；评委顺序变化不得改变共同参考。当前真实 semantic detector 与 judge adapter 尚未实现，CLI `--execute` 必须明确失败关闭；在 adapter 接线、离线测试和预算确认完成前，不得声称真实回放或 Gate A 已完成。 -Gate 判定只消费逐样本脱敏输入。`writer_gate.py` 在可信边界内自行计算 Gate A/B 的有效样本、作品/场景覆盖、C 臂硬门、C-A 五维增量、退化比例与五类混淆项；不信任上游聚合数字。五类混淆项为假阴、假阳、泄露、评委不稳定和新角色无卡，必须逐样本记录后汇总。 +当前实现与本版合同仍有明确差距：writer runner 只把 `opus` 当模型参数，未绑定绝对 CLI/hash、完整 model ID、单次预算与输出 schema，也未形成联合回执，stderr 仍可能泄漏；配置仍使用旧三臂证据策略、`inputProvenance=oracle_reference_scaffold` 和 temperature/topP/seed 数值；顺序仍是逐样本处理，缺少全评测集平衡表与完整上下文 allowlist diff；真实 oracleTruthPack、semantic detector、blind judge、GateInputBuilder、confounders、vault lease 和文件 CAS 未接线；测试注入仍把 detector 指标写死，`writer_gate.py` 及错误测试仍可能先判样本不足。以上任一项未整改，Gate A real-run 不得启动。 -## 11. 用户闭环与下游交接 +真实 CLI 极小探测还有一条直接证据：一次 Opus 调用等待 177043ms 后因 API 503 失败，进程 `exit=1`；JSON envelope 却同时出现 `type=result`、`subtype=success`、`is_error=true`、`api_error_status=503`、`terminal_reason=api_error`、`stop_reason=stop_sequence`、`total_cost_usd=0`、完整零值 `usage` 和空 `modelUsage={}`。因此 `subtype=success`、合法 JSON、完整 usage 或 `stop_reason=stop_sequence` 都不能单独证明调用成功；该证据也说明每次调用必须有编排器硬 deadline。安全摘要只记录状态码和受控字段，不记录具体网关错误正文。 -Shadow 候选展示后提供三决策： +该失败探测没有产生可验证的成功 `structured_output` 或完整 model ID，只能证明失败 envelope 语义。必须先完成第 11.4 节成功探测，才能冻结离线评测 adapter 所需字段；在此之前 `--execute` 继续失败关闭。 + +当前 `writer_gate.py` 把样本不足检查放在部分系统失败之前，错误测试也固化了这一顺序；两者必须按 10.1 重写。detector 指标必须来自严格校验的真实语义报告，禁止常量、默认通过或测试替身进入 real-run。第三评委报告非法或仍不稳定时，样本和顶层都必须失败。 + +### 10.3 Gate 输入与混淆项合同 + +`GateInputBuilder` 是 manifest/receipts 到 `gate-input.json` 的唯一可信入口，owner 固定为 `.claude/skills/replay-eval` 的可信编排器，由 `run_writer_replay.py` 在所有样本终态后调用。它只读取预注册 manifest、全评测集顺序表、A/C allowlist diff 回执、retrieval manifest、writer/detector/judge 执行回执与报告、oracleTruthPack 回执、泄漏审计和授权回执；逐项校验 schema、hash、run/sample/candidate 绑定后生成严格 `writer-gate-input-v2`。`writer_gate.py` 只接受该文件及其 SHA-256，不得接收手工对象、上游聚合数字或缺失回执的补写数据。 + +`writer_gate.py` 是 `writerGateBPassedReceipt` 的唯一签发者。它先从 `gate-input.json` 生成严格 `gate-report.json`；只有 Gate B 报告 `status=passed`，才可签发 receipt。receipt 必须包含 `runId/evaluationSetVersion/gateInputSha256/gateReportSha256/gatePolicyVersion/status=passed/issuedAt/receiptRevision/previousStateSha256/receiptSha256`，其中 `receiptSha256` 对除自身外字段的规范 JSON 计算。`failed`、`insufficient_evidence`、`no_gain` 或报告非法时一律不签发。 + +签发必须进入第 11.5 节同一文件 CAS journal 序列：在 `state.lock` 内先原子落盘并提交 `gate-report.json` 对应 revision，再基于该 `gateReportSha256` 和前一状态 hash 生成 receipt、原子落盘并提交下一 revision；禁止先签 receipt、跨运行复用或在 journal 外补发。细纲 real-run 入口守卫只读取已签发文件，验证 receipt 严格 schema、规范 hash、gate report、gate input、`receiptRevision/previousStateSha256` 与 journal 链全部一致；禁止调用方自算 JSON 冒充 receipt。细纲 dry-run 不要求该 receipt。 + +`gate-input.json` 不含正文、prompt、完整模型响应、oracle 断言或 raw path。每个样本的 `confounders` 必须完整包含以下字段，缺失、`null` 或默认空对象均使 Gate 输入 schema 失败： + +| 字段 | 确定性算法 | +|---|---| +| `falseNegative.A/C` | 对同一 `assertionId` 或 `constraintId`，detector verdict=`pass`、稳定 judge verdict=`fail` | +| `falsePositive.A/C` | 对同一 `assertionId` 或 `constraintId`，detector verdict=`fail`、稳定 judge verdict=`pass`，且 leakage=false | +| `leakage.A/C` | 对应臂 `leakageAuditReceipt.findingCount > 0` | +| `reviewerInstability` | 双评任一维差值 >0.5；第三评委可把样本裁成稳定，但该字段仍为 true；第三评委后不稳定则系统失败 | +| `newCharactersWithoutCards` | 冻结点前无记录的具名 requiredCharacters 中，在 C 臂卡检索 manifest 无合法卡命中的数量、分母、ratio 与名称集合 hash | + +Gate B 必须按预注册 `newCharacterRatio` 分为 `zero=0`、`low=(0,0.5]`、`high=(0.5,1]`、`unresolved` 四层，逐层报告样本数、C-A 五维增量、正增益比例、detector 假阴/假阳和无卡新角色。整体平均仍可用于增益阈值，但任一非空层出现硬错误或超过 10.1 的文风/张力退化线，Gate B 必须失败，不能用单层整体平均掩盖。 + +混淆项只按同类、同 ID verdict 计算：事实断言只能比较 detector `assertionVerdicts[]` 与 judge `oracleAssertionVerdicts[]` 的同一 `assertionId`，硬约束只能比较双方 `hardConstraintVerdicts[]` 的同一 `constraintId`，不得跨类型配对。预注册 manifest 固定 `comparableAssertionIds`，它必须等于 detector 冻结事实清单的完整 ID 集，并且是 oracleTruthPack assertion ID 集的子集；硬约束预期集来自预注册细纲。detector 与稳定 judge 必须完整覆盖各自预期集，每个 ID 仅出现一次。任一 verdict=`unknown`，或 ID 缺失、重复、越界、candidateSha256 不同，均使 confounder 计算失败并将样本置为 `failed`。五维分数不得推导或覆盖 verdict。 + +## 11. agent-example 离线评测 adapter 执行合同 + +本节是 agent-example 内 writer、semantic detector、blind judge 的离线 real-run 合同。它是为固定模型、独立预算和可审计回放设立的有限例外，不是 Muse 产品运行时方案。第 10.2 节只描述 Gate A 样本和当前实现状态，不再另定义调用参数、隔离或失败语义。 + +### 11.1 可信编排器与统一调用基线 + +可信编排器是唯一可以读取授权来源、装配输入、持有 A/B/C 映射、管理预算、写临时数据和推进状态的进程。三个模型角色都直连固定 Claude CLI，不调用 `chat_governed`，也不写 New-API 共享额度账本；但每次外发仍必须绑定授权快照、单次/总预算和执行回执。该例外在 Gate B 通过前不得接入产品路径。 + +Gate B 通过后的产品化必须回到父仓 `AI Orchestration -> Integration Execution Facade -> New-API` 边界；若该边界不能满足需求，必须另立正式 ADR 并评审通过，不能把本节直连 CLI 当成生产方案。 + +每次模型调用必须是 fresh process，并显式绑定以下已验证参数：`--print`、`--bare`、`--model`、`--effort`、`--max-budget-usd`、`--output-format json`、`--json-schema`、`--tools ""`、`--no-session-persistence`、`--disable-slash-commands`、`--strict-mcp-config`、`--mcp-config '{"mcpServers":{}}'`、`--system-prompt`。`--print` 是非交互执行及预算、JSON 输出、无会话参数生效的前提；`--bare` 用于跳过 hooks、LSP、插件同步、归因和 auto-memory。业务输入只从 stdin 传入，不得把正文、完整 prompt 或臂名写进命令行参数。 + +| `ExecutionProfile` 字段 | 约束 | +|---|---| +| `profileVersion/adapterRole` | 固定合同版本；角色为 `writer`、`semantic_detector`、`blind_judge` | +| `claudeExecutablePath/claudeExecutableSha256/claudeCliVersion` | 绑定绝对路径、可执行文件 SHA-256 和版本 `2.1.211`；任一变化先重新预注册 | +| `modelAlias/resolvedModelId/effort` | `opus` 只可作配置输入别名；预检探测解析完整 model ID，实际调用和回执都使用该完整 ID，禁止降级换模 | +| `maxBudgetUsdPerCall/timeoutSeconds` | 每个角色分别预注册；到限即失败，不扩大、不借用共享账本 | +| `maxContextChars` | 在装配前校验；A/B/C writer 上限完全相同；A/C 超限不得截断硬约束或连续四章基线，B 臂沿用第 7.1 节诊断例外 | +| `jsonSchemaId/jsonSchemaSha256` | 输入输出都绑定严格 schema；额外字段、缺字段或 hash 不一致均失败 | +| `systemPromptId/systemPromptSha256` | 三臂 writer 完全相同；所有评委也完全相同，评委编号只进执行元数据，不改变提示词 | +| `temperature/topP/seed` | 固定记为 `unsupported`，`reproducibilityClaim=not_claimed`；不作为 CLI 参数或已绑定控制项 | + +三臂 writer 的 `resolvedModelId/effort/maxBudgetUsdPerCall/maxContextChars/jsonSchemaSha256/systemPromptSha256` 必须逐字段相等，并对规范化配置计算同一 `executionProfileSha256`。回执缺完整 model ID 或与预注册值不一致即失败。detector 对所有候选使用同一 detector profile；所有 judge 调用使用同一 judge profile。 + +每次调用都由 `sandbox-exec` profile 拒绝隔离目录之外的文件读写，只允许 Claude CLI 完成模型调用所需的 DNS、代理和出站网络；工具、插件、hooks、技能、MCP 和其他网络用途全部禁止。cwd、HOME、TMPDIR 均指向本次 0700 隔离目录，调用结束即清理。可执行文件使用已绑定绝对路径，因此不传继承 PATH。 + +环境只允许以下字段：认证 `ANTHROPIC_API_KEY` 或 `CLAUDE_CODE_OAUTH_TOKEN` 中经授权的一种；代理 `HTTPS_PROXY/HTTP_PROXY/NO_PROXY` 及对应小写字段；locale `LANG/LC_ALL`；证书 `SSL_CERT_FILE/SSL_CERT_DIR/NODE_EXTRA_CA_CERTS`。HOME/TMPDIR 由编排器覆盖，其他 repo、数据库、云平台和业务 secret 一律不继承。blind judge 每次调用都使用新目录、新进程和新 stdin，不得发现 raw 目录、真实 A/B/C 映射或含臂名路径。 + +### 11.2 三类输入输出 + +| 角色 | 唯一输入 | 唯一业务输出 | 失败关闭条件 | +|---|---|---|---| +| writer | 严格校验的 `WriterContext v1`；A/C 只含统一事实约束与选出的历史原文，不含卡语义、检索策略或完整 manifest；B 为独立诊断例外 | `WriterOutput v1`；候选正文、claim ledger、补证请求、新设定申报、自检 | 上下文/输出 schema 非法，A/C allowlist diff 失败，预算或超时，完整 model ID 不符，候选与上下文 hash/版本不绑定 | +| semantic detector | `semantic-detector-input-v2`；候选、细纲硬约束、claim ledger、允许核对的冻结前证据和上下文绑定 | `semantic-detector-report-v2`；findings、`assertionVerdicts[]`、`hardConstraintVerdicts[]`、证据定位及报告 hash | 报告非法、候选绑定不符、verdict 为 unknown、ID 集不完整、结论无受控证据或高严重度残留 | +| blind judge | `writer-blind-input-v2`；盲化候选、统一细纲评测字段和字节相同的 oracleTruthPack | `blind-judge-report-v2`；五维评分、`oracleAssertionVerdicts[]`、`hardConstraintVerdicts[]`、候选/pack hash | pack 授权/hash 不同、verdict 为 unknown、ID 集不完整、看到臂专属证据、schema/候选/顺序非法，或第三评委后仍不稳定 | + +`semantic-detector-input-v2` 必须包含 `schemaVersion/runId/sampleId/opaqueArmId/candidateSha256/candidateBody/contextSnapshotSha256/fineOutline/hardConstraints/claimLedger/factEvidence/proseEvidence/asOf/authorizationSnapshotId/inputSha256`；不得包含 oracleTruthPack、目标章或未来章正文。`semantic-detector-report-v2` 必须包含 `schemaVersion/runId/sampleId/opaqueArmId/inputSha256/candidateSha256/modelReceiptSha256/findings[]/assertionVerdicts[]/hardConstraintVerdicts[]/status/reportSha256`。两类 verdict 数组分别绑定稳定 `assertionId` 或 `constraintId`、`candidateSha256`、`verdict=pass|fail|unknown` 和受控证据引用。编排器只从 schema、hash、候选和 ID 集均合法的报告计算 `highSeverityCount` 与 `hardConstraintCoverage`；unknown 或 ID 集不完整时报告非法，禁止填默认值。 + +未来泄漏不交给 semantic detector 猜测。可信编排器单独执行 `leakage-audit-v1`：只在编排器边界内比较候选与预注册 `forbiddenFacts[]`、目标/未来读取 trace、`asOf` 和来源 hash，输出不含禁区正文的 `leakageAuditReceipt`。禁区事实不得进入 writer、judge、日志或安全摘要；Gate 只消费该回执的 `status/findingCount/receiptSha256`。 + +`blind-judge-report-v2` 必须包含 `schemaVersion/runId/sampleId/reviewerInvocationId/blindInputSha256/oracleTruthPackSha256/candidateOrder[]/candidateScores[]/oracleAssertionVerdicts[]/hardConstraintVerdicts[]/modelReceiptSha256/status/reportSha256`。每个 `candidateScores[]` 项绑定 `blindCandidateId/candidateSha256`，并为五个维度逐项给出 0.5 步长分数和受控理由。两个 verdict 数组中的每一项分别绑定稳定 `assertionId` 或 `constraintId`、`candidateSha256`、`verdict=pass|fail|unknown` 和受控证据引用；证据只能引用候选区间、oracle assertion 或预注册 constraint，不得引用臂专属检索材料。`candidateOrder[]` 必须与本次 stdin 完全一致；分数与 verdict 独立，禁止用分数阈值生成 verdict。 + +每份 judge 报告先独立校验，再进入稳定性裁决。第三评委不是容错兜底：其报告 invalid，或三份报告仍找不到稳定配对，样本分别进入 `failed_judge_invalid` 或 `failed_judge_unstable`，顶层运行失败。失败样本不得进入 Gate A 的有效样本分母，也不得以“有效样本不足”掩盖系统失败。 + +### 11.3 敏感临时数据 + +原文、候选正文、完整模型输入和完整模型响应只允许写入 `/private/tmp` 下本次运行的独立 raw vault。批准角色只能是用户/创始人；写入任何 raw 字节前，先在非敏感文件 journal 原子持久化 `vaultLease`，绑定 `authorizationId/approvedBy/runId/vaultId/sourceVersion/contentHashes/createdAt/retainUntil/purpose`。没有有效 lease 不得创建 vault。 + +vault 路径由可信编排器生成不可猜测 ID，拒绝调用方传入绝对路径、`..`、软链接和任何 realpath 逃逸。目录权限固定 0700，文件固定 0600；创建、打开、重命名和清理全程拒绝 symlink 跟随。恢复时先扫描所有未关闭 lease：对应 vault 存在则进入清理流程，不存在则补记关闭回执，禁止留下无 lease 的孤儿 raw 目录。 + +默认在安全摘要和最终状态原子落盘后立即清理 raw vault。只有单独的调试授权记录 `authorizationId/approvedBy/runId/vaultId/sourceVersion/contentHashes/retainUntil/reason` 才可保留，授权不得跨运行复用，最长 24 小时。清理成功前运行不得进入 `completed`；失败进入 `failed_raw_cleanup`，由可信清理器持久重试并保持 vault 隔离，24 小时仍未清除升级为安全事件。任何状态都继续禁止输出 raw path。 + +日志、安全摘要和长期报告不得包含原文、候选正文、完整 prompt/response、raw path、真实臂映射或可反推内容的片段。stderr 不落盘、不回显原文；adapter 只输出稳定失败码、退出码、长度/hash 和预定义受控摘要。 + +### 11.4 运行回执、预算与失败语义 + +每次调用都产生不含正文的 `ExecutionReceipt`，至少记录 `adapterRole/invocationId/requestedModelId/actualModelId/modelMatch/effort/maxBudgetUsdPerCall/totalCostUsd/usage/modelUsage/stopReason/terminalReason/isError/apiErrorStatus/exitCode/durationMs/inputSha256/structuredOutputSha256/jsonSchemaSha256`。CLI 结果未提供完整实际 model ID、`total_cost_usd`、usage、modelUsage、stop reason 或 terminal reason，或任一字段无法归一化时，回执非法，不能把该调用算作成功。 + +`envelope.structured_output` 是唯一业务对象，必须直接通过该角色的严格 JSON schema；`envelope.result` 只作审计和受控错误分类，禁止解析为业务 JSON，也禁止作为 structured_output 缺失时的 fallback。当前 503 探测没有证明 2.1.211 成功响应的 `structured_output` 字段形状；实现前必须完成一次极小成功探测并冻结 envelope schema/hash。该探测未成功前 Gate A 不得启动。 + +调用成功必须联合满足：进程 `exitCode=0`；envelope `type=result` 且 `is_error=false`；`terminal_reason` 属于该角色预注册的正常终止集合；业务输出通过严格 schema；`modelUsage` 能证明实际模型且与请求模型一致；`usage` 结构和数值合法并可核账。`subtype=success` 与 `stop_reason` 只作审计字段，不能覆盖非零退出、`is_error=true`、API error、空 `modelUsage` 或 schema 失败。 + +每个 real-run Gate 启动前都必须单独确认 `totalBudgetUsd`，并在预注册配置中列出 writer、detector、judge 的单次预算、最大调用次数和最坏总额。实际美元成本以 envelope `total_cost_usd` 为权威值，按 JSON 十进制原值解析并统一到 6 位小数、`ROUND_HALF_UP`；若 `modelUsage` 提供分模型 `costUSD`，其同规则求和后必须与权威值一致，否则回执非法。编排器在每次启动前预留最坏预算，累计 `totalCostUsd` 与预留上限都不得超过该 Gate 总预算；缺字段、超总额或 CLI 因预算停止都失败关闭。 + +| 稳定失败码 | 触发条件 | +|---|---| +| `{ROLE}_TIMEOUT` | 超过该角色 deadline；取消下游并丢弃迟到输出 | +| `{ROLE}_NONZERO_EXIT` | Claude CLI 非零退出；stderr 仅转为受控摘要 | +| `{ROLE}_API_ERROR` | `is_error=true`、`terminal_reason=api_error` 或存在 API 错误状态；不记录网关错误正文 | +| `{ROLE}_RECEIPT_INVALID` | envelope 或联合回执缺字段、terminal reason 非法、成本无法对账 | +| `{ROLE}_SCHEMA_INVALID` | CLI 包装、业务输出或报告不符合严格 schema | +| `{ROLE}_BUDGET_EXCEEDED` | 单次预算停止、累计预算超限或 usage 无法核账 | +| `{ROLE}_MODEL_MISMATCH` | 实际 model 缺失或与预注册 model 不一致 | +| `JUDGE_INVALID` | 任一必需 judge 报告非法；第三评委非法时样本直接失败 | +| `JUDGE_UNSTABLE` | 第三评委后仍无稳定配对 | + +一个异常只产生一个 `primaryCode`，其余命中项进入不含敏感信息的 `causes[]`。主码优先级固定为：`TIMEOUT > API_ERROR > NONZERO_EXIT > RECEIPT_INVALID > BUDGET_EXCEEDED > MODEL_MISMATCH > SCHEMA_INVALID > JUDGE_INVALID > JUDGE_UNSTABLE`。实测 503 因此归 `API_ERROR`，非零退出、空 modelUsage 和零值 usage 只作 causes。任一失败码都使当前样本 `ok=false`、`acceptanceEligible=false`，并停止该样本后续调用；不得换模型、扩大预算、跳过失败臂或把系统失败降级成普通质量分。 + +### 11.5 文件型 CAS 与原子写 + +离线评测 adapter 不使用内存状态作为真实执行依据。每个运行维护不可变 `states/.json` journal，`state.json` 固定为当前 revision 的完整内容副本，不是路径指针。revision 至少包含 `runId/sampleId/arm/attempt/candidateVersion/state/revision/previousStateSha256/resultSha256/safeSummarySha256/cleanupState`。 + +状态目录通过已验证父目录 fd 使用 `openat` 与 no-follow 语义访问，拒绝路径替换和 symlink；固定锁文件 `state.lock` 在状态目录内排他创建，并用 `fcntl.flock` 包围读、比较、写全过程。推进时先排他创建 0600 revision 临时文件并 `fsync`，rename 为不可变 revision；再写 0600 `state.json.tmp`、`fsync`、rename 覆盖 `state.json`，最后 `fsync` 状态目录。结果、安全摘要和清理标记先原子落盘，其 hash 随同一 revision 提交，未被 revision 引用的文件不算已提交。 + +旧 revision、旧 attempt、旧 candidateVersion、重复终态和迟到结果统一返回 `CAS_CONFLICT`，不能覆盖较新状态。非敏感 journal 保留到运行审计期结束，使 `previousStateSha256` 可逐版验证。进程崩溃后比较 `state.json` 与不可变 journal，恢复最后一个 schema 合法、hash 链与关联文件 hash 完整的 revision；临时文件、孤儿文件、断链状态、异常锁或未关闭 vault lease 一律先失败关闭并清理，不得继续模型调用。 + +### 11.6 Gate A 绑定 + +Gate A real-run 只允许使用满足本节合同的离线评测 adapter。执行前必须机械证明：成功 structured_output 探测已冻结；Gate A 总预算与单次预算已确认；A/C 执行配置、事实约束和原文字符预算相等；全评测集顺序表平衡；完整上下文 allowlist diff 通过；temperature/topP/seed 为 `unsupported/not_claimed`；三类 schema、oracleTruthPack、GateInputBuilder、泄漏审计与回执测试通过；judge 隔离无法发现 raw、映射和臂名；raw lease、vault 权限/逃逸/保留/清理测试通过；文件 CAS journal 的并发、崩溃和迟到结果测试通过。Gate B 启动前另行预注册并批准独立预算，不得沿用 Gate A 批准。 + +本次设计修订只定义合同，不等于 adapter 已实现，更不等于 Gate A 已运行或通过。真实 `--execute` 在第 10.2 节列出的缺口全部关闭、机械测试通过且预算获批前，必须继续失败关闭。 + +## 12. 用户闭环与下游交接（Gate B 后第二阶段） + +本节不在 Gate A/B 前实现。Gate B=`passed` 后，Shadow 候选展示才提供三决策： 1. 原样接受； 2. 修改后合并，带 `expectedRevision`； @@ -341,23 +487,31 @@ Shadow 候选展示后提供三决策： 原样接受和修改后合并都必须经过 `accept_preflight`。修改后合并先生成新 candidateVersion 并重新 detector；原样接受也必须重新校验授权、来源、质量策略、candidate hash 和 `expectedRevision`。通过后才调用 confirm；版本冲突返回 `revision_conflict`，不得静默覆盖。Canonical 提交后异步触发章后抽取，产出知识草稿和冲突队列；正文层只定义交接合同，不直接审批知识入库。 -## 12. 实施计划与 SoT 回填 +## 13. 分阶段实施计划与 SoT 回填 -1. 启用并完善 `meta/schemas/generation_context.yaml`，新增 `WriterOutput`、`RetrievalPlan/Manifest`、`claimLedger` 合同。 -2. 新增受控历史原文读取入口；扩展 search 为卡索引检索，不让 search 直接返回无版本原文。 -3. 调整 `read-context`：四章全文基线、卡 `stateAsOf`、双证据和确定性 manifest。 -4. 调整 `writer`：无工具隔离执行、受预算补证、硬约束/可调节拍、新设定申报。 -5. 调整 `continuation`：确定性动态篇幅与输出合同。 -6. 调整 `detect`：硬门清单、claimLedger 语义验证、结构化返修单。 -7. 调整 `quality-gate/eval/judge`：生产与离线两套策略、双盲稳定性和第三评委上限。 -8. 接通 Shadow 三决策、confirm、Canonical 和异步抽取交接。 -9. 为无工具边界、未来章读取失败、卡冻结、manifest 复现、schema、超时、幂等、三臂隔离和用户决策增加机械测试。 -10. 通过 Gate A 后执行 Gate B；Gate B 通过才恢复细纲智能体。 -11. 评审通过后回填父仓 `架构-04`、`专题-01/03/04/05/06/07`、相关 API 契约、schema 和索引，删除重复定义；任务完成后蒸馏并删除本文。 +**第一阶段：做到 Gate B 裁决、receipt 签发和细纲入口守卫。** -## 13. 实施前门禁 +1. 实现 A/C 两种原文检索、B 负对照、统一事实约束、相同原文字符预算、全评测集顺序表和完整上下文 allowlist diff。 +2. 实现 writer 生成、真实 semantic detector、evaluator-only oracleTruthPack、隔离 blind judge、逐断言/逐约束 verdict、泄漏审计、混淆项合同、唯一 GateInputBuilder 与 `writer_gate.py` 新裁决顺序。 +3. 实现第 11 节离线 CLI adapter：绝对可执行文件/hash/版本、完整 model ID、sandbox、structured_output、预算/回执、raw lease/vault、文件 CAS 和原子结果。 +4. 在第一阶段实现 `writer_gate.py` 唯一 receipt 签发器和细纲 real-run 入口守卫；覆盖系统失败优先、同 ID verdict、unknown/ID 集失败、gate-report 先落盘、非 passed 不签发、journal/hash 链验签和拒绝自算 JSON 的机械测试。 +5. 用户批准 Gate A 预算后 real-run；通过后另批 Gate B 独立预算并执行。第一阶段不得实现 Shadow、confirm、Canonical 写入、章后抽取或父仓产品化回填。 + +**第二阶段：仅在 Gate B=`passed` 后启动。** + +6. 使用第一阶段已经实现的入口守卫实际启动细纲 real-run；必须提交由 `writer_gate.py` 签发并通过 journal/hash 链验证的 `writerGateBPassedReceipt`。细纲 dry-run 继续豁免。 +7. 接通 Shadow 三决策、confirm、Canonical 和异步抽取；按父仓 AI Orchestration、Integration Execution Facade、New-API 边界完成产品化，或先评审正式 ADR。 +8. 回填父仓设计、API 契约、schema 和索引，删除重复定义；任务完成后蒸馏并删除本文。 + +## 14. 实施前门禁 - 本修订版通过产品流程与技术合同两类独立评审。 - 用户确认本文为正文智能体实验台任务 SoT。 +- 第 11 节离线评测 adapter 未实现前，真实 `--execute` 保持失败关闭；设计评审通过不代表实现完成。 +- Gate A real-run 前，用户明确批准总预算、三类单次预算、最大调用次数和 raw 最长保留期。 +- Gate B real-run 前，按其样本集另行批准独立总预算、三类单次预算、最大调用次数和最坏总额。 +- writer、semantic detector、blind judge、oracleTruthPack、GateInputBuilder、Gate B receipt 签发器与细纲入口守卫的严格 schema、隔离、回执、路径安全、文件 CAS 和失败码均有机械测试证据。 +- Gate B 未通过，禁止实现或接入 Shadow/confirm/Canonical/章后抽取产品路径，禁止父仓产品化回填。 +- `writer_gate.py` 只为 passed Gate B 报告签发不可变 receipt；细纲 real-run 必须通过 journal/hash 链验签，拒绝自算 JSON；dry-run 明确豁免。 - 独立范式抽取继续运行，但不得与正文实现共享改动文件或进程。 - 细纲真实回放保持暂停，直到正文 Gate B 通过。