dsh-plugin-word-docx-writer

Readme

# word-docx-writer

> 中文 Word（.docx）报告生成与排版工具包 / Agent Skill。
> 无需第三方 Office 库即可生成规范的 .docx；同时提供 DSH / Claude Skill、AGENTS.md 等多种 Agent 入口。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
![Python](https://img.shields.io/badge/Python-3.8%2B-blue.svg)

> English version: [README_EN.md](./README_EN.md)

## 简介

`word-docx-writer` 适用于**各类中文长文档**（实验报告、课程设计报告、毕业论文、项目总结、研究报告、实训报告、说明书等），不限定专业方向：
用一份简单的标记稿（Markdown 风格）即可生成排版规范的 Word 文档，也可以对已有 `.docx` 一键套用格式规范。

核心排版规则（可在命令行覆盖）：

| 用途 | Word 内置样式 | 中文字号 | 磅值 | 段落格式 |
| --- | --- | --- | --- | --- |
| 正文 | 正文 / Normal | 小四 | 12 pt | 首行缩进2字符、两端对齐、1.5倍行距、段前段后0 |
| 一级标题 | 标题 1 | 三号 | 16 pt | 段前段后0、1.5倍行距、左对齐 |
| 二级标题 | 标题 2 | 四号 | 14 pt | 段前段后0、1.5倍行距、左对齐 |
| 三级标题 | 标题 3 | 小四 | 12 pt | 段前段后0、1.5倍行距、左对齐 |
| 图表题注 | 正文 + 黑体 | 小五 | 9 pt | 黑体不加粗、居中、单倍行距 |

- 字体：中文**宋体**（SimSun），西文**Times New Roman**；标题仍用宋体；默认颜色**黑色**。
- 表格：表内文字**五号、无底纹**、不首行缩进。
- 图表题注：**按章自动编号**（`表1.1 题名` / `图1.1 题名`），表题在表格上方、图题在图片下方。
- 标题必须使用 Word 内置样式（标题 1/2/3），保证目录（TOC 域）可自动生成。

## 特性

- **标准库即可生成**：OOXML 路径只依赖 Python 标准库（图片尺寸除外，需要 Pillow）。
- **双实现**：`OOXML`（跨平台，不需要 Word）与 `Word COM`（Windows + Office，功能最全：`.doc` 转换、目录刷新）。
- **模板套用**：保留模板封面/评分表/目录/页眉页脚，只替换正文。
- **规范化已有文档**：对任意 `.docx` 套用字体、字号、段落格式与颜色。
- **多 Agent 兼容**：内置 `SKILL.md`、`AGENTS.md` / `AGENTS_EN.md`、`CLAUDE.md`、`GEMINI.md`、Copilot / Cursor 入口。
- **可作为 DSH 插件分发**：同一仓库附带 `package.json` + `cordis.patch.yml` + 内置技能 `skills/word-docx-writer.md`，可 `dsh plugin add` 一键安装。

## 目录结构

```
word-docx-writer/
├── SKILL.md                    # DSH / Claude Skill 入口
├── AGENTS.md / AGENTS_EN.md    # 通用 Agent 说明（中文 / English）
├── CLAUDE.md / GEMINI.md       # Claude Code / Gemini CLI 入口
├── README.md / README_EN.md    # 说明文档（中文 / English）
├── LICENSE / CHANGELOG.md
├── scripts/
│   ├── word_style.py           # 排版规范唯一来源（字体/字号/段落格式/颜色）
│   ├── build_docx.py           # 标记稿 -> .docx（模板、标题样式、表格、图片、题注、目录）
│   └── read_docx.py            # 读取/转换 .doc、.docx 结构
├── references/
│   ├── style-spec.md           # 排版规范速查
│   └── markup.md               # 内容标记语法
├── assets/blank.docx           # 内置空白模板
├── examples/                   # 可运行示例（content.txt + README）
├── skills/word-docx-writer.md  # 插件内置技能（方式 C）
├── src/index.js                # 插件宿主入口（skills-only，空实现）
├── package.json                # npm 包定义（方式 C）
├── cordis.patch.yml            # DSH 插件挂载声明（方式 C）
├── .github/copilot-instructions.md
└── .cursor/rules/word-docx-writer.mdc
```

## 安装

### 方式 1：作为 DSH / Claude Skill（推荐）

```bash
# DSH（DeepSeek Harness）
git clone https://github.com/RempleXI/word-docx-writer ~/.dsh/skills/word-docx-writer

# Claude Code
git clone https://github.com/RempleXI/word-docx-writer ~/.claude/skills/word-docx-writer
```

也可以放到**项目级**目录，仅对当前项目生效：

```bash
git clone https://github.com/RempleXI/word-docx-writer <your-project>/.dsh/skills/word-docx-writer
# 或
git clone https://github.com/RempleXI/word-docx-writer <your-project>/.claude/skills/word-docx-writer
```

### 方式 2：下载 zip 直接用

下载 Release / 打包好的 `word-docx-writer.zip`，解压到上面的任一 skill 目录即可。

### 方式 3：其它 Agent 工具

- **Codex / OpenCode / 通用**：把本仓库放到项目里，工具会读根目录的 `AGENTS.md`；
- **Gemini CLI**：读 `GEMINI.md`；
- **Claude Code**：读 `CLAUDE.md`；
- **GitHub Copilot**：读 `.github/copilot-instructions.md`；
- **Cursor**：读 `.cursor/rules/word-docx-writer.mdc`；
- **英文用户**：见 `README_EN.md`、`AGENTS_EN.md`。

### 方式 4：作为 DSH 插件（npm）

本仓库本身也是一个 **skills-only** 的 DSH 插件：

```bash
npm publish --access public         # 发布为 dsh-plugin-word-docx-writer
dsh plugin --profile web add dsh-plugin-word-docx-writer@latest
```

- 插件运行时入口 `src/index.js` 为空实现（no-op）；
- 能力由内置技能 `skills/word-docx-writer.md` 与 `scripts/` 工具包提供；
- 发布前请把 `package.json` 的 `name` 改成你的 scope（如 `@your-scope/dsh-plugin-word-docx-writer`），并同步修改 `cordis.patch.yml` 里的 `name`。

## 快速开始

1）写一份内容稿 `content.txt`（语法见 [`references/markup.md`](references/markup.md)）：

```
TITLE|实验报告标题
H1|1. 实验目的
H2|1.1 实验背景
P|这是一段正文，自动首行缩进2字符、两端对齐、1.5倍行距。
TCAP|实验数据表
TBL|编号;;项目;;结果
ROW|1;;示例项目;;示例结果
FCAP|实验装置图
IMG|fig.png|12
```

2）生成文档：

```bash
python scripts/build_docx.py --content content.txt --out report.docx
```

3）对已有文档套用规范：

```bash
python scripts/word_style.py report.docx          # 默认优先 Word COM，失败自动退回 OOXML
python scripts/word_style.py report.docx --method ooxml
```

4）校验结构：

```bash
python scripts/read_docx.py report.docx
```

## 依赖与平台

| 能力 | 依赖 |
| --- | --- |
| 生成 / 排版（OOXML） | Python 3.8+；插入图片时需要 `Pillow` |
| `.doc` 转换 | Windows + Microsoft Word（COM） |
| 刷新目录 / 页码 | Windows + Microsoft Word（COM），或手动按 F9 |
| 字体 | 系统需有 宋体（SimSun）、黑体（SimHei）、Times New Roman |

```bash
pip install pywin32 Pillow
```

> 非 Windows 平台：`build_docx.py` 与 `word_style.py --method ooxml` 完全可用；`.doc` 转换与目录刷新请用 LibreOffice 或 Word 手动完成。

## 命令行参数（build_docx.py）

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| `--content` | 必填 | 内容稿路径 |
| `--out` | 必填 | 输出 .docx |
| `--template` | `assets/blank.docx` | 模板 .docx/.doc |
| `--font` / `--font-ascii` | 宋体 / Times New Roman | 中文 / 西文字体 |
| `--body` `--h1` `--h2` `--h3` | 12 / 16 / 14 / 12 | 字号（pt） |
| `--table-size` | 10.5 | 表格字号 |
| `--caption-font` `--caption-size` | 黑体 / 9 | 题注字体字号 |
| `--color` | 000000 | 默认字体颜色 |
| `--title` | — | 封面题目（模板含题目占位时替换） |
| `--no-update-toc` | — | 不调用 Word COM 刷新目录 |

## 许可证

[MIT](./LICENSE)。使用时请保留版权声明。

## 贡献

欢迎提 Issue / PR。提交前建议跑一遍 `examples/` 验证脚本可用。