GDK 参考
GDK 是一组 Rust crate。按需使用应用需要的 crate，或使用 goose-sdk 提供的 Python 和 Kotlin 绑定。
Crate
每个 crate 都链接到它在 docs.rs 上生成的 Rust 文档。
goose-agent
智能体运行时：由一组有序的操作和推理步骤构成的状态机。每个步骤可以检查对话、产生效果，或把控制权交给应用。StateMachine 可以替你运行整个序列，也可以让你逐步驱动。工作进行时事件会流式发出，取消时会收尾被中断的步骤和未答复的工具请求。
如果你想自己组装智能体，而不是运行完整的 goose 应用，就用这个 crate。InferenceRunner 把状态机接到模型提供商，ToolOperation 暴露并执行你的类型化工具。你提供会话类型、SessionLoader 和 EffectHandler，这样存储和应用特有的行为都由你掌控。持久化由你的运行时提供，而不是内嵌数据库。核心也支持 WebAssembly 宿主，平台差异见 crate 文档。
goose-provider-types
应用与模型后端之间的通用语言。它定义了 Provider trait、ModelConfig、Conversation、消息及其内容、工具请求和响应、token 用量以及提供商错误。它还提供共享的模型元数据，以及处理上下文限制、提示缓存和推理内容的辅助功能，这些概念不必为每个提供商换一种表示。
如果你在实现提供商，或者处理 GDK 消息但不需要提供商实现和智能体运行时，就依赖这个 crate。提供商通过 MessageStream 实现流式传输；默认的 complete 方法把流收集成一条消息和用量。文本可以增量到达，工具调用则在参数组装完成后发出。如果你还需要可用的后端，goose-providers 会重新导出这些模块。
goose-providers
模型后端的实现。它包含 OpenAI、Anthropic、Google Gemini、Azure AI Foundry 和 Databricks 等服务的提供商，以及 Ollama 和兼容 OpenAI 的端点。它们把各服务特有的请求和响应转换成共享的提供商接口。配套的 ApiClient 处理 HTTP 请求和认证，共享辅助功能负责响应错误和请求格式化。你可以直接使用这些提供商，不必构建智能体。
许多兼容服务可以通过声明式 JSON 定义来配置，定义中选择引擎、端点、配置键和模型。使用内置定义或加载你自己的定义即可，不用再写一个提供商实现。可选特性会添加本地推理及其硬件后端；实时会话和语音接口支持文本补全之外的应用，并可选用 WebSocket 传输。要使用原生 HTTPS 连接，请启用 rustls-tls 或 native-tls；两者默认都不启用。
goose-context-management
为即将超出模型上下文窗口的历史提供摘要和对话压缩。summarize 把一段消息变成一条摘要消息，并记录模型用量。更高层的 compact 函数通过 CompactionInput 和 CompactionOutput 读写，因此应用可以保留自己的对话表示和存储。
用 ProviderModel 可以借助现有的 GDK 提供商做摘要，也可以实现 CompactionModel 自行控制模型选择。提示模板和可选的 TokenEstimator 用于调整摘要并限制其输入；这个 crate 还定义了带文件活动的结构化摘要。作为更简单的兜底方案，CompactingProvider 包装一个提供商，遇到上下文长度错误时用摘要后的历史重试一次。压缩不依赖智能体状态机，基于 trait 的 API 把保存结果的工作留给你的应用。
goose-local-inference
在用户的机器上运行模型，对 GGUF 模型使用 llama.cpp，在 Apple 芯片上可选用 MLX 后端。它负责加载模型、共享已加载的实例、将其逐出内存，以及应用聊天模板。它还解析模型输出（包括工具调用和推理块），并为支持的模型处理图像输入。这是推理引擎，而不是需要应用另行启动的模型服务器。
通过 goose-providers 的 local-inference 特性使用它，可以得到 LocalInferenceProvider，它实现与远程后端相同的 Provider 接口。模型可以从本地路径加载；可选的 hf-hub 特性增加了 Hugging Face 发现、下载、缓存清单和模型管理 API。CUDA、Vulkan 和 MLX 通过特性选择。这些后端有原生构建要求，能运行哪些模型取决于可用内存和硬件。
goose-download-manager
在后台下载模型文件，并提供应用可以展示的进度。DownloadManager 按模型 ID 跟踪任务，并提供状态、已下载字节数、总大小、速度、预计剩余时间和错误。它支持单个文件和成组的模型分片，提供跨文件的合并进度、取消和可选的完成回调。
下载器写入临时的部分文件，用 HTTP range 请求续传，对瞬时故障重试，完成后把文件重命名到位。支持 Bearer token，可以从需要认证的端点获取文件。如果应用已经知道下载 URL 和目标路径，就用这个 crate。模型发现和缓存清单属于 goose-local-inference 中的 hf-hub 层；下载管理器本身不选择模型，也不加载模型进行推理。
goose-sdk-types
goose 对 ACP 扩展部分的共享线路类型。其中的请求、响应和通知类型描述 _goose/* 下的方法，包括扩展和工具管理、提供商配置、配方以及本地模型管理。自定义通知与标准 ACP 事件一起传递会话用量、状态消息、逐条消息耗时和提供商认证更新等信息。
如果 Rust 代码需要交换这些 goose 特有的消息，又不想依赖 goose 应用，就用这个 crate。这些类型包含序列化和 JSON schema 定义，让服务器、客户端和生成文档的线路格式集中在一处。它不会启动智能体，也不建立连接：传输和标准协议方法请用 ACP 客户端库，额外的方法见 goose ACP 参考。
goose-sdk
跨语言绑定包，也是共享线路类型的一个小型 Rust 入口。启用默认特性时，它从 goose-sdk-types 重新导出 custom_requests 和 custom_notifications。它不是会自动组装智能体或暴露全部 GDK 组件的总括 crate；构建进程内运行时的 Rust 应用请使用上面的组件 crate。
可选的 uniffi 特性把原生 API 暴露给 Python 和 Kotlin。这些绑定可以构造提供商、列出模型、发送类型化的消息和工具内容、流式或一次性获取补全，以及压缩对话。它们还包含类型化的决策请求和提供商调用的可观测性钩子。这是对原生库的进程内访问，而不是连接到运行中的 goose 进程。完整的智能体状态机没有通过这些绑定暴露；可用的 API 见下面生成的各语言参考。
API 文档
对于编码智能体或其他不运行 JavaScript 的客户端，请使用生成的 Python Markdown 参考或 Kotlin Markdown 参考。两者都包含方法锚点和指向带版本 API 快照的链接。
Python 和 Kotlin 绑定目前暴露模型提供商、流式补全和对话压缩，不暴露 Rust 中可用的完整智能体运行时。
请选择与你的依赖相匹配的文档版本。GDK 处于 alpha 阶段；API 可能在版本之间变化。