HUIIHONG PPT 模版开发：从AI协作到可复用技能的全记录
这篇文章记录了为一个投资路演 PPT 模版（汇竑资本 HUIIHONG 品牌，红金配色）开发 python-pptx 自动生成脚本，历经十轮迭代后封装为 OpenCode 可复用技能的完整过程。
核心数据：10 轮迭代，~750 行 Python，11 种自定义图标，20+ MSO_SHAPE 形状，最终生成 15 页投资报告 PPT。
背景：为什么需要自动生成 PPT
在算电协同投资研究中，频繁需要生成格式统一的投资路演 PPT。人工拖拽太慢，传统模板太死板。目标是用 python-pptx 实现：给定结构化数据 → 自动生成品牌一致的 PPT。
汇竑资本的 HUIIHONG 品牌有明确的视觉规范：深红 #C00000 + 金色 #D4AF37 + 白底卡片。难点在于精确复刻模版中的所有间距和对齐——0.01 英寸的偏差在放大后都会变得明显。
第一轮：精确测量与基础架构
从一份 40 页的参考模版（内蒙古新质动能科创投资基金路演报告申报材料）开始。用 python-pptx 逐页读取所有形状的位置、大小、颜色等属性：
from pptx import Presentation
prs = Presentation('template.pptx')
for slide in prs.slides:
for shape in slide.shapes:
print(shape.left, shape.top, shape.width, shape.height, shape.shape_type) 关键发现：python-pptx 的 Emu 单位 = 英寸 × 914400。所有模版元素都精确到 Emu 级别——比如 header bar 的 outer 框在 L0.642 T0.483，inner 红色 rect 在 L0.875 T0.684。
这一轮确定了基础架构：_add_header_bar + _add_header_title + _add_logo + _add_page_number 的页面骨架，以及 _set_cn_font 这个关键辅助函数——没有它，中文字符在 PPTX 中会显示为方框。
第二轮：封面与内容页布局
封面的核心挑战是模板中使用了背景图（城市夜景半透明），脚本需要检测图片是否存在，否则 fallback 到纯色背景。封面设计了黄金分隔线的位置（T4.80），以及底部的合规免责声明。
内容页采用「header bar + 标题 + 分页线 + logo + 正文」的五段式布局。卡片则采用「白底 + 0.042英寸红色左竖条」的模板标识模式。
第三轮：TOC 分节页
目录页（TOC）的难点在于需要模拟模板的 2×2 网格布局。每个 TOC 项目是一个圆角矩形，当前章节红色高亮（#C00000），其他章节灰色边框。
最初的实现没有金色图标，后来经历了「先加 → 又被去掉 → 最终加上更精致的」的反复。
第四轮：卡片布局系统
两种核心卡片布局：
- 竖式卡片（vert_cards）：2 列布局，左侧 label + body，右侧保持空白呼吸感。适用于文字较多的场景。
- 三列卡片（3col_cards）：3 列等宽布局，带 metrics 子指标。适用于对比分析。
其中三列卡片是收益最高的布局——视觉冲击力强、信息密度适中，适合投资 PPT 的「论据页」。
第五~七轮：图标系统的三次演进
图标系统是迭代次数最多的部分，共经历了三次重写：
V1：简单几何（红/金色菱形、圆形）
用 MSO_SHAPE 的 OVAL、DIAMOND 等基本形状。优点是实现简单，缺点是样式单调，且与卡片内容毫无关联。
V2：复杂形状映射（金色圆角矩形 + 白色几何）
参考模版第 9 页，实现「金色 #BF9000 圆角矩形背景 + 白色形状」的两层结构。引入了 10 种 MSO_SHAPE 形状映射（star/hexagon/cross/chevron 等），开始根据卡片内容选择不同形状。
这一版的问题：形状仍然是简单的几何图形，缺乏语义——比如用「齿轮」代表技术、「闪电」代表电力，而这些简单的 MSO_SHAPE 做不到。
V3：Pillow 自定义 PNG（有意义的图标）
最终方案：用 Python Pillow 在内存中绘制透明 PNG 图标，每一笔都是白色像素。然后通过 add_picture 嵌入 PPT。实现了 11 种语义图标：
| 图标 | 形状 | 含义映射 | 示例场景 |
|---|---|---|---|
| 靶子 🎯 | 同心圆 + 准心 | 目标/聚焦 | 双碳目标、投资方向 |
| 盾牌 🛡 | 多边形盾形 | 政策/安全 | 政策护航、估值安全 |
| 奖杯 🏆 | 高脚杯 + 把手 | 成就/回报 | 投资回报、成果 |
| 天平 ⚖ | 横梁 + 底座 + 托盘 | 公平/政策 | 政策评估、市场公平 |
| K线图 📈 | 坐标轴 + 柱状条 + 趋势线 | 市场/数据 | 市场驱动、数据分析 |
| 握手 🤝 | 重叠弧线 | 合作/协同 | 算电协同、交易合作 |
| 放大镜 🔍 | 圆形 + 手柄 | 观察/研究 | 行业研究、深度分析 |
| 书籍 📖 | 打开的书本 | 知识/研究 | 方法论、理论基础 |
| 房屋 🏠 | 三角屋顶 + 方形 | 稳定/基础 | 基础设施、底层架构 |
| 架构图 🏗 | 建筑 + 三角形屋顶 | 产业链 | 产业链分析、系统架构 |
| 地球 🌐 | 圆形 + 经纬线 | 全球/宏观 | 全球市场、宏观分析 |
这套系统的核心是 _add_gold_icon 函数：它先检查是否有自定义 PNG（查 _ICON_DRAW 字典），有则用；没有则 fallback 到 MSO_SHAPE 的几何形状。这种"插件式"设计让后续扩充图标只需要添加一个绘图函数。
第八轮：语义化映射
有了丰富的图标库之后，关键是把每个卡片标题映射到最合适的图标。这不是随意的——每张卡都经过语义匹配：
| 页面 | 卡片标题 | 图标 | 映射逻辑 |
|---|---|---|---|
| P2 最佳时机 | 技术条件成熟 | 齿轮 ⚙ | 技术 = 齿轮 |
| P3 驱动因素 | 市场驱动 | K线图 📈 | 市场 = 数据/K线 |
| P4 政策演进 | 正式入策 | 钻石 ◆ | 重要事件 = 钻石 |
| P5 政策叠加 | 双碳目标 | 靶子 🎯 | 目标/靶子 = target |
| P6 产业链 | 协同侧 | 握手 🤝 | 协同 = 握手 |
| P7 市场规模 | 全球算力市场 | 地球 🌐 | 全球 = 地球 |
| P8 投资逻辑 | 估值安全边际 | 八边形 ⛔ | 安全/警示 = octagon |
| P9 布局企业 | 协鑫能科 | 太阳 ☀ | 能源 = 太阳 |
| P10 风险 | 竞争加剧风险 | 八边形 ⛔ | 风险警示 = octagon |
最受好评的映射是「协同→握手」和「双碳目标→靶子」——用户原话是"这样会显得很有设计感和质感"。
第九~十轮：死代码清理与系统打磨
金无足赤。第一版的自定义图标系统里混入了几个不存在的 MSO_SHAPE（如 MSO_SHAPE.SHIELD 在 python-pptx 中并不存在），导致运行报错。还有未使用的 _add_numbered_gold_circle 死代码。
所有 icon 数组最终通过 grep icons= 逐行验证，确保每个图标名都存在于 _ICON_DRAW 或 _ICON_SHAPES 字典中。
从脚本到技能：封装为可复用模版
完成十轮迭代后，脚本运行稳定，生成 15 页 PPT 只需要几秒钟。但更好的做法是把它封装成一个可复用的 OpenCode 技能，让 AI 能够理解它的能力边界并正确调用。
技能封装了三个关键资产：
- SKILL.md：技能文档，说明触发条件（汇竑/红金等关键词）、工作流（4 阶段流程）、参考文件结构
- scripts/gen_huihong_v2.py：~750 行的完整生成脚本，包含所有布局函数和图标系统
- assets/：logo、封面背景图、banner 等静态素材
技能安装路径：~/.agents/skills/huihong-ppt/。当 AI 检测到用户需要生成"汇竑风格 PPT"、"红金配色路演材料"时，自动加载此技能。
技术与架构决策总结
| 决策 | 选择 | 原因 |
|---|---|---|
| 单位系统 | 英寸（Inches） | 模版中所有数值以英寸测量，保持整数精度 |
| 颜色字典 | 全局 C 字典 | 一处定义全身引用，避免色值漂移 |
| 图标系统 | Pillow PNG + MSO_SHAPE 混合 | 自定义图标有语义，MSO_SHAPE 做 fallback |
| 卡片布局 | vert / 3col 两种模式 | 覆盖绝大多数内容场景 |
| TOC 分节 | 2×2 网格 + 红色高亮 | 严格复制模版风格 |
| 字体处理 | _set_cn_font 双字体回退 | 确保中英文在不同系统上正确渲染 |
AI 协作的经验教训
这次开发过程中有几个值得记录的协作经验：
- 不要猜测模版参数：永远用脚本读取模版的实际数值，而非人眼估计。0.01 英寸的偏差在投影时会被放大。
- 语义映射优于随机图形：用户多次反馈"图标与内容不匹配"——最终用 Pillow 自定义绘制的方案最被认可。
- 用户是模版专家：开发过程中用户多次指出"参照模版第 X 页的做法"——把参考文件纳入上下文比 AI 凭空想象准确得多。
- 死代码影响信任：一个不存在的 MSO_SHAPE.SHIELD 报错就会中断整个生成流程。每轮迭代后 grep 验证所有引用是必要的。
- 从脚本到技能是质的飞跃：脚本只能执行固定逻辑，技能让 AI 理解能力边界、正确调用、甚至组合多个技能（比如这篇文章就是另一个技能生成的）。
相关的开发记录已沉淀为 OpenCode 技能，完整代码见 ~/.agents/skills/huihong-ppt/。