@deepwhale-cn/dsh-docx-batch 0.0.0-stage → 0.1.3

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,105 @@
-# Temporary Holding Version
+# @deepwhale-cn/dsh-docx-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-docx-batch)
+
+**整目录的 Word 一次处理完**：批量替换文本、提取正文、按文件名合并、列页眉页脚、转 Markdown —— 不打开 Word，不动原文件。
+
+**关键词**：Word 批量替换 · docx 批量处理 · 批量合并 Word · 提取 Word 文本 · Word 转 Markdown · 页眉页脚提取 · 合同批量改甲方 · 命令行处理 Word
+
+## 不装会怎样
+
+50 份合同要统一把甲方「深鲸科技」改成「深海鲸」：不装就得逐份打开 Word、Ctrl+H、保存、关掉，
+半小时起步，改到第 37 份时手一滑漏一份也没人发现。
+
+几十份周报要合成一份、把 Word 文档塞进知识库前要先转成 Markdown、需要核对每份文档的页眉页脚
+写的是什么 —— 这些都属于「机械但量大」的活，人工做既慢又容易漏。
+
+更麻烦的是：直接让 AI 改原文件，一旦改坏没有退路。这个插件只读输入，所有产物写到单独的输出目录，
+同名文件自动加序号、不覆盖任何东西。
+
+## 能做什么
+
+| 子命令 | 作用 | 产物（可核对） |
+|---|---|---|
+| `replace` | 整目录批量替换文本，`--from`/`--to` 可多组 | 替换后的 `.docx` 副本；JSON 里给出每个文件替换了几处 |
+| `extract` | 提取正文文本（含表格） | 每个文档一个 `.txt` |
+| `merge` | 按文件名自然顺序合并成一个 docx（正文 + 表格） | `merged.docx`，段落数只增不减 |
+| `headers` | 列出每份文档每一节的页眉、页脚文本 | `headers.txt` |
+| `to-md` | 按「标题样式 → `#`、表格 → Markdown 表格」转换 | 每个文档一个 `.md` |
+
+共同约定：
+
+- **不修改输入文件**，默认输出到 `<输入目录>/_输出`，可用 `--out` 指定；
+- **同名文件不覆盖**：已存在时自动变成 `合同_1.docx`、`合同_2.docx`；
+- 目录递归处理，自动跳过 Word 临时文件（`~$` 开头）和 `_输出` 目录；
+- `--json` 输出结构化结果，方便脚本 / CI 断言；出错时退出码非 0 并说明缺什么。
+
+```bash
+# 整目录替换，多组同时替换
+dsh-docx-batch replace --input ./合同 --out ./合同_新 \
+  --from 深鲸科技 --to 深海鲸 --from 2024 --to 2026
+
+# 提取正文
+dsh-docx-batch extract --input ./合同 --out ./文本
+
+# 按文件名顺序合并
+dsh-docx-batch merge --input ./周报 --out ./合并
+
+# 页眉页脚清单 / 转 Markdown
+dsh-docx-batch headers --input ./合同
+dsh-docx-batch to-md --input ./合同 --out ./md
+```
+
+## 不能做什么
+
+- ❌ **不保证排版 100% 不变**：替换跨多个 run（同一段里被拆开的文字块）时会合并该段落的 run，
+  段落内的局部加粗、字号、颜色可能丢失。重要文档请先跑一份对比再批量用。
+- ❌ 不处理 `.doc`（老格式）、`.docm`、加密/需要密码打开的文档；`.doc` 请先另存为 `.docx`。
+- ❌ 不处理脚注、尾注、批注、文本框、SmartArt、图片里的文字 —— 只覆盖正文段落、表格、页眉页脚。
+- ❌ `merge` 只合并正文和表格；页眉页脚、样式主题不合并，复杂排版（分栏、自动编号域）会退化为纯文本顺序。
+- ❌ `headers` 只**读**页眉页脚，不改；`replace` 能改页眉页脚里的文字。
+- ❌ **转 Markdown 会丢东西**：批注 / 修订痕迹 / 复杂表格样式（合并单元格降级为普通表格）/ 图片位置与浮动排版 / 脚注尾注 —— 只保留标题、段落、列表与基础表格文字，适合进知识库，不适合当排版成品。
+- ❌ 不是格式转换器：不导出 PDF、不做 OCR、不做批量重命名。
+- ❌ 替换是**字面匹配**，大小写敏感，不支持正则；`--from` 是空字符串之类无意义输入不做特殊处理。
+- ✅ 全部在本机由 python-docx 处理，不联网、不上传文档。
+
+## 安装
+
+```bash
+dsh plugin --profile web add @deepwhale-cn/dsh-docx-batch
+```
+
+运行依赖本机的 **python3 + python-docx**（插件不会替你装）。缺依赖时 CLI 会直接打印安装命令：
+
+```bash
+python3 -m pip install python-docx
+# macOS 没有 python3 时
+brew install python3
+```
+
+## 用法
+
+```bash
+dsh-docx-batch --help
+dsh-docx-batch --demo        # 自造样例文件跑完整流程，打印产物路径
+dsh-docx-batch <action> --input <文件或目录> [--out <目录>] [--json]
+```
+
+`--demo` 会在系统临时目录里造样例文档并依次跑 replace / extract / to-md / merge / headers，
+不动你的任何文件，跑完直接看产物路径就知道它能干什么。
+
+## License
+
+MIT © 温州深鲸智能科技有限公司
+
+## 面板（0.1.1 起）
+
+装上后侧栏会多一个「Word 批量」图标，点开即可：
+
+- 选操作：批量替换 / 提取正文 / 合并 / 页眉页脚 / 转 Markdown
+- 填文件或目录、输出目录（留空 = `<输入目录>/_输出`）
+- 批量替换时每行写一组「旧 → 新」
+- 点「开始处理」，结果直接显示在面板里
+
+面板与 CLI 是同一套内核（`lib/docx_tool.py`），能力完全一致；所有处理都在本机完成，不上传文件。
+需要 `python3` + `python-docx`（面板里会给出提示）。

