@deepwhale-cn/dsh-pptx-batch 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 深鲸 DeepWhale
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# @deepwhale-cn/dsh-pptx-batch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/feely0208/dsh-pptx-batch)
+
+**整目录的 PPT 一次处理完**：批量填模板占位符、按形状名换图片、提取每页文本、看页数/形状数/图片数 —— 不打开 PowerPoint，不动原文件。
+
+**关键词**：PPT 批量填模板 · pptx 批量替换 · PPT 批量换 Logo · 提取 PPT 文本 · PPT 页数统计 · 汇报批量生成 · 模板占位符替换 · 命令行处理 PPT
+
+## 不装会怎样
+
+30 份给不同客户的报价 PPT，模板里写着 `{{客户}}`、`{{金额}}`：不装就得一份份打开、双击文本框、输入、保存、关掉，
+一小时起步，改到第 20 份时手一滑把上一位客户的名字留在下一份里，也没人发现。
+
+五十份材料的 Logo 要换新版：人工做法是逐份删图、插图、再对齐一遍位置，版面还容易歪。
+
+要核对一批 PPT 每页写了什么、各有多少页多少张图：只能一份份翻，翻完还记不住。
+
+这些都属于「机械但量大、还容易漏」的活。更麻烦的是直接让 AI 改原文件，改坏了没有退路 ——
+这个插件**只读输入**，产物写到单独的输出目录，同名文件自动加序号，不覆盖任何东西。
+
+## 能做什么
+
+| 子命令 | 作用 | 产物（可核对） |
+|---|---|---|
+| `fill` | 按 `--set key=value` 批量填幻灯片里的 `{{key}}` 占位符（文本框、占位符、表格单元格、组合形状） | 填好的 `.pptx` 副本；JSON 里给出每份替换了几处、哪个 key 几处 |
+| `replace-image` | 把名为 `--shape` 的图片形状换成 `--image` 指定的图片 | 换图后的 `.pptx` 副本；图片数量不变、位置尺寸不变、形状名不变 |
+| `extract-text` | 提取每页文本：标题 + 正文 + 表格 + 备注 | 每份 PPT 一个同名 `.txt`，按「第 N 页」分块 |
+| `info` | 输出每份 PPT 的页数、形状数、图片数 | 终端表格；`--json` 给脚本用 |
+
+共同约定：
+
+- **不修改输入文件**，默认输出到 `<输入目录>/_输出`，可用 `--out` 指定；
+- **同名文件不覆盖**：已存在时自动变成 `简报_1.pptx`、`简报_2.pptx`；
+- 目录递归处理，自动跳过 PowerPoint 的 `~$` 临时文件和 `_输出` 目录；
+- `--json` 输出结构化结果，方便脚本 / CI 断言；出错时退出码非 0 并说明缺什么；
+- `fill` 填完会报出**还剩哪些 `{{...}}` 没给值**，模板里拼错 key 一眼能看出来。
+
+```bash
+# 批量填模板：一份模板 + 一个客户一套值
+dsh-pptx-batch fill --input ./模板 --out ./已填 \
+  --set 客户=客户甲 --set 金额=128000 --set 日期=2026-10-24
+
+# 批量换 Logo（形状名要和 PowerPoint「选择窗格」里显示的一致）
+dsh-pptx-batch replace-image --input ./已填 --out ./换图 \
+  --shape Logo --image ./logo-新.png
+
+# 提取每页文本
+dsh-pptx-batch extract-text --input ./模板 --out ./文本
+
+# 看一眼结构
+dsh-pptx-batch info --input ./模板 --json
+```
+
+`fill` 保留格式的方式：占位符整段落在一个 run 里时，这个 run 的字体、字号、颜色完全不动；
+只有跨多个 run 的占位符（同一段字被 PowerPoint 拆成几块）才会把这几段并到起始 run 的格式上。
+
+## 不能做什么
+
+- ❌ 只支持 `.pptx`；`.ppt` 老格式、`.pptm`、加密/需要密码打开的文档不支持 —— `.ppt` 请先用 PowerPoint/WPS 另存为 `.pptx`。
+- ❌ `fill` **不处理**图表文字、SmartArt 文字、图片里的文字、批注、母版/版式上的文字，也不跨段落匹配。
+- ❌ `fill` 是**字面匹配**（`{{key}}`，key 大小写敏感，允许 `{{ key }}` 这种空格），不支持正则、不支持一次给同名 key 多个值。
+- ❌ **不保证排版 100% 不变**：跨 run 的占位符替换会合并该段文字的 run，段落内局部加粗/字号/颜色可能丢失；
+  重要模板请先跑一份对比再批量用。
+- ❌ `replace-image` 只换图片内容：新图比例和原图不同时会被**拉伸**（裁剪设置沿用原来的）；
+  只按形状名精确匹配，不支持按内容或页码挑选，同名形状会全部替换。
+- ❌ `extract-text` 不提取图表数据、SmartArt、页码与母版文字；图片只留位置不留文字（没有 OCR）。
+- ❌ `info` 的「形状数」是每页顶层形状数之和（组合形状算 1 个，其内部形状不计入）。
+- ❌ 不是格式转换器：不导出 PDF、不做 OCR、不做批量重命名。
+- ✅ 全部在本机由 python-pptx 处理，不联网、不上传文件。
+
+## 安装
+
+```bash
+dsh plugin --profile web add @deepwhale-cn/dsh-pptx-batch
+```
+
+运行依赖本机的 **python3 + python-pptx**（插件不会替你装）。缺依赖时 CLI 会直接打印安装命令：
+
+```bash
+python3 -m pip install python-pptx
+# macOS 没有 python3 时
+brew install python3
+```
+
+## 用法
+
+```bash
+dsh-pptx-batch --help
+dsh-pptx-batch --demo        # 自造样例 PPT 跑完整流程，打印产物路径
+dsh-pptx-batch <action> --input <文件或目录> [--out <目录>] [--json]
+```
+
+`--demo` 会在系统临时目录里造两份带占位符、表格和图片形状的样例 PPT，
+依次跑 fill / replace-image / extract-text / info，不动你的任何文件，跑完直接看产物路径就知道它能干什么。
+
+退出码：`0` 成功 · `1` 运行失败 · `2` 参数或输入问题 · `3` 缺依赖。
+
+## License
+
+MIT © 温州深鲸智能科技有限公司

