dsh-boost 0.0.0-stage → 0.1.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.
- package/LICENSE +202 -0
- package/NOTICE +29 -0
- package/README.en.md +476 -0
- package/README.md +408 -2
- package/cordis.patch.yml +40 -0
- package/dist/admission/fixed-cost.d.ts +23 -0
- package/dist/admission/fixed-cost.js +61 -0
- package/dist/admission/fixed-cost.js.map +1 -0
- package/dist/admission/ledger.d.ts +113 -0
- package/dist/admission/ledger.js +176 -0
- package/dist/admission/ledger.js.map +1 -0
- package/dist/admission/retrieval.d.ts +65 -0
- package/dist/admission/retrieval.js +162 -0
- package/dist/admission/retrieval.js.map +1 -0
- package/dist/admission/usage.d.ts +75 -0
- package/dist/admission/usage.js +124 -0
- package/dist/admission/usage.js.map +1 -0
- package/dist/config.d.ts +43 -0
- package/dist/config.js +103 -0
- package/dist/config.js.map +1 -0
- package/dist/gate/binding.d.ts +113 -0
- package/dist/gate/binding.js +297 -0
- package/dist/gate/binding.js.map +1 -0
- package/dist/gate/decide.d.ts +82 -0
- package/dist/gate/decide.js +163 -0
- package/dist/gate/decide.js.map +1 -0
- package/dist/gate/guard.d.ts +69 -0
- package/dist/gate/guard.js +195 -0
- package/dist/gate/guard.js.map +1 -0
- package/dist/gate/invalidate.d.ts +112 -0
- package/dist/gate/invalidate.js +111 -0
- package/dist/gate/invalidate.js.map +1 -0
- package/dist/gate/plan.d.ts +86 -0
- package/dist/gate/plan.js +222 -0
- package/dist/gate/plan.js.map +1 -0
- package/dist/hooks/clock.d.ts +68 -0
- package/dist/hooks/clock.js +82 -0
- package/dist/hooks/clock.js.map +1 -0
- package/dist/hooks/execute.d.ts +79 -0
- package/dist/hooks/execute.js +128 -0
- package/dist/hooks/execute.js.map +1 -0
- package/dist/hooks/llm-stream.d.ts +276 -0
- package/dist/hooks/llm-stream.js +1008 -0
- package/dist/hooks/llm-stream.js.map +1 -0
- package/dist/hooks/pending.d.ts +89 -0
- package/dist/hooks/pending.js +115 -0
- package/dist/hooks/pending.js.map +1 -0
- package/dist/hooks/post-execute.d.ts +247 -0
- package/dist/hooks/post-execute.js +1776 -0
- package/dist/hooks/post-execute.js.map +1 -0
- package/dist/hooks/session-state.d.ts +158 -0
- package/dist/hooks/session-state.js +168 -0
- package/dist/hooks/session-state.js.map +1 -0
- package/dist/hooks/synthesize.d.ts +74 -0
- package/dist/hooks/synthesize.js +100 -0
- package/dist/hooks/synthesize.js.map +1 -0
- package/dist/host/loader.d.ts +23 -0
- package/dist/host/loader.js +31 -0
- package/dist/host/loader.js.map +1 -0
- package/dist/host/platform.d.ts +18 -0
- package/dist/host/platform.js +19 -0
- package/dist/host/platform.js.map +1 -0
- package/dist/host/root.d.ts +18 -0
- package/dist/host/root.js +43 -0
- package/dist/host/root.js.map +1 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +866 -0
- package/dist/index.js.map +1 -0
- package/dist/projection/apply.d.ts +174 -0
- package/dist/projection/apply.js +137 -0
- package/dist/projection/apply.js.map +1 -0
- package/dist/projection/canonicalise.d.ts +43 -0
- package/dist/projection/canonicalise.js +43 -0
- package/dist/projection/canonicalise.js.map +1 -0
- package/dist/projection/counters.d.ts +65 -0
- package/dist/projection/counters.js +88 -0
- package/dist/projection/counters.js.map +1 -0
- package/dist/projection/truncate.d.ts +47 -0
- package/dist/projection/truncate.js +57 -0
- package/dist/projection/truncate.js.map +1 -0
- package/dist/prompt/protocol.d.ts +45 -0
- package/dist/prompt/protocol.js +56 -0
- package/dist/prompt/protocol.js.map +1 -0
- package/dist/receipts/store.d.ts +198 -0
- package/dist/receipts/store.js +734 -0
- package/dist/receipts/store.js.map +1 -0
- package/dist/scope/doc.d.ts +117 -0
- package/dist/scope/doc.js +158 -0
- package/dist/scope/doc.js.map +1 -0
- package/dist/scope/resolve.d.ts +91 -0
- package/dist/scope/resolve.js +146 -0
- package/dist/scope/resolve.js.map +1 -0
- package/dist/scope/store.d.ts +135 -0
- package/dist/scope/store.js +573 -0
- package/dist/scope/store.js.map +1 -0
- package/dist/selector/jev.d.ts +93 -0
- package/dist/selector/jev.js +171 -0
- package/dist/selector/jev.js.map +1 -0
- package/dist/tools/boost.d.ts +367 -0
- package/dist/tools/boost.js +768 -0
- package/dist/tools/boost.js.map +1 -0
- package/dist/tools/family.d.ts +26 -0
- package/dist/tools/family.js +26 -0
- package/dist/tools/family.js.map +1 -0
- package/dist/types.d.ts +113 -0
- package/dist/types.js +21 -0
- package/dist/types.js.map +1 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +75 -4
package/README.md
CHANGED
|
@@ -1,3 +1,409 @@
|
|
|
1
|
-
#
|
|
1
|
+
# dsh-boost
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
通过**工具回执投影**与**确定性只读替换**降低 DeepSeek Harness(DSH)的 token 消耗。
|
|
4
|
+
|
|
5
|
+
> **状态:v1 已实现。** 投影、替换与控制面均已落地;`npm run build` 干净,测试套件全部通过。
|
|
6
|
+
|
|
7
|
+
## 它解决什么
|
|
8
|
+
|
|
9
|
+
DSH 每次模型请求都会回放全部历史。本机 300 个最长会话的实测聚合(`npm run --silent stats`——不带
|
|
10
|
+
`--silent` 时 npm 会把 `> dsh-boost@0.1.0 stats` 横幅打进 stdout,机器解析请用 `--silent` 或直接
|
|
11
|
+
`node scripts/session-stats.mjs`;快照时刻 `2026-11-19T03:13:21Z`):54,141 步、54,088 个请求,合计 10,575,904,022 raw token。按步均值
|
|
12
|
+
195,340 token,按请求均值 195,531、中位 187,681;97.01% 的输入是缓存读。工具回执是体积主体
|
|
13
|
+
(bash 61.75%、read 22.13%、ssh 10.01%),而下一步真正会用到的部分通常远小于回执本身。
|
|
14
|
+
|
|
15
|
+
插件做两件事:
|
|
16
|
+
|
|
17
|
+
1. **投影**——工具回执进入上下文之前,按工具族保留头尾,把中段换成可检索的落盘句柄;
|
|
18
|
+
原文仍可取回,页脚给出路径。投影按固定阈值确定性执行,不产生逐次决策。
|
|
19
|
+
2. **替换**——计划里重复的只读调用(`read` / `grep` / `glob`)若已有确定性证据满足守卫,
|
|
20
|
+
直接提交,不再向模型要一次决策;多候选时用一个单标签选择器——一次独立的辅助请求
|
|
21
|
+
(`maxTokens` 512,另加其输入)。对替换涉及的三个工具而言,计划里的 `$public` 参数绑定
|
|
22
|
+
(把上一步回执里的值直接搬进下一步参数)在实践中只对 `glob` 的单 token 输出有效;
|
|
23
|
+
`read` 与 `grep` 的输出带行号或是裸路径,标识符投影匹配不到,这些调用会退回模型。
|
|
24
|
+
|
|
25
|
+
v1 的预期收益区间是 **3.5%(保底)– 10.0%(上界)**,按 raw `totalTokens` 计。
|
|
26
|
+
这是设计阶段对一个 300 会话语料做**离线事前估算**得到的区间:不是保证,也不是从交付的
|
|
27
|
+
`session-snapshot.json` 能复算出来的数字(快照只存聚合计数,没有估算用的分项)——交付物里
|
|
28
|
+
**没有任何工具能复算它**。影子周也**不能**把这个区间变成实测百分比:影子报告只输出四个
|
|
29
|
+
比例(见「影子周」一节),没有总 token 分母,`boost status` 也只有绝对值;区间要被实测
|
|
30
|
+
取代,得等后续版本补上分母统计。
|
|
31
|
+
|
|
32
|
+
## 前置条件
|
|
33
|
+
|
|
34
|
+
- Node.js `>=24.9.0`,DSH `0.2.2-rc.4`(精确锁定,不是区间;两者都在 `package.json` 的
|
|
35
|
+
`engines` 里;Node 下限对齐宿主 `@deepseek-ai/dsh@0.2.2-rc.4`)。
|
|
36
|
+
- **本包不声明任何 peerDependencies**:安装它不会带出任何 `@deepseek-ai/*` 包,模块脱离它们也能
|
|
37
|
+
加载;运行时能力(`tokenMeter`、`spillStore`、估算器、页脚格式化器)由 DSH 宿主进程提供,
|
|
38
|
+
缺失时走降级(见「宿主依赖」)。
|
|
39
|
+
- **替换只在 POSIX 上可用。** Windows(`win32`)上替换被拒绝,`boost status` 的 `degraded`
|
|
40
|
+
会带 `ERR_HOST_PLATFORM_UNSUPPORTED`;投影不依赖平台,仍然工作。
|
|
41
|
+
- v1 面向 web profile;不支持 desktop profile。
|
|
42
|
+
|
|
43
|
+
## 安装
|
|
44
|
+
|
|
45
|
+
`dsh plugin` 要求指定 profile,剩下的参数原样转发给该 profile 目录里的 pnpm:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# 从 registry 安装(0.1.0 是首次发布;发布后 latest 就是它)
|
|
49
|
+
dsh plugin --profile <name> add dsh-boost@^0.1.0
|
|
50
|
+
|
|
51
|
+
# 或从本地 checkout 安装(先构建;dist/ 不入库)
|
|
52
|
+
npm run build
|
|
53
|
+
dsh plugin --profile <name> add /absolute/path/to/dsh-boost
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
例如 web profile:`dsh plugin --profile web add dsh-boost@^0.1.0`。`dsh plugin` 把操作转发给 pnpm,
|
|
57
|
+
所以 pnpm 必须在 PATH 上。
|
|
58
|
+
|
|
59
|
+
包是 ESM(`"type": "module"`),`exports` 的 `.` 条目同时映射 `require` / `default`:Node ≥ 24.9
|
|
60
|
+
下 `require('dsh-boost')` 与 `import` 加载同一份代码,装好的包里**不做任何构建**(`files` 只带
|
|
61
|
+
`dist`、`locale`、`cordis.patch.yml`、两份 README、`LICENSE`、`NOTICE`,不带 `src/`;`dist` 的
|
|
62
|
+
sourcemap 内联了源码)。
|
|
63
|
+
|
|
64
|
+
包里的 `dsh.bundle.patch` 指向 `cordis.patch.yml`,所以安装后宿主会把它登记为 profile 的一个
|
|
65
|
+
bundle,patch 的 `insert` 行落在 profile root 上。**装完必须重启 DSH**:插件在宿主启动时加载,
|
|
66
|
+
已经在运行的会话看不到 `boost` 工具;web profile 就是重启 `dsh web`。
|
|
67
|
+
|
|
68
|
+
## 启用
|
|
69
|
+
|
|
70
|
+
装上之后插件默认**不做事**。`scope.json` 不存在时使用 `DEFAULT_SCOPE`:
|
|
71
|
+
|
|
72
|
+
```json
|
|
73
|
+
{ "version": 2, "revision": 0, "mode": "selected", "workspaceIds": [], "shadow": true, "projection": "shadow" }
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
`workspaceIds` 为空时没有可见工作区:协议段不注入,投影与替换都原样放行,但每个工具调用
|
|
77
|
+
仍会记一条 `skip:no-scope` 收据。`boost` 工具本身是唯一的 scope 豁免,因此没有工作区时仍然
|
|
78
|
+
可以调用它来启用。
|
|
79
|
+
|
|
80
|
+
`boost` 是**模型工具,不是 shell 命令**——这个包没有 `bin`,启用全程都要在对话里让模型调用
|
|
81
|
+
它(status、scope-set、shadow 都是工具调用,没有 CLI 等价物)。例如:
|
|
82
|
+
|
|
83
|
+
> 调用 boost 工具,参数 `{"cmd":"status"}`,把 JSON 结果给我。
|
|
84
|
+
|
|
85
|
+
首次 `status` 应看到 `ok: true`;`data.scope.workspaceIds` 为空、`revision` 为 `0`,`shadow` 为
|
|
86
|
+
`true`、`projection` 为 `"shadow"`,`counts` 为空(**仅限全新会话**——越界会话更早的工具调用
|
|
87
|
+
已经各记过一条 `skip:no-scope`)。`degraded` 里出现 `ERR_SCOPE_READ_FAILED`
|
|
88
|
+
是正常的:`scope.json` 还不存在,插件正落在 fail-closed 默认值上。第一次成功的 `scope-set`
|
|
89
|
+
会创建这个文件。
|
|
90
|
+
|
|
91
|
+
然后列出要暴露的工作区:
|
|
92
|
+
|
|
93
|
+
```json
|
|
94
|
+
{
|
|
95
|
+
"cmd": "scope-set",
|
|
96
|
+
"body": {
|
|
97
|
+
"mode": "selected",
|
|
98
|
+
"workspaceIds": ["<workspace-id>"],
|
|
99
|
+
"shadow": true,
|
|
100
|
+
"projection": "shadow"
|
|
101
|
+
},
|
|
102
|
+
"baseRevision": 0
|
|
103
|
+
}
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
- `workspaceIds` 是宿主的 workspace UUID,不是路径;宿主通过 workspace registry 把 agent 的
|
|
107
|
+
cwd 映射成这个 id。**发现 UUID 本身有摩擦**:要么问宿主/翻会话记录,要么自己读
|
|
108
|
+
`$DSH_HOME/storages/workspace.json` 的 `tables.workspaces`(id ↔ path 的映射表)——v1 没有
|
|
109
|
+
任何命令替你做这件事。找不到 UUID 且是单用户机器时,可以用 `"mode": "global"` 放开到所有
|
|
110
|
+
**已定义**的工作区;没有工作区的会话仍然不可见。
|
|
111
|
+
- `baseRevision` 取你刚读到的 `data.scope.revision`(首次写入是 `0`)。这是 compare-and-swap:
|
|
112
|
+
revision 过期会返回 `ERR_SCOPE_REVISION_CONFLICT`,重读 `status` 再试。调用被调用方的取消
|
|
113
|
+
信号打断时返回 `ERR_SCOPE_ABORTED`:锁已释放、`scope.json` 原样未动,重读 `revision` 重试
|
|
114
|
+
即可,不留残留。
|
|
115
|
+
- `body` 里的 `version` 与 `revision` 是 store 自有的,带这两个字段会被拒绝。
|
|
116
|
+
|
|
117
|
+
写入成功后再 `status` 一次,健康输出应当满足:
|
|
118
|
+
|
|
119
|
+
- `ok: true`,`data.scope.workspaceIds` 含刚写入的 id,`data.scope.revision` 变成 `1`(每次写加一)。
|
|
120
|
+
- `data.shadow` 为 `true`,`data.projection` 为 `"shadow"`——正是影子周的状态。
|
|
121
|
+
- `data.degraded` 为空(POSIX、宿主有 token meter 与 spill 后端时);`estimate_kind` 为
|
|
122
|
+
`"host"`,`fixedOverheadTokens` 是一个数字,不是 `"unknown"`。若估算包
|
|
123
|
+
`@deepseek-ai/dsh-token-meter/estimate` 不可达,`fixedOverheadTokens` 会是字符串
|
|
124
|
+
`"unknown"`(不是 0),`degraded` 带 `ERR_HOST_NO_ESTIMATOR`;此时 `estimate_kind` 仍可能是
|
|
125
|
+
`"host"`,因为 token meter 服务还在——两件事不要混。
|
|
126
|
+
- `data.counts` 一开始通常为空——但**控制调用自己也计数**:可见工作区为空时,`boost`
|
|
127
|
+
自己的调用同样要过 post-execute 的 scope 门(那里没有 boost 豁免,豁免只在工具注册层),
|
|
128
|
+
每条记一次 `skip:no-scope`。正常工具调用后会累积,例如出现 `projection-shadow` 条目。
|
|
129
|
+
|
|
130
|
+
节选(数值示意;账目字段有省略):
|
|
131
|
+
|
|
132
|
+
```json
|
|
133
|
+
{
|
|
134
|
+
"ok": true,
|
|
135
|
+
"data": {
|
|
136
|
+
"scope": { "mode": "selected", "workspaceIds": ["<workspace-id>"], "revision": 1 },
|
|
137
|
+
"shadow": true,
|
|
138
|
+
"projection": "shadow",
|
|
139
|
+
"degraded": [],
|
|
140
|
+
"fixedOverheadTokens": 778,
|
|
141
|
+
"estimate_kind": "host",
|
|
142
|
+
"counts": { "skip:no-scope": 2 }
|
|
143
|
+
}
|
|
144
|
+
}
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
示例里的 `counts` 不是空对象:启用流程中前两次控制调用(`status`、`scope-set`)发起时还没有
|
|
148
|
+
可见工作区,每次各记了一条 `skip:no-scope`(post-execute 的 scope 门不豁免 `boost` 自身)。
|
|
149
|
+
|
|
150
|
+
`fixedOverheadTokens` 是启动时实测的固定开销**合计**:协议段 379 + `boost` 工具 schema 399 =
|
|
151
|
+
778(本 checkout)。它不是从使用量里推断的;估算包不可达时它是字符串 `'unknown'`,不是 778,
|
|
152
|
+
也不是 0,`status.degraded` 同时带 `ERR_HOST_NO_ESTIMATOR`。**哪个数字适用于当前请求取决于
|
|
153
|
+
scope**:`boost` 工具 schema(399)只要插件装配就常驻——`boost` 是唯一的 scope 豁免,始终留在
|
|
154
|
+
工具声明里;协议段(379)只在有可见工作区时注入,`selected + []` 下该段文本为空,**每请求固定
|
|
155
|
+
开销实际是 399**。`status` 汇报的是合计 778(估算包不可达时是 `'unknown'`),不随 scope 翻转;
|
|
156
|
+
上面示例里工作区已选中,778 就是当时的真实每请求开销。
|
|
157
|
+
|
|
158
|
+
## 影子周
|
|
159
|
+
|
|
160
|
+
设计选择**影子优先**:先用一周只记账(不合成回合、不跳过调用,投影只记账不改内容),再决定
|
|
161
|
+
是否真的投影与替换。**「什么都不改」并不成立**:只要有可见工作区,协议段(379 token)就会
|
|
162
|
+
注入系统提示;多候选计划仍会**真实调用一次选择器**(一次独立的辅助模型请求)。影子周按设计
|
|
163
|
+
零节省,它只产出下一节的四个比例。`scope.json` 里有两个独立开关:
|
|
164
|
+
|
|
165
|
+
| 开关 | 取值 | 行为 |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| `shadow` | `true` | 替换决策只记账(`kind:'shadow'` 收据),不合成、不跳过任何调用 |
|
|
168
|
+
| | `false` | 守卫满足的 `read` / `grep` / `glob` 调用会被真正替换 |
|
|
169
|
+
| `projection` | `off` | 完全不投影 |
|
|
170
|
+
| | `shadow` | 只计算“如果投影会省多少”,不改模型可见 content,不写 spill |
|
|
171
|
+
| | `on` | 先把完整原文交给宿主 spill 后端,再把回执换成 head + 页脚 + tail |
|
|
172
|
+
|
|
173
|
+
推荐的顺序:
|
|
174
|
+
|
|
175
|
+
1. **第一周**:按上面的 `scope-set` 使用 `shadow: true`、`projection: 'shadow'`,照常工作。
|
|
176
|
+
2. **读报告**:在仓库 checkout 里跑
|
|
177
|
+
`node scripts/shadow-report.mjs --dir "${DSH_HOME:-$HOME/.dsh}/boost/receipts"`。
|
|
178
|
+
这个脚本是 dev-only,不在 npm tarball 里。它输出四个标签:
|
|
179
|
+
`saveableRatio`(白名单能兑现的替换占比 = `whitelisted` 影子提交 / **全部**替换决策——分母
|
|
180
|
+
是每一次替换决策,不只是白名单调用;影子期全族记账,bash/ssh 的潜力看 `byFamily`)、`byFamily`(按候选工具族的命中率)、
|
|
181
|
+
`candidateRecall`(候选集召回)、`retrievalUpperBound`(取回率上界;影子期没有真正投影,
|
|
182
|
+
结构上恒为 `0`)。
|
|
183
|
+
3. **打开投影**:报告支持的话,保持 `shadow: true`,把 `projection` 改成 `'on'`:
|
|
184
|
+
|
|
185
|
+
```json
|
|
186
|
+
{ "cmd": "scope-set", "body": { "projection": "on" }, "baseRevision": 1 }
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
`scope-set` 只覆盖你传入的字段,其余保持不变。此时回执开始真正被替换,但替换决策仍然只记账。
|
|
190
|
+
4. **再打开替换**:直接把影子关掉——**先检查再关是无效顺序**:影子期从不合成回合,
|
|
191
|
+
`content[].thinking` 的 400 在结构上不可能出现,关影子之前检查它永远只能读到「未见」。
|
|
192
|
+
把 `shadow` 设为 `false` 之后,按 [docs/RELEASE.md](docs/RELEASE.md) §4 在**第一个真正
|
|
193
|
+
被替换的回合**检查该 400,并在此后的每个替换观察窗继续记录:
|
|
194
|
+
|
|
195
|
+
```json
|
|
196
|
+
{ "cmd": "shadow", "body": false, "baseRevision": 2 }
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
`projection: 'on'` 依赖宿主的 spill 后端。后端缺失时,超限回执**不投影**,原文完整进入历史
|
|
200
|
+
(收据 `projection-skipped:no-spill`,`status.degraded` 带 `ERR_HOST_NO_SPILL`)。影子模式
|
|
201
|
+
不需要 spill。
|
|
202
|
+
|
|
203
|
+
## 配置
|
|
204
|
+
|
|
205
|
+
`cordis.patch.yml` 里的 `config` 是**整体替换**,不做深合并:缺键回落插件默认值。但要注意:
|
|
206
|
+
`resolveConfig` 会用默认值填满**全部五个工具族**(`read` / `grep` / `glob` / `bash` / `ssh`),
|
|
207
|
+
所以**删掉一个族不是关掉它**——删掉 `projection.bash` 只会让 bash 按默认的 4000/2000/500
|
|
208
|
+
投影。要真正关掉一个族,把它的 `triggerChars` 提到你所有回执之上;投影的字节上限是 256 KiB,
|
|
209
|
+
`300000` 足以让该族全部不触发(不存在 per-family 的 off 键)。
|
|
210
|
+
|
|
211
|
+
配置里的 `projection.*` 是**窗口**,不是开关;开关在 `scope.json` 的 `projection` 字段,
|
|
212
|
+
由 `boost scope-set` 写。
|
|
213
|
+
|
|
214
|
+
| 键 | 默认值 | 作用 |
|
|
215
|
+
|---|---|---|
|
|
216
|
+
| `projection.read.triggerChars` / `headChars` / `tailChars` | 3000 / 2000 / 500 | `read` 回执超过 3000 字符时保留头 2000、尾 500 |
|
|
217
|
+
| `projection.grep.*` | 700 / 400 / 100 | `grep` 窗口 |
|
|
218
|
+
| `projection.glob.*` | 700 / 400 / 100 | `glob` 窗口 |
|
|
219
|
+
| `projection.bash.*` | 4000 / 2000 / 500 | `bash` 窗口 |
|
|
220
|
+
| `projection.ssh.*` | 2000 / 1200 / 300 | `mcp__ssh__*`(如 `mcp__ssh__execute-command`)窗口 |
|
|
221
|
+
| `admission.thresholdTokens` | 1024 | 每个候选进入替换所需的最小净节省;唯一候选的确定性提交豁免 |
|
|
222
|
+
| `selector.maxTokens` | 512 | 多候选选择器的输出预算(输入 + 输出上界从节省里扣) |
|
|
223
|
+
| `stepsPerTurn` | 8 | 每个 turn 的替换步数上限 |
|
|
224
|
+
| `horizonSteps` | 20 | 算不出会话历史均值时的剩余步数 horizon |
|
|
225
|
+
| `historyTurns` | 5 | 求步数均值所用的最近 turn 数 |
|
|
226
|
+
| `dshHome` | `$DSH_HOME`,未设则 `~/.dsh` | 状态根前缀:实际用 `<dshHome>/boost`,且优先于 `$DSH_HOME`;空白或非字符串视为未设,相对路径按装配时 cwd 解析一次。装配日志会打印解析后的 `root=` |
|
|
227
|
+
|
|
228
|
+
字符按 Unicode 码点计。错误回执与超过 256 KiB 的回执不投影。
|
|
229
|
+
|
|
230
|
+
不变量不是 `triggerChars ≥ headChars + tailChars + 1`。真实替换串是 head line + head + 页脚 +
|
|
231
|
+
tail + 3 个换行;页脚由宿主 `formatSpillNotice` 生成,约 196 字符(68 字符 locator、5 位省略
|
|
232
|
+
字节数、宿主固定 retrieval hint)。grep/glob 默认 400+100 时:
|
|
233
|
+
`400 + 100 + 50(head line) + 196(页脚) + 3 = 749 > 700`。于是刚过 700、约 749 以下的回执
|
|
234
|
+
会被 `truncate` 判定“可裁”,但 `projectApply` 组装后并不短于原文,直接返回原文——这是死区,
|
|
235
|
+
不是净亏。运行时的 `assembled.length >= text.length` 检查保证投影绝不会让回执变长;要消除
|
|
236
|
+
死区,把 `triggerChars` 提到至少这个和(例如 grep/glob 用 800),或缩小窗口。页脚长度会随
|
|
237
|
+
locator 与数字位数浮动。
|
|
238
|
+
|
|
239
|
+
(`projection: 'shadow'` 定价只含 `(Omitted N bytes.)` 省略句,不含 locator/页脚全文,所以
|
|
240
|
+
影子账的 `after` 是下界;apply 路径在写入后还会再核对一次。)
|
|
241
|
+
|
|
242
|
+
## Bundle patch
|
|
243
|
+
|
|
244
|
+
`cordis.patch.yml` 只有一条 `insert`,落在 profile root 上:
|
|
245
|
+
|
|
246
|
+
```yaml
|
|
247
|
+
- insert:
|
|
248
|
+
- id: dsh-boost
|
|
249
|
+
name: 'dsh-boost'
|
|
250
|
+
config:
|
|
251
|
+
projection:
|
|
252
|
+
read: { triggerChars: 3000, headChars: 2000, tailChars: 500 }
|
|
253
|
+
grep: { triggerChars: 700, headChars: 400, tailChars: 100 }
|
|
254
|
+
glob: { triggerChars: 700, headChars: 400, tailChars: 100 }
|
|
255
|
+
bash: { triggerChars: 4000, headChars: 2000, tailChars: 500 }
|
|
256
|
+
ssh: { triggerChars: 2000, headChars: 1200, tailChars: 300 }
|
|
257
|
+
admission: { thresholdTokens: 1024 }
|
|
258
|
+
selector: { maxTokens: 512 }
|
|
259
|
+
stepsPerTurn: 8
|
|
260
|
+
horizonSteps: 20
|
|
261
|
+
historyTurns: 5
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
宿主对顶层 `insert` 行**不做任何 id/name 匹配**:加载器(cordis-plugin-include 的
|
|
265
|
+
`applyEntryPatches`)直接把行 push 进装配计划,不存在「匹配不上就静默跳过」的路径。这两个
|
|
266
|
+
等式另有用途——**plugin manager 用它们把运行中的 entry 归属到本 bundle 的行**(`dsh-plugin-manager`
|
|
267
|
+
的 in-use / 可寻址判定,见 `listPlugins` / `removeBundle`):
|
|
268
|
+
|
|
269
|
+
```text
|
|
270
|
+
row.id === entry.options.id
|
|
271
|
+
row.name === entry.options.name
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
`id` 与 `name` **不需要彼此相等**:第三方插件 `dsh-mcp-btwy`(用户 profile 里自装的 GitHub
|
|
275
|
+
包,不是宿主自带的 patch)就写成 `id: dsh-mcp-server`、`name: dsh-mcp-btwy`。本包让四个名字
|
|
276
|
+
全部保持为 `dsh-boost`(npm 包名、导出的插件 `name`、patch 行的 `id` 与 `name`),这样
|
|
277
|
+
plugin manager 才能把运行中的 entry 认成本包的行、通过 profile patch 寻址与移除;等式不成
|
|
278
|
+
立时行**照常装配**,只是在管理面变成不可寻址(读写状态、移除判定都会失灵),而 `name` 指到
|
|
279
|
+
不存在的包时加载会**响亮地**失败,不是静默。
|
|
280
|
+
|
|
281
|
+
## 状态、回滚与卸载
|
|
282
|
+
|
|
283
|
+
状态在 `$DSH_HOME/boost/`(`$DSH_HOME` 未设置时回退 `~/.dsh`):
|
|
284
|
+
|
|
285
|
+
- `scope.json`——暴露面的唯一事实来源(version 2,带 revision)。
|
|
286
|
+
- `scope.lock`——写路径的短锁,正常写入结束后删除。
|
|
287
|
+
- `receipts/<encoded-session>.jsonl`——追加式收据。每行携带元数据、回执前 256 个码点的
|
|
288
|
+
preview(不存 stdout 全文)和**绑定后的参数 `args`(模型所写,截到 2048 个码点,超长会以
|
|
289
|
+
`args_truncated` 标记的截断 JSON 落盘——`write` / `edit` 的参数可携带整段文件内容,同样
|
|
290
|
+
入账)**。**只有替换类收据**(`substitute` / `substitute-settled` / `shadow`)另外携带计划
|
|
291
|
+
goal(≤256 码点)与守卫(≤8 条,各 ≤300 码点);投影与 skip 收据只有 preview 和 args,
|
|
292
|
+
没有 plan 证据。
|
|
293
|
+
|
|
294
|
+
`boost status` 的投影账按每条收据自己的 `horizon_steps` 重放;没有该字段的旧收据按当前
|
|
295
|
+
horizon 重放,并计入 `projection_horizon_reestimated`;`projection_horizon_steps` 报告当前
|
|
296
|
+
生效的 horizon(活动会话的最小值;没有历史时回落到 `horizonSteps`)。
|
|
297
|
+
|
|
298
|
+
`projection: 'on'` 时,完整原文在替换发生**之前**写入宿主的 spill 后端,页脚 locator 可以用
|
|
299
|
+
`read` / `grep` 取回。投影不会丢掉唯一副本;spill 写入失败就不替换(收据记
|
|
300
|
+
`projection-skipped:spill-failed`,页脚渲染失败记 `projection-skipped:footer-failed`;页脚
|
|
301
|
+
渲染器加载不到则记 `projection-skipped:no-footer`,见「宿主依赖」)。
|
|
302
|
+
|
|
303
|
+
回滚与停用(下面的 `baseRevision` 按「启用」一节的路径走完是 `3`,第一条执行完是 `4`;
|
|
304
|
+
实际使用时永远取你刚从 `status` 读到的 `data.scope.revision`,不要照抄):
|
|
305
|
+
|
|
306
|
+
- **关掉两个行为**(不再投影、不再替换,但仍然可见的工作区——`selected` 下已选的、`global`
|
|
307
|
+
下全部已定义的——会继续注入协议段,替换决策仍写影子收据,固定开销照旧):
|
|
308
|
+
|
|
309
|
+
```json
|
|
310
|
+
{ "cmd": "scope-set", "body": { "projection": "off", "shadow": true }, "baseRevision": 3 }
|
|
311
|
+
```
|
|
312
|
+
|
|
313
|
+
- **回到真正惰性**:把 `mode` 设回 `selected` 并清空列表。**注意 `workspaceIds` 只在
|
|
314
|
+
`selected` 模式下起作用**:`isVisible` 对 `mode:"global"` 恒为真(`src/scope/doc.ts`,
|
|
315
|
+
`global` 分支根本不读列表),所以**先处于 `global` 时只写 `workspaceIds: []` 什么都停不
|
|
316
|
+
下来**——投影与替换会照常进行,而你以为已经回滚了。在 `selected` 下移除单个工作区即可;
|
|
317
|
+
在 `global` 下必须同时改 `mode`:
|
|
318
|
+
|
|
319
|
+
```json
|
|
320
|
+
{ "cmd": "scope-set", "body": { "mode": "selected", "workspaceIds": [] }, "baseRevision": 4 }
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
`selected` + 空列表时协议段、投影、替换全部停止(只剩下 `boost` 工具 schema 的常驻开销)。
|
|
324
|
+
|
|
325
|
+
- **卸载插件**:`dsh plugin --profile <name> remove dsh-boost`,然后重启 DSH。
|
|
326
|
+
- 删除 `$DSH_HOME/boost` 会清掉 scope 与收据(回到默认),但不会删除宿主 spill 后端里已经
|
|
327
|
+
写出的原文文件。
|
|
328
|
+
|
|
329
|
+
## 宿主依赖
|
|
330
|
+
|
|
331
|
+
`inject` 是硬依赖:`tools`、`systemPrompt`——缺任一,插件加载失败。`llm` 是软依赖(只有
|
|
332
|
+
选择器用),缺失时选择器以 `selector-unavailable` 退回,投影与替换的其余部分照常。
|
|
333
|
+
|
|
334
|
+
| 依赖 | 形态 | 缺失时 |
|
|
335
|
+
|---|---|---|
|
|
336
|
+
| `workspaceRegistry` | 软(`ctx.get('workspaceRegistry')`) | **工作区不可见**:cwd 永远映射不到工作区 id,一切按 fail-closed 视为不可见——协议段不注入、投影与替换全部跳过,只有 `skip:no-scope` 收据在涨;`status.degraded` 带 `ERR_HOST_NO_WORKSPACE_REGISTRY`。这是**工作区本应可见却不可见**时的宿主能力解释,不是「装上了却什么都不发生」的唯一解释:默认 `selected + []` 按设计就是惰性的且不报错;缺 token meter 会拒绝真正的替换;`complete: true` 提示段会压掉协议段 |
|
|
337
|
+
| `tokenMeter` | 软(`ctx.get('tokenMeter')`) | 拒绝替换;投影仍可用,投影账记 `unknown`(不伪造数字);`status.degraded` 带 `ERR_HOST_NO_TOKENMETER` |
|
|
338
|
+
| `spillStore` | 软(`ctx.get('spillStore')`) | `projection: 'on'` 时超限回执不投影(保住证据),收据记 `projection-skipped:no-spill`;`status.degraded` 带 `ERR_HOST_NO_SPILL`(实时探测只在 on 模式;历史收据在任何模式下都会让它出现) |
|
|
339
|
+
| `@deepseek-ai/dsh-spill-policy/notice` | 软(动态 import) | spill 后端在,但页脚渲染器 `formatSpillNotice` 加载不到/不存在:apply 模式无法拼页脚,逐条跳过(收据 `projection-skipped:no-footer`),`status.degraded` 带 `ERR_HOST_NO_SPILL_NOTICE`。这与「没有 spill 后端」的 `ERR_HOST_NO_SPILL` 是两件事 |
|
|
340
|
+
| `@deepseek-ai/dsh-token-meter/estimate` | 软(动态 import) | 固定开销无法测量,`fixedOverheadTokens` 为 `'unknown'`;`status.degraded` 带 `ERR_HOST_NO_ESTIMATOR` |
|
|
341
|
+
| `win32` 平台 | 运行时检查 `isPosixOnly()` | 拒绝替换,投影照常;`status.degraded` 带 `ERR_HOST_PLATFORM_UNSUPPORTED` |
|
|
342
|
+
| 宿主版本线 | 启动时读 `@deepseek-ai/dsh-app-boot` 的版本 | 不是 `0.2.2-rc.4` 时日志警告 `ERR_HOST_VERSION_MISMATCH`,插件照常加载(advisory,不是 `status.degraded` 码);版本读不到时只记 info,不发码 |
|
|
343
|
+
| 收据分片可读性 | `boost status` 全量扫描(非依赖) | 至少一个收据分片读不出来(EACCES、名为 `x.jsonl` 的目录等)时 `status.degraded` 带 `ERR_RECEIPTS_UNREADABLE`;`status` 仍是**全量聚合**——健康分片照常计数——所以数字可能不完整。查 `$DSH_HOME/boost/receipts/` 的权限与异常条目,修复后重跑并对比计数 |
|
|
344
|
+
| 收据分片数量 | `boost status` 全量扫描(非依赖) | 分片超过 256 个时 `status` 只统计按编码名排序的前 256 个,`status.degraded` 带 `ERR_RECEIPTS_TRUNCATED`,所有计数因此是**下界**;分片永不自动删除,可归档/移走旧会话分片后重跑 `status` |
|
|
345
|
+
| 提示段装配瀑布 | 出站请求探测(非依赖) | 宿主的 `complete: true` 提示段在装配瀑布之后替换了整个系统提示、协议段没有到达请求时,`status.degraded` 带 `ERR_HOST_COMPLETE_SECTION`;受影响请求上替换与投影 fail-closed(工作区明明可见插件却不动作)。找出宿主里覆盖瀑布的 complete 段(通常属于另一个插件)并移除,或接受这些请求上不动作 |
|
|
346
|
+
|
|
347
|
+
`ERR_HOST_NO_STEP_WHEN` 已不存在:步骤级 `when` 从本包声明的最老宿主线起就在
|
|
348
|
+
`ToolRegistrationOptions` 里,插件不再探测、无条件注册。
|
|
349
|
+
|
|
350
|
+
注册阶段还有几个只进日志、不进 `status.degraded` 的码:协议段注册抛出**非重复**错误时记
|
|
351
|
+
`ERR_BOOST_SECTION_REGISTER_FAILED`;`registerHooks` 在第一个挂载处中止,后续替换/投影/
|
|
352
|
+
execute 钩子都不会注册,请求路径实际 inert,只有 `boost` 工具与会话事件仍会尝试挂载。宿主
|
|
353
|
+
真正的重复注册错误记 `ERR_BOOST_ALREADY_MOUNTED` 并跳过本次挂载;`boost` 工具自身注册失败
|
|
354
|
+
记 `ERR_BOOST_TOOL_REGISTER_FAILED`。
|
|
355
|
+
|
|
356
|
+
`ERR_HOST_NO_TOKENMETER` 与 `ERR_HOST_NO_ESTIMATOR` 是**两件不同的事**,不要合并:
|
|
357
|
+
前者是宿主服务(`ctx.get('tokenMeter')`)不存在,替换被拒绝;后者是纯估算包
|
|
358
|
+
`@deepseek-ai/dsh-token-meter/estimate` 不可达,只影响固定开销的数字。一个可以存在而另一个
|
|
359
|
+
不存在;合并会把操作者引到错误的宿主上。`ERR_HOST_NO_SPILL`(没有 spill 后端)与
|
|
360
|
+
`ERR_HOST_NO_SPILL_NOTICE`(后端在、页脚渲染器不在)也是两件事,修复方式不同。
|
|
361
|
+
|
|
362
|
+
`ERR_HOST_NO_SPILL` 有两半:**实时宿主探测**只在 `projection: 'on'` 时报告(影子模式不碰
|
|
363
|
+
spill,报它只会制造噪音);但**收据通道**不看当前模式——任何一条历史收据带
|
|
364
|
+
`projection-skipped:no-spill`,`status` 都会把它映射成该码,所以把投影切回 `off` 之后,旧收据
|
|
365
|
+
仍会让它出现在 `degraded` 里。
|
|
366
|
+
|
|
367
|
+
`tokenMeter` 与 `spillStore` 不能写进 `inject`:宿主没有该服务时插件会直接加载失败,
|
|
368
|
+
“拒绝替换、投影照做、保住证据”的降级路径就不可达。
|
|
369
|
+
|
|
370
|
+
## v1 的边界
|
|
371
|
+
|
|
372
|
+
- 只做两件事:**就地替换工具回执**,以及**替换只读调用**(`read` / `grep` / `glob`)。
|
|
373
|
+
- **不批量执行工具调用**(没有 PTC / `run_code`,设计 N1)。
|
|
374
|
+
- **不去重、不合并工具调用**(设计 N5)——这条完全没开工,且 v1 **没有任何工具能测出重复
|
|
375
|
+
调用率**:设计稿里用来触发重启判定的「影子周重复率统计」没有交付,`shadow-report.mjs`
|
|
376
|
+
不产出它。
|
|
377
|
+
- **影子周按设计零节省**:只记账(协议段照注入、选择器照调用),它的产出是四个比例,
|
|
378
|
+
不是省下的 token。
|
|
379
|
+
- **v1 不评判「结果更好」**:只有 token 账目与 20 任务回退门,没有任何质量指标;「替换后
|
|
380
|
+
结果质量」在 v1 是不可判的。
|
|
381
|
+
- **装上但未启用是小的净亏**:`boost` 工具只要插件装配就注册,schema 实测 399 token/请求
|
|
382
|
+
常驻(见「启用」一节的分解),收益为零。
|
|
383
|
+
- **不支持 desktop profile**(设计 D6)。
|
|
384
|
+
- 不替换、也不接管 DSH 的压缩、剪枝与 spill 决策(设计 N3);投影只改模型可见 content,
|
|
385
|
+
原文仍借宿主 spill 存放。
|
|
386
|
+
- 不做模型训练或权重改动(N2);不追求论文里的 87.93%(N4)。
|
|
387
|
+
- 不承诺 10%:3.5% 是保底线,10% 是全程存活的理想上界;影子周只告诉你是否继续,不能把
|
|
388
|
+
区间换成实测值(`shadow-report.mjs` 只有四个比例,没有总 token 分母)。
|
|
389
|
+
|
|
390
|
+
## 文档
|
|
391
|
+
|
|
392
|
+
以下文档在**仓库**里,不在 npm tarball 里(`files` 只带 `dist`、`locale`、`cordis.patch.yml`、
|
|
393
|
+
两份 README、`LICENSE`、`NOTICE`;`src/` 也不进包,`dist` 的 sourcemap 内联了源码)。在 npm
|
|
394
|
+
页面上请从仓库读取。
|
|
395
|
+
|
|
396
|
+
源码与文档在仓库 [github.com/SAXEM1997/dsh-boost](https://github.com/SAXEM1997/dsh-boost);
|
|
397
|
+
`package.json` 的 `repository`、`homepage`、`bugs` 都指向它。下面的文档链接是仓库相对路径。
|
|
398
|
+
|
|
399
|
+
| 文档 | 内容 |
|
|
400
|
+
|---|---|
|
|
401
|
+
| [设计稿](docs/superpowers/specs/2026-11-18-dsh-token-efficiency-design.md) | 目标、证据、架构、契约、度量、风险、发布形态 |
|
|
402
|
+
| [宿主契约附录](docs/superpowers/plans/2026-11-18-host-contracts.md) | 逐条抄自宿主源码的接口准绳 |
|
|
403
|
+
| [三层委派研究](docs/research/2026-11-18-three-tier-delegation.md) | 缓存、路由阈值、压缩、校验的 25 条一手来源 |
|
|
404
|
+
| [发布验收](docs/RELEASE.md) | `npm run verify:package` 一条命令验收、零 peerDependencies 现状与安装规格、降级码矩阵、20 任务回归门、影子周与统计复算 |
|
|
405
|
+
|
|
406
|
+
## 许可证
|
|
407
|
+
|
|
408
|
+
Apache-2.0。机制移植自 [HarnessMM](https://github.com/YuhuaJiang2002/HarnessMM)(Apache-2.0),
|
|
409
|
+
随包分发 `NOTICE`。
|
package/cordis.patch.yml
ADDED
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
# dsh-boost bundle patch — one insert over the profile root.
|
|
2
|
+
#
|
|
3
|
+
# Row ids are stable identity in the config tree; a later layer (the user's
|
|
4
|
+
# profile cordis.patch.yml, $DSH_HOME/cordis.patch.yml, --patch overlays)
|
|
5
|
+
# overrides a row by id.
|
|
6
|
+
#
|
|
7
|
+
# A patch replaces the targeted row's whole `config` rather than merging into
|
|
8
|
+
# it, so the keys below are this profile's complete configuration surface. A
|
|
9
|
+
# missing key falls back to the plugin default. All five tool families are
|
|
10
|
+
# always configured (`resolveConfig` fills them from defaults), so deleting a
|
|
11
|
+
# family here does not disable it: it only restores that family's default
|
|
12
|
+
# window. To disable one, raise its `triggerChars` above every receipt (the
|
|
13
|
+
# projection byte cap is 256 KiB, so 300000 prevents it from triggering).
|
|
14
|
+
#
|
|
15
|
+
# The loader pushes top-level `insert` rows into the assembly plan without any
|
|
16
|
+
# id/name matching (cordis-plugin-include `applyEntryPatches`); nothing is
|
|
17
|
+
# "silently skipped" at load time. The `row.id === entry.options.id &&
|
|
18
|
+
# row.name === entry.options.name` equalities are the plugin manager's in-use /
|
|
19
|
+
# addressable attribution (dsh-plugin-manager `listPlugins` / `removeBundle`):
|
|
20
|
+
# they decide whether a running entry is recognised as this bundle's row and
|
|
21
|
+
# can be addressed or removed through the profile patch. The two equalities
|
|
22
|
+
# are independent, so `id` and `name` need not match each other; keeping all
|
|
23
|
+
# four identical (package name, exported plugin name, row id, row name =
|
|
24
|
+
# `dsh-boost`) keeps the row addressable in the management plane.
|
|
25
|
+
|
|
26
|
+
- insert:
|
|
27
|
+
- id: dsh-boost
|
|
28
|
+
name: 'dsh-boost'
|
|
29
|
+
config:
|
|
30
|
+
projection:
|
|
31
|
+
read: { triggerChars: 3000, headChars: 2000, tailChars: 500 }
|
|
32
|
+
grep: { triggerChars: 700, headChars: 400, tailChars: 100 }
|
|
33
|
+
glob: { triggerChars: 700, headChars: 400, tailChars: 100 }
|
|
34
|
+
bash: { triggerChars: 4000, headChars: 2000, tailChars: 500 }
|
|
35
|
+
ssh: { triggerChars: 2000, headChars: 1200, tailChars: 300 }
|
|
36
|
+
admission: { thresholdTokens: 1024 }
|
|
37
|
+
selector: { maxTokens: 512 }
|
|
38
|
+
stepsPerTurn: 8
|
|
39
|
+
horizonSteps: 20
|
|
40
|
+
historyTurns: 5
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
/** The import seam, injectable so a test can simulate an absent/broken peer. */
|
|
2
|
+
type ModuleLoader = <T>(specifier: string) => Promise<T | undefined>;
|
|
3
|
+
/** One measured fixed-overhead breakdown, in tokens. */
|
|
4
|
+
export interface FixedOverheadMeasurement {
|
|
5
|
+
/** The protocol section alone (`estimateSystemMessage`). */
|
|
6
|
+
protocolTokens: number;
|
|
7
|
+
/** The `boost` tool schema alone (`estimateToolsTokens`). */
|
|
8
|
+
toolSchemaTokens: number;
|
|
9
|
+
/** The per-request total the design budgets at ≤800. */
|
|
10
|
+
totalTokens: number;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Measure the full fixed overhead: the protocol section **and** the tool schema.
|
|
14
|
+
*
|
|
15
|
+
* Both components are priced by the same host estimator module. Any failure
|
|
16
|
+
* (missing package/export, a throw, a non-finite part) makes the whole result
|
|
17
|
+
* `'unknown'`; a partial total would be a fabricated number. The tool schema is
|
|
18
|
+
* wrapped in the canonical-envelope shape `estimateToolsTokens` reads
|
|
19
|
+
* (`{ tools: [...] }`), never stringified by hand, so the measurement stays the
|
|
20
|
+
* host's rather than a second heuristic.
|
|
21
|
+
*/
|
|
22
|
+
export declare function measureFixedOverhead(toolSchema: unknown, text?: string, load?: ModuleLoader): Promise<FixedOverheadMeasurement | 'unknown'>;
|
|
23
|
+
export {};
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fixed overhead: what the plugin costs on **every** request.
|
|
3
|
+
*
|
|
4
|
+
* The protocol section and the `boost` tool schema are injected regardless of
|
|
5
|
+
* whether the plugin ever saves a token, so the design budgets them at ≤800
|
|
6
|
+
* tokens per request and requires the measured value in `boost status`
|
|
7
|
+
* (design §6.1). The measurement uses the host's own fixed-density estimator
|
|
8
|
+
* (`estimateSystemMessage` / `estimateToolsTokens` from
|
|
9
|
+
* `@deepseek-ai/dsh-token-meter/estimate`), a dynamic import of an undeclared package: a missing
|
|
10
|
+
* package must degrade to `'unknown'`, never to a fabricated zero, because the
|
|
11
|
+
* audit reader cannot tell a real zero from an absent measurement
|
|
12
|
+
* (design §9: do not fabricate).
|
|
13
|
+
*
|
|
14
|
+
* Both components stay visible. The protocol section alone is not the number
|
|
15
|
+
* the design names: the `boost` tool schema is another ~399 tokens, and a
|
|
16
|
+
* status figure that silently omits it understates the cost it is named after.
|
|
17
|
+
* `fixedOverheadTokens` is therefore the total, with
|
|
18
|
+
* `fixedOverhead.protocolTokens` / `fixedOverhead.toolSchemaTokens` alongside.
|
|
19
|
+
*
|
|
20
|
+
* This is a **startup/status-time** measurement, never a per-request one:
|
|
21
|
+
* `apply` starts the memoised probe once, `boost status` awaits it, and no hot
|
|
22
|
+
* path imports this module. The dynamic import is Node-module-cached and the
|
|
23
|
+
* estimate is O(text + schema length).
|
|
24
|
+
*
|
|
25
|
+
* @module dsh-boost/admission/fixed-cost
|
|
26
|
+
*/
|
|
27
|
+
import { loadOptional } from '../host/loader.js';
|
|
28
|
+
import { PROTOCOL_TEXT } from '../prompt/protocol.js';
|
|
29
|
+
/** One non-negative finite estimate, or `undefined` when it cannot be trusted. */
|
|
30
|
+
function usable(value) {
|
|
31
|
+
return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* Measure the full fixed overhead: the protocol section **and** the tool schema.
|
|
35
|
+
*
|
|
36
|
+
* Both components are priced by the same host estimator module. Any failure
|
|
37
|
+
* (missing package/export, a throw, a non-finite part) makes the whole result
|
|
38
|
+
* `'unknown'`; a partial total would be a fabricated number. The tool schema is
|
|
39
|
+
* wrapped in the canonical-envelope shape `estimateToolsTokens` reads
|
|
40
|
+
* (`{ tools: [...] }`), never stringified by hand, so the measurement stays the
|
|
41
|
+
* host's rather than a second heuristic.
|
|
42
|
+
*/
|
|
43
|
+
export async function measureFixedOverhead(toolSchema, text = PROTOCOL_TEXT, load = loadOptional) {
|
|
44
|
+
try {
|
|
45
|
+
const module = await load('@deepseek-ai/dsh-token-meter/estimate');
|
|
46
|
+
if (module === undefined ||
|
|
47
|
+
typeof module.estimateSystemMessage !== 'function' ||
|
|
48
|
+
typeof module.estimateToolsTokens !== 'function') {
|
|
49
|
+
return 'unknown';
|
|
50
|
+
}
|
|
51
|
+
const protocolTokens = usable(module.estimateSystemMessage({ role: 'system', content: [{ type: 'text', text }] }));
|
|
52
|
+
const toolSchemaTokens = usable(module.estimateToolsTokens({ tools: [toolSchema] }));
|
|
53
|
+
if (protocolTokens === undefined || toolSchemaTokens === undefined)
|
|
54
|
+
return 'unknown';
|
|
55
|
+
return { protocolTokens, toolSchemaTokens, totalTokens: protocolTokens + toolSchemaTokens };
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
return 'unknown';
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
//# sourceMappingURL=fixed-cost.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fixed-cost.js","sourceRoot":"","sources":["../../src/admission/fixed-cost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAqBrD,kFAAkF;AAClF,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAA;AAC9F,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,UAAmB,EACnB,OAAe,aAAa,EAC5B,OAAqB,YAAY;IAEjC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAiB,uCAAuC,CAAC,CAAA;QAClF,IACE,MAAM,KAAK,SAAS;YACpB,OAAO,MAAM,CAAC,qBAAqB,KAAK,UAAU;YAClD,OAAO,MAAM,CAAC,mBAAmB,KAAK,UAAU,EAChD,CAAC;YACD,OAAO,SAAS,CAAA;QAClB,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,CAC3B,MAAM,CAAC,qBAAqB,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CACpF,CAAA;QACD,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,mBAAmB,CAAC,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAA;QACpF,IAAI,cAAc,KAAK,SAAS,IAAI,gBAAgB,KAAK,SAAS;YAAE,OAAO,SAAS,CAAA;QAEpF,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,GAAG,gBAAgB,EAAE,CAAA;IAC7F,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC","sourcesContent":["/**\n * Fixed overhead: what the plugin costs on **every** request.\n *\n * The protocol section and the `boost` tool schema are injected regardless of\n * whether the plugin ever saves a token, so the design budgets them at ≤800\n * tokens per request and requires the measured value in `boost status`\n * (design §6.1). The measurement uses the host's own fixed-density estimator\n * (`estimateSystemMessage` / `estimateToolsTokens` from\n * `@deepseek-ai/dsh-token-meter/estimate`), a dynamic import of an undeclared package: a missing\n * package must degrade to `'unknown'`, never to a fabricated zero, because the\n * audit reader cannot tell a real zero from an absent measurement\n * (design §9: do not fabricate).\n *\n * Both components stay visible. The protocol section alone is not the number\n * the design names: the `boost` tool schema is another ~399 tokens, and a\n * status figure that silently omits it understates the cost it is named after.\n * `fixedOverheadTokens` is therefore the total, with\n * `fixedOverhead.protocolTokens` / `fixedOverhead.toolSchemaTokens` alongside.\n *\n * This is a **startup/status-time** measurement, never a per-request one:\n * `apply` starts the memoised probe once, `boost status` awaits it, and no hot\n * path imports this module. The dynamic import is Node-module-cached and the\n * estimate is O(text + schema length).\n *\n * @module dsh-boost/admission/fixed-cost\n */\nimport { loadOptional } from '../host/loader.js'\nimport { PROTOCOL_TEXT } from '../prompt/protocol.js'\n\n/** The export shapes this module reads from the host's estimate module. */\ninterface EstimateModule {\n estimateSystemMessage?: (message: unknown) => number\n estimateToolsTokens?: (header: unknown) => number\n}\n\n/** The import seam, injectable so a test can simulate an absent/broken peer. */\ntype ModuleLoader = <T>(specifier: string) => Promise<T | undefined>\n\n/** One measured fixed-overhead breakdown, in tokens. */\nexport interface FixedOverheadMeasurement {\n /** The protocol section alone (`estimateSystemMessage`). */\n protocolTokens: number\n /** The `boost` tool schema alone (`estimateToolsTokens`). */\n toolSchemaTokens: number\n /** The per-request total the design budgets at ≤800. */\n totalTokens: number\n}\n\n/** One non-negative finite estimate, or `undefined` when it cannot be trusted. */\nfunction usable(value: unknown): number | undefined {\n return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined\n}\n\n/**\n * Measure the full fixed overhead: the protocol section **and** the tool schema.\n *\n * Both components are priced by the same host estimator module. Any failure\n * (missing package/export, a throw, a non-finite part) makes the whole result\n * `'unknown'`; a partial total would be a fabricated number. The tool schema is\n * wrapped in the canonical-envelope shape `estimateToolsTokens` reads\n * (`{ tools: [...] }`), never stringified by hand, so the measurement stays the\n * host's rather than a second heuristic.\n */\nexport async function measureFixedOverhead(\n toolSchema: unknown,\n text: string = PROTOCOL_TEXT,\n load: ModuleLoader = loadOptional,\n): Promise<FixedOverheadMeasurement | 'unknown'> {\n try {\n const module = await load<EstimateModule>('@deepseek-ai/dsh-token-meter/estimate')\n if (\n module === undefined ||\n typeof module.estimateSystemMessage !== 'function' ||\n typeof module.estimateToolsTokens !== 'function'\n ) {\n return 'unknown'\n }\n\n const protocolTokens = usable(\n module.estimateSystemMessage({ role: 'system', content: [{ type: 'text', text }] }),\n )\n const toolSchemaTokens = usable(module.estimateToolsTokens({ tools: [toolSchema] }))\n if (protocolTokens === undefined || toolSchemaTokens === undefined) return 'unknown'\n\n return { protocolTokens, toolSchemaTokens, totalTokens: protocolTokens + toolSchemaTokens }\n } catch {\n return 'unknown'\n }\n}\n"]}
|