muse-agent-example/README.md

agent-example（Muse 单用户版）

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

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

新版工程入口（当前）

# 安装（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 起接入真实后端。

作者工作台与结构入口

运行配置草案使用提供方模板，经CLI保存到所选用途的数据库：

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

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

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

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

# 发布包内工作台；公开地址和写入来源必须与浏览器实际访问地址一致
.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；恢复由服务端登记的流程检查来源、结构、授权与预算，缺少对应业务处理器时明确拒绝。

当前工作台可新建作品、编辑动态档案、添加章节并手写正文。正文自动保存保留版本；冲突时先比较服务器稿件，回退会生成新版本。未提交的正文缓冲留在当前浏览器，重开时先与服务器基线比较。候选可审阅、编辑和部分选择；分支合并先生成候选，采纳时复检两端来源。

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

.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 与生成合同 定义。作者身份取自配置或会话；正文草稿使用受限文档树，不提交编辑器HTML。

审校与选段修订

正文页可圈选修改范围和保护区，选择扩写、压缩、润色或重写目的，发起一次受控写手任务。机器味修改从真实诊断和作者点名批准的发现出发。两条路径均只生成待审候选，保真失败或原文胜出保留原文。模型任务须已装配对应流程、选择已验证配置并批准额度。

.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>
# 只回放输入副本，不读取数据库配置；输出JSON可重定向到单独报告文件
.venv/bin/python -m muse 审校 - 修订回放 <离线请求.json> --离线

请求字段由审校操作及离线回放定义。离线产物不证明当前生产状态或模型文学收益，也不能作为正式批准；规则/方法正式启用仍须完成对应评测与批准链。

新库配置与迁移

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

.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 装配执行。缺凭据不会回退默认库。

参考分析与历史承接

uv run muse 研究 /private/作者配置.toml 进度 <来源ID>
uv run muse 研究 /private/作者配置.toml 分析 <分析ID>
uv run muse 研究 /private/作者配置.toml 承接 <已完成研究任务ID>

完整分析结果由B03保存。S02只保存执行证据与分析引用；旧任务显示history_not_imported时，明确运行承接命令才能转存，查询不会隐式写库。承接核原来源、全部窗口和归并，不创建任务或重跑模型。旧参考卡经旧库迁移入口导入为未决分析；保存或模型分析完成都不等于作者确认、当前生成资格或真实资料迁移验收。

过渡期旧实现

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

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

旧正式库（mini-infra 100.64.0.8:5433/muse-example）与旧 SQLite 账本（data/muse.db）对新实现冻结为只读参照；切换按 切换与回退 执行。旧测试树由旧环境运行，两套收集互不接管。

目录速览

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 与 .agent/rules/测试隔离.md。

所有任务从 AGENTS.md 开始。

正文候选

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

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

故事事实接口

新版提供 /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>核对最终格式；格式失败非零，方向确认与正式规划仍是独立动作。操作细节见完善故事基础设定。

整理稿通过格式检查后，可以明确选定为某部作品的规划依据。选定 <请求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>回查正式内容。详见确认规划候选。当前这一入口用于人工规划；模型生成、卷与场景节点、近期细化仍在W13实施中。

质量案例与行为观察

“审校 <作者配置> 案例采集/案例审阅/案例决定/案例撤回 <请求JSON>”调用同一B06/S01链；“案例 <case_id>”与“案例清单”只读查询。采集只形成待复核案例，真实引用的字段与许可见案例操作合同。四类跨书确认案例可经“案例规则 <请求JSON>”提出候选，不能直接启用。

“行为评测 <场景JSON> --适配器 scripted --观察 <观察JSON>”核对逐例动作、报告结构和前后文档哈希。省略适配器时不会以脚本替代真实角色调用；当前真实角色尚未接入，返回明确失败。场景固定输入见六类合成场景，真实服务边界与模型行为证据分别记录。