dsh-plugin-windows-guard 0.2.0 → 0.2.1
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.
- package/CHANGELOG.md +5 -0
- package/README.en.md +178 -0
- package/README.md +37 -15
- package/package.json +8 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [0.2.1] - 2026-08-29
|
|
4
|
+
|
|
5
|
+
- 文档：首屏前置「255 个真实会话」钩子；安装节改为单行 dsh plugin add 命令并去掉作者本机绝对路径；新增「装完你会看到什么」与徽章行；
|
|
6
|
+
- 元数据：keywords 补长尾词（mojibake/write-guard 等，15 → 20）；
|
|
7
|
+
- 新增英文版 README.en.md 与双语切换行。
|
|
3
8
|
## [0.2.0] - 2026-08-29
|
|
4
9
|
|
|
5
10
|
- **合并 `dsh-plugin-pwsh-guard` 全部主动防护能力（该插件同日删除，本插件为唯一后继）**：
|
package/README.en.md
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
[中文](./README.md) | **English**
|
|
2
|
+
|
|
3
|
+
# dsh-plugin-windows-guard
|
|
4
|
+
|
|
5
|
+
The DeepSeek Harness (dsh) **Windows pitfall-guard plugin** — **high-frequency
|
|
6
|
+
pitfalls distilled from 255 real session archives**, with two capability
|
|
7
|
+
layers: guidelines (skills) + proactive protection (hooks/tools):
|
|
8
|
+
|
|
9
|
+
- **Guideline layer** (since 0.1.0): two self-contained skills auto-loaded by
|
|
10
|
+
scenario — preventive rules for "getting it right the first time";
|
|
11
|
+
- **Proactive protection layer** (since 0.2.0, merged from
|
|
12
|
+
`dsh-plugin-pwsh-guard`, which has since been deleted): automatic mojibake
|
|
13
|
+
detection hints for pwsh results, dangerous write-command interception, and
|
|
14
|
+
encoding diagnosis/repair tools.
|
|
15
|
+
|
|
16
|
+
Zero runtime dependencies, zero build.
|
|
17
|
+
|
|
18
|
+
## Features
|
|
19
|
+
|
|
20
|
+
### Guideline layer: two auto-loaded skills
|
|
21
|
+
|
|
22
|
+
Split into two self-contained skills by trigger scenario (the
|
|
23
|
+
`<available_skills>` catalog auto-loads the body when the description
|
|
24
|
+
matches):
|
|
25
|
+
|
|
26
|
+
### `windows-enc` — Encoding and PowerShell parsing (command/file-content errors)
|
|
27
|
+
|
|
28
|
+
| Section | Content | Source incidents (historical records) |
|
|
29
|
+
|---|---|---|
|
|
30
|
+
| 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) |
|
|
31
|
+
| 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 |
|
|
32
|
+
| 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 |
|
|
33
|
+
| 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 |
|
|
34
|
+
|
|
35
|
+
### `windows-sys` — System environment (troubleshooting)
|
|
36
|
+
|
|
37
|
+
| Section | Content | Source incidents |
|
|
38
|
+
|---|---|---|
|
|
39
|
+
| 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 |
|
|
40
|
+
| 2 Processes and ports | `netstat` port lookup, `Stop-Process`/`taskkill`, check before kill | port 3080/39090 conflicts, orphan processes |
|
|
41
|
+
| 3 Cross-platform misc | CRLF traps, `.cmd` script host/ExecutionPolicy, time zones, case sensitivity | novel-file CRLF checks, run.bat chcp 65001 |
|
|
42
|
+
|
|
43
|
+
### Proactive protection layer (since 0.2.0, every layer switchable, all on by default)
|
|
44
|
+
|
|
45
|
+
| Layer | Mechanism | Effect |
|
|
46
|
+
|---|---|---|
|
|
47
|
+
| 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 |
|
|
50
|
+
|
|
51
|
+
> History: the original pwsh-guard L1 system-prompt section is **no longer
|
|
52
|
+
> injected** — it has been replaced by the guideline skills above (loaded on
|
|
53
|
+
> demand, saving always-on tokens).
|
|
54
|
+
|
|
55
|
+
## Configuration
|
|
56
|
+
|
|
57
|
+
Everything in `cordis.patch.yml` is switchable (all on by default):
|
|
58
|
+
|
|
59
|
+
```yaml
|
|
60
|
+
- insert:
|
|
61
|
+
- id: dsh-plugin-windows-guard
|
|
62
|
+
name: dsh-plugin-windows-guard
|
|
63
|
+
config:
|
|
64
|
+
enabled: true # master switch (false = keep only the guideline skills, degrading to the pure-guideline 0.1.0 form)
|
|
65
|
+
postCheck: true # L2 pwsh-result mojibake detection + hint
|
|
66
|
+
preCheck: true # L3 dangerous write-command interception
|
|
67
|
+
detectTools: true # L4 encoding diagnosis/repair tools
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Installation
|
|
71
|
+
|
|
72
|
+
```powershell
|
|
73
|
+
# npm (recommended)
|
|
74
|
+
dsh plugin --profile web add dsh-plugin-windows-guard
|
|
75
|
+
# or GitHub
|
|
76
|
+
dsh plugin --profile web add github:Pasumao/dsh-plugin-windows-guard
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Restart `dsh web` after installing for it to take effect. The package ships
|
|
80
|
+
its own `cordis.patch.yml` mount line, applied automatically — no manual
|
|
81
|
+
config edits needed; see the Configuration section for the switches.
|
|
82
|
+
|
|
83
|
+
Install from source (local development / debugging):
|
|
84
|
+
|
|
85
|
+
```bash
|
|
86
|
+
git clone https://github.com/Pasumao/dsh-plugin-windows-guard.git
|
|
87
|
+
cd dsh-plugin-windows-guard # the directory can live anywhere (e.g. your plugins collection dir)
|
|
88
|
+
npm install
|
|
89
|
+
# Mount into the profile as a link: dependency:
|
|
90
|
+
# add to the profile's package.json dependencies
|
|
91
|
+
# "dsh-plugin-windows-guard": "link:<your-plugins-dir>/dsh-plugin-windows-guard"
|
|
92
|
+
# and add it to dsh.profile.bundles (or insert manually via cordis.patch.yml)
|
|
93
|
+
# then pnpm install + restart dsh web
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## What you'll see after installation
|
|
97
|
+
|
|
98
|
+
- when `pwsh` tool output contains mojibake (`鈥?`/`鎻掍欢`/`锟斤拷`), a
|
|
99
|
+
`[windows-guard]` fix hint is appended to the end of the result;
|
|
100
|
+
- dangerous write commands such as `Set-Content`/`Add-Content`/`Out-File`
|
|
101
|
+
writing JSON/YAML/TOML without `-Encoding` are denied outright, with the
|
|
102
|
+
correct `[System.IO.File]::WriteAllText(...)` form attached;
|
|
103
|
+
- the tool list gains `windows_encode_detect` / `windows_encode_fix`
|
|
104
|
+
(encoding diagnosis and repair);
|
|
105
|
+
- the skill catalog gains the `windows-enc` / `windows-sys` pitfall-guard
|
|
106
|
+
guideline skills.
|
|
107
|
+
|
|
108
|
+
## Usage
|
|
109
|
+
|
|
110
|
+
No configuration needed after installation. When the model runs into a
|
|
111
|
+
Windows command/encoding/mojibake/path/process/port task,
|
|
112
|
+
`skill({ name: "windows-enc" | "windows-sys" })` auto-loads the matching
|
|
113
|
+
guideline; you can also ask the model to load a skill manually to read the
|
|
114
|
+
full text.
|
|
115
|
+
|
|
116
|
+
```text
|
|
117
|
+
User: Read D:\dsh\config\comfy_prompt.json and check the config
|
|
118
|
+
Model: Before reading, follow the guideline and use Get-Content -Encoding UTF8...
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
```text
|
|
122
|
+
User: Fix config.json for me, JSON.parse throws an error
|
|
123
|
+
Model: first windows_encode_detect on config.json → "utf-8-bom (confidence high)"
|
|
124
|
+
→ windows_encode_fix config.json → converted to UTF-8 without BOM (backup .windowsguard.bak)
|
|
125
|
+
→ verify that JSON parsing now passes
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
```powershell
|
|
129
|
+
# The model is told (via the guideline skills), and this kind of command is
|
|
130
|
+
# blocked by L3 with the correct form given:
|
|
131
|
+
# Set-Content -Path data.json -Value $json ← deny (PS5.1 writes UTF-16LE/BOM)
|
|
132
|
+
# [System.IO.File]::WriteAllText("data.json", $json, [System.Text.UTF8Encoding]::new($false)) ← correct
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
### Why split into two skills (design notes)
|
|
136
|
+
|
|
137
|
+
- **Always-on catalog cost**: two descriptions (~300 tokens) barely grows;
|
|
138
|
+
- **Trigger precision**: `windows-enc` covers "command/file-content errors"
|
|
139
|
+
(encoding/escaping/mojibake), `windows-sys` covers "system environment
|
|
140
|
+
troubleshooting" (paths/processes/ports/cross-platform) — clean boundaries,
|
|
141
|
+
no interference between them;
|
|
142
|
+
- **Body text halved on demand**: Windows "content error" tasks no longer
|
|
143
|
+
load the entire "system environment" section;
|
|
144
|
+
- Reserved for future topics (WSL/winget/containers…) to be folded into
|
|
145
|
+
`windows-sys` extensions.
|
|
146
|
+
|
|
147
|
+
## Implementation notes
|
|
148
|
+
|
|
149
|
+
- Guidelines are registered via `ctx.skills.register` (the official skill
|
|
150
|
+
subsystem), with content as the SKILL.md body;
|
|
151
|
+
- L2/L3 use `ctx.on('tools/post-execute' | 'tools/pre-execute')`; L4 uses
|
|
152
|
+
`ctx.tools.register` (raw definition shape); no `@deepseek-ai/*` runtime
|
|
153
|
+
packages are imported (with link: realpath resolution, external dependencies
|
|
154
|
+
cannot be resolved from the plugin directory);
|
|
155
|
+
- L2 only applies to the tool named `pwsh` with successful results; L3 only
|
|
156
|
+
intercepts the narrow patterns guaranteed to corrupt writes — reads and
|
|
157
|
+
writes with explicit `-Encoding` pass through; the mojibake vocabulary is
|
|
158
|
+
based on measurements from historical sessions (11/12 positive/negative
|
|
159
|
+
cases passed);
|
|
160
|
+
- Requires `Node ≥22.5` (`TextDecoder('gbk')` needs full-icu, which official
|
|
161
|
+
builds include by default);
|
|
162
|
+
- Changes to skill bodies/tools/guards require a dsh restart (the host reads
|
|
163
|
+
the skills/ directory when applying plugins);
|
|
164
|
+
- Every layer's registration has a ctx capability guard: if any layer is
|
|
165
|
+
unavailable it degrades gracefully with a warning — the plugin never fails
|
|
166
|
+
to mount.
|
|
167
|
+
|
|
168
|
+
## Related plugins
|
|
169
|
+
|
|
170
|
+
Published plugins cross-referencing each other (more of the DSH plugin
|
|
171
|
+
ecosystem):
|
|
172
|
+
|
|
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
|
package/README.md
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
1
|
# dsh-plugin-windows-guard
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
|
|
4
|
+
|
|
5
|
+
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
[**中文**](./README.md) | [English](./README.en.md)
|
|
8
|
+
|
|
9
|
+
DeepSeek Harness (dsh) 的 **Windows 环境防坑插件**——**源自 255 个真实会话归档的
|
|
10
|
+
高频踩坑**，守则（skill）+ 主动防护（hooks/工具）两层能力：
|
|
6
11
|
|
|
7
12
|
- **守则层**（0.1.0 起）：两个自包含 skill 按场景自动加载——「一次写对」的预防性守则；
|
|
8
13
|
- **主动防护层**（0.2.0 起，自 `dsh-plugin-pwsh-guard` 合并，该插件已删除）：
|
|
@@ -62,21 +67,38 @@ DeepSeek Harness (dsh) 的 **Windows 环境防坑插件**：守则（skill）+
|
|
|
62
67
|
## 安装
|
|
63
68
|
|
|
64
69
|
```powershell
|
|
65
|
-
#
|
|
66
|
-
|
|
67
|
-
#
|
|
68
|
-
|
|
69
|
-
# 2. 加入 dsh.profile.bundles（或 cordis.patch.yml 手动 insert）
|
|
70
|
-
cd C:\Users\18303\.dsh\profiles\web
|
|
71
|
-
pnpm install
|
|
72
|
-
node D:\dsh\scripts\check-profile.mjs # 自检 [PASS] 再重启
|
|
73
|
-
powershell -NoProfile -ExecutionPolicy Bypass -File D:\dsh\scripts\restart-dsh.ps1
|
|
74
|
-
|
|
75
|
-
# npm 分发安装（发布后）：
|
|
76
|
-
npm install dsh-plugin-windows-guard --prefix C:\Users\18303\.dsh\profiles\web
|
|
77
|
-
# 并在 profile 包/补丁中挂载，其余同上
|
|
70
|
+
# npm（推荐）
|
|
71
|
+
dsh plugin --profile web add dsh-plugin-windows-guard
|
|
72
|
+
# 或 GitHub
|
|
73
|
+
dsh plugin --profile web add github:Pasumao/dsh-plugin-windows-guard
|
|
78
74
|
```
|
|
79
75
|
|
|
76
|
+
装完重启 `dsh web` 即生效。包自带 `cordis.patch.yml` 挂载行，自动应用，
|
|
77
|
+
无需手动改配置；配置开关见「配置」节。
|
|
78
|
+
|
|
79
|
+
源码安装（本地开发 / 调试）：
|
|
80
|
+
|
|
81
|
+
```bash
|
|
82
|
+
git clone https://github.com/Pasumao/dsh-plugin-windows-guard.git
|
|
83
|
+
cd dsh-plugin-windows-guard # 目录放在任意位置（如你的插件收集目录）
|
|
84
|
+
npm install
|
|
85
|
+
# 以 link: 依赖挂载进 profile：
|
|
86
|
+
# profile 的 package.json dependencies 加
|
|
87
|
+
# "dsh-plugin-windows-guard": "link:<你的插件目录>/dsh-plugin-windows-guard"
|
|
88
|
+
# 并加入 dsh.profile.bundles（或 cordis.patch.yml 手动 insert）
|
|
89
|
+
# 之后 pnpm install + 重启 dsh web
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
## 装完你会看到什么
|
|
93
|
+
|
|
94
|
+
- `pwsh` 工具输出出现乱码（`鈥?`/`鎻掍欢`/`锟斤拷`）时，结果末尾自动附加
|
|
95
|
+
`[windows-guard]` 修复提示；
|
|
96
|
+
- 不带 `-Encoding` 的 `Set-Content`/`Add-Content`/`Out-File` 写 JSON/YAML/TOML
|
|
97
|
+
等危险写命令被直接拦截（deny），并附 `[System.IO.File]::WriteAllText(...)`
|
|
98
|
+
正确写法；
|
|
99
|
+
- 工具列表多出 `windows_encode_detect` / `windows_encode_fix`（编码诊断与修复）；
|
|
100
|
+
- 技能目录多出 `windows-enc` / `windows-sys` 两个防坑守则技能。
|
|
101
|
+
|
|
80
102
|
## 使用
|
|
81
103
|
|
|
82
104
|
安装后无需任何配置。模型遇到 Windows 命令/编码/乱码/路径/进程/端口任务时，
|
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.
|
|
4
|
+
"version": "0.2.1",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "lib/index.js",
|
|
7
7
|
"exports": {
|
|
@@ -13,6 +13,7 @@
|
|
|
13
13
|
"skills",
|
|
14
14
|
"cordis.patch.yml",
|
|
15
15
|
"README.md",
|
|
16
|
+
"README.en.md",
|
|
16
17
|
"CHANGELOG.md",
|
|
17
18
|
"scripts"
|
|
18
19
|
],
|
|
@@ -42,7 +43,12 @@
|
|
|
42
43
|
"encoding",
|
|
43
44
|
"utf-8",
|
|
44
45
|
"gbk",
|
|
45
|
-
"bom"
|
|
46
|
+
"bom",
|
|
47
|
+
"mojibake",
|
|
48
|
+
"garbled-text",
|
|
49
|
+
"powershell-guard",
|
|
50
|
+
"write-guard",
|
|
51
|
+
"hook"
|
|
46
52
|
],
|
|
47
53
|
"license": "MIT",
|
|
48
54
|
"homepage": "https://github.com/Pasumao/dsh-plugin-windows-guard#readme",
|