docs/product-guide.zh-CN.md

# YCloud Developer Kit 使用指南

适用版本：0.7.9

YCloud Developer Kit 是在 Codex 中使用的 YCloud 集成开发助手。你可以用自然语言描述业务需求，让它帮助你梳理接入方案、编写本地项目代码，并通过模拟测试检查流程。

它适合希望将 WhatsApp 消息、联系人、模板或其他 YCloud 能力接入自身系统的团队。你不必先记住所有接口和参数，可以先说清楚“希望客户获得什么体验”，再逐步确认如何实现。

> Developer Kit 帮助你完成集成开发，不是直接发送消息的运营后台。它不会替你操作真实 YCloud 账户，也不会自动将应用部署上线。

## 0.7.9 更新内容

- 插件简介与完整介绍明确说明 WhatsApp Business 集成用途，按订单通知、预约提醒、客服和线索收集展示场景。
- 起始提问覆盖订单通知、消息回调和已有集成检查；功能范围与本地开发边界保持不变。

## 0.7.8 更新内容

- 修复安装后部分共享参考资料无法加载的问题，领域助手现在随包携带所需资料。
- 明确执行边界：助手可以按授权生成和修改本地集成代码；生成的应用由团队配置服务端运行环境与凭据。规划和模拟测试不需要真实密钥，真实 API 联调需单独明确授权和范围。
- 对齐模板创建、编辑与消息发送的不同结构。轮播模板定义使用 2–10 张卡片，发送时可以只提供需要覆盖的卡片参数；保留服务支持的枚举大小写兼容。
- 修正模板名称下划线规则，补充 OpenAPI 来源及修正记录。
- 更新插件介绍和起始提示词；发布安装包与本使用指南由同一版本源码生成。

本版保持 17 个 Skills，覆盖固定 OpenAPI 快照中 95 项操作里的 88 项，以及鉴权、Webhook 接收两项跨领域能力。共 90 个能力覆盖项，并非全部功能都具有可执行的本地模拟接口；本版没有新增 API 覆盖范围。

本指南与 `ycloud-developer-kit-0.7.9.zip` 一起作为 Release 附件提供。`SHA256SUMS` 可用于核对下载的安装包和指南是否完整。ZIP 内也包含本指南（`docs/product-guide.zh-CN.md`）、上架资料和全部 Skill 的演示说明；源码中的参考应用与 Sandbox 需要按各自 README 单独运行。

## 一、你可以用它做什么

你可以从一个新需求开始，也可以把已有项目交给它评估。

| 你的需求 | 可以获得的帮助 |
| --- | --- |
| 想接入 YCloud，但不知道从哪里开始 | 拆解业务流程，明确需要哪些能力、前置条件和开发步骤 |
| 已有系统，需要增加 WhatsApp 通知 | 设计消息发送、模板使用和状态回传流程，并按要求编写本地代码 |
| 需要处理客户发来的消息 | 规划消息接收、回调验证、已读与输入状态处理 |
| 希望把联系人和退订状态接入业务流程 | 设计联系人同步、退订状态查询和发送前检查 |
| 想使用群组、Flows 或 Calling | 梳理相应功能的接入流程和与其他能力的衔接 |
| 已经完成部分开发，希望检查遗漏 | 评估现有实现，补充异常场景、测试和待验证事项 |

本版的集成指导覆盖 WhatsApp 消息、媒体、模板、账号与号码、群组、Flows、入站消息、Calling，以及鉴权、回调、余额、联系人、自定义事件和退订管理。本 Kit 不覆盖 SMS、Verify、Voice 和 Email 集成。

这里的“支持”指集成设计、代码生成与评估能力，不代表相关功能已在你的账户开通，也不代表所有流程都经过真实环境验证。

## 二、整体使用逻辑

建议按下面的顺序使用。它是一条推荐的协作路径，不是自动执行到上线的流水线；你可以只做方案，也可以从已有代码的检查开始。

**描述目标 → 确认方案 → 授权本地开发 → 模拟测试 → 由团队完成真实联调与上线**

| 阶段 | 你需要做什么 | 希望得到的结果 |
| --- | --- | --- |
| 描述目标 | 说明业务场景、现有系统和预期效果 | 明确本次要解决的问题及缺失信息 |
| 确认方案 | 确认功能范围、处理流程和暂不做的部分 | 可供讨论的接入方案与实施步骤 |
| 本地开发 | 明确允许修改的项目及范围 | 对应的代码、配置说明和测试 |
| 模拟测试 | 要求检查正常、失败和重复事件等情况 | 已验证结果、失败原因和未验证清单 |
| 联调与上线准备 | 安排技术团队配置真实环境并验证 | 真实调用记录和上线检查结果 |

