dsh-knit 0.13.0 → 0.14.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,10 +7,16 @@
7
7
 
8
8
  ![Knit 面板真机截图:右侧栏按相关性列出工作区文档,就地展开 Markdown 预览,预览头下方是引用条](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png)
9
9
 
10
- *真机截图(不是原型):一个含 34 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
10
+ *真机截图(不是原型):一个含 36 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
11
11
  *引用条是 v0.12 加的:展开就能看到「这篇被谁引用」,点一项直接跳过去。*
12
12
  *顶行会跟着你正在聊什么变;对话内容还不足时它退回按时间排,并如实说明依据。*
13
13
 
14
+ ![排序跟着对话走:发一句话,右侧栏的文档列表按这句话重排](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/demo-reorder.gif)
15
+
16
+ *排序跟着对话走(同一个工作区、同一个会话):先问「排序算法用的 BM25 是怎么加权的?」,*
17
+ *顶上换成排序那几篇;再问「插件市场收录和下载量怎么查?」,顶上又换成市场调研那几篇。*
18
+ *⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
19
+
14
20
  扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
15
21
 
16
22
  ```sh
@@ -125,6 +131,24 @@ dsh plugin --profile web add dsh-knit
125
131
  **可选**:装了 `dsh-better-sidebar` 的话,面板也会注册成它的一个 tab;
126
132
  没装不受影响,两边是各自独立的可选依赖。
127
133
 
134
+ **升级**:命令和首次安装是同一条,装完同样要**重启 DSH** + 硬刷新。
135
+
136
+ ---
137
+
138
+ ## 反馈
139
+
140
+ **这个项目当前的重心不是加功能,是搞清楚「按对话给文档排序」这件事到底有没有人在用。**
141
+ 所以最有价值的一句话不是「能不能加个 XX」,而是**你现在是怎么绕过它的** ——
142
+ 哪怕结论是「装了,但一周没打开过」,也请直说,那比一个功能建议有用得多。
143
+
144
+ - 💬 [说说你在什么场景下会打开它](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) —— 两步、三十秒,不必客气
145
+ - 🐞 [装不上 / 面板打不开 / 排得不对](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
146
+ - 📖 提之前先看一眼[已知限制](#已知限制) —— 短对话退化、中文用 n-gram 近似,这几条是已知的取舍,不是 bug
147
+
148
+ > 一条 issue 会被当成真实信号处理。这个插件到现在**一个真实用户的痕迹都没有**
149
+ > (npm 那个下载量是自动化版本枚举、不是人 —— `latest` 占比只有 14%,而真人只会装 `latest`)
150
+ > —— 一条有人味儿的反馈能直接改变接下来做什么。
151
+
128
152
  ---
129
153
 
130
154
  ## 功能
@@ -132,11 +156,12 @@ dsh plugin --profile web add dsh-knit
132
156
  | 能力 | |
133
157
  |---|---|
134
158
  | **按当前对话相关性排序**(BM25 + IDF,纯本地,零模型) | ✅ |
135
- | **给 agent 用的 `knit_docs` 工具**:让模型自己查「这个项目里跟当前话题最相关的文档」 | ✅ |
159
+ | **当前任务上下文**:把排序结果拆成 **主要 / 辅助 / 相关** 三层,每条都写明「为什么在这里」 | ✅ |
160
+ | **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
136
161
  | 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
137
162
  | 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
138
163
  | 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
139
- | 面板拖宽后文档列表**自动排成 2 列**(<420px 保持 1 列);**多列时字段一个不少**,只是排版改成纵向、标题与路径折两行 | ✅ |
164
+ | 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径面包屑**重复,只保留后者 | ✅ |
140
165
  | 单击就地展开预览,再点收起 | ✅ |
141
166
  | 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
142
167
  | **文档 / 图片与视频 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边 | ✅ |
@@ -149,14 +174,106 @@ dsh plugin --profile web add dsh-knit
149
174
  | 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
150
175
  | **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
151
176
  | **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局) | ✅ |
152
- | 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc` 收起;多列时 `←` `→` 按屏幕位置跨行,`Home` / `End` 到首尾 | ✅ |
177
+ | 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc` 收起;**媒体档** `←` `→` 按屏幕位置跨行,`Home` / `End` 到首尾(文档档永远单列,`←` `→` 没有空间含义) | ✅ |
153
178
  | 每 5 秒自动刷新 + 手动刷新;2 分钟内改动过的文档打 🆕 | ✅ |
154
179
  | 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
155
- | 列表是标准 `listbox`/`option` 语义,选中项用 `aria-activedescendant` 播报;多列时键盘焦点有可见描边 | ✅ |
180
+ | 列表是标准 `listbox`/`option` 语义,选中项用 `aria-activedescendant` 播报;媒体网格里的键盘焦点有可见描边 | ✅ |
156
181
  | 零模型调用、零网络出口 | ✅ |
157
182
 
158
183
  > 相关度**不做可视化**(不显示百分比、不画长条)—— 排序本身就是答案,名次即相关度。
159
184
 
185
+ ### 另外两档长什么样
186
+
187
+ ![图片与视频档真机截图:方形缩略图网格,这一屏 6 列,其中一个视频缩略图带播放三角与时长角标](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
188
+
189
+ *图片与视频:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
190
+ *视频取首帧当海报,中央叠播放三角、右下角叠时长。列出的就是工作区里真实的图片与 SVG 文件 ——*
191
+ *这个工作区里正好有几张截图和两个图标,所以看起来像一屏文件缩略图。*
192
+
193
+ ![全部档真机截图:上区文档列表,下区图片与视频只给计数](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
194
+
195
+ *全部:上区文档(最多 4 条,超出时右侧给「查看全部 →」)、下区图片与视频(**不截断**,只给计数)。*
196
+ 标题 / 时间 / 摘要 / 路径**四个字段一个不少**。
197
+ ⚠️ **这张图是 v0.13 时代的**:那时候文档还能排 2 列,列表行里也还有路径,标题与时间各占一行;
198
+ **v0.14 起文档列表永远单列**(每篇最左边独立一列是序号,与标题第一行垂直居中;右边第一行=
199
+ Primary 点 + 标题 + 相对时间,**时间靠右**;摘要再往下),
200
+ 而且**路径不再出现在列表行里**(预览头的面包屑始终显示完整路径,重复的那份删掉了),
201
+ 截图尚未重拍。
202
+
203
+ ---
204
+
205
+ ## 当前任务上下文(v0.14)
206
+
207
+ 排序解决的是「哪几篇跟这段对话最像」。但你要的往往是另一个问题的答案:
208
+
209
+ > **现在这个任务,项目里哪些东西最值得先看?**
210
+
211
+ Context Pack 是对这个问题的回答,但它是**数据层的结构**(主要 / 辅助 / 相关三层 + 每条的确定性理由),
212
+ **不是一张要单独显示的卡片**。所以它直接落在文档列表里:相关模式下,文档档从一条平铺列表
213
+ 变成**三层分组**,组名后面跟一句极短的说明。
214
+
215
+ ```
216
+ ┌─ 文档列表 ────────────────────────────┐
217
+ │ 主要上下文 先看 │
218
+ │ 01 ● 相关性排序算法 5分钟前 │
219
+ │ 标题命中:排序 │
220
+ │ │
221
+ │ 辅助上下文 辅助 │
222
+ │ 02 排序评测集 2小时前 │
223
+ │ 正文命中:关键词计数 │
224
+ │ │
225
+ │ 相关上下文 背景 │
226
+ │ 03 CHANGELOG.md 12天前 │
227
+ │ 正文命中:排序 │
228
+ └────────────────────────────────────────┘
229
+ ```
230
+
231
+ > 示意图省掉了每行的摘要。**真实的行结构是:最左边独立一列=序号(与右边第一行**垂直居中**),
232
+ > 右边堆叠=第一行「Primary 点 + 标题 + 相对时间(**靠右**)」→ 摘要(**没有路径** ——
233
+ > 列表行里不显示它,路径在预览头的面包屑上)。而且这个列表**永远是单列**(面板拖到多宽都一样)。
234
+
235
+ **分组之间不画横线**:层级靠 16px 的空间、组名与字号建立,不靠分割线。
236
+ 分组里没有分数、没有百分比、没有星级 —— 「为什么在这里」只写**确定性的事实**。
237
+
238
+ > **右侧那个「当前任务上下文」说明栏已经删掉了**(2026-09-29)。它说的和左侧三个分组是同一件事
239
+ > —— 当前任务就在列表上方那行弱化元信息里,「命中 N 篇」与头部总数重复,三条证据类型**就是**
240
+ > 三个组名;视觉价值有限,而且容易把 Knit 做成 AI Dashboard。随它一起删除的还有
241
+ > 「调宽 / 拖出浮动 / 右缘吸附」那一套(见 `CHANGELOG.md`)。
242
+
243
+ ### 分层是确定性规则,不是 AI 判断
244
+
245
+ | 层 | 什么时候进 | 上限 |
246
+ |---|---|---|
247
+ | **主要上下文** | 命中,**且**有「落脚点」(话题词命中标题或摘要),**且**相关度不是背景噪音(≥ 最高分的 30%) | 1 |
248
+ | **辅助上下文** | 对某个「焦点词」有**深入命中**(该词不止一篇在讲,而且这一篇是把它讲得最多的那一篇);**或**与某个主要上下文有引用关系(「被引用」/「引用了」,两个方向分别标注) | 3 |
249
+ | **相关上下文** | 其余**有命中**的条目,以及零命中但有引用关系的邻居 | 5 |
250
+
251
+ 上限是**上限,不是配额**:主要上下文允许为空(实测真实工作区上有相当比例的话题
252
+ 确实没有一篇文档在正经讲它),相关上下文也允许为空。**说不出的理由就不出场** ——
253
+ 零命中又没有任何引用关系的文档不是「与当前任务有关」,放它进来只能配一句
254
+ 「可能对你有帮助」,那是这一版明确不要的东西。
255
+
256
+ **「为什么在这里」**永远是一句可核验的事实:
257
+
258
+ | 理由 | 说的是什么 |
259
+ |---|---|
260
+ | 标题 / 摘要 / 正文命中当前话题:`词` | 真的命中了,而且告诉你命中了哪个词 |
261
+ | 被主要上下文引用 | 主文档里那条路径指过来的 —— 读主文档时你下一步就会点它 |
262
+ | 引用了主要上下文 | 它里面提到了主文档 |
263
+
264
+ **没有**「AI 判断这篇重要」「可能对你有帮助」这类句子,也**没有**百分比、星级、置信度条 ——
265
+ 理由要么是可核验的事实,要么干脆不写。
266
+
267
+ ### 边界(说清楚,不夸大)
268
+
269
+ - **引用关系不等于「更相关」。** 实测过:把引用图当排序信号补不上词面错配那个缺口。
270
+ 所以引用关系**只能**把一篇文档放进辅助 / 相关层,**永远不能**把它抬进主要上下文。
271
+ - **排序引擎本身没变。** 这一版加的是排序**之上**的一层投影 —— BM25 的打分、评测
272
+ (top-1 / MRR / 陷阱用例)一行没动。如果检索没把对的那篇找出来,分层也只能在
273
+ 找到的那几篇里分 —— 它救不了召回。
274
+ - **不做任务理解。** Context Pack 里那个「当前任务」字段放的是**最近一条用户消息的原文**,
275
+ 不是任何概括 —— Knit 不解一句话的意思,只是把它如实摆出来。真去概括需要模型,而 Knit 不调模型。
276
+
160
277
  ---
161
278
 
162
279
  ## 也给 agent 用:`knit_docs` 工具
@@ -164,19 +281,24 @@ dsh plugin --profile web add dsh-knit
164
281
  同一份排序,除了给你看,也开了一个口子给模型。
165
282
 
166
283
  装好之后,agent 的工具列表里会多一个 `knit_docs`:它可以问
167
- 「这个项目里跟当前话题最相关的文档是哪几篇」,拿到**按相关性排好序**的
168
- 路径 + 标题 + 摘要,再用它自己的 `read` 打开其中一篇。
284
+ 「这个项目里跟当前话题最相关的文档是哪几篇」,拿回**同一个 Context Pack** ——
285
+ `primary` / `supporting` / `related` 三层,每项带路径 + 标题 + 摘要 +
286
+ **结构化理由**(`direct` / `summaryMatch` / `bodyMatch` / `linkTarget` / `linkSource` / `related`)
287
+ + **项目角色**(`impl` / `test` / `config` / `design` / `doc`)+
288
+ 命中的那一小段原文,再用它自己的 `read` 打开其中一篇。
169
289
 
170
290
  **为什么有用**:agent 想引用项目里已有的文档时,只能靠猜路径、或者把 `glob`
171
- 出来的路径一个个 `read` 试过去 —— 费 token 又慢。而这份排序 Knit **每一轮已经算好了**,
172
- 这个工具只是把它交出去。
291
+ 出来的路径一个个 `read` 试过去。这份排序 Knit **每一轮已经算好了**,这个工具只是把它交出去 ——
292
+ 省掉的是**「先猜哪几篇相关」这一步判断**(实测:拿到包的 agent 不再需要 `glob` 去凑候选)。
173
293
 
174
294
  **只读,且不存储任何东西**:它读的是项目里**现成的文件**,不是「记忆」。
175
295
  和记忆类插件的区别是:**它们起点是空的**(agent 得先记过才有东西可召回),
176
296
  Knit 一装上就有整个项目的历史文档可用。
177
297
 
178
- 三个细节:
298
+ 四个细节:
179
299
 
300
+ - **给的是任务上下文,不是一条平铺列表**。面板与工具**共用同一个 Context Model** ——
301
+ 没有两套排序逻辑,也没有两份规则。
180
302
  - **不返回相关度分数**。它是**相对**分数(永远有一篇 100%,每次刷新可能换人当),
181
303
  给模型看会被当成绝对置信度去推理。**顺序即相关度** —— 与面板同一条规矩。
182
304
  - **不返回正文**。agent 有自己的 `read` 工具;Knit 负责**发现**,不负责**搬运**。
@@ -221,6 +343,15 @@ Knit 一装上就有整个项目的历史文档可用。
221
343
  - **媒体只认常见格式与大小**:图片 `png/jpg/jpeg/gif/webp/avif/bmp/ico/svg`、
222
344
  视频 `mp4/m4v/webm/mov/ogv`;图片 ≤ 12MB、视频 ≤ 256MB,超出不列出
223
345
  - **媒体只按文件名参与相关性匹配**:不解析画面 / 语音内容,截图与录屏建议用可检索的文件名
346
+ - **分层建立在召回之上**:如果 BM25 一篇都没把对的那篇捞进候选池,分层也只能在捞到的那几篇里分
347
+ —— 它救不了召回。词面错配(你问「图片和视频」,文档里写的是「媒体浏览」)就是这种情形
348
+ - **「当前任务上下文」只覆盖 Markdown**:面板的图片与视频两档、以及时间序模式都不分层
349
+ (那两档没有话题命中,就没有可解释的理由)。第一版也不解析 PDF / DOCX / 源码
350
+ - **引用关系只当上下文信号**:它能把文档放进辅助 / 相关层,**不会**把任何文档抬进主要上下文
351
+ - **测到的是「定位」,不是「省力」**:真机对照实验(冻结协议,四道题)里,能调 `knit_docs`
352
+ 的 agent 总探索次数**没有下降** —— Control 4.75 → Treatment 6.0,四题逐题无一变少。
353
+ 包确实替掉了「先 `glob` 找候选」那一步,但省下的被**翻倍的 `read`** 吃了回去:
354
+ 它把注意力指向了正确的文件,**不等于** agent 少读几次文件
224
355
  - **右侧栏状态是 memory-only**:刷新或新会话会回到收起状态
225
356
 
226
357
  ---
@@ -231,7 +362,7 @@ Knit 一装上就有整个项目的历史文档可用。
231
362
  git clone https://github.com/PolinniZhong/dsh-knit.git
232
363
  cd dsh-knit
233
364
 
234
- npm test # 215 项,零依赖,不需要先 npm install
365
+ npm test # 395 项,零依赖,不需要先 npm install
235
366
  ```
