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

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

@@ -0,0 +1,249 @@
+---
+name: glue-run-test
+description: 使用时机：当用户对某需求要「跑测试 / 验证 / 端到端执行 / 跑胶水测试 / 看报告」或显式触发 `/glue-run-test <需求目录>` 时使用。本 skill 包装 `@epoint-testtech/ep-stage-skill` CLI 的 `spec` + `run` 双子命令，做 spec 组装与 Playwright 执行 + AI 钻探追加。
+version: 2026-06-25+79c305a
+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                                        # 无参数 → 问需求目录
+```
+
+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**）：
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest 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）
+
+固定命令形式：
+
+```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
+```
+
+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"}

package/dist/src/cli/dev/extract-contract.js

@@ -0,0 +1,114 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { buildCrudBusinessModuleContract, extractCodeListSummary, extractHtmlPage, extractJavaAction, extractSpecYaml, } from '../../index.js';
+/**
+ * 解析 dev/extract-contract.ts 的命令行参数。
+ *
+ * @param argv - process.argv.slice(2)。
+ * @returns 解析后的 ExtractContractArgs。
+ * @throws 缺少必填参数或显式使用废弃的 --module 时抛错。
+ */
+function parseExtractContractArgs(argv) {
+    const result = {};
+    const normalizedArgv = argv.filter((arg) => arg !== '--');
+    for (let index = 0; index < normalizedArgv.length; index += 2) {
+        const key = normalizedArgv[index];
+        const value = normalizedArgv[index + 1];
+        if (!key?.startsWith('--') || !value) {
+            throw new Error(`Invalid argument pair near ${key ?? '<empty>'}`);
+        }
+        result[key.slice(2)] = value;
+    }
+    if (result.module) {
+        throw new Error('已废弃 --module，请使用 --module-id。');
+    }
+    for (const key of ['module-id', 'docs', 'code-list', 'webapp', 'java-actions', 'out']) {
+        if (!result[key]) {
+            throw new Error(`Missing required argument --${key}`);
+        }
+    }
+    return {
+        module: result['module-id'],
+        docs: result.docs,
+        codeList: result['code-list'],
+        webapp: result.webapp,
+        javaActions: result['java-actions'],
+        hints: result.hints,
+        out: result.out,
+    };
+}
+/**
+ * 列出指定目录下所有 .html 文件并返回排序后的绝对路径。
+ *
+ * @param dir - HTML 物料目录。
+ * @returns 排序后的绝对路径数组。
+ */
+function htmlFiles(dir) {
+    return readdirSync(dir)
+        .filter((fileName) => fileName.endsWith('.html'))
+        .sort()
+        .map((fileName) => path.join(dir, fileName));
+}
+/**
+ * 列出指定目录下所有 *Action.java 文件并返回排序后的绝对路径。
+ *
+ * @param dir - Java Action 物料目录。
+ * @returns 排序后的绝对路径数组。
+ */
+function javaFiles(dir) {
+    return readdirSync(dir)
+        .filter((fileName) => fileName.endsWith('Action.java'))
+        .sort()
+        .map((fileName) => path.join(dir, fileName));
+}
+/**
+ * 解析 docs 目录下的 spec.yaml；缺失时返回最小空骨架（保证 contract 构建不阻断）。
+ *
+ * @param docsDir - 需求文档目录。
+ * @param moduleId - 模块 ID。
+ * @param codeListSummary - 已解析的 code_list 摘要。
+ * @returns ExtractedSpecYaml。
+ */
+function resolveSpec(docsDir, moduleId, codeListSummary) {
+    const specPath = path.join(docsDir, 'spec.yaml');
+    if (existsSync(specPath))
+        return extractSpecYaml(specPath);
+    return {
+        path: specPath,
+        module: { id: moduleId, label: codeListSummary.moduleLabel },
+        fields: [],
+        businessRules: [],
+    };
+}
+/**
+ * 开发期 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 function runExtractContract(argv) {
+    const args = parseExtractContractArgs(argv);
+    const hints = args.hints
+        ? JSON.parse(readFileSync(args.hints, 'utf8'))
+        : undefined;
+    const codeList = extractCodeListSummary(args.codeList);
+    const contract = buildCrudBusinessModuleContract({
+        moduleId: args.module,
+        spec: resolveSpec(args.docs, args.module, codeList),
+        codeList,
+        pages: htmlFiles(args.webapp).map(extractHtmlPage),
+        actions: javaFiles(args.javaActions).map(extractJavaAction),
+        hints,
+    });
+    mkdirSync(path.dirname(args.out), { recursive: true });
+    writeFileSync(args.out, `${JSON.stringify(contract, null, 2)}\n`, 'utf8');
+    console.log(`Wrote ${args.out}`);
+    return { contractPath: path.resolve(args.out) };
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runExtractContract(process.argv.slice(2));
+}