create-yss-spec 1.0.0

package/template/.pi/skills/beautiful-article/assets/scaffold-template/article/Cover.tsx

@@ -0,0 +1,172 @@
+// Cover.tsx —— 文章封面（独立于 Article，位于 TOC + 正文 + colophon 之上）
+//
+// 这一文件是 article-specific 的（跟 Article.tsx / sections/*.tsx 同等地位）。
+// 主 Agent 在 Phase 4 First Spread 把下面的【封面内容区】替换成按 **主题 + 文章主旨**
+// 定制的设计。**外壳（3:4 比例、定位、PDF 分页）不要动**。
+//
+// 硬约束（详见 references/cover.md）：
+//   1. **3:4 比例固定（屏幕 + PDF）**：不要改 aspectRatio；打印时 .ra-cover 会自动
+//      独占首页，保持屏幕版 3:4 构图以避免 Chromium print 裁切内部布局。
+//      让内部元素用百分比 / aspect-ratio / inset 自适应，不要写绝对 px 高度。
+//   2. **图文并茂**：必须有视觉元素 + 简短文字（标题 + 可选副题 / 小标签）。
+//      **禁止纯文字封面**。视觉用什么技术由你选（见约束 5）。
+//   3. **主题忠实**：颜色 / 字号 / 字重 / 边框 / 律动**只能用 `--ra-*` token**。
+//      切主题时封面要跟随刷新；不要写死颜色 / 字体名 / 像素字号。
+//   4. **内容忠实**：封面的视觉主图与文字要呼应正文主旨（看一眼能猜出文章是讲什么的）。
+//   5. **技术自由**：内联 SVG / CSS 几何 / Canvas / 复杂 React 组件 / 字体艺术 / 多层
+//      gradient / mask / clip-path / 任意组合 —— 任选，最终效果好就行。**唯一禁止**：
+//      远程图片（offline-first）；base64 raster 仅当 Plan Checkpoint "配图模式" 是
+//      user-assets / ai-generated 才允许。
+//   6. **封面不承担正文**：不要把 Lead 第一段、TOC、阅读时间塞进来 —— 封面只承担
+//      "识别 + 风格信号 + 引起阅读欲望"，正文从下面的 Article 开始。
+
+export function Cover() {
+  return (
+    <section
+      className="ra-cover"
+      aria-label="文章封面"
+      data-ra-cover=""
+      style={{
+        // ── 外壳（请不要动） ──
+        position: "relative",
+        width: "100%",
+        // 屏幕上像"一本立着的书"：限宽 48rem（768px）；同时**从视口高度反推宽度**
+        // (100vh - 8rem) * 3/4，确保整个 3:4 封面**一屏看全、不用下拉**。8rem
+        // (128px) 给顶栏 / 边距 / site nav 等留出充足呼吸（典型场景 site nav 60 +
+        // 容器顶 padding 32 + 边框 1 ≈ 93px，仍有 35px 余量）。
+        // 3:4 比例由 aspect-ratio 保证不破。
+        maxWidth: "min(100%, 48rem, calc((100vh - 8rem) * 3 / 4))",
+        margin: "0 auto var(--ra-space-7, 3rem) auto",
+        aspectRatio: "3 / 4",
+        overflow: "hidden",
+        // 背景透明：让外层 .ra-root / .gx-reader 的 --ra-color-bg "纸面色" 直接透上来。
+        // 整片视觉是一张连续的纸，封面不再"自带一块色"。封面的辨识度由内部插画 + 边框
+        // + 内容排版承担。如果你的封面**确实需要**整体着色（如孟菲斯主题大色块覆盖），
+        // 可以改成 surface / surface-2 / accent-soft 等任意主题 token。
+        background: "transparent",
+        color: "var(--ra-color-fg, inherit)",
+        borderRadius: "var(--ra-radius-md, 0)",
+        border: "1px solid var(--ra-color-border, currentColor)",
+        // 让 ::before 之类的几何装饰可以铺满
+        isolation: "isolate",
+      }}
+    >
+      {/*
+        ─── 封面内容区 · 在这里写 ───
+        默认占位长这样：
+          • 一层主题感的几何装饰（SVG 网格 + 一个 accent 圆 + 描边斜线）
+          • 居中的占位标题、副题、小标签
+        构建时**替换为按文章 + 主题定制的封面**。占位是为了
+        "即使忘了替换，也不会渲染出一团乱"，但**不能交付出去**。
+      */}
+      <CoverPlaceholder />
+    </section>
+  );
+}
+
+// ────────────────────────────────────────────────────────────────────
+// 占位实现 —— 主 Agent 把 <CoverPlaceholder /> 替换成本文真正的封面。
+// 删掉这个 function 也行；保留它能让占位回退更友好。
+// ────────────────────────────────────────────────────────────────────
+function CoverPlaceholder() {
+  return (
+    <>
+      {/* 默认占位用了 SVG 是图省事，**不代表"应该用 SVG"** —— 你完全可以删掉这个
+       *  <svg>，换成 CSS 渐变层、Canvas、复杂 React 组件、字体艺术拼贴等任何能产生
+       *  漂亮视觉的方式。视觉技术由你选，效果好就行。 */}
+      <svg
+        viewBox="0 0 1200 1600"
+        preserveAspectRatio="xMidYMid slice"
+        aria-hidden="true"
+        style={{
+          position: "absolute",
+          inset: 0,
+          width: "100%",
+          height: "100%",
+          color: "var(--ra-color-border, currentColor)",
+          opacity: 0.55,
+          zIndex: 0,
+        }}
+      >
+        <defs>
+          <pattern id="ra-cover-grid" width="80" height="80" patternUnits="userSpaceOnUse">
+            <path
+              d="M 80 0 L 0 0 0 80"
+              fill="none"
+              stroke="currentColor"
+              strokeWidth="0.6"
+            />
+          </pattern>
+        </defs>
+        <rect width="1200" height="1600" fill="url(#ra-cover-grid)" />
+        <circle
+          cx="900"
+          cy="1180"
+          r="220"
+          fill="var(--ra-color-accent, currentColor)"
+          opacity="0.18"
+        />
+        <line
+          x1="80"
+          y1="1400"
+          x2="560"
+          y2="1400"
+          stroke="currentColor"
+          strokeWidth="2"
+        />
+      </svg>
+
+      {/* 文字层 */}
+      <div
+        style={{
+          position: "absolute",
+          inset: 0,
+          zIndex: 1,
+          display: "grid",
+          alignContent: "center",
+          justifyItems: "start",
+          padding:
+            "var(--ra-space-7, 3rem) var(--ra-space-8, 4rem) var(--ra-space-7, 3rem) var(--ra-space-8, 4rem)",
+          gap: "var(--ra-space-3, 0.75rem)",
+        }}
+      >
+        <span
+          style={{
+            fontSize: "var(--ra-text-xs, 0.75rem)",
+            letterSpacing: "0.22em",
+            textTransform: "uppercase",
+            color: "var(--ra-color-muted, inherit)",
+            opacity: 0.85,
+          }}
+        >
+          COVER · 3 : 4 · 占位
+        </span>
+        <h1
+          style={{
+            margin: 0,
+            fontSize: "clamp(1.6rem, 4.6vw, var(--ra-text-4xl, 3rem))",
+            lineHeight: 1.05,
+            fontWeight: "var(--ra-font-weight-bold, 700)",
+            color: "var(--ra-color-fg, inherit)",
+            maxWidth: "70%",
+          }}
+        >
+          按文章主旨 + 主题，在此处设计封面
+        </h1>
+        <p
+          style={{
+            margin: 0,
+            fontSize: "var(--ra-text-sm, 0.95rem)",
+            color: "var(--ra-color-muted, inherit)",
+            maxWidth: "70%",
+            lineHeight: 1.4,
+          }}
+        >
+          先读 <code>references/cover.md</code> 与选定主题的 <code>theme-profiles/&lt;id&gt;.md</code>，
+          再替换 <code>CoverPlaceholder</code> 为本文专属的图文构图。视觉用什么技术（SVG /
+          CSS / Canvas / 复杂 React 组件 / 任意混搭）由你选，效果好就行；唯一禁止远程图片。
+        </p>
+      </div>
+    </>
+  );
+}

