BizApi 接口参考 | Automa Agent

自动生成

本文档由 pnpm run gen:bizapi-docs 生成，请勿手动编辑源文件外的副本。

主进程 BizApi 参考

说明

command = @BizApi() 注册名；说明来自方法 JSDoc（首行 / @when / @args）。
args：无参省略或 null；唯一形参且非 params 用 JSON 数组 ["workflowId"]（按位置传入）；params 或多字段用对象 {...}。
响应：{ success, message, data, code }。

回复格式（必须遵守）

缺参数 / 意图不清 / 有破坏性操作 / 你不确定时：只问不执行（同轮禁止 bizapi-exec）：

text

## 回复用户
（说明为何需要确认）

## 待用户确认
（可选简短说明）

json

{"reason":"缺 workflowId","questions":[{"id":"wf","question":"要操作哪个窗口？","options":[{"label":"由用户回复名称或 ID"}]}]}

参数齐备且确定时：

text

## 回复用户
（2～4 句：结论、将执行的 command、风险）

## BizApi 执行计划
无调用：无
有调用：仅一个 bizapi-exec 代码块（见下），禁止其它 JSON 块

json

{"calls":[{"command":"getWorkflowListApi","args":{"page":1,"pageSize":10}},{"command":"startWorkflow","args":["workflowId示例"]}]}

含 ## 待用户确认 或 bizapi-ask 时主进程不执行 API，等用户下一条消息后再出 bizapi-exec
calls[] 仅含 command + args；禁止编造 command
窗口=Workflow（workflowId）；执行器=WorkflowWorker（workerId）
自动执行禁止 *StreamApi；AI 用 chatAiCompleteApi
有依赖时按序：先 list/get 取 id，再 write/start/stop

HTTP

POST /api + JSON { "command", "args" }。示例：

json

{
  "command": "getCronTaskListApi",
  "args": {
    "page": 1,
    "pageSize": 1,
    "orderBy": "example",
    "orderDirection": "asc",
    "search": {
      "name": "example",
      "bizType": "example",
      "status": "example"
    }
  }
}

场景选型

意图	Controller	command 模式
启停窗口流程	MainCommandController	`startWorkflow` / `stopWorkflow`
定时任务	MainApiController	`CronTask`
窗口/变量/Cookie	MainApiController	`Workflow`（非 Worker）
执行器/表数据	MainApiController	`WorkflowWorker`、`table*`
AI 会话/通道/规则	AiApiController	`AiSession`、`chatAiCompleteApi`
本机桌面自动化	NativeApiController	`Mouse`、`Screenshot`、`findImage`、`getElement`、`locateElement*`
本机文件 / grep	NativeApiController	`readLocalFileApi`、`listLocalDirApi`、`grepLocalFilesApi`、`writeLocalFileApi`
单节点试跑	`tryRunAiExecutorApi` / `runNode` + 下文 executorNodeTypesDoc	`listAiExecutorTypesApi` → config 查节点 slug 表

API 索引

AiApiController

command	作用	何时调用	args
`abortAiStreamApi`	中止Ai Stream（AiApiController）	用户取消、超时或规则要求中断仍在进行的流式 AI 请求时；需已知 streamId。	`bizapi:{…}`
`abortAiVoiceStreamApi`	中止语音输入（AiApiController）	仅前端流式展示；自动执行计划勿用，改用 chatAiCompleteApi。	`bizapi:{…}`
`appendAiSessionMessageApi`	追加AI 会话Message（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`captureAndSendScreenshotToAiChannelApi`	截屏、压缩并通过 AI 通道（钉钉）发送（AiApiController）	自动执行助手需推送桌面截图时：工作台会话（无钉钉绑定）回传 static 链接；钉钉会话上传并推送。	`bizapi:{…}`
`chatAiCompleteApi`	非流式：一次返回完整 assistant 文本（含思考合并为前缀块，便于展示）（AiApiController）	自动执行链需在服务端完成一轮 AI 对话并将全文写入变量时；应已有 sessionId。	`bizapi:{…}`
`chatAiStreamApi`	流式 AI 对话：返回 streamId 并推送 token（AiApiController）	用户在前端发起流式对话、需逐 token 推送时；自动执行/workflow 的 http-post 链请优先用 Complete 类 API。	`bizapi:{…}`
`clearAiSessionMessagesApi`	清理AI 会话Messages（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`createAiSessionApi`	新建AI 会话（AiApiController）	用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。	`bizapi:{…}`
`createAiTimerApi`	新建 AI 调度任务：一次性延迟或重复 cron（AiApiController）	需延迟/定时自动执行 BizApi（录屏结束、每天 8 点拉数据等）且落库可管理时。	`bizapi:{…}`
`deleteAiChannelApi`	删除AI 通道（AiApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:{…}`
`deleteAiCustomProviderApi`	设置Ai Provider Api Key（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`deleteAiMessageAutoexecRuleApi`	删除执行规则（AiApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:{…}`
`deleteAiPromptApi`	删除AI 提示词（AiApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:{…}`
`deleteAiSessionApi`	删除AI 会话（AiApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:{…}`
`deleteAiTimerApi`	删除 AI 一次性延迟定时器（AiApiController）	取消尚未触发的延迟任务，或清理测试数据时。	`bizapi:{…}`
`finishAiVoiceStreamApi`	结束语音输入并返回转写文本（AiApiController）	仅前端流式展示；自动执行计划勿用，改用 chatAiCompleteApi。	`bizapi:{…}`
`getAiChannelApi`	获取AI 通道（AiApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:{…}`
`getAiPromptBodyApi`	获取AI 提示词Body（AiApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:{…}`
`getAiSessionApi`	获取AI 会话（AiApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:{…}`
`listAiChannelsApi`	列出AI 通道s（AiApiController）	配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。	bizapi:null
`listAiCustomProvidersApi`	设置Ai Provider Api Key（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	bizapi:null
`listAiExecutorTypesApi`	列出Ai Executor Types（AiApiController）	配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。	bizapi:null
`listAiMessageAutoexecRulesApi`	列出执行规则s（AiApiController）	配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。	bizapi:null
`listAiModelsApi`	列出指定 AI 提供商下可用模型（AiApiController）	配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。	`bizapi:{…}`
`listAiPromptsApi`	列出AI 提示词s（AiApiController）	配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。	bizapi:null
`listAiProvidersApi`	列出可用 AI 提供商（ollama/deepseek/cursor）（AiApiController）	配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。	bizapi:null
`listAiSessionsApi`	列出AI 会话s（AiApiController）	配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。	`bizapi:{…}`
`listAiTimersApi`	列出 AI 调度任务（一次性延迟 + 重复 cron）（AiApiController）	需查看 AI 创建的延迟/定时 BizApi 任务时。	bizapi:null
`resetAiBuiltinPromptApi`	将内置助手恢复为应用内置默认 system 提示词（覆盖库中已改动的正文）（AiApiController）	升级应用后需同步最新内置助手，或误改内置正文后恢复时。	`bizapi:{…}`
`resetAiChannelDingTalkSessionsApi`	重置通道下全部钉钉 AI 会话绑定（AiApiController）	通道改了助手/模型后需让各钉钉聊天下次入站重新建会话，或清理错误绑定时。	`bizapi:{…}`
`sendAiChannelOutboundImageApi`	向 AI 通道发送图片（钉钉：上传 media + 图片消息）（AiApiController）	已有 static 相对路径 imagePath（可先 compressImageApi），需推送到钉钉会话时。	`bizapi:{…}`
`sendAiChannelOutboundMarkdownApi`	发送AI 通道Outbound Markdown（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`sendAiChannelOutboundVideoApi`	向 AI 通道发送视频（钉钉：上传 video + 封面图 + sampleVideo）（AiApiController）	已有 static 相对路径 mp4（如 stopScreenRecordingApi 返回的 videoPath），需推送到钉钉会话时。	`bizapi:{…}`
`sendAiVoiceAudioChunkApi`	推送 PCM 音频块（16kHz mono int16）（AiApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`setAiProviderApiKeyApi`	设置Ai Provider Api Key（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`startAiChannelStreamListenApi`	启动AI 通道Stream Listen（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`startAiVoiceStreamApi`	开始 AI 语音输入会话（按住说话）（AiApiController）	用户在 AI 对话输入框按住麦克风开始录音时。	`bizapi:{…}`
`startScreenRecordingWithAutoStopAndSendApi`	开始录屏并创建延迟任务：到时停录并推送钉钉（AiApiController）	需录制固定时长桌面操作并自动推送：工作台会话回传 static 链接；钉钉会话上传视频。	`bizapi:{…}`
`stopAiChannelStreamListenApi`	停止AI 通道Stream Listen（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`stopScreenRecordingAndSendToAiChannelApi`	停止录屏并通过 AI 通道发送视频（AiApiController）	录屏已 startScreenRecordingApi 启动，需结束录制并推送：工作台会话回传 static 链接；钉钉会话上传视频。	`bizapi:{…}`
`testAiChannelApi`	测试AI 通道（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`tryRunAiExecutorApi`	试跑单个内置工作流节点（AiApiController）	需单独执行一个节点（HTTP、脚本、钉钉等）且不必 startWorkflow 时；config 见 executorNodeTypesDoc / 自动执行助手内嵌节点表。	`bizapi:{…}`
`updateAiSessionApi`	更新AI 会话（AiApiController）	已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。	`bizapi:{…}`
`updateAiTimerApi`	更新 AI 调度任务（AiApiController）	已存在 timerId，需改 delayMs、cronExpr、enabled、名称或 BizApi 步骤时。	`bizapi:{…}`
`upsertAiChannelApi`	新增或更新AI 通道（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`upsertAiCustomProviderApi`	设置Ai Provider Api Key（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`
`upsertAiMessageAutoexecRuleApi`	新增或更新执行规则（AiApiController）	配置或查询 AI 仪表盘 → 执行规则（助手回复后触发的执行器链）时。	`bizapi:{…}`
`upsertAiPromptApi`	新增或更新AI 提示词（AiApiController）	操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。	`bizapi:{…}`

AiSingleExecutorRunner

command	作用	何时调用	args
`runNode`	试跑单个执行器节点（AiSingleExecutorRunner）	自动执行或调试时需要单独跑一个节点（如 `http-get`、`run-script`、`dingtalk-notify`），且不必启停整条 Workflow 时。	`bizapi:{executorType,config,variables}`

DataSourceApiController

command	作用	何时调用	args
`connectDataSourceApi`	连接数据源（建立 managed 连接）：业务逻辑在 DataSourceService.	数据源已配置且需建立运行时 TypeORM 连接，供后续读写业务表时。	`bizapi:["<dataSourceId>"]`
`createDataSourceApi`	新建数据源：业务逻辑在 DataSourceService.	用户或规则需注册新的 sqlite/mysql/pgsql 等数据源，且 enabled=1 时会自动尝试连接。	`bizapi:{…}`
`deleteDataSourceApi`	删除数据源：业务逻辑在 DataSourceService.	确认删除不再使用的数据源及其表元数据时；会先断开 managed 连接。	`bizapi:[<id>]`
`disconnectDataSourceApi`	断开数据源 managed 连接：业务逻辑在 DataSourceService.	释放连接资源、切换配置前断开，或数据源暂时停用时。	`bizapi:["<dataSourceId>"]`
`ensureDefaultDataSourceApi`	确保默认数据集存在并返回其 dataSourceId：业务逻辑在 DataSourceService.	窗口/节点「不选数据源直接建表」时，需要一个隐式归属的数据集。	bizapi:null
`getDataSourceConnectionStatusApi`	断开数据源 managed 连接：业务逻辑在 DataSourceService.	释放连接资源、切换配置前断开，或数据源暂时停用时。	`bizapi:["<dataSourceId>"]`
`getDataSourceDetailApi`	数据源详情（含表/列/索引元数据）：业务逻辑在 DataSourceService.	需读取某数据源完整配置、表结构，或在 saveTables 前确认当前 schema 时。	`bizapi:["<dataSourceId>"]`
`getDataSourceListApi`	数据源分页列表：业务逻辑在 DataSourceService.	数据管理页浏览/筛选数据源，或后续 connect/saveTables 需先取得 dataSourceId 时（宜放在链首）。	`bizapi:{…}`
`getDataSourceSchemaDiffApi`	保存表级表单 UI 配置（元数据 only，不同步物理库）：业务逻辑在 DataSourceService.	数据管理页为某张表配置新增/编辑表单的控件、标签、值类型等 UI 行为时；须先存在表结构元数据。	`bizapi:["<dataSourceId>"]`
`listManagedTablesApi`	列出当前分域内所有「有业务编码」的逻辑表：业务逻辑在 DataSourceService.	需要全局 tableCode 选择器、或窗口数据表格面板列出可操作表时。	bizapi:null
`managedTableCountApi`	统计 managed 数据源表行数（支持单字段搜索）：业务逻辑在 DataSourceService.	与 managedTableFindApi 配合做分页 total 统计时。	`bizapi:{…}`
`managedTableDeleteApi`	删除 managed 数据源表行：业务逻辑在 DataSourceService.	数据管理页删除行时；criteria 通常为主键字段。	`bizapi:{…}`
`managedTableFindApi`	查询 managed 数据源表数据（分页/排序/单字段搜索）：业务逻辑在 DataSourceService.	数据管理页浏览业务表行数据，需分页、排序或按单字段搜索时。	`bizapi:{…}`
`managedTableInsertApi`	向 managed 数据源表插入一行：业务逻辑在 DataSourceService.	数据管理页新增业务表行数据时。	`bizapi:{…}`
`managedTableUpdateApi`	更新 managed 数据源表行：业务逻辑在 DataSourceService.	数据管理页编辑已有行时；criteria 通常为主键字段。	`bizapi:{…}`
`resetDataSourceConnectionApi`	断开数据源 managed 连接：业务逻辑在 DataSourceService.	释放连接资源、切换配置前断开，或数据源暂时停用时。	`bizapi:["<dataSourceId>"]`
`resolveTableByCodeApi`	按业务编码全局定位表：业务逻辑在 DataSourceService.	需要由 tableCode 反查 `{ dataSourceId, tableName }` 时。	`bizapi:["<tableCode>"]`
`saveDataSourceTablesApi`	保存数据源表结构（元数据 + 同步 managed schema）：业务逻辑在 DataSourceService.	数据管理页配置完表/列后持久化，或 workflow 需同步业务表定义时；保存后会 forceRecreate 连接。	`bizapi:{…}`
`syncDataSourceSchemaApi`	保存表级表单 UI 配置（元数据 only，不同步物理库）：业务逻辑在 DataSourceService.	数据管理页为某张表配置新增/编辑表单的控件、标签、值类型等 UI 行为时；须先存在表结构元数据。	`bizapi:["<dataSourceId>"]`
`syncPhysicalTablesFromDatabaseApi`	断开数据源 managed 连接：业务逻辑在 DataSourceService.	释放连接资源、切换配置前断开，或数据源暂时停用时。	`bizapi:["<dataSourceId>"]`
`tableBatchInsertByCodeApi`	按业务编码批量插入：业务逻辑在 DataSourceService.	执行器/脚本/Excel 导入按 tableCode 批量写入数据时。	`bizapi:{…}`
`tableClearByCodeApi`	按业务编码清空表：业务逻辑在 DataSourceService.	执行器/脚本按 tableCode 清空整表（不可逆）时。	`bizapi:{…}`
`tableCountByCodeApi`	按业务编码统计行数（等值条件）：业务逻辑在 DataSourceService.	执行器/脚本按 tableCode 统计行数时。	`bizapi:{…}`
`tableDeleteByCodeApi`	按业务编码删除（等值条件）：业务逻辑在 DataSourceService.	执行器/脚本按 tableCode 删除满足条件的行时。	`bizapi:{…}`
`tableFindByCodeApi`	按业务编码查询表数据（等值条件）：业务逻辑在 DataSourceService.	执行器/脚本按 tableCode 读取多行数据时。	`bizapi:{…}`
`tableFindOneByCodeApi`	按业务编码查询单条：业务逻辑在 DataSourceService.	执行器/脚本按 tableCode 读取单行数据时。	`bizapi:{…}`
`tableInsertByCodeApi`	按业务编码插入一行：业务逻辑在 DataSourceService.	执行器/脚本按 tableCode 写入单行数据时。	`bizapi:{…}`
`tableUpdateByCodeApi`	按业务编码更新（等值条件）：业务逻辑在 DataSourceService.	执行器/脚本按 tableCode 更新满足条件的行时。	`bizapi:{…}`
`testDataSourceConnectionApi`	测试数据源连接：业务逻辑在 DataSourceService.	新建/编辑后验证连接参数是否正确，或排查连接失败原因时。	`bizapi:[<id>]`
`updateDataSourceApi`	更新数据源配置：业务逻辑在 DataSourceService.	已有数据源 id，需修改名称、连接参数或 enabled 等字段时；宜先 getDetail 确认。	`bizapi:{…}`
`updateTableFormUiConfigApi`	保存表级表单 UI 配置（元数据 only，不同步物理库）：业务逻辑在 DataSourceService.	数据管理页为某张表配置新增/编辑表单的控件、标签、值类型等 UI 行为时；须先存在表结构元数据。	`bizapi:{…}`

