mindmap-ppt-builder

思维导图 PPT 构建器

目标

将用户提供的源文档转换为适用于本仓库的演示文稿 project/source.js。源文档可以是对话中粘贴的文本，也可以是用户提供路径的本地文本或 Markdown 文件。输出为前序遍历的思维导图：节点精简为两行，可选节点图片，以及符合当前浅色 PPT 风格的本地资源。

需要了解项目文件的确切规范或视觉限制时，请阅读 references/project-format.md。

工作区要求

此技能仅在当前工作目录树中运行（当前工作目录本身，或其下的 mindmap-ppt/ 子文件夹）。不要搜索上级目录、同级目录或主目录中的现有检出副本。

• 将 https://github.com/agegr/mindmap-ppt 克隆到当前工作目录下的 ./mindmap-ppt/，然后进入该目录。
• 如果 ./mindmap-ppt/ 已存在，请停止并询问用户如何继续。不要执行 cd ..、find，也不要以其他方式探查文件系统来定位或在其他位置创建检出副本。
• 将应用仓库保留在技能文件夹之外。不要将 index.html、src/ 或 project/ 复制或克隆到 .agents/skills/mindmap-ppt-builder/ 中。
• 技能的常规输出只能修改 project/source.js 和 project/ 下的本地资源文件。
• 除非用户明确要求清理，否则不要删除现有项目资源。
• 除非用户明确要求实现更改，否则不要编辑 src/、index.html 或应用行为。

工作流

1. 获取用户的源文档：
   • 如果对话中提供了粘贴的文本，请使用该文本。
   • 如果用户提供了本地文件路径，只读取明确指定的文档文件并使用其内容。
   • 如果既没有粘贴文本，也没有可读取的本地文件，请先向用户索取文档，再生成 project/source.js。
2. 阅读文档并确定其表达主旨。
   • 默认遵循源文档的语言：中文输入 -> 中文输出；英文输入 -> 英文输出。
   • 对于英文输出，在自然的情况下，两行节点仍应采用眉题/标题结构。
   • 不要擅自更正事实。如果源文档中存在明显矛盾或存疑的说法，请谨慎保留原说法，或向用户说明冲突。
   • 对于很长的文档，首先保留原有章节结构。如果材料范围太广，无法有把握地精简，请先拟定高层级大纲，并在定稿前请用户确认优先级。
3. 构建清晰的逻辑树：
   • 根节点：文档/源文档名称或演示主题
   • 主要分支：通常为 2-4 个部分；若源文档逻辑更适合其他结构，则遵循源文档逻辑
   • 子节点：用于呈现原因、结果、证据、示例、流程步骤、对比或补充内容
   • 层级：仅在嵌套结构更易于理解作者逻辑时添加层级
4. 将每个节点写成一个无序列表项，并可选择添加一行续文：

- 副标题
  主标题

第一行用作简短的类别标签，第二行写主要信息。每行控制在约 30 个中文字符或 8 个英文单词以内。尽量为所有可见节点使用两行标签；只有在标签已经极短且清晰时，才使用单行节点。

5. 谨慎选择图像节点：
   • 节点图像为可选项。
   • 思维导图必然会省略许多源文档细节；请使用图像保留或解释高信息量节点中省略的细节。
   • 对于典型演示文稿，选择 3-8 个高信息量节点；短篇草稿可使用 0-2 张图像。
   • 优先选择概括流程、架构、对比、时间线、指标或概念模型的节点。
6. 使用 GPT Image 2 或可用的图像生成工具，为所选节点生成插图。将其保存在 project/ 或其子目录中。
   • 生成的栅格插图优先使用 PNG，图表或占位图优先使用 SVG，照片类素材优先使用 JPG。
   • 如果无法生成图像，可以省略图像，也可以在 project/ 下使用同一套克制的配色创建简单的 SVG 占位图。使用 16:10 构图，仅在有帮助时添加简短文字，并使用描述性 kebab-case 文件名，例如 project/demo-flow.svg。
7. 在 Markdown 元数据行中引用图像：

  @image process-overview.png

8. 将 project/source.js 替换为：

export const sourceMarkdown = `
- ...
`;

将用户提供的文本写入 JavaScript 模板字符串前，先对反引号和 ${...} 序列进行转义。

9. 运行 npm run check。
10. 可选的视觉验证：运行 npm run dev，并在浏览器检查可用时查看 Vite 输出的 URL（默认地址为 http://127.0.0.1:5173/；如果端口已被占用，地址可能不同）。

