PPT Library 使用说明

1. 它解决什么问题

PPT Library 把历史 PPT 按页变成可检索资产，让人和 Agent 都能：

• 搜索可复用页面（关键词 + 语义）
• 审查、标注、追踪战绩
• 按 brief 自动选页并组装 PPTX 草稿

适合：方案团队找历史页、售前减重复造页、Agent 稳定调用而非翻文件夹。

2. 与 PPT Deck Pro Max 的分工

3. 环境要求

• Python 3.12+
• uv（推荐）或 pip
• 可选：LibreOffice（页截图）、LM Studio/Ollama（embedding）、PaddleOCR MCP（OCR/版式识别）

无 embedding 时仍可做基础文本抽取与关键词搜索；配置 embedding 后语义检索质量明显提升。

4. 安装

git clone https://github.com/MainQuestAI/PPT-Library.git
cd PPT-Library

# 开发 + 测试依赖
uv sync --extra test --extra lint

# 推荐：PaddleOCR MCP
uv sync --extra test --extra lint --extra paddleocr

# 运行 CLI
uv run ppt-lib --help

# 或安装为全局命令
uv tool install .

安装 Agent Skill

# Codex
mkdir -p ~/.codex/skills/ppt-library
rsync -a skills/ppt-library/ ~/.codex/skills/ppt-library/

# Claude Code
mkdir -p ~/.claude/skills/ppt-library
rsync -a skills/ppt-library/ ~/.claude/skills/ppt-library/

# Cursor（项目级）
mkdir -p .cursor/skills/ppt-library
rsync -a skills/ppt-library/ .cursor/skills/ppt-library/

Smoke 验证 Prompt

Use the ppt-library skill. Check whether PPT Library is usable on this machine without indexing any private files. Report CLI availability, JSON schema health, index status, and model diagnostics.

5. 人类用户：首次建库

# 1. 初始化
uv run ppt-lib setup --quick

# 推荐：本地 embedding + PaddleOCR
uv run ppt-lib setup --mode lmstudio
uv run ppt-lib setup --mode paddleocr-mcp

# 2. 生成资料源清单
uv run ppt-lib sources manifest \
  --library /absolute/path/to/ppt-folder \
  --manifest-output ./ppt-sources.json

# 3. 写入 profile
uv run ppt-lib init --manifest ./ppt-sources.json --non-interactive

# 4. 预览扫描范围（必做）
uv run ppt-lib sources scan --dry-run

# 5. 确认后应用
uv run ppt-lib sources scan --apply

# 6. 建库
uv run ppt-lib index --from-sources --file-workers 2

# 7. 搜索
uv run ppt-lib search "技术架构" --html

# 8. 补齐 Deck 理解
uv run ppt-lib enrich-decks --pending --limit 20
uv run ppt-lib insights key-pages --output json

资料源清单最小示例：

{
  "sources": {
    "library": ["/path/to/your/ppt-folder"],
    "exclude": []
  }
}

建议：先用少量 PPTX 验证流程，再扩大资料库。

6. Agent 调用规范

1. 默认 --output json，以 stdout JSON 为结果依据
2. 路径必须绝对路径，不要用 ~
3. 汇报成功前检查 _errors、failed jobs、fallback warning
4. 建库流程：sources manifest → init --manifest → scan --dry-run → 用户确认 → scan --apply → index --from-sources
5. 禁止扫描 Home、Downloads、回收站、缓存、微信/WPS 缓存、依赖目录（除非用户明确确认）
6. 长任务用 status --output json 看 sources_health.index_progress

典型命令链

# Smoke（临时目录，避免误扫）
uv run ppt-lib --home-dir /tmp/ppt-lib-smoke setup --quick --non-interactive
uv run ppt-lib --home-dir /tmp/ppt-lib-smoke status --output json

# 建库
ppt-lib sources manifest --library /abs/path --manifest-output ~/.ppt-library/sources/sources-manifest.json --output json
ppt-lib init --manifest ~/.ppt-library/sources/sources-manifest.json --non-interactive --output json
ppt-lib sources scan --dry-run --output json
ppt-lib sources scan --apply --output json
ppt-lib index --from-sources
ppt-lib search "会员运营案例" --top-k 8 --output json

# 组装（先 dry-run）
ppt-lib compose --brief "生成一份客户成功案例方案" --dry-run
ppt-lib compose --confirm /path/to/narrative-plan.json

7. 常用工作流

8. 数据与隐私

默认数据目录 ~/.ppt-library/：

• SQLite 索引库
• 页截图、搜索 HTML 预览
• 组装清单与本地产物

客户 PPT、路径、截图、数据库均留在本机，勿提交到公开仓库。

9. Prompt 示例

Use the ppt-library skill：
1. 用 /tmp 做 smoke test，确认 CLI 与 JSON schema 正常；
2. 帮我把 /Users/me/work/ppt-archive 建库（先 dry-run 让我确认扫描范围）；
3. 搜索「零售会员运营架构」Top 8 页，输出 JSON；
4. 若有可复用页，生成 compose dry-run 组装方案。

10. 延伸阅读

• 仓库 docs/quick-start-guide.md
• docs/guides/agent-install-and-build-guideline.md
• skills/ppt-library/SKILL.md