dsh-knit 0.15.0 → 0.17.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,17 +7,20 @@
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
- *Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头的面包屑里**,列表行不再重复。*
14
+ *Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
15
+ *序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
16
+ *空着会被读成「漏了一个号」(2026-10-01)。*
15
17
 
16
18
  ![排序跟着对话走:发一句话,右侧栏的文档列表按这句话重排](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/demo-reorder.gif)
17
19
 
18
- *排序跟着对话走(同一个工作区、刚新开一个会话):还没聊什么时,顶行如实写着「对话内容还不足,暂按最新排序」,*
19
- *列表按时间排;问一句「排序算法用的 BM25 是怎么加权的?」,顶上立刻换成排序那几篇 ——*
20
- *序号与「主要上下文 / 辅助上下文 / 相关上下文」三层随之一起出现。*
20
+ *排序跟着对话走(同一个工作区、刚新开一个会话):还没聊什么时,列表按修改时间排;*
21
+ *问一句「排序算法用的 BM25 是怎么加权的?」,下一次轮询就把顶上几条整个换掉 ——*
22
+ *分组标题与**跨三档连续的序号**随之一起出现,每篇下面多一行「为什么」(命中在哪、怎么命中的)。*
23
+ *这一屏里没有文档落进主要层,所以分组从「辅助上下文」开始。*
21
24
  *⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
22
25
 
23
26
  扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
@@ -161,10 +164,11 @@ dsh plugin --profile web add dsh-knit
161
164
  | **按当前对话相关性排序**(BM25 + IDF,纯本地,零模型) | ✅ |
162
165
  | **当前任务上下文**:把排序结果拆成 **主要 / 辅助 / 相关** 三层,每条都写明「为什么在这里」 | ✅ |
163
166
  | **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
167
+ | **文档生命周期**(v0.17):每篇推荐文档现在处于 `未读 / 已读 / 读后已更新 / 修改后已重新读取` 哪一档,另外给出最近读了哪篇、包外读了哪几篇、上下文最近一次怎么变 | ✅ |
164
168
  | 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
165
169
  | 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
166
170
  | 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
167
- | 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径面包屑**重复,只保留后者 | ✅ |
171
+ | 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径**重复,只保留后者 | ✅ |
168
172
  | 单击就地展开预览,再点收起 | ✅ |
169
173
  | 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
170
174
  | **文档 / 图片与视频 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边 | ✅ |
@@ -172,11 +176,11 @@ dsh plugin --profile web add dsh-knit
172
176
  | 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
173
177
  | 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
174
178
  | 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出 | ✅ |
175
- | **「在本地打开」**:用系统默认应用打开当前预览的这篇文档(预览头的路径面包屑同样可点) | ✅ |
179
+ | **「本地打开」**:用系统默认应用打开当前预览的这篇文档(预览头的路径同样可点,完整路径在悬停提示里) | ✅ |
176
180
  | 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
177
181
  | 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
178
182
  | **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
