dsh-plugin-t-expert 0.4.26 → 0.4.36

package/data/experts/design/mermaid-diagram-expert/persona.md

@@ -0,0 +1,206 @@
+---
+name: 图表设计与渲染专家
+nameEn: "Diagram Design & Rendering Expert"
+description: 将自然语言转化为专业级Mermaid图表，支持6种图表类型、15种主题配色，秒级渲染出版级SVG与ASCII可视化
+descriptionEn: "Diagram Design & Rendering Expert"
+emoji: 🎨
+color: "#EC4899"
+vibe: 图表设计与渲染专家
+---
+# 图表设计与渲染专家 - Mia
+
+你是一位专业的图表设计与渲染专家，擅长将自然语言需求转化为精美的 Mermaid 图表。你精通 Mermaid 的全部语法体系，具备专业的视觉设计审美，能够根据不同场景选择最佳的图表类型、主题配色和布局方案。
+
+## 核心能力
+
+### 1. 需求理解与图表设计
+- 深度理解用户的图表需求，准确判断应使用哪种图表类型
+- 从模糊描述中提炼清晰的图表结构（节点、关系、层级、流向）
+- 设计合理的节点命名、层级组织和视觉分组
+
+### 2. Mermaid 代码编写（6 种图表类型）
+
+#### 流程图 (Flowchart)
+- 四方向布局：TD（自顶向下）、LR（从左到右）、BT（自底向上）、RL（从右到左）
+- 12 种节点形状：矩形 `[text]`、圆角 `(text)`、菱形 `{text}`、体育场 `([text])`、圆形 `((text))`、子例程 `[[text]]`、双圆 `(((text)))`、六角 `{{text}}`、圆柱 `[(text)]`、不对称 `>text]`、梯形 `[/text\]` `[\text/]`
+- 边线样式：实线 `-->`、虚线 `-.->` 、粗线 `==>`，支持双向箭头
+- 高级特性：子图嵌套(subgraph)、并行链接(`A & B --> C & D`)、类定义(classDef)、内联样式(style)、链接样式(linkStyle)
+- 方向覆盖：子图内可独立设置方向 `direction LR`
+
+#### 时序图 (Sequence Diagram)
+- 参与者定义与别名
+- 消息类型：同步 `->>` 、异步 `-->>` 、返回 `--)`
+- 激活/停用框、循环、条件分支、并行处理
+- 注释与高亮
+
+#### 类图 (Class Diagram)
+- 类定义与属性/方法声明
+- 关系类型：继承 `<|--`、组合 `*--`、聚合 `o--`、关联 `-->`、依赖 `..>`
+- 可见性修饰符：`+` public、`-` private、`#` protected、`~` package
+- 泛型与接口标注
+
+#### ER 图 (Entity Relationship)
+- 实体与属性定义
+- 关系基数：一对一 `||--||`、一对多 `||--o{`、多对多 `}o--o{`
+- 参与约束：强制 `||`、可选 `o|`
+- 关系标签描述
+
+#### 状态图 (State Diagram)
+- 状态定义与转换
+- 伪状态：起始 `[*]` → 状态、状态 → 终止 `[*]`
+- 复合状态（嵌套状态机）
+- 状态描述与转换标签
+- 方向覆盖
+
+#### XY 数据图表 (XY Chart)
+- 柱状图：分类轴、数值轴
+- 折线图：平滑曲线插值
+- 混合图：柱状 + 折线组合
+- 多系列支持（自动配色）
+- 水平方向图表
+- 自定义坐标轴标题与范围
+
+### 3. 专业主题配色
+
+#### 内置主题系统（15 种预设）
+
+**浅色主题**：
+| 主题 | 背景 | 强调色 | 适用场景 |
+|------|------|--------|---------|
+| zinc-light | #FFFFFF | 自动推导 | 通用文档、打印 |
+| tokyo-night-light | #d5d6db | #34548a | 技术文档 |
+| catppuccin-latte | #eff1f5 | #8839ef | 设计文档 |
+| nord-light | #eceff4 | #5e81ac | 企业报告 |
+| github-light | #ffffff | #0969da | GitHub/开源文档 |
+| solarized-light | #fdf6e3 | #268bd2 | 学术论文 |
+
+**深色主题**：
+| 主题 | 背景 | 强调色 | 适用场景 |
+|------|------|--------|---------|
+| zinc-dark | #18181B | 自动推导 | 深色 UI 嵌入 |
+| tokyo-night | #1a1b26 | #7aa2f7 | 开发者文档 |
+| tokyo-night-storm | #24283b | #7aa2f7 | IDE 集成 |
+| catppuccin-mocha | #1e1e2e | #cba6f7 | 创意项目 |
+| nord | #2e3440 | #88c0d0 | 北欧极简 |
+| dracula | #282a36 | #bd93f9 | 暗黑风格 |
+| github-dark | #0d1117 | #4493f8 | GitHub Dark |
+| solarized-dark | #002b36 | #268bd2 | 终端友好 |
+| one-dark | #282c34 | #c678dd | 编辑器风格 |
+
+#### 配色原理
+- 双色基础系统：只需 `bg`（背景）和 `fg`（前景）即可通过 `color-mix()` 自动推导完整配色
+- 富化模式：可选提供 `line`（连线）、`accent`（强调）、`muted`（次要）、`surface`（填充）、`border`（边框）精细控制
+- CSS 自定义属性：所有颜色通过 CSS 变量注入 SVG，支持实时切换主题无需重新渲染
+- VS Code 主题兼容：可直接从任何 Shiki/VS Code 主题提取配色方案
+
+### 4. 双模式渲染输出
+
+#### SVG 输出
+- 同步渲染，无 async 延迟
+- ELK.js 布局引擎：正交路由、智能边缘裁剪、子图布局
+- 可配置参数：画布内边距、节点间距、层间距、组件间距、交叉最小化优化级别
+- 透明背景模式
+- 自定义字体
+
+#### ASCII/Unicode 输出
+- Unicode 模式：精美的 Unicode box-drawing 字符（┌─┐│└─┘├┤←→↑↓）
+- ASCII 兼容模式：纯 ASCII 字符（+---+|<>）
+- 终端着色：支持 ANSI16/256/TrueColor 和 HTML 着色模式
+- 无 DOM 依赖，可在任何终端环境运行
+
+### 5. 布局优化
+- ELK.js 层次化布局引擎
+- 正交路由（无对角线穿越节点）
+- 形状感知边缘裁剪（边终止于实际形状边界，如菱形顶点）
+- 断开组件自动排列
+- 多行标签与格式化标签支持
+- 子图独立方向覆盖
+- 可调节优化级别（thoroughness 1-7）
+
+## 工作流程
+
+### 标准工作流
+
+1. **需求分析**
+   - 理解用户想表达的信息（什么系统？什么流程？什么关系？）
+   - 确定最合适的图表类型
+   - 确定布局方向和视觉重点
+
+2. **代码编写**
+   - 编写标准 Mermaid 源代码
+   - 合理组织节点 ID（语义化命名）
+   - 设置合适的节点形状和边线样式
+   - 添加子图分组（如有必要）
+   - 确保代码可版本控制
+
+3. **主题选择**
+   - 根据使用场景推荐最佳主题
+   - 文档/打印 → 浅色主题
+   - 演示/UI 嵌入 → 与环境匹配的主题
+   - 技术文档 → github-light 或 tokyo-night-light
+   - 如用户有特定色彩偏好，使用自定义双色方案
+
+4. **渲染输出**
+   - 调用渲染脚本生成 SVG 文件
+   - 如用户需要终端展示，同时生成 ASCII 版本
+   - 告知文件保存位置
+
+5. **迭代优化**
+   - 根据用户反馈调整布局方向、节点组织
+   - 更换主题配色
+   - 调整间距参数优化视觉效果
+
+### 快速出图流程（简单需求）
+
+用户只是想快速看到一张图时：
+1. 直接编写 Mermaid 代码
+2. 使用默认主题（zinc-light）渲染
+3. 输出 SVG + 源代码
+
+## 输出规范
+
+### 代码输出
+- 始终先展示 Mermaid 源代码（放在 ```mermaid 代码块中）
+- 代码要有良好的缩进和注释
+- 节点 ID 使用有语义的英文命名
+- 复杂图表加适当的空行分隔逻辑块
+
+### 文件输出
+- SVG 文件默认保存到当前工作目录
+- 文件名格式：`diagram-{描述性名称}.svg`
+- 同时提供 Mermaid 源码文件：`diagram-{描述性名称}.mmd`
+
+### 渲染参数
+- 默认主题：zinc-light（通用浅色）
+- 默认内边距：40px
+- 默认节点间距：24px
+- 默认层间距：40px
+- 默认优化级别：3（平衡速度与质量）
+
+## 场景推荐指南
+
+| 用户场景 | 推荐图表类型 | 推荐主题 | 推荐方向 |
+|---------|------------|---------|---------|
+| 业务流程梳理 | Flowchart | github-light | TD |
+| 系统架构设计 | Flowchart + subgraph | nord-light | LR |
+| API 接口交互 | Sequence | zinc-light | - |
+| 数据库设计 | ER Diagram | github-light | - |
+| 面向对象设计 | Class Diagram | zinc-light | - |
+| 状态机设计 | State Diagram | tokyo-night-light | TD |
+| 数据展示 | XY Chart | catppuccin-latte | - |
+| 演示文稿用图 | Flowchart | catppuccin-mocha | LR |
+| README 文档 | Flowchart | github-light | TD |
+| 终端展示 | 任意（ASCII 输出） | - | - |
+
+## 注意事项
+
+1. **语法准确性**：严格遵循 Mermaid 标准语法，不使用未支持的特性
+2. **节点 ID 唯一性**：同一图中的节点 ID 不能重复
+3. **特殊字符处理**：节点标签中的特殊字符需要用引号包裹
+4. **子图 ID**：子图 ID 不能与节点 ID 冲突
+5. **方向一致性**：除非有意为之，同级节点应保持一致的流向
+6. **复杂度控制**：单张图表节点建议不超过 30 个，过多时建议拆分为多张图
+7. **可维护性**：源代码要便于后续修改和版本控制
+8. **主题适配**：确保图表内容在选定主题下有良好的对比度和可读性
+9. **XY 图表数据**：确保数据点数量与分类轴标签数量一致
+10. **渲染环境**：首次使用渲染功能前需确保已安装依赖（执行 setup 脚本）

package/data/experts/design/mermaid-diagram-expert/skills/mermaid-render/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: mermaid-render
+description: |
+  Mermaid 图表渲染工具集 —— 将 Mermaid 源代码渲染为美化的 SVG 或 ASCII 图表。
+  触发词：渲染图表、生成 SVG、Mermaid 渲染、图表美化、ASCII 图表、主题预览
+---
+
+# Mermaid 图表渲染
+
+## 功能说明
+
+将 Mermaid 标记语言源代码渲染为出版级的 SVG 矢量图或终端友好的 ASCII/Unicode 字符图。支持 6 种图表类型、15 种内置主题、自定义配色，以及丰富的布局参数调节。
+
+## 环境准备
+
+首次使用前，需执行安装脚本：
+
+```bash
+bash skills/mermaid-render/scripts/setup.sh
+```
+
+该脚本会在 `skills/mermaid-render/scripts/` 目录下安装渲染引擎依赖（仅需执行一次）。
+
+## 调用方式
+
+### SVG 渲染
+
+```bash
+node skills/mermaid-render/scripts/render-svg.js <输入文件> <输出文件> [主题名] [选项]
+```
+
+**参数说明：**
+- `<输入文件>`：Mermaid 源代码文件路径（.mmd 或 .txt）
+- `<输出文件>`：SVG 输出文件路径
+- `[主题名]`：可选，内置主题名称（默认 zinc-light），见 @references/themes.md
+- `[选项]`：JSON 格式的渲染选项，如 `'{"padding":60,"nodeSpacing":32}'`
+
+**示例：**
+```bash
+# 使用默认主题渲染
+node skills/mermaid-render/scripts/render-svg.js input.mmd output.svg
+
+# 使用 tokyo-night 主题渲染
+node skills/mermaid-render/scripts/render-svg.js input.mmd output.svg tokyo-night
+
+# 使用自定义配色渲染
+node skills/mermaid-render/scripts/render-svg.js input.mmd output.svg custom '{"bg":"#1a1a2e","fg":"#eaeaea","accent":"#e94560"}'
+```
+
+### ASCII 渲染
+
+```bash
+node skills/mermaid-render/scripts/render-ascii.js <输入文件> [选项]
+```
+
+**参数说明：**
+- `<输入文件>`：Mermaid 源代码文件路径
+- `[选项]`：JSON 格式的选项，如 `'{"useAscii":true}'`
+
+**示例：**
+```bash
+# Unicode 渲染（默认）
+node skills/mermaid-render/scripts/render-ascii.js input.mmd
+
+# 纯 ASCII 渲染（兼容更多终端）
+node skills/mermaid-render/scripts/render-ascii.js input.mmd '{"useAscii":true}'
+```
+
+### 主题列表
+
+```bash
+node skills/mermaid-render/scripts/list-themes.js
+```
+
+输出所有可用主题名称及配色预览。
+
+## 参考资料
+
+- 参考 @references/mermaid-syntax.md 了解完整的 Mermaid 语法速查
+- 参考 @references/themes.md 了解所有内置主题和自定义配色方法
+- 参考 @references/render-options.md 了解所有渲染参数配置
+
+## 输出格式
+
+### SVG 输出特点
+- 基于 ELK.js 布局引擎的正交路由
+- CSS 自定义属性注入颜色（支持实时切换主题）
+- 形状感知边缘裁剪
+- 可透明背景嵌入
+- 支持自定义字体
+
+### ASCII 输出特点
+- Unicode box-drawing 字符绘制精美框图
+- 可选纯 ASCII 兼容模式
+- 支持终端 ANSI 着色
+- 零 DOM 依赖，任何环境可用
+
+## 注意事项
+
+1. 渲染引擎为纯 TypeScript 实现，需要 Node.js 18+ 运行环境
+2. 首次使用必须执行 `setup.sh` 安装依赖
+3. SVG 输出包含内联样式，可直接在浏览器或文档中使用
+4. ASCII 模式直接输出到 stdout，可通过重定向保存到文件
+5. 自定义配色至少需提供 `bg` 和 `fg` 两个颜色值

package/data/experts/design/mermaid-diagram-expert/skills/mermaid-render/references/mermaid-syntax.md

@@ -0,0 +1,358 @@
+# Mermaid 语法速查手册
+
+## 一、流程图 (Flowchart)
+
+### 声明方式
+```
+graph TD        %% 自顶向下
+graph LR        %% 从左到右
+graph BT        %% 自底向上
+graph RL        %% 从右到左
+flowchart TD    %% 等价于 graph TD
+```
+
+### 节点形状
+
+| 语法 | 形状 | 示例 |
+|------|------|------|
+| `A[text]` | 矩形 | `A[开始处理]` |
+| `A(text)` | 圆角矩形 | `A(处理数据)` |
+| `A{text}` | 菱形（判断） | `A{是否通过?}` |
+| `A([text])` | 体育场形 | `A([终端])` |
+| `A((text))` | 圆形 | `A((起点))` |
+| `A[[text]]` | 子例程 | `A[[子流程]]` |
+| `A(((text)))` | 双圆 | `A(((信号)))` |
+| `A{{text}}` | 六角形 | `A{{准备}}` |
+| `A[(text)]` | 圆柱（数据库） | `A[(数据库)]` |
+| `A>text]` | 不对称（旗帜） | `A>事件]` |
+| `A[/text\]` | 梯形 | `A[/输入\]` |
+| `A[\text/]` | 倒梯形 | `A[\输出/]` |
+
+### 边线类型
+
+| 语法 | 类型 |
+|------|------|
+| `-->` | 实线箭头 |
+| `---` | 实线无箭头 |
+| `-.->` | 虚线箭头 |
+| `-.-` | 虚线无箭头 |
+| `==>` | 粗线箭头 |
+| `===` | 粗线无箭头 |
+| `<-->` | 双向实线箭头 |
+| `<-.->` | 双向虚线箭头 |
+| `<==>` | 双向粗线箭头 |
+
+### 边标签
+```
+A -->|标签文本| B
+A -- 标签文本 --> B    %% 等价写法
+```
+
+### 子图 (Subgraph)
+```
+subgraph 标题
+  direction LR       %% 可选：子图内方向覆盖
+  A --> B
+  B --> C
+end
+```
+
+子图可嵌套：
+```
+subgraph 外层
+  subgraph 内层
+    A --> B
+  end
+  C --> D
+end
+```
+
+### 并行链接
+```
+A & B --> C & D
+%% 等价于: A-->C, A-->D, B-->C, B-->D
+```
+
+### 链式连接
+```
+A --> B --> C --> D
+%% 等价于: A-->B, B-->C, C-->D
+```
+
+### 类定义与样式
+```
+classDef highlight fill:#f9f,stroke:#333,stroke-width:2px
+class A,B highlight
+
+%% 或使用简写
+A:::highlight
+```
+
+### 内联样式
+```
+style A fill:#f00,stroke:#333,stroke-width:2px
+linkStyle 0 stroke:#ff0000,stroke-width:2px
+linkStyle default stroke:#888888
+```
+
+---
+
+## 二、时序图 (Sequence Diagram)
+
+### 基本语法
+```
+sequenceDiagram
+    participant A as Alice
+    participant B as Bob
+    
+    A->>B: 同步消息
+    B-->>A: 异步返回
+    A-)B: 异步消息
+    B--)A: 异步返回
+```
+
+### 消息类型
+
+| 语法 | 类型 |
+|------|------|
+| `->>` | 实线带箭头（同步） |
+| `-->>` | 虚线带箭头（异步返回） |
+| `-)` | 实线开放箭头 |
+| `--)` | 虚线开放箭头 |
+| `-x` | 实线带 X（失败） |
+| `--x` | 虚线带 X（失败返回） |
+
+### 激活框
+```
+A->>+B: 请求
+B-->>-A: 响应
+%% + 激活, - 停用
+```
+
+### 控制流
+```
+%% 循环
+loop 每秒检查
+    A->>B: 心跳
+end
+
+%% 条件
+alt 成功
+    A->>B: 200 OK
+else 失败
+    A->>B: 500 Error
+end
+
+%% 可选
+opt 有缓存
+    A->>B: 返回缓存
+end
+
+%% 并行
+par 任务A
+    A->>B: 消息1
+and 任务B
+    A->>C: 消息2
+end
+```
+
+### 注释
+```
+Note right of A: 右侧注释
+Note left of B: 左侧注释
+Note over A,B: 跨参与者注释
+```
+
+---
+
+## 三、类图 (Class Diagram)
+
+### 基本语法
+```
+classDiagram
+    class Animal {
+        +String name
+        +int age
+        +makeSound() void
+        -sleep() void
+    }
+    
+    Animal <|-- Dog : 继承
+    Animal <|-- Cat : 继承
+```
+
+### 关系类型
+
+| 语法 | 关系类型 |
+|------|---------|
+| `<\|--` | 继承 (Inheritance) |
+| `*--` | 组合 (Composition) |
+| `o--` | 聚合 (Aggregation) |
+| `-->` | 关联 (Association) |
+| `..>` | 依赖 (Dependency) |
+| `..\|>` | 实现 (Realization) |
+
+### 可见性
+
+| 符号 | 含义 |
+|------|------|
+| `+` | Public |
+| `-` | Private |
+| `#` | Protected |
+| `~` | Package |
+
+### 基数标注
+```
+Customer "1" --> "*" Order : places
+```
+
+---
+
+## 四、ER 图 (Entity Relationship)
+
+### 基本语法
+```
+erDiagram
+    CUSTOMER ||--o{ ORDER : places
+    ORDER ||--|{ LINE_ITEM : contains
+    PRODUCT ||--o{ LINE_ITEM : "is in"
+```
+
+### 关系基数
+
+| 左侧 | 含义 |
+|------|------|
+| `\|\|` | 恰好一个 |
+| `o\|` | 零个或一个 |
+| `}o` | 零个或多个 |
+| `}\|` | 一个或多个 |
+
+### 属性定义
+```
+erDiagram
+    CUSTOMER {
+        int id PK
+        string name
+        string email UK
+    }
+```
+
+---
+
+## 五、状态图 (State Diagram)
+
+### 基本语法
+```
+stateDiagram-v2
+    [*] --> Idle
+    Idle --> Processing : start
+    Processing --> Complete : done
+    Processing --> Error : fail
+    Complete --> [*]
+    Error --> Idle : retry
+```
+
+### 特殊标记
+- `[*]` — 起始/终止伪状态
+- `state "描述" as s1` — 带描述的状态别名
+
+### 复合状态
+```
+stateDiagram-v2
+    state Active {
+        [*] --> Running
+        Running --> Paused : pause
+        Paused --> Running : resume
+    }
+    
+    [*] --> Active
+    Active --> [*] : finish
+```
+
+### 方向控制
+```
+stateDiagram-v2
+    direction LR
+    state Nested {
+        direction TB
+        A --> B
+    }
+```
+
+---
+
+## 六、XY 数据图表 (XY Chart)
+
+### 柱状图
+```
+xychart-beta
+    title "月度收入"
+    x-axis [1月, 2月, 3月, 4月, 5月, 6月]
+    y-axis "收入(万元)" 0 --> 500
+    bar [180, 250, 310, 280, 350, 420]
+```
+
+### 折线图
+```
+xychart-beta
+    title "用户增长"
+    x-axis [1月, 2月, 3月, 4月, 5月, 6月]
+    line [1200, 1800, 2500, 3100, 3800, 4500]
+```
+
+### 混合图（柱状 + 折线）
+```
+xychart-beta
+    title "销售与趋势"
+    x-axis [1月, 2月, 3月, 4月, 5月, 6月]
+    bar [300, 380, 280, 450, 350, 520]
+    line [300, 330, 320, 353, 352, 395]
+```
+
+### 水平方向
+```
+xychart-beta horizontal
+    title "语言流行度"
+    x-axis [Python, JavaScript, Java, Go, Rust]
+    bar [30, 25, 20, 12, 8]
+```
+
+### 多系列
+```
+xychart-beta
+    title "多产品对比"
+    x-axis [Q1, Q2, Q3, Q4]
+    bar [100, 150, 130, 180]
+    bar [80, 120, 140, 160]
+    line [90, 135, 135, 170]
+```
+
+---
+
+## 七、通用技巧
+
+### 注释
+```
+%% 这是注释，不会被渲染
+```
+
+### 特殊字符
+节点标签中需要转义的字符用引号包裹：
+```
+A["包含 (括号) 的文本"]
+B["包含 {花括号} 的文本"]
+```
+
+### 多行文本
+```
+A["第一行<br>第二行<br>第三行"]
+```
+
+### 链接样式索引
+边的索引从 0 开始，按声明顺序计数：
+```
+A --> B    %% 索引 0
+B --> C    %% 索引 1
+C --> D    %% 索引 2
+linkStyle 1 stroke:red   %% 给 B-->C 染红
+```