cosmoe-bot/.qoder/repowiki/zh/content/Telegram 集成/命令系统/基础命令.md

基础命令

本文引用的文件

• src/index.ts
• src/command/index.ts
• src/command/handlers/start.ts
• src/command/handlers/login.ts
• src/command/handlers/logout.ts
• src/client/cosmoe.ts
• package.json

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能与可靠性考量
8. 故障排查指南
9. 结论
10. 附录：命令扩展与最佳实践

简介

本文件聚焦于基础命令的实现与使用，包括 /start、/login、/logout 的功能特性、参数处理、响应格式与错误处理机制，并解释命令注册方式与最佳实践。同时提供调用示例、常见使用场景以及扩展与自定义指导建议，帮助开发者快速理解与维护该机器人。

项目结构

• 入口与命令注册
  • 入口文件负责初始化 Bot 并调用命令注册函数，设置命令菜单。
  • 命令注册集中在一个模块中，统一挂载命令、对话与回调处理。
• 命令处理器
  • 每个命令对应一个处理器文件，职责单一，便于测试与扩展。

• 客户端封装

  • 对外服务（Cosmoe）接口通过客户端类统一封装，便于认证与数据交互。

    graph TB
    A["入口<br/>src/index.ts"] --> B["命令注册<br/>src/command/index.ts"]
    B --> C["开始命令处理器<br/>src/command/handlers/start.ts"]
    B --> D["登录命令处理器<br/>src/command/handlers/login.ts"]
    B --> E["登出命令处理器<br/>src/command/handlers/logout.ts"]
    D --> F["Cosmoe 客户端<br/>src/client/cosmoe.ts"]
    E --> F
    

图表来源

• src/index.ts
• src/command/index.ts
• src/command/handlers/start.ts
• src/command/handlers/login.ts
• src/command/handlers/logout.ts
• src/client/cosmoe.ts

章节来源

• src/index.ts
• src/command/index.ts

核心组件

• 命令注册器
  • 负责安装对话插件、创建对话、注册命令与消息监听、回调处理等。
• 开始命令处理器
  • 返回欢迎语与可用命令列表。
• 登录命令处理器
  • 基于对话进行交互式登录，调用外部 API 获取令牌并持久化到 KV。
• 登出命令处理器
  • 读取并删除用户凭证，清理本地状态。

章节来源

• src/command/index.ts
• src/command/handlers/start.ts
• src/command/handlers/login.ts
• src/command/handlers/logout.ts

架构总览

下图展示从请求进入至命令处理与外部服务交互的整体流程。

sequenceDiagram
participant U as "用户"
participant W as "Webhook 入口<br/>src/index.ts"
participant R as "命令注册器<br/>src/command/index.ts"
participant H as "处理器<br/>start/login/logout"
participant C as "Cosmoe 客户端<br/>src/client/cosmoe.ts"
participant K as "KV 存储<br/>COSMOE_CREDENTIALS/COSMOE_STORAGE"
U->>W : 发送命令或消息
W->>R : 初始化并注册命令
R->>R : 安装对话插件/创建对话
U->>R : 触发 /start 或 /login 或 /logout
alt /start
R->>H : 调用 handleStartCommand
H-->>U : 返回欢迎与命令列表
else /login
R->>H : 进入登录对话
H->>C : 调用 getToken 获取令牌
C-->>H : 返回认证结果
H->>K : 写入用户凭证
H-->>U : 返回登录结果
else /logout
R->>H : 调用 handleLogoutCommand
H->>K : 删除用户凭证
H-->>U : 返回登出结果
end

图表来源

• src/index.ts
• src/command/index.ts
• src/command/handlers/start.ts
• src/command/handlers/login.ts
• src/command/handlers/logout.ts
• src/client/cosmoe.ts

详细组件分析

/start 命令

• 功能特性
  • 向用户发送欢迎信息与可用命令提示。
• 参数处理
  • 无命令参数；直接读取上下文并回复。
• 响应格式
  • 文本消息，包含欢迎语与命令列表。
• 错误处理
  • 处理器内未显式抛错；若网络异常由框架层兜底。

• 使用场景

  • 新用户首次进入、需要查看可用命令时。

    flowchart TD
    S["收到 /start"] --> P["读取上下文"]
    P --> R["构造欢迎与命令列表文本"]
    R --> E["发送回复"]
    E --> X["结束"]
    

图表来源

• src/command/handlers/start.ts

章节来源

• src/command/handlers/start.ts

/login 命令

• 功能特性
  • 通过交互式对话引导用户提供用户名与密码，调用外部 API 获取令牌并保存到 KV。
• 参数处理
  • 无命令参数；通过对话等待用户输入用户名与密码。
• 响应格式
  • 文本消息，反馈登录成功或失败原因。
• 错误处理
  • 输入缺失时中止并提示；外部 API 失败时返回错误信息；异常捕获后统一提示“稍后重试”。

