create-yss-spec 1.0.0

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

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

package/template/.trae/skills/beautiful-article/references/scaffold.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`）。

package/template/.trae/skills/beautiful-article/references/section-build.md

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

package/template/.trae/skills/beautiful-article/references/source-to-markdown.md

@@ -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 横幅 / 推荐阅读 / 页眉页脚页码写进正文？编码有没有伤
+   （乱码、连字 `fi`、软连字符断词、两栏 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 是否漏掉了表格 / 段落 / 脚注 / 代码 / 图，
+是否混入噪音，是否有结构塌陷或编码损坏。
+只输出"按出现顺序的差异清单 + 必须修复项"，不评价文章好不好看，不要替我改文件。
+```

package/template/.trae/skills/beautiful-article/references/theme-selection.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 不能主动推荐。

package/template/.trae/skills/beautiful-article/scripts/html-to-pdf.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────
+# html-to-pdf.sh —— 把 Beautiful Article 的单页 HTML 转成 PDF
+#
+# 用法：
+#   bash <skill>/scripts/html-to-pdf.sh [input.html] [output.pdf]
+#   bash <skill>/scripts/html-to-pdf.sh                       # 默认 article/article.html → article/article.pdf
+#   bash <skill>/scripts/html-to-pdf.sh --help
+#
+# 前提：本机已装 Chromium / Google Chrome / Brave / Microsoft Edge 之一
+# （脚本会自动探测）。无需 npm 包、无需 Node。
+#
+# 设计要点（详见 references/pdf-output.md）：
+#   1. reacticle 默认 TOC 在桌面是左右栅格；PDF 需要 TOC 上、正文下的上下排布。
+#   2. 脚本在 HTML 头部注入一段 @media print CSS 覆盖：把 TOC 塌成一列、解除
+#      sticky、长 TOC 双列省纸、TOC 后强制分页、隐藏 colophon 之外的页眉页脚等。
+#   3. 用 headless 浏览器 --print-to-pdf 渲染（执行页面 JS，Raw 交互渲染为初始
+#      态）；输出标准 A4 / 主题纸色满版背景 + 0.45in 内容留白，无浏览器自带页眉页脚。
+#   4. 失败回退：打印"用浏览器手动 Cmd+P → 另存为 PDF"指引，并把注入后的 HTML
+#      留在临时目录方便用户自己打印。
+# ─────────────────────────────────────────────────────────────
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CSS_FILE="$SCRIPT_DIR/pdf-print-overrides.css"
+
+INPUT="${1:-article/article.html}"
+OUTPUT="${2:-article/article.pdf}"
+
+if [[ "$INPUT" == "--help" || "$INPUT" == "-h" ]]; then
+  sed -n '2,21p' "$0"
+  exit 0
+fi
+
+if [[ ! -f "$INPUT" ]]; then
+  echo "✗ 输入文件不存在：$INPUT" >&2
+  echo "  先在工作区跑 npm run html 产出 article/article.html。" >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$OUTPUT")"
+
+# ── 探测可用的 chromium-family 浏览器 ─────────────────────
+find_browser() {
+  local candidates=(
+    chromium
+    chromium-browser
+    google-chrome
+    google-chrome-stable
+    chrome
+    brave-browser
+    microsoft-edge
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+    "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"
+    "/Applications/Chromium.app/Contents/MacOS/Chromium"
+    "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge"
+    "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser"
+    "/Applications/Arc.app/Contents/MacOS/Arc"
+    "/usr/bin/chromium"
+    "/usr/bin/google-chrome"
+    "/snap/bin/chromium"
+  )
+  for c in "${candidates[@]}"; do
+    if command -v "$c" >/dev/null 2>&1; then
+      echo "$c"; return 0
+    fi
+    if [[ -x "$c" ]]; then
+      echo "$c"; return 0
+    fi
+  done
+  return 1
+}
+
+# ── 注入 @media print 覆盖到一个临时 HTML ─────────────────
+# 设计：CSS 抽到 scripts/pdf-print-overrides.css（详见该文件顶部注释），这里只
+# 负责"把它的内容包在 <style> 里、塞到 </head> 之前"。这样：
+#   • macOS BSD awk 不接受 -v 传多行字符串（"newline in string"），用 awk
+#     getline 从文件读则两边都吃得下。
+#   • CSS 文件可独立编辑 / lint / 复用，不被 shell 转义吃掉。
+TMP_DIR="$(mktemp -d -t beautiful-article-pdf.XXXXXX)"
+TMP_HTML="$TMP_DIR/article-print.html"
+
+if [[ ! -f "$CSS_FILE" ]]; then
+  echo "✗ 找不到打印覆盖 CSS：$CSS_FILE" >&2
+  echo "  这个文件应跟脚本同目录（scripts/pdf-print-overrides.css）。" >&2
+  exit 2
+fi
+
+awk -v css_file="$CSS_FILE" '
+  /<\/head>/ && !done {
+    print "<style id=\"ra-pdf-overrides\">"
+    while ((getline line < css_file) > 0) print line
+    close(css_file)
+    print "</style>"
+    done = 1
+  }
+  { print }
+' "$INPUT" > "$TMP_HTML"
+
+if ! grep -q 'ra-pdf-overrides' "$TMP_HTML"; then
+  echo "✗ 注入失败：未在输入 HTML 找到 </head>。" >&2
+  echo "  你的 article.html 可能不是 Vite + reacticle 单页产物。" >&2
+  exit 3
+fi
+
+# ── 找浏览器 ──────────────────────────────────────────────
+BROWSER="$(find_browser || true)"
+if [[ -z "$BROWSER" ]]; then
+  echo "⚠ 未找到任何 chromium-family 浏览器（chromium / google-chrome / brave / edge）。"
+  echo
+  echo "  回退方案：注入了打印 CSS 的 HTML 已经放在："
+  echo "  $TMP_HTML"
+  echo
+  echo "  请用浏览器打开它 → Cmd+P / Ctrl+P → 目标改为'另存为 PDF' → 保存。"
+  echo "  注入的 print 样式会让 TOC 在上、正文在下，与 PDF 阅读习惯对齐。"
+  exit 3
+fi
+
+echo "▸ 用浏览器：$BROWSER"
+echo "▸ 输入：$INPUT"
+echo "▸ 输出：$OUTPUT"
+
+# ── 渲染 ──────────────────────────────────────────────────
+# Chromium 系都支持 --headless --print-to-pdf。
+# --no-pdf-header-footer：去掉浏览器自带的 URL / 日期 / 页码（colophon 已有）。
+# --virtual-time-budget：给页面 JS 一点时间初始化 Raw 组件（5s 兜底）。
+# --hide-scrollbars：避免在 PDF 里看到滚动条残影。
+"$BROWSER" \
+  --headless=new \
+  --disable-gpu \
+  --no-sandbox \
+  --hide-scrollbars \
+  --no-pdf-header-footer \
+  --virtual-time-budget=5000 \
+  --print-to-pdf-no-header \
+  --print-to-pdf="$OUTPUT" \
+  "file://$TMP_HTML" 2>/dev/null || {
+    # 旧版 Chrome 不认 --headless=new，回退老 flag
+    "$BROWSER" \
+      --headless \
+      --disable-gpu \
+      --no-sandbox \
+      --hide-scrollbars \
+      --print-to-pdf-no-header \
+      --print-to-pdf="$OUTPUT" \
+      "file://$TMP_HTML" 2>/dev/null
+  }
+
+# 清理临时（HTML 注入留作回退证据，最后再清）
+rm -rf "$TMP_DIR"
+
+if [[ -f "$OUTPUT" ]]; then
+  SIZE="$(du -h "$OUTPUT" | cut -f1)"
+  echo "✓ PDF 输出：${OUTPUT} (${SIZE})"
+  echo
+  echo "  如果 TOC / 分页不理想，看 references/pdf-output.md 故障排除段。"
+else
+  echo "✗ 浏览器返回成功但输出文件不存在：$OUTPUT" >&2
+  exit 4
+fi