dsh-knit 0.14.0 → 0.16.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 +279 -0
- package/README.en.md +81 -23
- package/README.md +71 -20
- package/package.json +3 -2
- package/src/client/client.js +237 -98
- package/src/host/feedback.js +858 -0
- package/src/host/index.js +171 -7
- package/src/host/tool.js +63 -3
- package/test/client.test.mjs +279 -31
- package/test/context-delta.test.mjs +322 -0
- package/test/context-effectiveness.test.mjs +309 -0
- package/test/context-feedback-eval.test.mjs +220 -0
- package/test/feedback.test.mjs +247 -0
- package/test/host-http.test.mjs +249 -3
- package/test/i18n.test.mjs +22 -23
- package/test/path.test.mjs +6 -6
- package/test/peek.test.mjs +80 -26
- package/test/tool.test.mjs +132 -5
- package/tools/context-feedback-eval.mjs +362 -0
package/README.md
CHANGED
|
@@ -7,14 +7,19 @@
|
|
|
7
7
|
|
|
8
8
|

|
|
9
9
|
|
|
10
|
-
*真机截图(不是原型):一个含
|
|
10
|
+
*真机截图(不是原型):一个含 51 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
|
|
11
11
|
*引用条是 v0.12 加的:展开就能看到「这篇被谁引用」,点一项直接跳过去。*
|
|
12
12
|
*顶行会跟着你正在聊什么变;对话内容还不足时它退回按时间排,并如实说明依据。*
|
|
13
|
+
*v0.14 起文档列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
|
|
14
|
+
*Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
|
|
15
|
+
*序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
|
|
16
|
+
*空着会被读成「漏了一个号」(2026-10-01)。*
|
|
13
17
|
|
|
14
18
|

