Scout API 与集成参考
人工决策应使用产品界面，受控自动化可以使用 REST API。部署环境的 OpenAPI 是字段级权威；本页面面向已经理解 Scout 运行流程的客户集成团队。
认证与范围
- 使用平台认证流程和目标租户账号。
- 不把不可信请求中的 tenant ID 当授权依据。
- Scout API 要求对应
scout.*权限。 - 直接 Harness API 读取要求
platform.harness.read。 - 服务账号凭据放在平台 secret 系统，不写入脚本或证据产物。
已实现 Scout API
| Method | Endpoint | 权限 | 用途 |
|---|---|---|---|
POST | /api/v1/scout/missions | scout.write | 创建 Mission 并绑定快照 |
GET | /api/v1/scout/missions | scout.read | 筛选和分页 Mission |
GET | /api/v1/scout/missions/{missionId} | scout.read | Mission 摘要和下一动作 |
POST | /api/v1/scout/missions/{missionId}/snapshot | scout.write | 追加刷新快照绑定 |
POST | /api/v1/scout/missions/{missionId}/discovery | scout.write | 在快照允许时启动 discovery |
GET | /api/v1/scout/missions/{missionId}/coverage | scout.read | 冻结 Coverage |
GET | /api/v1/scout/missions/{missionId}/coverage/{rowKey} | scout.read | 单条 Coverage row |
GET/POST | /api/v1/scout/missions/{missionId}/workbench[/candidates] | scout.read/write | 列出/创建候选 |
POST | /api/v1/scout/missions/{missionId}/workbench/candidates/{candidateId}/decision | scout.write | 接受/驳回候选 |
GET | /api/v1/scout/contracts[/{contractId}] | scout.read | 合同列表、版本和审计 |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/shadow | scout.write | 进入 Shadow |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/approve | scout.approve | 批准版本 |
POST | /api/v1/scout/contracts/{contractId}/versions/{version}/deploy | scout.deploy | 部署版本 |
GET | /api/v1/scout/missions/{missionId}/runtime-evidence | scout.read | 读取运行证据 |
Platform Harness API
| Method | Endpoint | 用途 |
|---|---|---|
GET | /api/v1/platform/harness/v1/capabilities | 查询组件和限制 |
POST | /api/v1/platform/harness/v1/snapshots | 创建/解析授权不可变快照 |
GET | /api/v1/platform/harness/v1/snapshots/{snapshotId} | 读取冻结 manifest |
GET | /api/v1/platform/harness/v1/snapshots/{snapshotId}/components/{component} | 分页读取冻结组件 |
Scout 消费平台 Harness，不应再建 Scout 私有 context assembler。
Canonical 自动化顺序
create Mission -> read Mission/snapshot -> read Coverage
-> create candidate -> decide candidate -> read contract
-> Shadow -> approve -> deploy -> read Runtime Evidence
必须核对同一 Mission、snapshot、row、candidate、contract/version、source、Twin、binding、installation、consumption-evidence 和 result ID。路由返回成功不是闭环证据。
幂等与并发
治理 mutation 使用 UUID Idempotency-Key。只在重试同一个逻辑请求时复用相同 key。Candidate decision 和 contract transition 还带 expectedVersion；冲突表示记录已变化，应重新加载审阅。
列表/Coverage API 使用从 0 开始的 page 和明确 size。不得混合不同 snapshot/source version 的分页结果后声称其为冻结视图。
错误处理
| 条件 | 处理 |
|---|---|
401 | 更新认证，不无限重试 |
403 | 检查 entitlement、module、tenant、permission |
404 | 检查 tenant-scoped ID，不枚举其他租户 |
409/version conflict | 重新加载并审阅 |
| stale/rejected snapshot | 停止 mutation，处理证据问题 |
429 | 遵守服务端窗口并退避 |
5xx | 记录 trace ID 和第一失败阶段，只重试安全幂等操作 |
责任边界
DFS 负责 connector/source contract/source point/Mapping V2/native binding；Twin 负责 Twin/schema/attribute；ClickHouse 路由负责 canonical time-series read；PdM 负责 installation 和 consumer result；Scout 负责 Mission、frozen coverage、binding decision、IDBC lifecycle 和跨阶段证据。
当前版本不提供公开的 Scout MCP 工具或签名外部快照导出。请仅使用当前环境 OpenAPI 中正式发布的接口。