@guru-ai-product/ai-product-kit 0.1.251112172507

package/README.md

@@ -0,0 +1,107 @@
+# AI Product Kit
+
+AI Product Kit is a doc-first toolkit designed for product managers and cross-functional teams, offering end-to-end guidance from discovery to launch.
+
+Looking for the Chinese version? See `README_CN.md`.
+
+## 📁 Repository Structure
+
+```text
+ROOT/
+├── AGENTS.md                   # Single source of truth for agent guardrails and workflow rules
+├── skills/                     # Canonical lifecycle Skills and reusable guides
+│   ├── aipk_init_project/      # Project bootstrap workflow plus AGENTS enforcement scripts
+│   ├── aipk_requirements/      # Research, requirements authoring, reviews, change management
+│   ├── aipk_design/            # Script-driven automation (panel mapping, asset diffs, etc.)
+│   ├── aipk_development/       # Engineering playbooks and implementation templates
+│   ├── aipk_operations/        # Growth, launch prep, and post-launch tooling
+│   ├── aipk_skill_generate/    # Standards for creating or extending Skills
+│   └── aipk_tool_prompts/      # Reusable AI prompt blocks referenced by other Skills
+├── docs/                       # Legacy landing pages and shared standards referenced by Skills
+├── mcp/                        # Archived automation service source, documentation, and tests
+├── bin/                        # Distribution-ready CLI entry points (e.g., `ai-product-kit.js`)
+├── tools/                      # Release automation such as `publish-package.sh`
+├── scripts/                    # Helper utilities invoked by Skills and templates
+├── todos/                      # Working drafts and in-progress notes
+├── test/                       # Automated coverage for CLI helpers and scripts
+└── README*.md                  # Repository entry points (English + Chinese)
+```
+
+**Documentation Standards**: All documentation follows the standards defined in [`docs/guide_writing_standard/SKILL.md`](docs/guide_writing_standard/SKILL.md), covering document structure, content organization, formatting, and template writing guidelines.
+
+## 🎯 Who This Helps
+
+* **Product managers** – start in `skills/aipk_requirements` for market analysis, user research, and PRD templates.
+* **Designers** – leverage `skills/aipk_design` for automated panel/asset workflows, and pair it with the requirements skills for context.
+* **Engineers** – use `skills/aipk_development` for architecture notes and delivery checklists.
+* **QA teams** – align with the acceptance criteria defined in `skills/aipk_requirements` and leverage `skills/aipk_development` checklists for validation.
+* **Operators & growth** – explore `skills/aipk_operations` for launch, engagement, and optimization plans.
+
+## 📚 Core Capabilities
+
+* **Discovery & analysis** – market studies, user interviews, competitor reviews.
+* **Product planning** – PRD templates, backlog framing, prioritization.
+* **Design systems** – UI/UX principles, prompt and content guidelines.
+* **Delivery enablement** – architecture references, API design, dev workflows.
+* **Quality practice** – test plans, automation strategy, regression tooling.
+* **Release & operations** – go-to-market, post-launch metrics, growth loops.
+
+## ⚙️ Environment Requirements
+
+- **Node.js 18+** – required to run `npx ai-product-kit@latest` from `ROOT`.
+- **npm 9+** – provides access to the scoped package and carries your authenticated session, so the sync command can download the latest Skill bundle.
+
+## 🛠️ Usage Guide
+
+1. **Sync the latest Skills** from `ROOT` (call the explicit CLI so future additional binaries don’t break the command):
+
+   ```bash
+   npx ai-product-kit@latest ai-product-kit
+   ```
+
+   The command copies the newest Skill bundle (templates, scripts, and `GURU_AI.md` files) into your working tree. Rerun it whenever you pull updates or start a new branch.
+2. **Prime your agent** by sending the following sentence after the sync completes:
+
+   ```text
+   init project based on .claude/skill/int_project
+   ```
+
+   This prompt loads the init-project Skill documented in `AGENTS.md`, ensuring Codex/Cursor follows the canonical workflow every time.
+3. **Review the synced artifacts** – open the relevant `skills/aipk_<lifecycle>/SKILL.md`, verify the bundled checklists and `GURU_AI.md` instructions match your task, and log any new deliverables in the tracker specified by `AGENTS.md` before editing documents.
+
+Once the agent acknowledges the Skill load, continue with your usual prompts (for example, “Prepare the PRD for feature X using the AI Product Kit template.”)
+
+## 🚀 Quick Start
+
+Agents already know where each Skill lives because the mappings are declared in `AGENTS.md`. Use prompts like these to get moving quickly:
+
+1. 
+   ```text
+   Draft a PRD for the AI-assisted recording feature using the latest AI Product Kit template.
+   ```
+2. 
+   ```text
+   Review the current launch checklist and tell me what’s missing for the beta cut.
+   ```
+3. 
+   ```text
+   Summarize the deltas between @panel_diff_v2 and the current AI Product Kit design standard, then propose fixes.
+   ```
+
+## 📦 Release Guide
+
+1. **Login to npm** – run `npm whoami` to verify the session before releasing.
+2. **Execute the script** – from `ROOT` run:
+
+   ```bash
+   tools/publish-package.sh --version <version>
+   ```
+
+   Optionally pass `--tag beta` or `--dry-run`; the script performs the necessary validations (auth checks, `npm pack --dry-run`, Skill sync) before publishing.
+3. **Follow the prompts** – the script syncs Skills, runs `npm pack --dry-run`, and then publishes with `npm publish --access public`.
+
+> Ensure you have the necessary permissions on the npm org before running the script.
+
+## 📄 License
+
+This project is distributed under the MIT License.

