1

2026-03-15 10:15:02 +08:00
parent 2dd217522c
commit 72bb11b34f
916 changed files with 65306 additions and 16102803 deletions
--- a/scripts/ops/txt/orch_header_new.txt
+++ b/scripts/ops/txt/orch_header_new.txt
@@ -0,0 +1,2 @@
+> 主代理按本计划逐单元调度 4 种专职子代理（截图→审计→修正⇆验证）完成每屏还原。
+> 所有操作在单元内闭环，不存在跨单元批量截图或批量对比阶段。
--- a/scripts/ops/txt/orch_header_old.txt
+++ b/scripts/ops/txt/orch_header_old.txt
@@ -0,0 +1,3 @@
+> 主代理按本计划逐单元下发任务给子代理。
+> 每个子代理接收一个单元后，独立完成截图→对比→审计→修正→验证的完整闭环。
+> 不存在“批量截图”或“批量对比”阶段——所有操作在单元内闭环。
--- a/scripts/ops/txt/progress_p1.txt
+++ b/scripts/ops/txt/progress_p1.txt
@@ -0,0 +1,49 @@
+# H5 → 微信小程序视觉还原 — 进度跟踪
+
+> **主代理必读**：每次会话开始时先读本文件，确认当前状态后再下发任务。
+> 每完成一个处理单元后立即更新本文件。
+
+---
+
+## 当前状态（会话开始时填写）
+
+| 项目 | 内容 |
+|---|---|
+| **当前处理单元** | 未开始 |
+| **下一个单元** | #1 board-finance/default/step-0 |
+| **本次会话目标** | 未设定 |
+| **MCP 状态** | 未检查 |
+| **最后更新** | 2026-03-10 |
+
+### MCP 就绪检查清单（每次会话开始时执行）
+
+```
+[ ] mcp_weixin_devtools_mcp_get_connection_status → 已连接
+[ ] mcp_image_compare → 可用（测试 compare_images）
+[ ] Playwright MCP → 可用（测试 browser_run_code）
+[ ] 微信开发者工具已开启并显示目标页面
+```
+
+---
+
+## 总览
+
+| 指标 | 値 |
+|------|-----|
+| 总单元数 | 89 |
+| 已完成 | 0 |
+| 跳过 | 0 |
+| 进行中 | 0 |
+| 未开始 | 89 |
+| 整体进度 | 0% |
+
+---
+
+## 前置任务
+
+| # | 任务 | 状态 | 完成日期 | 备注 |
+|---|------|------|----------|------|
+| P0 | TS 零诊断基线检查 | ✅ 完成 | 2026-03-10 | 17 页面全部通过 |
+| P1 | 跨页面共性偏差批量修复 | ✅ 完成 | 2026-03-10 | board-finance/coach/customer 三页 |
+| P2 | 截图技术验证 | ✅ 完成 | 2026-03-10 | DPR=1.5 双端 645×1128 已验证 |
+| P3 | AGENT-PLAYBOOK.md v4.2 更新 | ✅ 完成 | 2026-03-11 | 4种专职子代理、间距测量代理、裁剪修正 |
--- a/scripts/ops/txt/progress_p2.txt
+++ b/scripts/ops/txt/progress_p2.txt
@@ -0,0 +1,88 @@
+
+## A 批次：board-finance/default（10 单元）
+
+> H5 scrollHeight=5600，maxScroll=4848，10 步
+> 序列：0, 600, 1200, 1800, 2400, 3000, 3600, 4200, 4800, 4848
+
+| # | 单元 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|-----------|----------|-----------|------|------|
+| 1 | default/step-0 | — | — | — | 未开始 | |
+| 2 | default/step-600 | — | — | — | 未开始 | |
+| 3 | default/step-1200 | — | — | — | 未开始 | |
+| 4 | default/step-1800 | — | — | — | 未开始 | |
+| 5 | default/step-2400 | — | — | — | 未开始 | |
+| 6 | default/step-3000 | — | — | — | 未开始 | |
+| 7 | default/step-3600 | — | — | — | 未开始 | |
+| 8 | default/step-4200 | — | — | — | 未开始 | |
+| 9 | default/step-4800 | — | — | — | 未开始 | |
+| 10 | default/step-4848 | — | — | — | 未开始 | |
+
+## A 批次：board-finance/compare（10 单元）
+
+> 环比开启后页面高度可能变化，scrollTop 序列需实测确认
+
+| # | 单元 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|-----------|----------|-----------|------|------|
+| 11 | compare/step-0 | — | — | — | 未开始 | |
+| 12 | compare/step-600 | — | — | — | 未开始 | |
+| 13 | compare/step-1200 | — | — | — | 未开始 | |
+| 14 | compare/step-1800 | — | — | — | 未开始 | |
+| 15 | compare/step-2400 | — | — | — | 未开始 | |
+| 16 | compare/step-3000 | — | — | — | 未开始 | |
+| 17 | compare/step-3600 | — | — | — | 未开始 | |
+| 18 | compare/step-4200 | — | — | — | 未开始 | |
+| 19 | compare/step-4800 | — | — | — | 未开始 | |
+| 20 | compare/step-4827 | — | — | — | 未开始 | |
+
+## A 批次：board-coach（4 单元，单屏×4 维度）
+
+| # | 单元 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|-----------|----------|-----------|------|------|
+| 21 | perf/step-0 | — | — | — | 未开始 | |
+| 22 | salary/step-0 | — | — | — | 未开始 | |
+| 23 | sv/step-0 | — | — | — | 未开始 | |
+| 24 | task/step-0 | — | — | — | 未开始 | |
+
+## A 批次：board-customer（8 单元，单屏×8 维度）
+
+| # | 单元 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|-----------|----------|-----------|------|------|
+| 25 | recall/step-0 | — | — | — | 未开始 | |
+| 26 | potential/step-0 | — | — | — | 未开始 | |
+| 27 | balance/step-0 | — | — | — | 未开始 | |
+| 28 | recharge/step-0 | — | — | — | 未开始 | |
+| 29 | recent/step-0 | — | — | — | 未开始 | |
+| 30 | spend60/step-0 | — | — | — | 未开始 | |
+| 31 | freq60/step-0 | — | — | — | 未开始 | |
+| 32 | loyal/step-0 | — | — | — | 未开始 | |
+
+## B 批次：task-list + my-profile（4 单元）
+
+| # | 单元 | 页面 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|------|-----------|----------|-----------|------|------|
+| 33 | step-0 | task-list | — | — | — | 未开始 | |
+| 34 | step-600 | task-list | — | — | — | 未开始 | |
+| 35 | step-676 | task-list | — | — | — | 未开始 | |
+| 36 | step-0 | my-profile | — | — | — | 未开始 | |
+
+## C 批次：task-detail 系列（17 单元）
+
+| # | 单元 | 页面 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|------|-----------|----------|-----------|------|------|
+| 37 | step-0 | task-detail | — | — | — | 未开始 | |
+| 38 | step-600 | task-detail | — | — | — | 未开始 | |
+| 39 | step-1200 | task-detail | — | — | — | 未开始 | |
+| 40 | step-1800 | task-detail | — | — | — | 未开始 | |
+| 41 | step-2243 | task-detail | — | — | — | 未开始 | |
+| 42 | step-0 | task-detail-callback | — | — | — | 未开始 | |
+| 43 | step-600 | task-detail-callback | — | — | — | 未开始 | |
+| 44 | step-1200 | task-detail-callback | — | — | — | 未开始 | |
+| 45 | step-1645 | task-detail-callback | — | — | — | 未开始 | |
+| 46 | step-0 | task-detail-priority | — | — | — | 未开始 | |
+| 47 | step-600 | task-detail-priority | — | — | — | 未开始 | |
+| 48 | step-1200 | task-detail-priority | — | — | — | 未开始 | |
+| 49 | step-1637 | task-detail-priority | — | — | — | 未开始 | |
+| 50 | step-0 | task-detail-relationship | — | — | — | 未开始 | |
+| 51 | step-600 | task-detail-relationship | — | — | — | 未开始 | |
+| 52 | step-1200 | task-detail-relationship | — | — | — | 未开始 | |
+| 53 | step-1523 | task-detail-relationship | — | — | — | 未开始 | |
--- a/scripts/ops/txt/progress_p3.txt
+++ b/scripts/ops/txt/progress_p3.txt
@@ -0,0 +1,98 @@
+
+## D 批次：详情页（12 单元）
+
+| # | 单元 | 页面 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|------|-----------|----------|-----------|------|------|
+| 54 | step-0 | coach-detail | — | — | — | 未开始 | |
+| 55 | step-600 | coach-detail | — | — | — | 未开始 | |
+| 56 | step-1200 | coach-detail | — | — | — | 未开始 | |
+| 57 | step-1800 | coach-detail | — | — | — | 未开始 | |
+| 58 | step-2166 | coach-detail | — | — | — | 未开始 | |
+| 59 | step-0 | customer-detail | — | — | — | 未开始 | |
+| 60 | step-600 | customer-detail | — | — | — | 未开始 | |
+| 61 | step-1200 | customer-detail | — | — | — | 未开始 | |
+| 62 | step-1800 | customer-detail | — | — | — | 未开始 | |
+| 63 | step-2318 | customer-detail | — | — | — | 未开始 | |
+| 64 | step-0 | customer-service-records | — | — | — | 未开始 | |
+| 65 | step-209 | customer-service-records | — | — | — | 未开始 | |
+
+## E 批次：绩效页面（18 单元）
+
+| # | 单元 | 页面 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|------|-----------|----------|-----------|------|------|
+| 66 | step-0 | performance | — | — | — | 未开始 | |
+| 67 | step-600 | performance | — | — | — | 未开始 | |
+| 68 | step-1200 | performance | — | — | — | 未开始 | |
+| 69 | step-1800 | performance | — | — | — | 未开始 | |
+| 70 | step-2400 | performance | — | — | — | 未开始 | |
+| 71 | step-3000 | performance | — | — | — | 未开始 | |
+| 72 | step-3600 | performance | — | — | — | 未开始 | |
+| 73 | step-4200 | performance | — | — | — | 未开始 | |
+| 74 | step-4800 | performance | — | — | — | 未开始 | |
+| 75 | step-5400 | performance | — | — | — | 未开始 | |
+| 76 | step-6000 | performance | — | — | — | 未开始 | |
+| 77 | step-6600 | performance | — | — | — | 未开始 | |
+| 78 | step-6953 | performance | — | — | — | 未开始 | |
+| 79 | step-0 | performance-records | — | — | — | 未开始 | |
+| 80 | step-600 | performance-records | — | — | — | 未开始 | |
+| 81 | step-1200 | performance-records | — | — | — | 未开始 | |
+| 82 | step-1800 | performance-records | — | — | — | 未开始 | |
+| 83 | step-1925 | performance-records | — | — | — | 未开始 | |
+
+## F 批次：对话页面（3 单元）
+
+| # | 单元 | 页面 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|------|-----------|----------|-----------|------|------|
+| 84 | step-0 | chat | — | — | — | 未开始 | |
+| 85 | step-309 | chat | — | — | — | 未开始 | |
+| 86 | step-0 | chat-history | — | — | — | 未开始 | |
+
+## G 批次：其他（3 单元）
+
+| # | 单元 | 页面 | 初始差异率 | 修正轮次 | 最终差异率 | 状态 | 备注 |
+|---|------|------|-----------|----------|-----------|------|------|
+| 87 | step-0 | notes | — | — | — | 未开始 | |
+| 88 | step-600 | notes | — | — | — | 未开始 | |
+| 89 | step-957 | notes | — | — | — | 未开始 | |
+
+---
+
+## 主代理会话恢复流程
+
+**每次新会话开始时，主代理必须执行以下步骤：**
+
+```
+步骤1：读取本文件（PROGRESS.md）
+  → 找到「当前状态」区块，确认「下一个单元」
+  → 扫描单元表，找到第一个状态为「进行中」或「未开始」的行
+
+步骤2：MCP 就绪检查
+  → mcp_weixin_devtools_mcp_get_connection_status
+  → 若未连接：等待10秒后重试，最多3次
+  → 3次失败后：mcp_weixin_devtools_mcp_recompile 重新编译，再重试
+
+步骤3：更新「当前状态」区块
+  → 填写「当前处理单元」和「本次会话目标」
+
+步骤4：从「下一个单元」开始下发任务
+  → 严格按编号顺序，单元完成后立即更新本文件对应行
+```
+
+**单元状态说明：**
+
+| 状态 | 含义 |
+|------|------|
+| 未开始 | 尚未处理 |
+| 进行中 | 当前会话正在处理 |
+| ✅ 通过 | 差异率 <5%，已收敛 |
+| ⚠️ 跳过 | 5轮未收敛，已记录差异，继续下一单元 |
+| 🔁 重写中 | 差异率 >20%，触发结构重写流程 |
+
+---
+
+## 变更日志
+
+| 日期 | 变更 |
+|------|------|
+| 2026-03-11 | 新增会话恢复机制、MCP就绪检查、重写状态标记 |
+| 2026-03-10 | 全部 89 单元初始化，前置任务 P0-P3 完成 |
--- a/scripts/ops/txt/spacing_agent_p1.txt
+++ b/scripts/ops/txt/spacing_agent_p1.txt
@@ -0,0 +1,51 @@
+---
+name: spacing-agent
+description: >
+  间距测量专用子代理。用于 H5 原型与小程序页面之间精确间距/内边距/外边距的测量与 rpx 转换。
+  当审计代理发现偏差根因为间距不准确，或修正代理需要确认某元素精确 rpx 尺寸时调用。
+---
+
+# 间距测量子代理（Spacing Agent）
+
+## 职责
+
+精确测量 H5 页面任意元素的间距，输出 rpx 对比表，为修正代理提供可信赖的定量依据。
+
+---
+
+## 一、核心方法论
+
+### 1.1 为什么不能只看 Tailwind 类名
+
+Tailwind 类名提供理论尺寸，但实际渲染受嵌套、布局算法影响。必须用 getBoundingClientRect() 测量实际位置的场景：
+
+| 场景 | 原因 |
+|---|---|
+| 嵌套层内边距 | 外层 padding + 内层 margin 叠加效果不直观 |
+| 边框到边框间距 | 参考线不确定，只有 rect.top/bottom 可信 |
+| flex/grid 元素 | gap 属性是容器的，不反映在子元素 rect 里 |
+| 断行文本 | lineHeight computed 値可能是 normal，需测 rect.height |
+| 页面下方元素 | 需先 scrollTo 再测 |
+
+### 1.2 换算公式
+
+```
+小程序 viewport 宽 = 750rpx = 430px
+rpx = px × 1.7442（取偶数）
+
+常用对照表：
+  2px →  4rpx    4px →  8rpx    6px → 10rpx
+  8px → 14rpx   10px → 18rpx   12px → 20rpx
+ 14px → 24rpx   16px → 28rpx   20px → 34rpx
+ 24px → 42rpx   28px → 50rpx   32px → 56rpx
+```
+
+### 1.3 五种间距类型与测量方法
+
+| 间距类型 | 测量方法 | 小程序对应 |
+|---|---|---|
+| **内容容器 padding** | computedStyle.paddingTop/Bottom/Left/Right | padding: Xrpx |
+| **相邻元素垂直间距** | B.rect.top - A.rect.bottom | margin-top 或父容器 gap |
+| **边框内文字到边框** | text.rect.top - border.rect.top - paddingTop | 子元素 padding |
+| **边框到边框（平行）** | B.rect.left - A.rect.right | gap 或 margin-left |
+| **嵌套边框内边距** | inner.rect.top - outer.rect.top - borderTopWidth | 内层 margin/padding |
--- a/scripts/ops/txt/spacing_agent_p2.txt
+++ b/scripts/ops/txt/spacing_agent_p2.txt
@@ -0,0 +1,101 @@
+
+## 二、测量工具：measure_gaps.py
+
+路径：`scripts/ops/measure_gaps.py`
+
+### 2.1 基本用法
+
+```bash
+# 测量页面内所有 .task-card 元素的尺寸和间距
+uv run python scripts/ops/measure_gaps.py task-list --selectors ".task-card"
+
+# 测量多个选择器（按 DOM 顺序，计算相邻间距）
+uv run python scripts/ops/measure_gaps.py board-finance --selectors ".summary-header" ".summary-content" ".grid-cols-3"
+
+# 指定两个元素的直接间距
+uv run python scripts/ops/measure_gaps.py task-list --pairs ".sticky-header" ".task-card:first-child"
+
+# 页面中下方元素（需 scrollTop）
+uv run python scripts/ops/measure_gaps.py performance --selectors ".perf-section" --scroll 1200
+```
+
+### 2.2 输出解读
+
+输出包含：
+- 元素尺寸表：top_px, h_px, paddingT/B, marginT/B, gap, fontSize, lineHeight, h_rpx
+- 相邻元素垂直间距表：gap_px 和 gap_rpx
+- audit.md 可直接粘贴的 Markdown 表格
+
+### 2.3 常用 CSS 选择器快查
+
+| 元素类型 | 选择器示例 |
+|---|---|
+| 页面内边距容器 | `.px-4`, `.px-6`, `[class*="px-"]` |
+| 卡片 | `.task-card`, `[class*="card"]` |
+| 列表项间距 | `.list-item`, `li`, `[class*="item"]` |
+| Sticky 头部 | `.sticky`, `.filter-bar`, `[class*="sticky"]` |
+| Banner | `.banner-bg`, `[class*="banner"]` |
+| 标签/徽章 | `.tag`, `.badge`, `[class*="tag"]` |
+
+---
+
+## 三、测量步骤（每页标准流程）
+
+### 3.1 H5 侧测量
+
+1. 确定要测量的元素（审计代理提供偏差元素列表）
+2. 确定 CSS 选择器（参照 2.3 快查表）
+3. 运行 measure_gaps.py，记录输出的 px 和 rpx 尺寸
+4. 如果元素在页面中下方，加上 `--scroll 目标scrollTop`
+
+### 3.2 MP 側反向验证
+
+1. 在 MP 页面 WXML 中定位对应元素
+2. 使用 `SelectorQuery`：
+   ```js
+   const query = wx.createSelectorQuery();
+   query.select('.task-card').boundingClientRect(res => {
+     console.log('top:', res.top, 'height:', res.height);
+   }).exec();
+   ```
+3. 比较 MP 实测高度（px）与理论 rpx 下的预期实际宣染尺寸
+4. 差异 > 4rpx 则标记为 P3 偏差，需要修正
+
+### 3.3 图像反推验证（处理截图偏差时使用）
+
+当 diff 图显示某个元素位置偏程时，用截图像素反推实际间距：
+
+```
+实际间距(px) = diff 图中偏程像素数 ÷ DPR
+DPR = 1.5
+示例：diff 图中元素 A 比 H5 下小 9 像素
+      实际偏差 = 9 / 1.5 = 6px = 10rpx
+      应描小 WXSS 中对应 margin/padding 10rpx
+```
+
+---
+
+## 四、输出格式：audit.md 间距表
+
+将 measure_gaps.py 输出的 Markdown 表格直接填入 audit.md 的 F 项：
+
+```markdown
+## G. 间距测量表
+
+| 元素 | H5 top_px | H5 高度px | 预期 rpx | MP 实测 rpx | 差异 | 处理 |
+|---|---|---|---|---|---|---|
+| .task-card | 88.0 | 84.0 | 146rpx | 140rpx | -6rpx | 将 height 改为 146rpx |
+| .task-card 间距 | - | - | 14rpx | 12rpx | -2rpx | margin-bottom 改为 14rpx |
+| .sticky-header | 0.0 | 44.0 | 76rpx | 76rpx | 0 | 匹配 ✓ |
+```
+
+---
+
+## 五、调用时机
+
+| 场景 | 调用方 | 输出用途 |
+|---|---|---|
+| \u00a70.8 迁移前预计算 | 主代理在 step-0 审计前主动调用 | 填入 WXSS 的初始内边距/外边距/gap 尺寸 |
+| 审计代理发现间距偏差 | 审计代理调用 | 补充 audit.md G 项 |
+| 修正代理需要确认尺寸 | 修正代理调用 | 确认正确 rpx 尺寸再写入 WXSS |
+| 差异率无法下降 | 修正代理调用 | 精确定位剩余偏差来源 |