@actiondock/sdk
ActionDock 2.x 纯净核心开发者接口契约包。
@actiondock/sdk 为开发者编写原子 Action 提供零生产依赖的纯净类型定义与核心契约。测试工具（createTestRuntime、FakeClock、FakeProcessDriver、MockProcessExecutor、MemoryStorage）已全面收敛至 @actiondock/testing。
安装方式
使用标准包管理器添加依赖：
npm install @actiondock/sdk
核心接口与函数
defineAction 函数
用于定义具备强类型推导的原子 Action 业务逻辑：
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 方法的对象形式：
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)：将纯文本或二进制数据编码为标准的 Base64Bytes结构。decodeText(bytesOrChunks)/decodeBytes(bytes)：将Bytes结构或OutputChunk数组快速解码为 UTF-8 文本或二进制数组。
单元测试支持
测试工具已全面收敛至 @actiondock/testing。在测试中使用 createTestRuntime 进行纯内存毫秒级验证：
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 开源协议。