gongwen-skill 2.7.0 → 2.8.0

package/.dsh/skills/gongwen-skill/SKILL.md

@@ -103,6 +103,7 @@ metadata:
    ```
    - **PyPI 为权威判定渠道**（pip 包核心分发，pip install -U 即从 PyPI 拉取）；PyPI 不可达时回退 GitHub tag（备用渠道，git 用户/CI 触发源）
    - GitCode/AtomGit 与 GitHub 同源 tag，仅在 GitHub 不可达时作国内拉取镜像提示（不参与版本判定）
+   - GitHub 不可达且触发 DNS 诊断时（系统解析为保留/Fake-IP 段），`check-update --json` 会输出 `dns_diagnosis` 字段（含 `hosts_suggestions`），如实向用户转述排查建议即可
    - 若全部渠道均不可用（无 git/无网络），**必须明确告知用户"版本自检因无法访问远程而跳过"**，不得静默假设本地即最新
 3.5. **本地 git tag 对比**（P6，Agent 执行版本确认时补充）：
    - 优先对 skill 安装目录执行 git tag 对比：
@@ -925,15 +926,16 @@ python -m gongwen fix-common 文件.docx -o 成品.docx
 | `table-signs` | 从名单批量生成会议桌签 | `python -m gongwen table-signs 名单.txt -o 桌签.docx` |
 | `review` | 生成公文审稿流转单（五/三角色） | `python -m gongwen review report -o 审稿单.docx` |
 | `handoff` | 跨会话交接（长任务收尾必写） | `python -m gongwen handoff --write` |
-| `check-update` | 版本自检（PyPI pip 包权威 + GitHub 备用，自动检测安装形态） | `python -m gongwen check-update` |
-| `font` | 公文标准字体管理（安装/检查/列出） | `python -m gongwen font install` |
+| `check-update` | 版本自检（PyPI pip 包权威 + GitHub 备用，自动检测安装形态；GitHub 不可达时 DNS 诊断） | `python -m gongwen check-update` |
+| `font` | 公文标准字体管理（安装/检查/列出；下载失败时自动安全 DNS 直连兜底） | `python -m gongwen font install` |
 
 ### 🩺 诊断与修复
 
 | 命令 | 用途 | 最小用法 |
 |------|------|---------|
-| `doctor` | 全面诊断：检查 Python 版本/依赖/版本一致性/字体/DSH 文件/代码风格等 | `python -m gongwen doctor` |
+| `doctor` | 全面诊断：检查 Python 版本/依赖/版本一致性/字体/DSH 文件/代码风格/网络 DNS 等 | `python -m gongwen doctor` |
 | `doctor --json` | JSON 结构化输出（便于 Agent 解析） | `python -m gongwen doctor --json` |
+| `doctor --offline` | 跳过网络/DNS 诊断（离线模式） | `python -m gongwen doctor --offline` |
 | `repair` | 修复常见问题：安装缺失依赖/字体/同步 SKILL.md 副本 | `python -m gongwen repair` |
 
 ### ⚙️ 规则管理

package/.dsh/skills/gongwen-skill.md

@@ -103,6 +103,7 @@ metadata:
    ```
    - **PyPI 为权威判定渠道**（pip 包核心分发，pip install -U 即从 PyPI 拉取）；PyPI 不可达时回退 GitHub tag（备用渠道，git 用户/CI 触发源）
    - GitCode/AtomGit 与 GitHub 同源 tag，仅在 GitHub 不可达时作国内拉取镜像提示（不参与版本判定）
+   - GitHub 不可达且触发 DNS 诊断时（系统解析为保留/Fake-IP 段），`check-update --json` 会输出 `dns_diagnosis` 字段（含 `hosts_suggestions`），如实向用户转述排查建议即可
    - 若全部渠道均不可用（无 git/无网络），**必须明确告知用户"版本自检因无法访问远程而跳过"**，不得静默假设本地即最新
 3.5. **本地 git tag 对比**（P6，Agent 执行版本确认时补充）：
    - 优先对 skill 安装目录执行 git tag 对比：
@@ -925,15 +926,16 @@ python -m gongwen fix-common 文件.docx -o 成品.docx
 | `table-signs` | 从名单批量生成会议桌签 | `python -m gongwen table-signs 名单.txt -o 桌签.docx` |
 | `review` | 生成公文审稿流转单（五/三角色） | `python -m gongwen review report -o 审稿单.docx` |
 | `handoff` | 跨会话交接（长任务收尾必写） | `python -m gongwen handoff --write` |
