iii 倉庫的 AGENTS.md 實(shí)戰(zhàn)指南Function / Trigger / Worker 三元組開發(fā)規(guī)范與 monorepo 協(xié)作邊界【免費(fèi)下載鏈接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/mo/iii導(dǎo)讀AGENTS.md是 iii 后端統(tǒng)一引擎 monorepo 面向編碼 Agent及人類開發(fā)者的倉庫憲法它以極短的篇幅定義了倉庫的三大原語Function、Trigger、Worker、全部構(gòu)建測試命令、項(xiàng)目目錄地圖、以及Always / Ask First / Never三層協(xié)作邊界并用 Rust、TypeScript、Python 三套 SDK 示例規(guī)定了函數(shù) ID 分隔符、HTTP 路徑與 Cron 表達(dá)式字段等核心編碼風(fēng)格。讀完本文你將掌握在該倉庫中正確注冊函數(shù)與觸發(fā)器、跑通構(gòu)建與測試、遵循引擎配置 Schema 約束的全部約定并了解這些約定在 engine 與各 SDK 源碼中的真實(shí)落點(diǎn)。1. 倉庫定位一個以 WebSocket 為核心的后端統(tǒng)一引擎AGENTS.md 開篇即給出倉庫的本質(zhì)定義iii 是一個backend unification engine擁有三個核心原語——Function函數(shù)、Trigger觸發(fā)器、Worker工作進(jìn)程。引擎本體由 Rust 編寫官方 SDK 覆蓋 TypeScript、Python、Rust 三種語言且所有 SDK 與引擎之間的通信都基于 WebSocket。這一架構(gòu)在源碼中得到了完全印證引擎的engine_fn內(nèi)置 worker 文檔將運(yùn)行時(shí)描述為 a WebSocket-routed worker mesh一個引擎進(jìn)程默認(rèn)端口49134持有所有已連接 worker、每個 worker 暴露的函數(shù)以及綁定到這些函數(shù)上的觸發(fā)器的實(shí)時(shí)注冊表worker 之間不存在直連流量每次調(diào)用都經(jīng)過caller → engine → handler路由見 engine/src/workers/engine_fn/README.md引擎源碼中的 trigger_formats.rs 為每種內(nèi)置觸發(fā)器類型定義了注冊時(shí)配置格式與觸發(fā)時(shí)調(diào)用請求格式兩套 Schema并派生JsonSchema供引擎自動生成 JSON Schema 定義。因此AGENTS.md 并非泛泛的倉庫介紹而是為在這套 WebSocket 路由的 worker 網(wǎng)格里正確編寫代碼提供的操作手冊。2. 命令速查從 Setup 到 Cloud 的完整工作流AGENTS.md 將倉庫命令劃分為六個層次覆蓋一個功能從依賴安裝、構(gòu)建、測試、靜態(tài)檢查到部署上云的全生命周期。2.1 依賴安裝與構(gòu)建# Setup pnpm install # JS/TS 依賴 cargo build --release # Rust workspace # Build pnpm build # 所有 JS/TS 包Turborepo 編排 cargo build --release # engine Rust SDK console兩個 Workspace 定義文件共同支撐這套構(gòu)建體系Cargo.toml 聲明 Rust workspace成員包括engine、sdk/packages/rust/iiiRust SDK、console/packages/console-rust以及crates/下的一批工具 crateiii-compose、iii-init、iii-filesystem、iii-network、iii-worker、scaffolder-core等當(dāng)前版本為0.23.0-rc.9并預(yù)置了tokio、serde、clap、reqwest等共享依賴與wiremock、tempfile、serial_test等共享 dev-dependenciespnpm-workspace.yaml 聲明 JS/TS 包范圍覆蓋sdk/packages/node/iii及其示例/瀏覽器/可觀測性/helpers 包、console/packages/*、docs與websiteturbo.json 定義構(gòu)建編排任務(wù)build依賴上游構(gòu)建dependsOn: [^build]、test與test:ci均依賴 build 且關(guān)閉緩存、dev為持久任務(wù)。2.2 測試與質(zhì)量檢查# 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/TSBiome pnpm fmt:check # 僅檢查不修改 pnpm lint # lint JS/TS cargo fmt --all # 格式化 Rust cargo clippy --workspace # lint Rust注意幾個細(xì)節(jié)Rust 的格式化使用cargo fmt --all覆蓋整個 workspaceJS/TS 側(cè)由 biome.json 驅(qū)動Python SDK 使用uv管理依賴先uv sync --extra dev拉取 dev 依賴再跑pytest。Rust SDK 的測試可以進(jìn)一步深入到 sdk/packages/rust/iii/tests 下的集成測試如api_triggers.rs、middleware.rs、pubsub.rs它們以真實(shí)引擎連接驗(yàn)證觸發(fā)器的注冊與調(diào)用行為。2.3 本地運(yùn)行與云端部署# Run cargo run --release # 啟動引擎讀取 engine/config.yaml pnpm dev:console # console 前端開發(fā)服務(wù)器 pnpm dev:docs # docs 開發(fā)服務(wù)器Mintlify pnpm dev:website # website 開發(fā)服務(wù)器 # Cloud iii cloud deploy --config path # 部署到 iii Cloud iii cloud list # 列出部署 iii cloud update deployment-id # 更新部署 iii cloud delete deployment-id # 刪除部署引擎啟動時(shí)讀取 engine/config.yaml。該文件當(dāng)前配置了兩個引擎生命周期內(nèi)的 workeriii-stream流式通道 worker監(jiān)聽127.0.0.1:3112端口可用STREAM_PORT環(huán)境變量覆蓋底層適配器為 Redisredis://localhost:6379configuration配置 worker使用fs適配器從./config目錄讀取配置ttl_seconds: 0表示不做緩存過期。此外文件還預(yù)留了被注釋的iii-sandbox瞬時(shí)沙箱配置示例image_allowlist、default_idle_timeout_secs、max_concurrent_sandboxes等字段表明沙箱屬于引擎托管特例而非普通項(xiàng)目 worker。3. 項(xiàng)目地圖一眼看懂 monorepo 布局AGENTS.md 給出的目錄地圖與倉庫實(shí)際結(jié)構(gòu)一致是定位代碼的首要索引engine/ Rust 引擎——運(yùn)行時(shí)、模塊、協(xié)議、CLI sdk/packages/node/iii/ TypeScript SDKnpm: iii-sdk sdk/packages/node/iii-browser/ 瀏覽器 SDKnpm: iii-browser-sdk sdk/packages/python/iii/ Python SDKPyPI: iii-sdk sdk/packages/rust/iii/ Rust SDKcrates.io: iii-sdk console/ 開發(fā)者控制臺React Rust skills/ 26 個 Agent skillsSkillKit 自動發(fā)現(xiàn) docs/ 文檔站Mintlify/MDX website/ iii.dev 官網(wǎng) website/presentations/ Tech-spec 演示站點(diǎn)iii.dev/tech-specs/ tech-specs/ Markdown 形式的規(guī)格文檔 scripts/ 構(gòu)建與 CI 腳本幾個需要留意的細(xì)節(jié)sdk/packages/rust/iii對應(yīng) Cargo.toml 中 workspace 依賴iii-sdk的路徑引用另有sdk/packages/rust/observabilityiii-observability與sdk/packages/rust/helpersiii-helpers作為配套 crate倉庫實(shí)際目錄skills/下包含 6 個iii-前綴的 skilliii-architecture-patterns、iii-core-primitives、iii-engine-config、iii-error-handling、iii-getting-started、iii-sdk-reference以及presentation/子項(xiàng)目每個 SKILL.md 都遵循 AGENTS.md 規(guī)定的結(jié)構(gòu)要求根目錄的Cargo.tomlRust、pnpm-workspace.yamlJS/TS、turbo.json構(gòu)建編排共同構(gòu)成三套工作區(qū)聲明。4. 協(xié)作邊界Always / Ask First / Never 三層規(guī)則AGENTS.md 用三個等級劃定了 Agent 在倉庫中的行為邊界這是避免破壞性變更的關(guān)鍵。4.1 Always必須遵守的硬性約定JS/TS 包一律使用pnpm禁止npm提交 Rust 變更前先跑cargo fmt --all提交 JS/TS 變更前先跑pnpm fmtHTTP 觸發(fā)器api_path必須使用前導(dǎo)斜杠/orders、/users/:idCron 觸發(fā)器配置字段必須叫expression而不是cron函數(shù) ID 使用::分隔符orders::validate、reports::daily-summary內(nèi)部 pnpm 包引用使用workspace:*協(xié)議每個 SKILL.md 必須包含## When to Use與## Boundaries小節(jié)且 SKILL.md 的name字段必須與所在目錄名完全一致。這些約定不是隨意規(guī)定而是與引擎的實(shí)際解析邏輯強(qiáng)綁定詳見第 5 節(jié)。4.2 Ask First變更前必須征詢的領(lǐng)域修改公開 SDK APInpm / PyPI / crates.io 對外暴露面修改引擎配置 Schemaengine/config.yaml修改 CI/CD 工作流.github/新增引擎模塊修改 SDK 與引擎之間的 WebSocket 協(xié)議。4.3 Never絕對禁止的行為提交密鑰、API Key 或憑據(jù)用npm代替pnpm直接向main分支推送更改引擎許可證ELv2或 SDK 許可證Apache-2.0——這一雙許可證結(jié)構(gòu)在 AGENTS.md 末尾的 Licensing 一節(jié)有明確說明engine/使用 Elastic License v2其余部分為 Apache-2.0引擎源碼文件頭部的版權(quán)注釋也印證了這一點(diǎn)從 SKILL.md 中刪除 When to Use / Boundaries 小節(jié)SkillKit 會校驗(yàn)用cron作為配置鍵——引擎標(biāo)準(zhǔn)是expression在api_path上省略前導(dǎo)斜杠——引擎標(biāo)準(zhǔn)是/path。5. 編碼風(fēng)格三語言 SDK 的統(tǒng)一約定AGENTS.md 用 Rust、TypeScript、Python 三套示例展示了完全一致的約定這是理解全文最重要的部分。5.1 函數(shù) ID 使用::分隔符無論哪種語言函數(shù) ID 都遵循服務(wù)名::動作名的命名空間約定// Rust —— 函數(shù) ID 使用 :: 分隔符 iii.register_function( RegisterFunction::new(orders::validate, validate_order) .description(Validate an incoming order), );::分隔符在引擎中被視為函數(shù) ID 的命名空間契約engine_fnREADME 明確Function 是 worker 內(nèi)的命名處理器ID 形如service::name函數(shù) 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 觸發(fā)器使用前導(dǎo)斜杠// Rust —— HTTP 觸發(fā)器使用前導(dǎo)斜杠 iii.register_trigger( IIITrigger::Http(HttpTriggerConfig::new(/orders/validate).method(HttpMethod::Post)) .for_function(orders::validate), );引擎的HttpTriggerConfig結(jié)構(gòu)體將api_path定義為HTTP endpoint path如/users/:id支持路徑參數(shù)且http_method默認(rèn) GET見 engine/src/trigger_formats.rs 第 24–48 行。TypeScript SDK 的iii-types.ts同樣暴露api_path、http_method等字段。TypeScript 側(cè)還展示了 HTTP 觸發(fā)器的中間件鏈能力// TypeScript —— HTTP 觸發(fā)器 中間件鏈 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 觸發(fā)器在調(diào)用 handler 前依次執(zhí)行鑒權(quán)、限流等中間件函數(shù)Rust SDK 的 middleware.rs 集成測試覆蓋了此類場景。5.3 Cron 觸發(fā)器使用expression字段AGENTS.md 特別強(qiáng)調(diào)Cron 配置字段是expression而非cron且給出 7 段格式sec min hour dom month dow year秒 分 時(shí) 日 月 周 年// Rust —— Cron 觸發(fā)器使用 expression 字段 iii.register_trigger( IIITrigger::Cron(CronTriggerConfig::new(0 0 9 * * * *)) .for_function(reports::daily-summary), );需要說明的一點(diǎn)是格式口徑AGENTS.md 的示例注釋寫作 7 段格式而引擎源碼 trigger_formats.rs 第 98–104 行的CronTriggerConfig注釋寫作 6-field format: sec min hour day month weekday。兩者在以0 0 9 * * * *這類表達(dá)式描述每日 9 點(diǎn)執(zhí)行的語義上一致但段數(shù)表述存在差異——實(shí)際編寫 Cron 觸發(fā)器時(shí)建議以當(dāng)前引擎源碼trigger_formats.rs中CronTriggerConfig.expression字段的注釋口徑為準(zhǔn)并在注冊前用小粒度表達(dá)式驗(yàn)證。字段名的強(qiáng)制性是雙重的引擎的CronTriggerConfig中字段就叫expression而非cron同時(shí) AGENTS.md 的 Never 清單再次強(qiáng)調(diào)不要用cron作為配置鍵。5.4 觸發(fā)器元數(shù)據(jù)可選TypeScript 示例展示了觸發(fā)器可附帶metadata隨觸發(fā)器一起存儲便于標(biāo)記歸屬團(tuán)隊(duì)與優(yōu)先級// TypeScript —— 帶元數(shù)據(jù)的觸發(fā)器 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 —— 同樣的模式前導(dǎo)斜杠 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 生態(tài)倉庫自帶的 LLM 知識庫AGENTS.md 說明skills/目錄包含 26 個iii-前綴的 Agent skills可通過npx skills add iii-hq/iii與npx skillkit install iii-hq/iii自動發(fā)現(xiàn)安裝倉庫中每個 SKILL.md 都配有 TypeScript、Python、Rust 變體的參考實(shí)現(xiàn)。倉庫實(shí)際可見的 skills 為 6 個iii-architecture-patterns、iii-core-primitives、iii-engine-config、iii-error-handling、iii-getting-started、iii-sdk-reference外加presentation/子項(xiàng)目總目錄結(jié)構(gòu)見 skills/完整的清單與安裝說明可參考 skills/README.md 與 skills/SKILLS.md。這些 skill 被 SkillKit 校驗(yàn)SKILL.md 必須含 When to Use 與 Boundaries 小節(jié)是面向編碼 Agent 的結(jié)構(gòu)化知識單元。此外AGENTS.md 提到博客文章作為 Agent 知識庫website/src/content/blog/為源碼目錄用于沉淀架構(gòu)文章與編碼示例供 Agent 檢索引用。7. 實(shí)戰(zhàn)要點(diǎn)總結(jié)基于 AGENTS.md 與倉庫源碼編寫 iii 相關(guān)代碼時(shí)應(yīng)時(shí)刻遵守以下清單維度約定依據(jù)包管理JS/TS 一律pnpmAGENTS.md Always / Never函數(shù) ID服務(wù)::動作如orders::validateengine_fn READMEHTTP 路徑必須前導(dǎo)斜杠支持:param路徑參數(shù)trigger_formats.rsCron 字段expression禁止crontrigger_formats.rs 第 99–101 行中間件middleware_function_ids串起調(diào)用鏈iii-types.ts、middleware.rs 測試引擎配置修改engine/config.yamlSchema 前先征詢AGENTS.md Ask First許可證引擎 ELv2其余 Apache-2.0AGENTS.md Licensing、LICENSE.spdxSKILL.md必須含 When to Use / Boundariesname 與目錄一致AGENTS.md AlwaysAGENTS.md 的獨(dú)特價(jià)值在于它把引擎如何解析與代碼該怎么寫直接對齊——api_path的前導(dǎo)斜杠、expression字段名、::分隔符都不是風(fēng)格偏好而是引擎 trigger_formats.rs 與 worker 網(wǎng)格運(yùn)行時(shí)實(shí)際讀取的 Schema 契約。對于任何準(zhǔn)備在 iii monorepo 中編寫或?qū)彶榇a的 Agent 與開發(fā)者這份文件既是入門地圖也是不可違背的邊界手冊。【免費(fèi)下載鏈接】iiiEffortlessly compose, extend, and observe every service in real-time for the first time ever.項(xiàng)目地址: https://gitcode.com/GitHub_Trending/mo/iii創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考