@will-17173/telegram-cli 0.1.1 → 0.3.0

package/README.md

@@ -2,18 +2,19 @@
 
 [简体中文](README.zh-CN.md)
 
-A TypeScript command-line client for syncing Telegram chats, listening to live messages, searching locally stored messages, and managing Telegram tasks from the terminal.
+A TypeScript command-line client for syncing Telegram chats, listening to live messages, searching locally stored messages, and inspecting groups from the terminal.
 
 ## Features
 
 - Sign in to Telegram and inspect the current account or available chats.
-- Manage multiple Telegram accounts with isolated sessions and message databases.
+- Manage multiple Telegram accounts with isolated sessions, message databases, and interactive account switching.
 - Fetch chat history into a local SQLite database for fast, offline search.
 - Sync one chat incrementally or sync many chats with a single command.
 - Listen for new messages in real time, with optional attachment summaries.
 - Download attachments from channels that restrict content saving.
-- Search, filter, summarize, and export locally stored messages.
+- Search, filter, summarize, and export locally stored messages, with reply context and media-group summaries in recent results.
 - Send, edit, and delete messages from the command line.
+- Inspect and manage groups, members, administrators, invites, forum topics, and messages.
 - Use human-readable output or structured JSON/YAML where supported.
 
 ## Built for AI agents
@@ -33,6 +34,17 @@ For example, an agent can search one account and parse the result as JSON:
 tg search "release" --account work --json
 ```
 
+### Agent skill
+
+Install the [`using-telegram-cli`](https://skills.sh/will-17173/telegram-cli/using-telegram-cli) skill to teach a supported AI coding agent how to authenticate accounts, synchronize and query messages, automate structured output, and guard Telegram write operations:
+
+```sh
+npx skills add https://github.com/will-17173/telegram-cli \
+  --skill using-telegram-cli
+```
+
+Add `--global` to make the skill available across projects instead of installing it into the current project.
+
 ## Installation
 
 Telegram CLI requires Node.js 22 or later.
@@ -54,13 +66,42 @@ tg config set --api-id <id> --api-hash <hash>
 If both `TG_API_ID` and `TG_API_HASH` are unset and the saved configuration file is missing, the CLI uses built-in Telegram API credentials. When a Telegram client is created, it writes this warning to stderr once per process:
 
 ```text
-warning: using default Telegram API credentials. Run tg config set --api-id <id> --api-hash <hash> to configure your own.
+warning: using default Telegram API credentials, which have stricter flood limits and may trigger FLOOD_WAIT during frequent or large requests. Run tg config set --api-id <id> --api-hash <hash> to configure your own.
 ```
 
 Setting only one of `TG_API_ID` or `TG_API_HASH` is an error. A malformed or unreadable saved configuration file is also an error; the CLI does not fall back to the built-in credentials in either case.
 
 Personal credentials are stored locally as sensitive configuration. Never share them. API credentials are shared by all registered accounts, while each account keeps its own authentication session.
 
+To persist a proxy for Telegram connections, run:
+
+```sh
+tg config set --proxy socks5://127.0.0.1:1080
+```
+
+For a one-command override, set `TG_PROXY` in the command environment:
+
+```sh
+TG_PROXY=http://127.0.0.1:8080 tg status
+```
+
+Supported proxy forms are `socks4://`, `socks5://`, `http://`, and `https://` proxy URLs, plus MTProxy links in the forms `tg://proxy?...` and `https://t.me/proxy?...`. A non-empty `TG_PROXY` value, after trimming surrounding whitespace, overrides the persisted proxy. If `TG_PROXY` is empty or unset, the CLI falls back to the stored proxy; if neither is configured, it connects directly.
+
+The selected proxy applies to account login and every Telegram-backed command, not only the command used in the example. Proxy URLs can contain usernames and passwords or MTProxy secrets, so treat them as sensitive. CLI output does not print the configured proxy URL. A credential-bearing proxy URL entered literally on a command line may remain in shell history or be visible through process inspection. Provide `TG_PROXY` through an appropriately protected environment or secret-loading mechanism, or otherwise avoid placing literal secrets in shared shell histories and scripts.
+
+To inspect the effective configuration in human-readable, JSON, or YAML format, run:
+
+```sh
+tg config list
+tg config list --json
+tg config list --yaml
+tg config list --show-secrets
+```
+
+This reports the effective configuration rather than the raw contents of `config.json`. API credentials are resolved from environment variables first, then stored configuration, then the built-in default. The proxy is resolved independently from `TG_PROXY` first, then stored configuration, then remains absent when neither is configured.
+
+The output reports exactly five fields: the effective API ID, API hash, credential source, proxy URL, and proxy source. The API hash is masked by default; use `--show-secrets` to display it in full. The proxy URL is always printed in full and may contain credentials or an MTProxy secret, so avoid writing `config list` output to logs or sharing it. `tg config list` does not create a Telegram client or make a network connection.
+
 Run `tg account add` to authenticate and create a local session. Other commands never start the interactive login flow.
 
 You can override the root directory for configuration, account sessions, and message databases:
@@ -90,13 +131,35 @@ tg search "keyword" --chat <chat>
 # Sync across all chats
 tg sync-all --max-chats 20 --delay 1
 
