修复一个 Hermes Agent 技能后，我更确定：问 AI 问题前，要先让它读懂项目
摘要：先让AI读项目再修问题
最近我修了一个 Hermes Agent 的生成图片技能。
这个技能以前很好用。给它产品资料、参考图和运营需求，基本可以做到一次性出图，后面只需要做很小的修改。
但最近开始不对劲。
出来的图片乍一看还像那么回事，但产品对不上了。参考图里的产品和最终生成图里的产品，开始出现错位、变形、替换不准确的问题。
如果只是偶发一次，我会当成模型波动。
但连续几次都跑偏，就说明这不是审美问题，也不是提示词写得不够细，而是技能流程里某个环节可能变了。
这篇文章想分享的，不只是一个 Hermes 技能修复案例，而是一个非常实用的 AI 调试方法：不要一上来就问具体 bug，先让 AI 读懂项目。
先建立项目上下文，再定位问题，最后做最小修复。
一、很多人用 AI 修问题，第一步就错了
现在很多人已经习惯把问题丢给 AI。
我这个功能坏了，帮我修一下。
这句话看起来很自然，但在真实项目里，往往效果不好。
原因很简单：AI 还不知道你的项目长什么样。
它不知道有哪些角色，不知道技能怎么组织，不知道旧流程是什么，不知道输入输出在哪里，不知道你所谓的“跑偏”是视觉风格跑偏、产品匹配跑偏，还是接口参数跑偏。
在这种情况下，你让它直接修，它只能靠猜。
如果你的表达能力很强，能一次性把项目结构、模块边界、问题现象、复现路径、历史行为、当前差异都说清楚，AI 当然有机会直接给出好答案。
但大多数业务同学不是这样使用 AI 的。
我们更常见的表达是：
最近这个图不对，你看一下哪里有问题。
这句话对人类同事都不够，对 Agent 更不够。
所以这次我没有一上来告诉 Cursor：“Hermes 生成图片坏了，帮我修。”
我先让它学习。
二、第一步：先回顾运营角色 Alice 有哪些技能
我在 Mac 上用 Cursor 打开 Hermes 的项目文件夹。
第一句话不是描述问题，而是让它回顾项目里的运营角色 Alice。
请你先不要修改代码。
请阅读当前 Hermes 项目，帮我回顾一下运营角色 Alice 下面有哪些技能。
要求：
1. 先梳理目录结构和角色配置
2. 找出 Alice 已经注册或可调用的技能
3. 用表格说明每个技能的用途、入口文件、输入输出
4. 暂时不要分析问题，也不要给修复建议
这一步看起来慢，其实非常关键。
因为 Hermes 不是一个单文件脚本，而是一个 Agent 项目。里面可能有角色、技能、工具、提示词模板、接口调用、数据格式、日志和运行脚本。
如果不先知道 Alice 有哪些技能，后面讨论“生成图片技能”时，AI 很可能不知道它位于哪个模块，也不知道它和其他技能之间有没有共用配置。
这一步的目标不是修复，而是建立项目地图。
先让 Agent 读项目，再读子模块，最后进入具体问题。
三、第二步：再让它回顾对应的生图技能流程
等它梳理完 Alice 的技能后，我才进入第二步。
这次不是问问题，而是让它回顾生成图片技能的完整流程。
请继续阅读 Alice 的生成图片技能。
这一步仍然不要修改代码。
请你梳理这个技能的完整执行流程：
1. 用户输入会经过哪些步骤
2. 产品资料、参考图、提示词分别在哪里处理
3. 调用了哪些图片生成平台或接口
4. 参考图是怎样被传入接口的
5. 最终图片结果是怎样返回给用户的
6. 请指出关键文件、关键函数和关键数据结构
这一步特别适合复杂项目。
如果项目庞大，不要指望 AI 看一眼全局就能修好。应该让它继续学习当前子项目、当前模块、当前技能。
你可以把它理解成带一个新同事接手工作。
你不会一上来就说“客户投诉了，赶紧改”。你会先告诉他：这个客户是谁，订单怎么流转，供应商在哪里，系统里哪个字段最关键。
Agent 也是一样。
Skill 本质上是可重复调用的工作 SOP。修 Skill 之前，要先让 AI 读懂这套 SOP。
四、第三步：学习完模块后，才描述问题
前两步完成后，AI 已经知道：
- Alice 是什么角色；
- Alice 有哪些技能；
- 生成图片技能在项目里的位置；
- 生图流程从输入到输出经历了哪些环节；
- 参考图在哪一步被处理；
- 图片生成接口在哪一步被调用。
这时我才描述真正的问题。
现在开始分析问题。
最近 Alice 的生成图片技能效果明显跑偏：
1. 以前根据产品参考图生成图片，产品基本可以对上
2. 最近生成出来的图片，产品和参考图经常对不上
3. 文案、风格、构图有时还可以，但产品主体不稳定
4. 请基于你刚才梳理的流程，重点排查参考图传入、图片接口参数、模型版本或平台接口变化
要求：
1. 先提出可能原因，并说明证据在哪里
2. 再给出最可能的根因
3. 不要大改架构，优先找最小修复方案
这个提问方式和“帮我看看为什么生图跑偏”完全不一样。
它不是把所有信息一次性倒给 AI，而是分阶段建立上下文。
更重要的是，它把排查范围限定在“参考图传入、图片接口参数、模型版本或平台接口变化”。
这样 AI 不会一上来去改提示词，也不会把问题归因到“描述不够详细”。
在这个案例里，最终定位到的问题也确实不在提示词。
五、真正的根因：生图平台接口升级了
经过这一轮分析，问题终于定位清楚。
生图平台的接口发生了变化，统一切到了新版接口。
老版本里参考图的传参格式是一套逻辑；新版接口里，参考图格式变了。
Hermes 的生图技能还在用旧格式传参考图，所以接口虽然能跑通，但参考图没有被正确理解。
这就解释了为什么图片看起来不是完全失败，而是“产品对不上”。
因为文案、风格和构图相关参数可能仍然有效，但产品参考图这个关键输入失效或弱化了。
如果一开始只让 AI 改提示词，它可能会继续堆描述：产品要一致、颜色要一致、结构要一致。
但真正的问题是接口格式。提示词再长，也修不好数据传错的问题。
问题不在提示词，而在新版接口的参考图格式。
六、修复动作：只改接口适配，不重写整个技能
定位到根因后，修复就很清楚。
我让 Cursor 按新版接口要求修复参考图传入格式。
请根据刚才定位到的问题进行最小修复。
目标：
新版生图接口已经改变参考图格式，请修复 Alice 生成图片技能中参考图传入逻辑。
要求：
1. 不要重写整个生成图片技能
2. 只修改新版接口适配相关代码
3. 保留旧流程中仍然有效的提示词、产品资料处理和结果返回逻辑
4. 修改后说明改了哪些文件、哪些函数、为什么这样改
5. 如果存在兼容旧接口的必要，请加清晰的分支或适配函数
6. 给出一组最小验证步骤，确认参考图能被新版接口正确识别
这里有一个原则：修复杂 Agent 技能时，优先做最小修复。
不要因为发现一个问题，就顺手重构整个项目。
尤其是 Hermes 这种已经能稳定跑业务的 Agent 项目，最怕把原本正常的流程改坏。
修完以后，再跑一轮验证：同样的产品资料、同样的参考图、同样的运营要求，生成结果恢复正常。
这说明根因判断是对的。
七、这次案例真正有价值的地方
这个案例表面上是在修一个生图技能。
但对所有正在用 Codex、Cursor、Claude Code、Hermes、Manus 或其他 Agent 工具的人来说，它背后的方法更重要。
从项目地图到模块流程，再到问题定位和最小修复。
我把它总结成四步。
第一步：先让 AI 建立项目地图
不要直接问 bug。
先让它看角色、目录、技能、配置、入口文件和调用关系。
这一步的输出最好是表格，因为表格能迫使 AI 把项目结构讲清楚。
第二步：让 AI 学当前子模块
如果项目很大，不要让 AI 一次性吞全部。
让它专门学习当前模块。比如这次就是 Alice 的生成图片技能。
要求它讲清楚输入、处理、调用、输出和关键数据结构。
第三步：再描述问题现象
描述问题时，要讲清楚“以前怎样、现在怎样”。
这句话很重要。
因为 Agent 需要对比历史正常行为和当前异常行为。
比如这次不是“图片不好看”，而是“以前产品能对上，现在产品对不上”。这会把排查方向从审美转到参考图和接口参数。
第四步：要求先定位，再修复
不要让 AI 一边猜一边改。
先让它列可能原因，说明证据，再给最可能根因。
确认根因后，再要求最小修复。
这比直接让 AI 改代码稳得多。
八、可以直接复制的提问模板
下面这套模板可以直接拿去用。
不管你修的是 Hermes Skill、Codex Skill、飞书机器人、选品 Agent，还是一个自动化脚本，都可以按这个顺序来。
模板 1：建立项目地图
请你先不要修改代码。
请阅读当前项目，帮我梳理项目地图：
1. 项目主要角色或模块有哪些
2. 每个模块负责什么业务任务
3. 关键入口文件在哪里
4. 关键配置文件在哪里
5. 当前和我问题相关的模块可能是哪几个
要求：
- 先输出结构化总结
- 不要分析具体问题
- 不要提出修复方案
模板 2：学习子模块流程
请继续阅读和【模块名称】相关的文件。
这一步仍然不要修改代码。
请你梳理这个模块的完整流程：
1. 输入从哪里来
2. 经过哪些处理步骤
3. 调用了哪些外部接口或工具
4. 关键数据结构是什么
5. 输出如何返回
6. 哪些文件和函数最关键
请用流程图式文字说明。
模板 3：描述问题并定位原因
现在开始分析问题。
问题现象：
1. 以前正常表现：……
2. 现在异常表现：……
3. 我已经观察到的变化：……
4. 请优先排查：……
要求：
1. 先列可能原因
2. 每个原因说明证据在哪里
3. 给出最可能根因
4. 暂时不要大改代码
模板 4：最小修复
请基于刚才确认的根因做最小修复。
要求：
1. 不要重写整个模块
2. 只修改和根因直接相关的代码
3. 保留原来已经正常工作的流程
4. 修改后说明改了哪些文件和函数
5. 给出验证步骤
6. 如果存在风险，请说明回滚方式
九、不要误解：不是让 AI 慢慢聊天
有些人看到这里，可能会觉得这个方法太慢。
其实正好相反。
复杂项目里，最快的方式不是直接问答案，而是先补上下文。
你前面省掉的 5 分钟，后面可能会用 2 个小时来收拾错误修改。
尤其是 Agent 项目，一旦牵涉到角色、技能、接口、工具、权限和数据格式，很多 bug 都不是单点代码问题，而是流程适配问题。
这次生图技能跑偏，就是典型例子。
如果只看结果，会以为是提示词变差了。
如果先读流程，就能发现参考图传参格式才是关键。
AI 修项目，不是靠一句神奇提示词，而是靠清晰的上下文、正确的排查顺序和可验证的最小改动。
十、给跨境团队的启发
跨境团队以后会越来越多地使用 Agent。
选品 Agent、广告 Agent、Listing Agent、图片 Agent、客服 Agent、飞书日报 Agent，都会慢慢进入日常工作。
但 Agent 越多，维护就越重要。
一个平台接口升级，一个字段格式变化，一个图片模型版本调整，都可能让原本稳定的技能开始跑偏。
所以团队不只是要会做 Agent，也要会修 Agent。
我的建议是：每个重要技能都要沉淀三份东西。
- 技能说明：这个 Skill 什么时候触发、输入是什么、输出是什么。
- 流程说明：数据从哪里来，经过哪些步骤，调用哪些接口。
- 验证用例：一组稳定样例，用来判断修复前后是否恢复正常。
有了这三份资料，下次再出问题，你就不用从零开始解释。
你可以让 AI 先读说明，再读流程，再跑验证。
这才是 Agent 时代真正的工作方式。
不要把 AI 当成许愿池。把它当成一个新加入项目的同事：先带它看项目，再带它看模块，最后再让它解决问题。
这次 Hermes 生图技能修复，最后只是改了一个接口适配问题。
但它提醒我一件事：
未来真正会用 AI 的人，不一定是提示词写得最长的人，而是最会组织上下文、拆解问题、验证结果的人。
素材说明
- 案例来源：用户提供的 Hermes 生图技能修复复盘