@olierjs/fugue-cli 0.1.0 → 0.1.3

package/README.md

@@ -13,7 +13,9 @@ fugue-cli guide
 
 后续更新执行同一条安装命令。包内提供 macOS、Linux、Windows 的 x64 和 arm64 二进制。
 
-安装脚本自动将包内 Skill 同步到 `~/.agents/skills`，包括薄入口 `fugue-stack` 和完整的 `plan-with-remote`。无需手动复制目录。替换同名旧 Skill 或清理本工具管理的过时 Skill 前，会先保存备份；其他 Skill 保持原样。备份放在 `~/.local/share/fugue-cli/backups`，位于技能发现目录之外。
+使用 nvm 管理 Node 时，先在当前终端执行 `nvm use 22.19.0` 或选择更高版本，再安装和运行。启动 Agent 的环境也需要能通过 `PATH` 找到 `fugue-cli`。
+
+安装脚本自动将包内 Skill 同步到 `~/.agents/skills`，包括薄入口 `fugue-stack`、远端规划 `plan-with-remote`、原版 `show-me`、原版 `statechart` 和可视化解释适配 `fugue-show-me`。无需手动复制目录。替换同名旧 Skill 或清理本工具管理的过时 Skill 前，会先保存备份；其他 Skill 保持原样。备份放在 `~/.local/share/fugue-cli/backups`，位于技能发现目录之外。
 
 自动同步通过 npm 的 `postinstall` 执行，需要允许安装脚本运行。清理发生在安装或升级时，针对新版已移除的受管理 Skill；`npm uninstall` 没有对应的自动清理钩子。
 
