Skip to content

zach22-1999/generic-skills / skills/zach-md-html

zach-md-html

Verified

已降级的 Markdown→HTML 兼容转换器。仅当用户明确要求“使用 zach-md-html”、或明确说“不要重组内容,只把现成 Markdown 机械转换成 HTML/套用旧主题”时使用。不要因为用户只说“输出成 HTML”“生成 HTML 报告”“把日常报告做成 HTML”“数据报告/交付报告”而触发;这些任务应由模型从原始资料直接组织并生成自包含 HTML。此 Skill 不负责数据可视化、工作面、自由设计、万物转 md、html 转 md 或 md 转 docx。

references/visual-designer-mode.md

View on GitHub
# 三档模式 · default / workspace / free-design

> 这是 zach-md-html 能力 2(md → html)的完整方法论。
> 在 zach-md-html「兜底 vs 视觉设计师」两种模式之上**升级为三档**——加入 Thariq 风格的「工作面」中间档,覆盖大部分场景,让"自由设计师档"只承担真正需要的创意自由度。

---

## 三档并存

| 档位 | 是否耗 token | 适合场景 | 工作流 |
|------|------|---|---|
| **A · default**(兜底) | ❌ 不耗 | 单线性叙述:散文 / 报告 / 教程 / 说明文档 | `md_to_html.py --theme xxx` 一条命令 |
| **B · workspace**(工作面) | ✅ 少量 | 含空间结构信号:对比 / 时间线 / 计划 / 评审 / 周报 / 解释器 | AI 识别场景 → 选模板 → pandoc 渲染 → 反 slop 检查 |
| **C · free-design**(自由设计师) | ✅ 多 | 强空间结构 + 无模板能匹配:dashboard / 自定义编辑器 / playground | AI 介入 4 步工作流,直接产出自包含 HTML,过 6 条自检 |

三档**不冲突**——大部分时候用 A,遇到「工作面信号」切换到 B,遇到「dashboard / 自定义」级需求切换到 C。

---

## 档 A · default 兜底

最简单、最稳定、不耗 token。

### 工作流

1. AI 收到「这篇 md 转 html」「做个 html」「生成 html」请求
2. **不读 md 全文,只看类型**——如果用户语言里没有空间结构信号词,默认走 default
3. 选阅读型主题(article / report / reading / interactive / wechat)
4. 跑 `python scripts/md_to_html.py input.md --theme article` 类命令
5. 5 秒出活,结束

### 何时走 A

- 「把这篇 md 做成 html」(无其他修饰)
- 「用 article / report 主题」
- 「公众号转接 / 微信文章」(→ wechat)
- 「长教程 / 橙皮书章节」(→ interactive)
- 「essay / 博客文章」(→ article)
- 「技术报告 / 白皮书」(→ report)

---

## 档 B · workspace 工作面(重点)

这是 zach-md-html 公开版强化的一档。

### 工作流(4 步)

```
md 输入
  ↓ ① 识别:AI 读 md 头部(< 30 行)找空间结构信号词
  ↓ ② 选模板:从 12 个场景中选最匹配的(见 workspace-scene-catalog.md)
  ↓ ③ 渲染:用对应 workspace 模板 + pandoc + 模板自带的 vanilla JS
  ↓ ④ 反 slop 检查:过 anti-ai-slop.md 的 12 条主清单(不是 free 的 6 条快速自检)
自包含 HTML 单文件(带「复制为 markdown」按钮)
```

### 第 1 步 · 识别信号词

读 md 头部 + 章节标题,找下列**强信号词**:

| 信号词 | 推荐场景 |
|--------|---------|
| 「方案 A / 方案 B」/「对比 / 选型 / ADR」 | comparison |
| 「实施计划 / roadmap / 里程碑 / 时间表」 | plan-board |
| 「PR / pull request / 代码评审 / diff」 | annotated-pr |
| 「事故 / 故障 / postmortem / 复盘」 + 时间戳 | incident-timeline |
| 「新特性 / feature / API 介绍 / FAQ」 | feature-explainer |
| 「周报 / 月报 / status / KPI / 进度」 | status-weekly |

**没强信号词** → 不要硬走工作面档,回退 default。

**多个信号词冲突**(如同时提"对比"和"时间线")→ 反问用户「你想要哪种?」

### 第 2 步 · 选模板

确认场景后跑:

```bash
python scripts/md_to_html.py input.md --scene comparison
# 或显式:
python scripts/md_to_html.py input.md --scene auto
```

> 注:当前 MVP 阶段,--scene 在脚本层会**降级到 default 并打印 notice**。
> 期间 AI agent 应该**自己直接 Write 一份工作面 HTML**(参考 `workspace-scene-catalog.md` 中场景描述 + `workspace-five-principles.md` 中 5 原则 + `js-interaction-allowlist.md` 中 JS 范围)。
> 等第 3 轮 MVP 6 个模板落地后,--scene 真实生效,AI 可以直接调脚本。

### 第 3 步 · 渲染

工作面 HTML 必须满足:

- **空间布局**(不是单栏纵向文字流)—— 见 `workspace-five-principles.md` 第 1 条
- **轻交互**(折叠 / tab / slider / copy 任选 1-2 个)—— 见 `js-interaction-allowlist.md`
- **视觉编码**(severity / 时间 / 状态 用颜色或位置)—— 见 `workspace-five-principles.md` 第 3 条
- **右下角「复制为 markdown」按钮**(强制)—— 见 `workspace-five-principles.md` 第 5 条
- **响应式**(@media max-width: 720px 至少处理一道)

### 第 4 步 · 反 slop 检查

过一遍 `anti-ai-slop.md` 的 12 条主清单。**注意**:工作面档不强制 free 档的 6 条快速自检,但主清单 12 条全部约束。

---

## 档 C · free-design 自由设计师

让 AI 完全自由设计 HTML,不被模板束缚。

### 何时走 C

| 用户说的话 | 应该走 C |
|---|---|
| 「做一个 dashboard」 | ✅ |
| 「做一个 feature flag 编辑器」 | ✅ |
| 「playground 风 / 实时调参」 | ✅ |
| 「按 Anthropic 风格做」 | ✅(流派已定,跳过推荐直接做) |
| 「给这个 md 做个出色的 html」+ 内容复杂 | ✅ |
| 「让我看看几种风格」 | ✅(必给 3 个差异化方向) |
| 「完全自定义」/「自由发挥」 | ✅ |
| 「这个 md 转 html」 | ❌(走 A) |
| 「方案对比 / 事故复盘」 | ❌(走 B) |

### 工作流(5 步,原始两档模式升级)

```
md 输入 + 用户意图
  ↓ ① 阅读:AI 读 md(title / 章节结构 / 内容调性 / 受众线索)
  ↓ ② 推荐:3 个差异化设计方向,每个来自不同流派 + 代表参考
  ↓ ③ 用户拍板:选一个方向(或快速直选)
  ↓ ④ 实现:AI 直接 Write 一份完整自包含 HTML,不走 pandoc
  ↓ ⑤ 6 条快速自检:过 anti-ai-slop.md 末尾的强制清单
自包含 HTML 单文件(带「复制为 markdown」按钮)
```

### 第 1 步 · 阅读 md 找设计线索

| 维度 | 怎么看 | 影响什么 |
|------|--------|----------|
| **内容类型** | essay?产品介绍?dashboard?playground? | 决定基础布局 |
| **受众身份** | 开发者?普通读者?投资人?编辑? | 决定字号 / 严谨度 / 留白量 |
| **调性气质** | 严肃克制?热情活泼?技术冷静?文艺? | 决定字体 / 配色 / 视觉节奏 |
| **结构密度** | 信息密度高?散文型?多模块? | 决定布局(宽体 / 单栏 / grid) |
| **品牌锚点** | 是否有已有视觉系统? | 决定能不能复用色板 |

### 第 2 步 · 推荐 3 个差异化方向

每个方向来自**不同流派**(避免"一种风格的三种微调"):

| 流派 | 代表 | 适合 |
|------|------|------|
| Pentagram 信息建筑 | Paula Scher / Pentagram NY | 严肃产品、企业落地页、信息密集 |
| Tufte 信息可视化 | Edward Tufte | essay、学术、数据驱动 |
| Kenya Hara 东方极简 | 原研哉 / MUJI | 文艺、产品哲学、克制 |
| Anthropic 暖色科技 | Anthropic / Notion 早期 | 开发者工具、温暖品牌 |
| Stripe Docs | Stripe / Linear | 技术文档、SaaS 工具 |
| Penguin Books | Penguin / 出版业 | 书籍、长内容、阅读优先 |
| Sagmeister 实验先锋 | Stefan Sagmeister | 创意、艺术、张扬 |
| Field.io 运动诗学 | Field.io / 数字艺术 | 实验、抽象、新媒体 |
| Bauhaus 几何包豪斯 | Bauhaus / Vignelli | 严谨、几何、教科书 |

