@kkeve/suite 0.0.15 → 0.0.18

package/dist/index.d.ts

@@ -1,8 +1,13 @@
-export { generateReportData, type ReportDataOptions, parseCaseIdFromTitle, extractAllSpecs, buildCaseResultMap, parseYamlSimple } from './core/generateReport/reportData';
-export { KevePageAgent, reactLoop, type AgentResult, type AgentStepEvent, type AgentEvent, type AgentOptions, type AgentHooks } from './page-agent/agent';
-export { tools, packMacroToolSchema, type PageAgentTool, type MacroToolInput, type ToolContext } from './page-agent/tools';
-export { keveAspect, KeveAspectRegistry, type AspectPhase, type AspectDefinition, type GoalContext, type GoalResult } from './core/keve-aspect';
-export { ActionLogWriter, type ActionLogRecord } from './core/action-log-writer';
-export { learnedActions, LearnedActions } from './core/learned-actions';
-export { generatePwConfig, resolveConfigOutputPath, findExistingConfig, type PwConfigOptions } from './core/pw-config';
-export { run, KeveRunError, type RunOptions, type RunResult } from './commands/run';
+export { generateReportData, type ReportDataOptions, parseCaseIdFromTitle, extractAllSpecs, buildCaseResultMap, parseYamlSimple } from './core/generateReport/reportData.js';
+export { KevePageAgent, reactLoop, type AgentResult, type AgentStepEvent, type AgentEvent, type AgentOptions, type AgentHooks } from './page-agent/agent.js';
+export { tools, packMacroToolSchema, type PageAgentTool, type MacroToolInput, type ToolContext } from './page-agent/tools.js';
+export { keveAspect, KeveAspectRegistry, type AspectPhase, type AspectDefinition, type GoalContext, type GoalResult } from './core/decorator/keve-aspect.js';
+export { ActionLogWriter, type ActionLogRecord } from './core/action-log-writer.js';
+export { learnedActions, LearnedActions } from './core/learned-actions.js';
+export { generatePwConfig, resolveConfigOutputPath, findExistingConfig, type PwConfigOptions } from './engine-playwright/pw-config.js';
+export { run, KeveRunError, type RunOptions, type RunResult } from './commands/run.js';
+export { definePage, type ElementRef, type ElementFactory, type ElementEntry, type ElementRegistry, type PageDefinition, type DefinedPage, type WaitForReady, isElementFactory, getElement } from './core/page-object/definePage.js';
+export { resolveElement, resolveChain, resolveFromPage } from './core/page-object/elementResolver.js';
+export { PlaywrightEngine, createEngine, type EngineAdapter } from './engine-playwright/engineAdapter.js';
+export { toDecorator, generateDecoratorSpec, type ToDecoratorOptions, type DslStep, type DslExpectation } from './dsl/index.js';
+export type { SsoCookie } from './core/sso-cookie.js';

package/dist/index.js

