多Agent协作 on Kalend's Blog

踩过的坑全给你：Blog Agent 最佳实践

Wed, 20 May 2026 00:00:00 +0800

跟着前三篇搭完 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。

看起来快，实际上：

对比项	Pipeline	裸写
Reviewer 把关	有	无
审计链路	有	无
返工次数	1-2 次	3-5 次
总耗时	16 分钟	30+ 分钟

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

是你不知道质量差——没有 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 用弱模型审。

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

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

角色	推荐模型	定位
Writer	glm-4.7	性价比写稿
Creator	glm-4.7	排版生成
Reviewer	glm-5.1	强模型把关

贵的模型只干贵的事——审核就是最该花 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 博客系统。

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

关注 varkm，一起学习，一起成长

多Agent协作系列完更，回复【agent】获取完整检查清单和 Profile 配置模板

多Agent协作实战：从写稿到审核的完整Pipeline

Tue, 19 May 2026 07:00:00 +0800

一篇AI对比文章，4个Agent接力完成，10步Pipeline自动跑通。中间经历3轮审核修复循环，全程1.5小时零人工介入。

先说结论

我们搭了一套多Agent协作的写作Pipeline。

4个专职Agent：写作、审核、博客部署、公众号发布，各司其职。

10步自动流水线：从第一行字写出来，到博客上线、公众号草稿就绪，全自动。

质量门禁：审核不通过，下游任务直接卡住，修好了才放行。

这是系列第3篇。第1篇讲了Kanban+Profile架构，第2篇搭了单个Writer Agent。

这篇是多Agent协作的完整实战——怎么让4个Agent接力干活、互相检查、自动修复。

1. 4个Agent怎么分工

先看全局。每个Agent有自己的Profile（身份配置）和SOUL.md（行为规范）。

Agent	职责	模型	特点
blog-writer	写原始文章	glm-5.1	204K上下文，有记忆
reviewer	审核内容质量	glm-5.1	只审不改，无记忆
blog-creator	转Markdown+部署	glm-4.7	最精简工具集
mp-creator	转公众号HTML+上传	glm-4.7	4个微信skill

类比：像一个编辑部——

◆ Writer是记者，负责采访写稿
◆ Reviewer是编辑，负责审稿把关
◆ Creator是排版员，负责报纸和网站两个渠道的排版

注意模型选择：写作和审核用强模型(glm-5.1)，格式转换用弱模型(glm-4.7)。

为什么？格式转换是机械活，不需要创造力。省下来的Token是真金白银。

2. Pipeline全景：10步流水线

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


 ① blog-writer ② reviewer Fan-out
 ┌──────────────┐ ┌──────────────┐ ┌─────────────────┐
 │ 写原始文章 │──────▶│ 内容审核 │──PASS│ 并行分发 │
 │ (glm-5.1) │ 7min │ PII/事实/AI味 │12min └──────┬──────────┘
 └──────────────┘ └──────────────┘ │
 ┌───────────┴───────────┐
 ▼ ▼
 ③ blog-creator ④ mp-creator
 ┌──────────────┐ ┌──────────────┐
 │ Markdown+部署 │ │ HTML+封面+上传│
 │ (glm-4.7) │ │ (glm-4.7) │
 └──────┬───────┘ └──────┬───────┘
 │ │
 ▼ ▼
 ⑤ reviewer ⑥ reviewer
 ┌──────────────┐ ┌──────────────┐
 │ Blog格式审核 │ │ 公众号格式审核 │
 └──────┬───────┘ └──────┬───────┘
 PASS ✅ FAIL ❌
 │ │
 ▼ ▼
 博客上线 ┌──────────────────┐
 │ ⟳ 审核修复循环×3轮 │
 │ ⑦修复→⑧审核→⑨修复 │
 │ →⑩审核 PASS ✅ │
 └──────────────────┘

解释一下关键节点：

