Back to Details

iii-getting-started

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Getting Started with iii

iii 快速入门

iii replaces your API framework, task queue, cron scheduler, pub/sub, state store, and observability pipeline with a single engine and three primitives: Function, Trigger, Worker.
iii 用单个引擎和三个基础组件替代你的API框架、任务队列、cron调度器、发布/订阅、状态存储以及可观测性流水线：Function、Trigger、Worker。

Step 1: Install the Engine

步骤1：安装引擎

bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh
Verify it installed:
bash
iii --version
bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh
验证安装结果：
bash
iii --version

Step 2: Create a Project

步骤2：创建项目

bash
iii create
Follow the interactive prompts to select a template and language. The default quickstart template includes TypeScript, Python, and Rust workers.
Then change into the project directory you chose at the prompt:
bash
cd <your-project>
bash
iii create
跟随交互式提示选择模板和语言。默认快速入门模板包含TypeScript、Python和Rust Worker。
然后切换到你在提示中选择的项目目录：
bash
cd <your-project>

Step 3: Start the Engine

步骤3：启动引擎

bash
iii --config iii-config.yaml
The engine starts and listens for worker connections on 
ws://localhost:49134
. The REST API is available at 
http://localhost:3111
. The console is available at 
http://localhost:3113
.
bash
iii --config iii-config.yaml
引擎启动后会在
ws://localhost:49134
监听Worker连接。REST API可通过
http://localhost:3111
访问，控制台可通过
http://localhost:3113
访问。

Step 4: Install the SDK

步骤4：安装SDK

Pick your language:
bash
undefined
选择你的语言：
bash
undefined

TypeScript / Node.js

TypeScript / Node.js

npm install iii-sdk
npm install iii-sdk

Python

Python

pip install iii-sdk
pip install iii-sdk

Rust — add to Cargo.toml

Rust — 添加到 Cargo.toml

[dependencies]

[dependencies]

iii-sdk = "*"

iii-sdk = "*"

undefined
undefined

Step 5: Write Your First Worker

步骤5：编写你的第一个Worker

TypeScript

TypeScript

typescript
import { registerWorker, Logger, TriggerAction } from 'iii-sdk'

const iii = registerWorker(process.env.III_URL ?? 'ws://localhost:49134')

iii.registerFunction(
  'hello::greet',
  async (input) => {
    const logger = new Logger()
    const name = input?.name ?? 'world'
    logger.info('Greeting user', { name })
    return { message: `Hello, ${name}!` }
  },
  { description: 'Greet a user by name' },
)

iii.registerTrigger({
  type: 'http',
  function_id: 'hello::greet',
  config: { api_path: '/hello', http_method: 'POST' },
})
typescript
import { registerWorker, Logger, TriggerAction } from 'iii-sdk'

const iii = registerWorker(process.env.III_URL ?? 'ws://localhost:49134')

iii.registerFunction(
  'hello::greet',
  async (input) => {
    const logger = new Logger()
    const name = input?.name ?? 'world'
    logger.info('Greeting user', { name })
    return { message: `Hello, ${name}!` }
  },
  { description: 'Greet a user by name' },
)

iii.registerTrigger({
  type: 'http',
  function_id: 'hello::greet',
  config: { api_path: '/hello', http_method: 'POST' },
})

Python

Python

python
from iii import register_worker, InitOptions, Logger

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

def greet(data):
    logger = Logger()
    name = data.get("name", "world") if isinstance(data, dict) else "world"
    logger.info("Greeting user", {"name": name})
    return {"message": f"Hello, {name}!"}

iii.register_function({"id": "hello::greet", "description": "Greet a user by name"}, greet)
iii.register_trigger({"type": "http", "function_id": "hello::greet", "config": {"api_path": "/hello", "http_method": "POST"}})
python
from iii import register_worker, InitOptions, Logger

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

def greet(data):
    logger = Logger()
    name = data.get("name", "world") if isinstance(data, dict) else "world"
    logger.info("Greeting user", {"name": name})
    return {"message": f"Hello, {name}!"}

iii.register_function({"id": "hello::greet", "description": "Greet a user by name"}, greet)
iii.register_trigger({"type": "http", "function_id": "hello::greet", "config": {"api_path": "/hello", "http_method": "POST"}})

Rust

Rust

rust
use iii_sdk::{register_worker, InitOptions, Logger, RegisterFunctionMessage, RegisterTriggerInput};
use serde_json::json;

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

iii.register_function(
    RegisterFunctionMessage::with_id("hello::greet".into()),
    |input: serde_json::Value| async move {
        let logger = Logger::new();
        let name = input["name"].as_str().unwrap_or("world");
        logger.info("Greeting user", Some(&json!({ "name": name })));
        Ok(json!({ "message": format!("Hello, {}!", name) }))
    },
);

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "http".into(),
    function_id: "hello::greet".into(),
    config: json!({ "api_path": "/hello", "http_method": "POST" }),
})?;
rust
use iii_sdk::{register_worker, InitOptions, Logger, RegisterFunctionMessage, RegisterTriggerInput};
use serde_json::json;

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

iii.register_function(
    RegisterFunctionMessage::with_id("hello::greet".into()),
    |input: serde_json::Value| async move {
        let logger = Logger::new();
        let name = input["name"].as_str().unwrap_or("world");
        logger.info("Greeting user", Some(&json!({ "name": name })));
        Ok(json!({ "message": format!("Hello, {}!", name) }))
    },
);

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "http".into(),
    function_id: "hello::greet".into(),
    config: json!({ "api_path": "/hello", "http_method": "POST" }),
})?;

