Blog-writer Skill/Agent/Orchestrator 避坑指南：一次流程优化的血泪史

从错误架构到最终正确形态——OpenClaw 博客生产流水线设计经验

2026-08-01 约 3044 字预计阅读 7 分钟

/images/Code-Art-Studio-images/blog-writer-skill-agent-orchestrator/blog-writer-skill-agent-orchestrator.webp

本文记录了 blog-writer 技能从设计到落地的完整踩坑历程。如果你也在 OpenClaw 中构建自动化工作流，这些教训值得你少踩几个坑。

一、背景：我们想做什么

2026 年 7 月 3 日，kb-writer 与用户围绕 blog-writer 技能进行了一场长时间讨论，目标是优化从「会话内容 → 博客文章」的完整生产流水线。

流程链条是这样的：

用户说"写博客"
    ↓
blog-writer 技能触发
    ↓
内容分析 + 改写
    ↓
写入知识库（Hugo frontmatter）
    ↓
生成封面图 + 文内插图
    ↓
返回结构化结果

看似简单，但在落地过程中，我们经历了多次方向调整——从「升级为正式 agent + orchestrator 调度」到「保持 skill + 直接调用」，每一步都踩了不少坑。

二、坑 #1：Skill ≠ Agent，别乱升级

错误认知： blog-writer 应该升级为正式 agent，由 agents-orchestrator 统一调度。

为什么这个想法听起来很合理？

因为「agent 之间有分工、有协作、有调度」——这听起来很架构，很专业。

正确理解：

概念	定义	类比
Skill	给当前 agent 的操作说明书。当前 agent 触发后，按步骤执行	食谱
Agent	有独立运行环境（workspace、model、tools）的专职代理	厨师
Orchestrator	调度多个 agent 的中转层	餐厅经理

blog-writer 作为 skill 的价值在于：在任何 agent 会话中说出"写博客"，当前 agent 就能触发并执行。不需要中转，不需要注册，即用即走。

判断标准：

≤ 2-3 个 agent，线性流程 → skill 直调，不需要 orchestrator
≥ 4-5 个 agent，有分支逻辑 → orchestrator 才有价值

blog-writer 流程只有 kb-writer + design-yuntianguang 两个角色，线性执行，完全没有 orchestrator 的必要。

📌 核心教训： 不要为了"架构感"而引入中间层。简单流程直接调用，比中转调度更高效、更可靠。

三、坑 #2：create_blog_note.sh 不是可选项，是必选项

问题根源：

OpenClaw 的 create_note.sh 只生成 7 个基础字段（title/date/created/session_key/caller_agent/content_type/tags）。

但 Hugo 博客需要 30+ 个 frontmatter 字段——subtitle、summary、description、keywords、slug、categories、images、resources、featuredImage、toc、code、isCJKLanguage……

错误尝试：

先 create_note.sh 创建基础 frontmatter，再用 Python 脚本替换为完整格式。

结果：工作量大、易出错、每次都得重新生成。

正确做法：

创建专用脚本 create_blog_note.sh，接受一个 frontmatter YAML 文件，原样保留所有 Hugo 字段。