package/bin/cli.mjs

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+/**
+ * Word 批量处理 CLI
+ *
+ * 形态：
+ *   dsh-docx-batch --help                 （无参数也打印 help，退出 0）
+ *   dsh-docx-batch --demo                 （自造样例跑完整流程，退出 0）
+ *   dsh-docx-batch <action> --input <文件或目录> [--out <目录>] [--json]
+ *
+ * 真实逻辑全部委托 python3 + python-docx（lib/docx_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', 'docx_tool.py');
+const TITLE = 'Word 批量处理';
+const CMD = 'dsh-docx-batch';
+const ACTIONS = {
+  replace: '批量替换文本（--from 旧 --to 新，可多组）',
+  extract: '提取正文文本到 .txt',
+  merge: '按文件名顺序合并成一个 docx',
+  headers: '列出页眉页脚文本',
+  'to-md': '段落/表格转 Markdown',
+};
+const PY_HINT = [
+  '需要 python3 + python-docx。安装：',
+  '  python3 -m pip install python-docx',
+  '没有 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(9)}${v}`).join('\n')}
+
+参数：
+  --input, -i   .docx 文件或目录（目录递归处理）
+  --out, -o     输出目录；默认 <输入目录>/_输出；同名文件不覆盖，自动加序号
+  --from        要替换的旧文本（可重复，与 --to 按顺序配对）
+  --to          替换后的新文本（可重复）
+  --json        输出 JSON（给脚本/CI 用）
+  --demo        自造样例文件，跑完整流程并打印产物路径
+
+示例：
+  ${CMD} replace --input ./合同 --from 深鲸科技 --to 深海鲸
+  ${CMD} extract --input ./合同 --out ./文本
+  ${CMD} merge --input ./周报 --out ./合并
+  ${CMD} headers --input ./合同
+  ${CMD} to-md --input ./合同 --out ./md
+
+依赖：python3 + python-docx（缺失时会提示安装命令）`);
+  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.DOCX_BATCH_PYTHON,
+    'python3',
+    '/opt/homebrew/bin/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, from: [], to: [], json: false, demo: false };
+  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 (flag === '--input' || flag === '-i' || flag === '--out' || flag === '-o' ||
+        flag === '--from' || flag === '--to') {
+      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 === '--from') opt.from.push(value);
+      else opt.to.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}`);
+  for (const f of res.files || []) {
+    let extra = '';
+    if (f.replacements !== undefined) extra = ` · 替换 ${f.replacements} 处`;
+    else if (f.chars !== undefined) extra = ` · ${f.chars} 字符`;
+    else if (f.sections !== undefined) extra = ` · ${f.sections} 节`;
+    else if (f.paragraphs !== undefined) extra = ` · ${f.paragraphs} 段`;
+    console.log(`  ✓ ${f.input_name} → ${f.output_name}${extra}`);
+  }
+  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.action).padEnd(8)} ${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，无法处理 Word 文件', 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 ./文档目录`, 2, opt.json);
+}
+if (opt.action === 'replace') {
+  if (opt.from.length === 0) {
+    fail('缺少 --from（要替换的旧文本）', `例：${CMD} replace --input ./合同 --from 旧文本 --to 新文本`, 2, opt.json);
+  }
+  if (opt.from.length !== opt.to.length) {
+    fail(
+      `--from 与 --to 数量不一致（${opt.from.length} vs ${opt.to.length}）`,
+      '每一组 --from 都要配一个 --to，按顺序一一对应。',
+      2,
+      opt.json,
+    );
+  }
+}
+
+const payload = { input: opt.input, out: opt.out, from: opt.from, to: opt.to };
+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-docx-batch 的组合层：装上即注册 docx-batch skill
+- insert:
+    - id: docx-batch
+      name: '@deepwhale-cn/dsh-docx-batch'

package/lib/api.js

@@ -0,0 +1,140 @@
+/**
+ * Word 批量处理 —— 宿主半边 HTTP 出口（面板用）
+ *
+ * 面板（lib/client.js）跟这里是同源的：浏览器 fetch `/dsh-docx-batch/api/*`，
+ * 由 DSH 宿主把请求交给这个 handler，真正干活的是随包的 bin/cli.mjs（Python 内核不变）。
+ *
+ * 安全约束：
+ *   · 参数一律走数组传给子进程，不拼 shell 字符串；
+ *   · 只允许白名单里的 action；
+ *   · 超时 10 分钟，超时杀掉整棵子进程树。
+ */
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const CLI = join(PKG_ROOT, 'bin', 'cli.mjs');
+const ROUTE = '/dsh-docx-batch';
+
+/** 面板可做的操作（与 CLI 的 action 一一对应） */
+const OPS = [
+  { key: 'replace', label: '批量替换文本', needs: ['pairs'], hint: '每行一组「旧文本 → 新文本」，可多行' },
+  { key: 'extract', label: '提取正文到 txt' },
+  { key: 'merge', label: '合并成一个 docx' },
+  { key: 'headers', label: '列出页眉页脚' },
+  { key: 'to-md', label: '转 Markdown' },
+];
+
+const 上限 = 10 * 60 * 1000;
+
+function 回(res, code, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+async function 读体(req) {
+  const chunks = [];
+  for await (const c of req) chunks.push(c);
+  const text = Buffer.concat(chunks).toString('utf8');
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    return {};
+  }
+}
+
+/** 跑 CLI：返回 { ok, code, output } */
+function 跑CLI(args) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CLI, ...args], {
+      // 与壳里其它子进程一致：用 Electron 当 Node（纯 node 环境下这个变量无副作用）
+      env: { ...process.env, ELECTRON_RUN_AS_NODE: '1' },
+      windowsHide: true,
+    });
+    let out = '';
+    const 收集 = (d) => {
+      out += String(d);
+      if (out.length > 200_000) out = out.slice(-200_000); // 防止刷爆内存
+    };
+    child.stdout?.on('data', 收集);
+    child.stderr?.on('data', 收集);
+    const timer = setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch {
+        /* 已退出 */
+      }
+      收集('\n[超时] 超过 10 分钟仍未完成，已终止。');
+    }, 上限);
+    child.on('error', (e) => {
+      clearTimeout(timer);
+      resolve({ ok: false, code: -1, output: `启动失败：${e instanceof Error ? e.message : String(e)}` });
+    });
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      resolve({ ok: code === 0, code: code ?? -1, output: out.trim() });
+    });
+  });
+}
+
+/** 把面板参数翻译成 CLI 参数 */
+function 组参数(b) {
+  const action = String(b.action || '');
+  if (!OPS.some((o) => o.key === action)) return { error: `未知操作：${action}` };
+  const input = String(b.input || '').trim();
+  if (!input) return { error: '请填写要处理的文件或目录路径' };
+  if (!existsSync(input)) return { error: `路径不存在：${input}` };
+  const args = [action, '--input', input];
+  const out = String(b.out || '').trim();
+  if (out) args.push('--out', out);
+  if (action === 'replace') {
+    const 行 = String(b.pairs || '')
+      .split('\n')
+      .map((l) => l.trim())
+      .filter(Boolean);
+    if (!行.length) return { error: '批量替换至少要一组「旧 → 新」' };
+    const 旧 = [];
+    const 新 = [];
+    for (const l of 行) {
+      const i = l.indexOf('→') >= 0 ? l.indexOf('→') : l.indexOf('->');
+      if (i < 0) return { error: `这一行缺少箭头（用「旧 → 新」）：${l}` };
+      const sep = l[i] === '→' ? 1 : 2;
+      旧.push(l.slice(0, i).trim());
+      新.push(l.slice(i + sep).trim());
+    }
+    for (const v of 旧) args.push('--from', v);
+    for (const v of 新) args.push('--to', v);
+  }
+  return { args };
+}
+
+/**
+ * 挂到宿主 webServer 上。
+ * @param {any} ctx 插件上下文（需已注入 webServer）
+ */
+export function registerDocxBatchApi(ctx) {
+  const handler = async (req, res) => {
+    try {
+      const u = new URL(req.url || '/', 'http://127.0.0.1');
+      const p = u.pathname;
+      if (p === `${ROUTE}/api/ops` && req.method === 'GET') {
+        return 回(res, 200, { ok: true, ops: OPS });
+      }
+      if (p === `${ROUTE}/api/run` && req.method === 'POST') {
+        const b = await 读体(req);
+        const { args, error } = 组参数(b);
+        if (error) return 回(res, 400, { ok: false, error });
+        const r = await 跑CLI(args);
+        return 回(res, 200, r);
+      }
+      return 回(res, 404, { ok: false, error: 'not found' });
+    } catch (e) {
+      return 回(res, 500, { ok: false, error: e instanceof Error ? e.message : String(e) });
+    }
+  };
+  ctx.webServer.register({ kind: 'prefix', path: ROUTE, handler });
+}