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

# 自建技能市场

**技能**页里的**技能市场**默认请求 `https://api.skillhub.cn`。运行 Octop 的机器访问不了公网时，可以在自己的网络里提供下面三个读接口，不需要部署完整的 SkillHub。

插件市场和专家市场是另一套目录，见[插件与专家市场](/guide/guides/private-market.md)。技能包页的**从技能市场导入**读取 `SKILLSET_ORIGIN` 上的技能集，集内每个技能的 ZIP 仍从 `SKILL_MARKET_ORIGIN` 下载。

## Octop 怎么调用市场

```text
打开技能市场
        │
        ▼
Octop 进程   GET {SKILL_MARKET_ORIGIN}/api/v1/showcase/hot
             GET …/featured  …/newest  …/recommended  …/trending  …/paid
        │
        │  六个榜单分别请求。某一个失败时，其余榜单仍返回。
        ▼
你搜索
        │
        ▼
Octop 进程   GET {SKILL_MARKET_ORIGIN}/api/v1/search?q=…&limit=…
        │
你点击安装
        │
        ▼
Octop 进程   GET {SKILL_MARKET_ORIGIN}/api/v1/download?slug=…
```

请求不带登录态，市场要放在内网。

搜索和榜单超时 **10 秒**，单次 JSON 不超过 **4 MiB**；下载超时 **30 秒**，压缩包不超过 **32 MiB**。请求头带 `User-Agent: octop-skillhub-market/1.0`，搜索和榜单的 `Accept` 是 `application/json`，下载的 `Accept` 是 `application/zip,application/octet-stream,*/*`。

Octop 会把空关键字换成 `a`，并把 `limit` 限制在 1–100。没有单独的 `all` 榜单路径，上面六个路径由 Octop 自己并发请求，再在本地拼成带 `rankings` 的结果。

这些请求失败时，Octop 直接报错，不会调用本机的 `skillhub` 命令。

## 让 Octop 指向自建市场

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

```bash
SKILL_MARKET_ORIGIN=http://market.internal:9000
```

只写协议、主机和端口，不要带路径。写成 `market.internal:9000` 时，Octop 按 `https://` 补协议，并丢掉路径、查询或账号信息。实际请求仍是 `{源站}/api/v1/...`。未设置或空字符串时使用 `https://api.skillhub.cn`。协议不是 `http` 或 `https`，或没有主机名，则这次请求失败，不会悄悄改回公网。

## HTTP 接口

搜索和六个榜单路径返回 JSON，下载返回 ZIP，没有合并榜单的路径。

```yaml
openapi: 3.0.3
info:
  title: Octop private skill market
  version: "1"
  description: >
    Read by the Octop server. Search and the six showcase paths return
    JSON. Download returns a ZIP. There is no combined rankings path.
servers:
  - url: http://market.internal:9000
paths:
  /api/v1/search:
    get:
      operationId: searchSkills
      summary: Search skills
      parameters:
        - in: query
          name: q
          required: true
          schema: { type: string }
        - in: query
          name: limit
          schema: { type: integer, minimum: 1, maximum: 100 }
      responses:
        "200":
          description: Search envelope
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SearchResponse"
  /api/v1/showcase/{kind}:
    get:
      operationId: showcaseSkills
      summary: One ranking section
      parameters:
        - in: path
          name: kind
          required: true
          schema:
            type: string
            enum: [hot, featured, newest, recommended, trending, paid]
      responses:
        "200":
          description: Ranking object. Octop passes it through.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Ranking"
  /api/v1/download:
    get:
      operationId: downloadSkill
      summary: Skill package bytes
      parameters:
        - in: query
          name: slug
          required: true
          schema: { type: string }
      responses:
        "200":
          description: ZIP archive
          content:
            application/zip:
              schema: { type: string, format: binary }
        "404":
          description: Skill is not published
components:
  schemas:
    SearchResponse:
      type: object
      required: [results]
      properties:
        results:
          type: array
          items: { $ref: "#/components/schemas/Skill" }
    Ranking:
      type: object
      properties:
        section: { type: string }
        total: { type: integer }
        skills:
          type: array
          items: { $ref: "#/components/schemas/Skill" }
    Skill:
      type: object
      required: [slug]
      properties:
        slug: { type: string }
        displayName: { type: string }
        name: { type: string }
        summary: { type: string }
        description: { type: string }
        version: { type: string }
        description_zh: { type: string }
        iconUrl: { type: string, description: "http(s) URL the browser can load" }
        downloads: { type: integer }
        installs: { type: integer }
        stars: { type: integer }
        category: { type: string }
        labels:
          type: object
          additionalProperties: true
```

搜索结果里没有 `slug` 的条目会被丢掉。卡片标题优先用 `displayName`，否则用 `name`，再没有就用 `slug`。简介优先用 `summary`，否则用 `description`。`version` 按字符串保存。其余字段原样交给页面，包括 `iconUrl`、`description_zh`、`downloads` 和 `labels`。

榜单对象按原样返回。页面读每个榜单里的 `skills` 数组，元素字段和搜索结果相同。`section` 和 `total` 可以带，但不参与安装。

下载必须是 ZIP，包的根目录要有 `SKILL.md`。如果所有文件都在同一个顶层目录里，且该目录下有 `SKILL.md`，Octop 会去掉这一层。解压后条目不超过 **2000** 个，未压缩总体积不超过 **64 MiB**。符号链接、绝对路径、`..` 和加密条目，Octop 会拒绝。HTTP 404 表示这个 slug 没有安装包。

