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

package/dist/test/testcase-skeleton.test.js

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+import { mapContractToCrudTestcaseSlots, renderGlueTestcaseSkeleton, selectTestcaseSkeletonByScenario, } from '../src/index.js';
+/**
+ * 构造用例骨架映射测试所需的最小 CRUD 契约。
+ *
+ * @returns 包含完整 CRUD 槽位来源的测试契约。
+ */
+function createCrudContract() {
+    return {
+        contractVersion: 'crud-business-module/v1',
+        module: {
+            id: 'zwplace',
+            label: '场所窗口信息管理',
+        },
+        pages: {
+            list: {
+                role: 'list',
+                pageId: 'gxhzwplacelist',
+                title: '场所窗口信息列表',
+                iframeSrcKeyword: 'gxhzwplacelist',
+                fields: [],
+                buttons: [],
+                grids: [],
+                dialogs: [],
+                sources: [],
+            },
+        },
+        dataKey: {
+            field: 'windowname',
+            label: '窗口名称',
+            availability: 'derivable',
+            generationStrategy: 'timestamp_prefix',
+            sources: [],
+        },
+        searchConditions: [
+            {
+                field: 'windowname',
+                label: '窗口名称',
+                component: 'input',
+                seedValue: '自动化测试窗口',
+                generationStrategy: 'timestamp_prefix',
+                sources: [],
+            },
+        ],
+        flows: {
+            create: {
+                entryButton: {
+                    pageRole: 'list',
+                    label: '新增场所窗口',
+                    sources: [],
+                },
+                targetPageId: 'gxhzwplaceadd',
+                saveButton: {
+                    pageRole: 'add',
+                    label: '保存并关闭',
+                    sources: [],
+                },
+                overrideFields: [],
+            },
+            search: {
+                searchField: {
+                    pageRole: 'list',
+                    field: 'windowname',
+                    label: '窗口名称',
+                    sources: [],
+                },
+                submitControl: {
+                    pageRole: 'list',
+                    label: '查询',
+                    sources: [],
+                },
+                resultGrid: 'datagrid',
+            },
+            update: {
+                entryAction: {
+                    pageRole: 'list',
+                    label: '修改',
+                    sources: [],
+                },
+                targetPageId: 'gxhzwplaceedit',
+                updateField: {
+                    pageRole: 'edit',
+                    field: 'windowname',
+                    label: '窗口名称',
+                    sources: [],
+                },
+                saveButton: {
+                    pageRole: 'edit',
+                    label: '保存并关闭',
+                    sources: [],
+                },
+            },
+            delete: {
+                entryButton: {
+                    pageRole: 'list',
+                    label: '删除选定',
+                    sources: [],
+                },
+                expectedOutcome: 'success_delete',
+                confirmControl: {
+                    pageRole: 'list',
+                    label: '确定',
+                    sources: [],
+                },
+            },
+        },
+        assertions: [],
+        businessRules: [],
+        unresolvedSlots: [],
+    };
+}
+describe('glue testcase skeleton', () => {
+    it('selects the CRUD testcase skeleton for a single-page CRUD scenario', () => {
+        expect(selectTestcaseSkeletonByScenario('crud.single-page')).toMatchObject({
+            skeletonId: 'crud.skeleton-testcase/v1',
+        });
+    });
+    it('selects the same CRUD testcase skeleton for a nested CRUD pilot scenario', () => {
+        expect(selectTestcaseSkeletonByScenario('crud.nested')).toMatchObject({
+            skeletonId: 'crud.skeleton-testcase/v1',
+        });
+    });
+    it('maps a CRUD contract to testcase slots without guessing unresolved business values', () => {
+        const slots = mapContractToCrudTestcaseSlots({
+            contract: createCrudContract(),
+            scenario: 'crud.single-page',
+            menu: '场所窗口信息管理>场所窗口信息列表',
+        });
+        expect(slots).toMatchObject({
+            moduleId: 'zwplace',
+            moduleName: '场所窗口信息管理',
+            listPageTitle: '场所窗口信息列表',
+            createActionLabel: '新增场所窗口',
+            searchFieldLabel: '窗口名称',
+            envBaseUrl: '.env: LOGIN_SYSTEM_URL',
+            envUsername: '.env: LOGIN_USERNAME',
+            envPassword: '.env: LOGIN_PASSWORD',
+            unresolved: [],
+        });
+    });
+    it('treats unresolved menu placeholders as unresolved instead of resolved slot sources', () => {
+        const slots = mapContractToCrudTestcaseSlots({
+            contract: createCrudContract(),
+            scenario: 'crud.single-page',
+            menu: '未确认菜单路径',
+        });
+        expect(slots.reviewStatus).toBe('needs_review');
+        expect(slots.menu).toBe('待人工确认');
+        expect(slots.unresolved).toContain('menu: 缺少 input.menu');
+        expect(slots.slotSources).not.toContain('menu=input.menu');
+    });
+    it('records missing contract slots as unresolved without guessing business values', () => {
+        const contract = createCrudContract();
+        delete contract.flows.create;
+        const slots = mapContractToCrudTestcaseSlots({
+            contract,
+            scenario: 'crud.single-page',
+            menu: '场所窗口信息管理>场所窗口信息列表',
+        });
+        expect(slots.reviewStatus).toBe('needs_review');
+        expect(slots.createActionLabel).toBe('待人工确认');
+        expect(slots.unresolved).toContain('createActionLabel: 缺少 contract.flows.create.entryButton.label');
+    });
+    it('renders the testcase skeleton template from slots', () => {
+        const template = [
+            '# {{moduleName}}',
+            '',
+            '## {{createCaseTitle}}',
+            '',
+            '- 列表页：{{listPageTitle}}',
+            '- 步骤：{{createSteps}}',
+            '- 查询字段：{{searchFieldLabel}}',
+        ].join('\n');
+        const markdown = renderGlueTestcaseSkeleton(template, mapContractToCrudTestcaseSlots({
+            contract: createCrudContract(),
+            scenario: 'crud.single-page',
+            menu: '场所窗口信息管理>场所窗口信息列表',
+        }));
+        expect(markdown).toContain('# 场所窗口信息管理');
+        expect(markdown).toContain('## 新增场所窗口信息管理');
+        expect(markdown).toContain('列表页：场所窗口信息列表');
+        expect(markdown).toContain('查询字段：窗口名称');
+        expect(markdown).not.toContain('{{');
+    });
+});

