fix(ci): 修复 pnpm 12 与 demo watch 验收并完善证据闭环

docs/engineering/agent-workflow.md

@@ -6,14 +6,18 @@
 
 ## 事实与复现
 
-先读取 Issue 最新评论及其截图，把用户操作变成可观察的验收条件。记录框架、平台、命令、依赖实际解析路径和编译器版本。明确区分已观察事实、待证假设和环境阻塞。
+先读取 Issue 最新评论及其截图，把用户操作变成可观察的验收条件。记录框架、平台、命令、依赖实际解析路径和编译器版本。明确区分已观察事实、待证假设和环境阻塞。每个独立问题记录最后成功阶段、第一失败阶段、原始错误及证据位置；内部卡点无法确定时写“未知”。回答“最后卡在哪里”时先给具体命令/阶段，再说明下一步；后续缺少设备或交互桌面的阻塞不能代替此前故障定位。
 
 测试预期必须来自项目配置和产品语义，不照搬默认 theme 数值。组件属性必须有真实消费方。首次加载先建立基线，再验证增量。Web 验证须确认服务根目录身份、端口和当前构建，不能仅凭标题或 localhost URL 判断实例。
 
 ## 根因与回归
 
 沿输入、转换、产物、运行时逐层找首次偏离。先固化失败用例，再修改负责该行为的模块；用相同用例验证修复前失败和修复后通过。未复现时不制造产品补丁，也不凭 mock 单测宣称用户环境已修复。
 
+连续两次相同失败且没有新增证据时，下一步必须增加阶段日志、做最小对照或更换验证路径；不盲目重试同一操作。诊断改进、一次运行通过和根因修复分别报告；只有对照与回归能够支持因果关系时，才把假设升级为已确认根因。
+
+协议、参数、路径或环境变量发生变化时，搜索全部生产消费方、mock、fixture、说明文档和 change intent，逐项确认是否需要同步。可模拟的平台分支在本地全部执行，防止仅运行宿主分支漏掉 Windows 等平台；模拟测试不能替代真实进程或桌面验收。
+
 HMR 在同一服务进程连续修改，覆盖新增、替换、删除和最终浏览器刷新。保存标识与被测属性尽量在一次写入提交；等待本轮 DOM、CSS 和计算样式一致，不用旧 marker 或固定等待证明成功。保留服务端错误、请求失败、页面日志和失败截图。
 
 ## 分层验收
@@ -23,21 +27,61 @@ HMR 在同一服务进程连续修改，覆盖新增、替换、删除和最终
 3. 对应 demo 的 static 基线和真实运行链路；设备流程见 [多端手册](../../e2e/LOCAL-MULTI-PLATFORM-E2E.md)。
 4. 检查 diff 与规则：`git diff --check`、`pnpm agents:check`。
 
+验证按依赖顺序执行：工具安装先于工具检查，构建完成先于读取 dist 的测试；共享源码或输出目录的验证串行执行。工作流变更除了语法校验，还验证实际命令的成功、失败和前置条件，保留语义断言与退出码。
+
 正常测试设置 `CI=1`；Vitest 5 显式使用 `--update=none`，禁止使用会被解释为更新参数的 `--update=false`。E2E 配置同时默认 `update: 'none'`，显式 `-u` 才更新基线。更新基线必须单独执行、限定项目、说明语义差异，再运行不更新的验证。聚合构建的缓存命中、跳过目标、测试 skip 均单独报告。
 
 ## 沉淀与自我修正
 
 根因修复、错误结论纠正或可复用的流程失败，需要在 `docs/engineering/lessons/` 留一份中文记录，链接持久回归和证据。原始大日志放到忽略的 artifacts；记录保留关键错误、命令、结果和适用版本，不能只留本机路径。
 
