fe-harness 1.0.0

package/fe-harness/workflows/map-codebase.md

@@ -0,0 +1,331 @@
+<purpose>
+编排并行前端代码库映射代理，分析代码库并在 .fe/codebase/ 中生成结构化文档。
+
+每个代理拥有独立上下文，探索特定聚焦领域，并**直接写入文档**。编排器仅接收确认 + 行数，然后输出总结。
+
+输出: .fe/codebase/ 目录，包含 7 个前端专属结构化文档。
+</purpose>
+
+<philosophy>
+**为什么使用专属映射代理:**
+- 每个领域独立上下文 (无 token 污染)
+- 代理直接写入文档 (不回传上下文给编排器)
+- 编排器仅总结创建了什么 (最小上下文占用)
+- 更快执行 (代理同时运行)
+
+**前端垂直化:**
+不同于通用代码库映射，前端映射聚焦于:
+- 组件架构与设计系统
+- 样式方案与设计 token
+- 状态管理与数据获取模式
+- 路由与页面组织
+- 前端性能指标 (LCP, CLS, INP, 包体积)
+
+**文档质量优于简洁:**
+包含足够的细节作为参考。优先提供实际的代码模式示例。
+
+**始终包含文件路径:**
+文档是 Claude 规划/执行时的参考材料。始终使用反引号格式化实际文件路径: `src/components/Button.tsx`。
+</philosophy>
+
+<process>
+
+<step name="check_existing">
+检查 .fe/codebase/ 是否已存在:
+
+```bash
+ls -la .fe/codebase/ 2>/dev/null
+```
+
+**如果目录存在且有文件:**
+
+```
+.fe/codebase/ 已存在，包含以下文档:
+[列出找到的文件]
+
+下一步?
+1. 刷新 - 删除现有映射，重新分析
+2. 更新 - 保留现有，仅更新特定文档
+3. 跳过 - 使用现有代码库映射
+```
+
+等待用户响应。
+
+如果 "刷新": 删除 .fe/codebase/，继续到 create_structure
+如果 "更新": 询问更新哪些文档，继续到 spawn_agents (过滤)
+如果 "跳过": 退出流程
+
+**如果不存在:**
+继续到 create_structure。
+</step>
+
+<step name="create_structure">
+创建 .fe/codebase/ 目录:
+
+```bash
+mkdir -p .fe/codebase
+```
+
+**预期输出文件:**
+- STACK.md (来自 tech 映射器) — 前端技术栈
+- COMPONENTS.md (来自 ui 映射器) — 组件架构与设计系统
+- STYLING.md (来自 ui 映射器) — 样式方案与设计 token
+- STATE.md (来自 tech 映射器) — 状态管理与数据获取
+- STRUCTURE.md (来自 structure 映射器) — 目录结构与路由
+- CONVENTIONS.md (来自 structure 映射器) — 前端编码惯例
+- CONCERNS.md (来自 concerns 映射器) — 前端问题与技术债
+
+继续到 spawn_agents。
+</step>
+
+<step name="spawn_agents">
+生成 4 个并行 fe-codebase-mapper 代理。
+
+使用 Agent 工具，`subagent_type="general-purpose"`，`run_in_background=true` 并行执行。
+
+**代理 1: 技术聚焦 (Tech Focus)**
+
+```
+Agent(
+  run_in_background=true,
+  subagent_type="general-purpose",
+  model="haiku",
+  description="映射前端技术栈",
+  prompt="你是前端代码库映射代理。
+
+聚焦: tech
+
+分析此前端代码库的技术栈和状态管理模式。
+
+写入以下文档到 .fe/codebase/:
+- STACK.md — 前端框架、构建工具、TypeScript 配置、包管理器、关键依赖
+- STATE.md — 状态管理方案、数据获取模式、表单管理、URL 状态
+
+**探索方法:**
+1. 读取 package.json 分析依赖
+2. 查找框架配置文件 (next.config.*, vite.config.*, nuxt.config.*, angular.json 等)
+3. 查找 TypeScript 配置 (tsconfig.json)
+4. 搜索状态管理库的使用 (redux, zustand, jotai, pinia, vuex, @tanstack/react-query, swr 等)
+5. 分析数据获取模式 (fetch, axios, graphql 等)
+
+使用 @~/.claude/agents/fe-codebase-mapper.md 中的模板。
+深入探索。直接使用 Write 工具写入文档。仅返回确认信息。"
+)
+```
+
+**代理 2: UI 聚焦 (UI Focus)**
+
+```
+Agent(
+  run_in_background=true,
+  subagent_type="general-purpose",
+  model="haiku",
+  description="映射前端组件与样式",
+  prompt="你是前端代码库映射代理。
+
+聚焦: ui
+
+分析此前端代码库的组件架构和样式方案。
+
+写入以下文档到 .fe/codebase/:
+- COMPONENTS.md — 组件库/设计系统、组件模式、Props 惯例、复合组件、图标系统
+- STYLING.md — CSS 方案、设计 token、主题系统、响应式策略、暗色模式、动画
+
+**探索方法:**
+1. 查找组件目录 (src/components/, src/ui/, components/, app/components/ 等)
+2. 分析组件模式 (函数组件、HOC、render props、compound components)
+3. 查找 UI 库依赖 (antd, @mui, shadcn, @radix-ui, element-plus, arco-design 等)
+4. 分析 CSS 方案 (Tailwind, CSS Modules, styled-components, Sass, Less, UnoCSS 等)
+5. 查找设计 token 或主题配置
+
+使用 @~/.claude/agents/fe-codebase-mapper.md 中的模板。
+深入探索。直接使用 Write 工具写入文档。仅返回确认信息。"
+)
+```
+
+**代理 3: 结构聚焦 (Structure Focus)**
+
+```
+Agent(
+  run_in_background=true,
+  subagent_type="general-purpose",
+  model="haiku",
+  description="映射前端结构与惯例",
+  prompt="你是前端代码库映射代理。
+
+聚焦: structure
+
+分析此前端代码库的目录结构和编码惯例。
+
+写入以下文档到 .fe/codebase/:
+- STRUCTURE.md — 目录布局、路由方案、页面组织、功能模块结构、新代码放置指南
+- CONVENTIONS.md — 命名模式、组件命名、Hooks 模式、TypeScript 模式、导入组织、代码风格
+
+**探索方法:**
+1. 分析目录结构 (find . -type d 排除 node_modules)
+2. 查找路由配置 (pages/, app/, router/, routes/ 等)
+3. 分析文件命名模式
+4. 查找 lint/format 配置 (.eslintrc*, .prettierrc*, biome.json 等)
+5. 读取示例文件分析编码惯例
+6. 查找自定义 hooks 的模式
+
+使用 @~/.claude/agents/fe-codebase-mapper.md 中的模板。
+深入探索。直接使用 Write 工具写入文档。仅返回确认信息。"
+)
+```
+
+**代理 4: 问题聚焦 (Concerns Focus)**
+
+```
+Agent(
+  run_in_background=true,
+  subagent_type="general-purpose",
+  model="haiku",
+  description="映射前端问题与技术债",
+  prompt="你是前端代码库映射代理。
+
+聚焦: concerns
+
+分析此前端代码库的技术债、性能问题和潜在风险。
+
+写入以下文档到 .fe/codebase/:
+- CONCERNS.md — 性能问题(包体积/渲染/Core Web Vitals)、可访问性差距、技术债、浏览器兼容、测试覆盖缺口
+
+**探索方法:**
+1. 搜索 TODO/FIXME/HACK 注释
+2. 查找大型文件 (>500行的组件可能需要拆分)
+3. 分析包体积 (检查大型依赖如 moment.js, lodash 全量导入)
+4. 检查可访问性 (搜索 aria-*, role, alt 属性的使用情况)
+5. 查找性能反模式 (内联函数创建、缺少 memo/useMemo、大型列表无虚拟化)
+6. 检查测试覆盖 (查找测试文件分布)
+7. 检查 any 类型使用、ts-ignore 等 TypeScript 问题
+
+使用 @~/.claude/agents/fe-codebase-mapper.md 中的模板。
+深入探索。直接使用 Write 工具写入文档。仅返回确认信息。"
+)
+```
+
+继续到 collect_confirmations。
+</step>
+
+<step name="collect_confirmations">
+等待所有 4 个代理完成。
+
+Agent 工具会在后台代理完成时自动通知。收集所有 4 个代理的确认。
+
+**预期确认格式:**
+```
+## 映射完成
+
+**聚焦:** {focus}
+**已写入文档:**
+- `.fe/codebase/{DOC1}.md` ({N} 行)
+- `.fe/codebase/{DOC2}.md` ({N} 行)
+
+已就绪。
+```
+
+**你收到的:** 仅文件路径和行数，不是文档内容。
+
+如果任何代理失败，记录失败并继续处理成功的文档。
+
+继续到 verify_output。
+</step>
+
+<step name="verify_output">
+验证所有文档是否成功创建:
+
+```bash
+ls -la .fe/codebase/
+wc -l .fe/codebase/*.md
+```
+
+**验证清单:**
+- 所有 7 个文档存在
+- 没有空文档 (每个应有 >20 行)
+
+如果有文档缺失或为空，记录哪些代理可能失败了。
+
+继续到 scan_for_secrets。
+</step>
+
+<step name="scan_for_secrets">
+**关键安全检查:** 扫描输出文件中是否意外泄露了密钥。
+
+```bash
+grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .fe/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
+```
+
+**如果 SECRETS_FOUND=true:**
+警告用户并等待确认后再继续。
+
+**如果 SECRETS_FOUND=false:**
+继续到 commit_codebase_map。
+</step>
+
+<step name="commit_codebase_map">
+提交代码库映射文档:
+
+```bash
+git add .fe/codebase/*.md
+git commit -m "docs: 映射前端代码库结构"
+```
+
+如果提交失败 (如没有 git 仓库或 pre-commit hook 失败)，记录错误但不阻塞流程，继续到 offer_next。
+
+继续到 offer_next。
+</step>
+
+<step name="offer_next">
+展示完成总结和下一步操作。
+
+```bash
+wc -l .fe/codebase/*.md
+```
+
+**输出格式:**
+
+```
+前端代码库映射完成。
+
+已创建 .fe/codebase/:
+- STACK.md ([N] 行) - 前端技术栈与依赖
+- COMPONENTS.md ([N] 行) - 组件架构与设计系统
+- STYLING.md ([N] 行) - 样式方案与设计 token
+- STATE.md ([N] 行) - 状态管理与数据获取
+- STRUCTURE.md ([N] 行) - 目录结构与路由
+- CONVENTIONS.md ([N] 行) - 前端编码惯例
+- CONCERNS.md ([N] 行) - 问题与技术债
+
+
+---
+
+## 下一步
+
+**开始规划** — 基于代码库理解创建任务计划
+
+`/fe:plan`
+
+---
+
+**其他操作:**
+- 重新映射: `/fe:map-codebase`
+- 查看特定文档: `cat .fe/codebase/STACK.md`
+- 在继续前编辑任何文档
+
+---
+```
+
+结束流程。
+</step>
+
+</process>
+
+<success_criteria>
+- .fe/codebase/ 目录已创建
+- 4 个并行 fe-codebase-mapper 代理使用 run_in_background=true 生成
+- 所有 7 个代码库文档存在
+- 没有空文档 (每个应有 >20 行)
+- 清晰的完成总结包含行数
+- 用户获得明确的下一步操作指引
+</success_criteria>

