如何用 iii SDK 新建一个 worker 并连接引擎注册函数与触发器？

如何用 iii SDK 新建一个 worker 并连接引擎注册函数与触发器？

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii

你的任务是从零创建一个 iii worker：用 iii SDK 写一个普通 TypeScript 项目，让它通过 WebSocket 连接 iii 引擎，注册一个可被系统调用的函数（math::add），并把该函数绑定到一个http触发器上，最后用iii triggerCLI 和 HTTP 请求两条路径验证它真的工作。适用前提：本地已安装 iii CLI、引擎正在运行，且你能启动 Compose daemon（用于引入提供http触发器类型的 http worker）。文中主路径以 Node / TypeScript 为例，源文档同时提供了 Python、Rust 的等价 API。

准备条件：安装 iii 并启动引擎

按 Install 文档 的命令安装 iii 引擎并初始化项目（安装脚本会从远程下载安装 iii CLI，属于会修改本机的操作，确认环境允许后再执行）：

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh iii project init iii-app && cd iii-app

在项目目录中启动引擎，该终端保持不关闭：

iii --config config.yaml

引擎启动后监听ws://localhost:49134。再开第二个终端，在同一目录下创建 Compose 文件并启动 Compose daemon：

printf 'containers: {}\n' > worker-compose.yaml iii compose --namespace dev --engine ws://127.0.0.1:49134

Compose daemon 是必选步骤：http这种触发器类型由独立的 http worker 发布，而引入 registry 里的 worker（如 http）要通过 Compose 的compose::add完成。第三个终端用于执行后续所有命令，且都在项目目录下。

创建 worker 项目并声明 manifest

按 Creating Workers / Workers 的说明，worker 就是一个安装了 iii SDK、能连上引擎并注册函数或触发器的进程。用语言自带的包管理工具建一个正常的 TypeScript 项目，安装 SDK 并提供src/index.ts之类的入口：

npm install iii-sdk

为了让 Compose 能启动这个本地 worker，在项目根目录放置iii.worker.yamlmanifest。manifest 描述的是“如何启动”worker，示例值来自文档：

name: my-worker description: One-line summary of what this worker does. scripts: start: pnpm start

scripts.start是 Compose 实际执行的启动命令，把它指向你项目里运行src/index.ts的方式（start脚本按你项目自身的构建/运行方案配置）。worker 一旦跑起来，iii 对 Compose 托管的进程和手动运行的 SDK 进程一视同仁。

版本约束：引擎和 SDK 包可以在同一 minor 线内使用不同的 patch 版本，但要保持在同一 minor 版本（文档举例0.11.x），除非 release note 另有说明。

连接引擎并注册函数与触发器

入口代码src/index.ts如下，各段均来自文档中的 Node / TypeScript 示例：

import { registerWorker } from "iii-sdk"; const url = process.env.III_URL; if (!url) throw new Error("III_URL must be set"); const worker = registerWorker(url, { workerName: "my-worker", workerDescription: "One-line summary of what this worker does", }); worker.registerFunction("math::add", async (payload: { a: number; b: number }) => { return { c: payload.a + payload.b }; }); worker.registerTrigger({ type: "http", function_id: "math::add", config: { api_path: "/math/add", http_method: "POST" }, });

几点必须知道的语义：

• 连接方式：worker 通过 WebSocket 连引擎，约定是环境变量III_URL提供引擎地址（也可以显式传给registerWorker）。这条连接串是 worker 与 iii 实例之间唯一的耦合，worker 进程可以部署在任何网络可达的位置。workerName缺省时显示名为hostname:pid。
• 函数 id：registerFunction的 id 使用service::name形式，触发器通过它引用你的函数。
• 触发器绑定是乐观的：即使此刻 http worker 还没连接，registerTrigger也会被引擎存储，等 http worker 加入后自动激活，无需重新注册。绑定顺序不敏感。
• 可选的请求/响应 schema：registerFunction可以带request_format/response_format（JSON Schema）。它们只作为契约文档展示在 console、iii trigger --help和 agent 可读的资料里，目前不做运行时校验，引擎不会因 payload 不匹配而拒绝。

通过 Compose 启动 worker