MainApiController

command	作用	何时调用	args
`addCapturedElementApi`	新增采集元素（MainApiController）	用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。	`bizapi:{…}`
`addFolderApi`	新增文件夹（MainApiController）	用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。	`bizapi:{…}`
`addScreenshotApi`	新增截图（MainApiController）	用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。	`bizapi:{…}`
`addWorkflowApi`	新增窗口（MainApiController）	用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。	`bizapi:{…}`
`addWorkflowWorkerApi`	新增执行器（MainApiController）	用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。	`bizapi:{…}`
`batchDeleteWorkflowVariablesApi`	批量删除变量（按主键 id，当前分域）（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:[…]`
`batchStartWorkflowWorkerApi`	批量Start执行器（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:[…]`
`batchStopWorkflowWorkerApi`	批量Stop执行器（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:[…]`
`clearCacheByWorkflowIdApi`	清理Cache By窗口Id（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:["<workflowId>"]`
`clearCookieApi`	清理Cookie（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`copyWorkflowApi`	复制窗口（MainApiController）	基于已有记录快速克隆一份（保留结构、改名称）时。	`bizapi:{…}`
`createCronTaskApi`	新建定时任务（window / executor / ai）：业务逻辑在 CronManager.	用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。	`bizapi:{…}`
`deleteCapturedElementApi`	删除采集元素（MainApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:[<id>]`
`deleteCronTaskApi`	删除定时任务，业务逻辑在 CronManager.	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:[<id>]`
`deleteFolderApi`	删除文件夹（MainApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:{…}`
`deleteScreenshotApi`	删除截图（MainApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:[<id>]`
`deleteWorkflowApi`	删除窗口（MainApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:[<id>]`
`deleteWorkflowVariablesApi`	删除窗口Variables（MainApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:[<id>]`
`deleteWorkflowWorkerApi`	删除执行器（MainApiController）	确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。	`bizapi:[<id>]`
`exportWorkflowsApi`	批量导出窗口配置为 Excel（按列表主键 id）（MainApiController）	需要导出文件供下载、备份或传给下游节点（如写文件、上传）时。	`bizapi:{…}`
`exportWorkflowVariablesByWorkflowIdsApi`	按窗口 ID 批量导出变量（与导入模板列一致）（MainApiController）	需要导出文件供下载、备份或传给下游节点（如写文件、上传）时。	`bizapi:{…}`
`exportWorkflowVariablesExcelApi`	导出变量为 Excel（按变量主键 id）（MainApiController）	需要导出文件供下载、备份或传给下游节点（如写文件、上传）时。	`bizapi:{…}`
`focusWorkflowWinApi`	聚焦窗口Win（MainApiController）	需要把用户注意力切到某窗口（调试或人工介入）时。	`bizapi:["<workflowId>"]`
`getCapturedElementByIdApi`	获取采集元素By Id（MainApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:[<id>]`
`getCapturedElementListApi`	采集元素分页列表（MainApiController）	需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。	`bizapi:{…}`
`getCookiesApi`	获取Cookies（MainApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:["<workflowId>"]`
`getCronTaskListApi`	定时任务分页列表：业务逻辑在 CronManager.	需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。	`bizapi:{…}`
`getFolderTreeApi`	获取文件夹Tree（MainApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:{…}`
`getLogsListApi`	Logs分页列表（MainApiController）	需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。	`bizapi:{…}`
`getPlatformInfoApi`	获取Platform Info（MainApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	bizapi:null
`getScreenshotListApi`	截图分页列表（MainApiController）	需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。	`bizapi:{…}`
`getStatisticsDetailListApi`	Statistics Detail分页列表（MainApiController）	需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。	`bizapi:{…}`
`getStatisticsListApi`	运行统计Statistics分页列表（MainApiController）	需要对窗口流程进行运行统计分析时。	`bizapi:{…}`
`getUnusedScreenshotsApi`	获取Unused截图s（MainApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	bizapi:null
`getUserAgentApi`	生成 User-Agent（MainApiController，user-agents 库）（MainApiController）	需按平台/浏览器/版本生成 UA；未传 platform 时使用当前运行环境。	`bizapi:{…}`
`getWorkflowListApi`	窗口分页列表（MainApiController）	需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。	`bizapi:{…}`
`getWorkflowVariablesApi`	获取所有变量 *（MainApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:["<workflowId>"]`
`getWorkflowWorkerApi`	获取执行器（MainApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:[<id>]`
`getWorkflowWorkerByWorkerIdApi`	获取执行器By Worker Id（MainApiController）	已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。	`bizapi:["<workerId>"]`
`getWorkflowWorkerListApi`	执行器分页列表（MainApiController）	需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。	`bizapi:{…}`
`importWorkflowsApi`	批量从 Excel 导入窗口：名称、host、窗口ID 必填；同一分域下窗口ID 已存在则更新，否则新增（MainApiController）	已有导入文件/表格数据，需批量写入系统时。	`bizapi:{…}`
`importWorkflowVariablesExcelApi`	导入窗口Variables Excel（MainApiController）	已有导入文件/表格数据，需批量写入系统时。	`bizapi:{…}`
`openLocalPathApi`	在系统文件管理器中打开本地路径 *（MainApiController）	需在 Finder/资源管理器中打开目录，或定位到文件所在目录时。	`bizapi:["<filePath>"]`
`resetCookieApi`	重置Cookie（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`resetMainWindowApi`	重置Main Window（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	bizapi:null
`restartAppServerApi`	重启内置 HTTP 服务 *（MainApiController）	修改服务相关配置或 HTTP 服务异常，需重新监听端口时。	bizapi:null
`runCronTaskNowApi`	立即执行一次定时任务（与开关无关）（MainApiController）	需立刻执行一次任务，不等待 cron/触发器排期时（与任务是否启用无关）。	`bizapi:[<id>]`
`saveWorkflowVariablesApi`	保存或添加 *（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:["<workflowVariables>"]`
`selectElementApi`	元素选择 *（MainApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:["<workflow>"]`
`setWorkflowEnabledApi`	设置窗口Enabled（MainApiController）	需开关功能（启停定时、执行器）但保留记录时；enabled: 0 会触发停用副作用。	`bizapi:{…}`
`setWorkflowWorkerEnabledApi`	设置执行器Enabled（MainApiController）	需开关功能（启停定时、执行器）但保留记录时；enabled: 0 会触发停用副作用。	`bizapi:{…}`
`startWorkflowWorkerApi`	启动执行器（MainApiController）	需立即启动运行；前置：资源已启用且参数齐备。	`bizapi:[<id>]`
`stopWorkflowWorkerApi`	停止执行器（MainApiController）	需中断运行或释放资源时。	`bizapi:[<id>]`
`updateAppServerPortApi`	修改内置 HTTP 服务端口并重启（写入 config/app.	已有资源 id，需修改配置并持久化时。	`bizapi:[<id>]`
`updateCapturedElementApi`	更新采集元素（MainApiController）	已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。	`bizapi:{…}`
`updateCronApi`	更新定时器任务 *（MainApiController）	已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。	`bizapi:{…}`
`updateCronTaskApi`	更新定时任务，业务逻辑在 CronManager.	已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。	`bizapi:{…}`
`updateFolderApi`	更新文件夹（MainApiController）	已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。	`bizapi:{…}`
`updateScreenshotApi`	更新截图（MainApiController）	已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。	`bizapi:{…}`
`updateWorkflowApi`	更新窗口（MainApiController）	已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。	`bizapi:{…}`
`updateWorkflowWorkerApi`	更新执行器（MainApiController）	已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。	`bizapi:{…}`

MainCommandController

command	作用	何时调用	args
`startWorkflow`	启动指定窗口流程（打开/运行自动化窗口流程）（MainCommandController）	自动执行或助手编排需启动某 workflowId 的流程（打开窗口并开始跑执行器链）时；需已确认 workflowId 有效。	`bizapi:["<workflow>"]`
`stopWorkflow`	停止指定 workflowId 的窗口流程运行（MainCommandController）	需终止正在运行的流程、释放窗口与引擎，或规则命中「停止/取消」语义时；须传入正确 workflowId。	`bizapi:["<workflowId>"]`

NativeApiController

command	作用	何时调用	args
`cancelElementPickerApi`	取消元素拾取由外部调用触发，用于取消当前的元素拾取操作（NativeApiController）	需交互式拾取 UI 元素时；自动执行链通常改用 locateElementApi + 坐标。	bizapi:null
`captureAreaApi`	截取指定区域（NativeApiController）	需截屏、框选区域或带元素信息截图，作为找图/OCR/上报输入时。	`bizapi:{…}`
`captureMonitorApi`	截取指定显示器全屏（NativeApiController）	需截全屏并发送到通道或写入 static 时（如钉钉截图推送）。	`bizapi:{…}`
`captureRectApi`	捕获屏幕指定矩形区域（含元素信息）（NativeApiController）	需截屏、框选区域或带元素信息截图，作为找图/OCR/上报输入时。	`bizapi:{…}`
`checkAccessibilityPermissionApi`	检查 Accessibility 权限（NativeApiController）	调用 AX/元素 API 前检查或申请 macOS 辅助功能权限时。	bizapi:null
`clearAppCacheApi`	清除应用列表缓存（NativeApiController）	需列出本机已安装应用或刷新应用列表缓存时。	bizapi:null
`clickMouseApi`	点击鼠标（NativeApiController）	需在屏幕坐标单击/双击时；勿对未知坐标盲点后确认前台窗口。	`bizapi:{…}`
`compressImageApi`	压缩图片为 JPEG（NativeApiController）	截图过大需满足钉钉等媒体上传大小限制（image 约 1MB）时。	`bizapi:{…}`
`confirmElementPickerApi`	确认元素选择（在当前鼠标位置选择元素）由外部调用触发，用于在当前鼠标位置确认选择元素（NativeApiController）	需交互式拾取 UI 元素时；自动执行链通常改用 locateElementApi + 坐标。	bizapi:null
`copyLocalPathApi`	复制文件（NativeApiController）	需复制本机文件到新路径时（仅文件，非目录树）。	`bizapi:{…}`
`cropImageApi`	裁剪图像，输出写入 static（NativeApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`deleteLocalPathApi`	删除文件或目录（NativeApiController）	需删除本机文件；目录须 `recursive:true` 才能非空删除。	`bizapi:{…}`
`doubleClickMouseApi`	双击鼠标（NativeApiController）	需在屏幕坐标单击/双击时；勿对未知坐标盲点后确认前台窗口。	`bizapi:{…}`
`dragMouseApi`	拖拽鼠标（NativeApiController）	需拖拽或滚轮操作时；确认目标区域在前台。	`bizapi:{…}`
`ensureVirtualDisplayApi`	插入虚拟显示器（须已安装 RustDeskIddDriver，仅 Windows）（NativeApiController）	getDisplayHealthApi 显示无屏或 captureOk=false，且已安装 RustDesk Idd 驱动时。	`bizapi:{…}`
`findColorApi`	在图像中查找颜色（NativeApiController）	需在屏幕/图像中定位模板或颜色，供后续点击/高亮时。	`bizapi:{…}`
`findImageApi`	在图像中查找子图像（NativeApiController）	需在屏幕/图像中定位模板或颜色，供后续点击/高亮时。	`bizapi:{…}`
`findImageInDesktopApi`	在桌面屏幕上查找指定图片（NativeApiController）	需在屏幕/图像中定位模板或颜色，供后续点击/高亮时。	`bizapi:{…}`
`getDisplayHealthApi`	显示器健康检查：枚举数量、DXGI 探针、RustDeskIdd 驱动状态（NativeApiController）	桌面自动化前需确认是否有可用显示器/截屏能力，尤其无物理屏服务器。	bizapi:null
`getDominantColorsApi`	获取图像主色调（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	`bizapi:{…}`
`getElementAtPositionApi`	获取指定位置的 UI 元素信息（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	`bizapi:{…}`
`getElementPathAtPositionApi`	获取指定位置元素的完整层级路径（从根到目标元素）（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	`bizapi:{…}`
`getElementPathUnderMouseApi`	获取鼠标位置下元素的完整层级路径（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	bizapi:null
`getElementRectApi`	获取指定位置元素的矩形区域（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	`bizapi:{…}`
`getElementRectUnderMouseApi`	获取鼠标位置下元素的矩形区域（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	bizapi:null
`getElementTreeAtPositionApi`	获取指定位置元素的树形结构（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	`bizapi:{…}`
`getElementUnderMouseApi`	获取鼠标位置下的 UI 元素信息（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	bizapi:null
`getInstalledAppsApi`	获取本地已安装的应用列表（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	`bizapi:{…}`
`getMousePositionApi`	获取当前鼠标位置（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	bizapi:null
`getScreenInfoApi`	获取屏幕信息（NativeApiController）	已有 id/workflowId/workerId，需读取详情再编排下一步时。	bizapi:null
`getScreenRecordingStatusApi`	获取录屏进度（NativeApiController）	录屏进行中需展示帧数、时长等进度信息时。	bizapi:null
`grepLocalFilesApi`	在目录中 grep 搜索（NativeApiController）	需在项目/日志目录中按关键字或正则查找代码、配置、错误行时。	`bizapi:{…}`
`highlightAreaApi`	高亮屏幕区域（NativeApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`highlightRegionsApi`	高亮多个屏幕区域（NativeApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`humanMoveMouseApi`	模拟人类滑动鼠标使用贝塞尔曲线和随机抖动来模拟真实的人类鼠标移动轨迹（NativeApiController）	需将光标移到屏幕坐标时；坐标宜来自 findImage/getElementRect/captureRect。	`bizapi:{…}`
`isElementPickerRunningApi`	检查元素拾取是否正在运行（NativeApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	bizapi:null
`isInputListenerRunningApi`	检查输入监听状态（NativeApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	bizapi:null
`isScreenRecordingRunningApi`	是否正在录屏（NativeApiController）	需判断录屏会话是否仍在运行时。	bizapi:null
`isScreenshotRunningApi`	检查截图是否正在进行（NativeApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	bizapi:null
`keyDownApi`	按下并保持按键（NativeApiController）	需向当前焦点控件输入文字或按键时；前置：目标应用已聚焦。	`bizapi:{…}`
`keyUpApi`	释放按键（NativeApiController）	需向当前焦点控件输入文字或按键时；前置：目标应用已聚焦。	`bizapi:{…}`
`listLocalDirApi`	列出目录条目（NativeApiController，fast-glob）（NativeApiController）	需枚举某目录下文件/子目录路径时。	`bizapi:{…}`
`locateElementApi`	根据查询条件定位元素（NativeApiController）	需读取屏幕坐标处 UI 元素信息、路径或矩形时；前置：Accessibility 已授权。	`bizapi:{…}`
`locateElementByAncestorsApi`	根据 ancestors 路径定位元素（NativeApiController）	需读取屏幕坐标处 UI 元素信息、路径或矩形时；前置：Accessibility 已授权。	`bizapi:{…}`
`mkdirLocalPathApi`	创建目录（NativeApiController）	写入文件前需确保目录存在，或单独创建文件夹时。	`bizapi:{…}`
`moveLocalPathApi`	移动/重命名路径（NativeApiController）	需重命名或移动本机文件/目录时。	`bizapi:{…}`
`moveMouseApi`	移动鼠标到指定位置（NativeApiController）	需将光标移到屏幕坐标时；坐标宜来自 findImage/getElementRect/captureRect。	`bizapi:{…}`
`pathExistsLocalApi`	判断路径是否存在（NativeApiController）	仅需布尔存在性、不必读取 stat 详情时。	`bizapi:{…}`
`pressKeyApi`	按下按键（NativeApiController）	需向当前焦点控件输入文字或按键时；前置：目标应用已聚焦。	`bizapi:{…}`
`readLocalFileApi`	读取本地文件（NativeApiController）	需读取本机文本/配置/日志等内容供 AI 分析或后续 BizApi 使用时。	`bizapi:{…}`
`requestAccessibilityPermissionApi`	请求 Accessibility 权限（NativeApiController）	调用 AX/元素 API 前检查或申请 macOS 辅助功能权限时。	bizapi:null
`resizeImageApi`	缩放图像，输出写入 static（NativeApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`resolveStaticUrlApi`	将相对路径解析为 HTTP 访问 URL（/static/.	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`saveImageToStaticApi`	保存图片到 config/static/{bizId}/，返回相对路径（NativeApiController）	确认业务语义、参数与副作用符合当前自动执行目标时。	`bizapi:{…}`
`scrollMouseApi`	滚动鼠标（NativeApiController）	需拖拽或滚轮操作时；确认目标区域在前台。	`bizapi:{…}`
`selectFileApi`	选择文件（NativeApiController）	需用户选择本地文件/目录时；无人值守场景慎用（会阻塞弹窗）。	`bizapi:{…}`
`selectFolderApi`	选择文件夹（NativeApiController）	需用户选择本地文件/目录时；无人值守场景慎用（会阻塞弹窗）。	`bizapi:{…}`
`selectPathApi`	选择文件或文件夹（NativeApiController）	需用户选择本地文件/目录时；无人值守场景慎用（会阻塞弹窗）。	`bizapi:{…}`
`smoothMoveMouseApi`	平滑移动鼠标（NativeApiController）	需将光标移到屏幕坐标时；坐标宜来自 findImage/getElementRect/captureRect。	`bizapi:{…}`
`startElementPickerApi`	启动元素拾取模式启动后会实时追踪鼠标位置，获取并高亮鼠标下的 UI 元素（NativeApiController）	需立即启动运行；前置：资源已启用且参数齐备。	bizapi:null
`startScreenRecordingApi`	开始屏幕录屏（NativeApiController）	需录制桌面操作过程并保存为 MP4 时。	`bizapi:{…}`
`startScreenshotApi`	启动交互式框选截图（NativeApiController）	需立即启动运行；前置：资源已启用且参数齐备。	`bizapi:{…}`
`statLocalPathApi`	获取路径 stat（NativeApiController）	需判断文件/目录是否存在及大小、修改时间时。	`bizapi:{…}`
`stopElementPickerApi`	停止元素拾取模式（NativeApiController）	需中断运行或释放资源时。	bizapi:null
`stopHighlightApi`	停止所有高亮（NativeApiController）	需中断运行或释放资源时。	bizapi:null
`stopInputListenerApi`	停止全局输入监听（NativeApiController）	需中断运行或释放资源时。	bizapi:null
`stopScreenRecordingApi`	停止屏幕录屏并保存 MP4（NativeApiController）	startScreenRecordingApi 已启动后，需结束录制并获取视频路径时。	bizapi:null
`typeStringApi`	输入字符串（NativeApiController）	需向当前焦点控件输入文字或按键时；前置：目标应用已聚焦。	`bizapi:{…}`
`writeLocalFileApi`	写入本地文件（NativeApiController）	需将文本或 base64 内容写入本机文件时。	`bizapi:{…}`

API 详细说明

AiApiController

`abortAiStreamApi`

作用：中止Ai Stream（AiApiController）
何时调用：用户取消、超时或规则要求中断仍在进行的流式 AI 请求时；需已知 streamId。勿用于自动执行计划（无同步全文）。。勿用于自动执行计划（无同步全文）
依赖与顺序：自动执行链禁止使用；改用 chatAiCompleteApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 含 streamId；正文由 IPC 流式推送，非一次性 data
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { streamId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：自动执行助手禁止编排 *StreamApi
调用示例：

json

{"command":"abortAiStreamApi","args":{"streamId":"example"}}

`abortAiVoiceStreamApi`

作用：中止语音输入（AiApiController）
何时调用：仅前端流式展示；自动执行计划勿用，改用 chatAiCompleteApi。勿用于自动执行计划（无同步全文）。。勿用于自动执行计划（无同步全文）
依赖与顺序：自动执行链禁止使用；改用 chatAiCompleteApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 含 streamId；正文由 IPC 流式推送，非一次性 data
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { voiceSessionId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：自动执行助手禁止编排 *StreamApi
调用示例：

json

{"command":"abortAiVoiceStreamApi","args":{"voiceSessionId":"example"}}

`appendAiSessionMessageApi`

作用：追加AI 会话Message（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { sessionId: string; role: AiChatMessage['role']; content: string; attachments?: AiMessageAttachment[] }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"appendAiSessionMessageApi","args":{"sessionId":"session-example","role":"user","content":"你好"}}

`captureAndSendScreenshotToAiChannelApi`

作用：截屏、压缩并通过 AI 通道（钉钉）发送（AiApiController）
何时调用：自动执行助手需推送桌面截图时：工作台会话（无钉钉绑定）回传 static 链接；钉钉会话上传并推送。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId?: string; recipient?: string; sessionId?: string; monitorIndex?: number; caption?: string; maxBytes?: number; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"captureAndSendScreenshotToAiChannelApi","args":{"channelId":"example","recipient":"example","sessionId":"example","monitorIndex":1,"caption":"example","maxBytes":1}}

`chatAiCompleteApi`

作用：非流式：一次返回完整 assistant 文本（含思考合并为前缀块，便于展示）（AiApiController）
何时调用：自动执行链需在服务端完成一轮 AI 对话并将全文写入变量时；应已有 sessionId。。前置：有效 sessionId 与提供商凭证
依赖与顺序：前置：createAiSessionApi 或已有 sessionId
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { sessionId: string; think?: boolean; systemPromptSlug?: string | null }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：需要 AI 总结时用本 API，须传 sessionId
调用示例：

json

{"command":"chatAiCompleteApi","args":{"sessionId":"example","think":true,"systemPromptSlug":"example"}}

`chatAiStreamApi`

作用：流式 AI 对话：返回 streamId 并推送 token（AiApiController）
何时调用：用户在前端发起流式对话、需逐 token 推送时；自动执行/workflow 的 http-post 链请优先用 Complete 类 API。。勿用于自动执行计划（无同步全文）
依赖与顺序：自动执行链禁止使用；改用 chatAiCompleteApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 含 streamId；正文由 IPC 流式推送，非一次性 data
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { sessionId: string; think?: boolean; systemPromptSlug?: string | null }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：自动执行助手禁止编排 *StreamApi
调用示例：

json

{"command":"chatAiStreamApi","args":{"sessionId":"example","think":true,"systemPromptSlug":"example"}}

`clearAiSessionMessagesApi`

作用：清理AI 会话Messages（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { sessionId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"clearAiSessionMessagesApi","args":{"sessionId":"example"}}

`createAiSessionApi`

作用：新建AI 会话（AiApiController）
何时调用：用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 AiSessionCreateParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"createAiSessionApi","args":{"provider":"ollama","model":"llama3.2","think":false}}

`createAiTimerApi`

作用：新建 AI 调度任务：一次性延迟或重复 cron（AiApiController）
何时调用：需延迟/定时自动执行 BizApi（录屏结束、每天 8 点拉数据等）且落库可管理时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CreateAiTimerInput
bizapi-exec args：params 对象整包；bizapi-exec.args={"name":"延迟截图","delayMin":1,"calls":[{"command":"captureMonitorApi","args":{"monitorIndex":0,"bizId":"captures"}}]}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"createAiTimerApi","args":{"name":"延迟截图","delayMin":1,"calls":[{"command":"captureMonitorApi","args":{"monitorIndex":0,"bizId":"captures"}}]}}

`deleteAiChannelApi`

作用：删除AI 通道（AiApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteAiChannelApi","args":{"channelId":"example"}}

`deleteAiCustomProviderApi`

作用：设置Ai Provider Api Key（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { providerId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteAiCustomProviderApi","args":{"providerId":"example"}}

`deleteAiMessageAutoexecRuleApi`

作用：删除执行规则（AiApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { ruleId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteAiMessageAutoexecRuleApi","args":{"ruleId":"example"}}

`deleteAiPromptApi`

作用：删除AI 提示词（AiApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { promptId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteAiPromptApi","args":{"promptId":"example"}}

`deleteAiSessionApi`

作用：删除AI 会话（AiApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { sessionId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteAiSessionApi","args":{"sessionId":"example"}}

`deleteAiTimerApi`

作用：删除 AI 一次性延迟定时器（AiApiController）
何时调用：取消尚未触发的延迟任务，或清理测试数据时。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { timerId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteAiTimerApi","args":{"timerId":"example"}}

`finishAiVoiceStreamApi`

作用：结束语音输入并返回转写文本（AiApiController）
何时调用：仅前端流式展示；自动执行计划勿用，改用 chatAiCompleteApi。勿用于自动执行计划（无同步全文）。。勿用于自动执行计划（无同步全文）
依赖与顺序：自动执行链禁止使用；改用 chatAiCompleteApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 含 streamId；正文由 IPC 流式推送，非一次性 data
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { voiceSessionId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：自动执行助手禁止编排 *StreamApi
调用示例：

json

{"command":"finishAiVoiceStreamApi","args":{"voiceSessionId":"example"}}

`getAiChannelApi`

作用：获取AI 通道（AiApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getAiChannelApi","args":{"channelId":"example"}}

`getAiPromptBodyApi`

作用：获取AI 提示词Body（AiApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { promptId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getAiPromptBodyApi","args":{"promptId":"example"}}

`getAiSessionApi`

作用：获取AI 会话（AiApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { sessionId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getAiSessionApi","args":{"sessionId":"example"}}

`listAiChannelsApi`

作用：列出AI 通道s（AiApiController）
何时调用：配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiChannelsApi","args":null}

`listAiCustomProvidersApi`

作用：设置Ai Provider Api Key（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiCustomProvidersApi","args":null}

`listAiExecutorTypesApi`

作用：列出Ai Executor Types（AiApiController）
何时调用：配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。
依赖与顺序：编排 tryRunAiExecutorApi 前列出合法节点 slug
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiExecutorTypesApi","args":null}

`listAiMessageAutoexecRulesApi`

作用：列出执行规则s（AiApiController）
何时调用：配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiMessageAutoexecRulesApi","args":null}

`listAiModelsApi`

作用：列出指定 AI 提供商下可用模型（AiApiController）
何时调用：配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- params（必填）类型 AiListModelsParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiModelsApi","args":{"provider":"ollama"}}

`listAiPromptsApi`

作用：列出AI 提示词s（AiApiController）
何时调用：配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiPromptsApi","args":null}

`listAiProvidersApi`

作用：列出可用 AI 提供商（ollama/deepseek/cursor）（AiApiController）
何时调用：配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiProvidersApi","args":null}

`listAiSessionsApi`

作用：列出AI 会话s（AiApiController）
何时调用：配置 AI 能力前需枚举提供商、模型、会话、规则等选项时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- params（可选）类型 { limit?: number }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiSessionsApi","args":{"limit":1}}

`listAiTimersApi`

作用：列出 AI 调度任务（一次性延迟 + 重复 cron）（AiApiController）
何时调用：需查看 AI 创建的延迟/定时 BizApi 任务时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data 为数组清单（提供商/模型/会话/规则等）
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listAiTimersApi","args":null}

`resetAiBuiltinPromptApi`

作用：将内置助手恢复为应用内置默认 system 提示词（覆盖库中已改动的正文）（AiApiController）
何时调用：升级应用后需同步最新内置助手，或误改内置正文后恢复时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { slug: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：仅内置资源可操作
调用示例：

json

{"command":"resetAiBuiltinPromptApi","args":{"slug":"example"}}

`resetAiChannelDingTalkSessionsApi`

作用：重置通道下全部钉钉 AI 会话绑定（AiApiController）
何时调用：通道改了助手/模型后需让各钉钉聊天下次入站重新建会话，或清理错误绑定时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"resetAiChannelDingTalkSessionsApi","args":{"channelId":"example"}}

`sendAiChannelOutboundImageApi`

作用：向 AI 通道发送图片（钉钉：上传 media + 图片消息）（AiApiController）
何时调用：已有 static 相对路径 imagePath（可先 compressImageApi），需推送到钉钉会话时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId: string; recipient: string; imagePath: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"sendAiChannelOutboundImageApi","args":{"channelId":"example","recipient":"example","imagePath":"example"}}

`sendAiChannelOutboundMarkdownApi`

作用：发送AI 通道Outbound Markdown（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：向外部通道（如钉钉）发送消息
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId: string; recipient: string; title?: string; text: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"sendAiChannelOutboundMarkdownApi","args":{"channelId":"example","recipient":"example","title":"example","text":"example"}}

`sendAiChannelOutboundVideoApi`

作用：向 AI 通道发送视频（钉钉：上传 video + 封面图 + sampleVideo）（AiApiController）
何时调用：已有 static 相对路径 mp4（如 stopScreenRecordingApi 返回的 videoPath），需推送到钉钉会话时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId?: string; recipient?: string; sessionId?: string; videoPath: string; picImagePath?: string; durationSec?: number; caption?: string; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"sendAiChannelOutboundVideoApi","args":{"channelId":"example","recipient":"example","sessionId":"example","videoPath":"example","picImagePath":"example","durationSec":1,"caption":"example"}}

`sendAiVoiceAudioChunkApi`

作用：推送 PCM 音频块（16kHz mono int16）（AiApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { voiceSessionId: string; pcmBase64: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"sendAiVoiceAudioChunkApi","args":{"voiceSessionId":"example","pcmBase64":"example"}}

`setAiProviderApiKeyApi`

作用：设置Ai Provider Api Key（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { provider: AiProviderId; apiKey?: string | null; url?: string | null; providerType?: string | null }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"setAiProviderApiKeyApi","args":{"provider":"ollama","apiKey":"example","url":"example","providerType":"example"}}

`startAiChannelStreamListenApi`

作用：启动AI 通道Stream Listen（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：启动通道 Stream 长连接监听
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"startAiChannelStreamListenApi","args":{"channelId":"example"}}

`startAiVoiceStreamApi`

作用：开始 AI 语音输入会话（按住说话）（AiApiController）
何时调用：用户在 AI 对话输入框按住麦克风开始录音时。勿用于自动执行计划（无同步全文）。。勿用于自动执行计划（无同步全文）
依赖与顺序：自动执行链禁止使用；改用 chatAiCompleteApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 含 streamId；正文由 IPC 流式推送，非一次性 data
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { sessionId?: string; language?: string; whisperModel?: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：自动执行助手禁止编排 *StreamApi
调用示例：

json

{"command":"startAiVoiceStreamApi","args":{"sessionId":"example","language":"example","whisperModel":"example"}}

`startScreenRecordingWithAutoStopAndSendApi`

作用：开始录屏并创建延迟任务：到时停录并推送钉钉（AiApiController）
何时调用：需录制固定时长桌面操作并自动推送：工作台会话回传 static 链接；钉钉会话上传视频。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId?: string; recipient?: string; sessionId?: string; delayMs?: number; delaySec?: number; delayMin?: number; durationMs?: number; durationSec?: number; durationMin?: number; caption?: string; monitorIndex?: number; fps?: number; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"startScreenRecordingWithAutoStopAndSendApi","args":{"channelId":"example","recipient":"example","sessionId":"example","delayMs":1,"delaySec":1,"delayMin":1,"durationMs":1,"durationSec":1,"durationMin":1,"caption":"example","monitorIndex":1,"fps":1}}

`stopAiChannelStreamListenApi`

作用：停止AI 通道Stream Listen（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"stopAiChannelStreamListenApi","args":{"channelId":"example"}}

`stopScreenRecordingAndSendToAiChannelApi`

作用：停止录屏并通过 AI 通道发送视频（AiApiController）
何时调用：录屏已 startScreenRecordingApi 启动，需结束录制并推送：工作台会话回传 static 链接；钉钉会话上传视频。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId?: string; recipient?: string; sessionId?: string; caption?: string; picImagePath?: string; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"stopScreenRecordingAndSendToAiChannelApi","args":{"channelId":"example","recipient":"example","sessionId":"example","caption":"example","picImagePath":"example"}}

`testAiChannelApi`

作用：测试AI 通道（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"testAiChannelApi","args":{"channelId":"example"}}

`tryRunAiExecutorApi`

作用：试跑单个内置工作流节点（AiApiController）
何时调用：需单独执行一个节点（HTTP、脚本、钉钉等）且不必 startWorkflow 时；config 见 executorNodeTypesDoc / 自动执行助手内嵌节点表。
依赖与顺序：前置：listAiExecutorTypesApi 或已知 executorType；executorConfig 字段见 executorNodeTypesDoc
副作用：节点副作用取决于 executorType（HTTP、写文件、通知等）；不创建 workflow_worker 运行记录
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { executorType: string; executorConfig?: Record<string, unknown>; variables?: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={"executorType":"http-get","executorConfig":{"url":"https://httpbin.org/get","saveToVariable":"body"},"variables":{"body":""}}
注意：试跑执行器，不写入正式运行记录；executorType/config 以 executorNodeTypesDoc（节点 slug 表）为准，勿与 workflowId/workerId 混淆
调用示例：

json

{"command":"tryRunAiExecutorApi","args":{"executorType":"http-get","executorConfig":{"url":"https://httpbin.org/get","saveToVariable":"body"},"variables":{"body":""}}}

`updateAiSessionApi`

作用：更新AI 会话（AiApiController）
何时调用：已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { sessionId: string; provider?: AiProviderId; model?: string; think?: boolean; baseUrl?: string | null; conversationTitle?: string | null; systemPromptSlug?: string | null; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateAiSessionApi","args":{"sessionId":"example","provider":"ollama","model":"example","think":true,"baseUrl":"example","conversationTitle":"example","systemPromptSlug":"example"}}

`updateAiTimerApi`

作用：更新 AI 调度任务（AiApiController）
何时调用：已存在 timerId，需改 delayMs、cronExpr、enabled、名称或 BizApi 步骤时。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { timerId: string } & UpdateAiTimerInput
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateAiTimerApi","args":{"timerId":"timer-example","cronExpr":"0 30 8 * * *","enabled":true}}

`upsertAiChannelApi`

作用：新增或更新AI 通道（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { channelId?: string; kind: AiChannelKind; name: string; enabled?: boolean; config: AiChannelConfig }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"upsertAiChannelApi","args":{"channelId":"example","kind":"…","name":"example","enabled":true,"config":"…"}}

`upsertAiCustomProviderApi`

作用：设置Ai Provider Api Key（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpsertAiCustomProviderInput
bizapi-exec args：params 对象整包；bizapi-exec.args="…"
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"upsertAiCustomProviderApi","args":"…"}

`upsertAiMessageAutoexecRuleApi`

作用：新增或更新执行规则（AiApiController）。配置助手回复后触发的执行器规则
何时调用：配置或查询 AI 仪表盘 → 执行规则（助手回复后触发的执行器链）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { ruleId?: string; name: string; enabled?: boolean; scopeAssistantSlug?: string | null; matchType: AiAutoexecMatchType; pattern?: string | null; hooks: AiAutoexecHookCommand[]; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"upsertAiMessageAutoexecRuleApi","args":{"name":"示例规则","matchType":"keyword","pattern":"执行","hooks":[]}}

`upsertAiPromptApi`

作用：新增或更新AI 提示词（AiApiController）
何时调用：操作 AI 会话/提示词/通道/凭证等能力，且与当前自动执行或对话上下文一致时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { promptId?: string; slug: string; name: string; category?: string; content: string; sortOrder?: number }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"upsertAiPromptApi","args":{"promptId":"example","slug":"example","name":"example","category":"example","content":"example","sortOrder":1}}

AiSingleExecutorRunner

`runNode`

作用：试跑单个执行器节点（AiSingleExecutorRunner）
何时调用：自动执行或调试时需要单独跑一个节点（如 http-get、run-script、dingtalk-notify），且不必启停整条 Workflow 时。
依赖与顺序：前置：listAiExecutorTypesApi 或已知 executorType；executorConfig 字段见 executorNodeTypesDoc
副作用：节点副作用取决于 executorType（HTTP、写文件、通知等）；不创建 workflow_worker 运行记录
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- executorType（必填）类型 string
- config（必填）类型 Record<string, unknown>
- variables（必填）类型 Record<string, unknown>
bizapi-exec args：多形参对象；bizapi-exec.args=["http-get",{"url":"https://httpbin.org/get","saveToVariable":"body"},{"body":""}]
注意：executorType/config 以 executorNodeTypesDoc（节点 slug 表）为准，勿与 workflowId/workerId 混淆
调用示例：

json

{"command":"runNode","args":["http-get",{"url":"https://httpbin.org/get","saveToVariable":"body"},{"body":""}]}

DataSourceApiController

`connectDataSourceApi`

作用：连接数据源（建立 managed 连接）：业务逻辑在 DataSourceService.connect（DataSourceApiController）
何时调用：数据源已配置且需建立运行时 TypeORM 连接，供后续读写业务表时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- dataSourceId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"dataSourceId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"connectDataSourceApi","args":["example"]}

`createDataSourceApi`

作用：新建数据源：业务逻辑在 DataSourceService.create（DataSourceApiController）
何时调用：用户或规则需注册新的 sqlite/mysql/pgsql 等数据源，且 enabled=1 时会自动尝试连接。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CreateDataSourceInput
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"createDataSourceApi","args":{"name":"示例数据源","driver":"sqlite","filePath":"./data/example.db"}}

`deleteDataSourceApi`

作用：删除数据源：业务逻辑在 DataSourceService.remove（DataSourceApiController）
何时调用：确认删除不再使用的数据源及其表元数据时；会先断开 managed 连接。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteDataSourceApi","args":[1]}

`disconnectDataSourceApi`

作用：断开数据源 managed 连接：业务逻辑在 DataSourceService.disconnect（DataSourceApiController）
何时调用：释放连接资源、切换配置前断开，或数据源暂时停用时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- dataSourceId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"dataSourceId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"disconnectDataSourceApi","args":["example"]}

`ensureDefaultDataSourceApi`

作用：确保默认数据集存在并返回其 dataSourceId：业务逻辑在 DataSourceService.ensureDefaultDataSource（DataSourceApiController）
何时调用：窗口/节点「不选数据源直接建表」时，需要一个隐式归属的数据集。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"ensureDefaultDataSourceApi","args":null}

`getDataSourceConnectionStatusApi`

作用：断开数据源 managed 连接：业务逻辑在 DataSourceService.disconnect（DataSourceApiController）
何时调用：释放连接资源、切换配置前断开，或数据源暂时停用时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- dataSourceId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"dataSourceId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getDataSourceConnectionStatusApi","args":["example"]}

`getDataSourceDetailApi`

作用：数据源详情（含表/列/索引元数据）：业务逻辑在 DataSourceService.getDetail（DataSourceApiController）
何时调用：需读取某数据源完整配置、表结构，或在 saveTables 前确认当前 schema 时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- dataSourceId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"dataSourceId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getDataSourceDetailApi","args":["example"]}

`getDataSourceListApi`

作用：数据源分页列表：业务逻辑在 DataSourceService.list（DataSourceApiController）
何时调用：数据管理页浏览/筛选数据源，或后续 connect/saveTables 需先取得 dataSourceId 时（宜放在链首）。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data：{ list, total, page, pageSize }；从 list 项取后续 API 所需 id/workflowId/workerId
形参：
- params（必填）类型 DataSourceListParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getDataSourceListApi","args":{"page":1,"pageSize":10}}

`getDataSourceSchemaDiffApi`

作用：保存表级表单 UI 配置（元数据 only，不同步物理库）：业务逻辑在 DataSourceService.updateTableFormUiConfig（DataSourceApiController）
何时调用：数据管理页为某张表配置新增/编辑表单的控件、标签、值类型等 UI 行为时；须先存在表结构元数据。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- dataSourceId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"dataSourceId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getDataSourceSchemaDiffApi","args":["example"]}

`listManagedTablesApi`

作用：列出当前分域内所有「有业务编码」的逻辑表：业务逻辑在 DataSourceService.listManagedTables（DataSourceApiController）
何时调用：需要全局 tableCode 选择器、或窗口数据表格面板列出可操作表时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"listManagedTablesApi","args":null}

`managedTableCountApi`

作用：统计 managed 数据源表行数（支持单字段搜索）：业务逻辑在 DataSourceService.managedTableCount（DataSourceApiController）
何时调用：与 managedTableFindApi 配合做分页 total 统计时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { dataSourceId: string; tableName?: string; tableCode?: string; options?: { search?: { field: string; value: string; operator?: 'include' | 'exclude' | 'eq' | 'ne' } }; }
bizapi-exec args：params 对象整包；bizapi-exec.args={"dataSourceId":"example","tableName":"example","tableCode":"example","options":{"search":{"field":"example","value":"example"}}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"managedTableCountApi","args":{"dataSourceId":"example","tableName":"example","tableCode":"example","options":{"search":{"field":"example","value":"example"}}}}

`managedTableDeleteApi`

作用：删除 managed 数据源表行：业务逻辑在 DataSourceService.managedTableDelete（DataSourceApiController）
何时调用：数据管理页删除行时；criteria 通常为主键字段。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { dataSourceId: string; tableName?: string; tableCode?: string; criteria: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"managedTableDeleteApi","args":{}}

`managedTableFindApi`

作用：查询 managed 数据源表数据（分页/排序/单字段搜索）：业务逻辑在 DataSourceService.managedTableFind（DataSourceApiController）
何时调用：数据管理页浏览业务表行数据，需分页、排序或按单字段搜索时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { dataSourceId: string; tableName?: string; tableCode?: string; options?: ManagedTableRowOptions }
bizapi-exec args：params 对象整包；bizapi-exec.args={"dataSourceId":"example","tableName":"example","tableCode":"example","options":
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"managedTableFindApi","args":{"dataSourceId":"example","tableName":"example","tableCode":"example","options":{}}}

`managedTableInsertApi`

作用：向 managed 数据源表插入一行：业务逻辑在 DataSourceService.managedTableInsert（DataSourceApiController）
何时调用：数据管理页新增业务表行数据时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { dataSourceId: string; tableName?: string; tableCode?: string; data: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"managedTableInsertApi","args":{}}

`managedTableUpdateApi`

作用：更新 managed 数据源表行：业务逻辑在 DataSourceService.managedTableUpdate（DataSourceApiController）
何时调用：数据管理页编辑已有行时；criteria 通常为主键字段。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { dataSourceId: string; tableName?: string; tableCode?: string; criteria: Record<string, unknown>; data: Record<string, unknown>; }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"managedTableUpdateApi","args":{}}

`resetDataSourceConnectionApi`

作用：断开数据源 managed 连接：业务逻辑在 DataSourceService.disconnect（DataSourceApiController）
何时调用：释放连接资源、切换配置前断开，或数据源暂时停用时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- dataSourceId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"dataSourceId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"resetDataSourceConnectionApi","args":["example"]}

`resolveTableByCodeApi`

作用：按业务编码全局定位表：业务逻辑在 DataSourceService.resolveTableRefByCode（DataSourceApiController）
何时调用：需要由 tableCode 反查 { dataSourceId, tableName } 时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- tableCode（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"tableCode":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"resolveTableByCodeApi","args":["example"]}

`saveDataSourceTablesApi`

作用：保存数据源表结构（元数据 + 同步 managed schema）：业务逻辑在 DataSourceService.saveTables（DataSourceApiController）
何时调用：数据管理页配置完表/列后持久化，或 workflow 需同步业务表定义时；保存后会 forceRecreate 连接。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { dataSourceId: string; tables: DataSourceTableInput[] }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"saveDataSourceTablesApi","args":{"dataSourceId":"ds-example","tables":[]}}

`syncDataSourceSchemaApi`

作用：保存表级表单 UI 配置（元数据 only，不同步物理库）：业务逻辑在 DataSourceService.updateTableFormUiConfig（DataSourceApiController）
何时调用：数据管理页为某张表配置新增/编辑表单的控件、标签、值类型等 UI 行为时；须先存在表结构元数据。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- dataSourceId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"dataSourceId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"syncDataSourceSchemaApi","args":["example"]}

`syncPhysicalTablesFromDatabaseApi`

作用：断开数据源 managed 连接：业务逻辑在 DataSourceService.disconnect（DataSourceApiController）
何时调用：释放连接资源、切换配置前断开，或数据源暂时停用时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- dataSourceId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"dataSourceId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"syncPhysicalTablesFromDatabaseApi","args":["example"]}

`tableBatchInsertByCodeApi`

作用：按业务编码批量插入：业务逻辑在 DataSourceService.tableBatchInsertByCode（DataSourceApiController）
何时调用：执行器/脚本/Excel 导入按 tableCode 批量写入数据时。
依赖与顺序：前置：workerId、tableName；宜 ensureTableInitializedApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为行数组或 count；表由 workerId+tableName 定位
形参：
- params（必填）类型 { tableCode: string; dataList: Record<string, unknown>[] }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"tableBatchInsertByCodeApi","args":{}}

`tableClearByCodeApi`

作用：按业务编码清空表：业务逻辑在 DataSourceService.tableClearByCode（DataSourceApiController）
何时调用：执行器/脚本按 tableCode 清空整表（不可逆）时。
依赖与顺序：前置：workerId、tableName；宜 ensureTableInitializedApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为行数组或 count；表由 workerId+tableName 定位
形参：
- params（必填）类型 { tableCode: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"tableClearByCodeApi","args":{"tableCode":"example"}}

`tableCountByCodeApi`

作用：按业务编码统计行数（等值条件）：业务逻辑在 DataSourceService.tableCountByCode（DataSourceApiController）
何时调用：执行器/脚本按 tableCode 统计行数时。
依赖与顺序：前置：workerId、tableName；宜 ensureTableInitializedApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为行数组或 count；表由 workerId+tableName 定位
形参：
- params（必填）类型 { tableCode: string; criteria?: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"tableCountByCodeApi","args":{}}

`tableDeleteByCodeApi`

作用：按业务编码删除（等值条件）：业务逻辑在 DataSourceService.tableDeleteByCode（DataSourceApiController）
何时调用：执行器/脚本按 tableCode 删除满足条件的行时。
依赖与顺序：前置：workerId、tableName；宜 ensureTableInitializedApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为行数组或 count；表由 workerId+tableName 定位
形参：
- params（必填）类型 { tableCode: string; criteria: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"tableDeleteByCodeApi","args":{}}

`tableFindByCodeApi`

作用：按业务编码查询表数据（等值条件）：业务逻辑在 DataSourceService.tableFindByCode（DataSourceApiController）。查询执行器动态表数据
何时调用：执行器/脚本按 tableCode 读取多行数据时。
依赖与顺序：前置：workerId、tableName；宜 ensureTableInitializedApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为行数组或 count；表由 workerId+tableName 定位
形参：
- params（必填）类型 { tableCode: string; criteria?: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"tableFindByCodeApi","args":{}}

`tableFindOneByCodeApi`

作用：按业务编码查询单条：业务逻辑在 DataSourceService.tableFindOneByCode（DataSourceApiController）。查询执行器动态表数据
何时调用：执行器/脚本按 tableCode 读取单行数据时。
依赖与顺序：前置：workerId、tableName；宜 ensureTableInitializedApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为行数组或 count；表由 workerId+tableName 定位
形参：
- params（必填）类型 { tableCode: string; criteria?: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"tableFindOneByCodeApi","args":{}}

`tableInsertByCodeApi`

作用：按业务编码插入一行：业务逻辑在 DataSourceService.tableInsertByCode（DataSourceApiController）。向执行器表插入一行
何时调用：执行器/脚本按 tableCode 写入单行数据时。
依赖与顺序：前置：workerId、tableName；宜 ensureTableInitializedApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为行数组或 count；表由 workerId+tableName 定位
形参：
- params（必填）类型 { tableCode: string; data: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"tableInsertByCodeApi","args":{}}

`tableUpdateByCodeApi`

作用：按业务编码更新（等值条件）：业务逻辑在 DataSourceService.tableUpdateByCode（DataSourceApiController）
何时调用：执行器/脚本按 tableCode 更新满足条件的行时。
依赖与顺序：前置：workerId、tableName；宜 ensureTableInitializedApi
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为行数组或 count；表由 workerId+tableName 定位
形参：
- params（必填）类型 { tableCode: string; criteria: Record<string, unknown>; data: Record<string, unknown> }
bizapi-exec args：params 对象整包；bizapi-exec.args={}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"tableUpdateByCodeApi","args":{}}

`testDataSourceConnectionApi`

作用：测试数据源连接：业务逻辑在 DataSourceService.testConnection（DataSourceApiController）
何时调用：新建/编辑后验证连接参数是否正确，或排查连接失败原因时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"testDataSourceConnectionApi","args":[1]}

`updateDataSourceApi`

作用：更新数据源配置：业务逻辑在 DataSourceService.update（DataSourceApiController）
何时调用：已有数据源 id，需修改名称、连接参数或 enabled 等字段时；宜先 getDetail 确认。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 { id: number; model: Partial<CreateDataSourceInput> }
bizapi-exec args：params 对象整包；bizapi-exec.args={"id":1,"model":
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateDataSourceApi","args":{"id":1,"model":{}}}

`updateTableFormUiConfigApi`

作用：保存表级表单 UI 配置（元数据 only，不同步物理库）：业务逻辑在 DataSourceService.updateTableFormUiConfig（DataSourceApiController）
何时调用：数据管理页为某张表配置新增/编辑表单的控件、标签、值类型等 UI 行为时；须先存在表结构元数据。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpdateTableFormUiConfigParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateTableFormUiConfigApi","args":{"dataSourceId":"ds-example","tableName":"orders","fields":[]}}

MainApiController

`addCapturedElementApi`

作用：新增采集元素（MainApiController）
何时调用：用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CapturedElementEntity
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"addCapturedElementApi","args":{"name":"示例元素"}}

`addFolderApi`

作用：新增文件夹（MainApiController）
何时调用：用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 AddFolderParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"addFolderApi","args":{"name":"示例分组","parentId":1,"businessType":"workflow","businessId":"example-workflow"}}

`addScreenshotApi`

作用：新增截图（MainApiController）
何时调用：用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ScreenshotEntity
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：截屏结果可写入 static，供 findImage/crop 等后续步骤使用
调用示例：

json

{"command":"addScreenshotApi","args":{"name":"示例截图","imagePath":"screenshots/example.png"}}

`addWorkflowApi`

作用：新增窗口（MainApiController）
何时调用：用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 WorkflowEntity
bizapi-exec args：params 对象整包；bizapi-exec.args={"name":"示例窗口","host":"https://example.com"}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"addWorkflowApi","args":{"name":"示例窗口","host":"https://example.com"}}

`addWorkflowWorkerApi`

作用：新增执行器（MainApiController）
何时调用：用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CreateWorkerParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"addWorkflowWorkerApi","args":{"name":"示例执行器","workflowId":"example-workflow"}}

`batchDeleteWorkflowVariablesApi`

作用：批量删除变量（按主键 id，当前分域）（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- ids（必填）类型 number[]
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[[1]]（勿写 {"ids":值}）
注意：批量 API：ids 为数据库主键 id 数组，非 workflowId
调用示例：

json

{"command":"batchDeleteWorkflowVariablesApi","args":[[1]]}

`batchStartWorkflowWorkerApi`

作用：批量Start执行器（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- ids（必填）类型 number[]
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[[1]]（勿写 {"ids":值}）
注意：批量 API：ids 为数据库主键 id 数组，非 workflowId
调用示例：

json

{"command":"batchStartWorkflowWorkerApi","args":[[1]]}

`batchStopWorkflowWorkerApi`

作用：批量Stop执行器（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- ids（必填）类型 number[]
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[[1]]（勿写 {"ids":值}）
注意：批量 API：ids 为数据库主键 id 数组，非 workflowId
调用示例：

json

{"command":"batchStopWorkflowWorkerApi","args":[[1]]}

`clearCacheByWorkflowIdApi`

作用：清理Cache By窗口Id（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- workflowId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"workflowId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"clearCacheByWorkflowIdApi","args":["example"]}

`clearCookieApi`

作用：清理Cookie（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：前置：workflowId
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ClearCookieApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"clearCookieApi","args":{"workflowId":"example","type":"all"}}

`copyWorkflowApi`

作用：复制窗口（MainApiController）
何时调用：基于已有记录快速克隆一份（保留结构、改名称）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CopyWorkflowApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"copyWorkflowApi","args":{"id":1}}

`createCronTaskApi`

作用：新建定时任务（window / executor / ai）：业务逻辑在 CronManager.createCronTask（MainApiController）
何时调用：用户或规则明确要求新建资源，且后续步骤依赖返回的 id/data（如写入变量）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时 data 常为新资源 id 或创建结果对象
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CreateCronTaskInput
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"createCronTaskApi","args":{"targetKind":"window","name":"示例定时任务","cronExpr":"0 0 9 * * *","workflowId":"example-workflow"}}

`deleteCapturedElementApi`

作用：删除采集元素（MainApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteCapturedElementApi","args":[1]}

`deleteCronTaskApi`

作用：删除定时任务，业务逻辑在 CronManager.deleteCronTask（MainApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteCronTaskApi","args":[1]}

`deleteFolderApi`

作用：删除文件夹（MainApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 DeleteFolderParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteFolderApi","args":{"id":1}}

`deleteScreenshotApi`

作用：删除截图（MainApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：截屏结果可写入 static，供 findImage/crop 等后续步骤使用
调用示例：

json

{"command":"deleteScreenshotApi","args":[1]}

`deleteWorkflowApi`

作用：删除窗口（MainApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确认 id 时调用。勿在未确…。勿在未确认 id 时调用
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteWorkflowApi","args":[1]}

`deleteWorkflowVariablesApi`

作用：删除窗口Variables（MainApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteWorkflowVariablesApi","args":[1]}

`deleteWorkflowWorkerApi`

作用：删除执行器（MainApiController）
何时调用：确认删除、清理测试数据或规则命中「删除」语义时；通常先 get 校验再 delete。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"deleteWorkflowWorkerApi","args":[1]}

`exportWorkflowsApi`

作用：批量导出窗口配置为 Excel（按列表主键 id）（MainApiController）。按窗口主键 id 列表导出 Excel
何时调用：需要导出文件供下载、备份或传给下游节点（如写文件、上传）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 常含 base64 或文件路径，体积可能较大
形参：
- params（必填）类型 { ids: number[] }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"exportWorkflowsApi","args":{"ids":[1]}}

`exportWorkflowVariablesByWorkflowIdsApi`

作用：按窗口 ID 批量导出变量（与导入模板列一致）（MainApiController）
何时调用：需要导出文件供下载、备份或传给下游节点（如写文件、上传）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 常含 base64 或文件路径，体积可能较大
形参：
- params（必填）类型 { workflowIds: string[] }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"exportWorkflowVariablesByWorkflowIdsApi","args":{"workflowIds":["example-workflow"]}}

`exportWorkflowVariablesExcelApi`

作用：导出变量为 Excel（按变量主键 id）（MainApiController）
何时调用：需要导出文件供下载、备份或传给下游节点（如写文件、上传）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 常含 base64 或文件路径，体积可能较大
形参：
- params（必填）类型 { ids: number[] }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"exportWorkflowVariablesExcelApi","args":{"ids":[1]}}

`focusWorkflowWinApi`

作用：聚焦窗口Win（MainApiController）
何时调用：需要把用户注意力切到某窗口（调试或人工介入）时。。前置：窗口进程已存在
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- workflowId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"workflowId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"focusWorkflowWinApi","args":["example"]}

`getCapturedElementByIdApi`

作用：获取采集元素By Id（MainApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getCapturedElementByIdApi","args":[1]}

`getCapturedElementListApi`

作用：采集元素分页列表（MainApiController）
何时调用：需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data：{ list, total, page, pageSize }；从 list 项取后续 API 所需 id/workflowId/workerId
形参：
- params（必填）类型 CapturedElementListParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"folderId":1,"workflowId":"example","name":"example"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getCapturedElementListApi","args":{"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"folderId":1,"workflowId":"example","name":"example"}}}

`getCookiesApi`

作用：获取Cookies（MainApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：前置：workflowId
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- workflowId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"workflowId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getCookiesApi","args":["example"]}

`getCronTaskListApi`

作用：定时任务分页列表：业务逻辑在 CronManager.listCronTasks（MainApiController）
何时调用：需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data：{ list, total, page, pageSize }；从 list 项取后续 API 所需 id/workflowId/workerId
形参：
- params（必填）类型 GetCronTaskListParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"name":"example","bizType":"example","status":"example"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getCronTaskListApi","args":{"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"name":"example","bizType":"example","status":"example"}}}

`getFolderTreeApi`

作用：获取文件夹Tree（MainApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 FolderTreeParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getFolderTreeApi","args":{"businessType":"workflow","businessId":"example-workflow"}}

`getLogsListApi`

作用：Logs分页列表（MainApiController）
何时调用：需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data：{ list, total, page, pageSize }；从 list 项取后续 API 所需 id/workflowId/workerId
形参：
- params（必填）类型 GetLogsListParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"workflowId":"example","name":"example"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getLogsListApi","args":{"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"workflowId":"example","name":"example"}}}

`getPlatformInfoApi`

作用：获取Platform Info（MainApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为平台/UA 信息对象
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getPlatformInfoApi","args":null}

`getScreenshotListApi`

作用：截图分页列表（MainApiController）
何时调用：需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data：{ list, total, page, pageSize }；从 list 项取后续 API 所需 id/workflowId/workerId
形参：
- params（必填）类型 ScreenshotListParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"folderId":1,"workflowId":"example","name":"example"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getScreenshotListApi","args":{"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"folderId":1,"workflowId":"example","name":"example"}}}

`getStatisticsDetailListApi`

作用：Statistics Detail分页列表（MainApiController）
何时调用：需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data：{ list, total, page, pageSize }；从 list 项取后续 API 所需 id/workflowId/workerId
形参：
- params（必填）类型 GetStatisticsDetailListParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"page":1,"pageSize":1,"search":{"workflowId":"example","createdAt":"example"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getStatisticsDetailListApi","args":{"page":1,"pageSize":1,"search":{"workflowId":"example","createdAt":"example"}}}

`getStatisticsListApi`

作用：运行统计Statistics分页列表（MainApiController）
何时调用：需要对窗口流程进行运行统计分析时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data：{ list, total, page, pageSize }；从 list 项取后续 API 所需 id/workflowId/workerId
形参：
- params（必填）类型 GetStatisticsListParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"search":{"workflowId":"example","createdAt":"example"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getStatisticsListApi","args":{"search":{"workflowId":"example","createdAt":"example"}}}

`getUnusedScreenshotsApi`

作用：获取Unused截图s（MainApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getUnusedScreenshotsApi","args":null}

`getUserAgentApi`

作用：生成 User-Agent（MainApiController，user-agents 库）（MainApiController）
何时调用：需按平台/浏览器/版本生成 UA；未传 platform 时使用当前运行环境。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为平台/UA 信息对象
形参：
- params（可选）类型 BuildUserAgentParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getUserAgentApi","args":{"platform":"MacIntel","browserType":"chrome","browserMajorVersion":124}}

`getWorkflowListApi`

作用：窗口分页列表（MainApiController）。分页查询窗口元数据，不含完整画布 json 时仍可能较大
何时调用：需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data.list[] 含 id、workflowId、name、host、enabled、status 等；json 字段体积大，自动执行总结时勿复述全量画布
形参：
- params（必填）类型 GetWorkflowListParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"workflowId":"example","name":"example","enabled":"all"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getWorkflowListApi","args":{"page":1,"pageSize":1,"orderBy":"example","orderDirection":"asc","search":{"workflowId":"example","name":"example","enabled":"all"}}}

`getWorkflowVariablesApi`

作用：获取所有变量 *（MainApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：前置：workflowId
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为变量数组或键值结构，依实现返回
形参：
- workflowId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"workflowId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getWorkflowVariablesApi","args":["example"]}

`getWorkflowWorkerApi`

作用：获取执行器（MainApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。
依赖与顺序：前置：已知 workflowId 或 workerId（来自 list）
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getWorkflowWorkerApi","args":[1]}

`getWorkflowWorkerByWorkerIdApi`

作用：获取执行器By Worker Id（MainApiController）
何时调用：已有所需主键或唯一标识，需读取详情再决定分支或组装下一节点参数时。。前置：已知 workerId 字符串
依赖与顺序：前置：已知 workflowId 或 workerId（来自 list）
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- workerId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"workerId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getWorkflowWorkerByWorkerIdApi","args":["example"]}

`getWorkflowWorkerListApi`

作用：执行器分页列表（MainApiController）
何时调用：需要先浏览/筛选列表、分页拉取，或后续节点依赖列表中的 id/workflowId 等字段时（宜放在链首）。
依赖与顺序：前置：已知 workflowId 或 workerId（来自 list）
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult.data 为分页结构：list[]、total、page、pageSize
data 结构：data.list[] 含 id、workerId、name、workflowId、status、progress 等
形参：
- params（必填）类型 GetWorkflowWorkerListParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"page":1,"pageSize":10,"search":{"workflowId":"example-workflow"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getWorkflowWorkerListApi","args":{"page":1,"pageSize":10,"search":{"workflowId":"example-workflow"}}}

`importWorkflowsApi`

作用：批量从 Excel 导入窗口：名称、host、窗口ID 必填；同一分域下窗口ID 已存在则更新，否则新增（MainApiController）。从 Excel 批量导入/更新窗口
何时调用：已有导入文件/表格数据，需批量写入系统时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为导入统计（成功/失败条数等）
形参：
- params（必填）类型 { base64: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：args.base64 为 Excel 文件内容，体积大时分次导入
调用示例：

json

{"command":"importWorkflowsApi","args":{"base64":"example"}}

`importWorkflowVariablesExcelApi`

作用：导入窗口Variables Excel（MainApiController）
何时调用：已有导入文件/表格数据，需批量写入系统时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：data 为导入统计（成功/失败条数等）
形参：
- params（必填）类型 { base64: string }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"importWorkflowVariablesExcelApi","args":{"base64":"example"}}

`openLocalPathApi`

作用：在系统文件管理器中打开本地路径 *（MainApiController）
何时调用：需在 Finder/资源管理器中打开目录，或定位到文件所在目录时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- filePath（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"filePath":值}）
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单
调用示例：

json

{"command":"openLocalPathApi","args":["example"]}

`resetCookieApi`

作用：重置Cookie（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：前置：workflowId
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ResetCookieApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"resetCookieApi","args":{"workflowId":"example-workflow","cookies":[]}}

`resetMainWindowApi`

作用：重置Main Window（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。。影响主界面，自动执行慎用
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：CommonResult；data 多为 boolean 或受影响行信息
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"resetMainWindowApi","args":null}

`restartAppServerApi`

作用：重启内置 HTTP 服务 *（MainApiController）
何时调用：修改服务相关配置或 HTTP 服务异常，需重新监听端口时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"restartAppServerApi","args":null}

`runCronTaskNowApi`

作用：立即执行一次定时任务（与开关无关）（MainApiController）
何时调用：需立刻执行一次任务，不等待 cron/触发器排期时（与任务是否启用无关）。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：立即触发一次定时任务副作用（与 cron 表达式无关执行一次）
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"runCronTaskNowApi","args":[1]}

`saveWorkflowVariablesApi`

作用：保存或添加 *（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- workflowVariables（必填）类型 WorkflowVariablesEntity
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[{"workflowId":"example-workflow","name":"myVar","value":"1"}]（勿写 {"workflowVariables":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"saveWorkflowVariablesApi","args":[{"workflowId":"example-workflow","name":"myVar","value":"1"}]}

`selectElementApi`

作用：元素选择 *（MainApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- workflow（必填）类型 WorkflowEntity
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[{"workflowId":"example-workflow","host":"https://example.com"}]（勿写 {"workflow":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"selectElementApi","args":[{"workflowId":"example-workflow","host":"https://example.com"}]}

`setWorkflowEnabledApi`

作用：设置窗口Enabled（MainApiController）
何时调用：需开关功能（启停定时、执行器）但保留记录时；enabled: 0 会触发停用副作用。。前置：已知窗口主键 id（非 workflowId 字符串时需注意字段）
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：enabled=0 会停用窗口、清理定时与运行态；enabled=1 恢复调度
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 SetEnabledApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"setWorkflowEnabledApi","args":{"id":1,"enabled":1}}

`setWorkflowWorkerEnabledApi`

作用：设置执行器Enabled（MainApiController）
何时调用：需开关功能（启停定时、执行器）但保留记录时；enabled: 0 会触发停用副作用。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：启停执行器调度，不删除记录
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 SetEnabledApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"setWorkflowWorkerEnabledApi","args":{"id":1,"enabled":1}}

`startWorkflowWorkerApi`

作用：启动执行器（MainApiController）
何时调用：需立即启动运行；前置：资源已启用且参数齐备。。前置：执行器记录存在、已启用，所属窗口宜已 startWorkflow
依赖与顺序：前置：getWorkflowWorkerListApi 取 id，或 getWorkflowWorkerApi；窗口 workflow 须已启动
副作用：启动指定 workerId 执行器运行
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"startWorkflowWorkerApi","args":[1]}

`stopWorkflowWorkerApi`

作用：停止执行器（MainApiController）
何时调用：需中断运行或释放资源时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：中断执行器运行
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- id（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"id":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"stopWorkflowWorkerApi","args":[1]}

`updateAppServerPortApi`

作用：修改内置 HTTP 服务端口并重启（写入 config/app.json）（MainApiController）
何时调用：已有资源 id，需修改配置并持久化时。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- port（必填）类型 number
bizapi-exec args：单形参按位置传入；bizapi-exec.args=[1]（勿写 {"port":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateAppServerPortApi","args":[1]}

`updateCapturedElementApi`

作用：更新采集元素（MainApiController）
何时调用：已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpdateCapturedElementApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"id":1,"model":{"name":"新名称"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateCapturedElementApi","args":{"id":1,"model":{"name":"新名称"}}}

`updateCronApi`

作用：更新定时器任务 *（MainApiController）
何时调用：已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpdateCronApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateCronApi","args":{"id":1,"cronStatus":"stop"}}

`updateCronTaskApi`

作用：更新定时任务，业务逻辑在 CronManager.updateCronTask（MainApiController）
何时调用：已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpdateCronTaskApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"id":1,"model":{"name":"示例定时任务"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateCronTaskApi","args":{"id":1,"model":{"name":"示例定时任务"}}}

`updateFolderApi`

作用：更新文件夹（MainApiController）
何时调用：已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpdateFolderParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateFolderApi","args":{"id":1,"model":"…"}}

`updateScreenshotApi`

作用：更新截图（MainApiController）
何时调用：已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpdateScreenshotApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"id":1,"model":{"name":"新名称"}}
注意：截屏结果可写入 static，供 findImage/crop 等后续步骤使用
调用示例：

json

{"command":"updateScreenshotApi","args":{"id":1,"model":{"name":"新名称"}}}

`updateWorkflowApi`

作用：更新窗口（MainApiController）
何时调用：已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpdateWorkflowApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"id":1,"model":{"name":"新名称"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateWorkflowApi","args":{"id":1,"model":{"name":"新名称"}}}

`updateWorkflowWorkerApi`

作用：更新执行器（MainApiController）
何时调用：已有资源 id，需修改配置/字段并持久化；避免在未查询确认前盲目更新。
依赖与顺序：前置：list/get 确认资源 id 与当前字段
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 UpdateWorkflowWorkerApiParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"id":1,"model":{"name":"新名称"}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"updateWorkflowWorkerApi","args":{"id":1,"model":{"name":"新名称"}}}

MainCommandController

`startWorkflow`

作用：启动指定窗口流程（打开/运行自动化窗口流程）（MainCommandController）
何时调用：自动执行或助手编排需启动某 workflowId 的流程（打开窗口并开始跑执行器链）时；需已确认 workflowId 有效。。前置条件：已从列表取得 workflowId 且窗口 enabled≠0
依赖与顺序：前置：getWorkflowListApi 或已知 workflowId；后置常接 getWorkflowWorkerListApi / startWorkflowWorkerApi
副作用：打开三方浏览器窗口、挂载 workflowId、可能启动执行器链与相关定时任务
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：通常无业务 data；以 success/message 为准
形参：
- workflow（必填）类型 WorkflowEntity | string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["…"]（勿写 {"workflow":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"startWorkflow","args":["…"]}

`stopWorkflow`

作用：停止指定 workflowId 的窗口流程运行（MainCommandController）
何时调用：需终止正在运行的流程、释放窗口与引擎，或规则命中「停止/取消」语义时；须传入正确 workflowId。
依赖与顺序：前置：已知正在运行的 workflowId
副作用：停止窗口流程、释放浏览器窗口与运行中执行器
返回：CommonResult；成功时看 data 字段，失败看 success=false 与 message
data 结构：通常无业务 data；以 success/message 为准
形参：
- workflowId（必填）类型 string
bizapi-exec args：单形参按位置传入；bizapi-exec.args=["example"]（勿写 {"workflowId":值}）
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"stopWorkflow","args":["example"]}

NativeApiController

`cancelElementPickerApi`

作用：取消元素拾取由外部调用触发，用于取消当前的元素拾取操作（NativeApiController）
何时调用：需交互式拾取 UI 元素时；自动执行链通常改用 locateElementApi + 坐标。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"cancelElementPickerApi","args":null}

`captureAreaApi`

作用：截取指定区域（NativeApiController）
何时调用：需截屏、框选区域或带元素信息截图，作为找图/OCR/上报输入时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：截屏或高亮 overlay，可能写入 static 目录
返回：方法返回 ApiResultType<CaptureAreaResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CaptureAreaParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：截屏结果可写入 static，供 findImage/crop 等后续步骤使用
调用示例：

json

{"command":"captureAreaApi","args":{"bizId":"captures","filename":"example","x":1,"y":1,"width":1,"height":1}}

`captureMonitorApi`

作用：截取指定显示器全屏（NativeApiController）
何时调用：需截全屏并发送到通道或写入 static 时（如钉钉截图推送）。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<CaptureMonitorResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CaptureMonitorParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"captureMonitorApi","args":{"bizId":"captures","filename":"example","monitorIndex":1}}

`captureRectApi`

作用：捕获屏幕指定矩形区域（含元素信息）（NativeApiController）
何时调用：需截屏、框选区域或带元素信息截图，作为找图/OCR/上报输入时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：截屏或高亮 overlay，可能写入 static 目录
返回：方法返回 ApiResultType<ReturnType<DesktopNative['captureRect']>>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CaptureRectParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：截屏结果可写入 static，供 findImage/crop 等后续步骤使用
调用示例：

json

{"command":"captureRectApi","args":{"bizId":"captures","filename":"example","x":1,"y":1,"width":1,"height":1}}

`checkAccessibilityPermissionApi`

作用：检查 Accessibility 权限（NativeApiController）
何时调用：调用 AX/元素 API 前检查或申请 macOS 辅助功能权限时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"checkAccessibilityPermissionApi","args":null}

`clearAppCacheApi`

作用：清除应用列表缓存（NativeApiController）
何时调用：需列出本机已安装应用或刷新应用列表缓存时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：清理缓存/Cookie/数据，可能影响后续页面自动化
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"clearAppCacheApi","args":null}

`clickMouseApi`

作用：点击鼠标（NativeApiController）
何时调用：需在屏幕坐标单击/双击时；勿对未知坐标盲点后确认前台窗口。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ClickMouseParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"clickMouseApi","args":{"button":"left","delayMs":1}}

`compressImageApi`

作用：压缩图片为 JPEG（NativeApiController）
何时调用：截图过大需满足钉钉等媒体上传大小限制（image 约 1MB）时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<CompressImageResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CompressImageParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"compressImageApi","args":{"bizId":"captures","filename":"example","imagePath":"example","maxBytes":1,"maxWidth":1,"maxHeight":1,"initialQuality":1}}

`confirmElementPickerApi`

作用：确认元素选择（在当前鼠标位置选择元素）由外部调用触发，用于在当前鼠标位置确认选择元素（NativeApiController）
何时调用：需交互式拾取 UI 元素时；自动执行链通常改用 locateElementApi + 坐标。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"confirmElementPickerApi","args":null}

`copyLocalPathApi`

作用：复制文件（NativeApiController）
何时调用：需复制本机文件到新路径时（仅文件，非目录树）。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<string>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CopyLocalPathParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单
调用示例：

json

{"command":"copyLocalPathApi","args":{"from":"example","to":"example","cwd":"example","allowedRoots":["example"],"overwrite":true}}

`cropImageApi`

作用：裁剪图像，输出写入 static（NativeApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读写 config/static 下图片文件
返回：方法返回 ApiResultType<string>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 CropImageParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"cropImageApi","args":{"bizId":"captures","filename":"example","imagePath":"example","x":1,"y":1,"width":1,"height":1}}

`deleteLocalPathApi`

作用：删除文件或目录（NativeApiController）
何时调用：需删除本机文件；目录须 recursive:true 才能非空删除。
依赖与顺序：前置：list/get 确认将删除的 id，避免误删
副作用：持久化删除或软删，通常不可自动撤销
返回：方法返回 ApiResultType<null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 DeleteLocalPathParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单
调用示例：

json

{"command":"deleteLocalPathApi","args":{"path":"example","cwd":"example","allowedRoots":["example"],"recursive":true}}

`doubleClickMouseApi`

作用：双击鼠标（NativeApiController）
何时调用：需在屏幕坐标单击/双击时；勿对未知坐标盲点后确认前台窗口。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 DoubleClickMouseParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"doubleClickMouseApi","args":{"button":"left","delayMs":1}}

`dragMouseApi`

作用：拖拽鼠标（NativeApiController）
何时调用：需拖拽或滚轮操作时；确认目标区域在前台。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 DragMouseParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"dragMouseApi","args":{"fromX":1,"fromY":1,"toX":1,"toY":1,"durationMs":1}}

`ensureVirtualDisplayApi`

作用：插入虚拟显示器（须已安装 RustDeskIddDriver，仅 Windows）（NativeApiController）
何时调用：getDisplayHealthApi 显示无屏或 captureOk=false，且已安装 RustDesk Idd 驱动时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<EnsureVirtualDisplayResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（可选）类型 EnsureVirtualDisplayOptions
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"ensureVirtualDisplayApi","args":{"width":1,"height":1,"monitorIndex":1,"edid":1,"retries":1}}

`findColorApi`

作用：在图像中查找颜色（NativeApiController）
何时调用：需在屏幕/图像中定位模板或颜色，供后续点击/高亮时。
依赖与顺序：前置：已有截图/图像路径（如 captureRectApi、saveImageToStaticApi）
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<FindColorResult[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 FindColorParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"findColorApi","args":{"imagePath":"example","red":1,"green":1,"blue":1,"alpha":1,"tolerance":1}}

`findImageApi`

作用：在图像中查找子图像（NativeApiController）
何时调用：需在屏幕/图像中定位模板或颜色，供后续点击/高亮时。
依赖与顺序：前置：已有截图/图像路径（如 captureRectApi、saveImageToStaticApi）
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<FindImageResult[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 FindImageParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"findImageApi","args":{"haystackPath":"example","needlePath":"example","tolerance":1}}

`findImageInDesktopApi`

作用：在桌面屏幕上查找指定图片（NativeApiController）。全屏模板匹配，返回坐标供 clickMouseApi
何时调用：需在屏幕/图像中定位模板或颜色，供后续点击/高亮时。
依赖与顺序：前置：模板图已在 static 或 args 提供可访问路径
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<FindImageInDesktopResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 FindImageInDesktopParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"findImageInDesktopApi","args":{"needle":"example","tolerance":1,"screenIndex":1}}

`getDisplayHealthApi`

作用：显示器健康检查：枚举数量、DXGI 探针、RustDeskIdd 驱动状态（NativeApiController）
何时调用：桌面自动化前需确认是否有可用显示器/截屏能力，尤其无物理屏服务器。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<DisplayHealth>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getDisplayHealthApi","args":null}

`getDominantColorsApi`

作用：获取图像主色调（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<DominantColor[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 GetDominantColorsParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getDominantColorsApi","args":{"imagePath":"example","maxColors":1}}

`getElementAtPositionApi`

作用：获取指定位置的 UI 元素信息（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：前置：Accessibility 已授权；坐标来自截图找图或人工指定
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<AXElement | null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 GetElementAtPositionParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"getElementAtPositionApi","args":{"x":1,"y":1}}

`getElementPathAtPositionApi`

作用：获取指定位置元素的完整层级路径（从根到目标元素）（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：前置：Accessibility 已授权；坐标来自截图找图或人工指定
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<AXElementPath | null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 GetElementPathAtPositionParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"getElementPathAtPositionApi","args":{"x":1,"y":1}}

`getElementPathUnderMouseApi`

作用：获取鼠标位置下元素的完整层级路径（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：前置：Accessibility 已授权；坐标来自截图找图或人工指定
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<AXElementPath | null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：本机桌面输入模拟，非浏览器内 DOM 操作；macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"getElementPathUnderMouseApi","args":null}

`getElementRectApi`

作用：获取指定位置元素的矩形区域（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：前置：Accessibility 已授权；坐标来自截图找图或人工指定
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<Rect | null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 GetElementRectParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"getElementRectApi","args":{"x":1,"y":1}}

`getElementRectUnderMouseApi`

作用：获取鼠标位置下元素的矩形区域（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：前置：Accessibility 已授权；坐标来自截图找图或人工指定
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<Rect | null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：本机桌面输入模拟，非浏览器内 DOM 操作；macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"getElementRectUnderMouseApi","args":null}

`getElementTreeAtPositionApi`

作用：获取指定位置元素的树形结构（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：前置：Accessibility 已授权；坐标来自截图找图或人工指定
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<AXElementNode | null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 GetElementTreeAtPositionParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"getElementTreeAtPositionApi","args":{"x":1,"y":1,"maxDepth":1}}

`getElementUnderMouseApi`

作用：获取鼠标位置下的 UI 元素信息（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：前置：Accessibility 已授权；坐标来自截图找图或人工指定
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<AXElement | null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：本机桌面输入模拟，非浏览器内 DOM 操作；macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"getElementUnderMouseApi","args":null}

`getInstalledAppsApi`

作用：获取本地已安装的应用列表（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<import('./NativeApiTypes').AppInfo[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（可选）类型 { forceRefresh?: boolean }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getInstalledAppsApi","args":{"forceRefresh":true}}

`getMousePositionApi`

作用：获取当前鼠标位置（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<MousePosition>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getMousePositionApi","args":null}

`getScreenInfoApi`

作用：获取屏幕信息（NativeApiController）
何时调用：已有 id/workflowId/workerId，需读取详情再编排下一步时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<Rect[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getScreenInfoApi","args":null}

`getScreenRecordingStatusApi`

作用：获取录屏进度（NativeApiController）
何时调用：录屏进行中需展示帧数、时长等进度信息时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<ScreenRecordingStatusResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"getScreenRecordingStatusApi","args":null}

`grepLocalFilesApi`

作用：在目录中 grep 搜索（NativeApiController）
何时调用：需在项目/日志目录中按关键字或正则查找代码、配置、错误行时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<GrepLocalFilesResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 GrepLocalFilesParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单；目录搜索安全上限：相对 root 深度 ≤3，文件/条目 ≤100（超出部分截断或忽略）
调用示例：

json

{"command":"grepLocalFilesApi","args":{"root":"example","pattern":"example","cwd":"example","allowedRoots":["example"],"glob":"example","ignore":["example"],"regex":true,"caseInsensitive":true,"includeDot":true,"maxDepth":1,"maxMatches":1,"maxFiles":1,"maxFileBytes":1}}

`highlightAreaApi`

作用：高亮屏幕区域（NativeApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：屏幕叠加高亮，不改变业务数据
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 HighlightAreaParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"x":1,"y":1,"width":1,"height":1,"config":{"color":"example","borderWidth":1,"opacity":1,"durationMs":1,"animation":"example","text":"example","textSize":1,"fill":true,"fillOpacity":1}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"highlightAreaApi","args":{"x":1,"y":1,"width":1,"height":1,"config":{"color":"example","borderWidth":1,"opacity":1,"durationMs":1,"animation":"example","text":"example","textSize":1,"fill":true,"fillOpacity":1}}}

`highlightRegionsApi`

作用：高亮多个屏幕区域（NativeApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：屏幕叠加高亮，不改变业务数据
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 HighlightRegionsParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"regions":[{"x":100,"y":100,"width":200,"height":80}],"config":{"color":"#ff0000","durationMs":2000}}
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"highlightRegionsApi","args":{"regions":[{"x":100,"y":100,"width":200,"height":80}],"config":{"color":"#ff0000","durationMs":2000}}}

`humanMoveMouseApi`

作用：模拟人类滑动鼠标使用贝塞尔曲线和随机抖动来模拟真实的人类鼠标移动轨迹（NativeApiController）
何时调用：需将光标移到屏幕坐标时；坐标宜来自 findImage/getElementRect/captureRect。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 HumanMoveMouseParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"humanMoveMouseApi","args":{"x":1,"y":1,"durationMs":1,"randomness":1}}

`isElementPickerRunningApi`

作用：检查元素拾取是否正在运行（NativeApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"isElementPickerRunningApi","args":null}

`isInputListenerRunningApi`

作用：检查输入监听状态（NativeApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"isInputListenerRunningApi","args":null}

`isScreenRecordingRunningApi`

作用：是否正在录屏（NativeApiController）
何时调用：需判断录屏会话是否仍在运行时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"isScreenRecordingRunningApi","args":null}

`isScreenshotRunningApi`

作用：检查截图是否正在进行（NativeApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"isScreenshotRunningApi","args":null}

`keyDownApi`

作用：按下并保持按键（NativeApiController）
何时调用：需向当前焦点控件输入文字或按键时；前置：目标应用已聚焦。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 KeyDownParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"keyDownApi","args":{"keyName":"enter","modifiers":["shift"]}}

`keyUpApi`

作用：释放按键（NativeApiController）
何时调用：需向当前焦点控件输入文字或按键时；前置：目标应用已聚焦。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 KeyUpParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"keyUpApi","args":{"keyName":"enter","modifiers":["shift"]}}

`listLocalDirApi`

作用：列出目录条目（NativeApiController，fast-glob）（NativeApiController）
何时调用：需枚举某目录下文件/子目录路径时。
依赖与顺序：宜作为 BizApi 链首步；后续 get/update/delete/start 依赖本步返回的 id
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<ListLocalDirEntry[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ListLocalDirParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单；目录搜索安全上限：相对 root 深度 ≤3，文件/条目 ≤100（超出部分截断或忽略）
调用示例：

json

{"command":"listLocalDirApi","args":{"path":"example","cwd":"example","allowedRoots":["example"],"glob":"example","recursive":true,"maxDepth":1,"limit":1,"includeDot":true,"entries":"all"}}

`locateElementApi`

作用：根据查询条件定位元素（NativeApiController）
何时调用：需读取屏幕坐标处 UI 元素信息、路径或矩形时；前置：Accessibility 已授权。
依赖与顺序：前置：checkAccessibilityPermissionApi 为 true；宜先 getElementPath 或 captureRect 取坐标
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<AXLocateResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 LocateElementParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"query":{"app":"example","pid":1,"selectors":[{"role":"example","subrole":"example","title":"example","identifier":"example","index":1,"description":"example","value":"example","label":"example","className":"example","helpText":"example"}]}}
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"locateElementApi","args":{"query":{"app":"example","pid":1,"selectors":[{"role":"example","subrole":"example","title":"example","identifier":"example","index":1,"description":"example","value":"example","label":"example","className":"example","helpText":"example"}]}}}

`locateElementByAncestorsApi`

作用：根据 ancestors 路径定位元素（NativeApiController）
何时调用：需读取屏幕坐标处 UI 元素信息、路径或矩形时；前置：Accessibility 已授权。
依赖与顺序：前置：checkAccessibilityPermissionApi 为 true；宜先 getElementPath 或 captureRect 取坐标
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<AXLocateResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 LocateElementByAncestorsParams
bizapi-exec args：params 对象整包；bizapi-exec.args={"ancestors":[
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"locateElementByAncestorsApi","args":{"ancestors":[{}],"selectors":"example","appName":"example","appPid":1}}

`mkdirLocalPathApi`

作用：创建目录（NativeApiController）
何时调用：写入文件前需确保目录存在，或单独创建文件夹时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<string>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 MkdirLocalPathParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单
调用示例：

json

{"command":"mkdirLocalPathApi","args":{"path":"example","cwd":"example","allowedRoots":["example"],"recursive":true}}

`moveLocalPathApi`

作用：移动/重命名路径（NativeApiController）
何时调用：需重命名或移动本机文件/目录时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<string>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 MoveLocalPathParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单
调用示例：

json

{"command":"moveLocalPathApi","args":{"from":"example","to":"example","cwd":"example","allowedRoots":["example"],"overwrite":true}}

`moveMouseApi`

作用：移动鼠标到指定位置（NativeApiController）
何时调用：需将光标移到屏幕坐标时；坐标宜来自 findImage/getElementRect/captureRect。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 MoveMouseParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"moveMouseApi","args":{"x":1,"y":1}}

`pathExistsLocalApi`

作用：判断路径是否存在（NativeApiController）
何时调用：仅需布尔存在性、不必读取 stat 详情时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 PathExistsLocalParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"pathExistsLocalApi","args":{"path":"example","cwd":"example","allowedRoots":["example"]}}

`pressKeyApi`

作用：按下按键（NativeApiController）
何时调用：需向当前焦点控件输入文字或按键时；前置：目标应用已聚焦。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 PressKeyParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"pressKeyApi","args":{"keyName":"enter","modifiers":["shift"]}}

`readLocalFileApi`

作用：读取本地文件（NativeApiController）
何时调用：需读取本机文本/配置/日志等内容供 AI 分析或后续 BizApi 使用时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<ReadLocalFileResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ReadLocalFileParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单
调用示例：

json

{"command":"readLocalFileApi","args":{"path":"example","cwd":"example","allowedRoots":["example"],"encoding":"base64","maxBytes":1}}

`requestAccessibilityPermissionApi`

作用：请求 Accessibility 权限（NativeApiController）
何时调用：调用 AX/元素 API 前检查或申请 macOS 辅助功能权限时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：可能弹出系统授权对话框
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"requestAccessibilityPermissionApi","args":null}

`resizeImageApi`

作用：缩放图像，输出写入 static（NativeApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读写 config/static 下图片文件
返回：方法返回 ApiResultType<string>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ResizeImageParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"resizeImageApi","args":{"bizId":"captures","filename":"example","imagePath":"example","width":1,"height":1,"preserveAspect":true}}

`resolveStaticUrlApi`

作用：将相对路径解析为 HTTP 访问 URL（/static/...）（NativeApiController）。将 static 相对路径转为本机 HTTP URL，供找图/预览
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<string>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ResolveStaticUrlParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"resolveStaticUrlApi","args":{"imagePath":"example"}}

`saveImageToStaticApi`

作用：保存图片到 config/static/{bizId}/，返回相对路径（NativeApiController）
何时调用：确认业务语义、参数与副作用符合当前自动执行目标时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读写 config/static 下图片文件
返回：方法返回 ApiResultType<StaticImageResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 SaveImageToStaticParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"saveImageToStaticApi","args":{"bizId":"captures","filename":"example","filePath":"example","pngBase64":"example"}}

`scrollMouseApi`

作用：滚动鼠标（NativeApiController）
何时调用：需拖拽或滚轮操作时；确认目标区域在前台。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 ScrollMouseParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"scrollMouseApi","args":{"direction":"up","clicks":1}}

`selectFileApi`

作用：选择文件（NativeApiController）
何时调用：需用户选择本地文件/目录时；无人值守场景慎用（会阻塞弹窗）。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<string[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（可选）类型 { title?: string; defaultPath?: string; buttonLabel?: string; filters?: Array<{ name: string; extensions: string[] }>; properties?: Array<'openFile' | 'multiSelections' | 'showHiddenFiles'>; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：会弹出系统文件对话框，无人值守自动执行慎用
调用示例：

json

{"command":"selectFileApi","args":{"title":"选择文件","properties":["openFile"]}}

`selectFolderApi`

作用：选择文件夹（NativeApiController）
何时调用：需用户选择本地文件/目录时；无人值守场景慎用（会阻塞弹窗）。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<string[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（可选）类型 { title?: string; defaultPath?: string; buttonLabel?: string; properties?: Array<'openDirectory' | 'multiSelections' | 'showHiddenFiles' | 'createDirectory'>; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：会弹出系统文件对话框，无人值守自动执行慎用
调用示例：

json

{"command":"selectFolderApi","args":{"title":"example","defaultPath":"example","buttonLabel":"example","properties":"multiSelections"}}

`selectPathApi`

作用：选择文件或文件夹（NativeApiController）
何时调用：需用户选择本地文件/目录时；无人值守场景慎用（会阻塞弹窗）。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<string[]>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（可选）类型 { title?: string; defaultPath?: string; buttonLabel?: string; filters?: Array<{ name: string; extensions: string[] }>; properties?: Array<'openFile' | 'openDirectory' | 'multiSelections' | 'showHiddenFiles' | 'createDirectory'>; }
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：会弹出系统文件对话框，无人值守自动执行慎用
调用示例：

json

{"command":"selectPathApi","args":{"title":"选择路径","properties":["openDirectory"]}}

`smoothMoveMouseApi`

作用：平滑移动鼠标（NativeApiController）
何时调用：需将光标移到屏幕坐标时；坐标宜来自 findImage/getElementRect/captureRect。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 SmoothMoveMouseParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"smoothMoveMouseApi","args":{"x":1,"y":1,"durationMs":1}}

`startElementPickerApi`

作用：启动元素拾取模式启动后会实时追踪鼠标位置，获取并高亮鼠标下的 UI 元素（NativeApiController）
何时调用：需立即启动运行；前置：资源已启用且参数齐备。
依赖与顺序：前置：Accessibility；常与 confirmElementPickerApi/cancelElementPickerApi 组合
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<ElementPickerResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：macOS 需辅助功能（Accessibility）权限
调用示例：

json

{"command":"startElementPickerApi","args":null}

`startScreenRecordingApi`

作用：开始屏幕录屏（NativeApiController）
何时调用：需录制桌面操作过程并保存为 MP4 时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<null>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（可选）类型 StartScreenRecordingParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"startScreenRecordingApi","args":{"bizId":"captures","filename":"example","monitorIndex":1,"fps":1,"maxDurationSec":1,"scale":1}}

`startScreenshotApi`

作用：启动交互式框选截图（NativeApiController）
何时调用：需立即启动运行；前置：资源已启用且参数齐备。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：截屏或高亮 overlay，可能写入 static 目录
返回：方法返回 ApiResultType<StartScreenshotResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（可选）类型 StartScreenshotParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：截屏结果可写入 static，供 findImage/crop 等后续步骤使用
调用示例：

json

{"command":"startScreenshotApi","args":{"bizId":"captures","filename":"example"}}

`statLocalPathApi`

作用：获取路径 stat（NativeApiController）
何时调用：需判断文件/目录是否存在及大小、修改时间时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<LocalPathStat>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 StatLocalPathParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单
调用示例：

json

{"command":"statLocalPathApi","args":{"path":"example","cwd":"example","allowedRoots":["example"]}}

`stopElementPickerApi`

作用：停止元素拾取模式（NativeApiController）
何时调用：需中断运行或释放资源时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"stopElementPickerApi","args":null}

`stopHighlightApi`

作用：停止所有高亮（NativeApiController）
何时调用：需中断运行或释放资源时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"stopHighlightApi","args":null}

`stopInputListenerApi`

作用：停止全局输入监听（NativeApiController）
何时调用：需中断运行或释放资源时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"stopInputListenerApi","args":null}

`stopScreenRecordingApi`

作用：停止屏幕录屏并保存 MP4（NativeApiController）
何时调用：startScreenRecordingApi 已启动后，需结束录制并获取视频路径时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<StopScreenRecordingResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- 无业务形参
bizapi-exec args：无参；bizapi-exec 省略 args 或 null
注意：术语：窗口=Workflow(workflowId)；执行器=WorkflowWorker(workerId)
调用示例：

json

{"command":"stopScreenRecordingApi","args":null}

`typeStringApi`

作用：输入字符串（NativeApiController）
何时调用：需向当前焦点控件输入文字或按键时；前置：目标应用已聚焦。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：操控本机鼠标/键盘，改变焦点与前台应用状态
返回：方法返回 ApiResultType<boolean>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 TypeStringParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机桌面输入模拟，非浏览器内 DOM 操作
调用示例：

json

{"command":"typeStringApi","args":{"text":"example","wpm":1}}

`writeLocalFileApi`

作用：写入本地文件（NativeApiController）
何时调用：需将文本或 base64 内容写入本机文件时。
依赖与顺序：与其它 API 组合时，先 list/get 再写/启停；id 与 workflowId/workerId 勿混淆
副作用：读操作为主则无持久化副作用；写操作会改变系统或运行时状态
返回：方法返回 ApiResultType<WriteLocalFileResult>，HTTP/BizApi 统一包在 CommonResult（success/message/data/code）
data 结构：以实际返回为准；自动执行须基于反馈 JSON 中的 data，禁止编造字段
形参：
- params（必填）类型 WriteLocalFileParams
bizapi-exec args：params 对象整包；bizapi-exec.args=
注意：本机文件 API：路径可为绝对或相对 cwd；可选 allowedRoots 白名单
调用示例：

json

{"command":"writeLocalFileApi","args":{"path":"example","cwd":"example","allowedRoots":["example"],"content":"example","encoding":"base64","append":true,"createDirs":true}}

主进程 BizApi 参考 ​

说明 ​

回复格式（必须遵守） ​

HTTP ​

场景选型 ​

API 索引 ​

AiApiController ​

AiSingleExecutorRunner ​

DataSourceApiController ​

MainApiController ​

MainCommandController ​

NativeApiController ​

API 详细说明 ​

AiApiController ​

abortAiStreamApi ​

abortAiVoiceStreamApi ​

appendAiSessionMessageApi ​

captureAndSendScreenshotToAiChannelApi ​

chatAiCompleteApi ​

chatAiStreamApi ​

clearAiSessionMessagesApi ​

createAiSessionApi ​

createAiTimerApi ​

deleteAiChannelApi ​

deleteAiCustomProviderApi ​

deleteAiMessageAutoexecRuleApi ​

deleteAiPromptApi ​

deleteAiSessionApi ​

deleteAiTimerApi ​

finishAiVoiceStreamApi ​

getAiChannelApi ​

getAiPromptBodyApi ​

getAiSessionApi ​

listAiChannelsApi ​

listAiCustomProvidersApi ​

listAiExecutorTypesApi ​

listAiMessageAutoexecRulesApi ​

listAiModelsApi ​

listAiPromptsApi ​

listAiProvidersApi ​

listAiSessionsApi ​

listAiTimersApi ​

resetAiBuiltinPromptApi ​

resetAiChannelDingTalkSessionsApi ​

sendAiChannelOutboundImageApi ​

sendAiChannelOutboundMarkdownApi ​

sendAiChannelOutboundVideoApi ​

sendAiVoiceAudioChunkApi ​

setAiProviderApiKeyApi ​

startAiChannelStreamListenApi ​

startAiVoiceStreamApi ​

startScreenRecordingWithAutoStopAndSendApi ​

stopAiChannelStreamListenApi ​

stopScreenRecordingAndSendToAiChannelApi ​

testAiChannelApi ​

tryRunAiExecutorApi ​

updateAiSessionApi ​

updateAiTimerApi ​

upsertAiChannelApi ​

upsertAiCustomProviderApi ​

upsertAiMessageAutoexecRuleApi ​

upsertAiPromptApi ​

AiSingleExecutorRunner ​

runNode ​

DataSourceApiController ​

connectDataSourceApi ​

createDataSourceApi ​

deleteDataSourceApi ​

disconnectDataSourceApi ​

ensureDefaultDataSourceApi ​

getDataSourceConnectionStatusApi ​

getDataSourceDetailApi ​

getDataSourceListApi ​

getDataSourceSchemaDiffApi ​

listManagedTablesApi ​

managedTableCountApi ​

managedTableDeleteApi ​

managedTableFindApi ​

managedTableInsertApi ​

managedTableUpdateApi ​

主进程 BizApi 参考

说明

回复格式（必须遵守）

HTTP

场景选型

API 索引

AiApiController

AiSingleExecutorRunner

DataSourceApiController

MainApiController

MainCommandController

NativeApiController

API 详细说明

AiApiController

`abortAiStreamApi`

`abortAiVoiceStreamApi`

`appendAiSessionMessageApi`

`captureAndSendScreenshotToAiChannelApi`

`chatAiCompleteApi`

`chatAiStreamApi`

`clearAiSessionMessagesApi`

`createAiSessionApi`

`createAiTimerApi`

`deleteAiChannelApi`

`deleteAiCustomProviderApi`

`deleteAiMessageAutoexecRuleApi`

`deleteAiPromptApi`

`deleteAiSessionApi`

`deleteAiTimerApi`

`finishAiVoiceStreamApi`

`getAiChannelApi`

`getAiPromptBodyApi`

`getAiSessionApi`

`listAiChannelsApi`

`listAiCustomProvidersApi`

`listAiExecutorTypesApi`

`listAiMessageAutoexecRulesApi`

`listAiModelsApi`

`listAiPromptsApi`

`listAiProvidersApi`

`listAiSessionsApi`

`listAiTimersApi`

`resetAiBuiltinPromptApi`

`resetAiChannelDingTalkSessionsApi`

`sendAiChannelOutboundImageApi`

`sendAiChannelOutboundMarkdownApi`

`sendAiChannelOutboundVideoApi`

`sendAiVoiceAudioChunkApi`

`setAiProviderApiKeyApi`

`startAiChannelStreamListenApi`

`startAiVoiceStreamApi`

`startScreenRecordingWithAutoStopAndSendApi`

`stopAiChannelStreamListenApi`

`stopScreenRecordingAndSendToAiChannelApi`

`testAiChannelApi`

`tryRunAiExecutorApi`

`updateAiSessionApi`

`updateAiTimerApi`

`upsertAiChannelApi`

`upsertAiCustomProviderApi`

`upsertAiMessageAutoexecRuleApi`

`upsertAiPromptApi`

AiSingleExecutorRunner

`runNode`

DataSourceApiController

`connectDataSourceApi`

`createDataSourceApi`

`deleteDataSourceApi`

`disconnectDataSourceApi`

`ensureDefaultDataSourceApi`

`getDataSourceConnectionStatusApi`

`getDataSourceDetailApi`

`getDataSourceListApi`

`getDataSourceSchemaDiffApi`

`listManagedTablesApi`

`managedTableCountApi`

`managedTableDeleteApi`

`managedTableFindApi`

`managedTableInsertApi`

`managedTableUpdateApi`