# 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。锁定依赖来自当前运行环境：

```bash
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。

```bash
# 前台测试：先通过你自己的安全方式导入环境变量，再启动。
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 菜单入口。

## 测试

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

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

## 数据与安全边界

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

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