name	ppt-library
description	安全调用本地 PPT Library CLI，完成 PPT 资料库建库、索引、搜索、诊断和自动选页组装。
version	1.0.0

ppt-library

能力摘要

能力	对应命令
配置引导	`ppt-lib setup --quick` 或 `ppt-lib setup --mode lmstudio\|paddleocr-mcp\|openai\|text-extraction`
扫描 PPT，去重，创建统一管理视图	`ppt-lib discover <dir>`
监听目录增量索引	`ppt-lib watch <dir>`
搜索 slide	`ppt-lib search "<query>" [--top-k N] [--threshold F]`；机器契约用 `--contract-v2`
生成 HTML 审查页	`ppt-lib search "<query>" --html`
索引单个文件	`ppt-lib index <path>`
批量索引	`ppt-lib index --batch <dir> [--full]`
资料库建库	`ppt-lib sources manifest` → `init --manifest` → `sources scan --dry-run` → `sources scan --apply` → `index --from-sources`
AI 摘要补充	`ppt-lib profile build` → `ppt-lib enrich`
Deck 理解与关键页	`ppt-lib enrich-decks --pending` → `ppt-lib insights key-pages`
标签审查包导出	`ppt-lib insights review-pack --output <jsonl>`
模型能力检测	`ppt-lib models test`
配置查看／修改	`ppt-lib config path\|get\|set`
健康检查	`ppt-lib doctor [--output json]`
样本 QA	`ppt-lib qa sample`
搜索质量评估	`ppt-lib eval-search --manifest <path> [--calibrate]`
孤立记录清理	`ppt-lib prune --dry-run` → `--apply`
聚合诊断	`ppt-lib doctor --output json`
生成用户画像	`ppt-lib profile build --output json`
战绩数据录入	`ppt-lib record-deal --description ...` / `record-usage`
叙事批量标注	`ppt-lib annotate [--batch N]`
自动选页	`ppt-lib select-slides --roles <roles> --brief "..."`
自动组装	`ppt-lib compose --brief "..."` 预览；确认后 `compose --confirm <run-dir>/narrative-plan.json`；明确跳过人工确认时加 `--auto`
运行时能力	`ppt-lib capabilities [--probe] --output json`

通用指引

所有路径要写绝对路径，不要写 ~ 相对路径。
命令支持 --output json 时显式携带；写文件型命令按其专用 --output <path> 契约执行。
JSON 响应体各命令结构不同，先跑一次获取结构，再引用具体字段。
stdout JSON 是机器真相源，stderr 只承载人类进度。先检查进程退出码，再检查 _errors[*].severity：error 会返回非零退出码，warning 可随成功结果返回退出码 0。
默认 CLI envelope 的 _meta.schema_version 字段目前为 1.0。search --contract-v2 直接输出 ppt_library.search_response.v2，以 _meta.envelope 和 _meta.contract 标识版本，不再套一层旧 envelope。
画像就绪：使用 AI summary 前必须先执行 profile build，并确认 ready=true。
建库前先用 sources manifest 生成资料源清单，再通过 sources scan --dry-run 确认扫描范围，避免误扫 Home、Downloads、回收站、缓存目录和依赖包目录。
需要判断“哪些页值得先看”时，先执行 enrich-decks --pending --limit 20，再执行 insights key-pages --output json。
需要批量审查标签时，使用 insights review-pack --output <jsonl> 导出只读包；标签回写继续使用 import-metadata。
推荐识别链路是本地 embedding + PaddleOCR MCP：先 setup --mode lmstudio，再 setup --mode paddleocr-mcp；token 只走环境变量，不写入 config.yml。
compose 默认生成可审查的 selection/manifest；--confirm 必须指向同一 run 目录中的 narrative-plan.json，CLI 会执行已冻结的 manifest.json，不会重新选页。只有明确授权全自动组装时使用 --auto。
search-request.v2 的 industry、scenario、narrative_role、page_role、review_state 过滤值使用非空字符串数组；include_versions 使用布尔值。未声明的过滤字段会直接返回契约校验错误。

建库前安全确认

资料范围通过 sources manifest 生成 manifest，再由 init --manifest 写入生效 profile。角色分为 baseline（用户画像基准）、library（入库资料）、exclude（排除路径）。
基准 PPT：至少准备 1~3 个样例 PPT（sources scan --dry-run 时可先确认它们是否能正常识别）。
资料库目录：在 manifest 中写明 baseline、library（与 excludes）。
高风险目录：Home、Downloads、回收站、缓存、微信、WPS、site-packages、node_modules、outputs、exports、artifacts 默认不得进入 library。
确认扫描：dry-run 后必须执行 sources scan --apply，让 CLI 写入 scan-state。
画像就绪：使用 AI summary 前必须先执行 profile build，并确认 ready=true。

