> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Skill Marketplace

> 在 Clink Skill Marketplace 准备、提交、发布并管理 Skill。

Clink Skill Marketplace 帮助商户发布经过审核的 Skill，供用户发现、查看和安装。你可以在 Clink Dashboard 的 **Developers > Skill Marketplace** 中上传 Skill 包、跟进审核进度、发布已通过审核的版本，并维护公开展示内容。

<Note>
  只有状态为 **Published** 的 Skill 会出现在公开 Marketplace 中。状态为 **Ready** 表示 Skill 已通过审核，但仍需由商户执行发布操作。
</Note>

## 发布流程

<Steps>
  <Step title="准备 Skill 包">
    创建包含当前 `SKILL.md` 的 ZIP 包，并准备 Skill 名称、版本、分类和 Marketplace 摘要。
  </Step>

  <Step title="上传并提交">
    从 Dashboard 上传 ZIP 包。Clink 会检查 Skill 包和提交的 Marketplace 信息。
  </Step>

  <Step title="查看审核结果">
    审核通过后，Skill 会进入 **Ready** 状态。如果审核失败，请根据失败详情修复 Skill 包并重新上传。
  </Step>

  <Step title="发布">
    检查公开展示内容，然后点击 **Publish**，使 Skill 在公开 Marketplace 中可见。
  </Step>
</Steps>

## 状态说明

| 状态            | 含义                          | 下一步                     | 公开可见 |
| :------------ | :-------------------------- | :---------------------- | :--: |
| **Uploaded**  | ZIP 包已提交，正在等待处理。            | 查看提交内容并等待审核。            |   否  |
| **Polishing** | Clink 正在处理或审核 Skill。        | 等待审核结果。                 |   否  |
| **Ready**     | Skill 已通过审核，但尚未发布。          | 检查展示内容并点击 **Publish**。  |   否  |
| **Published** | Skill 已在公开 Marketplace 中发布。 | 管理展示内容、提交更新或下架。         |   是  |
| **Failed**    | 一项或多项审核检查未通过。               | 查看失败详情、修复 Skill 包并重新上传。 |   否  |

## 开始前需要准备

| 项目             | 需要准备的内容                                               |
| :------------- | :---------------------------------------------------- |
| 商户账户           | 可访问 Clink Dashboard 的账户。发布的 Skill 归属于当前商户或 publisher。 |
| Skill 包        | 包含 Skill 所需文件的 ZIP 压缩包。                               |
| `SKILL.md`     | 当前版本的 Skill 说明文件，其中声明的版本必须与表单中提交的版本一致。                |
| Marketplace 内容 | 清晰的名称、版本、分类和一句话摘要。                                    |
| Tips 配置        | 可选的建议金额和公开说明。只有通过相应的 Clink 检查后，Tips 才会公开展示。           |

<Info>
  商户不填写或编辑公开的 CLI command 和安装 Prompt。Clink 会根据审核后的 Skill 包自动生成两种安装方式，并在商户端以只读形式展示。
</Info>

## 发布 Skill

### 准备 Skill 包

上传前，请确认：

* ZIP 包可以正常打开并包含 `SKILL.md`。
* `SKILL.md` 中声明的版本与准备提交的版本完全一致。
* 摘要清楚说明 Skill 的用途和适用对象。
* Skill 包中包含足够且准确的说明，供 Clink 自动生成安装方式。
* 如果 Skill 使用 Agent Payment，支付触发和用户确认逻辑清晰可验证。
* 如果计划启用 Tips，Skill 包中包含所需的 tip payment handler。

### 提交 Skill