package/bin/cli.mjs

@@ -0,0 +1,284 @@
+#!/usr/bin/env node
+/**
+ * PPT 批量处理 CLI
+ *
+ * 形态：
+ *   dsh-pptx-batch --help                       （无参数也打印 help，退出 0）
+ *   dsh-pptx-batch --demo                       （自造样例跑完整流程，退出 0）
+ *   dsh-pptx-batch <action> --input <文件或目录> [--out <目录>] [--json]
+ *
+ * 真实逻辑全部委托 python3 + python-pptx（lib/pptx_tool.py），
+ * Node 只负责参数校验、调用与人类可读输出。
+ */
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PY_SCRIPT = join(PKG_ROOT, 'lib', 'pptx_tool.py');
+const TITLE = 'PPT 批量处理';
+const CMD = 'dsh-pptx-batch';
+const ACTIONS = {
+  fill: '按 --set key=value 批量填模板里的 {{key}} 占位符',
+  'replace-image': '把名为 --shape 的图片形状换成 --image 指定的图片',
+  'extract-text': '提取每页文本（标题 + 正文 + 表格）到同名 .txt',
+  info: '输出每份 PPT 的页数 / 形状数 / 图片数',
+};
+const PY_HINT = [
+  '需要 python3 + python-pptx。安装：',
+  '  python3 -m pip install python-pptx',
+  '没有 python3 时：',
+  '  macOS: brew install python3',
+  '  Ubuntu: sudo apt install python3',
+].join('\n');
+const LINE = '─'.repeat(56);
+
+function help() {
+  console.log(`${TITLE}
+
+用法：
+  ${CMD} <action> --input <文件或目录> [--out <目录>] [--json]
+  ${CMD} --demo
+  ${CMD} --help
+
+子命令：
+${Object.entries(ACTIONS).map(([k, v]) => `  ${k.padEnd(14)}${v}`).join('\n')}
+
+参数：
+  --input, -i   .pptx 文件或目录（目录递归处理）
+  --out, -o     输出目录；默认 <输入目录>/_输出；同名文件不覆盖，自动加序号
+  --set         key=value，可重复；对应幻灯片里的 {{key}} 占位符
+  --shape       要替换的图片形状名（精确匹配，大小写敏感）
+  --image       新图片文件（png / jpg / gif / bmp / tiff）
+  --json        输出 JSON（给脚本 / CI 用）
+  --demo        自造样例 PPT，跑完整流程并打印产物路径
+
+示例：
+  ${CMD} fill --input ./模板 --set 客户=客户甲 --set 金额=128000
+  ${CMD} replace-image --input ./已填 --shape Logo --image ./logo-新.png
+  ${CMD} extract-text --input ./模板 --out ./文本
+  ${CMD} info --input ./模板 --json
+
+依赖：python3 + python-pptx（缺失时会提示安装命令）`);
+  process.exit(0);
+}
+
+function fail(message, hint = '', code = 2, json = false) {
+  if (json) {
+    console.log(JSON.stringify({ ok: false, code, message, hint }, null, 2));
+  } else {
+    console.error(`❌ ${message}`);
+    if (hint) console.error(`\n${hint}`);
+  }
+  process.exit(code);
+}
+
+function findPython() {
+  const candidates = [
+    process.env.DSH_PYTHON,
+    process.env.PPTX_BATCH_PYTHON,
+    '/opt/homebrew/bin/python3',
+    'python3',
+    '/usr/local/bin/python3',
+    '/usr/bin/python3',
+  ].filter(Boolean);
+  for (const cmd of candidates) {
+    const r = spawnSync(cmd, ['-c', 'import sys; print(sys.version_info[0])'], {
+      encoding: 'utf8',
+      timeout: 10000,
+    });
+    if (!r.error && r.status === 0) return cmd;
+  }
+  return null;
+}
+
+function parseArgs(argv) {
+  const opt = {
+    action: null, input: null, out: null, set: [], shape: null, image: null,
+    json: false, demo: false,
+  };
+  const VALUE_FLAGS = new Set(['--input', '-i', '--out', '-o', '--set', '--shape', '--image']);
+  for (let i = 0; i < argv.length; i++) {
+    const raw = argv[i];
+    const eq = raw.indexOf('=');
+    const flag = eq > 0 ? raw.slice(0, eq) : raw;
+    const inline = eq > 0 ? raw.slice(eq + 1) : undefined;
+    if (flag === '--json') {
+      opt.json = true;
+      continue;
+    }
+    if (flag === '--demo') {
+      opt.demo = true;
+      continue;
+    }
+    if (flag === '--help' || flag === '-h') help();
+    if (VALUE_FLAGS.has(flag)) {
+      let value = inline;
+      if (value === undefined) {
+        value = argv[i + 1];
+        if (value === undefined || value.startsWith('--')) {
+          fail(`参数 ${flag} 缺少取值`, `例：${flag} <值>`);
+        }
+        i += 1;
+      }
+      if (flag === '--input' || flag === '-i') opt.input = value;
+      else if (flag === '--out' || flag === '-o') opt.out = value;
+      else if (flag === '--shape') opt.shape = value;
+      else if (flag === '--image') opt.image = value;
+      else opt.set.push(value);
+      continue;
+    }
+    if (flag.startsWith('-')) {
+      fail(`未知参数：${raw}`, `用 ${CMD} --help 查看支持的参数。`);
+    }
+    if (!opt.action) {
+      opt.action = raw;
+      continue;
+    }
+    fail(`多余的参数：${raw}`, '一次只能执行一个子命令。');
+  }
+  return opt;
+}
+
+function human(res) {
+  console.log('');
+  console.log(`  ${TITLE} · ${res.action}`);
+  console.log(`  ${LINE}`);
+  if (res.input) console.log(`  输入       ${res.input}`);
+  if (res.out) console.log(`  输出目录   ${res.out}`);
+  if (res.image) console.log(`  新图片     ${res.image}`);
+  console.log('');
+  for (const f of res.files || []) {
+    switch (res.action) {
+      case 'fill': {
+        const keys = Object.entries(f.keys || {})
+          .map(([k, v]) => `${k}×${v}`).join(' ');
+        console.log(`  ✓ ${f.input_name} → ${f.output_name} · 替换 ${f.replacements} 处${keys ? `（${keys}）` : ''}`);
+        break;
+      }
+      case 'replace-image':
+        if (f.replaced === 0) {
+          console.log(`  – ${f.input_name} → ${f.output_name} · 跳过（没有该形状）`);
+        } else {
+          console.log(`  ✓ ${f.input_name} → ${f.output_name} · 替换图片 ${f.replaced} 处`);
+        }
+        break;
+      case 'extract-text':
+        console.log(`  ✓ ${f.input_name} → ${f.output_name} · ${f.slides} 页 · ${f.chars} 字符`);
+        break;
+      case 'info':
+        console.log(`  ✓ ${f.input_name} · ${f.pages} 页 · ${f.shapes} 个形状 · ${f.pictures} 张图片`);
+        break;
+      default:
+        console.log(`  ✓ ${f.input_name} → ${f.output_name}`);
+    }
+  }
+  if (res.unfilled && res.unfilled.length) {
+    console.log(`\n  ⚠ 还有 ${res.unfilled.length} 个占位符没给值：${res.unfilled.join('、')}`);
+    console.log('    确认 --set 的 key 和模板里的 {{key}} 完全一致（大小写、空格）。');
+  }
+  if (res.summary) console.log(`\n  ${res.summary}`);
+  if (res.artifacts && res.artifacts.length) {
+    console.log('\n  产物：');
+    for (const a of res.artifacts) console.log(`    ${a}`);
+  }
+  console.log('');
+}
+
+function humanDemo(res) {
+  console.log('');
+  console.log(`  ${TITLE} · 演示（--demo）`);
+  console.log(`  ${LINE}`);
+  console.log(`  演示目录   ${res.demoRoot}`);
+  console.log('');
+  for (const s of res.steps || []) {
+    console.log(`  ✓ ${String(s.step).padEnd(6)} ${s.action.padEnd(14)} ${s.summary}`);
+  }
+  console.log('\n  产物：');
+  for (const a of res.artifacts || []) console.log(`    ${a}`);
+  console.log('');
+}
+
+function callPython(py, action, payload) {
+  const r = spawnSync(py, [PY_SCRIPT, action, JSON.stringify(payload)], {
+    encoding: 'utf8',
+    maxBuffer: 128 * 1024 * 1024,
+  });
+  if (r.error) {
+    fail(`调用 python 失败：${r.error.message}`, PY_HINT, 3);
+  }
+  const lines = (r.stdout || '').trim().split('\n').filter(Boolean);
+  let result = null;
+  try {
+    result = JSON.parse(lines[lines.length - 1] || '');
+  } catch {
+    /* 下面统一报错 */
+  }
+  if (!result) {
+    const detail = (r.stderr || '').trim().split('\n').slice(-5).join('\n');
+    fail('Python 处理失败（没有拿到有效结果）', detail || PY_HINT, r.status || 1);
+  }
+  return result;
+}
+
+const argv = process.argv.slice(2);
+if (argv.length === 0) help();
+if (argv.includes('--help') || argv.includes('-h')) help();
+
+const opt = parseArgs(argv);
+const python = findPython();
+if (!python) {
+  fail('未找到 python3，无法处理 PPT 文件', PY_HINT, 3, opt.json);
+}
+
+if (opt.demo) {
+  const res = callPython(python, 'demo', {});
+  if (!res.ok) fail(res.message, res.hint, res.code || 1, opt.json);
+  if (opt.json) console.log(JSON.stringify(res, null, 2));
+  else humanDemo(res);
+  process.exit(0);
+}
+
+if (!opt.action) {
+  fail('缺少子命令', `可用子命令：${Object.keys(ACTIONS).join(' / ')}\n用 ${CMD} --help 查看详情。`, 2, opt.json);
+}
+if (!Object.hasOwn(ACTIONS, opt.action)) {
+  fail(`未知子命令：${opt.action}`, `可用子命令：${Object.keys(ACTIONS).join(' / ')}`, 2, opt.json);
+}
+if (!opt.input) {
+  fail('缺少 --input（文件或目录）', `例：${CMD} ${opt.action} --input ./PPT目录`, 2, opt.json);
+}
+if (opt.action === 'fill') {
+  if (opt.set.length === 0) {
+    fail('缺少 --set（要填的占位符）',
+      `例：${CMD} fill --input ./模板 --set 客户=客户甲 --set 金额=128000`, 2, opt.json);
+  }
+  const bad = opt.set.find((s) => !s.includes('=') || !s.split('=')[0].trim());
+  if (bad !== undefined) {
+    fail(`--set 需要 key=value 形式：${bad}`, '例：--set 客户=客户甲', 2, opt.json);
+  }
+}
+if (opt.action === 'replace-image') {
+  if (!opt.shape) {
+    fail('缺少 --shape（要替换的图片形状名）',
+      `例：${CMD} replace-image --input ./模板 --shape Logo --image ./logo.png`, 2, opt.json);
+  }
+  if (!opt.image) {
+    fail('缺少 --image（新图片文件）',
+      `例：${CMD} replace-image --input ./模板 --shape Logo --image ./logo.png`, 2, opt.json);
+  }
+}
+
+const payload = {
+  input: opt.input,
+  out: opt.out,
+  set: opt.set,
+  shape: opt.shape,
+  image: opt.image,
+};
+const res = callPython(python, opt.action, payload);
+if (!res.ok) fail(res.message, res.hint, res.code || 1, opt.json);
+
+if (opt.json) console.log(JSON.stringify(res, null, 2));
+else human(res);
+process.exit(0);

