@epoint-testtech/ep-stage-skill 0.0.10 → 0.5.0-alpha.2

package/codex-skill/ep-stage/glue-run-test/SKILL.md

@@ -1,296 +1,273 @@
----
-name: glue-run-test
-description: 使用时机：当用户对某需求要「跑测试 / 验证 / 端到端执行 / 跑胶水测试 / 看报告」或显式触发 `/glue-run-test <testcase.json5路径>` 时使用。
-version: 2026-08-12+c23cb62
-argument-hint: "<testcase.json5绝对/相对路径>"
-compatibility: 需要由 stage-create 生成的 glue 模式 Playwright 项目 + 已审过的 `testcase.json5` + 同目录 `credentials.json5`。
-metadata:
-  source-package: "@epoint-testtech/ep-stage-skill"
-  contract: "crud-business-module/v1"
----
-
-# ep-stage: glue-run-test
-
-本 skill 编排 `@epoint-testtech/ep-stage-skill` CLI 与 Agent Runtime。分工固定：
-
-1. 用户入口只收 `/glue-run-test <testcase.json5路径>`。
-2. CLI `prepare-tasks` 只做确定性工作：定位项目、补组装 glue 骨架、生成 `.ep-stage/ai-runtime-trace.json5` 任务包。
-3. Agent 读取 trace tasks，使用 playwright-cli 观察和操作真实页面，按 O-D-A-V 产出 `.ep-stage/ai-snippets.json5`。
-4. CLI `run` 只读取 Agent 产出的 resolved snippets，幂等追加到 `AI_APPEND_MARKER` 后并执行完整 spec。
-5. 缺少真实 resolved snippet 时，CLI 只写 `needs_review` trace，不追加占位代码、不执行 Playwright，避免假通过。
-6. 失败时写 `.ep-stage/repair-runs/<round>/repair-report.md` 并回写 trace.repairRounds，等待人审确认修补方向。
-
-skill 负责：路径解析、必要前置校验、任务清单打印、结果回显。用户视角全中文，不暴露 CLI 名称。
-
-> 钻探已前置：上游钻探、contract 提取、coverage 分析、`uncoveredCandidates` 推断由 `/glue-generate-testcase` 完成。本 skill 只消费 `testcase.json5` 和 `.ep-stage/contract.json5`，不再自行钻探，不读取 `inference-trace.json`，也不对 contract 缺失槽位二次猜测。
->
-> 修补边界：run 失败时先落 repair-report.md，等待用户确认修补方向后再重跑。不静默削弱断言、不改变 testcase 意图。重跑读取更新后的 spec/testcase 重新进入状态机。
->
-> 详细状态机和修补边界见 references/ai-runtime-loop.md。
-
-## 1. 自然语言映射
-
-```text
-/glue-run-test /abs/path/.../src/tests/014-测试需求10-20260622/testcase.json5
-/glue-run-test ../glue-project/src/tests/014-测试需求10-20260622/testcase.json5
-/glue-run-test                                                # 无参数 → 问 testcase.json5 路径
-/glue-run-test /abs/path/.../testcase.json5 --debug           # 调试模式 → 跑本地 ep-stage-skill dist
-```
-
-> `--debug` flag：正常调用走远程 `npx @epoint-testtech/ep-stage-skill@latest`。开发期想测试未发布的本地代码时传 `--debug`，skill 在 Step 4/Step 6 都改用 `node <repo>/packages/ep-stage-skill/dist/src/cli/index.js`：先跑 `prepare-tasks --testcase ...`，Agent 产出 `ai-snippets.json5` 后再跑 `run --testcase ... --ai-snippets ...`。前提：cwd 在 ep-stage monorepo 内（向上能找到 `pnpm-workspace.yaml`）；找不到时直接 exit 1 报错，不静默 fallback 到 npx。
-
-skill 把入参 `path.resolve` 绝对化，直接消费 `testcase.json5`。用户心智只保留这一个入口，不要求先显式跑 `spec` 再跑 `run`。
-
-## 2. Agent 执行剧本（7 步任务清单协议）
-
-**任务清单协议（REQ-UX-01）**：load 后**最先**单行展示技能版本（取本 SKILL.md frontmatter 的 `version` 字段），格式 `技能版本：glue-run-test <version>`；随后**立即**打印初始任务清单（Step 0）；每完成一步输出单行 `第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`；Step 7 输出全勾选终态清单 + 摘要（spec 路径 + trace 路径 + 报告路径）。
-
-### Step 0 — 打印任务清单
-
-```markdown
-**执行胶水测试任务清单**
-
-- [ ] 第 1 步 — 解析 testcase.json5 路径并定位测试项目
-- [ ] 第 2 步 — 校验 testcase.json5 输入
-- [ ] 第 3 步 — 校验 credentials.json5 凭据
-- [ ] 第 4 步 — 调用 prepare-tasks 输出 AI 任务包
-- [ ] 第 5 步 — Agent 使用 playwright-cli 完成 O-D-A-V 并写 ai-snippets.json5
-- [ ] 第 6 步 — 调用 run CLI 合并 snippet 并执行完整 spec
-- [ ] 第 7 步 — 收集 spec、trace 与报告产物并输出摘要
-```
-
-### Step 1 — 解析 testcase.json5 路径并定位测试项目
-
-- 从用户消息 / args 抽取 `testcase.json5` 路径，绝对化。入参缺失 → free text 询问"请给我 testcase.json5 的绝对或相对路径"。
-- 优先读取 `testcase.json5.runtimeContext.testProjectDir / specPath`；若缺失或校验失败，再从 testcase 所在目录向上查找 `package.json + playwright.config.ts + src/skeletons`。
-- 中文复述识别结果："已识别：testcase.json5 = `<abs>`，项目目录 = `<projectDir>`，spec = `<specPath>`"。
-
-### Step 2 — 校验 testcase.json5 输入（缺 → 引导 B）
-
-校验 `<projectDir>/src/tests/<需求名>/testcase.json5` 是否存在，且 `schemaVersion` 字段存在且合法。
-
-缺失 / schema 不合法 → 引导场景 B，AskUserQuestion 三选一：
-
-1. 跑 `/glue-generate-testcase <code_list.json5路径>`：先生成用例，回头再跑 run。
-2. 跳过用例直接组装（不推荐）：警告"无 testcase 时 run 内部也无法自动补出有效 glue 骨架"，确认后继续。
-3. 取消：直接退出，不调 CLI。
-
-### Step 3 — 校验 credentials.json5 凭据（缺 → 引导 C）
-
-校验 `<projectDir>/src/tests/<需求名>/credentials.json5` 存在，数组至少 1 条，且每条 `url / username / password` 非空。
-
-缺失 / 字段空 → 引导场景 C，先读 `~/.ep-stage/projects.index.json5` 的 `systems[].credentialsCache`，按 `url` 比对算 `cachedSystemsHit`。AskUserQuestion 三选一：
-
-1. 从全局缓存复用（仅 `cachedSystemsHit` 非空时显示）：列出命中的 url + 已缓存角色，自动拼出 `credentials.json5`（缺失角色用占位符保留）。
-2. 现在补：skill 顺序问每条角色的 URL / username / password / systemName（free text），直接写 `<需求名>/credentials.json5`。
-3. 取消：直接退出，不调 CLI。
-
-### Step 4 — 调用 prepare-tasks 输出 AI 任务包
-
-固定流程：不 which、不扫 monorepo、不 cd、不喂 stdin。用户入口仍只保留 `/glue-run-test <testcase.json5路径>`，但内部先调用 CLI `prepare-tasks`。
-
-正常模式：
-
-```bash
-npx -y @epoint-testtech/ep-stage-skill@latest prepare-tasks \
-  --testcase <projectDir>/src/tests/<需求名>/testcase.json5
-```
-
-调试模式：
-
-```bash
-D="$PWD"; REPO=""
-while [ "$D" != "/" ]; do
-  if [ -f "$D/pnpm-workspace.yaml" ] && [ -f "$D/packages/ep-stage-skill/dist/src/cli/index.js" ]; then
-    REPO="$D"; break
-  fi
-  D="$(dirname "$D")"
-done
-[ -z "$REPO" ] && { echo "错误：--debug 但找不到本地 monorepo"; exit 1; }
-echo "调试模式：本地 $REPO/packages/ep-stage-skill/dist/src/cli/index.js"
-node "$REPO/packages/ep-stage-skill/dist/src/cli/index.js" prepare-tasks \
-  --testcase <projectDir>/src/tests/<需求名>/testcase.json5
-```
-
-CLI prepare-tasks 行为：
-
-1. 解析 `runtimeContext` 或向上查找测试项目；若 `crud.spec.ts` 不存在，先自动补跑 `spec` 生成 glue 骨架。
-2. 构建 AI Runtime Tasks：取 `uncoveredCandidates` 中 `generationStrategy="ai"` 且 `coverageStatus!="blocked"` 的候选；`blocked` 候选不进入后续步骤。
-3. 写 `<caseDir>/.ep-stage/ai-runtime-trace.json5`：`tasks` 就绪，`results` 为空。
-4. 输出 trace 路径、spec 路径、AI task 数量和 blocked 数量。
-
-CLI 非 0 退出 → 复述 stderr，不进 Step 5。
-
-### Step 5 — Agent 使用 playwright-cli 完成 O-D-A-V 并写 ai-snippets.json5
-
-读取 `<caseDir>/.ep-stage/ai-runtime-trace.json5` 的 `tasks[]`。若任务数为 0，写一个空结果包：
-
-```json5
-{
-  schemaVersion: 'ep-stage-ai-snippets/v1',
-  testcasePath: '<testcase.json5绝对路径>',
-  generatedAt: '<ISO时间>',
-  results: [],
-}
-```
-
-若存在任务，先跑 `which playwright-cli` 校验本机已安装官方 CLI（v0.1.15+ 起支持 coding agent one-shot 子命令 + daemon session 模型）。缺失 → 整包 `needs_review` 后退出。可用则读 `docs/00-memory/dev-rules.md`，再按 `references/playwright-cli-odav.md` 执行：
-
-1. 生成一个命名 session：`SESSION="<moduleId>-$(date +%Y%m%d%H%M%S)"`，后续所有子命令都传 `-s=$SESSION`（daemon 保持浏览器 + cookies + localStorage 跨命令）。
-2. 从 `testcase.json5.testAccess.requiredRoles[0]` 取 primary role，从 `credentials.json5` 匹配该角色的 `loginUrl / username / password`。跑 `playwright-cli -s=$SESSION open <loginUrl> --headed`（**必须 `--headed`**，人工旁观 O-D-A-V 过程；不允许无头默认，避免运行态钻探变成无监督黑盒）→ `snapshot` 读 accessibility tree yml 拿 refs → `fill <userRef> <username>` / `fill <passRef> <password>` / `click <loginRef>` → 再 `snapshot` 验证登录成功。可选 `state-save <caseDir>/.ep-stage/auth.json` 便于跨 session 复用。
-3. `playwright-cli -s=$SESSION goto <contract.base.navigation.directUrl>` 直达列表页 → `snapshot` 观察 iframe 与初始 DOM。
-4. **初始元素扫描（page-element-scan 内核）**：在列表页加载完成后，用 `playwright-cli run-code` 将 `extract-page-elements-eval.mjs` 函数体注入主 frame 执行，拿到当前页元素清单落袋 `<caseDir>/.ep-stage/elementmap.json`（`{ title, scannedAt, elements[] }` 原始格式，grid 条目保留 `columns`/`rowActions` 供字段→列号映射）。后续 O-D-A-V 推理时 Agent 优先查此 map，snapshot refs 仅用于验证动作已生效。**不写 trace 根级**——`run` 子命令回写 trace 时全量覆盖，Agent 侧写入的自定义字段会被冲掉。
-   ```bash
-   CODE=$(cat <技能目录>/scripts/extract-page-elements-eval.mjs)
-   playwright-cli -s=$SESSION run-code "async page => page.evaluate(() => { $CODE; return JSON.stringify(extractPageElements()); })"
-   ```
-   > 注意：必须用 `run-code "async page => page.evaluate(...)"` 而不是 `eval`。`eval` 参数会被 CLI 包裹成 `() => (参数)`，文件内顶层语句（function 声明、`;` 分隔）会导致 `Passed function is not well-serializable!`；`run-code` 接收 `page => expr` 形式的 Node 侧函数，`page.evaluate` 回调体内可以安全包含完整脚本。
-   首次扫描只扫主 frame（不含弹窗 iframe），避免误扫登录残留。
-5. 对每条 task 做 O-D-A-V：
-   - **Observe**：`snapshot` 观察当前页面/iframe 结构，读 refs。
-   - **Decide**：推理下一步动作，查 `elementmap.json` 中 `label → locator` 找稳定定位符。
-   - **Act**：执行 `click <ref>` / `fill <ref> <text>` / `select <ref> <val>`。
-   - **补扫（Act 之后、Verify 之前）**：用 `run-code` 遍历 `page.frames()` 对所有 frame（含弹窗 iframe）分别注入执行，将新出现的元素按 `type|label|locator` 去重合并到 `.ep-stage/elementmap.json`。这一步确保弹窗/子表等动态创建的元素被捕获，供后续 task 直接查表使用，无需重复触发。注意 `extractAllFramesElementMap()` 依赖子 frame 也注入了同名函数，直接在主 frame eval 调用它扫不到子 frame；正确做法是 Node 侧遍历 frame：
-     ```bash
-     CODE=$(cat <技能目录>/scripts/extract-page-elements-eval.mjs)
-     playwright-cli -s=$SESSION run-code "async page => { const map = {}; for (const f of page.frames()) { try { const r = await f.evaluate(() => { $CODE; return extractPageElements(); }); r.elements.forEach(e => { if (e.label && (!map[e.label] || e.visible)) map[e.label] = { locator: e.locator, controlType: e.controlType, visible: e.visible }; }); } catch (_) {} } return JSON.stringify(map); }"
-     ```
-   - **Verify**：二次 snapshot 或 `eval "<js>"` 验证动作已生效并抽取断言值。
-   **refs 每次 snapshot 后重新编号，禁止跨 snapshot 缓存。**
-6. Agent 按 `dev-rules.md` 把观察 + 动作原料改写为符合本项目规范的 `test()` snippet（`repo*` 前缀、锚点作用域、复用 crud.spec.ts 已声明的 `directListUrl / credentialsPath / primaryRole / crudSlots / exportSlots` 常量，不重复声明）。**test 标题必须带 caseId 前缀**（如 `TC01015 同步窗口管理系统`），与 glue 用例的 `TCxxxxx 标题` 形态对齐，报告按标题回显用例 ID。
-7. 写 `<caseDir>/.ep-stage/ai-snippets.json5`，格式 `{ schemaVersion, testcasePath, generatedAt, results }`；每条 result 的 `evidence` 保留 `source: 'playwright-cli'` + snapshot yml 路径，支撑可观测性 gate。**specSnippet 值必须是合法 JSON5 字符串（单/双引号 + 转义），禁止反引号模板字符串**——JSON5 不支持 `` ` ``，run 解析即崩；建议用脚本 `JSON.stringify` 生成文件而非手写。
-8. 全部 task 完成后跑 `playwright-cli -s=$SESSION close` 释放 session（异常时 `playwright-cli kill-all` 兜底）。
-
-宿主 Agent 无 `playwright-cli`、目标系统网络不可达、testcase 信息不足或断言无法确认时，不强造 snippet；对应 result 标 `needs_review`，并在 observation/evidence 中写明原因。
-
-### Step 6 — 调用 run CLI 合并 snippet 并执行完整 spec
-
-正常模式：
-
-```bash
-npx -y @epoint-testtech/ep-stage-skill@latest run \
-  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
-  --ai-snippets <projectDir>/src/tests/<需求名>/.ep-stage/ai-snippets.json5 \
-  --headless false
-```
-
-调试模式：
-
-```bash
-node "$REPO/packages/ep-stage-skill/dist/src/cli/index.js" run \
-  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
-  --ai-snippets <projectDir>/src/tests/<需求名>/.ep-stage/ai-snippets.json5 \
-  --headless false
-```
-
-CLI run 行为：
-
-1. 读取 ai-snippets.json5；只合并 `status="resolved"` 且 `specSnippet` 非空、caseId 属于当前 tasks 的结果。
-2. 若存在 AI tasks 但缺少完整 resolved snippet，写 trace `needs_review` 后停止，不追加占位代码、不执行 Playwright。
-3. 若 snippets 完整，定位 `AI_APPEND_MARKER` 截断旧追加段，按任务顺序追加 snippets。
-4. 从 `projectDir` 跑 `npx playwright test <specPath>`，`headless=false` 时带 `--headed`。
-5. 失败时归类并写 `.ep-stage/repair-runs/<round>/repair-report.md`，同时回写 `trace.repairRounds`。
-
-CLI 非 0 退出 → 复述 stderr，不进 Step 7。
-
-### Step 7 — 收集 spec、trace 与报告产物并输出摘要
-
-用 `ls` / `Read` 校验 §3 验证清单。成功信号：
-
-- `crud.spec.ts` 已存在；若原先缺失，说明 prepare-tasks 已自动补组装。
-- `ai-runtime-trace.json5` 已落盘且含 tasks + results；若 results 含 `needs_review`，按原因提示继续 Agent O-D-A-V。
-- `ai-snippets.json5` 已落盘；resolved 结果已合并到 spec，needs_review 结果不会合并。
-- 报告目录已创建。
-- 成功路径不落 repair report；若失败，`.ep-stage/repair-runs/<round>/repair-report.md` 存在，按 §4 引导人审确认修补方向。
-- 若 CLI 返回 `credentialsNotice`，按原文回显给用户。
-
-## 3. 验证清单
-
-| 路径 | 说明 |
-|---|---|
-| `<projectDir>/src/tests/<需求名>/crud.spec.ts` | prepare-tasks 自动补组装 glue 骨架；run 在 `AI_APPEND_MARKER` 后合并 Agent snippet（幂等） |
-| `<projectDir>/src/tests/<需求名>/testcase.json5` | 必须存在 + `schemaVersion` 合法 |
-| `<projectDir>/src/tests/<需求名>/credentials.json5` | 必须存在 + 数组 ≥ 1 条 + 必填字段非空 |
-| `<projectDir>/src/tests/<需求名>/.ep-stage/contract.json5` | 由 testcase 阶段产，run 阶段只读不写 |
-| `<projectDir>/src/tests/<需求名>/.ep-stage/ai-runtime-trace.json5` | prepare-tasks 先写 tasks；run 回写 results / repairRounds |
-| `<projectDir>/src/tests/<需求名>/.ep-stage/elementmap.json` | Agent O-D-A-V 落的页面控件定位清单（含 grid columns）；run 不触碰 |
-| `<projectDir>/src/tests/<需求名>/.ep-stage/repair-runs/<round>/repair-report.md` | 失败时才产；含失败分类与摘要，待人审确认 |
-| `<projectDir>/e2e/glue-code-mvp/glue-report/<run-timestamp>/` | run 子命令产；执行账本（`index.html` glue 风格综合报告（全部用例）+ `playwright-results.json` + `run-output.log` 完整执行输出 + `run-info.json`） |
-| `<projectDir>/playwright-report/index.html` | run 子命令随执行产；Playwright 综合报告（用例状态/错误/截图/trace 回放），`npx playwright show-report` 打开 |
-| `<projectDir>/stage-report/` | run 子命令随执行产；stage-core 流程视角报告（index.html + report.pdf） |
-
-## 4. 错误处理
-
-| 触发时机 | Agent 中文呈现 + 建议 |
-|---|---|
-| 引导 A（缺脚手架） | 中文提示+退出，引导先跑 `/glue-create-project <项目名>` |
-| 引导 B（缺 testcase） | AskUserQuestion 三选一：跑 testcase / 强组装 / 取消（schema 不合法归入此类） |
-| 引导 C（缺凭据） | AskUserQuestion 三选一：缓存复用 / 现在补 / 取消 |
-| prepare-tasks / run 子命令 exit ≠ 0 | 复述 stderr；若缺 spec，也可能是 prepare-tasks 自动补跑 spec 失败 |
-| glue cases 为空 | 阻断 prepare-tasks 内部 spec 组装；提示用户回 `/glue-generate-testcase` 补齐 |
-| Playwright 执行失败 | 回显 `repairReportPath` 与失败分类；建议用户确认修补方向后重跑 `/glue-run-test <testcase.json5路径>`，不静默改 testcase |
-| 用户中途取消 | AskUserQuestion 阶段说「算了/取消」立即终止；CLI 启动后等其退出再复述 |
-
-## 5. 完成提示
-
-Step 7 全部通过后，按以下中文格式呈现：
-
-> 胶水测试执行完成
->
-> 需求：`<需求名>`／项目：`<projectDir>`
-> Spec：`<projectDir>/src/tests/<需求名>/crud.spec.ts`（glue 骨架 + Agent snippet 合并）
-> AI Runtime Trace：`<projectDir>/src/tests/<需求名>/.ep-stage/ai-runtime-trace.json5`
-> 报告目录：`<projectDir>/e2e/glue-code-mvp/glue-report/<run-timestamp>/`（run-output.log + run-info.json）
-> 综合报告：`<projectDir>/e2e/glue-code-mvp/glue-report/<run-timestamp>/index.html`（glue 风格，覆盖全部用例）
-> 技术细节：`<projectDir>/playwright-report/index.html`（trace/截图/视频）+ `<projectDir>/stage-report/`（流程 PDF）
-> 运行版本：`version = v1`
->
-> 下一步：① 调整 `testcase.json5` / `contract.json5` 后重跑 `/glue-run-test <testcase.json5路径>`；② 失败时查看 repair-report.md 确认修补方向后再重跑。
-
-失败时不要发完成提示：Playwright 失败已落 repair-report.md，按 §4 引导人审确认修补方向，不允许混合"执行完成"字样。
-
-## 6. 产物生命周期
-
-| 层 | 文件内容 | 由谁产 |
-|---|---|---|
-| glue 骨架 | 顶部 `// === 胶水模式生成 ===`，只含 glue cases | `spec` 子命令，或 `prepare-tasks` 内部自动补跑 |
-| AI 推理结果 | `.ep-stage/ai-snippets.json5`，由 Agent Runtime O-D-A-V 产出 | Agent + playwright-cli |
-| AI snippet 追加 | `AI_APPEND_MARKER` 后的 snippet，由 run 子命令按 ai-snippets.json5 合并 | `run` 子命令 |
-| trace | `.ep-stage/ai-runtime-trace.json5`，prepare-tasks 写 tasks，run 回写 results / repairRounds（全量覆盖，不保留 Agent 自定义字段） | `prepare-tasks` + `run` 子命令 |
-| elementMap | `.ep-stage/elementmap.json`，Agent O-D-A-V 落的控件定位清单（初始扫描 + 补扫合并，grid 保留 columns） | Agent + playwright-cli |
-| repair report | `.ep-stage/repair-runs/<round>/repair-report.md`，失败分类 + 摘要 | `run` 子命令（仅失败） |
-
-重跑幂等：AI 追加段在 `AI_APPEND_MARKER` 处截断旧段后重新追加，不堆积。
-
-## 7. 内嵌数据契约范例
-
-`<需求名>/credentials.json5`：
-
-```json5
-[ { url: "<请填登录页 URL>", username: "<请填>", password: "<请填>", role: "业务管理员" } ]
-```
-
-字段约束：必填 `url / username / password`；可选 `role / systemName`；数组至少 1 条；同 `(url, role)` 组合唯一；文件 gitignore。
-
-## 8. 引导场景
-
-- A（缺脚手架）：Step 1 反查 projects.index.json5 无 glue 条目 → 提示先跑 `/glue-create-project` 退出。
-- B（缺 testcase）：Step 2 缺失 / schema 不合法 → AskUserQuestion 三选一（跑 testcase / 强组装 / 取消）。
-- C（缺凭据）：Step 3 字段空 → AskUserQuestion 三选一（缓存复用 / 现在补 / 取消）。
-- D（缺 code_list.json5）：归 `/glue-generate-testcase` 处理。
-
-## 9. 按需加载
-
-- AI Runtime Loop 状态机与修补边界：`references/ai-runtime-loop.md`
-- CRUD 组装 pipeline + 失败归类：`references/crud-pipeline.md`
-- harness 治理原则：`references/harness-principles.md`
-- gap 评审协议：`references/gap-review-protocol.md`
-
-## 10. 关键约束
-
-- 钻探前置：本 skill 不再实现 contract 提取、coverage 分析、`uncoveredCandidates` 推断；这些在 `/glue-generate-testcase` 完成。
-- 当前用户入口只保留 `/glue-run-test <testcase.json5路径>`；不要要求用户先显式跑 `spec`。
-- Agent 对 AI 用例执行受控运行态推理并写 ai-snippets.json5；run 子命令只合并 resolved snippet 后执行完整 spec；失败时先落 repair-report.md 等待确认，不静默改变 testcase 意图。
-- `coverageStatus="blocked"` 的候选不进入 AI Runtime Task、不写 trace、不进 spec 追加段。
-- spec / run 都不得对 contract 缺失槽位二次猜测。
-- 用户视角始终全中文；业务断言、selector、iframe 关键字、按钮文案均由骨架 + `contract.json5` 的 `scenario.skeletonSlots` 决策，skill 不发明。
+---
+name: glue-run-test
+description: 使用时机：当用户对某需求要「跑测试 / 验证 / 端到端执行 / 跑胶水测试 / 看报告」或显式触发 `/glue-run-test <testcase.json5路径>` 时使用。
+version: 2026-07-03+06ded5d
+argument-hint: "<testcase.json5绝对/相对路径>"
+compatibility: 需要由 stage-create 生成的 glue 模式 Playwright 项目 + 已审过的 `testcase.json5` + 同目录 `credentials.json5`。
+metadata:
+  source-package: "@epoint-testtech/ep-stage-skill"
+  contract: "crud-business-module/v1"
+---
+
+# ep-stage: glue-run-test
+
+本 skill 编排 `@epoint-testtech/ep-stage-skill` CLI 与 Agent Runtime。分工固定：
+
+1. 用户入口只收 `/glue-run-test <testcase.json5路径>`。
+2. CLI `prepare-tasks` 只做确定性工作：定位项目、补组装 glue 骨架、生成 `.ep-stage/ai-runtime-trace.json5` 任务包。
+3. Agent 读取 trace tasks，使用 playwright-cli 观察和操作真实页面，按 O-D-A-V 产出 `.ep-stage/ai-snippets.json5`。
+4. CLI `run` 只读取 Agent 产出的 resolved snippets，幂等追加到 `AI_APPEND_MARKER` 后并执行完整 spec。
+5. 缺少真实 resolved snippet 时，CLI 只写 `needs_review` trace，不追加占位代码、不执行 Playwright，避免假通过。
+6. 失败时写 `.ep-stage/repair-runs/<round>/repair-report.md` 并回写 trace.repairRounds，等待人审确认修补方向。
+
+skill 负责：路径解析、必要前置校验、任务清单打印、结果回显。用户视角全中文，不暴露 CLI 名称。
+
+> 钻探已前置：上游钻探、contract 提取、coverage 分析、`uncoveredCandidates` 推断由 `/glue-generate-testcase` 完成。本 skill 只消费 `testcase.json5` 和 `.ep-stage/contract.json5`，不再自行钻探，不读取 `inference-trace.json`，也不对 contract 缺失槽位二次猜测。
+>
+> 修补边界：run 失败时先落 repair-report.md，等待用户确认修补方向后再重跑。不静默削弱断言、不改变 testcase 意图。重跑读取更新后的 spec/testcase 重新进入状态机。
+>
+> 详细状态机和修补边界见 references/ai-runtime-loop.md。
+
+## 1. 自然语言映射
+
+```text
+/glue-run-test /abs/path/.../src/tests/014-测试需求10-20260622/testcase.json5
+/glue-run-test ../glue-project/src/tests/014-测试需求10-20260622/testcase.json5
+/glue-run-test                                                # 无参数 → 问 testcase.json5 路径
+/glue-run-test /abs/path/.../testcase.json5 --debug           # 调试模式 → 跑本地 ep-stage-skill dist
+```
+
+> `--debug` flag：正常调用走远程 `npx @epoint-testtech/ep-stage-skill@latest`。开发期想测试未发布的本地代码时传 `--debug`，skill 在 Step 4/Step 6 都改用 `node <repo>/packages/ep-stage-skill/dist/src/cli/index.js`：先跑 `prepare-tasks --testcase ...`，Agent 产出 `ai-snippets.json5` 后再跑 `run --testcase ... --ai-snippets ...`。前提：cwd 在 ep-stage monorepo 内（向上能找到 `pnpm-workspace.yaml`）；找不到时直接 exit 1 报错，不静默 fallback 到 npx。
+
+skill 把入参 `path.resolve` 绝对化，直接消费 `testcase.json5`。用户心智只保留这一个入口，不要求先显式跑 `spec` 再跑 `run`。
+
+## 2. Agent 执行剧本（7 步任务清单协议）
+
+**任务清单协议（REQ-UX-01）**：load 后立即打印初始任务清单（Step 0）；每完成一步输出单行 `第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`；Step 7 输出全勾选终态清单 + 摘要（spec 路径 + trace 路径 + 报告路径）。
+
+### Step 0 — 打印任务清单
+
+```markdown
+**执行胶水测试任务清单**
+
+- [ ] 第 1 步 — 解析 testcase.json5 路径并定位测试项目
+- [ ] 第 2 步 — 校验 testcase.json5 输入
+- [ ] 第 3 步 — 校验 credentials.json5 凭据
+- [ ] 第 4 步 — 调用 prepare-tasks 输出 AI 任务包
+- [ ] 第 5 步 — Agent 使用 playwright-cli 完成 O-D-A-V 并写 ai-snippets.json5
+- [ ] 第 6 步 — 调用 run CLI 合并 snippet 并执行完整 spec
+- [ ] 第 7 步 — 收集 spec、trace 与报告产物并输出摘要
+```
+
+### Step 1 — 解析 testcase.json5 路径并定位测试项目
+
+- 从用户消息 / args 抽取 `testcase.json5` 路径，绝对化。入参缺失 → free text 询问"请给我 testcase.json5 的绝对或相对路径"。
+- 优先读取 `testcase.json5.runtimeContext.testProjectDir / specPath`；若缺失或校验失败，再从 testcase 所在目录向上查找 `package.json + playwright.config.ts + src/skeletons`。
+- 中文复述识别结果："已识别：testcase.json5 = `<abs>`，项目目录 = `<projectDir>`，spec = `<specPath>`"。
+
+### Step 2 — 校验 testcase.json5 输入（缺 → 引导 B）
+
+校验 `<projectDir>/src/tests/<需求名>/testcase.json5` 是否存在，且 `schemaVersion` 字段存在且合法。
+
+缺失 / schema 不合法 → 引导场景 B，AskUserQuestion 三选一：
+
+1. 跑 `/glue-generate-testcase <code_list.json5路径>`：先生成用例，回头再跑 run。
+2. 跳过用例直接组装（不推荐）：警告"无 testcase 时 run 内部也无法自动补出有效 glue 骨架"，确认后继续。
+3. 取消：直接退出，不调 CLI。
+
+### Step 3 — 校验 credentials.json5 凭据（缺 → 引导 C）
+
+校验 `<projectDir>/src/tests/<需求名>/credentials.json5` 存在，数组至少 1 条，且每条 `url / username / password` 非空。
+
+缺失 / 字段空 → 引导场景 C，先读 `~/.ep-stage/projects.index.json5` 的 `systems[].credentialsCache`，按 `url` 比对算 `cachedSystemsHit`。AskUserQuestion 三选一：
+
+1. 从全局缓存复用（仅 `cachedSystemsHit` 非空时显示）：列出命中的 url + 已缓存角色，自动拼出 `credentials.json5`（缺失角色用占位符保留）。
+2. 现在补：skill 顺序问每条角色的 URL / username / password / systemName（free text），直接写 `<需求名>/credentials.json5`。
+3. 取消：直接退出，不调 CLI。
+
+### Step 4 — 调用 prepare-tasks 输出 AI 任务包
+
+固定流程：不 which、不扫 monorepo、不 cd、不喂 stdin。用户入口仍只保留 `/glue-run-test <testcase.json5路径>`，但内部先调用 CLI `prepare-tasks`。
+
+正常模式：
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest prepare-tasks \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5
+```
+
+调试模式：
+
+```bash
+D="$PWD"; REPO=""
+while [ "$D" != "/" ]; do
+  if [ -f "$D/pnpm-workspace.yaml" ] && [ -f "$D/packages/ep-stage-skill/dist/src/cli/index.js" ]; then
+    REPO="$D"; break
+  fi
+  D="$(dirname "$D")"
+done
+[ -z "$REPO" ] && { echo "错误：--debug 但找不到本地 monorepo"; exit 1; }
+echo "调试模式：本地 $REPO/packages/ep-stage-skill/dist/src/cli/index.js"
+node "$REPO/packages/ep-stage-skill/dist/src/cli/index.js" prepare-tasks \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5
+```
+
+CLI prepare-tasks 行为：
+
+1. 解析 `runtimeContext` 或向上查找测试项目；若 `crud.spec.ts` 不存在，先自动补跑 `spec` 生成 glue 骨架。
+2. 构建 AI Runtime Tasks：取 `uncoveredCandidates` 中 `generationStrategy="ai"` 且 `coverageStatus!="blocked"` 的候选；`blocked` 候选不进入后续步骤。
+3. 写 `<caseDir>/.ep-stage/ai-runtime-trace.json5`：`tasks` 就绪，`results` 为空。
+4. 输出 trace 路径、spec 路径、AI task 数量和 blocked 数量。
+
+CLI 非 0 退出 → 复述 stderr，不进 Step 5。
+
+### Step 5 — Agent 使用 playwright-cli 完成 O-D-A-V 并写 ai-snippets.json5
+
+读取 `<caseDir>/.ep-stage/ai-runtime-trace.json5` 的 `tasks[]`。若任务数为 0，写一个空结果包：
+
+```json5
+{
+  schemaVersion: 'ep-stage-ai-snippets/v1',
+  testcasePath: '<testcase.json5绝对路径>',
+  generatedAt: '<ISO时间>',
+  results: [],
+}
+```
+
+若存在任务，先跑 `which playwright-cli` 校验本机已安装官方 CLI（v0.1.15+ 起支持 coding agent one-shot 子命令 + daemon session 模型）。缺失 → 整包 `needs_review` 后退出。可用则读 `docs/00-memory/dev-rules.md`，再按 `references/playwright-cli-odav.md` 执行：
+
+1. 生成一个命名 session：`SESSION="<moduleId>-$(date +%Y%m%d%H%M%S)"`，后续所有子命令都传 `-s=$SESSION`（daemon 保持浏览器 + cookies + localStorage 跨命令）。
+2. 从 `testcase.json5.testAccess.requiredRoles[0]` 取 primary role，从 `credentials.json5` 匹配该角色的 `loginUrl / username / password`。跑 `playwright-cli -s=$SESSION open <loginUrl> --headed`（**必须 `--headed`**，人工旁观 O-D-A-V 过程；不允许无头默认，避免运行态钻探变成无监督黑盒）→ `snapshot` 读 accessibility tree yml 拿 refs → `fill <userRef> <username>` / `fill <passRef> <password>` / `click <loginRef>` → 再 `snapshot` 验证登录成功。可选 `state-save <caseDir>/.ep-stage/auth.json` 便于跨 session 复用。
+3. `playwright-cli -s=$SESSION goto <contract.base.navigation.directUrl>` 直达列表页 → `snapshot` 观察 iframe 与初始 DOM。
+4. 对每条 task 做 O-D-A-V：`snapshot` 观察 → 推理决策 → `click <ref>` / `fill <ref> <text>` / `select <ref> <val>` 动作 → `snapshot` 或 `eval "<js>"` 验证并抽取断言值。**refs 每次 snapshot 后重新编号，禁止跨 snapshot 缓存**。
+5. Agent 按 `dev-rules.md` 把观察 + 动作原料改写为符合本项目规范的 `test()` snippet（`repo*` 前缀、锚点作用域、复用 crud.spec.ts 已声明的 `directListUrl / credentialsPath / primaryRole / crudSlots / exportSlots` 常量，不重复声明）。
+6. 写 `<caseDir>/.ep-stage/ai-snippets.json5`，格式 `{ schemaVersion, testcasePath, generatedAt, results }`；每条 result 的 `evidence` 保留 `source: 'playwright-cli'` + snapshot yml 路径，支撑可观测性 gate。
+7. 全部 task 完成后跑 `playwright-cli -s=$SESSION close` 释放 session（异常时 `playwright-cli kill-all` 兜底）。
+
+宿主 Agent 无 `playwright-cli`、目标系统网络不可达、testcase 信息不足或断言无法确认时，不强造 snippet；对应 result 标 `needs_review`，并在 observation/evidence 中写明原因。
+
+### Step 6 — 调用 run CLI 合并 snippet 并执行完整 spec
+
+正常模式：
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest run \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
+  --ai-snippets <projectDir>/src/tests/<需求名>/.ep-stage/ai-snippets.json5 \
+  --headless false
+```
+
+调试模式：
+
+```bash
+node "$REPO/packages/ep-stage-skill/dist/src/cli/index.js" run \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
+  --ai-snippets <projectDir>/src/tests/<需求名>/.ep-stage/ai-snippets.json5 \
+  --headless false
+```
+
+CLI run 行为：
+
+1. 读取 ai-snippets.json5；只合并 `status="resolved"` 且 `specSnippet` 非空、caseId 属于当前 tasks 的结果。
+2. 若存在 AI tasks 但缺少完整 resolved snippet，写 trace `needs_review` 后停止，不追加占位代码、不执行 Playwright。
+3. 若 snippets 完整，定位 `AI_APPEND_MARKER` 截断旧追加段，按任务顺序追加 snippets。
+4. 从 `projectDir` 跑 `npx playwright test <specPath>`，`headless=false` 时带 `--headed`。
+5. 失败时归类并写 `.ep-stage/repair-runs/<round>/repair-report.md`，同时回写 `trace.repairRounds`。
+
+CLI 非 0 退出 → 复述 stderr，不进 Step 7。
+
+### Step 7 — 收集 spec、trace 与报告产物并输出摘要
+
+用 `ls` / `Read` 校验 §3 验证清单。成功信号：
+
+- `crud.spec.ts` 已存在；若原先缺失，说明 prepare-tasks 已自动补组装。
+- `ai-runtime-trace.json5` 已落盘且含 tasks + results；若 results 含 `needs_review`，按原因提示继续 Agent O-D-A-V。
+- `ai-snippets.json5` 已落盘；resolved 结果已合并到 spec，needs_review 结果不会合并。
+- 报告目录已创建。
+- 成功路径不落 repair report；若失败，`.ep-stage/repair-runs/<round>/repair-report.md` 存在，按 §4 引导人审确认修补方向。
+- 若 CLI 返回 `credentialsNotice`，按原文回显给用户。
+
+## 3. 验证清单
+
+| 路径 | 说明 |
+|---|---|
+| `<projectDir>/src/tests/<需求名>/crud.spec.ts` | prepare-tasks 自动补组装 glue 骨架；run 在 `AI_APPEND_MARKER` 后合并 Agent snippet（幂等） |
+| `<projectDir>/src/tests/<需求名>/testcase.json5` | 必须存在 + `schemaVersion` 合法 |
+| `<projectDir>/src/tests/<需求名>/credentials.json5` | 必须存在 + 数组 ≥ 1 条 + 必填字段非空 |
+| `<projectDir>/src/tests/<需求名>/.ep-stage/contract.json5` | 由 testcase 阶段产，run 阶段只读不写 |
+| `<projectDir>/src/tests/<需求名>/.ep-stage/ai-runtime-trace.json5` | prepare-tasks 先写 tasks；run 回写 results / repairRounds |
+| `<projectDir>/src/tests/<需求名>/.ep-stage/repair-runs/<round>/repair-report.md` | 失败时才产；含失败分类与摘要，待人审确认 |
+| `e2e/glue-code-mvp/glue-report/<run-timestamp>/` | run 子命令产；执行结果账本目录 |
+
+## 4. 错误处理
+
+| 触发时机 | Agent 中文呈现 + 建议 |
+|---|---|
+| 引导 A（缺脚手架） | 中文提示+退出，引导先跑 `/glue-create-project <项目名>` |
+| 引导 B（缺 testcase） | AskUserQuestion 三选一：跑 testcase / 强组装 / 取消（schema 不合法归入此类） |
+| 引导 C（缺凭据） | AskUserQuestion 三选一：缓存复用 / 现在补 / 取消 |
+| prepare-tasks / run 子命令 exit ≠ 0 | 复述 stderr；若缺 spec，也可能是 prepare-tasks 自动补跑 spec 失败 |
+| glue cases 为空 | 阻断 prepare-tasks 内部 spec 组装；提示用户回 `/glue-generate-testcase` 补齐 |
+| Playwright 执行失败 | 回显 `repairReportPath` 与失败分类；建议用户确认修补方向后重跑 `/glue-run-test <testcase.json5路径>`，不静默改 testcase |
+| 用户中途取消 | AskUserQuestion 阶段说「算了/取消」立即终止；CLI 启动后等其退出再复述 |
+
+## 5. 完成提示
+
+Step 7 全部通过后，按以下中文格式呈现：
+
+> 胶水测试执行完成
+>
+> 需求：`<需求名>`／项目：`<projectDir>`
+> Spec：`<projectDir>/src/tests/<需求名>/crud.spec.ts`（glue 骨架 + Agent snippet 合并）
+> AI Runtime Trace：`<projectDir>/src/tests/<需求名>/.ep-stage/ai-runtime-trace.json5`
+> 报告目录：`e2e/glue-code-mvp/glue-report/<run-timestamp>/`
+> 运行版本：`version = v1`
+>
+> 下一步：① 调整 `testcase.json5` / `contract.json5` 后重跑 `/glue-run-test <testcase.json5路径>`；② 失败时查看 repair-report.md 确认修补方向后再重跑。
+
+失败时不要发完成提示：Playwright 失败已落 repair-report.md，按 §4 引导人审确认修补方向，不允许混合"执行完成"字样。
+
+## 6. 产物生命周期
+
+| 层 | 文件内容 | 由谁产 |
+|---|---|---|
+| glue 骨架 | 顶部 `// === 胶水模式生成 ===`，只含 glue cases | `spec` 子命令，或 `prepare-tasks` 内部自动补跑 |
+| AI 推理结果 | `.ep-stage/ai-snippets.json5`，由 Agent Runtime O-D-A-V 产出 | Agent + playwright-cli |
+| AI snippet 追加 | `AI_APPEND_MARKER` 后的 snippet，由 run 子命令按 ai-snippets.json5 合并 | `run` 子命令 |
+| trace | `.ep-stage/ai-runtime-trace.json5`，prepare-tasks 写 tasks，run 回写 results / repairRounds | `prepare-tasks` + `run` 子命令 |
+| repair report | `.ep-stage/repair-runs/<round>/repair-report.md`，失败分类 + 摘要 | `run` 子命令（仅失败） |
+
+重跑幂等：AI 追加段在 `AI_APPEND_MARKER` 处截断旧段后重新追加，不堆积。
+
+## 7. 内嵌数据契约范例
+
+`<需求名>/credentials.json5`：
+
+```json5
+[ { url: "<请填登录页 URL>", username: "<请填>", password: "<请填>", role: "业务管理员" } ]
+```
+
+字段约束：必填 `url / username / password`；可选 `role / systemName`；数组至少 1 条；同 `(url, role)` 组合唯一；文件 gitignore。
+
+## 8. 引导场景
+
+- A（缺脚手架）：Step 1 反查 projects.index.json5 无 glue 条目 → 提示先跑 `/glue-create-project` 退出。
+- B（缺 testcase）：Step 2 缺失 / schema 不合法 → AskUserQuestion 三选一（跑 testcase / 强组装 / 取消）。
+- C（缺凭据）：Step 3 字段空 → AskUserQuestion 三选一（缓存复用 / 现在补 / 取消）。
+- D（缺 code_list.json5）：归 `/glue-generate-testcase` 处理。
+
+## 9. 按需加载
+
+- AI Runtime Loop 状态机与修补边界：`references/ai-runtime-loop.md`
+- CRUD 组装 pipeline + 失败归类：`references/crud-pipeline.md`
+- harness 治理原则：`references/harness-principles.md`
+- gap 评审协议：`references/gap-review-protocol.md`
+
+## 10. 关键约束
+
+- 钻探前置：本 skill 不再实现 contract 提取、coverage 分析、`uncoveredCandidates` 推断；这些在 `/glue-generate-testcase` 完成。
+- 当前用户入口只保留 `/glue-run-test <testcase.json5路径>`；不要要求用户先显式跑 `spec`。
+- Agent 对 AI 用例执行受控运行态推理并写 ai-snippets.json5；run 子命令只合并 resolved snippet 后执行完整 spec；失败时先落 repair-report.md 等待确认，不静默改变 testcase 意图。
+- `coverageStatus="blocked"` 的候选不进入 AI Runtime Task、不写 trace、不进 spec 追加段。
+- spec / run 都不得对 contract 缺失槽位二次猜测。
+- 用户视角始终全中文；业务断言、selector、iframe 关键字、按钮文案均由骨架 + `contract.json5` 的 `scenario.skeletonSlots` 决策，skill 不发明。