指南 on tgs

配置文件

Mon, 01 Jan 0001 00:00:00 +0000

配置文件#

tgs 通过配置文件支持多个 Telegram 账户——类似于 AWS CLI 管理凭证的方式。每个配置文件拥有独立的会话，存储在单独的数据库文件中。

配置文件解析顺序#

运行任何 tgs 命令时，活跃配置文件按以下优先级确定（从高到低）：

传递给命令的 --profile 参数
TGS_PROFILE 环境变量
当前目录或父目录中的 .tgs.yaml 文件
"default"（默认值）

按目录绑定配置文件#

您可以通过创建 .tgs.yaml 文件将配置文件绑定到特定目录。使用 tgs profile switch 可自动完成此操作：

cd ~/projects/work-project
tgs profile switch work

profile: work

tgs 会沿目录树向上查找 .tgs.yaml，因此它在所有子目录中同样生效。这是为不同项目使用不同账户的推荐方式。

管理配置文件#

列出配置文件#

tgs profile list

* default (@myuser)
 work (@workuser)

* 标记当前活跃的配置文件。默认使用 JSON 格式输出，包含 active 字段。

切换当前目录的配置文件#

tgs profile switch work

在当前目录创建或覆盖 .tgs.yaml 文件。

删除配置文件#

tgs profile delete old-account

tgs profile switch default
tgs profile delete work

删除配置文件目录及其会话数据库。无法删除当前活跃的配置文件——请先切换到其他配置文件。

搜索

Mon, 01 Jan 0001 00:00:00 +0000

搜索#

tgs 提供四个搜索子命令，它们直接对应 Telegram 的 MTProto 搜索方法。所有输出均为 JSON，便于通过管道传入 jq、交给 AI 智能体或以编程方式处理。

在聊天中搜索#

最常见的操作：在指定聊天中搜索消息。

tgs search messages "docker compose" -c @devops_notes

查询参数为必填项。-c / --chat 标志指定在哪个聊天中搜索。所有支持的格式请参见下方的聊天解析。

多个聊天#

通过重复该标志或使用逗号分隔的值传入多个聊天：

# 重复标志
tgs search messages "release" -c @frontend -c @backend

# 逗号分隔
tgs search messages "release" -c @frontend,@backend

tgs 会依次对每个聊天执行搜索，并将结果合并为一个 JSON 响应。

按作者筛选#

使用 --from / -f 只显示来自特定发送者的消息：

tgs search messages "bug" -c @dev_chat --from @alice

--from 的值接受与 --chat 相同的格式（用户名、数字 ID、手机号或 t.me 链接）。

按内容类型筛选#

--filter 标志将结果限定为特定的消息类型。共有 15 种可用过滤器：

过滤器	说明
`photo`	图片
`video`	视频
`photo-video`	图片和视频
`document`	文件和文档
`url`	包含链接的消息
`gif`	GIF 动图
`voice`	语音消息
`music`	音频文件 / 音乐
`round-video`	圆形视频消息
`geo`	位置和实时位置
`contact`	共享的联系人
`pinned`	置顶消息
`mention`	提及当前用户的消息
`phone-call`	通话记录
`chat-photo`	聊天头像变更

示例 —— 查找频道中的所有文档：

来源

Mon, 01 Jan 0001 00:00:00 +0000

来源#

tgs sources 让您枚举并查看账户中的 Telegram 对话——频道、超级群组、普通群组、用户和机器人。所有输出均为 JSON 格式，可直接通过 jq 处理或提供给 AI 代理。

通过 jq 解析时： tgs 把诊断日志（[tgs] retry: …、[tgs] FLOOD_WAIT: …）写入 stderr，JSON 写入 stdout。在管道传给 jq 时请丢弃 stderr，以免解析失败：
tgs sources list --with-stats 2>/dev/null | jq '.sources[].title'
避免使用 2>&1 | jq …——那会把日志混进 stdout 并破坏 JSON 解析。

列出所有来源#

最简单的调用方式会返回账户中的所有对话：

tgs sources list

响应为包含 sources 数组、total 总数和可选 cursor 的 JSON 对象：

{
 "sources": [
 {
 "id": -1001234567890,
 "type": "channel",
 "title": "Durov's Channel",
 "username": "durov",
 "access": "public",
 "members_count": 1234567,
 "verified": true,
 "unread_count": 0,
 "last_message": {"id": 4321, "date": "2026-05-28T08:15:00Z"}
 }
 ],
 "total": 287
}

total 是您账户中的对话总数（应用 --type 筛选之前）。CLI 保证 total >= len(sources)（Telegram 自身的计数器有时已过期，我们会把 total 抬升到实际返回的数量）。请勿用 total 除以数组长度估算页数——请使用 cursor 分页。