# 基础命令

<cite>
**本文引用的文件**
- [src/index.ts](file://src/index.ts)
- [src/command/index.ts](file://src/command/index.ts)
- [src/command/handlers/start.ts](file://src/command/handlers/start.ts)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts)
- [package.json](file://package.json)
</cite>

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

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

## 项目结构
- 入口与命令注册
  - 入口文件负责初始化 Bot 并调用命令注册函数，设置命令菜单。
  - 命令注册集中在一个模块中，统一挂载命令、对话与回调处理。
- 命令处理器
  - 每个命令对应一个处理器文件，职责单一，便于测试与扩展。
- 客户端封装
  - 对外服务（Cosmoe）接口通过客户端类统一封装，便于认证与数据交互。

```mermaid
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](file://src/index.ts#L13-L35)
- [src/command/index.ts](file://src/command/index.ts#L20-L110)
- [src/command/handlers/start.ts](file://src/command/handlers/start.ts#L1-L6)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts#L1-L34)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L171)

章节来源
- [src/index.ts](file://src/index.ts#L13-L35)
- [src/command/index.ts](file://src/command/index.ts#L20-L110)

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

章节来源
- [src/command/index.ts](file://src/command/index.ts#L20-L110)
- [src/command/handlers/start.ts](file://src/command/handlers/start.ts#L1-L6)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts#L1-L34)

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

```mermaid
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](file://src/index.ts#L13-L35)
- [src/command/index.ts](file://src/command/index.ts#L20-L110)
- [src/command/handlers/start.ts](file://src/command/handlers/start.ts#L1-L6)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts#L1-L34)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L171)

## 详细组件分析

### /start 命令
- 功能特性
  - 向用户发送欢迎信息与可用命令提示。
- 参数处理
  - 无命令参数；直接读取上下文并回复。
- 响应格式
  - 文本消息，包含欢迎语与命令列表。
- 错误处理
  - 处理器内未显式抛错；若网络异常由框架层兜底。
- 使用场景
  - 新用户首次进入、需要查看可用命令时。

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

图表来源
- [src/command/handlers/start.ts](file://src/command/handlers/start.ts#L1-L6)

章节来源
- [src/command/handlers/start.ts](file://src/command/handlers/start.ts#L1-L6)

### /login 命令
- 功能特性
  - 通过交互式对话引导用户提供用户名与密码，调用外部 API 获取令牌并保存到 KV。
- 参数处理
  - 无命令参数；通过对话等待用户输入用户名与密码。
- 响应格式
  - 文本消息，反馈登录成功或失败原因。
- 错误处理
  - 输入缺失时中止并提示；外部 API 失败时返回错误信息；异常捕获后统一提示“稍后重试”。
- 使用场景
  - 需要访问受保护资源（如历史记录）前的认证步骤。

```mermaid
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](file://src/command/index.ts#L54-L66)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L171)

章节来源
- [src/command/index.ts](file://src/command/index.ts#L54-L66)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L171)

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

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

图表来源
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts#L1-L34)

章节来源
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts#L1-L34)

## 依赖关系分析
- 运行时依赖
  - grammy：Telegram Bot 框架。
  - @grammyjs/conversations：对话能力。
  - @grammyjs/storage-cloudflare：Cloudflare KV 存储适配器。
- 项目内部依赖
  - 命令注册器依赖各处理器；处理器依赖 Cosmoe 客户端；KV 作为凭证存储。

```mermaid
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](file://package.json#L18-L22)
- [src/command/index.ts](file://src/command/index.ts#L1-L11)
- [src/command/handlers/start.ts](file://src/command/handlers/start.ts#L1-L6)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts#L1-L34)
- [src/client/cosmoe.ts](file://src/client/cosmoe.ts#L113-L171)

章节来源
- [package.json](file://package.json#L18-L22)
- [src/command/index.ts](file://src/command/index.ts#L1-L11)

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

章节来源
- [src/command/index.ts](file://src/command/index.ts#L20-L52)
- [src/index.ts](file://src/index.ts#L23-L32)

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

章节来源
- [src/index.ts](file://src/index.ts#L23-L32)
- [src/command/index.ts](file://src/command/index.ts#L20-L52)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L70-L73)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts#L30-L33)

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

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

章节来源
- [src/command/index.ts](file://src/command/index.ts#L20-L110)
- [src/command/handlers/login.ts](file://src/command/handlers/login.ts#L1-L75)
- [src/command/handlers/logout.ts](file://src/command/handlers/logout.ts#L1-L34)