@@ -1,38 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KeveRunError = exports.run = exports.findExistingConfig = exports.resolveConfigOutputPath = exports.generatePwConfig = exports.LearnedActions = exports.learnedActions = exports.ActionLogWriter = exports.KeveAspectRegistry = exports.keveAspect = exports.packMacroToolSchema = exports.tools = exports.reactLoop = exports.KevePageAgent = exports.parseYamlSimple = exports.buildCaseResultMap = exports.extractAllSpecs = exports.parseCaseIdFromTitle = exports.generateReportData = void 0;
-var reportData_1 = require("./core/generateReport/reportData");
-Object.defineProperty(exports, "generateReportData", { enumerable: true, get: function () { return reportData_1.generateReportData; } });
-Object.defineProperty(exports, "parseCaseIdFromTitle", { enumerable: true, get: function () { return reportData_1.parseCaseIdFromTitle; } });
-Object.defineProperty(exports, "extractAllSpecs", { enumerable: true, get: function () { return reportData_1.extractAllSpecs; } });
-Object.defineProperty(exports, "buildCaseResultMap", { enumerable: true, get: function () { return reportData_1.buildCaseResultMap; } });
-Object.defineProperty(exports, "parseYamlSimple", { enumerable: true, get: function () { return reportData_1.parseYamlSimple; } });
+exports.generateDecoratorSpec = exports.toDecorator = exports.createEngine = exports.PlaywrightEngine = exports.resolveFromPage = exports.resolveChain = exports.resolveElement = exports.getElement = exports.isElementFactory = exports.definePage = exports.KeveRunError = exports.run = exports.findExistingConfig = exports.resolveConfigOutputPath = exports.generatePwConfig = exports.LearnedActions = exports.learnedActions = exports.ActionLogWriter = exports.KeveAspectRegistry = exports.keveAspect = exports.packMacroToolSchema = exports.tools = exports.reactLoop = exports.KevePageAgent = exports.parseYamlSimple = exports.buildCaseResultMap = exports.extractAllSpecs = exports.parseCaseIdFromTitle = exports.generateReportData = void 0;
+var reportData_js_1 = require("./core/generateReport/reportData.js");
+Object.defineProperty(exports, "generateReportData", { enumerable: true, get: function () { return reportData_js_1.generateReportData; } });
+Object.defineProperty(exports, "parseCaseIdFromTitle", { enumerable: true, get: function () { return reportData_js_1.parseCaseIdFromTitle; } });
+Object.defineProperty(exports, "extractAllSpecs", { enumerable: true, get: function () { return reportData_js_1.extractAllSpecs; } });
+Object.defineProperty(exports, "buildCaseResultMap", { enumerable: true, get: function () { return reportData_js_1.buildCaseResultMap; } });
+Object.defineProperty(exports, "parseYamlSimple", { enumerable: true, get: function () { return reportData_js_1.parseYamlSimple; } });
 // Re-Act loop (refactored to page-agent)
-var agent_1 = require("./page-agent/agent");
-Object.defineProperty(exports, "KevePageAgent", { enumerable: true, get: function () { return agent_1.KevePageAgent; } });
-Object.defineProperty(exports, "reactLoop", { enumerable: true, get: function () { return agent_1.reactLoop; } });
-var tools_1 = require("./page-agent/tools");
-Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_1.tools; } });
-Object.defineProperty(exports, "packMacroToolSchema", { enumerable: true, get: function () { return tools_1.packMacroToolSchema; } });
+var agent_js_1 = require("./page-agent/agent.js");
+Object.defineProperty(exports, "KevePageAgent", { enumerable: true, get: function () { return agent_js_1.KevePageAgent; } });
+Object.defineProperty(exports, "reactLoop", { enumerable: true, get: function () { return agent_js_1.reactLoop; } });
+var tools_js_1 = require("./page-agent/tools.js");
+Object.defineProperty(exports, "tools", { enumerable: true, get: function () { return tools_js_1.tools; } });
+Object.defineProperty(exports, "packMacroToolSchema", { enumerable: true, get: function () { return tools_js_1.packMacroToolSchema; } });
 // Aspect registry (new)
-var keve_aspect_1 = require("./core/keve-aspect");
-Object.defineProperty(exports, "keveAspect", { enumerable: true, get: function () { return keve_aspect_1.keveAspect; } });
-Object.defineProperty(exports, "KeveAspectRegistry", { enumerable: true, get: function () { return keve_aspect_1.KeveAspectRegistry; } });
+var keve_aspect_js_1 = require("./core/decorator/keve-aspect.js");
+Object.defineProperty(exports, "keveAspect", { enumerable: true, get: function () { return keve_aspect_js_1.keveAspect; } });
+Object.defineProperty(exports, "KeveAspectRegistry", { enumerable: true, get: function () { return keve_aspect_js_1.KeveAspectRegistry; } });
 // Action log (new)
