mirror of
https://gitee.com/mateos/mateclaw.git
synced 2026-09-15 03:55:09 +08:00
65 lines
10 KiB
Markdown
65 lines
10 KiB
Markdown
# Goal 受管 JSON 验收
|
||
|
||
打开已有目标的对话，点击顶部“目标”按钮，再展开“受管 JSON 验收”。普通工作区成员可管理自己对话中的要求，无需进入管理员计划看板；管理员也可从计划看板的 Goal 面板进入。由对话所有者或管理员显式保存要求。每个 Goal 最多 8 条要求，每条绑定一个产物槽和 1–16 个顶层字段。字段检查表示字段存在且不为 null；false、0 和空字符串允许，不等于内容质量判断。保存后不可关闭强验收模式，可以带当前 revision 修改要求；旧修订会返回冲突。
|
||
|
||
当前已接通用户配置、独立受管版本、绑定检查及共享完成检查。选中模式后，所有当前要求必须具有匹配的有效绑定，才可在既有完成规则满足时完成；自动评估、显式 completeGoal 和重试均使用同一完成检查。未选中的 Goal 保持既有行为。
|
||
|
||
当前会话的“目标”面板也保留暂停、已完成等历史目标，每次读取20项，可加载更早记录。暂停目标仍可修订要求、发布和检查；终态目标只能查看要求与已有正文。关闭面板、切换会话或离开页面后清除面板内容；刷新失败时清除旧列表。读取历史不会恢复目标运行。
|
||
|
||
## 受管版本接口
|
||
|
||
接口前缀 `/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 可按现有要求继续。恢复扫描遇到 continuation 租约仍有效或 owner 已变化的记录时会跳过，继续处理其他可恢复目标。JSON 绑定通过也不能越过不确定工具结果导致的暂停。
|
||
|
||
验证快照（2026-09-14）：默认后端完整测试集实际通过 5,249 项、条件跳过 33 项，前端通过 386 项。受管契约还覆盖真实编译的 ReAct/Plan 图及账户/调度 owner 四种组合；模型选择和语义评价是受控夹具，不是在线模型基准。专门集成 profile 与 Kingbase 专有引擎不包含在“默认完整测试集”结论中。
|
||
|
||
内置 shell/code 执行没有与服务宿主做操作系统隔离。选择 JSON 验收不会把这些工具变成沙箱；此协议不能抵抗能访问数据库凭据或文件的宿主代码，环境变量名称过滤和工作区路径检查也不能替代隔离。租约截止从绝对时刻计算，覆盖夏令时回拨；调度显示字段仍使用本地时间戳。
|
||
|
||
Web排队消息从V199起保存入队时已认证账户的内部ID，普通Web续跑同时携带当前会话工作区；受管工具执行时仍重新校验账户、归属和当前要求。旧队列项不按用户名补造身份，不能用于受管JSON操作；需要用户重新发送已认证请求。持久Goal工作器消费输入时继续使用原有attempt owner校验，没有转换成免租约的账户路径。
|
||
|
||
恢复执行会收到先核实已有证据、不要重放未知副作用的提示。首次恢复执行若在实际运行前延期，下一次领取仍保留恢复关联；已经执行过后的普通续跑不会因此变成新恢复。
|
||
|
||
会话归档或改绑 Agent 后，旧运行上下文不能再读取托管运行状态、发布、检查或完成目标；有权用户仍可读取已保存的证据。此检查与当前 Goal 身份和租约校验处于同一事务。
|