7.6 KiB
命令与作者决策
本文定义目标业务协议，路径与字段是实施合同，不表示当前服务器已提供这些接口。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 使用相同错误码和中文说明。连接文件路径相对所用配置文件解析，安装与运行不依赖当前工作目录。
稳定写入外壳
内容写命令包含 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 | 任务、事件、取消、暂停和恢复 | S02 |
| /types、/schemas、/schema-bindings | 类型、结构候选、投影和升级 | S04 |
| /system/configurations、/archives、/backups | 配置与受控数据维护任务 | S03 接入和对应维护者 |
表中的相邻资源使用各自路径，不存在一个对所有对象任意写字段的通用接口。动态表单根据所属模块公开的允许动作保存；/search 不暴露模型内部统一读取器的无限制参数。
私人探索可以早于正式作品建立，因此稿件以作者和稿件身份读取，不要求先创建work。明确选定时才绑定目标作品：携带稿件ID、稿件哈希、目标作品当前选定版本和命令ID。服务端读取对应原文快照、核对最终格式及作品归属，由S01记录选定版本与回执。作者和时间来自服务端，不接受confirmedByUser或confirmedAt。选定快照成为该作品允许用于规划的来源；后续编辑私人稿不修改既有选定快照，正式规划内容仍需单独生成、审阅和确认。
作者审阅与正式提交
审阅记录绑定展示的候选版本、候选哈希、目标基线、差异、有效结构、字段投影及来源摘要。它记录服务端展示和作者具体决定，不能把创建审阅记录本身当作作者已批准。
采纳请求必须包含 command_id、candidate_id、candidate_revision、candidate_hash、target_ref、expected_data_revision、author_review_id、approved_changes，以及动态内容所需的结构和投影版本。服务端从候选关系取得依赖，不相信客户端自报已经预检。
处理顺序：
- 占用或读取幂等命令，拒绝同键不同请求。
- 取得目标、候选和审阅记录，验证生产用途、身份与批准范围。
- 按稳定锁序保护当前正文或规划、结构绑定、策略及来源有效指针。
- 重验数据、候选、审阅、结构、投影及必需检查绑定。
- 各业务参与者准备类型化变更；批准事实由 B02 核对内容与依据。
- 同一事务写内容版本、当前指针、来源归因、决定、完整回执及派生任务。
- 提交后发布持久化事件。响应丢失后的相同请求返回同一回执。
部分采纳和作者编辑候选先形成新候选版本，重新生成差异和适用检查。人工正文保存保留版本、幂等及影响保护，不要求模型评分通过。
错误与恢复
| 错误码 | 含义 | 可执行后果 |
|---|---|---|
| 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 或吞掉错误不符合合同。