# @vmosedge/workflow-agent-sdk

VMOS Edge 自动化 SDK，用于把“目标描述 -> 设备执行 -> 工作流脚本”串成一条完整链路。

SDK 内置任务规划、运行时可靠性策略、MCP 工具接入和脚本生成能力，适合 Android/云手机自动化、录制回放和 Agent 执行场景。

## 能力概览

- 目标规划：先拆解任务，再进入执行阶段
- 设备执行：内置本地设备工具，并支持挂接 MCP server 扩展能力
- 可靠性控制：内置重试、超时、收敛限制和动作后验证 gate
- 脚本生成：基于 execution log 生成结构化 workflow script

## 安装

```bash
pnpm add @vmosedge/workflow-agent-sdk
```

要求：

- Node.js >= 20
- 需要可访问的模型接口，支持 OpenAI-compatible、Anthropic Claude、Google Gemini
- 需要设备连接信息：`hostIp` + `deviceId`

## 导出说明

- `@vmosedge/workflow-agent-sdk`
  - 轻量导出，包含 `generateScript` 和基础类型
- `@vmosedge/workflow-agent-sdk/runtime`
  - 完整 runtime 能力，包含 `createAutomationAgentRuntime`、`AutomationAgentRuntime`、默认可靠性配置和错误类型
- `@vmosedge/workflow-agent-sdk/types`
  - 全量类型定义，适合深度集成

## 快速开始：直接生成脚本

适用于你已经有 execution log，只需要生成 workflow script 的场景。

```ts
import {
  generateScript,
  type AIProviderConfig,
  type ExecutionLogEntry
} from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'openai',
  baseUrl: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini'
}

const executionLog: ExecutionLogEntry[] = [
  {
    index: 1,
    toolName: 'start_app',
    arguments: {
      package_name: 'com.example.app'
    },
    result: {
      toolCallId: 'call_1',
      name: 'start_app',
      success: true
    },
    category: 'action',
    timestamp: Date.now()
  }
]

const workflow = await generateScript(
  '打开目标应用并进入首页',
  executionLog,
  provider
)

console.log(JSON.stringify(workflow, null, 2))
```

## 快速开始：使用 runtime 跑完整流程

适用于你希望从自然语言目标出发，先规划、再执行、最后生成脚本的场景。

```ts
import { createAutomationAgentRuntime } from '@vmosedge/workflow-agent-sdk/runtime'
import type { AIProviderConfig } from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'openai',
  baseUrl: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini'
}

const runtime = createAutomationAgentRuntime({
  mcpServers: {
    knowledge: {
      transport: 'streamable_http',
      url: 'https://mcp.example.com'
    }
  }
})

runtime.on('planning', (data) => {
  console.log('[planning]', data.status, data.plan)
})

runtime.on('thinking', (data) => {
  console.log('[thinking]', data.text)
})

runtime.on('toolcall', (data) => {
  console.log('[toolcall]', data.toolCall.name, data.toolCall.arguments)
})

runtime.on('toolresult', (data) => {
  console.log('[toolresult]', data.result.name, data.result.success)
})

runtime.on('paused', async (data) => {
  console.log('[paused]', data.text)

  // 需要人工补充信息时，可恢复继续执行
  // await runtime.resume({
  //   sessionId: data.sessionId,
  //   message: '继续执行，目标是进入搜索页'
  // })
})

runtime.on('error', (data) => {
  console.error('[error]', data.code, data.error, data.details)
})

const { sessionId } = await runtime.start({
  goal: '打开目标应用并进入搜索页',
  provider,
  device: {
    hostIp: '192.168.50.10',
    deviceId: 'emulator-5554'
  }
})

// 当 session 已暂停，且已经产生可用 execution log 后：
const result = await runtime.generateScript(sessionId)

console.log(JSON.stringify(result.workflow, null, 2))
console.log(result.diagnostics)

await runtime.destroy()
```

典型调用顺序：

