公文处理助手 linhut/gongwen-skill

公文全流程处理专家

中文公文全流程处理专家——基于 GB/T 9704《党政机关公文格式》 国家标准，支持 格式检查与修复、内容优化（Word 原生修订+批注/差异对比版）、模板生成、Markdown 转公文、版头版记页码注入、事实核验、风格增强 等完整能力。原生支持 DeepSeek Harness (DSH) 技能系统，打包为可被 AI 智能体直接调用的技能，完全自包含，克隆即用。

本技能源自开源桌面项目 AI 公文智能优化助手，抽取其核心格式引擎，剥离桌面端与数据库依赖后独立发行，支持公文的模板建立、解析、规则检查、自动修复、内容优化、Markdown 转公文全流程能力。同时原生集成 DeepSeek Harness (DSH) 技能系统，DSH 智能体可自动发现并加载。

✨ 能力一览

| 能力 | 命令 | 说明 |
| 📋 列类型 | list-types | 列出 25 种支持的公文类型（新增主持词 host_speech；含新闻稿/讲话稿） |
| 🏗️ 模板生成 | template | 按类型生成 GB/T 9704 标准空白模板 |
| 🔍 解析 | parse | .docx → 结构化 DocumentModel（含文本框/修订摘要） |
| ✅ 格式检查 | check | 按国标检查，分级 P0/P1/P2（只读） |
| 🔧 格式修复 | optimize | 自动修复字体/字号/行距/页边距，输出合规文档；--verify 单命令闭环自动复查、P0 存在时退出码非 0；--json 结构化输出 |
| ✍️ 内容优化 | optimize-content | 内容润色：默认 Word 原生修订+批注（审阅面板逐条接受/拒绝），可选行内差异对比版；--precheck 预检 changes 与原文一致性、--preset quick/full/review 参数收敛 |
| 📝 草稿转公文 | md2docx | Markdown 文本直接转为格式化 .docx（支持 Front Matter） |
| 🚀 一站式生成 | draft | Markdown 草稿 → 国标成品 + 自动验证（路径 C 四步合一） |
| 📄 模型生成 | generate | 从 JSON 模型生成 .docx |
| 🔴 版头 | header | 注入发文机关标志 + 发文字号 + 签发人 + 红色反线 |
| 📑 版记 | footer | 注入抄送机关 + 印发机关 + 印发日期 + 分隔线 |
| 🔢 页码 | pagenum | 注入 Word PAGE 域动态页码（宋体 4 号，默认单右双左适配双面打印） |
| 🖊️ 首句加粗 | bold-first | 正文段落首句自动加粗（公文规范） |
| 🧰 一键修复 | fix-common | 路径 D 一键修复常见格式：段落类型修正 + 编号拆分 + 首句加粗 + 加粗范围修复 |
| 📋 桌签生成 | table-signs | 批量生成 A5 横版会议桌签 |
| 🔍 审稿生成 | review | 按五角色审稿机制生成审稿意见 |
| 🧩 完整审校 | full-review | 修订+批注联合命令（句子级差异修订 + 分类批注） |
| 🎨 样式学习 | style-learn / style-list | 上传标准文档学习 Run/段落/页面三级样式（字体/字号/字间距/行距/缩进/页边距），生成命名模板持久化，后续用 optimize -t 模板名 套用 |
| 🔄 版本自检 | check-update | 版本自检（PyPI pip 包权威判定 + GitHub 备用，GitCode/AtomGit 作国内镜像提示；GitHub 不可达时自动做 DNS 污染诊断 + hosts 建议） |
| 🩺 自我诊断 | doctor / repair | 全面诊断 23 项（Python/依赖/版本一致性/字体/DSH 文件/DSH 技能 frontmatter/代码风格/网络 DNS），自动修复常见问题；--offline 跳过网络检查 |
| 🕵️ 文档审计 | audit | 检查删除线/加粗/AI 声明等痕迹 |
| 🤝 会话交接 | handoff | 跨会话上下文传递（--list / --latest / 智能体长任务收尾必写） |
| ⚙️ 规则管理 | rule-export/import/list | YAML 规则三层定制（官方/单位/用户） |
| 🧭 向导式交互 | wizard | 交互式路径引导（A/B/C/D/E）+ 一键执行；智能体用 --answers 非交互 / --dry-run 只打印命令 |

使用示例

在 AI 对话中调用 gongwen-skill，输入自然语言指令，自动生成符合 GB/T 9704 国标格式的正式公文。

🤖 调用环境的适配指引（AI 智能体必读）

本工具针对不同能力层级的 AI 调用环境，提供不同的使用方式。AI 读取本文件后，请先判断自身环境属于哪一类，再按对应指引执行：

| 环境类型 | 典型平台 | 能力 | 使用方式 |
| ① 可执行代码的智能体 | WorkBuddy、CloudCode、Claude Code、AtomCode、DeepSeek Harness | 可运行命令、读写本地文件 | 直接执行 python -m gongwen <命令>，见下方「快速开始」与「通过智能体调用」 |
| ② 纯对话 LLM（无代码执行能力） | 豆包、Kimi、ChatGPT 网页版等 | 只能阅读文本、给出建议，不能运行命令或读写文件 | 引导用户手动执行，见下方「纯对话 LLM 使用指引」 |

纯对话 LLM 使用指引（环境 ②）

如果你是无法执行代码的纯对话 AI（如豆包、Kimi、ChatGPT 网页版等），请按以下方式协助用户：

1. 告知工具性质：向用户说明「这是一个本地运行的 Python 命令行工具，需要在你自己的电脑上安装后使用」，并说明它能做什么（格式检查、自动修复、内容优化、模板生成等 29 项命令能力）。
2. 引导安装：请用户在自己的电脑上执行以下步骤：步骤 1：克隆仓库
git clone https://github.com/linhut/gongwen-skill.git
cd gongwen-skill