◆ Step ①②：Writer写完文章，交给Reviewer审核内容
◆ Fan-out：审核通过后，同时派给Blog和公众号两个渠道
◆ Step ③④：两个Creator并行工作，互不等待
◆ Step ⑤⑥：各自的Reviewer再审一遍格式
◆ Step ⑦-⑩：公众号没过，进入修复循环

Blog那边一次通过，公众号那边经历了3轮修复。为什么？

因为公众号对段落长度有严格限制（每段≤100字），模型对"手机屏幕3行"的物理感知不够精确。

3. 依赖链：怎么让Agent自动接力

核心机制是Kanban的parents依赖。

创建任务时指定parents，意思是：“等这些父任务完成后，我才启动”。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 创建Writer任务
kanban_create(title="写对比文章", assignee="blog-writer")

# 创建Reviewer任务，依赖Writer
kanban_create(title="审核内容", assignee="reviewer",
 parents=["t_writer_xxx"])

# 创建两个Creator任务，依赖Reviewer
kanban_create(title="部署博客", assignee="blog-creator",
 parents=["t_reviewer_xxx"])
kanban_create(title="公众号推文", assignee="mp-creator",
 parents=["t_reviewer_xxx"])

注意看最后两行——它们的parents是同一个Reviewer任务。

这意味着Reviewer通过后，Blog和公众号同时启动。

这就是Fan-out（扇出）：一个任务完成，触发多个下游并行执行。

4. 质量门禁：FAIL就卡住

Reviewer不是走过场。它有5级审核维度，每级有明确的通过标准：

优先级	检查项	判定标准
🔴 必须通过	PII信息脱敏	手机号/邮箱/IP必须处理
🔴 必须通过	事实准确性	数据有来源，技术描述正确
🟡 3处FAIL	AI味检测	废话铺垫/过度道歉/套话
🟢 仅建议	品牌名	不强制，给出建议
🔵 格式规范	平台适配	Blog/公众号各有专项检查

关键机制：Reviewer判定FAIL时，在kanban_complete的metadata里写入问题列表。

下游任务的parents依赖没满足，不会自动启动。

必须创建修复任务，修好后再提交审核。这就是"门禁"——

不是标记一下就过了，是真的挡住，修好才放行。

5. 实战：3轮修复循环

说说真实发生的事。

第一轮公众号HTML生成后，Reviewer发现11个段落超标（限制100字/段）。

其中3个段落超过150字，在手机上会显示成一大坨。

mp-creator收到问题列表，拆分段落。

Reviewer二轮审核——还有5段超标。继续修。

第三轮审核——91个段落全部≤100字，PASS。

整个过程零人工介入。Reviewer自动FAIL，mp-creator自动读问题列表修复。

从第一次FAIL到最终PASS，修复循环自动跑了3轮。

教训：模型对"手机屏幕3行=100字"这种物理约束，理解不够精确。需要多轮迭代。

6. 模型分级：省钱的关键

4个Agent不是都用最贵的模型。按职责复杂度分级：

职责	模型	为什么
原创写作	glm-5.1（强）	需要创造力和上下文
内容审核	glm-5.1（强）	找错需要精确理解
格式转换	glm-4.7（省）	机械任务，够用即可
辅助工具	glm-4.5-air（最省）	压缩/搜索等轻量任务

实际效果：写作和审核两个最关键的环节用强模型保证质量。

格式转换这种"体力活"用弱模型，成本直接砍半。

而且reviewer在下游兜底，弱模型出了问题也能被拦截。

7. 搭建要点回顾

如果你也想搭这样的Pipeline，关键步骤：

◆ Step 1：为每个角色创建独立Profile
◆ Step 2：写SOUL.md定义行为规范
◆ Step 3：配置review skill的审核checklist
◆ Step 4：用kanban的parents参数搭建依赖链
◆ Step 5：按职责复杂度分配模型

最关键的设计决策是质量门禁。

没有它，Agent就是各干各的，错误会一路传到最终发布。

有了它，每个环节都有人把关，问题在传播之前就被拦截。

关注 varkm，一起学习，一起成长

多Agent协作系列第3篇 · 第4篇将分享踩坑最佳实践