使用说明

Telegram摘要机器人

一个自我托管的个人助理，可以查看你的电报，学习你如何回答问题，并为你提供每日简报。完全在您自己的硬件上运行——通过使用本地LLM 奥拉玛，没有第三方AI API。它还通过MCP服务器将所有这些数据暴露给Claude Code，因此您可以从任何项目询问您的Telegram活动。

大局

有三个部分协同工作：

                YOUR TELEGRAM
                     │
                     ▼
    ┌────────────────────────────────┐
    │          BOT (long-running)    │
    │                                │
    │  Telethon ──▶ SQLite           │
    │  (listens)    (messages.db)    │
    │                    │           │
    │  Ollama   ◀────────┘           │
    │  (local LLM: classifies        │
    │   questions, summarizes chats) │
    │                    │           │
    │  ChromaDB ◀────────┘           │
    │  (vector embeddings for        │
    │   Q&A similarity search)       │
    │                    │           │
    │  Telegram Bot ◀────┘           │
    │  (sends you digests,           │
    │   suggestions, responds        │
    │   to /commands)                │
    │                                │
    │  Dashboard ──▶ localhost:8000  │
    └────────────────────────────────┘
                     │
              writes to disk
                     │
                     ▼
              ./data/ folder
          (messages.db, chroma/)
                     │
              reads from disk
                     │
                     ▼
    ┌────────────────────────────────┐
    │   MCP SERVER (on-demand)       │
    │                                │
    │  Claude Code spawns this       │
    │  when you ask about Telegram.  │
    │  It reads the DB, returns      │
    │  results, then exits.          │
    └────────────────────────────────┘

机器人 全天候运行（通过Docker），接收消息并构建知识库。

MCP服务器 是无状态和只读的。Claude Code在需要Telegram数据时自动启动，然后关闭。它不需要机器人运行——它只是读取机器人已经收集的任何数据。

它实际上做了什么

1.收听您的所有Telegram消息

通过Telethon以您的用户帐户（而不是机器人）连接。捕获每个聊天中的每一条消息——DM、群组、频道。将它们以完整的上下文（谁说了什么、在哪里、何时）存储在SQLite中。

2.检测针对您的问题

每10分钟（或每50条消息），它会向本地LLM发送一批消息，以分类哪些消息是需要您注意的问题。寻找@提及、直接问题和上下文线索。

3.从你的答案中学习

当您回答检测到的问题时，它会保存问答对。这些被嵌入到ChromaDB中用于语义搜索。如果以后有人问类似的问题，它可以建议你之前的答案。重复问题（相似度>95%）会自动合并。

4.给你发每日摘要

在您配置的时间（默认为上午7点），本地LLM会根据严格的“引用实际内容”提示总结每个活动聊天。摘要以a开头 🚨 需要您的回复 部分列出待处理的@提及，然后是每个聊天的亮点。没有值得注意的报道的聊天被丢弃，而不是被绒毛填充。

5.将数据暴露给克劳德代码（MCP）

MCP服务器允许Claude Code访问您的Telegram数据。从任何项目中问“团队昨天讨论了什么？”或“谁在等我的回复？”之类的问题。

你需要的

在开始之前，请准备好以下内容：

电报API凭证 --从 my.telegram.org （api_id+api_hash）
电报机器人 --创建一个via @植物学家（用于向您发送摘要/通知）
奥拉玛 — 安装Ollama 并拉取一个模型： ollama pull gemma4 （或您喜欢的任何聊天模式；更新 llm.model 在 config.yaml 匹配）
码头工人 — 安装Docker桌面如果你没有

不需要第三方API密钥-LLM通过Ollama本地运行，嵌入通过 sentence-transformersDocker容器通过以下方式到达主机上的Ollama host.docker.internal （在中自动配置 docker-compose.yml).

快速开始

git clone <repo-url> && cd tg_summary_project
./setup.sh

就是这样。脚本将：

检查Docker是否已安装并正在运行
提示您输入凭据和Ollama基本URL（写入 .env 具有安全权限）
构建Docker镜像
运行Telegram身份验证向导（向您发送验证码）
生成您的 config.yaml
修复所有文件/目录权限
启动服务
打印Claude代码的MCP配置片段

最后，您将看到一个JSON块——将其粘贴到 ~/.claude/.mcp.json 连接克劳德代码。

手动设置（如果您愿意）

Click to expand

1.环境变量

cp .env.example .env
# Fill in your Telegram credentials + OLLAMA_BASE_URL, then lock it down:
chmod 600 .env

2.构建并运行安装向导

docker compose build
docker compose run --rm telegram-digest python -m src.setup

3.修复数据目录权限并启动

rm -f data/.lock
docker compose up -d

4.验证

docker compose logs -f        # Check logs
open http://127.0.0.1:8000    # Dashboard

运行Bot

# Start
docker compose up -d

# Stop
docker compose down

# Restart (e.g. after config changes)
docker compose restart

# Rebuild (after code changes)
docker compose build && docker compose up -d

# View logs
docker compose logs -f

# Force an immediate digest
docker compose exec telegram-digest python -m src.main --digest-now

MCP服务器（克劳德代码集成）

MCP服务器允许Claude Code查询您的电报数据。 setup.sh 在末尾打印配置，但如果需要手动打印，请将其添加到 ~/.claude/.mcp.json:

{
  "mcpServers": {
    "tg-summary": {
      "command": "/path/to/tg_summary_project/venv/bin/python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/tg_summary_project"
    }
  }
}

MCP服务器需要安装了依赖项的本地Python venv：

python3 -m venv venv && source venv/bin/activate && pip install -r requirements.txt

可用工具

工具	你可以问什么
`search_qa`	“以前有人问过X吗？”——在你的问答知识库中进行语义搜索
`search_messages`	“人们对Y说了什么？”——对最近的消息进行关键字搜索
`get_digest`	“昨天发生了什么事？”——取每日摘要
`get_pending_mentions`	“谁在等我？”——未回答@提及
`get_chat_summary`	“#engineering中发生了什么？”——来自特定聊天的原始信息
`get_stats`	“我们有多少数据？”——消息计数、问答对等。
`list_chats`	“正在监视哪些聊天？”--所有具有优先级的聊天
`list_qa_pairs`	“知识库中有什么？”——浏览所学问答对

MCP服务器是只读的，不需要机器人运行。它直接从SQLite数据库和磁盘上的ChromaDB文件读取。

机器人命令

在Telegram中将这些发送给您的机器人：

命令	它的作用
`/stats`	消息计数、问答对、存储、正常运行时间
`/digest`	立即生成并发送摘要
`/pending`	Show@提到您尚未回复
`/suggest`	与/待定，但有AI建议的回应
`/search <query>`	搜索您的问答知识库
`/recent <chat>`	特定聊天最近活动的摘要
`/pause` / `/resume`	停止/启动消息接收

配置

一切都在 config.yaml （由安装程序生成）。关键设置：

telegram:
  delivery_chat_id: 123456789     # Your Telegram user ID (where digests get sent)
  username: your_username          # For @mention detection (without the @)

llm:
  provider: ollama
  model: gemma4:latest             # Any chat model you've pulled into Ollama
  base_url: ${OLLAMA_BASE_URL}     # Read from .env
  request_timeout: 600.0           # Local generation can be slow; bump if needed

digest:
  schedule: "07:00"               # When to send the daily digest
  timezone: America/New_York      # Your timezone
  lookback_hours: 24              # How far back to look

quiet_hours:
  enabled: true
  start: "22:00"                  # No ingestion or notifications during quiet hours
  end: "08:00"

chats:
  default_priority: 3             # 1=detailed, 3=standard, 5=excluded from digest
  ignore_patterns:                # Chats to skip entirely (glob patterns)
    - "*Alerts*"
    - "*Bot"

数据

万物皆有生命 ./data/:

路径	内容	大小
`messages.db`	SQLite——消息、问答、摘要、建议	~1 MB
`chroma/`	ChromaDB——用于问答相似性搜索的向量嵌入	~几MB
`telegram.session`	Telethon身份验证会话（持久登录）	微小
`.lock`	防止多个实例运行	mini

90天后消息会自动删除（可通过配置 data_retention.messages_days).

CLI工具

# Quick look at recent messages
python fetch_today.py
python fetch_today.py --hours 48 --chat "Team Chat"

# See pending mentions
python fetch_today.py --pending

# See learned Q&A pairs
python fetch_today.py --qa

# Get your Telegram user ID
python get_user_id.py

仪表板

web仪表板运行在 http://127.0.0.1:8000.如果你设置了 DASHBOARD_TOKEN 在 .env （setup.sh会自动执行此操作），系统会提示您输入凭据——任何用户名都可以，密码就是您的令牌。

故障排除

“电报会话未授权” --会话已过期。重新运行安装程序：

docker compose run --rm telegram-digest python -m src.setup
docker compose restart

“另一个实例已在运行” --过期锁文件：

rm data/.lock
docker compose restart

容器中的权限错误 --修复数据目录所有权：

sudo chown -R 1000:1000 data/
docker compose restart

未检测到任何问题 --分类器分批运行（每10分钟或50条消息一次）。检查日志 classification_batch_processed.

克劳德代码中未显示MCP服务器 --添加后重新启动Claude代码 .mcp.json。请查看 /mcp 在Claude Code中查看连接的服务器。

集装箱无法到达Ollama --在Linux上， host.docker.internal 要求 extra_hosts: host.docker.internal:host-gateway 已存在的映射 docker-compose.yml确认Ollama正在监听所有接口（而不仅仅是 127.0.0.1)通过设置 OLLAMA_HOST=0.0.0.0 在启动Ollama之前，从容器内部进行测试：

docker compose exec telegram-digest python -c "import httpx; print(httpx.get('http://host.docker.internal:11434/api/tags').json())"