@epoint-testtech/ep-stage-skill 0.0.3-alpha.2 → 0.0.4-alpha.1

package/codex-skill/ep-stage/glue-generate-testcase/references/testcase-tpl.md

@@ -0,0 +1,72 @@
+<!--
+testcase.md 渲染模板（AI 用）。
+
+用法（由 glue-generate-testcase SKILL Step 6 驱动）：
+- 数据源：`<需求名>/testcase.json5`（cases 结构 = 事实源） + `<需求名>/.ep-stage/contract.json`（业务槽位）+ `<需求名>/credentials.json5`（环境信息）
+- AI 按本模板渲染 testcase.md，重跑覆盖
+- 忠实性约束：cases 数量 / caseId / title / reviewStatus / requiredRole 必须**逐字**取自 testcase.json5；步骤/断言/前置条件中的具体槽位标签（菜单/列表页/按钮文字/查询字段）必须**逐字**取自 contract.json，AI 只组织自然语言句式，不得新增/捏造 contract 没有的槽位
+
+下面是格式骨架。`{{...}}` 是占位，AI 渲染时全部替换；不要把这段说明注释写进产出的 testcase.md。
+-->
+
+---
+schemaVersion: {{testcase.schemaVersion}}            # 取自 testcase.json5 顶层
+scenario: {{testcase.scenario}}                       # 取自 testcase.json5 顶层
+moduleId: {{testcase.moduleId}}                       # 取自 testcase.json5 顶层
+contractVersion: {{contract.contractVersion}}         # 取自 contract.json
+---
+
+# {{testcase.moduleName}}胶水测试用例
+
+## 环境信息
+
+- 登录地址：{{credentials[0].url}}
+- 登录账号：{{credentials[0].username}}
+- 登录密码：（已配置在 credentials.json5，不在此展示）
+- 菜单路由：{{testcase.menuPath || "（未填写，待 testcase.json5 审阅补齐）"}}
+- 列表页：{{contract.pages.list.title}}
+- 查询字段：{{contract.flows.search.searchField.label}}
+- 操作角色：{{testcase.requiredRoles[0].role}}
+- 未解析槽位：{{contract.unresolvedSlots.length > 0 ? contract.unresolvedSlots.map(s => s.slotId).join("、") : "无"}}
+
+## CRUD 冒烟用例
+
+| 用例 ID | 标题 | 前置条件 | 步骤 | 断言 |
+|---|---|---|---|---|
+| {{case.caseId}} | {{case.title}} | {{case.preconditions}} | {{case.steps_joined}} | {{case.assertions_joined}} |
+
+<!--
+说明（仅供 AI 渲染时参考，不写入产出 md）：
+
+「步骤」「断言」「前置条件」列的填充规则——
+
+cases[].steps / cases[].assertions 当前若为占位（如「执行 create 主流程（详见 .spec.ts）」、「验证 create 完成后业务断言」），
+AI 应该**基于 contract.json 槽位组装具体的自然语言表述**：
+
+- create 步骤（caseId 含 .create）：`进入菜单 {testcase.menuPath || "<未填写菜单>"}；确认列表页 {contract.pages.list.title}；点击 {contract.flows.create.entryButton.label}；填写 {contract.dataKey.label} 等字段；点击 {contract.flows.create.saveButton.label}`
+- create 断言：`新增后可在 {contract.pages.list.title} 按 {contract.flows.search.searchField.label} 查询到记录`
+- create 前置条件：`已登录并进入 {testcase.menuPath || "<未填写菜单>"}`
+
+- read 步骤（caseId 含 .read）：`进入菜单 {testcase.menuPath || "<未填写菜单>"}；按查询字段：{contract.flows.search.searchField.label} 输入测试值；点击 {contract.flows.search.submitControl.label}`
+- read 断言：`查询结果包含 {contract.flows.search.searchField.label} 对应的测试记录`
+- read 前置条件：`已存在可查询测试数据`
+
+- update 步骤（caseId 含 .update）：`在 {contract.pages.list.title} 中定位测试记录；点击 {contract.flows.update.entryAction.label}；修改 {contract.dataKey.label} 字段；点击 {contract.flows.update.saveButton.label}`
+- update 断言：`修改后可按 {contract.flows.search.searchField.label} 查询到更新后的记录`
+- update 前置条件：`已定位到待修改记录`
+
+- delete 步骤（caseId 含 .delete）：`在 {contract.pages.list.title} 中定位测试记录；点击 {contract.flows.delete.entryButton.label}；按契约策略 {contract.flows.delete.expectedOutcome} 确认删除结果`
+- delete 断言：`删除结果符合 contract.flows.delete.expectedOutcome={contract.flows.delete.expectedOutcome} 的预期`
+- delete 前置条件：`已定位到待删除记录`
+
+- 非 CRUD 用例（uncoveredCandidates 转入的 candidate / planned 用例）：AI 按 testcase.json5 cases[].businessIntent + assertionExpectation 直译；缺时填「待人工补充」，不发挥
+
+testcase.json5 的 cases[].evidence 不展示在 md 表格（人审不需要技术性溯源）；
+若 testcase.json5 cases 数量为 0，testcase.md 表格只保留表头，下方追加一段说明「本需求未生成任何用例，请审阅 .ep-stage/inference-trace.json 排查」。
+-->
+
+## 审阅引导
+
+1. 表格中**步骤、断言列若仍含占位**（如「执行 X 主流程」），表示 contract.json 对应槽位证据不足；请检查 `.ep-stage/inference-trace.json` 的 `moduleHintsInference.unresolved` 与 `contract.json.unresolvedSlots`，补齐后重跑。
+2. 如对推断步骤/断言不认可，**修改 `testcase.json5` 的 cases[] 字段**（非本 md 文件），重跑 `/glue-generate-testcase` 重新渲染本 md。
+3. 凭据信息在 `credentials.json5`；登录密码不显示在本审阅视图。

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

