dsh-knit 0.19.1 → 0.20.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 +249 -0
- package/README.en.md +41 -24
- package/README.md +32 -21
- package/SECURITY.md +2 -2
- package/package.json +3 -2
- package/src/client/client.js +742 -63
- package/src/host/context.js +29 -1
- package/src/host/index.js +124 -13
- package/src/host/passage.js +408 -0
- package/src/host/tool.js +104 -23
- package/test/client.test.mjs +793 -12
- package/test/context/fixture.mjs +2 -5
- package/test/deep-context.test.mjs +447 -0
- package/test/deep-eval.test.mjs +90 -0
- package/test/deep-scale.test.mjs +64 -0
- package/test/eval/deep.mjs +322 -0
- package/test/eval/fixture.mjs +6 -9
- package/test/fixture.mjs +21 -1
- package/test/harness.mjs +63 -4
- package/test/host.test.mjs +2 -2
- package/test/icon.test.mjs +11 -8
- package/test/tool.test.mjs +247 -18
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,251 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.20.0] - 2026-10-07
|
|
7
|
+
|
|
8
|
+
> **Deep Context Retrieval**。核心体验从「任务 → 相关文件」升级为
|
|
9
|
+
> 「**任务 → 相关文件 → 相关内容片段**」—— Find the file. Then find the part that matters.
|
|
10
|
+
> 在这之前,每一篇只有**正文前 2500 字**参与打分,所以「那一段在 5000 字之后」就等于
|
|
11
|
+
> 「搜不到」,而 `knit_docs` 只能诚实地告诉模型「用 grep 去更深处找」。
|
|
12
|
+
> 关键约束:**没有 embedding / 向量库 / LLM / 网络请求 / AST / LSP / Tree-sitter /
|
|
13
|
+
> 代码知识图谱、没有第二个栏位、没有 Dashboard、没有新的 preview framework。**
|
|
14
|
+
> 文件仍然是 Context Pack 的**基本实体** —— 这不是把 Knit 改成一个纯片段搜索工具。
|
|
15
|
+
|
|
16
|
+
### 变化
|
|
17
|
+
|
|
18
|
+
- **取消「每篇只看前 2500 字」**(删掉 `HAYSTACK_CHARS`)。文档与代码的 `body` / `hayBody`
|
|
19
|
+
现在都是**整篇**转小写,上限仍是单文件 `MAX_BODY_BYTES = 256 KB`。
|
|
20
|
+
一个容易忽略的事实:宿主**本来就把整篇读进内存**(`readFile` 之后才 `subarray`),
|
|
21
|
+
所以这一版新增的磁盘 I/O 约等于 0,代价是幂等副本的内存(约 2× 正文,见「已知限制」)。
|
|
22
|
+
- **新增 `src/host/passage.js`(零依赖、纯字符串、无 AST)**。切分是**结构优先 + 长度兜底**:
|
|
23
|
+
Markdown 按 H1/H2/H3 / 段落 / 代码块,代码按 `function` `class` `const` `let` `var`
|
|
24
|
+
`interface` `type` `export` `import` 声明起点与大括号块;行号与字符偏移量由构造过程保证
|
|
25
|
+
(不是事后 `indexOf` 猜的)。导出 `chunkText()` / `snippetOf()` / `passageMatchesFor()` /
|
|
26
|
+
`windowTf()` / `passageTfOf()` 与 `PASSAGE_WINDOW = 24` / `PASSAGE_MAX_PER_FILE = 2` /
|
|
27
|
+
`SNIPPET_CHARS = 200` / `PASSAGE_MAX_CHARS = 1200`。
|
|
28
|
+
- **文件排序与片段排序分开**(需求 §8)。既有 `rankByRelevance()` 一行未改:先按文件排名,
|
|
29
|
+
再在每篇内部挑片段(命中词种数优先、其次窗口字频、最后行号升序),每篇最多 2 段、
|
|
30
|
+
段与段不重叠;「20 个低价值片段堆高分」这条被 `PASSAGE_MAX_PER_FILE` 与窗口内字频同时挡住。
|
|
31
|
+
- **长文件污染不再因为全文检索复活**(需求 §9)。`context.js` 的 `isDocHit` 闸门改用
|
|
32
|
+
**片段窗口内的字频**(`windowTf`,默认窗口 = `PASSAGE_MAX_CHARS`)而不是整篇字频 ——
|
|
33
|
+
否则 29000 字的 CHANGELOG 会对**每一个**任务都满足「这一篇在讲它」而挤进每条任务的 Supporting。
|
|
34
|
+
没有片段数据时(老宿主、`test/context*/fixture.mjs` 的合成记录)逐字退回 v0.19 的整篇口径,
|
|
35
|
+
因此 `test/eval.test.mjs` 与 `test/context-eval.test.mjs` 的基线**一条都没改**。
|
|
36
|
+
- **`knit_docs` 给出「文件 + 理由 + 最相关片段 + 行号」**(需求 §15/§11)。每项可选带
|
|
37
|
+
`matches: [{startLine, endLine, startOffset, endOffset, terms, snippet}]`;渲染成
|
|
38
|
+
`match: lines 147–163 — …`。**只渲染一段**:R2 实测两段 = v0.19 的 1.71×,超过实现说明
|
|
39
|
+
定的 1.4×,按那条规则砍到一段(同一语料 1.04×,最坏语料 1.36×)。诚实性文案改成
|
|
40
|
+
「Every document and code file was searched in full (files over 256 KB are indexed only up
|
|
41
|
+
to that size); images and videos have no searchable text.」—— 不再提 `2500 characters`
|
|
42
|
+
和 `use grep`。顺带拿掉 v0.19 里「每返回一条就 `readDocument()` 读一遍整篇」的 I/O。
|
|
43
|
+
- **面板多一行 metadata:「命中段 147–163」**(需求 §12 + 2026-10-07 用户裁决)。它是一个
|
|
44
|
+
**长得像文字的 button**(无图标、**无描边** —— 选中 / 聚焦都不画环,键盘焦点靠与 hover
|
|
45
|
+
同款的下划线;**有一个灰底**:`--knit-chip-bg` + 6px 圆角(胶囊感)、1px 6px 内边距,两个主题各一套值,
|
|
46
|
+
比行选中那档深一点,免得它在被选中的行里消失),点它走**既有**的就地预览。**点整行也一样**:行点击与
|
|
47
|
+
「点那行字」都带上篇内第一段命中(用户原话「我在点击这个文档或者是代码块的时候,就进入一个
|
|
48
|
+
预览,那能不能直接定位到这几段呢?这样的交互非常丝滑」)。代码文件会定位到命中行,命中区域画
|
|
49
|
+
一条中性灰横带(`.knit-code-hit`,`position:absolute` + `pointer-events:none` + **`opacity:.5`**
|
|
50
|
+
—— 用户要求「背景太深了,再减少一半」;不写死颜色、用 `--knit-active-bg` 回落),滚动用的仍是
|
|
51
|
+
既有那一个 `.knit-preview-body`。文案从「命中片段」缩到**「命中段」**(EN `Passage:`),并且与
|
|
52
|
+
v0.14 的「直接命中」**合成同一条 metadata 行**(`.knit-subrow`:命中段在左、中间一条 1px 中性
|
|
53
|
+
竖线、理由在右)—— 于是这一版**没有让每一行变高**。没有分数、没有百分比、没有置信度、
|
|
54
|
+
没有「AI 分析」—— 只展示可验证的行号区间。**2026-10-07 用户裁决(标点)**:中文去掉全角冒号
|
|
55
|
+
(`命中段 147–163 | 直接命中 knit · border`)—— 全角冒号占一个整字宽 + 强制停顿,而这一行是两个
|
|
56
|
+
标签并排;整族 6 个理由标签一起改,否则标点会随理由类型跳。**冒号只在引出列表时保留**,**英文保留
|
|
57
|
+
ASCII 冒号**(半个字宽,且 `direct match knit` 读起来像在说 match 这个词)。
|
|
58
|
+
- **Markdown 预览也跳到命中段**(2026-10-07 用户裁决:「文档这边也参考代码块一样,选中文档以后进入详情,
|
|
59
|
+
要指定到段落」)。`.md` 没有行号 ⇒ 不走行锚点,走**文本锚点**:从片段原文的 `[startOffset, endOffset)`
|
|
60
|
+
里按行取 1–4 根「针」(长度 ≥12、≤40;去掉行首 `#` / `>` / 列表符,`[文字](地址)` 只留文字,
|
|
61
|
+
`*` / `~` / 反引号去掉,**下划线只在成对强调处删**以保住 `snake_case`,空白折叠),再把渲染后的
|
|
62
|
+
文本节点接成一根带下标映射的串去 `indexOf`,找到就滚 `.knit-preview-body` 并给那一块一次 1.2s 的淡底
|
|
63
|
+
(`.knit-md-body .knit-doc-hit`,与 Coverage 那层同一档灰、同一个 `FLASH_MS`);**找不到就什么都不做**
|
|
64
|
+
(宁可不动,也不假装动了 —— 需求 §26)。两处都是真机实测后才对的:① DSH 的**行内 `code` 是
|
|
65
|
+
`inline-block`** —— 不把它算作行内,淡底会画在那一小片片上,所以 `DOC_INLINE_DISPLAY` 里补上
|
|
66
|
+
`inline-block / inline-flex / inline-grid / ruby`,落到所在的段落 / 列表项;② 同一根针在长文档里出现
|
|
67
|
+
几十次是常态,`docPickOffset()` 先**独特的那根针优先**、同档再按 `startOffset / 全文长度` 挑
|
|
68
|
+
**离锚点最近的那一次**(否则 `indexOf` 永远跳去全篇最早那次 —— 实测 CHANGELOG 就跳去了第 11 行的
|
|
69
|
+
同名行内 code 而不是第 36 行)。渲染仍是 DSH 的 `MarkdownText`(`DocPane` 只包一层,**不自己渲染
|
|
70
|
+
Markdown**);正文走**显式 `body` prop** 而不是 children(测试替身展开函数组件时只传 props)。
|
|
71
|
+
- **修一处在真机截图上发现的缺陷:Context Pack 的三层行不显示「命中片段」**(2026-10-07 验收时发现)。
|
|
72
|
+
宿主给三层条目的投影只有 `rel / title / summary / mtimeMs / kind / source / reason` 七个键
|
|
73
|
+
(`context.js`),**没有 `matches`** —— 于是 Primary / Supporting / Related 这九行(恰恰是最该给
|
|
74
|
+
片段的那几行)一条片段行都没渲染,只有「其他相关文档」区(取自 `docs`)有。修法是客户端按 `rel`
|
|
75
|
+
从 `visibleDocs` 取回 `matches`(`docs` 里本来就有这份数据 ⇒ **载荷零增长**;没有改成让宿主补键,
|
|
76
|
+
因为面板载荷已经吃掉 16 KB 预算的大部分)。新增守卫
|
|
77
|
+
`test/client.test.mjs`「v0.20 命中片段:三层(Primary/Supporting/Related)的行也要有片段行」——
|
|
78
|
+
把修法拿掉即变红(`README 在三层里,也必须有片段行`)。
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
- **暗色模式:把列表里最高那一档的白降下来,并全部改回 DSH 官方令牌**(2026-10-07 用户:
|
|
82
|
+
「暗色模式下高亮那个色值是不是纯白色……太亮了,就是太白了,看得有点犯晕」)。属实:命中段的底
|
|
83
|
+
原本是**纯白 13%**(`--knit-chip-bg`),是三档里最高的一档,而且那个 13% 是我们自己拍的数 ——
|
|
84
|
+
DSH 官方的 `--dsw-alias-interactive-bg-active` 在暗色下只有 `#ffffff24` = 14.12%(值取自
|
|
85
|
+
`dsh-client-ui-theme/lib/client.js`)。现在三档一律「官方透明度 × 固定比例」,且**暗色三个比例
|
|
86
|
+
比浅色各低 10%**:hover `7.84%×0.36`、active `14.12%×0.54`、chip `14.12%×0.81`(浅色比例是
|
|
87
|
+
`0.41` / `0.60` / `0.90`,暗色这组 = 浅色 ×0.9;**浅色的三个值一个字没动**)。顺手修掉两处「自己造一套」:
|
|
88
|
+
① 代码里有 6 处引用 `--dsw-alias-text-primary/secondary/tertiary` —— **DSH 全库零定义**(逐文件核实),
|
|
89
|
+
等于一直在静默失效:`color` 取到 unset ⇒ 命中段那一格的 hover 变色其实从来没生效过;已全部改回
|
|
90
|
+
官方 `--dsw-alias-label-primary/secondary/tertiary`,并补上官方浅色值作 fallback。
|
|
91
|
+
② 图标原来写死 `#000` / `#fff`:暗色的 `#fff` 比 DSH 自己的主文本色 `#f9fafb` 还亮,现在走
|
|
92
|
+
`--dsw-alias-label-primary`(令牌自己随主题切,那条 `body[data-ds-dark-theme] .knit-icon` 覆盖规则
|
|
93
|
+
因此删掉)。守卫:`test/client.test.mjs` 的灰底用例改成断言三档 + 「命中段必须比行选中更深」
|
|
94
|
+
+ 「不得亮过官方 active 14.12%」+「不许出现 `--dsw-alias-text-`」;`test/icon.test.mjs` 改成断言
|
|
95
|
+
官方令牌 + 不许再写死黑白。**测试数不变(635)**,是替换断言而不是加用例。
|
|
96
|
+
|
|
97
|
+
- **代码预览:语法高亮(2026-10-07 用户新增需求)**。用户原话:「我们现在在暗色模式下它是白色,
|
|
98
|
+
对于一个阅读代码的用户来说,它的可读性太低了;那在浅色模式下它也是一种黑色……你看这块要怎么治理一下?」
|
|
99
|
+
治理方式**不是自己配色**,而是**接 DSH 官方那一套**:
|
|
100
|
+
① 复用客户端**本来就在 require** 的 `@deepseek-ai/dsh-client-ui-primitives` 里的
|
|
101
|
+
`useCodeHighlighter(language)`(与 `MarkdownText` 同一个包 ⇒ **零新依赖、零新 specifier**);
|
|
102
|
+
② 语言标识**只认宿主分类层**给的 `language`(`classifyFile()` 的结论)—— 客户端自己不建第二张后缀表;
|
|
103
|
+
③ 颜色**只来自 `--shiki-*`**(定义在 `dsh-client-ui-theme`:`--shiki-token-keyword` 浅 `#d6336c` /
|
|
104
|
+
暗 `#faa2c1`、`comment` `#868e96` / `#adb5bd`、`string` `#2f9e44` / `#69db7c`……)⇒ 深浅两个主题
|
|
105
|
+
各自吃到官方调色板,不必为任何一个主题写死色值(这正是上面那条暗色治理的反面教材);
|
|
106
|
+
④ 拿不到高亮器(旧版 DSH / 包缺失)时**静默回落纯文本**,不报错、不空白。
|
|
107
|
+
**性能**:官方高亮器是同步的 shiki JS 引擎,真机实测约 170–560 ms / 千行 —— 4000 行的文件
|
|
108
|
+
(v0.19.1 基线 117 ms 打开)要 **1.3–2.2 s**,回车点开会白等一秒多。当天先收到「只上色前
|
|
109
|
+
800 行」,用户仍反馈「加载还是有点慢」,于是**再收一次**(用户原话:「要不代码模块我们换一个方案,
|
|
110
|
+
就是命中段才有颜色,不命中的段就不用上颜色,还是用原来的,浅色模式下用黑色,暗色模式下用白色
|
|
111
|
+
就可以了。我觉得这样可能就简单了。因为我刚刚去看了一下,加载还是有点慢,800 行也是很慢」):
|
|
112
|
+
上色范围 = **命中段前后各 `CODE_HL_PAD = 60` 行**,硬上限 `CODE_HL_MAX_LINES = 800`
|
|
113
|
+
(命中段本身可能几百行);**没有命中段(载荷里没有 `matches`)就一个 token 都不上色**,其余行
|
|
114
|
+
保持默认正文色(浅色黑 / 暗色白,跟随主题令牌);窗口之上 / 之下的行各是**一个**纯文本节点
|
|
115
|
+
(截断的是颜色,不是内容)。真机实测(同一浏览器会话连开 8 篇):`client.js`(4000 行)
|
|
116
|
+
**1496 → 424 ms**、`client.test.mjs`(4000 行)**2226 → 193 ms**,8 篇合计约 **5.9 s → 1.3 s**。
|
|
117
|
+
⚠️ 已知代价:窗口从半截注释 / 字符串中间开始时缺分词上下文,那一段可能**错色**(命中横带仍精确
|
|
118
|
+
标出行)。⚠️ 试过并**否决**「用
|
|
119
|
+
`useEffect` + `setTimeout(0)` 让出一帧、颜色随后补」:真机反而更慢(首个文本 3605 ms、颜色 3614 ms,
|
|
120
|
+
基线是同步版 1458 ms)—— `setTimeout(0)` 的回调在下一次绘制**之前**就跑掉了,纯文本那一帧从未
|
|
121
|
+
真正画出来,还多付了一次「文本节点 → 19782 个 span」的替换提交。
|
|
122
|
+
**渲染形状**:正文仍是**一个** `<pre>`,行间只隔一个 `'
|
|
123
|
+
'` 文本节点、**不包逐行元素** ——
|
|
124
|
+
行锚点(v0.20 §13)靠 `pre.scrollHeight / 行数` 量行高,逐行元素会把这个几何改掉;
|
|
125
|
+
窗口之外的头 / 尾也各是**一个**纯文本节点。高亮器返回的行数与正文对不上时一律退回纯文本
|
|
126
|
+
(宁可没颜色,也不能让颜色落在错误的代码上)。`useMemo` 记忆化,滚动 / 悬停 / 5 s 轮询的重渲染不重算。
|
|
127
|
+
测试 **+4(635 → 639)**:`test/client.test.mjs` 新增「逐 token 上色、颜色只来自 `--shiki-*`」
|
|
128
|
+
「宿主没导出高亮器时回落纯文本」「只给命中段前后各 60 行上色、窗口被 `CODE_HL_MAX_LINES` 截住」
|
|
129
|
+
「没有命中段就一个 token 都不上色」;`test/harness.mjs` 的假高亮器同时记录收到的**语言**与**正文**。
|
|
130
|
+
真机实测(Playwright,浅/暗两主题):颜色集合 = `--shiki-token-keyword/-comment/-string/-constant/
|
|
131
|
+
-function/-punctuation` + `--shiki-foreground`;命中横带几何、锚点滚动、横向滚动都没被 token 化破坏。
|
|
132
|
+
|
|
133
|
+
- **交互性能治理(2026-10-07,用户报「点击选中文档 / 代码都很卡、切换标签也卡顿」)**。先测后改:
|
|
134
|
+
宿主**不慢**(`/api/recent` 59–104 ms、`/api/context` 58 ms;R1 规模基准 1000 文件 cold 157 ms /
|
|
135
|
+
warm 21 ms,两条门槛都 PASS),慢在客户端四处:① **语法高亮每次重付**(`CodePane` 的 `useMemo`
|
|
136
|
+
只活在挂载期,切换类型档会卸载预览)⇒ 加**按文件缓存**(`CODE_HL_CACHE`,LRU 8 篇,键 =
|
|
137
|
+
`rel` + 窗口范围);② **FLIP 每次提交把整屏行全量量一遍**(`applyRowFlips` 的 `settled` 判据只看
|
|
138
|
+
视图签名)⇒ 加**行签名短路**(`rowSig` = 窗口尺寸 + 每行 `rel` / `tierKey` / `matches` 数 / mtime,
|
|
139
|
+
签名不变就复用上次的布局点、一行都不量);③ **每 5 s 轮询无条件 `setState` 一个新对象** ⇒
|
|
140
|
+
载荷签名与上次相同就**返回同一个 state 对象**(真 React 靠 `Object.is` 跳过整棵子树重渲染),
|
|
141
|
+
时间戳也改成渲染时刻取钟、不再为它重建 state;④ 行高 layout effect **先量后判** ⇒ 改成不补间就
|
|
142
|
+
提前返回(「别白量」:一屏挂着上万个 token span 时白量一次 ≈ 0.25 s @4× 节流)。
|
|
143
|
+
**改前 / 改后**(4× CPU 节流 + Retina,同一套脚本):切换类型档阻塞 **118 → 0–69 ms**、
|
|
144
|
+
点文档行阻塞 **415 → 172 ms**、同一篇代码关掉再开阻塞 **1390 → 261 ms**(CDP Profiler 里
|
|
145
|
+
`findNextMatchSync` = shiki 分词**从热点中消失**)、点代码行首开仍重(**2728 → 2217 ms**,剩下的是
|
|
146
|
+
第一次冷分词,第二次起走缓存)。测试 **+2(639 → 641)**:「同一篇代码收起再打开不再重新分词
|
|
147
|
+
(按文件缓存)」「载荷一字没变时,轮询不再落状态」—— 两条都**放过一次 bug**:把缓存 / 去重绕过
|
|
148
|
+
立刻变红(`actual 17 vs 11` / `actual 2 vs 1`)。⚠️ `test/harness.mjs` 的 `reset()` 补了
|
|
149
|
+
`timers.clear()` 与 `stateWrites()`:轮询链会自己续命、替身又从不跑 effect cleanup,上一个用例的
|
|
150
|
+
链会污染下一个用例的 hook 槽位(`v0.18 Coverage flash` 那条用例因此补了一次 `await harness.flush()`,
|
|
151
|
+
断言一个字没改)。
|
|
152
|
+
|
|
153
|
+
### 测试
|
|
154
|
+
|
|
155
|
+
- `npm test`:**641 / 641 通过**(v0.19.1 是 588;26 个测试文件)。
|
|
156
|
+
- **新增 `test/deep-context.test.mjs`(17 条)**:需求 §21 点名的 12 个用例逐条对应 + §17 的
|
|
157
|
+
媒体反例 + `windowTf` 单元 + 长归档分层集成 + **R2 面板预算**(≤24 篇带片段、每篇 ≤2 段、
|
|
158
|
+
片段 ≤`SNIPPET_CHARS`+8、载荷增量 ≤ 实测上界 16 KB / 每篇 700 B)。
|
|
159
|
+
- **新增 `test/deep-eval.test.mjs`(4 条)** 与 `test/eval/deep.mjs`(四指标的唯一定义处)。
|
|
160
|
+
- **新增 `test/deep-scale.test.mjs`(3 条)**:1000 文件规模的硬门槛与确定性。
|
|
161
|
+
- `test/client.test.mjs` **+17**(127 → 144):命中片段的渲染与点击、代码行锚点几何、样式纪律、i18n 键、
|
|
162
|
+
「媒体卡片即使被塞上 `matches` 也不渲染」,以及两条 2026-10-07 的裁决守卫:
|
|
163
|
+
**三层行也要有片段行**(`README 在三层里,也必须有片段行` —— 把客户端的 `withHits` 拿掉即红)、
|
|
164
|
+
**两条 metadata 合成一条**(`.knit-subrow` 存在、命中段在「正文命中」之前、有且只有一条 1px 竖线)、
|
|
165
|
+
**点整行带锚点**(行为断言 + `previewFor(doc, firstMatchOf(doc))` 源码守卫 —— 测试替身没有真实
|
|
166
|
+
布局,横带量不到行高,所以这条按 `AGENTS.md` §8.2 走「守代码形状 + 人眼」)。样式守卫同时钉住
|
|
167
|
+
`outline:none`(不再有白描边)、横带 `opacity:.5`、竖线是 1px 且不是虚线 / 渐变。
|
|
168
|
+
其中 **6 条是 Markdown 文本锚点**:归一化口径(`snake_case` 不许被当成强调)、取针(跳太短的行 /
|
|
169
|
+
去重 / 上限 / 越界不许闭眼切)、`docPickOffset`(重复的针按位置比例挑、独特的针优先、空正文返回 -1)、
|
|
170
|
+
`DocPane` 只包一层且没有 DOM 时不抛、接线守卫(`ratio` 一路传下去、`inline-block` 必须算行内)、
|
|
171
|
+
样式纪律(`transition` 在基础选择器上、时长 == `FLASH_MS`、不画边框)。
|
|
172
|
+
- `test/tool.test.mjs` +3:R2 预算守卫、镜像常量守卫(工具说的 256 KB 必须等于宿主真读的
|
|
173
|
+
`MAX_BODY_BYTES`,工具的 `SNIPPET_CHARS` 必须等于评分侧的)、**跨面集成守卫**(需求 §15:
|
|
174
|
+
同一条任务下 `knit_docs` 的 `matches` 行号必须与面板载荷 `docs[].matches` 逐条一致 ——
|
|
175
|
+
两侧各有自己的补偿路径〔面板靠客户端按 `rel` 取回、工具靠 `tool.js` 的 `matchesByRel`〕,
|
|
176
|
+
单面测试**各自都是绿的**,只有这条能抓住它们漂移)。
|
|
177
|
+
- **v0.19 的既有基线一条没改**(需求 §22):`test/eval.test.mjs` 与
|
|
178
|
+
`test/context-eval.test.mjs` 的断言、夹具与阈值全部原样通过。
|
|
179
|
+
|
|
180
|
+
### 改动量
|
|
181
|
+
|
|
182
|
+
- **26 个功能文件 = 20 改 + 6 新增**(另有 2 个不进包的开发文件:`tools/agents-budget.mjs`、`knit/AGENTS.md`;
|
|
183
|
+
发布提交合计 **33 处改动 = 25 改 + 8 新增** —— 多出来的 5 处是仓库侧的演示资产:`docs/README.md`
|
|
184
|
+
与重拍的四张图 `docs/screenshot.png` / `screenshot-media.png` / `screenshot-all.png` / `demo-reorder.gif`)。
|
|
185
|
+
仓库根就是 `knit/`;`git diff --shortstat` = `25 files changed, 2507 insertions(+), 218 deletions(-)`,
|
|
186
|
+
不含 8 个新文件。
|
|
187
|
+
> 2026-10-08 仓库侧又补了两轮**不进包**的改动:① **指令上下文治理**(`tools/agents-budget.mjs` 加
|
|
188
|
+
> `--claims` / `--strict` / 每层 sha256 指纹,常驻层改成触发词路由并净减 302 B,裁决记在
|
|
189
|
+
> `Knit-决策记录.md`);② 按 v0.20 界面**重拍四张演示图**(`docs/` 不在 `files` 白名单里,它们只出现在
|
|
190
|
+
> GitHub README 与市场详情页上)。两轮都**没动插件代码**(tarball 只因本节这几行文档改动而略变,
|
|
191
|
+
> 打包数字见下)。
|
|
192
|
+
- **新增 6 个**:`src/host/passage.js`、`test/deep-context.test.mjs`、`test/deep-eval.test.mjs`、
|
|
193
|
+
`test/deep-scale.test.mjs`、`test/eval/deep.mjs`、`tools/deep-benchmark.mjs`。
|
|
194
|
+
- `npm pack --dry-run`:**51 文件 / 557.0 kB 打包 / 1.66 MB 解包**(v0.19.1 是 46 文件 / 483.4 kB)。
|
|
195
|
+
⚠️ **shasum 故意不写在这一节里**:这份 CHANGELOG 本身就在 tarball 里,写自己的 shasum 会自指
|
|
196
|
+
(改一次就变一次)。**发布前那一刻的 shasum 记在 `03_发布/发布清单-v0.20.0.md`**(仓库外)。
|
|
197
|
+
|
|
198
|
+
### 基准
|
|
199
|
+
|
|
200
|
+
- **Deep Context Eval(需求 §23 的四个指标,`node -e "…runDeepEval()"`)**:
|
|
201
|
+
`DeepHitRate = 1.000`(v0.19 口径 **0.167**)、`PassageHit@1 = 1.000`、
|
|
202
|
+
`PassageRecall = 1.000`、`LongDocumentNoiseRate = 0.000`。5 条深度用例(词只在 2500 字之后、
|
|
203
|
+
尾部、一处两命中、代码函数附近、heading 附近)全部 `✔ 第 1 名`,长归档在 6 条用例里
|
|
204
|
+
**一次都没进 Primary/Supporting**。
|
|
205
|
+
- **R1 规模(`node tools/deep-benchmark.mjs`)**:100 文件 cold 63 ms;500 文件 164 ms;
|
|
206
|
+
1000 文件(进池 400 文档 + 100 代码)**157 ms**;真实工作区 1100 文件
|
|
207
|
+
(进池 400 + 300)**384 ms**。门槛 `1500 ms` / `1200 ms`,余量约 10× / 3×。
|
|
208
|
+
- **R2 预算(实测)**:面板载荷 24 篇带片段时 `+14760` 字节(每篇 615 B,片段最长 202 字符 ——
|
|
209
|
+
需求 §16 要的是更精准而不是更大,所以这条钉了自动守卫);`knit_docs` 渲染文本
|
|
210
|
+
1.04×(真机压力语料)~1.36×(最坏语料),均在 1.4× 以内。
|
|
211
|
+
- **§29 Step 8 真实验证**(真实工作区 `08_Knit`,非合成样本):`knit/CHANGELOG.md`
|
|
212
|
+
第 907 行的唯一词(正是那句「Matches come from the first 2500 characters…」)与
|
|
213
|
+
`knit/src/host/context.js` 第 133 行的唯一词,两者都**不在前 2500 字内** ——
|
|
214
|
+
v0.20 都能命中并给出覆盖该行的片段(名次 5/126 与 10/126)。
|
|
215
|
+
|
|
216
|
+
### 已知限制
|
|
217
|
+
|
|
218
|
+
- **Markdown 预览靠文本锚点跳段,不是行号**:`.md` 的「命中段」点击(以及直接点整行)会滚到**那一块**
|
|
219
|
+
(片段首行那根「针」落在哪个渲染块上)并闪一次底 —— 但它指的是一段**文本**,不是源文件第 N 行;
|
|
220
|
+
针在渲染结果里找不到时只打开、不滚动(宁可不动,也不指错)。代码文件才是精确到行的锚点。
|
|
221
|
+
- **单文件 256 KB 上限**:超过的部分不索引(输出里如实说明)。
|
|
222
|
+
- **媒体没有可检索正文**,不做 OCR、不调视觉模型(需求 §17)。
|
|
223
|
+
- **内存**:`body`(原文)与 `hayBody`(小写副本)现在都是整篇,每条约占 2× 正文;
|
|
224
|
+
缓存淘汰仍按 `bodyBytes` 计一份(已知偏差,未改)。
|
|
225
|
+
- **多词查询下,什么话题都提一句的长归档在文件级仍可能排在聚焦短文前面**:
|
|
226
|
+
`isDocHit` 管的是**分层**,不管文件名次。
|
|
227
|
+
|
|
228
|
+
### 没有实现(刻意)
|
|
229
|
+
|
|
230
|
+
Context Provenance、Context Graph UI、Pin-Lock、Context Bundle、Multi-Harness、MCP Server、
|
|
231
|
+
Doubao Adapter、Semantic Search、Embedding、Session Memory、AI Summary、新 Dashboard、
|
|
232
|
+
embedding / 向量数据库 / LLM / 网络 / LSP / Tree-sitter / AST 依赖图 / 语义模型 / 知识图谱,
|
|
233
|
+
以及把 Knit 做成 IDE / Code Intelligence / Language Server。
|
|
234
|
+
|
|
235
|
+
### 三问(每版必答,需求 §16)
|
|
236
|
+
|
|
237
|
+
1. **用户现在多获得了什么能力**:点开任何一篇(无论多长)都能直接看到**命中在哪几行**,并且
|
|
238
|
+
预览会**滚到那一段** —— 代码精确到行、Markdown 落到那一块。此前长文档里「第 5000 字之后」
|
|
239
|
+
等于不存在:列表只给文件名,预览从头开始,用户得自己在整篇里找。
|
|
240
|
+
2. **Agent 的 Context Consumption 多获得了什么能力**:**知道「文件内部哪里相关」**。
|
|
241
|
+
`knit_docs` 每条多一行 `match: lines 147–163 — …`(原文片段 + 行号),模型不必为定位再 `grep`
|
|
242
|
+
或整篇读一遍;诚实性文案也随之改成「全文都搜过了」(不再说「只看前 2500 字,更深的用 grep」)。
|
|
243
|
+
3. **明确没有做**:见上一节「没有实现(刻意)」。这一版**刻意不做**的四条最容易被误加的:
|
|
244
|
+
语义/向量检索(留 v0.24)、把片段当排序基本实体(文件仍是基本实体)、第二套预览框架、
|
|
245
|
+
在任何界面上显示分数 / 百分比 / 命中计数。已知边界另见「已知限制」。
|
|
246
|
+
|
|
247
|
+
### 升级注意
|
|
248
|
+
|
|
249
|
+
- **宿主不热加载** ⇒ 升级后要重启 DSH 才会生效(客户端 bundle 随页面刷新)。
|
|
250
|
+
|
|
6
251
|
## [0.19.1] - 2026-10-07
|
|
7
252
|
|
|
8
253
|
> **定位重构(只改对外叙事,一行代码没动)**。产品已经从 v0.12 时代的「更聪明的最近文件列表」
|
|
@@ -30,6 +275,10 @@
|
|
|
30
275
|
keywords 24 → 27(新增 `workspace-context` / `context-retrieval` / `context-lifecycle`)。
|
|
31
276
|
- **无代码变更**:`src/`、`test/`、`tools/` 一行没动,测试仍是 588 项全绿。
|
|
32
277
|
|
|
278
|
+
> ✅ **2026-10-07 已发布**:轻量 tag `v0.19.1` = 发布提交 `8dbbdef80c0d4d691b2724225ee6c4ec93aa6c34`;npm `latest = 0.19.1`、`gitHead` = 同一个提交、共 **16 个**版本;registry 真包 **46 文件 / 490 417 B 打包 / 1 452 990 B 解包 / shasum `a69ed85eb065335fda6a3e6cf91dfb346b76b71a`**;OIDC 可信发布 + provenance(`/slsa.dev/provenance/v1`);GitHub Release 正文取自本节(27 行 / 2020 字节),`publishedAt 2026-10-07T04:49:46Z`。
|
|
279
|
+
> ⚠️ 本地 `npm pack --dry-run` 报 46 文件 / 483.4 kB / shasum `5bfd69b0…` —— **本地字节与 registry 历来对不上**(v0.18 / v0.19.0 都这样),差的只是 tar/gzip 框架元数据,解包后清单与内容逐字一致。
|
|
280
|
+
> ⚠️ **这一行不在已发布的 tarball 里** —— 它在 publish 成功之后才写进来(下次 `npm view` 看到的是这份仓库里的文件)。
|
|
281
|
+
|
|
33
282
|
## [0.19.0] - 2026-10-07
|
|
34
283
|
|
|
35
284
|
> **Code Context**。产品概念从「Markdown / 图片 / 视频」变成「**文档 / 代码 / 媒体**」——
|
package/README.en.md
CHANGED
|
@@ -37,29 +37,31 @@ network, no latency, nothing leaves the machine.
|
|
|
37
37
|
> **which things in this project are worth looking at first for the task at hand — and what
|
|
38
38
|
> happened to them after they were read.**
|
|
39
39
|
|
|
40
|
-

