yrns-roadmap — 学术技术路线图生成器

从文档/文本自动提取研究结构，生成专业级技术路线图。

核心能力

• 智能提取：分析文档结构，自动识别研究阶段、方法、逻辑关系
• 多风格匹配：分析内容特征，建议适配风格（9 类细分风格），用户确认后采用
• 严格一致：同一套路线图保持配色、字体、布局完全统一
• 配色可选：9 套经典配色方案（默认纯黑白 + 8 种 2 色配色，借鉴 WorkBuddy 设计系统），用户按需选择
• 大量标注：每个节点/阶段都有文字，技术术语+中文混合

生成引擎

本 Skill 支持 3 种引擎，按推荐度排序：

引擎选择策略

• 每次生成前必须询问用户选择引擎，不可自动选定
• 用户未指定时推荐 SVG — 技术路线图需要精确文字和严格一致性，SVG 最可靠
• 用户说"要好看一点"/"加点设计感" → 切换到 Seedream
• 用户说"用 Gemini"/"AI 帮我画" → 切换到 Gemini
• 混合模式：先用 SVG 生成结构底图，再用 Seedream 美化

SVG 输出格式

SVG 可直接用于：
- 嵌入 Word/PPT（通过插入图片）
- 浏览器打开查看
- Inkscape/Illustrator 编辑
- 用 rsvg-convert 或 inkscape 转为 PNG/PDF

Phase 0: 首次使用配置 + 引擎确认

⚠️ 重要：每次触发本 Skill 时，必须先确认引擎选择，不可跳过。

首次配置（仅第一次）

检查配置文件 references/user-config.json 是否存在且完整。不存在时引导用户完成配置（SVG 免配置，Gemini 需 API Key），写入配置文件后继续。

每次触发：确认引擎（必做）

即使配置已存在，每次开始生成前必须询问用户本次使用哪个引擎：

> 本次生成使用哪个引擎？
> 1. SVG（推荐）— 矢量无损、中文完美、零成本
> 2. Seedream — 视觉丰富、飞书内置
> 3. Gemini — AI 理解力强、需 API

不可自动选择引擎。用户明确说"用 SVG"/"用即梦"/"用 Gemini"时可直接采用；否则必须问。

工作流程

> 交互铁律（贯穿全流程）：以下 4 个决策点必须询问用户确认后才能继续，不可自动选择：
> 1. 引擎选择 — Phase 0 确认使用 SVG / Seedream / Gemini
> 2. 风格选择 — Phase 2 先分析内容适配性，展示 1~3 种适合的风格 + 建议，用户在"自己说的类型"和"AI 建议的类型"间选择
> 3. 配色选择 — Phase 2.5 展示 9 种配色，用户明确选择
> 4. 输出参数 — Phase 3 确认比例和保存路径（文件格式由引擎决定，不询问）
>
> 用户已在输入中明确指定的（如"用 SVG 生成 A4 竖版的蓝色路线图"）可直接采用，无需重复询问。

Phase 1: 文档分析 → 结构提取

1. 接收输入 — 用户提供文档（飞书文档链接 / 本地文件 / 直接描述）
2. 结构分析 — 识别以下要素：
   - 研究阶段/模块划分（纵向递进）
   - 并行子任务/分支路径
   - 输入输出关系（左中右三栏逻辑线）
   - 关键术语和标注
3. 生成结构大纲 — 以 JSON 格式组织（见 references/json-schema.md）
4. 展示确认 — 将结构大纲展示给用户，等待确认或修改

Phase 2: 内容分析 → 风格建议 → 用户确认

5. 分析内容适配风格 — 基于 Phase 1 提取的结构，分析内容特征，判断适合哪几种风格：

分析后可能发现 1~3 种风格都适合。此时向用户展示分析结果：

> 基于内容分析，你的内容适合以下风格：
> - C2（分支汇合流程） — 内容有主路径 + 2 个分支，符合分支汇合特征 ✅ 最匹配
> - C1（线性递进流程） — 也有线性步骤，可简化呈现
>
> 你说的是"画流程图"，对应 C 系列风格。AI 建议 C2 更贴合内容结构。是否采用？也可以选 C1。