-| `check-update` | 版本自检（PyPI pip 包权威 + GitHub 备用，自动检测安装形态） | `python -m gongwen check-update` |
-| `font` | 公文标准字体管理（安装/检查/列出） | `python -m gongwen font install` |
+| `check-update` | 版本自检（PyPI pip 包权威 + GitHub 备用，自动检测安装形态；GitHub 不可达时 DNS 诊断） | `python -m gongwen check-update` |
+| `font` | 公文标准字体管理（安装/检查/列出；下载失败时自动安全 DNS 直连兜底） | `python -m gongwen font install` |
 
 ### 🩺 诊断与修复
 
 | 命令 | 用途 | 最小用法 |
 |------|------|---------|
-| `doctor` | 全面诊断：检查 Python 版本/依赖/版本一致性/字体/DSH 文件/代码风格等 | `python -m gongwen doctor` |
+| `doctor` | 全面诊断：检查 Python 版本/依赖/版本一致性/字体/DSH 文件/代码风格/网络 DNS 等 | `python -m gongwen doctor` |
 | `doctor --json` | JSON 结构化输出（便于 Agent 解析） | `python -m gongwen doctor --json` |
+| `doctor --offline` | 跳过网络/DNS 诊断（离线模式） | `python -m gongwen doctor --offline` |
 | `repair` | 修复常见问题：安装缺失依赖/字体/同步 SKILL.md 副本 | `python -m gongwen repair` |
 
 ### ⚙️ 规则管理

package/CHANGELOG.md

@@ -4,6 +4,19 @@
   Licensed under the MIT License. See the LICENSE file for details.
 -->
 
+## v2.8.0 (2026-09-03)
+
+### Added
+- **DNS 污染诊断（安全 DNS / DoH）**：`check-update` 在 GitHub 渠道不可达时自动触发 DNS 污染诊断，对比系统解析与安全 DNS（DoH）真实 IP，输出污染判定、对比表与可直接粘贴的 hosts 条目建议
+- **`doctor` 新增「网络/DNS 诊断」检查项**：默认联网检测 GitHub/PyPI 关键域名是否疑似 DNS 污染（系统解析落在 198.18.0.0/15 等保留/Fake-IP 段时判定疑似污染），`--offline` 参数可完全跳过网络查询
+- **新增 `gongwen/cli/netcheck.py` 模块**：DoH 解析（内置阿里 `dns.alidns.com` / 腾讯 `doh.pub` / `1.12.12.12` / Google 备用，多端点自动降级）+ 系统解析对比 + 污染判定 + hosts 建议生成；环境变量 `GONGWEN_DOH` 可覆盖为自定义 DoH 端点
+- **`check-update --json` 输出新增 `dns_diagnosis` 字段**：含 `polluted` / `detail` / `hosts_suggestions` 等，便于 Agent 解析
+- **自动直连兜底（DNS 污染时零操作下载）**：`font install` 下载字体、`check-update`/`helpers` 查询 PyPI 常规请求失败时，自动用 DoH 真实 IP + TLS SNI 直连重试（`netcheck.download_with_doh_fallback` / `_DoHHTTPSConnection`），证书校验仍针对真实域名，安全不降级
+
+### Notes
+- 诊断只做建议，不修改 hosts、不改变版本判定逻辑；自动直连仅作为下载/查询失败的兜底路径（YAGNI）
+- DoH 查询经第三方公共 DNS 服务（阿里/腾讯），仅诊断/兜底失败时发起少量查询；可设置 `GONGWEN_DOH` 指向私有端点
+
 ## v2.7.0 (2026-09-03)
 
 ### Added

package/README.md

@@ -45,8 +45,8 @@ Licensed under the MIT License. See the LICENSE file for details.
 | 🔍 审稿生成 | `review` | 按五角色审稿机制生成审稿意见 |
 | 🧩 完整审校 | `full-review` | 修订+批注联合命令（句子级差异修订 + 分类批注） |
 | 🎨 样式学习 | `style-learn` / `style-list` | 上传标准文档学习 Run/段落/页面三级样式（字体/字号/字间距/行距/缩进/页边距），生成命名模板持久化，后续用 `optimize -t 模板名` 套用 |
