智睦云打印
当用户希望通过智睦云打印服务完成打印相关操作时，使用此技能。
本技能支持：
- 查询可用打印机
- 上传本地文件
- 创建漫游打印任务
- 直接打印到指定设备
- 更新已有打印任务的单双面设置
- 更新已有打印任务的颜色设置
- 更新已有打印任务的份数设置
- 更新已有打印任务的纸张设置
使用前检查
- 运行环境需要
Python 3.10+ - 首次使用前先安装依赖：
pip install -r requirements.txt
- 要求用户先通过官方 OAuth 页面获取访问令牌。官方 OAuth 地址：
https://any.webprinter.cn/get-ai-server-token
- 令牌必须配置到环境变量
WEBPRINTER_ACCESS_TOKEN - 首次执行打印相关操作前，先运行：
python scripts/mcp_client.py check-install-progress
如果返回：
- hasClient: false：停止后续打印操作，提示用户先安装并绑定官方智睦云打印客户端（访问 https://any.webprinter.cn 下载）
- hasDevice: false：停止后续打印操作，提示用户先共享或绑定打印机
依赖文件：
- requirements.txt，当前依赖为 requests>=2.31.0
安全边界
直接打印和创建漫游打印任务，只接受两类输入来源：
- 用户指定的本地文件
- 用户明确提供的
http://或https://文档链接，且链接内容必须能被智睦云打印服务器访问
额外限制：
- 拒绝
localhost、.local等本地地址 - 如果 URL 指向内网地址，要提醒用户该地址必须可被打印服务访问
- 不要为了“验证链接”主动下载、抓取或打开用户给出的远程文档内容；把原始 URL 直接传给智睦云 API
- 更安全的默认路径：本地文件先上传，再使用上传结果中的
https://any.webprinter.cn/...地址 - 如果用户提供的远程链接域名看起来可疑，先提醒风险，再由用户确认是否继续
交互动作
保留以下动作和默认决策，不要随意改变。
1. 创建漫游打印任务
触发条件：
- 用户说“打印这个文件/链接”
- 用户没有明确指定具体打印机
默认行为：
- 这是默认打印方式
- 不需要先查询打印机详情
- 需要根据打印机能力参数中的默认值设定初始打印参数，不要主动提示用户修改打印参数
执行步骤：
1. 如果输入是本地文件，先执行 upload-file
2. 然后创建漫游任务：
python scripts/mcp_client.py create-roaming-task --file-name "document.pdf" --url "https://any.webprinter.cn/files/abc123/document.pdf" --media-format PDF
2. 直接打印到指定设备
触发条件：
- 用户明确说“直接打印”
- 例如“直接打印”“用 XX 打印机打印”“直接打印到 XX”
执行步骤：
1. 先查询打印机列表：
python scripts/mcp_client.py query-printers
- 如果用户指定的打印机模糊或不在打印机列表中，则列出所有可用打印机（过滤
hidden=true的数据），请用户确认 - 如果输入是本地文件，先上传
- 当明确了打印机，并拿到文档 URL 后，再执行直接打印：
python scripts/mcp_client.py print-document --file-name "report.pdf" --url "https://any.webprinter.cn/files/abc123/report.pdf" --media-format PDF --device-name "HP LaserJet Pro" --control-sn "SERVER123456"
3. 查询打印机能力
只在用户明确提出时调用，例如：
- “查询打印机能力”
- “这台打印机支持彩色/双面/多份打印吗”
执行命令：
python scripts/mcp_client.py query-printer-detail --printer-name "HP LaserJet Pro" --share-sn "SERVER123456"
4. 更新打印参数
只在用户明确提出时调用。
修改单双面时，例如：
- “设置双面打印”
- “改单面打印”
执行命令：
python scripts/mcp_client.py update-printer-side --task-id "TASK_20240324_001" --side DUPLEX
支持值：
ONESIDEDUPLEXTUMBLE
修改颜色时，例如：
- “改成彩色打印”
- “改成黑白打印”
执行命令：
python scripts/mcp_client.py update-printer-color --task-id "TASK_20240324_001" --color COLOR
支持值：
COLORMONOCHROME
修改份数时，例如：
- “打印 3 份”
- “改成 2 份”
执行命令：
python scripts/mcp_client.py update-printer-copies --task-id "TASK_20240324_001" --copies 3
支持值：
1-99
修改纸张时，例如：
- “改成 A4”
- “纸张设成 A3”
- “设置纸张宽 210 高 297”
执行命令：
python scripts/mcp_client.py update-printer-paper --task-id "TASK_20240324_001" --paper-size A4
或：
python scripts/mcp_client.py update-printer-paper --task-id "TASK_20240324_001" --width 210 --height 297
内置纸型转换规则（单位：毫米）：
A3->297 x 420A4->210 x 297A5->148 x 210B4->250 x 353B5->176 x 250LETTER->215.9 x 279.4LEGAL->215.9 x 355.6TABLOID->279.4 x 431.8
如果用户说的是纸型名称，优先自动转换成 paper.width 和 paper.height 后再调用接口。
核心规则
- 用户未明确说“直接打印到指定设备”时，默认创建漫游打印任务
- 只要是用户明确提供的可访问 HTTPS 文档链接，就直接使用原始链接，不主动下载或中转
- 只有本地文件才需要先上传；远程链接不需要先下载再上传
query-printer-detail、update-printer-side、update-printer-color、update-printer-copies、update-printer-paper仅在用户明确要求时调用update-printer-side只负责单双面；颜色和份数必须分别使用独立动作更新- 用户说
A3、A4等纸型时，不要把纸型名称原样传给后端；先转换成毫米单位的paper.width和paper.height - 在 WebPrinter 体系里，打印设备的唯一定位信息应以“打印机名称 + 服务端标识”为准；服务端标识可能表现为
sn、shareSn或controlSn，应结合接口返回字段使用
动作映射
| 用户表达 | 输入类型 | 调用动作 | 说明 |
|---|---|---|---|
| “上传这个文件” | 本地文件 | upload-file |
仅上传文件 |
| “打印这个链接：https://...” | URL 链接 | create-roaming-task |
默认进入漫游打印 |
| “打印这个文件”且未指定打印机 | 本地文件 | upload-file + create-roaming-task |
默认打印路径 |
| “用 XX 打印机打印” | 本地文件或 URL 链接 | query-printers + upload-file（仅本地文件）+ print-document |
直接打印到指定设备 |
| “查询打印机能力” | - | query-printer-detail |
按需调用 |
| “设置双面打印” | - | update-printer-side |
只更新单双面 |
| “改成彩色打印” | - | update-printer-color |
只更新颜色 |
| “打印 3 份” | - | update-printer-copies |
只更新份数 |
| “改成 A4” | - | update-printer-paper |
纸型先转宽高再更新 |
接口与命令
服务信息：
- 域名：
https://any.webprinter.cn - 认证方式：
Authorization: Bearer <token> - 环境变量：
WEBPRINTER_ACCESS_TOKEN
1. 检查安装状态
- 路径：
POST /openapi/platform/checkInstallProgressMCP - 命令：
python scripts/mcp_client.py check-install-progress
2. 查询打印机列表
- 路径：
POST /openapi/control/queryPrinters - 命令：
python scripts/mcp_client.py query-printers
3. 上传本地文件
- 路径：
POST /openapi/mcpClient/uploadFileMCP - 命令：
python scripts/mcp_client.py upload-file --file-path "C:/path/to/document.pdf"
4. 创建漫游打印任务
- 路径：
POST /openapi/task/createRoamingTask - 命令：
python scripts/mcp_client.py create-roaming-task --file-name "document.pdf" --url "https://any.webprinter.cn/files/abc123/document.pdf" --media-format PDF
- 返回值是任务 ID 字符串，脚本会统一包装为：
{
"success": true,
"taskId": "TASK_20240324_001"
}
5. 查询打印机能力
- 路径：
POST /openapi/control/queryPrinterDetail - 命令：
python scripts/mcp_client.py query-printer-detail --printer-name "HP LaserJet Pro" --share-sn "SERVER123456"
6. 更新单双面
- 路径：
POST /openapi/task/config/updatePrinterSideMCP - 命令：
python scripts/mcp_client.py update-printer-side --task-id "TASK_20240324_001" --side DUPLEX
7. 更新颜色
- 路径：
POST /openapi/task/config/updatePrinterColorMCP - 命令：
python scripts/mcp_client.py update-printer-color --task-id "TASK_20240324_001" --color COLOR
8. 更新份数
- 路径：
POST /openapi/task/config/updatePrinterCopiesMCP - 命令：
python scripts/mcp_client.py update-printer-copies --task-id "TASK_20240324_001" --copies 2
9. 更新纸张
- 路径：
POST /openapi/task/config/updatePrinterPaperMCP - 命令：
python scripts/mcp_client.py update-printer-paper --task-id "TASK_20240324_001" --paper-size A4
或：
python scripts/mcp_client.py update-printer-paper --task-id "TASK_20240324_001" --width 210 --height 297
10. 直接打印到指定设备
- 路径：
POST /openapi/task/directPrintDocumentMCP - 命令：
python scripts/mcp_client.py print-document --file-name "report.pdf" --url "https://any.webprinter.cn/files/abc123/report.pdf" --media-format PDF --device-name "HP LaserJet Pro" --control-sn "SERVER123456"
支持格式
HTML、PNG、JPG、PDF、BMP、WEBP、WORD、EXCEL、PPT、TEXT、WPS、ODF、ODT、ODS、ODP、ODG、XPS、PWG
错误处理
常见错误：
401：令牌缺失或失效403：账户没有访问该资源的权限404：接口路径或资源不存在5xx：服务端异常
排查顺序：
1. 环境变量 WEBPRINTER_ACCESS_TOKEN 是否已配置
2. 链接是否是服务端可访问的有效 HTTPS URL
3. 文件路径是否真实存在且是文件
4. 打印机名称和 control-sn 是否来自 query-printers 的返回结果
资源
- 客户端脚本：
scripts/mcp_client.py