步骤 2：安装依赖（需要 Python 3.10+）
pip install -r requirements.txt
或直接安装 PyPI 包：
pip install gongwen-skill

3. 按需给出具体命令：根据用户的实际需求，给出对应的命令让用户自行执行：

| 用户需求 | 建议用户执行 |
| 检查公文格式 | python -m gongwen check 公文.docx -t notice --json |
| 自动修复格式 | python -m gongwen optimize 公文.docx -o 成品.docx -t notice --apply |
| 生成标准模板 | python -m gongwen template notice -o 通知模板.docx |
| Markdown 转公文 | python -m gongwen md2docx 草稿.md -o 正式公文.docx -t report |
| 内容润色（修订+批注） | python -m gongwen optimize-content 原文.docx --changes 修订内容.json --apply --mode tracked |
| 注入版头/版记/页码 | python -m gongwen header/footer/pagenum 公文.docx ... |
| 从标准文档学样式做模板 | python -m gongwen style-learn 标准公文.docx -n 模板名，之后用 optimize -t 模板名 套用 |
| 安装标准字体 | python -m gongwen font install |

4. 解释输出：用户执行后，把命令输出结果（问题清单、修复报告、生成文件等）发给你时，你能继续帮助解读、判断下一步操作。
5. 注意事项：你不能代替用户执行任何命令，也不能读取用户本地的文件内容——所有文件操作都必须由用户在你的指引下完成。

文字性资源库（纯对话 LLM 可读的知识源）

项目内置以下文字性资源，纯对话 AI 可以直接读取，用作公文写作指导的知识库：

| 资源 | 位置 | 内容 |
| 公文语言风格提示词库 | prompts/style-prompts.md | 6 套风格（庄重严谨/平实简洁/宏观概括/请示商洽/法规条文/讲话稿），每套含用词规范、句式和语气指导 |
| 使用指引与决策速查 | prompts/usage-prompts.md | 最小可用指引、决策速查、每种公文类型的用法模板、常见问题解答 |
| 公文类型规则库 | rules/official/.yaml（25 个文件） | 每种公文类型的格式规范 + 内容层定义（如"请示应以'妥否，请批示'结尾""通知应以'特此通知'结尾"） |
| 通用格式标准 | rules/official/_common.yaml | GB/T 9704 国标全文参数：字体/字号/行距/页边距等 |
| 技能完整指令 | SKILL.md | 路径路由、执行标准、质量评审、禁令清单、审稿机制 |

使用方式：纯对话 AI 在回答用户关于公文写作的问题时，可直接引用上述资源中的内容，例如：
- 用户问"通知怎么写" → 引用 rules/official/notice.yaml 的结语规范和 style-prompts.md 的庄重严谨风格
- 用户问"请示和报告的区别" → 引用 request.yaml 和 report.yaml 的规则说明
- 用户问"公文用什么字体" → 引用 _common.yaml 中的 GB/T 9704 标准
- 用户需要润色文字 → 引用 style-prompts.md 中对应的风格提示词

这些资源均以纯文本格式存储，纯对话 AI 可直接读取解读，无需执行任何代码即可提供专业的公文写作指导。

🚀 快速开始

git clone https://github.com/linhut/gongwen-skill.git
cd gongwen-skill
pip install -r requirements.txt

生成一份标准通知模板
python -m gongwen template notice -o 通知模板.docx

检查公文格式（只读）bash
python -m gongwen check 公文.docx -t notice --json

自动修复格式（--apply 确认执行，默认预览）；--verify 生成后自动复查，P0 存在时退出码非 0

python -m gongwen optimize 公文.docx -o 成品.docx -t notice --apply --verify

一步到位：检查 + 修复 + 版头/版记/页码全注入（--layout 指向 JSON 配置）

python -m gongwen optimize 公文.docx -o 成品.docx --layout 版式.json

Markdown 草稿 → 正式公文（支持管道输入和 Front Matter 元数据）

python -m gongwen md2docx 草稿.md -o 正式公文.docx -t report --signer "XX单位" --date "2026年8月1日"

一步到位：Markdown 草稿 → 国标成品 + 自动验证（路径 C 四步合一）

python -m gongwen draft 草稿.md -o 正式公文.docx -t report --signer "XX单位" --date "2026年8月1日"

内容优化（默认 tracked 模式：Word 原生修订+批注，审阅面板逐条接受/拒绝）

python -m gongwen optimize-content 原文.docx --changes 修订内容.json --apply --mode tracked -t news

预检 changes 与原文一致性（不生成文档，输出不匹配清单+相似度诊断；不匹配时退出码 1）

python -m gongwen optimize-content 原文.docx --changes 修订内容.json --precheck

预设组合：quick 精简快速 / full 完整默认 / review 完整审稿（显式参数优先）

python -m gongwen optimize-content 原文.docx --changes 修订内容.json --apply --preset full

注入版头（发文机关标志 + 发文字号 + 签发人 + 红色反线）

python -m gongwen header 公文.docx -o 红头公文.docx --org-name "XX单位" --doc-number "〔2026〕1号"

注入版记（抄送 + 印发机关 + 印发日期）

python -m gongwen footer 红头公文.docx --cc "各单位" --printer "XX办公室" --print-date "2026年8月1日"

注入页码（Word PAGE 域动态页码）

python -m gongwen pagenum 红头公文.docx --alignment right

版本自检（PyPI pip 包权威判定 + GitHub 备用渠道）

python -m gongwen check-update

安装公文标准字体（方正小标宋简体/仿宋_GB2312/楷体_GB2312）

python -m gongwen font install # 安装字体到系统
python -m gongwen font check # 检查字体安装状态
python -m gongwen font list # 列出字体清单

从标准文档学习排版样式，生成自定义模板（后续用 optimize -t 模板名 套用）