-记录使用 YAML frontmatter：`status` 为 `verified`、`partial` 或 `superseded`；`issue` 为来源 URL；`baseline` 为验证提交 SHA；`regressions` 为仓库相对测试路径数组。正文包含“症状”“根因与纠正”“验证”“适用边界”“规则评估”。
+记录使用 YAML frontmatter：`status` 为 `verified`、`partial` 或 `superseded`；`issue` 为来源 URL；`baseline` 为原排查基线的完整提交 SHA；`regressions` 为仓库相对测试路径数组。正文包含“症状”“根因与纠正”“验证”“适用边界”“规则评估”。
+
+新建或更新复盘时，使用可选的 `verification` 数组记录本次结论对应的证据；未采用该字段的历史记录仍兼容。提供时必须为非空数组，每条只允许下列字段：
+
+| 字段 | 约定 |
+| --- | --- |
+| `claim` | 非空字符串，说明本条验证支持的具体结论 |
+| `kind` | `unit`、`integration`、`ci` 或 `native` |
+| `status` | `passed`、`failed` 或 `pending`；跳过的验收记录为 `pending`，在原因中说明 |
+| `sha` | 被测或待测的完整 40 位十六进制提交 SHA |
+| `environment` | 非空字符串，记录实际或目标系统及 Node/IDE 等版本 |
+| `command` / `url` | 已执行记录至少提供一个；命令为非空字符串，URL 为完整 HTTPS 地址；提供的字段均须有效 |
+| `reason` | 待验收记录必须说明原因；若提供则必须是非空字符串 |
+
+`baseline` 保留原排查基线，各条 `verification.sha` 记录实际验证提交。单项通过不改变整篇 `partial` 状态，也不证明所有环境或根因已解决。CI 证据优先链接不可混淆的运行/任务 URL；本地命令同时说明源码是否含未提交改动，原始日志位置和限制放在正文。记录的命令仅供审阅，不会被校验器执行。
 
 每次交付评估规则变化：优先修正已有条目或补可执行测试；只有跨任务可复用且有证据的约束才进入 AGENTS。允许说明“不新增规则”。推翻旧结论时保留原因和替代记录；过时经验标记 superseded，不静默覆盖历史证据。
 
