dsh-knit 0.14.0 → 0.15.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/CHANGELOG.md CHANGED
@@ -3,6 +3,58 @@
3
3
  本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
4
4
  版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
5
5
 
6
+ ## [0.15.0] - 2026-09-30
7
+
8
+ **从「构建一份当前任务上下文」再往前一步:让上下文能回答「它到底有没有被用上」。**
9
+ 排序(BM25)一行没改,Context Pack 的装配规则一行没改,**没有模型、没有联网、没有长期记忆** ——
10
+ 这一版加的是**一层可核验的使用反馈**:把 agent 真实读过哪些文件(会话日志里的
11
+ `tool/call(name="read")` 与按 `callId` 配对的 `tool/result`)跟「**读发生那一刻**生效的那份
12
+ Context Pack」对起来,得到五个计数:**Primary follow-through / First read tier /
13
+ Supporting coverage / Outside-context / Delta churn**。**只报事实**:没有分数、没有百分比、
14
+ 没有评分条、没有置信度。
15
+
16
+ ⚠️ **两条硬边界(别越)**:
17
+
18
+ 1. **默认关。** 只有人显式打开(面板头部「使用情况」开关 → 请求带 `usage=1`,或
19
+ `knit_docs` 传 `audit:true`)才开始记账;没打开时**不读一个事件、不攒一条数据**。
20
+ 理由是这笔账有代价(每次轮询都要读一遍会话事件),不该由 Knit 替用户决定。
21
+ 2. **不重复 DSH Trajectory。** 证据的**唯一来源**是会话里**已经存在**的 `tool/call` /
22
+ `tool/result` 事件(`session.snapshotEvents()`,沿用既有拉取式架构,用 `seq` 做幂等游标)——
23
+ **没有新的事件总线、没有 Runtime Trace、没有 Event Store**;数据只在内核内存里,
24
+ 重启即失(不落盘、不进 `localStorage`)。
25
+
26
+ ### 加了什么
27
+
28
+ | 新增 | 说明 |
29
+ |---|---|
30
+ | **`src/host/feedback.js`** | Context Snapshot / Context Delta / Usage matching。纯逻辑、只 import `node:path`。`snapshotOf()` 把一份包压成 `{seq, at, topic, task, total, items:[{rel,tier,rank}], sig}`;`diffContext()` 给「进 / 出 / 换层」;`normalizeReadEvidence()` 把真实事件流化成「哪一刻读了哪篇」(⚠️ `tool/call` 的 `arguments` 是 JSON **字符串**,必须 `JSON.parse`;`message.isError === true` 的读**不记账**;工作区根之外的路径丢掉);`ingestEvents()` / `noteSnapshot()` / `usageFor()`。会话与读都有上限(`MAX_SESSIONS 24` / `MAX_READS_PER_SESSION 200` / `MAX_SNAPSHOTS_PER_SESSION 2` / `MAX_DELTAS_PER_SESSION 20` / `MAX_PENDING_CALLS 64`),满员按 **LRU** 淘汰最久没碰的会话 |
31
+ | **读落在哪一层,看的是「读发生那一刻」的包** | 每篇读按 `firstReadSeq` 找 `seq ≤` 它的**最新一份快照**。少了这一步,一次话题切换会把之前所有读重新贴上「包外」的标签,指标全是噪声 |
32
+ | **`/knit/api/recent?usage=1`** | 开闸信号:**第一次带它就等于对本次会话说「开始记账」**,此后不带参数也回传 `usage`。`/api/context` 只推进快照、**从不激活**。顺序是契约:`usage` 先算(它报告的是**上一份**包),快照后记 |
33
+ | **`knit_docs` 的 `audit` 参数(默认 `false`)** | `audit:true` 时在工具结果末尾追加一行 `Usage since the last pack: …`(报告**上一份**包),并把这次装配记进快照。不传 `audit` 的一次普通调用**一个记账方法都不碰**(有测试钉住) |
34
+ | **面板头部的「使用情况」开关(默认关)** | 打开后列表上方多一行弱化文字:`先看的「x.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次`。**没有分数 / 百分比 / 进度条 / 品牌色**,风格与「相关性排序」那行同档 |
35
+ | **`tools/context-feedback-eval.mjs`** | 拿真实会话日志(`~/.dsh/sessions/<工作区>/<会话>/session.v4.jsonl.zstd`)**离线回放**;`--control` 时一份包都不交,做对照组。把「包外」拆成 **`missed`**(Knit 索引里有、却没进包 —— 真漏)与 **`outOfScope`**(压根不在索引里,例如 `.js`):不拆开的话 `outside` 恒高,读起来像「Context Pack 没用」,其实是**量错了东西** |
36
+ | **`test/feedback.test.mjs` · `test/context-delta.test.mjs` · `test/context-feedback-eval.test.mjs`** | 17 + 16 + 7 条:路径归一化的八种输入 / 配对与游标幂等 / 上限与降级不抛 / Delta 四类 / 审计开关 / **Control(不交包 ⇒ 读全在包外)vs Treatment(交包 ⇒ `firstReadTier === 'primary'`)的确定性对照** / 坏行不废整批 |
37
+
38
+ ### 真机读数(本机 `08_Knit`,会话 `session-09a33302`,**只量事实、不下结论**)
39
+
40
+ - **Treatment**(交包):**392** 份包 · Primary follow-through **YES** · Supporting coverage **1.00** ·
41
+ 包外 **25/32 篇(共 392 次)**,其中 Knit 看得到的 11 篇里漏了 **35** 次、真心漏的只有 4 篇
42
+ (`knit/CHANGELOG.md` · `knit/README.md` · `03_发布/验收-v0.14-重启后待执行.md` · `README.md`)·
43
+ Delta churn:**换过 66 次 / 进 177 / 出 177 / 换层 271 / 任务变了 14**。
44
+ - **Control**(`--control`,不交包):**0** 份包 · 包外 **32/32** · `missed` 11 篇(140 次)· churn 0 ·
45
+ 自检退出码 0(**量尺没坏**)。
46
+ - ⇒ 可复述的只有一句:**agent 读的东西绝大多数是代码文件** —— 32 篇里 21 篇根本不在 Knit 的索引内
47
+ (`.js` / `.json`)。这是**量尺的读数**,不能读成「Context Pack 没用」,也不能读成「有用」。
48
+
49
+ **测试:`395 → 447 → 450`**(+33 `feedback`/`context-delta`、+7 `context-feedback-eval`、
50
+ +7 `tool` 的 audit 通道、+5 `host-http` 的真实回环 HTTP、+3 `client` 的「使用情况」;
51
+ `i18n` 与 `client` 里几条旧断言随「头部多了一个按钮」同步)。`test/context-feedback-eval.test.mjs`
52
+ 与另两个新文件都**手写进了 `package.json` 的 `scripts.test`**(测试文件现共 19 个)。
53
+
54
+ ⚠️ 这一版**宿主侧**(`src/host/*`)改了,要**重启 DSH** 才生效(`curl -s
55
+ "http://127.0.0.1:3080/knit/api/raw?rel=nope.png"`:空 body 的 404 = 旧代码;
56
+ `{"ok":false,"code":"knit/not-found"}` = 新代码在跑);前端那个开关只需 `Cmd + Shift + R`。
57
+
6
58
  ## [0.14.0] - 2026-09-29
