@vmosedge/workflow-agent-sdk 0.1.0

package/dist/types/index.d.ts

@@ -0,0 +1,346 @@
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { ZodTypeAny } from 'zod';
+
+/**
+ * 工具执行器
+ *
+ * 将 Agent 的工具调用映射为 HTTP 请求，发送到设备的 Control API。
+ * 每个工具名对应一个 API 路径和参数转换逻辑。
+ */
+
+/** dump_compact 解析后的结构化节点 */
+interface DumpNode {
+    index: number;
+    className: string;
+    resourceId?: string;
+    text?: string;
+    contentDesc?: string;
+    packageName?: string;
+    bounds?: string;
+    clickable: boolean;
+    longClickable: boolean;
+    scrollable: boolean;
+    focusable: boolean;
+    enabled: boolean;
+    checked: boolean;
+    selected: boolean;
+}
+
+type AIVendor = 'deepseek' | 'openai' | 'anthropic' | 'claude' | 'google' | 'gemini' | 'azure' | 'custom';
+interface AIProviderConfig {
+    vendor: AIVendor;
+    baseUrl?: string;
+    apiKey: string;
+    model: string;
+    headers?: Record<string, string>;
+}
+interface DeviceConnection {
+    hostIp: string;
+    deviceId: string;
+}
+type ToolCategory = 'observation' | 'action';
+interface ToolDefinition {
+    name: string;
+    description: string;
+    schema: ZodTypeAny;
+    parameters: Record<string, unknown>;
+    category: ToolCategory;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    source?: 'local' | 'mcp';
+    server?: string;
+}
+type ToolErrorCode = 'TIMEOUT' | 'NETWORK' | 'HTTP_4XX' | 'HTTP_5XX' | 'VALIDATION' | 'UNKNOWN_TOOL' | 'ABORTED' | 'RUNTIME_GUARD' | 'MODEL_OUTPUT_INVALID' | 'PLAN_VALIDATION_FAILED' | 'SCRIPT_VALIDATION_FAILED' | 'UNKNOWN';
+interface ToolResult {
+    toolCallId: string;
+    name: string;
+    success: boolean;
+    data?: unknown;
+    error?: string;
+    warning?: string;
+    errorCode?: ToolErrorCode;
+    retryable?: boolean;
+    attempt?: number;
+    latencyMs?: number;
+    source?: 'local' | 'mcp';
+    server?: string;
+}
+interface ExecutionLogEntry {
+    index: number;
+    toolName: string;
+    arguments: Record<string, unknown>;
+    result: ToolResult;
+    category: ToolCategory;
+    timestamp: number;
+}
+interface WorkflowScript {
+    id: string;
+    name: string;
+    version: string;
+    steps: Record<string, WorkflowStep>;
+    flow: string[];
+    description?: string;
+    timeout?: number;
+    exception_handlers?: ExceptionHandler[];
+}
+interface ExceptionHandler {
+    description?: string;
+    name?: string;
+    selector: Record<string, unknown>;
+    action: string;
+    action_params?: Record<string, unknown>;
+    max_trigger_count?: number;
+}
+interface WorkflowStep {
+    description?: string;
+    completed?: string;
+    loop?: {
+        count: number;
+        interval?: number;
+    } | {
+        max_count: number;
+        interval?: number;
+    };
+    actions: WorkflowAction[];
+}
+interface WorkflowAction {
+    path: string;
+    params?: Record<string, unknown>;
+    throw_if_empty?: string[];
+}
+type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+interface ChatMessage {
+    role: MessageRole;
+    content: string;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+    timestamp?: number;
+}
+interface TaskPlanSubtask {
+    id: number;
+    description: string;
+    successCriteria: string;
+    estimatedActions: string[];
+}
+interface TaskPlan {
+    goal: string;
+    subtasks: TaskPlanSubtask[];
+    risks: string[];
+    assumptions: string[];
+    estimatedSteps: number;
+}
+interface ToolRetryPolicy {
+    observation: number;
+    action: number;
+}
+interface ToolTimeoutPolicy {
+    defaultMs: number;
+    observeScreenMs: number;
+    startAppMs: number;
+}
+interface RuntimeLimitPolicy {
+    /** Positive hard cap on dialogue iterations. */
+    maxIterations: number;
+    maxConsecutiveFailures: number;
+    maxSameToolFingerprint: number;
+}
+interface PlannerPolicy {
+    maxAttempts: number;
+}
+interface ScriptGenerationPolicy {
+    maxAttempts: number;
+}
+interface ReliabilityConfig {
+    retries: ToolRetryPolicy;
+    timeouts: ToolTimeoutPolicy;
+    limits: RuntimeLimitPolicy;
+    planner: PlannerPolicy;
+    scriptGeneration: ScriptGenerationPolicy;
+}
+interface AgentRuntimeStartParams {
+    sessionId?: string;
+    goal: string;
+    provider: AIProviderConfig;
+    device: DeviceConnection;
+    /** 默认启用任务规划；传 false 可关闭 */
+    enablePlanning?: boolean;
+    /** Runtime v2 可靠性策略 */
+    reliability?: Partial<ReliabilityConfig>;
+}
+interface AgentRuntimeResumeParams {
+    sessionId: string;
+    message: string;
+}
+interface AgentThinkingData {
+    sessionId: string;
+    text: string;
+    iteration: number;
+}
+interface AgentToolCallData {
+    sessionId: string;
+    toolCall: ToolCall;
+    iteration: number;
+}
+interface AgentToolResultData {
+    sessionId: string;
+    result: ToolResult;
+    iteration: number;
+}
+interface AgentPausedData {
+    sessionId: string;
+    text: string;
+    iteration: number;
+}
+interface AgentDiagnosticData {
+    sessionId: string;
+    phase: 'planning' | 'runtime' | 'recovery' | 'script_generation' | 'policy';
+    code: string;
+    message: string;
+    iteration?: number;
+    details?: Record<string, unknown>;
+    timestamp: number;
+}
+interface RuntimeDiagnosticsSummary {
+    planningRetries: number;
+    toolRetries: number;
+    scriptGenerationRetries: number;
+    convergenceTriggers: number;
+    totalToolCalls: number;
+    successfulToolCalls: number;
+    runtimeSuccessRate: number | null;
+    totalActionCalls: number;
+    successfulActionCalls: number;
+    automationSuccessRate: number | null;
+    totalFailures: number;
+    failureByCode: Record<string, number>;
+    finalFailureCode?: string;
+}
+interface AgentCompleteData {
+    sessionId: string;
+    workflow: WorkflowScript;
+    executionLog: ExecutionLogEntry[];
+    totalIterations: number;
+    diagnostics?: RuntimeDiagnosticsSummary;
+}
+interface AgentPlanningData {
+    sessionId: string;
+    status: 'started' | 'completed';
+    plan?: TaskPlan;
+}
+interface AgentScriptGeneratingData {
+    sessionId: string;
+}
+type AgentErrorCode = 'INVALID_CONFIG' | 'SESSION_NOT_FOUND' | 'SESSION_NOT_PAUSED' | 'AGENT_RUNNING' | 'EMPTY_EXECUTION_LOG' | 'MCP_CONNECT_FAILED' | 'SCRIPT_GENERATION_FAILED' | 'RUNTIME_LOOP_FAILED' | 'UNKNOWN';
+interface AgentErrorData {
+    sessionId: string;
+    error: string;
+    code?: AgentErrorCode;
+    details?: Record<string, unknown>;
+}
+type RuntimeEventName = 'planning' | 'thinking' | 'toolcall' | 'toolresult' | 'diagnostic' | 'paused' | 'scriptgenerating' | 'complete' | 'error';
+interface RuntimeEventPayloadMap {
+    planning: AgentPlanningData;
+    thinking: AgentThinkingData;
+    toolcall: AgentToolCallData;
+    toolresult: AgentToolResultData;
+    diagnostic: AgentDiagnosticData;
+    paused: AgentPausedData;
+    scriptgenerating: AgentScriptGeneratingData;
+    complete: AgentCompleteData;
+    error: AgentErrorData;
+}
+type RuntimeEventHandler<TEvent extends RuntimeEventName> = (data: RuntimeEventPayloadMap[TEvent]) => void;
+type McpServerConfig = {
+    transport: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    transport: 'http' | 'streamable_http' | 'sse';
+    url: string;
+    headers?: Record<string, string>;
+};
+interface AgentRuntimeOptions {
+    mcpServers?: Record<string, McpServerConfig>;
+    persistence?: {
+        mode?: 'sqlite' | 'memory';
+    };
+}
+interface RuntimeContextState {
+    lastObserveRawDump: string | null;
+    lastObserveNodes: DumpNode[];
+    pendingVerifyAction: {
+        index: number;
+        toolName: string;
+    } | null;
+    /** 软提醒：所有 action 工具（除 wait）成功后设置，verify_ui_state 成功后清除 */
+    softPendingVerify: {
+        index: number;
+        toolName: string;
+    } | null;
+    /** record_search_context 最后成功执行的时间戳 */
+    lastSearchContextTimestamp: number | null;
+    consecutiveFailures: number;
+    sameToolFingerprintCount: number;
+    lastToolFingerprint: string | null;
+    planningRetries: number;
+    toolRetries: number;
+    scriptGenerationRetries: number;
+    convergenceTriggers: number;
+}
+interface AgentSessionState {
+    sessionId: string;
+    goal: string;
+    provider: AIProviderConfig;
+    device: DeviceConnection;
+    reliability: ReliabilityConfig;
+    iteration: number;
+    running: boolean;
+    paused: boolean;
+    messages: ChatMessage[];
+    executionLog: ExecutionLogEntry[];
+    diagnostics: AgentDiagnosticData[];
+    runtimeContext: RuntimeContextState;
+    plan?: TaskPlan;
+}
+type AgentSessionStatus = 'running' | 'paused' | 'stopped';
+interface SessionQueryOptions {
+    status?: AgentSessionStatus;
+    deviceId?: string;
+    keyword?: string;
+    limit?: number;
+    offset?: number;
+}
+interface SessionSummary {
+    sessionId: string;
+    goal: string;
+    status: AgentSessionStatus;
+    providerVendor: string;
+    deviceId: string;
+    totalIterations: number;
+    lastError?: string;
+    lastErrorCode?: string;
+    createTime: number;
+    updateTime: number;
+}
+interface ProviderResponse {
+    content: string;
+    toolCalls: ToolCall[];
+    finishReason?: string;
+}
+interface ProviderCapabilities {
+    toolCalling: boolean;
+    structuredJson: boolean;
+    jsonMode: boolean;
+}
+interface IModelProvider {
+    readonly capabilities: ProviderCapabilities;
+    getModel(): BaseChatModel;
+    chatWithTools(messages: ChatMessage[], tools: Array<ToolDefinition | unknown>, signal?: AbortSignal): Promise<ProviderResponse>;
+    chatStructuredJson<T extends Record<string, unknown>>(messages: ChatMessage[], schema: ZodTypeAny, signal?: AbortSignal): Promise<T>;
+}
+
+export type { AIProviderConfig, AIVendor, AgentCompleteData, AgentDiagnosticData, AgentErrorCode, AgentErrorData, AgentPausedData, AgentPlanningData, AgentRuntimeOptions, AgentRuntimeResumeParams, AgentRuntimeStartParams, AgentScriptGeneratingData, AgentSessionState, AgentSessionStatus, AgentThinkingData, AgentToolCallData, AgentToolResultData, ChatMessage, DeviceConnection, ExceptionHandler, ExecutionLogEntry, IModelProvider, McpServerConfig, MessageRole, PlannerPolicy, ProviderCapabilities, ProviderResponse, ReliabilityConfig, RuntimeContextState, RuntimeDiagnosticsSummary, RuntimeEventHandler, RuntimeEventName, RuntimeEventPayloadMap, RuntimeLimitPolicy, ScriptGenerationPolicy, SessionQueryOptions, SessionSummary, TaskPlan, TaskPlanSubtask, ToolCall, ToolCategory, ToolDefinition, ToolErrorCode, ToolResult, ToolRetryPolicy, ToolTimeoutPolicy, WorkflowAction, WorkflowScript, WorkflowStep };

