华为云博客发布 Skill 优化历程：一份给 Agent Skill 作者的案例

文档版本：v1.0
更新时间：2026-06-26
Skill 仓库：Operations-Skill / huaweicloud-blog-publishing
适用读者：编写 Cursor Agent Skill、运维自动化 Skill、或任何「让 AI 代操 Web 表单」技能的设计者

1. 背景：这个 Skill 要解决什么

华为云开发者社区博客（bbs.huaweicloud.com/blogs/article）支持 Markdown 编辑器，但发布流程涉及：

• 用户扫码登录（必须有人协助）
• 标题、摘要、正文、免责声明等多个字段
• Markdown 编辑器里存在两个 textbox，粘错位置会导致「统计字数为 0」
• 平台对外链有白名单限制

最初的目标很简单：把一篇 Markdown 文章自动填进表单并点击发表。

Skill 路径：huaweicloud-blog-publishing/SKILL.md
辅助脚本：scripts/prep_markdown.py
浏览器工具：agent-browser --session-name huaweicloud --headed

2. 第一版 Skill 的假设（以及为什么不够）

第一版文档按「人类开发者读文档」的方式写：

• 步骤清晰：打开页面 → 填标题 → 切 Markdown → 粘贴 → 发表
• 示例命令：agent-browser click @e10
• 预处理逻辑写在 PowerShell 一行 python -c "..." 里
• 在线文章：「从 GitCode 下载 Markdown」——但未强调禁止 WebFetch / API / git clone

这些假设在人工执行时大多成立，但在 Agent 自主执行 时大面积失效：

核心教训：Skill 不是教程，是给非确定性执行者的操作契约。必须按 Agent 的「默认捷径」来设计防线。

3. 优化历程时间线

以下按 GitCode 合并记录（MR #15～#22）与跨机实测反馈整理。

阶段一：从 HTML 粘贴改为 Markdown 源码（MR #15～#17）

问题：早期尝试把 Markdown 转 HTML 写入 TinyMCE，格式丢失、表格/代码块异常。

改动：

• 明确走「Markdown 格式编辑」+ 剪贴板粘贴源码
• 支持在线 Markdown URL（不仅限本地文件）
• 登录改为 eval 轮询 检测 READY，禁止等用户说「继续」
• 禁止混用 Cursor 内置 browser_navigate / browser_click

启发：先选定唯一正确路径，在 Skill 开头写清「禁止备选方案」，否则 Agent 会「帮你想」更复杂的弯路。

阶段二：对抗 Agent 常见绕路（MR #18～#19）

问题：

• agent-browser daemon 冲突 → Agent 陷入 taskkill 循环
• 已安装仍 npm install -g → CLI 与 daemon 版本不一致
• GitCode 文章下载：手写 raw URL 漏 /raw/，下到 HTML

改动：

• 步骤 0b：daemon 报错 → 原样再 open 一次，仍失败才 close --all
• 先 agent-browser --version，有输出则跳过 npm 安装
• 文档顶部增加 「禁止绕路」 表格：禁止 WebFetch、API、git clone 文章仓库
• 提供 Resolve-MarkdownDownloadUrl 函数，并列出错误 vs 正确 raw URL 对照

典型错误 URL（Agent 高频手拼）：

❌ https://raw.gitcode.com/owner/repo/main/path/file.md     （缺 /raw/）
❌ https://gitcode.com/owner/repo/raw/main/path/file.md     （错误域名）
✅ https://raw.gitcode.com/owner/repo/raw/main/path/file.md

启发：Agent 失败后会「换策略」；要在 Skill 里提前封死比正确做法看起来「更简单」的错路（API base64、WebFetch、clone 仓库）。

阶段三：粘贴门禁与发布闭环（MR #20）

问题：

• 粘到 iframe 外 textbox，页面有字但「统计字数 0」，发表报「正文不能为空」
• YAML frontmatter、重复 H1 出现在正文
• 相对路径链接触发白名单
• 发表成功后只到 processcomplete，用户拿不到文章永久链接

