> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 自建插件市场与专家市场

运行 Octop 的机器访问不了 `octop.cloud` 或 `download.octop.cloud` 时，可以在自己的网络里提供这两份目录，不需要部署完整的公网门户。Octop 读取两份 JSON 列表，再按条目里的 `download_url` 下载安装包。

技能市场是另一套服务，见[技能市场](/guide/guides/skill-market.md)。

## Octop 怎么读取目录

```text
打开插件市场或专家市场
        │
        ▼
Octop 进程   GET {OCTOP_PORTAL_ORIGIN}/api/market/plugins
             GET {OCTOP_PORTAL_ORIGIN}/api/market/experts
        │
        │  成功后把 data.items 缓存 30 秒
        ▼
你点击安装
        │
        ▼
Octop 进程   GET 该条目的 download_url
             （协议、主机、端口必须与 OCTOP_MARKET_REMOTE_ORIGIN 一致）
```

两份目录都是一次取全量，Octop 不传查询参数。专家的搜索和场景筛选在本地完成，所以每条专家都要带上 `content` 和 `quick_prompts`。详情页读的是同一份缓存，不会再请求 `/{id}`。

请求不带登录态，把市场放在内网。Octop 不会附带 Token。

单次目录响应不超过 **1 MiB**，必须在 **8 秒**内返回。请求头是 `Accept: application/json` 和 `User-Agent: Octop`。`success` 必须是 JSON 布尔值 `true`，`data.items` 必须是数组，不是对象的元素会被丢掉。HTTP 错误、超时、门户地址为空，或者 `success` 不是 `true`，都算目录不可用，**插件市场**和**专家市场**会显示暂时不可用。

成功结果在进程里缓存 30 秒。改完 JSON 后等一会儿，或重启 Octop，再刷新页面。

## 让 Octop 指向自建市场

在运行 `octop run` 的机器上设置环境变量，然后重启进程。可以写进 `~/.octop/env`（服务启动时会载入），也可以写进 systemd 的 `Environment=`。

```bash
OCTOP_PORTAL_ORIGIN=http://market.internal:9000
OCTOP_MARKET_REMOTE_ORIGIN=http://market.internal:9000
```

| 变量                           | 含义                                                              |
| ---------------------------- | --------------------------------------------------------------- |
| `OCTOP_PORTAL_ORIGIN`        | 目录源站，只写协议、主机和端口，不要带路径。未设置时默认 `https://octop.cloud`。空字符串会关闭远程目录。 |
| `OCTOP_MARKET_REMOTE_ORIGIN` | 安装包源站，同样只写协议、主机和端口。未设置或无法解析时默认 `https://download.octop.cloud`。  |

目录和安装包可以放在同一台机器上，所以上面两个值可以相同。`download_url` 的协议、主机和端口必须与 `OCTOP_MARKET_REMOTE_ORIGIN` 一致。环境变量写了端口时，URL 也要使用该端口。没写端口时，Octop 使用该协议的默认端口。路径和查询参数不限制。

静态安装包可以这样放：

```text
/octop/market/plugins/{id}/{version}/{id}-{version}.zip
/octop/market/experts/{slug}/{version}/{slug}-{version}.zip
```

图标不要指向公网。浏览器直接加载插件卡片的 `icon`。专家的 `icon_url` 若是 `http` 或 `https` 图片，Octop 进程会在创建专家时下载。下载失败时，创建照常继续，只是不用这张图。使用内网能打开的地址，或改用 `icon_name`。

## HTTP 接口

Octop 只调用下面两个列表接口，安装包来自 `download_url`。

