# 技能市场与创作者中心

技能市场是控制台里的网页端技能系统,用于浏览、安装、创建、发布、运行和结算 AI 技能。它和本地 Claude/Codex 的 Skill / Plugin 不是同一件事:本地 Skill/Plugin 改变客户端工作流,控制台技能市场则运行在 Clomio 网页端和服务端。

> 技能入口受 AI Studio/控制台开关和登录状态影响。入口不可见时,以控制台当前开放状态为准。

---

## 页面入口与生命周期

| 页面 | 路由 | 用途 |
|---|---|---|
| 技能市场 | `/skills/market` | 浏览公开/可见技能、搜索、筛选、查看详情 |
| 已安装 | `/skills/installed` | 管理自己安装的技能 |
| 我的技能 | `/skills/mine` | 创作者管理自己创建的技能 |
| 新建技能 | `/skills/new` | 创建技能草稿 |
| 编辑技能 | `/skills/:id/edit` | 编辑基础信息、内容、变量、价格 |
| 版本管理 | `/skills/:id/versions` | 创建版本、提交审核、发布已审核版本 |
| 运行记录 | `/skills/:id/runs` | owner 查看运行历史和失败原因 |
| 收益 | `/skills/:id/revenue` | owner 查看收益汇总、趋势、订单 |
| 技能详情 | `/skills/:id` | 查看说明、安装、测试/使用 |

典型生命周期:

1. **发现**:进入市场,按类型、分类、价格、安装状态筛选。
2. **安装**:详情页确认价格和说明后安装,到「已安装」使用。
3. **创建**:进入「我的技能」→ 新建,填写名称、类型、变量、内容、价格。
4. **编辑**:owner 在编辑页调整元信息和内容。
5. **发版本**:在版本管理里创建版本,保存 draft 或提交 review。
6. **发布**:版本审核通过后调用 publish,把该版本设为 current/published。
7. **运行**:用户 test/use,生成 run 记录。
8. **收益**:付费运行产生结算记录,owner 在 revenue 页查看。

---

## 用户端点

所有 `/user/skills` 路由都要求已登录。

| 功能 | 方法与路径 |
|---|---|
| 列表/市场/我的 | `GET /user/skills` |
| 创建技能 | `POST /user/skills` |
| 技能详情 | `GET /user/skills/:id` |
| 更新技能 | `PUT /user/skills/:id` |
| 安装 | `POST /user/skills/:id/install` |
| 卸载 | `POST /user/skills/:id/uninstall` |
| 版本列表 | `GET /user/skills/:id/versions` |
| 创建版本 | `POST /user/skills/:id/versions` |
| 更新版本 | `PUT /user/skills/:id/versions/:versionId` |
| 提交审核 | `POST /user/skills/:id/versions/:versionId/submit` |
| 发布版本 | `POST /user/skills/versions/:versionId/publish` |
| 运行列表 | `GET /user/skills/:id/runs` |
| 通用运行 | `POST /user/skills/:id/runs` |
| 测试 | `POST /user/skills/:id/test` |
| 使用 | `POST /user/skills/:id/use` |
| 收益 | `GET /user/skills/:id/revenue` |

安装/卸载返回一般包含 `skill_id`、`installed`、`install_count` 和提示消息；连续点击安装/卸载时以前一次返回为准。付费技能请先确认 `pricing.mode`、`amount`、`currency` 和安装后的运行扣费说明。

列表常用 query:

- 通用:`page`、`page_size`、`scope`、`search`、`type`、`category`、`sort`
- 市场:`scope=market`,可加 `price_mode`、`installed`
- 我的:`scope=mine`,可加 `status`、`visibility`
- 运行记录:`status`、`version_id`、`search`

`scope=market` 在后端会进入公开/市场库视图；用户侧 `visibility` 只按 `public` / `private` 归一化。`installed` 支持 `installed|true|1|yes` 和 `not_installed|false|0|no`。用户侧技能 `status` 常见为 `draft`、`published`、`archived`、`hidden`；版本展示状态常见为 `draft`、`published`、`deprecated`、`archived`，未知/被拒绝版本通常按 draft 展示。`price_mode=free|paid` 是列表筛选和展示口径。

市场列表返回项通常会被前端归一化为 `id`、`slug`、`name`、`type`、`category`、`visibility`、`status`、`pricing`、`installed`、`install_count`、`current_version`、`owner` 等字段；不同后端版本可能把 `latest_version`、`published_version`、`owner_name`、`publisher_name` 作为兼容字段返回。版本 DTO 当前不保证直接给顶层 `review_status`，前端会从 metadata、状态和发布时间推导展示。