-| 🔄 版本自检 | `check-update` | 版本自检（PyPI pip 包权威判定 + GitHub 备用，GitCode/AtomGit 作国内镜像提示） |
-| 🩺 自我诊断 | `doctor` / `repair` | 全面诊断 22 项（Python/依赖/版本一致性/字体/DSH 文件/DSH 技能 frontmatter/代码风格），自动修复常见问题 |
+| 🔄 版本自检 | `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 规则三层定制（官方/单位/用户） |
@@ -336,7 +336,7 @@ python -m gongwen rule-list notice
 
 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 加速方案
+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`），不得静默使用旧版本
 
@@ -356,7 +356,7 @@ DSH 采用 **Cordis 模块化微内核架构**：技能体系基于本地文件
 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.7.0
+python -m gongwen --version       # 检验：gongwen-skill v2.8.0
 ```
 
 ### 方式一：作为 DSH Skill 注册（基于本地文件系统）
@@ -412,7 +412,7 @@ pnpm add -w gongwen-skill
   "dependencies": {
     "@deepseek-ai/dsh-base": "...",
     "@deepseek-ai/dsh-web-app": "...",
-    "gongwen-skill": "^2.7.0"
+    "gongwen-skill": "^2.8.0"
   },
   "dsh": {
     "profile": {
@@ -593,7 +593,7 @@ pip install -r requirements.txt
 用户：帮我优化这份会议通知的第二章节措辞
 
 Agent：📋 合规自检报告
-Skill 版本: v2.7.0（版本自检已确认最新）
+Skill 版本: v2.8.0（版本自检已确认最新）
 路径判定: B（内容优化）
 依据: 用户指定了已有文档，且要求"优化措辞"
 命令调用: 1. python -m gongwen optimize-content 会议通知.docx --changes changes.json --apply --paragraphs "5-8"
@@ -629,6 +629,23 @@ Skill 定位为**工具层**，默认不依赖 LLM（确定性工作全自包含
 
 ---
 
+## 🌐 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.8.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

package/SKILL.md

@@ -103,6 +103,7 @@ metadata:
    ```
    - **PyPI 为权威判定渠道**（pip 包核心分发，pip install -U 即从 PyPI 拉取）；PyPI 不可达时回退 GitHub tag（备用渠道，git 用户/CI 触发源）
    - GitCode/AtomGit 与 GitHub 同源 tag，仅在 GitHub 不可达时作国内拉取镜像提示（不参与版本判定）
+   - GitHub 不可达且触发 DNS 诊断时（系统解析为保留/Fake-IP 段），`check-update --json` 会输出 `dns_diagnosis` 字段（含 `hosts_suggestions`），如实向用户转述排查建议即可
    - 若全部渠道均不可用（无 git/无网络），**必须明确告知用户"版本自检因无法访问远程而跳过"**，不得静默假设本地即最新
 3.5. **本地 git tag 对比**（P6，Agent 执行版本确认时补充）：
    - 优先对 skill 安装目录执行 git tag 对比：
@@ -925,15 +926,16 @@ python -m gongwen fix-common 文件.docx -o 成品.docx
 | `table-signs` | 从名单批量生成会议桌签 | `python -m gongwen table-signs 名单.txt -o 桌签.docx` |
 | `review` | 生成公文审稿流转单（五/三角色） | `python -m gongwen review report -o 审稿单.docx` |
 | `handoff` | 跨会话交接（长任务收尾必写） | `python -m gongwen handoff --write` |
-| `check-update` | 版本自检（PyPI pip 包权威 + GitHub 备用，自动检测安装形态） | `python -m gongwen check-update` |
-| `font` | 公文标准字体管理（安装/检查/列出） | `python -m gongwen font install` |
+| `check-update` | 版本自检（PyPI pip 包权威 + GitHub 备用，自动检测安装形态；GitHub 不可达时 DNS 诊断） | `python -m gongwen check-update` |
+| `font` | 公文标准字体管理（安装/检查/列出；下载失败时自动安全 DNS 直连兜底） | `python -m gongwen font install` |
 
 ### 🩺 诊断与修复
 
 | 命令 | 用途 | 最小用法 |
 |------|------|---------|
-| `doctor` | 全面诊断：检查 Python 版本/依赖/版本一致性/字体/DSH 文件/代码风格等 | `python -m gongwen doctor` |
+| `doctor` | 全面诊断：检查 Python 版本/依赖/版本一致性/字体/DSH 文件/代码风格/网络 DNS 等 | `python -m gongwen doctor` |
 | `doctor --json` | JSON 结构化输出（便于 Agent 解析） | `python -m gongwen doctor --json` |
