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

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

@@ -1,7 +1,7 @@
 ---
 name: glue-create-project
 description: 使用时机：当用户表达「创建胶水项目 / 测试脚手架 / 新建 glue 项目」或显式触发 `/glue-create-project [名称或路径]` 时使用。本 skill 只创建胶水模式（glue）Playwright 测试脚手架，不收集登录信息，不写 .env / stage-context.md。
-version: 2026-06-25+562b629
+version: 2026-06-25+6e9e357
 argument-hint: "<脚手架项目名或脚手架项目路径>"
 ---
 
@@ -20,8 +20,11 @@ argument-hint: "<脚手架项目名或脚手架项目路径>"
 /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）：
@@ -88,12 +91,29 @@ Agent 在调用 CLI 前必须：跑 `pwd` → 按 §1.1 算最终落点 → 中
 
 ### Step 3 — 调用脚手架 CLI
 
-固定命令形式（不 which、不扫 monorepo、不 cd 进项目、**不喂 stdin**）。`<targetPath>` 由 §1.1 算出：
+固定流程（不 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 — 验证脚手架产物

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

@@ -1,25 +1,30 @@
 ---
 name: glue-generate-testcase
-description: 使用时机：当用户对某需求要「生成用例 / 准备测试场景 / 钻探上游需求生成胶水冒烟用例」或显式触发 `/glue-generate-testcase <需求目录>` 时使用。本 skill 包装 `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，并负责自然语言映射、缺数据引导、Step 5 凭据交互确认。
-version: 2026-06-25+5179a92
-argument-hint: "<需求目录绝对/相对路径>"
+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 负责：路径解析、反查项目脚手架、缺数据引导、Step 5 平台对话确认凭据、审阅引导。用户视角全中文，不暴露 CLI 名称。
+本 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   # 绝对路径
-/glue-generate-testcase ../knowledge-project/.../014-测试需求10-20260622  # 相对路径
-/glue-generate-testcase                                          # 无参数 → 问需求目录
+/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
 ```
 
-skill 把入参 `path.resolve` 绝对化，用 `path.basename` 取「需求名」作为 `<projectDir>/src/tests/<需求名>` 子目录。**projectDir 不接受参数**，全部从 `~/.ep-stage/projects.index.json5` 反查最新 `mode: 'glue'` 条目（多条 AskUserQuestion 让用户挑）；索引缺失走引导场景 A。
+> **`--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 步任务清单协议）
 
@@ -30,19 +35,19 @@ skill 把入参 `path.resolve` 绝对化，用 `path.basename` 取「需求名
 ```markdown
 📋 **生成胶水测试用例任务清单**
 
-- [ ] 第 1 步 — 解析需求路径
+- [ ] 第 1 步 — 解析 code_list 路径
 - [ ] 第 2 步 — 反查项目脚手架
 - [ ] 第 3 步 — 校验 code_list.md 输入
 - [ ] 第 4 步 — 调用钻探与用例生成 CLI
 - [ ] 第 5 步 — 与研发人员交互确认推断结果
-- [ ] 第 6 步 — 校验产物完整性
+- [ ] 第 6 步 — 校验产物完整性 + AI 渲染表格化 testcase.md
 - [ ] 第 7 步 — 写入需求条目到项目索引
 - [ ] 第 8 步 — 输出审阅引导摘要
 ```
 
-### Step 1 — 解析需求路径
+### Step 1 — 解析 code_list 路径
 
-从用户消息 / args 抽取需求目录路径，绝对化 + basename。中文复述识别结果："已识别：需求目录 = `<abs>`，需求名 = `<basename>`"。入参缺失 → free text 询问"请给我需求目录的绝对或相对路径"。
+从用户消息 / args 抽取 `code_list.md` 路径，绝对化后得到 `codeListPath`，再用其父目录 basename 作为需求名。中文复述识别结果："已识别：code_list.md = `<abs>`，需求名 = `<basename>`"。入参缺失 → free text 询问"请给我 code_list.md 的绝对或相对路径"。
 
 ### Step 2 — 反查项目脚手架（缺 → 引导 A）
 
@@ -50,27 +55,52 @@ skill 把入参 `path.resolve` 绝对化，用 `path.basename` 取「需求名
 
 ### Step 3 — 校验 code_list.md 输入（缺 → 引导 D）
 
-校验 `<需求目录>/code_list.md` 是否存在。缺失 → **引导场景 D**，AskUserQuestion 三选一：
+校验 `codeListPath` 是否存在，且 `code_list.md` 内至少给出：
+- `knowledgeRoot: /abs/path`，或
+- `> 整理目录：\`/abs/path\``
+
+其余物料路径默认视为相对该根目录的路径；若某项缺失或不存在，再进入交互补齐。`codeListPath` 本身缺失 → **引导场景 D**，AskUserQuestion 三选一：
 
