Registry API

Registry API 有两层：Cloudflare 上的公开 catalog API，以及本机 Jarvis 的受保护安装 API。

公开插件市场 API

公开 API 挂在 https://jarvis.xcos.dev/plugins/api/v1。

方法	路径	用途
`GET`	`/health`	Registry Worker 健康检查
`GET`	`/catalog`	返回 marketplace 卡片列表
`GET`	`/extensions/{publisher}/{name}`	返回扩展详情
`GET`	`/extensions/{publisher}/{name}/versions`	返回版本列表
`GET`	`/extensions/{publisher}/{name}/versions/resolve`	按 channel 或 version 解析 envelope
`GET`	`/extensions/{publisher}/{name}/versions/{version}/download`	下载 `.jarvispack` artifact
`GET`	`/extensions/packs/{pack_id}/versions/resolve`	按 pack id 解析 envelope
`POST`	`/publications/initiate`	受保护的官方插件发布初始化
`PUT`	`/publications/{publication_id}/artifacts/pack`	上传与 manifest 匹配的 `.jarvispack`
`POST`	`/publications/{publication_id}/complete`	校验、签名并提升为 dynamic catalog 版本
`GET`	`/publications/{publication_id}`	查询发布状态

catalog、resolve、download 和 health 不需要本机 Jarvis API key。publication API 需要 registry 配置的 publisher bearer token，当前只面向官方/canonical 发布路径。

本机 Jarvis API

本机安装 API 挂在 http://127.0.0.1:8888/api/v1/extensions，需要 Jarvis API key。

方法	路径	用途
`GET`	`/registry`	查看 registry 是否启用、catalog 是否可达
`POST`	`/registry/preview`	解析 pack、校验签名和展示安装计划
`POST`	`/registry/install`	下载、校验并安装扩展包
`POST`	`/packs/{pack_id}/updates/check`	检查 registry-managed pack 是否有新版本，并返回 diff/review 信息
`POST`	`/packs/{pack_id}/updates/apply`	在审查通过后下载、校验并应用更新

Preview 请求

{
  "pack_id": "jarvis.memagora",
  "channel": "stable",
  "version": null
}

响应会包含 artifact URL、sha256、签名 key 和原生依赖预览。

Install 请求

{
  "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>"
}

安装前本机 Jarvis 会检查：

Registry 已启用；
catalog entry 允许安装；
envelope 签名可信；
artifact hash 匹配；
原生依赖策略满足要求。

Update apply 请求

{
  "channel": "stable",
  "enable": true,
  "install_native_dependencies": true,
  "accept_capability_changes": true,
  "expected_artifact_sha256": "<sha256-from-check-candidate>",
  "expected_signature_key_id": "<key-id-from-check-candidate>",
  "expected_review_fingerprint": "<fingerprint-from-check-candidate>"
}

如果 candidate 没有新增权限、host capability 或 native dependency，accept_capability_changes 可以为 false。如果有能力变化但调用方没有显式接受，Jarvis 返回 409。

Publication initiate 请求

{
  "schemaVersion": 1,
  "kind": "jarvis.pluginPublication",
  "plugin": {
    "id": "jarvis.memagora",
    "publisher": "jarvis",
    "name": "memagora",
    "displayName": "MemAgora",
    "version": "0.3.3"
  },
  "artifact": {
    "mediaType": "application/vnd.jarvis.extension-pack+zip",
    "fileName": "jarvis.memagora-0.3.3.jarvispack",
    "size": 12345,
    "sha256": "<artifact-sha256>"
  },
  "capabilities": {
    "profiles": ["knowledge-curator"],
    "workflows": ["knowledge-curation"],
    "commands": ["/curate-knowledge"],
    "internalMcpServers": [
      { "id": "memagora", "tools": ["search", "fetch", "upload"] }
    ]
  },
  "nativeDependencies": [
    {
      "id": "memagorad",
      "version": "0.1.0",
      "required": true,
      "installMode": "host-managed"
    }
  ]
}

示例中的 artifact.size 要替换为实际字节数。发布流程会拒绝 size/hash 不匹配、非 zip pack、manifest identity 不一致、非受支持 publisher、重复版本覆盖和低于当前 latest 的版本。