wucaishi-generative-react-skill 0.1.0

package/scripts/check_h5_vw_units.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const root = process.argv[2] || "src";
+const allowedPxPatterns = [
+  /max-width\s*:\s*\d+(?:\.\d+)?px/,
+  /min-height\s*:\s*max\(\s*44px,/,
+  /border(?:-[a-z]+)?\s*:\s*1px\b/,
+  /border-(?:top|right|bottom|left)\s*:\s*1px\b/,
+  /outline\s*:\s*1px\b/,
+];
+
+function walk(dir) {
+  const entries = readdirSync(dir);
+  return entries.flatMap((entry) => {
+    const path = join(dir, entry);
+    const stat = statSync(path);
+    if (stat.isDirectory()) {
+      return walk(path);
+    }
+    return /\.(styles\.ts|styles\.tsx|tsx|ts)$/.test(entry) ? [path] : [];
+  });
+}
+
+const findings = [];
+
+for (const file of walk(root)) {
+  const source = readFileSync(file, "utf8");
+  const lines = source.split(/\r?\n/);
+
+  lines.forEach((line, index) => {
+    if (!/\d+(?:\.\d+)?px/.test(line)) {
+      return;
+    }
+    if (!/[a-zA-Z-]+\s*:.*\d+(?:\.\d+)?px/.test(line)) {
+      return;
+    }
+    if (/["'`][^"'`]*\d+(?:\.\d+)?px/.test(line)) {
+      return;
+    }
+    if (allowedPxPatterns.some((pattern) => pattern.test(line))) {
+      return;
+    }
+    findings.push({
+      file: relative(process.cwd(), file),
+      line: index + 1,
+      text: line.trim(),
+    });
+  });
+}
+
+if (findings.length > 0) {
+  console.error("H5 vw unit check failed. Convert visual px values to vw():");
+  for (const finding of findings) {
+    console.error(`${finding.file}:${finding.line} ${finding.text}`);
+  }
+  process.exit(1);
+}
+
+console.log("H5 vw unit check passed.");

package/subskills/build-version-confirm-zh/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: build-version-confirm-zh
+description: 当父 skill `component-package-workflow-zh` 进入 build、打包、打包发布、生成发布产物、准备发布、发布组件包或执行会产生可交付构建结果的命令时使用。输出和说明使用中文。
+---
+
+# 打包前版本确认 Skill
+
+这个 Skill 用于约束“打包前的版本确认流程”。目标不是决定如何构建项目，而是在真正执行构建、打包或发布相关命令前，先让用户明确本次版本号应该如何变化。
+
+## 适用场景
+
+当用户出现以下意图时触发：
+
+- 要你“打包项目”
+- 要你“执行 build”
+- 要你“出一个发布包”
+- 要你“构建生产产物”
+- 要你“准备发布”
+- 要你“发版前先帮我构建”
+
+只要任务会产出可交付构建结果，或明显进入发版流程，就应先使用本 Skill。
+
+## 不适用场景
+
+以下场景不应使用本 Skill 作为主 Skill：
+
+- 用户只是让你修改代码、修 bug、写组件、补文档
+- 用户只是运行测试、lint、typecheck
+- 用户只是问版本规则，但没有要求实际打包
+
+## 核心规则
+
+- 在执行 `build`、打包、发布前，不要默认替用户决定如何升级版本
+- 每次打包发布都必须调整版本号，不能沿用原版本直接发布
+- 必须先向用户确认本次版本号更新方式
+- 发起确认前，应先读取并告诉用户当前版本号
+- 如果用户没有明确指定，应暂停执行打包，并向用户发起确认
+- 允许用户选择：
+  - `major`（大版本，比如 `1.2.3 -> 2.0.0`，通常表示有较大变化或不兼容改动）
+  - `minor`（小版本，比如 `1.2.3 -> 1.3.0`，通常表示新增功能）
+  - `patch`（修订版本，比如 `1.2.3 -> 1.2.4`，通常表示修复问题或小改动）
+- 发布打包场景不允许选择“不修改版本”
+- 只有在用户明确给出选择后，才继续执行后续命令
+- 用户确认版本更新方式后，除主版本文件外，还必须同步修改 `manifest.json` 里的版本号，保持版本一致
+- 如果项目存在 `manifest.json`，在执行版本修改前应检查其当前版本；如发现与主版本不一致，应先告知用户
+
+## 推荐确认方式
+
+如果用户只说“帮我打包”或“执行 build”，应先用用户容易理解的中文解释来确认，不要只丢英文术语。推荐提问方式：
+
+- 当前版本是 `1.2.3`。
+- 这次打包前要把版本更新成哪一种？
+- 可以选：
+- `大版本`：例如 `1.2.3 -> 2.0.0`，一般用于大改动
+- `小版本`：例如 `1.2.3 -> 1.3.0`，一般用于新增功能
+- `修订版本`：例如 `1.2.3 -> 1.2.4`，一般用于修 bug 或小改动
+- 你回复 `大版本`、`小版本` 或 `修订版本` 都可以，我再继续打包。
+
+如果需要保留英文，也应写成中英对照，而不是只写 `major`、`minor`、`patch`。
+
+如果项目里已有对应脚本，也可以在用户确认后再选择执行：
+
+- `npm run build`
+
+## 执行顺序
+
+处理打包任务时，按下面顺序思考：
+
+1. 先识别这是不是一次真正的打包 / 构建 / 发版动作。
+2. 读取项目当前版本号；如果项目存在 `manifest.json`，一并读取其中的版本号。
+3. 检查用户是否已经明确说明本次版本策略。
+4. 如果没有说明，先告诉用户当前版本，再确认版本策略，不要直接执行构建命令。
+5. 如果发现主版本文件和 `manifest.json` 版本不一致，应先告知用户，再继续确认或修改流程。
+6. 用户确认后，先同步更新主版本文件和 `manifest.json` 中的版本。
+7. 完成版本同步后，再执行构建命令。
+
+## 输出要求
+
+- 所有确认和说明使用中文。
+- 询问要简洁，不要一次抛出太多额外问题。
+- 不要默认替用户选 `patch`。
+- 不要把“打包成功”建立在隐式修改版本号的前提上。
+- 不要假设用户理解 `major`、`minor`、`patch` 这些英文术语。
+- 提示用户做选择前，要先明确说出当前版本，例如“当前版本是 `1.2.3`”。
+- 本次必须修改版本号，要确保 `manifest.json` 中的版本也同步更新，不要只改一处。
+- 优先使用 `大版本 / 小版本 / 修订版本` 这样的中文表达。
+- 最好附一个像 `1.2.3 -> 1.2.4` 这样的例子，帮助用户快速判断。
+
+## 边界
+
+- 这个 Skill 只负责“打包前是否改版本、改哪一级”的确认流程。
+- 这个 Skill 不负责定义项目自己的发布语义。
+- 这个 Skill 不负责自动生成 changelog、tag 或 release note，除非用户额外要求。

package/subskills/html-template-to-react-components-zh/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: html-template-to-react-components-zh
+description: 当父 skill `component-package-workflow-zh` 需要从移动端 HTML 预览、HTML 模板、模板说明 Markdown、场景模块表格中拆分独立 React 组件包，或需要把模板说明字段约束转成 Props、schema、manifest 时使用。输出和说明使用中文。
+---
+
+# HTML 模板拆 React 组件 Skill
+
+这个子 Skill 用于把“一个包含多个模块的移动端 HTML 视觉预览”和“模板说明 Markdown”拆成多个可复用 React 组件包。它只处理拆分、映射和字段契约，后续组件创建、开发、预览、打包、上传仍服从父 Skill `component-package-workflow-zh`。
+
+## 必须同时使用
+
+- 组件代码实现必须继续使用 `react-component-spec-zh`。
+- 如果进入打包或上传，继续使用 `build-version-confirm-zh` 和 `upload-aliyun-oss-zh`。
+
+## 输入要求
+
+默认需要两个文件：
+
+- HTML 文件：包含多个移动端模块，通常以 `<section class="module" id="...">` 表示一个模块。
+- 模板说明 Markdown：必须包含“场景模块”表格，且表头包含 `模块名称`、`场景模块名称`、`用户要解决的问题`、`结构规范`。
+
+### 输入文件确认
+
+当用户要求从 HTML 模板、HTML 预览、移动端 HTML、模板说明 Markdown、场景模块表格中拆分 React 组件时，不要直接运行解析脚本，也不要自行猜测文件路径。
+
+执行解析前必须先用中文向用户确认：
+
+- 本次要转换的 HTML 文件是哪一个？
+- 本次要作为字段契约来源的 Markdown 模板说明文件是哪一个？
+
+即使当前目录中只有一个明显的 HTML 文件和一个明显的 Markdown 文件，也仍然需要向用户确认文件名后再继续。
+
+如果目录中存在多个 HTML 文件或多个 Markdown 文件，必须列出候选文件路径，让用户明确选择，不能按文件名相似度自行决定。
+
+询问时必须明确说明：
+
+- HTML 文件只作为视觉、布局、交互和示例数据参考。
+- Markdown 文件才是字段契约来源，包括组件名称、组件描述、字段、约束、默认值等。
+- 如果 HTML 和 Markdown 内容冲突，以 Markdown 为准；但视觉样式以 HTML 为准。
+
+## 核心规则
+
+- 字段契约只以模板说明 Markdown 为准，HTML 只作为视觉、布局、交互和示例数据参考。
+- 生成组件的名称必须取模板说明表格中的 `场景模块名称`，不要自行改写。
+- 生成组件的描述必须取模板说明表格中的 `用户要解决的问题`，不要自行概括。
+- 发布到平台的组件名必须使用 `<中文场景或模板>_<中文组件名>_<english_component_code>`，例如 `会议总结_一句话看懂_meeting_minutes_summary`；其中中文场景或模板优先来自模板标题，中文组件名来自 `场景模块名称`，英文 code 优先使用 HTML `id` 或让用户确认。
+- `package.json` 的包名和创建模板用的目录名是机器名，应与平台组件名分开；默认使用 `english_component_code` 转成 kebab-case，例如 `meeting-minutes-summary`。
+- HTML 中出现但模板说明未声明的字段，不能自动加入 Props、`schema.ts` 或 `manifest.json`。
+- 模板说明中声明的字段，即使 HTML 示例中没有展示，也要进入 Props、`schema.ts` 和 `manifest.json`。
+- HTML 示例文案只能作为 demo data，不能替代字段约束。
+
+## 样式还原要求
+
+HTML 转 React 组件时，React 组件的计算样式必须尽量与原 HTML 对应模块一致，不能只根据 DOM 结构重写大概样式。
+
+- 必须读取并分析 HTML 中与目标 section 相关的 CSS，包括 class 选择器、父级布局、CSS 变量、字体、颜色、间距、圆角、阴影、边框、背景、字号、行高、宽高、flex/grid 布局等。
+- 必须同时考虑 `<style>` 内联样式块、元素上的 `style=""`、HTML 引用的本地 CSS 文件，以及与目标 section 有关的全局基础样式。
+- 生成 React + `styled-components` 时，应把 HTML 的视觉 token 和布局规则迁移到组件样式中。
+- 如果原 HTML 依赖全局样式、CSS 变量或 reset，需要把目标组件正常显示所需的最小样式一并迁移。
+- 如果 HTML 引用远程 CSS 或缺失的 CSS 文件，应告知用户无法完整还原，并请求提供对应 CSS 文件或确认继续。
+- 如果某些样式无法可靠迁移，必须在实现前说明不确定点，不能静默忽略。
+- 本地 demo 中渲染出来的组件默认视觉效果应与 HTML 对应模块尽量一致。
+
+## 推荐流程
+
+1. 先确认输入文件，明确本次使用的 HTML 文件和 Markdown 模板说明文件；未确认前不要运行解析脚本。
+
+2. 运行解析脚本生成模块契约：
+
+```bash
+node .agents/skills/component-package-workflow-zh/subskills/html-template-to-react-components-zh/scripts/analyze_template_pair.mjs \
+  --html 移动端HTML预览.html \
+  --template 模板说明.md \
+  --out /tmp/template-contract.json
+```
+
+3. 先检查契约中的 `modules`，确认每个模块都正确映射：
+   - `componentDisplayName` 等于 `场景模块名称`
+   - `componentDescription` 等于 `用户要解决的问题`
+   - `fields` 来自 `结构规范` 的顶层字段
+   - `htmlId` 对应 HTML 中的模块 id
+
+4. 对每个要生成的模块，按父 Skill 流程创建组件包模板；创建前仍需完成组件名称存在性校验。
+
+5. 在模板基础上实现 React 组件：
+   - 视觉结构参考对应模块的 `bodyHtml`、`classNames` 和原 HTML 样式。
+   - 必须分析目标模块相关 CSS，并把必要的计算样式迁移到 `styled-components`。
+   - Props、`schema.ts`、`manifest.json` 以契约中的 `fields` 和 `constraints` 为准。
+   - 折叠、勾选、横滑等交互转成 React 状态，不把状态写死在 DOM 属性里。
+
+6. 完成后运行契约校验脚本：
+
+```bash
+node .agents/skills/component-package-workflow-zh/subskills/html-template-to-react-components-zh/scripts/validate_component_contract.mjs \
+  --contract /tmp/template-contract.json \
+  --module 模块htmlId或场景模块名称 \
+  --manifest 组件包/src/manifest.json \
+  --schema 组件包/src/schema.json
+```
+
+如果项目的 `schema.ts` 不是 JSON，先人工对照契约检查，或导出一份等价 JSON 再运行脚本。
+
+7. 生成组件后必须启动本地预览，对比原 HTML 目标模块与 React 本地 demo 的视觉表现；如发现明显差异，应优先修复样式差异，再进入打包或上传。
+
+## 输出约定
+
+向用户说明拆分结果时，使用以下字段：
+
+| 输出项 | 来源 |
+| --- | --- |
+| 组件名称 | `场景模块名称` |
+| 组件描述 | `用户要解决的问题` |
+| 字段约束 | `结构规范` |
+| 视觉参考 | HTML 对应 section |
+| 平台组件名 | `<中文场景或模板>_<场景模块名称>_<english_component_code>` |
+| 包名建议 | `english_component_code` 转 kebab-case 后的机器名 |
+
+反馈给用户时还必须说明：
+
+- 已使用的 HTML 文件路径
+- 已使用的 Markdown 文件路径
+- 目标模块对应的 HTML section id
+- 本地预览是否已与 HTML 对应模块完成视觉对比
+
+## 常见错误
+
+- 不要把 `模块名称` 当成组件名称；组件名称必须用 `场景模块名称`。
+- 不要把平台组件名简化成纯英文；发布平台、名称校验和 `manifest.json.name` 必须使用 `<中文场景或模板>_<中文组件名>_<english_component_code>`。
+- 不要把中文平台组件名直接作为 `package.json.name` 或本地目录名；机器名使用 `english_component_code` 的 kebab-case。
+- 不要把 HTML 里的预览摘要、示例表格列或补充文案当成新增字段。
+- 不要因为 HTML 视觉一致而省略模板说明中的字段上限、枚举和固定标题。
+- 不要让 `manifest.json` 的 `name` 和 `description` 脱离模板说明字段。
+- 不要在用户确认 HTML 和 Markdown 文件前自行运行解析脚本。
+- 不要忽略 HTML 中真实 CSS，只凭视觉印象重写近似样式。

package/subskills/html-template-to-react-components-zh/scripts/analyze_template_pair.mjs

@@ -0,0 +1,377 @@
+#!/usr/bin/env node
+
+import { readFile, writeFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+const FIELD_PROP_NAMES = new Map([
+  ["标题", "title"],
+  ["摘要", "summary"],
+  ["主线列表", "mainLineList"],
+  ["主线标题", "mainLineTitle"],
+  ["说明", "description"],
+  ["适配度", "fitScore"],
+  ["适配结论", "fitConclusion"],
+  ["结论说明", "conclusionDescription"],
+  ["评分依据", "scoreBasis"],
+  ["适配证据列表", "fitEvidenceList"],
+  ["适配维度", "fitDimension"],
+  ["表现证据", "performanceEvidence"],
+  ["问答列表", "qaList"],
+  ["问题类型", "questionType"],
+  ["问题原意", "questionIntent"],
+  ["回答重点", "answerFocus"],
+  ["表现判断", "performanceJudgment"],
+  ["可补强点", "improvementPoint"],
+  ["积极信号列表", "positiveSignalList"],
+  ["保留信号列表", "reservedSignalList"],
+  ["信号描述", "signalDescription"],
+  ["录音依据", "audioEvidence"],
+  ["风险列表", "riskList"],
+  ["风险点", "riskPoint"],
+  ["对话表现", "dialoguePerformance"],
+  ["可能疑虑", "possibleConcern"],
+  ["补强方向", "improvementDirection"],
+  ["准备列表", "preparationList"],
+  ["优先级", "priority"],
+  ["准备主题", "preparationTopic"],
+  ["准备方式", "preparationMethod"],
+  ["反问分组列表", "reverseQuestionGroupList"],
+  ["分组名称", "groupName"],
+  ["问题列表", "questionList"],
+  ["反问问题", "reverseQuestion"],
+  ["反问目的", "reverseQuestionPurpose"],
+]);
+
+function fail(message, code = 1) {
+  console.error(`错误：${message}`);
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const args = {
+    html: null,
+    template: null,
+    out: null,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const nextValue = () => {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("--")) {
+        fail(`${arg} 缺少参数值`);
+      }
+      i += 1;
+      return value;
+    };
+
+    if (arg === "-h" || arg === "--help") {
+      printHelp();
+      process.exit(0);
+    } else if (arg === "--html") {
+      args.html = nextValue();
+    } else if (arg === "--template") {
+      args.template = nextValue();
+    } else if (arg === "--out") {
+      args.out = nextValue();
+    } else {
+      fail(`未知参数：${arg}`);
+    }
+  }
+
+  if (!args.html) {
+    fail("必须传入 --html");
+  }
+  if (!args.template) {
+    fail("必须传入 --template");
+  }
+
+  return args;
+}
+
+function printHelp() {
+  console.log(`usage: analyze_template_pair.mjs --html HTML_FILE --template TEMPLATE_MD [--out OUT_JSON]
+
+解析移动端 HTML 预览和模板说明，输出可用于拆分 React 组件的模块契约。`);
+}
+
+function stripTags(value) {
+  return String(value || "")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&nbsp;/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function stripMarkdown(value) {
+  return String(value || "")
+    .replace(/`([^`]+)`/g, "$1")
+    .replace(/\*\*([^*]+)\*\*/g, "$1")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function splitMarkdownRow(line) {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((cell) => cell.trim());
+}
+
+function extractTemplateTitle(templateText) {
+  const match = templateText.match(/^#\s+(.+)$/m);
+  return match ? stripMarkdown(match[1]).replace(/模板说明$/, "") : "";
+}
+
+function extractSceneModuleRows(templateText) {
+  const lines = templateText.split(/\r?\n/);
+  const tableStart = lines.findIndex((line) =>
+    /^\|\s*顺序\s*\|\s*模块名称\s*\|\s*场景模块名称\s*\|\s*用户要解决的问题\s*\|\s*结构规范\s*\|/.test(line),
+  );
+
+  if (tableStart === -1) {
+    throw new Error("模板说明中未找到场景模块表格");
+  }
+
+  const rows = [];
+  for (let i = tableStart + 2; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!line.trim().startsWith("|")) {
+      break;
+    }
+    const cells = splitMarkdownRow(line);
+    if (cells.length < 5) {
+      continue;
+    }
+    rows.push({
+      order: Number.parseInt(cells[0], 10),
+      moduleName: stripMarkdown(cells[1]),
+      sceneModuleName: stripMarkdown(cells[2]),
+      userProblem: stripMarkdown(cells[3]),
+      structureSpec: cells.slice(4).join("|").trim(),
+    });
+  }
+
+  return rows;
+}
+
+function extractBacktickValues(text) {
+  return Array.from(String(text || "").matchAll(/`([^`]+)`/g), (match) => match[1].trim())
+    .filter(Boolean);
+}
+
+function propNameForField(fieldName, index) {
+  return FIELD_PROP_NAMES.get(fieldName) || `field${index + 1}`;
+}
+
+function extractTopLevelFields(structureSpec) {
+  const match = structureSpec.match(/字段：(.+?)(?:。|$)/);
+  const source = match ? match[1] : structureSpec;
+  return extractBacktickValues(source).map((name, index) => ({
+    name,
+    propName: propNameForField(name, index),
+    required: true,
+  }));
+}
+
+function segmentForField(structureSpec, fieldName) {
+  const escaped = fieldName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const matches = Array.from(
+    structureSpec.matchAll(new RegExp(`\`${escaped}\`([^；。|]*)`, "g")),
+    (match) => match[1].split("`")[0],
+  );
+  return (
+    matches.find((segment) => /固定为|不超过|最多|只使用/.test(segment)) ||
+    matches.at(-1) ||
+    ""
+  );
+}
+
+function extractQuotedValue(text) {
+  const match = text.match(/固定为[“"]([^”"]+)[”"]/);
+  return match ? match[1].trim() : null;
+}
+
+function extractEnum(text) {
+  const match = text.match(/只使用([^，；。]+)/);
+  if (!match) {
+    return null;
+  }
+  const values = match[1]
+    .split(/[、/]/)
+    .map((item) => item.trim())
+    .filter(Boolean);
+  return values.length > 0 ? values : null;
+}
+
+function extractConstraints(structureSpec, fields) {
+  const constraints = {};
+  const allFieldNames = extractBacktickValues(structureSpec);
+
+  allFieldNames.forEach((fieldName, index) => {
+    const propName = propNameForField(fieldName, index);
+    const segment = segmentForField(structureSpec, fieldName);
+    const fieldConstraints = {
+      sourceFieldName: fieldName,
+    };
+
+    const fixed = extractQuotedValue(segment);
+    if (fixed) {
+      fieldConstraints.fixed = fixed;
+    }
+
+    const maxLength = segment.match(/不超过\s*(\d+)\s*字/);
+    if (maxLength) {
+      fieldConstraints.maxLength = Number.parseInt(maxLength[1], 10);
+    }
+
+    const maxItems = segment.match(/最多\s*(\d+)\s*条/);
+    if (maxItems) {
+      fieldConstraints.maxItems = Number.parseInt(maxItems[1], 10);
+    }
+
+    const enumValues = extractEnum(segment);
+    if (enumValues) {
+      fieldConstraints.enum = enumValues;
+    }
+
+    if (Object.keys(fieldConstraints).length > 1) {
+      constraints[propName] = fieldConstraints;
+    }
+  });
+
+  fields.forEach((field) => {
+    constraints[field.propName] = {
+      sourceFieldName: field.name,
+      ...(constraints[field.propName] || {}),
+    };
+  });
+
+  return constraints;
+}
+
+function getAttributeValue(attributes, name) {
+  const match = attributes.match(new RegExp(`${name}\\s*=\\s*["']([^"']+)["']`, "i"));
+  return match ? match[1].trim() : "";
+}
+
+function extractClassNames(html) {
+  const names = new Set();
+  for (const match of html.matchAll(/class\s*=\s*["']([^"']+)["']/gi)) {
+    match[1].split(/\s+/).filter(Boolean).forEach((name) => names.add(name));
+  }
+  return Array.from(names).sort();
+}
+
+function extractHtmlSections(htmlText) {
+  const sections = [];
+  const sectionPattern = /<section\b([^>]*)>([\s\S]*?)<\/section>/gi;
+  for (const match of htmlText.matchAll(sectionPattern)) {
+    const attributes = match[1];
+    const fullHtml = match[0];
+    const className = getAttributeValue(attributes, "class");
+    if (!className.split(/\s+/).includes("module")) {
+      continue;
+    }
+
+    const title = fullHtml.match(/class\s*=\s*["'][^"']*\bmodule__title\b[^"']*["'][^>]*>([\s\S]*?)<\/[^>]+>/i);
+    const preview = fullHtml.match(/class\s*=\s*["'][^"']*\bmodule__preview\b[^"']*["'][^>]*>([\s\S]*?)<\/[^>]+>/i);
+
+    sections.push({
+      htmlId: getAttributeValue(attributes, "id"),
+      title: title ? stripTags(title[1]) : "",
+      previewText: preview ? stripTags(preview[1]) : "",
+      bodyHtml: fullHtml,
+      classNames: extractClassNames(fullHtml),
+    });
+  }
+  return sections;
+}
+
+function packageNameFromSection(section, fallbackIndex) {
+  const source = section?.htmlId || section?.title || `component-${fallbackIndex + 1}`;
+  const ascii = source
+    .normalize("NFKD")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return ascii || `component-${fallbackIndex + 1}`;
+}
+
+function mapTemplateRowsToHtmlSections(rows, sections) {
+  const sectionByTitle = new Map(sections.map((section) => [section.title, section]));
+  const usedSectionIds = new Set();
+
+  const modules = rows.map((row, index) => {
+    const section = sectionByTitle.get(row.sceneModuleName) || null;
+    if (section?.htmlId) {
+      usedSectionIds.add(section.htmlId);
+    }
+    const fields = extractTopLevelFields(row.structureSpec);
+
+    return {
+      order: row.order,
+      moduleName: row.moduleName,
+      sceneModuleName: row.sceneModuleName,
+      userProblem: row.userProblem,
+      componentDisplayName: row.sceneModuleName,
+      componentDescription: row.userProblem,
+      packageNameSuggestion: packageNameFromSection(section, index),
+      htmlId: section?.htmlId || "",
+      htmlTitle: section?.title || "",
+      previewText: section?.previewText || "",
+      fields,
+      constraints: extractConstraints(row.structureSpec, fields),
+      structureSpec: row.structureSpec,
+      bodyHtml: section?.bodyHtml || "",
+      classNames: section?.classNames || [],
+      hasHtmlMatch: Boolean(section),
+    };
+  });
+
+  const unmatchedHtmlSections = sections.filter((section) => !usedSectionIds.has(section.htmlId));
+  return { modules, unmatchedHtmlSections };
+}
+
+export function analyzeTemplatePair({ htmlText, templateText }) {
+  if (!htmlText || !templateText) {
+    throw new Error("必须同时传入 htmlText 和 templateText");
+  }
+
+  const templateTitle = extractTemplateTitle(templateText);
+  const rows = extractSceneModuleRows(templateText);
+  const sections = extractHtmlSections(htmlText);
+  const { modules, unmatchedHtmlSections } = mapTemplateRowsToHtmlSections(rows, sections);
+
+  return {
+    templateTitle,
+    moduleCount: modules.length,
+    modules,
+    unmatchedHtmlSections,
+  };
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const [htmlText, templateText] = await Promise.all([
+    readFile(args.html, "utf8"),
+    readFile(args.template, "utf8"),
+  ]);
+  const result = analyzeTemplatePair({ htmlText, templateText });
+  const output = `${JSON.stringify(result, null, 2)}\n`;
+
+  if (args.out) {
+    await writeFile(args.out, output);
+  } else {
+    process.stdout.write(output);
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  main().catch((error) => fail(error.stack || error.message || String(error)));
+}