dsh-knit 0.5.1 → 0.11.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.en.md CHANGED
@@ -2,15 +2,15 @@
2
2
 
3
3
  > Your agent writes 20 documents a day. You can't find the one you just saw.
4
4
  > Knit puts them next to the conversation — whatever you're talking about, the relevant doc is on top.
5
+ >
6
+ > **Your agent has the same problem.** It gets the same ranking as a tool — so it reads one doc instead of five.
5
7
 
6
- <img src="https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png"
7
- alt="Screenshot from a real machine: the Knit sidebar listing the workspace documents, with a Markdown preview expanded in place"
8
- width="880">
8
+ ![Screenshot from a real machine: the Knit sidebar listing the workspace documents, with a Markdown preview expanded in place](docs/screenshot.png)
9
9
 
10
10
  *Screenshot from a real machine, not a mock-up: a workspace with 16 documents, the list plus an
11
- inline preview. Note the top line — **before a session has any conversation to go on, it falls
12
- back to newest-first and states its basis instead of pretending to rank.** Send a message and that
13
- line switches to what you're currently talking about.*
11
+ inline preview.*
12
+ *The top line follows whatever you're talking about; when there isn't enough conversation yet it
13
+ falls back to newest-first and states its basis.*
14
14
 
15
15
  Scans Markdown / images / video across the project folder · Order follows the conversation · No model calls, no network
16
16
 
@@ -51,20 +51,106 @@ Newer messages weigh more: 3 / 2 / 1 / 1 …
51
51
 
52
52
  - **ASCII words** — high value, one occurrence is enough (`chokidar`, `mtime`)
53
53
  - **Chinese 2/3-grams** — either occurring twice, or appearing in the newest message
54
+ - **Drop fragments that straddle a word boundary.** Chinese has no word boundaries, so
55
+ n-grams glue the last character of one word to the first of the next (「图片和」, 「个插」,
56
+ 「的排」). They share one trait — **the first or last character is a pure function word** —
57
+ and are dropped. Leave them in and they fill every candidate slot, pushing the real words
58
+ (「图片」, 「排序」) out of the query entirely
54
59
  - stop-word filtering plus greedy de-overlap (picking「相关性排序」drops「相关性」and「排序」)
55
60
 
56
- **3. Score the documents.** Weighted hits per keyword per document:
61
+ **3. Score the documents — BM25.**
57
62
 
58
63
  ```
59
- title ×4 + summary ×2 + first 2500 chars of body ×1
60
- each keyword caps at 6 hits (so long docs can't farm score)
64
+ IDF per term first: rarer in the corpus means more valuable
65
+ ln(1 + (N - df + 0.5) / (df + 0.5))
66
+ then a weighted sum over fields: title ×4 + summary ×2 + first 2500 chars of body ×1
67
+ each field saturated and length-normalised (k1 = 1.2, b = 0.3 / 0.5 / 0.75)
61
68
  plus a 10% recency nudge (relevance still dominates)
62
69
  ```
63
70
 