package/bin/setup.js

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const packageRoot = path.resolve(__dirname, '..');
+const bundledSkillsDir = path.join(packageRoot, 'skills');
+
+function log(message) {
+  process.stdout.write(`[ai-product-kit] ${message}\n`);
+}
+
+function exitWithError(message) {
+  console.error(`[ai-product-kit] ERROR: ${message}`);
+  process.exit(1);
+}
+
+function assertBundledSkills() {
+  if (!fs.existsSync(bundledSkillsDir)) {
+    exitWithError('Bundled skills folder is missing from the package.');
+  }
+}
+
+function ensureClaudeSkillsDir(targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+}
+
+function containsGuruFile(dirPath) {
+  const stack = [dirPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = path.join(current, entry.name);
+      if (entry.isFile() && entry.name === 'GURU_AI.md') {
+        return true;
+      }
+      if (entry.isDirectory()) {
+        stack.push(entryPath);
+      }
+    }
+  }
+  return false;
+}
+
+function removeGuruDirectories(targetDir) {
+  if (!fs.existsSync(targetDir)) {
+    return;
+  }
+  const entries = fs.readdirSync(targetDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const entryPath = path.join(targetDir, entry.name);
+    if (containsGuruFile(entryPath)) {
+      fs.rmSync(entryPath, { recursive: true, force: true });
+      log(`Removed existing skill: ${entry.name}`);
+    }
+  }
+}
+
+function copyBundledSkills(targetDir) {
+  const entries = fs.readdirSync(bundledSkillsDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(bundledSkillsDir, entry.name);
+    const destPath = path.join(targetDir, entry.name);
+    if (fs.existsSync(destPath)) {
+      fs.rmSync(destPath, { recursive: true, force: true });
+    }
+    if (entry.isDirectory()) {
+      fs.cpSync(srcPath, destPath, { recursive: true });
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+    log(`Copied skill asset: ${entry.name}`);
+  }
+}
+
+function main() {
+  assertBundledSkills();
+  const targetDir = path.join(process.cwd(), '.claude', 'skills');
+  ensureClaudeSkillsDir(targetDir);
+  removeGuruDirectories(targetDir);
+  copyBundledSkills(targetDir);
+  log('Skills directory updated.');
+}
+
+main();

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@guru-ai-product/ai-product-kit",
+  "version": "0.1.251112172507",
+  "description": "Sync the AI Product Kit Skill bundle through npx without cloning the repository.",
+  "bin": {
+    "ai-product-kit": "bin/setup.js"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-product-kit"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "UNLICENSED",
+  "dependencies": {
+    "sharp": "^0.33.3"
+  }
+}

package/skills/aipk_design/GURU_AI.md

@@ -0,0 +1,10 @@
+# GURU AI Snapshot
+
+Last refreshed: 2025-11-12T09:25:07.317552+00:00
+
+| File | Last Modified (UTC) |
+| --- | --- |
+| `SKILL.md` | 2025-11-12T07:57:23.698734+00:00 |
+| `auto_panel_splitter/SKILL.md` | 2025-11-12T07:01:50.772859+00:00 |
+| `auto_panel_splitter/scripts/auto_panel_splitter.js` | 2025-11-12T06:58:38.936920+00:00 |
+| `auto_panel_splitter/scripts/panel_asset_mapper.js` | 2025-11-12T06:59:17.886824+00:00 |

package/skills/aipk_design/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: design
+description: Central hub for automation-ready design workflows, describing how agents split composite boards, prep visual assets, sync requirement docs, and discover the right sub-skill before handling new mocks.
+---
+
+# 设计阶段 Skill
+
+## 目标与适用范围
+
+- 统一收录设计交付相关的脚本化流程与指引，方便在需求或开发阶段前快速对齐视觉产出。
+- 为代理和协作者提供索引，指向符合 [`../skill_generate/SKILL.md`](../skill_generate/SKILL.md) 规范的子 Skill。
+- 当你需要处理视觉拆分、素材入库、设计变更对齐时，先查阅此处的列表，再加载对应子 Skill。
+
+## 当前可用的设计 Skill
+
+- **Auto Panel Splitter**（`./auto_panel_splitter/`）
+  - 使用脚本批量切分合成设计图、生成映射 CSV、同步需求文档并输出变动说明。
+  - 包含 `./auto_panel_splitter/scripts/auto_panel_splitter.js` 与 `./auto_panel_splitter/scripts/panel_asset_mapper.js` 等自动化工具。
+
+如需扩展新的设计场景，请在 `skills/aipk_design/` 下创建子目录，按照模板完成 `SKILL.md`、`references/` 等结构，并在本文件的“当前可用的设计 Skill”中登记用途与入口路径。
+
+## 使用方式
+
+1. **识别任务**：确认是面向设计交付的哪一类动作（拆 panel、生成 asset、审查视觉差异等）。
+2. **查找子 Skill**：在上方列表定位可复用方案；若缺失，请提出需求或新建 Skill。
+3. **加载并执行**：打开子 Skill 的 `SKILL.md` 阅读流程，或在 MCP 代理中加载该目录以自动索引规则。
+4. **回写产出**：按子 Skill 指示更新需求文档、变动记录或素材库，并在 `AGENTS.md` 约定的进度追踪方式中记录状态。
+
+## 维护指引
+
+- 当脚本或流程更新时，先在对应子 Skill 中调整，再同步这里的描述，确保索引不失效。
+- 撰写/更新任何设计 Skill 时，遵循 [`../guide_writing_standard/SKILL.md`](../guide_writing_standard/SKILL.md) 的写作与标记规则。
+- 设计流程若影响需求、开发或发布阶段，及时在相关 Skill 中留下引用或注意事项，保持跨阶段信息一致。

package/skills/aipk_design/auto_panel_splitter/SKILL.md

@@ -0,0 +1,360 @@
+---
+name: auto-panel-splitter
+description: Split composite design boards, align requirement docs with new visuals, and emit standardized requirement-change records.
+---
+
+# Auto Panel Splitter Skill
+
+处理最新视觉稿时使用本 Skill：先用 [`./scripts/auto_panel_splitter.js`](./scripts/auto_panel_splitter.js) 自动切分设计图，再用 [`./scripts/panel_asset_mapper.js`](./scripts/panel_asset_mapper.js) 生成映射、批量入库，并同步需求文档/变动说明。
+
+<!-- rule: Agents must complete the entire pipeline end-to-end without依赖人工手动操作或 GUI 工具。 -->
+
+## 1. 技能定位
+
+- **适用场景**：收到合成设计图（多屏拼板）后，需要批量切分、覆盖需求文档插图、修正文案，并输出需求变动记录
+- **目标人群**：需求文档维护者、AI 协作写手、设计对接 PM
+- **价值主张**：把视觉稿拆分、命名、需求对齐、变更记录打包成标准化流程，避免手动截屏、命名混乱与遗漏输出
+
+## 2. 快速上手
+
+### 2.1 完整流程概览
+
+```mermaid
+graph TD
+    A[收到合成设计图] --> B[自动切分设计图]
+    B --> C[生成映射模板CSV]
+    C --> D[手动填充映射信息]
+    D --> E[批量入库到assets目录]
+    E --> F[更新需求文档并比对差异]
+    F --> G[生成需求变动说明文档]
+    G --> H[清理临时文件]
+    
+    style A fill:#e1f5ff
+    style B fill:#fff4e1
+    style C fill:#fff4e1
+    style D fill:#ffe1f5
+    style E fill:#fff4e1
+    style F fill:#e1ffe1
+    style G fill:#ffe1f5
+    style H fill:#ffe1e1
+```
+
+### 2.2 详细步骤
+
+1. **自动切分设计图**：运行 [`scripts/auto_panel_splitter.js`](./scripts/auto_panel_splitter.js) 将合成图拆成临时 PNG（详见第3节）。
+2. **生成映射模板CSV**：执行 `node scripts/panel_asset_mapper.js --source <tmp> --mapping <tmp>/mapping.csv --init-mapping`，脚本会扫描全部 PNG 并生成映射模板（详见第4节）。
+3. **手动填充映射信息**：在 CSV 中补齐 `panel_title`（截图上方蓝色标题原文）与 `file_slug`（希望落库的文件名，推荐 kebab-case），必要时填写 `version`、`notes`（详见第5节）。
+4. **批量入库到assets目录**：确认映射后，运行 `scripts/panel_asset_mapper.js`（可指定 `--destination` 或 `--doc-slug/--iteration`）完成重命名与复制（详见第6节）。
+5. **更新需求文档并比对差异**：在需求文档中更新图片引用与文案，同时比对设计图与文档的一致性，记录不一致项（详见第7节）。
+6. **生成需求变动说明文档**：依照 [`需求变动说明模板`](../requirements/changes/template/需求变动说明文档模板.md) 在**需求文档版本文件夹下的 `changes/` 目录**中生成版本记录（详见第8节）。**重要**：变动说明文档必须保存在需求文档版本文件夹下的 `changes/` 目录中，例如 `../../sample/docs/requirement/v1.3.0/changes/YYYYMMDD_需求文档变动说明_*.md`。在删除 `.tmp` 目录前，必须将 `mapping.csv` 的内容以表格形式直接写入需求变动说明文档的附录中（推荐），或将其复制到需求文档版本文件夹下的 `changes/` 目录下（带时间戳命名，如 `YYYYMMDD_mapping.csv`）。同时附上脚本命令行和相关 issue/PR 链接。
+7. **清理临时文件**：完成所有步骤后，删除 `.tmp` 目录下的所有临时文件（包括切分的 PNG 和 `mapping.csv`），保持工作区整洁（详见第9节）。
+
+**⚠️ 重要提示**：步骤5中的"比对差异"是必要步骤，必须在步骤6（生成需求变动说明）之前完成，以确保变动说明文档中包含完整的差异核对信息。
+
+## 3. 自动切分设计图
+
+### 3.1 输入与输出约定
+
+- 原始合成图保存在 `../design/assets/source/`，命名保留日期或版本号。
+- 切分输出先落在临时目录（如 `.tmp/checkout-panels`），审核和命名完成后再移动到需求文档 `assets` 目录。
+- 最终文件名采用 "标题-版本" 形式（例：`checkout-summary-v3.png`）。
+
+### 3.2 运行脚本
+
+```bash
+node scripts/auto_panel_splitter.js \
+  --input ../design/assets/source/20241115_checkout.png \
+  --output .tmp/checkout-panels \
+  --prefix checkout \
+  --margin 12 \
+  --title-scan-height 260
+```
+
+**参数说明**：
+
+- `--input`：原始合成设计图路径
+- `--output`：临时输出目录，方便审核后再复制到需求文档 `assets`
+- `--prefix`：临时文件名前缀（仅作初始占位名，后续会被真实标题覆盖）
+- `--margin`：切分时保留的边距（单位：像素），默认12px
+- `--title-scan-height`：标题扫描高度，视稿件调节以减少误切
+- `--min-area`：最小面板面积阈值（可选参数）
+
+### 3.3 执行结果
+
+脚本会在临时目录下生成按顺序编号的 PNG 文件（如 `checkout_01.png`、`checkout_02.png` 等），每个文件对应一个切分出来的面板。
+
+## 4. 生成映射模板CSV
+
+### 4.1 执行时机
+
+在第3节（自动切分设计图）完成后立即执行。
+
+### 4.2 运行脚本
+
+```bash
+node scripts/panel_asset_mapper.js \
+  --source .tmp/checkout-panels \
+  --mapping .tmp/checkout-panels/mapping.csv \
+  --init-mapping
+```
+
+**参数说明**：
+
+- `--source`：临时目录路径（即第3节的输出目录）
+- `--mapping`：映射文件输出路径
+- `--init-mapping`：初始化模式，仅生成映射模板，不修改图片文件
+
+### 4.3 生成内容
+
+脚本会扫描 `--source` 目录下的所有 PNG 文件，生成 CSV 映射模板，包含以下列：
+
+| 列名 | 说明 |
+| --- | --- |
+| `original_name` | 临时目录下的原始文件名（如 `checkout_01.png`） |
+| `file_slug` | 目标文件名（初始值为文件stem，需手动修改） |
+| `version` | 版本号（初始为空） |
+| `panel_title` | 面板标题（初始为空，需手动填写） |
+| `notes` | 备注信息（初始为空） |
+
+**示例输出**：
+
+```csv
+original_name,file_slug,version,panel_title,notes
+checkout_01.png,checkout_01,,,
+checkout_02.png,checkout_02,,,
+checkout_03.png,checkout_03,,,
+```
+
+## 5. 手动填充映射信息
+
+### 5.1 执行时机
+
+在第4节（生成映射模板CSV）完成后，第6节（批量入库）之前执行。
+
+### 5.2 填写内容
+
+打开 `mapping.csv` 文件，逐行填写以下信息：
+
+#### 5.2.1 `panel_title`（必填）
+
+- **作用**：记录设计稿左上角的标题文本，用于文档描述及核对表
+- **填写规则**：
+  - 照抄设计稿上的标题原文
+  - 允许中文/符号，但不要包含 `/`、`\`
+  - 保持与设计稿完全一致
+
+#### 5.2.2 `file_slug`（必填）
+
+- **作用**：决定最终入库的文件名
+- **填写规则**：
+  - 推荐使用英文 kebab-case（如 `checkout-summary`）
+  - 若业务要求沿用中文标题，可直接复制 `panel_title` 的内容
+  - 禁止包含 `/`、`\` 字符
+  - 示例：`1-上传全身照`、`checkout-summary`、`error-network`
+
+#### 5.2.3 `version`（可选）
+
+- **作用**：版本号，脚本会自动将其拼接在 `file_slug` 末尾
+- **填写规则**：
+  - 若不需要版本号，留空即可
+  - 若需要多版本并行，填写版本号（如 `v1-3-0`）
+  - 最终文件名格式：`<file_slug>-<version>.png`
+
+#### 5.2.4 `notes`（可选）
+
+- **作用**：记录差异、待办事项或其他说明
+- **填写场景**：
+  - 标题尚未敲定：`TODO: 待产品确认标题`
+  - 文件名与内容不符：`标题写"身高"，但内容为体重选择`
+  - 其他需要说明的情况
+
+### 5.3 填写示例
+
+```csv
+original_name,file_slug,version,panel_title,notes
+ai-calorie_01.png,1-上传全身照,,1-上传全身照,
+ai-calorie_02.png,1-上传全身照备份,,1-上传全身照备份,
+ai-calorie_09.png,10-体重,,10-体重,标题写"身高"，但内容为体重选择
+ai-calorie_10.png,11-第一阶段完成,,11-第一阶段完成,
+```
+
+### 5.4 注意事项
+
+- 所有行的 `panel_title` 和 `file_slug` 都必须填写
+- `file_slug` 不要重复，确保每个文件名唯一
+- 填写完成后保存文件，准备进入第6节（批量入库）
+
+## 6. 批量入库到assets目录
+
+### 6.1 执行时机
+
+在第5节（手动填充映射信息）完成后，确认映射信息无误后执行。
+
+### 6.2 运行脚本
+
+**资产入库命令**：
+
+```bash
+node scripts/panel_asset_mapper.js \
+  --source .tmp/checkout-panels \
+  --mapping .tmp/checkout-panels/mapping.csv \
+  --destination ../../sample/docs/requirement/v1.3.0/assets \
+  --trim-top 140
+```
+
+**注意**：`--diff-report` 参数用于生成图片文件的 diff 比对表（包含哈希值），但 check 目录应保存的是文案/设计对齐核对表（见第7.2节），而非图片 diff 比对表。
+
+**参数说明**：
+
+- `--source`：临时目录路径
+- `--mapping`：映射文件路径
+- `--destination`：目标assets目录路径
+  - 或使用 `--doc-slug <doc-name> --iteration <version>` 自动构建路径
+- `--trim-top`：裁掉标题条的像素值（本项目默认140px，可选）
+- `--dry-run`：预览操作但不实际复制（可选，用于检查）
+- `--diff-report`：导出差异报告CSV（可选）
+- `--update-mapping-notes`：将差异信息写回 `mapping.csv`（可选）
+
+### 6.3 脚本行为
+
+**文件处理**：
+
+1. 读取 `mapping.csv` 中的映射关系
+2. 根据 `file_slug` 和 `version` 生成目标文件名
+3. 如果设置了 `--trim-top`，先裁掉图片顶部的标题条
+4. 复制文件到目标目录
+
+**差异检测**：
+
+- **像素完全一致**：跳过复制，标记为 `identical`
+- **文件缺失**：复制文件，标记为 `missing`
+- **像素不一致**：覆盖文件，标记为 `different`
+
+**输出示例**：
+
+```
+Copied .tmp/ai-calorie-panels/ai-calorie_01.png -> ../../sample/docs/requirement/v1.3.0/assets/1-上传全身照.png [missing]
+Skipped .tmp/ai-calorie-panels/ai-calorie_02.png -> ../../sample/docs/requirement/v1.3.0/assets/1-上传全身照备份.png [identical]
+Overwrote .tmp/ai-calorie-panels/ai-calorie_09.png -> ../../sample/docs/requirement/v1.3.0/assets/10-体重.png [different]
+```
+
+### 6.4 资产管理约定
+
+**目标路径规范**：
+
+- `../requirements/documentation/<doc-slug>/assets/`（或其版本子目录）
+- 文件直接平铺在目标目录下，不再额外创建二级子文件夹
+- `<doc-slug>` 对应需求文档目录名
+- `<iteration-id>` 采用 `YYYYMMDD` 或版本号
+
+**引用方式**：在 Markdown 中使用相对路径引用，格式：`![图片描述](./assets/文件名.png)`
+
+**覆盖策略**：脚本默认覆盖旧图；若需保留历史版本，在 `mapping.csv` 中更新 `version` 并重新执行脚本。
+
+### 6.5 映射留存
+
+**映射留存**：
+
+`mapping.csv` 的内容必须包含在**需求文档版本文件夹下的 `changes/`** 目录中的需求变动说明文档中（见第8节）。
+
+**推荐方式**：将 `mapping.csv` 的内容以表格形式直接写入需求变动说明文档的附录中，这样即使删除 `.tmp` 目录，映射信息仍然保留在文档中。
+
+**备选方式**：在删除 `.tmp` 目录前，将 `mapping.csv` 复制到**需求文档版本文件夹下的 `changes/`** 目录下，使用带时间戳的文件名（如 `YYYYMMDD_mapping.csv`），然后在需求变动说明文档中引用该文件。
+
+## 7. 更新需求文档并比对差异
+
+**执行时机**：在第6节（批量入库到assets目录）完成后立即执行。
+
+### 7.1 更新需求文档图片引用
+
+**执行步骤**：
+
+1. **定位段落**：使用 `rg -n "<关键词>" ../requirements -g '*.md'` 找到涉及模块。
+2. **更新图片引用**：将文档中的旧图片路径替换为新入库的图片路径，确保文件名与 `mapping.csv` 中的 `file_slug` 一致。
+3. **对照设计**：核实按钮/标签文案、显隐逻辑、字段顺序、错误提示、状态、单位等是否与最新图一致。
+4. **逐条更新**：直接修改 Markdown 文案与图片引用；必要时增加表格或列表突出新增/删减项。
+5. **标注待确认**：若设计仍未定稿，使用 `<!-- TODO: 待确认责任人 + 截止时间 -->` 提示。
+6. **写作规范**：遵循 [`../requirements/documentation/SKILL.md`](../requirements/documentation/SKILL.md)，保持单主题段落、显式引用来源。
+
+**注意事项**：
+
+- 图片引用路径应使用相对路径，格式：`![图片描述](./assets/文件名.png)`
+- 如果发现图片文件名与内容不符（如映射文件notes中标注的问题），应同时修正文档中的引用和注释
+
+### 7.2 比对文档与设计图差异
+
+**执行方法**：
+
+1. 逐一查看已入库的设计图文件
+2. 对照需求文档中对应的章节描述
+3. 检查以下内容的一致性：
+   - 界面标题和主标题
+   - 按钮文案和交互逻辑
+   - Toast提示和错误信息
+   - 字段顺序和显示状态
+   - 单位、格式、数值范围
+4. 使用下表模板记录发现的不一致项
+
+**链接格式规范**：需求文档位置列使用双重链接格式，前面为 Markdown 标准链接（显示"文件名+章节序号"），后面为 Obsidian 双向链接（在括号内显示"👁️"）。**重要**：Markdown 链接的锚点应该只包含章节号，不包含标题文本。格式示例：`[文件名 §章节号](../相对路径.md#章节锚点) ([[文件名#标题\|👁️]])`
+
+**核对表模板**：
+
+| 图片文件 | 设计稿关键文案/控件 | 对应需求文档位置 | 当前文案描述 | 不一致说明 | 建议处理人/动作 | 状态 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 例：![10-身高](../assets/10-身高.png) | "Save" 按钮 + 体重选项 | [引导页_用户体验优化 §4.3.1.6](../20250818_引导页_用户体验优化.md#4316) ([[20250818_引导页_用户体验优化#4.3.1.6 🆕 新增结果修改页面\|👁️]]) | 文档暂无说明该页面 | 命名与实际内容不符，且需求描述缺失 | 指派需求 Owner 确认是否更名/补文案 | 待确认 |
+
+**注意**：图片文件列应使用图片嵌入格式 `![描述](../assets/文件名.png)`，路径相对于 check 目录或 changes 目录（两者都在版本文件夹下，assets 目录也在版本文件夹下，所以使用 `../assets/`）。
+
+**处理原则**：
+
+- Review 完成后再决定是否修改文档或资产；未确认前不要自动改动
+- 核对表应包含在需求变动说明文档的"文档级变动详情"或"附录"章节中（见第8节）
+- 对于已修正的不一致项，在状态列标记为"已完成"或"✅ 已修正"
+
+## 8. 生成需求变动说明文档
+
+**执行时机**：在第7节（更新需求文档并比对差异）完成后执行。
+
+**执行步骤**：
+
+1. **创建目录**：在**需求文档版本文件夹下**创建 `changes/` 目录（如 `../../sample/docs/requirement/v1.3.0/changes/`），若不存在则创建。**重要**：变动说明文档必须保存在需求文档版本文件夹下的 `changes/` 目录中，而不是根目录的 `changes/` 文件夹。
+2. **文件命名**：新文件命名格式为 `YYYYMMDD_需求文档变动说明_<旧版本>至<新版本>.md`（示例：`20241116_需求文档变动说明_v2.3.0至v2.4.0.md`）。
+3. **套用模板**：严格套用 [`../requirements/changes/template/需求变动说明文档模板.md`](../requirements/changes/template/需求变动说明文档模板.md)，不得增删章节；不适用项填 `*略*`。
+4. **填写变动详情**：在"文档级变动详情"章节明确列出：
+   - 更新的需求文档路径以及受影响的章节编号（使用行号链接）
+   - 新增/覆盖的 `assets` 目录与关键 PNG 名称
+   - 文案、字段、交互、校验规则的差异摘要
+   - 比对差异核对表的发现（如有不一致项，见第7.2节）
+5. **包含映射信息**：在"附录"章节中必须包含 `mapping.csv` 的内容（见第6.5节）。**注意**：由于 `.tmp` 目录会在第9节被删除，因此必须将 `mapping.csv` 的内容以表格形式直接写入文档中（推荐），或先将其复制到**需求文档版本文件夹下的 `changes/`** 目录下再在文档中引用。
+6. **记录命令**：在"附录"章节中附上完整的脚本命令行，包括：
+   - 切分命令（`scripts/auto_panel_splitter.js`，见第3节）
+   - 生成映射命令（`scripts/panel_asset_mapper.js --init-mapping`，见第4节）
+   - 入库命令（`scripts/panel_asset_mapper.js`，见第6节）
+   - 相关 issue/PR 链接（如有）
+7. **包含核对表**：将第7.2节生成的文案/设计对齐核对表包含在文档的"文档级变动详情"或"附录"章节中。
+8. **生成文案/设计对齐核对表**：将第7.2节生成的文案/设计对齐核对表保存为 Markdown 文件到**需求文档版本文件夹下的 `check/`** 目录（如 `../../sample/docs/requirement/v1.3.0/check/YYYYMMDD_文案设计对齐核对表.md`）。**重要**：check 目录应保存的是文案/设计对齐核对表（记录设计图与需求文档的一致性比对），而非图片 diff 比对表（图片文件的哈希值比对）。核对表使用 Markdown 格式，包含表格和必要的说明文字。
+
+**重要提醒**：必须在执行第9节（清理临时文件）之前完成此步骤，确保 `mapping.csv` 的内容已保存到需求变动说明文档中。
+
+## 9. 清理临时文件
+
+**执行时机**：在第8节（生成需求变动说明文档）完成后，确认所有信息已保存到需求变动说明文档后执行。
+
+**执行步骤**：
+
+1. **检查确认**：确保 `mapping.csv` 的内容已包含在需求变动说明文档的附录中。
+2. **删除临时目录**：执行 `rm -rf .tmp/<项目名>-panels` 删除整个临时目录。
+3. **验证清理**：检查 `.tmp` 目录是否已清空，保持工作区整洁。
+
+**注意事项**：
+
+- 删除前务必确认 `mapping.csv` 已保存到需求变动说明文档中
+- 如果需要保留临时文件用于调试，可以暂缓删除，但务必在提交代码前清理
+- 临时文件不应提交到版本控制系统
+
+## 10. 附加资源
+
+- [自动切分脚本](./scripts/auto_panel_splitter.js) — 面板检测与裁切逻辑
+- [资产映射脚本](./scripts/panel_asset_mapper.js) — 映射管理与批量入库
+- [需求文档 Skill](../requirements/documentation/SKILL.md) — 需求文档结构与质检
+- [需求变动 Skill](../requirements/changes/SKILL.md) — 需求变动说明模板与执行清单