@@ -27,24 +29,74 @@ fugue-cli --help
 fugue-cli --version
 ```
 
+在目标项目中启动支持 Skill 的 Agent，描述要完成的工作，例如：
+
+```text
+$fugue-stack 根据这份已确认需求实现功能，完成后审查差异并验证。
+$fugue-stack 审查当前代码变更，列出有实际影响的问题。
+$fugue-show-me 用最小的结构图解释这次改动。
+$fugue-show-me 检查取消与重试交错时的状态变化，画出可能的缺陷路径。
+```
+
+`fugue-cli guide` 输出工作指南，编码、审查和解释由当前 Agent 按指南执行。若安装后暂时看不到新 Skill，可重新启动 Agent 后再选择入口。
+
 需求理解、规划和需求或方案解释继续由 `plan-with-remote` 及远端规划服务负责。指南提供规划技能的绝对路径；该技能的客户端需要 Git、已配置的规划服务，以及已在服务中登记的目标仓库，配置说明见 [configuration.md](skills/plan-with-remote/references/configuration.md)。
 
 编码、代码审查与验证、面向人的实现解释由当前 Agent 按指南完成。读取指南本身不会发起规划、修改项目或调用模型。远端规划返回的正式文档继续按 Markdown 原文保存，批准版本由规划客户端和服务端管理。
 
+## 上游技能
+
+`show-me` 完整目录原样引入自 [humanlayer/skills](https://github.com/humanlayer/skills/tree/653b6411c1f70c275a18e37673b042ff99f67ceb/plugins/show-me/skills/show-me)，保留原始说明和 Agent 调用配置。来源、固定提交和目录记录在 [upstream-skills.json](upstream-skills.json)，MIT 许可保留在 [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES)。
+
+`statechart` 完整目录原样引入自 [cursor/plugins 的 pstack](https://github.com/cursor/plugins/tree/99b609a72323b70204eab407c622f436e858e112/pstack/skills/statechart)，包括原始说明、脚本和测试。同样在来源记录中固定提交，并保留 MIT 许可。
+
+需要可视化解释时，总览路由到 [fugue-show-me](skills/fugue-show-me/SKILL.md)：由 `show-me` 选择通用表达形式，需要分析状态变化、检查行为规则或展示缺陷路径时配合 `statechart`。适配维护在独立目录中；更新上游时整体替换原版目录并更新来源记录。
+
+`fugue-show-me` 根据这些方法组织全局视图和必要的交互、状态细节，再通过本层的 [Pele 输出脚本](skills/fugue-show-me/scripts/render-html.mjs) 将 Mermaid 统一展示为单文件 HTML。图在正文直接可见，采用 Flexoki 浅色与深色主题，按信息角色分色，支持自适应和缩放。首次生成页面会将 `pele@1.12.0` 安装到独立用户缓存，生成的页面可离线打开；该展示链路不导入或修改上游的内部渲染模块。
+
+## 状态图依赖
+
+`statechart` 使用 Node.js 和 npm；模型检查还需要 [mise](https://mise.jdx.dev/getting-started.html)。macOS 可先安装：
+
+```sh
+brew install mise
+node ~/.agents/skills/statechart/scripts/statechart.mjs --help
+```
+
+首次模型检查由原版脚本通过 mise 安装 Java Temurin 25 和 TLC 1.7.4，需要联网下载约 305 MB。若使用已有环境，可按上游帮助设置 `JAVA` 和 `TLA2TOOLS`。首次 PNG 出图会将 `pele@1.8.0` 和 `@resvg/resvg-js@2.6.2` 安装到用户缓存目录；仅渲染现成 Mermaid 图时不运行 TLC。
+
+该版 TLC 无法解析模型字符串中的中文。模型使用 ASCII 标识符和字符串值，中文标签放在映射文件中，从模型生成中文状态图。
+
+输入和产物放在目标仓库之外的临时目录，按上游要求交付 PNG、Mermaid 源码、缺陷说明和再生成命令。模型检查结果与真实代码复现结果分别说明。
+
 ## 开发与发布
 
 开发与打包需要 Go >=1.23 和 Node >=22.19.0。
 
+验证尚未发布到 npm 的仓库版本时，在仓库根目录打包，再安装生成的本地包：
+
+```sh
+npm pack
+npm install -g ./olierjs-fugue-cli-0.1.3.tgz
+fugue-cli --version
+fugue-cli guide
+```
+
+本地包安装同样会运行 Skill 自动同步。`@latest` 使用 npm 上的已发布版本，本地包使用本次构建的仓库版本。
+
 ```sh
 go test ./...
 node --test tests/*.test.mjs
+node --test skills/statechart/scripts/test/statechart.test.mjs
 npm pack
 ```
 
+上游测试包含 Linux 的 `LD_PRELOAD` 故障注入，并对临时路径和英文 Java 诊断文本作精确断言；macOS 上需单独核对这些环境差异。
+
 `npm pack` 的 `prepack` 自动构建各平台二进制，并将版本写入命令。发布目标固定为 npmjs，包名为 `@olierjs/fugue-cli`。发布验收后的包：
 
 ```sh
-npm publish ./olierjs-fugue-cli-0.1.0.tgz --access public
+npm publish ./olierjs-fugue-cli-0.1.3.tgz --access public
 ```
 
 Go 命令入口位于 [cmd/fugue-cli](cmd/fugue-cli/main.go)，指南源码位于 [guide.md](internal/cli/guide.md)，入口技能位于 [SKILL.md](skills/fugue-stack/SKILL.md)。

package/THIRD_PARTY_NOTICES

@@ -1,4 +1,4 @@
-Third-party dependencies included in the compiled fugue-cli binaries.
+Third-party components distributed with fugue-cli.
 
 
 github.com/spf13/cobra v1.10.2
@@ -414,3 +414,54 @@ github.com/inconshreveable/mousetrap v1.1.0
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
+
+humanlayer/skills: show-me (653b6411c1f70c275a18e37673b042ff99f67ceb)
+https://github.com/humanlayer/skills/tree/653b6411c1f70c275a18e37673b042ff99f67ceb/plugins/show-me/skills/show-me
+
+MIT License
+
+Copyright (c) 2026 HumanLayer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+
+cursor/plugins: pstack statechart (99b609a72323b70204eab407c622f436e858e112)
+https://github.com/cursor/plugins/tree/99b609a72323b70204eab407c622f436e858e112/pstack/skills/statechart
+
+MIT License
+
+Copyright (c) 2026 Lauren Tan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olierjs/fugue-cli",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Fugue 需求交付工作指南与 Agent 技能",
   "type": "module",
   "bin": { "fugue-cli": "bin/fugue-cli.mjs" },
@@ -10,6 +10,7 @@
     "scripts/postinstall.mjs",
     "scripts/skills.mjs",
     "skills/",
+    "upstream-skills.json",
     "THIRD_PARTY_NOTICES"
   ],
   "engines": { "node": ">=22.19.0" },

package/skills/fugue-show-me/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: fugue-show-me
+description: 组合 show-me 与 statechart 的分析视角，用 Pele 将 Mermaid 展示为可读的 HTML 图解；解释实现、代码变更、运行结果、状态变化或缺陷路径时使用。
+---
+
+# 可视化解释
+
+上游 skill 保持独立。本层负责按问题选择分析方法、组织面向人的视图，再用 Pele 统一展示；不修改上游，也不调用它们的内部渲染模块。
+
+## 获取信息与组织视图
+
+先阅读并遵循[上游 show-me](../show-me/SKILL.md)，由它指导表达形式的选择。技能提供分析方法，事实来自当前源码、差异、文档和实际运行结果。
+
+| 问题需要的视角 | 方法与信息 | 适合的图 |
+| --- | --- | --- |
+| 系统全貌、职责边界、数据流 | 按 `show-me` 从材料中提取组件、输入输出与关系 | 流程图、分组结构图 |
+| 谁先做什么、谁调用谁 | 按 `show-me` 跟随真实调用或事件顺序 | 时序图 |
+| 状态、并发、重试、取消、恢复、缺陷路径 | 阅读并遵循[上游 statechart](../statechart/SKILL.md)，获取模型状态、转换、规则、检查结果和复现证据 | 上游生成的状态图与缺陷路径图 |
+
+按问题选用必要的方法；普通结构解释不强制建模。任务中其他已选技能的输出也可作为材料，使用前核对其依据和适用范围。
+
+模型负责组织信息：统一不同材料的对象名称、版本和粒度；区分已确认行为、模型假设与待确认关系。涉及多个组件或分支时先给出边界和主路径的总览，再按问题展开关键交互或状态细节。一张图回答一个问题，避免把全部实现细节堆进总览；说明使用用户的语言，标签优先写读者关心的行为。
+
+图中按职责或状态区分颜色，沿用 [Pele 展示说明](references/pele.md)中的颜色角色；由模型明确标注输入、处理、判断、外部交互、完成、失败和跳过，保留对应文字标签。不要按节点顺序轮流染色，也不让脚本从节点名称猜业务含义。浅色和深色使用同一套颜色含义，原模型的规则结果和缺陷路径标记优先。
+
+使用 `statechart` 时保留上游的建模、模型检查、复现及交付要求。原版 TLC 使用 ASCII 模型标识符和字符串值，中文状态与步骤标签写在映射文件中。将它生成的 `.mmd` 直接交给展示层，保留状态、边、步骤编号和缺陷标记；另画的简洁总览不能替代经检查的模型图，Pele 的渲染成功也不证明行为正确。
+
+## 用 Pele 交付图示
+
+选择 Mermaid 表达并需要 HTML 时，用本层的 [Pele 输出脚本](scripts/render-html.mjs) 渲染。输入可以同时包含模型编写的总览、时序图和 `statechart` 生成的状态图，顺序就是页面阅读顺序。用易懂的文件名作为各图标题。
+
+```bash
+node <本 skill 目录>/scripts/render-html.mjs --title "发布流程说明" --out /绝对路径/说明.html /绝对路径/全局视图.mmd /绝对路径/状态流转.mmd
+```
+
+脚本通过 Pele 的公开 API 生成内嵌 SVG，并将 Pele 的浏览器包一并嵌入 HTML，用它提供自适应、中文字体测量和缩放。采用官方站点的 Flexoki 浅色与深色配色，页面内可切换，`--theme light|dark` 指定初始主题。首次安装固定版本依赖，后续复用本层的独立缓存；页面打开时无需联网或启动服务。集成到已有 HTML、调整主题或定位兼容问题时，阅读 [Pele 展示说明](references/pele.md)。
+
+核心图放在对应说明旁、默认可见，简短说明补充结论、范围与必要证据。源码和模型检查材料可放附录，下载入口仅作补充。在支持 Mermaid 的对话或文档中可直接使用会渲染的 `mermaid` 代码块；表达形式更适合树、伪代码或表格时，继续遵循 `show-me`，无需强制转成图。
+
+## 交付检查
+
+打开最终交付的 HTML 或图片，检查实际图示；不能用“文件已生成”、HTML 源码或下载链接存在代替检查。HTML 检查桌面和窄屏，确认核心图已显示、中文标签及连线可读、大图可查看完整内容；本地静态页面还需确认离线可显示。渲染失败就修复后重新检查，不把下载源码当成完成。无法预览时明确说明未验证的范围。
+
+将上游的 `Bash(open ...)` 对应为当前宿主可用的终端或文件预览工具，按实际操作系统打开 HTML 或图片。交付本地文件时提供绝对路径链接；仅在实际打开成功后说明已打开。

package/skills/fugue-show-me/assets/diagram.css

@@ -0,0 +1,77 @@
+/* Flexoki light/dark palettes from https://pele.run/theming and the official site. */
+:root {
+  color-scheme: light;
+  --bg: #fffcf0; --surface: #f2f0e5; --surface-alt: #e6e4d9;
+  --text: #100f0f; --muted: #6f6e69; --border: #cecdc3; --accent: #205ea6;
+  --page-muted: #575653; --link: #205ea6;
+  --role-input: #24837b; --role-process: #205ea6; --role-decision: #ad8301;
+  --role-external: #5e409d; --role-success: #66800b; --role-failure: #af3029; --role-skipped: #6f6e69;
+  --role-strength: 18%;
+  --pele-series-1: #af3029; --pele-series-2: #bc5215; --pele-series-3: #ad8301; --pele-series-4: #66800b;
+  --pele-series-5: #24837b; --pele-series-6: #205ea6; --pele-series-7: #5e409d; --pele-series-8: #a02f6f;
+}
+html[data-theme="dark"] {
+  color-scheme: dark;
+  --bg: #100f0f; --surface: #1c1b1a; --surface-alt: #282726;
+  --text: #cecdc3; --muted: #878580; --border: #403e3c; --accent: #4385be;
+  --page-muted: #878580; --link: #66a0c8;
+  --role-input: #3aa99f; --role-process: #4385be; --role-decision: #d0a215;
+  --role-external: #8b7ec8; --role-success: #879a39; --role-failure: #d14d41; --role-skipped: #878580;
+  --role-strength: 24%;
+  --pele-series-1: #d14d41; --pele-series-2: #da702c; --pele-series-3: #d0a215; --pele-series-4: #879a39;
+  --pele-series-5: #3aa99f; --pele-series-6: #4385be; --pele-series-7: #8b7ec8; --pele-series-8: #ce5d97;
+}
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--surface); color: var(--text); font: 16px/1.65 var(--font); }
+main { max-width: 1200px; margin: auto; padding: 40px 28px; }
+.page-heading { display: flex; justify-content: space-between; align-items: start; gap: 20px; }
+h1 { font-size: clamp(26px,4vw,38px); line-height: 1.3; margin: 0 0 12px; }
+h2 { font-size: 20px; margin: 0 0 16px; }
+header p { color: var(--page-muted); font-size: 14px; }
+.theme-controls { display: flex; flex-shrink: 0; padding: 3px; gap: 3px; border: 1px solid var(--border); border-radius: 9px; background: var(--bg); }
+.theme-controls button { cursor: pointer; font: inherit; font-size: 13px; min-height: 36px; padding: 5px 14px; border: 0; border-radius: 6px; background: transparent; color: var(--muted); }
+.theme-controls button[aria-pressed="true"] { background: var(--surface-alt); color: var(--text); font-weight: 600; }
+nav { display: flex; flex-wrap: wrap; gap: 10px 20px; margin: 20px 0; }
+a { color: var(--link); text-decoration: underline; text-underline-offset: 4px; overflow-wrap: anywhere; }
+.legend { display: flex; flex-wrap: wrap; gap: 10px 22px; padding: 0; margin: 22px 0 32px; list-style: none; font-size: 13px; color: var(--page-muted); }
+.legend li { display: inline-flex; align-items: center; gap: 8px; }
+.legend i { width: 12px; height: 12px; border-radius: 3px; background: var(--role-color); }
+section { min-width: 0; margin: 24px 0; padding: 24px; background: var(--bg); border: 1px solid var(--border); border-radius: 12px; }
+.diagram {
+  width: 100%; min-width: 0;
+  --pele-bg: var(--bg); --pele-fg: var(--text); --pele-fg-on-light: #100f0f; --pele-fg-on-dark: #fffcf0;
+  --pele-muted: var(--muted); --pele-line: var(--muted); --pele-surface: var(--surface);
+  --pele-surface-alt: var(--surface-alt); --pele-border: var(--border); --pele-accent: var(--accent);
+  --pele-critical: var(--role-failure); --pele-error: var(--role-failure); --pele-font: var(--font);
+}
+.diagram > svg { display: block; max-width: 100%; height: auto; margin-inline: auto; }
+.fugueInput { --role-color: var(--role-input); }
+.fugueProcess { --role-color: var(--role-process); }
+.fugueDecision { --role-color: var(--role-decision); }
+.fugueExternal { --role-color: var(--role-external); }
+.fugueSuccess { --role-color: var(--role-success); }
+.fugueFailure { --role-color: var(--role-failure); }
+.fugueSkipped { --role-color: var(--role-skipped); }
+
+/* Neutral model states follow the theme; rule outcomes keep their source colors. */
+.diagram .pele-state:is(.works,.worksPath) > :is(rect,path,circle,ellipse,polygon) { fill: var(--surface) !important; }
+.diagram .pele-state:is(.works,.worksPath) .pele-label { fill: var(--text) !important; }
+
+/* Roles are explicit Mermaid classes, never guessed from labels or source order. */
+.diagram .pele-node:is(.fugueInput,.fugueProcess,.fugueDecision,.fugueExternal,.fugueSuccess,.fugueFailure,.fugueSkipped):not([class*="wrong" i]):not([class*="fixed" i]):not([class*="mixed" i]):not([class*="after" i]):not([class*="worse" i]) > :is(rect,path,circle,ellipse,polygon) {
+  fill: color-mix(in srgb, var(--role-color) var(--role-strength), var(--bg)) !important;
+  stroke: var(--path-border, var(--role-color)) !important;
+}
+.diagram .pele-node:is(.fugueInput,.fugueProcess,.fugueDecision,.fugueExternal,.fugueSuccess,.fugueFailure,.fugueSkipped):not([class*="wrong" i]):not([class*="fixed" i]):not([class*="mixed" i]):not([class*="after" i]):not([class*="worse" i]) .pele-label { fill: var(--text) !important; }
+
+/* Blue path borders remain blue, with their original width and step numbers. */
+.diagram .pele-state[class*="Path"] { --path-border: var(--role-process); }
+.diagram .pele-state[class*="Path"] > :is(rect,path,circle,ellipse,polygon) { stroke: var(--role-process) !important; }
+a:focus-visible,button:focus-visible,.diagram:focus-visible { outline: 2px solid var(--accent); outline-offset: 4px; }
+noscript { color: var(--page-muted); }
+@media(max-width:640px) {
+  main { padding: 24px 14px; }
+  .page-heading { flex-direction: column; gap: 8px; }
+  section { padding: 16px 10px; }
+  h2 { font-size: 18px; }
+}

