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 沉淀四样东西：
- agent 能力：写作/规划/抽取/检测的 prompt 按天迭代，达标版即未来 muse 智能体配置的种子；
- 元数据设计的实战修订：23 型 schema 在真实创作里用，字段缺什么、哪里别扭，写两章就暴露，改完回填 design-docs 与 W1 种子；
- 知识卡内容设计：知识库不模拟引擎（向量检索已在真环境证成），只打磨内容那一半——卡长什么样、检索回来怎么进上下文；
- （阶段二）真实 API 的使用反馈：哪只缺、哪只难用，即交付物。
二、两阶段
- 阶段一（现在）：纯文件 + git，无库无服务。产出可读的小说、schema 修订、达标 prompt。
- 阶段二（创作流稳定后）：同一套创作流换接真后端
/app-api（单人版 compose 按主仓 S9 收口已验证可从零起）。真 PG 在 infra、建表即主仓迁移 SQL、全用系统主账号调用——「要真表真 SQL」的要求由真后端天然满足，不拷库。
三、数据规则（三条）
- 人逐行读改的进文件：正文一章一个 md；每作品四个小文件（
设定.md、大纲.md、状态.md、装配.yaml）加一个带索引的知识卡目录。不按段落/场景拆文件。 - 运行噪音进
works/*/评审/：检测报告、评分、上下文包回显都在这，.gitignore 挡住——可看、可复跑、不入历史。 - 待审与确认交给 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)
五、一次续写怎么走
- 主会话读
装配.yaml（写作槽位绑了哪个写手、绑定了哪些公共库）； - 走
read-context组装上下文：设定与知识卡按 schema 的aiContext裁剪（如「结局方向」续写时不给）、近两章正文尾部、状态.md、本章细纲；被裁掉的字段记入回显，落评审/； - 写手产出整章，直接写进
manuscript/新章文件——不提交； - 检测/评委只读产出报告与评分，落
评审/； - 你读章 + 看报告：满意 → 走
confirmcommit；要改 → 提意见重生成；不要 → restore； - 确认后抽取员按 schema 从新章抽新实体/事件 → 知识卡（状态：草稿）落
知识/，与既有卡冲突时标冲突留你裁决；下次续写即可被读取器用上。
「角色卡长什么样」由 schema 声明——加一个字段，抽取与生成的产出立刻多这个字段，智能体一行不改；换绑写手只改 装配.yaml。这两条是「元数据驱动」的活体证明（场景 A7 专门验收）。
六、schema 设计稿公约
- 型名、两轴（domain×scope）、判据与专题-06 §4 严格对齐；字段是本仓先行草拟的实战设计稿（SoT 尚未给出逐型字段合同的部分由这里试出来）。
- 实战中的字段增删、判据修正 → 回填 design-docs 与 W1 种子后，在 schema 文件里标注「已回填@日期」。本仓不是字段定义的长期 SoT。
- 作品级扩展走
装配.yaml的「作品级扩展字段」，只增不改（对齐 base/override 机制）。
七、产品场景台账（对齐 产品-03，实验按真实产品旅程推进）
实验不走自造场景序，按 muse 的产品旅程走：管理员治理旅程（产品-03 §4）先备能力与全局资产，普通用户旅程（§2.2/§3 no-config 主线 + 增强路径）走创作闭环。市场、计费、个人中心不镜像，阶段二真后端承接。
管理线（管理员控制台旅程）
| # | 产品场景（SoT 锚） | 实验落法 | 判据锚 |
|---|---|---|---|
| G1 | 元结构治理：base schema 发布（§4.2） | meta/schemas/ 23 型种子与字段合同，发布=框架 commit |
字段全覆盖；发现回写「设计发现」 |
| G2 | 系统能力治理：功能链/槽位/默认件（§4.3） | 四槽位默认智能体 + read-context 保护流程 + confirm 封闭入口 | 保护节点不可被装配替换 |
| G3 | 全局知识治理：系统级拆书→授权（§4.4） | 参考书导入→拆书范式卡（草稿）→管理员确认（=commit）→作品侧凭绑定使用 | 范式卡脱敏带出处；未确认不授权 |
用户线（no-config 主路径 + 增强路径）
| # | 产品场景（SoT 锚） | 实验落法 | 判据锚 |
|---|---|---|---|
| U1 | 我的作品：新建作品（§3.2） | works/<书>/ 容器就位 |
容器合 novel_work 合同；确认随 U2 一并 commit |
| U2 | 规划旅程：候选→用户确认→正式规划（§3.5） | 设定包+大纲候选（未提交）→ 用户确认 | 未确认规划不进生成上下文 |
| U3 | AI 候选旅程：三决策（§3.4） | 续写候选 + 上下文回显 → 原样接受 / 修改后合并 / 丢弃 | 回显含裁剪清单；决策前 Canonical 零变化 |
| U4 | 知识确认旅程（§3.6） | 采纳后抽取→草稿→自动确认（自有正文+无冲突）/ 冲突入待确认队列 | 采纳正文≠确认知识；冲突必人工 |
| U5 | 增强·知识库绑定（§6.3） | 装配.yaml 绑 knowledge/范式/，用户确认生效 |
绑定≠写入；解绑即从上下文消失 |
| U6 | 增强·槽位替换（§5.3） | 换绑写手件，证「元数据驱动」 | 链与流程零改动，产出风格切换 |
| U7 | 导入解析旅程（§3.7） | 导入旧稿→解析分章→逐章审阅确认→知识草稿 | 解析结果先入待审；确认按章 |
| U8 | 导出交付（§3.8） | 编译全书正文+设定导出 | 导出走确认后内容，含来源标注 |
| — | 质量收敛（伴随 U3 循环，专题-04 简化） | judge 六维 + eval n=5 收敛，达标固化 golden/ |
评分有引文证据；≥4.0 达标 |
产品红线原样生效：候选决策只有三类（原样接受/修改后合并/丢弃）；采纳正文≠确认知识；未确认规划不进生成上下文；绑定≠写入；保护节点不可替换（§1.1-12）。
八、给 muse 的产出物清单
达标 prompt（→ 未来 agent_version.config 种子）；schema 修订（→ 专题-06/后端-04/W1 种子）；知识卡样式与上下文组装打法（→ 统一读取器 API 设计参考）；golden/ 样张与质量基线（→ 完整工程同场景对拍）；阶段二的 API 缺口清单。
九、当前阶段
阶段一。进度看 git log 与各作品 状态.md，不设过程状态文档。