跟着前三篇搭完 Pipeline，满怀信心跑了一次——然后各种炸。这篇文章是我踩了 50+ 个坑之后，精选出 12 个最致命的。

多Agent协作系列 第4篇/共4篇（收尾篇） | 避坑指南 | 约2800字 | 作者：varkm

先说结论

踩了 50 多个坑，80% 集中在五个环节。

我把最致命的 12 个挑出来，按"写→排→配→协→省"五个阶段给你。

每个坑都附具体命令和代码。

不是"建议你检查一下"，是"复制这条命令就能验证"。

一、写作篇：Agent 写的东西能看吗

内容质量不是模型能力问题，是验证流程问题。

Writer 写什么不重要，Reviewer 能拦住什么才重要。

坑1：子代理编造不存在的配置键名

这是最致命的一个坑，没有之一。

子代理会"幻觉"出看似合理的配置键名。

比如 tool_circuit_breaker，听起来很专业对吧？

源码里根本没有这个键。正确的叫 tool_loop_guardrails。

读者拿去配，白配。文章发出去，评论区翻车。

类似的情况还有：busy_input_mode 实际叫 display.busy_input_mode。

prompt_cache_ttl 实际叫 prompt_caching.cache_ttl。

验证方法——每个键名必须过这关：

1

grep -rn "键名" hermes_cli/config.py

不存在就不要写，哪怕 AI 信誓旦旦说"我确认过"。

这条规则我写进了 Reviewer 的检查清单，至今拦住了 20+ 次编造。

坑2：AI 味套话满天飞

“值得注意的是”、“总的来说”、“首先…其次…最后”。

这些话一出现，读者秒懂：AI 写的。

解法： 把 AI 味关键词清单写进 Reviewer 的规则文件。

逐段扫描，强制替换为自然过渡。

不是零容忍——允许 1-2 处漏网，但多了必须打回重写。

我维护了一份清单，大概 15 个高频 AI 味词组。

每次审校先跑一遍关键词扫描，比人工逐段看效率高 10 倍。

坑3：评测文事实核查翻车

“发布不到一个月”——实际仓库已创建 3 个月。

“不支持 Docker”——仓库里 Dockerfile 就在根目录。

“我两个都在用”——说实话，根本没用过第二个。

这条最危险，因为读者会去验证。一旦翻车，信任归零。

核心原则： 每一条事实声明都必须验证。

星数看 GitHub API，技术栈看源码，体验只写真话。

验证命令：

1
2

curl -s https://api.github.com/repos/owner/repo \
  | jq '{stars: .stargazers_count, created: .created_at}'

版本追溯三步法：

1
2
3

git log --oneline --all --grep="功能名" | head -5
git tag --contains <commit_hash> | head -3
git show --no-patch --format="%H %ci %s" <commit_hash>

写作篇一行检查：grep -rn "配置键名" config.py

二、排版篇：微信客户端是最大的敌人

微信渲染引擎会做你意想不到的事。

所有样式必须 inline，微信会剥离 <style> 和 class。

这是排版篇的第一条铁律，后面所有坑都跟它有关。

坑4：列表标签全线崩溃

<ul>、<ol>、<li>，三个标签在微信里有三个独立 bug。

<ol> 编号跨板块连续计数：第一个列表从 1 开始没问题。

第二个列表不从 1 开始，接着上一个的编号往下数。

<ul> 加手动 bullet 产生双圆点，一行出现两个点。

<li> 的 margin 产生空行，每个 item 变成空行 + 内容两行。

我在这三个标签上各踩了一轮，前后折腾了两天。

终极方案： 全部不要用。

所有列表统一用 ◆ 替代：

1
2

<p style="margin:4px 0;line-height:1.8;
padding-left:14px;">◆ 列表内容</p>

简单、稳定、不炸。这是 3 轮踩坑之后的终极结论。

坑5：代码块黑底黑字

微信会剥离 <pre> 标签的 color 样式，只剩 background。

黑色背景 + 黑色文字 = 完全看不了。

读者截图问我"代码块怎么什么都没有"。

我才知道这个坑——在电脑浏览器里是正常的。

解法： 永远不要用深色代码块背景。

浅色方案用 <section> 包裹：

1
2
3
4
5
6

<section style="background:#f6f8fa;
border-radius:6px;padding:14px;
border:1px solid #e1e4e8;">
<pre style="margin:0;color:#24292e;
font-size:14px;">代码内容</pre>
</section>

关键是用 <section> 而不是直接靠 <pre> 的样式。

深色方案也可以，但同样必须用 <section> + <span> 做语法高亮。

坑6：封面图中文变方格

Pillow 默认字体（DejaVu）不支持中文。

所有中文字符渲染成方格/空白。

发出去才知道——封面上的标题全是空白方块。

解法： 必须用系统 CJK 字体，且 .ttc 文件要加 index=0：

1
2
3
4
5
6

from PIL import ImageFont
font = ImageFont.truetype(
  "/usr/share/fonts/opentype/noto/"
  "NotoSansCJK-Bold.ttc",
  36, index=0
)

.ttc 是字体集合文件，不指定 index 可能加载到错误字体。

这个参数踩了我半小时才找到原因。

排版篇一行检查：grep -n '<ul>\|<ol>\|<li>' article.html

三、配置篇：80% 的崩溃来自两个默认值

不是功能不好用，是默认配置没改。

