# Goal 受管 JSON 验收

在 Goal 面板展开“JSON 验收要求”，由对话所有者或管理员显式保存要求。每个 Goal 最多 8 条要求，每条绑定一个产物槽和 1–16 个顶层字段。字段检查表示字段存在且不为 null；false、0 和空字符串允许，不等于内容质量判断。保存后不可关闭强验收模式，可以带当前 revision 修改要求；旧修订会返回冲突。

当前已接通用户配置、独立受管版本、绑定检查及共享完成检查。选中模式后，所有当前要求必须具有匹配的有效绑定，才可在既有完成规则满足时完成；自动评估、显式 completeGoal 和重试均使用同一完成检查。未选中的 Goal 保持既有行为。

## 受管版本接口

接口前缀 `/api/v1/goals/{goalId}/json-acceptance`，需要启用账户及对话所有者或管理员权限。ID、revision 和 generation 在响应中使用字符串，客户端应原样保留。

- `GET /`：读取启用状态和要求。
- `PUT /requirements/{criterionKey}`：提交 `expectedRevision`、`artifactSlot`、`requiredFields`。新要求的 revision 为 `0`。
- `GET /artifacts`：列出当前要求使用的槽及当前版本。空槽 generation 为 `0`。
- `POST /artifacts/{slot}`：提交 `expectedGeneration` 和 `jsonContent`（包含原始 JSON 正文的字符串），原子追加新版本并推进槽。
- `GET /artifacts/versions/{artifactId}`：读取本 Goal 指定版本的元数据及原始正文，包括历史版本；读取历史版本不表示它仍可用于验收。

仅当前要求引用的槽可发布，Goal 必须 active 或 paused。正文必须是严格 JSON 对象，拒绝重复键、尾随文档、超过 32 层的嵌套及超过 1 MiB 的 UTF-8 内容。每个 Goal 最多保存 32 个版本；达到配额拒绝继续发布，不覆盖旧版本。每版有效期 24 小时，重复发布同样正文也产生新版本。客户端遇到 generation 冲突应重新读取，不自动覆盖他人发布。

这些版本独立存储在数据库，不能用普通工作区文件、缓存路径或文字中的 hash 替代。发布接口不支持更新历史正文；所有版本与槽指针同事务保存。SHA-256 用于标识及完整性核对，不能隔离拥有数据库凭据或宿主权限的攻击者；数据库和服务宿主是此有限协议的可信基础。JSON 服务契约已在 H2、MySQL 8.0.46 和 PostgreSQL 16.14 上实测。MySQL 使用仅修正既有 V192 失败的临时迁移副本；PostgreSQL 使用原始 Kingbase 迁移树，跳过无关的内置技能导入失败。这是协议验证，不能代表未修改的完整安装成功；尚未实测 Kingbase 专有引擎。

## 代理发布

`getManagedGoalJsonSlots` 返回当前 Goal 的用户要求、槽和 generation；`publishManagedGoalJson` 接收 `artifactSlot`、字符串 `expectedGeneration` 和 `jsonContent`。工具不能配置要求，也不能传 Goal ID、账户或 owner fence。普通会话必须携带已认证账户的内部 ID；持久 Goal 的调度执行必须同时匹配当前 continuation、attempt、owner token 和有效租约。两种入口都重新检查对话、工作区、Agent 和启用账户。代理委派的默认禁止列表包含这两个工具，服务仍独立检查身份。

发布与调度结算按 Goal 锁串行化，晚到的旧 owner 不得继续写入。租约结束不会改写已经合法发布的历史版本。匿名会话和没有绑定 Goal attempt 的 cron 不支持此发布协议；身份缺失直接拒绝，不以显示用户名代替认证。


## 绑定检查

发布后，调用 `POST /checks/{criterionKey}`，提交 `expectedRequirementRevision`、`artifactId`、`expectedGeneration`；代理使用 `checkManagedGoalJson` 传相同字段。所有修订和 generation 在代理工具里都是字符串。服务端只检查当前槽的指定版本，运行自己的字段 recipe，不接受调用方提供的 PASS。返回 `acceptanceEligible=true` 表示这条要求当前匹配，不能代表整个 Goal 已完成。

