# 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 负责**；只读可视化模块只查库、只渲染，不写任何数据。
- **单一基底、分层权威、分区治理**：库是唯一存放处（基底统一），但正式内容与评测区是**不同治理区**。评测的独立性由 `run_type` + 四层隔离 + oracle + 盲评 + 人审承载，**不由物料位置承载**。“一切落库”是基底主张，不是“库是无差别统一体”。（harness 改造原则，见 [docs/2026-08-01-评测harness改造设计](../../../docs/2026-08-01-评测harness改造设计.md)）

## 4. 只读可视化模块

- 一个纯 Python 标准库的本地 web 看板（web 层零框架、零新增依赖；psycopg 复用 `.venv` 现成的，非标准库），内网或 Tailscale 访问，形态参照 open-wenmo。
- 只对数据库做只读查询并渲染，**不触发任何写操作**；接受、丢弃等写操作仍由 `决定正文候选去留` 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
用户意图
  -> 创作流程域前期阶段：定盘 -> 大纲/卷纲 -> 设定拆条 -> 范式与文风 -> 细纲
     （各阶段候选先 shadow、用户确认翻 confirmed 才进生成上下文；详见 05 §1A）
  -> 作品域提供目标、规划与最新正式正文
  -> 实体域提供正式事实和叙事状态
  -> 范式域提供经验证的写法参考
  -> 上下文域从库里选择、裁剪、冻结并投影
  -> Agent/Skill 域执行规划、写作、检测和审核
  -> 创作流程域维护候选、用户决策与正式正文边界
  -> 质量与复利域产出检查、审核、实验和升格结论
  -> 数据权威域把上述一切输入产出落库
  -> 只读看板随时把库里的状态渲染给人看
```

模型运行失败可以阻断当次 AI 任务，但不能损坏库里已有的作品、实体、范式。库内检索加速失败只影响速度，不改变内容语义、不跳过审核。

## 8. raw 边界（已翻转）

- 完整 Prompt/Response、未接受候选正文、标准答案、原书全文、供应商原始响应：**进库**（单独表 + 访问控制），只读看板可看全文。
- 不再要求 raw 留仓外；仓外 vault 降级为可选备份，不是合同要求。
- 密钥、token 和外部凭据仍不得写进内容表或运行报告；连接凭据按内网授权方案放在 Git 侧的受控文档里。

## 9. 明确不做

- 不实现管理员控制台、租户、角色权限、市场、计费、资产交易或多用户协作。
- 不复制父仓完整业务有界上下文。
- 可视化模块不写库。
- 不做多租户参考书授权机制：`muse/authority/db/ddl/96` 授权快照表**不启用**（单用户本地，授权人/使用者/机器是同一人，重型授权合规是从父仓过度继承）；参考书出处与导入信息用 `example_reference_work` / `muse_knowledge_document` 即可（2026-07-30 拍板）。
- 不再声称 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)