|
|
41
41
|
|
|
42
42
|
*Screenshot from a real machine, not a mock-up: the same workspace, this one left on the **Code tab** —
|
|
43
43
|
since v0.19 source files are first-class citizens, just like Markdown.*
|
|
44
|
-
*The
|
|
45
|
-
|
|
46
|
-
*Click a row to expand the preview **in place
|
|
47
|
-
numbers
|
|
44
|
+
*The sub-row under each row says how it matched (a filename hit, a path hit, …) and **which passage**
|
|
45
|
+
of that file matched this query (`命中段 24–38`).*
|
|
46
|
+
*Click a row to expand the preview **in place**, stopped right on that passage: here
|
|
47
|
+
`knit/src/host/passage.js`, line numbers plus syntax highlighting, with the matched lines under a grey
|
|
48
|
+
band; the preview header holds only the path and four actions (copy / full screen / open locally / close).*
|
|
48
49
|
*The header holds only the path, one count and two toggles; whether the list runs by
|
|
49
50
|
relevance or by newest-first is decided by that pair of tabs on the left.*
|
|
50
51
|
*Since v0.14 the list is always one column: the rank number sits in its own column on the far left
|
|
51
52
|
(vertically centred on the title's first line), then Primary dot + title + relative time (time on the
|
|
52
53
|
right), then the summary. **The path lives in the preview header only** — the directory collapses to a `…/` placeholder (hover the path for the full relative path); rows no longer repeat it.*
|
|
53
54
|
|
|
54
|
-

