企业官网建设流程全解析

• 人工智能
• AI 技能/插件
• 提示工程

beautiful-article是 garden-skills 中把用户素材编辑、设计成单文件 HTML 网页文章的 Skill，而**脚手架（scaffold）**是在其 Phase 4（First Spread）创建文章工作区的唯一入口：它把工程模板从 Skill 资产目录复制出来、接线并注入主题，让工作区能独立于 Skill 仓库在任意目录运行。读完本文，你将掌握scaffold.sh的全部参数与内部实现、生成的工作区结构、"一个 Section 一个文件"的铁律，以及构建、预览、切主题、升级组件库的完整闭环。

为什么需要脚手架：工程代码不塞进 SKILL.md

脚手架在 Phase 4 创建文章工作区，其设计哲学是不把工程代码塞进 SKILL.md——SKILL.md 只描述工作流与决策节点，真正的 Vite / React / TS 工程模板放在 Skill 的 assets 资产目录（assets/scaffold-template/），由 scripts/scaffold.sh 复制并接线。这样带来的直接好处：

• Skill 与工程解耦：工作区可建在任意目录，不需要在某个固定仓库内；
• 模板可独立演进：模板改动只需更新 assets，SKILL.md 无需跟着改；
• 零手工初始化：目录、依赖、主题注入、封面开关全部由脚本一次性完成。

用法：三条命令创建文章工作区

脚手架只有三条核心用法（--list-themes、--theme、--no-cover可自由组合）：

# 默认开封面，用 tufte 主题 bash <path-to-beautiful-article>/scripts/scaffold.sh ./my-article --theme=tufte # 用 press 主题，同时关闭书封式封面 bash <path-to-beautiful-article>/scripts/scaffold.sh ./brief --theme=press --no-cover # 仅列出可用主题，不创建任何目录 bash <path-to-beautiful-article>/scripts/scaffold.sh --list-themes

其中<path-to-beautiful-article>指向当前仓库的skills/beautiful-article/目录。

--theme：必须是注册表中的 id

--theme的值必须是 theme-profiles/index.json 里存在的 id。从脚本的theme_exists()实现看（grep -Eq "\"id\"...\"$1\""），它直接对 index.json 做精确字段匹配，不存在的 id 会立即报错并列出可用主题退出，不会静默回退到默认主题。当前注册表包含 11 个主题：

默认主题是tufte（脚本里DEFAULT_THEME="tufte"）。每个主题还有配套的 authoring profile 文件（theme-profiles/<id>.md），写作时供 AI 阅读参考。

--no-cover：书封式文章封面开关

封面默认开：工作区会创建article/Cover.tsx（书封式封面外壳，屏幕 3:4 / PDF 独占首页）。--no-cover用于关闭封面——典型场景是 Checkpoint 1 用户选了"封面 · 关"，或文章类型为briefing/dialogue时（详见 references/cover.md 的"何时关闭封面"一节：简报类文章"打开就是干货"，封面反而是阻力）。

脚手架内部做了什么：源码级拆解

读懂 scaffold.sh 的完整流程，能让你对生成的每个文件"从哪来、为什么存在"心中有数。脚本全程使用set -euo pipefail严格模式，任何一步失败都会中止。

1. 参数解析与前置检查

• 参数循环只认三类：--list-themes（列出后exit 0）、--theme=<id>、--no-cover/--cover；未知--*参数直接报错，第一个非--参数作为目标目录TARGET，缺省值为my-article。
• 目标目录检查：若目标目录已存在且非空，直接中止（避免覆盖已有工作区）。
• npm 检查：command -v npm找不到时中止，并提示需要 npm。

2. 复制工程模板

脚本把assets/scaffold-template/下的 5 个构建工装文件复制到目标目录：

cp "$TEMPLATE/package.json" "$TARGET/package.json" cp "$TEMPLATE/vite.config.ts" "$TARGET/vite.config.ts" cp "$TEMPLATE/tsconfig.json" "$TARGET/tsconfig.json" cp "$TEMPLATE/tsconfig.node.json" "$TARGET/tsconfig.node.json" cp "$TEMPLATE/index.html" "$TARGET/index.html"

