create-yss-spec 1.0.0

package/template/.pi/skills/beautiful-article/references/information-density.md

@@ -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 段"可删减的信息"列表。

package/template/.pi/skills/beautiful-article/references/layout.md

@@ -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 的开关是否经用户确认？短文是否误开了喧宾夺主的目录？
+- 移动端两栏是否正常回落为单栏？

package/template/.pi/skills/beautiful-article/references/pdf-output.md

@@ -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 版本解耦）。

package/template/.pi/skills/beautiful-article/references/plan-template.md

@@ -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 条）"。

package/template/.pi/skills/beautiful-article/references/raw-policy.md

@@ -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？
+- 它是否让文章更像应用？（如果是，砍掉或收敛成服务阅读的解释性视觉 / 排版）

package/template/.pi/skills/beautiful-article/references/repair-policy.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 通过 / 控制台无错>
+```
+
+先定位是哪一层（内容 / 结构 / 视觉 / 构建），再改最小切片，**不要重做整篇**。