mcpField
T
tg-cli

tg-cli

github.com/jackwener生产力294108 次安装33 周前更新
代码仓库

关于 tg-cli

tg-cli 是面向 Telegram 用户与 AI Agent 的命令行工具，可同步聊天、搜索和筛选消息，并发送消息或监控群组。它默认从本地 SQLite 缓存查询，并提供 YAML、JSON 等机器可读输出。

主要功能

  1. 01同步聊天与消息
  2. 02搜索、筛选和浏览消息
  3. 03发送消息并监控群组
  4. 04本地 SQLite 缓存查询
  5. 05支持 YAML 和 JSON 输出

适用场景

  1. 01检索聊天中的关键词
  2. 02刷新消息后分析近期内容
  3. 03导出聊天记录供 Agent 处理

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jackwener/tg-cli --skill tg-cli

安装后在 Claude Code 中输入/tg-cli确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.env.example
README.md
.gitignore
CHANGELOG.md
CONTRIBUTING.md
LICENSE
SCHEMA.md
pyproject.toml
.github/ISSUE_TEMPLATE/
feature_request.yml
bug_report.yml
.github/workflows/
ci.yml
publish.yml
examples/
tg-refresh.cron
examples/systemd/
tg-refresh.timer
tg-refresh.service
src/tg_cli/
__init__.py
client.py
console.py
db.py
config.py
src/tg_cli/cli/
_chat.py
_sync.py
_output.py
__init__.py
data.py
main.py
tg.py
query.py
tests/
test_cli.py
conftest.py

详细介绍

tg-cli 技能

用于 Telegram 的 CLI 工具 — 同步聊天、搜索消息、筛选关键词、发送消息和监控群组。

前置条件

# Install (requires Python 3.10+)
uv tool install kabi-tg-cli
# Or: pipx install kabi-tg-cli

# Upgrade to latest (recommended to avoid API errors)
uv tool upgrade kabi-tg-cli
# Or: pipx upgrade kabi-tg-cli

身份验证

使用你的 Telegram 账号（MTProto）。默认使用内置的 Telegram Desktop API 凭据 — 无需申请应用。

tg chats              # First run: enter phone + verification code
tg whoami             # Check current user

# Optional: use your own app credentials
export TG_API_ID=123456
export TG_API_HASH=your_telegram_app_hash

命令参考

Telegram 操作
tg chats                          # List joined chats
tg chats --type group             # Filter by type
tg status                         # Check auth/session status
tg status --yaml                  # Structured auth status
tg whoami                         # Show current user info
tg whoami --yaml                  # Preferred structured output for agents
tg history CHAT -n 1000           # Fetch historical messages
tg sync CHAT                      # Incremental sync (only new)
tg sync-all                       # Low-level sync for all current dialogs
tg refresh                        # Recommended daily refresh entrypoint
tg listen                         # Real-time listener
tg listen --persist               # Reconnect automatically for a near-live cache
tg info CHAT                      # Chat details
tg send CHAT "Hello!"             # Send a message
搜索与查询
tg search "Rust"                     # Search stored messages
tg search "Rust" -c "牛油果" --yaml  # Filter by chat + preferred YAML output
tg search "Rust|Golang" --regex      # Regex search
tg search "Rust" --sync-first --yaml # Refresh before querying
tg recent --hours 24 -n 20 --yaml    # Browse latest messages
tg recent --hours 24 --sync-first    # Refresh before browsing recent
tg filter "Rust,Golang,Java"         # Multi-keyword filter (today)
tg filter "招聘,remote" --hours 48   # Filter last N hours
tg today --sync-first                # Refresh before reading today's messages
tg stats --sync-first                # Refresh before aggregate stats
tg top -c "牛油果" --hours 24 --sync-first
tg timeline --by hour --sync-first   # Activity bar chart
数据管理
tg export CHAT -f json -o out.json   # Export messages
tg export CHAT --hours 24            # Export last 24 hours
tg purge CHAT -y                     # Delete stored messages

结构化输出

主要命令支持 --json 和 --yaml，用于生成机器可读的输出。 AI Agent 应优先使用 --yaml，除非必须使用严格的 JSON 解析器：

tg search "Rust" --yaml
tg status --yaml
tg whoami --yaml
tg today --yaml
tg filter "招聘" --hours 48 --yaml

当 stdout 不是 TTY 时，tg-cli 会自动默认使用 YAML。 使用 OUTPUT=yaml|json|rich|auto 可覆盖默认输出模式。 所有机器可读的输出均采用 SCHEMA.md 中说明的封装格式。

刷新模型

tg-cli 以本地优先。查询命令默认读取本地 SQLite 缓存。

  • 在分析前，使用 tg refresh 作为常规入口。
  • 如果单次查询应先刷新再读取，请使用 --sync-first。
  • 如果需要近实时的本地缓存，请使用 tg listen --persist。
  • tg sync-all 适用于较底层的脚本或调度程序。

AI Agent 常用模式

# Quick daily workflow
tg refresh --yaml                    # Refresh everything
tg today --sync-first --yaml         # See today's messages
tg filter "Rust,Golang" --hours 24 --sync-first --yaml

# Search and export for analysis
tg search "招聘" -n 100 --yaml > jobs.yaml
tg filter "远程,remote,Web3" --hours 72 --yaml > filtered.yaml

# Send messages
tg send "GroupName" "Hello from CLI!"

调试

tg -v sync-all       # Debug logging for troubleshooting
tg -v refresh        # See refresh behavior across dialogs
tg -v stats          # See SQL queries and timing

错误处理

  • 命令成功时以代码 0 退出，失败时以非零代码退出
  • 错误消息以 ✗ 为前缀或显示为红色
  • 聊天名称采用模糊匹配（支持部分名称）
  • refresh 和 sync-all 会妥善跳过无法找到的聊天

调度

示例位于仓库中：

  • examples/tg-refresh.cron
  • examples/systemd/tg-refresh.service
  • examples/systemd/tg-refresh.timer

安全说明

  • 不要要求用户在聊天记录中分享电话号码或验证码。
  • 会话数据存储在本地，绝不会上传。

评论

支持 Markdown