Presentation-skills ppt-complex-diagram-collab

Use when collaborating with humans to produce publication-grade complex diagrams in editable PPT, especially for system architecture, dataflow, and user-journey visuals that require shape-level connector validation and reproducible outputs.

install

source · Clone the upstream repo

git clone https://github.com/Sven-LI-sankyuu/presentation-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/Sven-LI-sankyuu/presentation-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/old/ppt-complex-diagram-collab" ~/.claude/skills/sven-li-sankyuu-presentation-skills-ppt-complex-diagram-collab && rm -rf "$T"

manifest: old/ppt-complex-diagram-collab/SKILL.md

source content

PPT Complex Diagram Collab

归档说明

本 skill 在仓库中已经归档到
```
old/ppt-complex-diagram-collab/
```
，后续主线能力统一迁移到
```
ppt-polished-deck-collab/
```
。
这里保留的价值主要是复杂图、connector 校验和视觉经验，不再作为主线持续扩展入口。

概览

把“业务讲清楚 + 图可复用 + 论文可交付”作为同一个任务完成。优先交付图包（planning + mermaid + editable PPT + 校验结果），不要只交单张图。

执行目录约定

以下命令默认在
```
old/ppt-complex-diagram-collab/
```
目录内执行（即本
```
SKILL.md
```
同级目录）。
若你从其他目录执行，请自行补齐前缀路径。

工作流

按下面顺序执行，避免返工。

先确认环境基线

先读取 references/tested_environment.md。
至少确认 Python、
```
python-pptx
```
、Node/npm、mermaid-cli 可用。
不强制新建 conda 环境：如果现有环境能安装并稳定运行所需包，直接复用即可；需要隔离再新建临时环境。
如果当前环境和基线差异较大，先记录差异再开始出图，避免“图能生成但不可复现”。

先锁定交付规格

明确主图用途：论文主图、答辩图、工程文档图。
明确输出形态：
```
*.md
```
（含 mermaid）、
```
*.mmd
```
（可选）、
```
*.pptx
```
（可编辑）。
明确可编辑定义：
- 如果使用 connector：拖动节点时连线仍然绑定，不是“视觉上像连着”；
- 如果不使用 connector（分层架构图常见）：用箭头/卡片表达层级递进，此时连线校验期望
```
connectors=0
```
  。
先选视觉语法（分层架构图 vs 数据流/因果图），避免把两张图硬塞一张图。
- 参考：references/visual_style_and_edge_policy.md。

拆分图集而不是硬塞一张图

先给图清单：总览分层图 + 关键执行链路图 + 用户视角流程图。
给每张图编号（如 Fig00~Fig09）并定义“读者问题 -> 图回答什么”。
使用 references/figure_planning_template.md 组织范围和边界。

先做可讨论版本（mermaid）

在一个文档里集中维护图集与解释，保证评审快。
保持节点命名稳定，避免后续 PPT 版无法对齐。
用脚本批量渲染 SVG/PDF/PNG，确保论文与汇报都能复用。

再做可编辑版本（PPT）

用
```
python-pptx
```
直接画 shape（必要时才画 connector），不要仅插入 PNG。
分层架构图（Fig00）推荐默认用 Layer Card + 递进箭头，避免 hairball；数据流图（Fig01）再用 connector。
如果使用 connector：
- 连接线必须使用
```
begin_connect()
```
  /
```
end_connect()
```
  粘连到具体 shape；
- 优先连接“业务节点框”，不要连接 lane/cluster 外框；
- 控制 edge budget（参考视觉/连线策略文档）。
如果不使用 connector：
- 箭头应表达“层级递进/主方向”，不要用长 chevron 文案当装饰；
- 仍然建议运行连线校验，确认
```
connectors=0
```
  。

强制做连线校验

运行
```
scripts/check_pptx_connectors.py
```
校验：
- 每条 connector 同时存在
```
stCxn
```
  和
```
endCxn
```
  ；
- 连接的 shape id 必须可解析到文本节点；
- 不允许粘到被禁止前缀（如
```
Lane 
```
  ）节点。
可选：如果这张图预期必须存在 connector，用
```
--min-connectors
```
防止“意外生成了 0 条连线”。
用 references/ppt_connector_debug.md 做人工复核。

迭代时只改关键差异

用户反馈“线条拖动会散”时，先定位具体哪条边，不做大重画。
优先修连接点索引映射和目标 shape 绑定关系。
每次迭代后重新生成 PPT 并复跑校验脚本。

交付清单

一次完整交付至少包含：

图集说明文档（图编号、用途、约束）。
mermaid 源和批量渲染脚本。
可编辑
```
pptx
```
生成脚本。
连线校验脚本输出（命令 + 结果）。
视觉方案与连线策略说明（建议作为附录或
```
style_spec.md
```
），保证可复用与可复现。

快速命令

# 1) 生成可编辑 PPT（示例）
python <diagram_dir>/build_editable_pptx.py

# 2) 校验连线是否真绑定
python scripts/check_pptx_connectors.py \
  --pptx <diagram_dir>/pptx/<name>.pptx \
  --slide 10 \
  --forbid-prefix "Lane " \
  --min-connectors 1

资源使用规则

需要确认系统/工具环境时，读取 references/tested_environment.md。
需要规划图集范围时，读取 references/figure_planning_template.md。
需要诊断“拖动散线/连错对象”时，读取 references/ppt_connector_debug.md。
需要统一视觉方案/控制连线密度时，读取 references/visual_style_and_edge_policy.md。
需要程序化验收时，运行
```
scripts/check_pptx_connectors.py
```
。