iii Engine 深度解析：启动流程、职责边界、断连清理与配置热重载的实现机制

iii 项目的 Engine（iii 引擎）是 Worker、Trigger 与 Function 三个原语得以运转的核心层。本文以官方文档 Engine 的六大主题——启动流程、运行时职责、Worker 断连清理、配置热重载、架构无关路由、服务发现与活动注册表——为骨架，结合 engine/src 下的实际源码逐一印证：读完后，你将理解 Engine 从进程拉起、加载 config.yaml、建立 WebSocket 连接到路由调用的完整生命周期，以及热重载与断连清理在源码层面的实现边界。

启动流程：从命令行参数到开始服务

官方文档描述的启动序列是：

1. 解析命令行参数；
2. 加载配置文件（通常是 config.yaml）；
3. 应用配置中的 worker 声明（拉起每个声明的 worker 进程）；
4. 开始接受连接。

在这个序列结束后，Engine 即可接受来自 Worker 的 WebSocket 连接，并在 Worker 之间路由调用。源码中这条序列与 engine/src/main.rs 的实现一一对应：

• 命令行解析：main() 通过 clap 的 Cli::try_parse_from(&argv) 解析参数（engine/src/main.rs#L303-L318）。不带子命令的 iii 直接落入 serve 分支，即引擎服务模式。
• 配置加载：run_serve() 首先确定配置路径（--config 显式值或默认 config.yaml，见 config_path_of()），再调用 EngineConfig::config_file(config_path) 读取配置，随后 EngineBuilder::new().with_config(config).with_config_path(config_path).build() 构建引擎并执行 engine.serve()（engine/src/main.rs#L281-L300）。
• 配置文件缺失的兜底：一个文档没有展开但源码里明确的行为是 ensure_config_file()——当 config.yaml 不存在时，交互式终端会询问是否创建，容器/CI 等无头环境则直接写入 EngineConfig::starter_config_yaml() 生成的起始配置，保证引擎在任何环境下都能继续启动（engine/src/main.rs#L243-L273）。

一个值得注意的细节：--config 只在不带子命令（即 serve 模式）以及子命令之前的位置生效。测试 config_flag_is_not_global_on_subcommands 明确验证了 iii project init --config foo.yaml 必须解析失败，而 --config 放在子命令之前仍然合法（engine/src/main.rs#L965-L981）。仓库根部的 engine/config.yaml 就是引擎自身随仓发布的真实配置样例，engine/worker-compose.yaml 则展示了 compose 侧的 worker 声明形态。

Engine 的三大运行时职责

文档将 Engine 的运行时职责归纳为三点，源码中的核心结构恰好一一对应。engine/src/engine/mod.rs 中 Engine 结构体持有的字段就是职责的物理体现（engine/src/engine/mod.rs#L369-L400）：

1. 接受 Worker 的 WebSocket 连接并维护活动注册表 对应 worker_registry: Arc<WorkerConnectionRegistry> 与 runtime_workers: Arc<DashMap<String, RuntimeWorkerInfo>>。每个 WS 连接由 worker_connections 模块封装（见 engine/src/worker_connections/mod.rs），连接建立后通过 engine::workers::register 携带命名空间信息进入注册表。
2. 跟踪每个已连接 Worker 注册的 Functions 与 Triggers，形成系统级统一表面 对应 functions: Arc<FunctionsRegistry> 与 trigger_registry: Arc<TriggerRegistry>，另有 service_registry 承载服务注册。所有注册以 (namespace, function_id) 为键，命名空间是键的一部分而非装饰——源码注释明确说明，若只用裸 id 作键，会让一个命名空间里的 Worker 抢占另一命名空间中 Worker 合法持有的函数 id，造成释放时的孤儿注册（engine/src/engine/mod.rs#L378-L399）。
3. 路由调用 对应 invocations: Arc<InvocationHandler>（实现位于 engine/src/invocation/mod.rs）。当 Trigger 触发或 Function 被调用时，Engine 找到提供目标 Function 的 Worker 并派发。EngineTrait trait 定义了引擎内部调用的分层入口：call() → call_with_metadata()（默认命名空间，供 hooks/中间件使用）→ call_with_metadata_ns()（显式命名空间，供 fire_triggers 按 trigger 声明的目标命名空间解析函数，见 engine/src/engine/mod.rs#L273-L306）。

源码中还可见一个文档未展开的并发细节：命名空间解析的缓冲机制。Worker 连接的命名空间并非独立协议消息，而是随 engine::workers::register 引擎调用到达；旧版 SDK 会先冲刷注册队列再发该调用，因此 RegisterFunction 等消息可能早于命名空间到达。Engine 为此设计了 Pending → Draining → Resolved 的 NamespaceState 状态机，将注册类消息按到达顺序排队，并给新连接 5 秒的 REGISTRATION_NAMESPACE_GRACE 宽限期，防止注册被错误地落入 default 命名空间（engine/src/engine/mod.rs#L62-L97）。

Worker 断连清理：注销注册、取消在途调用、系统继续服务

文档指出，Worker 断连时 Engine 会清理其在活动注册表中的全部足迹：移除其 Functions 与 Triggers、取消针对这些 Function 的在途调用，其余系统继续服务。这一行为的实现核心是 cleanup_worker()（engine/src/engine/mod.rs#L2688-L2829），调用链上有几处值得注意的防护：