<Steps>
  <Step title="进入 Skill Marketplace">
    登录 Clink Dashboard，进入 **Developers > Skill Marketplace**，然后点击 **Upload skill**。

    <Accordion icon="store" title="Skill Marketplace">
      <img src="https://mintcdn.com/clink/wuscSS0Af1DU0dCs/images/agent/merchant_marketplace.png?fit=max&auto=format&n=wuscSS0Af1DU0dCs&q=85&s=76c2fb14fb61edbc7a2a0acc239b84ee" alt="Clink Dashboard Skill Marketplace" width="1280" height="720" data-path="images/agent/merchant_marketplace.png" />
    </Accordion>
  </Step>

  <Step title="选择 ZIP 包">
    选择需要提交的 Skill 包。Clink 会在审核期间检查 ZIP 结构和 `SKILL.md`。
  </Step>

  <Step title="填写展示信息">
    填写公开 Marketplace 信息。

    | 字段                      | 用途                           |
    | :---------------------- | :--------------------------- |
    | **Skill Name**          | 展示在公开卡片和 Skill 详情页。          |
    | **Version**             | 用于展示和版本历史，必须与 `SKILL.md` 一致。 |
    | **Category**            | 用于公开筛选和分类标签。                 |
    | **Marketplace summary** | 展示在公开列表和详情页顶部。               |

    <Accordion icon="upload" title="上传表单">
      <img src="https://mintcdn.com/clink/wuscSS0Af1DU0dCs/images/agent/upload_skill.png?fit=max&auto=format&n=wuscSS0Af1DU0dCs&q=85&s=87e1375934d4d5850059706c24246dab" alt="Upload skill 表单" width="1280" height="720" data-path="images/agent/upload_skill.png" />
    </Accordion>
  </Step>

  <Step title="配置 Tips（可选）">
    只有在 Skill 支持所需的打赏支付流程时才启用 **Tips**。填写建议金额和公开说明，然后提交 Skill 包。
  </Step>

  <Step title="等待审核">
    在 **My skills** 中跟进状态。审核可能包括版本比较、包结构、安全和 Agent Payment 检查。Clink 也会根据审核后的 Skill 包生成公开的 CLI command 和 Prompt。
  </Step>
</Steps>

<Warning>
  仅在表单中启用 Tips，不会使 Tips 面板立即公开。相关的 Clink 检查也必须通过。
</Warning>

### 检查并发布

当 Skill 进入 **Ready** 状态后：

1. 点击 **View**，检查提交信息、自动生成的安装方式、Overview 卡片、Tips 配置和版本信息。
2. 使用 **Preview public listing** 检查当前 publisher 的 Skill 在公开 Marketplace 中的展示效果。
3. 返回 **My skills**，点击 **Publish**。

系统生成的 CLI command 和 Prompt 为只读内容。如果生成结果不准确，请修正相关 Skill 包内容并提交新版本审核，不要直接修改生成文本。

## 管理已发布的 Skill

### 公开 Marketplace 展示

公开列表只包含 **Published** Skill。列表卡片可以展示 Skill 名称、分类、当前版本、摘要、Capabilities、publisher、Users 指标、Verified 标识、系统生成的安装 Prompt，以及通过相应检查后的 CLI tips 标记。

公开详情页可以展示 listing 信息、系统生成的 CLI 和 Prompt 安装方式、Overview 卡片、`SKILL.md`、Skill 包文件、版本历史以及符合条件的 Tips 内容。

<AccordionGroup>
  <Accordion icon="layout-grid" title="公开 Marketplace 列表">
    <img src="https://mintcdn.com/clink/wuscSS0Af1DU0dCs/images/agent/public_marketplace.png?fit=max&auto=format&n=wuscSS0Af1DU0dCs&q=85&s=0e9006c8abf52cfa352431e9b22c1e77" alt="公开 Skill Marketplace" width="1264" height="1178" data-path="images/agent/public_marketplace.png" />
  </Accordion>

  <Accordion icon="panel-top" title="公开 Skill 详情">
    <img src="https://mintcdn.com/clink/wuscSS0Af1DU0dCs/images/agent/public_skill_detail.png?fit=max&auto=format&n=wuscSS0Af1DU0dCs&q=85&s=9b35c53663a4e5a44f9c54a099f07656" alt="公开 Skill 详情页" width="1264" height="1313" data-path="images/agent/public_skill_detail.png" />
  </Accordion>
</AccordionGroup>

### 检查和维护内容

点击 Skill 的 **View**，可以检查展示信息。

| 内容                     | 管理方式                                                     |
| :--------------------- | :------------------------------------------------------- |
| Submitted listing      | 商户提交分类、版本和 Marketplace 摘要。                               |
| Install methods        | Clink 根据审核后的 Skill 包生成 CLI command 和 Prompt，商户只能查看，不能编辑。 |
| Public detail overview | 由 Clink 生成的 Overview 卡片，商户可以编辑、新增或删除。                    |
| Tips                   | 商户可以管理建议金额和公开说明；是否公开展示还取决于相应的 Clink 检查。                  |
| Version timeline       | 展示已发布版本、日期、状态标签和商户提交的版本说明。                               |
| Marketplace metrics    | 展示 Marketplace 统计的 Users 指标。                             |

### 提交版本更新

状态为 **Ready** 或 **Published** 的 Skill 可以提交更新。

<Steps>
  <Step title="准备新版本 Skill 包">
    更新 Skill 文件和 `SKILL.md`，然后创建新的 ZIP 包。
  </Step>

  <Step title="打开更新表单">
    打开 Skill 详情，然后点击 **Submit update**。
  </Step>

  <Step title="填写版本信息">
    输入高于当前版本且与 `SKILL.md` 一致的新版本号，并填写简洁的版本说明，用于版本时间线。
  </Step>

  <Step title="提交审核">
    核对 listing 和 Tips 配置，然后提交 Skill 包。Clink 会审核新包并重新生成 CLI command 和 Prompt。
  </Step>
