跳转到正文

查找并安装插件 ​

先了解包的来源和用途。以下命令使用已发布的安装器;尚未安装时请参阅 CLI 安装。 使用 --dry-run 在应用变更前检查计划。

发现并检查包 ​

bash
agentplugins search docs
agentplugins info context7

context7 等短名称来自带签名的 Universal Agent Plugins Registry。 搜索和包信息用于筛选候选项,不会执行插件,也不能证明其服务可用。安装前请检查工具、技能、运行时和账户访问要求。

预览并应用明确的选择 ​

bash
agentplugins add context7 --target codex,cursor --dry-run

检查来源、目标、路径、安全检查结果和待完成的激活工作。这条命令只输出计划,不应用安装,也不测试 MCP 服务器。 检查完成后去掉 --dry-run:

bash
agentplugins add context7 --target codex,cursor

交互使用时可省略 --target。只有一个检测到的客户端时可自动选择;多个客户端时会显示选择器。 脚本和自动化中应明确指定目标,以便重现选择。安装器预先检查目标,并保护不属于它的文件。 若报告回滚失败或待恢复操作,请保留报告并先按恢复说明处理。

完成激活 ​

按结果中的客户端说明重新加载、新建会话、授予工作区信任、登录或激活。 准备好文件或完成原生注册,不等于 OAuth 已完成或工具调用已成功。 文件缺失或漂移时使用状态诊断;包已存在但不可用时还应检查客户端认证。

安装本地包 ​

选择包含根目录 plugin.json 的文件夹:

bash
agentplugins validate ./my-plugin
agentplugins add ./my-plugin --target codex --dry-run

安装器验证和规划会应用安全策略,必要时可能获取扫描器或元数据。即使输入是本地目录,也不保证离线执行。 --dry-run 避免应用客户端安装变更,不代表完全不联网或不使用缓存。

检查计划后去掉 --dry-run。本地目录仍是本地安装,不能作为另一台机器可抓取的可移植依赖。 请向作者索取包交付证据。

选择固定的 GitHub 源 ​

原有 GitHub 语法要求完整的 40 字符提交 SHA。请将示例换成实际仓库、已审核提交和包路径:

text
agentplugins add owner/repository@0123456789abcdef0123456789abcdef01234567//path/to/plugin --target codex --dry-run

owner/repository@... 这种写法拒绝分支、标签和缩短的 SHA。省略路径时会选择有效的根包或唯一有效的嵌套候选包。 有多个候选包时必须给出路径;可能的包超过 16 个时,要先提供路径才会抓取候选项。 repair 重放记录的来源;切换到不同固定来源是单独的源选择操作。

CLI 0.1.93 也支持 HTTPS/SSH Git、受支持的提供方浏览器链接,以及完整的 HTTPS 或本地归档。 请将以下占位地址替换为经过审核的真实包来源:

text
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-run

Git 使用现有的原生凭据和 SSH 主机信任配置。HTTPS 归档不使用凭据,且必须包含完整的标准包。 锁文件固定精确的 Git 提交或原始归档字节,并记录包摘要。跟踪可变引用的来源只能通过显式更新推进; 按锁文件恢复时仍使用原先固定的版本。这些完整包来源与独立技能的获取方式不同。 完整语法、包选择、校验和及解压限制见直接安装完整包。

安装 Agent Skills ​

独立技能使用 skills 命令组,来源可以是公共 GitHub 仓库、文件夹或 SKILL.md URL, 也可以是提供完整 .well-known 技能索引的 HTTPS 发布方:

bash
agentplugins skills add owner/repository --ui

请换成实际来源。--ui 在交互终端中打开内置浏览器选择器;--no-ui 使用终端选择。 明确选择时可运行:

bash
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 历史提交,并不代表该版本目前仍通过目录审核。实际安装时请从目录复制当前已审核的固定来源。

bash
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 启动、工具调用或模型执行。

查看项目安装指南和 各客户端项目边界,然后继续维护与恢复。

面向插件作者和集成者的公共文档。