按现象排查问题
先记下页面、时间、Agent/版本 ID、Session/Run ID、HTTP 状态、稳定错误 code 和 request_id。不要把密码、验证码、API Key、完整消息或工具参数发给公开诊断渠道。
| 现象 | 先检查 | 安全的下一步 |
|---|---|---|
| 收不到注册/恢复验证码 | 邮箱地址、垃圾邮件、10 分钟有效期和发送频率 | 使用该流程自己的新验证码；旧挑战和别的用途验证码不可混用 |
| 网页登录失效 | 是否改密、重置密码、换邮箱或切换账号 | 回到控制台重新登录；清除旧页面身份后再读取配置 |
| API/MCP 401 或 403 | Key/OAuth 是否撤销、scope、Agent 范围、Subject、Origin | 按身份说明补正确授权；不复用别人的 Subject |
| Agent 发布不成功 | 草稿 valid/ready、模型可用、价格、模型能力、工具集引用 |
依据校验字段修正；冲突时先回读最新 revision |
| 旧配置提交报字段校验失败 | 是否仍提交 max_context_chars、max_result_bytes、max_result_tokens |
按配置迁移删除旧字段；不要只改 SDK 的类型断言 |
| 工具执行成功，模型却缺少部分内容 | dry-run 的 context_preview.truncated 和实际 result，原结果是否超出字节预算 |
分页、筛选或按业务 ID 读取片段；原始回执仍保存，历史搜索不读取工具回执 |
| 压缩比预期早，或调整配置未生效 | Session 固定版本、Run 收紧值、渠道输入/总容量与输出预留、完整请求估算 | 按上下文机制核对有效窗口；新配置发布后需新 Session，不能只看原始消息长度 |
发送报 402 INSUFFICIENT_BALANCE |
可用余额、未结预留和模型预留上界 | 在“余额与用量”核对；此次未请求模型，待额度条件满足后再发送 |
| Run 一直排队或等待 | 运行诊断阶段、并发容量、单次调用超时、审批、执行器连接/缺失处理器 | 在原 Run 上解决待处理项；不会因刷新页面自动启动工具 |
| 流式连接断开 | 原 Run 是否仍活跃，快照与 resume_cursor |
续接同一 Run；不要换幂等键发送第二次 |
| 业务操作或费用结果不明 | 诊断、调用 ID、产品业务记录、receipt/模型账务状态 | 保留待核对；由接入方或平台按各自归属核对，避免重做副作用 |
“工具模拟测试通过”只证明 Schema 和模拟回执有效，不能证明业务系统权限或队列可用。配置的执行绑定也不代表执行器在线。工具页。
需要反馈具体问题时提供最小关联信息和可复现步骤。平台诊断默认使用安全元数据，不自动包含正文；产品侧业务数据和工具处理由产品团队核对。错误与限制列出更多 code。