dsh-knit 0.16.0 → 0.18.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/README.md CHANGED
@@ -7,9 +7,9 @@
7
7
 
8
8
  ![Knit 面板真机截图:右侧栏按相关性列出工作区文档,就地展开 Markdown 预览,预览头下方是引用条](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png)
9
9
 
10
- *真机截图(不是原型):一个含 51 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
10
+ *真机截图(不是原型):一个含 53 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
11
11
  *引用条是 v0.12 加的:展开就能看到「这篇被谁引用」,点一项直接跳过去。*
12
- *顶行会跟着你正在聊什么变;对话内容还不足时它退回按时间排,并如实说明依据。*
12
+ *头部只放路径、篇数与两个开关;列表按「相关」还是「最新」排,由左边那一对页签决定 —— 按「相关」时排的就是你正在聊什么。*
13
13
  *v0.14 起文档列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
14
14
  *Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
15
15
  *序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
@@ -17,9 +17,10 @@
17
17
 
18
18
  ![排序跟着对话走:发一句话,右侧栏的文档列表按这句话重排](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/demo-reorder.gif)
19
19
 
20
- *排序跟着对话走(同一个工作区、刚新开一个会话):还没聊什么时,顶行如实写着「对话内容还不足,暂按最新排序」,*
21
- *列表按时间排;问一句「排序算法用的 BM25 是怎么加权的?」,顶上立刻换成排序那几篇 ——*
22
- *序号与「主要上下文 / 辅助上下文 / 相关上下文」三层随之一起出现(跨三档连续编号)。*
20
+ *排序跟着对话走(同一个工作区、刚新开一个会话):还没聊什么时,列表按修改时间排;*
21
+ *问一句「排序算法用的 BM25 是怎么加权的?」,下一次轮询就把顶上几条整个换掉 ——*
22
+ *分组标题与**跨三档连续的序号**随之一起出现,每篇下面多一行「为什么」(命中在哪、怎么命中的)。*
23
+ *这一屏里没有文档落进主要层,所以分组从「辅助上下文」开始。*
23
24
  *⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
24
25
 
25
26
  扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
@@ -163,13 +164,14 @@ dsh plugin --profile web add dsh-knit
163
164
  | **按当前对话相关性排序**(BM25 + IDF,纯本地,零模型) | ✅ |
164
165
  | **当前任务上下文**:把排序结果拆成 **主要 / 辅助 / 相关** 三层,每条都写明「为什么在这里」 | ✅ |
165
166
  | **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
167
+ | **文档生命周期**(v0.17):每篇推荐文档现在处于 `未读 / 已读 / 读后已更新 / 修改后已重新读取` 哪一档,另外给出最近读了哪篇、包外读了哪几篇、上下文最近一次怎么变 | ✅ |
166
168
  | 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
167
169
  | 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
168
170
  | 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
169
171
  | 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径**重复,只保留后者 | ✅ |
170
172
  | 单击就地展开预览,再点收起 | ✅ |
171
173
  | 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
172
- | **文档 / 图片与视频 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边 | ✅ |
174
+ | **文档 / 媒体 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边(页签「媒体」2026-10-06 由「图片与视频」改短) | ✅ |
173
175
  | 图片与视频:方形缩略图网格,**格子基准固定 104px、列数由宽度连续数出来**(320px → 2 列 / 632px → 5 列 / 1200px → 10 列),格子大小基本不变;**纵向有多少行就铺多少行**,超出交给列表滚动;视频自动取首帧、叠播放三角与时长角标(零依赖、不转码) | ✅ |
174
176
  | 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
175
177
  | 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
@@ -189,19 +191,18 @@ dsh plugin --profile web add dsh-knit
189
191
 
190
192
  ### 另外两档长什么样
191
193
 