179
- | **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局) | ✅ |
183
+ | **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局;浮层只有「头 + 列表」,没有多余的横线与提示语) | ✅ |
180
184
  | 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc` 收起;**媒体档** `←` `→` 按屏幕位置跨行,`Home` / `End` 到首尾(文档档永远单列,`←` `→` 没有空间含义) | ✅ |
181
185
  | 每 5 秒自动刷新 + 手动刷新;2 分钟内改动过的文档打 🆕 | ✅ |
182
186
  | 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
@@ -190,16 +194,15 @@ dsh plugin --profile web add dsh-knit
190
194
  ![图片与视频档真机截图:方形缩略图网格,这一屏 6 列](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
191
195
 
192
196
  *图片与视频:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
193
- *列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图和两个单色 SVG 图标,*
194
- *所以看起来像一屏文件缩略图(那两个纯黑方块就是那两个图标本身)。视频会取首帧当海报、*
195
- *中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
197
+ *列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图、一张演示动图和一个*
198
+ *单色 SVG 图标,所以看起来像一屏文件缩略图(那个纯黑方块就是图标本身,不是加载失败)。*
199
+ *视频会取首帧当海报、中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
196
200
 
197
- ![全部档真机截图:文档区只给前 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)
198
202
 
199
- *全部:文档区最多 4 条,超出时右侧给「查看全部 →」(这一屏是「4 / 40」)。*
200
- *⚠️ **这一屏没有媒体区,而且不是排版问题** —— 宿主为「全部」档取的是 **40 条窗口**:这个工作区*
201
- *51 篇文档 + 8 个媒体,媒体按相关性排在第 50–58 位、整段被挤出窗口,于是客户端的*
202
- *`visibleDocs.filter(isMedia)` 恒为空、媒体区整个不渲染。**文档数 ≥ 40 的工作区都会这样**,*
203
+ *全部:上区文档最多 4 条,超出时右侧给「查看全部 →」(这一屏是「4 / 36」),下区是图片与视频网格。*
204
+ *⚠️ 上下两区共用宿主返回的**同一个 40 条窗口**:图片与视频如果按相关性排到第 40 名之外,*
205
+ *「全部」档就**整段看不到它们**(「图片与视频」档不受影响,它单独取媒体)。*
203
206
  *这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
204
207
 
205
208
  ---
@@ -232,7 +235,9 @@ Context Pack 是对这个问题的回答,但它是**数据层的结构**(主
232
235
 
233
236
  > 示意图省掉了每行的摘要。**真实的行结构是:最左边独立一列=序号(与右边第一行**垂直居中**),
234
237
  > 右边堆叠=第一行「Primary 点 + 标题 + 相对时间(**靠右**)」→ 摘要(**没有路径** ——
235
- > 列表行里不显示它,路径在预览头的面包屑上)。而且这个列表**永远是单列**(面板拖到多宽都一样)。
238
+ > 列表行里不显示它,路径在预览头上、目录收敛成 `…/`)。而且这个列表**永远是单列**(面板拖到多宽都一样)。
239
+ > 「其他相关文档」不在包里、不编号,那一列放一个中性的 `·` 占位 —— 但只在**这一屏里有号**时才放
240
+ > (时间序 / 平铺列表整屏没号 ⇒ 一个标记都没有;混着才刺眼)。
236
241
 
237
242
  **分组之间不画横线**:层级靠 16px 的空间、组名与字号建立,不靠分割线。
238
243
  分组里没有分数、没有百分比、没有星级 —— 「为什么在这里」只写**确定性的事实**。
@@ -313,26 +318,38 @@ Knit 一装上就有整个项目的历史文档可用。
313
318
 
314
319
  ---
315
320
 
316
- ## 它有没有被用上(v0.15)
321
+ ## 它有没有被用上(v0.16 → v0.17)
317
322
 
318
323
  Knit 会排出「现在最该先看的几篇」,但**排得对不对,过去只能靠感觉**。
319
- v0.15 加了一层**可核验的使用反馈**:把 agent 真实读过的文件,跟**读发生那一刻**生效的那份上下文对起来。
324
+ v0.15 起有一层**可核验的使用反馈**:把 agent 真实读过的文件,跟**读发生那一刻**生效的那份上下文对起来。
325
+ v0.16 把这件事钉死:**归因在读发生那一刻结算并冻结** —— 之后上下文怎么换,历史数字都不会改口
326
+ (v0.15 里同一个读会被「现在」重判成包外,那是 bug)。
320
327
 
321
328
  **默认关。** 面板头部有一个「使用情况」开关,打开之后列表上方会多一行字:
322
329
 
323
330
  ```
