MainQuestAI/PPT-Library skill 本地安装使用教程(2026新手版)

先把一个容易误会的点说清楚：MainQuestAI/PPT-Library skill 不是让 Agent “凭空生成一套 PPT”的按钮。它更像一套本地 PPT 资产库操作手册，真正处理的是团队电脑里已经有很多历史 PPTX，想按页搜索、审查、复用、组装，不再靠文件名和记忆翻目录。

PPT Library 在仓库 README 里的定位很明确：本地优先的 PPTX 资产库 CLI。它会把幻灯片逐页抽取文本、截图、向量和元数据，Agent 通过仓库内置的 skills/ppt-library/SKILL.md 学会安全调用 ppt-lib。第一个限制也要提前看见：公开版优先按源码安装，pyproject.toml 要求 Python 3.12+；如果机器还在用系统自带 Python 3.9，直接跑源码入口就可能先卡在版本不够上。

图注：先看清它管理的是已有 PPT 资产，输出重点是索引、截图、搜索页和组装清单。

先判断它适不适合你的 PPT 工作流

如果你的痛点是“每次写方案都要从几十个旧文件里找一页架构图、一页案例、一页实施路线”，这个 skill 很对口。PPT Library 支持页级搜索、版本治理、Deck 理解、重点页识别、复用追踪和自动组装，搜索结果还能生成本地 HTML 审查页，方便人先看一遍再决定是否复用。

如果你的目标是让 AI 直接设计全新视觉风格，或者跳过人工确认自动扫描整台电脑，它就不是最省事的入口。仓库里的 Agent 规则反复强调：建库前要先确认资料范围，搜索、组装和回写都要以 ppt-lib 的 JSON 输出和错误状态为准，客户 PPT、截图、数据库和导出产物也应留在本机。

本地安装先卡住三个前置条件

第一是 Python 版本，仓库要求 Python 3.12+。第二是安装工具，README 给出的主线是进入源码目录后运行 uv sync --extra test --extra lint，再用 uv run ppt-lib --help 检查 CLI；如果只是本地 editable 安装，也可以用 pip install -e .。第三是截图能力，LibreOffice 是可选但很实用的依赖，用来把 PPTX 页面渲染成截图，没有它时部分流程会退回文本能力。

模型能力可以晚一点配置。没有 embedding 服务时，PPT Library 仍能做基础文本抽取和关键词搜索；配置 OpenAI-compatible API、LM Studio 或 Ollama 后，搜索质量会升级到语义检索。仓库还推荐本地 embedding 搭配 PaddleOCR MCP，用来补 PPT 页面的 OCR、版式和图表识别。新手最好先把基础 CLI 跑通，再决定是否加这些进阶能力。

安装 Skill 时，不要只复制一份文件

仓库自带的 Agent Skill 在 skills/ppt-library/ 目录下。Codex 环境可以复制到 ~/.codex/skills/ppt-library，Claude Code 可以复制到 ~/.claude/skills/ppt-library。复制时要保留整个目录结构，里面的 references/agent-adapters.md 会说明不同 Agent 的适配方式。

装完后，别急着让 Agent 扫真实 PPT。更稳的验证方式是让它使用 ppt-library skill 检查本机是否可用，要求报告 CLI 可用性、JSON schema、索引状态和模型诊断。这个测试的重点是“命令能不能被识别、输出能不能被 Agent 稳定读取”，不是立刻建一座完整资料库。

图注：第一次验证不要碰客户文件，先用临时目录确认命令、配置和状态输出。

第一次试跑用临时目录，别直接扫资料库

Agent 场景下，README 给的 smoke test 思路是先用临时 home-dir。例如在源码目录里运行 uv run ppt-lib --home-dir /tmp/ppt-lib-smoke setup --quick --non-interactive，再看 schema --output json、status --output json 和 vision --test。这样即使配置失败，也不会污染真实的 ~/.ppt-library/。

本机试跑时如果遇到 uv 不存在，先补安装工具；如果用系统 Python 直接跑源码却报 datetime.UTC 相关错误，先查 Python 版本。仓库已经把 Python 3.12+ 写进要求里，低版本报错不是 PPT Library 的索引问题，而是运行环境还没到门槛。

正式建库前，用 manifest 收住扫描范围

真正入库的第一步不是“扫描本机所有 PPT”，而是让 sources manifest 写出你确认过的资料源。常见顺序是：ppt-lib sources manifest --library /absolute/path/to/ppt-folder --manifest-output ./ppt-sources.json --output json，然后用 ppt-lib init --manifest ./ppt-sources.json --non-interactive 写入当前 profile。路径要用绝对路径，第一次建议只选整理过的小范围 PPTX 文件夹。

接下来先跑 ppt-lib sources scan --dry-run，只预览会命中的文件；确认范围没有问题，再执行 ppt-lib sources scan --apply。仓库文档把 Home 根目录、Downloads、回收站、微信/企业微信缓存、WPS 缓存、依赖包目录和临时输出目录都列为高风险来源。除非你明确确认，不要让 Agent 把这些位置放进长期 PPT 库。

跑通后看三类结果

确认扫描范围后，再运行 ppt-lib index --from-sources。资料量比较大时，可以从 --file-workers 2 这种保守并行开始。建库结束后看 ppt-lib status --output json，重点检查幻灯片数量、失败任务和索引进度。搜索可以先用 ppt-lib search "技术架构" --html，默认生成本地 HTML 结果页。

默认数据会放在 ~/.ppt-library/，包括 SQLite 索引库、页面截图、搜索 HTML 预览、组装清单和本地产物。需要给另一个 Agent 或程序消费搜索结果时，优先用 ppt-lib search "查询内容" --contract-v2 --output json，并检查退出码和 _errors；warning 可以带着结果汇报，error 才是阻断。

常见失败先按这个顺序排查

1. 命令不可用：先查 Python 3.12+、uv 或 editable 安装是否完成，再确认 ppt-lib --help 能返回。
2. 搜索结果为空：先看 status 里的 slide 数量，再检查是否只做了 dry-run、还没执行 scan apply 和 index。
3. 截图缺失：优先查 LibreOffice。截图失败不一定影响文字搜索，但会影响 HTML 审查页的可读性。
4. 语义搜索质量差：检查 embedding provider、模型维度和阈值；切换 provider 或维度后按文档重建索引。
5. Agent 扫到一堆低价值文件：回到 sources manifest，收窄 library 路径，把 Downloads、缓存、回收站和临时产物排除掉。

MainQuestAI/PPT-Library skill 最适合的打开方式，是把它当成“本地 PPT 资产库的安全操作层”。先让 CLI 和 Skill 被 Agent 识别，再用临时目录做健康检查，然后用 manifest 管住资料范围，最后才扩大索引、补 embedding、OCR、关键页和自动组装。这样做看起来慢一点，但能避开两个大坑：把它误当成 PPT 生成器，以及没确认范围就扫进一堆敏感或低价值目录。