在 Vetta 中安装能力

Vetta 的能力分三种，安装路径互不相同。先分类，再动手。

用户给的东西	类型	安装路径
npm 包名、.zip、http(s) zip 链接、本地插件工程目录	插件	vetta-plugin-cli add → 按需 reload（§2）
能力市场里的插件条目	插件	引导用户在能力市场页安装（§2.6）
能力市场里的 skill / scene（有 slug）	Skill / 场景	skills.manage install-from-market（§3）
用户自己写的 / 仓库里的 SKILL.md	Skill / 场景	交给 create-skill skill（§3.2）
command + args，或一个 MCP 的 http url	MCP	mcp.manage upsert（§4）

分不清时先问用户，不要凭包名猜类型：npm 上的 @modelcontextprotocol/server-* 是 MCP，不是 Vetta 插件。

1. 通用前置

• 只在用户明确要求安装时执行。当前任务缺某个工具，不构成自行安装能力的理由。
• 所有写操作都会弹宿主审批。用户拒绝就停下并如实报告，不要改走别的路子达成同一效果。
• 禁止直接改注册表：~/.vetta/plugins/、~/.vetta/plugins-manifest.json、~/.vetta/skills-manifest.json（市场安装的部分）、~/.vetta/agent/mcp.json 都由宿主维护，手写会与宿主状态错位。
• 安装源来自用户。第三方 zip / http 链接在安装前把来源念给用户确认一次。

2. 插件

2.1 命令入口

npx @vetta-org/plugin-cli add <npm-package|./local.zip|https://…/x.zip|.>
npx @vetta-org/plugin-cli reload <plugin-id>

. 表示「当前插件工程」（会先 pack）。加 --json 便于解析结果。

npx 不可用或离线时，用系统插件「制作插件」内置的同一份 CLI：先 plugins.query → {"operation":"get","id":"plugin-workbench"} 取 rootPath，再

node "{workbenchRoot}/agent/cli/vetta-plugin-cli.js" add <source> --json

CLI 不直接写插件目录，它把请求交给正在运行的宿主校验、审批、安装。npm 包会以关闭生命周期脚本的方式下载，只解出 package.json#vetta.archive 声明的那个归档。

2.2 安装后必须重载（本 skill 的核心）

• 首次安装：宿主直接启用，输出 Installed <id>@<version>. —— 到此结束。

• 覆盖升级已装插件：宿主把新版本挂成 pending，输出

  Installed <id>@<old>. Update <new> is pending reload. Run `vetta-plugin-cli reload <id>` to apply it.

  此刻插件仍在跑旧代码。安装动作没有完成，必须立刻重载：

  npx @vetta-org/plugin-cli reload <plugin-id>

--json 下的判据（不要靠读人类文案）：

字段	含义	动作
result.plugin.pendingVersion 非空	新版本待应用	必须 reload
reload 返回 plugin.activeVersion	当前生效版本	应等于刚装的版本，否则报告异常

reload 走与 UI 相同的宿主审批流，用户确认后新版本才生效。

2.3 热更新是例外

改已安装插件、或对方是开发中的工程时，先 plugins.query → get <id>：

• 返回项含 devWatch → 热更新已开启，源码构建成功后自动重载。不要 reload、不要重装。
• 无 devWatch → 走 §2.1 / §2.2 常规流程。

开发迭代（不是安装）可以直接开热更新：在插件工程目录 npx @vetta-org/plugin-cli watch，--stop 关闭。

2.4 没有 CLI 时的等价调用

plugins.manage {"operation":"install-from-url","url":"https://…/x.zip"}
plugins.manage {"operation":"reload","id":"<plugin-id>"}

本地路径安装用 install-from-path（zip 绝对路径 + "enable": true）。若目标是「制作插件」工作台里的工程，改为引导用户点面板的「应用到 Vetta」，那条路径不弹确认。

2.5 退出码

0 成功 · 2 参数错 · 3 连不上宿主（Vetta 没运行，或 VETTA_CONFIG_DIR/VETTA_HOME 指到了别的环境）· 4 宿主拒绝（权限、id 冲突、系统插件不可覆盖）· 5 其它失败。遇到 3 先让用户确认 Vetta 桌面端在前台运行，不要反复重试。

2.6 能力市场里的插件

市场插件没有 Agent 侧的按 slug 安装动作。用 navigation.open 打开能力市场页，让用户点安装；装完再按 §2.7 校验即可。

2.7 校验

plugins.query → {"operation":"get","id":"<id>"}，确认 enabled === true、activeVersion 是目标版本、pendingVersion 不存在。

3. Skill 与场景

3.1 从能力市场装

skills.manage {"operation":"install-from-market","type":"skill","slug":"<slug>"}

type 为 "skill" 或 "scene"。slug 不确定就别猜：用 navigation.open 打开能力市场让用户挑，拿到准确 slug 再装。

Skill 不需要 reload，装完即进入能力页。校验：skills.query {"operation":"manifest"}，确认目标 name 在清单里且 enabled: true。

3.2 本地 / 自己写的 Skill

不要在这里手搓目录和清单——按 create-skill skill 的流程做（全局 ~/.vetta/skills/<name>/、项目 <root>/.vetta/skills/<name>/、插件 agent/skills/<name>/ 各有各的注册方式）。

3.3 启停与卸载

skills.manage {"operation":"set-enabled","name":"<name>","enabled":false}
skills.manage {"operation":"uninstall","name":"<name>"}

卸载前先 skills.query manifest 核对真实 type，类型对不上宿主会直接拒绝。

4. MCP 服务器

mcp.manage {"operation":"upsert","name":"filesystem",
  "data":{"command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/abs/dir"]}}

mcp.manage {"operation":"upsert","name":"remote",
  "data":{"type":"http","url":"https://example.com/mcp","headers":{"Authorization":"Bearer …"}}}

• 缺省是 stdio；http 必须显式写 "type":"http"。可选字段：env、cwd、disabled、autoApprove、startupTimeout、debug。
• 密钥只从用户处取，放进 env / headers，不要写进仓库文件、不要回显到聊天里。
• upsert 同名即覆盖，用它做「更新配置」，不要先 remove 再加。
• 校验：mcp.query {"operation":"get","name":"<name>"}（密钥字段会脱敏）。起不来时，先把 command args 在终端手跑一次看报错，再改配置——不要靠反复 upsert 试。
• 停用 / 删除：mcp.manage set-enabled / remove。
• 新装 MCP 的工具在当前会话里可能要等宿主重连才出现。这不是安装失败，别为了让工具出现而重装。

5. 报告

安装结束后向用户说明：装了什么类型、id/name 与版本、是否执行了 reload 及重载后的 activeVersion、校验结果，以及任何被用户拒绝或未能执行的步骤。不要把「已提交安装请求」说成「已安装成功」。