市场列表的筛选规则比较严格：`scope=market` 只列已公开且已发布的技能；`installed` 只显示你已安装的技能。排序里 `popular` 通常按 like/install 相关热度，`runs` 按运行数；当前 `sort=revenue` 也按运行数排序，不等于真实收益额排序。排查市场排序/筛选异常时,先复制筛选条件和列表响应里的字段。

---

## 创建 / 更新技能

支持类型:

| 类型 | 用途 | 当前限制 |
|---|---|---|
| `prompt_chat` | 提示词聊天技能 | 可由用户创建 |
| `prompt_image` | 图片生成技能 | 可由用户创建 |
| `script` | 脚本技能 | 当前普通用户创建会返回 `AI_SKILL_SCRIPT_CREATION_UNSUPPORTED` |

脚本技能还没对普通用户完整开放：创建会被阻断，运行时网关当前 fail-closed；即使旧版本曾经审核通过，若没有审核时固化的 artifact digest，也需要重新提交审核后才能执行。

基础请求体示例:

```json
{
  "slug": "daily-report",
  "name": "日报生成器",
  "tagline": "把要点整理成日报",
  "description": "适合团队日报/周报",
  "type": "prompt_chat",
  "visibility": "public",
  "status": "draft",
  "category": "writing",
  "cover_image_url": null,
  "tags": ["office", "report"],
  "pricing": {
    "mode": "free",
    "amount": 0,
    "currency": "CNY",
    "settlement_ratio": null
  },
  "source_locked": false,
  "variable_schema": [],
  "content": {
    "type": "prompt_chat",
    "system_prompt": "你是严谨的日报助手",
    "user_prompt_template": "请根据以下要点生成日报: {{items}}",
    "temperature": 0.7,
    "max_tokens": 1200
  },
  "readme": "使用说明",
  "install_note": "安装后在详情页使用"
}
```

`variable_schema` 可定义用户运行时填写的变量,常见类型有 `string`、`text`、`number`、`boolean`、`select`、`json`、`image`、`file`。

图片技能内容示例:

```json
{
  "type": "prompt_image",
  "prompt_template": "一张 {{style}} 风格的 {{subject}} 海报",
  "negative_prompt_template": "低清晰度,杂乱背景",
  "style": "product",
  "size": "1024x1024",
  "quality": "high",
  "image_count": 1
}
```

---

## 版本、审核与发布

创建/更新版本字段:

```json
{
  "version": "v1.0.0",
  "status": "draft",
  "changelog": "首次发布",
  "source_locked": false,
  "variable_schema": [],
  "content": { "type": "prompt_chat" }
}
```

状态关系有多层，不要只看一个字段:

| 层级 | 状态 | 说明 |
|---|---|---|
| 技能状态/展示状态 | `draft` / `published` / `archived` / `hidden` | 控制技能整体可见性；用户侧 `visibility` 仍只归一化为 `public/private` |
| 版本展示状态 | `draft` / `published` / `deprecated` / `archived` | 控制页面展示；disabled override 可能显示为 archived |
| 审核核心状态 | `draft` → `pending` → `approved`;`pending` → `rejected` | 只有 approved 版本才能 publish/test/use |
| service 内部版本状态 | `draft` / `submitted` / `approved` / `rejected` / `disabled` | `submitted` 会映射到审核 pending；不是直接给用户看的最终展示词 |

注意:

- `submit` 只是进入审核 pending,不等于对市场用户发布。
- 用户端 `publish` 是把已 approved 的版本设为 current/published。
- 创建/更新版本时若 `status` 传 `published`,服务端会尝试自动提交审核;真正发布仍要通过审核后 publish。不要把请求体里的 `published` 理解成立刻上架。
- 非 owner 只能运行已发布版本;请求其他版本会被拒绝。

---

## 运行、测试与收益

通用运行请求体:

```json
{
  "version_id": 123,
  "mode": "use",
  "parameters": {
    "topic": "本周销售数据"
  },
  "attachments": [],
  "idempotency_key": "client-generated-key"
}
```

通用 `POST /user/skills/:id/runs` 读取 body 中的 `version_id`、`mode`、`parameters`、`attachments`、`idempotency_key`。快捷 `POST /user/skills/:id/test` 和 `/use` 则使用固定 mode，`version_id` 主要走 query 参数，幂等键从 `Idempotency-Key` header 读取；当前网页前端通常不向 test/use 传附件 body。运行状态面向用户可理解为:

