Skip to content
Back to search

gongwen-skill

公文全流程处理工具——基于 GB/T 9704《党政机关公文格式》 国家标准,面向公文写作、企事业单位材料编制场景,支持 格式检查与修复、内容优化(Word 原生修订+批注/差异对比版)、模板生成、Markdown 转公文、版头版记页码注入、事实核验、风格增强 等完整能力。原生支持 DeepSeek Harness (DSH) 技能系统,打包为可被 AI Agent 直接调用的 Skill,完全自包含,克隆即用。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/linhut--gongwen-skill/badge.svg)](/listings/linhut--gongwen-skill)

HTML

<a href="/listings/linhut--gongwen-skill"><img src="/api/listings/linhut--gongwen-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 27 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "gongwen-skill-marketplace",
  3. "description": "公文全流程处理专家(gongwen-skill)Claude Code 插件市场",
  4. "owner": {
  5. "name": "Jose AI"
  6. },
  7. "plugins": [
  8. {
  9. "name": "gongwen-skill",
  10. "displayName": "公文全流程处理专家",
  11. "source": "./",
  12. "version": "2.12.0",
  13. "description": "公文全流程处理专家 —— 面向中文公文(.docx)的 GB/T 9704 全流程工具链:格式检查、自动修复、内容优化(Word 原生修订+批注 / 行内差异对比)、模板生成、样式学习、Markdown 转公文、版头版记页码注入,覆盖 25 类法定公文。",
  14. "category": "productivity",
  15. "tags": [
  16. "chinese",
  17. "document",
  18. "government",
  19. "official-document",
  20. "GB/T 9704",
  21. "docx",
  22. "skill",
  23. "公文"
  24. ]
  25. }
  26. ]
  27. }