package/fe-harness/workflows/plan.md

@@ -0,0 +1,244 @@
+# 任务规划工作流
+
+## 概述
+解析用户输入的功能列表和 Figma URL，通过设计分析、多轮讨论和智能优化创建精准的任务列表。
+
+## 流程
+
+### Step 1: 检查状态
+
+检查 `.fe-runtime/tasks.json` 是否存在：
+- 不存在 → 进入初始化阶段
+- 已存在：
+  - 用户提供了新功能列表 → 询问：重新初始化（覆盖）还是合并追加
+  - 用户没有提供新功能列表 → 显示当前状态概览（调用 `/fe:status`）
+
+### Step 2: 解析用户输入
+
+**期望的输入格式：**
+```
+功能1: 用户头像组件, figma设计稿: https://figma.com/design/xxx?node-id=1-2
+功能2: 登录页面, figma设计稿: https://figma.com/design/xxx?node-id=3-4
+功能3: 用户登录 API 对接
+功能4: 全局状态管理
+```
+
+解析每条功能，提取：
+- `name`: 功能名称
+- `figmaUrl`: Figma URL（可能没有）
+- `figmaFileKey`: 从 URL 提取
+- `figmaNodeId`: 从 URL 提取（将 `-` 转为 `:`）
+
+有 Figma URL 的 → 设计任务（视觉验证）
+无 Figma URL 的 → 逻辑任务（代码审查）
+
+### Step 3: 智能分析和优化
+
+#### 3a+3b. 并行分析（设计截图 + 项目扫描）
+
+3a（获取设计截图）和 3b（扫描现有项目）之间没有数据依赖，**必须使用 Agent 工具并行执行**。
+
+在一条消息中同时发起两个 Agent 调用，等待两者都完成后再继续：
+
+**Agent 1: 设计截图分析**
+
+```
+Agent(
+  subagent_type="general-purpose",
+  model="haiku",
+  description="获取 Figma 设计截图",
+  prompt="使用 @fe-harness/agents/fe-design-scanner.md 中的流程。
+
+设计任务列表:
+${DESIGN_TASKS_JSON}"
+)
+```
+
+**Agent 2: 项目扫描**
+
+```
+Agent(
+  subagent_type="general-purpose",
+  model="haiku",
+  description="扫描现有项目结构",
+  prompt="使用 @fe-harness/agents/fe-project-scanner.md 中的流程。"
+)
+```
+
+两个 Agent 都完成后，读取 `.fe-runtime/context/design-analysis.json` 和 `.fe-runtime/context/project-scan.json`，作为后续步骤的输入。
+
+#### 3c. 灰色地带讨论
+
+基于设计截图分析（design-analysis.json）和项目上下文（project-scan.json），识别设计稿中未明确表达的实现决策点。
+
+**识别维度：**
+- **交互行为**: 点击、悬停、动画、过渡效果等设计稿无法表达的行为
+- **响应式策略**: 不同屏幕尺寸下的布局变化、折叠/隐藏规则
+- **边界情况**: 空状态、加载状态、错误状态、超长文本、极端数据
+- **业务逻辑**: 表单验证规则、权限控制、数据流向
+- **组件复用**: 是否拆为公共组件、组件 API 设计倾向
+
+**执行方式：**
+1. 逐个任务审视设计截图，列出不确定的灰色地带
+2. 将所有灰色地带合并去重，按优先级排序
+3. 用 `AskUserQuestion` 逐个或分组提问（每个问题提供 2-4 个选项 + 推荐项）
+4. 如果用户回复"跳过"或"都行"，使用推荐默认值
+5. 将所有决策记录到内存中，传递给下一步优化（最终写入各任务的 `techNotes` 字段）
+
+**控制节奏：**
+- 聚焦于真正影响实现方向的决策，避免问琐碎细节（如颜色、字号等设计稿已明确的内容）
+- 每轮可利用 `AskUserQuestion` 的多问题能力（最多 4 个问题/轮）批量提问
+- 讨论持续到所有重要灰色地带都有明确决策为止，不设硬性轮次上限
+- 如果用户回复"够了"或"剩下的你决定"，立即结束讨论，未决项使用推荐默认值
+
+#### 3c+. 反问确认
+
+灰色地带讨论结束后，主动反问用户是否还有补充：
+
+```
+AskUserQuestion(
+  question: "在我开始生成最终任务列表之前，你还有什么需要和我讨论的吗？",
+  header: "补充讨论",
+  options: [
+    { label: "没有，继续", description: "所有需要讨论的内容已经覆盖，直接进入任务优化阶段" }
+  ]
+)
+```
+
+- 用户选择「没有，继续」→ 直接进入 3d
+- 用户选择「Other」并输入补充内容 → 针对补充内容继续讨论，讨论完毕后再次反问，直到用户选择「没有，继续」
+
+#### 3d. AI 驱动优化（6 个维度）
+
+基于用户输入、设计截图、项目上下文，以及**灰色地带讨论中的决策结果**，进行智能优化：
+
+1. **名称优化**: 使名称更精确、可操作
+2. **描述充实**: 为每个任务生成三个维度的描述：
+   - `description`: 功能描述（做什么）
+   - `acceptanceCriteria`: 验收条件数组（怎么算做好了，verifier/reviewer 的判定标准）
+   - `techNotes`: 实现提示（怎么做：复用哪些现有组件、灰色地带讨论决策、技术方案等）
+3. **粒度拆分**: 过大的任务拆分为更小的子任务
+4. **粒度合并**: 过于琐碎的相关任务合并
+5. **缺口识别**: 发现遗漏的任务（例如需要但未列出的公共组件、API 对接等）
+6. **路由推断**: 根据项目路由方案（project-scan.json）和功能描述，为每个任务推断 `route`（dev server 中的可访问路径）
+7. **文件所有权声明**: 为每个任务声明 `filesModified`（预计修改的文件路径列表）
+
+**文件所有权规则（用于并行执行冲突检测）：**
+- 每个任务必须声明 `filesModified` 字段，列出预计创建或修改的文件
+- 同一 Wave 内的任务，`filesModified` 不允许有交集（否则并行 worktree 合并会冲突）
+- 如果检测到同 wave 内文件冲突，有两种处理方式：
+  1. 将冲突任务加入 `dependsOn`，使其分到不同 wave（串行执行）
+  2. 将冲突任务合并为一个任务
+- 文件路径粒度：使用文件级，不使用目录级（如 `src/components/Avatar.tsx` 而非 `src/components/`）
+- 公共文件（如 `src/App.tsx`, `src/router.ts`, `package.json`）：多个任务可能都需要修改的公共文件，应通过 `dependsOn` 确保这些任务分到不同 wave
+
+#### 3e. 展示优化后的任务列表
+以表格形式展示优化后的任务列表，自动继续（不需要用户确认）。
+
+### Step 4: 确认配置完整
+
+读取 `.fe/config.jsonc`，**仅当存在设计任务时**检查 `devServerCommand` 是否已填写。
+- 有设计任务（含 figmaUrl 的任务）且未配置 → 提示用户先编辑 `.fe/config.jsonc` 配置开发服务器启动命令
+- 全部都是逻辑任务 → 跳过此检查，不需要开发服务器
+
+### Step 5: 创建任务文件
+
+写入 `.fe-runtime/tasks.json`，每个任务的 schema：
+```json
+{
+  "id": 1,
+  "name": "功能名称",
+  "description": "功能描述（做什么）",
+  "acceptanceCriteria": ["验收条件1", "验收条件2"],
+  "techNotes": "实现提示（复用哪些组件、灰色地带决策、技术方案等）",
+  "route": "/page-path",
+  "figmaUrl": "https://...",
+  "figmaFileKey": "xxx",
+  "figmaNodeId": "1:2",
+  "dependsOn": [],
+  "filesModified": ["src/components/Avatar.tsx", "src/components/Avatar.css"],
+  "status": "pending",
+  "verifyPassed": false,
+  "retryCount": 0,
+  "bestScore": 0,
+  "bestScoresJSON": null,
+  "lastError": "",
+  "completedAt": ""
+}
+```
+
+**`route` 字段说明：**
+- 填写该功能实现后在 dev server 中可访问的页面路径（如 `"/login"`, `"/settings/profile"`）
+- 如果是全局组件/工具函数（不对应特定页面），填 `"/"`
+- executor 自检、verifier 验证、fixer 自检都依赖此字段导航到正确页面
+
+依赖关系和文件所有权规则：
+- `dependsOn` 通过分析任务间的逻辑关系自动生成
+- `filesModified` 通过分析设计稿和项目结构推断
+- 同一 wave 内任务的 `filesModified` 不允许交集
+
+### Step 5b: Wave 分组与冲突检测
+
+任务写入后，调用 fe-tools 验证 wave 分组：
+
+```bash
+WAVES=$(node ~/.claude/fe-harness/bin/fe-tools.cjs tasks waves)
+```
+
+**Wave 分组基于 `dependsOn` 自动计算（拓扑排序）：**
+- Wave 1: 无依赖的任务（可并行执行）
+- Wave 2: 仅依赖 Wave 1 的任务（可并行执行）
+- Wave N: 依赖 Wave N-1 的任务
+
+**文件冲突检测：**
+
+```bash
+CONFLICTS=$(node ~/.claude/fe-harness/bin/fe-tools.cjs tasks check-conflicts)
+```
+
+如果检测到同 wave 内文件冲突：
+1. 输出冲突详情：哪些任务、哪些文件有冲突
+2. 自动将冲突任务添加 `dependsOn` 关系，使其分到不同 wave
+3. 重新计算 wave 分组
+
+**展示格式：**
+```
+## Wave 执行计划
+
+| Wave | 任务 | 类型 | 并行 |
+|------|------|------|------|
+| 1 | #1 用户头像组件, #2 登录表单 | design, design | ✓ |
+| 2 | #3 API 对接 | logic | - |
+
+文件所有权:
+- #1: src/components/Avatar.tsx, src/components/Avatar.css
+- #2: src/components/LoginForm.tsx, src/components/LoginForm.css
+- #3: src/api/auth.ts, src/components/LoginForm.tsx (→ 依赖 #2)
+```
+
+如果所有任务都在同一个 wave（无依赖关系且无文件冲突），提示用户："所有任务无依赖关系，将在 Wave 1 中并行执行。"
+
+### Step 6: 创建进度文件
+
+写入 `.fe-runtime/progress.md`：
+```markdown
+# Figma Implementation Progress
+
+## 项目信息
+- 创建时间: {timestamp}
+- 任务总数: {count}
+- 设计任务: {design_count}
+- 逻辑任务: {logic_count}
+
+## 执行日志
+```
+
+### Step 7: 完成
+
+输出规划完成信息和 wave 执行计划，提示用户先清除上下文再开始执行。
+
+提示信息应包含：
+- 任务总数和 wave 数
+- 每个 wave 的任务数和并行执行能力
+- 预期的执行流程："Wave 1 (3个任务并行) → Wave 2 (2个任务并行) → ..."
+- 提示用户：「规划已完成并写入 `.fe/` 目录。建议先执行 `/clear` 清除上下文，再使用 `/fe:execute` 开始执行，以获得更充裕的上下文空间。」

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "fe-harness",
+  "version": "1.0.0",
+  "description": "Figma design-to-code harness for Claude Code. Subagent-driven implementation, visual verification, and iterative fixing.",
+  "scripts": {
+    "build": "node scripts/bundle-puppeteer.js",
+    "test": "node --test fe-harness/bin/lib/__tests__/*.test.cjs"
+  },
+  "bin": {
+    "fe-harness": "bin/install.js"
+  },
+  "files": [
+    "bin",
+    "commands",
+    "agents",
+    "fe-harness",
+    "scripts"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "figma",
+    "design-to-code",
+    "visual-verification",
+    "subagent"
+  ],
+  "author": "qidian",
+  "license": "MIT",
+  "devDependencies": {
+    "puppeteer-core": "^24.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/scripts/bundle-puppeteer.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * 将 puppeteer-core 打包为单文件 vendor/puppeteer-core.cjs
+ * 发布前运行: npm run build
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const ROOT = path.resolve(__dirname, '..');
+const ENTRY = path.join(ROOT, 'scripts', '_puppeteer-entry.cjs');
+const OUT = path.join(ROOT, 'fe-harness', 'vendor', 'puppeteer-core.cjs');
+
+// 创建临时入口：re-export puppeteer-core
+fs.writeFileSync(ENTRY, `module.exports = require('puppeteer-core');\n`);
+
+const externals = [
+  'fs', 'path', 'child_process', 'os', 'net', 'http', 'https',
+  'tls', 'crypto', 'stream', 'url', 'zlib', 'events', 'util',
+  'buffer', 'querystring', 'string_decoder', 'assert', 'dns',
+  'readline', 'worker_threads', 'perf_hooks', 'async_hooks',
+].map(m => `--external:${m}`).join(' ');
+
+try {
+  execSync(
+    `npx esbuild "${ENTRY}" --bundle --platform=node --target=node18 --format=cjs --outfile="${OUT}" --minify ${externals}`,
+    { cwd: ROOT, stdio: 'inherit' }
+  );
+
+  const size = (fs.statSync(OUT).size / 1024 / 1024).toFixed(1);
+  console.log(`\n✓ puppeteer-core bundled → fe-harness/vendor/puppeteer-core.cjs (${size} MB)\n`);
+} finally {
+  // 清理临时入口
+  try { fs.unlinkSync(ENTRY); } catch (_) {}
+}