@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/ascii-video/references/troubleshooting.md

@@ -0,0 +1,367 @@
+# 故障排查 参考
+
+> **另见:** composition.md · architecture.md · shaders.md · scenes.md · optimization.md
+
+## Quick Diagnostic
+
+| Symptom | Likely Cause | Fix |
+|---------|-------------|-----|
+| 全黑输出 | tonemap gamma 过高或未渲染任何特效 | 将 gamma 降至 0.5，检查 scene_fn 是否返回非零 canvas |
+| 画面泛白/过亮 | 使用了线性亮度乘数而不是 tonemap | 将 `canvas * N` 替换为 `tonemap(canvas, gamma=0.75)` |
+| ffmpeg 在渲染途中挂起 | stderr=subprocess.PIPE 死锁 | 将 stderr 重定向到文件 |
+| "read-only" 数组错误 | 使用了未带 .copy() 的 broadcast_to 视图 | 在 broadcast_to 之后添加 `.copy()` |
+| PicklingError | SCENES 表中存在 Lambda 或闭包 | 在模块级别定义所有 fx_* 函数 |
+| 输出中随机出现暗洞 | 字体缺少 Unicode glyphs | 在初始化时验证调色板 |
+| 音画不同步 | 帧时间累积 | 使用整数帧计数器，为每一帧重新计算 t |
+| 单色平面输出 | Hue 字段形状不匹配 | 在 hsv2rgb 之前确保 h,s,v 数组的形状均为 |
+| 文字在复杂的背景上难以看清 | 文字与背景之间没有对比度 | 使用 `apply_text_backdrop()` (composition.md) + `reverse_vignette` shader (shaders.md) |
+| 文字乱码/镜像 | 对文字场景应用了 Kaleidoscope 或 mirror shader | **绝对不要对包含可读文字的场景应用 kaleidoscope, mirror_h/v/quad/diag** — 径向折叠会破坏可读性。仅将这些效果应用于背景层或无文字场景 |
+
+在 ASCII 视频开发过程中遇到的常见 bug、陷阱和特定平台问题。
+
+## NumPy Broadcasting
+
+### `broadcast_to().copy()` 陷阱
+
+Hue 字段生成器通常返回经过广播的视图 —— 它们的形状为 `(1, cols)` 或 `(rows, 1)`，numpy 会将其广播为 `(rows, cols)`。这些视图是**只读的**。如果任何下游代码试图原地修改它们（例如 `h %= 1.0`），numpy 会抛出以下错误：
+
+```
+ValueError: output array is read-only
+```
+
+**修复**：在 `broadcast_to()` 之后始终使用 `.copy()`：
+
+```python
+h = np.broadcast_to(h, (g.rows, g.cols)).copy()
+```
+
+这在 `_render_vf()` 中尤为重要，因为 hue 数组会流经 `hsv2rgb()`。
+
+### `+=` 与 `+` 陷阱
+
+当操作数形状不完全匹配时，原地操作符也会导致广播失败：
+
+```python
+# 如果结果是 (rows,1) 而操作数是 (rows, cols)，则会失败
+val += np.sin(g.cc * 0.02 + t * 0.3) * 0.5
+
+# 正常工作 —— 会创建一个新数组
+val = val + np.sin(g.cc * 0.02 + t * 0.3) * 0.5
+```
+
+`vf_plasma()` 函数曾经存在这个 bug。在混合不同形状的数组时，请使用 `+` 而不是 `+=`。
+
+### `hsv2rgb()` 中的形状不匹配
+
+`hsv2rgb(h, s, v)` 要求所有三个数组的形状必须一致。如果 `h` 是 `(1, cols)` 而 `s` 是 `(rows, cols)`，该函数将崩溃或输出错误结果。
+
+**修复**：在调用之前，确保所有输入都已广播并复制为 `(rows, cols)`。
+
+---
+
+## Blend Mode 陷阱
+
+### Overlay 压碎了暗部输入
+
+当 `a < 0.5` 时，`overlay(a, b) = 2*a*b`。两个值为 0.12 的输入相乘会得到 `2 * 0.12 * 0.12 = 0.03`。结果比任何一个输入都要暗。
+
+**影响**：如果两个图层都很暗（ASCII 艺术通常如此），overlay 会产生近乎全黑的输出。
+
+**修复**：对暗部素材使用 `screen`。Screen 总是提亮画面：`1 - (1-a)*(1-b)`。
+
+### Colordodge 除以零
+
+`colordodge(a, b) = a / (1 - b)`。当 `b = 1.0`（纯白像素）时，这会导致除以零。
+
+**修复**：添加 epsilon：`a / (1 - b + 1e-6)`。`BLEND_MODES` 中的实现应该包含这一点。
+
+### Colorburn 除以零
+
+`colorburn(a, b) = 1 - (1-a) / b`。当 `b = 0`（纯黑像素）时，这会导致除以零。
+
+**修复**：添加 epsilon：`1 - (1-a) / (b + 1e-6)`。
+
+### Multiply 总是导致画面变暗
+
+`multiply(a, b) = a * b`。由于两个操作数都在 [0,1] 范围内，结果总是 <= min(a,b)。切勿将 multiply 用作反馈混合模式 —— 画面会在几帧内变为全黑。
+
+**修复**：将 `screen` 用于反馈，或使用带有低透明度的 `add`。
+
+---
+
+## 多进程
+
+### Pickling 约束
+
+`ProcessPoolExecutor` 通过 pickle 序列化函数参数。这限制了你可以传递给 worker 的内容：
+
+| Can Pickle | Cannot Pickle |
+|-----------|---------------|
+| 模块级函数 (`def fx_foo():`) | Lambda 表达式 (`lambda x: x + 1`) |
+| 字典、列表、numpy 数组 | 闭包（在函数内部定义的函数） |
+| 类实例（带有 `__reduce__`） | 实例方法 |
+| 字符串、数字 | 文件句柄、套接字 |
+
+**影响**：SCENES 表中引用的所有场景函数都必须使用 `def` 在模块级别定义。如果你使用了 lambda 或闭包，你会得到：
+
+```
+_pickle.PicklingError: Can't pickle <function <lambda> at 0x...>
+```
+
+**修复**：在模块顶层定义所有场景函数。在 `_render_vf()` 中作为 val_fn/hue_fn 使用的 lambda 是没问题的，因为它们在 worker 进程内部执行 —— 它们不会跨进程边界被 pickle。
+
+### macOS spawn vs Linux fork
+
+在 macOS 上，`multiprocessing` 默认使用 `spawn`（完全序列化）。在 Linux 上，默认为 `fork`（写时复制）。这意味着：
+
+- **macOS**：特性 数组会按 worker 序列化（30 秒视频约为 57KB，但会随持续时间增加）。每个 worker 都会重新导入整个模块。
+- **Linux**：特性 数组通过 COW 共享。worker 继承父进程的内存。
+
+**影响**：在 macOS 上，模块级代码（如 `detect_hardware()`）会在每个 worker 进程中运行。如果它有副作用（例如 subprocess 调用），这些副作用将会执行 N+1 次。
+
+### 单 Worker 状态隔离
+
+每个 worker 都会创建各自的：
+- `Renderer` 实例（带有全新的网格缓存）
+- `FeedbackBuffer`（反馈不会跨越场景边界）
+- 随机种子 (`random.seed(hash(seg_id) + 42)`)
+
+这意味着：
+- 粒子状态不会在场景之间延续（符合预期）
+- 反馈轨迹在场景切换时会重置（符合预期）
+- `np.random` 状态**没有**被 `random.seed()` 初始化 —— 它们使用的是相互独立的 RNG
+
+**确定性噪声的修复方法**：显式使用 `np.random.RandomState(seed)`：
+
+```python
+rng = np.random.RandomState(hash(seg_id) + 42)
+noise = rng.random((rows, cols))
+```
+
+---
+
+## 亮度问题
+
+### Tonemap 后场景仍然偏暗
+
+如果场景经过 tonemap 后依然偏暗，请检查：
+
+1. **Gamma 过高**：对于具有破坏性后处理的场景，应降低 gamma (0.5-0.6)
+2. **Shader 破坏了亮度**：Shader 链中的 Solarize、posterize 或对比度调整会抵消 tonemap 的效果。请将破坏性的 Shader 移至链的前端，或增加 gamma 以进行补偿。
+3. **带有 multiply 的反馈**：Multiply 反馈会使每一帧变暗。请改用 screen 或 add。
+4. **场景中的 overlay 混合**：如果场景函数在暗色图层上使用了 `blend_canvas(..., "overlay", ...)`，请改用 screen。
+
+### 诊断：测试帧亮度
+
+```bash
+python reel.py --test-frame 10.0
+# 输出：平均亮度：44.3，最大值：255
+```
+
+如果平均值 < 20，则该场景需要注意。常见修复方法：
+- 在 SCENES 条目中降低 gamma
+- 将内部混合模式从 overlay/multiply 改为 screen/add
+- 提高值字段的乘数（例如，`vf_plasma(...) * 1.5`）
+- 检查 Shader 链中是否包含激进的 solarize 或 threshold
+
+### v1 亮度模式（已弃用）
+
+旧模式使用线性乘数：
+
+```python
+# 旧模式 —— 不要使用
+canvas = np.clip(canvas.astype(np.float32) * 2.0, 0, 255).astype(np.uint8)
+```
+
+这会失败，因为：
+- 暗场景 (均值 8): `8 * 2.0 = 16` —— 仍然很暗
+- 亮场景 (均值 130): `130 * 2.0 = 255` —— 饱和截断，丢失细节
+
+请改用 `tonemap()`。参见 `composition.md` 中的 § Adaptive Tone Mapping。
+
+---
+
+## ffmpeg 问题
+
+### 管道死锁
+
+这是头号生产级 bug。如果你使用 `stderr=subprocess.PIPE`：
+
+```python
+# 死锁 —— stderr 缓冲区在 64KB 时填满，阻塞 ffmpeg，进而阻塞你的写入操作
+pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE, stderr=subprocess.PIPE)
+```
+
+**修复**：始终将 stderr 重定向到文件：
+
+```python
+stderr_fh = open(err_path, "w")
+pipe = subprocess.Popen(cmd, stdin=subprocess.PIPE,
+                        stdout=subprocess.DEVNULL, stderr=stderr_fh)
+```
+
+### 帧数不匹配
+
+如果写入管道的帧数与 ffmpeg 期望的帧数（基于 `-r` 和持续时间）不匹配，输出可能会出现：
+- 末尾丢帧
+- 持续时间错误
+- 音视频不同步
+
+**修复**：显式计算帧数：`n_frames = int(duration * FPS)`。在没有验证总数匹配的情况下，不要使用 `range(int(start*FPS), int(end*FPS))`。
+
+### Concat 报错 "unsafe file name"
+
+```
+[concat @ ...] Unsafe file name
+```
+
+**修复**：始终使用 `-safe 0`：
+```python
+["ffmpeg", "-f", "concat", "-safe", "0", "-i", concat_path, ...]
+```
+
+---
+
+## 字体问题
+
+### 单元格高度
+
+`textbbox()` 和 `getbbox()` 在某些 macOS Pillow 版本上会返回错误的高度。请使用 `getmetrics()`：
+
+```python
+ascent, descent = font.getmetrics()
+cell_height = ascent + descent  # 正确
+# 不要使用：font.getbbox("M")[3]  # 在某些版本中是错误的
+```
+
+### 缺少 Unicode Glyphs
+
+并非所有字体都能渲染所有 Unicode 字符。如果调色板中的字符不在字体中，该 glyph 将渲染为空白或豆腐块，在输出中显示为黑洞。
+
+**修复**：在初始化时进行验证：
+
+```python
+all_chars = set()
+for pal in [PAL_DEFAULT, PAL_DENSE, PAL_RUNE, ...]:
+    all_chars.update(pal)
+
+valid_chars = set()
+for c in all_chars:
+    if c == " ":
+        valid_chars.add(c)
+        continue
+    img = Image.new("L", (20, 20), 0)
+    ImageDraw.Draw(img).text((0, 0), c, fill=255, font=font)
+    if np.array(img).max() > 0:
+        valid_chars.add(c)
+    else:
+        log(f"WARNING: '{c}' (U+{ord(c):04X}) missing from font")
+```
+
+### 平台字体路径
+
+| Platform | Common Paths |
+|----------|-------------|
+| macOS | `/System/Library/Fonts/Menlo.ttc`, `/System/Library/Fonts/Monaco.ttf` |
+| Linux | `/usr/share/fonts/truetype/dejavu/DejaVuSansMono.ttf` |
+| Windows | `C:\Windows\Fonts\consola.ttf` (Consolas) |
+
+始终探测多个路径并平滑回退。参见 `architecture.md` 中的 § Font Selection。
+
+---
+
+## 性能
+
+### 缓慢的 Shader
+
+某些 Shader 使用 Python 循环，在 1080p 分辨率下非常慢：
+
+| Shader | Issue | Fix |
+|--------|-------|-----|
+| `wave_distort` | 每行使用 Python 循环 | 使用向量化的花式索引 |
+| `halftone` | 三重嵌套循环 | 使用块规约进行向量化 |
+| `matrix rain` | 每列每轨迹循环 | 累积索引数组，进行批量赋值 |
+
+### 渲染时间缩放
+
+如果渲染花费的时间远超预期：
+1. 检查网格数量 —— 每个额外的网格在初始化时增加约 100-150ms/帧
+2. 检查粒子数量 —— 上限应设为画质允许的合理极限
+3. 检查 Shader 数量 —— 每个 Shader 增加 2-25ms
+4. 检查特效中是否意外存在 Python 循环（应该只使用 numpy）
+
+---
+
+## 常见错误
+
+### 使用 `r.S` 与 `S` 参数的区别
+
+v2 场景协议将 `S`（状态字典）作为显式参数传递。但 `S` 本身就是 `r.S` —— 它们是同一个对象。两者都可以工作：
+
+```python
+def fx_scene(r, f, t, S):
+    S["counter"] = S.get("counter", 0) + 1   # 通过参数访问（首选）
+    r.S["counter"] = r.S.get("counter", 0) + 1  # 通过 renderer 访问（也可行）
+```
+
+为了清晰起见，请使用 `S` 参数。显式参数能清楚地表明该函数持有持久化状态。
+
+### 忘记处理空的特性 值
+
+如果音频静音，音频特性默认值为 0.0。请使用带有合理默认值的 `.get()`：
+
+```python
+energy = f.get("bass", 0.3)  # 默认值为 0.3，而不是 0
+```
+
+如果默认设为 0，特效在静音期间将变为空白。
+
+### 创建新文件而不是修改现有状态
+
+粒子系统中的一个常见 bug：每帧都创建新数组，而不是更新持久化状态。
+
+```python
+# 错误 —— 粒子每帧重置
+S["px"] = []
+for _ in range(100):
+    S["px"].append(random.random())
+
+# 正确 —— 仅初始化一次，然后每帧更新
+if "px" not in S:
+    S["px"] = []
+# ... 根据节拍发射新粒子
+# ... 更新现有粒子
+```
+
+### 未对值字段进行截断处理
+
+值字段应该在 [0, 1] 之间。如果超出此范围，`val2char()` 将产生索引错误：
+
+```python
+# 错误 —— vf_plasma() * 1.5 可能会超过 1.0
+val = vf_plasma(g, f, t, S) * 1.5
+
+# 正确 —— 缩放后进行截断
+val = np.clip(vf_plasma(g, f, t, S) * 1.5, 0, 1)
+```
+
+`_render_vf()` 辅助函数会自动截断，但如果你在构建自定义场景，请显式进行截断。
+
+## 亮度最佳实践
+
+- 密集的动态背景 —— 绝对不要使用全黑，始终填满网格
+- Vignette 最小值限制在 0.15（而不是 0.12）
+- Bloom 阈值设为 130（而不是 170），这样能让更多像素贡献辉光
+- 对暗部 ASCII 图层使用 `screen` 混合模式（而不是 `overlay`）—— overlay 会对暗部值求平方：`2 * 0.12 * 0.12 = 0.03`
+- FeedbackBuffer 衰减最小值为 0.5 —— 低于此值，反馈消失得太快而无法看清
+- 值字段下限：`vf * 0.8 + 0.05` 确保没有单元格是绝对的零
+- 各场景 gamma 覆盖：默认 0.75，solarize 0.55，posterize 0.50，亮场景 0.85
+- 尽早进行测试帧：在提交完整渲染之前，在关键时间戳处渲染单帧
+
+**完整渲染前的快速检查清单：**
+1. 渲染 3 个测试帧（开头、中间、结尾）
+2. 检查经过 tonemap 后 `canvas.mean() > 8`
+3. 检查确保没有任何场景看起来是完全平坦的纯黑
+4. 验证各片段的差异（每个场景有不同的背景/调色板/颜色）
+5. 确认 Shader 链包含 bloom（阈值为 130）
+6. 确认 vignette 强度 ≤ 0.25

