快速开始

本文引用的文件

package.json
wrangler.jsonc
tsconfig.json
.dev.vars
worker-configuration.d.ts
src/index.ts
src/command/index.ts
src/command/handlers/start.ts
src/command/handlers/login.ts
src/scheduler/index.ts
src/client/cosmoe.ts
vitest.config.mts
test/env.d.ts

简介

本指南面向首次接触 Cosmoe Bot 的开发者，帮助你在本地快速完成环境搭建与首次运行。你将学到：

如何安装 Node.js 与 npm（含版本建议）
如何安装与配置 Cloudflare Workers CLI（wrangler）
如何获取并配置 Telegram Bot Token、Cosmoe 服务端 API 凭证等必要参数
如何配置本地开发环境（.dev.vars、TypeScript 编译、Wrangler 配置）
如何启动本地开发服务器并进行基础功能测试
常见环境问题的解决方案与调试技巧

项目结构

Cosmoe Bot 是一个基于 Cloudflare Workers 的 Telegram 机器人，采用 TypeScript 开发，并通过 Wrangler 进行本地开发与部署。核心目录与文件如下：

根目录包含包管理与构建配置：package.json、wrangler.jsonc、tsconfig.json、.dev.vars、vitest.config.mts、test/env.d.ts
源码位于 src/ 下：
- 入口与调度：src/index.ts、src/scheduler/index.ts
- 命令系统：src/command/index.ts 及其 handlers 子目录
- 客户端：src/client/cosmoe.ts（封装对 Cosmoe 服务端 API 的调用）

类型声明：worker-configuration.d.ts（由 wrangler 生成）

graph TB
subgraph "根目录"
Pkg["package.json"]
Wrangler["wrangler.jsonc"]
TSConf["tsconfig.json"]
DevVars[".dev.vars"]
Vitest["vitest.config.mts"]
TestEnv["test/env.d.ts"]
Types["worker-configuration.d.ts"]
end
subgraph "源码 src/"
Entry["src/index.ts"]
Cmd["src/command/index.ts"]
Handlers["src/command/handlers/*.ts"]
Scheduler["src/scheduler/index.ts"]
Client["src/client/cosmoe.ts"]
end
Pkg --> Wrangler
Wrangler --> Entry
Entry --> Cmd
Entry --> Scheduler
Cmd --> Handlers
Entry --> Client
Types --> Entry

图表来源

wrangler.jsonc
src/index.ts
src/command/index.ts
src/scheduler/index.ts
src/client/cosmoe.ts

章节来源

package.json
wrangler.jsonc
tsconfig.json
.dev.vars
worker-configuration.d.ts

核心组件

入口与路由：src/index.ts 负责初始化 Bot、注册命令、设置菜单、处理 Webhook 回调，并在定时触发时调用调度逻辑。
命令系统：src/command/index.ts 使用 grammY 与 @grammyjs/conversations 插件，结合 KV 存储实现对话式交互与状态持久化。
调度器：src/scheduler/index.ts 周期性检查新活动并向已注册用户推送通知。
客户端：src/client/cosmoe.ts 封装对 Cosmoe 服务端 API 的调用，包括认证、事件查询、预约、历史查询等。
配置与类型：wrangler.jsonc 定义 Worker 名称、入口、兼容日期、KV 绑定、计划任务；tsconfig.json 控制编译选项；.dev.vars 提供本地开发密钥；worker-configuration.d.ts 由 wrangler 生成运行时类型。

章节来源

src/index.ts
src/command/index.ts
src/scheduler/index.ts
src/client/cosmoe.ts
wrangler.jsonc
tsconfig.json
.dev.vars
worker-configuration.d.ts

架构总览

下图展示了本地开发与运行时的关键交互：本地通过 wrangler dev 启动 Worker，接收 Telegram Webhook 请求；Worker 初始化 grammY Bot 并注册命令；命令执行时可访问 KV 与 Cosmoe API；同时 Worker 在计划时间触发调度逻辑，向用户发送通知。