同时创建三个记忆目录source/ plan/ review/和文章源目录article/sections、article/raw-blocks、article/assets（后两者用.gitkeep占位），并复制main.tsx、Article.tsx、示例 section 组件01-opening.tsx，封面开启时额外复制Cover.tsx。

模板里的 package.json 值得注意：

• 依赖reacticle: "latest"（组件库本身不锁版本）；
• 开发依赖包含vite-plugin-singlefile——这正是"单文件 HTML、断网可打开"的关键；
• 预置五个 npm script：dev（预览）、build（tsc --noEmit && vite build）、html（构建后复制为交付物article/article.html）、typecheck、preview。

3. 注入主题 id

模板中的main.tsx与Article.tsx各有一个__THEME__占位符。脚本用perl（而非 sed，避免转义问题）做全局替换：

export RA_THEME="$THEME" perl -pi -e 's/__THEME__/$ENV{RA_THEME}/g' "$TARGET/article/main.tsx" perl -pi -e 's/__THEME__/$ENV{RA_THEME}/g' "$TARGET/article/Article.tsx"

替换结果在 main.tsx 中是<ThemeProvider theme="tufte">之类的一行；在 Article.tsx 末尾 colophon 中是· tufte theme。最后把主题名写入.theme文件，作为起步主题的记录。

4. 封面开关：标记包裹区段的两种剥法

模板main.tsx用四行__COVER_*__标记把封面相关代码"夹住"（import 段和 render 段各一对）。脚本据此做两种处理：

• COVER=1（开）：只删掉标记行本身，保留中间的import { Cover } from "./Cover"与<Cover />；
• COVER=0（关）：用 perl 的-0pe多行模式把BEGIN..END之间的内容连同标记行整段剥掉，封面完全不参与构建。

这正是文档所说"--no-cover时跳过这一步：不复制 Cover.tsx，并从 main.tsx 剥掉标记包裹的两段"的源码实现。渲染顺序也因此确定：Cover → ArticleDoc（封面在<Article>之外、TOC 之上，是兄弟节点而非被塞进正文栏）。

5. 安装依赖 + typecheck 验证

npm install # 按模板安装依赖 npm install reacticle@latest # 强制刷新到当下最新发布版

第二步刻意重复安装一次reacticle@latest——即使将来模板带了 lockfile 也会强制刷新。随后脚本用 Node 读取node_modules/reacticle/package.json的 version 字段打印实际安装版本，并跑一次npx tsc --noEmit确认接线无误（typecheck 有问题会给出警告但不中止，提示 dev / build 仍可能正常）。

依赖的自动传递：katex/prismjs作为reacticle的依赖会被自动带下来，工作区无需单独声明——这也是文档明确说明的点。

工作区结构全景

脚手架跑完后，得到的目录结构如下（以my-article为例）：

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 = 一个文件（铁律）

脚手架默认创建article/sections/01-opening.tsx示例，这个命名方式（NN-*序号前缀）本身就是铁律的体现：每个 Section 必须写成独立组件文件，坚决不允许把多个 Section 直接写进Article.tsx。Article.tsx只做组装（import + 排序），由主 Agent 拥有；示例 01-opening.tsx 展示了 Section 组件的标准写法——<Section index="01" title="...">包裹正文段落，语义组件（Aside）只作点缀，Raw自由层为本段现写、用主题 token 取色。

这条铁律是多 Agent 并行（开发模式 B，Checkpoint 2 选定）的前提：多个 subagent 各拥有一个sections/NN-*.tsx文件并行开发，互不触碰，主 Agent 负责合并与稳定性。

colophon 印记：不可删除

Article.tsx末尾自带colophon Raw 块——文本固定为Made with beautiful-article（链接到 github 仓库）· <主题> theme，样式是低对比小字、居中、走--ra-*token（见模板中 marginTop 用var(--ra-space-7)、颜色用var(--ra-color-muted)等）。这是文章的"印记"，不可删除、不可移到 Hero 旁边或浮动到角落（见 SKILL.md「默认策略」），切主题时需同步更新其中的主题名。

记忆目录：Skill 的长期记忆

source/（源材料与 source.md）、plan/（单一规划文件 plan.md）、review/（first-spread-review.md / final-review.md 等质检产物）是 Skill 决策的落盘位置，脚手架创建它们是为了不依赖聊天上下文记决策。

