@will-17173/telegram-cli 0.4.0 → 0.5.0

package/README.zh-CN.md

@@ -1,544 +1,183 @@
 # Telegram CLI
 
-[English](README.md)
+[项目网站](https://will-17173.github.io/telegram-cli/zh-CN/) · [Telegram CLI 使用文档](https://will-17173.github.io/telegram-cli/zh-CN/docs/) · [English README](README.md)
 
-一个 TypeScript 命令行客户端，用于同步 Telegram 聊天记录、监听实时消息、搜索本地存储的消息，并在终端中查看群组信息。
+Telegram CLI 是一个 TypeScript 命令行界面（CLI），统一处理 Telegram 在线数据、本地 SQLite 搜索和远端管理。它的目标是成为面向人和 AI agent 的最强 Telegram CLI，让你通过同一个 `tg` 命令稳定访问 Telegram。账号会话与同步消息保留在本机。
 
-## 你可以做什么
+## Telegram CLI 的亮点
 
-- 管理多个 Telegram 账号，并隔离各账号的会话和消息数据库。
-- 查看未读聊天，并直接读取或搜索消息，且不保存到本地。
-- 将聊天记录同步到 SQLite，用于离线搜索、筛选、分析和导出。
-- 将指定聊天增量归档为 Markdown 文件，并可选择下载附件。
-- 监听实时消息并下载收到的附件。
-- 通过命令行发送、编辑和删除消息。
-- 查看联系人、通知设置、聊天文件夹、群组、成员、管理员、邀请链接和论坛话题。
-- 禁用 Telegram 远端写操作，同时保留只读命令和本地命令。
-- 在脚本和智能体工作流中使用人类可读、JSON、YAML 或 Markdown 输出。
+Telegram CLI 将在线读取、本地持久化、文件归档、实时监听、远端写入、群组管理、账号隔离、本地 Web 界面和结构化输出放进同一个工具。
 
-## 为 AI 智能体设计
+它专为 AI agent 设计：
 
-Telegram CLI 为 AI 智能体提供基于命令的 Telegram 和本地消息访问接口。通过 `tg account add` 完成账号认证后，智能体无需操作浏览器即可执行在线命令和本地命令。
+- **稳定的命令契约**：有限结果命令支持 JSON、YAML、Markdown、退出状态和稳定错误码
+- **本地优先的数据访问**：同步消息保存在 SQLite，agent 可以搜索和分析 Telegram 历史，而无需反复联网读取
+- **明确的账号控制**：`--account` 可以为单次命令选择预期会话
+- **写操作安全边界**：写操作总开关将只读自动化与修改 Telegram 的命令分开
+- **Agent skill 支持**：`using-telegram-cli` skill 会指导受支持的 agent 完成认证、同步、查询，并避开不安全写操作
 
-以下接口适合智能体工作流：
+## 阅读完整文档
 
-- JSON 和 YAML 输出让智能体直接读取结构化数据，而不是解析终端表格。
-- 非零退出码和结构化错误码让智能体能够检测并处理失败。
-- `--account <name>` 可以明确指定账号，且不会改变当前账号。
-- 本地搜索和分析命令无需重新连接 Telegram，即可查询已同步消息。
+阅读 [Telegram CLI 完整使用文档](https://will-17173.github.io/telegram-cli/zh-CN/docs/)，了解安装、工作流、全部命令、自动化、安全边界和故障排查。
 
-例如，智能体可以搜索指定账号，并将结果作为 JSON 解析：
+## 选择 Telegram 工作流
 
-```sh
-tg search "release" --account work --json
-```
+请根据数据新鲜度、结果去向以及命令是否修改 Telegram 来选择工作流。
 
-### Agent skill
+### 读取 Telegram 当前数据
 
-安装 [`using-telegram-cli`](https://skills.sh/will-17173/telegram-cli/using-telegram-cli) 技能，可以指导受支持的 AI 编程智能体完成账号认证、消息同步与查询、结构化输出自动化，并安全处理 Telegram 写操作：
+需要最新的服务端状态时，请使用在线命令。这些命令不会把返回消息写入 SQLite。
 
 ```sh
-npx skills add https://github.com/will-17173/telegram-cli \
-  --skill using-telegram-cli
+tg inbox
+tg read @team --since 2h
+tg search-online "incident" --chat @team --json
 ```
 
-如需让技能跨项目可用，请添加 `--global`，避免将其安装到当前项目中。
-
-## 安装
-
-Telegram CLI 需要 Node.js 22 或更高版本。
-
-通过 npm 全局安装：
+你还可以在线查看联系人、通知设置、文件夹和群组详情，且不会导入消息。
 
-```sh
-npm install -g @will-17173/telegram-cli
-```
-
-## 快速开始
-
-登录账号、检查状态并列出聊天：
-
-```sh
-tg account add
-tg status
-tg chats
-```
+### 建立可搜索的本地消息库
 
-从 `tg chats` 的结果中选择聊天名称、用户名或 ID，然后同步并搜索消息：
+将一个或多个聊天同步到所选账号的 SQLite 数据库。之后无需连接 Telegram，即可搜索和分析本地副本。
 
 ```sh
-tg sync <chat>
-tg search "keyword" --chat <chat>
+tg sync @team
+tg search "release" --chat @team
+tg recent --chat @team --hours 24
 ```
 
-你还可以批量同步聊天、监听实时消息或发送消息：
+本地命令还可以筛选、汇总和导出已存储消息。
 
-```sh
-tg sync-all --max-chats 20 --delay 1
-tg listen <chat-or-id> --auto-download
-tg send <chat> "Hello from tg"
-```
+### 在 Web 界面浏览本地数据
 
-## 在线读取与管理 Telegram
-
-`history`、`sync` 和 `sync-all` 会从 Telegram 获取消息，并保存到本地 SQLite 数据库。`read`、`search-online` 和 `inbox` 直接查询 Telegram，不会保存查询结果。`inbox` 列出有未读消息的聊天，但不会把消息标记为已读。
+启动仅限本机访问的管理界面来浏览已存储消息：
 
 ```sh
-tg inbox --markdown
-tg read @team --since 7d --until 2d
-tg search-online release --chat @team --json
+tg web
 ```
 
-时间边界支持以 `s`、`m`、`h`、`d` 或 `w` 结尾的相对时长。例如，`7d` 表示命令启动前七天。绝对时间使用包含时区的 ISO 8601 时间戳，例如 `2026-07-13T00:00:00Z`。`--since` 必须早于 `--until`。
-
-以下命令可以查看联系人、通知设置、文件夹和群组对话框，且不会修改远端状态：
+服务器只绑定 `127.0.0.1`，没有登录页面，仅供本机使用。它可以浏览本地 SQLite 数据，并为当前选中的聊天触发只读同步。
 
-```sh
-tg contact list
-tg contact info +8613800000000
-tg notification info @team
-tg folder list
-tg folder info 2
-tg group list --admin
-```
+### 监听新消息并下载文件
 
-以下命令会修改 Telegram 远端状态：
+`listen` 可以实时接收一个或多个聊天的新消息。它还可以下载收到的附件，并在交互模式中执行回复或群组操作。
 
 ```sh
-tg notification mute @team 8h
-tg notification unmute @team
-tg folder chat add Work @team
-tg folder chat remove Work @team
+tg listen @team --auto-download
 ```
 
-使用 `tg config write-access off` 可阻止这些修改。通过 `tg config write-access on` 恢复远端写操作。
+### 保存增量 Markdown 归档
 
-文件夹命令接受标题或数字文件夹 ID。文件夹标题不一定唯一。请先运行 `tg folder list`，再将返回的 ID 用于 `tg folder info`、`tg folder chat add` 或 `tg folder chat remove`。
-
-## 配置
-
-配置个人 Telegram API 凭据是可选的。如需使用自己的凭据，请先在 [my.telegram.org](https://my.telegram.org) 创建，然后通过以下命令保存：
+`archive` 将消息增量写入 Markdown，并可同时下载媒体文件。它单独记录归档进度，不会填充 SQLite。
 
 ```sh
-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, 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 正在使用限制更严格的默认凭据；频繁请求或大量同步可能触发 `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 archive @team --download-media
 ```
 
-如需仅覆盖单次命令，可在该命令的环境中设置 `TG_PROXY`：
+后续运行会追加新消息，并重试仍然缺失的引用媒体。
 
-```sh
-TG_PROXY=http://127.0.0.1:8080 tg status
-```
-
-Telegram CLI 支持 SOCKS4、SOCKS5、HTTP、HTTPS 和 MTProxy。代理会应用于账号登录和所有需要连接 Telegram 的命令。包含凭据的代理 URL 应视为敏感信息。
+### 发送消息并管理群组
 
-如需以人类可读、JSON 或 YAML 格式查看生效配置，请运行：
+你可以从终端发送文本、文件或带说明文字的媒体组，也可以查看和管理群成员、管理员、邀请链接、论坛话题和消息。
 
 ```sh
-tg config list
-tg config list --json
-tg config list --yaml
-tg config list --show-secrets
+tg send @team "Release is ready" --file ./report.pdf
+tg group members @team --type admins
+tg group member mute @team @alice 2h --yes
 ```
 
-该命令报告的是生效配置，而非 `config.json` 的原始内容。API hash 默认脱敏；`--show-secrets` 只会显示完整的 API hash。
+Telegram CLI 还可以管理联系人、通知设置和聊天文件夹。写操作总开关会控制修改 Telegram 的命令。
 
-安全的代理端点详情仍然可见，但代理用户名、密码和凭据查询参数始终会被脱敏，即使使用 `--show-secrets`。
+### 跨隔离账号运行自动化
 
-运行 `tg account add` 完成身份验证并创建本地会话。其他命令不会启动交互式登录流程。
-
-你可以通过环境变量修改配置、账号会话和消息数据库的根目录：
+每个已添加账号都有独立的会话和 SQLite 数据库。你可以为单次命令选择账号，且不会改变默认账号。
 
 ```sh
-export DATA_DIR=/path/to/tg-cli-data
+tg stats --account work --json
 ```
 
-## 发送消息和附件
-
-`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 拒绝所请求的组合或数量，命令会返回错误，不会静默拆分为多条消息或多个媒体组。
-
-## 将聊天归档为 Markdown
+有限结果命令支持 JSON、YAML 和 Markdown 输出。失败时会返回非零退出状态和稳定错误码。
 
-`archive` 必须指定明确范围。请传入一个或多个聊天 ID 或用户名，或者使用 `--all`，但不能同时使用这两种方式。
+## 安装
 
-命令默认使用当前账号，也可通过 `--account <name>` 临时选择账号。归档默认写入该账号数据目录下的 `archive`。使用 `--output <路径>` 可以指定其他目录。
+安装 Node.js 22.12.0 或更高版本，再从 npm 安装 Telegram CLI：
 
 ```sh
-# 首次归档并下载附件：此前七天
-tg archive @team --download-media
-
-# 自定义范围（相对时长或带时区的 ISO 时间）
-tg archive @team --since 30d --until 2026-07-13T00:00:00Z
-
-# 归档所有聊天的完整可用历史并下载附件
-tg archive --all --full --download-media
+npm install -g @will-17173/telegram-cli
 ```
 
-首次运行默认归档此前七天。使用 `--since` 和 `--until` 可以选择其他范围。`--full` 会取消起始时间限制，且不能与 `--since` 同时使用。
-
-后续运行会将新消息追加到现有归档。使用 `--rebuild` 可以替换所选的 Markdown 文件。未指定新范围时，重建会复用归档的初始范围。
-
-使用 `--download-media` 可以将附件保存到归档目录的 `media/` 下。增量运行会重试仍然缺失的引用附件。
-
-任一聊天或附件失败时，命令返回 `archive_partial_failure`，保留其他聊天的成功结果，并以状态码 1 退出。自动化场景建议使用 `--json` 或 `--yaml`，检查 `completed`、`failed` 和 `warnings`。
+## 开始使用
 
-大量历史和媒体请求可能触发 Telegram flood wait 或其他速率限制。媒体下载可以独立失败。已成功归档的消息仍保留在磁盘上，警告会指出失败的附件。
-
-## 多账号
-
-每个 Telegram 账号都有独立持久化的身份验证会话和本地消息数据库。通过以下命令交互式登录并添加账号：
+认证一个账号，列出聊天，同步一个聊天，再搜索本地消息：
 
 ```sh
 tg account add
+tg status
+tg chats
+tg sync @team
+tg search "release" --chat @team
 ```
 
-添加的第一个账号会自动成为当前账号。继续添加其他账号时不会自动切换，可通过以下命令查看或更改选择：
-
-```sh
-# 列出已添加的账号
-tg account list
-
-# 查看当前账号
-tg account current
-
-# 从交互式列表中选择默认账号
-tg account switch
-
-# 按名称设置默认账号
-tg account switch <name>
-
-# 删除账号及其本地会话和数据
-tg account remove <name> --force
-```
-
-显式登出可以结束远端会话，同时保留已添加账号、账号设置和本地消息。`--yes` 可以跳过确认提示。
-
-再次登录需要交互式终端（TTY），并会创建或替换本地 Telegram 会话。脚本和非交互智能体会收到 `interaction_required` 错误。
-
-```sh
-tg account logout work --yes
-tg account login work
-```
-
-在交互式终端中，`tg account switch` 会列出已添加账号、标记当前账号，并接受账号序号。编写脚本或使用 `--json`、`--yaml`、非交互式输入时，请传入 `<name>`。
-
-各命令默认使用当前账号。支持 `--account` 的命令可以临时指定另一个已添加的账号，且不会改变当前账号：
-
-```sh
-tg chats --account <name>
-tg sync-all --account <name>
-tg search "keyword" --account <name>
-```
-
-账号名称可通过 `tg account list` 查看，通常由 Telegram 用户名生成。各账号的会话和消息数据库分别保存在 `DATA_DIR` 下对应的账号目录中。
-
-Telegram API 凭据对所有已添加账号生效，添加其他账号时无需单独配置 API 凭据。
-
-## 群组管理
-
-`group` 命令同时支持只读查询，以及成员、管理员、群设置、邀请链接、论坛话题和消息管理。请通过各命令组的帮助查看可用操作：
-
-```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 admin transfer-owner @team @newowner --yes
-tg group chat slowmode @team 30s
-tg group topic --help
-```
-
-确认转移所有权后，命令会安全提示输入 Telegram 双重身份验证（2FA）密码。密码绝不会来自 CLI 参数、stdin 输入或环境变量等自动化来源。安全提示仅接受交互式终端输入，不接受管道输入。请勿自动操作该提示。
-
-`group members` 的 `--type` 恰好支持以下七种筛选器：`recent`、`all`、`admins`、`banned`、`restricted`、`bots` 和 `contacts`。默认使用 `recent` 并返回 100 条结果；`--limit` 可设为 1 到 200。Telegram 可能返回少于其报告总数的成员，因此单页结果不保证包含整个群组的全部成员。
-
-`group audit` 要求当前账号具有群组管理员权限。`--limit` 的范围是 1 到 500，默认返回 100 条事件。可重复的 `--user` 用于筛选操作发起者。可重复的 `--type` 支持以下事件组：
-
-- **群组**：`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` 的操作会输出结构化成功或错误结果。失败时进程退出状态非零。命令默认使用当前账号；`--account <name>` 可仅为本次调用选择另一个已添加账号，且不会改变当前账号。
-
-管理操作分为 `member`、`admin`、`chat`、`invite`、`topic` 和 `message` 六个命令组。成员目标必须显式使用 `@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 弹窗确认。管理操作需要对应的管理员权限，部分操作还要求超级群组、论坛或群主身份。
-
-查询成员详情请优先使用规范路由 `tg group member info <chat> <user>`。旧形式 `tg group member <chat> <user>` 仍保留，但当群名等于 `ban`、`mute`、`info` 等保留操作名时会产生歧义，必须使用规范路由。
-
-## 监听模式中的斜杠命令
-
-交互式 `tg listen` 会在同一个菜单中展示所有支持的斜杠命令，包括 `/reply` 和完整的群管理命令目录。群管理命令沿用原有语法，无需重复当前群组：
-
-```text
-/reply <消息ID> <内容>
-/member mute @alice 2h
-```
-
-输入 `/` 会打开统一命令菜单，并优先显示 `/reply`。匹配顺序依次为完整匹配、前缀匹配和有序模糊匹配，因此 `/rep`、`/rpy` 都能找到 `/reply`，`/ban` 能找到 `/member ban`。使用**上方向键**和**下方向键**移动。**Tab** 补全选中的命令。**Enter** 补全未完成的命令或执行完整命令。**Esc** 关闭菜单、结果或确认框。
-
-群管理命令原有的可用性和权限检查保持不变：不可用操作仍会禁用，有风险的操作会打开确认弹窗，删除群组还会要求输入完全一致的群名。监听多个群组时，必须先用 `--send-to <chat>` 明确发送目标，例如 `tg listen @team @ops --send-to @team`，之后才能使用群管理命令。
-
-## 在线命令与本地命令
+请将 `@team` 替换为聊天名称、用户名或数字标识符（ID）。运行 `tg --help` 或 `tg sync --help` 等具体命令查看可用选项。
 
-在线命令会连接 Telegram，因此需要有效的账号会话：
+## 了解数据去向
 
-- `read`、`search-online` 和 `inbox` 返回结果，但不保存到本地。
-- `history`、`sync`、`sync-all` 和 `refresh` 将获取的消息保存到 SQLite。
-- `contact`、`notification`、`folder`、`info` 和 `group` 用于查看或管理 Telegram 数据。
-- `archive` 读取 Telegram 历史，并将 Markdown 文件写入本地。
-- `send`、`edit` 和 `delete` 修改 Telegram 消息。
-- `listen` 保持连接，以接收消息和执行交互操作。
+运行命令前，先检查它的执行范围：
 
-全局在线搜索和大规模归档可能触发 Telegram flood wait 或其他速率限制。
+| 范围 | 命令 | 结果 |
+| --- | --- | --- |
+| 在线读取 | `inbox`、`read`、`search-online` | 查询 Telegram，不保存返回的消息。 |
+| 写入本地 | `history`、`sync`、`sync-all`、`refresh` | 将消息保存到所选账号的 SQLite 数据库。 |
+| 仅本地 | `search`、`recent`、`stats`、`export`、`web` | 读取本地 SQLite，不连接 Telegram。 |
+| 文件归档 | `archive` | 读取 Telegram 并写入 Markdown 或媒体文件，不写入 SQLite。 |
+| 远端写入 | `send`、`edit`、`delete`，以及通知、文件夹和群组操作 | 修改 Telegram 消息或设置。 |
 
-本地命令只读取或修改所选账号的消息数据库，不会连接 Telegram。这类命令包括 `search`、`recent`、`stats`、`top`、`timeline`、`today`、`filter`、`export` 和 `purge`。
+每个账号都有独立的会话和 SQLite 数据库。添加 `--account work` 可以为单次命令选择账号，且不会改变默认账号。
 
-## 查看最近消息
+## 保护远端数据
 
-`tg recent` 默认显示最近 24 小时内存储的 50 条消息。你可以按聊天或发送者筛选，也可以调整时间范围和数量：
+在只读工作流或自动化任务前关闭远端写入：
 
 ```sh
-tg recent --chat <chat> --sender <sender> --hours 6 --limit 100
+tg config write-access off
+tg config write-access status
 ```
 
-人类可读输出会将每个 Telegram 媒体组合并为一行，并汇总其中的附件。`ID` 列列出该行包含的所有原始消息 ID。如果回复目标已存储在本地同一聊天中，输出会显示原消息的时间、发送者、ID 和文本。否则会标出本地缺失的消息 ID。
+准备再次修改 Telegram 时，运行 `tg config write-access on`。打开总开关不代表已授权某一项具体写操作。
 
-JSON 和 YAML 输出保留已存储消息的结构，便于脚本处理。`recent` 只读取本地 SQLite 数据，不会连接 Telegram。
+请妥善保管 Telegram 应用程序接口（API）凭据、代理凭据、会话文件、SQLite 数据库、导出文件和归档。
 
-## 命令参考
-
-运行内置帮助以查看完整且最新的命令列表：
-
-```sh
-tg --help
-```
+## 配合编程智能体
 
-常用命令：
-
-| 命令 | 用途 |
-| --- | --- |
-| `tg account add` | 登录并添加另一个 Telegram 账号。 |
-| `tg account list` | 列出已添加的账号及当前状态。 |
-| `tg account current` | 查看当前账号。 |
-| `tg account switch [name]` | 交互式选择默认账号，或按名称设置账号。 |
-| `tg account remove <name> --force` | 删除账号及其本地会话和数据。 |
-| `tg account logout <name> --yes` / `tg account login <name>` | 非交互确认登出，或交互式重新认证并创建新的本地会话；本地消息会保留。 |
-| `tg whoami` | 显示当前登录账号的基本信息。 |
-| `tg config set --api-id <id> --api-hash <hash>` | 持久化保存 Telegram API 凭据。 |
-| `tg config set --proxy <url>` | 为账号登录及所有需要连接 Telegram 的命令保存可选代理。 |
-| `tg config list [--show-secrets]` | 显示生效配置值及其来源。代理凭据始终保持脱敏。 |
-| `tg config write-access [status\|on\|off]` | 查看或控制远端 Telegram 写操作权限。 |
-| `tg status` | 检查 Telegram 账户是否已完成身份验证。 |
-| `tg chats` | 列出可用聊天。 |
-| `tg inbox` | 在线列出未读聊天，且不把消息标记为已读。 |
-| `tg read <chat> [--since <time>] [--until <time>]` | 读取 Telegram 最近消息，不持久化到本地。 |
-| `tg search-online <query> [--chat <chat>]` | 在 Telegram 全局或单个聊天内搜索，不持久化结果。 |
-| `tg contact list` / `tg contact info <user_or_phone>` | 列出联系人，或按 ID、用户名、手机号查询联系人。 |
-| `tg dialog inbox` / `tg dialog read <chat>` | 通过 `dialog` 命令组使用 `inbox` 和 `read`。 |
-| `tg dialog search <query>` / `tg dialog groups` | 通过 `dialog` 命令组在线搜索消息或列出群组对话框。 |
-| `tg notification info <chat>` | 查看聊天的通知设置。 |
-| `tg notification mute <chat> [duration]` | 临时或永久关闭聊天通知。 |
-| `tg notification unmute <chat>` | 恢复聊天通知。 |
-| `tg folder list` / `tg folder info <folder>` | 列出文件夹或查看指定文件夹。 |
-| `tg folder chat add <folder> <chat>` | 将显式聊天添加到文件夹。 |
-| `tg folder chat remove <folder> <chat>` | 从文件夹移除显式聊天。 |
-| `tg history <chat> -n <limit>` | 获取并保存完整聊天历史（默认最多 1000 条）。 |
-| `tg sync <chat>` | 将聊天消息同步到本地存储。 |
-| `tg sync-all` | 从全部聊天同步消息，按本地已同步进度做增量更新。 |
-| `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 archive <chat ...>` / `tg archive --all` | 将指定聊天或全部聊天增量归档为 Markdown 文件。 |
-| `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 list [--admin]` | 列出普通群组、超级群组和频道对话框；`--admin` 仅保留自己管理或拥有的聊天。 |
-| `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 条）。 |
-| `tg group member/admin/chat/invite/topic/message --help` | 按类别查找群组管理操作。 |
-
-所有同步类命令都会写入本地 SQLite 数据库。`sync-all` 和 `refresh` 根据本地已保存的消息 ID 增量处理多个聊天。
-
-有限结果命令支持 `--json`、`--yaml` 和 `--markdown` 输出。未指定格式时，非交互输出仍默认使用 YAML。交互式终端使用富文本人类可读输出。
-
-有限结果命令成功时写入 stdout。JSON/YAML 结构化失败按请求的格式写入 stdout。输出格式冲突同样写入 stdout，并使用稳定的 YAML 信封。人类可读和 Markdown 失败信息写入 stderr。所有失败都会设置非零退出状态。
-
-`listen` 是无界数据流，因此不适用这些有限结果输出规则。
-
-常用选项：
-
-| 选项 | 用途 |
-| --- | --- |
-| `--account <name>` | 临时使用已添加的账号，不改变当前账号。 |
-| `--json` / `--yaml` / `--markdown` | 为有限结果命令选择 JSON、YAML 或 Markdown 输出。 |
-| `-v`, `--verbose` | 启用调试日志。 |
-| `-V`, `--version` | 输出当前安装版本。 |
-
-使用 `tg <command> --help` 查看命令专用选项。例如，`listen` 支持自动重连和纯文本模式，`search` 支持发送者、时间、正则表达式和结果数量筛选。
-
-### 错误码
-
-结构化输出会在 `error.code` 中提供稳定的顶层命令错误码，并在可用时附带操作相关详情：
-
-- **账号：** `account_logged_out`、`account_identity_mismatch`、`interaction_required`
-- **联系人：** `contact_not_found`
-- **通知和文件夹：** `invalid_notification_duration`、`folder_not_found`、`ambiguous_folder`、`folder_operation_unsupported`
-- **群组所有权：** `password_required`、`password_invalid`、`password_too_fresh`、`session_too_fresh`
-- **归档：** `archive_account_mismatch`、`archive_failed`、`archive_partial_failure`。附件失败但归档保留部分结果时，顶层错误码为 `archive_partial_failure`，命令以非零状态退出；每条媒体警告的 `archive_media_failed` 位于 `error.details.warnings[].code`。
-- **写操作安全和速率限制：** `write_access_disabled`、`flood_wait`
-
-### 远端写操作安全
-
-运行 `tg config write-access status` 可以查看当前设置。使用 `tg config write-access off` 可阻止发送、编辑、删除、通知、文件夹和群组命令修改 Telegram。本地数据库操作、配置修改和 Telegram 读取操作仍可使用。
-
-测试或维护结束后，运行 `tg config write-access on` 恢复远端写操作。
-
-### 同步与监听行为
-
-以下规则说明同步、监听、回复和下载功能如何影响本地数据与终端输出。
-
-- `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` 组合时仍会下载附件。
-
-## 故障排查
-
-按照以下步骤解决常见的账号、会话和 API 凭据问题。
-
-### 没有可用的当前账号
-
-如果命令返回 `account_required`，请添加账号或选择已有账号：
+脚本或编程智能体需要结构化输出时，请使用 JSON 或 YAML：
 
 ```sh
-tg account add
-tg account switch <name>
-```
-
-### 账号会话已经失效
-
-如果 Telegram 返回 `AUTH_KEY_UNREGISTERED`，请删除失效的本地会话并重新登录：
-
-```sh
-tg account remove <name> --force
-tg account add
+tg search "release" --account work --json
 ```
 
-### 默认 API 凭据警告
+命令失败时会返回非零退出状态和稳定错误码。显式传入 `--account` 可以让自动化任务使用预期账号。
 
-内置 API 凭据仍可使用，但 CLI 创建 Telegram 客户端时会输出警告。配置个人凭据即可移除该警告：
+在受支持的编程智能体中安装 [`using-telegram-cli` agent skill](https://skills.sh/will-17173/telegram-cli/using-telegram-cli)：
 
 ```sh
-tg config set --api-id <id> --api-hash <hash>
-```
-
-通过环境变量配置时，必须同时设置 `TG_API_ID` 和 `TG_API_HASH`。只设置其中一个会导致配置错误。
-
-## 本地数据与隐私
-
-除非你明确复制或导出，否则持久化配置、身份验证会话和已同步消息都会保留在本机。`DATA_DIR` 下的相关文件如下：
-
-```text
-config.json
-accounts.json
-accounts/<name>/session
-accounts/<name>/messages.db
+npx skills add https://github.com/will-17173/telegram-cli \
+  --skill using-telegram-cli
 ```
 
-请将持久化配置、`.env`、Telegram 凭据、会话文件和 SQLite 数据视为敏感信息，切勿与他人分享或将它们提交到版本控制中。
+该技能涵盖认证、同步、查询和写操作安全流程。
 
 ## 开发
 
-本项目使用 pnpm：
+请使用 pnpm 和 Node.js 22.12.0 或更高版本：
 
 ```sh
 pnpm install
 pnpm dev --help
 pnpm test
 pnpm typecheck
+pnpm build
 ```
 
-开发时，可以将当前源码目录设置为全局 `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
-TG_API_ID=your_telegram_api_id
-TG_API_HASH=your_telegram_api_hash
-```
-
-`pnpm dev` 仅在本地源码开发时加载此文件。安装后的 `tg` 不会自动加载 `.env`；如需持久化生产配置，请使用 `tg config set --api-id <id> --api-hash <hash>`。
-
 ## 许可证
 
-采用 [GPL-3.0](LICENSE) 许可证。
+本项目采用 [GPL-3.0-only](LICENSE) 许可证。

package/dist/cli/app.js

@@ -10,6 +10,7 @@ import { registerFolderCommands } from '../commands/folder.js';
 import { registerNotificationCommands } from '../commands/notification.js';
 import { registerQueryCommands } from '../commands/query.js';
 import { registerTelegramCommands } from '../commands/telegram.js';
+import { registerWebCommand } from '../commands/web.js';
 export function createApp() {
     const app = new Command()
         .name('tg')
@@ -17,7 +18,7 @@ export function createApp() {
         .option('-v, --verbose', 'Enable debug logging')
         .option('--account <account>', 'Select an account for account-dependent commands')
         .option('--markdown', 'Produce Markdown output for human-readable results')
-        .version('0.4.0');
+        .version('0.5.0');
     registerQueryCommands(app);
     registerArchiveCommand(app);
     registerDataCommands(app);
@@ -29,6 +30,7 @@ export function createApp() {
     registerNotificationCommands(app);
     registerAccountCommands(app);
     registerConfigCommands(app);
+    registerWebCommand(app);
     return app;
 }
 //# sourceMappingURL=app.js.map