python -m gongwen style-learn 标准公文.docx -n 模板名
python -m gongwen style-list # 列出已学习的模板

🖥️ Windows 控制台编码（GBK 乱码排查）

工具内部已统一按 UTF-8 输出（gongwen/_bootstrap.py 强制 stdout/stderr/stdin 重配置为 UTF-8，保证管道/Agent 调用无编码问题）。若在原生 cmd（默认 GBK 代码页 936）看到中文乱码，任选其一：

- 推荐：改用 Windows Terminal / VS Code 终端（默认 UTF-8，无乱码）
- 在 cmd 中先执行 chcp 65001 切换 UTF-8 代码页，再运行命令
- 或设置环境变量 PYTHONIOENCODING=utf-8（与工具内部行为一致）

说明：GBK 乱码仅影响原生 cmd 的交互显示，不影响文件内容与 --json 的机器可解析性。

🔤 字体管理

公文标准字体是 GB/T 9704 排版的关键。项目内置 3 个标准字体文件（assets/fonts/），支持自动安装：

| 字体 | 用途 | TTF 大小 |
| 方正小标宋简体 | 公文大标题 | 3.7 MB |
| 仿宋_GB2312 | 正文 | 3.8 MB |
| 楷体_GB2312 | 二级标题 | 3.9 MB |

安装方式：
- git clone 用户：字体文件在 assets/fonts/ 中，直接安装
- pip install 用户：字体不打包到 PyPI（体积过大），font install 会自动从 GitHub 仓库 下载到 ~/.gongwen-skill/fonts/ 缓存后安装 bash
python -m gongwen font install # 一键安装 3 个标准字体
python -m gongwen font check # 检查安装状态

✍️ 内容优化（路径 B）核心能力

三种输出模式（--mode）

| 模式 | 说明 |
| tracked（默认） | Word 原生修订标记（w:del/w:ins）+ 批注（comments.xml），审阅面板逐条接受/拒绝 |
| comment-mode | 仅 Word 原生批注（可审阅→接受/拒绝） |
| inline | 行内差异对比版（原文灰色删除线 + 优化后红色高亮 + 修改说明） |

8 色审阅角色方案

批注/修订按语义类别自动分配角色与颜色，Word 中可按审阅者筛选：

| 角色 | 类型 | 颜色 | 色值 | 语义类别 |
| 格式审校 | 批注 | 蓝 | 2E86C1 | 格式优化 |
| 用语审校 | 批注 | 绿 | 27AE60 | 用语优化 |
| 逻辑审校 | 批注 | 红 | E74C3C | 逻辑优化 |
| 法规审校 | 批注 | 紫罗兰 | 9B59B6 | 法规合规 |
| 综合审校 | 批注 | 橙 | F39C12 | 内容优化 |
| 事实核验 | 批注 | 青 | 00BCD4 | 事实核验 |
| GongWen-Skill修订 | 修订 | 玫红 | E91E63 | 内容/事实核验修订 |
| 风格审校 | 批注+修订 | 深紫 | 6C3483 | 风格优化（自动应用） |

事实核验

- 默认执行（不依赖 --background）：实体提取（人名/职务/机构全称）→ 互联网交叉核验 → 生成"存疑/已确认/未经核验"批注
- 实体属性核验：识别人名+职务配对（如"××单位党组成员、副主任XXX"），能发现职务写反等严重事实错误
- LLM+规则混合提取：配置 GONGWEN_LLM_API 后 LLM 内容理解提取（主通道）+ 规则提取（兜底）
- 背景资料增强：--background 传入 docx/pdf/md/txt/URL 构建基准，已确认实体自动过滤

智能体协作机制（--output-tasks / --input-tasks）

技能定位为工具层——确定性工作自己做，需 LLM/搜索判断的环节交由智能体： bash

1. Skill 输出待处理任务（待核验实体 + 风格增强请求），同时生成基础版文档

python -m gongwen optimize-content 新闻稿.docx --changes changes.json \
--output-tasks tasks.json --apply --mode tracked -t news

2. Agent 用自身 LLM+搜索能力处理 tasks.json（核验人事信息、生成风格建议），输出 tasks_result.json

3. Skill 读入回填结果，合并到 changes 后执行（去重/已确认过滤/独立修订作者）

python -m gongwen optimize-content 新闻稿.docx --changes changes.json \
--input-tasks tasks_result.json --apply --mode tracked -t news

风格增强（v2，数据驱动）

- 输出 5 套上下文信号：段落角色标注（复用 structure 规则关键词）、文档类型规则摘要（structure 含 modes/focus_checks/title_patterns）、结构/焦点检查结果、数据驱动风格评分（completeness/compliance/change_density/style_deviation_hint）、完整已有变更摘要（不再截断）
- 风格建议 auto-accept 自动合入已有变更（difflib 映射），不生成独立修订；批注标注【已自动应用】
- 跨 20+ 文档类型自动适配（rules YAML 数据驱动，不硬编码）

结构/焦点自动检查

- 结构完整性检查（structure_checker.py）：按 rules YAML 的 structure 定义检查必要段落/要素，多候选评分定位段落
- focus_checks 自动检查（focus_checker.py）：逻辑闭环（听取→指出→强调→要求）/时间一致性/事实表述客观克制/稿源编辑信息/简称定义规范
- 检查结果自动生成按角色区分的批注

命令行参数速查

--mode tracked|inline 输出模式（默认 tracked） --reviewers 3|5|6 审稿角色数（默认 6 完整版） --changes <json> 变更列表（paragraph_index/original_text/optimized_text/reason/category） --background <paths> 背景资料（事实核验基准） --auto-generate 无 changes.json 时基于内置规则自动生成优化建议（需 LLM） --output-tasks <json> 输出待 Agent 处理任务 --input-tasks <json> 读入 Agent 回填结果 --style <名称> 语言风格（--style 显式 > changes.style > doc_type 映射 > 默认庄重严谨） --no-style-enhance 禁用风格增强（默认开启） -t/--doc-type <类型> 显式指定公文类型（默认自动检测） --show-rules 输出文档类型内容层规则摘要 --show-confirmed 已确认实体也生成批注

