dsh-injection-manager 1.10.4 → 2.0.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 (49) hide show
  1. package/CHANGELOG.md +267 -0
  2. package/CONTRIBUTING.md +2 -2
  3. package/README.md +282 -94
  4. package/README.zh.md +236 -97
  5. package/client.js +3325 -295
  6. package/docs/ARCHITECTURE.md +111 -24
  7. package/docs/COMPATIBILITY.md +28 -7
  8. package/docs/DETAIL.md +148 -0
  9. package/docs/DETAIL.zh.md +105 -1
  10. package/docs/FAQ.md +49 -7
  11. package/docs/PERFORMANCE.md +60 -6
  12. package/docs/images/demo.gif +0 -0
  13. package/docs/images/dock.png +0 -0
  14. package/docs/images/panel-dark.png +0 -0
  15. package/docs/images/panel-drawer.png +0 -0
  16. package/docs/images/panel-insights.png +0 -0
  17. package/docs/images/panel-manage-expanded.png +0 -0
  18. package/docs/images/panel-manage.png +0 -0
  19. package/docs/images/panel-settings.png +0 -0
  20. package/docs/images/panel-sidebar.png +0 -0
  21. package/docs/preview.svg +177 -23
  22. package/icon.svg +19 -5
  23. package/index.js +100 -14
  24. package/lib/actions.js +12 -4
  25. package/lib/apply.js +14 -2
  26. package/lib/compaction.js +126 -0
  27. package/lib/content.js +360 -0
  28. package/lib/events.js +216 -0
  29. package/lib/health.js +210 -0
  30. package/lib/pressure.js +146 -0
  31. package/lib/routes.js +293 -9
  32. package/lib/snapshot.js +256 -29
  33. package/lib/stats.js +394 -0
  34. package/lib/text.js +160 -0
  35. package/lib/trend.js +168 -0
  36. package/locale/de.json +251 -6
  37. package/locale/en.json +251 -6
  38. package/locale/es.json +251 -6
  39. package/locale/fr.json +251 -6
  40. package/locale/ja.json +251 -6
  41. package/locale/pt.json +251 -6
  42. package/locale/ru.json +252 -7
  43. package/locale/zh.json +249 -4
  44. package/package.json +16 -3
  45. package/screenshots.json +7 -5
  46. package/docs/images/panel-about.png +0 -0
  47. package/docs/images/panel-budget.png +0 -0
  48. package/docs/images/panel-policy.png +0 -0
  49. package/docs/images/panel-suites.png +0 -0
@@ -1,6 +1,6 @@
1
1
  # 架构
2
2
 
3
- 这份文档只讲一件事:一次新会话的首轮上下文,从策略文件到模型请求,中间经过哪些环节、每一环用什么接口、失败时会怎样。
3
+ 这份文档只讲一件事:一次新会话的首轮上下文,从策略文件到模型请求,中间经过哪些环节、每一环用什么接口、失败时会怎样;v2 新增的只读表面(内容透视、趋势、事件、健康检查)分别从哪来、写到哪去。
4
4
 
5
5
  ## 四条注入通道
6
6
 
@@ -17,7 +17,7 @@
17
17
 
18
18
  ## 快照流水线
19
19
 
20
- 面板、模型工具、导出文件、应用策略,全部来自同一次 `buildSnapshot()`:
20
+ 面板、模型工具、导出文件、应用策略、健康检查、内容抽屉,全部来自同一次 `buildSnapshot()`:
21
21
 
22
22
  ```
23
23
  policy.json ──┐
@@ -26,18 +26,21 @@ Config ───────┤
26
26
  工作目录 ─────┤ collectSkills (snapshot)
27
27
  │ collectTools (schemas)
28
28
  │ collectInstructions (固定路径探测)
29
+ │ readContext (tokenMeter + contextBreakdown + llm)
29
30
  ▼
30
31
  assignGroups() → 按套件聚类
31
32
  ▼
32
33
  previewPolicy() → 关掉后剩多少 / 省多少
33
34
  planBudget() → 目标预算下的关闭建议
34
35
  ▼
35
- { items, groups, channels, totals, policy, undo }
36
- ▼
37
- panel · context_injection 工具 · /export · applyPolicyForAgent
36
+ { items(+preview), groups, channels, totals, context, policy, undo }
37
+ ├─▶ 面板 / context_injection / /export / applyPolicyForAgent
38
+ └─▶ buildHealth(snapshot) → 健康检查(纯函数,见下)
38
39
  ```
39
40
 
40
- 关键不变量:**只有一份实现**。浏览器不重算 token、不重算预览;它拿到什么就画什么。这也让「预览数字」和「实际生效」不会打架。
41
+ `context` 那一路是唯一不由本插件估算的部分:`window` / `pressure` / `projected` 来自宿主的 `contextPressure` 投影,`breakdown` 来自 `contextBreakdown`,(缺分母时才)用 `ctx.llm.resolveModelInfo()` 的 `contextWindow` 兜底;压缩回执由 `session/event` 监听器从 `compaction/*` 累积。因此面板里的占用百分比与宿主自己的「上下文已用 x%」是同一个数,不会各说各话。
42
+
43
+ 关键不变量:**只有一份实现**。浏览器不重算 token、不重算预览;它拿到什么就画什么。这也让「预览数字」和「实际生效」不会打架。v2 只加了两个派生:每个条目的 `preview`(快照阶段切好的前 180 字符纯文本)和 `buildHealth()` 的检查结果——两者都从同一份快照算,不额外读盘。
41
44
 
42
45
  ## 生效时序
43
46
 
@@ -60,31 +63,106 @@ agent/created (source=startup|clear)
60
63
 
61
64
  `resume` / `compact` 不处理:它们带着已有历史,中途改写不是「默认策略」该做的事。
62
65
 
63
- ## 数据
66
+ ## HTTP 面
64
67
 
