[teamai] Push 87 resource(s) from XingfenD

2026-09-10 16:10:45 +08:00
parent 425c9c078a
commit 65c04def51
1314 changed files with 211681 additions and 0 deletions
@@ -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`）。