teamai-test/.teamai/skills/common/beautiful-article/references/scaffold.md

脚手架

脚手架在 Phase 4 创建文章工作区，不把工程代码塞进 SKILL.md。工程模板是 Skill assets（assets/scaffold-template/），由 scripts/scaffold.sh 复制并接线。

用法

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 的依赖会被自动带下来，无需在工作区单独声明。

升级组件库

工作区随时可升级到最新组件库：

npm install reacticle@latest

工作区结构

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