markdown-html-orchestrator

Markdown → HTML — 领域编排器

Thariq Shihipar 的观点（Claude Code HTML 输出文章，Medium 2026）：**对于 Agent 生成的内容，markdown 超过 100 行后就会失去优势。**长篇规范、代码审查和架构说明一旦超过一屏文本，就会失去信息密度、层次结构和轻量交互。HTML 能恢复这三者——单文件、浏览器原生、易于分享。

此编排器会分叉上下文，以确定性方式对输入的 markdown 进行分类，将其路由到合适的转换子技能，并返回摘要和输出路径。大量输入内容（完整 markdown 正文、差异内容、幻灯片）会留在分叉的上下文中。

**领域状态（已完成）：**全部五项技能均已上线——编排器 + design-system（引导设置 + 共享品牌标记）+ 三个转换子技能（md-document、md-review、md-slides）。转换时始终路由到已发布转换器的脚本；切勿直接内联手工渲染 HTML。

何时调用

症状	子技能
“将这份 RFC / 规范 / 报告 / 说明文档转换为 HTML”——长篇文档	md-document
“将这篇 PR 说明 / 代码审查转换为 HTML”——含差异块的 markdown	md-review
“根据这份 markdown 制作幻灯片”——包含 --- 分隔符或 H1 标题规律	md-slides

预检关卡（严格拒绝条件）

1. **未达到 100 行阈值。**低于 100 行时，markdown 更合适（Shihipar）。分类器会打印 below_min_lines: true，而 route_explainer.py 会拒绝处理。告知用户保留输入的 markdown 格式。
2. **尚未完成 design-system 引导设置。**如果 ~/.config/markdown-html/design-system.json 不存在（或其 setup_completed_at 为 null），则拒绝处理。请用户运行 python3 markdown-html/skills/design-system/scripts/onboard.py（或使用 --defaults 进行零交互运行）。
3. **保存位置不可写。**如果配置的 default_output_dir（或 --out 覆盖值）不可写，output_path_resolver.py 将拒绝处理。

路由逻辑（确定性）

采用从 research-ops/skills/research-ops-skills/SKILL.md 借鉴的双信号阈值模式。文件名提示 = 2 分；每项内容信号 = 1 分。胜出项 ≥ 3 分，且（次高项 = 0 或胜出项 ≥ 次高项的 2 倍）时，允许静默路由。未达到阈值时，提出一个澄清问题并附上建议答案。

信号表

