agents-cli 扩展系统实战用一份 YAML 覆盖或新增内置命令【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本文围绕 agents-cli 的扩展Extension机制展开一个目录里只要有一份agents-cli-extension.yaml任何 git 仓库都可以充当扩展注册表用来覆盖override或新增add内置命令。读完本文你将掌握两种完整路径——在本地项目中快速编写一个 ad-hoc 扩展并共享给团队以及从 GitHub/自建 Git 主机/本地路径安装、固定pin、更新和移除现有扩展并能对照仓库源码理解命令覆盖、信任门禁、版本兼容与供应vendoring的底层实现。1. 扩展是什么一个文件让任何 git 仓库成为注册表扩展的本质非常轻它就是一个包含agents-cli-extension.yaml的目录因此任何 git 仓库都可以直接作为扩展来源见 references/extension.md。围绕它只有两件事可做Author编写先在当前仓库临时ad-hoc起步之后再发布给其他仓库Adopt采用安装一个已存在的扩展。扩展能做的事被限制为两类命令贡献对应 manifest 中commands:下的两个分组分组含义约束commands.override替换一个内置命令用户命令行参数原样透传命令名用点号表示子命令路径如eval.generatecommands.add新增一个尚不存在的命令新命令从此成为 CLI 的一部分从源码看扩展的解析、加载、校验全部集中在 src/google/agents/cli/extension/ 包内_spec.py 负责解析校验 manifest_loader.py 跨作用域发现并合并成ExtensionSet_resolver.py 把引用解析成 commit SHA 并供应目录_overrides.py 合成出真正执行的 Click 命令。2. 编写 ad-hoc 扩展不建仓库就能起步最简单的起步方式把单个agents-cli-extension.yaml放在项目根目录与agents-cli-manifest.yaml同级。它会被以项目作用域自动加载无需执行extension add。提交到 git 后队友和 CI 会得到与本地完全一致的命令覆盖。两条硬性限制该精确路径下只能有一个此类文件且永远是项目作用域如果想装第二个、或者想把本地扩展装到全局就把它移进独立目录然后执行agents-cli extension add local./path --global如果目录里有多个扩展用#name选择其中一个。发布给其他仓库把同一个文件连同其脚本移入一个独立的 git 仓库并打 tag别人即可agents-cli extension add org/repo#name --ref v1.0.0关键点文件本身不需要任何改动ad-hoc 与共享格式完全相同。3.agents-cli-extension/v1alpha1模式详解除命令条目的run非空列表外manifest 中所有字段都是可选的。未知键会被拒绝——拼写错误会立刻报错而不是静默无效。机器可读版本是仓库中的 agents-cli-extension-v1alpha1.schema.json它与加载器使用的是同一套 pydantic 模型生成的可以给编辑器配一条yaml-language-servermodeline 指向该 schema 做校验。3.1 完整示例# 可加一条 yaml-language-server modeline 指向本仓库的 # schemas/agents-cli-extension-v1alpha1.schema.json 以获得编辑器校验 schema: agents-cli-extension/v1alpha1 name: my-extension description: What this extension does. requires: agents_cli: 1.3,2 # 示例 - 请按 agents-cli --version 推导见下文 on_incompatible: warn # warn (安装并警告) | error (add/update 时拒绝CLI 漂移出范围后拦截其命令) commands: override: # 替换内置命令用户 argv 原样透传 deploy: run: [uv, run, scripts/custom_deploy.py] description: SBOM upload, then the built-in deploy. eval.generate: # 点号名 子命令group.sub run: [uv, run, scripts/eval_generate.py] description: Framework-specific inference runner. add: # 新增一个尚不存在的命令 compliance-report: run: [python, scripts/compliance_report.py] description: Generate the quarterly compliance report.3.2 字段说明字段类型/取值说明schema固定agents-cli-extension/v1alpha1跟踪的是manifest 格式版本不是 CLI 版本跨 CLI 大版本均可接受。源码中即 V1ALPHA1 常量当前 v1alpha1 文档只接受 v1alpha1name字符串缺省时回退为扩展目录名parse_extension_spec的default_namedescription字符串默认空显示在--help等处requires.agents_cliPEP 440 版本范围如1.3,2兼容性声明强烈建议总是声明无效范围会被告警并丢弃扩展仍会加载requires.on_incompatiblewarn默认|error版本出范围时的行为见下文commands.override/commands.add映射命令名 → 条目命令名支持点号子命令路径条目run非空字符串列表命令向量直接 exec不经 shell条目description字符串默认空该命令的描述从源码看严格性来自 _spec.py 中extraforbid的 pydantic 模型拼错键名如reqires:会触发extra_forbidden校验错误并且校验器会用difflib.get_close_matches给出 did you mean 提示见 _describe 实现。另外commands:下什么都没有即None会被视为整节被注释掉而不是报错——这是留给作者临时禁用一个分组的惯用法。4. 必须知道的规则附源码级解释4.1run:是无 shell 的命令向量用户命令行参数原样追加到向量末尾向量中相对扩展目录的路径会被解析为绝对路径因此从任何 cwd 都能找到脚本环境变量$AGENTS_CLI_EXTENSION_DIR指向扩展目录用于定位同目录的脚本/模板。这一点在 src/google/agents/cli/_runner.py 的run_extension_command中实现得很精确只有看起来像路径且在extension_root下真实存在的 token 才会被解析为绝对路径——避免把恰好与扩展内某个文件名同名的普通参数如make build中的build误改写成路径。子进程的退出码被原样返回使覆盖命令的退出行为与被替换的内置命令一致。4.2 不能覆盖命令组只能覆盖具体子命令例如不能覆盖eval这个组只能覆盖eval.generate同组的eval grade、eval compare保持内置行为。这样部分覆盖不会波及未声明的子命令。4.3 安全地重入内置命令覆盖命令执行时CLI 会设置AGENTS_CLI_DISABLE_OVERRIDES1见 DISABLE_OVERRIDES_ENV 定义。因此你的包装脚本里再调用agents-cli deploy时命中的是内置实现不会无限递归。同时--help会为被覆盖的命令显示一条绕过扩展、直接跑内置的提示Windows 下会给出set AGENTS_CLI_DISABLE_OVERRIDES1 agents-cli cmd的写法见 bypass_hint。4.4 串联步骤必须写在包装脚本里因为run:只是单个向量而不是 shell 行先检查、再跑内置这类串联要指向一个脚本#!/usr/bin/env bash set -e $AGENTS_CLI_EXTENSION_DIR/scripts/compliance_check.sh # 这里非零退出则中止 agents-cli deploy $ # 命中内置守卫已设置4.5run:以程序开头而不是脚本向量被直接 exec不经过 shell所以[python, scripts/x.py]或[uv, run, python, scripts/x.py]在任何平台都工作裸的[scripts/x.py]依赖 shebang且在 Windows 上永远不会运行。源码里这条警告是真实存在的_warn_if_script_entrypoint 会检测run首 token 是否带.py/.sh/.js/.ts/.rb/.pl后缀若是则记录 warning 并建议前缀解释器。向量内的路径相对扩展目录解析从任何 cwd 都有效。4.6 冲突规则同一作用域内两个扩展声明同一条命令先声明者获胜后者被忽略并在agents-cli extension list/agents-cli info中显示冲突。加载器按低优先级先、高优先级后的顺序遍历项目作用域覆盖用户作用域的同名命令见 load_extension_set 的注释与实现跨作用域没有冲突——项目作用域优先于用户--global作用域。4.7 永远声明requires兼容范围操作建议运行agents-cli --version下界设为该major.minor上界设为下一个大版本CLI 报 1.3.x 则写1.3,2——示例中的数字仅为示例。on_incompatible由用户选择默认warnwarn照常安装、运行出范围时警告errorextension add/update拒绝出范围的安装如果之后 CLI 升级把你带出范围该扩展的命令会失败并给出范围与修复办法——而不是静默回退到内置命令回退意味着做了别的事对覆盖命令尤其危险恢复性命令install、extension *始终可用。从源码看范围解析统一走 src/google/agents/cli/extension/_compat.py 的is_compatible基于packaging库的 PEP 440SpecifierSetprereleasesTrue使范围内的 rc 版本也算合规开发构建dev build永远视为兼容从 checkout 直接运行不应被任何扩展范围挡住。schema字段与 CLI 版本解耦它跟 manifest 格式走跨 CLI 大版本都能被接受。5. 源码级纵深加载、门禁与供应5.1 不可覆盖的恢复命令_loader.py 定义了RECOVERY_COMMANDS集合install、extension、extension.add、extension.list、extension.remove、extension.update任何扩展都不允许覆盖。理由是这些命令正是用户移除/修复扩展的手段若让某个扩展拥有它们等于让它拥有自己的卸载按钮。extension add在门禁阶段拒绝这类声明见 _check_reserved_commands加载器对手改 manifest 的同类声明则告警并忽略。5.2extension add的门禁顺序与回滚cmd_extension_add.py 的顺序是解析引用 → 信任确认 → 解析 SHA 并供应目录 → 解析 manifest失败即安装失败而非装上了但没贡献任何命令→ 兼容检查 → 保留命令检查 → 同作用域冲突检查 → 才写入agents-cli-extensions.yaml。所有门禁都在落账之前执行若门禁失败已供应的目录会被删除做到拒绝安装不留残迹。5.3 引用解析与供应vendoring_refs.py 的parse_ref支持的形式与第 6 节表格一一对应localpath可带#selector→ 本地路径带https://、http://、ssh://等 scheme 的 URL或githost:org/reposcp 形式 → 任意 git 主机。源码中 GIT_URL_SCHEMES 还接受file://共享挂载上的裸仓库并刻意排除git://——该协议无认证而扩展命令会在安装机器上执行任意代码org/repo简写 → github.com 上的仓库裸名字 →第一方简写解析到google/agents-cli仓库FIRST_PARTY_REPO常量其扩展位于该仓库的extensions/selector/下见 materialize。_resolver.py 的关键设计只有完整 40 位十六进制 SHA 才被当作 commit更短的十六进制串可能恰好是某个分支/tag 名一律走git ls-remote解析见 _SHA_RE 注释扩展名会用作目录组件validate_extension_name只允许[A-Za-z0-9._-]防止上游 manifest 里的恶意name: ../../x逃逸供应目录git 仓库克隆进共享缓存POSIX 下~/.cache/agents-cli/gitWindows 下%LOCALAPPDATA%\agents-cli\git见 _paths.py按仓库加文件锁串行化超时 120 秒供应副本写入.agents-cli-extension-shastamp 文件记录来源local引用没有 commit 可钉改用源树内容哈希做 stamp这样对本地源的编辑能被下一次 sync 发现拷贝用旁路暂存 原子替换且跳过符号链接避免把notes.md - ~/.ssh/id_rsa这类链接解引用成项目内真实文件源码注释直接标注了 CWE-59。5.4 信任门禁src/google/agents/cli/extension/_trust.py 的逻辑与文档一致第一方简写引用自动信任其余一切引用org/repo、URL、本地路径、完整写出的google/agents-cli在安装前提示确认因为它的命令被调用时会执行任意代码。--yesauto_approve跳过提示属于无差别信任仅限自动化/引导场景。5.5 一个真实的第一方示例仓库自带一个可直接学习的样例extensions/langchain/template/agents-cli-extension.yaml。它把playground、run、publish.gemini-enterprise、eval.generate覆盖为 LangChain/LangGraph 等价物并把需要内省 ADK agent 对象的eval.dataset、eval.optimize指向scripts/unsupported.py显式报不支持。这正是文档中点号名 子命令不支持就显式失败而非静默回退两个规则的落地形态。6. 采用现有扩展6.1 命令一览agents-cli extension add ref [--global] [--ref branch|tag|sha] [--yes] agents-cli extension list # 激活的扩展、作用域及其命令 agents-cli extension update [name] # 推进 pin重新解析被跟踪的 ref agents-cli extension remove name # 移除并删除其供应副本 agents-cli info # 显示激活的扩展 来源 冲突6.2 引用形式形式含义acme/acli-extensionsgithub.com 上任意org/repoacme/acli-extensions#soc2-deploy从多扩展仓库中选一个扩展https://git.example.com/acme/acli-extensions任意 git 主机——https://、http://或ssh://gitgit.example.com:acme/acli-extensions同一主机的 scp 形式local../my-extension本地路径用于开发name第一方简写——解析到google/agents-cli仓库--ref branch\|tag\|sha钉住分支、tag 或 commit SHAURL 会按你环境里现成的 git 配置克隆因此已有的认证方式credential helper、ssh agent直接生效——agents-cli 既不会索要也不会存储凭据。另一个边界扩展改变的是命令。想换 agent 框架运行时应改用该框架的模板脚手架agents-cli create my-agent --agent org/repotag模板自带agents-cli-extension.yaml不会在全局机器层面安装任何东西。6.3 作用域Scope项目作用域默认只记录在本仓库写入agents-cli-extensions.yaml工作副本供应在extensions/下不影响你其他的项目CI/队友都能拿到。两个文件清单 供应副本都提交即可离线工作缺失时install会按 pin 重新抓取见 6.4用户作用域--global位于~/.config/agents-cli/Windows 下为%APPDATA%\agents-cli见 user_config_root。对机器上每个项目生效且可以在项目尚不存在时就应用覆盖。由于全局覆盖会改变所有地方的命令除非确实要机器级生效优先用项目作用域两个作用域声明同一条命令时项目作用域获胜agents-cli info会显示来源。6.4 信任Trust通过简写形式添加的第一方扩展extension add name自动信任其他一切引用——org/repo、URL、本地路径乃至完整拼写的google/agents-cli——安装前都会提示其命令被调用时运行任意代码。--yes跳过提示无差别信任仅限自动化/引导。6.5 Pin 与更新Pinning and updatesextension add把 ref 解析为精确 commit SHA并以source/ref/sha记录在agents-cli-extensions.yaml的extensions:下——这是一个独立文件两种作用域同文件名这样扩展系统的任何写操作都不可能碰到项目脚手架状态agents-cli-manifest.yaml见 _manifest.py 的模块注释工作副本供应在extensions/下agents-cli install会把缺失/陈旧的供应副本按 pin 的 SHA 重新物化用 stamp 文件校验见 sync_extensions——CI 和新 checkout 拿到的是同一份经审查过的代码与命令覆盖。它从不推进 pinextension update [name]把 pin 推进到同一被跟踪 ref如某分支的最新 commit第三方扩展会重新提示信任。后台永远不更新任何东西。注意钉住的 tag/SHA 重新解析还是自己——要换到另一个tag需重跑extension add ref --ref new-tag它会替换现有 pinextension remove name删除条目并删除工作副本。它每次调用只从一个作用域移除项目优先于用户所以两个作用域都装了的话需要remove两次。跟踪一个版本的完整流程agents-cli extension add acme/acli-extensions#soc2 --ref v1.2.0 # 钉 tag推荐 agents-cli extension add acme/acli-extensions#soc2 --ref main # 跟随分支 agents-cli extension update soc2 # 在被跟踪 ref 内推进 agents-cli extension add acme/acli-extensions#soc2 --ref v1.3.0 # 换到别的 tag重新 add而不是 update agents-cli extension add acme/acli-extensions#soc2 --ref v1.2.0 # 同样方式回滚最后一行值得留意一次失败的重新add会回滚到什么都没有而不是回退到上一个 pin——要恢复原状重新 add 旧的 ref 即可。7. 小结何时用哪种形态场景推荐做法单仓库内让deploy先做 SBOM 再跑内置项目根放一个agents-cli-extension.yaml提交即可多仓库共享同一套覆盖独立 git 仓库 tagextension add org/repo#name --ref v1.0.0换 agent 框架的完整生命周期用模板脚手架agents-cli create --agent repotag不要手写全局扩展机器级、项目创建前的覆盖--global并清楚它影响所有项目团队 CI 可复现提交agents-cli-extensions.yamlextensions/依赖install按 SHA 恢复写作扩展时的检查清单run:首 token 是程序而不是脚本覆盖子命令而非组需要多步就写包装脚本并用$AGENTS_CLI_EXTENSION_DIR定位资源requires永远声明且下界来自当前agents-cli --version不要尝试覆盖install/extension *这类恢复命令会被拒绝。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 agents-cli 扩展系统实战：用一份 YAML 覆盖或新增内置命令
agents-cli 扩展系统实战用一份 YAML 覆盖或新增内置命令【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli本文围绕 agents-cli 的扩展Extension机制展开一个目录里只要有一份agents-cli-extension.yaml任何 git 仓库都可以充当扩展注册表用来覆盖override或新增add内置命令。读完本文你将掌握两种完整路径——在本地项目中快速编写一个 ad-hoc 扩展并共享给团队以及从 GitHub/自建 Git 主机/本地路径安装、固定pin、更新和移除现有扩展并能对照仓库源码理解命令覆盖、信任门禁、版本兼容与供应vendoring的底层实现。1. 扩展是什么一个文件让任何 git 仓库成为注册表扩展的本质非常轻它就是一个包含agents-cli-extension.yaml的目录因此任何 git 仓库都可以直接作为扩展来源见 references/extension.md。围绕它只有两件事可做Author编写先在当前仓库临时ad-hoc起步之后再发布给其他仓库Adopt采用安装一个已存在的扩展。扩展能做的事被限制为两类命令贡献对应 manifest 中commands:下的两个分组分组含义约束commands.override替换一个内置命令用户命令行参数原样透传命令名用点号表示子命令路径如eval.generatecommands.add新增一个尚不存在的命令新命令从此成为 CLI 的一部分从源码看扩展的解析、加载、校验全部集中在 src/google/agents/cli/extension/ 包内_spec.py 负责解析校验 manifest_loader.py 跨作用域发现并合并成ExtensionSet_resolver.py 把引用解析成 commit SHA 并供应目录_overrides.py 合成出真正执行的 Click 命令。2. 编写 ad-hoc 扩展不建仓库就能起步最简单的起步方式把单个agents-cli-extension.yaml放在项目根目录与agents-cli-manifest.yaml同级。它会被以项目作用域自动加载无需执行extension add。提交到 git 后队友和 CI 会得到与本地完全一致的命令覆盖。两条硬性限制该精确路径下只能有一个此类文件且永远是项目作用域如果想装第二个、或者想把本地扩展装到全局就把它移进独立目录然后执行agents-cli extension add local./path --global如果目录里有多个扩展用#name选择其中一个。发布给其他仓库把同一个文件连同其脚本移入一个独立的 git 仓库并打 tag别人即可agents-cli extension add org/repo#name --ref v1.0.0关键点文件本身不需要任何改动ad-hoc 与共享格式完全相同。3.agents-cli-extension/v1alpha1模式详解除命令条目的run非空列表外manifest 中所有字段都是可选的。未知键会被拒绝——拼写错误会立刻报错而不是静默无效。机器可读版本是仓库中的 agents-cli-extension-v1alpha1.schema.json它与加载器使用的是同一套 pydantic 模型生成的可以给编辑器配一条yaml-language-servermodeline 指向该 schema 做校验。3.1 完整示例# 可加一条 yaml-language-server modeline 指向本仓库的 # schemas/agents-cli-extension-v1alpha1.schema.json 以获得编辑器校验 schema: agents-cli-extension/v1alpha1 name: my-extension description: What this extension does. requires: agents_cli: 1.3,2 # 示例 - 请按 agents-cli --version 推导见下文 on_incompatible: warn # warn (安装并警告) | error (add/update 时拒绝CLI 漂移出范围后拦截其命令) commands: override: # 替换内置命令用户 argv 原样透传 deploy: run: [uv, run, scripts/custom_deploy.py] description: SBOM upload, then the built-in deploy. eval.generate: # 点号名 子命令group.sub run: [uv, run, scripts/eval_generate.py] description: Framework-specific inference runner. add: # 新增一个尚不存在的命令 compliance-report: run: [python, scripts/compliance_report.py] description: Generate the quarterly compliance report.3.2 字段说明字段类型/取值说明schema固定agents-cli-extension/v1alpha1跟踪的是manifest 格式版本不是 CLI 版本跨 CLI 大版本均可接受。源码中即 V1ALPHA1 常量当前 v1alpha1 文档只接受 v1alpha1name字符串缺省时回退为扩展目录名parse_extension_spec的default_namedescription字符串默认空显示在--help等处requires.agents_cliPEP 440 版本范围如1.3,2兼容性声明强烈建议总是声明无效范围会被告警并丢弃扩展仍会加载requires.on_incompatiblewarn默认|error版本出范围时的行为见下文commands.override/commands.add映射命令名 → 条目命令名支持点号子命令路径条目run非空字符串列表命令向量直接 exec不经 shell条目description字符串默认空该命令的描述从源码看严格性来自 _spec.py 中extraforbid的 pydantic 模型拼错键名如reqires:会触发extra_forbidden校验错误并且校验器会用difflib.get_close_matches给出 did you mean 提示见 _describe 实现。另外commands:下什么都没有即None会被视为整节被注释掉而不是报错——这是留给作者临时禁用一个分组的惯用法。4. 必须知道的规则附源码级解释4.1run:是无 shell 的命令向量用户命令行参数原样追加到向量末尾向量中相对扩展目录的路径会被解析为绝对路径因此从任何 cwd 都能找到脚本环境变量$AGENTS_CLI_EXTENSION_DIR指向扩展目录用于定位同目录的脚本/模板。这一点在 src/google/agents/cli/_runner.py 的run_extension_command中实现得很精确只有看起来像路径且在extension_root下真实存在的 token 才会被解析为绝对路径——避免把恰好与扩展内某个文件名同名的普通参数如make build中的build误改写成路径。子进程的退出码被原样返回使覆盖命令的退出行为与被替换的内置命令一致。4.2 不能覆盖命令组只能覆盖具体子命令例如不能覆盖eval这个组只能覆盖eval.generate同组的eval grade、eval compare保持内置行为。这样部分覆盖不会波及未声明的子命令。4.3 安全地重入内置命令覆盖命令执行时CLI 会设置AGENTS_CLI_DISABLE_OVERRIDES1见 DISABLE_OVERRIDES_ENV 定义。因此你的包装脚本里再调用agents-cli deploy时命中的是内置实现不会无限递归。同时--help会为被覆盖的命令显示一条绕过扩展、直接跑内置的提示Windows 下会给出set AGENTS_CLI_DISABLE_OVERRIDES1 agents-cli cmd的写法见 bypass_hint。4.4 串联步骤必须写在包装脚本里因为run:只是单个向量而不是 shell 行先检查、再跑内置这类串联要指向一个脚本#!/usr/bin/env bash set -e $AGENTS_CLI_EXTENSION_DIR/scripts/compliance_check.sh # 这里非零退出则中止 agents-cli deploy $ # 命中内置守卫已设置4.5run:以程序开头而不是脚本向量被直接 exec不经过 shell所以[python, scripts/x.py]或[uv, run, python, scripts/x.py]在任何平台都工作裸的[scripts/x.py]依赖 shebang且在 Windows 上永远不会运行。源码里这条警告是真实存在的_warn_if_script_entrypoint 会检测run首 token 是否带.py/.sh/.js/.ts/.rb/.pl后缀若是则记录 warning 并建议前缀解释器。向量内的路径相对扩展目录解析从任何 cwd 都有效。4.6 冲突规则同一作用域内两个扩展声明同一条命令先声明者获胜后者被忽略并在agents-cli extension list/agents-cli info中显示冲突。加载器按低优先级先、高优先级后的顺序遍历项目作用域覆盖用户作用域的同名命令见 load_extension_set 的注释与实现跨作用域没有冲突——项目作用域优先于用户--global作用域。4.7 永远声明requires兼容范围操作建议运行agents-cli --version下界设为该major.minor上界设为下一个大版本CLI 报 1.3.x 则写1.3,2——示例中的数字仅为示例。on_incompatible由用户选择默认warnwarn照常安装、运行出范围时警告errorextension add/update拒绝出范围的安装如果之后 CLI 升级把你带出范围该扩展的命令会失败并给出范围与修复办法——而不是静默回退到内置命令回退意味着做了别的事对覆盖命令尤其危险恢复性命令install、extension *始终可用。从源码看范围解析统一走 src/google/agents/cli/extension/_compat.py 的is_compatible基于packaging库的 PEP 440SpecifierSetprereleasesTrue使范围内的 rc 版本也算合规开发构建dev build永远视为兼容从 checkout 直接运行不应被任何扩展范围挡住。schema字段与 CLI 版本解耦它跟 manifest 格式走跨 CLI 大版本都能被接受。5. 源码级纵深加载、门禁与供应5.1 不可覆盖的恢复命令_loader.py 定义了RECOVERY_COMMANDS集合install、extension、extension.add、extension.list、extension.remove、extension.update任何扩展都不允许覆盖。理由是这些命令正是用户移除/修复扩展的手段若让某个扩展拥有它们等于让它拥有自己的卸载按钮。extension add在门禁阶段拒绝这类声明见 _check_reserved_commands加载器对手改 manifest 的同类声明则告警并忽略。5.2extension add的门禁顺序与回滚cmd_extension_add.py 的顺序是解析引用 → 信任确认 → 解析 SHA 并供应目录 → 解析 manifest失败即安装失败而非装上了但没贡献任何命令→ 兼容检查 → 保留命令检查 → 同作用域冲突检查 → 才写入agents-cli-extensions.yaml。所有门禁都在落账之前执行若门禁失败已供应的目录会被删除做到拒绝安装不留残迹。5.3 引用解析与供应vendoring_refs.py 的parse_ref支持的形式与第 6 节表格一一对应localpath可带#selector→ 本地路径带https://、http://、ssh://等 scheme 的 URL或githost:org/reposcp 形式 → 任意 git 主机。源码中 GIT_URL_SCHEMES 还接受file://共享挂载上的裸仓库并刻意排除git://——该协议无认证而扩展命令会在安装机器上执行任意代码org/repo简写 → github.com 上的仓库裸名字 →第一方简写解析到google/agents-cli仓库FIRST_PARTY_REPO常量其扩展位于该仓库的extensions/selector/下见 materialize。_resolver.py 的关键设计只有完整 40 位十六进制 SHA 才被当作 commit更短的十六进制串可能恰好是某个分支/tag 名一律走git ls-remote解析见 _SHA_RE 注释扩展名会用作目录组件validate_extension_name只允许[A-Za-z0-9._-]防止上游 manifest 里的恶意name: ../../x逃逸供应目录git 仓库克隆进共享缓存POSIX 下~/.cache/agents-cli/gitWindows 下%LOCALAPPDATA%\agents-cli\git见 _paths.py按仓库加文件锁串行化超时 120 秒供应副本写入.agents-cli-extension-shastamp 文件记录来源local引用没有 commit 可钉改用源树内容哈希做 stamp这样对本地源的编辑能被下一次 sync 发现拷贝用旁路暂存 原子替换且跳过符号链接避免把notes.md - ~/.ssh/id_rsa这类链接解引用成项目内真实文件源码注释直接标注了 CWE-59。5.4 信任门禁src/google/agents/cli/extension/_trust.py 的逻辑与文档一致第一方简写引用自动信任其余一切引用org/repo、URL、本地路径、完整写出的google/agents-cli在安装前提示确认因为它的命令被调用时会执行任意代码。--yesauto_approve跳过提示属于无差别信任仅限自动化/引导场景。5.5 一个真实的第一方示例仓库自带一个可直接学习的样例extensions/langchain/template/agents-cli-extension.yaml。它把playground、run、publish.gemini-enterprise、eval.generate覆盖为 LangChain/LangGraph 等价物并把需要内省 ADK agent 对象的eval.dataset、eval.optimize指向scripts/unsupported.py显式报不支持。这正是文档中点号名 子命令不支持就显式失败而非静默回退两个规则的落地形态。6. 采用现有扩展6.1 命令一览agents-cli extension add ref [--global] [--ref branch|tag|sha] [--yes] agents-cli extension list # 激活的扩展、作用域及其命令 agents-cli extension update [name] # 推进 pin重新解析被跟踪的 ref agents-cli extension remove name # 移除并删除其供应副本 agents-cli info # 显示激活的扩展 来源 冲突6.2 引用形式形式含义acme/acli-extensionsgithub.com 上任意org/repoacme/acli-extensions#soc2-deploy从多扩展仓库中选一个扩展https://git.example.com/acme/acli-extensions任意 git 主机——https://、http://或ssh://gitgit.example.com:acme/acli-extensions同一主机的 scp 形式local../my-extension本地路径用于开发name第一方简写——解析到google/agents-cli仓库--ref branch\|tag\|sha钉住分支、tag 或 commit SHAURL 会按你环境里现成的 git 配置克隆因此已有的认证方式credential helper、ssh agent直接生效——agents-cli 既不会索要也不会存储凭据。另一个边界扩展改变的是命令。想换 agent 框架运行时应改用该框架的模板脚手架agents-cli create my-agent --agent org/repotag模板自带agents-cli-extension.yaml不会在全局机器层面安装任何东西。6.3 作用域Scope项目作用域默认只记录在本仓库写入agents-cli-extensions.yaml工作副本供应在extensions/下不影响你其他的项目CI/队友都能拿到。两个文件清单 供应副本都提交即可离线工作缺失时install会按 pin 重新抓取见 6.4用户作用域--global位于~/.config/agents-cli/Windows 下为%APPDATA%\agents-cli见 user_config_root。对机器上每个项目生效且可以在项目尚不存在时就应用覆盖。由于全局覆盖会改变所有地方的命令除非确实要机器级生效优先用项目作用域两个作用域声明同一条命令时项目作用域获胜agents-cli info会显示来源。6.4 信任Trust通过简写形式添加的第一方扩展extension add name自动信任其他一切引用——org/repo、URL、本地路径乃至完整拼写的google/agents-cli——安装前都会提示其命令被调用时运行任意代码。--yes跳过提示无差别信任仅限自动化/引导。6.5 Pin 与更新Pinning and updatesextension add把 ref 解析为精确 commit SHA并以source/ref/sha记录在agents-cli-extensions.yaml的extensions:下——这是一个独立文件两种作用域同文件名这样扩展系统的任何写操作都不可能碰到项目脚手架状态agents-cli-manifest.yaml见 _manifest.py 的模块注释工作副本供应在extensions/下agents-cli install会把缺失/陈旧的供应副本按 pin 的 SHA 重新物化用 stamp 文件校验见 sync_extensions——CI 和新 checkout 拿到的是同一份经审查过的代码与命令覆盖。它从不推进 pinextension update [name]把 pin 推进到同一被跟踪 ref如某分支的最新 commit第三方扩展会重新提示信任。后台永远不更新任何东西。注意钉住的 tag/SHA 重新解析还是自己——要换到另一个tag需重跑extension add ref --ref new-tag它会替换现有 pinextension remove name删除条目并删除工作副本。它每次调用只从一个作用域移除项目优先于用户所以两个作用域都装了的话需要remove两次。跟踪一个版本的完整流程agents-cli extension add acme/acli-extensions#soc2 --ref v1.2.0 # 钉 tag推荐 agents-cli extension add acme/acli-extensions#soc2 --ref main # 跟随分支 agents-cli extension update soc2 # 在被跟踪 ref 内推进 agents-cli extension add acme/acli-extensions#soc2 --ref v1.3.0 # 换到别的 tag重新 add而不是 update agents-cli extension add acme/acli-extensions#soc2 --ref v1.2.0 # 同样方式回滚最后一行值得留意一次失败的重新add会回滚到什么都没有而不是回退到上一个 pin——要恢复原状重新 add 旧的 ref 即可。7. 小结何时用哪种形态场景推荐做法单仓库内让deploy先做 SBOM 再跑内置项目根放一个agents-cli-extension.yaml提交即可多仓库共享同一套覆盖独立 git 仓库 tagextension add org/repo#name --ref v1.0.0换 agent 框架的完整生命周期用模板脚手架agents-cli create --agent repotag不要手写全局扩展机器级、项目创建前的覆盖--global并清楚它影响所有项目团队 CI 可复现提交agents-cli-extensions.yamlextensions/依赖install按 SHA 恢复写作扩展时的检查清单run:首 token 是程序而不是脚本覆盖子命令而非组需要多步就写包装脚本并用$AGENTS_CLI_EXTENSION_DIR定位资源requires永远声明且下界来自当前agents-cli --version不要尝试覆盖install/extension *这类恢复命令会被拒绝。【免费下载链接】agents-cliThe CLI and skills that turn any coding assistant into an expert at creating, evaluating, and deploying AI agents on Google Cloud.项目地址: https://gitcode.com/GitHub_Trending/ag/agents-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考