muse-agent-example/README.md

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)

能力清单（公约：所有 API/工具能力一律封装为 skill，不散写一次性脚本、不裸调外部服务）

skill = 动手的（确定性工具能力，每只都是未来 muse API 的一道缝）——共 7 只：现有 3 + 按闭环步交付 4。

skill	做什么	对应 muse API 面	状态
read-context	统一读取器：读装配绑定→按用途+aiContext 三级裁剪→组装六分区上下文包→裁剪清单回显	统一创作数据读取器（专题-06 §7）	现有（文件版）；C4 升 PG 检索版（内部调 search）
confirm	唯一确认通道：确认=commit、丢弃=restore，仅创始人触发；PG 版加知识行草稿→已确认翻转	双轨提交 / 候选三决策入口	现有
eval	质量收敛环：n=5、每轮只动一个变量、达标固化 golden/	质量域	现有
db	muse-example 唯一数据库通道：ssh+容器 psql 封装（凭据按 db/连接信息.md），查询/DDL/DML 全走这，结果卡片式打印（=审查面）	数据访问层	A2 交付
import	导入解析：txt→回目正则静态分章→作品/章行入库（调 db）	导入解析旅程	B1 交付；C8 用户旧稿复用
embed	New-API 嵌入封装：Qwen3-Embedding-8B、dimensions:1024、--noproxy、批量+失败重试	AI 网关（嵌入）	B2 交付
search	向量检索：意图→embed→pgvector 相似度召回→授权过滤（仅已确认+已绑定）+字段裁剪→带相似度分的结果集	知识检索	B3 交付

