Forward Skill API 复用的响应与包结构。
Skill 对象
创建、查询、列表接口都会返回该结构；content 与 content_encoding 仅在 查询 Skill 请求 include_content=true 时随响应返回。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Skill ID，前缀为 skill_ |
type | string | 固定值 "skill" |
display_title | string | 展示标题，可与 SKILL 内的 name 独立设置；同一用户下允许重复 |
source | string | Skill 来源，可选值：custom、qoder |
latest_version | string | null | 最新版本标识。三态： • 版本化后为 Unix 微秒时间戳（如 1759178010641129）；• 过渡期未回填时为旧递增计数器（如 2）；• 所有版本被删除后为 null。不保证为可 +1 的递增数字，客户端不应据此推算下一版本 |
metadata | object | 与 Skill 一起存储的自定义元数据对象；省略时为 {}。created_by 为 Forward 保留字段，调用方不可传入 |
created_at | string | 创建时间，RFC 3339 格式 |
updated_at | string | 最后更新时间，RFC 3339 格式 |
identity_id | string | null | Forward 归属身份。归属为某个 Identity 时返回该 Identity ID，否则为 null。详见 Identity 归属 |
icon_url | string | null | Forward 关联的 icon URL |
binding_info | Binding info | 绑定信息（Template 引用计数等） |
description | string | Skill 描述。⚠️ 弃用中：新客户端请改从版本对象读取（见 Skill 版本对象），此字段仅为兼容保留 |
content | string | ⚠️ 弃用中：include_content=true 时返回的 base64 编码 zip 内容；请改用版本内容下载接口 |
content_encoding | string | ⚠️ 弃用中：与 content 成对返回，值固定为 "base64"；请改用版本内容下载接口 |
Identity 归属
一个账户（或 Workspace）下可以创建多个 Identity，每个 Identity 表示该账户（或 Workspace）接入产品中的一个终端用户。
Skill 可以归属于账户（或 Workspace），也可以归属于某个 Identity；Skill Version 始终继承所属 Skill 的归属，不能单独指定 Owner。归属决定了谁能看到和操作该 Skill 及其版本。
如何指定归属
| 调用方 | 归属 | 如何指定 |
|---|---|---|
| PAT | 账户 / Workspace | 不传 identity_id（默认，与此前行为一致） |
| PAT | 指定 Identity | 传查询参数 identity_id=<identity_id> |
| SAT（管理员） | Workspace | 自动解析，不能通过参数切换 |
| SAT（绑定 Identity） | 该 Identity | 自动解析，不能通过参数切换 |
identity_id 仅在操作 Identity 归属资源时使用，非必填；PAT 场景可显式传入，未传时为管理员视角；SAT 场景由凭证确定归属，请签发 Identity 维度凭证且不要显式携带该参数（包括传空值），否则返回 HTTP 400。
PAT 指定的 Identity 必须属于当前 PAT 所代表的账户或 Workspace，且处于启用状态。不存在、已禁用、已删除或不属于当前调用方时返回 404。
归属隔离
- 管理员 Scope 下（PAT 未传
identity_id或 Admin SAT）看不到归属于 Identity 的 Skill。 - 一个 Identity 看不到账户（或 Workspace）本身的 Skill，也看不到同账户下其他 Identity 的 Skill。
- 在有效 Identity Scope 下，跨 Scope 查询、下载、更新或删除统一返回
404，不区分“不存在”与“不属于你”。 - 未传
identity_id的 PAT 和 Admin SAT 保持存量行为，Owner mismatch 返回403；下游服务的权限校验拒绝也可能返回403。 - 创建的幂等键按归属隔离；不同 Identity 可以复用相同
Idempotency-Key，不会互相回放。
支持的接口
创建、搜索、列出、查询、更新、删除 Skill，以及 Skill Version 的列出、创建、查询、内容下载和删除，均支持 Identity Scope。
GET /api/v1/forward/resources/batch 不支持 identity_id，其可见性规则保持不变。Skill 版本对象
列出 Skill 版本、查询 Skill 版本 和 创建 Skill 版本 会返回该结构；版本内容通过 下载 Skill 版本内容 拉取；已有版本可通过 删除 Skill 版本 软删除。版本一经创建后不可变，是内容 + 元信息的独立快照。
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | Skill Version ID，前缀为 skillver_ |
skill_id | string | 所属 Skill 的 ID |
version | string | 版本号。新建版本返回 16 位 Unix 微秒时间戳；latest_version 三态与本字段值域一致 |
name | string | 从上传包 SKILL.md frontmatter name 解析出的规范名 |
description | string | 从上传包 SKILL.md frontmatter description 解析出的描述 |
directory | string | 包内顶层目录名，等于 name |
content_size | integer | 版本包大小，单位 byte；最大 50 MB |
content_sha256 | string | 版本包内容的 SHA-256 摘要（十六进制小写） |
status | string | 版本状态；当前始终为 active |
created_at | string | 创建时间，RFC 3339 格式 |
metadata | object | 版本级元数据，暂固定为 {} |
老版本编号兼容
GET /skills/{id}/versions/{version} 路径段接受两种版本号：
- 推荐：16 位 Unix 微秒时间戳（如
1759178010641129）。 - 兼容：过渡期的老递增计数器（如
"1"、"2"）仍可命中同一条版本记录。传入不存在的老编号返回404。
latest 不受支持（返回 400 invalid_request_error）；请通过 查询 Skill 读取 latest_version 字段拿到当前最新版本号，再拼路径。下载 Skill 版本内容 与 查询 Skill 版本 都遵循这条规则。
Binding info
Forward 在 Skill 响应中携带的引用聚合。
| 字段 | 类型 | 说明 |
|---|---|---|
agent_template_count | integer | 当前绑定该 Skill 的 Template 数量 |
Skill package 上传包规则
创建 Skill 和 创建 Skill 版本 使用 multipart/form-data 上传。推荐字段名 files；file 是保留兼容的老字段（⚠️ 已弃用，命中时响应头返回 Deprecation: true，请迁移到 files）。
支持两种上传形态：
① 单 .zip 包
上传单个 files part，Content-Type: application/zip；包内文件结构见下文"包内结构示例"。
② 裸文件树
files 字段可重复出现多次，每个 part 上传一个文件；part 的 filename 携带相对路径（如 code-review/SKILL.md、code-review/scripts/run.sh）。Forward 按 part 顺序无关规范化后打包，最终以 zip 形式存储。
| 规则 | 说明 |
|---|---|
| 上传字段 | files（可重复 part）；file（单 zip 兼容，已弃用） |
| 大小上限 | 压缩包本身与解压后总大小均不超过 50 MB；任一超过返回 400 skill_content_too_large。声明的解压大小与实际解压字节都会校验 |
| 包内 manifest | 顶层目录下的 SKILL.md（必需，含 frontmatter name、description） |
| 顶层目录 | 有且仅有一个；目录名必须与 SKILL.md 的 name 一致 |
包内结构示例
列表分页字段
Skill 列表响应的分页字段与 Forward 其他列表接口一致。
| 字段 | 类型 | 说明 |
|---|---|---|
data | Skill 对象 数组 | 当前页记录 |
has_more | boolean | 是否还有下一页 |
next_page | string | null | 下一页向后游标（推荐使用）；has_more=true 时等于当前页 last_id，否则为 null |
first_id | string | null | 当前页第一条记录 ID |
last_id | string | null | 当前页最后一条记录 ID |
page / after_id / before_id 互斥，同时提供多个返回 400；推荐使用 page，语义等价于 after_id。
Skill 版本列表分页字段
Skill 版本列表响应只使用推荐分页字段。
| 字段 | 类型 | 说明 |
|---|---|---|
data | Skill 版本对象 数组 | 当前页记录 |
has_more | boolean | 是否还有下一页 |
next_page | string | 下一页向后游标；has_more=false 时省略 |