Md Readable

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 研究）：

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

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

什么时候该用 / 不该用

✅ 该用（三层完整模式）

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

⚠️ 走简洁模式

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

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

三层空间架构

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

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

工作流

Step 0：校准（必须执行）

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

Step 1：语义提取

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

Layer 1 — SCQA 提取：

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

置信度判断：

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

Layer 3 — 验证层收集：

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

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

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

推理块（默认容器）

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

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

核心约束：

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

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

内容节奏规则

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

Step 3：组装 HTML

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

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

Step 4：自检（强制执行）

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

未通过项 > 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 扫描的终点是最低优先级区域

边界情况

参考资源

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