1

_DEL/miniprogram-h5-conversion/POWER.md

@@ -0,0 +1,67 @@
+---
+name: "miniprogram-h5-conversion"
+displayName: "H5 → 微信小程序转换规范"
+description: "H5 原型转微信小程序页面的完整开发规范体系。覆盖截图、审计、修正、验证四阶段流水线，89 单元批量编排，半自动/新页面开发模式。核心硬性规则在 always-on steering 中始终生效，本 Power 提供操作手册。"
+keywords: ["微信小程序", "miniprogram", "wxml", "wxss", "H5", "转换", "迁移", "rpx", "截图", "审计", "修正", "验证", "视觉还原", "TDesign", "Tailwind"]
+author: "NeoZQYY"
+---
+
+# H5 → 微信小程序转换规范
+
+核心硬性规则已提取到 always-on steering `mp-h5-rules.md`（每次对话自动生效），详细开发参考值在 fileMatch steering `mp-h5-dev.md`（读取 wxml/wxss/h5_ui 文件时自动加载）。
+
+本 Power 提供操作手册——截图、审计、修正、验证的具体执行流程。
+
+## 使用方式
+
+### 确认工作模式后加载对应 steering
+
+| 我要做什么 | 加载的 steering |
+|-----------|----------------|
+| 批量执行 89 单元视觉还原 | `batch-auto.md` |
+| 用户指定页面/区域做开发或修正 | `user-guided.md` |
+| 从零开发新页面 | `user-guided.md`（场景二） |
+| 执行截图+审计+修正+验证流程 | `action-manual.md` |
+| 查 Power/MCP 调用方式 | `power-integration.md` |
+
+### 实时数据（仓库内，不在 Power 中）
+
+| 资源 | 路径 |
+|------|------|
+| 迁移进度 | `docs/miniprogram-dev/04-audit/PROGRESS.md` |
+| 踩坑速查 | `docs/miniprogram-dev/05-lessons/pitfalls.md` |
+| 收敛模式 | `docs/miniprogram-dev/05-lessons/convergence-patterns.md` |
+| 页面结构速查 | `docs/miniprogram-dev/03-reference/page-structure-map.md` |
+| 基准测试历史 | `docs/miniprogram-dev/03-reference/benchmark-history.md` |
+
+### 关联资源
+
+| 资源 | 路径 |
+|------|------|
+| H5 原型 | `docs/h5_ui/pages/*.html` |
+| 设计 Token | `docs/h5_ui/design-tokens.json` |
+| 图标映射 | `docs/h5_ui/icon-mapping.md` |
+| 截图产物 | `docs/h5_ui/compare/<page>/` |
+| MP 源码 | `apps/miniprogram/miniprogram/pages/` |
+
+## Steering 文件清单
+
+本 Power 包含 4 个 steering 文件：
+
+### 调度层（做什么、什么顺序）
+- `batch-auto.md` — 89 单元批量编排 + 4 代理流水线
+- `user-guided.md` — 半自动/新页面开发模式
+
+### 行动层（怎么做）
+- `action-manual.md` — 截图+审计+修正+验证的完整执行手册（合并原 screenshot/audit/fix/verify 四个文件）
+
+### 集成层
+- `power-integration.md` — 4 个外部 Power 的调用方式 + MCP 连接规范
+
+## 与 Steering 的分工
+
+| 内容 | 位置 | 加载方式 |
+|------|------|---------|
+| 硬性规则（标签映射、rpx、颜色、截图禁令） | `mp-h5-rules.md` | always-on |
+| 开发参考值（灰阶全表、圆角、阴影、CSS 风险） | `mp-h5-dev.md` | fileMatch 自动 |
+| 操作手册（截图流程、审计方法、修正策略） | 本 Power steering | 按需 readSteering |

_DEL/miniprogram-h5-conversion/steering/action-manual.md