思维导图编写规则

• 不要强行将每个内容都套入严格的 root -> level 1 -> level 2 -> level 3 分类体系。这种结构只是一个实用的默认方案，并非规则。
• 让层级体现作者的逻辑结构。如果原因 A 导致结果 B，B 可以作为 A 的子节点；如果 B 进一步导致结果 C，则形成 A -> B -> C 子树。
• 唯一的硬性原则是清晰：读者应当理解每个子节点为何归属于其父节点，以及表达的是什么关系。
• 遵循源文顺序。此应用按先序遍历展示节点：先展示父节点，再展示所有子节点。不要把后文的结论提前放进前面的父节点标签中。
• 不要在子节点中重复根主题。如果根节点已经说明问题或主题，子节点就应推动内容展开。
• 将相近的含义归在同一个父节点下。背景、标准、风险、产品/工具清单、建议和结论各自归入连贯的分支。
• 主节点表达判断；子节点提供证据、理由、示例或补充。如果一个节点用于解释另一个节点，就将其设为子节点，而不是同级节点。
• 每个父节点最多包含 5 个子节点。如果超过，则添加分组节点。
• 仅当源文逐一分析工具/产品时才拆分；若源文只是顺带列出选项，则将其合并。
• 不要逐句拆分。一个节点应表达一个完整的小要点。
• 每个节点应对应源文中约 10-80 个汉字的内容（这是节点覆盖的源文长度，并非其可见标签的长度）。少于 10 个字通常过于零碎；超过 80 个字通常需要拆分。
• 节点文本可以比普通标题稍长，但一个节点不应包含多个彼此独立的想法。
• 父节点标签应起概括和导航作用；子节点标签应展示具体信息。避免父节点标签提前透露后续细节。
• 将图片放在信息量较大的节点上，例如框架、比较、清单、建议或风险模型节点。避免在很小的细节节点上添加图片。

Markdown 和图片示例

使用 @image 作为元数据续行，放在节点可见的两行标签之后。@image 行不会显示为节点文本。

export const sourceMarkdown = `
- 产品发布
  三分钟讲清楚新功能
  @image overview.png
    - 用户痛点
      当前流程成本很高
      @image image-asset-1/pain-points.jpg
    - 解决方案
      自动整理文稿和插图
    - 演示效果
      像 PPT 一样逐步展开
      @image diagrams/demo-flow.svg
`;

默认情况下，图片路径相对于 project/：

• @image overview.png -> ./project/overview.png
• @image image-asset-1/pain-points.jpg -> ./project/image-asset-1/pain-points.jpg
• @image diagrams/demo-flow.svg -> ./project/diagrams/demo-flow.svg

图片提示词模式

为 GPT Image 2 使用以下风格提示词：

Create a clean presentation illustration for a light PPT mind-map node.
Subject: <node main idea>.
Include: <2-4 concrete visual elements from the source text>.
Style: restrained vector-like editorial illustration, warm off-white background, dark teal #183a4a, muted green #eef7f3, orange accent #d8894f, simple geometric shapes, thin shadows, small 8px-radius card-like forms, no photorealism, minimal short text only when useful, no logos, no busy decorations.
Composition: centered, generous whitespace, readable at thumbnail size, aspect ratio 16:10.

如果源文需要真实的图表、示意图或屏幕截图，请创建简单的示意插图，而不要编造精确数字。图片中尽量不使用文字；若文字有助于理解，则仅使用 1-3 个简短标签或关键词，并将详细标签放在节点中。

SVG 占位图模式

如果没有可用的图像生成工具，但插图仍有帮助，则可以使用简单的 SVG 占位图：

• 尺寸：1280x800。
• 风格：暖调米白背景、深青色 #183a4a、柔和绿色 #eef7f3、橙色点缀 #d8894f。
• 内容：根据节点主题设计抽象的流程区块、箭头、卡片或时间线形状。
• 仅在有帮助时使用少量简短文字；不要使用徽标、密集装饰或照片级写实效果。

图片与资源规则

• 仅在节点标题行之后、子节点之前使用 @image。
• 使用 PNG、JPG/JPEG 或 SVG 资源。
• 将图片文件保存在 project/ 或其子文件夹中。
• @image 值尽量简短，并使用相对于 project/ 的路径，例如 @image user-journey.png、@image diagrams/user-journey.png 或 @image image-asset-1/a.jpg。

验证清单

• project/source.js 导出 sourceMarkdown。
• 每个 @image 对应的资源文件都存在。
• npm run check 运行通过。