🧭 向导式交互（wizard）

交互式引导选择处理路径并一键执行，适合不熟悉命令行的用户；智能体可走非交互模式： bash
python -m gongwen wizard # 终端交互：菜单选 A/B/C/D/E → 逐项填参 → 预览确认 → 执行
python -m gongwen wizard --answers 答案.json # Agent 非交互：跳过提问直接执行
python -m gongwen wizard --answers 答案.json --dry-run # 只打印将执行的命令

--answers 扁平 JSON（顶层带 path）： json {"path": "A", "input": "原文.docx", "doc_type": "notice", "output": "成品.docx", "apply": true}

路径：A 格式优化（optimize）｜B 内容优化（optimize-content）｜C 生成模板（template）｜D 一键格式修复（fix-common）｜E 样式学习（style-learn）。A/B/D 默认先预览再 y/n 确认；不写 apply 时非交互模式仅预览不执行（安全默认）。

📐 GB/T 9704 标准格式

| 元素 | 字体 | 字号 | 对齐 |
| 公文标题 | 方正小标宋简体 | 二号（22pt） | 居中 |
| 一级标题（一、二、三） | 黑体 | 三号（16pt） | 顶格 |
| 二级标题（（一）（二）） | 楷体_GB2312 | 三号（16pt） | 首行缩进2字符 |
| 三级标题（1. 2.） | 仿宋_GB2312 加粗 | 三号（16pt） | 首行缩进2字符 |
| 正文 | 仿宋_GB2312 | 三号（16pt） | 首行缩进2字符 |
| 西文/数字 | Times New Roman | 与中文字号一致 | — |
| 页码 | 宋体（4号半角） | 四号（14pt） | 单页右/双页左（双面打印） |
| 页边距 | — | — | 上2.8/下2.8/左2.7/右2.7 cm（工具实际采用值，见 _common.yaml） |

讲话稿（speech 朗读件）

页边距为国标默认（上3.7/下3.5/左2.8/右2.6 cm）；标题方正小标宋简体 24pt 居中、行距 35pt；一级标题黑体 18pt、二级标题楷体_GB2312 18pt；署名/日期楷体_GB2312 18pt 居中、行距 35pt；正文仿宋_GB2312 18pt 不加粗、行距 30pt exact、首行缩进 2 字符；跳过版头/版记/发文字号/密级检查。（样式以最终版定稿为准）

主持词（host_speech 朗读件）

页边距与普通公文一致（上2.8/下2.8/左2.7/右2.7 cm）；标题方正小标宋简体 24pt 居中、行距 35pt；主持人信息/日期楷体_GB2312 18pt 居中、行距 30pt；正文仿宋_GB2312 18pt 不加粗、行距 30pt exact、首行缩进 2 字符，议程引导句（"下面，进行第X项议程…"）可局部加粗；跳过版头/版记/发文字号/密级检查。（样式以最终版定稿为准）

📚 支持的 25 种公文类型

通知 · 请示 · 报告 · 函 · 会议纪要 · 纪要 · 决定 · 通告 · 公告 · 命令 · 通报 · 议案 · 批复 · 指示 · 制度 · 公报 · 意见 · 总结 · 方案/计划 · 桌签 · 技术方案 · 决议 · 新闻稿/简报 · 讲话稿 · 主持词

每种类型对应 rules/official/.yaml，含格式规则 + 内容层定义（structure/focus_checks/title 等），驱动 check/optimize/optimize-content 全链路。

⚙️ 规则化与二次定制

规则以 YAML 定义，三层优先级 official < custom < user：

- 官方规则：仓库内 rules/official/.yaml
- 用户覆盖：~/.gongwen-skill/user_rules/.yaml（同名字段覆盖官方） bash
python -m gongwen rule-export notice -o notice_rules.yaml
python -m gongwen rule-import my_company -f 公司规范.yaml
python -m gongwen rule-list --source all

⚠️ 使用红线

- 不伪造、冒用真实机关正式发文 — 生成物仅为草稿，正式发文须走审核流程
- 人事信息准确性铁律 — 领导姓名/机构全称/职务等仅有"确定"或"[XXX] 占位"两种状态，严禁推理/猜测填造
- 不编造政策依据、数据、结论 — 缺失信息用 XXX 占位
- 涉密材料先脱敏再处理
- 字体版权 — 方正小标宋简体等字体可能受版权约束，缺少时 Word 会回退

🤖 作为 AI Agent Skill 使用

将本仓库放入 Agent 的 skills 目录，Agent 读取 SKILL.md 后自动调用命令。支持三条路径：

- 路径 A：格式修复（不改文字，只修排版）
- 路径 B：内容优化（润色文字，Word 原生修订+批注 / 差异对比版）
- 路径 C：生成公文（从零创建，四步流水线；draft 命令可一步到位）

平台适配：SKILL.md 采用通用 frontmatter（name/description/whenToUse/user-invocable），兼容 WorkBuddy、CloudCode、Claude Code、AtomCode、DeepSeek Harness 等以 SKILL.md 为技能清单的平台；纯对话 LLM（无代码执行能力）请参见上方「纯对话 LLM 使用指引」。

🔄 版本追新（Agent 加载 skill 后必须执行）

Agent 加载 skill 后必须执行版本追新自检，确保使用最新版本：