-var action_log_writer_1 = require("./core/action-log-writer");
-Object.defineProperty(exports, "ActionLogWriter", { enumerable: true, get: function () { return action_log_writer_1.ActionLogWriter; } });
+var action_log_writer_js_1 = require("./core/action-log-writer.js");
+Object.defineProperty(exports, "ActionLogWriter", { enumerable: true, get: function () { return action_log_writer_js_1.ActionLogWriter; } });
 // Learned actions (new)
-var learned_actions_1 = require("./core/learned-actions");
-Object.defineProperty(exports, "learnedActions", { enumerable: true, get: function () { return learned_actions_1.learnedActions; } });
-Object.defineProperty(exports, "LearnedActions", { enumerable: true, get: function () { return learned_actions_1.LearnedActions; } });
+var learned_actions_js_1 = require("./core/learned-actions.js");
+Object.defineProperty(exports, "learnedActions", { enumerable: true, get: function () { return learned_actions_js_1.learnedActions; } });
+Object.defineProperty(exports, "LearnedActions", { enumerable: true, get: function () { return learned_actions_js_1.LearnedActions; } });
 // Playwright config generator
-var pw_config_1 = require("./core/pw-config");
-Object.defineProperty(exports, "generatePwConfig", { enumerable: true, get: function () { return pw_config_1.generatePwConfig; } });
-Object.defineProperty(exports, "resolveConfigOutputPath", { enumerable: true, get: function () { return pw_config_1.resolveConfigOutputPath; } });
-Object.defineProperty(exports, "findExistingConfig", { enumerable: true, get: function () { return pw_config_1.findExistingConfig; } });
+var pw_config_js_1 = require("./engine-playwright/pw-config.js");
+Object.defineProperty(exports, "generatePwConfig", { enumerable: true, get: function () { return pw_config_js_1.generatePwConfig; } });
+Object.defineProperty(exports, "resolveConfigOutputPath", { enumerable: true, get: function () { return pw_config_js_1.resolveConfigOutputPath; } });
+Object.defineProperty(exports, "findExistingConfig", { enumerable: true, get: function () { return pw_config_js_1.findExistingConfig; } });
 // Run API
-var run_1 = require("./commands/run");
-Object.defineProperty(exports, "run", { enumerable: true, get: function () { return run_1.run; } });
-Object.defineProperty(exports, "KeveRunError", { enumerable: true, get: function () { return run_1.KeveRunError; } });
+var run_js_1 = require("./commands/run.js");
+Object.defineProperty(exports, "run", { enumerable: true, get: function () { return run_js_1.run; } });
+Object.defineProperty(exports, "KeveRunError", { enumerable: true, get: function () { return run_js_1.KeveRunError; } });
 // Script refine (new)
 // script-refine is now part of page-agent/tools
+// ─── Code-based Element Management (P0) ──────────────────────────────
+var definePage_js_1 = require("./core/page-object/definePage.js");
+Object.defineProperty(exports, "definePage", { enumerable: true, get: function () { return definePage_js_1.definePage; } });
+Object.defineProperty(exports, "isElementFactory", { enumerable: true, get: function () { return definePage_js_1.isElementFactory; } });
+Object.defineProperty(exports, "getElement", { enumerable: true, get: function () { return definePage_js_1.getElement; } });
+var elementResolver_js_1 = require("./core/page-object/elementResolver.js");
+Object.defineProperty(exports, "resolveElement", { enumerable: true, get: function () { return elementResolver_js_1.resolveElement; } });
+Object.defineProperty(exports, "resolveChain", { enumerable: true, get: function () { return elementResolver_js_1.resolveChain; } });
+Object.defineProperty(exports, "resolveFromPage", { enumerable: true, get: function () { return elementResolver_js_1.resolveFromPage; } });
+var engineAdapter_js_1 = require("./engine-playwright/engineAdapter.js");
+Object.defineProperty(exports, "PlaywrightEngine", { enumerable: true, get: function () { return engineAdapter_js_1.PlaywrightEngine; } });
+Object.defineProperty(exports, "createEngine", { enumerable: true, get: function () { return engineAdapter_js_1.createEngine; } });
+var index_js_1 = require("./dsl/index.js");
+Object.defineProperty(exports, "toDecorator", { enumerable: true, get: function () { return index_js_1.toDecorator; } });
+Object.defineProperty(exports, "generateDecoratorSpec", { enumerable: true, get: function () { return index_js_1.generateDecoratorSpec; } });

