DeBox Auto Reply Bot

This project is a Python bot for DeBox that:

• loads a reply corpus from .xlsx, .csv, or .tsv
• hot reloads the corpus when the source file is saved
• matches incoming messages against the corpus
• returns or sends an automatic reply candidate
• supports reminder-style follow-up logic
• supports DeBox webhook intake and DeBox message sending APIs

It is designed so you can maintain the knowledge base in Excel and let the bot reload it automatically.

Features

• Excel-backed corpus with flexible header detection
• automatic corpus hot reload
• reply suggestion endpoint for local testing
• DeBox webhook adapter
• DeBox private/group send client with request signing
• basic safety gates for auto sending
  • auto-send master switch
  • private/group send switches
  • optional group mention requirement
  • optional group whitelist
  • duplicate-send suppression

Project Layout

app/
  config.py
  corpus.py
  debox_client.py
  main.py
  models.py
  notifier.py
  rules.py
.env.example
requirements.txt
sample_corpus.csv
test.py

Run

From the project root:

python -m app.main

Main Endpoints

• GET /health
• GET /debug/conversations
• GET /corpus/status
• GET /debox/status
• POST /corpus/load
• POST /reply/suggest
• POST /events/debox
• POST /webhooks/debox

Corpus Format

The loader supports flexible header names. The most recommended columns are:

• 问题 or question
• 答案 / 回复 or answer / reply
• optional: 分类 / category
• optional: 优先级 / priority

Example CSV:

问题,回复,分类,优先级
订单什么时候处理,订单已经收到，我这边帮你核对进度，稍后给你具体时间。,订单,1.8
在吗,我在，刚看到你的消息，现在就帮你看。,通用,1.2

The loader also supports sheets where the actual table header is not on the first row.

Auto Reload

Set these values in .env:

CORPUS_PATH=C:/Users/asus/Desktop/百问百答.xlsx
CORPUS_AUTO_RELOAD_ENABLED=true
CORPUS_RELOAD_INTERVAL_SECONDS=3

After that, saving the Excel file is enough. The service will detect the file change and reload the corpus automatically.

Check status:

curl http://127.0.0.1:8000/corpus/status

Local Suggestion Test

curl -X POST http://127.0.0.1:8000/reply/suggest ^
  -H "Content-Type: application/json" ^
  -d "{\"text\":\"大象社区的核心定位是什么\"}"

DeBox Integration

When you are ready to connect a real DeBox bot, configure:

DEBOX_APP_ID=
DEBOX_API_KEY=
DEBOX_APP_SECRET=
DEBOX_WEBHOOK_KEY=
DEBOX_BOT_USER_ID=
DEBOX_AUTO_SEND_ENABLED=false
DEBOX_PRIVATE_REPLY_ENABLED=true
DEBOX_GROUP_REPLY_ENABLED=false
DEBOX_REQUIRE_GROUP_MENTION=true
DEBOX_GROUP_WHITELIST=
DEBOX_DEDUPE_WINDOW_SECONDS=120

Recommended rollout:

1. Keep DEBOX_AUTO_SEND_ENABLED=false first.
2. Point the DeBox bot webhook to POST /webhooks/debox.
3. Verify the returned auto_reply and debox_auto_send.reason.
4. Turn on DEBOX_AUTO_SEND_ENABLED=true after you trust the matches.
5. Only enable group auto reply after setting DEBOX_GROUP_WHITELIST.

Example webhook payload:

{
  "from_user_id": "user-123",
  "to_user_id": "bot-456",
  "language": "zh",
  "group_id": "",
  "message": "大象社区的核心定位是什么",
  "mention_users": [],
  "message_raw": "大象社区的核心定位是什么"
}

Notes

• .env is intentionally excluded from git.
• Local Excel corpus files are also ignored by git to avoid leaking private data.
• Use .env.example as the safe template for public repositories.