Files

T

RRRosmontis 34089d0042 Initial import of Shirobana bot backend

Include utility modules, shared channels, prompts, read-only skills, wardrobe memory and regression tests. Externalize legacy credentials and exclude private runtime state.

2026-11-11 00:25:30 +08:00

5.0 KiB

Raw Blame History

Shirobana Bot · 白花

统一 Telegram / 可选 QQ 桥的 utility bot 后端，包含多模态聊天、受权限控制的工具循环、持久通知、定时提醒、用户记忆、笔记本、私人衣柜和只读 Agent Skills。

bot-utility/：主入口、业务模块、提示词、技能加载器。
根目录 channel.py、tg_channel.py、qq_channel.py、identity.py：共享通道和统一身份。
tests/：隔离回归测试，不需要真实邮箱密码或模型 API Key。
mail-bridge/：独立邮件桥源代码。hMailServer COM 相关功能需另行在 Windows 部署，不由 bot 主入口自动启动。
bot-utility.service：可调整的 systemd 部署模板，不是生产服务器的私有配置。

安装与配置

建议 Python 3.12。锁定依赖来自当前运行环境：

python3 -m venv bot-utility/.venv
bot-utility/.venv/bin/pip install -r bot-utility/requirements.lock
cp bot-utility/settings.example.json bot-utility/settings.json

在本地私有 settings.json 中设置 Telegram token、可选代理及管理员 ID。聊天模式默认普通用户 command、管理员 chat、群聊 command；已保存的用户设置优先。媒体下载模块如需本地代理端口列表，可将 bot-utility/proxies.example.json 复制为私有 bot-utility/proxies.json 并按实际代理配置填写；不要上传真实代理配置。

将 .env.example 复制到仓库外的受限环境文件，例如 /etc/shirobana-bot/bot.env，由 systemd 的 EnvironmentFile 加载。程序不会自动读取 .env 文件。 密钥为空的示例不能直接用于生产。权限建议 root:root、0600；不要把真实密钥放进 unit 的可读 Environment= 行或提交到 Git。

# 前台测试：先通过你自己的安全方式导入环境变量，再启动。
cd bot-utility
.venv/bin/python -B main.py

systemd 模板中的用户、目录和环境文件路径需要先调整。代理、OSS/FUSE、Komari、Pixiv 文件服务器、OpenAPI 和邮件桥地址依具体环境配置；部分旧模块保留了现有部署的非秘密域名或目录，迁移部署前应检查。不要为了试运行同时启动两份使用相同 Telegram token 的长轮询实例。

凭据来源

用途	配置
模型调用	`DEEPSEEK_API_KEY`、`MODELSCOPE_API_KEY`
白花 Akaros 邮箱	`AKAROS_MAIL_API_KEY`
Komari 旧式密码登录	`KOMARI_PASSWORD`；既有 `komari/setting.json` API Key 方式仍兼容
Pixiv 文件服务器上传	`PIXIV_CF_PASSWORD`
直播回调认证	`BOT_SRS_CALLBACK_SECRET`
Linux bot 访问邮件 COM HTTP 桥	`MAIL_COM_TOKEN_FILE` 指向私有 token 文件
独立 mailWeb 程序	`HMAIL_ADMIN_PASSWORD`、`MAIL_REGISTER_AUTH_CODE`、`MAIL_FLASK_SECRET_KEY`
独立 COM 桥	`MAIL_COM_CONFIG` 指向私有 `com-private.json`；参考 `mail-bridge/com-private.example.json`

Komari/Pixiv 未提供对应凭据时，不会回退到内置密码。mailWeb 的 Flask 签名密钥未配置时每次启动随机生成，持久会话部署应设置稳定的私有密钥。仓库中保留的 SSO 加密/CSRF 协议常量并不是用户密码。

Windows 邮件 Web/MCP 附加服务使用 Flask-CORS、MCP SDK 等额外依赖，COM 服务还需要 pywin32/hMailServer；Linux bot 的依赖锁不是这些独立服务的完整部署清单。

功能说明

私聊和群聊身份隔离；权限由执行器验证，不由模型自行授权。
多轮工具执行，累计结果摘要，衣柜同轮重复新增保护。
持久化定时提醒、通知投递重试及去重；异常情况下为至少一次投递，不承诺绝对 exactly-once。
长期记忆、备忘录、Todo、每用户独立的衣柜；衣柜默认白色连衣裙，不向群聊提供私人库存。
原生多模态输入与全局贴纸场景库。
只读语言 Skill：见 bot-utility/skills/README.md。默认白名单为空；不执行 Skill 脚本或允许其改变工具权限。
衣柜收尾使用独立纯文本润色，不将内部记录 JSON 直接作为聊天内容。
/my、/setting、/help 是 Telegram 菜单入口。

测试

PYTHONDONTWRITEBYTECODE=1 bot-utility/.venv/bin/python -m unittest discover -s tests -v

测试使用临时目录及 mock；不要将测试数据或测试配置替换成生产数据。发布前应在独立 checkout 运行测试，避免导入时创建的状态文件污染运行目录。

数据与安全边界

此仓库仅保存代码、默认提示词和无凭据模板，不包括用户账号映射、TG token、API Key、聊天历史、记忆/衣柜数据库、邮件、白果云账号密码、贴纸文件、下载缓存、日志、备份和虚拟环境。

.gitignore 是防误提交措施，不代替内容审查。新增文件或发布前仍应扫描硬编码密钥，特别是嵌套配置和历史测试样本。生产业务状态可能包含明文敏感数据，应限制文件权限并自行加密备份；现有审计行为未因本次源码发布整体重构。

5.0 KiB Raw Blame History Unescape Escape