create-yss-spec 1.0.0

package/template/.trae/skills/beautiful-article/references/article-types/review.md

@@ -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`。

package/template/.trae/skills/beautiful-article/references/article-types/tutorial.md

@@ -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 不适合做参考手册。

package/template/.trae/skills/beautiful-article/references/article-types/visual-essay.md

@@ -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`。

package/template/.trae/skills/beautiful-article/references/article-types.md

@@ -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 覆盖。

package/template/.trae/skills/beautiful-article/references/asset-policy.md

@@ -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 自查段。

package/template/.trae/skills/beautiful-article/references/component-policy.md

@@ -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>
+  );
+}
+```

package/template/.trae/skills/beautiful-article/references/cover.md

@@ -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 导出时封面自动独占首页（不需要额外操作） |

package/template/.trae/skills/beautiful-article/references/harness.md

@@ -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、配图都服务阅读。

package/template/.trae/skills/beautiful-article/references/html-output.md

@@ -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` 能在浏览器离线打开。
+- 控制台无报错；桌面与移动端都可读，无文字溢出 / 遮挡 / 空白异常。