dsh-knit 0.17.0 → 0.19.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
@@ -5,11 +5,12 @@
5
5
  >
6
6
  > **你的 agent 也一样。** 同一份排序也给它当工具用 —— 它问「哪几篇相关」,拿回排名**加每篇里命中的那段原文**。
7
7
 
8
- ![Knit 面板真机截图:右侧栏按相关性列出工作区文档,就地展开 Markdown 预览,预览头下方是引用条](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png)
8
+ ![Knit 面板真机截图:右侧栏停在「代码」档,按相关性列出工作区源码,就地展开代码预览](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png)
9
9
 
10
- *真机截图(不是原型):一个含 53 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
11
- *引用条是 v0.12 加的:展开就能看到「这篇被谁引用」,点一项直接跳过去。*
12
- *头部只放路径、篇数与两个开关;列表按「相关」还是「最新」排,由左边那一对页签决定 —— 按「相关」时排的就是你正在聊什么。*
10
+ *真机截图(不是原型):同一个工作区,这张停在 **「代码」档** —— v0.19 起,源码和 Markdown 一样是一等公民。*
11
+ *每行下面的「为什么」写着它是怎么被命中的(`直接命中:knit · readme` / `路径命中:knit · path` / `直接命中:knit · 工作区`)。*
12
+ *点一行**就地**展开预览:这里是 `knit/src/host/classification.js`,带行号;预览头里只有路径和四个动作(复制 / 全屏 / 本地打开 / 关闭)。*
13
+ *头部只放路径、一个计数与两个开关;列表按「相关」还是「最新」排,由左边那一对页签决定 —— 按「相关」时排的就是你正在聊什么。*
13
14
  *v0.14 起文档列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
14
15
  *Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
15
16
  *序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
@@ -23,7 +24,7 @@
23
24
  *这一屏里没有文档落进主要层,所以分组从「辅助上下文」开始。*
24
25
  *⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
25
26
 
26
- 扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
27
+ 扫整个项目文件夹的文档 / 代码 / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
27
28
 
28
29
  ```sh
29
30
  dsh plugin --profile web add dsh-knit
@@ -41,8 +42,8 @@ dsh plugin --profile web add dsh-knit
41
42
 
42
43
  三句话说完它是什么:
43
44
 
44
- 1. 扫**整个项目文件夹**的 Markdown,不只是这一轮生成的那几篇 —— 重启、换会话、跨天都还在
45
- 2. 排序**跟着你正在聊什么走**:聊架构,架构文档浮上来;聊竞品,竞品分析浮上来
45
+ 1. 扫**整个项目文件夹**的文档与代码,不只是这一轮生成的那几篇 —— 重启、换会话、跨天都还在
46
+ 2. 排序**跟着你正在聊什么走**:聊架构,架构文档浮上来;聊 loader 的 bug,`plugin-loader.ts` 浮上来
46
47
  3. **不调模型、不联网**:全是本地字符串运算,零延迟、零成本、文档不出本机
47
48
 
48
49
  ---
@@ -166,18 +167,22 @@ dsh plugin --profile web add dsh-knit
166
167
  | **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
167
168
  | **文档生命周期**(v0.17):每篇推荐文档现在处于 `未读 / 已读 / 读后已更新 / 修改后已重新读取` 哪一档,另外给出最近读了哪篇、包外读了哪几篇、上下文最近一次怎么变 | ✅ |
168
169
  | 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
169
- | 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
170
+ | 扫描会话工作区里的 `.md` 与上表那批代码后缀(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist` / `build` / `out` / `coverage` …) | ✅ |
171
+ | **生成 / 噪声产物不进检索**:`.map`、`*.min.js`、`*.min.css`、`*.bundle.js`、`*.generated.js`、`*.gen.js`、`*.lock`、`package-lock.json` —— 你能打开它们看,但它们**不会**成为主要 / 辅助 / 相关上下文 | ✅ |
172
+ | 代码预览:行号 + 等宽 + 横向滚动 + 复制 + 「本地打开」;同名 `app.js.map` 存在时预览页脚多一个低权重「Source map」入口(点开按纯文本看,`.map` 本身不进上下文) | ✅ |
170
173
  | 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
