# @deepwhale-cn/dsh-cn-doc-formatter 中文文档

规范地址：https://npmcn.com/package/%40deepwhale-cn/dsh-cn-doc-formatter/

版本：0\.2\.4
npm 元数据更新时间：2026-10-29T04:49:57.885Z
中文译文更新时间：2026-11-14T16:17:00.712Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40deepwhale-cn/dsh-cn-doc-formatter
原文对照：https://npmcn.com/package/%40deepwhale-cn/dsh-cn-doc-formatter/?lang=original
项目主页：https://github.com/feely0208/dsh-cn-skills#readme
源码仓库：https://github.com/feely0208/dsh-cn-skills

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：133 kB，15 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：0 个
- peer 依赖：@deepseek-ai/dsh-skill \*
- 首次发布：2026-09-25T09:19:01.265Z
- 最新版本发布：2026-10-29T04:49:57.696Z
- 近 30 天下载量：1985（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

中文公文排版：按 GB/T 9704-2012 生成 .docx / .pdf / .txt，附输出自检。不含字体文件，字体由用户自备。

## 安装

```sh
npm install @deepwhale-cn/dsh-cn-doc-formatter
```

也可以使用：`pnpm add @deepwhale-cn/dsh-cn-doc-formatter`、`yarn add @deepwhale-cn/dsh-cn-doc-formatter`、`bun add @deepwhale-cn/dsh-cn-doc-formatter`

## README

# @deepwhale-cn/dsh-cn-doc-formatter

**中文公文排版** —— 给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 用的 skill 插件。

按 **GB/T 9704-2012《党政机关公文格式》** 生成 `.docx` / `.pdf` / `.txt`， 并自带**输出自检**——生成完逐项核对页边距、字号、行距、字体、页面尺寸， 不符合规范就报错，而不是让你交付一份看起来差不多、实际不合规的文件。

## ⚠️ 本插件不含字体，字体需你自备

**这是刻意的设计，不是缺失。**

公文规范要求的仿宋（方正仿宋等）是**商业字体**。其授权允许你在文档中使用， 但**不允许再分发字体文件本身**。所以本插件只做「排版引擎」，字体由你提供：

```bash
# 方式一：直接指定字体文件（推荐，最明确）
export DSH_CN_FANGSONG=/path/to/仿宋.ttf
export DSH_CN_FANGSONG_BOLD=/path/to/仿宋加粗.ttf   # 可选

# 方式二：指定一个目录，脚本在其中按文件名查找
export DSH_CN_FONT_DIR=~/my-fonts
```

也可以直接装进**系统字体目录**（一次装好处处可用）：

| 系统 | 目录 |
| --- | --- |
| macOS | `~/Library/Fonts/` |
| Windows | `C:\Windows\Fonts\` |
| Linux | `~/.fonts/` 或 `~/.local/share/fonts/` |

装 WPS Office 也行 —— 它自带方正仿宋。

**找不到字体时不会静默失败**：PDF 退回系统宋体，并在 stderr 打印上面这张获取指引。 docx 只在文件里声明字体族名（由你机器上的 Word 渲染），不依赖字体文件。

> **一个细节**：如果你只有常规仿宋、没有加粗体，**标题会继续使用仿宋**（只是不加粗）， 而不是换成宋体。因为「全文统一仿宋」是硬规范，宁可字重不够也不换字体族。 reportlab 不做合成粗体，这是引擎限制。

## 它管什么

| 项目 | 规范值 |
| --- | --- |
| 标题 | 仿宋，二号（22pt）加粗，居中，行距 33–36 磅 |
| 一/二/三/四级标题 | 仿宋，三号（16pt）加粗，左空二字 |
| 正文 | 仿宋，四号（14pt），固定行距 28 磅，首行缩进严格 2 字 |
| 版头（可选） | 份号 / 密级 / 紧急程度 / 发文字号，仿宋三号 |
| 署名与日期 | 距正文下空 3 行，日期阿拉伯数字右空 4 字 |
| 页码 | 「- 1 -」，单页居右空一字、双页居左空一字 |
| 页边距 | 上 3.7 / 下 3.5 / 左 2.8 / 右 2.6 cm |
| 文档网格 | 每面 22 行、每行 28 字 |

**不出现任何 AI 痕迹**：无水印、无生成标记、无作者信息、无版本说明、无注释。

## 安装

```bash
dsh plugin --profile <profile> add @deepwhale-cn/dsh-cn-doc-formatter
```

然后重启 dsh。技能会在 agent 需要时自动可用。

### Python 依赖

排版脚本是 Python，需要这些库：

```bash
pip install python-docx reportlab fontTools pypdf
```

| 库 | 用途 |
| --- | --- |
| `python-docx` | 生成 Word 文档 |
| `reportlab` | 生成 PDF |
| `fontTools` | 探测本机已装字体（读字体 name 表） |
| `pypdf` | 自检时校验 PDF 是否真的嵌入了目标字体 |

## 它比「套个模板」多做了什么

**1\. 输出自检（`verify_output.py`）**

生成完不是结束。自检会真的打开产出文件，逐项核对：

```
  ── 公文.docx
     ✅ 上边距 3.70cm ✓      ✅ 标题 22pt 加粗 ✓
     ✅ 正文 14.0pt / 行距 28pt ✓
     ✅ 全文统一字体：FangS-SC ✓
  ── 公文.pdf
     ✅ 嵌入字体：/AAAAAA+FangS-SC, /AAAAAA+FangS-SC-Bold
     ✅ 页面 A4 21.0×29.7cm ✓
