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

package/dist/src/validation/inference-trace.js

@@ -0,0 +1,31 @@
+/**
+ * 校验 inference-trace.json 的顶层结构（REQ-INFER-006）。
+ *
+ * 最小校验：只保证 schemaVersion 正确且 5 个必需顶层章节存在。
+ * 章节内部证据数组 / reason 允许扩展（spec §8），不做深校验。
+ *
+ * @param obj - 从 JSON.parse 得到的任意值。
+ * @returns 类型收窄后的 InferenceTraceV1。
+ * @throws 顶层非对象、schemaVersion 不符或缺章节时抛错。
+ */
+export function validateInferenceTrace(obj) {
+    const raw = obj;
+    if (!raw || typeof raw !== 'object') {
+        throw new Error('inference-trace.json 顶层必须是对象');
+    }
+    if (raw.schemaVersion !== 'inference-trace/v1') {
+        throw new Error('inference-trace.json schemaVersion 必须是 inference-trace/v1');
+    }
+    for (const key of [
+        'materialInventory',
+        'sourceAnalysis',
+        'moduleHintsInference',
+        'coverageDiff',
+        'reasoningSummary',
+    ]) {
+        if (!raw[key]) {
+            throw new Error(`inference-trace.json 缺 ${key}`);
+        }
+    }
+    return raw;
+}

package/dist/test/cli/generate-testcase-inference.test.d.ts

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

package/dist/test/cli/generate-testcase-inference.test.d.ts.map

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

package/dist/test/cli/generate-testcase-inference.test.js