package/cordis.patch.yml

@@ -0,0 +1,4 @@
+# @deepwhale-cn/dsh-pptx-batch 的组合层：装上即注册 pptx-batch skill
+- insert:
+    - id: pptx-batch
+      name: '@deepwhale-cn/dsh-pptx-batch'

package/lib/index.js

@@ -0,0 +1,10 @@
+import { createPlugin, pkgRootFrom } from '@deepwhale-cn/dsh-guard-core/plugin';
+
+export const { name, inject, apply } = createPlugin({
+  name: 'pptx-batch',
+  pkgRoot: pkgRootFrom(import.meta.url),
+  skillFile: 'skill/pptx-batch.md',
+  binFile: 'bin/cli.mjs',
+  description: 'PPT 批量填模板 / 替换文字与图片 / 导出内容清单（python-pptx）',
+  whenToUse: '当用户要批量处理整目录的 PowerPoint（.pptx）时使用：按 {{key}} 批量填模板（客户名、金额、日期）、按形状名批量换图片（Logo）、提取每页文本到 txt、统计页数/形状数/图片数。典型说法：「这套模板有 30 份要按客户发」「把每份 PPT 里的旧 Logo 换掉」「把这批 pptx 的文字导出来核对」。不用于 .ppt 老格式、加密文档、需要保持复杂动画与版式的场景。',
+});