1. 远程自检（首选）：python -m gongwen check-update——以 PyPI（pip 包发布源）为权威判定渠道并发查询比对本地（pip install -U 即从 PyPI 拉取）；PyPI 不可达时回退 GitHub tag（备用渠道）。全部渠道不可达时明确告知"版本自检跳过"。GitHub 为海外渠道（国内常超时）采用短超时快速降级；GitHub 不可达时自动提示国内代码镜像（GitCode/AtomGit，与 GitHub 同源 tag）、GitHub520 hosts 加速方案，并自动做 DNS 污染诊断（对比系统解析与安全 DNS/DoH 真实 IP，输出可直接粘贴的 hosts 条目建议）
2. 本地 git tag 对比（补充）：对 skill 安装目录执行 git -C "<skill安装目录>" describe --tags --abbrev=0；若安装目录不在 git 管理下，应告知用户"无法执行版本对比，建议手动检查 GitHub 更新"
3. 落后则警告：发现本地版本落后于最新版本时，必须在执行前警告用户并提示更新——check-update 会按安装形态自动给出精准更新命令（pip 包安装：pip install --upgrade gongwen-skill；git/skill 目录安装：cd <gongwen-skill目录> && git pull && git fetch --tags），不得静默使用旧版本

严禁只用本地 git describe 判断版本——它只读本地可达 tag，未 fetch 时会误判本地即最新。

🚀 DeepSeek Harness (DSH) 集成本技能同时支持 DeepSeek Harness (DSH) 的两种集成方式——文件系统 技能（轻量、跟随项目）与 Cordis 插件 bundle（包入 npm 通道、让 Web UI Toolkit 可调用），按你的部署需求选择。

DSH 采用 Cordis 模块化微内核架构：技能体系基于本地文件系统（无中心化技能市场），插件体系基于 npm 包 + ~/.dsh/profiles/<preset>/package.json 中的 dsh.profile.bundles 声明挂载。

方式零：仅作为 Python CLI 使用（最轻量） bash
git clone https://github.com/linhut/gongwen-skill.git
cd gongwen-skill
pip install -r requirements.txt # 或 pip install gongwen-skill（已上 PyPI）
python -m gongwen --version # 检验：gongwen-skill v2.12.0

方式一：作为 DSH 技能注册（基于本地文件系统）

DSH 智能体启动时自动扫描下表目录中的技能（优先级从高到低）：

| 优先级 | 目录 | 说明 |
| 100 | {project}/.dsh/skills/ | 项目级 DSH 技能目录 |
| 200 | {project}/.agents/skills/ | 项目级智能体技能目录 |
| 400 | ~/.dsh/skills/ | 用户级 DSH 技能目录 |
| 500 | ~/.agents/skills/ | 用户级智能体技能目录 |

安装方式（二选一）： bash

A. 项目级：克隆到工程目录（跟随项目，推荐）

git clone https://github.com/linhut/gongwen-skill.git ./third_party/gongwen-skill
ln -s ./third_party/gongwen-skill/.dsh/skills/gongwen-skill ./.dsh/skills/gongwen-skill

B. 用户级：全局可用，所有 DSH 会话都能发现

git clone https://github.com/linhut/gongwen-skill.git ~/skills/gongwen-skill
mkdir -p ~/.dsh/skills/
ln -s ~/skills/gongwen-skill/.dsh/skills/gongwen-skill ~/.dsh/skills/gongwen-skill

两种方式都会让 DSH 智能体在启动时自动发现并加载本技能；本仓库自带 .dsh/skills/gongwen-skill/ 双格式（目录技能 + 单文件技能）兼容。

方式二：作为 DSH Cordis 插件安装（注册到 Web Profile）

把本仓库当作 npm 包安装到 DSH Web Profile，让 DSH 的 Web UI 通过 gongwen-skill 调用桥接器执行 Python CLI。
bash

1️⃣ 用 DSH 官方 CLI 一键挂载（推荐：自动改 package.json + 重建 bundle）

dsh plugin --profile web add -w gongwen-skill

-w = workspace，按 preset 自动写入 ~/.dsh/profiles/web/package.json

bash

2️⃣ 或在 Web Profile 目录下手动 npm/pnpm 安装

cd ~/.dsh/profiles/web
npm i gongwen-skill -w

或：

pnpm add -w gongwen-skill

安装后请确认 ~/.dsh/profiles/web/package.json 中的 dsh.profile.bundles 数组已包含 gongwen-skill： jsonc { "name": "dsh-profile-web", "private": true,
"dependencies": {
"@deepseek-ai/dsh-base": "...",
"@deepseek-ai/dsh-web-app": "...",
"gongwen-skill": "^2.12.0"
},
"dsh": {
"profile": {
"bundles": [
"@deepseek-ai/dsh-base",
"@deepseek-ai/dsh-web-app",
"gongwen-skill"
]
}
}
}

注意：若 add 启动报错提示子包重复声明，请检查 dsh.profile.bundles 数组中仅包含根包 gongwen-skill，避免同时列入 engine 或 gongwen 等子目录。
DSH 版本要求：支持 DSH ≥ 0.1.2-rc.1。插件按 DeepSeek Harness 0.1.2-rc.1 官方开发文档（Bluebook · Developer Guide）实现——ctx.tools.register(defineTool(...))（模型工具）、ctx.settings.register + settings.section 平级菜单（配置，设置侧边栏「文档样式配置」）、ctx.systemPrompt.section、ctx.skills.register。需要承载这些 API 的 DSH 组合（@deepseek-ai/dsh-base 等），peerDependencies 已声明 @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery 与 @deepseek-ai/dsh-client-ui-settings-plugins。旧版宿主（installSettingsSection 时代）不兼容：DSH 0.1.2-rc.1 之前（无上述官方 API / 尚用 installSettingsSection 注入设置卡片的版本）上安装会得到 pnpm peer 缺失警告，插件可能无法加载，请升级 DSH 到 ≥ 0.1.2-rc.1 或改用方式一（Skill 文件系统）。

方式三：本地源码链接（用于插件开发）

如果你在本地开发 gongwen-skill 插件，可以用 link 方式让 DSH 直接加载仓库源码： bash

