@kkeve/suite 0.0.1 → 0.0.3

package/dist/page-agent/tools.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * page-agent tools — Playwright-native action tools
+ *
+ * Design: Each tool has independent inputSchema + execute.
+ * Tools are registered in a Map, then packed into a MacroTool for LLM invocation.
+ *
+ * Element targeting: aria-ref via page.locator('aria-ref=xxx')
+ * - mode:'ai' snapshot provides [ref=f5e13] identifiers
+ * - aria-ref selector automatically penetrates iframe boundaries
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tools = void 0;
+exports.tool = tool;
+exports.getZodShape = getZodShape;
+exports.packMacroToolSchema = packMacroToolSchema;
+const zod_1 = require("zod");
+function tool(options) {
+    return options;
+}
+// ─── Tool Registry ────────────────────────────────────────────────────
+exports.tools = new Map();
+// --- done ---
+exports.tools.set('done', tool({
+    description: 'Complete the task with a test conclusion. Use this when the expected state is achieved, not achieved, or you are blocked.',
+    inputSchema: zod_1.z.object({
+        verdict: zod_1.z.enum(['pass', 'fail', 'blocked']).describe('Test verdict: "pass"=expected state achieved; "fail"=page accessible but expected not met; "blocked"=cannot continue (SSO, connection refused, etc.)'),
+        text: zod_1.z.string().describe('Summary of what was achieved, why it failed, or why blocked'),
+    }),
+    execute: async function (input) {
+        const icons = { pass: '✅', fail: '❌', blocked: '🚫' };
+        let verdict = input.verdict;
+        // 强制校验：verdict 缺失或非法时从 text 推断（MacroTool 扁平化导致 verdict 变 optional）
+        if (!icons[verdict]) {
+            console.warn(`[done] ⚠️ verdict missing or invalid ("${input.verdict}"), inferring from text`);
+            const t = String(input.text || '').toLowerCase();
+            if (t.includes('fail') || t.includes('failure') || t.includes('失败') || t.includes('不通过') || t.includes('未通过')) {
+                verdict = 'fail';
+            }
+            else if (t.includes('blocked') || t.includes('阻塞') || t.includes('阻止')) {
+                verdict = 'blocked';
+            }
+            else {
+                verdict = 'pass'; // 有 text 且无否定词 → 默认 pass
+            }
+        }
+        return `${icons[verdict]} Task ${verdict}: ${input.text}`;
+    },
+}));
+// --- click ---
+exports.tools.set('click', tool({
+    description: 'Click an element by its ref identifier from the accessibility tree. The aria-ref selector automatically penetrates iframe boundaries.',
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().describe('Element ref from the accessibility tree, e.g. "f5e13"'),
+    }),
+    execute: async function (input) {
+        const locator = this.page.locator(`aria-ref=${input.ref}`);
+        await locator.click({ timeout: 5000, force: true });
+        return `✅ Clicked element [ref=${input.ref}]`;
+    },
+}));
+// --- type ---
+exports.tools.set('type', tool({
+    description: 'Type text into an input element by its ref identifier. Clears existing content first. The aria-ref selector automatically penetrates iframe boundaries.',
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().describe('Element ref from the accessibility tree, e.g. "f5e91"'),
+        text: zod_1.z.string().describe('Text to type into the element'),
+        submit: zod_1.z.boolean().optional().describe('Whether to press Enter after typing'),
+    }),
+    execute: async function (input) {
+        const locator = this.page.locator(`aria-ref=${input.ref}`);
+        await locator.fill(input.text, { timeout: 5000, force: true });
+        if (input.submit)
+            await this.page.keyboard.press('Enter');
+        return `✅ Typed "${input.text.slice(0, 50)}" into element [ref=${input.ref}]${input.submit ? ' + Enter' : ''}`;
+    },
+}));
+// --- hover ---
+exports.tools.set('hover', tool({
+    description: 'Hover over an element by its ref identifier. The aria-ref selector automatically penetrates iframe boundaries.',
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().describe('Element ref from the accessibility tree, e.g. "f5e13"'),
+    }),
+    execute: async function (input) {
+        const locator = this.page.locator(`aria-ref=${input.ref}`);
+        await locator.hover({ timeout: 5000, force: true });
+        return `✅ Hovered over element [ref=${input.ref}]`;
+    },
+}));
+// --- pressKey ---
+exports.tools.set('pressKey', tool({
+    description: 'Press a keyboard key (Enter, Escape, Tab, ArrowDown, etc.)',
+    inputSchema: zod_1.z.object({
+        key: zod_1.z.string().describe('Key to press: Enter, Escape, Tab, ArrowDown, etc.'),
+    }),
+    execute: async function (input) {
+        await this.page.keyboard.press(input.key);
+        return `✅ Pressed key "${input.key}"`;
+    },
+}));
+// --- scroll ---
+exports.tools.set('scroll', tool({
+    description: 'Scroll the page vertically. Use when target content is off-screen.',
+    inputSchema: zod_1.z.object({
+        direction: zod_1.z.enum(['down', 'up']).default('down').describe('Scroll direction'),
+        amount: zod_1.z.number().optional().describe('Scroll amount in pixels (default 500)'),
+    }),
+    execute: async function (input) {
+        const pixels = input.amount ?? 500;
+        const dir = input.direction === 'down' ? 1 : -1;
+        await this.page.mouse.wheel(0, pixels * dir);
+        return `✅ Scrolled ${input.direction} ${pixels}px`;
+    },
+}));
+// --- wait ---
+exports.tools.set('wait', tool({
+    description: 'Wait for a specified duration (in milliseconds). Use when page is loading.',
+    inputSchema: zod_1.z.object({
+        time: zod_1.z.number().min(100).max(10000).describe('Wait time in milliseconds'),
+    }),
+    execute: async function (input) {
+        await this.page.waitForTimeout(input.time);
+        return `✅ Waited ${input.time}ms`;
+    },
+}));
+// --- navigate ---
+exports.tools.set('navigate', tool({
+    description: 'Navigate to a URL. Use KEVE_TARGET_URL (from test-cases.yaml principle) for the main application page. For other pages, use URLs from envVars (e.g., process.env.PAGE_KNOWLEDGE). Do NOT construct or guess URLs yourself.',
+    inputSchema: zod_1.z.object({
+        url: zod_1.z.string().describe('URL to navigate to. Use process.env.KEVE_TARGET_URL for the main page, or envVars for other declared pages. Supports absolute URLs or relative paths starting with /'),
+    }),
+    execute: async function (input) {
+        let url = input.url;
+        if (!url.startsWith('http://') && !url.startsWith('https://')) {
+            const base = process.env.KEVE_TARGET_URL || process.env.BASE_URL || '';
+            url = new URL(url, base).href;
+        }
+        await this.page.goto(url, { waitUntil: 'networkidle', timeout: 15000 });
+        return `✅ Navigated to ${url}`;
+    },
+}));
+// --- execute_javascript ---
+exports.tools.set('execute_javascript', tool({
+    description: 'READ-ONLY query tool: execute JavaScript in the BROWSER DOM context to retrieve precise values that screenshots and accessibility trees CANNOT provide — such as computed CSS styles (getComputedStyle), DOM measurements (offsetWidth, getBoundingClientRect), or element properties (checked, disabled, value).\n\n⚠️ EXECUTION CONTEXT: This runs inside the browser page via page.evaluate — it is a plain browser JavaScript sandbox. There is NO `page` object, NO Playwright API, NO `locator`, NO top-level `await`. Using `page.locator(...)`, `page.evaluate(...)`, `await`, or `async () => {}` wrappers will cause SyntaxError or return undefined.\n\nDo NOT use for: clicking, typing, navigating, form filling, or any page interaction — use click/type/navigate tools instead. Do NOT use for: assertions or logical checks — just return the raw value, you judge the result yourself. Do NOT use for: modifying page state (setting styles, cookies, localStorage, DOM mutations).',
+    inputSchema: zod_1.z.object({
+        script: zod_1.z.string().describe("JavaScript code to execute inside the browser DOM. MUST start with `return` to capture the result. Use `var` for variable declarations (NOT `const`/`let` — they cause SyntaxError in some evaluate contexts). Only browser DOM APIs: document.querySelector, window.getComputedStyle, etc.\n\n✅ Correct: 'return document.querySelector(\".x\").innerText'\n✅ Correct: 'var el = document.querySelector(\".x\"); return window.getComputedStyle(el).backgroundColor'\n❌ Wrong: 'page.locator(\".x\")' — no Playwright `page` object in browser context\n❌ Wrong: 'await page.locator(...)' — no `await` or `async`\n❌ Wrong: 'const el = ...' — use `var` instead of `const`/`let`\n❌ Wrong: 'async () => { ... }' — do NOT wrap in async function, returns undefined\n\nRead-only queries only."),
+    }),
+    execute: async function (input) {
+        try {
+            let script = input.script.trim();
+            // Auto-unwrap arrow function wrappers that Agent frequently generates:
+            //   async () => { ... return ... }  →  ... return ...
+            //   () => { ... return ... }        →  ... return ...
+            //   (async () => { ... })()        →  ... return ...
+            // These wrappers cause page.evaluate to return undefined because the
+            // arrow function is created but never invoked inside the IIFE.
+            const arrowMatch = script.match(/^(?:async\s+)?(?:\(\s*\)\s*|)\s*=>\s*\{([\s\S]*)\}\s*;?\s*$/);
+            if (arrowMatch) {
+                script = arrowMatch[1].trim();
+            }
+            // Also strip IIFE self-call: (async () => { ... })()
+            const iifeMatch = script.match(/^\(\s*(?:async\s+)?\(\s*\)\s*=>\s*\{([\s\S]*)\}\s*\)\s*\(\s*\)\s*;?\s*$/);
+            if (iifeMatch) {
+                script = iifeMatch[1].trim();
+            }
+            // Read-only guard: block DOM mutation APIs to prevent Agent from altering page state.
+            const writePatterns = [
+                /\b(?:document|element|el|node)\.\s*(?:remove|appendChild|insertBefore|replaceChild|removeChild|appendChild)\s*\(/,
+                /\b(?:document|element|el|node)\.\s*(?:innerHTML|outerHTML|textContent|innerText)\s*=/,
+                /\b(?:document|element|el|node)\.\s*(?:setAttribute|removeAttribute|classList)\s*\./,
+                /\b\.style\s*\.\s*\w+\s*=/,
+                /\blocation\s*(?:\.href\s*=|\.assign\s*\(|\.replace\s*\()/,
+                /\bwindow\s*\.\s*(?:close|stop|open)\s*\(/,
+                /\bdocument\.\s*(?:write|writeln|execCommand)\s*\(/,
+                /\blocalStorage\s*\.\s*set\s*\(/,
+                /\bsessionStorage\s*\.\s*set\s*\(/,
+                /\bdocument\.cookie\s*=/,
+                /\beval\s*\(/,
+            ];
+            for (const pattern of writePatterns) {
+                if (pattern.test(script)) {
+                    return `❌ JS execution blocked: write/mutation API detected. execute_javascript is read-only. Use click/type/navigate tools for interactions.`;
+                }
+            }
+            // Require explicit `return` — no auto-wrapping.
+            // Wrap in IIFE so `return` is valid (page.evaluate treats bare strings as expressions).
+            if (!/\breturn\b/.test(script)) {
+                return `❌ Script must start with 'return' to capture the result. Example: "return window.getComputedStyle(document.body).backgroundColor"`;
+            }
+            const wrapped = `(function() { ${script} })()`;
+            const result = await this.page.evaluate(wrapped);
+            const output = typeof result === 'object' && result !== null
+                ? JSON.stringify(result, null, 2)
+                : String(result ?? 'undefined');
+            return `✅ JS executed. Result: ${output}`;
+        }
+        catch (err) {
+            return `❌ JS execution error: ${err.message || String(err)}`;
+        }
+    },
+}));
+// --- visual_locate ---
+exports.tools.set('visual_locate', tool({
+    description: 'Locate and click an element by visual analysis of a screenshot. FALLBACK: only use after `click` fails 2+ times on the same element (non-standard ARIA role, invisible in accessibility tree, or element visible in screenshot but missing from accessibility tree). Provide a concise visual description of the element. It will screenshot the page, send it to a multimodal LLM to locate the element, then click at the predicted coordinates. After clicking, verify the effect on the next screenshot.',
+    inputSchema: zod_1.z.object({
+        description: zod_1.z.string().describe('Visual description of the element to find, e.g. "the dropdown button showing 当前Agent▼"'),
+    }),
+    execute: async function (input) {
+        // 1. Capture screenshot
+        let screenshotBase64;
+        try {
+            const buf = await this.page.screenshot({ type: 'png', timeout: 10000 });
+            screenshotBase64 = buf.toString('base64');
+        }
+        catch (e) {
+            throw new Error(`visual_locate screenshot failed: ${e.message}`);
+        }
+        // 2. Call LLM for visual element location
+        const locateResult = await this.visualLocateElement(screenshotBase64, input.description);
+        if (!locateResult.found || !locateResult.bbox || locateResult.bbox.length !== 4) {
+            return `❌ Visual locate failed: element "${input.description}" not found. ${locateResult.analysis || ''}`;
+        }
+        // 3. Convert normalized bbox (0-1000) to viewport pixel coordinates
+        const viewport = this.page.viewportSize() || { width: 1280, height: 720 };
+        const [x1, y1, x2, y2] = locateResult.bbox;
+        const centerX = Math.round(((x1 + x2) / 2) * viewport.width / 1000);
+        const centerY = Math.round(((y1 + y2) / 2) * viewport.height / 1000);
+        // 4. Click at coordinates (bypasses iframe boundaries)
+        await this.page.mouse.click(centerX, centerY);
+        return `✅ Visual locate & click: "${input.description}" at (${centerX}, ${centerY})`;
+    },
+}));
+// ── verify_expected fully removed (Phase 6) ──
+// LLM now sees screenshots via multimodal prompt and self-evaluates.
+// No separate verification tool or function needed — each step's screenshot
+// is injected into the LLM prompt directly, so LLM judges goal state itself.
+// ─── Zod schema helper (used by packMacroToolSchema & MacroTool execute) ──
+function getZodShape(schema) {
+    const def = schema?._def;
+    if (!def)
+        return schema?.shape || {};
+    const s = def.shape;
+    return typeof s === 'function' ? s() : (s || schema?.shape || {});
+}
+// ─── Pack tools into MacroTool schema for LLM ────────────────────────
+// Auto-derive flat schema from tools Map (like page-agent's #packMacroTool).
+// Key insight: z.union() is UNSTABLE with keve-core's safeParse.
+// Solution: merge all tool inputSchema fields into one flat object with `tool` enum.
+function packMacroToolSchema() {
+    // Collect tool names for enum
+    const toolNames = Array.from(exports.tools.keys());
+    // Collect all unique fields from all tool schemas
+    const fieldMap = new Map();
+    for (const [name, t] of exports.tools.entries()) {
+        // Unwrap ZodObject to get its shape
+        const shape = getZodShape(t.inputSchema);
+        for (const [key, val] of Object.entries(shape)) {
+            if (!fieldMap.has(key)) {
+                // First encounter — store the schema and add tool names to description
+                const zodField = val;
+                const desc = zodField._def?.description || '';
+                fieldMap.set(key, { schema: zodField.optional(), description: desc });
+            }
+            // If field already exists, just ensure description mentions both tools
+        }
+    }
+    // Build the flat schema
+    const reflectionFields = {
+        evaluation_previous_goal: zod_1.z.string().optional()
+            .describe('Concise one-sentence analysis of your last action. State success, failure, or uncertain.'),
+        memory: zod_1.z.string().optional()
+            .describe('1-3 concise sentences of key observations that will help in future steps.'),
+        next_goal: zod_1.z.string().optional()
+            .describe('State the next immediate goal and action to achieve it.'),
+    };
+    const actionFields = {
+        tool: zod_1.z.enum(toolNames).describe('The action tool to use'),
+    };
+    // Add all tool fields as optional
+    for (const [key, { schema, description }] of fieldMap.entries()) {
+        // Make all fields optional + add which tools use this field
+        const usedBy = Array.from(exports.tools.entries())
+            .filter(([_, t]) => {
+            const shape = getZodShape(t.inputSchema);
+            return key in shape;
+        })
+            .map(([name]) => name);
+        const enrichedDesc = usedBy.length > 1
+            ? `${description} (for ${usedBy.join('/')})`
+            : description;
+        actionFields[key] = schema.describe(enrichedDesc);
+    }
+    return zod_1.z.object({
+        ...reflectionFields,
+        ...actionFields,
+    }).passthrough(); // Allow extra LLM fields for stability
+}

package/doc/README.md

@@ -0,0 +1,124 @@
+标准测试金字塔（Martin Fowler / Mike Cohn 经典模型）
+                    ▲
+                   ╱ ╲
+                  ╱   ╲
+                 ╱ E2E ╲          ← 少量：跨页面完整用户旅程
+                ╱ 测试   ╲            运行慢、成本高、脆弱
+               ╱━━━━━━━━━╲
+              ╱           ╲
+             ╱  集成测试    ╲       ← 中量：模块间交互、API 调用
+            ╱  (Integration) ╲         模拟依赖、验证契约
+           ╱━━━━━━━━━━━━━━━━━╲
+          ╱                   ╲
+         ╱    单元测试          ╲     ← 大量：纯函数、工具方法
+        ╱    (Unit Test)        ╲        毫秒级、确定性、低成本
+       ╱━━━━━━━━━━━━━━━━━━━━━━━━╲
+      ╱                         ╲
+     ╱     静态分析 (Static)       ╲   ← 最底层：TypeScript、ESLint、Prettier
+    ╱━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╲      不运行代码、零成本、实时反馈
+
+原则：越底层越多、越快、越稳定；越顶层越少、越慢、越脆弱。
+
+
+前端测试金字塔（细化版）
+对于前端项目，经典三层太粗，需要细化：
+                         ▲
+                        ╱ ╲
+                       ╱   ╲
+                      ╱ E2E ╲              ← Playwright/Cypress
+                     ╱ 测试    ╲               跨页面用户旅程
+                    ╱━━━━━━━━━━╲                5~10 条
+                   ╱            ╲
+                  ╱  视觉回归    ╲           ← 截图对比
+                 ╱  (Visual)      ╲             UI 一致性
+                ╱━━━━━━━━━━━━━━━━╲
+               ╱                  ╲
+              ╱   组件集成测试      ╲         ← Testing Library
+             ╱   (Integration)      ╲           组件 + 子组件 + Store
+            ╱━━━━━━━━━━━━━━━━━━━━━━╲             模拟 API、验证交互流
+           ╱                        ╲
+          ╱      组件单元测试          ╲       ← Vitest + Vue Test Utils
+         ╱      (Component Unit)       ╲         孤立组件、mock 依赖
+        ╱━━━━━━━━━━━━━━━━━━━━━━━━━━━━╲           Props in → 渲染 out
+       ╱                              ╲
+      ╱       纯函数单元测试             ╲     ← Vitest
+     ╱       (Pure Unit)                 ╲       utils / hooks / store
+    ╱━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╲      无 DOM 依赖
+   ╱                                      ╲
+  ╱          静态分析 (Static)              ╲  ← TypeScript + ESLint
+ ╱━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╲    编译期捕获类型/规范错误
+
+Kent C. Dodds 的"测试奖杯"模型
+前端社区更流行的其实是 Testing Trophy，因为前端 E2E 成本极高，集成测试才是 ROI 最高的层次。
+              🏆
+             ╱ ╲
+            ╱E2E╲              ← 极少：仅冒烟 / 关键路径
+           ╱━━━━━╲               3~5 
+           条
+          ╱       ╲
+         ╱ 集成测试 ╲           ← 最多：组件集成 + API mock
+        ╱ (Integration) ╲         ROI 最高、信心最强
+       ╱━━━━━━━━━━━━━━━━╲
+      ╱                  ╲
+     ╱    单元测试          ╲     ← 补充：纯逻辑、边界条件
+    ╱    (Unit)             ╲       快但不验证用户行为
+   ╱━━━━━━━━━━━━━━━━━━━━━━━━╲
+  ╱                          ╲
+ ╱      静态分析 (Static)      ╲  ← 基座：零成本捕获大量错误
+╱━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╲
+
+核心区别：奖杯模型中集成测试最宽（而非单元测试最宽），因为：
+- 单元测试只验证"零件"，集成测试验证"装配"
+- 前端 bug 多出在组件协作、API 对接、状态管理，而非纯函数逻辑
+- 集成测试的信心度远高于单元测试（更接近真实使用）
+
+
+当前keve-agent生成的那就应该是前端集成测试（Integration Test）
+
+传统 E2E（后端视角）：
+  用户浏览器 ──────────────────────────────→ 数据库
+  ┃          前端          API         后端       ┃
+  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+  "端到端" = 从用户操作到数据库落盘，全链路
+
+keve-agent 做的测试（前端视角）：
+  用户浏览器 ─────────→ 前端 devServer
+  ┃          前端           ┃
+  ┗━━━━━━━━━━━━━━━━━━━━━━━━┛
+  "端" = 只到前端渲染层，后端是 mock/stub
+
+
+
+┌────────────────────────────────────────────────────────────────────────┐
+│                    静态分析能力谱（三阶段）                             │
+├─────────────┬─────────────────────────────────────────────────────────┤
+│  Phase 1    │  tsc 类型检查 + eslint 规范（P0 必修，自动修复）         │
+│  tsc+eslint  │                                                        │
+│             │  ✅ 类型不匹配、缺失属性、隐式 any、缺失导入            │
+│             │  ✅ 可空类型误用、未使用变量/参数                        │
+│             │  ✅ 缺失依赖项、等号误赋值、console.log                  │
+│             │  ✅ 缺失返回值、一致性规范（命名/排序）                  │
+├─────────────┼─────────────────────────────────────────────────────────┤
+│  Phase 2    │  Code-Graph 关系分析（P1 建议修，只输出不自动改）       │
+│  Code-Graph │                                                        │
+│  (Tree-sitter)│ ✅ 循环依赖检测（A→B→C→A）                          │
+│             │  ✅ 幽灵依赖检测（import 了但 package.json 没声明）      │
+│             │  ✅ 死代码检测（无调用者的非导出函数）                  │
+│             │  ✅ 架构层级违规（utils 不应 import components）        │
+│             │  ✅ 变更影响范围（改了函数 X，哪些模块受影响）          │
+├─────────────┼─────────────────────────────────────────────────────────┤
+│  Phase 3    │  Git 变更分析（P2 信息参考，不自动改）                  │
+│  Git 分析    │                                                        │
+│             │  ✅ 当前 diff 修改了哪些文件/函数                       │
+│             │  ✅ 变更影响范围（结合 Phase 2 计算受影响的调用链）     │
+│             │  ✅ 热点文件（30天内高频变更 = 不稳定区域）            │
+│             │  ✅ 新增文件（可能缺少测试覆盖）                        │
+├─────────────┼─────────────────────────────────────────────────────────┤
+│  ❌ 未覆盖   │  安全漏洞 → keve-static-analysis Phase 4（已规划）        │
+│             │    XSS/SQL注入/ReDoS/硬编码敏感信息/npm audit        │
+│             │  运行时风险 → Phase 4（已规划）                       │
+│             │    内存泄漏/事件监听器未移除/Promise rejection        │
+│             │  代码克隆 → Code-Graph AST 比对 + AI 模式匹配（可覆盖）│
+│             │  圈/认知复杂度 → Code-Graph 获取函数体 + AI 计算决策点  │
+│             │  → 大部分未覆盖项可通过 Code-Graph + AI 间接覆盖       │
+└─────────────┴─────────────────────────────────────────────────────────┘

package/doc/agents/keve-dev-test-agent.md

@@ -0,0 +1,140 @@
+---
+name: keve-dev-test-agent
+description: 开发阶段测试流水线编排代理。协调 static-analysis → unit-gen → component-gen 三技能按序执行，支持阶段检测、断点续跑、覆盖率摘要输出。
+tools:
+  - Bash(shell:*)
+  - Bash(npx:*)
+  - Bash(npm:*)
+  - Bash(node:*)
+  - Bash(git:*)
+---
+
+# KEVE 开发阶段测试编排代理
+
+> 本代理是**薄编排层**，负责：检测起点、创建执行计划、调度技能、输出覆盖率摘要。
+> 不包含技能细节——不做类型修复、不写测试脚本、不做组件分析。
+
+## 触发方式
+
+用户输入 `/keve-dev-test` 指令触发，跳过意图识别直接进入本流程。
+
+适用场景：**开发阶段**，需要快速反馈（秒级），不涉及 E2E 测试。
+
+---
+
+## 整体流程
+
+```
+1. 阶段检测 → 确定触发模式（dev），创建 test-plan.yaml
+2. 调度 keve-static-analysis → 修类型/lint 错误
+3. 调度 keve-unit-gen → 生成单测 + coverage.yaml
+4. 调度 keve-component-gen → 生成组件模型 + 组件测试 + coverage.yaml
+5. 输出覆盖率摘要 + 缺口列表
+```
+
+---
+
+## 阶段检测
+
+### Step 0: 读取或创建 test-plan.yaml
+
+1. **已有 test-plan.yaml**：
+   - 读取 `context.trigger` 和各 phase.status
+   - 输出："检测到已有执行计划，当前进度："
+   - 列出各阶段状态（✅ completed / 🔄 in_progress / ⏳ pending / ⏭️ skipped）
+   - 询问用户："从断点继续 / 重新开始？"
+
+2. **无 test-plan.yaml**：
+   - 根据 trigger=dev 创建新 test-plan.yaml
+   - 输出执行计划，等待用户确认
+
+### 阶段自动检测
+
+```
+if 用户指定 MR ID:
+  → 建议使用 /keve-test (keve-test-agent)
+  → 确认后继续或切换
+
+elif git diff 有未提交变更:
+  → 开发阶段 → trigger=dev
+
+else:
+  → 询问用户意图（开发测试 / MR 提测 / 其他）
+```
+
+### Dev 模式的 Phase 模板
+
+```yaml
+phases:
+  - { id: static,    skill: keve-static-analysis, status: pending }
+  - { id: unit,      skill: keve-unit-gen,        status: pending }
+  - { id: component, skill: keve-component-gen,   status: pending }
+```
+
+---
+
+## 调度技能
+
+| 步骤 | 调度目标 | use_skill 名称 | 输入 | 期望输出 |
+|------|----------|---------------|------|----------|
+| Step 2 | 静态分析 | `keve-static-analysis` | 项目源码 | 0 type error + 0 lint error |
+| Step 3 | 单测生成 | `keve-unit-gen` | src/utils/ + hooks/ | `keve_test_spec/util/__test__/*.test.ts` + `coverage.yaml` |
+| Step 4 | 组件测试生成 | `keve-component-gen` | src/components/ | `keve_test_spec/component/models/*.model.ts` + `__test__/*.test.ts` + `coverage.yaml` |
+
+**每个步骤完成后**：
+1. 更新 test-plan.yaml 中对应 phase 的 status
+2. 确认产物已生成
+3. 进入下一步
+
+---
+
+## 断点续跑
+
+如果 test-plan.yaml 中存在 `status = in_progress` 或 `status = pending` 的 phase：
+1. 找到第一个未完成的 phase
+2. 从该 phase 开始继续执行
+3. 跳过已 completed 的 phase
+
+---
+
+## 输出摘要
+
+所有 phase 完成后，输出：
+
+```
+━━━ KEVE 开发阶段测试报告 ━━━
+
+静态分析: ✅ 通过 (0 type error, 0 lint error)
+单元测试: ✅ 13/15 函数已覆盖 (87%)
+组件测试: 🔄 12/20 组件已覆盖 (60%)
+
+覆盖率缺口:
+  ❌ src/utils/validator.ts — 未生成测试
+  ❌ src/components/ToolManagement.vue — 未生成测试
+  ⚠️ src/utils/format.ts:formatCurrency — 缺少 NaN输入 场景
+
+下一步:
+  - 运行 npx vitest run --coverage 查看详细覆盖率
+  - 修复缺口后重新运行 /keve-dev-test
+```
+
+---
+
+## 与 keve-test-agent 的关系
+
+| 维度 | keve-dev-test-agent | keve-test-agent |
+|------|---------------------|-----------------|
+| 适用阶段 | 开发中 | MR 提测前 |
+| 编排 | static → unit → component | bddcase-gen → e2e-gen → test-eval |
+| 反馈速度 | 秒级 | 分钟级 |
+| 产出 | 覆盖率 + 缺口列表 | E2E 报告 + 评估 |
+| test-plan trigger | dev | mr |
+
+---
+
+## 禁止事项
+
+- 不做代码分析、POM 设计、定位器生成
+- 不写测试脚本
+- 不运行 Playwright E2E 测试
+- 不自行决定修复策略（只根据 phase status 决策调度方向）