|
|
55
56
|
|
|
56
|
-
*Order follows the conversation — same workspace, in a
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
*⚠️ The panel polls **every 5 seconds**, so the re-rank
|
|
62
|
-
|
|
57
|
+
*Order follows the conversation — same workspace, in a separate session: the conversation had been
|
|
58
|
+
about a release checklist, so the top of the list was that family of documents; ask
|
|
59
|
+
"how is BM25 weighted for the ranking?" and the list swaps over to the BM25 family, keeping the tier
|
|
60
|
+
headings and the **continuous rank numbers across all tiers**, with a one-line "why" under each row
|
|
61
|
+
(what matched, how, and which passage).*
|
|
62
|
+
*⚠️ The panel polls **every 5 seconds**, so the re-rank is not instantaneous: in this take the top rows
|
|
63
|
+
only swapped once that turn had moved along (the tens of seconds in between were cut out).
|
|
64
|
+
The GIF runs faster than real time.*
|
|
63
65
|
|
|
64
66
|
Scans Markdown / images / video across the project folder · Order follows the conversation · No model calls, no network
|
|
65
67
|
|
|
@@ -175,20 +177,21 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
175
177
|

|
|
176
178
|
|
|
177
179
|
*Media: square thumbnails, with the **column count following the panel width continuously** —
|
|
178
|
-
six columns at this width, cells about 110px. These are the workspace's real image and SVG files
|
|
179
|
-
particular workspace
|
|
180
|
-
(the solid black square is that icon, not a failed load). Videos get their first
|
|
181
|
-
a play glyph and a duration badge — this workspace simply has no video, so none
|
|
180
|
+
six columns at this width, cells about 110px. These are the workspace's real image and SVG files
|
|
181
|
+
(18 of them in this take); this particular workspace holds several screenshots, a demo GIF and one
|
|
182
|
+
single-colour SVG icon (the solid black square is that icon, not a failed load). Videos get their first
|
|
183
|
+
frame as a poster with a play glyph and a duration badge — this workspace simply has no video, so none
|
|
184
|
+
shows here.*
|
|
182
185
|
|
|
183
186
|

