gongwen-skill 2.2.0 → 2.3.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@
   Licensed under the MIT License. See the LICENSE file for details.
 -->
 
+## v2.3.0 (2026-08-31)
+
+### Added
+- **doctor 自检新增「DSH 技能 frontmatter」检查项**（21 项 → 22 项）：按 DSH 最新技能规范校验 SKILL.md frontmatter——`name` 必填且为 kebab-case、与 `.dsh/skills/<name>` 目录/文件名一致；`description` 必填非空且足够自描述（模型在会话目录只能看到它）；`whenToUse` 建议存在；`user-invocable`/`disable-model-invocation` 若存在必须为布尔值；frontmatter 必须 `---` 包裹且 YAML 可解析
+
+### Changed
+- **技能名动态化**：新增 `_get_skill_name()` 从 SKILL.md frontmatter 读取技能名，`_check_skill_sync`/`cmd_repair` 不再硬编码 `gongwen-skill`，技能改名后检查与修复仍准确
+- **纯 pip 环境不再误报**：frontmatter 目录一致性校验仅在 `.dsh/skills` 存在时执行（非 DSH 环境跳过）
+
+### Fixed
+- **SKILL.md 编码读取修复**：读取编码 `utf-8` → `utf-8-sig`（自动剥离 BOM，兼容带/无 BOM）；修复 Windows 下默认 locale 编码（cp936/GBK）读 UTF-8 无 BOM 的 SKILL.md 抛 `UnicodeDecodeError` 的隐患
+
 ## v2.2.0 (2026-08-28)
 
 ### Added

package/README.md

@@ -46,7 +46,7 @@ Licensed under the MIT License. See the LICENSE file for details.
 | 🧩 完整审校 | `full-review` | 修订+批注联合命令（句子级差异修订 + 分类批注） |
 | 🎨 样式学习 | `style-learn` / `style-list` | 上传标准文档学习 Run/段落/页面三级样式（字体/字号/字间距/行距/缩进/页边距），生成命名模板持久化，后续用 `optimize -t 模板名` 套用 |
 | 🔄 版本自检 | `check-update` | 多渠道版本自检（GitHub/GitCode/AtomGit 三仓库比对取最新） |
-| 🩺 自我诊断 | `doctor` / `repair` | 全面诊断 21 项（Python/依赖/版本一致性/字体/DSH 文件/代码风格），自动修复常见问题 |
+| 🩺 自我诊断 | `doctor` / `repair` | 全面诊断 22 项（Python/依赖/版本一致性/字体/DSH 文件/DSH 技能 frontmatter/代码风格），自动修复常见问题 |
 | 🕵️ 文档审计 | `audit` | 检查删除线/加粗/AI 声明等痕迹 |
 | 🤝 会话交接 | `handoff` | 跨会话上下文传递（`--list` / `--latest` / Agent 长任务收尾必写） |
 | ⚙️ 规则管理 | `rule-export/import/list` | YAML 规则三层定制（官方/单位/用户） |