7
59
 
8
60
  **从「按当前对话给文档排序」升级成「按对话构建当前任务最需要的项目上下文」。**
package/README.en.md CHANGED
@@ -7,18 +7,22 @@
7
7
 
8
8
  ![Screenshot from a real machine: the Knit sidebar ranking the workspace documents by relevance, with a Markdown preview expanded in place and the references bar below the preview header](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png)
9
9
 
10
- *Screenshot from a real machine, not a mock-up: a workspace with 36 documents — the list, an inline
10
+ *Screenshot from a real machine, not a mock-up: a workspace with 51 documents — the list, an inline
11
11
  preview, and the references bar.*
12
12
  *The references bar is new in v0.12: expand it to see which documents reference this one, and click
13
13
  one to jump straight there.*
14
14
  *The top line follows whatever you're talking about; when there isn't enough conversation yet it
15
15
  falls back to newest-first and states its basis.*
16
+ *Since v0.14 the list is always one column: the rank number sits in its own column on the far left
17
+ (vertically centred on the title's first line), then Primary dot + title + relative time (time on the
18
+ right), then the summary. **The path lives in the preview header's breadcrumb only** — rows no longer repeat it.*
16
19
 
17
20
  ![Order follows the conversation: send a message and the sidebar re-ranks the document list by it](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/demo-reorder.gif)
18
21
 
19
- *Order follows the conversation — same workspace, same session: ask "how is BM25 weighted for the
20
- ranking?" and the sorting docs move to the top; then ask "how do I check plugin-market listings and
21
- download counts?" and the market-research docs take over.*
22
+ *Order follows the conversation — same workspace, in a freshly opened session: before you have said
23
+ anything, the top line says so ("not enough conversation yet — sorted by time") and the list runs
24
+ newest-first; ask "how is BM25 weighted for the ranking?" and the ranking docs take over, with the
25
+ rank numbers and the primary / supporting / related tiers appearing alongside them.*
22
26
  *⚠️ The panel polls **every 5 seconds**, so the re-rank lands **0–5 s** after the message rather than