package/template/.pi/skills/beautiful-article/assets/scaffold-template/article/main.tsx

@@ -0,0 +1,26 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { ThemeProvider } from "reacticle";
+import "reacticle/styles.css";
+// __COVER_IMPORT_BEGIN__  (scaffold.sh 在 --no-cover 时剥掉这一段，连同标记)
+import { Cover } from "./Cover";
+// __COVER_IMPORT_END__
+import { ArticleDoc } from "./Article";
+
+// Entry for the self-contained single-file HTML build.
+// Theme is fixed here — change `theme` (must be a registered reacticle theme id:
+// "tufte" | "press" | …) to switch the whole look.
+//
+// 渲染顺序：Cover（封面，可选）→ ArticleDoc（含 TOC + 正文 + colophon）。
+// Cover 故意**不**塞进 <Article> 内部（那样会被挤到正文栏旁边），而是和 <ArticleDoc/>
+// 在 ThemeProvider 下做兄弟，DOM 顺序天然就是「封面 → TOC → 正文 → colophon」。
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <ThemeProvider theme="__THEME__">
+      {/* __COVER_RENDER_BEGIN__  (scaffold.sh 在 --no-cover 时剥掉这一段，连同标记) */}
+      <Cover />
+      {/* __COVER_RENDER_END__ */}
+      <ArticleDoc />
+    </ThemeProvider>
+  </StrictMode>
+);