`iconUrl` 由浏览器直接加载，不要使用只有 Octop 进程才能访问的地址。

## 最小部署

```text
/srv/skill-market/
├── api/v1/search                 # 忽略查询参数时，返回一份固定 JSON 也可以
├── api/v1/showcase/recommended
├── api/v1/showcase/hot
├── api/v1/showcase/featured
├── api/v1/showcase/newest
├── api/v1/showcase/trending
├── api/v1/showcase/paid
└── api/v1/download               # 按 slug 查询参数返回对应 ZIP
```

`api/v1/search` 的正文：

```json
{
  "results": [
    {
      "slug": "weather",
      "displayName": "天气",
      "summary": "查询城市天气",
      "version": "0.1.0",
      "description_zh": "查询城市天气",
      "iconUrl": "http://market.internal:9000/icons/weather.png"
    }
  ]
}
```

`api/v1/showcase/recommended` 的正文：

```json
{
  "section": "recommended",
  "total": 1,
  "skills": [
    {
      "slug": "weather",
      "displayName": "天气",
      "summary": "查询城市天气",
      "version": "0.1.0"
    }
  ]
}
```

用 Nginx 把这个目录挂到任意端口，下面的 `9000` 只是示例。没有扩展名的接口需要标成 JSON。下载接口要按 `slug` 选出 ZIP。静态文件做不到这一点，可以用反向代理。

```nginx
server {
    listen 9000;
    server_name market.internal;
    root /srv/skill-market;
    location /api/v1/showcase/ {
        default_type application/json;
    }
    location = /api/v1/search {
        default_type application/json;
    }
}
```

设好 `SKILL_MARKET_ORIGIN` 并重启 Octop，**技能市场**的榜单和搜索应出现你的条目。安装时只会向这个源站要压缩包。

## 技能集

技能包页的**从技能市场导入**不读上面的榜单，而是先列出专家市场里的卡片。你点导入后，Octop 按卡片的 `slug` 向技能集源站要这一份技能集，再按里面的技能 slug 向 `SKILL_MARKET_ORIGIN` 下载每个技能。

```text
在技能包页导入
        │
        ▼
Octop 进程   GET {SKILLSET_ORIGIN}/api/v1/skillsets/{slug}
        │
        │  详情里没有 skillSlugs 时，再要压缩包
        ▼
Octop 进程   GET {SKILLSET_ORIGIN}/api/v1/skillsets/{slug}/download
        │
        ▼
Octop 进程   GET {SKILL_MARKET_ORIGIN}/api/v1/download?slug=…   （集内每个技能）
```

在运行 `octop run` 的机器上设置 `SKILLSET_ORIGIN` 后重启。写法和 `SKILL_MARKET_ORIGIN` 相同：只留协议、主机和端口。Octop 对裸主机按 `https://` 补协议，并丢掉路径和查询。未设置或空字符串时使用 `https://api.skillhub.cn`。协议不是 `http` 或 `https`，或没有主机名，则这次导入失败，不会改回公网。

```bash
SKILLSET_ORIGIN=http://market.internal:9000
```

详情是 JSON 对象，导入会读这些字段：

| 字段                        | 用途                                      |
| ------------------------- | --------------------------------------- |
| `slug`                    | 技能集标识，须与路径里的 slug 一致                    |
| `displayName` 或 `name`    | 新建技能包的名称                                |
| `summary` 或 `description` | 技能包说明                                   |
| `iconUrl`                 | 技能包图标，须是 Octop 能访问的 `http` 或 `https` 地址 |
| `scene`                   | 没有图标时，用来选一个内置图标名                        |
| `skillSlugs`              | 要下载的技能 slug 列表                          |

详情里有 `skillSlugs` 时，Octop 不再请求 `/download`。没有这个字段时，`/download` 必须返回 ZIP，里面有 `manifest.json`，并用 `skillSlugs` 或 `skillSets[].skillSlugs` 列出技能。压缩包里还要有一份工作流说明：优先 `skillsets/{slug}.md`，否则任意 `skillsets/*.md`，都没有就用 `identify.md`。详情和压缩包的超时都是 **30 秒**，单次响应不超过 **32 MiB**。详情请求头是 `Accept: application/json`，下载是 `Accept: application/zip,*/*`，`User-Agent` 为 `octop-expert-skillhub/1.0`。

导入不会请求 `GET /api/v1/skillsets` 全量列表。

## 搜索或导入失败时

| 你看到的现象        | 要检查的地方                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| 技能市场仍是公网内容    | `SKILL_MARKET_ORIGIN` 没有进 `octop run` 的环境，或改完没有重启。在 Octop 所在机器上 `curl` 搜索地址，确认 10 秒内返回带 `results` 的 JSON。                 |
| 市场直接报错        | 源站协议或主机名无效，或榜单、搜索没有在时限内返回合法 JSON。                                                                                         |
| 卡片在，安装失败      | `GET /api/v1/download?slug=` 不是 ZIP，包内没有 `SKILL.md`，或超过体积限制。404 表示这个 slug 没有包。                                            |
| 图标是空白         | `iconUrl` 仍指向公网，或浏览器打不开该地址。                                                                                               |
| 技能包导入仍去公网要技能集 | `SKILLSET_ORIGIN` 没有进 `octop run` 的环境，或改完没有重启。导入读的是 `{SKILLSET_ORIGIN}/api/v1/skillsets/{slug}`，不是 `SKILL_MARKET_ORIGIN`。 |