171
174
  | 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径**重复,只保留后者 | ✅ |
172
175
  | 单击就地展开预览,再点收起 | ✅ |
173
176
  | 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
174
- | **文档 / 图片与视频 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边 | ✅ |
177
+ | **代码上下文**(v0.19):`.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm .css .scss .yaml .yml .sh .bash .zsh` 与 Markdown **进同一个检索池**,共用同一份 BM25、同一个 Context Pack、同一套生命周期 —— 不是第二套「代码搜索」 | ✅ |
178
+ | **文档 / 代码 / 媒体 / 全部** 四类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边(页签「媒体」2026-10-06 由「图片与视频」改短,「代码」v0.19 加入) | ✅ |
175
179
  | 图片与视频:方形缩略图网格,**格子基准固定 104px、列数由宽度连续数出来**(320px → 2 列 / 632px → 5 列 / 1200px → 10 列),格子大小基本不变;**纵向有多少行就铺多少行**,超出交给列表滚动;视频自动取首帧、叠播放三角与时长角标(零依赖、不转码) | ✅ |
176
180
  | 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
177
181
  | 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
178
- | 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出 | ✅ |
179
- | **「本地打开」**:用系统默认应用打开当前预览的这篇文档(预览头的路径同样可点,完整路径在悬停提示里) | ✅ |
182
+ | 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出;**全屏时头部 / 排序条 / 类型档 / 使用情况 / 列表全部让位**,预览铺满整个面板 | ✅ |
183
+ | **「本地打开」**:用系统默认应用打开当前预览的这篇文档;**预览头那条路径点开的是它「所在的文件夹」并顺带选中这个文件**(reveal,macOS 是 Finder 里 `open -R`;与顶部那行工作区路径同一套机制,差别只在「打开目录」vs「定位到文件」,完整相对路径在悬停提示里) | ✅ |
180
184
  | 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
185
+ | **HTML 的「网页预览」**(v0.19 追加):预览头只对 `.html` / `.htm` 多一个按钮,点了在官方文档预览标签页里**按网页渲染** —— 那一侧是 DSH 自带的 HTML 渲染器(默认静态档:清洗过的文档 + 不给 sandbox 权限的 iframe + CSP 挡脚本 / 外部资源 / 表单 / 嵌套框架,内联 `<style>` 与 `data:` 图片保留)。就地预览给的是**源码**,两者不重复;其余代码类型不给这个按钮 | ✅ |
181
186
  | 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
182
187
  | **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
183
188
  | **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局;浮层只有「头 + 列表」,没有多余的横线与提示语) | ✅ |
@@ -191,18 +196,19 @@ dsh plugin --profile web add dsh-knit
191
196
 
192
197
  ### 另外两档长什么样
193
198
 
