4adc85cafd
- 八个领域 SoT + 索引：正式内容权威从 Git 文件改为 PostgreSQL；Git 退回代码/文档/DDL 权威，可对作品信息与文本留痕但非权威。 - 立横切合同：一切输入产出必须落库可见；raw 进库可看全文（访问控制）。 - 08 更名为数据权威与可视化领域；新增独立 可视化模块合同（只读查库渲染，绝不写）。 - AGENTS.md / README.md 同步翻面。
100 lines
7.1 KiB
Markdown
100 lines
7.1 KiB
Markdown
# 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)
|