⚠️ 不可因用户说了类型就直接采用。 必须先分析内容，告知适配结果，让用户在"自己说的类型"和"AI 建议的类型"之间做选择。用户坚持原选择时尊重用户决定。

5b. 从参考图库选图（六维匹配） — 读取 assets/builtin/manifest.json，按以下维度逐层筛选：

manifest 每张图有 6 个元数据维度，不可只看 style + tags：

筛选流程：
1. 按风格代号过滤候选集（如 style=C2 → 16 张候选）
2. 按 layout 缩小范围（如内容是三栏式 → 优先 layout 含"三栏"的）
3. 按 connection_style 进一步筛选（如内容需要分组 → 优先含"虚线框"的）
4. 按 tags 匹配领域（如国自然 → 优先 tags 含"国自然"的）
5. 检查 description 字段确认匹配度

多图组合策略：选 2-3 张图，分别参考不同方面：
- 一张参考整体布局（layout 最接近）
- 一张参考节点/连线风格（node_style / connection_style 最接近）
- 一张参考领域特征（tags 最接近）

⚠️ 不可每次都选列表前几张。 C2 有 10 种不同 layout，C1 有 6 种，D1 有 6 种——必须根据内容特征匹配不同的图，不可固定选同一批。

例：
- "国自然三栏式技术路线，含虚线分组框" → style=A + layout 含"三栏" + connection_style 含"虚线框" → 匹配 layout 和 connection_style 都符合的图
- "生物医学实验流程，5 步线性递进 + 并行分支" → style=C2 + layout 含"分支" → 从 16 张 C2 类中匹配 layout 最接近的（不是随便挑前几张）
- "动物实验 4 组对照 + 多时间点检测" → style=C3 + layout 含"分组矩阵" → 从 6 张 C3 类中匹配

6. 生成结构 JSON / 提示词 — 根据确认的引擎生成对应输入：
   - SVG → 生成 JSON 结构定义（见 references/json-schema.md）
   - Seedream → 生成提示词（见 references/style-guide.md）
   - Gemini → 生成提示词（见 references/style-guide.md）

Phase 2.5: 配色方案选择

7. 询问配色（必做，不可跳过） — 向用户展示配色方案选项，等待用户明确选择后继续：

⚠️ 不可静默默认配色。 必须展示上表并询问：
> 请选择配色方案：mono（纯黑白，默认）/ blue / red / green / purple / teal / amber / coral / pink

用户明确说"用蓝色"/"用红色"时可直接采用，但仍需告知已选中。SVG 引擎通过 --palette 参数指定；Seedream/Gemini 引擎在提示词中替换强调色。

Phase 3: 确认输出参数 → 生成交付

8. 询问输出参数（必做） — 生成前确认以下参数：

> 输出参数确认：
> 1. 图片比例：16:9（PPT/演示）/ A4 竖版（申报书）/ 3:4 / 4:3 — 选哪个？
> 2. 保存路径：默认 ~/workspace/roadmap-output/，是否需要自定义？

⚠️ 不可自动决定比例。 用户明确说"用 A4 竖版"时可直接采用；否则必须问。

> 文件格式由引擎决定，不询问、不混合输出：SVG 引擎只输出 SVG 矢量文件（可用 rsvg-convert 或 inkscape 后续转 PNG/PDF），Seedream/Gemini 引擎只输出 PNG/JPEG 图片。选了 SVG 就不生成 PNG，避免浪费。

9. 生成 — 根据确认的参数调用引擎：

SVG 引擎:

python scripts/generate_svg.py --input roadmap.json --output output.svg --style A --ratio 16:9 --palette mono
# 可用 --list-palettes 查看所有配色方案
python scripts/generate_svg.py --list-palettes

Seedream 引擎:

python scripts/generate_seedream.py --input prompts.json --output-dir ./output --style A --ratio 16:9
# 或直接用 aily-generate-image batch
aily-generate-image batch --images '[{"path":"out.jpeg","prompt":"...","aspect_ratio":"16:9"}]'

Gemini 引擎:

python scripts/generate_image.py --prompt "..." --output output.png --ratio 16:9