324
- 先看的「docs/xxx.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次
331
+ 当前上下文 · Epoch 4 · 先看的「docs/xxx.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次
325
332
  ```
326
333
 
334
+ - **Context Epoch**:一份**内容有变化**的上下文 = 一个 Epoch(内容没变就不新建,轮询不会灌进几十个)。
335
+ `Epoch 4` 是累计编号,不是「第几份包」。
336
+ - **两个只记事实的字段**:`continuedReadAfterExit`(离开这份上下文之后它仍然被读)、
337
+ `reEntry`(离开过、又回到包里、又被读)。它们**不许**被读成「Agent 不认可新上下文」——
338
+ 那是推断,不是事实。
339
+
327
340
  它只报**事实**:先看的那篇被读了没有、读了几次、多少篇落在包外、上下文换过几回。
328
341
  **没有分数、没有百分比、没有进度条** —— 这些数字不是估算出来的,是数出来的。
329
342
 
330
343
  三条边界:
331
344
 
332
- - **默认关闭**:不打开就**不读一个事件、不攒一条数据**。这笔账是有代价的
333
- (每次轮询都要读一遍会话事件),该由你决定要不要付。
334
- - **不重复 DSH 的轨迹**:证据只有一个来源 —— 会话里**已经存在**的 `tool/call` / `tool/result`
335
- 事件(成功的 `read`)。**没有新的事件总线、没有 Runtime Trace、也没有 Event Store。**
345
+ - **默认关闭**:不打开就**不统计任何东西**(Knit 订阅宿主事件流,但回调第一行就按会话早退,
346
+ 没开审计的会话只花一次 Map 查找)。这笔账该由你决定要不要付。
347
+ - **不重复 DSH 的轨迹**:证据只有一个来源 —— 会话事件流里**已经存在**的 `tool/call` /
348
+ `tool/result` 事件(成功的 `read`)。**没有新的事件总线、没有 Runtime Trace、也没有 Event Store。**
349
+ - **打开开关的那一刻会回填一次**:订阅是唯一的读证据来源(旧的 `session.snapshotEvents()` 已被
350
+ DSH 标为 deprecated,不再新增生产调用),所以**闸门打开之前发生的读,Knit 当时确实看不见**;
351
+ v0.17 起在闸门打开的那一刻**回填一次**本会话已有的事件,让「未读」变成有证据的结论。
352
+ ⚠️ 回填的读按**我们已知最早的那份包**归因(更早的包无从得知)。
336
353
  - **不落盘**:数据只在宿主内存里,重启 DSH 就没了,**别把它当长期统计**。
337
354
 
338
355
  agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工具结果末尾会多一行
@@ -343,6 +360,58 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
343
360
  **Knit 索引里有、却没进包**(真漏)与**压根不在索引里**(`.js` / `.json`,Knit 本来就不索引这些);
344
361
  不拆开的话包外比例恒高,读起来像「Context Pack 没用」,其实是**量错了东西**。
345
362
 
363
+ ### v0.17:读完之后,这篇文档现在是什么状态
364
+
365
+ 打开「使用情况」之后,除了上面那一行,还会多两样东西:**每篇推荐文档的状态**,
366
+ 以及「最近读了哪篇 / 包外读了哪几篇 / 上下文最近一次怎么变」。
367
+
368
+ ```
369
+ 当前上下文 · Epoch 4
370
+ 最近读取:SDD-v0.17.md · 12 分钟前
371
+
372
+ 主要上下文
373
+ 01 ● SDD-v0.17.md 已读 ×3
374
+ 02 feedback.md 未读
375
+
376
+ 辅助上下文
377
+ 03 context.md 已读
378
+ 04 eval.md 读后已更新
379
+
380
+ 相关上下文
381
+ 05 README.md 修改后已重新读取
382
+
383
+ 上下文外读取 · 2 篇 ← 点得开,展开是「哪几篇」
384
+ 上下文刚刚变化 ← 点得开,展开是「进入 / 离开 / 换层」
385
+ ```
386
+
387
+ 四档状态全是**事实**,不是评分:
388
+
389
+ | 界面文案 | 事实 |
390
+ |---|---|
391
+ | 未读 | 本会话没有一次成功 `read` |
392
+ | 已读 / 已读 ×N | 成功读过,且最后一次读取之后文件没变 |
393
+ | 读后已更新 | 最后一次成功读取之后,文件的 `mtimeMs` 变过 |
394
+ | 修改后已重新读取 | 变过之后又成功读过一次(再变一次就退回上一档) |
395
+
396
+ - **判据就是文件的 `mtimeMs`** —— 工作区扫描本来就拿得到它,所以**不比对内容、不扫描全文、不新增索引**。
397
+ 拿不到 mtime 时**不下结论**(宁可停在「已读」)。
398
+ - `grep` / `glob` / `bash` 不算读;失败的 `read` 也不算。
399
+ - 「最近读取」按事件序号判定「谁最近」,**不叫「正在阅读」**:Knit 无法证明 Agent 此刻还在读它;
400
+ 它落在 Context Pack 之外也照实显示。
401
+ - **上下文外读取 · N 篇**只表达「这篇不在当前包,但 Agent 确实成功读过它」——
402
+ 不写「Knit 漏掉了」,也不做漏召回率、命中率、Context 质量。
403
+ - **上下文刚刚变化**只展示**最近一次** Delta(`+` 进入 / `-` 离开 / `↔` 换层,
404
+ 任务变了就说一句「任务上下文已更新」)—— **没有时间线,也没有事件浏览器**。
405
+ - 状态文字排在标题和时间之间,**标题仍然是视觉主体**;不用红绿、不给分。
406
+ 关掉开关则**一个都不出现**(也不统计)。
407
+ - **列表不再「一闪一闪」**(2026-10-03 用户要求):被读到的行从下方淡入上浮,被挤掉的行
408
+ **自上而下**擦除渐隐;同一拍里多篇按 45ms 错开(最多 6 档);换了层或名次变了的那篇
409
+ **从老位置飞过去**(FLIP,340ms)。首屏、换类型 / 换排序 / 搜索词,
410
+ 以及系统开了「减弱动态效果」时都**不播**。这不是新功能,只是把「谁进来了、谁走了、
411
+ 谁挪了位置」演给人看 —— 索引、排序、分层与 `knit_docs` 的输出一个字都没改。
412
+
413
+ `knit_docs` 的工具输出**没有跟着变大**:它仍然只负责找上下文。
414
+
346
415
  ---
347
416
 
348
417
  ## 它读什么,不读什么
@@ -398,7 +467,7 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
398
467
  git clone https://github.com/PolinniZhong/dsh-knit.git
399
468
  cd dsh-knit
400
469
 
401
- npm test # 395 项,零依赖,不需要先 npm install
470
+ npm test # 517 项,零依赖,不需要先 npm install
402
471
  ```
403
472
 
404
473
  **改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
@@ -419,9 +488,10 @@ knit/
419
488
  │ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
420
489
  │ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
421
490
  │ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
491
+ │ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
422
492
  │ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
423
493
  │ └── client/client.js # 双宿主注册 + 面板 UI
424
- └── test/ # 395 项测试
494
+ └── test/ # 517 项测试
425
495
  ├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
426
496
  └── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
427
497
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-knit",
3
- "version": "0.15.0",
3
+ "version": "0.17.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"
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": {