-1. **提供 code_list.md 路径**：让用户给绝对路径，skill 用跨平台 softlink fallback（symlink → hardlink → copy + 时间戳警示）建到需求目录。
+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**）：
+固定流程（不 which、不扫 monorepo、不 cd、**不喂 stdin**）。
+
+**正常模式**（用户 args 无 `--debug`）：
 
 ```bash
 npx -y @epoint-testtech/ep-stage-skill@latest testcase \
-  --code-list <需求目录>/code_list.md \
+  --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 <需求目录> \
+  --requirement-dir <codeListPath 的父目录> \
   --project-dir <projectDir> \
-  [--scenario <值>] \
-  [--hints <module-hints.json 路径>]
+  [--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` → 软链上游 code_list.md。CLI 非 0 退出 → 复述 stderr，不发完成提示，不进 Step 5。
+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）
 
@@ -87,13 +117,48 @@ Step 4 成功后，skill 读 testcase.json5 顶层 `requiredSystems[]` / `requir
 - **选 2**：保留 template；提示"请编辑 `credentials.json5` 后再跑 `/glue-run-test`"，进入 Step 6。
 - **选 3**：从 `systems[].credentialsCache` 拼出 credentials.json5，缺失角色用 template 占位符保留。
 
-### Step 6 — 校验产物完整性
+### Step 6 — 校验产物完整性 + AI 渲染审阅视图 testcase.md
+
+**Step 6.1 — 校验产物完整性**
+
+按 §3 验证清单 `ls` / `Read` 校验 CLI 产物存在（除 `testcase.md` 外其他全部，缺任意一项视为整体失败，按 §4 报告）：
 
-按 §3 验证清单 `ls` / `Read` 校验全部产物存在。缺任意一项视为整体失败，按 §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 子命令已在 `~/.ep-stage/projects.index.json5` 对应 `projects[].requirements[]` 追加本需求条目（含 `name / requirementDir / testsDir / lastRunStatus: "never"`）。skill 校验：条目存在；`name` 与 Step 1 一致；`testsDir` 指向 `<projectDir>/src/tests/<需求名>`。缺时由 skill 补写。
+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 — 输出审阅引导摘要
 
@@ -101,24 +166,28 @@ CLI testcase 子命令已在 `~/.ep-stage/projects.index.json5` 对应 `projects
 
 ## 3. 验证清单
 
-| 路径                                                  | 说明                          |
-|-------------------------------------------------------|-------------------------------|
-| `<projectDir>/src/tests/<需求名>/testcase.json5`      | v2 schema（含 scenario / menuPath / requiredSystems 等）|
-| `<projectDir>/src/tests/<需求名>/testcase.md`         | 中文人审视图（i18n 映射）     |
-| `<projectDir>/src/tests/<需求名>/credentials.template.json5` | 行数 = `requiredRoles.length` |
-| `<projectDir>/src/tests/<需求名>/code_list.md`        | 软链 / hardlink / copy 到上游 |
-| `<projectDir>/src/tests/<需求名>/.ep-stage/contract.json` | 内部产物，机器专用，禁手编 |
-| `~/.ep-stage/projects.index.json5`                    | 已追加 `projects[].requirements[]` |
+| 路径                                                         | 说明                                                   |
+|--------------------------------------------------------------|--------------------------------------------------------|
+| `<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 <需求路径>`" |
-| Step 5 选 1 用户中途取消  | 保留 template，提示"凭据未写入，请稍后拷贝 template 自填" |
+| 触发时机                                | 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. 完成提示
 
@@ -128,7 +197,7 @@ Step 8 全部通过后，按以下中文格式呈现（不要用 success/done/ge
 >
 > 需求：`<需求名>`
 > 项目：`<projectDir>`
-> 产物目录：`<projectDir>/src/tests/<需求名>/`（testcase.json5 v2 + testcase.md + credentials.template.json5 + credentials.json5（如选 1/3）+ code_list.md 软链）
+> 产物目录：`<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` 已追加需求条目
 >
 > 下一步审阅引导链：