-# Listen for new messages from one or more chats
-tg listen <chat-or-id> [another-chat ...] --no-media
+# Listen for new messages and automatically download incoming attachments
+tg listen <chat-or-id> --auto-download
+
+# Use plain output, download attachments, and hide their message summaries
+tg listen <chat-or-id> --no-interactive --auto-download --no-media
 
 # Send a message
 tg send <chat> "Hello from tg"
 ```
 
+## Send messages and attachments
+
+`send` requires `<chat>`. Send text, one or more files, or files with a caption:
+
+```sh
+# Text only
+tg send <chat> "Text only"
+
+# Files only; repeat --file to preserve this order
+tg send <chat> --file ./photo.jpg --file ./clip.mp4
+
+# Caption and files
+tg send <chat> "Group caption" --file ./photo.jpg --file ./clip.mp4
+```
+
+`--file` is repeatable. Multiple files are sent in the specified order as one Telegram media group. The message is optional only when at least one file is present. When files are present, the message becomes the group caption; the CLI does not send it as a separate text message.
+
+Telegram determines which file combinations and group sizes it accepts. If Telegram rejects the requested combination or limit, the command returns an error and does not silently split the files into separate messages or groups.
+
 ## Multiple accounts
 
 Each Telegram account has its own persisted authentication session and local message database. Add and authenticate an account interactively with:
@@ -114,13 +177,18 @@ tg account list
 # Show the current account
 tg account current
 
-# Set the default account used by commands
+# Choose the default account from an interactive list
+tg account switch
+
+# Set the default account by name
 tg account switch <name>
 
 # Remove an account and its local session/data
 tg account remove <name> --force
 ```
 
