dsh-plugin-windows-guard 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+## [0.2.1] - 2026-08-29
+
+- 文档：首屏前置「255 个真实会话」钩子；安装节改为单行 dsh plugin add 命令并去掉作者本机绝对路径；新增「装完你会看到什么」与徽章行；
+- 元数据：keywords 补长尾词（mojibake/write-guard 等，15 → 20）；
+- 新增英文版 README.en.md 与双语切换行。
+## [0.2.0] - 2026-08-29
+
+- **合并 `dsh-plugin-pwsh-guard` 全部主动防护能力（该插件同日删除，本插件为唯一后继）**：
+  - L2 `tools/post-execute`：pwsh 工具结果出现 GBK 误解码 / U+FFFD 洪水 / ASCII 化
+    乱码时，自动附加 `[windows-guard]` 修复提示（不中断、不改写结果本体）；
+  - L3 `tools/pre-execute`：拦截「无 `-Encoding` 的 `Set-Content`/`Add-Content`/
+    `Out-File` 写 JSON/YAML/TOML/GD」与「`>` 重定向写结构化文件」，deny 并给出
+    `WriteAllText` 正确写法；
+  - L4 新工具 `windows_encode_detect` / `windows_encode_fix`（原 `ps_encode_*`
+    更名，遵循「主题_动词」工具命名规范）：编码诊断（BOM/UTF-8/GBK/UTF-16 +
+    置信度）与修复（→ UTF-8 无 BOM，备份 `<path>.windowsguard.bak`，支持 dryRun）。
+- 原 pwsh-guard 的 L1 系统提示词段**不再注入**——由 0.1.0 的守则技能取代
+  （按需加载、更省常驻 token）。
+- 配置开关（cordis.patch.yml，默认全开）：`enabled` / `postCheck` / `preCheck` /
+  `detectTools`；`enabled: false` 时退化为 0.1.0 的纯守则形态。
+- `inject` 从 `['skills']` 扩为 `['skills', 'tools']`；版本 0.1.0 → 0.2.0。
+
+## [0.1.0] - 2026-08-25
+
+- 首发 `dsh-plugin-windows-guard`：Windows 环境防坑守则 skill 插件（纯数据）。
+- 内容来源：本机 255 个会话归档问题扫描（GBK 误解码 / BOM / UTF-16 /
+  单引号转义 / 长路径 / EACCES / 端口占用 / stderr 误判 / 乱码当答案）。
+- 按触发场景拆为两个技能：
+  - `windows-enc`：编码与 PowerShell 解析守则（读/写文件、引号转义、乱码三不）；
+  - `windows-sys`：系统环境守则（路径/文件占用、进程与端口、跨平台杂项）。
+- 纯技能载体：`lib/index.js` 约 40 行注册代码；零运行时依赖、零构建。

package/README.en.md