@@ -0,0 +1,210 @@
+# 截图+审计+修正+验证 执行手册
+
+> 合并原 screenshot.md / audit.md / fix.md / verify.md 四个文件。
+> 硬性规则（rpx、标签映射、颜色）已在 always-on steering `mp-h5-rules.md` 中，此处不重复。
+
+---
+
+## 一、截图
+
+### H5 截图（Playwright Power → `browser_run_code`）
+
+```javascript
+async (page) => {
+  const browser = page.context().browser();
+  const ctx = await browser.newContext({
+    viewport: { width: 430, height: 752 },
+    deviceScaleFactor: 1.5
+  });
+  const p = await ctx.newPage();
+  await p.goto('file:///C:/NeoZQYY/docs/h5_ui/pages/<page>.html',
+    { waitUntil: 'domcontentloaded', timeout: 30000 });
+  await p.waitForTimeout(3000); // Tailwind CDN JIT
+
+  await p.evaluate(() => {
+    const nav = document.getElementById('bottomNav');
+    if (nav) nav.style.display = 'none';
+    const safeArea = document.querySelector('.safe-area-top');
+    if (safeArea) safeArea.style.paddingTop = '0px';
+    const aiFab = document.querySelector('.ai-float-btn-container');
+    if (aiFab) aiFab.style.display = 'none';
+    const s = document.createElement('style');
+    s.textContent = '::-webkit-scrollbar{display:none!important}*{scrollbar-width:none!important}';
+    document.head.appendChild(s);
+  });
+
+  await p.evaluate((scrollTop) => window.scrollTo(0, scrollTop), <scrollTop>);
+  await p.waitForTimeout(300);
+  await p.screenshot({
+    path: 'C:/NeoZQYY/docs/h5_ui/compare/<page>/h5--step-<scrollTop>.png',
+    type: 'png', scale: 'device'
+  });
+  await ctx.close();
+  return { saved: true };
+}
+```
+
+步数 ≥3 的页面可在同一 context 中循环截图。
+
+### MP 截图（weixin-devtools Power）
+
+```
+1. relaunch → url: "/pages/<page>/<page>"（禁止 switch_tab/navigate_to）
+2. waitFor → delay: 2000
+3. 前置：WXML 中 dev-fab/ai-float-button 加 wx:if="{{false}}"
+4. 滚动到目标 scrollTop
+5. screenshot
+6. 模式 B 页面裁剪头部 96px（PIL: img.crop((0, 96, 645, 1224))）
+```
+
+### 滚动策略
+
+标准：直接使用 H5 相同 scrollTop。
+
+窗口错位判断：上下大块红绿(>200px)=整体偏移→锚点对齐法 | 散布多区域=样式差异→继续修正 | 底部全黑/白>100px=内容更短→锚点对齐法
+
+锚点对齐法：确定锚点元素 → `wx.createSelectorQuery` 获取绝对 top → `MP_target = absoluteTop - sticky高度` → 滚动到该位置
+
+### 多维度切换
+
+board-coach/customer：获取快照 → 点击筛选下拉 → 选择维度 → 等待刷新
+board-finance：H5 `toggleCompare()` / MP 点击环比开关
+
+### 截图后行为（严格遵守）
+
+- 直接进入审计流程，禁止用 PIL/pixelmatch/image-compare 检查尺寸或做像素 diff
+- 截图参数已固定，尺寸必然正确
+
+---
+
+## 二、审计
+
+### 三阶段流程
+
+```
+阶段 0：结构拆解（自顶向下）
+  H5 源码 → 首层容器 → 递归到叶子 → 建立 H5↔MP 映射表
+  结构完整性校验（缺失/多余/顺序错误 → P0）
+
+阶段 1：逐级测量（自底向上）
+  叶子：自身尺寸 + 样式属性
+  容器：内边距 + 子元素间距 + 总尺寸
+  页面级：全局内边距 + 区块间距
+  工具：pixel-audit Power → readSteering("measure.md")
+
+阶段 2：偏差审计
+  逐属性对比 H5 rpx 理论值 vs MP 实测值 → 按偏差量分级
+```
+
+### 迁移前置准备（step-0 必做）
+
+1. H5 页面结构预扫描：全局结构、CSS 风险特性、字体确认
+2. MP 骨架检查：根容器、navigationBar、safe-area 移除、背景色、浮动按钮隐藏
+3. mock 数据一致性预核对（不一致 = P0）
+4. 多屏页面：测量 MP scrollHeight，与编排值差异 >50px 则重算序列
+
+### 审计报告格式
+
+产出 `docs/h5_ui/compare/<page>/audit.md`：
+
+| 章节 | 内容 |
+|------|------|
+| A. 结构对照 | 区域完整性、顺序 |
+| B. CSS 风险点 | 不支持的 CSS |
+| C. 关键样式映射 | Tailwind→computed→WXSS 现值→是否一致 |
+| D. 图标处理 | 每个图标迁移状态 |
+| E. 偏差清单 | P0-P7 排序，含 H5 值→rpx→MP 现值→差异 |
+| F. 复杂结构专项 | Banner/AI 图标/盖戳/inline SVG/渐变文字 |
+
+关键原则：不能只看 diff 图猜测，必须回溯 H5 源码。Tailwind 类名是唯一可信样式来源。
+
+---
+
+## 三、修正
+
+### 优先级定义
+
+| 级别 | 类型 | 判定标准 | 阶段 |
+|------|------|---------|------|
+| P0 | 区域缺失/顺序错误 | 整块缺失 | 阶段一 |
+| P1 | 背景色/渐变色不匹配 | 大面积色差 | 阶段一 |
+| P2 | 字号明显偏差 | font-size 差 ≥4rpx | 阶段一 |
+| P3 | 间距明显偏差 | padding/margin/gap 差 ≥4rpx | 阶段一 |
+| P4 | 圆角偏差 | border-radius 差 ±2rpx | 阶段二 |
+| P5 | 颜色微调 | 灰阶偏差、透明度差 0.1 | 阶段二 |
+| P6 | 行高/字重微调 | line-height 缺失或偏差 | 阶段二 |
+| P7 | 阴影微调 | box-shadow 偏差 | 阶段二 |
+
+### 两阶段收敛
+
+```
+P0-P3 >10 → 结构级重写（每轮 3-8 处）→ 循环
+P0-P3 >0  → 阶段一：结构级修正（每轮 2-5 处）→ 循环直到 P0-P3=0
+P4-P7 >0  → 阶段二：像素级精调（每轮 1-3 处）→ 循环直到可接受
+全部 ≤2rpx → ✅ 通过
+```
+
+### 回滚规则（强制）
+
+每轮修正后重新截图对比，差异率上升（哪怕 0.01%）→ 立即回滚 → 逐项排查 → 每次只改一处
+
+### 最大重试限制
+
+差异率下降 >0.5% → 重试计数归零 | 下降 ≤0.5% → 计数+1 | 计数=5 且仍 ≥5% → 跳过（记录到 report.md）
+
+### 首屏 >20% 触发结构重写
+
+| 页面类型 | 重写范围 | 禁止修改 |
+|---|---|---|
+| 单屏 | 当前维度完整 WXML/WXSS | 其他维度 |
+| 多屏(step-0) | 页面顶部结构 | step-600 以下 |
+| 多屏(step-N>0) | 当前视口内节点 | 其他屏和全局样式 |
+| 变体 | 与主页面差异部分 | 共享布局 |
+
+### 修改范围约束
+
+- 只改当前屏可见元素
+- 偏差根因在前序屏 → 标注"需回退到 step-X"返回主代理
+- 偏差根因是全局样式 → 标注"全局样式变更"返回主代理
+- 修改后 `getDiagnostics` 确认零 TS 错误，有错误立即回退
+
+### 收敛停滞
+
+连续 3 轮差异率未下降 >0.5%：分析是否为不可消除结构性差异 → 是则标注可接受 → 否则缩小粒度
+
+---
+
+## 四、验证
+
+### 修正后验证
+
+```
+1. 重新截图 → 重新审计
+2. P0-P3=0 → ✅ 通过
+3. P0-P3 减少 → 继续修正
+4. P0-P3 未减少或增加 → 回滚 + 重试计数+1
+5. 重试=5 → 跳过
+```
+
+### 全量回归校验（多屏页面所有屏通过后强制执行）
+
+```
+1. 逐屏截取双端截图
+2. 每屏结构化审计
+3. 禁止修改任何源码
+4. P0-P3 增加 → 标记"回归"
+5. 返回主代理决定处理方式
+```
+
+### Sticky 元素专项
+
+step-0 完成后先检测 sticky 差异 → 优先修复（一次修复所有屏受益）→ 再继续后续步骤
+
+### 异常处理
+
+| 故障 | 处理 | 升级 |
+|------|------|------|
+| MCP 断开 | reconnect_devtools；3次失败→mcp_recompile+5s | 重编译后仍失败→暂停 |
+| Playwright 不可用 | 用已有截图继续审计 | 无截图→报告主代理 |
+| 截图异常(白屏) | 暂停检查页面状态 | 禁止使用异常截图 |
+| MCP 超时 | 重试最多 2 次 | 3次均超时→跳过 |

