dsh-knit 0.18.0 → 0.19.1
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 +229 -7
- package/README.en.md +291 -180
- package/README.md +248 -112
- package/SECURITY.md +4 -3
- package/package.json +9 -4
- package/src/client/client.js +451 -47
- package/src/host/classification.js +250 -0
- package/src/host/context.js +31 -9
- package/src/host/index.js +336 -77
- package/src/host/tool.js +29 -13
- package/test/classification.test.mjs +237 -0
- package/test/client.test.mjs +431 -3
- package/test/code-context.test.mjs +567 -0
- package/test/eval/fixture.mjs +309 -6
- package/test/eval.test.mjs +117 -1
- package/test/host.test.mjs +63 -3
- package/test/path.test.mjs +97 -5
- package/test/tool.test.mjs +23 -15
package/README.md
CHANGED
|
@@ -1,15 +1,45 @@
|
|
|
1
1
|
# Knit
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
> Knit 把它们放到对话旁边 —— 你正在聊什么,相关的那篇就在最上面。
|
|
3
|
+
> **面向 AI Coding Agent 的任务感知工作区上下文检索与生命周期追踪。**
|
|
5
4
|
>
|
|
6
|
-
>
|
|
5
|
+
> Task-aware workspace context retrieval and lifecycle tracking for AI coding agents.
|
|
6
|
+
|
|
7
|
+
Knit 接的是**当前任务**和**整个工作区**之间那一层:从工作区里找出最相关的文档、源码与媒体,
|
|
8
|
+
组织成 **主要 / 辅助 / 相关** 三层上下文(Context Pack),交给面板、也交给 agent;
|
|
9
|
+
再持续追踪这些上下文**有没有被读、被读之后有没有变**。
|
|
10
|
+
|
|
11
|
+
**找到 → 组织 → 追踪**,三步都在本机用字符串运算完成 —— 不调模型、不联网、零延迟、内容不出本机。
|
|
12
|
+
|
|
13
|
+
```text
|
|
14
|
+
当前任务
|
|
15
|
+
│
|
|
16
|
+
工作区检索
|
|
17
|
+
┌────────────┼────────────┐
|
|
18
|
+
▼ ▼ ▼
|
|
19
|
+
主要上下文 辅助上下文 相关上下文
|
|
20
|
+
└────────────┼────────────┘
|
|
21
|
+
▼
|
|
22
|
+
Context Pack ──► `knit_docs` 工具(给 agent)
|
|
23
|
+
▼
|
|
24
|
+
Agent 读取
|
|
25
|
+
▼
|
|
26
|
+
读取证据 · Context Epoch
|
|
27
|
+
▼
|
|
28
|
+
工作区发生变化
|
|
29
|
+
▼
|
|
30
|
+
重新读取 · 生命周期
|
|
31
|
+
```
|
|
7
32
|
|
|
8
|
-
|
|
33
|
+
> **它不是「更聪明的最近文件列表」,也不是「代码浏览器」。**
|
|
34
|
+
> 最近文件记的是「你点开过什么、哪个更新」;Knit 回答的是
|
|
35
|
+
> **当前这个任务,项目里哪些东西最值得先看 —— 以及看过之后,事情变成了什么样。**
|
|
9
36
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
37
|
+