+In an interactive terminal, `tg account switch` lists registered accounts, marks the current one, and accepts its number. Pass `<name>` when scripting or using `--json`, `--yaml`, or non-interactive input.
+
 Commands use the current account by default. Commands that support `--account` can target another registered account for one invocation without changing the current account:
 
 ```sh
@@ -133,12 +201,72 @@ Account names are shown by `tg account list`; they are normally derived from the
 
 Telegram API credentials apply to every registered account. You don't need to configure separate API credentials when adding another account.
 
+## Group management
+
+The `group` command keeps read-only inspection alongside management families for members, administrators, chat settings, invite links, forum topics, and messages. Use family help to see the current actions:
+
+```sh
+# Group details
+tg group info <chat> --account alice --json
+
+# Member list: type, name/username query, and bounded result count
+tg group members <chat> --type admins --query alice --limit 50 --yaml
+
+# One member's role, administrator rights, and restrictions
+tg group member <chat> <user>
+
+# Administrator audit log; --user and --type can be repeated
+tg group audit <chat> --query invite --user <user> --type member_invited --type invite_changed --limit 100 --account alice --json
+
+# Management examples (the chat argument comes before action arguments)
+tg group member ban @team @alice --yes
+tg group chat slowmode @team 30s
+tg group topic --help
+```
+
+`group members` accepts exactly these seven `--type` filters: `recent`, `all`, `admins`, `banned`, `restricted`, `bots`, and `contacts`. It defaults to `recent` and 100 results; `--limit` accepts 1 through 200. Telegram can return fewer members than its reported total, so a page is not guaranteed to enumerate the whole group.
+
+`group audit` requires group administrator rights. Its `--limit` range is 1 through 500, with a default of 100 events. Its repeatable `--user` filter selects action authors. The repeatable `--type` filter accepts exactly these 17 stable grouped event types: `info_changed`, `settings_changed`, `member_joined`, `member_left`, `member_invited`, `member_banned`, `member_unbanned`, `member_restricted`, `member_unrestricted`, `admin_promoted`, `admin_demoted`, `message_deleted`, `message_edited`, `message_pinned`, `invite_changed`, `topic_changed`, and `other`.
+
+Inspection and management actions use human-readable output by default; actions that expose `--json` or `--yaml` provide structured success or error output. Failures set a nonzero exit status. They use the current account unless `--account <name>` selects another registered account for that invocation.
+
+Management actions are grouped under `member`, `admin`, `chat`, `invite`, `topic`, and `message`. Member targets must be explicit `@username` values or numeric Telegram user IDs. Durations accept `s`, `m`, `h`, and `d` suffixes, or `off` where disabling is supported. For example, `tg group member mute @team @alice 2h --yes` temporarily mutes a member, while `tg group chat slowmode @team off` disables slow mode.
+
+Potentially destructive CLI actions refuse to connect to Telegram unless `--yes` is present. Permanently deleting a chat additionally requires `--confirm-title` with the exact current title. Interactive listen mode presents these confirmations in an Ink modal. Management requires the relevant administrator permission, and some actions require a supergroup, forum, or creator role. Ownership transfer currently reports `password_required` when Telegram requires a password; this release does not accept a password for that action.
+
+Use `tg group member info <chat> <user>` as the canonical member-details route. The legacy `tg group member <chat> <user>` form remains available, but a chat name matching a reserved member action such as `ban`, `mute`, or `info` is ambiguous and requires the canonical route.
+
+## Slash commands while listening
+
+Interactive `tg listen` presents every supported slash command in one menu. This includes `/reply` and the complete group-management catalog; group commands use the same management grammar without repeating the selected chat:
+
+```text
+/reply <message-id> <content>
+/member mute @alice 2h
+```
+
+Typing `/` opens the unified command menu, with reply first. Matching ranks exact paths, prefixes, then ordered fuzzy matches, so `/rep` and `/rpy` find `/reply`, while `/ban` finds `/member ban`. Use Up/Down to move through matches. Tab completes the selected command; Enter also completes an incomplete selection, or runs a complete command. Esc closes the menu, result, or confirmation.
+
+Group-command availability and permission checks are unchanged: unavailable actions remain disabled, risky actions open a confirmation modal, and chat deletion also asks for the exact title. When listening to more than one chat, set an unambiguous outgoing target with `--send-to <chat>` before using group commands, for example `tg listen @team @ops --send-to @team`.
+
 ## Online and local commands
 
-Online commands connect to Telegram and require a valid session. These include `status`, `whoami`, `chats`, `history`, `sync`, `sync-all`, `refresh`, `info`, `send`, `edit`, `delete`, and `listen`.
+Online commands connect to Telegram and require a valid session. These include `status`, `whoami`, `chats`, `history`, `sync`, `sync-all`, `refresh`, `info`, all `group` inspection and management families, `send`, `edit`, `delete`, and `listen`.
 
 Local commands read or modify the selected account's message database without connecting to Telegram. These include `search`, `recent`, `stats`, `top`, `timeline`, `today`, `filter`, `export`, and `purge`.
 
+## Review recent messages
+
+`tg recent` shows messages stored during the last 24 hours, with a default limit of 50. Filter the results by chat or sender, or change the time window and limit:
+
+```sh
+tg recent --chat <chat> --sender <sender> --hours 6 --limit 100
+```
+
+Human-readable output groups each Telegram media group into one row and summarizes its attachments. The `ID` column lists every source message ID in that row. Replies include the original message's time, sender, ID, and text when the target exists locally in the same chat. Otherwise, the output identifies the missing local message ID.
+
+JSON and YAML output keep the stored-message structure for scripts. `recent` reads local SQLite data and does not connect to Telegram.
+
 ## Command reference
 
 Run the built-in help for the complete, current command list:
@@ -154,11 +282,13 @@ Common commands:
 | `tg account add` | Authenticate and register another Telegram account. |
 | `tg account list` | List registered accounts and show which one is current. |
 | `tg account current` | Show the current account. |
-| `tg account switch <name>` | Set the default account used by commands. |
+| `tg account switch [name]` | Select the default account interactively or set it by name. |
 | `tg account remove <name> --force` | Remove an account and its local session/data. |
 | `tg status` | Check whether the Telegram account is authenticated. |
 | `tg whoami` | Show basic authenticated account information. |
 | `tg config set --api-id <id> --api-hash <hash>` | Save Telegram API credentials for persistent use. |
+| `tg config set --proxy <url>` | Save an optional proxy for account login and Telegram-backed commands. |
+| `tg config list [--show-secrets]` | Show effective configuration values and sources; the proxy URL is always visible. |
 | `tg chats` | List available chats. |
 | `tg history <chat> -n <limit>` | Fetch and store full chat history (default up to 1000 messages). |
 | `tg sync <chat>` | Incrementally sync new messages for one chat. |
@@ -166,15 +296,21 @@ Common commands:
 | `tg refresh` | Alias-like command for bulk sync with same runtime options as `sync-all`. |
 | `tg listen [chat ...]` | Stream incoming messages from selected chats or all chats. |
 | `tg listen --no-media` | Hide attachment summary lines while listening. |
+| `tg listen <chat-or-id> --auto-download` | Automatically download incoming attachments while listening. |
 | `tg search "keyword" --chat <chat>` | Search messages already stored locally. |
 | `tg recent`, `tg today`, `tg stats`, `tg top`, `tg timeline` | Explore local message data. |
 | `tg filter <keywords>` | Filter local messages by keyword with optional chat/hour filters. |
 | `tg export <chat>` | Export local messages from a chat. |
-| `tg send <chat> "Hello from tg"` | Send a message. |
+| `tg send <chat> [message] [--file <path> ...]` | Send text, files, or a captioned media group. |
 | `tg edit <chat> <msgId> <text>` | Edit a message. |
 | `tg delete <chat> <msgIds...>` | Delete one or more messages. |
 | `tg purge <chat> --yes` | Remove a chat's locally stored messages. |
 | `tg info <chat>` | Show metadata for a Telegram chat. |
+| `tg group info <chat>` | Show read-only group or supergroup details. |
+| `tg group members <chat> [--type <type>] [--query <text>] [--limit <count>]` | List and filter members (default `recent`, limit 100; maximum 200). |
+| `tg group member <chat> <user>` | Show one member's role, rights, and restrictions. |
+| `tg group audit <chat> [--query <text>] [--user <user>] [--type <type>] [--limit <count>]` | Query the administrator audit log (default 100; maximum 500). |
+| `tg group member/admin/chat/invite/topic/message --help` | Discover group management actions by family. |
 
 All sync-like commands write to local SQLite storage. The `sync-all` and `refresh` commands process multiple chats based on locally stored message IDs.
 
@@ -195,6 +331,13 @@ Use `tg <command> --help` to inspect command-specific options. For example, `lis
 
 - `sync-all` and `refresh` are batch operations for local persistence; they are not read-only.
 - `listen` prints a concise separator for each incoming message and can optionally suppress attachment summaries.
