slideops

用途

SlideOps 用于把代码仓库变成一份带引用的 HTML 幻灯片，并让这份幻灯片能够在数月之后证明自己是否仍然与仓库一致。它有两个任务，第二个才是重点：

构建（Build）：把仓库转成单个自包含的 HTML 幻灯片，其中每一条论断都来自代码本身，而不是模型对代码的印象。
保持同步（Keep in sync）：让幻灯片能够在数月后证明自己是否仍与仓库匹配。

连接这两个任务的机制是引用（citation）。每个被引用的代码片段都会记录文件、行范围以及构建时这些源代码行的哈希，幻灯片还会记录它构建所基于的 commit。“这些幻灯片还准确吗？”因此变成一个命令，而不是重新通读一遍。

何时使用

用户要求制作关于某个代码仓库、其子系统、某个功能或近期变更的幻灯片、演示文稿时，例如“make slides”“overview deck”“team update slides”“HTML slides for this repo”。
用户询问已有幻灯片是否仍与代码匹配，或希望重新检查、刷新、保持同步时，例如“is this deck still accurate”“check the slides against the code”“these docs are stale”。
用户希望把幻灯片新鲜度接入 CI、拉取请求检查或智能体钩子时，例如“fail the build when the deck stops matching the code”。
不适用于非代码库主题的幻灯片（如销售演示、讲座）；引用机制假定以 git 仓库作为事实来源。

工作原理

第 1 步：从规范仓库安装

在 Claude Code 中作为插件安装（两个技能，更新需显式审查）。

或者对 Codex CLI、Copilot CLI 和 OpenCode，一个安装器即可覆盖全部。

外部工具前置条件：只使用已安装、且其确切版本、完整依赖树和完整性已经过审查的工具。该技能不会引导安装工具或激活外部插件。如果缺少前置条件，应停止该可执行路径并报告；在可能时继续做静态分析。单独的安装任务必须固定不可变产物，将其暂存在活动智能体目录之外并禁用生命周期脚本，检查每个捆绑文件和可执行入口点（包括测试和钩子），并在激活或更改宿主配置前获得批准。不要用同名的 workspace 脚本替代，也不要拉取移动的分支。

该检出固定在此目录副本冻结的确切 commit 上，读者可以独立验证。（规范仓库还通过活动标签规则集阻止 v* 标签被重新指向，但 SHA 不需要你信任这一点。）install.sh 会把两个技能以符号链接方式安装到 ~/.claude/skills（由 Claude Code 和 OpenCode 读取）和 ~/.agents/skills（由 Codex CLI 和 Copilot CLI 读取）。

第 2 步：构建幻灯片

该技能走一条固定流水线：两分钟的仓库扫描、一次紧凑的信息采集（主题、受众、长度、主题风格、范围、附加项）、在写任何 HTML 之前先做大纲检查点，然后基于经过验证的模板逐页构建。每个片段在写入时即被引用。在被展示的仓库内部运行引用脚本，通过其安装路径（智能体会自动相对于技能自身目录解析 scripts/；下面的路径是给安装 install.sh 后自行运行用的）：

python3 ~/.agents/skills/slideops/scripts/cite.py app/main.py:40-58 --repo . --snippet   # prints data-src + data-sha256
python3 ~/.agents/skills/slideops/scripts/cite.py --stamp deck.html --repo .             # stamps the build commit

--repo 始终指向幻灯片所讲述的那个仓库，绝不指向 SlideOps 检出目录。

随后每一页幻灯片都会用无头 Chrome 渲染，并在幻灯片被视为完成之前进行视觉验证。

第 3 步：之后免费检查

在被展示的仓库内部，路径约定与第 2 步相同：

python3 ~/.agents/skills/slideops/scripts/check.py docs/slides/ --repo .

来自该技能自带演示幻灯片的真实输出：

