# agent-example（Muse 单用户版）

Muse 的单用户缩小版：AI 驱动的长篇创作工具。**正在按新版设计改造**（见 [`docs/系统架构/新版设计/阅读指南.md`](docs/系统架构/新版设计/阅读指南.md) 与 [改造计划](docs/系统架构/新版设计/改造计划/总计划.md)），新版工程骨架已落地，业务能力按工作包逐步交付。

正式内容权威是 PostgreSQL；Git 是代码、技能、文档与 DDL 的权威。本项目不含管理员、多用户、租户、市场、计费与资产交易。

## 新版工程入口（当前）

```bash
# 安装（uv 管理 .venv 为新版仓内解释器）
make 安装
make 前端安装  # 使用 web/pnpm-lock.yaml；生成和索引核对需要 Node/TypeScript

# 日常检查：格式 + 类型 + 索引一致性
make 检查
make 前端检查
make 前端测试

# 离线测试（默认 OS 进程隔离，未标记外部环境的用例禁止联网连库）
make 测试
make 测试 用例=TC-a5c7d4adafe3   # 按稳定用例 ID 选择单例

# 隔离数据库测试（需先导出 MUSE_TEST_DATABASE_URL，缺变量直接失败）
make 数据库测试

# 实际Pi SDK整链：另需MUSE_PI_NODE与MUSE_PI_PACKAGE，固定Pi 0.84.4、Node至少22.19.0
# 这些是本地运行路径；提供方使用合成HTTP，不调用外部模型
make 宿主测试

# 生成（资源包 / 接口合同 / 索引）与构建发布包
make 生成
make 构建
```

- 新版源码：`src/muse/`（模块化单体，中文模块名；公共接口在各模块 `接口.py`）。
- 新版测试：`tests/单元|契约|集成|架构/`，用例以完整 `case_id` 绑定实际文件、符号与参数行；六位后缀只辅助阅读。
- 工程工具：`工具/`（资源打包、接口生成、索引检查），登记输入在 `工具/资源登记.json` 与 `工具/生成输入.json`。
- 前端工作台（React/TS）：`web/`，随 W07 起接入真实后端。

## 作者工作台与结构入口

运行配置草案使用[提供方模板](配置/提供方.example.toml)，经CLI保存到所选用途的数据库：

```bash
.venv/bin/python -m muse 配置 <私人应用配置.toml> 保存 <配置ID> <版本> --内容 <运行配置草案.toml>
.venv/bin/python -m muse 配置 <私人应用配置.toml> 查看 <配置ID> <版本>
```

保存与查看不会自动启用。任务执行从已验证启用并绑定的版本装配；生产能力验证器和对应的作者启用流程仍在实施，不能用离线配置检查替代。

复制 `配置/应用.example.toml` 到私人配置目录，将数据库连接和工作台口令分别保存在该目录的受控文件中。相对凭据地址以配置文件所在目录为起点。

先运行`.venv/bin/python 工具/环境预检.py`取得当前`resource_build_id`，填入私人配置的资源发布身份。执行任务固定这一构建；换装资源后已有任务不能静默改用新版。

```bash
# 发布包内工作台；公开地址和写入来源必须与浏览器实际访问地址一致
.venv/bin/python -m muse 服务 <私人作者配置.toml>

# 维护配置发布固定种子；重复发布幂等，不启用任何实例绑定
.venv/bin/python -m muse 结构 <私人维护配置.toml> 发布内置
.venv/bin/python -m muse 结构 <私人作者配置.toml> 查看 character --版本 1
.venv/bin/python -m muse 结构 <私人作者配置.toml> 维护 <结构请求.json>

.venv/bin/python -m muse 任务 <私人作者配置.toml> 列表
.venv/bin/python -m muse 任务 <私人作者配置.toml> 查看 <任务ID>
.venv/bin/python -m muse 任务 <私人作者配置.toml> 控制 <控制请求.json>
```