@@ -0,0 +1,178 @@
+[中文](./README.md) | **English**
+
+# dsh-plugin-windows-guard
+
+The DeepSeek Harness (dsh) **Windows pitfall-guard plugin** — **high-frequency
+pitfalls distilled from 255 real session archives**, with two capability
+layers: guidelines (skills) + proactive protection (hooks/tools):
+
+- **Guideline layer** (since 0.1.0): two self-contained skills auto-loaded by
+  scenario — preventive rules for "getting it right the first time";
+- **Proactive protection layer** (since 0.2.0, merged from
+  `dsh-plugin-pwsh-guard`, which has since been deleted): automatic mojibake
+  detection hints for pwsh results, dangerous write-command interception, and
+  encoding diagnosis/repair tools.
+
+Zero runtime dependencies, zero build.
+
+## Features
+
+### Guideline layer: two auto-loaded skills
+
+Split into two self-contained skills by trigger scenario (the
+`<available_skills>` catalog auto-loads the body when the description
+matches):
+
+### `windows-enc` — Encoding and PowerShell parsing (command/file-content errors)
+
+| Section | Content | Source incidents (historical records) |
+|---|---|---|
+| 1 Environment fact card | pwsh 5.1/7 differences, `-Command` as a single argv with no shell escaping layer, OutputEncoding pinned, exit codes are authoritative | stderr misjudgment (git red progress, NativeCommandError) |
+| 2 Three encoding iron rules | always read with `-Encoding UTF8`; write structured files with `WriteAllText(UTF8Encoding($false))`; BOM check / transcoding command templates | GBK misdecoding (`鎻掍欢`/`鈥?`), BOM corrupting package.json (startup incident #2), UTF-16 corruption |
+| 3 Quoting and escaping quick reference | PS `''` escaping (backslash doesn't work), double-quote interpolation, `node -e`/`python -c` quoting hell → write a temp file | `SyntaxError: unterminated string literal`, quoting-nesting failures confirmed in testing |
+| 4 Three mojibake "don'ts" | mojibake signature table (`鈥?`/`??OK??`/`\uFFFD`) + don't guess / don't quote it / re-read first | `??OK??`, `??? skill ????` mojibake treated as the answer |
+
+### `windows-sys` — System environment (troubleshooting)
+
+| Section | Content | Source incidents |
+|---|---|---|
+| 1 Paths and filesystem | MAX_PATH/long paths, paths with spaces, EACCES/EBUSY file locks, junctions and `link:` realpath, path formats | `EACCES: realpath '...sock'`, deeply nested npm-cache paths |
+| 2 Processes and ports | `netstat` port lookup, `Stop-Process`/`taskkill`, check before kill | port 3080/39090 conflicts, orphan processes |
+| 3 Cross-platform misc | CRLF traps, `.cmd` script host/ExecutionPolicy, time zones, case sensitivity | novel-file CRLF checks, run.bat chcp 65001 |
+
+### Proactive protection layer (since 0.2.0, every layer switchable, all on by default)
+
+| Layer | Mechanism | Effect |
+|---|---|---|
+| L2 | `tools/post-execute` listener | when a `pwsh` tool result shows GBK misdecoding / an FFFD flood / Chinese turned into question marks, automatically appends a `[windows-guard]` fix hint after the result (no interruption, the result body is never rewritten) |
+| L3 | `tools/pre-execute` listener | intercepts commands that write JSON/YAML/TOML/GD via `Set-Content`/`Add-Content`/`Out-File` without `-Encoding`, and `>` redirection into structured files; denies them and offers the correct `[System.IO.File]::WriteAllText(...)` form |
+| L4 | `windows_encode_detect` / `windows_encode_fix` tools | file encoding diagnosis (BOM/UTF-8/GBK/UTF-16 + confidence) and repair (→ UTF-8 without BOM, automatic `.windowsguard.bak` backup); `dryRun` diagnoses without writing |
+
+> History: the original pwsh-guard L1 system-prompt section is **no longer
+> injected** — it has been replaced by the guideline skills above (loaded on
+> demand, saving always-on tokens).
+
+## Configuration
+
+Everything in `cordis.patch.yml` is switchable (all on by default):
+
+```yaml
+- insert:
+    - id: dsh-plugin-windows-guard
+      name: dsh-plugin-windows-guard
+      config:
+        enabled: true     # master switch (false = keep only the guideline skills, degrading to the pure-guideline 0.1.0 form)
+        postCheck: true   # L2 pwsh-result mojibake detection + hint
+        preCheck: true    # L3 dangerous write-command interception
+        detectTools: true # L4 encoding diagnosis/repair tools
+```
+
+## Installation
+
+```powershell
+# npm (recommended)
+dsh plugin --profile web add dsh-plugin-windows-guard
+# or GitHub
+dsh plugin --profile web add github:Pasumao/dsh-plugin-windows-guard
+```
+
+Restart `dsh web` after installing for it to take effect. The package ships
+its own `cordis.patch.yml` mount line, applied automatically — no manual
+config edits needed; see the Configuration section for the switches.
+
+Install from source (local development / debugging):
+
+```bash
+git clone https://github.com/Pasumao/dsh-plugin-windows-guard.git
+cd dsh-plugin-windows-guard          # the directory can live anywhere (e.g. your plugins collection dir)
+npm install
+# Mount into the profile as a link: dependency:
+#   add to the profile's package.json dependencies
+#   "dsh-plugin-windows-guard": "link:<your-plugins-dir>/dsh-plugin-windows-guard"
+#   and add it to dsh.profile.bundles (or insert manually via cordis.patch.yml)
+# then pnpm install + restart dsh web
+```
+
+## What you'll see after installation
+
+- when `pwsh` tool output contains mojibake (`鈥?`/`鎻掍欢`/`锟斤拷`), a
+  `[windows-guard]` fix hint is appended to the end of the result;
+- dangerous write commands such as `Set-Content`/`Add-Content`/`Out-File`
+  writing JSON/YAML/TOML without `-Encoding` are denied outright, with the
+  correct `[System.IO.File]::WriteAllText(...)` form attached;
+- the tool list gains `windows_encode_detect` / `windows_encode_fix`
+  (encoding diagnosis and repair);
+- the skill catalog gains the `windows-enc` / `windows-sys` pitfall-guard
+  guideline skills.
+
+## Usage
+
+No configuration needed after installation. When the model runs into a
+Windows command/encoding/mojibake/path/process/port task,
+`skill({ name: "windows-enc" | "windows-sys" })` auto-loads the matching
+guideline; you can also ask the model to load a skill manually to read the
+full text.
+
+```text
+User: Read D:\dsh\config\comfy_prompt.json and check the config
+Model: Before reading, follow the guideline and use Get-Content -Encoding UTF8...
+```
+
+```text
+User: Fix config.json for me, JSON.parse throws an error
+Model: first windows_encode_detect on config.json → "utf-8-bom (confidence high)"
+     → windows_encode_fix config.json → converted to UTF-8 without BOM (backup .windowsguard.bak)
+     → verify that JSON parsing now passes
+```
+
+```powershell
+# The model is told (via the guideline skills), and this kind of command is
+# blocked by L3 with the correct form given:
+# Set-Content -Path data.json -Value $json      ← deny (PS5.1 writes UTF-16LE/BOM)
+# [System.IO.File]::WriteAllText("data.json", $json, [System.Text.UTF8Encoding]::new($false))   ← correct
+```
+
+### Why split into two skills (design notes)
+
+- **Always-on catalog cost**: two descriptions (~300 tokens) barely grows;
+- **Trigger precision**: `windows-enc` covers "command/file-content errors"
+  (encoding/escaping/mojibake), `windows-sys` covers "system environment
+  troubleshooting" (paths/processes/ports/cross-platform) — clean boundaries,
+  no interference between them;
+- **Body text halved on demand**: Windows "content error" tasks no longer
+  load the entire "system environment" section;
+- Reserved for future topics (WSL/winget/containers…) to be folded into
+  `windows-sys` extensions.
+
+## Implementation notes
+
+- Guidelines are registered via `ctx.skills.register` (the official skill
+  subsystem), with content as the SKILL.md body;
+- L2/L3 use `ctx.on('tools/post-execute' | 'tools/pre-execute')`; L4 uses
+  `ctx.tools.register` (raw definition shape); no `@deepseek-ai/*` runtime
+  packages are imported (with link: realpath resolution, external dependencies
+  cannot be resolved from the plugin directory);
+- L2 only applies to the tool named `pwsh` with successful results; L3 only
+  intercepts the narrow patterns guaranteed to corrupt writes — reads and
+  writes with explicit `-Encoding` pass through; the mojibake vocabulary is
+  based on measurements from historical sessions (11/12 positive/negative
+  cases passed);
+- Requires `Node ≥22.5` (`TextDecoder('gbk')` needs full-icu, which official
+  builds include by default);
+- Changes to skill bodies/tools/guards require a dsh restart (the host reads
+  the skills/ directory when applying plugins);
+- Every layer's registration has a ctx capability guard: if any layer is
+  unavailable it degrades gracefully with a warning — the plugin never fails
+  to mount.
+
+## Related plugins
+
+Published plugins cross-referencing each other (more of the DSH plugin
+ecosystem):
+
+- [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) — VS Code-style workspace file explorer + editable preview
+- [dsh-notify](https://www.npmjs.com/package/dsh-notify) — native Windows notification when the agent stops/errors + tray icon
+- [dsh-plugin-image-tools](https://www.npmjs.com/package/dsh-plugin-image-tools) — image choice cards / inline reply images / chat image zoom
+- [dsh-plugin-dev-kb](https://www.npmjs.com/package/dsh-plugin-dev-kb) — full Markdown mirror of the official dsh docs (plugin development knowledge base)
+- [dsh-plugin-choice-refresh](https://www.npmjs.com/package/dsh-plugin-choice-refresh) — "regenerate options" / "more options" on choice cards
+- [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) — floating table viewer in chat + one-click Markdown copy

package/README.md

@@ -1,16 +1,24 @@
 # dsh-plugin-windows-guard
 
-DeepSeek Harness (dsh) 的 **Windows 环境防坑守则插件**（纯数据，零代码逻辑）。
+![npm version](https://img.shields.io/npm/v/dsh-plugin-windows-guard)
+![License](https://img.shields.io/github/license/Pasumao/dsh-plugin-windows-guard)
+![AI Assisted](https://img.shields.io/badge/AI-Assisted-8A2BE2)
 
-把本机 255 个会话归档里反复出现的 Windows 高频坑，沉淀成「一次写对」的
-预防性守则，以两个 skill 形式自动加载给 agent——**不是修复工具，是行为规则**：
-让模型在写 PowerShell、读文件、处理编码/路径/进程/端口问题前先看到防坑清单。
+[**中文**](./README.md) | [English](./README.en.md)
 
-纯技能载体（对标 `dsh-plugin-dev-kb`）：`lib/index.js` 只有约 40 行注册代码，
-全部内容在 `skills/` 目录。零运行时依赖、零构建。
+DeepSeek Harness (dsh) 的 **Windows 环境防坑插件**——**源自 255 个真实会话归档的
+高频踩坑**，守则（skill）+ 主动防护（hooks/工具）两层能力：
+
+- **守则层**（0.1.0 起）：两个自包含 skill 按场景自动加载——「一次写对」的预防性守则；
+- **主动防护层**（0.2.0 起，自 `dsh-plugin-pwsh-guard` 合并，该插件已删除）：
+  pwsh 结果乱码自动检测提示、危险写命令拦截、编码诊断/修复工具。
+
+零运行时依赖、零构建。
 
 ## 功能
 
+### 守则层：两个自动加载的技能
+
 按触发场景拆成两个自包含技能（`<available_skills>` 按 description 匹配自动加载正文）：
 
 ### `windows-enc` —— 编码与 PowerShell 解析（命令/文件内容出错类）
@@ -30,24 +38,67 @@ DeepSeek Harness (dsh) 的 **Windows 环境防坑守则插件**（纯数据，
 | 2 进程与端口 | `netstat` 查端口、`Stop-Process`/`taskkill`、先查后杀 | 3080/39090 端口占用、孤儿进程 |
 | 3 跨平台杂项 | CRLF 陷阱、`.cmd` 脚本宿主/ExecutionPolicy、时区、大小写 | 小说文件 CRLF 检查、run.bat chcp 65001 |
 
+### 主动防护层（0.2.0 起，均可配置开关，默认全开）
+
+| 层 | 机制 | 作用 |
+|---|---|---|
+| L2 | `tools/post-execute` 监听 | `pwsh` 工具结果出现 GBK 误解码/FFFD 洪水/中文变问号时，自动在结果后附加 `[windows-guard]` 修复提示（不中断、不改写结果本体） |
+| L3 | `tools/pre-execute` 监听 | 拦截「不带 -Encoding 的 `Set-Content`/`Add-Content`/`Out-File` 写 JSON/YAML/TOML/GD」与「`>` 重定向写结构化文件」命令，deny 并给出 `[System.IO.File]::WriteAllText(...)` 正确写法 |
+| L4 | `windows_encode_detect` / `windows_encode_fix` 工具 | 文件编码诊断（BOM/UTF-8/GBK/UTF-16 + 置信度）与修复（→ UTF-8 无 BOM，自动备份 `.windowsguard.bak`）；`dryRun` 只诊断不写入 |
+
+> 历史：原 pwsh-guard 的 L1 系统提示词段**不再注入**——由上面的守则技能取代
+> （按需加载、更省常驻 token）。
+
+## 配置
+
+`cordis.patch.yml` 全部可开关（默认全开）：
+
+```yaml
+- insert:
+    - id: dsh-plugin-windows-guard
+      name: dsh-plugin-windows-guard
+      config:
+        enabled: true     # 总开关（false = 只保留守则技能，退化为 0.1.0 纯守则形态）
+        postCheck: true   # L2 pwsh 结果乱码检测+提示
+        preCheck: true    # L3 危险写命令拦截
+        detectTools: true # L4 编码诊断/修复工具
+```
+
 ## 安装
 
 ```powershell
-# 本地 link 开发（本仓库）：
-git clone https://github.com/Pasumao/dsh-plugin-windows-guard.git D:\dsh\plugins\dsh-plugin-windows-guard
-#   1. profile package.json dependencies 加
-#      "dsh-plugin-windows-guard": "link:D:/dsh/plugins/dsh-plugin-windows-guard"
-#   2. 加入 dsh.profile.bundles（或 cordis.patch.yml 手动 insert）
-cd C:\Users\18303\.dsh\profiles\web
-pnpm install
-node D:\dsh\scripts\check-profile.mjs          # 自检 [PASS] 再重启
-powershell -NoProfile -ExecutionPolicy Bypass -File D:\dsh\scripts\restart-dsh.ps1
-
-# npm 分发安装（发布后）：
-npm install dsh-plugin-windows-guard --prefix C:\Users\18303\.dsh\profiles\web
-# 并在 profile 包/补丁中挂载，其余同上
+# npm（推荐）
+dsh plugin --profile web add dsh-plugin-windows-guard
+# 或 GitHub
+dsh plugin --profile web add github:Pasumao/dsh-plugin-windows-guard
 ```
 
+装完重启 `dsh web` 即生效。包自带 `cordis.patch.yml` 挂载行，自动应用，
+无需手动改配置；配置开关见「配置」节。
+
+源码安装（本地开发 / 调试）：
+
+```bash
+git clone https://github.com/Pasumao/dsh-plugin-windows-guard.git
+cd dsh-plugin-windows-guard          # 目录放在任意位置（如你的插件收集目录）
+npm install
+# 以 link: 依赖挂载进 profile：
+#   profile 的 package.json dependencies 加
+#   "dsh-plugin-windows-guard": "link:<你的插件目录>/dsh-plugin-windows-guard"
+#   并加入 dsh.profile.bundles（或 cordis.patch.yml 手动 insert）
+# 之后 pnpm install + 重启 dsh web
+```
+
+## 装完你会看到什么
+
+- `pwsh` 工具输出出现乱码（`鈥?`/`鎻掍欢`/`锟斤拷`）时，结果末尾自动附加
+  `[windows-guard]` 修复提示；
+- 不带 `-Encoding` 的 `Set-Content`/`Add-Content`/`Out-File` 写 JSON/YAML/TOML
+  等危险写命令被直接拦截（deny），并附 `[System.IO.File]::WriteAllText(...)`
+  正确写法；
+- 工具列表多出 `windows_encode_detect` / `windows_encode_fix`（编码诊断与修复）；
+- 技能目录多出 `windows-enc` / `windows-sys` 两个防坑守则技能。
+
 ## 使用
 
 安装后无需任何配置。模型遇到 Windows 命令/编码/乱码/路径/进程/端口任务时，
@@ -59,18 +110,20 @@ npm install dsh-plugin-windows-guard --prefix C:\Users\18303\.dsh\profiles\web
 模型：读取前先按守则用 Get-Content -Encoding UTF8……
 ```
 
-## 配置/示例
-
-**无需任何配置**：挂载后即生效，无 API key、无 token、无配置文件。示例：
-
 ```text
-用户：读一下 D:\dsh\config\comfy_prompt.json 看看配置
-模型：读取前先按守则用 Get-Content -Encoding UTF8……
+用户：帮我修一下 config.json，JSON.parse 报错
+模型：先 windows_encode_detect 查 config.json → "utf-8-bom（可信度 high）"
+     → windows_encode_fix config.json → 已转换为 UTF-8 无 BOM（备份 .windowsguard.bak）
+     → 验证 JSON 解析通过
 ```
 
-更完整的使用说明见上方「使用」节。
+```powershell
+# 模型被告知（守则技能），且此类命令会被 L3 拦截并给出正确写法：
+# Set-Content -Path data.json -Value $json      ← deny（PS5.1 写 UTF-16LE/BOM）
+# [System.IO.File]::WriteAllText("data.json", $json, [System.Text.UTF8Encoding]::new($false))   ← 正确
+```
 
-### 为何拆成两个（设计说明）
+### 为何拆成两个技能（设计说明）
 
 - **常驻目录成本**：两条 description（~300 token）几乎不涨；
 - **触发精度**：`windows-enc` 管「命令/文件内容出错」（编码/转义/乱码），
@@ -80,9 +133,15 @@ npm install dsh-plugin-windows-guard --prefix C:\Users\18303\.dsh\profiles\web
 
 ## 实现说明
 
-- 注册走 `ctx.skills.register`（官方 skill 子系统），content 为 SKILL.md 正文；
-- 无工具、无命令、无服务端逻辑、无文件写入——纯预防性指令；
-- skill 正文改动需重启 dsh（host 插件 apply 时读取 skills/ 目录）。
+- 守则注册走 `ctx.skills.register`（官方 skill 子系统），content 为 SKILL.md 正文；
+- L2/L3 走 `ctx.on('tools/post-execute' | 'tools/pre-execute')`；L4 走
+  `ctx.tools.register`（原始 definition 形状）；不 import 任何 `@deepseek-ai/*`
+  运行时包（link: realpath 解析，外部依赖从插件目录解析不到）；
+- L2 只对工具名 `pwsh` 且成功结果生效；L3 仅拦截「确定会写坏」的窄模式，读操作与
+  显式 `-Encoding` 的写操作放行；乱码词表基于历史会话实测（11/12 正/负例通过）；
+- 依赖 `Node ≥22.5`（`TextDecoder('gbk')` 需要 full-icu，官方构建默认满足）；
+- 技能正文/工具/守卫改动需重启 dsh（host 插件 apply 时读取 skills/ 目录）；
+- 各层注册均有 ctx 能力守卫：任何一层不可用时降级并警告，绝不让插件挂载失败。
 
 ## 相关插件
 

package/cordis.patch.yml

@@ -1,8 +1,18 @@
-# dsh-plugin-windows-guard bundle patch: Windows 环境防坑守则 skill。
+# dsh-plugin-windows-guard bundle patch: Windows 环境防坑守则 + 主动防护。
 #
 # 应用方式与 dev-kb/nonebot-kb 相同：作为一条 insert 覆盖 profile 根。
 # `name` 必须等于 package.json 的 `name`（loader 从 profile node_modules 按名解析）。
-# 无配置项（纯数据插件）；注册技能名 windows-guard（内容见 skills/windows-guard/SKILL.md）。
+#
+# 配置项（均可省略使用默认；0.2.0 起自 dsh-plugin-pwsh-guard 合并主动防护层）：
+#   enabled: true     # 总开关（false = 只保留守则技能）
+#   postCheck: true   # L2 pwsh 工具结果乱码检测+修复提示
+#   preCheck: true    # L3 危险写命令拦截
+#   detectTools: true # L4 windows_encode_detect / windows_encode_fix 工具
 - insert:
     - id: dsh-plugin-windows-guard
       name: dsh-plugin-windows-guard
+      config:
+        enabled: true
+        postCheck: true
+        preCheck: true
+        detectTools: true

package/lib/encode.js

@@ -0,0 +1,220 @@
+/**
+ * dsh-plugin-windows-guard — 文件编码检测与修复（零依赖纯函数）。
+ *
+ * 自 0.2.0 起自 dsh-plugin-pwsh-guard 合并（该插件已删除）。
+ * 检测逻辑对齐历史会话中实际用过的字节嗅探诊断（`前3字节: 35 32 229 ---GBK解码---`）：
+ *  1. BOM 探测（UTF-8 / UTF-16LE / UTF-16BE / UTF-32）；
+ *  2. 严格 UTF-8 解码（TextDecoder fatal）判断是否合法 UTF-8；
+ *  3. GBK(936) 备选解码 + CJK 占比启发式（判断「更像 GBK 还是 UTF-8」）；
+ *  4. 修复：任意源编码 → UTF-8 无 BOM（先备份原文件）。
+ *
+ * 依赖：Node 内置 TextDecoder（需 full-icu，Node 官方构建默认满足）。
+ */
+
+import { readFileSync, writeFileSync, copyFileSync, statSync } from 'node:fs'
+
+export const GBK_LABEL = 'gbk'
+export const UTF8_LABEL = 'utf-8'
+
+/** 读文件前 N 字节做 BOM 探测。 */
+export function detectBom(buf) {
+  if (buf.length >= 3 && buf[0] === 0xef && buf[1] === 0xbb && buf[2] === 0xbf) return 'utf-8-bom'
+  if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) return 'utf-16le'
+  if (buf.length >= 2 && buf[0] === 0xfe && buf[1] === 0xff) return 'utf-16be'
+  if (buf.length >= 4 && buf[0] === 0x00 && buf[1] === 0x00 && buf[2] === 0xfe && buf[3] === 0xff) return 'utf-32be'
+  if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xfe && buf[2] === 0x00 && buf[3] === 0x00) return 'utf-32le'
+  return null
+}
+
+/** 严格 UTF-8 解码（fatal）；失败返回 null。 */
+export function strictUtf8(buf) {
+  try {
+    return { text: new TextDecoder('utf-8', { fatal: true }).decode(buf), ok: true }
+  } catch {
+    return { text: null, ok: false }
+  }
+}
+
+/** GBK 解码（宽松）；失败返回 null。 */
+export function decodeGbk(buf) {
+  try {
+    return { text: new TextDecoder('gbk').decode(buf), ok: true }
+  } catch {
+    return { text: null, ok: false }
+  }
+}
+
+/** CJK 字符占比（0~1）。 */
+export function cjkRatio(text) {
+  if (!text || text.length === 0) return 0
+  let cjk = 0
+  for (const ch of text) {
+    const cp = ch.codePointAt(0)
+    if (cp >= 0x4e00 && cp <= 0x9fff) cjk++
+  }
+  return cjk / text.length
+}
+
+/** 可控字符比例（排除替换字符/怪异字节残片）。 */
+function printableRatio(text) {
+  if (!text || text.length === 0) return 0
+  let ok = 0
+  for (const ch of text) {
+    const cp = ch.codePointAt(0)
+    if (ch === '\uFFFD') continue
+    if (cp === 9 || cp === 10 || cp === 13 || (cp >= 0x20 && cp !== 0x7f && cp < 0x10000)) ok++
+  }
+  return ok / text.length
+}
+
+/**
+ * 诊断一个文件/字节缓冲的编码。
+ * @param {Buffer} buf
+ * @param {string} [fileName] 用于报告
+ * @returns {{ encoding: string, confidence: 'high'|'medium'|'low', bom: string|null,
+ *             validUtf8: boolean, utf8CjkRatio: number, gbkCjkRatio: number, gbkPrintable: number,
+ *             replaceChars: number, note: string }}
+ */
+export function detectEncoding(buf) {
+  const bom = detectBom(buf)
+  if (bom === 'utf-16le' || bom === 'utf-16be' || bom === 'utf-32le' || bom === 'utf-32be') {
+    const enc = new TextDecoder(bom === 'utf-16le' ? 'utf-16le' : bom === 'utf-16be' ? 'utf-16be' : bom === 'utf-32le' ? 'utf-32le' : 'utf-32be')
+    let text = ''
+    try { text = enc.decode(buf) } catch { /* keep */ }
+    return {
+      encoding: bom, confidence: 'high', bom,
+      validUtf8: false,
+      utf8CjkRatio: 0,
+      gbkCjkRatio: cjkRatio(text),
+      gbkPrintable: printableRatio(text),
+      replaceChars: (text.match(/\uFFFD/g) ?? []).length,
+      note: `检测到 BOM（${bom}）——这是脚本/配置不该有的编码；建议转换为 UTF-8 无 BOM。`,
+    }
+  }
+  if (bom === 'utf-8-bom') {
+    const body = strictUtf8(buf.subarray(3))
+    return {
+      encoding: 'utf-8-bom', confidence: 'high', bom,
+      validUtf8: body.ok,
+      utf8CjkRatio: body.ok ? cjkRatio(body.text) : 0,
+      gbkCjkRatio: body.ok ? 0 : cjkRatio(decodeGbk(buf.subarray(3)).text ?? ''),
+      gbkPrintable: body.ok ? 1 : printableRatio(decodeGbk(buf.subarray(3)).text ?? ''),
+      replaceChars: body.ok ? 0 : (buf.length ? (buf.toString('utf8').match(/\uFFFD/g) ?? []).length : 0),
+      note: '检测到 UTF-8 BOM——写入 BOM 的文件（如 PowerShell 5.1 `Out-File -Encoding utf8`/记事本 早期版本）可能导致 JSON/YAML 解析失败；建议剥离 BOM。',
+    }
+  }
+  // 无 BOM：先验证严格 UTF-8
+  const utf8 = strictUtf8(buf)
+  if (utf8.ok) {
+    // UTF-8 合法。若文本几乎无 CJK 又有大量 FFFD？FFFD 不会在 fatal 模式出现。
+    const ratio = cjkRatio(utf8.text)
+    return {
+      encoding: 'utf-8', confidence: 'high', bom: null,
+      validUtf8: true,
+      utf8CjkRatio: ratio,
+      gbkCjkRatio: decodeGbk(buf).ok ? cjkRatio(decodeGbk(buf).text) : 0,
+      gbkPrintable: 1,
+      replaceChars: 0,
+      note: ratio > 0.05 ? '合法 UTF-8（含中文）。' : '合法 UTF-8（纯 ASCII/英文为主）。',
+    }
+  }
+  // UTF-8 失败 → 尝试 GBK
+  const gbk = decodeGbk(buf)
+  if (gbk.ok) {
+    const print = printableRatio(gbk.text)
+    const cjk = cjkRatio(gbk.text)
+    if (print > 0.9 && cjk > 0.05) {
+      return {
+        encoding: 'gbk', confidence: 'high', bom: null,
+        validUtf8: false,
+        utf8CjkRatio: 0,
+        gbkCjkRatio: cjk, gbkPrintable: print,
+        replaceChars: (gbk.text.match(/\uFFFD/g) ?? []).length,
+        note: '不是合法 UTF-8；按 GBK(936) 解码后为正常中文——文件由 GBK 编码工具生成（如老脚本/老编辑器）。',
+      }
+    }
+    if (print > 0.8) {
+      return {
+        encoding: 'gbk', confidence: 'medium', bom: null,
+        validUtf8: false,
+        utf8CjkRatio: 0,
+        gbkCjkRatio: cjk, gbkPrintable: print,
+        replaceChars: (gbk.text.match(/\uFFFD/g) ?? []).length,
+        note: '不是合法 UTF-8；GBK 解码基本可读（但中文占比低）。',
+      }
+    }
+    return {
+      encoding: 'unknown-binary', confidence: 'low', bom: null,
+      validUtf8: false,
+      utf8CjkRatio: 0, gbkCjkRatio: cjk, gbkPrintable: print,
+      replaceChars: (gbk.text.match(/\uFFFD/g) ?? []).length,
+      note: '不是合法 UTF-8，GBK 解码也多为不可读字符——疑似二进制文件。',
+    }
+  }
+  return {
+    encoding: 'unknown', confidence: 'low', bom: null,
+    validUtf8: false,
+    utf8CjkRatio: 0, gbkCjkRatio: 0, gbkPrintable: 0,
+    replaceChars: 0,
+    note: '无法识别编码（既非 UTF-8 也非 GBK，可能是二进制或损坏文件）。',
+  }
+}
+
+/** 诊断磁盘上的文件。 */
+export function diagnoseFile(path) {
+  const st = statSync(path)
+  if (st.size > 8 * 1024 * 1024) {
+    return { error: `文件过大（${st.size} 字节 > 8MB），跳过检测。` }
+  }
+  const buf = readFileSync(path)
+  const enc = detectEncoding(buf)
+  return { size: st.size, ...enc }
+}
+
+/**
+ * 修复为 UTF-8 无 BOM：先备份（.windowsguard.bak），再写回。
+ * @param {string} path
+ * @param {{ backup?: boolean }} [opts]
+ * @returns {{ written: boolean, before: string, after: string, backupPath?: string, note: string }}
+ */
+export function fixToUtf8NoBom(path, opts = {}) {
+  const { backup = true } = opts
+  const buf = readFileSync(path)
+  const diag = detectEncoding(buf)
+  let text
+  switch (diag.encoding) {
+    case 'utf-8-bom':
+      text = strictUtf8(buf.subarray(3)).text
+      break
+    case 'utf-16le':
+    case 'utf-16be':
+    case 'utf-32le':
+    case 'utf-32be':
+      text = new TextDecoder(
+        diag.encoding === 'utf-16le' ? 'utf-16le'
+          : diag.encoding === 'utf-16be' ? 'utf-16be'
+          : diag.encoding === 'utf-32le' ? 'utf-32le'
+          : 'utf-32be'
+      ).decode(buf)
+      break
+    case 'gbk':
+      text = decodeGbk(buf).text ?? ''
+      break
+    default:
+      if (diag.validUtf8) text = strictUtf8(buf).text ?? ''
+      else throw new Error(`无法确定编码（${diag.encoding}），不执行写入：${path}`)
+  }
+  let backupPath
+  if (backup) {
+    backupPath = `${path}.windowsguard.bak`
+    copyFileSync(path, backupPath)
+  }
+  writeFileSync(path, text, { encoding: 'utf8' }) // Node 默认 utf8 = 无 BOM
+  return {
+    written: true,
+    before: diag.encoding,
+    after: 'utf-8',
+    backupPath,
+    note: `已转换为 UTF-8 无 BOM（源编码：${diag.encoding}${backupPath ? `；备份：${backupPath}` : ''}）。`,
+  }
+}