package/template/.pi/skills/beautiful-article/assets/scaffold-template/article/sections/01-opening.tsx

@@ -0,0 +1,30 @@
+import { Section, Aside, Raw } from "reacticle";
+
+// One Section per file. In parallel builds a single subagent owns this file and
+// must not touch Article.tsx or other section files. See references/section-build.md.
+//
+// Rules of thumb (references/component-policy.md + raw-policy.md):
+//   - Prose is the body. Write paragraphs as <Section> children.
+//   - Semantic components (Aside / Quote / Table / RiskList ...) are accents.
+//   - Raw is freely used but hand-authored for THIS section, token-driven.
+export function SectionOpening() {
+  return (
+    <Section index="01" title="第一节">
+      <p>正文段落用 children —— 这应是文章主体，尽量多写正文，把背景、推理、结论讲清楚。</p>
+      <p>再写一段，保持阅读节奏。语义组件只在内容确实"是"那个结构时才用。</p>
+
+      <Aside tone="principle" label="核心判断">一句话的核心判断，给本节点睛。</Aside>
+
+      <Raw title="为本段现写的内联 SVG（用主题 token 取色）">
+        <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>
+  );
+}

package/template/.pi/skills/beautiful-article/assets/scaffold-template/index.html

@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Beautiful Article</title>
+    <!-- Theme fonts. tufte falls back to Georgia; press uses Newsreader. -->
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link
+      href="https://fonts.googleapis.com/css2?family=Newsreader:opsz,wght@6..72,400;6..72,500&family=Source+Serif+4:opsz,wght@8..60,400&family=JetBrains+Mono:wght@400;500&display=swap"
+      rel="stylesheet"
+    />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/article/main.tsx"></script>
+  </body>
+</html>

package/template/.pi/skills/beautiful-article/assets/scaffold-template/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "beautiful-article-workspace",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc --noEmit && vite build",
+    "html": "npm run build && node -e \"require('fs').mkdirSync('article',{recursive:true});require('fs').copyFileSync('dist/index.html','article/article.html');console.log('built article/article.html')\"",
+    "typecheck": "tsc --noEmit",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "reacticle": "latest"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.6.3",
+    "vite": "^5.4.11",
+    "vite-plugin-singlefile": "^2.0.3"
+  }
+}

package/template/.pi/skills/beautiful-article/assets/scaffold-template/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["article"]
+}

package/template/.pi/skills/beautiful-article/assets/scaffold-template/tsconfig.node.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "noEmit": true
+  },
+  "include": ["vite.config.ts"]
+}

package/template/.pi/skills/beautiful-article/assets/scaffold-template/vite.config.ts

@@ -0,0 +1,18 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+// reacticle is consumed from the published npm package (see package.json).
+// Builds a self-contained single-page HTML (CSS + JS inlined, opens offline)
+// to dist/index.html. `npm run html` then copies it to article/article.html.
+export default defineConfig({
+  plugins: [react(), viteSingleFile()],
+  build: {
+    outDir: "dist",
+    emptyOutDir: true,
+    rollupOptions: {
+      input: resolve(__dirname, "index.html"),
+    },
+  },
+});

package/template/.pi/skills/beautiful-article/manifest.json

@@ -0,0 +1,15 @@
+{
+  "name": "beautiful-article",
+  "version": "0.1.0",
+  "category": "Editorial · Any source → beautiful article",
+  "description": "Edit and design any source material (URL / PDF / DOCX / Markdown / plain text / screenshots / pasted notes) into a beautiful, share-ready article. Built on the reacticle component protocol with a theme-constrained Raw layer; runs a small source -> plan -> double-confirmation -> build -> final review -> repair harness, defaulting to 100% information retention long-form articles.",
+  "homepage": "https://github.com/ConardLi/garden-skills/tree/main/skills/beautiful-article",
+  "compat": [
+    "claude-code",
+    "claude-ai",
+    "cursor",
+    "codex-cli",
+    "gemini-cli",
+    "opencode"
+  ]
+}

package/template/.pi/skills/beautiful-article/references/article-types/briefing.md

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

package/template/.pi/skills/beautiful-article/references/article-types/dialogue.md

@@ -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` + 正文显式标注即可。

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

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

package/template/.pi/skills/beautiful-article/references/article-types/explainer.md

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

package/template/.pi/skills/beautiful-article/references/article-types/full-report.md

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

package/template/.pi/skills/beautiful-article/references/article-types/interactive-explainer.md

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

package/template/.pi/skills/beautiful-article/references/article-types/longform.md

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