Phase 4: 迭代优化（可选）

• SVG → 修改 JSON 结构重新生成（秒级）
• Seedream → 修改提示词或用 aily-generate-image variation 编辑
• Gemini → 修改提示词重新生成

风格配置

> 完整风格提示词模板、配色映射、提示词组合规则见 references/style-guide.md。此处仅列要点。

• 基底风格：学术线稿（Academic Line Drawing），纯白底 + 深炭线条（色值随配色方案变化，mono 默认 #2C2C2A）
• 配色：由用户选择（默认 mono 纯黑白，可选 8 种 2 色配色，借鉴 WorkBuddy 设计系统），见 Phase 2.5
• 默认比例：16:9（PPT/演示）；可选 A4 竖版（申报书）
• 文字规则：大量中文标注，技术术语可英文
• 一致性：同批次所有图保持完全统一的视觉语言

提示词结构

完整提示词 = 风格前缀 + 内容描述 + 中文文字指令 + 一致性锚定 + 排除项

• 风格前缀：九种风格 A/B/C1/C2/C3/C4/D1/D2 各有专属描述（详见 references/style-guide.md）
• 中文文字指令：始终追加，要求主要文字为简体中文
• 一致性锚定：批量生成时追加，mono 配色时替换强调色描述为 pure monochrome
• 排除项：始终追加，禁止装饰元素/渐变/阴影/3D

A4 竖版变体

用户需要嵌入申报书时，在风格提示词末尾追加竖版方向指令（详见 references/style-guide.md）。

API 配置

所有 API 配置从 references/user-config.json 读取，绝不硬编码。

SVG 引擎

无需 API，纯 Python 生成。

Seedream 引擎

通过 aily-generate-image batch CLI 调用，飞书内置，无需额外配置。

Gemini 引擎

配置项从 references/user-config.json 的 gemini 字段读取：

> scripts/generate_image.py 启动时读取 references/user-config.json，找不到配置文件或 api_key 为空时，提示用户完成 Phase 0 配置。

通用配置

保存路径规范

输出目录由用户指定，默认：
~/workspace/roadmap-output/MMDD-主题名/
├── 01-总览图.svg      (SVG 引擎) 或 .png (Seedream/Gemini 引擎)
├── 02-阶段1详图.svg
├── 03-阶段2详图.svg
└── ...

提示词优化规则

1. 叙述性描述 > 关键词堆砌 — Gemini 理解完整语句更好
2. 明确指定背景、比例、文字量 — 每次都要写清楚
3. 具体化视觉元素 — "矩形节点内写'文献综述'"比"一个节点"好
4. 同一批次所有图使用相同风格前缀 — 保证一致性
5. 节点文字要具体 — "数据采集（问卷调查 N=200）"比"数据采集"好

参考图风格锚定

本 Skill 的视觉风格基于以下参考图特征锚定：

参考图管理

内置参考图

Skill 预装 73 张参考图的元数据索引（manifest.json 全量索引 + 49 张详细 .md 分析文件），存放在 assets/builtin/ 目录。不包含二进制图片文件，完整索引见 assets/builtin/manifest.json。

风格分布：
| 风格代号 | 名称 | 数量 | 典型场景 |
|---------|------|------|---------|
| A | 三栏/学术蓝图 | 21 张 | 国自然、课题申报 |
| B | 概念逻辑/辐射 | 1 张 | 概念关系、理论框架 |
| C1 | 线性递进流程 | 7 张 | 简单实验流程、工艺步骤 |
| C2 | 分支汇合流程 | 16 张 | 复杂实验设计、多条件研究 |
| C3 | 分组矩阵流程 | 6 张 | 动物实验分组、对照设计 |
| C4 | 多模块并行流程 | 7 张 | 体外+体内、临床+机制 |
| D1 | 系统分层架构 | 6 张 | 工程系统、深度学习架构 |
| D2 | 层次递进框架 | 6 张 | 研究框架、方法论递进 |
| E | 混合/其他 | 3 张 | — |

语言分布：中文 57 张 / 英文 10 张 / 中英混合 6 张

场景标签：生物医学 29 张 / 国自然课题申报 18 张 / 工程论文 11 张 / 通用模板 3 张