|
|
184
187
|
|
|
185
188
|
*All: the documents section shows at most 4, the **code section** shows at most 4 (each gets its own
|
|
186
|
-
"View all →" when truncated — here "4 /
|
|
189
|
+
"View all →" when truncated — here "4 / 21" and "4 / 8"), and the media grid (11 rows) comes last.*
|
|
187
190
|
|
|
188
191
|
⚠️ All three sections share the **same 40-item window** the host returns — a category that ranks past
|
|
189
192
|
40th by relevance drops out of the All view entirely. This screenshot uses the **Newest** sort: in this
|
|
190
193
|
workspace, under the default Relevance sort, media rank outside that window every time (at `limit=40`
|
|
191
|
-
those 40 rows are
|
|
194
|
+
those 40 rows are documents + code files). The **Media** and **Code** tabs are unaffected — they
|
|
192
195
|
request their own kind. A known defect, with reproduction and the fix recorded in
|
|
193
196
|
[`docs/README.md`](docs/README.md).*
|
|
194
197
|
|
|
@@ -305,6 +308,13 @@ Current task -> Workspace Retrieval -> Document + Code Candidates
|
|
|
305
308
|
version, not recall.
|
|
306
309
|
- **The type tabs become four**: `Docs / Code / Media / All`. The Code tab is **still driven by the
|
|
307
310
|
current task** — it is not a file tree of the project.
|
|
311
|
+
- **Syntax highlighting is DSH's own (v0.20)** — the client reuses
|
|
312
|
+
`useCodeHighlighter` from `@deepseek-ai/dsh-client-ui-primitives` and takes every colour from the
|
|
313
|
+
official `--shiki-*` tokens, so light and dark match DSH instead of inventing a palette. Only the
|
|
314
|
+
matched stretch is coloured (60 lines either side, window capped at 800) and the rest stays plain
|
|
315
|
+
text — a file with no match gets no colour at all (an un-capped 4k-line file
|
|
316
|
+
costs ~2 s); if the host does not export the hook (older DSH) or the line counts disagree, it falls
|
|
317
|
+
back to plain text silently.
|
|
308
318
|
- **No second engine**: no second retrieval path, no second lifecycle, no second store, no new
|
|
309
319
|
dependencies, no AST, no LSP, no embedding, no model call, no network, no IDE.
|
|
310
320
|
|
|
@@ -319,7 +329,8 @@ project are most relevant to what we're discussing?"* and get back **the same Co
|
|
|
319
329
|
panel shows — the `primary` / `supporting` / `related` tiers, each item carrying its path, title,
|
|
320
330
|
summary, a **structured reason** (`direct` / `titleMatch` / `summaryMatch` / `bodyMatch` /
|
|
321
331
|
`linkTarget` / `linkSource` / `related`), its **project role** (`impl` / `test` / `config` /
|
|
322
|
-
`design` / `doc`) and the matching snippet
|
|
332
|
+
`design` / `doc`) and the matching snippet **with its line range** (`match: lines 147–163 — …`) —
|
|
333
|
+
then open one of them with its own `read` tool.
|
|
323
334
|
|
|
324
335
|
**Why it helps**: to cite a document that already exists, an agent can only guess paths or glob
|
|
325
336
|
and `read` them one by one. Knit has **already computed that ranking** every refresh; this tool
|
|
@@ -335,7 +346,12 @@ Three details:
|
|
|
335
346
|
- **No relevance score in the result.** It is a *relative* score (something is always 100%, and it
|
|
336
347
|
may be a different document on the next refresh); shown to a model it reads as absolute confidence.
|
|
337
348
|
**The order is the relevance** — the same rule the panel follows.
|
|
338
|
-
- **
|
|
349
|
+
- **The whole file is searched** (since v0.20). Every file is split into structural passages and each
|
|
350
|
+
passage is scored, so "the relevant part is past the first 2,500 characters" no longer means
|
|
351
|
+
"unfindable"; a file over 256 KB is indexed only up to that size, and media has no text — both
|
|
352
|
+
boundaries are stated in the output rather than hidden.
|
|
353
|
+
- **No document bodies.** Only the matched passage (one per file at most, ≤200 characters) — the agent
|
|
354
|
+
has its own `read` tool; Knit *finds*, it does not *carry*.
|
|
339
355
|
- **No workspace means an error, never a fallback.** The HTTP route falls back to the process cwd
|
|
340
356
|
when a session can't be resolved (for older clients that send no session id); the tool has no such
|
|
341
357
|
baggage — falling back would scan an unrelated project and return *its* documents.
|
|
@@ -537,7 +553,7 @@ Newer messages weigh more: 3 / 2 / 1 / 1 …
|
|
|
537
553
|
```
|
|
538
554
|
IDF per term first: rarer in the corpus means more valuable
|
|
539
555
|
ln(1 + (N - df + 0.5) / (df + 0.5))
|
|
540
|
-
then a weighted sum over fields: title ×4 + summary ×2 +
|
|
556
|
+
then a weighted sum over fields: title ×4 + summary ×2 + the whole body ×1
|
|
541
557
|
each field saturated and length-normalised (k1 = 1.2, b = 0.3 / 0.5 / 0.75)
|
|
542
558
|
plus a 10% recency nudge (relevance still dominates)
|
|
543
559
|
```
|
|
@@ -674,7 +690,7 @@ feature request.
|
|
|
674
690
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
675
691
|
cd dsh-knit
|
|
676
692
|
|
|
677
|
-
npm test #
|
|
693
|
+
npm test # 641 tests, zero dependencies, no npm install needed
|
|
678
694
|
```
|
|
679
695
|
|
|
680
696
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -695,11 +711,12 @@ knit/
|
|
|
695
711
|
│ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
|
|
696
712
|
│ ├── host/links.js # reference parsing (pure; never touches ranking)
|
|
697
713
|
│ ├── host/classification.js # v0.19 file classification: kind / language / searchable / contextual
|
|
714
|
+
│ ├── host/passage.js # passage layer: chunking / passage scoring / line mapping (pure, zero I/O)
|
|
698
715
|
│ ├── host/context.js # context assembly: the three-tier Context Pack (pure, zero I/O)
|
|
699
716
|
│ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
|
|
700
717
|
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
701
718
|
│ └── client/client.js # dual-host registration + panel UI
|
|
702
|
-
└── test/ #
|
|
719
|
+
└── test/ # 641 tests
|
|
703
720
|
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
704
721
|
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
705
722
|
```
|
package/README.md
CHANGED
|
@@ -34,24 +34,26 @@ Knit 接的是**当前任务**和**整个工作区**之间那一层:从工作
|
|
|
34
34
|
> 最近文件记的是「你点开过什么、哪个更新」;Knit 回答的是
|
|
35
35
|
> **当前这个任务,项目里哪些东西最值得先看 —— 以及看过之后,事情变成了什么样。**
|
|
36
36
|
|
|
37
|
-