+| `doctor --offline` | 跳过网络/DNS 诊断（离线模式） | `python -m gongwen doctor --offline` |
 | `repair` | 修复常见问题：安装缺失依赖/字体/同步 SKILL.md 副本 | `python -m gongwen repair` |
 
 ### ⚙️ 规则管理

package/dsh/index.js

@@ -1,4 +1,4 @@
-// 公文全流程处理工具 - DSH plugin bridge (gongwen-skill, v2.7.0+)
+// 公文全流程处理工具 - DSH plugin bridge (gongwen-skill, v2.8.0+)
 // (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.

package/gongwen/__init__.py

@@ -7,7 +7,7 @@
 #
 # 公文全流程处理工具 - gongwen-skill Python package
 
-__version__ = "2.7.0"
+__version__ = "2.8.0"
 
 # Re-export everything from the legacy module for backward compatibility
 # This allows: from gongwen import main, cmd_check, etc.

package/gongwen/_legacy.py

@@ -52,7 +52,7 @@ from engine.core.document.font_utils import (
     PAGE_NUMBER_FONT,
     PAGE_NUMBER_SIZE_PT,
 )
-__version__ = "2.7.0"
+__version__ = "2.8.0"
 # 版本号应与 gongwen/__init__.py 保持一致，每次发版同步更新
 """
 中文公文全流程处理工具 —— 基于 GB/T 9704《党政机关公文格式》国家标准。
@@ -1120,9 +1120,11 @@ def main():
     p.set_defaults(func=cmd_font)
 
     # ---- 自我诊断与修复 ----
-    p = sub.add_parser("doctor", help="全面诊断：检查 Python 版本/依赖/版本一致性/字体/DSH 文件/代码风格等")
+    p = sub.add_parser("doctor", help="全面诊断：检查 Python 版本/依赖/版本一致性/字体/DSH 文件/代码风格/网络 DNS 等")
     p.add_argument("--json", action="store_true",
                    help="输出 JSON 格式结果（便于 Agent 解析）")
+    p.add_argument("--offline", action="store_true",
+                   help="跳过网络/DNS 诊断（离线模式）")
     p.set_defaults(func=cmd_doctor)
 
     p = sub.add_parser("repair", help="修复常见问题：安装缺失依赖/字体/同步 SKILL.md 副本")

package/gongwen/cli/doctor_cmds.py

@@ -548,7 +548,57 @@ def _check_npm_package() -> dict:
         }
 
 
-def _run_all_checks() -> dict:
+def _check_network_dns(offline: bool = False) -> dict:
+    """网络与 DNS 诊断：检测 GitHub/PyPI 域名是否疑似 DNS 污染。
+
+    原理：系统 DNS 常被污染（返回 198.18.0.0/15 等保留段 Fake-IP），
+    通过安全 DNS（DoH）查询真实 IP 对比，判定是否疑似污染，
+    并给出 hosts 建议（v2.8.0 规格）。
+    --offline 时跳过网络查询（WARN）。
+    """
+    if offline:
+        return {
+            "name": "网络/DNS 诊断",
+            "ok": None,
+            "detail": "已跳过（--offline 离线模式）",
+            "hint": None,
+        }
+    try:
+        from gongwen.cli import netcheck
+        entries = netcheck.check_hosts()
+        s = netcheck.summarize(entries)
+        if s.get("polluted"):
+            return {
+                "name": "网络/DNS 诊断",
+                "ok": False,
+                "detail": s.get("detail", ""),
+                "hint": ("疑似 DNS 污染（系统解析为保留/Fake-IP 段）。"
+                         "可参考安全 DNS（DoH）方案，或使用国内镜像；"
+                         "hosts 建议： " + s.get("hosts_suggestions", "")),
+            }
+        if s.get("checked") and s.get("ok_count") == s.get("checked"):
+            return {
+                "name": "网络/DNS 诊断",
+                "ok": True,
+                "detail": "GitHub/PyPI 域名解析正常（与安全 DNS 一致）",
+                "hint": None,
+            }
+        return {
+            "name": "网络/DNS 诊断",
+            "ok": None,
+            "detail": s.get("detail", "") or "部分域名解析存在差异",
+            "hint": "部分域名解析与安全 DNS 不一致，建议进一步排查",
+        }
+    except Exception as e:
+        return {
+            "name": "网络/DNS 诊断",
+            "ok": None,
+            "detail": "诊断失败: " + str(e)[:100],
+            "hint": None,
+        }
+
+
+def _run_all_checks(offline: bool = False) -> dict:
     """运行所有检查，返回结构化报告。"""
     t0 = time.time()
 
@@ -584,6 +634,7 @@ def _run_all_checks() -> dict:
     add(_check_git_status())
     add(_check_pycodestyle())
     add(_check_npm_package())
+    add(_check_network_dns(offline))
 
     report["elapsed_seconds"] = round(time.time() - t0, 1)
     return report
@@ -596,7 +647,8 @@ def cmd_doctor(args):
     但实际文件残缺。本命令逐一检查每个组件，不依赖"看起来正常"的状态。
     """
     use_json = getattr(args, "json", False)
