# toolhub

**Repository Path**: ximo-aipc/toolhub

## Basic Information

- **Project Name**: toolhub
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: EPL-1.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-05-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ToolHub

统一工具服务平台，将多个独立工具合并为单个 FastAPI 应用 + Vue3 前端，通过域名自动发现机制注册路由，单端口提供服务。

## 技术栈

- **后端**: Python 3.11 + FastAPI + Uvicorn + Pydantic Settings
- **前端**: Vue 3 + TypeScript + Vite + Tailwind CSS v4 + Vue Router 4
- **文档处理**: Pandoc、python-docx、PyMuPDF、Tesseract OCR
- **AI**: OpenAI 兼容接口（摘要/翻译）、Agno Agent（MD→Word 增强）

## 项目结构

```
toolhub/
├── app/                          # FastAPI 应用
│   ├── main.py                   # 应用入口，域名自动发现 + SPA fallback
│   ├── config.py                 # 全局配置（pydantic-settings）
│   ├── static/                   # 前端构建产物（vite build 输出）
│   └── domains/                  # 业务域名
│       ├── doc/
│       │   ├── md2docx/          # MD → Word
│       │   ├── doc2md/           # Word/PDF → Markdown
│       │   └── doc_summarize/    # 文档摘要与翻译
│       └── ops/
│           └── server_monitor/   # 服务器监控
├── web/                          # Vue3 前端源码
│   ├── src/
│   │   ├── views/                # 页面组件
│   │   ├── components/           # 通用组件
│   │   ├── composables/          # 组合式函数（toast、theme）
│   │   └── utils/                # 工具函数
│   ├── vite.config.ts
│   └── package.json
├── tests/                        # 测试（按域名组织）
├── Dockerfile                    # 多阶段构建
├── docker-compose.yml
├── .dockerignore
├── pyproject.toml
└── .env                          # 环境变量
```

## 工具说明

### MD → Word (`/doc/md2docx`)

Markdown 转 Word 报告。支持 Pandoc 模板、多种报告样式（默认/商务/调研）、自定义 Word 样式配置、Agno Agent 增强处理。

- `POST /doc/md2docx/api/v1/convert` — JSON 提交 Markdown，返回 docx 文件
- `POST /doc/md2docx/api/v1/convert-file` — 上传 .md 文件，返回 docx 文件
- `GET /doc/md2docx/templates` — 获取可用模板列表

### Word/PDF → Markdown (`/doc/doc2md`)

将 Word 或 PDF 文档转换为 Markdown。支持标题、表格、图片、列表、代码块保留，PDF 含 Tesseract OCR fallback。

- `POST /doc/doc2md/convert` — 上传 .docx/.pdf 文件，返回 Markdown JSON

### 文档摘要与翻译 (`/doc/doc-summarize`)

基于大模型的文档处理服务，支持文本摘要和多语言翻译（中/英/日/韩）。使用 OpenAI 兼容接口。

- `POST /doc/doc-summarize/summarize/json` — 文本摘要
- `POST /doc/doc-summarize/translate/json` — 文本翻译

### 服务器监控 (`/ops/server-monitor`)

实时系统指标监控面板，展示 CPU、内存、磁盘、网络、系统负载。5 秒自动刷新。

- `GET /ops/server-monitor/metrics` — 获取系统指标 JSON

## 部署

### Docker 部署（推荐）

```bash
# 构建并启动
docker compose up -d --build

# 查看日志
docker compose logs -f

# 停止
docker compose down
```

访问 `http://localhost:10080`。

Dockerfile 采用多阶段构建：`node:22-alpine` 编译前端 → `python:3.11-slim` 运行后端（内置 pandoc + tesseract）。

### 本地开发

```bash
# 后端
pip install -e .
uvicorn app.main:app --port 10080 --reload

# 前端（另一个终端）
cd web
npm install
npm run dev
# Vite dev server 默认 http://localhost:5173，自动代理 API 到 10080
```

前端开发时 API 请求通过 Vite proxy 转发到后端。`npm run build` 将产物输出到 `app/static/`，由 FastAPI 直接托管。

### 环境变量

在 `.env` 文件中配置（参考 `.env.example`）：

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `DEBUG` | 调试模式 | `false` |
| `API_KEY` | API 认证密钥（为空则不鉴权） | — |

## 架构说明

**域名自动发现**: `app/main.py` 启动时扫描 `app/domains/<group>/<domain>/router.py`，自动注册 FastAPI 路由，前缀为 `/{group}/{domain}`（下划线转连字符）。

**SPA 部署**: 前端构建产物放在 `app/static/`，FastAPI 挂载 `/assets` 静态文件，其余非 API 路径 fallback 到 `index.html`（Vue Router history mode）。

**新增工具**: 在 `app/domains/` 下创建 `<group>/<domain>/router.py` 导出 `router`，在 `web/src/views/` 添加对应页面并注册路由即可。