+本次流程纠正的实例见 [PR #1172 证据与交付复盘](lessons/ai-evidence-delivery.md)。
+
 根规则只放跨仓库硬约束，领域规则只放局部差异，操作步骤只有一个权威文档。新增规则须给出触发场景、验证入口和复查条件；不以重复或更长的规则代表更高质量。
 
+## 交付与自动跟进收尾
+
+交付前核对最新 head SHA、CI 运行/任务 ID 与验收范围，分别报告通过、失败、跳过和待验收。PR 标题、正文、相关复盘和 change intent 按最终实现同步，保留首次失败与纠正过程；历史通过记录标明提交，不用旧结果描述当前状态。正文写成面向审阅者的最终变更说明，避免不断追加过期进展。
+
+CI 通过、审核批准、无冲突可合并与已经合并是不同状态。更新 PR 元数据或取消草稿后重新读取状态；若触发新一轮检查，报告“此前一轮通过，新一轮进行中”。未经合并授权不得执行合并。
+
+只在已有授权范围内跟进自动化；观察状态不变时安静等待，只报告有意义的变化。已授权任务达到约定停止条件、PR 合并/关闭或用户要求停止时，调用所在平台的管理工具停用，再核对返回状态；不能只把停止条件写进提示词。停用失败则如实说明，不声称已停止，也不擅自重建定时任务。原生待验收按独立范围记录，不能无限延长已经完成的自动 CI 跟进。
+
+## 交接模板
+
+中断、移交或长任务结束时，更新已有任务记录。临时状态放在忽略目录，持久结论进入复盘，不将本机路径复制为仓库规则。可直接使用以下模板：
+
+```text
+目标与授权范围：本轮成功标准；允许的外部操作；明确不做的事。
+工作区：worktree、分支、基线 SHA、被测 SHA；是否含未提交改动。
+当前归属：本轮文件；测试临时变更与恢复记录；自有/外部 PID 和服务。
+证据：每项结论的环境、命令或运行 ID/URL；通过、失败、跳过、待验收。
+准确阻塞：最后成功阶段 → 第一失败阶段；原始错误；已知事实与未证假设。
+下一步：具体操作及预期新增证据；缺少的设备、输入或外部条件。
+自动化：任务 ID、授权范围、停止条件、已核对的启用/停用状态。
+```
+
 ## 自动检查与边界
 
-`pnpm agents:check` 是只读检查，验证规则索引、相对文件链接、明确 pnpm 命令和复盘引用。它不会执行文档里的命令，不会改规则、更新快照或对语义正确性做保证。新增语法或规则变更先补检查器测试。
+`pnpm agents:check` 是只读检查，验证规则索引、相对文件链接、明确 pnpm 命令、复盘引用及可选证据字段的结构。错误包含文件名和从 1 开始的 `verification[n]` 记录位置。它保持离线，不联网核对 CI，不执行文档里的命令，不会改规则、更新快照或对证据真实性及语义正确性做保证。尤其不能把 CI 通过换算成原生验收通过。新增语法或规则变更先补检查器测试。
 
 纯 Markdown PR 同样执行独立规则检查。AI 可以在授权任务中提出和实现有证据的规则修订，但不得自行放宽安全边界、操作用户会话、发布、关闭 Issue 或创建后台任务。
 

docs/engineering/lessons/ai-evidence-delivery.md

@@ -0,0 +1,74 @@
+---
+status: partial
+issue: https://github.com/sonofmagic/weapp-tailwindcss/pull/1172
+baseline: 8940eb551660176ab5f69f2086ac3a13acd161af
+regressions:
+  - scripts/agents/verification.test.mjs
+  - packages/hbuilderx-runner/test/host-connection.test.ts
+  - e2e/react-native-ci.test.ts
+verification:
+  - claim: "证据结构校验和旧记录兼容回归通过"
+    kind: "unit"
+    status: "passed"
+    sha: "960bc940d13cc8e47b0036f85714a2489e52d130"
+    environment: "macOS / Node 24.18.0 / pnpm 11.25.0"
+    command: "CI=1 pnpm agents:test --update=none"
+  - claim: "Windows/macOS/Linux × Node 22/24 六组 portable 回归通过；不替代原生桌面验收"
+    kind: "ci"
+    status: "passed"
+    sha: "7623470bddfb3e3ada51cefbdbd6527015867220"
+    environment: "GitHub hosted Windows、macOS、Linux / Node 22、24"
+    url: "https://github.com/sonofmagic/weapp-tailwindcss/actions/runs/34309551585"
+  - claim: "React Native Web、Android、iOS 自动验收通过"
+    kind: "ci"
+    status: "passed"
+    sha: "7623470bddfb3e3ada51cefbdbd6527015867220"
+    environment: "GitHub hosted Linux、macOS / Node 24 / Expo 54 / Android 11、iOS 18.5"
+    url: "https://github.com/sonofmagic/weapp-tailwindcss/actions/runs/34309551591"
+  - claim: "通过 IDE 点击运行后的 Windows 两轮连接验收"
+    kind: "native"
+    status: "pending"
+    sha: "7623470bddfb3e3ada51cefbdbd6527015867220"
+    environment: "Windows 11 交互桌面 / HBuilderX stable、alpha"
+    reason: "没有可用交互桌面完成该模式的逐场景两轮验收；portable 和历史 CLI 结果不能替代"
+  - claim: "macOS stable 两轮与 alpha 完整第二轮连接验收"
+    kind: "native"
+    status: "pending"
+    sha: "7623470bddfb3e3ada51cefbdbd6527015867220"
+    environment: "macOS / HBuilderX stable 5.24、alpha 5.25"
+    reason: "alpha 首轮四场景完成；剩余轮次未完成，不能由 CI 通过或 PR 合并补足"
+---
+
+# 从 PR #1172 修正 AI 排障与交付流程
+
+## 症状
+
+本轮暴露了五类流程问题：Windows 输出协议更新后遗漏另一份 mock；Android 加速检查放在工具安装前；CI 完成后仓库复盘仍写待验证、change intent 仍描述旧 JSON；回答“最后卡在哪里”时使用泛化的启停问题或后续缺少交互桌面代替准确命令；自动跟进提示词虽有停止条件，实际仍需用户提醒停用。
+
+## 根因与纠正
+
+协议修改没有完整检查生产消费方、mock、fixture 和说明，宿主平台测试又掩盖 Windows 分支。已有 host-connection 回归现已显式执行三平台，旧 mock 在 macOS 模拟 win32 时能够失败，修正后通过。流程要求每次边界变更检查完整消费链；原生能力仍由真实环境验证。
+
+工作流语法检查不能证明工具已经安装。Android 回归现已检查生命周期顺序，并实际执行带空格、中文与 & 路径的启动钩子，验证成功与非零失败退出。构建与消费 dist 的测试同样按依赖顺序执行。
+
+原记录与 PR 正文各自追加进展却没有最终同步。本轮以明确 SHA、运行 URL 和验收范围更新对应复盘，保留原始失败与反例；change intent 按最终 Base64 协议纠正。verification 为可选结构，历史文档继续兼容；新记录不允许通过未知字段、空来源或缺失待验收原因掩盖信息遗漏。
+
+准确卡点应表述为：最后一轮继承 stdin 对照已渲染页面，随后 project close 空日志、20 秒超时，其他只读 CLI 请求仍正常。内部等待位置未知；缺少 Windows 桌面导致新的连接模式待验收是独立问题。后续排障记录最后成功阶段、第一失败阶段和原始错误，两次相同失败没有新证据时必须改变诊断动作。
+
+已授权自动化的停止必须落实为管理工具操作并核对状态；本次任务最终已停用为 PAUSED，不能把提示词中的停止条件当作执行结果。新流程要求按约定终止跟进，并用交接模板保留目标、授权、源码与进程归属、证据、精确阻塞和下一步。它不自动创建、恢复或管理任何定时任务。
+
+## 验证
+
+证据校验先运行旧实现：36 个负例未被拒绝，测试失败；补充字段校验后全部通过，并覆盖 SHA 尾部换行与真正的嵌套数组输入。最终 50 项测试通过。代码验证提交见 verification，流程和本复盘为后续说明文档，不冒充旧 SHA 已包含这些文档。
+
+仓库级 fixture 检查错误包含文件和第二条记录位置；不可达 HTTPS 地址不会触发网络请求，带写文件语句的 command 不会执行，文档字节和 Git 状态保持不变。另运行 `pnpm agents:check`（45 份规则、19 份工程文档、238 条命令，0 错误）、脚本定向 ESLint 和 `git diff --check`；Markdown 被现有 ESLint 配置忽略，使用 agents 校验与人工差异审查，不冒充已通过 Markdown lint。校验结果只支持结构、兼容性与只读行为，不能证明任意 claim 的真实性。
+
+#1172 的六组 portable 及 React Native 三端 CI 已通过，详见结构化来源；首次失败不删除。原生阶段详情见[Windows 进程边界](hbuilderx-windows-process-boundary.md)、[连接验收](hbuilderx-attached-acceptance.md)及 [Android 前置条件](android-ci-kvm-access.md)。
+
+## 适用边界
+
+原生 CLI 间歇挂起的内部根因仍未确认；Windows 交互桌面两轮、macOS stable 两轮及 alpha 完整第二轮仍待验收。不能以自动 CI 通过或 PR 合并覆盖这些限制。新校验器只检查结构，不核实远端状态、命令执行结果、因果关系或原生覆盖，也不保证 AI 从此不会误判。
+
+## 规则评估
+
+改进集中在[现有工程流程](../agent-workflow.md)与 agents 校验器，根 AGENTS 继续路由到该文档，不添加重复规则。本轮不涉及产品行为、demo/static 基线或 CI 触发范围，无需重建 demo；仍需人工审查证据与结论是否相符、授权边界及真正的停止条件。

docs/engineering/lessons/android-ci-kvm-access.md

@@ -5,6 +5,19 @@ baseline: 7b50dcb582174221fc2f85ae0e9132e0a4c16316
 regressions:
   - e2e/react-native-android-window.test.ts
   - e2e/react-native-ci.test.ts
+verification:
+  - claim: "安装模拟器之前执行加速检查会退出 127"
+    kind: "ci"
+    status: "failed"
+    sha: "5ce6db93e80baf1bbaacb6a6fc080ac223c52c15"
+    environment: "GitHub ubuntu-latest / Node 24"
+    url: "https://github.com/sonofmagic/weapp-tailwindcss/actions/runs/34306912064/job/102325400077"
+  - claim: "React Native Web、Android、iOS 自动验收通过"
+    kind: "ci"
+    status: "passed"
+    sha: "7623470bddfb3e3ada51cefbdbd6527015867220"
+    environment: "GitHub hosted Linux、macOS / Node 24 / Expo 54 / Android 11、iOS 18.5"
+    url: "https://github.com/sonofmagic/weapp-tailwindcss/actions/runs/34309551591"
 ---
 
 # Android CI 的 KVM 访问前置条件
@@ -17,11 +30,11 @@ Expo Android 11/API 30 自动检查 34304902514 的任务 102319452874 在调用
 
 工作流日志明确报告当前用户没有 /dev/kvm 权限，自动将硬件加速关闭，使用 `-accel off` 启动。模拟器警告 x86_64 软件仿真可能无法工作，TCG 不支持 AVX/F16C；启动耗时 356 秒。logcat 中 Android ART 的 BootImageLoader::LoadImage 在 app_process 启动阶段触发 SIGTRAP，尚未进入 uiautomator 业务逻辑。
 
-CI 只给当前临时 runner 用户增加 KVM 读写 ACL，在 action 之前检查权限，并禁止 action 静默退回软件仿真。首轮补丁 5ce6db93e 把 emulator -accel-check 也放在 action 前，实际运行 34306912064 因模拟器尚未安装而退出 127；该执行顺序有误。本次将二进制检查移入 action 的 pre-emulator-launch-script，位于 installAndroidSdk/createAvd 之后、launchEmulator 之前，避免假定 runner 预装模拟器。原有 UI、运行时、截图与样式断言保持不变，没有添加重试。日志能证明旧运行缺少 KVM 前置条件；具体 ART 指令故障与软件仿真的因果仍需后续真实 CI 证据，不据此修改产品代码。
+CI 只给当前临时 runner 用户增加 KVM 读写 ACL，在 action 之前检查权限，并禁止 action 静默退回软件仿真。首轮补丁 5ce6db93e 把 emulator -accel-check 也放在 action 前，实际运行 34306912064 因模拟器尚未安装而退出 127；该执行顺序有误。本次将二进制检查移入 action 的 pre-emulator-launch-script，位于 installAndroidSdk/createAvd 之后、launchEmulator 之前，避免假定 runner 预装模拟器。原有 UI、运行时、截图与样式断言保持不变，没有添加重试。日志能证明旧运行缺少 KVM 前置条件；后续真实 CI 已确认加速模式下验收通过，但具体 ART 指令故障与软件仿真的因果仍未独立证实，不据此修改产品代码。
 
 ## 验证
 
-新增 e2e/react-native-ci.test.ts：禁止在 SDK 安装前调用模拟器；实际执行启动钩子验证含中文、空格及 & 的 SDK 路径，并验证加速检查非零退出会原样传播。同一回归在旧工作流失败，修正后 2 个回归通过，actionlint 校验工作流通过；Linux hosted runner 的实际加速和现有 Android 验收由新提交自动检查验证。本机为 macOS，未执行 /dev/kvm 配置，不以本机命令冒充 Linux 结果。原失败 logcat、截图、UI XML、Metro 和构建日志保留在原工作流 artifact。
+新增 e2e/react-native-ci.test.ts：禁止在 SDK 安装前调用模拟器；实际执行启动钩子验证含中文、空格及 & 的 SDK 路径，并验证加速检查非零退出会原样传播。同一回归在旧工作流失败，修正后 2 个回归通过，actionlint 校验工作流通过；随后 `cc6b30f96` 的真实 Linux 任务确认 KVM version 12 可用、模拟器约 26 秒启动，UI、TSX 保存标识和 CSS 颜色变化通过，三张截图及 UI XML 已上传；最新被测提交 `7623470bd` 的 [React Native 完整工作流](https://github.com/sonofmagic/weapp-tailwindcss/actions/runs/34309551591) 再次通过 Web、Android 和 iOS 验收。本机为 macOS，未执行 /dev/kvm 配置，不以本机命令冒充 Linux 结果。原失败 logcat、截图、UI XML、Metro 和构建日志保留在原工作流 artifact。
 
 ## 适用边界