create-yss-spec 1.0.0

package/template/.pi/skills/beautiful-article/README.zh-CN.md

@@ -0,0 +1,450 @@
+# Beautiful Article Skill —— 把任意素材编辑成一篇精美的文章
+
+> 一个面向 AI Agent 的 Skill：把任意素材（URL / PDF / DOCX / Markdown / 纯文本 / 截图 / 粘贴材料）**编辑、设计**成一篇**比原文更易读、更便于分享和归档的精美文章**。
+
+[English](./README.md) · [返回集合首页](../../README.zh-CN.md)
+
+![Beautiful Article Skill](https://cdn.jsdelivr.net/gh/ConardLi/assets@main/imgs/article/banner.webp)
+
+---
+
+### 由 [ReActicle](https://github.com/ConardLi/reacticle) 驱动
+
+`beautiful-article` 是编辑型 **harness**（方法论、checkpoint、主题选型、sub-agent reviewer）；[`reacticle`](https://github.com/ConardLi/reacticle) 是 Skill 在运行时调用的**底层组件协议** —— prose-first 的 React 语义组件 + 基于主题 token 的 `Raw` 自由层，统一接到同一套主题系统上。
+
+```
+beautiful-article  （本 Skill · 方法论 + harness）
+        │  调用
+        ▼
+reacticle          （npm 包 · 组件 / 主题 / Raw / 导出）
+```
+
+| 层级 | 负责什么 | 仓库 / 文档 |
+|---|---|---|
+| `beautiful-article`（本 Skill） | **怎么** 让 Agent 从任意素材出发，规划、撰写、审阅、交付一篇文章 —— 6 阶段流程、3 个硬 checkpoint、主题选型、sub-agent reviewer | 当前目录 |
+| `reacticle` | Skill 实际拼装出的组件词表 + 11 套 authoring 主题 —— `Article` / `Hero` / `Lead` / `Section` / `Quote` / `Image` / `Formula` / `CodeBlock` / `Raw` …，每套主题 = 一份 `.css` token 包 + 一份 `.md` authoring profile | [`ConardLi/reacticle`](https://github.com/ConardLi/reacticle) · [npm `reacticle`](https://www.npmjs.com/package/reacticle) · [文档站](https://rearticle.mmh1.top/) |
+
+二者搭配最佳但相互独立：Skill 因为有 ReActicle 这个稳定目标层才能跑通；ReActicle 单独作为 React 组件库使用也完全立得住。
+
+---
+
+### [文章实例](https://mmh1.top/#/ai-article) —— 用 `beautiful-article` + ReActicle 写出来的真实文章
+
+每一篇都是 AI Agent 用本 Skill 调用 [`reacticle`](https://www.npmjs.com/package/reacticle) 组件协议端到端写完的真实长文。点封面即可在线打开单文件 HTML 版本。
+
+<table>
+<tr>
+<td width="50%" valign="top" align="center">
+<a href="https://mmh1.top/#/ai-article/tools">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/tools.webp" alt="Agent Tools 设计的最佳实践" width="320">
+<br><b>Agent Tools 设计的最佳实践</b>
+</a>
+<br><sub>Theme · Freddie · 长文 · 21 min</sub>
+<br><sup>Anthropic 工程团队关于 Tools 的五条原则，与一套评测驱动的方法。</sup>
+</td>
+<td width="50%" valign="top" align="center">
+<a href="https://mmh1.top/#/ai-article/skill">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/skill.webp" alt="Agent Skill 是如何进化的？" width="320">
+<br><b>Agent Skill 是如何进化的？</b>
+</a>
+<br><sub>Theme · Freddie · 解释文 · 8 min</sub>
+<br><sup>把 Skill 文档当成被训练的对象，而不是被复制粘贴的 prompt。</sup>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top" align="center">
+<a href="https://mmh1.top/#/ai-article/harness">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/harness.webp" alt="Agent Harness 的解剖图" width="320">
+<br><b>Agent Harness 的解剖图</b>
+</a>
+<br><sub>Theme · Vignelli · 长文 · 12 min</sub>
+<br><sup>智能在模型里；让智能变得有用的，是它周围的那套系统。</sup>
+</td>
+<td width="50%" valign="top" align="center">
+<a href="https://mmh1.top/#/ai-article/prompt-cache">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/prompt-cache.webp" alt="提示词缓存对 Agent 有多重要？" width="320">
+<br><b>提示词缓存对 Agent 有多重要？</b>
+</a>
+<br><sub>Theme · Bayer · 长文 · 15 min</sub>
+<br><sup>缓存命中率是 Agent 的 SLO，Claude Code 团队的反直觉经验。</sup>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top" align="center">
+<a href="https://mmh1.top/#/ai-article/context">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/context.webp" alt="面向 Agent 的高效上下文工程" width="320">
+<br><b>面向 Agent 的高效上下文工程</b>
+</a>
+<br><sub>Theme · Tufte · 长文 · 16 min</sub>
+<br><sup>本文探讨如何高效地筛选与管理驱动 AI Agent 运转的上下文。</sup>
+</td>
+<td width="50%" valign="top" align="center">
+<a href="https://mmh1.top/#/ai-article/transformer">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/transformer.webp" alt="Attention Is All You Need" width="320">
+<br><b>Attention Is All You Need</b>
+</a>
+<br><sub>Theme · Tufte · 长文 · 30 min</sub>
+<br><sup>一篇重塑现代 AI 的论文，逐层拆给你看。</sup>
+</td>
+</tr>
+<tr>
+<td width="50%" valign="top" align="center">
+<a href="https://mmh1.top/#/ai-article/agent-eval">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/agent-eval.webp" alt="把 AI Agent 的评测讲清楚" width="320">
+<br><b>把 AI Agent 的评测讲清楚</b>
+</a>
+<br><sub>Theme · Tufte · 长文 · 25 min</sub>
+<br><sup>让 Agent 有用的那些能力，恰恰让它难以评测 —— 来自 Anthropic 的指南。</sup>
+</td>
+<td width="50%" valign="top" align="center">
+<a href="https://mmh1.top/#/ai-article/agent-loop-codex">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/agent-loop-codex.webp" alt="Codex 的 Agent Loop 是怎么做的？" width="320">
+<br><b>Codex 的 Agent Loop 是怎么做的？</b>
+</a>
+<br><sub>Theme · Sottsass · 长文 · 18 min</sub>
+<br><sup>OpenAI 官方分享：在 Responses API 之上，一条对话是如何被反复"展开"的。</sup>
+</td>
+</tr>
+</table>
+
+---
+
+### [主题概览](https://rearticle.mmh1.top/#/gallery) —— 每套主题一篇样品文章
+
+> 11 套主题已上架。每套主题的完整契约（`.css` token 包 + `.md` authoring profile、anti-patterns、code/media style）见 [Theming](https://rearticle.mmh1.top/#/theming)。
+
+每套主题都附一篇**样品长文**，从字体到摄影、代码、公式、Raw 块通通走一遍。点封面在线阅读，点主题名跳到该主题在文档站的章节。
+
+<table>
+<tr>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/caffeine-half-life">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-tufte.webp" alt="Tufte · Data-Ink" width="260">
+<br><b>Tufte</b> · Data-Ink
+</a>
+<br><sub>咖啡因与睡眠 · 数据笔记</sub>
+<br><sup>Edward Tufte 数据墨水，证据优先，发丝级图表与最朴素的版式。</sup>
+</td>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/movable-type">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-press.webp" alt="Press · 书卷" width="260">
+<br><b>Press</b> · 书卷
+</a>
+<br><sub>活字之后 · 随笔</sub>
+<br><sup>Stripe Press 式书卷长读物：会落定的标题、氧化血红首字母、纯正文之美。</sup>
+</td>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/pool-exhaustion">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-shannon.webp" alt="Shannon · 工程暗色" width="260">
+<br><b>Shannon</b> · 工程暗色
+</a>
+<br><sub>连接池耗尽 · 故障复盘</sub>
+<br><sup>贝尔实验室技术论文血统，暗底黄金信号、回压依赖、夜间作战气质。</sup>
+</td>
+</tr>
+<tr>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/orbit-spec">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-vignelli.webp" alt="Vignelli · 瑞士" width="260">
+<br><b>Vignelli</b> · 瑞士网格
+</a>
+<br><sub>Orbit 设计系统规格 · 规格</sub>
+<br><sup>Massimo Vignelli 网格至上、grotesque 字族、瑞士红只承载结构。</sup>
+</td>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/linear-attention">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/knuth.png" alt="Knuth · 学术" width="260">
+<br><b>Knuth</b> · 学术
+</a>
+<br><sub>线性化自注意力 · 预印本</sub>
+<br><sup>Donald Knuth / Computer Modern，编号小节、命题与证明、arXiv 草稿气质。</sup>
+</td>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/first-newsletter">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-freddie.webp" alt="Freddie · 暖黄" width="260">
+<br><b>Freddie</b> · 暖黄
+</a>
+<br><sub>第一封 Newsletter · 上手指南</sub>
+<br><sup>Mailchimp Freddie 黑字荧光，亲和插画 + 不端着的产品上手语气。</sup>
+</td>
+</tr>
+<tr>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/slow-breathing">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-andy.webp" alt="Andy · 静谧" width="260">
+<br><b>Andy</b> · 静谧
+</a>
+<br><sub>把呼吸放慢 · 练习</sub>
+<br><sup>柔软圆润、呼吸-神经跷跷板，让人慢下来的练习气质。</sup>
+</td>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/front-page">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-bodoni.webp" alt="Bodoni · 报刊" width="260">
+<br><b>Bodoni</b> · 报刊
+</a>
+<br><sub>头版的消亡 · 特稿</sub>
+<br><sup>高对比 Didone 报刊气质，黑白大报、对折线之上的分量。</sup>
+</td>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/geometry-of-meaning">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-bayer.webp" alt="Bayer · 包豪斯" width="260">
+<br><b>Bayer</b> · 包豪斯
+</a>
+<br><sub>形、色、网格 · 教学</sub>
+<br><sup>Herbert Bayer 包豪斯三原色几何，形有性格、色有重量。</sup>
+</td>
+</tr>
+<tr>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/rate-limiter-spec">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-fuller.webp" alt="Fuller · 蓝图" width="260">
+<br><b>Fuller</b> · 蓝图
+</a>
+<br><sub>限流器设计规格 · 系统设计</sub>
+<br><sup>Buckminster Fuller 工程蓝图，方格纸拓扑、令牌桶模拟，可照着实现。</sup>
+</td>
+<td width="33%" valign="top" align="center">
+<a href="https://rearticle.mmh1.top/#/gallery/color-clash">
+<img src="https://raw.githubusercontent.com/ConardLi/assets/main/imgs/article/theam-sottsass.webp" alt="Sottsass · 孟菲斯" width="260">
+<br><b>Sottsass</b> · 孟菲斯
+</a>
+<br><sub>撞色不翻车 · 设计随笔</sub>
+<br><sup>Memphis 80s 撞色，黑描边、硬投影、轻微旋转的不正经语法。</sup>
+</td>
+<td width="33%" valign="top" align="center">
+&nbsp;
+</td>
+</tr>
+</table>
+
+> 完整的 11 套主题样品（含主题切换、搜索与筛选）在线 gallery：<https://rearticle.mmh1.top/#/gallery>。
+
+---
+
+## 这个 Skill 干什么
+
+`beautiful-article` 把原本枯燥、线性、难以消化的文字材料变成视觉体验更漂亮、阅读节奏更清晰、也更便于审阅和分享的**文章**。它**不是**网页应用生成器 —— 注意力永远在"文章"本身：更好的阅读、更好的节奏、更好的美学。最终交付物是一份自包含、可离线打开的文件（可选随附 PDF），但那是交付细节、不是目标。
+
+适合的场景：
+
+- 把一篇长 URL / PDF / DOCX / Markdown 编辑成一篇**网页长文**
+- 决策摘要 briefing、概念解释 explainer、教学步骤 tutorial、复盘 review、方案分析
+- 视觉随笔 visual essay、对话 / 访谈 / 播客转写、交互式学习解释器
+- 任何时候你希望**比 Markdown 更好的阅读载体** —— 表格、SVG、代码、公式、复制 / 导出按钮一条龙
+
+Skill 本质上是一个**方法论 + 协作 harness**。它附带一个 Vite + React + TypeScript 脚手架，基于 [`reacticle`](https://www.npmjs.com/package/reacticle) 组件协议 —— Agent 不手写裸 HTML / CSS，而是用 prose-first 的语义组件 + 主题约束的 `Raw` 自由层来组合。
+
+---
+
+## 核心思想
+
+- **首先是一篇文章，不是应用** —— 注意力永远在文章。Raw 自由层、SVG、小工具必须服务阅读 / 解释 / 节奏 / 审美，不能喧宾夺主。
+- **Source → Plan → Build → Review 小型 harness** —— 每个项目走 6 个有编号的 phase，中间有 3 个硬 checkpoint。
+- **`reacticle` 组件协议** —— 语义化的 prose 组件（Hero / Lead / Section / Quote / Callout / Image / Formula / CodeBlock / Table …）+ 一个必须用主题 token（`--ra-*`）的 `Raw` 自由层。
+- **主题驱动设计** —— 内置 11 套 authoring profile（`tufte` / `press` / `bayer` / `bodoni` / `vignelli` / `sottsass` / `freddie` / `andy` / `fuller` / `knuth` / `shannon`），每套是给 Agent 看的 Markdown 契约，不是 CSS 文件。
+- **默认 100% 信息保留** —— 文章类型自带推荐保留比例（longform `~100%` / briefing `~50%` / visual-essay `~40%` …），用户可一句话覆盖。
+- **硬协作 checkpoint** —— Plan、首屏样张、最终交付前 Agent 必须停下来；**每个决策必须逐项独立确认，不允许打包一个"全部 OK 吗"**。
+- **默认带封面** —— 一个 3:4 书封式题图位于 TOC 之上，外壳锁死、只能用主题 token、不允许远程图片。
+- **PDF 导出可选** —— 主交付物是一份自包含的 HTML 文件；PDF 只在用户在 Checkpoint 3 主动选择时通过零依赖的 `html-to-pdf.sh` 生成。
+
+---
+
+## 工作流
+
+```text
+Phase 0  Intake
+   │
+Phase 1  Source → Markdown      （URL / PDF / DOCX / MD / 文本 → source.md）
+   │
+Phase 2  Editorial Planning     （一份 plan.md：Brief / Outline / Theme / Assets）
+   │
+★ Checkpoint 1  Plan            （5 个独立决策逐项确认）
+   │
+Phase 4  First Spread           （封面 + Hero + 第一节 + 一个代表性视觉块）
+   │
+★ Checkpoint 2  First Spread    （验收 + 后续开发模式 A/B）
+   │
+Phase 5  Full Article Build     （单 Agent 顺序 / 多 Agent 并行）
+   │
+Phase 6  Final Review           （Editorial / Visual / Technical 三视角）
+   │
+Phase 7  Repair                 （只允许最小切片修复）
+   │
+★ Checkpoint 3  Delivery        （HTML，或 HTML + PDF，或暂停修订）
+   │
+Phase 8  Delivery               （article.html，可选 article.pdf）
+```
+
+每个项目都有自己的工作区目录，作为 Agent 的**长期记忆**：
+
+```text
+<workspace>/
+  source/   original.*   source.md   source.<lang>.md（需翻译时）   extraction-notes.md
+  plan/     plan.md
+  article/  Cover.tsx   Article.tsx   sections/   raw-blocks/   assets/   article.html（产物）
+  review/   first-spread-review.md   final-review.md
+            （source-review.md 仅复杂源；repair-log.md 仅有修复时）
+  index.html  package.json  vite.config.ts  tsconfig*.json   （构建工装）
+```
+
+---
+
+## Skill 目录结构
+
+```text
+skills/beautiful-article/
+├── SKILL.md                            主 Skill 文件（frontmatter name: beautiful-article）
+├── manifest.json                       发布清单
+├── README.md  /  README.zh-CN.md       本文档
+├── references/
+│   ├── article-types.md                文章类型路由
+│   ├── article-types/                  briefing / dialogue / essay / explainer / full-report
+│   │                                    interactive-explainer / longform / review / tutorial / visual-essay
+│   ├── information-density.md          保留比例与组件 / 视觉比例的关系
+│   ├── plan-template.md                单一 plan.md 模板（Brief / Outline / Theme / Assets）
+│   ├── theme-selection.md              主题选择，density 与 theme 解耦
+│   ├── layout.md                       版式宽度、TOC 默认值
+│   ├── cover.md                        3:4 书封封面指南（5 条自检 + 5 个构图模板）
+│   ├── asset-policy.md                 配图策略（none / user-assets / placeholders / ai-generated）
+│   ├── component-policy.md             Reacticle 组件契约、prose-first
+│   ├── raw-policy.md                   Raw 允许 / 禁止表、token 驱动、自检
+│   ├── section-build.md                一节一文件铁律、subagent prompt 模板
+│   ├── source-to-markdown.md           各类输入抽取规则 + 5 条自检
+│   ├── scaffold.md                     脚手架行为、工作区结构
+│   ├── html-output.md                  dev / build / 单文件 HTML 命令
+│   ├── pdf-output.md                   html-to-pdf.sh 用法 + print CSS 覆盖
+│   ├── review-checklist.md             各阶段 reviewer 清单与 sub-agent prompt
+│   ├── repair-policy.md                最小切片修复对照表
+│   └── harness.md                      Skill-as-harness 视角
+├── theme-profiles/
+│   ├── index.json                      主题注册表
+│   └── andy / bayer / bodoni / freddie / fuller / knuth / press / shannon / sottsass / tufte / vignelli
+├── scripts/
+│   ├── scaffold.sh                     一键创建工作区
+│   ├── html-to-pdf.sh                  可选 HTML → PDF（headless 浏览器，零 npm 依赖）
+│   ├── pdf-print-overrides.css         注入 HTML 的 @media print 覆盖
+│   ├── source-to-markdown-markitdown.py  主路径抽取（PDF / DOCX / HTML）
+│   └── source-to-markdown.py           轻量 fallback（Markdown / TXT / 简单 HTML）
+└── assets/
+    └── scaffold-template/              脚手架脚本拷贝的 Vite + React + TS 模板
+```
+
+---
+
+## 它是怎么工作的（要点）
+
+### 1. 各节点的质检协议
+
+不同 phase 用不同的质检方式 —— 滥开 SubAgent、滥写 review 文件是首要性能问题，所以 Skill 把规则写明：
+
+| 节点 | 怎么检 | 产物 |
+|---|---|---|
+| Phase 1 Source（默认） | 主 Agent 内联 5 条 checklist | 无文件 |
+| 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` |
+
+### 2. 禁止静默替用户选择
+
+每个 Checkpoint 的每一项决策必须**独立**问 —— Agent 可以推荐，但不能"我已经替你定了 X，不对再说"。Plan Checkpoint 5 项独立决策：文章类型（含推荐保留比例）/ 主题 / 版式宽度 / 配图模式 / 封面开关。
+
+### 3. 文章类型 → 保留比例打包
+
+10 种文章类型都自带推荐保留比例：`longform · ~100%` / `tutorial · ~90%` / `full-report · ~80%` / `explainer · ~80%` / `dialogue · ~80%` / `review · ~70%` / `essay · ~70%` / `briefing · ~50%` / `visual-essay · ~40%` / `interactive-explainer · ~25% 摘录 + 75% AI 重构`。用户可一句话覆盖。
+
+### 4. 一节一文件铁律
+
+每个 Section 都是 `article/sections/NN-*.tsx` 单文件组件。`Article.tsx` 只是 assembler —— 由主 Agent 拥有，负责 import 与排序、跑 typecheck / build、解决主题漂移。这是后续多 Agent 并行的前提。
+
+### 5. 全程主题 token
+
+`Raw` 块必须只用 `--ra-*` 主题 token —— 不允许野生颜色 / 字体。换主题时所有 Raw 块一处生效。每个主题都有一份 Markdown authoring profile，告诉 Agent 在该主题下怎么写、怎么排版。
+
+---
+
+## 创建一个项目
+
+Skill 不预先创建工作区 —— 每个项目自己开。来自 Phase 4 的命令：
+
+```bash
+# 默认开封面
+bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=tufte
+
+# 关闭封面
+bash <path-to-skill>/scripts/scaffold.sh ./my-article --theme=press --no-cover
+
+# 查看可用主题
+bash <path-to-skill>/scripts/scaffold.sh --list-themes
+```
+
+脚手架会拉起 Vite + React + TS 工作区，从 npm 装最新 `reacticle`，并放好 `source/ plan/ review/` 三个目录 + `article/Article.tsx` / `article/Cover.tsx` / `article/sections/01-opening.tsx` 三份起点文件。
+
+Phase 5 完成后 Agent 跑构建产出单文件 HTML：
+
+```bash
+npm run build           # → article/article.html（CSS + JS 全内联）
+```
+
+可选 PDF 导出（仅当 Checkpoint 3 用户选了 HTML + PDF）：
+
+```bash
+bash <path-to-skill>/scripts/html-to-pdf.sh
+```
+
+---
+
+## 最佳实践
+
+### 推荐
+
+1. **先定文章类型** —— 它的保留比例锚定整个 plan。
+2. **信任 harness 的 phase** —— 不要因为"答案显而易见"就跳过 Plan checkpoint。
+3. **Raw 块只用主题 token** —— `--ra-*`，禁止裸颜色 / 字体名。
+4. **一节一文件** —— 哪怕这一节很短，也要隔离。review 与修复阶段会回报这点投入。
+5. **封面要呼应主题 + 文章主旨** —— 不是一个占位渐变。
+
+### 避免
+
+1. ❌ 把 Skill 当成"帮我做个 HTML 页面" —— 交付物是**文章**。
+2. ❌ 把多个 Checkpoint 决策打包成一个 yes/no。
+3. ❌ Raw 块自带颜色 / 字体（主题漂移）。
+4. ❌ 把所有 Section 都写进 `Article.tsx`（杀死 sub-agent 并行）。
+5. ❌ 删除 colophon / 封面外壳（这些是契约的一部分）。
+
+---
+
+## 常见问题
+
+**Q1：什么时候不应该用这个 Skill？**
+当用户其实想要的是网页应用 / dashboard / 表单 / 原型 / 通用 landing page —— 这些去找 `web-design-engineer`，不是这里。不确定时 Skill 会停下来澄清，而不是默默生成错的产物。
+
+**Q2：是不是总是 100% 信息保留？**
+不是 —— 那只是 `longform` 类型的默认值。文章类型决定推荐比例，用户可以在 Checkpoint 1 覆盖。
+
+**Q3：文章语言可以与源材料不同吗？**
+可以。如果用户指定的目标语言与源不一致，Phase 1 会先产出地道翻译版 `source/source.<lang>.md`，Phase 2+ 据此编写。
+
+**Q4：如果 Agent 运行时没有 SubAgent / Task 工具怎么办？**
+Skill 显式照顾了这种情况：主 Agent 兜底承担 SubAgent 的工作，并在 review 文件首注明"无 SubAgent 环境，主 Agent 兜底"。
+
+**Q5：为什么用 React + Vite + reacticle 而不是裸 HTML？**
+因为 Agent 需要一个稳定的、prose-first 的组件契约 —— 它要扛住多 Section 并行写作、主题切换、Raw 自由层这些场景。`npm run build` 时所有依赖会全部内联回单文件 HTML 交付。
+
+---
+
+## 工具要求
+
+Skill 假设 Agent 运行时可以：
+
+- 启动 shell 命令（用于 `scaffold.sh` / `html-to-pdf.sh` / `npm` 构建）
+- 在工作区读写文件
+- （可选）开启 sub-agent 来跑 First Spread / Section / Final review
+- （可选）调用 `MarkItDown`（Python）做高保真 PDF / DOCX / HTML 抽取；不可用时由轻量 fallback 脚本处理 Markdown / TXT / 简单 HTML
+
+---
+
+## 许可证
+
+MIT