install-ability
在本机 Astravia 中安装能力——插件(plugin)、Skill/场景(scene)与 MCP 服务器。用户说「装一个插件 / install plugin / 从能力市场安装 / 加一个 MCP server / 配置 MCP / 装个 skill」,或插件装完没生效、需要 reload、pending 版本没应用时使用。不用于安装 npm 依赖、IDE 插件、浏览器扩展,也不用于开发插件(那是 plugin-workbench)或创作 Skill(那是 create-skill)。
Install
npx skills add https://github.com/maomaochong-ai/open-astravia/tree/main/packages/skill-presets/install-ability
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install maomaochong-ai-open-astravia@llmmart
git clone https://github.com/maomaochong-ai/open-astravia.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole maomaochong-ai/open-astravia collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
在 Astravia 中安装能力
Astravia 的能力分三种,安装路径互不相同。先分类,再动手。
| 用户给的东西 | 类型 | 安装路径 |
|---|---|---|
npm 包名、.zip、http(s) zip 链接、本地插件工程目录 |
插件 | astravia-plugin-cli add → 按需 reload(§2) |
| 能力市场里的插件条目 | 插件 | 引导用户在能力市场页安装(§2.6) |
| 能力市场里的 skill(有 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,不是 Astravia 插件。
1. 通用前置
- 只在用户明确要求安装时执行。当前任务缺某个工具,不构成自行安装能力的理由。
- 所有写操作都会弹宿主审批。用户拒绝就停下并如实报告,不要改走别的路子达成同一效果。
- 禁止直接改注册表:
~/.astravia/plugins/、~/.astravia/plugins-manifest.json、~/.astravia/skills-manifest.json(市场安装的部分)、~/.astravia/agent/mcp.json都由宿主维护,手写会与宿主状态错位。 - 安装源来自用户。第三方 zip / http 链接在安装前把来源念给用户确认一次。
2. 插件
2.1 命令入口
npx @astravia-org/plugin-cli add <npm-package|./local.zip|https://…/x.zip|.>
npx @astravia-org/plugin-cli reload <plugin-id>
. 表示「当前插件工程」(会先 pack)。加 --json 便于解析结果。
npx 不可用或离线时,用系统插件「制作插件」内置的同一份 CLI:先 plugins.query → {"operation":"get","id":"plugin-workbench"} 取 rootPath,再
node "{workbenchRoot}/agent/cli/astravia-plugin-cli.js" add <source> --json
CLI 不直接写插件目录,它把请求交给正在运行的宿主校验、审批、安装。npm 包会以关闭生命周期脚本的方式下载,只解出 package.json#astravia.archive 声明的那个归档。
2.2 安装后必须重载(本 skill 的核心)
首次安装:宿主直接启用,输出
Installed <id>@<version>.—— 到此结束。覆盖升级已装插件:宿主把新版本挂成 pending,输出
Installed <id>@<old>. Update <new> is pending reload. Run `astravia-plugin-cli reload <id>` to apply it.此刻插件仍在跑旧代码。安装动作没有完成,必须立刻重载:
npx @astravia-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 @astravia-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)。若目标是「制作插件」工作台里的工程,改为引导用户点面板的「应用到 Astravia」,那条路径不弹确认。
2.5 退出码
0 成功 · 2 参数错 · 3 连不上宿主(Astravia 没运行,或 ASTRAVIA_CONFIG_DIR/ASTRAVIA_HOME 指到了别的环境)· 4 宿主拒绝(权限、id 冲突、系统插件不可覆盖)· 5 其它失败。遇到 3 先让用户确认 Astravia 桌面端在前台运行,不要反复重试。
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"。slug 不确定就别猜:用 navigation.open 打开能力市场让用户挑,拿到准确 slug 再装。
Skill 不需要 reload,装完即进入能力页。校验:skills.query {"operation":"manifest"},确认目标 name 在清单里且 enabled: true。
3.2 本地 / 自己写的 Skill
不要在这里手搓目录和清单——按 create-skill skill 的流程做(全局 ~/.astravia/skills/<name>/、项目 <root>/.astravia/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、校验结果,以及任何被用户拒绝或未能执行的步骤。不要把「已提交安装请求」说成「已安装成功」。
Files (open-astravia)
-
ability.json 2.7 KB
Loading… -
SKILL.md 7.4 KB
--- name: install-ability description: 在本机 Astravia 中安装能力——插件(plugin)、Skill 与 MCP 服务器。用户说「装一个插件 / install plugin / 从能力市场安装 / 加一个 MCP server / 配置 MCP / 装个 skill」,或插件装完没生效、需要 reload、pending 版本没应用时使用。不用于安装 npm 依赖、IDE 插件、浏览器扩展,也不用于开发插件(那是 plugin-workbench)或创作 Skill(那是 create-skill)。 metadata: version: 1.0.0 author: Astravia category: 开发 --- # 在 Astravia 中安装能力 Astravia 的能力分三种,安装路径互不相同。**先分类,再动手**。 | 用户给的东西 | 类型 | 安装路径 | | --- | --- | --- | | npm 包名、`.zip`、http(s) zip 链接、本地插件工程目录 | 插件 | `astravia-plugin-cli add` → 按需 `reload`(§2) | | 能力市场里的插件条目 | 插件 | 引导用户在能力市场页安装(§2.6) | | 能力市场里的 skill(有 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,不是 Astravia 插件。 ## 1. 通用前置 - **只在用户明确要求安装时执行**。当前任务缺某个工具,不构成自行安装能力的理由。 - 所有写操作都会弹宿主审批。用户拒绝就**停下并如实报告**,不要改走别的路子达成同一效果。 - **禁止直接改注册表**:`~/.astravia/plugins/`、`~/.astravia/plugins-manifest.json`、`~/.astravia/skills-manifest.json`(市场安装的部分)、`~/.astravia/agent/mcp.json` 都由宿主维护,手写会与宿主状态错位。 - 安装源来自用户。第三方 zip / http 链接在安装前把来源念给用户确认一次。 ## 2. 插件 ### 2.1 命令入口 ```bash npx @astravia-org/plugin-cli add <npm-package|./local.zip|https://…/x.zip|.> npx @astravia-org/plugin-cli reload <plugin-id> ``` `.` 表示「当前插件工程」(会先 pack)。加 `--json` 便于解析结果。 npx 不可用或离线时,用系统插件「制作插件」内置的同一份 CLI:先 `plugins.query` → `{"operation":"get","id":"plugin-workbench"}` 取 `rootPath`,再 ```bash node "{workbenchRoot}/agent/cli/astravia-plugin-cli.js" add <source> --json ``` CLI 不直接写插件目录,它把请求交给正在运行的宿主校验、审批、安装。npm 包会以关闭生命周期脚本的方式下载,只解出 `package.json#astravia.archive` 声明的那个归档。 ### 2.2 安装后必须重载(本 skill 的核心) - **首次安装**:宿主直接启用,输出 `Installed <id>@<version>.` —— 到此结束。 - **覆盖升级已装插件**:宿主把新版本挂成 **pending**,输出 ``` Installed <id>@<old>. Update <new> is pending reload. Run `astravia-plugin-cli reload <id>` to apply it. ``` 此刻插件**仍在跑旧代码**。安装动作没有完成,必须立刻重载: ```bash npx @astravia-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 @astravia-org/plugin-cli watch`,`--stop` 关闭。 ### 2.4 没有 CLI 时的等价调用 ```json plugins.manage {"operation":"install-from-url","url":"https://…/x.zip"} plugins.manage {"operation":"reload","id":"<plugin-id>"} ``` 本地路径安装用 `install-from-path`(zip 绝对路径 + `"enable": true`)。若目标是「制作插件」工作台里的工程,改为引导用户点面板的「应用到 Astravia」,那条路径不弹确认。 ### 2.5 退出码 `0` 成功 · `2` 参数错 · `3` 连不上宿主(Astravia 没运行,或 `ASTRAVIA_CONFIG_DIR`/`ASTRAVIA_HOME` 指到了别的环境)· `4` 宿主拒绝(权限、id 冲突、系统插件不可覆盖)· `5` 其它失败。遇到 `3` 先让用户确认 Astravia 桌面端在前台运行,不要反复重试。 ### 2.6 能力市场里的插件 市场插件没有 Agent 侧的按 slug 安装动作。用 `navigation.open` 打开能力市场页,让用户点安装;装完再按 §2.7 校验即可。 ### 2.7 校验 `plugins.query` → `{"operation":"get","id":"<id>"}`,确认 `enabled === true`、`activeVersion` 是目标版本、`pendingVersion` 不存在。 ## 3. Skill ### 3.1 从能力市场装 ```json skills.manage {"operation":"install-from-market","type":"skill","slug":"<slug>"} ``` `type` 为 `"skill"`。**slug 不确定就别猜**:用 `navigation.open` 打开能力市场让用户挑,拿到准确 slug 再装。 Skill 不需要 reload,装完即进入能力页。校验:`skills.query {"operation":"manifest"}`,确认目标 name 在清单里且 `enabled: true`。 ### 3.2 本地 / 自己写的 Skill 不要在这里手搓目录和清单——按 `create-skill` skill 的流程做(全局 `~/.astravia/skills/<name>/`、项目 `<root>/.astravia/skills/<name>/`、插件 `agent/skills/<name>/` 各有各的注册方式)。 ### 3.3 启停与卸载 ```json skills.manage {"operation":"set-enabled","name":"<name>","enabled":false} skills.manage {"operation":"uninstall","name":"<name>"} ``` 卸载前先 `skills.query manifest` 核对真实 `type`,类型对不上宿主会直接拒绝。 ## 4. MCP 服务器 ```json 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**、校验结果,以及任何被用户拒绝或未能执行的步骤。不要把「已提交安装请求」说成「已安装成功」。
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.