在第三个终端（项目目录）执行，-n是--namespace的缩写，指向正在运行的 Compose daemon 的命名空间：

iii trigger -n dev compose::add worker=./workers/my-worker

Compose daemon 终端会报告 worker 进入 ready（文档示例输出，耗时数值仅为示例）：

→ my-worker starting ✓ my-worker ready (2.1s) up: 1 of 1 changed in 2.1s

Linux/WSL2 上的已知问题：Compose 托管的 worker 启动在 microVM 中，需要读写/dev/kvm。如果 worker 启动失败并出现KVM not accessible，说明当前用户不在kvm组，按 Troubleshooting 的处理方式：

sudo usermod -aG kvm $USER

该命令需要 sudo 权限，修改的是系统用户组归属；之后要重启会话让新组生效，WSL2 下从 Windows 终端执行wsl --shutdown再重新打开发行版。

验证函数注册与触发器绑定

1. 直接调用函数。引擎按注册的函数路由调用，不涉及触发器：

iii trigger math::add a=2 b=3

文档示例输出为{ "c": 5 }。如果刚添加完 worker 就调用，看到"message": "Function math::add not found"时，等几秒再试——worker 在被添加后需要一点时间安装运行时依赖。

2. 查看函数帮助。iii trigger与其他路径走完全相同的代码，可以当作开发工具直接用：

iii trigger math::add --help

函数如果附带了请求/响应 schema，这里会显示参数结构。

3. 引入 http worker 并验证触发器。先加入发布http触发器类型的 http worker：

iii trigger -n dev compose::add worker=http

之前注册的那个 http 触发器绑定会自动激活，然后发请求（http worker 的默认端口是 3111）：

curl -X POST http://localhost:3111/math/add \ -H 'Content-Type: application/json' \ -d '{"a": 2, "b": 3}'

文档示例：返回 200 OK，请求通过已激活的触发器到达math::add，响应体是 handler 的返回值（本例即{ "c": 5 }）。同一个函数在 handler 不变的前提下，同时响应 CLI 调用和 HTTP 请求。

4. 查看引擎的注册表。引擎自身注册了一组 introspection 函数，调用方式与普通函数相同（iii trigger或 worker 代码里的worker.trigger），完整清单见 Using iii / Functions：

也可以在浏览器里用iii console打开交互式界面，查看 workers、functions、triggers、日志和状态。

失败现象与限制

• 命名空间冲突：worker 身份是(namespace, name)，同一命名空间内名字独占；重复的活 owner 会被拒绝，错误码WORKER_NAMESPACE_CONFLICT。Node SDK 将其视为致命错误，停止且不再重连。需要多租户/多项目共存时，用registerWorker的namespace选项或III_NAMESPACE环境变量（解析顺序：options.namespace→III_NAMESPACE→ 引擎的default命名空间）把不同部署放到不同命名空间。
• 触发器注册被拒绝：当活跃的 provider worker 拒绝你给的 config（例如不合法的 trigger config），引擎会向发起注册的 worker 回送带error内容的TriggerRegistrationResult并记录日志。
• worker 断开：WebSocket 关闭时，引擎自动把它的 Functions 和 Triggers 移出注册表，进行中的调用被取消，调用方会收到invocation_stopped错误，需要捕获并按取消处理，等 worker 重连后再重试。
• schema 不校验：函数和触发器类型的请求/响应 schema 都是信息性的，引擎不会拒绝不匹配的值，这一点在写契约时要留意。

优雅停机与下一步

worker 退出时用 SDK 的shutdown干净关闭 WebSocket，引擎会确定性地移除它的注册并触发engine::workers-available事件；文档给出的 Node 示例：

process.on("SIGTERM", async () => { await worker.shutdown(); process.exit(0); });

不显式调用shutdown时，进程异常退出最终会达到同样的清理结果，只是时机取决于引擎何时注意到断开的 socket。

完成本文后，可以继续：给同一函数绑定多个不同触发器（如 http + cron）、用condition_function_id为触发器加条件门控（见 Using iii / Triggers）、编写自己的触发器类型供其他 worker 绑定（见 Creating Workers / Triggers），以及为 worker 添加状态（state worker）与更多语言的等价写法（见 Workers 总览 与 Quickstart）。

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii