dsh-plugin-windows-guard 0.2.1 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/README.en.md +41 -12
  3. package/README.md +30 -10
  4. package/lib/encode.js +6 -2
  5. package/lib/index.js +10 -11
  6. package/package.json +1 -1
  7. package/scripts/selfcheck.mjs +2 -2
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.2.2] - 2026-09-10
4
+
5
+ - 修复：L3 重定向拦截对命令中部 `> file.json` 的漏放（锚点逻辑缺口），现覆盖任意位置的 `>` 重定向写结构化文件；
6
+ - 修复：`windows_encode_fix` 对「UTF-8 BOM 存在但主体非合法 UTF-8」的文件改报明确的「无法判定编码」错误，不再走崩溃报错路径；
7
+ - 修复：移除对 `.gd`（Godot）扩展名的误拦截；
8
+ - 自检：selfcheck 版本断言改为通用格式校验（不再硬编码具体版本号）；
9
+ - 文档：README 同步拦截能力与工具行为描述；相关插件表格修复断行。
10
+
3
11
  ## [0.2.1] - 2026-08-29
4
12
 
5
13
  - 文档：首屏前置「255 个真实会话」钩子；安装节改为单行 dsh plugin add 命令并去掉作者本机绝对路径；新增「装完你会看到什么」与徽章行；
package/README.en.md CHANGED
@@ -1,7 +1,17 @@
1
- [中文](./README.md) | **English**
1
+ <p align="center">
2
+ <img src="docs/banner.svg" alt="dsh-plugin-windows-guard banner" width="100%">
3
+ </p>
2
4
 
3
5
  # dsh-plugin-windows-guard
4
6
 
