ppshu

擅长用单文件 HTML 画图来表达想法、讲解概念、做可交互原型，并与用户互动。当用户需要可视化（流程图/架构图/图表/状态机）、想看而不是读、要交互式 UI 原型，或任何把东西画出来的需求时，应使用本技能。所有 HTML 集中存到用户仓库之外的 ~/.workbuddy/ppshu 目录，按 001-描述 序号统一管理。

Ppshu — 用 HTML 画图表达与交互

Overview

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

核心价值：HTML 图比纯文字更直观、可交互、可反复打开；集中目录让作品不污染任何项目仓库。

何时使用

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

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

集中存储目录（不污染仓库）

所有 HTML 统一存放，默认位置：

text

~/.workbuddy/ppshu/

• 该目录位于用户级 .workbuddy 下，任何项目仓库之外，永远不会污染源码。
• 可用环境变量 PPSHU_DIR 或 save_html.py 的 --dir 覆盖（例如想按项目分文件夹时）。
• 该目录会自动生成 index.html 画廊，列出全部作品，便于回看。

工作流

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

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

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

   bash

   # 从标准输入读取（把写好的 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 查看，避免重复造轮子。
• 不要为了「好看」引入外部库；原生 SVG + Canvas + JS 足以覆盖绝大多数画图需求。