0260bcd8e2
- 新版设计各域 SoT 按本轮实现同步：总体架构、模块设计、接口契约、数据模型、功能规格、文件设计与决策记录。 - 接口契约生成物重新导出（openapi 与前端客户端随契约一致）。 - 实现回顾与专项检查台账保留历史结论；本轮收尾发现另见 .agents.local 下的收尾报告与审查处置。
101 lines
9.5 KiB
Markdown
101 lines
9.5 KiB
Markdown
<!-- 导航元信息: {"内容描述": "命令与作者决策", "使用场景": "设计、实现或评审对应主题", "使用要求": "与阅读指南的主题权威分工一致"} -->
|
||
# 命令与作者决策
|
||
|
||
本文定义目标业务协议，路径与字段是实施合同，不表示当前服务器已提供这些接口。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 或吞掉错误不符合合同。
|