65
- | 位置 | 内容 | 谁写 |
66
- | --- | --- | --- |
67
- | `$DSH_HOME/injection-manager/policy.json` | 通道模式、名单、前言后记、预算 | 面板动作(原子写) |
68
- | `$DSH_HOME/injection-manager/` 的旧目录 | `context-injection/`、`context-preflight/` | 只在首次读取时迁移 |
69
- | 插件行 `config` | dock / refreshOnFocus / showRawNames / budgetTokens | Plugins → Configuration |
70
- | 内存 | 撤销栈(20 步)、最近一次应用结果、客户端 boot 报告 | 进程内,重启清空 |
68
+ 全部挂在 `/plugins/dsh-injection-manager` 下,共 15 条路由:**12 条只读 GET + 3 条 POST-only**(`/action` 改策略;`/boot`、`/registrations` 是客户端自报诊断,二者收到 GET 会返回 405):
69
+
70
+ | 路由 | 方法 | 作用 | 响应要点 |
71
+ | --- | --- | --- | --- |
72
+ | `/ping` | GET | 注册自检 | 路由清单、策略文件路径 |
73
+ | `/summary` | GET | 面板快照 | `apiVersion: 2`、`healthSummary {high,warn,info}`、`items[].preview`、`settings`、`locale` |
74
+ | `/content` | GET | 单条原文 | `?channel=&id=[&session=]`;`contentType`、`content`、`bytes`、`truncated`、`sourcePath`、`note`;256KB 上限、2 秒预算、404/400 分支 |
75
+ | `/trend` | GET | 跨会话趋势 | `?range=all|30d|7d&limit=120`(上限 500);`points[]`、`aggregate`、`coverage {recorded, known}`、`backfilling` |
76
+ | `/events` | GET | 事件流 | `?session=&limit=60`(上限 300);`events[]`、`coverage {from, count, limit}` |
77
+ | `/health` | GET | 健康检查 | `?session=`;`summary {high,warn,info,checkedAt}`、`checks[]`(`code`、`severity`、`params`、可选 `action`) |
78
+ | `/stats` | GET | 历史与覆盖 | `stats.json` 内容 + `sessions` 头信息(≤60)+ 最近一轮 `backfill` + `backfilling` + `coverage` |
79
+ | `/policy` | GET | 策略文件状态 | 策略、路径、是否迁移、最近一次应用 |
80
+ | `/verify` | GET | 生效核对 | `?session=`;重新装配后的段落/上下文/工具名 |
81
+ | `/diag` | GET | 诊断 | 客户端 boot、最近应用、过滤器调用计数、宿主版本 |
82
+ | `/export` | GET | 导出 | Markdown / JSON |
83
+ | `/locale` | GET | 八语言字典 | 客户端词条 |
84
+ | `/registrations`、`/boot` | **POST** | 客户端自报诊断(仅内存) | 启动表与注册诊断,不落盘;GET 返回 405 |
85
+ | `/action` | **POST** | 改策略入口 | 同源 JSON;开关/预设/预算/导入/撤销 |
86
+
87
+ 约定的响应边界:JSON 单次响应有上限,`/summary` 的条目文本靠 `preview` 控制体积;`/content` 的 256KB 上限和 UTF-8 安全截断在 `lib/content.js` 里实现;`/trend` 的 `limit` 与被回填的会话数都封顶;`/events` 读的是已经封顶 300 条的 `events.json`。
88
+
89
+ ## 数据文件
90
+
91
+ | 位置 | 内容 | 谁写 | 生命周期 |
92
+ | --- | --- | --- | --- |
93
+ | `$DSH_HOME/injection-manager/policy.json` | 通道模式、名单、前言后记、预算 | 面板动作(原子写) | 持久,卸载后保留 |
94
+ | `$DSH_HOME/injection-manager/stats.json` | 每个会话一行测量:`allOn` / `effective` / `saved` / `peak` / `samples` / `firstAt` / `scope` / `policy` / `compactions` / 新快照才有的 `channels` | 每次取快照(面板/工具/命令) | 上限 400 行,原子写,可被日志回填补齐 |
95
+ | `$DSH_HOME/injection-manager/events.json` | `{version:1, events:[…]}`,最多 300 条;每条 `id` / `at` / `kind` / `params`(拍平的原始值,字符串 ≤200 字符,≤24 项)/ `tokensDelta` / 可选 `sessionId` / `dedupeKey` | 策略保存、预设、预算、导入、撤销、压缩 | 追加式;tmp+rename;去重键防重放 |
96
+ | `$DSH_HOME/injection-manager/` 的旧目录 | `context-injection/`、`context-preflight/` | 只在首次读取时迁移 | 只读兼容 |
97
+ | 插件行 `config` | dock / refreshOnFocus / showRawNames / budgetTokens | Plugins → Configuration | 持久 |
98
+ | 浏览器 localStorage | 抽屉行号、洞察范围、被关掉的 gate 卡 | 面板 | 只在这个浏览器 |
99
+ | 内存 | 撤销栈(20 步)、最近一次应用结果、客户端 boot 报告、压缩回执(按会话)、路由窗口容量缓存 | 进程内 | 重启清空 |
71
100
 
72
101
  不上传、不联网、不写 workspace 文件。
73
102
 
103
+ ## 事件埋点
104
+
105
+ `lib/events.js` 是唯一的写入口,`appendEvent()` 永不抛错(事件流是锦上添花,写失败不能把一次策略保存变成错误)。当前会产生事件的来源:
106
+
107
+ | 位置 | kind | 说明 |
108
+ | --- | --- | --- |
109
+ | `index.js` 的 `agent/created` | `session-created` | 新会话建立(`source: startup|clear`),fire-and-forget,不进首轮关键路径 |
110
+ | `lib/apply.js` 的 `savePolicy()` | `policy-saved` / `preset` / `budget` / `switch` / `import` / `undo` | 由调用方通过 `meta` 指定,缺省 `policy-saved` |
111
+ | `lib/compaction.js` 的摘要/剪枝回执 | `compaction` / `prune` | 宿主的 `compaction/summary`、`compaction/prune` 事件 |
112
+ | `lib/compaction.js` 的失败回执 | `diagnostic` | 宿主报告 `compaction/*` 带 `error` 时写一条:`params {phase:'compaction', error, compactionId}`,用于解释"这次压缩失败了" |
113
+
114
+ `model-switch` / `mode-toggle` 目前在枚举里预留、本版本不会主动产生(还没有对应的宿主事件入口);`/inject health` 这类只读命令也不写事件。也就是说:**写策略、压缩/剪枝、压缩失败、新会话**会留下事件,其余读取不会。
115
+
116
+ 去重键 = `时间戳|kind|params 的稳定哈希`(压缩事件可由调用方给显式 `dedupeKey`,如 `seq/compactionId`),因此同一条宿主事件被观察两次不会变成两行。`params` 只收原始值:嵌套对象直接丢弃,数组最多 20 项,字符串截到 200 字符——会话正文没有路径能进这个文件。
117
+
118
+ ## 健康检查
119
+
120
+ `lib/health.js` 的 `buildHealth(snapshot)` 是纯函数:输入一份快照,输出 `{summary, checks}`;唯一的时钟值是 `snapshot.generatedAt`,所以同一份快照两次调用逐字节一致。面板、`/health` 路由、`/inject health` 都调它。
121
+
122
+ - 固定 9 个 code 的枚举,当前实现实际会产生 7 个:`heavy-suite`(单套 ≥25% 或 ≥30k)、`budget-gap`(预测值超预算)、`catalog-truncated`(描述被目录行截断)、`locked-items`(不可关项 ≥10%)、`unknown-window`(无测量)、`no-policy`(从没保存过策略且全开)、`empty-catalog`(目录为空且完整)。
123
+ - `duplicate-skill` 与 `tool-name-collision` **刻意不产生**:这版宿主的技能注册表与工具注册表在插件可见之前就解析掉了重名,报出来就是编造。枚举保留完整,未来宿主能观察到时再加,UI 契约不变。
124
+ - `action.kind` 只有四种:`switch-group` / `set-budget` / `open-content` / `open-tab`;`payload` 直接是 `POST /action` 能吃下的形状(`{channel, group, enabled, op}` 等),面板不再做二次映射。
125
+ - 排序:严重度 → 涉及 token 数 → code;`summary` 按严重度计数,`checkedAt` 来自快照。
126
+
127
+ ## 内容透视
128
+
129
+ `lib/content.js` 回答「这一行到底是什么」。两条硬规则:
130
+
131
+ 1. **路径白名单**:只打开快照自己收集时登记过的路径(技能的注册路径、工作区规则探测到的文件)。接口不接受调用方给的路径,因此不可能变成任意文件读取。
132
+ 2. **截断安全**:上限按字节卡(HTTP 256KB、模型工具 32KB),在码点边界切,绝不切坏多字节字符;响应里的 `bytes` 描述的是实际返回的前缀。
133
+
134
+ `sourcePath` 只有在真的来自磁盘时才有;`note` 说明来源:`catalog`(技能没有定位到 SKILL.md,给的是目录行)、`file`(磁盘文件)、`assemble`(系统提示词装配结果,无单文件)、`snapshot`(会话快照)。工具内容做 JSON 格式化后返回(`contentType: json`),面板在抽屉里拆成「描述 / 参数表 / 原始 JSON」三视图。路由层给这次收集套 2 秒预算,超时返回 `timeout` 而不是半个结果。
135
+
136
+ ## 洞察数据
137
+
138
+ `lib/trend.js` 只合并两种诚实来源:本插件写下的 `stats.json` 行(`measured`)和有界的 durable-log 回填(`log`)。回填在**后台**跑,读取从不 await 它:一个进程内单飞的任务,冷却 60 秒、每轮最多 8 个会话、单轮预算 6 秒;`/trend` 立即返回已有行并带 `backfilling: true`,后续轮询会看到后台补进来的行。这样 671 个会话的语料不会让每次打开洞察页都等 7 秒。
139
+
140
+ - 老行与日志行没有通道分解:`channels` 报 `null`,不补 0;UI 画斜纹。
141
+ - 排序按 `firstAt`(时间轴左→右),`limit` 取最近的 N 个点;`aggregate` 在切 `limit` **之前**算,所以汇总代表整个范围而不是「最近 120 个」。
142
+ - 契约修订(2026-11-16):`scope` 是自由字符串(常见 `startup|clear|route.session|backfill`,未知值原样透传、截到 64 字符),`policy` 允许 `all|minimal|custom|unknown`——不为迎合枚举而改写历史数据。
143
+ - `coverage {recorded, known}`:`known` 来自 `sessionQuery.listSessions()` 的头信息数量(可失败为 `null`),`recorded` 是范围内的行数。UI 的覆盖率脚注就是这两个数。
144
+
74
145
  ## 包结构
