mineru-tianshu: Instructions file for Codex

AGENTS.md — MinerU Tianshu（天枢）

本文件面向 AI 编码代理，介绍本项目的架构、命令与开发约定。 项目文档、代码注释、日志输出以简体中文为主，修改现有文件时请保持中文注释风格。

项目概述

MinerU Tianshu（天枢）是一个企业级 AI 数据预处理平台，将非结构化数据转换为 AI 可用的结构化格式（Markdown + JSON）：

• 📄 文档：PDF、Word、Excel、PPT（MinerU 原生解析 DOCX/PPTX；旧版 .doc/.ppt 经 LibreOffice 转换）、Excel .xlsx/.xls 与 HTML/TXT/CSV/EPUB（MarkItDown）、ZIP 压缩包（自动解包为父子任务批量解析）
• 🖼️ 图片：JPG、PNG、BMP、TIFF（多 OCR 引擎 + 水印去除🧪）
• 🎙️ 音频：MP3、WAV、M4A、FLAC（SenseVoice 多语言、说话人识别、情感识别）
• 🎬 视频：MP4、AVI、MKV、MOV、WebM（FFmpeg 音频提取转写 + 关键帧 OCR🧪）
• 🧬 生物格式：FASTA、GenBank（插件化格式引擎）
• 🏗️ 企业特性：GPU 负载均衡、任务队列、JWT 认证、API Key、MCP 协议、RustFS 对象存储

技术栈

项目结构

mineru-tianshu/
├── frontend/                  # Vue 3 前端
│   ├── src/
│   │   ├── api/               # Axios API 客户端（authApi/taskApi/queueApi/systemApi）
│   │   ├── components/        # 组件（MarkdownViewer、JsonViewer、VirtualPdfViewer 等）
│   │   ├── views/             # 页面（Dashboard、TaskSubmit、TaskDetail、Login 等）
│   │   ├── stores/            # Pinia 状态（authStore、taskStore、queueStore 等）
│   │   ├── locales/           # i18n（zh-CN.ts、en-US.ts）
│   │   ├── router/            # Vue Router（含权限路由守卫）
│   │   └── types/ utils/      # TypeScript 类型与工具
│   ├── package.json  vite.config.ts  Dockerfile
│
├── backend/                   # Python 后端（所有服务共用此目录代码）
│   ├── start_all.py           # 统一启动脚本（本地开发入口）
│   ├── api_server.py          # FastAPI API 服务器（端口 8000）
│   ├── litserve_worker.py     # LitServe GPU Worker Pool（端口 8001）
│   ├── task_scheduler.py      # 任务调度器（超时重置、文件清理）
│   ├── mcp_server.py          # MCP 协议服务器（端口 8002，供 Claude Desktop 等调用）
│   ├── task_db.py             # SQLite 任务数据库（启动时原地迁移）
│   ├── redis_queue.py         # Redis 优先级队列（可选，SQLite 自动回退）
│   ├── download_models.py     # 模型预下载脚本
│   ├── auth/                  # JWT 认证、API Key、角色权限、OIDC/SAML SSO
│   ├── mineru_pipeline/       # MinerU 引擎封装
│   ├── audio_engines/         # SenseVoice 音频引擎
│   ├── video_engines/         # 视频引擎（FFmpeg + 关键帧提取，OCR 走 MinerU）
│   ├── format_engines/        # 插件化格式引擎（FASTA、GenBank 为参考实现）
│   ├── remove_watermark/      # 水印去除（YOLO11x + LaMa）
│   ├── image_caption/         # 图片描述（多模态大模型，OpenAI 兼容接口，配置存 system_config 表）
│   ├── webhook/               # Webhook 任务通知（投递表 + HMAC 签名 + SSRF 防护，调度器周期投递）
│   ├── output_normalizer/     # 输出标准化（统一 result.md/result.json/images/）
│   ├── storage/               # RustFS S3 客户端（图片上传、URL 替换）
│   ├── utils/                 # 工具函数
│   ├── requirements.txt       # Python 依赖（版本锁定，含 mineru[all]>=3.4.5）
│   └── Dockerfile  Dockerfile.cpu  Dockerfile.offline  install.sh
│
├── dify_plugin/tianshu/       # Dify 插件（manifest.yaml + provider/ + tools/）
├── setup.sh                   # 一键部署入口（交互式引导 + 非交互参数 --mode/--yes/--dry-run）
├── scripts/                   # 辅助脚本（docker-entrypoint.sh、init-models.sh）
├── docker-compose.yml         # 生产编排（GPU 版，含 vllm-mineru/rustfs 等）
├── docker-compose.dev.yml     # 开发编排（热重载 + debugpy 端口 5678）
├── docker-compose.cpu.yml     # CPU 本地开发（Mac Apple Silicon，需 Rosetta 2）
├── docker-compose.offline.yml # 离线部署编排
├── docker-compose.pipeline.yml# 纯 pipeline 模式部署
├── Makefile                   # Docker 快捷命令
├── pyproject.toml             # Ruff 配置（无 Python 打包用途）
├── .pre-commit-config.yaml    # pre-commit 钩子（唯一 CI 质量门禁）
└── .env.example               # 根环境变量模板（docker-compose 与 Makefile 消费）