</Steps>

提交更新不会立即替换公开 Skill 包。新版本必须通过审核，之后才能成为公开版本。

### 下架 Skill

点击 **Published** Skill 的 **Unpublish**，可以将其从公开 Marketplace 中移除。Skill 仍会保留在商户 Dashboard 中，当前状态和可用操作会显示其是否能够再次发布。

<Warning>
  下架后，Skill 将从公开列表和公开详情页中移除。继续前，请确认这符合预期的用户影响。
</Warning>

## 处理 Skill 支付 Webhook

部分 Marketplace Skill 需要用户购买额外额度后才能继续使用。Clink 完成充值订单后，商户 Webhook 必须把结果应用到商户账户，并返回相应的账户处理结果。

<Info>
  商户进入此流程前，Clink Marketplace 已经注册订单事件 Webhook，并准备好所需的 Webhook 配置。商户不需要创建或更新 endpoint，不需要手动修改事件订阅，也不负责轮换 signing secret。本节只说明商户服务需要实现的 Webhook 处理逻辑。
</Info>

### 支付成功事件

当事件类型为 `order.succeeded` 时，关联订单，根据 `data.object.customerEmail` 查找商户账户，应用本次成功充值，并返回 HTTP `200`，响应类型为 `account.reloaded` 或 `account.created`。

### 安全处理流程

<Steps>
  <Step title="验证 Webhook">
    使用原始请求体校验 `X-Clink-Timestamp`、`X-Clink-Signature` 和 `X-Clink-SignType`，通过后再读取和处理事件。签名无效的请求必须拒绝。
  </Step>

  <Step title="去重并关联订单">
    优先使用事件 `id` 作为幂等键，并保存首次处理的响应供重试复用。如果商户同时保存了 `merchantReferenceId` 和 `sessionId`，当两者都存在时必须同时匹配；不一致的订单应隔离处理，不能增加额度。
  </Step>

  <Step title="确认充值成功">
    只有当事件类型为 `order.succeeded` 时才继续进行账户匹配，并使用 `data.object.customerEmail` 识别商户账户。
  </Step>

  <Step title="匹配商户账户">
    如果邮箱属于商户已注册的用户，只执行一次充值，并准备 `account.reloaded` 响应。如果账户不存在，商户先创建用户账户，把购买的额度作为首次充值写入，然后准备 `account.created` 响应。
  </Step>

  <Step title="提交并返回结果">
    在返回 HTTP `200` 前，提交本地订单状态、账户创建或充值结果以及幂等记录。重复事件必须返回相同的已保存响应，不能重复创建账户或重复增加额度。
  </Step>
</Steps>

<Warning>
  HTTP `200` 本身不代表充值已经完成。只有商户账户变更成功提交后才能返回成功。如果本地履约失败，应返回非 2xx 响应，让事件能够安全重试。
</Warning>

### 账户响应字段

API 文档中的响应示例名为 `accountReloaded` 和 `accountCreated`，实际 JSON `type` 必须使用 `account.reloaded` 和 `account.created`。

| 响应字段                 | 来源或要求                                                   |
| :------------------- | :------------------------------------------------------ |
| `object`             | 固定为 `event`。                                            |
| `type`               | 已有商户账户使用 `account.reloaded`；创建新账户后使用 `account.created`。 |
| `data.customerEmail` | 必须与传入的 `data.object.customerEmail` 一致。                  |
| `data.webSite`       | 商户网站的绝对 URL，必须包含 `http` 或 `https` scheme。               |
| `data.userId`        | 商户系统中的用户 ID，不是 Clink `customerId`。                      |
| `data.amount`        | 复制传入的 `data.object.amountTotal`。                        |
| `data.currency`      | 复制传入的 `data.object.paymentCurrency`。                    |

<CodeGroup>
  ```json 已注册用户 theme={null}
  {
    "object": "event",
    "type": "account.reloaded",
    "data": {
      "customerEmail": "customer@example.com",
      "webSite": "https://merchant.example.com",
      "userId": "usr_xxxxx",
      "amount": 19.99,
      "currency": "USD"
    }
  }
  ```

  ```json 新注册用户 theme={null}
  {
    "object": "event",
    "type": "account.created",
    "data": {
      "customerEmail": "customer@example.com",
      "webSite": "https://merchant.example.com",
      "userId": "usr_xxxxx",
      "amount": 19.99,
      "currency": "USD"
    }
  }
  ```
