goose 离线/隔离网络文档GOOSE_DOCS_ROOT 让 goose-doc-guide 技能读取本地文档库的完整指南【免费下载链接】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 内置的goose-doc-guide技能如何在离线offline或气隙air-gapped网络环境中工作展开当默认文档站点https://goose-docs.ai无法访问时如何通过GOOSE_DOCS_ROOT把 goose 指向一份本地文档副本使其无需任何网络访问即可回答问题。读完本文你将掌握 docs 根目录的结构约定、从仓库构建本地文档库的完整流程、config.yaml与环境变量两种配置方式以及GOOSE_DOCS_ROOT在 goose 源码中的解析与占位符替换机制。背景goose-doc-guide 技能为什么需要本地文档goose 在回答涉及 goose 自身特性的问题时会先阅读官方文档而不是依赖训练数据或猜测。这一行为由一个内置技能builtin skillgoose-doc-guide驱动其技能定义文件位于 crates/goose/src/skills/builtins/goose_doc_guide.md技能描述明确指出Reference goose documentation to create, configure, or explain goose-specific features like recipes, extensions, sessions, and providers. You MUST read the relevant goose docs before answering. You MUST NOT rely on training data or assumptions...即凡是涉及 goose 专属配置项、字段名、语法、命令的内容必须先查阅官方文档再作答。该技能适用于创建/编辑 recipe、配置扩展或 provider、解释 goose 功能等工作对于与 goose 无关的通用编码任务则不应启用。从技能正文看goose 会在会话启动时注入当前会话的文档根目录正文原文为The docs root for this session is {{GOOSE_DOCS_ROOT}}. It may be a local filesystem path or an HTTP(S) URL...其中{{GOOSE_DOCS_ROOT}}是一个占位符会在技能加载时被替换为实际配置值详见下文占位符替换机制。技能执行步骤Steps也严格约束了读取行为先读取docs-root/goose-docs-map.md这份文档地图索引在地图中搜索与用户主题相关的页面路径只允许读取地图中显式列出的路径不得猜测或推断路径多篇文档并行读取并保存到临时文件后续搜索基于临时文件而非重复读取回答时必须逐项对照官方 schema/文档校验字段名、必填项与值格式结尾需要包含 Verification Completed 部分并对每个 goose 专属条目给出具体文档来源。这意味着只要让{{GOOSE_DOCS_ROOT}}指向一份包含goose-docs-map.md与docs/树的本地目录整个文档查询链路就可以完全脱离网络运行。GOOSE_DOCS_ROOT 的解析规则与占位符替换机制配置读取config.yaml 或环境变量GOOSE_DOCS_ROOT既可在 goose 的config.yaml中设置也可作为进程环境变量提供。它的读取逻辑实现在 crates/goose/src/config/base.rspub fn get_goose_docs_root(self) - ResultOptionString, ConfigError { match self.get_param::String(GOOSE_DOCS_ROOT) { Ok(root) Ok(Some(root.trim().to_string()).filter(|root| !root.is_empty())), Err(ConfigError::NotFound(_)) Ok(None), Err(e) Err(e), } }源码揭示了三个细节行为返回值经过trim()处理纯空白值会被过滤成None即视为未设置只有当该参数完全不存在时才返回None之后由上层决定回退逻辑通过统一的get_param读取因此环境变量与config.yaml两种来源都会被识别。同一文件中的单元测试完整覆盖了这些场景crates/goose/src/config/base.rsget_goose_docs_root_reads_config_file从配置文件读取/tmp/goose-docsget_goose_docs_root_reads_env_value从环境变量读取/tmp/env-docsget_goose_docs_root_returns_none_when_unset未设置时返回Noneget_goose_docs_root_ignores_blank_value值为 纯空白时同样返回None。占位符替换{{GOOSE_DOCS_ROOT}} 如何变成真实路径技能加载时执行占位符替换核心逻辑位于 crates/goose/src/skills/mod.rsconst DEFAULT_GOOSE_DOCS_ROOT: str https://goose-docs.ai; const GOOSE_DOCS_ROOT_PLACEHOLDER: str {{GOOSE_DOCS_ROOT}}; fn resolve_docs_root_placeholder(skill: SourceEntry, content: str, docs_root: str) - String { if skill.name ! goose-doc-guide || skill.source_type ! SourceType::BuiltinSkill { return content.to_string(); } content.replace(GOOSE_DOCS_ROOT_PLACEHOLDER, docs_root) } fn loaded_skill_context(skill: SourceEntry, content: str) - ResultString { let docs_root Config::global() .get_goose_docs_root()? .unwrap_or_else(|| DEFAULT_GOOSE_DOCS_ROOT.to_string()); let content resolve_docs_root_placeholder(skill, content, docs_root); // ... }DEFAULT_GOOSE_DOCS_ROOT常量即默认在线文档根https://goose-docs.ai。整个解析是**确定性deterministic**的若GOOSE_DOCS_ROOT已配置则使用配置值否则回退到在线默认值。替换只针对名称为goose-doc-guide的内置技能其他技能内容不受影响。当根目录是本地文件系统路径时goose 直接使用文件工具file/shell tools读取文档全程无需网络当值为 HTTP(S) URL 时则通过网络获取。文档根目录docs root的结构约定无论在线还是离线goose 期望的文档根目录结构是固定的docs-root/ ├── goose-docs-map.md └── docs/ ├── getting-started/... └── guides/...goose-docs-map.md文档地图索引是goose-doc-guide技能最先搜索的文件。技能只会读取其中列出的页面路径例如地图中若显示docs/guides/sessions/session-management.md技能就读取docs-root/docs/guides/sessions/session-management.mddocs/树实际的 Markdown 文档正文按getting-started/、guides/等目录组织。该约束也见于 goose 全局配置文档documentation/docs/guides/config-files.md 与 documentation/docs/guides/environment-variables.md两处对GOOSE_DOCS_ROOT的定义一致——Documentation root used bygoose-doc-guide(e.g. for offline/air-gapped docs)取值为Local path or HTTP(S) URL containinggoose-docs-map.mdanddocs/默认值为https://goose-docs.ai。构建本地文档根在有网环境下用同一版本源码构建构建本地文档库应使用与当前 goose 二进制相同版本的源码以确保文档内容与运行时代码匹配git checkout v1.41.0 # match your goose binary version cd documentation npm run build版本号仅为示例实际请替换为与你 goose 二进制一致的 tag 或 commit。查看 documentation/package.json 的build脚本可以确认构建流程build: node scripts/generate-docs-map.js docusaurus build即先执行 documentation/scripts/generate-docs-map.js 生成文档地图该脚本将索引写入static/goose-docs-map.md从而被 Docusaurus 一并拷入构建产物再执行标准的docusaurus build。因此——正如原文档所指出的——标准的文档构建流程已经产出 goose 需要的全部内容一份goose-docs-map.md索引加一棵docs/Markdown 树无需任何自定义工具链。构建完成后产物位于documentation/build/build/ ├── goose-docs-map.md └── docs/ ├── getting-started/... └── guides/...由于npm run build需要下载依赖registry access必须在联网环境执行。随后把整个build/目录复制到气隙目标位置例如/opt/goose-docs再将GOOSE_DOCS_ROOT指向该目录即可。配置 gooseconfig.yaml 或环境变量二选一方式一写入 config.yaml在 goose 的config.yaml中增加一行GOOSE_DOCS_ROOT: /opt/goose-docs方式二通过环境变量导出export GOOSE_DOCS_ROOT/opt/goose-docs两种方式等价因为 goose 统一通过Config::get_param(GOOSE_DOCS_ROOT)读取见 crates/goose/src/config/base.rs。若同时设置最终生效值取决于 goose 环境变量与配置文件的分层优先级约定可参考 documentation/docs/guides/config-files.md 中的详细说明。托管发行版managed distribution场景对于需要分发给多台离线主机的托管发行版例如镜像打包场景建议在镜像构建阶段把构建好的docs/树烘焙bake进镜像在镜像自带的config.yaml或启动器launcher环境中设置GOOSE_DOCS_ROOT。这样每台主机启动 goose 时都会自动指向内置的本地文档用户无需任何额外配置。验证配置是否生效配置完成后可以结合以下线索验证技能内容在加载时已完成占位符替换可通过 goose 会话中技能加载上下文确认docs-root指向了本地路径源码逻辑见 crates/goose/src/skills/mod.rs 的loaded_skill_contextgoose-doc-guide技能会先尝试读取docs-root/goose-docs-map.md。若本地根目录中缺少该文件技能将无法定位任何文档页面由于技能只读取地图中显式列出的路径本地docs/树与goose-docs-map.md必须来自同一次构建避免出现地图指向的路径在树中不存在的情况。关键行为与注意事项回答中的链接始终渲染为规范化 URL即使文档是本地读取的goose 回答中给出的文档链接仍会以https://goose-docs.ai/...形式呈现技能正文亦要求 Always link to the canonical site https://goose-docs.ai/, even if you read the docs from a local path. Never expose local filesystem paths.不会暴露本地文件路径。HTTP(S) 镜像同样可行GOOSE_DOCS_ROOT不限于本地路径也可以指向自定义的 HTTP(S) 镜像根 URL例如内网部署的文档站点https://docs.internal.example/goose-docs。本地读取模式当根是本地路径时goose 用其文件工具读取文档不产生网络请求——这正是气隙环境可用的根本原因。默认回退未设置GOOSE_DOCS_ROOT时回退到DEFAULT_GOOSE_DOCS_ROOThttps://goose-docs.ai此时需要网络可达。环境变量值清理配置值会先trim()纯空白视为未设置因此配置文件中不要残留空值或多余空格。关联排障气隙环境下的 MCP 扩展问题离线环境的问题不止于文档读取。如果 MCP server 扩展无法激活或下载运行时依赖报错常含hermit:fatal、Failed to start extension等可参考 documentation/docs/troubleshooting/known-issues.md 中的Airgapped/Offline Environment Issues小节。其核心思路是goose Desktop 用打包的npx/uvxshim 自动下载运行时受限网络中该下载会失败可以通过创建自定义命名的命令如把uvx链接为runuv、把npx链接为runnpx并在扩展配置中改用这些自定义名绕过 goose 的 shim 机制直接调用系统真实的可执行文件——因为 goose 只替换已知命令名npx、uvx、jbang等自定义名会原样透传。该文档也在Documentation access段落中明确指向本文所述方案作为离线文档读取的官方入口。小结三步完成离线文档接入构建在联网机器上git checkout 你的版本 cd documentation npm run build得到含goose-docs-map.md与docs/树的build/目录搬运把build/复制到气隙目标位置例如/opt/goose-docs托管发行版则烘焙进镜像指向在config.yaml或环境变量中设置GOOSE_DOCS_ROOT指向该根目录goose 便会在不访问https://goose-docs.ai的情况下通过文件工具读取本地官方文档保证 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 goose 离线/隔离网络文档：GOOSE_DOCS_ROOT 让 goose-doc-guide 技能读取本地文档库的完整指南
goose 离线/隔离网络文档GOOSE_DOCS_ROOT 让 goose-doc-guide 技能读取本地文档库的完整指南【免费下载链接】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 内置的goose-doc-guide技能如何在离线offline或气隙air-gapped网络环境中工作展开当默认文档站点https://goose-docs.ai无法访问时如何通过GOOSE_DOCS_ROOT把 goose 指向一份本地文档副本使其无需任何网络访问即可回答问题。读完本文你将掌握 docs 根目录的结构约定、从仓库构建本地文档库的完整流程、config.yaml与环境变量两种配置方式以及GOOSE_DOCS_ROOT在 goose 源码中的解析与占位符替换机制。背景goose-doc-guide 技能为什么需要本地文档goose 在回答涉及 goose 自身特性的问题时会先阅读官方文档而不是依赖训练数据或猜测。这一行为由一个内置技能builtin skillgoose-doc-guide驱动其技能定义文件位于 crates/goose/src/skills/builtins/goose_doc_guide.md技能描述明确指出Reference goose documentation to create, configure, or explain goose-specific features like recipes, extensions, sessions, and providers. You MUST read the relevant goose docs before answering. You MUST NOT rely on training data or assumptions...即凡是涉及 goose 专属配置项、字段名、语法、命令的内容必须先查阅官方文档再作答。该技能适用于创建/编辑 recipe、配置扩展或 provider、解释 goose 功能等工作对于与 goose 无关的通用编码任务则不应启用。从技能正文看goose 会在会话启动时注入当前会话的文档根目录正文原文为The docs root for this session is {{GOOSE_DOCS_ROOT}}. It may be a local filesystem path or an HTTP(S) URL...其中{{GOOSE_DOCS_ROOT}}是一个占位符会在技能加载时被替换为实际配置值详见下文占位符替换机制。技能执行步骤Steps也严格约束了读取行为先读取docs-root/goose-docs-map.md这份文档地图索引在地图中搜索与用户主题相关的页面路径只允许读取地图中显式列出的路径不得猜测或推断路径多篇文档并行读取并保存到临时文件后续搜索基于临时文件而非重复读取回答时必须逐项对照官方 schema/文档校验字段名、必填项与值格式结尾需要包含 Verification Completed 部分并对每个 goose 专属条目给出具体文档来源。这意味着只要让{{GOOSE_DOCS_ROOT}}指向一份包含goose-docs-map.md与docs/树的本地目录整个文档查询链路就可以完全脱离网络运行。GOOSE_DOCS_ROOT 的解析规则与占位符替换机制配置读取config.yaml 或环境变量GOOSE_DOCS_ROOT既可在 goose 的config.yaml中设置也可作为进程环境变量提供。它的读取逻辑实现在 crates/goose/src/config/base.rspub fn get_goose_docs_root(self) - ResultOptionString, ConfigError { match self.get_param::String(GOOSE_DOCS_ROOT) { Ok(root) Ok(Some(root.trim().to_string()).filter(|root| !root.is_empty())), Err(ConfigError::NotFound(_)) Ok(None), Err(e) Err(e), } }源码揭示了三个细节行为返回值经过trim()处理纯空白值会被过滤成None即视为未设置只有当该参数完全不存在时才返回None之后由上层决定回退逻辑通过统一的get_param读取因此环境变量与config.yaml两种来源都会被识别。同一文件中的单元测试完整覆盖了这些场景crates/goose/src/config/base.rsget_goose_docs_root_reads_config_file从配置文件读取/tmp/goose-docsget_goose_docs_root_reads_env_value从环境变量读取/tmp/env-docsget_goose_docs_root_returns_none_when_unset未设置时返回Noneget_goose_docs_root_ignores_blank_value值为 纯空白时同样返回None。占位符替换{{GOOSE_DOCS_ROOT}} 如何变成真实路径技能加载时执行占位符替换核心逻辑位于 crates/goose/src/skills/mod.rsconst DEFAULT_GOOSE_DOCS_ROOT: str https://goose-docs.ai; const GOOSE_DOCS_ROOT_PLACEHOLDER: str {{GOOSE_DOCS_ROOT}}; fn resolve_docs_root_placeholder(skill: SourceEntry, content: str, docs_root: str) - String { if skill.name ! goose-doc-guide || skill.source_type ! SourceType::BuiltinSkill { return content.to_string(); } content.replace(GOOSE_DOCS_ROOT_PLACEHOLDER, docs_root) } fn loaded_skill_context(skill: SourceEntry, content: str) - ResultString { let docs_root Config::global() .get_goose_docs_root()? .unwrap_or_else(|| DEFAULT_GOOSE_DOCS_ROOT.to_string()); let content resolve_docs_root_placeholder(skill, content, docs_root); // ... }DEFAULT_GOOSE_DOCS_ROOT常量即默认在线文档根https://goose-docs.ai。整个解析是**确定性deterministic**的若GOOSE_DOCS_ROOT已配置则使用配置值否则回退到在线默认值。替换只针对名称为goose-doc-guide的内置技能其他技能内容不受影响。当根目录是本地文件系统路径时goose 直接使用文件工具file/shell tools读取文档全程无需网络当值为 HTTP(S) URL 时则通过网络获取。文档根目录docs root的结构约定无论在线还是离线goose 期望的文档根目录结构是固定的docs-root/ ├── goose-docs-map.md └── docs/ ├── getting-started/... └── guides/...goose-docs-map.md文档地图索引是goose-doc-guide技能最先搜索的文件。技能只会读取其中列出的页面路径例如地图中若显示docs/guides/sessions/session-management.md技能就读取docs-root/docs/guides/sessions/session-management.mddocs/树实际的 Markdown 文档正文按getting-started/、guides/等目录组织。该约束也见于 goose 全局配置文档documentation/docs/guides/config-files.md 与 documentation/docs/guides/environment-variables.md两处对GOOSE_DOCS_ROOT的定义一致——Documentation root used bygoose-doc-guide(e.g. for offline/air-gapped docs)取值为Local path or HTTP(S) URL containinggoose-docs-map.mdanddocs/默认值为https://goose-docs.ai。构建本地文档根在有网环境下用同一版本源码构建构建本地文档库应使用与当前 goose 二进制相同版本的源码以确保文档内容与运行时代码匹配git checkout v1.41.0 # match your goose binary version cd documentation npm run build版本号仅为示例实际请替换为与你 goose 二进制一致的 tag 或 commit。查看 documentation/package.json 的build脚本可以确认构建流程build: node scripts/generate-docs-map.js docusaurus build即先执行 documentation/scripts/generate-docs-map.js 生成文档地图该脚本将索引写入static/goose-docs-map.md从而被 Docusaurus 一并拷入构建产物再执行标准的docusaurus build。因此——正如原文档所指出的——标准的文档构建流程已经产出 goose 需要的全部内容一份goose-docs-map.md索引加一棵docs/Markdown 树无需任何自定义工具链。构建完成后产物位于documentation/build/build/ ├── goose-docs-map.md └── docs/ ├── getting-started/... └── guides/...由于npm run build需要下载依赖registry access必须在联网环境执行。随后把整个build/目录复制到气隙目标位置例如/opt/goose-docs再将GOOSE_DOCS_ROOT指向该目录即可。配置 gooseconfig.yaml 或环境变量二选一方式一写入 config.yaml在 goose 的config.yaml中增加一行GOOSE_DOCS_ROOT: /opt/goose-docs方式二通过环境变量导出export GOOSE_DOCS_ROOT/opt/goose-docs两种方式等价因为 goose 统一通过Config::get_param(GOOSE_DOCS_ROOT)读取见 crates/goose/src/config/base.rs。若同时设置最终生效值取决于 goose 环境变量与配置文件的分层优先级约定可参考 documentation/docs/guides/config-files.md 中的详细说明。托管发行版managed distribution场景对于需要分发给多台离线主机的托管发行版例如镜像打包场景建议在镜像构建阶段把构建好的docs/树烘焙bake进镜像在镜像自带的config.yaml或启动器launcher环境中设置GOOSE_DOCS_ROOT。这样每台主机启动 goose 时都会自动指向内置的本地文档用户无需任何额外配置。验证配置是否生效配置完成后可以结合以下线索验证技能内容在加载时已完成占位符替换可通过 goose 会话中技能加载上下文确认docs-root指向了本地路径源码逻辑见 crates/goose/src/skills/mod.rs 的loaded_skill_contextgoose-doc-guide技能会先尝试读取docs-root/goose-docs-map.md。若本地根目录中缺少该文件技能将无法定位任何文档页面由于技能只读取地图中显式列出的路径本地docs/树与goose-docs-map.md必须来自同一次构建避免出现地图指向的路径在树中不存在的情况。关键行为与注意事项回答中的链接始终渲染为规范化 URL即使文档是本地读取的goose 回答中给出的文档链接仍会以https://goose-docs.ai/...形式呈现技能正文亦要求 Always link to the canonical site https://goose-docs.ai/, even if you read the docs from a local path. Never expose local filesystem paths.不会暴露本地文件路径。HTTP(S) 镜像同样可行GOOSE_DOCS_ROOT不限于本地路径也可以指向自定义的 HTTP(S) 镜像根 URL例如内网部署的文档站点https://docs.internal.example/goose-docs。本地读取模式当根是本地路径时goose 用其文件工具读取文档不产生网络请求——这正是气隙环境可用的根本原因。默认回退未设置GOOSE_DOCS_ROOT时回退到DEFAULT_GOOSE_DOCS_ROOThttps://goose-docs.ai此时需要网络可达。环境变量值清理配置值会先trim()纯空白视为未设置因此配置文件中不要残留空值或多余空格。关联排障气隙环境下的 MCP 扩展问题离线环境的问题不止于文档读取。如果 MCP server 扩展无法激活或下载运行时依赖报错常含hermit:fatal、Failed to start extension等可参考 documentation/docs/troubleshooting/known-issues.md 中的Airgapped/Offline Environment Issues小节。其核心思路是goose Desktop 用打包的npx/uvxshim 自动下载运行时受限网络中该下载会失败可以通过创建自定义命名的命令如把uvx链接为runuv、把npx链接为runnpx并在扩展配置中改用这些自定义名绕过 goose 的 shim 机制直接调用系统真实的可执行文件——因为 goose 只替换已知命令名npx、uvx、jbang等自定义名会原样透传。该文档也在Documentation access段落中明确指向本文所述方案作为离线文档读取的官方入口。小结三步完成离线文档接入构建在联网机器上git checkout 你的版本 cd documentation npm run build得到含goose-docs-map.md与docs/树的build/目录搬运把build/复制到气隙目标位置例如/opt/goose-docs托管发行版则烘焙进镜像指向在config.yaml或环境变量中设置GOOSE_DOCS_ROOT指向该根目录goose 便会在不访问https://goose-docs.ai的情况下通过文件工具读取本地官方文档保证 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考