71
+ **Why BM25 and not "hits × weight"** (the original approach, since replaced):
72
+
73
+ - with no IDF, a term that appears **everywhere** (the project name) is worth as much as a
74
+ rare one — so the frequent term discriminates nothing and dilutes the rare ones
75
+ - with no length normalisation, **a long document wins by piling up hits**
76
+ - capping hits at 6 was a hand-drawn knee; `k1` / `b` exist precisely for this
77
+
78
+ Measured on `test/eval/fixture.mjs` (21 cases, both engines on the same corpus):
79
+
80
+ | | top-1 | MRR |
81
+ |---|---|---|
82
+ | old (weighted hits) | 76.2% | 0.830 |
83
+ | **BM25** | **95.2%** | **0.976** |
84
+
85
+ That eval runs inside `npm test`, and the baseline is **recomputed each run** from the old
86
+ engine frozen in `test/eval/legacy.mjs` — so "the new engine must be clearly better" is
87
+ verified automatically rather than asserted against a hard-coded number.
88
+
89
+ **Against counting keywords yourself** (`knit/tools/scale-benchmark.mjs`, N = 20/60/180/540):
90
+ the corpus is built with a real trap — 12 short, focused topic documents, plus a pile of long
91
+ distractors that mention every topic five times without explaining any of them (which is what a
92
+ real project's CHANGELOG looks like). Half the topic documents have descriptive filenames, half
93
+ are opaque.
94
+
95
+ | Approach | Descriptive filenames | Opaque filenames | MRR vs. scale |
96
+ |---|---|---|---|
97
+ | **Knit (BM25)** | **100%** | **100%** | **1.000 (flat)** |
98
+ | `grep -c` keyword counting | 17% | **0%** | 0.313 → **0.089** |
99
+ | Filenames only | 100% | **0%** | 0.602 |
100
+
101
+ Three things: **the ranking beats counting keywords yourself** (so having the agent recompute it
102
+ is irrational); **filename matching only works when names describe content**, and Knit is the
103
+ only approach that scores 100% either way; and **self-counting degrades as the corpus grows**.
104
+
105
+ **About the "sorted by「xxx」" line**: it shows the **span of your own text** that the matched
106
+ terms cover, not the raw candidate tokens. Chinese has no word boundaries, so candidates always
107
+ include fragments that straddle two words (「项目文档」 yields `项目文` / `目文档`), and showing
108
+ those renders as gibberish — merging their spans and slicing the original text recovers `项目文档`.
109
+ The label is **your own wording**, so its casing is preserved (type `BM25`, see `BM25`).
110
+
64
111
  All of it is string arithmetic — **no embeddings, no model calls**.
65
112
 
66
- **And the honest boundary**: with only one or two messages there are too few keywords, so it
67
- falls back to sorting by modification time and says so in the panel — it does not pretend to rank.
113
+ **And the honest boundaries**:
114
+
115
+ - **With only one or two messages** there are too few keywords, so it falls back to sorting by
116
+ modification time and says so in the panel — it does not pretend to rank
117
+ - **With only three to five documents IDF barely does anything**: `df` only takes a few values,
118
+ so its dynamic range collapses. The more documents, the better this ranking gets
119
+ - **It can only rank documents that share vocabulary with the conversation**: if no term matches,
120
+ every document scores the same and the order degrades to time
121
+
122
+ ---
123
+
124
+ ## Also for the agent: the `knit_docs` tool
125
+
126
+ The same ranking that you see in the panel is also exposed to the model.
127
+
128
+ Once installed, the agent's tool list gains `knit_docs`: it can ask *"which documents in this
129
+ project are most relevant to what we're discussing?"* and get back **relevance-ordered** paths,
130
+ titles and summaries — then open one with its own `read` tool.
131
+
132
+ **Why it helps**: to cite a document that already exists, an agent can only guess paths or glob
133
+ and `read` them one by one — slow and token-hungry. Knit has **already computed that ranking**
134
+ every refresh; this tool just hands it over.
135
+
136
+ **Read-only, and it stores nothing**: it reads the files that are already in the project — this is
137
+ not "memory". The difference from memory plugins is that **theirs start empty** (the agent has to
138
+ have saved something first), while Knit has the whole project's history from the moment you install it.
139
+
140
+ Three details:
141
+
142
+ - **No relevance score in the result.** It is a *relative* score (something is always 100%, and it
143
+ may be a different document on the next refresh); shown to a model it reads as absolute confidence.
144
+ **The order is the relevance** — the same rule the panel follows.
145
+ - **No document bodies.** The agent has its own `read` tool; Knit *finds*, it does not *carry*.
146
+ - **No workspace means an error, never a fallback.** The HTTP route falls back to the process cwd
147
+ when a session can't be resolved (for older clients that send no session id); the tool has no such
148
+ baggage — falling back would scan an unrelated project and return *its* documents.
149
+ Better to fail than to return the wrong thing.
150
+
151
+ > ⚠️ **The cost, stated plainly**: the tool description goes into the **system prompt of every
152
+ > request**. Installing Knit costs a few extra tokens per session. That is the price of giving the
153
+ > agent the capability.
68
154
 
69
155
  ---
70
156
 
@@ -90,7 +176,8 @@ as one of its tabs. Each host is an independent optional dependency; missing one
90
176
 
91
177
  | | |
92
178
  |---|---|
93
- | **Sorted by relevance to the current conversation** (local keyword matching, no model) | ✅ |
179
+ | **Sorted by relevance to the current conversation** (BM25 + IDF, fully local, no model) | ✅ |
180
+ | **The `knit_docs` tool for the agent**: the model can look up this project's most relevant documents itself | ✅ |
94
181
  | One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
95
182
  | Scans `.md` in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist`) | ✅ |
96
183
  | Each row shows H1 title (or filename) + relative time + first-paragraph summary | ✅ |
@@ -101,7 +188,8 @@ as one of its tabs. Each host is an independent optional dependency; missing one
101
188
  | Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
102
189
  | The **All** view splits into **two stacked sections**: docs (max 4, with "View all →" when truncated) and images & video (**never truncated**, count only) | ✅ |
103
190
  | Preview pane is height-draggable (20%–80%, remembered), fullscreen-able, `Esc` to exit | ✅ |
104
- | Double-click opens in a new tab | ✅ |
191
+ | **"Open locally"**: opens the previewed document in your default app (the path breadcrumb in the preview header is clickable too) | ✅ |
192
+ | Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
105
193
  | Filter box over title / summary / path | ✅ |
106
194
  | **Click the workspace path** to open the project folder in your file manager | ✅ |
107
195
  | **Hover the entry button to peek**: a read-only floating list of the 5 most recent docs; click to open the right sidebar (doesn't push the layout) | ✅ |
@@ -109,6 +197,7 @@ as one of its tabs. Each host is an independent optional dependency; missing one
109
197
  | Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
110
198
  | Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
111
199
  | Zero model calls, zero network egress | ✅ |
200
+ | **A `knit_docs` tool for the agent** — read-only, so the model can find this project's relevant docs itself | ✅ |
112
201
 
113
202
  > Relevance is deliberately **not visualised** (no percentages, no bars) — the ranking itself is
114
203
  > the answer; position is relevance.
@@ -120,6 +209,7 @@ as one of its tabs. Each host is an independent optional dependency; missing one
120
209
  - Scans `.md`, images and video **inside the current session workspace** (anything resolving
121
210
  outside is rejected); for media it reads metadata only, never the pixels
122
211
  - Reads only **the current session's** conversation events (used for ranking)
212
+ - The `knit_docs` tool is **read-only**: it writes no files and persists no index
123
213
  - **Makes no outbound network requests**: the client's `fetch` calls all point to
124
214
  the plugin's own same-origin routes
125
215
  - **No install-time scripts** (no `install` / `postinstall`)
@@ -130,14 +220,21 @@ as one of its tabs. Each host is an independent optional dependency; missing one
130
220
 
131
221
  The relevance figure only affects ordering — it is **never displayed and never sent anywhere**.
132
222
 
223
+ > Every claim above is guarded by an automated check, listed one by one in
224
+ > **[SECURITY.md](SECURITY.md)** — each property points at a test that actually exists.
225
+ > `npm test` verifies that the table itself has not rotted.
226
+
133
227
  ---
134
228
 
135
229
  ## Known limitations
136
230
 
137
231
  - **Short conversations degrade the ranking**: one or two messages give too few keywords, so it
138
232
  falls back to modification time and says so in the panel
139
- - **Chinese segmentation is n-gram approximation**: no tokenizer dependency was added; good
140
- enough in practice, not linguistically precise
233
+ - **Chinese segmentation is n-gram approximation**: no tokenizer dependency was added. Fragments
234
+ that straddle two words are dropped when they start/end on a function character, and the
235
+ remaining hits are **merged by their spans** back into real words — but an **isolated fragment**
236
+ (like 「视频上」, with nothing overlapping to merge with) can still appear in the
237
+ "sorted by「xxx」" line
141
238
  - **The right sidebar's default page becomes the guide**: DSH's rule is "if there's exactly one
142
239
  guide entry, open it directly"; the built-in Files entry takes that slot, so expanding the
143
240
  sidebar shows the guide first and Knit needs one more click on its pill
@@ -155,7 +252,7 @@ The relevance figure only affects ordering — it is **never displayed and never
155
252
  git clone https://github.com/PolinniZhong/dsh-knit.git
156
253
  cd dsh-knit
157
254
 
158
- npm test # 162 tests, zero dependencies, no npm install needed
255
+ npm test # 215 tests, zero dependencies, no npm install needed
159
256
  ```
160
257
 
161
258
  **How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
@@ -173,9 +270,9 @@ knit/
173
270
  ├── assets/ # icon source (path inlined into client.js)
174
271
  ├── src/
175
272
  │ ├── host/index.js # /knit/api/recent · /doc · /raw
176
- │ ├── host/relevance.js # the relevance engine (pure functions)
273
+ │ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
177
274
  │ └── client/client.js # dual-host registration + panel UI
178
- └── test/ # 162 tests
275
+ └── test/ # 215 tests
179
276
  ```
180
277
 
181
278
  Details and trade-offs live in the source comments; see [CONTRIBUTING.md](CONTRIBUTING.md)
package/README.md CHANGED
@@ -2,14 +2,13 @@
2
2
 
3
3
  > Agent 一天产出 20 篇文档,你找不到刚才那篇。
4
4
  > Knit 把它们放到对话旁边 —— 你正在聊什么,相关的那篇就在最上面。
5
+ >
6
+ > **你的 agent 也一样。** 同一份排序也给它当工具用 —— 它读一篇,而不是翻五篇。
5
7
 
6
- <img src="https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png"
7
- alt="Knit 面板真机截图:右侧栏列出工作区里的文档,下方就地展开 Markdown 预览"
8
- width="880">
8
+ ![Knit 面板真机截图:右侧栏列出工作区里的文档,下方就地展开 Markdown 预览](docs/screenshot.png)
9
9
 
10
- *真机截图(不是原型):一个含 16 篇文档的工作区,列表 + 就地预览。
11
- 注意顶行:**新会话还没聊起来时,它退回按最新排并如实说明依据,不假装排了个序** ——
12
- 一发出消息,这一行就会换成按你正在聊什么排序。*
10
+ *真机截图(不是原型):一个含 16 篇文档的工作区,列表 + 就地预览。*
11
+ *顶行会跟着你正在聊什么变;对话内容还不足时它退回按时间排,并如实说明依据。*
13
12
 
14
13
  扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
15
14
 
@@ -46,20 +45,66 @@ dsh plugin --profile web add dsh-knit
46
45
 
47
46
  - **英文词**:取值很高,出现 1 次就要(`chokidar`、`mtime` 这种精确词)
48
47
  - **中文 2/3-gram**:出现 2 次,或出现在最新那条消息里
48
+ - **丢掉跨词边界的碎片**:中文没有词边界,n-gram 会把相邻两个词的字粘起来
49
+ (「图片和」「个插」「的排」)。这类碎片有个共同特征 —— **首字或尾字是纯虚词**,
50
+ 一律丢掉。不丢的话它们会占满候选位,把「图片」「排序」这些真词全挤出去
49
51
  - 虚词表过滤 + 贪心去重叠(选了「相关性排序」就不再算「相关性」和「排序」)
50
52
 
51
- **3. 给文档打分。** 每个词对每篇文档算加权命中:
53
+ **3. 给文档打分 —— BM25。**
52
54
 
53
55
  ```
54
- 标题 ×4 + 摘要 ×2 + 正文前 2500 字 ×1
55
- 单个词命中数封顶 6 次(防止长文档堆词刷分)
56
+ 每个词先算 IDF:在语料里越罕见越值钱 ln(1 + (N - df + 0.5) / (df + 0.5))
57
+ 再按字段加权求和:标题 ×4 + 摘要 ×2 + 正文前 2500 字 ×1
58
+ 每个字段都按 BM25 饱和 + 长度归一化(k1 = 1.2,b = 0.3 / 0.5 / 0.75)
56
59
  再叠 10% 的时间新鲜度微调(主排序仍是相关性)
57
60
  ```
58
61
 
62
+ **为什么是 BM25 而不是「命中次数 × 权重」**(那是最初的做法,已换掉):
63
+
64
+ - 没有 IDF 时,**语料里到处都是的词**(比如项目名)和罕见词一样值钱,
65
+ 于是高频词不产生任何区分度,还稀释掉罕见词的分辨力
66
+ - 没有长度归一化时,**长文档靠堆词就能赢**
67
+ - 命中次数封顶 6 次是个手写硬拐点;`k1` / `b` 才是为这件事设计的
68
+
69
+ 实测(`test/eval/fixture.mjs`,21 个用例,两版引擎跑同一套语料):
70
+
71
+ | | top-1 命中 | MRR |
72
+ |---|---|---|
73
+ | 旧做法(加权命中) | 76.2% | 0.830 |
74
+ | **BM25** | **95.2%** | **0.976** |
75
+
76
+ 这套评测在 `npm test` 里跑,**基线由 `test/eval/legacy.mjs` 冻结的旧引擎现算**,
77
+ 所以「新引擎必须显著更好」是自动验证的,而不是引用一个写死的数字。
78
+
79
+ **跟「自己数关键词」比**(`knit/tools/scale-benchmark.mjs`,N = 20/60/180/540):
80
+ 语料刻意做成有真实陷阱的 —— 12 篇短而聚焦的主题文档,加上一堆「每条主题各提 5 次、
81
+ 但哪一件都没讲」的长干扰文档(真实项目里的 CHANGELOG 就长这样)。
82
+ 主题文档一半用描述性文件名,一半看不出内容。
83
+
84
+ | 路线 | 文件名说得清 | 文件名看不出 | MRR 随规模 |
85
+ |---|---|---|---|
86
+ | **Knit(BM25)** | **100%** | **100%** | **1.000(不随规模变)** |
87
+ | 自己 `grep -c` 数关键词 | 17% | **0%** | 0.313 → **0.089** |
88
+ | 只看文件名 | 100% | **0%** | 0.602 |
89
+
90
+ 三件事:**排序强于自己数关键词**(所以让 agent 重算是不理性的);
91
+ **文件名匹配只在名字描述内容时好使**,Knit 是唯一两种都 100% 的;
92
+ **自己数的可靠性随规模单调下降**。
93
+
94
+ **关于那行「按「xxx」排序」**:显示的是**命中词在原文里覆盖的那一段**,不是词表里的碎片。
95
+ 中文没有词边界,候选里必然有跨词的碎片(「项目文档」会切出 `项目文` / `目文档`),
96
+ 直接显示就成了乱码 —— 把它们的**区间合并**再切原文,正好还原出 `项目文档`。
97
+ 标签是你**自己打的字**,所以大小写原样保留(打 `BM25` 就显示 `BM25`)。
98
+
59
99
  全是字符串运算 —— **没有 embedding,没有模型调用**。
60
100
 
61
- **并且老实说边界**:对话只有一两句时关键词太少,它会退回按修改时间排,
62
- 并在面板上说明这一点 —— 不假装排了个序。
101
+ **并且老实说边界**:
102
+
103
+ - **对话只有一两句时**关键词太少,它会退回按修改时间排,并在面板上说明这一点 —— 不假装排了个序
104
+ - **语料只有三五篇时 IDF 几乎不起作用**:`df` 的取值范围太窄,动态范围被压扁。
105
+ 文档越多这个排序越准 —— 这正是它该有的样子
106
+ - **它只能排「和对话有共同词汇」的文档**:如果一个词都没命中,所有文档同分,
107
+ 名次就退化成按时间排
63
108
 
64
109
  ---
65
110
 
@@ -85,7 +130,8 @@ dsh plugin --profile web add dsh-knit
85
130
 
86
131
  | 能力 | |
87
132
  |---|---|
88
- | **按当前对话相关性排序**(纯本地关键词匹配,零模型) | ✅ |
133
+ | **按当前对话相关性排序**(BM25 + IDF,纯本地,零模型) | ✅ |
134
+ | **给 agent 用的 `knit_docs` 工具**:让模型自己查「这个项目里跟当前话题最相关的文档」 | ✅ |
89
135
  | 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
90
136
  | 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
91
137
  | 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
@@ -96,7 +142,8 @@ dsh plugin --profile web add dsh-knit
96
142
  | 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
97
143
  | 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
98
144
  | 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出 | ✅ |
99
- | 双击在新标签页打开 | ✅ |
145
+ | **「在本地打开」**:用系统默认应用打开当前预览的这篇文档(预览头的路径面包屑同样可点) | ✅ |
146
+ | 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
100
147
  | 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
101
148
  | **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
102
149
  | **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局) | ✅ |
@@ -109,10 +156,41 @@ dsh plugin --profile web add dsh-knit
109
156
 
110
157
  ---
111
158
 
159
+ ## 也给 agent 用:`knit_docs` 工具
160
+
161
+ 同一份排序,除了给你看,也开了一个口子给模型。
162
+
163
+ 装好之后,agent 的工具列表里会多一个 `knit_docs`:它可以问
164
+ 「这个项目里跟当前话题最相关的文档是哪几篇」,拿到**按相关性排好序**的
165
+ 路径 + 标题 + 摘要,再用它自己的 `read` 打开其中一篇。
166
+
167
+ **为什么有用**:agent 想引用项目里已有的文档时,只能靠猜路径、或者把 `glob`
168
+ 出来的路径一个个 `read` 试过去 —— 费 token 又慢。而这份排序 Knit **每一轮已经算好了**,
169
+ 这个工具只是把它交出去。
170
+
171
+ **只读,且不存储任何东西**:它读的是项目里**现成的文件**,不是「记忆」。
172
+ 和记忆类插件的区别是:**它们起点是空的**(agent 得先记过才有东西可召回),
173
+ Knit 一装上就有整个项目的历史文档可用。
174
+
175
+ 三个细节:
176
+
177
+ - **不返回相关度分数**。它是**相对**分数(永远有一篇 100%,每次刷新可能换人当),
178
+ 给模型看会被当成绝对置信度去推理。**顺序即相关度** —— 与面板同一条规矩。
179
+ - **不返回正文**。agent 有自己的 `read` 工具;Knit 负责**发现**,不负责**搬运**。
180
+ - **拿不到会话就报错,不兜底**。HTTP 路由在会话查不到时会兜底到进程 cwd
181
+ (兼容不带 sessionId 的老客户端),工具**没有这个包袱** ——
182
+ 兜底只会扫到一个不相干的项目并返回它的文档。宁可报错,也不返回错的东西。
183
+
184
+ > ⚠️ **代价要说清楚**:工具描述会进**每一次请求的系统提示词**。
185
+ > 装 Knit 的用户每个会话都会多占一点 token。这是「让 agent 有能力」的必要成本。
186
+
187
+ ---
188
+
112
189
  ## 它读什么,不读什么
113
190
 
114
191
  - 扫描**当前会话工作区内**的 `.md`、图片与视频(路径越出工作区一律拒绝);媒体只取元信息,不读画面内容
115
192
  - 只读**当前会话**的对话事件(用来排序)
193
+ - `knit_docs` 工具**只读**:不写任何文件、不落盘任何索引
116
194
  - **不发起任何对外网络请求**:客户端的 `fetch` 都指向插件自己的同源路由
117
195
  - **没有安装期脚本**(无 `install` / `postinstall`)
118
196
  - **零依赖** —— 装完不需要构建授权,也没有构建步骤
@@ -121,12 +199,20 @@ dsh plugin --profile web add dsh-knit
121
199
 
122
200
  面板里那份「相关度」只影响排序,**不显示也不外传**。
123
201
 
202
+ > 上面每一条都有自动化检查守着,逐条列在 **[SECURITY.md](SECURITY.md)** 里 ——
203
+ > 每条属性都指向一个真实存在的测试。`npm test` 会校验那张表本身没腐烂。
204
+
124
205
  ---
125
206
 
126
207
  ## 已知限制
127
208
 
128
209
  - **对话太短时排序会退化**:只有一两句时关键词不足,退回按修改时间,并在面板上说明
129
- - **中文分词是 n-gram 近似**:没有引入分词库(那会带来依赖),效果够用但不算精细
210
+ - **中文分词是 n-gram 近似**:没有引入分词库(那会带来依赖)。跨词边界的碎片已经按
211
+ 「首尾是虚词」丢掉、并按**原文区间合并**还原成真词,但**仍可能有孤立碎片**
212
+ (比如「视频上」这种没有重叠伙伴的)出现在「按「xxx」排序」那行里 ——
213
+ 匹配不上任何文档的碎片不参与打分
214
+ - **语料太少时 IDF 作用有限**:只有三五篇文档时,`df` 的取值范围被压扁,
215
+ 排序更接近按命中次数排;文档越多越准
130
216
  - **右侧栏默认页会变成 guide**:DSH 的规则是「guide 入口只有一个才直接开那一页」,
131
217
  内置 Files 占了一个,所以展开右侧栏先看到 guide,需要点一下胶囊
132
218
  - **媒体只认常见格式与大小**:图片 `png/jpg/jpeg/gif/webp/avif/bmp/ico/svg`、
@@ -142,7 +228,7 @@ dsh plugin --profile web add dsh-knit
142
228
  git clone https://github.com/PolinniZhong/dsh-knit.git
143
229
  cd dsh-knit
144
230
 
145
- npm test # 162 项,零依赖,不需要先 npm install
231
+ npm test # 215 项,零依赖,不需要先 npm install
146
232
  ```
147
233
 
148
234
  **改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
@@ -160,9 +246,11 @@ knit/
160
246
  ├── assets/ # 图标源文件(path 已内联进 client.js)
161
247
  ├── src/
162
248
  │ ├── host/index.js # /knit/api/recent · /doc · /raw
163
- │ ├── host/relevance.js # 相关性引擎(纯函数)
249
+ │ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
250
+ │ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
164
251
  │ └── client/client.js # 双宿主注册 + 面板 UI
165
- └── test/ # 162 项测试
252
+ └── test/ # 215 项测试
253
+ └── eval/ # 离线质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
166
254
  ```
167
255
 
168
256
  细节和取舍写在源码注释里;贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md),
package/SECURITY.md ADDED
@@ -0,0 +1,51 @@
1
+ # Security
2
+
3
+ > **Knit 的安全属性 —— 每一条都指向一个真实存在的检查。**
4
+ >
5
+ > 最后更新:2026-09-18(v0.11.0)
6
+
7
+ ## 为什么有这份文件
8
+
9
+ Codex 插件生态**强制**每个插件过安全扫描([HOL `plugin-scanner`](https://github.com/hashgraph-online/hol-guard),
10
+ 准入线 ≥80/130 分),给六维信任分,还把结果发成公开数据集。
11
+ DSH 的插件市场**只有一条「描述只说功能」的文案规范,没有任何安全评分**
12
+ (对比见 `00_调研与规划/竞品调研-Codex插件生态.md`)。
13
+
14
+ Knit 的安全属性其实一直成立 —— 但它们此前只散落在文档和代码注释里,
15
+ **没有任何一处能被机器核验**。在一个人人自述的市场里,「**能被核验**」本身就是差异化。
16
+
17
+ 所以这份表格的规矩是:
18
+
19
+ - **✅ 只给真的有检查守着的属性**;没检查的宁可不写
20
+ - 每条 ✅ 的「证据」列必须指向一个**真实路径**
21
+ - **允许出现 ⚠️/❌** —— 没验证的事不装成验证过
22
+ - `test/security.test.mjs` 会**自动校验这张表**:引用的路径必须存在、
23
+ ✅ 行必须指向具体检查、每行必须有状态列。**表格腐烂会直接让测试变红。**
24
+
25
+ ## 属性对照表
26
+
27
+ | 属性 | 状态 | 证据(指向真实的检查) |
28
+ |---|---|---|
29
+ | 零运行时依赖 | ✅ | `package.json` 的 `dependencies` 为空;`test/security.test.mjs` 断言 |
30
+ | 无安装期脚本 | ✅ | `package.json` 只有 `test` 一个 script,无 `install`/`postinstall`/`prepare`;`test/security.test.mjs` 断言 |
31
+ | 读文件接口守在会话工作区内 | ✅ | `test/host.test.mjs` 的越界用例(解析后必须落在工作区内,否则一律拒绝) |
32
+ | `/knit/api/raw` 叠扩展名白名单 | ✅ | `test/host-http.test.mjs`(非图片/视频扩展名一律拒绝) |
33
+ | 只允许 GET、只允许回环地址 | ✅ | `test/host-http.test.mjs` |
34
+ | 响应带 `nosniff` 与 `default-src 'none'; sandbox` | ✅ | `test/host-http.test.mjs`(两个指令各自断言) |
35
+ | 零网络出口:客户端 `fetch` 全部同源相对路径 | ✅ | `src/client/client.js` 的三个接口常量都是 `/knit/api/*`;`test/security.test.mjs` 断言无协议头 |
36
+ | 宿主半边不 import `@deepseek-ai/*` | ✅ | `test/security.test.mjs` 扫三个宿主文件,注释里提到可以、真实 `import` 不行 |
37
+ | `knit_docs` 工具只读,不写任何文件 | ✅ | `src/host/tool.js` 只调注入进来的 `scan` 与只读的 `readDocument`;无写文件调用 |
38
+ | 未经第三方安全审计 | ⚠️ | **如实说明**:这张表是**自证**。没有外部审计报告,也没有自动化扫描评分 —— 它不等于「已证明安全」 |
39
+
40
+ ## 不在这张表里的东西
41
+
42
+ - **DSH 主程序本身的安全性**不在 Knit 的责任范围内。
43
+ - **用户装的其他插件**不受 Knit 影响。
44
+ - 装任何插件都等于在本机跑第三方代码。**建议只装你信任的来源。**
45
+
46
+ ## 如何自己复核
47
+
48
+ ```sh
49
+ npm test # 231 项,含本节所有断言
50
+ npm test -- test/security.test.mjs # 只跑安全守卫
51
+ ```
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "dsh-knit",
3
- "version": "0.5.1",
3
+ "version": "0.11.0",
4
4
  "type": "module",
5
- "description": "Knit — recent Markdown, images and video in the DSH sidebar, sorted by relevance to the current conversation, with inline previews and HTTP Range streaming. Zero model calls.",
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, so it reads one doc instead of five. Zero model calls, zero network.",
6
6
  "main": "./src/host/index.js",
7
7
  "exports": {
8
8
  ".": "./src/host/index.js",
@@ -16,10 +16,11 @@
16
16
  "test",
17
17
  "cordis.patch.yml",
18
18
  "README.md",
19
+ "SECURITY.md",
19
20
  "LICENSE"
20
21
  ],
21
22
  "scripts": {
22
- "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"
23
+ "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/security.test.mjs"
23
24
  },
24
25
  "dsh": {
25
26
  "bundle": {
@@ -53,7 +54,9 @@
53
54
  "最近文档",
54
55
  "侧边栏",
55
56
  "知识管理",
56
- "图片视频"
57
+ "图片视频",
58
+ "agent-tool",
59
+ "model-tool"
57
60
  ],
58
61
  "repository": {
59
62
  "type": "git",