编辑文档 - 把 xiaohei Skill 装到 pi 跑了一遍，过程比想象中曲折（附踩坑清单）

标题

工具栏

点击或拖拽上传图片

支持 PNG, JPG, GIF, WebP 格式

内容 (Markdown 格式)

接上一篇 xiaohei 的文章（点我看），我把那个 Skill 装到本地 pi 里跑了一遍，过程比想象中曲折。

## 装到 pi 的过程

pi agent 兼容 Codex Skill 规范（都遵循 Agent Skills 规范），所以理论上能直接装。

```
git clone https://github.com/helloianneo/ian-xiaohei-illustrations.git
mkdir -p ~/.pi/skills
cp -R ian-xiaohei-illustrations/ian-xiaohei-illustrations ~/.pi/skills/
```

装完在 pi 里说 `Use $ian-xiaohei-illustrations` 就能引用。

注：pi 没有内置 image_gen（Codex 有），所以图要自己接 API。我用的是 Agnes Image 2.1 Flash（$0.003/张，便宜），效果稳定。

## 给两篇 Obsidian 文章配图

我拿手里两篇 Obsidian 系列的文章试了：

第一篇：Obsidian 是什么 + 怎么和 OpenCode 接
第二篇：Obsidian 多端同步方案对比

每篇要 3 张图。

### 第一步：先出 shot list

不要直接让 AI 生图，先让它读 Skill 里的 `references/` 文档，按「消化正文 → 提炼认知锚点 → 选结构类型 → 设计小动作 → 列中文标注」这个流程，输出 shot list。

这个步骤很关键。我第一篇直接让它生图，结果生成的图虽然风格对，但隐喻和文章段落对不上。第二篇先做 shot list，AI 理解了文章结构，生成的图才能和正文呼应。

### 第二步：逐张 img2img

这是我踩坑最多的地方。

我第一版按 Skill 的 prompt 模板从零生图，结果 3 张图里的小黑长得完全不一样——AI 每次对小黑「黑色实心、白点眼、细腿」的文字理解都有偏差。第一张是小豆子，第二张变成胖圆球，第三张直接没有眼睛。

解决办法：准备一张参考图，用 img2img 锁定角色形象。

```python
extra_body = {
    "image": ["data:image/png;base64,..."],  # 参考图
    "response_format": "b64_json"
}
```

这样生成的所有图角色高度一致。3 张图的角色识别度从 60% 提升到 95%。

### 第三步：踩坑清单

我整理了实操中遇到的几个坑：

**坑 1：超时太短**

API 文档说 60-360s。我一开始 Python 写了 120s 超时，结果 3 张图全部 timeout。改成 300s，一次过。

**坑 2：Base64 参数位置**

Agnes API 的 Base64 输出要用顶层参数 `return_base64: true`，不是 `extra_body.response_format`。文档说得很清楚，但我猜了两次才猜对。

**坑 3：img2img 的 image 也要放 extra_body**

图生图时 `image` 数组必须放 `extra_body.image`，不要放顶层。这点和文生图不一样。

**坑 4：超时是好事**

我中途怀疑 API 挂了，5 分钟没响应。但实际上 1920×1080 的大图生成就是要 2-3 分钟。耐心等。

## 改 Skill：把小黑换成我的角色

跑通之后，我做了一件事：改 Skill。

原版小黑是「黑色实心小怪物」，我想要的角色是「黑色短发少年、蓝色方框眼镜、立领半拉链卫衣、休闲卷边裤、灿烂笑容」。

Skill 文档都拆成 markdown 了，改起来很直接：

- `references/xiaohei-ip.md`：重写角色定义
- `references/prompt-template.md`：更新 prompt 模板
- `references/style-dna.md`：补充比例原则
- `references/composition-patterns.md`：扩充动作池

改完跑一遍，3 张图的角色立刻换了，而且所有 prompt 模板都自动用新角色——这就是 Skill 化设计的好处，只改一个文件，全链路生效。

我还加了一条新规则：角色姿势要匹配内容主题。讲效率就让角色推东西，讲问题就让角色摸头，讲成果就让角色抱东西。一个图一个核心姿势，不重复站姿。

## 哪些设计值得抄

回头看这个 Skill，最值得抄的设计有 4 个：

### 1. 文档即代码

所有规则都拆成 markdown（`style-dna`、`xiaohei-ip`、`composition-patterns`、`prompt-template`、`qa-checklist`），每个文件职责单一。改一条规则不会破坏其他规则。

### 2. 角色 IP 化

固定一个角色 = 固定视觉识别度。读者看 3 篇文章，3 张配图里有同一个角色在干不同的事——这就是品牌感。

### 3. 量化标准

- 「小黑去掉画面仍成立 = 太装饰」
- 「主体占 40-60%，留白至少 35%」
- 「中文标注最多 5-8 处」
- 「不许左上角写 Workflow/流程图标题」

这些数字让 AI 知道自己什么时候违规。不是模糊的「风格统一」，是可执行的检查项。

### 4. QA checklist 内置

`references/qa-checklist.md` 明确列了「失败信号」和「迭代方法」。AI 生成完自己跑一遍 check，不通过就重生成。这是把工作流产品化的关键。

## 实操后我对 Skill 的判断

**优点**：

- 风格统一性极强，10 张图出来像 10 幅系列画
- 角色 IP 化解决了「每张图都换脸」的问题
- 文档结构清晰，二次改造成本低
- 适合「一人公司」或小团队——一个人也能产出统一风格的内容

**缺点**：

- 中文标注 AI 容易写错字（特别是长词容易缺字），需要人工检查
- 复杂构图（4 个以上模块）容易跑成 PPT 信息图感
- 角色姿势库还不够大，目前动作池偏向「操作机器」，缺少「与人互动」类姿势
- 依赖外部生图 API，没有自托管方案

**适合谁**：

- 写公众号/博客需要稳定配图风格的人
- 知识型内容创作者（方法论、流程、概念解释）
- 用 AI Agent 做内容生产、希望视觉风格资产化的人

**不适合谁**：

- 要商业插画/品牌 KV
- 要可爱卡通/儿童风格
- 要在一张图里塞大量文字
- 需要可编辑矢量源文件

## 我现在的用法

两篇文章配图都生成了，存在 `assets/obsidian-illustrations/` 和 `assets/obsidian-sync-illustrations/` 下。

接下来如果再写文章，我会先把 Skill 跑一遍，shot list 出来后人工改一下（AI 选的隐喻偶尔不贴），然后批量生图。

整个流程跑熟之后，给一篇文章配 3-5 张图，从消化文章到出图大约 15 分钟。其中生图本身只占 5 分钟，剩下 10 分钟是检查和重生成。

这个 Skill 真正解决的不是「AI 生图」，是「稳定地生同一种风格的图」。单张图质量不是关键，关键是你能连续产 50 张图都看起来像一个人画的。

摘要

标签多个标签用逗号分隔

分类