package/extensions/skills/builtin/creative/baoyu-infographic/PORT_NOTES.md

@@ -0,0 +1,43 @@
+# 移植说明 — baoyu-infographic
+
+移植自 [JimLiu/baoyu-skills](https://github.com/JimLiu/baoyu-skills) v1.56.1。
+
+## 与上游的差异
+
+仅修改了 `SKILL.md`。所有 45 个参考文件均为原样副本。
+
+### SKILL.md 适配
+
+| 变更项 | 上游 | Hermes |
+| -------- | ---------- | -------- |
+| Metadata namespace | `openclaw` | `hermes` |
+| 触发方式 | `/baoyu-infographic` slash command | 自然语言技能匹配 |
+| 用户配置 | EXTEND.md 文件（项目/用户/XDG 路径） | 已移除 — 不属于 Hermes 基础设施 |
+| 用户提示 | `AskUserQuestion`（批量） | `clarify` 工具（单次） |
+| 图片生成 | baoyu-imagine (Bun/TypeScript) | `image_generate` 工具 |
+| 平台支持 | Linux/macOS/Windows/WSL/PowerShell | 仅限 Linux/macOS |
+| 文件操作 | Bash 命令 | Hermes 文件工具 (write_file, read_file) |
+
+### 保留的内容
+
+- 所有布局定义（21 个文件）
+- 所有样式定义（21 个文件）
+- 核心参考文件（analysis-framework, base-prompt, structured-content-template）
+- 推荐组合表
+- 关键词快捷方式表
+- 核心原则与工作流结构
+- 作者、版本、主页归属信息
+
+## 与上游同步
+
+拉取上游更新：
+```bash
+# 对比版本
+curl -sL https://raw.githubusercontent.com/JimLiu/baoyu-skills/main/skills/baoyu-infographic/SKILL.md | head -5
+# 查找 version: 行
+
+# 对比参考文件差异
+diff <(curl -sL https://raw.githubusercontent.com/.../references/layouts/bento-grid.md) references/layouts/bento-grid.md
+```
+
+参考文件可以直接覆盖（它们与上游相比未作更改）。由于 `SKILL.md` 包含 Hermes 特有的适配内容，因此必须手动合并。

package/extensions/skills/builtin/creative/baoyu-infographic/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: baoyu-infographic
+description: "Infographics: 21 layouts x 21 styles (信息图, 可视化)."
+version: 1.56.1
+author: 宝玉 (JimLiu)
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [infographic, visual-summary, creative, image-generation]
+    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-infographic
+---
+
+# Infographic 生成器
+
+改编自 [baoyu-infographic](https://github.com/JimLiu/baoyu-skills)，适配 Hermes Agent 的工具生态系统。
+
+包含两个维度：**layout**（信息结构）× **style**（视觉美学）。任意 layout 与任意 style 均可自由组合。
+
+## 何时使用
+
+当用户要求创建 infographic、视觉摘要、信息图表，或使用诸如“信息图”、“可视化”、“高密度信息大图”等术语时，触发此 skill。用户提供内容（文本、文件路径、URL 或主题），并可选择指定 layout、style、aspect ratio（长宽比）或语言。
+
+## 选项
+
+| 选项 | 取值 |
+| -------- | -------- |
+| Layout | 21 个选项（见 Layout 展示），默认：bento-grid |
+| Style | 21 个选项（见 Style 展示），默认：craft-handmade |
+| Aspect | 命名格式：landscape (16:9), portrait (9:16), square (1:1)。自定义：任意 W:H 比例（例如：3:4, 4:3, 2.35:1） |
+| 语言 | en, zh, ja 等 |
+
+## Layout 展示
+
+| Layout | 最适合 |
+| -------- | ---------- |
+| `linear-progression` | 时间线、流程、教程 |
+| `binary-comparison` | A 对比 B、前后对比、优缺点 |
+| `comparison-matrix` | 多因素比较 |
+| `hierarchical-layers` | 金字塔、优先级 |
+| `tree-branching` | 类别、分类法 |
+| `hub-spoke` | 中心概念及相关项目 |
+| `structural-breakdown` | 分解图、剖面图 |
+| `bento-grid` | 多主题、概览（默认） |
+| `iceberg` | 表面与隐藏层面 |
+| `bridge` | 问题-解决方案 |
+| `funnel` | 转化、过滤 |
+| `isometric-map` | 空间关系 |
+| `dashboard` | 指标、KPI |
+| `periodic-table` | 已分类的集合 |
+| `comic-strip` | 叙事、序列 |
+| `story-mountain` | 情节结构、张力弧 |
+| `jigsaw` | 相互关联的部分 |
+| `venn-diagram` | 重叠的概念 |
+| `winding-roadmap` | 旅程、里程碑 |
+| `circular-flow` | 循环、重复流程 |
+| `dense-modules` | 高密度模块、数据丰富的指南 |
+
+完整定义：`references/layouts/<layout>.md`
+
+## Style 展示
+
+| Style | 说明 |
+| ------- | ------------- |
+| `craft-handmade` | 手绘、纸工艺（默认） |
+| `claymation` | 3D 粘土人物、定格动画 |
+| `kawaii` | 日系可爱、粉彩 |
+| `storybook-watercolor` | 柔和水彩画、异想天开 |
+| `chalkboard` | 黑板上的粉笔 |
+| `cyberpunk-neon` | 霓虹光效、未来主义 |
+| `bold-graphic` | 漫画风格、半色调 |
+| `aged-academia` | 复古科学、棕褐色调 |
+| `corporate-memphis` | 扁平矢量、色彩鲜艳 |
+| `technical-schematic` | 蓝图、工程制图 |
+| `origami` | 折纸、几何图形 |
+| `pixel-art` | 复古 8 位 |
+| `ui-wireframe` | 灰度界面模型 |
+| `subway-map` | 交通线路图 |
+| `ikea-manual` | 极简线条艺术 |
+| `knolling` | 整齐排列的平铺 |
+| `lego-brick` | 玩具积木拼装 |
+| `pop-laboratory` | 蓝图网格、坐标标记、实验室精确度 |
+| `morandi-journal` | 手绘涂鸦、温暖莫兰迪色调 |
+| `retro-pop-grid` | 70 年代复古波普艺术、瑞士网格、粗轮廓线 |
+| `hand-drawn-edu` | 马卡龙粉彩、手绘波动、火柴人 |
+
+完整定义：`references/styles/<style>.md`
+
+## 推荐组合
+
+| 内容类型 | Layout + Style |
+| -------------- | ---------------- |
+| 时间线/历史 | `linear-progression` + `craft-handmade` |
+| 分步指南 | `linear-progression` + `ikea-manual` |
+| A 对比 B | `binary-comparison` + `corporate-memphis` |
+| 层级结构 | `hierarchical-layers` + `craft-handmade` |
+| 交集/重叠 | `venn-diagram` + `craft-handmade` |
+| 转化漏斗 | `funnel` + `corporate-memphis` |
+| 循环周期 | `circular-flow` + `craft-handmade` |
+| 技术原理 | `structural-breakdown` + `technical-schematic` |
+| 数据指标 | `dashboard` + `corporate-memphis` |
+| 教育科普 | `bento-grid` + `chalkboard` |
+| 旅程路线 | `winding-roadmap` + `storybook-watercolor` |
+| 分类系统 | `periodic-table` + `bold-graphic` |
+| 产品指南 | `dense-modules` + `morandi-journal` |
+| 技术指南 | `dense-modules` + `pop-laboratory` |
+| 潮流指南 | `dense-modules` + `retro-pop-grid` |
+| 教学图表 | `hub-spoke` + `hand-drawn-edu` |
+| 流程教程 | `linear-progression` + `hand-drawn-edu` |
+
+默认：`bento-grid` + `craft-handmade`
+
+## 关键词快捷方式
+
+当用户输入包含这些关键词时，**自动选择**关联的 layout，并在第 3 步中提供关联的 style 作为首选推荐。对于匹配到的关键词，跳过基于内容的 layout 推断。
+
+如果快捷方式包含 **Prompt 说明**，请将其作为附加的 style 指令附加到生成的 prompt 中（第 5 步）。
+
+| 用户关键词 | Layout | 推荐 Style | 默认 Aspect | Prompt 说明 |
+| -------------- | -------- | -------------------- | ---------------- | -------------- |
+| 高密度信息大图 / high-density-info | `dense-modules` | `morandi-journal`, `pop-laboratory`, `retro-pop-grid` | portrait | — |
+| 信息图 / infographic | `bento-grid` | `craft-handmade` | landscape | 极简主义：干净的画布，充足的留白，无复杂的背景纹理。仅使用简单的卡通元素和图标。 |
+
+## 输出结构
+
+```
+infographic/{topic-slug}/
+├── source-{slug}.{ext}
+├── analysis.md
+├── structured-content.md
+├── prompts/infographic.md
+└── infographic.png
+```
+
+Slug：提取自主题的 2-4 个单词的 kebab-case 格式。冲突时：追加 `-YYYYMMDD-HHMMSS`。
+
+## 核心原则
+
+- 忠实保留源数据 — 不得进行总结或改写（但在包含于输出之前，**必须剔除任何凭据、API key、token 或机密信息**）
+- 在构建内容结构之前确定学习目标
+- 面向视觉交流构建结构（标题、标签、视觉元素）
+
+## 工作流程
+
+### 第 1 步：分析内容
+
+**加载参考文件**：读取此 skill 中的 `references/analysis-framework.md`。
+
+1. 保存源内容（文件路径或粘贴 → 使用 `write_file` 写入 `source.md`）
+   - **备份规则**：如果 `source.md` 已存在，重命名为 `source-backup-YYYYMMDD-HHMMSS.md`
+2. 分析：主题、数据类型、复杂度、语调、受众
+3. 检测源语言和用户语言
+4. 从用户输入中提取设计说明
+5. 将分析结果保存到 `analysis.md`
+   - **备份规则**：如果 `analysis.md` 已存在，重命名为 `analysis-backup-YYYYMMDD-HHMMSS.md`
+
+详细格式请参见 `references/analysis-framework.md`。
+
+### 第 2 步：生成结构化内容 → `structured-content.md`
+
+将内容转换为 infographic 结构：
+1. 标题和学习目标
+2. 包含以下内容的区块：核心概念、内容（原样保留）、视觉元素、文本标签
+3. 数据点（所有统计数据/引语均准确无误地复制）
+4. 来自用户的设计说明
+
+**规则**：仅限 Markdown 格式。不得添加新信息。忠实保留数据。从输出中剔除任何凭据或机密信息。
+
+详细格式请参见 `references/structured-content-template.md`。
+
+### 第 3 步：推荐组合
+
+**3.1 优先检查关键词快捷方式**：如果用户输入匹配 **关键词快捷方式** 表中的关键词，自动选择关联的 layout，并将关联的 style 优先作为首选推荐。跳过基于内容的 layout 推断。
+
+**3.2 否则**，根据以下因素推荐 3-5 个 layout×style 组合：
+- 数据结构 → 匹配的 layout
+- 内容语调 → 匹配的 style
+- 受众期望
+- 用户设计说明
+
+### 第 4 步：确认选项
+
+使用 `clarify` 工具与用户确认选项。由于 `clarify` 每次只处理一个问题，请先询问最重要的问题：
+
+**Q1 — 组合方式**：展示 3 个及以上 layout×style 组合并附带理由。请用户挑选一个。
+
+**Q2 — 长宽比**：询问长宽比偏好（landscape/portrait/square 或自定义 W:H）。
+
+**Q3 — 语言**（仅当源语言 ≠ 用户语言时）：询问文本内容应使用哪种语言。
+
+### 第 5 步：生成 Prompt → `prompts/infographic.md`
+
+**备份规则**：如果 `prompts/infographic.md` 已存在，重命名为 `prompts/infographic-backup-YYYYMMDD-HHMMSS.md`
+
+**加载参考文件**：读取选定的 layout 文件 `references/layouts/<layout>.md` 和 style 文件 `references/styles/<style>.md`。
+
+组合以下内容：
+1. 来自 `references/layouts/<layout>.md` 的 layout 定义
+2. 来自 `references/styles/<style>.md` 的 style 定义
+3. 来自 `references/base-prompt.md` 的基础模板
+4. 来自第 2 步的结构化内容
+5. 所有文本均采用已确认的语言
+
+**长宽比解析**，用于 `{{ASPECT_RATIO}}`：
+- 命名预设 → 比例字符串：landscape→`16:9`，portrait→`9:16`，square→`1:1`
+- 自定义 W:H 比例 → 原样使用（例如：`3:4`, `4:3`, `2.35:1`）
+
+使用 `write_file` 将组装好的 prompt 保存到 `prompts/infographic.md`。
+
+### 第 6 步：生成图像
+
+使用 `image_generate` 工具，并带入第 5 步组装好的 prompt。
+
+- 将长宽比映射到 image_generate 的 format：`16:9` → `landscape`，`9:16` → `portrait`，`1:1` → `square`
+- 对于自定义比例，选择最接近的命名长宽比
+- 失败时，自动重试一次
+- 将生成的图像 URL/路径保存到输出目录
+
+### 第 7 步：输出摘要
+
+报告：主题、layout、style、长宽比、语言、输出路径、创建的文件。
+
+## 参考文件
+
+- `references/analysis-framework.md` — 分析方法论
+- `references/structured-content-template.md` — 内容格式
+- `references/base-prompt.md` — Prompt 模板
+- `references/layouts/<layout>.md` — 21 个 layout 定义
+- `references/styles/<style>.md` — 21 个 style 定义
+
+## 常见陷阱
+
+1. **数据完整性至关重要** — 绝不总结、改写或更改源统计数据。“73% increase” 必须保持为 “73% increase”，不能变成 “significant increase”。
+2. **剔除机密信息** — 在将源内容包含在任何输出文件之前，务必扫描其中的 API key、token 或凭据。
+3. **每个区块传达单一信息** — 每个 infographic 区块应传达一个清晰的概念。区块过载会降低可读性。
+4. **style 一致性** — 参考文件中的 style 定义必须在整张 infographic 中保持一致。不要混合不同的 style。
+5. **image_generate 长宽比** — 该工具仅支持 `landscape`、`portrait` 和 `square`。自定义比例（如 `3:4`）应映射到最接近的选项（在上述情况下为 portrait）。