一句话，办完一堆事

对话式办公文件智能体平台 — 在聊天窗口用自然语言下达指令、拖入文件， 系统路由到专职智能体执行批量文件处理，以任务卡片返回进度与产物。

llm-agent · office-automation · batch-file-processing · fastapi · react · celery · qwen

功能特性 · 运行截图 · 快速开始 · 部署指南 · 二次开发 · 路线图

---

💡 它解决什么问题

行政、HR、财务、法务每天都在做重复的文件杂务：批量改名、Word 转 PDF、合并 30 个部门的 Excel、给整批合同加水印……这些活单个都不难，难的是量大、易错、无聊。

OfficePilot 的核心闭环：对话 → 任务 → 预览确认 → 产物。

「把这 120 个文件按 日期_部门_原名 批量重命名」 + 拖入文件
        │
        ▼
  意图路由（PilotAgent / LLM） ──► 生成结构化 TaskSpec
        │
        ▼
  专职执行智能体 preview() ──► 预览对照表，等待你确认
        │ 确认
        ▼
  Celery Worker 逐项执行（幂等） ──► 任务卡片实时进度 ──► 产物打包下载

三条产品红线贯穿始终：预览必须准确、高危操作必须二次确认、产物永远是副本（绝不覆盖原件）。

✨ 功能特性

V1.0 已上线（8 类能力）

能力	说明
🏷️ 批量重命名	前缀/后缀/替换/正则/序号/日期，预览对照表后执行
📄 格式转换	Word / Excel / PPT / 图片 → PDF（LibreOffice headless）
🗜️ PDF 压缩	三档压缩，执行前后体积对比
💧 PDF 水印	文字水印批量应用
📝 文档总结	一句话 / 要点 / 结构化三种模式（LLM）
📊 表格合并	多表纵向合并，行数对账防丢数据
✂️ 表格拆分	按列取值拆分为多文件 / 多 Sheet
🧹 数据清洗	去重 / 去空行 / 格式统一

平台能力

• 💬 对话工作台 — 自然语言 + 拖拽文件，@ 可指定智能体，意图由 LLM 路由
• 🗂️ 任务中心 — 任务卡片实时进度（WebSocket），失败条目明细，产物打包下载
• 📁 文件中心 — 上传 / 产物 / 回收站分区，预签名直传 MinIO
• 🛠️ 工具页直达 — 不想打字？每类能力都有表单化入口
• 🔐 安全设计 — JWT + 刷新轮换、登录限流、高危操作强制确认、凭据信封加密
• 🤖 双 Provider 抽象 — 千问（DashScope）为主、Claude 可切换，所有 LLM 调用经 AIGateway，结构化输出 Pydantic 校验 + 重试

📸 运行截图

登录	对话工作台

工具中心	任务中心	文件中心

🏗️ 架构总览

flowchart LR
    U[浏览器<br/>React 18 + AntD 5] -->|REST /api/v1| A[FastAPI]
    U <-->|WebSocket 进度| A
    A --> P[(PostgreSQL 16)]
    A --> R[(Redis 7)]
    A -->|预签名直传| M[(MinIO / S3)]
    A -->|TaskSpec| Q[Celery 队列<br/>interactive / batch]
    Q --> W[Worker · ExecutorAgent]
    W --> M
    W --> L[LibreOffice headless<br/>PyMuPDF / pikepdf / pandas]
    A & W -->|AIGateway| G{{LLM Provider<br/>千问 DashScope / Claude}}

Loading

层	选型
前端	React 18 · TypeScript · Vite · Ant Design 5 · Zustand · Tailwind
后端	FastAPI · SQLAlchemy 2 (async) · Alembic · Celery
存储	PostgreSQL 16 · Redis 7 · MinIO
文档引擎	LibreOffice (headless) · PyMuPDF · pikepdf · pandas / openpyxl
LLM	千问（百炼 DashScope）为主，Claude 备选，经 AIGateway 双 Provider 抽象

详见 TECH-SPEC.md（架构与表设计）与 docs/adr/（关键技术决策记录）。

🚀 快速开始

依赖：Python 3.12 · Node 20 · Docker Desktop · uv

git clone https://github.com/topbat/officepilot.git
cd officepilot

# 1. 启动基础设施（Postgres :5433 / Redis / MinIO / ClamAV / LibreOffice）
docker compose -f deploy/docker-compose.dev.yml up -d

# 2. 后端
cd backend
uv sync                               # 安装依赖
cp .env.example .env                  # 按需修改（LLM 能力需填 DASHSCOPE_API_KEY）
uv run alembic upgrade head           # 建表
uv run uvicorn app.main:app --reload  # API :8000（Swagger: /api/docs）
uv run celery -A app.workers worker -Q interactive,batch -l info  # Worker（执行任务必需）

# 3. 前端
cd ../frontend
npm i
npm run dev                           # :5173，/api 自动代理到 :8000

打开 http://localhost:5173 注册账号即可体验。不配置 DASHSCOPE_API_KEY 时，对话路由不可用，但工具页表单入口可正常使用全部文件处理能力。

测试

cd backend
uv run pytest      # 单元测试独立可跑；基础设施在线时自动附带集成测试

📦 部署指南

单机 Docker 部署（推荐起步）

1. 基础设施：以 deploy/docker-compose.dev.yml 为底本复制一份 docker-compose.prod.yml，为 Postgres / MinIO 挂持久卷并改掉默认口令。

