goose 文档自动化管线用「确定性脚本 AI Recipe」让 CLI 参考文档与代码自动同步【免费下载链接】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 仓库 documentation/automation/ 目录的官方文档与配套脚本源码讲解 goose 如何构建一套文档自动化管线在新版本发布时通过「构建二进制 → 解析--help→ 确定性 diff → AI 合成变更说明 → AI 外科手术式更新文档」五步流程自动检测 CLI 命令与选项的变更并把 CLI Commands Guide 保持与代码一致。读完后你可以完整理解这套「脚本负责确定性、AI 负责语义合成」的混合管线设计并能在本地或 GitHub Actions 中复现整条管线。文档自动化的总体设计goose 的 documentation/automation/ 目录存放一组自动化管线目标是「让 goose 文档与代码变更保持同步」。每个自动化项目追踪特定类型的代码变更并更新对应的文档项目状态追踪对象更新对象cli-command-trackingPlannedCLI 命令与选项CLI 文档provider-trackingPlanned受支持的 AI ProviderProvider 文档extension-trackingPlanned内置扩展扩展文档目前仓库中真正落地的完整案例是cli-command-tracking其余项目仍在规划中。所有自动化项目遵循统一的标准目录结构project-name/ ├── README.md # 项目专属文档 ├── TESTING.md # 该自动化如何测试 ├── config/ # 配置文件 ├── scripts/ # 确定性的抽取/diff 脚本 └── recipes/ # AI 驱动的合成/更新 recipe其设计原则可以概括为四点模块化每个项目自包含、可测试每阶段输入/输出清晰、透明中间文件可人工检查、可复用跨项目共用同一模式。而贯穿所有项目的核心手法是混合架构Hybrid ApproachShell/Python 脚本负责确定性的抽取与比对——构建二进制、运行--help、解析输出、JSON 结构比对全程不做任何解释与推断AI Recipe负责语义合成与文档更新——解释变更影响、生成迁移指引、以正确的格式更新文档。之所以这样划分是因为「抽取什么变了」必须是可复现的事实问题而「这变更对用户意味着什么、文档该怎么改」是需要语言理解的能力问题。两者通过 JSON/Markdown 中间文件解耦每一步都可以单独重跑、单独检查。CLI 命令追踪管线的架构cli-command-tracking/README.md 描述了管线的四阶段流水线目标是让 CLI Commands Guide 始终与代码同步┌─────────────────────────────────────────────────────────────────┐ │ EXTRACTION (确定性) │ ├─────────────────────────────────────────────────────────────────┤ │ extract-cli-structure.sh → extract-cli-structure.py │ │ ↓ │ │ cli-structure.json (commands, options, subcommands, aliases) │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ DIFFING (确定性) │ ├─────────────────────────────────────────────────────────────────┤ │ diff-cli-structures.py │ │ ↓ │ │ cli-changes.json (added, removed, modified commands/options) │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ SYNTHESIS (AI 驱动) │ ├─────────────────────────────────────────────────────────────────┤ │ synthesize-cli-changes.yaml │ │ ↓ │ │ cli-changes.md (人类可读的变更文档) │ └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ │ UPDATE (AI 驱动) │ ├─────────────────────────────────────────────────────────────────┤ │ update-cli-commands.yaml │ │ ↓ │ │ goose-cli-commands.md (已更新) update-summary.md │ └─────────────────────────────────────────────────────────────────┘各阶段之间全部通过output/目录下的 JSON/Markdown 文件通信这是整个管线「透明、可测试」的关键文件生产者消费者用途old-cli-structure.jsonextract-cli-structure.shdiff-cli-structures.py旧版本 CLI 结构new-cli-structure.jsonextract-cli-structure.shdiff-cli-structures.py新版本 CLI 结构cli-changes.jsondiff-cli-structures.pysynthesize-cli-changes.yaml检测到的变更结构化cli-changes.mdsynthesize-cli-changes.yamlupdate-cli-commands.yaml人类可读的变更文档update-summary.mdupdate-cli-commands.yaml人工审查文档更新摘要版本如何被确定管线支持自动版本检测逻辑实现在 run-pipeline.sh 中旧版本通过gh release list取最近第二个 release taggh不可用时回退到git tag --sort-v:refname取第二个匹配vX.Y.Z的 tag新版本取最近的 release tag或读取 CI 注入的RELEASE_TAG环境变量测试未发布变更显式传HEAD即可从当前代码构建二进制。实操本地运行整条管线环境变量变量是否必需默认值说明GOOSE_REPO本地运行时必需无脚本默认$HOME/Development/goosegoose 仓库根目录路径CLI_COMMANDS_PATH否$GOOSE_REPO/documentation/docs/guides/goose-cli-commands.md目标文档文件完整路径RELEASE_TAG否无GitHub Actions 指定新版本时使用前置条件来自 TESTING.mdPython 3.7、Rust 工具链构建 goose 时、jqJSON 处理、已安装 goose CLI运行 recipe、可访问 goose 仓库的 Git。一键运行# 设置 goose 仓库路径 export GOOSE_REPO/path/to/goose # 自动检测版本跑完整管线 ./scripts/run-pipeline.sh # 或显式指定新旧版本 ./scripts/run-pipeline.sh v1.17.0 v1.19.0 # 测试未发布的变更 ./scripts/run-pipeline.sh v1.19.0 HEADrun-pipeline.sh 的执行流程是先对旧版本、新版本分别抽取结构并统计命令数jq .commands | length再运行 diff 脚本得到cli-changes.json只有当has_changes为true时才继续执行两个 AI recipe 阶段否则直接输出「No Changes Detected」并结束。AI 阶段调用goose run --recipe ...时脚本会用sed/grep过滤掉 ANSI 转义和会话日志行starting session、session id:、text_editor等避免噪声混入输出同时用PIPESTATUS[0]检查 goose 进程本身是否失败而不是被grep的退出码误导。分步手动执行# 1. 抽取 CLI 结构 ./scripts/extract-cli-structure.sh v1.17.0 output/old-cli-structure.json ./scripts/extract-cli-structure.sh v1.19.0 output/new-cli-structure.json # 2. 检测变更 python3 scripts/diff-cli-structures.py output/old-cli-structure.json \ output/new-cli-structure.json \ output/cli-changes.json # 3. 生成人类可读的变更文档 cd output goose run --recipe ../recipes/synthesize-cli-changes.yaml # 4. 更新 goose-cli-commands.md cd output goose run --recipe ../recipes/update-cli-commands.yaml跳过命令配置有些命令被有意排除在抽取与文档追踪之外配置在 skip-commands.json{ description: Commands to skip during extraction (not documented intentionally), skip_commands: [ { name: term, reason: Terminal integration documented via goose/g aliases } ] }增删跳过命令只需编辑该配置无需改代码——抽取脚本启动时通过load_skip_commands()读取该文件并据此跳过对应子命令见 extract-cli-structure.py。确定性抽取阶段脚本在做什么获取指定版本的二进制extract-cli-structure.sh 是抽取阶段的入口按版本类型走两条路release tagvX.Y.Z格式通过官方download_cli.sh下载对应版本预构建二进制is_release_tag()用正则^v[0-9]\.[0-9]\.[0-9]$判断省去编译时间HEAD 或其他 git ref在GOOSE_REPO中构建。其中非 HEAD 的 ref 会先用git rev-parse校验版本存在再通过git worktree add把该版本检出到临时目录执行cargo build --release构建完成后把二进制拷出并移除 worktree保证不污染主工作区。拿到二进制后脚本打印--version输出确认版本最后调用python3 extract-cli-structure.py binary version完成真正的解析。解析--help输出为命令树extract-cli-structure.py 是抽取的核心它递归地对命令树中每个节点执行command --help用正则把 clap 风格的帮助文本解析为结构化 JSON。关键解析函数包括parse_about()取Usage:行之前的第一行作为命令描述parse_aliases()匹配[aliases: x, y]模式提取别名从帮助文本前 500 字符中找parse_options()定位Options:段按「行首为-的缩进行」切分选项块parse_option_block()再对每个块提取短标志-f、长标志--format、值名FORMAT、帮助文本含首行内联帮助、默认值[default: ...]、可选值[possible values: ...]六个字段parse_subcommands()解析Commands:段中的子命令名与别名自动跳过 clap 生成的help子命令extract_command_structure()递归入口对每个子命令先检查是否在SKIP_COMMANDS列表中再深入其子树。最终输出的 JSON 顶层结构为{version, source_version, extracted_at, binary_path, commands: [...]}每个命令节点包含name / about / aliases / usage / options / subcommands。所有--help调用带 10 秒超时超时只会告警并返回空串而不中断整个抽取。确定性 diff变更如何被分类diff-cli-structures.py 的算法分为三步展平flatten_commands()把嵌套的命令树按全路径如session list展开为字典便于按路径逐一对比逐字段比对compare_commands()对同一路径的旧新命令比较about、aliases、usage选项层面由compare_options()按「长标志优先、否则短标志」作为键逐一比对short / long / value_name / help / default / possible_values六个字段任一字段不同即记入modified破坏性变更归类categorize_breaking_changes()将变更打上类型与严重级别标签。变更类型严重级别判定逻辑command_removedhigh命令路径从新版本消失option_removedhigh选项标志键从选项中消失option_renamedhigh短/长标志发生变化default_changedmedium默认值改变行为可能隐性变化enum_values_removedhigh[possible values]中出现值被移除alias_removedmedium命令别名被移除可能破坏用户肌肉记忆输出 JSON 包含has_changes布尔值、summary各计数其中 breaking 只统计 high 级别、changes.commands.{added,removed,modified}与breaking_changes数组。summary.breaking_changes的计数口径在 main() 中可以确认只统计severity high的条目。AI 阶段两个 goose Recipe管线的后两步用 goose 的 recipe 机制实现recipe 文件即提示词工程——instructions定义系统级约束prompt触发执行均依赖内置的developer扩展提供text_editor等工具。synthesize-cli-changes.yaml生成变更说明synthesize-cli-changes.yaml 读取三份输入cli-changes.json变更 diff 新旧两份结构 JSON 作上下文产出cli-changes.md。recipe 指令中规定输出必须包含摘要统计、Breaking Changes每条附影响说明与迁移指引破坏性变更永远排在最前、New Commands含用途与关键选项、Removed Commands含替代方案、Modified Commands描述/选项/别名的逐项对比、Non-Breaking Changes。它的分析准则也很具体从用户影响而非实现细节的角度解释变更为破坏性变更给出新旧用法对照示例利用命令名与选项名推断变更意图跳过纯排版级的帮助文本微调对空类别整节跳过。update-cli-commands.yaml外科手术式更新目标文档update-cli-commands.yaml 是整条管线中约束最严格的一步。它的核心目标是文档永远描述 CLI 的当前状态而不是变更历史——选项被删就从文档删掉选项被加就补上绝不写「已移除」「已新增」这类措辞。为此 recipe 列出了一组硬性禁令ABSOLUTE PROHIBITIONS只有当cli-changes.md明确写「命令 X 被移除」时才删除整节命令绝不改分区标题如### Task Execution、### Session Management绝不在没有明确记录的情况下重命名选项绝不重复创建已存在的分区只原地更新绝不删除分区之间的水平线---绝不重写示例只更新实际变化的那个标志/选项。更新策略上它要求按「读cli-changes.md识别全部变更 → 逐条施加最小化编辑surgical edits用str_replace精确匹配→ 保持目标文档既有风格####命令标题、加粗选项名的 bullet 列表、带语言标识的代码块、admonition 提示框→ 自查确认」的顺序执行并在完成后额外生成update-summary.md供人工审查含「已应用变更清单 更新分区 验证清单」。目标文档路径优先取CLI_COMMANDS_PATH环境变量否则回退为$GOOSE_REPO/documentation/docs/guides/goose-cli-commands.md。从源码结构看run-pipeline.sh在调用该 recipe 前会显式export CLI_COMMANDS_PATH${GOOSE_REPO}/documentation/docs/guides/goose-cli-commands.md保证 CI 与本地行为一致。追踪范围与 GitHub Actions 集成追踪什么该管线检测的完整范围来自 cli-command-tracking/README.md命令层面新增/删除命令、描述变更、别名增删、子命令增删。选项层面新增/删除选项、帮助文本变更、默认值变更、可选值枚举变更、短/长标志变更。破坏性变更按上文严重级别表自动归类。GitHub Actions 工作流自动化通过 docs-update-cli-ref.yml 接入 GitHub Actions触发新版本发布时自动触发或手动触发用于测试流程为两个版本分别构建 goose、抽取 CLI 结构、检测变更、更新文档输出检测到变更时创建一个包含更新后goose-cli-commands.md的 PR工件old-cli-structure.json、new-cli-structure.json、cli-changes.json、cli-changes.md、pipeline.log都会作为 artifacts 上传可下载检查。工作流支持三个输入参数输入说明默认值old_version旧版本 tag从 release 自动检测new_version新版本 tagHEADdry_run只生成文件、不创建 PRtrue在 fork 中测试时需要在 fork 的 Actions 设置里配置ANTHROPIC_API_KEYsecret可选配置GOOSE_PROVIDER默认 anthropic与GOOSE_MODEL变量手动触发时建议dry_run: true跑完后从 workflow run 页面下载 artifacts ZIP 检查中间产物。用已知变更做回归验证TESTING.md 给出了三种典型测试用例可直接复用# 用例 1版本间新增了命令 ./scripts/run-pipeline.sh v1.13.0 v1.14.0 jq .changes.commands.added output/cli-changes.json # 用例 2版本间修改了选项 ./scripts/run-pipeline.sh v1.14.0 v1.15.0 jq .changes.commands.modified output/cli-changes.json # 用例 3同版本对比应无变更 ./scripts/run-pipeline.sh v1.14.0 v1.14.0 jq .has_changes output/cli-changes.json # 期望输出 false抽取阶段的验证则用jq直接抽查结构文件jq .commands[] | select(.name session) output/test-extraction.json检查特定命令、jq .commands[].name | grep -v term确认跳过命令已排除。常见问题排查TESTING.md 沉淀了几个典型故障的排查路径macOS Keychain 提示goose 启动时可能尝试读取已存凭据而触发钥匙串访问提示CI runner 没有 keychain可能需通过keyring: false之类的配置或环境变量禁用凭据加载文档中标注为待调查项旧版本构建失败先git tag确认版本存在再手动git worktree add /tmp/goose-test v1.14.0 cargo build --release定位依赖问题抽取超时调大 extract-cli-structure.py 中run_help_command的timeout10diff 出现意外变更可能是帮助文本排版格式变了直接对两版二进制的原始--help输出做diff对比AI recipe 失败先用ls -lh与jq empty确认三份输入 JSON 存在且格式合法。扩展指南与维护建议按照总 README 的约定新增一个自动化项目只需四步创建documentation/automation/your-project/子目录、遵循标准结构README、TESTING、config、scripts、recipes、按需创建 GitHub Actions 工作流、最后更新 automation 总 README 的项目表格。维护cli-command-tracking本身时README 给出的纪律是先用测试版本本地跑./scripts/run-pipeline.sh将生成文件与实际 CLI 变更逐一核对在 fork 中用 dry-run 模式验证工作流把设计决策回写进 README。此外 TESTING.md 还建议保存「已知正确」的输出作为回归测试数据如test-data/v1.14.0-to-v1.15.0-changes.json防止后续脚本改动破坏既有行为。这套管线值得借鉴的地方在于它没有把「文档更新」整体交给 AI而是把可复现的事实提取构建、--help、解析、diff留给脚本、把需要语言判断的合成与编辑留给 AI中间用可检查的 JSON/Markdown 文件交接——每一步失败都可以定位到具体阶段每一步的产物都可以人工复核这正是它能在发布流程中无人值守运行的前提。【免费下载链接】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），仅供参考
