企业官网建设流程全解析

如何 fork goose 构建预配置提供商与捆绑扩展的自定义发行版？

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose

假设你要为自己的组织分发一个定制版 goose：开箱即用某个指定的 AI 提供商（本地模型或托管 API 端点），并且预装若干内部 MCP 扩展，用户无需自己配置。goose 官方把它称为"custom distribution"（也叫 white labelling），并且明确设计上就是支持 fork 定制的。本文按照 CUSTOM_DISTROS.md 给出的路径，走一条最短的连续操作链：fork → 预配置提供商 → 捆绑扩展 → 构建桌面应用 → 验证产物。网页版指南 documentation/docs/guides/custom-distributions.md 也指出：构建自定义发行版需要工作到代码级别，所以完整指南放在仓库根目录。

准备：Fork 并克隆

先在 goose 的托管平台把仓库 fork 到你自己的组织下，然后克隆这个 fork（YOUR_ORG替换为你的组织名，这是文档中的原始命令）：

git clone https://github.com/YOUR_ORG/goose.git cd goose

克隆后先确定定制策略。文档把定制分为三档，本文只涉及前两档：

• Configuration-only：只改配置文件和环境变量，不改代码——预配置提供商走这条路，复杂度 Low；
• Extension-based：以自定义 MCP server 的形式加入你的工具，核心改动最小——捆绑扩展走这条路，复杂度 Medium；
• Deep customization：改核心行为、UI 或新增 provider 实现，本文不展开。

定制点与位置速查（来自文档的 Key Customization Points 表）：

预配置 AI 提供商

最短路径：init-config.yaml + 环境变量

以"开箱即用本地 Ollama 模型、不需要 API key"为例（文档 Scenario A）：

1. 在发行版根目录创建init-config.yaml。文档说明它是"Applied on first run if no config exists"——即首次运行且尚不存在配置时应用：

# init-config.yaml - Applied on first run if no config exists GOOSE_PROVIDER: ollama GOOSE_MODEL: qwen3-coder:latest

2. 在启动脚本或打包环节设置环境变量默认值：

export GOOSE_PROVIDER=ollama export GOOSE_MODEL=qwen3-coder:latest export OLLAMA_HOST=http://localhost:11434 # Or your hosted instance

3. 可选：修改ui/desktop/src/下的组件，在 UI 中隐藏提供商选择入口。

关于生效顺序，文档给出明确说明：Config precedence: Environment variables → config.yaml → defaults，即环境变量优先于config.yaml，二者再覆盖内置默认值。相关实现见 crates/goose/src/config/base.rs（其中也包含init-config.yaml的首次运行加载逻辑）与 Ollama 提供商实现 crates/goose/src/providers/ollama.rs。

可选分支 A：托管 API key（企业内部分发）

如果你的发行版是"内部预置 frontier 模型 API key"（文档 Scenario B），配置同样写在随包分发的config.yaml中：

# config.yaml (distributed with your package) GOOSE_PROVIDER: anthropic GOOSE_MODEL: claude-sonnet-4-20250514

密钥不放进配置文件，而是在安装时或通过 MDM/配置管理注入，使用 goose 自带的密钥管理命令：

# Secrets are stored in system keyring or ~/.config/goose/secrets.yaml # if GOOSE_DISABLE_KEYRING=1 goose configure set-secret ANTHROPIC_API_KEY "your-corporate-key"

按文档说明，secret 默认存系统 keyring；设置GOOSE_DISABLE_KEYRING=1时回退到~/.config/goose/secrets.yaml文件存储。

可选分支 B：自托管端点用声明式 JSON provider

如果你的端点是内部 LLM 网关，文档提供无需写代码的方案：在~/.config/goose/custom_providers/创建 JSON，或直接捆绑在发行版内（Scenario G，Option 1）：

{ "name": "my_provider", "engine": "openai", "display_name": "My Custom Provider", "description": "Our internal LLM endpoint", "api_key_env": "MY_PROVIDER_API_KEY", "base_url": "https://llm.internal.company.com/v1/chat/completions", "models": [ { "name": "company-llm-v1", "context_limit": 32768 } ], "supports_streaming": true, "requires_auth": true }

其中base_url、api_key_env、models都要换成你自己端点的实际值。文档说明支持的engine为：openai、anthropic、ollama。只有当 API 形态无法被这三种 engine 覆盖时，才需要走 Option 2：新建文件实现Providertrait（crates/goose/src/providers/base.rs）并在 provider 注册处登记，属于代码级定制。

捆绑自定义 MCP 扩展

以"让发行版内置一个连接内部数据源的 stdio 扩展"为例（文档 Scenario C），分两步。

第一步是实现你的 MCP server。文档给出的 Python 示例（mcp.server的Server+@server.tool()装饰器）只是骨架，query_data_lake函数体需要你自己实现，需遵循 MCP 规范编写。

第二步是把该 server 声明为内置扩展，写入以下两个文件之一（两个文件均真实存在于本仓库）：

