什么是 iii

当你开始构建后端时，往往立刻就需要六种不同的工具：API 框架、任务队列、定时调度器、发布/订阅系统、状态存储以及可观测性管道。每一种都有自己的配置、部署方式和故障模式。即使只是一个“先处理这个，再通知那个”的简单工作流，在你编写任何业务逻辑之前，就已经涉及到了三种服务。

而 iii 则用一个统一的引擎和三个基本原语——函数、触发器和工作者——来取代这一切。

函数是执行具体工作的单元；触发器则是触发函数运行的原因——可以是 HTTP 请求、定时任务、队列消息或状态变化等。工作者负责将你的函数与引擎连接起来。你只需编写函数、声明其触发条件、连接一个工作者，剩下的路由、重试和可观测性等工作都将由引擎自动完成。

只需一份配置文件、一个进程，所有内容都可被自动发现。就像 React 为前端提供了一套统一的 UI 开发模型一样，iii 也为后端提供了一套统一的执行模型。

这些基本原语带来了一种独特的执行模型和系统特性，使得 iii 在构建后端软件方面表现出众：

执行模型 — 跨工作者和触发器的持久化编排；跨语言的互操作性执行，仿佛它们运行在同一个运行时中；简单的原语让复杂的分布式后端设计简化为人类和自动化代理都能理解的范式。

实时系统特性 — 由某个工作者暴露的函数和触发器会立即在整个系统中可见并可用（实时发现）。你可以在不重新设计架构的情况下，向正在运行的 iii 系统中添加新的工作者和能力（实时扩展性）。同时，你可以实时观察整个系统的操作、调用链路及行为（实时可观测性）。

三个核心概念

概念	作用
函数	工作单元。接收输入并可选择性地返回输出。它可以存在于任何地方：本地、云端、无服务器环境，或者作为第三方 HTTP 端点。
触发器	导致函数运行的触发条件——可以是代码显式调用，也可以是事件源自动触发。例如：HTTP 路由、定时任务、队列主题、状态变化、流事件等。
工作者	将你的函数和触发器连接到引擎的运行时环境。工作者无需配置即可自动注册和注销。一旦连接成功，其管理的函数便可在整个后端系统中使用。

快速入门

通过阅读 快速入门指南 即可开始使用 iii。

SDKs

语言	包名	安装命令
Node.js	iii-sdk	npm install iii-sdk
Python	iii-sdk	pip install iii-sdk
Rust	iii-sdk	添加到 Cargo.toml

代理技能

为你的 AI 编码代理提供关于 iii 的完整上下文：

npx skillkit add iii-hq/iii/skills

这些技能涵盖了 iii 的所有基本原语——HTTP 端点、队列、定时任务、状态、流、自定义触发器等。适用于 Claude Code、Cursor、Gemini CLI、Codex 以及其他 30 多种代理。完整的技能列表请参见 skills/。

控制台

iii 控制台 是一个面向开发者和运维人员的仪表板，用于检查函数、触发器、调用链路以及实时状态。有关设置和使用方法，请参阅 控制台文档。

仓库结构

目录	内容	README
engine/	iii 引擎（Rust）——核心运行时、模块和协议	engine/README.md
sdk/	Node.js、Python 和 Rust 的 SDK	sdk/README.md
console/	开发者仪表板（React + Rust）	console/README.md
frameworks/	基于 SDK 构建的高级框架	frameworks/motia/
skills/	面向 AI 编码代理的技能	skills/README.md
website/	iii 官网	website/
docs/	文档站点（Mintlify/MDX）	docs/README.md

完整的 monorepo 布局、依赖关系链以及 CI/CD 详情，请参阅 STRUCTURE.md。

示例

详细的分步教程请参阅 快速入门指南。

资源

• 文档
• CLI 和引擎
• 控制台
• 示例
• 贡献指南

许可证

iii 项目采用双许可模式：

目录	许可证
engine/	Elastic License 2.0
sdk/	Apache License 2.0
cli/	Apache License 2.0
console/	Apache License 2.0
frameworks/	Apache License 2.0
docs/	Apache License 2.0
website/	Apache License 2.0

