FactVerse AI Agent 故障排查

当 AI 客户端已经接入 FactVerse AI Agent，但工作流无法按预期完成时，使用本指南。先检查 endpoint、API key、scope 和来源数据边界，再分析工作流逻辑。

快速排查顺序

1. 确认客户端使用了预期 host 和 endpoint。
2. 确认请求发送了 X-API-Key。
3. 在运行时列出工具，并把可见工具与预期工作流对比。
4. 确认 API key 的 scope 与工具 scope 匹配。
5. 检查来源数据新鲜度、资产映射、文档可用性和场景版本。
6. 排查写入动作被阻止前，先检查审批策略。

连接与认证

现象	可能原因	检查	修复
网关返回 403	缺少 API key header	检查请求 headers	使用 X-API-Key 发送 key
网关返回 401	key 无效、已撤销、过期或属于其他环境	请管理员确认 key 状态	轮换或重新签发 key
客户端连到错误路由	endpoint 路径或 host 错误	与 /mcp/base/、/mcp/pdm/ 或已启用模块 endpoint 对比	更新客户端 server URL
TLS 或网络失败	客户端无法访问客户 host	从同一网络测试 host	修复网络、代理、DNS 或证书信任

工具可见性与 scope

现象	可能原因	检查	修复
预期工具缺失	endpoint 错误、模块未启用或 key 缺少 scope	运行工具发现	使用正确 endpoint 或申请所需 scope
scope 被拒绝	key 没有所需 scope	对比工具 scope 与 scope 参考	通过管理员更新 key 策略
工具列表为空	endpoint 可达，但模块配置不可用	检查部署模块启用状态	启用模块或使用受支持 endpoint
写入工具不可见	key 只读或审批策略阻止写入工具	检查 base.action.write 和工作流策略	写入获批前把输出保留为草稿

数据与资产问题

现象	可能原因	检查	修复
无法解析资产	Platform、Inspector、DFS 和文档中的名称或 ID 不一致	按站点、区域、设备 ID 和别名检索	确认后更新资产映射
回答过于空泛	来源数据缺失、过期或范围过宽	检查数据时间戳和查询边界	收窄边界或修复数据管道
缺少近期工作记录	Inspector 或外部工单记录尚未同步	检查最近同步时间和源系统状态	刷新连接器后重跑
文档不可用	文档超出租户、权限或知识 scope	检查文档权限和租户归属	更新文档访问权限或挂接正确来源

预测性维护问题

现象	可能原因	检查	修复
健康摘要较弱	信号历史过短、稀疏或未映射	复核信号时长、采样间隔、单位和缺口	返回数据就绪度报告并修复输入数据
异常缺少解释	缺少维护上下文或运行模式	对比异常窗口、工作历史和模式变化	挂接工单、巡检备注和运行状态
告警过多	资产组或阈值配置过宽	复核资产边界和阈值策略	与维护工程师一起调优
后续动作被阻止	缺少工程师审核或写入 scope	检查审批状态和 base.action.write	将动作保留为草稿

Physical AI 与仿真问题

现象	可能原因	检查	修复
场景无法用于仿真	缺少场景版本或必要资产元数据	检查场景版本、资产版本、比例和坐标系	先准备场景包再计算
仿真表现较差	碰撞、质量、关节、摩擦或约束元数据不完整	运行 SimReady 就绪度复核	修复元数据并重新检查
结果无法复用	缺少假设、后端参数或验证备注	检查场景包和结果记录	补充假设、限制和验证备注
计算请求被阻止	缺少计算 scope 或负责人审批	检查 base.compute.run 和项目审批	流转给工程负责人

升级记录

问题需要产品或实施支持时，保留这份记录：

字段	说明
环境	Host、endpoint、租户或项目标识、部署类型。
请求	用户任务、时间范围、资产或场景边界、客户端类型。
工具发现	可见工具、缺失的预期工具、key 持有的 scope。
来源状态	资产映射、数据新鲜度、文档可用性、场景版本、连接器状态。
错误	HTTP 状态、工具错误、验证消息或被阻止的审批状态。
审核负责人	对下一步负责的操作员、维护工程师、工程负责人或管理员。