常见问题和故障处理
常见问题和故障处理
本页说明创建和运行 Agent 时最常见的问题。
Agent 无法启动
可能原因：
- 任务目标为空或过短。
- 没有连接必要资源。
- 没有设置预算。
- Agent 角色为空。
- Git 或云授权失败。
- 审批策略缺失。
处理方式：
- 补充任务目标。
- 打开准备清单。
- 连接缺失资源。
- 重新确认 Agent 角色。
- 设置预算。
- 再次启动。
任务一直准备中
可能原因：
- 资源发现较慢。
- SK 快照解析失败。
- 云资源接口超时。
- 密钥保管器不可用。
- Agent 平台排队。
处理方式：
- 查看准备清单状态。
- 查看最近事件。
- 重新解析 SK。
- 检查资源授权。
- 稍后重试。
- 联系管理员查看平台状态。
任务显示需要输入
任务本身仍是 running，但 Agent 触发了 task.blocked 事件，说明 Agent 无法继续判断。
常见问题：
- 需求有多个方向。
- 资源范围不明确。
- 需要选择方案。
- 缺少测试账号。
- 缺少部署目标。
处理方式：
- 打开任务详情。
- 阅读问题。
- 给出明确选择。
- 不要只回复“继续”。
等待审批
任务仍是 running，但存在一条状态为 pending 的审批请求，说明 Agent 请求了高危操作。
处理方式：
- 查看操作类型。
- 查看请求的 Agent。
- 查看目标资源。
- 查看风险等级和凭证 TTL。
- 批准或拒绝。
不确定时选择拒绝，并要求 Agent 生成更详细计划。
Git 授权失败
可能原因：
- token 过期。
- 仓库权限不足。
- 分支不存在。
- 路径范围过窄。
- 组织策略不允许访问。
处理方式：
- 重新授权 Git。
- 检查仓库权限。
- 选择正确分支。
- 调整路径范围。
- 联系组织管理员。
SK 解析失败
可能原因：
- SK 仓库不可访问。
- ref 不存在。
- SKILL.md 缺失。
- 技能声明格式错误。
- 技能请求了禁止工具。
处理方式：
- 选择可访问的 SK 仓库。
- 固定到有效 tag 或 commit。
- 修复 SKILL.md。
- 禁用危险技能。
- 重新解析快照。
云资源不可访问
可能原因：
- 云授权过期。
- 资源不在授权范围。
- 环境选择错误。
- 需要审批。
- 短期凭证过期。
处理方式：
- 重新连接云账号。
- 调整资源范围。
- 重新审批。
- 重新派生短期凭证。
- 检查云平台状态。
预算耗尽
可能原因：
- 任务范围过大。
- 失败后重复重试。
- 使用了高成本模型。
- 多个 Agent 并行执行。
处理方式：
- 暂停任务。
- 查看消耗明细。
- 缩小范围。
- 拆分任务。
- 调整模型策略。
- 提高预算后继续。
任务失败
处理顺序：
- 查看失败原因。
- 查看最近日志。
- 查看资源访问记录。
- 查看是否有审批被拒绝。
- 查看预算是否耗尽。
- 查看测试或构建输出。
- 让 Agent 汇总可恢复方案。
疑似密钥泄漏
立即处理：
- 停止任务。
- 撤销相关凭证。
- 轮换密钥。
- 检查 Git、日志、Markdown 和截图。
- 通知安全负责人。
- 查看审计记录。
- 重新授权后再继续。
交付结果不符合预期
处理方式：
- 对照验收标准。
- 明确指出不符合的地方。
- 要求 Agent 只修复指定问题。
- 不要扩大任务范围。
- 必要时退回到计划阶段。
示例：
当前结果不符合验收标准第 2 条。
请只修复用户登录后的项目列表为空问题。
不要修改通知模块。
完成后运行现有测试，并给出 diff 摘要。