引擎运行时采用 Elastic License 2.0（ELv2）授权。而所有 SDK、框架、CLI、控制台、文档和官网则采用 Apache License 2.0 授权。

详细信息请参阅 NOTICE.md。

iii 快速上手指南

iii 是一个统一的后端执行引擎，旨在用函数 (Function)、触发器 (Trigger) 和 工作节点 (Worker) 三个核心概念，替代传统的 API 框架、任务队列、定时调度、发布订阅等分散的基础设施。它让后端开发像 React 简化前端一样，拥有单一的执行模型。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• 运行时依赖:
  • Node.js: v18+ (如果你使用 Node.js SDK)
  • Python: v3.9+ (如果你使用 Python SDK)
  • Rust: 最新稳定版 (如果你使用 Rust SDK 或编译引擎)
• 网络: 能够访问 iii.dev 及相关包仓库（npm, pypi, crates.io）。
  • 国内加速建议: 如遇网络延迟，建议配置国内镜像源：
    • npm: npm config set registry https://registry.npmmirror.com
    • pip: pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

安装步骤

iii 采用“引擎 + SDK"的架构。你需要运行一个 iii 引擎实例，并在你的代码项目中安装对应的 SDK。

1. 启动 iii 引擎 (推荐 Docker)

最简单的方式是通过 Docker 运行 iii 引擎。它将处理路由、重试和可观测性。

docker run -d --name iii-engine -p 4000:4000 iiidev/iii

引擎默认监听在 localhost:4000。

2. 安装 SDK

根据你的开发语言，在项目目录中安装对应的 SDK：

Node.js

npm install iii-sdk
# 或使用国内镜像
# npm install iii-sdk --registry=https://registry.npmmirror.com

Python

pip install iii-sdk
# 或使用国内镜像
# pip install iii-sdk -i https://pypi.tuna.tsinghua.edu.cn/simple

Rust 在 Cargo.toml 中添加依赖：

[dependencies]
iii-sdk = "latest"

基本使用

以下以 Node.js 为例，展示如何创建一个简单的函数并将其暴露给 iii 引擎。其他语言逻辑相同。

第一步：定义函数与触发器

创建一个文件（例如 index.js），定义一个函数并声明触发它的方式（例如 HTTP 请求）。

import { Iii, HttpTrigger } from 'iii-sdk';

// 1. 初始化客户端，连接到本地引擎
const iii = new Iii({
  endpoint: 'http://localhost:4000',
});

// 2. 定义一个函数 (Function)
async function greet(input) {
  return { message: `Hello, ${input.name || 'World'}!` };
}

// 3. 注册函数并绑定触发器 (Trigger)
// 这里将 greet 函数绑定到 HTTP POST /greet 路由
iii.register(greet, {
  triggers: [
    new HttpTrigger({
      method: 'POST',
      path: '/greet',
    }),
  ],
});

// 4. 启动 Worker，连接引擎
await iii.start();

console.log('Worker connected. Function "greet" is now available via HTTP.');

第二步：运行工作节点 (Worker)

在终端中运行你的脚本。此时，该进程成为一个 Worker，它会自动向 iii 引擎注册上述函数。

node index.js

你会看到日志提示 Worker 已成功连接。

第三步：测试调用

现在，你可以直接通过 HTTP 请求调用该函数，iii 引擎会自动将请求路由到你的 Worker。

curl -X POST http://localhost:4000/greet \
  -H "Content-Type: application/json" \
  -d '{"name": "Developer"}'

预期输出：

{"message":"Hello, Developer!"}

进阶：查看控制台

iii 提供了一个可视化的开发者控制台，用于实时查看函数状态、追踪调用链路和监控系统行为。

访问 http://localhost:4000/console (具体端口视引擎配置而定，或通过单独部署 iii-console 获取更完整功能) 即可看到刚才注册的 greet 函数及其调用记录。

---

更多高级用法（如定时任务、消息队列、状态存储）请参考官方文档：https://iii.dev/docs