skillhub/docs/06-api-design.md
XiaoSeS 36824d33b7 docs: complete remaining deployment and navigation gaps in issue 1042
Signed-off-by: XiaoSeS <87064762+XiaoSeS@users.noreply.github.com>
2026-11-02 15:38:30 +08:00

604 lines
29 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# skillhub API 设计
## 0. 标识类型约束
- 所有 API 中出现的用户标识一律为 `string`。
- 该约束覆盖路径参数、query 参数、请求体字段、响应 DTO 字段,以及统一响应结构中的业务数据内容。
- 任何旧草案中的整型用户标识写法都已失效,前后端正式契约只允许字符串用户标识。
## 1. 响应结构规范
除文件下载、文件内容读取这类二进制流接口外,所有 JSON API 必须统一使用以下成功响应结构:
```json
{
"code": 0,
"msg": "成功",
"data": {},
"timestamp": "2026-03-12T06:00:00Z",
"requestId": "req-123"
}
```
约束如下:
- `code`:成功时固定为 `0`;失败时固定为 HTTP 状态码,例如 `400`、`401`、`403`、`500`。
- `msg`:返回给调用方的用户可读提示文案,必须通过 Spring Boot `MessageSource` + i18n 机制生成,禁止在 controller 中硬编码。
- `msg` 的 locale 必须在响应封装层或全局异常处理层通过 `LocaleContextHolder` 从请求上下文自动获取,禁止在 controller/service 中显式传递 `Locale`。
- `data` 承载实际业务数据;列表、分页对象、详情对象、操作结果对象都必须放在 `data` 下。
- 分页响应统一使用 `{ items, total, page, size }`,禁止直接暴露 Spring `Page` 的 `content/pageable/sort/first/last` 等内部结构。
- `timestamp`:响应创建时间戳,由后端统一自动生成。
- `requestId`:请求链路 ID,由后端统一注入,便于日志追踪。
- Controller 层禁止直接返回 `Map`、裸 DTO、裸 `Page`、裸 `List` 作为 JSON 成功响应。
- 普通 JSON 接口应直接返回统一响应 DTO;仅文件下载、文件预览等需要自定义状态码或 header 的二进制接口保留 `ResponseEntity`。
- 删除、撤销、移动标签等操作也必须返回统一 JSON 结构;如无实体数据,返回 `data.message` 或 `data=null`,但外层结构不得变化。
- 错误响应与成功响应使用同一外层结构,不再使用单独的异常 JSON 结构。
- 异常链路中的 `msg` 也必须通过 Spring Boot 标准 i18n 机制生成;参数校验异常、领域异常、认证鉴权异常都必须进入统一的 `@RestControllerAdvice` 出口。
- 二进制流接口保持原始 HTTP 语义,不套 `code/data` 包装:
- `/download`
- `/file`
- 其他返回 `application/octet-stream`、`application/zip` 等内容类型的接口
成功响应示例:
```json
{
"code": 0,
"msg": "发布成功",
"data": {
"skillId": 123,
"version": "1.0.0"
},
"timestamp": "2026-03-12T06:00:00Z",
"requestId": "req-123"
}
```
错误响应示例:
```json
{
"code": 403,
"msg": "需要命名空间管理员或所有者权限",
"data": null,
"timestamp": "2026-03-12T06:00:00Z",
"requestId": "req-123"
}
```
## 7.1 Public API(匿名可访问)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/skills` | 搜索/列表(匿名仅返回 PUBLIC 技能) |
| GET | `/api/v1/skills/{namespace}/{slug}` | 技能详情(PUBLIC 匿名可访问) |
| GET | `/api/v1/skills/{namespace}/{slug}/versions` | 版本列表 |
| GET | `/api/v1/skills/{namespace}/{slug}/versions/{version}` | 版本详情 |
| GET | `/api/v1/skills/{namespace}/{slug}/versions/{version}/files` | 文件清单 |
| GET | `/api/v1/skills/{namespace}/{slug}/versions/{version}/file?path=...` | 读取单个文件(query param 避免路径中 / 的解析问题) |
| GET | `/api/v1/skills/{namespace}/{slug}/download` | 按原始 latest 指针选择版本,再检查下载权限;公开分发须已发布,管理预览例外见[生命周期读模型](./14-skill-lifecycle.md#32-lifecycle-projection) |
| GET | `/api/v1/skills/{namespace}/{slug}/versions/{version}/download` | 下载指定版本包 |
| GET | `/api/v1/skills/{namespace}/{slug}/resolve` | 解析技能版本(支持 query param: `version`、`tag`、`hash`) |
| GET | `/api/v1/skills/{namespace}/{slug}/tags/{tagName}/download` | 按标签下载(解析标签指向的版本后下载) |
| GET | `/api/v1/skills/{namespace}/{slug}/tags/{tagName}/files` | 按标签查看文件清单 |
| GET | `/api/v1/skills/{namespace}/{slug}/tags/{tagName}/file?path=...` | 按标签读取单个文件 |
| GET | `/api/v1/skills/{skillId}/reviews` | 公开评价分页列表;仅返回可见评价,管理员可见隐藏项 |
| GET | `/api/v1/namespaces` | 公开命名空间列表 |
| GET | `/api/v1/namespaces/{slug}` | 命名空间详情 |
版本列表支持 `page`(从 0 开始)、`size` 和可选 `downloadableOnly`(缺省 `false`)。`true` 仅返回已发布、下载就绪且未撤回的版本,先过滤和排序后分页,`total` 为过滤后的数量。公开列表按发布时间倒序、空时间靠后,再按创建时间和 ID 倒序稳定排序。管理者缺省读取保留生命周期分组和未发布历史。过滤不探测对象存储,实际下载仍可能因文件缺失或网络错误失败。
Public API 的可见性规则:
- `PUBLIC` 技能:若存在已发布版本,则已登录用户可访问;匿名访问仍受下载/resolve 端点的 namespace 类型限制
- `NAMESPACE_ONLY` 技能:仅该命名空间成员可访问(需登录)
- `PRIVATE` 技能:owner 本人 + 该 namespace 的 ADMIN 以上可访问(需登录)
- 若 `latest_version_id = null`,即使 `visibility=PUBLIC`,skill 也不会对外公开,只有 owner 可访问
- `hidden=true` 时,普通访客不可访问;仅 owner 或该 namespace 的 `ADMIN` / `OWNER` 可访问
### 技能详情的公共页面地址
`GET /api/v1/skills/{namespace}/{slug}` 的 `data.webUrl` 是可空的 URI 字符串,
指向该技能的 SkillHub 网页详情,而非作者自定义外站地址,也不是 CLI `resolve` 响应字段。
它只取自部署配置 `skillhub.public.base-url`(环境变量 `SKILLHUB_PUBLIC_BASE_URL`),
不根据请求的 Host 或转发头推测地址,不改变技能原有访问权限。
- 有效配置须为带主机的 HTTP(S) 地址,不能包含用户凭据、查询参数或片段。
- 配置缺省、空白或不符合上述校验时返回 `null`;客户端应隐藏该跳转入口,不拼造链接。
- 保留公开地址中的子路径,去掉结尾斜杠,再追加 `/space/{namespace}/{slug}`。
两个路径段分别按 UTF-8 URL 编码,空格为 `%20`,段内斜杠为 `%2F`。
- 例如公开地址 `https://skills.example.com/portal/` 和技能 `team/demo`,
返回 `https://skills.example.com/portal/space/team/demo`。
实现与边界测试:[SkillWebUrls](../server/skillhub-app/src/main/java/com/iflytek/skillhub/service/SkillWebUrls.java)、
[SkillWebUrlsTest](../server/skillhub-app/src/test/java/com/iflytek/skillhub/service/SkillWebUrlsTest.java)。
`GET /api/v1/skills/{namespace}/{slug}/versions/{version}` 的 `data` 字段除版本基础信息外,还必须包含:
- `parsedMetadataJson`:`SKILL.md` frontmatter 的完整 JSON 序列化结果
- `manifestJson`:版本文件清单摘要 JSON
## 7.2 Auth API(登录与会话相关)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/oauth2/authorization/github` | 发起 GitHub OAuth 登录(Spring Security 内置) |
| GET | `/login/oauth2/code/github` | GitHub OAuth 回调(Spring Security 内置) |
| GET | `/api/v1/auth/me` | 当前用户信息(未登录返回 401) |
| POST | `/api/v1/auth/logout` | 登出(清除 Session) |
| GET | `/api/v1/auth/providers` | 可用的 OAuth Provider 列表(前端渲染登录按钮用) |
| GET | `/api/v1/auth/methods` | 统一登录方式目录(密码/OAuth/direct/bootstrap 元数据) |
| POST | `/api/v1/auth/direct/login` | 显式走直连认证 provider 的兼容登录入口(默认关闭) |
| POST | `/api/v1/auth/session/bootstrap` | 显式尝试用外部被动会话换取 skillhub Session(默认关闭) |
`/api/v1/auth/providers` 响应示例:
```json
{
"code": 0,
"msg": "获取成功",
"data": [
{ "id": "github", "name": "GitHub", "authorizationUrl": "/oauth2/authorization/github" }
],
"timestamp": "2026-03-12T06:00:00Z",
"requestId": "req-123"
}
```
前端根据此接口动态渲染登录按钮,新增 Provider 无需改前端代码。
`/api/v1/auth/methods` 返回统一登录方式目录。典型项包括:
- `PASSWORD`:现有本地账号密码登录
- `OAUTH_REDIRECT`:OAuth 跳转登录
- `DIRECT_PASSWORD`:默认关闭的直连认证兼容入口
- `SESSION_BOOTSTRAP`:默认关闭的被动会话引导入口
示例:
```json
{
"code": 0,
"msg": "获取成功",
"data": [
{
"id": "local-password",
"methodType": "PASSWORD",
"provider": "local",
"displayName": "Local Account",
"actionUrl": "/api/v1/auth/local/login"
},
{
"id": "oauth-github",
"methodType": "OAUTH_REDIRECT",
"provider": "github",
"displayName": "GitHub",
"actionUrl": "/oauth2/authorization/github"
}
],
"timestamp": "2026-03-12T06:00:00Z",
"requestId": "req-123"
}
```
`/api/v1/auth/session/bootstrap` 请求示例:
```json
{
"provider": "private-sso"
}
```
`/api/v1/auth/session/bootstrap` 协议约束:
- 开源版默认关闭,需显式开启 `skillhub.auth.session-bootstrap.enabled=true`
- 关闭时返回 `403`
- provider 不存在时返回 `400`
- 外部会话不存在或校验失败时返回 `401`
- 成功时返回与 `/api/v1/auth/me` 相同的用户结构,并建立标准 Session
`/api/v1/auth/direct/login` 请求示例:
```json
{
"provider": "private-sso",
"username": "alice",
"password": "secret"
}
```
`/api/v1/auth/direct/login` 协议约束:
- 开源版默认关闭,需显式开启 `skillhub.auth.direct.enabled=true`
- 关闭时返回 `403`
- provider 不存在时返回 `400`
- 成功时返回与 `/api/v1/auth/me` 相同的用户结构,并建立标准 Session
- `/api/v1/auth/local/login` 继续保留,作为现有本地账号入口
## 7.3 Authenticated API(需登录)
| 方法 | 路径 | 说明 |
|------|------|------|
| PUT | `/api/v1/skills/{skillId}/star` | 收藏 |
| GET | `/api/v1/skills/{skillId}/star` | 当前用户收藏状态 |
| DELETE | `/api/v1/skills/{skillId}/star` | 取消本人收藏(幂等) |
| PUT | `/api/v1/skills/{skillId}/rating` | 评分 |
| GET | `/api/v1/skills/{skillId}/rating` | 当前用户评分状态 |
| GET | `/api/v1/skills/{skillId}/reviews/me` | 当前用户的评分与文字评价 |
| PUT | `/api/v1/skills/{skillId}/reviews/me` | 新增或更新当前用户评价(`score` 1-5,`reviewText` 最长 2000) |
| DELETE | `/api/v1/skills/{skillId}/reviews/me` | 删除文字评价并保留星级评分 |
| GET | `/api/v1/me/stars` | 我的收藏列表 |
| GET | `/api/v1/me/skills` | 我发布的技能列表 |
收藏与评分同样支持 `/api/web` 路由。上述 `GET` / `PUT star`、`GET` / `PUT rating`
在读取状态或写入前,按技能详情的对象可见性策略检查当前用户、空间角色和平台角色。
存在但不可访问的技能返回 `403`,不存在返回 `404`;拒绝不会新增收藏、评分或统计事件。
合法的所有者、空间管理员及超级管理员仍按现有访问策略处理,不统一禁止私有技能互动。
`GET /me/stars` 在数据库计数、排序与分页之前过滤当前无权访问的技能。
技能转私有、被隐藏或用户失去空间角色后,旧收藏不能继续返回技能名称、摘要等信息。
收藏关系仍保留,恢复访问后可再次显示;不因当前不可访问而自动删除历史收藏或评分。
`DELETE star` 只操作当前用户自己的收藏,可在失去访问权限后继续幂等清理,不返回目标技能信息。
本次不改变归档技能和未发布技能的既有可见性规则,也不增加数据库业务约束。
### 已上传版本与审核提交
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/skills/{namespace}/{slug}/versions/{version}/withdraw-review` | 撤回提审(PENDING_REVIEW → UPLOADED,同时删除关联的 PENDING review_task) |
| POST | `/api/v1/reviews` | 提交指定 `skillVersionId` 进入审核队列 |
| POST | `/api/v1/skills/{namespace}/{slug}/submit-review` | 提交 `UPLOADED` 或兼容 `DRAFT` 版本;body 为 `version`、`targetVisibility`(`PUBLIC` / `NAMESPACE_ONLY`) |
| POST | `/api/v1/skills/{namespace}/{slug}/confirm-publish` | 确认发布 PRIVATE 技能的 `UPLOADED` 或兼容 `DRAFT` 版本;body 为 `version` |
### 标签管理
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/skills/{namespace}/{slug}/tags` | 列出标签 |
| PUT | `/api/v1/skills/{namespace}/{slug}/tags/{tagName}` | 创建/移动自定义标签(`latest` 为系统保留标签,不可通过此接口操作) |
| DELETE | `/api/v1/skills/{namespace}/{slug}/tags/{tagName}` | 删除自定义标签(`latest` 不可删) |
### 技能可见范围
已发布技能可独立调整范围,不上传新 ZIP、不创建内容版本。`GET/POST /api/v1/skills/{namespace}/{slug}/visibility`(Web 同时支持 `/api/web`)提供当前范围及申请提交;Token 写入需 `skill:publish`,仍需维护权限。扩大范围走统一技能审核,缩小立即生效。请求、响应、扫描和冲突说明见[可见范围使用指南](./skill-visibility.md)。
### 技能生命周期管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/skills/{namespace}/{slug}/archive` | 归档技能(namespace ADMIN 或 owner) |
| POST | `/api/v1/skills/{namespace}/{slug}/unarchive` | 恢复归档(namespace ADMIN 或 owner) |
| DELETE | `/api/v1/skills/{namespace}/{slug}/versions/{version}` | 删除 DRAFT/UPLOADED/REJECTED/SCAN_FAILED 版本;不能删除最后一个版本 |
| POST | `/api/v1/skills/{namespace}/{slug}/versions/{version}/yank` | 撤回已发布版本(namespace ADMIN 或 owner;可选 body `{"reason"}`;API Token 需 `skill:publish`) |
| POST | `/api/v1/skills/{namespace}/{slug}/versions/{version}/rerelease` | 从已发布版本重新发出一个新版本(namespace ADMIN 或 owner) |
当前代码中的 skill 生命周期读模型不再依赖 `latestVersionStatus` / `viewingVersionStatus` 一类拼装字段,而统一使用以下 projection:
- `headlineVersion`:projection 的默认主展示候选;前端可按选中版本或管理预览选择展示内容,不保证每个页面都直接显示该字段
- `publishedVersion`:当前最新已发布版本;能否安装仍需通过可见性与安全门禁
- `ownerPreviewVersion`:owner / namespace 管理者可见、比当前已发布版本更新的未发布版本(排除 `YANKED`);无已发布版本时取最新候选
- `resolutionMode`:`PUBLISHED` / `OWNER_PREVIEW` / `NONE`
其中:
- 默认公开版本展示、安装与搜索以最新已发布版本为候选;显式版本和自定义标签可选择其他 `PUBLISHED` 版本,仍须通过对应入口的授权与就绪检查
- owner 详情页在没有可展示发布版本时,才允许 `headlineVersion` 落到 `ownerPreviewVersion`
- 提升到全局可选择属于来源 skill 的任一 `PUBLISHED` 版本,包括历史版本;不要求等于 `publishedVersion.id`
- `hidden` 是独立治理覆盖层,不属于生命周期状态机
- 常规版本详情与文件预览在技能可见性校验后,允许 owner / namespace `ADMIN` / `OWNER` 查看非发布版本;这不授予安装或下载权限。显式下载另对 `UPLOADED` / `PENDING_REVIEW` 放行有权管理的用户,其他未发布状态不放行。完整边界见 [生命周期文档](./14-skill-lifecycle.md)。
发布成功响应中的 `data` 至少包含以下字段:
- `skillId`
- `namespace`
- `slug`
- `version`
- `status`
- `fileCount`
- `totalSize`
发布状态约束:
- 普通用户上传 PRIVATE 技能:启用扫描时先进入 `SCANNING`,扫描完成后进入 `UPLOADED`;关闭扫描时直接进入 `UPLOADED`。
- 普通用户上传 PUBLIC / NAMESPACE_ONLY 技能必须启用扫描,先进入 `SCANNING`,扫描完成后进入 `PENDING_REVIEW`。扫描执行失败与扫描发现风险是不同结果,不能把进入待审等同于通过安全验收。
- `SUPER_ADMIN` 可免人工审核、免 namespace 成员校验而直接创建 `PUBLISHED` 版本,但不绕过 PUBLIC / NAMESPACE_ONLY 的扫描启用要求,也不表示扫描和安装门禁已通过。
- 撤回审核保留版本记录,将 `PENDING_REVIEW → UPLOADED`;`DRAFT` 是兼容状态,不是当前撤回目标。
- 确认私有发布、提交审核、扫描重试及安装门禁见 [生命周期文档](./14-skill-lifecycle.md),不要只根据发布响应的 `status` 判断可安装性。
## 7.4 Token API(需登录)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/tokens` | 创建 API Token |
| GET | `/api/v1/tokens` | 列出我的 Token |
| DELETE | `/api/v1/tokens/{id}` | 吊销 Token |
## 7.5 CLI API(Bearer Token 认证,CLI 主流程由 Device Flow 获取凭证)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/whoami` | 当前 Bearer Token 对应的用户信息 |
| POST | `/api/v1/publish` | 上传技能包(结果受可见性、扫描和发布权限影响,见发布状态约束) |
| GET | `/api/v1/resolve/{namespace}/{slug}` | 解析版本 |
| GET | `/api/v1/check/{namespace}/{slug}/{version}` | 本地哈希与远端比对 |
### ClawHub CLI 协议兼容层
一期不仅提供 skillhub 自有 CLI API,还必须暴露一组兼容 ClawHub CLI 的 registry API。
- 目标:让现有 ClawHub CLI 可通过配置 registry base URL 直接对接 skillhub
- 范围:一期聚焦覆盖 ClawHub CLI 所依赖的核心接口:查询、版本解析、下载、发布、whoami
- 要求:兼容层优先保持 ClawHub CLI 既有请求/响应语义;若内部领域模型不同,通过 adapter 层完成协议转换,而不是要求客户端适配 skillhub 私有协议
- 要求:兼容层纳入 OpenAPI 或独立兼容协议文档,并作为正式对外契约维护
- 要求:兼容层与 skillhub 自有 `/api/v1/**` 并存,二者共享同一套权限、审计、限流与领域服务
- 非目标:前端页面不直接依赖兼容层;兼容层用于服务已有 ClawHub CLI 和相关自动化脚本
兼容层最少需要覆盖的能力类别:
- Registry metadata:技能查询、技能详情、版本列表、标签/默认版本解析
- Artifact resolution:按技能坐标或版本解析下载地址/下载流
- Publish workflow:包上传与发布结果返回
- Integrity check:版本存在性校验、摘要/哈希比对、whoami/token 上下文确认
如 ClawHub CLI 的现有协议与 skillhub 自有接口存在差异,文档以“兼容 ClawHub CLI 协议”为准,skillhub 内部 API 可继续保持当前风格。
## 7.6 Admin API(需对应平台角色)
Admin API 按最小权限拆分,不再统一要求 SUPER_ADMIN:
### 平台治理接口
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/promotions` | 待审核提升申请列表(需 `SKILL_ADMIN` / `SUPER_ADMIN`;路由不在 `/admin/*` 下) |
| GET | `/api/v1/promotions/{id}` | 提升申请详情(提交人本人或 `SKILL_ADMIN` / `SUPER_ADMIN` 可读) |
| GET | `/api/v1/promotions/source/{sourceSkillId}/state` | 来源团队技能的提升状态和关联全局版本(服务端校验来源管理权限) |
| POST | `/api/v1/promotions/{id}/approve` | 通过提升申请(需 `SKILL_ADMIN` / `SUPER_ADMIN`) |
| POST | `/api/v1/promotions/{id}/reject` | 拒绝提升申请(需 `SKILL_ADMIN` / `SUPER_ADMIN`) |
| GET | `/api/v1/promotion-revocations/pending` | 待审撤销申请(需平台技能管理员) |
| GET | `/api/v1/promotion-revocations/history?page=0&size=20` | 已审核撤销申请历史,服务端分页(需平台技能管理员) |
| GET | `/api/v1/promotion-revocations/{id}` | 撤销申请详情(提交人或平台技能管理员) |
| GET | `/api/v1/promotion-revocations/source/{sourceSkillId}/history` | 来源技能的撤销申请历史(按来源权限读取) |
| POST | `/api/v1/promotion-revocations/{id}/approve` | 审核通过撤销并删除全局派生技能 |
| POST | `/api/v1/promotion-revocations/{id}/reject` | 拒绝撤销申请 |
| POST | `/api/v1/promotion-revocations/source/{sourceSkillId}/direct` | 平台技能管理员直接撤销,仍写申请及审计 |
| POST | `/api/v1/admin/skills/{id}/hide` | 隐藏技能(仅 `SUPER_ADMIN`) |
| POST | `/api/v1/admin/skills/{id}/unhide` | 恢复技能(仅 `SUPER_ADMIN`) |
| POST | `/api/v1/admin/skills/versions/{versionId}/yank` | 撤回已发布版本(`SKILL_ADMIN` / `SUPER_ADMIN`) |
| POST | `/api/v1/admin/skill-reviews/{reviewId}/hide` | 隐藏用户评价(`SKILL_ADMIN` / `SUPER_ADMIN`) |
| POST | `/api/v1/admin/skill-reviews/{reviewId}/restore` | 恢复用户评价(`SKILL_ADMIN` / `SUPER_ADMIN`) |
### 用户治理(需 USER_ADMIN / SUPER_ADMIN)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/admin/users` | 用户列表 |
| GET | `/api/v1/admin/users/{id}` | 用户详情 |
| PUT | `/api/v1/admin/users/{id}/role` | 修改用户角色(USER_ADMIN 不可分配 SUPER_ADMIN,也不可修改已有 SUPER_ADMIN 的角色状态) |
| POST | `/api/v1/admin/users/{id}/approve` | 审批待准入用户 |
| POST | `/api/v1/admin/users/{id}/disable` | 封禁用户 |
| POST | `/api/v1/admin/users/{id}/enable` | 解封用户 |
### 审计(需 AUDITOR / SUPER_ADMIN)
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/admin/audit-logs` | 审计日志查询 |
## 7.7 Namespace 管理 API(需命名空间 OWNER 或 ADMIN)
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/namespaces` | 创建命名空间 |
| PUT | `/api/v1/namespaces/{slug}` | 更新命名空间信息 |
| GET | `/api/v1/namespaces/{slug}/members` | 成员列表 |
| POST | `/api/v1/namespaces/{slug}/members` | 添加成员 |
| PUT | `/api/v1/namespaces/{slug}/members/{userId}/role` | 修改成员角色 |
| DELETE | `/api/v1/namespaces/{slug}/members/{userId}` | 移除成员 |
| GET | `/api/v1/reviews?namespaceId={id}` | 该空间待审核列表 |
| POST | `/api/v1/reviews/{id}/approve` | 空间管理员审核通过 |
| POST | `/api/v1/reviews/{id}/reject` | 空间管理员审核拒绝 |
| POST | `/api/v1/promotions` | 首次提升或再次提交已发布团队版本;后者自动关联原全局技能,均需平台审核 |
| POST | `/api/v1/promotion-revocations` | 来源 owner 或 namespace 管理员申请撤销提升 |
## 7.8 `latest` 语义说明
`latest` 自动跟随最新已发布版本,不可手动移动。
- 对外 `latest` 以 `publishedVersion` 表示的最新已发布版本为准;`skill.latest_version_id` 是内部指针,PRIVATE 上传流程可能指向未发布版本,不能单凭该指针判断已发布或可安装。
- `yank` 当前最新已发布版本时,需要同步重算 `latest_version_id` 指向下一个最新的 `PUBLISHED` 版本;若不存在则允许为 `null`
- `latest` 标签是系统保留、API 不可手动移动的标签。当前 `SkillTagService.listTags` 通过读取授权后,直接按原始 `latest_version_id` 合成该标签,不检查目标版本状态;PRIVATE 未发布指针也可能出现在授权用户的标签列表中。这是列表现状,不代表该版本可以公开下载,解析与下载仍须执行各自门禁。
- 自定义标签(如 `beta`、`stable-2026q1`):允许人工创建和移动,用于固定安装通道
| 场景 | 使用字段 | 说明 |
|------|---------|------|
| 搜索索引内容 | `publishedVersion` | 外部协议仍叫 latest,但内部语义必须等价于最新已发布版本 |
| `/download`(不带版本号) | `latest_version_id`,再做下载权限和版本检查 | 公开分发只允许可安装的发布版本;管理者受限下载与公开分发分开判断 |
| CLI `install @team/skill` | `publishedVersion` | 等同于 `@latest` |
| CLI `install @team/skill@beta` | `skill_tag` 查询 | 自定义标签指向的版本 |
## 7.9 Resolve 接口说明
`GET /api/v1/skills/{namespace}/{slug}/resolve` 用于解析技能版本,支持以下 query param:
| 参数 | 类型 | 说明 |
|------|------|------|
| `version` | string | 精确版本号(如 `1.2.0`) |
| `tag` | string | 标签名(如 `beta`、`latest`) |
| `hash` | string | fingerprint 哈希,用于判断本地版本是否与 registry 同步 |
解析优先级:
1. `version` 和 `tag` 不可同时传,同时传返回 `400 Bad Request`
2. 仅传 `version`:精确匹配版本号
3. 仅传 `tag`:查询 `skill_tag` 表获取 `target_version_id`
4. 仅传 `hash`:遍历已发布版本,比对 fingerprint
5. 均不传:返回最新已发布版本;实现上可由 `latest_version_id` 或等价 published projection 解析
响应:
```json
{
"code": 0,
"msg": "获取成功",
"data": {
"skillId": 456,
"namespace": "team-name",
"slug": "my-skill",
"version": "1.2.0",
"versionId": 123,
"fingerprint": "sha256:abc123...",
"downloadUrl": "/api/v1/skills/team-name/my-skill/versions/1.2.0/download"
},
"timestamp": "2026-03-12T06:00:00Z",
"requestId": "req-123"
}
```
`hash` 匹配时额外返回 `"matched": true`,不匹配时返回最新版本信息 + `"matched": false`。
## 7.10 ClawHub CLI 兼容层 API
兼容层 API 基地址为 `/api/v1`,通过 `/.well-known/clawhub.json` 发现。兼容层使用 canonical slug(双连字符映射规则,详见 `00-product-direction.md` 1.1 节)。
认证方式:`Authorization: Bearer <token>`。Bearer Token 可来自 CLI Device Flow 或平台 API Token。
### Well-known 发现
```
GET /.well-known/clawhub.json
响应:
{
"apiBase": "/api/v1"
}
```
### 兼容层端点
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/v1/whoami` | 当前用户信息 |
| GET | `/api/v1/search` | 搜索技能 |
| GET | `/api/v1/resolve` | 通过 slug + version 解析版本 |
| GET | `/api/v1/download/{slug}/{version}` | 下载技能 zip 包 |
| POST | `/api/v1/publish` | 上传技能(multipart/form-data;状态与安装门禁见发布状态约束) |
### 兼容层请求/响应格式
**GET `/api/v1/whoami`**
```json
{
"handle": "username",
"displayName": "User Name",
"role": "user"
}
```
**GET `/api/v1/search?q={keyword}&page={page}&limit={limit}`**
```json
{
"results": [
{
"slug": "my-skill",
"name": "My Skill",
"description": "...",
"author": { "handle": "username", "displayName": "User Name" },
"version": "1.2.0",
"downloadCount": 100,
"starCount": 50,
"createdAt": "2026-01-01T00:00:00Z",
"updatedAt": "2026-03-01T00:00:00Z"
}
],
"total": 1,
"page": 1,
"limit": 20
}
```
注意:兼容层返回的 `slug` 为 canonical slug 格式(全局空间直接返回 skill slug,团队空间返回 `namespace--skill`)。
**GET `/api/v1/resolve?slug={slug}&version={version}`**
```json
{
"slug": "my-skill",
"version": "1.2.0",
"downloadUrl": "/api/v1/download/my-skill/1.2.0"
}
```
**GET `/api/v1/download/{slug}/{version}`**
返回指定版本的 zip 文件流。默认版本解析由 `resolve` 接口负责。
**POST `/api/v1/publish`**
```
Content-Type: multipart/form-data
Parts:
- file: zip 包
```
一期同步响应,返回发布结果:
```json
{
"slug": "my-skill",
"version": "1.0.0",
"status": "published"
}
```
### 兼容层适配说明
- 兼容层是独立的 Controller 层,内部调用与 native API 相同的领域服务
- 请求进入时将 canonical slug 转换为 `(namespace_id, skill_slug)` 坐标
- 响应返回时将内部坐标转换为 canonical slug
- 兼容层不暴露 namespace 概念,对 ClawHub CLI 透明
- 发布时如果 canonical slug 包含 `--`,解析为团队空间发布;否则发布到全局空间
- 兼容层的认证复用 skillhub Bearer Token 体系,ClawHub CLI 通过登录或配置 token 后即可使用
## 7.11 Rate Limiting
分两阶段实施:
### Phase 1:Ingress 层基础限流
通过 Nginx Ingress `limit-req` 按 IP 全局限流,覆盖认证、搜索、下载等匿名可访问接口,防止基本的滥用和爬虫。
### Phase 2:应用层精细限流
基于 Redis 滑动窗口,按用户/端点分类的精细限流。
| 端点类别 | 限流策略 |
|---------|---------|
| 搜索 API | 已登录 60 次/分钟,匿名 20 次/分钟(按 IP) |
| 下载 API | 已登录 120 次/分钟,匿名 30 次/分钟(按 IP) |
| 发布 API | 10 次/小时(按用户) |
| 认证 API | 30 次/分钟(按 IP) |
触发限流时返回 `429 Too Many Requests` + `Retry-After` Header。
## 7.12 API 设计原则
### Native API(`/api/v1/*`)
- 统一响应包裹:`{ code, message, data, timestamp }`
- 分页格式:`{ items, total, page, size }`
- 错误码体系:业务错误码 + HTTP 状态码配合
- 版本策略:URL path 版本 `/api/v1/`
- 幂等性:写操作通过 `X-Request-Id` + Redis 去重(TTL 24h)
### Compatibility API(`/api/v1/*`)
- 响应格式完全遵循 ClawHub 协议,不套统一响应包裹
- 错误响应遵循 ClawHub 格式:`{ error: string, message: string }`
- 分页格式遵循 ClawHub 格式:`{ results, total, page, limit }`
### OpenAPI 文档分离
生成两份独立的 OpenAPI spec:
- `openapi-native.json`:skillhub Native API,用于前端 SDK 生成
- `openapi-compat-clawhub.json`:ClawHub 兼容层 API,用于兼容性测试和文档