每完成一个阶段，都建议让助手总结：“已经完成什么、依据是什么、还缺什么”。这样可以避免把“方案已写好”误认为“功能已可上线”。

## 三、开始前准备什么

### 使用环境

请先在支持插件的 Codex 环境中安装 YCloud Developer Kit。安装配置可由你或团队的技术人员完成；技术安装说明见源码仓库 README 的 Install 小节。

安装后新建一个任务，输入：

~~~text
使用 $ycloud-developer-kit-smoke-test 检查插件是否已准备好。
~~~

预期响应为：

~~~text
YCloud Developer Kit is ready. No external API was called.
~~~

这表示插件已被发现，不代表已经连接你的 YCloud 账户。

### 需求信息

开始规划不需要提供真实密钥。准备以下信息就足够：

- 业务目标：例如订单确认、物流更新、售后沟通或联系人同步。
- 当前系统：已有项目还是新项目；如果知道，可以说明技术栈。
- 触发时机：谁在什么情况下发起操作。
- 预期结果：客户收到什么、你的系统需要记录什么。
- 本次范围：只要方案，还是需要修改本地代码并测试。

如果你不是开发人员，可以先描述业务流程，让助手整理出交给技术团队的接入说明。涉及代码修改、部署和真实联调时，再由技术人员参与。

请不要在对话中粘贴真实 API Key、客户手机号、客户消息或其他敏感数据。示例使用虚构数据即可。

## 四、第一次使用：从订单通知开始

下面以“客户下单后收到 WhatsApp 订单通知，商家能查看发送结果”为例，展示推荐的使用方式。它是一个需求示例，不表示插件已经替你完成了订单系统接入。

### 第 1 步：描述业务目标，先要方案

不确定该选哪个功能时，可以从集成规划助手开始：

~~~text
使用 $ycloud-integration-architect 帮我规划一个订单通知功能。

客户在我们的网站下单后，希望通过 WhatsApp 收到订单确认通知。
我们的后台需要记录消息状态，发送失败时能看到原因。
本次先做订单确认，不做营销群发。

请先说明完整业务流程、需要准备的条件和开发步骤。
只输出方案，不修改文件，不调用真实 API。
~~~

建议要求方案回答这几个问题：

- 订单系统在什么时机触发通知？
- 需要哪些账号、号码或模板准备？
- 发送前需要检查哪些条件？
- 如何把发送请求与订单关联起来？
- 如何获取后续消息状态？
- 失败、超时或重复通知如何处理？

先确认业务流程，再进入代码开发。不确定的信息应单独列出，不应由助手自行假设已经具备。

### 第 2 步：确认这次做什么

阅读方案后，可以继续缩小范围：

~~~text
这次只做订单确认通知，以及消息状态回传。
先不做图片、群组和客户回复处理。

请按这个范围更新方案，列出：
1. 我们需要准备的信息；
2. 需要改动的模块；
3. 完成后如何验收；
4. 仍然需要确认的问题。
~~~

这里的“状态回传”通常通过 Webhook 完成：YCloud 将后续事件通知给你的系统，你的系统再更新记录。提交发送请求和收到最终结果是两个环节，不能把“已受理”直接显示成“客户已收到”。

### 第 3 步：明确授权本地开发

方案确认后，再提供项目并明确允许修改：

~~~text
按刚才确认的方案，在当前本地项目中实现订单通知和消息状态接收。

允许修改相关代码并补充测试，不修改无关模块。
使用虚构订单和模拟数据，不读取真实密钥，不调用真实 API。
完成后请说明改了什么、如何运行，以及哪些配置需要我们后续填写。
~~~

此阶段可以要求交付：

- 本次范围内的集成代码。
- 配置项及用途说明，不包含真实凭据。
- 消息状态与业务记录的关联处理。
- 正常与异常场景的测试。
- 尚未完成或需要真实环境确认的事项。

如果你只需要示例而不希望修改现有项目，应明确说“只生成示例，不应用修改”。

### 第 4 步：检查流程，不只检查成功情况

继续让助手验证可能影响客户体验的场景：

~~~text
请使用本地模拟测试检查：
正常提交、发送失败、请求超时、重复状态通知和无效回调。

不要将超时直接当成发送失败后重新发送。
请分别列出已执行的测试、实际结果和未验证的事项。
如果现有测试环境不支持某个场景，请直接说明。
~~~

Developer Kit 源码仓库提供本地模拟环境及参考示例，但安装插件不会自动启动这些资源，也不是所有支持的能力都有对应模拟场景。

测试结果需要分清层次：

| 结果描述 | 代表什么 |
| --- | --- |
| 代码已生成 | 实现已写出，仍需检查和运行 |
| 模拟测试通过 | 指定模拟场景中的处理符合预期 |
| 本地 Sandbox 验证通过 | 已覆盖的本地接口流程通过检查，不代表全部功能或真实服务通过 |
| 真实环境联调通过 | 由团队在授权环境下实际执行并验证了明确范围的流程 |

