插件目录安装

插件目录安装在 main/stable 默认开启，Jarvis 会通过本机后端受控请求公共插件市场；gated 构建会强制关闭该入口。公共网页只负责发现，真正的安装和更新由本机 Jarvis 完成。

配置

默认插件目录根路径是 https://jarvis.xcos.dev/plugins。需要改到私有或测试插件目录时，在本地 .env 中设置：

JARVIS_EXTENSION_REGISTRY_URL=https://jarvis.xcos.dev/plugins

重启 Jarvis 后确认健康状态：

curl http://127.0.0.1:8888/api/v1/health

查看插件目录状态

curl -H "Authorization: Bearer $JARVIS_API_KEY" \
  http://127.0.0.1:8888/api/v1/extensions/registry

默认会返回 catalog_status: ok 并列出 catalog 条目。显式设置 JARVIS_EXTENSION_REGISTRY_ENABLED=0 或 gated 构建时会返回 catalog_status: disabled。

CLI 安装

.venv/bin/jarvis extensions registry-install jarvis.memagora --version 0.3.3 --enable --install-native-dependencies

安装 MemAgora 0.3.3 但不立即启用：

.venv/bin/jarvis extensions registry-install jarvis.memagora --version 0.3.3 --install-native-dependencies

MemAgora 0.3.3 需要 host-managed memagorad。CLI 完整安装时传 --install-native-dependencies；UI 安装会在审查流程中展示并请求确认。

常用选项：

选项	用途
`--version 0.3.3`	安装精确版本
`--channel stable`	解析 channel，默认 `stable`
`--registry-url URL`	临时覆盖插件目录 URL
`--enable`	安装后立即启用
`--install-native-dependencies`	允许安装 host-managed 原生依赖
`--data-dir DIR`	指向非默认 Jarvis data dir

本机 API 安装

预览安装计划：

curl -X POST -H "Authorization: Bearer $JARVIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"pack_id":"jarvis.memagora","channel":"stable"}' \
  http://127.0.0.1:8888/api/v1/extensions/registry/preview

执行安装：

curl -X POST -H "Authorization: Bearer $JARVIS_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "pack_id":"jarvis.memagora",
    "channel":"stable",
    "enable":true,
    "install_native_dependencies":true,
    "expected_artifact_sha256":"<sha256-from-preview>",
    "expected_signature_key_id":"<key-id-from-preview>",
    "expected_review_fingerprint":"<fingerprint-from-preview>"
  }' \
  http://127.0.0.1:8888/api/v1/extensions/registry/install

对于需要原生依赖的插件，执行安装时需要用户审查过的 artifact 字段和原生依赖 consent。普通用户应使用 UI，避免手写 stale review metadata。

更新检查和应用

curl -X POST -H "Authorization: Bearer $JARVIS_API_KEY" \
  http://127.0.0.1:8888/api/v1/extensions/packs/jarvis.memagora/updates/check

有新版本时，Jarvis 会返回 candidate、diff、review fingerprint 和是否需要能力变更确认。应用更新时必须提交用户刚审查过的 expected artifact fields；如果新增权限、host capability 或 native dependency，还必须显式接受能力变化。

失败语义

情况	结果
插件目录被显式关闭	CLI 报 `extension registry is disabled`，API 返回 403
gated 构建	强制视为未开启
catalog 不可达	状态接口返回 `catalog_status: unavailable`
pack 未在 catalog listed 或已下架	安装失败，返回 `registry catalog entry is not listed` 或 resolve 404
签名或 hash 不匹配	安装失败，不能 materialize pack
installability 禁止安装	安装失败并返回 catalog 中的原因
原生依赖缺失	除非显式 `--install-native-dependencies`，否则不安装
更新能力变化未确认	apply 返回 409，要求先审查并接受能力变化

安装后检查

.venv/bin/jarvis extensions list

然后在 Jarvis UI 中检查设置 -> 插件与扩展、配置档、工作流和斜杠命令是否显示扩展来源。