+- Telegram media groups appear as one incoming message with a combined attachment summary.
+- Reply output includes the original message's local context when available, or identifies the missing message ID.
+- In interactive `listen`, reply with `/reply <message-id> <content>`. Add attachments with repeatable `--file <path>` options; quote paths that contain spaces.
+- Contact cards show the available name and phone number in attachment summaries. They aren't downloadable attachments and are hidden by `--no-media`.
+- `listen --auto-download` works in both interactive and plain-text modes, saves attachments to `~/Downloads/telegram-cli`, and runs at most three downloads concurrently.
+- Downloads keep Telegram-provided filenames. Unnamed downloads use a MIME-derived extension, then the media-kind extension, then `.bin`.
+- Download failures are reported without stopping the listener. `--no-media` hides attachment summaries only; downloads still run when it is combined with `--auto-download`.
 
 ## Troubleshooting
 
@@ -239,6 +382,8 @@ accounts/<name>/messages.db
 
 Treat persisted configuration, `.env`, Telegram credentials, session files, and SQLite data as sensitive. Never share them or commit them to version control.
 
+The `config.json` file may contain an optional `proxy` setting in addition to API credentials. CLI success and error output does not print the stored proxy URL, but you must still protect `config.json`, the environment, and shell history because proxy URLs can contain credentials or MTProxy secrets.
+
 ## Development
 
 This project uses pnpm:
@@ -250,6 +395,20 @@ pnpm test
 pnpm typecheck
 ```
 
+During development, expose the current checkout as a global `tg` command that runs the TypeScript source directly. From the project root:
+
+```sh
+mkdir -p ~/.local/bin
+cat > ~/.local/bin/tg <<EOF
+#!/bin/sh
+exec "$(pwd)/node_modules/.bin/tsx" "$(pwd)/src/dev.ts" "\$@"
+EOF
+chmod +x ~/.local/bin/tg
+rehash
+```
+
+Make sure `~/.local/bin` is in `PATH`. Subsequent `tg` invocations load the latest source changes.
+
 For local source development, create a `.env` file in the project root:
 
 ```dotenv

package/README.zh-CN.md

@@ -2,18 +2,19 @@
 
 [English](README.md)
 
-一个 TypeScript 命令行客户端，用于同步 Telegram 聊天记录、监听实时消息、搜索本地存储的消息，并在终端中管理 Telegram 任务。
+一个 TypeScript 命令行客户端，用于同步 Telegram 聊天记录、监听实时消息、搜索本地存储的消息，并在终端中查看群组信息。
 
 ## 功能
 
 - 登录 Telegram，并查看当前账户或可用聊天列表。
-- 管理多个 Telegram 账号，每个账号使用独立的会话和消息数据库。
+- 管理多个 Telegram 账号，每个账号使用独立的会话和消息数据库，并支持交互式切换。
 - 将聊天记录提取到本地 SQLite 数据库，以便快速离线搜索。
 - 通过增量同步和批量同步命令更新本地数据。
 - 监听实时消息，并可选显示附件摘要。
 - 从限制下载的频道中下载附件。
-- 搜索、筛选、汇总和导出本地存储的消息。
+- 搜索、筛选、汇总和导出本地消息，并在最近消息中显示回复上下文和媒体组摘要。
 - 通过命令行发送、编辑和删除消息。
+- 查看并管理群组、成员、管理员、邀请链接、论坛话题和消息。
 - 在支持的场景下使用人类可读输出，或结构化的 JSON/YAML 输出。
 
 ## 为 AI Agent 设计
@@ -33,6 +34,17 @@ Telegram CLI 为 AI Agent 提供基于命令的 Telegram 和本地消息访问
 tg search "release" --account work --json
 ```
 
+### Agent Skill
+
+安装 [`using-telegram-cli`](https://skills.sh/will-17173/telegram-cli/using-telegram-cli) 技能，可以指导受支持的 AI 编程 Agent 完成账号认证、消息同步与查询、结构化输出自动化，并安全处理 Telegram 写操作：
+
+```sh
+npx skills add https://github.com/will-17173/telegram-cli \
+  --skill using-telegram-cli
+```
+
+如需让技能跨项目可用，请添加 `--global`，避免将其安装到当前项目中。
+
 ## 安装
 
 Telegram CLI 需要 Node.js 22 或更高版本。
@@ -54,13 +66,42 @@ tg config set --api-id <id> --api-hash <hash>
 如果 `TG_API_ID` 和 `TG_API_HASH` 均未设置，且已保存的配置文件不存在，CLI 会使用内置的 Telegram API 凭据。创建 Telegram 客户端时，每个进程只会向 stderr 输出一次以下警告：
 
 ```text