|
|
38
38
|
|
|
39
39
|
*真机截图(不是原型):同一个工作区,这张停在 **「代码」档** —— v0.19 起,源码和 Markdown 一样是一等公民。*
|
|
40
|
-
|
|
41
|
-
|
|
40
|
+
*每行下面的副行写着它是怎么被命中的(`直接命中 classification · changelog` / `路径命中 agents · classification`),*
|
|
41
|
+
*以及**命中段** —— 这次查询在这份文件里最像的是哪一段(`命中段 24–38`)。*
|
|
42
|
+
*点一行**就地**展开预览,并且**直接停在那一段**上:这里是 `knit/src/host/passage.js`,行号栏 + 语法高亮,*
|
|
43
|
+
*命中的那几行带一条灰底横带;预览头里只有路径和四个动作(复制 / 全屏 / 本地打开 / 关闭)。*
|
|
42
44
|
*头部只放路径、一个计数与两个开关;列表按「相关」还是「最新」排,由左边那一对页签决定 —— 按「相关」时排的就是你正在聊什么。*
|
|
43
|
-
*v0.14
|
|
45
|
+
*v0.14 起列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
|
|
44
46
|
*Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
|
|
45
47
|
*序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
|
|
46
48
|
*空着会被读成「漏了一个号」(2026-10-01)。*
|
|
47
49
|
|
|
48
|
-