package/dist/page-agent/agent.d.ts

@@ -15,8 +15,10 @@
  *   const agent = new KevePageAgent(page, { maxSteps: 5 });
  *   const result = await agent.execute(step, expected, { learnedActionsHint, fnResult });
  */
-import type { Page } from '@playwright/test';
 import { LLM } from '@kkeve/core/llm';
+import type { AgentInitialImageLoader, AgentPage, AgentScreenshotSaver } from './page-like.js';
+import { toAgentPage } from './playwright-page.js';
+import { type RawAiUsageRecord, type RawConsoleRecord, type RawNetworkRecord, type RuntimeDiagnostics } from './diagnostics.js';
 export interface AgentStepEvent {
     type: 'step';
     stepIndex: number;
@@ -29,6 +31,8 @@ export interface AgentStepEvent {
     toolError?: string;
     snapshot: string;
     screenshotPath?: string;
+    /** 工具执行耗时（ms）；LLM 调度异常时缺省 */
+    duration?: number;
 }
 export interface AgentObservationEvent {
     type: 'observation';
@@ -44,6 +48,8 @@ export interface AgentResult {
     data: string;
     events: AgentEvent[];
     finalSnapshot: string;
+    /** 运行诊断：性能、网络、浏览器错误与质量信号 */
+    diagnostics?: RuntimeDiagnostics;
     agentScreenshots?: string[];
     diagnosticHints?: string[];
 }
@@ -75,13 +81,48 @@ export interface AgentOptions {
     /** fn-after 截图路径（相对 taskDir）— fn 执行后的页面状态 */
     fnAfterScreenshot?: string;
 }
+/**
+ * Agent 的宿主能力注入点。
+ *
+ * `page-agent` 现在同时服务 Playwright 与 Cypress（浏览器 bundle），因此不能再
+ * 直接持有 Node API。所有原本写死的 Node 能力（读 prompt / 落盘截图 / 读本地
+ * 图片 / 读环境变量 / LLM 传输）都改为构造时注入；Playwright 侧给 Node 实现，
+ * Cypress 侧给 HTTP 桥实现。
+ */
+export interface AgentHostOptions {
+    /** system prompt 文本（缺省用编译期内联的 SYSTEM_PROMPT） */
+    systemPrompt?: string;
+    /** 目标应用 URL（原 process.env.KEVE_TARGET_URL） */
+    targetUrl?: string;
+    /** 环境变量读取（原 process.env.X），缺省返回空串 */
+    getEnv?: (name: string) => string;
+    /** 截图落盘，返回相对 taskDir 的路径（原 saveScreenshotBuffer 的 fs 部分） */
+    saveScreenshot?: AgentScreenshotSaver;
+    /** 读取初始多模态截图（原 loadInitialScreenshots 的 fs 部分） */
+    loadInitialImages?: AgentInitialImageLoader;
+    /** LLM 配置；缺省从注入的环境变量拼装 */
+    llm?: {
+        baseURL: string;
+        model: string;
+        apiKey?: string;
+        temperature?: number;
+        maxRetries?: number;
+        /** 浏览器侧经桥转发；Node 侧缺省走原生 fetch */
+        customFetch?: typeof globalThis.fetch;
+    };
+}
 export declare class KevePageAgent {
-    readonly page: Page;
+    readonly page: AgentPage;
     readonly maxSteps: number;
     readonly llm: LLM;
     events: AgentEvent[];
     private abortController;
     private systemPrompt;
+    /** 目标应用 URL（原 process.env.KEVE_TARGET_URL） */
+    readonly targetUrl: string;
+    private getEnvFn;
+    private saveScreenshotFn?;
+    private loadInitialImagesFn?;
     /** Current execute options (set at start of execute(), accessible from hooks) */
     options?: AgentOptions;
     private hooks?;
@@ -97,12 +138,26 @@ export declare class KevePageAgent {
     _pendingFileChooser: any;
     _consoleMessages: any[];
     _networkRequests: any[];
+    _browserDiagnostics: RawConsoleRecord[];
+    _networkDiagnostics: RawNetworkRecord[];
+    /** 本次 execute 内 LLM 推理累计耗时（ms） */
+    _aiReasoningMs: number;
+    /** 本次 execute 内 LLM token 累计用量 */
+    _aiUsage: RawAiUsageRecord;
+    /** 本次 execute 内工具操作累计耗时（ms） */
+    _actionMs: number;
+    /** 本次 execute 起始时间，用于总耗时诊断 */
+    _executeStartedAt: number;
     _pageListenersSetup: boolean;
-    constructor(page: Page, options?: {
+    /** 页面级性能指标（execute 结束时一次性读取；读取失败则留空） */
+    private _lastPageMetrics?;
+    constructor(page: AgentPage, options?: {
         maxSteps?: number;
         customSystemPrompt?: string;
         hooks?: AgentHooks;
-    });
+    } & AgentHostOptions);
+    /** 读取宿主注入的环境变量（Cypress 侧由 cy.env 转发，Playwright 侧即 process.env） */
+    getEnv(name: string): string;
     /** Stop the current execution */
     stop(): void;
     /** Set up page event listeners for dialog, console, network, and file chooser capture.
@@ -111,9 +166,28 @@ export declare class KevePageAgent {
     /** Main Re-Act execute loop */
     execute(step: string, expected: string, options?: AgentOptions): Promise<AgentResult>;
     private pushObservation;
+    /**
+     * 读取页面级性能指标。
+     *
+     * Playwright 与 Cypress 都走同一段探针源码：Playwright 在真实页面上下文，
+     * Cypress 在 AUT 的 isolated world（navigation timing / performance entries
+     * 与主世界共享同一份 Performance 数据）。
+     */
+    private capturePageMetrics;
+    /**
+     * 汇总当前执行期的运行诊断（含页面性能与质量信号）。
+     * 公开给 reactLoop 的异常兜底分支复用，避免中断时丢失已采集数据。
+     */
+    buildDiagnostics(): RuntimeDiagnostics;
+    /** 累加单次 LLM 调用的 token 用量（重试中的失败请求不在返回结果里，无法计量） */
+    private recordAiUsage;
     private assembleUserPrompt;
     private buildMacroTool;
-    /** Save screenshot buffer to test artifacts (reuses already-captured buffer) */
+    /**
+     * Save screenshot base64 to test artifacts.
+     *
+     * 落盘能力由宿主注入：Playwright 侧写本地文件系统，Cypress 侧经 HTTP 桥落盘。
+     */
     private saveScreenshotBuffer;
     /** Load initial screenshots (goal-before + fn-after) as ContentItem[] for step 0 multimodal input */
     private loadInitialScreenshots;
@@ -139,7 +213,7 @@ export declare class KevePageAgent {
  * Drop-in replacement for the old reactLoop function.
  * Creates a KevePageAgent, runs it, and maps the result.
  */
-export declare function reactLoop(page: Page, step: string, expected: string, options?: {
+export declare function reactLoop(page: Parameters<typeof toAgentPage>[0], step: string, expected: string, options?: {
     maxSteps?: number;
     learnedActionsHint?: string;
     specFilePath?: string;
@@ -151,10 +225,11 @@ export declare function reactLoop(page: Page, step: string, expected: string, op
     signal?: AbortSignal;
     goalScreenshotBefore?: string;
     fnAfterScreenshot?: string;
-}): Promise<{
+} & AgentHostOptions): Promise<{
     actions: any[];
     expectedMet: boolean;
     conclusion?: 'pass' | 'fail' | 'blocked';
     finalSnapshot: string;
+    diagnostics?: RuntimeDiagnostics;
     agentScreenshots?: string[];
 }>;