| 状态 | 含义 |
|---|---|
| `queued` / `prepared` | 等待中 |
| `running` / `dispatched` | 执行中 |
| `succeeded` | 成功 |
| `failed` | 失败,查看 `error_message` |
| `cancelled` / `canceled` | 已取消 |

收益页 `GET /user/skills/:id/revenue` 只对 owner 可见,会展示 total revenue、sales、runs、pending/settled/refunded 等汇总和订单。创建/编辑页的 `pricing.mode=free|paid` 是前端展示口径；运行结算底层会转换为 `free` 或 `per_run`。`amount>0` 表示每次运行价格，`settlement_ratio` 是创作者分成比例；付费但金额为 0、负价格、分成比例不在 0..1 都可能触发 `AI_SKILL_BILLING_POLICY_INVALID`。

结算状态底层常见为 `skipped`、`pending`、`settled`、`failed`；页面或旧接口可能映射为 `pending`、`settled`、`rejected`、`refunded` 等展示词。用户收益汇总通常只把 transferred/settled 类记录计入 settled/total，pending 只进待结算；订单原始状态可能再被前端映射为 paid/cancelled。免费运行通常不会产生创作者收益，可能表现为 skipped/无结算记录；付费运行失败时请同时保留 run id、settlement/order id 和错误信息。

源码可见性和安装状态是两件事。owner 通常可看源码；非 owner 必须先有读取权限，并且 effective source visibility 为 public 才能看到 `content`、`metadata`、`examples` 等源码/配置。公开付费技能默认可能隐藏源码；安装付费技能不等于一定能看到源码。

---

## 权限与常见错误

下面是用户侧常见错误码，不是全集；持续异常请带运行记录或订单信息提交工单。

| 报错 / 现象 | 常见原因 | 处理 |
|---|---|---|
| 入口不可见 | AI Studio/技能功能未开放 | 以控制台当前开放状态为准 |
| 401 / `User not authenticated` | 未登录或登录过期 | 重新登录 |
| `AI_SKILL_ACCESS_DENIED` | 私有技能、未发布技能或非 owner 访问 owner-only 页面 | 确认技能可见性和权限 |
| `AI_SKILL_NOT_FOUND` | 技能不存在、已隐藏或无权访问 | 刷新列表,确认链接 |
| `AI_SKILL_VERSION_NOT_FOUND` / `AI_SKILL_REVIEW_NOT_FOUND` / `AI_SKILL_RUN_NOT_FOUND` / `AI_SKILL_SETTLEMENT_NOT_FOUND` | 版本、审核单、运行记录或结算记录不存在或不可见 | 回到对应列表确认 ID 和权限 |
| `AI_SKILL_NAME_REQUIRED` | 创建/更新时名称缺失 | 填写技能名称 |
| `AI_SKILL_TYPE_INVALID` / `AI_SKILL_VISIBILITY_INVALID` / `AI_SKILL_BILLING_MODE_INVALID` / `AI_SKILL_PRICE_MODE_INVALID` / `AI_SKILL_SOURCE_VISIBILITY_INVALID` | 类型、可见性、计费模式、价格模式或源码可见性非法 | 使用页面提供的下拉值，不要手改接口参数 |
| `AI_SKILL_SCRIPT_CREATION_UNSUPPORTED` | 普通用户创建脚本技能 | 改用 prompt 类型或等待开放 |
| `AI_SKILL_SCRIPT_EXECUTION_UNAVAILABLE` | 脚本执行器未接入 | 脚本技能运行不可用,等待站点开放 runtime |
| `AI_SKILL_SCRIPT_NOT_APPROVED` | 脚本版本没有审核时固化的 artifact digest | 重新提交审核并等待通过 |
| `AI_SKILL_SCRIPT_ARTIFACT_MISMATCH` | 运行时脚本包与审核通过的 digest 不一致 | 不要绕过版本发布;重新上传/审核 |
| `AI_SKILL_SCRIPT_ARCHIVE_PATH_INVALID` | 脚本归档路径不在允许根目录或格式不合法 | 使用平台上传/生成的归档 |
| `AI_SKILL_VERSION_NOT_APPROVED` | 版本未审核通过就 test/use/publish | 先提交审核并等待 approved |
| `AI_SKILL_VERSION_TRANSITION_INVALID` | 版本状态流转不合法 | 按 draft → pending → approved → publish 流程操作 |
| `AI_SKILL_VERSION_NOT_EDITABLE` | 已发布/归档版本不能直接编辑 | 新建修复版本 |
| `AI_SKILL_RUN_MODE_INVALID` | 运行模式非法 | 使用 `test` 或 `use` |
| `AI_SKILL_RUN_INPUT_REQUIRED` | 运行输入为空 | 填写输入后再 test/use |
| `AI_SKILL_EXECUTION_SPEC_INVALID` / `AI_SKILL_BILLING_POLICY_INVALID` | 技能执行/计费配置非法 | 检查版本 content 与 pricing |
| `AI_SKILL_SERVICE_UNAVAILABLE` / `AI_SKILL_INPUT_REQUIRED` / `AI_SKILL_VERSION_INPUT_REQUIRED` | 技能模块或请求输入缺失 | 刷新页面后补齐技能/版本/输入；持续出现提交工单 |
| `AI_SKILL_VERSION_STATUS_INVALID` / `AI_SKILL_REVIEW_STATUS_INVALID` / `AI_SKILL_RUN_STATUS_INVALID` / `AI_SKILL_SETTLEMENT_STATUS_INVALID` / `AI_SKILL_REVIEWER_INVALID` | 版本、审核、运行、结算状态或审核人不合法 | 按页面流程提交审核；持续异常提交工单 |
| `AI_SKILL_SETTLEMENT_INPUT_INVALID` / `AI_SKILL_PRICE_INVALID` / `AI_SKILL_VERSION_NUMBER_INVALID` / `AI_SKILL_REVIEW_ALREADY_PENDING` / `AI_SKILL_REVIEW_TRANSITION_INVALID` / `AI_SKILL_VERSION_IN_USE` / `AI_SKILL_VERSION_ALREADY_EXISTS` / `AI_SKILL_SETTLEMENT_ALREADY_EXISTS` / `AI_SKILL_BALANCE_UNAVAILABLE` / `AI_SKILL_EXECUTION_FAILED` | 结算输入、价格、版本号、审核流转、版本占用/重复或运行执行失败 | 保留 run id、版本 id、订单/结算 id 后提交工单 |
| `AI_SKILL_SETTLEMENT_UNAVAILABLE` | 收益结算服务不可用 | 稍后重试或提交工单 |
| `AI_SKILL_CREATOR_EARNINGS_UNAVAILABLE` / `AI_SKILL_CREATOR_EARNINGS_MISMATCH` | 创作者收益结算异常 | 保留 run/order id 提交工单 |