_DEL/miniprogram-h5-conversion/steering/batch-auto.md

@@ -0,0 +1,122 @@
+# 批量自动模式：89 单元视觉还原编排
+
+> 每次会话开始：读 `docs/miniprogram-dev/04-audit/PROGRESS.md` 确认进度。
+> 执行手册：`readSteering("action-manual.md")`
+> Power 调用：`readSteering("power-integration.md")`
+
+---
+
+## 执行模型：4 种专职子代理
+
+```
+主代理（调度）
+  → 截图代理 → 审计代理 → 修正代理 ⇆ 验证代理 → 主代理汇总
+```
+
+全程严格串行——同一时刻只有一个单元在执行。禁止预先批量截图。
+
+---
+
+## 主代理调度职责
+
+1. 读 PROGRESS.md 确认进度
+2. 检查 MCP 就绪
+3. 新页面：隐藏 dev-fab/ai-float-button
+4. 逐屏下发：截图→审计→修正/验证循环
+5. 通过→更新 PROGRESS.md→下一屏
+6. 需回退→回退到指定 step
+7. 跳过→备注原因，继续
+8. 页面所有屏通过→全量回归校验
+
+---
+
+## 单元内流程
+
+```
+Step 1：截图代理 → H5/MP 截图
+Step 2：审计代理 → audit.md + 偏差清单
+Step 3：修正代理 → 修正源码
+  ├─ P0-P3 >0 且未触发跳过 → 验证代理 → 循环
+  ├─ P0-P3=0 → Step 4
+  ├─ 连续 5 轮无改善 → 跳过
+  └─ P0-P3 >10 且连续 3 轮无法突破 → 结构重写
+Step 4：主代理汇总 → 更新 PROGRESS.md
+```
+
+---
+
+## 前置任务
+
+P0. TS 零诊断基线：17 页面 `.ts` 全部 `getDiagnostics` 零诊断
+P1. 跨页面共性偏差批量修复
+
+---
+
+## 批次编排
+
+### A 批次：看板（32 单元）
+
+board-finance（20 单元）：default 10 屏(step-0~4848) + compare 10 屏(step-0~4827)
+board-coach（4 单元）：perf/salary/sv/task 各 step-0
+board-customer（8 单元）：recall/potential/balance/recharge/recent/spend60/freq60/loyal 各 step-0
+
+### B 批次：核心（4 单元）
+
+task-list：3 屏(#33-35) | my-profile：1 屏(#36)
+
+### C 批次：任务详情（17 单元）
+
+task-detail：5 屏(#37-41)
+task-detail-callback：4 屏(#42-45，teal 主题色)
+task-detail-priority：4 屏(#46-49，orange 主题色)
+task-detail-relationship：4 屏(#50-53，pink 主题色)
+
+### D 批次：详情（12 单元）
+
+coach-detail：5 屏(#54-58) | customer-detail：5 屏(#59-63) | customer-service-records：2 屏(#64-65)
+
+### E 批次：绩效（18 单元）
+
+performance：13 屏(#66-78) | performance-records：5 屏(#79-83)
+
+### F 批次：对话（3 单元）
+
+chat：2 屏(#84-85) | chat-history：1 屏(#86)
+
+### G 批次：其他（3 单元）
+
+notes：3 屏(#87-89)
+
+---
+
+## 子代理下发模板
+
+### 标准单元
+
+```
+执行视觉还原对照单元：<单元 ID>
+源码：H5 docs/h5_ui/pages/<page>.html | MP apps/miniprogram/.../pages/<page>/
+输出：docs/h5_ui/compare/<page>/
+当前步骤：step-<N>（第 M / 共 T 步）
+前序屏状态：<首屏"无前序" / 后续"step-X 已通过">
+
+执行：截图→审计→修正→验证（见 action-manual.md）
+约束：只改当前屏 | 偏差在前序屏→标注"需回退" | 全局样式→标注"全局变更"
+完成后：更新 PROGRESS.md
+```
+
+### 变体单元（C 批次）
+
+```
+执行视觉还原（变体简化）：<单元 ID>
+与 task-detail 共享布局，仅 Banner 主题色不同。
+主题色：callback=teal / priority=orange / relationship=pink
+step-0 重点验证 Banner 渐变色和按钮配色，其余快速对比。
+```
+
+### 回归校验
+
+```
+执行全量回归校验：<page>
+逐屏截取+审计，禁止修改源码。P0-P3 增加→标记"回归"。
+```

_DEL/miniprogram-h5-conversion/steering/power-integration.md

@@ -0,0 +1,63 @@
+# Power 集成指南
+
+> 4 个外部 Power 的调用方式 + MCP 连接规范。
+
+---
+
+## Power 清单与激活
+
+| Power | 用途 | 激活 |
+|-------|------|------|
+| `wechat-miniprogram` | 小程序开发规范 | `kiroPowers activate wechat-miniprogram` → `view-layer.md` / `tdesign.md` / `builtin-components.md` |
+| `pixel-audit` | 像素间距测量 | `kiroPowers activate pixel-audit` → `readSteering("measure.md")` |
+| `power-playwright` | H5 截图 | `kiroPowers activate power-playwright` → `browser_run_code` |
+| `weixin-devtools` | MP 截图+操作 | `kiroPowers activate weixin-devtools` → `mcp_weixin_devtools_mcp_*` |
+
+---
+
+## 各阶段调用
+
+### 页面开发
+
+wechat-miniprogram → `view-layer.md` + `tdesign.md` + `builtin-components.md`
+
+### 截图
+
+H5：power-playwright → `browser_run_code`（DPR=1.5 context，详见 action-manual.md §一）
+MP：weixin-devtools → `relaunch` → `waitFor` → `screenshot`（+ `evaluate_script` / `get_page_snapshot` / `click`）
+
+### 审计
+
+pixel-audit → `readSteering("measure.md")`（rpx 换算精确公式 + 五种间距类型 + Tailwind→WXSS 映射表）
+测量工具：`uv run python scripts/ops/measure_gaps.py`
+锚点对比：`uv run python scripts/ops/anchor_compare.py`
+
+> `image-compare` MCP 已移除（2026-03-12），禁止调用。
+
+---
+
+## MCP 连接规范
+
+### weixin-devtools
+
+- 只能用 wsEndpoint：`ws://127.0.0.1:9420`
+- 禁止 auto/launch/connect/discover 策略
+- 断开：`reconnect_devtools` → 3 次失败 → `mcp_recompile` + 5s
+- 单次调用最大等待 10 分钟
+
+### Playwright
+
+- 必须 `browser_run_code` 创建 DPR=1.5 context
+- 禁止 `browser_take_screenshot`（DPR=1）
+- 禁止 `browser_navigate` + `browser_evaluate` 分步流程
+
+---
+
+## 会话开始 MCP 就绪检查
+
+```
+[ ] weixin-devtools → get_connection_status → 已连接
+[ ] Playwright → browser_run_code 可用
+[ ] 微信开发者工具已开启
+[ ] pixel-audit → 已激活
+```

_DEL/miniprogram-h5-conversion/steering/user-guided.md

@@ -0,0 +1,122 @@
+# 半自动模式 & 新页面开发
+
+> 合并原 user-guided.md / new-page.md / page-dev.md。
+> 硬性规则和开发参考值已在 steering `mp-h5-rules.md` + `mp-h5-dev.md` 中。
+
+---
+
+## 一、半自动模式
+
+用户直接指定页面/区域/任务，AI 按需执行。
+
+### 意图解析
+
+解析用户输入，确定：目标页面 → 目标范围（整页/step/区域/组件）→ 任务类型（开发/修正/审计/验证）
+
+意图不明确时追问一轮即可（不进入完整审问模式）。
+
+### 按需加载
+
+| 任务类型 | 加载 |
+|---------|------|
+| 视觉还原（截图+审计+修正） | `readSteering("action-manual.md")` |
+| 仅审计 | `readSteering("action-manual.md")` §二 |
+| 仅修正（已有审计报告） | `readSteering("action-manual.md")` §三+§四 |
+| 仅截图 | `readSteering("action-manual.md")` §一 |
+| 新页面开发 | 本文件 §二/§三 |
+
+始终加载：`readSteering("power-integration.md")`
+
+### 与批量模式的区别
+
+- 不需要按批次顺序
+- 可跳过不相关步骤
+- 修正范围由用户指定
+- 完成后提示是否更新 PROGRESS.md
+
+### 经验沉淀
+
+发现新踩坑点 → 向用户提出建议 → 确认后录入 `docs/miniprogram-dev/05-lessons/pitfalls.md`
+
+---
+
+## 二、新页面开发（有 H5 原型）
+
+### 流程
+
+```
+1. 前置加载
+   H5 源码 + design-tokens.json + icon-mapping.md + 交互说明
+   激活 wechat-miniprogram Power（view-layer.md + tdesign.md）
+
+2. H5 结构分析
+   全局结构识别（safe-area/bottomNav/ai-float 等）
+   CSS 风险特性扫描
+   组件清单（TDesign 可覆盖 vs 自定义）
+
+3. MP 页面骨架搭建（见 §四）
+
+4. 视觉比对审计（推荐）
+   → readSteering("action-manual.md")
+```
+
+### 必须遵守
+
+- mock 数据必须与 H5 原型完全一致
+- TDesign 优先原则
+- 所有规则见 always-on steering `mp-h5-rules.md`
+
+---
+
+## 三、新页面开发（无 H5 原型）
+
+从 spec/PRD 直接开发，无视觉比对。
+
+```
+1. 需求确认（用途、数据来源、导航关系、是否 tabBar）
+2. 设计参考（design-tokens.json + 现有页面风格 + TDesign 选型）
+3. 页面开发（见 §四）
+4. 功能验证（微信开发者工具预览 + 交互流程 + 空/加载/错误态）
+```
+
+---
+
+## 四、页面骨架搭建
+
+### 文件结构
+
+```
+apps/miniprogram/miniprogram/pages/<page>/
+├── <page>.wxml    # 结构
+├── <page>.wxss    # 样式
+├── <page>.ts      # 逻辑 + mock
+└── <page>.json    # 配置（navigationBarTitleText + usingComponents）
+```
+
+### .json 配置模板
+
+```json
+{
+  "navigationBarTitleText": "页面标题",
+  "usingComponents": {
+    "t-button": "tdesign-miniprogram/button/button",
+    "t-icon": "tdesign-miniprogram/icon/icon"
+  }
+}
+```
+
+### TS mock 数据
+
+```typescript
+Page({
+  data: { /* mock 数据，结构贴近真实 API */ },
+  onLoad() {
+    // TODO: 替换为真实 API 调用
+    this.setData({ /* ... */ });
+  }
+});
+```
+
+### 完成检查
+
+见 fileMatch steering `mp-h5-dev.md` 中的「新页面 Checklist」。