sn-ppt-tools

1# sn-ppt-tools
2 
3这是 PPT Skill 整包自带的备用工具，不是独立内容生产流程。调用前先读
4`references/capability-policy.md`。宿主 Agent 的等价原生工具始终优先；只有原生能力
5不存在或一次实际调用确认不可用时，才调用这里的脚本。
6 
7## 持久配置
8 
9四个脚本每次启动都会自动加载一个用户级 `.env`：
10 
111. 设置了 `SN_PPT_ENV_FILE` 时读取该文件；
122. OpenClaw 读取 `~/.openclaw/.env`；
133. 其他环境默认读取 `~/.hermes/.env`。
14 
15已有进程环境变量优先，`.env` 只补充缺失项。不要把 secret 写进 Skill 目录、workspace、
16命令行、prompt 或 task pack。完整模板和缺失项检查通过 `sn-ppt-doctor` 查看。
17 
18## 普通搜索
19 
20```bash
21python3 "$PPT_TOOLS_DIR/scripts/web_search.py" "QUERY" --num 10
22```
23 
24配置：
25 
26- URL：`SN_PPT_WEB_SEARCH_URL`；否则
27  `SN_PPT_SEARCH_BASE_URL` / `SERPER_BASE_URL` 加 `/search`。
28- Key：`SN_PPT_WEB_SEARCH_API_KEY` -> `SN_PPT_SEARCH_API_KEY` ->
29  `SERPER_API_KEY`。
30 
31## 图片搜索与下载
32 
33```bash
34python3 "$PPT_TOOLS_DIR/scripts/image_search.py" "QUERY" --num 10
35 
36python3 "$PPT_TOOLS_DIR/scripts/fetch_image.py" \
37  "https://example.com/image.png" \
38  --deck-dir "$DECK_DIR" \
39  --output "assets/image.png" \
40  --referer "https://example.com/source-page"
41```
42 
43图片搜索配置：
44 
45- URL：`SN_PPT_IMAGE_SEARCH_URL`；否则
46  `SN_PPT_SEARCH_BASE_URL` / `SERPER_BASE_URL` 加 `/images`。
47- Key：`SN_PPT_IMAGE_SEARCH_API_KEY` -> `SN_PPT_SEARCH_API_KEY` ->
48  `SERPER_API_KEY`。
49 
50先根据搜索元数据选择候选，再下载选中的图片。不得把远程 URL 直接留在最终 deck。
51 
52## 图片生成
53 
54```bash
55python3 "$PPT_TOOLS_DIR/scripts/image_generate.py" \
56  --prompt-file "$DECK_DIR/pages/page_001.prompt.txt" \
57  --deck-dir "$DECK_DIR" \
58  --output "pages/page_001.png" \
59  --size "2752x1536"
60```
61 
62配置：
63 
64- URL：`SN_PPT_IMAGE_GEN_URL`；否则
65…