Ppshu — 用 HTML 画图表达与交互

Overview

ppshu 是一个「画图助手」技能：把任何想表达的东西做成一张自包含的 HTML 图， 存到当前项目目录下的 .ppshu/ 集中文件夹里，按 001-<描述>.html 的序号递增命名， 并用 present_files 把图直接呈现给用户。图可以是静态示意图，也可以是带交互的原型。

核心价值：HTML 图比纯文字更直观、可交互、可反复打开；集中到一个 .ppshu/ 文件夹，既好找、又能整目录一键删除。

何时使用

出现以下意图时触发本技能：

• 「画个流程图 / 架构图 / 状态机 / 时序图」
• 「画个带判断 / 分支 / 回环的流程图（是否…？→ 是 / 否…）」——用 Mermaid 自动布局（见 cookbook 第 7 节 + references/mermaid_flowchart_template.html），禁止手写 SVG 坐标
• 「对比两份文件 / 代码 / 配置，做个 diff 审查报告」，或「代码改动前后 / review 配图展示差异」——用 scripts/diff_report.py 生成（双栏 diff + 差异块导航 + 三栏成果声明 + SHA-256 可验证，见 cookbook 第 8 节）。这类需求常与「先用图讲清现状」配套出现：先画现状图建立上下文，再出 diff 图聚焦增量
• 「用图说明 / 可视化 / 对比 / 演示 ……」
• 「做个表单 / 原型 / 小工具让我能点着玩」
• 任何「把东西画出来给我看」而不是「写一段文字解释」的请求
• 用户提到 ppshu、画册、或要求把某张图存成带序号的文件

集中存储目录（落在当前项目，好找、可整删）

所有 HTML 统一存放到当前项目的 .ppshu/ 子文件夹（默认即当前工作目录下的 .ppshu/）：

<当前项目>/.ppshu/

• 作品就落在你正在做的项目里，打开文件管理器一眼可见，不用去用户级隐藏目录找。
• 所有图集中在一个 .ppshu/ 文件夹内、不乱散到项目根，想清掉时直接删这个文件夹即可，不算污染仓库。
• 可用环境变量 PPSHU_DIR 或 save_html.py 的 --dir 覆盖（例如想指到别处时）。
• 该目录会自动生成 index.html 画廊，列出全部作品，便于回看。

工作流

1. 确认要表达什么。 想清楚这张图的核心信息：对象、关系、流程、或要交互的点。

2. 生成单文件 HTML。 按 references/html_cookbook.md 的质量规范写： 自包含（无外链）、深色主题、清晰可读、有标题、交互有反馈。

3. 保存到集中目录。 用 scripts/save_html.py 写入并自动编号：

   # 从标准输入读取（把写好的 HTML 通过管道传入）
   cat /tmp/diagram.html | python "<skill_dir>/scripts/save_html.py" "股票价格走势图"
   
   # 或从文件读取
   python "<skill_dir>/scripts/save_html.py" "tcp-ip 协议栈" --file /tmp/diagram.html
   

   脚本会：扫描目录得到下一个 001/002/... 序号 → 把描述转 kebab-case 做文件名 → 写入 <NNN>-<描述>.html → 重新生成 index.html 画廊 → 把最终绝对路径打印到 stdout。

4. 呈现给用户。 用 present_files 打开脚本打印出的那个 .html 路径 （HTML 会自动在预览面板渲染）。同时可一并打开 index.html 画廊。

资源

scripts/save_html.py

落盘与编号的确定性工具。每个作品都通过它保存，不要手动写文件到目录， 以保证序号连续、文件名规范、画廊自动更新。

• 参数：第一个位置参数为「一句话描述」；--file <路径> 从文件读 HTML，否则读 stdin； --dir <路径> 覆盖存储目录。
• 输出：保存后的绝对路径（打印到 stdout），直接喂给 present_files。

references/html_cookbook.md

单文件 HTML 画图的质量规范：单文件铁律、深色主题与配色、画图方式选型 （SVG / Canvas / 表单）、交互要点、响应式、以及写完前的自检清单。 生成任意 HTML 图前先参考它。

备注

• 描述尽量用中文或英文短词，脚本会自动处理成合法文件名。
• 已经存过的图会从画廊 index.html 查看，避免重复造轮子。
• 不要为了「好看」引入外部 CDN 库；原生 SVG + Canvas + JS 足以覆盖绝大多数画图需求。唯一例外是带判断/分叉的流程图——此时用 references/mermaid_flowchart_template.html 的 Mermaid 方案，库已随技能打包到 assets/ 并由 save_html.py 自动复制到作品目录，离线可用、不依赖外网。