Back to search
gongwen-skill
SkillGitHub
公文全流程处理工具——基于 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
Markdown
[](/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)
- {
- "name": "gongwen-skill-marketplace",
- "description": "公文全流程处理专家(gongwen-skill)Claude Code 插件市场",
- "owner": {
- "name": "Jose AI"
- },
- "plugins": [
- {
- "name": "gongwen-skill",
- "displayName": "公文全流程处理专家",
- "source": "./",
- "version": "2.12.0",
- "description": "公文全流程处理专家 —— 面向中文公文(.docx)的 GB/T 9704 全流程工具链:格式检查、自动修复、内容优化(Word 原生修订+批注 / 行内差异对比)、模板生成、样式学习、Markdown 转公文、版头版记页码注入,覆盖 25 类法定公文。",
- "category": "productivity",
- "tags": [
- "chinese",
- "document",
- "government",
- "official-document",
- "GB/T 9704",
- "docx",
- "skill",
- "公文"
- ]
- }
- ]
- }
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)
- <!--
- (c) 2026 Jose AI (https://www.linhut.cn)
- https://github.com/linhut/gongwen-skill
- Licensed under the MIT License. See the LICENSE file for details.
- -->
- # 公文全流程处理专家
- <p align="center">
- <img src="./logo/2026-08-19_11-17-43.png" alt="公文全流程处理专家" width="760">
- </p>
- > 中文公文全流程处理专家——基于 **GB/T 9704《党政机关公文格式》** 国家标准,支持 **格式检查与修复、内容优化(Word 原生修订+批注/差异对比版)、模板生成、Markdown 转公文、版头版记页码注入、事实核验、风格增强** 等完整能力。原生支持 **DeepSeek Harness (DSH)** 技能系统,打包为可被 AI Agent 直接调用的 Skill,完全自包含,克隆即用。
- [](https://github.com/linhut/gongwen-skill/actions)
- [](https://pypi.org/project/gongwen-skill/)
- [](./LICENSE)
- 
- 
- 
- 
- 本 Skill 源自开源桌面项目 [AI 公文智能优化助手](https://github.com/linhut/document-ai-assistant),将其核心格式引擎抽取、剥离桌面端/数据库依赖后独立发行,支持公文的**模板建立、解析、规则检查、自动修复、内容优化、Markdown 转公文**全流程能力。同时原生集成 **DeepSeek Harness (DSH)** 技能系统,支持 DSH Agent 自动发现与加载。
- ---
- ## ✨ 能力一览
- | 能力 | 命令 | 说明 |
- |------|------|------|
- | 📋 列类型 | `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` / Agent 长任务收尾必写) |
- | ⚙️ 规则管理 | `rule-export/import/list` | YAML 规则三层定制(官方/单位/用户) |
- | 🧭 向导式交互 | `wizard` | 交互式路径引导(A/B/C/D/E)+ 一键执行;Agent 用 `--answers` 非交互 / `--dry-run` 只打印命令 |
- ## 使用示例
- > 在 AI 对话中调用 gongwen-skill,输入自然语言指令,自动生成符合 GB/T 9704 国标格式的正式公文。
- ### 🤖 调用环境的适配指引(AI Agent 必读)
- 本工具针对不同能力层级的 AI 调用环境,提供不同的使用方式。**AI 读取本文件后,请先判断自身环境属于哪一类,再按对应指引执行:**
- | 环境类型 | 典型平台 | 能力 | 使用方式 |
- |:---------|:---------|:-----|:---------|
- | **① 可执行代码的 Agent** | WorkBuddy、CloudCode、Claude Code、AtomCode、DeepSeek Harness | 可运行命令、读写本地文件 | 直接执行 `python -m gongwen <命令>`,见下方「快速开始」与「通过 Agent 调用」 |
- | **② 纯对话 LLM(无代码执行能力)** | 豆包、Kimi、ChatGPT 网页版等 | 只能阅读文本、给出建议,**不能运行命令或读写文件** | 引导用户手动执行,见下方「纯对话 LLM 使用指引」 |
- #### 纯对话 LLM 使用指引(环境 ②)
- > **如果你是无法执行代码的纯对话 AI**(如豆包、Kimi、ChatGPT 网页版等),请按以下方式协助用户:
- 1. **告知工具性质**:向用户说明「这是一个本地运行的 Python 命令行工具,需要在你自己的电脑上安装后使用」,并说明它能做什么(格式检查、自动修复、内容优化、模板生成等 29 项命令能力)。
- 2. **引导安装**:请用户在自己的电脑上执行以下步骤:
- ```bash
- # 步骤 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 可直接读取解读,无需执行任何代码即可提供专业的公文写作指导。
- ## 🚀 快速开始
- ```bash
- git clone https://github.com/linhut/gongwen-skill.git
- cd gongwen-skill
- pip install -r requirements.txt
- # 生成一份标准通知模板
- python -m gongwen template notice -o 通知模板.docx
- # 检查公文格式(只读)
- 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 仓库](https://github.com/linhut/document-ai-assistant/tree/master/TTF) 下载到 `~/.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 构建基准,已确认实体自动过滤
- ### Agent 协作机制(`--output-tasks` / `--input-tasks`)
- Skill 定位为**工具层**——确定性工作自己做,需 LLM/搜索判断的环节交由 Agent:
- ```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)
- 交互式引导选择处理路径并一键执行,适合不熟悉命令行的用户;Agent 可走非交互模式:
- ```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) 集成
- 本 Skill 同时支持 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 的**两种集成方式**——文件系统 **Skill**(轻量、跟随项目)与 **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 Skill 注册(基于本地文件系统)
- DSH Agent 启动时自动扫描下表目录中的技能(优先级从高到低):
- | 优先级 | 目录 | 说明 |
- |:------:|:-----|:------|
- | 100 | `{project}/.dsh/skills/` | 项目级 DSH 技能目录 |
- | 200 | `{project}/.agents/skills/` | 项目级 Agent 技能目录 |
- | 400 | `~/.dsh/skills/` | 用户级 DSH 技能目录 |
- | 500 | `~/.agents/skills/` | 用户级 Agent 技能目录 |
- **安装方式**(二选一):
- ```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 Agent 在启动时自动发现并加载本技能;本仓库自带 `.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/](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 体系:`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` → Agent 核验 → `--input-tasks` 回填 | B+协作 |
- | "给这份会议通知生成桌签" | 询问名单后执行 `table-signs` | 独立 |
- | "看看这份文档有没有问题" | 执行 `audit` 检查删除线/加粗/AI声明 | 独立 |
- ### Agent 调用示例(对话式)
- ```
- 用户:帮我优化这份会议通知的第二章节措辞
- Agent:📋 合规自检报告
- 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` | 事实核验互联网交叉核验(百度→必应多引擎) |
- > **推荐模式**:Agent 环境中通过 `--output-tasks` / `--input-tasks` 协作,用 Agent 自身 LLM+搜索能力处理,无需配置上述环境变量。
- ## 📦 依赖
- 仅 3 个纯 Python 包:`python-docx`、`pydantic`、`pyyaml`。无数据库、无 Web 框架、无桌面端。
- ## 💬 社区交流
- 欢迎加入社区,参与讨论、交流使用问题、插件开发和项目进展:
- | 平台 | 说明 |
- |:-----|:------|
- | 💬 **Discord** | [加入 Discord 服务器](https://discord.gg/4qT7TPdft) — 实时交流、问题讨论、版本更新通知 |
- | 💚 **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 公文智能优化助手](https://github.com/linhut/document-ai-assistant)。格式引擎与规则 YAML 版权归原作者所有,依 MIT 许可证发行。
- ### 镜像仓库
- - GitHub:https://github.com/linhut/gongwen-skill
- - GitCode:https://gitcode.com/linhut/gongwen-skill
- - AtomGit:https://atomgit.com/linhut/gongwen-skill
gongwen/cli/netcheck.py · Bundled script · 362 lines · 1 finding marked
- #!/usr/bin/env python3
- # -*- coding: utf-8 -*-
- #
- # (c) 2026 Jose AI (https://www.linhut.cn)
- # https://github.com/linhut/gongwen-skill
- # Licensed under the MIT License. See the LICENSE file for details.
- #
- """
- gongwen.cli.netcheck -- DNS 污染诊断 + 自动直连兜底(安全 DNS / DoH)。
- 背景:系统 DNS 常被污染(返回 198.18.0.0/15 等保留段 Fake-IP),
- 导致 GitHub 等域名无法访问/超时。本模块通过 DoH(DNS over HTTPS)
- 查询真实 IP,与系统解析对比,判定是否疑似 DNS 污染,
- 并输出可直接粘贴的 hosts 条目建议。
- 诊断(v2.8.0 规格 docs/superpowers/specs/2026-09-03-dns-pollution-diagnosis-design.md):
- - 不修改 hosts;诊断结果仅供参考
- - 内置国内公共 DoH(阿里/腾讯),支持环境变量 GONGWEN_DOH 自定义
- - 所有网络操作超时短、可完全离线(--offline 时调用方不调用本模块)
- 自动直连兜底(download_with_doh_fallback):
- - 常规下载失败(疑似 DNS 污染)时,自动用 DoH 真实 IP + TLS SNI 直连
- - 证书校验保持针对真实域名(server_hostname),安全不降级,用户零操作
- """
- from __future__ import annotations
- import http.client
- import ipaddress
- import json
- import logging
- import os
- import socket
- import urllib.parse
- import urllib.request
- _logger = logging.getLogger(__name__)
- # 超时(秒):DoH 查询每个端点,短超时快速降级
- _DOH_TIMEOUT = 5
- # 默认 DoH 端点:优先国内公共 DoH(实测 2026-09-03 可用,Cloudflare 不可达)。
- # 环境变量 GONGWEN_DOH 可覆盖/追加自定义端点(如用户自建 oaifree 服务)。
- # 格式:application/dns-json GET 风格,追加 ?name=X&type=A 查询
- _DOH_ENDPOINTS = [
- "https://dns.alidns.com/resolve", # 阿里公共 DNS
- "https://doh.pub/resolve", # 腾讯 DNSPod
- "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
- "https://dns.google/resolve", # Google(备用,实测可用)
- ]
- def _doh_endpoints() -> list:
- """返回 DoH 端点列表:环境变量 GONGWEN_DOH 置顶,其余跟随默认列表。"""
- custom = os.environ.get("GONGWEN_DOH", "").strip()
- if not custom:
- return list(_DOH_ENDPOINTS)
- # 支持逗号分隔多个自定义端点(如 GONGWEN_DOH=a.com/x,b.com/y)
- custom_list = [u.strip() for u in custom.split(",") if u.strip()]
- return custom_list + [u for u in _DOH_ENDPOINTS if u not in custom_list]
- def _is_ipv4(s: str) -> bool:
- """判断字符串是否为合法 IPv4 地址。"""
- try:
- ipaddress.IPv4Address(s)
- return True
- except (ipaddress.AddressValueError, TypeError, ValueError):
- return False
- def resolve_via_doh(host: str) -> list:
- """通过 DoH 查询域名的真实 IPv4 地址(多端点降级)。
- Args:
- host: 域名,如 "github.com"。
- Returns:
- IPv4 地址列表;全部端点失败时返回空列表。
- """
- for base in _doh_endpoints():
- try:
- query = urllib.parse.urlencode({"name": host, "type": "A"})
- url = base + "?" + query
- req = urllib.request.Request(url, headers={
- "Accept": "application/dns-json",
- "User-Agent": "gongwen-skill/2.8",
- })
- with urllib.request.urlopen(req, timeout=_DOH_TIMEOUT) as resp:
- data = json.loads(resp.read().decode("utf-8", errors="replace"))
- ips = [
- a.get("data", "") for a in data.get("Answer", [])
- if a.get("type") == 1 and _is_ipv4(a.get("data", ""))
- ]
- if ips:
- return list(dict.fromkeys(ips)) # 去重保序
- except Exception as e:
- _logger.debug("DoH 端点 %s 查询 %s 失败: %s", base, host, e)
- continue
- return []
- def system_resolve(host: str) -> list:
- """系统 DNS 解析域名,返回 IPv4 地址列表。失败返回空列表。"""
- try:
- infos = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
- ips = [info[4][0] for info in infos if ":" not in info[4][0]]
- return list(dict.fromkeys(ips))
- except Exception as e:
- _logger.debug("系统解析 %s 失败: %s", host, e)
- return []
- def _is_reserved_or_fake_ip(ip: str) -> bool:
- """判断 IP 是否落在保留/异常网段(DNS 污染 / Fake-IP 典型特征)。
- 覆盖:198.18.0.0/15(Fake-IP 基准段)、0.0.0.0/8、127.0.0.0/8、
- 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16。
- """
- try:
- addr = ipaddress.IPv4Address(ip)
- except (ipaddress.AddressValueError, ValueError):
- return False
- reserved = [
- ipaddress.ip_network("198.18.0.0/15"),
- ipaddress.ip_network("0.0.0.0/8"),
- ipaddress.ip_network("127.0.0.0/8"),
- ipaddress.ip_network("10.0.0.0/8"),
- ipaddress.ip_network("172.16.0.0/12"),
- ipaddress.ip_network("192.168.0.0/16"),
- ]
- return any(addr in net for net in reserved)
- def _join_ips(ips) -> str:
- """IP 列表转中文顿号分隔字符串。"""
- return "、".join(ips) if ips else "(无)"
- def detect_pollution(host: str) -> dict:
- """对单个域名做 DNS 污染诊断。
- Returns:
- dict: {
- "host": 域名,
- "ok": True=正常 / False=疑似污染 / None=无法判定或差异提示,
- "system_ips": 系统解析 IP 列表,
- "doh_ips": DoH 真实 IP 列表,
- "detail": 诊断说明,
- }
- """
- sys_ips = system_resolve(host)
- doh_ips = resolve_via_doh(host)
- sys_str = _join_ips(sys_ips)
- doh_str = _join_ips(doh_ips)
- # DoH 全部端点不可达 → 无法判定(不误报)
- if not doh_ips:
- return {
- "host": host, "ok": None,
- "system_ips": sys_ips, "doh_ips": [],
- "detail": "安全 DNS(DoH)查询失败,无法判定(可能离线或 DoH 服务不可达)",
- }
- # 系统解析失败 + DoH 成功 → 疑似污染
- if not sys_ips:
- return {
- "host": host, "ok": False,
- "system_ips": [], "doh_ips": doh_ips,
- "detail": "系统 DNS 解析失败,安全 DNS 真实 IP 为 " + doh_str,
- }
- overlap = set(sys_ips) & set(doh_ips)
- if overlap:
- return {
- "host": host, "ok": True,
- "system_ips": sys_ips, "doh_ips": doh_ips,
- "detail": "系统 DNS 与安全 DNS 解析一致",
- }
- # 无交集:若系统 IP 全部落在保留段 → 疑似污染;否则为多区域差异提示
- if all(_is_reserved_or_fake_ip(ip) for ip in sys_ips):
- return {
- "host": host, "ok": False,
- "system_ips": sys_ips, "doh_ips": doh_ips,
- "detail": ("系统 DNS 解析为 " + sys_str + "(保留/Fake-IP 段),"
- "安全 DNS 真实 IP 为 " + doh_str + " —— 疑似 DNS 污染"),
- }
- return {
- "host": host, "ok": None,
- "system_ips": sys_ips, "doh_ips": doh_ips,
- "detail": ("系统 DNS 解析为 " + sys_str + ",安全 DNS 为 " + doh_str
- + "(无保留段特征,可能为 CDN 多区域差异)"),
- }
- def check_hosts(hosts: list = None) -> list:
- """批量诊断一组域名(默认 GitHub 关键域名 + PyPI)。
- Args:
- hosts: 域名列表;None 时使用默认检查清单。
- Returns:
- 每个域名的 detect_pollution 结果列表。
- """
- default_hosts = [
- "github.com",
- "api.github.com",
- "raw.githubusercontent.com",
- "codeload.github.com",
- "objects.githubusercontent.com",
- "pypi.org",
- ]
- targets = hosts if hosts else default_hosts
- return [detect_pollution(h) for h in targets]
- def format_hosts(entries: list) -> str:
- """根据诊断结果生成可粘贴的 hosts 条目文本。
- Args:
- entries: check_hosts / detect_pollution 的结果列表。
- Returns:
- hosts 条目文本(每行 "IP 域名"),仅包含有真实 IP 的域名。
- """
- lines_out = []
- for e in entries:
- ips = e.get("doh_ips") or []
- host = e.get("host") or ""
- if ips:
- lines_out.append(ips[0] + " " + host)
- if not lines_out:
- return "(无可用的 hosts 建议:安全 DNS 未取得真实 IP)"
- return chr(10).join(lines_out)
- def summarize(entries: list) -> dict:
- """汇总批量诊断结果(供 check-update --json / doctor 使用)。
- Returns:
- dict: {
- "polluted": 是否存在疑似污染域名,
- "checked": 检查域名数,
- "ok_count": 正常数,
- "warn_count": 差异提示数,
- "fail_count": 疑似污染数,
- "detail": 汇总说明,
- "hosts_suggestions": hosts 条目文本,
- }
- """
- ok_count = sum(1 for e in entries if e.get("ok") is True)
- fail_count = sum(1 for e in entries if e.get("ok") is False)
- warn_count = sum(1 for e in entries if e.get("ok") is None)
- polluted = fail_count > 0
- detail_parts = []
- for e in entries:
- if e.get("ok") is False:
- detail_parts.append(e.get("host", "") + ": " + str(e.get("detail", "")))
- detail = ";".join(detail_parts) if detail_parts else "未检测到 DNS 污染"
- return {
- "polluted": polluted,
- "checked": len(entries),
- "ok_count": ok_count,
- "warn_count": warn_count,
- "fail_count": fail_count,
- "detail": detail,
- "hosts_suggestions": format_hosts(entries),
- }
- class _DoHHTTPSConnection(http.client.HTTPSConnection):
- """用 DoH 真实 IP 直连的 HTTPS 连接(TLS SNI 保持真实域名)。
- 证书校验仍针对真实域名(server_hostname=host),安全不降级:
- 连接的目标 IP 来自 DoH 真实解析,但 TLS 握手/证书校验完全等价于
- 常规 HTTPS 请求,只是绕过了被污染的系统 DNS。
- """
- def __init__(self, host, ip, timeout=None):
- super().__init__(host, timeout=timeout)
- self._doh_ip = ip
- def connect(self):
- """连接 DoH 解析出的真实 IP,TLS 握手仍使用真实域名(SNI)。"""
- sock = socket.create_connection((self._doh_ip, self.port), self.timeout)
- self.sock = self._context.wrap_socket(sock, server_hostname=self.host)
- def _http_get_via_ip(host, ip, path, timeout, headers):
- """通过指定 IP 发起 HTTPS GET(SNI/证书校验针对 host),返回 (status, data, location)。"""
- conn = _DoHHTTPSConnection(host, ip, timeout=timeout)
- try:
- conn.request("GET", path, headers=headers)
- resp = conn.getresponse()
- return resp.status, resp.read(), resp.getheader("Location")
- finally:
- conn.close()
- def download_with_doh_fallback(url, timeout=30, headers=None, max_redirects=5):
- """下载 URL 内容;常规下载失败时自动用 DoH 真实 IP + TLS SNI 直连兜底。
- Args:
- url: http(s) 下载地址。
- timeout: 单次请求超时(秒),默认 30。
- headers: 附加请求头(dict);缺省用 gongwen-skill UA。
- max_redirects: 最大跟随重定向次数(兜底路径手动处理 3xx)。
- Returns:
- bytes: 响应体。
- Raises:
- Exception: 常规与 DoH 兜底均失败时抛出(由调用方决定提示)。
- Note:
- - 常规 urllib 请求自动跟随重定向;兜底路径手动跟随并重新解析新域名。
- - 仅 https 参与 DoH 兜底(http 无 TLS,无 SNI 语义)。
- - 证书校验不降级:wrap_socket 时 server_hostname=host,等价常规 HTTPS。
- """
- if headers is None:
- headers = {"User-Agent": "gongwen-skill"}
- current = url
- for _ in range(max_redirects + 1):
- parsed = urllib.parse.urlsplit(current)
- host = parsed.hostname or ""
- is_https = parsed.scheme == "https"
- try:
- req = urllib.request.Request(current, headers=headers)
- with urllib.request.urlopen(req, timeout=timeout) as resp:
- return resp.read()
- except Exception as normal_err:
- if not is_https:
- raise
- ips = resolve_via_doh(host)
- last_err = normal_err
- redirected = False
- for ip in ips:
- try:
- status, data, location = _http_get_via_ip(
- host, ip, parsed.path or "/", timeout, headers,
- )
- except Exception as ip_err:
- last_err = ip_err
- continue
- if status in (301, 302, 303, 307, 308) and location:
- current = urllib.parse.urljoin(current, location)
- redirected = True
- break
- if 200 <= status < 300:
- return data
- if status >= 400:
- # 4xx/5xx 一般为真实错误,但不排除中间设备干扰(如 400),
- # 已尝试下一 IP;全部失败后抛出最后错误。
- last_err = OSError("HTTP " + str(status) + " via DoH IP " + ip)
- continue
- last_err = OSError("HTTP " + str(status) + " via DoH IP " + ip)
- continue
- if redirected:
- continue
- raise last_err
- raise OSError("下载重定向次数超限: " + url)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.