b9af240b68
- 章后处理：事实提案命令身份加入类型、批内去重改为先校验后去重（REPEAT_OBJECT_TYPE 记跳过、不再静默丢重复）；查询章后状态回传事实跳过；可按需发布/核对可登记任务与 config_not_declared 语义收紧 - 模型治理：推理字符数计量（ChatCompletions/Messages/执行合同）、探针在声明关闭推理却仍有推理时拒绝、计价支持缓存协议与未知模型兜底 - 运行态：资源包重建（发布身份 21d850f7…），三处配置同步，post-extract v5 代次 5 启用，服务 PID 96675（health/ready 通过） - 门禁：make 检查通过；离线 1008 passed；定点数据库 101 passed；最终完整备份 bkp-1f5591d8… 与空库恢复演练 verified（152 表/158 关系/迁移 45，演练库已 DROP） - 文档与证据：运行手册、功能覆盖、工作包清单 W30 证据、测试用例清单（17 条 execution_evidence 回填 + 历史死指针说明）、目标文件清单 - 旧实现与旧库直连材料退出（含明文凭据文件移除）；新配置 配置/本机正式.toml、配置/本机维护.toml、配置/计费/、配置/运行配置/ 入库，均只含受控引用 - R2 执行证据在 .agents.local/改造/R2-20260909/（不入库）
293 lines
29 KiB
Markdown
293 lines
29 KiB
Markdown
# agent-example（Muse 单用户版）
|
||
|
||
Muse 的单用户缩小版：AI 驱动的长篇创作工具。**正在按新版设计改造**（见 [`docs/系统架构/新版设计/阅读指南.md`](docs/系统架构/新版设计/阅读指南.md) 与 [改造计划](docs/系统架构/新版设计/改造计划/总计划.md)），新版工程骨架已落地，业务能力按工作包逐步交付。
|
||
|
||
正式内容权威是 PostgreSQL；Git 是代码、技能、文档与 DDL 的权威。本项目不含管理员、多用户、租户、市场、计费与资产交易。
|
||
|
||
## 新版工程入口（当前）
|
||
|
||
日常运行、备份恢复与排障见[运行手册](docs/运行手册.md)。
|
||
|
||
```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.85.1、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>
|
||
.venv/bin/python -m muse 任务 <私人作者配置.toml> 预算 <任务ID>
|
||
.venv/bin/python -m muse 任务 <私人作者配置.toml> 批准额度 <任务ID> --额度文件 <额度请求.json>
|
||
.venv/bin/python -m muse 任务 <私人作者配置.toml> 推进 <任务ID>
|
||
```
|
||
|
||
任务控制 JSON 使用 `command_id`、`target_ref`、`expected_state`、`action`，其中 action 为“暂停”“取消”或“恢复”。重试同一请求保留 command_id；恢复由服务端登记的流程检查来源、结构、授权与预算，缺少对应业务处理器时明确拒绝。
|
||
|
||
HTTP和CLI默认登记生成、规划、拆书、章后、完整审校及修订的真实处理器；明确发起任务时按需载入包内流程。启动服务不连接模型，也不批量派发任务。“推进”只执行任务冻结计划中的一个步骤，前置、租约、预算和来源仍由原业务接口核对。
|
||
|
||
首次使用某个运行配置的额度账户，先明确五小时窗口的支出和次数上限，用 `muse 管理 <作者配置> 登记额度 <账户JSON>` 登记。账户JSON严格包含 `account_id`、`version`、`window_usd`（金额字符串）、`window_calls`（正整数）；账户必须对应运行配置的预算引用。相同版本重复登记幂等，不覆写既有策略。
|
||
|
||
每个任务再单独批准额度：请求固定 `command_id`、`max_cost_usd`、带时区的未来 `valid_until`，以及覆盖任务实际模型角色的 `roles`。每项包含 `role`、`max_calls` 和 `per_call_usd`；金额须为正数。先通过“预算”读取任务角色，也可在任务页填写并批准。批准不会执行任务；冻结后不能借重试改大额度。当前账本的支出上限不表示费用已知，提供方用量或计价缺失仍保留未知状态。
|
||
|
||
当前工作台可新建作品、编辑动态档案、添加章节并手写正文。正文自动保存保留版本；冲突时先比较服务器稿件，回退会生成新版本。未提交的正文缓冲留在当前浏览器，重开时先与服务器基线比较。候选可审阅、编辑和部分选择；分支合并先生成候选，采纳时复检两端来源。
|
||
|
||
人工命令与网页复用同一业务入口：
|
||
|
||
```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> 选段定位 <坐标请求.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> --离线
|
||
```
|
||
|
||
请求字段由[审校操作](src/muse/接入/审校操作.py)及[离线回放](src/muse/审校修订/离线回放.py)定义。离线产物不证明当前生产状态或模型文学收益，也不能作为正式批准；规则/方法正式启用仍须完成对应评测与批准链。
|
||
|
||
固定返修候选可单独进行双评委比较，不再生成另一份文本冒充被评候选：
|
||
|
||
```bash
|
||
muse 评测 <维护配置.toml> 发布返修数据集 <来源请求.json> --来源配置 <作者配置.toml>
|
||
muse 评测 <评测配置.toml> 创建返修比较 <实验请求.json>
|
||
muse 评测 <评测配置.toml> 启动实验 <启动请求.json>
|
||
muse 评测 <评测配置.toml> 执行工作面 <实验ID>
|
||
muse 任务 <评测配置.toml> 推进 <工作面中的任务ID>
|
||
muse 评测 <评测配置.toml> 导出返修证明 <实验ID> --维护配置 <维护配置.toml>
|
||
muse 审校 <作者配置.toml> 返修比较证明 <比较回执ID>
|
||
```
|
||
|
||
来源请求固定返修会话、轮次、实际候选、批准引用和有效期；实验请求固定数据集及哈希、两份独立judge配置、维度和预算。请求结构见[B10固定返修比较合同](docs/系统架构/新版设计/模块设计/B10-效果评测.md)。评测任务也可在evaluation工作台按“执行下一步”推进，每次只执行一个冻结步骤；缺少计价仍记录未知费用。
|
||
|
||
返修页可按回执读取比较记录、未完整或未标定原因，作者仍可保留原文。维护/来源连接只由本地显式配置选择，HTTP不接受服务器凭据路径。当前发布策略只有单一固定评委模型，真实双模型执行须先解决角色策略冲突；隔离合成测试不替代真实模型验收，也不授予生产启用许可。
|
||
|
||
## 新库配置与迁移
|
||
|
||
清理当前配置的无租约暂存与读取回执：
|
||
|
||
```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 装配执行。缺凭据不会回退默认库。
|
||
|
||
## 参考分析与历史承接
|
||
|
||
```bash
|
||
uv run muse 研究 /private/作者配置.toml 进度 <来源ID>
|
||
uv run muse 研究 /private/作者配置.toml 分析 <分析ID>
|
||
uv run muse 研究 /private/作者配置.toml 承接 <已完成研究任务ID>
|
||
```
|
||
|
||
完整分析结果由B03保存。S02只保存执行证据与分析引用；旧任务显示`history_not_imported`时，明确运行承接命令才能转存，查询不会隐式写库。承接核原来源、全部窗口和归并，不创建任务或重跑模型。旧参考卡经[旧库迁移入口](docs/系统架构/新版设计/数据模型/旧知识记录分流.md)导入为未决分析；保存或模型分析完成都不等于作者确认、当前生成资格或真实资料迁移验收。
|
||
|
||
## 旧实现已完全退出
|
||
|
||
旧实现（`muse/` 主体、`runtime/`、`framework/`、`tests/skills/` 等旧代码与测试）已完全退出；`muse/sot/角色合同.md` 已迁入 [`.agent/角色/角色合同.md`](.agent/角色/角色合同.md)。历史内容见 git 与[现有文件处置清单](docs/系统架构/新版设计/现有文件处置清单.json)，不再作为运行入口。旧正式库（mini-infra `100.64.0.8:5433/muse-example`）对新实现冻结为只读参照。
|
||
|
||
## 目录速览
|
||
|
||
```text
|
||
agent-example/
|
||
├── AGENTS.md # 项目工作入口（唯一事实源）
|
||
├── CLAUDE.md # 兼容入口，只引用 AGENTS.md
|
||
├── src/muse/ # 模块化单体（装配、共享基础与全部业务域）
|
||
├── tests/ # 自动化测试（单元/契约/集成/架构/迁移/端到端 + 夹具）
|
||
├── 工具/ # 工程生成与检查入口
|
||
├── 配置/ # 无凭据配置模板
|
||
├── web/ # React/TS 作者工作台
|
||
├── 数据库/ # 数据库迁移脚本与旧库迁移工具链
|
||
├── .agent/ # 智能体能力中枢（规则、约束、规范、角色合同、技能）
|
||
├── docs/ # 设计 SSOT、系统架构、运行手册与历史执行记录
|
||
└── data/ # 运行态数据（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实施中。
|
||
|
||
## 质量案例与行为观察
|
||
|
||
“审校 <作者配置> 案例采集/案例审阅/案例决定/案例撤回 <请求JSON>”调用同一B06/S01链；“案例 <case_id>”与“案例清单”只读查询。采集只形成待复核案例，真实引用的字段与许可见[案例操作合同](.agent/skills/操作/记录机器味案例/references/案例合同.md)。四类跨书确认案例可经“案例规则 <请求JSON>”提出候选，不能直接启用。
|
||
|
||
“行为评测 <场景JSON> --适配器 scripted --观察 <观察JSON>”核对逐例动作、报告结构和前后文档哈希。角色模式显式提供`--配置 评测.toml --业务配置 合成资料.toml --动作 准备 --目标 请求.json`，固定S02任务并返回可审请求；`--动作 执行/报告 --目标 任务ID`分别点名执行与读回。请求字段见[角色行为命令](src/muse/接入/cli/角色行为命令.py)，缺少配置不回退脚本。场景固定输入见[六类合成场景](tests/夹具/行为评测/诊断机器味场景.json)，runtime_verified仅证明实际工具协议，合成调用不认证真实外部模型行为。
|
||
|
||
## 隔离数据集与实验条件
|
||
|
||
方法的合格评测证明须先运行`评测 <评测配置> 导出启用凭据 <请求JSON> --维护配置 <同库维护配置>`，请求含experiment_id、approval_ref和valid_until。导出不会启用方法；在方法详情页填写凭据编号，核对已测版本后再确认启用写手用途。停止来源实验或标定会阻断新启用与新消费，历史记录保留。合成验证不作为真实外部模型效果验收。
|
||
|
||
方法写手对照先运行`评测 <维护配置> 发布方法数据集 <请求JSON>`，由B04读取确切确认版本；用返回的`method_target`创建实验。两臂共享写手模板，只在处理组加入获准方法投影。请求与边界见[B10方法版本对照](docs/系统架构/新版设计/模块设计/B10-效果评测.md#方法版本对照)，不改变方法启用状态。
|
||
|
||
`python -m muse 评测 <维护配置> 发布数据集 <数据集JSON>`封存公开输入与私有答案。同版本只允许原样重放，新版按序追加。`评测 <评测配置> 创建实验 <实验JSON>`固定数据集、样本分割、目标哈希与实际S02配置版本；实验JSON包含`command_id`和`request`。字段分别见[数据集合同](src/muse/效果评测/数据集.py)与[实验条件](src/muse/效果评测/实验条件.py)。两种配置都需明确本地操作者，数据库用途分别为maintenance和evaluation。
|
||
|
||
`数据集 <版本ID>`、`实验 <实验ID>`与`生成输入 <实验ID> --样本 <样本ID>`读回已保存记录。HTTP共用相同用例，入口位于`/api/v1/evaluation/datasets`和`/api/v1/evaluation/experiments`，沿用作者会话及来源校验。registered只表示条件已登记。
|
||
|
||
`评测 <评测配置> 启动实验 <启动JSON>`接受`experiment_id`及`request`，后者明确`approval_ref`和带时区的未来`deadline`。启动在同一事务创建固定生成任务、配置和预算；S02工作进程执行后，`推进实验 <实验ID>`登记已满足前置的比较任务。`执行工作面 <实验ID>`读回全部单元、实际交付、失败和费用；`取消实验 <实验ID>`先保存停止决定，再收敛剩余任务。HTTP对应实验下的`/execution`、`/advance`与`/stop`。当前适配范围见[B10固定执行合同](docs/系统架构/新版设计/模块设计/B10-效果评测.md)，执行状态不授予启用许可。
|
||
|
||
`评测 <评测配置> 报告 <实验ID>`或`GET /api/v1/evaluation/experiments/{实验ID}/report`从真实逐例记录重算报告。固定分母、来源分组、逐维分歧、所有调用费用和缺失项均保留；未知总成本与未标定文学指标显示为空。报告含原调用引用及内容哈希，读报告不触发新的模型调用或启用。
|
||
|
||
文学评分实验设置`comparison_profile: "writer_rubric"`，固定五维、两名初评`judges`和一名候补`arbitrator`，预算需覆盖全部潜在单元。样本的共同依据随数据集封存；真实回放的`judging`只声明场景、事实断言和约束，正文与细纲从B09已选材料生成。双评稳定时无需第三评；规定分歧触发第三评，原始评分与分歧同时保留。评分收敛不等于完成文学标定或允许启用，字段和边界见[B10文学执行合同](docs/系统架构/新版设计/模块设计/B10-效果评测.md)。
|
||
|
||
标定实验使用`calibration`分割并明确`calibration_policy`。全部候选生成后，运行`评测 <维护配置> 发布金标准 <标注JSON>`，完整绑定这些候选的输出哈希、五维分数和事实/约束标注；评委在金标准封存后才可推进，且看不到标注。`评测 <评测配置> 标定 <实验ID>`读取逐调用偏差，`封存标定 <实验ID>`保存已完成的合格或失败记录。报告页也可查看并保存标定记录；这不等于批准方法或规则启用。
|
||
|
||
资格实验在创建请求中设置`evaluation_goal: "qualification"`，使用独立`holdout`及`calibration_use`（所需策略、原标定实验ID和凭据哈希）。服务核验所有实际评委的标定，报告可追查各自来源；申请资格评测尚不代表效果或启用通过。字段与拒绝条件见[B10标定消费合同](docs/系统架构/新版设计/模块设计/B10-效果评测.md)。
|
||
|
||
正文效果实验可预注册`effect_policy: "writer-effect-v1"`并选择独立`detector`。`评测 <评测配置> 效果判据 <实验ID>`读取工程与效果阈值、场景/角色分层及明确的证据不足原因；`封存效果 <实验ID>`仅保存通过的统计凭据。工作台同样可读回和保存。分层字段及标准以[B10效果判据合同](docs/系统架构/新版设计/模块设计/B10-效果评测.md#固定效果判据)为准，统计记录不直接批准正式启用。
|
||
|
||
使用评测用途配置启动工作台后，从“效果评测”进入`/evaluations`，输入已有实验编号查看报告。页面可展开每个样本的独立判断与全部调用费用；刷新只重新读取报告。实验创建和执行批准沿上述CLI/HTTP入口办理。
|
||
|
||
正文来源对照先用`评测 <维护配置> 发布回放数据集 <请求JSON>`或`POST /api/v1/evaluation/replay-datasets`封存资料。请求按[回放数据集合同](src/muse/效果评测/数据集.py)声明样本、分割、许可引用、批准及到期时间；每例按[B09材料选择](src/muse/上下文/回放材料.py)指定作品、目标章、历史文稿版本和预算。A使用历史正文，B使用卡片索引，C使用索引及关联正文；目标正文只进入答案区。评测账号不能直接读取正式正文表。
|
||
|
||
这类实验使用`kind=code`、`target_ref=B09.writer-replay`，目标版本和内容哈希均指向实际安装构建身份，实验臂为A/B/C。比较覆盖三组文本对，报告以A/C为主，其余两组单列诊断；调用上限需覆盖三次生成及每名评委的三次比较。实验期限不得超过资料批准期限，字段策略变化阻止新派发。真实文学标定和启用判断仍须独立证据，不能把合成提供方或读取报告当作通过。
|
||
|
||
评测实验可用`max_judge_corrections`固定0—2次引文纠正（默认1，实际次数还受原调用配额约束）。工作面和报告保留每次判断拒绝、实际费用及单元纠正上限。若S02已经保存而实验登记中断，恢复会要求先补登原交付；不要通过重建调用替换已发生回合。以评测用途配置运行`muse 评测 <配置.toml> 补登记交付 <请求.json>`，请求包含`unit_id`、`call_id`和原始`output`对象；HTTP对应`POST /api/v1/evaluation/deliveries/restore`。服务核对原S02回合哈希，只在暂停或失败任务补登，原样重放幂等，已停止实验拒绝新增结果。
|
||
|
||
<!-- W28 deployment -->
|
||
## 规则验证与运行观察
|
||
|
||
规则的确定性验证独立于文学盲评，不调用模型。维护者先封存确切规则版本、许可、独立保留集和人工金标；使用同一作者的明确配置，不从生产配置推导其他用途的连接。
|
||
|
||
```bash
|
||
muse 评测 维护.toml 发布规则样本 规则样本.json --来源配置 作者.toml
|
||
muse 评测 评测.toml 验证规则 <数据集版本ID>
|
||
muse 评测 评测.toml 规则验证报告 <运行ID>
|
||
muse 评测 维护.toml 导出规则凭据 凭据导出.json
|
||
muse 审校 作者.toml 规则状态 <规则ID>
|
||
```
|
||
|
||
凭据导出请求含`run_id/approval_ref/valid_until`。未知、缺样本、合成来源或任一逐例失败均不生成可启用凭据；声明的来源许可与金标仍由维护者负责。工作台“诊断规则”页可点名凭据打开审阅，作者确认后才启用；停用也需明确决定。CLI对应`规则审阅`和`规则决定`，二者共用HTTP合同。凭据失效会阻断新诊断消费，旧报告和启停历史保留；该资格不开放语义判断、自动改文或其他用途。
|
||
|
||
任务页可选一次实际执行，核对技术来源后记录现象、原话和背景。观察不会自动形成有效方法或长期偏好。CLI的`运行来源`请求含`task_id/attempt_id`及可选具名业务定位；`记录运行观察`含`command_id/observation`，来源定位使用前者原样返回的`locator`。内容用途由服务端任务取得，不能通过请求修改。
|
||
|
||
```bash
|
||
muse 经验 作者.toml 运行来源 来源请求.json
|
||
muse 经验 作者.toml 记录运行观察 观察请求.json
|
||
muse 经验 作者.toml 运行观察 <观察ID>
|
||
muse 经验 作者.toml 运行观察清单 <任务ID>
|
||
muse 经验 作者.toml 重复问题 <同类问题名称>
|
||
```
|
||
|
||
运行观察和作者自报的人审时间、返工、误杀及费用分开保存。历史失败或未知不随重试成功而改变；同一任务的多次尝试不扩大跨任务样本。
|
||
|
||
反馈对照可提出具体规则改进：选择候选规则后由服务读取版本和哈希，提案只保存验证意向。使用独立评测配置完成同目标验证后，工作台展示实际验证回执；提供有效凭据、打开审阅并明确确认，才由规则模块改变生效状态。页面还能追查使用该版本的诊断报告，刷新或查看回执不会产生新批准。
|
||
|
||
```bash
|
||
muse 经验 作者.toml 提出规则改进 规则提案.json
|
||
muse 经验 作者.toml 申请规则验证 规则验证请求.json --评测配置 评测.toml
|
||
muse 经验 作者.toml 读取改进 <改进ID>
|
||
muse 经验 作者.toml 规则启停 规则决定.json
|
||
```
|
||
|
||
JSON请求按[经验接入合同](src/muse/接入/经验操作.py)填写，规则决定必须携带已打开的确切审阅。响应未知时复用原请求恢复；停用已生效旧版时仍点名该旧版，不用最新候选替换它。
|
||
|
||
## 独立发布与系统管理
|
||
|
||
`uv run python 工具/构建发布.py --输出 <全新发布目录>` 一次生成接口、工作台、资源清单、wheel、带哈希的运行依赖及部署文件。生成目录不含工作树、测试或私人资料；重用目录会拒绝覆盖。`--已生成` 只用于复用刚构建的资源，仍会核对当前代码哈希。
|
||
|
||
发布目录可直接作为 Docker 构建上下文：`docker build --platform linux/amd64 -t <本地标签> <发布目录>`。Dockerfile固定 Python 和 Node 的镜像摘要，Pi 及其依赖由锁文件固定；应用以 UID/GID 10001运行。镜像构建不执行数据库迁移。
|
||
|
||
将发布目录中的 `应用.example.toml` 和 `部署.example.env` 复制到不提交的受控位置，填写独立实例名、镜像完整 ID 或摘要、用途明确的数据库引用、作者口令引用与持久目录。发布构建已将配置中的资源身份固定为具体构建哈希；不要换成固定发布标签。应用仅挂载这两个具体凭据文件。持久目录应归实际运行 UID/GID 所有；应用配置只读，raw 与草稿使用持久挂载。
|
||
|
||
首次安装由维护者明确建立用途角色，并以维护配置执行 `python -m muse 迁移 <维护配置>`。正常启动命令是 `<发布目录>/启动.sh <发布目录> <部署环境文件>`；启动脚本核对镜像与发布清单的构建身份后才开放服务。健康探针 `/ready` 同时核对程序、资源和数据库版本。数据库落后、超前或迁移校验和变化时，作者 HTTP/CLI 数据库写入被拒绝；登录、系统诊断和本地探索草稿仍可使用。
|
||
|
||
`<发布目录>/停止.sh <发布目录> <部署环境文件>` 优雅停止本实例，保留卷、凭据和配置。显式的第三参数可追加 `compose.test.yaml`，只供独立 PostgreSQL 验收环境；不会接到既有数据库。重启后任务记录和候选保留，定稿导出可继续推进原任务。模型任务仍需其已验证的具名配置和流程能力，安装成功不等于真实模型能力已通过验收。
|
||
|
||
工作台“系统管理”读取实际版本、角色允许模型、脱敏配置及作者数据盘点。配置页面只保存草案；保存不是启用。在`文件.备份目录`配置权限0700的备份根后，备份页可列出、核对和下载完整备份；未配置时显示“未盘点”。文稿导出与完整备份是两个入口。
|
||
|
||
完整备份和灾难恢复使用`muse 数据维护`命令，由安装了对应应用及PostgreSQL客户端的维护机执行。必须保留备份时的发布包，恢复到新空库和新文件根；源库不可用也能离线核对、解包和恢复。命令、故障处理与后台维护请求见[备份与恢复入口](docs/系统架构/新版设计/迁移与验收.md#备份与恢复入口)。恢复成功后还需核对实际正文、决定和任务，命令不会启动服务或重发模型调用。
|