框架: 领域设计权威改订为数据库，立一切落库合同，新增只读可视化模块合同
- 八个领域 SoT + 索引：正式内容权威从 Git 文件改为 PostgreSQL；Git 退回代码/文档/DDL 权威，可对作品信息与文本留痕但非权威。 - 立横切合同：一切输入产出必须落库可见；raw 进库可看全文（访问控制）。 - 08 更名为数据权威与可视化领域；新增独立 可视化模块合同（只读查库渲染，绝不写）。 - AGENTS.md / README.md 同步翻面。
This commit is contained in:
zizi
parent
e36cd57010
commit
4adc85cafd
5
.agent/_index.md
Normal file
5
.agent/_index.md
Normal file
@ -0,0 +1,5 @@
|
||||
# agent-example 长期知识索引
|
||||
|
||||
- [项目长期文档](docs/_index.md)
|
||||
|
||||
项目入口与协作规则仍由根目录 [`AGENTS.md`](../AGENTS.md) 拥有；本目录只保存跨任务稳定知识。
|
||||
3
.agent/docs/_index.md
Normal file
3
.agent/docs/_index.md
Normal file
@ -0,0 +1,3 @@
|
||||
# 长期文档索引
|
||||
|
||||
- [架构](architecture/_index.md)
|
||||
3
.agent/docs/architecture/_index.md
Normal file
3
.agent/docs/architecture/_index.md
Normal file
@ -0,0 +1,3 @@
|
||||
# 架构文档索引
|
||||
|
||||
- [单用户本地优先领域设计](domains/_index.md)
|
||||
91
.agent/docs/architecture/domains/01-作品领域.md
Normal file
91
.agent/docs/architecture/domains/01-作品领域.md
Normal file
@ -0,0 +1,91 @@
|
||||
# 作品领域 SoT
|
||||
|
||||
> 数据权威：本领域的正式内容（Canonical）以 PostgreSQL `muse-example` 库为唯一事实源；Git 只管代码、Skill、文档与 DDL，不再是正式内容权威。横切合同（一切输入产出必须落库才能被看见）见[领域设计索引](_index.md) §3，本领域只引用、不重复定义。
|
||||
|
||||
## 1. 唯一职责
|
||||
|
||||
作品领域拥有一部小说作为创作项目的身份、规划、正式正文、作品级状态、用户决策记录，以及其他领域产物在作品内的归档关系。它回答“正在写哪部作品、正式内容是什么、下一步写什么、哪些决策已经由用户确认”。决策本身意味着什么（接受、合并、丢弃各改变什么）由创作流程领域定义，本领域拥有决策记录的存储与可追溯。
|
||||
|
||||
作品领域不拥有实体详细事实、跨作品范式、审核/实验结果语义、Agent 定义、Skill 实现、运行回执字段合同或库内检索加速。`reviews`、`experiments`、`runs` 在库内挂在作品名下只是为了完整归档：审核与实验的 schema 与终态由质量与复利领域拥有，运行回执（`runs`）的字段合同由数据权威与可视化领域拥有，本领域只声明它们与作品的归档关系。
|
||||
|
||||
## 2. 数据合同
|
||||
|
||||
作品的正式内容权威是 PostgreSQL（`muse-example` 库）里的三张表：
|
||||
|
||||
| 库表 | 承载 |
|
||||
|---|---|
|
||||
| `muse_content_work` | 作品行：身份、状态、规划引用、绑定 |
|
||||
| `muse_content_chapter` | 章行：章序、标题、章级状态 |
|
||||
| `muse_content_block` | 正文块：正文整章存 `content_text` 列 |
|
||||
|
||||
字段权威由 `meta/schemas/`（`work_core`、`novel_work`、`outline`、`chapter`、`style` 等）加上对应库表共同定义。作品身份、状态、规划、正文、用户决策、运行回执都在库里。一切输入产出必须落库才能被看见，这条横切合同见[领域设计索引](_index.md) §3。
|
||||
|
||||
正式内容以库行为准，不再要求 `work.yaml`、`settings/*.md` 这类文件形态。
|
||||
|
||||
## 3. 作品行字段合同
|
||||
|
||||
`muse_content_work` 一行只保存静态身份和必须由人判断的字段：
|
||||
|
||||
- `schema_version`：字段合同标识，当前为 `work-file-v1`
|
||||
- `work_id`
|
||||
- `slug`
|
||||
- `title`
|
||||
- `category`
|
||||
- `status`：`draft | writing | paused | completed`
|
||||
- `created_at`
|
||||
- `next_action`
|
||||
- `entity_root`：指向库内该作品的实体集合，由实体领域拥有（见 [02-实体领域](02-实体领域.md)）
|
||||
- `pattern_bindings`：绑定的范式范围或明确 ID
|
||||
|
||||
章节数、字数、最后章号、审核前沿、库内检索加速版本等派生量不写进作品行，必须从库内正文、审核结果或状态机械计算，不做手工镜像。
|
||||
|
||||
## 4. 正文与候选边界
|
||||
|
||||
- 正式正文 = 库内正文块（`muse_content_block`）：只保存用户手写保存、原样接受或修改后合并后的内容。
|
||||
- AI 产出默认不可信，先落库为待审候选（Shadow），不触碰正式正文。
|
||||
- 完整候选正文属于 raw，按 raw 边界进库（单独表 + 访问控制），只读看板可看全文；raw 的存储与访问控制合同见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
|
||||
- 接受或合并时必须校验候选版本、正文哈希、当前正式正文 revision 和来源状态，全部通过后才写库；任一失败不得写正式正文。
|
||||
- 丢弃候选不修改正式正文、实体或范式。
|
||||
- 每次接受/合并/丢弃对应的运行回执随候选归档到作品名下；回执的字段合同见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)，本领域只声明归档关系。
|
||||
|
||||
实现边界：作品、章、正文经 import 已落库，接受的前置校验为纯函数、已可用。目标合同还差三处落库写入——写正式正文、决策记录、运行回执；在正式正文落库写入层建成前，正式正文的写回暂由人工提交兜底，属临时通道，不是合同形态。
|
||||
|
||||
## 5. 规划与状态
|
||||
|
||||
- 规划（总纲、卷纲、章级细纲）候选先落库为待审候选，用户确认后才入库成为正式规划。
|
||||
- 进度状态在库内记录下一步、伏笔承接和阶段目标，不复制正文可推导的统计。
|
||||
- 叙事状态在库内只保存作品级状态或对实体状态的引用；人物、地点、事件等详细事实由实体领域拥有。
|
||||
- 章数、字数、前沿等派生量机械计算，不入库做手工镜像。
|
||||
- 用户接受正文不自动确认知识或实体变化。正文保存后可以异步生成实体草稿，仍需确认。
|
||||
|
||||
## 6. 生命周期
|
||||
|
||||
```text
|
||||
draft -> writing -> paused -> writing -> completed
|
||||
```
|
||||
|
||||
状态只描述作品生命周期，不表达章节审核或发布状态。章节的正式性由其是否为库内正式正文块以及 revision 记录决定。
|
||||
|
||||
> 注：本生命周期用 `draft/writing/paused/completed`，而部分 schema 用“筹备/连载/完结”，两套状态词待对齐。
|
||||
|
||||
## 7. 可恢复性
|
||||
|
||||
作品的可恢复性（数据库备份、快照、可重建脚本，配合 Git 里的代码与 DDL 从零重建库结构）见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
|
||||
|
||||
## 8. 验收条件
|
||||
|
||||
1. 一部作品的身份、规划、正式正文、用户决策都能从 `muse-example` 库查出，不依赖任何文件。
|
||||
2. 库内正式正文与待审候选隔离：候选不被当作正式正文返回；丢弃候选后，正式正文逐字节不变。
|
||||
3. 章节数、字数、前沿等派生量不在库内手工镜像；从正文机械重算，两次结果一致。
|
||||
4. 用户决策、正文 revision、审核结果在库内可追溯。
|
||||
5. 接受/合并校验（候选版本、正文哈希、正式正文 revision、来源状态）任一失败时，库内正式正文不发生写入。
|
||||
6. 作品的每个输入产出都已落库，只读看板能据此渲染出作品全貌，不读取任何库外数据。
|
||||
7. `reviews`、`experiments`、`runs` 不在作品领域重复定义结果 schema 或终态。
|
||||
|
||||
## 9. 关联 SoT
|
||||
|
||||
- 领域总览与横切合同：[领域设计索引](_index.md)
|
||||
- 实体事实：[02-实体领域](02-实体领域.md)
|
||||
- 正向创作与决策语义：[05-创作流程领域](05-创作流程领域.md)
|
||||
- 数据权威、raw 进库、运行回执字段合同与可恢复性：[08-数据权威与可视化领域](08-数据权威与可视化领域.md)
|
||||
- Shadow/Canonical 上级合同：[架构-02](../../../../../design-docs/架构-02-核心数据结构与双轨模型.md)
|
||||
133
.agent/docs/architecture/domains/02-实体领域.md
Normal file
133
.agent/docs/architecture/domains/02-实体领域.md
Normal file
@ -0,0 +1,133 @@
|
||||
# 实体领域 SoT
|
||||
|
||||
## 1. 唯一职责
|
||||
|
||||
实体领域拥有单部作品内可被稳定引用的正式事实（Canonical），包括人物、关系、事件、地点、物品、组织、能力体系、世界规则和叙事状态。它回答“作品世界中有哪些对象、对象之间是什么关系、截至某章哪些事实成立”。
|
||||
|
||||
实体领域不拥有正文、规划、跨作品写作范式、模型候选或评测分数。
|
||||
|
||||
实体就是库里的一行，不是文件。正式内容权威是 PostgreSQL（`muse-example` 库）：未确认的叫待审候选（Shadow），确认后才成为正式内容。数据权威的总原则见 [领域索引](./_index.md) §2。
|
||||
|
||||
## 2. 数据合同
|
||||
|
||||
实体的“长什么样”由两处共同决定，实体领域不另行复制字段：
|
||||
|
||||
- **型（有哪些实体类型、各型有哪些字段）**：由 `meta/schemas/` 拥有。本领域承认九个实体型：`character`、`character_relation`、`event`、`location`、`item`、`faction`、`power_system`、`world`、`narrative_state`。
|
||||
- **存放（字段落在哪张库表）**：由库表拥有。草稿落 `muse_knowledge_draft`，已确认落 `muse_knowledge_entity`（关系另有 `muse_knowledge_relation`）。每个实体的可变业务字段放在该行的 JSONB `payload` 里，型决定 payload 里允许有哪些字段。
|
||||
|
||||
一句话：**型看 `meta/schemas/`，字段权威 = `meta/schemas/` 的九型 + 库表**。本文件只描述实体合同，不复制九型的字段清单。
|
||||
|
||||
## 3. 最小实体合同
|
||||
|
||||
一个实体在库里至少要能被这几个字段说清楚（字段名留英文，含义当场白话）：
|
||||
|
||||
| 字段 | 含义 |
|
||||
|---|---|
|
||||
| 稳定 `id` | 作品内唯一，且**不因改名而变化** |
|
||||
| `type` | 实体型，必须落在九型之一 |
|
||||
| `status` | 生命周期状态（见下） |
|
||||
| 时态 | 该事实从第几章起成立、到第几章止 |
|
||||
| `revision` | 第几次被用户确认修改 |
|
||||
| 来源 | 回到正式正文、已确认设定或已确认规划的位置与内容哈希 |
|
||||
|
||||
状态的目标合同是三态：
|
||||
|
||||
- `draft`：草稿，未确认，不进正式上下文。
|
||||
- `canonical`：正式事实。
|
||||
- `retired`：已退役，不再作为当前事实参与，但保留记录。
|
||||
|
||||
> 现状标注：库里实际用的状态名是草稿表 `pending / confirmed / ignored` 加正式表 `active`，与设计三态 `draft / canonical / retired` 不是一一对应。**实现状态名与设计三态待对齐**，对齐前以库内实际状态为准、以本节为目标。
|
||||
|
||||
约束：
|
||||
|
||||
- `id` 在作品内稳定，改名不换 id。
|
||||
- `type` 必须是 `meta/schemas/` 已登记的九型之一。
|
||||
- 只有用户确认或正式正文支持的事实才能成为正式内容；草稿不得静默进入后续正式上下文。
|
||||
- 来源要能回到不可变位置和内容哈希，不能只写“某章某段”。
|
||||
- 会随剧情变化的事实必须带生效章区间，不能用终态覆盖历史时点。
|
||||
|
||||
## 4. 实体与作品关系
|
||||
|
||||
- 作品侧只引用实体 `id`，不复制实体的详细字段。
|
||||
- 作品级设定可以定义创作边界和主题，但不得成为人物、地点、事件的第二事实源。
|
||||
- 正文保存或候选接受后可以产生实体草稿；**草稿不进入后续正式上下文**。
|
||||
- 草稿到正式是一次**库内状态流转**：由用户确认（`confirm`）把草稿从 `pending` 翻成 `confirmed`，并落出正式表 `active` 行、`revision` 加一。没有用户确认，草稿不会自己变正式。
|
||||
- 实体的演进历史由库与 Git 共同留痕（库留当前合同与必要时态区间，Git 留 DDL、代码与变更历史），不在实体行里另写一份不可校验的历史叙述副本。
|
||||
|
||||
## 5. 拆书与知识草稿入口
|
||||
|
||||
本项目不只写自己的书，也拆别人的书：把参考书导入、分章、解析，抽出可复用的知识，经审核形成知识草稿。这条链的一个落点就是实体领域——参考书里的人物、关系、设定可以成为本作品的实体草稿。
|
||||
|
||||
- 参考书导入后先分章解析，解析结果是待审候选，不是正式事实。
|
||||
- 解析结果经审核、再由用户确认，才成为实体草稿并最终落库为正式实体；和从正文产生的草稿走**同一条确认链**，不因来源是参考书而跳过确认。
|
||||
- 拆书得到的“写法经验”不落实体领域，归范式领域，见 [03-范式领域](03-范式领域.md)。
|
||||
- 参考书全文按 raw 规则**进库**（单独表加访问控制，只读看板可看全文），不再留仓外，见 [领域索引](./_index.md) §8。
|
||||
|
||||
## 6. 作品面实体入库管线（本领域拥有）
|
||||
|
||||
这一节归实体领域拥有。它把参考书里的人物、关系卡抽进库的正式层，是一条确定性管线：
|
||||
|
||||
- **抽取**：从参考书解析结果里抽出人物卡、关系卡，写入草稿表。
|
||||
- **别名判重**：同一人物在不同书里叫法不同，按别名归并到同一实体，避免一人多卡。
|
||||
- **跨窗出场留档**：人物在长篇里分窗（按窗口切分的大段）出现，逐窗记录其出场与状态变化，留作证据。
|
||||
- **覆写审计**：每次抽取或覆写都留痕，能追溯“这条卡是谁、何时、依据哪段原文写进来的”。
|
||||
- **灾备导出**：正式层可导出，配合数据库备份用于恢复。
|
||||
- 参考作品的授权与来源以授权快照表为准（`db/ddl/96-example参考作品授权快照.sql`）。
|
||||
|
||||
> 注意区分两个“升格”：本节是**作品面实体升格**——把参考书的人物/关系抽进库的正式层。06 质量与复利领域的“经验升格”是另一件事——把写法经验从写法→范式→Skill 逐级固化。两者只是都叫“升格”，对象和去向完全不同，不要混为一谈。作品面升格对应实现：upgrade skill 加 `db/ddl/94-example作品面升格.sql`。
|
||||
|
||||
## 7. 关系与状态
|
||||
|
||||
- 关系作为独立实体，引用两端实体 `id`，并带方向、关系类型、有效章区间和来源。
|
||||
- 事件记录参与者、发生章、结果和来源，不把正文摘要当作完整事实。
|
||||
- 叙事状态（`narrative_state`）保存可变状态，如位置、持有物、知情范围、伤势和关系阶段；状态必须能按“截至某章”（`as_of`）重建。
|
||||
- 无法证明章号或来源的状态只能标为草稿或省略，不能推断成正式事实。
|
||||
|
||||
> 现状标注：叙事时态目前用“演变历程”的双层模型表达（一条当前态加一条演变记录），与设计里的 `valid_from / valid_to_chapter` 章区间并存。**两套时态表示待对齐**，对齐前两者都承认、以库内实际为准。
|
||||
|
||||
## 8. 检索
|
||||
|
||||
实体检索 = 库内查询 + 库内检索加速（向量）。
|
||||
|
||||
- 按 `id`、名称、别名、型、章号过滤，直接在库里查。
|
||||
- 语义召回走库内检索加速（pgvector 向量索引），它只是数据库一侧的加速，不是独立权威，可从库重建。
|
||||
- **命中后回读库行并校验内容哈希**，确认拿到的是库里当前正式行——不是回读任何文件。
|
||||
- 检索加速失败只影响速度，不改变实体内容语义、不跳过审核。
|
||||
|
||||
## 9. 验收条件
|
||||
|
||||
1. 任一正式实体都能回到库内来源行，并经内容哈希校验一致。
|
||||
2. 同一事实只有一个 owner 行，不要求同时维护 Markdown 与 JSON 两份人工事实。
|
||||
3. 按目标章冻结上下文时，不会读取该章之后才成立的状态。
|
||||
4. 实体草稿不会静默进入正式创作上下文（可机械验证：未被用户确认的草稿不出现在冻结的正式上下文里）。
|
||||
5. 参考书导入产生的实体草稿与正文产生的实体草稿走同一条确认链（可机械验证：两类草稿的确认都经 `confirm` 触发、都产生正式表行）。
|
||||
6. 向量召回命中后回读的是库行而非文件（可机械验证：命中结果带库行 id 与内容哈希，且哈希与库一致）。
|
||||
7. 作品面入库管线的每一次覆写都有审计记录，可追到来源原文。
|
||||
8. 可恢复性（库损坏后能否重建）见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
|
||||
|
||||
## 10. 关联 SoT
|
||||
|
||||
- 类型结构：[`meta/schemas/`](../../../../meta/schemas/README.md)
|
||||
- 数据权威与可恢复性：[08-数据权威与可视化领域](08-数据权威与可视化领域.md)
|
||||
- 作品引用：[01-作品领域](01-作品领域.md)
|
||||
- 上下文冻结：[04-上下文领域](04-上下文领域.md)
|
||||
- 经验升格（与作品面实体升格不同）：[06-质量与复利领域](06-质量与复利领域.md)
|
||||
- 父仓元数据合同：[专题-06](../../../../../design-docs/专题-06-元数据驱动的智能体架构.md)
|
||||
|
||||
---
|
||||
|
||||
## 附：现状与目标合同对照
|
||||
|
||||
可承认的现有实现（已建成，引用即可）：
|
||||
|
||||
- 拆书与作品面实体入库管线（抽取、别名判重、跨窗留档、覆写审计）。
|
||||
- review-cards 三角色审核（番茄作家 / 起点作家 / 主编）作为拆书常设步骤。
|
||||
- `aiContext` 字段级用途裁剪（按用途只取需要的字段）。
|
||||
- 参考作品授权快照表（`db/ddl/96`）。
|
||||
|
||||
待建（目标合同，尚未跑通）：
|
||||
|
||||
- 草稿→确认的后半段真正跑通（当前正式表、绑定表基本为空，卡多在 `pending`）。
|
||||
- 稳定 `id` 不因改名变化的保证。
|
||||
- `retired` 退役态。
|
||||
- 删库可恢复（见 08）。
|
||||
107
.agent/docs/architecture/domains/03-范式领域.md
Normal file
107
.agent/docs/architecture/domains/03-范式领域.md
Normal file
@ -0,0 +1,107 @@
|
||||
# 范式领域 SoT
|
||||
|
||||
## 1. 唯一职责
|
||||
|
||||
范式领域拥有可复用的写作方法、适用条件、禁用条件、来源证据和验证状态。它回答“什么写法在什么场景下值得参考、证据是什么、是否已经达到可复用标准”。
|
||||
|
||||
范式不是作品事实。范式可以指导规划和写作，但不能证明某人物、事件或世界规则成立。
|
||||
|
||||
范式的正式内容（Canonical）权威在 PostgreSQL，不在 Git 文件。Git 只管代码、Skill、`meta/schemas` 和文档；范式卡作为正式内容存在库里，由只读看板查库渲染给人看。一切输入产出必须落库可见，这条硬纪律见 [领域索引 §3](_index.md)，本文件不重复定义。
|
||||
|
||||
## 2. 数据合同
|
||||
|
||||
范式不再用“目标文件目录”定义，改用数据合同定义：字段权威 = `meta/schemas` 六个范式型 + 库表。
|
||||
|
||||
- **六个范式型**（由 `meta/schemas` 驱动）：`scene_pattern`（通用桥段）、`trope`（套路）、`craft`（技法）、`pacing`（节奏）、`emotion`（情感）、`combat`（打斗）。每型的字段、边界判据和 aiContext 控制项由对应 schema 拥有，本文件不复制字段定义，见 [`meta/schemas/`](../../../../meta/schemas/README.md)。
|
||||
- **库表**：范式卡是 `muse_knowledge_draft` 表里的行。公共范式 `work_id = 0`，作品级范式 `work_id = 8`（当前实验作品）。型别、名称、摘要、写法要点、适用条件、例证出处等放在 `draft_payload`（JSONB）里，结构对齐 `meta/schemas` 对应型。
|
||||
- **scope（适用范围）用库内字段区分**，不再用目录层级：公共 / 作品两层靠 `work_id` + 目标库区分。`work_id = 0` 是公共范式，非零 `work_id` 是某部作品的作品级范式。
|
||||
- 范式卡的演进历史靠库内 `revision` 和数据库自身的版本/备份承载，不在卡里另写一份不可校验的历史叙述。
|
||||
|
||||
## 3. 最小范式合同
|
||||
|
||||
一张范式卡至少由这些库内字段说清楚：
|
||||
|
||||
- `work_id`：0 为公共，非 0 为作品级，决定这张卡的适用范围。
|
||||
- `draft_type`：范式型，取六个范式型之一。
|
||||
- `draft_payload`（JSONB）：至少含 `名称`、`一句话摘要`、`标签`、`来源`（手工 / 抽取@第N章 / 拆书@书名），以及该型在 `meta/schemas` 定义的特有字段（如通用桥段的场景类型、目标结构、推进机制、例证出处）。
|
||||
- `status`：库内状态字段。现状取值是“待确认 → 确认 / 丢弃”，见第 4 节。
|
||||
- `confidence`：可信度，供召回排序参考，不单独决定卡是否成立。
|
||||
- `source_type` / `source_id`：来源回指，能追到拆书原文、抽取章节或作品证据。
|
||||
|
||||
`draft_payload` 的人可读部分必须至少说明：要解决的问题、适用条件、不适用或容易误用的条件、可操作写法、预期效果和可观察信号、来源与验证证据。例证出处只记书名 + 回目 + 一句话定位，严禁抄录原文；原书全文按 raw 规则进库，见 [领域索引 §8](_index.md)。
|
||||
|
||||
## 4. 生命周期
|
||||
|
||||
设计目标合同是五态：
|
||||
|
||||
```text
|
||||
observation -> draft -> evaluating -> active -> retired
|
||||
```
|
||||
|
||||
- `observation`：只留在作品审核、实验或经验记录中，不进入正式范式。
|
||||
- `draft`：已形成可操作写法，但证据不足。
|
||||
- `evaluating`：已进入预注册实验或跨样本复核。
|
||||
- `active`：有可追溯证据，允许被正式上下文选择。
|
||||
- `retired`：被证伪、被更高版本替代或适用边界已失效。
|
||||
|
||||
> **现状标注**：库里现在只有“草稿 / 待确认 → 确认 / 丢弃”这一档，五态生命周期尚未建成。`evaluating`、`active`、`retired` 的机械判据待建。
|
||||
|
||||
单章、单作品或一次高分不能直接产生公共 `active`。升格必须说明样本范围、场景选择偏差和替代解释。
|
||||
|
||||
现有实现锚点：公共范式卡由 `parse-book` 窗级聚类出卡，经 `review-cards` 三角色审核（番茄作家 / 起点作家 / 主编）判 pass / revise / reject 后写回卡里，再由用户确认落为正式内容。
|
||||
|
||||
## 5. 消费合同
|
||||
|
||||
- 范式按意图、场景、适用范围选择，不能临场把整个范式库倾倒给 writer。
|
||||
- 注入 writer 的是有尺寸上限的写法摘要（名称、一句话摘要、写法要点），不是库行全文。来源指针另留在冻结上下文里供审计回读。
|
||||
- **尺寸上限（现有实现，合同侧失败关闭）**：`name ≤ 40` 字、`summary ≤ 120` 字、`writingPoints ≤ 6` 条且每条 `≤ 200` 字；召回每型取 top-2、单次总量 ≤ 12 张。超量内容在合同侧直接拒收，无论检索端将来怎么换，超量都进不了 writer 输入。
|
||||
- 范式冲突时按作品明确绑定、适用范围、证据等级和版本顺序处理；无法确定时省略，不随机拼接。
|
||||
- 范式只影响“怎么写”，不能覆盖作品和实体的正式事实。
|
||||
|
||||
> **消费方式待对齐**：设计目标是“规划期选定并绑定范式，写作期只消费已绑定范式”；现状是“写作期按本章意图实时有界召回”。两者尚未对齐，规划期绑定待建。
|
||||
|
||||
实验臂现状：Gate A 用 A/B/C 三臂，A 臂恒空（纯历史原文对照），B/C 臂拿候选范式卡；分臂规则收敛在 writer 合同一处，保证“有无范式卡”这个单变量不被破坏。
|
||||
|
||||
## 6. 范式在经验升格中的位置
|
||||
|
||||
范式是经验升格的中转站：作品里反复出现的稳定观察，先进入范式验证，达到可复用标准后，再升格为 Skill、确定性工具或 Agent 规则。**完整升格规则和判据由质量与复利领域独家拥有**，见 [06-质量与复利领域 §6](06-质量与复利领域.md)。本节只说范式这一段：
|
||||
|
||||
- 升格一旦发生，范式卡只保留原理、适用边界和证据，具体执行步骤链接到接手它的 Skill 或 Tool，不再自己留一份。
|
||||
- 只适用于单书的经验留在作品级（非零 `work_id`），不得污染公共层（`work_id = 0`）。
|
||||
|
||||
> **两个“升格”不同义**：本节的“经验升格”指写法经验从范式提炼为 Skill / Tool / Agent 规则，对象是**方法**。02 实体领域里的“升格”指参考书或正文产生的实体草稿经用户确认成为作品正式事实，对象是**作品面实体入库**，见 [02-实体领域](02-实体领域.md)。两者对象不同，不要混用。
|
||||
|
||||
## 7. 检索与召回
|
||||
|
||||
范式的选择靠库内检索：按型别、适用范围、场景和意图从库里过滤候选；库内检索加速（pgvector 向量索引）只负责提高召回速度，不是独立权威，可从库重建。任何命中都必须回读库行并校验内容哈希后才能采用。
|
||||
|
||||
- 检索加速失败只影响速度，不改变范式状态语义、不跳过审核。
|
||||
- 只读看板查库渲染范式，绝不写库；接受、丢弃等写操作仍由 `confirm` skill 和主会话走。
|
||||
- 可恢复性（库备份、快照、可重建脚本）见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
|
||||
|
||||
## 8. 验收条件
|
||||
|
||||
1. 每张 `active`（或现状下已确认）范式卡都能从 `draft_payload` 回到来源（拆书书名 + 回目，或作品证据）。
|
||||
2. 公共范式行的 `work_id = 0`，作品级范式行的 `work_id` 非 0；单作品观察不会被写成 `work_id = 0`。
|
||||
3. 任一注入 writer 的范式摘要可机械校验：`name ≤ 40` 字、`summary ≤ 120` 字、`writingPoints ≤ 6` 条且每条 `≤ 200` 字；超量在合同侧失败关闭。
|
||||
4. 单次召回每型 ≤ 2 张、总量 ≤ 12 张，可机械读出。
|
||||
5. 检索加速命中后必回读库行并验哈希；哈希不符的命中不被采用。
|
||||
6. 范式卡只影响“怎么写”，上下文里的作品事实和实体事实不被范式覆盖。
|
||||
7. 范式升格为 Skill/Tool 后，卡里不存在第二份执行步骤，只有链接。
|
||||
8. 只读看板对范式只查不写。
|
||||
|
||||
## 9. 待建
|
||||
|
||||
- 五态生命周期（`evaluating` / `active` / `retired`）的机械判据。
|
||||
- scope 的 category（品类）层：现状只有公共 / 作品两层，品类层为目标。
|
||||
- 规划期绑定：现状是写作期实时有界召回，待与设计目标对齐。
|
||||
|
||||
## 10. 关联 SoT
|
||||
|
||||
- 数据权威与落库硬纪律：[领域索引](_index.md)
|
||||
- 质量与经验升格规则：[06-质量与复利领域](06-质量与复利领域.md)
|
||||
- 实体入库（另一种“升格”）：[02-实体领域](02-实体领域.md)
|
||||
- Skill 边界：[07-Agent与Skill领域](07-Agent与Skill领域.md)
|
||||
- 数据权威与可恢复性：[08-数据权威与可视化领域](08-数据权威与可视化领域.md)
|
||||
- 类型结构：[`meta/schemas/`](../../../../meta/schemas/README.md)
|
||||
- 知识消费上级合同：[专题-07](../../../../../design-docs/专题-07-知识消费契约与质量闭环.md)
|
||||
88
.agent/docs/architecture/domains/04-上下文领域.md
Normal file
88
.agent/docs/architecture/domains/04-上下文领域.md
Normal file
@ -0,0 +1,88 @@
|
||||
# 上下文领域 SoT
|
||||
|
||||
> 数据权威层级、落库纪律和 raw 边界以[领域索引](./_index.md)为准（横切合同见索引 §3，raw 见索引 §8，可恢复性见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)）。本文只定义上下文领域如何从库里选择、冻结、裁剪并投影角色可见输入。
|
||||
|
||||
## 1. 唯一职责
|
||||
|
||||
上下文领域负责根据一次任务的作品、目标章、用途、角色和预算，从数据库中选择来源，冻结版本，裁剪字段，并投影成角色可见输入。它回答“这个 Agent 在这次任务中应该看到什么、为什么能看、哪些内容被省略”。
|
||||
|
||||
上下文领域不创作正文、不修改实体、不评价候选质量，也不授权自己扩大来源范围。它只读库，不写库；写入由现有管线和 Skill 负责（见索引 §3）。
|
||||
|
||||
## 2. 输入与输出
|
||||
|
||||
输入至少包含：
|
||||
|
||||
- `work_id`
|
||||
- `target_chapter`
|
||||
- `as_of`
|
||||
- `purpose`
|
||||
- `scenario`
|
||||
- `agent_role`
|
||||
- `source_policy_version`
|
||||
- `context_budget`
|
||||
|
||||
输出分两层：
|
||||
|
||||
1. 完整冻结清单：来源标识（库内 `sourceId` / `sourceVersion`，不是文件路径）、内容哈希、版本、章号范围、选择理由、省略理由和总预算。
|
||||
2. 角色投影：只包含该角色完成本次任务需要的字段，不暴露运行身份、授权密钥、实验臂、raw 路径或无关来源。
|
||||
|
||||
## 3. 来源优先级（作为门禁）
|
||||
|
||||
```text
|
||||
已确认规划和作品边界
|
||||
> 正式内容（Canonical）正文与正式实体/状态
|
||||
> 作品明确绑定的激活范式
|
||||
> 品类或全局激活范式
|
||||
> 待审/评测中内容（仅诊断用途）
|
||||
```
|
||||
|
||||
- 生产用途必须命中“激活的正式实体 + 已绑定”，否则失败关闭；不靠降级、重试或人工说明绕过。
|
||||
- 作品事实不能由范式替代；范式只提供写法，不提供人物或事件事实。
|
||||
- 回放任务严格拒绝目标章和未来章；正向创作读取最新正式内容和已确认规划。
|
||||
- 来源缺失、哈希不符或章号上界无法证明时，失败关闭或显式省略，且省略带机械可读原因。
|
||||
- 待建（目标合同）：来源优先级从“门禁”升级为“择高降级裁决”——在更高优先来源可用时优先取用、低优先来源只在显式授权下降级使用，并给出裁决记录。
|
||||
|
||||
## 4. 数据库读取器（核心实现）
|
||||
|
||||
数据库读取器是本领域的核心实现，对齐 [`read-context`](../../../../.claude/skills/read-context/SKILL.md) 现状：从库读可信来源、冻结、再投影。它必须能够：
|
||||
|
||||
1. 从库中枚举作品、实体和范式，按 ID、类型、名称、别名、scope、scenario 和章号过滤。
|
||||
2. 解析库内 schema 与来源授权快照，确认每条来源可被本次任务合法读取。
|
||||
3. 对选中内容计算稳定哈希：先剔除运行期易变字段，再对规范化后的 JSON 求哈希（`retrieval_identity`），保证同一内容不因无关字段变动而改变身份。
|
||||
4. 在固定排序和预算下产生可重复的冻结清单（manifest）；排序规则固定为按相似度分降序、版本升序、来源升序、偏移升序，同样输入必得同样来源集合与哈希。
|
||||
5. 按指针回读库行（在只读、可重复读事务中按 `sourceId` / `sourceVersion` 取正式内容行），构造角色投影。
|
||||
|
||||
连续前四章全文构成近期基线，不可裁剪；若预算不足以容纳基线加硬约束，失败关闭，不静默丢硬约束、不截断连续正文。作品事实（实体卡、设定、叙事状态）按字段授权逐字段裁剪（aiContext 字段级裁剪），不整表倾倒，也不把未来状态降格为当前事实。
|
||||
|
||||
## 5. 加速边界
|
||||
|
||||
- 库内检索加速（向量索引，pgvector）只负责候选召回，返回候选 ID / 来源路径，不负责事实裁决。
|
||||
- 可信组装器拿到候选后仍回读库行并验证哈希；加速结果与权威行不一致时丢弃加速结果并重建投影。
|
||||
- 向量索引是数据库一侧的派生加速，可从库重建；它失效只影响速度，不改变内容语义、不跳过审核（见索引 §2、§7）。
|
||||
- **数据库是权威**：库不可用 = 该次任务失败关闭，不假装有本地兜底。不存在“外部不可用自动降级到本地”的路径。
|
||||
|
||||
## 6. ReAct Agent 边界
|
||||
|
||||
ReAct Agent 可以调用上下文 Skill 请求补充证据，但不能自行访问数据库、遍历全库、修改检索计划、读取未来内容，或把待审候选/候选范式提升为事实。补证必须产生新的冻结清单和新的输入哈希，再启动新的模型调用。
|
||||
|
||||
## 7. 审计与 raw
|
||||
|
||||
- 安全 manifest（来源标识、版本、章号、字符数、裁剪与省略原因、状态、哈希）落库可查；安全回显只含这些元信息，不含原文与完整问答。
|
||||
- 完整角色输入、Prompt、Response、未接受候选正文、评测专用答案属于 raw，**落库**（单独表 + 访问控制），只读看板可看全文（见索引 §8）；不再要求进仓外 vault，仓外 vault 仅为可选备份。
|
||||
- 密钥、token、运行身份、授权凭据不写进内容表或运行报告。
|
||||
|
||||
## 8. 验收条件
|
||||
|
||||
1. 同一作品、选择计划、冻结点和预算，产生相同的来源集合与内容哈希。
|
||||
2. 数据库是权威：读取器对库只读、失败关闭；任何来源、字段授权、冻结点、哈希或预算无法验证时失败关闭。可恢复性见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
|
||||
3. 未来信息、未确认实体和未激活范式不会进入正式创作输入；回放任务拒绝目标章与未来章。
|
||||
4. writer、detector、judge 等角色只看到各自投影，互不暴露运行身份、密钥、实验臂、raw 路径。
|
||||
5. 每个选中和省略来源都有机械可读原因。
|
||||
6. 连续前四章全文基线不可裁剪；预算不足以容纳基线加硬约束时失败关闭而非截断。
|
||||
|
||||
## 9. 关联 SoT
|
||||
|
||||
- 内容来源：[01-作品领域](01-作品领域.md)、[02-实体领域](02-实体领域.md)、[03-范式领域](03-范式领域.md)
|
||||
- 数据权威与 raw：[08-数据权威与可视化领域](08-数据权威与可视化领域.md)
|
||||
- 当前 Skill：[`read-context`](../../../../.claude/skills/read-context/SKILL.md)
|
||||
- 上级上下文合同：[专题-03](../../../../../design-docs/专题-03-AI编排上下文与质量评测实现规范.md)
|
||||
118
.agent/docs/architecture/domains/05-创作流程领域.md
Normal file
118
.agent/docs/architecture/domains/05-创作流程领域.md
Normal file
@ -0,0 +1,118 @@
|
||||
# 创作流程领域 SoT
|
||||
|
||||
## 1. 唯一职责
|
||||
|
||||
创作流程领域拥有单用户正向创作链的步骤、状态和失败收敛。它回答"用户的创作意图怎样变成待审候选（Shadow）、候选怎样经过检查、用户决策怎样把候选写为库内正式正文（Canonical）"。
|
||||
|
||||
本领域不拥有作品正文内容、实体字段、范式内容、Agent Prompt、评分量表或存储表结构（存储归 [01-作品领域](01-作品领域.md) 和 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)）。
|
||||
|
||||
一切输入产出必须落库可见——横切合同见索引 §3。
|
||||
|
||||
## 2. 正向流程
|
||||
|
||||
```text
|
||||
用户意图
|
||||
-> 从库内读取作品目标、已确认规划和当前正式正文
|
||||
-> 组装并冻结角色上下文
|
||||
-> Planner/Fine-outline 产生规划候选（按需）
|
||||
-> 用户确认规划
|
||||
-> Writer 产生正文待审候选（Shadow）
|
||||
-> 确定性检查（机械门）
|
||||
-> 语义检测（Semantic Detector）
|
||||
-> 质量策略与有限修订（补证≤3 次 / 重写≤2 次）
|
||||
-> 展示候选、风险、来源和质量摘要
|
||||
-> 用户：原样接受 / 修改后合并 / 丢弃
|
||||
-> accept preflight 与 revision 校验
|
||||
-> 写库内正式正文（= 写库内正文块，不写任何本地文件）
|
||||
-> 生成实体/范式观察草稿
|
||||
-> 继续创作
|
||||
```
|
||||
|
||||
写正式正文 = 写库内正文块。候选在用户接受之前已落库（候选表），只读看板随时可见。
|
||||
|
||||
用户也可以直接在库内编辑并保存正式正文，不要求先运行 Agent 或配置范式。
|
||||
|
||||
## 3. 状态合同
|
||||
|
||||
待审候选状态采用有限状态机（设计合同）：
|
||||
|
||||
```text
|
||||
DRAFT -> CHECKING -> PASSED -> ACCEPTED
|
||||
| |
|
||||
| -> ARCHIVED
|
||||
-> REJECTED
|
||||
DRAFT/CHECKING/PASSED -> DISCARDED（用户明确决策）
|
||||
```
|
||||
|
||||
- 状态应持久化到库（候选表），使只读看板能渲染每个候选的当前命运。
|
||||
- 状态迁移必须绑定 `run_id` + `attempt` + `candidate_version` + `candidate_sha256`。
|
||||
- 迟到检测结果、旧版本候选和 revision 冲突不能覆盖新状态。
|
||||
- `PASSED` 只表示候选可展示、可进入接受前置校验，不表示已成为正式正文。
|
||||
- 诊断和评测候选固定不可接受（四层机械强制：资格由 run 类型机械派生、合同硬校验拒绝、接受入口硬拒、产出钉死评测区）。
|
||||
|
||||
> **现状标注**：当前实现只有内存四态（DRAFT / CHECKING / PASSED / REJECTED）；ACCEPTED、DISCARDED、ARCHIVED 三态与持久化到候选表为目标合同，待建。
|
||||
|
||||
## 4. 用户决策
|
||||
|
||||
只有三类改变候选命运的用户决策：
|
||||
|
||||
- **原样接受**：当前候选正文写为库内正式正文。
|
||||
- **修改后合并**：用户修改产生新 `candidate_version`，必须重新检测和接受前置校验。
|
||||
- **丢弃**：正式正文不变，候选标记为丢弃并留在库内可查。
|
||||
|
||||
决策记录落库（存储结构归 [01-作品领域](01-作品领域.md)）。
|
||||
|
||||
重新生成、查看来源、展开评分和取消运行是辅助操作，不等于接受、合并或丢弃。
|
||||
|
||||
## 5. ReAct 编排
|
||||
|
||||
主 Agent 负责观察库内当前状态、选择下一项 Skill、读取结果并决定是否继续。它不能绕过以下保护步骤：
|
||||
|
||||
1. schema 与来源校验。
|
||||
2. 上下文冻结。
|
||||
3. 确定性检查（机械门）。
|
||||
4. 语义检测。
|
||||
5. 用户接受前置校验（accept preflight）。
|
||||
6. 正式正文 revision 比较与库内原子写（CAS 乐观锁，冲突则收敛到明确终态）。
|
||||
|
||||
正文、规划、提取、检测和评审分别由单一职责角色执行。主 Agent 不把多个角色合成一次模型调用。
|
||||
|
||||
已落地的编排合同（`run_writer_pipeline`）：机械门 → 语义检测 → 补证≤3 / 重写≤2、CAS 乐观锁 + 失败收敛终态、动态篇幅合同、评测候选四层强制。
|
||||
|
||||
## 6. 运行与落库
|
||||
|
||||
- 正式内容和候选都在 PostgreSQL 内；Git 只管代码与文档，不承载正式内容。
|
||||
- 模型调用失败时保留库内已有正式内容不受损；重试产生新 `attempt`。
|
||||
- 任一步失败必须进入明确终态，不留下无法判断是否可接受的处理中候选。
|
||||
- 一切输入产出落库（见索引 §3）：用户意图、冻结上下文、候选正文、检测与评分、决策、运行回执、补证与重写记录。
|
||||
|
||||
> **待建（目标合同）**：
|
||||
> - 写库写入层：当前管线只读不写，正式内容变更仍靠人工 commit；目标是管线直接原子写库。
|
||||
> - 状态机持久化与三态（ACCEPTED / DISCARDED / ARCHIVED）落候选表。
|
||||
> - 生产链上的质量评分环节：当前盲评只接离线评测，生产链尚无评分落库。
|
||||
> - 生成实体/范式草稿的触发接线：当前未接通。
|
||||
|
||||
## 7. 开发评测边界
|
||||
|
||||
Gate A/B、A/B/C 三臂、参考书标准答案和盲评只属于开发期离线验收，不进入普通创作链。离线评测可以复用 Writer、Detector、Judge 和上下文合同，但：
|
||||
|
||||
- 所有评测候选固定不可接受（四层机械强制，见 §3）。
|
||||
- 评测产出不反写作品、实体或范式正式事实。
|
||||
- 评测产出钉死评测区，只读看板可按区查看但不混入正式内容视图。
|
||||
|
||||
## 8. 验收条件
|
||||
|
||||
1. 单用户可以完成新建作品、规划、生成、审核和接受正文，全流程在库内闭环。
|
||||
2. 每个待审候选在库内有明确状态、版本、来源和用户决策记录。
|
||||
3. 修改后合并一定产生新版本并重跑检测。
|
||||
4. 任何评测候选都不能成为库内正式正文（四层强制可机械验证：查询候选表 `run_type` 为评测类型的行，`status` 不得为 ACCEPTED）。
|
||||
5. 中途失败不损坏库内已有的作品、实体或范式正式事实。
|
||||
6. 只读看板能渲染每个候选的当前状态——看板看不到 = 没落库 = 不合规。
|
||||
|
||||
## 9. 关联 SoT
|
||||
|
||||
- 作品与决策存储：[01-作品领域](01-作品领域.md)——正式正文、决策记录的表结构归它。
|
||||
- 上下文输入：[04-上下文领域](04-上下文领域.md)——冻结上下文的选择与裁剪。
|
||||
- 质量步骤：[06-质量与复利领域](06-质量与复利领域.md)——机械门、语义检测、评分的合同。
|
||||
- 数据权威与落库：[08-数据权威与可视化领域](08-数据权威与可视化领域.md)——库权威层级、落库机制、只读看板。
|
||||
- 接受上级合同：[专题-01](../../../../../design-docs/专题-01-正文建议接受%28Accept%20Suggestion%29实现规范.md)——accept preflight 的产品级规范。
|
||||
126
.agent/docs/architecture/domains/06-质量与复利领域.md
Normal file
126
.agent/docs/architecture/domains/06-质量与复利领域.md
Normal file
@ -0,0 +1,126 @@
|
||||
# 质量与复利领域 SoT
|
||||
|
||||
> 数据权威已改订为 PostgreSQL：正式内容（Canonical）都在库里，待审候选（Shadow）也在库里，raw 进库可看全文，只读看板只查库渲染绝不写。本文档不再描述任何“作品内文件目录”作为质量证据的家。落库的横切合同见索引 §3，本文只引用、不重复定义。
|
||||
|
||||
## 1. 唯一职责
|
||||
|
||||
质量与复利领域拥有候选检查、语义审核、评分策略、失败终态合同和经验升格规则。它回答“候选有什么问题、是否可以交给用户裁决、某种写法是否稳定有效、哪些经验值得进入范式、Agent、Skill 或工具”。
|
||||
|
||||
本领域产出检查、审核、实验和升格结论，并把结论落库；它不拥有正文、实体事实、范式正文、模型运行底座，也不拥有用户的接受动作。一切检查输入与质量产出都必须落库可见，没落库的等于系统视角里不存在。
|
||||
|
||||
## 2. 四层质量链
|
||||
|
||||
```text
|
||||
机械正确性
|
||||
-> 语义正确性
|
||||
-> 创作质量
|
||||
-> 长期效果与复利
|
||||
```
|
||||
|
||||
1. 机械检查：schema、字数合同、hash、引用、状态机、预算账本、确定性规则。
|
||||
2. 语义检测：实体、关系、细纲硬约束、知情范围、时间线和来源支持。
|
||||
3. 创作评审：通用底层指标 + 场景类型评分；指出具体可修问题。
|
||||
4. 长期验证：跨章、跨场景或跨作品复核，结合用户决策和合法外部反馈判断方法是否有效。
|
||||
|
||||
机械失败不可被 Agent 主观覆判：机械层不过就是不过，语义和创作评审再高也不能把它盖过去。语义和创作评审也不能替代机械检查。
|
||||
|
||||
## 3. 评分结构
|
||||
|
||||
评分采用两层结构：
|
||||
|
||||
- 通用底层指标（四个通用维度）：设定与实体保真、规划忠实、文风一致、可读性。这些跨章节可比较。
|
||||
- 场景类型策略（五类场景）：战斗、人物对话、转折、信息揭示、老角色回归，各有自己的重点、权重和锚点。
|
||||
|
||||
每章不能自创完全不同的量表，否则失去跨章比较；也不能用一套固定权重覆盖所有场景。量表、场景策略和阈值必须版本化——改了评分口径，要能读出“这次用的是哪一版量表”。
|
||||
|
||||
现有实现承认（各一句，不展开）：六类混淆项报告与新角色比例分层裁决由 [`eval`](../../../../.claude/skills) 质量收敛环承载；卡三角色审核与金标准校准由 [`review-cards`](../../../../.claude/skills) 承载。
|
||||
|
||||
## 4. 失败分类
|
||||
|
||||
安全报告至少区分五类（这是合同）：
|
||||
|
||||
- `execution_invalid`：调用、schema、hash、raw、预算、运行状态或适配器失败，无法形成质量结论。
|
||||
- `quality_failed`：执行有效，但候选存在明确质量问题或硬约束残留。
|
||||
- `insufficient_evidence`：样本或场景不足，不能形成方向结论。
|
||||
- `no_gain`：执行有效且质量合格，但新策略没有证明增益。
|
||||
- `passed`：满足对应质量或实验合同。
|
||||
|
||||
> 实现现状标注（诚实保留，不强改）：当前以四类终态承载——`passed` / `failed` / `insufficient_evidence` / `no_gain`，失败原因靠原因码表达。合同里的 `execution_invalid` 与 `quality_failed` 在实现中合并落 `failed`，靠原因码区分；这两类从合同五类到实现四类的精确映射待对齐。
|
||||
|
||||
运行器失败可以使 Gate 失败关闭，但报告必须保留失败类别与原因码，不能让用户把基础设施故障误解为正文不合格。
|
||||
|
||||
## 5. 库内证据
|
||||
|
||||
审核、实验、运行证据一律落库，并绑定它所评价的正文或候选哈希：
|
||||
|
||||
- 审核记录（reviews）：候选与章节的质量摘要、问题、修复与复验结论，落库并绑候选哈希。
|
||||
- 实验记录（experiments）：baseline、假设、干预、预期、到期与结论，落库并绑被验证的正文或候选哈希。
|
||||
- 运行回执（runs）：安全执行回执、预算账本与 raw 指针，落库；完整 Prompt/Response、供应商原始响应等 raw 进单独表、可看全文（访问控制见索引 §8）。
|
||||
- 用户决策与正式状态：接受、合并、丢弃及其依据，落库。
|
||||
|
||||
正文发生变化后，旧审核不能继续作为接受依据——哈希一变，挂在旧哈希上的审核自动失效。
|
||||
|
||||
> 实现现状标注（诚实保留）：当前审核证据散在 `docs/` 的带日期报告里、不绑哈希，正文一变旧报告照常躺着、无法判定是否过期。审核/实验/运行证据落库并绑候选哈希，待建。
|
||||
|
||||
## 6. 经验升格
|
||||
|
||||
经验升格的规则由本领域独家拥有。范式领域和 Agent 与 Skill 领域只描述各自在这条链上的那一段，并链接回这里。
|
||||
|
||||
```text
|
||||
单次观察
|
||||
-> 作品 review/experiment（落库证据）
|
||||
-> 重复出现的 lesson/win
|
||||
-> 范式 draft/evaluating
|
||||
-> active 范式
|
||||
-> 稳定 Skill / Tool / Agent 规则
|
||||
```
|
||||
|
||||
这是本领域的设计目标合同；现状是这条链基本未实现——证据还散在文件、升格靠人手记，承接物（把 lesson/win 接进范式与 Skill 的结构与状态机）还没建起来。
|
||||
|
||||
> 与 02 的同名区分：本节“升格”指经验沿上面这条链从一次观察长成可复用的范式/Skill/Tool。[02-实体领域](02-实体领域.md) 里的“作品面实体入库（也叫升格）”指拆书抽出的实体进入某部作品的正式事实库。两者只是都叫“升格”，对象、链路与 owner 都不同，引用时注意区分。
|
||||
|
||||
升格原则：
|
||||
|
||||
- 同类问题第 3 次复发，停止逐次修补，评估是否固化为检查项或 Skill。
|
||||
- 单作品证据默认只能产生作品级范式。
|
||||
- 跨作品规则变更必须做影响复核。
|
||||
- 每项优化必须写明可证伪假设、观察窗口和替代解释。
|
||||
- 可机械判断的经验优先固化为工具，不长期堆进 Prompt。
|
||||
- 已被 Skill/Tool 完整拥有的执行步骤，范式和 lessons 只保留原理、证据与链接。
|
||||
|
||||
## 7. Gate A/B 边界
|
||||
|
||||
- Gate A 只验证离线评测链可运行，不能宣布正文层通过。
|
||||
- Gate B 才对跨作品样本做正文能力和策略增益裁决。
|
||||
- Gate A/B 是开发验收，不是正常用户写一章的线上质量流程。
|
||||
- 离线 raw、标准答案和候选进库（单独表 + 访问控制），不要求留仓外。
|
||||
|
||||
现有实现承认（各一句，不展开）：预算账本合同与运行探针锁定由 [`db`](../../../../.claude/skills) 与运行回执承载，Gate B 通过回执的哈希链由 [`confirm`](../../../../.claude/skills) 承载。
|
||||
|
||||
> 实现现状标注（诚实保留）：当前只有一个作品且评测样本已预注册，Gate B 因此恒判 `insufficient_evidence`（跨作品样本不足）——这是目标态下的正确行为，不是 bug。
|
||||
|
||||
## 8. 可恢复性
|
||||
|
||||
可恢复性不在本领域定义，见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)：质量证据与运行回执既然全部落库，可恢复性就跟随数据库备份、快照或可重建脚本，加上 Git 里的代码与 DDL 从零重建库结构。本领域不再单独主张“本地完备”。
|
||||
|
||||
## 9. 待建
|
||||
|
||||
- 经验升格链承接物：把 lesson/win 接进范式与 Skill/Tool 的结构、状态机与落库字段。
|
||||
- 审核证据落库绑哈希：审核/实验/运行记录从 `docs/` 日期报告迁入库表并绑正文或候选哈希。
|
||||
- eval 收敛环脚本：把评分、失败分类与升格触发串成可机械复跑的闭环。
|
||||
|
||||
## 10. 验收条件
|
||||
|
||||
1. 机械失败、运行失败和内容质量失败可以由原因码明确区分，脚本能从报告里读出类别。
|
||||
2. 修改后的候选一定重新检查并绑定新 hash；旧 hash 上的审核对当前正文不再有效。
|
||||
3. 每个 active 范式或稳定规则都有可追溯到库内记录（含哈希）的证据。
|
||||
4. 同一章用两套不同场景策略打分时，通用底层指标的分差能被脚本读出并比较；场景策略只改场景权重，不改四个通用维度的定义。
|
||||
5. 任一审核、实验或运行回执，都能用库内一条记录定位到它所评价的正文或候选哈希。
|
||||
|
||||
## 11. 关联 SoT
|
||||
|
||||
- 数据权威、落库合同、raw 边界与可恢复性：[索引](./_index.md) §2/§3/§4/§8，细则见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)
|
||||
- 范式生命周期：[03-范式领域](03-范式领域.md)
|
||||
- 实体入库“升格”（与本文经验升格不同义）：[02-实体领域](02-实体领域.md)
|
||||
- Agent/Skill 升格：[07-Agent与Skill领域](07-Agent与Skill领域.md)
|
||||
- 离线 Gate 上级合同：[专题-04](../../../../../design-docs/专题-04-生成质量门控与创作健康度设计方案.md)
|
||||
96
.agent/docs/architecture/domains/07-Agent与Skill领域.md
Normal file
96
.agent/docs/architecture/domains/07-Agent与Skill领域.md
Normal file
@ -0,0 +1,96 @@
|
||||
# Agent 与 Skill 领域 SoT
|
||||
|
||||
## 1. 唯一职责
|
||||
|
||||
Agent 与 Skill 领域拥有角色职责、可调用能力合同、确定性工具边界和能力复用方式。它回答“谁负责判断、调用什么能力、输入输出是什么、失败后如何收场、什么经验可以复用到下一部作品”。
|
||||
|
||||
本领域不拥有作品内容、实体事实、范式内容、质量终态或数据库事实；数据库权威和落库机制归 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。但 Skill 是落库的执行者：它声明自己读写哪些表，并把经手的输入和产出落库可见。
|
||||
|
||||
## 2. 四类执行单元
|
||||
|
||||
| 单元 | 负责 | 不负责 |
|
||||
|---|---|---|
|
||||
| 主 ReAct Agent | 观察库内状态、选择 Skill、组织步骤、融合结果、请求用户决策 | 代替所有专业角色创作，或绕过保护步骤 |
|
||||
| 角色 Agent | 在一次调用中完成一种需要模型判断的职责 | 运行 hash、权限、状态机或持久化 |
|
||||
| Skill | 定义一个可复用能力的输入、输出、允许动作、失败和验收 | 同时承担多个无关意图 |
|
||||
| Tool | 执行确定性解析、校验、计算、读写或报告 | 主观创作和质量裁决 |
|
||||
|
||||
角色至少包括 planner、writer、extractor、detector、judge。角色身份由 `.claude/agents/*.md` 拥有；具体功能步骤由 Skill 拥有，不复制进角色提示词。
|
||||
|
||||
角色提示词用“声明不做什么”守边界：说清本角色不碰哪些支架职责（适配、hash、状态机、持久化），把该做的判断留给模型，把该走的步骤交给 Skill。
|
||||
|
||||
## 3. Skill 合同
|
||||
|
||||
每个 `.claude/skills/{name}/SKILL.md` 必须声明：
|
||||
|
||||
1. 唯一目的和消费者。
|
||||
2. 输入、输出及 schema/version。
|
||||
3. 必读文件和允许读取范围。
|
||||
4. 允许的副作用与禁止写入对象。
|
||||
5. 数据库读写合同：读哪些表、写哪些表、失败时如何关闭（失败即收手，不写半成品）。
|
||||
6. 输入产出落库：哪些输入和产出必须进库可见，见索引 §3。
|
||||
7. 稳定错误码和失败恢复。
|
||||
8. raw、授权、预算和审计边界。
|
||||
9. 离线测试与验收命令。
|
||||
|
||||
数据库是权威：Skill 对自己读写哪些表负责，声明失败时如何关闭，并确保经手的输入和产出都落库。没落库的输入产出，在系统视角里等于不存在。只读看板只查库渲染，不替 Skill 写任何数据。
|
||||
|
||||
## 4. Tool 合同
|
||||
|
||||
- Tool 放在所属 Skill 的 `scripts/`，不散落一次性脚本。
|
||||
- 默认从仓库任意工作目录调用，必须自行解析项目根和输入绝对路径，不能依赖调用者先 `cd` 到特定目录。
|
||||
- 机械事实必须结构化输出稳定状态和错误码；人读日志是补充，不是唯一接口。
|
||||
- Tool 不调用模型，除非所属 Skill 明确声明该步骤本质需要模型。
|
||||
- Tool 变更必须有离线测试、`py_compile` 和 `git diff --check` 证据。
|
||||
|
||||
## 5. ReAct 工作方式
|
||||
|
||||
```text
|
||||
观察库内状态
|
||||
-> 选择单一 Skill
|
||||
-> Skill 读取受控上下文
|
||||
-> 角色 Agent 或 Tool 执行
|
||||
-> 校验结构化结果
|
||||
-> 更新待审候选(Shadow)与安全状态
|
||||
-> 判断继续、补证、修订或请求用户决策
|
||||
```
|
||||
|
||||
ReAct Agent 不能把“扫全库、随意写表”当作通用工具。每次动作必须经过 Skill 合同，且只拿到完成当前步骤所需的表、文件和工具范围。
|
||||
|
||||
## 6. 能力复利：升格落点如何接收
|
||||
|
||||
经验升格的完整规则由质量与复利领域独家拥有，见 [06-质量与复利领域 §6](06-质量与复利领域.md)。本领域只管升格的落点——Skill、Tool 和 Agent 提示词——怎么接收：
|
||||
|
||||
- 作品内反复成功的做法先进入范式验证，不直接改全局 Agent。
|
||||
- 升格一旦发生，原位置的重复执行说明必须删除，只保留证据和指向新 owner 的链接，不留下两份规则。
|
||||
- 复用能力不得携带具体作品事实、人物名称或未经授权的正文。
|
||||
|
||||
注意两个“升格”不是一个意思：本节说的是经验或能力沉淀进 Skill、Tool、Agent 提示词；[02-实体领域](02-实体领域.md) 里也习惯把“作品面实体从待审转为正式事实”叫升格，那是数据落库动作，与本节无关。
|
||||
|
||||
## 7. 模型与运行
|
||||
|
||||
模型运行时可替换；角色合同不绑定某个 CLI 的私有状态。模型别名、完整模型 ID、预算和回执由运行适配器记录并落库。模型不可用可以终止当次 Agent 调用，但不损坏库里已有的正式内容，也不让 Skill 跳过检查。
|
||||
|
||||
现有运行底座：受控沙箱子进程执行、运行回执一经写入不可篡改、依赖只向下（上层调下层，不反向）。完整问答、完整原文这类 raw 进库可看全文；仓外保险库降级为可选备份，不再是合同要求。
|
||||
|
||||
模型治理参数固定可见：按 5 小时额度窗计量，达到约 $24 阈值即降级到更省的模型，全程有一条全局降级链兜底，命中敏感词时切换到可用模型。参数由运行适配器持有，回执按索引 §3 落库。
|
||||
|
||||
## 8. 验收条件
|
||||
|
||||
1. 一个 Skill 只有一个明确业务目的。
|
||||
2. 每个 Skill 在 SKILL.md 声明数据库读写合同（读哪些表、写哪些表、失败如何关闭）。
|
||||
3. 每个 Skill 的输入与产出都落库，只读看板能查到对应记录。
|
||||
4. Tool 从不同当前目录调用得到一致结果。
|
||||
5. 角色 Prompt 只声明职责边界（说清不做什么），不包含 adapter、hash、状态机等支架职责。
|
||||
6. 稳定经验能沿“范式 -> Skill/Tool/Agent”升格且不产生重复规则。
|
||||
7. 模型不可用只终止当次 AI 调用，库内已有正式内容不被损坏。
|
||||
|
||||
## 9. 关联 SoT
|
||||
|
||||
- 横切落库合同：见索引 §3。
|
||||
- 数据权威、raw 进库与只读看板：[08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
|
||||
- 范式来源：[03-范式领域](03-范式领域.md)。
|
||||
- 创作编排：[05-创作流程领域](05-创作流程领域.md)。
|
||||
- 质量升格：[06-质量与复利领域](06-质量与复利领域.md)。
|
||||
- 实体入库（另一种“升格”）：[02-实体领域](02-实体领域.md)。
|
||||
- Agent 上级合同：[专题-06](../../../../../design-docs/专题-06-元数据驱动的智能体架构.md)。
|
||||
164
.agent/docs/architecture/domains/08-数据权威与可视化领域.md
Normal file
164
.agent/docs/architecture/domains/08-数据权威与可视化领域.md
Normal file
@ -0,0 +1,164 @@
|
||||
# 数据权威与可视化领域 SoT
|
||||
|
||||
> 本领域定义“数据以谁为准、输入产出如何落库、raw 如何进库、只读看板怎么工作、库如何恢复”。“一切输入产出必须落库可见”这条全系统硬纪律的 owner 在[领域索引 §3](_index.md)，本领域只定义它的**存储与可恢复侧**：哪些东西进哪类表、写入顺序、可恢复要求。原则不在此重复。
|
||||
|
||||
## 1. 唯一职责
|
||||
|
||||
本领域拥有：
|
||||
|
||||
- 数据权威层级：PostgreSQL 是正式内容权威，Git 退回代码与文档的家。
|
||||
- 输入产出落库的机制侧：哪些输入产出必须进哪类表，以及落库的可恢复要求。
|
||||
- raw（完整原文、完整问答、标准答案、供应商响应）进库与访问控制。
|
||||
- 只读可视化看板的合同：它对库只读、绝不写。
|
||||
- 可恢复性：库如何从备份加上 Git 里的代码与 DDL 重建。
|
||||
|
||||
本领域**不拥有**作品、实体、范式的业务语义（那些在各内容领域），也**不决定**候选质量或用户接受结果（那些在质量与复利领域、创作流程领域）。本领域只回答“数据放在哪、谁能看、能不能恢复”。
|
||||
|
||||
## 2. 权威层级
|
||||
|
||||
```text
|
||||
PostgreSQL（muse-example 库） = 正式内容权威（SoT）
|
||||
Git = 代码 / Skill / Agent 提示词 / meta（schema 与 chains）/ 文档 / DDL 的权威
|
||||
+ 这些东西的版本历史与备份
|
||||
库内向量索引（pgvector） = 数据库一侧的检索加速，不是独立权威，可从库重建
|
||||
仓外 vault = 可选备份，不是合同要求
|
||||
```
|
||||
|
||||
- 正式内容都在库里：作品、章、正文、实体、范式、用户决策、运行回执，以及 raw。判断“系统里有没有这个东西”，以库里能不能查到为准。
|
||||
- Git 不是正式内容权威。它保存让系统能跑起来、能重建的代码和 DDL 及其变更历史；也可以对作品相关信息和作品文本留痕（历史、备份）。但留痕只是痕迹，不是权威——正式内容以库为准，看板只读库，两者冲突时以库为准。
|
||||
- 向量索引只是加速检索（快速找出相关实体和知识）的手段，删掉或损坏不影响正式内容，能从库里的正文和知识重建。
|
||||
- 旧主张“Git 文件是正式内容 SoT、数据库是可删除投影、删库零丢失”已作废，全部反过来。
|
||||
|
||||
## 3. 一切输入产出落库（机制侧）
|
||||
|
||||
落库原则（每个输入、每个产出都要落库，没落库等于不存在）见[领域索引 §3](_index.md)，那里是唯一 owner。本节把它落成**存储合同**：每类输入产出进哪类表。落库动作由各业务管线与 Skill 负责执行，本领域负责“必须落库的清单”和“可恢复”两件事。
|
||||
|
||||
| 输入产出 | 落库去向 |
|
||||
|---|---|
|
||||
| 作品、章、正文（正式） | 内容表（作品 / 章 / 正文 block） |
|
||||
| 实体、关系、叙事状态、世界规则 | 实体与知识表 |
|
||||
| 范式（写法、适用条件、证据、生命周期） | 范式表 |
|
||||
| 用户意图、规划、细纲、冻结的上下文、范式选择 | 规划与上下文冻结表 |
|
||||
| AI 待审候选正文（未接受） | 候选表（raw 访问控制，见 §5） |
|
||||
| 检测、评分、审核、实验结果 | 质量结果表 + 运行回执（见 §7） |
|
||||
| 用户的接受 / 合并 / 丢弃决策 | 用户决策记录 |
|
||||
| 每次运行的回执 | 运行回执表（见 §7） |
|
||||
| 补证、重写记录 | 对应的候选 / 回执记录 |
|
||||
| 模型调用的提示词与执行配置 | 模型调用记录表（raw 访问控制，见 §5） |
|
||||
| 完整原文、完整问答、标准答案、供应商响应 | raw 表（见 §5） |
|
||||
|
||||
硬要求：
|
||||
|
||||
- 上表每一类都必须有库内记录；只读看板看不到的，就是没落库。
|
||||
- 每条记录要能回答“它是谁产生的、针对哪个作品/章/候选、什么时候”。
|
||||
- 落库写入必须走 `db` skill 这一条数据库通道，不裸连、不散写一次性脚本（见 §9 与 [07-Agent与Skill领域](07-Agent与Skill领域.md)）。
|
||||
|
||||
## 4. 写入顺序
|
||||
|
||||
```text
|
||||
校验输入
|
||||
-> 写库（正式内容权威）
|
||||
-> 记录安全事件 / 变更
|
||||
-> 异步刷新库内检索加速（向量索引）
|
||||
```
|
||||
|
||||
- 向量刷新失败**不回滚**已经成功的库写入。向量索引只是加速，可从库重建（见 §8）。
|
||||
- 检索加速失败只影响速度，不改变内容语义、不跳过审核。
|
||||
- 模型运行失败可以阻断当次 AI 任务，但不能损坏库里已有的作品、实体、范式。
|
||||
- 任何外部系统、缓存或投影都不得反过来改写库里的正式内容。
|
||||
|
||||
## 5. raw 进库与访问控制
|
||||
|
||||
raw 指不适合直接当正文、但需要留存可查的完整材料：完整 Prompt/Response、未接受的候选正文、标准答案、原书全文、供应商原始响应。
|
||||
|
||||
- raw **进库**，放在单独的表里并加访问控制；只读看板可以看全文。
|
||||
- 旧主张“raw 必须留仓外、仓外 vault 是合同要求”已作废：仓外 vault 降级为可选备份，不再是合同要求。
|
||||
- 内容表（作品 / 章 / 正文 / 实体）里只放正式内容与安全摘要，不直接塞完整 Prompt/Response。
|
||||
- 密钥、token 和外部连接凭据**仍不得**写进内容表或运行报告；连接凭据按内网授权方案放在 Git 侧的受控文档里。
|
||||
|
||||
访问控制的最小要求：
|
||||
|
||||
- raw 表默认不进入普通检索结果；要看全文须显式指定。
|
||||
- 看板展示 raw 全文时，不展示密钥 / token / 凭据字段。
|
||||
|
||||
## 6. 只读可视化模块
|
||||
|
||||
一个本地 web 看板，把库里的状态随时渲染给人看。核心不变量：纯标准库实现、只对库做只读查询并渲染、**绝不触发任何写**（接受、丢弃等写操作仍由 `confirm` skill 与主会话走，看板只展示结果）；看板看到的等于库里的，因此它倒逼 §3 一切落库——看板上空白的地方，就是落库的缺口。
|
||||
|
||||
完整合同（只读硬约束、技术形态、视图清单、raw 访问控制、验收）见 [可视化模块合同](../可视化模块合同.md)，那里是本模块的唯一 SoT，本节不复制。
|
||||
|
||||
## 7. 运行回执库表合同
|
||||
|
||||
每次生成、检测、审核或接受运行，都在库内留下一条回执。旧版“作品内 `runs/` 文件合同”改为库表合同：回执存在库里，不再靠 Git 文件读出。
|
||||
|
||||
一条回执至少包含：
|
||||
|
||||
- `run_id`、`attempt`：哪一次运行、第几次尝试。
|
||||
- `candidate_version`、`candidate_sha256`：针对哪个候选版本、正文哈希是多少。
|
||||
- `context_sha256`：用的是哪一份冻结上下文。
|
||||
- 检测与质量结果的安全摘要：结论和失败类别（完整 Prompt/Response 不落这里，落 raw 表）。
|
||||
- 用户决策：接受、合并或丢弃。
|
||||
- raw 归档指针：完整内容在库内 raw 表的哪条记录。
|
||||
|
||||
硬要求：
|
||||
|
||||
- 回执写入后**不改写**；新的尝试产生新的记录（不可变账本）。
|
||||
- 回执字段合同由本领域拥有；作品领域只提供一个在作品下的归档关系，质量领域只消费其中的结果摘要。
|
||||
- 现有实现里 `runtime` 的不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）即属此合同的落地。
|
||||
|
||||
## 8. 可恢复性
|
||||
|
||||
数据库是权威，所以可恢复性围绕数据库建立：
|
||||
|
||||
- **库结构与数据**：靠数据库备份、快照或 dump 恢复。
|
||||
- **从零重建**：用 Git 里的代码与 DDL（`db/ddl/` 审计文件）重建库结构，再恢复数据。
|
||||
- **向量索引**：可从库里的正文与知识重建，不单独备份也不算丢。
|
||||
- **代码与文档**：靠 Git 历史恢复。
|
||||
|
||||
不再承诺“删掉数据库零丢失”。删库后可恢复的前提是有可用的备份或 dump，加上 Git 里的代码与 DDL。DB 备份与重建脚本属待建项（见 §10）。
|
||||
|
||||
## 9. Git 角色
|
||||
|
||||
- Git 保存代码、Skill、Agent 提示词、`meta/`（schema 与 chains）、文档、DDL 的版本历史，提供差异审查、回滚依据和备份。
|
||||
- Git 不是正式内容权威，也不是实时消息总线。它可以对作品信息与作品文本留痕（历史、备份），但留痕不等于权威；正式内容以库为准，看板只读库，冲突时以库为准。
|
||||
- 一次 `git commit` **不等于**用户接受。接受语义由创作流程和库内状态决定，见 [05-创作流程领域](05-创作流程领域.md)。
|
||||
- 数据库写入、DDL 应用走 `db` skill 单一通道；DDL 先落 `db/ddl/` 审计文件再应用，不绕过。
|
||||
|
||||
可承认的现有实现（引用即可，细节以各自载体为准）：
|
||||
|
||||
- `db` skill：单一数据库通道。
|
||||
- `runtime`：不可改回执（内容寻址账本）与租约 raw 保险库（当前服务评测）。
|
||||
- 额度账本：`db/ddl/95-example额度账本.sql`。
|
||||
- 清洗日志：`db/ddl/92-example清洗日志.sql`。
|
||||
- 参考作品授权快照：`db/ddl/96-example参考作品授权快照.sql`。
|
||||
- `import` skill：参考书 / 旧稿导入落库。
|
||||
|
||||
## 10. 待建（目标合同）
|
||||
|
||||
以下为当前尚未满足、但属于本领域目标合同的缺口：
|
||||
|
||||
- 一切输入产出落库的缺失项：候选正文、用户决策、运行回执、补证记录、模型调用提示词的库内落库尚未全部接通。
|
||||
- 只读可视化看板模块本身。
|
||||
- raw 全文进库的表与访问控制。
|
||||
- DB 备份与重建脚本。
|
||||
|
||||
## 11. 验收条件
|
||||
|
||||
1. 删库后，能用数据库备份 / dump 加上 Git 里的代码与 DDL 重建出库结构和数据。
|
||||
2. raw 全文（完整原文、完整问答、标准答案、供应商响应）能从库里读到，且受访问控制。
|
||||
3. 只读看板对库零写：它发起的所有数据库操作都是只读查询。
|
||||
4. §3 表中的每一类输入产出，在库里都查得到对应记录；看板看不到的即判为缺口。
|
||||
5. 向量索引被删除或损坏后，正式内容不丢，且能从库重建索引。
|
||||
6. 运行回执写入后不可改写，新尝试产生新记录。
|
||||
7. 内容表与运行报告里查不到密钥 / token / 外部凭据。
|
||||
8. 检索加速或模型运行失败时，库里已有的正式内容不被损坏、审核终态不被跳过。
|
||||
|
||||
## 12. 关联 SoT
|
||||
|
||||
- 横切合同 owner（一切输入产出落库）：[领域索引 §3](_index.md)
|
||||
- 内容权威的业务语义：[01-作品领域](01-作品领域.md)、[02-实体领域](02-实体领域.md)、[03-范式领域](03-范式领域.md)
|
||||
- 上下文冻结与取数：[04-上下文领域](04-上下文领域.md)
|
||||
- 候选、用户决策与接受语义：[05-创作流程领域](05-创作流程领域.md)
|
||||
- 检测 / 审核 / 实验结果消费回执：[06-质量与复利领域](06-质量与复利领域.md)
|
||||
- 数据库通道与 Skill 边界：[07-Agent与Skill领域](07-Agent与Skill领域.md)
|
||||
- 外部交互上级合同：[专题-05](../../../../../design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md)
|
||||
99
.agent/docs/architecture/domains/_index.md
Normal file
99
.agent/docs/architecture/domains/_index.md
Normal file
@ -0,0 +1,99 @@
|
||||
# agent-example 领域设计索引
|
||||
|
||||
> **SoT 状态**：本目录是 `agent-example` 领域边界、数据权威和领域协作合同的唯一事实来源。父仓 `design-docs/` 继续拥有完整 Muse 产品、业务和总体架构；本目录只定义单用户缩小版 Muse 的实现边界。
|
||||
> 本版把数据权威从“Git 文件”改订为“PostgreSQL”，以对齐已经建成的实现：正式内容都在库里，Git 退回代码与文档的家，另有一个只读看板随时把库里的一切渲染给人看。
|
||||
|
||||
## 1. 项目目的
|
||||
|
||||
`agent-example` 是一个由 ReAct Agent 驱动的单用户长篇小说创作系统。它依靠 PostgreSQL、Git、Agent、Skill、确定性工具和一个只读可视化看板完成：
|
||||
|
||||
1. 创建和维护作品。
|
||||
2. 管理作品实体与叙事状态。
|
||||
3. 沉淀、验证和复用写作范式。
|
||||
4. 规划、生成、审核、接受和修订正文。
|
||||
5. 从作品证据中持续升级 Agent、Skill、规则与范式。
|
||||
|
||||
## 2. 数据权威（本次重订的核心）
|
||||
|
||||
- **PostgreSQL（`muse-example` 库）= 正式内容权威（SoT）**。作品、章、正文、实体、范式、用户决策、运行回执，以及完整原文、完整问答、标准答案、供应商响应这类 raw，都记录在库里。
|
||||
- **Git = 代码、Skill、Agent 提示词、`meta/`（schema 与 chains）、文档、DDL 的权威**，以及这些的版本历史与备份。Git 不再是“正式内容”的权威。
|
||||
- **库内向量索引（pgvector）= 数据库一侧的检索加速**，不是独立权威，可从库重建。
|
||||
- 数据库是权威，意味着可恢复性靠数据库备份、快照或可重建脚本，加上 Git 里的代码与 DDL 从零重建库结构。**不再承诺“删掉数据库零丢失”**，也不再要求“本地文件模式”为必选。
|
||||
|
||||
## 3. 横切合同：一切输入产出必须落库可见
|
||||
|
||||
这是全系统硬纪律，本索引是唯一 owner，各领域文档只引用、不重复定义：
|
||||
|
||||
- **每个输入都要落库**：用户意图、规划、细纲、冻结的上下文、范式选择、模型调用的提示词与执行配置。
|
||||
- **每个产出都要落库**：AI 候选正文、检测与评分结果、用户的接受/合并/丢弃决策、每次运行的回执、补证与重写记录、实体与范式草稿、完整原文与完整问答。
|
||||
- **没落库的，等于系统视角里不存在**。只读看板看不到，就是没记录。
|
||||
- **落库由现有管线和 Skill 负责**；只读可视化模块只查库、只渲染，不写任何数据。
|
||||
|
||||
## 4. 只读可视化模块
|
||||
|
||||
- 一个纯 Python 标准库的本地 web 看板，零 pip 依赖，内网或 Tailscale 访问，形态参照 open-wenmo。
|
||||
- 只对数据库做只读查询并渲染，**不触发任何写操作**；接受、丢弃等写操作仍由 `confirm` skill 和主会话走，看板只展示结果。
|
||||
- 它看到的内容等于库里的内容，因此它倒逼第 3 条“一切落库”。
|
||||
- 合同细节见 [08-数据权威与可视化领域](08-数据权威与可视化领域.md)。
|
||||
|
||||
## 5. 三条正交轴
|
||||
|
||||
领域采用三条互不替代的观察轴。同一对象可以同时出现在三条轴上，但每份正式数据只能有一个写入 owner。
|
||||
|
||||
| 轴 | 回答的问题 | 构成 |
|
||||
|---|---|---|
|
||||
| 内容轴 | 系统长期保存什么 | 作品、实体、范式 |
|
||||
| 生命周期轴 | 内容如何产生并进入正式事实 | 初始化、规划、组装、生成、检查、审核、用户决策、复利 |
|
||||
| 能力轴 | 谁执行、如何复用、如何被看见 | Agent、Skill、确定性工具、数据库存储、只读看板 |
|
||||
|
||||
## 6. 领域清单
|
||||
|
||||
| 领域 | 唯一 owner | SoT |
|
||||
|---|---|---|
|
||||
| 作品 | 作品身份、规划、正式正文、生命周期、用户决策记录及其他领域产物在作品内的归档关系 | [01-作品领域](01-作品领域.md) |
|
||||
| 实体 | 单作品内人物、关系、事件、地点、物品、组织、世界规则、叙事状态事实，以及拆书与作品面实体入库管线 | [02-实体领域](02-实体领域.md) |
|
||||
| 范式 | 跨作品或限定范围复用的写作方法、适用条件、证据与生命周期 | [03-范式领域](03-范式领域.md) |
|
||||
| 上下文 | 从作品、实体、范式选择并冻结角色可见输入 | [04-上下文领域](04-上下文领域.md) |
|
||||
| 创作流程 | 从用户意图到待审候选，再到用户决策和正式正文的正向链路 | [05-创作流程领域](05-创作流程领域.md) |
|
||||
| 质量与复利 | 机械门、语义审查、审核/实验结果合同、场景评分、验证终态和经验升格规则 | [06-质量与复利领域](06-质量与复利领域.md) |
|
||||
| Agent 与 Skill | 角色职责、能力合同、确定性工具及复用标准 | [07-Agent与Skill领域](07-Agent与Skill领域.md) |
|
||||
| 数据权威与可视化 | 数据库权威层级、输入产出落库机制、raw 进库与访问控制、只读看板、可恢复性 | [08-数据权威与可视化领域](08-数据权威与可视化领域.md) |
|
||||
|
||||
## 7. 总体协作
|
||||
|
||||
```text
|
||||
用户意图
|
||||
-> 作品域提供目标、规划与最新正式正文
|
||||
-> 实体域提供正式事实和叙事状态
|
||||
-> 范式域提供经验证的写法参考
|
||||
-> 上下文域从库里选择、裁剪、冻结并投影
|
||||
-> Agent/Skill 域执行规划、写作、检测和审核
|
||||
-> 创作流程域维护候选、用户决策与正式正文边界
|
||||
-> 质量与复利域产出检查、审核、实验和升格结论
|
||||
-> 数据权威域把上述一切输入产出落库
|
||||
-> 只读看板随时把库里的状态渲染给人看
|
||||
```
|
||||
|
||||
模型运行失败可以阻断当次 AI 任务，但不能损坏库里已有的作品、实体、范式。库内检索加速失败只影响速度，不改变内容语义、不跳过审核。
|
||||
|
||||
## 8. raw 边界（已翻转）
|
||||
|
||||
- 完整 Prompt/Response、未接受候选正文、标准答案、原书全文、供应商原始响应：**进库**（单独表 + 访问控制），只读看板可看全文。
|
||||
- 不再要求 raw 留仓外；仓外 vault 降级为可选备份，不是合同要求。
|
||||
- 密钥、token 和外部凭据仍不得写进内容表或运行报告；连接凭据按内网授权方案放在 Git 侧的受控文档里。
|
||||
|
||||
## 9. 明确不做
|
||||
|
||||
- 不实现管理员控制台、租户、角色权限、市场、计费、资产交易或多用户协作。
|
||||
- 不复制父仓完整业务有界上下文。
|
||||
- 可视化模块不写库。
|
||||
- 不再声称 Git 是正式内容权威，也不再承诺“删库零丢失”或“本地文件模式必选”。
|
||||
|
||||
## 10. 上级 SoT
|
||||
|
||||
- 完整 Muse 产品边界：[产品-01](../../../../../design-docs/产品-01-产品定位与核心价值.md)
|
||||
- Shadow/Canonical 双轨：[架构-02](../../../../../design-docs/架构-02-核心数据结构与双轨模型.md)
|
||||
- 上下文与评测合同：[专题-03](../../../../../design-docs/专题-03-AI编排上下文与质量评测实现规范.md)
|
||||
- 外部 Agent Adapter：[专题-05](../../../../../design-docs/专题-05-AI统一交互协议与外部AgentAdapter设计.md)
|
||||
- 元数据与智能体结构：[专题-06](../../../../../design-docs/专题-06-元数据驱动的智能体架构.md)
|
||||
- 知识消费与回放：[专题-07](../../../../../design-docs/专题-07-知识消费契约与质量闭环.md)
|
||||
96
.agent/docs/architecture/可视化模块合同.md
Normal file
96
.agent/docs/architecture/可视化模块合同.md
Normal file
@ -0,0 +1,96 @@
|
||||
# 只读可视化模块合同
|
||||
|
||||
> 本文件是只读可视化模块（下称“看板”）的设计 SoT。数据权威、落库原则和可恢复性见 [领域索引](domains/_index.md) §2/§3 与 [08-数据权威与可视化领域](domains/08-数据权威与可视化领域.md)；本文件只定义看板这个**只读**模块本身。库内有哪些表、各表现状以 [`db/表映射.md`](../../../db/表映射.md) 为准。
|
||||
|
||||
## 1. 它是什么，不做什么
|
||||
|
||||
看板是一个本地 web 页面，把 `muse-example` 库里的状态随时渲染给你看。
|
||||
|
||||
- 它只干两件事：对库做**只读查询**，把结果渲染成人能读的页面。
|
||||
- 它**绝不触发任何写操作**。接受、合并、丢弃、确认这些写，仍由 `confirm` skill 和主会话走，看板只展示结果。
|
||||
- 它看到的 = 库里的。看板上空白的地方，就是落库的缺口——所以看板天然是“一切输入产出必须落库”这条纪律的验收面。
|
||||
- 它服务本机单用户，不做多用户、权限管理、对外分享。
|
||||
|
||||
## 2. 只读硬约束（怎么保证它绝不写）
|
||||
|
||||
这是看板的命根子，验收时按机械门查：
|
||||
|
||||
- **连接只读**：看板用独立的只读连接，默认事务只读（`SET TRANSACTION READ ONLY` 或库侧只读角色）；连接串与写通道（`db` skill）分开。
|
||||
- **代码无写语句**：全模块只允许 `SELECT`，不得出现任何 `INSERT/UPDATE/DELETE` 或 DDL。审查以“grep 全代码无写语句”为门。
|
||||
- **不接会写的通道**：看板不调用 `confirm` 或任何会写库的 skill，只自己读库。
|
||||
- **挂了不牵连**：看板进程崩了、断网了，库内正式内容和创作链不受任何影响。
|
||||
|
||||
## 3. 技术形态
|
||||
|
||||
- web 层用纯 Python 标准库的 HTTP 服务（`http.server` 一类），**不引入任何 web 框架**，`python3` 直接跑。形态参照 open-wenmo 的 hub（前端相对路径 + 注入 base）。
|
||||
- **一处如实说明**：查 PostgreSQL 需要数据库驱动，而驱动（psycopg）不是标准库。所以“零 pip”在这里的准确含义是——**web 层零框架、零新增依赖；数据库驱动复用本仓 `.venv` 里现成的 psycopg，且只用于只读连接**。不为看板新装任何东西。
|
||||
- 门禁参照 open-wenmo：本机 / 局域网 / Tailscale 直连免验证；如需公网，走 TOTP 动态码。单用户本地信任。
|
||||
- 端口、页面结构等实现细节实现期再定；本合同只约束“只读 + 查库 + 渲染”这三条不变。
|
||||
|
||||
## 4. 视图清单（一次画全，待落库的标明）
|
||||
|
||||
### 4.1 现已在库（看板一上线就有数据）
|
||||
|
||||
| 视图 | 看什么 | 对应表 |
|
||||
|---|---|---|
|
||||
| 作品全貌 | 作品列表 → 章列表 → 正文全文 | `muse_content_work` / `muse_content_chapter` / `muse_content_block`（正文在 `content_text`） |
|
||||
| 知识卡（实体与范式） | 草稿卡、已确认卡、按型别与公共/作品分布 | `muse_knowledge_draft`（草稿）/ `muse_knowledge_entity`（已确认）/ `muse_knowledge_base`（库）/ `muse_knowledge_binding`（绑定） |
|
||||
| 参考书与拆书 | 参考书档案、拆书任务状态、逐章脚手架、窗级大纲 | `example_reference_work` / `example_parse_task` / `example_parse_scaffold` / `example_parse_outline` / `muse_knowledge_document`（原文档案指针） |
|
||||
| 清洗审计 | 每次删了哪段原文、为什么、哪个模型、哪一批，可回放 | `example_clean_log` |
|
||||
| 额度账本 | 5 小时额度窗、花费与调用次数水位 | 额度账本表（`db/ddl/95-example额度账本.sql`） |
|
||||
| 结构本体（框架视图，可选） | 23 型合同、字段、aiContext 控制项、保护节点、功能链 | `muse_meta_schema` / `muse_meta_field` / `muse_meta_visibility_policy` / `muse_meta_protection_node` / `muse_meta_function_chain` |
|
||||
| 写命令审计 | 写命令的幂等审计记录 | `muse_content_command_log` |
|
||||
| 授权快照 | 参考书原文版本对应的用途授权 | `example_reference_authorization_snapshot`（`db/ddl/96`，**待 apply**） |
|
||||
|
||||
### 4.2 待落库（合同要求、表尚未建/未接通；看板预留视图，暂显示“无数据 / 待落库”）
|
||||
|
||||
| 视图 | 看什么 | 落库去向 |
|
||||
|---|---|---|
|
||||
| 待审候选 | 候选正文、版本、哈希、状态、所属作品/章 | 候选表（待建，见 08 §3） |
|
||||
| 用户决策 | 接受 / 合并 / 丢弃的历史与依据 | 用户决策记录（待建） |
|
||||
| 运行回执 | 每次运行的回执、结果摘要、raw 指针 | 运行回执表（待建，见 08 §7） |
|
||||
| 模型调用 | 提示词、执行配置、花费 | 模型调用记录表（待建） |
|
||||
| raw 全文 | 完整原文、完整问答、标准答案、供应商响应 | raw 表（待建，受 §5 访问控制） |
|
||||
| 规划与冻结上下文 | 规划、细纲、冻结上下文清单 | 规划与上下文冻结表（待建） |
|
||||
|
||||
## 5. raw 全文与访问控制
|
||||
|
||||
- raw 全文表受访问控制；看板按单用户本地信任，可看全文。
|
||||
- 任何视图都**不得显示密钥、token、外部凭据**——库内本就不该有这些，看板再加一层“不渲染”。
|
||||
- 看板只服务本机单用户；对外分享、截图不在合同内。
|
||||
|
||||
## 6. 与现有通道的关系
|
||||
|
||||
- 看板**不替代** `db` skill。`db` skill 是面向 agent 和主会话的唯一数据库通道（可写可查）；看板是面向人的独立只读渲染面。
|
||||
- 看板只读库，不经过会写库的通道；它的存在和死活都不影响创作链。
|
||||
|
||||
## 7. 看板必须正确呈现的库内约定（防误导）
|
||||
|
||||
库里现在的数据有几条“坑”，看板必须按实情渲染，不能让人看错：
|
||||
|
||||
- **型别看 payload，不看 `draft_type` 列**：公共卡的型在 `draft_payload->>'型'`（中文键，如 craft/trope）；作品卡的型在 `draft_payload->>'type'`（英文键，如 character/item）。`draft_type` 列对所有活卡都是 `entity`，不能拿来筛型。
|
||||
- **公共 vs 作品看 `work_id`**：`work_id=0` 是公共范式；`work_id=具体书`（深空之影=8）是作品级；辅以 payload 里的「目标库」。
|
||||
- **草稿不等于已确认**：`muse_knowledge_entity`、`muse_knowledge_binding` 当前都是 0 行，卡全是 `pending`。看板要如实显示“已确认知识当前为 0”，不能把草稿当已确认。
|
||||
- **数字实时查库**，不缓存成快照冒充实时。
|
||||
|
||||
## 8. 验收条件
|
||||
|
||||
1. 全模块代码无任何 `INSERT/UPDATE/DELETE`/DDL；只读事务下任何写尝试都报错。
|
||||
2. 看板进程挂掉或断网，库内正式内容零影响，创作链不受影响。
|
||||
3. §4.1 的每个视图都能从对应表渲染出实时数据。
|
||||
4. §4.2 的视图在表未建时显示“无数据 / 待落库”，不报错、不假装已有。
|
||||
5. raw 全文视图受访问控制；任何视图都不显示密钥 / token。
|
||||
6. 型别与公共/作品归属按 §7 的库内约定正确渲染，不把草稿显示为已确认。
|
||||
7. web 层不引入任何 web 框架（纯标准库 HTTP）；数据库驱动仅复用 `.venv` 现成 psycopg 的只读连接。
|
||||
|
||||
## 9. 待建（实现期，按依赖排序）
|
||||
|
||||
1. 候选 / 用户决策 / 运行回执 / 模型调用 / raw 全文 / 规划冻结各表——这属于“一切落库”那批实现工作，不是看板本身，但没有它们 §4.2 的视图就是空的。
|
||||
2. `db/ddl/96` 授权快照表 apply 入库。
|
||||
3. 看板模块本体：只读 HTTP 服务 + 各视图渲染。
|
||||
|
||||
## 10. 关联 SoT
|
||||
|
||||
- 数据权威、落库合同、可恢复性：[领域索引](domains/_index.md) §2/§3、[08-数据权威与可视化领域](domains/08-数据权威与可视化领域.md)
|
||||
- 库内表清单与现状：[`db/表映射.md`](../../../db/表映射.md)
|
||||
- 形态参照：open-wenmo（纯标准库 hub + 门禁）
|
||||
71
AGENTS.md
71
AGENTS.md
@ -1,14 +1,15 @@
|
||||
# AGENTS.md —— agent-example 项目工作入口
|
||||
|
||||
> 适用范围：本文件只约束 `agent-example/`。父仓 [`../AGENTS.md`](../AGENTS.md) 的通用工程、证据和协作规则继续生效；本文件只补充创作实验仓的本地规则，不重复父仓规范。
|
||||
> 适用范围：本文件只约束 `agent-example/`。父仓 [`../AGENTS.md`](../AGENTS.md) 的通用工程、证据和协作规则继续生效；本文件只补充本地创作仓的规则，不重复父仓规范。
|
||||
|
||||
## 1. 项目定位
|
||||
|
||||
`agent-example` 是物理位于 `oh-my-muse` 内、拥有独立 `.git/` 的嵌套实验仓。它用真实创作、拆书、回放评测和候选审查验证 Muse 的智能体、元数据、知识卡与上下文合同，不是另一个 Muse 产品实现。
|
||||
`agent-example` 的目标定位是物理位于 `oh-my-muse` 内、拥有独立 `.git/` 的单用户缩小版 Muse，以 PostgreSQL 为正式内容权威。目标系统由 ReAct Agent、角色 Agent、Skill 和确定性工具协作，在本地完成作品、实体、范式、规划、正文、审核、用户决策与经验复利；不实现管理员、多用户、租户、市场、计费或资产交易。
|
||||
|
||||
- 概念、产品和总体架构的单一事实来源（SoT）在 [`../design-docs/`](../design-docs/)；本仓发现设计问题后应回填父仓 SoT，不在本仓另立概念体系。
|
||||
- 本仓当前运行数据主要在 PostgreSQL `muse-example`；仓内 `knowledge/`、`docs/` 和 `meta/` 是资产、合同或记录，不是业务运行数据的完整镜像。
|
||||
- 仓内不存在 README 历史描述中的 `works/` 主存储。任何仍以 `works/<书>/...` 为当前事实的说明，只能作为历史设计背景，不能据此读写不存在的路径。
|
||||
- 完整 Muse 的产品、业务和总体架构 SoT 在 [`../design-docs/`](../design-docs/)；本仓只定义单用户、数据库为权威的简化实现合同，发现通用设计问题后回填父仓 SoT。
|
||||
- 本仓正式内容的权威是 PostgreSQL（`muse-example` 库）：作品、章、正文、实体、范式、用户决策、运行回执和 raw 都在库里。判断“系统里有没有这个东西”，以库里能不能查到为准；不得把库外的文件或临时快照说成正式内容。
|
||||
- Git 是代码、Skill、Agent 提示词、`meta/`、文档和 DDL 的权威，并可以对作品相关信息和作品文本留痕（版本历史与备份）；但 Git 留痕不是正式内容权威，正式内容以库为准，只读看板只读库，两者冲突时以库为准。库内向量索引是数据库一侧的检索加速，不是独立权威。可恢复性靠数据库备份加快库里代码与 DDL 重建，见 [数据权威与可视化领域 SoT](.agent/docs/architecture/domains/08-数据权威与可视化领域.md)。
|
||||
- 本仓继续承担真实创作、拆书、回放评测和候选审查；这些活动服务缩小版 Muse 的能力验证，不把开发期 Gate 当作产品主流程。
|
||||
|
||||
## 2. SoT 与职责边界
|
||||
|
||||
@ -16,16 +17,18 @@ SoT 按主题分域，不做跨主题的全局排序。可执行脚本与书面
|
||||
|
||||
| 载体 | 权威职责 |
|
||||
|---|---|
|
||||
| [`../AGENTS.md`](../AGENTS.md) + 本文件 | 父仓通用规则与本实验仓工作边界。更具体的本地规则只做收窄，不取消父仓规则。 |
|
||||
| [`CLAUDE.md`](CLAUDE.md) | 主会话、角色分工、模型使用、候选确认和提交纪律；其中 `works/*`、`装配.yaml`、`状态.md` 等文件式运行路径属于旧实现，不是当前执行入口。 |
|
||||
| [`../AGENTS.md`](../AGENTS.md) + 本文件 | 父仓通用规则与本地创作仓工作边界。更具体的本地规则只做收窄，不取消父仓规则。 |
|
||||
| [`CLAUDE.md`](CLAUDE.md) | Claude Code 兼容入口，只引用本文件，不定义独立规则或 SoT。 |
|
||||
| [`../design-docs/`](../design-docs/) | Muse 的概念、产品、业务和总体架构 SoT。 |
|
||||
| [`meta/schemas/`](meta/schemas/) | 23 型结构本体的本仓设计稿与入库种子；运行时字段合同以 PostgreSQL 中经 `db` skill 读取的权威行为准，变更需保持种子与库内定义一致。 |
|
||||
| [`.agent/docs/architecture/domains/`](.agent/docs/architecture/domains/_index.md) | 本仓领域边界、数据权威、落库合同和领域协作的 SoT。 |
|
||||
| [`meta/schemas/`](meta/schemas/) | 23 型结构本体的字段合同；库内 payload 结构以该合同为准。 |
|
||||
| [`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 或磁盘事实。 |
|
||||
| [`.claude/skills/`](.claude/skills/) | 每个 `SKILL.md` 定义能力的输入、输出、红线、数据库读写合同、输入产出落库和自测入口；同目录 `scripts/` 是确定性实现与机械门。 |
|
||||
| [`.agent/`](.agent/_index.md) | 跨任务长期知识；领域设计位于 `docs/architecture/domains/`，新增、删除或重命名必须同步各级 `_index.md`。 |
|
||||
| [`docs/`](docs/) | 单次任务探索、计划、评测资料、样张和历史执行证据；任务完成后把稳定结论蒸馏到 `.agent/`，不得长期拥有领域定义。 |
|
||||
| [`README.md`](README.md) | 项目背景和历史路线概览。目录、阶段、技能数量和存储方式等描述可能陈旧，不得覆盖本文件、`meta/`、skill 或磁盘事实。 |
|
||||
|
||||
`docs/` 的稳定任务 SoT 使用不带日期的稳定名称，只描述创作者可见行为、agent 职责、可执行合同和验收边界。带日期文件只记录历史过程、运行证据、调试和当时待办，必须明确标注“非 SoT”，不得覆盖或重复稳定 SoT。若父仓 `design-docs/` 已指定同一主题的唯一 owner，本仓 `docs/` 只能引用，不得再立本地 SoT。
|
||||
`.agent/docs/architecture/domains/` 一个领域一份 SoT，索引只登记 owner 和协作关系，不复制字段与流程细节。`.agent/` 内文档增删改名必须同步对应层级 `_index.md`。`docs/` 只记录单次任务过程、评测资料、样张和历史证据，不得覆盖领域 SoT。父仓 `design-docs/` 已拥有的完整产品概念，本仓只引用并定义单用户本地实现差异。
|
||||
|
||||
## 3. 真实目录与能力
|
||||
|
||||
@ -34,10 +37,11 @@ agent-example/
|
||||
├── .git/ # 独立 Git 仓元数据
|
||||
├── .claude/
|
||||
│ ├── agents/ # 5 个 LLM 角色
|
||||
│ └── skills/ # 21 个能力合同及其脚本
|
||||
│ └── skills/ # 能力合同及其脚本
|
||||
├── meta/
|
||||
│ ├── schemas/ # 23 型结构设计稿与种子
|
||||
│ └── chains/ # 功能链登记表
|
||||
├── .agent/ # 跨任务长期知识与领域设计 SoT
|
||||
├── db/
|
||||
│ ├── ddl/ # 可审计 DDL / 迁移文件
|
||||
│ ├── 表映射.md
|
||||
@ -46,21 +50,21 @@ agent-example/
|
||||
├── docs/ # 设计、评测、样张与历史执行记录
|
||||
├── .venv/ # 本地 Python 运行环境
|
||||
├── requirements.txt # Python 依赖清单
|
||||
├── CLAUDE.md # 会话与角色章程
|
||||
├── CLAUDE.md # Claude Code 兼容入口，只引用 AGENTS.md
|
||||
└── README.md # 历史概览，不是当前运行态 SoT
|
||||
```
|
||||
|
||||
5 个角色：`writer`、`planner`、`extractor`、`detector`、`judge`。角色身份在 `.claude/agents/*.md`，具体功能合同不复制进角色文件。
|
||||
|
||||
21 个技能按能力分组如下：
|
||||
技能按能力分组如下，实际清单以 `.claude/skills/*/SKILL.md` 为准，不手填数量镜像：
|
||||
|
||||
- 数据、模型与上下文：`db`、`import`、`embed`、`search`、`llm`、`read-context`。
|
||||
- 流程与主权治理：`confirm`、`eval`、`replay-eval`。
|
||||
- 清洗、拆解与知识：`clean`、`parse-book`、`extract-knowledge`、`review-cards`。
|
||||
- 数据、运行与上下文：`db`、`import`、`embed`、`search`、`llm`、`runtime`、`snapshot`、`read-context`。
|
||||
- 流程与主权治理：`confirm`。
|
||||
- 清洗、拆解与知识：`clean`、`parse-book`、`extract-knowledge`、`review-cards`、`upgrade`。
|
||||
- 规划与写作：`planning`、`fine-outline`、`continuation`、`rewrite`、`expansion`、`polish`。
|
||||
- 检测与质量门：`detect`、`quality-gate`。
|
||||
- 检测与质量评测：`detect`、`quality-gate`、`eval`、`replay-eval`。
|
||||
|
||||
当前上下文读取以 `read-context` 顶部登记的 PostgreSQL 可信读取链为准：固定检索计划 -> 卡索引 -> 按来源指针回读原文 -> 双证据组装 -> 冻结与回显。该 skill 后半段仍保留的 `works/<书>/装配.yaml`、`状态.md`、`设定.md` 和文件式回显步骤是迁移前设计稿，不是可执行路径；调用方不得回退到这些旧步骤。
|
||||
上下文目标合同以 [上下文领域 SoT](.agent/docs/architecture/domains/04-上下文领域.md) 为准：数据库读取器是核心实现，库内检索加速（向量）只做候选召回；任何命中都要回读库行并校验 hash。Skill 对自己读写哪些表负责，并把经手的输入和产出落库；没落库的输入产出在系统视角里等于不存在。
|
||||
|
||||
## 4. 反序验证顺序
|
||||
|
||||
@ -94,20 +98,29 @@ agent-example/
|
||||
- Claude 生成或评测只在对应任务 SoT、显式预算、固定执行配置和原文用途授权全部满足后运行；任一前置门失败都应关闭执行。
|
||||
- Claude 的模型别名、解析后的完整模型 ID、预算和回执必须与冻结配置一致。不得因模型不可用而静默换模型、换供应商或降低评测规格；需要变更时先取得明确授权并重新登记配置。
|
||||
|
||||
## 7. 数据与合规边界
|
||||
## 7. 会话编排与汇报
|
||||
|
||||
- 主会话负责上下文组装、任务编排、机械校验和结果裁决；设定、大纲、细纲、正文和知识卡等创作内容由 `.claude/agents/` 中对应角色产生。该边界不限制主会话执行授权范围内的框架维护、只读核验和测试。
|
||||
- 派发角色时必须显式指定模型，并遵守第 6 节的角色模型归属；不得由调用方静默换模型或绕过 skill 的模型治理。
|
||||
- 每次创作生成结束后，向用户说明使用了哪些依据、候选或报告位于哪里，以及涉及哪些伏笔动作；不得把运行日志当作用户可观察的结果界面。
|
||||
- 全程使用简体中文。任务正常执行期间只汇报关键里程碑；任务终止或需要用户决策时，第一句先说明用户现在需要做什么。
|
||||
- 内部代号和英文术语要么不用，要么当场用白话解释；一句话只表达一件事，常规汇报以 30 秒内可读完为限。
|
||||
|
||||
## 8. 数据与合规边界
|
||||
|
||||
- 主代理和业务 agent 不裸连 PostgreSQL 或 New-API。查询、写入和 DDL 走对应 skill 的 `scripts/`；专用导入、嵌入、检索也走各自 skill。
|
||||
- 数据库写入、迁移、授权快照变更和批量运行必须先取得明确授权。DDL 先落 `db/ddl/` 的审计文件，再通过 `db` skill 应用；不得用一次性直连命令绕过。
|
||||
- 原书全文、历史正文证据和候选正文遵守 `replay-eval` 的授权、冻结和仓外临时目录边界。最终报告只保留评分、摘要、章节定位、失败类别和哈希，不复制原书全文、目标章全文、完整 Prompt/Response 或供应商原始响应。
|
||||
- 原书全文、完整问答、候选正文、标准答案和供应商响应按 raw 规则进库（单独表加访问控制，只读看板可看全文），授权、冻结边界遵守 `replay-eval` 合同。对外或跨任务引用的最终报告仍只保留评分、摘要、章节定位、失败类别和哈希，不直接复制全文。
|
||||
- 未绑定、未授权、来源状态无效或超出用途范围的 `knowledge/` 与数据库来源不得进入上下文；失败时明确记录 `not_authorized`、`stale_source` 等原因，不静默降级。
|
||||
|
||||
## 8. 候选、改动与提交
|
||||
## 9. 候选、改动与提交
|
||||
|
||||
- 创作候选默认不提交。用户明确选择接受或修改后合并，且实时审查通过后，才可经 `confirm` 流程进入正式事实；丢弃也必须针对用户明确指定的候选。
|
||||
- 框架改动与创作内容分开审查、分开提交。不得把 agents、skills、meta、脚本改动和正文、规划、知识卡候选混在同一提交。
|
||||
- 任何 `git add` 或 `git commit` 都必须先取得用户明确授权；获得授权后，提交信息使用 `作品(书名): 动作 摘要` 或 `框架: 摘要`。
|
||||
- 不覆盖、不还原、不暂存其他工作者或用户已有改动。执行前后都要核对真实 diff，只处理当前授权范围。
|
||||
|
||||
## 9. 评测结论与验证入口
|
||||
## 10. 评测结论与验证入口
|
||||
|
||||
- 明确区分**已验证事实**、**推断**和**假设**。报告必须给出证据来源；没有机械输出或运行证据时，不声称完成、修复或通过。
|
||||
- 禁止从 `n=1` 样本推出普适结论。至少分析假阴、假阳、样本偏差和混淆因素；需要判断卡或模型效果时使用同任务、同模型、同预算、同公共上下文的对照，并把不稳定样本排除在方向结论之外。
|
||||
@ -122,11 +135,11 @@ git diff --check
|
||||
|
||||
只运行与改动和风险相关的检查。测试涉及真实 PostgreSQL、New-API、Claude 或原文时，先核对授权、预算和副作用；不能把离线自测通过表述为真实链路通过。
|
||||
|
||||
## 10. Agent 提示词与 Skill 审查标准
|
||||
## 11. Agent 提示词与 Skill 审查标准
|
||||
|
||||
新增、修改或定期复核任何 agent 提示词、skill 时，按本节逐条审。总原则：**一份提示词、一个 skill 只服务一个明确意图；与意图无关的词、约束、机制都是污染——它让执行者分心，也让合同两张皮。**
|
||||
|
||||
### 10.1 Agent 提示词（`.claude/agents/*.md` 与角色系统提示词）
|
||||
### 11.1 Agent 提示词（`.claude/agents/*.md` 与角色系统提示词）
|
||||
|
||||
逐条问四个问题：
|
||||
|
||||
@ -137,7 +150,7 @@ git diff --check
|
||||
|
||||
> 反例（已纠正）：评测写手提示词曾塞入「你是 Gate A 离线回放的 writer…只输出 candidateBody…不输出哈希/身份…不访问 MCP」，把评测支架混进创作提示词——既没有写作指导，又诱导写手照抄细纲概述句。正解：提示词只讲怎么写好，输出格式与盲化交给 schema 和输入设计。
|
||||
|
||||
### 10.2 Skill（`.claude/skills/*/`）
|
||||
### 11.2 Skill（`.claude/skills/*/`）
|
||||
|
||||
逐条问五个问题：
|
||||
|
||||
@ -145,8 +158,8 @@ git diff --check
|
||||
2. **目的单一**：一个 skill 只实现一个能力。功能并列、又当编排又当执行的，拆。
|
||||
3. **可靠性与稳定性**：失败是否明确失败关闭（不静默降级、不返回假成功）？错误是否带稳定码、不泄漏原文/密钥？有无离线自测覆盖关键路径与失败路径？确定性步骤是否真不调模型？
|
||||
4. **符合 skill 规范**：`SKILL.md` 是否清楚定义输入、输出、红线、用法？`scripts/` 是否其确定性实现与自测入口？是否走 `.venv`、不裸调 PG/New-API/模型？
|
||||
5. **边界一致**：引用的路径、合同、字段是否与现行 SoT（本文件、`meta/`、库内权威行为）一致？引用已失效旧路径（如 `works/*` 文件式步骤）的不得执行。
|
||||
5. **边界一致**：引用的路径、合同、字段是否与现行 SoT（本文件、`.agent/`、`meta/` 和库内正式内容）一致？数据库是正式内容权威，Skill 必须声明读写哪些表、失败如何关闭、输入产出如何落库；引用已失效合同的不得执行。
|
||||
|
||||
### 10.3 审查产出
|
||||
### 11.3 审查产出
|
||||
|
||||
每次审查对每个被审对象给出：**面对谁 / 目的**、**逐条问题**（正向资产 + 负向污染，各标严重度）、**具体修改建议**。审查只读、不改代码；修改另起授权，框架改动与创作内容分开提交。
|
||||
|
||||
295
README.md
295
README.md
@ -1,257 +1,70 @@
|
||||
# muse-agent-example —— muse 的创作实验台
|
||||
# agent-example
|
||||
|
||||
- 版本：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/`](../design-docs/)（专题-06、架构-02）为准；这里发现设计不合用，回填那边，不在本仓自立定义
|
||||
`agent-example` 的目标是成为 Muse 的单用户缩小版，以 PostgreSQL 为正式内容权威：ReAct Agent 通过角色 Agent、Skill 和确定性工具，完成长篇小说的作品管理、实体维护、范式复用、规划、写作、审核、用户决策和经验复利。代码与文档在 Git，正式内容在数据库。
|
||||
|
||||
## 一、定位：不是迷你 muse
|
||||
本项目不包含管理员、多用户、租户、市场、计费和资产交易。完整 Muse 产品、业务和总体架构仍以父仓 [`../design-docs/`](../design-docs/) 为准。
|
||||
|
||||
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` 天然是采纳台账。
|
||||
|
||||
## 四、目录与能力清单
|
||||
核心合同是：
|
||||
|
||||
```text
|
||||
PostgreSQL（muse-example 库） = 正式内容权威（作品 / 章 / 正文 / 实体 / 范式 / 用户决策 / 运行回执 / raw）
|
||||
Git = 代码 / Skill / 文档 / DDL 的权威，并可对作品信息与作品文本留痕（历史 / 备份）
|
||||
库内向量索引 = 数据库一侧的检索加速，可从库重建
|
||||
```
|
||||
|
||||
正式内容以库为准；Git 留痕不是权威，只读看板只读库，两者冲突时以库为准。可恢复性靠数据库备份，加上 Git 里的代码与 DDL 重建库结构。一切输入和产出都必须落库才能被看板看见。
|
||||
|
||||
## 三条正交轴
|
||||
|
||||
```text
|
||||
内容：作品 + 实体 + 范式
|
||||
流程：上下文组装 -> 创作 -> 质量审核 -> 用户决策 -> 复利
|
||||
能力：Agent + Skill + Tool + 数据库存储 + 只读看板
|
||||
```
|
||||
|
||||
领域边界、数据权威和验收合同见 [`.agent/docs/architecture/domains/_index.md`](.agent/docs/architecture/domains/_index.md)。该目录定义目标行为，不代表所有落库写入和只读看板已经完成实现。
|
||||
|
||||
## 当前工程入口
|
||||
|
||||
```text
|
||||
agent-example/
|
||||
├── CLAUDE.md ← 会话章程:主会话只编排裁决;确认只能由用户触发
|
||||
├── .claude/
|
||||
│ ├── agents/ ← 动脑的:writer / planner / extractor / detector / judge
|
||||
│ └── skills/ ← 基建 skill(组装/确认/收敛+库/导入/嵌入/检索) + 功能 skill(每 scenario 一只功能合同)
|
||||
├── meta/schemas/ ← 23 型结构本体设计稿(对齐专题-06;README 有实例落点表)
|
||||
├── meta/chains/ ← 功能链与功能指令设计稿(prompt 三段式的功能段;G2 治理对象)
|
||||
├── knowledge/ ← 跨作品层:参考书原文 + 拆书产出的公共范式卡(绑定才进上下文)
|
||||
└── works/<书名>/
|
||||
├── 设定.md ← 作品容器+作品核心+世界观总纲+文风画像(四节一文件)
|
||||
├── 大纲.md 状态.md 装配.yaml
|
||||
├── manuscript/ ← 正文,一章一个 md,frontmatter 按 chapter/scene 合同
|
||||
├── 知识/ ← 本作品知识卡:人物/地点/势力/功法体系/物品/事件/关系 + 索引.md
|
||||
└── 评审/ ← 运行噪音(gitignored)
|
||||
├── AGENTS.md # 项目工作入口与规则
|
||||
├── CLAUDE.md # 只引用 AGENTS.md 的兼容入口
|
||||
├── .agent/ # 跨任务长期知识与领域设计 SoT
|
||||
├── .claude/agents/ # 角色 Agent
|
||||
├── .claude/skills/ # Skill、确定性工具和离线测试
|
||||
├── meta/schemas/ # 结构本体与本地字段合同
|
||||
├── meta/chains/ # 功能链、场景、用途和角色槽位
|
||||
├── knowledge/ # 现有参考资产
|
||||
├── db/ # PostgreSQL（正式内容权威）的 DDL 与资料
|
||||
└── docs/ # 单次任务资料、评测样张和历史执行证据
|
||||
```
|
||||
|
||||
### 能力清单（公约：所有 API/工具能力一律封装为 skill，不散写一次性脚本、不裸调外部服务）
|
||||
正式内容在 PostgreSQL，不在 `content/` 文件目录。判断有没有某个内容，以库里能不能查到为准；不得把库外文件或临时快照说成正式内容。
|
||||
|
||||
**skill 两族共 16 只**：**基建 7**（确定性工具能力，每只=未来 muse API 的一道缝；现有 3 + 按闭环步交付 4）+ **功能 9**（每 scenario 一只，承载功能细节约束=功能链场景合同，已全部建成）。
|
||||
## 正向创作
|
||||
|
||||
| skill | 做什么 | 对应 muse API 面 | 状态 |
|
||||
|---|---|---|---|
|
||||
| read-context | 统一读取器：读装配绑定→按用途+aiContext 三级裁剪→组装六分区上下文包→裁剪清单回显 | 统一创作数据读取器（专题-06 §7） | 现有（文件版）；C4 升 PG 检索版（内部调 search） |
|
||||
| confirm | 唯一确认通道：确认=commit、丢弃=restore，仅创始人触发；PG 版加知识行草稿→已确认翻转 | 双轨提交 / 候选三决策入口 | 现有 |
|
||||
| eval | 质量收敛环：n=5、每轮只动一个变量、达标固化 `golden/` | 质量域 | 现有 |
|
||||
| db | `muse-example` 唯一数据库通道：psycopg 直连封装（凭据按 `db/连接信息.md`），查询/DDL/DML/SQL 文件应用全走这，结果卡片式打印（=审查面） | 数据访问层 | 已交付（2026-07-13） |
|
||||
| import | 导入解析：txt→回目正则静态分章→作品/章行入库（调 db） | 导入解析旅程 | B1 交付；C8 用户旧稿复用 |
|
||||
| embed | New-API 嵌入封装：Qwen3-Embedding-8B、`dimensions:1024`、`--noproxy`、批量+失败重试 | AI 网关（嵌入） | B2 交付 |
|
||||
| search | 向量检索：意图→embed→pgvector 相似度召回→授权过滤（仅已确认+已绑定）+字段裁剪→带相似度分的结果集 | 知识检索 | B3 交付 |
|
||||
| llm | New-API LLM 统一调用入口（默认 `MiniMax-M3`）：trust_env=False、重试、`<think>` 剥离、JSON 三级容错（json-repair 兜底）、token 用量审计；清洗/拆书等内容生产调用一律经此 | AI 网关（生成） | 已交付（2026-07-13） |
|
||||
| clean | LLM 探测+代码执行的正文清洗：M3 每窗（~10万字）只报待删段逐字原文→四道守卫裁决删除→审计入 example_clean_log；源 txt 不动可回滚 | 导入清洗旅程 | P0/P1 已交付（2026-07-13） |
|
||||
|
||||
**功能 skill ×9**（prompt 三段式的功能段；每只必带「元数据驱动」节写明 schema 怎么控制它；链登记表见 `meta/chains/README.md`）：
|
||||
|
||||
| 功能 skill | 一句话 |
|
||||
|---|---|
|
||||
| continuation / rewrite / expansion / polish | 写作四功能：章结构=chapter/scene 字段合同；改写锁范围+版本核对；扩写只扩内容不加设定；润色只动表达层+逐处清单 |
|
||||
| planning | 产出结构=schema 字段清单本身；字段全覆盖或标「字段存疑」 |
|
||||
| parse-book / extract-knowledge | 拆书（判据归型+脱敏红线+设计发现回写）与章后抽取（字段合同=抽取 checklist；冲突不覆盖） |
|
||||
| detect | 检查清单由 aiContext 含 detection 的字段自动生成，schema 加字段检查项+1 |
|
||||
| quality-gate | 专题-04 维度体系的单一来源（3 叙事关键定达标线+5 非关键出建议） |
|
||||
|
||||
**skill 官方规范对齐**（2026-07-09 按 code.claude.com/docs 核查）：frontmatter `name`（≤64，小写连字符）+`description`（≤1024，第三人称，写清做什么+何时用）；正文纯 markdown <500 行，附属文件（scripts/reference）从 SKILL.md 单层链接；progressive disclosure 三级（description 常驻 / 正文按调用加载 / 附属按需）。**功能 skill 递送给子代理**：官方三机制——子代理带 Skill 工具自主调用、frontmatter `skills:` 启动预加载、skill 侧 `context: fork` 反向驱动；但 `skills:` 预加载是"列出的全部注入"，与「一次只带本次功能」冲突——**定为主会话内联**：派发时读 SKILL.md 正文按拼装序塞进功能指令段位，子代理无需 Skill 工具（tools 受限不影响，我们的功能 skill 是纯 markdown 合同、无动态注入语法，内联零损失）。9 只功能 skill 已标 `disable-model-invocation: true`（防主会话误自动触发、description 不占常驻上下文，/name 手动仍可用）。
|
||||
|
||||
**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 智能体三层清单](../design-docs/专题-06-元数据驱动的智能体架构.md) 一一对应、无自造型：**第一层开放槽位件 4 + 第二层保护节点件 1**。
|
||||
|
||||
| agent | SoT 身份（专题-06 §3 / 专题-03 §2.3） | 做什么 | 用在 |
|
||||
|---|---|---|---|
|
||||
| writer | 一层 · 写作（Writing 槽位） | 无工具、无会话，只消费 stdin 的 `WriterContext v1`；动态篇幅算法和入口合同已实现，上游编排接线待 Task 8；返回严格 `WriterOutput v1`，本轮只验收 continuation | C4 |
|
||||
| planner | 一层 · 规划（规划链槽位） | 设定包/大纲/细纲候选；字段全覆盖或标「字段存疑」；未确认不进后续生成上下文 | C2 |
|
||||
| extractor | 一层 · 拆书/分析（Analysis 槽位） | 两用场：**拆书**（B2，按库内 schema 产知识行草稿+出处链；系统级只产抽象范式、不留原文）与**章后抽取**（C5）；冲突标「⚠ 冲突待裁决」不覆盖 | B2 / C5 |
|
||||
| detector | 一层 · 检测（Detection 槽位） | 一致性/伏笔/设定违背检查，只产解释与定位落 `评审/`，不改正文与知识 | C4 伴随 |
|
||||
| judge | **二层 · 保护节点（质量门控与 LLM-Judge）**——不可被装配替换，即 G2 判据的活体 | 按专题-04 §4 维度体系评分：3 叙事关键（定达标线，全部 ≥4.0 过门）+5 非关键（只出建议），引文证据制 | C6 / eval 内 |
|
||||
|
||||
SoT 第三层「知识基座」（检索/切块/入库，明文不是 app）在实验里即 **skill 层**（db/import/embed/search）——正好印证「所有 API/工具皆 skill」。分工判据：需要 LLM 判断的进 agent；确定性的取数、写库、外部调用、流程管控进 skill；LLM 参与但属主权裁决的落保护节点（不开放装配）。agent 只经 skill 拿上下文与落库。
|
||||
|
||||
**prompt 三段式**（登记表见 `meta/chains/README.md`）：身份段（agent .md，跨功能共享）× 功能指令段（**功能 skill**，每 scenario 一只，派发只加载本次一只）× L0 任务特化——不做一个 agent 一个大 prompt（防指令稀释），也不按功能裂 agent（防身份复制）。**skill 辅助映射**：extractor 最重（db 读 schema 与既有知识、产出经 db 写入 draft、embed 嵌入）；writer/planner/detector 经 read-context 取数、PG 版加 search 召回；judge 零外部依赖（基线包+rubric）；import 是纯确定性工具，LLM 不参与。
|
||||
|
||||
**LLM 能力功能全覆盖对照**（SoT 功能 → 实验落点，防漏配）：写作 7 功能（续写/改写/扩写/润色/纠错/去AI味/角色声音）共享 writer 身份，但正文实验台 v1 **只验收续写**，其余场景不得据此宣称已优化；规划 5 动作（生成/补全/整理/检查/多方案，产品-03 §3.5）→planner；分析 6 功能（目标分析/实体解析/候选草稿提取/全书解析/章节抽取/结构拆解）→extractor；检测 5 检查（风险/一致性/角色声音/文风/语义偏离）→detector；质量评分 8 维（专题-04：3 叙事关键+5 非关键）→judge；**有限重写**（≤2 次，专题-04 §5）→eval 环承担（judge 诊断+writer 重生成，人在环）；**合规与语义围栏**→不镜像（阶段一由平台安全层承担，阶段二真后端承接）；**组装内摘要化**（超预算先摘要低层）→read-context 流程内动作；**嵌入/重排**→embed/search skill（第三层模型能力，非 agent）；**硬阻断 3 维**（来源安全/输出合规/静态结构）→规则层检查，skill/流程承担，不进评委职权。
|
||||
|
||||
### 上下文组装结构（SoT=[专题-03 §4 四层上下文](../design-docs/专题-03-AI编排上下文与质量评测实现规范.md) + [专题-06 §7 统一读取器](../design-docs/专题-06-元数据驱动的智能体架构.md)；操作细节以 read-context skill 为准）
|
||||
|
||||
```
|
||||
四层上下文(专题-03 §4.2;请求带 scenario 用途与授权语义)
|
||||
├── Layer 0 当前输入 任务目标+本章细纲+当前文本 ——不可省略
|
||||
├── Layer 1 近邻正文 目标章之前连续四章全文+近期叙事状态 ——正文实验 v1 不可省略
|
||||
├── Layer 2 作品事实 设定四节+正式规划+状态台账+知识卡(仅出场+关联) ——只读已确认(Canonical)
|
||||
└── Layer 3 授权资料 绑定的公共范式库/全局知识 ——按场景可省;必须有绑定授权
|
||||
预算顺序:先留输出预算 → L0 完整保留 → L1 优先 L2 优先 L3;超限先摘要化低层再截断
|
||||
拼装顺序(物理序,与预算序是两回事,按稳定度递减):
|
||||
通用系统位(全 agent 相同) → 章级基线包(L2+L1+L0稳,按 writer 视图组装,跨 agent 共享缓存)
|
||||
→ agent 身份段(角色指令后置) → 功能指令段(本次 scenario 的功能 skill)
|
||||
→ agent 增量段(底牌/全集/rubric/L3 检索结果,只加不减) → L0易变部(用户本回合意图,绝对尾置)
|
||||
——同章流水线 writer 首跑写缓存,后续 agent 按 1/10 价读;基线=writer 视图锁"无人多看",
|
||||
增量只加锁"无人少看";阶段一子代理机制钉系统位不落此布局,阶段二 Context Assembly 落
|
||||
裁剪回显(落 评审/,验收证据):字段级=aiContext 裁剪清单(专题-06 §7)
|
||||
+ 来源级=omittedSources(原因枚举:token_budget/not_authorized/stale_source/low_confidence/not_relevant/blocked)
|
||||
```text
|
||||
用户意图
|
||||
-> 读取作品、实体和范式
|
||||
-> 冻结角色上下文
|
||||
-> 规划/写作 Agent 产生 Shadow 候选
|
||||
-> 确定性检查、语义检测和质量审核
|
||||
-> 用户原样接受、修改后合并或丢弃
|
||||
-> 正式正文（写入库内正文块）
|
||||
-> 实体草稿、范式观察和复利验证
|
||||
```
|
||||
|
||||
文件版落位：设定/大纲/状态/知识卡→L2，正文近邻→L1，装配绑定的公共范式→L3，派发指令与细纲→L0。三级裁剪=**字段级** aiContext / **来源级** 装配绑定 / **用途级** scenario。PG 版只改 L2/L3 取数方式（search 召回+授权过滤），层结构与回显合同不变。
|
||||
Gate A/B 是开发期离线能力验收，不是正常用户写一章的生产主流程。评测候选固定不可进入 Canonical。
|
||||
|
||||
**按 agent 差异**（骨架不变，差异=字段可见集×每层取数范围×层必省性；完整矩阵在 read-context skill）：writer 防剧透（底牌全闭、仅出场卡）；planner 看全局（唯一底牌全开+未来粗纲）；extractor 忠于原文（待拆章全文是处理对象、L3 关闭防诱导脑补）；detector 持有基准（知识全集+底牌开，专查提前泄底）；judge 同证独立（可见面=writer 基线不多不少、L3 关闭防拿范式放水）。矩阵为实验设计稿，验证后回填专题-03 §4。
|
||||
## SoT 顺序
|
||||
|
||||
## 五、一次续写怎么走
|
||||
1. 父仓 `design-docs/`：完整 Muse 产品、业务和总体架构。
|
||||
2. 本仓 `.agent/docs/architecture/domains/`：单用户、数据库为权威的领域边界。
|
||||
3. `meta/`：结构本体和功能链登记。
|
||||
4. `.claude/agents/` 与 `.claude/skills/`：角色和可执行能力合同。
|
||||
5. `docs/`：单次任务过程、评测资料与执行证据，不覆盖稳定 SoT。
|
||||
|
||||
1. 主会话读 `装配.yaml`（写作槽位绑了哪个写手、绑定了哪些公共库）；
|
||||
2. 走 `read-context` 组装 `WriterContext v1`：知识卡只作索引并触发冻结原文回读，连续前四章全文作为基线，事实证据与文风证据分开；被裁掉的字段和来源记入回显；
|
||||
3. 无工具 adapter 只经 stdin 调用 writer；writer 返回严格 `WriterOutput v1`，校验通过后形成待检测候选，不直接写 `manuscript/`；
|
||||
4. 先运行机械硬门；机械通过后才允许调用语义 detector。当前真实模型 detector 尚未实现，fake 只验证接口与失败终态；两层最终通过后候选才进入 Shadow；
|
||||
5. 用户对 Shadow 明确选择接受、修改后合并或丢弃；修改生成严格下一 candidateVersion 并重跑 detector，接受/合并还需通过 revision、上下文、授权、来源、策略和过期检查；
|
||||
6. 本轮 accept_preflight 是纯函数，不提交 Canonical、不调用抽取进程；只返回要求 Canonical 成功提交后才可放行的异步抽卡命令意图。
|
||||
|
||||
「角色卡长什么样」由 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 按专题-04 维度评分 + eval n=5 收敛，达标固化 `golden/` | 评分有引文证据；叙事关键三维 ≥4.0 达标 |
|
||||
|
||||
产品红线原样生效：候选决策只有三类（原样接受/修改后合并/丢弃）；采纳正文≠确认知识；未确认规划不进生成上下文；绑定≠写入；保护节点不可替换（§1.1-12）。
|
||||
|
||||
### 完整闭环执行序（对齐稿 v2，2026-07-09，待创始人拍板）
|
||||
|
||||
创始人已拍：**知识域先行**（PG+向量插件为基座、以可见知识库数据为审查）、**创作域后置**。完整闭环 = 四阶段三回路：**作品内环**（生成→章后抽取→知识回库→供下一章）、**元数据环**（拆书/创作暴露的字段问题→修订 schema 种子→产出立刻变）、**设计环**（发现回填 design-docs 与 W1 种子）。
|
||||
|
||||
```mermaid
|
||||
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/字段行卡片打印 | ✅ 已收口（2026-07-13）：23 型/294 字段行，字段级 aiContext 入 policy_snapshot；seed_schemas.py 幂等 |
|
||||
| A4 | G2 系统能力治理 | 四槽位默认智能体（身份段）+ 功能 skill ×9 + 功能链登记表（`meta/chains/`）+ read-context/confirm/eval 保护流程 | 保护节点不可被装配替换 | 已就位（文件侧）；装配入库随阶段二 |
|
||||
|
||||
**阶段B 全局知识生产（管理线 G3 主体；审查=可见知识库数据）**
|
||||
|
||||
| # | 场景锚 | 步骤 | 审查面 | 现状 |
|
||||
|---|---|---|---|---|
|
||||
| B1（原K3） | 参考书导入+静态分章 | import 工具（回目正则）→ 8 本全本作品/章/块入库 | 作品/章行数对账+quality_report 基础面报告 | ✅ 基本收口（2026-07-13）：8 本 ≈1.18 万章全入库；机战无限/超神机械师因源损坏格式（区间章号/分页尾巴/残破实体）用修复后解析器重导 |
|
||||
| B2（原K4） | 拆书智能体 PG 版 | extractor 走 parse-book 2b：先逐章逆推细纲+抽实体作**脚手架**，再在其上按库内 schema 拆范式→知识行(draft)+嵌入 | 脚手架(细纲/实体)+知识行卡片打印+分型统计+出处链 | 文件版首轮流程已验（产物已清理，字段发现存 schema）；PG 版从零起拆 |
|
||||
| B3（原K5） | 检索验证 | 创作意图→相似度召回；授权与 aiContext 裁剪落查询层 | 检索结果+相关性人工评 | 未做 |
|
||||
| B4（原K6） | 联合优化环 | prompt × schema 字段 × 知识行质量，n=5 收敛 | 迭代前后对比+设计发现清单 | 未做 |
|
||||
| B5 | G3 确认+授权门 | 管理员确认（状态草稿→已确认，=commit）→开放作品侧绑定 | 已确认行清单/授权台账 | 无存量，待 B2 产出 |
|
||||
|
||||
**阶段C 创作域（用户线 no-config 主线+增强；创始人已拍后置，B5 过门后启动）**
|
||||
|
||||
| # | 场景锚 | 步骤 | 审查面 | 现状 |
|
||||
|---|---|---|---|---|
|
||||
| C1 | U1 新建作品 | 作品实体入库（新作） | 作品行合 novel_work 合同 | 未做 |
|
||||
| C2 | U2 规划确认 | 设定包+大纲候选→用户确认→正式规划 | 未确认规划不进生成上下文 | 未做 |
|
||||
| C3 | U5 绑定全局库 | 装配绑定已确认范式库，确认生效 | 绑定行；解绑即从上下文消失 | 未做 |
|
||||
| C4 | U3 续写三决策 | read-context 升 PG 检索版→候选→原样接受/修改后合并/丢弃 | 回显含裁剪清单；决策前 Canonical 零变化 | 未做（文件版流程已演练，产物已清理） |
|
||||
| C5 | U4 知识确认旅程 | 章后抽取→草稿→自动确认（自有正文+无冲突）/冲突入待确认队列；**新知识回库供下一章=作品内环闭合** | 采纳正文≠确认知识；冲突必人工 | 未做 |
|
||||
| C6 | 质量收敛（伴随 C4） | judge 按专题-04 维度+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 缺口清单 | 缺口清单 | 未启动 |
|
||||
|
||||
待拍板（①已拍）：① **已拍 A@2026-07-09**——B2 首轮公共面只拆 5 型范式，双层型（人物原型等）待脚手架数据可见后二轮决策；② 封神演义导入与拆书范围（决策中）；③ A2 口径=主仓表原样不改列、私货全进 `example_*`；④ 本闭环序整体确认——确认即从 A1 起跑，B5 前每阶段收口报一行。
|
||||
|
||||
## 八、给 muse 的产出物清单
|
||||
|
||||
达标 prompt（→ 未来 agent_version.config 种子）；schema 修订（→ 专题-06/后端-04/W1 种子）；知识卡样式与上下文组装打法（→ 统一读取器 API 设计参考）；`golden/` 样张与质量基线（→ 完整工程同场景对拍）；阶段二的 API 缺口清单。
|
||||
|
||||
## 九、当前位置（2026-07-13 快照）
|
||||
|
||||
**执行态速览（compact 后从此恢复；细节看 git log 与库内状态表）**
|
||||
|
||||
- **批9d SoT 完善+路线拍板（2026-07-17/18）**：创始人插入方向级任务，第一性原理结论「以用定卡」落 design-docs——新增专题-07（知识消费契约与质量闭环）+ 七册配套拍板（aiContext 值域升级为用途集、参照作品面、双层拍板、purpose 枚举统一；主仓提交 2124a793，经 codex+opus 双独立评审）。**路线拍板（2026-07-18）**：批9c 收尾照旧（补3洞→零落库小样确认→全量重抽）；重抽收官后 **批10 = 消费最小闭环+回放评测首跑**（升格卡向量落库→read-context 从桩变实→单书规划线回放，验收对齐专题-07 §4/§7），不再继续扩书拆卡。执行记录见 [`docs/2026-07-17-卡的第一性原理与知识效用闭环.md`](docs/2026-07-17-卡的第一性原理与知识效用闭环.md)。
|
||||
- **批9c 五书重审真收官+额度改造与卡质量优化启动（2026-07-16 晚，compact 恢复锚点；详见 [`docs/2026-07-16-批9c-收官与优化方案.md`](docs/2026-07-16-批9c-收官与优化方案.md)）**：**五书全量重审库内校验真收官**（星环1525/机动780/机战2336/超神1441/深空963 全 b9-full-v2 覆盖；pass 1677(23.8%)/revise 4358/reject 1010/blocked 0，均分 3.16，降级卡 30 全星环）。本轮解开重审 wrapper×清洗钩子 pgrep 互锁死锁；**review_cards.py 修 3 处勿回退**（敏感降级链 M3→M2.7→deepseek→glm-5.2 / 分片 `--shard` / 连接拆读算写三段治 Tailscale 空转超时 + isinstance 守卫）；创始人授权**物理删除 work5/9**（机战超神源修复前重复旧本 8596 行，仓库唯一物删授权，其余仍守软删红线），作品表现干净 8 本 8 活。三样张入库（升格深空新出、untracked）；旧 grep 额度口径作废、服务端实花 $122.93。**下一步（创始人已确认，勿擅自跑管线）**：①**item4 额度系统改造**（opus 子代理在跑，以钱为主 $10/5h 窗 MiniMax(M3+M2.7) 花完→glm-5.2→deepseek / 4000 次窗硬停=自动挂下一窗续跑 / 库表 example_llm_quota 共享账本 / 只改 llm.py；费率公式与兜底见 plan doc；**compact 时 llm.py 未落盘→恢复后先查子代理结果、主代理亲验再上线**）②**卡质量优化**（等 item4 上线再跑：范式卡 P0 跨窗跨书聚类去重+P1 抽取提干货[含 combat 打标签]；升格卡 P0 补「演变历程」骨架+P1 串链+语义判重；**两点细化：历史数组用绝对章号不用窗号、卡渐进式披露=现状层+完整历史层接 aiContext 按用途裁剪**）③combat 210 卡=打标签。待创始人：item4 验完上线→卡修复实施；框架改动（review_cards.py/llm.py/两 doc）待你点头提交。
|
||||
- **A 阶段全收口**：muse-example 库+pgvector 0.8.5（容器重建恢复命令见 `db/连接信息.md`）；24 表（主仓一致 20+example_* 5，含 92-清洗日志表；映射见 `db/表映射.md`）；23 型 schema 入库（294 字段行，字段级 aiContext 在 visibility_policy.policy_snapshot）。
|
||||
- **B1 基本收口**：8 本参考书全本入库（希泊尼战纪1496 / 星环使命1722 / 机动风暴673 / 机武风暴686 / 机破星河2250 / 深空之影594 / 超神机械师 / 机战无限2901 章；星环使命为创始人 2026-07-13 新增）。源损坏修复经历：双章区间号「第2373-2374章」、分页尾巴「(第1/1页)」、残破实体「&bp;」、纯中文数字章题+重贴+目录页（机动风暴）——全部进 import 解析器规则。基础面验收工具=`quality_report.py`（字数/分章/章题/段落/垃圾嫌疑扫描）。
|
||||
- **M3 拍板（2026-07-13 创始人）**：清洗与拆书的内容生产 LLM **全部改走 New-API `MiniMax-M3`**（llm skill 统一入口，密钥入仓）；主会话（Fable5）只固化 agent/提示词/skill 与发起调用。清洗范围=**所有书**；删除前创始人质检样张（门①）；**拆书先不放量**（试拆 M3 重做后质检=门②，B2 硬停等新指令）。执行计划：`docs/2026-07-13-M3清洗拆书执行计划.md`。
|
||||
- **清洗 P0/P1 收口（2026-07-13）**：llm skill（M3 入口+json-repair 三级容错）+ clean_detect（每窗一调、断点续跑）+ clean_apply 四道守卫（长度界/章题/单章20%顶/**行级垃圾特征拆行**——盗版源把广告插进正文句中，M3 会拼「广告+截断正文」，已实测拦住）+ 三级匹配（精确/空白弹性/邻章±1）。实测定标：M3 中文 0.58 token/字，10 万字窗 in≈5.9 万 token 耗时 24s；全语料 ≈340 调用/~19M token。机破星河前 50 章演示已备：40 段/2,188 字待删（dry-run），误删 0。
|
||||
- **opus 试拆基准（workflow 已完成）**：机动风暴 1–3 章，范式卡 2 张入库（ch2/ch3 各 1 拒 1 越合同）+ch1 脚手架；opus 也犯 JSON 中文引号/缺逗号病（已被 llm skill 容错吸收）。此产物只作 M3 对比基准，不算正式拆书。
|
||||
- **P2 全语料清洗收口（2026-07-13）**：8 书全清（门①创始人放行）——总删 1,685 段/约 6.1 万字（机破星河 2.4 万/机战无限 1.9 万/超神 0.6 万…），审计全在 example_clean_log（批次 P2-20260713 主删 + fix/fix2/fix3 补删 + P2-sweep 高频水印收割），全库空行归一 8,786 章。守卫体系放量长成：行级垃圾特征+书名豁免+水印裁剪+20%顶带下限+敏感窗备选模型降级（见 clean/SKILL.md）。误删实测 1 例 3 字已修复。已知残留待拍：机动风暴「重贴章题+（第N更 求月票）」嵌正文行变体（求票嫌疑 270 处主源）、感言/请假条整章、作者疲劳话散句。
|
||||
- **B2 试拆收口（2026-07-13，门②已呈报）**：5 本×前 3 章 M3 直调完成——scaffold 15/15 全过（绝对字数上限+压缩重试对症后，细纲 2.9%–7.8%）；范式卡三轮迭代后活卡 19 张（样张 `docs/试拆-门②样张.md`，opus 同章基准 `docs/试拆-opus基准-机动风暴.md`）。**M3 三病理已档**：①归型偏科——内容有型区分但 type 一律标 craft，prompt 两轮矫正无效，字段指纹改型又被「串型混填」挫败（一卡混两型字段）；②重跑自噬——判重名录含本章旧卡+幂等软删+LLM 随机性组合损耗（已修：名录排除本章+0 卡不软删）；③偶发脱敏违规/source 偷懒（守卫拦对+机械回填治）。
|
||||
- **拆书流程增补（2026-07-13 创始人拍板+落地）**：①**窗级大纲聚合**——大纲不从单章抽（单章对大纲层可能零贡献），5–10 万字窗（多章细纲+正文）聚合一次，整本完后拿全体细纲终检（parse_outline.py + 93 表）；②**三角色审核常设步骤**——番茄作家/起点作家/主编审核公共卡（成立性/AI 可用性/可参考性），**M3 执行**（review-cards skill）；fable/opus 只做起量前校准+起量后总审核。校准已过：opus 三评审金标准入 golden/，M3 对照平均绝对偏差 0.45（合格线 0.5），四大系统病独立复现。首批 19 卡 M3 判定 pass 5 / revise 10 / reject 4。
|
||||
- **金标准评审结论（拆书 prompt 的 B4 改造清单,见 review-cards/SKILL.md）**：同功 family 撞车（19 卡实为 10–12 个独立技法）、命名黑话+专名泄漏、伪精确数字、伏笔框架硬套场景手法、失败模式才是干货位、采样偏科开局——七条改进已档,B4 环实施。
|
||||
- **B4 收敛环（2026-07-13 创始人拍板「先收敛质量」,S1-S4 全部完成）**：fable 独立审查完成（报告=`docs/2026-07-13-B4-fable独立审查报告.md`,S1-S6 实施序）。**头号发现=CONTRACTS 漂移冤案**：parse_llm 手写合同与库内字段名漂移,M3 正确产出的 11 张非 craft 卡全被守卫冤杀——「craft 偏科」一半是冤案。**已完成**：S1 修地基（合同库内动态渲染 prompt 与守卫同源+system 角色分离+审核 idx 匹配;验证=重跑 15 章拒卡 14→0、scene_pattern 首次存活 8 张）;S2 schema 批（craft 双模板「装置形态」条件必填禁填+装置类型闭合枚举判定测试+原理/触发条件/读者收益/回收点/记忆维持/滥用反例/迁移用例新字段+emotion 目标情绪+**pacing 启用 8 字段**「黄金三章画像/开局策略/上架节奏切换/张力曲线/爽点间隔…」=创始人抽取分层议题的书级归属;ingest 三守卫已验）;S4 审核环（CRITERIA#8 场景走位+机械降档回测零误伤+分页 ≤30+豁免区说明防假阳）;**S3 管线重构（本轮完成并验收）**——见下条。**待做**：S5 参数 A/B（范式线 temp 0.2vs1.0;M3 输出方差的根治口）→S6 pacing 书级抽取（等整本拆完）。
|
||||
- **S3 管线重构收口（2026-07-13,验收报告=`docs/2026-07-13-S3窗级出卡验收报告.md`）**：出卡权上移窗级——章级只产「范式候选线索」（并入 scaffold pass,正文只过一遍,放量每书省 ~8M 输入 token）,窗级（=大纲窗行,幂等键改 from_order+书末残窗必成窗）聚类归并出母卡+多实例章号,**间隔章数由实例章号差机械计算**（伪精确灭绝）,入库前嵌入判重（≥0.85→M3 归并终判,0.75-0.85 标记）。**验收（5 书×3 章重拆对比）**：型偏科痊愈（craft 27/32→14/39,trope 0→15）;命名全短名;摘要通用化;间隔全机械溯源;跨书近亲 3 对被判重标记;审核 pass 11/39,top 4.33×2 超旧金标准最高 4.0。**本轮实战修四病**（各带机械防线,见验收报告）：纪律措辞串型→裁剪降级;占位符字面抄写→机械检测+拒卡重试环;M3 输出方差（同料 0 卡vs10 卡）→0 卡可疑重试;审核豁免区假阳→CRITERIA 补说明。管线定版=五步（chapters→window→cards→check→review,SKILL.md §放量全流程）。
|
||||
- **抽取窗口×型映射（创始人议题定版）**：单章=6 实体型+范式候选 hint;窗级（5-10万字）=五型出卡聚类+trope+character_relation;书级=pacing/style/终检。原理:**抽取窗口必须 ≥ 该型判据的证成窗口**（trope 判据是跨章公式却曾在单章抽=永远证不成）。
|
||||
- **B2 放量首批收口（2026-07-13 创始人拍板放量）**：5 书×前 50 章跑通五步管线——**216 张活卡,审核 pass 123/revise 81/reject 12（pass 率 57%,验收批 2 倍）**,顶卡 5.0 满分（「小动作验真」四跨章实例三角色全五分）;五型首次全活（emotion/combat 在 50 章窗首次出卡）;多实例卡 98 张。样张=`docs/2026-07-13-B2放量-5书50章-216卡样张.md`。**放量首日抓出并根治三轮病**（全带机械防线,均已提交）：①usage 嵌套 dict 合并崩溃+实体坏行陪葬整章+窗行占位陷阱（换窗参数必先清窗行,入 SKILL.md）;②M3 百条线索全型聚类=认知超载退化为逐条转写（37 章窗曾出 74 卡/42 卡整批丢实例键）——治=**出卡按型分批**（每批一型线索+该型合同,聚类真实发生,压缩比 4:1）;③软删延后到确有新卡通过（防新卡全拒时旧卡净损失——星环曾净丢 8 卡）。教训：在飞任务期间不改共享脚本（超神曾读到半成品代码崩溃）。
|
||||
- **B2 全本拆书·限流分批（2026-07-14 创始人拍板：暂停→分批,每批 ≤3000 次请求、批间隔 5 小时）**：首夜 5 路并行拆至 425–544/书（合计 ~2570 章落库）后按指令暂停。**限流纪律**：请求含重试保守全计,每批按 ~2700 章排（章级=每章 1 次调用+少量病症重试;窗级出卡=每窗 5–8 次）;批间隔 ≥5 小时,宁晚勿早。**批1 定时失败→09:09 脱离补跑**：sleep 18000 定时挂在 Claude Code 后台任务上,上会话退出被带走→06:40 未开跑、零请求（额度未亏）;改 nohup+disown 脱离会话补跑五路（深空→594/机动→673/超神→1455/星环→1722/机战→827,共 2700 章,断点续跑跳已完成章,日志 /tmp/muse-b1-*.log）。**跨会话根因未除**：本地后台长任务随 Claude Code 会话消亡,彻底可靠需放 mini-desktop tmux/nohup（待定）;`pkill -f parse_llm` 模式串会连带杀定时器。**批2**=机战章级收口（→2901）+四书窗大纲续切+余量开出卡;批3+=出卡/终检/审核/样张,每批开跑前按预算精排。**shell 教训**：定时批命令 `A && B & C &` 中 C 不等 A（`&` 分组陷阱）,必须 `A && { B & C & wait; }`——首挂曾致 4 书抢跑约 1 分钟,当场杀掉,烧个位数请求。**章级完成后的续跑序**：窗大纲续切（`window --to 末章`——机动已有 win1-37/深空 win1-36/其余至 50,续跑自动从缺口接;换窗参数才需清窗行）→ 分型出卡 `cards --redo 不带`（断点续跑跳已出窗）→ `check` 终检 → `review` 审核 → `export` 样张呈报。
|
||||
- **B2 停跑·缓存与敏感优化前置（2026-07-14 创始人拍板）**：创始人点破**限次数是果不是因**——每次请求 token 太贵→同配额可用次数缩水→被迫连砍额度(4000→3000→1000→500)；省 token=省次数一根链，先前把两者当并列选项是错判。停跑时批2实发280(机动16/深空43/超神81/星环67/机战73)，**其中66次(23%)被上游内容安全 new_sensitive(1026) 拦截空耗**(机动/星环暴力战争情节,每敏感章重试3次)。双重漏水：①缓存没吃到(scaffold_prompt/window_cards_prompt 把 title/章号/cap/batch_note 变量前置,破坏 read-context 规定的"稳定度递减吃前缀缓存")②敏感空耗23%。**优化落地前不重启批次**，三前置(均省次数)：①缓存重排(固定规则前置、正文/章号/大纲尾置；窗级合同+金标准纪律上千字是最大靶,拆书自拼消息不受"阶段一子代理不能共享缓存"豁免)②拆书补敏感换模型/跳过机制(清洗侧已有先例)③读 token 明细验 M3+New-API 真支持缓存(usage 带 *_tokens_details 疑含 cached_tokens,需1次诊断)。方案待出给创始人。
|
||||
- **B2 优化落地·批3重启（2026-07-14 实测纠正预判）**：①**真凶是前文实体膨胀,不是缓存**——章级 prompt 把前文实体全档(型+名+摘要)累积重发,深空557章2851实体≈15万token/章占输入97%、随章号雪崩;缓存只缓存"每次一样的固定前缀"、救不了每章都变的实体清单,此路错判。②**压缩(主力)**:实体索引全档json→名字清单(判重只需名字),每章16万→2万token砍86%(深空500实测14万→1.95万,细纲/实体/线索质量正常),同预算次数×7-8,直达创始人目标2-3000。③**缓存诊断**:M3经New-API自动缓存恒命中128token(其内部模板,与我方内容无关);换 Anthropic /v1/messages+cache_control 仍 cache_creation=0(M3上游不支持显式缓存);M2.7/deepseek=0——要吃缓存须换模型,但压缩后缓存仅省固定前缀1k小头,不值当;提示词已缓存重排(固定前置)备将来换模型。④**敏感降级链**:撞 new_sensitive→MiniMax-M2.7→deepseek-v4-flash→全失败硬停,实测 M2.7 救回深空/机动密集敏感章(深空连测3章皆敏感)。**批3=500次自停闸**(wrapper PID精确kill+计数 grep [llm]|[敏感] 含敏感失败请求防超支,哨兵盯收尾)。**教训**:创始人两次纠偏单一归因(省钱=省次数是一根链;缓存/压缩/检索是多重方向非二选一)。检索召回(名字清单再压)留后续。
|
||||
- **批9b 终检收官+样张走查治理(2026-07-16 午前)**：**五书窗大纲终检 100% 收官,blocked=0**——compact 前的"STOP 终检完成"实为假收官:check 命令裸用 chat 无敏感降级,超神窗20/星环窗22/机战窗65 撞 new_sensitive 直接崩进程,三书共 134 窗漏检;修复=check 接 chat_degrade 降级链+断点续跑(跳已检窗)+单窗全链拦截标 blocked 跳窗不崩(commit 74989af),补跑 134 窗全过(敏感降级救回 14 次,blocked 0)。**样张走查揪出三病并根治**:①升格卡尾部 JSON 拼接残渣 59 处+中缝断片(李锋等 20 张头部大卡,条目尾挂 ",/'] 等符号)——机动已清洗归零,守卫 _strip_tail 固化进 merge 追加/立卡/覆写三处,体检加红线 2 条(尾残渣/前缀重复);②前缀重复追加 36 处(模型把旧条目整段抄回再加尾巴,A 是 B 严格前缀→删 A 保超集)——机动清洗 13 处,深空 44 处待接力收官后由 /tmp/muse-debris-w8.sh 串行钩子自动清(整行写回不能与摘要重刷并发);③5 张连号 emotion 卡"读者会Z:"批量乱码定点修复。**体检又抓深空窗洞 523-530**(B 路补切时漏切)——补切 win46-48(含 530 单章窗)+补出卡+补终检闭环。**样张导出固化 parse_export.py**(export-patterns 每书每型实例数 top1+combat 加倍供拍板/export-upgrade 出场章 top8+各型代表),两份终态样张已入库:`docs/2026-07-16-批9终态样张-范式五书.md`(全库 7026 卡:星环1525/机动780/机战2336/深空944/超神1441)+`-升格机动.md`(559 卡,残渣清洗后重导)。**review 全量审核装不下剩余额度**(范式 7026 卡×每卡一审≈7000 次)——列入总验收拍板项。
|
||||
- **批8-9 终态治理+全自动收尾(2026-07-16,compact恢复锚点)**：批8(闸5700=批7+追加1000)+批9(闸7700=+追加2000,"continue,2000")。**里程碑:五书范式出卡全部收官**(星环/机动/机战/超神/深空,深空窗大纲尾部353-594由B路自动补切,末窗593-594入库确认)。**串行铁律定版(创始人2026-07-15拍板,勿回退)**:升格窗失败=当场撤销半写入+同窗重试1次,仍败停书断点续跑,严禁跳窗后补(断层+覆盖风险);曾跳窗的深空回滚窗12-38重跑;机动补跑倒流覆写44处按audit最高窗还原+迟到覆写弃用闸+水位GREATEST。**三轮找-修-优化**:①机械体检6项(三书窗洞51章断点悬空系统性成因→补切9窗+补出卡闭环;星环#1593漏章;新天枢号1723/1895漏并;林初雨垃圾)②opus范式终检(星环1526/机战2319,实例锚定20/20全对,四型80%达标;82卡专名清洗70改8免/同名3对消歧/判重失败5张重判4并1留;**combat型210卡题材绑定待创始人拍板:打标签(我方建议)vs改写泛化**)③fable升格复验(机械10项:100引号变体去重/15分隔符拆分/果子摘要幻觉更正/安吉儿身份串写回退/萨马奥633章更正/431僵尸水位行;LLM批:安吉儿窗72-80缺口回填/200张character卡死活校验更正12张幻觉摘要——死活类幻觉毒性最高,方法论:机械grep死亡词±60字候选→LLM批判)。**管线固化(勿回退,commit 0892bca..073c351)**:merge 8处守卫/体检脚本parse_health.py(四层+五红线)/切窗缝隙自检/IP词表含词形边界注释(浮游炮平反)/undo清水位/立卡路守卫(初卡字段同过拆分+垃圾拦截)/前缀正则宽至12字符/更新批缺键宽容。机动561卡治理完备(机械清洗+摘要重刷559/561)。五红线终扫全绿。**compact时在跑(nohup脱离会话,勿重启)**:深空升格92+/116(/tmp/muse-b7-upgrade.log)+接力钩子/tmp/muse-w8-relay.sh(升格收官→自动跑/tmp/muse-clean-w8.py机械清洗→/tmp/muse-resummary-w8.py摘要重刷,日志/tmp/muse-b7-resummary.log)+守护闸/tmp/muse-b9-guard.sh(7700,全线自然完成→自动五书check终检/tmp/muse-b7-check.log→STOP行落/tmp/muse-b7-cards-main.log)+五书check因B路收官空档已提前开跑(窗大纲已定型,时点无害)。compact时计数~5720/7700。**新会话恢复**:查STOP行+接力游标(/tmp/muse-b7-upgrade.log尾"[接力]"行);全完后续跑序=review审核→export范式样张+升格样张(机动/深空)→总验收呈报(含combat拍板项+额度实耗)。待创始人:样张过目/B3检索验证/B5确认门/combat处置拍板。
|
||||
- **批6-7 全线放量+质量闭环(2026-07-15,compact恢复锚点)**：批6(2400闸→1211章,敏感救回423,超神/星环/机战大步收口)。批7(创始人放量5000,中途令牌余额见底403中断→充值恢复)：**章级 7344/7345 收官**(顽固59章分段抢救救回57、感言章#97/坏章#811诚实标注入库;唯一余量见库);fable5抽检(事实4.4/合同3.8/生长2.8/归并4.0,判"需修后再放量")→**4高2中全修+两轮存量回洗**(前缀去重/出场章全书重扫重建312卡/关系落点统一57卡/覆写回退拦截/越合同key裁剪38处/别名准入);定点修复7调用全过(4卡audit旧值合并/黄蜂针净化剥雷行天下/泰加+白色游魂2对并卡)。**关键机制修复(勿回退)**:max_tokens=512000(创始人拍板不设限;New-API按max_tokens预扣费,余额须≥并发×$0.154否则403)+chat()撞模型上限自适应降档(M2.7上限196608实测)+细纲守卫60字绝对豁免+升格failed窗重跑先撤销+连续2窗失败才停书+模型输出str防御。**compact时在跑(nohup脱离会话,勿重启)**:升格路(机动52+/80窗→深空116窗,日志/tmp/muse-b7-upgrade.log)+出卡双路(5书窗大纲续切→分型出卡,/tmp/muse-b7-cards[AB].log)+全局守护闸4700(/tmp/muse-b7-cards-main.log出STOP行=收尾)。跑完续跑序:check终检→review审核→export样张+升格样张(机动全书+深空末段压测数据)呈报创始人。固化脚本:parse_salvage.py(顽固章分段抢救)/parse_rewash.py(存量回洗)/parse_upgrade.py(作品面升格)。待创始人:样张过目、B3检索验证、B5确认门。
|
||||
- **批3-5 分批拆(2026-07-14,创始人逐批给额度)**：批3(501次→322章)、批4(1000次→572章,529升5%)、**批5 收尾(2000次自停零超支→1133章:星环250/机战510/超神373;M2.7救回281章,0硬停,529降至1.7%)**。压缩+敏感降级实测有效。**章级全局 5500/7345=75%**:机动673✓/深空593(仅#143)/超神1438(差17)/星环1194/机战1602。**待办**:批6待创始人发额度(剩余约1845章≈2100次可全收口章级)、深空#143顽固敏感(备用模型疑也撞,单独攻)、机动/深空章级已完成可进窗大纲+出卡。续跑序:章级完→window切窗大纲→cards分型出卡→check终检→review审核→export样张。
|
||||
- **参考书作品面数据入库（2026-07-14 创始人指令+同日认可开工）**：「这几本书本身也是被导入的作品,对应的数据也都需要入库」——**方案 v6 定稿并已批准：`docs/2026-07-14-参考书作品面数据入库方案.md`**。四轮独立评审+创始人五条反馈换核,核心机制=**全实体统一生长**(废v4「前15全卡/轻卡」分层——创始人质疑成立):一实体一卡(唯一键=作品×型×归一名×范围,范围恒「本书私有」),每窗「机械预扫在场实体→实体观察→判重(留档/别名→嵌入近邻→AI终判)→卡更新(只对有新信息,批≤6张)→关系增量」,字段三类演进(底色覆写留审计/演进追加带窗号/当前态保最新);两阶段合并:拆书期候选卡就地累积,创作期走变更提案(draft表entity_id/proposed_changes/snapshot三列原生支持);正文窗直抽(3-5万字/窗,同窗调用连发吃缓存);防膨胀双设计(索引=窗内机械预扫命中集不随书涨/观察输出超12新名或15章对半分段)。**5张升格工作表已建**(`db/ddl/94`:别名/出场留档/窗状态/卡水位/覆写审计)。作品面抽取估3000-4800次,**总额闸5000封顶**,试跑校准;全链从2026-07-14起约5900-8400次。**下一步**:首书机动风暴~10窗+深空末段3窗压测出样张→创始人过目→放量。M3无思考确认(实测reasoning_tokens=0,中位out=331),维持不开(质量已达标,思考按输出计费烧次数,深推理单点用强模型)。
|
||||
- **未决**：①机动残留变体与感言章处理方式②跨书同功母卡归并=放量后公共面课题③S5 参数 A/B（M3 输出方差根治口）④S6 pacing 书级抽取（等整本拆完,依赖全本+作品面入库）。
|
||||
- **教训入档**：StructuredOutput 工具 schema 属性名仅限 ASCII（中文键 API 400）——schema ASCII 键+入库脚本键名归一；Tailscale 长事务需 keepalive+批量写（逐行两万往返曾半死 16 分钟）。
|
||||
|
||||
## 九·旧（2026-07-10 快照，留档）
|
||||
|
||||
- 执行主线=§七闭环序，知识域（A/B）先行；创作域（C）后置，待 B5 过门后按 C 线走。
|
||||
- **拍板台账（①–④已全拍）**：①B2 首轮公共面只拆 5 型范式，双层型二轮凭脚手架实据定；细纲字数比例已拍入 outline schema。②已拍（2026-07-10）——参考书=`../小说清单/` 7 本**全部导入**私有库；首轮拆书 4 本：超神机械师/机战无限/深空之影/机动风暴（每本 30–50 章；原文只入私有库，公共面只有脱敏范式）。③已拍——主仓表原样不改列+私货全进 `example_*`。④已拍——整序确认，A1 已起跑（B2 跑批前有成本确认闸）。
|
||||
- **能力就位**：skill 16 只（基建 7：read-context/confirm/eval 现有+db/import/embed/search 按 A2–B3 交付；功能 9 全建成，对齐官方规范）× agent 5（已瘦身为身份段）；prompt 三段式（身份段×功能 skill×L0）；上下文=四层+章级基线包共享前缀+按 agent 差异矩阵（read-context skill 为准）；拆书=workflow 编排+逐章 agent 有界任务（parse-book skill 为准）。
|
||||
- **基座**：A1/A2 已收口（2026-07-13）——`muse-example` 库+pgvector 0.8.5 验通（容器重建恢复命令见连接信息），24 表建成（主仓一致 20 + `example_*` 4，映射与暂缓登记见 `db/表映射.md`），db skill 已交付；凭据与配方在 `db/连接信息.md`；`.venv` 丢失时按 requirements.txt 重建即用。
|
||||
- **待审资产已清零（2026-07-10 创始人清理）**：文件版首轮的 13 张范式卡、参考书档案 extracted 态、《焚忆》全部文件资产已清除，工作区（干净 clone）无任何待审存量；首轮拆书的字段设计发现已蒸馏入 `meta/schemas/`（已提交），不受影响。
|
||||
- 进度惯例：看 git log 与本节拍板台账，不设过程状态文档。
|
||||
所有任务从 [`AGENTS.md`](AGENTS.md) 开始。
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user