Cognitive html doc

Skill beihai23/cognitive-html-doc

将密集、线性的 Markdown 技术/产品文档重构为认知降维的工业级单文件 HTML 文档。核心目标是让读者 3 秒抓核心、30 秒理解全貌、3 分钟查到细节。使用此 skill 当用户：把 markdown 转成 HTML、要求做"漂亮的 HTML 文档"、要求"工业级 HTML"、要"技术文档可视化"、给一份 markdown 蓝图要 HTML 化、需要带 TOC/Mermaid 图表/卡片设计的长文档、提到"降低认知负荷"或"扫视即可获取"。即使没明说"HTML 文档"，只要涉及把密集文字降维成结构化、可扫读的形态，就用此 skill。不要用于简单 markdown 渲染（一行命令即可）或纯打印样式 PDF。From its SKILL.md

Install

npx -y skills add beihai23/cognitive-html-doc

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

11.2 KB, ~4.1k tokens by cl100k_base, as published. Nobody here has run it

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 自动布局），配隐形  注释做结构真源；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>）

What ships with it: 15 files

143.2 KB alongside SKILL.md, 1 of them executable

assets/