-    report = _run_all_checks()
+    offline = getattr(args, "offline", False)
+    report = _run_all_checks(offline=offline)
 
     if use_json:
         print(json.dumps(report, ensure_ascii=False, indent=2))

package/gongwen/cli/font_cmds.py

@@ -35,7 +35,11 @@ def _get_fonts_dir() -> Path:
 
 
 def _download_font(ttf_file: str, dest: Path) -> bool:
-    """从 GitHub 下载字体文件到 dest，返回是否成功。"""
+    """从 GitHub 下载字体文件到 dest，返回是否成功。
+
+    常规下载失败（如 DNS 污染）时自动用安全 DNS（DoH）真实 IP + TLS SNI
+    直连兜底，用户零操作（证书校验不降级，仍针对真实域名）。
+    """
     import urllib.request
     import urllib.error
     from urllib.parse import quote
@@ -46,17 +50,24 @@ def _download_font(ttf_file: str, dest: Path) -> bool:
         req = urllib.request.Request(url, headers={"User-Agent": "gongwen-skill"})
         with urllib.request.urlopen(req, timeout=60) as resp:
             data = resp.read()
-        # SEC-V168-03 修复：完整性校验——字体文件应 >1MB
-        if len(data) < 1_000_000:
-            print(f"  ❌ 下载文件过小 ({len(data)} bytes)，可能不完整")
-            return False
-        dest.parent.mkdir(parents=True, exist_ok=True)
-        dest.write_bytes(data)
-        print(f"  📦 已下载: {dest} ({len(data) / 1024:.0f}KB)")
-        return True
     except Exception as e:
-        print(f"  ❌ 下载失败: {e}")
+        # DNS 污染兜底：常规下载失败时改用安全 DNS 真实 IP 直连
+        try:
+            print(f"  ⚠️  常规下载失败: {str(e)[:120]}")
+            print("  🔄 尝试安全 DNS（DoH）真实 IP 直连下载 ...")
+            from gongwen.cli import netcheck as gwnet
+            data = gwnet.download_with_doh_fallback(url, timeout=60)
+        except Exception as e2:
+            print(f"  ❌ 下载失败: {str(e2)[:120]}")
+            return False
+    # SEC-V168-03 修复：完整性校验——字体文件应 >1MB
+    if len(data) < 1_000_000:
+        print(f"  ❌ 下载文件过小 ({len(data)} bytes)，可能不完整")
         return False
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_bytes(data)
+    print(f"  📦 已下载: {dest} ({len(data) / 1024:.0f}KB)")
+    return True
 
 
 def _ensure_font_file(ttf_file: str, fonts_dir: Path) -> Path | None:

package/gongwen/cli/helpers.py