@@ -0,0 +1,63 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import JSON5 from 'json5';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { runGenerateTestcase } from '../../src/cli/generate-testcase.js';
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const codeList = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2/_docs/014-测试需求10-20260622/code_list.md');
+/**
+ * HOME 隔离 + 预填 projects.index.json5，让 runGenerateTestcase 的 requirement 追加不报错、不污染真实环境。
+ */
+function seedIsolatedHomeWithProject(homeDir, projectDir) {
+    const indexPath = join(homeDir, '.ep-stage', 'projects.index.json5');
+    mkdirSync(dirname(indexPath), { recursive: true });
+    writeFileSync(indexPath, `${JSON5.stringify({
+        projects: [
+            {
+                projectName: 'test-inference',
+                projectDir,
+                mode: 'glue',
+                stageCreateVersion: '0.0.0-test',
+                requirements: [],
+            },
+        ],
+        systems: [],
+    }, null, 2)}\n`, 'utf8');
+}
+describe('runGenerateTestcase inference trace output', () => {
+    let tmpDir = '';
+    let tmpHome = '';
+    const originalHome = process.env.HOME;
+    beforeEach(() => {
+        tmpHome = mkdtempSync(join(tmpdir(), 'ep-stage-inference-home-'));
+        process.env.HOME = tmpHome;
+    });
+    afterEach(() => {
+        process.env.HOME = originalHome;
+        if (tmpHome)
+            rmSync(tmpHome, { recursive: true, force: true });
+        if (tmpDir)
+            rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('只传 code_list 时落 contract.json 与 inference-trace.json，不落独立 module-hints 文件', () => {
+        tmpDir = mkdtempSync(join(tmpdir(), 'ep-stage-testcase-'));
+        const projectDir = join(tmpDir, 'project');
+        const testsDir = join(projectDir, 'src', 'tests', '014-测试需求10-20260622');
+        seedIsolatedHomeWithProject(tmpHome, projectDir);
+        runGenerateTestcase({ codeList, testsDir, requirementDir: dirname(codeList), projectDir });
+        const tracePath = join(testsDir, '.ep-stage/inference-trace.json');
+        const contractPath = join(testsDir, '.ep-stage/contract.json');
+        expect(existsSync(tracePath)).toBe(true);
+        expect(existsSync(contractPath)).toBe(true);
+        expect(existsSync(join(testsDir, '.ep-stage/source-spec.json'))).toBe(false);
+        expect(existsSync(join(testsDir, '.ep-stage/module-hints.inferred.json5'))).toBe(false);
+        const trace = JSON.parse(readFileSync(tracePath, 'utf8'));
+        expect(trace.schemaVersion).toBe('inference-trace/v1');
+        expect(trace.sourceAnalysis.mode).toMatch(/prd|mixed|inferred/);
+        expect(trace.moduleHintsInference.dataKey.selectedField).toBe('placename');
+        const testcase = JSON5.parse(readFileSync(join(testsDir, 'testcase.json5'), 'utf8'));
+        expect(testcase.moduleId).toBe('zwplace');
+    });
+});

package/dist/test/cli/generate-testcase-paths.test.d.ts

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

package/dist/test/cli/generate-testcase-paths.test.d.ts.map

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

package/dist/test/cli/generate-testcase-paths.test.js

@@ -0,0 +1,165 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import JSON5 from 'json5';
+/**
+ * HOME 隔离 + 预填 projects.index.json5，让 runGenerateTestcase 的 requirement 追加不报错、不污染真实环境。
+ * 仅服务于本文件的路径解析断言；requirement 追加的正确性由 generate-testcase-requirements.test.ts 覆盖。
+ */
+function seedIsolatedHomeWithProject(homeDir, projectDir) {
+    const indexPath = path.join(homeDir, '.ep-stage', 'projects.index.json5');
+    mkdirSync(path.dirname(indexPath), { recursive: true });
+    writeFileSync(indexPath, `${JSON5.stringify({
+        projects: [
+            {
+                projectName: 'test-paths',
+                projectDir,
+                mode: 'glue',
+                stageCreateVersion: '0.0.0-test',
+                requirements: [],
+            },
+        ],
+        systems: [],
+    }, null, 2)}\n`, 'utf8');
+}
+const probe = vi.hoisted(() => ({
+    runProbeAndCoverage: vi.fn(() => ({
+        contract: { contractVersion: 'crud-business-module/v1', module: { id: 'm1', label: '模块' } },
+        testcaseV2: {
+            schemaVersion: 'v2',
+            scenario: 'crud.single-page',
+            moduleId: 'm1',
+            moduleName: '模块',
+            menuPath: '一级>二级',
+            requiredSystems: [{ url: '', systemName: undefined }],
+            requiredRoles: [{ role: 'admin', hint: undefined }],
+            coveredActions: [],
+            uncoveredCandidates: [],
+            cases: [],
+            reasoningSummary: {
+                conclusion: 'ok',
+                evidenceChain: [],
+                alternatives: [],
+                confidence: 'high',
+                risks: [],
+                needsHumanReview: false,
+            },
+        },
+        inferenceTrace: {
+            schemaVersion: 'inference-trace/v1',
+            codeListPath: 'mock',
+            generatedAt: '2026-06-25T00:00:00.000Z',
+            materialInventory: {
+                knowledgeRoot: '',
+                moduleId: { status: 'resolved', value: 'm1' },
+                menu: { status: 'resolved', value: '一级>二级' },
+                htmlFiles: [],
+                javaActionFiles: [],
+                docsFiles: [],
+                missing: [],
+            },
+            sourceAnalysis: {
+                mode: 'inferred',
+                confidence: 'medium',
+                sources: [],
+                fields: [],
+                businessRules: [],
+                uiSignals: [],
+                backendSignals: [],
+                unresolved: [],
+            },
+            moduleHintsInference: {
+                mode: 'inferred',
+                confidence: 'medium',
+                dataKey: { evidence: [] },
+                searchConditions: [],
+                buttonAliases: {},
+                deletePolicy: { evidence: [] },
+                assertionPolicy: {},
+                customWorkflows: [],
+                unresolved: [],
+            },
+            coverageDiff: {
+                coveredActions: [],
+                uncoveredCandidates: [],
+                needsReview: [],
+            },
+            reasoningSummary: {
+                conclusion: 'ok',
+                confidence: 'high',
+                risks: [],
+                needsHumanReview: false,
+            },
+        },
+    })),
+}));
+const softlink = vi.hoisted(() => ({
+    createSoftlinkWithFallback: vi.fn(() => ({ strategy: 'symlink' })),
+}));
+vi.mock('../../src/cli/probe.js', () => probe);
+vi.mock('../../src/util/softlink.js', () => softlink);
+const { runGenerateTestcase } = await import('../../src/cli/generate-testcase.js');
+describe('runGenerateTestcase 路径解析', () => {
+    let tmpDir;
+    let tmpHome;
+    const originalHome = process.env.HOME;
+    beforeEach(() => {
+        tmpDir = mkdtempSync(path.join(os.tmpdir(), 'generate-testcase-paths-'));
+        tmpHome = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-paths-home-'));
+        process.env.HOME = tmpHome;
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        process.env.HOME = originalHome;
+        rmSync(tmpHome, { recursive: true, force: true });
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('根据 code_list.md 的整理目录与物料路径推导 probe 输入，而不是误用 requirementDir', () => {
+        const knowledgeRoot = path.join(tmpDir, 'knowledge-project', 'sample-app');
+        const requirementDir = path.join(knowledgeRoot, '_docs', '014-测试需求10-20260622');
+        const testsDir = path.join(tmpDir, 'project', 'src', 'tests', '014-测试需求10-20260622');
+        const codeListPath = path.join(requirementDir, 'code_list.md');
+        const htmlDir = path.join(knowledgeRoot, 'src', 'main', 'webapp', 'perpage', 'zwplace');
+        const javaDir = path.join(knowledgeRoot, 'src', 'main', 'java', 'com', 'epoint', 'zwplace', 'action');
+        const htmlPath = path.join(htmlDir, 'gxhzwplacelist.html');
+        const javaPath = path.join(javaDir, 'GxhZwPlaceListAction.java');
+        const docsDir = path.join(knowledgeRoot, '_docs', 'zwplace-observable-docs');
+        const docsPath = path.join(docsDir, 'spec.yaml');
+        const hintsPath = path.join(knowledgeRoot, '_docs', 'zwplace.module-hints.json');
+        mkdirSync(requirementDir, { recursive: true });
+        mkdirSync(htmlDir, { recursive: true });
+        mkdirSync(javaDir, { recursive: true });
+        mkdirSync(docsDir, { recursive: true });
+        writeFileSync(htmlPath, '<html></html>\n', 'utf8');
+        writeFileSync(javaPath, 'public class GxhZwPlaceListAction {}\n', 'utf8');
+        writeFileSync(docsPath, 'module:\n  id: zwplace\n', 'utf8');
+        writeFileSync(hintsPath, '{}\n', 'utf8');
+        writeFileSync(codeListPath, `# 测试模块代码清单
+
+> 整理目录：\`${knowledgeRoot}\`
+
+menu: 一级>二级
+
+| 文件路径 |
+|---------|
+| \`_docs/zwplace-observable-docs/spec.yaml\` |
+| \`src/main/webapp/perpage/zwplace/gxhzwplacelist.html\` |
+| \`src/main/java/com/epoint/zwplace/action/GxhZwPlaceListAction.java\` |
+| \`_docs/zwplace.module-hints.json\` |
+`, 'utf8');
+        // HOME 隔离 + 预填 index（projectDir = <tmpDir>/project，与 testsDir 反推一致），避开末尾 requirement 追加校验。
+        seedIsolatedHomeWithProject(tmpHome, path.join(tmpDir, 'project'));
+        runGenerateTestcase({
+            codeList: codeListPath,
+            testsDir,
+            requirementDir,
+        });
+        expect(probe.runProbeAndCoverage).toHaveBeenCalledWith(expect.objectContaining({
+            docsDir,
+            webappDir: htmlDir,
+            javaActionsDir: javaDir,
+            hintsPath,
+        }));
+    });
+});

package/dist/test/cli/generate-testcase-requirements.test.d.ts

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

package/dist/test/cli/generate-testcase-requirements.test.d.ts.map

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

package/dist/test/cli/generate-testcase-requirements.test.js

@@ -0,0 +1,229 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import JSON5 from 'json5';
+// mock probe 避开真实钻探；requirements 追加逻辑不 mock，真实跑。
+const probe = vi.hoisted(() => ({
+    runProbeAndCoverage: vi.fn(() => ({
+        contract: { contractVersion: 'crud-business-module/v1', module: { id: 'm1', label: '模块' } },
+        testcaseV2: {
+            schemaVersion: 'v2',
+            scenario: 'crud.single-page',
+            moduleId: 'm1',
+            moduleName: '模块',
+            menuPath: '一级>二级',
+            requiredSystems: [{ url: '', systemName: undefined }],
+            requiredRoles: [{ role: 'admin', hint: undefined }],
+            coveredActions: [],
+            uncoveredCandidates: [],
+            cases: [],
+            reasoningSummary: {
+                conclusion: 'ok',
+                evidenceChain: [],
+                alternatives: [],
+                confidence: 'high',
+                risks: [],
+                needsHumanReview: false,
+            },
+        },
+        inferenceTrace: {
+            schemaVersion: 'inference-trace/v1',
+            codeListPath: 'mock',
+            generatedAt: '2026-06-26T00:00:00.000Z',
+            materialInventory: {
+                knowledgeRoot: '',
+                moduleId: { status: 'resolved', value: 'm1' },
+                menu: { status: 'resolved', value: '一级>二级' },
+                htmlFiles: [],
+                javaActionFiles: [],
+                docsFiles: [],
+                missing: [],
+            },
+            sourceAnalysis: {
+                mode: 'inferred',
+                confidence: 'medium',
+                sources: [],
+                fields: [],
+                businessRules: [],
+                uiSignals: [],
+                backendSignals: [],
+                unresolved: [],
+            },
+            moduleHintsInference: {
+                mode: 'inferred',
+                confidence: 'medium',
+                dataKey: { evidence: [] },
+                searchConditions: [],
+                buttonAliases: {},
+                deletePolicy: { evidence: [] },
+                assertionPolicy: {},
+                customWorkflows: [],
+                unresolved: [],
+            },
+            coverageDiff: {
+                coveredActions: [],
+                uncoveredCandidates: [],
+                needsReview: [],
+            },
+            reasoningSummary: {
+                conclusion: 'ok',
+                confidence: 'high',
+                risks: [],
+                needsHumanReview: false,
+            },
+        },
+    })),
+}));
+const softlink = vi.hoisted(() => ({
+    createSoftlinkWithFallback: vi.fn(() => ({ strategy: 'symlink' })),
+}));
+vi.mock('../../src/cli/probe.js', () => probe);
+vi.mock('../../src/util/softlink.js', () => softlink);
+const { runGenerateTestcase } = await import('../../src/cli/generate-testcase.js');
+const REQUIREMENT_NAME = '014-测试需求10-20260622';
+/**
+ * 构造一组能让 resolveProbeInputsFromCodeList 成功的最小物料 fixture
+ * （复用 generate-testcase-paths.test.ts 验证过的目录结构）。
+ */
+function buildMaterialFixture(workDir) {
+    const knowledgeRoot = path.join(workDir, 'knowledge-project', 'sample-app');
+    const requirementDir = path.join(knowledgeRoot, '_docs', REQUIREMENT_NAME);
+    const codeListPath = path.join(requirementDir, 'code_list.md');
+    const htmlDir = path.join(knowledgeRoot, 'src', 'main', 'webapp', 'perpage', 'zwplace');
+    const javaDir = path.join(knowledgeRoot, 'src', 'main', 'java', 'com', 'epoint', 'zwplace', 'action');
+    const htmlPath = path.join(htmlDir, 'gxhzwplacelist.html');
+    const javaPath = path.join(javaDir, 'GxhZwPlaceListAction.java');
+    const docsDir = path.join(knowledgeRoot, '_docs', 'zwplace-observable-docs');
+    const docsPath = path.join(docsDir, 'spec.yaml');
+    const hintsPath = path.join(knowledgeRoot, '_docs', 'zwplace.module-hints.json');
+    mkdirSync(requirementDir, { recursive: true });
+    mkdirSync(htmlDir, { recursive: true });
+    mkdirSync(javaDir, { recursive: true });
+    mkdirSync(docsDir, { recursive: true });
+    writeFileSync(htmlPath, '<html></html>\n', 'utf8');
+    writeFileSync(javaPath, 'public class GxhZwPlaceListAction {}\n', 'utf8');
+    writeFileSync(docsPath, 'module:\n  id: zwplace\n', 'utf8');
+    writeFileSync(hintsPath, '{}\n', 'utf8');
+    writeFileSync(codeListPath, `# 测试模块代码清单
+
+> 整理目录：\`${knowledgeRoot}\`
+
+menu: 一级>二级
+
+| 文件路径 |
+|---------|
+| \`_docs/zwplace-observable-docs/spec.yaml\` |
+| \`src/main/webapp/perpage/zwplace/gxhzwplacelist.html\` |
+| \`src/main/java/com/epoint/zwplace/action/GxhZwPlaceListAction.java\` |
+| \`_docs/zwplace.module-hints.json\` |
+`, 'utf8');
+    return { codeListPath, requirementDir };
+}
+/**
+ * 在临时 HOME 下造一个最小可用的 projects.index.json5（含一条 project + 一条 system），
+ * 用于验证 requirements 追加不丢 systems。
+ */
+function seedIndex(homeDir, projectDir) {
+    const indexPath = path.join(homeDir, '.ep-stage', 'projects.index.json5');
+    mkdirSync(path.dirname(indexPath), { recursive: true });
+    writeFileSync(indexPath, `${JSON5.stringify({
+        projects: [
+            {
+                projectName: 'demo-glue',
+                projectDir,
+                mode: 'glue',
+                stageCreateVersion: '0.0.0-test',
+                requirements: [],
+            },
+        ],
+        systems: [
+            {
+                url: 'http://demo.example.com',
+                knownRoles: ['admin'],
+                credentialsCache: {
+                    admin: {
+                        username: 'demo',
+                        password: 'secret',
+                        lastUsed: '2026-06-26T00:00:00.000Z',
+                    },
+                },
+            },
+        ],
+    }, null, 2)}\n`, 'utf8');
+}
+function readIndex(homeDir) {
+    const indexPath = path.join(homeDir, '.ep-stage', 'projects.index.json5');
+    return JSON5.parse(readFileSync(indexPath, 'utf8'));
+}
+describe('runGenerateTestcase 追加 requirement 到 projects.index', () => {
+    let tmpHome;
+    let tmpWork;
+    const originalHome = process.env.HOME;
+    beforeEach(() => {
+        tmpHome = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-req-home-'));
+        tmpWork = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-req-work-'));
+        // 关键：HOME 隔离，绝对不污染真实 ~/.ep-stage
+        process.env.HOME = tmpHome;
+        vi.clearAllMocks();
+    });
+    afterEach(() => {
+        process.env.HOME = originalHome;
+        rmSync(tmpHome, { recursive: true, force: true });
+        rmSync(tmpWork, { recursive: true, force: true });
+    });
+    it('跑完后向对应 project.requirements 追加一条 name=<basename(testsDir)>, lastRunStatus=never', () => {
+        const { codeListPath, requirementDir } = buildMaterialFixture(tmpWork);
+        const projectDir = path.join(tmpWork, 'glue-project');
+        const testsDir = path.join(projectDir, 'src', 'tests', REQUIREMENT_NAME);
+        seedIndex(tmpHome, projectDir);
+        runGenerateTestcase({ codeList: codeListPath, testsDir, requirementDir, projectDir });
+        const index = readIndex(tmpHome);
+        const project = index.projects[0];
+        expect(project.projectDir).toBe(projectDir);
+        expect(project.requirements).toHaveLength(1);
+        const req = project.requirements[0];
+        expect(req.name).toBe(REQUIREMENT_NAME);
+        expect(req.testsDir).toBe(testsDir);
+        expect(req.requirementDir).toBe(requirementDir);
+        expect(req.lastRunStatus).toBe('never');
+    });
+    it('重跑同名需求不重复追加（去重更新）', () => {
+        const { codeListPath, requirementDir } = buildMaterialFixture(tmpWork);
+        const projectDir = path.join(tmpWork, 'glue-project');
+        const testsDir = path.join(projectDir, 'src', 'tests', REQUIREMENT_NAME);
+        seedIndex(tmpHome, projectDir);
+        runGenerateTestcase({ codeList: codeListPath, testsDir, requirementDir, projectDir });
+        runGenerateTestcase({ codeList: codeListPath, testsDir, requirementDir, projectDir });
+        const index = readIndex(tmpHome);
+        const project = index.projects[0];
+        expect(project.requirements).toHaveLength(1);
+    });
+    it('不丢 systems（整体覆写后 systems 仍在）', () => {
+        const { codeListPath, requirementDir } = buildMaterialFixture(tmpWork);
+        const projectDir = path.join(tmpWork, 'glue-project');
+        const testsDir = path.join(projectDir, 'src', 'tests', REQUIREMENT_NAME);
+        seedIndex(tmpHome, projectDir);
+        runGenerateTestcase({ codeList: codeListPath, testsDir, requirementDir, projectDir });
+        const index = readIndex(tmpHome);
+        expect(index.systems).toHaveLength(1);
+        const sys = index.systems[0];
+        expect(sys.url).toBe('http://demo.example.com');
+        expect(sys.credentialsCache.admin.username).toBe('demo');
+    });
+    it('projectDir 不在 index 时抛中文错误并引导先跑 /glue-create-project', () => {
+        const { codeListPath, requirementDir } = buildMaterialFixture(tmpWork);
+        const projectDir = path.join(tmpWork, 'unknown-project');
+        const testsDir = path.join(projectDir, 'src', 'tests', REQUIREMENT_NAME);
+        // seed 的是另一个 projectDir
+        seedIndex(tmpHome, path.join(tmpWork, 'another-project'));
+        expect(() => runGenerateTestcase({ codeList: codeListPath, testsDir, requirementDir, projectDir })).toThrowError(/未在.*projects\.index\.json5.*glue-create-project/u);
+    });
+    it('index 文件不存在时也按 projectDir 不在 index 处理并抛中文错误', () => {
+        const { codeListPath, requirementDir } = buildMaterialFixture(tmpWork);
+        const projectDir = path.join(tmpWork, 'glue-project');
+        const testsDir = path.join(projectDir, 'src', 'tests', REQUIREMENT_NAME);
+        // 不 seedIndex，连 index 文件都不存在
+        expect(() => runGenerateTestcase({ codeList: codeListPath, testsDir, requirementDir, projectDir })).toThrowError(/未在.*projects\.index\.json5.*glue-create-project/u);
+    });
+});

package/dist/test/cli/index.test.js

@@ -9,6 +9,10 @@
  * 用 vi.mock 替换 generate-testcase / spec / run 模块，避免占位 throw 干扰路由判定。
  */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, symlinkSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
 const generateTestcase = vi.hoisted(() => ({
     parseGenerateTestcaseArgs: vi.fn((argv) => ({ codeList: 'parsed', testsDir: argv.join(' ') })),
     runGenerateTestcase: vi.fn(() => 'TESTCASE_OK'),
@@ -90,4 +94,20 @@ describe('ep-stage-skill CLI 路由', () => {
         await main(['node', 'cli', 'testcase', '--', '--code-list', '/x']);
         expect(generateTestcase.parseGenerateTestcaseArgs).toHaveBeenCalledWith(['--code-list', '/x']);
     });
+    it('软链 CLI 入口也应识别为直接执行', async () => {
+        const mod = await import('../../src/cli/index.js');
+        const tmpDir = mkdtempSync(path.join(os.tmpdir(), 'ep-stage-skill-cli-'));
+        const realEntry = path.join(tmpDir, 'dist', 'src', 'cli', 'index.js');
+        const binEntry = path.join(tmpDir, '.bin', 'ep-stage-skill');
+        try {
+            mkdirSync(path.dirname(realEntry), { recursive: true });
+            mkdirSync(path.dirname(binEntry), { recursive: true });
+            writeFileSync(realEntry, '// mock cli entry\n', 'utf8');
+            symlinkSync(realEntry, binEntry);
+            expect(mod.isDirectExecution(pathToFileURL(realEntry).href, binEntry)).toBe(true);
+        }
+        finally {
+            rmSync(tmpDir, { recursive: true, force: true });
+        }
+    });
 });

package/dist/test/cli/probe.test.d.ts

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

package/dist/test/cli/probe.test.d.ts.map

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

package/dist/test/cli/probe.test.js

@@ -0,0 +1,31 @@
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { runProbeAndCoverage } from '../../src/cli/probe.js';
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../../../..');
+const knowledgeRoot = join(repoRoot, 'knowledge-project/epoint-web-v9.5.2');
+const requirementDir = join(knowledgeRoot, '_docs/014-测试需求10-20260622');
+const codeListPath = join(requirementDir, 'code_list.md');
+const webappDir = join(knowledgeRoot, 'src/main/webapp/perpage/zwplace');
+const javaActionsDir = join(knowledgeRoot, 'src/main/java/com/epoint/zwplace/action');
+describe('runProbeAndCoverage spec fallback', () => {
+    it('在 code_list 缺少 spec.yaml 与 module-hints 时，仍能基于 HTML/Java 生成可审阅 testcase', () => {
+        const result = runProbeAndCoverage({
+            moduleId: 'zwplace',
+            codeListPath,
+            docsDir: requirementDir,
+            webappDir,
+            javaActionsDir,
+            scenario: 'crud.single-page',
+        });
+        expect(result.contract.dataKey.field).toBe('placename');
+        expect(result.contract.searchConditions?.[0]?.field).toBe('placename');
+        // 推理 hints 流入后，dataKey 已解析为 placename；unresolvedSlots 只剩非 dataKey 项。
+        expect(result.contract.unresolvedSlots.map((slot) => slot.slotId)).not.toContain('dataKey.selectedField');
+        expect(result.testcaseV2.moduleId).toBe('zwplace');
+        expect(result.testcaseV2.cases).toHaveLength(4);
+        // Task 3: inference trace 随 probe 返回。
+        expect(result.inferenceTrace.schemaVersion).toBe('inference-trace/v1');
+        expect(result.inferenceTrace.moduleHintsInference.dataKey.selectedField).toBe('placename');
+    });
+});

package/dist/test/cli/spec-boundary.test.d.ts

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

package/dist/test/cli/spec-boundary.test.d.ts.map

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