详细说明见仓库文档 docs/guides/library-build-guideline.md。CLI 会强制检查 scan-state、高风险路径和 profile readiness；Skill 只负责按流程引导。

未 dry-run 且未显式确认时，不得扫描 Home、Downloads、回收站、微信缓存、WPS 缓存、依赖包目录和临时产物目录。遇到高风险来源时，先向用户说明风险，再让用户决定是否追加 --force-risky-sources。

推荐命令链（确认后执行）：

快速建库（推荐，首次使用）

ppt-lib setup --quick --non-interactive
ppt-lib sources manifest --library /absolute/path/to/ppt-folder --manifest-output /absolute/path/to/sources-manifest.json --output json
ppt-lib init --manifest /path/to/sources-manifest.json --non-interactive
ppt-lib sources scan --role baseline --dry-run
ppt-lib sources scan --role library --dry-run
ppt-lib sources scan --apply
ppt-lib index --from-sources
ppt-lib status --output json
ppt-lib search "你的查询"
# Agent 需要稳定机器契约时：
ppt-lib search "你的查询" --contract-v2 --output json

如果用户已准备 PaddleOCR MCP，并且资料量较大，可以使用保守文件级并行：

ppt-lib index --from-sources --file-workers 2

先从 2 个 worker 开始，确认 AI Studio 或自托管 OCR endpoint 稳定后再提高。

资产经营闭环（公开演示）

ppt-lib enrich-decks --pending --limit 20 --output json
ppt-lib insights key-pages --output json
ppt-lib insights review-pack --output /absolute/path/to/review-pack.jsonl
ppt-lib record-deal --name "Synthetic Demo Win" --outcome won --description "Synthetic demo opportunity" --industry general --scenario proposal --tags demo,key-page
ppt-lib record-usage --deal-id <deal-id> --slide-id <slide-id> --deck-presentation-id <presentation-id>
ppt-lib search "实施路径 价值" --ranking business --threshold 0.0 --output json

insights key-pages 返回关键页候选、页面角色、重要性分、视觉复核标记和战绩统计。business ranking 只有在有效 usage 和 won/lost 数据积累后才会体现业务权重。

完整建库（可选，含 AI 摘要）

ppt-lib profile build
ppt-lib enrich --pending --limit 50

首次使用建议走快速建库，确认搜索可用后再开启 AI 摘要。

单个文件校验：

ppt-lib index /absolute/path/to/deck.pptx

返回值示例

`ppt-lib doctor --output json`

{
  "summary": {
    "status": "warning",
    "config": "ok",
    "scanner": "ok",
    "model_compat": "warning"
  },
  "config": {
    "embedding_provider": "openai",
    "embedding_model": "text-embedding-3-small",
    "embedding_dimensions": 1536,
    "vision_provider": "auto"
  },
  "model_compat": {
    "status": "warning",
    "checks": [{"capability": "embedding", "status": "ok", "message": "OpenAI embedding works"}]
  },
  "index_health": {
    "status": "ok",
    "slides_indexed": 746,
    "presentations": 107,
    "failed_jobs": 0
  },
  "scanner": {"status": "ok"}
}

`ppt-lib search "<query>" --top-k 3`

{
  "query": "实施计划流程",
  "results": [
    {
      "slide_index": 5,
      "presentation": {"path": "/path/to/deck.pptx", "filename": "demo_overview.pptx"},
      "title": "实施计划流程",
      "text_snippet": "流程图...",
      "screenshot_url": "file:///.../screenshots/slide-5.png",
      "score": 0.68,
      "duplicate_group_id": null
    }
  ],
  "timing_ms": 316
}

`ppt-lib status --output json`

{
  "presentations": {
    "total": 107,
    "limit": null,
    "disabled": 0
  },
  "slides": {
    "total": 746,
    "canonical": 746,
    "canonical_with_duplicates": 0,
    "duplicates": 0,
    "limit": null
  },
  "inline_details": {}
}

注意事项

路径必须绝对路径。
建库流程中的 sources scan 要每次带 --dry-run 预览来确认 safe（home dir、downloads、微信缓存都是高风险来源）。
JSON 输出可能带 _errors 与 warnings。以退出码和 _errors[*].severity 判断阻塞；warning 需要汇报，但不等同于失败。
默认优先 setup --quick。OpenAI-compatible 服务通过 embedding_api_url、embedding_model、embedding_dimensions 配置；LM Studio 默认服务地址为 http://127.0.0.1:1234/v1。
当前 embedding 维度：openai=1536，lmstudio=768；切换 provider 后应 index --from-sources --full 重算。

name	ppt-library
description	安全调用本地 PPT Library CLI，完成 PPT 资料库建库、索引、搜索、诊断和自动选页组装。
version	1.0.0