-warning: using default Telegram API credentials. Run tg config set --api-id <id> --api-hash <hash> to configure your own.
+warning: using default Telegram API credentials, which have stricter flood limits and may trigger FLOOD_WAIT during frequent or large requests. Run tg config set --api-id <id> --api-hash <hash> to configure your own.
 ```
 
-这表示 CLI 正在使用默认凭据；如需配置自己的凭据，请运行 `tg config set --api-id <id> --api-hash <hash>`。只设置 `TG_API_ID` 或 `TG_API_HASH` 其中之一会导致错误。已保存的配置文件格式错误或无法读取也会导致错误；这两种情况下 CLI 都不会改用内置凭据。
+这表示 CLI 正在使用限制更严格的默认凭据；频繁请求或大量同步可能触发 `FLOOD_WAIT`。如需配置自己的凭据，请运行 `tg config set --api-id <id> --api-hash <hash>`。只设置 `TG_API_ID` 或 `TG_API_HASH` 其中之一会导致错误。已保存的配置文件格式错误或无法读取也会导致错误；这两种情况下 CLI 都不会改用内置凭据。
 
 个人凭据会作为敏感配置存储在本地，切勿与他人分享。所有已添加账号共用一套 API 凭据，但每个账号都有独立的身份验证会话。
 
+如需为 Telegram 连接持久化配置代理，请运行：
+
+```sh
+tg config set --proxy socks5://127.0.0.1:1080
+```
+
+如需仅覆盖单次命令，可在该命令的环境中设置 `TG_PROXY`：
+
+```sh
+TG_PROXY=http://127.0.0.1:8080 tg status
+```
+
+支持的代理形式包括 `socks4://`、`socks5://`、`http://` 和 `https://` 代理 URL，以及 `tg://proxy?...` 和 `https://t.me/proxy?...` 形式的 MTProxy 链接。去除首尾空白后，非空的 `TG_PROXY` 值会覆盖持久化代理；如果 `TG_PROXY` 为空或未设置，CLI 会回退到已保存的代理；如果两者均未配置，则直接连接。
+
+所选代理会应用于账号登录和所有需要连接 Telegram 的命令，并非只应用于示例中的单个命令。代理 URL 可能包含用户名和密码或 MTProxy secret，因此应视为敏感信息。CLI 输出不会打印已配置的代理 URL。在命令行中直接输入包含凭据的代理 URL，可能会使其留在 shell 历史记录中，或通过进程检查被看到。请通过受到适当保护的环境或 secret 加载机制提供 `TG_PROXY`，或以其他方式避免将明文 secret 写入共享的 shell 历史记录和脚本。
+
+如需以人类可读、JSON 或 YAML 格式查看生效配置，请运行：
+
+```sh
+tg config list
+tg config list --json
+tg config list --yaml
+tg config list --show-secrets
+```
+
+该命令报告的是生效配置，而非 `config.json` 的原始内容。API 凭据会依次从环境变量、已保存配置和内置默认值中解析。代理则独立解析，依次使用 `TG_PROXY` 和已保存配置；两者均未配置时，代理保持缺省状态。
+
+输出恰好报告五个字段：生效的 API ID、API hash、凭据来源、代理 URL 以及代理来源。API hash 默认脱敏；使用 `--show-secrets` 可显示完整值。代理 URL 始终完整输出，并可能包含凭据或 MTProxy secret，因此请勿将 `config list` 输出写入日志或与他人分享。`tg config list` 不会创建 Telegram 客户端，也不会发起网络连接。
+
 运行 `tg account add` 完成身份验证并创建本地会话。其他命令不会启动交互式登录流程。
 
 你可以通过环境变量修改配置、账号会话和消息数据库的根目录：
@@ -90,13 +131,35 @@ tg search "keyword" --chat <chat>
 # 同步全部聊天
 tg sync-all --max-chats 20 --delay 1
 
-# 监听实时消息（可指定多个聊天）
-tg listen <chat-or-id> [another-chat ...] --no-media
+# 监听实时消息并自动下载收到的附件
+tg listen <chat-or-id> --auto-download
+
+# 使用纯文本输出、下载附件并隐藏消息中的附件摘要
+tg listen <chat-or-id> --no-interactive --auto-download --no-media
 
 # 发送消息
 tg send <chat> "Hello from tg"
 ```
 
+## 发送消息和附件
+
+`send` 必须指定 `<chat>`。可以发送纯文本、一个或多个文件，或带说明文字的文件：
+
+```sh
+# 仅发送文本
+tg send <chat> "Text only"
+
+# 仅发送文件；重复使用 --file，并按指定顺序发送
+tg send <chat> --file ./photo.jpg --file ./clip.mp4
+
+# 发送说明文字和文件
+tg send <chat> "Group caption" --file ./photo.jpg --file ./clip.mp4
+```
+
+`--file` 可重复使用。多个文件会按指定顺序作为一个 Telegram 媒体组发送。只有提供至少一个文件时，消息文本才可省略。提供文件后，消息文本会成为媒体组的说明文字；CLI 不会另发一条纯文本消息。
+
+Telegram 决定可接受的文件组合和媒体组数量限制。如果 Telegram 拒绝所请求的组合或数量，命令会返回错误，不会静默拆分为多条消息或多个媒体组。
+
 ## 多账号
 
 每个 Telegram 账号都有独立持久化的身份验证会话和本地消息数据库。通过以下命令交互式登录并添加账号：
@@ -114,13 +177,18 @@ tg account list
 # 查看 current 账号
 tg account current
 
-# 设置命令默认使用的账号
+# 从交互式列表中选择默认账号
+tg account switch
+
+# 按名称设置默认账号
 tg account switch <name>
 
 # 删除账号及其本地会话和数据
 tg account remove <name> --force
 ```
 
