AI Agent 工作流排障实战：从博客路径错误到图片生成失败的完整修复

引言

今天我想记录一次完整的 AI Agent 工作流排障与优化过程。这不是传统的排障（没有报错、没有故障），而是通过一次「写博客」任务的执行，逐步发现了三个不同层面的问题，最终修复了涉及多个 Agent 协作的全局配置。

整个过程耗时约两个小时，包含五轮迭代。核心收获是：AI Agent 工作流的稳定运行，不仅需要正确的 Skill 定义，还需要所有协作 Agent 的配置保持一致。

问题清单：

1. 博客写入路径错误（/content/ 写到了错误目录）
2. 图片生成工具错误（调用了不可用的第三方模型）
3. 协作模式错误（应该委托专业 Agent 生图，知识归档员自己直接动手）
4. 配置传播错误（design-yuntianguang 自身配置写的是 Midjourney/SD/DALL-E）

第一轮：博客写入路径错误

症状

用户要求将一篇排障笔记（位于 /AI/OpenClaw/06-排障/）改写成博客文章。任务完成后，文章被写入到了 /read-and-write/02-写作/，而不是与源文件同目录。

分析

kb-writer 的 AGENTS.md 中确实有路径规则，但规则中没有明确「博客写入目录 = 源文件所在目录」这一条。

修复

在 AGENTS.md 和 TOOLS.md 中新增「博客路径铁律」：

博客文章必须写入与源文件相同的目录（同一分类）
源文件在 /AI/OpenClaw/06-排障/ → 博客也在 /AI/OpenClaw/06-排障/
判定规则：目录跟随源文件，不跟随内容主题

这个规则看似简单，但实际上解决了一个根本性的分类问题：博客是源文件的衍生品，不是新创作的内容，应该保持同一分类。

第二轮：图片生成工具错误

症状

在博客写入成功后，图片生成环节报错：

Gemini Flash：Google API 429 配额超限
GPT Image 2：LiteLLM 模型名无效（400）
OpenRouter Gemini：地区限制（403）

初步判断

配置中确实指定了 agnes-image skill，但设计 Agent（design-yuntianguang）似乎调用了错误的工具。

第一次修正（错误方向）

在 AGENTS.md 中改为「kb-writer 自己直接调用 agnes-image 的生图脚本」，绕过了设计 Agent。这是错误的做法——破坏了 Agent 分工架构。

用户纠正

用户的反馈很明确：

生图还是要发提示词给专业的 design-yuntianguang 这个 agent 使用 agnes-image 这个 skill 技能生图，而不是你自己知识库归档员自己生图

第三轮：发现真正的根因

症状

设计 Agent 收到生图请求后，为什么会去调用 Gemini/GPT Image/OpenRouter？

关键发现

检查 design-yuntianguang 的 AGENTS.md，发现工具依赖写的是：

AI 图片生成 API（Midjourney / Stable Diffusion / DALL-E 等）

完全没有提到 agnes-image。这就是根本原因：Agent 不知道正确的工具是什么。

修复

1. design-yuntianguang 的 AGENTS.md：将 agnes-image 设为唯一核心工具
2. design-yuntianguang 的 TOOLS.md：新增 agnes-image 工具速查 + 标准工作流
3. 删除所有 Midjourney/SD/DALL-E 的引用（标注为不可用）

第四轮：系统性修复

根因定位后，开始系统性修复所有相关文件：

AGENTS.md（kb-writer）

blog-writer SKILL.md

升级到 v3.0，核心变更：

• Step 4：封面图生成 → sessions_send 调用 design-yuntianguang，指定 agnes-image
• Step 4.5：文内插图 → 同上
• 注意事项：新增「图片后处理」「委托生图」两条

agnes-image SKILL.md

新增内容：

• 尺寸不精确问题说明
• 标准后处理工作流（Resize + WebP + 重命名 + 删除临时文件）
• 博客图片规格对照表
• 文章内图片引用格式

design-yuntianguang 配置

AGENTS.md 新增：

