dsh-plugin-windows-guard 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## [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.md

@@ -1,16 +1,19 @@
 # dsh-plugin-windows-guard
 
-DeepSeek Harness (dsh) 的 **Windows 环境防坑守则插件**（纯数据，零代码逻辑）。
+DeepSeek Harness (dsh) 的 **Windows 环境防坑插件**：守则（skill）+ 主动防护（hooks/工具）。
 
-把本机 255 个会话归档里反复出现的 Windows 高频坑，沉淀成「一次写对」的
-预防性守则，以两个 skill 形式自动加载给 agent——**不是修复工具，是行为规则**：
-让模型在写 PowerShell、读文件、处理编码/路径/进程/端口问题前先看到防坑清单。
+把本机 255 个会话归档里反复出现的 Windows 高频坑，沉淀成两层能力：
 
-纯技能载体（对标 `dsh-plugin-dev-kb`）：`lib/index.js` 只有约 40 行注册代码，
-全部内容在 `skills/` 目录。零运行时依赖、零构建。
+- **守则层**（0.1.0 起）：两个自包含 skill 按场景自动加载——「一次写对」的预防性守则；
+- **主动防护层**（0.2.0 起，自 `dsh-plugin-pwsh-guard` 合并，该插件已删除）：
+  pwsh 结果乱码自动检测提示、危险写命令拦截、编码诊断/修复工具。
+
+零运行时依赖、零构建。
 
 ## 功能
 
+### 守则层：两个自动加载的技能
+
 按触发场景拆成两个自包含技能（`<available_skills>` 按 description 匹配自动加载正文）：
 
 ### `windows-enc` —— 编码与 PowerShell 解析（命令/文件内容出错类）
@@ -30,6 +33,32 @@ 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
@@ -59,18 +88,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 +111,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}` : ''}）。`,
+  }
+}

package/lib/index.js

