dsh-knit 0.19.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 +36 -0
- package/README.en.md +264 -200
- package/README.md +153 -93
- package/SECURITY.md +1 -1
- package/package.json +5 -2
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,33 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.19.1] - 2026-10-07
|
|
7
|
+
|
|
8
|
+
> **定位重构(只改对外叙事,一行代码没动)**。产品已经从 v0.12 时代的「更聪明的最近文件列表」
|
|
9
|
+
> 长成了 **Workspace Context Retrieval**:当前任务 → 工作区检索 → 主要 / 辅助 / 相关 →
|
|
10
|
+
> Context Pack → Agent 读取 → 读取证据 → 工作区变化 → 重新读取。v0.19.1 把 README、
|
|
11
|
+
> 仓库 About 与市场条目文案统一到这条主线上,并把「怎么排序」(BM25 / IDF)
|
|
12
|
+
> 从卖点降级成证据。
|
|
13
|
+
|
|
14
|
+
### 变化
|
|
15
|
+
|
|
16
|
+
- **`README.md` / `README.en.md` 第一屏整体换掉**。定位句升级为
|
|
17
|
+
*Task-aware workspace context retrieval and lifecycle tracking for AI coding agents.*
|
|
18
|
+
(面向 AI Coding Agent 的任务感知工作区上下文检索与生命周期追踪),并给出
|
|
19
|
+
Find → Organize → Track 的主线图。原来开头的「Agent 一天产出 20 篇文档,你找不到刚才那篇」
|
|
20
|
+
降级成 `## 为什么需要它` 里的一句引文。
|
|
21
|
+
- **「这不就是个最近文件列表吗?」不再是「是的,但…」**。改成
|
|
22
|
+
`## 「最近文件列表」和「代码浏览器」都不是它`,用一张五行对照表(范围 / 排序 / 输出 /
|
|
23
|
+
给谁 / 之后)说明区别,不再替读者接受「最近文件」这个框架。
|
|
24
|
+
- **BM25 降级为证据**。原「「相关」是怎么算出来的」改成
|
|
25
|
+
`## 检索是怎么算的(实现细节,不是产品定义)`,正文前加一句「这一节是证据,不是卖点」。
|
|
26
|
+
- **章节重排**:两份 README 的章节顺序现在一一对应;英文版原先嵌在
|
|
27
|
+
"Did it actually get used?" 里的 `### v0.19: code as context (Code Context)`
|
|
28
|
+
提升成独立的 `## Code as context (v0.19)`。
|
|
29
|
+
- **`package.json`**:`description` 换成同时讲 retrieval 与 lifecycle tracking 的一版;
|
|
30
|
+
keywords 24 → 27(新增 `workspace-context` / `context-retrieval` / `context-lifecycle`)。
|
|
31
|
+
- **无代码变更**:`src/`、`test/`、`tools/` 一行没动,测试仍是 588 项全绿。
|
|
32
|
+
|
|
6
33
|
## [0.19.0] - 2026-10-07
|
|
7
34
|
|
|
8
35
|
> **Code Context**。产品概念从「Markdown / 图片 / 视频」变成「**文档 / 代码 / 媒体**」——
|
|
@@ -187,6 +214,15 @@
|
|
|
187
214
|
400 文档截断 + 300 代码(243 条被 cap 挡下)+ 400 媒体,语料 400 → 700 ——
|
|
188
215
|
`MAX_CODE = 300` 在这里正好起到「别让代码把原有 Markdown 上下文挤出去」的作用。
|
|
189
216
|
|
|
217
|
+
> ✅ **2026-10-07 已发布**:`v0.19.0` = 轻量 tag = npm `gitHead` = `22ab1346f1b8e145ae0940490af13bca02d9ab08`
|
|
218
|
+
> · npm `latest = 0.19.0` · **46 文件 / 486.8 kB 打包 / 1.4 MB 解包** / shasum `7f67559d005fcf19405a96ab459d7aac6515a99f`。
|
|
219
|
+
> (本地 `npm pack --dry-run` 报的是 479.8 kB / `291a9150…`;两个 tarball 的**文件清单与解包内容逐字一致**,
|
|
220
|
+
> 差的只是 tar/gzip 框架元数据 —— 与 v0.17 / v0.18 同一现象。)由 **npm 可信发布(Trusted Publisher / OIDC)**
|
|
221
|
+
> 经 GitHub Actions 发出(带 provenance,`predicateType` = `https://slsa.dev/provenance/v1`),不设 `NODE_AUTH_TOKEN`。
|
|
222
|
+
> GitHub Release 正文直接切自本节(184 行 / 16 858 字节),没有另写一份。
|
|
223
|
+
> ⚠️ **这一行是发布之后补的,所以它不在已发布的 tarball 里** —— 包内那份 CHANGELOG 读到上一段为止
|
|
224
|
+
> (节首刻意写成发布前后都成立的说法,所以包内那份不自相矛盾)。逐条核对见 `03_发布/发布清单-v0.19.0.md` §四。
|
|
225
|
+
|
|
190
226
|
## [0.18.0] - 2026-10-06
|
|
191
227
|
|
|
192
228
|
> ✅ **2026-10-06 已发布**:`v0.18.0` = 轻量 tag = npm `gitHead` = `170ee8f` · npm `latest = 0.18.0`
|
package/README.en.md
CHANGED
|
@@ -1,9 +1,41 @@
|
|
|
1
1
|
# Knit
|
|
2
2
|
|
|
3
|
-
>
|
|
4
|
-
> Knit puts them next to the conversation — whatever you're talking about, the relevant doc is on top.
|
|
3
|
+
> **Task-aware workspace context retrieval and lifecycle tracking for AI coding agents.**
|
|
5
4
|
>
|
|
6
|
-
>
|
|
5
|
+
> **面向 AI Coding Agent 的任务感知工作区上下文检索与生命周期追踪。**
|
|
6
|
+
|
|
7
|
+
Knit is the layer between **the task you are on** and **your whole workspace**: it finds the most
|
|
8
|
+
relevant documents, source files and media, organises them into **Primary / Supporting / Related**
|
|
9
|
+
context (the Context Pack) for both the panel and the agent, and keeps tracking **whether they were
|
|
10
|
+
read, and whether they changed after being read**.
|
|
11
|
+
|
|
12
|
+
**Find → Organise → Track**, all of it plain string work on your own machine — no model calls, no
|
|
13
|
+
network, no latency, nothing leaves the machine.
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
Current task
|
|
17
|
+
│
|
|
18
|
+
Workspace retrieval
|
|
19
|
+
┌───────────────┼───────────────┐
|
|
20
|
+
▼ ▼ ▼
|
|
21
|
+
Primary Supporting Related
|
|
22
|
+
└───────────────┼───────────────┘
|
|
23
|
+
▼
|
|
24
|
+
Context Pack ──► the `knit_docs` tool (for the agent)
|
|
25
|
+
▼
|
|
26
|
+
Agent reads
|
|
27
|
+
▼
|
|
28
|
+
Read Evidence · Context Epoch
|
|
29
|
+
▼
|
|
30
|
+
Workspace changes
|
|
31
|
+
▼
|
|
32
|
+
Re-read · Lifecycle
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
> **It is not a smarter recent-files list, and it is not a code browser.**
|
|
36
|
+
> A recent-files list records what you happened to open and what is newest; Knit answers
|
|
37
|
+
> **which things in this project are worth looking at first for the task at hand — and what
|
|
38
|
+
> happened to them after they were read.**
|
|
7
39
|
|
|
8
40
|