@@ -337,7 +337,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.2.0
+python -m gongwen --version       # 检验：gongwen-skill v2.3.0
 ```
 
 ### 方式一：作为 DSH Skill 注册（基于本地文件系统）
@@ -393,7 +393,7 @@ pnpm add -w gongwen-skill
   "dependencies": {
     "@deepseek-ai/dsh-base": "...",
     "@deepseek-ai/dsh-web-app": "...",
-    "gongwen-skill": "^2.2.0"
+    "gongwen-skill": "^2.3.0"
   },
   "dsh": {
     "profile": {
@@ -448,9 +448,9 @@ dsh --profile web
 | CLI 独立可执行（`python -m gongwen <命令>`） | ✅ |
 | PyPI 上架（`pip install gongwen-skill`） | ✅ |
 | 零外部运行时依赖（仅 python-docx/pydantic/pyyaml） | ✅ |
-| DSH 配置化排版参数（页边距/行距/字体/默认模板版本） | ✅ v2.2.0+ |
+| DSH 配置化排版参数（页边距/行距/字体/默认模板版本） | ✅ v2.3.0+ |
 
-### DSH 插件配置化（v2.2.0+）
+### DSH 插件配置化（v2.3.0+）
 
 DSH 插件支持通过配置文件管理排版参数，Agent 调用时自动注入，纯 CLI 用户不受影响。
 
@@ -574,7 +574,7 @@ pip install -r requirements.txt
 用户：帮我优化这份会议通知的第二章节措辞
 
 Agent：📋 合规自检报告
-Skill 版本: v2.2.0（多渠道自检已确认最新）
+Skill 版本: v2.3.0（多渠道自检已确认最新）
 路径判定: B（内容优化）
 依据: 用户指定了已有文档，且要求"优化措辞"
 命令调用: 1. python -m gongwen optimize-content 会议通知.docx --changes changes.json --apply --paragraphs "5-8"

package/dsh/index.js

@@ -1,4 +1,4 @@
-// 公文全流程处理工具 - DSH plugin bridge (gongwen-skill, v2.2.0+)
+// 公文全流程处理工具 - DSH plugin bridge (gongwen-skill, v2.3.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.
@@ -30,7 +30,7 @@ const CONFIG_FILE = join(APP_DATA_DIR, "dsh-config.json");
 const DEFAULTS_FILE = join(resolve(__dirname, ".."), "etc", "dsh-config-defaults.json");
 
 // AI 工作指引
-const GONGWEN_GUIDANCE = `本机已安装公文全流程处理工具插件（gongwen-skill）。能力：.docx 公文全流程——列出公文类型（list-types）、解析文档（parse）、格式检查（check）、自动修复（optimize）、内容修订对比版（optimize-content）、模板生成（template）、样式学习（style-learn/style-list，从标准文档学习排版样式）、全面诊断（doctor，21 项自检）、自动修复（repair）、Markdown 转公文（md2docx）、JSON 模型生成（generate）、版头/版记/页码注入（header/footer/pagenum）、首句加粗（bold-first）、一键格式修复（fix-common）、桌签生成（table-signs）、审稿流转单（review）、完整审校（full-review）、文档审计（audit）、规则管理（rule-export/import/list）、版本自检（check-update）、会话交接（handoff）、字体管理（font）。覆盖通知/请示/报告/函/会议纪要等 24 类公文。完全自包含，克隆即用，无需数据库或后端服务。用户提到「公文 / 红头文件 / 版式 / 排版 / 格式检查 / 公文模板 / 样式学习 / 自定义模板 / 党政机关公文」时即指本插件。DSH 插件支持配置化排版参数（页边距/行距/字体等），配置文件位于 ~/.gongwen-skill/dsh-config.json，可通过 config 命令或 DSH 系统设置→插件配置管理。`;
+const GONGWEN_GUIDANCE = `本机已安装公文全流程处理工具插件（gongwen-skill）。能力：.docx 公文全流程——列出公文类型（list-types）、解析文档（parse）、格式检查（check）、自动修复（optimize）、内容修订对比版（optimize-content）、模板生成（template）、样式学习（style-learn/style-list，从标准文档学习排版样式）、全面诊断（doctor，22 项自检）、自动修复（repair）、Markdown 转公文（md2docx）、JSON 模型生成（generate）、版头/版记/页码注入（header/footer/pagenum）、首句加粗（bold-first）、一键格式修复（fix-common）、桌签生成（table-signs）、审稿流转单（review）、完整审校（full-review）、文档审计（audit）、规则管理（rule-export/import/list）、版本自检（check-update）、会话交接（handoff）、字体管理（font）。覆盖通知/请示/报告/函/会议纪要等 24 类公文。完全自包含，克隆即用，无需数据库或后端服务。用户提到「公文 / 红头文件 / 版式 / 排版 / 格式检查 / 公文模板 / 样式学习 / 自定义模板 / 党政机关公文」时即指本插件。DSH 插件支持配置化排版参数（页边距/行距/字体等），配置文件位于 ~/.gongwen-skill/dsh-config.json，可通过 config 命令或 DSH 系统设置→插件配置管理。`;
 
 // Web API 路由前缀
 const API_PREFIX = "/plugins/gongwen-skill/api";

package/gongwen/__init__.py

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

package/gongwen/_legacy.py

@@ -45,7 +45,7 @@ from gongwen.cli.helpers import (
     parse_config_overrides as _parse_config_overrides,
     load_rules_with_overrides as _load_rules_with_overrides,
 )
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 # 版本号应与 gongwen/__init__.py 保持一致，每次发版同步更新
 """
 中文公文全流程处理工具 —— 基于 GB/T 9704《党政机关公文格式》国家标准。

package/gongwen/cli/doctor_cmds.py

@@ -162,11 +162,45 @@ def _check_fonts() -> dict:
     }
 
 
+def _get_skill_name() -> str:
+    """从 SKILL.md frontmatter 读取技能名（DSH 规范：name 即目录名）。
+
+    供 _check_skill_sync / _check_skill_frontmatter / cmd_repair 共用，
+    避免硬编码技能名导致改名后检查失准。无法解析时返回空串。
+    """
+    skill_path = _PROJECT_ROOT / "SKILL.md"
+    try:
+        # P2-29：utf-8-sig 自动剥离 BOM，兼容带 BOM/无 BOM 的 UTF-8；
+        # 若用默认编码（Windows 下 cp936/GBK）读 UTF-8 无 BOM 文件会抛 UnicodeDecodeError
+        text = skill_path.read_text(encoding="utf-8-sig")
+        if not text.startswith("---"):
+            return ""
+        end = text.index("\n---", 4)
+        fm_text = text[4:end]
+    except Exception:
+        return ""
+    try:
+        import yaml
+        fm = yaml.safe_load(fm_text) or {}
+        name = fm.get("name")
+        return str(name).strip() if name else ""
+    except Exception:
+        # 回退：简单键值解析
+        for line in fm_text.splitlines():
+            line = line.strip()
+            if line.startswith("name:"):
+                return line.split(":", 1)[1].strip()
+        return ""
+
+
 def _check_skill_sync() -> dict:
     """检查 .dsh/skills/ 中的 SKILL.md 副本是否与根目录一致。"""
     root_skill = _PROJECT_ROOT / "SKILL.md"
-    dsh_skill = _PROJECT_ROOT / ".dsh" / "skills" / "gongwen-skill.md"
-    dsh_skill2 = _PROJECT_ROOT / ".dsh" / "skills" / "gongwen-skill" / "SKILL.md"
+    # P2-26：技能名从 frontmatter 动态读取（DSH 规范 name 即目录名），
+    # 避免硬编码 gongwen-skill 导致改名后同步检查失准；SKILL.md 缺失时回退默认名
+    skill_name = _get_skill_name() or "gongwen-skill"
+    dsh_skill = _PROJECT_ROOT / ".dsh" / "skills" / f"{skill_name}.md"
+    dsh_skill2 = _PROJECT_ROOT / ".dsh" / "skills" / skill_name / "SKILL.md"
 
     if not root_skill.exists():
         return {
@@ -205,6 +239,122 @@ def _check_skill_sync() -> dict:
     }
 
 
+def _check_skill_frontmatter() -> dict:
+    """（P2-25）检查 SKILL.md frontmatter 是否符合 DSH 技能规范。
+
+    依据 DSH 最新技能编写规范（writing-skills）：
+      - name 必须存在、为 kebab-case、且与技能目录名一致
+      - description 必须存在、非空，是模型在会话目录中看到的唯一自描述
+      - whenToUse 建议存在（触发条件，便于模型匹配）
+      - user-invocable / disable-model-invocation 若存在必须为布尔值
+    frontmatter 必须以 --- 包裹且可被 YAML 解析。
+    """
+    import re as _re
+
+    skill_path = _PROJECT_ROOT / "SKILL.md"
+    if not skill_path.exists():
+        return {
+            "name": "DSH 技能 frontmatter",
+            "ok": False,
+            "detail": "根目录 SKILL.md 不存在",
+            "hint": "项目文件不完整",
+        }
+
+    # P2-29：utf-8-sig 自动剥离 BOM，兼容带 BOM/无 BOM 的 UTF-8；
+    # 若用默认编码（Windows 下 cp936/GBK）读 UTF-8 无 BOM 文件会抛 UnicodeDecodeError
+    text = skill_path.read_text(encoding="utf-8-sig")
+    if not text.startswith("---"):
+        return {
+            "name": "DSH 技能 frontmatter",
+            "ok": False,
+            "detail": "缺少 frontmatter（内容未以 --- 开头）",
+            "hint": "为 SKILL.md 添加 --- 包裹的 frontmatter",
+        }
+
+    # 解析 frontmatter（用 pyyaml 若可用，否则回退简单键值解析）
+    fm = None
+    try:
+        end = text.index("\n---", 4)
+        fm_text = text[4:end]
+    except ValueError:
+        fm_text = None
+
+    parse_ok = False
+    error_detail = ""
+    if fm_text is not None:
+        try:
+            import yaml
+            fm = yaml.safe_load(fm_text) or {}
+            parse_ok = isinstance(fm, dict)
+        except Exception as e:
+            error_detail = f"{str(e)[:80]}"
+            # 回退：简单键值解析
+            kv = {}
+            for line in fm_text.splitlines():
+                line = line.strip()
+                if line and ":" in line and not line.startswith("#"):
+                    k, v = line.split(":", 1)
+                    kv[k.strip()] = v.strip()
+            if kv:
+                fm = kv
+                parse_ok = True
+
+    if not parse_ok:
+        return {
+            "name": "DSH 技能 frontmatter",
+            "ok": False,
+            "detail": f"frontmatter 未找到或解析失败（{error_detail or '缺少 --- 闭合'}）",
+            "hint": "修正 SKILL.md 的 frontmatter YAML",
+        }
+
+    problems = []
+
+    # 1. name：存在、kebab-case
+    name = fm.get("name")
+    if not name:
+        problems.append("缺少 name 字段")
+    else:
+        if not _re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", str(name)):
+            problems.append(f"name '{name}' 不是 kebab-case")
+        # 与技能目录名一致（.dsh/skills/<name>/ 或 .dsh/skills/<name>.md）
+        # P2-27：仅当 .dsh/skills 目录存在时才校验，纯 pip 安装（非 DSH 环境）
+        # 不携带 .dsh/skills，不应误报目录缺失
+        dsh_skills = _PROJECT_ROOT / ".dsh" / "skills"
+        if dsh_skills.is_dir():
+            dir_candidates = [
+                str(dsh_skills / str(name)),
+                str(dsh_skills / f"{name}.md"),
+            ]
+            if not any(Path(c).exists() for c in dir_candidates):
+                problems.append(f"name '{name}' 与 .dsh/skills 下无对应目录/文件")
+
+    # 2. description：存在、非空、自描述
+    desc = fm.get("description")
+    if not desc or not str(desc).strip():
+        problems.append("description 为空（模型只能看到 description，必须自描述）")
+    elif len(str(desc)) < 30:
+        problems.append(f"description 过短（{len(str(desc))} 字），应完整自描述触发条件与能力")
+
+    # 3. whenToUse：建议存在
+    when = fm.get("whenToUse")
+    if not when or not str(when).strip():
+        problems.append("缺少 whenToUse（建议写明触发场景便于模型匹配）")
+
+    # 4. 可选布尔字段类型
+    for key in ("user-invocable", "disable-model-invocation"):
+        if key in fm and not isinstance(fm[key], bool):
+            problems.append(f"{key} 应为布尔值（true/false）")
+
+    ok = not problems
+    detail = f"name={fm.get('name', '?')}, description={len(str(fm.get('description', '')))} 字"
+    return {
+        "name": "DSH 技能 frontmatter",
+        "ok": ok,
+        "detail": detail if ok else "; ".join(problems),
+        "hint": None if ok else "对照 DSH 技能规范修正 SKILL.md frontmatter",
+    }
+
+
 def _check_required_dirs() -> list[dict]:
     """检查必需目录是否存在。"""
     results = []
@@ -430,6 +580,7 @@ def _run_all_checks() -> dict:
     for file_result in _check_dsh_plugin_files():
         add(file_result)
     add(_check_skill_sync())
+    add(_check_skill_frontmatter())
     add(_check_git_status())
     add(_check_pycodestyle())
     add(_check_npm_package())
@@ -562,9 +713,11 @@ def cmd_repair(args):
     total += 1
     print(f"[{total}] 同步 SKILL.md 到 .dsh/skills/...")
     root_skill = _PROJECT_ROOT / "SKILL.md"
+    # P2-28：技能名从 frontmatter 动态读取，与 doctor 检查保持一致
+    repair_skill_name = _get_skill_name() or "gongwen-skill"
     dsh_targets = [
-        _PROJECT_ROOT / ".dsh" / "skills" / "gongwen-skill.md",
-        _PROJECT_ROOT / ".dsh" / "skills" / "gongwen-skill" / "SKILL.md",
+        _PROJECT_ROOT / ".dsh" / "skills" / f"{repair_skill_name}.md",
+        _PROJECT_ROOT / ".dsh" / "skills" / repair_skill_name / "SKILL.md",
     ]
 
     if not root_skill.exists():

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gongwen-skill",
-  "version": "2.2.0",
+  "version": "2.3.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.2.0
+Skill 版本: v2.3.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.2.0"
+version = "2.3.0"
 description = "公文全流程处理工具 - GB/T 9704 格式检查/修复/内容优化/模板生成/版式注入"
 readme = "README.md"
 license = {text = "MIT"}