|
|
38
|
+
|
|
39
|
+
*真机截图(不是原型):同一个工作区,这张停在 **「代码」档** —— v0.19 起,源码和 Markdown 一样是一等公民。*
|
|
40
|
+
*每行下面的「为什么」写着它是怎么被命中的(`直接命中:knit · readme` / `路径命中:knit · path` / `直接命中:knit · 工作区`)。*
|
|
41
|
+
*点一行**就地**展开预览:这里是 `knit/src/host/classification.js`,带行号;预览头里只有路径和四个动作(复制 / 全屏 / 本地打开 / 关闭)。*
|
|
42
|
+
*头部只放路径、一个计数与两个开关;列表按「相关」还是「最新」排,由左边那一对页签决定 —— 按「相关」时排的就是你正在聊什么。*
|
|
13
43
|
*v0.14 起文档列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
|
|
14
44
|
*Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
|
|
15
45
|
*序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
|
|
@@ -23,7 +53,7 @@
|
|
|
23
53
|
*这一屏里没有文档落进主要层,所以分组从「辅助上下文」开始。*
|
|
24
54
|
*⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
|
|
25
55
|
|
|
26
|
-
|
|
56
|
+
扫整个项目文件夹的文档 / 代码 / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
|
|
27
57
|
|
|
28
58
|
```sh
|
|
29
59
|
dsh plugin --profile web add dsh-knit
|
|
@@ -31,93 +61,47 @@ dsh plugin --profile web add dsh-knit
|
|
|
31
61
|
|
|
32
62
|
---
|
|
33
63
|
|
|
34
|
-
##
|
|
35
|
-
|
|
36
|
-
**是的,但有两个关键区别:**
|
|
37
|
-
|
|
38
|
-
1. **范围**:最近打开列表只记你**点开过**的文件;Knit 扫**整个项目文件夹**。
|
|
39
|
-
重启 DSH、新开会话、跨天回来,它都还在。
|
|
40
|
-
2. **排序**:它按时间排;Knit 按**你正在聊什么**排。
|
|
41
|
-
|
|
42
|
-
三句话说完它是什么:
|
|
43
|
-
|
|
44
|
-
1. 扫**整个项目文件夹**的 Markdown,不只是这一轮生成的那几篇 —— 重启、换会话、跨天都还在
|
|
45
|
-
2. 排序**跟着你正在聊什么走**:聊架构,架构文档浮上来;聊竞品,竞品分析浮上来
|
|
46
|
-
3. **不调模型、不联网**:全是本地字符串运算,零延迟、零成本、文档不出本机
|
|
47
|
-
|
|
48
|
-
---
|
|
49
|
-
|
|
50
|
-
## 「相关」是怎么算出来的
|
|
51
|
-
|
|
52
|
-
没有玄学,就是字符串运算。三步:
|
|
53
|
-
|
|
54
|
-
**1. 读当前会话。** 取最近 6 条用户 / 助手消息,只认真人输入的用户消息
|
|
55
|
-
(`agent.inject()` 塞进来的合成上下文不算,那会把话题带偏)。越新的消息权重越高:3 / 2 / 1 / 1 …
|
|
56
|
-
|
|
57
|
-
**2. 抽关键词。**
|
|
58
|
-
|
|
59
|
-
- **英文词**:取值很高,出现 1 次就要(`chokidar`、`mtime` 这种精确词)
|
|
60
|
-
- **中文 2/3-gram**:出现 2 次,或出现在最新那条消息里
|
|
61
|
-
- **丢掉跨词边界的碎片**:中文没有词边界,n-gram 会把相邻两个词的字粘起来
|
|
62
|
-
(「图片和」「个插」「的排」)。这类碎片有个共同特征 —— **首字或尾字是纯虚词**,
|
|
63
|
-
一律丢掉。不丢的话它们会占满候选位,把「图片」「排序」这些真词全挤出去
|
|
64
|
-
- 虚词表过滤 + 贪心去重叠(选了「相关性排序」就不再算「相关性」和「排序」)
|
|
64
|
+
## 为什么需要它
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
> Agent 一天产出 20 篇文档,你找不到刚才那篇。
|
|
67
67
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
再按字段加权求和:标题 ×4 + 摘要 ×2 + 正文前 2500 字 ×1
|
|
71
|
-
每个字段都按 BM25 饱和 + 长度归一化(k1 = 1.2,b = 0.3 / 0.5 / 0.75)
|
|
72
|
-
再叠 10% 的时间新鲜度微调(主排序仍是相关性)
|
|
73
|
-
```
|
|
68
|
+
这是它最开始要解决的问题:**产出速度超过了人翻目录的速度**。
|
|
69
|
+
DSH 自带的「最近文件」只记你点开过什么;一轮对话结束,前面那几篇就沉下去了。
|
|
74
70
|
|
|
75
|
-
|
|
71
|
+
Knit 换了个问法:**不看「谁新」,看「和现在这件事有多相关」**。
|
|
72
|
+
它扫的是**整个工作区**(不是这一轮生成的那几篇),按你正在聊的内容排序 ——
|
|
73
|
+
重启 DSH、换会话、跨天回来,它都还在。
|
|
76
74
|
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
- 命中次数封顶 6 次是个手写硬拐点;`k1` / `b` 才是为这件事设计的
|
|
75
|
+
后来问题往前长了一步:真要动一个功能时,最该先看的往往不是文档,而是**那几行源码**。
|
|
76
|
+
v0.19 起代码进了同一条链路。再往后,「排在前面」也不够用了 ——
|
|
77
|
+
**排出来的那些,agent 到底读了没有?读完改过没有?** v0.15–v0.18 补的就是这一层。
|
|
81
78
|
|
|
82
|
-
|
|
79
|
+
三句话:**找到**(扫全工作区、按当前任务排序)→ **组织**(主要 / 辅助 / 相关三层 + 每条的理由)
|
|
80
|
+
→ **追踪**(读了没有、读完变了没有)。
|
|
83
81
|
|
|
84
|
-
|
|
85
|
-
|---|---|---|
|
|
86
|
-
| 旧做法(加权命中) | 76.2% | 0.830 |
|
|
87
|
-
| **BM25** | **95.2%** | **0.976** |
|
|
82
|
+
---
|
|
88
83
|
|
|
89
|
-
|
|
90
|
-
所以「新引擎必须显著更好」是自动验证的,而不是引用一个写死的数字。
|
|
84
|
+
## 「最近文件列表」和「代码浏览器」都不是它
|
|
91
85
|
|
|
92
|
-
|
|
93
|
-
语料刻意做成有真实陷阱的 —— 12 篇短而聚焦的主题文档,加上一堆「每条主题各提 5 次、
|
|
94
|
-
但哪一件都没讲」的长干扰文档(真实项目里的 CHANGELOG 就长这样)。
|
|
95
|
-
主题文档一半用描述性文件名,一半看不出内容。
|
|
86
|
+
这两个类比各自只说中 Knit 的一个**表层形态**,说不到它回答的问题。
|
|
96
87
|
|
|
97
|
-
|
|
|
88
|
+
| | 最近文件列表 | 代码浏览器 | **Knit** |
|
|
98
89
|
|---|---|---|---|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
90
|
+
| 范围 | 你点开过的 | 一棵目录树 | **整个工作区**:文档 / 代码 / 图片 / 视频 |
|
|
91
|
+
| 排序 | 修改时间 | 你自己翻 | **当前任务的相关性**(BM25 + IDF,本地算) |
|
|
92
|
+
| 输出 | 一条平铺列表 | 你打开的那一个文件 | **主要 / 辅助 / 相关** 三层,每条都写明为什么在这里 |
|
|
93
|
+
| 给谁 | 你 | 你 | 你**和** agent —— 同一份 Context Pack,走 `knit_docs` |
|
|
94
|
+
| 之后 | 不管 | 不管 | **读了没有 / 读完变了没有**(读取证据 + 生命周期) |
|
|
102
95
|
|
|
103
|
-
|
|
104
|
-
**文件名匹配只在名字描述内容时好使**,Knit 是唯一两种都 100% 的;
|
|
105
|
-
**自己数的可靠性随规模单调下降**。
|
|
96
|
+
三条最要紧的区别:
|
|
106
97
|
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
全是字符串运算 —— **没有 embedding,没有模型调用**。
|
|
113
|
-
|
|
114
|
-
**并且老实说边界**:
|
|
98
|
+
1. **范围**:最近打开列表只记你**点开过**的文件;Knit 扫**整个项目文件夹** ——
|
|
99
|
+
重启 DSH、新开会话、跨天回来,它都还在。
|
|
100
|
+
2. **排序**:它按时间排;Knit 按**你正在聊什么**排 ——
|
|
101
|
+
聊架构,架构文档浮上来;聊 loader 的 bug,`plugin-loader.ts` 浮上来。
|
|
102
|
+
3. **它不止于「找」**:找完还要**组织**(三层 + 可核验的理由)和**追踪**(哪些真被读了、读完有没有变)。
|
|
115
103
|
|
|
116
|
-
|
|
117
|
-
- **语料只有三五篇时 IDF 几乎不起作用**:`df` 的取值范围太窄,动态范围被压扁。
|
|
118
|
-
文档越多这个排序越准 —— 这正是它该有的样子
|
|
119
|
-
- **它只能排「和对话有共同词汇」的文档**:如果一个词都没命中,所有文档同分,
|
|
120
|
-
名次就退化成按时间排
|
|
104
|
+
**不调模型、不联网**:全是本地字符串运算,零延迟、零成本、内容不出本机。
|
|
121
105
|
|
|
122
106
|
---
|
|
123
107
|
|
|
@@ -141,22 +125,6 @@ dsh plugin --profile web add dsh-knit
|
|
|
141
125
|
|
|
142
126
|
---
|
|
143
127
|
|
|
144
|
-
## 反馈
|
|
145
|
-
|
|
146
|
-
**这个项目当前的重心不是加功能,是搞清楚「按对话给文档排序」这件事到底有没有人在用。**
|
|
147
|
-
所以最有价值的一句话不是「能不能加个 XX」,而是**你现在是怎么绕过它的** ——
|
|
148
|
-
哪怕结论是「装了,但一周没打开过」,也请直说,那比一个功能建议有用得多。
|
|
149
|
-
|
|
150
|
-
- 💬 [说说你在什么场景下会打开它](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) —— 两步、三十秒,不必客气
|
|
151
|
-
- 🐞 [装不上 / 面板打不开 / 排得不对](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
|
|
152
|
-
- 📖 提之前先看一眼[已知限制](#已知限制) —— 短对话退化、中文用 n-gram 近似,这几条是已知的取舍,不是 bug
|
|
153
|
-
|
|
154
|
-
> 一条 issue 会被当成真实信号处理。这个插件到现在**一个真实用户的痕迹都没有**
|
|
155
|
-
> (npm 那个下载量是自动化版本枚举、不是人 —— `latest` 占比只有 14%,而真人只会装 `latest`)
|
|
156
|
-
> —— 一条有人味儿的反馈能直接改变接下来做什么。
|
|
157
|
-
|
|
158
|
-
---
|
|
159
|
-
|
|
160
128
|
## 功能
|
|
161
129
|
|
|
162
130
|
| 能力 | |
|
|
@@ -166,18 +134,22 @@ dsh plugin --profile web add dsh-knit
|
|
|
166
134
|
| **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
|
|
167
135
|
| **文档生命周期**(v0.17):每篇推荐文档现在处于 `未读 / 已读 / 读后已更新 / 修改后已重新读取` 哪一档,另外给出最近读了哪篇、包外读了哪几篇、上下文最近一次怎么变 | ✅ |
|
|
168
136
|
| 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
|
|
169
|
-
| 扫描会话工作区里的 `.md
|
|
137
|
+
| 扫描会话工作区里的 `.md` 与上表那批代码后缀(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist` / `build` / `out` / `coverage` …) | ✅ |
|
|
138
|
+
| **生成 / 噪声产物不进检索**:`.map`、`*.min.js`、`*.min.css`、`*.bundle.js`、`*.generated.js`、`*.gen.js`、`*.lock`、`package-lock.json` —— 你能打开它们看,但它们**不会**成为主要 / 辅助 / 相关上下文 | ✅ |
|
|
139
|
+
| 代码预览:行号 + 等宽 + 横向滚动 + 复制 + 「本地打开」;同名 `app.js.map` 存在时预览页脚多一个低权重「Source map」入口(点开按纯文本看,`.map` 本身不进上下文) | ✅ |
|
|
170
140
|
| 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
|
|
171
141
|
| 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径**重复,只保留后者 | ✅ |
|
|
172
142
|
| 单击就地展开预览,再点收起 | ✅ |
|
|
173
143
|
| 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
|
|
174
|
-
|
|
|
144
|
+
| **代码上下文**(v0.19):`.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm .css .scss .yaml .yml .sh .bash .zsh` 与 Markdown **进同一个检索池**,共用同一份 BM25、同一个 Context Pack、同一套生命周期 —— 不是第二套「代码搜索」 | ✅ |
|
|
145
|
+
| **文档 / 代码 / 媒体 / 全部** 四类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边(页签「媒体」2026-10-06 由「图片与视频」改短,「代码」v0.19 加入) | ✅ |
|
|
175
146
|
| 图片与视频:方形缩略图网格,**格子基准固定 104px、列数由宽度连续数出来**(320px → 2 列 / 632px → 5 列 / 1200px → 10 列),格子大小基本不变;**纵向有多少行就铺多少行**,超出交给列表滚动;视频自动取首帧、叠播放三角与时长角标(零依赖、不转码) | ✅ |
|
|
176
147
|
| 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
|
|
177
148
|
| 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
|
|
178
|
-
| 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc`
|
|
179
|
-
|
|
|
149
|
+
| 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出;**全屏时头部 / 排序条 / 类型档 / 使用情况 / 列表全部让位**,预览铺满整个面板 | ✅ |
|
|
150
|
+
| **「本地打开」**:用系统默认应用打开当前预览的这篇文档;**预览头那条路径点开的是它「所在的文件夹」并顺带选中这个文件**(reveal,macOS 是 Finder 里 `open -R`;与顶部那行工作区路径同一套机制,差别只在「打开目录」vs「定位到文件」,完整相对路径在悬停提示里) | ✅ |
|
|
180
151
|
| 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
|
|
152
|
+
| **HTML 的「网页预览」**(v0.19 追加):预览头只对 `.html` / `.htm` 多一个按钮,点了在官方文档预览标签页里**按网页渲染** —— 那一侧是 DSH 自带的 HTML 渲染器(默认静态档:清洗过的文档 + 不给 sandbox 权限的 iframe + CSP 挡脚本 / 外部资源 / 表单 / 嵌套框架,内联 `<style>` 与 `data:` 图片保留)。就地预览给的是**源码**,两者不重复;其余代码类型不给这个按钮 | ✅ |
|
|
181
153
|
| 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
|
|
182
154
|
| **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
|
|
183
155
|
| **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局;浮层只有「头 + 列表」,没有多余的横线与提示语) | ✅ |
|
|
@@ -193,16 +165,17 @@ dsh plugin --profile web add dsh-knit
|
|
|
193
165
|
|
|
194
166
|

|
|
195
167
|
|
|
196
|
-
*媒体:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约
|
|
168
|
+
*媒体:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 110px。*
|
|
197
169
|
*列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图、一张演示动图和一个*
|
|
198
170
|
*单色 SVG 图标,所以看起来像一屏文件缩略图(那个纯黑方块就是图标本身,不是加载失败)。*
|
|
199
171
|
*视频会取首帧当海报、中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
|
|
200
172
|
|
|
201
|
-

|
|
202
174
|
|
|
203
|
-
|
|
204
|
-
*⚠️
|
|
205
|
-
|
|
175
|
+
*全部:**文档区最多 4 条**、**代码区最多 4 条**(超出时各区右侧给「查看全部 →」,这一屏是「4 / 19」与「4 / 17」),最后是媒体网格。*
|
|
176
|
+
*⚠️ 三个区共用宿主返回的**同一个 40 条窗口**:某一类如果按相关性排到第 40 名之外,「全部」档就整个看不到它。*
|
|
177
|
+
*这张图用的是**「最新」排序** —— 在这个工作区里,默认的「相关」排序下媒体恒定掉在 40 条窗口之外*
|
|
178
|
+
*(`limit=40` 时那 40 条全是 34 篇文档 + 6 个代码文件)。**「媒体」/「代码」档不受影响**,它们各自单独取。*
|
|
206
179
|
*这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
|
|
207
180
|
|
|
208
181
|
---
|
|
@@ -283,6 +256,71 @@ Context Pack 是对这个问题的回答,但它是**数据层的结构**(主
|
|
|
283
256
|
|
|
284
257
|
---
|
|
285
258
|
|
|
259
|
+
## 代码上下文(v0.19)
|
|
260
|
+
|
|
261
|
+
上面这一整套(检索 → 三层 Context Pack → 读取证据 → 生命周期 → 上下文变化 → 使用情况)
|
|
262
|
+
v0.19 起**同样适用于代码**。没有第二条链路:代码文件走的是**同一个** BM25、**同一个** Context Pack、
|
|
263
|
+
**同一套** Read Evidence 与生命周期。
|
|
264
|
+
|
|
265
|
+
**为什么加了代码是有意义的。** 一个真实任务(「改 plugin loader,让它支持新的 plugin metadata」)
|
|
266
|
+
最该先看的往往不是某篇文档,而是 `plugin-loader.ts` 本身。v0.18 之前 Knit 扫不到它 ——
|
|
267
|
+
面板里只有 Markdown,agent 也只能靠 `glob` 猜路径。
|
|
268
|
+
|
|
269
|
+
### 第一批支持的后缀(严格限定)
|
|
270
|
+
|
|
271
|
+
```
|
|
272
|
+
.js .mjs .cjs .ts .tsx .jsx .py .json
|
|
273
|
+
.html .htm .css .scss .yaml .yml
|
|
274
|
+
.sh .bash .zsh
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
**明确不支持**(这一版刻意不做):`.go .rs .java .kt .c .cpp .h .hpp .cs .php .rb .swift .sql`。
|
|
278
|
+
|
|
279
|
+
为什么不一次全上:这一版要验证的命题是「**把当前任务真正需要的代码纳入上下文有没有用**」,
|
|
280
|
+
不是「支持了多少种语言」。范围越小,「没用」这个结论越可信。
|
|
281
|
+
|
|
282
|
+
### 代码的排序字段与 Markdown 不同
|
|
283
|
+
|
|
284
|
+
代码没有「标题 / 摘要 / 正文」这套结构,硬套会把文件名这个**最强的信号**降权。所以代码条目:
|
|
285
|
+
|
|
286
|
+
| 字段 | 权重 | 放什么 |
|
|
287
|
+
|---|---|---|
|
|
288
|
+
| `filename` | ×4 | `context-manager.ts` —— 文件名本身就带任务语义 |
|
|
289
|
+
| `path` | ×2 | `src/context/` —— 目录名是第二层信号 |
|
|
290
|
+
| `content` | ×1 | 文件**前 8 KB**(不是全文,见下) |
|
|
291
|
+
|
|
292
|
+
Markdown 仍是 `title ×4 / summary ×2 / body ×1`。**两套字段权重,同一个 BM25。**
|
|
293
|
+
|
|
294
|
+
### 有边界的三件事(都实测过)
|
|
295
|
+
|
|
296
|
+
- **正文有界**:代码只读前 8 KB 进语料。不是为了省磁盘,是为了让扫描时间与检索延迟
|
|
297
|
+
不随「项目里有多少 JS」线性爆炸。
|
|
298
|
+
- **候选有上限**:代码准入上限 **300 个**(Markdown 仍是 400)。
|
|
299
|
+
这个数字是**量过真实工作区**才定的 —— 不是拍的。上限存在的理由是需求里那条:
|
|
300
|
+
**代码不许把原有 Markdown 上下文挤出去。**
|
|
301
|
+
- **生成 / 噪声产物一个都不准入**:
|
|
302
|
+
|
|
303
|
+
| 不进入检索的东西 | 为什么 |
|
|
304
|
+
|---|---|
|
|
305
|
+
| `app.js.map` | source map 是调试产物,不是上下文;但同名源文件在时,它的预览里给一个「Source map」入口 |
|
|
306
|
+
| `*.min.js` `*.min.css` | 压缩产物,读它没有意义 |
|
|
307
|
+
| `*.bundle.js` `*.generated.js` `*.gen.js` | 打包 / 生成产物 |
|
|
308
|
+
| `*.lock` `package-lock.json` | 锁文件,几千行机器生成的 json |
|
|
309
|
+
| `node_modules/` `dist/` `build/` `out/` `coverage/` `…` | 沿用 v0.18 就有的目录排除,**没有重写** |
|
|
310
|
+
|
|
311
|
+
⚠️ 「不进上下文」≠「不能看」。你通过 DSH 原生文件树打开 `dist/app.js`,Knit 不拦你 ——
|
|
312
|
+
**上下文资格与文件可见性是两件事。**
|
|
313
|
+
|
|
314
|
+
### 代码预览
|
|
315
|
+
|
|
316
|
+
点一个代码文件,就在**面板下方就地展开**(和 Markdown 一模一样的位置、一样的交互,
|
|
317
|
+
没有新的弹窗):行号 + 等宽字体 + 横向滚动,页脚给复制与「本地打开」。
|
|
318
|
+
不做语法高亮、不做代码折叠、不做多标签、不做 git diff —— **Knit 不是代码浏览器**。
|
|
319
|
+
|
|
320
|
+
同类入口还有:双击进官方标签页预览(带 DSH 自己的渲染器)、`Esc` 收起、键盘 `↑↓` 预览。
|
|
321
|
+
|
|
322
|
+
---
|
|
323
|
+
|
|
286
324
|
## 也给 agent 用:`knit_docs` 工具
|
|
287
325
|
|
|
288
326
|
同一份排序,除了给你看,也开了一个口子给模型。
|
|
@@ -455,9 +493,87 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
455
493
|
|
|
456
494
|
---
|
|
457
495
|
|
|
496
|
+
## 检索是怎么算的(实现细节,不是产品定义)
|
|
497
|
+
|
|
498
|
+
> 这一节是**证据**,不是卖点:支撑上面那句「按当前任务排序」的,就是下面这套本地算法。
|
|
499
|
+
> 产品要回答的问题在开头那一屏,这里回答的是「它凭什么排得准」。
|
|
500
|
+
|
|
501
|
+
没有玄学,就是字符串运算。三步:
|
|
502
|
+
|
|
503
|
+
**1. 读当前会话。** 取最近 6 条用户 / 助手消息,只认真人输入的用户消息
|
|
504
|
+
(`agent.inject()` 塞进来的合成上下文不算,那会把话题带偏)。越新的消息权重越高:3 / 2 / 1 / 1 …
|
|
505
|
+
|
|
506
|
+
**2. 抽关键词。**
|
|
507
|
+
|
|
508
|
+
- **英文词**:取值很高,出现 1 次就要(`chokidar`、`mtime` 这种精确词)
|
|
509
|
+
- **中文 2/3-gram**:出现 2 次,或出现在最新那条消息里
|
|
510
|
+
- **丢掉跨词边界的碎片**:中文没有词边界,n-gram 会把相邻两个词的字粘起来
|
|
511
|
+
(「图片和」「个插」「的排」)。这类碎片有个共同特征 —— **首字或尾字是纯虚词**,
|
|
512
|
+
一律丢掉。不丢的话它们会占满候选位,把「图片」「排序」这些真词全挤出去
|
|
513
|
+
- 虚词表过滤 + 贪心去重叠(选了「相关性排序」就不再算「相关性」和「排序」)
|
|
514
|
+
|
|
515
|
+
**3. 给文档打分 —— BM25。**
|
|
516
|
+
|
|
517
|
+
```
|
|
518
|
+
每个词先算 IDF:在语料里越罕见越值钱 ln(1 + (N - df + 0.5) / (df + 0.5))
|
|
519
|
+
再按字段加权求和:标题 ×4 + 摘要 ×2 + 正文前 2500 字 ×1
|
|
520
|
+
每个字段都按 BM25 饱和 + 长度归一化(k1 = 1.2,b = 0.3 / 0.5 / 0.75)
|
|
521
|
+
再叠 10% 的时间新鲜度微调(主排序仍是相关性)
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
**为什么是 BM25 而不是「命中次数 × 权重」**(那是最初的做法,已换掉):
|
|
525
|
+
|
|
526
|
+
- 没有 IDF 时,**语料里到处都是的词**(比如项目名)和罕见词一样值钱,
|
|
527
|
+
于是高频词不产生任何区分度,还稀释掉罕见词的分辨力
|
|
528
|
+
- 没有长度归一化时,**长文档靠堆词就能赢**
|
|
529
|
+
- 命中次数封顶 6 次是个手写硬拐点;`k1` / `b` 才是为这件事设计的
|
|
530
|
+
|
|
531
|
+
实测(`test/eval/fixture.mjs`,21 个用例,两版引擎跑同一套语料):
|
|
532
|
+
|
|
533
|
+
| | top-1 命中 | MRR |
|
|
534
|
+
|---|---|---|
|
|
535
|
+
| 旧做法(加权命中) | 76.2% | 0.830 |
|
|
536
|
+
| **BM25** | **95.2%** | **0.976** |
|
|
537
|
+
|
|
538
|
+
这套评测在 `npm test` 里跑,**基线由 `test/eval/legacy.mjs` 冻结的旧引擎现算**,
|
|
539
|
+
所以「新引擎必须显著更好」是自动验证的,而不是引用一个写死的数字。
|
|
540
|
+
|
|
541
|
+
**跟「自己数关键词」比**(`knit/tools/scale-benchmark.mjs`,N = 20/60/180/540):
|
|
542
|
+
语料刻意做成有真实陷阱的 —— 12 篇短而聚焦的主题文档,加上一堆「每条主题各提 5 次、
|
|
543
|
+
但哪一件都没讲」的长干扰文档(真实项目里的 CHANGELOG 就长这样)。
|
|
544
|
+
主题文档一半用描述性文件名,一半看不出内容。
|
|
545
|
+
|
|
546
|
+
| 路线 | 文件名说得清 | 文件名看不出 | MRR 随规模 |
|
|
547
|
+
|---|---|---|---|
|
|
548
|
+
| **Knit(BM25)** | **100%** | **100%** | **1.000(不随规模变)** |
|
|
549
|
+
| 自己 `grep -c` 数关键词 | 17% | **0%** | 0.313 → **0.089** |
|
|
550
|
+
| 只看文件名 | 100% | **0%** | 0.602 |
|
|
551
|
+
|
|
552
|
+
三件事:**排序强于自己数关键词**(所以让 agent 重算是不理性的);
|
|
553
|
+
**文件名匹配只在名字描述内容时好使**,Knit 是唯一两种都 100% 的;
|
|
554
|
+
**自己数的可靠性随规模单调下降**。
|
|
555
|
+
|
|
556
|
+
**关于那行「按「xxx」排序」**:显示的是**命中词在原文里覆盖的那一段**,不是词表里的碎片。
|
|
557
|
+
中文没有词边界,候选里必然有跨词的碎片(「项目文档」会切出 `项目文` / `目文档`),
|
|
558
|
+
直接显示就成了乱码 —— 把它们的**区间合并**再切原文,正好还原出 `项目文档`。
|
|
559
|
+
标签是你**自己打的字**,所以大小写原样保留(打 `BM25` 就显示 `BM25`)。
|
|
560
|
+
|
|
561
|
+
全是字符串运算 —— **没有 embedding,没有模型调用**。
|
|
562
|
+
|
|
563
|
+
**并且老实说边界**:
|
|
564
|
+
|
|
565
|
+
- **对话只有一两句时**关键词太少,它会退回按修改时间排,并在面板上说明这一点 —— 不假装排了个序
|
|
566
|
+
- **语料只有三五篇时 IDF 几乎不起作用**:`df` 的取值范围太窄,动态范围被压扁。
|
|
567
|
+
文档越多这个排序越准 —— 这正是它该有的样子
|
|
568
|
+
- **它只能排「和对话有共同词汇」的文档**:如果一个词都没命中,所有文档同分,
|
|
569
|
+
名次就退化成按时间排
|
|
570
|
+
|
|
571
|
+
---
|
|
572
|
+
|
|
458
573
|
## 它读什么,不读什么
|
|
459
574
|
|
|
460
|
-
- 扫描**当前会话工作区内**的 `.md
|
|
575
|
+
- 扫描**当前会话工作区内**的 `.md`、第一批代码后缀(见上文「代码上下文」)、图片与视频
|
|
576
|
+
(路径越出工作区一律拒绝);媒体只取元信息,不读画面内容;代码只读前 8 KB 进语料
|
|
461
577
|
- 只读**当前会话**的对话事件(用来排序)
|
|
462
578
|
- `knit_docs` 工具**只读**:不写任何文件、不落盘任何索引
|
|
463
579
|
- v0.15 的「使用情况」**默认关**:打开后也只读**当前会话已有**的工具事件(成功的 `read`),
|
|
@@ -491,8 +607,11 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
491
607
|
- **媒体只按文件名参与相关性匹配**:不解析画面 / 语音内容,截图与录屏建议用可检索的文件名
|
|
492
608
|
- **分层建立在召回之上**:如果 BM25 一篇都没把对的那篇捞进候选池,分层也只能在捞到的那几篇里分
|
|
493
609
|
—— 它救不了召回。词面错配(你问「图片和视频」,文档里写的是「媒体浏览」)就是这种情形
|
|
494
|
-
-
|
|
495
|
-
|
|
610
|
+
- **「当前任务上下文」覆盖文档与代码(v0.19,v0.14 起只覆盖文档)**:面板的媒体档、以及时间序模式都不分层
|
|
611
|
+
(那一档没有话题命中,就没有可解释的理由)。仍不解析 PDF / DOCX,也不支持第一批范围外的源码语言
|
|
612
|
+
- **代码只做词面检索,不做代码理解**:没有 AST、没有符号表、没有调用图、没有 LSP、不跳转定义。
|
|
613
|
+
文件名与路径是这一版最强的两个信号 —— 文件名起得含糊的文件(`utils.js`、`index.ts`)本来就难排上来
|
|
614
|
+
- **代码候选上限 300、正文只取前 8 KB**:超大仓库里这两条会生效,生效时面板头部的计数会显示被截断
|
|
496
615
|
- **引用关系只当上下文信号**:它能把文档放进辅助 / 相关层,**不会**把任何文档抬进主要上下文
|
|
497
616
|
- **测到的是「定位」,不是「省力」**:真机对照实验(冻结协议,四道题)里,能调 `knit_docs`
|
|
498
617
|
的 agent 总探索次数**没有下降** —— Control 4.75 → Treatment 6.0,四题逐题无一变少。
|
|
@@ -502,13 +621,29 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
502
621
|
|
|
503
622
|
---
|
|
504
623
|
|
|
624
|
+
## 反馈
|
|
625
|
+
|
|
626
|
+
**这个项目当前的重心不是加功能,是搞清楚「按对话给文档排序」这件事到底有没有人在用。**
|
|
627
|
+
所以最有价值的一句话不是「能不能加个 XX」,而是**你现在是怎么绕过它的** ——
|
|
628
|
+
哪怕结论是「装了,但一周没打开过」,也请直说,那比一个功能建议有用得多。
|
|
629
|
+
|
|
630
|
+
- 💬 [说说你在什么场景下会打开它](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) —— 两步、三十秒,不必客气
|
|
631
|
+
- 🐞 [装不上 / 面板打不开 / 排得不对](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
|
|
632
|
+
- 📖 提之前先看一眼[已知限制](#已知限制) —— 短对话退化、中文用 n-gram 近似,这几条是已知的取舍,不是 bug
|
|
633
|
+
|
|
634
|
+
> 一条 issue 会被当成真实信号处理。这个插件到现在**一个真实用户的痕迹都没有**
|
|
635
|
+
> (npm 那个下载量是自动化版本枚举、不是人 —— `latest` 占比只有 14%,而真人只会装 `latest`)
|
|
636
|
+
> —— 一条有人味儿的反馈能直接改变接下来做什么。
|
|
637
|
+
|
|
638
|
+
---
|
|
639
|
+
|
|
505
640
|
## 开发
|
|
506
641
|
|
|
507
642
|
```sh
|
|
508
643
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
509
644
|
cd dsh-knit
|
|
510
645
|
|
|
511
|
-
npm test #
|
|
646
|
+
npm test # 588 项,零依赖,不需要先 npm install
|
|
512
647
|
```
|
|
513
648
|
|
|
514
649
|
**改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
|
|
@@ -526,13 +661,14 @@ knit/
|
|
|
526
661
|
├── assets/ # 图标源文件(path 已内联进 client.js)
|
|
527
662
|
├── src/
|
|
528
663
|
│ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
|
|
664
|
+
│ ├── host/classification.js # 文件分类层:kind / language / 能力位(纯函数,零 I/O)
|
|
529
665
|
│ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
|
|
530
666
|
│ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
|
|
531
667
|
│ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
|
|
532
668
|
│ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
|
|
533
669
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
534
670
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
535
|
-
└── test/ #
|
|
671
|
+
└── test/ # 588 项测试
|
|
536
672
|
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
|
|
537
673
|
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
538
674
|
```
|
package/SECURITY.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> **Knit 的安全属性 —— 每一条都指向一个真实存在的检查。**
|
|
4
4
|
>
|
|
5
|
-
> 最后更新:2026-
|
|
5
|
+
> 最后更新:2026-10-07(v0.19.1)
|
|
6
6
|
|
|
7
7
|
## 为什么有这份文件
|
|
8
8
|
|
|
@@ -29,10 +29,11 @@ Knit 的安全属性其实一直成立 —— 但它们此前只散落在文档
|
|
|
29
29
|
| 零运行时依赖 | ✅ | `package.json` 的 `dependencies` 为空;`test/security.test.mjs` 断言 |
|
|
30
30
|
| 无安装期脚本 | ✅ | `package.json` 只有 `test` 一个 script,无 `install`/`postinstall`/`prepare`;`test/security.test.mjs` 断言 |
|
|
31
31
|
| 读文件接口守在会话工作区内 | ✅ | `test/host.test.mjs` 的越界用例(解析后必须落在工作区内,否则一律拒绝) |
|
|
32
|
+
| `/knit/api/doc` 只放行文本类产物 | ✅ | v0.19 起因代码而放宽(原为「仅 Markdown」),所以边界要重新说清:**文档 / 代码 / 生成产物**放行,**媒体与未知后缀一律拒绝**。`test/host.test.mjs` 的 `notPreviewable` 用例 + `test/classification.test.mjs` 的 `isPreviewKind` 闭集断言 |
|
|
32
33
|
| `/knit/api/raw` 叠扩展名白名单 | ✅ | `test/host-http.test.mjs`(非图片/视频扩展名一律拒绝) |
|
|
33
34
|
| 只允许 GET、只允许回环地址 | ✅ | `test/host-http.test.mjs` |
|
|
34
35
|
| 响应带 `nosniff` 与 `default-src 'none'; sandbox` | ✅ | `test/host-http.test.mjs`(两个指令各自断言) |
|
|
35
|
-
| 零网络出口:客户端 `fetch` 全部同源相对路径 | ✅ | `src/client/client.js` 的三个接口常量都是 `/knit/api/*`;`test/security.test.mjs`
|
|
36
|
+
| 零网络出口:客户端 `fetch` 全部同源相对路径 | ✅ | `src/client/client.js` 的三个接口常量都是 `/knit/api/*`;`test/security.test.mjs` 断言无协议头。HTML 的「网页预览」按钮是把文件交给 **DSH 自己的**文档预览标签页去渲染(Knit 这一侧一个请求都不发),渲染的沙箱与 CSP 归 DSH 管 —— 所以这条承诺不变 |
|
|
36
37
|
| 宿主半边不 import `@deepseek-ai/*` | ✅ | `test/security.test.mjs` 扫三个宿主文件,注释里提到可以、真实 `import` 不行 |
|
|
37
38
|
| `knit_docs` 工具只读,不写任何文件 | ✅ | `src/host/tool.js` 只调注入进来的 `scan` 与只读的 `readDocument`;无写文件调用 |
|
|
38
39
|
| 未经第三方安全审计 | ⚠️ | **如实说明**:这张表是**自证**。没有外部审计报告,也没有自动化扫描评分 —— 它不等于「已证明安全」 |
|
|
@@ -46,6 +47,6 @@ Knit 的安全属性其实一直成立 —— 但它们此前只散落在文档
|
|
|
46
47
|
## 如何自己复核
|
|
47
48
|
|
|
48
49
|
```sh
|
|
49
|
-
npm test #
|
|
50
|
+
npm test # 588 项,含本节所有断言
|
|
50
51
|
npm test -- test/security.test.mjs # 只跑安全守卫
|
|
51
52
|
```
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.19.1",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"description": "
|
|
5
|
+
"description": "Task-aware workspace context retrieval and lifecycle tracking for DeepSeek Harness. Finds the documents, source files and media most relevant to the current conversation, organises them into a Context Pack (primary / supporting / related) in the sidebar with inline preview, and tracks which of them were actually read and what changed afterwards. Zero model calls, zero network, nothing leaves the machine.",
|
|
6
6
|
"main": "./src/host/index.js",
|
|
7
7
|
"exports": {
|
|
8
8
|
".": "./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 test/document-lifecycle.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 test/classification.test.mjs test/code-context.test.mjs"
|
|
27
27
|
},
|
|
28
28
|
"dsh": {
|
|
29
29
|
"bundle": {
|
|
@@ -45,13 +45,18 @@
|
|
|
45
45
|
"dsh",
|
|
46
46
|
"markdown",
|
|
47
47
|
"documents",
|
|
48
|
+
"code",
|
|
49
|
+
"code-context",
|
|
50
|
+
"typescript",
|
|
48
51
|
"sidebar",
|
|
49
52
|
"right-sidebar",
|
|
50
53
|
"recent-files",
|
|
51
54
|
"relevance",
|
|
52
55
|
"context-pack",
|
|
56
|
+
"workspace-context",
|
|
57
|
+
"context-retrieval",
|
|
58
|
+
"context-lifecycle",
|
|
53
59
|
"task-context",
|
|
54
|
-
"knowledge-base",
|
|
55
60
|
"images",
|
|
56
61
|
"video",
|
|
57
62
|
"media-gallery",
|