dsh-better-debug 0.0.0-stage → 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/README.md CHANGED
@@ -1,3 +1,446 @@
1
- # Temporary Holding Version
1
+ # dsh-better-debug
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ 把「卡住闸门」从自觉条款变成代码闸门。
4
+
5
+ `AGENTS.md` 里的五条闸门与 `stuck-gate` 技能都是**提示词层**的约束——模型得先想起
6
+ 「我卡住了」,条款才开始生效。可卡住时的典型症状恰恰是**想不起来**:于是它写第 3 个
7
+ 「再试一次」、吃第 4 遍同一个报错、改完代码不跑任何验证。这个插件不看模型说了什么,
8
+ 只看它做了什么;一旦行为符合「原地打转」,就在**下一步之前**塞一句话进去。
9
+
10
+ ## 三个信号(v0.2 语义)
11
+
12
+ | 信号 | 触发条件 | 默认阈值 | 为什么是它 |
13
+ | --- | --- | --- | --- |
14
+ | **A** 同一文件**连续盲改** | `fs/write-intent` 按绝对路径计数;**一次真测量返回结果后**才清零该目录下的计数 | 第 **3** 次 | 单点反复摩擦且中间夹不进新事实,才是「没建回路就在猜」 |
15
+ | **B** 同一**操作**反复吃错 | `tool/result` 按 `工具\|目标\|错误指纹` 组成 episode 计数;该 episode 之后搜过才免疫 | 第 **2** 次 | 同一个错两次说明第一次没读懂;按 episode 判,不会被别处的搜索免单 |
16
+ | **C** 改完**又动手**却没回路 | 写入后过 N 步没测量 → 只**上膛**(`arm` 行),**下一次写入之前**才提醒 | **2** 步 | 改完就跑下一处是最常见的漏验证;但阅读阶段不该被打断 |
17
+
18
+ 三条的判据都建立在「**测量**」这个概念上,而不是「调用了某个工具」。
19
+
20
+ ### 什么算一次测量
21
+
22
+ 「工具被调用」≠「测量完成」。这是 v0.1 最大的漏洞:`edit → ls → edit → edit` 里那个
23
+ `ls` 会把盲改计数洗白,于是真打转反而不响。
24
+
25
+ v0.2 拆成两态:**测量意图**(`tool/call` 时按参数判)与**测量结果**(`tool/result` 回来后
26
+ 才记账)。只有结果回来才清零,并且只清与该命令目录相关的文件——在 `C:/other` 跑一遍
27
+ `npm test` 不该洗掉 `C:/work/src/target.js` 的盲改计数。
28
+
29
+ | 类别 | 工具 | 判据 |
30
+ | --- | --- | --- |
31
+ | 硬测量 | `lsp_diagnostics` `verify` `run_tests` `run_test` | 恒为测量 |
32
+ | 软测量 | `ops_bash` `bash` `shell` `pwsh` | 命令命中 `measureCommands`,或描述命中 `measureIntent` 且命令不是 `ls/dir/cat/type/head/tail` |
33
+ | 搜索 | `web_search` `research` `advanced_search` `multi_search` `platform_search` `domain_search` `cache_search` `video_search` | 命中即视为取得外部先验 |
34
+ | 方法论 | `skill` | 加载方法论算有效转向,单独计数,不混进 `other` |
35
+ | 编辑 | `edit` `write` `ops_write` `str_replace` `apply_patch` `notebook_edit` | |
36
+
37
+ **失败的测试仍然是有效测量**:它给出了「错在哪一行」这个新事实。`[exit code: 1]` 一样清零、
38
+ 一样算回路,面板里只把 `ok` 记成 `false`。
39
+
40
+ `DEFAULT_MEASURE_COMMANDS` 认:`npm/pnpm/yarn/bun` + `test|verify|check|lint|typecheck|build`、
41
+ `node --test`、`pytest`、`vitest`、`jest`、`mocha`、`go test`、`cargo test`、`dotnet test`、
42
+ `tsc`、`eslint`、`ruff check`、`mypy`、`git diff --stat`。任务类型不是代码时用
43
+ `measureCommands` 换成自己的正则(词数统计、段数检查都行)。
44
+
45
+ **生成物不计入盲改**:`node_modules`、`dist`、`build`、`out`、`coverage`、`.git`、`.next`、
46
+ `.cache`、各类 lock 文件、`*.log` / `*.map` / `*.min.js` 由 `excludePaths` 排掉。
47
+
48
+ ### 错误 episode(B 的 key)
49
+
50
+ ```
51
+ 工具名 | 目标 | 错误指纹
52
+ ```
53
+
54
+ - **目标**是报错正文里第一个像路径的东西(`C:/work/a.js`),行号归一成 `<n>`;
55
+ - **指纹**是归一化后取首 6 行 / 前 300 字符的 sha256 前 16 位,`0x1f3a2b9c`→`<hex>`、
56
+ 路径→`<path>`、`42`→`<n>`。
57
+
58
+ 所以「行号变了但异常类没变」仍算同一个 episode,而**两个不同文件各错一次 ENOENT 不算**。
59
+
60
+ ## 不做的事
61
+
62
+ - **不做「我猜是」措辞检测**:插件看不见模型的内心独白,这条留给 `stuck-gate` 技能自检。
63
+ - **不做 no-op 写入判定**:`fs/write-intent` 拿到的只有 freshness token(`FsVersion` 或
64
+ `createIfAbsent`),不含内容,插件层拿不到 diff。
65
+ - **不做收尾探针清零**:归 `dsh-turn-cleanup`。
66
+ - **不用 `reject`**:那会把整个 turn 变成 no-op。只往 `messages` 尾部追加一条 user 消息。
67
+ - **不对子会话生效**:`header.origin === 'subagent'` 或 `delegationDepth > 0` 一律跳过,
68
+ 它们的 cwd 可能是别人的工作区,计数也没有可比性。
69
+
70
+ ## D 段例外
71
+
72
+ `AGENTS.md` 的 D 条:用户显式说「别搜了 / 直接改 / 快速试一下」时闸门不落。
73
+ 插件用**本 turn 用户原话**实现这条——命中 `/别搜|不要搜|不用搜|先别搜|直接改|快速试|别折腾|先试试/`
74
+ 就整 turn 静音。只认 `source.kind === 'user'` 的消息,插件自己注入的不算。
75
+
76
+ ## 幂等与重新武装
77
+
78
+ 不是「每类信号每 turn 一次」——那会让长 turn 的第二阶段永远没人管。v0.2 是**每个卡住
79
+ episode 一次**:
80
+
81
+ - 同一局面不重复(`lastFireMark` 的写序号与错序号都没变就再不开口);
82
+ - **有效测量之后重新武装**:`fired.A/C` 归零,同一 turn 里新的盲改可以再被提醒一次;
83
+ - **每 turn 总预算** `maxInjectsPerTurn`(默认 3),防止变成连击。
84
+
85
+ A/B 触发时会顺带把 C 标成已触发:A/B 已经说明了局面,再补一句「改完没验证」只是换个说法。
86
+
87
+ ## 触发前置
88
+
89
+ 闸门只管「下一次尝试之前」,不管「交完货之后」。命中信号也先过三道前置:
90
+
91
+ 1. **done-state**:本 turn 出现过 **`present` 且结果成功**(`isError !== true`)→ **不注入**。
92
+ 写一行 `suppress … reason=done`。**`present` 失败不休眠**——交付物没挂出去,闸门得继续醒着。
93
+ 下一次 `fs/write-intent` 会把 done 复位。关掉:`doneOnPresent: false`。
94
+ 2. **有回路的收敛**:见上面「什么算一次测量」。关掉:`decayEditsOnVerify: false`。
95
+ 3. **任务类型**:写作 / 词数校准 / 版式收敛没有报错与失败测试,回路是一条能给出数字的
96
+ 校验命令;注入文案已改成任务中立。
97
+
98
+ 边界:代码层只能认 `present` 这个动作。**纯文本终稿(没有 `present`)** 只能靠
99
+ `stuck-gate` 技能里的 done-state 自检覆盖——两层互补,别指望插件读模型心思。
100
+
101
+ ## 注入文案
102
+
103
+ ```
104
+ [better-debug] 观察到的重复动作(只是观察,不是结论):
105
+ - 同一个文件连续改了 3 次,中间没有任何测量。
106
+ 下一步(挑一条就够):
107
+ 1) 建一条几秒能跑完、能给出数字或事实的回路(失败测试 / 复现命令 / 一条断言 / lsp_diagnostics);建不出来就停下要现场产物。
108
+ 恢复条件:拿到一条新的测量结果或一条外部事实后,继续动手即可。
109
+ 完整五条:skill `stuck-gate`。
110
+ ```
111
+
112
+ 三条纪律:
113
+
114
+ 1. **只陈述观察,不替模型下诊断**。原来那句「检测到你在原地打转」是在替它定性,现在改成
115
+ 「观察到的重复动作(只是观察,不是结论)」。
116
+ 2. **最多给两条动作**。多给等于没给。
117
+ 3. **一定给恢复条件**。「怎么才能继续」比「你错了」有用。
118
+
119
+ 文案的唯一来源是 `lib/text.js`,`index.js`(注入)与 `panel.js`(老日志回填字符数)共用它,
120
+ 所以面板的字符估算不会与真实文案漂移。
121
+
122
+ ## 响应协议(提示词层,`stuck-gate` 技能)
123
+
124
+ 闸门触发后,把验证 / 搜索 / 清场 / 上下文压缩**静默一次性跑完**,期间不输出终稿措辞,
125
+ 全部结束后给**一个**结论。禁止「结论 → 一串工具调用 → 又一句结论」的倒挂。
126
+ `[better-debug]` 只是提醒,不需要先用文字回应它。
127
+
128
+ ## 自带技能
129
+
130
+ 插件包内含 `assets/stuck-gate/SKILL.md`,通过 `inject: ["skills"]` 注册成 **bundled 技能**
131
+ (`source: "bundled"`,`rank: 600`)——装完就出现在模型可见的技能目录里,不需要另外拷贝文件。
132
+
133
+ 注入的那句提醒末尾写着「完整五条:skill `stuck-gate`」,指的是这一份。
134
+
135
+ **rank 关系**(数值小的优先):
136
+
137
+ | rank | 来源 | 谁说话 |
138
+ | --- | --- | --- |
139
+ | 100–200 | 项目级 `.dsh/skills`、`.agents/skills` | 项目覆盖 |
140
+ | 300 | `custom` | |
141
+ | 400 | `~/.dsh/skills`(用户全局) | **用户自己放的会压过本插件** |
142
+ | 500 | `~/.agents/skills` | |
143
+ | 600 | 本插件 `assets/` | 默认文案 |
144
+
145
+ 所以想改闸门措辞**不必改代码**:在 `~/.dsh/skills/stuck-gate/SKILL.md` 放一份就自动生效。
146
+ 改插件里的那份则对所有安装者生效(改了 `assets/` 下的文件,`get()` 每次重读,无需重启)。
147
+
148
+ 宿主若没有 `skills` 服务(老版本 DSH),注册会被跳过并记一行日志,**闸门本身照常工作**。
149
+
150
+ ## 观测面板
151
+
152
+ 日志只有一种人爱读,就是写它的人。面板把它变成一眼能看的东西:**设置页 → better-debug**,
153
+ 一个 iframe 视图,5 秒自刷新,只读,不改插件行为。
154
+
155
+ 四张主卡:
156
+
157
+ | 卡 | 数据来源 | 能说明什么 |
158
+ | --- | --- | --- |
159
+ | 闸门触发次数 | 每条 `inject` 行 | 提醒一共说了几次,按 `A/B/C` 与组合标签分组 |
160
+ | 覆盖会话 | `inject` 行的 `session=` 去重 | 影响了多少个会话、多少个轮次、注入文本共多少字符 / token |
161
+ | **提示后首个动作** | `outcome` 行的 `class=` | 提醒之后第一条 `tool/call` 是什么类别。**描述性的,不证明因果** |
162
+ | **测量回路(硬证据)** | `measure` 行 | 真正的测量发生了多少次、成功几次、失败几次、清掉了哪些盲改计数 |
163
+
164
+ 外加三个分布:信号分布、提示后首个动作六类、**窗口内是否真的转去取得新事实**
165
+ (`change` 行,含中位步数)。
166
+
167
+ ### 指标措辞纪律
168
+
169
+ 这是 v0.1 面板最容易误导的地方,v0.2 明确拆开:
170
+
171
+ - 「换动作率」这个名字**删掉了**。它算的是「提示后第一个工具属 verify/search 的比例」,
172
+ 既不能证明提示促成了改变,更不能证明它帮你发现了缺陷——模型本来也可能这正是它下一步。
173
+ 现在叫 **「提示后首个动作」**,字段名 `firstAction`。
174
+ - 想知道「窗口内有没有转去取得新事实」,看 `turned`(只从 `change` 行算,有真中位步数)。
175
+ 真正的 `medianSteps` 在这里才有样本——v0.1 那个恒为 `null`,因为 outcome 在下一步就写、
176
+ 步差永远是 0。
177
+ - **老日志不会被算成「0% 转向」**。v0.1 的 `inject` 行没有 `inj=`,也就不可能有 `change` /
178
+ `measure` 行;这时「转向 0 次」是**没测**,不是「测了没有」。`turned.observed` 是分母,
179
+ 只数埋点上线后的注入,`rate` 在 `observed = 0` 时是 `null`,面板显示「这段日志早于
180
+ v0.2 埋点」。真实日志里 55 次注入全是老格式,`observed = 0` —— 面板现在会这么说,
181
+ 而不是拿 49 条 outcome 当分母报一个 0%。
182
+ - 「这些数字不证明什么」直接印在页脚:要证明增益,需要对照组或历史回放,面板两个都不做。
183
+ - **不估算「省掉了多少 token」**。插件的职责是把可观测的事记下来,把判断留给看的人。
184
+
185
+ ### 为面板新增的埋点
186
+
187
+ 每次注入分到一个 `inj=`(8 位哈希),后续几行都带着它,于是同一次提醒的全生命周期可串起来:
188
+
189
+ ```
190
+ inject session=… turn=39 step=88 signals=A inj=78ed6bc3 chars=309 tokens=271 files=1 worstEdits=3 worstStreak=3 worstErrors=0 searched=false measured=no
191
+ arm session=… turn=39 gap=2
192
+ outcome session=… turn=39 inj=78ed6bc3 after=A first=ops_bash class=verify steps=1 before=write
193
+ measure session=… turn=39 tool=ops_bash ok=false exit=1 cleared=1
194
+ change session=… turn=39 inj=78ed6bc3 after=A tool=ops_bash class=verify steps=1
195
+ suppress session=… turn=39 reason=done
196
+ ```
197
+
198
+ - `outcome` 只收**第一条**后续 `tool/call`:晚到的验证不能把早先的原地打转洗白。
199
+ `before=` 是提醒前的上一条动作(写入也计入,所以常见值是 `write`)。
200
+ - `change` 只在注入后的 `changedWindow`(默认 6)步内写,窗口外自动丢弃。
201
+ - `measure` 每次测量结果都写,带 `ok` / `exit` / `cleared`(清掉了几个文件的计数)。
202
+ - 老日志没有 `chars=` 时,解析器用 `lib/text.js` 的 `charsFor(signals)` **真算一遍文案长度**,
203
+ v0.1 那张硬编码常量表(`A=254` 等,与真实文案差约 50 字符)已删除。
204
+
205
+ ### 关掉面板
206
+
207
+ `config: { panel: false }`。路由不挂,`/better-debug` 返回 404,闸门不受影响。
208
+
209
+ 路由用 `ctx.inject(['webServer'], …)` **动态注入**,没有加进 `export const inject` ——
210
+ 后者是结构性变更,会让热重载失效,也会让没有 `webServer` 的宿主连闸门都装不上。
211
+ 宿主缺 `webServer` 时日志写一行 `panel unavailable: …`,挂载抛错写 `panel register failed: …`,
212
+ 面板会把它显示出来。
213
+
214
+ ## 安装
215
+
216
+ **最短一条(npm registry,已发布):**
217
+
218
+ ```bash
219
+ dsh plugin add dsh-better-debug
220
+ ```
221
+
222
+ **或者从 Release tarball 装(pnpm 会把它当普通包装进 profile):**
223
+
224
+ ```bash
225
+ dsh plugin add https://github.com/Leonlee114514/dsh-better-debug/releases/download/v0.2.1/dsh-better-debug-0.2.1.tgz
226
+ ```
227
+
228
+ (两条装的是同一个包:npm 上的 tarball 与 Release 资产逐字节相同。走 npm 的好处是
229
+ 市场每日探测会自动把 `npm` 字段回填进目录条目,用户点一下就走 registry 快路。)
230
+
231
+ **手动 link(要改代码就用这个):**
232
+
233
+ ```bash
234
+ # 1. 放到一个你长期保留的位置。别放临时目录,也别放 node_modules 里
235
+ # (下面以 ~/dsh-plugins/dsh-better-debug 为例,换成你自己的路径即可)
236
+ mkdir -p ~/dsh-plugins
237
+ cp -r dsh-better-debug ~/dsh-plugins/
238
+
239
+ # 2. profile 里加 link 依赖
240
+ cd ~/.dsh/profiles/desktop
241
+ # package.json → dependencies 加一行(路径相对 .dsh/profiles/desktop):
242
+ # "dsh-better-debug": "link:../../../dsh-plugins/dsh-better-debug"
243
+ # 也可以直接写绝对路径:
244
+ # "dsh-better-debug": "link:D:/code/dsh-better-debug"
245
+ # package.json → dsh.profile.bundles 数组末尾加:
246
+ # "dsh-better-debug"
247
+
248
+ # 3. 让 bundle patch 挂上(如果 bundles 已含它,dsh 会自动 apply 包内的 cordis.patch.yml)
249
+ # 或者在自己的 profile cordis.patch.yml 里手写一行:
250
+ # - id: better-debug
251
+ # name: dsh-better-debug
252
+ # 注意:**不要加 `inject: [skills]`**,见下面「为什么不用静态 inject」。
253
+ # 包内那行也**故意不带 config**,见「为什么 bundle patch 里没有 config」。
254
+
255
+ # 4. 重启 DSH。
256
+ ```
257
+
258
+ > **别同时用两种挂法。** 包内 `cordis.patch.yml` 已有一行 `- id: better-debug`;如果你又在
259
+ > profile 里手写同 id 一行,cordis 会 reject 重复 id。两行 id **不同**但指向同一包名更糟:
260
+ > 插件被挂两次,每句提醒注入两遍、每行日志写两份。
261
+
262
+ ### 为什么不用静态 inject
263
+
264
+ `export const inject` 是空的,`cordis.patch.yml` 里也不写 `inject:` —— 这都是刻意的。
265
+
266
+ cordis 的 `Fiber._refresh()` 只要声明的服务里**有一个拿不到**,就把 epoch 置成 `INACTIVE`
267
+ 并直接不执行 `apply()`:没有报错、没有日志、面板里看起来装好了,实际一行代码都没跑。
268
+ 而 loader 还会把 YAML entry 的 `inject:` 合并进依赖集
269
+ (`cordis-plugin-loader`:`Inject.resolve(entry.options.inject, fiber.inject)`),
270
+ 所以光改代码不够,配置里的那行同样会把插件卡死。
271
+
272
+ `skills` 由 `@deepseek-ai/dsh-skill` 提供。裁剪过的 profile、别的发行版、或者只是没启用
273
+ 那个包时,它就不在——而闸门根本不需要它。两个可选服务(`skills` / `webServer`)一律走
274
+ `ctx.inject(['skills'], cb)` 动态订阅:服务在就挂上,不在就少一个可选功能。
275
+
276
+ 面板同理:`client.js` 在 `slots` 不在时自己跳过注册,不影响闸门。
277
+ 想看面板就打开 **设置 → better-debug**,或直接访问 `http://<web-origin>/better-debug`。
278
+
279
+ ### 为什么 bundle patch 里没有 config
280
+
281
+ 包内的 `cordis.patch.yml` 只有两行 `id` + `name`,一个配置键都不写。原因是
282
+ DshMarket 的热挂载只重放**纯 insert 行**:
283
+
284
+ ```js
285
+ // dshmarket/lib/hot.js
286
+ export function parseSimplePatch(patchText) {
287
+ const scan = scanPatch(patchText)
288
+ return scan.blocker === null ? scan.rows : null // 一遇到别的键就 null
289
+ }
290
+ ```
291
+
292
+ `scanPatch()` 撞上 `config:` 就停下并把整份 patch 标成 `blocker: 'config'`,
293
+ 市场于是给用户看「bundle patch 里有 config 块,热挂载只重放纯 insert 行;重启后由
294
+ bundle 层按原样加载」。也就是说:**写了 config,用户点「启用」不会有任何反应,
295
+ 必须重启 DSH**——新用户最容易在这一步以为插件坏了。
296
+
297
+ 每个默认值本来就已经在 `lib/index.js` 的 `normalizeConfig()` 里,那份 config 块
298
+ 只买到"自我文档"这一个好处,代价却是新手看不到任何反馈。所以默认值留在代码里,
299
+ 需要在 profile 里覆盖时再写 config——profile 那一行不参与包的热挂载,写什么都行。
300
+
301
+ ## 配置
302
+
303
+ 全部默认值写在 `lib/index.js` 的 `normalizeConfig()` 里,装上就能跑。要改就在
304
+ **自己 profile 的** `cordis.patch.yml` 里写同一 id(`- id: better-debug`)并加
305
+ `config:` 块覆盖——不要改包内那份(下次升级会被覆盖,而且带 config 会让市场无法热挂载):
306
+
307
+ ```yaml
308
+ - id: better-debug
309
+ name: dsh-better-debug
310
+ config:
311
+ enabled: true
312
+ repeatEditThreshold: 3 # A:同一文件连续改几次算盲改
313
+ repeatErrorThreshold: 2 # B:同一 episode 错几次算打转
314
+ noVerifySteps: 2 # C:改完几步没测量才「上膛」
315
+ maxInjectsPerTurn: 3 # 单轮最多提醒几次
316
+ changedWindow: 6 # 注入后多少步内算「转向」窗口
317
+ decayEditsOnVerify: true # 测量后清零连续盲改计数(false = 旧行为)
318
+ doneOnPresent: true # present 成功后休眠,下一次写入重新武装(false = 旧行为)
319
+ measureCommands: "" # 覆盖「什么命令算测量」的正则;空 = 内置清单
320
+ measureIntent: "" # 覆盖「描述里出现什么算测量意图」的正则
321
+ excludePaths: "" # 覆盖「哪些路径不算盲改」的正则
322
+ logFile: "~/.dsh/logs/better-debug.log" # 支持 ~ 展开;不写就默认这个位置
323
+ panel: true # 挂 /better-debug 只读面板;false = 不挂路由
324
+ ```
325
+
326
+ 调紧(更容易触发)→ 数字调小;放松 → 调大。`enabled: false` 时连 listener 都不注册。
327
+ 三个正则键传坏正则会**回退到内置默认**并记一行 warn,不会把插件弄死。
328
+
329
+ `logFile` 的四种写法:
330
+
331
+ | 写法 | 落到哪 |
332
+ | --- | --- |
333
+ | 不写这个键 | `$DSH_HOME/logs/better-debug.log`(没设 `DSH_HOME` 就是 `~/.dsh/logs/better-debug.log`) |
334
+ | `"~/my.log"` | 展开成家目录下的 `my.log`(`~` 和 `~/x`、`~\x` 都认) |
335
+ | `"C:/x.log"` / `"/var/log/x.log"` | 原样使用 |
336
+ | `""` 或 `false` | **显式关闭落盘**。`ctx.logger` 只进 Electron stdout,事后 grep 不到,面板也就没有数据 |
337
+
338
+ 默认不落盘曾经是 v0.1 的行为,代价是新用户装完打开面板看到四张空卡,
339
+ 以为插件没工作。现在开箱就有数据。
340
+
341
+ ## 怎么验证它真的在工作
342
+
343
+ 1. 装好重启后,日志默认就在 `$DSH_HOME/logs/better-debug.log`,不需要配置。
344
+ 想换位置就设 `logFile`。
345
+ 2. 加载即有一行 `apply pid=… logFile=… A=3 B=2 C=2 budget=3 window=6 panel=true`——
346
+ **这一行是唯一能证明「插件到底加载了」的证据**(`ctx.logger` 只进 Electron stdout,
347
+ 事后 grep 不到)。没有 `apply` 行就是没挂上。
348
+ 3. 正常干活,日志出现这样一行即为命中:
349
+ ```
350
+ inject session=… turn=32 step=98 signals=A inj=78ed6bc3 chars=309 tokens=271 files=1 worstEdits=3 worstStreak=3 worstErrors=0 searched=false measured=no
351
+ ```
352
+ `signals` 是命中的信号(`A`/`B`/`C`,多条用 `+`);`files` 是本 turn 碰过的**不同文件数**、
353
+ `worstEdits` 是累计改了几次,**`worstStreak` 才是 A 真正用的判据**(自上次测量以来的
354
+ 连续盲改次数)。三者混着看:`files=1 worstEdits=3 worstStreak=1` 说明中间夹过测量,不该响。
355
+ `suppress … reason=done` 表示闸门醒着但处于交付态,故意不出声。
356
+ `arm … gap=2` 表示 C 只上了膛、还没开口(它在等你下一次写入)。
357
+ 4. 自证指标**不要**看「下一动作是不是 verify」。要看两件事:
358
+ - `measure` 行有没有出现(这是硬证据:真的测了);
359
+ - `change` 行的 `steps=`(隔了几步才转去取得新事实)。
360
+ 如果只有 `outcome` 没有 `measure`,说明模型只是换了个工具,没真的建立回路。
361
+
362
+ ## 本地验证
363
+
364
+ ```bash
365
+ node --check lib/index.js && node --check lib/panel.js && node --check lib/text.js && node --check client.js
366
+ node test/sim.mjs # 40 个用例:闸门语义 + 可移植性
367
+ node test/panel.mjs # 32 个用例:日志解析、聚合、埋点落盘
368
+ npm run test:posix # 把上面两套用 POSIX 路径语义再跑一遍
369
+ npm run verify # 上面全部(含语法检查)
370
+ ```
371
+
372
+ `test/sim.mjs` 用假 ctx 复刻 agent-loop 的调用顺序(`emitPlain` / `emitWaterfall`),
373
+ 覆盖 **40 个用例**。
374
+
375
+ 语义层(每条都有正例 + 反例):
376
+
377
+ - **测量意图 / 结果两态**:`edit → ls → edit → edit` 仍触发;只 call 不 result 不清零;
378
+ 失败的测试不算盲改;无关目录的测量不清目标文件的计数。
379
+ - **B 的 episode**:同目标同指纹才累计;两个不同文件各错一次 ENOENT 不触发;
380
+ episode 之后搜过才免疫(先搜过别的问题不免疫)。
381
+ - **C 的两段式**:改完只在读东西不打断;上膛后又动手才开口。
382
+ - **重新武装**:A 提醒 → 有效测量恢复 → 新阶段再盲改允许第二次;受每 turn 预算约束。
383
+ - **交付态**:`present` 成功后不注入;**`present` 失败不休眠**。
384
+ - 措辞只陈述观察、锁文件不计入、D 段静音、子会话跳过、阈值可调、
385
+ `decayEditsOnVerify: false` 反例可回滚、`enabled: false`、自带技能注册与正文去私有化、
386
+ 宿主无 `skills` 服务不抛、导出形状,以及 13 项分类/判据/指纹单测。
387
+
388
+ **不依赖 DSH 运行时**,改动后先跑它。
389
+
390
+ ### 为什么有 `test:posix` 这一轮
391
+
392
+ `test/sim.mjs` 里的路径全是 `C:/work/...` 这种 Windows 方言。它在一台 Linux 机器上照样
393
+ 能跑,但跑的是**另一套语义**——这正是 v0.2 之前的一个真事故:
394
+
395
+ `node:path` 的 `isAbsolute` 是平台相关的,`isAbsolute('C:/work/a.js')` 在 Linux/macOS 上
396
+ 返回 `false`。入口闸用它筛写入路径,于是那些机器上**所有写入被静默丢弃**,A / C 两个信号
397
+ 完全不工作,而 Windows 开发机上一片绿。修法是不再问操作系统「这个根像不像我」,只问
398
+ 「它是不是从根开始的」(`isAbsPath`)。
399
+
400
+ `test/posix` 用 `node --import` 的 resolve hook 把 `node:path` 换成 `node:path/posix`,
401
+ 然后**把两套用例原样再跑一遍**——这样 Windows 开发机也能复现 Linux 的路径语义。CI 在
402
+ ubuntu / windows / macos × node 20 / 22 / 24 上跑 `npm run verify`,所以这条不会退回去。
403
+ (24 不是凑数:桌面版 DSH 跑的是 Electron 内置的 node 24。)
404
+
405
+ 同一类问题的另外四处,都在 v0.2 / v0.2.1 修掉了:
406
+
407
+ | 症状 | 根因 | 现在 |
408
+ | --- | --- | --- |
409
+ | Linux/macOS 上闸门完全不响 | `isAbsolute` 平台相关 | `isAbsPath` 两种方言都认 |
410
+ | 装完面板四张卡全 0 | 默认 `logFile: ""` 不落盘 | 默认落 `$DSH_HOME/logs/better-debug.log` |
411
+ | 插件静默不加载,无报错无日志 | 静态 `inject: ['skills']` 缺服务时 `apply()` 整个不执行 | `inject = []`,走 `ctx.inject` 动态订阅 |
412
+ | 市场点「启用」没反应 | bundle patch 带 `config:` 块 | patch 只留 `id` + `name` |
413
+ | 宿主版本太旧也不拦 | 版本范围写在 `dsh.engines.dsh`,而宿主与市场只读顶层 `engines.dsh` | 移到顶层 `engines.dsh` |
414
+
415
+ **大小写折叠按平台判**(`CASE_INSENSITIVE`):只在 `win32` / `darwin` 上折叠。折叠错了的
416
+ 后果不对称——该折叠却不折叠是漏报,不该折叠却折叠是**误报**(狼来了),后者才是这道闸门
417
+ 最不能犯的错。macOS 上装了区分大小写的 APFS 会少报一点,仍然是安全方向。
418
+
419
+ `test/panel.mjs` 覆盖 **32 个用例**:带引号与转义的字段切分、六种行型解析(`inject` / `outcome` /
420
+ `change` / `measure` / `arm` / `panel-failed`)、`charsFor` 与真实文案长度零漂移(6 组信号组合)、
421
+ `worstStreak` 在日志→解析→聚合→面板全链路保留、`suppress` 与 `arm` 行可解析且不计入触发、
422
+ 聚合出的 `firstAction` / `turned` / `measures`、**断言 v0.1 的旧字段名
423
+ `changed` / `changedRate` / `outcomes` 不得复活**、阈值取最后一条 `apply`、空日志与坏行不抛,
424
+ 以及端到端——真跑 `apply()` 走完一个 turn,读回日志断言 `inject` 带 `inj=`、
425
+ `outcome` 带 `before=write`、`measure ok=false exit=1`、`change` 行都写了且被聚合。
426
+
427
+ ## 已知边界
428
+
429
+ - 「同一文件」按**绝对路径**判定。删了重建同名文件也算同一处——这通常是对的(说明在同一个
430
+ 概念上打转),但如果只是反复改生成文件,用 `excludePaths` 排掉或把 `repeatEditThreshold` 调大。
431
+ - **测量判据是启发式的**:`ops_bash` 跑的是不是真测量,靠 `measureCommands` / `measureIntent`
432
+ 两个正则猜。猜错的代价现在是不对称的——把非测量当测量会漏报,把测量当非测量会误报。
433
+ 默认清单偏向「宁可误报也不漏报」,因为你看到提醒后自己判断的成本很低。
434
+ - `done-state` 认的是**成功返回的** `present` 调用,不是「模型说了一句收尾话」。纯文本终稿靠
435
+ `stuck-gate` 技能的 done-state 自检兜底;若某类任务从不调 `present`,
436
+ 把 `doneOnPresent: false` 关掉更省心。
437
+ - 只在**主会话**生效。多 agent 场景下每个 subagent 各自打转不会被拦——但它们的产物最终
438
+ 汇到 lead,lead 这边的计数仍然有效。
439
+ - 面板是**只读的日志视图**,不是监控:它不写任何数据,也不改变闸门判定。只有显式写
440
+ `logFile: ""` 关掉落盘时,面板才会只剩「没有数据」,一切统计为 0。
441
+ - `firstAction` 的分母是「已被观察到的注入」。注入后 turn 直接结束(没有后续 `tool/call`)
442
+ 不计入,样本少时波动很大——看量级,别当 KPI。
443
+
444
+ ## License
445
+
446
+ MIT
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: stuck-gate
3
+ description: "卡住闸门。Use when stuck: 2+ failed attempts at the same fix, an error repeating unchanged after your change, a problem you cannot reproduce but keep editing code for, any 「我猜是…」 without a probe, or any impulse to keep guessing. Forces five checks before the next attempt: build a red-capable feedback loop, search the exact error, minimize until every element carries weight, write 3-5 falsifiable hypotheses, treat a third failure at one layer as an architecture question."
4
+ metadata:
5
+ version: "1.1"
6
+ author: "Leonlee114514"
7
+ source: "companion skill for the dsh-better-debug plugin"
8
+ ---
9
+
10
+ # Stuck Gate(卡住闸门)
11
+
12
+ Trigger is **self-detection**, not the user's wording. Fire it the first time any of these is true in the current task:
13
+
14
+ - 同一处修了 **2 次以上**,症状没变,或变了但你无法解释为什么。
15
+ - 你正在写第 3 个「再试一次」的命令,而没有新的信息进来。
16
+ - 你刚在心里写了「大概是 / 我猜是 / 应该是版本问题」——**没有探针支撑**。
17
+ - 你不知道怎么让这个问题**稳定复现**,却在继续改代码。
18
+ - 性能/时序类问题你直接开始改实现,没有先测出数字。
19
+
20
+ Fire it **before** the next attempt. Not after.
21
+
22
+ ## 触发前置判断与响应协议
23
+
24
+ - **done-state**:`present` / 终稿答复已发出、无下次修改在即 → 不落闸;新写入重新武装(插件 `doneOnPresent`)。
25
+ - **有进展的收敛 ≠ 卡住**:数字朝目标收敛、每次修改间有测量回路 → 不算「症状没变、没有新信息」。插件 `decayEditsOnVerify` 在每次 verify 后清零连续盲改计数。
26
+ - **任务类型**:写作/收敛类任务的回路是「词数/段数统计 + checklist 断言」,收尾是数字复核 + 清场,不套 commit / 探针 / 事故复盘。
27
+ - **响应协议**:闸门轮把验证/搜索/清场/压缩静默一次性跑完,再给一个结论;禁止「结论 → 工具串 → 又一句结论」。
28
+
29
+ **共同敌人**:用昂贵的动作(猜、从零造、第 4 次重试)逃避便宜的动作(验证、搜索、要现场)。
30
+
31
+ ## The gate: 5 checks, in order, no skipping
32
+
33
+ 1. **回路存在吗?** 必须有一条你**自己能在几秒内跑完、且当前就 red** 的命令(失败测试、最小脚本、`lsp_diagnostics`、一条 grep+diff、一个能稳定打出错误栈的调用)。
34
+ - 建不出来 → **停止修改**。这是环境问题,不是代码问题:向用户要一份能复现的产物(日志、最小 repo、录屏、错误原文),或自己造一个 capture/replay。
35
+ - 非确定性 → 目标不是 100% 复现,而是**把复现率抬到能观测**(循环 N 次、加时间戳、固定种子)。
36
+ 2. **搜过了吗?** 用你的搜索工具查**错误原文整句** + 版本 + 栈顶符号,含 GitHub issue(closed 也要看)。时间盒 **10 分钟**。搜到 → 在自己的机器/版本/数据上验证一遍才算数。搜不到有两种含义:这组合没人踩过,或你的关键词是错的(换语言、换术语、去掉自造名词再搜)。
37
+ 3. **最小化了吗?** 把输入/配置/代码砍到「再砍就不报错」。每个残留元素必须**承重**——不承重的元素是噪声,说明你在错误的现场。
38
+ 4. **有几个可证伪假设?** 写 **3–5 条**,每条格式:`如果 X,那么我改 Y 会看到 Z`。给同行(或先给用户)看一遍再动手。**一次只动一个变量**,探针统一前缀(如 `[DEBUG-a4f2]`)方便一把删干净。
39
+ 5. **三次失败 = 换层,不是第四次尝试。** 同一层连失败三次,说明架构假设错了:往上走一层(这真的该由这个组件负责吗?这个 seam 存在吗?),而不是在同层继续猜。
40
+
41
+ ## 收尾(修好之后必做,否则闸门白跑)
42
+
43
+ - 回归测试写在修复**之前**;只在有正确 seam 时才写,别为了测试去新造 seam。
44
+ - commit message 里写下**正确的那个假设**(以及被排除的那几个),这是给下一个人的地图。
45
+ - 探针清理:`grep -rn "DEBUG-a4f2"` 必须为空。
46
+ - 把这次的事故复盘写成文档(issue / 笔记 / wiki 都行),让方法论与具体案例之间有据可查。
47
+
48
+ ## 与 `dsh-better-debug` 插件的关系
49
+
50
+ 插件只看**行为**:同一文件反复改、同一报错反复吃、改完不验证。它命中时会注入一句话提醒,
51
+ 那句提醒指回本技能。两者互相独立——插件不依赖本技能存在,本技能也不需要插件。
52
+ 插件负责「你想不起来的那一刻」,本技能负责「想起来了该做什么」。
package/client.js ADDED
@@ -0,0 +1,71 @@
1
+ window.__ModuleLoader__.load({
2
+ id: "dsh-better-debug",
3
+ factory: (require) => {
4
+ var module = { exports: {} };
5
+ var exports = module.exports;
6
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
7
+ let react = require("react");
8
+ let react_jsx_runtime = require("react/jsx-runtime");
9
+
10
+ //#region styles
11
+ // 面板本体在 web/index.html 里(原生 JS/SVG,不经过 React),
12
+ // 这里只负责给 iframe 一个能撑满 section 的壳。
13
+ const css = [
14
+ ".bd-view{display:flex;flex-direction:column;width:100%;min-height:0}",
15
+ ".bd-frame{flex:1;width:100%;min-height:640px;border:0;display:block;background:transparent}",
16
+ ".bd-fail{font-size:12px;opacity:.72;padding:8px 0}"
17
+ ].join("");
18
+ const tagId = "dsh-better-debug/style";
19
+ if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
20
+ const tag = document.createElement("style");
21
+ tag.dataset.plugin = "dsh-better-debug";
22
+ tag.dataset.pluginCss = tagId;
23
+ tag.textContent = css;
24
+ document.head.appendChild(tag);
25
+ }
26
+ //#endregion
27
+
28
+ /** 面板地址。相对路径即可:和 DSH 同源,由插件的 webServer 前缀路由提供。 */
29
+ const panelSrc = "/better-debug/index.html";
30
+
31
+ function BetterDebugPanel() {
32
+ return react_jsx_runtime.jsx("div", {
33
+ className: "bd-view",
34
+ children: react_jsx_runtime.jsx("iframe", {
35
+ className: "bd-frame",
36
+ src: panelSrc,
37
+ title: "better-debug 观测面板"
38
+ })
39
+ });
40
+ }
41
+
42
+ /**
43
+ * 不声明静态 inject —— 和宿主侧同一个理由。
44
+ *
45
+ * cordis 的 `Fiber._refresh()` 只要声明的服务拿不到就不执行 apply:没有报错、
46
+ * 没有日志,面板安安静静地不存在。`slots` 属于前端 runtime,版本差异下未必有;
47
+ * 而它不在时我们本来就该只是「不注册面板」,而不是整段代码不跑。
48
+ * 所以改成 ctx.inject 动态订阅:服务在就挂,不在就跳过。
49
+ */
50
+ const inject = [];
51
+
52
+ function apply(ctx) {
53
+ const mount = (slotCtx) => {
54
+ const slots = slotCtx?.slots;
55
+ if (slots === void 0 || typeof slots.inject !== "function") return;
56
+ slots.inject("settings.section", () => slots.register({
57
+ name: "settings.section",
58
+ id: "better-debug",
59
+ order: 40,
60
+ label: "better-debug"
61
+ }, BetterDebugPanel));
62
+ };
63
+ if (typeof ctx?.inject === "function") ctx.inject(["slots"], mount);
64
+ else mount(ctx);
65
+ }
66
+
67
+ exports.apply = apply;
68
+ exports.inject = inject;
69
+ return module.exports;
70
+ }
71
+ });
@@ -0,0 +1,52 @@
1
+ # dsh-better-debug — bundle manifest entry.
2
+ #
3
+ # Mounts the gate with defaults on. Override any key under the same id in your
4
+ # own profile's cordis.patch.yml:
5
+ #
6
+ # enabled: false → installed but inert (no listener registered)
7
+ # repeatEditThreshold: 4 → loosen "same file re-edited" from 3 to 4
8
+ # repeatErrorThreshold: 3 → loosen "same error repeated" from 2 to 3
9
+ # noVerifySteps: 3 → 改完 N 步没测量才「上膛」(不等于立刻提醒)
10
+ # maxInjectsPerTurn: 5 → 单轮最多提醒 5 次(默认 3)
11
+ # changedWindow: 10 → 注入后多少步内算「转向」窗口(默认 6)
12
+ # measureCommands: "npm|pnpm" → 覆盖「什么命令算测量」的正则
13
+ # measureIntent: "验证|测试" → 覆盖「描述里出现什么算测量意图」的正则
14
+ # excludePaths: "vendor/" → 覆盖「哪些路径不算盲改」的正则
15
+ # decayEditsOnVerify: false → 关闭「测量后清零连续盲改计数」,退回旧 A 行为
16
+ # doneOnPresent: false → 关闭交付态休眠,交付后仍注入
17
+ # panel: false → 不挂 /better-debug 只读面板
18
+ # logFile: "~/my.log" → 日志换个位置(支持 ~ 展开)
19
+ # logFile: "" → 显式关闭落盘(面板就只剩不到数据了,通常不要)
20
+ #
21
+ # 日志默认落在 $DSH_HOME/logs/better-debug.log(没设 DSH_HOME 就是
22
+ # ~/.dsh/logs/better-debug.log)。开箱就有数据,不用先配置。
23
+ #
24
+ # If you already registered this plugin by hand (manual link + your own
25
+ # `- id: better-debug` row), remove that row first: two rows with the same
26
+ # loader entry id make cordis reject the duplicate.
27
+ #
28
+ # Do NOT rename this id to differ from your profile row. Two *different* ids
29
+ # pointing at the same package name mount the plugin twice — two listener sets,
30
+ # every reminder injected twice, every log line doubled.
31
+ #
32
+ # NOTE: no `inject:` here on purpose. cordis resolves entry options.inject into
33
+ # the plugin's dependency set (cordis-plugin-loader `Inject.resolve(
34
+ # entry.options.inject, fiber.inject)`), and Fiber._refresh() skips apply()
35
+ # entirely — silently, with no log line — when any declared service is missing.
36
+ # `skills` comes from @deepseek-ai/dsh-skill, which a trimmed profile or another
37
+ # distribution may not mount; the gate does not need it. Both optional services
38
+ # (skills / webServer) are subscribed dynamically via ctx.inject instead.
39
+ #
40
+ # NOTE: no `config:` block here either, and that one is about the market.
41
+ # DshMarket's hot mount replays *plain* insert rows only — `scanPatch()` in
42
+ # dshmarket/lib/hot.js stops at any other key and reports
43
+ # "the bundle patch has a config block; hot-mount replays plain insert rows
44
+ # only". A config block therefore turns "enable" in the market into "nothing
45
+ # happens until you restart DSH". Every default below is already applied by
46
+ # normalizeConfig() in lib/index.js, so the block bought only self-documentation
47
+ # at the price of a silent no-op for new users. Keep this row to id + name; set
48
+ # overrides under the same id in your own profile's cordis.patch.yml, where a
49
+ # config block is expected and hot mount is not involved.
50
+ - insert:
51
+ - id: better-debug
52
+ name: dsh-better-debug