改两个配置，解决 80% 的 Pipeline 崩溃。

坑7：max_tokens 太小导致截断

默认 max_tokens 只有 4096。

一篇 2000 字的文章大概需要 8000-12000 token。

超了直接截断，Agent crash，日志显示：

1
2

Response truncated (finish_reason='length')
refusing to execute incomplete tool arguments

解法： Profile 配置里改成 32768 或更大：

1
2

model:
  max_tokens: 32768

Worker 自己改不了这个值。

必须由 Orchestrator 在 Profile 配置文件里提前设好。

算笔账： 一次跑完 vs 截断重跑。

截断一次 = 浪费已消耗的 token + 重新跑一遍完整流程。

max_tokens 调大，单次不会多花，但省掉了重试的浪费。

坑8：Skill 文件没复制到 Profile 目录

全局 skill 目录和 Profile 独立目录是两套。

Profile 看不到全局目录里的 skill，必须手动复制。

报错信息：

1

Error: Unknown skill(s): article-review

明明装了，为什么找不到？因为装错地方了。

解法： Orchestrator dispatch 前检查并复制：

1
2

cp -r ~/.hermes/skills/devops/article-review \
  ~/.hermes/profiles/blog-writer/skills/devops/

路径规则：全局 ~/.hermes/skills/ ≠ Profile 独立目录。

我第一次遇到这个报错时，反复重装了 3 遍 skill 才反应过来。

装的全是全局目录，Profile 根本看不到。

这两个配置改完，80% 的 Pipeline 崩溃直接消失。

配置篇一行检查：grep "max_tokens" ~/.hermes/profiles/你的profile/config.yaml

四、协作篇：Agent 编排的三个反模式

Pipeline 不是流程负担，是质量保险。

跳过的每一步，都会在下游加倍还回来。

坑9：跳过 Pipeline 裸写

手动 delegate_task 直接让一个 Agent 写文章，没有 Reviewer。

看起来快，实际上：

裸写最大的问题不是质量差。

是你不知道质量差——没有 Reviewer 告诉你哪里有问题。

等读者反馈，已经晚了。

我写过一篇裸写的文章，3 个配置键名编造，2 处 AI 味套话。

没有 Reviewer 拦，全发出去了。后来评论区被指出才改。

强制规则： 走完整 Kanban Pipeline，无例外。

流程：Writer → Reviewer → Creator → Reviewer → 发布。

坑10：task_id 幻觉编造

kanban_complete 时传入编造的 task_id。

kernel 验证不通过，直接报错：

1

phantom id blocks the completion

核心： task_id 只能来自 kanban_create 的返回值。

不要从文字描述里"编"，不要从上一轮的上下文里"猜"。

正确写法——先捕获返回值，再传入：

1
2
3
4
5
6

card = kanban_create(
  title="审校文章", assignee="reviewer"
)
kanban_complete(
  created_cards=[card["task_id"]]
)

错误写法：从摘要中看到 “t_deadbeef” 就传进去。

kernel 会验证每个 id 是否真实存在，幻编的 id 100% 被拦截。

坑11：Reviewer 模型比 Writer 弱

Writer 用最强模型写，Reviewer 用弱模型审。

结果：审校形同虚设，该拦的拦不住。

规则： 审核模型必须 ≥ 写作模型。

贵的模型只干贵的事——审核就是最该花 token 的环节。

五、成本篇：怎么让 Agent 省着花

不是不能用贵模型，是别在不需要的地方用。

坑12：Pipeline 被反复"跳过"

完整 Pipeline 6 步全 PASS 只需 16 分钟。

但经常有人觉得"Pipeline 慢"，手动跳过。

跳过的后果：质量不过关 → 返工 → 再跑一遍 → 总耗时翻倍。

不要跳。 16 分钟换一次通过，比跳过之后返工 30 分钟划算。

分层用模型才是真省钱

全文用一个模型 = 全程用最贵的模型 = 浪费。

写作用性价比模型，快且便宜。

排版用同样的性价比模型。

审核用强模型，只审核一次。

贵模型用得少，但每次用在关键位置。

max_tokens 调大 + 模型分层，总成本反而比"省钱方案"更低。

具体算一下：Writer 跑 5 分钟用 glm-4.7，Reviewer 跑 2 分钟用 glm-5.1。

比全程用 glm-5.1 省 60% 以上 token。

该省省，该花花——审核环节绝不省钱。

系列 4 篇收尾

回顾整个多Agent协作系列：

第 1 篇 讲了 Kanban + Profile，让 Agent 有了分工和身份。

Kanban 是任务看板，Profile 是 Agent 的角色配置。

两者结合，Agent 从"什么都干"变成"各司其职"。

第 2 篇 搭建了 Blog Writer Agent，7 步从零到能写能部署。

从安装框架到写第一篇文章，全程可跟着操作。

第 3 篇 组建了完整 Pipeline，多 Agent 协作链路跑通。

Writer 写稿 → Reviewer 审校 → Creator 排版 → 发布。

6 步全 PASS 只需 16 分钟。

第 4 篇（这篇）补上了最后一环：搭完怎么不炸。

12 个坑，5 个阶段，每个都有具体命令和代码。

收藏这篇，每次跑 Pipeline 之前扫一遍检查清单。

四篇读完，你就有了一套完整的 Agent 博客系统。

从搭建到协作到避坑，该踩的坑我都替你踩了。