• 核心能力 0：图片生成（博客相关），agnes-image 为核心工具
• 核心能力 0.1：博客生图标准工作流（完整的执行脚本）
• 工具依赖：更新为 agnes-image + 禁用旧工具列表

TOOLS.md 新增：

• agnes-image 工具速查（脚本路径、环境变量、尺寸格式）
• 标准工作流（6 步）
• 博客图片保存路径

第五轮：最终验证

一致性检查：

# 所有提到 design-yuntianguang 的地方
grep -rn "design-yuntianguang" /home/oklife/.openclaw/skills/blog-writer/SKILL.md \
  /home/oklife/.openclaw/workspace-kb-writer/AGENTS.md \
  /home/oklife/.openclaw/workspace-kb-writer/MEMORY.md \
  /home/oklife/.openclaw/workspace-design-yuntianguang/AGENTS.md

# 所有提到生图工具的地方
grep -rn "agnes-image\|Midjourney\|Stable Diffusion\|DALL-E" /home/oklife/.openclaw/skills/blog-writer/SKILL.md \
  /home/oklife/.openclaw/workspace-kb-writer/AGENTS.md \
  /home/oklife/.openclaw/workspace-design-yuntianguang/AGENTS.md

验证结果：

• 所有文件一致指定 agnes-image 为唯一工具
• 协作模式统一为「kb-writer 发 prompt → design-yuntianguang 执行 → 回传路径」
• 没有任何文件引用 Midjourney/SD/DALL-E/Gemini/GPT Image

实际修改清单

总修改文件 7 个，新增/变更内容约 30 处。

五条核心教训

教训 1：Agent 分工必须明确

ki-writer 管内容（写 prompt + 路径），design-yuntianguang 管执行（生图 + 后处理）。两者不能互相替代。当一个 Agent 试图做另一个 Agent 的工作时，协议就被破坏了。

教训 2：配置传播要彻底

最初只在 kb-writer 中指定了 agnes-image，但忘了更新 design-yuntianguang。导致设计 Agent 接收请求后，按自己的旧配置去调用 Midjourney/SD/DALL-E，而这些工具根本不可用。

规则：修改工具配置时，必须问「还有谁需要知道这件事？」

教训 3：Skill 文件是最好的文档

本次排障的所有发现都记录到了 AGENTS.md、TOOLS.md 和 MEMORY.md 中。下次遇到同类任务时，Agent 会自动读取这些文件，不需要再次排查。

教训 4：用户反馈是最终的纠偏机制

当 kb-writer 自己直接生图时，虽然任务完成了，但架构是错误的。如果没有人指出这个问题，错误配置可能会一直延续下去，直到某次生图失败时才暴露。

规则：技术决策（是否委托、是否并行、是否跳过）都应该有用户确认。

教训 5：排障要从全局视角出发

最初的错误（路径错误）只是表象。真正的根因是「未明确博客路径跟随源文件」。如果只修复表面症状而不追溯根因，同样的错误会在不同场景下反复出现。

后续改进方向

1. 自动化验证：编写 Skill 一致性检查脚本，确保所有 Agent 引用的工具配置一致
2. 配置同步：当某个 Skill 的工具配置变化时，自动通知相关 Agent 更新
3. 文档审查：将「是否涉及跨 Agent 配置变更」加入 Agent 的决策树
4. 测试用例：为博客编写流程编写端到端测试，确保各环节配置正确

关联阅读

• [[2026-07-11-1014-memory-search-qmd-fallback|memory_search 反复 fallback？一次配置冲突引发的血案]]
• [[2026-06-28-1100-知识归档工作流程经验教训|知识归档工作流程经验教训]]
• [[2026-07-03-1600-blog-writer-skill-agent-orchestrator-经验教训|blog-writer skill Agent 编排器经验教训]]

–全文完–

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：　　　《内容已折叠，点击展开》

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。　　　　　　　　　　　　　　　　　　　　　《内容已折叠，点击展开》

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

转载请注明来自https://oklife.me。