查找并安装插件
先了解包的来源和用途。以下命令使用已发布的安装器;尚未安装时请参阅 CLI 安装。 使用 --dry-run 在应用变更前检查计划。
发现并检查包
agentplugins search docs
agentplugins info context7context7 等短名称来自带签名的 Universal Agent Plugins Registry。 搜索和包信息用于筛选候选项,不会执行插件,也不能证明其服务可用。安装前请检查工具、技能、运行时和账户访问要求。
预览并应用明确的选择
agentplugins add context7 --target codex,cursor --dry-run检查来源、目标、路径、安全检查结果和待完成的激活工作。这条命令只输出计划,不应用安装,也不测试 MCP 服务器。 检查完成后去掉 --dry-run:
agentplugins add context7 --target codex,cursor交互使用时可省略 --target。只有一个检测到的客户端时可自动选择;多个客户端时会显示选择器。 脚本和自动化中应明确指定目标,以便重现选择。安装器预先检查目标,并保护不属于它的文件。 若报告回滚失败或待恢复操作,请保留报告并先按恢复说明处理。
完成激活
按结果中的客户端说明重新加载、新建会话、授予工作区信任、登录或激活。 准备好文件或完成原生注册,不等于 OAuth 已完成或工具调用已成功。 文件缺失或漂移时使用状态诊断;包已存在但不可用时还应检查客户端认证。
安装本地包
选择包含根目录 plugin.json 的文件夹:
agentplugins validate ./my-plugin
agentplugins add ./my-plugin --target codex --dry-run安装器验证和规划会应用安全策略,必要时可能获取扫描器或元数据。即使输入是本地目录,也不保证离线执行。 --dry-run 避免应用客户端安装变更,不代表完全不联网或不使用缓存。
检查计划后去掉 --dry-run。本地目录仍是本地安装,不能作为另一台机器可抓取的可移植依赖。 请向作者索取包交付证据。
选择固定的 GitHub 源
原有 GitHub 语法要求完整的 40 字符提交 SHA。请将示例换成实际仓库、已审核提交和包路径:
agentplugins add owner/repository@0123456789abcdef0123456789abcdef01234567//path/to/plugin --target codex --dry-runowner/repository@... 这种写法拒绝分支、标签和缩短的 SHA。省略路径时会选择有效的根包或唯一有效的嵌套候选包。 有多个候选包时必须给出路径;可能的包超过 16 个时,要先提供路径才会抓取候选项。 repair 重放记录的来源;切换到不同固定来源是单独的源选择操作。
CLI 0.1.93 也支持 HTTPS/SSH Git、受支持的提供方浏览器链接,以及完整的 HTTPS 或本地归档。 请将以下占位地址替换为经过审核的真实包来源:
agentplugins add 'https://git.example.com/team/tools.git#refs/heads/main//plugins/demo' --target codex --dry-run
agentplugins add 'ssh://git@git.example.com/team/tools.git#main//plugins/demo' --target codex --dry-run
agentplugins add 'https://downloads.example.com/plugin.tar.gz' --target codex --dry-runGit 使用现有的原生凭据和 SSH 主机信任配置。HTTPS 归档不使用凭据,且必须包含完整的标准包。 锁文件固定精确的 Git 提交或原始归档字节,并记录包摘要。跟踪可变引用的来源只能通过显式更新推进; 按锁文件恢复时仍使用原先固定的版本。这些完整包来源与独立技能的获取方式不同。 完整语法、包选择、校验和及解压限制见直接安装完整包。
安装 Agent Skills
独立技能使用 skills 命令组,来源可以是公共 GitHub 仓库、文件夹或 SKILL.md URL, 也可以是提供完整 .well-known 技能索引的 HTTPS 发布方:
agentplugins skills add owner/repository --ui请换成实际来源。--ui 在交互终端中打开内置浏览器选择器;--no-ui 使用终端选择。 明确选择时可运行:
agentplugins skills add owner/repository --skill review --skill pdf \
--target codex,claude --no-ui --yes- 重复
--skill指定精确名称;名称有歧义时用--path指定仓库内技能目录。 - URL 的分支与路径边界有歧义时用
--ref明确 Git 引用。 --dry-run只预览安装。- JSON 或非交互执行需要明确技能和目标;除预览外,还需要
--yes。 --ui不能与--skill、--target或--dry-run组合。- HTTPS 发布方安装需要精确的
--skill名称,且索引必须列出该技能的所有文件。
自动安全检查可能阻止安装。用 --security-details 查看详细结果,再决定是否明确接受 --accept-security-risk。 已安装技能会出现在 agentplugins list 中,并使用普通维护命令。
为单个项目安装
CLI 0.1.93 及以后版本支持显式项目范围。 选择已存在的目录,并在每条命令中指定范围:
对于符合条件的已审核目录条目,如果目标客户端支持所有必需组件,已发布的 CLI 可使用签名 Directory 短名称和显式项目范围(例如 agentplugins add context7 --target codex --scope project --dry-run)。如需固定可复现的来源,也可以使用完整提交 SHA 的 Git 来源及兼容客户端。将 OWNER/REPOSITORY、FULL_COMMIT_SHA 和 PACKAGE_PATH 替换为真实值;如果包位于仓库根目录,请省略 //PACKAGE_PATH。
语法模板:github:OWNER/REPOSITORY@FULL_COMMIT_SHA//PACKAGE_PATH。下面的命令使用一个真实的 GitLab 历史提交,并不代表该版本目前仍通过目录审核。实际安装时请从目录复制当前已审核的固定来源。
agentplugins add github:777genius/universal-agent-plugins@2ddbb99dd190c1792b79904f9875e6322bccd243//plugins/gitlab --target codex --scope project \
--project-root /path/to/project --dry-run
agentplugins skills add owner/repository --ui --scope project \
--project-root /path/to/project第一条只预览,准备应用时去掉 --dry-run。第二条打开绑定到该项目的选择器,可应用用户确认的选择。 指定项目范围但省略 --project-root 时,仅使用调用目录,不向上查找。add 和维护命令默认使用用户范围。 从 CLI 0.1.94 起,未指定来源参数的 install 仅在当前目录中存在普通文件 uap.toml 时自动选择项目范围; 显式指定的范围始终优先。严格的锁文件校验规则见维护与恢复。
目标必须支持所请求的项目组件。ChatGPT 明确不支持原生项目安装。 如果结果为 Prepared,请检查所需的工作区和服务器信任,以及客户端配置。 仅有已安装的文件不能证明 MCP 启动、工具调用或模型执行。