创建、更新、提交、发布、运行都带幂等包装;页面卡顿时不要连续重复点击。付费技能的源码可见性由 `source_visibility`、价格、发布状态和 owner 身份共同决定,安装后不保证一定能看到源码。

媒体字段可能是 `cover_image_url`、`avatar_url`、`media_id` 或迁移后的媒体 asset。旧版本返回 URL、新版本返回媒体对象时,前端会做兼容归一化;如果封面丢失,先检查媒体服务是否开启、对应 asset 是否被删除,再看技能 metadata 里的旧 URL 是否还能访问。

---

## 实用场景

### 安装一个市场技能

1. 进入 `/skills/market`。
2. 搜索“日报”或按类型/价格筛选。
3. 打开详情,确认价格、说明、变量和示例。
4. 点击安装。
5. 到 `/skills/installed` 找到它并使用。

### 创建提示词聊天技能

1. 进入 `/skills/mine` → 新建。
2. 类型选 `prompt_chat`。
3. 填写系统提示词、用户模板、变量 schema。
4. 保存草稿。
5. 创建 `v1.0.0` 版本并提交审核。
6. 审核通过后 publish。

### 发布修复版本

1. 在版本页新建 `v1.1.0`。
2. 写清 changelog。
3. 提交审核。
4. approved 后 publish。
5. 未 publish 前,市场用户仍使用旧 current/published version。

### 查看运行失败与收益

- owner 进入 `/skills/:id/runs`,按 `failed` 筛选,查看 `error_message`、输入/输出摘要、成本。
- owner 进入 `/skills/:id/revenue`,核对 buyer、version、amount、status,再和订单/用量截图一起提交工单。

---

## 不要和本地 Skill / Plugin 混淆

本页是 Clomio 控制台技能市场。Claude/Codex 本地 Skill、Plugin、MCP 安装见 [必装 Skill 与插件](#/skills-plugins)。本地 skill 不能让网关多出不存在的 API;例如视频端点仍然只支持 Grok 分组。