改动：

• 新增 scripts/prep_markdown.py：去 frontmatter、去重复标题、相对链接转纯文本
• 步骤 4d：粘贴后 wait 5000，eval 检查字数 > 0 才能发表
• 步骤 9：打开「我的博客」，点击标题，返回 https://bbs.huaweicloud.com/blogs/{id}

启发：

1. 关键步骤要有「门禁」（gate），不能假设上一步成功
2. 脚本文件 > 内联代码（此阶段已引入脚本，但文档仍保留内联备选——后面证明这是隐患）
3. Skill 的交付物要可验证——用户要的是文章链接，不是「我点过发表了」

阶段四：「安装 Skill + 发布」一体化（MR #21～#22）

用户典型 Prompt：

安装这个 skill，然后用它发布这篇文章 [URL]

Agent 实际行为：把「安装」理解成 6 轮 WebFetch + GitCode API + base64 解码，任务在「获取内容」处中止，从未打开浏览器。

改动：

• 文档最前增加 「安装 ≠ WebFetch」 专节
• 安装方式：sparse clone 仅 huaweicloud-blog-publishing，或 一条 raw SKILL点md
• 安装/加载后 同一条流水线 执行步骤 0～9，不得拆成两个任务
• 步骤 0a 格式检查：仅支持 .md，非 md 立即报错终止（不下载、不打开浏览器）

启发：用户一句话里往往包含多个意图；Skill 要把 「安装」定义为 1～2 条命令，并写清「装完立刻继续，禁止停下来探索仓库」。

阶段五：跨 Agent 实测反馈（另一台 Windows 机器）

在不同于编写环境的机器上，另一名 Agent 跑通发布，但总结了 7 类坎坷。其中两项已合入 Skill（分支 docs/huaweicloud-blog-publish-click-and-prep-script）：

跨 Agent 优化的方法论：

1. 让另一台机器、另一个 Agent、另一套 Prompt 跑一遍，而不是作者自测通过即完结
2. 让 Agent 写「坎坷总结」——比作者猜失败模式准确得多
3. 每次只合入 1～2 项高优先级 改动，避免 Skill 膨胀失控

4. 当前 Skill 的结构设计（推荐模板）

经过多轮迭代，有效 Skill 大致呈现以下结构：

┌─────────────────────────────────────────┐
│  ⚡ 收到任务后第一步（禁止绕路）           │  ← Agent 最常读到的部分
├─────────────────────────────────────────┤
│  重要规则 / Agent 执行禁令（表格）         │  ← 封死错路
├─────────────────────────────────────────┤
│  使用前提（登录、工具安装）                │
├─────────────────────────────────────────┤
│  步骤 0～9（线性流水线）                   │  ← 每步可独立验证
│    - 0a 格式检查 → 下载 → 内容校验         │
│    - 4d 粘贴门禁                          │
│    - 7  发表 + 提交验证                    │
│    - 9  返回可交付 URL                     │
├─────────────────────────────────────────┤
│  常见问题（按 Agent 真实踩坑编号）         │
├─────────────────────────────────────────┤
│  实测经验教训 + 完整示例脚本               │
├─────────────────────────────────────────┤
│  关键记忆点（单表速查）                    │
└─────────────────────────────────────────┘

5. 给 Skill 作者的十条建议

5.1 把 Agent 当成「会走捷径的实习生」

不要写「如果需要可以从 API 获取」——Agent 会理解为首选。应写：

禁止 GitCode API；必须 HTTP 下载；失败时只修正 raw URL 重试。

5.2 成功信号必须可机器验证

5.3 脚本文件优先，禁止内联

PowerShell + Python 内联是重灾区。正确模式：

# ✅ 执行文件
python $prepScript

# ❌ 不要写
python -c "import re; ..."

并提供 raw URL 单文件下载 兜底，不依赖 git、不依赖 clone 整个仓库。

5.4 一步一门禁，再进入下一步

粘贴 → 验证字数 → 填摘要 → 勾选声明 → 发表 → 验证 URL → 取文章链接。
任何一步失败都禁止继续，并给出唯一修复路径。

