1. 为什么我要在 Mac 和 Windows 上折腾一个 Word 瘦身工具一份带 50 张高清图的投标文件体积能到 80MB 以上。邮件附件超限、网盘上传慢、对方打开卡顿这些场景你应该都遇到过。市面上的压缩工具要么按年收费要么要求把文件传到别人的服务器上处理涉及合同、标书这类内容时隐私风险让人不放心。我想要的其实很简单一个能在 Mac 和 Windows 上都能跑的桌面小工具把 .docx 里的图片智能压缩、必要时还能按段落拆分成多个子文档全程本地处理不联网上传。问题在于我并不是专业桌面开发PyQt6 的跨平台打包、python-docx 的格式保留、PyInstaller 的双平台构建每一项单独拎出来都要查半天文档。真正让这件事从「想想」变成「30 分钟能跑起来」的是 AI 编程助手。但用 AI 写代码有个前置问题你得先让编辑器里的 AI 能稳定调用模型。我试过在 Cursor、Claude Code 这类工具里分别配不同厂商的 Key切换模型时改配置改到烦。后来统一走 TaoToken 的 API 通道一个 Key 覆盖多个模型Mac 和 Windows 上配置骨架一致省掉了大量重复劳动。这篇就按我实际的操作顺序来先讲清楚这个工具要解决什么、技术栈怎么选再给 TaoToken 的接入配置config.toml 和 settings.json 两套骨架然后是 CC Switch 切换步骤、压缩前后体积对比的验证动作最后把我在双平台上踩过的坑列出来。你跟着做30 分钟内应该能拿到一个可运行的版本。2. 技术选型与 TaoToken 前置准备2.1 为什么是 Python PyQt6 python-docx选型逻辑很直接。Python 生态里处理 Word 的库成熟AI 辅助编码时生成的代码质量也最高PyQt6 提供跨平台原生体验拖拽、进度条这些交互组件齐全图片压缩用 Pillow工业级图像处理支持 PNG、JPEG、BMP 多种格式互转打包用 PyInstaller一条命令出独立可执行文件。关键认知.docx 本质上是一个 ZIP 压缩包。你把 .docx 后缀改成 .zip 再解压会看到这样的结构document.docx (ZIP) ├── [Content_Types].xml ├── _rels/ ├── word/ │ ├── document.xml # 文档正文内容 │ ├── media/ # 所有图片都在这里 │ │ ├── image1.png │ │ ├── image2.jpeg │ │ └── image3.bmp │ └── ... └── ...压缩的核心就是解压 → 遍历 word/media/ 下的图片 → 智能压缩 → 重新打包。理解这一点后面所有代码你都能看懂。2.2 TaoToken 前置拿 Key 与确认通道在写代码之前先把 AI 通道配好否则编辑器里的助手没法稳定工作。步骤不复杂访问官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后进控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。API 基础地址统一用 https://taotoken.net/api 注意这个地址后面不加任何 UTM 参数配置时直接填这个就行。注意Key 只在创建时完整显示一次复制后立刻存到密码管理器或本地环境变量里别直接硬编码进要提交到 Git 的代码。如果你用的是 Claude Code 这类工具接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的详细配置说明。想先验证模型通不通可以直接用模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条测试消息。3. 可复制配置config.toml 与 settings.json 骨架3.1 config.toml 骨架适用于支持 TOML 配置的客户端很多 AI 编程工具用 TOML 做配置。下面这份骨架你可以直接复制把your_api_key_here换成自己的 Key# config.toml - TaoToken 统一接入配置 # 适用于 Mac 与 Windows路径差异见注释 [provider] name taotoken base_url https://taotoken.net/api api_key your_api_key_here # 建议改为从环境变量读取api_key ${TAOTOKEN_API_KEY} [model] # 按需切换统一走同一通道 default claude-sonnet-4-20250514 # 可选gpt-4o、claude-opus-4 等以控制台可用列表为准 [request] timeout_seconds 120 max_retries 3 # 长文档处理时适当调大超时 [workspace] # Mac 示例路径 # project_root /Users/yourname/projects/word-slimmer # Windows 示例路径 project_root D:/projects/word-slimmerMac 和 Windows 的差异主要在路径分隔符和盘符写法。TOML 里 Windows 路径用正斜杠/或双反斜杠\\都行别用单反斜杠会被当转义符。3.2 settings.json 骨架适用于 VS Code / Cursor 系如果你用的是 VS Code 或 Cursor配置走 settings.json。打开命令面板搜「Preferences: Open User Settings (JSON)」加入下面这段{ ai.providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: ${env:TAOTOKEN_API_KEY}, models: [ claude-sonnet-4-20250514, gpt-4o ] } }, ai.defaultProvider: taotoken, ai.defaultModel: claude-sonnet-4-20250514, ai.request.timeout: 120000, editor.formatOnSave: true }这里用${env:TAOTOKEN_API_KEY}从环境变量读 Key比明文写在 JSON 里安全。设置环境变量的方式Mac写入 ~/.zshrc 或 ~/.bash_profileexport TAOTOKEN_API_KEY你的KeyWindowsPowerShell永久生效[System.Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, 你的Key, User)设置完重启终端和编辑器让环境变量生效。3.3 两套配置的对照配置项config.tomlsettings.json说明基础地址base_urlbaseUrl统一为 https://taotoken.net/api密钥api_keyapiKey推荐环境变量注入默认模型model.defaultai.defaultModel按控制台可用列表填超时timeout_secondsai.request.timeout单位不同注意毫秒/秒重试max_retries视客户端支持长任务建议 ≥34. CC Switch 切换步骤与核心压缩代码4.1 CC Switch 切换模型通道CC Switch 是用来在多个模型通道之间快速切换的工具配置好之后不用每次手改配置文件。操作顺序第一步确认 CC Switch 已安装并能读取到你的配置文件路径。Mac 上通常在~/.config/下Windows 在%APPDATA%下。第二步把上面 3.1 的 config.toml 放到 CC Switch 识别的配置目录或者通过它的「导入配置」功能加载。第三步在 CC Switch 界面里选中taotoken这个 provider点「应用」或「切换」。切换成功后当前激活的通道就是 TaoToken。第四步验证切换是否生效在编辑器里让 AI 助手随便生成一段代码如果能正常返回说明通道通了。如果报 401多半是 Key 没读到报超时检查 base_url 是否写成了带 UTM 的地址——API 地址不要带任何查询参数。提示切换后建议重启一次编辑器部分客户端会缓存旧的 provider 配置。4.2 图片智能压缩核心代码压缩不是简单降 JPEG 质量而是多维度策略。下面这段可以直接放进你的项目import io from PIL import Image def compress_image(image_bytes: bytes, filename: str) - bytes: 智能均衡压缩在清晰度和体积之间找最优平衡 img Image.open(io.BytesIO(image_bytes)) # 策略1大尺寸图片等比缩放超过 1920px 的按比例缩小 max_dimension 1920 if max(img.size) max_dimension: ratio max_dimension / max(img.size) new_size (int(img.width * ratio), int(img.height * ratio)) img img.resize(new_size, Image.LANCZOS) # 策略2统一转 JPEGPNG/BMP 转 JPEG 通常能减 60-80% if img.mode in (RGBA, P): img img.convert(RGB) # 策略3渐进式质量搜索找到满足目标体积的最高质量 target_size len(image_bytes) * 0.4 # 目标压到原始的 40% buffer io.BytesIO() for quality in range(85, 30, -5): buffer io.BytesIO() img.save(buffer, formatJPEG, qualityquality, optimizeTrue) if buffer.tell() target_size: return buffer.getvalue() return buffer.getvalue()三个技术点值得记一下Lanczos 重采样在缩放时保持最佳视觉质量避免模糊和锯齿渐进式质量搜索从高到低尝试确保满足体积要求的前提下清晰度最高格式统一转换把无损的 PNG 转成 JPEG肉眼几乎看不出差异但体积大幅下降。4.3 文档拆分保留格式的段落级分割拆分的难点不在「分」而在保留字体、样式、页眉页脚、编号列表。用 python-docx 逐段复制import math from docx import Document def split_document(doc_path: str, num_parts: int): 按段落均匀拆分为 N 个子文档保留完整格式 doc Document(doc_path) paragraphs doc.paragraphs total len(paragraphs) chunk_size math.ceil(total / num_parts) output_files [] for i in range(num_parts): new_doc Document() start i * chunk_size end min(start chunk_size, total) for para in paragraphs[start:end]: new_para new_doc.add_paragraph() new_para.style para.style new_para.paragraph_format.alignment para.paragraph_format.alignment for run in para.runs: new_run new_para.add_run(run.text) new_run.bold run.bold new_run.italic run.italic new_run.font.size run.font.size new_run.font.name run.font.name output_path f{doc_path.rsplit(., 1)[0]}_part{i1}.docx new_doc.save(output_path) output_files.append(output_path) return output_files4.4 跨平台差异处理Mac 和 Windows 的差异集中在字体、文件管理器调用、图标格式三处import platform import subprocess IS_WINDOWS platform.system() Windows IS_MACOS platform.system() Darwin # 字体适配 if IS_WINDOWS: font_family Microsoft YaHei UI elif IS_MACOS: font_family PingFang SC # 在文件管理器中定位文件 def open_in_explorer(path): if IS_WINDOWS: subprocess.run([explorer, /select,, path]) elif IS_MACOS: subprocess.run([open, -R, path]) # 图标格式 icon_ext .ico if IS_WINDOWS else .icns5. 验证请求与压缩前后体积对比5.1 先验证 AI 通道是否通在正式跑压缩之前先确认 TaoToken 通道能正常返回。用 curl 发一条最小请求curl https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: 回复 OK 两个字母}], max_tokens: 10 }返回里能看到content: OK就说明通道正常。如果返回 401检查环境变量是否在当前终端生效echo $TAOTOKEN_API_KEY返回 404检查 base_url 是否多写了路径或参数。5.2 压缩效果验证动作拿一份真实的带图文档测试。我用的是一份 87.3MB、含 50 张高清图的投标文件跑完压缩后对比指标压缩前压缩后效果文件大小87.3 MB12.8 MB减少 85.3%图片质量原始高清视觉无损肉眼无差异处理时间-8.2 秒本地处理图片数量50 张50 张数量不变验证动作分三步第一步压缩前用ls -lhMac或dirWindows记录原始体积第二步跑完压缩后再次记录第三步用 Word 打开压缩后的文档翻到图片密集的页面放大到 200% 对比细节确认没有明显模糊或锯齿。注意如果压缩后文档打不开多半是重新打包 ZIP 时[Content_Types].xml被破坏。确保打包时保留原始 ZIP 内的所有非 media 文件只替换 word/media/ 下的图片。5.3 双平台打包命令Mac 上打包 DMGpyinstaller --windowed --name Word瘦身神器 main.py create-dmg dist/Word瘦身神器.app --overwriteWindows 上打包 EXEpyinstaller --windowed --iconicon.ico --name Word瘦身神器 main.py如果想让一次 git push 同时构建两个平台用 GitHub Actions 的 matrix 策略分别在 macos-latest 和 windows-latest 上跑对应命令即可。6. 本篇常见错排查报错一401 Unauthorized。最常见的原因是 Key 没读到。先echo $TAOTOKEN_API_KEYMac或echo $env:TAOTOKEN_API_KEYWindows确认环境变量存在。如果存在但编辑器仍报 401重启编辑器因为部分客户端只在启动时读一次环境变量。报错二连接超时。检查 base_url 是否写成了https://taotoken.net/api不要在后面加/v1或其他路径也不要带任何查询参数。API 地址就是干净的https://taotoken.net/api。报错三压缩后图片变模糊。说明质量搜索的下限设得太低。把range(85, 30, -5)里的 30 调高到 50或者把target_size从 0.4 调到 0.6给清晰度留更多余量。报错四Windows 上路径报错。TOML 或 JSON 里的 Windows 路径用正斜杠/比如D:/projects/word-slimmer。用单反斜杠会被当转义符导致路径解析失败。报错五PyInstaller 打包后运行闪退。多半是缺少隐藏依赖。在打包命令里加--hidden-importPIL._tkinter_finder或把 Pillow 的插件显式声明。Mac 上还要注意签名问题未签名的 .app 首次打开需要在「系统设置-隐私与安全性」里手动允许。报错六CC Switch 切换后不生效。检查 CC Switch 读取的配置路径是否和你实际编辑的文件一致。Mac 和 Windows 的默认配置目录不同切换工具里一般有「打开配置目录」的入口点进去确认文件确实在那里。排障和接入相关的细节接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里有更完整的说明Key 的管理和重新生成在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你打算长期用 AI 做编码和 Agent 类任务可以看下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 按用量规划比单次调用更划算。想先快速验证模型效果直接去模型对话页 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 发一条消息就行。最后说个我踩过的坑第一次跑压缩时忘了处理 RGBA 透明通道PNG 转 JPEG 直接报错。后来在img.convert(RGB)之前先判断img.mode in (RGBA, P)问题就没了。你如果遇到类似报错先看图片模式再决定转换路径。
