Xinlan Telegram Companion Bot

一个可长期运行、可配置、可扩展的 Telegram 陪伴型 Bot。
项目目标是让机器人在聊天体验上更接近真实私聊：有节奏、有状态、有记忆，并支持中断续写。

Highlights

• 人格化聊天体验：时段人格、情绪维度、关系维度联合驱动回复风格
• Debounce 合并输入：减少抢答与碎片化回复
• 分段发送：支持 ||| 分段语义与策略化段数控制
• 可中断回复（Interruptible Response）：
  • typing 阶段可中断并重生成
  • 已发送部分段时可停止后续未发送段并续写
• Warm/Linger 窗口：短时在线感，窗口内更快响应，窗口外恢复冷启动节奏
• MongoDB 持久化：聊天状态、消息、摘要、记忆、情绪、关系等全链路落库
• 管理面板命令：超级管理员可在线调参与诊断

Tech Stack

• Python 3.14
• python-telegram-bot[job-queue] >=20,<22
• openai >=1.0.0（调用 DeepSeek OpenAI 兼容接口）
• motor >=3.5.0（MongoDB async driver）

Project Structure

.
├── main.py                    # 入口，依赖装配与启动
├── config.py                  # 配置加载（.env）
├── handlers/                  # 用户命令与消息入口
├── admin/                     # 超级管理员命令与权限
├── services/                  # 核心业务逻辑
├── repositories/              # 数据访问层与模型
├── db/                        # Mongo 管理
└── utils/                     # 通用工具

Quick Start

1) Install

pip install -r requirements.txt

2) Start MongoDB

使用本地 Mongo，或直接用项目自带 compose：

docker compose up -d

3) Configure

cp .env.example .env

编辑 .env，至少填入：

• TELEGRAM_TOKEN
• DEEPSEEK_API_KEY

4) Run

python3 main.py

Environment Variables

配置定义位于 config.py。

Required

• TELEGRAM_TOKEN
• DEEPSEEK_API_KEY

Runtime / Model

• DEEPSEEK_BASE_URL (default: https://api.deepseek.com)
• DEEPSEEK_MODEL (default: deepseek-chat)
• MAX_HISTORY_MESSAGES (default: 20)
• STATE_FILE (default: bot_state.json)
• CHECK_INTERVAL_SECONDS (default: 300)

Debounce / Timing

• DEBOUNCE_MIN_SECONDS (default: 4)
• DEBOUNCE_MAX_SECONDS (default: 8)
• LINGER_WINDOW_SECONDS (default: 60)
• COLD_REPLY_DELAY_MIN / COLD_REPLY_DELAY_MAX
• WARM_REPLY_DELAY_MIN / WARM_REPLY_DELAY_MAX
• COLD_TYPING_DELAY_MULTIPLIER / WARM_TYPING_DELAY_MULTIPLIER
• COLD_INTER_SEGMENT_PAUSE_MULTIPLIER / WARM_INTER_SEGMENT_PAUSE_MULTIPLIER

MongoDB

• MONGODB_URI (default: mongodb://localhost:27017)
• MONGODB_DB_NAME (default: xinlan_bot)

Message Logging

• ENABLE_MESSAGE_LOGGING (default: true)
• MESSAGE_RETENTION_DAYS (default: 90)
• MAX_STORED_MESSAGES_PER_CHAT (default: 5000)
• LOG_COMMAND_MESSAGES (default: true)
• LOG_PROACTIVE_MESSAGES (default: true)

Admin

• SUPERADMIN_CHAT_ID（可选，启用超级管理员命令）

Commands

命令注册位置：

• 用户命令：handlers/message_handlers.py
• 管理命令：admin/handlers.py

User Commands

/start, /help, /myid, /status, /timepersona, /emotion_show, /corrections, /history, /memory, /remember, /forget, /profile, /profile_rebuild, /profile_edit, /silent, /unsilent, /busy, /unbusy

Superadmin Commands

/whoami, /su, /admin_help, /bot_status, /bot_pause, /bot_resume, /proactive_on, /proactive_off, /reload_config, /ping, /uptime, /chat_list, /chat_info, /chat_enable, /chat_disable, /chat_reset, /memory_list, /memory_history, /summary_show, /emotion_show, /emotion_set, /emotion_reset, /emotion_fields, /emotion_metric_set, /emotion_intensity_set, /emotion_metrics_set, /relationship_show, /relationship_fields, /relationship_metric_set, /relationship_metrics_set, /relationship_reset, /debug_context, /corrections, /profile_show, /profile_set, /profile_clear, /profile_rebuild_admin, /profile_history, /db_status, /db_ping, /db_stats

High-risk Commands (Need /confirm)

/chat_delete, /history_clear, /memory_clear, /summary_clear, /broadcast, /db_cleanup, /confirm

Behavior Priority (Style Control)

当前实现遵循以下优先级：

核心人格 > 回复模式 > 情绪硬约束 > relationship 修饰 > 时段人格修饰 > 风格后处理

这保证了：

• 不会因为单一模块导致风格失真
• 低温度情绪可对过热表达进行硬约束
• 高亲近状态可以增强“怎么说”，不是只影响“答不答应”

Operational Notes

• 同一 token 只能有一个 polling 实例。
  若出现 409 Conflict (getUpdates)，请关闭重复进程。
• 生产环境建议：
  • 使用独立 Mongo 实例
  • 配置日志采集
  • 固定模型与关键参数

Development

Local checks

python3 -m compileall .

Suggested workflow

1. 新增能力先补 repository/service 边界
2. 在 handler 接入命令或事件入口
3. 增加日志与回归验证脚本
4. 更新 README 与 .env.example

Contributing

欢迎 PR / Issue。

• 提交前请确保：
  • 代码可运行
  • 不提交密钥与敏感信息
  • README 与配置说明同步更新
• 建议使用清晰的提交信息与可复现步骤

Security

• 不要提交真实 token/API key 到仓库（包括历史提交）。
• 如果你曾误提交，请立刻：
  1. 在平台侧轮换密钥
  2. 清理 Git 历史（例如 git filter-repo）
  3. 重新推送并通知协作者

Roadmap

• Webhook/多实例部署方案
• 更完善的回归测试（对话行为快照）
• 可视化管理后台
• 更细粒度的策略热更新

License

建议在开源前添加 LICENSE 文件（例如 MIT / Apache-2.0）。
当前仓库若未包含 LICENSE，默认不授予他人使用权。