# @beeos-ai/bma-executor-sdk 中文文档

规范地址：https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/

版本：1\.1\.0
npm 元数据更新时间：2026-11-07T16:41:29.448Z
中文译文更新时间：2026-11-07T20:37:47.492Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40beeos-ai/bma-executor-sdk
原文对照：https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/?lang=original
项目主页：https://github.com/beeos-ai/bma-executor-sdk#readme
源码仓库：https://github.com/beeos-ai/bma-executor-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：377 kB，32 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：2 个
- 首次发布：2026-10-31T17:39:59.432Z
- 最新版本发布：2026-11-07T16:41:28.658Z
- 近 30 天下载量：3599（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：17（近 12 个月 17 个）

## 中文简介

BMA执行器协议(bma.executor.v1.1):执行器,取用和代理以WebSocket,本地套接字和进程内传输为结尾.

## 安装

```sh
npm install @beeos-ai/bma-executor-sdk
```

也可以使用：`pnpm add @beeos-ai/bma-executor-sdk`、`yarn add @beeos-ai/bma-executor-sdk`、`bun add @beeos-ai/bma-executor-sdk`

## README

# @beeos-ai/bma-executor-sdk (英语)

[![npm](https://img.shields.io/npm/v/@beeos-ai/bma-executor-sdk.svg)](https://www.npmjs.com/package/@beeos-ai/bma-executor-sdk)

将您的机器(手)或自己的代理(大脑)连接到 BMA —— 执行器、 控制器和代理端 `bma.executor` 协议. [`@beeos-ai/bma-sdk`](https://github.com/beeos-ai/bma-sdk) 驱动和使用代理(REST/外观客户端); `bma-executor-sdk` 将手或大脑连接到BMA.

执行者( E)`ExecutorClient`),取用(`Harness`)和BMA的代理端 执行者协议 `bma.executor.v1.1` (和 `v1`),具有相同的三部分和 行为作为 [走开 `executor` 模块](https://npmcn.com/package/%40beeos-ai/README.md)。议定书类型是: 从合同中产生([`src/generated/executor.ts`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/src/generated/executor.ts), (中文(简体) ), 快照和锁定 [`contracts/bma/executor`](https://npmcn.com/package/%40beeos-ai/contracts/bma/executor)(三); 运行时间是手写的。 传输: WebSocket, 一个 Unix 域上的 WebSocket 套接字或名为 Windows 的管道(`unix://`, (中文(简体) ), `npipe://`),进行中.

|  |  |
| --- | --- |
| 版本 | 1.0.0 (计数) `v1.0.0`,参见 [变化](https://npmcn.com/package/%40beeos-ai/CHANGELOG.md) |
| 议定书 | `bma.executor.v1.1` (合同1.1.0, [`lock.json`](https://npmcn.com/package/%40beeos-ai/contracts/bma/executor/lock.json)(中文(简体) ) |
| 节点.js | 20个或较新的;无害环境管理,取决于 `ws` 财务报告和审定财务报表 `@types/ws` (声明的使用) `ws` 类型) |
| 融合指南 | [文件/执行员](https://npmcn.com/package/%40beeos-ai/docs/executor/README.md) (单位:千美元)[页:1](https://npmcn.com/package/%40beeos-ai/docs/executor/README.zh-CN.md)(中文(简体) ) |

```sh
npm install @beeos-ai/bma-executor-sdk@1.0.2
```

REST / 外观客户端是单独的软件包 [`@beeos-ai/bma-sdk`](https://github.com/beeos-ai/bma-sdk/tree/main/typescript)。 。 。 .

### 执行器快速启动

```ts
import { ExecutorClient } from "@beeos-ai/bma-executor-sdk";

const client = new ExecutorClient({
  baseUrl: process.env.BMA_BASE_URL, // required: see below
  environmentKey: process.env.BMA_ENVIRONMENT_KEY,
  environmentId: process.env.BMA_ENVIRONMENT_ID!,
  executor: { name: "my-executor", os: process.platform, arch: process.arch, version: "0.1.0" },
});
client.tools.bash.handle(async (input, { signal, progress }) => {   // input: BashInput
  progress("running");
  const r = await run(input.command, { cwd: input.cwd, env: input.env, signal });
  return { stdout: r.stdout, stderr: r.stderr, exitCode: r.code };    // rendered like Go Core
});
client.tools.read.handle(async ({ path, offset, limit }) => readText(path, offset, limit)); // string or content blocks
await client.start();
await client.waitClosed(); // rejects when the client ends for good
```

设定 `baseUrl` 到您的 BMA 部署 : 主机服务在早期访问和默认情况下 `DEFAULT_BASE_URL` (单位:千美元)`https://api.bma.beeos.ai`)尚未解决。 这是部署 源,与 `BMA_BASE_URL` 在bma-sdk中(例如 `https://api.staging.bma.beeos.ai`(三); 客户端张贴环境键 `{baseUrl}/v1/executors/token` 落下一条线索 `/api/v1`。SDK不读 `BMA_BASE_URL` 自己来 A 类 `tokenSource` 携带自己的频道 URL并忽略 `baseUrl`。 。 。 .

#### 机器扫描器必须声明 `process` 或者说 `agent`

空着 `environmentId` (一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一作一 **拒绝对既未登广告的执行人进行登记 `process` 也没有 `agent` 能力**: 它回答了 `executor.register`,然后关闭 `4002` "跑步时间注册被拒绝". 壳和档案都是这样的执行者。 声明 `process` 服务 `process.*` (或 `serveAgent`),与 `executor.version` 作为 `MAJOR.MINOR.PATCH`数字 :

```ts
const client = new ExecutorClient({
  baseUrl: process.env.BMA_BASE_URL,
  environmentKey: process.env.BMA_MACHINE_TOKEN, // the machine token
  environmentId: '',                              // machine scope
  executor: { name: 'my-machine', os: process.platform, arch: process.arch, version: '1.0.0' },
  capabilities: { process: { enabled: true } },
})
client.onRequest('process.start', async (params) => { /* start it, answer with the result */ })
// ... onRequest for process.read / write / interrupt / terminate / list as needed
await client.start()
await client.waitReady(30_000) // registered and still open one heartbeat later
```

SDK将拒绝视为配置错误:在连续三次拒绝注册之后 `executor.register` (关闭) `4002` "注册时间被拒绝"或 `executor.register` 错误 `capability_unavailable` 编号 : `invalid_params`, (中文(简体) ), `waitClosed()` 拒绝方式 `RegistrationRefusedError`; 其他 `4002` 关闭( 例如“ 守护运行时间结束 ” ) 重新连接 . `state` 实值 `ready` 尽快 `executor.register` 返回,拒绝登记者也这样做; `waitReady(timeoutMs?)` 只在注册保持一个心跳间隔后解决,并用结束的客户端的错误拒绝.

### 执行者生命周期、取消和结果

-   `tool.cancel` 中止处理器 `signal` (对) `deadline_ms` 财务报告和审定财务报表 `stop()`); 客户端回答 `{"canceled":true}` 和报告 `outcome: "canceled"`重复 `tool.call` id 确认, 不运行 两次 每个内置工具都有一个打入的插槽 `client.tools.<name>.handle(fn)` (单位:千美元)`bash`, (中文(简体) ), `read`, (中文(简体) ), `write`, (中文(简体) ), `edit`, (中文(简体) ), `glob`, (中文(简体) ), `grep`, (中文(简体) ), `list_files`; 数据 `computer_*` 工具在合同确定输入时获得插槽) 输入是合同的 `<Tool>Input`。输入缺失需要的成员 无法调用( n)`bash requires command`)在操作者运行之前. A 类 处理器返回字符串、内容块或 `{ content, isError, artifacts }`; 击打可能返回 `{ stdout, stderr, exitCode, truncated? }`, (中文(简体) ), 由Go Core完成(Stout, stderr, `exit_code: N`,切入到 Core 的 预览超出 `INLINE_RESULT_BYTES`) (中文(简体) ). `throw new ToolError(msg)` 报告 工具级错误( q)`is_error: true`;任何其他例外是: `outcome: "failed"`A级 `tool.call` 没有处理器的工具被拒绝 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}在撞击之前 `-32012` (单位:千美元)`data.capability: "tool:<name>"`),作为去 科里拒绝.
-   这个 `shell` 财务报告和审定财务报表 `files` 在操作时启用了能力 组已注册,除非您设定 `enabled: false` (胜利,就像 MCP的音乐 `RegisteredTool.enabled`); 之后注册的处理器 `start()` 发送 `executor.capabilities.update`,作为 MCP 服务器发送 `tools/list_changed`。 。 。 .
-   打电话 `sessionReady` 工作空间/MCP设置后 `sessionEnded` 之后 清净相. `tool.result` 正在重审 `-32009`, (中文(简体) ), `-32004` 或者说 `data.retryable: true`时 `tool_call_id`; 当每次尝试 失败 `onToolResultLost` 获得持续的结果,并重放.
-   重新连接: 直到 `stop()` 默认的,以指数倒置(1 s base, ×2, 60 s 盖, 焦急),每个拨号一个新鲜的代币和 `resume` (单位:千美元)`executor_id`, (中文(简体) ), `last_connection_id`, (中文(简体) ), `active_sessions`) (中文(简体) ). 只有关闭代码4003和4004和3 连续拒绝注册,是终端。 阳性 `maxReconnectAttempts` 限制尝试. `await client.waitClosed()` 解决 `stop()` 编号 : `executor.close` 和拒绝 与 `ChannelClosedError` (4003/4004), (中文(简体) ), `RegistrationRefusedError`, (中文(简体) ), `CredentialRejectedError` (符号) 端点回答 401/403 关于重接: 吊销或无效证书, 不 (经重新审理)或 `ReconnectExhaustedError`; 在拒绝时退出进程 主管可以重启 .
-   `openMcpChannel(sessionId, serverKey)` 打开原始 MCP 频道 (单位:千美元)`?channel=mcp&session_id=&server_key=`(三); `read()`编号 :`write()` 携带 MCP JSON-RPC框架不变.
-   一个能扔出 `RpcError` 保持它的密码和数据在电线上. `onRequest('process.start', (params) => …)` 服务 `process.*` (读取) `sessionContext(params.process_id)` 在那里拒绝 `RpcError.withReason(code, ErrorReason.X, msg)`; 见 [会议背景](https://npmcn.com/package/%40beeos-ai/docs/executor/session-context.md), (中文(简体) ), `terminal.*`, (中文(简体) ), `skill.install` 财务报告和审定财务报表 `workspace.backup` 与合同 参数和结果类型; `call(method, params)` 财务报告和审定财务报表 `notify(method, params)` 发送执行器到harness 方法键入相同 方式( e)`MethodParamsMap` 编号 : `MethodResultMap`) (中文(简体) ).

### 快速启动

```ts
import { Harness } from "@beeos-ai/bma-executor-sdk";

const harness = new Harness({ authenticate: (request) => verify(request) }); // omit only on loopback
const { url } = await harness.listen(); // or harness.attach(httpServer)

const executor = await harness.waitExecutor();
const session = await executor.assignSession({ session_id: "sess_1" });
await session.ready();
const result = await session.tools.bash.call({ command: "ls" }); // or callTool("bash", { command: "ls" }, { toolCallId })
const mcp = await session.mcp("echo"); // raw MCP JSON-RPC
await session.stop("done");
```

语义上与去相匹配 `Harness`数字 : `callTool` 由 `toolCallId`· ; 一个未知的呼叫 `tool.result` 实值 `-32002`,外国会议 `-32007`· ; 届会和待处理的电话在内部重新连接 `leaseTtlMs`; 较新的 连接以4004取代旧的;租赁期满或 `executor.close` 无法使用 `ToolOutcomeUnknownError`。 。 。 .

### 运输

每个传送器上的信息是相同的;谁拨号独立于 协议角色( 执行器总是发送) `executor.register` (第一编).

| 运输 | 执行器结束 | 调和结束 |
| --- | --- | --- |
| WebSocket(云,执行器拨号) | 默认,或 `webSocketDialer(...)` | `listen()`, (中文(简体) ), `attach(server)`, (中文(简体) ), `handleUpgrade(...)` |
| 本地套接字、 执行器拨号 | `webSocketDialer({ ..., tokenSource: staticToken('unix:///path.sock', token) })` | `new Harness({ authenticate: bearerAuthenticator(token) }).listenLocal(path)` |
| 本地套接字, 拨号( bmad 听) | `listenExecutor({ path, token })` → `new ExecutorClient({ dialer: listener.dialer })` | `harness.dialExecutor(listener.url, { token })` |
| 进行中 | `dialer: harness.inProcessDialer()` | —— 说 |

本地套接字带有与云( 子protocol) 相同的 WebSocket 协议 通过 Unix 域名套接字谈判、 无记名符号、 关闭代码 (单位:千美元)`unix:///path.sock`, 0700目录, 0600 套接字)或名为管的 Windows (单位:千美元)`npipe:////./pipe/<name>`就像Go和Python SDK一样 每个开始写一个 新鲜的本地标志( n)`createLocalToken`, 0600);环境密钥从未使用 当地(见 [`src/local.ts`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/src/local.ts)) (中文(简体) ). 当吊带 拨打执行器,也可以拨打会话 MCP 频道(`session.mcp`) (中文(简体) ).

### 代理执行器

```ts
client.serveAgent(
  {
    openTurn: async (p) => ({ accepted: true, turn_id: p.turn_id, executor_session_ref: "conv_1", resumed: false, effective: {} }),
    runTurn: async (turn, signal) => {
      const answer = await turn.requestInteraction({ kind: "permission", tool_use_id: "tu_1", tool_name: "bash" }, signal);
      turn.emit({ type: "agent.message", content: [{ type: "text", text: answer.outcome }] });
    },
    closeSession: async () => {},
  },
  { models: [{ id: "my-model" }] },
);
```

SDK 指定事件 ID 和 顺序, 发送事件顺序 ACKs, 重新连接后重新发送, 和帧每个转动 `session.status_running` 财务报告和审定财务报表 `session.status_idle` (单位:千美元)`completed`, (中文(简体) ), `canceled`, (中文(简体) ), `failed`) (中文(简体) ). 绳子边是 `HarnessOptions.agent` (单位:千美元)`AgentPlatform`+) 加上 (中文(简体) ) `executor.startTurn / sendTurnInput / cancelTurn / closeAgentSession / respondInteraction`; 序列间隙答案 `-32013` 与 `data.expected_sequence`。 。 。 .

