[teamai] Push 87 resource(s) from XingfenD

2026-09-10 16:10:45 +08:00
parent 425c9c078a
commit 65c04def51
1314 changed files with 211681 additions and 0 deletions
@@ -0,0 +1,42 @@
+# 文章类型路由
+
+文章类型是**结构决策**，主题是**审美决策**（见 `theme-selection.md`）—— 两者完全解耦。
+
+**文章类型与信息保留比例的关系**（重要）：理论上"内容保留是独立决策"，**但实践中两者
+绑定很紧**。每个类型都自带一个标配保留比例（见下表"推荐信息保留"列）。`longform + 20%` /
+`tutorial + 20%` / `briefing + 100%` 这类组合是**伪选项**：要么类型变形（briefing+100%≈full-report），
+要么内容空洞（longform 写出 8 章每章 2 段）。所以 Plan Checkpoint 1 把"保留比例"打包进"文章
+类型"的语义化选项里（见 SKILL.md Phase 3），**只在用户明确想精修**（如"longform 但只要 60%"
+= 一篇被深度编辑的长文）才作为非标配组合记入 plan.md。
+
+Phase 2 选定类型后，读对应 `article-types/<type>.md` 拿结构 / 组件 / Raw 边界 / 配图倾向 /
+自检。**非标配组合**要在 `plan/plan.md` Brief 段同时记下"标配 X% → 用户覆盖 Y%"，并让主 Agent
+在写每节时手动调整正文/视觉比例（不能照搬 article-types/<type>.md 的默认建议）。
+
+| 类型 | 推荐信息保留 | 用途 | 典型结构 | 详情 |
+|---|---|---|---|---|
+| `longform` | 100% | 完整长文、归档、深度阅读 | Hero / Lead / Summary / 多 Section / Raw 增强 / Conclusion | `article-types/longform.md` |
+| `full-report` | 80% | 研究报告、正式分析 | 执行摘要 / 背景 / 证据 / 数据 / 风险 / 结论 | `article-types/full-report.md` |
+| `tutorial` | 80-100% | 教学、步骤、上手 | 目标 / 步骤 / 示例 / 练习 / 总结 | `article-types/tutorial.md` |
+| `explainer` | 80% | 解释技术、系统、概念 | 问题 / 机制 / 图解 / 示例 / 常见误区 | `article-types/explainer.md` |
+| `dialogue` | 80% | 对话 / Q&A / 访谈 / 播客 / AMA | Hero / 嘉宾 / 多话题 Section / 关键观点摘要 | `article-types/dialogue.md` |
+| `review` | 60-80% | PR / 方案 / 事故 / 设计审阅 | 背景 / 发现 / 影响 / 建议 / 行动 | `article-types/review.md` |
+| `essay` | 60-80% | 观点、评论、叙事 | 开场 / 论点 / 例证 / 转折 / 收束 | `article-types/essay.md` |
+| `briefing` | 40-60% | 给忙人快速判断 | 结论先行 / 关键证据 / 取舍 / 下一步 | `article-types/briefing.md` |
+| `interactive-explainer` | ~25%（原文摘录占比，**非删 75%**） | **Raw 交互为主载体的"会用了再走"式学习页**（参考 3blue1brown / distill.pub / ciechanow.ski）。本质是**内容重构**：只摘核心知识点，其余 AI 围绕它们全新创作 | 每知识点：定义 / 交互演示 / 自己试 / 验证理解 | `article-types/interactive-explainer.md` |
+| `visual-essay` | 20-60% | 展示、传播、图文主导 | 少文字 / 大视觉 / 强节奏 / 章节短 | `article-types/visual-essay.md` |
+
+## 选型提示
+
+- 源材料信息密度高、要完整归档 → `longform`。
+- 源材料是消化后的报告 / 正式分析（执行摘要 + 数据 + 风险 + 建议四件套）→ `full-report`。
+- 要把一个机制 / 概念讲清楚（正文为主）→ `explainer`。
+- **要让读者"玩明白"一个概念**（Raw 交互为主，正文为辅，每知识点配交互演示）→ `interactive-explainer`。
+- 对话 / Q&A / 访谈 / 播客转录 / AMA → `dialogue`。
+- 评审某个 **工程** PR / 方案 / 事故 / 设计 → `review`。
+- 给决策者快速判断 → `briefing`。
+- 观点输出 / 评论 / 产品 / 书 / 论文评测 → `essay`。
+- 教别人上手做事（步骤 + 跑通）→ `tutorial`。
+- 传播 / 展示、图文主导 → `visual-essay`。
+
+类型只定**结构倾向**，不锁死信息密度和主题；用户可在 Plan Checkpoint 覆盖。
@@ -0,0 +1,32 @@
+# Article Type · briefing
+
+给忙人（决策者 / 同事 / 投资人）**快速判断**用。读者**不会读完全文**，所以每段都得帮决策。
+
+- **推荐信息保留**：40-60%（只留重点结论、关键证据、关键取舍、下一步；删一切铺垫 / 推导 /
+  背景 / 历史）。
+- **典型结构**：`Hero`（标题 = 一句话结论）→ `Summary`（**结论先行 + 3-5 个关键事实**，最重要
+  的一块）→ `Section`：关键证据 → 取舍 / 风险 → 下一步 / 行动项。**短而紧凑，整体阅读时间
+  控制在 3-5 分钟**。不必有 `Conclusion`（`Summary` 已经把结论说了）。
+- **组件选择**：仍 **prose-first**，正文短句直给（每段最好不超过 3 句）。`Summary` 是核心 ——
+  这是 briefing 的灵魂。其余按需：
+  - `Table`：确需 N 项并排对比时。
+  - `Decision` / `Tradeoff`：确有"X vs Y"取舍要展示时。
+  - `ActionList`：确有下一步要列时（谁做 / 何时做）。
+  - **不要因为是 briefing 就堆组件** —— briefing 贵在精简，组件多了反而显冗。
+- **Raw 边界**：少量但有力 —— 一个**关键对比图** / 趋势 / 选项矩阵 / 决策树；不堆视觉。
+  一篇 briefing 通常 0-2 块 Raw。
+- **配图倾向**：`none` 或**单张关键图**（数据图 / 关键截图）；偏 `tufte` 证据感或 `press`
+  简洁编辑感。
+- **主题倾向**：`tufte`（数据型 briefing）、`vignelli`（中性规格）、`press`（编辑节奏）。
+- **自检**：
+  - 30 秒内（只读 Hero + Summary）能抓到结论吗？
+  - 每段是否都在**帮决策**（这段删掉决策会受影响吗）？
+  - 有没有冗余展开 / 解释来由 / 历史背景 / "之所以这样"段落？
+  - 行动项是否可执行（谁做 / 何时做 / 怎么验收）？
+  - 整体阅读时间是否真的在 3-5 分钟？超过就不是 briefing 了。
+
+> **何时不要用 briefing**：
+>
+> - 要让读者**完整理解**而非快速判断 → `longform` / `full-report` / `explainer`。
+> - 评审某个具体产物 → `review`。
+> - 给读者**学懂**一个概念 → `explainer` / `interactive-explainer`。
@@ -0,0 +1,30 @@
+# Article Type · dialogue
+
+对话 / Q&A / 访谈 / 播客转录 / AMA / 圆桌。任何"多个声音轮流说话"的内容形式。
+
+- **推荐信息保留**：80%（删冗余口语 / 重复 / 寒暄，保留实质内容；不删观点也不改语气）。
+- **典型结构**：`Hero`（话题 + 嘉宾 + 主持 + 日期 / 来源）→ `Lead`（背景 / 为什么聊这个）→
+  多个 `Section`，每节一个话题或问题，正文用 **发言者明示 + 大量 `Quote`** 体现对话节奏 →
+  可选 `Summary` 放"关键观点摘要"在文章开头或结尾 → `Conclusion`（要点 / 延伸阅读）。
+- **组件选择**：
+  - 正文中**每段开头明示发言者**（如 `**A**：…` / `**主持**：…`），避免读者搞混；
+  - `Quote` 大量使用 —— 嘉宾的金句、原话、关键定义都用 Quote 抬出来；
+  - `Aside tone="principle"` 标定义 / 数据 / 概念解释；
+  - `Summary` 在开头放"3-5 个关键观点"，让快速读者也能拿到精华；
+  - 少用 `Table` / `CodeBlock`（对话很少有结构化技术内容；有时一律按嘉宾原话放代码段）；
+  - `Detail` 折叠可选的延伸 / 注释。
+- **Raw 边界**：可用 Raw 做**话题地图**（章节导航 / 时间线）、**关键概念可视化**（嘉宾解释了
+  什么机制就配一张 Raw 图解）、**金句卡片**；不要装饰性弹幕 / 动画头像。
+- **配图倾向**：`user-assets`（嘉宾头像 / 现场照片 / 提到的截图）或 `none`（纯文本对话）；
+  少用 `ai-generated` 氛围图。
+- **主题倾向**：`press`（出版编辑感，适合长对话 / 访谈）、`bodoni`（杂志感专访）、`freddie`
+  （活泼播客感）。
+- **自检**：
+  - 发言者归属清晰，不会让读者搞错"是谁说的"？
+  - 对话节奏保留？没有把它压成"单声音综述"？
+  - 关键观点能在 30 秒内从 Summary 抓到？
+  - 删减后嘉宾原意没有被改写 / 误传？
+  - 移动端发言者标记仍然清晰？
+
+> **未来扩展**：若 reacticle 组件库新增 `Dialogue` / `Speaker` 等专用对话组件，本类型应优先使用。
+> 当前实现用 `Quote` + 正文显式标注即可。
@@ -0,0 +1,31 @@
+# Article Type · essay
+
+观点、评论、叙事、评测（产品 / 书 / 论文 / 电影）、随笔、专栏、宣言。**观点驱动**的非
+虚构写作。
+
+- **推荐信息保留**：60-80%（保留论证链与最有力的例证；删旁枝、删冗长引用、删重复的换句话）。
+- **典型结构**：`Hero`（标题气质强）→ `Lead`（**抛出张力 / 矛盾 / 反直觉问题**，钩住读者）
+  → `Section`：开场 → 论点 → 例证 → 转折 → 收束。结构**服务叙事节奏，不必规整对称** ——
+  一篇好 essay 可以是 3 节也可以是 7 节，看节奏。
+- **组件选择**：正文是**绝对主体**；`Quote` 引名言 / 原话 / 反方观点；`Aside tone="aside"`
+  放旁注 / 个人评论 / 反方立场；**少用** `Table` / `RiskList` 等数据组件（会破坏叙事感）；
+  `Summary` 仅在长 essay 时用。
+- **Raw 边界**：偶尔一个有表现力的视觉停顿（节奏图 / 概念对比 / 情绪曲线），服务叙事而非
+  解释机制；密度低 —— 一篇 essay 通常 1-3 块 Raw 就够了。
+- **配图倾向**：`press` 暖色编辑摄影 / 插图 / 手稿；服务气氛但**不喧宾夺主**。评测型 essay
+  可用 `user-assets`（产品 / 书 / 电影截图）。
+- **主题倾向**：`press`（出版编辑型）、`bodoni`（专栏 / feature）、`andy`（柔软叙事）、
+  `sottsass`（活泼文化评论）。
+- **自检**：
+  - 是否有**一条清晰的论证 / 叙事线**？读者能否一句话复述这篇的核心观点？
+  - 例证是否有力？是否最少 2 个具体例子（而不是空泛论断）？
+  - 语气是否一致、像**人写的**（不是 AI 味、不是套路化展开）？
+  - Lead 是否真的"抛出张力"，而不是温吞地铺垫背景？
+  - 收束是否给读者留下点什么（不一定结论，可以是新问题 / 新视角）？
+
+> **何时不要用 essay**：
+>
+> - 评审**工程产物**（PR / 方案 / 事故）→ `review`。
+> - 给读者做决策 → `briefing`。
+> - 要把一个机制讲清楚 → `explainer`。
+> - 是对话 / 访谈整理 → `dialogue`。
@@ -0,0 +1,32 @@
+# Article Type · explainer
+
+解释一个机制 / 系统 / 概念 / 算法 / 协议。读者读完**真懂**这个东西怎么回事、为什么这样、
+何时用 / 不用。
+
+- **推荐信息保留**：80%（保留主要机制和关键细节，删重复 / 旁枝 / 历史背景；保留所有"关键
+  直觉"和"易错点"）。
+- **典型结构**：`Hero` → `Lead`（为什么要懂这个 / 不懂的代价）→ `Section`：问题 → 机制 →
+  图解 → 示例 → 常见误区 → 何时用 / 不用 → `Conclusion`。
+- **组件选择**：正文讲机制（**正文仍是主体**，不要拆成卡片堆）；`Aside tone="principle"`
+  点出"关键直觉 / 一句话本质 / 易错点"；`CodeBlock` 给具体示例；`Table` 对比方案 / 对比变种；
+  `Detail` / `Tabs` 折叠次要细节和深入推导；`Quote` 引原论文 / 规范原文。
+- **Raw 边界**：**鼓励多用解释性视觉** —— 机制流程、状态变化、数据流向、概念关系可用 Raw
+  自由层（HTML 布局 / 轻交互 / 动效 / 按需 SVG），让抽象概念可视、可对照；每块**服务一个
+  具体机制点**。Raw 是辅助而非主体 —— 如果你发现 Raw 承载了主要信息、正文变成了图注，那应
+  该考虑 `interactive-explainer`。
+- **配图倾向**：解释性视觉优先（Raw —— 交互 / 布局 / 动效 / SVG 均可）；需要真实界面 / 系统
+  截图时用 `user-assets`；少用氛围图。
+- **主题倾向**：`tufte`（技术 / 数据型）、`shannon`（系统 / 工程型）、`knuth`（学术型）、
+  `freddie` / `bayer`（面向新手的活泼型）、`fuller`（系统设计 / 协议型）。
+- **自检**：
+  - 读者读完是否**真懂**这个机制（不只是"知道有这个东西"）？
+  - 图解是否服务理解还是装饰？删掉是否影响理解？
+  - 常见误区是否覆盖（最容易踩的 2-3 个坑）？
+  - "何时用 / 不用"是否清楚？这是 explainer 与 longform 的关键差别。
+  - 长技术文章如果可以删 20% 仍能讲清，优先用 explainer；要原文归档用 `longform`。
+
+> **何时不要用 explainer**：
+>
+> - 要让读者**操作着学懂**（Raw 是主载体）→ `interactive-explainer`。
+> - 要让读者**跟着做出来一个东西** → `tutorial`。
+> - 源材料是论文 / 报告级别的完整论证 → `longform` / `full-report`。
@@ -0,0 +1,32 @@
+# Article Type · full-report
+
+研究报告、正式分析、技术评估、年度回顾、调研报告。源材料具备"执行摘要 + 关键发现 +
+数据 + 风险 + 建议"骨架，或可以被重组成这个骨架。
+
+- **推荐信息保留**：80%（消化原始材料后的报告化呈现；删冗余推导、扩展阅读、附录细节，
+  保留**执行摘要 / 关键发现 / 数据 / 风险 / 建议**四件套不动）。若用户的源材料就是报告原文
+  且要 100% 归档，覆盖为 100% 并按"非标配组合"在 `plan/plan.md` Brief 段记下。
+- **典型结构**：`Hero`（标题 + 报告期 / 范围 / 作者 / 单位）→ `Summary`（**执行摘要 / 关键
+  结论先行，必备**）→ `Section`：背景与方法 → 关键发现 → 数据与证据 → 风险与限制 → 建议与
+  下一步 → `Conclusion`（核心结论复述 + 决策建议）。**`TOC` 必开**。
+- **组件选择**：`Summary` 放"关键结论 + 关键数据"（让快读者 30 秒能拿到核心）；`Table` 承载
+  数据 / 对比；`RiskList` / `Decision` / `Tradeoff` 承载风险与取舍；`CodeBlock` / `Formula`
+  承载技术证据；`ActionList` 承载建议清单；正文承载论证过程。
+- **Raw 边界**：数据图、趋势、对比矩阵、风险热度图、依赖关系等用 Raw 自由层（HTML / CSS
+  图表与矩阵、轻交互、按需 SVG / canvas）；**保持证据感、低装饰**——避免动效抢戏，避免氛围
+  渐变色。
+- **配图倾向**：`none` 或真实数据图 / 报告截图（`tufte` 风）；**避免氛围图 / 配图打断阅读**。
+  如有产品截图，要服务一个具体结论。
+- **主题倾向**：`tufte`（数据型）、`knuth`（学术型）、`vignelli`（中性规格 / 标准化报告）、
+  `fuller`（系统设计 / RFC 风格）。
+- **自检**：
+  - 结论是否在文章开头 30 秒内能抓到？
+  - 数据 / 风险 / 建议是否齐全且有据可循（每条建议指向哪些发现）？
+  - 是否像一份**正式报告**而非营销页或长文随笔？
+  - `Table` / `RiskList` / `Decision` 等是因为内容是这样才用，还是为了"显得专业"硬塞？
+
+> **何时不要用 full-report**：
+>
+> - 源材料是连贯论证 / 叙事长文 → `longform`。
+> - 用户要的是"给老板看"的决策摘要而非完整报告 → `briefing`。
+> - 评审某个具体 PR / 方案 / 事故 → `review`。
@@ -0,0 +1,66 @@
+# Article Type · interactive-explainer
+
+把一篇长技术文章 / 论文 / 系统设计稿，**重构为以交互动画为主载体的"会用了再走"式学习页**。
+参考路径：3blue1brown 视觉化、distill.pub 的可调参数式机器学习解释、Bartosz Ciechanowski
+（ciechanow.ski）的"硬件原理可玩页"。
+
+> **与 explainer 的关键区别**：
+>
+> - `explainer`：**正文是主体**，Raw 是辅助插图。读者读完"知道了"。
+> - `interactive-explainer`：**Raw 是主体**，正文是简短引导和定义。读者**操作完**"会用了"。
+
+- **推荐信息保留**：~25%（**注意：这里的百分比不是"原文删了 75%"，而是"成品里直接来自
+  原文的句子 / 段落只占约 25%"**。本类型的本质是**内容重构** —— 从原文里**只摘**核心知识
+  点的关键定义、公式、数据、约束、易错点；其余 75% 由 AI 围绕这些知识点**全新创作**：引导
+  文字、直觉解释、交互演示、自己试、验证理解。原文的叙事铺垫、历史背景、案例展开、扩展
+  讨论**全部舍弃**，由交互替代。**不要把它当"删 50% 的 explainer"做**，那样既学不透也失去
+  本类型存在的意义。
+- **典型结构**：
+  - `Hero`（一句话定位：这页让你学懂什么 / 玩什么）
+  - `Lead`（前置：1-2 句话提示你需要哪些基础，玩完能做到什么）
+  - 可选 `Summary`（列出 N 个核心知识点作为路线图）
+  - 多个 **Concept Section**，每个一个核心知识点，节内三段式：
+    1. **定义 / 直觉**：1-3 段正文 + 一个 `Aside tone="principle"` 抬出一句话直觉。
+    2. **交互演示**（Raw 主体）：动画 / 滑块 / 拖拽 / 状态切换 / 参数变化的实时可视化。
+    3. **自己试 / 验证理解**（Raw 交互）：让读者动手试一个边界 / 反例 / 应用场景；可选一个
+       "答案揭晓"的折叠。
+  - `Conclusion`（知识点串联回顾 + 何时用 / 不用 + 延伸阅读）。
+- **组件选择**：
+  - 正文**短**：每节正文加起来通常不超过 200-400 字；
+  - `Aside tone="principle"` 标定义、关键直觉、易错点；
+  - `Detail` / `Tabs` 折叠次要细节、答案、推导；
+  - `Quote` 引原文 / 论文金句；
+  - 少用 `Table` / `CodeBlock`（如有，必须服务一个具体交互演示，不放整页代码）；
+  - `Raw` 是主角。
+- **Raw 边界（核心 · 必读）**：
+  - **每个 Raw 必须服务一个具体知识点**，不允许装饰性炫技。
+  - **操作性优先**：滑块 / 拖拽 / 切换 / 输入框 / 步进按钮；让用户**改变某个量**并**实时看到
+    结果**。比"看一段动画"更深。
+  - **状态可见**：当前参数、当前数值、当前阶段都要显式可见，不要藏在动画里。
+  - **可重置**：每个交互配"reset"或"恢复初值"，鼓励反复试。
+  - **样式走 token**：颜色 / 字体 / 间距用 `--ra-*`，不写野生 CSS。
+  - **错误示例同样有价值**：让用户拖到"会出错"的位置，配一行说明"为什么这里崩"。
+- **配图倾向**：`none` 优先（交互比图片更有信息量）；少量 `placeholders`（理论图 / 截图）；
+  避免 `ai-generated`（氛围图打断学习节奏）。
+- **主题倾向**：`tufte`（克制 + 数据感，适合 ML / 算法可视化）、`shannon`（暗底工程感，
+  适合系统 / 硬件交互演示）、`knuth`（学术克制，适合论文重构）；避免 `freddie` / `sottsass`
+  这类活泼配色（会让交互显得像游戏而非学习）。
+- **自检**：
+  - 读者玩完是否**真正会用**这个概念，而不只是"听过 / 看过"？
+  - 每个交互是否服务一个具体知识点？有没有炫技但学不到东西的 Raw？
+  - 没有交互的章节，是真的不需要交互，还是偷懒了？（这是判断本类型是否走样的关键问题）
+  - 移动端能不能操作？很多滑块 / 拖拽 / 复杂 SVG 在 mobile 上不能用 —— 必须在 Plan 阶段就
+    决定"是否放弃 mobile 交互" 还是"提供 mobile 替代展示"。
+  - 删掉所有 Raw 后，剩下的正文是不是太薄？太薄说明 Raw 没把信息装进去 —— 应该在 Raw 内或
+    紧邻位置补足。
+  - 成品里"直接来自原文的句子 / 段落"比例**确实在 ~25% 这个量级**吗？太高（>40%）说明你
+    在"删 explainer"而不是重构；太低（<10%）说明核心知识点没说清。
+  - **核心知识点筛选有据**：能否一句话说出"这页保留的 N 个知识点为什么是这 N 个"？随便挑
+    几个是这个类型走样的开端。
+
+> **何时不要用 interactive-explainer**：
+>
+> - 源材料是叙事 / 观点 / 评论（→ essay）。
+> - 源材料是步骤型操作（→ tutorial，步骤之间有先后依赖，不是知识点的并列）。
+> - 源材料是数据报告（→ full-report，结论比交互重要）。
+> - 你不打算写真正可操作的 Raw（→ explainer 即可，别假装 interactive）。
@@ -0,0 +1,32 @@
+# Article Type · longform
+
+完整长文、归档、深度阅读。这是**默认类型**。源材料是连贯论证 / 叙事 / 综述，且用户要原
+文级保留。
+
+- **推荐信息保留**：100%（原文关键内容不丢；只允许删除明显的重复段落和无信息的过场句）。
+- **典型结构**：`Hero` → `Lead`（导语，框定主题）→ 可选 `Summary`（TL;DR / 结论先行）→
+  多个 `Section`（必要时 `Subsection`）→ 关键概念处 `Raw` 增强 → `Conclusion`。长文（>10
+  小节或预估阅读 >15 分钟）开启 `TOC`。
+- **组件选择**：正文段落为**绝对主体**，应占文章绝大部分篇幅；`Aside` 点出关键直觉 /
+  历史注 / 反方观点；`Quote` 引用名言或原话；`Table` 承载二维数据；技术内容用 `CodeBlock` /
+  `Formula`。**不要把连贯段落拆成卡片堆** —— 卡片堆是 longform 最常见的走样形态。
+- **Raw 边界**：在关键概念、数据趋势、机制处插入 Raw 自由层（轻交互 / 自定义排版 / 动效 /
+  按需 SVG），给长文节奏与呼吸；每块服务具体段落，用 `--ra-*` token。Raw **是增强而非主体**
+  —— 如果开始让 Raw 承载主要信息，说明你应该考虑 `explainer` 或 `interactive-explainer`。
+- **配图倾向**：`none` / `placeholders` 优先；技术 / 证据型可用真实数据图（`tufte` 风）；
+  叙事型可加少量 `press` 风氛围图。
+- **主题倾向**：`tufte`（技术 / 证据型）、`knuth`（学术 / 论文）、`press`（叙事 / 综述）、
+  `bodoni`（专栏 / feature）。
+- **自检**：
+  - 正文是否仍是绝对主体？没有把段落拆成卡片堆？
+  - 章节衔接是否自然？读者读完一节会自然想读下一节？
+  - Raw 是点亮关键概念还是打断阅读节奏？
+  - 100% 信息是否读起来像被精修过的长文（而非原文搬运）？
+  - 长文有没有 `TOC` + `Summary` 帮助读者定位？
+
+> **何时不要用 longform**：
+>
+> - 源材料是消化后的报告（执行摘要 + 风险 + 建议四件套）→ `full-report`。
+> - 源材料是要解释一个机制 / 概念，可以删 20% → `explainer`。
+> - 源材料是论文 / 长文但你想做成交互学习页 → `interactive-explainer`。
+> - 给忙人看 / 要决策 → `briefing`。
@@ -0,0 +1,32 @@
+# Article Type · review
+
+**工程审阅**：PR / 方案设计 / 事故复盘 / 架构 / API / 安全审计。起点是审阅一份**具体产物**
+并产出意见与行动。
+
+- **推荐信息保留**：60-80%（保留关键发现 + 证据 + 行动；省略无关细节 / 上下文铺垫）。
+- **典型结构**：`Hero`（被评对象 + 评审范围 + 评审日期 / 评审人）→ `Summary`（**结论 /
+  评审意见先行**）→ `Section`：背景与目标 → 发现（逐条） → 影响评估 → 建议 → 行动项 →
+  `Conclusion`（核心判断 + 通过 / 待修 / 否决）。
+- **组件选择**：仍 **prose-first** —— 结论与发现先用正文 + `Summary` 讲清楚。下面是**领域
+  特例组件**，**只在内容确实是该结构时**按需取用，不要因为是 review 就全堆上：
+  - `RiskList`：确有一组需要分级的风险时。
+  - `DiffReview`：确有代码改动要逐行评时；代码一律用 `CodeBlock`。
+  - `Decision` / `Tradeoff`：确有"X vs Y"的取舍要展示时。
+  - `Incident`：事故复盘时的时间线。
+  - `ActionList` / `Checkpoint`：行动项 / 验收点确需结构化时。
+- **Raw 边界**：影响范围图、依赖关系、风险热度矩阵、调用链、监控曲线等用 Raw 自由层
+  （HTML / CSS 矩阵 + 热度、轻交互、按需 SVG）；**克制、证据优先、不抢正文**。
+- **配图倾向**：`user-assets` 真实截图 / diff / 监控图 / dashboard 截图（`tufte` 风）。
+- **主题倾向**：`tufte`（证据型 review）、`shannon`（暗底工程 / 事故复盘）、`fuller`（系统设计
+  / RFC review）、`vignelli`（中性规格型）。
+- **自检**：
+  - 评审意见是否在文章开头先行清楚（通过 / 待修 / 否决）？
+  - 每条发现是否有**证据支撑**（代码片段 / 截图 / 数据 / 日志），不是凭感觉？
+  - 建议与行动项是否**可执行**（谁做 / 何时做 / 怎么验收）？
+  - 起点是审阅一份**具体产物**？如果起点是"读者要做决策"，应该用 `briefing`。
+
+> **何时不要用 review**：
+>
+> - 评测**产品 / 书 / 论文 / 电影**（观点驱动，没有"通过 / 否决"二元判断）→ `essay`。
+> - 给老板做一份"该不该做 X"的决策摘要 → `briefing`。
+> - 完整的事后调研报告 → `full-report`。
@@ -0,0 +1,30 @@
+# Article Type · tutorial
+
+教学、步骤、上手指南、安装配置、迁移手册。读者**跟着做**就能跑通的内容。
+
+- **推荐信息保留**：80-100%（**步骤不能丢**，否则跟不下来；可删的只有冗长背景、可选的深入
+  扩展、不影响跑通的"为什么"段落）。
+- **典型结构**：`Hero` → `Lead`（学完能做什么 / 前置条件 / 预计用时）→ 可选 `Summary`
+  （整体路径鸟瞰）→ `Section`：每个阶段一节，节内 = 目标 → 步骤（逐步）→ 示例 → 验收点 →
+  常见坑 → 可选 `Section`：练习 / 扩展 → `Conclusion`（总结 + 下一步学什么）。
+- **组件选择**：`CodeBlock` 给每一步代码（**保真，可复制运行**）；`ActionList` /
+  `Checkpoint` 列步骤与验收点；`Aside tone="warning"` 标坑 / 注意事项；`Detail` 折叠可选的
+  深入解释 / 替代方案；`Table` 列参数 / 选项 / 配置项；`Tabs` 给多平台 / 多语言并列示例。
+- **Raw 边界**：流程图、状态变化（before / after）、UI 步骤示意、命令前后对照用 Raw 自由层
+  （HTML 步骤布局 / 轻交互 / 按需 SVG）；让步骤可视、可对照。**不必为每步都加 Raw** ——
+  代码 + 截图能讲清楚的就不加。
+- **配图倾向**：`user-assets` 优先（**真实截图**每个关键步骤）；纯命令行类教程可用 `none`。
+- **主题倾向**：`vignelli`（中性规格 / 文档感）、`freddie`（活泼上手）、`fuller`（系统配置 /
+  RFC 风格）、`tufte`（密度高的技术教程）。
+- **自检**：
+  - 照着做能否**真的跑通**？没有跳步 / 没有"省略号 …"假装代码？
+  - 步骤是否完整有序？每步都有验收点（怎么知道这步成了）？
+  - 代码是否可**直接复制运行**？不缺 import / 不缺环境说明？
+  - 常见坑是否标注（版本不匹配 / 权限不够 / 平台差异）？
+  - 移动端代码块能横滚不溢出？
+
+> **何时不要用 tutorial**：
+>
+> - 源材料是讲机制不是讲操作 → `explainer`。
+> - 想让读者**玩懂**而不是**做出来** → `interactive-explainer`。
+> - 源材料是 API 文档 / 完整规格 → 用 `longform` + 强 TOC，tutorial 不适合做参考手册。
@@ -0,0 +1,33 @@
+# Article Type · visual-essay
+
+展示、传播、图文主导、品牌叙事、年终回顾、文化评论。**视觉是主角**，文字短而精，节奏强。
+
+- **推荐信息保留**：20-60%（只留核心观点和最有力量的材料；大量删减叙事 / 推导 / 数据细节，
+  把保留下来的内容用视觉重新组织）。
+- **典型结构**：`Hero`（强气质 / 满版视觉 / 大字标题）→ 短 `Section` 串联，每节 = 少文字 +
+  大视觉 + 一句金句 → 节与节之间有**强节奏对比**（疏 / 密 / 明 / 暗）→ `Conclusion`（留白
+  收束 / 一句话点题）。**章节短** —— 每节阅读时间 30 秒到 1 分钟。
+- **组件选择**：正文用**短句、断行**；`Quote` 做金句停顿（不引名言，而是把文章里的"狠话"抬
+  出来当节标记）；`Image` / `Raw` 是主角；**少用密集数据组件**（`Table` / `RiskList` 会破
+  坏视觉节奏）。
+- **Raw 边界**：**视觉块占比最高** —— 大尺度版面、节奏图、概念可视化、动效、轻交互（HTML
+  / CSS / React，按需用 SVG / canvas）；可以做**满版背景**、**滚动触发动效**、**多列错位
+  排版**等。但**仍必须是文章形态** —— 不是 landing page、不是产品 dashboard。
+- **配图倾向**：`ai-generated` / `user-assets` **大图**；构图 / 留白 / 排版本身就是表达；
+  避免 stock photo 和"商务握手"类俗图。
+- **主题倾向**：`bodoni`（黑白大刊）、`press`（暖色编辑）、`sottsass`（活泼彩色）、`bayer`
+  （现代主义 / 海报感）、`andy`（柔软叙事）。气质强的主题在这个类型里效果最好。
+- **自检**：
+  - 是否仍是一篇**文章**而非海报 / landing page / dashboard？（删掉所有视觉后，剩下的文字
+    能否串成一个观点？能 = 文章；不能 = landing page）
+  - 视觉是否服务**核心观点**而非纯装饰 / 炫技？
+  - 节奏是否有呼吸（疏密对比 / 明暗对比 / 大小对比）？
+  - 删减后是否仍像"被编辑过的文章"而非"缩水的摘要"？
+  - 移动端是否仍能传达核心观点（很多大版面在 mobile 上会塌）？
+
+> **何时不要用 visual-essay**：
+>
+> - 给读者做决策 → `briefing`。
+> - 让读者完整理解 → `longform` / `explainer`。
+> - 让读者**操作着学懂** → `interactive-explainer`（也是视觉主导，但读者要动手）。
+> - 要传达完整论证 / 数据 → `essay` / `full-report`。
@@ -0,0 +1,71 @@
+# 配图与素材策略
+
+配图必须服务文章，不是装饰。Phase 2 把配图策略与逐图计划写进 `plan/plan.md` 的
+**Assets** 段（见 `plan-template.md`），**不再产出独立的 `asset-plan.md` 文件**。
+
+## 与 Raw 正交：配图策略只管 Image，不管 Raw（铁律）
+
+**配图策略 = 是否使用外部 `Image`，以及用哪种来源。它与 `Raw` 完全正交，不是二选一：**
+
+- **`Raw` 始终存在**，是每篇文章默认的表现力层（任意 HTML / CSS / JS / React：交互、
+  自定义布局排版、动效、小工具，以及按需的 SVG / canvas 图解），不受配图策略影响，也永远
+  不需要用户"开启"。
+- **`Image` 是独立的可选叠加层**，由配图策略决定是否使用、用哪种来源。
+- 选 `none` **不等于**"用 Raw 替代 Image" —— 它只表示"不使用外部图片"，`Raw` 照常使用。
+
+> 别把它框成 "Image vs Raw"。正确心智是："Raw 一定有；Image 要不要、用哪种来源，由用户在
+> Plan Checkpoint 明确选定。"
+
+## 四种来源模式（只针对 Image）
+
+| 模式 | 说明 | 适合情况 |
+|---|---|---|
+| `user-assets` | 用户提供截图 / 照片 / 图表 / 素材目录 | 产品文章、代码审阅、真实报告 |
+| `placeholders` | 先用占位图或图片位说明 | 用户稍后补素材 |
+| `ai-generated` | AI 按文章和主题生成图片提示词 | 视觉文章、概念解释、封面图 |
+| `none` | 不使用外部图片（`Raw` 自由层 / 表格不受影响，照常使用） | tufte 风、技术分析、证据型文章 |
+
+**不主动生成 AI 图片**：`ai-generated` 必须用户显式选择。但即便选 `none`，也不影响 `Raw`。
+
+## Asset Checkpoint 必问（Plan Checkpoint 内 · 必须让用户选，不能默认通过）
+
+配图模式是**必选项**，不允许用一个默认值一笔带过。先一句话说明"Raw 照常使用"，再让用户
+从四种 **Image** 来源里明确选一种：
+
+```text
+配图模式（这一项只决定是否使用外部 Image；Raw 自由层 —— 交互 / 布局 / 动效 / 图解 —— 不受影响，照常使用）。
+请从以下四种里选一种：
+- none：不使用外部图片，靠正文 + Raw + 表格表达（推荐给技术 / 证据型文章）。
+- user-assets：你提供素材目录或截图，我据此排版。
+- placeholders：先放占位图，我在 plan.md 的 Assets 段标注每张图应替换成什么。
+- ai-generated：我先生成配图提示词，等你确认后再生成图片。
+我的推荐：<策略>，原因：<一句话>。你确认或改成别的？
+```
+
+## ai-generated 提示词原则
+
+选 `ai-generated` 时**不直接随意生成图片**，先在 `plan/plan.md` 的 Assets 段列出每张图：
+位置 · 服务的段落 / 论点 · 目的 · 主题风格 · 构图 · 禁止项 · 提示词 · 备选提示词。
+
+示例：
+
+```text
+Image 01
+位置：Hero 背景
+目的：建立"技术出版物"气质，不解释具体机制
+主题：press
+风格：warm editorial still life, paper texture, low saturation
+禁止：3D icon, neon gradient, SaaS stock photo, smiling office people
+Prompt: Warm editorial photograph of a desk with annotated technical notes,
+printed code snippets, a graphite pencil, soft morning light, low saturation,
+refined book-publishing mood, no screens, no logos.
+```
+
+## 图片自检（每张图）
+
+- 是否服务文章中的具体位置？是否符合选定主题 `theme-profiles/<id>.md` 的媒体风格？
+- 是否不是纯装饰？是否不会抢正文？是否没有和 Raw 表达重复？
+- 是否有 caption / source / alt 文本？
+
+配图自查并入 Plan 自查（5 条之一："Raw / 图片有目的"）—— 由主 Agent 内联完成，
+**不再单独开 Asset Reviewer SubAgent**。详见 `review-checklist.md` 的 Plan 自查段。
@@ -0,0 +1,103 @@
+# 组件使用政策（reacticle 协议）
+
+文章用 `reacticle` 组件协议写：**不手写裸 `div` / `className` / 行内 `style` / CSS**。
+结构走语义组件，正文走段落，自定义视觉走 `Raw`。从包入口导入：
+
+```tsx
+import { ThemeProvider, Article, Hero, Lead, Section, Aside, Table, Raw } from "reacticle";
+```
+
+## 核心规则（始终适用）
+
+1. **Prose-first，组件按需，Raw 自由。**
+   - **正文是主体**：普通段落写成 `Section` 的 children，应占文章绝大部分。
+   - **语义组件是点睛，只在内容确实"是"那个结构时才用**：`Summary` / `Aside` /
+     `Quote` / `Table` / `RiskList` / `Decision` 等。不要堆叠当装饰 —— 堆卡片会让
+     文章显得做作、零碎。litmus test：若一句话 / 一个列表 / 一张表 / 一块 Raw 读起来
+     更好，就用那个。
+   - **Raw 相反：鼓励多用。** 交互、动画、自定义可视化、新颖排版 —— Markdown 做不到的
+     东西，才是把文章从"能读"变成"值得读"的关键。Raw 不打断阅读，它给密集文本节奏与
+     呼吸。
+2. **表达语义，不表达布局。** 说"这是 insight / risk / decision"，别说"蓝卡片、24px 边距"。
+3. **Props 即协议。** 填齐必填字段；确实没有就留空 —— 组件会渲染显式的 `⚠ 未指定xxx`
+   标记，让缺口可见。**绝不为掩盖缺口而编造。**
+4. **主题，不写样式。** 作者只通过 `ThemeProvider` 选一个主题，从不写组件样式。
+5. **始终用 `<ThemeProvider theme="...">` 包住 `<Article>`。**
+6. **版式与主题解耦。** `Article` 的 `width`（`narrow` / `regular` / `wide` / `full`，默认
+   `regular`）决定阅读列宽，`toc`（默认在本 Skill 开启）决定是否有左侧目录 —— 都按内容选、
+   经 Plan Checkpoint 确认，**不由主题决定**。详见 `references/layout.md`。
+7. **一个 Section = 一个文件。** 每个 Section 必须是独立组件（`article/sections/NN-*.tsx`），
+   **坚决不允许**把多个 Section 写进一个组件；`Article.tsx` 只做组装（assembler）。这是
+   多 Agent 并行开发的前提，详见 `references/section-build.md`。
+
+## 组件分两层：默认核心 + 领域特例
+
+**默认核心组件（绝大多数文章只用这些 + 正文 + Raw）：**
+
+- 结构：`Article`、`Hero`、`Lead`、`Section`、`Subsection`、`Conclusion`、`TOC`
+- 观点：`Summary`、`Aside`、`Quote`
+- 数据：`Table`
+- 技术：`CodeBlock`（写代码**只用它**）、`Formula`
+- 媒体：`Image`
+- 自由层：`Raw`
+
+**领域特例组件（仅当内容"确实是"该结构时按需取用，不要因为属于某类文章就全用上）：**
+
+- 决策 / 审阅：`RiskList`、`Decision`、`ActionList`、`Checkpoint`、`Tradeoff`、`Incident`
+- 代码评审：`DiffReview`
+- 交互壳：`Detail`、`Tabs`
+- 富媒体：`Video`、`Audio`
+
+> **不要暴露给作者**：`HighlightedCode` 是 `CodeBlock` 的内部底层，写代码一律用
+> `CodeBlock`，不直接使用 `HighlightedCode`。
+
+选组件前先过 litmus test（规则 1）：若正文 / 列表 / 表格 / Raw 读起来更好，就不要为了
+用组件而用组件。领域特例组件每多用一个，都要能回答"这块内容本质上就是它"。
+
+完整组件 API（属性、用法）见组件库本身的 reference：
+`skill/references/{structure,insight,structured,decision,technical}.md`（reacticle-authoring
+skill），按需读取，不要一次全读。
+
+## 使用原则
+
+- 正文是主体。组件是语义，不是装饰。
+- Raw 是文章表现力，不是应用开发入口（边界见 `raw-policy.md`）。
+- `Table` 负责二维信息；`Image` 负责真实或生成配图；`Raw` 是自由的 Web 层 —— 任意
+  HTML / CSS / JS / React：交互、自定义布局排版、动效、嵌入小工具，以及按需的图解（SVG /
+  canvas），SVG 只是其中一种手段，不是默认。
+- **`Raw` 与 `Image` 正交，不是二选一**：`Raw` 始终默认存在、照常使用；`Image` 是否使用、
+  用哪种来源由 Plan Checkpoint 的配图策略决定（见 `references/asset-policy.md`）。选配图
+  `none` 只表示不用外部图片，`Raw` 不受影响。
+
+## 信息密度与组件比例
+
+见 `information-density.md`：100% 时长文优先、Raw 点亮关键概念；密度越低，视觉块比例
+越高，但**仍必须保持文章形态**。
+
+## 最小骨架（注意比例：大量正文 + 一个点睛组件 + 一块 Raw）
+
+```tsx
+import { ThemeProvider, Article, Hero, Lead, Section, Aside, Raw } from "reacticle";
+
+export function Article_() {
+  return (
+    <ThemeProvider theme="tufte">
+      <Article>
+        <Hero title="标题" subtitle="副标题" meta={[{ label: "日期", value: "2026-06-08" }]} />
+        <Lead>导语，框定主题。</Lead>
+        <Section index="01" title="第一节">
+          <p>正文段落用 children —— 这应是文章主体，尽量多写正文。</p>
+          <p>再写一段，把背景、推理、结论用文字讲清楚。</p>
+          <Aside tone="principle" label="核心判断">一句话的核心判断。</Aside>
+          <Raw title="为本段现写的内联 SVG">
+            <svg viewBox="0 0 240 60" width="100%">
+              <polyline points="0,50 40,42 80,46 120,20 160,28 200,8 240,14"
+                fill="none" stroke="var(--ra-color-accent)" strokeWidth="2" />
+            </svg>
+          </Raw>
+        </Section>
+      </Article>
+    </ThemeProvider>
+  );
+}
+```
@@ -0,0 +1,208 @@
+# 文章封面（Cover）—— 设计指南
+
+## 这是什么
+
+每篇 Beautiful Article 在 TOC + 正文之上有一块**像书的封面**的题图，独占顶部。
+它是 HTML 文章"出版物感"的开篇 —— 类似书封 / 杂志封面 / 唱片封套：
+一眼传达 "**这篇讲什么 + 长什么气质**"，决定读者会不会往下看。
+
+封面**不**是 Hero：
+
+| 角色 | Hero | Cover |
+|---|---|---|
+| 位置 | `<Article>` 内、TOC 旁 | `<Article>` **之外**、TOC **之上** |
+| 形态 | 标题 + 副题 + meta（文字栏） | 3:4 图文构图（图 + 字） |
+| 职责 | 框定主题 + 读者收获 | 视觉钩子 + 风格定调 |
+| 信息 | 文字为主 | **图主字辅** |
+
+两者**互补**：封面引人，Hero 锚定。**不要把它们做成同一件事**。
+
+---
+
+## 尺寸 · 屏幕 3:4 一屏看全 / PDF 独占首页
+
+- **屏幕**：`aspect-ratio: 3 / 4`，宽度同时受**两条上限**约束（取较小者），保证
+  3:4 完整封面**一屏看全、不用下拉**：
+    1. `48rem`（768px）—— 硬上限，再大就像广告牌而不是书封；
+    2. `calc((100vh - 8rem) * 3 / 4)` —— 从视口高度反推的宽度，给顶栏 / 容器
+       边距 / 上下呼吸留 8rem (128px)。
+
+  也就是 `max-width: min(100%, 48rem, calc((100vh - 8rem) * 3 / 4))`。在矮屏幕上
+  封面自动缩小（仍是 3:4），在 1024px 以上的高屏幕上保持 768×1024。
+- **PDF**：`@media print` 默认保持屏幕版 3:4 构图，并在封面之后分页，让封面独占
+  PDF 首页。不要依赖通用 `height: 100vh` 把封面强行拉成整页；Chromium print 对
+  复杂封面内部布局的裁切行为不够稳定。
+
+为什么是 3:4 而不是 A4 比例（1:√2 ≈ 0.707）：
+
+| 比例 | 数值 | 感觉 |
+|---|---|---|
+| 16:9 | 1.78 | 太宽，像横幅 / banner |
+| A4 (1:√2) | 0.707 | 偏瘦，像报告内页 |
+| **3:4** | **0.75** | **像书封 · A4 和 Letter 的中间值** |
+| 2:3 | 0.667 | 像小说封面 · 偏窄 |
+
+3:4 在 A4 PDF 上下方有约 4% 白边；在 Letter PDF 上下方约 3% 白边。默认保留这
+些比例差异，换取 PDF 输出稳定。
+
+**给设计者的影响**：默认 PDF 不会改变封面比例，但内部布局仍应自适应：用百分比 /
+`aspect-ratio` / `inset: 0` / `grid` / `flex` 撑起元素，**不要把任何元素的位置写死
+成绝对像素**，否则不同视口和打印缩放下仍可能错位。
+
+---
+
+## 硬约束（5 条 · 不可妥协）
+
+1. **3:4 屏幕 + PDF 独占首页（外壳不要动）**。`Cover.tsx` 的 `aspectRatio: "3 / 4"` 和
+   max-width / margin / border 不要改 —— `pdf-print-overrides.css` C 段只负责让封面
+   之后分页。**内部元素一律用百分比 / 相对单位**，不要写绝对 px 高度。
+2. **图文并茂**。**禁止纯文字封面**。必须同时具备：
+   - **视觉主体**（什么技术都行，见下）；
+   - **文字层**：至少一个标题，可加一行副题、一个小标签（type / date / kicker）。
+3. **主题忠实 · 只能用 `--ra-*` token**。颜色 / 字号 / 字重 / 边框 / 圆角 / 间距全部通过
+   `var(--ra-color-fg)` `var(--ra-color-accent)` `var(--ra-text-3xl)` 等取值。
+   **禁止**：写死 hex 颜色、写死字体名、写死像素字号 —— 切主题封面就废。
+4. **内容忠实**。封面的视觉主体要呼应**正文主旨**（不是泛泛装饰）。读完封面，
+   读者要能猜出文章在讲哪个领域 / 哪种判断。比如：
+   - 文章讲"提示词缓存就是一切" → 封面可以是**缓存命中率曲线 / 重复 token 的高亮带**；
+   - 文章讲"Codex 智能体循环" → 封面可以是**带箭头的循环图（USER → MODEL → TOOL）**；
+   - 文章讲"色彩冲撞" → 封面可以是**两个互补色块的几何拼贴**。
+5. **offline-first**。**唯一被硬禁的事**：远程图片（`<img src="https://...">`、
+   Google Fonts 动态加载、跨域 CSS background-url 等）—— 离线打不开。
+   **base64 raster** 仅当 Plan Checkpoint "配图模式" 是 `user-assets` / `ai-generated`
+   才允许，且必须内联。
+
+---
+
+## 视觉技术 · 模型自己选，效果好就行
+
+封面的视觉主体**用什么技术由你（模型）决定** —— SVG / CSS / Canvas / WebGL / 字体 / 表情符号
+/ 复杂 React 组件 / mask / clip-path / filter / 多层合成 / 任意混搭。**没有"首选"**，只
+有"对这篇文章 + 这个主题，哪种最对味"。
+
+可选技术（不全，能想到的都可用）：
+
+- **内联 SVG**：网格 / 曲线 / 节点-边图 / 流程箭头 / 矢量插画 / pattern fill / mask；
+  优势是任意尺寸清晰、`currentColor` 自动跟主题。
+- **CSS 几何 / gradient / clip-path / backdrop-filter**：分屏色块、玻璃感、光感、
+  抽象排版；适合海报感 / 平面设计感的封面。
+- **`<canvas>` + JS**：粒子 / 流体 / 噪声 / 程序化纹理 / 字符 ASCII art；
+  适合数据 / 科技 / 生成艺术气质。注意：Canvas 在 PDF 里只会渲染**初始帧**，所以
+  动画类要保证"第一帧本身就是好看的最终态"。
+- **复杂 React 组件**：完全自定义的布局，比如用 grid + 条件渲染做一面"目录式封面"、
+  用 React 重排标题字符做字体艺术。
+- **字体 / 排版本身就是图**：超大字号、字距 / 行距实验、字符叠加、emoji 拼贴、
+  Unicode 几何字符 (`◐ ▲ ◆ ╳`)、引号 / 章节号放大到布满整页。
+- **多层合成**：背景层（gradient） + 中层（SVG） + 前景层（文字） + 装饰层（图标 / 标签）。
+- **混搭**：上面任意几种叠在一起。封面是单次创作，没必要拘泥单一技术栈。
+
+**唯一不允许**：远程图片（见硬约束 5）。其它**全开放**。
+
+**判定标准**：眯眼看 3 秒（图 OK 吗？气质对吗？切主题不会废吗？打印不会错位吗？）。
+通过这 4 关，技术怎么实现都行。
+
+---
+
+## 构图模板（按主题感选一个起手）
+
+| 模板 | 视觉布局 | 适合主题感 |
+|---|---|---|
+| **A · 上字下图** | 标题区在上 1/3，视觉主体占下 2/3（书封最经典的"片名 + 主画面"） | 教学 / 报告 / 多数场景 |
+| **B · 大字盖图** | 视觉铺满整个 3:4，超大字标题压在中段或下段 | bodoni / press · 印刷 / 叙事 |
+| **C · 上下分屏** | 上半色块（含标题） + 下半视觉主体；中间一条分割 | tufte / shannon · 数据 / 严谨 |
+| **D · 满屏拼贴** | 视觉是若干色块 / 形状 / 图层拼接铺满整页，文字嵌在某个块里 | sottsass / bayer · 当代 / 视觉感 |
+| **E · 极简框** | 大留白、细线框、标题居中、一个极小的视觉锚点（一个圆 / 一个图标 / 一段曲线） | 极简主题 / 严肃报告 / 哲思 |
+
+**不要混搭** —— 一篇文章一个模板。模板只是"起手"，具体怎么实现（用 SVG / CSS /
+Canvas / React 还是别的）由你定。
+
+---
+
+## 主题倾向（速查）
+
+读 `theme-profiles/<id>.md` 获得权威风格指南；下面是"封面起手"提示（**视觉手法只是
+启发，不是规定** —— 你可以用任何技术做出对的气质）：
+
+| 主题 | 封面感觉 | 推荐模板 | 视觉手法举例 |
+|---|---|---|---|
+| tufte | 学术 / 克制 / 数据 | C 或 E | 极细线网格 + 一个小型 sparkline / 数据点；颜色低饱和 |
+| press | 报刊 / 叙事 / 凝重 | B 或 E | 大字标题 + 横分割线 + 印章式 kicker；可加铜版画感纹理 |
+| shannon | 信息论 / 工程 / 蓝调 | A 或 C | 节点-边图 / 香农式信道图 / 概率分布 |
+| bodoni | 古典 / 优雅 / 印刷 | B | 高对比 serif 大标题 + 极细 hairline 装饰 + 留白 |
+| bayer | 包豪斯 / 几何 / 排版 | D | 三原色块拼贴 + 圆 / 方 / 三角组合 |
+| sottsass | 后现代 / 玩味 / 明亮 | D | 撞色色块 + 装饰图案 + 大胆字体 |
+| fuller | 测地 / 科技 / 结构 | A 或 D | 三角网格 / 等距投影 / 工程图样 |
+
+没列到的主题 → 读它的 `theme-profiles/*.md` 决定模板。
+
+---
+
+## 反面案例（**禁止**）
+
+- **纯文字封面**（只有标题居中，没有视觉主体）。
+- **使用远程图片**（`<img src="https://...">`、`background-image: url(https://…)`）—— 离线打不开。
+- **写死颜色 / 字体 / 像素值**（`color: #ff0066` / `font: 24px Helvetica`）—— 切主题废。
+- **位置写死成 3:4 时的绝对像素**（`top: 384px`）—— 换视口或打印缩放就错位。
+- **复制 Hero 内容到封面**（标题、副题、日期、作者全堆封面里）—— 与 Hero 重复。
+- **塞过多元素**（封面里同时塞下：标题 + 副题 + 三个小标签 + meta + Lead + TOC 预览 +
+  大插画 + 二维码）—— 信息密度爆炸，不像封面像 dashboard。
+- **内部元素溢出容器**（让 absolute 子元素跑出 3:4 边界）—— PDF 会被裁切。
+- **封面承担正文**（把第一段干货塞封面里）—— 封面是钩子不是内容。
+- **Canvas 动画依赖时间才出现内容**（PDF 只截第一帧，黑屏）—— 保证第一帧自身就好看。
+
+---
+
+## 自检（**必过 5 条**）
+
+写完封面，对照下面 5 项；任何一项 fail → 改完再交付：
+
+1. **图文并茂**：截掉文字层后还剩视觉主体？截掉视觉层后还剩文字？两者都要有。
+2. **主题忠实**：切到 `theme-profiles/index.json` 里另一个主题（改 `main.tsx` 一行），
+   封面**自动跟随**变色 / 变字、不破相？如果有写死值就不算过。
+3. **内容忠实**：盯着封面看 5 秒钟，能不能猜出文章在讲什么？如果只能看到"一个漂亮
+   图形"但跟正文关系不大，不算过。
+4. **比例自适应**：把容器从 3:4（屏幕）拉成 ~3:4.2（A4）/ ~3:3.9（Letter），内部元素
+   没溢出 / 没错位 / 没出现大块空白？（用 `position:absolute; inset:0` + `grid`
+   / `flex` 撑起元素，而不是写死像素位置，就自动通过）。
+5. **不与 Hero 重复**：封面文字 ≠ Hero 文字（一个是钩子，一个是锚点）。
+
+---
+
+## PDF 表现
+
+`scripts/pdf-print-overrides.css` 的 C 段会把封面：
+
+- **保持封面的 3:4 外壳不变** —— 避免 Chromium print 在强拉伸时裁切内部布局；
+- **`break-after: always`** —— TOC 从第二页开始。
+
+效果：PDF 第一页 = 3:4 封面独占首页；第二页起 = TOC + 正文。
+
+> **想做满页封面**：可以在单篇文章里为 `.ra-cover` 加专门的 print 适配，但必须导出
+> PDF 目检。不要把满页拉伸作为通用默认值。
+
+---
+
+## 何时关闭封面（`--no-cover`）
+
+99% 的场景都该开。少数关闭的情况：
+
+- **briefing**（决策摘要 / 给忙人看）：用户希望"打开就是干货"，封面反而是阻力。
+- **dialogue**（对话 / 访谈）：内容是对话流，封面价值不大；可关。
+- **用户明确要关**：尊重用户。
+
+关闭方法：
+- 脚手架阶段：`bash scripts/scaffold.sh <dir> --theme=<id> --no-cover`。
+- 已脚手架：删 `article/main.tsx` 里 `<Cover />` 引入和渲染，可顺手删 `Cover.tsx`。
+
+---
+
+## 写作流程（在 Skill 里的位置）
+
+| 阶段 | 跟封面相关的事 |
+|---|---|
+| Phase 2 Plan | `plan/plan.md` Brief 段里加一行"封面：开/关 + 一句构图想法 + 主题模板（A/B/C/D/E）" |
+| Phase 3 Checkpoint 1 | 第 5 项独立确认"封面 · 开 / 关"，AI 推荐通常是"开" |
+| Phase 4 First Spread | **替换 `article/Cover.tsx` 里的 `<CoverPlaceholder />`** 为本文专属设计；首屏验收必看封面 |
+| Phase 4 First Spread Review | Reviewer 用本文档自检 5 条核对 |
+| Phase 6 Final Review | Visual Reviewer 复查封面与主题一致性 |
+| Phase 8 Delivery | PDF 导出时封面自动独占首页（不需要额外操作） |
@@ -0,0 +1,35 @@
+# Harness 视角
+
+本 Skill 的重点不是"提示词"，而是一个小型 harness。它要回答六个问题：
+
+| Harness 部分 | 本 Skill 解决的问题 | 设计手段 |
+|---|---|---|
+| 上下文管理 | 模型到底看到了什么 | 原始源统一转 `source.md`，阶段化读取 reference |
+| 工具系统 | 能处理什么输入 / 输出 | URL / PDF / DOCX / Markdown / 截图 / 图片素材 / 本地构建 / 浏览器检查 |
+| 执行编排 | 下一步该做什么 | 分 Phase、检查点、首屏样张、完整生成、验收修复 |
+| 状态与记忆 | 决策如何跨步骤保持 | `source.md`、`plan/plan.md`（Brief/Outline/Theme/Assets 四段合一）、`review/first-spread-review.md`、`review/final-review.md` |
+| 评估与观测 | 怎么知道文章好不好 | Plan 主 Agent 内联自查；First Spread / Final 用 SubAgent + 写文件；Section 用 SubAgent + 消息返回 |
+| 约束与恢复 | 跑偏后怎么修 | 最小切片修复，禁止整篇无脑重写 |
+
+## 状态文件是长期记忆
+
+Agent **不应依赖聊天上下文记住关键决策**。跨阶段决策落盘到下列文件 —— 比原先精简了 ~5 份：
+
+```text
+source/source.md             # 统一后的源材料（原始语言，事实底座）
+source/source.<lang>.md      # 仅当需翻译：地道翻译版，作为后续编写的事实底座
+source/extraction-notes.md   # 抽取风险 / 丢失 / 待补充 / 语言与翻译说明
+plan/plan.md                 # 唯一规划文件：Brief / Outline / Theme / Assets 四段合一
+review/first-spread-review.md  # First Spread SubAgent 结论（首屏验收依据）
+review/final-review.md         # 终审三视角结论（交付物的一部分）
+review/source-review.md        # 仅复杂/低置信源时
+review/repair-log.md           # 仅有修复时
+```
+
+
+长会话中如果不确定某个已确认的决策，**回读这些文件**，不要凭记忆重新发明。
+
+## 一句话定位
+
+> Beautiful Article 把素材编辑、设计成一篇美丽的网页文章；它首先是一篇**文章**，
+> 不是网页应用。交互、Raw、配图都服务阅读。
@@ -0,0 +1,42 @@
+# HTML 输出与构建
+
+工作区是一个 Vite + React + TS 项目，从 npm 消费 `reacticle`（最新发布版）。文章源在
+`article/Article.tsx`（由 `article/main.tsx` 挂载，主题在此固定）。
+
+## 命令（在工作区根目录）
+
+| 命令 | 作用 |
+|---|---|
+| `npm run dev` | 启动预览（Phase 4 / 5 边写边看）。 |
+| `npm run build` | `tsc --noEmit` 类型检查 **+** 构建自包含单页 HTML 到 `dist/index.html`（CSS + JS 内联）。TS 报错会让构建失败，避免错误漏进交付物。 |
+| `npm run html` | 复用 `npm run build`（含类型检查），再把单页 HTML 复制到 `article/article.html`（**交付物**）。 |
+| `npm run typecheck` | 仅类型检查。 |
+
+单文件由 `vite-plugin-singlefile` 产出：CSS + JS 全部内联，**断网可打开、可分享**。
+
+## 切换主题
+
+主题在 `article/main.tsx` 的 `<ThemeProvider theme="...">` 改一个字即可（必须是组件库
+已注册的 runtime theme id：`tufte` / `press`）。
+
+## PDF（可选 · 由 Checkpoint 3 触发）
+
+详见 `references/pdf-output.md`。一句话用法：
+
+```bash
+npm run html                                                   # 先有 article/article.html
+bash <path-to-beautiful-article>/scripts/html-to-pdf.sh        # → article/article.pdf
+```
+
+脚本会自动探测系统的 chromium-family 浏览器，在 HTML 头部注入 `@media print` 覆盖（把
+TOC 从左右栅格塌成上下排布，TOC 独占首页），再 headless 打印为 PDF。无 npm 依赖、无 Node。
+
+> Raw 交互在 PDF 里只能渲染为初始态。`interactive-explainer` 类型 PDF 价值有限，用户可在
+> Checkpoint 3 自行决定要不要导。
+
+如需"复制为提示词 / 行动项"按钮，可在文章里挂 `ExportBar`（与 PDF 无关）。
+
+## 交付自检
+
+- `npm run html` 成功，`article/article.html` 能在浏览器离线打开。
+- 控制台无报错；桌面与移动端都可读，无文字溢出 / 遮挡 / 空白异常。
@@ -0,0 +1,50 @@
+# 信息密度
+
+信息密度（信息保留比例）决定**正文与视觉块的配比、内容取舍的尺度、章节深度**。
+
+**与文章类型的关系**：理论上两者独立，实践中绑定很紧 —— 每个文章类型都自带一个标配保留
+比例（见下表）。Plan Checkpoint 1 把"保留比例"打包进"文章类型"的语义化选项里收集，避免
+`longform + 20%` 这种伪组合（详见 `article-types.md` 顶部说明）。**只在用户明确精修**（如
+"longform 但只要 60%"）时作为非标配组合记入 `plan/plan.md` Brief 段。
+
+默认值：**100% 信息保留**（跟随默认类型 `longform`）。
+
+## 信息密度等级
+
+| 信息保留 | 推荐文章类型 | 适合场景 | 表达特征 |
+|---|---|---|---|
+| 100% | longform | 完整归档、原文级深度阅读 | 长文为主，Raw 增强，完整章节和细节 |
+| 80-90% | tutorial / full-report / explainer / dialogue | 教学步骤 / 消化后的报告 / 概念解释 / 对话整理 | 删冗余但保留主要论证、步骤、对话 |
+| 60-70% | review / essay | 工程审阅 / 观点评论 | 留核心证据、论证、关键发现 |
+| ~50% | briefing | 给决策者看 | 留结论 + 关键证据 + 行动；视觉比例升高 |
+| 40% | visual-essay | 分享、传播、图文展示 | 视觉块占比最高，文字更短，强调节奏 |
+| **~25%（原文摘录）** | interactive-explainer | 玩懂一个概念（Raw 交互为主载体） | **特例：百分比含义不同** —— 不是"删 75%"，而是"成品里直接来自原文的句子 / 段落约占 25%"；其余 75% 是 AI 围绕核心知识点全新创作的引导文字 + 交互演示 + 自己试 + 验证理解 |
+| 20% | one-page teaser / 封面式表达 | 引导阅读、封面 | 只留核心观点和最有力量的材料（任何注册类型 + 20% 都属"非标配组合"，要在 plan.md 标注） |
+
+## 信息密度与组件 / 视觉比例
+
+| 信息保留 | 正文比例 | Raw / 图片比例 | 组件策略 |
+|---|---|---|---|
+| 100% | 高 | 中低 | 长文优先，Raw 点亮关键概念 |
+| 80% | 中高 | 中 | 每节可有一个视觉增强 |
+| 60% | 中 | 中高 | 重点结构化，视觉辅助理解 |
+| 40% | 中低 | 高 | 图文节奏更强，但仍是文章 |
+| 20% | 低 | 高 | 接近视觉文章，不保留细节 |
+
+## 三个维度的关系
+
+```text
+文章类型 = 结构决策
+信息密度 = 内容保留决策   ← 与类型实际绑定（每类有标配比例），仅在用户精修时解耦
+主题     = 审美气质决策   ← 与前两者完全解耦
+```
+
+- 主题与类型 / 密度**完全解耦**：任意主题都能在任意类型 + 密度下成立（表现策略不同而已）。
+- 类型与密度**实践绑定**：见 SKILL.md Phase 3 的合并问题；只有"non-standard"组合时才显式解耦。
+
+## Plan Checkpoint 必问
+
+1. 文章类型（含标配信息保留比例）—— 见 SKILL.md Phase 3，4 个必问题之一。
+2. 是否允许编辑删减、重组、改写语气？—— 默认允许，开场说明里明示。
+3. 哪些信息必须 100% 保留？—— 写进 Brief 段"必须保留的信息"列表。
+4. 哪些内容可以压缩或移除？—— 写进 Brief 段"可删减的信息"列表。
@@ -0,0 +1,46 @@
+# 版式：宽度模式与 TOC
+
+版式是**与主题解耦的独立决策**（主题只管审美气质，宽度/目录管阅读版式），就像信息密度
+与主题解耦一样。在 Plan Checkpoint（Phase 3）由用户确认，落盘到 `plan/plan.md` 的 Brief 段。
+
+## 宽度模式（`Article` 的 `width`，需 reacticle ≥ 0.2.0）
+
+宽度由 `<Article width="...">` 控制，**不再由主题决定**。四种常见模式：
+
+| 模式 | 阅读列宽 | 适合 |
+|---|---|---|
+| `narrow` | ~34rem | 聚焦短文、`essay`、`briefing`、金句节奏强的文章 |
+| `regular`（默认） | ~46rem | `longform` / `explainer` 等常规长文阅读 |
+| `wide` | ~58rem | 表格 / 代码 / 数据密集（`full-report`、`review`、`tutorial`） |
+| `full` | ~78rem | 图文主导、宽幅媒体（`visual-essay`） |
+
+任意主题都能配任意宽度（解耦）。例：`tufte + wide` 适合大量数据表；`press + narrow`
+适合从容随笔。
+
+## TOC（`Article` 的 `toc`）
+
+`<Article toc>` 渲染左侧目录（从 `Section` / `Subsection` 自动派生，最多三级，带滚动高亮）。
+
+- **本 Skill 默认开启 TOC**（长文有导航更易读），但**必须在 Plan Checkpoint 让用户确认**。
+- 很短的文章（`briefing` / 短 `visual-essay`）可以关掉，避免目录比正文还显眼。
+- TOC 开启会变成"左目录 + 正文"两栏；窄视口（<1000px）自动回落为单栏。
+
+## 用法
+
+```tsx
+// 默认：常规宽度 + 开 TOC
+<Article toc width="regular"> ... </Article>
+
+// 数据密集报告：更宽 + TOC
+<Article toc width="wide"> ... </Article>
+
+// 短随笔：窄列、不要目录
+<Article width="narrow"> ... </Article>
+```
+
+## 自检
+
+- 宽度是否匹配内容？（表格 / 代码多 → 至少 `wide`；纯叙事 → `regular` / `narrow`）
+- 宽度是按内容选的，而不是被主题决定的？
+- TOC 的开关是否经用户确认？短文是否误开了喧宾夺主的目录？
+- 移动端两栏是否正常回落为单栏？
@@ -0,0 +1,208 @@
+# PDF 输出（可选）
+
+把交付的单页 HTML（`article/article.html`）转成 PDF。**这是 Phase 8 Delivery 里的可选步骤**，
+由 Checkpoint 3 用户选 "通过 · 同时导出 HTML + PDF" 时触发；不选则不动。
+
+> HTML 仍然是主交付物：它能离线打开、可分享、可在浏览器里完整体验 Raw 交互。PDF 是给"需要
+> 归档 / 打印 / 邮件附件 / 不联网阅读"场景的补充，**Raw 交互在 PDF 里只能渲染为初始态**。
+
+---
+
+## 快速用法
+
+```bash
+# 工作区根目录
+npm run html                                                    # 先确保有 article/article.html
+bash <path-to-beautiful-article>/scripts/html-to-pdf.sh         # 默认 article/article.html → article/article.pdf
+bash <path-to-beautiful-article>/scripts/html-to-pdf.sh in.html out.pdf  # 自定义路径
+```
+
+也可以把这个 bash 调用放到工作区 `package.json` 的 scripts 里，让用户 `npm run pdf` 就跑
+（路径是用户机器上 Skill 的绝对路径，**不在脚手架模板里固化**，避免硬编码）。
+
+---
+
+## 前提条件
+
+本机已装 chromium-family 浏览器之一（脚本会自动探测，按下列顺序）：
+
+```text
+chromium / chromium-browser / google-chrome / google-chrome-stable / chrome
+brave-browser / microsoft-edge
+/Applications/Google Chrome.app/...
+/Applications/Chromium.app/...
+/Applications/Microsoft Edge.app/...
+/Applications/Brave Browser.app/...
+/Applications/Arc.app/...
+/usr/bin/chromium / /snap/bin/chromium
+```
+
+**找不到任何浏览器** → 脚本不会爆，会给出回退指引：注入了打印 CSS 的临时 HTML 路径会被
+打印出来，用户可以用任意浏览器手动 `Cmd+P` / `Ctrl+P` → "另存为 PDF"。
+
+不依赖 Node / npm 包 / puppeteer / playwright / weasyprint —— 故意只用系统已装的浏览器，
+零环境配置。
+
+---
+
+## 设计原理（重要 · 调样式前先读）
+
+### 1. 为什么要注入 print CSS（不是改 reacticle）
+
+reacticle 的 TOC 在桌面是**左右栅格**（`.ra-article-layout--with-toc` 是 `display: grid`，
+两列：TOC | 文章），在 mobile（≤999px）才塌成单列 `display: block`。
+
+PDF 阅读习惯是**上下排布**（TOC 先 / 正文后），跟 mobile 体验对齐。最干净的实现：在 PDF
+生成时**注入一段 `@media print` CSS**，强制 `display: block`，等价于复用 mobile 分支。
+这样：
+
+- **不动 reacticle**：任何版本的 reacticle 都能用这个脚本生成合理 PDF。
+- **不动用户的 Article.tsx**：用户的源码完全不受影响。
+- **CSS 只在打印生效**：浏览器里看 HTML 还是左右栅格。
+
+### 2. 注入了哪几条规则
+
+CSS 抽到了独立文件 **`scripts/pdf-print-overrides.css`**（与脚本同目录），分三组：
+
+```text
+A · TOC 排版（让 TOC 上 / 正文下）
+  A1) .ra-article-layout--with-toc { display: block }   → 塌成单列
+  A2) .ra-toc { position: static; page-break-after: always } → 解 sticky + 独占首页
+  A3) .ra-toc__list { column-count: 2 }                 → 长 TOC 双列省纸
+  A4) .ra-toc__item { break-inside: avoid }             → TOC 项不被列间撕开
+  A5) .ra-article-layout--with-toc > .ra-article        → 正文在 TOC 后自然流
+  A6) .ra-toc a / .ra-article a { text-decoration: none } → 关闭打印链接下划线
+
+B · 分页行为（修长文章的大块空白页）
+  B1) .ra-section / .ra-subsection { break-inside: auto !important }
+        → 撤销 reacticle print.css 里的 break-inside: avoid-page。
+          对长 Section 来说，那条规则会把整节推到下一页、留前一页大半空白。
+  B2) h1-h4 + .ra-section__head + .ra-subsection__head { break-after: avoid }
+        → 标题不被孤儿化（不会孤零零卡在页底，下面是空白）
+  B3) .ra-hero / .ra-lead / .ra-conclusion { break-inside: avoid }
+        → 短的开场 / 收束块原子化，不撕开
+  B4) p / li / blockquote { orphans: 3; widows: 3 }
+        → 段落不留 1-2 行寡行
+  B5) figure / .ra-table / .ra-codeblock / .ra-formula / .ra-image / .ra-raw
+        { break-inside: avoid }
+        → 图表、表格、代码块、Raw 块尽量整块；过高时浏览器仍会自动 fallback 分页
+
+C · 封面（若文章有 3:4 封面，让它独占 PDF 首页）
+  C1) .ra-cover { break-after: always; break-inside: avoid }
+        → 屏幕和 PDF 都保持 3:4 书封；打印时 TOC 从第二页开始
+        → 详见 references/cover.md
+```
+
+完整带注释的 CSS 直接看 `scripts/pdf-print-overrides.css`。要调样式（比如换页面 break 策略
+/ 改双列阈值 / 加打印水印），**直接改这个文件就行**，不用动 bash 脚本。
+
+> **为什么 CSS 是独立文件**：macOS 自带 BSD awk 对 `-v inject="$INLINE_CSS"` 这种多行字符串
+> 报 `newline in string` 错（GNU awk 没事）。把 CSS 抽成文件，awk 用 `getline < file` 读取，
+> 两个 awk 都吃得下。顺带也让 CSS 变成可独立编辑 / lint / diff 的真正资源。
+
+reacticle 自带的 `print.css` 仍然生效（白底黑字 / 隐藏 export bar / `break-inside: avoid`
+等），本脚本只补 TOC 排版那一块。
+
+### 3. 渲染流程
+
+```
+article.html  ──── awk 注入 print CSS ────  /tmp/article-print.html
+                                                  │
+                                                  ▼
+                  探测的浏览器 --headless --print-to-pdf
+                                                  │
+                                                  ▼
+                                          article.pdf
+```
+
+Chrome 标志：
+
+- `--headless=new`（旧版 fallback 到 `--headless`）：无窗口模式。
+- `--no-pdf-header-footer` / `--print-to-pdf-no-header`：去掉浏览器自带的 URL / 日期 / 页码
+  （颠倒了 colophon 的角色）。
+- `--virtual-time-budget=5000`：给页面 JS 5 秒初始化时间，让 Raw 组件、KaTeX、Prism 等
+  渲染完再截屏。
+- `--hide-scrollbars` / `--disable-gpu` / `--no-sandbox`：清洁渲染。
+
+### 4. Raw 交互在 PDF 里会怎样？
+
+PDF 是**静态文档**，所有 Raw 交互（滑块、按钮、动画、canvas、视频）只能渲染**初始状态**。
+设计建议：
+
+- **interactive-explainer 类型**：PDF 价值有限（核心是"操作"），用户可在 Plan 阶段不开
+  PDF 导出。
+- **其它类型**：Raw 通常是辅助图解（流程图 / SVG / 趋势图），初始态已经够看，PDF 没问题。
+- **Raw 内的内容若依赖 hover / click 才显示**：在写 Raw 时考虑"是否打印友好"，如默认露出
+  关键内容、用 `print:` 风格让 hover 状态在打印时强制展开。
+
+---
+
+## 故障排除
+
+### 找不到浏览器
+
+脚本会打印临时 HTML 路径（已经注入打印 CSS），手动 Cmd+P 即可。
+
+### PDF 里 TOC 没分页 / 跟正文挤在一起
+
+某些 Chromium 旧版本对 `page-break-after: always` 的支持有差异。可以：
+
+- 升级 Chrome 到当前主版本。
+- 或手动 Cmd+P 时在打印对话框选"两面 / 缩放 / 自定义边距"。
+
+### PDF 分页奇怪 / 出现大块空白页 / 标题孤零零卡在页底
+
+通常是某些"原子块"被强制不分页导致整块被推到下一页。检查 `pdf-print-overrides.css`：
+
+- **B1** 是否生效（看 DevTools Print Preview 里 `.ra-section` 的 `break-inside` 值）。
+  reacticle `print.css` 那条没 `!important`，理论上我们的 `!important` 一定能赢。
+- 自己写的 **Raw 块**里有没有 inline `style={{ breakInside: 'avoid' }}` 或类似 CSS —— 删掉。
+- 如果还想"标题永远不卡页底"，把 B2 里 `break-after: avoid` 改成
+  `break-before: avoid; break-after: avoid`（更激进，但偶尔会牺牲一些纸面利用率）。
+
+### PDF 里 Raw 没渲染完整 / 图表是空白
+
+- 增加 `--virtual-time-budget`（编辑脚本，从 5000 改到 10000+）。
+- 检查 Raw 的 JS 是否在 DOMContentLoaded 内同步渲染（异步加载的远程图片 / 数据可能没等到
+  截屏就开拍）。
+- 改造 Raw：用 SSR-friendly 的初始态 + 客户端 hydrate 增强，不要"完全靠 JS 后才能看"。
+
+### PDF 字体跟浏览器看不一样
+
+主题用了 `@font-face` 远程字体？headless Chrome 默认不等远程字体加载完。可以：
+
+- 用 system font fallback（推荐，多数主题已经做了）。
+- 或在 HTML 里把字体 `data:` 内联（vite-plugin-singlefile 已经处理静态资源，但 woff 字体
+  要看主题怎么写的）。
+
+### 想自定义页面留白 / 纸张大小
+
+Chromium 的 `--print-to-pdf` 不支持命令行页面尺寸 / 边距参数。当前 CSS 用
+`@page { margin: 0 }` 让主题纸色铺满整页，再用 `.ra-root { padding: 0.45in }`
+提供内容留白。如果需要改留白，优先调整 `scripts/pdf-print-overrides.css` 里的
+`.ra-root` print padding。
+
+如果用户真的要自定义，建议：
+
+1. 用浏览器 GUI 打印（Cmd+P）—— 那里有边距 / 纸张 / 缩放选项。
+2. 或者派生一个 `html-to-pdf-puppeteer.sh` 脚本，单独支持自定义。当前脚本默认按 Chrome
+   默认页面尺寸（Letter 美区 / A4 其它区）输出。
+
+---
+
+## 与 Skill 流程的关系
+
+| 阶段 | 触发 | 动作 |
+|---|---|---|
+| Phase 8 Delivery | 用户在 Checkpoint 3 选 "通过 · 同时导出 HTML + PDF" | 跑 `npm run html` → 跑 `bash <skill>/scripts/html-to-pdf.sh` → 交付 `article.html` + `article.pdf` |
+| Checkpoint 3 其它选项 | 用户选 "通过 · 导出 HTML 交付" | 不跑 PDF |
+| 用户事后想补 PDF | 任何时刻 | 在工作区根目录手动跑 `bash <skill>/scripts/html-to-pdf.sh` |
+
+---
+
+## 不做的事
+
+- ❌ 不在脚手架强行装任何 PDF 相关 npm 包（保持脚手架轻量）。
+- ❌ 不在 Checkpoint 3 默认勾选 "导出 PDF"（PDF 不是主交付物）。
+- ❌ 不替用户判断"要不要 PDF" —— 这是 Checkpoint 3 用户独立选择项。
+- ❌ 不改 reacticle 来支持 PDF（CSS 注入更轻量、跟 reacticle 版本解耦）。
@@ -0,0 +1,109 @@
+# plan.md 模板（单一规划文件）
+
+Phase 2 **只产出一份** `plan/plan.md`，四段：**Brief / Outline / Theme / Assets**。
+**不直接写 HTML**。写完后由主 Agent 内联跑 5 条自查（见 `review-checklist.md` 的 "Plan
+自查"），按结论改 `plan/plan.md` 本身，**不开 SubAgent、不写任何 review 文件**，然后进入
+Checkpoint 1。
+
+> 为什么合并：原先四份文件（editorial-brief / outline / theme-decision / asset-plan）真正
+> 跨阶段被读取的只有"信息保留比例 / 目标语言 / 章节锚点 / 主题 id"。合并成一份后，主 Agent
+> 维护更省心，Section subagent 只需打开 plan.md 找到"Outline"段里自己的章节即可。
+
+---
+
+## `plan/plan.md` 完整模板
+
+```markdown
+# Plan
+
+## Brief
+
+- 目标读者：<谁会读，带着什么问题>
+- 目标语言：<跟随源语言（默认） / 指定语言>。若指定且与源不一致：源语言 <X> → 目标 <Y>，
+  事实底座用翻译版 `source/source.<lang>.md`（地道、去翻译腔）
+- 文章类型：<longform / full-report / tutorial / explainer / dialogue / review / essay / interactive-explainer / briefing / visual-essay>
+- 信息保留比例：<X%>（默认走类型标配：longform=100% · tutorial=90% · full-report=80% ·
+  explainer=80% · dialogue=80% · review=70% · essay=70% · briefing=50% · visual-essay=40% ·
+  **interactive-explainer=~25%（特例 · 见下）**；用户偏离标配则写实际值并加一行"非标配组合
+  · 注意事项"，提醒主 Agent 在写每节时手动调整正文/视觉比例）
+- **interactive-explainer 特例说明**：这个比例的含义和其它类型不同 —— 不是"原文删了 75%"，而是
+  "成品里直接来自原文的句子 / 段落约占 25%"；其余 75% 是 AI 围绕核心知识点全新创作的引导文字
+  + 交互演示 + 自己试 + 验证理解。本质是**内容重构**而非内容压缩。
+- 必须保留的信息：<章节 / 表格 / 代码 / 数据 / 引用，逐条列；指向 source.md 的具体位置>
+- 可删减的信息：<重复 / 旁枝 / 过时内容；每条带理由>
+- 语气：<克制分析 / 出版叙事 / 决策汇报 / 教学>
+- 主要观点：<这篇要让读者记住的 1-3 个判断>
+- 阅读目标：<读完能做什么 / 知道什么>
+- 版式宽度：<narrow / regular / wide / full>（默认 regular，见 layout.md）
+- TOC：<开 / 关>（默认开）
+- 配图策略：<none / user-assets / placeholders / ai-generated>
+- 封面：<开（默认） / 关>。若开，写一句构图想法 + 选定的封面模板（A 左字右图 / B 大字盖图 /
+  C 上字下图 / D 几何拼贴 / E 极简框）+ 主视觉用什么（如"SVG 缓存命中率曲线"/"包豪斯三色块"）。
+  详见 `references/cover.md`。Brief 阶段一句话即可，正式视觉在 Phase 4 First Spread 替换
+  `article/Cover.tsx` 时落定。
+
+## Outline
+
+- Hero：<标题气质 / 副标题 / meta：日期·来源·作者>
+- Lead：<导语，框定主题，1-2 句>
+- Summary：<是否需要；放结论先行 / TL;DR>
+
+### Sections
+
+1. <编号 NN> <标题>
+   - 保留信息：<从 source.md 哪几段，要保留到什么程度>
+   - 需要的组件：<Section 正文 + 是否 Aside/Quote/Table/CodeBlock/Formula/Image>
+   - 是否需要 Raw：<是/否；若是，服务哪个论点、表达目的>
+2. ...
+
+- 结尾方式：<Conclusion / 行动项 / 留白收束>
+
+## Theme
+
+- 选定主题：<tufte / press / ...>
+- 理由：<为什么是它，结合源材料类型 / 语气 / 配图策略>
+- 与源材料的冲突：<若有，如何处理；若无，写"无">
+- 当前信息密度下的表现建议：<正文 / Raw / 图片比例如何调整；可引用 theme-profiles/<id>.md>
+
+## Assets
+
+> 这一段配合"Brief / 配图策略"使用。`none` 模式下写一句话即可。
+
+- 策略：<none / user-assets / placeholders / ai-generated>
+- 一句话说明：<为什么是这个策略；Raw 始终存在、不在本段讨论>
+
+### 逐图计划（仅 user-assets / placeholders / ai-generated 模式需要）
+
+每张图列：
+
+- 位置：<Hero 背景 / Section 02 之后 / ...>
+- 服务的段落或论点：<...>
+- 目的：<建立气质 / 解释机制 / 提供证据 / ...>
+- 主题：<选定主题>
+- 风格 / 构图：<...>
+- 禁止项：<3D icon / neon gradient / SaaS stock photo / 笑脸办公室人 / ...>
+- 来源：<user-assets 文件路径 / placeholders 描述 / ai-generated 提示词>
+- 备选提示词（ai-generated 模式）：<...>
+```
+
+---
+
+## 模板使用要点
+
+- **Outline 是章节锚点**：Section subagent（开发模式 B 下）会读这一段找到自己负责的章节。
+  每节用 `<编号 NN> <标题>` 起头，编号要和最终 `article/sections/NN-*.tsx` 一致。
+- **必须保留 / 可删减**列出来不是装饰，**Section Reviewer 会核对**信息保留比例是否兑现。
+- **Theme 段不必长**：通常 3-5 句话足够。冲突的处理才是这段的真正价值。
+- **Assets 段在 `none` 模式下极短**：一句话说明"不使用外部图片，靠正文 + Raw + 表格表达"
+  即可，不需要逐图计划。
+
+## 与其它 reference 的关系
+
+- 文章类型选择：见 `article-types.md` → `article-types/<type>.md`。
+- 信息保留比例：见 `information-density.md`。
+- 主题选择：见 `theme-selection.md`，结论落到本模板的 **Theme** 段。
+- 版式宽度 / TOC：见 `layout.md`，结论落到本模板的 **Brief** 段。
+- 配图四种来源 / ai-generated 提示词原则：见 `asset-policy.md`，结论落到 **Assets** 段。
+- 封面（书封式题图：屏幕 3:4 / PDF 独占首页）：见 `cover.md`，结论落到 **Brief** 段的
+  "封面"一行；正式视觉在 Phase 4 First Spread 写 `article/Cover.tsx` 时定稿。
+- 自查清单：见 `review-checklist.md` 的"Plan 自查（5 条）"。
@@ -0,0 +1,86 @@
+# Raw 政策
+
+Raw 是 Beautiful Article 的关键表现力，但必须受**主题**和**文章性**约束。写 Raw 前先读
+选定主题的 `theme-profiles/<id>.md` 的 Raw 风格。
+
+## Raw 是完整的 Web 平台，不是"画 SVG"
+
+**Raw 里可以写任意 HTML / CSS / JS / React 组件 —— 整个 Web 平台都在你手里。** SVG 只是
+**其中一种**手段，绝不是默认或唯一。别把 Raw 想成"内联画图"，那会严重限制网页的想象力。
+按"哪种媒介最能讲清这一段"自由选择，例如：
+
+- **交互**：拖动条 / 切换 / 折叠 / 步进器 / 计算器 / 小型可调模型 / 假设演算。
+- **布局排版**：并排对比、时间线、卡片网格、分栏、引文大字、特殊标题节奏（用 HTML + CSS）。
+- **动效**：CSS transition / `@keyframes` / 滚动揭示 / 状态切换的动画。
+- **数据可视**：HTML/CSS 条形与热度、`<canvas>`、需要时才用 `<svg>` 折线 / slopegraph。
+- **嵌入与组合**：表格 + 控件 + 文本拼成的一次性小工具、可复制片段、对照面板。
+
+判断只问一句：**哪种实现最能服务这一段的理解 / 论证 / 节奏？** 用那个，而不是反射性地画 SVG。
+
+## 核心心法
+
+- **为 THIS 篇文章手写，不是 widget 库。** 每块 Raw 都应为它旁边的段落即时发明：写 token
+  成本？现写一个小拖动条；写两套方案？拼一个并排对照面板；写体积趋势？才考虑一条内联折线。
+  **绝不**把 Raw 做成一套固定小组件在文章间复用（同一条 pipeline / 同一套配色到处出现）——
+  那等于把自由层退化成又一组受限组件。
+- **自由但一致：用 token。** Raw 内部随便写 —— 任意 HTML / React 组件、`<style>` 与
+  `@keyframes`、行内样式、`<canvas>`、按需的 `<svg>`、一次性小交互 —— 但颜色 / 字体 / 间距
+  必须取自主题变量（`var(--ra-color-accent)`、`var(--ra-font-body)`、`var(--ra-space-4)` …），
+  这样每块都独一无二却又随主题切换。
+
+## 允许
+
+- 任意服务段落的 HTML / CSS / JS / React：轻量交互解释、可调小工具、自定义布局与排版、
+  并排对比、概念动效、阅读节奏中的视觉停顿，以及按需的 SVG / canvas 图解 —— 都是
+  为当前段落定制的一次性实现。
+
+## 禁止
+
+- 复杂表单、拖拽工作台、完整 dashboard、产品原型、和文章无关的动画、独立于主题的配色、
+  复用固定小组件冒充自由表达。
+
+## Raw by example（每次现写，别复用固定 widget）
+
+> 下面只是几种常见手段（SVG / CSS 动画 / React 交互），**不是穷举也不是优先级**。布局、
+> 排版、对照面板、`<canvas>`、嵌入式小工具同样都行 —— 按"最能讲清这一段"来选。
+
+```tsx
+// 1) 需要曲线时，才为这个数据点手画一条内联 SVG（不是默认手段）
+<Raw title="构建体积走势">
+  <svg viewBox="0 0 300 80" width="100%">
+    <polyline points={pts} fill="none" stroke="var(--ra-color-accent)" strokeWidth="2" />
+  </svg>
+</Raw>
+
+// 2) 带一次性 CSS / @keyframes 的 HTML 字符串（内联进产物）
+<Raw html={`
+  <style>@keyframes ra-rise{from{height:0}to{height:var(--h)}}</style>
+  <div style="display:flex;gap:8px;align-items:flex-end;height:80px">
+    <i style="--h:60%;flex:1;background:var(--ra-color-accent);animation:ra-rise .6s ease"></i>
+    <i style="--h:90%;flex:1;background:var(--ra-color-accent);animation:ra-rise .8s ease"></i>
+  </div>
+`} />
+
+// 3) 只为这篇文章定义的一个小交互组件
+function TokenScale() {
+  const [n, setN] = useState(50);
+  return (
+    <div>
+      <input type="range" value={n} onChange={(e) => setN(+e.target.value)} />
+      <span style={{ color: "var(--ra-color-accent)" }}>{n}%</span>
+    </div>
+  );
+}
+<Raw title="拖动感受差距"><TokenScale /></Raw>
+```
+
+整篇文章里变化这些 —— 不同媒介、不同布局、不同交互 —— 让没有两块 Raw 看起来一样。变化是好的，违反
+主题气质不行：`tufte` 的 Raw 不该变成发亮营销 dashboard，`press` 的 Raw 不该变成冷霓虹终端
+（除非主题 md 明确允许）。
+
+## Raw 自检
+
+- 这块 Raw 删掉后，文章理解是否会变差？
+- 它服务哪一个段落 / 论点？
+- 它是否使用 `--ra-*` token？是否符合主题 md？
+- 它是否让文章更像应用？（如果是，砍掉或收敛成服务阅读的解释性视觉 / 排版）
@@ -0,0 +1,35 @@
+# 修复政策（最小切片）
+
+按最小单位修复。**有修复才写** `review/repair-log.md`（一次过 / 无修复则不写）。
+
+## 禁止
+
+- 用户只反馈一处问题就**重写整篇**。
+- 为了修视觉而改动**已确认的文章结构**。
+- 为了压缩信息而删除用户**指定必须保留**的内容。
+
+## 最小切片对照
+
+| 问题 | 最小修复单位 |
+|---|---|
+| 信息缺失 | 对应 Section / Table / CodeBlock |
+| 信息太密 | 对应 Section 的段落和局部 Raw |
+| 主题不对 | `plan/plan.md` 的 Theme 段 + 局部 token / Raw |
+| 图片不对 | 对应图片和 `plan/plan.md` 的 Assets 段 |
+| 首屏不对 | Hero / Lead / Summary |
+| Raw 跑偏 | 单个 Raw block |
+| 移动端问题 | 对应 CSS / 组件布局 |
+| 构建错误 | 具体文件和行 |
+
+## repair-log.md 格式
+
+```markdown
+## <日期> <谁反馈 / 哪个 Reviewer>
+- 问题：<一句话>
+- 定位层：<节奏 / 视觉 / 内容 / 构建>
+- 最小修复单位：<Section 03 / raw-blocks/02 / main.tsx 主题 ...>
+- 改动：<改了什么>
+- 验证：<dev 预览 / npm run html 通过 / 控制台无错>
+```
+
+先定位是哪一层（内容 / 结构 / 视觉 / 构建），再改最小切片，**不要重做整篇**。
@@ -0,0 +1,133 @@
+# 评审清单与 Reviewer
+
+> 本文件的核心目的：**让每个节点用对的方式做对的事**，不要错开 SubAgent、不要错写文件。
+> 误开 SubAgent / 错写 review 文件是首要性能问题。完整规则见 SKILL.md「硬性质检协议」段。
+
+## 各阶段质检方式（铁律）
+
+| 阶段 | 质检方式 | 产物 |
+|---|---|---|
+| **Phase 1 Source（默认）** | 主 Agent 内联 5 条 checklist（见 `source-to-markdown.md`） | 无文件 |
+| Phase 1 Source（仅复杂/低置信源） | Source Reviewer SubAgent（对照 `original.*` diff） | `review/source-review.md` |
+| **Phase 2 Plan / Checkpoint 1 前** | **主 Agent 内联自查（禁开 SubAgent）** | **无文件** |
+| **Phase 4 First Spread / Checkpoint 2 前** | First Spread Reviewer SubAgent | `review/first-spread-review.md` |
+| **Phase 5 每个 Section** | Section Reviewer SubAgent | **以消息返回 pass/fail + 修复点，不写文件** |
+| **Phase 6 终审 / Checkpoint 3 前** | Editorial + Visual + Technical Reviewer SubAgent | `review/final-review.md` |
+
+拿到结论后**先按 fail 项把产出改完，再向用户汇报**。直接拿结论汇报但不修复 = 违规。
+
+---
+
+## Plan 自查（Phase 2 → Checkpoint 1 · 主 Agent 内联 · 5 条）
+
+写完 `plan/plan.md` 后**就地**核查这 5 条，按结论改 `plan/plan.md` 本身（不要写新文件）：
+
+1. **Brief / Outline 自洽**：信息保留比例与每节"保留信息"加起来对得上；Outline 没有偷偷
+   塞 Brief 没承诺的内容，也没有遗漏 Brief 必须保留的内容。
+2. **信息取舍有据**：每个"可删减"项都给出了理由（重复 / 旁枝 / 过时）；每个"必须保留"项
+   都指向 source.md 的具体段落 / 表格 / 代码。
+3. **没有过度组件化**：每节的"需要组件"不是把所有内容都框成 Aside / Quote / Table；正文仍
+   是主体（prose-first，见 `component-policy.md`）。
+4. **Raw / 图片有目的**：Outline 里每个标注"需要 Raw"或"需要 Image"的位置，都能用一句话
+   说出它服务的论点 / 表达目的，不是装饰。
+5. **章节序号合理**：Outline 章节连续单调（01 / 02 / 03 …），子节序号前缀对齐父章节（第 08
+   章下只能是 8.1 / 8.2，不要出现 5.1）。
+
+> 这一步**绝不开 SubAgent**：内容量小、上下文是热的，SubAgent 冷启动反而慢。
+
+---
+
+## First Spread 自检清单（Phase 4 → Checkpoint 2 前 · SubAgent）
+
+SubAgent 读 `article/Article.tsx`、`article/sections/01-*.tsx`、`article/Cover.tsx`（若有）、
+`plan/plan.md`、选定主题 `theme-profiles/<id>.md`，按清单核查，写 `review/first-spread-review.md`：
+
+- **封面**（若开 · 见 `cover.md` 5 条自检）：图文并茂、主题忠实（只用 `--ra-*` token）、
+  内容忠实（封面视觉跟正文主旨对得上）、比例自适应（屏幕 3:4 + PDF 独占首页都不错位）、
+  不与 Hero 重复内容？
+- 首屏像文章，不像 landing page？读者是否立刻知道文章要解决什么？
+- 第一节有阅读节奏？Raw 服务理解？图片服务表达？移动端能读？
+- 主题气质对不对？版式宽度合适吗？
+- 代码可构建（`npm run dev` 无报错），浏览器控制台无红字？
+
+prompt 模板：
+
+```text
+请作为 First Spread Reviewer。读取 article/Cover.tsx（若有）、article/Article.tsx、
+article/sections/01-*.tsx、plan/plan.md、theme-profiles/<id>.md、references/cover.md
+（若有封面），对照 First Spread 自检清单逐项核查。把结论写进
+review/first-spread-review.md（pass / fail + 证据 + 必须修复项 + 改写建议）。
+不要替我改文件，也不要泛泛夸奖。
+```
+
+主 Agent 收到结论后**先按 fail 项改完**，再进 Checkpoint 2。
+
+---
+
+## Section 自检清单（Phase 5 每个 Section · SubAgent · 消息返回）
+
+SubAgent 读对应 `sections/<NN>-*.tsx`、`plan/plan.md` 的本节段落、`source/source.md` 本节
+对应内容，按清单核查，**以消息形式返回结论**：
+
+- 完成本节 outline 任务？
+- 符合 Brief 的信息保留比例？必须保留的信息没丢？
+- 与前后节衔接？没有重复或矛盾？
+- 没有过度组件化？正文充足？
+- Raw 与配图有明确目的？
+- **本节序号自洽**：`Section index` 等于主 Agent 指定的 `<NN>`；每个 `Subsection` 序号
+  前缀等于 `<NN>`（如 `<NN>=08` 则小节是 8.1 / 8.2，**不要**写成 5.1）。
+
+prompt 模板：
+
+```text
+请作为 Section Reviewer。读取 article/sections/<NN>-*.tsx、plan/plan.md 本节段落、
+source/source.md 本节对应内容、theme-profiles/<id>.md。
+对照 Section 自检清单逐项核查，**直接以消息形式返回**：
+- 第一行：pass / fail
+- 若 fail：列出修复点（带行号 / 代码片段证据）
+不要写任何 review 文件。不要替我改文件。不要泛泛夸奖。
+```
+
+主 Agent 收到 fail 项后**直接修对应 section 文件**，再汇报本节交付。
+
+---
+
+## Phase 6 终审三视角（SubAgent · 写 `review/final-review.md`）
+
+**Editorial Reviewer**（文章性、信息取舍、结构）
+
+- 它仍然是一篇文章，不是网页应用。
+- 信息保留比例符合 Brief；必须保留的信息没有丢。
+- 语言符合 Brief：全文统一为目标语言，地道、无翻译腔、无残留源语言片段（图注 / 引用 / 术语也算）。
+- 没有空泛标题、堆卡片、过度总结。
+
+**Visual Reviewer**（主题、Raw、图片、移动端）
+
+- 主题气质统一；Raw 没有野生样式（都用 `--ra-*` token）。
+- 图片符合主题和上下文，不抢正文，不与 Raw 重复。
+- 没有明显 AI 味：装饰性视觉、紫粉渐变、圆角彩卡、假插画、emoji 装饰。
+- 桌面和移动端都可读，无文字溢出 / 遮挡 / 空白异常。
+
+**Technical Reviewer**（构建、控制台、代码 / 公式、可访问性、序号）
+
+- `npm run html` 可构建，`article/article.html` 可打开、可分享。
+- 浏览器控制台无报错；代码 / 公式高亮和主题一致。
+- 图片有 alt，链接可用，标题层级合理。
+- **章节序号全篇自洽**（`index` 是手写字符串，组件不自动编号也不校验）：
+  - `Section` 序号连续单调：`01 / 02 / 03 …`，无跳号、无重复、无错序。
+  - 每个 `Subsection` 序号前缀等于其父 `Section` 编号：第 08 章下是 `8.1 / 8.2`，**绝不**出现 `5.1`。
+  - 序号与左侧 TOC、`plan/plan.md` Outline 章节顺序三者一致。
+  - 逐个 `Section` / `Subsection` 把渲染出来（或 TOC 里）的序号抄下来比对，**不要只看代码顺序** ——
+    并行模式（开发模式 B）下 subagent 看不到自己在全篇的位置，最容易在这里写错。
+
+prompt 模板：
+
+```text
+请作为 <Editorial / Visual / Technical> Reviewer。读取 plan/plan.md、source/source.md、
+article/Article.tsx 和所有 article/sections/*.tsx、theme-profiles/<id>.md。
+对照本视角的终审清单逐项核查，把结论追加到 review/final-review.md 的
+"<视角>"段（pass / fail + 证据 + 必须修复项 + 改写建议）。
+不要替我改文件，不要泛泛夸奖。
+```
+
+三个视角可并行起 SubAgent，主 Agent 收齐后按 fail 项最小切片修复（见 `repair-policy.md`）。
@@ -0,0 +1,77 @@
+# 脚手架
+
+脚手架在 Phase 4 创建文章工作区，**不把工程代码塞进 SKILL.md**。工程模板是 Skill
+assets（`assets/scaffold-template/`），由 `scripts/scaffold.sh` 复制并接线。
+
+## 用法
+
+```bash
+bash <path-to-beautiful-article>/scripts/scaffold.sh ./my-article --theme=tufte
+bash <path-to-beautiful-article>/scripts/scaffold.sh ./brief --theme=press --no-cover
+bash <path-to-beautiful-article>/scripts/scaffold.sh --list-themes
+```
+
+`--theme` 必须是 `theme-profiles/index.json` 里的 id（当前 `tufte` / `press` / …）。工作区可建在
+**任意目录**，不需要在 reacticle 仓库内。
+
+`--no-cover` 禁用书封式文章封面（默认开 · 屏幕 3:4 / PDF 独占首页）。Checkpoint 1 用户
+选了"封面 · 关"时传这个。详见 `references/cover.md`。
+
+## 脚手架做什么
+
+- 创建工作区目录 + 复制 Vite / React / TS 模板。
+- **从 npm 安装最新发布版的 `reacticle`**：`package.json` 里 `reacticle: "latest"`，脚手架
+  装完依赖后再 `npm install reacticle@latest` 强制刷新到当下最新，并打印实际版本。
+- 在 `article/main.tsx` 写入所选 runtime theme id，并 `import "reacticle/styles.css"`。
+- 创建默认 `article/Article.tsx` + `article/sections/`、`article/raw-blocks/`、
+  `article/assets/`。`Article.tsx` 末尾自带 **colophon Raw 块**（`Made with
+  [beautiful-article](github 仓库) · <主题> theme`），样式低对比小字、走 `--ra-*` token，
+  **不可删除**（见 SKILL.md「默认策略」）。
+- 默认创建 **`article/Cover.tsx`**（书封式封面外壳 + 占位：屏幕 3:4 / PDF 独占首页）并在
+  `main.tsx` 里渲染 `<Cover />` 在 `<ArticleDoc />` 之上。`--no-cover` 时跳过这一步：
+  不复制 Cover.tsx，并从 `main.tsx` 剥掉 `__COVER_IMPORT_*__` / `__COVER_RENDER_*__`
+  标记包裹的两段。封面设计见 `references/cover.md`。
+- 创建工作记忆目录 `source/`、`plan/`、`review/`。
+- `katex` / `prismjs` 作为 `reacticle` 的依赖会被自动带下来，无需在工作区单独声明。
+
+## 升级组件库
+
+工作区随时可升级到最新组件库：
+
+```bash
+npm install reacticle@latest
+```
+
+## 工作区结构
+
+```text
+my-article/
+  package.json  vite.config.ts  tsconfig.json  tsconfig.node.json  index.html
+  source/   plan/   review/
+  article/
+    main.tsx        # 入口：<ThemeProvider theme="..."> + <Cover/> + <ArticleDoc/>
+    Cover.tsx       # 书封式文章封面：屏幕 3:4 / PDF 独占首页（默认；--no-cover 时不生成）
+    Article.tsx     # assembler（主 Agent 拥有）：import + 排序各 Section，不写 Section 正文
+    sections/       # 一节一文件（铁律）：NN-*.tsx，每个导出一个 Section 组件
+      01-opening.tsx
+    raw-blocks/     # 大型 Raw 隔离：NN-*.tsx
+    assets/         # 配图素材
+  .theme            # 记录起步主题
+```
+
+> **一个 Section = 一个文件**（`sections/NN-*.tsx`），坚决不允许把多个 Section 写进
+> `Article.tsx`。`Article.tsx` 只做组装。这是多 Agent 并行（开发模式由 Checkpoint 2 选定）
+> 的前提，详见 `references/section-build.md`。
+
+## 切主题
+
+改两处（脚手架默认会把主题名注入到这两个位置）：
+
+1. `article/main.tsx` 里 `<ThemeProvider theme="...">`（控制运行时主题）。
+2. `article/Article.tsx` 末尾的 colophon `· <主题> theme`（控制印记里显示的主题名）。
+
+两处保持一致。详见 `html-output.md`。
+
+## 构建 / 预览
+
+见 `references/html-output.md`（`npm run dev` / `build` / `html`）。
@@ -0,0 +1,100 @@
+# Section 构建与多 Agent 并行
+
+## 铁律：一个 Section = 一个组件文件
+
+每个 Section **必须**是独立组件文件，**坚决不允许**把多个 Section 直接写进一个组件。
+
+```text
+article/
+  Article.tsx          # assembler（主 Agent 拥有）：import + 排序各 Section
+  sections/
+    01-opening.tsx     # export function SectionOpening() { return <Section .../> }
+    02-context.tsx
+    03-mechanism.tsx
+  raw-blocks/
+    01-token-flow.tsx  # 大型 / 复用的 Raw 隔离到这里，被对应 section import
+```
+
+- 每个 `sections/NN-*.tsx` 导出一个组件，内部用 `<Section index="NN" title="...">…</Section>`。
+- `Article.tsx` 只做组装：
+  ```tsx
+  import { Article, Hero, Lead, Conclusion } from "reacticle";
+  import { SectionOpening } from "./sections/01-opening";
+  import { SectionContext } from "./sections/02-context";
+  export function ArticleDoc() {
+    return (
+      <Article toc width="regular">
+        <Hero ... /><Lead>…</Lead>
+        <SectionOpening />
+        <SectionContext />
+        <Conclusion>…</Conclusion>
+      </Article>
+    );
+  }
+  ```
+- 文件级隔离 + reacticle 无裸 CSS（样式全走主题 token）→ 多个 Agent 改不同 section 文件
+  **不会互相破坏**。
+
+## 章节序号由主 Agent 统一编（避免序号错乱）
+
+`Section` / `Subsection` 的 `index` 是**手写字符串**，组件既不自动编号、也不校验——它只会原样显示。
+所以一旦哪个 section 文件写错了序号（典型：并行模式里 subagent 看不到自己在全篇的位置，凭空写出
+"第 8 章下挂一个 5.1"），就会一路漏到成品里。规则：
+
+- **全局序号归主 Agent（assembler）所有。** 在 `Article.tsx` 排定最终顺序后，主 Agent 据此把每个
+  `Section` 的 `index` 校准成 `01 / 02 / 03 …`，并把每个 `Subsection` 的序号前缀对齐到所属
+  `Section`（第 08 章下只能是 `8.1 / 8.2 …`）。
+- **subagent 不自编全局序号。** 主 Agent 在派活时直接告诉它"你是第 `<NN>` 章"，subagent 用这个
+  `<NN>` 写 `Section index` 和本节 `Subsection` 的前缀；拿不准就留 outline 给的占位，最终由主
+  Agent 统一过一遍。
+- **组装后必校验**：对照 TOC 显示与 `outline.md` 顺序，确认序号连续单调、子节前缀正确（并入终审
+  Technical Reviewer 的"章节序号全篇自洽"清单）。
+
+## 两种开发模式（Checkpoint 2 由用户选定）
+
+第一个 Section 无论哪种模式都先由**主 Agent 完成并验收**（风格锚点）。差异在第 2 个 Section 起：
+
+### A · 单 Agent 顺序（默认，最稳）
+
+主 Agent 顺序写 `02 → 03 → …`，风格最统一，随时验收。
+
+### B · 多 Agent 并行（最快）
+
+subagent 各**拥有一个** `sections/NN-*.tsx` 并行开发。**主 Agent 负责合并与稳定性**：
+
+- 维护 `Article.tsx` 的 import 与 Section 顺序（唯一组装点，避免冲突），并据最终顺序**统一校准每个
+  Section 的 `index` 与各 Subsection 的序号前缀**（见上节"章节序号由主 Agent 统一编"）。
+- 每轮并行结束跑 `npm run typecheck` + `npm run build`，修构建错误。
+- 兜底主题与风格一致（颜色 / 字体 / 间距走 token，气质不跑偏）。
+- 解决重复 / 衔接问题（相邻 section 论点是否承接）。
+
+风格在并行下会有轻微差异（这是预期，主题 token 兜底视觉统一）。
+
+### 并行 subagent 的 prompt 必须包含
+
+```text
+你负责文件 article/sections/<NN>-<id>.tsx，只改这一个文件，导出一个 Section 组件。
+你是全篇第 <NN> 章（这个编号由主 Agent 指定，你看不到自己在全篇的位置，不要自己另编）。
+读取：plan/plan.md 的 Outline 段本节段落 + Brief 段（信息保留比例）+
+      source/source.md 本节对应内容 + 选定主题 theme-profiles/<id>.md +
+      references/component-policy.md + references/raw-policy.md +
+      第一个 section 文件作为“代码风格”参考（不是抄袭对象）。
+硬规则：
+- 一个文件 = 一个 Section 组件；不要碰 Article.tsx 或别的 section 文件。
+- 正文为主体，组件按需（默认核心组件优先），Raw 用 --ra-* token 现写。
+- 符合本节 outline 任务与信息保留比例；与前后节衔接。
+- 序号：<Section index="<NN>">；本节所有 <Subsection> 的序号前缀必须等于 <NN>
+  （如 <NN>=08 则小节是 8.1 / 8.2 …），不要从别的章节复制序号。
+- 完工自检对照 references/review-checklist.md 的 Section 清单。
+不要修改 Article.tsx（主 Agent 统一组装与序号校准），不要改主题。
+```
+
+## 每个 Section 完工（必走质检 · SubAgent · 消息返回）
+
+按硬性质检协议创建 **Section Reviewer** SubAgent，对照清单核查：完成 outline 任务 / 符合
+信息保留比例 / 与前后衔接 / 不过度组件化 / 正文充足 / Raw 与配图有明确目的 / **本节序号
+自洽**（`Section index` 等于 `<NN>`，各 `Subsection` 序号前缀等于 `<NN>`）。
+
+**SubAgent 以消息形式返回 pass/fail + 修复点**（pass 一行 OK，fail 列出修复点），**不要写
+`review/section-NN-review.md` 文件**。主 Agent 收到 fail 项后直接修对应 section 文件，再
+汇报本节交付。完整 prompt 模板见 `references/review-checklist.md` 的 Section 段。
@@ -0,0 +1,118 @@
+# Source → Markdown
+
+无论输入是什么，Phase 1 都先转成统一的 `source/source.md`，并把风险写进
+`source/extraction-notes.md`。
+
+## 产物
+
+`source.md` 要包含：标题 · 来源 · 作者 / 时间 / 链接（若可得）· 正文 · 表格 ·
+图片占位 · 代码块 · 引用 · 附录 / 脚注。
+
+`extraction-notes.md` 要记录：输入类型 · 提取方式 · 可能丢失的信息 · PDF/DOCX 中
+无法可靠还原的版式 · 图片 / 表格 / 脚注 / 代码是否完整 · 需要用户补充的素材或上下文 ·
+**源语言、是否需要翻译、目标语言、翻译版文件名与翻译说明**。
+
+## 语言与翻译
+
+抽取后判断 `source.md` 的语言，并按 Phase 0 记录的目标语言决定：
+
+- 未指定目标语言，或目标语言与源一致 → **不翻译**，最终文章语言 = 源语言。
+- 指定了目标语言且与源不一致 → 产出 `source/source.<lang>.md`（如 `source.zh.md` / `source.en.md`），
+  作为 Phase 2+ 的**事实底座**；原 `source.md` 保留备查。
+  - 翻译要求：**地道、去翻译腔** —— 按目标语言的表达习惯重组句子，不逐字直译，不留生硬外语语序 /
+    被动堆叠 / 异国标点；术语 / 数字 / 代码 / 公式 / 引用保持准确；标题层级、结构、信息保留比例不变。
+  - 翻译只在源文层做一次；后续编辑、改写语气、组件化都基于翻译版进行。
+
+## 不同输入的处理原则
+
+| 输入 | 处理方式 | 自检重点 |
+|---|---|---|
+| URL | 抓网页正文，清理导航 / 广告 / 推荐 | 是否抓到主体，链接和图片是否保留 |
+| PDF | 提取文本 / 章节 / 表格 / 图片占位 | 断行错乱、页眉页脚混入、表格丢失 |
+| DOCX | 提取标题层级 / 段落 / 表格 / 图片占位 | 样式不重要，结构和内容完整性重要 |
+| Markdown | 保持原有标题 / 代码块 / 表格 | 不要过度改写源文 |
+| 纯文本 | 识别结构并标注不确定处 | 不要擅自编造层级 |
+| 截图 / 图片 | 转成图片占位 + 说明，记录用途 | 记录到 extraction-notes，等用户确认 |
+
+## 抽取脚本选择
+
+Skill 提供两条抽取路径：MarkItDown 主路径 + 轻量 fallback。Agent 应在 Phase 1 先判断
+输入类型、信息保留要求和本机环境，再选择脚本。
+
+### 1. MarkItDown 主路径
+
+对 PDF / DOCX / PPTX / HTML / 复杂文档，尤其是用户要求 80-100% 信息保留时，优先使用
+`scripts/source-to-markdown-markitdown.py`：
+
+```bash
+python3.10 <path-to-beautiful-article>/scripts/source-to-markdown-markitdown.py <input> -o source/source.md
+```
+
+MarkItDown 需要 Python 3.10+。它是可选增强依赖，不随组件库或脚手架强制安装。
+若未安装，按需提示用户安装：
+
+```bash
+python3.10 -m pip install "markitdown[pdf,docx]"
+```
+
+如果本机没有 `python3.10` 命令但有 `uv`，可临时拉起带 MarkItDown 的环境：
+
+```bash
+uv run --python 3.12 --with "markitdown[pdf,docx]" python \
+  <path-to-beautiful-article>/scripts/source-to-markdown-markitdown.py <input> -o source/source.md
+```
+
+不要默认安装 `markitdown[all]`，除非用户明确需要 PPTX / XLSX / 音频 / YouTube / Azure 等
+额外格式。全量安装更重，也更容易引入环境问题。
+
+### 2. 轻量 fallback
+
+如果 MarkItDown 不可用、Python 版本不足、转换失败，或输入只是 Markdown / TXT / 简单 HTML，
+使用 `scripts/source-to-markdown.py`：
+
+```bash
+python3 <path-to-beautiful-article>/scripts/source-to-markdown.py <input> -o source/source.md
+```
+
+脚本会探测可用的解析库（pdfminer / pdfplumber / python-docx / BeautifulSoup），缺库时
+打印安装建议并优雅降级。脚本只做**机械抽取**；正文清理、占位标注、风险记录仍由 agent 完成。
+URL 也可直接用 agent 的网页抓取能力获取正文，再清理。
+
+### 3. Agent 决策规则
+
+- PDF / DOCX / PPTX / 复杂 HTML：先尝试 MarkItDown。
+- Markdown / TXT：直接用 fallback，保持原文结构，不要过度处理。
+- URL：可先用 Agent 的网页抓取能力获取正文；若已保存为 HTML 文件，再按复杂度选择
+  MarkItDown 或 fallback。
+- 100% 信息保留：抽取后必须更严格自检，必要时同时跑 MarkItDown 与 fallback，对比是否
+  有表格、代码、脚注、图片占位遗漏。
+- 任一脚本产物都只是 `source.md` 草稿；Agent 必须继续清理噪音、补图片占位，并写
+  `source/extraction-notes.md`。
+
+## Source Phase 自检（主 Agent 内联 · 5 条 checklist）
+
+源材料质检**不是硬性 SubAgent 质检点**。主 Agent 进 Phase 2 前反正要通读 `source.md`，
+就地按这 5 条核查、按结论修复即可（无需单独的 review 文件）：
+
+1. **完整性**：是否被截断？体量是否和原文相称（长 PDF / 长文没有只抽到一半 / 只抓到首屏）？
+2. **结构**：标题层级是否保留？还是被压平成一片正文（后面没法分章）？
+3. **关键载体**：表格 / 代码 / 公式 / 引用 / 脚注是否保留且没损坏（表格没挤成一行、代码缩进还在、
+   公式没变乱字符）？
+4. **噪声**：是否误把导航 / 广告 / Cookie 横幅 / 推荐阅读 / 页眉页脚页码写进正文？编码有没有伤
+   （乱码、连字 `ﬁ`、软连字符断词、两栏 PDF 阅读顺序错乱）？
+5. **不确定项**：图片是否以占位标注？拿不准的都写进 `extraction-notes.md` 了吗？
+
+> ⚠️ 上面 1/4 能孤读 markdown 抓到，但 **2/3 里"静默丢失"的表/段**（被悄悄删掉、吞掉）
+> 光看 markdown 看不出来——必须对照 `original.*`。
+
+## 升级为独立 Source Reviewer（仅限复杂/低置信源）
+
+**只有**当 `extraction-notes.md` 标记了"低置信 / 复杂 PDF/DOCX / 转换吃不准 / 要求 100% 保留的关键源"
+时，才升级为独立 SubAgent，并**强制对照原件做 diff 式核查**，写 `review/source-review.md`：
+
+```text
+请作为 Source Reviewer。同时读取 source/original.*（原件）和 source/source.md（转换产物）。
+逐项做 diff 式核查：对照原件，source.md 是否漏掉了表格 / 段落 / 脚注 / 代码 / 图，
+是否混入噪音，是否有结构塌陷或编码损坏。
+只输出"按出现顺序的差异清单 + 必须修复项"，不评价文章好不好看，不要替我改文件。
+```
@@ -0,0 +1,48 @@
+# 主题选择
+
+主题负责**审美气质、排版语言、图片风格、Raw 风格、代码 / 公式风格**。它不是 CSS 皮肤，
+也不是信息密度规则。
+
+> CSS 给浏览器读，theme profile 给 AI 读。
+
+- **组件库拥有运行时主题**：CSS token、`ThemeProvider` 注册、实际渲染。
+  注册的 runtime theme id 见 `src/theme/ThemeProvider.tsx`（当前：`tufte`、`press`）。
+- **Skill 拥有主题 authoring profile**：`theme-profiles/index.json` + `<id>.md`，
+  指导 AI 如何选择和使用主题。
+
+## 选择流程
+
+1. 读 `theme-profiles/index.json`，拿每个主题的 `bestFor` / `mood`。
+2. 按 `source.md` 的内容类型 / 语气，从 `bestFor` 命中里挑 1-2 个推荐：
+   - 技术 / 证据 / 数据型 → `tufte`。
+   - 叙事 / 评论 / 出版 / 产品手记 → `press`。
+3. 读选定主题的 `theme-profiles/<id>.md`（写作 / 配图 / Raw / 代码前的权威）。
+4. 把选择 + 理由写进 `plan/plan.md` 的 **Theme** 段（见 `plan-template.md`）。
+
+## Density 与 Theme 解耦
+
+theme profile 里可以写"不同信息密度下的表现建议"，但**不能写成限制**。例：
+
+- `tufte + 100% longform`：克制长文、数据证据、Raw 点亮关键概念。
+- `tufte + 40% visual-essay`：仍成立，Raw 偏图解 / 证据、低装饰。
+- `press + 100% longform`：可做深度出版文章。
+- `press + 40% briefing`：更强编辑节奏与图文留白。
+
+## 主题选择自检
+
+- 主题是否匹配文章类型？
+- 当前信息密度下，正文 / Raw / 图片比例该如何调整？
+- Raw 是否能在该主题下自然发生？配图策略是否符合主题？
+- 是否存在主题与源材料冲突？（冲突要在 `plan/plan.md` 的 Theme 段解释）
+- runtime theme id 是否真实存在于组件库？Skill profile 是否存在？
+
+## 新增主题的约束
+
+新增主题必须**同时**满足：
+
+1. 组件库有 runtime theme CSS 与 `ThemeProvider` 注册（`src/theme/themes/<id>/`）。
+2. Skill 有对应 `theme-profiles/<id>.md`。
+3. `theme-profiles/index.json` 绑定到正确 runtime theme id。
+
+- 只有 Skill profile、没有组件库 runtime theme → 只能作候选，不能用于正式生成。
+- 只有组件库 runtime theme、没有 Skill profile → Agent 不能主动推荐。