# Soia Pkm Transform Article Visual

> 把文章转换为长图、信息图、海报、封面、插画等视觉产物。HTML/CSS 截图为本地默认方案，可选 Open Design 或 Codex 图生成。Triggers：「生成长图」「做成信息图」「转成海报」「生成封面」「做成图片」「export visual」「make infographic」

- Skill: `soia-team/soia-pkm-transform-article-visual` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add soia-team/soia-pkm-transform-article-visual`
- Raw SKILL.md: https://api.skillmd.com/api/skills/soia-team/soia-pkm-transform-article-visual/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: soia-team (https://skillmd.com/u/soia-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/soia-team/soia-pkm-transform-article-visual

---


# soia-pkm-transform-article-visual

把已归档或指定文章转换为视觉产物：长图、信息图、海报、封面或插画。

## 客户可读说明

### 这个技能可以做什么

把 Markdown / vault 文章或 URL 渲染为图片产物：

- **长图**：完整文章内容纵向展开为单张 PNG/JPEG
- **信息图**：核心概念可视化，节点 + 连接 + 标注
- **术语地图 / 路线图**：左侧认知路径 + 右侧视觉隐喻 + 底部结论
- **海报 / 封面**：单张设计稿，强排版重视觉
- **插画 / 封面图**：可选 Codex imagegen 生成配图

| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 生成长图 | HTML/CSS 渲染截图，prompt 落盘可重跑 | 图片路径、像素尺寸、预览 |
| 指定 provider | 走对应 provider 流程 | provider 日志 |
| 执行完成 | 验收文件存在、尺寸合理、中文可读 | 完成回执 |

### 客户如何使用

1. 说明来源（URL / vault 路径 / 本地 Markdown）和目标视觉类型（长图/信息图/海报/封面，可选）。
2. 可选：指定 provider（`local` / `open-design` / `codex-image`）、风格、尺寸。
3. URL 来源先 clip 归档再转换。

### 依赖与安装

```bash
claude plugin marketplace add soia-team/soia-open-skills
```

```bash
claude plugin install soia-pkm-vault@soia
```

只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 `~/.agents/skills`；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：

```bash
npx skills add soia-team/soia-open-pkm-vault-skills -g -a '*' -s soia-pkm-transform-article-visual -y
```

- 本地截图方案：优先使用当前 agent 的浏览器截图能力；命令行 smoke 可注入 Playwright，也可在缺少 Playwright 时使用系统浏览器/PDF-图片工具 fallback。
- Open Design（可选强化依赖）：安装 `soia-dev-open-design-ops` 后才可使用 `provider=open-design`；见 [references/provider-open-design.md](references/provider-open-design.md)
- Codex image / imagegen（可选）：见 [references/prompt-codex-image.md](references/prompt-codex-image.md)

| 路径 | 依赖 | 缺失时行为 |
|---|---|---|
| `local` | 无 | 零依赖可用 |
| `codex-image` | 当前环境的 image generation 能力 | 仅该 provider 停在工具可用性闸门 |
| `open-design` | `soia-dev-open-design-ops`（该路径硬依赖）及其 Open Design 环境 | 停止该 provider，给出安装与环境检查命令；不把它冒充为 Open Design 结果 |

`soia-dev-open-design-ops` 在本技能 frontmatter 中标为 `optional`，因为 `local` 和 `codex-image` 路径不依赖它；一旦用户选择 `provider=open-design`，它就是该次执行的硬依赖。

私有配置放在 `~/.config/soia-skills/soia-pkm-transform-article-visual/config.yml`，可用 `SOIA_PKM_TRANSFORM_ARTICLE_VISUAL_CONFIG_FILE` 覆盖。

**WorkBuddy** 的装载单位是角色化专家而不是插件，`npx skills add -a '*'` 覆盖不到它，需要单独安装，见 [docs/install/workbuddy.md](https://github.com/soia-team/soia-open-skills/blob/main/docs/install/workbuddy.md)。

### 日志与完成回执

```markdown
完成：<一句话>。

日志摘要：
- source: <路径或 URL>
- visual_type: long_image | infographic | poster | cover | illustration
- provider: local | open-design | codex-image
- content_mode: visual_dense
- prompt: <落盘路径>
- output: <图片路径>
- dimensions: <宽x高 px>

验证：
- 文件存在，大小 > 50KB
- 尺寸合理（宽 ≥ 750px，高视类型而定）
- 目视中文可读、无截断、无方块乱码

问题与下一步：
- <无 / provider 降级原因 / 建议>
```

## 边界

- 默认 `visual_dense` 模式：核心概念保留，排版压缩，不逐段重复原文。
- 位图上文字错误（乱码、溢出、重叠）**唯一合法修复是改 prompt 重新生成**，禁止 PIL/Canvas/ImageMagick 描字覆盖。
- prompt 必须落盘到 `outputs/transform/<YYYY>/<stem>/prompts/` 保证可重跑。
- Open Design / Codex-image 是可选 provider。未指定 provider 时可选择本地路径；用户显式选择 `open-design` 而缺少其原子层或环境时，停止该 provider 并说明缺口，不静默降级或声称已使用 Open Design。
- 不做内容总结；但允许信息架构重组（如将段落提炼为节点关系图）。

## 工作流

1. 确认来源 → URL 先 clip。
2. 确定 `visual_type`：`long_image`（默认）/ `infographic` / `concept_map` / `poster` / `cover` / `illustration`。
3. 选 provider：用户指定 > 配置 > 本地 HTML/CSS 截图。
4. 读 [references/prompt-infographic.md](references/prompt-infographic.md) 或 [references/prompt-codex-image.md](references/prompt-codex-image.md)（封面/插画时）生成 prompt，落盘。用户提供参考图时，先提取其版式语法，不直接复制内容。
5. 生成产物到 `outputs/transform/<YYYY>/<stem>/`。
6. 先跑机械质量门，再实际渲染 PNG；最后用 `view_image` 或等价视觉检查确认中文可读、无重叠、无截断。
7. 任何 fallback 必须在 manifest 和回执中写明真实 provider，不得把浏览器工具 fallback 写成 Open Design 或 imagegen。
8. 回执。

详见 [references/prompt-infographic.md](references/prompt-infographic.md)、[references/design-prompts.md](references/design-prompts.md)、[references/quality-gates.md](references/quality-gates.md)、[references/provider-open-design.md](references/provider-open-design.md)。Open Design 的环境、daemon、目录与导出原子操作以 `soia-dev-open-design-ops/SKILL.md` 为单一真源。