sequenceDiagram
participant TG as "Telegram"
participant CF as "Cloudflare Workers"
participant Bot as "grammY Bot"
participant Cmd as "命令系统"
participant Sched as "调度器"
participant KV as "KV 命名空间"
participant API as "Cosmoe 服务端"
TG->>CF : "Webhook 请求"
CF->>Bot : "初始化 Bot 与命令"
Bot->>Cmd : "分发命令/回调"
Cmd->>KV : "读取/写入对话状态/凭证"
Cmd->>API : "调用 Cosmoe API"
API-->>Cmd : "返回结果"
Cmd-->>TG : "回复消息"
CF->>Sched : "定时触发"
Sched->>API : "拉取活动列表"
API-->>Sched : "返回活动"
Sched->>KV : "读取/更新最新活动 ID"
Sched-->>TG : "向已注册用户推送通知"

图表来源

src/index.ts
src/command/index.ts
src/scheduler/index.ts
src/client/cosmoe.ts

详细组件分析

环境与工具准备

Node.js 与 npm
- 推荐使用当前 LTS 版本（如 20.x 或 22.x），确保 npm 与 Node.js 版本匹配。
- 安装完成后，验证版本：node --version、npm --version。
Cloudflare Workers CLI（wrangler）
- 全局安装：npm install -g wrangler
- 首次使用需登录：wrangler login
- 验证安装：wrangler --version

章节来源

package.json

获取与配置必要参数

Telegram Bot Token
- 通过 @BotFather 创建机器人并获取 Token。
- 将 Token 写入 .dev.vars 中的 BOT_TOKEN 字段。
Cosmoe 服务端 API 凭证
- 本仓库示例中未包含 Cosmoe API 密钥字段，通常可通过 KV 或环境变量注入。请根据实际部署需求在 wrangler.jsonc 的 vars 或 KV 中配置。
Cloudflare KV 命名空间
- 已在 wrangler.jsonc 中定义两个 KV 绑定：COSMOE_CREDENTIALS（存储用户凭证）、COSMOE_STORAGE（存储会话与状态）。
- 本地开发时，wrangler 会自动创建本地 KV；生产部署需在 Cloudflare 控制台创建并绑定。

章节来源

.dev.vars
wrangler.jsonc

本地开发环境设置

安装依赖
- 在项目根目录执行：npm install
生成运行时类型
- 执行：wrangler types（生成 worker-configuration.d.ts）
启动本地开发服务器
- 执行：npm run dev 或 wrangler dev
- 访问 http://localhost:8787 查看日志与调试输出
配置 .dev.vars
- 确保 .dev.vars 包含 BOT_TOKEN 等本地密钥（若需要其他密钥，请按实际添加）
TypeScript 编译设置
- tsconfig.json 已启用严格模式、ES2024 目标、Bundler 模块解析等，满足 Workers 运行时要求
Wrangler 配置
- wrangler.jsonc 指定入口、兼容日期、计划任务、KV 绑定与运行观测开关

章节来源

package.json
tsconfig.json
wrangler.jsonc
.dev.vars
worker-configuration.d.ts

首次运行示例

启动本地开发服务器
- 在项目根目录执行：npm run dev
- 观察控制台输出，确认 Worker 启动成功
设置 Telegram Webhook（可选）
- 若需使用 Webhook，可在部署后通过 Telegram Bot API 设置 webhook URL；本地开发默认使用 wrangler dev 提供的本地端点
测试基本功能
- 在 Telegram 中向机器人发送 /start，应收到欢迎信息
- 发送 /login，进入交互式登录流程，输入用户名与密码
- 成功登录后，凭证将保存至 KV 命名空间
- 发送 /events 查看活动列表
- 发送 /history 查看预约历史
调度功能验证
- 等待计划任务触发（默认每分钟一次），观察控制台日志与通知推送情况

章节来源

src/index.ts
src/command/handlers/start.ts
src/command/handlers/login.ts
src/scheduler/index.ts

关键流程图解

登录交互流程（命令驱动）

flowchart TD
Start(["用户发送 /login"]) --> EnterConv["进入登录对话"]
EnterConv --> AskUser["提示输入用户名"]
AskUser --> WaitUser["等待用户输入"]
WaitUser --> AskPass["提示输入密码"]
AskPass --> WaitPass["等待用户输入"]
WaitPass --> CallAPI["调用 Cosmoe API 获取 Token"]
CallAPI --> CheckRes{"认证成功？"}
CheckRes --> |是| SaveCreds["以 Telegram 用户 ID 为键保存凭证到 KV"]
SaveCreds --> ReplyOK["回复登录成功"]
CheckRes --> |否| ReplyFail["回复失败原因"]
ReplyOK --> End(["结束"])
ReplyFail --> End

图表来源