@@ -1,29 +1,57 @@
 /**
- * dsh-plugin-windows-guard — 主机插件（纯技能载体，无工具/命令/修复逻辑）。
+ * dsh-plugin-windows-guard — Windows 环境防坑插件（守则 + 主动防护）。
  *
- * 挂载于 profile 根层（全局层），唯一职责：把 skills/ 目录下的 windows-guard
- * 技能注册为 runtime skill，让每个会话的 agent 在 Windows 上执行命令、读写
- * 文件、处理编码/路径/进程/端口/乱码类任务时，按技能 description 自动加载
- * 防坑守则——预防性规则，不提供修复工具（AI 按守则自行修复）。
+ * 挂载于 profile 根层（全局层），两部分职责：
+ *
+ * A. 守则层（0.1.0 起）：把 skills/ 目录下的 windows-enc / windows-sys 技能注册为
+ *    runtime skill，让每个会话的 agent 在 Windows 上执行命令、读写文件、处理
+ *    编码/路径/进程/端口/乱码类任务时，按技能 description 自动加载防坑守则。
+ *
+ * B. 主动防护层（0.2.0 起，自 dsh-plugin-pwsh-guard 合并，该插件已删除）：
+ *    - L2 tools/post-execute（postCheck=true）：pwsh 工具结果出现乱码特征时，
+ *      自动在结果后附加模型可见的修复提示（不中断、不改写结果本体）；
+ *    - L3 tools/pre-execute（preCheck=true）：拦截「确定会写坏文件的命令」
+ *      （结构文件重定向写 / 无 -Encoding 的 Set-Content），给出正确写法；
+ *    - L4 windows_encode_detect / windows_encode_fix 工具（detectTools=true）：
+ *      文件编码诊断与修复（BOM 剥离、GBK→UTF-8、UTF-16→UTF-8），零依赖 Node 实现。
+ *    （原 pwsh-guard 的 L1 系统提示词段由上面的守则技能取代，不再注入。）
  *
  * 守则内容来自本机 255 个会话归档的问题扫描（GBK 误解码 / BOM / UTF-16 /
  * 单引号转义 / 长路径 / EACCES / 端口占用 / stderr 误判 / 乱码当答案等），
- * 详见 skills/windows-guard/SKILL.md。
+ * 详见 skills/windows-enc.md 与 skills/windows-sys.md。
  *
  * 依赖纪律：本模块不 import 任何 @deepseek-ai/* 运行时包（插件以 link: 方式
- * 装入 profile，Node ESM 按 realpath 解析链接包，外部依赖从插件目录解析不到）。
+ * 装入 profile，Node ESM 按 realpath 解析链接包，外部依赖从插件目录解析不到）；
+ * 工具直接走 ctx.tools.register 的原始 definition 形状（标准 JSON Schema）。
  */
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { isAbsolute, dirname, join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
+import { detect as detectMojibake, blocksToText } from './mojibake.js'
+import { diagnoseFile, fixToUtf8NoBom } from './encode.js'
 
 export const name = 'dsh-plugin-windows-guard'
-export const inject = ['skills']
+export const inject = ['skills', 'tools']
 
 const PKG_DIR = dirname(fileURLToPath(import.meta.url))
 const SKILLS_DIR = join(PKG_DIR, '..', 'skills')
 
+const DEFAULT_CONFIG = {
+  /** 总开关（false = 只保留守则技能，关闭全部主动防护）。 */
+  enabled: true,
+  /** L2：pwsh 工具结果乱码检测 + 自动附加修复提示。 */
+  postCheck: true,
+  /** L3：拦截确定会写坏结构化文本文件的命令。 */
+  preCheck: true,
+  /** L4：注册 windows_encode_detect / windows_encode_fix 工具。 */
+  detectTools: true,
+}
+
+// ---------------------------------------------------------------------------
+// 守则技能（0.1.0 起）
+// ---------------------------------------------------------------------------
+
 /** 极简 frontmatter 解析（name/description/whenToUse）。 */
 function parseFrontmatter(md) {
   const match = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(md)
@@ -66,12 +94,235 @@ function loadSkills() {
   return out
 }
 
+// ---------------------------------------------------------------------------
+// L2：post-execute 乱码检测（自 pwsh-guard 合并）
+// ---------------------------------------------------------------------------
+
+/** 后置检测附加提示（供 post-execute 追加）。 */
+function buildPostHint(detection) {
+  return [
+    '',
+    `[windows-guard] ${detection.summary}`,
+    '处理建议：若输出来自文件内容 → 先 `windows_encode_detect` 确认该文件编码、`windows_encode_fix` 转成 UTF-8 无 BOM 后再读；',
+    '若是 PowerShell 5.1 读 UTF-8 文件 → 改用 `Get-Content -Encoding UTF8`；',
+    '若是管道/控制台输出 → 先执行 `[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)` 再重跑命令。',
+    '不要把以上乱码内容当作有效答案直接使用。',
+  ].join('\n')
+}
+
+/** post-execute：pwsh 结果乱码检测 → 附加模型可见提示。 */
+export async function postCheckHandler(exec, result, next) {
+  if (exec?.name !== 'pwsh') return next()
+  if (!result || result.isError) return next()
+  const text = blocksToText(result.content ?? [])
+  if (!text) return next()
+  const detection = detectMojibake(text)
+  if (detection.ok) return next()
+  const hint = buildPostHint(detection)
+  const content = [...(result.content ?? []), { type: 'text', text: hint }]
+  return { kind: 'accept', content }
+}
+
+// ---------------------------------------------------------------------------
+// L3：pre-execute 危险写拦截（自 pwsh-guard 合并）
+// ---------------------------------------------------------------------------
+
+/** 结构文件扩展名（写坏会直接炸解析）。 */
+const STRUCTURED_EXT = /\.(json|ya?ml|toml|gd|lock)\b/i
+
+/**
+ * pre-execute 拦截：检测「确定会写坏文件」的 PowerShell 命令。
+ * @param {string} command
+ * @returns {string | undefined} 拒绝理由（含修正示例）；undefined = 放行。
+ */
+export function checkDangerousWrite(command) {
+  if (!command || typeof command !== 'string') return undefined
+  // 不带 -Encoding 的 Set-Content / Add-Content / Out-File 写结构化文件
+  if (/\b(?:Set-Content|Add-Content|Out-File)\b/i.test(command)) {
+    const hasEncoding = /-Encoding\b/i.test(command)
+    const targetsStructured = STRUCTURED_EXT.test(command)
+    if (targetsStructured && !hasEncoding) {
+      return [
+        `该命令会以 PowerShell 默认编码写入结构化文本文件（Windows PowerShell 5.1 默认 UTF-16LE，`,
+        `或 UTF-8 带 BOM），JSON/YAML 将无法解析（历史上以此为根的启动事故）。`,
+        `请改为：[System.IO.File]::WriteAllText(文件路径, $content, [System.Text.UTF8Encoding]::new($false))`,
+        `或 pwsh 7 的 Out-File -Encoding utf8NoBOM。`,
+      ].join('\n')
+    }
+  }
+  // 裸重定向写结构化文件（> file.json 等）
+  if (/>>?\s*["']?[^"'\s]+\.(json|ya?ml|toml|gd)(?:["']|$)/i.test(command)) {
+    const leading = /^>>?\s*["']?[^"'\s]+\.(json|ya?ml|toml|gd)/i.exec(command)
+    if (leading) {
+      return [
+        `PowerShell 的 > 重定向默认按 UTF-16LE（5.1）编码写入，会破坏结构化文件。`,
+        `请改用 [System.IO.File]::WriteAllText(path, content, (New-Object System.Text.UTF8Encoding($false))) 或 Out-File -Encoding utf8NoBOM。`,
+      ].join('\n')
+    }
+  }
+  // Get-Content 读 UTF-8 文件不给 -Encoding（提示但放行：英文文件无害，交给 post-check）
+  return undefined
+}
+
+/** pre-execute：拦截危险写命令。 */
+export async function preCheckHandler(exec, next) {
+  if (exec?.name !== 'pwsh') return next()
+  const command = exec.arguments?.command
+  const reason = checkDangerousWrite(command)
+  if (reason) {
+    return { kind: 'deny', reason: `[windows-guard] ${reason}` }
+  }
+  return next()
+}
+
+// ---------------------------------------------------------------------------
+// L4：编码诊断/修复工具（自 pwsh-guard 合并；命名遵循「主题_动词」规范）
+// ---------------------------------------------------------------------------
+
+/** resolvePath：绝对路径原样，相对路径基于会话 cwd（兜底 process.cwd()）。 */
+function resolveWorkPath(cwd, p) {
+  if (isAbsolute(p)) return resolve(p)
+  return resolve(cwd || process.cwd(), p)
+}
+
+function sessionCwd(exec) {
+  return exec?.agent?.session?.header?.cwd || process.cwd()
+}
+
+/** windows_encode_detect 工具定义（原始 definition 形状）。 */
+function encodeDetectTool() {
+  return {
+    name: 'windows_encode_detect',
+    description:
+      '零 token 本地文件编码诊断：检测 BOM（UTF-8/UTF-16/UTF-32）、是否合法 UTF-8、' +
+      '是否 GBK(936) 编码（PowerShell 5.1 / 老工具常见）、疑似 GBK 误解码乱码等，' +
+      '输出诊断结论与修复建议。遇到中文乱码（鈥?/鎻掍欢/锟斤拷/???）或 JSON/YAML 解析失败时先调用本工具。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: {
+        path: {
+          type: 'string',
+          description: '文件路径（相对当前工作区或绝对路径）。'
+        }
+      }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['path', 'encoding', 'diagnosis'],
+        properties: {
+          path: { type: 'string' },
+          encoding: { type: 'string' },
+          diagnosis: { type: 'string' }
+        }
+      },
+      render: (_args, value) => [{ type: 'text', text: value.diagnosis }]
+    },
+    async execute(args, exec) {
+      const cwd = sessionCwd(exec)
+      const p = resolveWorkPath(cwd, args.path)
+      if (!existsSync(p)) throw new Error(`文件不存在：${args.path}（已解析为 ${p}）`)
+      const diag = diagnoseFile(p)
+      if (diag.error) throw new Error(diag.error)
+      const diagnosis = [
+        `【文件编码诊断】${p}`,
+        `大小：${diag.size} 字节 | BOM：${diag.bom ?? '无'} | 判定：${diag.encoding}（置信度 ${diag.confidence}）`,
+        `合法 UTF-8：${diag.validUtf8 ? '是' : '否'} | UTF-8 中文占比：${(diag.utf8CjkRatio * 100).toFixed(1)}% | GBK 中文占比：${(diag.gbkCjkRatio * 100).toFixed(1)}%`,
+        `诊断：${diag.note}`,
+      ].join('\n')
+      return { path: p, encoding: diag.encoding, diagnosis }
+    }
+  }
+}
+
+/** windows_encode_fix 工具定义。 */
+function encodeFixTool() {
+  return {
+    name: 'windows_encode_fix',
+    description:
+      '零 token 本地编码修复：把文件转换为 UTF-8 无 BOM（剥离 BOM、GBK/UTF-16 → UTF-8），' +
+      '自动备份原文件为 <path>.windowsguard.bak。诊断与修复一站式；dryRun 只诊断不写入。' +
+      '修复后可用 windows_encode_detect 复查。',
+    parameters: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['path'],
+      properties: {
+        path: {
+          type: 'string',
+          description: '文件路径（相对当前工作区或绝对路径）。'
+        },
+        dryRun: {
+          type: 'boolean',
+          description: '仅诊断并输出将要执行的转换，不写文件、不创建备份（默认 false）。'
+        }
+      }
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['path', 'before', 'after', 'notice'],
+        properties: {
+          path: { type: 'string' },
+          before: { type: 'string' },
+          after: { type: 'string' },
+          notice: { type: 'string' }
+        }
+      },
+      render: (_args, value) => [{ type: 'text', text: value.notice }]
+    },
+    async execute(args, exec) {
+      const cwd = sessionCwd(exec)
+      const p = resolveWorkPath(cwd, args.path)
+      if (!existsSync(p)) throw new Error(`文件不存在：${args.path}（已解析为 ${p}）`)
+      const diag = diagnoseFile(p)
+      if (diag.error) throw new Error(diag.error)
+      if (args.dryRun) {
+        return {
+          path: p, before: diag.encoding, after: 'utf-8',
+          notice: `【dryRun】${p}\n当前编码：${diag.encoding}（置信度 ${diag.confidence}）\n转换计划：→ UTF-8 无 BOM\n${diag.note}\n未写入任何文件。`
+        }
+      }
+      if (diag.encoding === 'utf-8') {
+        return {
+          path: p, before: 'utf-8', after: 'utf-8',
+          notice: `【无需修复】${p}\n已是合法 UTF-8 且无 BOM。`
+        }
+      }
+      const fixed = fixToUtf8NoBom(p, { backup: true })
+      return {
+        path: p, before: fixed.before, after: fixed.after,
+        notice: `【修复完成】${p}\n${fixed.note}`
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// apply
+// ---------------------------------------------------------------------------
+
 export function apply(ctx, config) {
+  const cfg = { ...DEFAULT_CONFIG, ...(config ?? {}) }
+  // 显式布尔归一（patch 配置可能是字符串）
+  for (const key of Object.keys(DEFAULT_CONFIG)) {
+    if (typeof cfg[key] === 'string') cfg[key] = cfg[key] === 'true'
+  }
+
   const disposers = []
-  const skills = loadSkills()
 
+  // A. 守则技能
+  const skills = loadSkills()
   for (const skill of skills) {
     try {
+      if (typeof ctx?.skills?.register !== 'function') {
+        console.warn('[dsh-plugin-windows-guard] ctx.skills.register 不可用，跳过技能注册')
+        break
+      }
       // 契约（dsh-skill validateDefinition）：name/description/source/content 四字符串；
       // provider 缺省为 'runtime'；纯正文技能无资源目录，不声明 resourceBase。
       disposers.push(ctx.skills.register({
@@ -87,7 +338,42 @@ export function apply(ctx, config) {
     }
   }
 
-  console.log(`[dsh-plugin-windows-guard] 已挂载：${skills.length} 技能（守则在 skills/ 目录）`)
+  if (cfg.enabled) {
+    // B1（L2）：post-execute 乱码检测
+    if (cfg.postCheck) {
+      if (typeof ctx?.on === 'function') {
+        disposers.push(ctx.on('tools/post-execute', postCheckHandler))
+      } else {
+        console.warn('[dsh-plugin-windows-guard] ctx.on 不可用，postCheck 未注册')
+      }
+    }
+
+    // B2（L3）：pre-execute 危险写拦截
+    if (cfg.preCheck) {
+      if (typeof ctx?.on === 'function') {
+        disposers.push(ctx.on('tools/pre-execute', preCheckHandler))
+      } else {
+        console.warn('[dsh-plugin-windows-guard] ctx.on 不可用，preCheck 未注册')
+      }
+    }
+
+    // B3（L4）：编码诊断/修复工具
+    if (cfg.detectTools) {
+      if (typeof ctx?.tools?.register === 'function') {
+        disposers.push(ctx.tools.register(encodeDetectTool()))
+        disposers.push(ctx.tools.register(encodeFixTool()))
+      } else {
+        console.warn('[dsh-plugin-windows-guard] ctx.tools.register 不可用，detectTools 未注册')
+      }
+    }
+
+    console.log(
+      `[dsh-plugin-windows-guard] 已挂载：${skills.length} 技能 + 主动防护` +
+      `${cfg.postCheck ? ' [postCheck]' : ''}${cfg.preCheck ? ' [preCheck]' : ''}${cfg.detectTools ? ' [detectTools]' : ''}`
+    )
+  } else {
+    console.log(`[dsh-plugin-windows-guard] 已挂载：${skills.length} 技能（主动防护已由配置关闭）`)
+  }
 
   // 卸载清理（HMR 重载时避免重复注册）。
   return () => {

package/lib/mojibake.js

@@ -0,0 +1,128 @@
+/**
+ * dsh-plugin-windows-guard — 乱码模式检测（零依赖纯函数）。
+ *
+ * 自 0.2.0 起自 dsh-plugin-pwsh-guard 合并（该插件已删除）。
+ *
+ * 检测 PowerShell / dsh 运行中最常见的两类编码损坏：
+ *   1. UTF-8 字节被按 GBK/ANSI(936) 解码产生的「误解码乱码」
+ *      （经典：`鎻掍欢鏋勮瑙勮寖` = `插件构建规范`、`鈥?` = `—`、`锟斤拷` = U+FFFD 对）；
+ *   2. 替换字符 U+FFFD 洪水 / 连续问号（UTF-8 → ASCII 转换丢失，`??OK??` 案例）。
+ *
+ * 词表基于历史会话归档中实际出现的误读对（见 README「历史案例」），
+ * 全部为正常中文中几乎不出现的生僻字形，误报率极低。
+ */
+
+const GBK_MISREAD_CHARS =
+  '鎻鏋瑙鍚鏁璁锟斤拷鈥鍒鍩銆鎺鍛婵鑻娿浣剧鏇鏈浠杩鍙鏄鐨涓鑱氭' +
+  '涔勭璇ヨ寮勩缁撻噸妫娉ㄥご鍏鍐呭澶ф槸鏇撮闀扮畝鐜暣浠庢潵鍒樹笅鐪嬪潶' +
+  '涓嶆槸寰堝ソ搴旇杩囷紝锛岃繖鍙椾笉寰楄繍鐢ㄧ殑鍦板疄銆備功椤磋兘'
+
+function isCjk(ch) {
+  return ch >= '\u4e00' && ch <= '\u9fff'
+}
+
+/**
+ * 检测一段文本是否为「UTF-8 被 GBK 误解码」乱码。
+ * @param {string} text - 待检测文本。
+ * @returns {{ misread: boolean, chars?: string[], confidence: 'high'|'medium'|'low', note?: string }}
+ */
+export function detectGbkMisread(text) {
+  if (typeof text !== 'string' || text.length === 0) {
+    return { misread: false, confidence: 'low' }
+  }
+  const found = new Set()
+  for (const ch of text) {
+    if (isCjk(ch) && GBK_MISREAD_CHARS.includes(ch)) found.add(ch)
+  }
+
+  // 误解码标点怪串（强特征，单独加权）
+  let punctPieces = 0
+  const punctPatterns = [
+    /鈥[？\?\uFFFD]/g,   // em-dash 误读（鈥? / 鈥？ / 鈥�）
+    /锛[？\?\uFFFD]/g,   // 全角逗号/括号误读
+    /锛堝/g,             // 左括号误读
+    /銆[？\?\uFFFD]/g,   // 句号误读
+    /锘[？\?\uFFFD]/g,   // U+FEFF 误读
+  ]
+  for (const re of punctPatterns) {
+    const m = text.match(re)
+    if (m) punctPieces += m.length
+  }
+
+  // U+FFFD 洪水（≥5 个）
+  const substCount = (text.match(/\uFFFD/g) ?? []).length
+  const hasSubstFlood = substCount >= 5
+
+  if (found.size >= 6) {
+    return { misread: true, chars: [...found].slice(0, 16), confidence: 'high' }
+  }
+  if (found.size >= 5 && punctPieces > 0) {
+    return { misread: true, chars: [...found].slice(0, 16), confidence: 'high' }
+  }
+  if (found.size >= 3) {
+    return { misread: true, chars: [...found].slice(0, 16), confidence: 'medium' }
+  }
+  if (found.size >= 1 && punctPieces >= 1) {
+    return { misread: true, chars: [...found].slice(0, 16), confidence: 'medium', note: '含误解码标点组合' }
+  }
+  if (hasSubstFlood) {
+    return { misread: true, confidence: 'medium', note: '大量 U+FFFD 替换字符——原文在某个环节被按错误编码解码' }
+  }
+  return { misread: false, confidence: 'low' }
+}
+
+/**
+ * 检测「内容被替换为问号」的 ASCII 化损坏（`??OK??`、`??? skill ????` 案例）。
+ * @param {string} text
+ * @returns {{ asciiLoss: boolean, score: number }}
+ */
+export function detectAsciiLoss(text) {
+  if (typeof text !== 'string' || text.length < 12) {
+    return { asciiLoss: false, score: 0 }
+  }
+  const runs = text.match(/\?{2,}/g) ?? []
+  if (runs.length === 0) return { asciiLoss: false, score: 0 }
+  let score = 0
+  for (const run of runs) {
+    score += run.length >= 4 ? 2 : 1
+  }
+  const density = (text.match(/\?/g) ?? []).length / Math.max(1, text.length)
+  if (density > 0.03) score += 2
+  return { asciiLoss: score >= 2, score }
+}
+
+/**
+ * 一键检测：给定文本返回规范化的结果摘要（供 post-execute 附加提示）。
+ * @param {string} text
+ * @returns {{ ok: boolean, kind?: 'gbk-misread'|'ascii-loss', summary: string }}
+ */
+export function detect(text) {
+  const gbk = detectGbkMisread(text)
+  if (gbk.misread) {
+    return {
+      ok: false,
+      kind: 'gbk-misread',
+      summary: `疑似 GBK/ANSI 误解码乱码（特征字形：${(gbk.chars ?? []).slice(0, 6).join(' ')}${gbk.note ? `；${gbk.note}` : ''}）。`,
+    }
+  }
+  const asc = detectAsciiLoss(text)
+  if (asc.asciiLoss) {
+    return {
+      ok: false,
+      kind: 'ascii-loss',
+      summary: '疑似编码丢失（中文被替换为问号，常见于 UTF-8→ANSI 转换）。',
+    }
+  }
+  return { ok: true }
+}
+
+/** 把 ContentBlock[] 展平为纯文本（用于 post-execute 扫描）。 */
+export function blocksToText(content) {
+  if (!Array.isArray(content)) return ''
+  const parts = []
+  for (const block of content) {
+    if (block && typeof block.text === 'string') parts.push(block.text)
+    else if (typeof block === 'string') parts.push(block)
+  }
+  return parts.join('\n')
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-plugin-windows-guard",
-  "description": "DeepSeek Harness (dsh) Windows 环境防坑守则 skill 插件（纯数据）：GBK/BOM/UTF-16 编码坑、PowerShell 引号转义、长路径/文件占用/EACCES、进程与端口、CRLF、stderr 误判、乱码识别——预防性规则，无修复工具。纯技能载体，零运行时依赖，零构建。",
-  "version": "0.1.0",
+  "description": "DeepSeek Harness (dsh) Windows 环境防坑插件：两个防坑 skill（windows-enc/windows-sys：编码/转义/路径/进程/乱码预防规则）+ 三层主动防护（pwsh 结果乱码检测提示、危险写命令拦截、windows_encode_detect/fix 编码诊断修复工具）。零运行时依赖，零构建。",
+  "version": "0.2.0",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -13,6 +13,7 @@
     "skills",
     "cordis.patch.yml",
     "README.md",
+    "CHANGELOG.md",
     "scripts"
   ],
   "scripts": {
@@ -34,6 +35,8 @@
     "cordis",
     "plugin",
     "skill",
+    "tools",
+    "guard",
     "windows",
     "powershell",
     "encoding",

package/scripts/selfcheck.mjs

@@ -4,6 +4,9 @@ import fs from 'node:fs'
 import path from 'node:path'
 import { createRequire } from 'node:module'
 import { fileURLToPath, pathToFileURL } from 'node:url'
+import { detectGbkMisread, detectAsciiLoss, detect, blocksToText } from '../lib/mojibake.js'
+import { detectEncoding, fixToUtf8NoBom } from '../lib/encode.js'
+import { checkDangerousWrite } from '../lib/index.js'
 
 const require = createRequire(import.meta.url)
 const pkg = require('../package.json')
@@ -27,6 +30,7 @@ t('package.json name/main/patch 一致', () => {
   assert.equal(pkg.name, 'dsh-plugin-windows-guard')
   assert.equal(pkg.main, 'lib/index.js')
   assert.ok(pkg.dsh?.bundle?.patch, '应有 bundle patch')
+  assert.equal(pkg.version, '0.2.0', '版本应为 0.2.0')
 })
 
 // ---- 技能文件：拆分后的两个技能 ----
@@ -56,6 +60,12 @@ t('windows-enc 覆盖编码/转义/乱码', () => {
     assert.ok(md.includes(needle), `windows-enc 缺少: ${needle}`)
   }
 })
+t('windows-enc 提及配套工具 windows_encode_detect/fix', () => {
+  const md = fs.readFileSync(path.join(SKILLS_DIR, 'windows-enc.md'), 'utf8')
+  for (const needle of ['windows_encode_detect', 'windows_encode_fix', 'windowsguard.bak']) {
+    assert.ok(md.includes(needle), `windows-enc 缺少工具指引: ${needle}`)
+  }
+})
 t('windows-sys 覆盖路径/进程/跨平台', () => {
   const md = fs.readFileSync(path.join(SKILLS_DIR, 'windows-sys.md'), 'utf8')
   for (const needle of ['MAX_PATH', 'Stop-Process', 'netstat', 'autocrlf']) {
@@ -64,11 +74,15 @@ t('windows-sys 覆盖路径/进程/跨平台', () => {
 })
 
 // ---- lib 可加载且导出一致 ----
-t('lib/index.js 导出 name/inject/apply', async () => {
+t('lib/index.js 导出 name/inject/apply + 合并层导出', async () => {
   const mod = await import(pathToFileURL(path.join(PKG_DIR, '..', 'lib', 'index.js')).href)
   assert.equal(mod.name, 'dsh-plugin-windows-guard')
-  assert.ok(Array.isArray(mod.inject) && mod.inject.includes('skills'))
+  assert.ok(Array.isArray(mod.inject) && mod.inject.includes('skills'), 'inject 应含 skills')
+  assert.ok(mod.inject.includes('tools'), 'inject 应含 tools')
   assert.equal(typeof mod.apply, 'function')
+  assert.equal(typeof mod.checkDangerousWrite, 'function')
+  assert.equal(typeof mod.postCheckHandler, 'function')
+  assert.equal(typeof mod.preCheckHandler, 'function')
 })
 
 // ---- frontmatter 解析一致性（用 index.js 相同的解析逻辑）----
@@ -96,5 +110,80 @@ t('lib 只能发现拆分的两个技能', async () => {
   assert.deepEqual(registered.sort(), ['windows-enc', 'windows-sys'])
 })
 
+// ==== 以下为 0.2.0 自 pwsh-guard 合并的主动防护层测试 ====
+
+// ---- mojibake ----
+t('gbk misread 真实样本', () => {
+  assert.equal(detectGbkMisread('鎻掍欢鏋勮瑙勮寖锛堢煡璇嗗簱锛?').misread, true)
+  assert.equal(detectGbkMisread('# restart-dsh.ps1 鈥?DSH web 涓€閿畨鍏ㄩ噸鍚?').misread, true)
+})
+t('正常文本不误报', () => {
+  assert.equal(detectGbkMisread('插件构建规范，启动故障记录。').misread, false)
+  assert.equal(detectGbkMisread('PowerShell 读取 Get-Content 文件没有问题。').misread, false)
+})
+t('ascii loss 检测', () => {
+  assert.equal(detectAsciiLoss('??? skill ???? novel-format-rules ??,????:???????????????').asciiLoss, true)
+  assert.equal(detect('插件构建规范，重启前必跑自检。').ok, true)
+})
+t('blocksToText', () => {
+  const blocks = [{ type: 'text', text: 'hello' }, { type: 'tool-use', text: 'x' }]
+  assert.equal(blocksToText(blocks).includes('hello'), true)
+})
+
+// ---- encode ----
+t('utf8 无 BOM 检出', () => {
+  const d = detectEncoding(Buffer.from('插件规范,正常内容。', 'utf8'))
+  assert.equal(d.encoding, 'utf-8')
+  assert.equal(d.validUtf8, true)
+})
+t('utf8 BOM 检出', () => {
+  const d = detectEncoding(Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from('{"a":1}', 'utf8')]))
+  assert.equal(d.encoding, 'utf-8-bom')
+})
+t('utf16le BOM 检出', () => {
+  const d = detectEncoding(Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from('中文测试', 'utf16le')]))
+  assert.equal(d.encoding, 'utf-16le')
+})
+t('gbk 检出', () => {
+  // "插件规范" GBK 字节
+  const gbk = Buffer.from([0xb2, 0xe5, 0xbc, 0xfe, 0xb9, 0xe6, 0xb7, 0xb6])
+  const d = detectEncoding(gbk)
+  assert.equal(d.encoding, 'gbk')
+})
+
+// ---- pre-execute 危险写拦截 ----
+t('拦截无编码 Set-Content 写 json', () => {
+  const reason = checkDangerousWrite('Set-Content -Path config.json -Value $x')
+  assert.ok(reason && reason.includes('WriteAllText'), '应给出 WriteAllText 修正')
+})
+t('拦截 Out-File 写 yaml（无编码）', () => {
+  const reason = checkDangerousWrite('$list | Out-File list.yaml')
+  assert.ok(reason && reason.includes('WriteAllText'), reason)
+})
+t('放行带编码 Out-File', () => {
+  assert.equal(checkDangerousWrite('Out-File -Path x.json -Encoding utf8NoBOM -Value $x'), undefined)
+})
+t('放行读操作', () => {
+  assert.equal(checkDangerousWrite('Get-Content -Path readme.md'), undefined)
+  assert.equal(checkDangerousWrite("Get-ChildItem | Measure-Object"), undefined)
+})
+
+// ---- fix 往返（临时目录，零残留风险）----
+t('fixToUtf8NoBom：GBK → UTF-8 无 BOM + .windowsguard.bak 备份', () => {
+  const tmp = path.join(PKG_DIR, '..', '.selfcheck-tmp')
+  fs.mkdirSync(tmp, { recursive: true })
+  const f = path.join(tmp, 'sample.gbk.txt')
+  try {
+    fs.writeFileSync(f, Buffer.from([0xb2, 0xe5, 0xbc, 0xfe, 0xb9, 0xe6, 0xb7, 0xb6])) // GBK「插件规范」
+    const fixed = fixToUtf8NoBom(f, { backup: true })
+    assert.equal(fixed.before, 'gbk')
+    assert.equal(fixed.after, 'utf-8')
+    assert.ok(fs.existsSync(`${f}.windowsguard.bak`), '备份应存在')
+    assert.ok(fs.readFileSync(f, 'utf8').includes('插件'), '修复后应为 UTF-8 中文')
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+})
+
 if (!process.exitCode) console.log(`\n${passed} 项全部通过`)
 else console.log(`\n${passed} 项通过，存在失败项`)

package/scripts/smoke-server.mjs

@@ -1,10 +1,17 @@
-// dsh-plugin-windows-guard 服务端冒烟：假 ctx 走注册全链路（纯数据插件）。
+// dsh-plugin-windows-guard 服务端冒烟：假 ctx 走全链路
+// （技能注册 → 工具注册 → pre/post hook 决策 → 工具执行 → 修复往返 → 清理）。零依赖。
 import assert from 'node:assert'
+import fs from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import * as mod from '../lib/index.js'
 
-// 假 ctx：收集注册与日志
+// ---- 构造假 ctx ----
 const registered = []
+const registrations = {}
+const listeners = {}
 const logs = []
+
 const ctx = {
   skills: {
     register: (def) => {
@@ -12,15 +19,17 @@ const ctx = {
       return () => {} // disposer
     }
   },
+  tools: { register: (def) => { registrations[def.name] = def; return () => {} } },
+  on: (event, fn) => { listeners[event] = fn; return () => {} },
 }
 const origLog = console.log
 console.log = (...args) => { logs.push(args.join(' ')) }
 
-mod.apply(ctx)
+const dispose = mod.apply(ctx)
 
 console.log = origLog
 
-// 断言：拆分后的两个技能
+// ---- 断言：拆分后的两个技能 ----
 const names = registered.map((s) => s.name).sort()
 assert.deepEqual(names, ['windows-enc', 'windows-sys'], '应注册 windows-enc 与 windows-sys')
 for (const skill of registered) {
@@ -34,4 +43,67 @@ const sys = registered.find((s) => s.name === 'windows-sys')
 assert.ok(sys.content.includes('Stop-Process'), 'windows-sys 正文含进程守则')
 assert.ok(logs.some((l) => l.includes('技能已注册：windows-enc')), '日志有注册记录')
 
-console.log(`smoke: 全部通过（注册 ${registered.length} 个技能：${registered.map((s) => s.name).join(', ')}）`)
+// ---- 断言：合并的主动防护层（0.2.0）----
+assert.ok(registrations.windows_encode_detect, '注册 windows_encode_detect')
+assert.ok(registrations.windows_encode_fix, '注册 windows_encode_fix')
+assert.ok(listeners['tools/pre-execute'] && listeners['tools/post-execute'], '注册 hooks')
+
+// ---- pre-execute 决策 ----
+const denyExec = { name: 'pwsh', arguments: { command: 'Set-Content -Path a.json -Value $x' } }
+const preDeny = await listeners['tools/pre-execute'](denyExec, async () => ({ kind: 'allow' }))
+assert.equal(preDeny.kind, 'deny', '危险写命令被拒')
+assert.ok(preDeny.reason.includes('[windows-guard]'), '拒绝理由带 [windows-guard] 标签')
+const preAllow = await listeners['tools/pre-execute']({ name: 'pwsh', arguments: { command: 'Get-Content x.md' } }, async () => ({ kind: 'allow' }))
+assert.equal(preAllow.kind, 'allow', '读命令放行')
+
+// ---- post-execute 决策（乱码 → 附加提示）----
+const postHit = await listeners['tools/post-execute'](
+  { name: 'pwsh' },
+  { isError: false, content: [{ type: 'text', text: '# DSH 鍚姩鏁呴殰璁板綍锛堜簨鏁呭洓鎺樼栵?' }] },
+  async () => ({ kind: 'accept', content: [{ type: 'text', text: 'fallback' }] })
+)
+assert.equal(postHit.kind, 'accept')
+assert.ok(postHit.content.some((c) => typeof c.text === 'string' && c.text.includes('[windows-guard]')), '附加 windows-guard 提示')
+assert.ok(postHit.content.some((c) => typeof c.text === 'string' && c.text.includes('windows_encode_detect')), '提示引导到新工具名')
+
+const postClean = await listeners['tools/post-execute'](
+  { name: 'pwsh' },
+  { isError: false, content: [{ type: 'text', text: 'all good here' }] },
+  async () => ({ kind: 'accept', content: [{ type: 'text', text: 'fallback' }] })
+)
+assert.equal(postClean.kind, 'accept')
+assert.ok(!postClean.content.some((c) => typeof c.text === 'string' && c.text.includes('[windows-guard]')), '正常输出不附加')
+
+// ---- 非 pwsh 工具不受影响 ----
+const postOther = await listeners['tools/post-execute'](
+  { name: 'read' },
+  { isError: false, content: [{ type: 'text', text: '鎻掍欢鏋勮瑙勮寖' }] },
+  async () => ({ kind: 'accept', content: [{ type: 'text', text: 'fallback' }] })
+)
+assert.equal(postOther.kind, 'accept')
+assert.ok(!postOther.content.some((c) => typeof c.text === 'string' && c.text.includes('[windows-guard]')), '非 pwsh 工具不附加')
+
+// ---- 工具执行 ----
+const tmp = join(tmpdir(), 'windowsguard-smoke')
+fs.mkdirSync(tmp, { recursive: true })
+const f = join(tmp, 'sample.gbk.txt')
+fs.writeFileSync(f, Buffer.from([0xb2, 0xe5, 0xbc, 0xfe, 0xb9, 0xe6, 0xb7, 0xb6])) // GBK 插件规范(近似)
+const fakeExec = { agent: { session: { header: { cwd: tmp } } } }
+const detectResult = await registrations.windows_encode_detect.execute({ path: 'sample.gbk.txt' }, fakeExec)
+assert.equal(detectResult.encoding, 'gbk', 'GBK 文件被正确检出')
+const dryRun = await registrations.windows_encode_fix.execute({ path: 'sample.gbk.txt', dryRun: true }, fakeExec)
+assert.ok(dryRun.notice.includes('dryRun'), 'dryRun 不写文件')
+assert.ok(!fs.existsSync(`${f}.windowsguard.bak`), 'dryRun 无备份')
+const fixResult = await registrations.windows_encode_fix.execute({ path: 'sample.gbk.txt' }, fakeExec)
+assert.equal(fixResult.before, 'gbk')
+assert.equal(fixResult.after, 'utf-8')
+const reread = fs.readFileSync(f, 'utf8')
+assert.ok(reread.includes('插件'), '修复后为 UTF-8 中文')
+assert.ok(fs.existsSync(`${f}.windowsguard.bak`), '备份存在（.windowsguard.bak）')
+
+// ---- 清理函数可调用（HMR 幂等）----
+dispose()
+
+fs.rmSync(tmp, { recursive: true, force: true })
+
+console.log(`smoke: 全部通过（技能 ${registered.length} + 工具 ${Object.keys(registrations).length} + hooks ${Object.keys(listeners).length}，修复往返 OK）`)

package/skills/windows-enc.md

@@ -30,7 +30,11 @@ whenToUse: 读/写文本与配置文件、处理中文输出、命令引号转
 | pwsh 7 写文件 | `Out-File -Encoding utf8`（5.1 下 = 带 BOM；7 下无 BOM） | `Out-File -Encoding utf8NoBOM`（仅 pwsh 7） |
 
 补充：
-- **查文件编码**（前 3 字节嗅探）：`Format-Hex -Path a.json -Count 3`——
+- **配套零 token 工具**（本插件注册，优先于手写嗅探/转换命令）：
+  `windows_encode_detect`（诊断 BOM/UTF-8/GBK/UTF-16 + 置信度）与
+  `windows_encode_fix`（转成 UTF-8 无 BOM，自动备份 `<path>.windowsguard.bak`，
+  支持 `dryRun`）。遇到乱码或 JSON/YAML 解析失败时，先 detect 后 fix，再复检。
+- **查文件编码**（无工具可用时的替代）：`Format-Hex -Path a.json -Count 3`——
   `EF BB BF` = UTF-8 BOM（解析器可能拒绝）；`FF FE` = UTF-16LE（必然炸 JSON）；
   无 BOM 且含 `FF FD` 替换符 = 文件本来就被写坏了。
 - **GBK→UTF-8 转换**（确证文件是 GBK 时，PowerShell 无直接 cmdlet，用 .NET）：
@@ -64,3 +68,6 @@ whenToUse: 读/写文本与配置文件、处理中文输出、命令引号转
 1. **不猜**——乱码文本语义不可信，别试图「意思理解一下」继续用；
 2. **不引用**——不要把它当答案、文件名、配置值传给下游；
 3. **先重读**——回到源头（原文件原命令）按守则重新读/重新执行。
+
+附：pwsh 工具输出出现乱码时，本插件会自动在结果后追加 `[windows-guard]` 修复提示；
+文件类乱码直接走 `windows_encode_detect` / `windows_encode_fix` 工具链。