任务控制 JSON 使用 `command_id`、`target_ref`、`expected_state`、`action`，其中 action 为“暂停”“取消”或“恢复”。重试同一请求保留 command_id；恢复由服务端登记的流程检查来源、结构、授权与预算，缺少对应业务处理器时明确拒绝。

当前工作台可新建作品、编辑动态档案、添加章节并手写正文。正文自动保存保留版本；冲突时先比较服务器稿件，回退会生成新版本。未提交的正文缓冲留在当前浏览器，重开时先与服务器基线比较。候选审阅、引用选择与作品结构升级仍在实施，不能将人工主链通过视为完整创作链完成。

人工命令与网页复用同一业务入口：

```bash
.venv/bin/python -m muse 作品 <私人作者配置.toml> 结构 <作品ID> --结构 work_core --版本 1
.venv/bin/python -m muse 作品 <私人作者配置.toml> 保存档案 <档案请求.json>
.venv/bin/python -m muse 作品 <私人作者配置.toml> 新增章节 <章节请求.json>
.venv/bin/python -m muse 作品 <私人作者配置.toml> 保存正文 <正文请求.json>
.venv/bin/python -m muse 作品 <私人作者配置.toml> 正文 <章节ID>
.venv/bin/python -m muse 作品 <私人作者配置.toml> 回退正文 <回退请求.json>
```

请求外壳由 [`创作操作.py`](src/muse/接入/创作操作.py) 与[生成合同](docs/接口契约/生成/openapi.generated.json) 定义。作者身份取自配置或会话；正文草稿使用[受限文档树](docs/系统架构/新版设计/接口契约/正文结构与中文选区.md)，不提交编辑器HTML。

## 新库配置与迁移

清理当前配置的无租约暂存与读取回执：

```bash
.venv/bin/python -m muse 管理 <私人应用配置.toml> 清理无租约暂存
.venv/bin/python -m muse 管理 <私人应用配置.toml> 查看清理回执 <对象ID>
```

该操作保留已登记租约、未知资料和其他命名空间。旧的非空未标记目录须先按迁移合同承接，不能直接交给新版清理器。

按 `配置/应用.example.toml` 配置连接引用和用途。三类角色由管理员使用 `数据库/初始化/用途角色.sql` 显式创建，独立目标库交由 `muse_maint` 所有；应用迁移不创建角色。`muse_app` 处理业务对象，`muse_eval` 处理评测对象，生产角色不能读取 oracle。

`make 生成` 将迁移投影到包内；`make 迁移 配置=<私人维护配置路径>` 通过 maintenance 装配执行。缺凭据不会回退默认库。

## 过渡期旧实现

旧实现位于原工作树的 `muse/`、`framework/`、`runtime/`、`web/app.py`。新版在隔离工作树使用自己的 `.venv`；原工作树的旧 harness 仍沿原 `.venv` 路径启动，须保持该路径连接旧依赖环境。旧环境可依据 `requirements.txt` 重建：

```bash
uv pip install --python .venv/bin/python -r requirements.txt
```

旧正式库（mini-infra `100.64.0.8:5433/muse-example`）与旧 SQLite 账本（`data/muse.db`）对新实现冻结为只读参照；切换按 [切换与回退](docs/系统架构/新版设计/改造计划/切换与回退.md) 执行。旧测试树由旧环境运行，两套收集互不接管。

## 目录速览

```text
agent-example/
├── AGENTS.md          # 项目工作入口（唯一事实源）
├── CLAUDE.md          # 兼容入口，只引用 AGENTS.md
├── src/muse/          # 新版模块化单体（装配、共享基础、业务模块随包落地）
├── tests/             # 新版测试（单元/契约/集成/架构 + 夹具）
├── 工具/              # 工程生成与检查入口
├── 配置/              # 无凭据配置模板
├── web/               # 新版 React/TS 作者工作台（随包建设）
├── 数据库/            # 新版迁移（随 W03 起）
├── muse/ framework/ runtime/   # 旧实现（验收后逐步退出）
├── .agent/            # 智能体能力中枢（规则、约束、规范、技能）
├── docs/              # 设计 SSOT、任务资料与执行证据
└── data/              # 运行态数据（旧 SQLite 账本与参考原文，gitignore）
```