• ui/desktop/src/built-in-extensions.json——"core built-ins surfaced in extension UI"；
• ui/desktop/src/components/settings/extensions/bundled-extensions.json——Settings 中的捆绑扩展目录（bundled extension catalog）。

文档给出的条目示例：

{ "id": "internal-data", "name": "Internal Data Lake", "description": "Query corporate data sources", "enabled": true, "type": "stdio", "cmd": "python", "args": ["/path/to/internal_data_mcp.py"], "env_keys": ["INTERNAL_DATA_API_KEY"], "timeout": 300 }

args中的/path/to/internal_data_mcp.py是占位路径，替换为你发行版中 MCP 脚本的实际位置；env_keys列出需要注入给该 server 的环境变量名（这里示意的是内部数据源的 API key 变量名，按你的实际变量调整）。

另一种分发方式是用 recipe 来启用扩展（文档data-analyst.yaml示例的核心片段）：

extensions: - type: stdio name: internal-data cmd: python args: ["/opt/corp-goose/internal_data_mcp.py"] description: Corporate data lake access

两条路径的关系：直接写进built-in-extensions.json/bundled-extensions.json是"发行版级捆绑"，用户在 Settings 扩展目录中直接看到；recipe 方式则把扩展与指令、参数打包成可分发的 YAML 文件。文档指明的相关实现位置：扩展配置类型为 crates/goose/src/agents/extension.rs（ExtensionConfig），扩展加载在 crates/goose/src/agents/extension_manager.rs，内置 MCP server 代码在 crates/goose-mcp/。

构建并验证发行版（Linux 桌面路径）

以下构建步骤来自 BUILDING_LINUX.md，以 Debian/Ubuntu 为例。

准备条件

• Rust（通过 rustup 安装）、Node.js 22.9.0 或更高版本、pnpm 10 或更高版本、just（cargo install just）；
• 系统构建依赖。以下命令需要 sudo 权限，会向系统安装编译器与图形/Vulkan 头文件等构建包：

sudo apt update sudo apt install -y dpkg fakeroot build-essential clang libxcb1-dev libxcb-util-dev protobuf-compiler libvulkan-dev libvulkan1 glslc

Arch、Fedora、openSUSE 的对应包列表见 BUILDING_LINUX.md 的 Prerequisites 一节。

构建步骤

先构建后端二进制，再把 goose 二进制放进桌面应用期望的位置：

cargo build --release -p goose-cli --bin goose cd ui/desktop pnpm install # Copy the goose binary to the expected location mkdir -p src/bin cp ../../target/release/goose src/bin/

然后打包（在ui/desktop目录下执行）：

# Option A: ZIP 分发，文档标注为推荐，兼容所有 Linux 发行版 pnpm run make --targets=@electron-forge/maker-zip # Option B: DEB 包（Debian/Ubuntu） pnpm run make --targets=@electron-forge/maker-deb

验证

• ZIP 构建的产物路径文档写为out/make/zip/linux/x64/goose-linux-x64-{version}.zip，DEB 为out/make/deb/x64/goose_{version}_amd64.deb，其中{version}由构建时版本号填充，是路径模板而非固定文件名；
• 从构建目录直接运行验证应用可启动：./out/goose-linux-x64/goose；DEB 可用sudo dpkg -i out/make/deb/x64/goose_*.deb安装（需要 root 权限）；
• 若启动时报 "Goose binary not found"，文档给出的排查顺序是：确认已执行cargo build --release -p goose-cli --bin goose、已把二进制复制到src/bin/、然后重新pnpm run make；
• 扩展是否捆绑成功，对照 Settings 中的扩展目录检查：写入bundled-extensions.json的条目应出现在该目录中。

macOS/Windows 平台的构建说明见 ui/desktop/README.md。

合规与长期维护

• 许可：goose 采用 Apache License 2.0。自定义发行版必须保留原始 license 与版权声明、清楚标注所做的修改、且不得使用 "Goose" 商标暗示官方背书（见仓库 LICENSE）。
• 遥测：发行版可设置GOOSE_DISABLE_TELEMETRY=1关闭可选的 PostHog 遥测；也可以修改crates/goose/src/posthog.rs指向自己的 PostHog 实例。
• 持续跟进上游：定期把 fork 与主仓库同步；把定制隔离在配置文件、独立扩展仓库中；工作流定制优先用 recipe 而非改代码。文档提醒：私有 fork 偏离过远后维护成本会显著上升，并且会错过安全更新。

完成上述链条后，你得到的产物是一个可安装的应用包（ZIP 或 DEB）：首次运行即应用init-config.yaml预置的提供商与模型，Settings 扩展目录中列出捆绑的 stdio 扩展。文档没有为"提供商预配置"单独给出验证命令，可用的核对依据就是构建产物生成、应用可启动、以及 Settings 扩展列表中可见捆绑条目这三点。

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose