Telegram 知识库机器人

当前状态

MVP 已上线，可在 TG 群组中 @ 机器人提问，机器人会检索知识库并通过 LLM 生成回答。单独 @ 不带问题时，返回站点功能导航。

部署方式

git push main → GitHub Actions 自动：

1. 上传知识库 md 到 /srv/knowledge_base/
2. 上传 bot/ 到 /srv/kb_bot/
3. 写入 /srv/kb_bot/bot/.env
4. 全量构建 RAG 向量索引（python3 retriever.py）
5. systemctl restart kb_bot
6. 幂等注入 Nginx location（首次）

环境变量

变量	说明
TELEGRAM_BOT_TOKEN	BotFather 生成的 token
BOT_USERNAME	机器人用户名（不含 @），用于群组 @ 过滤
COMPATIBLE_BASE_URL	LLM Compatible API base URL
COMPATIBLE_API_KEY	LLM Compatible API Key
OPENROUTER_API_KEY	OpenRouter API Key，用于 embedding
KB_PATH	知识库 md 文件目录，默认 /srv/knowledge_base
INDEX_PATH	chromadb 向量索引目录，默认 /srv/kb_index
GITHUB_TOKEN	GitHub fine-grained token（contents:read），用于 /recent 拉取 private 仓库 commits

存储位置：GitHub Actions → Settings → Environments → prod → Secrets

使用方式

群组中

@ 机器人并附上问题：

@my_kb_bot 什么是 RAG？

单独 @ 不带问题时，返回功能导航。

私聊中

直接发送问题，无需 @。

命令

命令	说明
/start 或 /help	显示功能介绍与使用说明
/nav	站点功能导航（含各页面链接）
/site	站点入口链接汇总
/categories	展示所有知识库分类，点击分类 → 文章列表，点击文章 → 直接查看内容
/today	显示今天日期
/status	查看知识库已加载的文档数量
/recent	拉取近期 GitHub commits，结合待办，LLM 总结进度与下一步建议
/save	对当前 session 执行知识沉淀 Pipeline（Step 1~3），回复摘要 + 写入决策预览
/save <内容>	直接沉淀指定文本（跳过 Step 1），回复写入决策预览

会话策略

按 {chat_id}:{user_id}:{session_key} 维护对话历史：

• chat_id：群组或私聊 ID
• user_id：消息发送者 ID
• session_key：日期 + 序号，30 分钟无交互自动新建

示例：

-1001234567890:987654321:20260307_1  # 群组中用户 A 的第一个会话
-1001234567890:987654321:20260307_2  # 30 分钟后用户 A 的第二个会话
-1001234567890:123456789:20260307_1  # 同群组用户 B 的独立会话

限制与待改进

问题	说明
无上下文记忆	✅ 已支持，按 chat_id:user_id:session_key 维护对话历史（Redis，7 天 TTL）
关键词匹配	✅ 已替换为 RAG 向量检索
无写入能力	✅ /save 命令已支持 Step 1~3（提炼 → 寻址 → 决策预览），Step 3.5 确认 + Step 4 写入待实现
无权限控制	任何人加入群组都可以提问 已通过白名单 chat_id 硬编码控制
多机器人循环	过滤所有 from.is_bot = true 的消息，不响应任何机器人发出的内容