@will-17173/telegram-cli 0.3.0 → 0.4.0

package/README.zh-CN.md

@@ -4,39 +4,38 @@
 
 一个 TypeScript 命令行客户端，用于同步 Telegram 聊天记录、监听实时消息、搜索本地存储的消息，并在终端中查看群组信息。
 
-## 功能
-
-- 登录 Telegram，并查看当前账户或可用聊天列表。
-- 管理多个 Telegram 账号，每个账号使用独立的会话和消息数据库，并支持交互式切换。
-- 将聊天记录提取到本地 SQLite 数据库，以便快速离线搜索。
-- 通过增量同步和批量同步命令更新本地数据。
-- 监听实时消息，并可选显示附件摘要。
-- 从限制下载的频道中下载附件。
-- 搜索、筛选、汇总和导出本地消息，并在最近消息中显示回复上下文和媒体组摘要。
+## 你可以做什么
+
+- 管理多个 Telegram 账号，并隔离各账号的会话和消息数据库。
+- 查看未读聊天，并直接读取或搜索消息，且不保存到本地。
+- 将聊天记录同步到 SQLite，用于离线搜索、筛选、分析和导出。
+- 将指定聊天增量归档为 Markdown 文件，并可选择下载附件。
+- 监听实时消息并下载收到的附件。
 - 通过命令行发送、编辑和删除消息。
-- 查看并管理群组、成员、管理员、邀请链接、论坛话题和消息。
-- 在支持的场景下使用人类可读输出，或结构化的 JSON/YAML 输出。
+- 查看联系人、通知设置、聊天文件夹、群组、成员、管理员、邀请链接和论坛话题。
+- 禁用 Telegram 远端写操作，同时保留只读命令和本地命令。
+- 在脚本和智能体工作流中使用人类可读、JSON、YAML 或 Markdown 输出。
 
-## 为 AI Agent 设计
+## 为 AI 智能体设计
 
-Telegram CLI 为 AI Agent 提供基于命令的 Telegram 和本地消息访问接口。由人工通过 `tg account add` 完成账号认证后，Agent 无需操作浏览器即可执行在线命令和本地命令。
+Telegram CLI 为 AI 智能体提供基于命令的 Telegram 和本地消息访问接口。通过 `tg account add` 完成账号认证后，智能体无需操作浏览器即可执行在线命令和本地命令。
 
-以下接口适合 Agent 工作流：
+以下接口适合智能体工作流：
 
-- JSON 和 YAML 输出让 Agent 直接读取结构化数据，而不是解析终端表格。
-- 非零退出码和结构化错误码让 Agent 能够检测并处理失败。
-- `--account <name>` 可以明确指定账号，且不会改变 current 账号。
+- JSON 和 YAML 输出让智能体直接读取结构化数据，而不是解析终端表格。
+- 非零退出码和结构化错误码让智能体能够检测并处理失败。
+- `--account <name>` 可以明确指定账号，且不会改变当前账号。
 - 本地搜索和分析命令无需重新连接 Telegram，即可查询已同步消息。
 
-例如，Agent 可以搜索指定账号，并将结果作为 JSON 解析：
+例如，智能体可以搜索指定账号，并将结果作为 JSON 解析：
 
 ```sh
 tg search "release" --account work --json
 ```
 
-### Agent Skill
+### Agent skill
 
