md-document 是一个面向长篇 Markdown 文档的通用转换器，主要处理规格说明、计划、RFC、报告和讲解材料等场景。它由三个标准库工具串联成流水线：markdown_parser.py 将 Markdown 解析为 JSON AST；html_renderer.py 将 AST 与设计系统配置渲染为单文件 HTML；interactivity_injector.py 向 HTML 注入轻量 JS 行为。最终输出为一个 .html 文件，包含粘性目录、搜索过滤、滚动监听、代码复制按钮，以及用户派生的 12 个品牌令牌。外部依赖仅限 Google Fonts CSS 与 Prism.js CDN。
主要能力方面，该工具支持 CommonMark 子集，足以处理智能体生成的产物：H1-H6 标题（每个 H2 及以上标题获得锚点 id 和目录条目）、带行内粗体/斜体/代码/链接的段落、带 Prism.js 按需高亮的围栏代码块、支持按列对齐的 GFM 表格、GFM 提示块（NOTE、TIP、IMPORTANT、WARNING、CAUTION）、块引用、有序与无序列表（单层）、水平分割线。不在范围内：嵌套列表、行内 HTML、脚注、定义列表、任务列表复选框（按纯文本渲染）、引用式链接。
使用方式上，可以分三步运行：第一步用 markdown_parser.py 将 Markdown 解析为 sections.json；第二步用 html_renderer.py 将 sections.json 渲染为 document.html；第三步用 interactivity_injector.py 注入 search、copycode、smoothscroll、scrollspy 等特性。也可以使用一体化示例渲染命令，通过管道将 html_renderer.py 的 --sample 输出传给 interactivity_injector.py。
适用场景包括：当 markdown-html-orchestrator 将输入路由为 DOCUMENT 时调用；用户直接运行 /cs:md-document <path>.md 时调用；用户要求将规格/报告/RFC/计划转换为 HTML 时调用。若输入是代码审查（含 ```diff 块），应改用 md-review；若输入是幻灯片（有清晰的 --- 边界），应改用 md-slides；若输入少于 100 行，则拒绝处理（Shihipar 阈值，Markdown 仍更优）；若设计系统未接入，则拒绝并提示 /cs:design-system。
限制与硬性规则：拒绝少于 100 行的输入；拒绝未完成设计系统接入的情况（config_loader.setup_completed() 必须返回 True）；输出必须为单文件，所有 CSS 与 JS 内联，仅允许 fonts.googleapis.com 和 cdn.jsdelivr.net（Prism）作为外部资源；自定义必须改变行为，例如 design_style=editorial 产生 720px 宽布局与 1.75 行高，playful 使提示块变圆并添加阴影，technical 使用 0.875rem 代码的紧凑样式；令牌需符合 WCAG AA 对比度（正文文本至少 4.5:1，链接迭代调整至 4.5:1）；注入具有幂等性，重复注入为无操作，使用不同 design_style 重新渲染可正常工作。
输出产物路径为 {default_output_dir}/doc-{slug}.html，路径由 orchestrator 的 output_path_resolver.py 解析，默认冲突时添加 -2、-3 等后缀。