|
|
9
41
|
|
|
@@ -37,104 +69,128 @@ dsh plugin --profile web add dsh-knit
|
|
|
37
69
|
|
|
38
70
|
---
|
|
39
71
|
|
|
40
|
-
##
|
|
72
|
+
## Why it exists
|
|
41
73
|
|
|
42
|
-
|
|
74
|
+
> An agent produces 20 documents a day, and you cannot find the one from a minute ago.
|
|
43
75
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
76
|
+
That is the problem it started from: **output got faster than anyone can browse directories.**
|
|
77
|
+
DSH's built-in "recent files" only records what you opened; once a turn ends, the earlier ones sink
|
|
78
|
+
out of sight.
|
|
47
79
|
|
|
48
|
-
|
|
80
|
+
Knit asks a different question: **not "what is newest", but "what is relevant to what I am doing".**
|
|
81
|
+
It scans the **whole workspace** (not just what this turn produced) and ranks by what you are
|
|
82
|
+
talking about — restart DSH, open a new session, come back the next day, and it is still there.
|
|
49
83
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
84
|
+
Then the problem grew one step further: when you actually change a feature, the first thing worth
|
|
85
|
+
reading is usually not a document but **a few lines of source**. That is what v0.19 added. And after
|
|
86
|
+
that, "ranked first" stopped being enough — **of the things it ranked, did the agent actually read
|
|
87
|
+
them? Did they change afterwards?** v0.15–v0.18 filled in that layer.
|
|
88
|
+
|
|
89
|
+
Three words: **Find** (scan the workspace, rank by the current task) → **Organise** (three tiers,
|
|
90
|
+
each with its reason) → **Track** (read or not, changed or not).
|
|
56
91
|
|
|
57
92
|
---
|
|
58
93
|
|
|
59
|
-
##
|
|
94
|
+
## It is not a recent-files list, and not a code browser
|
|
60
95
|
|
|
61
|
-
|
|
96
|
+
Both comparisons catch one **surface** of Knit and miss the question it answers.
|
|
62
97
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
98
|
+
| | Recent-files list | Code browser | **Knit** |
|
|
99
|
+
|---|---|---|---|
|
|
100
|
+
| Scope | What you happened to open | A directory tree | **The whole workspace**: documents / code / images / video |
|
|
101
|
+
| Order | Modified time | You scroll it yourself | **Relevance to the current task** (BM25 + IDF, computed locally) |
|
|
102
|
+
| Output | One flat list | The one file you opened | **Primary / Supporting / Related**, each saying why it is there |
|
|
103
|
+
| For whom | You | You | You **and** the agent — the same Context Pack, through `knit_docs` |
|
|
104
|
+
| Afterwards | Nothing | Nothing | **Was it read? Did it change after being read?** (Read Evidence + lifecycle) |
|
|
66
105
|
|
|
67
|
-
|
|
106
|
+
The three differences that matter:
|
|
68
107
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
(「图片」, 「排序」) out of the query entirely
|
|
76
|
-
- stop-word filtering plus greedy de-overlap (picking「相关性排序」drops「相关性」and「排序」)
|
|
108
|
+
1. **Scope**: a recent-files list only records the files you **opened**; Knit scans **the whole project
|
|
109
|
+
folder** — restart DSH, open a new session, come back days later, and it is still there.
|
|
110
|
+
2. **Order**: it sorts by time; Knit sorts by **what you are talking about** — discuss architecture and
|
|
111
|
+
the architecture docs rise; discuss a loader bug and `plugin-loader.ts` rises.
|
|
112
|
+
3. **It does not stop at finding**: after finding comes **organising** (three tiers, each with a
|
|
113
|
+
verifiable reason) and **tracking** (which were really read, and whether they changed).
|
|
77
114
|
|
|
78
|
-
**
|
|
115
|
+
**No model calls, no network**: all plain string work, no latency, no cost, nothing leaves the machine.
|
|
79
116
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
117
|
+
---
|
|
118
|
+
|
|
119
|
+
## Install
|
|
120
|
+
|
|
121
|
+
```sh
|
|
122
|
+
dsh plugin --profile web add dsh-knit
|
|
86
123
|
```
|
|
87
124
|
|
|
88
|
-
**
|
|
125
|
+
Then **restart DSH** and hard-refresh the browser (`Cmd + Shift + R`).
|
|
89
126
|
|
|
90
|
-
|
|
91
|
-
rare one — so the frequent term discriminates nothing and dilutes the rare ones
|
|
92
|
-
- with no length normalisation, **a long document wins by piling up hits**
|
|
93
|
-
- capping hits at 6 was a hand-drawn knee; `k1` / `b` exist precisely for this
|
|
127
|
+
**How to open it:**
|
|
94
128
|
|
|
95
|
-
|
|
129
|
+
- The **Knit icon button in the session header** (right next to the sidebar toggle) — one click
|
|
130
|
+
- Or the right sidebar's tab bar「+」→「Knit recent docs」
|
|
96
131
|
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
| old (weighted hits) | 76.2% | 0.830 |
|
|
100
|
-
| **BM25** | **95.2%** | **0.976** |
|
|
132
|
+
**Optional**: if `dsh-better-sidebar` is installed, the panel also registers
|
|
133
|
+
as one of its tabs. Each host is an independent optional dependency; missing one doesn't affect the other.
|
|
101
134
|
|
|
102
|
-
|
|
103
|
-
engine frozen in `test/eval/legacy.mjs` — so "the new engine must be clearly better" is
|
|
104
|
-
verified automatically rather than asserted against a hard-coded number.
|
|
135
|
+
**Upgrading**: same command as installing, and the same restart + hard-refresh afterwards.
|
|
105
136
|
|
|
106
|
-
|
|
107
|
-
the corpus is built with a real trap — 12 short, focused topic documents, plus a pile of long
|
|
108
|
-
distractors that mention every topic five times without explaining any of them (which is what a
|
|
109
|
-
real project's CHANGELOG looks like). Half the topic documents have descriptive filenames, half
|
|
110
|
-
are opaque.
|
|
137
|
+
---
|
|
111
138
|
|
|
112
|
-
|
|
113
|
-
|---|---|---|---|
|
|
114
|
-
| **Knit (BM25)** | **100%** | **100%** | **1.000 (flat)** |
|
|
115
|
-
| `grep -c` keyword counting | 17% | **0%** | 0.313 → **0.089** |
|
|
116
|
-
| Filenames only | 100% | **0%** | 0.602 |
|
|
139
|
+
## Features
|
|
117
140
|
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
141
|
+
| | |
|
|
142
|
+
|---|---|
|
|
143
|
+
| **Code Context** (v0.19): source files join the **same** retrieval pipeline as documents — classify, BM25, Context Pack, lifecycle. A dedicated classification layer decides what a file *is* and what it may do, so extension knowledge lives in exactly one place | ✅ |
|
|
144
|
+
| **Sorted by relevance to the current conversation** (BM25 + IDF, fully local, no model) | ✅ |
|
|
145
|
+
| **The `knit_docs` tool for the agent**: the model can look up this project's most relevant documents itself | ✅ |
|
|
146
|
+
| **Document lifecycle** (v0.17): each recommended document is shown as `Unread / Read / Updated after read / Re-read after update`, alongside the most recent read, how many reads fell outside the pack (expandable to which ones), and the latest context change | ✅ |
|
|
147
|
+
| One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
|
|
148
|
+
| Scans **documents and code** in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist` / `build` / `out` / `coverage`) | ✅ |
|
|
149
|
+
| Each row shows H1 title (or filename) + relative time + first-paragraph summary | ✅ |
|
|
150
|
+
| The document list is **always one column** (v0.14 — the multi-column layout was deleted outright, not switched off); the **number sits in its own column on the far left** and is **vertically centred with the title line**, everything else stacks to its right starting with **one line: Primary dot + title + relative time** (the time is pushed to the right edge), then the summary. **The path is no longer shown in the list** — it duplicates the clickable **path** in the preview header, which is the one that stays | ✅ |
|
|
151
|
+
| Click to preview inline, click again to collapse | ✅ |
|
|
152
|
+
| Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
|
|
153
|
+
| One-click switch between **Docs / Code / Media / All** (v0.19 adds Code; remembered, defaults to Docs); the selected tab is an **underline tab**, deliberately different from the list row's grey fill | ✅ |
|
|
154
|
+
| Images & video: square thumbnail grid — cells have a **fixed 104px baseline independent of the item count**, columns come from CSS `repeat(auto-fill, minmax(104px, 1fr))`, and **as many rows as there are items are laid out** (no max height, the grid never scrolls itself — scrolling belongs to the list); videos auto-grab the first frame with a play glyph and duration badge (no deps, no transcoding) | ✅ |
|
|
155
|
+
| **"Web preview" for `.html`** (v0.19): the preview header hands the file to DSH's own document-preview tab (`openResource`) instead of showing source; the inline preview still shows source, so the two do not duplicate. Knit itself sends no request | ✅ |
|
|
156
|
+
| Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
|
|
157
|
+
| The **All** view splits into **three stacked sections**: docs (max 4, with "View all →" when truncated), **code** (max 4), then images & video (**never truncated**, count only) | ✅ |
|
|
158
|
+
| Preview pane is height-draggable (20%–80%, remembered), fullscreen-able, `Esc` to exit | ✅ |
|
|
159
|
+
| **"Open locally"** opens the document in your default app; the **path in the preview header is clickable** and now opens the system file manager with the file **selected** (`action:'reveal'`), and its tooltip carries the full relative path | ✅ |
|
|
160
|
+
| Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
|
|
161
|
+
| Filter box over title / summary / path | ✅ |
|
|
162
|
+
| **Click the workspace path** to open the project folder in your file manager | ✅ |
|
|
163
|
+
| **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; the popover is just header + list — no extra divider or hint line) | ✅ |
|
|
164
|
+
| Keyboard: `↑` `↓` move-and-preview, `Enter` toggle, `Esc` collapse (`←` `→` span rows in the **media grid only** — the document list is always one column, so they have no spatial meaning there) | ✅ |
|
|
165
|
+
| Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
|
|
166
|
+
| Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
|
|
167
|
+
| Zero model calls, zero network egress | ✅ |
|
|
168
|
+
| **A `knit_docs` tool for the agent** — read-only, so the model can find this project's relevant docs itself | ✅ |
|
|
121
169
|
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
include fragments that straddle two words (「项目文档」 yields `项目文` / `目文档`), and showing
|
|
125
|
-
those renders as gibberish — merging their spans and slicing the original text recovers `项目文档`.
|
|
126
|
-
The label is **your own wording**, so its casing is preserved (type `BM25`, see `BM25`).
|
|
170
|
+
> Relevance is deliberately **not visualised** (no percentages, no bars) — the ranking itself is
|
|
171
|
+
> the answer; position is relevance.
|
|
127
172
|
|
|
128
|
-
|
|
173
|
+
### The other two views
|
|
129
174
|
|
|
130
|
-
|
|
175
|
+

|
|
131
176
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
177
|
+
*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; this
|
|
179
|
+
particular workspace happens to hold several screenshots, one demo GIF and one single-colour SVG icon
|
|
180
|
+
(the solid black square is that icon, not a failed load). Videos get their first frame as a poster with
|
|
181
|
+
a play glyph and a duration badge — this workspace simply has no video, so none shows here.*
|
|
182
|
+
|
|
183
|
+

|
|
184
|
+
|
|
185
|
+
*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 / 19" and "4 / 17"), and the media grid comes last.*
|
|
187
|
+
|
|
188
|
+
⚠️ All three sections share the **same 40-item window** the host returns — a category that ranks past
|
|
189
|
+
40th by relevance drops out of the All view entirely. This screenshot uses the **Newest** sort: in this
|
|
190
|
+
workspace, under the default Relevance sort, media rank outside that window every time (at `limit=40`
|
|
191
|
+
those 40 rows are 34 documents + 6 code files). The **Media** and **Code** tabs are unaffected — they
|
|
192
|
+
request their own kind. A known defect, with reproduction and the fix recorded in
|
|
193
|
+
[`docs/README.md`](docs/README.md).*
|
|
138
194
|
|
|
139
195
|
---
|
|
140
196
|
|
|
@@ -219,6 +275,41 @@ There is **no** "the AI thinks this matters" and **no** percentages, stars or co
|
|
|
219
275
|
|
|
220
276
|
---
|
|
221
277
|
|
|
278
|
+
## Code as context (v0.19)
|
|
279
|
+
|
|
280
|
+
Until v0.18 Knit understood Markdown, images and video. v0.19's product concept becomes
|
|
281
|
+
**documents / code / media** — not "a few more extensions", but letting Knit put the source files an
|
|
282
|
+
AI-coding task actually needs into the same Context Pack, on the same main line:
|
|
283
|
+
|
|
284
|
+
```text
|
|
285
|
+
Current task -> Workspace Retrieval -> Document + Code Candidates
|
|
286
|
+
-> Primary / Supporting / Related -> Context Pack -> Agent Read
|
|
287
|
+
-> Read Evidence -> File Changed -> Lifecycle -> Context Epoch / Delta -> Usage Lens
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
- **One classification layer, not scattered `if (ext === '.js')`** — `src/host/classification.js`
|
|
291
|
+
turns a filename into `{ kind, language, previewable, searchable, contextual, generated,
|
|
292
|
+
sourceMap }`. The scanner, retrieval, preview and UI all just read that verdict.
|
|
293
|
+
- **Supported in v0.19**: `.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm .css .scss .yaml .yml
|
|
294
|
+
.sh .bash .zsh`. **Not yet**: `.go .rs .java .kt .c .cpp .h .hpp .cs .php .rb .swift .sql`.
|
|
295
|
+
- **Code gets its own field weights** — filename x4, path x2, body (first 8 KB) x1, instead of the
|
|
296
|
+
document weights (title x4 / summary x2 / body x1). A filename like `context-manager.ts` carries
|
|
297
|
+
the task signal.
|
|
298
|
+
- **Generated files are not context**: `.map`, `*.min.js`, `*.min.css`, `*.bundle.js`,
|
|
299
|
+
`*.generated.js`, `*.gen.js`, `*.lock` classify as `generated` — previewable, but never in
|
|
300
|
+
retrieval, the Context Pack or the Usage Lens. When `app.js` and `app.js.map` both exist, the
|
|
301
|
+
`app.js` preview offers one low-key **"Source map"** entry; the `.map` never shows up as a row.
|
|
302
|
+
**Context eligibility is not file-system visibility** — the built-in file tree still opens them.
|
|
303
|
+
- **Bounded and capped**: at most `MAX_CODE = 300` code candidates and a head-limited body read, so
|
|
304
|
+
a large repo cannot flood the Markdown corpus. Corpus pressure is the thing to watch in this
|
|
305
|
+
version, not recall.
|
|
306
|
+
- **The type tabs become four**: `Docs / Code / Media / All`. The Code tab is **still driven by the
|
|
307
|
+
current task** — it is not a file tree of the project.
|
|
308
|
+
- **No second engine**: no second retrieval path, no second lifecycle, no second store, no new
|
|
309
|
+
dependencies, no AST, no LSP, no embedding, no model call, no network, no IDE.
|
|
310
|
+
|
|
311
|
+
---
|
|
312
|
+
|
|
222
313
|
## Also for the agent: the `knit_docs` tool
|
|
223
314
|
|
|
224
315
|
The same ranking that you see in the panel is also exposed to the model.
|
|
@@ -256,103 +347,6 @@ Three details:
|
|
|
256
347
|
|
|
257
348
|
---
|
|
258
349
|
|
|
259
|
-
## Install
|
|
260
|
-
|
|
261
|
-
```sh
|
|
262
|
-
dsh plugin --profile web add dsh-knit
|
|
263
|
-
```
|
|
264
|
-
|
|
265
|
-
Then **restart DSH** and hard-refresh the browser (`Cmd + Shift + R`).
|
|
266
|
-
|
|
267
|
-
**How to open it:**
|
|
268
|
-
|
|
269
|
-
- The **Knit icon button in the session header** (right next to the sidebar toggle) — one click
|
|
270
|
-
- Or the right sidebar's tab bar「+」→「Knit recent docs」
|
|
271
|
-
|
|
272
|
-
**Optional**: if `dsh-better-sidebar` is installed, the panel also registers
|
|
273
|
-
as one of its tabs. Each host is an independent optional dependency; missing one doesn't affect the other.
|
|
274
|
-
|
|
275
|
-
**Upgrading**: same command as installing, and the same restart + hard-refresh afterwards.
|
|
276
|
-
|
|
277
|
-
---
|
|
278
|
-
|
|
279
|
-
## Feedback
|
|
280
|
-
|
|
281
|
-
**Right now this project is not about adding features — it's about finding out whether
|
|
282
|
-
"rank project docs by the current conversation" is something anyone actually uses.**
|
|
283
|
-
So the most valuable thing you can send is not "could you add X" but **how you work around
|
|
284
|
-
this today** — including "I installed it and never opened it", which is more useful than a
|
|
285
|
-
feature request.
|
|
286
|
-
|
|
287
|
-
- 💬 [Tell us when you actually open it](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) — two fields, thirty seconds
|
|
288
|
-
- 🐞 [Won't install / panel won't open / ranking looks wrong](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
|
|
289
|
-
- 📖 Check [known limitations](#known-limitations) first — short conversations degrade to time order and Chinese uses n-gram approximation; those are deliberate trade-offs, not bugs
|
|
290
|
-
|
|
291
|
-
> A single issue is treated as a real signal. So far this plugin has **no trace of a single
|
|
292
|
-
> real user** — the npm download count is automated version enumeration, not people
|
|
293
|
-
> (only 14% of it is `latest`, and a human install only ever pulls `latest`). One human reply
|
|
294
|
-
> changes what gets built next.
|
|
295
|
-
|
|
296
|
-
---
|
|
297
|
-
|
|
298
|
-
## Features
|
|
299
|
-
|
|
300
|
-
| | |
|
|
301
|
-
|---|---|
|
|
302
|
-
| **Code Context** (v0.19): source files join the **same** retrieval pipeline as documents — classify, BM25, Context Pack, lifecycle. A dedicated classification layer decides what a file *is* and what it may do, so extension knowledge lives in exactly one place | ✅ |
|
|
303
|
-
| **Sorted by relevance to the current conversation** (BM25 + IDF, fully local, no model) | ✅ |
|
|
304
|
-
| **The `knit_docs` tool for the agent**: the model can look up this project's most relevant documents itself | ✅ |
|
|
305
|
-
| **Document lifecycle** (v0.17): each recommended document is shown as `Unread / Read / Updated after read / Re-read after update`, alongside the most recent read, how many reads fell outside the pack (expandable to which ones), and the latest context change | ✅ |
|
|
306
|
-
| One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
|
|
307
|
-
| Scans **documents and code** in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist` / `build` / `out` / `coverage`) | ✅ |
|
|
308
|
-
| Each row shows H1 title (or filename) + relative time + first-paragraph summary | ✅ |
|
|
309
|
-
| The document list is **always one column** (v0.14 — the multi-column layout was deleted outright, not switched off); the **number sits in its own column on the far left** and is **vertically centred with the title line**, everything else stacks to its right starting with **one line: Primary dot + title + relative time** (the time is pushed to the right edge), then the summary. **The path is no longer shown in the list** — it duplicates the clickable **path** in the preview header, which is the one that stays | ✅ |
|
|
310
|
-
| Click to preview inline, click again to collapse | ✅ |
|
|
311
|
-
| Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
|
|
312
|
-
| One-click switch between **Docs / Code / Media / All** (v0.19 adds Code; remembered, defaults to Docs); the selected tab is an **underline tab**, deliberately different from the list row's grey fill | ✅ |
|
|
313
|
-
| Images & video: square thumbnail grid — cells have a **fixed 104px baseline independent of the item count**, columns come from CSS `repeat(auto-fill, minmax(104px, 1fr))`, and **as many rows as there are items are laid out** (no max height, the grid never scrolls itself — scrolling belongs to the list); videos auto-grab the first frame with a play glyph and duration badge (no deps, no transcoding) | ✅ |
|
|
314
|
-
| **"Web preview" for `.html`** (v0.19): the preview header hands the file to DSH's own document-preview tab (`openResource`) instead of showing source; the inline preview still shows source, so the two do not duplicate. Knit itself sends no request | ✅ |
|
|
315
|
-
| Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
|
|
316
|
-
| The **All** view splits into **three stacked sections**: docs (max 4, with "View all →" when truncated), **code** (max 4), then images & video (**never truncated**, count only) | ✅ |
|
|
317
|
-
| Preview pane is height-draggable (20%–80%, remembered), fullscreen-able, `Esc` to exit | ✅ |
|
|
318
|
-
| **"Open locally"** opens the document in your default app; the **path in the preview header is clickable** and now opens the system file manager with the file **selected** (`action:'reveal'`), and its tooltip carries the full relative path | ✅ |
|
|
319
|
-
| Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
|
|
320
|
-
| Filter box over title / summary / path | ✅ |
|
|
321
|
-
| **Click the workspace path** to open the project folder in your file manager | ✅ |
|
|
322
|
-
| **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; the popover is just header + list — no extra divider or hint line) | ✅ |
|
|
323
|
-
| Keyboard: `↑` `↓` move-and-preview, `Enter` toggle, `Esc` collapse (`←` `→` span rows in the **media grid only** — the document list is always one column, so they have no spatial meaning there) | ✅ |
|
|
324
|
-
| Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
|
|
325
|
-
| Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
|
|
326
|
-
| Zero model calls, zero network egress | ✅ |
|
|
327
|
-
| **A `knit_docs` tool for the agent** — read-only, so the model can find this project's relevant docs itself | ✅ |
|
|
328
|
-
|
|
329
|
-
> Relevance is deliberately **not visualised** (no percentages, no bars) — the ranking itself is
|
|
330
|
-
> the answer; position is relevance.
|
|
331
|
-
|
|
332
|
-
### The other two views
|
|
333
|
-
|
|
334
|
-

|
|
335
|
-
|
|
336
|
-
*Media: square thumbnails, with the **column count following the panel width continuously** —
|
|
337
|
-
six columns at this width, cells about 110px. These are the workspace's real image and SVG files; this
|
|
338
|
-
particular workspace happens to hold several screenshots, one demo GIF and one single-colour SVG icon
|
|
339
|
-
(the solid black square is that icon, not a failed load). Videos get their first frame as a poster with
|
|
340
|
-
a play glyph and a duration badge — this workspace simply has no video, so none shows here.*
|
|
341
|
-
|
|
342
|
-

|
|
343
|
-
|
|
344
|
-
*All: the documents section shows at most 4, the **code section** shows at most 4 (each gets its own
|
|
345
|
-
"View all →" when truncated — here "4 / 19" and "4 / 17"), and the media grid comes last.*
|
|
346
|
-
|
|
347
|
-
⚠️ All three sections share the **same 40-item window** the host returns — a category that ranks past
|
|
348
|
-
40th by relevance drops out of the All view entirely. This screenshot uses the **Newest** sort: in this
|
|
349
|
-
workspace, under the default Relevance sort, media rank outside that window every time (at `limit=40`
|
|
350
|
-
those 40 rows are 34 documents + 6 code files). The **Media** and **Code** tabs are unaffected — they
|
|
351
|
-
request their own kind. A known defect, with reproduction and the fix recorded in
|
|
352
|
-
[`docs/README.md`](docs/README.md).*
|
|
353
|
-
|
|
354
|
-
---
|
|
355
|
-
|
|
356
350
|
## Did it actually get used? (v0.16 → v0.17)
|
|
357
351
|
|
|
358
352
|
Knit orders "what to read first right now" — but **whether that order was right could only be felt,
|
|
@@ -515,38 +509,89 @@ The `knit_docs` tool output **did not grow**: it still only finds context.
|
|
|
515
509
|
|
|
516
510
|
---
|
|
517
511
|
|
|
518
|
-
|
|
512
|
+
## How retrieval works (implementation, not the pitch)
|
|
519
513
|
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
514
|
+
> This section is **evidence**, not the sales pitch: it is what backs the claim "ranked by the
|
|
515
|
+
> current task". The product question is answered on the first screen; this answers "why is it
|
|
516
|
+
> any good at ranking".
|
|
517
|
+
|
|
518
|
+
No magic, just string operations. Three steps:
|
|
519
|
+
|
|
520
|
+
**1. Read the conversation.** The host takes the last 6 user/assistant messages, and only
|
|
521
|
+
counts real user messages (`agent.inject()` synthetic context would drag the topic off course).
|
|
522
|
+
Newer messages weigh more: 3 / 2 / 1 / 1 …
|
|
523
|
+
|
|
524
|
+
**2. Extract keywords.**
|
|
525
|
+
|
|
526
|
+
- **ASCII words** — high value, one occurrence is enough (`chokidar`, `mtime`)
|
|
527
|
+
- **Chinese 2/3-grams** — either occurring twice, or appearing in the newest message
|
|
528
|
+
- **Drop fragments that straddle a word boundary.** Chinese has no word boundaries, so
|
|
529
|
+
n-grams glue the last character of one word to the first of the next (「图片和」, 「个插」,
|
|
530
|
+
「的排」). They share one trait — **the first or last character is a pure function word** —
|
|
531
|
+
and are dropped. Leave them in and they fill every candidate slot, pushing the real words
|
|
532
|
+
(「图片」, 「排序」) out of the query entirely
|
|
533
|
+
- stop-word filtering plus greedy de-overlap (picking「相关性排序」drops「相关性」and「排序」)
|
|
534
|
+
|
|
535
|
+
**3. Score the documents — BM25.**
|
|
523
536
|
|
|
524
|
-
```
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
537
|
+
```
|
|
538
|
+
IDF per term first: rarer in the corpus means more valuable
|
|
539
|
+
ln(1 + (N - df + 0.5) / (df + 0.5))
|
|
540
|
+
then a weighted sum over fields: title ×4 + summary ×2 + first 2500 chars of body ×1
|
|
541
|
+
each field saturated and length-normalised (k1 = 1.2, b = 0.3 / 0.5 / 0.75)
|
|
542
|
+
plus a 10% recency nudge (relevance still dominates)
|
|
528
543
|
```
|
|
529
544
|
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
545
|
+
**Why BM25 and not "hits × weight"** (the original approach, since replaced):
|
|
546
|
+
|
|
547
|
+
- with no IDF, a term that appears **everywhere** (the project name) is worth as much as a
|
|
548
|
+
rare one — so the frequent term discriminates nothing and dilutes the rare ones
|
|
549
|
+
- with no length normalisation, **a long document wins by piling up hits**
|
|
550
|
+
- capping hits at 6 was a hand-drawn knee; `k1` / `b` exist precisely for this
|
|
551
|
+
|
|
552
|
+
Measured on `test/eval/fixture.mjs` (21 cases, both engines on the same corpus):
|
|
553
|
+
|
|
554
|
+
| | top-1 | MRR |
|
|
555
|
+
|---|---|---|
|
|
556
|
+
| old (weighted hits) | 76.2% | 0.830 |
|
|
557
|
+
| **BM25** | **95.2%** | **0.976** |
|
|
558
|
+
|
|
559
|
+
That eval runs inside `npm test`, and the baseline is **recomputed each run** from the old
|
|
560
|
+
engine frozen in `test/eval/legacy.mjs` — so "the new engine must be clearly better" is
|
|
561
|
+
verified automatically rather than asserted against a hard-coded number.
|
|
562
|
+
|
|
563
|
+
**Against counting keywords yourself** (`knit/tools/scale-benchmark.mjs`, N = 20/60/180/540):
|
|
564
|
+
the corpus is built with a real trap — 12 short, focused topic documents, plus a pile of long
|
|
565
|
+
distractors that mention every topic five times without explaining any of them (which is what a
|
|
566
|
+
real project's CHANGELOG looks like). Half the topic documents have descriptive filenames, half
|
|
567
|
+
are opaque.
|
|
568
|
+
|
|
569
|
+
| Approach | Descriptive filenames | Opaque filenames | MRR vs. scale |
|
|
570
|
+
|---|---|---|---|
|
|
571
|
+
| **Knit (BM25)** | **100%** | **100%** | **1.000 (flat)** |
|
|
572
|
+
| `grep -c` keyword counting | 17% | **0%** | 0.313 → **0.089** |
|
|
573
|
+
| Filenames only | 100% | **0%** | 0.602 |
|
|
574
|
+
|
|
575
|
+
Three things: **the ranking beats counting keywords yourself** (so having the agent recompute it
|
|
576
|
+
is irrational); **filename matching only works when names describe content**, and Knit is the
|
|
577
|
+
only approach that scores 100% either way; and **self-counting degrades as the corpus grows**.
|
|
578
|
+
|
|
579
|
+
**About the "sorted by「xxx」" line**: it shows the **span of your own text** that the matched
|
|
580
|
+
terms cover, not the raw candidate tokens. Chinese has no word boundaries, so candidates always
|
|
581
|
+
include fragments that straddle two words (「项目文档」 yields `项目文` / `目文档`), and showing
|
|
582
|
+
those renders as gibberish — merging their spans and slicing the original text recovers `项目文档`.
|
|
583
|
+
The label is **your own wording**, so its casing is preserved (type `BM25`, see `BM25`).
|
|
584
|
+
|
|
585
|
+
All of it is string arithmetic — **no embeddings, no model calls**.
|
|
586
|
+
|
|
587
|
+
**And the honest boundaries**:
|
|
588
|
+
|
|
589
|
+
- **With only one or two messages** there are too few keywords, so it falls back to sorting by
|
|
590
|
+
modification time and says so in the panel — it does not pretend to rank
|
|
591
|
+
- **With only three to five documents IDF barely does anything**: `df` only takes a few values,
|
|
592
|
+
so its dynamic range collapses. The more documents, the better this ranking gets
|
|
593
|
+
- **It can only rank documents that share vocabulary with the conversation**: if no term matches,
|
|
594
|
+
every document scores the same and the order degrades to time
|
|
550
595
|
|
|
551
596
|
---
|
|
552
597
|
|
|
@@ -604,6 +649,25 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
604
649
|
|
|
605
650
|
---
|
|
606
651
|
|
|
652
|
+
## Feedback
|
|
653
|
+
|
|
654
|
+
**Right now this project is not about adding features — it's about finding out whether
|
|
655
|
+
"rank project docs by the current conversation" is something anyone actually uses.**
|
|
656
|
+
So the most valuable thing you can send is not "could you add X" but **how you work around
|
|
657
|
+
this today** — including "I installed it and never opened it", which is more useful than a
|
|
658
|
+
feature request.
|
|
659
|
+
|
|
660
|
+
- 💬 [Tell us when you actually open it](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) — two fields, thirty seconds
|
|
661
|
+
- 🐞 [Won't install / panel won't open / ranking looks wrong](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
|
|
662
|
+
- 📖 Check [known limitations](#known-limitations) first — short conversations degrade to time order and Chinese uses n-gram approximation; those are deliberate trade-offs, not bugs
|
|
663
|
+
|
|
664
|
+
> A single issue is treated as a real signal. So far this plugin has **no trace of a single
|
|
665
|
+
> real user** — the npm download count is automated version enumeration, not people
|
|
666
|
+
> (only 14% of it is `latest`, and a human install only ever pulls `latest`). One human reply
|
|
667
|
+
> changes what gets built next.
|
|
668
|
+
|
|
669
|
+
---
|
|
670
|
+
|
|
607
671
|
## Development
|
|
608
672
|
|
|
609
673
|
```sh
|
package/README.md
CHANGED
|
@@ -1,9 +1,38 @@
|
|
|
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
|
+
```
|
|
32
|
+
|
|
33
|
+
> **它不是「更聪明的最近文件列表」,也不是「代码浏览器」。**
|
|
34
|
+
> 最近文件记的是「你点开过什么、哪个更新」;Knit 回答的是
|
|
35
|
+
> **当前这个任务,项目里哪些东西最值得先看 —— 以及看过之后,事情变成了什么样。**
|
|
7
36
|
|
|
8
37
|

|
|
9
38
|
|
|
@@ -32,93 +61,47 @@ dsh plugin --profile web add dsh-knit
|
|
|
32
61
|
|
|
33
62
|
---
|
|
34
63
|
|
|
35
|
-
##
|
|
36
|
-
|
|
37
|
-
**是的,但有两个关键区别:**
|
|
38
|
-
|
|
39
|
-
1. **范围**:最近打开列表只记你**点开过**的文件;Knit 扫**整个项目文件夹**。
|
|
40
|
-
重启 DSH、新开会话、跨天回来,它都还在。
|
|
41
|
-
2. **排序**:它按时间排;Knit 按**你正在聊什么**排。
|
|
42
|
-
|
|
43
|
-
三句话说完它是什么:
|
|
44
|
-
|
|
45
|
-
1. 扫**整个项目文件夹**的文档与代码,不只是这一轮生成的那几篇 —— 重启、换会话、跨天都还在
|
|
46
|
-
2. 排序**跟着你正在聊什么走**:聊架构,架构文档浮上来;聊 loader 的 bug,`plugin-loader.ts` 浮上来
|
|
47
|
-
3. **不调模型、不联网**:全是本地字符串运算,零延迟、零成本、文档不出本机
|
|
48
|
-
|
|
49
|
-
---
|
|
50
|
-
|
|
51
|
-
## 「相关」是怎么算出来的
|
|
64
|
+
## 为什么需要它
|
|
52
65
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
**1. 读当前会话。** 取最近 6 条用户 / 助手消息,只认真人输入的用户消息
|
|
56
|
-
(`agent.inject()` 塞进来的合成上下文不算,那会把话题带偏)。越新的消息权重越高:3 / 2 / 1 / 1 …
|
|
57
|
-
|
|
58
|
-
**2. 抽关键词。**
|
|
59
|
-
|
|
60
|
-
- **英文词**:取值很高,出现 1 次就要(`chokidar`、`mtime` 这种精确词)
|
|
61
|
-
- **中文 2/3-gram**:出现 2 次,或出现在最新那条消息里
|
|
62
|
-
- **丢掉跨词边界的碎片**:中文没有词边界,n-gram 会把相邻两个词的字粘起来
|
|
63
|
-
(「图片和」「个插」「的排」)。这类碎片有个共同特征 —— **首字或尾字是纯虚词**,
|
|
64
|
-
一律丢掉。不丢的话它们会占满候选位,把「图片」「排序」这些真词全挤出去
|
|
65
|
-
- 虚词表过滤 + 贪心去重叠(选了「相关性排序」就不再算「相关性」和「排序」)
|
|
66
|
+
> Agent 一天产出 20 篇文档,你找不到刚才那篇。
|
|
66
67
|
|
|
67
|
-
|
|
68
|
+
这是它最开始要解决的问题:**产出速度超过了人翻目录的速度**。
|
|
69
|
+
DSH 自带的「最近文件」只记你点开过什么;一轮对话结束,前面那几篇就沉下去了。
|
|
68
70
|
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
每个字段都按 BM25 饱和 + 长度归一化(k1 = 1.2,b = 0.3 / 0.5 / 0.75)
|
|
73
|
-
再叠 10% 的时间新鲜度微调(主排序仍是相关性)
|
|
74
|
-
```
|
|
71
|
+
Knit 换了个问法:**不看「谁新」,看「和现在这件事有多相关」**。
|
|
72
|
+
它扫的是**整个工作区**(不是这一轮生成的那几篇),按你正在聊的内容排序 ——
|
|
73
|
+
重启 DSH、换会话、跨天回来,它都还在。
|
|
75
74
|
|
|
76
|
-
|
|
75
|
+
后来问题往前长了一步:真要动一个功能时,最该先看的往往不是文档,而是**那几行源码**。
|
|
76
|
+
v0.19 起代码进了同一条链路。再往后,「排在前面」也不够用了 ——
|
|
77
|
+
**排出来的那些,agent 到底读了没有?读完改过没有?** v0.15–v0.18 补的就是这一层。
|
|
77
78
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
- 没有长度归一化时,**长文档靠堆词就能赢**
|
|
81
|
-
- 命中次数封顶 6 次是个手写硬拐点;`k1` / `b` 才是为这件事设计的
|
|
79
|
+
三句话:**找到**(扫全工作区、按当前任务排序)→ **组织**(主要 / 辅助 / 相关三层 + 每条的理由)
|
|
80
|
+
→ **追踪**(读了没有、读完变了没有)。
|
|
82
81
|
|
|
83
|
-
|
|
82
|
+
---
|
|
84
83
|
|
|
85
|
-
|
|
86
|
-
|---|---|---|
|
|
87
|
-
| 旧做法(加权命中) | 76.2% | 0.830 |
|
|
88
|
-
| **BM25** | **95.2%** | **0.976** |
|
|
84
|
+
## 「最近文件列表」和「代码浏览器」都不是它
|
|
89
85
|
|
|
90
|
-
|
|
91
|
-
所以「新引擎必须显著更好」是自动验证的,而不是引用一个写死的数字。
|
|
86
|
+
这两个类比各自只说中 Knit 的一个**表层形态**,说不到它回答的问题。
|
|
92
87
|
|
|
93
|
-
|
|
94
|
-
语料刻意做成有真实陷阱的 —— 12 篇短而聚焦的主题文档,加上一堆「每条主题各提 5 次、
|
|
95
|
-
但哪一件都没讲」的长干扰文档(真实项目里的 CHANGELOG 就长这样)。
|
|
96
|
-
主题文档一半用描述性文件名,一半看不出内容。
|
|
97
|
-
|
|
98
|
-
| 路线 | 文件名说得清 | 文件名看不出 | MRR 随规模 |
|
|
88
|
+
| | 最近文件列表 | 代码浏览器 | **Knit** |
|
|
99
89
|
|---|---|---|---|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
**文件名匹配只在名字描述内容时好使**,Knit 是唯一两种都 100% 的;
|
|
106
|
-
**自己数的可靠性随规模单调下降**。
|
|
90
|
+
| 范围 | 你点开过的 | 一棵目录树 | **整个工作区**:文档 / 代码 / 图片 / 视频 |
|
|
91
|
+
| 排序 | 修改时间 | 你自己翻 | **当前任务的相关性**(BM25 + IDF,本地算) |
|
|
92
|
+
| 输出 | 一条平铺列表 | 你打开的那一个文件 | **主要 / 辅助 / 相关** 三层,每条都写明为什么在这里 |
|
|
93
|
+
| 给谁 | 你 | 你 | 你**和** agent —— 同一份 Context Pack,走 `knit_docs` |
|
|
94
|
+
| 之后 | 不管 | 不管 | **读了没有 / 读完变了没有**(读取证据 + 生命周期) |
|
|
107
95
|
|
|
108
|
-
|
|
109
|
-
中文没有词边界,候选里必然有跨词的碎片(「项目文档」会切出 `项目文` / `目文档`),
|
|
110
|
-
直接显示就成了乱码 —— 把它们的**区间合并**再切原文,正好还原出 `项目文档`。
|
|
111
|
-
标签是你**自己打的字**,所以大小写原样保留(打 `BM25` 就显示 `BM25`)。
|
|
96
|
+
三条最要紧的区别:
|
|
112
97
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
98
|
+
1. **范围**:最近打开列表只记你**点开过**的文件;Knit 扫**整个项目文件夹** ——
|
|
99
|
+
重启 DSH、新开会话、跨天回来,它都还在。
|
|
100
|
+
2. **排序**:它按时间排;Knit 按**你正在聊什么**排 ——
|
|
101
|
+
聊架构,架构文档浮上来;聊 loader 的 bug,`plugin-loader.ts` 浮上来。
|
|
102
|
+
3. **它不止于「找」**:找完还要**组织**(三层 + 可核验的理由)和**追踪**(哪些真被读了、读完有没有变)。
|
|
116
103
|
|
|
117
|
-
|
|
118
|
-
- **语料只有三五篇时 IDF 几乎不起作用**:`df` 的取值范围太窄,动态范围被压扁。
|
|
119
|
-
文档越多这个排序越准 —— 这正是它该有的样子
|
|
120
|
-
- **它只能排「和对话有共同词汇」的文档**:如果一个词都没命中,所有文档同分,
|
|
121
|
-
名次就退化成按时间排
|
|
104
|
+
**不调模型、不联网**:全是本地字符串运算,零延迟、零成本、内容不出本机。
|
|
122
105
|
|
|
123
106
|
---
|
|
124
107
|
|
|
@@ -142,22 +125,6 @@ dsh plugin --profile web add dsh-knit
|
|
|
142
125
|
|
|
143
126
|
---
|
|
144
127
|
|
|
145
|
-
## 反馈
|
|
146
|
-
|
|
147
|
-
**这个项目当前的重心不是加功能,是搞清楚「按对话给文档排序」这件事到底有没有人在用。**
|
|
148
|
-
所以最有价值的一句话不是「能不能加个 XX」,而是**你现在是怎么绕过它的** ——
|
|
149
|
-
哪怕结论是「装了,但一周没打开过」,也请直说,那比一个功能建议有用得多。
|
|
150
|
-
|
|
151
|
-
- 💬 [说说你在什么场景下会打开它](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) —— 两步、三十秒,不必客气
|
|
152
|
-
- 🐞 [装不上 / 面板打不开 / 排得不对](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
|
|
153
|
-
- 📖 提之前先看一眼[已知限制](#已知限制) —— 短对话退化、中文用 n-gram 近似,这几条是已知的取舍,不是 bug
|
|
154
|
-
|
|
155
|
-
> 一条 issue 会被当成真实信号处理。这个插件到现在**一个真实用户的痕迹都没有**
|
|
156
|
-
> (npm 那个下载量是自动化版本枚举、不是人 —— `latest` 占比只有 14%,而真人只会装 `latest`)
|
|
157
|
-
> —— 一条有人味儿的反馈能直接改变接下来做什么。
|
|
158
|
-
|
|
159
|
-
---
|
|
160
|
-
|
|
161
128
|
## 功能
|
|
162
129
|
|
|
163
130
|
| 能力 | |
|
|
@@ -526,6 +493,83 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
526
493
|
|
|
527
494
|
---
|
|
528
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
|
+
|
|
529
573
|
## 它读什么,不读什么
|
|
530
574
|
|
|
531
575
|
- 扫描**当前会话工作区内**的 `.md`、第一批代码后缀(见上文「代码上下文」)、图片与视频
|
|
@@ -577,6 +621,22 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
577
621
|
|
|
578
622
|
---
|
|
579
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
|
+
|
|
580
640
|
## 开发
|
|
581
641
|
|
|
582
642
|
```sh
|
package/SECURITY.md
CHANGED
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.19.
|
|
3
|
+
"version": "0.19.1",
|
|
4
4
|
"type": "module",
|
|
5
|
-
"description": "Task-aware workspace context retrieval for DeepSeek Harness.
|
|
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",
|
|
@@ -53,6 +53,9 @@
|
|
|
53
53
|
"recent-files",
|
|
54
54
|
"relevance",
|
|
55
55
|
"context-pack",
|
|
56
|
+
"workspace-context",
|
|
57
|
+
"context-retrieval",
|
|
58
|
+
"context-lifecycle",
|
|
56
59
|
"task-context",
|
|
57
60
|
"images",
|
|
58
61
|
"video",
|