-安装 [`using-telegram-cli`](https://skills.sh/will-17173/telegram-cli/using-telegram-cli) 技能，可以指导受支持的 AI 编程 Agent 完成账号认证、消息同步与查询、结构化输出自动化，并安全处理 Telegram 写操作：
+安装 [`using-telegram-cli`](https://skills.sh/will-17173/telegram-cli/using-telegram-cli) 技能，可以指导受支持的 AI 编程智能体完成账号认证、消息同步与查询、结构化输出自动化，并安全处理 Telegram 写操作：
 
 ```sh
 npx skills add https://github.com/will-17173/telegram-cli \
@@ -49,12 +48,73 @@ npx skills add https://github.com/will-17173/telegram-cli \
 
 Telegram CLI 需要 Node.js 22 或更高版本。
 
-在该软件包发布到 npm 后，可通过以下命令全局安装：
+通过 npm 全局安装：
 
 ```sh
 npm install -g @will-17173/telegram-cli
 ```
 
+## 快速开始
+
+登录账号、检查状态并列出聊天：
+
+```sh
+tg account add
+tg status
+tg chats
+```
+
+从 `tg chats` 的结果中选择聊天名称、用户名或 ID，然后同步并搜索消息：
+
+```sh
+tg sync <chat>
+tg search "keyword" --chat <chat>
+```
+
+你还可以批量同步聊天、监听实时消息或发送消息：
+
+```sh
+tg sync-all --max-chats 20 --delay 1
+tg listen <chat-or-id> --auto-download
+tg send <chat> "Hello from tg"
+```
+
+## 在线读取与管理 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
+```
+
+时间边界支持以 `s`、`m`、`h`、`d` 或 `w` 结尾的相对时长。例如，`7d` 表示命令启动前七天。绝对时间使用包含时区的 ISO 8601 时间戳，例如 `2026-07-13T00:00:00Z`。`--since` 必须早于 `--until`。
+
+以下命令可以查看联系人、通知设置、文件夹和群组对话框，且不会修改远端状态：
+
+```sh
+tg contact list
+tg contact info +8613800000000
+tg notification info @team
+tg folder list
+tg folder info 2
+tg group list --admin
+```
+
+以下命令会修改 Telegram 远端状态：
+
+```sh
+tg notification mute @team 8h
+tg notification unmute @team
+tg folder chat add Work @team
+tg folder chat remove Work @team
+```
+
+使用 `tg config write-access off` 可阻止这些修改。通过 `tg config write-access on` 恢复远端写操作。
+
+文件夹命令接受标题或数字文件夹 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) 创建，然后通过以下命令保存：
@@ -85,9 +145,7 @@ tg config set --proxy socks5://127.0.0.1:1080
 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 历史记录和脚本。
+Telegram CLI 支持 SOCKS4、SOCKS5、HTTP、HTTPS 和 MTProxy。代理会应用于账号登录和所有需要连接 Telegram 的命令。包含凭据的代理 URL 应视为敏感信息。
 
 如需以人类可读、JSON 或 YAML 格式查看生效配置，请运行：
 
@@ -98,9 +156,9 @@ tg config list --yaml
 tg config list --show-secrets
 ```
 
-该命令报告的是生效配置，而非 `config.json` 的原始内容。API 凭据会依次从环境变量、已保存配置和内置默认值中解析。代理则独立解析，依次使用 `TG_PROXY` 和已保存配置；两者均未配置时，代理保持缺省状态。
+该命令报告的是生效配置，而非 `config.json` 的原始内容。API hash 默认脱敏；`--show-secrets` 只会显示完整的 API hash。
 
-输出恰好报告五个字段：生效的 API ID、API hash、凭据来源、代理 URL 以及代理来源。API hash 默认脱敏；使用 `--show-secrets` 可显示完整值。代理 URL 始终完整输出，并可能包含凭据或 MTProxy secret，因此请勿将 `config list` 输出写入日志或与他人分享。`tg config list` 不会创建 Telegram 客户端，也不会发起网络连接。
+安全的代理端点详情仍然可见，但代理用户名、密码和凭据查询参数始终会被脱敏，即使使用 `--show-secrets`。
 
 运行 `tg account add` 完成身份验证并创建本地会话。其他命令不会启动交互式登录流程。
 
@@ -110,37 +168,6 @@ tg config list --show-secrets
 export DATA_DIR=/path/to/tg-cli-data
 ```
 
-## 快速开始
-
-```sh
-# 添加并登录第一个账号
-tg account add
-
-# 检查身份验证状态
-tg status
-
-# 列出聊天，然后在出现 `<chat>` 的位置使用聊天名称、用户名或 ID
-tg chats
-
-# 将聊天记录保存到本地
-tg sync <chat>
-
-# 搜索已同步到本地的消息
-tg search "keyword" --chat <chat>
-
-# 同步全部聊天
-tg sync-all --max-chats 20 --delay 1
-
-# 监听实时消息并自动下载收到的附件
-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>`。可以发送纯文本、一个或多个文件，或带说明文字的文件：
@@ -160,6 +187,33 @@ tg send <chat> "Group caption" --file ./photo.jpg --file ./clip.mp4
 
 Telegram 决定可接受的文件组合和媒体组数量限制。如果 Telegram 拒绝所请求的组合或数量，命令会返回错误，不会静默拆分为多条消息或多个媒体组。
 
+## 将聊天归档为 Markdown
+
+`archive` 必须指定明确范围。请传入一个或多个聊天 ID 或用户名，或者使用 `--all`，但不能同时使用这两种方式。
+
+命令默认使用当前账号，也可通过 `--account <name>` 临时选择账号。归档默认写入该账号数据目录下的 `archive`。使用 `--output <路径>` 可以指定其他目录。
+
+```sh
+# 首次归档并下载附件：此前七天
+tg archive @team --download-media
+
+# 自定义范围（相对时长或带时区的 ISO 时间）
+tg archive @team --since 30d --until 2026-07-13T00:00:00Z
+
+# 归档所有聊天的完整可用历史并下载附件
+tg archive --all --full --download-media
+```
+
+首次运行默认归档此前七天。使用 `--since` 和 `--until` 可以选择其他范围。`--full` 会取消起始时间限制，且不能与 `--since` 同时使用。
+
+后续运行会将新消息追加到现有归档。使用 `--rebuild` 可以替换所选的 Markdown 文件。未指定新范围时，重建会复用归档的初始范围。
+
+使用 `--download-media` 可以将附件保存到归档目录的 `media/` 下。增量运行会重试仍然缺失的引用附件。
+
+任一聊天或附件失败时，命令返回 `archive_partial_failure`，保留其他聊天的成功结果，并以状态码 1 退出。自动化场景建议使用 `--json` 或 `--yaml`，检查 `completed`、`failed` 和 `warnings`。
+
+大量历史和媒体请求可能触发 Telegram flood wait 或其他速率限制。媒体下载可以独立失败。已成功归档的消息仍保留在磁盘上，警告会指出失败的附件。
+
 ## 多账号
 
 每个 Telegram 账号都有独立持久化的身份验证会话和本地消息数据库。通过以下命令交互式登录并添加账号：
@@ -168,13 +222,13 @@ Telegram 决定可接受的文件组合和媒体组数量限制。如果 Telegra
 tg account add
 ```
 
-添加的第一个账号会自动成为 current 账号。继续添加其他账号时不会自动切换 current 账号，可通过以下命令查看或更改选择：
+添加的第一个账号会自动成为当前账号。继续添加其他账号时不会自动切换，可通过以下命令查看或更改选择：
 
 ```sh
 # 列出已添加的账号
 tg account list
 
-# 查看 current 账号
+# 查看当前账号
 tg account current
 
 # 从交互式列表中选择默认账号
@@ -187,9 +241,18 @@ tg account switch <name>
 tg account remove <name> --force
 ```
 
-在交互式终端中，`tg account switch` 会列出已添加账号、标记 current 账号，并接受账号序号。编写脚本或使用 `--json`、`--yaml`、非交互式输入时，请传入 `<name>`。
+显式登出可以结束远端会话，同时保留已添加账号、账号设置和本地消息。`--yes` 可以跳过确认提示。
+
+再次登录需要交互式终端（TTY），并会创建或替换本地 Telegram 会话。脚本和非交互智能体会收到 `interaction_required` 错误。
+
+```sh
+tg account logout work --yes
+tg account login work
+```
+
+在交互式终端中，`tg account switch` 会列出已添加账号、标记当前账号，并接受账号序号。编写脚本或使用 `--json`、`--yaml`、非交互式输入时，请传入 `<name>`。
 
-各命令默认使用 current 账号。支持 `--account` 的命令可以临时指定另一个已添加的账号，且不会改变 current 账号：
+各命令默认使用当前账号。支持 `--account` 的命令可以临时指定另一个已添加的账号，且不会改变当前账号：
 
 ```sh
 tg chats --account <name>
@@ -203,7 +266,7 @@ Telegram API 凭据对所有已添加账号生效，添加其他账号时无需
 
 ## 群组管理
 
-`group` 命令同时提供只读查询，以及成员、管理员、群设置、邀请链接、论坛话题和消息管理。请通过各 family 的帮助查看当前操作：
+`group` 命令同时支持只读查询，以及成员、管理员、群设置、邀请链接、论坛话题和消息管理。请通过各命令组的帮助查看可用操作：
 
 ```sh
 # 群组详情
@@ -220,23 +283,33 @@ tg group audit <chat> --query invite --user <user> --type member_invited --type
 
 # 管理示例（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` 恰好接受以下 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`。
+`group audit` 要求当前账号具有群组管理员权限。`--limit` 的范围是 1 到 500，默认返回 100 条事件。可重复的 `--user` 用于筛选操作发起者。可重复的 `--type` 支持以下事件组：
 
-查询和管理操作默认输出人类可读内容；暴露 `--json` 或 `--yaml` 的操作会输出结构化成功或错误结果。失败时进程退出状态非零。命令默认使用 current 账号；`--account <name>` 可仅为本次调用选择另一个已添加账号，且不会改变 current 账号。
+- **群组**：`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`
 
-管理操作分为 `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` 会关闭慢速模式。
+查询和管理操作默认输出人类可读内容；支持 `--json` 或 `--yaml` 的操作会输出结构化成功或错误结果。失败时进程退出状态非零。命令默认使用当前账号；`--account <name>` 可仅为本次调用选择另一个已添加账号，且不会改变当前账号。
 
-有破坏风险的 CLI 操作在缺少 `--yes` 时会直接拒绝，且不会连接 Telegram。永久删除群组还必须用 `--confirm-title` 提供完全一致的当前群名；交互式 listen 模式则通过 Ink 弹窗确认。管理操作需要对应的管理员权限，部分操作还要求超级群组、论坛或 creator 身份。转移所有权时，如果 Telegram 要求密码，本版本只返回 `password_required`，尚不接收密码。
+管理操作分为 `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` 等保留操作名时会产生歧义，必须使用规范路由。
 
-## Listen 中的斜杠命令
+## 监听模式中的斜杠命令
 
 交互式 `tg listen` 会在同一个菜单中展示所有支持的斜杠命令，包括 `/reply` 和完整的群管理命令目录。群管理命令沿用原有语法，无需重复当前群组：
 
@@ -245,13 +318,22 @@ tg group topic --help
 /member mute @alice 2h
 ```
 
-输入 `/` 会打开统一命令菜单，并优先显示 reply。匹配顺序依次为完整匹配、前缀匹配和有序模糊匹配，因此 `/rep`、`/rpy` 都能找到 `/reply`，`/ban` 能找到 `/member ban`。使用 Up/Down 移动；Tab 补全选中的命令；对于尚未补全的命令，Enter 也会先补全，否则执行完整命令；Esc 关闭菜单、结果或确认框。
+输入 `/` 会打开统一命令菜单，并优先显示 `/reply`。匹配顺序依次为完整匹配、前缀匹配和有序模糊匹配，因此 `/rep`、`/rpy` 都能找到 `/reply`，`/ban` 能找到 `/member ban`。使用**上方向键**和**下方向键**移动。**Tab** 补全选中的命令。**Enter** 补全未完成的命令或执行完整命令。**Esc** 关闭菜单、结果或确认框。
 
 群管理命令原有的可用性和权限检查保持不变：不可用操作仍会禁用，有风险的操作会打开确认弹窗，删除群组还会要求输入完全一致的群名。监听多个群组时，必须先用 `--send-to <chat>` 明确发送目标，例如 `tg listen @team @ops --send-to @team`，之后才能使用群管理命令。
 
 ## 在线命令与本地命令
 
-在线命令会连接 Telegram，因此需要有效的账号会话。这类命令包括 `status`、`whoami`、`chats`、`history`、`sync`、`sync-all`、`refresh`、`info`、全部 `group` 查询与管理 family、`send`、`edit`、`delete` 和 `listen`。
+在线命令会连接 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 或其他速率限制。
 
 本地命令只读取或修改所选账号的消息数据库，不会连接 Telegram。这类命令包括 `search`、`recent`、`stats`、`top`、`timeline`、`today`、`filter`、`export` 和 `purge`。
 
@@ -280,16 +362,30 @@ tg --help
 | 命令 | 用途 |
 | --- | --- |
 | `tg account add` | 登录并添加另一个 Telegram 账号。 |
-| `tg account list` | 列出已添加的账号及 current 状态。 |
-| `tg account current` | 查看 current 账号。 |
+| `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]` | 显示生效配置值及其来源；代理 URL 始终可见。 |
+| `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` | 从全部聊天同步消息，按本地已同步进度做增量更新。 |
@@ -301,33 +397,59 @@ tg --help
 | `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` 输出结构化数据。命令失败时会返回非零退出码，脚本无需解析人类可读文本即可判断执行结果。
+有限结果命令支持 `--json`、`--yaml` 和 `--markdown` 输出。未指定格式时，非交互输出仍默认使用 YAML。交互式终端使用富文本人类可读输出。
+
+有限结果命令成功时写入 stdout。JSON/YAML 结构化失败按请求的格式写入 stdout。输出格式冲突同样写入 stdout，并使用稳定的 YAML 信封。人类可读和 Markdown 失败信息写入 stderr。所有失败都会设置非零退出状态。
+
+`listen` 是无界数据流，因此不适用这些有限结果输出规则。
 
 常用选项：
 
 | 选项 | 用途 |
 | --- | --- |
-| `--account <name>` | 临时使用已添加的账号，不改变 current 账号。 |
-| `--json` / `--yaml` | 在命令支持时输出结构化数据。 |
+| `--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 媒体组会显示为一条收到的消息，并合并附件摘要。
@@ -340,6 +462,8 @@ tg --help
 
 ## 故障排查
 
+按照以下步骤解决常见的账号、会话和 API 凭据问题。
+
 ### 没有可用的当前账号
 
 如果命令返回 `account_required`，请添加账号或选择已有账号：
@@ -381,8 +505,6 @@ accounts/<name>/messages.db
 
 请将持久化配置、`.env`、Telegram 凭据、会话文件和 SQLite 数据视为敏感信息，切勿与他人分享或将它们提交到版本控制中。
 
-除 API 凭据外，`config.json` 文件还可能包含可选的 `proxy` 设置。CLI 的成功和错误输出不会打印已保存的代理 URL，但代理 URL 可能包含凭据或 MTProxy secret，因此仍须保护 `config.json`、环境和 shell 历史记录。
-
 ## 开发
 
 本项目使用 pnpm：

package/dist/account/account-authenticator.js

@@ -0,0 +1,95 @@
+import { TelegramClient } from '@mtcute/node';
+import { getTelegramCredentials, getTelegramProxy } from '../config/env.js';
+import { telegramTransportOptions } from '../telegram/proxy.js';
+import { createInterruptScope, isCliInputError, readSecret, readVisibleInput, } from '../cli/secure-input.js';
+export async function authenticateAccountAt(sessionPath, createClient = createAccountAuthClient) {
+    const client = createClient(sessionPath);
+    const input = createAuthenticationInput();
+    try {
+        await client.start(input.options);
+        const user = await client.getMe();
+        return {
+            user,
+            close: () => client.destroy(),
+        };
+    }
+    catch (error) {
+        await client.destroy().catch(() => undefined);
+        throwAccountLoginError(error);
+    }
+    finally {
+        input.close();
+    }
+}
+function createAuthenticationInput() {
+    const interrupt = createInterruptScope();
+    return {
+        options: {
+            phone: () => readVisibleInput('Phone number: ', { signal: interrupt.signal }),
+            code: () => readVisibleInput('Login code: ', { signal: interrupt.signal }),
+            password: () => readSecret('2FA password: ', { signal: interrupt.signal }),
+            codeSentCallback: () => {
+                process.stderr.write('Login code sent.\n');
+            },
+            invalidCodeCallback: (type) => {
+                process.stderr.write(type === 'code'
+                    ? 'Invalid login code. Please try again.\n'
+                    : 'Invalid 2FA password. Please try again.\n');
+            },
+            abortSignal: interrupt.signal,
+        },
+        close: interrupt.dispose,
+    };
+}
+export function mapAuthUser(user) {
+    const displayName = user.displayName?.trim();
+    const displayNameFallback = [
+        user.firstName,
+        user.lastName,
+    ].filter((value) => value != null && value.trim().length > 0).join(' ');
+    const username = user.username?.trim() || `user-${user.id}`;
+    const phone = (user.phoneNumber ?? '').replace(/\D/g, '') || String(user.id);
+    const preferredName = user.username?.trim().toLowerCase() || '';
+    const name = preferredName.length > 0 ? preferredName : phone;
+    const resolvedDisplayName = displayName && displayName.length > 0
+        ? displayName
+        : displayNameFallback;
+    return {
+        user_id: user.id,
+        username: username.toLowerCase(),
+        phone,
+        display_name: resolvedDisplayName.length > 0 ? normalizeDisplayName(resolvedDisplayName) : username,
+        name,
+    };
+}
+function createAccountAuthClient(sessionPath) {
+    const credentials = getTelegramCredentials();
+    return new TelegramClient({
+        apiId: credentials.apiId,
+        apiHash: credentials.apiHash,
+        storage: sessionPath,
+        ...telegramTransportOptions(getTelegramProxy()),
+    });
+}
+function normalizeDisplayName(displayName) {
+    const normalized = displayName.trim().replace(/\s+/g, ' ');
+    const words = normalized.split(' ');
+    for (let len = 1; len * 2 <= words.length; len += 1) {
+        if (words.length !== len * 2)
+            continue;
+        const first = words.slice(0, len).join(' ');
+        const second = words.slice(len).join(' ');
+        if (first === second)
+            return first;
+    }
+    return normalized;
+}
+function throwAccountLoginError(cause) {
+    if (isCliInputError(cause))
+        throw cause;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const error = new Error(message, { cause });
+    error.code = 'account_login_failed';
+    throw error;
+}
+//# sourceMappingURL=account-authenticator.js.map

package/dist/account/account-authenticator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-authenticator.js","sourceRoot":"","sources":["../../src/account/account-authenticator.ts"],"names":[],"mappings":"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"}

package/dist/account/account-context.js

@@ -15,6 +15,13 @@ export function resolveAccountContext(input = {}) {
     }
     return toAccountContext(dataDir, account);
 }
+export function resolveAuthenticatedAccountContext(input = {}) {
+    const context = resolveAccountContext(input);
+    if (context.authState === 'logged_out') {
+        throw new Error(`account_logged_out: account "${context.name}" is logged out`);
+    }
+    return context;
+}
 function explicitOrCurrent(explicitName, currentAccount) {
     const explicit = explicitName?.trim();
     return explicit ? explicit : currentAccount ?? undefined;

package/dist/account/account-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"account-context.js","sourceRoot":"","sources":["../../src/account/account-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAOvD,MAAM,UAAU,qBAAqB,CAAC,QAAgC,EAAE;IACtE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAA;IAC3E,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAA;IAC/D,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC7B,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAA;IAE5E,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAC9D,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,GAAG,CAAC,CAAA;IACzD,CAAC;IAED,OAAO,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAC3C,CAAC;AAED,SAAS,iBAAiB,CAAC,YAAgC,EAAE,cAA6B;IACxF,MAAM,QAAQ,GAAG,YAAY,EAAE,IAAI,EAAE,CAAA;IACrC,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,IAAI,SAAS,CAAA;AAC1D,CAAC"}
+{"version":3,"file":"account-context.js","sourceRoot":"","sources":["../../src/account/account-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACrE,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAOvD,MAAM,UAAU,qBAAqB,CAAC,QAAgC,EAAE;IACtE,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,CAAA;IAC3E,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAA;IAC/D,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,EAAE,CAAA;IAC7B,MAAM,IAAI,GAAG,iBAAiB,CAAC,KAAK,CAAC,YAAY,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAA;IAE5E,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAC9D,CAAC;IAED,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IAC/B,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,+BAA+B,IAAI,GAAG,CAAC,CAAA;IACzD,CAAC;IAED,OAAO,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;AAC3C,CAAC;AAED,MAAM,UAAU,kCAAkC,CAAC,QAAgC,EAAE;IACnF,MAAM,OAAO,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;IAC5C,IAAI,OAAO,CAAC,SAAS,KAAK,YAAY,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,gCAAgC,OAAO,CAAC,IAAI,iBAAiB,CAAC,CAAA;IAChF,CAAC;IAED,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,SAAS,iBAAiB,CAAC,YAAgC,EAAE,cAA6B;IACxF,MAAM,QAAQ,GAAG,YAAY,EAAE,IAAI,EAAE,CAAA;IACrC,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAc,IAAI,SAAS,CAAA;AAC1D,CAAC"}

package/dist/account/account-name.js

@@ -0,0 +1,17 @@
+const PATH_SEPARATOR = /[/\\]/u;
+const CONTROL_CHARACTER = /[\u0000-\u001f\u007f-\u009f]/u;
+export function isSafeAccountName(value) {
+    return typeof value === 'string'
+        && value.trim().length > 0
+        && value !== '.'
+        && value !== '..'
+        && !PATH_SEPARATOR.test(value)
+        && !CONTROL_CHARACTER.test(value)
+        && value.normalize('NFC') === value;
+}
+export function assertSafeAccountName(value) {
+    if (!isSafeAccountName(value)) {
+        throw new Error('account_store_error: invalid account name');
+    }
+}
+//# sourceMappingURL=account-name.js.map

package/dist/account/account-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"account-name.js","sourceRoot":"","sources":["../../src/account/account-name.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAAG,QAAQ,CAAA;AAC/B,MAAM,iBAAiB,GAAG,+BAA+B,CAAA;AAEzD,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ;WAC3B,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;WACvB,KAAK,KAAK,GAAG;WACb,KAAK,KAAK,IAAI;WACd,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC;WAC3B,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC;WAC9B,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,KAAK,KAAK,CAAA;AACvC,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,KAAc;IAClD,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAA;IAC9D,CAAC;AACH,CAAC"}

package/dist/account/account-presets.js

@@ -1,4 +1,5 @@
-import { join } from 'node:path';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { assertSafeAccountName } from './account-name.js';
 export function toAccountContext(dataDir, account) {
     const accountCopy = Object.freeze({
         name: account.name,
@@ -6,17 +7,33 @@ export function toAccountContext(dataDir, account) {
         username: account.username,
         phone: account.phone,
         display_name: account.display_name,
+        auth_state: account.auth_state,
     });
     return Object.freeze({
+        name: account.name,
+        authState: account.auth_state,
         account: accountCopy,
         sessionPath: accountSessionPath(dataDir, account.name),
         dbPath: accountDbPath(dataDir, account.name),
     });
 }
 export function accountSessionPath(dataDir, accountName) {
-    return join(dataDir, 'accounts', accountName, 'session');
+    return join(accountRoot(dataDir, accountName), 'session');
 }
 export function accountDbPath(dataDir, accountName) {
-    return join(dataDir, 'accounts', accountName, 'messages.db');
+    return join(accountRoot(dataDir, accountName), 'messages.db');
+}
+function accountRoot(dataDir, accountName) {
+    assertSafeAccountName(accountName);
+    const accountsRoot = resolve(dataDir, 'accounts');
+    const root = resolve(accountsRoot, accountName);
+    const contained = relative(accountsRoot, root);
+    if (contained.length === 0
+        || contained === '..'
+        || contained.startsWith(`..${sep}`)
+        || isAbsolute(contained)) {
+        throw new Error('account_store_error: invalid account name');
+    }
+    return root;
 }
 //# sourceMappingURL=account-presets.js.map