23
27
  instantly, and the GIF runs faster than real time.*
24
28
 
@@ -321,24 +325,62 @@ feature request.
321
325
 
322
326
  ### The other two views
323
327
 
324
- ![Screenshot of the Images & video tab: a square thumbnail grid, six columns at this panel width, with a video thumbnail carrying a play glyph and a duration badge](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
328
+ ![Screenshot of the Images & video tab: a square thumbnail grid, six columns at this panel width](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
325
329
 
326
330
  *Images & video: square thumbnails, with the **column count following the panel width continuously** —
327
- six columns at this width, cells about 112px. Videos show their first frame as a poster with a play
328
- glyph and a duration badge. These are the workspace's real image and SVG files; this particular
329
- workspace happens to hold several screenshots and two icon files.*
331
+ six columns at this width, cells about 112px. These are the workspace's real image and SVG files; this
332
+ particular workspace happens to hold several screenshots and two single-colour SVG icons (the two solid
333
+ black squares are those icons). Videos get their first frame as a poster with a play glyph and a
334
+ duration badge — this workspace simply has no video, so none shows here.*
330
335
 
331
- ![Screenshot of the All tab: documents above, media with a count only below](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
336
+ ![Screenshot of the All tab: the documents section showing the first 4 with a "View all →" link, and no media section](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
332
337
 
333
- *All: documents on top (max 4, with a "View all →" link when truncated) and images & video below
334
- (**never truncated**, count only). All four fields — title, time, summary, path — were present.*
338
+ *All: the documents section shows at most 4, with a "View all →" link when truncated (here "4 / 40").*
335
339
 
336
- ⚠️ **This screenshot is from v0.13**, when documents could still lay out in two columns *and* rows still
337
- carried the path. **Since v0.14 the list is always one column** (the number now sits in its own column
338
- on the far left, with Primary dot + relative time, then the title, stacked to its right), and **the path
339
- is no longer shown in the list** (the preview header's breadcrumb always shows the full path, so the
340
- duplicate was dropped).
341
- The screenshot has not been retaken yet.
340
+ ⚠️ **There is no media section in this screenshot, and that is not a layout accident** — for the All
341
+ view the host fetches a **40-item window**. This workspace has 51 documents plus 8 media files, and the
342
+ media rank 50th–58th by relevance, so they fall outside the window; the client's
343
+ `visibleDocs.filter(isMedia)` is then empty and the media section is not rendered at all. **Any
344
+ workspace with 40 or more documents behaves this way** — a known defect, with reproduction and the fix
345
+ recorded in [`docs/README.md`](docs/README.md).*
346
+
347
+ ---
348
+
349
+ ## Did it actually get used? (v0.15)
350
+
351
+ Knit orders "what to read first right now" — but **whether that order was right could only be felt,
352
+ never checked**. v0.15 adds a layer of **verifiable usage feedback**: the files the agent really read,
353
+ matched against the context pack that was in effect **at the moment of the read**.
354
+
355
+ **Off by default.** There is a "Usage" toggle in the panel head; turning it on adds one muted line
356
+ above the list:
357
+
358
+ ```
359
+ primary read (docs/xxx.md) · supporting 1/2 · 7 reads · 2 outside the pack · context changed 2×
360
+ ```
361
+
362
+ It reports **facts only**: was the primary doc read, how many reads happened, how many fell outside
363
+ the pack, how often the context changed. **No score, no percentage, no progress bar** — these numbers
364
+ are counted, not estimated.
365
+
366
+ Three boundaries:
367
+
368
+ - **Off by default**: while it is off, Knit reads **no events and stores nothing**. This accounting
369
+ has a cost (every poll would walk the session's events), and that is the user's call, not ours.
370
+ - **No duplicate of the DSH trajectory**: the only evidence source is the `tool/call` / `tool/result`
371
+ events the session **already has** (successful `read`s). **No new event bus, no runtime trace,
372
+ no event store.**
373
+ - **Nothing is persisted**: the numbers live in kernel memory only and are gone after a DSH restart —
374
+ do not treat them as long-term statistics.
375
+
376
+ Agents get the same thing optionally: `knit_docs` accepts `audit: true` (default `false`), which
377
+ appends one line, `Usage since the last pack: …` (a report on the **previous** pack).
378
+
379
+ To check offline: `node tools/context-feedback-eval.mjs` replays the latest real session log;
380
+ `--control` is the "deliver no pack at all" arm. ⚠️ It splits "outside the pack" in two —
381
+ **in Knit's index but not in the pack** (a real miss) versus **not in the index at all** (`.js` /
382
+ `.json`, which Knit never indexes). Without that split the outside ratio stays high and reads like
383
+ "the Context Pack is useless", when in fact **the wrong thing was measured**.
342
384
 
343
385
  ---
344
386
 
@@ -348,6 +390,8 @@ The screenshot has not been retaken yet.
348
390
  outside is rejected); for media it reads metadata only, never the pixels
349
391
  - Reads only **the current session's** conversation events (used for ranking)
350
392
  - The `knit_docs` tool is **read-only**: it writes no files and persists no index
393
+ - v0.15 usage accounting is **off by default**: when enabled it reads only the **current session's
394
+ existing** tool events (successful `read`s) — still no file writes, no persisted counters, gone on restart
351
395
  - **Makes no outbound network requests**: the client's `fetch` calls all point to
352
396
  the plugin's own same-origin routes
353
397
  - **No install-time scripts** (no `install` / `postinstall`)
package/README.md CHANGED
@@ -7,14 +7,17 @@
7
7
 
8
8
  ![Knit 面板真机截图:右侧栏按相关性列出工作区文档,就地展开 Markdown 预览,预览头下方是引用条](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png)
9
9
 
10
- *真机截图(不是原型):一个含 36 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
10
+ *真机截图(不是原型):一个含 51 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
11
11
  *引用条是 v0.12 加的:展开就能看到「这篇被谁引用」,点一项直接跳过去。*
12
12
  *顶行会跟着你正在聊什么变;对话内容还不足时它退回按时间排,并如实说明依据。*
13
+ *v0.14 起文档列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
14
+ *Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头的面包屑里**,列表行不再重复。*
13
15
 
14
16
  ![排序跟着对话走:发一句话,右侧栏的文档列表按这句话重排](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/demo-reorder.gif)
15
17
 
16
- *排序跟着对话走(同一个工作区、同一个会话):先问「排序算法用的 BM25 是怎么加权的?」,*
17
- *顶上换成排序那几篇;再问「插件市场收录和下载量怎么查?」,顶上又换成市场调研那几篇。*
18
+ *排序跟着对话走(同一个工作区、刚新开一个会话):还没聊什么时,顶行如实写着「对话内容还不足,暂按最新排序」,*
19
+ *列表按时间排;问一句「排序算法用的 BM25 是怎么加权的?」,顶上立刻换成排序那几篇 ——*
20
+ *序号与「主要上下文 / 辅助上下文 / 相关上下文」三层随之一起出现。*
18
21
  *⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
19
22
 
20
23
  扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
@@ -184,21 +187,20 @@ dsh plugin --profile web add dsh-knit
184
187
 
185
188
  ### 另外两档长什么样
186
189
 
187
- ![图片与视频档真机截图:方形缩略图网格,这一屏 6 列,其中一个视频缩略图带播放三角与时长角标](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
190
+ ![图片与视频档真机截图:方形缩略图网格,这一屏 6 列](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
188
191
 
189
192
  *图片与视频:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
190
- *视频取首帧当海报,中央叠播放三角、右下角叠时长。列出的就是工作区里真实的图片与 SVG 文件 ——*
191
- *这个工作区里正好有几张截图和两个图标,所以看起来像一屏文件缩略图。*
193
+ *列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图和两个单色 SVG 图标,*
194
+ *所以看起来像一屏文件缩略图(那两个纯黑方块就是那两个图标本身)。视频会取首帧当海报、*
195
+ *中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
192
196
 
193
- ![全部档真机截图:上区文档列表,下区图片与视频只给计数](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
197
+ ![全部档真机截图:文档区只给前 4 条与「查看全部 →」,媒体区没有出现](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
194
198
 
195
- *全部:上区文档(最多 4 条,超出时右侧给「查看全部 →」)、下区图片与视频(**不截断**,只给计数)。*
196
- 标题 / 时间 / 摘要 / 路径**四个字段一个不少**。
197
- ⚠️ **这张图是 v0.13 时代的**:那时候文档还能排 2 列,列表行里也还有路径,标题与时间各占一行;
198
- **v0.14 起文档列表永远单列**(每篇最左边独立一列是序号,与标题第一行垂直居中;右边第一行=
199
- Primary 点 + 标题 + 相对时间,**时间靠右**;摘要再往下),
200
- 而且**路径不再出现在列表行里**(预览头的面包屑始终显示完整路径,重复的那份删掉了),
201
- 截图尚未重拍。
199
+ *全部:文档区最多 4 条,超出时右侧给「查看全部 →」(这一屏是「4 / 40」)。*
200
+ *⚠️ **这一屏没有媒体区,而且不是排版问题** —— 宿主为「全部」档取的是 **40 条窗口**:这个工作区*
201
+ *51 篇文档 + 8 个媒体,媒体按相关性排在第 50–58 位、整段被挤出窗口,于是客户端的*
202
+ *`visibleDocs.filter(isMedia)` 恒为空、媒体区整个不渲染。**文档数 ≥ 40 的工作区都会这样**,*
203
+ *这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
202
204
 
203
205
  ---
204
206
 
@@ -311,11 +313,45 @@ Knit 一装上就有整个项目的历史文档可用。
311
313
 
312
314
  ---
313
315
 
316
+ ## 它有没有被用上(v0.15)
317
+
318
+ Knit 会排出「现在最该先看的几篇」,但**排得对不对,过去只能靠感觉**。
319
+ v0.15 加了一层**可核验的使用反馈**:把 agent 真实读过的文件,跟**读发生那一刻**生效的那份上下文对起来。
320
+
321
+ **默认关。** 面板头部有一个「使用情况」开关,打开之后列表上方会多一行字:
322
+
323
+ ```
324
+ 先看的「docs/xxx.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次
325
+ ```
326
+
327
+ 它只报**事实**:先看的那篇被读了没有、读了几次、多少篇落在包外、上下文换过几回。
328
+ **没有分数、没有百分比、没有进度条** —— 这些数字不是估算出来的,是数出来的。
329
+
330
+ 三条边界:
331
+
332
+ - **默认关闭**:不打开就**不读一个事件、不攒一条数据**。这笔账是有代价的
333
+ (每次轮询都要读一遍会话事件),该由你决定要不要付。
334
+ - **不重复 DSH 的轨迹**:证据只有一个来源 —— 会话里**已经存在**的 `tool/call` / `tool/result`
335
+ 事件(成功的 `read`)。**没有新的事件总线、没有 Runtime Trace、也没有 Event Store。**
336
+ - **不落盘**:数据只在宿主内存里,重启 DSH 就没了,**别把它当长期统计**。
337
+
338
+ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工具结果末尾会多一行
339
+ `Usage since the last pack: …`(报的是**上一份**包)。
340
+
341
+ 想离线核对:`node tools/context-feedback-eval.mjs` 回放最近一份真实会话日志,
342
+ `--control` 是「一份包都不交」的对照组。⚠️ 它把「包外」拆成两半 ——
343
+ **Knit 索引里有、却没进包**(真漏)与**压根不在索引里**(`.js` / `.json`,Knit 本来就不索引这些);
344
+ 不拆开的话包外比例恒高,读起来像「Context Pack 没用」,其实是**量错了东西**。
345
+
346
+ ---
347
+
314
348
  ## 它读什么,不读什么
315
349
 
316
350
  - 扫描**当前会话工作区内**的 `.md`、图片与视频(路径越出工作区一律拒绝);媒体只取元信息,不读画面内容
317
351
  - 只读**当前会话**的对话事件(用来排序)
318
352
  - `knit_docs` 工具**只读**:不写任何文件、不落盘任何索引
353
+ - v0.15 的「使用情况」**默认关**:打开后也只读**当前会话已有**的工具事件(成功的 `read`),
354
+ 同样不写任何文件、不落盘任何计数,重启即失
319
355
  - **不发起任何对外网络请求**:客户端的 `fetch` 都指向插件自己的同源路由
320
356
  - **没有安装期脚本**(无 `install` / `postinstall`)
321
357
  - **零依赖** —— 装完不需要构建授权,也没有构建步骤
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-knit",
3
- "version": "0.14.0",
3
+ "version": "0.15.0",
4
4
  "type": "module",
5
5
  "description": "Find the doc your agent just wrote. Lists the DSH workspace's Markdown, images and video in the sidebar, ranked by relevance to the current conversation, with inline preview — and hands the same ranking to the agent as a tool, returning the passage that matched in each document. Zero model calls, zero network.",
6
6
  "main": "./src/host/index.js",
@@ -15,6 +15,7 @@
15
15
  "src",
16
16
  "test",
17
17
  "tools/json-schema-subset.mjs",
18
+ "tools/context-feedback-eval.mjs",
18
19
  "cordis.patch.yml",
19
20
  "CHANGELOG.md",
20
21
  "README.md",
@@ -22,7 +23,7 @@
22
23
  "LICENSE"
23
24
  ],
24
25
  "scripts": {
25
- "test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs"
26
+ "test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs"
26
27
  },
27
28
  "dsh": {
28
29
  "bundle": {
@@ -60,6 +60,16 @@ window.__ModuleLoader__.load({
60
60
  'topic.relevancePlain': '相关性排序',
61
61
  'topic.needsConversation': '对话内容还不足,暂按最新排序',
62
62
  'topic.time': '按修改时间倒序',
63
+ 'usage.toggle': '使用情况',
64
+ 'usage.toggleTitle': '打开后开始统计这个会话:先看的那篇有没有被读、有多少次读落在包外、上下文换过几回。只记事实,不给分数。',
65
+ 'usage.none': '还没有记录',
66
+ 'usage.primaryRead': '先看的「{rel}」已读',
67
+ 'usage.primaryUnread': '先看的「{rel}」还没读',
68
+ 'usage.supporting': '辅助 {read}/{total}',
69
+ 'usage.reads': '读了 {n} 次',
70
+ 'usage.outside': '包外 {n} 篇',
71
+ 'usage.changes': '上下文换过 {n} 次',
72
+ 'usage.note': '只统计本会话 · 数据在内核内存里,重启 DSH 就没了',
63
73
 
64
74
  // ── v0.14 当前任务上下文(Context Pack)──────────────────────
65
75
  // ⚠️ 文案纪律:不出现「AI / 智能 / 推荐 / 置信度 / 百分比」。
@@ -202,6 +212,16 @@ window.__ModuleLoader__.load({
202
212
  'topic.relevancePlain': 'Sorted by relevance',
203
213
  'topic.needsConversation': 'Not enough conversation yet — sorted by time',
204
214
  'topic.time': 'Sorted by modified time',
215
+ 'usage.toggle': 'Usage',
216
+ 'usage.toggleTitle': 'Measure this session: whether the primary doc was read, how many reads fell outside the pack, how often the context changed. Facts only — no score.',
217
+ 'usage.none': 'Nothing recorded yet',
218
+ 'usage.primaryRead': 'primary read ({rel})',
219
+ 'usage.primaryUnread': 'primary not read yet ({rel})',
220
+ 'usage.supporting': 'supporting {read}/{total}',
221
+ 'usage.reads': '{n} reads',
222
+ 'usage.outside': '{n} outside the pack',
223
+ 'usage.changes': 'context changed {n}×',
224
+ 'usage.note': 'This session only · kept in kernel memory, gone after a DSH restart',
205
225
 
206
226
  // ── v0.14 current-task context (Context Pack) ──────────────
207
227
  // ⚠️ Never say "AI", "smart", "recommended", "confidence" or show percentages:
@@ -405,6 +425,11 @@ window.__ModuleLoader__.load({
405
425
  const SORT_KEY = 'dsh-knit:sort'
406
426
  const RATIO_KEY = 'dsh-knit:preview-ratio'
407
427
  const KIND_KEY = 'dsh-knit:kind'
428
+ /**
429
+ * v0.15「使用情况」的开闸键。**默认关** —— 记账意味着每次轮询都要读一遍会话事件,
430
+ * 用户没要看这个之前,不该有人替他付出这个代价(也不该悄悄攒数据)。
431
+ */
432
+ const USAGE_KEY = 'dsh-knit:usage'
408
433
 
409
434
  /** 列表类型:仅文档 / 仅图片视频 / 全部混排。默认 doc,与旧版体验一致。 */
410
435
  const KIND_DOC = 'doc'
@@ -567,6 +592,8 @@ body[data-ds-dark-theme] .knit-root{
567
592
  border:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.08));font-size:11px}
568
593
  .knit-btn:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));
569
594
  color:var(--dsw-alias-label-primary,#e8eaed)}
595
+ .knit-btn.active{background:var(--knit-active-bg,rgba(255,255,255,.085));
596
+ color:var(--dsw-alias-label-primary,#e8eaed);border-color:var(--dsw-alias-border-l4,rgba(255,255,255,.22))}
570
597
  .knit-bar{display:flex;align-items:center;gap:8px;padding:0 12px 8px;flex:none}
571
598
  .knit-seg{display:inline-flex;flex:none;border-radius:7px;overflow:hidden;
572
599
  border:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.1))}
@@ -586,6 +613,11 @@ body[data-ds-dark-theme] .knit-root{
586
613
  /* ⚠️ 这里以前有一条 border-bottom(全宽横线)。2026-09-29 用户要求**减少全宽分割线**
587
614
  ——「页面上横线一多,读起来就像文件管理表格」。层级改由空间与字号建立:
588
615
  这一行只用 bottom padding 与列表拉开距离,不画线。 */
616
+ /* v0.15「使用情况」:**一行事实**,不画卡片、不画进度条、不用品牌色。
617
+ 它就在「相关性排序」那行下面 —— 与它同档的弱化文字,不是一块新面板。 */
618
+ .knit-usage{flex:none;padding:0 12px 9px;font-size:10.5px;line-height:1.45;
619
+ color:var(--dsw-alias-label-caption,#80868b);
620
+ overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
589
621
 
590
622
 
591
623
  /* ── v0.14 右栏(Context Pack 面板)已整体删除(2026-09-29)────────
@@ -1009,6 +1041,14 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1009
1041
  return v === KIND_MEDIA || v === KIND_ALL ? v : KIND_DOC
1010
1042
  }
1011
1043
 
1044
+ /**
1045
+ * 读上次是否打开了「使用情况」。**默认关**(没写过就是关)。
1046
+ * @returns {boolean} 是否记账
1047
+ */
1048
+ function readUsagePref() {
1049
+ return readPref(USAGE_KEY) === '1'
1050
+ }
1051
+
1012
1052
  /**
1013
1053
  * 把预览高度比例夹到合法区间。
1014
1054
  * @param {number} value - 原始比例
@@ -1596,6 +1636,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1596
1636
  // v0.14:当前任务上下文(Context Pack)。宿主只在「文档档 + 相关序 + 有命中」时给,
1597
1637
  // 其余情形是 null —— 那时面板退回它一直在用的平铺列表(行为与 v0.13 逐字一致)。
1598
1638
  context: null,
1639
+ // v0.15:这个会话的使用情况(只统计**事实**:读了几次、落在哪一层、上下文换过几次)。
1640
+ // 宿主只在用户显式打开「使用情况」之后才回传它。
1641
+ usage: null,
1599
1642
  })
1600
1643
  const [preview, setPreview] = React.useState(null)
1601
1644
  const [tick, setTick] = React.useState(() => Date.now())
@@ -1617,6 +1660,10 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1617
1660
  const [links, setLinks] = React.useState(null)
1618
1661
  const [linksExpandedTick, setLinksExpandedTick] = React.useState(0)
1619
1662
 
1663
+ // v0.15「使用情况」的开闸状态(默认关,见 `USAGE_KEY`)。放在最后 —— 前几个 hook
1664
+ // 的顺序被测试按位预置,别插队。
1665
+ const [usageOn, setUsageOn] = React.useState(readUsagePref)
1666
+
1620
1667
  /* ── 曾经在这里的三个状态 + 一个 ref:右栏的形态 ──────────
1621
1668
  `packWidth`(310) / `packFloat`(null) / `packSnap`(false) / `packColRef`。
1622
1669
  **2026-09-29 随右栏一起删除**。当时它们**只存在内存里**(刷新回默认值),
@@ -1642,7 +1689,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1642
1689
  return
1643
1690
  }
1644
1691
  try {
1645
- const url = `${LIST_API}?sessionId=${encodeURIComponent(sessionId)}&limit=40&sort=${sort}&kind=${kind}`
1692
+ // `usage=1` 是**开闸**(不是「顺便取一下」):宿主只有看到它才会开始给这个会话记账。
1693
+ // 没打开「使用情况」的会话,宿主侧一个事件都不读。
1694
+ const url = `${LIST_API}?sessionId=${encodeURIComponent(sessionId)}&limit=40&sort=${sort}&kind=${kind}${usageOn ? '&usage=1' : ''}`
1646
1695
  const res = await fetch(url, { headers: { accept: 'application/json' }, cache: 'no-store' })
1647
1696
  const data = await res.json()
1648
1697
  if (data && data.ok) {
@@ -1655,16 +1704,17 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1655
1704
  mode: data.mode || 'time',
1656
1705
  topic: data.topic || '',
1657
1706
  context: data.context || null,
1707
+ usage: data.usage || null,
1658
1708
  })
1659
1709
 
1660
1710
  } else {
1661
- setState({ status: 'error', docs: [], root: '', total: 0, error: hostMessage(data), mode: 'time', topic: '', context: null })
1711
+ setState({ status: 'error', docs: [], root: '', total: 0, error: hostMessage(data), mode: 'time', topic: '', context: null, usage: null })
1662
1712
  }
1663
1713
  } catch (error) {
1664
- setState({ status: 'error', docs: [], root: '', total: 0, error: String((error && error.message) || error), mode: 'time', topic: '', context: null })
1714
+ setState({ status: 'error', docs: [], root: '', total: 0, error: String((error && error.message) || error), mode: 'time', topic: '', context: null, usage: null })
1665
1715
  }
1666
1716
  setTick(Date.now())
1667
- }, [sessionId, sort, kind])
1717
+ }, [sessionId, sort, kind, usageOn])
1668
1718
 
1669
1719
  React.useEffect(() => {
1670
1720
  let alive = true
@@ -1848,6 +1898,10 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1848
1898
  // 预览高度:拖完就记住
1849
1899
  React.useEffect(() => { writePref(RATIO_KEY, String(ratio)) }, [ratio])
1850
1900
 
1901
+ // 「使用情况」开关:开了就记住(只记开关本身,**记账数据一律活在内核内存里**,
1902
+ // 面板不落盘 —— 与「界面几何状态不落盘」是同一条纪律)。
1903
+ React.useEffect(() => { writePref(USAGE_KEY, usageOn ? '1' : '0') }, [usageOn])
1904
+
1851
1905
  /**
1852
1906
  * 为一个条目造预览状态:图片/视频直接 ready(字节地址交给 <img>/<video>),
1853
1907
  * Markdown 才进 loading 去拉正文。
@@ -2173,6 +2227,29 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2173
2227
  ? t('topic.relevanceTerms', { topic: state.topic })
2174
2228
  : topicText
2175
2229
 
2230
+ /* v0.15「使用情况」:只把**事实**读出来 —— 先看的那篇读没读、辅助读了几篇、
2231
+ 一共读了几次、几次落在包外、上下文换过几回。
2232
+ ⚠️ 不许出现分数 / 百分比 / 评分条 / 置信度 / 「AI 判断」这类词:用户要知道的是
2233
+ 「这份上下文有没有被用上」,不是「它好不好用」。**没有任何一行是估算出来的。** */
2234
+ const usageText = (() => {
2235
+ if (!usageOn) return ''
2236
+ const u = state.usage
2237
+ if (!u || !u.stats) return t('usage.none')
2238
+ const s = u.stats
2239
+ const parts = []
2240
+ if (s.primaryRel) {
2241
+ parts.push(s.primaryFollowThrough
2242
+ ? t('usage.primaryRead', { rel: s.primaryRel })
2243
+ : t('usage.primaryUnread', { rel: s.primaryRel }))
2244
+ }
2245
+ const sup = (s.byTier && s.byTier.supporting) || { read: 0, total: 0 }
2246
+ if (sup.total > 0) parts.push(t('usage.supporting', { read: sup.read, total: sup.total }))
2247
+ if (s.reads) parts.push(t('usage.reads', { n: s.reads }))
2248
+ if (s.outside) parts.push(t('usage.outside', { n: s.outside }))
2249
+ if (s.churn && s.churn.snapshots) parts.push(t('usage.changes', { n: s.churn.snapshots }))
2250
+ return parts.join(' · ')
2251
+ })()
2252
+
2176
2253
  // 不同类型用不同量词:文档「篇」、媒体「个」、混排「项」。
2177
2254
  const countKey = kind === KIND_MEDIA
2178
2255
  ? (filtering ? 'count.media.filtered' : 'count.media')
@@ -2199,6 +2276,14 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2199
2276
  },
2200
2277
  }, state.root || '—'),
2201
2278
  h('div', { className: 'knit-count' }, countText),
2279
+ // v0.15:默认关的自查开关。开着才有 `&usage=1` —— 宿主也只在那一刻开始记账。
2280
+ h('button', {
2281
+ type: 'button',
2282
+ className: `knit-btn${usageOn ? ' active' : ''}`,
2283
+ 'aria-pressed': usageOn,
2284
+ title: t('usage.toggleTitle'),
2285
+ onClick: () => setUsageOn((value) => !value),
2286
+ }, t('usage.toggle')),
2202
2287
  h('button', { className: 'knit-btn', onClick: load, title: t('action.refreshNow') }, t('action.refresh'))),
2203
2288
  h('div', { className: 'knit-bar' },
2204
2289
  h('div', { className: 'knit-seg' },
@@ -2234,6 +2319,8 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2234
2319
  onClick: () => pickKind(value),
2235
2320
  }, t(labelKey)))),
2236
2321
  h('div', { className: 'knit-topic', title: topicTitle }, topicText),
2322
+ // v0.15:开了才显示。一行事实,没有卡片、没有分数条。
2323
+ usageOn ? h('div', { className: 'knit-usage', title: t('usage.note') }, usageText || t('usage.none')) : null,
2237
2324
  notice ? h('div', { className: 'knit-notice' }, notice) : null,
2238
2325
  // 列表节点**直接挂上去**(2026-09-29 起永远单栏;曾经它要交给一个 IIFE
2239
2326
  // 决定塞进单栏还是双栏的左列)。**输出与 v0.13 逐字一致** ——