Deck: skill-demo.html
Built: commit=179bbdb date=2026-08-28 repo=slideops

  slide   9  THEMING        skills/slideops/assets/template.html:22-45    CURRENT
  slide  14  MERMAID        skills/slideops/references/diagrams.md:55-59  CURRENT

2 current, 0 stale, 2 cited in total.

MOVED 表示只有行号发生了移动（更新两个属性，保留正文）。CHANGED 表示被引用的代码被编辑过（阅读 diff，判断幻灯片中的论断是否仍然成立）。MISSING 表示文件已不存在（该幻灯片很可能已过时）。--json 标志会为每条过时引用输出完整的修复简报，使智能体无需重新通读仓库即可修复漂移。

示例

示例 1：新幻灯片

用户：make slides about this repo 智能体：[扫描仓库，提出 3-4 个具体主题并各附一个“why now”，询问一次紧凑的信息采集，展示大纲，然后在 docs/slides/ 构建并视觉验证一份带引用的 HTML 幻灯片]

示例 2：CI 中的新鲜度检查

python3 tools/slideops-check.py docs/slides/ --repo . --exit-zero   # report-only PR annotation

规范仓库的 references/automation.md 包含 PR 检查工作流、建议性钩子变体以及委托刷新配方。check.py 是一个无依赖的单文件，设计为可 vendored 进幻灯片所在的仓库。

最佳实践

✅ 用 cite.py 引用，绝不手工引用：手工计算的哈希会在数月后静默报告 CHANGED，没人能分辨是代码移动了还是构建草率。
✅ 修复漂移的幻灯片，而不是重建它。只修复引用已过时的幻灯片，然后重新打戳。
✅ 对常青幻灯片（入职、架构）自动化检查；对快照（冲刺更新、会议演讲）有意保持冻结。
❌ 不要对 PDF 导出运行 check.py：引用存在于 HTML 中，因此 PDF 会报告“No citations found in this deck”。
❌ 不要用检查阻塞每一次提交。先在拉取请求上只报告；在快速路径上设置文档门禁会训练人们使用 --no-verify 绕过。

限制

视觉验证环节需要无头 Chrome 或 Chromium 二进制（Playwright 缓存或系统安装），引用脚本需要 Python 3。
除两个可选功能外可离线工作：Mermaid 图表（一次性 npx 下载）和从在线样式指南提取品牌色。
检查只验证被引用的代码片段与代码是否一致；它无法验证没有引用任何内容的正文论断。
漂移检测假定幻灯片和代码共享同一个 git 仓库。

安全与安全说明

在克隆上游仓库、运行 install.sh、在用户主目录创建技能符号链接、下载可选 npx 包或写入幻灯片输出之前，先询问。先展示确切的固定 commit 和目标路径，并保留任何已有的技能条目，而不是静默覆盖。
引用脚本是仅用标准库的 Python：无依赖、无网络、无 token。
该技能刻意不声明 allowed-tools：宿主智能体自身的权限模型保持主导，无头 Chrome 保持其沙箱。
该技能对幻灯片内容有明确的保密规则：绝不读取或引用机密、密钥、.env 文件、生产日志或客户数据；对内部主机名和标识符进行脱敏；最后对渲染后的幻灯片做一次脱敏扫描，因为幻灯片是会离开仓库的文档。
文件写入仅限于幻灯片输出文件夹（默认 docs/slides/）及其配套 README。

常见陷阱

问题：对导出的 PDF 运行 check.py 报告没有引用。解决：对 HTML 幻灯片运行它；PDF 是配套 slides-to-pdf 技能生成的派生产物。
问题：刚构建的幻灯片已经报告 CHANGED。解决：这是构建缺陷，不是未来的问题：某个片段被引用后又被编辑，或哈希是手工计算的。发布前用 cite.py 重新引用。
问题：验证步骤找不到 Chrome。解决：规范仓库的 references/verification.md 有跨平台发现配方（先 Playwright 缓存，再系统安装）。

技能介绍

用途