goose-sdkGDK用 UniFFI 讓同一套 Goose API 跑通 Rust、Python 與 Kotlin【免費(fèi)下載鏈接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM項(xiàng)目地址: https://gitcode.com/GitHub_Trending/goose3/goosegoose-sdk 是開源 AI Agent 項(xiàng)目 goose 的綁定層bindings layer對(duì)外以 goose Development KitGDK形式發(fā)布。它既承載 ACPAgent Client Protocol與 GDK 訪問所需的共享類型也通過 UniFFI 把 goose 的核心能力編譯成 Python 與 Kotlin 原生綁定讓開發(fā)者可以在這些語言里直接構(gòu)造 Provider、發(fā)起流式與非流式補(bǔ)全并把富文本消息、工具等內(nèi)容安全地跨過 FFI 邊界傳遞。讀完本文你將掌握 GDK 的整體架構(gòu)、其跨語言 API 形態(tài)、結(jié)構(gòu)化可觀測性鉤子的用法以及 Python 包與 Maven 產(chǎn)物的完整構(gòu)建流程。goose-sdk 在 goose 中的定位goose 是一個(gè)可擴(kuò)展的開源 AI Agent其代碼庫采用多 crate 工作區(qū)結(jié)構(gòu)。crates/goose-sdk位于綁定層從其 Cargo.toml 的描述可以確認(rèn)它的雙重身份The goose Development Kit (GDK) for Rust, with optional uniffi bindings for Python/Kotlin從源碼看goose-sdk 的默認(rèn)行為是只讀共享類型、不直接引入重量級(jí) Provider 邏輯。在 lib.rs 中可以看到不開啟uniffi特性時(shí)crate 直接重導(dǎo)出goose-sdk-types位于crates/goose-sdk-types中的 GDK 線協(xié)議類型例如custom_notifications、custom_requests開發(fā)者可以基于它們構(gòu)建一個(gè)與goose acp通過 stdio 通信的 ACP 客戶端倉庫中提供了現(xiàn)成示例 acp_client.rs。開啟--features uniffi時(shí)crate 以cdylib/staticlib/rlib三種形式編譯見 Cargo.toml 中的crate-type調(diào)用uniffi::setup_scaffolding!(goose)生成綁定腳手架并暴露bindings與observability兩個(gè)模塊——前者是面向 Python/Kotlin 的進(jìn)程內(nèi) API后者是請(qǐng)求生命周期可觀測性鉤子。這意味著 goose-sdk 提供的是兩個(gè)互補(bǔ)的接入維度要么走進(jìn)程外的 ACP 協(xié)議默認(rèn)特性要么走進(jìn)程內(nèi)的 FFI 綁定uniffi特性。UniFFI 特性一套 API多種語言README 指出啟用--features uniffi后 crate 會(huì)編譯為 Python 與 Kotlin 的原生綁定命名空間分別為語言命名空間 / 包PythongoosePyPI 上的包名為goose-sdkKotlinio.github.aaif_gooseUniFFI 表面surface允許調(diào)用方完成四類核心操作構(gòu)造 Provider——既可以從聲明式 JSON 構(gòu)造declarative_provider_from_json也可以使用內(nèi)置的便捷構(gòu)造器流式補(bǔ)全 Provider 響應(yīng)stream非流式補(bǔ)全complete在 FFI 邊界傳遞富媒體消息與工具內(nèi)容MessageContent、ProviderTool等類型。從 bindings.rs 的#[uniffi::export]標(biāo)注可以看到 FFI 暴露的具體函數(shù)清單例如declarative_provider_from_json(json: String) - ResultArcProvider, GooseError——從 JSON 構(gòu)造聲明式 Provideropenai_provider(api_key)、anthropic_provider(...)、groq_provider(api_key)、databricks_provider(host, token)、databricks_v2_provider(...)以及配套的*_default_model()函數(shù)default_compaction_templates()——返回默認(rèn)的對(duì)話壓縮模板install_request_logger(...)——安裝請(qǐng)求日志回調(diào)。Provider對(duì)象本身見 bindings.rs暴露name()、supported_features()、context_limit(model)、stream(...)、complete(...)、compact(...)等方法流式請(qǐng)求返回ProviderStream通過next_chunk()逐塊拉取StreamChunk包括TextChunk、EndChunk、ErrorChunk、ToolChunk等變體?？焖偕鲜謏ust python與just kotlingoose-sdk 倉庫內(nèi)自帶的justfilecrates/goose-sdk/justfile把編譯、綁定生成和示例運(yùn)行串成一條命令just --justfile crates/goose-sdk/justfile python # 構(gòu)建綁定并運(yùn)行 examples/uniffi/provider.py just --justfile crates/goose-sdk/justfile kotlin # 構(gòu)建 Maven 工件并運(yùn)行 examples/uniffi/kotlin 示例說明原 README 中簡寫為just python/just kotlin二者等價(jià)--justfile只是顯式指定 justfile 的位置。注意該 justfile 內(nèi)設(shè)置working-directory : ../..即所有構(gòu)建命令都以倉庫根目錄為工作目錄執(zhí)行。Python 示例 provider.py 演示了完整的“構(gòu)造 Provider → 流式補(bǔ)全”鏈路from goose import ( MessageContent, MessageRole, ProviderMessage, ProviderModelConfig, StreamChunk, declarative_provider_from_json, ) async def main() - None: provider declarative_provider_from_json((HERE.parent / deepseek.json).read_text()) model ProviderModelConfig(model_namedeepseek-v4-flash) messages [ ProviderMessage( roleMessageRole.USER, content[MessageContent.Text(textwhat is the capital of France?)], ) ] stream await provider.stream( model, You are a knowledgable geography expert, messages, [], ) while chunk : await stream.next_chunk(): if isinstance(chunk, StreamChunk.TextChunk): print(chunk.text, end) elif isinstance(chunk, StreamChunk.EndChunk) and chunk.usage: print(f\nusage: {chunk.usage}) elif isinstance(chunk, StreamChunk.ErrorChunk): print(f\nerror: {chunk.error.message}, filesys.stderr)其中聲明式 Provider 的 JSON 配置來自 deepseek.json這正是“從 JSON 構(gòu)造 Provider”用法的真實(shí)樣例。Kotlin 示例 Main.kt 展示了從io.github.aaif_goose命名空間導(dǎo)入并使用 OpenAI Provider 的對(duì)應(yīng)寫法讀取環(huán)境變量OPENAI_API_KEY通過openAiProvider(apiKey)構(gòu)造 Provider再用streamFlow(...)以協(xié)程 Flow 的形式消費(fèi)StreamChunkimport io.github.aaif_goose.MessageContent import io.github.aaif_goose.MessageRole import io.github.aaif_goose.ProviderMessage import io.github.aaif_goose.ProviderModelConfig import io.github.aaif_goose.StreamChunk import io.github.aaif_goose.streamFlow import io.github.aaif_goose.providers.openai.defaultModel import io.github.aaif_goose.providers.openai.provider as openAiProvider import kotlinx.coroutines.runBlocking fun main() runBlocking { val apiKey System.getenv(OPENAI_API_KEY) require(!apiKey.isNullOrBlank()) { Set OPENAI_API_KEY before running this example. } val provider openAiProvider(apiKey) val model ProviderModelConfig(modelName defaultModel()) val messages listOf( ProviderMessage( role MessageRole.USER, content listOf(MessageContent.Text(text What is the capital of France? Answer in one sentence.)), ), ) provider.streamFlow(model, You are a knowledgeable geography expert., messages) .collect { chunk - when (chunk) { is StreamChunk.TextChunk - print(chunk.text) is StreamChunk.EndChunk - chunk.usage?.let { println(\nusage: $it) } is StreamChunk.ErrorChunk - System.err.println(\nerror: ${chunk.error.message}) is StreamChunk.ToolChunk - Unit } } println() }兩種語言示例幾乎一一對(duì)應(yīng)都包含MessageRole.USER、MessageContent.Text、EndChunk.usage、ErrorChunk.error.message印證了 UniFFI 保證跨語言 API 形態(tài)一致的設(shè)計(jì)目標(biāo)。結(jié)構(gòu)化可觀測性O(shè)bservabilityHook傳統(tǒng)的觀測手段是解析 Provider 的調(diào)試日志脆弱且難以復(fù)用。goose-sdk 提供了類型化的可觀測性鉤子注冊(cè)一個(gè)ObservabilityHook就能收到結(jié)構(gòu)化的 Provider 請(qǐng)求生命周期事件而無需在日志文本里做字符串匹配。鉤子的生命周期契約README 明確了事件的嚴(yán)格順序與不變量每個(gè)請(qǐng)求先觸發(fā)onRequestStart當(dāng) Provider 響應(yīng)可用時(shí)觸發(fā)onResponseStart——對(duì)于流式請(qǐng)求這發(fā)生在流剛打開時(shí)最后恰好觸發(fā)一次onRequestEnd攜帶結(jié)果Success或帶類型化GooseStreamError的Failure、durationMs毫秒耗時(shí)以及 tokenusage。三個(gè)事件共享同一個(gè)requestId因此可以與應(yīng)用自身的遙測如 trace/span關(guān)聯(lián)起來。README 特別強(qiáng)調(diào)一個(gè)細(xì)節(jié)流式讀取若超時(shí)會(huì)以該錯(cuò)誤結(jié)束 trace因此即使之后繼續(xù)讀取該流也絕不會(huì)再產(chǎn)生第二個(gè)onRequestEnd。對(duì)照源碼 observability.rs 可以看到這些保證的實(shí)現(xiàn)方式事件類型均為uniffi::Record派生包含request_id、provider、model、operationComplete/Stream等字段RequestEndEvent額外攜帶outcome: RequestOutcomeSuccess或Failure { error: GooseStreamError }、duration_ms、usage、response_json鉤子注冊(cè)采用進(jìn)程級(jí)全局單例HOOK: RwLockOptionArcRegisteredHook每個(gè)鉤子帶一個(gè)revoked: AtomicBoolRequestObserver::end使用AtomicBool::swap保證onRequestEnd至多觸發(fā)一次request_id通過AtomicU64自增生成格式為req-N無論是調(diào)用set_observability_hook替換舊鉤子還是調(diào)用clear_observability_hook清空鉤子舊鉤子都會(huì)被立即revoke()因此仍在飛行in-flight中的請(qǐng)求也不會(huì)再向舊鉤子投遞任何事件。observability.rs末尾的單元測試對(duì)這些不變量做了逐一驗(yàn)證如success_emits_start_response_and_end_with_usage、end_is_emitted_at_most_once、clearing_hook_mid_request_stops_in_flight_events讀者可以據(jù)此理解鉤子的精確語義。最小實(shí)現(xiàn)示例KotlinREADME 給出了一個(gè)把事件橋接到 tracing 系統(tǒng)的 Kotlin 示例class TracingHook : ObservabilityHook { override fun onRequestStart(event: RequestStartEvent) { tracer.startSpan(event.requestId, event.provider, event.model) } override fun onResponseStart(event: ResponseStartEvent) { tracer.recordTimeToFirstByte(event.requestId, event.elapsedMs) } override fun onRequestEnd(event: RequestEndEvent) { tracer.finishSpan(event.requestId, event.outcome, event.durationMs, event.usage) } } setObservabilityHook(TracingHook(), capturePayloads false)這個(gè)模式可以自然映射到常見的 trace/semantic conventions 場景onRequestStart建立 span 并記錄 Provider 與模型名onResponseStart記錄“首字節(jié)時(shí)間”Time To First Byteevent.elapsedMsonRequestEnd匯總最終結(jié)果、耗時(shí)與 token 用量。性能與安全語義READMA 明確了兩點(diǎn)使用約束源碼也給出了對(duì)應(yīng)實(shí)現(xiàn)同步回調(diào) 崩潰隔離鉤子在調(diào)用線程上同步執(zhí)行且被catch_unwind包裹見 observability.rs 中RegisteredHook::emit的實(shí)現(xiàn)所以一個(gè)拋異常的鉤子回調(diào)不會(huì)導(dǎo)致請(qǐng)求失敗。反過來鉤子回調(diào)必須足夠快否則會(huì)直接增加被觀測請(qǐng)求的延遲。單元測試panicking_hook_does_not_stop_later_events驗(yàn)證了onRequestStart 拋異常后后續(xù) onResponseStart / onRequestEnd 仍能正常投遞。默認(rèn)不捕獲負(fù)載set_observability_hook的capturePayloads參數(shù)默認(rèn)值為false對(duì)應(yīng) Rust 側(cè)#[uniffi::export(default(capture_payloads false))]。該模式下RequestStartEvent.payload與RequestEndEvent.responseJson恒為null事件里只剩下非敏感元數(shù)據(jù)provider、model、延遲、用量。安全指引Security guidance這是使用鉤子時(shí)最重要的邊界負(fù)載捕獲默認(rèn)關(guān)閉是有意為之。一旦開啟capturePayloadsRequestStartEvent.payload會(huì)攜帶系統(tǒng)提示詞system、完整對(duì)話messages與工具模式tools它們通常包含憑據(jù)、客戶數(shù)據(jù)和其他機(jī)密。因此僅在**你完全掌控 sink日志/遙測后端**時(shí)才開啟capturePayloads在持久化或?qū)С鲞@些字段之前務(wù)必自行做脫敏redaction。另有一個(gè)容易踩坑的不對(duì)稱性RequestEndEvent.responseJson只對(duì)complete非流式調(diào)用填充對(duì)stream調(diào)用恒為null。原因是流式響應(yīng)是按塊chunk直接交付給調(diào)用方的SDK從不緩沖整個(gè)響應(yīng)體源碼中stream路徑的事件結(jié)束不攜帶response_json。如果應(yīng)用需要完整的流式響應(yīng)正文應(yīng)當(dāng)從自己已經(jīng)收到的 chunks 中自行拼接而不是依賴鉤子事件。Python 包構(gòu)建本地 wheelGDK 的 Python 產(chǎn)物通過 PyPI 發(fā)布包名為goose-sdkimport 名是goose。其 python/README.md 說明了本地構(gòu)建方式——在倉庫根目錄執(zhí)行just --justfile crates/goose-sdk/justfile python-wheel這條命令背后對(duì)應(yīng) justfile 中的python-wheel→python-bindings release鏈實(shí)際完成的工作包括cargo build -p goose-sdk --features uniffi --release以 release 模式編譯原生庫在 Linux/macOS/Windows 上分別產(chǎn)出libgoose_sdk.so/.dylib/.dll見 justfile 頂部的平臺(tái)推導(dǎo)運(yùn)行g(shù)oose-uniffi-bindgen generate --library ... --config ... --language python --no-format --out-dir ...重新生成 Python 綁定把生成的goose.py重命名為__init__.py將 release 原生庫拷入包目錄并生成py.typed標(biāo)記以支持類型檢查用uvxpyproject-build構(gòu)建 wheel產(chǎn)物寫入crates/goose-sdk/python/dist/。如果需要快速驗(yàn)證產(chǎn)物可用justfile 還提供了python-check目標(biāo)強(qiáng)制重裝 wheel 并執(zhí)行import goose冒煙測試以及python-publish目標(biāo)twine checktwine upload默認(rèn)發(fā)往 PyPI也可通過repository參數(shù)指定其他倉庫。Maven 包gdk artifactGoose 的 JVM/Kotlin 側(cè)產(chǎn)物發(fā)布在 Maven Central坐標(biāo)為io.github.aaif-goose:gdk版本號(hào)直接跟隨 Rust crate 的版本當(dāng)前為 Cargo.toml 中的0.1.0-alpha.7。本地構(gòu)建命令just --justfile crates/goose-sdk/justfile maven-package這條命令對(duì)應(yīng)maven-package→maven-bindings release→crates/goose-sdk/scripts/prepare-maven-package.sh→./gradlew publishToMavenLocal。它同樣先以 release 模式構(gòu)建原生庫然后調(diào)用 prepare-maven-package.sh 腳本重新生成 Kotlin 綁定UniFFI 生成 Kotlin 代碼并放入maven/src/main/kotlin把原生庫放入 JVM jar 的資源目錄maven/src/main/resources在 maven 目錄下用 Gradle 執(zhí)行publishToMavenLocal發(fā)布到本地 Maven 倉庫。CI 負(fù)責(zé)為受支持的平臺(tái)構(gòu)建原生庫并可選擇把整合后的產(chǎn)物發(fā)布到 Maven Central對(duì)應(yīng) justfile 中的maven-publish目標(biāo)。Kotlin 示例工程examples/uniffi/kotlin依賴本地發(fā)布的gdk產(chǎn)物這也是just kotlin能直接運(yùn)行示例的前提。版本、路徑與構(gòu)建入口速查項(xiàng)目說明位置Rust crategoose-sdk版本0.1.0-alpha.7Cargo.tomlUniFFI 配置綁定生成參數(shù)uniffi.tomlRust 源碼重導(dǎo)出 / 綁定 / 可觀測性src/lib.rs、src/bindings.rs、src/observability.rs構(gòu)建任務(wù)python、kotlin、python-wheel、python-publish、maven-package、maven-publish等justfile示例ACP 客戶端示例、聲明式 Provider JSONexamples/acp_client.rs、examples/deepseek.jsonPython 示例 / Kotlin 示例流式補(bǔ)全的跨語言對(duì)照examples/uniffi/provider.py、examples/uniffi/kotlin/src/main/kotlin/Main.kt小結(jié)goose-sdk 是 goose 生態(tài)中連接“Rust 核心實(shí)現(xiàn)”與“多語言調(diào)用方”的樞紐默認(rèn)特性下它提供構(gòu)建 ACP 客戶端所需的共享線協(xié)議類型啟用uniffi特性后它把 Provider 構(gòu)造、流式/非流式補(bǔ)全、上下文壓縮等能力以命名空間goosePython與io.github.aaif_gooseKotlin的形式原樣輸出并通過ObservabilityHook提供默認(rèn)關(guān)閉、負(fù)載可選、語義嚴(yán)格恰好一次onRequestEnd、可關(guān)聯(lián)的requestId的請(qǐng)求生命周期觀測。對(duì)想要在自有應(yīng)用里嵌入 goose 能力的開發(fā)者來說just python/just kotlin是零成本體驗(yàn)入口python-wheel/maven-package則是把 GDK 接入自己構(gòu)建鏈的標(biāo)準(zhǔn)姿勢(shì)。【免費(fèi)下載鏈接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM項(xiàng)目地址: https://gitcode.com/GitHub_Trending/goose3/goose創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考