@@ -0,0 +1,289 @@
+---
+name: glue-run-test
+description: 使用时机：当用户对某需求要「跑测试 / 验证 / 端到端执行 / 跑胶水测试 / 看报告」或显式触发 `/glue-run-test <需求目录>` 时使用。本 skill 包装 `@epoint-testtech/ep-stage-skill` CLI 的 `spec` + `run` 双子命令，做 spec 组装与 Playwright 执行 + AI 钻探追加。
+version: 2026-06-25+6e9e357
+argument-hint: "<需求目录绝对/相对路径>"
+compatibility: 需要由 stage-create 生成的 glue 模式 Playwright 项目 + 已审过的 `<需求名>/testcase.json5` (v2) + 填好的 `<需求名>/credentials.json5`。
+metadata:
+  source-package: "@epoint-testtech/ep-stage-skill"
+  contract: "crud-business-module/v1"
+---
+
+# ep-stage: glue-run-test
+
+本 skill 引导 Agent **包装** `@epoint-testtech/ep-stage-skill` CLI 的 `spec` + `run` 双子命令，不重新实现 spec 组装、Playwright 执行或 AI 推理。CLI 内部完成：v1 初始版 spec 生成（spec 子命令）+ 凭据数组加载 + 多角色登录切换 + Playwright 执行 + uncoveredCandidates 中 `planned` 项 AI 钻探追加 + v2 追加版 spec 写回 + 报告生成 + 项目索引回写（run 子命令）。skill 负责：路径解析、反查项目脚手架、缺前置数据引导、任务清单打印、报告路径回显。用户视角全中文，不暴露 CLI 名称。
+
+> **钻探已前置**：上游钻探 + contract 提取 + coverage 分析 + uncoveredCandidates 推断由 `/glue-generate-testcase` 阶段完成（REQ-CHAIN-01）。本 skill 只消费 testcase v2 + contract.json，不再自行钻探（REQ-CHAIN-02）。
+>
+> **spec 双生命周期**（REQ-SPEC-01）：spec 子命令只产 **v1 初始版**（只含 coveredActions 胶水部分，顶部 `// === 胶水模式生成 ===`），不执行；run 子命令跑 v1 + AI 钻探 uncoveredCandidates → 追加 **v2 追加版**（底部 `// === AI 钻探追加 ===`）。重跑 run 检测已有追加段则**覆盖**，不保留旧追加。
+
+## 1. 自然语言映射
+
+```text
+/glue-run-test /abs/path/.../014-测试需求10-20260622          # 绝对路径
+/glue-run-test ../knowledge-project/.../014-测试需求10-20260622  # 相对路径
+/glue-run-test                                                # 无参数 → 问需求目录
+/glue-run-test /abs/path/.../014-测试需求10-20260622 --debug   # 调试模式 → 跑本地 ep-stage-skill dist
+```
+
+> **`--debug` flag**：正常调用走远程 `npx @epoint-testtech/ep-stage-skill@latest`。开发期想测试未发布的本地代码时传 `--debug`，skill 在 Step 4（spec）+ Step 5（run）都改用 `node <repo>/packages/ep-stage-skill/dist/src/cli/index.js`。前提：cwd 在 ep-stage monorepo 内（向上能找到 `pnpm-workspace.yaml`）；找不到时直接 exit 1 报错，不静默 fallback 到 npx。
+
+skill 把入参 `path.resolve` 绝对化，`path.basename` 取「需求名」。projectDir 不接受参数，全部从 `~/.ep-stage/projects.index.json5` 反查最新 `mode: 'glue'` 条目（多条 AskUserQuestion 让用户挑）；索引缺失走引导场景 A。
+
+## 2. Agent 执行剧本（8 步任务清单协议）
+
+**任务清单协议（REQ-UX-01）**：load 后**立即**打印初始任务清单（Step 0）；每完成一步输出单行 `✅ 第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`；Step 8 输出全勾选终态清单 + 摘要（spec 路径 + 报告路径 + lastRunStatus）。
+
+### Step 0 — 打印任务清单
+
+```markdown
+📋 **执行胶水测试任务清单**
+
+- [ ] 第 1 步 — 解析需求路径并反查项目脚手架
+- [ ] 第 2 步 — 校验 testcase.json5 输入
+- [ ] 第 3 步 — 校验 credentials.json5 凭据
+- [ ] 第 4 步 — 调用 spec 组装 CLI（只生成 v1 不执行）
+- [ ] 第 5 步 — 调用 run 执行与 AI 推理 CLI（产 v2）
+- [ ] 第 6 步 — 收集报告产物
+- [ ] 第 7 步 — 写入运行状态到项目索引
+- [ ] 第 8 步 — 输出执行摘要
+```
+
+### Step 1 — 解析需求路径并反查项目脚手架（缺 → 引导 A）
+
+- 从用户消息 / args 抽取需求目录路径，绝对化 + basename。入参缺失 → free text 询问"请给我需求目录的绝对或相对路径"。
+- 读 `~/.ep-stage/projects.index.json5`：文件不存在 / 无 glue 条目 → **引导场景 A**：中文提示"未发现胶水测试脚手架。请先跑 `/glue-create-project <项目名>` 创建脚手架后再回来"，退出不调 CLI。多条匹配 → AskUserQuestion 挑 projectDir。
+- 中文复述识别结果："已识别：需求目录 = `<abs>`，需求名 = `<basename>`，项目目录 = `<projectDir>`"。
+
+### Step 2 — 校验 testcase.json5 输入（缺 → 引导 B）
+
+校验 `<projectDir>/src/tests/<需求名>/testcase.json5` 是否存在 + `schemaVersion: "v2"`。
+
+缺失 / schema 非 v2 → **引导场景 B**，AskUserQuestion 三选一：
+
+1. **跑 `/glue-generate-testcase <需求目录>`**：先生成用例，回头再跑 run。
+2. **跳过用例直接组装**（不推荐）：警告"无 testcase 时 spec 只能生成空胶水骨架，钻探追加无法启动"，确认后继续。
+3. **取消**：直接退出，不调 CLI。
+
+### Step 3 — 校验 credentials.json5 凭据（缺 → 引导 C）
+
+校验 `<projectDir>/src/tests/<需求名>/credentials.json5` 存在 + 数组至少 1 条 + 每条 `url / username / password` 非空（参 §4.3）。
+
+缺失 / 字段空 → **引导场景 C**，先读 `~/.ep-stage/projects.index.json5` 的 `systems[].credentialsCache`，按 testcase.json5 `requiredSystems[].url` 比对算 `cachedSystemsHit`。AskUserQuestion 三选一：
+
+1. **从全局缓存复用**（仅 `cachedSystemsHit` 非空时显示）：列出命中的 url + 已缓存角色，自动拼出 credentials.json5（缺失角色用占位符保留）。
+2. **现在补**：skill 顺序问每条角色的 URL / username / password / systemName（free text），直接写 `<需求名>/credentials.json5`，**回写**全局 `systems[].credentialsCache`（按 url 归并，跨需求复用）。
+3. **取消**：直接退出，不调 CLI。
+
+### Step 4 — 调用 spec 组装 CLI（只生成 v1 不执行）
+
+固定流程（不 which、不扫 monorepo、不 cd、**不喂 stdin**）。
+
+**正常模式**（用户 args 无 `--debug`）：
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest spec \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
+  --out <projectDir>/src/tests/<需求名>/crud.spec.ts
+```
+
+**调试模式**（用户 args 含 `--debug`，要求 cwd 在 ep-stage monorepo 内；详见 §1 `--debug` flag 说明）：
+
+```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" spec \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
+  --out <projectDir>/src/tests/<需求名>/crud.spec.ts
+```
+
+CLI 内部：读 testcase v2 + `.ep-stage/contract.json` → 基于 `coveredActions` + `cases[]` 生成 **v1 初始版** `crud.spec.ts`（顶部注释 `// === 胶水模式生成 ===`，引用 `../../skeletons` 相对路径，只覆盖 coveredActions 胶水部分，不执行 Playwright）。CLI 非 0 退出 → 复述 stderr，不进 Step 5。
+
+### Step 5 — 调用 run 执行与 AI 推理 CLI（产 v2）
+
+**正常模式**（用户 args 无 `--debug`）：
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest run \
+  --spec <projectDir>/src/tests/<需求名>/crud.spec.ts \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
+  --headless false
+```
+
+**调试模式**（用户 args 含 `--debug`，要求 cwd 在 ep-stage monorepo 内；详见 §1 `--debug` flag 说明）：
+
+```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" run \
+  --spec <projectDir>/src/tests/<需求名>/crud.spec.ts \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
+  --headless false
+```
+
+CLI 内部全链路（详见 references/crud-pipeline.md「执行 + AI 推理追加」）：
+
+1. 读 `<需求名>/credentials.json5`（数组形态多角色）+ testcase.json5（v2）。
+2. **多角色登录**：通过 `@epoint-testtech/stage-core.loadCredentials(path, role?)` 按 `cases[].requiredRole` / `uncoveredCandidates[].requiredRole` 检索对应角色，启动 `LoginPage`。
+3. **跑 v1 胶水部分**：执行 spec 顶部 `// === 胶水模式生成 ===` 区段所有 `test(...)` block。
+4. **AI 钻探追加**：对 `uncoveredCandidates[].status === 'planned'` 项，按 `requiredRole` 切登录 → 页面浏览补 spec（`businessIntent` / `assertionExpectation` / `label` 驱动 test 标题与断言）→ **追加到 spec 底部**产 v2（注释 `// === AI 钻探追加 ===`）。
+5. **重跑覆盖**：检测到分段标记则**覆盖**追加段（v2 → v2'），不保留旧追加。
+6. 写报告到 `e2e/glue-code-mvp/glue-report/<run-timestamp>/`。
+
+CLI 非 0 退出 → 复述 stderr，按 §4 报告。
+
+> **凭据通路**：skill 自身**不调** `loadCredentials`；该工具由 CLI run 子命令生成的 Playwright spec 内部 import 自 `@epoint-testtech/stage-core`。skill 只校验 credentials.json5 + 引导补齐，不解析凭据明文。
+
+### Step 6 — 收集报告产物
+
+CLI 退出后用 `ls` / `Read` 校验 §3 验证清单。报告目录缺失视为整体失败，按 §4 报告。
+
+### Step 7 — 写入运行状态到项目索引
+
+CLI run 子命令已在 `~/.ep-stage/projects.index.json5` 回写：
+
+- `projects[].requirements[<i>].lastRunAt` / `lastRunStatus`（`passed` / `failed` / `partial`）
+- `systems[].credentialsCache`（按 url 归并本次 credentials.json5 用到的角色凭据）
+
+skill 校验：本需求条目存在；`lastRunAt` 是本次时间戳；`lastRunStatus` 非 `never`。缺时由 skill 补写。
+
+### Step 8 — 输出执行摘要
+
+打印全勾选终态清单 + §5 完成提示（含 spec 路径 + 报告路径 + `lastRunStatus` + Playwright HTML 报告打开指令 + 重跑提示）。
+
+## 3. 验证清单
+
+| 路径                                                            | 说明                                                |
+|-----------------------------------------------------------------|-----------------------------------------------------|
+| `<projectDir>/src/tests/<需求名>/crud.spec.ts`                   | v1 或 v2（含 `// === 胶水模式生成 ===` + 可选 `// === AI 钻探追加 ===` 分段）|
+| `<projectDir>/src/tests/<需求名>/testcase.json5`                | 必须存在 + `schemaVersion: "v2"`                    |
+| `<projectDir>/src/tests/<需求名>/credentials.json5`             | 必须存在 + 数组 ≥ 1 条 + 必填字段非空              |
+| `<projectDir>/src/tests/<需求名>/.ep-stage/contract.json`        | 由 testcase 阶段产，run 阶段只读不写                |
+| `e2e/glue-code-mvp/glue-report/<run-timestamp>/`                | run 子命令产；含执行摘要 + Playwright trace 引用    |
+| `~/.ep-stage/projects.index.json5`                              | 已更新 `lastRunAt / lastRunStatus + systems[].credentialsCache` |
+
+## 4. 错误处理
+
+失败归类与详细排障路径见 `references/crud-pipeline.md`「失败归类」节。本 skill 高频呈现：
+
+| 触发时机                  | Agent 中文呈现 + 建议                                     |
+|---------------------------|-----------------------------------------------------------|
+| 引导 A（缺脚手架）        | 中文提示+退出，引导先跑 `/glue-create-project <项目名>`   |
+| 引导 B（缺 testcase）     | AskUserQuestion 三选一：跑 testcase / 强组装 / 取消        |
+| 引导 C（缺凭据）          | AskUserQuestion 三选一：缓存复用 / 现在补 / 取消           |
+| spec 子命令 exit ≠ 0      | 复述 stderr 中文转述，不进 Step 5                          |
+| run 子命令 exit ≠ 0       | 复述 stderr；归类参 references/crud-pipeline.md 失败归类   |
+| Playwright 业务失败       | 报告 `lastRunStatus: failed`，提示打开 HTML 报告人审      |
+| `coveredActions` 为空     | 阻断 spec 子命令；提示用户回 `/glue-generate-testcase` 补齐 |
+| 用户中途取消              | AskUserQuestion 阶段说「算了/取消」立即终止；CLI 启动后等其退出再复述 |
+
+## 5. 完成提示
+
+Step 8 全部通过后，按以下中文格式呈现（不要用 success/done/passed）：
+
+> ✅ 胶水测试执行完成
+>
+> 需求：`<需求名>`／项目：`<projectDir>`
+> Spec：`<projectDir>/src/tests/<需求名>/crud.spec.ts`（v2 — 胶水 + AI 钻探追加）
+> 报告目录：`e2e/glue-code-mvp/glue-report/<run-timestamp>/`
+> Playwright HTML：`npx playwright show-report --config <projectDir>/playwright.config.ts`
+> 运行状态：`lastRunStatus = <passed/failed/partial>`（已回写 `~/.ep-stage/projects.index.json5`）
+>
+> 下一步：① 失败用例打开 HTML 报告看 trace；② 调整 testcase.json5 / ModuleHints 后重跑 `/glue-run-test <需求目录>`；③ 研发回归独立执行 `cd <projectDir> && npx playwright test src/tests/<需求名>/crud.spec.ts`（**跑文件当前内容**，v1/v2 行为见 §6）
+
+**失败时不要发完成提示**：§3 验证项任一缺失或 CLI 非 0 退出 → 按 §4 报告，不允许混合"执行完成"字样。
+
+## 6. spec 双向执行路径与生命周期（REQ-SPEC-01）
+
+生成的 `crud.spec.ts` 是 standard Playwright spec，可被 2 条路径执行；文件有 v1 / v2 两个生命周期：
+
+| 状态 | 文件内容 | 由谁产 | 何时存在 |
+|---|---|---|---|
+| **v1 初始版** | 仅 coveredActions 胶水部分（顶部 `// === 胶水模式生成 ===`） | `spec` 子命令 | 跑过 spec 但未跑过 run |
+| **v2 追加版** | v1 + AI 钻探追加（底部 `// === AI 钻探追加 ===`） | `run` 子命令 | 跑过 run 后；重跑覆盖追加段 |
+
+- **路径 ①（本 skill 标准链路）**：spec → run 子命令 → AI 推理追加产 v2。
+- **路径 ②（研发回归独立执行）**：`cd <projectDir> && npx playwright test src/tests/<需求名>/crud.spec.ts` — 纯文件 IO 跑当前内容，不区分 v1/v2，不修改文件。
+
+**测试资产自包含原则**（v1/v2 都成立）：spec 用相对路径 `import { CrudPage } from '../../skeletons/...'`；凭据由同需求目录 `credentials.json5` 加载（通过 stage-core `loadCredentials`），不依赖任何 ep-stage runtime 状态；研发人员把整个 `<需求名>/` 目录拷到任意环境都能跑（含填好的 credentials.json5）。
+
+## 7. 真实系统 E2E 运行约束
+
+- **禁止** `--headless true` 跑真实业务系统 E2E。本 skill 调用 run 子命令固定 `--headless false`。
+- 真实系统验证**必须有人在场观察**页面行为、弹窗、登录状态和业务副作用；无人工观察的无头回放不算当前阶段验收证据。
+- `--headless true` 仅允许用于本地结构调试，不作为真实系统验收方式。
+- 观察结论须与 `glue-report/<run-timestamp>/` + Playwright HTML 报告交叉核对后才作为验收证据。
+
+## 8. 内嵌数据契约范例
+
+`<需求名>/credentials.json5`（数组形态，REQ-ENV-02；详见 spec §4.3）：
+
+```json5
+// 单系统单角色（zwplace 最常见）
+[ { url: "http://192.168.x.x:8100/.../login", username: "admin", password: "..." } ]
+
+// 多系统多角色（StageZhgd 类业务）
+[
+  { url: "http://sys1/login", username: "atjsdw...", password: "Epoint@2021", role: "建设单位", systemName: "建设单位办公系统" },
+  { url: "http://sys1/login", username: "atsgdw...", password: "Epoint@2021", role: "施工单位", systemName: "建设单位办公系统" },
+  { url: "http://sys2/login", username: "...",       password: "...",         role: "审批员",   systemName: "审批端" }
+]
+```
+
+字段约束：必填 `url / username / password`；可选 `role / systemName`；数组至少 1 条；同 `(url, role)` 组合唯一；文件 gitignore。
+
+`~/.ep-stage/projects.index.json5`（run 阶段回写 `requirements[].lastRun*` + `systems[].credentialsCache`）：
+
+```json5
+{
+  projects: [{
+    projectName: "...", projectDir: "...", mode: "glue", stageCreateVersion: "0.0.4-alpha.0",
+    requirements: [{
+      name: "014-测试需求10-20260622",
+      requirementDir: "/abs/.../014-测试需求10-20260622",
+      testsDir: "<projectDir>/src/tests/014-测试需求10-20260622",
+      lastRunAt: "2026-06-25T10:00:00Z",        // run 回写
+      lastRunStatus: "passed"                    // passed | failed | partial | never；run 回写
+    }]
+  }],
+  systems: [{
+    url: "http://192.168.x.x:8100/.../login",
+    knownRoles: ["建设单位", "施工单位"],
+    credentialsCache: { "建设单位": { username: "...", password: "...", lastUsed: "..." } }  // run 回写
+  }]
+}
+```
+
+## 9. 引导场景
+
+- **A（缺脚手架）**：Step 1 反查 projects.index.json5 无 glue 条目 → 提示先跑 `/glue-create-project` 退出。
+- **B（缺 testcase）**：Step 2 缺失 / schema 非 v2 → AskUserQuestion 三选一（跑 testcase / 强组装 / 取消）。
+- **C（缺凭据）**：Step 3 字段空 → AskUserQuestion 三选一（缓存复用 / 现在补 / 取消，含 `cachedSystemsHit` 命中提示）。
+- **D（缺 code_list.md）**：归 `/glue-generate-testcase` 处理（钻探前置）。
+
+## 10. 按需加载
+
+- CRUD 组装 pipeline + 验证命令 + **失败归类**：`references/crud-pipeline.md`
+- harness 治理原则：`references/harness-principles.md`；gap 评审协议：`references/gap-review-protocol.md`
+
+## 11. 关键约束
+
+- 钻探前置：本 skill 不再实现 contract 提取 / coverage 分析 / uncoveredCandidates 推断；这些在 `/glue-generate-testcase` 完成。
+- spec 子命令**只生成不执行**（REQ-SPEC-01）；Playwright 执行只走 run 子命令 ① 或研发独立 ②。
+- run 子命令仅对 `uncoveredCandidates[].status === 'planned'` 项 AI 推理；`candidate` / `unresolved` 项不得盲目追加 spec（gap 评审协议）。
+- AI 推理阶段不修改 `cases[].businessIntent` / `assertionExpectation`，也不改 `src/skeletons/*.ts`。
+- 用户视角始终全中文；业务断言、selector、iframe 关键字、按钮文案均由骨架 + `ModuleHints` 决策，skill / spec 不发明。