1. `start()` 启动一次执行
2. 如果 Agent 主动暂停并要求补充信息，调用 `resume()`
3. 当 session 已暂停且执行日志可用时，调用 `generateScript()`
4. 结束时调用 `destroy()`

## Runtime 事件

| 事件名 | 说明 |
| --- | --- |
| `planning` | 任务规划开始或完成 |
| `thinking` | 模型当前可见思考文本 |
| `toolcall` | 发起工具调用 |
| `toolresult` | 收到工具执行结果 |
| `diagnostic` | 可靠性策略、重试、收敛等诊断信息 |
| `paused` | 当前轮次暂停，等待人工补充或外部决策 |
| `scriptgenerating` | 开始生成 workflow script |
| `complete` | `generateScript()` 成功完成后触发 |
| `error` | 运行时错误 |

## MCP Server 配置

支持 `stdio`、`http`、`streamable_http` 和 `sse` 四类传输方式。

### `stdio` 示例

```ts
const runtime = createAutomationAgentRuntime({
  mcpServers: {
    filesystem: {
      transport: 'stdio',
      command: 'npx',
      args: ['-y', '@modelcontextprotocol/server-filesystem', './workspace']
    }
  }
})
```

### HTTP 示例

```ts
const runtime = createAutomationAgentRuntime({
  mcpServers: {
    remoteKnowledge: {
      transport: 'streamable_http',
      url: 'https://mcp.example.com',
      headers: {
        Authorization: `Bearer ${process.env.MCP_TOKEN}`
      }
    }
  }
})
```

## 常用接口

- `createAutomationAgentRuntime(options)`：创建 runtime 实例
- `runtime.start(params)`：启动一次完整任务执行，返回 `sessionId`
- `runtime.resume(params)`：在任务暂停后继续执行
- `runtime.generateScript(sessionId)`：基于当前 session 的 execution log 生成 workflow script
- `runtime.stop(sessionId)`：停止当前 session
- `runtime.destroy()`：释放 runtime 占用资源
- `runtime.on(event, handler)` / `runtime.off(event, handler)`：订阅或取消订阅事件

## Provider 配置

SDK 现在支持两类模型接入方式：

- OpenAI-compatible：`vendor` 使用 `openai` / `deepseek` / `azure` / `custom`，需要提供 `baseUrl`
- Native provider：`vendor` 使用 `anthropic` / `claude` 或 `google` / `gemini`，分别走 Claude / Gemini 官方接口，`baseUrl` 可选

如果你拿到的是 OpenAI-compatible 聚合网关，即使底层模型实际是 Claude 或 Gemini，也应该继续使用 `openai` 或 `custom` 并填写 `baseUrl`。

### OpenAI-compatible 示例

```ts
import type { AIProviderConfig } from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'openai',
  baseUrl: 'https://api.openai.com/v1',
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-4o-mini'
}
```

### Claude 示例

```ts
import type { AIProviderConfig } from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'claude',
  apiKey: process.env.ANTHROPIC_API_KEY!,
  model: 'claude-model-id'
}
```

### Gemini 示例

```ts
import type { AIProviderConfig } from '@vmosedge/workflow-agent-sdk'

const provider: AIProviderConfig = {
  vendor: 'gemini',
  apiKey: process.env.GOOGLE_API_KEY!,
  model: 'gemini-model-id'
}
```

## 可靠性策略

内置默认策略包括：

- observation 工具最多重试 3 次
- action 工具最多重试 2 次
- 默认工具超时 12 秒
- 最大迭代次数 120
- 连续失败和重复工具调用达到阈值时自动暂停

如需调优，可在 `start()` 时传入 `reliability` 覆盖默认值。

## 使用说明

- `generateScript(sessionId)` 只有在 session 不再运行、execution log 非空且不存在待验证动作时才能成功
- `vendor` 会直接决定底层 provider：
- `openai` / `deepseek` / `azure` / `custom`：按 OpenAI-compatible 方式接入
- `anthropic` / `claude`：按 Claude 官方接口接入
- `google` / `gemini`：按 Gemini 官方接口接入