iii 仓库的 AGENTS.md 实战指南：Function / Trigger / Worker 三元组开发规范与 monorepo 协作边界

iii 仓库的 AGENTS.md 实战指南：Function / Trigger / Worker 三元组开发规范与 monorepo 协作边界

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii

导读

AGENTS.md是 iii 后端统一引擎 monorepo 面向编码 Agent（及人类开发者）的"仓库宪法"：它以极短的篇幅定义了仓库的三大原语Function、Trigger、Worker、全部构建测试命令、项目目录地图、以及"Always / Ask First / Never"三层协作边界，并用 Rust、TypeScript、Python 三套 SDK 示例规定了函数 ID 分隔符、HTTP 路径与 Cron 表达式字段等核心编码风格。读完本文，你将掌握在该仓库中正确注册函数与触发器、跑通构建与测试、遵循引擎配置 Schema 约束的全部约定，并了解这些约定在 engine 与各 SDK 源码中的真实落点。

1. 仓库定位：一个以 WebSocket 为核心的后端统一引擎

AGENTS.md 开篇即给出仓库的本质定义：iii 是一个backend unification engine，拥有三个核心原语——Function（函数）、Trigger（触发器）、Worker（工作进程）。引擎本体由 Rust 编写，官方 SDK 覆盖 TypeScript、Python、Rust 三种语言，且所有 SDK 与引擎之间的通信都基于 WebSocket。

这一架构在源码中得到了完全印证：

• 引擎的engine_fn内置 worker 文档将运行时描述为 "a WebSocket-routed worker mesh"：一个引擎进程（默认端口49134）持有所有已连接 worker、每个 worker 暴露的函数以及绑定到这些函数上的触发器的实时注册表，worker 之间不存在直连流量，每次调用都经过caller → engine → handler路由（见 engine/src/workers/engine_fn/README.md）；
• 引擎源码中的 trigger_formats.rs 为每种内置触发器类型定义了"注册时配置格式"与"触发时调用请求格式"两套 Schema，并派生JsonSchema供引擎自动生成 JSON Schema 定义。

因此，AGENTS.md 并非泛泛的仓库介绍，而是为"在这套 WebSocket 路由的 worker 网格里正确编写代码"提供的操作手册。

2. 命令速查：从 Setup 到 Cloud 的完整工作流

AGENTS.md 将仓库命令划分为六个层次，覆盖一个功能从依赖安装、构建、测试、静态检查到部署上云的全生命周期。

2.1 依赖安装与构建

# Setup pnpm install # JS/TS 依赖 cargo build --release # Rust workspace # Build pnpm build # 所有 JS/TS 包（Turborepo 编排） cargo build --release # engine + Rust SDK + console

两个 Workspace 定义文件共同支撑这套构建体系：