```yaml
openapi: 3.0.3
info:
  title: Octop private plugin and expert market
  version: "1"
  description: >
    Catalog read by the Octop server. Octop calls only the two list
    operations. Archive bytes are fetched from download_url.
servers:
  - url: http://market.internal:9000
paths:
  /api/market/plugins:
    get:
      operationId: listMarketPlugins
      summary: Full plugin catalog
      responses:
        "200":
          description: Catalog envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PluginCatalog"
  /api/market/experts:
    get:
      operationId: listMarketExperts
      summary: Full expert catalog
      responses:
        "200":
          description: Catalog envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ExpertCatalog"
components:
  schemas:
    Localized:
      oneOf:
        - type: string
        - type: object
          properties:
            zh: { type: string }
            en: { type: string }
    PluginCatalog:
      type: object
      required: [success, data]
      properties:
        success: { type: boolean, enum: [true] }
        data:
          type: object
          required: [items]
          properties:
            items:
              type: array
              items: { $ref: "#/components/schemas/Plugin" }
    ExpertCatalog:
      type: object
      required: [success, data]
      properties:
        success: { type: boolean, enum: [true] }
        data:
          type: object
          required: [items]
          properties:
            items:
              type: array
              items: { $ref: "#/components/schemas/Expert" }
    Plugin:
      type: object
      required: [id, version, download_url]
      properties:
        id: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$" }
        version: { type: string }
        name: { $ref: "#/components/schemas/Localized" }
        description: { $ref: "#/components/schemas/Localized" }
        kind: { type: string, default: tool }
        icon: { type: string, description: "Emoji, or an http(s) URL the browser can load" }
        group: { type: string }
        requires:
          type: array
          items: { type: string }
        download_url: { type: string, format: uri }
        updated_at: { type: string, description: "ISO-8601. Octop sorts newer stamps first." }
    Expert:
      type: object
      required: [slug, download_url]
      properties:
        id: { type: string }
        slug: { type: string, pattern: "^[A-Za-z0-9][A-Za-z0-9._-]{0,80}$" }
        label: { $ref: "#/components/schemas/Localized" }
        description: { $ref: "#/components/schemas/Localized" }
        scene: { type: string }
        sub_scene: { type: string }
        icon_url: { type: string, description: "http(s) raster image, or omit and use icon_name" }
        icon_name: { type: string }
        color: { type: string }
        skill_slugs:
          type: array
          items: { type: string }
        skill_count: { type: integer }
        content: { $ref: "#/components/schemas/Localized" }
        quick_prompts:
          type: array
          items:
            type: object
            properties:
              title: { $ref: "#/components/schemas/Localized" }
              description: { $ref: "#/components/schemas/Localized" }
              prompt: { $ref: "#/components/schemas/Localized" }
              color: { type: string }
              icon_name: { type: string }
        task_examples:
          type: object
          properties:
            zh: { type: array, items: { type: string } }
            en: { type: array, items: { type: string } }
        download_url: { type: string, format: uri }
        updated_at: { type: string }
```

`id` 和 `slug` 以字母或数字开头，后面可以是字母、数字、`.`、`_`、`-`，总共最长 81 个字符。

安装插件时，目录里的 `version` 必须和压缩包内 `plugin.yaml` 的 `version` 逐字一致，`id` 也必须一致。安装专家时，压缩包里 `manifest.json` 的 `id` 必须等于目录里的 `slug`。

`updated_at` 使用同一种 ISO-8601 写法，例如 `2026-10-26T00:00:00Z`。Octop 按这个字符串倒序排列。

已知的插件分组会显示成翻译后的标签，其他字符串归到**其他**：`lifestyle`、`news`、`finance`、`media`、`fun`、`games`、`tools`、`ops`。

已知的专家场景会翻译，其他字符串按原文显示：`ecommerce`、`finance`、`content-creation`、`lifestyle`、`marketing`、`mysticism`、`academic`、`legal`、`tech`、`education`、`healthcare`、`hr`、`media`、`design`。

## 最小部署

同一源站同时提供目录和文件时，目录可以这样放：

```text
/srv/market/
├── api/market/plugins          # Content-Type: application/json
├── api/market/experts
└── octop/market/
    ├── plugins/weather/0.1.0/weather-0.1.0.zip
    └── experts/ops-engineer/1.0.0/ops-engineer-1.0.0.zip
```

`api/market/plugins` 的正文：

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "weather",
        "version": "0.1.0",
        "name": { "zh": "天气", "en": "Weather" },
        "description": { "zh": "查询城市天气", "en": "City weather" },
        "kind": "tool",
        "icon": "☀️",
        "group": "lifestyle",
        "requires": [],
        "download_url": "http://market.internal:9000/octop/market/plugins/weather/0.1.0/weather-0.1.0.zip",
        "updated_at": "2026-10-26T00:00:00Z"
      }
    ]
  }
}
```

用 Nginx 把这个目录挂到任意端口，下面的 `9000` 只是示例。改端口时，环境变量和每条 `download_url` 里的端口也要一起改。`api/market/plugins` 和 `api/market/experts` 没有扩展名，需要自己标成 JSON：

```nginx
server {
    listen 9000;
    server_name market.internal;
    root /srv/market;
    location /api/market/ {
        default_type application/json;
    }
}
```

设好两个环境变量并重启 Octop，**插件市场**和**专家市场**应列出你的条目。安装时只会向 `market.internal` 请求 ZIP。

## 市场打不开时

| 你看到的现象           | 要检查的地方                                                                                        |
| ---------------- | --------------------------------------------------------------------------------------------- |
| 插件市场或专家市场显示暂时不可用 | 列表请求失败、超时，或 `OCTOP_PORTAL_ORIGIN` 为空。在 Octop 所在机器上 `curl` 两个列表地址，确认 8 秒内返回 `"success": true`。 |
| 卡片在，安装却提示没有安装包   | `download_url` 的协议、主机或端口与 `OCTOP_MARKET_REMOTE_ORIGIN` 不一致。                                   |
| 安装后版本对不上         | 目录 `version` 与 `plugin.yaml` 不一致，或专家 `slug` 与 `manifest.json` 的 `id` 不一致。                     |
| 改了 JSON，页面不变     | 进程内缓存大约 30 秒。等待，或重启 Octop。                                                                    |
| 图标是空白            | 图标地址仍指向公网。改成 emoji、`icon_name`，或浏览器和 Octop 都能打开的地址。                                           |