skill 形态公约：每只 skill = SKILL.md（何时用+输入输出合同）+ scripts/*.py（封装好的确定性实现）。Python 3.12 + uv 管理的 .venv，依赖清单 requirements.txt（psycopg[binary] / requests / pyyaml / click），多用通用依赖不造轮子；PG 经 psycopg 直连（连通事实与凭据见 db/连接信息.md），New-API 调用禁系统代理（trust_env=False）；脚本失败原样报错不静默。现有三只流程型 skill（read-context/confirm/eval）以流程管控为主，涉库涉外步骤在 PG 版升级时同样下沉进脚本。

agent = 动脑的（LLM 判断力，达标 prompt 即未来 agent_version.config 种子）——共 5 个，全 opus，与 专题-06 §3 智能体三层清单 一一对应、无自造型：第一层开放槽位件 4 + 第二层保护节点件 1。

agent	SoT 身份（专题-06 §3 / 专题-03 §2.3）	做什么	用在
writer	一层 · 写作（Writing 槽位）	整章正文候选：2500–3500 字、AI 味黑名单零命中、新设定申报注释块；只进待审	C4
planner	一层 · 规划（规划链槽位）	设定包/大纲/细纲候选；字段全覆盖或标「字段存疑」；未确认不进后续生成上下文	C2
extractor	一层 · 拆书/分析（Analysis 槽位）	两用场：拆书（B2，按库内 schema 产知识行草稿+出处链；系统级只产抽象范式、不留原文）与章后抽取（C5）；冲突标「⚠ 冲突待裁决」不覆盖	B2 / C5
detector	一层 · 检测（Detection 槽位）	一致性/伏笔/设定违背检查，只产解释与定位落 评审/，不改正文与知识	C4 伴随
judge	二层 · 保护节点（质量门控与 LLM-Judge）——不可被装配替换，即 G2 判据的活体	六维 rubric 1–5 打分，引文证据制，≥4.0 达标	C6 / eval 内

SoT 第三层「知识基座」（检索/切块/入库，明文不是 app）在实验里即 skill 层（db/import/embed/search）——正好印证「所有 API/工具皆 skill」。分工判据：需要 LLM 判断的进 agent；确定性的取数、写库、外部调用、流程管控进 skill。agent 只经 skill 拿上下文与落库。

上下文组装结构（SoT=专题-03 §4 四层上下文 + 专题-06 §7 统一读取器；操作细节以 read-context skill 为准）

四层上下文(专题-03 §4.2;请求带 scenario 用途与授权语义)
├── Layer 0 当前输入   任务目标+本章细纲+当前文本 ——不可省略
├── Layer 1 近邻正文   上一章末尾场景原文+再前一章摘要+近期叙事状态 ——续写不可省略
├── Layer 2 作品事实   设定四节+正式规划+状态台账+知识卡(仅出场+关联) ——只读已确认(Canonical)
└── Layer 3 授权资料   绑定的公共范式库/全局知识 ——按场景可省;必须有绑定授权
预算顺序:先留输出预算 → L0 完整保留 → L1 优先 L2 优先 L3;超限先摘要化低层再截断
拼装顺序(物理序,与预算序是两回事,按稳定度递减):
  系统prompt → L2 作品事实 → L1 近邻正文 → L0稳定部(本章细纲/输出特化)
  → L3 授权资料(选卡每章变;PG 检索结果每回合随查询变,故不比作品信息稳)
  → L0易变部(用户本回合意图,绝对尾置)——前缀缓存命中最大化,指令尾置遵循度最优
裁剪回显(落 评审/,验收证据):字段级=aiContext 裁剪清单(专题-06 §7)
  + 来源级=omittedSources(原因枚举:token_budget/not_authorized/stale_source/low_confidence/not_relevant/blocked)

文件版落位：设定/大纲/状态/知识卡→L2，正文近邻→L1，装配绑定的公共范式→L3，派发指令与细纲→L0。三级裁剪=字段级 aiContext / 来源级 装配绑定 / 用途级 scenario。PG 版只改 L2/L3 取数方式（search 召回+授权过滤），层结构与回显合同不变。

按 agent 差异（骨架不变，差异=字段可见集×每层取数范围×层必省性；完整矩阵在 read-context skill）：writer 防剧透（底牌全闭、仅出场卡）；planner 看全局（唯一底牌全开+未来粗纲）；extractor 忠于原文（待拆章全文是处理对象、L3 关闭防诱导脑补）；detector 持有基准（知识全集+底牌开，专查提前泄底）；judge 最小独立（可见面≤writer、L3 关闭防拿范式放水）。矩阵为实验设计稿，验证后回填专题-03 §4。

五、一次续写怎么走

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 机制）。

七、产品场景台账（对齐 产品-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）。

完整闭环执行序（对齐稿 v2，2026-07-09，待创始人拍板）

创始人已拍：知识域先行（PG+向量插件为基座、以可见知识库数据为审查）、创作域后置。完整闭环 = 四阶段三回路：作品内环（生成→章后抽取→知识回库→供下一章）、元数据环（拆书/创作暴露的字段问题→修订 schema 种子→产出立刻变）、设计环（发现回填 design-docs 与 W1 种子）。

flowchart LR
  A[A 基座与元结构<br>建库·表映射·schema种子入库] --> B[B 全局知识生产<br>导入分章→拆书→检索→优化环]
  B --> G{B5 管理员确认+授权门}
  G --> C[C 创作域<br>建作→规划→绑定→续写三决策→导出]
  C -->|章后抽取→知识确认→回库| C
  B & C -->|字段/判据修订| A
  B & C -->|设计发现| D[D 回填design-docs<br>+阶段二换接真后端]

阶段A 基座与元结构（管理线 G1/G2）

#	场景锚	步骤	审查面	现状
A1（原K0）	基座	muse-example 建库+vector 插件；嵌入通道已实测（Qwen3-8B 默认 4096、dimensions:1024 生效）	psql 实测输出	未做，第一步
A2（原K1）	库表映射	主仓 sql/muse 摘录一致 DDL（meta / work·chapter / knowledge 三域）→应用；实验私货全进 example_* 前缀（嵌入边表 vector(1024)、tenant/creator 默认系统主账号=1）；交付 db 查询 skill	\dt + 表↔主仓迁移来源映射	未做
A3（原K2）	G1 元结构治理	23 型 YAML → meta 表行（=W1 种子演练）；此后拆书/抽取一律读库内 schema	schema/字段行卡片打印	YAML 就绪，入库未做
A4	G2 系统能力治理	四槽位默认智能体 + read-context/confirm/eval 保护流程	保护节点不可被装配替换	已就位（文件侧）；装配入库随阶段二

阶段B 全局知识生产（管理线 G3 主体；审查=可见知识库数据）

#	场景锚	步骤	审查面	现状
B1（原K3）	参考书导入+静态分章	import 工具（回目正则）→《封神演义》作品/章入库	作品/章行数+逐章抽查	12-14 回原文已备；全本未取
B2（原K4）	拆书智能体 PG 版	extractor 升级：按库内 schema 逐章拆→知识行(draft)+嵌入；13 张文件范式卡迁入作首批	知识行卡片打印+分型统计+出处链	文件版首轮已验（13 卡）；PG 版未做
B3（原K5）	检索验证	创作意图→相似度召回；授权与 aiContext 裁剪落查询层	检索结果+相关性人工评	未做
B4（原K6）	联合优化环	prompt × schema 字段 × 知识行质量，n=5 收敛	迭代前后对比+设计发现清单	未做
B5	G3 确认+授权门	管理员确认（状态草稿→已确认，=commit）→开放作品侧绑定	已确认行清单/授权台账	13 卡+档案停在此门

阶段C 创作域（用户线 no-config 主线+增强；创始人已拍后置，B5 过门后启动）

#	场景锚	步骤	审查面	现状
C1	U1 新建作品	作品实体入库（《焚忆》解封或新作）	作品行合 novel_work 合同	焚忆文件资产封存备用
C2	U2 规划确认	设定包+大纲候选→用户确认→正式规划	未确认规划不进生成上下文	焚忆候选已有（文件版）
C3	U5 绑定全局库	装配绑定已确认范式库，确认生效	绑定行；解绑即从上下文消失	装配暂存待确认
C4	U3 续写三决策	read-context 升 PG 检索版→候选→原样接受/修改后合并/丢弃	回显含裁剪清单；决策前 Canonical 零变化	文件版演练过一轮
C5	U4 知识确认旅程	章后抽取→草稿→自动确认（自有正文+无冲突）/冲突入待确认队列；新知识回库供下一章=作品内环闭合	采纳正文≠确认知识；冲突必人工	未做
C6	质量收敛（伴随 C4）	judge 六维+eval n=5，达标固化 golden/	评分有引文证据；≥4.0 达标	未做
C7	U6 槽位替换	换绑写手件，链与流程零改动	产出风格切换=元数据驱动活证	未做
C8	U7 用户导入解析	用户旧稿导入（复用 B1 工具）→逐章审阅确认→知识草稿	解析先入待审；确认按章	未做
C9	U8 导出交付	编译全书正文+设定导出	只含确认后内容，带来源标注	未做

阶段D 回填与换接（伴随各阶段，期末收口审计）

#	场景锚	步骤	审查面	现状
D1	设计环收口	设计发现回填 design-docs（专题-06/后端-04/W1 种子），本仓 schema 标「已回填@日期」	回填 commit 清单+两侧对读	9 条发现已归档在 schema 文件，未回填
D2	阶段二换接	同一创作流换接真后端 /app-api；沉淀 API 缺口清单	缺口清单	未启动

待拍板四点：① B2 首轮只拆 5 型范式 vs 加双层型公共面（建议先 5 型）；② 封神演义全本 100 回 vs 先 30 回（建议全本，静态分章要量大才见问题）；③ A2 口径=主仓表原样不改列、私货全进 example_*；④ 本闭环序整体确认——确认即从 A1 起跑，B5 前每阶段收口报一行。

八、给 muse 的产出物清单

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

九、当前位置（2026-07-09 快照）

• 执行主线已切知识域（§七 闭环序阶段 A/B），创作域（阶段 C）后置：《焚忆》设定包（27 文件）+第一章候选封存工作区、未提交，待 B5 过门后按 C 线走。
• 停在创始人手里的确认：① §七完整闭环序与四个待拍点；② B5/G3 确认门——13 张范式卡+参考书档案（extracted）未提交待确认；③《焚忆》装配的范式库绑定已暂存。
• 基座事实与凭据见 db/连接信息.md；muse-example 库与 vector 插件尚未创建（A1 第一步）。
• 进度惯例：看 git log 与各作品 状态.md，不设过程状态文档。