package/lib/pptx_tool.py

@@ -0,0 +1,705 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+dsh-pptx-batch 的真实处理逻辑（python-pptx）
+
+由 bin/cli.mjs 通过 spawnSync 调用：
+    python3 lib/pptx_tool.py <action> '<json payload>'
+
+约定：
+  - stdout 只输出一行 JSON（人类可读文案由 Node 侧负责）
+  - stderr 输出异常栈（调试用）
+  - 退出码：0 成功 / 1 运行失败 / 2 参数或输入问题 / 3 缺依赖
+  - 只读输入文件，所有产物写进 --out 目录（默认 <输入目录>/_输出）
+"""
+
+import json
+import os
+import re
+import shutil
+import struct
+import sys
+import tempfile
+import traceback
+import zlib
+from pathlib import Path
+
+try:
+    from pptx import Presentation
+    from pptx.enum.shapes import MSO_SHAPE_TYPE
+    from pptx.util import Inches
+except ImportError as exc:  # 缺依赖必须明确提示安装命令，不能静默
+    print(json.dumps({
+        "ok": False,
+        "code": 3,
+        "message": "缺少 Python 依赖：%s" % getattr(exc, "name", exc),
+        "hint": "请先安装：\n  python3 -m pip install python-pptx\n"
+                "如果 python3 也没有：\n  macOS: brew install python3\n  Ubuntu: sudo apt install python3",
+    }, ensure_ascii=False))
+    sys.exit(3)
+
+PPTX_EXT = ".pptx"
+SKIP_DIRS = {"_输出", "node_modules", ".git", "__pycache__", ".venv", "venv"}
+PLACEHOLDER_RE = re.compile(r"\{\{\s*([^{}]{1,60}?)\s*\}\}")
+DEMO_TITLE = "季度经营简报"
+DEMO_CLIENT = "示例客户甲"
+DEMO_AMOUNT = "¥ 128,000"
+
+
+# ── 错误 ──────────────────────────────────────────────────────────
+
+class ToolError(Exception):
+    def __init__(self, message, hint="", code=2):
+        super().__init__(message)
+        self.message = message
+        self.hint = hint
+        self.code = code
+
+
+def emit(obj):
+    print(json.dumps(obj, ensure_ascii=False))
+
+
+# ── 路径与文件收集 ────────────────────────────────────────────────
+
+def natural_key(text):
+    return [int(t) if t.isdigit() else t.lower() for t in re.split(r"(\d+)", text)]
+
+
+def resolve_out(payload, input_path):
+    """输出目录：--out 优先，否则 <输入目录>/_输出。"""
+    out = payload.get("out")
+    if out:
+        return Path(out).expanduser().resolve()
+    base = Path(input_path).expanduser().resolve()
+    if not base.is_dir():
+        base = base.parent
+    return base / "_输出"
+
+
+def collect_pptx(input_path, out_dir=None):
+    """接受单个 .pptx 或目录（递归），按文件名自然排序。"""
+    if not input_path:
+        raise ToolError("缺少 --input", "例：fill --input ./模板目录 --set 客户=客户甲")
+    root = Path(input_path).expanduser().resolve()
+    if not root.exists():
+        raise ToolError(
+            "输入不存在：%s" % input_path,
+            "请检查路径是否正确；传目录会递归处理其中的 .pptx 文件。",
+        )
+    skip_out = set()
+    if out_dir:
+        try:
+            skip_out = {str(Path(out_dir).resolve())}
+        except OSError:
+            skip_out = set()
+    if root.is_file():
+        if root.suffix.lower() != PPTX_EXT:
+            raise ToolError(
+                "输入不是 .pptx 文件：%s" % root.name,
+                "本插件只处理 PowerPoint 2007+ 的 .pptx；.ppt 请先另存为 .pptx。",
+            )
+        return [root]
+    files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        current = str(Path(dirpath).resolve())
+        if current in skip_out:
+            dirnames[:] = []
+            continue
+        dirnames[:] = sorted(
+            [d for d in dirnames if d not in SKIP_DIRS and not d.startswith("~$")],
+            key=natural_key,
+        )
+        for name in filenames:
+            if name.startswith("~$"):
+                continue  # PowerPoint 打开时的临时文件
+            p = Path(dirpath) / name
+            if p.suffix.lower() == PPTX_EXT:
+                files.append(p)
+    files.sort(key=lambda p: natural_key(str(p.relative_to(root))))
+    if not files:
+        raise ToolError(
+            "目录里没有 .pptx 文件：%s" % root,
+            "确认目录选对了；本插件不处理 .ppt（请先另存为 .pptx）。",
+        )
+    return files
+
+
+def unique_path(directory, filename):
+    """同名文件不覆盖，追加 _1/_2 序号。"""
+    directory = Path(directory)
+    target = directory / filename
+    if not target.exists():
+        return target
+    stem, suffix = target.stem, target.suffix
+    n = 1
+    while (directory / ("%s_%d%s" % (stem, n, suffix))).exists():
+        n += 1
+    return directory / ("%s_%d%s" % (stem, n, suffix))
+
+
+# ── 形状遍历 ──────────────────────────────────────────────────────
+
+def shape_type_of(shape):
+    try:
+        return shape.shape_type
+    except Exception:
+        return None
+
+
+def is_group(shape):
+    return shape_type_of(shape) == MSO_SHAPE_TYPE.GROUP
+
+
+def is_picture(shape):
+    return shape_type_of(shape) == MSO_SHAPE_TYPE.PICTURE
+
+
+def iter_shapes(shapes):
+    """按文档顺序遍历形状，组合形状递归展开（只读遍历，不改变结构）。"""
+    for shape in shapes:
+        yield shape
+        if is_group(shape):
+            try:
+                yield from iter_shapes(shape.shapes)
+            except Exception:
+                continue  # 极少数残缺组合形状取不到子形状：跳过
+
+
+def shape_kind(shape):
+    if getattr(shape, "has_table", False):
+        return "table"
+    if getattr(shape, "has_chart", False):
+        return "chart"
+    if is_picture(shape):
+        return "picture"
+    if is_group(shape):
+        return "group"
+    if getattr(shape, "has_text_frame", False):
+        return "text"
+    return "shape"
+
+
+def shape_paragraphs(shape):
+    """形状里可编辑的段落：文本框 + 表格单元格。"""
+    if getattr(shape, "has_text_frame", False):
+        yield from shape.text_frame.paragraphs
+    if getattr(shape, "has_table", False):
+        for row in shape.table.rows:
+            for cell in row.cells:
+                yield from cell.text_frame.paragraphs
+
+
+def iter_paragraphs(prs):
+    """整份 PPT 里所有可编辑段落（每页的文本框、表格单元格，组合形状递归）。"""
+    for slide in prs.slides:
+        for shape in iter_shapes(slide.shapes):
+            yield from shape_paragraphs(shape)
+
+
+# ── 文本替换（尽量保留 run 级格式） ───────────────────────────────
+
+def sub_paragraph(paragraph, pattern, replacement):
+    """
+    在单个段落里按正则替换，返回替换次数。
+
+    先按 run 拼出整段文字再定位匹配，然后把「匹配外的字符」原样归还原来的 run，
+    「替换后的文字」落到匹配起点所在的 run 上 —— 所以没被匹配碰到的 run 格式完全不变，
+    只有真正跨 run 的匹配才会把这几段文字并到起始 run 的格式上。
+    """
+    runs = list(paragraph.runs)
+    if not runs:
+        return 0
+    texts = [run.text for run in runs]
+    full = "".join(texts)
+    if not full:
+        return 0
+    matches = list(pattern.finditer(full))
+    if not matches:
+        return 0
+    owner = []
+    for idx, text in enumerate(texts):
+        owner.extend([idx] * len(text))
+    pieces = [[] for _ in runs]
+    cursor = 0
+    for match in matches:
+        start, end = match.span()
+        if end <= cursor:
+            continue
+        if start > cursor:
+            for pos in range(cursor, start):
+                pieces[owner[pos]].append(full[pos])
+        pieces[owner[start]].append(replacement)
+        cursor = end
+    for pos in range(cursor, len(full)):
+        pieces[owner[pos]].append(full[pos])
+    for run, old, parts in zip(runs, texts, pieces):
+        new = "".join(parts)
+        if new != old:
+            run.text = new
+    return len(matches)
+
+
+def paragraph_text(paragraph):
+    try:
+        return paragraph.text
+    except Exception:
+        return ""
+
+
+def leftover_placeholders(prs):
+    """填完之后还剩哪些 {{...}} —— 帮用户抓模板里拼错的 key。"""
+    left = []
+    for paragraph in iter_paragraphs(prs):
+        for match in PLACEHOLDER_RE.finditer(paragraph_text(paragraph)):
+            key = match.group(1).strip()
+            if key and key not in left:
+                left.append(key)
+    return left
+
+
+# ── 各动作 ────────────────────────────────────────────────────────
+
+def parse_sets(raw_sets):
+    if not raw_sets:
+        raise ToolError(
+            "缺少 --set（要填的占位符）",
+            "每个值用 key=value，可重复：\n"
+            "  fill --input ./模板 --set 客户=客户甲 --set 金额=1000",
+        )
+    pairs, seen = [], set()
+    for item in raw_sets:
+        if "=" not in item:
+            raise ToolError(
+                "--set 需要 key=value 形式：%s" % item,
+                "例：--set 客户=客户甲（等号左边是模板里的 {{key}}，右边是要填的值）",
+            )
+        key, value = item.split("=", 1)
+        key = key.strip()
+        if not key:
+            raise ToolError(
+                "--set 的 key 不能为空：%s" % item,
+                "例：--set 客户=客户甲",
+            )
+        if key in seen:
+            raise ToolError(
+                "--set 重复给了同一个 key：%s" % key,
+                "同一个 key 只写一次，需要不同值请分两次运行。",
+            )
+        seen.add(key)
+        pairs.append((key, value))
+    return pairs
+
+
+def action_fill(payload):
+    files = collect_pptx(payload.get("input"))
+    out = resolve_out(payload, payload.get("input"))
+    pairs = parse_sets(payload.get("set"))
+    out.mkdir(parents=True, exist_ok=True)
+    results, total, unfilled = [], 0, []
+    for src in files:
+        prs = Presentation(str(src))
+        counts = {}
+        for key, value in pairs:
+            pattern = re.compile(r"\{\{\s*" + re.escape(key) + r"\s*\}\}")
+            for paragraph in iter_paragraphs(prs):
+                n = sub_paragraph(paragraph, pattern, value)
+                if n:
+                    counts[key] = counts.get(key, 0) + n
+        file_total = sum(counts.values())
+        left = leftover_placeholders(prs)
+        for key in left:
+            if key not in unfilled:
+                unfilled.append(key)
+        target = unique_path(out, src.name)
+        prs.save(str(target))
+        results.append({
+            "input": str(src),
+            "input_name": src.name,
+            "output": str(target),
+            "output_name": target.name,
+            "replacements": file_total,
+            "keys": counts,
+            "unfilled": left,
+        })
+        total += file_total
+    summary = "处理 %d 个文件，共替换 %d 处占位符" % (len(files), total)
+    if unfilled:
+        summary += "；仍有未赋值占位符 %d 个：%s" % (len(unfilled), "、".join(unfilled[:8]))
+    return {
+        "action": "fill",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "out": str(out),
+        "files": results,
+        "replacements": total,
+        "unfilled": unfilled,
+        "summary": summary,
+        "artifacts": [r["output"] for r in results],
+    }
+
+
+def picture_names(prs):
+    names = []
+    for slide in prs.slides:
+        for shape in iter_shapes(slide.shapes):
+            if is_picture(shape) and shape.name and shape.name not in names:
+                names.append(shape.name)
+    return names
+
+
+def action_replace_image(payload):
+    files = collect_pptx(payload.get("input"))
+    out = resolve_out(payload, payload.get("input"))
+    shape_name = (payload.get("shape") or "").strip()
+    image_arg = (payload.get("image") or "").strip()
+    if not shape_name:
+        raise ToolError(
+            "缺少 --shape（要替换的图片形状名）",
+            "例：replace-image --input ./模板 --shape Logo --image ./logo.png\n"
+            "形状名要和 PowerPoint 选择窗格（或「开始 → 选择 → 选择窗格」）里显示的名字完全一致。",
+        )
+    if not image_arg:
+        raise ToolError(
+            "缺少 --image（新图片文件）",
+            "例：replace-image --input ./模板 --shape Logo --image ./logo.png",
+        )
+    image = Path(image_arg).expanduser().resolve()
+    if not image.exists() or not image.is_file():
+        raise ToolError(
+            "新图片不存在：%s" % image_arg,
+            "确认 --image 指向一个 png / jpg / gif / bmp / tiff 图片文件。",
+        )
+    out.mkdir(parents=True, exist_ok=True)
+    results, total = [], 0
+    non_picture_hits, all_picture_names = [], []
+    for src in files:
+        prs = Presentation(str(src))
+        replaced, non_picture = 0, []
+        for slide in prs.slides:
+            rId = None
+            for shape in iter_shapes(slide.shapes):
+                if shape.name != shape_name:
+                    continue
+                if not is_picture(shape):
+                    non_picture.append(shape_kind(shape))
+                    continue
+                if rId is None:
+                    try:
+                        _part, rId = slide.part.get_or_add_image_part(str(image))
+                    except Exception:
+                        raise ToolError(
+                            "新图片无法读取：%s" % image.name,
+                            "支持 png / jpg / gif / bmp / tiff；确认文件没损坏、后缀与内容一致。",
+                        )
+                # 只换图片内容，保留原形状的位置与尺寸（版面不动）
+                shape._element.blipFill.blip.rEmbed = rId
+                replaced += 1
+        for kind in non_picture:
+            item = "%s（%s）" % (src.name, kind)
+            if item not in non_picture_hits:
+                non_picture_hits.append(item)
+        names = picture_names(prs)
+        for name in names:
+            if name not in all_picture_names:
+                all_picture_names.append(name)
+
+        target = unique_path(out, src.name)
+        if replaced == 0:
+            # 这一份没有该形状：原样带过去，不清空产物目录，也不假装替换过
+            shutil.copyfile(str(src), str(target))
+            results.append({
+                "input": str(src),
+                "input_name": src.name,
+                "output": str(target),
+                "output_name": target.name,
+                "replaced": 0,
+                "image": image.name,
+                "skipped": "没有名为 %s 的图片形状" % shape_name,
+            })
+            continue
+        prs.save(str(target))
+        results.append({
+            "input": str(src),
+            "input_name": src.name,
+            "output": str(target),
+            "output_name": target.name,
+            "replaced": replaced,
+            "image": image.name,
+        })
+        total += replaced
+
+    if total == 0:
+        if non_picture_hits:
+            raise ToolError(
+                "形状「%s」不是图片（%s）" % (shape_name, " / ".join(non_picture_hits[:6])),
+                "replace-image 只能替换图片形状；文字替换请用 fill。",
+            )
+        raise ToolError(
+            "没有名为「%s」的图片形状" % shape_name,
+            ("这些文件里的图片形状名：" + " / ".join(all_picture_names[:12])) if all_picture_names
+            else "这些文件里没有任何图片形状。",
+        )
+
+    skipped = sum(1 for r in results if r["replaced"] == 0)
+    summary = "处理 %d 个文件，替换图片形状 %d 处（形状名：%s）" % (len(files), total, shape_name)
+    if skipped:
+        summary += "；%d 个文件没有该形状，已原样带过" % skipped
+    return {
+        "action": "replace-image",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "out": str(out),
+        "files": results,
+        "replaced": total,
+        "skipped": skipped,
+        "image": str(image),
+        "summary": summary,
+        "artifacts": [r["output"] for r in results],
+    }
+
+
+def slide_block(slide, index):
+    lines = []
+    title, title_id = "", None
+    try:
+        title_shape = slide.shapes.title
+        if title_shape is not None and getattr(title_shape, "has_text_frame", False):
+            title = title_shape.text_frame.text.strip()
+            title_id = get_shape_id(title_shape)
+    except Exception:
+        title, title_id = "", None
+    head = "=== 第 %d 页" % index
+    if title:
+        head += " · " + " ".join(title.split())
+    lines.append(head + " ===")
+    for shape in iter_shapes(slide.shapes):
+        if getattr(shape, "has_table", False):
+            rows = []
+            for row in shape.table.rows:
+                cells = [" ".join(c.text_frame.text.split()) for c in row.cells]
+                if any(cells):
+                    rows.append(" | ".join(cells))
+            if rows:
+                lines.append("[表格 · %s]" % shape.name)
+                lines.extend(rows)
+            continue
+        if not getattr(shape, "has_text_frame", False):
+            continue
+        if title_id is not None and get_shape_id(shape) == title_id:
+            continue  # 标题已经在页头里
+        text = shape.text_frame.text.strip()
+        if not text:
+            continue
+        lines.append("[正文 · %s]" % shape.name)
+        lines.extend(text.split("\n"))
+    try:
+        if slide.has_notes_slide:
+            notes = slide.notes_slide.notes_text_frame.text.strip()
+            if notes:
+                lines.append("[备注]")
+                lines.extend(notes.split("\n"))
+    except Exception:
+        pass  # 备注页异常不影响正文提取
+    return "\n".join(lines)
+
+
+def get_shape_id(shape):
+    try:
+        return shape.shape_id
+    except Exception:
+        return None
+
+
+def action_extract_text(payload):
+    files = collect_pptx(payload.get("input"))
+    out = resolve_out(payload, payload.get("input"))
+    out.mkdir(parents=True, exist_ok=True)
+    results = []
+    for src in files:
+        prs = Presentation(str(src))
+        blocks = [slide_block(slide, i) for i, slide in enumerate(prs.slides, 1)]
+        text = "\n\n".join(blocks).strip() + "\n"
+        target = unique_path(out, src.stem + ".txt")
+        target.write_text(text, encoding="utf-8")
+        results.append({
+            "input": str(src),
+            "input_name": src.name,
+            "output": str(target),
+            "output_name": target.name,
+            "slides": len(prs.slides),
+            "chars": len(text),
+        })
+    return {
+        "action": "extract-text",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "out": str(out),
+        "files": results,
+        "summary": "提取 %d 个文件、共 %d 页文本" % (len(files), sum(r["slides"] for r in results)),
+        "artifacts": [r["output"] for r in results],
+    }
+
+
+def action_info(payload):
+    files = collect_pptx(payload.get("input"))
+    results = []
+    for src in files:
+        prs = Presentation(str(src))
+        shapes = sum(len(slide.shapes) for slide in prs.slides)
+        pictures = 0
+        for slide in prs.slides:
+            pictures += sum(1 for shape in iter_shapes(slide.shapes) if is_picture(shape))
+        results.append({
+            "input": str(src),
+            "input_name": src.name,
+            "pages": len(prs.slides),
+            "shapes": shapes,
+            "pictures": pictures,
+        })
+    return {
+        "action": "info",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "files": results,
+        "pages": sum(r["pages"] for r in results),
+        "summary": "共 %d 个文件、%d 页" % (len(files), sum(r["pages"] for r in results)),
+        "artifacts": [],
+    }
+
+
+# ── demo ─────────────────────────────────────────────────────────
+
+def write_solid_png(path, rgb, size=16):
+    """手写一张纯色 PNG（不依赖 Pillow），给演示用的示例图片。"""
+    width = height = size
+    raw = b"".join(b"\x00" + bytes(rgb) * width for _ in range(height))
+
+    def chunk(tag, data):
+        return (struct.pack(">I", len(data)) + tag + data
+                + struct.pack(">I", zlib.crc32(tag + data) & 0xFFFFFFFF))
+
+    ihdr = struct.pack(">IIBBBBB", width, height, 8, 2, 0, 0, 0)
+    png = (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", ihdr)
+           + chunk(b"IDAT", zlib.compress(raw)) + chunk(b"IEND", b""))
+    Path(path).write_bytes(png)
+
+
+def make_demo_deck(path, logo_path, client, amount, rows=None):
+    """造一份带 {} 占位符 + 表格 + 图片形状的演示模板。"""
+    prs = Presentation()
+    slide = prs.slides.add_slide(prs.slide_layouts[5])  # Title Only
+    slide.shapes.title.text = "{{title}}"
+
+    box = slide.shapes.add_textbox(Inches(0.8), Inches(1.8), Inches(6.2), Inches(1.6))
+    frame = box.text_frame
+    frame.word_wrap = True
+    frame.paragraphs[0].text = "客户：{{client}}"
+    frame.add_paragraph().text = "金额：{{amount}}"
+
+    table_rows = rows or [["项目", "内容"], ["{{client}}", "{{amount}}"]]
+    table_shape = slide.shapes.add_table(
+        len(table_rows), len(table_rows[0]), Inches(0.8), Inches(3.6), Inches(6.2), Inches(1.4)
+    )
+    for i, row in enumerate(table_rows):
+        for j, value in enumerate(row):
+            table_shape.table.cell(i, j).text = value
+
+    picture = slide.shapes.add_picture(str(logo_path), Inches(7.2), Inches(0.8),
+                                       Inches(2.2), Inches(2.2))
+    picture.name = "Logo"
+    prs.save(str(path))
+
+
+def action_demo(payload):
+    root = Path(tempfile.mkdtemp(prefix="dsh-pptx-batch-demo-"))
+    inputs = root / "样例"
+    inputs.mkdir(parents=True, exist_ok=True)
+    old_logo = root / "logo-旧.png"
+    new_logo = root / "logo-新.png"
+    write_solid_png(old_logo, (200, 30, 30))
+    write_solid_png(new_logo, (20, 120, 220))
+
+    make_demo_deck(inputs / "简报A.pptx", old_logo, "{{client}}", "{{amount}}")
+    make_demo_deck(inputs / "简报B.pptx", old_logo, "{{client}}", "{{amount}}",
+                   rows=[["项目", "金额"], ["{{client}}", "{{amount}}"]])
+    out = root / "输出"
+    steps, artifacts = [], []
+
+    def record(name, result):
+        steps.append({
+            "step": name,
+            "action": result.get("action"),
+            "summary": result.get("summary", ""),
+            "out": result.get("out"),
+        })
+        artifacts.extend(result.get("artifacts", []))
+
+    filled_dir = out / "fill"
+    record("填占位符", action_fill({
+        "input": str(inputs), "out": str(filled_dir),
+        "set": ["title=" + DEMO_TITLE, "client=" + DEMO_CLIENT, "amount=" + DEMO_AMOUNT],
+    }))
+    record("换图片", action_replace_image({
+        "input": str(filled_dir), "out": str(out / "replace-image"),
+        "shape": "Logo", "image": str(new_logo),
+    }))
+    record("提文本", action_extract_text({
+        "input": str(out / "replace-image"), "out": str(out / "extract-text"),
+    }))
+    record("看结构", action_info({"input": str(inputs)}))
+
+    return {
+        "action": "demo",
+        "demoRoot": str(root),
+        "inputRoot": str(inputs),
+        "steps": steps,
+        "summary": "演示完成：%d 个动作全部跑通，产物 %d 个" % (len(steps), len(artifacts)),
+        "artifacts": artifacts,
+    }
+
+
+ACTIONS = {
+    "fill": action_fill,
+    "replace-image": action_replace_image,
+    "extract-text": action_extract_text,
+    "info": action_info,
+    "demo": action_demo,
+}
+
+
+def main(argv):
+    if len(argv) < 3:
+        emit({"ok": False, "code": 2,
+              "message": "内部调用参数不足：需要 <action> 和 JSON payload",
+              "hint": "请通过 bin/cli.mjs 调用本脚本。"})
+        return 2
+    action, raw = argv[1], argv[2]
+    try:
+        payload = json.loads(raw) if raw else {}
+    except json.JSONDecodeError as exc:
+        emit({"ok": False, "code": 2, "message": "参数 JSON 解析失败：%s" % exc, "hint": ""})
+        return 2
+    fn = ACTIONS.get(action)
+    if not fn:
+        emit({"ok": False, "code": 2, "message": "未知动作：%s" % action,
+              "hint": "可用动作：%s" % " / ".join(k for k in ACTIONS if k != "demo")})
+        return 2
+    try:
+        result = fn(payload)
+        result.setdefault("ok", True)
+        emit(result)
+        return 0
+    except ToolError as exc:
+        emit({"ok": False, "code": exc.code, "message": exc.message, "hint": exc.hint})
+        return exc.code
+    except PermissionError as exc:
+        emit({"ok": False, "code": 1,
+              "message": "没有权限读写文件：%s" % exc,
+              "hint": "检查文件是否被 PowerPoint 占用、或输出目录是否有写权限。"})
+        return 1
+    except Exception as exc:  # noqa: BLE001 —— 兜底，保证永远输出 JSON
+        traceback.print_exc(file=sys.stderr)
+        emit({"ok": False, "code": 1, "message": "处理失败：%s" % exc,
+              "hint": "文件可能已损坏或被加密；可先用 PowerPoint 打开另存一次再试。"})
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@deepwhale-cn/dsh-pptx-batch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "PPT 批量填模板 / 替换文字与图片 / 导出内容清单（python-pptx）",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["dsh", "dsh-plugin", "deepseek-harness", "skill", "tool", "pptx-batch"],
+  "files": ["lib", "bin", "skill", "cordis.patch.yml", "tests/fixtures", "README.md", "LICENSE"],
+  "main": "./lib/index.js",
+  "exports": { ".": "./lib/index.js", "./package.json": "./package.json" },
+  "bin": { "dsh-pptx-batch": "./bin/cli.mjs" },
+  "engines": { "dsh": ">=0.1.0-rc.6 <0.3.0", "node": ">=18" },
+  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } },
+  "dependencies": { "@deepwhale-cn/dsh-guard-core": "^0.5.1" },
+  "peerDependencies": { "@deepseek-ai/dsh-skill": "*" },
+  "repository": { "type": "git", "url": "git+https://github.com/feely0208/dsh-pptx-batch.git" },
+  "homepage": "https://www.deepwhale.org.cn/skills.html",
+  "bugs": { "url": "https://github.com/feely0208/dsh-pptx-batch/issues" }
+}

package/skill/pptx-batch.md

@@ -0,0 +1,68 @@
+# PPT 批量处理
+
+**一句话**：整目录的 PPT 一次处理完 —— 批量填模板占位符、按形状名换图片、提取每页文本、看页数/形状数/图片数。只读输入，产物单独输出，不覆盖原文件。
+
+## 什么时候用
+
+用户说这些话时用：
+
+- 「这套模板有 30 份按客户发，帮我把 `{{客户}}`、`{{金额}}` 填上」
+- 「每份 PPT 右上角那个 Logo 都要换成新版，形状名是 Logo」
+- 「把这几份 pptx 每页的文字导成 txt，我要核对内容」
+- 「看看这批 PPT 各有多少页、多少张图」
+- 用户给了一个装了很多 `.pptx` 的目录，要求批量处理其中文字或图片
+
+## 怎么调用
+
+```bash
+<cli 路径> --help
+```
+
+```bash
+# 批量填占位符（--set key=value 可重复；替换幻灯片里的 {{key}}）
+<cli 路径> fill --input <文件或目录> [--out <输出目录>] \
+  --set 客户=客户甲 [--set 金额=128000] [--json]
+
+# 按形状名换图片（形状名精确匹配，大小写敏感）
+<cli 路径> replace-image --input <文件或目录> [--out <输出目录>] \
+  --shape Logo --image <新图片文件> [--json]
+
+# 提取每页文本到同名 .txt（标题 + 正文 + 表格 + 备注）
+<cli 路径> extract-text --input <文件或目录> [--out <输出目录>] [--json]
+
+# 页数 / 形状数 / 图片数
+<cli 路径> info --input <文件或目录> [--json]
+
+# 自造样例跑完整流程（不碰用户文件），先跑这个确认环境正常
+<cli 路径> --demo
+```
+
+## 输出约定（要向用户说清）
+
+- **不修改输入文件**；输出默认写到 `<输入目录>/_输出`，可用 `--out` 指定。
+- 同名产物不覆盖：自动变成 `简报_1.pptx`、`简报_2.pptx`。
+- 目录递归处理，跳过 `~$` 临时文件和 `_输出` 目录。
+- 成功退出码 0；参数/输入错误退出码 2；缺依赖退出码 3；运行失败退出码 1。
+- `--json` 输出结构化结果（每个文件的产物路径、替换次数、页数/形状数/图片数等）。
+- `fill` 会把「填完之后还剩哪些 `{{...}}`」报在 `unfilled` 里 —— 用来抓模板里拼错的 key。
+- `replace-image` 批量时，**没有该形状的文件原样带到输出目录**（JSON 里 `replaced: 0` + `skipped`），
+  只有当整批都没有这个形状时才报错非 0 退出，避免打错一个字就把整批弄失败。
+
+## 边界（必须向用户说清）
+
+- 只支持 `.pptx`；`.ppt` 老格式、`.pptm`、加密文档不支持，需先另存为 `.pptx`。
+- `fill` 覆盖**文本框、占位符、表格单元格、组合形状里的文本框**；
+  **不处理**图表文字、SmartArt 文字、图片里的文字、批注、母版/版式上的文字，也不跨段落匹配。
+- `fill` 的匹配是**字面匹配**（`{{key}}`，key 大小写敏感，允许 `{{  key  }}` 这种空格），不支持正则；
+  同一个 key 一次只能给一个值。
+- **格式尽量保留但不保证 100%**：占位符整段在一个 run 里时，该 run 的字体/字号/颜色完全不动；
+  跨多个 run 的匹配会把这几段文字并到起始 run 的格式上，中间 run 的局部格式会丢。
+  重要模板先跑一份对比，再批量用。
+- `replace-image` 只换**图片内容**：形状的位置、尺寸、名称都不变。新图比例和原图不同时会被**拉伸**，
+  裁剪（crop）设置也沿用原来的；不支持按图片内容或页码挑选，只按形状名，同名形状会全部替换。
+- `extract-text` 提取标题、正文、表格、备注页文字；不提取图表数据、SmartArt、页码和母版文字，
+  图片只留位置不留文字（没有 OCR）。
+- `info` 的「形状数」是每页顶层形状数之和（组合形状算 1 个，其内部形状不计入），
+  「图片数」包含组合形状里的图片。
+- 缺 `python3` 或 `python-pptx` 时会明确打印安装命令（`python3 -m pip install python-pptx`），不会静默失败。
+- 不联网、不上传文件，全部在本机由 python-pptx 处理。