zizi abadaa15e9 框架: 正文评测链职责重构收口（writer/detector/judge 单一职责）+决策修复+加固门+探针刷新

- writer/detector/judge 按父仓专题-03/04 单一职责拆分：WriterDraft v2（仅 candidateBody）、CandidateEnvelope v2（adapter 确定性绑定）、SemanticDetection v3（quote 唯一匹配/unknown-gapReason）、blind judge v3（双盲第三评中位）；预算两层（启动预留=Σ plannedCalls×cap，修正旧 maxCalls×cap 的 $2250 阻断 bug）。

- 决策修复：补第六类混淆项「场景选择偏差」（集合级、只标注不改终态）；模型归属口径（planner/writer/judge 固定 opus，extractor/detector 可用它模型，拆书走 M3 不经角色派发）；eval 评分尺改链接+一句话引用 quality-gate。

- 加固执行门：探针合同绑定（probe.executionProfileSha256 须等于 writer profile 身份哈希），陈旧探针被机械阻断 EXECUTE_PROBE_CONTRACT_MISMATCH。

- 新增探针刷新工具 refresh_runtime_probe.py（可注入 invoker+失败关闭+重签同源 canonical_sha256），并已按新合同真实重测探针（绑定 9d319ea0，成本 $0.155）。

- 逐行复核后修复：省略号被当路径穿越误杀（claude_runtime 共用精确判定 contains_path_traversal，盲评/检测统一引用）；检测 failed 分支测试缺口；评委报告↔模型原始输出绑定恢复（reviewerStructuredOutputs，防一致篡改报告评分）；上下文 purpose 词汇两层对齐；盲评死代码清理。

- 全量离线测试约 800+ 项全绿（continuation/detect/quality-gate/read-context/replay-eval/parse-book 572/llm），不连库不调模型。

2026-07-25 04:44:10 +08:00

10 KiB

Raw Blame History

AGENTS.md —— agent-example 项目工作入口

适用范围：本文件只约束 agent-example/。父仓 ../AGENTS.md 的通用工程、证据和协作规则继续生效；本文件只补充创作实验仓的本地规则，不重复父仓规范。

1. 项目定位

agent-example 是物理位于 oh-my-muse 内、拥有独立 .git/ 的嵌套实验仓。它用真实创作、拆书、回放评测和候选审查验证 Muse 的智能体、元数据、知识卡与上下文合同，不是另一个 Muse 产品实现。

概念、产品和总体架构的单一事实来源（SoT）在 ../design-docs/；本仓发现设计问题后应回填父仓 SoT，不在本仓另立概念体系。
本仓当前运行数据主要在 PostgreSQL muse-example；仓内 knowledge/、docs/ 和 meta/ 是资产、合同或记录，不是业务运行数据的完整镜像。
仓内不存在 README 历史描述中的 works/ 主存储。任何仍以 works/<书>/... 为当前事实的说明，只能作为历史设计背景，不能据此读写不存在的路径。

2. SoT 与职责边界

SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面合同不一致时视为缺陷，不得自行拼接两套口径；本文件已经明确判定失效的旧路径，不因仍出现在历史文档或 skill 中而恢复有效。

载体	权威职责
`../AGENTS.md` + 本文件	父仓通用规则与本实验仓工作边界。更具体的本地规则只做收窄，不取消父仓规则。
`CLAUDE.md`	主会话、角色分工、模型使用、候选确认和提交纪律；其中 `works/*`、`装配.yaml`、`状态.md` 等文件式运行路径属于旧实现，不是当前执行入口。
`../design-docs/`	Muse 的概念、产品、业务和总体架构 SoT。
`meta/schemas/`	23 型结构本体的本仓设计稿与入库种子；运行时字段合同以 PostgreSQL 中经 `db` skill 读取的权威行为准，变更需保持种子与库内定义一致。
`meta/chains/`	scenario、purpose、功能 skill、角色槽位和保护节点的链路登记。
`.claude/skills/`	每个 `SKILL.md` 定义能力的输入、输出、红线和用法；同目录 `scripts/` 是确定性实现、机械门和自测入口。skill 内仍引用 `works/*` 的旧步骤不得执行，需迁移到 PostgreSQL 链路后才可恢复。
`docs/`	稳定任务 SoT、评测资料、样张和历史执行证据。只有被上级 SoT 或具体 skill 明确指定的文档，才是对应主题的 SoT；其余不代表运行态。
`README.md`	项目背景和历史路线概览。目录、阶段、技能数量和存储方式等描述可能陈旧，不得覆盖本文件、`CLAUDE.md`、`meta/`、skill 或磁盘事实。

