enhanced-markdown

Files (1)

• SKILL.md

SKILL.md (first lines)

# Enhanced Markdown Output Skill

让大模型输出充分利用 Markdown Viewer 扩展渲染能力的内容。

## 核心原则

> **人类可读性优先** —— 选择让读者理解最快的呈现方式，而非最炫技的方式。

---

## 渲染能力速查

| 能力 | 语法标记 | 最佳场景 | 复杂度 |
|------|---------|---------|--------|
| **Mermaid** | `mermaid` | 流程、架构、时序、类图 | ★☆☆ |
| **Vega-Lite** | `vega-lite` | 数据可视化、统计图表 | ★★☆ |
| **Canvas** | `canvas` | 思维导图、知识图谱 | ★★☆ |
| **DOT** | `dot` | 复杂关系、依赖树、状态机 | ★★☆ |
| **Infographic** | `infographic` | 统计图表、进度展示 | ★☆☆ |
| **LaTeX** | `$...$` / `$$...$$` | 数学公式、方程 | ★☆☆ |
| **合并表格** | HTML `colspan/rowspan` | 复杂报表、跨行跨列 | ★☆☆ |
| **内联 HTML** | `<tag>` | 样式增强、彩色标签 | ★☆☆ |

> 不确定具体语法？去 `~/dev/ai/markdown-viewer-extension/docs/features/` 查对应文档。

---

## 路由决策树

```
内容类型判断
│
├─► 有数据要展示？
│   ├─ 时间序列/对比 → Vega-Lite 图表
│   ├─ 占比/分布 → Infographic 饼图/柱状图
│   └─ 简单统计 → 表格
│
├─► 有流程/步骤？
│   ├─ 线性流程 (A→B→C) → Mermaid flowchart LR
│   ├─ 复杂分支 (多条件判断) → Mermaid flowchart TD
│   ├─ 系统交互 → Mermaid sequenceDiagram
│   └─ 代码执行流程 → 代码块 + 注释
│
├─► 有架构/组件关系？
│   ├─ 简单层级 → Mermaid graph TD
│   ├─ 复杂拓扑 → DOT graph
│   ├─ 云服务架构 → drawio (如需要精确图标)
│   └─ 概念关联 → Canvas 思维导图
│
├─► 有数学/算法？
│   ├─ 行内公式 → `$E=mc^2$`
│   ├─ 方程组 → `$$...$$` 块
│   └─ 算法步骤 → 编号列表 + 关键行 LaTeX
│
└─► 纯文本内容？
    ├─ 重点突出 → HTML `<mark>`, `<span style="color:">`
    ├─ 状态标签 → HTML `<span style="background:">badge</span>`
    └─ 结构清晰 → 标准 Markdown 层级
```

---

## 渐进式文档策略（全栈开发版）

根据文档用途和读者角色选择复杂度层级：

| 层级 | 目标读者 | 文档形式 | 图表密度 | 示例场景 |
|------|---------|---------|---------|---------|
| **L1-草稿** | 自己/AI | 速记要点 | 0% | 需求梳理、BUG记录 |
| **L2-讨论** | 团队成员 | 结构化描述 | 20% | PRD评审、技术方案讨论 |
| **L3-交付** | 跨团队协作 | 完整文档+关键图 | 40% | API文档、部署指南 |
| **L4-存档** | 未来维护者 | 全面可视化 | 60%+ | 架构文档、运维手册 |

### 渐进判定标准

```
问题 → 回答 → 决策

是否需要快速迭代？
├─ 是 → L1-草稿（纯文本速记）
└─ 否 → 继续

是否需要多人讨论？
├─ 是 → L2-讨论（结构化+Mermaid流程）
└─ 否 → 继续

是否需要长期维护？
├─ 是 → L4-存档（完整图表+版本记录）
└─ 否 → L3-交付（关键路径可视化）
```

---

## 编程场景模板路由

### 路由总览

```
开发阶段 → 文档类型 → 推荐渲染方式

需求分析
├─ 用户故事 → 文本 + 验收清单
├─ 业务流程 → Mermaid flowchart
└─ 数据流图 → Mermaid sequenceDiagram

架构设计
├─ 系统架构 → Mermaid graph TB / drawio
├─ 模块关系 → DOT digraph
├─ ERD设计 → Mermaid erDiagram
└─ 技术选型 → 对比表格 + Infographic卡片

编码实现
├─ API设计 → Mermaid sequenceDiagram
├─ 状态机 → Mermaid stateDiagram
├─ 类图 → Mermaid classDiagram
└─ 错误处理 → Mermaid flowchart（异常分支标注红）

测试部署
├─ 测试策略 → DOT图（覆盖路径）

From Dwsy/agent, MIT.

More from Dwsy/agent