### 实例

[`examples`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/examples) (单位:千美元)`npm install` 首先: `executor-minimal` (云 执行者与出击), `harness-loopback` (血型) 本地套接字:执行器监听、拨号, `agent-minimal` (代理人) 执行器和一个过程中的模拟平台).

### 转到 QQ 类型脚本

| 前进( G)`github.com/beeos-ai/bma-executor-sdk`(中文(简体) ) | 类型脚本( T)`@beeos-ai/bma-executor-sdk`(中文(简体) ) |
| --- | --- |
| `NewClient(Options)` 编号 : `Start` 编号 : `Stop` | `new ExecutorClient(options)` 编号 : `start()` 编号 : `stop()` |
| `Options.TokenSource`, (中文(简体) ), `StaticToken` | `tokenSource`, (中文(简体) ), `staticToken` (或 `dialer`(中文(简体) ) |
| `Tools.<Name>.Handle(func(ctx, input, tool))` | `tools.<name>.handle(input, { signal, progress })` |
| `OnSessionAssign` 编号 : `OnSessionStop` 编号 : `OnDrain` | `onSessionAssign` 编号 : `onSessionStop` 编号 : `onDrain` |
| `Requests.ProcessStart.Handle(client, fn)` 编号 : `Calls.X.Call(ctx, client, p)` 编号 : `Notifications.X.Notify(ctx, client, p)` | `onRequest('process.start', fn)` 编号 : `call('x', p)` 编号 : `notify('x', p)` |
| `SessionReady` 编号 : `SessionEnded` 编号 : `ReportToolResult` | `sessionReady` 编号 : `sessionEnded` 编号 : `reportToolResult` |
| `SendSessionStatus` 编号 : `SendToolProgress` 编号 : `SendExecutorCapabilitiesUpdate` | `sessionStatus` 编号 : `toolProgress` 编号 : `updateCapabilities` |
| `OpenMCPChannel` → `MCPChannel` | `openMcpChannel` → `FrameChannel` |
| `ServeAgent(AgentHandler, AgentCapability)` | `serveAgent(handler, capability)` |
| `AgentTurn.Emit/EmitWithID/Delta/Flush/Inputs/RequestInteraction/CancelInteraction` | `emit/emitWithId/delta/flush/inputs/requestInteraction/cancelInteraction` |
| `NewHarness(HarnessOptions)` (单位:千美元)`http.Handler`(中文(简体) ) | `new Harness(options)` + 键 `listen/listenLocal/attach/handleUpgrade/accept/dialExecutor/inProcessDialer` |
| `Harness.WaitExecutor` 编号 : `Executors` | `waitExecutor` 编号 : `executors` |
| `Executor.AssignSession/Drain/StartTurn/SendTurnInput/CancelTurn/CloseAgentSession/RespondInteraction` | `HarnessExecutor.assignSession/drain/startTurn/sendTurnInput/cancelTurn/closeAgentSession/respondInteraction` |
| `Session.Ready/CallTool/CancelTool/Stop/MCP/Done/EndReason` | `HarnessSession.ready/callTool/cancelTool/stop/mcp/done/endReason` |
| `AgentPlatform` | `AgentPlatform` |
| `*RPCError`, (中文(简体) ), `ErrNotConnected`, (中文(简体) ), `ErrClientStopped`, (中文(简体) ), `ErrSessionEnded`, (中文(简体) ), `ErrToolOutcomeUnknown`, (中文(简体) ), `ErrAssignRejected` | `RpcError`, (中文(简体) ), `NotConnectedError`, (中文(简体) ), `ClientStoppedError`, (中文(简体) ), `SessionEndedError`, (中文(简体) ), `ToolOutcomeUnknownError`, (中文(简体) ), `AssignRejectedError` |
| `Core` (bash/files/stio MCP) (中文(简体) ) | 未提供 |
| `StaticToken("unix://…")`, (中文(简体) ), `ListenUnixSocket` + 键 `Harness.DialExecutor`, (中文(简体) ), `InProcessDialer` | `Harness.listenLocal` 编号 : `listenExecutor` + 键 `Harness.dialExecutor` 编号 : `inProcessDialer` (Go中命名为管: `ListenNamedPipe`, (中文(简体) ), `NamedPipeListener`; Python 语: `serve_npipe`(中文(简体) ) |

### 测试

`npm test` 运行符合性示例 双端 TS 端 ([`test/conformance.test.ts`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/test/conformance.test.ts)),执行者 通过重新连接和租赁,利用所有运输工具 (单位:千美元)[`test/executor.test.ts`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/test/executor.test.ts)),代理能力 (单位:千美元)[`test/agent.test.ts`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/test/agent.test.ts)),并与GO SDK对接 (单位:千美元)[`test/interop.test.ts`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/test/interop.test.ts): TS执行者 . . . . 代理 QQGO 平台, TS 控制 QQGO 执行器; 需要 GO), 并与该平台交互 在 Unix 套接字上的 WebSocket 上的 Python SDK (单位:千美元)[`test/interop-python.test.ts`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/test/interop-python.test.ts): TS 执行者 {} Python 牵引装置, Python 执行器 QQ TS 牵引装置; `BMA_PYTHON_SDK=<python dir with .venv>`跳过Unix套接字 (单位:千美元)[`test/interop-go-unix.test.ts`](https://npmcn.com/package/%40beeos-ai/bma-executor-sdk/test/interop-go-unix.test.ts)) (中文(简体) ).

## 常见问题

### @beeos-ai/bma-executor-sdk 是什么？

BMA执行器协议\(bma\.executor\.v1\.1\):执行器,取用和代理以WebSocket,本地套接字和进程内传输为结尾\.

### 如何安装 @beeos-ai/bma-executor-sdk？

在项目目录运行 npm install @beeos-ai/bma-executor-sdk，或使用 pnpm add / yarn add / bun add。

### @beeos-ai/bma-executor-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @beeos-ai/bma-executor-sdk 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @beeos-ai/bma-executor-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @beeos-ai/bma-executor-sdk 可以商用吗？

@beeos-ai/bma-executor-sdk 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @beeos-ai/bma-executor-sdk 的下载量有多少？

根据 npm 官方下载统计，@beeos-ai/bma-executor-sdk 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,599 次，日均约 120 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @beeos-ai/bma-executor-sdk 还在维护吗？

最新版本 1\.1\.0 发布于 2026/11/08（今天）；至今共发布 17 个版本，其中过去 12 个月发布了 17 个；首次发布于 2026/11/01。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。