`GET /checks` 读取每条要求的当前资格。要求修改、Goal 定义修改、槽出现新版本、版本过期或正文完整性失败都会使旧绑定失效；需要按当前条件重新检查。每次绑定与 Goal version 更新同事务，失败回滚不留下通过凭据。历史诊断接口的 `acceptanceEligible=false` 保持不变，只有此受管版本检查产生绑定。完成事件保留本次受管绑定的条件修订、产物 ID 和 generation 引用；事务回滚不发布完成事件或完成记忆。

这是逐 Goal 显式选择的有限受管 JSON 协议；宽泛执行证据账本的全局 ENFORCE 配置仍遵循原有准入限制。此协议不把任何普通工具成功文本或诊断 MATCH 自动升级为绑定。后端服务已覆盖成功、失效、竞争和回滚；真实 JWT/浏览器/服务夹具及磁盘 H2 升级重启也已通过；这不代表在线模型运行或完整产品端到端覆盖。

代理在 ReAct、Plan 和持久 Goal 续跑入口都会收到受管 JSON 操作指引。业务技能的工具白名单保留读取、发布和检查这三个 Goal 通用工具，仍执行服务端身份校验与子代理禁用。选中模式下，follow-up 和调度投影不能凭模型的“已完成”或 segment Complete 声明结束；必须先有已提交的 Goal completed 状态。自动完成被拒绝时，向运行时返回 continue 和重检指引，不暴露已接受完成的信号。

运行时完成也必须携带服务端身份：completeGoal 工具与自动评估节点使用专门的 runtime 完成入口，在同一事务中复查启用账户、当前 Goal/对话/工作区/Agent 和调度 owner 租约，再检查所有绑定。即使绑定仍有效，旧租约、跨 Goal 或已撤销的身份也不能发起完成。平台内部完成 API 仍执行绑定门；它不是向模型或 HTTP 暴露的免身份入口。

在 Goal 面板的“产物版本与检查”中可以查看当前受管 JSON、粘贴正文并显式发布新版本，以及逐条执行检查。界面显示条件修订、版本、有效期、已使用配额和读取时间；这是读取时的快照，最终完成仍复核当前状态。发生冲突后必须重新读取，访问撤销会清空旧内容，终态只读。正文按文本显示，不渲染其中的 HTML。

`GET /snapshot` 在同一 Goal 锁内返回要求、当前槽、检查资格、Goal 状态和版本计数。代理 `getManagedGoalJsonSlots` 也使用此快照，避免分别读取要求和产物造成混合视图。

## 部署与升级

受管 JSON 服务与所有 Goal 写入实例必须统一部署。启用要求前停止旧应用和调度实例，不得让不认识此完成门的旧二进制继续写入选中协议的 Goal。回滚须保留兼容的写入实例，或协调恢复升级前的应用及数据库备份；不能清除 required 标记或删除要求来让旧版本继续完成。

V197 使用 epoch 秒作为有效期依据，不受 JVM/JDBC 时区变化影响。此前受管记录的本地时间戳无法可靠还原原始时区，因此升级保留正文、要求、generation 和历史，但使旧验收资格过期。需要重新发布版本并按当前要求检查。已经完成的 Goal 保持历史完成状态，不被重新打开；保留历史仍计入 32 个版本的配额。

宿主时钟、数据库凭据和服务宿主仍属于可信基础。若外部任意代码不可信，应在没有服务/数据库凭据、没有服务存储权限的隔离环境执行；仅设置工作目录或扫描路径不是操作系统隔离。备份应协调保存数据库中的要求、正文、指针和绑定，仅备份工作区文件无法恢复受管验收。

V198 同样以绝对时间保存调度租约截止。升级时旧租约失效，按已有检查点恢复：安全工作可建立新 attempt，不确定副作用仍阻断并要求核实。过期 owner 不能续租、提交检查点、结算或使用受管 JSON 工具。续租在获得 Goal 锁后检查两侧当前租约，迟到调度 tick 不能利用旧时间戳复活 owner；新的有效 owner 可按现有要求继续。