dsh-jev-tools-continued 0.0.0-stage → 0.2.0

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 (122) hide show
  1. package/CHANGELOG.en.md +449 -0
  2. package/CHANGELOG.i18n.yaml +13 -0
  3. package/CHANGELOG.md +357 -0
  4. package/LICENSE +21 -0
  5. package/README.en.md +210 -0
  6. package/README.i18n.yaml +13 -0
  7. package/README.md +209 -2
  8. package/client/client.js +755 -0
  9. package/cordis.patch.yml +30 -0
  10. package/docs/banner.png +0 -0
  11. package/docs/dev-workflow.md +414 -0
  12. package/docs/s0-trigger-rate.md +168 -0
  13. package/icon.svg +16 -0
  14. package/lib/backends/jev.d.ts +69 -0
  15. package/lib/backends/jev.d.ts.map +1 -0
  16. package/lib/backends/jev.js +151 -0
  17. package/lib/backends/jev.js.map +1 -0
  18. package/lib/backends/types.d.ts +104 -0
  19. package/lib/backends/types.d.ts.map +1 -0
  20. package/lib/backends/types.js +12 -0
  21. package/lib/backends/types.js.map +1 -0
  22. package/lib/budget.d.ts +60 -0
  23. package/lib/budget.d.ts.map +1 -0
  24. package/lib/budget.js +70 -0
  25. package/lib/budget.js.map +1 -0
  26. package/lib/calibrate.d.ts +162 -0
  27. package/lib/calibrate.d.ts.map +1 -0
  28. package/lib/calibrate.js +269 -0
  29. package/lib/calibrate.js.map +1 -0
  30. package/lib/config.d.ts +261 -0
  31. package/lib/config.d.ts.map +1 -0
  32. package/lib/config.js +194 -0
  33. package/lib/config.js.map +1 -0
  34. package/lib/context-cache.d.ts +59 -0
  35. package/lib/context-cache.d.ts.map +1 -0
  36. package/lib/context-cache.js +116 -0
  37. package/lib/context-cache.js.map +1 -0
  38. package/lib/credentials.d.ts +32 -0
  39. package/lib/credentials.d.ts.map +1 -0
  40. package/lib/credentials.js +44 -0
  41. package/lib/credentials.js.map +1 -0
  42. package/lib/degrade.d.ts +36 -0
  43. package/lib/degrade.d.ts.map +1 -0
  44. package/lib/degrade.js +41 -0
  45. package/lib/degrade.js.map +1 -0
  46. package/lib/features/prune.d.ts +116 -0
  47. package/lib/features/prune.d.ts.map +1 -0
  48. package/lib/features/prune.js +574 -0
  49. package/lib/features/prune.js.map +1 -0
  50. package/lib/features/screen.d.ts +112 -0
  51. package/lib/features/screen.d.ts.map +1 -0
  52. package/lib/features/screen.js +130 -0
  53. package/lib/features/screen.js.map +1 -0
  54. package/lib/features/skill-suggest.d.ts +68 -0
  55. package/lib/features/skill-suggest.d.ts.map +1 -0
  56. package/lib/features/skill-suggest.js +283 -0
  57. package/lib/features/skill-suggest.js.map +1 -0
  58. package/lib/host.d.ts +280 -0
  59. package/lib/host.d.ts.map +1 -0
  60. package/lib/host.js +15 -0
  61. package/lib/host.js.map +1 -0
  62. package/lib/http.d.ts +71 -0
  63. package/lib/http.d.ts.map +1 -0
  64. package/lib/http.js +162 -0
  65. package/lib/http.js.map +1 -0
  66. package/lib/i18n.d.ts +372 -0
  67. package/lib/i18n.d.ts.map +1 -0
  68. package/lib/i18n.js +254 -0
  69. package/lib/i18n.js.map +1 -0
  70. package/lib/index.d.ts +44 -0
  71. package/lib/index.d.ts.map +1 -0
  72. package/lib/index.js +268 -0
  73. package/lib/index.js.map +1 -0
  74. package/lib/keys.d.ts +90 -0
  75. package/lib/keys.d.ts.map +1 -0
  76. package/lib/keys.js +131 -0
  77. package/lib/keys.js.map +1 -0
  78. package/lib/ledger-domain.d.ts +169 -0
  79. package/lib/ledger-domain.d.ts.map +1 -0
  80. package/lib/ledger-domain.js +338 -0
  81. package/lib/ledger-domain.js.map +1 -0
  82. package/lib/ledger.d.ts +243 -0
  83. package/lib/ledger.d.ts.map +1 -0
  84. package/lib/ledger.js +239 -0
  85. package/lib/ledger.js.map +1 -0
  86. package/lib/memo.d.ts +32 -0
  87. package/lib/memo.d.ts.map +1 -0
  88. package/lib/memo.js +62 -0
  89. package/lib/memo.js.map +1 -0
  90. package/lib/notify.d.ts +78 -0
  91. package/lib/notify.d.ts.map +1 -0
  92. package/lib/notify.js +122 -0
  93. package/lib/notify.js.map +1 -0
  94. package/lib/proxy.d.ts +40 -0
  95. package/lib/proxy.d.ts.map +1 -0
  96. package/lib/proxy.js +136 -0
  97. package/lib/proxy.js.map +1 -0
  98. package/lib/request.d.ts +99 -0
  99. package/lib/request.d.ts.map +1 -0
  100. package/lib/request.js +168 -0
  101. package/lib/request.js.map +1 -0
  102. package/lib/source.d.ts +46 -0
  103. package/lib/source.d.ts.map +1 -0
  104. package/lib/source.js +35 -0
  105. package/lib/source.js.map +1 -0
  106. package/lib/status.d.ts +42 -0
  107. package/lib/status.d.ts.map +1 -0
  108. package/lib/status.js +214 -0
  109. package/lib/status.js.map +1 -0
  110. package/lib/tokens.d.ts +26 -0
  111. package/lib/tokens.d.ts.map +1 -0
  112. package/lib/tokens.js +57 -0
  113. package/lib/tokens.js.map +1 -0
  114. package/lib/tools/jev-ask.d.ts +44 -0
  115. package/lib/tools/jev-ask.d.ts.map +1 -0
  116. package/lib/tools/jev-ask.js +208 -0
  117. package/lib/tools/jev-ask.js.map +1 -0
  118. package/lib/tools/jev-gate.d.ts +79 -0
  119. package/lib/tools/jev-gate.d.ts.map +1 -0
  120. package/lib/tools/jev-gate.js +412 -0
  121. package/lib/tools/jev-gate.js.map +1 -0
  122. package/package.json +169 -4
