iii-sdk-reference

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SDK Reference

SDK参考

Use this skill for language-specific SDK details. Use

iii-core-primitives

for the common model and

iii-error-handling

for exception handling.

本技能适用于查询各语言专属的SDK细节。通用模型相关内容请使用

iii-core-primitives

，异常处理相关内容请使用

iii-error-handling

。

Install

安装

bash

undefined

bash

undefined

TypeScript / Node.js

npm install iii-sdk

Browser apps

浏览器应用

npm install iii-browser-sdk

Python

pip install iii-sdk

Rust

cargo add iii-sdk

undefined

cargo add iii-sdk

undefined

Choose the SDK

选择SDK

SDK	Package	Best for	Important caveat
Node.js	`iii-sdk`	Server-side TypeScript/JavaScript workers	Supports custom headers, Logger, OpenTelemetry, HTTP-invoked functions
Browser	`iii-browser-sdk`	Web apps and interactive UI callbacks	Connect through an RBAC-protected listener; keep secrets server-side
Python	`iii-sdk`	Sync or async Python workers	Use `trigger_async` inside async handlers
Rust	`iii-sdk`	High-performance tokio workers	Handler error type should map into `IIIError`

SDK	包名	最适用场景	重要注意事项
Node.js	`iii-sdk`	服务端TypeScript/JavaScript Worker	支持自定义请求头、Logger、OpenTelemetry、HTTP触发的函数
Browser	`iii-browser-sdk`	Web应用与交互式UI回调	通过RBAC保护的监听器连接；敏感信息需保留在服务端
Python	`iii-sdk`	同步或异步Python Worker	在异步处理器内使用 `trigger_async`
Rust	`iii-sdk`	高性能tokio Worker	处理器错误类型需映射为 `IIIError`

Common API Map

通用API映射

Capability	Node	Python	Rust
Connect worker	`registerWorker(url, options?)`	`register_worker(address, options?)`	`register_worker(url, InitOptions)`
Register local function	`registerFunction(id, handler, options?)`	`register_function(id, handler, **options)`	`register_function(RegisterFunction::new(...))`
Register trigger	`registerTrigger({ type, function_id, config })`	`register_trigger({...})`	`register_trigger(RegisterTriggerInput { ... })`
Invoke function	`trigger({ function_id, payload })`	`trigger(request)` / `trigger_async(request)`	`trigger(TriggerRequest)`
Durable enqueue	`TriggerAction.Enqueue({ queue })`	`{"type": "enqueue", "queue": name}`	`TriggerAction::Enqueue { queue }`
Channels	`createChannel()`	`create_channel()` / `create_channel_async()`	`create_channel(None).await`

功能	Node	Python	Rust
连接Worker	`registerWorker(url, options?)`	`register_worker(address, options?)`	`register_worker(url, InitOptions)`
注册本地函数	`registerFunction(id, handler, options?)`	`register_function(id, handler, **options)`	`register_function(RegisterFunction::new(...))`
注册触发器	`registerTrigger({ type, function_id, config })`	`register_trigger({...})`	`register_trigger(RegisterTriggerInput { ... })`
调用函数	`trigger({ function_id, payload })`	`trigger(request)` / `trigger_async(request)`	`trigger(TriggerRequest)`
持久化入队	`TriggerAction.Enqueue({ queue })`	`{"type": "enqueue", "queue": name}`	`TriggerAction::Enqueue { queue }`
通道	`createChannel()`	`create_channel()` / `create_channel_async()`	`create_channel(None).await`

Node.js

typescript

import { Logger, registerWorker } from "iii-sdk";

const iii = registerWorker("ws://localhost:49134", {
  workerName: "node-worker",
  invocationTimeoutMs: 30000,
});

iii.registerFunction("users::lookup", async (input) => {
  new Logger().info("looking up user", { userId: input.userId });
  return { userId: input.userId, name: "Ada" };
});

Node supports custom WebSocket headers,

Logger

, OpenTelemetry options, HTTP-invoked function registration, trigger metadata, channels, and custom trigger types.

typescript

import { Logger, registerWorker } from "iii-sdk";

const iii = registerWorker("ws://localhost:49134", {
  workerName: "node-worker",
  invocationTimeoutMs: 30000,
});

iii.registerFunction("users::lookup", async (input) => {
  new Logger().info("looking up user", { userId: input.userId });
  return { userId: input.userId, name: "Ada" };
});

Node.js支持自定义WebSocket请求头、

Logger

、OpenTelemetry选项、HTTP触发函数注册、触发器元数据、通道以及自定义触发器类型。

Browser

浏览器

typescript

import { registerWorker, TriggerAction } from "iii-browser-sdk";

const iii = registerWorker("wss://api.example.com/worker?token=session-token");

