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

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

@@ -1,275 +1,275 @@
----
-name: glue-generate-testcase
-description: 使用时机：当用户对某需求要「生成用例 / 准备测试场景 / 钻探上游需求生成胶水冒烟用例」或显式触发 `/glue-generate-testcase <code_list.json5路径>` 时使用。本 skill 包装 `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，并负责自然语言映射、缺数据引导、Step 5 凭据交互确认。
-version: 2026-08-12+925f4c4
-argument-hint: "<code_list.json5绝对/相对路径>"
----
-
-# ep-stage: glue-generate-testcase
-
-本 skill 引导 Agent **包装** `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，不重新实现钻探与用例生成。CLI 内部完成物料解析 + contract 提取（内嵌）+ coverage 分析 + testcase 装配 + credentials.template 生成。skill 负责：`code_list.json5` 路径解析、反查项目脚手架、缺数据引导、Step 5 平台对话确认凭据、审阅引导。用户视角全中文，不暴露 CLI 名称。
-
-> **契约可观测性 gate**：每个非平凡字段必须能追溯到上游证据、可重复推导规则、运行配置来源或人工确认问题；无法给出来源的字段必须进入 `unresolvedSlots`，禁止写入 `contract.json5`。"无来源不入契约"。
-
-> 钻探前置：testcase.json5 顶层（schemaVersion:'ep-stage-testcase/v1-draft' + testcaseId + contractRef + scenario + moduleId + moduleName + runtimeContext? + testAccess? + cases + uncoveredCandidates）由 CLI 一次写入。scenario 由 CLI 按 `code_list.json5` 推导（assembler），014 默认 `crud_export`；scenario 作为**产物**（非输入）写入顶层。`menuPath` 不是新链路必填字段。`runtimeContext` 用于落定工程与 spec 路径；`testAccess` 只保存 `credentialRef/requiredRoles`，明文账号密码与运行访问数据统一写入 `credentials.json5`。`directUrl` 是待测页面直达地址，不属于上游出码事实；缺失时必须在本 skill 交互补齐，并通过 CLI 参数写入 `contract.json5.base.navigation.directUrl`。**module-hints 已废弃**（交接文档 §4.1），不作为输入。
-
-## 1. 自然语言映射
-
-```text
-/glue-generate-testcase /abs/path/.../014-测试需求10-20260622/_docs/code_list.json5          # 绝对路径
-/glue-generate-testcase ../knowledge-project/.../014-测试需求10-20260622/_docs/code_list.json5  # 相对路径
-/glue-generate-testcase                                                             # 无参数 → 问 code_list.json5 路径
-/glue-generate-testcase /abs/path/.../014-测试需求10-20260622/_docs/code_list.json5 --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。
-
-`--scenario` 不作为正常路径输入（scenario 由 CLI 按 `code_list.json5` 推导，014 默认 `crud_export`）；`--hints` / module-hints 已废弃，不作为输入。
-
-skill 把 `code_list.json5` 入参 `path.resolve` 绝对化，用其父目录的父目录 basename 取「需求名」作为 `<projectDir>/src/tests/<需求名>` 子目录（`_docs/code_list.json5` 上一级即需求目录）。**projectDir 不接受参数**，全部从 `~/.ep-stage/projects.index.json5` 反查最新 `mode: 'glue'` 条目（多条 AskUserQuestion 让用户挑）；索引缺失走引导场景 A。
-
-## 2. Agent 执行剧本（8 步任务清单协议）
-
-**任务清单协议（REQ-UX-01）**：load 后**最先**单行展示技能版本（取本 SKILL.md frontmatter 的 `version` 字段），格式 `技能版本：glue-generate-testcase <version>`；随后**立即**打印初始任务清单（Step 0）；每完成一步输出单行 `第 N 步 — <中文名> 已完成，进入第 N+1 步 — <下一中文名>...`；Step 8 输出全勾选终态清单 + 摘要。
-
-### Step 0 — 打印任务清单
-
-```markdown
-**生成胶水测试用例任务清单**
-
-- [ ] 第 1 步 — 解析 code_list.json5 路径
-- [ ] 第 2 步 — 反查项目脚手架
-- [ ] 第 3 步 — 校验 code_list.json5 输入
-- [ ] 第 4 步 — 补齐待测页面 directUrl 并调用钻探与用例生成 CLI
-- [ ] 第 5 步 — 与研发人员交互确认推断结果
-- [ ] 第 6 步 — 校验产物完整性 + 审阅 testcase.md 单表
-- [ ] 第 7 步 — 写入需求条目到项目索引
-- [ ] 第 8 步 — 输出审阅引导摘要
-```
-
-### Step 1 — 解析 code_list 路径
-
-从用户消息 / args 抽取 `code_list.json5` 路径，绝对化后得到 `codeListPath`，再用其父目录的父目录 basename 作为需求名（`_docs/code_list.json5` 上一级即需求目录）。中文复述识别结果："已识别：code_list.json5 = `<abs>`，需求名 = `<basename>`"。入参缺失 → free text 询问"请给我 code_list.json5 的绝对或相对路径（位于需求目录 `_docs/` 下）"。
-
-### Step 2 — 反查项目脚手架（缺 → 引导 A）
-
-读 `~/.ep-stage/projects.index.json5`：文件不存在 / 无 glue 条目 → **引导场景 A**：中文提示"未发现胶水测试脚手架。请先跑 `/glue-create-project <项目名>` 创建脚手架后再回来"，退出不调 CLI。多条匹配 → AskUserQuestion 挑 projectDir。单条 → 直接拼 `--tests-dir` 根。
-
-### Step 3 — 校验 code_list.json5 输入（缺 → 引导 D）
-
-校验 `codeListPath` 是否存在，且 `code_list.json5` 内至少给出：
-- `knowledgeRoot: /abs/path`，或
-- `> 整理目录：\`/abs/path\``
-
-其余物料路径默认视为相对该根目录的路径；若某项缺失或不存在，再进入交互补齐。`codeListPath` 本身缺失 → **引导场景 D**，AskUserQuestion 三选一：
-
-1. **提供 code_list.json5 路径**：让用户给绝对路径（位于需求目录 `_docs/` 下），skill 改用该路径继续。
-2. **读 PRD 草稿生成 code_list.json5**：在需求目录找 PRD / spec.yaml，AI 推断 `knowledgeRoot` / `menu` / 文件清单写一份 `code_list.json5` 草稿到 `_docs/` 下，提示"已生成草稿，请人审后再跑"，退出。
-3. **取消**：直接退出，不调 CLI。
-
-### Step 4 — 补齐待测页面 directUrl 并调用钻探与用例生成 CLI
-
-固定流程（不 which、不扫 monorepo、不 cd、**不喂 stdin**）。调用 CLI 前先确定待测页面 `directUrl`：
-
-- 若 `code_list.json5` 已有待测页面节点的 `pages[role=list].directUrl`，直接使用。
-- 若缺失，必须用平台对话询问用户："请提供待测页面直达链接（directUrl）。说明：直达链接通常来自浏览器地址栏中 view-source: 后面的页面地址；例如 view-source:http://192.168.203.46:8100/epoint-web/perpage/zwplace/gxhzwplacelist.html，实际填写 http://192.168.203.46:8100/epoint-web/perpage/zwplace/gxhzwplacelist.html。"
-- 仍缺失则停止，不调 CLI。禁止让下游 `glue-run-test` 自行猜入口。
-
-**正常模式**（用户 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> \
-  --direct-url <待测列表页 directUrl>
-```
-
-（scenario 由 CLI 按 `code_list.json5` 推导，014 默认 `crud_export`，正常路径不传 `--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> \
-  --direct-url <待测列表页 directUrl>
-```
-
-（scenario 由 CLI 按 `code_list.json5` 推导，014 默认 `crud_export`，正常路径不传 `--scenario`）
-
-CLI 内部：按 `code_list.json5` 解析物料 → assembler 推导 scenario（014 默认 `crud_export`）→ 装配 contract + testcase（scenario 作为产物写入 `testcase.json5` 顶层，`directUrl` 写入 `contract.json5.base.navigation.directUrl`，`testcase.json5.testAccess` 只写 `credentialRef/requiredRoles`）→ schema 门禁 → 写 testcase.json5 / testcase.md（统一单表审阅视图）/ credentials.template.json5 / `.ep-stage/contract.json5` / `.ep-stage/inference-trace.json`。testcase.md 只渲染一张用例表，列为：用例 ID / 生成策略 / 用例标题 / 查询主键 / 前置条件 / 执行步骤 / 执行断言。glue 与 ai 通过“生成策略”列区分，不拆成两个表。CLI 非 0 退出 → 复述 stderr，不发完成提示，不进 Step 5。
-
-### Step 5 — 与研发人员交互确认推断结果（REQ-UX-02）
-
-Step 4 成功后，skill 读 CLI 产出的 `credentials.template.json5`（行数 = `code_list.roles.length`，每条对应一个角色）+ `uncoveredCandidates[].requiredRole`，再读 `~/.ep-stage/projects.index.json5` 的 `systems[]` 算 `cachedSystemsHit`（url 命中的列表）。用**平台对话能力**（Claude Code 用 `AskUserQuestion` / Codex 用对应交互机制）跟用户对话：
-
-> 推断出 **N 个角色**（如 建设单位 / 施工单位 / 监理单位）。请选择：
-> 1. **现在交互输入**（推荐：≤3 角色场景）— 我逐个角色问直达链接（directUrl）/ 登录地址（loginUrl）/ 系统名称（systemName）/ 角色（role）/ 账号（username）/ 密码（password），汇总摘要请你确认后写 `credentials.json5`
-> 2. **仅生成 template，自己后续填** — 退出后请拷贝 `credentials.template.json5` → `credentials.json5` 并填值
-> 3. **跳过，使用全局 systems[] 缓存复用** — 自动从 `cachedSystemsHit` 命中缓存生成 `credentials.json5`（缺失角色 fallback 引导 C，留给 glue-run-test）
-
-三分支处理：
-
-- **选 1**：skill 顺序问每条角色的直达链接（directUrl）/ 登录地址（loginUrl）/ 系统名称（systemName）/ 角色（role）/ 账号（username）/ 密码（password）（free text）。直达链接问题必须说明其来源是 `view-source:` 后面的页面地址。收集后先展示摘要给用户确认；确认后写 `<需求名>/credentials.json5`（gitignore，非 template），`<需求名>/testcase.json5.testAccess` 只保留 `credentialRef: 'credentials.json5'` 和 `requiredRoles`，**回写**全局 `~/.ep-stage/projects.index.json5` 的 `systems[].credentialsCache`（按 loginUrl 归并，跨需求复用）。
-- **选 2**：保留 template；提示"请编辑 `credentials.json5` 后再跑 `/glue-run-test`"，进入 Step 6。
-- **选 3**：从 `systems[].credentialsCache` 拼出 credentials.json5，缺失角色用 template 占位符保留；`<需求名>/testcase.json5.testAccess` 只保留 `credentialRef: 'credentials.json5'` 和 `requiredRoles`，不写明文账号密码。
-
-### Step 6 — 校验产物完整性 + 审阅 testcase.md 单表
-
-**Step 6.1 — 校验产物完整性**
-
-按 §3 验证清单 `ls` / `Read` 校验 CLI 产物存在（除 `testcase.md` 外其他全部，缺任意一项视为整体失败，按 §4 报告）：
-
-- `testcase.json5`、`credentials.template.json5`（或 `credentials.json5`）、`.ep-stage/contract.json5`、`.ep-stage/inference-trace.json`
-
-Step 6 只需要确认 CLI 已基于 `testcase.json5` 事实源写出 `testcase.md`。该文件固定是一张审阅表，列为：用例 ID / 生成策略 / 用例标题 / 查询主键 / 前置条件 / 执行步骤 / 执行断言。glue 与 ai 统一在同一张表中，通过“生成策略”列区分。每次重跑都会整体覆盖 `testcase.md`；人审意见只写进 `testcase.json5`（JSON5 `// 注释`），不写 `testcase.md`。
-
-### 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`             | testcase schema v1-draft（schemaVersion / scenario / moduleId / moduleName / menuPath / runtimeContext? / testAccess? / contractRef / cases / uncoveredCandidates），**事实源** |
-| `<projectDir>/src/tests/<需求名>/testcase.md`                | 基于 `testcase.json5` 渲染的单表审阅视图（列：用例 ID / 生成策略 / 用例标题 / 查询主键 / 前置条件 / 执行步骤 / 执行断言；重跑覆盖） |
-| `<projectDir>/src/tests/<需求名>/credentials.template.json5` | 行数 = `code_list.roles.length`（每条对应一个角色）    |
-| `<projectDir>/src/tests/<需求名>/.ep-stage/contract.json5`    | 内部产物，机器专用，禁手编                               |
-| `<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.json5）              | AskUserQuestion 三选一：提供路径 / 读 PRD 草稿 / 取消                   |
-| CLI exit ≠ 0                            | 复述 stderr 中文转述，不发完成提示，不进 Step 5                        |
-| testcase.json5 缺 `schemaVersion`        | 报"产物 schema 校验失败，请重跑 `/glue-generate-testcase <code_list.json5路径>`" |
-| Step 5 选 1 用户中途取消                | 保留 template，提示"凭据未写入，请稍后拷贝 template 自填"              |
-| testcase.md 单表缺失或结构异常          | 复述缺失项或列结构异常，提示检查 testcase.json5 与 CLI 输出后重跑 |
-
-## 5. 完成提示
-
-Step 8 全部通过后，按以下中文格式呈现（不要用 success/done/generated）：
-
-> 用例已生成。
->
-> 测试项目：`<projectDir>`
-> 用例文件：`<projectDir>/src/tests/<需求名>/testcase.json5`
-> 用例摘要：共 N 条，胶水组装 X 条，AI 推理 Y 条
-> 重点审核：AI 推理用例、blocked 候选、登录角色信息
->
-> 需要调整的话，直接告诉我改哪条用例，我来更新 testcase.json5。
->
-> 下一步指令：
-> `/glue-run-test <projectDir>/src/tests/<需求名>/testcase.json5`
-
-## 6. 引导场景
-
-- **A（缺脚手架）**：Step 2 反查 projects.index.json5 无 glue 条目 → 提示先跑 `/glue-create-project` 退出。
-- **D（缺 code_list.json5）**：Step 3 缺失 → AskUserQuestion 三选一（提供路径 / 读 PRD 草稿 / 取消）。
-- **B / C**：由下游 `glue-run-test` 处理。
-
-## 7. 输入字段约定
-
-```markdown
-<!-- code_list.json5 字段约定（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` 顶层骨架（v1-draft，详见 references/testcase-schema.md）：
-
-```json5
-{
-  schemaVersion: "ep-stage-testcase/v1-draft",
-  testcaseId: "zwplace-testcase",
-  contractRef: ".ep-stage/contract.json5",     // 指向同需求目录 .ep-stage/contract.json5
-  scenario: "crud_export",                      // 产物：CLI 按 code_list.json5 推导，014 默认 crud_export
-  moduleId: "zwplace", moduleName: "场所窗口信息管理",
-  menuPath: "场所窗口信息管理>场所窗口信息列表",
-  runtimeContext: {
-    testProjectDir: "/abs/path/to/glue-project",
-    caseDir: "/abs/path/to/glue-project/src/tests/014-测试需求10-20260622",
-    specPath: "/abs/path/to/glue-project/src/tests/014-测试需求10-20260622/crud.spec.ts"
-  },
-  testAccess: {
-    credentialRef: "credentials.json5",
-    requiredRoles: ["业务管理员"]
-  },
-  cases: [
-    { caseId: "zwplace-placename-create", title: "场所名称-新增", generationStrategy: "glue", coverageStatus: "covered", reviewStatus: "confirmed", queryKey: "场所名称", precondition: "使用具备权限的测试角色登录系统并进入目标列表页", steps: "按查询主键完成新增、查询、编辑、删除或导出流程", assertion: "按查询主键、列表结果或导出行为验证执行结果" }
-    // cases[] 桶只承载 generationStrategy='glue'；正式执行字段同步写入 queryKey/precondition/steps/assertion
-  ],
-  uncoveredCandidates: [
-    { caseId: "businessState.transitions", label: "状态流转", generationStrategy: "ai", coverageStatus: "gap", requiredRole: "业务管理员", businessIntent: "覆盖在用不可删除等业务规则边界", assertionExpectation: "在用状态场所执行删除时应被业务规则阻断", queryKey: "不适用", precondition: "使用角色：业务管理员", steps: "按 AI Runtime Task 观察页面并执行：覆盖在用不可删除等业务规则边界", assertion: "在用状态场所执行删除时应被业务规则阻断" }
-    // uncoveredCandidates[] 桶只承载 generationStrategy='ai'；缺入口/缺权限/缺运行数据用 coverageStatus='blocked' 表达，同时保留正式执行字段
-  ]
-}
-```
-
-`<需求名>/credentials.template.json5`（按 code_list.json5 的业务角色事实生成模板） + `~/.ep-stage/projects.index.json5` 需求条目（CLI 追加到 `projects[].requirements[]`）：
-
-```json5
-// credentials.template.json5
-[
-  {
-    directUrl: "<请填待测页面直达链接，取 view-source: 后面的页面地址>",
-    loginUrl: "<请填登录地址>",
-    systemName: "<请填系统名称>",
-    role: "业务管理员",
-    username: "<请填账号>",
-    password: "<请填密码>",
-  },
-]
-
-// 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`（v1-draft）
-- **testcase.md 渲染规则：统一单表，列为用例 ID / 生成策略 / 用例标题 / 查询主键 / 前置条件 / 执行步骤 / 执行断言**
-- 既有工作流参考：`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。审阅视图固定为统一单表，glue 与 ai 只通过“生成策略”列区分，不再拆成两个表。
-- 对话中展示可审阅推理摘要和证据链，不展示原始隐式思维链。
+---
+name: glue-generate-testcase
+description: 使用时机：当用户对某需求要「生成用例 / 准备测试场景 / 钻探上游需求生成胶水冒烟用例」或显式触发 `/glue-generate-testcase <code_list.json5路径>` 时使用。本 skill 包装 `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，并负责自然语言映射、缺数据引导、Step 5 凭据交互确认。
+version: 2026-07-03+06ded5d
+argument-hint: "<code_list.json5绝对/相对路径>"
+---
+
+# ep-stage: glue-generate-testcase
+
+本 skill 引导 Agent **包装** `@epoint-testtech/ep-stage-skill` CLI 的 `testcase` 子命令，不重新实现钻探与用例生成。CLI 内部完成物料解析 + contract 提取（内嵌）+ coverage 分析 + testcase 装配 + credentials.template 生成。skill 负责：`code_list.json5` 路径解析、反查项目脚手架、缺数据引导、Step 5 平台对话确认凭据、审阅引导。用户视角全中文，不暴露 CLI 名称。
+
+> **契约可观测性 gate**：每个非平凡字段必须能追溯到上游证据、可重复推导规则、运行配置来源或人工确认问题；无法给出来源的字段必须进入 `unresolvedSlots`，禁止写入 `contract.json5`。"无来源不入契约"。
+
+> 钻探前置：testcase.json5 顶层（schemaVersion:'ep-stage-testcase/v1-draft' + testcaseId + contractRef + scenario + moduleId + moduleName + runtimeContext? + testAccess? + cases + uncoveredCandidates）由 CLI 一次写入。scenario 由 CLI 按 `code_list.json5` 推导（assembler），014 默认 `crud_export`；scenario 作为**产物**（非输入）写入顶层。`menuPath` 不是新链路必填字段。`runtimeContext` 用于落定工程与 spec 路径；`testAccess` 只保存 `credentialRef/requiredRoles`，明文账号密码与运行访问数据统一写入 `credentials.json5`。`directUrl` 是待测页面直达地址，不属于上游出码事实；缺失时必须在本 skill 交互补齐，并通过 CLI 参数写入 `contract.json5.base.navigation.directUrl`。**module-hints 已废弃**（交接文档 §4.1），不作为输入。
+
+## 1. 自然语言映射
+
+```text
+/glue-generate-testcase /abs/path/.../014-测试需求10-20260622/_docs/code_list.json5          # 绝对路径
+/glue-generate-testcase ../knowledge-project/.../014-测试需求10-20260622/_docs/code_list.json5  # 相对路径
+/glue-generate-testcase                                                             # 无参数 → 问 code_list.json5 路径
+/glue-generate-testcase /abs/path/.../014-测试需求10-20260622/_docs/code_list.json5 --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。
+
+`--scenario` 不作为正常路径输入（scenario 由 CLI 按 `code_list.json5` 推导，014 默认 `crud_export`）；`--hints` / module-hints 已废弃，不作为输入。
+
+skill 把 `code_list.json5` 入参 `path.resolve` 绝对化，用其父目录的父目录 basename 取「需求名」作为 `<projectDir>/src/tests/<需求名>` 子目录（`_docs/code_list.json5` 上一级即需求目录）。**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.json5 路径
+- [ ] 第 2 步 — 反查项目脚手架
+- [ ] 第 3 步 — 校验 code_list.json5 输入
+- [ ] 第 4 步 — 补齐待测页面 directUrl 并调用钻探与用例生成 CLI
+- [ ] 第 5 步 — 与研发人员交互确认推断结果
+- [ ] 第 6 步 — 校验产物完整性 + 审阅 testcase.md 单表
+- [ ] 第 7 步 — 写入需求条目到项目索引
+- [ ] 第 8 步 — 输出审阅引导摘要
+```
+
+### Step 1 — 解析 code_list 路径
+
+从用户消息 / args 抽取 `code_list.json5` 路径，绝对化后得到 `codeListPath`，再用其父目录的父目录 basename 作为需求名（`_docs/code_list.json5` 上一级即需求目录）。中文复述识别结果："已识别：code_list.json5 = `<abs>`，需求名 = `<basename>`"。入参缺失 → free text 询问"请给我 code_list.json5 的绝对或相对路径（位于需求目录 `_docs/` 下）"。
+
+### Step 2 — 反查项目脚手架（缺 → 引导 A）
+
+读 `~/.ep-stage/projects.index.json5`：文件不存在 / 无 glue 条目 → **引导场景 A**：中文提示"未发现胶水测试脚手架。请先跑 `/glue-create-project <项目名>` 创建脚手架后再回来"，退出不调 CLI。多条匹配 → AskUserQuestion 挑 projectDir。单条 → 直接拼 `--tests-dir` 根。
+
+### Step 3 — 校验 code_list.json5 输入（缺 → 引导 D）
+
+校验 `codeListPath` 是否存在，且 `code_list.json5` 内至少给出：
+- `knowledgeRoot: /abs/path`，或
+- `> 整理目录：\`/abs/path\``
+
+其余物料路径默认视为相对该根目录的路径；若某项缺失或不存在，再进入交互补齐。`codeListPath` 本身缺失 → **引导场景 D**，AskUserQuestion 三选一：
+
+1. **提供 code_list.json5 路径**：让用户给绝对路径（位于需求目录 `_docs/` 下），skill 改用该路径继续。
+2. **读 PRD 草稿生成 code_list.json5**：在需求目录找 PRD / spec.yaml，AI 推断 `knowledgeRoot` / `menu` / 文件清单写一份 `code_list.json5` 草稿到 `_docs/` 下，提示"已生成草稿，请人审后再跑"，退出。
+3. **取消**：直接退出，不调 CLI。
+
+### Step 4 — 补齐待测页面 directUrl 并调用钻探与用例生成 CLI
+
+固定流程（不 which、不扫 monorepo、不 cd、**不喂 stdin**）。调用 CLI 前先确定待测页面 `directUrl`：
+
+- 若 `code_list.json5` 已有待测页面节点的 `pages[role=list].directUrl`，直接使用。
+- 若缺失，必须用平台对话询问用户："请提供待测页面直达链接（directUrl）。说明：直达链接通常来自浏览器地址栏中 view-source: 后面的页面地址；例如 view-source:http://192.168.203.46:8100/epoint-web/perpage/zwplace/gxhzwplacelist.html，实际填写 http://192.168.203.46:8100/epoint-web/perpage/zwplace/gxhzwplacelist.html。"
+- 仍缺失则停止，不调 CLI。禁止让下游 `glue-run-test` 自行猜入口。
+
+**正常模式**（用户 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> \
+  --direct-url <待测列表页 directUrl>
+```
+
+（scenario 由 CLI 按 `code_list.json5` 推导，014 默认 `crud_export`，正常路径不传 `--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> \
+  --direct-url <待测列表页 directUrl>
+```
+
+（scenario 由 CLI 按 `code_list.json5` 推导，014 默认 `crud_export`，正常路径不传 `--scenario`）
+
+CLI 内部：按 `code_list.json5` 解析物料 → assembler 推导 scenario（014 默认 `crud_export`）→ 装配 contract + testcase（scenario 作为产物写入 `testcase.json5` 顶层，`directUrl` 写入 `contract.json5.base.navigation.directUrl`，`testcase.json5.testAccess` 只写 `credentialRef/requiredRoles`）→ schema 门禁 → 写 testcase.json5 / testcase.md（统一单表审阅视图）/ credentials.template.json5 / `.ep-stage/contract.json5` / `.ep-stage/inference-trace.json`。testcase.md 只渲染一张用例表，列为：用例 ID / 生成策略 / 用例标题 / 查询主键 / 前置条件 / 执行步骤 / 执行断言。glue 与 ai 通过“生成策略”列区分，不拆成两个表。CLI 非 0 退出 → 复述 stderr，不发完成提示，不进 Step 5。
+
+### Step 5 — 与研发人员交互确认推断结果（REQ-UX-02）
+
+Step 4 成功后，skill 读 CLI 产出的 `credentials.template.json5`（行数 = `code_list.roles.length`，每条对应一个角色）+ `uncoveredCandidates[].requiredRole`，再读 `~/.ep-stage/projects.index.json5` 的 `systems[]` 算 `cachedSystemsHit`（url 命中的列表）。用**平台对话能力**（Claude Code 用 `AskUserQuestion` / Codex 用对应交互机制）跟用户对话：
+
+> 推断出 **N 个角色**（如 建设单位 / 施工单位 / 监理单位）。请选择：
+> 1. **现在交互输入**（推荐：≤3 角色场景）— 我逐个角色问直达链接（directUrl）/ 登录地址（loginUrl）/ 系统名称（systemName）/ 角色（role）/ 账号（username）/ 密码（password），汇总摘要请你确认后写 `credentials.json5`
+> 2. **仅生成 template，自己后续填** — 退出后请拷贝 `credentials.template.json5` → `credentials.json5` 并填值
+> 3. **跳过，使用全局 systems[] 缓存复用** — 自动从 `cachedSystemsHit` 命中缓存生成 `credentials.json5`（缺失角色 fallback 引导 C，留给 glue-run-test）
+
+三分支处理：
+
+- **选 1**：skill 顺序问每条角色的直达链接（directUrl）/ 登录地址（loginUrl）/ 系统名称（systemName）/ 角色（role）/ 账号（username）/ 密码（password）（free text）。直达链接问题必须说明其来源是 `view-source:` 后面的页面地址。收集后先展示摘要给用户确认；确认后写 `<需求名>/credentials.json5`（gitignore，非 template），`<需求名>/testcase.json5.testAccess` 只保留 `credentialRef: 'credentials.json5'` 和 `requiredRoles`，**回写**全局 `~/.ep-stage/projects.index.json5` 的 `systems[].credentialsCache`（按 loginUrl 归并，跨需求复用）。
+- **选 2**：保留 template；提示"请编辑 `credentials.json5` 后再跑 `/glue-run-test`"，进入 Step 6。
+- **选 3**：从 `systems[].credentialsCache` 拼出 credentials.json5，缺失角色用 template 占位符保留；`<需求名>/testcase.json5.testAccess` 只保留 `credentialRef: 'credentials.json5'` 和 `requiredRoles`，不写明文账号密码。
+
+### Step 6 — 校验产物完整性 + 审阅 testcase.md 单表
+
+**Step 6.1 — 校验产物完整性**
+
+按 §3 验证清单 `ls` / `Read` 校验 CLI 产物存在（除 `testcase.md` 外其他全部，缺任意一项视为整体失败，按 §4 报告）：
+
+- `testcase.json5`、`credentials.template.json5`（或 `credentials.json5`）、`.ep-stage/contract.json5`、`.ep-stage/inference-trace.json`
+
+Step 6 只需要确认 CLI 已基于 `testcase.json5` 事实源写出 `testcase.md`。该文件固定是一张审阅表，列为：用例 ID / 生成策略 / 用例标题 / 查询主键 / 前置条件 / 执行步骤 / 执行断言。glue 与 ai 统一在同一张表中，通过“生成策略”列区分。每次重跑都会整体覆盖 `testcase.md`；人审意见只写进 `testcase.json5`（JSON5 `// 注释`），不写 `testcase.md`。
+
+### 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`             | testcase schema v1-draft（schemaVersion / scenario / moduleId / moduleName / menuPath / runtimeContext? / testAccess? / contractRef / cases / uncoveredCandidates），**事实源** |
+| `<projectDir>/src/tests/<需求名>/testcase.md`                | 基于 `testcase.json5` 渲染的单表审阅视图（列：用例 ID / 生成策略 / 用例标题 / 查询主键 / 前置条件 / 执行步骤 / 执行断言；重跑覆盖） |
+| `<projectDir>/src/tests/<需求名>/credentials.template.json5` | 行数 = `code_list.roles.length`（每条对应一个角色）    |
+| `<projectDir>/src/tests/<需求名>/.ep-stage/contract.json5`    | 内部产物，机器专用，禁手编                               |
+| `<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.json5）              | AskUserQuestion 三选一：提供路径 / 读 PRD 草稿 / 取消                   |
+| CLI exit ≠ 0                            | 复述 stderr 中文转述，不发完成提示，不进 Step 5                        |
+| testcase.json5 缺 `schemaVersion`        | 报"产物 schema 校验失败，请重跑 `/glue-generate-testcase <code_list.json5路径>`" |
+| Step 5 选 1 用户中途取消                | 保留 template，提示"凭据未写入，请稍后拷贝 template 自填"              |
+| testcase.md 单表缺失或结构异常          | 复述缺失项或列结构异常，提示检查 testcase.json5 与 CLI 输出后重跑 |
+
+## 5. 完成提示
+
+Step 8 全部通过后，按以下中文格式呈现（不要用 success/done/generated）：
+
+> 用例已生成。
+>
+> 测试项目：`<projectDir>`
+> 用例文件：`<projectDir>/src/tests/<需求名>/testcase.json5`
+> 用例摘要：共 N 条，胶水组装 X 条，AI 推理 Y 条
+> 重点审核：AI 推理用例、blocked 候选、登录角色信息
+>
+> 需要调整的话，直接告诉我改哪条用例，我来更新 testcase.json5。
+>
+> 下一步指令：
+> `/glue-run-test <projectDir>/src/tests/<需求名>/testcase.json5`
+
+## 6. 引导场景
+
+- **A（缺脚手架）**：Step 2 反查 projects.index.json5 无 glue 条目 → 提示先跑 `/glue-create-project` 退出。
+- **D（缺 code_list.json5）**：Step 3 缺失 → AskUserQuestion 三选一（提供路径 / 读 PRD 草稿 / 取消）。
+- **B / C**：由下游 `glue-run-test` 处理。
+
+## 7. 输入字段约定
+
+```markdown
+<!-- code_list.json5 字段约定（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` 顶层骨架（v1-draft，详见 references/testcase-schema.md）：
+
+```json5
+{
+  schemaVersion: "ep-stage-testcase/v1-draft",
+  testcaseId: "zwplace-testcase",
+  contractRef: ".ep-stage/contract.json5",     // 指向同需求目录 .ep-stage/contract.json5
+  scenario: "crud_export",                      // 产物：CLI 按 code_list.json5 推导，014 默认 crud_export
+  moduleId: "zwplace", moduleName: "场所窗口信息管理",
+  menuPath: "场所窗口信息管理>场所窗口信息列表",
+  runtimeContext: {
+    testProjectDir: "/abs/path/to/glue-project",
+    caseDir: "/abs/path/to/glue-project/src/tests/014-测试需求10-20260622",
+    specPath: "/abs/path/to/glue-project/src/tests/014-测试需求10-20260622/crud.spec.ts"
+  },
+  testAccess: {
+    credentialRef: "credentials.json5",
+    requiredRoles: ["业务管理员"]
+  },
+  cases: [
+    { caseId: "zwplace-placename-create", title: "场所名称-新增", generationStrategy: "glue", coverageStatus: "covered", reviewStatus: "confirmed", queryKey: "场所名称", precondition: "使用具备权限的测试角色登录系统并进入目标列表页", steps: "按查询主键完成新增、查询、编辑、删除或导出流程", assertion: "按查询主键、列表结果或导出行为验证执行结果" }
+    // cases[] 桶只承载 generationStrategy='glue'；正式执行字段同步写入 queryKey/precondition/steps/assertion
+  ],
+  uncoveredCandidates: [
+    { caseId: "businessState.transitions", label: "状态流转", generationStrategy: "ai", coverageStatus: "gap", requiredRole: "业务管理员", businessIntent: "覆盖在用不可删除等业务规则边界", assertionExpectation: "在用状态场所执行删除时应被业务规则阻断", queryKey: "不适用", precondition: "使用角色：业务管理员", steps: "按 AI Runtime Task 观察页面并执行：覆盖在用不可删除等业务规则边界", assertion: "在用状态场所执行删除时应被业务规则阻断" }
+    // uncoveredCandidates[] 桶只承载 generationStrategy='ai'；缺入口/缺权限/缺运行数据用 coverageStatus='blocked' 表达，同时保留正式执行字段
+  ]
+}
+```
+
+`<需求名>/credentials.template.json5`（按 code_list.json5 的业务角色事实生成模板） + `~/.ep-stage/projects.index.json5` 需求条目（CLI 追加到 `projects[].requirements[]`）：
+
+```json5
+// credentials.template.json5
+[
+  {
+    directUrl: "<请填待测页面直达链接，取 view-source: 后面的页面地址>",
+    loginUrl: "<请填登录地址>",
+    systemName: "<请填系统名称>",
+    role: "业务管理员",
+    username: "<请填账号>",
+    password: "<请填密码>",
+  },
+]
+
+// 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`（v1-draft）
+- **testcase.md 渲染规则：统一单表，列为用例 ID / 生成策略 / 用例标题 / 查询主键 / 前置条件 / 执行步骤 / 执行断言**
+- 既有工作流参考：`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。审阅视图固定为统一单表，glue 与 ai 只通过“生成策略”列区分，不再拆成两个表。
+- 对话中展示可审阅推理摘要和证据链，不展示原始隐式思维链。