dsh-plugin-windows-guard 0.1.0 → 0.2.1

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.1",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -13,6 +13,8 @@
     "skills",
     "cordis.patch.yml",
     "README.md",
+    "README.en.md",
+    "CHANGELOG.md",
     "scripts"
   ],
   "scripts": {
@@ -34,12 +36,19 @@
     "cordis",
     "plugin",
     "skill",
+    "tools",
+    "guard",
     "windows",
     "powershell",
     "encoding",
     "utf-8",
     "gbk",
-    "bom"
+    "bom",
+    "mojibake",
+    "garbled-text",
+    "powershell-guard",
+    "write-guard",
+    "hook"
   ],
   "license": "MIT",
   "homepage": "https://github.com/Pasumao/dsh-plugin-windows-guard#readme",

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} 项通过，存在失败项`)