@@ -188,18 +188,31 @@ def verify_output_fresh(output_path: Path, start_time: float, label: str = "输
         return False
 
 
+def _parse_pypi_version(data: dict) -> str:
+    """从 PyPI JSON 响应提取版本号（自动补 v 前缀）。"""
+    version = data.get("info", {}).get("version", "")
+    if version and not version.startswith("v"):
+        version = "v" + version
+    return version
+
+
 def latest_version_from_pypi(timeout: int = 10) -> tuple[bool, str]:
-    """从 PyPI JSON API 查询最新发布版本。"""
+    """从 PyPI JSON API 查询最新发布版本。
+
+    DNS 污染兜底：常规请求失败时自动用安全 DNS（DoH）真实 IP + TLS SNI
+    直连重试（PyPI 域名也可能被污染），用户零操作。
+    """
     import urllib.request
     try:
         req = urllib.request.Request(PYPI_API, headers={"Accept": "application/json"})
         with urllib.request.urlopen(req, timeout=timeout) as resp:
             data = json.loads(resp.read().decode("utf-8"))
-        version = data.get("info", {}).get("version", "")
-        if version:
-            if not version.startswith("v"):
-                version = f"v{version}"
-            return True, version
-        return False, "PyPI API 返回无版本号"
+        return True, _parse_pypi_version(data)
     except Exception as e:
-        return False, str(e)[:120]
+        try:
+            from gongwen.cli import netcheck as gwnet
+            raw = gwnet.download_with_doh_fallback(PYPI_API, timeout=timeout)
+            data = json.loads(raw.decode("utf-8"))
+            return True, _parse_pypi_version(data)
+        except Exception as e2:
+            return False, str(e2 or e)[:120]

package/gongwen/cli/netcheck.py

@@ -0,0 +1,362 @@
+#!/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 直连）
+    "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)

package/gongwen/cli/update_cmds.py

@@ -160,12 +160,32 @@ def cmd_check_update(args):
                 if not use_json:
                     print(f"  ⚠️  {name:<8} 不可达: {val}")
 
-    # GitHub 海外渠道不可达时，给出国内加速指引（EasyTier 式加速代理 + GitHub520 hosts）
-    if not use_json and results.get("GitHub", "") == "" and ok_count > 0:
-        print("  💡 国内访问 GitHub 常超时，可用国内代码镜像：")
-        for _name, _url in _GIT_MIRRORS.items():
-            print(f"     - {_name}: {_url}")
-        print("     或参考 GitHub520 hosts 加速方案：https://github.com/521xueweihan/GitHub520")
+    # GitHub 海外渠道不可达时，给出国内加速指引 + DNS 污染诊断（安全 DNS / DoH）
+    dns_diag = None
+    github_unreachable = results.get("GitHub", "") == "" and ok_count > 0
+    if github_unreachable:
+        from gongwen.cli import netcheck as _netcheck
+        _dns_entries = _netcheck.check_hosts(
+            ["github.com", "api.github.com", "raw.githubusercontent.com"]
+        )
+        dns_diag = _netcheck.summarize(_dns_entries)
+        if not use_json:
+            print("  💡 国内访问 GitHub 常超时，可用国内代码镜像：")
+            for _name, _url in _GIT_MIRRORS.items():
+                print(f"     - {_name}: {_url}")
+            print("     或参考 GitHub520 hosts 加速方案：https://github.com/521xueweihan/GitHub520")
+            if dns_diag.get("polluted"):
+                print("  🔬 DNS 诊断：检测到疑似 DNS 污染（系统解析为保留/Fake-IP 段）")
+                for _e in _dns_entries:
+                    _mark = ("疑似污染" if _e.get("ok") is False
+                             else "正常" if _e.get("ok") is True else "差异提示")
+                    _sys = "、".join(_e.get("system_ips") or []) or "解析失败"
+                    _doh = "、".join(_e.get("doh_ips") or []) or "（无）"
+                    _host = _e.get("host", "")
+                    print(f"     - {_host}: 系统 {_sys} → 安全DNS {_doh}（{_mark}）")
+                print("  📝 hosts 建议（管理员权限写入 hosts 文件）：")
+                for _line in dns_diag.get("hosts_suggestions", "").splitlines():
+                    print(f"     {_line}")
 
     if not use_json:
         print(f"{'─' * 50}")
@@ -217,6 +237,7 @@ def cmd_check_update(args):
             "install_type": _detect_install_type(),
             "reachable_channels": ok_count,
             "elapsed_seconds": round(time.time() - t0, 1),
+            "dns_diagnosis": dns_diag,
         }
         print(_json.dumps(output, ensure_ascii=False, indent=2))
         return 0 if not has_update else 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gongwen-skill",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "公文全流程处理工具 - GB/T 9704 格式检查/修复/内容优化/模板生成/版式注入",
   "type": "module",
   "main": "dsh/index.js",

package/prompts/usage-prompts.md

@@ -201,7 +201,7 @@ python -m gongwen optimize 文件.docx -o 优化版.docx
 **Agent 响应**：
 ```
 📋 合规自检报告
-Skill 版本: v2.7.0
+Skill 版本: v2.8.0
 路径判定: B（内容优化）
 依据: 用户提供纯文本+优化要求，无已有文档
 命令调用: 将原文保存为临时文件后执行 optimize-content --apply --paragraphs "1-3"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gongwen-skill"
-version = "2.7.0"
+version = "2.8.0"
 description = "公文全流程处理工具 - GB/T 9704 格式检查/修复/内容优化/模板生成/版式注入"
 readme = "README.md"
 license = {text = "MIT"}