@@ -0,0 +1,30 @@
1
+ # dsh-jev-tools-continued bundle layer: Jev as a judgment primitive inside DeepSeek Harness.
2
+ #
3
+ # Mounts one host plugin. It contributes:
4
+ # 1. semantic pruning of oversized tool results (tools/post-execute)
5
+ # 2. screening of fetched pages for injected instructions (web_fetch / web_search)
6
+ # 3. skill suggestion when the skill catalog is large (agent/pre-step, advisory only)
7
+ # 4. the jev_ask and jev_gate tools
8
+ # 5. a judgment ledger persisted through the storage domain
9
+ #
10
+ # Requires TYPESAFE_API_KEY (environment variable or the settings card).
11
+ # With no key configured the plugin still mounts, every capability stays
12
+ # completely inert, and no network request is made.
13
+ #
14
+ # Privacy: once a key is configured, tool-result and fetched-page content is sent
15
+ # to the configured System One endpoint (api.typesafe.ai unless `baseUrl` names a
16
+ # self-hosted or gateway deployment) for judging. Every capability can be turned
17
+ # off separately in Settings -> Plugins -> dsh-jev-tools-continued, and disabling takes
18
+ # effect immediately.
19
+ #
20
+ # The row id is the package name on purpose. DSH addresses a bundle's settings
21
+ # namespace by its **mount row id** — `SettingsForms.describe()` publishes
22
+ # `entry.options.id`, and a write resolves the same way — while this bundle's own
23
+ # card (the occupant of `plugins.bundle.config`) and the plugin page's config seat
24
+ # are keyed by the **package name**. Mounted as `jev-tools` the two disagree, and
25
+ # the card reads no namespace at all: every toggle stays disabled and the endpoint
26
+ # fields stay blank, with no error printed anywhere. Keep the row id and the
27
+ # package name equal — `test/bundle-contract.test.ts` enforces it.
28
+ - insert:
29
+ - id: dsh-jev-tools-continued
30
+ name: dsh-jev-tools-continued
Binary file
@@ -0,0 +1,414 @@
1
+ # DSH 本地 bundle 开发工作流(实测)
2
+
3
+ > 这些是开发 `dsh-jev-tools` 过程中在**本机 DSH 0.1.6-alpha.2** 上实测得到的规则,不是文档转述。
4
+ > 每一条都花过时间,写下来避免重复踩。
5
+
6
+ ## 1. 什么改动需要什么级别的重载
7
+
8
+ > ⚠️ **先决条件:profile 里的 `dsh-jev-tools` 必须指向开发目录。** 下表全部建立在这一点上。
9
+ > 插件发布后按版本号安装时,`profiles/web/node_modules/dsh-jev-tools` 是**真实拷贝**,
10
+ > 于是「改 `src/` → `npm run build` → 重启宿主」这条本来正确的链会**静默失效**:宿主正常启动、
11
+ > 无警告、跑的还是 registry 上那份。**2026-09-22 实测踩到**——一次已经改好的修复因此被
12
+ > 误判为「没生效」,白查了一轮。判断当前是哪一种、以及怎么切成链接,见 **§15**。
13
+
14
+ | 改动 | 生效方式 | 原因 |
15
+ |---|---|---|
16
+ | host 半边 `lib/*.js` **内容** | **必须重启 `dsh web`**(且 profile 已 link 到开发目录,见上) | **关开 bundle 无效**——Node ESM 按 URL 缓存模块,重挂同一路径拿到的是旧模块。见下方警告 |
17
+ | `package.json` 里新增/修改 **`dsh.client`** | **必须重启宿主** | 见 §2,`client-modules` 按包名缓存扫描结果 |
18
+ | `client/*.js` **内容**(manifest 不变) | HMR watch 可接 | `client-modules` 有 `artifactBaseline` / `rebuilt()` 的 fs watch |
19
+ | 新增 host 行(patch 里加 row) | `install_bundle`(新 bundle)或重启 | — |
20
+
21
+ > ⚠️ **这一行曾经写错,代价很大。** 早期的表格写的是「关→开 `set_bundle` 即可」,实测**不成立**:S4–S6 的宿主代码因此一度**从未执行过**——每次看起来都"重载成功"(两次 `applied`、无 warnings),但跑到的是缓存的旧模块。`set_bundle` 会让行卸载重挂,而 ESM 模块注册表按 **URL** 缓存,同一文件路径第二次 import 直接返回旧实例。
22
+ >
23
+ > **判定方法**:别信 `applied`,去看一个只有新代码才会有的可观测差异(例如 `Tool.listTools` 里新注册的工具)——如果它没出现,就是没生效。
24
+
25
+ **推论:`dsh.client` 从第一次安装就该声明好。** 后补要被缓存的 `null` 挡住,只能重启。
26
+
27
+ ## 2. 为什么后补 `dsh.client` 必须重启(源码依据)
28
+
29
+ `packages/client/modules/src/index.ts`:
30
+
31
+ ```ts
32
+ private resolveMeta(loaderName: string, baseUrl: string): ResolvedPkgMeta | null {
33
+ const sourceKey = this.sourceKey(loaderName, baseUrl)
34
+ const cached = this.pkgMeta.get(sourceKey)
35
+ if (cached !== undefined) return cached // ← 命中即返回
36
+ ...
37
+ const decl = parseDshClient(packageName, pkg.dsh?.client)
38
+ if (decl === undefined || decl.platform !== 'web') {
39
+ this.pkgMeta.set(sourceKey, null) // ← 缓存"不是客户端行"
40
+ return null
41
+ }
42
+ ...
43
+ }
44
+
45
+ private sourceKey(loaderName, baseUrl) { return `${baseUrl}\0${loaderName}` }
46
+ ```
47
+
48
+ `sourceKey` 只含 `baseUrl` + 包名,**关开 bundle 不会改变它**。所以包在"还没有 `dsh.client`"时被扫过一次,就会把 `null` 缓存到进程结束——之后无论怎么重挂都不会再被当作客户端行。
49
+
50
+ 文件头也写明了:*"Scanning is incremental per package — there is no full-rescan code path."*
51
+
52
+ **实测表现**(`Slots.listSubTree { root: 'plugins.bundle.config' }` 的 `occupants`):
53
+
54
+ | 状态 | occupants |
55
+ |---|---|
56
+ | 后补 `dsh.client`、未重启(关开 bundle 也无效) | `[]` |
57
+ | **重启宿主 + 刷新页面后** | `[{ registrant: 'lc', key: 'dsh-jev-tools', active: true }]` ✅ |
58
+
59
+ 所以这条结论是**实测确认**的,不只是源码推断。另外客户端 inspect 查询是**由已连接页面回答**的,两层条件都要满足:宿主扫描到 **且** 页面重新拉取过客户端 bundle——只重启不刷新,`occupants` 仍会是空。
60
+
61
+ ## 3. `install_bundle` 不能用于已存在的本地包
62
+
63
+ 对已经以 `link:` 形式装好的包再调一次 `install_bundle`,返回:
64
+
65
+ ```
66
+ application: "failed", error: { code: "ambiguous-install" }, changed: false
67
+ ```
68
+
69
+ `changed: false` 意味着**什么都没被改动**,bundle 仍在 profile 的 `dependencies` 与 `dsh.profile.bundles` 里。安全的迭代方式是 §1 的关开,而不是重装。
70
+
71
+ ## 4. npm 上的 DSH 包严重滞后
72
+
73
+ 实测(`npm view`):
74
+
75
+ | 包 | registry | 本机部署 |
76
+ |---|---|---|
77
+ | `@deepseek-ai/dsh-settings` | `0.0.1-rc.1` | `0.1.6-alpha.2` |
78
+ | `@deepseek-ai/dsh-tools` | `0.0.1-rc.1` | `0.1.6-alpha.2` |
79
+ | `@deepseek-ai/dsh-credentials` | `0.0.1-rc.1` | `0.1.6-alpha.2` |
80
+ | `@deepseek-ai/schemastery` | `3.18.2` | `3.18.2` ✅ |
81
+
82
+ **所以不要从这些包 import 类型**——会按陈旧签名编译。本插件改用**结构化类型**(`src/host.ts`),真实契约是服务名字符串。副作用:这也是抗版本漂移的正确姿势,而版本漂移正是社区插件的头号差评来源。
83
+
84
+ `@deepseek-ai/schemastery` 是唯一版本对得上的,可以正常依赖。
85
+
86
+ ## 5. 客户端槽位:用哪个
87
+
88
+ | 槽位 | 现状 | 说明 |
89
+ |---|---|---|
90
+ | `settings.plugin.item` | **不存在** | map-tools 的 `client/client.js` 注册到这里。槽位不存在时 `inject` 不会触发,卡片静默不挂载。**官方对应槽位叫 `plugins.item`**——`ui-settings-plugins/src/client/index.ts` 里 shell / agent-loop / subagent / web-search 四张卡都注册在那里 |
91
+ | `plugins.bundle.config` | **可用,本插件用它** | keyed,key = bundle 包名。`ui-plugin-manager` 的 `PluginManagerPage.tsx` 以 `renderSlot('plugins.bundle.config', { view: 'page' }, { entryKey: pkg.name })` 渲染 |
92
+ | `settings.section` | 可用 | 整个独立的设置页(list) |
93
+
94
+ 注册形式已对官方实现核过:`ctx.slots.inject(槽位, () => ctx.slots.register({ name, key }, 组件))`,与 `ui-settings-plugins` 里那四张卡写法一致。
95
+ `ui-plugin-manager` 另有一份 config ledger(`config-ledger.ts` 的 `keysOf('plugins.bundle.config')`),用来知道哪些 bundle 自带配置卡片。
96
+
97
+ ### 5.1 数据怎么读怎么写:只用 `ctx.configForms`,不要直接调 `remote.settings`
98
+
99
+ **实测踩过(2026-09-30)**:卡片占住了座位、`plugins.bundle.config` 也挂上了,但读不到自己的设置——
100
+ 三个开关 disabled、两个端点框 readOnly,界面上**一句错都不报**。原因不是命名空间(那个也一起修了),
101
+ 而是**通道**:浏览器里 `settings.describe()` **只有一个读取方**——设置 UI 自己(`ui-settings` 的
102
+ `SettingsDescribeMirror`,README 原话 "the one `settings.describe` reader in the browser")。第三方卡片
103
+ 直接 `remote.settings.describe()` 拿不到东西,于是永远读到 null。
104
+
105
+ 正确姿势是注入 `configForms`(设置 UI 提供的客户端服务):
106
+
107
+ ```js
108
+ inject: ['slots', 'locale', 'remote', 'remote.credentials', 'configForms']
109
+ const form = ctx.configForms.get('dsh-jev-tools') // 命名空间 = 挂载行 id,见 §5.2
110
+ form.getSnapshot() // { status, value, base, user, revision, writable, mode }
111
+ form.subscribe(fn) // 共享镜像变化时回调(任何编辑者的写入都会到这里)
112
+ await form.mutate([{ op: 'set', path: ['prune', 'enabled'], value: false }], revision)
113
+ ```
114
+
115
+ 插件页上四个官方设置页(shell / agent-loop / subagent / web-search)全都走这条;`get` 的命名空间就是
116
+ `settings.describe()` 公布的 `entry.options.id`,也就是**挂载行的 id**。
117
+
118
+ ### 5.2 设置命名空间 = 挂载行 id,而且 schema 必须有 `.volatile()`
119
+
120
+ 两件事都得对,否则卡片同样静默:
121
+
122
+ 1. **行 id 必须等于卡片问的那个名字**。`SettingsForms.describe()` 公布的是 `entry.options.id`(`cordis.patch.yml`
123
+ 里 `- id:` 那一行,非包名),写入也按它解析。行 id 叫 `jev-tools` 而卡片问 `dsh-jev-tools` → 取不到。
124
+ 本插件的行 id 现在就是包名,`test/bundle-contract.test.ts` 会拦。
125
+ 2. **schema 里至少要有一个 `.volatile()`**。`volatileForm(schema)` 对一个 volatile 字段都没有的 schema 返回
126
+ `undefined`,`describe()` 直接把整条跳过——连命名空间都不会出现;而且**只有标了 volatile 的路径才允许写**。
127
+ 卡片画的字段(总开关、密钥变量名、端点、模型、两个能力开关)都标了。
128
+ 注意 `.volatile()` 会把该字段的解析结果包成标记对象,所以配置要走 `Config['~standard'].validate()`
129
+ 再解包(`src/config.ts` 的 `plainConfig`),否则 `model` 会是 `[object Object]`。
130
+
131
+ ## 6. 命令速查
132
+
133
+ ```powershell
134
+ # 构建 + 测试(pretest 会自动构建,测试跑的是 lib/ 产物)
135
+ npm test
136
+
137
+ # 重载 host 半边(改 lib/ 之后)
138
+ # plugin_manager set_bundle target=dsh-jev-tools enabled=false
139
+ # plugin_manager set_bundle target=dsh-jev-tools enabled=true
140
+
141
+ # 验证客户端槽位占用
142
+ # cordis_inspect_query platform=client provider=Slots method=listSubTree
143
+ # input={"root":"plugins.bundle.config"}
144
+
145
+ # S0 触发率(无需 key、无网络)
146
+ node scripts/trigger-rate.ts --json trigger-rate.json
147
+ ```
148
+
149
+ ## 7. 测试跑的是 `lib/` 而不是 `src/`
150
+
151
+ `src/` 里的 import 用 `.js` 扩展名(NodeNext 规范,编译产物需要),所以 Node 直接跑 `.ts` 源码时解析不到 `./tokens.js`。测试改为 import `../lib/*.js`,`pretest` 先构建——**顺带验证了真正会发布的那份产物**。
152
+
153
+ **同一个原因还有两个后果**:
154
+
155
+ - **脚本不能直接 import `src/` 里的模块**(源码的相对 import 带 `.js`,磁盘上只有 `.ts`,Node 不做扩展名改写)。脚本要么 import `lib/`(需先 build),要么自成一体——`scripts/lib/` 只依赖 `node:` 与 `lib/`。
156
+ - **`node --test` 的 strip-only 模式不支持 TS parameter properties**。`constructor (readonly name: string, ...)` 直接抛 `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`;测试是 `.ts` 且不经过 tsc,所以必须显式声明字段再赋值。
157
+
158
+ ## 8. junction / link 安装的包,裸 import 解析不到 profile 的依赖
159
+
160
+ **这一节只在链接形态下成立。** profile 的 `package.json` 把本包写成 `link:…` 时(见 §15),
161
+ `node_modules/dsh-jev-tools` 是以 **junction** 链到开发目录的;按版本号安装时它是真实拷贝,
162
+ 下面这件事不会发生。链接形态下 **Node 的 ESM 会对被导入模块做 realpath**,所以解析裸标识符的起点是**真实路径**,不是 link 路径:
163
+
164
+ ```
165
+ import.meta.url → file:///D:/projects/.../dsh-jev-tools/.probe/probe.mjs ← 已经是真实路径
166
+ await import('zod') → ERR_MODULE_NOT_FOUND ← 在 workspace 树里找不到
167
+ ```
168
+
169
+ **实测确认过,不是推断。** 后果:宿主提供的依赖(`zod`、`@deepseek-ai/*`)**不能裸 import**。本插件的应对是全程用**结构化类型 + 服务名字符串**(`src/host.ts`),台账的域 spec 也因此手写了校验器而不用 zod。
170
+
171
+ ## 9. `dsh plugin` 的真实契约
172
+
173
+ `apps/cli/src/args.ts`:
174
+
175
+ ```
176
+ dsh plugin --profile <name> <pnpm 参数…>
177
+ ```
178
+
179
+ - `--profile` 是 **`requiredOption`**——所以 `dsh plugin add <pkg>` 是**错的**(缺 `--profile`,Commander 直接拒)
180
+ - `--profile` 之后的参数**原样转发给 profile 目录里的 `pnpm`**(`add` / `remove` / `why` / …)
181
+ - **`add` 是"装包 + 启用"一步完成的**,插件页面那条路只是同一件事的另一个入口。
182
+
183
+ **这一条以前写反了**(原文是「它只装包,不启用」),2026-09-22 读源码更正。pnpm 成功后,
184
+ `plugin-manager` 会跑一次 `reconcile()`(`packages/boot/plugin-manager/src/operations.ts`):
185
+ 遍历**新装的依赖**,凡是声明了 `dsh.bundle` 的就把包名 push 进 `dsh.profile.bundles` 并存盘。
186
+ 它由 `:160` 的 `if (exitCode === 0 && options.activateNewBundles !== false)` 触发,而
187
+ `apps/cli/src/plugin.ts` 调用时**没有传** `activateNewBundles`,所以 `dsh plugin` 这条路上它必然执行。
188
+
189
+ **推论(海报和 README 都依赖它)**:`npm install dsh-jev-tools` **不能**让 DSH 加载这个插件。
190
+ 它只把包放进 `node_modules`,而 npm 不知道 `dsh.profile.bundles` 这个字段;DSH 的加载器只解析
191
+ 那个列表(`packages/boot/app-boot/src/profile.ts`)。结果就是包在磁盘上、插件一个字节都没跑起来。
192
+ 唯一能让它生效的入口是 `dsh plugin --profile <name> add`,或插件页面。
193
+
194
+ ## 10. 这台机器上的 shell 不是 UTF-8 安全的,读也不行
195
+
196
+ PowerShell 按 GBK 解码 UTF-8 文件:控制台输出变乱码,**而且行数会少**——3 字节汉字的第三个字节被当成 GBK 前导字节,把后面的换行吞掉了。
197
+
198
+ 实测:我曾据 PowerShell 得出某文档只有 112 行、疑似损坏的结论,**实际它是 155 行且完好**。
199
+
200
+ **规则:统计/校验非 ASCII 文件一律用 Node 显式 `utf8` 读,或直接看 `edit` / `read` 工具的结果。改含非 ASCII 的源文件绝不用 `Get-Content` + `Set-Content`(会写成乱码,我因此重写过一次 `prune.ts`)。**
201
+
202
+ **同一个坑的第三种形态(2026-09-22 实测)**:PowerShell 5.1 的 `>` 与 `Out-File` **默认写 UTF-16LE**。用它把生成好的文本落盘、再交给按 UTF-8 读的工具,字节就被改写了——`node scripts/release-notes.ts 0.1.7 > notes.md` 之后 `gh release create --notes-file notes.md`,GitHub 上的 Release 正文变成一串 `^@`(每个字符之间夹一个 NUL:4286 字节的正文被读成 9952 个字符的乱码)。
203
+
204
+ 需要字节不被改写时:
205
+
206
+ | 场景 | 用 | 不要用 |
207
+ |---|---|---|
208
+ | 程序的 stdout 直接落盘 | `cmd /c "node x.ts > out.md"`(cmd 的重定向按字节写) | PowerShell 的 `>` / `Out-File` |
209
+ | 自己构造内容 | `write` 工具,或 Node 的 `fs.writeFileSync(..., 'utf8')` | `Set-Content` |
210
+
211
+ 注意这条**只影响本地手工操作**:CI 里 `shell: bash` 的 `>` 是按字节写的,所以 workflow 内的同一条命令没有这个问题——而在本机复现 CI 步骤时就会撞上。
212
+
213
+ ## 11. 双语文档的维护约定
214
+
215
+ `README.md` + `README.en.md`、`CHANGELOG.md` + `CHANGELOG.en.md`:**每份文档都是三个兄弟文件**——一个不加后缀的 `foo.md`、一个带语言后缀的 `foo.<lang>.md`、外加一个 `foo.i18n.yaml`。两份内容是**对等的两份正文**,不是"原文 + 摘要"。
216
+
217
+ **一对文档是三个兄弟文件**:默认语言一份 `foo.md`、可切换的一份 `foo.<lang>.md`、外加 `foo.i18n.yaml` 记录两侧在上一次确认一致时的 **git blob 哈希**:
218
+
219
+ ```bash
220
+ git hash-object README.md README.en.md
221
+ ```
222
+
223
+ **改任一侧,必须同步另一侧并重新记录**,否则 `test/docs.test.ts` 直接红。
224
+
225
+ **`test/docs.test.ts` 强制七件事**(这是本项目的 CI,没有别的东西在守约定):
226
+
227
+ 1. 每对文档三个文件齐全,且记录里点名的文件真的存在;
228
+ 2. 记录的哈希与当前内容一致——**改了任一侧而没重新记录,就是红的**;
229
+ 3. 每侧都有语言切换行(`[English](foo.en.md)` ↔ `[中文](foo.md)`);
230
+ 4. 两侧**结构镜像**:标题层级顺序、列表项数、表格行列数、代码块语言、链接目标;
231
+ 5. 行内锚点在**该侧自己的标题**里能解析(标题是翻译的,`#v01-boundaries` 与 `#v01-的边界` 是同一个目标,所以第 4 项把锚点归一化掉,再由这一项单独校验);
232
+ 6. **配对文档不得链接到被 gitignore 的文件**——那对克隆仓库的人是死链,而本地看起来完全正常;
233
+ 7. 文档里声明的测试数量与实际测试数一致。
234
+
235
+ **它守不住的那一半要写清楚:绿灯只意味着"在这份内容上确认过一致",不意味着两侧说的是同一件事。** 翻译是否忠实、术语是否得当、读起来是否自然,是评审的事,哈希管不了。
236
+
237
+ **一条由此产生的约定**:文档里可以写测试数量,但只能是**当前版本**的数量——第 7 项会数出 `test/*.test.ts` 里的测试数并核对每一处声明。这个数字在本项目里漂移过四次(136 → 160 → 183 → 189),每次都让文档短暂地撒谎,所以现在它漂不动了。旧版本的 changelog 条目**不要**写测试数,那会变成一句关于当下的陈述。
238
+
239
+ (DSH 自己用 `pnpm run verify-translation-pairing --write <path>`,那个脚本在 harness checkout 里,独立 bundle 跑不了;`git hash-object` 不需要仓库、算出的 blob 哈希一致,格式兼容。本项目的 blob 哈希由 `test/docs.test.ts` 用 `node:crypto` 直接算,连 git 都不需要。)
240
+
241
+ ## 12. 哪些文件不上传:`notes/` 与本地工作文档
242
+
243
+ 仓库里有两个不同的位置,分界线是"陌生人克隆下来有没有用":
244
+
245
+ | 位置 | 上传? | 放什么 |
246
+ |---|---|---|
247
+ | `docs/` | **是** | 项目文档:开发踩坑(本文件)、实测依据(`s0-trigger-rate.md`)。它们是别人理解这个项目为什么这么设计所需要的东西 |
248
+ | `notes/` | **否**(已 gitignore) | 作者自己的材料:立项计划、草稿、调研、会话笔记。**不被任何已上传的文档引用**——第 6 项检查就是防这个 |
249
+
250
+ 所以:**开发计划之类的放 `notes/`,不要放 `docs/`。** 原始立项文档就在 `notes/dsh-jev-插件开发项目.md`。
251
+
252
+ `.gitignore` 里写了这条规则和它的理由;第 6 项检查保证"不上传"和"不被引用"这两件事不会各自漂移——一旦某个已上传的文档链接进 `notes/`,测试立刻红。
253
+
254
+ ## 13. Node 的删除在这台机器上会被静默忽略
255
+
256
+ 用 Node 删文件会**不报错、也不生效**:
257
+
258
+ ```js
259
+ fs.rmSync('x.md') // 不抛异常
260
+ fs.existsSync('x.md') // 同一个进程里立刻检查:仍然是 true
261
+ ```
262
+
263
+ 实测确认过(不是推断),两个进程都看得见这个文件仍然存在。用 PowerShell 的 `Remove-Item` 则**立刻生效且持久**。
264
+
265
+ 所以这台机器上正确的分工是**反直觉的**:
266
+
267
+ | 操作 | 用 | 不要用 |
268
+ |---|---|---|
269
+ | 读/改含非 ASCII 的文本 | `edit` / `write` / `read` 工具,或 Node 显式 `utf8`(§10) | PowerShell 的 `Get-Content`/`Set-Content` |
270
+ | **删除、移动、重命名文件** | PowerShell(`Remove-Item` / `Move-Item`) | **Node 的 `rmSync`** |
271
+
272
+ (这条和 §10 正好互补:shell 不能碰文本,Node 不能碰删除。两个都踩过一次才发现。)
273
+
274
+ ## 14. 版本与发布策略:文档改动不单独发版
275
+
276
+ **2026-09-21 犯过一次,代价是版本历史被污染。** 一天里发了 `0.1.0`–`0.1.5` 六个版本,其中
277
+ `0.1.1`(README 徽章与发布状态措辞)、`0.1.3`(README 重写)**纯属文档改动**;
278
+ `0.1.4` / `0.1.5` 是同一个第三方清单字段的"加字段 + 改字段"两次抖动。
279
+ 下游任何按 SemVer 判断"要不要跟进"的工具(Dependabot、Renovate)因此白跑四轮。
280
+
281
+ 规则(按此执行,不再例外):
282
+
283
+ | 改动类型 | 发版? |
284
+ |---|---|
285
+ | 运行时行为(`src/`) | **发** |
286
+ | 安装/打包方式(`prepare`、`files`、`exports`、`dsh.bundle`) | **发**——`0.1.2` 属于这类,合理 |
287
+ | 第三方清单/元数据字段(如 `dshWorkshop`) | 跟随它所属的那次代码发版;**单独发不算理由** |
288
+ | 文档、注释、README、CHANGELOG 措辞 | **不发**,跟随下一次代码发版一起进包 |
289
+
290
+ npm 页面上的 README 取自发布时的 tarball,但"README 想立刻更新"**不是**发版理由——
291
+ 下一次发版自然就同步了。
292
+
293
+ **同一个字段不要发两次。** `0.1.4` 的教训:第三方清单应当**先在本地用对方自己的校验器跑通**,
294
+ 再提交并发版(`node <workshop>/scripts/intake.mjs validate submission.json`)。
295
+ 先发版、再发现 `install.adapter` 写错、再发一次修,这一轮完全可以避免。
296
+
297
+ ### 发版前清单
298
+
299
+ 1. `npm test` 全绿;
300
+ 2. `CHANGELOG` 中英两侧已更新,并用 `git hash-object` 重录进 `*.i18n.yaml`;
301
+ 3. 涉及第三方格式时,**对方的校验器**已经通过;
302
+ 4. `npm publish --dry-run` 看一眼 tarball 内容与版本号;
303
+ 5. 当天已经发过版时,先问一句"这几条能不能合成一次发"。
304
+
305
+ (本文档本身的改动就是这条规则的第一个例子:它**没有**伴随任何版本号。)
306
+
307
+ ### 发版动作:两步,中间是人(2026-09-22 起)
308
+
309
+ 打 tag 之后 workflow 只把包 **stage 到 npm 暂存区**,不公开。剩下两步由人做:
310
+
311
+ ```powershell
312
+ npm stage list dsh-jev-tools # 拿 <stage-id>
313
+ npm stage approve <stage-id> # 会要求 2FA;也可在 npmjs.com 的 Staged Packages 页点 Approve
314
+ gh release edit v0.1.8 --draft=false # 把 workflow 留下的草稿 Release 转正
315
+ ```
316
+
317
+ **为什么这样设计**:trusted publisher 的 Allowed actions 刻意只留 `npm stage publish`(不勾 `npm publish`)。因此**一个被攻陷的 workflow 无法自己把包推给全世界**——tag 表示"这是候选",2FA 那一下才表示"这是发布"。Release 也只能先是草稿:包还没公开时先发公告,正是这套流程要消灭的那种错误。
318
+
319
+ 三条实测约束:
320
+
321
+ - **`npm stage` 需要 npm >= 11.15.0**(trusted publishing 只要 >= 11.5.1)。所以 workflow 里装的是 `npm@^11.15.0` 而**不是** `@latest`:npm 12 的 engines 是 `^22.22.2 || ^24.15.0 || >=26.0.0`,而 runner 的 Node 24 比 24.15 旧——装上去只会得到 EBADENGINE 警告,并在一个它声明不支持的 Node 上跑(0.1.7 那次就是这么跑的,侥幸没炸)。
322
+ - **批准必须有 2FA**,CLI 与网页都一样:这是 proof-of-presence 步骤。账号没启用 2FA 就做不了(staged publishing 的前置条件之一)。
323
+ - **`list` / `view` / `approve` / `reject` 不能用 OIDC**,只能在本地交互式执行。所以 workflow 能做的只有 stage,剩下的一定是人。
324
+
325
+ ## 15. 让宿主跑你的开发版:先判断当前是拷贝还是链接
326
+
327
+ **为什么单独写**:§1 里所有重载手段都建立在「profile 指向开发目录」之上,而这**不是一个会自动成立的
328
+ 前提**。插件一旦发布,按版本号安装装的是**真实拷贝**,「改代码 → 构建 → 重启」这条链就静默失效了:
329
+ 宿主照常启动、`applied` 正常、日志里一句警告都没有,跑的还是 registry 上那份。
330
+ 2026-09-22 实测因此把一个**已经改好的修复**误判为「没生效」,白查了一轮。
331
+
332
+ ### 判断
333
+
334
+ ```powershell
335
+ $p = "C:\Users\Horus\.dsh\profiles\web\node_modules\dsh-jev-tools"
336
+ (Get-Item $p -Force).LinkType # 'Junction' 且 Target 指向开发目录才是链接;空 = 真实拷贝
337
+
338
+ # 最可靠的一条:比哈希。两侧不一致,就说明宿主跑的不是你的产物
339
+ Get-FileHash "$p\lib\features\skill-suggest.js"
340
+ Get-FileHash "<开发目录>\lib\features\skill-suggest.js"
341
+ ```
342
+
343
+ 顺带一条:**`lib/` 必须比 `src/` 新**,否则拿到的是过期产物。
344
+
345
+ ### 为什么不能直接 `pnpm add`
346
+
347
+ `dsh plugin --profile web add <开发目录>`(等于在 profile 目录跑 `pnpm add`)**在这台机器上走不通**:
348
+ 它先做锁定文件的供应链校验,而 profile 的 `minimumReleaseAge` 策略会拦下 **lockfile 里已经存在**的
349
+ 若干条目——2026-09-22 实测被拒的是 `dsh-context@0.54.4`、`dsh-map-tools@0.7.0`、`dshmarket@1.55.0`
350
+ (都因发布日期太新),报 `ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION`。**注意被拦的不是你要装的那个包**,
351
+ 所以那条报错信息很容易把人带偏。
352
+
353
+ **不要**为它放松策略,也**不要**跑 `pnpm clean --lockfile`——后者会重解整棵依赖,动到的远不止本插件。
354
+ 手工链接完全等价,而且离线。
355
+
356
+ ### 切成链接
357
+
358
+ ```powershell
359
+ $prof = "C:\Users\Horus\.dsh\profiles\web"
360
+ $dev = "D:\projects\DSH\DSH代码学习\04-插件\dsh-jev-tools"
361
+
362
+ # 1) 把 registry 拷贝移到 node_modules 之外备份(§13:Node 的 rmSync 在这台机器上静默失败,用 PowerShell)
363
+ Move-Item "$prof\node_modules\dsh-jev-tools" "$prof\.backup-dsh-jev-tools-registry" -Force
364
+
365
+ # 2) 建 junction
366
+ New-Item -ItemType Junction -Path "$prof\node_modules\dsh-jev-tools" -Target $dev | Out-Null
367
+ ```
368
+
369
+ ```jsonc
370
+ // 3) profile 的 package.json:spec 也要改,否则将来一次 pnpm install 会把 registry 版装回来盖掉链接
371
+ "dsh-jev-tools": "link:D:/projects/DSH/DSH代码学习/04-插件/dsh-jev-tools"
372
+ ```
373
+
374
+ 然后**重启 `dsh web`**(§1),并回到上面「判断」一节复核哈希两侧一致。
375
+ `dsh.profile.bundles` 里那一行**不用动**——链接与否都挂在这一行上。
376
+
377
+ ### 回退
378
+
379
+ 删掉 junction → 把备份移回 `node_modules\dsh-jev-tools` → 把 spec 改回版本号。三步都可用 PowerShell 完成。
380
+
381
+ ### 一个副作用
382
+
383
+ 链接之后宿主跑的是**未发布的开发版**:单元测试全绿不等于在真实宿主里验证过。
384
+ 要区分「已验证」和「只是测试通过」,看宿主里的实际行为(例如 `Tool.listTools` 里有没有新注册的工具,
385
+ 或台账里有没有只有新代码才会写出的记录),不要相信 `applied`。
386
+
387
+ ## 16. 复现 `suggest` 的判断时,criteria 必须用目录里的真实描述
388
+
389
+ **踩过一次,代价是一个被证伪的结论进了代码注释,并据此改了行为。**
390
+
391
+ `suggest` 送出的每个候选是 `skill.description.slice(0, 200)`——**目录里的真实描述**。
392
+ 若用 `jev_ask` 复现它的判断,却按自己的理解把描述缩写一遍,那你改掉的不只是任务文本,
393
+ **criteria 也一起换了**。两个变量同时动,得出的差异会被归因到错的那一个。
394
+
395
+ 实测(2026-09-22,同一句话、同一批 29 个技能):
396
+
397
+ | criteria | 任务文本 | top1 | 次席 | tokens |
398
+ |---|---|---|---|---|
399
+ | 自写缩写 | 单条长请求 | `lark-workflow-meeting-summary` 0.45 | `lark-minutes` 0.39 | 1606 |
400
+ | 自写缩写 | 三条窗口 | `lark-workflow-meeting-summary` 0.47 | `lark-minutes` 0.40 | 1606 |
401
+ | **真实描述** | 单条长请求 | **`lark-minutes` 0.510** | `lark-workflow-meeting-summary` 0.270 | 3544 |
402
+ | **真实描述** | 三条窗口 | **`lark-minutes` 0.470** | `lark-workflow-meeting-summary` 0.310 | 3608 |
403
+
404
+ 真实描述下,两种任务文本**冠军相同**:窗口只稀释信号(0.510 → 0.470,top2 边际 0.24 → 0.16),
405
+ 并不翻盘。此前那句「窗口翻了冠军」是错的,冠军差异来自我自写的 criteria。
406
+
407
+ **规则**:复现 `suggest` 的判断,criteria 逐字取目录描述。`inputTokens` 是最快的自检——
408
+ 真实描述约 **3500~4200**,缩写版只有 **1600**,差一倍以上就说明 criteria 被换过了。
409
+
410
+ **顺带一条**:`jev_ask` 和 `suggest` 是两个不同的调用方,但问的是同一类问题。
411
+ 拿 `jev_ask` 复现 `suggest` 是合法手段,前提是输入逐字一致;否则它证明不了 `suggest` 的行为。
412
+
413
+
414
+
@@ -0,0 +1,168 @@
1
+ # S0 — 触发率实测报告与阈值决策
2
+
3
+ > 数据来源:`C:\Users\Horus\.dsh\sessions` 下 **72 个** `session.v*.jsonl.zstd`
4
+ > 样本量:24,178 条记录,其中 **4,653 条 `tool/result`**,252 个 `turn/start`
5
+ > 复现:`node scripts/trigger-rate.ts --json trigger-rate.json`
6
+
7
+ 这份文件是**所有默认值的依据**。下面的数字是 2026-09-20 那次测量的结果,没有被后续改动取代——
8
+ 后续新增的能力(注入筛查、试运行、完成度闸门)都在 §8 里补了它们各自的默认值依据。
9
+
10
+ ## 为什么先做这一步
11
+
12
+ `tools/post-execute` 是 **await 型 waterfall**,每次工具调用都会经过。所以决定成败的不是单次延迟,而是:
13
+
14
+ ```
15
+ 触发率 × 单次延迟 = 每 turn 增量
16
+ ```
17
+
18
+ 这个数字必须实测,不能猜。
19
+
20
+ ## 1. 工具结果体积分布(估算 token)
21
+
22
+ `mean 733 · p50 125 · p90 1610 · p99 12500 · max 14800`
23
+
24
+ | 阈值 | 条数 | 占比 |
25
+ |---|---|---|
26
+ | > 1,000 | 748 | 16.1% |
27
+ | > 1,500 | 509 | 10.9% |
28
+ | > 2,000 | 377 | 8.1% |
29
+ | > 3,000 | 251 | 5.4% |
30
+ | > 6,000 | 129 | 2.8% |
31
+
32
+ **中位数只有 125 token** —— 绝大多数工具结果是小的,长尾很少但极大。这决定了阈值必须卡在 p90 以上。
33
+
34
+ ## 2. 只读族占比(决定白名单)
35
+
36
+ 超 1,500 token 且非错误的 509 条中,只读族占 **72.1%**:
37
+
38
+ ```
39
+ web_fetch 191 · read 113 · pwsh 113 · grep 52 · cordis_inspect_query 19 · glob 11 · 其他 10
40
+ ```
41
+
42
+ **`web_fetch` 是最大来源(37.5%)**——抓来的网页天然巨大。
43
+
44
+ **`pwsh` 113 条被刻意排除。** 终端输出常含构建日志、错误栈、文件列表,其中的"无关"内容往往是诊断所需;让廉价判定去裁它有实际风险。同理排除 `cordis_inspect_query`(API 转储,结构强、不该由语义判定裁剪)。
45
+
46
+ **同一份分布也是注入筛查把 `web_fetch` 放在第一位的理由**——它既是最大的来源,也是唯一真正不可信的输入。
47
+
48
+ ## 3. 每 turn 触发数(决定 per-turn 配额)
49
+
50
+ 252 个 turn 中 **79 个(31%)** 会产生至少一次触发。
51
+
52
+ | minTokens | 触发 turn | 均值/turn | p90 | **max** | cap3→均值 | cap3→最坏 |
53
+ |---|---|---|---|---|---|---|
54
+ | 1000 | 88 | 5.8 | 16 | **38** | 0.66s | 0.9s |
55
+ | 1500 | 79 | 4.6 | 10 | **27** | 0.63s | 0.9s |
56
+ | **2000** | **69** | **4.1** | **12** | **21** | **0.60s** | **0.9s** |
57
+ | 3000 | 53 | 3.6 | 12 | 18 | 0.54s | 0.9s |
58
+ | 6000 | 32 | 3.1 | 10 | 12 | 0.52s | 0.9s |
59
+
60
+ **两个决定性结论:**
61
+
62
+ 1. **不设配额会在最坏情况下加 8.1 秒**(27 次 × 300ms)。**配额是必需品,不是优化。**
63
+ 2. **加上 cap=3 之后,延迟在所有阈值下几乎持平(0.52–0.66s)。** 也就是说:**延迟由配额决定,不由阈值决定。** 因此阈值不该按延迟来选。
64
+
65
+ cap=3 时仍有 34.2% 的触发 turn 被截断(cap1 64.6%、cap2 46.8%、cap5 20.3%)——配额确实在起作用。
66
+
67
+ **配额是共享的。** 注入筛查搭车在同一次请求里时不额外消耗配额;只有"没有剪枝请求可以搭车"时它才单独消耗一次。这意味着筛查不会悄悄把剪枝的预算吃光——两者竞争的是同一个上限,而那个上限正是上面测出来的那个数。
68
+
69
+ ## 4. 预估上下文节省(**模型,非实测**)
70
+
71
+ 假设一次判定能丢弃 65% 的内容(受 `minKeepRatio` 0.2 下限约束)。全部工具结果合计 **3,409,687** token。
72
+
73
+ | minTokens | 判定次数 | 判定覆盖 token | 节省 token | **占全部** | 每触发 turn 节省 |
74
+ |---|---|---|---|---|---|
75
+ | 1000 | 508 | 1,991,227 | 1,294,297 | 38.0% | 14,708 |
76
+ | 1500 | 367 | 1,817,443 | 1,181,338 | 34.6% | 14,954 |
77
+ | **2000** | **284** | **1,674,735** | **1,088,578** | **31.9%** | **15,776** |
78
+ | 3000 | 191 | 1,443,868 | 938,514 | 27.5% | 17,708 |
79
+ | 6000 | 100 | 1,067,280 | 693,732 | 20.3% | 21,679 |
80
+
81
+ **这张表是模型,不是实测。** 实测只证明过管线跑通,见 §7 的现场记录;真实节省必须以台账为准(§5)。
82
+
83
+ ## 5. 一个必须写清的警告:基线不是零
84
+
85
+ DSH **已经有两套削减机制**,上面 31.9% 是**毛机会,不是净增量**:
86
+
87
+ | 已有机制 | 作用方式 | 实测频率 |
88
+ |---|---|---|
89
+ | `toolResultPruner` | 对当前 surface 节点做**确定性** head/middle/tail 截断 | 不进日志,无法从历史估算 |
90
+ | `compaction` | **整条消息**遮蔽(`compaction/prune` 带 `shadowedTokenCount`,实测 2305/4818/3314) | 72 个 session 里**只有 3 次** |
91
+
92
+ **Jev 的真实增量在哪:** 确定性截断只能砍**连续**的中段;Jev 能砍**散布**的无关片段、同时保留散布的相关片段。这是真差异,但**无法从日志量化**——`toolResultPruner` 不写日志。
93
+
94
+ **因此 v0.1 内建了 A/B**:`tools/post-execute` 里直接调用 `toolResultPruner.pruneContent(blocks)` 拿到"确定性基线会保留什么",把**基线与 Jev 的保留量一起写进台账**。这样净增量从上线第一天就可测,而不是靠事后争论。台账现已持久化,`npm run measure -- --ledger` 读的就是它。
95
+
96
+ ### 5.1 「可测」有一个前提,而它曾经不成立
97
+
98
+ 上面那句"从上线第一天就可测"**只在基线真的被量到时才成立**,而最初的实现没有区分两种情况:
99
+
100
+ - `pruneContent` 返回 `null`,意思是**载荷在 DSH 自己的预算内**,也就是基线本就会全留——这是一次**测量**,结果是"基线不削";
101
+ - `toolResultPruner` 服务缺失,或调用抛错——**根本没量**。
102
+
103
+ 两者当时都写成"`baselineKeptTokens` 字段不存在",而台账把它们一并按"基线不削"计入净增量。于是 `baselineSavedTokens: 0` 有两个含义完全相反的解释:「基线在这里确实不削」与「我们从没看过」,从外部**无法区分**。实测后果:某台机器上 497 条记录、15 次剪枝判定,基线字段**一次都没有出现过**,而 `/jev-status` 照常打印"其中 DSH 自带确定性截断本就会削掉:0 tokens"——一个从未测过的零,读起来像一个测出来的结果。
104
+
105
+ 现在的实现把三种结果分开:`null` 记为完整的原文(测得),服务缺失或抛错记为 `baselineUnavailable: 'no-service' | 'error'`(未测得)。台账新增 `baselineMeasured` / `baselineUnmeasured` 两个计数器,`/jev-status` 把**覆盖率**与增量一起打印,`npm run measure` 分别打印。**一次都没测到时不再报净增量**——只有削减量是已知的,而它相对确定性截断是否真有增量,此时无数据。
106
+
107
+ 这个修法与 0.1.8 修 `suggest` 的理由是同一条:「从未运行」与「运行了但没有产出」必须能从外部区分,否则台账就答不出它存在的唯一问题。
108
+
109
+ 顺带把基线的真实参数记下来,它决定了「测得为 0」有多常见:DSH 的 `toolResultPruner` 默认 **`thresholdChars 8192` / `headChars 4096` / `tailChars 1024`**(`packages/compaction/compaction-tool-result-pruner`)。它**只对超过 8192 字符的载荷动手**,且保的是**定额**;本插件从约 2000 tokens 起判,保的是**比例**(实测约占原文一半)。两者阈值几乎相邻,所以「基线测得为 0」——载荷还没到 8192 字符——是一个会经常出现的结果,不是异常。也正因为一个是定额、一个是比例,**两者谁留得多取决于载荷大小**,会在某个体量上交叉:对刚好超阈值的载荷,确定性截断留 5120 字符(约六成),本插件留得可能更少;对很大的载荷,本插件按比例留,会远多于那 5120 字符。所以「比确定性截断省得多」不是一个无条件成立的说法,而「挑得准」与「留得多」到目前为止没有被分开量过。
110
+
111
+ ## 6. turn 文件改动频率(当时的 v0.3 输入,现已决策)
112
+
113
+ **252 个 turn 中只有 11 个(4.4%)** 有 `workspace/changes`。
114
+
115
+ 这条数字**改变了计划**,值得完整记下来:
116
+
117
+ - 立项文档里的 M2 是"在 `agent/turn-stopping` 上做完成度自检真",并且留了一个未核实项(`agent.steer` 的确切入口)。
118
+ - 4.4% 说明**自动拦截型**的自检几乎没有可帮的人群,而它的风险(把本来正确的 turn 反复拉长)却是实的。
119
+ - 所以它没有做成钩子,而是做成了工具 **`jev_gate`**:agent 主动调用,用真实证据核对完成声明。工具形态不需要无人值守的 steer,也就没有自检循环风险,却拿到了大部分价值。
120
+ - **结论:这条路的性价比问题不是被推迟回答的,而是被换了个形态回答的。**
121
+
122
+ ## 7. skill 目录规模(决定 minCatalogSize)
123
+
124
+ n=55 个投递给模型的目录:**min 27 · p50 29 · p90 31 · max 40**。
125
+
126
+ **100% 的目录 ≥ 20 个 skill。** 技能推荐不是伪需求——典型用户面对的是 **~29 个 skill 的目录**。
127
+
128
+ ### 现场记录(真实会话,非实验室)
129
+
130
+ 在真实会话里被观测到的四次剪枝:
131
+
132
+ ```
133
+ read: 4613 → 2624 tokens(保留 8/13 段)
134
+ grep: 2932 → 1679 tokens(保留 9/15 段)
135
+ read: 2035 → 1651 tokens(保留 6/7 段)
136
+ grep: 2392 → 1126 tokens(保留 40/83 段)
137
+ ```
138
+
139
+ 这四次说明了三件事:管线在真实数据上跑得通;确定性首尾保底确实在起作用(上面 8/13、9/15 都是首尾留下、中段被丢);以及**保留比例波动很大**(46%–80%),这正是"只排序、不卡阈值"的原因——没有哪个固定比例是安全的。
140
+
141
+ ## 8. 最终阈值决策
142
+
143
+ | 配置项 | 决策值 | 依据 |
144
+ |---|---|---|
145
+ | `prune.minTokens` | **2000** | 延迟已被配额支配而与阈值无关;2000 保留 31.9% 的节省(vs 1500 的 34.6%,仅差 2.7pp),却少发 83 次判定——**每次判定都是一次内容出境和一次裁错风险** |
146
+ | `prune.perTurnLimit` | **3** | 无配额最坏 8.1s;cap=3 最坏 0.9s、均值 0.60s |
147
+ | `prune.toolAllowlist` | `read` `grep` `glob` `web_fetch` `web_search` | 覆盖 72–76% 的超大结果;**刻意排除 `pwsh`** |
148
+ | `prune.headLines` / `tailLines` | 40 / 40 | 确定性保底,不可协商 |
149
+ | `prune.keepHigh` | 0.5 | 高概率段无条件保留 |
150
+ | `prune.minKeepRatio` | 0.2 | 防止把结果削成空壳 |
151
+ | `prune.minSaving` | 0.15 | 削减不足则放弃,不引入失真 |
152
+ | `prune.minTaskChars` | 12 | 拿「继续吧」这类极短消息判相关性得到的是噪声 |
153
+ | `prune.shadow` | false | 默认关。它是一个**信任前的观察工具**,不是默认工作模式:开着的代价是判定照付、相同 payload 会被重复判定(缓存里存的是已精简内容,试运行不能取用) |
154
+ | `screen.enabled` | true | 默认开。抓取内容是唯一真正不可信的输入,而这一次判定的成本几乎为零(搭车同一次请求) |
155
+ | `screen.minTokens` | **300** | 与剪枝阈值**刻意不同**:最危险的页面往往是短的,短到永远进不了剪枝。300 token 足以承载一段注入指令 |
156
+ | `screen.threshold` | 0.75 | 采纳生态里通行的注入阈值起点(jev-mcp 的 `block_at` 同为 0.75)。官方明确阈值应随后果分档,并且**必须用自己的数据调** |
157
+ | `screen.toolAllowlist` | `web_fetch` `web_search` | 只查外部抓取。本地文件是用户自己的材料,且读取频繁(§2 里 `read` 113 条 vs `web_fetch` 191 条)——把它们也查会吃掉剪枝的配额 |
158
+ | `suggest.minCatalogSize` | **15** | 实测 min 27、p50 29;真实用户必触发,极简 preset 保持沉默 |
159
+ | `suggest.minConfidence` | 0.3 | 低置信度**不注入**——宁可沉默,不要噪音。注意它卡的是 Choice 的 `confidence`(分布形状派生的统计量),与 `prune.keepHigh` 卡的 **Noul 值**不是同一种量,两个数字不可比较 |
160
+ | `sessionCallLimit` | 200 | 成本与内容出境的硬上限,所有能力**共享** |
161
+
162
+ ## 9. 复现与后续
163
+
164
+ - 脚本:`scripts/trigger-rate.ts`(`node scripts/trigger-rate.ts --json trigger-rate.json`)
165
+ - 会话日志格式:不是单一 zstd 流,也**不是一帧一记录**——写入方追加独立 zstd 帧,每帧含多条 JSONL 记录。Node 的 zstd API 遇多帧只解第一帧,因此必须**扫描帧魔数 + 按 `seq` 并集去重**。实现见 `scripts/lib/session-log.ts`。
166
+ - token 数为估算(`cjkChars + otherChars / 4`,约 ±20%),只用于比例与形状,不用于计费。
167
+ - 真实节省必须以台账为准(见 §5 的 A/B 要求)。台账现已持久化到 `$DSH_HOME/storages/dsh_jev_tools/`,`npm run measure -- --ledger` 可直接读它并报告相对基线的净增量。
168
+ - **仍未测的**:与主模型在同一批样本上的对照(立项文档 M0 的验收标准),以及标定曲线的真实拟合——后者需要每条判定的概率与事后对错,两者 v0.1 都没有。
package/icon.svg ADDED
@@ -0,0 +1,16 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 36 36" width="36" height="36" role="img" aria-label="dsh-jev-tools">
2
+ <defs>
3
+ <linearGradient id="jevPath" x1="19" y1="8" x2="33" y2="28" gradientUnits="userSpaceOnUse">
4
+ <stop offset="0" stop-color="#22C9E6" />
5
+ <stop offset="1" stop-color="#8B5CF6" />
6
+ </linearGradient>
7
+ </defs>
8
+ <!-- The checklist: every call is judged, and the judgement is a yes or a no. -->
9
+ <path d="M4.2 11H11.6" stroke="#6B7A90" stroke-opacity="0.55" stroke-width="2" stroke-linecap="round" />
10
+ <path d="M13.8 8.9l4.2 4.2M18 8.9l-4.2 4.2" fill="none" stroke="#F87171" stroke-width="2" stroke-linecap="round" />
11
+ <!-- The no is dropped here; the yes becomes the decision path. -->
12
+ <path d="M4.2 25H11.6" stroke="#7E8CA3" stroke-width="2" stroke-linecap="round" />
13
+ <path d="M13.6 25l2.1 2.2 3.8-4.3" fill="none" stroke="#4ADE80" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
14
+ <path d="M19.8 25H32.2" fill="none" stroke="url(#jevPath)" stroke-width="2.7" stroke-linecap="round" />
15
+ <path d="M29.3 22.3 32.2 25l-2.9 2.7" fill="none" stroke="url(#jevPath)" stroke-width="2.7" stroke-linecap="round" stroke-linejoin="round" />
16
+ </svg>