@@ -147,13 +216,18 @@ Step 8 全部通过后，按以下中文格式呈现（不要用 success/done/ge
 
 ```markdown
 <!-- code_list.md 字段约定（REQ-FILE-02 / REQ-MENU-01） -->
-knowledgeRoot: /abs/path/to/knowledge-project/xxx
-menu: 一级菜单>二级菜单   <!-- 可选；缺时引导补，最终写入 testcase.json5.menuPath -->
+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`
-`_docs/.../*.module-hints.json`
+
+<!-- module-hints 是 CLI 基于上游物料推理的过程产物（落入 .ep-stage/inference-trace.json），
+     不是 code_list 该列的输入物料；旧 examples/zwplace.module-hints.json 仅作历史 fixture（REQ-INFER-010）。 -->
 ```
 
 ## 8. 内嵌数据契约范例
@@ -188,12 +262,13 @@ menu: 一级菜单>二级菜单   <!-- 可选；缺时引导补，最终写入 t
 ## 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 组装（run 阶段按 case 粒度阻断）。
+- `cases[].reviewStatus = needs_review` 的用例不得进入 spec 组装（spec 组装阶段按 case 粒度阻断）。
 - 嵌套 CRUD 一期仅作为候选用例进入 testcase，不写入正式 CRUD 契约。
-- testcase.md 每次重跑完全覆盖，不保留人工编辑（事实源是 testcase.json5）。
+- 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-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

@@ -1,7 +1,7 @@
 ---
 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
+version: 2026-06-25+6e9e357
 argument-hint: "<需求目录绝对/相对路径>"
 compatibility: 需要由 stage-create 生成的 glue 模式 Playwright 项目 + 已审过的 `<需求名>/testcase.json5` (v2) + 填好的 `<需求名>/credentials.json5`。
 metadata:
@@ -20,11 +20,14 @@ metadata:
 ## 1. 自然语言映射
 
 ```text
-/glue-run-test /abs/path/.../014-测试需求10-20260622   # 绝对路径
+/glue-run-test /abs/path/.../014-测试需求10-20260622          # 绝对路径
 /glue-run-test ../knowledge-project/.../014-测试需求10-20260622  # 相对路径
-/glue-run-test                                        # 无参数 → 问需求目录
+/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 步任务清单协议）
@@ -74,7 +77,9 @@ skill 把入参 `path.resolve` 绝对化，`path.basename` 取「需求名」。
 
 ### Step 4 — 调用 spec 组装 CLI（只生成 v1 不执行）
 
-固定命令形式（不 which、不扫 monorepo、不 cd、**不喂 stdin**）：
+固定流程（不 which、不扫 monorepo、不 cd、**不喂 stdin**）。
+
+**正常模式**（用户 args 无 `--debug`）：
 
 ```bash
 npx -y @epoint-testtech/ep-stage-skill@latest spec \
@@ -82,11 +87,28 @@ npx -y @epoint-testtech/ep-stage-skill@latest spec \
   --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 \
@@ -95,6 +117,24 @@ npx -y @epoint-testtech/ep-stage-skill@latest run \
   --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）。

package/dist/src/cli/generate-testcase.d.ts

@@ -23,6 +23,7 @@ export type GenerateTestcaseResult = {
     testcasePath: string;
     testcaseMdPath: string;
     credentialsTemplatePath: string;
+    inferenceTracePath: string;
     inference: {
         scenario: string;
         requiredSystems: TestcaseV2['requiredSystems'];

package/dist/src/cli/generate-testcase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate-testcase.d.ts","sourceRoot":"","sources":["../../../src/cli/generate-testcase.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,uBAAuB,EAAE,MAAM,CAAC;IAChC,SAAS,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC;QAC/C,aAAa,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;QAC3C,uBAAuB,EAAE,MAAM,CAAC;QAChC,qBAAqB,EAAE,MAAM,CAAC;QAC9B,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAqB9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAOjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAgDnE;AAsBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,sBAAsB,CA+CtF"}
+{"version":3,"file":"generate-testcase.d.ts","sourceRoot":"","sources":["../../../src/cli/generate-testcase.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,uBAAuB,EAAE,MAAM,CAAC;IAChC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE;QACT,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,UAAU,CAAC,iBAAiB,CAAC,CAAC;QAC/C,aAAa,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;QAC3C,uBAAuB,EAAE,MAAM,CAAC;QAChC,qBAAqB,EAAE,MAAM,CAAC;QAC9B,gBAAgB,EAAE,MAAM,EAAE,CAAC;KAC5B,CAAC;CACH,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,oBAAoB,CAqB9E;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAOjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,UAAU,GAAG,MAAM,CAgDnE;AAkID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,oBAAoB,GAAG,sBAAsB,CA+DtF"}