README.md · README · 736 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!--
  2. (c) 2026 Jose AI (https://www.linhut.cn)
  3. https://github.com/linhut/gongwen-skill
  4. Licensed under the MIT License. See the LICENSE file for details.
  5. -->
  6. # 公文全流程处理专家
  7. <p align="center">
  8. <img src="./logo/2026-08-19_11-17-43.png" alt="公文全流程处理专家" width="760">
  9. </p>
  10. > 中文公文全流程处理专家——基于 **GB/T 9704《党政机关公文格式》** 国家标准,支持 **格式检查与修复、内容优化(Word 原生修订+批注/差异对比版)、模板生成、Markdown 转公文、版头版记页码注入、事实核验、风格增强** 等完整能力。原生支持 **DeepSeek Harness (DSH)** 技能系统,打包为可被 AI Agent 直接调用的 Skill,完全自包含,克隆即用。
  11. [![CI](https://img.shields.io/badge/CI-Passing-brightgreen)](https://github.com/linhut/gongwen-skill/actions)
  12. [![PyPI](https://img.shields.io/pypi/v/gongwen-skill)](https://pypi.org/project/gongwen-skill/)
  13. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
  14. ![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)
  15. ![GB/T 9704](https://img.shields.io/badge/standard-GB%2FT%209704-red.svg)
  16. ![DSH](https://img.shields.io/badge/DSH-Compatible-brightgreen)
  17. ![Downloads](https://img.shields.io/pypi/dm/gongwen-skill)
  18. 本 Skill 源自开源桌面项目 [AI 公文智能优化助手](https://github.com/linhut/document-ai-assistant),将其核心格式引擎抽取、剥离桌面端/数据库依赖后独立发行,支持公文的**模板建立、解析、规则检查、自动修复、内容优化、Markdown 转公文**全流程能力。同时原生集成 **DeepSeek Harness (DSH)** 技能系统,支持 DSH Agent 自动发现与加载。
  19. ---
  20. ## ✨ 能力一览
  21. | 能力 | 命令 | 说明 |
  22. |------|------|------|
  23. | 📋 列类型 | `list-types` | 列出 25 种支持的公文类型(新增主持词 host_speech;含新闻稿/讲话稿) |
  24. | 🏗️ 模板生成 | `template` | 按类型生成 GB/T 9704 标准空白模板 |
  25. | 🔍 解析 | `parse` | `.docx` → 结构化 DocumentModel(含文本框/修订摘要) |
  26. | ✅ 格式检查 | `check` | 按国标检查,分级 P0/P1/P2(只读) |
  27. | 🔧 格式修复 | `optimize` | 自动修复字体/字号/行距/页边距,输出合规文档;`--verify` 单命令闭环自动复查、P0 存在时退出码非 0;`--json` 结构化输出 |
  28. | ✍️ **内容优化** | **`optimize-content`** | 内容润色:默认 **Word 原生修订+批注**(审阅面板逐条接受/拒绝),可选行内差异对比版;`--precheck` 预检 changes 与原文一致性、`--preset quick/full/review` 参数收敛 |
  29. | 📝 草稿转公文 | `md2docx` | Markdown 文本直接转为格式化 `.docx`(支持 Front Matter) |
  30. | 🚀 一站式生成 | `draft` | Markdown 草稿 → 国标成品 + 自动验证(路径 C 四步合一) |
  31. | 📄 模型生成 | `generate` | 从 JSON 模型生成 `.docx` |
  32. | 🔴 版头 | `header` | 注入发文机关标志 + 发文字号 + 签发人 + 红色反线 |
  33. | 📑 版记 | `footer` | 注入抄送机关 + 印发机关 + 印发日期 + 分隔线 |
  34. | 🔢 页码 | `pagenum` | 注入 Word PAGE 域动态页码(宋体 4 号,默认单右双左适配双面打印) |
  35. | 🖊️ 首句加粗 | `bold-first` | 正文段落首句自动加粗(公文规范) |
  36. | 🧰 一键修复 | `fix-common` | 路径 D 一键修复常见格式:段落类型修正 + 编号拆分 + 首句加粗 + 加粗范围修复 |
  37. | 📋 桌签生成 | `table-signs` | 批量生成 A5 横版会议桌签 |
  38. | 🔍 审稿生成 | `review` | 按五角色审稿机制生成审稿意见 |
  39. | 🧩 完整审校 | `full-review` | 修订+批注联合命令(句子级差异修订 + 分类批注) |
  40. | 🎨 样式学习 | `style-learn` / `style-list` | 上传标准文档学习 Run/段落/页面三级样式(字体/字号/字间距/行距/缩进/页边距),生成命名模板持久化,后续用 `optimize -t 模板名` 套用 |
  41. | 🔄 版本自检 | `check-update` | 版本自检(PyPI pip 包权威判定 + GitHub 备用,GitCode/AtomGit 作国内镜像提示;GitHub 不可达时自动做 DNS 污染诊断 + hosts 建议) |
  42. | 🩺 自我诊断 | `doctor` / `repair` | 全面诊断 23 项(Python/依赖/版本一致性/字体/DSH 文件/DSH 技能 frontmatter/代码风格/网络 DNS),自动修复常见问题;`--offline` 跳过网络检查 |
  43. | 🕵️ 文档审计 | `audit` | 检查删除线/加粗/AI 声明等痕迹 |
  44. | 🤝 会话交接 | `handoff` | 跨会话上下文传递(`--list` / `--latest` / Agent 长任务收尾必写) |
  45. | ⚙️ 规则管理 | `rule-export/import/list` | YAML 规则三层定制(官方/单位/用户) |
  46. | 🧭 向导式交互 | `wizard` | 交互式路径引导(A/B/C/D/E)+ 一键执行;Agent 用 `--answers` 非交互 / `--dry-run` 只打印命令 |
  47. ## 使用示例
  48. > 在 AI 对话中调用 gongwen-skill,输入自然语言指令,自动生成符合 GB/T 9704 国标格式的正式公文。
  49. ### 🤖 调用环境的适配指引(AI Agent 必读)
  50. 本工具针对不同能力层级的 AI 调用环境,提供不同的使用方式。**AI 读取本文件后,请先判断自身环境属于哪一类,再按对应指引执行:**
  51. | 环境类型 | 典型平台 | 能力 | 使用方式 |
  52. |:---------|:---------|:-----|:---------|
  53. | **① 可执行代码的 Agent** | WorkBuddy、CloudCode、Claude Code、AtomCode、DeepSeek Harness | 可运行命令、读写本地文件 | 直接执行 `python -m gongwen <命令>`,见下方「快速开始」与「通过 Agent 调用」 |
  54. | **② 纯对话 LLM(无代码执行能力)** | 豆包、Kimi、ChatGPT 网页版等 | 只能阅读文本、给出建议,**不能运行命令或读写文件** | 引导用户手动执行,见下方「纯对话 LLM 使用指引」 |
  55. #### 纯对话 LLM 使用指引(环境 ②)
  56. > **如果你是无法执行代码的纯对话 AI**(如豆包、Kimi、ChatGPT 网页版等),请按以下方式协助用户:
  57. 1. **告知工具性质**:向用户说明「这是一个本地运行的 Python 命令行工具,需要在你自己的电脑上安装后使用」,并说明它能做什么(格式检查、自动修复、内容优化、模板生成等 29 项命令能力)。
  58. 2. **引导安装**:请用户在自己的电脑上执行以下步骤:
  59. ```bash
  60. # 步骤 1:克隆仓库
  61. git clone https://github.com/linhut/gongwen-skill.git
  62. cd gongwen-skill
  63. # 步骤 2:安装依赖(需要 Python 3.10+)
  64. pip install -r requirements.txt
  65. # 或直接安装 PyPI 包:
  66. # pip install gongwen-skill
  67. ```
  68. 3. **按需给出具体命令**:根据用户的实际需求,给出对应的命令让用户自行执行:
  69. | 用户需求 | 建议用户执行 |
  70. |:---------|:-------------|
  71. | 检查公文格式 | `python -m gongwen check 公文.docx -t notice --json` |
  72. | 自动修复格式 | `python -m gongwen optimize 公文.docx -o 成品.docx -t notice --apply` |
  73. | 生成标准模板 | `python -m gongwen template notice -o 通知模板.docx` |
  74. | Markdown 转公文 | `python -m gongwen md2docx 草稿.md -o 正式公文.docx -t report` |
  75. | 内容润色(修订+批注) | `python -m gongwen optimize-content 原文.docx --changes 修订内容.json --apply --mode tracked` |
  76. | 注入版头/版记/页码 | `python -m gongwen header/footer/pagenum 公文.docx ...` |
  77. | 从标准文档学样式做模板 | `python -m gongwen style-learn 标准公文.docx -n 模板名`,之后用 `optimize -t 模板名` 套用 |
  78. | 安装标准字体 | `python -m gongwen font install` |
  79. 4. **解释输出**:用户执行后,把命令输出结果(问题清单、修复报告、生成文件等)发给你时,你能继续帮助解读、判断下一步操作。
  80. 5. **注意事项**:你**不能**代替用户执行任何命令,也**不能**读取用户本地的文件内容——所有文件操作都必须由用户在你的指引下完成。
  81. #### 文字性资源库(纯对话 LLM 可读的知识源)
  82. 项目内置以下文字性资源,纯对话 AI 可以直接读取,用作**公文写作指导的知识库**:
  83. | 资源 | 位置 | 内容 |
  84. |:-----|:-----|:------|
  85. | **公文语言风格提示词库** | `prompts/style-prompts.md` | 6 套风格(庄重严谨/平实简洁/宏观概括/请示商洽/法规条文/讲话稿),每套含用词规范、句式和语气指导 |
  86. | **使用指引与决策速查** | `prompts/usage-prompts.md` | 最小可用指引、决策速查、每种公文类型的用法模板、常见问题解答 |
  87. | **公文类型规则库** | `rules/official/*.yaml`(25 个文件) | 每种公文类型的格式规范 + 内容层定义(如"请示应以'妥否,请批示'结尾""通知应以'特此通知'结尾") |
  88. | **通用格式标准** | `rules/official/_common.yaml` | GB/T 9704 国标全文参数:字体/字号/行距/页边距等 |
  89. | **技能完整指令** | `SKILL.md` | 路径路由、执行标准、质量评审、禁令清单、审稿机制 |
  90. **使用方式**:纯对话 AI 在回答用户关于公文写作的问题时,可直接引用上述资源中的内容,例如:
  91. - 用户问"通知怎么写" → 引用 `rules/official/notice.yaml` 的结语规范和 `style-prompts.md` 的庄重严谨风格
  92. - 用户问"请示和报告的区别" → 引用 `request.yaml` 和 `report.yaml` 的规则说明
  93. - 用户问"公文用什么字体" → 引用 `_common.yaml` 中的 GB/T 9704 标准
  94. - 用户需要润色文字 → 引用 `style-prompts.md` 中对应的风格提示词
  95. > 这些资源均以纯文本格式存储,纯对话 AI 可直接读取解读,无需执行任何代码即可提供专业的公文写作指导。
  96. ## 🚀 快速开始
  97. ```bash
  98. git clone https://github.com/linhut/gongwen-skill.git
  99. cd gongwen-skill
  100. pip install -r requirements.txt
  101. # 生成一份标准通知模板
  102. python -m gongwen template notice -o 通知模板.docx
  103. # 检查公文格式(只读)
  104. python -m gongwen check 公文.docx -t notice --json
  105. # 自动修复格式(--apply 确认执行,默认预览);--verify 生成后自动复查,P0 存在时退出码非 0
  106. python -m gongwen optimize 公文.docx -o 成品.docx -t notice --apply --verify
  107. # 一步到位:检查 + 修复 + 版头/版记/页码全注入(--layout 指向 JSON 配置)
  108. python -m gongwen optimize 公文.docx -o 成品.docx --layout 版式.json
  109. # Markdown 草稿 → 正式公文(支持管道输入和 Front Matter 元数据)
  110. python -m gongwen md2docx 草稿.md -o 正式公文.docx -t report --signer "XX单位" --date "2026年8月1日"
  111. # 一步到位:Markdown 草稿 → 国标成品 + 自动验证(路径 C 四步合一)
  112. python -m gongwen draft 草稿.md -o 正式公文.docx -t report --signer "XX单位" --date "2026年8月1日"
  113. # 内容优化(默认 tracked 模式:Word 原生修订+批注,审阅面板逐条接受/拒绝)
  114. python -m gongwen optimize-content 原文.docx --changes 修订内容.json --apply --mode tracked -t news
  115. # 预检 changes 与原文一致性(不生成文档,输出不匹配清单+相似度诊断;不匹配时退出码 1)
  116. python -m gongwen optimize-content 原文.docx --changes 修订内容.json --precheck
  117. # 预设组合:quick 精简快速 / full 完整默认 / review 完整审稿(显式参数优先)
  118. python -m gongwen optimize-content 原文.docx --changes 修订内容.json --apply --preset full
  119. # 注入版头(发文机关标志 + 发文字号 + 签发人 + 红色反线)
  120. python -m gongwen header 公文.docx -o 红头公文.docx --org-name "XX单位" --doc-number "〔2026〕1号"
  121. # 注入版记(抄送 + 印发机关 + 印发日期)
  122. python -m gongwen footer 红头公文.docx --cc "各单位" --printer "XX办公室" --print-date "2026年8月1日"
  123. # 注入页码(Word PAGE 域动态页码)
  124. python -m gongwen pagenum 红头公文.docx --alignment right
  125. # 版本自检(PyPI pip 包权威判定 + GitHub 备用渠道)
  126. python -m gongwen check-update
  127. # 安装公文标准字体(方正小标宋简体/仿宋_GB2312/楷体_GB2312)
  128. python -m gongwen font install # 安装字体到系统
  129. python -m gongwen font check # 检查字体安装状态
  130. python -m gongwen font list # 列出字体清单
  131. # 从标准文档学习排版样式,生成自定义模板(后续用 optimize -t 模板名 套用)
  132. python -m gongwen style-learn 标准公文.docx -n 模板名
  133. python -m gongwen style-list # 列出已学习的模板
  134. ```
  135. ### 🖥️ Windows 控制台编码(GBK 乱码排查)
  136. 工具内部已统一按 UTF-8 输出(`gongwen/_bootstrap.py` 强制 stdout/stderr/stdin 重配置为 UTF-8,
  137. 保证管道/Agent 调用无编码问题)。若在原生 `cmd`(默认 GBK 代码页 936)看到中文乱码,任选其一:
  138. - **推荐**:改用 Windows Terminal / VS Code 终端(默认 UTF-8,无乱码)
  139. - 在 cmd 中先执行 `chcp 65001` 切换 UTF-8 代码页,再运行命令
  140. - 或设置环境变量 `PYTHONIOENCODING=utf-8`(与工具内部行为一致)
  141. > 说明:GBK 乱码仅影响原生 cmd 的**交互显示**,不影响文件内容与 `--json` 的机器可解析性。
  142. ### 🔤 字体管理
  143. 公文标准字体是 GB/T 9704 排版的关键。项目内置 3 个标准字体文件(`assets/fonts/`),支持自动安装:
  144. | 字体 | 用途 | TTF 大小 |
  145. |:-----|:-----|:---------|
  146. | 方正小标宋简体 | 公文大标题 | 3.7 MB |
  147. | 仿宋_GB2312 | 正文 | 3.8 MB |
  148. | 楷体_GB2312 | 二级标题 | 3.9 MB |
  149. **安装方式**:
  150. - **git clone 用户**:字体文件在 `assets/fonts/` 中,直接安装
  151. - **pip install 用户**:字体不打包到 PyPI(体积过大),`font install` 会自动从 [GitHub 仓库](https://github.com/linhut/document-ai-assistant/tree/master/TTF) 下载到 `~/.gongwen-skill/fonts/` 缓存后安装
  152. ```bash
  153. python -m gongwen font install # 一键安装 3 个标准字体
  154. python -m gongwen font check # 检查安装状态
  155. ```
  156. ## ✍️ 内容优化(路径 B)核心能力
  157. ### 三种输出模式(`--mode`)
  158. | 模式 | 说明 |
  159. |------|------|
  160. | `tracked`(默认) | **Word 原生修订标记(w:del/w:ins)+ 批注(comments.xml)**,审阅面板逐条接受/拒绝 |
  161. | `comment-mode` | 仅 Word 原生批注(可审阅→接受/拒绝) |
  162. | `inline` | 行内差异对比版(原文灰色删除线 + 优化后红色高亮 + 修改说明) |
  163. ### 8 色审阅角色方案
  164. 批注/修订按语义类别自动分配角色与颜色,Word 中可按审阅者筛选:
  165. | 角色 | 类型 | 颜色 | 色值 | 语义类别 |
  166. |------|------|------|------|---------|
  167. | 格式审校 | 批注 | 蓝 | `2E86C1` | 格式优化 |
  168. | 用语审校 | 批注 | 绿 | `27AE60` | 用语优化 |
  169. | 逻辑审校 | 批注 | 红 | `E74C3C` | 逻辑优化 |
  170. | 法规审校 | 批注 | 紫罗兰 | `9B59B6` | 法规合规 |
  171. | 综合审校 | 批注 | 橙 | `F39C12` | 内容优化 |
  172. | 事实核验 | 批注 | 青 | `00BCD4` | 事实核验 |
  173. | GongWen-Skill修订 | 修订 | 玫红 | `E91E63` | 内容/事实核验修订 |
  174. | 风格审校 | 批注+修订 | 深紫 | `6C3483` | 风格优化(自动应用) |
  175. ### 事实核验
  176. - **默认执行**(不依赖 `--background`):实体提取(人名/职务/机构全称)→ 互联网交叉核验 → 生成"存疑/已确认/未经核验"批注
  177. - **实体属性核验**:识别人名+职务配对(如"××单位党组成员、副主任XXX"),能发现职务写反等严重事实错误
  178. - **LLM+规则混合提取**:配置 `GONGWEN_LLM_API` 后 LLM 内容理解提取(主通道)+ 规则提取(兜底)
  179. - **背景资料增强**:`--background` 传入 docx/pdf/md/txt/URL 构建基准,已确认实体自动过滤
  180. ### Agent 协作机制(`--output-tasks` / `--input-tasks`)
  181. Skill 定位为**工具层**——确定性工作自己做,需 LLM/搜索判断的环节交由 Agent:
  182. ```bash
  183. # 1. Skill 输出待处理任务(待核验实体 + 风格增强请求),同时生成基础版文档
  184. python -m gongwen optimize-content 新闻稿.docx --changes changes.json \
  185. --output-tasks tasks.json --apply --mode tracked -t news
  186. # 2. Agent 用自身 LLM+搜索能力处理 tasks.json(核验人事信息、生成风格建议),输出 tasks_result.json
  187. # 3. Skill 读入回填结果,合并到 changes 后执行(去重/已确认过滤/独立修订作者)
  188. python -m gongwen optimize-content 新闻稿.docx --changes changes.json \
  189. --input-tasks tasks_result.json --apply --mode tracked -t news
  190. ```
  191. ### 风格增强(v2,数据驱动)
  192. - 输出 5 套上下文信号:**段落角色标注**(复用 structure 规则关键词)、**文档类型规则摘要**(structure 含 modes/focus_checks/title_patterns)、**结构/焦点检查结果**、**数据驱动风格评分**(completeness/compliance/change_density/style_deviation_hint)、**完整已有变更摘要**(不再截断)
  193. - 风格建议 **auto-accept 自动合入**已有变更(difflib 映射),不生成独立修订;批注标注【已自动应用】
  194. - 跨 20+ 文档类型自动适配(rules YAML 数据驱动,不硬编码)
  195. ### 结构/焦点自动检查
  196. - **结构完整性检查**(`structure_checker.py`):按 rules YAML 的 structure 定义检查必要段落/要素,多候选评分定位段落
  197. - **focus_checks 自动检查**(`focus_checker.py`):逻辑闭环(听取→指出→强调→要求)/时间一致性/事实表述客观克制/稿源编辑信息/简称定义规范
  198. - 检查结果自动生成按角色区分的批注
  199. ### 命令行参数速查
  200. ```
  201. --mode tracked|inline 输出模式(默认 tracked)
  202. --reviewers 3|5|6 审稿角色数(默认 6 完整版)
  203. --changes <json> 变更列表(paragraph_index/original_text/optimized_text/reason/category)
  204. --background <paths> 背景资料(事实核验基准)
  205. --auto-generate 无 changes.json 时基于内置规则自动生成优化建议(需 LLM)
  206. --output-tasks <json> 输出待 Agent 处理任务
  207. --input-tasks <json> 读入 Agent 回填结果
  208. --style <名称> 语言风格(--style 显式 > changes.style > doc_type 映射 > 默认庄重严谨)
  209. --no-style-enhance 禁用风格增强(默认开启)
  210. -t/--doc-type <类型> 显式指定公文类型(默认自动检测)
  211. --show-rules 输出文档类型内容层规则摘要
  212. --show-confirmed 已确认实体也生成批注
  213. ```
  214. ### 🧭 向导式交互(wizard)
  215. 交互式引导选择处理路径并一键执行,适合不熟悉命令行的用户;Agent 可走非交互模式:
  216. ```bash
  217. python -m gongwen wizard # 终端交互:菜单选 A/B/C/D/E → 逐项填参 → 预览确认 → 执行
  218. python -m gongwen wizard --answers 答案.json # Agent 非交互:跳过提问直接执行
  219. python -m gongwen wizard --answers 答案.json --dry-run # 只打印将执行的命令
  220. ```
  221. `--answers` 扁平 JSON(顶层带 `path`):
  222. ```json
  223. {"path": "A", "input": "原文.docx", "doc_type": "notice", "output": "成品.docx", "apply": true}
  224. ```
  225. 路径:A 格式优化(`optimize`)|B 内容优化(`optimize-content`)|C 生成模板(`template`)|D 一键格式修复(`fix-common`)|E 样式学习(`style-learn`)。A/B/D 默认先预览再 y/n 确认;不写 `apply` 时非交互模式仅预览不执行(安全默认)。
  226. ## 📐 GB/T 9704 标准格式
  227. | 元素 | 字体 | 字号 | 对齐 |
  228. |------|------|:----:|:----:|
  229. | **公文标题** | 方正小标宋简体 | 二号(22pt) | 居中 |
  230. | **一级标题**(一、二、三) | 黑体 | 三号(16pt) | 顶格 |
  231. | **二级标题**((一)(二)) | 楷体_GB2312 | 三号(16pt) | 首行缩进2字符 |
  232. | **三级标题**(1. 2.) | 仿宋_GB2312 **加粗** | 三号(16pt) | 首行缩进2字符 |
  233. | **正文** | 仿宋_GB2312 | 三号(16pt) | 首行缩进2字符 |
  234. | **西文/数字** | Times New Roman | 与中文字号一致 | — |
  235. | **页码** | 宋体(4号半角) | 四号(14pt) | 单页右/双页左(双面打印) |
  236. | **页边距** | — | — | 上2.8/下2.8/左2.7/右2.7 cm(工具实际采用值,见 `_common.yaml`) |
  237. ### 讲话稿(speech 朗读件)
  238. 页边距为国标默认(上3.7/下3.5/左2.8/右2.6 cm);标题方正小标宋简体 24pt 居中、行距 35pt;一级标题黑体 18pt、二级标题楷体_GB2312 18pt;署名/日期楷体_GB2312 18pt 居中、行距 35pt;正文仿宋_GB2312 18pt 不加粗、行距 30pt exact、首行缩进 2 字符;跳过版头/版记/发文字号/密级检查。(样式以最终版定稿为准)
  239. ### 主持词(host_speech 朗读件)
  240. 页边距与普通公文一致(上2.8/下2.8/左2.7/右2.7 cm);标题方正小标宋简体 24pt 居中、行距 35pt;主持人信息/日期楷体_GB2312 18pt 居中、行距 30pt;正文仿宋_GB2312 18pt 不加粗、行距 30pt exact、首行缩进 2 字符,议程引导句("下面,进行第X项议程…")可局部加粗;跳过版头/版记/发文字号/密级检查。(样式以最终版定稿为准)
  241. ## 📚 支持的 25 种公文类型
  242. 通知 · 请示 · 报告 · 函 · 会议纪要 · 纪要 · 决定 · 通告 · 公告 · 命令 · 通报 · 议案 · 批复 · 指示 · 制度 · 公报 · 意见 · 总结 · 方案/计划 · 桌签 · 技术方案 · 决议 · **新闻稿/简报** · **讲话稿** · **主持词**
  243. > 每种类型对应 `rules/official/*.yaml`,含格式规则 + 内容层定义(structure/focus_checks/title 等),驱动 check/optimize/optimize-content 全链路。
  244. ## ⚙️ 规则化与二次定制
  245. 规则以 YAML 定义,三层优先级 **official < custom < user**:
  246. - 官方规则:仓库内 `rules/official/*.yaml`
  247. - 用户覆盖:`~/.gongwen-skill/user_rules/*.yaml`(同名字段覆盖官方)
  248. ```bash
  249. python -m gongwen rule-export notice -o notice_rules.yaml
  250. python -m gongwen rule-import my_company -f 公司规范.yaml
  251. python -m gongwen rule-list --source all
  252. ```
  253. ## ⚠️ 使用红线
  254. - **不伪造、冒用真实机关正式发文** — 生成物仅为草稿,正式发文须走审核流程
  255. - **人事信息准确性铁律** — 领导姓名/机构全称/职务等仅有"确定"或"`[XXX]` 占位"两种状态,严禁推理/猜测填造
  256. - **不编造政策依据、数据、结论** — 缺失信息用 `XXX` 占位
  257. - **涉密材料先脱敏再处理**
  258. - **字体版权** — 方正小标宋简体等字体可能受版权约束,缺少时 Word 会回退
  259. ## 🤖 作为 AI Agent Skill 使用
  260. 将本仓库放入 Agent 的 skills 目录,Agent 读取 `SKILL.md` 后自动调用命令。支持三条路径:
  261. - **路径 A**:格式修复(不改文字,只修排版)
  262. - **路径 B**:内容优化(润色文字,Word 原生修订+批注 / 差异对比版)
  263. - **路径 C**:生成公文(从零创建,四步流水线;`draft` 命令可一步到位)
  264. **平台适配**:`SKILL.md` 采用通用 frontmatter(`name/description/whenToUse/user-invocable`),兼容 **WorkBuddy、CloudCode、Claude Code、AtomCode、DeepSeek Harness** 等以 `SKILL.md` 为技能清单的平台;纯对话 LLM(无代码执行能力)请参见上方「纯对话 LLM 使用指引」。
  265. ### 🔄 版本追新(Agent 加载 skill 后必须执行)
  266. Agent 加载 skill 后**必须执行版本追新自检**,确保使用最新版本:
  267. 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 条目建议)
  268. 2. **本地 git tag 对比**(补充):对 skill 安装目录执行 `git -C "<skill安装目录>" describe --tags --abbrev=0`;若安装目录不在 git 管理下,应告知用户"无法执行版本对比,建议手动检查 GitHub 更新"
  269. 3. **落后则警告**:发现本地版本落后于最新版本时,**必须在执行前警告用户**并提示更新——`check-update` 会按安装形态自动给出精准更新命令(pip 包安装:`pip install --upgrade gongwen-skill`;git/skill 目录安装:`cd <gongwen-skill目录> && git pull && git fetch --tags`),不得静默使用旧版本
  270. > 严禁只用本地 `git describe` 判断版本——它只读本地可达 tag,未 fetch 时会误判本地即最新。
  271. ## 🚀 DeepSeek Harness (DSH) 集成
  272. 本 Skill 同时支持 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 的**两种集成方式**——文件系统 **Skill**(轻量、跟随项目)与 **Cordis 插件 bundle**(包入 npm 通道、让 Web UI Toolkit 可调用),按你的部署需求选择。
  273. DSH 采用 **Cordis 模块化微内核架构**:技能体系基于本地文件系统(无中心化技能市场),插件体系基于 npm 包 + `~/.dsh/profiles/<preset>/package.json` 中的 `dsh.profile.bundles` 声明挂载。
  274. ### 方式零:仅作为 Python CLI 使用(最轻量)
  275. ```bash
  276. git clone https://github.com/linhut/gongwen-skill.git
  277. cd gongwen-skill
  278. pip install -r requirements.txt # 或 pip install gongwen-skill(已上 PyPI)
  279. python -m gongwen --version # 检验:gongwen-skill v2.12.0
  280. ```
  281. ### 方式一:作为 DSH Skill 注册(基于本地文件系统)
  282. DSH Agent 启动时自动扫描下表目录中的技能(优先级从高到低):
  283. | 优先级 | 目录 | 说明 |
  284. |:------:|:-----|:------|
  285. | 100 | `{project}/.dsh/skills/` | 项目级 DSH 技能目录 |
  286. | 200 | `{project}/.agents/skills/` | 项目级 Agent 技能目录 |
  287. | 400 | `~/.dsh/skills/` | 用户级 DSH 技能目录 |
  288. | 500 | `~/.agents/skills/` | 用户级 Agent 技能目录 |
  289. **安装方式**(二选一):
  290. ```bash
  291. # A. 项目级:克隆到工程目录(跟随项目,推荐)
  292. git clone https://github.com/linhut/gongwen-skill.git ./third_party/gongwen-skill
  293. ln -s ./third_party/gongwen-skill/.dsh/skills/gongwen-skill ./.dsh/skills/gongwen-skill
  294. # B. 用户级:全局可用,所有 DSH 会话都能发现
  295. git clone https://github.com/linhut/gongwen-skill.git ~/skills/gongwen-skill
  296. mkdir -p ~/.dsh/skills/
  297. ln -s ~/skills/gongwen-skill/.dsh/skills/gongwen-skill ~/.dsh/skills/gongwen-skill
  298. ```
  299. > 两种方式都会让 DSH Agent 在启动时自动发现并加载本技能;本仓库自带 `.dsh/skills/gongwen-skill/` 双格式(目录技能 + 单文件技能)兼容。
  300. ### 方式二:作为 DSH Cordis 插件安装(注册到 Web Profile)
  301. 把本仓库当作 npm 包安装到 DSH Web Profile,让 DSH 的 Web UI 通过 `gongwen-skill` 调用桥接器执行 Python CLI。
  302. ```bash
  303. # 1️⃣ 用 DSH 官方 CLI 一键挂载(推荐:自动改 package.json + 重建 bundle)
  304. dsh plugin --profile web add -w gongwen-skill
  305. # -w = workspace,按 preset 自动写入 ~/.dsh/profiles/web/package.json
  306. ```
  307. ```bash
  308. # 2️⃣ 或在 Web Profile 目录下手动 npm/pnpm 安装
  309. cd ~/.dsh/profiles/web
  310. npm i gongwen-skill -w
  311. # 或:
  312. pnpm add -w gongwen-skill
  313. ```
  314. 安装后请确认 `~/.dsh/profiles/web/package.json` 中的 `dsh.profile.bundles` 数组已包含 `gongwen-skill`:
  315. ```jsonc
  316. {
  317. "name": "dsh-profile-web",
  318. "private": true,
  319. "dependencies": {
  320. "@deepseek-ai/dsh-base": "...",
  321. "@deepseek-ai/dsh-web-app": "...",
  322. "gongwen-skill": "^2.12.0"
  323. },
  324. "dsh": {
  325. "profile": {
  326. "bundles": [
  327. "@deepseek-ai/dsh-base",
  328. "@deepseek-ai/dsh-web-app",
  329. "gongwen-skill"
  330. ]
  331. }
  332. }
  333. }
  334. ```
  335. > **注意**:若 `add` 启动报错提示子包重复声明,请检查 `dsh.profile.bundles` 数组中**仅包含根包 `gongwen-skill`**,避免同时列入 `engine` 或 `gongwen` 等子目录。
  336. > **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 文件系统)。
  337. ### 方式三:本地源码链接(用于插件开发)
  338. 如果你在本地开发 gongwen-skill 插件,可以用 link 方式让 DSH 直接加载仓库源码:
  339. ```bash
  340. # 把本地仓库以 link 方式挂到 DSH Web Profile
  341. dsh plugin --profile web add -w "link:/path/to/gongwen-skill"
  342. # 同样:检查 ~/.dsh/profiles/web/package.json
  343. # - dependencies 出现 "gongwen-skill": "link:/path/to/gongwen-skill"
  344. # - dsh.profile.bundles 包含 "gongwen-skill"
  345. ```
  346. ### 架构边界(O12 · DSH 插件)
  347. > 规则:**CLI(`python -m gongwen`)是唯一业务逻辑入口**,DSH 插件(`dsh/`)只做 UI 代理与结果展示。
  348. - 插件通过 `spawn("python", ["-m", "gongwen", ...])` 子进程转发命令,**不直接 import 引擎、不操作 docx**,避免双入口行为分裂
  349. - `dsh/index.js` 的 `POSITIONAL_ARGS` 声明各命令的位置参数(如 `draft: ["input"]`);新增/调整 CLI 命令位置参数时**必须同步更新该表**,否则插件转发会构造出 `--input` 而 CLI 只接受位置参数
  350. - 插件保持薄层:业务逻辑全在 CLI / engine,改动引擎不影响插件;改动 CLI 参数形态时需同步检查 `dsh/index.js` 转发(doctor 自检覆盖 DSH 文件存在性)
  351. - **模型工具注册**:插件通过官方 `ctx.tools.register(defineTool({...}))` 注册名为 `gongwen` 的模型工具,工具 schema 自动流入 DSH 系统提示词组装;`defineTool` 校验模型生成的参数后调用 `runCli()` 透传 Python CLI(详见上方「DSH 插件配置化」)
  352. - **客户端配置菜单**:`dsh/client.js` 注册进官方 `settings.section` list slot(id=`gongwen-styles`,order=20,label=`文档样式配置`),在「系统设置」侧边栏与通用设置/模型/插件平级;页面经 `ctx.settingsScope` 读写官方 settings 文档,UI 样式使用 `--dsw-alias-*` 语义 token(官方 Client UI & Slots 规范)
  353. ### 🚀 启动 DSH Web 服务
  354. ```bash
  355. # 让 gongwen-skill 桥接可用:先在仓库根安装 Python 依赖
  356. cd /path/to/gongwen-skill
  357. pip install -r requirements.txt # 或 pip install gongwen-skill
  358. # 启 DSH
  359. dsh --profile web
  360. # 或:dsh web
  361. ```
  362. 浏览器访问 [http://127.0.0.1:3080/](http://127.0.0.1:3080/),在新建会话时即可让 DSH Agent 自动加载 gongwen-skill 调用 Web UI 工具流。
  363. ### 🤖 Agent 预设「公文全流程处理专家」
  364. 插件装载后会自动把 `presets/`(`preset.yml` + `agent.cordis.yml`)安装到 `~/.dsh/.agent-presets/gongwen-skill/`,DSH Web **新建会话 → 预设选择**中会出现 **「公文全流程处理专家」**,选中即可开箱即用:
  365. - **内置 Persona**:公文专家人设(25 类公文能力、A/B/C/D/E 路径判定:格式优化 / 内容优化 / 生成 / 一键修复 / 样式学习、硬性规则——`bold-first` 先于 `optimize`、交付前 `check` 复核 P0=0 等)
  366. - **完整工具链**:文件系统(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)
  367. - 业务能力由插件 host 平面注册的 `gongwen` 模型工具 + 运行时技能 `gongwen-skill` 提供,无需额外配置
  368. > **自定义预设**:如需修改该预设,可在 DSH 预设列表把它复制为新预设后再编辑(插件升级会覆盖原预设文件)。预设 id 为 `gongwen-skill`,源码在仓库 `presets/`。
  369. ### DSH 兼容性自查
  370. | 检查项 | 状态 |
  371. |:-------|:----:|
  372. | **DSH 宿主版本要求(≥ 0.1.2-rc.1;旧版宿主「installSettingsSection 时代」不兼容)** | ✅ 需 DSH ≥ 0.1.2-rc.1 |
  373. | Skill 体系:`SKILL.md` YAML frontmatter (`name + description + whenToUse`) | ✅ |
  374. | 技能名称规范 (`gongwen-skill`,长度 ≤ 30 字符) | ✅ |
  375. | 目录技能格式 (`.dsh/skills/gongwen-skill/SKILL.md`) | ✅ |
  376. | 单文件技能格式 (`.dsh/skills/gongwen-skill.md`) | ✅ 双格式兼容 |
  377. | Cordis 插件包:`package.json` + `dsh/` + `cordis.patch.yml` | ✅ |
  378. | 插件 bundle 声明:`dsh.bundle.patch`(官方「第三方插件」规范) | ✅ |
  379. | 客户端半侧声明:`dsh.client` + `exports["./client"]`(官方 Client 模块系统) | ✅ |
  380. | 模型工具注册:`ctx.tools.register(defineTool(...))`(官方 Registering Tools 规范) | ✅ `gongwen` 工具 |
  381. | 配置菜单:官方 `settings.section` 平级菜单(「文档样式配置」)+ `ctx.settingsScope`(官方 Client UI & Slots) | ✅ |
  382. | 系统提示注入:`ctx.systemPrompt.section`(官方 Host Services & Events) | ✅ |
  383. | 运行时技能:`ctx.skills.register`(官方 Skills 注册表) | ✅ |
  384. | CLI 独立可执行(`python -m gongwen <命令>`) | ✅ |
  385. | PyPI 上架(`pip install gongwen-skill`) | ✅ |
  386. | 零外部运行时依赖(仅 python-docx/pydantic/pyyaml) | ✅ |
  387. | DSH 配置化排版参数(页边距/行距/字体/默认公文类型,39 字段) | ✅ v2.6.0+ |
  388. ### DSH 插件配置化(v2.6.0+)
  389. DSH 插件支持通过配置文件管理排版参数,Agent 调用时自动注入,纯 CLI 用户不受影响。
  390. **两种配置入口(同一数据,双向同步)**:
  391. 1. **DSH Web 设置面板(推荐)**:系统设置 → **文档样式配置**(设置侧边栏平级菜单,与通用设置/模型/插件并列),页面含默认公文类型下拉(25 种)与完整排版参数(页边距/字体/行距等 39 字段);保存后写入 DSH 官方 settings 文档,并由插件 Host 的 `scope.watch` 自动同步到 `~/.gongwen-skill/dsh-config.json`。样式模板的**学习与管理走 CLI**(`style-learn` / `style-list` / `template`,见「样式学习」章节),不占用设置面板,保持插件薄层
  392. 2. **CLI / 配置文件**:直接编辑 `~/.gongwen-skill/dsh-config.json`,或通过插件 `config` 命令管理
  393. > **兼容性**:插件首次在带 settings provider 的 DSH 部署中加载时,会把已存在的 `~/.gongwen-skill/dsh-config.json` 一次性迁移进官方 settings 命名空间(仅当设置面板尚无用户覆盖时),之后以设置面板 / settings 文档为权威源,双向同步。
  394. **配置文件**:`~/.gongwen-skill/dsh-config.json`
  395. **初始化配置**(从默认模板创建):
  396. ```bash
  397. # 通过 DSH 插件调用
  398. node -e "import('./dsh/index.js').then(async m => { console.log(await m.call({}, {command: 'config', action: 'init'})) })"
  399. # 或直接复制默认模板
  400. cp etc/dsh-config-defaults.json ~/.gongwen-skill/dsh-config.json
  401. ```
  402. **配置项说明**(完整 39 字段,与设置面板一一对应):
  403. | 配置路径 | 说明 | 默认值 |
  404. |:---------|:-----|:-------|
  405. | `default_doc_type` | 默认公文类型 | `notice` |
  406. | `page_setup.margins.top/bottom` | 上下页边距 | `2.8cm` |
  407. | `page_setup.margins.left/right` | 左右页边距 | `2.7cm` |
  408. | `page_setup.header_distance` | 页眉距边界 | `1.5cm` |
  409. | `page_setup.footer_distance` | 页脚距边界 | `2.3cm` |
  410. | `body.font` / `body.font_fallback` | 正文字体 / 回退字体 | `仿宋_GB2312` / `FangSong` |
  411. | `body.size` | 正文字号 | `16pt` |
  412. | `body.line_spacing` | 正文行距 | `33pt` |
  413. | `body.first_line_indent` | 首行缩进 | `2em` |
  414. | `body.align` | 正文对齐 | `justify` |
  415. | `doc_title.font` / `doc_title.font_fallback` | 大标题字体 / 回退字体 | `方正小标宋简体` / `SimSun` |
  416. | `doc_title.size` / `doc_title.align` / `doc_title.bold` | 大标题字号 / 对齐 / 加粗 | `22pt` / `center` / `false` |
  417. | `doc_title.line_spacing` | 大标题行距 | `33pt` |
  418. | `heading_1.font` / `heading_1.font_fallback` | 一级标题字体 / 回退字体 | `黑体` / `SimHei` |
  419. | `heading_1.size` / `heading_1.line_spacing` / `heading_1.first_line_indent` | 一级标题字号 / 行距 / 首行缩进 | `16pt` / `33pt` / `2em` |
  420. | `heading_2.font` / `heading_2.font_fallback` | 二级标题字体 / 回退字体 | `楷体_GB2312` / `KaiTi` |
  421. | `heading_2.size` / `heading_2.line_spacing` / `heading_2.first_line_indent` | 二级标题字号 / 行距 / 首行缩进 | `16pt` / `33pt` / `2em` |
  422. | `heading_3.font` / `heading_3.font_fallback` | 三级标题字体 / 回退字体 | `仿宋_GB2312` / `FangSong` |
  423. | `heading_3.size` / `heading_3.bold` / `heading_3.line_spacing` / `heading_3.first_line_indent` | 三级标题字号 / 加粗 / 行距 / 首行缩进 | `16pt` / `true` / `33pt` / `2em` |
  424. | `signature.font` / `signature.font_fallback` | 署名字体 / 回退字体 | `仿宋_GB2312` / `FangSong` |
  425. | `signature.size` / `signature.align` | 署名字号 / 对齐 | `18pt` / `center` |
  426. **修改配置**(DSH 插件调用):
  427. ```javascript
  428. // 设置单个配置项
  429. await call({}, {command: 'config', action: 'set', key: 'page_setup.margins.top', value: '3.0cm'})
  430. // 读取配置项
  431. await call({}, {command: 'config', action: 'get', key: 'body.line_spacing'})
  432. // 查看完整配置
  433. await call({}, {command: 'config', action: 'show'})
  434. // 重置为默认值
  435. await call({}, {command: 'config', action: 'reset'})
  436. ```
  437. **纯 CLI 使用 `--config-overrides`**:
  438. ```bash
  439. # 临时覆盖行距为 28 磅
  440. python -m gongwen template notice -o 通知.docx \
  441. --config-overrides '{"body":{"line_spacing":"28pt"}}'
  442. # 临时覆盖页边距
  443. python -m gongwen optimize input.docx -o output.docx --apply \
  444. --config-overrides '{"page_setup":{"margins":{"top":"3.0cm"}}}'
  445. ```
  446. **设计说明**:
  447. - **分层架构**:Python CLI(纯工具层)只接受 `--config-overrides` 通用参数;DSH 插件(配置管理者)读写配置文件并自动注入
  448. - **优先级**:official YAML < custom YAML < user YAML < DSH config overrides < 命令行 `--config-overrides`
  449. - **热更新**:每次调用读取配置文件,修改后立即生效,无需重启
  450. - **纯 CLI 不受影响**:不使用 DSH 插件时不会读取 `dsh-config.json`
  451. ### 适用场景对照
  452. | 你的场景 | 推荐方式 |
  453. |:---|:---|
  454. | 只想在终端用 gongwen-skill 命令 | 方式零 |
  455. | 想让 DSH Agent 调用本技能,无需 Web UI | 方式一(Skill 文件系统) |
  456. | 想让 DSH Web UI 工具面板直接调用 | 方式二(npm 插件 bundle) |
  457. | 二开插件本身,本地反复编辑 | 方式三(link 模式) |
  458. | 通用 Agent 一行安装(Claude Code/Codex/Cursor 等) | `npx skills add linhut/gongwen-skill` |
  459. ## 🤖 通过 Agent 调用
  460. 本 Skill 可直接被 AI Agent(如 WorkBuddy、CloudCode、Claude Code、AtomCode 等)加载并调用,无需手动操作。
  461. ### 安装方式
  462. **方式零:npx skills add 一行安装(最简)**
  463. ```bash
  464. # 任意支持 Agent Skills 的 harness(Claude Code / Codex / Cursor 等)均可:
  465. # skills CLI 会自动把本技能路由到对应 harness 的 skills 目录
  466. npx skills add linhut/gongwen-skill
  467. ```
  468. **方式一:克隆到 Skills 目录(推荐)**
  469. ```bash
  470. # WorkBuddy / CloudCode
  471. git clone https://github.com/linhut/gongwen-skill.git ~/.workbuddy/skills/gongwen-skill/
  472. # AtomCode
  473. git clone https://github.com/linhut/gongwen-skill.git ~/.atomcode/skills/gongwen-skill/
  474. # Claude Code
  475. git clone https://github.com/linhut/gongwen-skill.git ~/.claude/skills/gongwen-skill/
  476. # 其他 Agent — 将仓库克隆到对应的 skills 目录即可
  477. ```
  478. **方式二:任何工作目录下直接使用**
  479. ```bash
  480. git clone https://github.com/linhut/gongwen-skill.git
  481. cd gongwen-skill
  482. pip install -r requirements.txt
  483. # 之后 Agent 可直接调用 python -m gongwen <命令>
  484. ```
  485. ### 对话中使用示例
  486. | 用户说 | Agent 行为 | 路径 |
  487. |--------|-----------|------|
  488. | "帮我检查这份通知的格式" | 自动执行 `check` 并展示问题清单 | A |
  489. | "帮我排版这份红头文件" | 自动执行 `optimize --apply` 修复格式 | A |
  490. | "润色一下这份报告的措辞" | 生成 `changes.json`,执行 `optimize-content`(tracked 修订+批注) | B |
  491. | "帮我写一份关于XX的通知" | 追问细节后走草稿→`md2docx`→`optimize`→`check` | C |
  492. | "核验一下这份新闻稿里的人名职务" | 执行 `optimize-content --output-tasks` → Agent 核验 → `--input-tasks` 回填 | B+协作 |
  493. | "给这份会议通知生成桌签" | 询问名单后执行 `table-signs` | 独立 |
  494. | "看看这份文档有没有问题" | 执行 `audit` 检查删除线/加粗/AI声明 | 独立 |
  495. ### Agent 调用示例(对话式)
  496. ```
  497. 用户:帮我优化这份会议通知的第二章节措辞
  498. Agent:📋 合规自检报告
  499. Skill 版本: v2.12.0(版本自检已确认最新)
  500. 路径判定: B(内容优化)
  501. 依据: 用户指定了已有文档,且要求"优化措辞"
  502. 命令调用: 1. python -m gongwen optimize-content 会议通知.docx --changes changes.json --apply --paragraphs "5-8"
  503. 是否绕过: 否
  504. 交付物: 会议通知+庄重严谨+2026-08-01+v1.docx(Word 原生修订+批注版)
  505. 质量验证: check 通过
  506. ```
  507. ## 🔧 LLM 集成(可选)
  508. Skill 定位为**工具层**,默认不依赖 LLM(确定性工作全自包含)。以下可选能力需配置环境变量(未配置自动降级,不影响主流程):
  509. | 环境变量 | 能力 |
  510. |---------|------|
  511. | `GONGWEN_LLM_API` / `_API_KEY` / `_MODEL` | LLM 实体提取、自动生成优化建议、风格增强(skill 内置调用) |
  512. | `GONGWEN_OPTIMIZE_LLM_API`(优先于 LLM_API) | optimize-content 专用配置 |
  513. | `GONGWEN_WEB_VERIFY=1` | 事实核验互联网交叉核验(百度→必应多引擎) |
  514. > **推荐模式**:Agent 环境中通过 `--output-tasks` / `--input-tasks` 协作,用 Agent 自身 LLM+搜索能力处理,无需配置上述环境变量。
  515. ## 📦 依赖
  516. 仅 3 个纯 Python 包:`python-docx`、`pydantic`、`pyyaml`。无数据库、无 Web 框架、无桌面端。
  517. ## 💬 社区交流
  518. 欢迎加入社区,参与讨论、交流使用问题、插件开发和项目进展:
  519. | 平台 | 说明 |
  520. |:-----|:------|
  521. | 💬 **Discord** | [加入 Discord 服务器](https://discord.gg/4qT7TPdft) — 实时交流、问题讨论、版本更新通知 |
  522. | 💚 **QQ 群** | 扫码加入 QQ 群,与中文用户交流使用经验 |
  523. ---
  524. ## 🌐 GitHub 不可达排查(安全 DNS / DoH)
  525. 国内网络访问 GitHub 常遇「无法访问 / 超时」问题,常见原因之一是 **DNS 污染**——系统 DNS 返回的不是真实 IP,而是保留/Fake-IP 段(如 198.18.0.0/15、0.0.0.0),连接自然失败或超时。
  526. **快速诊断**:运行 python -m gongwen doctor(含网络/DNS 检查项),或 python -m gongwen check-update(GitHub 渠道不可达时自动诊断)。检测到疑似污染时,会输出系统解析 vs 安全 DNS 真实 IP 对比,以及可直接粘贴的 hosts 条目建议。
  527. **原理**:安全 DNS(DoH,DNS over HTTPS)通过加密 HTTP 查询 DNS,避免中间设备篡改解析结果,可拿到域名的真实 IP。本工具内置阿里(dns.alidns.com)、腾讯(doh.pub / 1.12.12.12)等国内公共 DoH 端点,多端点自动降级;可通过环境变量 GONGWEN_DOH 覆盖为自定义端点(如自建的 DoH 服务)。
  528. **自动兜底(v2.10.0)**:`font install` 下载字体、`check-update` 查 PyPI 时若常规请求失败(疑似 DNS 污染),自动用 DoH 真实 IP + TLS SNI 直连重试——TLS 证书仍按真实域名校验,安全不降级,用户零操作。
  529. **处置建议**(按推荐度):
  530. 1. 若使用了代理工具(Clash/V2Ray 等)且系统解析命中 198.18.x Fake-IP,优先检查其 DNS 模式的 fake-ip-filter 是否漏掉 GitHub 域名(比改 hosts 更治本)
  531. 2. 将诊断输出的 hosts 条目写入 C:\Windows\System32\drivers\etc\hosts(需管理员权限),git / 浏览器即可直连真实 IP
  532. 3. 或使用国内镜像仓库克隆/更新(见下方「镜像仓库」)
  533. > 诊断 + 自动兜底:本工具不写入 hosts、不修改系统配置;但 `font install` 下载字体、`check-update` 查询 PyPI 遇到 DNS 污染导致的失败时,会**自动用安全 DNS(DoH)真实 IP + TLS SNI 直连重试**(零操作,证书校验不降级)。DoH 查询经第三方公共 DNS 服务,仅在诊断/兜底失败时发起少量查询,隐私敏感者可设置 GONGWEN_DOH 指向自有端点。
  534. ## 📄 许可证与出处
  535. MIT License · **(c) 2026 Jose AI** · https://www.linhut.cn
  536. 本 Skill 源自开源项目 [AI 公文智能优化助手](https://github.com/linhut/document-ai-assistant)。格式引擎与规则 YAML 版权归原作者所有,依 MIT 许可证发行。
  537. ### 镜像仓库
  538. - GitHub:https://github.com/linhut/gongwen-skill
  539. - GitCode:https://gitcode.com/linhut/gongwen-skill
  540. - AtomGit:https://atomgit.com/linhut/gongwen-skill
gongwen/cli/netcheck.py · Bundled script · 362 lines · 1 finding marked
  1. #!/usr/bin/env python3
  2. # -*- coding: utf-8 -*-
  3. #
  4. # (c) 2026 Jose AI (https://www.linhut.cn)
  5. # https://github.com/linhut/gongwen-skill
  6. # Licensed under the MIT License. See the LICENSE file for details.
  7. #
  8. """
  9. gongwen.cli.netcheck -- DNS 污染诊断 + 自动直连兜底(安全 DNS / DoH)。
  10. 背景:系统 DNS 常被污染(返回 198.18.0.0/15 等保留段 Fake-IP),
  11. 导致 GitHub 等域名无法访问/超时。本模块通过 DoH(DNS over HTTPS)
  12. 查询真实 IP,与系统解析对比,判定是否疑似 DNS 污染,
  13. 并输出可直接粘贴的 hosts 条目建议。
  14. 诊断(v2.8.0 规格 docs/superpowers/specs/2026-09-03-dns-pollution-diagnosis-design.md):
  15. - 不修改 hosts;诊断结果仅供参考
  16. - 内置国内公共 DoH(阿里/腾讯),支持环境变量 GONGWEN_DOH 自定义
  17. - 所有网络操作超时短、可完全离线(--offline 时调用方不调用本模块)
  18. 自动直连兜底(download_with_doh_fallback):
  19. - 常规下载失败(疑似 DNS 污染)时,自动用 DoH 真实 IP + TLS SNI 直连
  20. - 证书校验保持针对真实域名(server_hostname),安全不降级,用户零操作
  21. """
  22. from __future__ import annotations
  23. import http.client
  24. import ipaddress
  25. import json
  26. import logging
  27. import os
  28. import socket
  29. import urllib.parse
  30. import urllib.request
  31. _logger = logging.getLogger(__name__)
  32. # 超时(秒):DoH 查询每个端点,短超时快速降级
  33. _DOH_TIMEOUT = 5
  34. # 默认 DoH 端点:优先国内公共 DoH(实测 2026-09-03 可用,Cloudflare 不可达)。
  35. # 环境变量 GONGWEN_DOH 可覆盖/追加自定义端点(如用户自建 oaifree 服务)。
  36. # 格式:application/dns-json GET 风格,追加 ?name=X&type=A 查询
  37. _DOH_ENDPOINTS = [
  38. "https://dns.alidns.com/resolve", # 阿里公共 DNS
  39. "https://doh.pub/resolve", # 腾讯 DNSPod
  40. "https://1.12.12.12/resolve", # 腾讯 DNSPod(IP 直连)
    • Note: Talks to a raw IP address or throwaway host, where malware is often staged
    • Line 48 on GitHub
  41. "https://dns.google/resolve", # Google(备用,实测可用)
  42. ]
  43. def _doh_endpoints() -> list:
  44. """返回 DoH 端点列表:环境变量 GONGWEN_DOH 置顶,其余跟随默认列表。"""
  45. custom = os.environ.get("GONGWEN_DOH", "").strip()
  46. if not custom:
  47. return list(_DOH_ENDPOINTS)
  48. # 支持逗号分隔多个自定义端点(如 GONGWEN_DOH=a.com/x,b.com/y)
  49. custom_list = [u.strip() for u in custom.split(",") if u.strip()]
  50. return custom_list + [u for u in _DOH_ENDPOINTS if u not in custom_list]
  51. def _is_ipv4(s: str) -> bool:
  52. """判断字符串是否为合法 IPv4 地址。"""
  53. try:
  54. ipaddress.IPv4Address(s)
  55. return True
  56. except (ipaddress.AddressValueError, TypeError, ValueError):
  57. return False
  58. def resolve_via_doh(host: str) -> list:
  59. """通过 DoH 查询域名的真实 IPv4 地址(多端点降级)。
  60. Args:
  61. host: 域名,如 "github.com"。
  62. Returns:
  63. IPv4 地址列表;全部端点失败时返回空列表。
  64. """
  65. for base in _doh_endpoints():
  66. try:
  67. query = urllib.parse.urlencode({"name": host, "type": "A"})
  68. url = base + "?" + query
  69. req = urllib.request.Request(url, headers={
  70. "Accept": "application/dns-json",
  71. "User-Agent": "gongwen-skill/2.8",
  72. })
  73. with urllib.request.urlopen(req, timeout=_DOH_TIMEOUT) as resp:
  74. data = json.loads(resp.read().decode("utf-8", errors="replace"))
  75. ips = [
  76. a.get("data", "") for a in data.get("Answer", [])
  77. if a.get("type") == 1 and _is_ipv4(a.get("data", ""))
  78. ]
  79. if ips:
  80. return list(dict.fromkeys(ips)) # 去重保序
  81. except Exception as e:
  82. _logger.debug("DoH 端点 %s 查询 %s 失败: %s", base, host, e)
  83. continue
  84. return []
  85. def system_resolve(host: str) -> list:
  86. """系统 DNS 解析域名,返回 IPv4 地址列表。失败返回空列表。"""
  87. try:
  88. infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
  89. ips = [info[4][0] for info in infos if ":" not in info[4][0]]
  90. return list(dict.fromkeys(ips))
  91. except Exception as e:
  92. _logger.debug("系统解析 %s 失败: %s", host, e)
  93. return []
  94. def _is_reserved_or_fake_ip(ip: str) -> bool:
  95. """判断 IP 是否落在保留/异常网段(DNS 污染 / Fake-IP 典型特征)。
  96. 覆盖:198.18.0.0/15(Fake-IP 基准段)、0.0.0.0/8、127.0.0.0/8、
  97. 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16。
  98. """
  99. try:
  100. addr = ipaddress.IPv4Address(ip)
  101. except (ipaddress.AddressValueError, ValueError):
  102. return False
  103. reserved = [
  104. ipaddress.ip_network("198.18.0.0/15"),
  105. ipaddress.ip_network("0.0.0.0/8"),
  106. ipaddress.ip_network("127.0.0.0/8"),
  107. ipaddress.ip_network("10.0.0.0/8"),
  108. ipaddress.ip_network("172.16.0.0/12"),
  109. ipaddress.ip_network("192.168.0.0/16"),
  110. ]
  111. return any(addr in net for net in reserved)
  112. def _join_ips(ips) -> str:
  113. """IP 列表转中文顿号分隔字符串。"""
  114. return "、".join(ips) if ips else "(无)"
  115. def detect_pollution(host: str) -> dict:
  116. """对单个域名做 DNS 污染诊断。
  117. Returns:
  118. dict: {
  119. "host": 域名,
  120. "ok": True=正常 / False=疑似污染 / None=无法判定或差异提示,
  121. "system_ips": 系统解析 IP 列表,
  122. "doh_ips": DoH 真实 IP 列表,
  123. "detail": 诊断说明,
  124. }
  125. """
  126. sys_ips = system_resolve(host)
  127. doh_ips = resolve_via_doh(host)
  128. sys_str = _join_ips(sys_ips)
  129. doh_str = _join_ips(doh_ips)
  130. # DoH 全部端点不可达 → 无法判定(不误报)
  131. if not doh_ips:
  132. return {
  133. "host": host, "ok": None,
  134. "system_ips": sys_ips, "doh_ips": [],
  135. "detail": "安全 DNS(DoH)查询失败,无法判定(可能离线或 DoH 服务不可达)",
  136. }
  137. # 系统解析失败 + DoH 成功 → 疑似污染
  138. if not sys_ips:
  139. return {
  140. "host": host, "ok": False,
  141. "system_ips": [], "doh_ips": doh_ips,
  142. "detail": "系统 DNS 解析失败,安全 DNS 真实 IP 为 " + doh_str,
  143. }
  144. overlap = set(sys_ips) & set(doh_ips)
  145. if overlap:
  146. return {
  147. "host": host, "ok": True,
  148. "system_ips": sys_ips, "doh_ips": doh_ips,
  149. "detail": "系统 DNS 与安全 DNS 解析一致",
  150. }
  151. # 无交集:若系统 IP 全部落在保留段 → 疑似污染;否则为多区域差异提示
  152. if all(_is_reserved_or_fake_ip(ip) for ip in sys_ips):
  153. return {
  154. "host": host, "ok": False,
  155. "system_ips": sys_ips, "doh_ips": doh_ips,
  156. "detail": ("系统 DNS 解析为 " + sys_str + "(保留/Fake-IP 段),"
  157. "安全 DNS 真实 IP 为 " + doh_str + " —— 疑似 DNS 污染"),
  158. }
  159. return {
  160. "host": host, "ok": None,
  161. "system_ips": sys_ips, "doh_ips": doh_ips,
  162. "detail": ("系统 DNS 解析为 " + sys_str + ",安全 DNS 为 " + doh_str
  163. + "(无保留段特征,可能为 CDN 多区域差异)"),
  164. }
  165. def check_hosts(hosts: list = None) -> list:
  166. """批量诊断一组域名(默认 GitHub 关键域名 + PyPI)。
  167. Args:
  168. hosts: 域名列表;None 时使用默认检查清单。
  169. Returns:
  170. 每个域名的 detect_pollution 结果列表。
  171. """
  172. default_hosts = [
  173. "github.com",
  174. "api.github.com",
  175. "raw.githubusercontent.com",
  176. "codeload.github.com",
  177. "objects.githubusercontent.com",
  178. "pypi.org",
  179. ]
  180. targets = hosts if hosts else default_hosts
  181. return [detect_pollution(h) for h in targets]
  182. def format_hosts(entries: list) -> str:
  183. """根据诊断结果生成可粘贴的 hosts 条目文本。
  184. Args:
  185. entries: check_hosts / detect_pollution 的结果列表。
  186. Returns:
  187. hosts 条目文本(每行 "IP 域名"),仅包含有真实 IP 的域名。
  188. """
  189. lines_out = []
  190. for e in entries:
  191. ips = e.get("doh_ips") or []
  192. host = e.get("host") or ""
  193. if ips:
  194. lines_out.append(ips[0] + " " + host)
  195. if not lines_out:
  196. return "(无可用的 hosts 建议:安全 DNS 未取得真实 IP)"
  197. return chr(10).join(lines_out)
  198. def summarize(entries: list) -> dict:
  199. """汇总批量诊断结果(供 check-update --json / doctor 使用)。
  200. Returns:
  201. dict: {
  202. "polluted": 是否存在疑似污染域名,
  203. "checked": 检查域名数,
  204. "ok_count": 正常数,
  205. "warn_count": 差异提示数,
  206. "fail_count": 疑似污染数,
  207. "detail": 汇总说明,
  208. "hosts_suggestions": hosts 条目文本,
  209. }
  210. """
  211. ok_count = sum(1 for e in entries if e.get("ok") is True)
  212. fail_count = sum(1 for e in entries if e.get("ok") is False)
  213. warn_count = sum(1 for e in entries if e.get("ok") is None)
  214. polluted = fail_count > 0
  215. detail_parts = []
  216. for e in entries:
  217. if e.get("ok") is False:
  218. detail_parts.append(e.get("host", "") + ": " + str(e.get("detail", "")))
  219. detail = ";".join(detail_parts) if detail_parts else "未检测到 DNS 污染"
  220. return {
  221. "polluted": polluted,
  222. "checked": len(entries),
  223. "ok_count": ok_count,
  224. "warn_count": warn_count,
  225. "fail_count": fail_count,
  226. "detail": detail,
  227. "hosts_suggestions": format_hosts(entries),
  228. }
  229. class _DoHHTTPSConnection(http.client.HTTPSConnection):
  230. """用 DoH 真实 IP 直连的 HTTPS 连接(TLS SNI 保持真实域名)。
  231. 证书校验仍针对真实域名(server_hostname=host),安全不降级:
  232. 连接的目标 IP 来自 DoH 真实解析,但 TLS 握手/证书校验完全等价于
  233. 常规 HTTPS 请求,只是绕过了被污染的系统 DNS。
  234. """
  235. def __init__(self, host, ip, timeout=None):
  236. super().__init__(host, timeout=timeout)
  237. self._doh_ip = ip
  238. def connect(self):
  239. """连接 DoH 解析出的真实 IP,TLS 握手仍使用真实域名(SNI)。"""
  240. sock = socket.create_connection((self._doh_ip, self.port), self.timeout)
  241. self.sock = self._context.wrap_socket(sock, server_hostname=self.host)
  242. def _http_get_via_ip(host, ip, path, timeout, headers):
  243. """通过指定 IP 发起 HTTPS GET(SNI/证书校验针对 host),返回 (status, data, location)。"""
  244. conn = _DoHHTTPSConnection(host, ip, timeout=timeout)
  245. try:
  246. conn.request("GET", path, headers=headers)
  247. resp = conn.getresponse()
  248. return resp.status, resp.read(), resp.getheader("Location")
  249. finally:
  250. conn.close()
  251. def download_with_doh_fallback(url, timeout=30, headers=None, max_redirects=5):
  252. """下载 URL 内容;常规下载失败时自动用 DoH 真实 IP + TLS SNI 直连兜底。
  253. Args:
  254. url: http(s) 下载地址。
  255. timeout: 单次请求超时(秒),默认 30。
  256. headers: 附加请求头(dict);缺省用 gongwen-skill UA。
  257. max_redirects: 最大跟随重定向次数(兜底路径手动处理 3xx)。
  258. Returns:
  259. bytes: 响应体。
  260. Raises:
  261. Exception: 常规与 DoH 兜底均失败时抛出(由调用方决定提示)。
  262. Note:
  263. - 常规 urllib 请求自动跟随重定向;兜底路径手动跟随并重新解析新域名。
  264. - 仅 https 参与 DoH 兜底(http 无 TLS,无 SNI 语义)。
  265. - 证书校验不降级:wrap_socket 时 server_hostname=host,等价常规 HTTPS。
  266. """
  267. if headers is None:
  268. headers = {"User-Agent": "gongwen-skill"}
  269. current = url
  270. for _ in range(max_redirects + 1):
  271. parsed = urllib.parse.urlsplit(current)
  272. host = parsed.hostname or ""
  273. is_https = parsed.scheme == "https"
  274. try:
  275. req = urllib.request.Request(current, headers=headers)
  276. with urllib.request.urlopen(req, timeout=timeout) as resp:
  277. return resp.read()
  278. except Exception as normal_err:
  279. if not is_https:
  280. raise
  281. ips = resolve_via_doh(host)
  282. last_err = normal_err
  283. redirected = False
  284. for ip in ips:
  285. try:
  286. status, data, location = _http_get_via_ip(
  287. host, ip, parsed.path or "/", timeout, headers,
  288. )
  289. except Exception as ip_err:
  290. last_err = ip_err
  291. continue
  292. if status in (301, 302, 303, 307, 308) and location:
  293. current = urllib.parse.urljoin(current, location)
  294. redirected = True
  295. break
  296. if 200 <= status < 300:
  297. return data
  298. if status >= 400:
  299. # 4xx/5xx 一般为真实错误,但不排除中间设备干扰(如 400),
  300. # 已尝试下一 IP;全部失败后抛出最后错误。
  301. last_err = OSError("HTTP " + str(status) + " via DoH IP " + ip)
  302. continue
  303. last_err = OSError("HTTP " + str(status) + " via DoH IP " + ip)
  304. continue
  305. if redirected:
  306. continue
  307. raise last_err
  308. raise OSError("下载重定向次数超限: " + url)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.