# 第1步：把完整 Hugo frontmatter（不含 --- 分隔线）写入临时 YAML 文件
write /tmp/blog_frontmatter.yaml "
title: \"文章标题\"
subtitle: \"一句话吸引读者\"
summary: \"50-150 字摘要\"
description: \"用于 SEO 的描述\"
keywords: [\"长尾关键词1\", \"长尾关键词2\"]
tags: [\"标签1\", \"标签2\"]
date: YYYY-MM-DD
lastmod: 2026-08-03
slug: \"文章slug\"
categories: [\"Code Art Studio\"]
resources:
  - name: \"featured-image\"
    src: \"{slug}.webp\"
  - name: \"featured-image-preview\"
    src: \"{slug}.webp\"
featuredImage: \"/images/Code-Art-Studio-images/{slug}/{slug}.webp\"
author: \"梦行志\"
toc:
  enable: true
  auto: true
code:
  copy: true
  maxShownLines: 50
"

# 第2步：create_blog_note.sh 生成完整 frontmatter + 标题行
~/.openclaw/skills/obsidian-vault/scripts/create_blog_note.sh \
  "/home/oklife/Obsidian-oklife-ub/AI/OpenClaw/知识库管理/2026-08-01-0958-blog-writer-skill-agent-orchestrator.md" \
  "/tmp/blog_frontmatter.yaml"

# 第3步：update_note.sh append 追加正文
~/.openclaw/skills/obsidian-vault/scripts/update_note.sh append \
  "/home/oklife/Obsidian-oklife-ub/AI/OpenClaw/知识库管理/2026-08-01-0958-blog-writer-skill-agent-orchestrator.md" \
  "$(cat /tmp/note_body.md)"

📌 核心教训： 工具设计要为场景服务。create_note.sh 面向普通笔记，create_blog_note.sh 面向博客——职责分离，互不干扰。

四、坑 #3：回退 ≠ 回到最原始版

错误认知： “回退” = 回到 v1.0 初始状态，把所有修改都撤掉。

实际意图： “回退” = 只去掉最后一次修改（agents-orchestrator 中间层），保留之前实用的优化（双路径支持、token 优化、封面图模板、fallback 机制）。

核心教训： 修改文件前，先确认用户说的"回退"具体指哪个版本、哪个修改。不要自作主张全部撤回。

五、坑 #4：Token 优化的最佳实践

原始问题：

blog-writer 将完整博客正文（4000+ 字）通过 sessions_send 传给 kb-writer，消耗 8000+ token。

优化方案：

传文件路径给 kb-writer，让它自己 read 文件。token 消耗从 8000 降到 500。

限制条件：

模式 A（内容接收模式）：没有文件路径，只能传压缩摘要
模式 B/C（会话/文件模式）：有文件路径，直接传路径

📌 核心教训： 能传路径就别传内容。文件路径是 token 节省的终极武器。

六、坑 #5：封面图不能并行生成

错误认知： 封面图生成和文章写入可以并行执行，节省时间。

实际情况： 封面图的 prompt 需要完整的文章标题 + slug，而 slug 可能在写入过程中发生变化。封面图必须在文章写入完成后才能生成。

这是数据依赖关系，不能并行。

📌 核心教训： 识别任务间的依赖关系。有数据依赖的串行执行，比并行执行更可靠。

七、最终正确架构

经过多轮迭代，blog-writer 流程的最终正确架构如下：

用户说"写博客"
    ↓
当前 agent → 触发 blog-writer skill
    ├── Step 1: 判断内容来源（会话 or 文件）
    ├── Step 2: 准备 Hugo frontmatter YAML
    ├── Step 3: sessions_send → kb-writer（传文件路径 + YAML 路径）
    │              └── kb-writer 自己读文件、改写、写入
    ├── Step 4: sessions_send → design-yuntianguang（传标题 + slug）
    │              └── 封面图 + 文内插图生成（文章写入后）
    └── Step 5: 返回结构化结果

关键特征：

✅ blog-writer skill 直接调用 kb-writer 和 design-yuntianguang
✅ 不需要 orchestrator 中转
✅ kb-writer 通过 create_blog_note.sh 保留完整 Hugo frontmatter
✅ frontmatter YAML 由 blog-writer skill 生成，kb-writer 直接用
✅ 有数据依赖时串行执行（封面图在文章写入后）

graph LR A[用户: 写博客] --> B[blog-writer Skill] B --> C{内容来源?} C -->|会话| D[sessions_history 拉取] C -->|文件| E[read 读取文件] D --> F[准备 Hugo frontmatter YAML] E --> F F --> G[sessions_send → kb-writer] G --> H[kb-writer 改写 + 写入] H --> I[sessions_send → design-yuntianguang] I --> J[封面图 + 插图生成] J --> K[返回结构化结果]

八、本次优化行动清单

创建 create_blog_note.sh，支持完整 Hugo frontmatter
TOOLS.md 中补充 create_blog_note.sh 文档
kb-writer AGENTS.md 中增加 create_blog_note.sh 使用说明
blog-writer SKILL.md 确认无 agents-orchestrator 残留

九、总结

这次 blog-writer 优化经历，本质上是三个核心问题的答案：

Skill 还是 Agent？ → 简单流程用 skill，复杂多 agent 才需要 orchestrator
工具怎么设计？ → 面向场景职责分离，create_note.sh 和 create_blog_note.sh 各司其职
流程怎么优化？ → 传路径不传内容（省 token），串行依赖不并行（保可靠）

如果你也在构建类似的自动化流水线，希望这些经验能帮到你。

关联阅读

[[技能资产全量优化]]

参考来源

–全文完–

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

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

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

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

目录

Blog-writer Skill/Agent/Orchestrator 避坑指南：一次流程优化的血泪史

从错误架构到最终正确形态——OpenClaw 博客生产流水线设计经验

一、背景：我们想做什么

二、坑 #1：Skill ≠ Agent，别乱升级

三、坑 #2：create_blog_note.sh 不是可选项，是必选项

四、坑 #3：回退 ≠ 回到最原始版

五、坑 #4：Token 优化的最佳实践

六、坑 #5：封面图不能并行生成

七、最终正确架构

八、本次优化行动清单

九、总结

关联阅读

参考来源