信号类别	文件名提示	内容信号	子技能
DOCUMENT	report.md、*-doc.md、spec.md、rfc-*.md、*-analysis.md、*-explainer.md	## Table of Contents（2）、^# 、^## 、markdown 表格行、> [!NOTE]/[!TIP]/[!IMPORTANT] 提示块	md-document
REVIEW	review.md、*-pr-*.md、*.diff.md、code-review*.md	```diff（2）、^[-+]{3} （2）、^@@（2）、> [!BLOCKER]/[!MAJOR]/[!MINOR]/[!NIT]（2）、LGTM/nit:/blocker:	md-review
SLIDES	deck.md、slides.md、*-talk.md、presentation*.md	^---$ ≥ 3（2 + 每个分隔符加分）、<!-- notes:（2）、H1 数量 ≥ 5 且中位间隔 ≤ 12 行（2）	md-slides

流程：

python3 markdown-html/skills/markdown-html-orchestrator/scripts/doctype_classifier.py \
    --input <path>.md --output json \
  | python3 markdown-html/skills/markdown-html-orchestrator/scripts/route_explainer.py

route_explainer.py 会检查 design-system 状态，应用 < 100 行拒绝规则，并输出以下结果之一：ROUTE_SILENTLY -> md-<type>、ASK_USER one question: ... 或 REFUSE — fix the issues above。

工作流

步骤 1 — 确认已完成引导设置

如果用户从未运行过引导设置，展示一次性设置步骤：

python3 markdown-html/skills/design-system/scripts/onboard.py

十个问题，用时 1-2 分钟。收集品牌主色 + 强调色 + 标题/正文 Google Fonts + 设计风格（编辑风/技术风/极简/活泼）+ 默认输出目录 + 语法主题 + 目录行为 + 可选徽标/公司名称。设置保存在 ~/.config/markdown-html/design-system.json。可使用 --scope project 重新运行，以便针对每个仓库进行覆盖设置。

步骤 2 — 对输入进行分类

对 markdown 运行 doctype_classifier.py。检查分类结果。

第 3 步 — 路由或提问

将分类结果传入 route_explainer.py。如果结果是 ROUTE_SILENTLY，就在分支上下文中，将原始 Markdown 和设计系统配置传给指定子技能的渲染器。如果结果是 ASK_USER，则提出一个问题，并附上推荐答案。

第 4 步 — 确定输出路径

python3 markdown-html/skills/markdown-html-orchestrator/scripts/output_path_resolver.py \
    --input <path>.md --doctype <document|review|slides>

发生冲突时，默认添加 -2 / -3 / ... 后缀；使用 --on-collision timestamp 可生成带时间戳的名称。

第 5 步 — 移交给子技能

路由到的转换子技能渲染器（md-document/scripts/、md-review/scripts/ 或 md-slides/scripts/）接收输入 Markdown、设计系统配置和已确定的输出路径，并写入一个独立完整的 HTML 文件。编排器返回一段不超过 100 个词的摘要，包含输入行数、输出路径、采用的设计风格、使用的 3 个主要功能（目录、搜索、代码复制等），以及向用户提出的一个引导性问题。绝不手动渲染 HTML——渲染工作由转换脚本负责。

引导性问题库（Matt Pocock 的文档审视模式）

一次提出一个问题，并为每个问题提供推荐答案，同时引用规范来源。将此列表纳入 /cs:grill-markdown-html，用于计划阶段的询问。

1. 这个 HTML 要辅助做出什么决策——读者是在快速浏览、做决定，还是进行演示？ 推荐：先明确用途；内容密度应由目的决定。规范：Shihipar——“让输出格式匹配使用场景”；Tufte——Visual Display of Quantitative Information，第 1 章。
2. 输入 Markdown 是否有 100 行或以上？ 推荐：是——少于 100 行时，保留 Markdown 格式。规范：Shihipar——少于 100 行时，Markdown 仍是更好的选择。
3. 是否已接入设计系统？ 推荐：是，全局接入（~/.config/markdown-html/design-system.json）。规范：research-ops 接入模式（research-ops/CLAUDE.md §8）；WCAG 2.2 §1.4.3（文本对比度为 4.5:1）。
4. 输出保存到哪里？是否会覆盖现有内容？ 推荐：保存到配置的 default_output_dir，并使用 --on-collision suffix。规范：Matt Pocock 的 handoff 技能——绝不静默覆盖可用产物。
5. 对文档类型的判断有多大把握——静默路由还是提问？ 推荐：仅当分类器判定为 document/review/slides 之一，且 silent_route_allowed: true 时，才静默路由。否则提问。规范：research-ops 双信号阈值（research-ops/skills/research-ops-skills/SKILL.md §"Routing logic"）。

在确定流程路径之前，绝不要运行子技能。

假设

1. 用户有一个想要转换的 Markdown 文件，且文件至少有 100 行。
2. 用户已运行过一次接入流程（~/.config/markdown-html/design-system.json 存在，且已填充 setup_completed_at）。
3. 可以接受单文件 HTML 输出（无多文件站点、无嵌入式服务器、无构建步骤）。
4. 外部资源仅限 Google Fonts CSS 和 Prism.js CDN（jsdelivr / cdnjs）。

非目标

• 不用于生成落地页（请使用 marketing/landing/）。
• 不用于交互式提示词调优试验场（请使用 Anthropic 官方的 playground 插件）。
• 不用于生成静态站点（无多文件输出、无站点索引）。
• 不用于生成 PDF（幻灯片使用 @media print；用户通过浏览器打印）。
• 不用于监听 / 实时重载流水线（转换只执行一次）。

与以下工具的区别

• Anthropic Playground 插件（/playground）——构建用于提示词调优的交互式控件（滑块、旋钮、拖放），并支持复制提示词回传的流程。此插件则将现有 Markdown 文档转换为 HTML。工具不同，用途也不同。
• marketing/landing/——从零生成落地页（Phase-0 信息收集 → 3 个版块 → 带品牌风格的 TSX/HTML）。此插件转换的是已有的 Markdown 文件。
• engineering/handoff/ + productivity/handoff/——在 Claude 对话之间保持会话连续性。产物类型不同（交接摘要与文档转换）。

输出产物

子技能	产物	状态
md-document	doc-<slug>.html（单文件，固定目录，折叠面板，搜索，代码复制，滚动定位）	✓ 已上线
md-review	review-<slug>.html（双栏差异 + 严重性边注 + 跳转导航）	✓ 已上线
md-slides	deck-<slug>.html（方向键导航 + 演示者模式 + 打印为 PDF）	✓ 已上线

反模式（请勿）

• ❌ 转换少于 100 行的 markdown——markdown 仍然更合适。拒绝并告知用户。
• ❌ 在 design-system 完成接入前运行编排器。缺少设计令牌时，输出效果会很差。
• ❌ 悄悄串联两个子技能（例如“转换文档并制作幻灯片”）。选择一个，完成后再询问是否串联。
• ❌ 使用外部 JS 框架（React/Vue/Svelte）。仅使用原生 JS + IntersectionObserver。Prism.js CDN 是唯一例外。
• ❌ 输出多个文件（提取 CSS、资源目录）。只生成单文件，否则不生成——这正是核心要点。
• ❌ 默认覆盖现有输出文件。路径解析器会添加 -2、-3 等后缀；只有明确选择 --on-collision overwrite 时才覆盖。

参考资料

• 规范：Thariq Shihipar — “Claude Code HTML output”（Medium，2026）
• 分叉模式：research-ops/skills/research-ops-skills/SKILL.md（context: fork，双信号路由）
• 自定义模式：research-ops/skills/clinical-research/scripts/（onboard.py、config_loader.py）
• 品牌配色计算：marketing/landing/skills/landing/scripts/brand_palette_validator.py（WCAG + HSL 推导）
• 信息密度经典参考：Tufte；Shihipar 的 thariqs.github.io/html-effectiveness/ 画廊；Wattenberger 交互式文章；Maggie Appleton 数字花园