package/dist/types/index.js

@@ -0,0 +1 @@
+

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@vmosedge/workflow-agent-sdk",
+  "version": "0.1.0",
+  "description": "VMOS Edge 自动化 SDK，提供任务规划、设备执行与工作流脚本生成能力",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js",
+      "require": "./dist/runtime/index.cjs",
+      "default": "./dist/runtime/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js",
+      "require": "./dist/types/index.cjs",
+      "default": "./dist/types/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "vmos",
+    "vmos-edge",
+    "automation",
+    "android",
+    "agent",
+    "mcp",
+    "langchain",
+    "workflow"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist .rollup-tmp",
+    "build:js": "tsc -p tsconfig.rollup.json",
+    "build:bundle": "rollup -c rollup.config.mjs",
+    "build:types": "rollup -c rollup.config.types.mjs",
+    "build": "pnpm run clean && pnpm run build:js && pnpm run build:bundle && pnpm run build:types && rm -rf .rollup-tmp",
+    "prepublishOnly": "pnpm run build && npm pack --dry-run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@langchain/anthropic": "1.3.21",
+    "@langchain/core": "^1.1.29",
+    "@langchain/google-genai": "2.1.23",
+    "@langchain/mcp-adapters": "^1.1.3",
+    "@langchain/openai": "^1.2.10",
+    "better-sqlite3": "^12.5.0",
+    "uuid": "^13.0.0",
+    "zod": "^3.25.76",
+    "zod-to-json-schema": "^3.24.6"
+  },
+  "devDependencies": {
+    "@rollup/plugin-terser": "^1.0.0",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.13.11",
+    "rollup": "^4.59.0",
+    "rollup-plugin-dts": "^6.3.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  }
+}