docs/ 的稳定任务 SoT 使用不带日期的稳定名称，只描述创作者可见行为、agent 职责、可执行合同和验收边界。带日期文件只记录历史过程、运行证据、调试和当时待办，必须明确标注“非 SoT”，不得覆盖或重复稳定 SoT。若父仓 design-docs/ 已指定同一主题的唯一 owner，本仓 docs/ 只能引用，不得再立本地 SoT。

3. 真实目录与能力

agent-example/
├── .git/                   # 独立 Git 仓元数据
├── .claude/
│   ├── agents/             # 5 个 LLM 角色
│   └── skills/             # 21 个能力合同及其脚本
├── meta/
│   ├── schemas/            # 23 型结构设计稿与种子
│   └── chains/             # 功能链登记表
├── db/
│   ├── ddl/                # 可审计 DDL / 迁移文件
│   ├── 表映射.md
│   └── 连接信息.md
├── knowledge/              # 仓内参考资产；未经绑定、授权不得进入上下文
├── docs/                   # 设计、评测、样张与历史执行记录
├── .venv/                  # 本地 Python 运行环境
├── requirements.txt        # Python 依赖清单
├── CLAUDE.md               # 会话与角色章程
└── README.md               # 历史概览，不是当前运行态 SoT

5 个角色：writer、planner、extractor、detector、judge。角色身份在 .claude/agents/*.md，具体功能合同不复制进角色文件。

21 个技能按能力分组如下：

数据、模型与上下文：db、import、embed、search、llm、read-context。
流程与主权治理：confirm、eval、replay-eval。
清洗、拆解与知识：clean、parse-book、extract-knowledge、review-cards。
规划与写作：planning、fine-outline、continuation、rewrite、expansion、polish。
检测与质量门：detect、quality-gate。

当前上下文读取以 read-context 顶部登记的 PostgreSQL 可信读取链为准：固定检索计划 -> 卡索引 -> 按来源指针回读原文 -> 双证据组装 -> 冻结与回显。该 skill 后半段仍保留的 works/<书>/装配.yaml、状态.md、设定.md 和文件式回显步骤是迁移前设计稿，不是可执行路径；调用方不得回退到这些旧步骤。

4. 反序验证顺序

本仓优化与验证采用反序推进：

清洗 / 抽卡 / 范式
        ↓
正文智能体
        ↓
细纲智能体
        ↓
大纲 + 设定智能体

这是为了从底层证据与消费效果向上验证，不是正向生产调用顺序。不得把它改写成“大纲设定 → 细纲 → 正文”的实施进度，也不得因为某一层的单个样例可用，就宣称上层或整条创作链已经完成。

5. 创作与证据核心契约

卡是索引，不是原文替代。 卡用于定位实体、关系、来源和章号；生成或审查使用卡内历史事实前，必须沿 sourceRefs/sourceVersion/stateAsOf 回读冻结快照中的历史原文。
严格冻结。 所有历史原文、里程碑和窗口上界必须 <= asOf；目标章正文、目标章细纲答案、目标章出场清单及未来章、未来里程碑、终态摘要一律禁读。无法证明上界的来源按未知或省略处理。
双证据而非卡片灌入。 正文上下文以目标章前连续历史正文为基线，卡只触发补充原文回读；未经原文或正式设定、Canonical 状态、已确认细纲支持的卡内容不能单独成为事实证据。
正文按细纲执行。 细纲的硬事件、结果方向、伏笔动作、必须出场实体和章末钩子不可删除、反转或提前回收；缺细纲时停止，不由 writer 自编。
先审后入。 正文和规划先形成 Shadow 候选；机械门、语义检测或质量审查不通过时必须修订并以新候选版本重跑，不得绕过审查直接写入 Canonical。

6. 模型边界

清洗、抽卡、范式拆取及其模型调用统一走 llm skill，不裸调 New-API。治理政策固定为 5 小时额度窗：MiniMax 模型累计花费上限 $24，全模型成功调用上限 6000；机械事实源是 .claude/skills/llm/scripts/llm.py 及 test_quota.py，模型链切换必须由该 skill 治理并留下日志。
角色模型归属：planner/writer/judge 固定 opus；extractor/detector 可用其它模型（非必须降级）。拆书/导入侧抽取经 llm/parse-book skill 走 MiniMax-M3，不走角色 model 派发；创作期章后抽取作为角色派发，可用 opus。
确定性脚本、合同校验、快照冻结、泄漏审计和报告生成不调用模型；除非对应 SKILL.md 明确声明模型步骤，不得把机械任务升级为模型任务。
Claude 生成或评测只在对应任务 SoT、显式预算、固定执行配置和原文用途授权全部满足后运行；任一前置门失败都应关闭执行。
Claude 的模型别名、解析后的完整模型 ID、预算和回执必须与冻结配置一致。不得因模型不可用而静默换模型、换供应商或降低评测规格；需要变更时先取得明确授权并重新登记配置。

7. 数据与合规边界

主代理和业务 agent 不裸连 PostgreSQL 或 New-API。查询、写入和 DDL 走对应 skill 的 scripts/；专用导入、嵌入、检索也走各自 skill。
数据库写入、迁移、授权快照变更和批量运行必须先取得明确授权。DDL 先落 db/ddl/ 的审计文件，再通过 db skill 应用；不得用一次性直连命令绕过。
原书全文、历史正文证据和候选正文遵守 replay-eval 的授权、冻结和仓外临时目录边界。最终报告只保留评分、摘要、章节定位、失败类别和哈希，不复制原书全文、目标章全文、完整 Prompt/Response 或供应商原始响应。
未绑定、未授权、来源状态无效或超出用途范围的 knowledge/ 与数据库来源不得进入上下文；失败时明确记录 not_authorized、stale_source 等原因，不静默降级。

8. 候选、改动与提交

创作候选默认不提交。用户明确选择接受或修改后合并，且实时审查通过后，才可经 confirm 流程进入正式事实；丢弃也必须针对用户明确指定的候选。
框架改动与创作内容分开审查、分开提交。不得把 agents、skills、meta、脚本改动和正文、规划、知识卡候选混在同一提交。
不覆盖、不还原、不暂存其他工作者或用户已有改动。执行前后都要核对真实 diff，只处理当前授权范围。

9. 评测结论与验证入口

明确区分已验证事实、推断和假设。报告必须给出证据来源；没有机械输出或运行证据时，不声称完成、修复或通过。
禁止从 n=1 样本推出普适结论。至少分析假阴、假阳、样本偏差和混淆因素；需要判断卡或模型效果时使用同任务、同模型、同预算、同公共上下文的对照，并把不稳定样本排除在方向结论之外。
Python 一律使用仓内解释器 .venv/bin/python。先读目标 skill 的 SKILL.md，再运行其已存在的相关自测；例如：

.venv/bin/python .claude/skills/fine-outline/scripts/test_contract.py
.venv/bin/python .claude/skills/llm/scripts/test_quota.py
.venv/bin/python .claude/skills/read-context/scripts/test_writer_contract.py
git diff --check

只运行与改动和风险相关的检查。测试涉及真实 PostgreSQL、New-API、Claude 或原文时，先核对授权、预算和副作用；不能把离线自测通过表述为真实链路通过。

10 KiB Raw Blame History Unescape Escape