Telegram MTProto（telethon）
    ↓  sync / refresh（增量）
本地 SQLite  ~/.tg-hub/messages.db
    ↓  search / today / recent / filter（离线）
结构化数据

/var/minis/skills/tg-hub/
├── SKILL.md
├── pyproject.toml          # 仅 telethon
└── scripts/
    ├── __init__.py
    ├── config.py           # 配置（环境变量 / 默认路径）
    ├── db.py               # SQLite 消息存储
    ├── exceptions.py       # 结构化异常
    └── client.py           # TGClient 核心类（全部 API）

1. 打开 Terminal
2. （推荐）先设置自己的 TG_API_ID / TG_API_HASH
3. cd /var/minis/skills/tg-hub
4. uv run python -c "
   import sys; sys.path.insert(0,'.')
   from scripts.client import TGClient
   me = TGClient().login()
   print('登录成功：', me)
   "
5. 按提示输入手机号（+86XXXXXXXXXX 格式）
6. 输入 Telegram App 收到的验证码
7. 登录成功后 session 自动保存，后续免登录

cd /var/minis/skills/tg-hub
uv sync

import sys
sys.path.insert(0, "/var/minis/skills/tg-hub")
from scripts.client import TGClient
client = TGClient()
# 查看当前账号
me = client.whoami()
print(me["name"], me["phone"])
# 列出所有对话（实时从 TG 获取）
chats = client.list_chats()
for c in chats[:10]:
    print(f"  [{c['type']}] {c['name']}  未读: {c['unread']}")
# 增量同步单个群
n = client.sync("群名或用户名", limit=1000)
print(f"新增 {n} 条消息")
# 快速刷新所有群（每群最多 500 条新消息）
# 默认带轻微节流；也可以限制本轮只刷前 30 个 chat
result = client.refresh(delay=1.0, max_chats=30)
for name, count in result.items():
    if count > 0:
        print(f"  {name}: +{count}")
# 搜索关键词
msgs = client.search("Python", hours=48)
for m in msgs:
    print(f"[{m['chat_name']}] {m['sender_name']}: {m['content'][:80]}")
# 多关键词过滤（OR 逻辑）
msgs = client.filter("招聘,remote,兼职", hours=24)
# 今日消息
msgs = client.today()
# 最近 12 小时消息
msgs = client.recent(hours=12, limit=200)
# 发言排行
top = client.top_senders(hours=24)
for t in top[:5]:
    print(f"  {t['sender_name']}: {t['msg_count']} 条")
# 时间线统计
tl = client.timeline(granularity="hour", hours=48)
# 本地数据库统计
stats = client.stats()
print(f"本地共 {stats['total']} 条消息，{len(stats['chats'])} 个群")