把本地仓库以 link 方式挂到 DSH Web Profile

dsh plugin --profile web add -w "link:/path/to/gongwen-skill"

同样：检查 ~/.dsh/profiles/web/package.json

- dependencies 出现 "gongwen-skill": "link:/path/to/gongwen-skill"

- dsh.profile.bundles 包含 "gongwen-skill"

架构边界（O12 · DSH 插件）

规则：CLI（python -m gongwen）是唯一业务逻辑入口，DSH 插件（dsh/）只做 UI 代理与结果展示。

- 插件通过 spawn("python", ["-m", "gongwen", ...]) 子进程转发命令，不直接 import 引擎、不操作 docx，避免双入口行为分裂
- dsh/index.js 的 POSITIONAL_ARGS 声明各命令的位置参数（如 draft: ["input"]）；新增/调整 CLI 命令位置参数时必须同步更新该表，否则插件转发会构造出 --input 而 CLI 只接受位置参数
- 插件保持薄层：业务逻辑全在 CLI / engine，改动引擎不影响插件；改动 CLI 参数形态时需同步检查 dsh/index.js 转发（doctor 自检覆盖 DSH 文件存在性）
- 模型工具注册：插件通过官方 ctx.tools.register(defineTool({...})) 注册名为 gongwen 的模型工具，工具 schema 自动流入 DSH 系统提示词组装；defineTool 校验模型生成的参数后调用 runCli() 透传 Python CLI（详见上方「DSH 插件配置化」）
- 客户端配置菜单：dsh/client.js 注册进官方 settings.section list slot（id=gongwen-styles，order=20，label=文档样式配置），在「系统设置」侧边栏与通用设置/模型/插件平级；页面经 ctx.settingsScope 读写官方 settings 文档，UI 样式使用 --dsw-alias-* 语义 token（官方 Client UI & Slots 规范）

🚀 启动 DSH Web 服务 bash

让 gongwen-skill 桥接可用：先在仓库根安装 Python 依赖

cd /path/to/gongwen-skill
pip install -r requirements.txt # 或 pip install gongwen-skill

启 DSH

dsh --profile web

或：dsh web

浏览器访问 http://127.0.0.1:3080/，在新建会话时即可让 DSH Agent 自动加载 gongwen-skill 调用 Web UI 工具流。

🤖 Agent 预设「公文全流程处理专家」

插件装载后会自动把 presets/（preset.yml + agent.cordis.yml）安装到 ~/.dsh/.agent-presets/gongwen-skill/，DSH Web 新建会话 → 预设选择中会出现 「公文全流程处理专家」，选中即可开箱即用：

- 内置 Persona：公文专家人设（25 类公文能力、A/B/C/D/E 路径判定：格式优化 / 内容优化 / 生成 / 一键修复 / 样式学习、硬性规则——bold-first 先于 optimize、交付前 check 复核 P0=0 等）
- 完整工具链：文件系统（fs/fs-search）、shell（Windows 用 pwsh / 其他用 bash，跑 python -m gongwen）、后台任务（jobs）、技能（skills + tool-skill）、目标（goal）、计划模式（plan-mode）、压缩（compaction）、委派（subagent/workflow/ralph）、问答（ask-user）、任务清单（todo）、联网（web）
- 业务能力由插件 host 平面注册的 gongwen 模型工具 + 运行时技能 gongwen-skill 提供，无需额外配置

自定义预设：如需修改该预设，可在 DSH 预设列表把它复制为新预设后再编辑（插件升级会覆盖原预设文件）。预设 id 为 gongwen-skill，源码在仓库 presets/。

DSH 兼容性自查

| 检查项 | 状态 |
| DSH 宿主版本要求（≥ 0.1.2-rc.1；旧版宿主「installSettingsSection 时代」不兼容） | ✅ 需 DSH ≥ 0.1.2-rc.1 |
| 技能体系：SKILL.md YAML frontmatter（name + description + whenToUse） | ✅ |
| 技能名称规范（gongwen-skill，长度 ≤ 30 字符） | ✅ |
| 目录技能格式（.dsh/skills/gongwen-skill/SKILL.md） | ✅ |
| 单文件技能格式（.dsh/skills/gongwen-skill.md） | ✅ 双格式兼容 |
| Cordis 插件包：package.json + dsh/ + cordis.patch.yml | ✅ |
| 插件 bundle 声明：dsh.bundle.patch（官方「第三方插件」规范） | ✅ |
| 客户端半侧声明：dsh.client + exports["./client"]（官方 Client 模块系统） | ✅ |
| 模型工具注册：ctx.tools.register(defineTool(...))（官方 Registering Tools 规范） | ✅ gongwen 工具 |
| 配置菜单：官方 settings.section 平级菜单（「文档样式配置」）+ ctx.settingsScope（官方 Client UI & Slots） | ✅ |
| 系统提示注入：ctx.systemPrompt.section（官方 Host Services & Events） | ✅ |
| 运行时技能：ctx.skills.register（官方 Skills 注册表） | ✅ |
| CLI 独立可执行（python -m gongwen <命令>） | ✅ |
| PyPI 上架（pip install gongwen-skill） | ✅ |
| 零外部运行时依赖（仅 python-docx/pydantic/pyyaml） | ✅ |
| DSH 配置化排版参数（页边距/行距/字体/默认公文类型，39 字段） | ✅ v2.6.0+ |

DSH 插件配置化（v2.6.0+）

DSH 插件支持通过配置文件管理排版参数，Agent 调用时自动注入，纯 CLI 用户不受影响。

两种配置入口（同一数据，双向同步）：

