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图（覆盖路径） ├─ CI/CD流程 → Mermaid flowchart LR ├─ 部署架构 → Mermaid graph TB └─ 性能基准 → Vega-Lite对比图

运维监控 ├─ 告警策略 → 表格 + 条件样式 ├─ 故障处理 → Mermaid flowchart（决策树） └─ 监控大屏 → Infographic仪表板

场景模板库

1. API 响应说明（L2-L3）

❌ 纯文本描述

接口先验证token，然后检查权限，最后返回数据

✅ Mermaid 时序图

sequenceDiagram Client->>+API: POST /data API->>+Auth: verify(token) Auth-->>-API: valid API->>+DB: query DB-->>-API: result API-->>-Client: 200 + data

2. 数据库 ERD（L3-L4）

erDiagram USER ||--o{ ORDER : places USER { int id PK string email string name } ORDER { int id PK int user_id FK decimal total datetime created_at }

3. 系统架构图（L3-L4）

graph TB subgraph Client A[React SPA] B[Mobile App] end subgraph Gateway C[NGINX] D[API Gateway] end subgraph Services E[Auth Service] F[Core API] G[Worker] end subgraph Data H[(PostgreSQL)] I[(Redis)] J[Object Storage] end

A --> C
B --> C
C --> D
D --> E
D --> F
F --> G
F --> H
F --> I
G --> J

4. 状态机设计（L2-L3）

stateDiagram-v2 [] --> Draft Draft --> Pending: submit Pending --> Approved: approve Pending --> Rejected: reject Approved --> Published: publish Rejected --> Draft: revise Published --> Archived: archive Archived --> []

5. 错误处理流程（L3-L4）

flowchart TD A[API调用] --> B{异常?} B -->|No| C[正常响应] B -->|Yes| D{异常类型} D -->|4xx| E[返回错误信息] D -->|5xx| F[记录日志] F --> G[返回500] D -->|Timeout| H[重试] H --> I{重试次数>3?} I -->|No| A I -->|Yes| J[熔断降级]

style E fill:#ffebee
style G fill:#ffebee
style J fill:#fff3e0

6. CI/CD 部署流程（L3-L4）

flowchart LR A[Push] --> B[Build] B --> C[Test] C --> D{Pass?} D -->|Yes| E[Deploy Staging] D -->|No| F[Notify] E --> G[Integration Test] G --> H{Pass?} H -->|Yes| I[Deploy Prod] H -->|No| F I --> J[Done]

7. 技术选型对比（L2-L3）

方案 性能 生态 学习成本 维护成本 推荐度

A: React ★★★★☆ ★★★★★ ★★★☆☆ ★★★★☆ 首选

B: Vue ★★★★☆ ★★★★☆ ★★★★☆ ★★★★★ 备选

C: Svelte ★★★★★ ★★★☆☆ ★★★★★ ★★★☆☆ 观察

8. 性能基准对比（L3-L4）

{ "data": {"values": [ {"framework": "React", "ops": 45000, "memory": 45}, {"framework": "Vue", "ops": 52000, "memory": 38}, {"framework": "Svelte", "ops": 68000, "memory": 28}, {"framework": "Solid", "ops": 72000, "memory": 25} ]}, "encoding": { "x": {"field": "framework", "type": "ordinal"}, "y": {"field": "ops", "type": "quantitative", "title": "ops/sec"} }, "layer": [ {"mark": "bar", "encoding": {"color": {"value": "#4a90d9"}}}, {"mark": {"type": "text", "dy": -5}, "encoding": {"text": {"field": "ops"}}} ] }

9. 前端组件层级（L2-L3）

graph TD App --> Layout Layout --> Header Layout --> Sidebar Layout --> Main Main --> PageContainer PageContainer --> Table PageContainer --> Form Table --> Pagination Table --> FilterBar Form --> Input Form --> Select Form --> Button

10. API 路由表（L3-L4）

<table> <tr> <th>Method</th> <th>Path</th> <th>Auth</th> <th>Rate Limit</th> <th>描述</th> </tr> <tr> <td><span style="background:#4caf50;color:white;padding:2px 6px;border-radius:3px;">GET</span></td> <td><code>/api/users</code></td> <td>✓</td> <td>100/min</td> <td>列表查询</td> </tr> <tr> <td><span style="background:#2196f3;color:white;padding:2px 6px;border-radius:3px;">POST</span></td> <td><code>/api/users</code></td> <td>✓</td> <td>10/min</td> <td>创建用户</td> </tr> <tr> <td><span style="background:#ff9800;color:white;padding:2px 6px;border-radius:3px;">PATCH</span></td> <td><code>/api/users/:id</code></td> <td>✓ Admin</td> <td>20/min</td> <td>部分更新</td> </tr> </table>

11. 模块依赖说明（L2-L3）

❌ 文字罗列

A依赖B和C，B依赖D，C依赖D和E

✅ DOT 依赖图

digraph { rankdir=TB; A -> B -> D A -> C -> D C -> E }

12. 监控仪表板（L4）

✅ Infographic 柱状图

infographic column-chart data title 生产环境关键指标 items - label 可用性 value 99.95 - label P50延迟 value 42 - label P99延迟 value 128 - label 活跃告警 value 3

✅ Infographic 进度图（项目完成度）

infographic progress-chart data title Sprint 进度 items - label API开发 value 100 - label 前端联调 value 75 - label 测试覆盖 value 60 - label 文档编写 value 30

✅ Infographic 饼图（资源占比）

infographic pie-chart data title 服务器资源分布 items - label Web服务 value 45 - label 数据库 value 30 - label 缓存 value 15 - label 队列 value 10

13. 复杂表格报表（L3-L4）

✅ HTML 合并表格

<table> <tr><th rowspan="2">模块</th><th colspan="2">性能</th></tr> <tr><th>CPU</th><th>内存</th></tr> <tr><td>Core</td><td>15%</td><td>256MB</td></tr> </table>

14. 类图设计（L3-L4）

classDiagram class User { +String id +String email +String name +login() +logout() } class Order { +String id +String userId +Decimal total +submit() +cancel() } class OrderItem { +String id +String orderId +String productId +Int quantity } User "1" --> "" Order : has Order "1" --> "" OrderItem : contains

15. 代码审查清单（L2-L3）

检查项 状态 说明

代码风格符合规范 ✓ Pass ESLint 无警告

单元测试覆盖 >80% ⚠ Warn 当前 72%

无 console.log ✓ Pass

敏感信息未硬编码 ✓ Pass

文档已更新 ✗ Fail README 未同步

渐进式增强策略（按交付物类型）

交付阶段 策略 图表类型 示例

初稿 纯文本速记 无 要点列表、TODO

讨论稿 结构化 + 流程图 Mermaid flow/sequence PRD、技术方案

评审稿 完整图表 + 标注 ERD、架构图、状态机 设计评审

终稿 全面可视化 图表 + 数据 + 样式 上线文档

避坑指南

坑 解决方案

图表太宽被截断 Vega-Lite 加 "width": 400

Mermaid 中文乱码 引号包裹 "中文"

复杂图表维护难 优先用简单流程图，复杂的上 Canvas

表格列不对齐 用 HTML <table> 替代 Markdown 表格

公式不渲染 检查 $ 是否配对，块级用 $$

快速参考路径

需要具体语法示例时，读取：

• ~/dev/ai/markdown-viewer-extension/docs/features/diagrams/mermaid.md

• ~/dev/ai/markdown-viewer-extension/docs/features/diagrams/vega.md

• ~/dev/ai/markdown-viewer-extension/demo/test-full.md (综合示例)