5.5 写「禁止」比写「建议」更有效

Agent 对「建议」「可选」「也可以」会理解成多条等价路径。高失败步骤应用表格：

5.6 平台细节要写「为什么」

例如：「必须粘到 Iframe 内 textbox」——若只写「粘到 @e106」，ref 变化后 Agent 会乱试。写结构特征（与 bold/code 工具栏同级）比写 ref 更稳。

5.7 登录等人机协作步骤要「自动轮询」

禁止：

• 等用户输入「继续」
• 一条 shell 阻塞 5 分钟

应：

• 每次 eval 一次，sleep 3s，循环，最多 5 分钟
• 首次检测到登录页时通知用户一次即可

5.8 输入格式在流水线最前面拦截

.md 格式检查放在下载之前。失败则 零副作用（不打开浏览器、不消耗登录态）。

5.9 交付物对齐用户真实目标

用户要的是：文章链接 https://bbs.huaweicloud.com/blogs/{id}
不是：「已点击发表」「已到 processcomplete 页」。

5.10 用「另一 Agent 实测」作为发布门槛

Skill 合并前：

1. 换一台机器 / 换一个 Agent 模型
2. 只给最小 Prompt：「安装 skill 并发布 [URL]」
3. 收集 Agent 自述的坎坷清单
4. 每次合入 1～2 条针对性防线

6. 仍待优化的方向（诚实清单）

Skill 不是一次写完的，以下是已知但未全部合入的项：

1. 统计字数验证：兼容 7544/100000 与 统计字数7544/100000 两种 DOM 文本
2. URL 转换：用 Python 脚本统一处理 percent-encoding，避免 PowerShell 正则边界问题
3. 外链预处理：prep_markdown.py --strip-external-links 默认可选开启
4. 弹窗清理：发表前 eval 关闭「推广大使」「设置昵称」等遮挡层
5. 无 git 安装：raw SKILL点md 下载与 sparse clone 并列写进「安装」第一节
6. Windows 粘贴：iframe 内 Control+v 不稳定时，base64 分块 eval 注入 .mce-content-body（实测有效，可沉淀为正式步骤）

7. 反模式速查表

8. 最小 Prompt 参考（用于验收 Skill）

交付 Skill 时，用下面 Prompt 在陌生环境验收：

安装这个 skill：
https://gitcode.com/developer-skill/Operations-Skill/tree/main/huaweicloud-blog-publishing

然后用它发布这篇文章：
https://gitcode.com/lming112/madao/blob/main/pilots/multica-readme-best-practice-20260619/实践文章.md

合格标准：

• [ ] 未使用 WebFetch / GitCode API / git clone 文章仓库
• [ ] 打开有头浏览器，自动轮询登录
• [ ] 正文统计字数 > 0 后才发表
• [ ] 返回 https://bbs.huaweicloud.com/blogs/{数字}
• [ ] 全程未要求用户输入「继续」（除扫码登录外）

9. 结语

huaweicloud-blog-publishing 的优化历程说明：Skill 的质量 ≈ 你在多少种 Agent 失败模式上写过明确的防线。

最初它像一份操作手册；现在它是一份面向非确定性执行者的契约——包含禁令表、门禁步骤、脚本文件、验证信号和跨机实测反馈。

若你正在编写类似的 Web 自动化 Skill（发帖、填表、后台录入、工单提交），不必等「完美再发布」。更可行的路径是：

1. 先跑通一条 happy path
2. 让别的 Agent 跑并写坎坷总结
3. 把坎坷变成文档里的禁止项 + 验证项
4. 重复

这比一次性写长文档更有用，也更接近 Skill 作为「可演进资产」的本质。

附录：主要 Git 里程碑

反馈：若你在其他 Agent / 其他 OS 上跑本 Skill 仍有新坎坷，建议让 Agent 按「现象 → 根因 → 建议改动」三段式总结，并提 Issue 或 MR 到 Operations-Skill。