+在交互式终端中，`tg account switch` 会列出已添加账号、标记 current 账号，并接受账号序号。编写脚本或使用 `--json`、`--yaml`、非交互式输入时，请传入 `<name>`。
+
 各命令默认使用 current 账号。支持 `--account` 的命令可以临时指定另一个已添加的账号，且不会改变 current 账号：
 
 ```sh
@@ -133,12 +201,72 @@ tg search "keyword" --account <name>
 
 Telegram API 凭据对所有已添加账号生效，添加其他账号时无需单独配置 API 凭据。
 
+## 群组管理
+
+`group` 命令同时提供只读查询，以及成员、管理员、群设置、邀请链接、论坛话题和消息管理。请通过各 family 的帮助查看当前操作：
+
+```sh
+# 群组详情
+tg group info <chat> --account alice --json
+
+# 成员列表：按类型、姓名/用户名查询和结果数量筛选
+tg group members <chat> --type admins --query alice --limit 50 --yaml
+
+# 单个成员的角色、管理员权限和限制
+tg group member <chat> <user>
+
+# 管理员审计日志；--user 和 --type 均可重复指定
+tg group audit <chat> --query invite --user <user> --type member_invited --type invite_changed --limit 100 --account alice --json
+
+# 管理示例（chat 参数位于操作参数之前）
+tg group member ban @team @alice --yes
+tg group chat slowmode @team 30s
+tg group topic --help
+```
+
+`group members` 的 `--type` 恰好支持以下七种筛选器：`recent`、`all`、`admins`、`banned`、`restricted`、`bots` 和 `contacts`。默认使用 `recent` 并返回 100 条结果；`--limit` 可设为 1 到 200。Telegram 可能返回少于其报告总数的成员，因此单页结果不保证包含整个群组的全部成员。
+
+`group audit` 要求当前账号具有群组管理员权限。`--limit` 的范围是 1 到 500，默认返回 100 条事件。可重复的 `--user` 用于筛选操作发起者。可重复的 `--type` 恰好接受以下 17 种稳定的分组事件类型：`info_changed`、`settings_changed`、`member_joined`、`member_left`、`member_invited`、`member_banned`、`member_unbanned`、`member_restricted`、`member_unrestricted`、`admin_promoted`、`admin_demoted`、`message_deleted`、`message_edited`、`message_pinned`、`invite_changed`、`topic_changed` 和 `other`。
+
+查询和管理操作默认输出人类可读内容；暴露 `--json` 或 `--yaml` 的操作会输出结构化成功或错误结果。失败时进程退出状态非零。命令默认使用 current 账号；`--account <name>` 可仅为本次调用选择另一个已添加账号，且不会改变 current 账号。
+
+管理操作分为 `member`、`admin`、`chat`、`invite`、`topic` 和 `message` 六个 family。成员目标必须显式使用 `@username` 或 Telegram 数字用户 ID。时长支持 `s`、`m`、`h`、`d` 后缀；支持关闭的设置还可使用 `off`。例如 `tg group member mute @team @alice 2h --yes` 会临时禁言，`tg group chat slowmode @team off` 会关闭慢速模式。
+
+有破坏风险的 CLI 操作在缺少 `--yes` 时会直接拒绝，且不会连接 Telegram。永久删除群组还必须用 `--confirm-title` 提供完全一致的当前群名；交互式 listen 模式则通过 Ink 弹窗确认。管理操作需要对应的管理员权限，部分操作还要求超级群组、论坛或 creator 身份。转移所有权时，如果 Telegram 要求密码，本版本只返回 `password_required`，尚不接收密码。
+
+查询成员详情请优先使用规范路由 `tg group member info <chat> <user>`。旧形式 `tg group member <chat> <user>` 仍保留，但当群名等于 `ban`、`mute`、`info` 等保留操作名时会产生歧义，必须使用规范路由。
+
+## Listen 中的斜杠命令
+
+交互式 `tg listen` 会在同一个菜单中展示所有支持的斜杠命令，包括 `/reply` 和完整的群管理命令目录。群管理命令沿用原有语法，无需重复当前群组：
+
+```text
+/reply <消息ID> <内容>
+/member mute @alice 2h
+```
+
+输入 `/` 会打开统一命令菜单，并优先显示 reply。匹配顺序依次为完整匹配、前缀匹配和有序模糊匹配，因此 `/rep`、`/rpy` 都能找到 `/reply`，`/ban` 能找到 `/member ban`。使用 Up/Down 移动；Tab 补全选中的命令；对于尚未补全的命令，Enter 也会先补全，否则执行完整命令；Esc 关闭菜单、结果或确认框。
+
+群管理命令原有的可用性和权限检查保持不变：不可用操作仍会禁用，有风险的操作会打开确认弹窗，删除群组还会要求输入完全一致的群名。监听多个群组时，必须先用 `--send-to <chat>` 明确发送目标，例如 `tg listen @team @ops --send-to @team`，之后才能使用群管理命令。
+
 ## 在线命令与本地命令
 
-在线命令会连接 Telegram，因此需要有效的账号会话。这类命令包括 `status`、`whoami`、`chats`、`history`、`sync`、`sync-all`、`refresh`、`info`、`send`、`edit`、`delete` 和 `listen`。
+在线命令会连接 Telegram，因此需要有效的账号会话。这类命令包括 `status`、`whoami`、`chats`、`history`、`sync`、`sync-all`、`refresh`、`info`、全部 `group` 查询与管理 family、`send`、`edit`、`delete` 和 `listen`。
 
 本地命令只读取或修改所选账号的消息数据库，不会连接 Telegram。这类命令包括 `search`、`recent`、`stats`、`top`、`timeline`、`today`、`filter`、`export` 和 `purge`。
 
+## 查看最近消息
+
+`tg recent` 默认显示最近 24 小时内存储的 50 条消息。你可以按聊天或发送者筛选，也可以调整时间范围和数量：
+
+```sh
+tg recent --chat <chat> --sender <sender> --hours 6 --limit 100
+```
+
+人类可读输出会将每个 Telegram 媒体组合并为一行，并汇总其中的附件。`ID` 列列出该行包含的所有原始消息 ID。如果回复目标已存储在本地同一聊天中，输出会显示原消息的时间、发送者、ID 和文本。否则会标出本地缺失的消息 ID。
+
+JSON 和 YAML 输出保留已存储消息的结构，便于脚本处理。`recent` 只读取本地 SQLite 数据，不会连接 Telegram。
+
 ## 命令参考
 
 运行内置帮助以查看完整且最新的命令列表：
@@ -154,10 +282,12 @@ tg --help
 | `tg account add` | 登录并添加另一个 Telegram 账号。 |
 | `tg account list` | 列出已添加的账号及 current 状态。 |
 | `tg account current` | 查看 current 账号。 |
-| `tg account switch <name>` | 设置各命令默认使用的账号。 |
+| `tg account switch [name]` | 交互式选择默认账号，或按名称设置账号。 |
 | `tg account remove <name> --force` | 删除账号及其本地会话和数据。 |
 | `tg whoami` | 显示当前登录账号的基本信息。 |
 | `tg config set --api-id <id> --api-hash <hash>` | 持久化保存 Telegram API 凭据。 |
+| `tg config set --proxy <url>` | 为账号登录及所有需要连接 Telegram 的命令保存可选代理。 |
+| `tg config list [--show-secrets]` | 显示生效配置值及其来源；代理 URL 始终可见。 |
 | `tg status` | 检查 Telegram 账户是否已完成身份验证。 |
 | `tg chats` | 列出可用聊天。 |
 | `tg history <chat> -n <limit>` | 获取并保存完整聊天历史（默认最多 1000 条）。 |
@@ -166,15 +296,20 @@ tg --help
 | `tg refresh` | 与 `sync-all` 相同用途的批量同步命令。 |
 | `tg listen [chat ...]` | 实时监听指定聊天（或监听全部聊天）。 |
 | `tg listen --no-media` | 监听时隐藏附件摘要。 |
+| `tg listen <chat-or-id> --auto-download` | 监听时自动下载收到的附件。 |
 | `tg search "keyword" --chat <chat>` | 搜索已存储在本地的消息。 |
 | `tg recent`, `tg today`, `tg stats`, `tg top`, `tg timeline` | 浏览本地消息数据。 |
 | `tg filter <keywords>` | 按关键词筛选本地消息（支持按聊天和时间范围过滤）。 |
 | `tg export <chat>` | 导出本地存储的消息。 |
-| `tg send <chat> "Hello from tg"` | 发送消息。 |
+| `tg send <chat> [message] [--file <path> ...]` | 发送文本、文件或带说明文字的媒体组。 |
 | `tg edit <chat> <msgId> <text>` | 编辑消息。 |
 | `tg delete <chat> <msgIds...>` | 删除一条或多条消息。 |
 | `tg purge <chat> --yes` | 移除某个聊天在本地存储的消息。 |
 | `tg info <chat>` | 查看聊天元信息。 |
+| `tg group info <chat>` | 查看普通群组或超级群组的只读详情。 |
+| `tg group members <chat> [--type <type>] [--query <text>] [--limit <count>]` | 列出并筛选成员（默认 `recent`、100 条；最大 200 条）。 |
+| `tg group member <chat> <user>` | 查看单个成员的角色、权限和限制。 |
+| `tg group audit <chat> [--query <text>] [--user <user>] [--type <type>] [--limit <count>]` | 查询管理员审计日志（默认 100 条；最大 500 条）。 |
 
 所有同步类命令都会写入本地 SQLite 数据库。`sync-all` 和 `refresh` 根据本地已保存的消息 ID 增量处理多个聊天。
 
@@ -195,6 +330,13 @@ tg --help
 
 - `sync-all` 和 `refresh` 是写入本地数据库的批量同步流程，不是只读命令。
 - `listen` 会实时打印每条到达消息；可用 `--no-media` 关闭附件摘要显示。
+- Telegram 媒体组会显示为一条收到的消息，并合并附件摘要。
+- 回复输出会在本地原消息可用时显示其上下文，否则标出缺失的消息 ID。
+- 在交互式 `listen` 中，可用 `/reply <消息ID> <内容>` 回复消息；通过可重复的 `--file <路径>` 添加附件，包含空格的路径需要使用引号。
+- 联系人卡片会在附件摘要中显示可用的姓名和手机号。联系人卡片不属于可下载附件，使用 `--no-media` 时不会显示。
+- `listen --auto-download` 同时支持交互式和纯文本模式，附件保存在 `~/Downloads/telegram-cli`，最多同时下载 3 个附件。
+- 下载时保留 Telegram 提供的文件名。无文件名时，依次根据 MIME 类型、媒体类型推断扩展名，最后回退为 `.bin`。
+- 下载失败会被报告，但监听器会继续运行。`--no-media` 只隐藏附件摘要；与 `--auto-download` 组合时仍会下载附件。
 
 ## 故障排查
 
@@ -239,6 +381,8 @@ accounts/<name>/messages.db
 
 请将持久化配置、`.env`、Telegram 凭据、会话文件和 SQLite 数据视为敏感信息，切勿与他人分享或将它们提交到版本控制中。
 
+除 API 凭据外，`config.json` 文件还可能包含可选的 `proxy` 设置。CLI 的成功和错误输出不会打印已保存的代理 URL，但代理 URL 可能包含凭据或 MTProxy secret，因此仍须保护 `config.json`、环境和 shell 历史记录。
+
 ## 开发
 
 本项目使用 pnpm：
@@ -250,6 +394,20 @@ pnpm test
 pnpm typecheck
 ```
 
