dsh-word-docs

Readme

# 🧾 dsh-word-docs

**给 DeepSeek Harness 的办公 Word 文档插件——说一句话,出正式文档。**

生成、编辑、读取、统计、转 PDF `.docx`,底层是**纯 Python 标准库**(只有 `zipfile` + `xml.etree`),**零第三方依赖**——不需要 pip install 任何东西,装完即用。中文字体(宋体/eastAsia)自动处理,正式公文排版一步到位。

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![dependencies: zero](https://img.shields.io/badge/dependencies-zero-brightgreen)](package.json)
[![ecosystem: dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-4F46E5)](https://github.com/topics/dsh-plugin)

---

![三种真实文档演示:会议纪要公文版 / 劳动合同模板 / 带表格图片的周报](docs/banner.png)

*真实生成效果(Quick Look 渲染):左=Markdown 会议纪要转公文版(页码+首行缩进+标题编号)· 中=劳动合同模板(页脚页码)· 右=周报(指定列宽表格+合并单元格+插入图片)*

---

## 为什么用它

| | |
| --- | --- |
| 🚀 **零依赖** | 纯标准库实现,装完即用;没有 python-docx / pandoc / LibreOffice 的依赖地狱 |
| 🇨🇳 **中文优先** | 宋体正文、公文首行缩进 2 字符、"一、/（一）/1."式标题编号、A4 版式 |
| 📄 **说人话出文档** | 对 AI 说"把这份 Markdown 转成 Word 加页码",它自己调工具完成 |
| ✏️ **不只是生成** | 能读、能改、能批量填模板、能转 PDF,覆盖文档全生命周期 |
| 🧩 **Harness 原生** | 标准 dsh 插件:装进 profile 即注册 `word_docs` 工具 + `word-docs` 技能 |

## 快速开始(30 秒)

```sh
# 1. 安装
dsh plugin --profile web add git+https://github.com/Ei-Ayw/dsh-word-docs.git

# 2. 重启 dsh Web,然后直接对 AI 说:
#    "把这份 Markdown 转成 Word,加页码、首行缩进"
#    "生成一份劳动合同模板"
#    "读一下这个 docx 里写了什么,总结一下"
#    "把这个合同里的 {占位符} 批量填掉"
```

不想装?核心引擎是单文件,直接命令行用:

```sh
python3 scripts/worddocs.py md2docx --input demo/sample.md --output demo/meeting.docx \
    --page-number --first-line-indent --number-headings chinese
```

## 它能做什么(真实演示)

### 📄 生成:JSON 规格即文档

标题、正文(内联 **加粗** / *斜体* / `` `代码` ``)、嵌套列表、表格(合并单元格 + 列宽)、图片、分页,一个 JSON 全搞定:

```json
{
  "page": { "footer": { "pageNumber": true } },
  "headingNumbering": "chinese",
  "content": [
    { "type": "heading", "level": 0, "text": "2026 年第 35 周工作周报", "align": "center" },
    { "type": "paragraph", "text": "完成 **API 网关** 限流改造,压测 QPS 提升 40%" },
    { "type": "table", "colWidths": [3.5, 3, 3, 3],
      "headers": ["指标", "本周", "上周", "环比"],
      "rows": [ ["需求交付数", "5", "4", "+25%"],
                [{ "text": "合并列", "colSpan": 2 }, "3", "-57%"] ] },
    { "type": "image", "path": "chart.png", "widthCm": 10, "alt": "趋势图" }
  ]
}
```

<table>
<tr>
<td><img src="docs/preview-weekly.png" width="300" alt="周报"></td>
<td><img src="docs/preview-contract.png" width="300" alt="劳动合同"></td>
<td><img src="docs/preview-meeting.png" width="300" alt="会议纪要"></td>
</tr>
<tr>
<td align="center">周报:表格+图片+自动编号</td>
<td align="center">劳动合同:页脚页码+条款缩进</td>
<td align="center">会议纪要:Markdown 一键转公文版</td>
</tr>
</table>

### 🔄 Markdown → Word(一条命令)

```sh
python3 scripts/worddocs.py md2docx --input demo/sample.md --output demo/meeting.docx \
    --page-number --first-line-indent --number-headings chinese
```

支持 ATX 标题、管道表格、嵌套列表、代码块、引用、图片、链接;`--number-headings chinese` 自动变成"一、/（一）"编号。

### ✏️ 编辑现有文档(不丢格式)

```json
[
  { "op": "replaceText", "find": "旧文案", "replace": "新文案", "all": true },
  { "op": "append", "blocks": [{ "type": "heading", "level": 1, "text": "新章节" }] },
  { "op": "delete", "index": 5, "count": 2 },
  { "op": "fill", "values": { "{姓名}": "张三", "{日期}": "2026-09-01" } },
  { "op": "setFormat", "find": "标题", "align": "center", "bold": true,
    "fontSize": 14, "color": "FF0000", "lineSpacing": 1.5 }
]
```

`replaceText` 跨加粗/斜体边界替换时**保留周边格式**(字符级格式映射);`fill` 一条指令批量填模板;`setFormat` 改字体/字号/颜色/对齐/行距。

### 📖 读取、统计、转 PDF

```sh
python3 scripts/worddocs.py extract --input demo/weekly.docx --format markdown   # 还原成 Markdown
python3 scripts/worddocs.py info    --input demo/weekly.docx                     # 段落/表格/图片统计
python3 scripts/worddocs.py pdf     --input demo/weekly.docx                     # 转 PDF(需 LibreOffice/pandoc)
```

## 演示文件

`demo/` 目录有 3 份**生成好的文档**,clone 下来直接打开:

| 文件 | 内容 |
| --- | --- |
| `demo/meeting.docx` | 会议纪要公文版(页码+缩进+编号) |
| `demo/contract.docx` | 劳动合同模板(页脚页码,条款首行缩进) |
| `demo/weekly.docx` | 周报(列宽表格+合并单元格+图片) |
| `demo/sample.md` / `spec-*.json` | 生成它们的源文件,可复现 |

## 安装

```sh
# 方式一:安装为 profile bundle(推荐)
dsh plugin --profile web add git+https://github.com/Ei-Ayw/dsh-word-docs.git

# 方式二:本地开发(--patch,不需要 pnpm)
# word-docs.patch.yml:
#   - insert:
#       - id: word-docs
#         name: '/绝对路径/dsh-word-docs/index.js'
# dsh --profile web --patch ./word-docs.patch.yml
```

> 本地 `link:` 安装需让插件解析到 peer 依赖:`ln -s ~/.dsh/profiles/node_modules/@deepseek-ai node_modules/@deepseek-ai`(npm 安装无需)。

## 测试

```sh
node --test        # 13 个端到端用例,覆盖生成/编辑/提取往返、页码、缩进、编号、合并单元格、格式保留替换
```

## 目录结构

```
dsh-word-docs/
├── index.js              # Cordis 插件:word_docs 工具 + word-docs 技能
├── cordis.patch.yml      # bundle 补丁层
├── scripts/worddocs.py   # 核心引擎(单文件,纯标准库)
├── skills/word-docs/SKILL.md
├── demo/                 # 示例文档与规格
├── docs/                 # README 素材(预览图)
└── tests/
```

## 已知限制

- 标题编号为静态编号(生成时写死),非 Word 自动编号域
- 图片支持 png/jpg/gif;页眉页脚在生成时设置;无脚注/目录域/水印

## License

MIT © [Ei-Ayw](https://github.com/Ei-Ayw)