muse-agent-example/docs/系统架构/新版设计/接口契约/命令与作者决策.md

命令与作者决策

本文定义目标业务协议，路径与字段是实施合同，不表示当前服务器已提供这些接口。HTTP、CLI 和主会话进入同一应用用例；公开请求按运行时类型校验。JSON Schema、OpenAPI 与 TypeScript 从同一合同生成并检查差异。

接口类别

类别	返回	主要约束
查询	对象、版本、分页、来源与字段投影	按真实身份和用途读取
人工保存	新数据版本及命令回执	预期版本、请求幂等与写入范围
长任务	task_id、初始状态与事件位置	已接受不等于已完成
作者决定	原子提交回执或类型化拒绝	被审对象、批准清单、当前依赖
恢复控制	原任务、新尝试或等待原因	原授权、预算、来源与租约

单作者接入

HTTP 服务从受控文件读取访问口令，作者使用 POST /api/v1/session 换取有期限的 HttpOnly、SameSite 会话。作者 ID 由服务端配置绑定，登录请求不接受自报作者身份；凭据不放 URL 或浏览器持久缓存。退出删除当前会话。

带 Cookie 的写请求核对明确登记的 Origin；客户端不能通过 decided_by 或类似字段取得确认权。CLI 使用本地受控配置确定作者身份，并调用同一业务接口；模型工具入口不读取作者口令、不构造作者身份。所有路径仍核对用途和目标范围。

/health 只报告进程存活；/ready 实查当前数据库依赖；两者不代表业务任务完成。HTTP 与 CLI 使用相同错误码和中文说明。连接文件路径相对所用配置文件解析，安装与运行不依赖当前工作目录。

HTTP 与 CLI 的作者运行入口使用同一默认装配：构建阶段只登记包内真实处理器，不连接数据库、不批量发布流程，也不开始模型调用。作者明确发起某类任务时，才从安装包内已登记且经哈希核对的流程资源按需发布固定版本。研究拆书与章后处理没有明确配置引用时保持缺配置拒绝，不猜测部署名称。

稳定写入外壳

内容写命令包含 command_id、target_ref、expected_data_revision 和明确 payload。任务暂停、取消和恢复属于状态控制，使用 command_id、任务身份、expected_state 与明确动作；在同一事务核对状态并登记幂等结果，不伪造正文 revision。作者身份由接入层认证，客户端不能通过 decided_by 字符串获得权限。command_id 在作者与用途内唯一；规范化请求哈希不包含连接、重试时间等传输噪声。

动态内容增加 schema_binding、expected_effective_schema_hash 与 expected_projection_version，payload 按绑定的有效结构校验。系统外壳不允许额外字段；动态值只能使用结构声明的 key。字段引用的真实目标由所属模块解析。

命令的授权范围必须能从作者动作与业务上下文解释，不能让模型提供表名、物理列、SQL 或处理函数路径。

目标接口族

统一使用 /api/v1。路径内部技术标识保持稳定，界面名称用中文。

目标接口族	主要动作	所属模块
/works、/works/{work_id}/plans	作品档案、规划查询、编辑、候选决定	B01
/explorations、/works/{work_id}/exploration-selection	私人探索稿读取与原子保存、明确选定来源交接	B01
/works/{work_id}/entities、/facts	动态实例、时点查询和事实提案决定	B02
/sources、/rankings、/analyses	导入、快照、拆书任务及分析版本	B03
/methods、/method-bindings	方法候选、版本、绑定及启停	B04
/chapters/{chapter_id}/documents	读取、人工保存、分支与正文版本	B05
/writing-candidates/{candidate_id}/decisions	正文候选采纳、拒绝或暂缓	B05
/reviews、/voices、/quality-rules	检查、声音与规则版本、修订任务	B06
/preferences、/improvements	偏好、反馈与改进验证申请	B07
/deliveries、/releases、/reader-feedback	定稿、导出、发布和反馈	B08
/contexts、/search	作者查询及可见来源解释	B09
/experiments	隔离样例、盲评和结果	B10
/author-reviews	创建被展示版本的审阅记录和读取差异	S01
/tasks、/tasks/{task_id}/events、/tasks/{task_id}/advance	任务、事件、取消、暂停、恢复及点名推进一个冻结步骤	S02
/tasks/{task_id}/budget	读取实际角色、账户策略和冻结额度；明确批准本任务额度	S02
/types、/schemas、/schema-bindings	类型、结构候选、投影和升级	S04
/system/configurations、/archives、/backups	配置与受控数据维护任务	S03 接入和对应维护者