192
- ![图片与视频档真机截图:方形缩略图网格,这一屏 6 列](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
194
+ ![媒体档真机截图:方形缩略图网格,这一屏 6 列](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
193
195
 
194
- *图片与视频:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
195
- *列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图和两个单色 SVG 图标,*
196
- *所以看起来像一屏文件缩略图(那两个纯黑方块就是那两个图标本身)。视频会取首帧当海报、*
197
- *中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
196
+ *媒体:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
197
+ *列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图、一张演示动图和一个*
198
+ *单色 SVG 图标,所以看起来像一屏文件缩略图(那个纯黑方块就是图标本身,不是加载失败)。*
199
+ *视频会取首帧当海报、中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
198
200
 
199
- ![全部档真机截图:文档区只给前 4 条与「查看全部 →」,媒体区没有出现](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
201
+ ![全部档真机截图:上区文档只给前 4 条与「查看全部 →」,下区是媒体网格](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
200
202
 
201
- *全部:文档区最多 4 条,超出时右侧给「查看全部 →」(这一屏是「4 / 40」)。*
202
- *⚠️ **这一屏没有媒体区,而且不是排版问题** —— 宿主为「全部」档取的是 **40 条窗口**:这个工作区*
203
- *51 篇文档 + 8 个媒体,媒体按相关性排在第 50–58 位、整段被挤出窗口,于是客户端的*
204
- *`visibleDocs.filter(isMedia)` 恒为空、媒体区整个不渲染。**文档数 ≥ 40 的工作区都会这样**,*
203
+ *全部:上区文档最多 4 条,超出时右侧给「查看全部 →」(这一屏是「4 / 39」),下区是媒体网格。*
204
+ *⚠️ 上下两区共用宿主返回的**同一个 40 条窗口**:媒体如果按相关性排到第 40 名之外,*
205
+ *「全部」档就只剩窗口里那几个(这一屏只剩 1 个;「媒体」档不受影响,它单独取媒体)。*
205
206
  *这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
206
207
 
207
208
  ---
@@ -317,17 +318,19 @@ Knit 一装上就有整个项目的历史文档可用。
317
318
 
318
319
  ---
319
320
 
320
- ## 它有没有被用上(v0.16)
321
+ ## 它有没有被用上(v0.16 → v0.17)
321
322
 
322
323
  Knit 会排出「现在最该先看的几篇」,但**排得对不对,过去只能靠感觉**。
323
324
  v0.15 起有一层**可核验的使用反馈**:把 agent 真实读过的文件,跟**读发生那一刻**生效的那份上下文对起来。
324
325
  v0.16 把这件事钉死:**归因在读发生那一刻结算并冻结** —— 之后上下文怎么换,历史数字都不会改口
325
326
  (v0.15 里同一个读会被「现在」重判成包外,那是 bug)。
326
327
 
327
- **默认关。** 面板头部有一个「使用情况」开关,打开之后列表上方会多一行字:
328
+ **默认关。** 面板头部有一个「使用情况」开关,打开之后列表上方会多出一块**观察层**
329
+ (v0.18 起叫 Usage Lens,形状见下面「把使用情况读出来」一节)。它最上面一行仍然只报事实:
328
330
 
329
331
  ```
330
- 当前上下文 · Epoch 4 · 先看的「docs/xxx.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次
332
+ 使用情况 Epoch 5 ˄
333
+ 174 次读取 · 28 篇包外 · 上下文变化 3 次
331
334
  ```
332
335
 
333
336
  - **Context Epoch**:一份**内容有变化**的上下文 = 一个 Epoch(内容没变就不新建,轮询不会灌进几十个)。
@@ -345,8 +348,10 @@ v0.16 把这件事钉死:**归因在读发生那一刻结算并冻结** ——
345
348
  没开审计的会话只花一次 Map 查找)。这笔账该由你决定要不要付。
346
349
  - **不重复 DSH 的轨迹**:证据只有一个来源 —— 会话事件流里**已经存在**的 `tool/call` /
347
350
  `tool/result` 事件(成功的 `read`)。**没有新的事件总线、没有 Runtime Trace、也没有 Event Store。**
348
- - **只从现在开始**:订阅是 v0.16 唯一的读证据来源(旧的 `session.snapshotEvents()` 已被 DSH
349
- 标为 deprecated),所以**打开开关之前发生的读不会回补** —— 那一刻起才开始计数。
351
+ - **打开开关的那一刻会回填一次**:订阅是唯一的读证据来源(旧的 `session.snapshotEvents()` 已被
352
+ DSH 标为 deprecated,不再新增生产调用),所以**闸门打开之前发生的读,Knit 当时确实看不见**;
353
+ v0.17 起在闸门打开的那一刻**回填一次**本会话已有的事件,让「未读」变成有证据的结论。
354
+ ⚠️ 回填的读按**我们已知最早的那份包**归因(更早的包无从得知)。
350
355
  - **不落盘**:数据只在宿主内存里,重启 DSH 就没了,**别把它当长期统计**。
351
356
 
352
357
  agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工具结果末尾会多一行
@@ -357,6 +362,97 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
357
362
  **Knit 索引里有、却没进包**(真漏)与**压根不在索引里**(`.js` / `.json`,Knit 本来就不索引这些);
358
363
  不拆开的话包外比例恒高,读起来像「Context Pack 没用」,其实是**量错了东西**。
359
364
 
365
+ ### v0.17:读完之后,这篇文档现在是什么状态
366
+
367
+ 打开「使用情况」之后,除了统计,还会多两样东西:**每篇推荐文档的状态**,
368
+ 以及「最近读了哪篇 / 包外读了哪几篇 / 上下文最近一次怎么变」。
369
+
370
+ > ⚠️ 下面这段 ASCII 是 **v0.17 当时的界面形状**。v0.18 把这一块重做成了列表上方的 Usage Lens
371
+ > (形状见下一节)—— **判据、四档状态、数据来源一个字没变**,这一节讲的是数据与判据。
372
+
373
+ ```
374
+ 当前上下文 · Epoch 4
375
+ 最近读取:SDD-v0.17.md · 12 分钟前
376
+
377
+ 主要上下文
378
+ 01 ● SDD-v0.17.md 已读 ×3
379
+ 02 feedback.md 未读
380
+
381
+ 辅助上下文
382
+ 03 context.md 已读
383
+ 04 eval.md 读后已更新
384
+
385
+ 相关上下文
386
+ 05 README.md 修改后已重新读取
387
+
388
+ 上下文外读取 · 2 篇 ← 点得开,展开是「哪几篇」
389
+ 上下文刚刚变化 ← 点得开,展开是「进入 / 离开 / 换层」
390
+ ```
391
+
392
+ 四档状态全是**事实**,不是评分:
393
+
394
+ | 界面文案 | 事实 |
395
+ |---|---|
396
+ | 未读 | 本会话没有一次成功 `read` |
397
+ | 已读 / 已读 ×N | 成功读过,且最后一次读取之后文件没变 |
398
+ | 读后已更新 | 最后一次成功读取之后,文件的 `mtimeMs` 变过 |
399
+ | 修改后已重新读取 | 变过之后又成功读过一次(再变一次就退回上一档) |
400
+
401
+ - **判据就是文件的 `mtimeMs`** —— 工作区扫描本来就拿得到它,所以**不比对内容、不扫描全文、不新增索引**。
402
+ 拿不到 mtime 时**不下结论**(宁可停在「已读」)。
403
+ - `grep` / `glob` / `bash` 不算读;失败的 `read` 也不算。
404
+ - 「最近读取」按事件序号判定「谁最近」,**不叫「正在阅读」**:Knit 无法证明 Agent 此刻还在读它;
405
+ 它落在 Context Pack 之外也照实显示。
406
+ - **上下文外读取 · N 篇**只表达「这篇不在当前包,但 Agent 确实成功读过它」——
407
+ 不写「Knit 漏掉了」,也不做漏召回率、命中率、Context 质量。
408
+ - **上下文刚刚变化**只展示**最近一次** Delta(`+` 进入 / `-` 离开 / `↔` 换层,
409
+ 任务变了就说一句「任务上下文已更新」)—— **没有时间线,也没有事件浏览器**。
410
+ - 状态文字排在标题和时间之间,**标题仍然是视觉主体**;不用红绿、不给分。
411
+ 关掉开关则**一个都不出现**(也不统计)。
412
+ - **列表不再「一闪一闪」**(2026-10-03 用户要求):被读到的行从下方淡入上浮,被挤掉的行
413
+ **自上而下**擦除渐隐;同一拍里多篇按 45ms 错开(最多 6 档);换了层或名次变了的那篇
414
+ **从老位置飞过去**(FLIP,340ms)。首屏、换类型 / 换排序 / 搜索词,
415
+ 以及系统开了「减弱动态效果」时都**不播**。这不是新功能,只是把「谁进来了、谁走了、
416
+ 谁挪了位置」演给人看 —— 索引、排序、分层与 `knit_docs` 的输出一个字都没改。
417
+
418
+ ### v0.18:把「使用情况」读出来(Context Usage Lens)
419
+
420
+ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出结构:哪一层读得多、最近读的是哪一篇、
421
+ 包外那二十篇里哪几篇被反复读、这次变化是进是出。v0.18 把它重做成列表**上方的一块观察层**
422
+ —— 不是弹窗、不是新页面、也不是 Dashboard:
423
+
424
+ ```
425
+ 使用情况 Epoch 5 ˄
426
+ 174 次读取 · 28 篇包外 · 上下文变化 3 次
427
+ 当前上下文
428
+ 主要 1 / 1 辅助 2 / 3 相关 0 / 5
429
+ ● ● ○ ○ ○ ○ ○ ○
430
+ 最近读取 docs/eval.md 12分钟前 ›
431
+ 上下文外读取 20 ›
432
+ 上下文变化 最近一次 ›
433
+ ```
434
+
435
+ - **当前上下文 Coverage**:三层各给「状态点 + `已读数 / 本层总数`」。点某一层会**滚到那一层并短暂亮一下**
436
+ (不画箭头、不画横线 —— 用空间说「就是这里」)。**只报事实**:没有进度条、没有百分比
437
+ —— Knit 不评价「这份上下文用完了没有」;Primary 不存在时整列不显示,不画 `0 / 0` 的假层。
438
+ - **行内状态点**:未读=空心圆 / 已读=实心圆 / 读后已更新=实心圆套内圈 / 修改后已重新读取=`↻`,
439
+ 与原来那行文字**同时**存在(状态点说状态、文字说次数)。点它=打开这一篇。不用红绿、不加徽章。
440
+ Coverage 的三层圆点与文档行这一颗**同一套 token、同一个 6px 直径** —— 两处说的是同一种状态语言。
441
+ - **最近读取**是一行可点的事实(`文件名 · 相对时间 ›`),点它直接打开该篇,**不重新请求列表**。
442
+ 它仍然是「**最近一次成功 read**」—— 没有改成「正在阅读」。
443
+ - **上下文外读取**默认最多 10 篇 + 「还有 N 篇」,每行可点、带状态;按**读得最多的**排
444
+ (`count DESC`)—— 这是事实排序,不是相关度。**不许**从这里把文档加进 Context(V0.18 不做 Context Control)。
445
+ - **上下文变化**默认折叠,展开按 进入 / 离开 / 换层 分组,每组最多 5 条;只展示**最近一次**。
446
+ - Lens 自己能展开 / 收起。**收起不等于关掉统计** —— 收起只是「统计开着、暂时不想看细节」;
447
+ 关掉开关才真的一个统计 DOM 都不产生。
448
+ - 面板很矮(< 420px)时降级成「摘要 + Coverage + 最近读取」,变化明细点开仍在;
449
+ 滚动**始终只交给列表** —— 没有第二个滚动容器,窄侧栏里不会滚轮套滚轮。
450
+
451
+ 数据一个字都没新加:全部来自 v0.17 已有的 `lifecycle / recentRead / outsideDocs / latestDelta`
452
+ 与当前 `context` 的三层,Coverage 是从它们**派生**的(纯函数 `coverageOf` / `groupOutsideDocs` / `groupDelta`)。
453
+
454
+ `knit_docs` 的工具输出**没有跟着变大**:它仍然只负责找上下文。
455
+
360
456
  ---
361
457
 
362
458
  ## 它读什么,不读什么
@@ -412,7 +508,7 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
412
508
  git clone https://github.com/PolinniZhong/dsh-knit.git
413
509
  cd dsh-knit
414
510
 
415
- npm test # 468 项,零依赖,不需要先 npm install
511
+ npm test # 532 项,零依赖,不需要先 npm install
416
512
  ```
417
513
 
418
514
  **改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
@@ -436,7 +532,7 @@ knit/
436
532
  │ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
437
533
  │ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
438
534
  │ └── client/client.js # 双宿主注册 + 面板 UI
439
- └── test/ # 468 项测试
535
+ └── test/ # 532 项测试
440
536
  ├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
441
537
  └── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
442
538
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-knit",
3
- "version": "0.16.0",
3
+ "version": "0.18.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",
@@ -23,7 +23,7 @@
23
23
  "LICENSE"
24
24
  ],
25
25
  "scripts": {
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 test/context-effectiveness.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 test/context-effectiveness.test.mjs test/document-lifecycle.test.mjs"
27
27
  },
28
28
  "dsh": {
29
29
  "bundle": {