const result = await iii.trigger({
  function_id: "backend::get-user",
  payload: { userId: "123" },
});

await iii.trigger({
  function_id: "analytics::track",
  payload: { event: "page_view" },
  action: TriggerAction.Void(),
});

Do not expose the private engine worker port to untrusted browsers. Browser workers cannot send custom WebSocket headers and must not hold backend secrets.

typescript

import { registerWorker, TriggerAction } from "iii-browser-sdk";

const iii = registerWorker("wss://api.example.com/worker?token=session-token");

const result = await iii.trigger({
  function_id: "backend::get-user",
  payload: { userId: "123" },
});

await iii.trigger({
  function_id: "analytics::track",
  payload: { event: "page_view" },
  action: TriggerAction.Void(),
});

请勿向不可信浏览器暴露私有引擎Worker端口。浏览器Worker无法发送自定义WebSocket请求头，且不得存储后端敏感信息。

Python

python

from iii import InitOptions, Logger, register_worker

iii = register_worker(
    address="ws://localhost:49134",
    options=InitOptions(worker_name="python-worker"),
)

def lookup_user(data):
    Logger().info("looking up user", {"userId": data["userId"]})
    return {"userId": data["userId"], "name": "Ada"}

iii.register_function("users::lookup", lookup_user)

Python handlers may be sync or async. Use

await iii.trigger_async(request)

inside async handlers, and

iii.trigger(request)

in sync contexts.

ApiResponse

uses camelCase

statusCode

python

from iii import InitOptions, Logger, register_worker

iii = register_worker(
    address="ws://localhost:49134",
    options=InitOptions(worker_name="python-worker"),
)

def lookup_user(data):
    Logger().info("looking up user", {"userId": data["userId"]})
    return {"userId": data["userId"], "name": "Ada"}

iii.register_function("users::lookup", lookup_user)

Python处理器支持同步或异步模式。异步处理器内请使用

await iii.trigger_async(request)

，同步上下文则使用

iii.trigger(request)

。

ApiResponse

采用小驼峰命名的

statusCode

。

Rust

rust

use iii_sdk::{register_worker, InitOptions, RegisterFunction};
use serde_json::json;

let iii = register_worker("ws://127.0.0.1:49134", InitOptions::default());

iii.register_function(
    RegisterFunction::new("users::lookup", |input: serde_json::Value| {
        Ok(json!({ "userId": input["userId"], "name": "Ada" }))
    }).description("Look up a user"),
)?;

Rust supports typed handlers and schema extraction when input/output types derive

schemars::JsonSchema

. Add the

otel

feature when using OpenTelemetry helpers.

rust

use iii_sdk::{register_worker, InitOptions, RegisterFunction};
use serde_json::json;

let iii = register_worker("ws://127.0.0.1:49134", InitOptions::default());

iii.register_function(
    RegisterFunction::new("users::lookup", |input: serde_json::Value| {
        Ok(json!({ "userId": input["userId"], "name": "Ada" }))
    }).description("Look up a user"),
)?;

当输入/输出类型派生自

schemars::JsonSchema

时，Rust支持类型化处理器和Schema提取。使用OpenTelemetry工具时请添加

otel

特性。

Channels

通道

Use channels for binary data, large payloads, or streaming transfer between workers.
Pass
```
readerRef
```
or
```
writerRef
```
through a function payload.
Reconstruct readers/writers from refs in consumers when the SDK requires it.

通道适用于Worker间的二进制数据、大负载或流式传输场景。
通过函数负载传递
```
readerRef
```
或
```
writerRef
```
。
当SDK要求时，在消费者端通过引用重构读取器/写入器。

When to Use

使用场景

Use this skill for package names, SDK exports, initialization options, browser security constraints, channel API details, and language-specific syntax.
Use this when a task asks for Python or Rust examples and the issue is SDK syntax rather than iii architecture.

本技能适用于查询包名、SDK导出内容、初始化选项、浏览器安全约束、通道API细节以及各语言专属语法。
当任务需要Python或Rust示例，且问题聚焦于SDK语法而非iii架构时，可使用本技能。

Boundaries

边界说明

For the common Function/Trigger/Worker model, built-in trigger schemas, custom triggers, and invocation mode decisions, use
```
iii-core-primitives
```
.
For deployment config, queue adapter policy, worker manager, RBAC listeners, and ports, use
```
iii-engine-config
```
.
For retryability and exception classes, use
```
iii-error-handling
```
.

通用函数/触发器/Worker模型、内置触发器Schema、自定义触发器以及调用模式决策相关内容，请使用
```
iii-core-primitives
```
。
部署配置、队列适配器策略、Worker管理器、RBAC监听器以及端口相关内容，请使用
```
iii-engine-config
```
。
重试机制与异常类相关内容，请使用
```
iii-error-handling
```
。