</CodeGroup>

### 重试与乱序要求

* 重复处理相同事件时，不能重复创建账户或重复增加额度。
* 保存事件对应的响应；收到重复投递时，返回相同的已保存结果。
* 支持乱序投递，并且只在处理有效的 `order.succeeded` 事件后执行充值。
* 对标准化后的 customer email 设置商户账户唯一约束，避免并发投递创建重复用户。
* 记录 order ID、event ID、匹配到的商户 user ID、实际充值金额和币种，以及最终账户响应，便于审计和恢复。

## 处理审核失败

当一项或多项审核检查未通过时，Skill 会进入 **Failed** 状态。Failed Skill 保持私有，不会出现在公开 Marketplace 中。

### 阅读审核反馈

| 详情                       | 含义                   |
| :----------------------- | :------------------- |
| Failure reason           | 问题摘要和说明。             |
| Failed check             | 未通过的审核检查。            |
| Detected in              | 与问题相关的文件或配置位置。       |
| Review run               | 本次审核任务的标识。           |
| Fix suggestion and steps | 对 Skill 包的修复建议和操作步骤。 |
| Impact                   | 问题如何阻止发布或影响 Skill。   |
| Next step                | 重新打包和提交 Skill 的说明。   |

### 修复并重新上传

<Steps>
  <Step title="定位问题">
    使用 **Failed check** 和 **Detected in** 找到受影响的文件或配置。
  </Step>

  <Step title="按建议修复">
    根据审核反馈更新 Skill 包。如果问题涉及支付行为，请使支付触发和用户确认逻辑明确且可验证。
  </Step>

  <Step title="重新检查 Skill 包">
    确认 ZIP 包可以打开、包含当前 `SKILL.md`，并且 Skill 包与提交表单使用相同的版本号。
  </Step>

  <Step title="重新上传">
    点击 **Reupload**，选择修正后的 ZIP 包并再次提交审核。
  </Step>
</Steps>

## 发布检查清单

### Skill 包与技术内容

* [ ] ZIP 包可以正常打开并包含 `SKILL.md`。
* [ ] 提交版本与 `SKILL.md` 中声明的版本一致。
* [ ] Skill 包中包含准确内容，供 Clink 生成 CLI command 和 Prompt。
* [ ] 使用 Agent Payment 时，相关行为清晰且可审核。
* [ ] 启用 Tips 时，包含可审核的 tip payment handler。

### Marketplace 内容

* [ ] Skill 名称简洁且容易识别。
* [ ] 分类准确，便于用户发现。
* [ ] 摘要说明 Skill 能够带来的主要结果。
* [ ] 已在 listing 预览中检查系统生成的安装方式。
* [ ] Overview 卡片描述真实能力和使用前提。
* [ ] 提交更新时填写了版本说明。

### 发布前确认

* [ ] Skill 状态为 **Ready**。
* [ ] 已检查 listing、系统生成的安装方式、Overview、Tips 和版本信息。
* [ ] 已检查公开列表预览。
* [ ] 只有在公开内容准备完成后才点击 **Publish**。

## 常见问题

<AccordionGroup>
  <Accordion title="为什么我的 Skill 没有出现在公开 Marketplace 中？">
    只有 **Published** Skill 会公开展示。**Uploaded**、**Polishing**、**Ready** 和 **Failed** Skill 保持私有。状态为 **Ready** 的 Skill 仍需要由商户发布。
  </Accordion>

  <Accordion title="可以编辑系统生成的 CLI command 或 Prompt 吗？">
    不可以。Clink 根据审核后的 Skill 包生成两种安装方式。如果生成结果需要变化，请修正相关 Skill 包内容并提交新版本。
  </Accordion>

  <Accordion title="为什么没有显示 Tips 面板？">
    商户必须启用 Tips，并通过相应的 Clink 检查，才会公开展示 CLI tips 内容。
  </Accordion>

  <Accordion title="可以只在表单中更新版本号吗？">
    不可以。提交的版本必须与 Skill 包中 `SKILL.md` 声明的版本一致。版本更新还必须使用高于当前版本的版本号。
  </Accordion>

  <Accordion title="发布后还能编辑内容吗？">
    可以在 Skill 详情中维护 Overview 卡片和 Tips 配置。Skill 包或系统生成的安装方式发生变化时，应提交新版本审核。
  </Accordion>
</AccordionGroup>

<Note>
  本指南不定义审核时效、Marketplace 费用、结算、分成或退款政策。请以 Clink 最新商业条款为准，或联系 Clink 支持获取当前政策信息。
</Note>