src/command/handlers/login.ts
src/client/cosmoe.ts

调度通知流程

flowchart TD
Cron(["定时触发"]) --> LoadLatest["读取最新活动 ID"]
LoadLatest --> FetchEvents["调用 Cosmoe API 获取活动列表"]
FetchEvents --> FilterNew{"过滤新活动"}
FilterNew --> |有| ListUsers["遍历已注册用户"]
FilterNew --> |无| End(["结束"])
ListUsers --> SendMsg["向每个用户发送通知"]
SendMsg --> UpdateID["更新最新活动 ID"]
UpdateID --> End

图表来源

src/scheduler/index.ts

依赖关系分析

运行时依赖
- grammY：Telegram 机器人框架
- @grammyjs/conversations：对话式交互插件
- @grammyjs/storage-cloudflare：KV 存储适配器

开发依赖

wrangler：Cloudflare Workers CLI
vitest 与 @cloudflare/vitest-pool-workers：Workers 环境下的单元测试

typescript：类型支持与编译

graph LR
Entry["src/index.ts"] --> Gram["grammY"]
Entry --> Conv["@grammyjs/conversations"]
Entry --> KVStore["@grammyjs/storage-cloudflare"]
Entry --> Client["src/client/cosmoe.ts"]
Entry --> Cmd["src/command/index.ts"]
Cmd --> Handlers["src/command/handlers/*.ts"]
Entry --> Sched["src/scheduler/index.ts"]
Wrangler["wrangler.jsonc"] --> Entry
Pkg["package.json"] --> Wrangler
Pkg --> Types["worker-configuration.d.ts"]

图表来源

src/index.ts
src/command/index.ts
src/scheduler/index.ts
src/client/cosmoe.ts
wrangler.jsonc
package.json
worker-configuration.d.ts

章节来源

package.json
wrangler.jsonc

性能注意事项

使用 KV 存储对话状态与用户凭证，避免在内存中缓存大量数据
调度任务按需触发，避免频繁拉取 Cosmoe API；可利用本地存储的最新活动 ID 做增量判断
严格模式与 noEmit 配置有助于在本地尽早发现类型问题，减少运行时错误
对外请求建议使用合理的超时与重试策略（可在客户端层扩展）

故障排查指南

本地无法启动
- 检查 Node.js 与 npm 版本是否满足要求
- 确认已安装 wrangler 并执行过 wrangler login
- 清理缓存后重新安装依赖：npm ci 或删除 node_modules 后 npm install
.dev.vars 未生效
- 确认 .dev.vars 位于项目根目录且包含正确的键值（如 BOT_TOKEN）
- 重启本地开发服务器使变更生效
KV 读写异常
- 确认 wrangler.jsonc 中 KV 绑定名称与代码一致（如 COSMOE_CREDENTIALS、COSMOE_STORAGE）
- 检查本地 KV 是否已创建，必要时删除临时目录后重启开发服务器
Telegram Webhook 无法接收消息
- 本地开发默认使用 wrangler dev 提供的端点；如需外部可访问，请参考官方文档配置自定义域名与证书
调度任务未触发
- 检查 wrangler.jsonc 中 triggers.crons 配置是否正确
- 确认本地开发服务器正在运行，且控制台显示定时日志
单元测试报错
- 确认 vitest.config.mts 正确指向 wrangler.jsonc
- 测试环境类型声明需与 Env 接口保持一致

章节来源

.dev.vars
wrangler.jsonc
vitest.config.mts
test/env.d.ts

结论

通过以上步骤，你可以在本地快速搭建 Cosmoe Bot 的开发环境，并完成首次运行与基础功能测试。后续可根据业务需要扩展命令、完善调度逻辑与错误处理，并在 Cloudflare 上完成正式部署。

附录

常用命令清单

安装依赖：npm install
生成类型：wrangler types
启动本地开发：npm run dev 或 wrangler dev
运行测试：npm run test
部署：npm run deploy 或 wrangler deploy

章节来源

package.json

快速开始.md 14 KB History Raw

快速开始

目录

简介

项目结构

核心组件

架构总览

详细组件分析

环境与工具准备

获取与配置必要参数

本地开发环境设置

首次运行示例

关键流程图解

登录交互流程（命令驱动）

调度通知流程

依赖关系分析

性能注意事项

故障排查指南

结论

附录

常用命令清单

快速开始.md 14 KB

History Raw