1. DSH Web 设置面板（推荐）：系统设置 → 文档样式配置（设置侧边栏平级菜单，与通用设置/模型/插件并列），页面含默认公文类型下拉（25 种）与完整排版参数（页边距/字体/行距等 39 字段）；保存后写入 DSH 官方 settings 文档，并由插件 Host 的 scope.watch 自动同步到 ~/.gongwen-skill/dsh-config.json。样式模板的学习与管理走 CLI（style-learn / style-list / template，见「样式学习」章节），不占用设置面板，保持插件薄层
2. CLI / 配置文件：直接编辑 ~/.gongwen-skill/dsh-config.json，或通过插件 config 命令管理

兼容性：插件首次在带 settings provider 的 DSH 部署中加载时，会把已存在的 ~/.gongwen-skill/dsh-config.json 一次性迁移进官方 settings 命名空间（仅当设置面板尚无用户覆盖时），之后以设置面板 / settings 文档为权威源，双向同步。

配置文件：~/.gongwen-skill/dsh-config.json

初始化配置（从默认模板创建）： bash

通过 DSH 插件调用

node -e "import('./dsh/index.js').then(async m => { console.log(await m.call({}, {command: 'config', action: 'init'})) })"

或直接复制默认模板

cp etc/dsh-config-defaults.json ~/.gongwen-skill/dsh-config.json

配置项说明（完整 39 字段，与设置面板一一对应）：

| 配置路径 | 说明 | 默认值 |
| default_doc_type | 默认公文类型 | notice |
| page_setup.margins.top/bottom | 上下页边距 | 2.8cm |
| page_setup.margins.left/right | 左右页边距 | 2.7cm |
| page_setup.header_distance | 页眉距边界 | 1.5cm |
| page_setup.footer_distance | 页脚距边界 | 2.3cm |
| body.font / body.font_fallback | 正文字体 / 回退字体 | 仿宋_GB2312 / FangSong |
| body.size | 正文字号 | 16pt |
| body.line_spacing | 正文行距 | 33pt |
| body.first_line_indent | 首行缩进 | 2em |
| body.align | 正文对齐 | justify |
| doc_title.font / doc_title.font_fallback | 大标题字体 / 回退字体 | 方正小标宋简体 / SimSun |
| doc_title.size / doc_title.align / doc_title.bold | 大标题字号 / 对齐 / 加粗 | 22pt / center / false |
| doc_title.line_spacing | 大标题行距 | 33pt |
| heading_1.font / heading_1.font_fallback | 一级标题字体 / 回退字体 | 黑体 / SimHei |
| heading_1.size / heading_1.line_spacing / heading_1.first_line_indent | 一级标题字号 / 行距 / 首行缩进 | 16pt / 33pt / 2em |
| heading_2.font / heading_2.font_fallback | 二级标题字体 / 回退字体 | 楷体_GB2312 / KaiTi |
| heading_2.size / heading_2.line_spacing / heading_2.first_line_indent | 二级标题字号 / 行距 / 首行缩进 | 16pt / 33pt / 2em |
| heading_3.font / heading_3.font_fallback | 三级标题字体 / 回退字体 | 仿宋_GB2312 / FangSong |
| heading_3.size / heading_3.bold / heading_3.line_spacing / heading_3.first_line_indent | 三级标题字号 / 加粗 / 行距 / 首行缩进 | 16pt / true / 33pt / 2em |
| signature.font / signature.font_fallback | 署名字体 / 回退字体 | 仿宋_GB2312 / FangSong |
| signature.size / signature.align | 署名字号 / 对齐 | 18pt / center |

修改配置（DSH 插件调用）： javascript // 设置单个配置项 await call({}, {command: 'config', action: 'set', key: 'page_setup.margins.top', value: '3.0cm'})

// 读取配置项 await call({}, {command: 'config', action: 'get', key: 'body.line_spacing'})

// 查看完整配置 await call({}, {command: 'config', action: 'show'})

// 重置为默认值 await call({}, {command: 'config', action: 'reset'})

纯 CLI 使用 --config-overrides： bash

临时覆盖行距为 28 磅

python -m gongwen template notice -o 通知.docx \
--config-overrides '{"body":{"line_spacing":"28pt"}}'

临时覆盖页边距

python -m gongwen optimize input.docx -o output.docx --apply \
--config-overrides '{"page_setup":{"margins":{"top":"3.0cm"}}}'

设计说明：

- 分层架构：Python CLI（纯工具层）只接受 --config-overrides 通用参数；DSH 插件（配置管理者）读写配置文件并自动注入
- 优先级：official YAML < custom YAML < user YAML < DSH config overrides < 命令行 --config-overrides
- 热更新：每次调用读取配置文件，修改后立即生效，无需重启
- 纯 CLI 不受影响：不使用 DSH 插件时不会读取 dsh-config.json

适用场景对照

| 你的场景 | 推荐方式 |
| 只想在终端用 gongwen-skill 命令 | 方式零 |
| 想让 DSH Agent 调用本技能，无需 Web UI | 方式一（Skill 文件系统） |
| 想让 DSH Web UI 工具面板直接调用 | 方式二（npm 插件 bundle） |
| 二开插件本身，本地反复编辑 | 方式三（link 模式） |
| 通用 Agent 一行安装（Claude Code/Codex/Cursor 等） | npx skills add linhut/gongwen-skill |

🤖 通过 Agent 调用

本 Skill 可直接被 AI Agent（如 WorkBuddy、CloudCode、Claude Code、AtomCode 等）加载并调用，无需手动操作。

安装方式

方式零：npx skills add 一行安装（最简）bash

任意支持 Agent Skills 的 harness（Claude Code / Codex / Cursor 等）均可：

skills CLI 会自动把本技能路由到对应 harness 的 skills 目录

npx skills add linhut/gongwen-skill

方式一：克隆到 Skills 目录（推荐）bash

WorkBuddy / CloudCode

git clone https://github.com/linhut/gongwen-skill.git ~/.workbuddy/skills/gongwen-skill/

AtomCode

git clone https://github.com/linhut/gongwen-skill.git ~/.atomcode/skills/gongwen-skill/