|
|
49
51
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
52
|
+
*排序跟着对话走(同一个工作区、新开的一个会话):聊天里先聊过一轮发布清单,顶上几条就是发布清单那一族;*
|
|
53
|
+
*再问一句「Knit 里 BM25 的字段权重是怎么定的?」,列表整个换成 BM25 那一族 ——*
|
|
54
|
+
*分组标题与**跨三档连续的序号**随之一起出现,每篇下面多一行「为什么」(命中在哪、怎么命中的、命中段是哪一段)。*
|
|
55
|
+
*⚠️ 面板是**每 5 秒轮询一次**的,重排不是发消息那一瞬间:这一屏里顶上几条是这一轮对话推进之后才整个换掉的*
|
|
56
|
+
*(中间那几十秒被剪掉了)。动图比真实时间快。*
|
|
55
57
|
|
|
56
58
|
扫整个项目文件夹的文档 / 代码 / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
|
|
57
59
|
|
|
@@ -166,16 +168,16 @@ dsh plugin --profile web add dsh-knit
|
|
|
166
168
|

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

|
|
174
176
|
|
|
175
|
-
*全部:**文档区最多 4 条**、**代码区最多 4 条**(超出时各区右侧给「查看全部 →」,这一屏是「4 /
|
|
177
|
+
*全部:**文档区最多 4 条**、**代码区最多 4 条**(超出时各区右侧给「查看全部 →」,这一屏是「4 / 21」与「4 / 8」),最后是媒体网格(11 条)。*
|
|
176
178
|
*⚠️ 三个区共用宿主返回的**同一个 40 条窗口**:某一类如果按相关性排到第 40 名之外,「全部」档就整个看不到它。*
|
|
177
179
|
*这张图用的是**「最新」排序** —— 在这个工作区里,默认的「相关」排序下媒体恒定掉在 40 条窗口之外*
|
|
178
|
-
*(`limit=40` 时那 40
|
|
180
|
+
*(`limit=40` 时那 40 条全是文档 + 代码)。**「媒体」/「代码」档不受影响**,它们各自单独取。*
|
|
179
181
|
*这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
|
|
180
182
|
|
|
181
183
|
---
|
|
@@ -315,7 +317,12 @@ Markdown 仍是 `title ×4 / summary ×2 / body ×1`。**两套字段权重,
|
|
|
315
317
|
|
|
316
318
|
点一个代码文件,就在**面板下方就地展开**(和 Markdown 一模一样的位置、一样的交互,
|
|
317
319
|
没有新的弹窗):行号 + 等宽字体 + 横向滚动,页脚给复制与「本地打开」。
|
|
318
|
-
|
|
320
|
+
**有语法高亮,但用的是 DSH 自己的那一套**(v0.20,2026-10-07 按用户要求改):客户端复用
|
|
321
|
+
`@deepseek-ai/dsh-client-ui-primitives` 的 `useCodeHighlighter`,颜色全部来自官方的 `--shiki-*` 令牌
|
|
322
|
+
⇒ **浅色 / 暗色都跟 DSH 一致**,不自己造一套配色。**只给命中段那一带上色**(前后各 60 行,窗口
|
|
323
|
+
最多 800 行),其余行保持默认正文色 —— 没有命中段的文件一个 token 都不上色(高亮要跑同步分词,
|
|
324
|
+
4 千行整篇着色要 2 秒量级);宿主没导出这个 hook(旧版 DSH)或行数对不上 ⇒ 静默回落纯文本。
|
|
325
|
+
不做代码折叠、不做多标签、不做 git diff —— **Knit 不是代码浏览器**。
|
|
319
326
|
|
|
320
327
|
同类入口还有:双击进官方标签页预览(带 DSH 自己的渲染器)、`Esc` 收起、键盘 `↑↓` 预览。
|
|
321
328
|
|
|
@@ -330,7 +337,7 @@ Markdown 仍是 `title ×4 / summary ×2 / body ×1`。**两套字段权重,
|
|
|
330
337
|
`primary` / `supporting` / `related` 三层,每项带路径 + 标题 + 摘要 +
|
|
331
338
|
**结构化理由**(`direct` / `summaryMatch` / `bodyMatch` / `linkTarget` / `linkSource` / `related`)
|
|
332
339
|
+ **项目角色**(`impl` / `test` / `config` / `design` / `doc`)+
|
|
333
|
-
|
|
340
|
+
命中的那一小段原文**和它的行号区间**(`match: lines 147–163 — …`),再用它自己的 `read` 打开其中一篇。
|
|
334
341
|
|
|
335
342
|
**为什么有用**:agent 想引用项目里已有的文档时,只能靠猜路径、或者把 `glob`
|
|
336
343
|
出来的路径一个个 `read` 试过去。这份排序 Knit **每一轮已经算好了**,这个工具只是把它交出去 ——
|
|
@@ -346,7 +353,10 @@ Knit 一装上就有整个项目的历史文档可用。
|
|
|
346
353
|
没有两套排序逻辑,也没有两份规则。
|
|
347
354
|
- **不返回相关度分数**。它是**相对**分数(永远有一篇 100%,每次刷新可能换人当),
|
|
348
355
|
给模型看会被当成绝对置信度去推理。**顺序即相关度** —— 与面板同一条规矩。
|
|
349
|
-
-
|
|
356
|
+
- **搜的是全文**(v0.20 起)。每篇文件都按结构切成分片、逐片打分,所以「相关内容在前 2500 字之后」
|
|
357
|
+
不再等于「搜不到」;单文件超过 256 KB 时只索引到那里,媒体没有正文 —— 这两条边界会在输出里如实说明。
|
|
358
|
+
- **不返回正文**。只给命中片段(每篇最多一段、≤200 字符),agent 有自己的 `read` 工具;
|
|
359
|
+
Knit 负责**发现**,不负责**搬运**。
|
|
350
360
|
- **拿不到会话就报错,不兜底**。HTTP 路由在会话查不到时会兜底到进程 cwd
|
|
351
361
|
(兼容不带 sessionId 的老客户端),工具**没有这个包袱** ——
|
|
352
362
|
兜底只会扫到一个不相干的项目并返回它的文档。宁可报错,也不返回错的东西。
|
|
@@ -516,7 +526,7 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
516
526
|
|
|
517
527
|
```
|
|
518
528
|
每个词先算 IDF:在语料里越罕见越值钱 ln(1 + (N - df + 0.5) / (df + 0.5))
|
|
519
|
-
再按字段加权求和:标题 ×4 + 摘要 ×2 +
|
|
529
|
+
再按字段加权求和:标题 ×4 + 摘要 ×2 + 正文 ×1
|
|
520
530
|
每个字段都按 BM25 饱和 + 长度归一化(k1 = 1.2,b = 0.3 / 0.5 / 0.75)
|
|
521
531
|
再叠 10% 的时间新鲜度微调(主排序仍是相关性)
|
|
522
532
|
```
|
|
@@ -643,7 +653,7 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
643
653
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
644
654
|
cd dsh-knit
|
|
645
655
|
|
|
646
|
-
npm test #
|
|
656
|
+
npm test # 641 项,零依赖,不需要先 npm install
|
|
647
657
|
```
|
|
648
658
|
|
|
649
659
|
**改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
|
|
@@ -664,12 +674,13 @@ knit/
|
|
|
664
674
|
│ ├── host/classification.js # 文件分类层:kind / language / 能力位(纯函数,零 I/O)
|
|
665
675
|
│ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
|
|
666
676
|
│ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
|
|
677
|
+
│ ├── host/passage.js # 内容片段层:切分 / 片段打分 / 行号映射(纯函数,零 I/O)
|
|
667
678
|
│ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
|
|
668
679
|
│ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
|
|
669
680
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
670
681
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
671
|
-
└── test/ #
|
|
672
|
-
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
|
|
682
|
+
└── test/ # 641 项测试
|
|
683
|
+
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线 + Deep Context 四指标
|
|
673
684
|
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
674
685
|
```
|
|
675
686
|
|
package/SECURITY.md
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
> **Knit 的安全属性 —— 每一条都指向一个真实存在的检查。**
|
|
4
4
|
>
|
|
5
|
-
> 最后更新:2026-10-07(v0.
|
|
5
|
+
> 最后更新:2026-10-07(v0.20.0)
|
|
6
6
|
|
|
7
7
|
## 为什么有这份文件
|
|
8
8
|
|
|
@@ -47,6 +47,6 @@ Knit 的安全属性其实一直成立 —— 但它们此前只散落在文档
|
|
|
47
47
|
## 如何自己复核
|
|
48
48
|
|
|
49
49
|
```sh
|
|
50
|
-
npm test #
|
|
50
|
+
npm test # 641 项,含本节所有断言
|
|
51
51
|
npm test -- test/security.test.mjs # 只跑安全守卫
|
|
52
52
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.20.0",
|
|
4
4
|
"type": "module",
|
|
5
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",
|
|
@@ -23,7 +23,8 @@
|
|
|
23
23
|
"LICENSE"
|
|
24
24
|
],
|
|
25
25
|
"scripts": {
|
|
26
|
-
"
|
|
26
|
+
"agents:budget": "node tools/agents-budget.mjs",
|
|
27
|
+
"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 test/deep-context.test.mjs test/deep-eval.test.mjs test/deep-scale.test.mjs"
|
|
27
28
|
},
|
|
28
29
|
"dsh": {
|
|
29
30
|
"bundle": {
|