+开发时，可以将当前源码目录设置为全局 `tg` 命令，并直接运行 TypeScript 源码。在项目根目录执行：
+
+```sh
+mkdir -p ~/.local/bin
+cat > ~/.local/bin/tg <<EOF
+#!/bin/sh
+exec "$(pwd)/node_modules/.bin/tsx" "$(pwd)/src/dev.ts" "\$@"
+EOF
+chmod +x ~/.local/bin/tg
+rehash
+```
+
+请确保 `~/.local/bin` 已加入 `PATH`。之后执行 `tg` 时会加载最新的源码修改。
+
 在本地进行源码开发时，请在项目根目录创建 `.env` 文件：
 
 ```dotenv

package/dist/cli/app.js

@@ -2,6 +2,7 @@ import { Command } from 'commander';
 import { registerAccountCommands } from '../commands/account.js';
 import { registerConfigCommands } from '../commands/config.js';
 import { registerDataCommands } from '../commands/data.js';
+import { registerGroupCommands } from '../commands/group.js';
 import { registerQueryCommands } from '../commands/query.js';
 import { registerTelegramCommands } from '../commands/telegram.js';
 export function createApp() {
@@ -10,10 +11,11 @@ export function createApp() {
         .description('Telegram CLI for syncing chats, searching messages, and local analysis.')
         .option('-v, --verbose', 'Enable debug logging')
         .option('--account <account>', 'Select an account for account-dependent commands')
-        .version('0.1.0');
+        .version('0.3.0');
     registerQueryCommands(app);
     registerDataCommands(app);
     registerTelegramCommands(app);
+    registerGroupCommands(app);
     registerAccountCommands(app);
     registerConfigCommands(app);
     return app;

package/dist/cli/app.js.map

@@ -1 +1 @@
-{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/cli/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAElE,MAAM,UAAU,SAAS;IACvB,MAAM,GAAG,GAAG,IAAI,OAAO,EAAE;SACtB,IAAI,CAAC,IAAI,CAAC;SACV,WAAW,CAAC,yEAAyE,CAAC;SACtF,MAAM,CAAC,eAAe,EAAE,sBAAsB,CAAC;SAC/C,MAAM,CAAC,qBAAqB,EAAE,kDAAkD,CAAC;SACjF,OAAO,CAAC,OAAO,CAAC,CAAA;IAEnB,qBAAqB,CAAC,GAAG,CAAC,CAAA;IAC1B,oBAAoB,CAAC,GAAG,CAAC,CAAA;IACzB,wBAAwB,CAAC,GAAG,CAAC,CAAA;IAC7B,uBAAuB,CAAC,GAAG,CAAC,CAAA;IAC5B,sBAAsB,CAAC,GAAG,CAAC,CAAA;IAE3B,OAAO,GAAG,CAAA;AACZ,CAAC"}
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/cli/app.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAA;AAC9D,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAA;AAElE,MAAM,UAAU,SAAS;IACvB,MAAM,GAAG,GAAG,IAAI,OAAO,EAAE;SACtB,IAAI,CAAC,IAAI,CAAC;SACV,WAAW,CAAC,yEAAyE,CAAC;SACtF,MAAM,CAAC,eAAe,EAAE,sBAAsB,CAAC;SAC/C,MAAM,CAAC,qBAAqB,EAAE,kDAAkD,CAAC;SACjF,OAAO,CAAC,OAAO,CAAC,CAAA;IAEnB,qBAAqB,CAAC,GAAG,CAAC,CAAA;IAC1B,oBAAoB,CAAC,GAAG,CAAC,CAAA;IACzB,wBAAwB,CAAC,GAAG,CAAC,CAAA;IAC7B,qBAAqB,CAAC,GAAG,CAAC,CAAA;IAC1B,uBAAuB,CAAC,GAAG,CAAC,CAAA;IAC5B,sBAAsB,CAAC,GAAG,CAAC,CAAA;IAE3B,OAAO,GAAG,CAAA;AACZ,CAAC"}