Step 6: Test It

步骤6：进行测试

bash
curl -X POST http://localhost:3111/hello \
  -H "Content-Type: application/json" \
  -d '{"name": "iii"}'
Expected response:
json
{"message": "Hello, iii!"}
bash
curl -X POST http://localhost:3111/hello \
  -H "Content-Type: application/json" \
  -d '{"name": "iii"}'
预期响应：
json
{"message": "Hello, iii!"}

Install Agent Skills

安装Agent技能

Get all iii skills for your AI coding agent:
bash
npx skillkit add iii-hq/iii/skills
Skills teach your agent how to use every iii primitive — HTTP endpoints, cron scheduling, queues, state management, streams, channels, and more. Available for Claude Code, Cursor, Codex, Gemini CLI, and 30+ other agents.
获取适用于AI编码Agent的所有iii技能：
bash
npx skillkit add iii-hq/iii/skills
这些技能会教你的Agent如何使用iii的所有基础组件——HTTP端点、cron调度、队列、状态管理、流、通道等。支持Claude Code、Cursor、Codex、Gemini CLI以及30+其他Agent。

Adapting This Pattern

适配此模式

  • Add more functions to the same worker — each gets its own 
    registerFunction
    + 
    registerTrigger
    calls
  • Use 
    ::
    separator for function IDs to namespace them: 
    orders::create
    , 
    orders::validate
  • Add cron triggers with 
    { type: 'cron', config: { expression: '0 0 9 * * * *' } }
    (7-field: sec min hour day month weekday year)
  • Add queue triggers with 
    { type: 'durable:subscriber', config: { topic: 'my-queue' } }
  • Use 
    iii.trigger()
    to invoke other functions from within a function
  • Use 
    state::get
    / 
    state::set
    to persist data across function calls
  • 向同一个Worker添加更多函数——每个函数都需要单独的
    registerFunction
    + 
    registerTrigger
    调用
  • 使用
    ::
    分隔符为函数ID命名空间：
    orders::create
    、
    orders::validate
  • 添加cron触发器，格式为
    { type: 'cron', config: { expression: '0 0 9 * * * *' } }
    （7字段格式：秒 分 时 日 月 周 年）
  • 添加队列触发器，格式为
    { type: 'durable:subscriber', config: { topic: 'my-queue' } }
  • 在函数内部使用
    iii.trigger()
    调用其他函数
  • 使用
    state::get
    / 
    state::set
    在函数调用之间持久化数据

Recommended Next Steps

推荐后续步骤

After getting your first worker running:
  1. Add state — Use 
    iii-state-management
    skill to persist data
  2. Add a queue — Use 
    iii-queue-processing
    skill for async job processing
  3. Add a cron job — Use 
    iii-cron-scheduling
    skill for scheduled tasks
  4. Build an API — Use 
    iii-http-endpoints
    skill for REST endpoints with CRUD
  5. Add observability — Use 
    iii-observability
    skill for tracing and metrics
  6. Explore architecture patterns — See 
    iii-agentic-backend
    , 
    iii-reactive-backend
    , 
    iii-workflow-orchestration
在你的第一个Worker运行起来之后：
  1. 添加状态管理——使用
    iii-state-management
    技能持久化数据
  2. 添加队列——使用
    iii-queue-processing
    技能处理异步任务
  3. 添加定时任务——使用
    iii-cron-scheduling
    技能实现定时任务
  4. 构建API——使用
    iii-http-endpoints
    技能创建带CRUD功能的REST端点
  5. 添加可观测性——使用
    iii-observability
    技能实现追踪和指标监控
  6. 探索架构模式——查看
    iii-agentic-backend
    、
    iii-reactive-backend
    、
    iii-workflow-orchestration

Key Resources

关键资源

Pattern Boundaries

模式适用边界

  • For HTTP endpoint patterns (CRUD, parameterized routes), prefer 
    iii-http-endpoints
  • For cron/scheduling patterns, prefer 
    iii-cron-scheduling
  • For queue/async job patterns, prefer 
    iii-queue-processing
  • For state persistence patterns, prefer 
    iii-state-management
  • For engine configuration, prefer 
    iii-engine-config
  • Stay with 
    iii-getting-started
    for installation, initial setup, and first-worker guidance
  • 对于HTTP端点模式（CRUD、参数化路由），优先使用
    iii-http-endpoints
  • 对于cron/调度模式，优先使用
    iii-cron-scheduling
  • 对于队列/异步任务模式，优先使用
    iii-queue-processing
  • 对于状态持久化模式，优先使用
    iii-state-management
  • 对于引擎配置，优先使用
    iii-engine-config
  • 安装、初始设置和第一个Worker相关指导，请使用
    iii-getting-started

When to Use

使用场景

  • Use this skill when the task is about installing iii, creating a new project, or writing a first worker.
  • Triggers when the request asks for setup help, quickstart guidance, or getting started with iii.
  • 当任务涉及安装iii、创建新项目或编写第一个Worker时，使用此技能。
  • 当请求需要设置帮助、快速入门指南或iii入门指导时触发。

Boundaries

使用限制

  • Never use this skill as a generic fallback for unrelated tasks.
  • You must not apply this skill when a more specific iii skill is a better fit.
  • Always verify environment and safety constraints before applying examples from this skill.
  • 切勿将此技能作为无关任务的通用 fallback。
  • 当有更合适的特定iii技能时，不得使用此技能。
  • 在应用此技能中的示例之前，务必验证环境和安全约束。