75
146
 
76
147
  ```
77
- index.js 插件入口:Config、工具、/inject、路由、agent/created
78
- lib/snapshot.js 快照与策略预览/预算
79
- lib/apply.js 四通道生效 + 撤销之外的注册
148
+ index.js 插件入口:Config、工具(含单条内容模式)、/inject、路由、agent/created
149
+ lib/snapshot.js 快照、套件聚类、行内预览、策略预览/预算
150
+ lib/apply.js 四通道生效 + 策略保存(含事件埋点)
80
151
  lib/group.js 套件聚类
81
152
  lib/policy.js 策略 schema、原子读写、旧目录迁移
82
- lib/routes.js HTTP 面(面板、导出、诊断、校验)
153
+ lib/routes.js HTTP 面(15 条路由、同源写校验、安全头)
154
+ lib/content.js 内容透视:白名单读取、UTF-8 安全截断
155
+ lib/events.js 事件流:校验、去重、封顶、原子写
156
+ lib/trend.js 跨会话趋势:stats + 有界日志回填合并
157
+ lib/health.js 健康检查:纯函数、固定 code 集
158
+ lib/stats.js 历史记录、通道分解、日志定价回填
83
159
  lib/history.js 撤销栈
84
160
  lib/settings.js Config 归一化
85
- lib/text.js 模型卡片与文本报告
161
+ lib/text.js 模型卡片、文本报告、健康摘要
86
162
  lib/instructions.js 工作区规则只读探测
87
- client.js 浏览器半包:侧栏图标、主页面、输入框徽标
163
+ lib/pressure.js 窗口占用(tokenMeter / contextBreakdown / llm 容量)
164
+ lib/compaction.js 压缩回执(session/event 上的 compaction/*)
165
+ client.js 浏览器半包:面板三页、侧栏、输入框徽标、内容抽屉
88
166
  locale/*.json 八语言字典(宿主展示用 meta + 客户端词条)
89
167
  ```
90
168
 
