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

# YCloud Developer Kit

> 借助适用于 Codex、Claude Code 和 WorkBuddy 的 AI 编程技能，构建 YCloud 集成。

YCloud Developer Kit 可帮助你的 AI 编程智能体在现有项目中规划集成、生成服务端代码并测试工作流。描述你想要构建的内容，例如 WhatsApp 订单通知、预约提醒或客户支持，智能体将使用 YCloud API 约定来指导开发工作。

你还可以要求智能体审查现有集成，或使用你配置的服务端凭据执行特定的线上 API 操作。

## 开始之前

对于安装和本地开发，你需要准备：

* Codex、Claude Code 或 WorkBuddy。
* 终端中可用的 Node.js 和 `npx`。
* 要在其中构建集成的项目。

安装检查或使用 Mock 的测试不需要 YCloud API Key。对于线上 API 请求，你需要一个 YCloud 账户、服务端 API Key 以及工作流所需的资源。有关凭据设置，请参阅[身份验证](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/authentication.md)。

## 安装技能

从你的项目目录运行对应编程智能体的命令。每个命令都会在该项目中安装全部 17 项技能。

> [tab] Codex
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> npx skills add YCloud-Developers/YCloud-Developer-Kit --skill '*' -a codex --copy -y
> ```

> [tab] Claude Code
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> npx skills add YCloud-Developers/YCloud-Developer-Kit --skill '*' -a claude-code --copy -y
> ```

> [tab] WorkBuddy
>
> WorkBuddy 使用兼容 CodeBuddy 的技能目录 `.codebuddy/skills/`。
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> npx skills add YCloud-Developers/YCloud-Developer-Kit --skill '*' -a codebuddy --copy -y
> ```

若要以交互方式选择编程智能体，请运行：

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx skills add YCloud-Developers/YCloud-Developer-Kit --skill '*'
```

