Ppshu — 用 HTML 画图表达与交互

Overview

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

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

何时使用

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

「画个流程图 / 架构图 / 状态机 / 时序图」
「用图说明 / 可视化 / 对比 / 演示 ……」
「做个表单 / 原型 / 小工具让我能点着玩」
任何「把东西画出来给我看」而不是「写一段文字解释」的请求
用户提到 ppshu、画册、或要求把某张图存成带序号的文件

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

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

<当前项目>/.ppshu/

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

工作流

确认要表达什么。 想清楚这张图的核心信息：对象、关系、流程、或要交互的点。
生成单文件 HTML。 按 references/html_cookbook.md 的质量规范写：自包含（无外链）、深色主题、清晰可读、有标题、交互有反馈。
保存到集中目录。 用 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。
呈现给用户。 用 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 查看，避免重复造轮子。
不要为了「好看」引入外部库；原生 SVG + Canvas + JS 足以覆盖绝大多数画图需求。

Ppshu Github

安装到 Tokeny（自动）

SKILL.md