zilong-wps — WPS Office COM 自动化引擎

通过 COM 接口程序化操控本机 WPS Office（文字 Writer / 表格 ET / 演示 Presentation），核心能力是 JSON 数据驱动 PPT 一键生成：搜数据 → 出图表 → 写 JSON → 产出 PPTX+PDF 双格式。

环境与 Python 解释器

使用装有 pywin32 的 Python 3.10+（Windows）。先检测、缺失再安装：

python -c "import win32com.client" 2>/dev/null || pip install pywin32

下文命令中的 python 一律指该解释器。若环境里存在多个 Python，优先选已装 pywin32 的那个。

首次使用或报错时，先跑自检脚本确认链路：

python <skill_dir>/scripts/env_check.py

自检项：Windows 系统 / WPS 安装路径 / pywin32 / 三大 COM ProgID（KWPS=文字, KET=表格, KWPP=演示）注册状态。

三条使用路径

路径 A：JSON→PPT 构建器（核心工作流）

完整 6 步流水线：

1. 提取模板背景(可选): 模版.pptx 里的背景图存为 PNG (960x540)
2. WebSearch 搜数据: 分数线/排名/计划/科研数据等
3. matplotlib 生成图表 PNG (注意中文字体 plt.rcParams['font.sans-serif']=['SimHei'])
4. 编写 data.json: 每页 elements[] 编排
5. 运行构建器:
   python build_ppt_from_json.py data.json -o output.pptx [--pdf]
6. 校验: 打开 PPTX 逐页检查溢出/间距/字号

JSON 完整字段规范与 7 种元素类型的排版细节见 references/ppt_json_spec.md；COM 常量/格式码/踩坑见 references/com_cheatsheet.md。

路径 B：COM 助手模块

自定义脚本放在任意目录，把技能的 scripts/ 目录加入 sys.path 后 import wps_com：

import sys; sys.path.insert(0, r"C:\Users\shizi\.workbuddy\skills\zilong-wps\scripts")
from wps_com import connect_wpp, rgb, kill_wps, safe_quit

app = connect_wpp()            # 连接 WPS 演示（自动回退 PowerPoint.Application）
pres = app.Presentations.Add()
# ... 自定义逻辑 ...
safe_quit(app, pres)           # 保存退出，不留僵尸进程

路径 C：裸 COM

import win32com.client
app = win32com.client.Dispatch("KWPP.Application")   # WPS 演示

JSON→PPT 元素类型路由

关键约束 ⚠️（违反必翻车）

• 标题与内容间距：标题 y=14 h=40（结束于 y≈54），第一个内容元素必须起始于 y≥76-78（≥24pt gap）
• 页面标题最多 4 字，居中，SimHei 40-44pt，品牌色，无装饰线
• JSON 中文引号：文本内引用用「」代替 ""，避免 JSON 转义地狱
• 所有元素不出画布：960x540，任何元素 y+h ≤ 518
• 构建前清理：COM 连接失败/卡死时先杀进程 taskkill //F //IM wps.exe //T，或调 wps_com.kill_wps()
• 导出 PDF：pres.SaveAs(path, 32)；保存 PPTX 用 pres.SaveAs(path, 24)
• OLE 颜色：COM 的 RGB 是 r + g*256 + b*65536（BGR 打包），直接用 wps_com.rgb("#1A3C8B")

设计预设（品牌色）

标准页序（12-15 页汇报型 PPT）

S1 封面 → S2 目录(card_list_wide) → S3-S10 内容页(图+表+卡片) → S11 总结卡片 → S12 致谢

质量审查（交付前 5 维度自检）

排障