扩展开发.md 14 KB
扩展开发
本文引用的文件
- src/index.ts
- src/command/index.ts
- src/client/cosmoe.ts
- src/scheduler/index.ts
- src/command/handlers/start.ts
- src/command/handlers/login.ts
- src/command/handlers/events.ts
- src/command/handlers/history.ts
- src/command/handlers/bookEvent.ts
- src/command/handlers/cancel.ts
- package.json
- tsconfig.json
- worker-configuration.d.ts
目录
简介
本指南面向希望为 Cosmoe Bot 进行扩展开发的工程师，覆盖以下主题：
- 如何新增命令处理器：从命令注册、参数解析到业务逻辑实现的完整流程
- 对话状态管理的扩展方法：自定义对话状态、状态转换规则、数据持久化策略
- 新增 API 客户端：端点封装、认证集成、统一错误处理
- 插件系统的使用：基于 grammY 的插件架构扩展功能
- 最佳实践与代码规范：确保新功能与现有系统兼容一致
- 实际扩展示例与常见场景：快速上手与问题定位
项目结构
Cosmoe Bot 采用按职责分层的组织方式：
- 入口与运行时：Cloudflare Worker 入口负责初始化 Bot、注册命令菜单、接入 Webhook 与定时任务
- 命令层：集中注册命令与回调，协调对话与业务处理器
- 业务处理器：每个命令对应一个处理器模块，负责参数解析与调用 API 客户端
- API 客户端：对第三方 API 的统一封装，提供认证、错误处理与数据模型
调度器：基于 Cloudflare Cron 的定时任务，用于推送新活动通知等
graph TB A["入口<br/>src/index.ts"] --> B["命令注册与对话<br/>src/command/index.ts"] B --> C["命令处理器<br/>src/command/handlers/*.ts"] C --> D["API 客户端<br/>src/client/cosmoe.ts"] A --> E["定时任务<br/>src/scheduler/index.ts"] A --> F["环境变量与类型<br/>worker-configuration.d.ts"]
图表来源
- src/index.ts
- src/command/index.ts
- src/client/cosmoe.ts
- src/scheduler/index.ts
章节来源
- src/index.ts
- src/command/index.ts
- src/client/cosmoe.ts
- src/scheduler/index.ts
- worker-configuration.d.ts
核心组件
- Bot 与上下文：通过 grammY 初始化 Bot，并注入对话风味（ConversationFlavor）以支持对话状态
- 命令注册中心：集中安装 conversations 插件、KV 存储适配器，并注册各类命令与回调
- API 客户端：封装第三方 API 的认证、端点与错误处理，统一返回结构
- KV 持久化：使用 Cloudflare KV 作为对话状态与用户凭证的存储介质
- 定时任务：基于 Cloudflare Cron 推送新活动通知
章节来源
- src/index.ts
- src/command/index.ts
- src/client/cosmoe.ts
- src/scheduler/index.ts
架构总览
下图展示了从用户输入到 API 调用与 KV 存取的整体流程。
sequenceDiagram
participant U as "用户"
participant W as "Worker 入口<br/>src/index.ts"
participant B as "Bot/命令注册<br/>src/command/index.ts"
participant H as "命令处理器<br/>handlers/*.ts"
participant C as "API 客户端<br/>src/client/cosmoe.ts"
participant K as "KV 存储<br/>COSMOE_STORAGE/COSMOE_CREDENTIALS"
U->>W : "发送消息/回调"
W->>B : "webhookCallback 分发"
B->>H : "匹配命令/正则/回调键"
H->>K : "读取/写入对话状态/凭证"
H->>C : "调用 API 方法"
C-->>H : "返回统一结构"
H-->>U : "回复消息/内联键盘"
图表来源
- src/index.ts
- src/command/index.ts
- src/client/cosmoe.ts
详细组件分析
命令注册与路由
- 安装对话插件与 KV 存储：通过 @grammyjs/storage-cloudflare 的 KvAdapter 将对话状态持久化至 KV
- 注册命令与回调：
- 基础命令：/start、/events、/history、/login、/logout
- 正则路由：/event{id}、/book{eventid}{slotid}、/cancel{booking_id}
- 回调查询：确认取消、优惠券选择等
设置命令菜单：在入口中一次性设置 Bot 命令列表
flowchart TD A["setupCommands 启动"] --> B["安装 conversations 插件"] B --> C["注册命令与回调"] C --> D["/start /events /history /login /logout"] C --> E["正则路由：/event_*/book_*/cancel_*"] C --> F["回调查询：confirm_cancel_* / select_coupon_*"] A --> G["设置命令菜单"]
图表来源
- src/command/index.ts
- src/index.ts
章节来源
- src/command/index.ts
- src/index.ts
对话状态管理扩展
- 自定义对话状态：通过 conversations 插件与 KV 存储，对话状态可跨多轮消息保存
- 状态转换规则：在对话处理器内部使用 conversation.wait() 等 API 控制等待与流转
数据持久化策略：KV 适配器负责序列化/反序列化，异常时记录日志并保持健壮性
sequenceDiagram participant U as "用户" participant B as "Bot" participant CV as "对话处理器<br/>login.ts" participant K as "KV 存储" U->>B : "/login" B->>CV : "enter('login')" CV->>U : "提示输入用户名" U->>CV : "用户名" CV->>U : "提示输入密码" U->>CV : "密码" CV->>K : "写入凭证" CV-->>U : "登录结果"
图表来源
- src/command/index.ts
- src/command/handlers/login.ts
章节来源
- src/command/index.ts
- src/command/handlers/login.ts
API 客户端集成指南
- 端点封装：每个 API 方法封装为独立方法，统一参数与返回结构
- 认证机制：支持显式设置凭证或通过登录流程自动获取并存入 KV
错误处理：统一返回结构包含 code/msg/data；在客户端内部抛出语义化错误或返回错误码
classDiagram class CosmoeClient { +getToken(username, password) +setCredentials(userId, token) +getCredentials() +isAuthenticated() +getEvents() +getEventDetail(eventId) +getProfile() +getMyBookings() +bookEvent(request) +changePassword(...) +getUserProfile() +getAvailableCoupons(eventId) +updatePaymentOrder(...) +updateBookingNote(...) +cancelBooking(bookingId) +selfReschedule(...) +selfTransfer(...) +register(...) }
图表来源
- src/client/cosmoe.ts
章节来源
- src/client/cosmoe.ts
新增命令处理器：从零到一
- 步骤概览 1) 在命令注册处引入新处理器并注册命令/回调 2) 在处理器中解析参数（命令参数、正则捕获、回调数据） 3) 读取 KV 凭证或对话状态，调用 API 客户端 4) 组织消息内容，必要时构造内联键盘 5) 返回响应并处理异常
- 参考实现路径
- 基础命令：/start、/events、/history、/login、/logout
- 参数解析：正则路由与回调键解析
- KV 读写：凭证与对话状态
- API 调用：统一在处理器中调用 CosmoeClient
章节来源
- src/command/index.ts
- src/command/handlers/start.ts
- src/command/handlers/events.ts
- src/command/handlers/history.ts
- src/command/handlers/bookEvent.ts
- src/command/handlers/cancel.ts
插件系统与扩展点
- conversations 插件：用于多轮对话与状态持久化
- @grammyjs/storage-cloudflare：KV 存储适配器
- grammY 中间件与插件：可在入口或命令注册阶段安装更多插件
章节来源
- src/command/index.ts
- package.json
定时任务与通知
- 触发时机：Cloudflare Cron 定时触发
- 逻辑要点：拉取最新事件、对比上次 ID、向已登录用户逐一推送通知
KV 使用：存储最新事件 ID 与用户凭证
sequenceDiagram participant S as "调度器<br/>src/scheduler/index.ts" participant C as "API 客户端" participant K as "KV 存储" participant T as "Telegram Bot" S->>C : "getEvents()" C-->>S : "事件列表" S->>K : "读取/更新 latestEventId" loop 遍历新事件 S->>K : "列出已注册用户" S->>T : "sendMessage(用户, 新活动通知)" end
图表来源
- src/scheduler/index.ts
章节来源
- src/scheduler/index.ts
依赖关系分析
- 运行时依赖：grammy、@grammyjs/conversations、@grammyjs/storage-cloudflare
类型与环境：通过 wrangler 生成的类型声明与 Cloudflare Worker 环境对接
graph LR P["package.json 依赖"] --> G["grammy"] P --> GC["conversations"] P --> KS["@grammyjs/storage-cloudflare"] T["tsconfig.json 编译配置"] --> R["运行时类型/严格检查"] W["worker-configuration.d.ts"] --> E["Env 类型注入"]
图表来源
- package.json
- tsconfig.json
- worker-configuration.d.ts
章节来源
- package.json
- tsconfig.json
- worker-configuration.d.ts
性能考量
- KV 读写：对话状态与凭证均走 KV，注意批量读取与序列化开销
- API 调用：避免在高频路径重复请求，可结合缓存策略（如仅在需要时刷新）
- 消息长度：输出内容需遵守 Telegram API 限制，必要时截断或分段发送
- 并发控制：定时任务与 Webhook 并发执行，注意 KV 写入竞争与幂等设计
故障排查指南
- 常见错误与处理
- KV 读写异常：在对话存储适配器中已记录错误日志，检查命名空间权限与键名
- 认证失败：确认凭证是否过期或被清理，必要时引导用户重新登录
- API 返回非 200：在处理器中统一解析 msg 字段并反馈给用户
- 正则解析失败：检查命令格式与回调键拼接规则
- 日志与可观测性
- 在命令处理器与 API 客户端中保留必要的错误日志
- 定时任务中对每个用户的推送结果进行验证与日志记录
章节来源
- src/command/index.ts
- src/command/handlers/history.ts
- src/client/cosmoe.ts
结论
通过统一的命令注册中心、KV 持久化的对话状态、以及统一封装的 API 客户端，Cosmoe Bot 提供了清晰的扩展路径。新增命令时遵循“注册—解析—调用—回复—异常”的闭环流程，并在处理器中完成 KV 与 API 的交互，即可快速实现新功能并与现有系统保持一致。
附录
新增命令处理器最佳实践
- 命令注册
- 在命令注册文件中引入处理器并注册命令/回调
- 为回调键与正则表达式定义稳定的格式，便于解析与维护
- 参数解析
- 使用正则捕获关键字段，或在处理器中解析命令文本
- 对用户输入进行最小化校验，尽早失败
- 业务逻辑
- 优先读取 KV 凭证或对话状态，再调用 API 客户端
- 统一处理 API 返回结构，提取 msg 作为用户可见错误提示
- 消息与交互
- 必要时构造内联键盘，区分编辑消息与发送新消息
- 控制消息长度，避免超过平台限制
- 异常处理
- 在处理器中捕获异常并记录日志，向用户返回友好提示
- 对于 KV 与网络异常，区分重试策略与降级方案
章节来源
- src/command/index.ts
- src/command/handlers/bookEvent.ts
- src/command/handlers/cancel.ts
对话状态扩展清单
- 自定义对话：使用 createConversation 定义新对话，绑定环境变量
- 状态读写：通过 conversations 插件与 KV 适配器实现状态持久化
- 等待与恢复：在对话处理器中使用 wait/answerCallbackQuery 等 API 控制流程
章节来源
- src/command/index.ts
API 客户端扩展清单
- 新增端点：在客户端类中新增方法，遵循统一的参数与返回结构
- 认证集成：支持 setCredentials 或通过登录流程自动写入 KV
- 错误处理：在客户端内部抛出语义化错误或返回错误码，由调用方统一处理
章节来源
- src/client/cosmoe.ts
插件系统使用建议
- conversations：用于多轮对话与状态持久化
- @grammyjs/storage-cloudflare：KV 存储适配器
- grammY 生态：根据需求引入中间件或插件，注意版本兼容与类型声明
章节来源
- package.json
- src/command/index.ts