内容
# 打印队列应用
公司文档打印队列管理应用 — WinUI MCP 服务器連携
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://dotnet.microsoft.com/download/dotnet/8.0)
## 📋 概要
打印队列应用是一款用于将XLSX/XLS/PDF文件通过拖拽添加到队列，并通过WinUI 3的图形用户界面管理状态，同时打印到公司内部打印机的应用程序。
- **跨平台**: Python部分可在Windows/Mac/Linux上运行
- **WinUI 3 图形用户界面**: Windows本地现代化界面
- **MCP协议**: 通过Model Context Protocol实现灵活的服务器/客户端分离
- **多格式支持**: 支持Excel (XLSX/XLS) 和PDF文件
## 🏗 架构
```
┌─────────────────────────────────────────────────────────┐
│ Python 打印队列应用 (跨平台) │
│ ├── 队列管理 │
│ ├── 文件处理 (openpyxl, xlrd, PyMuPDF) │
│ └── 打印执行 (Windows API / lp) │
│ │ │
│ │ MCP (HTTP 或 stdio) │
│ ▼ │
│ WinUI MCP 服务器 (C# / WinUI 3) │
│ ├── MCP 工具 → WinUI 小部件实现 │
│ └── 图形用户界面窗口托管 │
└─────────────────────────────────────────────────────────┘
```
## ✨ 主要功能
### 队列管理
- 文件拖拽添加
- 队列文件列表显示
- 单个/全部打印操作
- 打印状态实时显示
### 支持文件格式
| 格式 | 库 | 备注 |
|------|-----------|------|
| XLSX | openpyxl | Excel 2007+ |
| XLS | xlrd + xlwt | Excel 97-2003 (遗留) |
| PDF | PyMuPDF | 直接打印或图像化 |
### 打印管道
```
PENDING → PROCESSING → PRINTING → DONE / ERROR
```
## 🚀 快速入门
### 前提条件
- **Python 3.11+**
- **.NET 8 SDK** (使用WinUI 图形用户界面)
- **Windows 10/11** (使用WinUI 图形用户界面或Windows打印API)
### 安装
```bash
# 克隆仓库
git clone https://github.com/nsh1l/print-queue-app.git
cd print-queue-app
# 创建并激活虚拟环境
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
# 安装依赖
pip install -r requirements.txt
```
### 运行方式
#### 图形用户界面模式 (推荐 - Windows)
```bash
# 使用启动器 (自动启动WinUI服务器和Python客户端)
python run_app.py
# 或直接运行
python -m src --gui
```
#### 模拟图形用户界面模式 (Mac/Linux/开发)
```bash
# 使用无需Windows的模拟服务器
python run_app.py --mock
```
#### 命令行模式
```bash
# 从命令行指定文件
python run_app.py --cli report.xlsx invoice.pdf
```
### 环境变量
| 变量 | 说明 | 默认值 |
|------|------|-----------|
| `PRINT_QUEUE_MCP_URL` | MCP服务器URL | `http://localhost:8765` |
| `DOTNET_PATH` | dotnet CLI路径 | `dotnet` |
## 🔧 MCP 工具接口
WinUI服务器公开以下MCP工具:
| 工具 | 说明 |
|--------|------|
| `winui_create_window` | 创建主窗口 |
| `winui_add_drop_zone` | 添加文件拖拽区域 |
| `winui_update_file_list` | 更新队列列表 |
| `winui_add_button` | 添加工具栏按钮 |
| `winui_add_label` | 添加文本标签 |
| `winui_set_status_text` | 更新状态栏文本 |
| `winui_set_progress` | 更新进度条 |
| `winui_poll_events` | 轮询UI事件 |
### 传输协议
- **开发/测试**: stdio (JSON-RPC over stdin/stdout)
- **生产**: HTTP POST `http://localhost:8765/mcp`
## 📁 项目结构
```
print-queue-app/
├── run_app.py # 应用启动器
├── winui_mcp_server.py # WinUI MCP 服务器 (Python)
├── winui_bridge.py # WinUI 桥接 (Windows本地)
├── requirements.txt # Python依赖
├── src/
│ ├── __main__.py # 入口点
│ ├── main.py # 主应用
│ ├── queue_item.py # 队列项定义
│ ├── file_processor.py # 文件处理
│ ├── print_engine.py # 打印引擎
│ ├── winui_client.py # WinUI客户端
│ └── mock_mcp_server.py # 模拟MCP服务器
└── WinUIMCPServer/
├── Program.cs # C#入口点
├── MCPServer.cs # MCP服务器实现
├── MainWindow.xaml.cs # 主窗口
└── PrintQueueApp.WinUI.csproj
```
## 🧪 开发
### 测试
```bash
# 服务器单元测试
python test_server.py
```
### 远程连接
请参考`CONNECTION.md`了解远程服务器连接设置。
```bash
# 连接到远程服务器
python -m src --mock --url http://print.soichi.ro/ --token <token>
```
## ⚠️ 注意事项
- **使用WinUI 图形用户界面** 需要Windows环境
- **Mac/Linux** 请使用 `--mock` 或 `--cli` 模式
- 打印功能依赖于Windows打印机驱动
- Unix/Linux可以使用 `lp` 命令打印
## 📄 许可证
MIT License
## 🤝 贡献
欢迎提交Issue或Pull Request！
## 📞 支持
请在GitHub Issues上提交您的疑问或问题。