2. 后端：任何支持 Python 3.12 的环境均可运行：

   cd backend && uv sync --frozen
   uv run alembic upgrade head
   uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
   uv run celery -A app.workers worker -Q interactive,batch -l info --concurrency 4

3. 前端：cd frontend && npm ci && npm run build，产物在 frontend/dist/，用 Nginx 托管并将 /api 反向代理到后端 8000 端口。

生产环境检查清单

• JWT_SECRET 换成 ≥32 字节随机值；CRED_MASTER_KEY 配置信封加密主密钥
• DATABASE_URL / S3_* 指向生产实例，MinIO 换掉默认凭据
• CORS_ORIGINS 只允许生产域名；全站 HTTPS
• DASHSCOPE_API_KEY（国内）或 ANTHROPIC_API_KEY + AI_PROVIDER=claude（海外）
• ClamAV 上传扫描、MinerU 高质量解析按需启用（CLAMAV_* / DOCPARSER_MINERU_URL）
• 环境变量全量清单见 backend/.env.example（与 TECH-SPEC §8.2 一一对应）

性能基线（PRD 验收标准）：对话首响 ≤2s；500 文件重命名 ≤30s；20MB 文档转 PDF ≤15s。

🔧 二次开发指南

仓库结构

backend/
  app/
    api/          # FastAPI 路由（auth / chat / files / tasks / ws）
    agents/       # 智能体：base.py 基类 + registry.py 注册表 + 各能力包
    ai/           # AIGateway 与双 Provider 适配（qwen / claude）
    engines/      # 文档引擎封装（LibreOffice / PDF / 表格）
    services/     # 业务服务层（任务状态机、文件、认证）
    models/       # SQLAlchemy 模型
    workers/      # Celery 应用与任务
    core/         # 配置 / DB / Redis / 错误码
  alembic/        # 数据库迁移
  tests/          # pytest（单元 + 集成，集成测试基础设施不可达时自动 skip）
frontend/
  src/
    pages/        # 页面（auth / chat / files / tasks / tools）
    components/   # 复用组件
    api/          # axios 封装
    stores/       # Zustand 状态
deploy/           # docker-compose 与部署配置
docs/adr/         # 架构决策记录（ADR-001 ~ 006）

新增一个执行智能体（最常见的扩展）

1. 新建 backend/app/agents/<your_agent>/agent.py，继承 ExecutorAgent（见 base.py）：

   from app.agents.base import ExecutorAgent, PreviewResult
   
   class WatermarkAgent(ExecutorAgent):
       key = "watermark"
       dangerous_actions = set()      # 高危 action 列入后强制二次确认
       queue = "batch"
   
       def preview(self, task, params, input_file_ids) -> PreviewResult:
           """展开条目清单 + 生成用户可核对的预览摘要"""
   
       def execute_item(self, task, item_id, item_input) -> dict:
           """执行单条目。必须幂等：以 item_id 为幂等键"""

2. 在 registry.py 的 _bootstrap() 中注册。

3. 参数用 Pydantic 模型定义并校验；若要让对话路由识别新能力，在 PilotAgent 的路由提示词中登记（app/agents/pilot.py）。

4. 补一条单元测试（参考 tests/test_rename_rules.py），前端在 src/pages/tools 加表单入口。

必须遵守的工程约束

• LLM 调用只能经 app/ai 的 AIGateway，结构化输出必须 Pydantic 校验 + 失败重试 — 不允许绕过直连 SDK
• 高危操作必须进入 awaiting_confirm 状态、无旁路；产物永远是副本，不覆盖原件
• UI 颜色 / 字号 / 圆角只用 UI-SPEC.md 定义的 Token；智能紫仅用于 AI 时刻，活力橙仅用于进度与庆祝
• 数据库变更一律走 Alembic：uv run alembic revision --autogenerate -m "..."
• 需求事实源：PRD.md · TECH-SPEC.md · UI-SPEC.md，实现与文档冲突时以文档链为准

🗺️ 路线图

版本	范围	目标
✅ V1.0（MVP）	对话工作台 + 批量重命名 + any→PDF + 文档总结 + 表格合并/拆分 + PDF 压缩/水印 + 任务中心	跑通「对话→任务→产物」闭环，覆盖最高频文件与表格杂活
🚧 V1.5（T+4 月）	批量邮件 · 图片识别与批处理 · 模板批量生成文档 · 文档翻译 · 压缩解压 · 模板库 · 管理后台	补齐分发与生成类能力，形成「处理→生成→分发」链路
🔭 V2.0（T+6 月）	音视频转写纪要 · 文档比对查重 · 敏感信息脱敏 · 智能归档 · 校对规范化 · 跨 Agent 流水线编排 · 定时任务 · 桌面客户端 · 开放 API	从工具集走向办公自动化平台

🤝 贡献

欢迎 Issue 与 PR：

1. Fork 本仓库并创建特性分支（git checkout -b feat/awesome）
2. 提交前确保 uv run pytest 与 npm run build 通过（CI 会同时跑两者）
3. 提交信息遵循 Conventional Commits（feat: / fix: / docs: …）
4. 涉及产品行为的变更请先对齐 PRD.md；架构级决策请补充 ADR

📄 License

本项目基于 MIT License 开源。

_{智办通 · OfficePilot — 把重复的文件杂务交给智能体}