常见原因及应对
1. Token 不足 / 输出被截断
表现： Skill 执行到一半突然停下，或者只执行了前半部分。
原因： 模型输出达到 token 限制，导致截断。
解决：
✅ 缩短 Skill 指令，分步执行
✅ 在 Workflow 中拆分多个短任务
✅ 使用 sessions_spawn 让子 Agent 独立执行各阶段
✅ 降低模型复杂度要求
2. Skill 指令不够清晰
表现： 模型"选择性执行"，挑简单的做，难的跳过。
原因： Skill 描述模糊，没有明确强制要求。
解决：
❌ 模糊指令："分析一下这只股票"
✅ 清晰指令："按以下步骤分析：
-
获取最新股价和PE值
-
获取近3年营收增长率
-
对比行业平均水平
-
输出结论（买入/持有/卖出）和理由
每一步都必须执行，不能跳过"
3. 模型推理能力不足
表现： 复杂多步骤任务只做第一步，后面的"忘了"。
原因： 上下文太长，主要任务被稀释。
解决：
✅ 使用 update_plan 明确当前进度
✅ 每阶段结束时总结状态再进入下一阶段
✅ 使用 thinking=on 开启推理模式
✅ 拆分为多个独立 Agent 任务
4. 工具执行失败但静默忽略
表现： 模型说"已执行"但实际没有结果。
原因： web_search、exec 等工具超时或报错，但模型没有上报。
解决：
✅ 指令中明确要求："如果任何工具调用失败，必须明确报告错误"
✅ 检查工具返回的错误信息
✅ 增加超时时间
✅ 使用 sessions_spawn 隔离执行，避免主上下文污染
5. 任务编排问题
表现： 多个 Skill 之间顺序混乱，或并行执行时出问题。
原因： Workflow 步骤之间没有清晰的状态传递。
解决：
✅ 确保每个阶段有明确的输入/输出约定
✅ 使用 write 工具把中间结果写入文件
✅ 下一阶段明确读取上一阶段的输出文件
✅ 添加验证节点："确认上一步输出存在再继续"
实战建议：让工作流更听话
📋 Plan + 验证法
如现在的任务是：
🔧 分而治之
不要让一个 Agent 做所有事：
Workflow:
任务1 → sessions_spawn(独立Agent, 执行Skill A)
任务2 → sessions_spawn(独立Agent, 执行Skill B)
汇总 → 主Agent读取A+B的结果进行整合
📝 强制报告格式
在 Skill 指令中要求：
执行完毕后，必须按以下格式报告：
-
执行状态：成功/失败/部分成功
-
实际输出：具体内容
-
异常信息：如有
-
建议：是否需要人工介入
快速排查清单
| 检查项 | 操作 |
|---|---|
| Token 是否耗尽 | 检查模型输出是否被截断 |
| 指令是否清晰 | 用 ✅ 的"清晰指令"模板重新描述 |
| 工具是否正常 | 单独测试每个工具调用 |
| 上下文是否过长 | 拆分任务，减少历史依赖 |
| 模型是否"跳步" | 添加强制验证节点 |
| 并发是否冲突 | 改为串行执行，或隔离到子Agent |
一句话总结
工作流不听话的主要原因：指令模糊、token不足、工具失败被忽略。核心解法：指令具体化、执行分阶段、结果强制验证。