# @actiondock/sdk 中文文档

规范地址：https://npmcn.com/package/%40actiondock/sdk/

版本：2\.22\.0
npm 元数据更新时间：2026-10-29T09:01:00.534Z
中文译文更新时间：2026-11-06T17:45:43.784Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：39.9 kB，14 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.12\.0
- 运行依赖：0 个
- 首次发布：2026-09-02T08:43:07.717Z
- 最新版本发布：2026-10-29T09:01:00.089Z
- 近 30 天下载量：2551（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：40（近 12 个月 40 个）

## 中文简介

ActionDock SDK用于定义和测试独立的AI代理动作

## 安装

```sh
npm install @actiondock/sdk
```

也可以使用：`pnpm add @actiondock/sdk`、`yarn add @actiondock/sdk`、`bun add @actiondock/sdk`

## README

# @actiondock/sdk

ActionDock 2.x 纯净核心开发者接口契约包。

[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24.12.0-green?logo=node.js)](https://nodejs.org/) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

`@actiondock/sdk` 为开发者编写原子 Action 提供零生产依赖的纯净类型定义与核心契约。测试工具（`createTestRuntime`、`FakeClock`、`FakeProcessDriver`、`MockProcessExecutor`、`MemoryStorage`）已全面收敛至 [@actiondock/testing](https://npmcn.com/package/%40actiondock/testing/README.md)。

* * *

## 安装方式

使用标准包管理器添加依赖：

```bash
npm install @actiondock/sdk
```

* * *

## 核心接口与函数

### defineAction 函数

用于定义具备强类型推导的原子 Action 业务逻辑：

```ts
import { defineAction } from "@actiondock/sdk";

export interface AddInput {
  a: number;
  b: number;
}

export interface AddOutput {
  result: number;
}

export default defineAction(async (input: AddInput, ctx): Promise<AddOutput> => {
  ctx.log.info(`计算加法: ${input.a} + ${input.b}`);
  return {
    result: input.a + input.b,
  };
});
```

也可以传入包含 `run` 方法的对象形式：

```ts
import { defineAction } from "@actiondock/sdk";

export default defineAction({
  async run(input, ctx) {
    return { ok: true };
  },
});
```

* * *

## ActionContext 运行时上下文

在 Action 执行时，宿主环境注入标准化上下文对象 `ActionContext`，提供受控的系统交互能力：

-   `ctx.process`：统一受管进程接口 ProcessAPI，提供一次性执行 run、长期受管进程 start、独占控制权治理、逐流增量读取与优雅终止。
-   `ctx.log`：结构化日志输出接口 Logger，提供 `debug`、`info`、`warn`、`error` 级别日志。日志严格输出至标准错误流，彻底隔离标准输出流，杜绝污染协议报文。
-   `ctx.progress`：进度报告器 ProgressReporter，支持在执行过程中通过 `report(current, total, message)` 上报当前阶段。
-   `ctx.signal`：协作式取消信号 AbortSignal。当任务被外部客户端取消或超时时自动触发中止。
-   `ctx.run`：当前执行实例元数据，包含 `id`（本次运行标识）、`rootId`（根调用标识）和 `parentId`（父级调用标识）。
-   `ctx.config`：分层配置读取接口 Config，提供 `get` 与 `has` 方法，支持优先级回退与类型强转。
-   `ctx.state`：持久化状态接口 StateStore，提供基于当前包命名空间隔离的键值存储与存活时间控制。
-   `ctx.actions`：动作相互调用接口 ActionInvoker，支持直接调用或通过 `invoke` 方法调用下游 Action，并内置调用栈环路死锁检测。

* * *

## 受管进程接口与辅助工具

SDK 为受管进程提供了完整的接口契约与开箱即用的高阶交互工具：

### 核心接口 ProcessAPI

-   `ctx.process.run(input, call)`：一次性运行外部命令，超时自动终止并收集有限输出。
-   `ctx.process.start(input, call)`：创建长期受管进程，返回进程元数据与输出流初始游标。
-   `ctx.process.inspect(id, call)`：查看指定受管进程的最新状态快照。
-   `ctx.process.list(input, call)`：分页列出当前可见的受管进程。
-   `ctx.process.acquire(id, input, call)`：申请指定进程的独占控制令牌。
-   `ctx.process.renew(id, token, ttlMs, call)`：延长控制令牌的存活时间。
-   `ctx.process.release(id, token, call)`：显式释放控制令牌。
-   `ctx.process.write(id, input, call)`：向受管进程输入流写入 Base64 编码的原始字节。
-   `ctx.process.operation(id, requestId, call)`：按请求标识查询写入或控制操作的调度收据。
-   `ctx.process.read(id, input, call)`：基于游标读取有界原始输出日志，支持长轮询与断层跳跃。
-   `ctx.process.control(id, input, call)`：发送 `input-eof`、`interrupt-foreground` 或 `resize` 结构化控制指令。
-   `ctx.process.stop(id, input, call)`：优雅终止受管进程并执行跨平台进程树清理。

### 高阶辅助工具函数

-   `withControl(api, processId, options, fn)`：在独占控制权保护下执行异步业务函数。自动申请令牌、在存活期内按三分之一 TTL 周期定期自动续租、正常完成显式调用 `release`；若发生异常、取消中断或续租失败，严禁调用 `release`，主动按契约调用 `stop` 隔离或终止进程并抛出原始错误。
-   `createStreamDecoder()`（别名 `createIncrementalTextDecoder()`）：创建逐流增量 UTF-8 解码器，为不同输出流独立缓存残缺的多字节字符，杜绝切块乱码与多流交错污染。
-   `encodeText(text)` / `encodeBytes(data)`：将纯文本或二进制数据编码为标准的 Base64 `Bytes` 结构。
-   `decodeText(bytesOrChunks)` / `decodeBytes(bytes)`：将 `Bytes` 结构或 `OutputChunk` 数组快速解码为 UTF-8 文本或二进制数组。

* * *

## 单元测试支持

测试工具已全面收敛至 [@actiondock/testing](https://npmcn.com/package/%40actiondock/testing/README.md)。在测试中使用 `createTestRuntime` 进行纯内存毫秒级验证：

```ts
import { describe, it } from "node:test";
import assert from "node:assert/strict";
import { createTestRuntime } from "@actiondock/testing";
import addAction from "../actions/add.js";

describe("add action", () => {
  it("calculates sum correctly", async () => {
    const runtime = createTestRuntime();
    const res = await runtime.run(addAction, { a: 10, b: 20 });
    assert.equal(res.result, 30);
  });
});
```

* * *

## 开源协议

本项目采用 Apache-2.0 开源协议。

## 常见问题

### @actiondock/sdk 是什么？

ActionDock SDK用于定义和测试独立的AI代理动作

### 如何安装 @actiondock/sdk？

在项目目录运行 npm install @actiondock/sdk，或使用 pnpm add / yarn add / bun add。

### @actiondock/sdk 支持 TypeScript 吗？

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

### @actiondock/sdk 支持 ESM 还是 CommonJS？

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

### @actiondock/sdk 需要什么版本的 Node\.js？

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

### @actiondock/sdk 可以商用吗？

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

### @actiondock/sdk 的下载量有多少？

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

### @actiondock/sdk 还在维护吗？

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