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

package/docs/README.md

@@ -1,134 +1,124 @@
-# @epoint-testtech/ep-stage-skill
-
-> 胶水编码链路 Agent Skill — 解析上游物料，按契约生成可执行测试脚本
-
-## 定位
-
-`ep-stage-skill` 是 **ep-stage 生态的 AI 驱动层**，作为 Agent Skill 嵌入胶水编码链路。它解析上游物料（PRD、code_list、HTML、Java Action），根据槽位信息契约按图索骥，获取槽位信息后组装 `stage-create --mode glue` 创建的骨架项目中的代码骨架，最终生成可以真实执行的 Playwright 测试脚本。
-
-## 外发形式
-
-AI Agent 可发现的 Skill 入口（Claude Code 扫 `.claude/skills/`、Codex 扫 `.agents/skills/`，均 symlink 到包内源）：
-
-```text
-.claude/skills/{glue-create-project, glue-generate-testcase, glue-run-test, recording-to-glue}
-.agents/skills/{glue-create-project, glue-generate-testcase, glue-run-test, recording-to-glue}
-  → packages/ep-stage-skill/codex-skill/ep-stage/<skill>/
-```
-
-## 链路
-
-```text
-上游物料（PRD / code_list / HTML / Java Action）
-  -> 解析上游物料，提取 crud-business-module/v1 契约
-  -> 根据槽位信息契约按图索骥，获取槽位信息
-  -> 组装 stage-create glue 骨架项目中的代码骨架
-  -> 生成 CrudFlowSlots spec
-  -> 落袋到 stage-create 脚手架项目
-```
-
-## CLI
-
-```bash
-# 可观测默认入口（推荐）
-pnpm --filter @epoint-testtech/ep-stage-skill run:gap-pipeline -- \
-  --code-list <code_list.md>
-
-# 生成契约
-pnpm --filter @epoint-testtech/ep-stage-skill generate:crud-contract -- \
-  --module-id <模块ID> \
-  --docs <上游文档目录> \
-  --code-list <code_list.md> \
-  --webapp <前端 HTML 目录> \
-  --java-actions <Java Action 目录> \
-  --hints packages/ep-stage-skill/examples/<module>.module-hints.json \
-  --out output/<module>.crud.contract.json
-
-# 生成测试脚本
-pnpm --filter @epoint-testtech/ep-stage-skill generate:playwright-tests -- \
-  --contract output/<module>.crud.contract.json \
-  --out <glue项目>/src/tests/<name>.spec.ts \
-  --menu "一级菜单>二级菜单" \
-  --testcase <glue项目>/testcases/<module>.glue-testcase.json
-```
-
-`run:gap-pipeline` 的默认业务输入收口到 `code_list.md`。建议在该文件中声明：
-
-```md
-knowledgeRoot: /abs/path/to/knowledge-project/xxx
-menu: 一级菜单>二级菜单
-
-`_docs/.../spec.yaml`
-`src/main/webapp/.../*.html`
-`src/main/java/.../*Action.java`
-`_docs/.../*.module-hints.json`
-```
-
-说明：
-
-- `knowledgeRoot`：上游物料根目录，用于解析 `code_list.md` 中的相对路径。
-- `menu` / `menuPath`：系统菜单路由，不是文件路径；缺失时链路会生成候选菜单并停在人工确认 gate。
-- `--docs` / `--webapp` / `--java-actions` / `--hints` / `--menu` / `--project-dir`：仍保留，但定位为开发调试覆盖参数。
-
-当前验收主线只锚定 `zwplace`，其唯一上游扎口是：
-
-```text
-knowledge-project/epoint-web-v9.5.2/_docs/code_list.md
-```
-
-由于主仓 `knowledge-project` 只读，仓内另提供一个“模拟交互补齐后回写”的**可写镜像**：
-
-```text
-packages/ep-stage-skill/examples/zwplace.observable.code_list.md
-```
-
-这个镜像不修改主仓只读 `knowledge-project/.../_docs/code_list.md`，而是把 `knowledgeRoot`、`menu`、文档物料和
-`ModuleHints` 写入单独的可写 `code_list.md`，用于默认入口验证、交互补齐回写验证，以及只读真相源无法直接落盘时的 e2e 联调。
-
-不要把脚手架项目中带出的说明信息当作上游本源；当前 skill 的默认入口和业务真相源仍然是 `code_list.md`。
-
-如果后续要验证“不同系统的普通 CRUD 泛化”，应直接由用户补充第二个真实业务样本的 `code_list.md`，再复用同一条 `run:gap-pipeline -- --code-list <path>` 链路；不要把脚手架项目中的说明信息当作第二个业务样本。
-
-当前 `run:gap-pipeline` 在 TTY 环境下已支持对默认入口缺失字段做轻量交互补齐：
-
-- `material-inventory` gate：补 `knowledgeRoot`、`moduleId`、`webappDir`、`javaActionsDir`、`hintsPath`、`menu`
-- `menu` gate：补 `menu`
-
-若目标 `code_list.md` 是可写文件，补齐结果会按当前格式回写；若目标位于主仓只读
-`knowledge-project/...`，补齐结果只对本次运行生效，不会写回受保护物料。
-
-真实系统 E2E 约束：
-
-- 禁止无头模式作为真实系统验收方式；真实系统验证必须使用 `--headless false`。
-- 必须通过 `packages/ep-stage-skill/codex-skill/ep-stage` 对应 skill / `run:gap-pipeline` 入口执行，不接受绕开 skill 的自由式 Playwright 回放作为当前验收证据。
-- 运行过程中需要人为观察页面、登录、弹窗和业务副作用；trace / report 负责补证，不替代人工观察。
-
-当链路已走到 Playwright / glue-report 尾段但真实系统环境不可用时，`playwright-execution` trace 会把失败归类为
-`environment_unavailable`，并尽量补充 `.env` 中 `LOGIN_SYSTEM_URL` 的轻量环境预检证据（例如 `curl -I: Empty reply from server`），
-避免把登录环境空响应误判成 stage-glue 代码缺陷。
-
-## 开发
-
-```bash
-pnpm build
-pnpm test
-pnpm typecheck
-```
-
-## Gap Inference
-
-`ep-stage-skill` 会先生成 CRUD + Export 可覆盖范围，再对当前模块的页面按钮、行操作和弹窗动作做 coverage diff。
-
-- CRUD + Export 已覆盖动作不会进入 gap。
-- 只有按钮文本不足以生成测试。
-- `ModuleHints.customWorkflows` 可以补充自定义工作流的业务意图和断言预期。
-- 真实页面定位补证由 `e2e/glue-code-mvp` 的 gap-executor 试点 runner 执行。
-
-## 生态关系
-
-```text
-ep-stage-skill（AI 驱动 / 解析 + 组装）
-  ├── 消费 stage-core（定位器、自动填充）
-  ├── 消费 stage-create glue 骨架（skeletons）
-  └── 产出测试脚本 → 落袋到 stage-create 项目
-```
+# @epoint-testtech/ep-stage-skill
+
+> ep-stage 胶水编码 Skill 与 CLI — 从 `code_list.json5` 生成用例、契约、脚本任务并驱动执行闭环
+
+## 定位
+
+`ep-stage-skill` 是 **ep-stage 生态的 AI 驱动层**。它同时提供：
+
+- 面向 Claude Code / Codex 的 Skill 文案与执行剧本。
+- 面向确定性处理的 TypeScript CLI。
+- 上游物料抽取、契约生成、用例装配、spec 组装、AI Runtime 任务准备和执行报告衔接能力。
+
+当前正式用户链路以三个 Skill 为入口：
+
+```text
+/glue-create-project -> /glue-generate-testcase -> /glue-run-test
+```
+
+## Skill 外发形式
+
+AI Agent 可发现的 Skill 入口通过双目录 symlink 暴露：
+
+```text
+.claude/skills/{glue-create-project, glue-generate-testcase, glue-run-test, recording-to-glue}
+.agents/skills/{glue-create-project, glue-generate-testcase, glue-run-test, recording-to-glue}
+  -> packages/ep-stage-skill/codex-skill/ep-stage/<skill>/
+```
+
+用户行为文案以 `packages/ep-stage-skill/codex-skill/ep-stage/*/SKILL.md` 为准。
+
+## 当前链路
+
+```text
+需求目录/_docs/code_list.json5
+  -> testcase 子命令解析物料、提取契约、生成 testcase
+  -> testcase.json5 + testcase.md + credentials.template.json5 + .ep-stage/contract.json5
+  -> spec / prepare-tasks 子命令组装 glue 骨架并生成 AI Runtime tasks
+  -> Agent 使用真实页面 O-D-A-V 产出 ai-snippets.json5
+  -> run 子命令合并 resolved snippet 并执行完整 spec
+  -> glue-report / repair-report
+```
+
+## CLI 子命令
+
+```bash
+# 生成用例、契约、审阅视图和凭据模板
+pnpm --filter @epoint-testtech/ep-stage-skill cli -- testcase \
+  --code-list <需求目录/_docs/code_list.json5> \
+  --tests-dir <glue项目>/src/tests/<需求名> \
+  --requirement-dir <需求目录/_docs> \
+  --project-dir <glue项目> \
+  --direct-url <待测列表页直达 URL>
+
+# 基于 testcase.json5 + contract.json5 生成初始 glue spec
+pnpm --filter @epoint-testtech/ep-stage-skill cli -- spec \
+  --testcase <glue项目>/src/tests/<需求名>/testcase.json5 \
+  --out <glue项目>/src/tests/<需求名>/crud.spec.ts
+
+# 准备执行任务：缺 spec 时自动补组装 glue 骨架，并输出 AI Runtime tasks
+pnpm --filter @epoint-testtech/ep-stage-skill cli -- prepare-tasks \
+  --testcase <glue项目>/src/tests/<需求名>/testcase.json5
+
+# 合并 Agent 产出的 ai-snippets.json5 并执行完整 spec
+pnpm --filter @epoint-testtech/ep-stage-skill cli -- run \
+  --testcase <glue项目>/src/tests/<需求名>/testcase.json5 \
+  --ai-snippets <glue项目>/src/tests/<需求名>/.ep-stage/ai-snippets.json5 \
+  --headless false
+```
+
+> 正常用户不需要直接运行这些命令；Skill 会按步骤包装调用。开发调试时可用 `pnpm --filter @epoint-testtech/ep-stage-skill cli -- <subcommand>` 直接验证 CLI 行为。
+
+## 输入与产物
+
+### 输入
+
+`testcase` 子命令的正式输入是需求目录下的：
+
+```text
+_docs/code_list.json5
+```
+
+`code_list.json5` 只记录上游研发对需求和出码产物的结构化总结，不应写入测试执行结果、最终 Playwright locator、账号密码或运行态页面观察。
+
+### 产物
+
+| 产物 | 说明 |
+|------|------|
+| `testcase.json5` | 用例事实源，后续 `/glue-run-test` 的入口 |
+| `testcase.md` | 人工审阅视图，每次重跑会按 `testcase.json5` 重新渲染 |
+| `credentials.template.json5` | 凭据模板 |
+| `credentials.json5` | 实际测试凭据，由人工填写或交互生成，通常不提交 |
+| `.ep-stage/contract.json5` | 下游消费契约，记录可信槽位、证据和未解析项 |
+| `.ep-stage/inference-trace.json` | 用例生成过程账本 |
+| `.ep-stage/ai-runtime-trace.json5` | run 阶段任务和结果账本 |
+| `.ep-stage/ai-snippets.json5` | Agent Runtime 产出的 resolved snippets |
+| `.ep-stage/repair-runs/<round>/repair-report.md` | 执行失败时的修补建议 |
+
+## 关键约束
+
+- `code_list.json5` 是上游输入，不反灌测试契约、运行结果或账号密码。
+- `contract.json5` 中每个非平凡字段都应有来源；无法确认的字段进入 `unresolvedSlots`。
+- 生成策略只使用 `glue` / `ai`；阻断场景用 `coverageStatus: blocked` 表达。
+- `glue-run-test` 不重新钻探上游物料，只消费 `testcase.json5` 和 `.ep-stage/contract.json5`。
+- AI Runtime 只合并 `status="resolved"` 的 snippet；缺 resolved 结果时停止并写 `needs_review`，不追加占位代码。
+- 真实系统执行必须使用有界面模式，便于人工观察运行态推理和业务副作用。
+
+## 开发
+
+```bash
+pnpm build
+pnpm test
+pnpm typecheck
+```
+
+## 生态关系
+
+```text
+ep-stage-skill（Skill + CLI）
+  ├── 消费 stage-create glue 模板项目
+  ├── 消费 stage-core 基础能力
+  ├── 读取需求目录 _docs/code_list.json5
+  ├── 产出 testcase / contract / trace / spec / snippets
+  └── 驱动 glue-report 与 repair-report 闭环
+```