# How to build your own agent harness??? # 如何构建你自己的智能体运行基座？？？ Most agent teams don't build a harness. They adopt one. LangChain, LangGraph, OpenAI Agents SDK, Anthropic SDK, CrewAI, AutoGen, the loop, the tools, the memory, and the orchestration are picked off the shelf as a single decision. The harness is a framework you import. If something inside it doesn't fit, you fork it, fight it, or work around it. 大多数智能体团队并不自己构建运行基座（Harness），而是直接采用现成的。比如 LangChain、LangGraph、OpenAI Agents SDK、Anthropic SDK、CrewAI、AutoGen，无论是循环、工具、记忆还是编排，都在一次技术选型中被打包“拿来主义”了。基座成了你导入的一个框架。如果里面有不符合需求的地方，你要么分叉（fork）它的代码，要么和它死磕，要么想尽办法去绕过它。 ![](https://pbs.twimg.com/media/HJa7xHCWEAQZ9aX.jpg) I think that shape is wrong, and it's the reason every long-running agent team eventually ends up rewriting its harness from scratch. The harness isn't one thing. It's ten or twelve different things bundled together because the surrounding ecosystem doesn't give you a way to compose them. [Pi agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) packages are on the right track, but they are still in the paradigm of “Add another service and integrate it with all others.” The iii engine treats all workers the same and removes the integration logic completely. The provider router, the credential vault, the policy engine, the approval gate, the model catalog, the session storage, the budget tracker, the after-call hook fanout, and the durable turn loop are independent concerns. These are all interoperable with your queue, http/api server, streaming, even browser workers. A framework that ships them as one block is selling you a tradeoff you didn't have to make. 我认为这种形态是错误的，这也正是为什么每一个长期运营的智能体团队，最终都会从头重写他们自己的运行基座。基座不应该是一个单一的整体，它其实是十来个不同的组件强行捆绑在一起的产物，因为现有的生态系统没有给你提供自由组合它们的方式。[Pi agent](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) 在这条路上走对了方向，但它们仍然处于“添加另一个服务并将其与其他所有服务集成”的旧范式中。iii 引擎则将所有工作节点（Worker）一视同仁，完全去除了复杂的集成逻辑。模型提供商路由、凭据保险库、策略引擎、审批网关、模型目录、会话存储、预算追踪器、调用后的钩子扇出（Hook Fanout）以及持久化的轮次循环（Turn Loop），这些都是独立的关注点。它们完全可以与你的队列、HTTP/API 服务器、流媒体，甚至浏览器中的工作节点进行互操作。把它们作为铁板一块打包提供给你的框架，是在强迫你接受原本不必做的妥协。 The bet underneath [iii](https://iii.dev/) is that they shouldn't be one block. There should be a set of workers on a shared engine, each replaceable, each versioned independently, each connected by a single primitive: a trigger (iii.trigger()) that every other worker also uses. The harness becomes a stack of installable workers, and "build your own" stops meaning "fork a framework." It means "swap a few workers." [iii](https://iii.dev/) 背后的核心理念是：基座本就不该是铁板一块。它应该是一组运行在共享引擎上的工作节点（Worker），每个节点都可替换，独立控制版本，并通过一个极其简单的原语连接在一起：也就是所有其他节点都在使用的触发器（`iii.trigger()`）。如此一来，基座就变成了一个可以通过安装节点来组装的技术栈，“构建你自己的基座”不再意味着“分叉一个庞大的框架”，而是变成了“替换几个工作节点”。 This post walks through what that actually looks like. The complete stack that drives an iii agent turn today, why each layer is its own worker, and how you replace any of them. 本文将带你一探这套理念在实际中的运作形态。包括今天驱动一个 iii 智能体交互轮次（Turn）的完整技术栈，为什么每一层都能作为独立的工作节点，以及你该如何随意替换其中的任何一层。 ### The 15 jobs an agent harness has to do ### 智能体运行基座必须完成的 15 项任务 If you strip a production agent harness back to its responsibilities, you get a list that looks roughly like this: 如果你剥开一个生产级别的智能体基座的外衣，回归其最基本的职责，你会得到一个大致如下的任务清单： - Accept a turn request from a client and persist it 接收来自客户端的轮次（Turn）请求并将其持久化 - Resolve credentials for whichever model provider gets called 为即将调用的任意模型提供商解析身份凭据 - Look up what the chosen model can actually do (vision, tools, streaming, context window) 查询所选模型实际具备的能力（如视觉、工具调用、流式输出、上下文窗口大小） - Drive the per-turn state machine, provision, stream assistant, run tools, steer, tear down 驱动单轮交互的状态机：从分配资源、流式输出助手回复、运行工具、引导走向，直到拆卸回收 - Load and serve skill bodies that describe each function's request shape, error codes, and usage notes 加载并提供技能体（Skill bodies），描述每个工具函数的请求格式、错误代码及使用说明 - Assemble the system prompt, mode paragraph, identity preamble, working directory, and default skills appendix 组装系统提示词（System prompt），包括模式段落、身份预设前言、工作目录以及默认的技能附录 - Stream tokens back to the client as the model produces them 当模型生成内容时，将 Token 实时流式传输回客户端 - Check every tool call (that’s just a function) against a policy before it runs 在运行之前，根据策略规则校验每一次工具调用（本质上就是个函数） - Pause tool calls that need a human decision and route the answer back to the right turn 挂起需要人工干预决策的工具调用，并在决策后将结果精准路由回对应的交互轮次 - Track LLM spend against per-workspace or per-agent budgets 根据每个工作空间或每个智能体设定的预算，追踪 LLM 的成本消耗 - Run hooks before and after tool calls (logging, redaction, custom side effects) 在工具调用前后触发钩子函数（Hook，如日志记录、数据脱敏、自定义的副作用操作） - Persist the session as a branching tree so forks and resumes work 将会话持久化记录为树状分支，以完美支持分支（Forks）与恢复（Resumes）工作流 - Compact session history when the context window fills up 当上下文窗口即将满载时，对会话历史进行压缩 - Emit an event stream that the UI subscribes to 发出 UI 订阅所需的事件流 - Missing piece from every agent's company building, I see. Carry one OpenTelemetry trace across every step so you can debug it 我发现几乎所有智能体公司在基建时都会遗漏的一环：在整个流程的每一个步骤中，携带一条完整的 OpenTelemetry 链路追踪（Trace）数据，以便于调试排错 Every serious agent harnesses most of these. The expensive ones do all of them. The cheap ones cut corners and rebuild the corners later when they hit production. The frameworks bundle them into a monolith and ship one version of each. That last part is the part that costs you, because a year in, you find out that the policy engine you want is not the policy engine the framework ships, and replacing it means replacing the harness. 每一个严肃的智能体框架都需要搞定其中的大部分任务。昂贵的商业方案会把它们全包了。简陋的开源方案则会先偷工减料，等企业将其推向生产环境痛点爆发时，再让开发者自己打补丁去重建。传统的框架会把这 15 项能力死死捆绑成一个庞然大物，并提供固定的单一版本。最后这一点恰恰是让你付出惨痛代价的地方：因为一年后你会发现，框架自带的策略引擎根本满足不了你的定制需求，而想要替换掉它，就意味着你要推翻并替换掉整个基座。 The iii harness ships every one of those thirteen jobs as a separate worker on the [workers.iii.dev](https://workers.iii.dev/) registry. Each speaks the same WebSocket protocol. Each registers functions and triggers on the same engine bus. Each is iii worker add-able, swappable, and writable in any language with an SDK. iii 的运行基座将上述各项任务（*注：原文称 thirteen 但上方列了 15 条*）拆解成了独立的 Worker，并发布在 [workers.iii.dev](https://workers.iii.dev/) 注册中心。每个 Worker 都讲相同的 WebSocket 协议。每个 Worker 都在同一个引擎总线（Engine Bus）上注册函数与触发器。它们全都可以通过 `iii worker add` 灵活添加或替换，且支持用任何提供了 SDK 的编程语言来编写。 ### The stack, by worker ### 技术栈的 Worker 划分 Here is the actual production stack from the [iii-hq/workers](https://github.com/iii-hq/workers/tree/main/harness) monorepo, with each worker's job in one line. The whole bundle ships at [github.com/iii-hq/workers/harness](https://github.com/iii-hq/workers/tree/main/harness): 以下是来自 [iii-hq/workers](https://github.com/iii-hq/workers/tree/main/harness) 单体仓库（Monorepo）中的真实生产级技术栈，每一行都代表一个 Worker 及其负责的任务。整个捆绑包发布于 [github.com/iii-hq/workers/harness](https://github.com/iii-hq/workers/tree/main/harness)： ![](https://pbs.twimg.com/media/HJauEXNXoAQ1dNA.jpg) Eleven workers. One engine. Each is on a published version. Each is independently runnable as a standalone process (pnpm dev: in dev, iii worker add as a release binary) or as part of the composite entry point that spins them up together. 十一款 Worker。一个引擎。它们分别都有公开发布的版本。不仅每一个都能作为独立进程单独运行（开发环境下用 `pnpm dev:`，作为发布环境的二进制文件用 `iii worker add `），它们也可以在复合入口点被一键组合拉起。 The reason this matters: every box in that table is a place where someone can hand you a different worker, and you keep the rest. Don't like the static model catalogue? Plug in a worker that registers models::list and reads from a live API. Don't like file-backed credentials? Plug in a worker that registers auth::get_token and reads from a secrets manager. Want a different turn FSM for a workflow that branches differently? Replace turn-orchestrator, every dependent calls run::start and reads turn_state through the same bus, so the rest of the stack doesn't change. 这之所以意义重大，是因为上表中的每一个模块，你都能随时换上另一个不同的 Worker，而完美保留系统的其余部分。不喜欢静态的模型目录？没问题，插入一个注册了 `models::list` 并从实时 API 读取数据的 Worker 即可。不喜欢存在文件里的凭据库？换成一个注册了 `auth::get_token` 并直连你公司密钥管理器的 Worker。针对不同分支形态的工作流，想要一个不同的轮次状态机（Turn FSM）？直接替换掉 `turn-orchestrator`，所有依赖项依旧可以通过同一条总线调用 `run::start` 并读取 `turn_state`，因此你整个技术栈的其余部分完全不需要修改！ ### How the loop actually runs ### 循环运行的实际机制 The shape of one turn looks like this, walking through the workers in the order they fire. 单轮交互（Turn）的整体形态如下，我们将按触发的先后顺序，带你遍历所有的 Worker。 A browser/cli/chat POSTs a turn through harness::trigger with {session_id, message_id, payload}. The harness meta-worker forwards payload to run::start. That hop exists so the OpenTelemetry span wrapper can seed the session and message IDs as baggage, which propagates to every nested iii.trigger call across every worker in the stack. The trace tree on the other side is one connected graph. 浏览器/命令行工具/聊天窗口通过发送包含 `{session_id, message_id, payload}` 的 POST 请求至 `harness::trigger`。此时，基座的元节点（Meta-worker）将 `payload` 转发给 `run::start`。保留这一跳转步骤的用意在于：让 OpenTelemetry 跨度（Span）的包装器能将会话 ID 和消息 ID 作为上下文包袱（Baggage）“播种”下去。这样，它们就能自动传播到穿透所有 Worker 栈的每一个嵌套的 `iii.trigger` 调用中去。由此一来，最终生成的分布式链路追踪树（Trace tree）将是一张完美的无缝连通图。 run::start lands on the turn-orchestrator. It persists the run request, seeds the initial TurnStateRecord in iii state at session//turn_state, and returns immediately. The actual work happens inside the durable per-state machine, woken by publishes to the turn-step FIFO. `run::start` 的请求落地在 `turn-orchestrator` 上。它会立即持久化该运行请求，在 iii 的状态管理中向 `session//turn_state` 写入初始的 `TurnStateRecord`，然后立即返回。所有幕后的繁重工作，其实都发生在那个持久化的、按状态划分的状态机里，并由发布到 `turn-step` FIFO 队列的消息来依次唤醒。 The two terminal states are stopped (clean exit via finishSession()) and failed (an unexpected handler throw routes here, acks the queue so it stops retrying, and surfaces message_complete{stop_reason:'error'} plus agent_end so the UI shows the reason). Teardown is an inline finishSession() port called from any turn-end path, not a separate enqueued step. 状态机拥有两个终止状态：**stopped**（通过 `finishSession()` 干净利落地退出）和 **failed**（如果有未预期的代码报错被抛出并路由至此，它会向队列发送 ACK 确认，以防止无限重试，同时向上层抛出附带 `stop_reason:'error'` 的 `message_complete` 和 `agent_end` 事件，让前端 UI 能向用户展示报错原因）。资源拆卸（Teardown）并不是一个单独入队排队的步骤，而是一个内联的 `finishSession()` 端口调用，可以从任意轮次结束的路径中被安全触发。 provisioning does three things. It boots a [iii-sandbox](https://github.com/iii-hq/iii/tree/main/crates/iii-worker/src/sandbox_daemon) microVM if the run needs isolated execution. It calls directory::skills::download for every namespace in system_default_skills (default ["iii://iii-directory/index"]) so iii-directory pre-caches the skill bodies the run starts with. And it assembles the system prompt in three layers: a mode paragraph picked from run_request.mode (plan, ask, or agent), the iii identity preamble that teaches the model the agent_trigger convention and the directory::skills::get on-demand discovery pattern, and an appended index of the default skills the agent boots with. The caller can override the whole prompt by passing system_prompt on run::start; otherwise the orchestrator builds it. Function schemas come from the live engine catalog. 资源分配（Provisioning）节点主要做三件事。第一，如果本次运行需要隔离执行环境，它会启动一个 [iii-sandbox](https://github.com/iii-hq/iii/tree/main/crates/iii-worker/src/sandbox_daemon) 微型虚拟机。第二，它会为 `system_default_skills`（默认值是 `["iii://iii-directory/index"]`）中的所有命名空间调用 `directory::skills::download`，让 `iii-directory` 预先缓存好智能体启动时需要的技能体文件。第三，它会将系统提示词（System prompt）进行三层组装：包括根据 `run_request.mode`（比如规划、询问或智能体模式）选取的模式段落；负责教会大模型遵循 `agent_trigger` 约定及 `directory::skills::get` 按需发现机制的 iii 身份预设前言；以及智能体启动时附带的默认技能索引。当然，如果在调用 `run::start` 时调用方直接传了 `system_prompt` 参数，它就能覆盖整个默认提示词组装过程。所有函数的 Schema（结构定义）始终来自于实时的引擎目录。 assistant_streaming calls provider::::stream on whichever provider worker matches the run's provider field. The provider worker pulls credentials via auth::get_token (auth-credentials), streams the model's SSE response into an iii channel, and the orchestrator drains that channel emitting message_update events on agent::events for the UI fanout. Channel creation and the read loop live behind a pull-based MessagePump in provider-stream.ts, so the streaming state stays focused on transitions. 助手的流式输出节点（`assistant_streaming`）会根据运行配置中的 provider 字段，调用匹配的提供商 Worker 的 `provider::::stream` 方法。提供商 Worker 则会经由 `auth::get_token` 找凭据 Worker（auth-credentials）拉取调用密钥，然后将模型返回的 SSE 响应流式推入到 iii 的数据通道（Channel）中。接着，编排器会不断排空这个通道，在 `agent::events` 事件线上发出 `message_update` 事件，从而向前端 UI 扇出（Fanout）实时打字效果。通道的创建与读取循环被隐藏在 `provider-stream.ts` 里基于拉取（Pull-based）的 `MessagePump` 之后，确保了流式处理逻辑纯粹聚焦于状态转换。 When the assistant returns tool calls, the FSM enters function_execute. Every tool call passes through dispatchWithHook, the single chokepoint in the orchestrator. consultBefore calls policy::check_permissions directly with a 5-second timeout. The policy worker (the harness meta-worker, in the default stack) reads iii-permissions.yaml, matches the call's function_id against the rule set, and returns one of three outcomes: 当助手模型决定返回工具调用（Tool calls）时，状态机会随之进入 `function_execute` 状态。每一次工具调用都会经过 `dispatchWithHook`——这是编排器中唯一的“咽喉”检查点（Chokepoint）。它会通过 `consultBefore` 带着 5 秒的超时设置去直接调用 `policy::check_permissions`。在默认栈下，策略 Worker（即基座元节点）会读取 `iii-permissions.yaml` 配置文件，将要调用的 `function_id` 与规则集匹配，并返回以下三种结果之一： - allow: dispatch proceeds; the orchestrator triggers the target function and writes the result **允许（allow）**：正常放行；编排器触发目标函数，然后记录执行结果。 - deny: dispatch short-circuits with a DenialEnvelope, the result becomes a denial record **拒绝（deny）**：直接拦截并返回一个“拒绝封套（DenialEnvelope）”，该次调用的结果将变成一条被拒绝访问的记录。 - needs_approval: the individual call parks into the turn's awaiting_approval list. The rest of the batch keeps dispatching. The turn transitions to function_awaiting_approval only when one or more entries are pending. **需要审批（needs_approval）**：单个工具调用会被挂起，并停留在本轮交互的 `awaiting_approval` 列表中。同一批次中的其他正常调用则继续分发执行。仅当列表中有一个或多个任务处于待处理状态时，这一轮交互的状态才会变更为 `function_awaiting_approval`。 The approval wake is reactive and shared. The orchestrator registers exactly one turn::on_approval state trigger on scope approvals. When the console calls approval::resolve, the approval-gate worker writes approvals// = {decision, reason} to iii state. That write fires turn::on_approval, which advances the affected session. function_awaiting_approval reads only the decisions that just landed, dispatches each one as it arrives (allow becomes a pre-approved dispatch, deny or aborted becomes a synthetic denial), and advances when awaiting_approval[] is empty. No per-call resume functions to register. No startup re-scan to recover pending approvals. One trigger covers every session. 审批唤醒机制完全是响应式的，且是跨实例共享的。编排器仅需要在全局层级注册仅仅一个 `turn::on_approval` 状态触发器。当管理控制台下发 `approval::resolve` 调用时，网关 Worker（`approval-gate`）就会向 iii 的状态机里写入 `approvals// = {decision, reason}`。这笔写入操作会瞬间激活 `turn::on_approval` 触发器，从而推动受影响的会话继续往下走。`function_awaiting_approval` 状态只读取刚刚落地的最新决策，来一个处理一个（允许了就当作预审批的分发任务放行，拒绝或中止了就直接合成一条被拒记录），等到 `awaiting_approval[]` 数组变空时，流程自然继续推进。完全不需要为每一次函数调用注册什么专属的“恢复函数（Resume functions）”。也不需要在系统重启时去重新扫描数据库捞取待处理的审批件。区区一个触发器，就优雅地覆盖了全天下所有的会话。 Fail-closed by construction: if the policy worker is unreachable or the 5-second timeout fires, consultBefore denies the call with a gate_unavailable envelope. If iii::durable::publish itself errored, the hook fanout returns publish_failed: true and the orchestrator treats it as a deny. 设计上默认拒绝（Fail-closed by construction）：如果策略 Worker 挂了连不上，或者等待了 5 秒触发超时，`consultBefore` 将非常干脆地用一个 `gate_unavailable` 封套来拒绝该次工具调用。如果底层持久化的 `iii::durable::publish` 抛出了错误，钩子扇出就会返回 `publish_failed: true`，此时编排器同样会将其视为调用被拒绝，从而守住安全底线。 A few latency wins fall out of this shape. The after-function-call hook short-circuits publish_collect via a subscriber-presence cache when no durable subscriber is registered for the topic, removing roughly 500ms per executed function call. tearing_down is inlined into finishSession(), removing one durable queue hop per turn. context-compaction subscribes to a dedicated agent::turn_end stream the orchestrator emits at turn boundaries, so compactor wakeups are per-turn instead of per-event. The session-create fanout state trigger gates by scope alone and matches in-process, so the previous per-write harness::session::is_create_event RPC is gone. 这套架构自然而然地带来了一系列延迟上的红利。例如函数调用后的钩子，如果某主题没有注册对应的持久化订阅者，它会利用“订阅者在场缓存”直接短路跳过 `publish_collect` 操作，这就为每次执行的函数调用生生抠出了大约 500 毫秒的时间。`tearing_down` 清理阶段直接内联合并到了 `finishSession()` 中，每轮次减少了一次访问持久化队列的网络开销。上下文压缩器（`context-compaction`）直接订阅编排器在轮次边界发出的专属 `agent::turn_end` 流，因此压缩器只会“按轮次（per-turn）”而不是“按事件（per-event）”被唤醒。触发“会话创建”扇出的状态触发器如今完全靠作用域来做门控，并在进程内直接匹配，原先每一次写操作都要进行的 `harness::session::is_create_event` RPC 调用也就被彻底省掉了。 After the batch completes, steering_check decides whether to continue, stop, or hit max_turns. If continue, loop back to assistant_streaming. If stop or max, finishSession() runs inline: emit agent_end, free the sandbox, transition to stopped. 当一批次的工具调用全部完成后，走向检查（`steering_check`）负责拍板接下来是继续（Continue）、停止（Stop）还是已经触发了最大轮次限制（max_turns）。如果是继续，循环就重回 `assistant_streaming` 状态。如果是停止或达上限，`finishSession()` 就会内联执行：抛出 `agent_end` 事件，释放微型沙箱实例，将最终状态转入 stopped。 Throughout the whole run, every worker that participates emits OTel spans tagged with iii.session.id, iii.message.id, and iii.function.id. Those tags are what the engine's engine::traces::group_by reads to populate "Group by Session" / "Group by Message" / "Group by Function" in the traces UI. The instrumentation is automatic: src/runtime/worker.ts wraps every registerFunction in a Proxy so no per-worker code has to remember to add spans. 在贯穿整个运行周期的过程中，只要参与了干活的 Worker 都会发出附带了 `iii.session.id`、`iii.message.id` 和 `iii.function.id` 标签的 OpenTelemetry 跨度信息（OTel spans）。正是基于这些标签，引擎的 `engine::traces::group_by` 接口才能读取它们，进而在链路追踪界面的 UI 上呈现出完美丝滑的“按会话分组”、“按消息分组”或者“按函数分组”视图。而且，这套埋点是完全自动生成的：在底层的 `src/runtime/worker.ts` 中，系统会通过 Proxy 将每一个 `registerFunction` 包装起来，因此你在手写 Worker 业务代码时，根本无需痛苦地去记着给各个地方加 Span。 ### Build your own ### 构建你自己的系统 The interesting part is that none of the workers above are special. Each one is a process that opens a WebSocket to the engine, registers some functions and triggers, and runs. The contract is the same as the contract every application worker uses. The harness is built on the same primitive your business logic is built on. 最有趣的地方在于，上面提到的这些 Worker 压根没有任何特殊特权。它们中的每一个，都只是一个普通的进程——向引擎打开一个 WebSocket 连接，注册好一些函数和触发器，然后安安静静地跑。它们所遵循的契约，和你自己写的业务 Worker 用的契约是一模一样的。也就是说，这个伟大的框架基座，完全是建立在构建你普通业务逻辑相同的原语之上的。 Which means "build your own harness" decomposes into the same operation as "write any worker." You pick the layer you want to replace, you write a worker that registers the same functions on the bus, you iii worker add it, and the rest of the stack starts using your worker. 这意味着，“构建你自己专属的运行基座”这件事，被降维拆解成了和“写一个最普通的 Worker”毫无二致的操作。你看中想替换哪一层，你就写一个能在总线上注册对应函数的 Worker，然后通过 `iii worker add` 把它加进去，整个系统剩下的部分就会丝滑地开始调用你的这名“新员工”。 Two layers don't show up in the worker table above but matter for how the harness behaves. Skills are how each worker advertises what its functions do. Every worker can publish a skill at iii:/// that the agent fetches via directory::skills::get before calling that function for the first time. The system prompt is assembled per turn from a mode paragraph, the iii identity preamble, and the default skill bodies the run was configured with. Both are bus-driven: skills are served by the iii-directory worker, the system prompt is assembled by the turn-orchestrator. Both are replaceable. 前面的 Worker 列表里有两层隐形的关键角色没写出来，但它们对基座的表现至关重要。第一层是“技能（Skills）”，即每个 Worker 宣告自己函数能干啥的机制。每个 Worker 都能在 `iii:///` 上发布一份技能清单，智能体在首次调用某函数前，会老老实实通过 `directory::skills::get` 去拉取它。第二层是“系统提示词（System prompt）”，它是由模式段落、iii 身份预设前言以及配置的默认技能内容，在每一次交互中即时组装而成的。这两者同样全都是总线驱动的：技能由 `iii-directory` Worker 伺服提供，而系统提示词则由 `turn-orchestrator` 负责组装。当然，这两者同样也全都是可替换的。 Five concrete examples. 这里给你举五个具象化的例子。 Replace the model catalogue with a live API. Write a worker that registers models::list, models::get, models::supports. Have it fetch from your provider's catalog endpoint every N minutes and cache. Publish it. iii worker add your-org/dynamic-models-catalog. Stop the static models-catalog worker. The turn-orchestrator never knows the difference. It calls iii.trigger('models::list') and the engine routes to whichever worker registered that function id most recently. **将模型目录替换为实时 API：** 写一个注册了 `models::list`、`models::get` 和 `models::supports` 的 Worker。让它每隔几分钟就去你们家大模型供应商的 API 接口拉取最新目录并做好缓存。发布出去。通过 `iii worker add your-org/dynamic-models-catalog` 添加它，并关掉原来那个静态加载列表的 Worker。编排器 `turn-orchestrator` 压根就不会发现有什么不同，它照常调用 `iii.trigger('models::list')`，而引擎则会聪明地将请求路由给最近注册了这个函数 ID 的 Worker。 Add a new provider. The shape is provider-kimi and provider-lmstudio already prove out. Each is one worker that registers provider::::stream and provider::::complete, drains an SSE stream from the upstream API into an iii channel, and writes its model usage to llm-budget via budget::record. Adding a fifth provider is writing one folder with one iii.worker.yaml and one register.ts. Publish to the registry, or keep it local. The turn-orchestrator picks the provider by the run's provider field; new providers become available the instant the worker connects. **新增一个模型提供商（Provider）：** 我们目前针对 kimi 和 lmstudio 做的 Worker 就是最好的模板。每一个提供商都是一个注册了 `provider::::stream` 和 `provider::::complete` 的独立 Worker，它们负责接管来自上游 API 的 SSE 流推入 iii 通道，顺手再通过 `budget::record` 把 Token 消耗量记到预算管理节点上。你想添加自家的第五个模型提供商？那就建一个文件夹，扔进一个 `iii.worker.yaml` 加上一个 `register.ts` 搞定！发布到公共库或者留作私有本地使用都行。编排器只看配置里给的 provider 字段去选人；只要你的新 Worker 连上线，新模型立刻全员可用。 Serve skills from a private artifact store. Write a worker that registers directory::skills::get and directory::skills::list, backed by your internal docs system or a private S3 bucket. Disconnect or rename the default iii-directory worker. The orchestrator's bootstrap calls directory::skills::download per namespace; your worker answers. The agent's "fetch the per-function skill before calling a new function" pattern keeps working unchanged because the wire shape is the same. **从私有制品库提供技能（Skills）内容：** 写一个注册了 `directory::skills::get` 和 `directory::skills::list` 的 Worker，并在背后对接你们公司内部的文档系统或私有 S3 存储桶。停掉或重命名默认的 `iii-directory` Worker。由于编排器的引导程序在面对每个命名空间时还是照常调用 `directory::skills::download`，这次轮到你的私有 Worker 来作答了。智能体那种“在调新函数前先读说明书”的行为逻辑丝毫未变，因为底层的网络传输形态完全没变。 Override the system prompt entirely. run::start accepts an optional system_prompt field. Pass it and the orchestrator uses your string verbatim, skipping the mode paragraph + identity preamble + skills appendix assembly. Useful when you have an existing prompt asset you want the harness to honour without modification. Skill download still runs in bootstrap, so the agent keeps directory::skills::get on-demand discovery even with a custom prompt. **完全覆盖接管系统提示词：** `run::start` 原生接受一个可选的 `system_prompt` 参数字段。只要你传了，编排器就会乖乖地逐字使用你传来的字符串，无视掉它原有的“模式段落+身份预设+技能附录”组装逻辑。当你手里早有一套视若珍宝的提示词资产，并希望框架一字不落地尊重执行时，这招极度好用。而且技能下载这一步依然会在引导阶段照常运行，所以即便你在用定制的提示词，智能体依旧保有通过 `directory::skills::get` 去按需发现新工具的能力。 Replace the approval gate UI surface. The default approval-gate worker registers approval::resolve. The wire schema is one function call: **大换血审批网关的用户交互界面：** 默认的审批 Worker（`approval-gate`）注册了 `approval::resolve`。其网络层架构模式简单到只是下面这一个纯粹的函数调用： ````typescript iii.trigger('approval::resolve', { session_id: '...', function_call_id: '...', decision: 'allow' | 'deny' | 'aborted', reason: 'optional human text', }) ```` The handler persists approvals// = {decision, reason} to iii state. The orchestrator's single turn::on_approval state trigger picks that write up and wakes the right session. If you want to drive approvals from Slack instead of the console, write a Slack worker that listens for /approve and /deny slash commands, then calls approval::resolve with the right payload. The orchestrator never knows the difference. The whole approval-gate worker stays untouched. You added a new worker; you didn't replace the existing one. 处理器接收请求后，将 `approvals// = {decision, reason}` 持久化写进 iii 的状态库中。接着编排器那个孤零零的 `turn::on_approval` 状态触发器嗅探到了写入，便会自动唤醒正苦苦等待的对应会话。如果你嫌默认的网页控制台太土，想在 Slack 企微钉钉里点按钮审批？太简单了！写一个专属于你的 Slack Worker，监听 `/approve ` 或 `/deny ` 指令，然后带着正确的负载去触发上面的 `approval::resolve`。在编排器眼里，它压根不知道屏幕背后是一条 Slack 消息。甚至你连原有的 `approval-gate` Worker 都不用去动。你这叫锦上添花加了新兵，而不是开除老将。 If you want a different policy engine (OPA, Cedar, your own DSL), write a worker that registers policy::check_permissions and returns { decision, rule_id?, matched_constraint? }. Disconnect the default policy worker (which is wrapped inside the harness meta-worker, so you'd disable that handler or run a stripped-down meta-worker). The turn-orchestrator's consultBefore doesn't know the difference. Same 5-second timeout, same fail-closed semantics, same wire shape. **如果你受不鸟默认的策略引擎**，非要上 OPA、Cedar 或者你们自研的牛气 DSL，写个 Worker 注册上 `policy::check_permissions`，并返回诸如 `{ decision, rule_id?, matched_constraint? }` 的结果即可。拔掉原来默认策略 Worker 的网线（因为它默认封死在基座元节点内，你可以选择关掉这个处理句柄，或者跑个阉割版的基座元节点）。再次重申，编排器的 `consultBefore` 还是跟个瞎子一样毫无察觉。依旧是那个严苛的 5 秒超时，依旧是那个固若金汤的默认拒绝（Fail-closed）语义，一切照旧。 The point of these examples isn't the specific replacements. It's the shape of the operation. Every harness layer in the iii stack is reachable through one or two function ids on the bus. Replacing a layer is writing a worker that registers those ids. The rest of the system stays. 举这些例子的真正用意，绝不在于让你死记硬背去替换这几个特定对象。我想要展示的是这种操作模式无与伦比的“形态美”。在 iii 这套堆栈里，基座架构的每一层，统统暴露成了总线上的那一两个函数 ID 而已。所谓的“替换架构”，翻译过来就是写个占坑新 Worker 注册掉那个 ID 这么简单。至于整个庞大系统的其余部分，它们还是它们。 ### The harness is a slider, not a fork in the road ### 基座是一个滑动条，而不是一个岔路口 The classic harness debate frames itself as thin vs thick. Anthropic's thin loop versus LangGraph's explicit DAG. The framing assumes you pick one side and live with it. 关于智能体基座，业界一直有“薄”与“厚”的经典撕逼战。比如 Anthropic 家极简主义的“薄”循环模式，与 LangGraph 家繁复显式的 DAG（有向无环图）架构阵营。这种讨论的潜台词都在假设：你只能选一条道走到黑，然后凑合过日子。 When the harness is composed of workers on the same bus, thin vs thick is just a count of how many workers you install. A thin harness is turn-orchestrator plus provider-anthropic plus auth-credentials plus a minimal harness meta-worker. That's it. No approvals, no budgets, no policy engine, no hook fanout. Run anything. Trust the model. Useful for autonomous research agents, experimental loops, anything internal. 但只要你用总线把这些干活的 Worker 串在一起，“薄”与“厚”的差别，就仅仅是你到底安装了多少个 Worker 数量的差别而已！一个极简“薄”基座的配方是：`turn-orchestrator` + `provider-anthropic` + `auth-credentials`，外加一个极简版的基座元节点。就这些，完事。没有审批，不查预算，没有策略引擎拦截，更没有一堆乱七八糟的钩子扇出。啥都能跑，百分百信任大模型。这套班子拿来做自动化研究型智能体、跑跑实验循环或者任何对内的项目简直完美。 A thick harness is all thirteen workers plus context-compaction plus a custom policy worker plus a custom approval-gate plus a Slack-integrated approval surface plus the budget worker enforcing per-workspace caps. Useful for an agent running customer workflows where every tool call needs to be auditable and every model spend has to roll up to a finance dashboard. 那“厚”基座长啥样？那就是十三太保 Worker 全开，外带上上下文压缩器（`context-compaction`），外加严苛的自定义策略 Worker，外挂复杂的自定义审批网关，外接 Slack 企微集成审批界面，最后再套上一个对每个工作区额度精打细算死抠上限的预算 Worker。如果你要将智能体跑在客户工作流上，如果你的合规要求每一次工具调用都得白纸黑字可供审计，并且大模型消耗的每一分钱都得老老实实地滚入财务报表的大屏里，那你必须得用这种全副武装的配置。 The architectural distance between thin and thick isn't a rewrite. It's a config change. Same wire protocol, same trace shape, same observability story. The slider moves by adding and removing workers from your config.yaml. Everything else holds. 在这里，“薄”与“厚”之间的架构距离，不再是一场推倒重来的重写灾难。它只是一次配置文件的修改。相同的网络协议，相同的链路追踪拓扑图，相同的可观测性故事。这个灵活的“滑动条”，全凭你在 `config.yaml` 增删 Worker 的操作随意滑动。架构的根基依然坚如磐石。 It applies inside a single worker too. The turn-orchestrator just shipped a refactor that collapsed its FSM from eleven states to seven, deleted the per-call turn::approval_resume::/ mechanism in favour of one reactive turn::on_approval state trigger on scope approvals, and inlined tearing_down into a finishSession() port. Every other worker in the stack (approval-gate, session, llm-budget, providers, models-catalog, auth-credentials, hook-fanout, context-compaction) stayed unchanged. The approval::resolve wire shape didn't move. The contracts held. That's the property the composition gives you: a major internal rewrite of one worker is a self-contained change because every neighbour talks to it through bus-level function ids. 哪怕深入到单一 Worker 内部，这套逻辑也同样受用。`turn-orchestrator` 编排器刚刚交付了一次重构：它硬生生地将 11 种状态压缩成了 7 种，一刀砍掉了过去那种按调用次数生成的 `turn::approval_resume::/` 的臃肿机制，全盘替换成依赖单个响应式 `turn::on_approval` 覆盖全范围审批的状态触发器，并顺带将 `tearing_down` 清理动作内联成 `finishSession()` 的直调。你猜怎么着？堆栈里的所有其他弟兄（审批网关、会话、预算、模型提供商、目录、凭据、钩子、上下文压缩）连一行代码都没改！`approval::resolve` 的数据通信接口连个逗号都没变。契约依然坚不可摧。这，就是“组装式设计”赋予你的逆天能力：对单个 Worker 进行哪怕伤筋动骨的重构，也不过是一场“闭门造车”的内部修缮。因为街坊邻居们在找它办事时，永远只认总线上挂着的那个函数 ID 门牌号。 This is the part the framework model can't give you. A framework picks a position on the slider for you and locks you in. The worker model leaves the slider in your hand. 这，正是传统的“铁板一块”框架模式永远给不了你的体验。框架在滑动条上帮你硬定了一个刻度，然后用锁头死死锁住。而 Worker 工作节点模式，则从容地把这个滑动条递到了你的手上。 ### What this means in practice ### 在实践中的意义 If you've been running an agent on top of a framework and feeling the same boundary problems most teams hit at scale, the answer is probably not "rewrite the harness in our own framework." The policy engine doesn't extend the way you need. The approval UI is wired into the framework's chat surface. The credential store can't talk to your secrets manager. The budget tracker is in a sidecar database the trace can't see. The answer is to switch to a substrate where the harness is decomposed in the first place. 如果你一直在某个大一统的框架上苦哈哈地跑智能体，并且正遭遇着绝大多数团队在扩大规模时都会痛点的边界瓶颈，那么答案很可能并不是“卷起袖子用我们自己的造轮子框架重写一遍基座”。策略引擎扩展性差？审批 UI 跟框架默认的聊天界面绑死在了一起？凭据库就是连不上你们自建的密钥管理器？预算跟踪模块卡在某个死角里的 Sidecar 数据库里，以至于链路追踪死活看不见它？别折腾了。真正的出路是：切到一种在底层骨子里，就已经把基座完全解耦的运行机制基底上。 The fastest way to feel the argument is to clone [github.com/iii-hq/workers](https://github.com/iii-hq/workers), pnpm install, pnpm build, and run the composite entry point. You'll get the full fourteen-worker harness pointed at an iii engine. You can disable any worker by removing its entry from the boot list. You can swap any worker by writing a replacement that registers the same function ids. You can extend any worker by adding a subscriber to its hook topics. hook-fanout::publish_collect is the generic every iii hook builds on. 想要最快速体会到这种架构快感？那就克隆 [github.com/iii-hq/workers](https://github.com/iii-hq/workers)，执行 `pnpm install`、`pnpm build`，然后跑起复合入口点。砰！一个由足足十四名大汉（Worker）组成的满血版基座，直指 iii 引擎便赫然跑在了你面前。你想禁掉谁，直接在启动列表里把它的名字划掉。你想换掉谁，写个新模块霸占掉原有的函数 ID 就行。你想扩展谁的功能，给它的事件钩子订阅点加个新听众就得了。`hook-fanout::publish_collect` 就是所有 iii 拓展钩子的万金油。 The docs live at [iii.dev/docs](https://iii.dev/docs). The engine is at [github.com/iii-hq/iii](https://github.com/iii-hq/iii). The worker registry is at [workers.iii.dev](https://workers.iii.dev/). The harness bundle is at [github.com/iii-hq/workers/harness](https://github.com/iii-hq/workers/tree/main/harness). 文档就在 [iii.dev/docs](https://iii.dev/docs)。引擎源码在 [github.com/iii-hq/iii](https://github.com/iii-hq/iii)。Worker 注册中心在 [workers.iii.dev](https://workers.iii.dev/)。运行基座代码包则静静躺在 [github.com/iii-hq/workers/harness](https://github.com/iii-hq/workers/tree/main/harness)。 ### The bet ### 愿景与下注 A harness is not a thing you install. A harness is a set of jobs your system has to do for an agent to run durably, safely and observably. The framework era bundled those jobs together because nothing underneath gave you a way to compose them. 基座，从来都不是一个安装包就能打发死的物件。基座，是为了让你的智能体能够持久、安全且明明白白（可观测）地跑起来，你的系统所必须完成的“一系列苦工任务”。在传统的框架时代，因为底层缺乏给你自由组合它们的武器，这堆苦活累活只能粗暴地被捆死成一团。 iii's bet is that one primitive: a worker that connects to the engine over WebSocket and registers functions and triggers is small enough to absorb every one of those jobs separately, and that the resulting stack is more useful than any framework because every layer is independently replaceable. iii 押注的是极简美学的一个原语：一个通过 WebSocket 连接到引擎并注册函数和触发器的 Worker，这种形态足够轻、足够小，小到足以将上述的每一项任务都完美地吃透并拆解开来。而由此积木般拼凑出的技术栈，将比世上任何现有的框架都更具实用性，因为在它的世界里，每一层，皆可被完美替换。 You don't adopt the iii harness. You install the workers you want, write the ones you need, and end up with a harness shaped exactly like your system. Same protocol on every layer. Same trace across every call. Same iii worker add for the parts you take from the registry as for the parts you publish yourself. 所以，你并非是在“生搬硬套” iii 的基座。你是在安装你恰好相中的那些 Worker，顺手再写上几个你独有业务需要的 Worker。最终交付到你手上的，是一个形状、脾性完全复刻你系统模样的完美基座。在它的每一层，永远是整齐划一的协议。在每一次跨系统的深海潜游中，永远是清晰连贯的链路 Trace 追踪图。无论是从注册中心拿来的现成货，还是你自己手写的看家本事，安装命令永远是那句干脆利落的：`iii worker add`。 That's what "build your own agent harness" looks like when the substrate is the right shape. Pick the workers. Write the missing ones. Compose. The harness is the composition. 这才叫真正的“构建你自己的智能体运行基座”。只要底子打对了形状，剩下的就是挑人（Worker），补缺，然后组装。这套完美的积木组合件，本身就是基座。 Join us in building the perfect agent harness that the modern world needs: discord.gg/iiidev 欢迎加入我们，共同打造这个现代世界迫切渴求的完美智能体运行基座：discord.gg/iiidev iii is open source. Get started at [iii.dev/docs](https://iii.dev/docs). The harness workers are at [github.com/iii-hq/workers](https://github.com/iii-hq/workers) and the engine is at [github.com/iii-hq/iii](https://github.com/iii-hq/iii). iii 完全开源。从 [iii.dev/docs](https://iii.dev/docs) 开启征途。基座的 Worker 在 [github.com/iii-hq/workers](https://github.com/iii-hq/workers)，而它的轰鸣引擎坐落于 [github.com/iii-hq/iii](https://github.com/iii-hq/iii)。 — Mike Piccolo, Founder & CEO @iiidevs — Mike Piccolo，iiidevs 创始人兼 CEO