|
|
15
19
|
|
|
16
|
-
|
|
17
|
-
|
|
20
|
+
*排序跟着对话走(同一个工作区、刚新开一个会话):还没聊什么时,顶行如实写着「对话内容还不足,暂按最新排序」,*
|
|
21
|
+
*列表按时间排;问一句「排序算法用的 BM25 是怎么加权的?」,顶上立刻换成排序那几篇 ——*
|
|
22
|
+
*序号与「主要上下文 / 辅助上下文 / 相关上下文」三层随之一起出现(跨三档连续编号)。*
|
|
18
23
|
*⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
|
|
19
24
|
|
|
20
25
|
扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
|
|
@@ -161,7 +166,7 @@ dsh plugin --profile web add dsh-knit
|
|
|
161
166
|
| 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
|
|
162
167
|
| 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
|
|
163
168
|
| 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
|
|
164
|
-
| 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** ——
|
|
169
|
+
| 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径**重复,只保留后者 | ✅ |
|
|
165
170
|
| 单击就地展开预览,再点收起 | ✅ |
|
|
166
171
|
| 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
|
|
167
172
|
| **文档 / 图片与视频 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边 | ✅ |
|
|
@@ -169,11 +174,11 @@ dsh plugin --profile web add dsh-knit
|
|
|
169
174
|
| 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
|
|
170
175
|
| 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
|
|
171
176
|
| 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出 | ✅ |
|
|
172
|
-
|
|
|
177
|
+
| **「本地打开」**:用系统默认应用打开当前预览的这篇文档(预览头的路径同样可点,完整路径在悬停提示里) | ✅ |
|
|
173
178
|
| 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
|
|
174
179
|
| 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
|
|
175
180
|
| **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
|
|
176
|
-
| **悬停入口按钮偷看**:弹只读浮层列最近 5
|
|
181
|
+
| **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局;浮层只有「头 + 列表」,没有多余的横线与提示语) | ✅ |
|
|
177
182
|
| 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc` 收起;**媒体档** `←` `→` 按屏幕位置跨行,`Home` / `End` 到首尾(文档档永远单列,`←` `→` 没有空间含义) | ✅ |
|
|
178
183
|
| 每 5 秒自动刷新 + 手动刷新;2 分钟内改动过的文档打 🆕 | ✅ |
|
|
179
184
|
| 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
|
|
@@ -184,21 +189,20 @@ dsh plugin --profile web add dsh-knit
|
|
|
184
189
|
|
|
185
190
|
### 另外两档长什么样
|
|
186
191
|
|
|
187
|
-

|
|
188
193
|
|
|
189
194
|
*图片与视频:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
|
|
190
|
-
|
|
191
|
-
|
|
195
|
+
*列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图和两个单色 SVG 图标,*
|
|
196
|
+
*所以看起来像一屏文件缩略图(那两个纯黑方块就是那两个图标本身)。视频会取首帧当海报、*
|
|
197
|
+
*中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
|
|
192
198
|
|
|
193
|
-

|
|
194
200
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
而且**路径不再出现在列表行里**(预览头的面包屑始终显示完整路径,重复的那份删掉了),
|
|
201
|
-
截图尚未重拍。
|
|
201
|
+
*全部:文档区最多 4 条,超出时右侧给「查看全部 →」(这一屏是「4 / 40」)。*
|
|
202
|
+
*⚠️ **这一屏没有媒体区,而且不是排版问题** —— 宿主为「全部」档取的是 **40 条窗口**:这个工作区*
|
|
203
|
+
*51 篇文档 + 8 个媒体,媒体按相关性排在第 50–58 位、整段被挤出窗口,于是客户端的*
|
|
204
|
+
*`visibleDocs.filter(isMedia)` 恒为空、媒体区整个不渲染。**文档数 ≥ 40 的工作区都会这样**,*
|
|
205
|
+
*这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
|
|
202
206
|
|
|
203
207
|
---
|
|
204
208
|
|
|
@@ -230,7 +234,9 @@ Context Pack 是对这个问题的回答,但它是**数据层的结构**(主
|
|
|
230
234
|
|
|
231
235
|
> 示意图省掉了每行的摘要。**真实的行结构是:最左边独立一列=序号(与右边第一行**垂直居中**),
|
|
232
236
|
> 右边堆叠=第一行「Primary 点 + 标题 + 相对时间(**靠右**)」→ 摘要(**没有路径** ——
|
|
233
|
-
>
|
|
237
|
+
> 列表行里不显示它,路径在预览头上、目录收敛成 `…/`)。而且这个列表**永远是单列**(面板拖到多宽都一样)。
|
|
238
|
+
> 「其他相关文档」不在包里、不编号,那一列放一个中性的 `·` 占位 —— 但只在**这一屏里有号**时才放
|
|
239
|
+
> (时间序 / 平铺列表整屏没号 ⇒ 一个标记都没有;混着才刺眼)。
|
|
234
240
|
|
|
235
241
|
**分组之间不画横线**:层级靠 16px 的空间、组名与字号建立,不靠分割线。
|
|
236
242
|
分组里没有分数、没有百分比、没有星级 —— 「为什么在这里」只写**确定性的事实**。
|
|
@@ -311,11 +317,55 @@ Knit 一装上就有整个项目的历史文档可用。
|
|
|
311
317
|
|
|
312
318
|
---
|
|
313
319
|
|
|
320
|
+
## 它有没有被用上(v0.16)
|
|
321
|
+
|
|
322
|
+
Knit 会排出「现在最该先看的几篇」,但**排得对不对,过去只能靠感觉**。
|
|
323
|
+
v0.15 起有一层**可核验的使用反馈**:把 agent 真实读过的文件,跟**读发生那一刻**生效的那份上下文对起来。
|
|
324
|
+
v0.16 把这件事钉死:**归因在读发生那一刻结算并冻结** —— 之后上下文怎么换,历史数字都不会改口
|
|
325
|
+
(v0.15 里同一个读会被「现在」重判成包外,那是 bug)。
|
|
326
|
+
|
|
327
|
+
**默认关。** 面板头部有一个「使用情况」开关,打开之后列表上方会多一行字:
|
|
328
|
+
|
|
329
|
+
```
|
|
330
|
+
当前上下文 · Epoch 4 · 先看的「docs/xxx.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
- **Context Epoch**:一份**内容有变化**的上下文 = 一个 Epoch(内容没变就不新建,轮询不会灌进几十个)。
|
|
334
|
+
`Epoch 4` 是累计编号,不是「第几份包」。
|
|
335
|
+
- **两个只记事实的字段**:`continuedReadAfterExit`(离开这份上下文之后它仍然被读)、
|
|
336
|
+
`reEntry`(离开过、又回到包里、又被读)。它们**不许**被读成「Agent 不认可新上下文」——
|
|
337
|
+
那是推断,不是事实。
|
|
338
|
+
|
|
339
|
+
它只报**事实**:先看的那篇被读了没有、读了几次、多少篇落在包外、上下文换过几回。
|
|
340
|
+
**没有分数、没有百分比、没有进度条** —— 这些数字不是估算出来的,是数出来的。
|
|
341
|
+
|
|
342
|
+
三条边界:
|
|
343
|
+
|
|
344
|
+
- **默认关闭**:不打开就**不统计任何东西**(Knit 订阅宿主事件流,但回调第一行就按会话早退,
|
|
345
|
+
没开审计的会话只花一次 Map 查找)。这笔账该由你决定要不要付。
|
|
346
|
+
- **不重复 DSH 的轨迹**:证据只有一个来源 —— 会话事件流里**已经存在**的 `tool/call` /
|
|
347
|
+
`tool/result` 事件(成功的 `read`)。**没有新的事件总线、没有 Runtime Trace、也没有 Event Store。**
|
|
348
|
+
- **只从现在开始**:订阅是 v0.16 唯一的读证据来源(旧的 `session.snapshotEvents()` 已被 DSH
|
|
349
|
+
标为 deprecated),所以**打开开关之前发生的读不会回补** —— 那一刻起才开始计数。
|
|
350
|
+
- **不落盘**:数据只在宿主内存里,重启 DSH 就没了,**别把它当长期统计**。
|
|
351
|
+
|
|
352
|
+
agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工具结果末尾会多一行
|
|
353
|
+
`Usage since the last pack: …`(报的是**上一份**包)。
|
|
354
|
+
|
|
355
|
+
想离线核对:`node tools/context-feedback-eval.mjs` 回放最近一份真实会话日志,
|
|
356
|
+
`--control` 是「一份包都不交」的对照组。⚠️ 它把「包外」拆成两半 ——
|
|
357
|
+
**Knit 索引里有、却没进包**(真漏)与**压根不在索引里**(`.js` / `.json`,Knit 本来就不索引这些);
|
|
358
|
+
不拆开的话包外比例恒高,读起来像「Context Pack 没用」,其实是**量错了东西**。
|
|
359
|
+
|
|
360
|
+
---
|
|
361
|
+
|
|
314
362
|
## 它读什么,不读什么
|
|
315
363
|
|
|
316
364
|
- 扫描**当前会话工作区内**的 `.md`、图片与视频(路径越出工作区一律拒绝);媒体只取元信息,不读画面内容
|
|
317
365
|
- 只读**当前会话**的对话事件(用来排序)
|
|
318
366
|
- `knit_docs` 工具**只读**:不写任何文件、不落盘任何索引
|
|
367
|
+
- v0.15 的「使用情况」**默认关**:打开后也只读**当前会话已有**的工具事件(成功的 `read`),
|
|
368
|
+
同样不写任何文件、不落盘任何计数,重启即失
|
|
319
369
|
- **不发起任何对外网络请求**:客户端的 `fetch` 都指向插件自己的同源路由
|
|
320
370
|
- **没有安装期脚本**(无 `install` / `postinstall`)
|
|
321
371
|
- **零依赖** —— 装完不需要构建授权,也没有构建步骤
|
|
@@ -362,7 +412,7 @@ Knit 一装上就有整个项目的历史文档可用。
|
|
|
362
412
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
363
413
|
cd dsh-knit
|
|
364
414
|
|
|
365
|
-
npm test #
|
|
415
|
+
npm test # 468 项,零依赖,不需要先 npm install
|
|
366
416
|
```
|
|
367
417
|
|
|
368
418
|
**改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
|
|
@@ -383,9 +433,10 @@ knit/
|
|
|
383
433
|
│ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
|
|
384
434
|
│ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
|
|
385
435
|
│ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
|
|
436
|
+
│ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
|
|
386
437
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
387
438
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
388
|
-
└── test/ #
|
|
439
|
+
└── test/ # 468 项测试
|
|
389
440
|
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
|
|
390
441
|
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
391
442
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.16.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 test/context-effectiveness.test.mjs"
|
|
26
27
|
},
|
|
27
28
|
"dsh": {
|
|
28
29
|
"bundle": {
|