```

退出码 `0` = 通过，`1` = 有不符合项 —— **可以直接用在 CI 或交付卡口上**。

**2\. Markdown 输入适配（`md_adapter.py`）**

内容常以 Markdown 写就，直接喂给脚本会丢失层级（整篇被当正文）：

| Markdown | 转成 | 公文层级 |
| --- | --- | --- |
| `## 一、小节` | `一、小节` | 一级标题 |
| `### 1.1 小节` | `（一）小节` | 二级标题 |
| `#### 更深` | `1. 小节` | 三级标题 |
| `- 列表项` | 正文 | 正文 |
| `| 表格 |` | `表头：值；表头：值。` | 正文 |

它还会把同一段内的软换行合并成一行 —— 源文档常手动折行， 逐行当独立段落会在断句处留下孤立标点（如单独一行的「、」）。

**3\. 跨平台字体探测**

早期实现用 `fc-list` 探测字体，而 **macOS 不预装 fontconfig**， 异常被吞掉后恒返回「字体不存在」，于是**即使装了仿宋也检测不到**，会始终走回退分支。 本版改为直接读字体文件的 `name` 表，macOS / Windows / Linux 通用。

## 用法

### 面板（v0.2.0 起已带面板）

侧栏「深鲸公文排版」：选 .md/.txt 源文件、填输出目录（可选标题 / 发文机关 / 成文日期）→ 勾选 docx / pdf / txt → 点「开始排版」→ 面板直接显示产物名、体积与绝对路径。面板走宿主 `/dsh-cn-doc-formatter/api/run`，复用随包的 python 排版脚本；Python 或依赖缺失时显示可读错误，不白屏。

### CLI / 技能命令

技能正文里有完整命令。核心三条：

```bash
# 生成 Word / PDF
python "<插件目录>/scripts/docx_formatter.py" --output <目录> \
  --title "标题" --body "正文..." --sender "发文机关" --date "2026年9月25日"
python "<插件目录>/scripts/pdf_formatter.py"  --output <目录> \
  --title "标题" --body "正文..." --sender "发文机关" --date "2026年9月25日"

# 输出自检（不要跳过）
python "<插件目录>/scripts/verify_output.py" --dir <输出目录>
```

> ⚠️ **早期文档里的 `--type notice` 参数并不存在**，加上会直接报 `unrecognized arguments`。文种由内容决定，脚本不做区分。本版已修正文档。

## 设计取舍

**不分发字体。** 见上文——这不是省事，是避免把商业字体的再分发风险 转嫁给每一个使用者。

**不联网。** 排版、字体探测、自检全部在本地完成，不把文档内容发往任何第三方服务。

**文种不参与排版。** 通知 / 报告 / 函 / 决定的排版规范是一致的， 差别只在正文怎么写。脚本不为文种分叉，避免维护一堆看似不同实则相同的模板。

## 与其它插件的关系

按 [DSH 插件生态倡议书](https://github.com/anywhere-labs/dsh-desktop/blob/main/docs/plugin-ecosystem.md) 的三条原则开发：**组合优先、声明清晰、兼容优先**。不假设、不覆盖其它插件的内部实现。

## 许可

MIT。**本软件不包含任何字体文件**；使用者在文档中选用何种字体，由使用者自行负责 取得该字体的合法授权。

## 常见问题

### @deepwhale-cn/dsh-cn-doc-formatter 是什么？

中文公文排版：按 GB/T 9704-2012 生成 \.docx / \.pdf / \.txt，附输出自检。不含字体文件，字体由用户自备。

### 如何安装 @deepwhale-cn/dsh-cn-doc-formatter？

在项目目录运行 npm install @deepwhale-cn/dsh-cn-doc-formatter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/dsh-skill（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @deepwhale-cn/dsh-cn-doc-formatter 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/deepwhale-cn\_\_dsh-cn-doc-formatter 是否存在。

### @deepwhale-cn/dsh-cn-doc-formatter 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @deepwhale-cn/dsh-cn-doc-formatter 可以商用吗？

@deepwhale-cn/dsh-cn-doc-formatter 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @deepwhale-cn/dsh-cn-doc-formatter 的下载量有多少？

根据 npm 官方下载统计，@deepwhale-cn/dsh-cn-doc-formatter 在 2026/10/12 – 2026/11/10 这 30 天内被下载 1,985 次，日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @deepwhale-cn/dsh-cn-doc-formatter 还在维护吗？

最新版本 0\.2\.4 发布于 2026/10/29（16 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/09/25。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。