236
367
 
237
368
  **改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
@@ -248,12 +379,15 @@ knit/
248
379
  ├── cordis.patch.yml # 挂进 plugin tree 的 insert 行
249
380
  ├── assets/ # 图标源文件(path 已内联进 client.js)
250
381
  ├── src/
251
- │ ├── host/index.js # /knit/api/recent · /doc · /raw
382
+ │ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
252
383
  │ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
384
+ │ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
385
+ │ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
253
386
  │ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
254
387
  │ └── client/client.js # 双宿主注册 + 面板 UI
255
- └── test/ # 215 项测试
256
- └── eval/ # 离线质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
388
+ └── test/ # 395 项测试
389
+ ├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
390
+ └── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
257
391
  ```
258
392
 
259
393
  细节和取舍写在源码注释里;贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-knit",
3
- "version": "0.13.0",
3
+ "version": "0.14.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",
@@ -14,6 +14,7 @@
14
14
  "assets",
15
15
  "src",
16
16
  "test",
17
+ "tools/json-schema-subset.mjs",
17
18
  "cordis.patch.yml",
18
19
  "CHANGELOG.md",
19
20
  "README.md",
@@ -21,7 +22,7 @@
21
22
  "LICENSE"
22
23
  ],
23
24
  "scripts": {
24
- "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"
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"
25
26
  },
26
27
  "dsh": {
27
28
  "bundle": {
@@ -47,6 +48,8 @@
47
48
  "right-sidebar",
48
49
  "recent-files",
49
50
  "relevance",
51
+ "context-pack",
52
+ "task-context",
50
53
  "knowledge-base",
51
54
  "images",
52
55
  "video",