7
+ ![npm version](https://img.shields.io/npm/v/dsh-plugin-windows-guard)
8
+ ![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-windows-guard)
9
+ ![License](https://img.shields.io/github/license/Pasumao/dsh-plugin-windows-guard)
10
+ ![Stars](https://img.shields.io/github/stars/Pasumao/dsh-plugin-windows-guard?style=social)
11
+ ![AI Assisted](https://img.shields.io/badge/AI-Assisted-8A2BE2)
12
+
13
+ [中文](./README.md) | **English**
14
+
5
15
  The DeepSeek Harness (dsh) **Windows pitfall-guard plugin** — **high-frequency
6
16
  pitfalls distilled from 255 real session archives**, with two capability
7
17
  layers: guidelines (skills) + proactive protection (hooks/tools):
@@ -45,8 +55,8 @@ matches):
45
55
  | Layer | Mechanism | Effect |
46
56
  |---|---|---|
47
57
  | 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) |
48
- | 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 |
49
- | 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 |
58
+ | L3 | `tools/pre-execute` listener | intercepts commands that write JSON/YAML/TOML via `Set-Content`/`Add-Content`/`Out-File` without `-Encoding`, and `>` redirection into structured files (including mid-command `> file.json` anchor positions); denies them and offers the correct `[System.IO.File]::WriteAllText(...)` form |
59
+ | 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; when the encoding cannot be determined (e.g. a BOM is present but the body is not valid UTF-8) it returns a clear error instead of crashing |
50
60
 
51
61
  > History: the original pwsh-guard L1 system-prompt section is **no longer
52
62
  > injected** — it has been replaced by the guideline skills above (loaded on
@@ -98,7 +108,9 @@ npm install
98
108
  - when `pwsh` tool output contains mojibake (`鈥?`/`鎻掍欢`/`锟斤拷`), a
99
109
  `[windows-guard]` fix hint is appended to the end of the result;
100
110
  - dangerous write commands such as `Set-Content`/`Add-Content`/`Out-File`
101
- writing JSON/YAML/TOML without `-Encoding` are denied outright, with the
111
+ writing JSON/YAML/TOML without `-Encoding` are denied outright; `>`
112
+ redirection into structured files (including mid-command `> file.json`)
113
+ is intercepted too, with the
102
114
  correct `[System.IO.File]::WriteAllText(...)` form attached;
103
115
  - the tool list gains `windows_encode_detect` / `windows_encode_fix`
104
116
  (encoding diagnosis and repair);
@@ -167,12 +179,29 @@ Model: first windows_encode_detect on config.json → "utf-8-bom (confidence hig
167
179
 
168
180
  ## Related plugins
169
181
 
170
- Published plugins cross-referencing each other (more of the DSH plugin
171
- ecosystem):
182
+ This plugin is part of **Pasumao's dsh plugin ecosystem**. Published plugins
183
+ that work well together:
184
+
185
+ | Plugin (npm) | GitHub | Description |
186
+ |---|---|---|
187
+ | [dsh-notify](https://www.npmjs.com/package/dsh-notify) | [GitHub](https://github.com/Pasumao/dsh-plugin-notify) | Native Windows notifications + system tray |
188
+ | [dsh-plugin-choice-refresh](https://www.npmjs.com/package/dsh-plugin-choice-refresh) | [GitHub](https://github.com/Pasumao/dsh-plugin-choice-refresh) | Choice enhancements: regenerate / more options |
189
+ | [dsh-plugin-dev-kb](https://www.npmjs.com/package/dsh-plugin-dev-kb) | [GitHub](https://github.com/Pasumao/dsh-plugin-dev-kb) | Plugin development knowledge base (full official docs mirror + skills) |
190
+ | [dsh-plugin-image-tools](https://www.npmjs.com/package/dsh-plugin-image-tools) | [GitHub](https://github.com/Pasumao/dsh-plugin-image-tools) | Image choice cards + inline reply images + blind-model image intake |
191
+ | [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) | [GitHub](https://github.com/Pasumao/dsh-plugin-table-zoom) | Floating viewer for long chat tables + one-click Markdown copy |
192
+ | [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) | [GitHub](https://github.com/Pasumao/dsh-plugin-workbench) | VS Code-style file explorer + editable preview |
193
+ | [dsh-plugin-context-trim](https://www.npmjs.com/package/dsh-plugin-context-trim) | [GitHub repo](https://github.com/Pasumao/dsh-plugin-context-trim) | Per-session injection gate: trim skills / tools / prompt sections per session |
194
+
195
+ > For the rest of the series see [Pasumao · dsh plugins](https://github.com/Pasumao) —
196
+ > a ⭐ on GitHub is always appreciated.
197
+
198
+ ## AI-generated disclosure
199
+
200
+ Part of the code and documentation was AI-assisted (DeepSeek Harness), all
201
+ human-reviewed and verified against real sessions (the mojibake word list was
202
+ validated on historical sessions, 11/12 positives/negatives; L3 interception
203
+ rules were hand-checked one by one).
204
+
205
+ ## License
172
206
 
173
- - [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) — VS Code-style workspace file explorer + editable preview
174
- - [dsh-notify](https://www.npmjs.com/package/dsh-notify) — native Windows notification when the agent stops/errors + tray icon
175
- - [dsh-plugin-image-tools](https://www.npmjs.com/package/dsh-plugin-image-tools) — image choice cards / inline reply images / chat image zoom
176
- - [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)
177
- - [dsh-plugin-choice-refresh](https://www.npmjs.com/package/dsh-plugin-choice-refresh) — "regenerate options" / "more options" on choice cards
178
- - [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) — floating table viewer in chat + one-click Markdown copy
207
+ [MIT](./LICENSE)
package/README.md CHANGED
@@ -1,7 +1,13 @@
1
+ <p align="center">
2
+ <img src="docs/banner.svg" alt="dsh-plugin-windows-guard banner" width="100%">
3
+ </p>
4
+
1
5
  # dsh-plugin-windows-guard
2
6
 
3
7
  ![npm version](https://img.shields.io/npm/v/dsh-plugin-windows-guard)
8
+ ![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-windows-guard)
4
9
  ![License](https://img.shields.io/github/license/Pasumao/dsh-plugin-windows-guard)
10
+ ![Stars](https://img.shields.io/github/stars/Pasumao/dsh-plugin-windows-guard?style=social)
5
11
  ![AI Assisted](https://img.shields.io/badge/AI-Assisted-8A2BE2)
6
12
 
7
13
  [**中文**](./README.md) | [English](./README.en.md)
@@ -43,8 +49,8 @@ DeepSeek Harness (dsh) 的 **Windows 环境防坑插件**——**源自 255 个
43
49
  | 层 | 机制 | 作用 |
44
50
  |---|---|---|
45
51
  | L2 | `tools/post-execute` 监听 | `pwsh` 工具结果出现 GBK 误解码/FFFD 洪水/中文变问号时，自动在结果后附加 `[windows-guard]` 修复提示（不中断、不改写结果本体） |
46
- | L3 | `tools/pre-execute` 监听 | 拦截「不带 -Encoding 的 `Set-Content`/`Add-Content`/`Out-File` 写 JSON/YAML/TOML/GD」与「`>` 重定向写结构化文件」命令，deny 并给出 `[System.IO.File]::WriteAllText(...)` 正确写法 |
47
- | L4 | `windows_encode_detect` / `windows_encode_fix` 工具 | 文件编码诊断（BOM/UTF-8/GBK/UTF-16 + 置信度）与修复（→ UTF-8 无 BOM，自动备份 `.windowsguard.bak`）；`dryRun` 只诊断不写入 |
52
+ | L3 | `tools/pre-execute` 监听 | 拦截「不带 -Encoding 的 `Set-Content`/`Add-Content`/`Out-File` 写 JSON/YAML/TOML」与「`>` 重定向写结构化文件」（含命令中部 `> file.json` 等锚点位置），deny 并给出 `[System.IO.File]::WriteAllText(...)` 正确写法 |
53
+ | L4 | `windows_encode_detect` / `windows_encode_fix` 工具 | 文件编码诊断（BOM/UTF-8/GBK/UTF-16 + 置信度）与修复（→ UTF-8 无 BOM，自动备份 `.windowsguard.bak`）；`dryRun` 只诊断不写入；无法判定编码（如 BOM 存在但主体非合法 UTF-8）时返回明确错误而非报错崩溃 |
48
54
 
49
55
  > 历史：原 pwsh-guard 的 L1 系统提示词段**不再注入**——由上面的守则技能取代
50
56
  > （按需加载、更省常驻 token）。
@@ -94,7 +100,8 @@ npm install
94
100
  - `pwsh` 工具输出出现乱码（`鈥?`/`鎻掍欢`/`锟斤拷`）时，结果末尾自动附加
95
101
  `[windows-guard]` 修复提示；
96
102
  - 不带 `-Encoding` 的 `Set-Content`/`Add-Content`/`Out-File` 写 JSON/YAML/TOML
97
- 等危险写命令被直接拦截（deny），并附 `[System.IO.File]::WriteAllText(...)`
103
+ 等危险写命令被直接拦截（deny），`>` 重定向写结构化文件（含命令中部的
104
+ `> file.json`）同样拦截，并附 `[System.IO.File]::WriteAllText(...)`
98
105
  正确写法；
99
106
  - 工具列表多出 `windows_encode_detect` / `windows_encode_fix`（编码诊断与修复）；
100
107
  - 技能目录多出 `windows-enc` / `windows-sys` 两个防坑守则技能。
@@ -145,11 +152,24 @@ npm install
145
152
 
146
153
  ## 相关插件
147
154
 
148
- 已发布插件互相引用（更多 DSH 插件生态）：
155
+ 本插件属于 **Pasumao 的 dsh 插件生态**，同系列已发布插件可搭配使用：
156
+
157
+ | 插件（npm） | GitHub | 说明 |
158
+ |---|---|---|
159
+ | [dsh-notify](https://www.npmjs.com/package/dsh-notify) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-notify) | Windows 原生通知 + 系统托盘 |
160
+ | [dsh-plugin-choice-refresh](https://www.npmjs.com/package/dsh-plugin-choice-refresh) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-choice-refresh) | 选择增强：重新生成选项 / 更多选项 |
161
+ | [dsh-plugin-dev-kb](https://www.npmjs.com/package/dsh-plugin-dev-kb) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-dev-kb) | 插件开发知识库（官方文档完整镜像 + 技能） |
162
+ | [dsh-plugin-image-tools](https://www.npmjs.com/package/dsh-plugin-image-tools) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-image-tools) | 图片选择卡 + 回复内嵌图片 + 盲模型收图 |
163
+ | [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-table-zoom) | 聊天长表格浮窗查看 + 一键复制 Markdown |
164
+ | [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-workbench) | VS Code 风格文件浏览器 + 可编辑预览 |
165
+ | [dsh-plugin-context-trim](https://www.npmjs.com/package/dsh-plugin-context-trim) | [GitHub 仓库](https://github.com/Pasumao/dsh-plugin-context-trim) | 会话注入门控：skill / tool / 提示词段落按会话裁剪 |
166
+ > 本系列其余插件见 [Pasumao · dsh 插件](https://github.com/Pasumao)；觉得好用欢迎到 GitHub 点 ⭐。
167
+
168
+ ## AI 生成声明
169
+
170
+ 代码与文档由 AI 辅助生成（DeepSeek Harness），均经人工审查与实测验证
171
+ （乱码词表基于历史会话实测，11/12 正/负例通过；L3 拦截规则逐条人工核验）。
172
+
173
+ ## License
149
174
 
150
- - [dsh-plugin-workbench](https://www.npmjs.com/package/dsh-plugin-workbench) — VS Code 风格工作区文件浏览器 + 可编辑预览
151
- - [dsh-notify](https://www.npmjs.com/package/dsh-notify) — agent 停止/出错的 Windows 原生通知 + 托盘图标
152
- - [dsh-plugin-image-tools](https://www.npmjs.com/package/dsh-plugin-image-tools) — 图片选择卡 / 回复内嵌图片 / 聊天图片放大
153
- - [dsh-plugin-dev-kb](https://www.npmjs.com/package/dsh-plugin-dev-kb) — dsh 官方文档完整 Markdown 镜像（插件开发知识库）
154
- - [dsh-plugin-choice-refresh](https://www.npmjs.com/package/dsh-plugin-choice-refresh) — 选择卡「重新生成选项」/「更多选项」
155
- - [dsh-plugin-table-zoom](https://www.npmjs.com/package/dsh-plugin-table-zoom) — 聊天表格浮窗查看 + 一键复制 Markdown
175
+ [MIT](./LICENSE)
package/lib/encode.js CHANGED
@@ -183,9 +183,13 @@ export function fixToUtf8NoBom(path, opts = {}) {
183
183
  const diag = detectEncoding(buf)
184
184
  let text
185
185
  switch (diag.encoding) {
186
- case 'utf-8-bom':
187
- text = strictUtf8(buf.subarray(3)).text
186
+ case 'utf-8-bom': {
187
+ // BOM 主体若不是合法 UTF-8，无法判定编码——明确报错，不写文件不备份。
188
+ const body = strictUtf8(buf.subarray(3))
189
+ if (!body.ok) throw new Error(`无法判定编码（有 UTF-8 BOM 但主体不是合法 UTF-8），不执行写入：${path}`)
190
+ text = body.text
188
191
  break
192
+ }
189
193
  case 'utf-16le':
190
194
  case 'utf-16be':
191
195
  case 'utf-32le':
package/lib/index.js CHANGED
@@ -127,8 +127,8 @@ export async function postCheckHandler(exec, result, next) {
127
127
  // L3：pre-execute 危险写拦截（自 pwsh-guard 合并）
128
128
  // ---------------------------------------------------------------------------
129
129
 
130
- /** 结构文件扩展名（写坏会直接炸解析）。 */
131
- const STRUCTURED_EXT = /\.(json|ya?ml|toml|gd|lock)\b/i
130
+ /** 结构文件扩展名（写坏会直接炸解析）。不含 .gd：Godot 文件与 dsh 场景无关，属误杀源。 */
131
+ const STRUCTURED_EXT = /\.(json|ya?ml|toml|lock)\b/i
132
132
 
133
133
  /**
134
134
  * pre-execute 拦截：检测「确定会写坏文件」的 PowerShell 命令。
@@ -150,15 +150,14 @@ export function checkDangerousWrite(command) {
150
150
  ].join('\n')
151
151
  }
152
152
  }
153
- // 裸重定向写结构化文件（> file.json 等）
154
- if (/>>?\s*["']?[^"'\s]+\.(json|ya?ml|toml|gd)(?:["']|$)/i.test(command)) {
155
- const leading = /^>>?\s*["']?[^"'\s]+\.(json|ya?ml|toml|gd)/i.exec(command)
156
- if (leading) {
157
- return [
158
- `PowerShell 的 > 重定向默认按 UTF-16LE（5.1）编码写入，会破坏结构化文件。`,
159
- `请改用 [System.IO.File]::WriteAllText(path, content, (New-Object System.Text.UTF8Encoding($false))) 或 Out-File -Encoding utf8NoBOM。`,
160
- ].join('\n')
161
- }
153
+ // 裸重定向写结构化文件（> file.json 等）：外层无锚点检测命中即拦截，
154
+ // 不要求重定向位于命令开头（原内层 ^ 锚点会漏放命令中部的 > file.json）。
155
+ // 仅对结构化扩展名生效，避免扩大误杀面。
156
+ if (/>>?\s*["']?[^"'\s]+\.(json|ya?ml|toml|lock)(?:["']|$)/i.test(command)) {
157
+ return [
158
+ `PowerShell 的 > 重定向默认按 UTF-16LE（5.1）编码写入，会破坏结构化文件。`,
159
+ `请改用 [System.IO.File]::WriteAllText(path, content, (New-Object System.Text.UTF8Encoding($false))) 或 Out-File -Encoding utf8NoBOM。`,
160
+ ].join('\n')
162
161
  }
163
162
  // Get-Content 读 UTF-8 文件不给 -Encoding（提示但放行：英文文件无害，交给 post-check）
164
163
  return undefined
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "dsh-plugin-windows-guard",
3
3
  "description": "DeepSeek Harness (dsh) Windows 环境防坑插件：两个防坑 skill（windows-enc/windows-sys：编码/转义/路径/进程/乱码预防规则）+ 三层主动防护（pwsh 结果乱码检测提示、危险写命令拦截、windows_encode_detect/fix 编码诊断修复工具）。零运行时依赖，零构建。",
4
- "version": "0.2.1",
4
+ "version": "0.2.2",
5
5
  "type": "module",
6
6
  "main": "lib/index.js",
7
7
  "exports": {
package/scripts/selfcheck.mjs CHANGED
@@ -26,11 +26,11 @@ function t(name, fn) {
26
26
  }
27
27
 
28
28
  // ---- package 完整性 ----
29
- t('package.json name/main/patch 一致', () => {
29
+ t('package.json name/main/patch 一致 + 版本号合法', () => {
30
30
  assert.equal(pkg.name, 'dsh-plugin-windows-guard')
31
31
  assert.equal(pkg.main, 'lib/index.js')
32
32
  assert.ok(pkg.dsh?.bundle?.patch, '应有 bundle patch')
33
- assert.equal(pkg.version, '0.2.0', '版本应为 0.2.0')
33
+ assert.ok(typeof pkg.version === 'string' && /^\d+\.\d+\.\d+$/.test(pkg.version), `版本号应为非空 semver：${pkg.version}`)
34
34
  })
35
35
 
36
36
  // ---- 技能文件：拆分后的两个技能 ----