## 验证纪律

完成 = 机械验证：无自动化绿证据不得声称完成。测试默认离线禁网禁库；空收集、全跳过、超时与缺依赖都如实呈现，不冒充通过。详见 [`docs/系统架构/新版设计/改造计划/执行与验收.md`](docs/系统架构/新版设计/改造计划/执行与验收.md) 与 [`.agent/rules/测试隔离.md`](.agent/rules/测试隔离.md)。

所有任务从 [`AGENTS.md`](AGENTS.md) 开始。
## 正文候选

章节保存后可进入“比较正文候选”，另拟改稿、编辑候选或按段选择改动。候选保存只增加候选版本；打开审阅后，作者可采纳为正文新版本、拒绝或暂缓。当前人工候选只做格式与版本校验，模型生成与关联事实采纳随相应创作流程接入。

CLI 使用 `.venv/bin/python -m muse 审阅 <作者配置> 列表 <章节ID>` 定位；`查看 <候选ID>` 读取候选，`打开 <请求JSON>` 取得固定审阅。`建立候选`、`修改候选` 与 `决定` 的请求合同和执行说明见[决定正文候选去留](.agent/skills/操作/决定正文候选去留/SKILL.md)。

## 故事事实接口

新版提供 `/api/v1/works/{work_id}/facts/schema` 预览事实结构，`/fact-proposals` 创建提案；通过 `/api/v1/fact-proposals/{proposal_id}/reviews` 打开审阅，再向 `/decisions` 提交作者决定。来源使用确切正文版本及段落引文。提案保存不产生正式事实，确认使用与正文相同的S01事务机制。

`/api/v1/works/{work_id}/facts` 按稳定章节身份 `as_of`、事实域确认版本 `system_revision` 和 `view=author|reader|character` 查询；角色视角同时提供 `character_id`。事实、猜测、计划分别返回。作者总览支持后文对早期事件的说明，早期读者查询不会提前得到后文披露。完整世界维护页面随W19接入。

## 私人探索稿

作者配置中的`文件.探索草稿`指定私人目录。工作台从“先记下一个想法”进入探索页，可保存原话、刷新恢复输入，保存冲突时先比较当前稿。草稿不进入正式作品列表、规划或生成上下文。

`.venv/bin/python -m muse 探索 <作者配置> 列表`及`查看 <稿件ID>`读取私人稿；`保存 <请求JSON>`接受draft_id、title、content、expected_hash。新稿expected_hash为null。整理后用`检查 <稿件ID> --预期哈希 <draft_hash>`核对最终格式；格式失败非零，方向确认与正式规划仍是独立动作。操作细节见[完善故事基础设定](.agent/skills/操作/完善故事基础设定/SKILL.md)。

整理稿通过格式检查后，可以明确选定为某部作品的规划依据。`选定 <请求JSON>`提交command_id和selection（work_id、draft_id、expected_hash、expected_revision）；`查看选定 <作品ID>`读回服务器保存的作者、时间和确切快照。修改私人稿不会改变这份已选来源，正式规划候选仍须单独确认。
## 人工规划候选

`.venv/bin/python -m muse 规划 <作者配置> 结构 <作品ID> --结构 outline --版本 1`读取固定规划结构。`创建候选 <请求JSON>`使用command_id和request；request包含work_id、expected_revision、schema和动态content。候选保存不会产生正式规划。

`查看候选`、`打开审阅`和`决定`完成作者明确确认，`查看 <规划ID>`或`列表 <作品ID>`回查正式内容。详见[确认规划候选](.agent/skills/操作/确认规划候选/SKILL.md)。当前这一入口用于人工规划；模型生成、卷与场景节点、近期细化仍在W13实施中。