iii-hq /iii
Effortlessly compose, extend, observe, discover, and react to every service in real-time for the first time ever.
★ 18,933⑂ 1,273👁 83⑃ 2,150● 375▤ 401
-2
日增长
+37
周增长
+94
月增长
18,933
stars
1,273
forks
83
watchers
2,150
prs
375
issues
401
releases
README
iii
本文件是 README.md 的简体中文翻译。为方便同步,正文中的代码、命令、专有名词(Worker、Function、Observer、Compose、SDK 等)保持原文。
!iii: 从点对点集成到基于共享运行时的零集成
什么是 iii? ·
安装 iii ·
添加 Worker ·
SDK ·
Agent Skills ·
资源
什么是 iii?
iii 是在实时场景中组合(compose)、观测(observe)、发现(discover)、扩展(extend)并响应(react)你技术栈中每一个服务的最简单方式,即 CODER。
每一个后端在写下第一行业务逻辑之前,都始于一个项目。队列、定时任务(cron)、HTTP、状态管理、可观测性、agent、沙箱(sandbox),往往各自都带来一套需要单独打通的集成方案,让 CODER 变得复杂。iii 用一个实时的系统界面(live system surface)统一解决了所有这些关注点。
bash
iii compose --namespace dev --up
iii call -n dev compose::add worker=queue
iii call -n dev compose::add worker=agent
iii call -n dev compose::add worker=
每个 Worker 都会加入实时目录(live catalog)。其他所有 Worker 会立即收到通知并可以直接调用它。可在 workers.iii.dev 浏览可用的 Worker。
这也是关于 agent 的故事:当某个任务需要系统尚不具备的能力时,agent 可以添加一个 Worker、发现它的函数、调用它们,并追踪发生了什么。开发者与 agent 使用的是同一套接口。
三大原语
iii 由 3 个原语驱动:
Workers 是连接到 iii 引擎并注册 Functions 的进程。一个 TypeScript API 服务是一个 Worker,一个 Python 数据管道是一个 Worker,一个 Rust 微服务也是一个 Worker。只需几行代码,任何功能都可以被改造为一个 Worker。Compose 还能在运行时添加 Worker,因此 agent 和应用可以在系统运行的过程中对其扩展。
Functions 是具有稳定标识符的工作单元(例如 content::classify、orders::validate)。Function 接收输入、执行工作,并可选择性地返回输出。Functions 存在于 Worker 之中,任何 Worker 都可以用 iii.call() 调用任何 Function,无论它运行在哪里。
Observers 让系统具备响应能力。iii.observe('orders::create', 'alerts::big-order') 的含义是:当 orders::create 运行时,alerts::big-order 随之运行。每一个 Function 都可以被观测(observe),包括 Worker 为事件提供的 Function:一个 HTTP 请求是对 http::on-request 的一次调用,cron 的一次 tick 是对 cron::on-tick 的一次调用,一条队列消息是对 queue::on-message 的一次调用。iii 负责路由、序列化和投递。
通过将服务所能做的一切映射到这三个原语,iii 打造出一个既毫不费力地可组合、又完全可观测的开发流程。
带来什么改变
在使用 iii 之前:
- 新的可观测性工具:数不尽的集成工作
- 新的 agent harness:单独的重试配置、单独的链路追踪、单独的超时
- 新的队列:厂商评估、采购,以及数周的集成
在使用 iii 之后:
- 在 worker-compose.yaml 中声明 Worker
- 用 iii compose --up 运行它们
- 完成。它已进入系统,可被追踪、可被调用。
平台团队发布 Worker,应用团队注册函数并观测(observe)它们要响应的函数,agent 使用同一份目录、同一套函数调用。
扩展 iii 就是添加一个 Compose Worker;编排 iii 就是调用函数;观测 iii 就是打开那条链路追踪(trace)。
安装 iii
安装 iii:
bash
curl -fsSL https://install.iii.dev/iii/main/install.sh | sh
添加 Worker
在 worker-compose.yaml 中声明项目的 Worker,或通过一个正在运行的 Compose 守护进程添加它们:
bash
iii call -n dev compose::add worker=queue
在 workers.iii.dev 浏览软件包,并查阅
Compose 文档。
SDK
| 语言 | 软件包 | 安装 |
| -------- | -------------------------------------------------- | ------------------------------------------- |
| Node.js | iii-sdk | pnpm add iii-sdk 或 npm install iii-sdk |
| Python | iii-sdk | pip install iii-sdk |
| Rust | iii-sdk | 添加到 Cargo.toml |
| Go | iii-sdk | go get github.com/iii-hq/iii/sdk/packages/go/iii |
面向第三方 harness 的 Agent Skills
如果你使用的是 iii harness,那么 agent skills 会自动可用。
如果你使用的是其他 harness,可以通过以下方式安装 iii 的 skills:
bash
npx skills add iii-hq/iii/skills
这些 skills 覆盖了 iii 的每一个原语:HTTP 端点、队列、cron、状态、流、Observer、可观测函数(observable function)等等。完整列表见 skills/。
iii-hq/workers 中的每个 Worker 也自带各自的 skill。可与 Worker 一起安装:
bash
npx skills add iii-hq/workers --list 列出可用Top issues
#1553iii native Windows installation8 comments · 2026-04-28#2201provider-llamacpp: context window falls back to 4096 on non-llama.cpp OpenAI-compatible servers (SGLang/vLLM) every turn fails with context/overflow5 comments · 2026-09-18#1095Feature: Jump to Trace from Log Details5 comments · 2025-12-19#811Deduplication/Debounce features5 comments · 2025-10-12#1814Support enqueue with custom priority4 comments · 2026-06-09#1723iii worker add mcp fails with missing skills dependency, but config.yaml starts it successfully4 comments · 2026-05-31#2084HTTP trigger disappears after duplicate worker registration is rejected3 comments · 2026-08-25#1744Feature Request: Export Conversation as JSON3 comments · 2026-06-03
Discussions
#2312HA and zero-downtime deployments: roadmap for engine redundancy and worker replicas?3 comments · 2026-10-08#1738Feature Request: Worker isolation / access control between workers1 comments · 2026-06-02#1730iii worker add --force does not invalidate dependency cache when project dependencies change (ex. pyproject.toml, Cargo.lock)3 comments · 2026-05-31#1728`iii worker add` attempts to pull local Docker image from registry2 comments · 2026-05-30#1135Dependency Injection1 comments · 2026-01-15#1134API for create cron scheduling job0 comments · 2026-01-14#1041Low Test Coverage - Blocking Production Adoption0 comments · 2025-12-10#1030Paths0 comments · 2025-12-08
Latest release
iii 0.26.0 iii/v0.26.0 2026-11-09What's Changed docs(changelog): complete 0.25.0 release notes by @guibeira in https://github.com/iii-hq/iii/pull/2383 test(rust): give the oversized result_wire case a 30s budget by @guibeira in https://github.com/iii-hq/iii/pull/2386 fix(python): require websockets=14.0 by @guibeira in https://github.com/iii-hq/iii/pull/2385 fix(deps): update Tokio to address RUSTSEC-2026-0386 by @guibeira in https://github.com/iii-hq/iii/pull/2391 fix(sdk): patch happy-dom and zod security advisories by @guibeira in https://github.com/iii-hq/iii/pull/2400 docs: move Upgrading group to bottom of sidebar