package/skills/fugue-show-me/references/pele.md

@@ -0,0 +1,68 @@
+# Pele 展示层
+
+Pele 只负责把 Mermaid 画成 SVG。模型决定要解释什么、采用哪个视角和保留哪些关系；源码、运行结果与上游检查结果提供事实依据。展示层不重新判断这些事实。
+
+## 生成单文件 HTML
+
+```bash
+node <本 skill 目录>/scripts/render-html.mjs \
+  --title "取消与恢复的实现" \
+  --out /绝对路径/说明.html \
+  /绝对路径/全局视图.mmd \
+  /绝对路径/调用顺序.mmd \
+  /绝对路径/状态与缺陷.mmd
+```
+
+仅传入本次解释需要的图，不要求凑齐示例中的三种视角。输入与产物放在目标源码仓库之外，除非用户明确要求保存到仓库。
+
+脚本使用 `pele@1.12.0`，首次通过 npm 安装到用户缓存目录的 `fugue-show-me/pele-1.12.0`，遵循 `XDG_CACHE_HOME`，默认在 `~/.cache` 下。缓存独立于 `statechart`；不读取上游缓存、导入上游私有模块或依赖上游 PNG 渲染实现。
+
+所有输入先调用 `render()` 检查并生成 SVG，成功后才写 HTML；错误会使命令失败，不生成仅剩下载入口的页面。HTML 同时内嵌 SVG、Mermaid 源码和 Pele 的浏览器包。浏览器通过 `mount()` 使用实际字体和容器宽度布局，缩放、拖动、复位及键盘操作复用 Pele 自带能力。
+
+打开后查看每张图，而不是仅检查命令成功。浏览器发生绘图错误时，Pele 会在图旁显示错误；这仍是不完整的交付，需要修复并重新检查。
+
+## 主题与颜色含义
+
+使用 Pele 官方站点的 Flexoki 浅色与深色配色：浅色为暖白 `#fffcf0`，深色为墨黑 `#100f0f`。页面内提供切换按钮；命令加 `--theme dark` 可指定初始深色，默认浅色。颜色通过同一份 CSS 变量切换，不重新布局图，也不改变缩放位置。
+
+| 信息角色 | Mermaid 类名 | 色系 |
+| --- | --- | --- |
+| 输入、上下文与事实 | `fugueInput` | 青色 |
+| 程序处理步骤 | `fugueProcess` | 蓝色 |
+| 判断、确认与等待 | `fugueDecision` | 黄色 |
+| 外部系统交互 | `fugueExternal` | 紫色 |
+| 完成与目标达成 | `fugueSuccess` | 绿色 |
+| 失败与阻断 | `fugueFailure` | 红色 |
+| 跳过与未执行 | `fugueSkipped` | 灰色 |
+
+流程图用标准 Mermaid 类标注，类的主题样式由本层 HTML 提供：
+
+```mermaid
+flowchart LR
+  input[任务事实]:::fugueInput --> check{来源是否完整}:::fugueDecision
+  check -->|完整| run[执行处理]:::fugueProcess
+  check -->|缺失| stop[失败并保留事实]:::fugueFailure
+  run --> done[交付结果]:::fugueSuccess
+```
+
+状态图在展示副本中增加 `class s0 fugueInput` 这样的颜色角色即可，保留原 `class`、状态、边、编号和规则标记。已标记的错误或修复状态保持原有结果配色；缺陷路径继续使用蓝框及原有线宽。不得为了颜色修改模型或把失败状态改成通过。
+
+时序图用标准 `box rgba(...) 分组名` 区分参与方，透明填色能与浅、深背景叠合；分组名写明职责。需要突出某段交互时可使用 `rect rgba(...)`。采用上表的对应色系，不按参与方顺序随机分色。
+
+页面图例只列出图中实际使用的颜色角色。颜色增强信息分组，文字标签继续承载含义。两种主题均需检查实际节点填色、标签和连线，测量文字与其真实背景的对比度。
+
+配色来源：[官方站点 Flexoki 主题定义](https://github.com/obsidianmd/pele/blob/bdbad5df4dea13b9a14a83a92aed62c4769e49f5/website/src/styles/pele-theme.scss)。
+
+## 集成到已有 HTML
+
+可以调整生成页面的布局、说明和 CSS，保留每张图的容器、源码数据与初始化脚本。也可按以下原则自行组装：
+
+- 使用 Pele 的公开 `render()` / `mount()` API；浏览器单文件使用 `pele/global` 导出的包并内嵌它，不依赖 CDN。
+- 把 SVG 放在相应说明旁。多张图各用独立的 `idPrefix`，避免箭头、渐变、标题和描述的 ID 冲突。
+- 图示 CSS 位于 `assets/diagram.css`，生成时内嵌到 HTML。用 `--pele-bg`、`--pele-fg`、`--pele-muted`、`--pele-line`、`--pele-surface`、`--pele-surface-alt`、`--pele-border` 等 CSS 变量匹配宿主页面。源图的 `classDef` 可能表达错误、修复和缺陷路径，不为统一配色覆盖这些语义。
+- 用 `mount()` 读取实际中文字体并随容器宽度重排；需要缩放时使用它的 `zoom` 选项，不自行实现图布局或缩放系统。仍然过密的图应先拆分视角，而不是继续缩小文字。
+- 内嵌源码、标题和说明时正确转义 HTML 与脚本结束标签。图中禁用外部图片以保持离线显示，保留 Pele 的许可文本。
+
+Pele 使用自己的布局与主题；Mermaid 的 `themeVariables` 不生效，任意 HTML 标签也不受支持。遇到不支持的语法，按原含义调整或拆图后重新验证；状态与缺陷路径的含义必须保持，不静默改用另一套渲染器。
+
+官方依据：[API](https://pele.run/api)、[主题](https://pele.run/theming)、[兼容性](https://pele.run/compatibility)、[安全与嵌入](https://pele.run/security)。

package/skills/fugue-show-me/scripts/render-html.mjs

@@ -0,0 +1,116 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+
+const version = '1.12.0';
+const fontFamily = "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'PingFang SC', 'Microsoft YaHei', sans-serif";
+const html = text => text.replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char]);
+const json = value => JSON.stringify(value).replace(/</g, '\\u003c');
+const roles = [
+  ['fugueInput', '输入事实'], ['fugueProcess', '处理步骤'], ['fugueDecision', '判断与等待'],
+  ['fugueExternal', '外部交互'], ['fugueSuccess', '完成'], ['fugueFailure', '失败与阻断'], ['fugueSkipped', '跳过'],
+];
+
+async function loadPele() {
+  const cache = join(process.env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'fugue-show-me', `pele-${version}`);
+  if (!existsSync(join(cache, 'node_modules', 'pele', 'package.json'))) {
+    await mkdir(dirname(cache), { recursive: true });
+    const staging = await mkdtemp(`${cache}-`);
+    try {
+      await writeFile(join(staging, 'package.json'), '{"private":true}\n');
+      console.error(`首次安装 pele@${version}，缓存位置：${cache}`);
+      const result = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--ignore-scripts', '--save-exact', `pele@${version}`], {
+        cwd: staging,
+        encoding: 'utf8',
+        env: { ...process.env, PATH: `${dirname(process.execPath)}${process.platform === 'win32' ? ';' : ':'}${process.env.PATH || ''}` },
+        shell: process.platform === 'win32',
+      });
+      if (result.status !== 0) throw new Error(result.error?.message || result.stderr || 'Pele 安装失败');
+      try { await rename(staging, cache); }
+      catch (error) { if (!existsSync(join(cache, 'node_modules', 'pele', 'package.json'))) throw error; }
+    } finally {
+      await rm(staging, { recursive: true, force: true });
+    }
+  }
+  const require = createRequire(join(cache, 'package.json'));
+  const { render } = await import(pathToFileURL(require.resolve('pele')).href);
+  const bundle = await readFile(require.resolve('pele/global'), 'utf8');
+  const license = await readFile(join(dirname(require.resolve('pele/package.json')), 'LICENSE'), 'utf8');
+  return { render, bundle, license };
+}
+
+async function main() {
+  const { values, positionals } = parseArgs({ options: {
+    out: { type: 'string', short: 'o' }, title: { type: 'string' }, theme: { type: 'string', default: 'light' }, help: { type: 'boolean', short: 'h' },
+  }, allowPositionals: true });
+  const usage = '用法：node render-html.mjs --out 说明.html [--title 标题] [--theme light|dark] 总览.mmd [细节.mmd ...]';
+  if (values.help) { console.log(usage); return; }
+  if (!values.out || !positionals.length) throw new Error(usage);
+  if (!['light', 'dark'].includes(values.theme)) throw new Error('主题必须是 light 或 dark');
+  const sources = await Promise.all(positionals.map(async file => ({
+    title: basename(file, extname(file)), source: await readFile(file, 'utf8'),
+  })));
+  const { render, bundle, license } = await loadPele();
+  const diagrams = sources.map((diagram, index) => {
+    const id = `diagram-${index + 1}`;
+    try {
+      const { svg } = render(diagram.source, { idPrefix: id, fontFamily, images: false });
+      return { ...diagram, id, svg };
+    } catch (error) { throw new Error(`${positionals[index]}：${error.message}`, { cause: error }); }
+  });
+  const title = values.title || '图解说明';
+  const css = await readFile(new URL('../assets/diagram.css', import.meta.url), 'utf8');
+  const nodeClasses = diagrams.flatMap(({ svg }) => [...svg.matchAll(/<g\b[^>]*\bclass="([^"]*)"/g)].map(match => match[1].split(/\s+/)))
+    .filter(classes => classes.includes('pele-node') && !classes.some(name => /wrong|fixed|mixed|after|worse/i.test(name)));
+  const usedRoles = roles.filter(([name]) => nodeClasses.some(classes => classes.includes(name)));
+  const legend = usedRoles.length ? `<ul class="legend" aria-label="颜色含义">${usedRoles.map(([name, label]) => `<li class="${name}"><i aria-hidden="true"></i>${label}</li>`).join('')}</ul>` : '';
+  const sections = diagrams.map(({ title, id, svg }) => `<section aria-labelledby="${id}-heading">
+<h2 id="${id}-heading">${html(title)}</h2>
+<div class="diagram" id="${id}" role="region" aria-label="${html(title)}">${svg}</div>
+</section>`).join('\n');
+  const page = `<!doctype html>
+<html lang="zh-CN" data-theme="${values.theme}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${html(title)}</title><style>
+:root { --font: ${fontFamily}; }
+${css}
+</style></head><body><main>
+<header><div class="page-heading"><h1>${html(title)}</h1><div class="theme-controls" role="group" aria-label="页面主题"><button type="button" data-theme-option="light" aria-pressed="${values.theme === 'light'}">浅色</button><button type="button" data-theme-option="dark" aria-pressed="${values.theme === 'dark'}">深色</button></div></div><p>先看全局，再查看需要的细节。图内可缩放、拖动和复位；聚焦图后也可使用 +、−、0 和方向键。</p></header>
+<nav aria-label="图示目录">${diagrams.map(({ id, title }) => `<a href="#${id}-heading">${html(title)}</a>`).join('')}</nav>
+${legend}
+${sections}
+<noscript>当前展示静态图；启用 JavaScript 后可使用自适应布局和缩放。</noscript>
+</main>
+<script id="diagram-sources" type="application/json">${json(diagrams.map(({ id, source }) => ({ id, source })))}</script>
+<script>/* Pele ${version}\n${license.replace(/\*\//g, '* /')}\n*/\n${bundle.replace(/<\/script/gi, '<\\/script')}</script>
+<script>
+for (const button of document.querySelectorAll('[data-theme-option]')) {
+  button.addEventListener('click', () => {
+    document.documentElement.dataset.theme = button.dataset.themeOption;
+    for (const option of document.querySelectorAll('[data-theme-option]')) {
+      option.setAttribute('aria-pressed', String(option === button));
+    }
+  });
+}
+for (const { id, source } of JSON.parse(document.getElementById('diagram-sources').textContent)) {
+  const container = document.getElementById(id);
+  pele.mount(container, source, {
+    idPrefix: id,
+    images: false,
+    zoom: { always: true, labels: { zoomIn: '放大', zoomOut: '缩小', reset: '显示全图' } },
+    onRender() { container.dataset.rendered = 'true'; delete container.dataset.renderError; },
+    onError(error) { container.dataset.renderError = String(error); },
+  });
+}
+</script></body></html>`;
+  const output = resolve(values.out);
+  await mkdir(dirname(output), { recursive: true });
+  await writeFile(output, page);
+  console.log(`已生成 ${diagrams.length} 张图：${output}`);
+}
+
+main().catch(error => { console.error(error.message); process.exitCode = 1; });

package/skills/show-me/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: show-me
+description: Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.
+disable-model-invocation: true
+---
+
+Help the user understand the current topic of conversation visually. Skip the preamble and keep prose brief. Pick the smallest view that makes the key point clear.
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```tsx
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1)
+  return `use the ${skillName} skill`
+}
+```
+
+- For a visual UI, layout, state comparison, or concept too dense for Mermaid, write one focused HTML file — a diagram, an infographic, or a short slide deck, whichever fits the point. Match the product's colors, type, spacing, and components; use real labels and data; support desktop and mobile. Then open it for the user:
+
+```
+Bash(open path/to/show-me-{description}.html)
+```
+
+### guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.

package/skills/show-me/agents/openai.yaml

@@ -0,0 +1,2 @@
+policy:
+  allow_implicit_invocation: false