• Cargo.toml 声明 Rust workspace，成员包括engine、sdk/packages/rust/iii（Rust SDK）、console/packages/console-rust以及crates/下的一批工具 crate（iii-compose、iii-init、iii-filesystem、iii-network、iii-worker、scaffolder-core等），当前版本为0.23.0-rc.9，并预置了tokio、serde、clap、reqwest等共享依赖与wiremock、tempfile、serial_test等共享 dev-dependencies；
• pnpm-workspace.yaml 声明 JS/TS 包范围，覆盖sdk/packages/node/iii及其示例/浏览器/可观测性/helpers 包、console/packages/*、docs与website；
• turbo.json 定义构建编排任务：build依赖上游构建（dependsOn: ["^build"]）、test与test:ci均依赖 build 且关闭缓存、dev为持久任务。

2.2 测试与质量检查

# Test pnpm test # 全部 JS/TS 测试 cargo test # 全部 Rust 测试 cargo test -p iii # 仅引擎 cargo test -p iii-sdk # 仅 Rust SDK cd sdk/packages/python/iii && uv sync --extra dev && uv run pytest # Python SDK # Lint & Format pnpm fmt # 格式化 JS/TS（Biome） pnpm fmt:check # 仅检查不修改 pnpm lint # lint JS/TS cargo fmt --all # 格式化 Rust cargo clippy --workspace # lint Rust

注意几个细节：Rust 的格式化使用cargo fmt --all覆盖整个 workspace；JS/TS 侧由 biome.json 驱动；Python SDK 使用uv管理依赖，先uv sync --extra dev拉取 dev 依赖再跑pytest。Rust SDK 的测试可以进一步深入到 sdk/packages/rust/iii/tests 下的集成测试（如api_triggers.rs、middleware.rs、pubsub.rs），它们以真实引擎连接验证触发器的注册与调用行为。

2.3 本地运行与云端部署

# Run cargo run --release # 启动引擎（读取 engine/config.yaml） pnpm dev:console # console 前端开发服务器 pnpm dev:docs # docs 开发服务器（Mintlify） pnpm dev:website # website 开发服务器 # Cloud iii cloud deploy --config <path> # 部署到 iii Cloud iii cloud list # 列出部署 iii cloud update <deployment-id> # 更新部署 iii cloud delete <deployment-id> # 删除部署

引擎启动时读取 engine/config.yaml。该文件当前配置了两个引擎生命周期内的 worker：

• iii-stream：流式通道 worker，监听127.0.0.1:3112（端口可用STREAM_PORT环境变量覆盖），底层适配器为 Redis（redis://localhost:6379）；
• configuration：配置 worker，使用fs适配器从./config目录读取配置，ttl_seconds: 0表示不做缓存过期。

此外文件还预留了被注释的iii-sandbox瞬时沙箱配置示例（image_allowlist、default_idle_timeout_secs、max_concurrent_sandboxes等字段），表明沙箱属于引擎托管特例而非普通项目 worker。

3. 项目地图：一眼看懂 monorepo 布局

AGENTS.md 给出的目录地图与仓库实际结构一致，是定位代码的首要索引：

engine/ Rust 引擎——运行时、模块、协议、CLI sdk/packages/node/iii/ TypeScript SDK（npm: iii-sdk） sdk/packages/node/iii-browser/ 浏览器 SDK（npm: iii-browser-sdk） sdk/packages/python/iii/ Python SDK（PyPI: iii-sdk） sdk/packages/rust/iii/ Rust SDK（crates.io: iii-sdk） console/ 开发者控制台（React + Rust） skills/ 26 个 Agent skills（SkillKit 自动发现） docs/ 文档站（Mintlify/MDX） website/ iii.dev 官网 website/presentations/ Tech-spec 演示站点（iii.dev/tech-specs/） tech-specs/ Markdown 形式的规格文档 scripts/ 构建与 CI 脚本

几个需要留意的细节：

• sdk/packages/rust/iii对应 Cargo.toml 中 workspace 依赖iii-sdk的路径引用，另有sdk/packages/rust/observability（iii-observability）与sdk/packages/rust/helpers（iii-helpers）作为配套 crate；
• 仓库实际目录skills/下包含 6 个iii-前缀的 skill（iii-architecture-patterns、iii-core-primitives、iii-engine-config、iii-error-handling、iii-getting-started、iii-sdk-reference）以及presentation/子项目，每个 SKILL.md 都遵循 AGENTS.md 规定的结构要求；
• 根目录的Cargo.toml（Rust）、pnpm-workspace.yaml（JS/TS）、turbo.json（构建编排）共同构成三套工作区声明。

4. 协作边界：Always / Ask First / Never 三层规则

AGENTS.md 用三个等级划定了 Agent 在仓库中的行为边界，这是避免破坏性变更的关键。

4.1 Always：必须遵守的硬性约定

• JS/TS 包一律使用pnpm，禁止npm；
• 提交 Rust 变更前先跑cargo fmt --all，提交 JS/TS 变更前先跑pnpm fmt；
• HTTP 触发器api_path必须使用前导斜杠：/orders、/users/:id；
• Cron 触发器配置字段必须叫expression，而不是cron；
• 函数 ID 使用::分隔符：orders::validate、reports::daily-summary；
• 内部 pnpm 包引用使用workspace:*协议；
• 每个 SKILL.md 必须包含## When to Use与## Boundaries小节，且 SKILL.md 的name字段必须与所在目录名完全一致。

这些约定不是随意规定，而是与引擎的实际解析逻辑强绑定（详见第 5 节）。

4.2 Ask First：变更前必须征询的领域

• 修改公开 SDK API（npm / PyPI / crates.io 对外暴露面）；
• 修改引擎配置 Schema（engine/config.yaml）；
• 修改 CI/CD 工作流（.github/）；
• 新增引擎模块；
• 修改 SDK 与引擎之间的 WebSocket 协议。

4.3 Never：绝对禁止的行为

• 提交密钥、API Key 或凭据；
• 用npm代替pnpm；
• 直接向main分支推送；
• 更改引擎许可证（ELv2）或 SDK 许可证（Apache-2.0）——这一双许可证结构在 AGENTS.md 末尾的 "Licensing" 一节有明确说明（engine/使用 Elastic License v2，其余部分为 Apache-2.0），引擎源码文件头部的版权注释也印证了这一点；
• 从 SKILL.md 中删除 "When to Use" / "Boundaries" 小节（SkillKit 会校验）；
• 用cron作为配置键——引擎标准是expression；
• 在api_path上省略前导斜杠——引擎标准是/path。

5. 编码风格：三语言 SDK 的统一约定

AGENTS.md 用 Rust、TypeScript、Python 三套示例展示了完全一致的约定，这是理解全文最重要的部分。

5.1 函数 ID 使用::分隔符

无论哪种语言，函数 ID 都遵循服务名::动作名的命名空间约定：

// Rust —— 函数 ID 使用 :: 分隔符 iii.register_function( RegisterFunction::new("orders::validate", validate_order) .description("Validate an incoming order"), );

::分隔符在引擎中被视为函数 ID 的命名空间契约：engine_fnREADME 明确"Function 是 worker 内的命名处理器，ID 形如service::name，函数 ID 是任意两个 worker 之间唯一的契约"（见 engine/src/workers/engine_fn/README.md）。Rust SDK 的示例程序 cron_trigger_example.rs 同样使用example::scheduled_cleanup、example::on_user_updated这类::分隔 ID。

5.2 HTTP 触发器使用前导斜杠

// Rust —— HTTP 触发器使用前导斜杠 iii.register_trigger( IIITrigger::Http(HttpTriggerConfig::new("/orders/validate").method(HttpMethod::Post)) .for_function("orders::validate"), );

引擎的HttpTriggerConfig结构体将api_path定义为"HTTP endpoint path（如/users/:id）"，支持路径参数，且http_method默认 GET（见 engine/src/trigger_formats.rs 第 24–48 行）。TypeScript SDK 的iii-types.ts同样暴露api_path、http_method等字段。

TypeScript 侧还展示了 HTTP 触发器的中间件链能力：

// TypeScript —— HTTP 触发器 + 中间件链 iii.registerTrigger({ type: 'http', function_id: 'orders::validate', config: { api_path: '/orders/validate', http_method: 'POST', middleware_function_ids: ['middleware::auth', 'middleware::rate-limit'], }, });

middleware_function_ids让一个 HTTP 触发器在调用 handler 前依次执行鉴权、限流等中间件函数；Rust SDK 的 middleware.rs 集成测试覆盖了此类场景。

5.3 Cron 触发器使用expression字段

AGENTS.md 特别强调：Cron 配置字段是expression而非cron，且给出 7 段格式sec min hour dom month dow year（秒 分 时 日 月 周 年）：

// Rust —— Cron 触发器使用 expression 字段 iii.register_trigger( IIITrigger::Cron(CronTriggerConfig::new("0 0 9 * * * *")) .for_function("reports::daily-summary"), );

需要说明的一点是格式口径：AGENTS.md 的示例注释写作 7 段格式，而引擎源码 trigger_formats.rs 第 98–104 行的CronTriggerConfig注释写作 "6-field format: sec min hour day month weekday"。两者在"以0 0 9 * * * *这类表达式描述每日 9 点执行"的语义上一致，但段数表述存在差异——实际编写 Cron 触发器时，建议以当前引擎源码（trigger_formats.rs）中CronTriggerConfig.expression字段的注释口径为准，并在注册前用小粒度表达式验证。

字段名的强制性是双重的：引擎的CronTriggerConfig中字段就叫expression（而非cron），同时 AGENTS.md 的 "Never" 清单再次强调"不要用cron作为配置键"。

5.4 触发器元数据（可选）

TypeScript 示例展示了触发器可附带metadata，随触发器一起存储，便于标记归属团队与优先级：

// TypeScript —— 带元数据的触发器 iii.registerTrigger({ type: 'cron', function_id: 'reports::daily-summary', config: { expression: '0 0 9 * * * *' }, metadata: { owner: 'billing-team', priority: 'high' }, });

5.5 Python SDK 使用相同模式

# Python —— 同样的模式：前导斜杠 + expression 字段 iii.register_trigger({ "type": "http", "function_id": "orders::validate", "config": {"api_path": "/orders/validate", "http_method": "POST"}, })

Python SDK 采用字典传参方式，但字段名与 TypeScript 完全对齐（function_id、api_path、http_method），保证跨语言的心智一致性。

6. Skills 与 Agent 生态：仓库自带的 LLM 知识库

AGENTS.md 说明skills/目录包含 26 个iii-前缀的 Agent skills，可通过npx skills add iii-hq/iii与npx skillkit install iii-hq/iii自动发现安装；仓库中每个 SKILL.md 都配有 TypeScript、Python、Rust 变体的参考实现。

仓库实际可见的 skills 为 6 个（iii-architecture-patterns、iii-core-primitives、iii-engine-config、iii-error-handling、iii-getting-started、iii-sdk-reference）外加presentation/子项目，总目录结构见 skills/，完整的清单与安装说明可参考 skills/README.md 与 skills/SKILLS.md。这些 skill 被 SkillKit 校验（SKILL.md 必须含 "When to Use" 与 "Boundaries" 小节），是面向编码 Agent 的结构化知识单元。

此外，AGENTS.md 提到博客文章作为 Agent 知识库（website/src/content/blog/为源码目录），用于沉淀架构文章与编码示例，供 Agent 检索引用。

7. 实战要点总结

基于 AGENTS.md 与仓库源码，编写 iii 相关代码时应时刻遵守以下清单：

AGENTS.md 的独特价值在于：它把"引擎如何解析"与"代码该怎么写"直接对齐——api_path的前导斜杠、expression字段名、::分隔符都不是风格偏好，而是引擎 trigger_formats.rs 与 worker 网格运行时实际读取的 Schema 契约。对于任何准备在 iii monorepo 中编写或审查代码的 Agent 与开发者，这份文件既是入门地图，也是不可违背的边界手册。

【免费下载链接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.项目地址: https://gitcode.com/GitHub_Trending/mo/iii