package/codex-skill/ep-stage/glue-run-test/references/crud-pipeline.md

@@ -0,0 +1,145 @@
+# CRUD Pipeline 参考（CRUD Pipeline Reference）
+
+> 本文为 `glue-run-test` skill 的参考文档。所有 CLI 调用统一使用 `npx -y @epoint-testtech/ep-stage-skill@latest <subcommand>` 形态（REQ-CLI-01 / REQ-CLI-02）。
+
+## 子命令一览
+
+| 子命令 | 入口 | 说明 |
+| --- | --- | --- |
+| `testcase` | `glue-generate-testcase` skill 包装 | 上游钻探 + contract 提取 + coverage 分析 + testcase v2 生成 + credentials.template 生成 + code_list 软链 |
+| `spec` | `glue-run-test` skill 包装（**只生成不执行**） | 读 testcase + contract → 生成 v1 初始版 `crud.spec.ts`（只覆盖 coveredActions 胶水部分） |
+| `run` | `glue-run-test` skill 包装 | 读 spec + testcase + credentials → 启动 Playwright + AI 推理 uncoveredCandidates → 追加产 v2 + 报告 |
+
+> **contract 提取已内嵌**到 `testcase` 子命令（REQ-CLI-02），不暴露为独立 CLI 命令。开发期可用 `pnpm generate:crud-contract`（路由到 `src/cli/dev/extract-contract.ts`），仅作调试入口，**不进 SKILL.md**。
+
+## ModuleHints 指引（ModuleHints Guidance）
+
+`ModuleHints` 是"已提取事实"与"测试人员策略"之间的边界。
+
+以下内容应放入 hints，而不是由 Agent 自行推断：
+
+- `dataKey.selectedField` 和 `dataKey.generationStrategy`
+- `searchConditions[]`，尤其是 listbox 的 `value`
+- `buttonAliases`
+- `autofill.overrideFields`
+- `deletePolicy`
+- 断言策略覆盖
+
+对于多条件 CRUD 冒烟测试，推荐：
+
+```json
+{
+  "dataKey": {
+    "selectedField": "placename",
+    "generationStrategy": "timestamp_prefix"
+  },
+  "searchConditions": [
+    {
+      "field": "placename",
+      "component": "input",
+      "seedValue": "自动化测试名称",
+      "strategy": "timestamp_prefix",
+      "updatePrefix": "修改"
+    },
+    {
+      "field": "placecategory",
+      "component": "listbox",
+      "value": "条线大厅",
+      "createSelections": [
+        { "field": "placecategory", "value": "条线大厅" }
+      ]
+    }
+  ]
+}
+```
+
+`searchConditions` 驱动生成的 `CrudFlowSlots`。`dataKey` 仍作为兼容性和策略锚点保留，但不应与独立的 `searchField` 概念重复。
+
+## 检查 testcase 闸门（Inspect Testcase Gate）
+
+testcase 子命令产出后，由 skill 校验 `testcase.json5` 顶层结构（schemaVersion=v2 + scenario + menuPath + requiredSystems + requiredRoles + coveredActions + uncoveredCandidates + cases + reasoningSummary）。`coveredActions` 为空 → 阻断 spec 子命令；`uncoveredCandidates[].status === 'unresolved'` → 提示用户补 `ModuleHints` 或拒签该 case。
+
+详细 schema 见 [glue-generate-testcase/references/testcase-schema.md](../../glue-generate-testcase/references/testcase-schema.md)。
+
+## 生成 Spec（Generate Spec）
+
+任意 cwd 执行（**只生成不执行**，REQ-SPEC-01）：
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest spec \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
+  --out <projectDir>/src/tests/<需求名>/crud.spec.ts
+```
+
+生成的 spec（v1 初始版）应当：
+
+- 从 `../../skeletons` 导入 `CrudPage`、`LoginPage`、`MenuPage` 以及 `type CrudFlowSlots`
+- 定义 `const crudSlots: CrudFlowSlots`
+- 调用 `await crudPage.runCrudFlow()`
+- 仅覆盖 `coveredActions`（胶水部分）；`uncoveredCandidates` 留给 `run` 子命令 AI 推理追加
+- 避免内联 Playwright 操作流程
+
+## 执行 + AI 推理追加（Run + AI Inference Append）
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest run \
+  --spec <projectDir>/src/tests/<需求名>/crud.spec.ts \
+  --testcase <projectDir>/src/tests/<需求名>/testcase.json5 \
+  --headless false
+```
+
+run 子命令内部：
+
+1. 读 `<需求名>/credentials.json5`（数组形态多角色，REQ-ENV-02）
+2. 启动 Playwright → 按 `cases[].requiredRole` 切换登录
+3. 跑 v1 胶水部分 spec
+4. 对 `uncoveredCandidates[].status === 'planned'` 项 AI 实时推理（页面浏览 + 补 spec），用 `uncoveredCandidates[].requiredRole` 切换登录
+5. 追加到 spec 底部产 v2（带 `// === AI 钻探追加 ===` 分段注释）
+6. 报告落 `e2e/glue-code-mvp/glue-report/<run-timestamp>/`
+7. 回写 `~/.ep-stage/projects.index.json5` 的 `systems[].credentialsCache` + `requirements[].lastRun*`
+
+**重跑 run**：检测到 spec 已含 `// === AI 钻探追加 ===` 分段时**覆盖追加段**，不保留旧追加（REQ-SPEC-01 v1/v2 生命周期）。
+
+## 凭据配置（Credentials Config）
+
+凭据下沉到**需求级** `credentials.json5` 数组形态（REQ-ENV-02 / REQ-ENV-03），**不再用 `.env`**：
+
+```json5
+// <projectDir>/src/tests/<需求名>/credentials.json5（gitignore）
+[
+  {
+    url: "http://192.168.x.x:8100/.../login",
+    username: "admin",
+    password: "***",
+    role: "admin",           // 可选，多角色场景必填
+    systemName: "主业务系统"  // 可选，便于审阅与报告
+  }
+]
+```
+
+字段约束（Task 1.1 `validateCredentials` 强制）：
+
+- 必填：`url` / `username` / `password`
+- 可选：`role`（用于 Playwright 多角色登录切换）/ `systemName`
+- `(url, role)` 组合唯一
+
+完整流程参考 [glue-generate-testcase SKILL.md](../../glue-generate-testcase/SKILL.md) 第 5 步「与用户交互确认推断结果」。
+
+## 在消费方 glue 项目中本地编译验证（Optional Local Check）
+
+```bash
+cd <projectDir>
+pnpm --ignore-workspace exec tsc --noEmit
+```
+
+仅校验 v1 spec 编译通过；不执行测试。Playwright 真实执行走 `run` 子命令。
+
+## 失败归类（Failure Triage）
+
+若运行时失败，将失败原因归类为：
+
+- **系统可达性或登录配置** — credentials.json5 缺字段 / URL 不通 / 角色凭据错；引导场景 C
+- **上游物料不匹配** — code_list.md 缺字段；引导场景 D
+- **`ModuleHints` 缺失或错误** — testcase.json5 `coveredActions` 为空 / `uncoveredCandidates` 长期 `unresolved`
+- **骨架/组件行为** — `CrudPage` / `LoginPage` 实现 bug；本地修复后回归
+- **包生成器缺陷** — `spec` / `run` 子命令产物错误；走 ep-stage-skill 仓库 issue

