运行治理与执行核对

管理应用运行状态

应用管理员调用 PUT /v1/apps/{app}，用 If-Match 携带应用 revision。正文可包含 name、status、reason。状态为 DRAFT、ACTIVE、SUSPENDED、ARCHIVED。暂停和归档的状态变更必须填写原因；归档保留数据，可以恢复。恢复 ACTIVE 前会校验已发布默认 Agent 及依赖。DRAFT 通过设置默认 Agent 激活，不能把运行应用退回 DRAFT。

暂停后拒绝新任务，在途任务在下一次能力检查时终止；已发送的外部请求不会被撤销。更换默认 Agent 不会绕过暂停或归档。控制台概览中的“应用设置”提供同一入口。

限制 Agent 入口

Agent definition 可包含 entryPolicy。省略时为 APPLICATION，保持原应用内入口行为。INTERNAL_ONLY 仅允许合法委托，不能直接聊天或设为默认。RESTRICTED 按认证身份过滤，示例：

{"mode":"RESTRICTED","roles":["APP_ADMIN"],"tenants":["tenant-a"]}

roles、subjects、tenants 的非空维度取交集，每一维度中的值取并集。至少配置一个非空过滤维度。Context 中的身份字段不参与授权。委托仍要求 allowedAgents 和委托能力授权。

配置密钥所属应用

带 secretRef 的能力现在同时校验密钥名称、目标 origin 和能力所属应用。部署前必须补充 SPARKTIDE_SECRET_APPLICATIONS，例如 MODEL_API_KEY=global,DEVICE_KEY=monitor;maintenance。分号分隔同一密钥允许的应用，逗号分隔不同密钥。

global 只授权平台拥有的模型资源；应用通过合法的模型绑定使用。不要把 global 当成通配符。缺少所属应用授权会返回 SECRET_SCOPE_DENIED，即使 origin 相同也不例外。迁移前盘点现有 secretRef 并配置精确授权，在隔离环境验证后升级。

核对未知工具结果

Flyway V7 增加独立执行账本。每次工具外呼前持久化执行 ID、可信身份、工具版本、输入摘要和幂等键；完成后保存结果摘要或错误。账本不保存完整业务参数和结果。

GET /v1/apps/{app}/runs/{runId}/tool-executions 返回账本数组。用户只能读取自己的任务；应用管理身份可在所属应用内核对，管理读取有审计。状态为 RUNNING、SUCCEEDED、FAILED、UNKNOWN。写操作或危险操作的异常不能证明外部业务回滚，因此标为 UNKNOWN；已终止 Run 的遗留 RUNNING 记录也保守恢复为 UNKNOWN。

管理员先在业务系统查明实际结果，再调用 POST /v1/apps/{app}/tool-executions/{executionId}/reconcile，携带账本 revision 的 If-Match：

{"status":"SUCCEEDED","reason":"业务已成功，回调响应丢失","evidence":"订单系统流水号 ORDER-123 的核对记录"}

status 仅允许 SUCCEEDED 或 FAILED。reason 长度 1..1024，evidence 长度 1..2048。仅终态 Run 中的 UNKNOWN 记录可核对，修订冲突返回 412，状态不符返回 409。核对不会再次调用业务，也不会改变原 Run 的终态。控制台任务详情提供同一表单。

升级、回退与边界

先备份数据库并保留审计。V7 是新增表，回退程序时保留表和核对证据，不删除账本。旧程序不会执行新的入口与密钥所属应用限制；仍依赖这些限制时不可直接回退旧程序。人工核对不提供自动补偿或跨系统事务保证，业务系统必须按执行 ID 实现自身幂等。本文只说明已实现的能力，不代表全产品审计已关闭。

评测、留存和通知交付边界

2026-10-08：评测提交冻结数据集正文与摘要；发布门禁要求当前数据集摘要、候选 Agent 精确版本和全案例通过一致。失败/取消/超时运行不会因空断言而通过；遗留 worker 恢复只终结评测，工具不重放。诊断见 summary.message，私有执行快照不进入公开响应。

留存预览无法完成 SQL 时返回失败；执行按各类别行数限制在同一事务中清理，任一类别失败全批回滚，提交后更新计数。dryRun 必须为 JSON 布尔，字符串或 null 不得触发真实删除。

通知在领取时持久化尝试次数，以租约和次数围栏拒绝迟到结果；投递为至少一次，接收方按通知标识去重。降低尝试上限会终结已耗尽的待处理通知，不能视为精确一次副作用。

文档来源与验证记录

日期：2026-09-29；状态：已实现，按源码与自动化测试核验；责任人：项目维护者。来源：Registry、AgentEntryPolicy、Outbound、ToolExecutions 和 OpenAPI。