集成 Scout
Scout 提供网页、平台 MCP 和 REST API 三种访问方式。网页适合人工调查与审阅；MCP 适合在 AI 客户端中调用受治理的 Scout 工具；REST API 适合应用集成和自动化。
选择集成方式
| 方式 | 适用场景 | 认证方式 |
|---|---|---|
| FactVerse 网页 | 创建任务、审阅证据、批准和发布 | 平台用户登录 |
| 平台 MCP | 让外部 AI 客户端读取任务和调用已授权工具 | 平台 MCP 凭据和 X-API-Key |
| REST API | 将 Scout 操作接入业务系统或自动化程序 | 部署环境提供的平台凭据 |
所有方式共享同一租户、任务、权限和审计记录。请求字段以当前环境返回的工具定义或 API 说明为准。
前提条件与输入
- FactVerse 主机地址和目标租户
- 已启用的 Scout 与平台 MCP 能力
- 绑定有效账号、用途和最小权限的平台凭据
- 业务问题、设备或数据集范围
- 通过授权服务取得的任务和资源标识
先使用只读访问列出能力和任务，确认客户端连接到预期租户。
连接 MCP 客户端
使用支持远程 MCP Streamable HTTP 并可配置请求头的客户端。Scout 端点为：
https://your-factverse-host/mcp/scout/
- 请租户管理员签发平台 MCP 凭据。首次验证建议使用
READ用途和scout.read范围。 - 在客户端中添加远程 MCP 服务；私有部署填写客户环境的平台地址。
- 在受保护配置中添加请求头
X-API-Key，值为平台 MCP 凭据。 - 连接后刷新工具列表，依次调用
scout_capabilities、scout_mission_list和scout_mission_get。 - 核对返回的任务、设备、来源选项和租户信息。
| 工具 | 用途 |
|---|---|
scout_capabilities | 查看可用流程、业务目标和授权来源选项 |
scout_mission_list | 分页列出当前租户的 Scout 任务 |
scout_mission_get | 查看所选任务的阶段、阻塞项、下一步和证据引用 |
工具输入以客户端显示的定义为准。任务列表为空表示当前查询范围没有可见任务，可以回到网页创建任务或请管理员检查权限。
分配凭据用途
| 工作责任 | 凭据用途 | Scout 权限范围 |
|---|---|---|
| 查看任务和证据 | READ | scout.read |
| 创建任务、调查和验证 | OPERATOR | scout.read、scout.write |
| 审阅发布证据 | APPROVER | scout.read、scout.approve |
| 应用获批发布或执行受支持恢复 | DEPLOYER | scout.read、scout.deploy |
平台还会检查账号状态及相关数据、MDM、模型和 DFS 权限。对需要职责分离的发布流程，应为审批人与发布操作员分别配置访问。
示例：调查设备信号
可以向 AI 客户端提出：
检查这台电机最近一周的振动、温度和电池数据。确认实际设备、X/Y/Z 方向、测量量和单位，先列出依据和待确认问题，再提出匹配建议。
- 调用
scout_capabilities查看可用流程和业务目标。 - 使用
scout_mission_list找到任务，再用scout_mission_get查看范围和当前阶段。 - 按工具定义调查获授权来源，查看候选依据。
- 补充设备手册、安装记录或字段负责人确认。
- 在相应角色下完成候选审阅、验证、审批和发布。
- 检查指定时间范围的实际读数与应用结果。
示例：审阅业务数据交付
按已发布业务目标检查这批授权数据。识别数据集，提出字段含义和身份键建议，检查重复记录与关系，并列出需要业务审阅人确认的定义。
使用能力接口选择业务目标和授权来源，按任务流程完成盘点、剖析、字段与 MDM 决策、试运行、审批和发布。周期性交付先与当前生效版本比较，详见后续批次交付。
REST API 入口
以下路径相对于 FactVerse 主机。资源标识应来自当前租户的授权响应。
| 方法和路径 | 用途 |
|---|---|
GET /api/v1/scout/missions | 列出任务 |
GET /api/v1/scout/missions/{missionId} | 读取任务 |
POST /api/v1/scout/missions/{missionId}/discovery | 启动发现 |
GET /api/v1/scout/missions/{missionId}/semantic-model-proposals/options | 获取模型草稿、设备、属性和兼容类别选项 |
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals | 提交模型提案供审阅 |
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals/{id}/review | 记录模型提案决策 |
POST /api/v1/scout/missions/{missionId}/semantic-model-proposals/{id}/apply-to-draft | 将获批提案应用到模型草稿 |
POST /api/v1/scout/missions/{missionId}/semantic-execution/dry-runs | 验证模型和引用发布计划 |
模型相关接口还需要相应的模型、MDM 和 DFS 权限。草稿应用完成后，继续使用独立的发布审批与执行流程。
处理重试和错误
要求 Idempotency-Key 的接口，应为同一逻辑请求和相同内容复用同一标识。超时后先读取操作状态，再重试服务明确支持的幂等动作。
| 响应 | 处理方式 |
|---|---|
| 401 | 更新或恢复平台认证 |
| 403 | 检查租户、模块、动作和相关数据权限 |
| 404 | 使用当前租户返回的资源标识重新查询 |
| 409 | 读取最新版本，重新验证并审阅 |
| 429 | 按响应要求退避 |
| 超时或服务错误 | 查询现有操作状态，保留请求关联信息 |
轮换客户端凭据
- 签发绑定适当账号、用途和权限的新凭据。
- 用
scout_capabilities和scout_mission_list验证只读访问。 - 更新客户端受保护的
X-API-Key配置并重新连接。 - 撤销旧凭据，确认新旧凭据的访问结果符合预期。
- 记录凭据标签、负责人、用途和轮换日期。
平台 MCP 凭据与模型提供商凭据分别管理。发现凭据泄露或人员离岗时，应按客户安全流程及时撤销访问。