### 第 5 步：交给团队完成真实联调

当本地开发和测试完成后，可以要求一份交接清单：

~~~text
请整理交给我们技术团队的联调与上线准备清单。

区分已完成的本地工作和仍需真实环境确认的工作。
列出账号与号码准备、模板状态、服务端密钥配置、
回调地址、测试步骤、异常处理和回滚准备。
只输出清单，不执行真实操作。
~~~

之后由你的团队负责真实凭据配置、账号准备、实际调用验证、部署和上线决策。不要仅凭“本地测试通过”就开启面向客户的真实发送。

## 五、已有明确需求时，直接使用对应助手

Skill 可以理解为面向不同任务的专业助手。你不需要记住所有名称；第一次使用或跨多个功能时，优先使用集成规划助手。

| 想处理的事情 | 推荐入口 | 可以直接复制的提问 |
| --- | --- | --- |
| 整体接入方案 | `$ycloud-integration-architect` | 帮我梳理当前项目接入 WhatsApp 通知的完整流程，先不改代码。 |
| 消息发送与查询 | `$ycloud-whatsapp-messages` | 帮我实现本地消息发送与结果查询代码，并补充模拟测试。 |
| 模板管理 | `$ycloud-whatsapp-templates` | 帮我设计模板管理流程，说明哪些状态需要等待或人工处理。 |
| 图片等媒体上传 | `$ycloud-whatsapp-media` | 帮我设计媒体上传后用于消息发送的流程，不执行真实上传。 |
| 状态通知与消息回调 | `$ycloud-webhook-endpoints` | 帮我检查回调接收方案，关注验证来源和重复通知处理。 |
| 联系人同步 | `$ycloud-contacts` | 帮我设计联系人与备注同步流程，使用虚构数据。 |
| 退订状态 | `$ycloud-unsubscribers` | 帮我在发送前加入退订状态检查，说明还需要哪些业务判断。 |
| 服务端鉴权 | `$ycloud-api-authentication` | 帮我设计服务端密钥配置，不读取或展示真实密钥。 |

这里只列常用入口。涉及号码、群组、Flows、自定义事件或 Calling 时，也可以先让集成规划助手判断需要哪些领域能力。

## 六、怎样让结果更符合你的需求

有效的提问通常包含五部分：

**业务目标 + 当前情况 + 本次范围 + 允许执行的动作 + 交付要求**

例如：

~~~text
我们希望在订单发货后通知客户。
现有系统已经记录物流单号，但尚未接入 WhatsApp。
这次只做发货通知，不做营销消息。

请先评估方案，不修改代码。
最后给出流程说明、前置条件、风险和开发验收清单。
~~~

需要继续开发时，再明确“按已确认方案修改当前本地项目”。需要检查现有实现时，明确“只评估，不修改”。

也可以随时缩小任务，例如“先只完成消息状态接收”。不必第一次就要求接入全部功能。

## 七、常见问题

### 不懂 API，可以使用吗？

可以先用于整理需求、了解接入流程和形成技术交接说明。将功能接入实际系统，仍需要具备开发和部署能力的人员参与。

### 安装后就可以直接给客户发消息吗？

不可以。插件安装不等于账号配置或业务接入完成。Developer Kit 帮助开发和验证集成，不替你执行真实消息发送。

### 需要把 API Key 提供给助手吗？

不需要。规划、代码示例和模拟测试使用占位符或合成数据。真实凭据由技术团队在受控的服务端环境中配置，不应粘贴进对话或写进代码仓库。

### 生成的方案和示例是否一定符合最新规则？

在生成或判断真实接口示例前，需要核对最新官方文档。如果官方文档无法访问，合成示例需要标注为 `synthetic_unverified`，表示尚未完成官方文档核对，不能直接视为可用于真实环境的示例。资料冲突也需要先澄清。

### 为什么发送请求成功了，还不能说客户已收到？

请求被受理只表示进入后续处理。实际送达或失败需要依据后续状态判断；你的业务系统应保留这种区别。

### 助手是否会自动改文件、部署或更改账户设置？

本地文件修改应由你明确提出并限定范围。真实账户操作和部署不是本指南中的自动执行步骤，需要由团队另行安排。

## 八、开始你的第一个任务

如果还没有想好具体接口，可以直接从这句话开始：

~~~text
使用 $ycloud-integration-architect 帮我规划 YCloud 接入。

我希望实现的业务目标是：……
我们当前的系统情况是：……
本次先只要方案，不修改代码、不调用真实 API。

请帮我梳理整体流程，指出需要补充的信息，
并给出可以交给技术团队的实施与验收清单。
~~~

先把一个业务流程讲清楚，再逐步完成开发与验证。