切换主题：两处保持一致

脚手架默认会把主题名注入到两个位置，切主题时必须两处同步修改：

1. article/main.tsx里<ThemeProvider theme="...">——控制运行时主题（一个词：tufte/press等）；
2. article/Article.tsx末尾 colophon 的· <主题> theme——控制印记里显示的主题名。

改完后npm run dev即可看到整篇（含封面、Raw、语义组件）跟随新主题刷新。这正是"主题忠实"约束的底层逻辑：所有颜色、字号、间距都通过var(--ra-*)token 取主题值，写死 hex / 字体名 / 像素值会让切主题失效。

构建 / 预览 / 交付

在工作区根目录执行的四个命令（详见 references/html-output.md）：

单文件由 vite.config.ts 中的viteSingleFile()插件产出：CSS + JS 全部内联，断网可打开、可分享——这是 Beautiful Article 的核心交付标准。

升级组件库

工作区随时可升级到最新组件库（不需要重跑脚手架）：

npm install reacticle@latest

这与脚手架内部的安装逻辑一致，保证文章始终构建在当下最新的reacticle发布版之上。

封面：默认开，3:4 书封式题图

脚手架默认创建的 Cover.tsx 是一个外壳 + 占位：外壳固定aspectRatio: "3 / 4"，宽度受两条上限约束（48rem硬上限 +calc((100vh - 8rem) * 3 / 4)从视口高度反推，保证一屏看全不用下拉）；<CoverPlaceholder />是占位内容（SVG 网格 + accent 圆 + 居中标题文字），Phase 4 时主 Agent 会把它替换为按主题 + 文章主旨定制的图文构图。

references/cover.md 给出的 5 条硬约束，正是脚手架默认外壳存在的原因：

1. 3:4 屏幕 + PDF 独占首页：aspectRatio与 max-width / margin / border 不要动，PDF 导出时pdf-print-overrides.css的 C 段负责封面后分页；
2. 图文并茂：禁止纯文字封面，必须有视觉主体 + 至少一个标题；
3. 主题忠实：颜色 / 字号 / 字重只能用--ra-*token，禁止写死 hex / 字体名 / 像素字号；
4. 内容忠实：封面视觉要呼应正文主旨，让读者"看一眼能猜出文章讲什么"；
5. offline-first：唯一硬禁项是远程图片（<img src="https://...">等），base64 raster 仅当配图模式为user-assets/ai-generated才允许且必须内联。

封面视觉用什么技术（内联 SVG / CSS 几何 / Canvas / 复杂 React 组件 / 字体排版 / 多层混搭）完全开放，判定标准是"眯眼看 3 秒"——图 OK、气质对、切主题不废、打印不错位。封面与 Hero 是互补关系：封面是"视觉钩子 + 风格定调"（图主字辅），Hero 是"框定主题 + 读者收获"（文字栏），两者不能做成同一件事。

常见问题速查

• 目标目录非空：脚手架直接中止，需另选空目录或清理后重试。
• 未知主题 id：立即报错并列出现有 11 个主题，可用--list-themes随时查看。
• 忘记封面开关：--no-cover只影响本次脚手架；已建工作区想开封面，可手动复制模板 Cover.tsx 并恢复 main.tsx 的 import 与渲染。
• 想改主题：同步改main.tsx的<ThemeProvider theme="...">和Article.tsxcolophon 两处，然后npm run dev验证。
• PDF 导出：先npm run html生成article/article.html，再跑bash <path-to-beautiful-article>/scripts/html-to-pdf.sh（脚本自动探测系统 chromium-family 浏览器、注入@media print覆盖、headless 打印，零 npm 依赖）；注意 Raw 交互在 PDF 里只渲染为初始态，interactive-explainer类型是否导 PDF 由用户在 Checkpoint 3 决定。

整套脚手架的设计闭环是：一次命令 → 可运行的工作区 → 铁律约束的文件布局 → 可预览可构建可交付的单文件 HTML，这也是beautiful-article从素材到成品能稳定推进的工程基础。

• 人工智能
• AI 技能/插件
• 提示工程