表中的相邻资源使用各自路径，不存在一个对所有对象任意写字段的通用接口。动态表单根据所属模块公开的允许动作保存；/search 不暴露模型内部统一读取器的无限制参数。

POST /tasks/{task_id}/advance 的客户端输入只有路径中的任务身份，可选空对象不接受额外字段。服务端核对会话作者、运行用途和允许的作者流程，再从任务冻结计划取得处理器身份与版本，按 S02 原领取 SQL 和租约最多执行一个步骤。请求不能携带脚本路径、处理器、版本、能力列表或处理器参数；未批准预算、未启用配置、失效来源及缺失资源继续按原错误合同拒绝，不自动批准、恢复或换配置。

任务预算GET返回任务实际冻结角色、配置绑定的账户策略及已有计划；无模型角色则返回空角色集合。POST和CLI共用主会话.任务额度请求，严格校验金额、角色次数、未来截止时间和命令身份。作者身份来自服务配置或会话，批准引用由服务端派生。S02在任务锁内核对归属、非终态及完整角色集合，同事务登记不可变预算；同内容重试返回原计划，不允许借用其他作者、额外角色、修改额度或重启复活停止预算。账户策略须先经明确管理动作登记，任务批准不自动设置账户上限，也不执行模型步骤。

私人探索可以早于正式作品建立，因此稿件以作者和稿件身份读取，不要求先创建work。明确选定时才绑定目标作品：携带稿件ID、稿件哈希、目标作品当前选定版本和命令ID。服务端读取对应原文快照、核对最终格式及作品归属，由S01记录选定版本与回执。作者和时间来自服务端，不接受confirmedByUser或confirmedAt。选定快照成为该作品允许用于规划的来源；后续编辑私人稿不修改既有选定快照，正式规划内容仍需单独生成、审阅和确认。

作者审阅与正式提交

审阅记录绑定展示的候选版本、候选哈希、目标基线、差异、有效结构、字段投影及来源摘要。它记录服务端展示和作者具体决定，不能把创建审阅记录本身当作作者已批准。

采纳请求必须包含 command_id、candidate_id、candidate_revision、candidate_hash、target_ref、expected_data_revision、author_review_id、approved_changes，以及动态内容所需的结构和投影版本。服务端从候选关系取得依赖，不相信客户端自报已经预检。

处理顺序：

1. 占用或读取幂等命令，拒绝同键不同请求。
2. 取得目标、候选和审阅记录，验证生产用途、身份与批准范围。
3. 按稳定锁序保护当前正文或规划、结构绑定、策略及来源有效指针。
4. 重验数据、候选、审阅、结构、投影及必需检查绑定。
5. 各业务参与者准备类型化变更；批准事实由 B02 核对内容与依据。
6. 同一事务写内容版本、当前指针、来源归因、决定、完整回执及派生任务。
7. 提交后发布持久化事件。响应丢失后的相同请求返回同一回执。

部分采纳和作者编辑候选先形成新候选版本，重新生成差异和适用检查。人工正文保存保留版本、幂等及影响保护，不要求模型评分通过。

错误与恢复

错误码	含义	可执行后果
REVISION_CONFLICT	数据或候选版本变化	保留输入，取当前版本并由作者比较
COMMAND_PAYLOAD_MISMATCH	命令键被用于不同请求	修正客户端命令身份，不自动覆盖
REVIEW_MISMATCH	被审内容与提交不一致	重新展示实际候选并决策
SOURCE_STALE	当前来源或绑定变化	重组上下文或复核影响
SCHEMA_STALE	有效结构与预期不符	重取结构，处理升级后重审
PROJECTION_STALE	策略、授权或来源影响字段集合	清除不再允许的缓存，重取投影
SCOPE_DENIED	超出作品、用途或来源范围	拒绝，不以重试扩大权限
INVALID_OUTPUT	输出不满足合同	保留失败证据，按策略返修或终止
EVIDENCE_PENDING	必需证据未可靠保存	优先补交，不为补日志重跑模型
BUDGET_EXHAUSTED	预算不足	等待授权或预算，不能暗自换低能力角色
PRECONDITION_PENDING	前章、规划、事实或摘要不满足要求	展示具体缺失前置并暂停依赖步骤

错误统一包含 code、中文 message、target_ref、retryable、details 和允许的后续动作。返回空对象、布尔 false 或吞掉错误不符合合同。