**每个方向至少包含**:
- 哲学锚点(一句话定调)
- 配色(3-4 个具体色值)
- 字体组合(中英文 + 代码)
- 关键视觉锚点(hero 怎么做、表格怎么做、卡片怎么做)

3 个方向给完之后,**告诉用户你推荐哪个 + 为什么**,但让用户拍板。

### 第 3 步 · 用户拍板

不要默认替用户选。设计判断有主观成分,让人来决定。

**例外**:用户说「按 Anthropic 风格做」/「按 Tufte 风做」 — 流派已定,跳过推荐直接做。

### 第 4 步 · 实现

1. **不依赖 pandoc**——直接手写自包含 HTML,全 inline CSS。这样定制空间最大。
2. **以 md 内容为蓝本**——按 md 的章节结构组织 HTML 区块,但**每个区块可以定制版式**。
3. **应用方向的视觉语言**——配色、字体、间距、字号、装饰、动效(如果需要)都按方向走。
4. **JS 限于白名单**——见 `js-interaction-allowlist.md`,禁止 React/Vue/CDN/网络请求。
5. **图片用相对路径**——不要 base64 嵌入(防止文件巨大),除非用户明确要求 self-contained。
6. **响应式必做**——`@media (max-width: 720px)` 至少处理一道。
7. **「复制为 markdown」按钮必做**——右下角固定,是工作面身份标识。
8. **保持反 AI slop 底线**——见 `anti-ai-slop.md` 的 12 条主清单 + 末尾 6 条快速自检。

### 第 5 步 · 6 条快速自检(强制)

完成 Write 后,AI 必须过 `anti-ai-slop.md` 末尾的 6 条:

1. 最大宽度 ≤ 820px(单栏) / 卡片内 ≤ 820px(grid)
2. 正文行高 ≥ 1.7
3. 中文衬线 / 系统 sans,英文 Inter / serif,代码 JetBrains Mono
4. 无紫渐变 / 赛博霓虹 / #0D1117 深蓝底
5. 无圆角卡片 + 左 border accent 烂组合
6. emoji 仅装饰,不作图标

**任一未过 → 重写 HTML**。连续两次不过 → **降级到 default 档**并告知用户。

---

## 三档选档决策树

```
用户输入 md + 意图描述
  │
  ├─ 用户显式 flag?
  │   ├─ --free-design → 走 C
  │   ├─ --scene xxx  → 走 B
  │   ├─ --theme xxx  → 走 A
  │   └─ --mode {default|workspace|free} → 显式选档
  │
  ├─ 用户语言信号?
  │   ├─ 「做个 dashboard / 自定义 / 出色 / 几种风格」 → 走 C
  │   ├─ 「对比 / 时间线 / 计划 / 评审 / 周报 / 解释器 / FAQ」 → 走 B
  │   ├─ 「转 html / 做 html / 生成 html / 公众号 / essay」 → 走 A
  │   └─ 没明确信号 → 读 md 内容判断
  │
  ├─ md 内容判断?
  │   ├─ 含工作面强信号词且单一场景 → 走 B
  │   ├─ 含工作面信号但多场景模糊 → 反问用户
  │   ├─ 强空间结构 + 模板无法覆盖 → 走 C
  │   ├─ 单线性叙述 → 走 A
  │   └─ 置信度 < 70% → 降级到 A
```

---

## 三档之间的失败降级

- **B 失败**(工作面渲染或自检不过)→ 降级到 A,告知用户
- **C 失败**(自检多次不过)→ 降级到 A,告知用户
- **A 永远不应该失败**(pandoc + 现成主题 + 5 秒命令)—— 如果 A 都失败,是依赖或环境问题,**直接报错而非沉默**

---

## 一句话总结

**A 是"我给你什么",B 是"我把你的内容空间化",C 是"你的内容应该被怎么表达"。**

A 不耗 token,最稳定;B 中等成本,覆盖大部分工作面场景;C 最自由,承担真正需要原创设计的产物。

按内容形态自动选档,不要乱选——**置信度低就降级**,比选错强。
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall