md-readable — Make Agent Output Readable

当 agent 输出变成一堵文本墙，你找不到信号在哪——这个 skill 把线性 Markdown 展开成可扫读的三层空间 HTML。每个字都在，什么都没压缩，只改变了组织方式。让你跟得上 agent 的思考，让对话继续推进。

核心原则

不压缩信息，重组信息。 这不是"摘要"工具。源 Markdown 的每个字都保留——唯一改变的是容器。

AI 用 3 秒生成 3000 字分析，人类需要 15-30 分钟阅读。这是 6 个数量级的编码成本不对称。这个 skill 建造一个中介层——将 Markdown 解析为三层空间架构，用 10 条跨领域第一性原则渲染为 HTML——让人类用 3 秒定位、选择性深入，而不是被强制按线性路径通读。

设计哲学：为什么三层架构是必要的

这是本 skill 区别于所有同类工具的根本。三层架构不是审美选择——它补偿了 AI 文本的三种结构性缺陷（来自认知科学和 HCI 研究）：

AI 文本的问题	认知原因	三层架构的补偿
意图缺位	LLM 产出是统计预测，缺乏人类作者对"包含什么/省略什么"的选择——选择 = 意图信号，读者默认每句话有目的	置信度标记 + SCQA 结构：用 Layer 1 替代缺失的意图信号——告诉读者"这个结论有多可靠""什么会推翻它"
可预测性疲劳	LLM 最大化文本平滑度，缺乏意外/转折/节奏变化，大脑无法维持注意力唤醒	前提标注 + 翻转条件 + 对比表：在 Layer 1 和 Layer 2 中主动暴露矛盾、不确定性、替代路径——打破平滑文本，创造认知张力
验证负担	读人写的东西默认信任，遇矛盾才验证；读 AI 必须全程同时理解+验证，争夺同一工作记忆	来源追溯 + Layer 3 验证层：每个主张标注来源和置信度，证据折叠在推理块内部——把"验证"从并行任务变成按需任务

三层架构不是把信息分成三堆——它是三种认知通道的同时激活（Peirce 符号学）：置信度用颜色（图像符号）+ 位置在顶部（索引符号=优先级）+ 标签文字（象征符号）。同一信息用三种方式编码，降低单通道的认知负载。

执行时牢记：你不是在美化 CSS——你在为 AI 文本注入意图信号、打破可预测性、降低验证成本。每个视觉决策都服务于这三个补偿。

什么时候该用 / 不该用

✅ 该用（三层完整模式）

3000 字以上的分析报告、研究产出、决策备忘录
有明确论证结构（前提→推理→结论）的文档
用户说"让我看看这个""这太密了""看不下去""生成 HTML""让这个可读"

⚠️ 走简洁模式

500-3000 字、论证结构不明显的文档
用户说"转成 HTML 看看""快速格式化"
跳过强制 SCQA，但保留推理块和设计系统

❌ 不该用——主动告知用户

输入类型	告知内容
500 字以下简短内容	"内容较短，HTML 转化收益不大。需要的话我仍可处理。"
纯叙事/故事/个人随笔	"叙事类内容依赖线性情感弧线，三层空间架构反而会破坏阅读体验。建议保持线性。"
API 文档 / 技术规范	"技术规范更适合搜索和交叉引用，而非空间化组织。建议用其他工具。"
纯数据表格（无论证）	"纯数据表格不需要 SCQA 结构。需要的话我用简洁模式处理。"

三层空间架构

这是本 skill 与所有同类工具的根本差异——不是模板套用，而是语义重组。

层	定位	读者时间	从 MD 中找什么
Layer 1 — 信号层	页面顶部，3 秒定向	≤10s	核心结论句、置信度表述、关键数字（≤3 个）、翻转前提
Layer 2 — 推理层	页面主体，选择性深入	2-15min	H2/H3 章节、论证段落、对比分析、推理步骤、表格
Layer 3 — 验证层	页面底部，默认折叠	按需	参考来源、文献引用、局限性、替代路径、注释

关键：Layer 2 所有内容必须保留。<details> 折叠是渐进披露的手段——<summary> 提供"信息气味"让读者在展开前知道里面有什么。

工作流

Step 0：校准（必须执行）

读取源 Markdown 全文
必须读取 references/design-system.md——这是 HTML 骨架和 CSS token 的唯一来源
判断模式：
- 文档 > 500 字 + 有论证结构 → 完整模式（SCQA + 三层架构）
- 文档 200-500 字或论证结构不明显 → 简洁模式（推理块 + 设计系统，不强套 SCQA）
- 文档 < 200 字 → 告知用户、询问是否继续
确定文档语言（中文 / 英文），UI 标签跟随源语言

Step 1：语义提取

边读边将内容归入三层。这是整个流程中最难、最重要的步骤。

Layer 1 — SCQA 提取：

元素	提取来源	要求
S (Situation)	开篇背景描述	1-2 句共识背景
C (Complication)	问题陈述、矛盾、变化	1-2 句制造张力
A (Answer)	核心结论	完整断言句，≤28 字（中文）
Metrics	关键数字/指标	1-3 个，每个带数字+标签
Premises	"如果…错了""前提是…"类表述	≤3 条，标明翻转后果

如果 MD 没有显式 SCQA 结构，从内容推断并在信号卡中标注"（推断）"。不要编造不存在的前提。

置信度判断：

高：多来源交叉验证、明确数据支撑、作者标注"高置信度"
中：有推理但缺实证、单一来源、作者标注"推断"/"可能"
低：纯推测、缺乏证据、作者标注"不确定"/"需要验证"

Layer 3 — 验证层收集：

参考来源（编号、名称、链接如可用）
局限性/边界条件
替代路径/方案
注释

Step 2：组件匹配（用决策启发式）

对 Layer 2 中每个章节，按以下规则匹配组件。这是控制输出质量的关键——不是主观审美，而是规则驱动。

推理块（默认容器）

每个主张一个推理块。构建规则：

断言标题：完整断言句，不是主题标签
- ✅ 前提→推理→结论的完整链条
- ❌ 关于 X 的分析
摘要：1-2 句，始终可见——给扫描者"信息气味"
置信度：高/中/低，左边框颜色编码
完整推理：放在 <details> 内，逐步展开
来源：折叠在推理详情内部

核心约束：

标题里出现"和"→ 拆成两个推理块（一容器一主张）
推理步骤嵌套 ≤ 3 层
展开按钮带信息气味：展开完整推理（3 个步骤 · 预计阅读 2 分钟）

视觉断点组件（何时用什么）

源文档出现	用这个组件	硬规则
A vs B 对比分析，≥3 个维度	对比表 `<table class="comparison-table">`	维度 < 3 个时用文字即可，不必上表
前提→推理→结论的明确 3 段式逻辑	推理链可视化 `<div class="inference-chain">`	3 个节点必须各有内容，不要为凑 3 个而拆分
≥2 条关键假设/前提列表	假设条件卡 `<div class="assumption-card">`	标注每条的反转风险
特别有洞见的陈述	关键引语 `<blockquote class="insight-quote">`	限制：每章 ≤ 2 条，多了就不"特别"了
连续 ≥ 3 个推理块等密度排列	视觉断点容器 `<div class="visual-break">`	断点内放上述任一组件，打破文本墙

内容节奏规则

不要连续 3 个以上推理块等密度且无视觉断点
每个章节 ≤ 6 个推理块（v3.0 侧边栏提供空间定向，单页可容纳更多章节，但每章内部仍需节奏控制）
第一个推理块最详细，后续可逐步加速
表格的"判断"列必须给出明确倾向（← 优），不要两边都说好
大型文档（>5000 字）：优先战略聚焦——将核心主张提炼为推理块，支持性数据（表格、列表、详细步骤）保持为章节内的结构化内容。目标：推理块承载"为什么"，结构化内容承载"是什么"

Step 3：组装 HTML

使用 references/design-system.md 中的完整骨架（v3.0 双列布局 + sticky 侧边栏）
按三层架构 + 组件匹配结果填充内容
添加侧边栏导航：所有 H2 章节链接放在 <aside class="sidebar"> → <nav class="sidebar-nav"> 中。桌面端 sticky 固定在左侧，移动端（≤900px）自动退化为 sticky 顶部横向 pills。侧边栏通过 IntersectionObserver 高亮当前章节，顶部固定进度条显示阅读进度
添加 footer（Agent 名、日期、原始 MD 链接）

输出路径：<MD 所在目录>/<MD 文件名（不含 .md）>.html

Step 4：自检（强制执行）

生成 HTML 后，必须逐项自查。 不要跳过这一步——这是质量保证的机制，不是可选的礼貌。

#	检查项	对应原则
1	每个推理块标题是完整断言句（不是"关于 X"）？	P1 断言优先
2	每个推理块只包含一个主张？标题里出现"和"→ 拆分	P2 一容器一单元
3	非关键信息放在折叠区？首屏只展示结论+摘要	P3 渐进披露
4	相关元素物理靠近，无关元素分离？	P4 空间编码
5	Squint Test：模糊后最显眼的 3 个元素就是最重要的 3 个？	P5 三层视觉层次
6	间距够用吗？够用的话——加倍了吗？	P6 留白是主动元素
7	强调色出现在 ≤ 2 个元素上？	P7 单色+一强调色
8	每个 CSS 规则都在传递信息？有没有纯装饰？	P8 信噪比
9	有没有连续 3+ 个推理块等密度？有 → 插入视觉断点	P9 内容节奏
10	任何间距/颜色/字号可以追溯到系统 token？	P10 系统性
11	重要信息不在右下角？	死区避免
12	展开按钮带信息气味标签？	App UI 智慧
13	推理步骤不超过 3 层嵌套？	认知负荷
14	正文颜色是 #333（不是 #000）？	中文排版
15	内容没有丢失？——对照原 MD 确认所有章节和推理都保留了	不压缩原则

未通过项 > 3 条 → 修改后重新自检。 特别是第 15 条——这是本 skill 的根本，不容妥协。

执行反模式

以下行为在 skill 执行过程中禁止。它们是工程层面的错误，不涉及视觉设计：

❌ 用多个小 Edit 调用来组装 HTML → 一次性在内存中构建完整字符串，然后一次 Write
❌ "改进"原文 → 不添加原稿中没有的信息、不修正原文的错误推理、不补充缺失的前提
❌ 翻译专有名词或代码标识符 → 文件名、变量名、产品名保持原文
❌ 对提取不出的 SCQA 强行编造 → 标注"（源文档未提供）"，不要造假
❌ 跳过短文档的自检 → 短文档也有设计问题
❌ 跳过 references/design-system.md 的读取 → CSS token 和骨架的唯一来源
❌ 在输出 HTML 中新增 <style> 块 → 所有样式必须来自 design-system.md 中的 CSS token
❌ 为长文档创建单一的、无限滚动的页面 → v3.0 侧边栏 + 进度条提供了持续空间定向，7-10 章节单页可行。但预估 HTML > 2000 行或推理块 > 15 个时，主动询问是否拆成子报告
❌ 将信息折叠到 <details> 中但 <summary> 不提供信息气味 → 每个折叠必须告诉读者里面有什么

设计禁止项（信噪比审计）

这些视觉做法在 HTML 输出中禁止。每一条都服务于一个明确的设计原则：

❌ 任何 gradient（渐变）— P8 信噪比：不传递信息的视觉元素即噪音
❌ border-radius > 12px — P8 + P7：圆角分散单强调色的焦点
❌ emoji 作为标题/CTA 装饰 — P8：emoji 是情绪标记，不是信息系统（置信度指示器例外）
❌ 3 列以上重复卡片布局 — P4 + P5：重复结构摊平视觉层次
❌ 加载外部字体或图标库 — P10：打破自包含性，引入外部依赖
❌ 过度阴影（最大 0 4px 12px rgba(0,0,0,0.08)）— P8：阴影是深度暗示，不是装饰
❌ 纯装饰的边框、分隔线、背景色 — P8：每个 CSS 规则必须传递信息
❌ 不在 spacing scale 中的任意 margin/padding 值 — P10：一切可追溯
❌ 不在 type scale 中的任意 font-size 值 — P10：一切可追溯
❌ 闪烁、脉冲、无限循环动画 — P8 + accessibility：分散注意力且影响无障碍
❌ 彩色背景（假设卡等语义例外除外）— P7：强调色只用于 ≤2 个关键元素
❌ 为不同推理类型使用不同颜色编码 — P7：额外颜色不增加信息，只增加噪音
❌ 重要内容放在右下角 — 视觉死区：F-pattern 扫描的终点是最低优先级区域

边界情况

边界	处理策略
源文档无标题	从文件名推断标题，不编造
源文档无显式 SCQA	从内容推断 S/C/A，信号卡标注"（推断）"
源文档 < 200 字	告知用户收益有限；如继续，走简洁模式，不必强行三层
源文档 > 5000 字	v3.0 侧边栏支持 7-10 个章节的导航。优先单页 + 战略聚焦（关键主张用推理块，支持性数据用结构化内容）。单页超 15 个推理块或预估 HTML > 2000 行时 → 询问是否拆成子报告
源文档已有 HTML 标签	提取纯文本内容，忽略已有样式
源文档的章节全是 H2 无 H3	推理块在 H2 章节内按段落逻辑拆分，不必强行制造 H3
输出路径已存在同名 .html	直接覆盖——md 是源，html 是可重新生成的产物
源文档内容类型不适合三层架构	见上方"不该用"表格——主动拒绝并告知原因
推理块内容极长（单块 > 500 字）	拆成 2 个独立推理块，各带自己的断言标题

参考资源

references/design-system.md — 完整 HTML 骨架、CSS Token 系统、组件模板。在 Step 0 校准阶段必须读取。

md-readable

SKILL.mdSKILL.md