选图流程（Phase 2 必做，六维匹配）：
1. 读取 assets/builtin/manifest.json
2. 按风格代号过滤候选集
3. 按 layout + connection_style + node_style + tags + text_density 六维逐层筛选
4. 选 2-3 张分别参考不同方面（布局/节点风格/领域特征），不可固定选同一批
5. 读取匹配参考图的 .md 分析文件（assets/builtin/<filename>.md）提取风格特征，融入提示词；用户提供的参考图通过路径/URL 传入引擎
- 回退策略：若匹配的参考图无 .md 分析文件（73 条中 49 条有 .md），使用 manifest 的 description + layout + connection_style 字段作为风格引导

添加新参考图（含库中快速匹配）

用户提供参考图时，先匹配库中已有风格，命中则推荐用库中的，没命中才入库新记录。

完整流程：

1. 用户提供图片 — 发送图片 / 本地文件 / 图片链接

2. AI 分析图片特征 — 提取六维元数据（与 builtin manifest 同格式）：
   - style：风格代号（A/B/C1/C2/C3/C4/D1/D2/E）
   - layout：布局类型（如"三栏纵向""纵向递进+多分支"）
   - node_style：节点样式（如"矩形""矩形+圆角矩形"）
   - connection_style：连线风格（如"直线箭头""直线箭头+虚线框分组"）
   - text_density：文字密度（低/中/高）
   - tags：场景标签（如["生物医学","动物实验"]）

3. 快速匹配库中已有参考 — 读取 assets/builtin/manifest.json 和 assets/user/manifest.json，按三维核心特征比对：
   - 维度 1：layout 是否相同或相似（如"纵向递进+双分支" ≈ "纵向递进+多分支"）
   - 维度 2：connection_style 是否相同
   - 维度 3：node_style 是否相同
   - 匹配阈值：3 维匹配 = 高度相似 / 2 维 = 部分相似 / ≤1 维 = 无匹配

4. 决策与告知：

5. 入库操作（仅无匹配或用户选择入库时执行）：
   - ⚠️ 禁止存储二进制文件（.jpg/.png/.jpeg/.webp/.gif 等）。只记录元数据，不保存图片本身
   - 在 assets/user/manifest.json 中记录完整元数据（与 builtin 同格式 + 来源标记）：

{
  "references": [
    {
      "filename": "my-reference.jpg",
      "style": "C2",
      "layout": "纵向递进+三分支",
      "color_scheme": "黑白",
      "node_style": "矩形",
      "connection_style": "直线箭头",
      "text_density": "中",
      "language": "中文",
      "tags": ["生物医学", "肿瘤"],
      "description": "肿瘤耐药机制研究三分支流程",
      "source": "user-upload",
      "added_at": "2026-07-05"
    }
  ]
}

6. 触发词关联 — 根据用户描述关联触发场景。用户说"这是一张架构图参考"→ tags 加 "架构图"，以后说"画架构图"时自动引用。

查看已有参考图

用户说"看看我有哪些参考图"或"参考图列表"时，读取 assets/user/manifest.json 并展示：

你的参考图库（共 N 张）：

📋 Style A（课题申报书）— 2 张
  - my-ref-01: 国自然三栏式（layout: 三栏纵向, node_style: 矩形）
  - my-ref-02: 社科研究框架（layout: 三栏纵向, node_style: 矩形+圆角矩形）

📊 Style D1（系统分层架构）— 1 张
  - my-ref-03: 四层架构（layout: 上下分层, connection_style: 直线箭头）

💡 添加新参考图：直接发图片给我就行（仅记录特征，不存储图片文件）

使用参考图

• SVG 引擎 — AI 读取 manifest 元数据理解布局/风格，转化为 JSON 结构（不需要实际图片文件）
• Seedream 引擎 — 用户提供的参考图通过路径/URL 直接传入 aily-generate-image batch；builtin 参考通过 .md 分析文件作为风格引导
• Gemini 引擎 — 用户提供的参考图通过路径/URL 传入 generate_image.py --reference；builtin 参考通过 .md 分析文件作为风格引导

常见用法

参考文件