package/dist/test/testcase-spec-assembly.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=testcase-spec-assembly.test.d.ts.map

package/dist/test/testcase-spec-assembly.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testcase-spec-assembly.test.d.ts","sourceRoot":"","sources":["../../test/testcase-spec-assembly.test.ts"],"names":[],"mappings":""}

package/dist/test/testcase-spec-assembly.test.js

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import { validateGlueTestcaseDocumentForSpecAssembly } from '../src/testcase/testcase-spec-assembly.js';
+/**
+ * 构造 spec assembly 校验所需的最小契约。
+ *
+ * @returns CRUD 业务模块契约的模块标识部分。
+ */
+function createContract() {
+    return {
+        contractVersion: 'crud-business-module/v1',
+        module: {
+            id: 'zwplace',
+            label: '场所窗口信息管理',
+        },
+        pages: {
+            list: {
+                role: 'list',
+                pageId: 'gxhzwplacelist',
+                title: '场所窗口信息列表',
+                iframeSrcKeyword: 'gxhzwplacelist',
+                fields: [],
+                buttons: [],
+                grids: [],
+                dialogs: [],
+                sources: [],
+            },
+        },
+        dataKey: {
+            field: 'windowname',
+            label: '窗口名称',
+            availability: 'derivable',
+            generationStrategy: 'timestamp_prefix',
+            sources: [],
+        },
+        flows: {},
+        assertions: [],
+        businessRules: [],
+        unresolvedSlots: [],
+    };
+}
+/**
+ * 构造已确认的 CRUD 四工作流用例文档。
+ *
+ * @returns 胶水测试用例文档。
+ */
+function createConfirmedTestcaseDocument() {
+    return {
+        moduleId: 'zwplace',
+        moduleName: '场所窗口信息管理',
+        cases: [
+            createCase('zwplace.create', 'Create：新增场所窗口信息管理'),
+            createCase('zwplace.read', 'Read：搜索场所窗口信息管理'),
+            createCase('zwplace.update', 'Update：修改场所窗口信息管理'),
+            createCase('zwplace.delete', 'Delete：删除场所窗口信息管理'),
+        ],
+        reasoningSummary: {
+            conclusion: '已确认 CRUD 用例。',
+            evidenceChain: [],
+            alternatives: [],
+            confidence: 'high',
+            risks: [],
+            needsHumanReview: false,
+        },
+    };
+}
+/**
+ * 构造单条已确认用例。
+ *
+ * @param caseId 用例 ID。
+ * @param title 用例标题。
+ * @returns 胶水测试用例。
+ */
+function createCase(caseId, title) {
+    return {
+        caseId,
+        title,
+        scenario: 'crud.single-page',
+        reviewStatus: 'confirmed',
+        evidence: [],
+        steps: ['执行动作'],
+        assertions: ['验证结果'],
+        unresolved: [],
+    };
+}
+describe('testcase spec assembly contract', () => {
+    it('accepts confirmed testcase documents that match the contract CRUD workflow granularity', () => {
+        expect(() => validateGlueTestcaseDocumentForSpecAssembly(createConfirmedTestcaseDocument(), createContract())).not.toThrow();
+    });
+    it('rejects testcase documents that still need human review', () => {
+        const document = createConfirmedTestcaseDocument();
+        document.cases[1].reviewStatus = 'needs_review';
+        document.cases[1].unresolved = ['menu: 缺少 input.menu'];
+        expect(() => validateGlueTestcaseDocumentForSpecAssembly(document, createContract())).toThrow('glue testcase 仍有未确认用例');
+    });
+    it('rejects testcase documents that do not match the contract module', () => {
+        const document = createConfirmedTestcaseDocument();
+        document.moduleId = 'other-module';
+        expect(() => validateGlueTestcaseDocumentForSpecAssembly(document, createContract())).toThrow('glue testcase moduleId 与 contract 不一致');
+    });
+    it('rejects testcase documents missing CRUD workflow cases required by the generated spec', () => {
+        const document = createConfirmedTestcaseDocument();
+        document.cases = document.cases.filter((item) => item.caseId !== 'zwplace.update');
+        expect(() => validateGlueTestcaseDocumentForSpecAssembly(document, createContract())).toThrow('glue testcase 缺少 spec assembly 需要的用例');
+    });
+});

package/dist/vitest.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("vite").UserConfig;
+export default _default;
+//# sourceMappingURL=vitest.config.d.ts.map

package/dist/vitest.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vitest.config.d.ts","sourceRoot":"","sources":["../vitest.config.ts"],"names":[],"mappings":";AAEA,wBAKG"}

package/dist/vitest.config.js

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+    test: {
+        include: ['test/**/*.test.ts'],
+        environment: 'node'
+    }
+});

package/docs/README.md

@@ -0,0 +1,134 @@
+# @epoint/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-test, create-project, recording-to-glue}
+.agents/skills/{glue-test, create-project, 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/ep-stage-skill run:gap-pipeline -- \
+  --code-list <code_list.md>
+
+# 生成契约
+pnpm --filter @epoint/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/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 项目
+```