技能介绍

要解决什么问题

如果你在维护 Halo 博客，最琐碎的工作往往不是写作本身：发布一篇文章要在控制台里逐个点击，批量给十几篇文章打标签得逐条操作，迁移分类结构时还得手动一条条对齐。这些操作本质上都是对 Halo RESTful API 的重复调用，但自己写脚本又容易踩坑——认证 token 散落各处、并发更新时版本冲突、slug 生成规则不统一。

halo 技能把这些重复劳动固化成一组可直接调用的脚本，让你用自然语言驱动博客内容管理，而不必关心 HTTP 请求的构造细节。

技能如何工作

核心入口是 scripts/halo.mjs，它作为统一的 CLI 接口，向下分发到四个业务模块：

scripts/lib/post-actions.mjs — 文章的 list/get/create/update/delete/publish/unpublish
scripts/lib/tag-actions.mjs — 标签的增删改查
scripts/lib/category-actions.mjs — 分类的增删改查
scripts/lib/singlepage-actions.mjs — 单页的增删改查与发布、下线

底层由 scripts/lib/client.mjs 统一封装 HTTP 客户端，同时对接 Halo 的 Extension API 与 Console API；config.mjs 负责环境变量加载，utils.mjs 提供 slugify、时间格式化、链接构造等工具函数。

几个实现细节值得注意：

乐观锁自动重试：更新操作需要 metadata.version，脚本自动获取最新版本，遇到 409 冲突时自动重试。
metadata.name 自动生成：遵循 ≤253 字符、仅小写字母、数字与连字符的规则，自动拼成 {slug}-{timestamp}。
slug 保留中文：Halo 支持 Unicode，中文字符原样保留在 slug 中，特殊字符替换为连字符。

适用边界与注意点

凭据安全是硬约束：HALO_PAT 绝不能出现在对话、文件、代码或日志里；所有 API 调用必须经过 scripts/halo.mjs，响应中的敏感字段会自动清理。
环境变量有优先级：加载顺序为 process env → skill .env → 项目根目录 .env，排查配置问题时按这个顺序检查。
错误码要分别对待：401 是认证失败，403 是无权限，404 是资源不存在，409 是版本冲突（脚本已自动重试）。
搜索 Halo 文档时建议加 site:docs.halo.run，避免被游戏类内容干扰。