@@ -92,9 +170,10 @@ locale/*.json 八语言字典(宿主展示用 meta + 客户端词条)
92
170
 
93
171
  - 写操作(`POST /action`)要求 `content-type: application/json`,且 `sec-fetch-site` 不是跨站;带 `Origin` 时还要求 host 与页面一致。
94
172
  - 所有 JSON 响应带 `x-content-type-options: nosniff`、`x-frame-options: DENY`、`cache-control: no-store`。
95
- - 没有任何 GET 路由会写文件:`/summary`、`/verify`、`/export` 只读策略与当前会话。
96
- - 策略写入是同目录临时文件 + rename,崩溃时保留旧策略。
97
- - 插件不发起网络请求,不上传策略或会话内容。
173
+ - 没有任何 GET 路由会写文件:`/summary`、`/content`、`/trend`、`/events`、`/health`、`/stats`、`/verify`、`/export` 都只读策略、快照、统计与事件文件。
174
+ - `/content` 是唯一读磁盘内容的接口,但路径来自快照登记,不接受外部路径;有 2 秒预算与 256KB 上限。
175
+ - 策略与统计、事件写入都是同目录临时文件 + rename,崩溃时保留旧文件。
176
+ - 插件不发起网络请求,不上传策略或会话内容;`events.json` 只收策略与被截断的原始值。
98
177
 
99
178
  ## 测试
100
179
 
@@ -103,6 +182,14 @@ locale/*.json 八语言字典(宿主展示用 meta + 客户端词条)
103
182
  | `test/policy.test.mjs` | 模式语义、必填锁定、预算贪心、计划回写 |
104
183
  | `test/group.test.mjs` | MCP/前缀/provider 聚类、汇总 |
105
184
  | `test/settings.test.mjs` | 配置归一化与默认值 |
106
- | `test/text.test.mjs` | 工具卡片与文本报告的数字/告警 |
185
+ | `test/text.test.mjs` | 工具卡片、文本报告与健康摘要的数字/告警 |
107
186
  | `test/apply.test.mjs` | 假 ctx 下四条通道端到端、幂等、resume 跳过 |
108
- | `test/routes.test.mjs` | 动作/撤销/导出/同源校验(假 req/res) |
187
+ | `test/routes.test.mjs` | 动作/撤销/导出/同源校验、新路由的分支 |
188
+ | `test/pressure.test.mjs` | 占用分子/分母、容量兜底与缓存、缺数据不瞎猜、阈值档位 |
189
+ | `test/compaction.test.mjs` | 摘要/剪枝/失败回执、未知会话、事件转发 |
190
+ | `test/content.test.mjs` | 白名单、UTF-8 截断、四种 `note`、404/400、超时 |
191
+ | `test/events.test.mjs` | 去重、封顶、参数拍平、原子写、读窗 |
192
+ | `test/trend.test.mjs` | 范围切分、`channels: null`、聚合先于 limit、覆盖率 |
193
+ | `test/health.test.mjs` | 每个 code 的触发条件、排序、summary、不产生的 code |
194
+ | `test/tool-content.test.mjs` | 模型工具单条模式:参数校验、32KB 上限、错误 JSON |
195
+ | `test/command.test.mjs` | `/inject` 子命令(含 health)与错误分支 |
@@ -4,13 +4,14 @@
4
4
 
5
5
  ## 已验证
6
6
 
7
- | dsh 版本 | 结果 | 验证方式 |
8
- | --- | --- | --- |
9
- | `0.2.2-rc.3`(Desktop) | 通过 | 真实会话:`/verify` 重新装配、`/diag` 过滤器计数、子智能体实测工具集 |
10
- | `0.2.2-rc.2` | 未验证 | — |
11
- | `0.2.1` / `0.2.0` | 未验证 | 旧版 `dsh-context-preflight` 曾在早期版本上运行,但注入过滤改用 `system-prompt/assemble` 后未复测 |
7
+ | dsh 版本 | 环境 | 结果 | 验证方式 |
8
+ | --- | --- | --- | --- |
9
+ | `0.2.2-rc.1` | **CLI**:临时 profile `v2qa` 起的独立 `dsh web` 实例(49801),不碰 Desktop 实例 | 通过 | Playwright 全流程(管理/洞察/设置三 tab、内容抽屉、趋势、设置页)+ 四条新路由探针(135 项断言 PASS);宿主版本由 `hostinfo` 在真实宿主里读出 |
10
+ | `0.2.2-rc.3` | **Desktop**:用户真实 profile(49711) | 通过 | 真实会话:`/verify` 重新装配、`/diag` 过滤器计数、子智能体实测工具集 |
11
+ | `0.2.2-rc.2` | — | 未验证 | — |
12
+ | `0.2.1` / `0.2.0` | — | 未验证 | 旧版 `dsh-context-preflight` 曾在早期版本上运行,但注入过滤改用 `system-prompt/assemble` 后未复测 |
12
13
 
13
- 运行时自检:插件会读宿主版本(`DSH_INSTALL_DIR` 的 `package.json`,或 profile 里的 `@deepseek-ai/dsh`),低于 `0.2.2` 时面板顶部提示「部分开关可能不生效」;版本读不到时按未知处理,不猜。`/diag` 的 `host` 字段给出实际读到的版本与来源。
14
+ 运行时自检:插件会读宿主版本(`DSH_INSTALL_DIR` 的 `package.json`,或 profile 里的 `@deepseek-ai/dsh`),低于 `0.2.2` 时面板顶部提示「部分开关可能不生效」;版本读不到时按未知处理,不猜。版本读取在桌面 rc.3 与 CLI rc.1 两个真实宿主里都验证过(`hostinfo`),`/diag` 的 `host` 字段给出实际读到的版本与来源。
14
15
 
15
16
  ## 依赖的接口(缺一个会降级或失效)
16
17
 
@@ -24,6 +25,25 @@
24
25
  | `ctx.agents.get(id)` / `currentInitiator()` | 面板对会话取数 | 退回到最近活跃会话 |
25
26
  | `ctx.webServer.register({ kind: 'exact' })` | 面板路由 | 面板无数据(工具与命令仍可用) |
26
27
  | `agent/created` 事件的 `source` | 区分新会话与恢复/压缩 | 只按 `startup` / `clear` 兜底 |
28
+ | `ctx.get('tokenMeter').contextPressure(session)` | 窗口占用:分子(provider 报的 prompt)与分母(`contextWindow`) | 窗口卡片显示「窗口未知」,其余功能不受影响 |
29
+ | `ctx.get('sessionProjections').snapshot(session)` 的 `contextBreakdown` | 系统 / 工具 / 消息构成 | 只显示占用条,不显示构成 |
30
+ | `ctx.llm.resolveModelInfo(provider, model)` | 首次请求前拿窗口容量(按路由缓存) | 首个请求之后才有分母 |
31
+ | `session/event` 上的 `compaction/summary` / `compaction/prune` / `compaction/end` | 压缩回执与释放的 token | 不显示压缩行;数值来自宿主 `shadowedTokenCount`,缺失时不猜 |
32
+
33
+ ## v2 HTTP 契约(2.0.0 起)
34
+
35
+ 面板与宿主之间多了一层版本协商:`GET /summary` 返回 `apiVersion: 2`。新版面板读到 v1 时显示可关掉的 gate 卡(新版洞察/内容透视/健康检查需要 v2 宿主),管理、设置与开关不受影响;v1 面板连 v2 宿主则照常工作(新增字段都是追加的)。
36
+
37
+ v2 新增的四条只读路由与它们的宿主侧依赖:
38
+
39
+ | 路由 | 依赖 | 缺失时 |
40
+ | --- | --- | --- |
41
+ | `/content?channel=&id=[&session=]` | 快照登记的技能路径、规则文件路径;`node:fs` 读取 | 抽屉显示读取失败,列表与开关不受影响 |
42
+ | `/trend?range=&limit=` | `stats.json` + `sessionQuery.listSessions()`(可选) | 无 `sessionQuery` 时只读历史文件,覆盖率 `known: null` |
43
+ | `/events?session=&limit=` | `$DSH_HOME/injection-manager/events.json` | 文件不存在时返回空窗口,不报错 |
44
+ | `/health?session=` | 与面板同一份 `buildSnapshot()` | 快照失败时返回错误,面板显示「健康检查读取失败」 |
45
+
46
+ 宿主版本无关:这些路由全部由插件自己实现,只用到 `0.2.2` 已有的公开服务(`agents`、`webServer`、`sessionQuery`)。
27
47
 
28
48
  ## 明确不可管(不是兼容性问题)
29
49
 
@@ -36,4 +56,5 @@
36
56
  1. `GET /plugins/<id>/ping` 是否 200(路由注册)。
37
57
  2. `GET /plugins/<id>/diag` 的 `clientModule` 是否有值(客户端进了 boot 表)、`rewrite.count` 是否随新会话增长(过滤器被调用)。
38
58
  3. `GET /plugins/<id>/verify?session=<id>` 对比 `sections` 数量与面板预期。
39
- 4. 仍不对时,先确认该版本是否仍导出上表中的方法(版本 release notes 与包内 README)。
59
+ 4. 新版表面单独排查:`/health` 是否 200(健康条)、`/trend` 是否返回点(洞察)、`/content?channel=tools&id=tool:<name>` 是否 200(抽屉);`/summary` 的 `apiVersion` 不是 2 时面板会显示 gate 卡,说明宿主加载的是旧版服务端半包。
60
+ 5. 仍不对时,先确认该版本是否仍导出上表中的方法(版本 release notes 与包内 README)。
package/docs/DETAIL.md CHANGED
@@ -1 +1,149 @@
1
1
  ![Context injection: many sources narrowed into one first request](preview.svg)
2
+
3
+ # What this plugin actually changes
4
+
5
+ A new DSH session receives a lot before its first request reaches a model: the system prompt
6
+ sections, runtime contexts, the skill catalog as text, one JSON schema per tool, and the
7
+ `AGENTS.md` chain. None of it is visible in the conversation, and there is no single place to
8
+ turn any of it off.
9
+
10
+ This page is the five-minute version of what the plugin measures, what it can and cannot switch,
11
+ and what the new surfaces show. The [README](../README.md) is the overview; the
12
+ [architecture](ARCHITECTURE.md) is the implementation.
13
+
14
+ ## 1. Three numbers, three questions
15
+
16
+ | Number | Question | Where it comes from |
17
+ | --- | --- | --- |
18
+ | First-turn injection (e.g. 83.8k) | What will the *next new session* be given? | Assembled here: prompt sections and contexts from `systemPrompt.assemble()`, skills from `skills.snapshot()`, tool schemas from `tools.schemas()`, `AGENTS.md` read from the default chain |
19
+ | Window occupancy (e.g. 36%) | How full is *this* conversation? | The host's own `contextPressure` projection, divided by the model's window |
20
+ | Content (the drawer) | What does one line *actually say*? | The snapshot's own registered sources: assembled text, tool declarations, skill files or catalog lines, instruction files |
21
+
22
+ They are not comparable, and the panel never subtracts one from the other. The first number is
23
+ what the plugin controls; the second decides when the host compacts; the third is the raw text
24
+ behind a row, read only when you open it.
25
+
26
+ Token counts from this plugin are estimates (ASCII ÷ 4, other characters ÷ 1.6). The occupancy
27
+ figure is not: `pressureTokens` is provider-reported, and the window comes from the same request
28
+ record the model adapter used.
29
+
30
+ ## 2. Three tabs, two ambient entries
31
+
32
+ | Surface | What it is for |
33
+ | --- | --- |
34
+ | Manage (管理) | Health strip, KPI row, request strip, then the suite-clustered list with switches; every row can expand a preview or open its content. |
35
+ | Insights (洞察) | Cross-session first-turn trend, aggregate band, session cards, cross-session composition, heaviest suites, this session's event timeline, coverage footnote. |
36
+ | Settings (设置) | Presets, four channel masters, custom prefix/suffix, budget, export/import, undo history, verification, plugin preferences, versions and language. |
37
+ | Composer chip | First-turn total and window occupancy, one line, deliberately muted; × hides it. |
38
+ | `/inject` + `context_injection` | The same numbers as text, plus a read-only model tool (optionally one item's content). |
39
+
40
+ ## 3. What the manage page shows
41
+
42
+ - **Health** — deterministic findings over the current snapshot (section 5), each with an action.
43
+ - **KPI** — first-turn injection, window occupancy with its denominator, the switchable share and the
44
+ current budget; the composer chip mirrors the same numbers.
45
+ - **Request strip** — system / tools / messages split of the *current* request and compaction
46
+ receipts, from the host's own projections.
47
+ - **The list** — five channels, clustered into suites (one MCP server = one switch), with a
48
+ description column for every item. A suite row carries item count, tokens, share and a tri-state
49
+ switch; a closed suite stays visible with its remembered size so it can be reopened. Items expand
50
+ an inline preview; the content button opens the drawer.
51
+
52
+ ## 4. What the content drawer reads
53
+
54
+ Only sources the snapshot itself registered — a request cannot name a path:
55
+
56
+ | Row | Content | Note shown |
57
+ | --- | --- | --- |
58
+ | Prompt section / runtime context | The assembled text (no single file) | "from the system prompt assembly" |
59
+ | Tool schema | The JSON declaration, split into description / parameter table / raw JSON | "from the session snapshot" |
60
+ | Skill | `SKILL.md` body when resolvable, otherwise the exact catalog line that is injected | "file" or "skill catalog entry" |
61
+ | Workspace rule | The real `AGENTS.md` / `CLAUDE.md` content and path | "from a file on disk" |
62
+
63
+ The drawer shows line numbers (toggleable), in-content search with match highlighting and a
64
+ per-line match summary, copy full text / copy path, a truncation notice at the 256 KB cap (32 KB
65
+ for the model tool), and closes on Esc with focus restored. It renders plain text; nothing is
66
+ re-interpreted as HTML. A slow read returns `timeout` after 2 seconds instead of a half result.
67
+
68
+ ## 5. Health checks
69
+
70
+ | Code | Fires when | Action |
71
+ | --- | --- | --- |
72
+ | `heavy-suite` | one suite is ≥25% of the first turn or ≥30k tokens | turn that suite off |
73
+ | `budget-gap` | the projection is above the saved budget | open the budget / drop the suggested suite |
74
+ | `catalog-truncated` | skill descriptions are cut at the catalog line length | read the affected skill |
75
+ | `locked-items` | items that cannot be switched off are ≥10% | jump to the manage list |
76
+ | `unknown-window` | no measurement yet, so occupancy is unknowable | — |
77
+ | `no-policy` | nothing has been switched off in this workspace | open settings |
78
+ | `empty-catalog` | the skill catalog is complete and empty | open settings |
79
+
80
+ Checks are a pure function of one snapshot (two refreshes cannot disagree). Up to six findings are
81
+ shown with a "more" line. Two contract codes, `duplicate-skill` and `tool-name-collision`, are
82
+ never emitted: this host build resolves duplicate names before the plugin can observe them, and
83
+ inventing a finding would be a lie.
84
+
85
+ ## 6. The insights tab
86
+
87
+ - **Trend** — one stacked bar per session, split by the five channels; 7 days / 30 days / all;
88
+ hover for values, click to pin, Esc to unpin, ←/→ by keyboard. Above 40 points the bars merge
89
+ into overview buckets so a long history does not become hairlines. Rows without a channel split
90
+ are striped, not zeroed. The durable-log backfill runs in the background (one pass per minute,
91
+ ≤8 sessions) so opening the tab never waits on it; a response may carry `backfilling: true` while
92
+ a pass is running, and the panel notes that older sessions are still being filled in.
93
+ - **Aggregate band** — sessions measured (shown as measured / known), average, peak, cumulative
94
+ saved.
95
+ - **Session cards** — search by id/title/directory; sort by recent / heaviest / most saved; the
96
+ current session is marked; a card opens that session in the manage list or its content.
97
+ - **Cross-session composition** — the five-channel ring averaged over sessions that have a split.
98
+ - **Heaviest suites** — the current session's suites by size, with the policy-removed part drawn
99
+ lighter.
100
+ - **Event timeline** — policy saves, presets, budget edits, imports, undos, compactions and prunes
101
+ for this session (`events.json`, capped at 300, up to 60 shown).
102
+ - **Coverage footnote** — recorded N of M sessions; the trend only contains what this plugin
103
+ measured plus a bounded log backfill.
104
+
105
+ ## 7. What a policy does, and when
106
+
107
+ A policy is one JSON file: per channel, `all`, `only [names]` or `except [names]`, plus an optional
108
+ persona prefix/suffix and a token budget.
109
+
110
+ It is applied exactly once, at `agent/created` with `source: startup|clear`. A session that already
111
+ exists is never rewritten mid-flight, so:
112
+
113
+ - the panel says whether *this* session was affected;
114
+ - "after policy" numbers are a projection for the next new session;
115
+ - undo restores the previous policy file, but still cannot retroactively change a live session.
116
+
117
+ ## 8. Suites
118
+
119
+ Items cluster by name: `mcp__<server>__<tool>` is one suite per MCP server; non-MCP tools cluster by
120
+ shared prefix; skills by provider; prompt sections and contexts by namespace, so an MCP server's
121
+ prompt section joins the same suite as its tools. One switch then means "the whole server", which is
122
+ the reason this plugin exists.
123
+
124
+ ## 9. Data and privacy
125
+
126
+ `policy.json` (switches and budget), `stats.json` (one measured row per session, with a channel
127
+ split from 2.0.0 on), `events.json` (append-only, 300 rows, policy metadata only — strings are
128
+ flattened and truncated to 200 characters, prompt text has no path in), and browser-local UI
129
+ preferences. No network requests, no telemetry, no uploads. Details: [FAQ](FAQ.md).
130
+
131
+ ## 10. What the model sees
132
+
133
+ The model-facing tool `context_injection` returns the same snapshot the panel renders, plus a short
134
+ "What you can do" block: which suite is the biggest win, whether this session predates the policy,
135
+ what compaction already removed, and the fact that the tool cannot flip switches. With
136
+ `{channel, name}` it returns one item's content instead (≤32 KB). It is read-only by design; every
137
+ write comes from a human click in the panel.
138
+
139
+ ## 11. Failure behaviour
140
+
141
+ - Host older than 0.2.2: banner, switches may not take effect, the numbers still render.
142
+ - Host HTTP contract older than v2: the new surfaces show a dismissible gate card (current /
143
+ minimum / dismiss) instead of silently disappearing; manage, settings and switches keep working.
144
+ - No measurement yet in this session: the window card says "window unknown" rather than guessing.
145
+ - A `compaction/*` event this build does not know: ignored (the receipt simply does not count it).
146
+ - `events.json` unreadable or absent: the timeline shows an empty state; policy saves still work.
147
+ - A content read that exceeds 2 seconds: the drawer shows the timeout and can retry.
148
+ - Policy file unreadable: the panel shows the error and keeps running with the all-on defaults;
149
+ `/inject` still prints the snapshot.
package/docs/DETAIL.zh.md CHANGED
@@ -1 +1,105 @@
1
- ![上下文注入:多条来源收敛成一次请求](preview.svg)
1
+ ![上下文注入:多条来源收束成一次首轮请求](preview.svg)
2
+
3
+ # 这个插件到底改了什么
4
+
5
+ 一个新会话在第一次请求到达模型之前,已经收到了一大堆东西:系统提示词段落、运行时上下文、以文本形式列出的技能目录、每个工具一个 JSON schema,还有 `AGENTS.md` 链。这些内容在对话里完全看不见,也没有一个统一的地方可以关掉。
6
+
7
+ 这页是五分钟版:插件量了什么、能关什么、关不掉什么,以及 2.0.0 新增的几块界面各显示什么。总览看 [README](../README.zh.md),实现细节看 [架构](ARCHITECTURE.md)。
8
+
9
+ ## 1. 三个数字,三个问题
10
+
11
+ | 数字 | 回答的问题 | 来源 |
12
+ | --- | --- | --- |
13
+ | 首轮注入(如 83.8k) | **下一个新会话**会被塞进多少东西 | 本插件自己装配:段落与上下文来自 `systemPrompt.assemble()`,技能来自 `skills.snapshot()`,工具 schema 来自 `tools.schemas()`,`AGENTS.md` 按默认链读取 |
14
+ | 上下文窗口占用(如 36%) | **当前这段对话**有多满 | 宿主自己的 `contextPressure` 投影 ÷ 模型窗口 |
15
+ | 内容原文(抽屉) | 某一行**到底写了什么** | 快照自己登记过的来源:装配文本、工具声明、技能文件/目录行、规则文件 |
16
+
17
+ 三者不可比,面板也从不拿一个去减另一个。第一个是插件能控制的部分,第二个决定宿主什么时候压缩,第三个只在你打开时才读。
18
+
19
+ 本插件的 token 是估算(ASCII ÷ 4,其他字符 ÷ 1.6)。占用率不是:`pressureTokens` 是 provider 上报的真实请求大小,窗口来自同一条请求记录。
20
+
21
+ ## 2. 三个页面,两个常驻入口
22
+
23
+ | 表面 | 用来干什么 |
24
+ | --- | --- |
25
+ | 管理 | 健康检查条、KPI、请求构成条,然后是套件清单与开关;每行可展开行内预览或打开原文 |
26
+ | 洞察 | 跨会话首轮趋势、聚合带、会话卡、跨会话构成、最重套件排行、本会话事件时间线、覆盖率脚注 |
27
+ | 设置 | 预设、四条通道总开关、自定义前言/后记、预算、导出导入、撤销历史、生效核对、插件偏好、版本与语言 |
28
+ | 输入框徽标 | 一行「首轮注入 + 窗口占用」,刻意低存在感;点 × 隐藏 |
29
+ | `/inject` 与 `context_injection` | 同样的数字的文本版,外加只读模型工具(可读单条原文) |
30
+
31
+ ## 3. 管理页显示什么
32
+
33
+ - **健康检查**:当前快照上的确定性检查(见第 5 节),每条都能点动作。
34
+ - **KPI**:首轮注入、带分母的上下文窗口占用、可关闭占比、当前预算;输入框徽标与它们是同一份数字。
35
+ - **请求构成条**:当前这次请求的系统/工具/消息构成,以及压缩回执,全部来自宿主投影。
36
+ - **管理清单**:五条通道,按套件聚类(一个 MCP server 一套),每条带「说明」列。组头有项目数、token、占比与三态开关;整组关掉后仍留在清单里(带「已关闭」标记与记住的体积),随时能开回来。条目可展开行内预览,「内容」按钮打开抽屉。
37
+
38
+ ## 4. 内容抽屉读什么
39
+
40
+ 只读快照自己登记过的来源——请求里不能指定任意路径:
41
+
42
+ | 行 | 内容 | 来源标注 |
43
+ | --- | --- | --- |
44
+ | 提示词段落 / 运行时上下文 | 装配出来的文本(没有单一文件) | 「来自系统提示词装配」 |
45
+ | 工具 schema | JSON 声明,拆成描述 / 参数表 / 原始 JSON 三视图 | 「来自会话快照」 |
46
+ | 技能 | 能定位就读 `SKILL.md` 正文,否则给目录里真正注入的那一行 | 「来自磁盘文件」或「技能目录条目」 |
47
+ | 工作区规则 | 真实的 `AGENTS.md` / `CLAUDE.md` 内容与路径 | 「来自磁盘文件」 |
48
+
49
+ 抽屉里有行号开关、内容内搜索(高亮 + 命中行摘要)、复制全文 / 复制路径、超过 256KB(模型工具 32KB)的截断提示、Esc 关闭、焦点回到打开它的那一行;全部按纯文本渲染,不会把内容当 HTML 解释。读取超过 2 秒就返回 `timeout`,不给半个结果。
50
+
51
+ ## 5. 健康检查
52
+
53
+ | code | 什么时候报 | 动作 |
54
+ | --- | --- | --- |
55
+ | `heavy-suite` | 某一套占首轮 ≥25% 或 ≥30k token | 关掉这一套 |
56
+ | `budget-gap` | 预测值超出已设预算 | 去设预算 / 关掉建议的那一套 |
57
+ | `catalog-truncated` | 技能描述被目录行长度截断 | 看那条技能的内容 |
58
+ | `locked-items` | 不可关条目占首轮 ≥10% | 去管理列表 |
59
+ | `unknown-window` | 还没有测量数据,占用率无从判断 | — |
60
+ | `no-policy` | 这个工作区从没动过策略 | 去设置 |
61
+ | `empty-catalog` | 技能目录是完整的空 | 去设置 |
62
+
63
+ 检查项是同一份快照的纯函数(两次刷新不会互相打架)。契约里另有两个 code(`duplicate-skill`、`tool-name-collision`)永远不会出现:这版宿主在插件能看到之前就把重名解析掉了,凭空报一条就是撒谎。
64
+
65
+ ## 6. 洞察页
66
+
67
+ - **趋势**:每个会话一根按五通道堆叠的柱子;近 7 天 / 近 30 天 / 全部;悬停看数值、点击钉住、Esc 取消、←/→ 切换。超过 40 个点合并成总览分组,避免柱宽被压成线;没有通道分解的行画斜纹,不补 0。历史日志回填在后台跑(每分钟一轮、每轮 ≤8 个会话),打开页面不等它;响应可能带 `backfilling: true`,面板会提示历史仍在补齐。
68
+ - **聚合带**:已测量会话(按「实测 / 全部」显示)、均值、峰值、累计可省。
69
+ - **会话卡**:按 id/标题/目录搜索;按最新 / 最重 / 可省最多排序;本会话有标记;点卡片跳到管理列表或直接看内容。
70
+ - **跨会话平均构成**:只统计有通道分解的会话,五通道构成环。
71
+ - **最重套件排行**:当前会话的套件体积,被策略关掉的部分画浅色。
72
+ - **事件时间线**:本会话的策略保存、预设、预算、导入、撤销、压缩、剪枝(`events.json`,上限 300 条,最多显示 60 条)。
73
+ - **覆盖率脚注**:已记录 N 个 / 本机共 M 个;趋势只包含本插件测过的与有限日志回填的。
74
+
75
+ ## 7. 策略什么时候生效
76
+
77
+ 策略就是一个 JSON:每个通道 `all`、`only [名单]` 或 `except [名单]`,外加可选的人设前言/后记与 token 预算。
78
+
79
+ 它只在 `agent/created` 且 `source` 为 `startup` / `clear` 时应用一次。已经在跑的会话永远不会被中途改写,所以:
80
+
81
+ - 面板会标明「本会话是否按策略处理」;
82
+ - 「策略后」的数字是**下一个新会话**的预估;
83
+ - 撤销恢复的是策略文件,同样不会追溯改掉活着的会话。
84
+
85
+ ## 8. 套件
86
+
87
+ 条目按名字聚类:`mcp__<server>__<tool>` 一个 MCP server 一套;非 MCP 工具按共同前缀;技能按 provider;段落与上下文按命名空间——所以某个 MCP server 的说明段落会和它的工具并进同一套。于是一个开关就是「整个 server」,这正是这插件存在的理由。
88
+
89
+ ## 9. 数据与隐私
90
+
91
+ `policy.json`(开关与预算)、`stats.json`(每会话一行测量,2.0.0 起含通道分解)、`events.json`(追加式事件流,300 条上限,只存策略元数据——字符串被拍平并截到 200 字符,会话正文没有入口能进来)、以及浏览器本地的界面偏好。不联网、不遥测、不上传。细节见[常见问题](FAQ.md)。
92
+
93
+ ## 10. 模型看到什么
94
+
95
+ 模型侧工具 `context_injection` 返回和面板完全相同的快照,外加一段「能做什么」:哪一套最划算、本会话是否在策略之前创建、宿主已经压缩掉多少、以及这个工具**不能**自己拨开关。带 `{channel, name}` 时改为返回单条原文(≤32KB)。按设计只读,所有写操作都来自人在面板里点。
96
+
97
+ ## 11. 出问题时会怎样
98
+
99
+ - 宿主低于 0.2.2:顶部提示,开关可能不生效,数字照常显示。
100
+ - 宿主 HTTP 契约低于 v2:新表面显示可关掉的 gate 卡(当前版本 / 最低要求 / 知道了),而不是静默消失;管理、设置和开关照常工作。
101
+ - 本会话还没有测量数据:窗口显示「未知」,不猜一个数。
102
+ - 收到本版本还不认识的 `compaction/*` 事件:忽略(回执只是不统计它)。
103
+ - `events.json` 读不到或不存在:时间线显示空态,策略保存不受影响。
104
+ - 内容读取超过 2 秒:抽屉显示超时并可重试。
105
+ - 策略文件读不了:面板显示错误,按全开继续跑;`/inject` 仍能打印快照。
package/docs/FAQ.md CHANGED
@@ -5,12 +5,54 @@
5
5
  先看面板顶部的「首轮注入」是不是真的降了。三个常见原因:
6
6
 
7
7
  1. 你关的是**旧会话**看到的数;策略只对之后新建的会话生效。
8
- 2. 大头是 `AGENTS.md` 或工具 schema,而你没关到对应通道。
8
+ 2. 大头是 `AGENTS.md` 或工具 schema,而你没关到对应通道(打开那一行的内容抽屉能确认它到底有多大)。
9
9
  3. 面板的 token 是估算(ASCII ÷ 4,其他 ÷ 1.6);真实占用看输入框下方统计行。
10
10
 
11
11
  ## 为什么 `AGENTS.md` 不能关?
12
12
 
13
- 它由 `dsh-agent-instructions` 在 `agent/pre-step` 直接注入成一条 user 消息,0.2.2 没有公开的抑制入口。插件选择只读展示:告诉你哪些文件真的在加载路径上、哪些超了预算、哪些在 `~/AGENTS.md` 这种不会被读的位置。改名/删除是旧版的做法,已废弃——它会在多目录会话里改错文件。
13
+ 它由 `dsh-agent-instructions` 在 `agent/pre-step` 直接注入成一条 user 消息,0.2.2 没有公开的抑制入口。插件选择只读展示:告诉你哪些文件真的在加载路径上、哪些超了预算、哪些在 `~/AGENTS.md` 这种不会被读的位置,并且**内容抽屉里能读到真正被注入的那份文本**。改名/删除是旧版的做法,已废弃——它会在多目录会话里改错文件。
14
+
15
+ ## 内容抽屉会读什么?会不会外传?
16
+
17
+ 只读三类来源,全部来自快照自己登记过的路径:
18
+
19
+ - 技能注册路径上的 `SKILL.md`(读不到时退回目录里真正注入的那一行,并注明是目录行);
20
+ - 工作区规则探测到的 `AGENTS.md` / `CLAUDE.md` 文件;
21
+ - 系统提示词段落、运行时上下文、工具声明:这些本来就是装配结果或内存里的对象,不读盘。
22
+
23
+ 请求里**不能指定任意路径**,接口只接受「通道 + 条目 id」。单次读取有 2 秒预算、256KB 上限(模型工具单条 32KB),UTF-8 安全截断。读到的东西只在这次请求内返回给当前页面,**不写文件、不落盘、不联网、不上传**;关掉抽屉就没了。
24
+
25
+ ## 趋势里为什么有「未知」的数据(斜纹)?
26
+
27
+ 趋势只合并两种诚实来源:本插件自己写下的 `stats.json` 行(实测),和从历史会话日志里定价出来的行(日志)。日志行只测得到首轮总量,没有五条通道的分解,所以 `channels` 报 `null`、柱子画成斜纹——不补 0,因为 0 是一个我们没测过的断言。历史更早的实测行同理(通道分解是 2.0.0 才开始写的)。
28
+
29
+ 「已记录 N 个会话 / 本机共 M 个」是覆盖率:没测过、也没有回填到的会话不会画进趋势。回填在**后台**跑(每分钟最多一轮、每轮最多 8 个会话、单轮预算 6 秒),读取接口立即返回已有数据并带 `backfilling: true`,所以趋势会随着后台补齐慢慢变多,但打开页面不会被回填卡住。
30
+
31
+ ## 事件(events)存在哪?会记录对话内容吗?
32
+
33
+ `$DSH_HOME/injection-manager/events.json`,追加式,最多 300 条,原子写(临时文件 + rename),重复的宿主事件靠去重键只记一次。记录的是**策略与元数据**:哪个套件被关、预设切换、预算调整、导入、撤销、压缩/剪枝、新会话建立,以及每次的 net token 变化。
34
+
35
+ 不记对话正文:`params` 只接受原始值(字符串截到 200 字符、最多 24 项,嵌套对象直接丢弃),会话文本没有入口能进这个文件。重启不丢,删掉文件即清空;上限到了自动丢最旧的。
36
+
37
+ ## 健康检查说「没有发现问题」,但我明明觉得很大?
38
+
39
+ 健康检查是确定性的 7 类 code:重套件(单套 ≥25% 或 ≥30k)、预算缺口、描述截断、不可关项占比、窗口未知、从没保存过策略、空技能目录。它只报"能行动"的问题,不按直觉打分。
40
+
41
+ 另外两个契约里的 code(`duplicate-skill`、`tool-name-collision`)**永远不会出现**:这版宿主在插件能看到之前就把重名解析掉了,凭空报一条就是撒谎。枚举保留着,等宿主能观察时再加。
42
+
43
+ 检查项是同一份快照的纯函数:同一份数据刷新两次,结果逐字节一致(唯一的时间值是快照的生成时间)。
44
+
45
+ ## 新面板为什么显示「需要 v2 宿主」?
46
+
47
+ 面板通过 `/summary` 的 `apiVersion` 判断宿主能力。宿主还是 v1 时,新版洞察、内容透视、健康检查这些需要新接口的能力无法工作,所以显示一张可关掉的 gate 卡(当前版本 / 最低要求 / 知道了),而不是让 tab 静默消失。升级插件后自动出现;管理、设置和所有开关不受影响。
48
+
49
+ ## 洞察页的会话卡为什么比宿主的会话列表少?
50
+
51
+ 因为趋势和会话卡只画「本插件测过或从日志定价过」的会话,而不是宿主知道的所有会话。这是有意的:没测过的会话没有任何数字可画,画一个空列会让人以为它真的没有注入。页脚会写明「已记录 N 个 / 本机共 M 个」。
52
+
53
+ ## 我关掉一套之后,洞察里的历史点会变吗?
54
+
55
+ 不会。洞察里的每个点描述的是**那一次测量时**的首轮注入;策略只影响之后新建的会话(以及之后的新测量)。所以你会在趋势上看到关闭动作对应的下降台阶,而不是整条线被重算——这正是这个页面存在的意义。
14
56
 
15
57
  ## 关掉一个工具,模型还能调用它吗?
16
58
 
@@ -35,20 +77,20 @@
35
77
 
36
78
  ## 撤销能退多远?
37
79
 
38
- 内存里保留最近 20 次写策略前的状态,重启清空。撤销本身也会写文件,但不进栈。
80
+ 内存里保留最近 20 次写策略前的状态,重启清空。撤销本身也会写文件(并记一条事件),但不进栈。
39
81
 
40
82
  ## 应用预算会叠加当前的手动开关吗?
41
83
 
42
- 不会。应用预算会按目标 token 重算四条通道,把当前单个条目的关闭/开启**替换掉**。所以面板在检测到已有手动关闭项时会先提示「当前有 N 项被手动关闭;应用建议会按预算重算,并覆盖这些选择。」切换预设(全开/极简)同理,策略页也会给同样的提示。如果只想保留手动结果,别点「应用这套建议」,直接调大预算即可。
84
+ 不会。应用预算会按目标 token 重算四条通道,把当前单个条目的关闭/开启**替换掉**。所以面板在检测到已有手动关闭项时会先提示「当前有 N 项被手动关闭;应用建议会按预算重算,并覆盖这些选择。」切换预设(全开/极简)同理。如果只想保留手动结果,别点「应用这套建议」,直接调大预算即可。
43
85
 
44
86
  ## 数据存在哪?会上传吗?
45
87
 
46
- `$DSH_HOME/injection-manager/policy.json`,加上插件行的 `config`。没有网络请求,没有遥测。
88
+ 四个地方:`policy.json`(开关与预算)、`stats.json`(每会话测量与通道分解)、`events.json`(事件流)、插件行的 `config`;另有浏览器 localStorage 存两个纯界面偏好。没有网络请求,没有遥测,不上传策略或会话内容。
47
89
 
48
90
  ## 和 `dsh-context` 是什么关系?
49
91
 
50
- `dsh-context` 看**历史**:每个请求的组成、演进、压缩事件、多 Agent。这个插件管**下一次注入**:首轮到底塞了什么、哪些能关、预算多少。两者可以同时装,互不修改对方。
92
+ `dsh-context` 看**历史**:每个请求的组成、演进、压缩事件、多 Agent、文件与命令。这个插件管**下一次注入**:首轮到底塞了什么、哪些能关、关掉后什么代价。两者可以同时装,互不修改对方;我们是控制面,它是只读回放。
51
93
 
52
94
  ## 卸载后会怎样?
53
95
 
54
- 策略文件留在 `$DSH_HOME/injection-manager/`,不会自动删除;已生效的会话在插件卸载时解除注册(注册都挂在插件/agent 作用域上)。想彻底清掉就删这个目录。
96
+ 策略、统计、事件文件留在 `$DSH_HOME/injection-manager/`,不会自动删除;已生效的会话在插件卸载时解除注册(注册都挂在插件/agent 作用域上)。想彻底清掉就删这个目录。