# Cognitive HTML Doc
> 将密集、线性的 Markdown 技术/产品文档重构为认知降维的工业级单文件 HTML 文档。核心目标是让读者 3 秒抓核心、30 秒理解全貌、3 分钟查到细节。使用此 skill 当用户：把 markdown 转成 HTML、要求做"漂亮的 HTML 文档"、要求"工业级 HTML"、要"技术文档可视化"、给一份 markdown 蓝图要 HTML 化、需要带 TOC/Mermaid 图表/卡片设计的长文档、提到"降低认知负荷"或"扫视即可获取"。即使没明说"HTML 文档"，只要涉及把密集文字降维成结构化、可扫读的形态，就用此 skill。不要用于简单 markdown 渲染（一行命令即可）或纯打印样式 PDF。
- Skill: `beihai23/cognitive-html-doc` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add beihai23/cognitive-html-doc`
- Raw SKILL.md: https://api.skillmd.com/api/skills/beihai23/cognitive-html-doc/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: beihai23 (https://skillmd.com/u/beihai23)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/beihai23/cognitive-html-doc
---
# Cognitive HTML Doc
把密集的 Markdown 重构为**认知降维**的工业级单文件 HTML。
## 核心哲学（纲领）
> **认知降维 = 降低阅读成本，不是降低信息完整度。**
降维是重组信息的**呈现方式**（空间位置 / 视觉权重 / 交互组件），不是删减信息量。这条源于真实事故：13,000 字符规格被当摘要任务压成 7,400 字符交付，丢失字段/状态/异常。后续所有机制都为落实这一条。
读者三节奏，产出必须同时满足：
- **3 秒抓核心**：Hero 区一句话定位 + 4 维度卡片
- **30 秒理解全貌**：精修主架构图（手写 SVG + 语义箭头）
- **3 分钟查细节**：固定侧边栏 TOC + 滚动高亮（移动端有替代导航）
## 执行模型（先读懂这段，再动手）
本 skill 的规则分两层：
- **机检层**：可机械验证的项由 `validate.mjs` 物理保证。**交付前必须运行** `node validate.mjs --source `，全绿（允许 warn，不允许 fail）才算完成。不要靠记忆自查这些项。
- **判断层**：只有需要判断力的项留给模型（见文末"交付前检查"）。
历史教训：24 项纯文字清单在最硬的几项上被系统性跳过——文字规则改变不了执行可靠性，机制才可以。
## 场景无关性
所有原则适用于产品/技术/API/手册等任意密集文档。写原则用**中性词**（"关键数字"而非"KPI"），场景词只下沉到例子：
| 错误（锚定） | 正确（场景无关） |
|---|---|
| "KPI 应该突出" | "关键数字应该突出（产品 KPI / 技术 SLO / API 限流值）" |
| "护城河要前置" | "核心价值要前置（护城河 / 核心机制 / 差异化能力）" |
| "5 个理由要展开" | "决策依据要展开" |
| "Phase 1 必做项" | "MVP 必做项（Phase 1 / v1.0 / 稳定接口）" |
## 工作流程
| Step | 动作 | 细则 |
|---|---|---|
| 1 | 通读全文，画逻辑链：输入 → 处理 → 输出 → 反馈 | 下文 |
| 1.5 ⭐ | 选转换模式 + 给源章节打保真标签（判断门①） | 下文；`references/fidelity-and-mapping.md` |
| 2 | 逻辑完整性：关键环节缺失必须补并标注依据 | `references/completeness-check.md` |
| 3 | 信息分层：6 类手段按"读者何时需要"组合 | `references/layering-patterns.md`、`references/folding-decision.md` |
| 4 | 选表现形式：读者目的 → 内容类型 → 视觉节制 | `references/visualization-patterns.md` |
| 5 | 逐章扫描核心论点 + L1/L2 图视觉审查（判断门③） | `references/diagram-quality-contract.md` |
| 5.5 ⭐ | 写交付契约 meta 块，跑 validate.mjs | 下文 |
### Step 1 · 画逻辑链
不直接写 HTML。先画 `输入（数据/触发）→ 处理 → 输出 → 反馈/沉淀`，后续每节都是链上一环；断链处就是要补的关键环节（Step 2）。
### Step 1.5 · 转换模式 + 保真门（判断门①）
**选模式**（默认双层型；摘要型只在用户显式要求"给高管看/控制在 N 页"时用；要落地的规格类文档一律不进摘要型）：
| 模式 | 适用 | 处理方式 |
|---|---|---|
| 保真型 | 正式 PRD、研发规格、合同、手册 | 逐章保留，只重组呈现 |
| 双层型（默认） | 大多数产品/技术文档 | 主线精简 + 完整规格折叠保留 |
| 摘要型 | 汇报、路演 | 允许压缩，但必须说明删了什么 |
**打标签**（每章归一类，决定允许怎么处理）：**核心需求**（100% 保留+展开强化）/ **决策依据**（100% 保留，可移位不摘要）/ **执行规格**（可折叠但保全文不摘要）/ **重复表达**（合并到主定义处+锚点引用）/ **历史说明**（进附录）/ **可删除**（必须写明理由）。
一句话原则：**去重 = 合并重复表达，不是删减不同层次的细节。** 区分法：两处是给同一类读者、回答同一个问题吗？是→合并；否→都保留。
### Step 2 · 逻辑完整性
逐章问"这章删了逻辑链会断吗"。原文缺关键环节（产品：数据来源/未决项；技术：错误处理/回滚/监控；API：鉴权/限流/错误码）**必须主动补上**，标注依据（引用其他文档或注明"基于最佳实践补充"），不能以"原文没写"跳过。
### Step 3 · 信息分层（≠ 折叠）
6 类手段按"读者何时需要"选用：**空间位置**（侧栏约束卡）/ **视觉权重**（关键数字大字号）/ **Hover**（短补充信息，移动端不可用，关键信息不得只藏 hover）/ **折叠**（长内容）/ **跳转链接** / **附录**。
折叠三分类：**核心**→完全展开+视觉强化；**重要按需**→折叠+强化三件套（色条+badge+计数）；**真次要**→朴素折叠（class 加 `details-plain`）。未决项/当前关键约束用 ``。"为了简洁折叠核心"是违规。
### Step 4 · 选表现形式（判断门②）
**先问读者目的，再问内容类型**——不机械套用"内容类型→形式"：
| 读者目的 | 推荐形式 |
|---|---|
| 快速判断 | 关键数字卡片 + 状态色 + Hero |
| 理解关系 | 精修 SVG 图（先分 L1/L2/L3）/ 并排卡片 |
| 做决策 | 对比表格 + callout |
| 执行操作 | 时间轴 / 步骤卡片 |
| 查阅参数 | 表格 + hover |
| 学习概念 | hover 定义 + 折叠详解 |
**图表分级**：读者会盯着看 >10 秒的图 → L1/L2 → **手写精修 SVG**（从 `assets/svg-skeletons.md` 的布局骨架起步，不交给 Mermaid 自动布局），配隐形 `` 注释做结构真源；L3 小图可 Mermaid。Mermaid 源码先过 lint 禁忌（见 svg-skeletons.md 末节，如禁止 `A->>B via C:` 幻影参与者写法）。
**视觉节制**：同层连续卡片 ≤6；普通列表不全卡片化；每章最多一个主视觉重点；不为"页面整齐"把核心与次要同权展示。（121 卡片稀释视觉重点的真实事故。）
### Step 5 · 系统扫描 + 图表视觉审查（判断门③）
逐章问：核心论点是什么？是视觉重点吗？有信息平铺吗？用户指出单点问题时扫描全文找同类。
L1/L2 图必须**读图复查**（截图/浏览器打开）6 类碰撞：箭头穿节点 / label 压线互撞 / 节点重叠 / 图例盖内容 / 文字溢出边框 / viewBox 裁边。最多修两轮，结果记入 meta 块的 `visual_review`（passed/skipped）——**不许猜**。
### Step 5.5 · 交付契约（机制，不是自觉）
在 HTML `` 开头嵌入 meta 注释块（JSON），这是完整度的可机检证明：
```html
```
硬性规则：`mapping` 行数 == `source.chapters`（**每一行源章节都必须出现**，没出现 = 可能无意删了）；`handling` 限 5 枚举：完整展开 / 合并呈现 / 折叠保留 / 附录保留 / 删除并说明理由；`sha1` 用 `shasum source.md` 取。然后运行 `node validate.mjs --source `，修到无 fail。最后在对话里附 3 行报告：模式与合并/删除情况、折叠保留的规格数、校验结果。
## 交付前检查
**机检层**（validate.mjs 保证，不用自查）：meta 契约 N=N、源 sha1 同步、TOC↔锚点、手写 SVG 配 mermaid-source、mermaid initialize 与源码 lint、CDN theme、折叠三件套、卡片计数、移动端导航、Alpine 死加载、单文件。
**判断层**（模型自查，每项一句话能答）：
- [ ] 模式选择有依据？规格类文档没进摘要型？
- [ ] 保真标签打对了吗？执行规格是全文保留（折叠后没明显变短）？
- [ ] 逻辑链无断点？补的环节标注了依据并同步回源 markdown？
- [ ] 每章核心论点第一眼可见？
- [ ] 形式是读者目的驱动的？查过映射表的"何时别用"列？
- [ ] 折叠合法（没藏核心）？hover 没藏关键信息？
- [ ] 视觉节制：有且只有一个主视觉重点？关键数字脱离了表格？
- [ ] 原则命名场景无关？
## 视觉系统 & 技术栈（细则在 references/assets）
- 状态色 4 态（success/warning/danger/info）× text/border/bg 三态，全局一致
- 卡片 / callout / 强化 details / 关键数字（`tabular-nums`）：`assets/components.md`
- 骨架模板（含 TOC、scroll spy、移动端导航、meta 块示例）：`assets/template.html`
- CDN 栈（Tailwind+自定义 theme / Highlight.js / Mermaid 10）：`references/cdn-stack.md`；**Alpine.js 不默认加载**，需要 Tab/Tooltip 时才引入
## 常见反模式
1. **"Markdown + CSS"伪重构**：只换字体颜色，没做空间重组
2. **主视觉交给 Mermaid 自动布局**：L1/L2 必须精修 SVG（从 svg-skeletons 起步），Mermaid 只用于 L3 和隐形结构真源
3. **ASCII 图直接搬运**：应转精修 SVG 或嵌套卡片
4. **Tab 隐藏核心对比**：双方案对比用 Tab 首屏看不到 → 并排卡片
5. **为了简洁折叠核心**：核心内容应展开+强化
6. **朴素 summary**：重要折叠没色条/badge/计数 → 用户不会点开
7. **数字藏在文字里**：关键数字应大字号卡片
8. **逻辑链断点**：跳过数据来源/错误处理等关键环节
9. **只盯用户指出的单点**：不扫描全文找同类
10. **分层=折叠**：6 类手段只用 1 类；或关键信息只藏 hover（移动端/截图/SEO 全丢）
11. **场景词锚定通用原则**："KPI 应该突出"让技术读者误判不适用
12. **混淆语义重复与必要重复**：把不同层次的表达当重复删掉（本 skill 最严重的内容丢失模式）
## 详见
- `references/fidelity-and-mapping.md` — 转换模式 + 保真门 + 压缩预算 + 重复判定（v15/v16 对照案例）
- `references/diagram-quality-contract.md` — 图表质量契约（分级/箭头语义/几何预算/视觉审查门）
- `references/layering-patterns.md` — 分层 6 手段决策流程
- `references/visualization-patterns.md` — 内容→形式映射（含"何时别用"）+ Mermaid 模式库
- `references/folding-decision.md` — 折叠合法性判定
- `references/completeness-check.md` — 逻辑完整性清单（按文档类型）
- `references/cdn-stack.md` — CDN 详细配置
- `assets/template.html` / `assets/components.md` / `assets/svg-skeletons.md` — 模板 / 组件 / SVG 布局骨架
- `validate.mjs` — 交付前机检（`node validate.mjs --source `）