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

package/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: ep-stage-skill-package
-description: 使用时机：当需要维护 @epoint/ep-stage-skill 包源码、CLI 提取器、CRUD 契约生成器，或面向 Codex 的 ep-stage skill 资产时使用。
+description: 使用时机：当需要维护 @epoint-testtech/ep-stage-skill 包源码、CLI 提取器、CRUD 契约生成器，或面向 Codex 的 ep-stage skill 资产时使用。
 ---
 
-# @epoint/ep-stage-skill 包
+# @epoint-testtech/ep-stage-skill 包
 
 本包负责面向 Codex 的 `ep-stage` skill 背后的确定性工具链：
 

package/codex-skill/ep-stage/.omc/state/sessions/d636ad35-5fc9-4d5e-85b0-2bcad7d86ee5/pre-tool-advisory-throttle.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "entries": {
+    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
+      "last_emitted_at_ms": 1782437222409,
+      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
+    }
+  },
+  "updated_at": "2026-06-26T01:27:02.409Z"
+}

package/codex-skill/ep-stage/glue-create-project/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: glue-create-project
+description: 使用时机：当用户表达「创建胶水项目 / 测试脚手架 / 新建 glue 项目」或显式触发 `/glue-create-project [名称或路径]` 时使用。本 skill 只创建胶水模式（glue）Playwright 测试脚手架，不收集登录信息，不写 .env / stage-context.md。
+version: 2026-06-25+6e9e357
+argument-hint: "<脚手架项目名或脚手架项目路径>"
+---
+
+# ep-stage: glue-create-project
+
+本 skill 引导 Agent **包装** `@epoint-testtech/stage-create` CLI 的 glue 模式，不重新实现脚手架。用户视角全中文，不暴露 CLI 名称。
+
+> CLI 自 0.0.4-alpha.0 起已中性化：不再收集业务系统登录信息，不再写 `<projectDir>/.env`，也不再写 `<projectDir>/stage-context.md`。项目元信息全部沉到 `~/.ep-stage/projects.index.json5`（含 `stageCreateVersion`）。登录凭据由下游 `glue-generate-testcase` / `glue-run-test` 在需求级 `credentials.json5` 中收集。
+
+## 1. 自然语言映射规则
+
+用户在 Claude Code / Codex 里触发 skill 的典型形式：
+
+```text
+/glue-create-project my-project              # 裸名 → 落 <pwd>/e2e-test/my-project
+/glue-create-project path/my-project         # 含 / → 原样落点
+/glue-create-project /abs/path/my-project    # 绝对路径 → 原样落点
+/glue-create-project                         # 无参数 → 问项目名
+/glue-create-project my-project --debug      # 调试模式 → 跑本地 monorepo 的 stage-create dist
+```
+
+> **`--debug` flag**：正常调用走远程 `npx @epoint-testtech/stage-create@latest`。开发期想测试未发布的本地代码时传 `--debug`，skill 在 Step 3 改用 `node <repo>/packages/stage-create/dist/index.js`。前提：cwd 在 ep-stage monorepo 内（向上能找到 `pnpm-workspace.yaml`）；找不到时直接 exit 1 报错，不静默 fallback 到 npx。
+
+### 1.1 目标位置与项目名（路径解析三段式）
+
+CLI 接收 `[project-name]` 参数，内部用 `path.basename` 取项目名、`path.resolve` 取输出目录（基于 Agent cwd）：
+
+| 用户输入                                    | skill 传给 CLI 的值                         | 最终落点                                |
+|---------------------------------------------|---------------------------------------------|-----------------------------------------|
+| 含 `/` 或绝对路径                           | 原样透传                                    | `<cwd>/...` 或绝对路径；项目名取 basename |
+| 裸名（无 `/`）                              | 拼成 `e2e-test/<name>`                      | `<cwd>/e2e-test/<name>`                 |
+| 无参数                                      | 先问 `<name>`，再拼 `e2e-test/<name>`        | `<cwd>/e2e-test/<name>`                 |
+
+**逃生口**：想在当前 cwd 根直接建裸名（不进 `e2e-test/`），用 `./my-project`（含 `/`）。
+
+中文目录名 macOS/Linux 能建，但 npm scope 校验和跨平台兼容差。Agent 收到中文名时，AskUserQuestion 二选一：保留中文 / 换 kebab-case 建议（如 `我的项目` → `my-project`）。
+
+### 1.2 模式 — 固定 glue
+
+本 skill 只创建 glue 项目，固定传 `--mode glue`，不暴露 default 模式入口。
+
+### 1.3 工作目录 (cwd) 确认
+
+Agent 在调用 CLI 前必须：跑 `pwd` → 按 §1.1 算最终落点 → 中文复述"将在 `<最终落点>` 下创建项目，确认吗？" → 用户否认 → 让用户给绝对路径或先 `cd` 切换。
+
+典型陷阱：cwd 是 git 仓库根（存在 `.git/`）时必须额外二次确认，避免污染该仓库工作树。
+
+## 2. Agent 执行剧本（7 步任务清单协议）
+
+**任务清单协议（REQ-UX-01）**：
+
+- 加载 skill 后**立即**打印初始任务清单（Step 0）。
+- 每完成一步，输出单行状态更新 `✅ 第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`（不重写完整清单）。
+- Step 7 输出全勾选终态清单 + 完成摘要。
+
+### Step 0 — 打印任务清单
+
+```markdown
+📋 **创建胶水测试项目任务清单**
+
+- [ ] 第 1 步 — 抽取项目名与落点
+- [ ] 第 2 步 — 补齐核心参数（含 cwd 确认）
+- [ ] 第 3 步 — 调用脚手架 CLI
+- [ ] 第 4 步 — 验证脚手架产物
+- [ ] 第 5 步 — 安装依赖
+- [ ] 第 6 步 — 写入项目索引
+- [ ] 第 7 步 — 输出摘要
+```
+
+### Step 1 — 抽取项目名与落点
+
+从用户原始消息 / args 抽取目标路径/项目名（规则见 §1）。模式固定 glue。中文复述识别结果：
+
+> 已识别：项目名 = `xxx`，模式 = `胶水模式 (glue)`，落点 = `<pwd>/e2e-test/xxx`。
+
+识别失败/不确定 → Step 2 补齐。
+
+### Step 2 — 补齐核心参数（含 cwd 确认）
+
+只在缺失/有疑时触发，全中文：
+
+- 缺 `projectName`（无参数）→ free text 询问"请告诉我新项目的名称"，按 §1.1 拼 `e2e-test/<name>`。
+- 中文项目名 → AskUserQuestion 二选一：保留中文 / 换 `<kebab-case 建议>`。
+- cwd 是 git 仓库根 → AskUserQuestion 二选一：在此 cwd 创建 / 取消并手动 cd。
+
+> 本 skill 固定 glue 模式，不再收集登录信息，无需就模式或登录配置询问。
+
+### Step 3 — 调用脚手架 CLI
+
+固定流程（不 which、不扫 monorepo、不 cd 进项目、**不喂 stdin**）。`<targetPath>` 由 §1.1 算出。
+
+**正常模式**（用户 args 无 `--debug`）：
+
+```bash
+npx -y @epoint-testtech/stage-create@latest "<targetPath>" --mode glue
+```
+
+**调试模式**（用户 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/stage-create/dist/index.js" ]; then
+    REPO="$D"; break
+  fi
+  D="$(dirname "$D")"
+done
+[ -z "$REPO" ] && { echo "❌ --debug 但找不到本地 monorepo（需 cwd 在 ep-stage 仓库内向上能找到 pnpm-workspace.yaml + packages/stage-create/dist/index.js）"; exit 1; }
+echo "▸ 调试模式：本地 $REPO/packages/stage-create/dist/index.js"
+node "$REPO/packages/stage-create/dist/index.js" "<targetPath>" --mode glue
+```
+
+CLI 中性化后**不读 stdin**，不询问登录 URL / 用户名 / 密码 / 知识库根。
+
+### Step 4 — 验证脚手架产物
+
+按 §4 验证产物。验证失败 → §3 错误处理报告，不发完成提示。
+
+### Step 5 — 安装依赖
+
+1. 先 `pnpm ping` 检测 registry 连通性：
+   - 连不上（超时/报错）→ 跳过自动安装，提示 `网络不通，依赖未自动安装，请手动执行: pnpm install --dir <projectDir>`。
+   - 连通 → 进入下一步。
+2. `pnpm install --dir "<projectDir>"`（**禁用 `cd`** 进入项目目录，必须用 `--dir`）。若 `<projectDir>` 位于某个 pnpm workspace 内（向上能找到 `pnpm-workspace.yaml`），改用 `pnpm install --dir "<projectDir>" --ignore-workspace` 做独立安装。
+3. **必须实时透传 pnpm 输出**（进度条、日志），不得静默执行。安装失败 → 如实报告 stderr，不谎报成功；骨架已生成，用户可手动重跑。
+
+### Step 6 — 写入项目索引
+
+CLI 0.0.4-alpha.0 已在 `~/.ep-stage/projects.index.json5` 的 `projects[]` 数组末尾追加本项目条目（字段精简，含 `stageCreateVersion`，**不含** `envPath/stageContextPath/knowledgeRoot/codeListPaths`）。Agent 校验：
+
+- 文件存在
+- 末尾条目 `projectDir` 与本次创建一致
+- 字段含 `projectName / projectDir / mode='glue' / createdAt / stageCreateVersion / requirements=[]`
+
+JSON5 项目条目范例（CLI 自动写）：
+
+```json5
+// ~/.ep-stage/projects.index.json5 项目条目范例（CLI 自动写，无 stageContextPath/envPath/knowledgeRoot）
+{
+  projectName: '<projectName>',
+  projectDir: '<绝对路径>',
+  mode: 'glue',
+  createdAt: '2026-06-25T...',
+  stageCreateVersion: '0.0.4-alpha.0',
+  requirements: [],
+}
+```
+
+条目缺失 → 提示"索引文件未登记本项目，后续 ep-stage skills/CLI 无法发现，请检查 stage-create CLI 版本（应 ≥ 0.0.4-alpha.0）"。
+
+### Step 7 — 输出摘要
+
+打印全勾选终态清单 + §5 完成提示。
+
+## 3. 错误处理
+
+| CLI 错误（原文）                  | 触发时机    | Agent 中文呈现 + 建议                                                                                                |
+|-----------------------------------|-------------|----------------------------------------------------------------------------------------------------------------------|
+| `目录已存在: <path>` (exit 1)     | Step 3 前置 | "目录 `<path>` 已存在。我不会主动删除任何已存在目录。" → AskUserQuestion 三选一：换名重来 / 改 cwd / 取消              |
+| npm `404 / ENOTFOUND / ETIMEDOUT` | npx 拉包失败 | "无法从 npm 拉取 @epoint-testtech/stage-create" → 建议 ① 检查网络 ② `npm config get registry` ③ `npm i -g` 预装        |
+| 其他 exit !== 0                   | CLI 崩溃    | 把 stderr 原文中文转述并贴出，建议复制错误私聊开发                                                                   |
+
+**半成品回滚**：CLI 在校验失败时（目录已存在）在 `mkdirSync` 之前退出，无副作用。若 CLI 已 `mkdirSync` 后中途崩，Agent **不主动 `rm`**，提示用户手动检查 `<path>` 后决定是否 `rm -rf` 重试。理由：cwd 不一定可信，盲删可能误伤。
+
+**用户中途取消**：AskUserQuestion 阶段等待不超时；自然对话阶段说「算了/取消/stop」立即终止不调 CLI；已调 CLI 后用户取消 → CLI 无中途取消信号，等 CLI 退出后再复述结果。
+
+## 4. 验证清单
+
+CLI 退出后必须用 `ls` / `Read` 校验产物。验证失败视为整体失败，不要谎报成功。
+
+| 路径                                | 说明                          |
+|-------------------------------------|-------------------------------|
+| `<projectDir>/package.json`         | 模板渲染产出                  |
+| `<projectDir>/playwright.config.ts` | Playwright 基础配置           |
+| `<projectDir>/tsconfig.json`        | TS 配置                       |
+| `<projectDir>/src/skeletons/`       | 业务骨架目录（非空）          |
+| `<projectDir>/src/web/component/`   | 页面组件目录                  |
+| `<projectDir>/src/report/`          | 报告辅助目录                  |
+| `~/.ep-stage/projects.index.json5`  | 用户级索引，应新增本项目条目  |
+
+> **不再校验** `<projectDir>/.env`（CLI 不再写）和 `<projectDir>/stage-context.md`（CLI 不再写，元信息已沉到 projects.index.json5）。
+
+**不验证什么**：模板占位符 `{{projectName}}` 是否替换（已由 stage-create prepublish 校验）；业务系统登录配置（中性化后不再涉及）。
+
+## 5. 完成提示
+
+Step 7 验证与依赖安装都通过后，按以下中文格式呈现结果。不要用英文 success/done/created：
+
+> ✅ 项目创建完成，依赖已安装
+>
+> 路径：`<projectDir 绝对路径>`
+> 模式：胶水模式 (glue)
+> 索引登记：`~/.ep-stage/projects.index.json5`（含 stageCreateVersion）
+> 依赖：已 `pnpm install` 完成
+> 下一步：对某需求跑 `/glue-generate-testcase <需求目录路径>` 生成用例
+
+**失败时不要发完成提示**：第 4 节任一验证项失败或依赖安装失败 → 按 §3 报告，不允许在失败信息里混合"项目创建完成"字样。
+
+## 6. 引导场景
+
+- **A（缺脚手架）**：N/A — 本 skill 本身即建脚手架的入口，不存在"缺脚手架"前置。
+- **其他**：cwd 是 git 仓库根 → Step 2 二次确认；中文目录名 → Step 2 建议改 kebab-case。

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

@@ -0,0 +1,274 @@
+---
+name: glue-generate-testcase
+description: 使用时机：当用户对某需求要「生成用例 / 准备测试场景 / 钻探上游需求生成胶水冒烟用例」或显式触发 `/glue-generate-testcase <code_list.md路径>` 时使用。本 skill 包装 `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，并负责自然语言映射、缺数据引导、Step 5 凭据交互确认。
+version: 2026-06-26+58fd337
+argument-hint: "<code_list.md绝对/相对路径>"
+---
+
+# ep-stage: glue-generate-testcase
+
+本 skill 引导 Agent **包装** `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，不重新实现钻探与用例生成。CLI 内部完成物料解析 + contract 提取（内嵌）+ coverage 分析 + testcase v2 装配 + credentials.template 生成 + code_list.md 软链。skill 负责：`code_list.md` 路径解析、反查项目脚手架、缺数据引导、Step 5 平台对话确认凭据、审阅引导。用户视角全中文，不暴露 CLI 名称。
+
+> 钻探前置：v2 顶层（schemaVersion + scenario + menuPath + requiredSystems + requiredRoles + coveredActions + uncoveredCandidates）由 CLI 一次写入。scenario 3 档决策（REQ-SCENE-01）：①CLI `--scenario` ②ModuleHints 推断 ③默认 `crud`；scenario 作为**产物**（非输入）写入顶层。
+
+## 1. 自然语言映射
+
+```text
+/glue-generate-testcase /abs/path/.../014-测试需求10-20260622/code_list.md          # 绝对路径
+/glue-generate-testcase ../knowledge-project/.../014-测试需求10-20260622/code_list.md  # 相对路径
+/glue-generate-testcase                                                             # 无参数 → 问 code_list.md 路径
+/glue-generate-testcase /abs/path/.../014-测试需求10-20260622/code_list.md --debug   # 调试模式 → 跑本地 ep-stage-skill dist
+```
+
+> **`--debug` flag**：正常调用走远程 `npx @epoint-testtech/ep-stage-skill@latest`。开发期想测试未发布的本地代码时传 `--debug`，skill 在 Step 4 改用 `node <repo>/packages/ep-stage-skill/dist/src/cli/index.js`。前提：cwd 在 ep-stage monorepo 内（向上能找到 `pnpm-workspace.yaml`）；找不到时直接 exit 1 报错，不静默 fallback 到 npx。
+
+`--hints` 仅保留为 CLI 开发调试覆盖参数，skill 正常路径不得要求用户提供。
+
+skill 把 `code_list.md` 入参 `path.resolve` 绝对化，用其父目录 basename 取「需求名」作为 `<projectDir>/src/tests/<需求名>` 子目录。**projectDir 不接受参数**，全部从 `~/.ep-stage/projects.index.json5` 反查最新 `mode: 'glue'` 条目（多条 AskUserQuestion 让用户挑）；索引缺失走引导场景 A。
+
+## 2. Agent 执行剧本（8 步任务清单协议）
+
+**任务清单协议（REQ-UX-01）**：load 后**立即**打印初始任务清单（Step 0）；每完成一步输出单行 `✅ 第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`；Step 8 输出全勾选终态清单 + 摘要。
+
+### Step 0 — 打印任务清单
+
+```markdown
+📋 **生成胶水测试用例任务清单**
+
+- [ ] 第 1 步 — 解析 code_list 路径
+- [ ] 第 2 步 — 反查项目脚手架
+- [ ] 第 3 步 — 校验 code_list.md 输入
+- [ ] 第 4 步 — 调用钻探与用例生成 CLI
+- [ ] 第 5 步 — 与研发人员交互确认推断结果
+- [ ] 第 6 步 — 校验产物完整性 + AI 渲染表格化 testcase.md
+- [ ] 第 7 步 — 写入需求条目到项目索引
+- [ ] 第 8 步 — 输出审阅引导摘要
+```
+
+### Step 1 — 解析 code_list 路径
+
+从用户消息 / args 抽取 `code_list.md` 路径，绝对化后得到 `codeListPath`，再用其父目录 basename 作为需求名。中文复述识别结果："已识别：code_list.md = `<abs>`，需求名 = `<basename>`"。入参缺失 → free text 询问"请给我 code_list.md 的绝对或相对路径"。
+
+### Step 2 — 反查项目脚手架（缺 → 引导 A）
+
+读 `~/.ep-stage/projects.index.json5`：文件不存在 / 无 glue 条目 → **引导场景 A**：中文提示"未发现胶水测试脚手架。请先跑 `/glue-create-project <项目名>` 创建脚手架后再回来"，退出不调 CLI。多条匹配 → AskUserQuestion 挑 projectDir。单条 → 直接拼 `--tests-dir` 根。
+
+### Step 3 — 校验 code_list.md 输入（缺 → 引导 D）
+
+校验 `codeListPath` 是否存在，且 `code_list.md` 内至少给出：
+- `knowledgeRoot: /abs/path`，或
+- `> 整理目录：\`/abs/path\``
+
+其余物料路径默认视为相对该根目录的路径；若某项缺失或不存在，再进入交互补齐。`codeListPath` 本身缺失 → **引导场景 D**，AskUserQuestion 三选一：
+
+1. **提供 code_list.md 路径**：让用户给绝对路径，skill 改用该路径继续。
+2. **读 PRD 草稿生成 code_list.md**：在需求目录找 PRD / spec.yaml，AI 推断 `knowledgeRoot` / `menu` / 文件清单写一份 code_list.md 草稿，提示"已生成草稿，请人审后再跑"，退出。
+3. **取消**：直接退出，不调 CLI。
+
+### Step 4 — 调用钻探与用例生成 CLI
+
+固定流程（不 which、不扫 monorepo、不 cd、**不喂 stdin**）。
+
+**正常模式**（用户 args 无 `--debug`）：
+
+```bash
+npx -y @epoint-testtech/ep-stage-skill@latest testcase \
+  --code-list <codeListPath> \
+  --tests-dir <projectDir>/src/tests/<需求名> \
+  --requirement-dir <codeListPath 的父目录> \
+  --project-dir <projectDir> \
+  [--scenario <值>]
+```
+
+**调试模式**（用户 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（需 cwd 在 ep-stage 仓库内向上能找到 pnpm-workspace.yaml + packages/ep-stage-skill/dist/src/cli/index.js）"; exit 1; }
+echo "▸ 调试模式：本地 $REPO/packages/ep-stage-skill/dist/src/cli/index.js"
+node "$REPO/packages/ep-stage-skill/dist/src/cli/index.js" testcase \
+  --code-list <codeListPath> \
+  --tests-dir <projectDir>/src/tests/<需求名> \
+  --requirement-dir <codeListPath 的父目录> \
+  --project-dir <projectDir> \
+  [--scenario <值>]
+```
+
+CLI 内部：先按 scenario 3 档决策（①`--scenario` ②ModuleHints ③默认 `crud`），按 scenario 选 extractor → 物料解析 + contract 提取 + coverage 分析 → 装配 testcase v2（最终 scenario 写入 `testcase.json5` 顶层）→ 写 testcase.json5 / testcase.md（i18n 中文）/ credentials.template.json5 / `.ep-stage/contract.json` / `.ep-stage/inference-trace.json` → 软链上游 code_list.md。CLI 非 0 退出 → 复述 stderr，不发完成提示，不进 Step 5。
+
+### Step 5 — 与研发人员交互确认推断结果（REQ-UX-02）
+
+Step 4 成功后，skill 读 testcase.json5 顶层 `requiredSystems[]` / `requiredRoles[]`，再读 `~/.ep-stage/projects.index.json5` 的 `systems[]` 算 `cachedSystemsHit`（url 命中的列表）。用**平台对话能力**（Claude Code 用 `AskUserQuestion` / Codex 用对应交互机制）跟用户对话：
+
+> 推断出 **N 个系统** + **M 个角色**（如 建设单位 / 施工单位 / 监理单位）。请选择：
+> 1. **现在交互输入**（推荐：≤3 角色场景）— 我逐个角色问 URL / 用户名 / 密码 / systemName，**直接写 `credentials.json5`**
+> 2. **仅生成 template，自己后续填** — 退出后请拷贝 `credentials.template.json5` → `credentials.json5` 并填值
+> 3. **跳过，使用全局 systems[] 缓存复用** — 自动从 `cachedSystemsHit` 命中缓存生成 `credentials.json5`（缺失角色 fallback 引导 C，留给 glue-run-test）
+
+三分支处理：
+
+- **选 1**：skill 顺序问每条角色的 URL/username/password/systemName（free text），直接写 `<需求名>/credentials.json5`（gitignore，非 template），**回写**全局 `~/.ep-stage/projects.index.json5` 的 `systems[].credentialsCache`（按 url 归并，跨需求复用）。
+- **选 2**：保留 template；提示"请编辑 `credentials.json5` 后再跑 `/glue-run-test`"，进入 Step 6。
+- **选 3**：从 `systems[].credentialsCache` 拼出 credentials.json5，缺失角色用 template 占位符保留。
+
+### Step 6 — 校验产物完整性 + AI 渲染审阅视图 testcase.md
+
+**Step 6.1 — 校验产物完整性**
+
+按 §3 验证清单 `ls` / `Read` 校验 CLI 产物存在（除 `testcase.md` 外其他全部，缺任意一项视为整体失败，按 §4 报告）：
+
+- `testcase.json5`、`credentials.template.json5`（或 `credentials.json5`）、`code_list.md` 软链、`.ep-stage/contract.json`、`.ep-stage/inference-trace.json`
+
+> 注意：CLI 当前会先产一份 bullet 格式的 `testcase.md`（来自 `renderTestcaseMarkdown`）；本 Step 6.2 会**覆盖**它为表格化审阅视图。先校验该 CLI 产物存在即可，不审格式。
+
+**Step 6.2 — AI 基于 tpl 渲染表格化 testcase.md（核心人审视图）**
+
+1. **读三个数据源（全部 `Read`，绝不修改其内容）**：
+   - `<testsDir>/testcase.json5`：事实源 — cases 数量 / `caseId` / `title` / `reviewStatus` / `requiredRole` / 顶层 `schemaVersion` / `scenario` / `moduleId` / `moduleName` / `menuPath` / `requiredRoles` 必须**逐字取自此**。
+   - `<testsDir>/.ep-stage/contract.json`：业务槽位 — 步骤/断言/前置条件中的具体标签（菜单 / 列表页 / 按钮文字 / 查询字段 / 删除策略）必须**逐字取自此**对应路径（`contract.pages.list.title` / `contract.flows.create.entryButton.label` 等）。
+   - `<testsDir>/credentials.json5`（如不存在则用 `credentials.template.json5`）：登录地址 / 账号；密码**不写入** testcase.md。
+
+2. **读 tpl**：`packages/ep-stage-skill/codex-skill/ep-stage/glue-generate-testcase/references/testcase-tpl.md`（本 skill 的同级 `references/testcase-tpl.md`，按 frontmatter + 环境信息 section + 5 列 CRUD 表格 + 审阅引导组装；模板内 `<!-- ... -->` 注释含详细填充规则，AI 必须读完后再渲染）。
+
+3. **按 tpl 填充，写盘到 `<testsDir>/testcase.md`（覆盖 CLI 那份 bullet 版本）**：
+   - frontmatter 4 字段（schemaVersion / scenario / moduleId / contractVersion）逐字取数据源
+   - 「环境信息」section：登录地址/账号从 credentials；菜单/列表页/查询字段/操作角色/未解析槽位从 testcase.json5 + contract.json
+   - 「CRUD 冒烟用例」表格：cases[] **一条 = 一行**（数量必须严格等于 `testcase.json5.cases.length`，不得增删），按 caseId 后缀（.create / .read / .update / .delete）走 tpl 内注释列出的步骤/断言/前置条件填充规则；非 CRUD 用例按 cases[].businessIntent / assertionExpectation 直译，缺时填「待人工补充」、不发挥
+   - 表格中**不展示 evidence 列**（人审不需要技术性溯源）
+   - 「审阅引导」section：原样复制 tpl 末尾的 3 条引导（替换其中引用的具体路径）
+
+4. **AI 忠实性自检（写盘前必做）**：
+   - testcase.md 表格行数 - 1 (表头) == testcase.json5 cases.length
+   - 每行 `用例 ID` 列 == testcase.json5 cases[i].caseId
+   - 每行 `标题` 列 == testcase.json5 cases[i].title
+   - 步骤/断言/前置条件中所有「{contract.xxx}」型槽位标签真实存在于 contract.json（grep 验证）
+   - **任一项不通过**：不写盘，按 §4 报告「忠实性自检失败」+ 具体差异 + 停 Step 6.2，不进 Step 7
+
+5. **重跑覆盖语义**：每次跑 skill 都重新执行 Step 6.2，testcase.md 完全覆盖前一次产物；人审意见**只写进 testcase.json5**（JSON5 `// 注释`），**不写 testcase.md**。
+
+**Step 6.3 — 复核环境信息可执行性（可选）**
+
+如 Step 5 已交互写入 credentials.json5：环境信息 section 的「登录地址」应是真实 URL（非占位 `<请填登录页 URL>`）。占位状态下完成提示中提醒用户补 credentials.json5 后再跑 `/glue-run-test`。
+
+### Step 7 — 写入需求条目到项目索引
+
+CLI testcase 子命令在传入 `--project-dir` 时，自动往 `~/.ep-stage/projects.index.json5` 对应 `projects[].requirements[]` 追加本需求条目（含 `name / requirementDir / testsDir / lastRunStatus: "never"`，同名需求去重更新）；未传 `--project-dir` 则跳过（不维护 index）。skill Step 4 命令总带 `--project-dir`，故正常流程 CLI 必追加。skill 校验：条目存在；`name` 与 Step 1 一致；`testsDir` 指向 `<projectDir>/src/tests/<需求名>`。
+
+### Step 8 — 输出审阅引导摘要
+
+打印全勾选终态清单 + §5 完成提示（含审阅引导链：审 testcase.md → 编辑 testcase.json5 → 填 credentials.json5 → 跑 `/glue-run-test`）。
+
+## 3. 验证清单
+
+| 路径                                                         | 说明                                                   |
+|--------------------------------------------------------------|--------------------------------------------------------|
+| `<projectDir>/src/tests/<需求名>/testcase.json5`             | v2 schema（含 scenario / menuPath / requiredSystems 等），**事实源** |
+| `<projectDir>/src/tests/<需求名>/testcase.md`                | **AI 基于 `references/testcase-tpl.md` 渲染的审阅视图**（5 列表格 + 环境信息 + 审阅引导，重跑覆盖；CLI 先产 bullet 版，Step 6.2 覆盖之） |
+| `<projectDir>/src/tests/<需求名>/credentials.template.json5` | 行数 = `requiredRoles.length`                          |
+| `<projectDir>/src/tests/<需求名>/code_list.md`               | 软链 / hardlink / copy 到上游                          |
+| `<projectDir>/src/tests/<需求名>/.ep-stage/contract.json`    | 内部产物，机器专用，禁手编                               |
+| `<projectDir>/src/tests/<需求名>/.ep-stage/inference-trace.json` | 推理追踪总账，只供排查和审阅，不作为 spec 主输入     |
+| `~/.ep-stage/projects.index.json5`                           | 已追加 `projects[].requirements[]`                     |
+
+> 常态不生成 `source-spec.json` 或 `module-hints.inferred.json5`；二者只作为显式调试导出，非正常产物。
+
+## 4. 错误处理
+
+| 触发时机                                | Agent 中文呈现 + 建议                                                |
+|-----------------------------------------|----------------------------------------------------------------------|
+| 引导 A（缺脚手架）                        | 中文提示+退出，引导先跑 `/glue-create-project`                        |
+| 引导 D（缺 code_list.md）                 | AskUserQuestion 三选一：建软链 / 读 PRD 草稿 / 取消                   |
+| CLI exit ≠ 0                            | 复述 stderr 中文转述，不发完成提示，不进 Step 5                        |
+| testcase.json5 缺 `schemaVersion: "v2"` | 报"产物 schema 校验失败，请重跑 `/glue-generate-testcase <code_list.md路径>`" |
+| Step 5 选 1 用户中途取消                | 保留 template，提示"凭据未写入，请稍后拷贝 template 自填"              |
+| Step 6.2 忠实性自检失败                 | 不写 testcase.md，复述差异（行数不匹配 / caseId 错位 / 槽位标签 contract 中不存在），引导审阅 testcase.json5 与 contract.json 后重跑 |
+
+## 5. 完成提示
+
+Step 8 全部通过后，按以下中文格式呈现（不要用 success/done/generated）：
+
+> ✅ 用例生成完成
+>
+> 需求：`<需求名>`
+> 项目：`<projectDir>`
+> 产物目录：`<projectDir>/src/tests/<需求名>/`（testcase.json5 v2 + testcase.md + credentials.template.json5 + credentials.json5（如选 1/3）+ code_list.md 软链 + .ep-stage/contract.json + .ep-stage/inference-trace.json）
+> 项目索引：`~/.ep-stage/projects.index.json5` 已追加需求条目
+>
+> 下一步审阅引导链：
+> 1. 打开 `testcase.md` 审阅推断结果与未确认项
+> 2. 如需调整，编辑 `testcase.json5`（JSON5 支持 `// 注释`，审阅意见可直接写注释）
+> 3. 检查 / 填好 `credentials.json5`（如未在 Step 5 选 1/3 写入）
+> 4. 跑 `/glue-run-test <需求目录路径>` 组装并执行 spec
+
+## 6. 引导场景
+
+- **A（缺脚手架）**：Step 2 反查 projects.index.json5 无 glue 条目 → 提示先跑 `/glue-create-project` 退出。
+- **D（缺 code_list.md）**：Step 3 缺失 → AskUserQuestion 三选一（建软链 / 读 PRD 草稿 / 取消）。
+- **B / C**：由下游 `glue-run-test` 处理。
+
+## 7. 输入字段约定
+
+```markdown
+<!-- code_list.md 字段约定（REQ-FILE-02 / REQ-MENU-01） -->
+knowledgeRoot: /abs/path/to/knowledge-project/xxx   <!-- 推荐：结构化根目录 -->
+
+> 整理目录：`/abs/path/to/knowledge-project/xxx`   <!-- 兼容旧格式；其余相对路径默认相对该目录 -->
+> 菜单：一级菜单>二级菜单   <!-- 人工读写首选：中文键「菜单」，与「整理目录」同风格；可选，缺时引导补，最终写入 testcase.json5.menuPath -->
+menu: 一级菜单>二级菜单   <!-- 英文键兼容：裸行 menu / menuPath 仍可解析（blockquote「>」形式仅认「菜单」）。CLI 内部字段名仍为 menu -->
+
+`_docs/.../spec.yaml`
+`src/main/webapp/.../*.html`
+`src/main/java/.../*Action.java`
+
+<!-- module-hints 是 CLI 基于上游物料推理的过程产物（落入 .ep-stage/inference-trace.json），
+     不是 code_list 该列的输入物料；旧 examples/zwplace.module-hints.json 仅作历史 fixture（REQ-INFER-010）。 -->
+```
+
+## 8. 内嵌数据契约范例
+
+`<需求名>/testcase.json5` v2 顶层骨架（详见 references/testcase-schema.md）：
+
+```json5
+{
+  schemaVersion: "v2",
+  scenario: "crud",                            // 产物：CLI 3 档决策后写入
+  moduleId: "zwplace", moduleName: "场所窗口信息管理",
+  menuPath: "场所窗口信息管理>场所窗口信息列表",
+  requiredSystems: [{ url: "http://...", systemName: "主业务系统" }],
+  requiredRoles:   [{ role: "admin", hint: "默认操作员" }],
+  coveredActions:  [{ actionId: "zwplace.create", kind: "create", evidence: ["html=...", "java=..."] }],
+  uncoveredCandidates: [{ actionId: "zwplace.sync", status: "planned", requiredRole: "admin", businessIntent: "...", assertionExpectation: "...", evidence: ["..."] }],
+  cases: [{ caseId: "zwplace.create", title: "新增", scenario: "crud.single-page", reviewStatus: "confirmed", requiredRole: "admin", evidence: ["..."], steps: [], assertions: [], unresolved: [] }],
+  reasoningSummary: { conclusion: "...", evidenceChain: [], alternatives: [], confidence: "high", risks: [], needsHumanReview: false }
+}
+```
+
+`<需求名>/credentials.template.json5`（行数 = `requiredRoles.length`） + `~/.ep-stage/projects.index.json5` 需求条目（CLI 追加到 `projects[].requirements[]`）：
+
+```json5
+// credentials.template.json5
+[ { url: "<请填登录页 URL>", username: "<请填>", password: "<请填>", role: "admin", systemName: "主业务系统" } ]
+
+// projects.index.json5 → projects[].requirements[<i>]
+{ name: "014-测试需求10-20260622", requirementDir: "/abs/.../014-测试需求10-20260622", testsDir: "<projectDir>/src/tests/014-测试需求10-20260622", lastRunStatus: "never" }
+```
+
+## 9. 按需加载
+
+- 用例 schema 详解：`references/testcase-schema.md`（v2）
+- **testcase.md 渲染模板：`references/testcase-tpl.md`（Step 6.2 必读）**
+- 既有工作流参考：`references/workflow.md`
+
+## 10. 关键约束
+
+- 顶层 `reviewStatus` 字段**永远不引入**（REQ-DATA-04）；审阅意见请直接在 `testcase.json5` 加 JSON5 `// 注释`。
+- `cases[].reviewStatus = needs_review` 的用例不得进入 spec 组装（spec 组装阶段按 case 粒度阻断）。
+- 嵌套 CRUD 一期仅作为候选用例进入 testcase，不写入正式 CRUD 契约。
+- testcase.md 每次重跑完全覆盖，不保留人工编辑（事实源是 testcase.json5）。**testcase.md 由 skill Step 6.2 基于 `references/testcase-tpl.md` AI 渲染**（CLI 当前先产一份 bullet 版作为兜底，Step 6.2 覆盖之）；步骤/断言/前置条件中的具体槽位标签必须逐字取自 contract.json，AI 只组织自然语言句式，不得新增/捏造槽位。
+- 对话中展示可审阅推理摘要和证据链，不展示原始隐式思维链。

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

@@ -0,0 +1,112 @@
+# glue-testcase schema (v2)
+
+`testcase.json5` 顶层 schema：
+
+```json5
+{
+  schemaVersion: "v2",
+  scenario: "crud",                  // ★ v2 新增（REQ-SCENE-01）：场景类型。**由 testcase 子命令运行时决定后写入此字段**（产物，非输入）。决策优先级：①--scenario CLI 参数 ②ModuleHints 推断 ③默认 "crud"
+  moduleId: "zwplace",
+  moduleName: "场所窗口信息管理",
+  menuPath: "场所窗口信息管理>场所窗口信息列表",  // ★ v2 新增（REQ-MENU-01）：从 code_list.md 搬到 testcase 扎口
+
+  // ★ v2 新增：上游推断的需求系统/角色集
+  requiredSystems: [
+    { url: "http://192.168.x.x:8100/.../login", systemName: "主业务系统" }
+  ],
+  requiredRoles: [
+    { role: "admin", hint: "默认操作员" }
+  ],
+
+  // ★ v2 新增：骨架命中清单（run 阶段直接组装）
+  // evidence 格式约定：<kind>=<ref>，kind ∈ {html, java, spec, contract, skeleton, hint}
+  coveredActions: [
+    {
+      actionId: "zwplace.create",
+      kind: "create",
+      evidence: [
+        "html=src/main/webapp/.../gxhzwplaceadd.html",
+        "java=src/main/java/.../ZwplaceAction.java"
+      ]
+    },
+    { actionId: "zwplace.read",   kind: "read",   evidence: ["html=src/main/webapp/.../gxhzwplacelist.html", "java=..."] },
+    { actionId: "zwplace.update", kind: "update", evidence: ["html=...", "java=..."] },
+    { actionId: "zwplace.delete", kind: "delete", evidence: ["html=...", "java=..."] }
+  ],
+
+  // ★ v2 新增：骨架未命中候选（run 阶段 AI 推理）
+  uncoveredCandidates: [
+    {
+      actionId: "zwplace.sync",
+      label: "同步窗口管理系统",
+      status: "planned",            // planned | candidate | unresolved | resolved
+      requiredRole: "admin",        // ★ v2 新增：AI 推理时知道用哪个角色操作
+      businessIntent: "同步窗口数据",
+      assertionExpectation: "同步完成提示",
+      evidence: ["html=...", "hint=ModuleHints.customWorkflows.zwplace.sync"]
+    }
+  ],
+
+  // 既有 v1 字段（cases 内部行为不变）
+  cases: [
+    {
+      caseId: "zwplace.create",
+      title: "新增场所窗口信息管理",
+      scenario: "crud.single-page",
+      reviewStatus: "confirmed",    // v1 字段保留：confirmed | needs_review | blocked
+      requiredRole: "admin",        // ★ v2 新增：该用例由哪个角色操作
+      evidence: ["skeleton=crud.skeleton-testcase/v1", "contract=crud-business-module/v1"],
+      steps: ["进入菜单", "点击新增", "填写并保存测试数据"],
+      assertions: ["新增后可查询到记录"],
+      unresolved: []
+    }
+  ],
+
+  reasoningSummary: {
+    conclusion: "生成 4 条 CRUD 胶水测试用例。",
+    evidenceChain: [],
+    alternatives: ["crud.single-page"],
+    confidence: "high",
+    risks: [],
+    needsHumanReview: false
+  }
+}
+```
+
+## v1 → v2 升级点
+
+- 顶层新增 `schemaVersion: "v2"`
+- 顶层新增 `scenario`（REQ-SCENE-01）
+- 顶层新增 `menuPath`（REQ-MENU-01 修订）
+- 顶层新增 `requiredSystems[]` / `requiredRoles[]`
+- 顶层新增 `coveredActions[]` / `uncoveredCandidates[]`（钻探产物前移）
+- `cases[]` 新增 `requiredRole`
+- `uncoveredCandidates[]` 新增 `requiredRole`
+- `evidence` 字段格式约定 `<kind>=<ref>`
+- **顶层不引入** `reviewStatus`（REQ-DATA-04）；仅 `cases[].reviewStatus` 保留
+
+## 字段说明（v2 新增字段）
+
+- `schemaVersion`：必为字符串 `"v2"`。Task 1.1 `validateTestcase` 强制校验；其他值或缺失会拒绝并提示重跑 `glue-generate-testcase`。
+- `scenario`：场景类型（**产物**，非输入）。由 testcase 子命令运行时按 3 档优先级决定：① CLI `--scenario` 显式参数 → ② 从 `ModuleHints` 推断 → ③ 默认 `"crud"`。本轮仅支持 `"crud"`；未来 `"statistic"` / `"approval"` 等场景扩展时不增加新 CLI 命令，仅扩展 testcase 内部分发（REQ-SCENE-01）。
+- `menuPath`：菜单路径，从 `code_list.md` 搬到 testcase 扎口（REQ-MENU-01 修订）。glue-run-test 的 spec 子命令从此读取，不再从 code_list 二次解析。
+- `requiredSystems[]`：上游钻探推断的需求涉及的系统集，每项 `{ url, systemName? }`。驱动 `credentials.template.json5` 生成 + 引导用户在 glue-generate-testcase 第 5 步交互确认（REQ-UX-02）。
+- `requiredRoles[]`：上游钻探推断的需求涉及的角色集，每项 `{ role, hint? }`。同上驱动 template + 确认。
+- `coveredActions[]`：骨架命中清单。run 阶段直接组装胶水部分 spec，按 `evidence` 引用源码与契约。
+- `uncoveredCandidates[]`：骨架未命中候选；`status` 取 `planned`（可进 AI 推理）/ `candidate`（不得进 spec，要求补 hints）/ `unresolved`（缺证据）/ `resolved`（已通过推理）。
+- `uncoveredCandidates[].requiredRole`：AI 推理时该动作由哪个角色操作（多角色场景必需）。
+- `cases[].requiredRole`：该用例由哪个角色操作。spec 子命令据此映射 credentials.json5 + cases 登录切换。
+- `evidence`：字符串数组，每项格式 `<kind>=<ref>`。`kind` ∈ `{html, java, spec, contract, skeleton, hint}`。
+
+## 既有 v1 字段说明（保留语义）
+
+- `cases[].reviewStatus`：`confirmed` / `needs_review` / `blocked`。`needs_review` 的用例不得进入 spec assembly（run 阶段按 case 粒度阻断）。
+- `caseId`：spec assembly 需要与生成脚本工作流粒度一致。CRUD 用例固定为 `<moduleId>.create` / `.read` / `.update` / `.delete`。
+- `unresolved`：未确认项（如嵌套 CRUD 子表保存后断言）。必须落盘，不能只在对话解释。
+- `reasoningSummary`：与 `.stage/trace/<run-id>/testcase-generation.json` 同构。
+
+## Schema 演化策略
+
+- 破坏性升级走 major 版本号（如 v2 → v3）
+- CLI 读取时校验 `schemaVersion`：不匹配抛结构化错误（含期望版本 + 修复建议「重跑 `glue-generate-testcase <需求路径>`」）
+- 顶层 `reviewStatus` 字段**永远不引入**（REQ-DATA-04）；审阅意见请直接在 `testcase.json5` 加 JSON5 `// 注释`