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

package/LICENSE

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,155 @@
+# @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 通用。
+
+## 用法
+
+技能正文里有完整命令。核心三条：
+
+```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。**本软件不包含任何字体文件**；使用者在文档中选用何种字体，由使用者自行负责
+取得该字体的合法授权。

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# @deepwhale-cn/dsh-cn-doc-formatter 的组合层
+#
+# profile 在 dsh.profile.bundles 里列出本包后，这一层会把插件本身挂进组合。
+#
+# 约定（官方 verify-cordis-config 强制）：每个具名行都必须能从本包自己的
+# 作用域解析。这里 name 写的就是本包已发布的包名 —— 加载器按这个 specifier 导入，
+# 所以它必须与 package.json 的 name 完全一致。
+- insert:
+    - id: cn-doc-formatter
+      name: '@deepwhale-cn/dsh-cn-doc-formatter'

package/fonts/PUT-FONTS-HERE.txt

@@ -0,0 +1,27 @@
+把仿宋字体文件放进这个目录即可被自动识别（可选做法）。
+
+本插件不随包分发任何字体 —— 方正仿宋等是商业字体，其授权允许在文档中使用，
+但不允许再分发字体文件本身。
+
+推荐做法（优先级从高到低）：
+
+  1. 环境变量直接指定文件（最明确，不受文件名限制）
+       export DSH_CN_FANGSONG=/path/to/仿宋.ttf
+       export DSH_CN_FANGSONG_BOLD=/path/to/仿宋加粗.ttf   # 可选
+
+  2. 环境变量指定一个目录
+       export DSH_CN_FONT_DIR=~/my-fonts
+
+  3. 放进系统字体目录（推荐，一次装好处处可用）
+       macOS    ~/Library/Fonts/
+       Windows  C:\Windows\Fonts\
+       Linux    ~/.fonts/  或  ~/.local/share/fonts/
+
+  4. 放进本插件的这个 fonts/ 目录
+       ⚠️ 注意：npm 更新本插件时这个目录可能被覆盖，建议用方式 1 / 2 / 3。
+
+脚本可自动识别的文件名：
+     FangS-SC.ttf、simfang.ttf、FangSong.ttf、FangSong_GB2312.ttf、
+     STFangsong.ttf、FandolFang-Regular.otf、仿宋.ttf、仿宋_GB2312.ttf
+
+文件名不在上面的列表里也没关系 —— 用 DSH_CN_FANGSONG 显式指定即可。

package/lib/index.js

@@ -0,0 +1,88 @@
+/**
+ * @deepwhale-cn/dsh-cn-doc-formatter — 中文公文排版
+ *
+ * 把 GB/T 9704-2012 党政机关公文格式的排版方法注册为 DSH skill，
+ * 使 agent 在需要生成公文时能按规范产出 .docx / .pdf / .txt。
+ *
+ * ── 关于字体（本插件最重要的设计约束）────────────────────────────────
+ * 本插件**不随包分发任何字体文件**。公文规范要求的仿宋（方正仿宋等）是商业字体，
+ * 其授权允许在文档中使用，但不允许再分发字体文件本身。因此这里是「排版引擎」，
+ * 字体由用户自备，通过环境变量或系统字体目录提供：
+ *
+ *   DSH_CN_FANGSONG       仿宋常规体文件的绝对路径（最高优先）
+ *   DSH_CN_FANGSONG_BOLD  仿宋加粗体（可选）
+ *   DSH_CN_FONT_DIR       一个目录，脚本在其中按文件名查找
+ *
+ * 找不到时的行为见 skill/scripts/pdf_formatter.py 的 register_fonts()：
+ * 退回系统宋体并在 stderr 打印可操作的指引，不会静默失败。
+ *
+ * ── 技能标识 ────────────────────────────────────────────────────────
+ * SKILL_NAME 取 'cn-doc-formatter' 而非 'chinese-doc-formatter'：后者是很多用户
+ * 本地已有的私有技能名，重名会与用户自己的技能冲突。加 cn- 前缀以示这是插件内嵌版本。
+ *
+ * ── 与官方 API 的约定 ───────────────────────────────────────────────
+ * 依赖 `ctx.skills`（由 @deepseek-ai/dsh-skill 提供）。缺失时插件不做任何事，
+ * 不会影响 profile 启动。
+ */
+
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+/** 本包根目录（lib/ 的上一级） */
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+/** 随包分发的 skill 与脚本所在目录 */
+const skillDir = join(packageRoot, 'skill');
+
+/** 技能正文里用来占位脚本目录的标记 —— 运行期替换成真实绝对路径 */
+const SKILL_DIR_PLACEHOLDER = '<skill目录>';
+
+export const name = 'cn-doc-formatter';
+export const inject = ['skills'];
+
+/** 技能标识：kebab-case。刻意避开 'chinese-doc-formatter'，见文件头说明 */
+const SKILL_NAME = 'cn-doc-formatter';
+
+/** 随包分发的 skill 目录绝对路径（安装后位置由加载器决定） */
+export function skillDirPath() {
+  return skillDir;
+}
+
+function skillBody() {
+  const raw = readFileSync(join(skillDir, 'chinese-doc-formatter.md'), 'utf-8');
+  // 把占位符替换为真实路径：用户安装到任何位置都能照文档直接跑脚本
+  return raw.split(SKILL_DIR_PLACEHOLDER).join(skillDir);
+}
+
+export function apply(ctx) {
+  // skills 服务缺失时静默跳过：这是一个可选能力，不应阻断 profile 启动
+  if (!ctx.skills || typeof ctx.skills.register !== 'function') {
+    ctx.logger?.warn?.('[cn-doc-formatter] 未找到 skills 服务，跳过技能注册');
+    return;
+  }
+
+  let content;
+  try {
+    content = skillBody();
+  } catch (error) {
+    ctx.logger?.error?.(`[cn-doc-formatter] 读取技能正文失败: ${String(error)}`);
+    return;
+  }
+
+  ctx.skills.register({
+    name: SKILL_NAME,
+    // 来源标记：'bundled' = 随插件分发的内嵌技能（区别于磁盘上的 project/user 技能）
+    source: 'bundled',
+    description:
+      '中文公文排版生成器。按 GB/T 9704-2012 规范生成 Word(.docx)、PDF、TXT 中文文书，' +
+      '涵盖字体字号、行距、页边距、标题层级与页码。涉及排版、格式、文书、公文、' +
+      '字体、行距等需求时使用。',
+    whenToUse:
+      '需要生成或排版中文公文/正式文书时使用——通知、报告、函、决定、意见等。' +
+      '用户提到「排版」「格式」「docx」「pdf」「word」「文书」「公文」「字体」「行距」' +
+      '时也必须使用。',
+    content,
+  });
+
+  ctx.logger?.info?.(`[cn-doc-formatter] 已注册技能 ${SKILL_NAME}`);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@deepwhale-cn/dsh-cn-doc-formatter",
+  "version": "0.1.0",
+  "description": "中文公文排版：按 GB/T 9704-2012 生成 .docx / .pdf / .txt，附输出自检。不含字体文件，字体由用户自备。",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "skill",
+    "docx",
+    "pdf",
+    "公文",
+    "排版",
+    "仿宋",
+    "GB/T 9704"
+  ],
+  "files": [
+    "lib",
+    "skill",
+    "fonts",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "dsh": ">=0.1.0-rc.6"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-skill": "*"
+  }
+}

package/skill/chinese-doc-formatter.md

@@ -0,0 +1,328 @@
+---
+name: chinese-doc-formatter
+description: 中文文书排版生成器。当用户需要生成 Word(.docx)、PDF、TXT 等格式的中文文书或文件，涉及排版、字体、行距、标题加粗等需求时使用。触发词："排版"、"格式"、"docx"、"pdf"、"word"、"文书"、"文件"、"字体"、"行距"。
+---
+
+# 中文文书排版技能
+
+生成排版规范的中文常规文书（通知、报告、函、文件等）。输出 .docx / .pdf / .txt 三种文件，全文统一使用仿宋（GB2312 简体字集）排版，严格遵循以下规范，且文档内不出现任何 AI 生成痕迹（无水印、无生成标记、无作者信息、无版本说明）。
+
+## 字体字号规范
+
+### 正文内容
+
+| 元素 | 字体 | 字号 | 字号对照（磅） |
+|------|------|------|---------------|
+| 标题 | 仿宋（全文统一） | 二号加粗 | 22pt |
+| 正文 | 仿宋 | 四号 | 14pt |
+| 一级标题 | 仿宋 | 三号加粗 | 16pt |
+| 二级标题 | 仿宋 | 三号加粗 | 16pt |
+| 三级标题 | 仿宋 | 三号加粗 | 16pt |
+| 四级标题 | 仿宋 | 三号加粗 | 16pt |
+| 数字/英文 | 仿宋（与全文一致） | 四号 | 14pt |
+| 页码 | 仿宋阿拉伯数字 | 四号半角 | 14pt |
+
+### 版头（可选，仅红头文件需要，常规文书默认不输出）
+
+份号顶格居左第一行、密级第二行、紧急程度第三行（仿宋三号）；发文字号仿宋三号（上行文左空一字，否则居中）。不设签发人。
+
+### 附件、落款、日期
+
+| 元素 | 字体 | 字号 |
+|------|------|------|
+| 附件说明 | 仿宋 GB2312 | 四号 |
+| 发文机关署名 | 仿宋 GB2312 | 四号 |
+| 成文日期 | 仿宋 GB2312 | 四号 |
+
+## 行距与页边距规范
+
+| 项目 | 规范值 |
+|------|--------|
+| 标题行距 | 固定值 33-36 磅 |
+| 正文行距 | 固定值 28 磅 |
+| 上边距 | 3.7 cm |
+| 下边距 | 3.5 cm |
+| 左边距 | 2.8 cm |
+| 右边距 | 2.6 cm |
+| 文档网格 | 每面排 22 行，每行排 28 个字（Word 按 28 磅行距设置 docGrid） |
+
+## 输出文件规范
+
+生成文件须同时输出以下格式：
+1. **Word 文档 (.docx)** — 标准排版，可编辑
+2. **PDF 文件 (.pdf)** — 打印级质量，与 Word 排版一致
+3. **纯文本文件 (.txt)** — 无格式，保留标题层级结构
+
+所有文件保存在用户指定的输出目录（默认为桌面 `公文排版输出/` 目录）。
+
+## 无 AI 痕迹要求
+
+生成的文档必须是纯粹、专业的公文，不得包含：
+- 任何作者署名、AI 标记、生成时间戳
+- 任何解释性文字、注释或说明
+- 任何文档结构说明或元信息
+- 任何来源标注或版权信息
+
+文档应仅包含用户要求的内容本身，格式专业、干净。
+
+## 字体：本插件不随包分发，需用户自备
+
+⚠️ **本插件不含任何字体文件。** 公文规范要求的仿宋（方正仿宋等）是商业字体，
+其授权允许在文档中使用，但**不允许再分发字体文件本身**。因此本插件只提供排版引擎，
+字体请自行准备 —— 这是刻意的设计，不是缺失。
+
+### 怎么提供字体
+
+PDF 需要真正读取字体文件并嵌入，按以下顺序查找，**命中即用**：
+
+| 顺序 | 来源 | 说明 |
+|---|---|---|
+| 1 | 环境变量 `DSH_CN_FANGSONG` | 直接指向仿宋字体文件，**最高优先**，最明确 |
+| 1 | 环境变量 `DSH_CN_FANGSONG_BOLD` | 加粗体（可选；不提供时标题用常规仿宋，见下） |
+| 2 | 环境变量 `DSH_CN_FONT_DIR` | 指定一个目录，脚本在其中按文件名查找 |
+| 3 | 插件自己的 `fonts/` 目录 | 用户自行把字体文件放进去 |
+| 4 | 系统字体目录 | macOS `~/Library/Fonts`／Windows `C:\Windows\Fonts`／Linux `~/.fonts`、`/usr/share/fonts` |
+| 5 | WPS Office 安装目录 | WPS 自带方正仿宋 |
+
+**用法示例**：
+
+```bash
+# 方式一：直接指定文件（推荐，最明确、不受文件名限制）
+export DSH_CN_FANGSONG=/path/to/仿宋.ttf
+
+# 方式二：指定一个目录
+export DSH_CN_FONT_DIR=~/my-fonts
+```
+
+**可自动识别的仿宋文件名**：`FangS-SC.ttf`、`simfang.ttf`、`FangSong.ttf`、
+`STFangsong.ttf`、`FandolFang-Regular.otf`、`仿宋.ttf` 等。
+文件名不在列表里的，用 `DSH_CN_FANGSONG` 显式指定即可。
+
+**找不到时的行为 —— 不会静默失败**：
+- PDF 退回系统宋体，并在 stderr 打印上面这张获取指引
+- docx 退回本机可用的宋体族名，并打印同样格式的提示
+
+### Word 文档 (.docx)
+
+docx 只在文件里**声明字体族名**，实际渲染由用户机器上的 Word 完成，
+所以 docx 不依赖字体文件本身。脚本会实测本机已装字体，按优先级取第一个命中的族名：
+
+| 顺序 | 字体族名 | 说明 |
+|---|---|---|
+| 1 | `仿宋_GB2312` | Windows 标准公文仿宋 |
+| 2 | `FangS-SC` | 方正仿宋（WPS 自带；需自备） |
+| 3 | `仿宋` | Windows 自带仿宋的另一族名 |
+| 4 | `FandolFang R` | macOS 常见仿宋替代（注意真实族名带空格与 R） |
+| 5 | `STFangsong` | macOS 华文仿宋 |
+| 6 | `Songti SC` | 最后回退：宋体 |
+
+标题与小标题通过**加粗**区分，字体族与正文一致：
+
+| 元素 | 字体 | 加粗 |
+|------|------|------|
+| 标题 | 上表命中的仿宋族 | 是 |
+| 正文 | 上表命中的仿宋族 | 否 |
+| 一/二/三/四级标题 | 上表命中的仿宋族 | 是 |
+| 附件、署名、日期、页码 | 上表命中的仿宋族 | 否 |
+
+### PDF 文档
+
+PDF 需要**嵌入字体**，所以必须有真实字体文件（见上）。
+
+- 正文 / 版头 / 页码 → 仿宋常规体
+- 标题 / 各级小标题 → 仿宋加粗体
+
+**没有加粗字体时**（用户自备字体的常态）：标题**继续使用常规仿宋**，只是不加粗。
+这样保住了「全文统一仿宋」这条硬规范 —— 宁可字重不够，也不换成宋体。
+需要真加粗时用 `DSH_CN_FANGSONG_BOLD` 指定加粗体文件。
+（reportlab 不做合成粗体，这是引擎限制。）
+
+### 页码处理
+页码使用宋体，四号（14pt）半角阿拉伯数字，格式为 `- 1 -`：
+- PDF：每页页脚输出，单页码居右空一字，双页码居左空一字
+- Word：页脚插入 PAGE 域，奇数页居右空一字，偶数页居左空一字
+
+## 工作流程
+
+### 第一步：确认文档类型和内容
+
+向用户确认：
+- 文档类型：一般文书（通知、函、报告等）/ 红头文件 / 其他正式文本
+- 是否需要版头（份号、密级、紧急程度、发文字号；默认不需要）
+- 正文内容是什么
+- 输出目录（默认为桌面）
+
+### 第二步：生成文件
+
+调用脚本生成 docx 和 pdf：
+
+```bash
+# 生成 Word 文档
+python "<skill目录>/scripts/docx_formatter.py" \
+  --output /path/to/output \
+  --title "标题文字" \
+  --body "正文内容..." \
+  --sender "发文机关名称" \
+  --date "成文日期"
+
+# 生成 PDF
+python "<skill目录>/scripts/pdf_formatter.py" \
+  --output /path/to/output \
+  --title "标题文字" \
+  --body "正文内容..." \
+  --sender "发文机关名称" \
+  --date "成文日期"
+```
+
+### 第三步：生成 TXT 版本
+
+从内容中提取纯文本，按标题层级保留结构，生成 .txt 文件。
+
+### 第四步：输出自检（**不要跳过**）
+
+```bash
+python "<skill目录>/scripts/verify_output.py" --dir <输出目录>
+```
+
+逐项核对页边距、标题字号加粗、正文行高、字体是否本机存在、PDF 是否嵌入仿宋、页面是否 A4。
+**退出码 0 = 通过，1 = 有不符合项** —— 必须处理完再交付。
+
+### 第五步：确认输出
+
+告知用户文件位置和格式，附上简要说明。
+
+---
+
+## 从 Markdown 生成（常见场景）
+
+内容常以 Markdown 写就，直接喂给脚本会**丢失层级**（整篇被当正文）。
+先用 `md_adapter.py` 转换：
+
+```bash
+python "<skill目录>/scripts/md_adapter.py" \
+  --input 原文.md --output /tmp/_body.txt [--drop-meta]
+```
+
+转换规则：
+
+| Markdown | 转成 | 公文层级 |
+|---|---|---|
+| `# 标题` | （丢弃，作为 `--title` 传入） | — |
+| `## 一、小节` | `一、小节` | 一级标题 |
+| `### 1.1 小节` | `（一）小节` | 二级标题 |
+| `#### 更深` | `1. 小节` | 三级标题 |
+| `- 列表项` | 正文 | 正文 |
+| `| 表格 |` | `表头：值；表头：值。` | 正文 |
+| `> 引用块` | 正文（连续行自动合并） | 正文 |
+
+再把 `_body.txt` 内容作为 `--body` 传给 docx/pdf 脚本。
+
+**注意**：`md_adapter` 会把同一段内的软换行合并成一行（源文档常手动折行，
+逐行当独立段落会在断句处留下孤立标点，如单独一行的「、」）。
+
+## 文种
+
+公文文种（通知 / 报告 / 函 / 决定 / 意见 等）由**内容本身**决定，脚本不做区分 ——
+排版规范对所有文种是一致的，差别只在于正文怎么写。
+
+常用文种及其特征，供起草时参考：
+
+| 文种 | 特征 |
+|------|------|
+| 通知 | 最常见，含主送机关、正文、发文机关署名、日期 |
+| 报告 | 上行文，汇报工作、反映情况 |
+| 函 | 平行文或不相隶属机关之间的商洽工作 |
+| 决定 | 重要事项决策 |
+| 意见 | 对重要问题提出见解和处理办法 |
+
+> ⚠️ 早期版本的本 skill 文档里写过 `--type notice` 参数，**该参数在脚本中并不存在**
+> （命令行会直接报 `unrecognized arguments`）。文种无需传参，已在本版修正。
+
+## 特殊处理
+
+### 版头信息
+- 份号：顶格居左排在版心第一行
+- 密级：第二行；紧急程度：第三行
+- 发文字号：仿宋，三号；上行文左空一字，下行文居中
+- 不设签发人；常规文书默认不带版头
+
+### 标题格式
+- 居中，二号字加粗，仿宋
+- 标题行距 33-36 磅
+
+### 一级标题
+格式：一、二、三……（仿宋，三号加粗，左空二字）
+
+### 二级标题
+格式：（一）（二）（三）……（仿宋，三号加粗，左空二字）
+
+### 三级标题
+格式：1. 2. 3. ……（仿宋，三号加粗，左空二字）
+
+### 四级标题
+格式：（1）（2）（3）……（仿宋，三号加粗，左空二字）
+
+### 正文段落
+- 四号（14pt）仿宋 GB2312，首行缩进严格 2 字
+
+### 发文机关署名和日期
+- 距正文（或附件说明）下空 3 行
+- 署名以成文日期为准居中编排
+- 日期用阿拉伯数字，右空 4 字
+- 署名在上，日期在下
+
+### 页码
+- 格式："- 1 -"（单页码右空一字，双页码左空一字）
+- 位置：版心下边缘之下的页脚区（PDF 每页输出；Word 奇偶页页脚插入 PAGE 域）
+- 字体：宋体，四号，半角
+
+---
+
+## 附录：2026-09-22 修复记录
+
+本 skill 曾有四处缺陷，已在当日修复，此处存档以免重犯。
+
+### 1. 字体探测在 macOS 上恒失败（**最严重**）
+
+```python
+# 原实现
+out = subprocess.run(['fc-list', f':family={family}'], ...)
+return bool(out.stdout.strip())
+```
+
+`fc-list` 是 fontconfig 的命令，**macOS 不预装**。异常被 `except` 吞掉后函数恒返回
+`False`，于是**即使机器上装了 `仿宋_GB2312` 也检测不到**，永远走回退分支。
+
+→ 已改为直接扫描字体文件读 `name` 表（fontTools），macOS / Windows / Linux 通用，
+  并逐个候选名实测，避免再把字体名写错。
+
+### 2. 常规仿宋依赖 WPS 安装路径
+
+`pdf_formatter.py` 只从 `/Applications/wpsoffice.app/...` 找 `FangS-SC.ttf`。
+未装 WPS 的机器会**静默退回宋体**，与「全文仿宋」规范不符。
+
+→ 当时把 `FangS-SC.ttf` 纳入 `fonts/` 随 skill 分发，查找顺序改为
+  自带 → 用户字体目录 → WPS → 系统。
+
+→ **2026-09-25 再修正**：该字体是方正商业字体，授权允许在文档中使用，
+  **不允许再分发字体文件本身**。本插件改为**不随包分发任何字体**，
+  只提供排版引擎；字体由用户通过 `DSH_CN_FANGSONG` / `DSH_CN_FONT_DIR`
+  或系统字体目录自备。详见前文「字体：本插件不随包分发，需用户自备」。
+
+### 3. 不支持 Markdown 输入
+
+内容以 Markdown 写就时，整篇会被当作正文，层级全部丢失。
+
+→ 新增 `scripts/md_adapter.py`。
+
+### 4. 没有输出自检
+
+生成完不知道是否真的符合规范（页边距、字号、行距、字体、A4 尺寸）。
+
+→ 新增 `scripts/verify_output.py`，退出码可用于卡口。
+
+### 安装位置说明
+
+skill 实际存放在 `~/.claude/skills/`，同时在 `~/.dsh/skills/` 建了软链接。
+**两处都需要**：前者供 Claude Code 使用，后者供 DSH 自动加载。
+如新会话未自动加载本 skill，先检查 `~/.dsh/skills/chinese-doc-formatter` 链接是否存在。