Claude Code

git clone https://github.com/linhut/gongwen-skill.git ~/.claude/skills/gongwen-skill/

其他 Agent — 将仓库克隆到对应的 skills 目录即可

方式二：任何工作目录下直接使用bash
git clone https://github.com/linhut/gongwen-skill.git
cd gongwen-skill
pip install -r requirements.txt

之后 Agent 可直接调用 python -m gongwen <命令>

对话中使用示例

| 用户说 | Agent 行为 | 路径 |
| "帮我检查这份通知的格式" | 自动执行 check 并展示问题清单 | A |
| "帮我排版这份红头文件" | 自动执行 optimize --apply 修复格式 | A |
| "润色一下这份报告的措辞" | 生成 changes.json，执行 optimize-content（tracked 修订+批注） | B |
| "帮我写一份关于XX的通知" | 追问细节后走草稿→md2docx→optimize→check | C |
| "核验一下这份新闻稿里的人名职务" | 执行 optimize-content --output-tasks → 智能体核验 → --input-tasks 回填 | B+协作 |
| "给这份会议通知生成桌签" | 询问名单后执行 table-signs | 独立 |
| "看看这份文档有没有问题" | 执行 audit 检查删除线/加粗/AI声明 | 独立 |

智能体调用示例（对话式）

用户：帮我优化这份会议通知的第二章节措辞

智能体：📋 合规自检报告 Skill 版本: v2.12.0（版本自检已确认最新）路径判定: B（内容优化）依据: 用户指定了已有文档，且要求"优化措辞" 命令调用: 1. python -m gongwen optimize-content 会议通知.docx --changes changes.json --apply --paragraphs "5-8" 是否绕过: 否交付物: 会议通知+庄重严谨+2026-08-01+v1.docx（Word 原生修订+批注版）质量验证: check 通过

🔧 LLM 集成（可选）

Skill 定位为工具层，默认不依赖 LLM（确定性工作全自包含）。以下可选能力需配置环境变量（未配置自动降级，不影响主流程）：

| 环境变量 | 能力 |
| GONGWEN_LLM_API / _API_KEY / _MODEL | LLM 实体提取、自动生成优化建议、风格增强（skill 内置调用） |
| GONGWEN_OPTIMIZE_LLM_API（优先于 LLM_API） | optimize-content 专用配置 |
| GONGWEN_WEB_VERIFY=1 | 事实核验互联网交叉核验（百度→必应多引擎） |

推荐模式：智能体环境中通过 --output-tasks / --input-tasks 协作，用智能体自身 LLM+搜索能力处理，无需配置上述环境变量。

📦 依赖

仅 3 个纯 Python 包：python-docx、pydantic、pyyaml。无数据库、无 Web 框架、无桌面端。

💬 社区交流

欢迎加入社区，参与讨论、交流使用问题、插件开发和项目进展：

| 平台 | 说明 |
| 💬 Discord | 加入 Discord 服务器 — 实时交流、问题讨论、版本更新通知 |
| 💚 QQ 群 | 扫码加入 QQ 群，与中文用户交流使用经验 |

🌐 GitHub 不可达排查（安全 DNS / DoH）

国内网络访问 GitHub 常遇「无法访问 / 超时」问题，常见原因之一是 DNS 污染——系统 DNS 返回的不是真实 IP，而是保留/Fake-IP 段（如 198.18.0.0/15、0.0.0.0），连接自然失败或超时。

快速诊断：运行 python -m gongwen doctor（含网络/DNS 检查项），或 python -m gongwen check-update（GitHub 渠道不可达时自动诊断）。检测到疑似污染时，会输出系统解析 vs 安全 DNS 真实 IP 对比，以及可直接粘贴的 hosts 条目建议。

原理：安全 DNS（DoH，DNS over HTTPS）通过加密 HTTP 查询 DNS，避免中间设备篡改解析结果，可拿到域名的真实 IP。本工具内置阿里（dns.alidns.com）、腾讯（doh.pub / 1.12.12.12）等国内公共 DoH 端点，多端点自动降级；可通过环境变量 GONGWEN_DOH 覆盖为自定义端点（如自建的 DoH 服务）。

自动兜底（v2.10.0）：font install 下载字体、check-update 查 PyPI 时若常规请求失败（疑似 DNS 污染），自动用 DoH 真实 IP + TLS SNI 直连重试——TLS 证书仍按真实域名校验，安全不降级，用户零操作。

处置建议（按推荐度）：
1. 若使用了代理工具（Clash/V2Ray 等）且系统解析命中 198.18.x Fake-IP，优先检查其 DNS 模式的 fake-ip-filter 是否漏掉 GitHub 域名（比改 hosts 更治本）
2. 将诊断输出的 hosts 条目写入 C:\Windows\System32\drivers\etc\hosts（需管理员权限），git / 浏览器即可直连真实 IP
3. 或使用国内镜像仓库克隆/更新（见下方「镜像仓库」）

诊断 + 自动兜底：本工具不写入 hosts、不修改系统配置；但 font install 下载字体、check-update 查询 PyPI 遇到 DNS 污染导致的失败时，会自动用安全 DNS（DoH）真实 IP + TLS SNI 直连重试（零操作，证书校验不降级）。DoH 查询经第三方公共 DNS 服务，仅在诊断/兜底失败时发起少量查询，隐私敏感者可设置 GONGWEN_DOH 指向自有端点。

📄 许可证与出处

MIT License · (c) 2026 Jose AI · https://www.linhut.cn

本 Skill 源自开源项目 AI 公文智能优化助手。格式引擎与规则 YAML 版权归原作者所有，依 MIT 许可证发行。

镜像仓库

- GitHub：https://github.com/linhut/gongwen-skill
- GitCode：https://gitcode.com/linhut/gongwen-skill
- AtomGit：https://atomgit.com/linhut/gongwen-skill