@deepwhale-cn/dsh-docx-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,92 @@
-# 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` 能改页眉页脚里的文字。
+- ❌ 不是格式转换器：不导出 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 © 温州深鲸智能科技有限公司

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/docx_tool.py

@@ -0,0 +1,651 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+dsh-docx-batch 的真实处理逻辑（python-docx）
+
+由 bin/cli.mjs 通过 spawnSync 调用：
+    python3 lib/docx_tool.py <action> '<json payload>'
+约定：
+  - stdout 只输出一行 JSON（最后一行），人类可读文案由 Node 侧负责
+  - stderr 输出异常栈（调试用）
+  - 退出码：0 成功 / 1 运行失败 / 2 参数或输入问题 / 3 缺依赖
+  - 只读输入文件，所有产物写进 --out 目录（默认 <输入目录>/_输出）
+"""
+
+import csv
+import json
+import os
+import re
+import sys
+import tempfile
+import traceback
+from pathlib import Path
+
+try:
+    from docx import Document
+    from docx.oxml.ns import qn
+    from docx.table import Table
+    from docx.text.paragraph import Paragraph
+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-docx\n"
+                "如果 python3 也没有：\n  macOS: brew install python3\n  Ubuntu: sudo apt install python3",
+    }, ensure_ascii=False))
+    sys.exit(3)
+
+DOCX_EXT = ".docx"
+SKIP_DIRS = {"_输出", "node_modules", ".git", "__pycache__", ".venv", "venv"}
+DEMO_HEADER = "机密 · 深鲸科技"
+DEMO_FOOTER = "第 1 页"
+
+
+# ── 错误 ──────────────────────────────────────────────────────────
+
+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 _out_skip_set(out_dir):
+    try:
+        return {str(out_dir.resolve())}
+    except OSError:
+        return set()
+
+
+def collect_docx(input_path, out_dir=None):
+    """接受单个 .docx 或目录（递归），按文件名自然排序。"""
+    if not input_path:
+        raise ToolError("缺少 --input", "例：replace --input ./合同目录 --from 旧 --to 新")
+    root = Path(input_path).expanduser().resolve()
+    if not root.exists():
+        raise ToolError(
+            "输入不存在：%s" % input_path,
+            "请检查路径是否正确；传目录会递归处理其中的 .docx 文件。",
+        )
+    skip_out = _out_skip_set(out_dir) if out_dir else set()
+    if root.is_file():
+        if root.suffix.lower() != DOCX_EXT:
+            raise ToolError(
+                "输入不是 .docx 文件：%s" % root.name,
+                "本插件只处理 Word 2007+ 的 .docx；.doc 请先用 Word/WPS 另存为 .docx。",
+            )
+        return [root]
+    files = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(
+            [d for d in dirnames if d not in SKIP_DIRS and not d.startswith("~$")],
+            key=natural_key,
+        )
+        if str(Path(dirpath).resolve()) in skip_out:
+            dirnames[:] = []
+            continue
+        for name in filenames:
+            if name.startswith("~$"):
+                continue  # Word 打开时的临时文件
+            p = Path(dirpath) / name
+            if p.suffix.lower() == DOCX_EXT:
+                files.append(p)
+    files.sort(key=lambda p: natural_key(str(p.relative_to(root))))
+    if not files:
+        raise ToolError(
+            "目录里没有 .docx 文件：%s" % root,
+            "确认目录选对了；本插件不处理 .doc（请先另存为 .docx）。",
+        )
+    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))
+
+
+# ── docx 遍历 ─────────────────────────────────────────────────────
+
+def iter_block_items(parent):
+    """按文档顺序遍历段落和表格。"""
+    body = parent.element.body
+    for child in body.iterchildren():
+        if child.tag == qn("w:p"):
+            yield Paragraph(child, parent)
+        elif child.tag == qn("w:tbl"):
+            yield Table(child, parent)
+
+
+def iter_cell_paragraphs(cell):
+    for p in cell.paragraphs:
+        yield p
+    for table in cell.tables:
+        for row in table.rows:
+            for c in row.cells:
+                yield from iter_cell_paragraphs(c)
+
+
+def iter_table_paragraphs(table):
+    for row in table.rows:
+        for cell in row.cells:
+            yield from iter_cell_paragraphs(cell)
+
+
+def all_editable_paragraphs(doc):
+    """正文 + 表格 + 页眉页脚，去重（链接到前一节的页眉是同一个 part）。"""
+    out, seen = [], set()
+
+    def add(p):
+        key = id(p._p)
+        if key not in seen:
+            seen.add(key)
+            out.append(p)
+
+    for p in doc.paragraphs:
+        add(p)
+    for t in doc.tables:
+        for p in iter_table_paragraphs(t):
+            add(p)
+    for section in doc.sections:
+        for part in (section.header, section.footer):
+            try:
+                for p in part.paragraphs:
+                    add(p)
+                for t in part.tables:
+                    for p in iter_table_paragraphs(t):
+                        add(p)
+            except Exception:
+                # 极少数残缺文档取不到页眉/页脚定义：跳过，不影响正文
+                continue
+    return out
+
+
+# ── 文本替换 ──────────────────────────────────────────────────────
+
+def replace_in_paragraph(paragraph, pairs):
+    """先做 run 内替换（保留格式），跨 run 的再做段落级重建。返回替换次数。"""
+    count = 0
+    if not paragraph.runs:
+        return 0
+    for old, new in pairs:
+        if not old:
+            continue
+        for run in paragraph.runs:
+            if old in run.text:
+                count += run.text.count(old)
+                run.text = run.text.replace(old, new)
+        if old in paragraph.text:
+            runs = paragraph.runs
+            full = "".join(r.text for r in runs)
+            if old in full:
+                count += full.count(old)
+                runs[0].text = full.replace(old, new)
+                for r in runs[1:]:
+                    r.text = ""
+    return count
+
+
+# ── 各动作 ────────────────────────────────────────────────────────
+
+def action_replace(payload):
+    files = collect_docx(payload.get("input"))
+    out = resolve_out(payload, payload.get("input"))
+    olds = payload.get("from") or []
+    news = payload.get("to") or []
+    if not olds:
+        raise ToolError("缺少 --from（要替换的旧文本）",
+                        "例：replace --input ./合同 --from 旧公司名 --to 新公司名")
+    if len(olds) != len(news):
+        raise ToolError(
+            "--from 与 --to 数量不一致（%d vs %d）" % (len(olds), len(news)),
+            "每一组 --from 都要配一个 --to，按顺序一一对应。",
+        )
+    pairs = list(zip(olds, news))
+    out.mkdir(parents=True, exist_ok=True)
+    results, total = [], 0
+    for src in files:
+        doc = Document(str(src))
+        n = 0
+        for p in all_editable_paragraphs(doc):
+            n += replace_in_paragraph(p, pairs)
+        target = unique_path(out, src.name)
+        doc.save(str(target))
+        results.append({
+            "input": str(src),
+            "input_name": src.name,
+            "output": str(target),
+            "output_name": target.name,
+            "replacements": n,
+        })
+        total += n
+    return {
+        "action": "replace",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "out": str(out),
+        "files": results,
+        "replacements": total,
+        "summary": "处理 %d 个文件，共替换 %d 处" % (len(files), total),
+        "artifacts": [r["output"] for r in results],
+    }
+
+
+def doc_body_text(doc):
+    lines = []
+    for block in iter_block_items(doc):
+        if isinstance(block, Paragraph):
+            lines.append(block.text)
+        else:
+            lines.append("")
+            lines.append("[表格]")
+            for row in block.rows:
+                lines.append("\t".join(c.text.replace("\n", " ") for c in row.cells))
+    return "\n".join(lines).strip() + "\n"
+
+
+def action_extract(payload):
+    files = collect_docx(payload.get("input"))
+    out = resolve_out(payload, payload.get("input"))
+    out.mkdir(parents=True, exist_ok=True)
+    results = []
+    for src in files:
+        text = doc_body_text(Document(str(src)))
+        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,
+            "chars": len(text),
+        })
+    return {
+        "action": "extract",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "out": str(out),
+        "files": results,
+        "summary": "提取 %d 个文件的正文文本" % len(files),
+        "artifacts": [r["output"] for r in results],
+    }
+
+
+def copy_run(dst_paragraph, src_run):
+    run = dst_paragraph.add_run(src_run.text)
+    try:
+        run.bold = src_run.bold
+        run.italic = src_run.italic
+        run.underline = src_run.underline
+        if src_run.font.size is not None:
+            run.font.size = src_run.font.size
+        if src_run.font.name:
+            run.font.name = src_run.font.name
+    except Exception:
+        pass  # 字体属性个别无法复制时不影响文本合并
+
+
+def copy_paragraph(dst_doc, src_paragraph):
+    p = dst_doc.add_paragraph()
+    try:
+        style_name = src_paragraph.style.name if src_paragraph.style else None
+        if style_name and style_name.lower() not in ("normal", "正文"):
+            p.style = style_name
+    except Exception:
+        pass
+    try:
+        if src_paragraph.alignment is not None:
+            p.alignment = src_paragraph.alignment
+    except Exception:
+        pass
+    for run in src_paragraph.runs:
+        copy_run(p, run)
+    return p
+
+
+def copy_table(dst_doc, src_table):
+    rows = len(src_table.rows)
+    cols = max((len(r.cells) for r in src_table.rows), default=0)
+    if rows == 0 or cols == 0:
+        return None
+    table = dst_doc.add_table(rows=rows, cols=cols)
+    for i, row in enumerate(src_table.rows):
+        for j, cell in enumerate(row.cells):
+            if j < cols:
+                table.cell(i, j).text = cell.text
+    try:
+        table.style = src_table.style.name
+    except Exception:
+        pass
+    return table
+
+
+def action_merge(payload):
+    files = collect_docx(payload.get("input"))
+    out = resolve_out(payload, payload.get("input"))
+    out.mkdir(parents=True, exist_ok=True)
+    merged = Document()
+    results = []
+    for src in files:
+        doc = Document(str(src))
+        paragraphs_before = len(merged.paragraphs)
+        for block in iter_block_items(doc):
+            if isinstance(block, Paragraph):
+                copy_paragraph(merged, block)
+            else:
+                copy_table(merged, block)
+        results.append({
+            "input": str(src),
+            "input_name": src.name,
+            "paragraphs": len(merged.paragraphs) - paragraphs_before,
+            "source_paragraphs": len(doc.paragraphs),
+        })
+    target = unique_path(out, "merged.docx")
+    merged.save(str(target))
+    return {
+        "action": "merge",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "out": str(out),
+        "files": results,
+        "output": str(target),
+        "output_name": target.name,
+        "paragraphs": len(merged.paragraphs),
+        "summary": "按文件名顺序合并 %d 个文件，共 %d 段" % (len(files), len(merged.paragraphs)),
+        "artifacts": [str(target)],
+    }
+
+
+def section_texts(doc):
+    sections = []
+    for idx, section in enumerate(doc.sections, 1):
+        item = {"section": idx, "header": [], "footer": []}
+        for label, part in (("header", section.header), ("footer", section.footer)):
+            try:
+                texts = [p.text.strip() for p in part.paragraphs if p.text.strip()]
+            except Exception:
+                texts = []
+            item[label] = texts
+        sections.append(item)
+    return sections
+
+
+def action_headers(payload):
+    files = collect_docx(payload.get("input"))
+    out = resolve_out(payload, payload.get("input"))
+    out.mkdir(parents=True, exist_ok=True)
+    results, lines = [], []
+    for src in files:
+        sections = section_texts(Document(str(src)))
+        hit = sum(1 for s in sections if s["header"] or s["footer"])
+        results.append({
+            "input": str(src),
+            "input_name": src.name,
+            "sections": len(sections),
+            "sections_with_text": hit,
+            "detail": sections,
+        })
+        lines.append("文件：%s（%d 节）" % (src.name, len(sections)))
+        for s in sections:
+            h = " / ".join(s["header"]) if s["header"] else "（空）"
+            f = " / ".join(s["footer"]) if s["footer"] else "（空）"
+            lines.append("  第 %d 节  页眉：%s" % (s["section"], h))
+            lines.append("          页脚：%s" % f)
+        lines.append("")
+    target = unique_path(out, "headers.txt")
+    target.write_text("\n".join(lines).strip() + "\n", encoding="utf-8")
+    return {
+        "action": "headers",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "out": str(out),
+        "files": results,
+        "output": str(target),
+        "output_name": target.name,
+        "summary": "列出 %d 个文件的页眉页脚" % len(files),
+        "artifacts": [str(target)],
+    }
+
+
+def inline_runs(paragraph):
+    parts = []
+    for run in paragraph.runs:
+        text = run.text
+        if not text:
+            continue
+        if run.bold and run.italic:
+            text = "***%s***" % text
+        elif run.bold:
+            text = "**%s**" % text
+        elif run.italic:
+            text = "*%s*" % text
+        parts.append(text)
+    text = "".join(parts).strip()
+    return text or paragraph.text.strip()
+
+
+def table_to_md(table):
+    rows = []
+    for row in table.rows:
+        cells = [" ".join(c.text.split()) for c in row.cells]
+        if any(cells):
+            rows.append(cells)
+    if not rows:
+        return ""
+    width = max(len(r) for r in rows)
+    rows = [r + [""] * (width - len(r)) for r in rows]
+
+    def esc(s):
+        return s.replace("|", "\\|")
+
+    out = ["| " + " | ".join(esc(c) for c in rows[0]) + " |",
+           "| " + " | ".join(["---"] * width) + " |"]
+    for r in rows[1:]:
+        out.append("| " + " | ".join(esc(c) for c in r) + " |")
+    return "\n".join(out)
+
+
+def paragraph_to_md(paragraph, state):
+    style = (paragraph.style.name if paragraph.style else "") or ""
+    style_low = style.lower()
+    text = inline_runs(paragraph)
+    m = re.match(r"^(heading|标题)\s*([1-6])$", style, re.I)
+    if m:
+        return "#" * int(m.group(2)) + " " + text
+    if style_low.startswith("title"):
+        return "# " + text
+    if "list bullet" in style_low or ("列表" in style and "项目" in style):
+        return "- " + text
+    if "list number" in style_low:
+        state["number"] += 1
+        return "%d. %s" % (state["number"], text)
+    if not text:
+        return ""
+    return text
+
+
+def doc_to_md(doc):
+    blocks = []
+    state = {"number": 0}
+    for block in iter_block_items(doc):
+        if isinstance(block, Paragraph):
+            md = paragraph_to_md(block, state)
+        else:
+            md = table_to_md(block)
+        if md.strip():
+            blocks.append(md)
+    return "\n\n".join(blocks).strip() + "\n"
+
+
+def action_to_md(payload):
+    files = collect_docx(payload.get("input"))
+    out = resolve_out(payload, payload.get("input"))
+    out.mkdir(parents=True, exist_ok=True)
+    results = []
+    for src in files:
+        md = doc_to_md(Document(str(src)))
+        target = unique_path(out, src.stem + ".md")
+        target.write_text(md, encoding="utf-8")
+        results.append({
+            "input": str(src),
+            "input_name": src.name,
+            "output": str(target),
+            "output_name": target.name,
+            "chars": len(md),
+        })
+    return {
+        "action": "to-md",
+        "input": str(Path(payload["input"]).expanduser().resolve()),
+        "out": str(out),
+        "files": results,
+        "summary": "转换 %d 个文件为 Markdown" % len(files),
+        "artifacts": [r["output"] for r in results],
+    }
+
+
+# ── demo ─────────────────────────────────────────────────────────
+
+def _make_demo_docx(path, heading, lines, table_rows=None, header=True):
+    doc = Document()
+    doc.add_heading(heading, level=1)
+    for line in lines:
+        doc.add_paragraph(line)
+    if table_rows:
+        table = doc.add_table(rows=len(table_rows), cols=len(table_rows[0]))
+        for i, row in enumerate(table_rows):
+            for j, value in enumerate(row):
+                table.cell(i, j).text = value
+    if header:
+        doc.sections[0].header.paragraphs[0].text = DEMO_HEADER
+        doc.sections[0].footer.paragraphs[0].text = DEMO_FOOTER
+    doc.save(str(path))
+
+
+def action_demo(payload):
+    root = Path(tempfile.mkdtemp(prefix="dsh-docx-batch-demo-"))
+    inputs = root / "样例"
+    inputs.mkdir(parents=True, exist_ok=True)
+    _make_demo_docx(
+        inputs / "合同A.docx",
+        "第一章 总则",
+        ["甲方：深鲸科技", "乙方：示例客户", "本合同由深鲸科技起草。"],
+        [["条款", "内容"], ["保密", "深鲸科技对数据保密"]],
+    )
+    _make_demo_docx(
+        inputs / "附件B.docx",
+        "附件 B",
+        ["附件内容第一段", "附件内容第二段"],
+    )
+    out = root / "输出"
+    steps, artifacts = [], []
+
+    def run(name, fn, extra):
+        p = {"input": str(inputs), "out": str(out / name)}
+        p.update(extra)
+        result = fn(p)
+        steps.append({
+            "step": name,
+            "action": result.get("action"),
+            "summary": result.get("summary", ""),
+            "out": result.get("out"),
+        })
+        artifacts.extend(result.get("artifacts", []))
+
+    run("替换", action_replace, {"from": ["深鲸科技"], "to": ["深海鲸"]})
+    replaced_dir = out / "替换"
+    # 提取/转 Markdown 用替换后的产物，顺带演示链路
+    p_extract = {"input": str(replaced_dir), "out": str(out / "文本")}
+    result = action_extract(p_extract)
+    steps.append({"step": "文本", "action": "extract", "summary": result["summary"], "out": result["out"]})
+    artifacts.extend(result["artifacts"])
+    p_md = {"input": str(replaced_dir), "out": str(out / "markdown")}
+    result = action_to_md(p_md)
+    steps.append({"step": "markdown", "action": "to-md", "summary": result["summary"], "out": result["out"]})
+    artifacts.extend(result["artifacts"])
+    run("合并", action_merge, {})
+    run("页眉页脚", action_headers, {})
+
+    return {
+        "action": "demo",
+        "demoRoot": str(root),
+        "steps": steps,
+        "summary": "演示完成：5 个动作全部跑通，产物 %d 个" % len(artifacts),
+        "artifacts": artifacts,
+    }
+
+
+ACTIONS = {
+    "replace": action_replace,
+    "extract": action_extract,
+    "merge": action_merge,
+    "headers": action_headers,
+    "to-md": action_to_md,
+    "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": "检查目标文件是否被 Word 占用、或输出目录是否有写权限。"})
+        return 1
+    except Exception as exc:  # noqa: BLE001 —— 兜底，保证永远输出 JSON
+        traceback.print_exc(file=sys.stderr)
+        emit({"ok": False, "code": 1, "message": "处理失败：%s" % exc,
+              "hint": "文件可能已损坏或被加密；可先用 Word 打开另存一次再试。"})
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv))

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: 'docx-batch',
+  pkgRoot: pkgRootFrom(import.meta.url),
+  skillFile: 'skill/docx-batch.md',
+  binFile: 'bin/cli.mjs',
+  description: 'Word 批量替换 / 合并 / 提取文本 / 页眉页脚 / 转 Markdown，一次处理整目录',
+  whenToUse: '当用户要批量处理整目录的 Word（.docx）时使用：批量替换文本（合同改甲方、术语统一）、合并多份文档、提取正文到 txt、查看页眉页脚、转 Markdown。典型说法：「把这批 Word 里的旧公司名全换掉」「这些 docx 合并成一份」「Word 转 Markdown」。不用于 .doc 老格式、加密文档或需要保留复杂排版的场景。',
+});

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "@deepwhale-cn/dsh-docx-batch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Word 批量替换 / 合并 / 提取文本 / 页眉页脚 / 转 Markdown，一次处理整目录",
+  "type": "module",
+  "license": "MIT",
+  "keywords": ["dsh", "dsh-plugin", "deepseek-harness", "skill", "tool", "docx-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-docx-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-docx-batch.git" },
+  "homepage": "https://www.deepwhale.org.cn/skills.html",
+  "bugs": { "url": "https://github.com/feely0208/dsh-docx-batch/issues" }
+}

package/skill/docx-batch.md

@@ -0,0 +1,59 @@
+# Word 批量处理
+
+**一句话**：整目录的 Word 一次处理完 —— 批量替换文本、提取正文、按文件名合并、列页眉页脚、转 Markdown。只读输入，产物单独输出，不覆盖原文件。
+
+## 什么时候用
+
+用户说这些话时用：
+
+- 「把这批 Word 里的××全部改成××」「50 份合同批量替换甲方」
+- 「把目录下这些 docx 合并成一份」「周报合成一个文件」
+- 「把这些 Word 的正文提取成 txt」「把 Word 转成 Markdown」
+- 「看看这些文档的页眉页脚都写了什么」
+- 用户给了一个装了很多 `.docx` 的目录，要求批量处理其中文字
+
+## 怎么调用
+
+```bash
+<cli 路径> --help
+```
+
+```bash
+# 批量替换（--from/--to 可多组，按顺序配对；改正文、表格、页眉页脚）
+<cli 路径> replace --input <文件或目录> [--out <输出目录>] \
+  --from 旧文本 --to 新文本 [--from 旧2 --to 新2] [--json]
+
+# 提取正文到 .txt
+<cli 路径> extract --input <文件或目录> [--out <输出目录>] [--json]
+
+# 按文件名自然顺序合并
+<cli 路径> merge --input <文件或目录> [--out <输出目录>] [--json]
+
+# 列出页眉页脚
+<cli 路径> headers --input <文件或目录> [--out <输出目录>] [--json]
+
+# 转 Markdown
+<cli 路径> to-md --input <文件或目录> [--out <输出目录>] [--json]
+
+# 自造样例跑完整流程（不碰用户文件），推荐先跑这个确认环境正常
+<cli 路径> --demo
+```
+
+## 输出约定（要向用户说清）
+
+- **不修改输入文件**；输出默认写到 `<输入目录>/_输出`，可用 `--out` 指定。
+- 同名产物不覆盖：自动变成 `合同_1.docx`、`合同_2.docx`。
+- 目录递归处理，跳过 `~$` 临时文件和 `_输出` 目录。
+- 成功退出码 0；参数/输入错误退出码 2；缺依赖退出码 3；运行失败退出码 1。
+- `--json` 时输出结构化结果（含每个文件的产物路径和替换次数 / 字符数等）。
+
+## 边界（必须向用户说清）
+
+- **替换可能影响局部格式**：跨多个 run 的匹配会合并段落内的 run，局部加粗/字号/颜色可能丢失。
+  重要文档先小批量跑一份对比，再整目录处理。
+- 只支持 `.docx`；`.doc` 老格式、`.docm`、加密文档不支持，需先另存为 `.docx`。
+- 只覆盖正文段落、表格、页眉页脚；**不处理**脚注、尾注、批注、文本框、SmartArt、图片里的文字。
+- `merge` 只合并正文与表格，不合并页眉页脚和样式主题；复杂排版会退化为顺序文本。
+- `headers` 只读不改；替换是字面匹配，大小写敏感，不支持正则。
+- 缺 `python3` 或 `python-docx` 时会明确打印安装命令（`python3 -m pip install python-docx`），不会静默失败。
+- 不联网、不上传文档，全部在本机处理。