• 使用场景

  • 需要访问受保护资源（如历史记录）前的认证步骤。

    sequenceDiagram
    participant U as "用户"
    participant R as "命令注册器"
    participant L as "登录对话处理器"
    participant C as "Cosmoe 客户端"
    participant K as "KV 存储"
    U->>R : 触发 /login
    R->>L : 进入对话
    L->>U : 提示输入用户名
    U-->>L : 回复用户名
    L->>U : 提示输入密码
    U-->>L : 回复密码
    L->>C : 调用 getToken
    C-->>L : 返回认证结果
    alt 成功
    L->>K : 写入凭证
    L-->>U : 登录成功
    else 失败
    L-->>U : 登录失败
    end
    

图表来源

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

章节来源

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

/logout 命令

• 功能特性
  • 清除当前用户的凭证信息，完成登出。
• 参数处理
  • 无命令参数；根据上下文获取用户 ID。
• 响应格式
  • 文本消息，反馈登出成功或失败原因。
• 错误处理
  • 无法获取用户身份、KV 读取/删除异常时均给出明确提示。

• 使用场景

  • 用户主动登出或切换账号。

    flowchart TD
    S["收到 /logout"] --> G["获取用户ID"]
    G --> V{"存在凭证?"}
    V --> |否| N["提示先登录"] --> X["结束"]
    V --> |是| D["删除凭证"]
    D --> OK["发送登出成功消息"] --> X
    

图表来源

• src/command/handlers/logout.ts

章节来源

• src/command/handlers/logout.ts

依赖关系分析

• 运行时依赖
  • grammy：Telegram Bot 框架。
  • @grammyjs/conversations：对话能力。
  • @grammyjs/storage-cloudflare：Cloudflare KV 存储适配器。

• 项目内部依赖

  • 命令注册器依赖各处理器；处理器依赖 Cosmoe 客户端；KV 作为凭证存储。

    graph LR
    P["package.json"] --> G["grammy"]
    P --> C["@grammyjs/conversations"]
    P --> S["@grammyjs/storage-cloudflare"]
    IDX["src/command/index.ts"] --> HSTART["handlers/start.ts"]
    IDX --> HLOGIN["handlers/login.ts"]
    IDX --> HLOGOUT["handlers/logout.ts"]
    HLOGIN --> CC["client/cosmoe.ts"]
    HLOGOUT --> CC
    

图表来源

• package.json
• src/command/index.ts
• src/command/handlers/start.ts
• src/command/handlers/login.ts
• src/command/handlers/logout.ts
• src/client/cosmoe.ts

章节来源

• package.json
• src/command/index.ts

性能与可靠性考量

• 对话存储
  • 使用 Cloudflare KV 作为对话状态存储，具备跨实例一致性与低延迟特性。
• 异常处理
  • 登录与登出处理器均包含 try/catch，避免崩溃并返回友好提示。
• 命令菜单
  • 在入口处一次性设置命令菜单，减少重复调用带来的开销。

章节来源

• src/command/index.ts
• src/index.ts

故障排查指南

• /start 无响应
  • 检查命令注册是否生效；确认入口已调用命令注册器。
• /login 无法完成
  • 确认外部 API 可达且凭据正确；检查 KV 写入权限；查看控制台日志定位异常。
• /logout 无效
  • 确认 KV 中是否存在该用户的凭证；检查删除操作是否成功。
• 命令菜单未显示
  • 检查入口设置命令菜单的调用是否执行；关注错误日志。

章节来源

• src/index.ts
• src/command/index.ts
• src/command/handlers/login.ts
• src/command/handlers/logout.ts

结论

基础命令围绕“欢迎引导—认证—清理”的核心路径构建，采用清晰的职责分离与健壮的错误处理策略。通过对话与 KV 的结合，实现了良好的用户体验与可维护性。后续扩展可在现有注册器与客户端封装基础上，按需新增命令与对话。

附录：命令扩展与最佳实践

• 命令注册方式
  • 在命令注册器中添加 bot.command 或 bot.hears，并绑定对应的处理器。
  • 对话型命令通过 createConversation 注册并在命令中 enter 对话。
• 参数与上下文
  • 优先从上下文提取用户信息与消息内容；对空值进行显式校验与提示。
• 响应格式
  • 统一使用文本消息；必要时配合按钮或内联键盘以提升交互体验。
• 错误处理
  • 包裹关键流程在 try/catch 中；对 KV 读写、外部 API 调用分别处理异常。
• 扩展建议
  • 将通用逻辑抽象为工具函数（如 KV 访问、API 调用包装），降低重复代码。
  • 为每个命令编写单元测试，覆盖正常与异常分支。
  • 对敏感信息（如令牌）仅在内存中使用，持久化时确保键名唯一且有时间戳。

章节来源

• src/command/index.ts
• src/command/handlers/login.ts
• src/command/handlers/logout.ts