package/codex-skill/ep-stage/{glue-test → glue-run-test}/scripts/generate-crud-spec.mjs

@@ -24,7 +24,7 @@ function help() {
 
 Notes:
   - Relative upstream paths are resolved from the repository root.
-  - The contract path is passed to @epoint/ep-stage-skill relative to its package root.
+  - The contract path is passed to @epoint-testtech/ep-stage-skill relative to its package root.
   - The script fails when unresolvedSlots is non-empty.
 `);
 }
@@ -88,7 +88,7 @@ mkdirSync(path.dirname(contractAbs), { recursive: true });
 
 run([
   '--filter',
-  '@epoint/ep-stage-skill',
+  '@epoint-testtech/ep-stage-skill',
   'generate:crud-contract',
   '--',
   '--module-id',
@@ -125,7 +125,7 @@ mkdirSync(path.dirname(specAbs), { recursive: true });
 
 run([
   '--filter',
-  '@epoint/ep-stage-skill',
+  '@epoint-testtech/ep-stage-skill',
   'generate:playwright-tests',
   '--',
   '--contract',

package/codex-skill/ep-stage/recording-to-glue/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: recording-to-glue
 description: 使用时机：当用户讨论或规划「将录制产出的 Playwright 脚本转换为 ep-stage 胶水骨架（glue skeleton）或组件（component）候选代码」时使用。
+version: 2026-06-23+a9e7576
 ---
 
 # ep-stage: recording-to-glue

package/codex-skill/ep-stage/scripts/validate-skill.mjs

@@ -1,4 +1,13 @@
 #!/usr/bin/env node
+// validate-skill.mjs — 校验 ep-stage scope 下所有 skill 的 SKILL.md frontmatter
+// + 双发现目录（.claude/skills / .agents/skills）symlink 指向。
+//
+// version 字段维护契约（REQ-VER-003）：
+//   当 SKILL.md 内容（frontmatter 或正文）发生变更时，维护者必须手动把
+//   `version:` 更新为 `YYYY-MM-DD+<7位短SHA>`，其中 <短SHA> 取当前 HEAD。
+//   快捷生成命令：date +"%Y-%m-%d"+$(git rev-parse --short HEAD)
+//   pre-commit hook（.husky/pre-commit → check-skill-version-bump.mjs）会
+//   自动校验：改了 SKILL.md 但没改 version 行 → 阻塞 commit。
 import { lstatSync, readFileSync, realpathSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -8,6 +17,9 @@ const epStageRoot = path.resolve(__dirname, '..');
 const packageRoot = path.resolve(epStageRoot, '../..');
 const repoRoot = path.resolve(packageRoot, '../..');
 
+// version 值正则：YYYY-MM-DD+<7位十六进制短SHA>
+const VERSION_PATTERN = /^\d{4}-\d{2}-\d{2}\+[0-9a-f]{7}$/;
+
 function readFrontmatter(skillRoot) {
   const skillPath = path.join(skillRoot, 'SKILL.md');
   const text = readFileSync(skillPath, 'utf8');
@@ -18,17 +30,20 @@ function readFrontmatter(skillRoot) {
   return {
     name: frontmatter.match(/^name:\s*(.+)$/m)?.[1]?.trim(),
     description: frontmatter.match(/^description:\s*(.+)$/m)?.[1]?.trim(),
+    version: frontmatter.match(/^version:\s*(.+)$/m)?.[1]?.trim(),
     skillPath,
   };
 }
 
 function assertSkill(skillRoot, expectedName) {
-  const { name, description, skillPath } = readFrontmatter(skillRoot);
+  const { name, description, version, skillPath } = readFrontmatter(skillRoot);
   if (name !== expectedName) throw new Error(`Expected name ${expectedName} in ${skillPath}, got ${name ?? 'missing'}`);
   if (!description?.startsWith('使用时机') && !description?.startsWith('Use when')) throw new Error(`${skillPath} description 必须以「使用时机」或「Use when」开头`);
   if (description.length > 1024) throw new Error(`${skillPath} description exceeds 1024 characters`);
   if (path.basename(skillRoot) !== name) throw new Error(`${skillPath} directory basename must match name`);
-  return { name, descriptionLength: description.length, skillRoot };
+  if (!version) throw new Error(`${skillPath} version 字段缺失；维护者改 SKILL.md 时必须同步更新 version（格式 YYYY-MM-DD+<7位短SHA>）`);
+  if (!VERSION_PATTERN.test(version)) throw new Error(`${skillPath} version 格式非法 "${version}"；应为 YYYY-MM-DD+<7位短SHA>，如 2026-06-23+a9e7576`);
+  return { name, descriptionLength: description.length, version, skillRoot };
 }
 
 function assertSymlink(linkPath, targetPath) {
@@ -40,10 +55,14 @@ function assertSymlink(linkPath, targetPath) {
 }
 
 // ep-stage scope 下四个 skill 的包内真相源目录。
+// 注：Task 0.2 已 git mv 改名 3 个 skill 目录（glue-* 前缀化）。
+// - glue-create-project：Task 2.1 已同步 SKILL.md frontmatter name → 'glue-create-project'。
+// - glue-generate-testcase：Task 3.2 已同步 SKILL.md frontmatter name → 'glue-generate-testcase'。
+// - glue-run-test：Task 4.3 已同步 SKILL.md frontmatter name → 'glue-run-test'。
 const skillSources = [
-  { name: 'create-project', source: path.join(epStageRoot, 'create-project') },
-  { name: 'glue-test', source: path.join(epStageRoot, 'glue-test') },
-  { name: 'glue-testcase', source: path.join(epStageRoot, 'glue-testcase') },
+  { name: 'glue-create-project', source: path.join(epStageRoot, 'glue-create-project') },
+  { name: 'glue-generate-testcase', source: path.join(epStageRoot, 'glue-generate-testcase') },
+  { name: 'glue-run-test', source: path.join(epStageRoot, 'glue-run-test') },
   { name: 'recording-to-glue', source: path.join(epStageRoot, 'recording-to-glue') },
 ];
 
@@ -57,11 +76,14 @@ const discoveryDirs = [
   path.join(repoRoot, '.agents/skills'),
 ];
 
+// 注：symlink 名总是与包内目录 basename 一致（Phase 0 重建后）。
+// Task 4.3 收敛后，3 个 glue-* skill 的 SKILL.md `name` 与目录 basename 完全一致；symlink 仍以 basename 为准。
 const symlinks = [];
 for (const dir of discoveryDirs) {
   for (const { name, source } of skillSources) {
-    assertSymlink(path.join(dir, name), source);
-    symlinks.push({ dir: path.relative(repoRoot, dir), name, pointsTo: path.relative(repoRoot, source) });
+    const linkName = path.basename(source);
+    assertSymlink(path.join(dir, linkName), source);
+    symlinks.push({ dir: path.relative(repoRoot, dir), name, linkName, pointsTo: path.relative(repoRoot, source) });
   }
 }
 

package/dist/src/cli/dev/extract-contract.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 开发期 contract 提取入口（REQ-CLI-03）。被 generate:crud-contract pnpm script 调用，
+ * 不在 index.ts 注册为子命令，不出现在任何 SKILL.md。
+ *
+ * 行为与 0.0.3-alpha.2 的 generate-crud-contract.ts 完全等价；本次重构仅把执行
+ * 入口包装成可被 pnpm script 与 generate-testcase 子命令复用的纯函数。
+ *
+ * @param argv - 命令行参数（--module-id/--docs/--code-list/--webapp/--java-actions/--hints/--out）。
+ * @returns 写入的 contract.json 绝对路径。
+ */
+export declare function runExtractContract(argv: string[]): {
+    contractPath: string;
+};
+//# sourceMappingURL=extract-contract.d.ts.map

package/dist/src/cli/dev/extract-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"extract-contract.d.ts","sourceRoot":"","sources":["../../../../src/cli/dev/extract-contract.ts"],"names":[],"mappings":"AA+GA;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAkB3E"}