muse-agent-example —— muse 的创作实验台

• 版本：v3（2026-07-09，路线定版：文件创作台先行，真后端第二步；不再模拟数据库与知识库引擎）
• 仓库：独立 git，remote ssh://git@101.200.34.71:2222/zizi-al/muse-agent-example.git；本地物理上住在 oh-my-muse/ 下（父仓已 ignore），为的是就近引用 design-docs
• 概念权威：一律以 ../design-docs/（专题-06、架构-02）为准；这里发现设计不合用，回填那边，不在本仓自立定义

一、定位：不是迷你 muse

Claude Code 在这里只扮演一个角色：智能体运行时——真架构里这个位置本来就是可替换的外部运行时（专题-05 定义的那道缝）。它真写一部小说，验证面就是可读的作品内容。给 muse 沉淀四样东西：

1. agent 能力：写作/规划/抽取/检测的 prompt 按天迭代，达标版即未来 muse 智能体配置的种子；
2. 元数据设计的实战修订：23 型 schema 在真实创作里用，字段缺什么、哪里别扭，写两章就暴露，改完回填 design-docs 与 W1 种子；
3. 知识卡内容设计：知识库不模拟引擎（向量检索已在真环境证成），只打磨内容那一半——卡长什么样、检索回来怎么进上下文；
4. （阶段二）真实 API 的使用反馈：哪只缺、哪只难用，即交付物。

二、两阶段

• 阶段一（现在）：纯文件 + git，无库无服务。产出可读的小说、schema 修订、达标 prompt。
• 阶段二（创作流稳定后）：同一套创作流换接真后端 /app-api（单人版 compose 按主仓 S9 收口已验证可从零起）。真 PG 在 infra、建表即主仓迁移 SQL、全用系统主账号调用——「要真表真 SQL」的要求由真后端天然满足，不拷库。

三、数据规则（三条）

1. 人逐行读改的进文件：正文一章一个 md；每作品四个小文件（设定.md、大纲.md、状态.md、装配.yaml）加一个带索引的知识卡目录。不按段落/场景拆文件。
2. 运行噪音进 works/*/评审/：检测报告、评分、上下文包回显都在这，.gitignore 挡住——可看、可复跑、不入历史。
3. 待审与确认交给 git：智能体产出一律不提交，git diff 就是候选评审界面；确认 = commit（提交信息带来源），丢弃 = restore；git log 天然是采纳台账。

四、目录

agent-example/
├── CLAUDE.md                ← 会话章程:主会话只编排裁决;确认只能由用户触发
├── .claude/
│   ├── agents/              ← 动脑的:writer / planner / extractor / detector / judge
│   └── skills/              ← 动手的:read-context(组装上下文) / confirm(确认提交) / eval(质量收敛)
├── meta/schemas/            ← 23 型结构本体设计稿(对齐专题-06;README 有实例落点表)
├── knowledge/               ← 跨作品层:参考书原文 + 拆书产出的公共范式卡(绑定才进上下文)
└── works/<书名>/
    ├── 设定.md              ← 作品容器+作品核心+世界观总纲+文风画像(四节一文件)
    ├── 大纲.md  状态.md  装配.yaml
    ├── manuscript/          ← 正文,一章一个 md,frontmatter 按 chapter/scene 合同
    ├── 知识/                ← 本作品知识卡:人物/地点/势力/功法体系/物品/事件/关系 + 索引.md
    └── 评审/                ← 运行噪音(gitignored)

五、一次续写怎么走

1. 主会话读 装配.yaml（写作槽位绑了哪个写手、绑定了哪些公共库）；
2. 走 read-context 组装上下文：设定与知识卡按 schema 的 aiContext 裁剪（如「结局方向」续写时不给）、近两章正文尾部、状态.md、本章细纲；被裁掉的字段记入回显，落 评审/；
3. 写手产出整章，直接写进 manuscript/ 新章文件——不提交；
4. 检测/评委只读产出报告与评分，落 评审/；
5. 你读章 + 看报告：满意 → 走 confirm commit；要改 → 提意见重生成；不要 → restore；
6. 确认后抽取员按 schema 从新章抽新实体/事件 → 知识卡（状态：草稿）落 知识/，与既有卡冲突时标冲突留你裁决；下次续写即可被读取器用上。

「角色卡长什么样」由 schema 声明——加一个字段，抽取与生成的产出立刻多这个字段，智能体一行不改；换绑写手只改 装配.yaml。这两条是「元数据驱动」的活体证明（场景 A7 专门验收）。

六、schema 设计稿公约

• 型名、两轴（domain×scope）、判据与专题-06 §4 严格对齐；字段是本仓先行草拟的实战设计稿（SoT 尚未给出逐型字段合同的部分由这里试出来）。
• 实战中的字段增删、判据修正 → 回填 design-docs 与 W1 种子后，在 schema 文件里标注「已回填@日期」。本仓不是字段定义的长期 SoT。
• 作品级扩展走 装配.yaml 的「作品级扩展字段」，只增不改（对齐 base/override 机制）。

七、阶段一验收场景

#	场景	判据锚
A1	立项	作品目录四文件就位；git 待审/确认语义可演示
A2	规划：设定+人物+大纲	产出全部未提交；字段覆盖 schema；设定互相咬合（境界-势力-地理）
A3	首章续写	上下文回显含裁剪明细（aiContext 挡掉的字段、未绑定的库）；正文有 diff 无提交
A4	采纳/丢弃	commit 信息带来源；restore 干净；知识卡零新增（采纳正文≠自动确认知识）
A5	章后抽取	知识卡带来源（抽取@第N章）；冲突卡走人工裁决
A6	检测	只出报告与定位，正文与知识卡零变化
A7	元数据驱动性	schema 加字段→产出即变；换绑写手→流程零改动（全程不改 agent/skill）
A8	拆书	参考书入 knowledge/参考书/，范式卡脱敏带出处；绑定后 A3 可用、解绑即消失
A9	质量收敛	评委六维打分，n=5 收敛环迭代 prompt/schema；≥4.0 样张固化 golden/

八、给 muse 的产出物清单

达标 prompt（→ 未来 agent_version.config 种子）；schema 修订（→ 专题-06/后端-04/W1 种子）；知识卡样式与上下文组装打法（→ 统一读取器 API 设计参考）；golden/ 样张与质量基线（→ 完整工程同场景对拍）；阶段二的 API 缺口清单。

九、当前阶段

阶段一。进度看 git log 与各作品 状态.md，不设过程状态文档。