beihai23 Cognitive HTML Doc
把密集的 Markdown 重构为认知降维的工业级单文件 HTML。
核心哲学（纲领）
认知降维 = 降低阅读成本，不是降低信息完整度。
降维是重组信息的呈现方式（空间位置 / 视觉权重 / 交互组件），不是删减信息量。这条源于真实事故：13,000 字符规格被当摘要任务压成 7,400 字符交付，丢失字段/状态/异常。后续所有机制都为落实这一条。
读者三节奏，产出必须同时满足：
- 3 秒抓核心：Hero 区一句话定位 + 4 维度卡片
- 30 秒理解全貌：精修主架构图（手写 SVG + 语义箭头）
- 3 分钟查细节：固定侧边栏 TOC + 滚动高亮（移动端有替代导航）
执行模型（先读懂这段，再动手）
本 skill 的规则分两层：
- 机检层：可机械验证的项由
validate.mjs物理保证。交付前必须运行node validate.mjs <output.html> --source <source.md>，全绿（允许 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）。未决项/当前关键约束用 <details open>。"为了简洁折叠核心"是违规。
Step 4 · 选表现形式（判断门②）
先问读者目的，再问内容类型——不机械套用"内容类型→形式"：
| 读者目的 | 推荐形式 |
|---|---|
| 快速判断 | 关键数字卡片 + 状态色 + Hero |
| 理解关系 | 精修 SVG 图（先分 L1/L2/L3）/ 并排卡片 |
| 做决策 | 对比表格 + callout |
| 执行操作 | 时间轴 / 步骤卡片 |
| 查阅参数 | 表格 + hover |
| 学习概念 | hover 定义 + 折叠详解 |
图表分级：读者会盯着看 >10 秒的图 → L1/L2 → 手写精修 SVG（从 assets/svg-skeletons.md 的布局骨架起步，不交给 Mermaid 自动布局），配隐形 <!-- mermaid-source: --> 注释做结构真源；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 <body> 开头嵌入 meta 注释块（JSON），这是完整度的可机检证明：
<!-- cognitive-html-doc-meta
{
"mode": "双层型",
"source": { "path": "source.md", "sha1": "<源文件sha1>", "chapters": 13 },
"mapping": [
{ "source": "§1", "html": "#sec-1", "handling": "完整展开" },
{ "source": "§2-4", "html": "#sec-2", "handling": "合并呈现" }
],
"visual_review": { "hero-arch": "passed" }
}
-->
硬性规则：mapping 行数 == source.chapters（每一行源章节都必须出现，没出现 = 可能无意删了）；handling 限 5 枚举：完整展开 / 合并呈现 / 折叠保留 / 附录保留 / 删除并说明理由；sha1 用 shasum source.md 取。然后运行 node validate.mjs <html> --source <md>，修到无 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 时才引入
常见反模式
- "Markdown + CSS"伪重构：只换字体颜色，没做空间重组
- 主视觉交给 Mermaid 自动布局：L1/L2 必须精修 SVG（从 svg-skeletons 起步），Mermaid 只用于 L3 和隐形结构真源
- ASCII 图直接搬运：应转精修 SVG 或嵌套卡片
- Tab 隐藏核心对比：双方案对比用 Tab 首屏看不到 → 并排卡片
- 为了简洁折叠核心：核心内容应展开+强化
- 朴素 summary：重要折叠没色条/badge/计数 → 用户不会点开
- 数字藏在文字里：关键数字应大字号卡片
- 逻辑链断点：跳过数据来源/错误处理等关键环节
- 只盯用户指出的单点：不扫描全文找同类
- 分层=折叠：6 类手段只用 1 类；或关键信息只藏 hover（移动端/截图/SEO 全丢）
- 场景词锚定通用原则："KPI 应该突出"让技术读者误判不适用
- 混淆语义重复与必要重复：把不同层次的表达当重复删掉（本 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 <html> --source <md>）