内容
# Paperless Genie
一个使用 **Google Antigravity SDK** （`google-antigravity`）为 **Paperless-ngx** 提供服务的AI驱动的Telegram机器人。
[](https://github.com/rabestro/paperless-genie/actions/workflows/ci.yaml)
[](https://www.gnu.org/licenses/agpl-3.0)
`paperless-genie` 作为一个智能的对话式界面，用于您的Paperless-ngx文档存档。它完全以对话式运行，不需要在服务器上挂载本地文件。它支持多用户，通过相应的用户API令牌动态路由到Paperless-ngx。
<p align="center">
<img src="docs/assets/demo.gif" alt="Demo: searching the archive, asking for a yearly utilities total with a follow-up comparison, and auto-archiving a document from a Telegram chat" width="360">
<br>
<sub><i>示例演示 — 一个模拟聊天，包含样本数据，而不是实时实例的记录。</i></sub>
</p>
---
## 🚀 主要功能
* **对话式搜索与查询**：用自然语言询问关于存档的问题（例如， *"查找John Doe的护照"* 或 *"我们有哪些1993年的合同？"*）。机器人将查询路由到一个自主代理，该代理使用Paperless-ngx MCP工具查找答案。
* **总计、比较和后续查询**：由于AI代理处理每个查询，它可以推理一组文档 — *"我们2025年花费了多少公用事业费用？"* — 并且每个用户的对话记忆允许您用后续查询完善答案，例如 *"与2024年相比如何？"*。请参阅[示例查询](docs/examples.md)页面以获取完整的范围（及其诚实的准确性说明）。
* **智能文档归档**：直接在Telegram中上传文档（PDF、JPG、PNG等）。机器人将其下载到内存中，并运行Antigravity代理来分析其内容。代理建议元数据（标题、日期、对应人、类型、标签），通过`post_document` MCP工具上传文档，等待OCR，设置元数据，并在Paperless中写入详细说明。所有响应都自动以您编写的语言发送。
* **多用户安全性和权限**：Telegram用户ID和Paperless API令牌之间的映射确保每个用户只能搜索、查看和编辑他们有权查看的Paperless-ngx中的文档。
* **现代开发者工具**：使用`uv`、`mise`、`ruff`进行格式化/检查，使用`mypy`进行静态类型检查，使用`pytest`进行测试。
---
## 🛠️ 配置和设置
### 1. 环境变量
复制示例文件并填写您自己的值：
```bash
cp .env.example .env
```
`.env.example` 文档了每个变量：
```ini
TELEGRAM_BOT_TOKEN="您的Telegram机器人令牌"
PAPERLESS_URL="https://您的Paperless实例.com"
GEMINI_API_KEY="您的Google AI Studio Gemini API密钥"
# Telegram用户ID与其Paperless API令牌之间的JSON映射
PAPERLESS_USER_TOKENS='{"52966251": "用户1的令牌", "12345678": "用户2的令牌"}'
# 可选 - 留空以使用默认值（gemini-3.1-flash-lite）
#GEMINI_MODEL="gemini-3.1-flash-lite"
```
### 2. 本地环境设置
确保您的机器上已安装 `mise`。
```bash
# 安装Python 3.14和uv
mise install
# 安装项目依赖项（包括开发和文档依赖项组）
uv sync --all-groups
# 设置预提交钩子
uv run pre-commit install
```
机器人通过 [`@baruchiro/paperless-mcp`](https://github.com/baruchiro/paperless-mcp) MCP服务器与Paperless-ngx通信。安装Node.js 24+并在全局范围内预安装确切的已锁定版本，以便机器人可以在`PATH`上找到它（Docker镜像会自动执行此操作）：
```bash
npm install -g @baruchiro/paperless-mcp@2.0.0
```
此版本必须与[Dockerfile](Dockerfile)中的`PAPERLESS_MCP_VERSION`构建参数匹配 — 升级时请同时升级。
### 3. 可用任务（通过 `mise`）
* **运行机器人**：`mise run run`
* **格式化代码**：`mise run format`
* **检查代码**：`mise run lint`
* **类型检查**：`mise run mypy`
* **运行测试**：`mise run test`
---
## 🐳 Docker部署（推荐）
您可以使用Docker和Docker Compose在后台运行机器人。这会自动打包Node.js，以便机器人可以执行基于Node.js的MCP服务器。
### 1. 构建和启动容器
确保您已创建 `.env` 文件，然后运行：
```bash
docker compose up -d --build
```
### 2. 查看日志
```bash
docker compose logs -f
```
---
## 📋 生产部署（systemd）
要在Linux服务器上后台运行机器人，请创建一个systemd服务文件：`/etc/systemd/system/paperless-genie.service`
```ini
[Unit]
Description=Paperless Genie Telegram机器人
After=network.target
[Service]
Type=simple
User=您的Linux用户名
WorkingDirectory=/home/您的Linux用户名/仓库/paperless-genie
ExecStart=/home/您的Linux用户名/仓库/paperless-genie/.venv/bin/python -m paperless_genie
Restart=always
RestartSec=10
EnvironmentFile=/home/您的Linux用户名/仓库/paperless-genie/.env
[Install]
WantedBy=multi-user.target
```
启用并启动服务：
```bash
sudo systemctl daemon-reload
sudo systemctl start paperless-genie
sudo systemctl enable paperless-genie
```
---
## 🔒 隐私和数据流
该机器人处理身份验证令牌和个人文档存档的内容，因此有必要明确说明数据流向哪里。
* **文档发送到Google的Gemini API进行分析。** 当您归档或搜索时，相关文档文本和查询将被发送到Gemini（通过Google Antigravity SDK），以便代理可以提取元数据、编写说明和回答问题。这 **不是** 一个完全本地/离线的设置 — Google的API数据处理条款适用，并且因API层级而异。请记住处理高度敏感的文档。模型可以通过`GEMINI_MODEL`进行配置。
* **机密存储在 `.env` 中** （gitignored）并且永远不会被记录。机器人令牌、Gemini密钥和每个用户的Paperless令牌都存储在进程环境中。
* **每个用户隔离。** 每个Telegram用户都映射到他们自己的Paperless-ngx API令牌，因此用户只能搜索和编辑该令牌允许访问的文档。
* **最小权限子进程。** Paperless MCP服务器作为子进程运行，它只接收Paperless URL和**请求用户的**令牌 — 永远不会接收Telegram机器人令牌、Gemini密钥或其他用户的令牌。
* **不存储任何数据。** 机器人没有数据库。对话历史仅在内存中存储，直到进程生命周期结束（并且 `/clear` 重置它）。上传的文件在内存中处理并直接传递到Paperless-ngx；代理的临时工作空间是一个临时目录，在处理完成后删除。在Docker中，它作为非特权用户运行。
漏洞：请使用私人报告，不要公开问题 — 请参阅 [SECURITY.md](SECURITY.md)。
---
## 🤝 贡献
欢迎贡献！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以获取开发设置、检查套件和工作流程。首次贡献者通过首次拉取请求签署 [Contributor License Agreement](CLA.md)。我们遵循 [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md)；安全问题通过 [private vulnerability reporting](SECURITY.md) 进行，而不是公开问题。
---
## 📝 许可证
该项目在 **GNU Affero General Public License v3.0 (AGPL-3.0)** 下获得许可。有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
这意味着如果您将此机器人的修改版本作为网络服务部署，则必须根据相同的许可证公开您的修改后的源代码。
