From fb43441c564b9d2ef369a378240a5406c014686d Mon Sep 17 00:00:00 2001
From: YoursFunny <admin@yoursfunny.top>
Date: Thu, 6 Aug 2026 21:21:28 +0800
Subject: [PATCH] feat: add command descriptions and document commands in
 README

All bot commands now carry English descriptions, shown in the Telegram
command menu and by /help (which prints Command::descriptions()). The
README command table explains each command's arguments and behavior:
forward channel (@channel or ID), edit-before-forward flow, template
[] placeholder semantics and per-site caption format placeholders.
---
 README.md                         | 12 +++++++-----
 crates/xmedia-bot/src/handlers.rs | 18 +++++++++---------
 2 files changed, 16 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 54c1bc1..737e53c 100644
--- a/README.md
+++ b/README.md
@@ -101,12 +101,14 @@ Telegram 只接受 443/80/88/8443 端口。
 
 | 命令 | 说明 |
 |---|---|
-| `/set_forward_channel <频道>` | 设置转发频道 |
+| `/start` | 欢迎语 |
+| `/help` | 查看全部命令及用法（即本文档的命令表） |
+| `/set_forward_channel <频道>` | 设置转发频道，参数为 `@频道名` 或频道 ID；设置后发送的媒体消息会自动转发到该频道 |
 | `/remove_forward_channel` | 取消转发频道 |
-| `/edit_before_forward` | 开关转发前编辑 |
-| `/set_template <名称>` | 将回复的消息（含 `[]`）保存为模板 |
-| `/set_format <站点> <格式>` | 自定义 caption 格式（占位符 `{url}` `{title}` `{tags}` 等） |
-| `/bot_dict` | 查看聊天状态 |
+| `/edit_before_forward` | 开关「转发前编辑」：开启后，转发成功后 bot 会发一条提示消息，回复它可修改第一条转发消息的 caption（或点击模板按钮套用模板） |
+| `/set_template <名称>` | 回复一条含 `[]` 的消息，将其保存为命名模板；转发时 `[]` 会被替换为原帖链接（配合「转发前编辑」使用） |
+| `/set_format <站点> <格式>` | 自定义某站点的 caption 格式。站点：`twitter` / `bsky` / `pixiv`。占位符：`{url}` `{author}` `{author_url}` `{title}` `{tags}` |
+| `/bot_dict` | 查看当前聊天状态（调试用） |
 
 链接处理仅限私聊；命令在任意聊天可用。
 
diff --git a/crates/xmedia-bot/src/handlers.rs b/crates/xmedia-bot/src/handlers.rs
index 7c670ee..3643635 100644
--- a/crates/xmedia-bot/src/handlers.rs
+++ b/crates/xmedia-bot/src/handlers.rs
@@ -34,23 +34,23 @@ pub static CONFIG: LazyLock<Config> = LazyLock::new(Config::load);
 static URL_TASKS: LazyLock<Semaphore> = LazyLock::new(|| Semaphore::new(8));
 
 #[derive(BotCommands, Clone)]
-#[command(rename_rule = "snake_case", description = "")]
+#[command(rename_rule = "snake_case", description = "Turn X/Pixiv/Bluesky links into media messages")]
 enum Command {
-    #[command(description = "")]
+    #[command(description = "Get started")]
     Start,
-    #[command(description = "")]
+    #[command(description = "Show command help")]
     Help,
-    #[command(description = "", parse_with = "split")]
+    #[command(description = "Set forward channel (@channel or ID)", parse_with = "split")]
     SetForwardChannel(String),
-    #[command(description = "")]
+    #[command(description = "Remove forward channel")]
     RemoveForwardChannel,
-    #[command(description = "")]
+    #[command(description = "Toggle edit-before-forward")]
     EditBeforeForward,
-    #[command(description = "", parse_with = "split")]
+    #[command(description = "Reply with [] to save as template", parse_with = "split")]
     SetTemplate(String),
-    #[command(description = "")]
+    #[command(description = "Show chat state (debug)")]
     BotDict,
-    #[command(description = "", parse_with = "split")]
+    #[command(description = "Set site caption format", parse_with = "split")]
     SetFormat(String),
 }