e36cd57010
【评测合同与提示词】 - writer/detector/judge 评测提示词去支架化：删评测身份/输出格式叮嘱/盲化反向叮嘱/机器字段 （改由运行时 --json-schema/--tools ""/--strict-mcp-config/输入设计强制），装回各角色本业纪律 - writer 加写作纪律：戏剧化节拍禁抄细纲概述句、具体压倒抽象、每场戏三件套、篇幅用场景写够不注水不缩水 - 篇幅自纠环修订指令区分偏短（加场景）/偏长（删冗余）；机械门要求清单（章末钩子/硬事件/角色/伏笔）注入写手硬约束 - 引文校验从「必须恰好1次」放宽为「0次失败关闭、≥1次绑首次」（检测+盲评同口径） - llm 立 chat_governed 为主入口（chat 降为仅调试），clean_detect 改用 chat_governed 弃自带降级链 - rewrite/expansion/polish 输出合同对齐 writer.md（返回文本、写手不读写工作区、主会话落工作区） - 修复 confirm/replay-eval 探针两组坏自测（夹具适配现行合同、探针测试自包含不硬编码漂移哈希）；补 clean_detect 离线测试 - AGENTS.md 新增 §10「Agent 提示词与 Skill 审查标准」 【skill 三层重组：单向依赖 底座→能力→编排，断两环+修生产倒挂】 - Phase 0: 新建 runtime 底座（claude_runtime/file_cas/raw_vault），断环 C1、修 continuation 生产倒挂 - Phase 1: 评分尺+门判（writer_rubric/fine_outline_rubric/writer_gate/gate_input_builder）收进 quality-gate，断环 C2、名实相符 - Phase 2: 升格管线从 parse-book 独立成 upgrade skill（备份审计契约键名稳定、仅改路径定位） - Phase 3: replay-eval 瘦成纯编排 - read-context 共用簇（build_snapshot/audit_leakage/check_snapshot/load_reference_work）下沉到新 snapshot skill，消除能力层向上引用 - Phase 4: run_writer_replay.py（130KB）拆成包（_common/budget/authorization/sample/blind/execute），__init__ 全量 re-export 测试零改动 【base 配置】三角色 effort 提 high；提示词更新；探针重测绑定 writer 合同；预算 writer 45 次/总 450 美元（含篇幅修订） 全量离线测试 36 个文件全绿；函数逻辑零改动（仅搬位置/改 import/改文档，capture_code_identity 仅改路径定位）。
153 lines
14 KiB
Markdown
153 lines
14 KiB
Markdown
# AGENTS.md —— agent-example 项目工作入口
|
||
|
||
> 适用范围：本文件只约束 `agent-example/`。父仓 [`../AGENTS.md`](../AGENTS.md) 的通用工程、证据和协作规则继续生效；本文件只补充创作实验仓的本地规则，不重复父仓规范。
|
||
|
||
## 1. 项目定位
|
||
|
||
`agent-example` 是物理位于 `oh-my-muse` 内、拥有独立 `.git/` 的嵌套实验仓。它用真实创作、拆书、回放评测和候选审查验证 Muse 的智能体、元数据、知识卡与上下文合同，不是另一个 Muse 产品实现。
|
||
|
||
- 概念、产品和总体架构的单一事实来源（SoT）在 [`../design-docs/`](../design-docs/)；本仓发现设计问题后应回填父仓 SoT，不在本仓另立概念体系。
|
||
- 本仓当前运行数据主要在 PostgreSQL `muse-example`；仓内 `knowledge/`、`docs/` 和 `meta/` 是资产、合同或记录，不是业务运行数据的完整镜像。
|
||
- 仓内不存在 README 历史描述中的 `works/` 主存储。任何仍以 `works/<书>/...` 为当前事实的说明，只能作为历史设计背景，不能据此读写不存在的路径。
|
||
|
||
## 2. SoT 与职责边界
|
||
|
||
SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面合同不一致时视为缺陷，不得自行拼接两套口径；本文件已经明确判定失效的旧路径，不因仍出现在历史文档或 skill 中而恢复有效。
|
||
|
||
| 载体 | 权威职责 |
|
||
|---|---|
|
||
| [`../AGENTS.md`](../AGENTS.md) + 本文件 | 父仓通用规则与本实验仓工作边界。更具体的本地规则只做收窄，不取消父仓规则。 |
|
||
| [`CLAUDE.md`](CLAUDE.md) | 主会话、角色分工、模型使用、候选确认和提交纪律；其中 `works/*`、`装配.yaml`、`状态.md` 等文件式运行路径属于旧实现，不是当前执行入口。 |
|
||
| [`../design-docs/`](../design-docs/) | Muse 的概念、产品、业务和总体架构 SoT。 |
|
||
| [`meta/schemas/`](meta/schemas/) | 23 型结构本体的本仓设计稿与入库种子；运行时字段合同以 PostgreSQL 中经 `db` skill 读取的权威行为准，变更需保持种子与库内定义一致。 |
|
||
| [`meta/chains/`](meta/chains/) | scenario、purpose、功能 skill、角色槽位和保护节点的链路登记。 |
|
||
| [`.claude/skills/`](.claude/skills/) | 每个 `SKILL.md` 定义能力的输入、输出、红线和用法；同目录 `scripts/` 是确定性实现、机械门和自测入口。skill 内仍引用 `works/*` 的旧步骤不得执行，需迁移到 PostgreSQL 链路后才可恢复。 |
|
||
| [`docs/`](docs/) | 稳定任务 SoT、评测资料、样张和历史执行证据。只有被上级 SoT 或具体 skill 明确指定的文档，才是对应主题的 SoT；其余不代表运行态。 |
|
||
| [`README.md`](README.md) | 项目背景和历史路线概览。目录、阶段、技能数量和存储方式等描述可能陈旧，不得覆盖本文件、`CLAUDE.md`、`meta/`、skill 或磁盘事实。 |
|
||
|
||
`docs/` 的稳定任务 SoT 使用不带日期的稳定名称，只描述创作者可见行为、agent 职责、可执行合同和验收边界。带日期文件只记录历史过程、运行证据、调试和当时待办，必须明确标注“非 SoT”，不得覆盖或重复稳定 SoT。若父仓 `design-docs/` 已指定同一主题的唯一 owner，本仓 `docs/` 只能引用，不得再立本地 SoT。
|
||
|
||
## 3. 真实目录与能力
|
||
|
||
```text
|
||
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. 反序验证顺序
|
||
|
||
本仓优化与验证采用反序推进：
|
||
|
||
```text
|
||
清洗 / 抽卡 / 范式
|
||
↓
|
||
正文智能体
|
||
↓
|
||
细纲智能体
|
||
↓
|
||
大纲 + 设定智能体
|
||
```
|
||
|
||
这是为了从底层证据与消费效果向上验证，不是正向生产调用顺序。不得把它改写成“大纲设定 → 细纲 → 正文”的实施进度，也不得因为某一层的单个样例可用，就宣称上层或整条创作链已经完成。
|
||
|
||
## 5. 创作与证据核心契约
|
||
|
||
1. **卡是索引，不是原文替代。** 卡用于定位实体、关系、来源和章号；生成或审查使用卡内历史事实前，必须沿 `sourceRefs/sourceVersion/stateAsOf` 回读冻结快照中的历史原文。
|
||
2. **严格冻结。** 所有历史原文、里程碑和窗口上界必须 `<= asOf`；目标章正文、目标章细纲答案、目标章出场清单及未来章、未来里程碑、终态摘要一律禁读。无法证明上界的来源按未知或省略处理。
|
||
3. **双证据而非卡片灌入。** 正文上下文以目标章前连续历史正文为基线，卡只触发补充原文回读；未经原文或正式设定、Canonical 状态、已确认细纲支持的卡内容不能单独成为事实证据。
|
||
4. **正文按细纲执行。** 细纲的硬事件、结果方向、伏笔动作、必须出场实体和章末钩子不可删除、反转或提前回收；缺细纲时停止，不由 writer 自编。
|
||
5. **先审后入。** 正文和规划先形成 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`，再运行其已存在的相关自测；例如：
|
||
|
||
```bash
|
||
.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. Agent 提示词与 Skill 审查标准
|
||
|
||
新增、修改或定期复核任何 agent 提示词、skill 时，按本节逐条审。总原则：**一份提示词、一个 skill 只服务一个明确意图；与意图无关的词、约束、机制都是污染——它让执行者分心，也让合同两张皮。**
|
||
|
||
### 10.1 Agent 提示词（`.claude/agents/*.md` 与角色系统提示词）
|
||
|
||
逐条问四个问题：
|
||
|
||
1. **面对谁**：这份提示词读给哪个模型/角色？它只该有这一个身份，不该同时背「执行器/评测器/审查器」之类第二身份。
|
||
2. **每个词都有意义吗**：逐词问——它对「这个角色干好本业」有用吗？框架名、schema 名、字段名、运行身份、哈希、评测状态这类机器词，对创作/规划/抽取/检测等本体任务毫无意义，是其它层的泄漏，应删。
|
||
3. **约束是该有的限制吗**：每条约束问——它是角色意图本身需要的，还是支架（harness）本就能强制的？**输出格式**由结构化输出 schema 强制、**工具可用性**由调用参数强制、**盲化**由「输入里压根没有该信息」保证——这些都不该写进提示词反复叮嘱。提示词只留角色凭自身判断必须遵守的约束。
|
||
4. **正向与负向**：分清哪些部分**帮**角色达成意图（正向：本业纪律、领域边界、知情范围），哪些**妨碍**它（负向：与本业无关的机器约束、诱导照搬输入原文的措辞、让模型惦记评测的暗示）。负向部分删除或移到它该在的层。
|
||
|
||
> 反例（已纠正）：评测写手提示词曾塞入「你是 Gate A 离线回放的 writer…只输出 candidateBody…不输出哈希/身份…不访问 MCP」，把评测支架混进创作提示词——既没有写作指导，又诱导写手照抄细纲概述句。正解：提示词只讲怎么写好，输出格式与盲化交给 schema 和输入设计。
|
||
|
||
### 10.2 Skill（`.claude/skills/*/`）
|
||
|
||
逐条问五个问题：
|
||
|
||
1. **给谁用**：主会话编排？某角色 agent？还是别的 skill？消费者必须明确、单一。
|
||
2. **目的单一**：一个 skill 只实现一个能力。功能并列、又当编排又当执行的，拆。
|
||
3. **可靠性与稳定性**：失败是否明确失败关闭（不静默降级、不返回假成功）？错误是否带稳定码、不泄漏原文/密钥？有无离线自测覆盖关键路径与失败路径？确定性步骤是否真不调模型？
|
||
4. **符合 skill 规范**：`SKILL.md` 是否清楚定义输入、输出、红线、用法？`scripts/` 是否其确定性实现与自测入口？是否走 `.venv`、不裸调 PG/New-API/模型？
|
||
5. **边界一致**：引用的路径、合同、字段是否与现行 SoT（本文件、`meta/`、库内权威行为）一致？引用已失效旧路径（如 `works/*` 文件式步骤）的不得执行。
|
||
|
||
### 10.3 审查产出
|
||
|
||
每次审查对每个被审对象给出：**面对谁 / 目的**、**逐条问题**（正向资产 + 负向污染，各标严重度）、**具体修改建议**。审查只读、不改代码；修改另起授权，框架改动与创作内容分开提交。
|