• 双路径触发：读循环正常结束（engine/src/engine/mod.rs#L2593-L2609 打印 Worker disconnected）与写端中止（Worker disconnected (writer aborted)）都会汇入 cleanup_worker；
• 防止重复清理：源码注释说明清理是幂等去重的（避免重复的 worker_disconnected 触发与指标），并通过 NamespaceState::Aborted 让正在 drain 注册队列的任务立刻停手，不再为已消失的 worker 注册函数；
• 取消在途调用：在途调用等待响应时若持有方已断开，会返回“caller already disconnected”一类的预期错误（engine/src/engine/mod.rs#L2022-L2031）；
• fast-restart 竞态防护：function_owners 以 CAS（check-and-set）方式记录每个函数当前的属主连接，清理时原子地跳过已被另一存活 Worker 覆盖的注册，防止旧连接的 cleanup_worker 误删新连接的注册（engine/src/engine/mod.rs#L2221 与 engine/src/engine/mod.rs#L3745-L3786 的 cleanup_worker_releases_the_name_lease 测试）。

断连的取消错误码与随之触发的发现事件（含一致性语义），文档指引到 docs/0-21-0/creating-workers/workers.mdx 中 “Handling Worker disconnects” 一节继续查阅。断连场景的端到端验证散布在 engine/tests/worker_namespace_ws_e2e.rs、engine/tests/worker_ws_handshake_timeout_test.rs 等集成测试中。

配置热重载：parse → diff → validate → commit，以及 settings 的独立层

文档对热重载的描述是：config.yaml 在运行时被监视；文件变化时 Engine 会解析、求差、校验并提交新配置；差集中未变化的 Worker 保持运行，只有新增、删除或变更的 Worker 会重启；若配置非法（解析错误或校验失败），Engine 直接退出而不是进入不确定状态。

源码侧对应 workers::reload 模块（remove_worker_registrations() 接收 WorkerRegistrations 快照来撤销旧注册，见 engine/src/engine/mod.rs#L589），并有三个针对性测试覆盖热重载的差集逻辑：

• engine/tests/reload_diff_unit.rs：diff 计算；
• engine/tests/reload_manager_unit.rs：reload 管理器；
• engine/tests/reload_scope_unit.rs：作用域判断；
• engine/tests/config_reload_e2e.rs：端到端验证文件变更触发的完整重载路径。

文档特别强调了 Worker settings 是独立于引擎热重载的一层：注册了配置 schema 的 Worker 只在首次启动时读取一次自己的 config: 块，用于在 configuration worker（docs/0-21-0/using-iii/configuration.mdx）中建立条目；此后 settings 完全由该 worker 管理并动态更新，无需引擎重载。settings 变更会对照 Worker 的 schema 校验：非法变更被拒绝、旧值继续生效——因此一次错误的 settings 编辑永远不会拖垮 Engine。这个设计与上文热重载“配置非法则退出”的策略形成对照：config.yaml 是引擎自身的部署面，坏了必须失败得响亮；而 Worker settings 是业务运行面，坏了必须失败得安静。

架构无关的路由

文档的表述是：路由独立于语言、运行时和位置。无论 Function 由笔记本电脑上的 Python Agent、浏览器标签页中的 TypeScript Worker、microVM 里的 Rust 二进制，还是 Kubernetes 上的 OCI 镜像承载，Engine 走的都是同一条路由路径。从源码结构看这一点成立：EngineTrait 的 call_with_metadata_ns 等入口只按 (namespace, function_id) 在 FunctionsRegistry 中解析目标，不感知属主 Worker 的语言或宿主；连接端差异全部被 WorkerConnection 抽象吸收。文档中 “Python Agent on a laptop / browser tab / microVM / OCI image on Kubernetes” 的场景组合，与仓库中 worker 侧多语言 SDK（sdk/python、sdk/node、sdk/rust、sdk/go）并存的事实一致。

服务发现与活动注册表

Engine 维护的注册表覆盖三个维度：每个已连接 Worker、各 Worker 注册的 Functions、以及绑定到这些 Function 的 Triggers。其他 Worker 与工具链既可以按需读取注册表快照，也可以订阅其变化事件。

文档引用的具体调用与事件是：engine::*::list 系列快照调用（读取当前注册表状态），以及 engine::workers-available / engine::functions-available 两个订阅事件（注册表演变时推送）。源码中确实存在 TRIGGER_WORKERS_AVAILABLE 等引擎内置触发常量（engine/src/engine/mod.rs#L38-L43 的导入处），具体的调用示例见 docs/0-21-0/creating-workers/workers.mdx 的 “Inspecting the live registry” 一节。

文档最后还提到：traces、logs 与 metrics 的查询由 iii-observability Worker 承载。这与源码中 Engine 内置的 OTLP 二进制帧处理（OTLP / MTRC / LOGS 三个 magic 前缀，见 engine/src/engine/mod.rs#L45-L50 与 handle_telemetry_frame()）呼应——SDK 可直接把遥测数据走 WS 通道送进引擎，而查询面则由独立 worker 提供。

小结

文档主题	源码落点	关键机制
启动流程	engine/src/main.rs	clap 解析 → EngineConfig::config_file → EngineBuilder::build → serve()
三大职责	engine/src/engine/mod.rs	WorkerConnectionRegistry + FunctionsRegistry + TriggerRegistry + InvocationHandler
断连清理	cleanup_worker()（engine/src/engine/mod.rs#L2688）	幂等去重、CAS 属主表防 fast-restart 误删、在途调用取消
热重载	engine/tests/reload_diff_unit.rs 等	parse→diff→validate→commit；仅重启差集 Worker；非法配置即退出
架构无关路由	EngineTrait::call_with_metadata_ns	按 (namespace, function_id) 解析，不感知属主语言/运行时
发现与注册表	TRIGGER_WORKERS_AVAILABLE 等内置触发	engine::*::list 快照 + available 事件订阅

理解了以上六个部分，就掌握了 iii Engine 的完整心智模型：它是一个无状态路由内核——连接进来即注册、注册即路由、断连即清理、配置变更即差量重启，而 Worker 究竟跑在哪种语言与运行时里，对它而言只是一个连接。