自建技能市场
技能页里的技能市场默认请求 https://api.skillhub.cn。运行 Octop 的机器访问不了公网时,可以在自己的网络里提供下面三个读接口,不需要部署完整的 SkillHub。
插件市场和专家市场是另一套目录,见插件与专家市场。技能包页的从技能市场导入读取 SKILLSET_ORIGIN 上的技能集,集内每个技能的 ZIP 仍从 SKILL_MARKET_ORIGIN 下载。
Octop 怎么调用市场
打开技能市场
│
▼
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=。
SKILL_MARKET_ORIGIN=http://market.internal:9000
只写协议、主机和端口,不要带路径。写成 market.internal:9000 时,Octop 按 https:// 补协议,并丢掉路径、查询或账号信息。实际请求仍是 {源站}/api/v1/...。未设置或空字符串时使用 https://api.skillhub.cn。协议不是 http 或 https,或没有主机名,则这次请求失败,不会悄悄改回公网。
HTTP 接口
搜索和六个榜单路径返回 JSON,下载返回 ZIP,没有合并榜单的路径。
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 进程才能访问的地址。
最小部署
/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 的正文:
{
"results": [
{
"slug": "weather",
"displayName": "天气",
"summary": "查询城市天气",
"version": "0.1.0",
"description_zh": "查询城市天气",
"iconUrl": "http://market.internal:9000/icons/weather.png"
}
]
}
api/v1/showcase/recommended 的正文:
{
"section": "recommended",
"total": 1,
"skills": [
{
"slug": "weather",
"displayName": "天气",
"summary": "查询城市天气",
"version": "0.1.0"
}
]
}
用 Nginx 把这个目录挂到任意端口,下面的 9000 只是示例。没有扩展名的接口需要标成 JSON。下载接口要按 slug 选出 ZIP。静态文件做不到这一点,可以用反向代理。
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 下载每个技能。
在技能包页导入
│
▼
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,或没有主机名,则这次导入失败,不会改回公网。
SKILLSET_ORIGIN=http://market.internal:9000
详情是 JSON 对象,导入会读这些字段:
详情里有 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 全量列表。
搜索或导入失败时