你可以在[官方发布页面](https://github.com/YCloud-Developers/YCloud-Developer-Kit/releases)找到带版本号的插件 ZIP 压缩包和校验和。

## 检查安装情况

在编程智能体中启动新会话并发送：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Use ycloud-developer-kit-smoke-test to check that YCloud Developer Kit is ready.
```

预期响应为：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
YCloud Developer Kit is ready. No external API was called.
```

此项检查可确认智能体能够发现并调用安装就绪检查技能。它不会读取凭据、调用 YCloud，也不会验证你的账户配置。

如果智能体找不到该技能，请确认你是否在正确的项目中运行了安装命令、选择了正确的智能体，并为该项目打开了新会话。

## 构建你的第一个集成

描述你的业务目标、项目技术栈以及所需的结果。当工作流程涉及多项功能（例如模板、消息发送和 Webhook）时，请从 `ycloud-integration-architect` 开始。

例如，在你的应用程序项目中发送以下提示词：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Use ycloud-integration-architect to add WhatsApp order notifications to this project.
Reuse the existing framework and configuration patterns.
Send an existing approved template and handle delivery-status webhooks.
Keep the API key on the server and verify webhook signatures.
Add local tests with synthetic data and mocked YCloud responses.
Report the files changed, test results, and remaining setup.
```

智能体会为你所选的工作流程使用相关的领域技能。检查生成的代码和测试结果，然后在请求线上测试之前配置所需的 YCloud 资源。

在适当时向智能体提供以下上下文信息：

| 上下文 | 示例 |
| - | - |
| 业务目标 | 通过 WhatsApp 发送订单确认。 |
| 现有技术栈 | 复用该项目的 Node.js 后端和测试运行器。 |
| 范围 | 使用现有模板；不要创建或编辑模板。 |
| 测试环境 | 使用包含合成客户和消息 ID 的 Mock。 |
| 线上操作 | 使用其配置的凭据引用检索指定账户的余额。 |
| 预期结果 | 服务端代码、本地测试以及剩余配置步骤列表。 |

请通过你的服务器配置或机密管理器引用凭据。切勿将 API Key 或 Webhook 签名密钥直接粘贴到提示词中。

## 工具包涵盖的内容

版本 `0.7.13` 包含 17 项技能，涵盖 88 项 API 操作，以及 API 身份验证和 Webhook 接收。下表按你可以请求的工作内容对领域技能进行了分组。

| 功能 | 技能 | 典型任务 |
| - | - | - |
| API 身份验证 | `ycloud-api-authentication` | 配置服务端 API Key 并规划密钥轮换。 |
| WhatsApp 消息 | `ycloud-whatsapp-messages` | 直接或通过队列发送消息，以及检索消息。 |
| WhatsApp 媒体 | `ycloud-whatsapp-media` | 为消息工作流程上传媒体。 |
| WhatsApp 模板 | `ycloud-whatsapp-templates` | 创建、列出、检索、编辑和删除模板；检索分析数据。 |
| Webhook | `ycloud-webhook-endpoints` | 管理端点并构建具有签名验证功能的接收器。 |
| WhatsApp 商业账户 | `ycloud-whatsapp-business-accounts` | 列出和检索账户；管理自动创意优化设置。 |
| WhatsApp 电话号码 | `ycloud-whatsapp-phone-numbers` | 管理注册、个人资料、显示名称、用户名和设置。 |
| WhatsApp 群组 | `ycloud-whatsapp-groups` | 管理群组、成员资格、加入请求和邀请链接。 |
| WhatsApp Flows | `ycloud-whatsapp-flows` | 创建、更新、预览、发布、弃用和删除 Flows。 |
| 入站消息确认 | `ycloud-whatsapp-inbound-messages` | 将收到的消息标记为已读或显示正在输入提示。 |
| WhatsApp Calling | `ycloud-whatsapp-calling` | 管理通话会话并下载通话媒体。 |
| 账户余额 | `ycloud-balance` | 查询账户余额。 |
| 联系人 | `ycloud-contacts` | 管理联系人和备注，并列出联系人属性。 |
| 自定义事件 | `ycloud-custom-events` | 管理事件定义与属性，并提交与联系人关联的事件。 |
| 退订偏好 | `ycloud-unsubscribers` | 创建、获取、列出和删除退订记录。 |

其余两项技能是负责跨域协调工作流的 `ycloud-integration-architect`，以及负责检查安装就绪状态的 `ycloud-developer-kit-smoke-test`。

> [!NOTE]
>
> 此版本不涵盖 SMS、Verify、Voice 或 Email 集成。这些产品仍可通过 YCloud API 使用。有关集成详情，请参阅各自的 API 指南和参考页面。

## 更多示例提示词

### 添加入站消息和 Webhook

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Use YCloud Developer Kit to add WhatsApp inbound-message handling to this backend.
Verify webhook signatures and handle duplicate events.
Add local tests for valid signatures, invalid signatures, and repeated delivery.
Report the implementation changes and test results.
```

### 审查现有集成

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Review this project's YCloud WhatsApp integration.
Check server-side authentication, request and response handling, delivery-status
webhooks, error handling, and retry behavior against the supported contracts.
Report findings and suggested fixes without changing files or calling live APIs.
```

### 查询线上数据

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Use ycloud-balance to retrieve the balance for the YCloud account identified in
this project's server configuration. Use the configured credential reference
without displaying the key. Report the returned amount and currency.
```

## 本地测试与线上操作

本地 Mock 测试可让你使用合成数据检查应用程序行为。通过 Mock 测试并不代表线上身份验证、消息传递或生产环境部署已确认无误。

对于线上操作，请指定账户、环境、目标资源和操作。智能体会在该范围内使用已配置的凭证。当目标或影响不明确时，它会要求提供缺失的详细信息。在本地开发代码的请求并不意味着授权无关的线上变更。

对于消息发送和其他异步操作，请注意区分已接受的请求与其实际最终结果。请通过相应的查询 API 或 Webhook 验证送达或完成情况。如果线上变更发生超时，请在重试之前检查可用的资源状态。

## 后续步骤

> [card] [发送 WhatsApp 消息](https://docs.ycloud.com/zh/api-reference/guides/whatsapp-platform/send-whatsapp-message.md)
>
> 准备消息模板、有效负载以及送达处理。

> [card] [配置 Webhook](https://docs.ycloud.com/zh/api-reference/guides/api-fundamentals/configure-webhooks.md)
>
> 将你的应用程序连接到入站消息和状态更新。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.