194
- ![图片与视频档真机截图:方形缩略图网格,这一屏 6 列](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
199
+ ![媒体档真机截图:方形缩略图网格,这一屏 6 列](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
195
200
 
196
- *图片与视频:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
201
+ *媒体:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 110px。*
197
202
  *列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图、一张演示动图和一个*
198
203
  *单色 SVG 图标,所以看起来像一屏文件缩略图(那个纯黑方块就是图标本身,不是加载失败)。*
199
204
  *视频会取首帧当海报、中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
200
205
 
201
- ![全部档真机截图:上区文档只给前 4 条与「查看全部 →」,下区是图片与视频网格](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
206
+ ![全部档真机截图:上区文档只给前 4 条与「查看全部 →」,中间是代码区,下区是媒体网格](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
202
207
 
203
- *全部:上区文档最多 4 条,超出时右侧给「查看全部 →」(这一屏是「4 / 36」),下区是图片与视频网格。*
204
- *⚠️ 上下两区共用宿主返回的**同一个 40 条窗口**:图片与视频如果按相关性排到第 40 名之外,*
205
- *「全部」档就**整段看不到它们**(「图片与视频」档不受影响,它单独取媒体)。*
208
+ *全部:**文档区最多 4 条**、**代码区最多 4 条**(超出时各区右侧给「查看全部 →」,这一屏是「4 / 19」与「4 / 17」),最后是媒体网格。*
209
+ *⚠️ 三个区共用宿主返回的**同一个 40 条窗口**:某一类如果按相关性排到第 40 名之外,「全部」档就整个看不到它。*
210
+ *这张图用的是**「最新」排序** —— 在这个工作区里,默认的「相关」排序下媒体恒定掉在 40 条窗口之外*
211
+ *(`limit=40` 时那 40 条全是 34 篇文档 + 6 个代码文件)。**「媒体」/「代码」档不受影响**,它们各自单独取。*
206
212
  *这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
207
213
 
208
214
  ---
@@ -283,6 +289,71 @@ Context Pack 是对这个问题的回答,但它是**数据层的结构**(主
283
289
 
284
290
  ---
285
291
 
292
+ ## 代码上下文(v0.19)
293
+
294
+ 上面这一整套(检索 → 三层 Context Pack → 读取证据 → 生命周期 → 上下文变化 → 使用情况)
295
+ v0.19 起**同样适用于代码**。没有第二条链路:代码文件走的是**同一个** BM25、**同一个** Context Pack、
296
+ **同一套** Read Evidence 与生命周期。
297
+
298
+ **为什么加了代码是有意义的。** 一个真实任务(「改 plugin loader,让它支持新的 plugin metadata」)
299
+ 最该先看的往往不是某篇文档,而是 `plugin-loader.ts` 本身。v0.18 之前 Knit 扫不到它 ——
300
+ 面板里只有 Markdown,agent 也只能靠 `glob` 猜路径。
301
+
302
+ ### 第一批支持的后缀(严格限定)
303
+
304
+ ```
305
+ .js .mjs .cjs .ts .tsx .jsx .py .json
306
+ .html .htm .css .scss .yaml .yml
307
+ .sh .bash .zsh
308
+ ```
309
+
310
+ **明确不支持**(这一版刻意不做):`.go .rs .java .kt .c .cpp .h .hpp .cs .php .rb .swift .sql`。
311
+
312
+ 为什么不一次全上:这一版要验证的命题是「**把当前任务真正需要的代码纳入上下文有没有用**」,
313
+ 不是「支持了多少种语言」。范围越小,「没用」这个结论越可信。
314
+
315
+ ### 代码的排序字段与 Markdown 不同
316
+
317
+ 代码没有「标题 / 摘要 / 正文」这套结构,硬套会把文件名这个**最强的信号**降权。所以代码条目:
318
+
319
+ | 字段 | 权重 | 放什么 |
320
+ |---|---|---|
321
+ | `filename` | ×4 | `context-manager.ts` —— 文件名本身就带任务语义 |
322
+ | `path` | ×2 | `src/context/` —— 目录名是第二层信号 |
323
+ | `content` | ×1 | 文件**前 8 KB**(不是全文,见下) |
324
+
325
+ Markdown 仍是 `title ×4 / summary ×2 / body ×1`。**两套字段权重,同一个 BM25。**
326
+
327
+ ### 有边界的三件事(都实测过)
328
+
329
+ - **正文有界**:代码只读前 8 KB 进语料。不是为了省磁盘,是为了让扫描时间与检索延迟
330
+ 不随「项目里有多少 JS」线性爆炸。
331
+ - **候选有上限**:代码准入上限 **300 个**(Markdown 仍是 400)。
332
+ 这个数字是**量过真实工作区**才定的 —— 不是拍的。上限存在的理由是需求里那条:
333
+ **代码不许把原有 Markdown 上下文挤出去。**
334
+ - **生成 / 噪声产物一个都不准入**:
335
+
336
+ | 不进入检索的东西 | 为什么 |
337
+ |---|---|
338
+ | `app.js.map` | source map 是调试产物,不是上下文;但同名源文件在时,它的预览里给一个「Source map」入口 |
339
+ | `*.min.js` `*.min.css` | 压缩产物,读它没有意义 |
340
+ | `*.bundle.js` `*.generated.js` `*.gen.js` | 打包 / 生成产物 |
341
+ | `*.lock` `package-lock.json` | 锁文件,几千行机器生成的 json |
342
+ | `node_modules/` `dist/` `build/` `out/` `coverage/` `…` | 沿用 v0.18 就有的目录排除,**没有重写** |
343
+
344
+ ⚠️ 「不进上下文」≠「不能看」。你通过 DSH 原生文件树打开 `dist/app.js`,Knit 不拦你 ——
345
+ **上下文资格与文件可见性是两件事。**
346
+
347
+ ### 代码预览
348
+
349
+ 点一个代码文件,就在**面板下方就地展开**(和 Markdown 一模一样的位置、一样的交互,
350
+ 没有新的弹窗):行号 + 等宽字体 + 横向滚动,页脚给复制与「本地打开」。
351
+ 不做语法高亮、不做代码折叠、不做多标签、不做 git diff —— **Knit 不是代码浏览器**。
352
+
353
+ 同类入口还有:双击进官方标签页预览(带 DSH 自己的渲染器)、`Esc` 收起、键盘 `↑↓` 预览。
354
+
355
+ ---
356
+
286
357
  ## 也给 agent 用:`knit_docs` 工具
287
358
 
288
359
  同一份排序,除了给你看,也开了一个口子给模型。
@@ -325,10 +396,12 @@ v0.15 起有一层**可核验的使用反馈**:把 agent 真实读过的文件
325
396
  v0.16 把这件事钉死:**归因在读发生那一刻结算并冻结** —— 之后上下文怎么换,历史数字都不会改口
326
397
  (v0.15 里同一个读会被「现在」重判成包外,那是 bug)。
327
398
 
328
- **默认关。** 面板头部有一个「使用情况」开关,打开之后列表上方会多一行字:
399
+ **默认关。** 面板头部有一个「使用情况」开关,打开之后列表上方会多出一块**观察层**
400
+ (v0.18 起叫 Usage Lens,形状见下面「把使用情况读出来」一节)。它最上面一行仍然只报事实:
329
401
 
330
402
  ```
331
- 当前上下文 · Epoch 4 · 先看的「docs/xxx.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次
403
+ 使用情况 Epoch 5 ˄
404
+ 174 次读取 · 28 篇包外 · 上下文变化 3 次
332
405
  ```
333
406
 
334
407
  - **Context Epoch**:一份**内容有变化**的上下文 = 一个 Epoch(内容没变就不新建,轮询不会灌进几十个)。
@@ -362,9 +435,12 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
362
435
 
363
436
  ### v0.17:读完之后,这篇文档现在是什么状态
364
437
 
365
- 打开「使用情况」之后,除了上面那一行,还会多两样东西:**每篇推荐文档的状态**,
438
+ 打开「使用情况」之后,除了统计,还会多两样东西:**每篇推荐文档的状态**,
366
439
  以及「最近读了哪篇 / 包外读了哪几篇 / 上下文最近一次怎么变」。
367
440
 
441
+ > ⚠️ 下面这段 ASCII 是 **v0.17 当时的界面形状**。v0.18 把这一块重做成了列表上方的 Usage Lens
442
+ > (形状见下一节)—— **判据、四档状态、数据来源一个字没变**,这一节讲的是数据与判据。
443
+
368
444
  ```
369
445
  当前上下文 · Epoch 4
370
446
  最近读取:SDD-v0.17.md · 12 分钟前
@@ -410,13 +486,50 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
410
486
  以及系统开了「减弱动态效果」时都**不播**。这不是新功能,只是把「谁进来了、谁走了、
411
487
  谁挪了位置」演给人看 —— 索引、排序、分层与 `knit_docs` 的输出一个字都没改。
412
488
 
489
+ ### v0.18:把「使用情况」读出来(Context Usage Lens)
490
+
491
+ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出结构:哪一层读得多、最近读的是哪一篇、
492
+ 包外那二十篇里哪几篇被反复读、这次变化是进是出。v0.18 把它重做成列表**上方的一块观察层**
493
+ —— 不是弹窗、不是新页面、也不是 Dashboard:
494
+
495
+ ```
496
+ 使用情况 Epoch 5 ˄
497
+ 174 次读取 · 28 篇包外 · 上下文变化 3 次
498
+ 当前上下文
499
+ 主要 1 / 1 辅助 2 / 3 相关 0 / 5
500
+ ● ● ○ ○ ○ ○ ○ ○
501
+ 最近读取 docs/eval.md 12分钟前 ›
502
+ 上下文外读取 20 ›
503
+ 上下文变化 最近一次 ›
504
+ ```
505
+
506
+ - **当前上下文 Coverage**:三层各给「状态点 + `已读数 / 本层总数`」。点某一层会**滚到那一层并短暂亮一下**
507
+ (不画箭头、不画横线 —— 用空间说「就是这里」)。**只报事实**:没有进度条、没有百分比
508
+ —— Knit 不评价「这份上下文用完了没有」;Primary 不存在时整列不显示,不画 `0 / 0` 的假层。
509
+ - **行内状态点**:未读=空心圆 / 已读=实心圆 / 读后已更新=实心圆套内圈 / 修改后已重新读取=`↻`,
510
+ 与原来那行文字**同时**存在(状态点说状态、文字说次数)。点它=打开这一篇。不用红绿、不加徽章。
511
+ Coverage 的三层圆点与文档行这一颗**同一套 token、同一个 6px 直径** —— 两处说的是同一种状态语言。
512
+ - **最近读取**是一行可点的事实(`文件名 · 相对时间 ›`),点它直接打开该篇,**不重新请求列表**。
513
+ 它仍然是「**最近一次成功 read**」—— 没有改成「正在阅读」。
514
+ - **上下文外读取**默认最多 10 篇 + 「还有 N 篇」,每行可点、带状态;按**读得最多的**排
515
+ (`count DESC`)—— 这是事实排序,不是相关度。**不许**从这里把文档加进 Context(V0.18 不做 Context Control)。
516
+ - **上下文变化**默认折叠,展开按 进入 / 离开 / 换层 分组,每组最多 5 条;只展示**最近一次**。
517
+ - Lens 自己能展开 / 收起。**收起不等于关掉统计** —— 收起只是「统计开着、暂时不想看细节」;
518
+ 关掉开关才真的一个统计 DOM 都不产生。
519
+ - 面板很矮(< 420px)时降级成「摘要 + Coverage + 最近读取」,变化明细点开仍在;
520
+ 滚动**始终只交给列表** —— 没有第二个滚动容器,窄侧栏里不会滚轮套滚轮。
521
+
522
+ 数据一个字都没新加:全部来自 v0.17 已有的 `lifecycle / recentRead / outsideDocs / latestDelta`
523
+ 与当前 `context` 的三层,Coverage 是从它们**派生**的(纯函数 `coverageOf` / `groupOutsideDocs` / `groupDelta`)。
524
+
413
525
  `knit_docs` 的工具输出**没有跟着变大**:它仍然只负责找上下文。
414
526
 
415
527
  ---
416
528
 
417
529
  ## 它读什么,不读什么
418
530
 
419
- - 扫描**当前会话工作区内**的 `.md`、图片与视频(路径越出工作区一律拒绝);媒体只取元信息,不读画面内容
531
+ - 扫描**当前会话工作区内**的 `.md`、第一批代码后缀(见上文「代码上下文」)、图片与视频
532
+ (路径越出工作区一律拒绝);媒体只取元信息,不读画面内容;代码只读前 8 KB 进语料
420
533
  - 只读**当前会话**的对话事件(用来排序)
421
534
  - `knit_docs` 工具**只读**:不写任何文件、不落盘任何索引
422
535
  - v0.15 的「使用情况」**默认关**:打开后也只读**当前会话已有**的工具事件(成功的 `read`),
@@ -450,8 +563,11 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
450
563
  - **媒体只按文件名参与相关性匹配**:不解析画面 / 语音内容,截图与录屏建议用可检索的文件名
451
564
  - **分层建立在召回之上**:如果 BM25 一篇都没把对的那篇捞进候选池,分层也只能在捞到的那几篇里分
452
565
  —— 它救不了召回。词面错配(你问「图片和视频」,文档里写的是「媒体浏览」)就是这种情形
453
- - **「当前任务上下文」只覆盖 Markdown**:面板的图片与视频两档、以及时间序模式都不分层
454
- (那两档没有话题命中,就没有可解释的理由)。第一版也不解析 PDF / DOCX / 源码
566
+ - **「当前任务上下文」覆盖文档与代码(v0.19,v0.14 起只覆盖文档)**:面板的媒体档、以及时间序模式都不分层
567
+ (那一档没有话题命中,就没有可解释的理由)。仍不解析 PDF / DOCX,也不支持第一批范围外的源码语言
568
+ - **代码只做词面检索,不做代码理解**:没有 AST、没有符号表、没有调用图、没有 LSP、不跳转定义。
569
+ 文件名与路径是这一版最强的两个信号 —— 文件名起得含糊的文件(`utils.js`、`index.ts`)本来就难排上来
570
+ - **代码候选上限 300、正文只取前 8 KB**:超大仓库里这两条会生效,生效时面板头部的计数会显示被截断
455
571
  - **引用关系只当上下文信号**:它能把文档放进辅助 / 相关层,**不会**把任何文档抬进主要上下文
456
572
  - **测到的是「定位」,不是「省力」**:真机对照实验(冻结协议,四道题)里,能调 `knit_docs`
457
573
  的 agent 总探索次数**没有下降** —— Control 4.75 → Treatment 6.0,四题逐题无一变少。
@@ -467,7 +583,7 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
467
583
  git clone https://github.com/PolinniZhong/dsh-knit.git
468
584
  cd dsh-knit
469
585
 
470
- npm test # 517 项,零依赖,不需要先 npm install
586
+ npm test # 588 项,零依赖,不需要先 npm install
471
587
  ```
472
588
 
473
589
  **改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
@@ -485,13 +601,14 @@ knit/
485
601
  ├── assets/ # 图标源文件(path 已内联进 client.js)
486
602
  ├── src/
487
603
  │ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
604
+ │ ├── host/classification.js # 文件分类层:kind / language / 能力位(纯函数,零 I/O)
488
605
  │ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
489
606
  │ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
490
607
  │ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
491
608
  │ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
492
609
  │ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
493
610
  │ └── client/client.js # 双宿主注册 + 面板 UI
494
- └── test/ # 517 项测试
611
+ └── test/ # 588 项测试
495
612
  ├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
496
613
  └── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
497
614
  ```
package/SECURITY.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  > **Knit 的安全属性 —— 每一条都指向一个真实存在的检查。**
4
4
  >
5
- > 最后更新:2026-09-18(v0.11.0)
5
+ > 最后更新:2026-10-07(v0.19.0)
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 # 231 项,含本节所有断言
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.17.0",
3
+ "version": "0.19.0",
4
4
  "type": "module",
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.",
5
+ "description": "Task-aware workspace context retrieval for DeepSeek Harness. Ranks the workspace's documents and code by relevance to the current conversation, shows the Context Pack (primary / supporting / related) in the sidebar with inline preview, and tracks which of them the agent actually read and what changed after. Zero model calls, zero network.",
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,15 @@
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",
53
56
  "task-context",
54
- "knowledge-base",
55
57
  "images",
56
58
  "video",
57
59
  "media-gallery",