# agent-example

`agent-example` 的目标是成为 Muse 的单用户缩小版，以 PostgreSQL 为正式内容权威：ReAct Agent 通过角色 Agent、Skill 和确定性工具，完成长篇小说的作品管理、实体维护、范式复用、规划、写作、审核、用户决策和经验复利。代码与文档在 Git，正式内容在数据库。

本项目不包含管理员、多用户、租户、市场、计费和资产交易。完整 Muse 产品、业务和总体架构仍以父仓 [`../design-docs/`](../design-docs) 为准。

## 数据权威

核心合同是：

```text
PostgreSQL（muse-example 库） = 正式内容权威（作品 / 章 / 正文 / 实体 / 范式 / 用户决策 / 运行回执 / raw）
Git                           = 代码 / Skill / 文档 / DDL 的权威，并可对作品信息与作品文本留痕（历史 / 备份）
库内向量索引                   = 数据库一侧的检索加速，可从库重建
```

正式内容以库为准；Git 留痕不是权威，只读看板只读库，两者冲突时以库为准。可恢复性靠数据库备份，加上 Git 里的代码与 DDL 重建库结构。一切输入和产出都必须落库才能被看板看见。

## 三条正交轴

```text
内容：作品 + 实体 + 范式
流程：上下文组装 -> 创作 -> 质量审核 -> 用户决策 -> 复利
能力：Agent + Skill + Tool + 数据库存储 + 只读看板
```

领域边界、数据权威和验收合同见 [`muse/sot/domains/_index.md`](muse/sot/domains/_index.md)。框架执行端口见 [`framework/README.md`](framework/README.md)。该目录定义目标行为，不代表所有落库写入和只读看板已经完成实现。

## 当前工程入口

```text
agent-example/
├── AGENTS.md                # 项目工作入口与规则
├── CLAUDE.md                # 只引用 AGENTS.md 的兼容入口
├── framework/               # 框架无关执行对象与 Pi 适配器
├── .agent/                  # 角色身份与方法 Skill 挂载源
│   ├── agents/              # 角色 Agent
│   └── skills/              # 15 个方法 Skill 的嵌套源
├── muse/                    # Muse 业务平面
│   ├── sot/                 # 领域与角色合同 SoT
│   ├── content/             # 作品、实体、范式与结构 schema
│   ├── lifecycle/           # 上下文、流程、质量与 harness
│   ├── authority/           # DB、证据、Studio 与只读工具
│   └── platform/            # 共享连接、模型、嵌入包
└── docs/                    # 单次任务资料、评测样张和历史执行证据
```

正式内容在 PostgreSQL，不在 `content/` 文件目录。判断有没有某个内容，以库里能不能查到为准；不得把库外文件或临时快照说成正式内容。

## 正向创作

```text
用户意图
  -> 读取作品、实体和范式
  -> 冻结角色上下文
  -> 规划/写作 Agent 产生 Shadow 候选
  -> 确定性检查、语义检测和质量审核
  -> 用户原样接受、修改后合并或丢弃
  -> 正式正文（写入库内正文块）
  -> 实体草稿、范式观察和复利验证
```

Gate A/B 是开发期离线能力验收，不是正常用户写一章的生产主流程。评测候选固定不可进入 Canonical。

## SoT 顺序

1. 父仓 `design-docs/`：完整 Muse 产品、业务和总体架构。
2. 本仓 `muse/sot/domains/`：单用户、数据库为权威的领域边界。
3. `muse/content/meta/` 与 `muse/lifecycle/flow/chains/`：结构本体和功能链登记。
4. `.agent/agents/`、`.agent/skills/` 与 `muse/_skills_index.md`：角色、方法与编排能力合同。
5. `docs/`：单次任务过程、评测资料与执行证据，不覆盖稳定 SoT。

所有任务从 [`AGENTS.md`](AGENTS.md) 开始。