dsh-knit 0.18.0 → 0.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +193 -7
- package/README.en.md +73 -26
- package/README.md +97 -21
- package/SECURITY.md +4 -3
- package/package.json +6 -4
- package/src/client/client.js +451 -47
- package/src/host/classification.js +250 -0
- package/src/host/context.js +31 -9
- package/src/host/index.js +336 -77
- package/src/host/tool.js +29 -13
- package/test/classification.test.mjs +237 -0
- package/test/client.test.mjs +431 -3
- package/test/code-context.test.mjs +567 -0
- package/test/eval/fixture.mjs +309 -6
- package/test/eval.test.mjs +117 -1
- package/test/host.test.mjs +63 -3
- package/test/path.test.mjs +97 -5
- package/test/tool.test.mjs +23 -15
package/CHANGELOG.md
CHANGED
|
@@ -3,15 +3,201 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.19.0] - 2026-10-07
|
|
7
|
+
|
|
8
|
+
> **Code Context**。产品概念从「Markdown / 图片 / 视频」变成「**文档 / 代码 / 媒体**」——
|
|
9
|
+
> 这不是给后缀表加几行,而是让 Knit 把 AI Coding 任务**当前真正需要的那几个源码文件**
|
|
10
|
+
> 纳入同一条 Context Retrieval 链路。
|
|
11
|
+
> 关键约束:**没有第二条检索链路、没有第二套生命周期、没有第二个 Context Store、
|
|
12
|
+
> 没有 AST / LSP / embedding / 模型调用 / 网络请求、没有把 Knit 变成代码浏览器或 IDE。**
|
|
13
|
+
> 主线数据流一个字没改:当前任务 → Workspace Retrieval → Document + Code Candidates →
|
|
14
|
+
> Primary / Supporting / Related → Context Pack → Agent Read → Read Evidence →
|
|
15
|
+
> File Changed → Lifecycle → Context Epoch / Delta → Usage Lens。
|
|
16
|
+
|
|
17
|
+
### 变化
|
|
18
|
+
|
|
19
|
+
- **新增独立的文件分类层 `src/host/classification.js`**。在这之前,扩展名判定是
|
|
20
|
+
`src/host/index.js` 里一个返回 `''|'md'|'image'|'video'` 的 `kindOfName()`,散在扫描、
|
|
21
|
+
预览、UI 各处。现在只有一个入口:`classifyFile(name)` →
|
|
22
|
+
`{kind, language, previewable, searchable, contextual, generated, sourceMap}`,
|
|
23
|
+
扫描 / 检索 / 预览 / UI **全部消费它的产物**,没有一处再自己看扩展名
|
|
24
|
+
(有一条架构守卫:`src/host/index.js` 与 `src/client/client.js` 里不许出现
|
|
25
|
+
`'.ts'` `'.py'` `'.map'` `'.min.js'` 这类后缀字面量)。
|
|
26
|
+
- **第一批支持 17 个代码后缀**:`.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm
|
|
27
|
+
.css .scss .yaml .yml .sh .bash .zsh`。内部统一 `{kind:'code', language:'…'}`。
|
|
28
|
+
**刻意不支持** `.go .rs .java .kt .c .cpp .h .hpp .cs .php .rb .swift .sql` ——
|
|
29
|
+
范围越小,「代码上下文到底有没有用」这个结论越可信。
|
|
30
|
+
- **代码复用 Markdown 的 BM25,只换字段口径**。代码没有 Markdown 的 title/summary/body,
|
|
31
|
+
所以宿主按 `filename`(**带扩展名**,`plugin-loader.js` 与 `plugin.json` 的差别就在这儿)
|
|
32
|
+
→ `title` 字段、`目录`(保留结尾斜杠)→ `summary` 字段、`正文前 8 KB` → `body` 字段填充,
|
|
33
|
+
于是 `relevance.js` 里既有的 `FIELD_WEIGHTS = {title:4, summary:2, body:1}`
|
|
34
|
+
**一行未改**就是需求要的 filename×4 / path×2 / content×1。排序器、语料过滤、
|
|
35
|
+
门槛规则全是同一个。
|
|
36
|
+
- **`.map` / generated / noise 一律不进上下文**:`*.map`、`*.min.js`、`*.min.css`、
|
|
37
|
+
`*.bundle.js`、`*.generated.js`、`*.gen.js`、`*.lock`(含 `package-lock.json`)→
|
|
38
|
+
`{kind:'generated', searchable:false, contextual:false}`。它们不参与检索、不进 Context Pack、
|
|
39
|
+
不进 Usage Lens、不进代码列表、不进 BM25 语料 —— 但**仍然可以预览**(用户主动从
|
|
40
|
+
DSH 原生文件树点开时不拦):**Context eligibility ≠ File system visibility**。
|
|
41
|
+
- **有边界的扫描**:新增 `MAX_CODE = 300`(Markdown 仍是 400)、代码正文只读前 8 KB
|
|
42
|
+
(`CODE_HEAD_BYTES = 8*1024`,没有无界读取)。目录元信息 → 扩展名分类 → 候选准入 →
|
|
43
|
+
有界内容读取,顺序不变。数字是**量出来的**:真实项目根(`08_Knit`)59 文档 + 54 代码,
|
|
44
|
+
上限根本碰不到;而一个 1300+ 目录的大树正好在这里截住(400 文档 + 300 代码 + 400 媒体)。
|
|
45
|
+
- **代码预览就地展开,不新增交互**:复用面板下方那块现有预览区。行号 gutter + 等宽正文、
|
|
46
|
+
横向滚动只在正文列(纵向滚动仍归 `.knit-preview-body`,**没有第二个纵向滚动容器**)、
|
|
47
|
+
复制、`打开文件`、同一个 `Source map` 轻量入口(只在同名 `.map` 存在时出现)。
|
|
48
|
+
超过 4000 行只渲染前 4000 行并明说被截断。**没有**语法高亮 / 折叠 / 多标签 / mini-map /
|
|
49
|
+
git diff / symbol outline —— 也没有引入 Monaco 或 CodeMirror。
|
|
50
|
+
- **UI 类型档从三档变四档**:`文档 / 代码 / 媒体 / 全部`。代码档**仍然受当前任务检索支配**,
|
|
51
|
+
不是「项目代码文件树」:任务说「改 Skill loader 支持新 frontmatter」,这一档就该是
|
|
52
|
+
`skill-loader.ts` 在前,而不是 `src/` 下全部代码。没有第二层语言分类 UI;
|
|
53
|
+
代码行只多一个很弱的语言徽章(`TS` / `PY` …),文档行不挂(整列都是 MD,是纯噪声)。
|
|
54
|
+
「全部」档变成三区:文档区(≤4)→ 代码区(≤4)→ 媒体网格。
|
|
55
|
+
- **代码的理由码**:`filenameMatch`(文件名命中,与 Markdown 的 `titleMatch` 同级)与
|
|
56
|
+
`pathMatch`(目录命中,与 `summaryMatch` 同级)。`why.filenameMatch` / `why.pathMatch`
|
|
57
|
+
中英各一条;**没有**新增第 8 个条目字段 —— `{rel,title,summary,mtimeMs,kind,source,reason}`
|
|
58
|
+
与 v0.18 逐字相同,代码只是让 `kind` 多了一个取值。
|
|
59
|
+
- **生命周期 / Read Evidence / Epoch / Delta / Usage Lens 一行未改**。代码被读之后走的是
|
|
60
|
+
完全同一套归因:读的时候在哪一层就冻结在哪一层,历史证据不许因后来的 BM25 变化而重算;
|
|
61
|
+
四态(未读 / 已读 / 读后已更新 / 修改后已重新读取)也是同一套;Epoch 是同一份;
|
|
62
|
+
UI 上多出来的叫法一个都没有(仍然只叫「上下文变化」)。
|
|
63
|
+
- **预览头那条路径改成「在文件管理器里定位到这个文件」**。原文案是「用系统默认应用打开这篇文档」,
|
|
64
|
+
与页脚那个「本地打开」按钮**做的是同一件事** —— 一个东西两个入口,还偏要悬停才知道。
|
|
65
|
+
现在两者分工清楚:**路径点开它所在的文件夹、并且已经选中这个文件**
|
|
66
|
+
(`openWorkspacePath({ path, action: 'reveal' })`,macOS 走 `open -R`、Windows 走
|
|
67
|
+
`explorer /select,`,正是 Chrome「在文件夹中显示」那个手感 —— 不用在文件夹里自己再找一遍),
|
|
68
|
+
**「本地打开」点开文件本身**(不带 `action`,走默认应用)。文案随之换成
|
|
69
|
+
`preview.reveal`(中「在文件管理器中显示并选中这个文件」/ 英 `Show this file in your file manager (and select it)`)。
|
|
70
|
+
⚠️ 送过去的是**文件本身的绝对路径**而不是所在目录 —— reveal 一个目录会变成
|
|
71
|
+
「在上级目录里选中这个文件夹」,不是用户要的。Linux 的 `xdg-open` 没有「选中」这个概念,
|
|
72
|
+
那边只有打开目录(平台差异,不是少做一步)。
|
|
73
|
+
- **修:开着「使用情况」点全屏,预览没铺满**。全屏的隐藏名单写于 v0.12,当时面板里只有
|
|
74
|
+
「头部 / 排序条 / 类型档 / 列表 / 预览」这几块,所以只藏了前四块;v0.18 在列表**上方**
|
|
75
|
+
加了 Context Usage Lens(`.knit-usage`),谁也没回头去补那份名单 —— 于是开着「使用情况」
|
|
76
|
+
再点全屏,Lens 仍以 `flex:none` 的自然高度占掉面板上方约三分之一,预览被挤在下面,
|
|
77
|
+
看起来就像「全屏没生效」。补 `.knit-root.fullscreen .knit-usage{display:none}` 一块即可,
|
|
78
|
+
预览那条 `flex:1 1 auto` 本来就在等它让位。
|
|
79
|
+
守卫放在 `test/client.test.mjs`:全屏隐藏名单必须覆盖 `.knit-head` / `.knit-bar` /
|
|
80
|
+
`.knit-types` / `.knit-usage` / `.knit-list`,并跟真的渲染出来的全屏树对一次账 ——
|
|
81
|
+
以后谁再往列表上方加块,这条会响。
|
|
82
|
+
- **HTML 多了「网页预览」**。加了代码支持之后,`.html` 点开看到的是**源码**;
|
|
83
|
+
可 HTML 想看的恰恰是它渲染出来的样子。DSH 其实**自带**这个渲染器
|
|
84
|
+
(`dsh-client-ui-sidebar-documentpreview` 注册了 `["html","htm"]`,默认静态档:
|
|
85
|
+
DOMPurify 清洗过的文档塞进一个**不给任何 sandbox 权限**的 iframe,CSP 摆在最前挡脚本 /
|
|
86
|
+
外部资源 / 连接 / 表单 / 嵌套框架,内联 `<style>` 与 `data:` 图片保留),而 Knit 双击一行
|
|
87
|
+
本来就走 `actions.openResource` → 官方文档预览 —— 通路早就在,缺的只是一个入口。
|
|
88
|
+
所以预览头给 `.html` / `.htm` 加一个「网页预览」按钮,走的就是双击那条**同一个**
|
|
89
|
+
`openResource` 通道:**没有新开第二条打开路径、没有 iframe、没有把 DSH 的渲染器搬进面板**,
|
|
90
|
+
Knit 的零网络出口承诺一个字不用改。
|
|
91
|
+
这不算「把删掉的功能加回来」:v0.10 撤掉「新标签页」按钮的理由是「就地预览已经能看到内容,
|
|
92
|
+
重复度高」—— 那条前提对 HTML 不成立(就地给源码、官方给页面),是纠正而不是回退;
|
|
93
|
+
其余代码类型一个都不给这个按钮。
|
|
94
|
+
- **修掉「工作区是符号链接时,点路径一律报 `Path has no verified Host path`」**(发布前发现的真实 bug):
|
|
95
|
+
在 `DSH_Skill_Trace`(→ `10_DSH_Skill_Trace` 的符号链接)这类工作区里,点预览头路径 /
|
|
96
|
+
「本地打开」/ 点顶部工作区路径**全部失败**,而在真实目录(`08_Knit`)里没事。
|
|
97
|
+
根因不在 Knit,在 DSH 的校验方式:`dsh-api-session-controller` 的 `verifyDesktopPath()`
|
|
98
|
+
把路径送进 `ctx.fs`,要求
|
|
99
|
+
`processPath(await resolve(processPathFromHostPath(p))) === p`,而 `dsh-fs-local` 的
|
|
100
|
+
targetKey 落的是 **`realpath()`** —— 也就是说**含未展开符号链接的路径一定过不了**。
|
|
101
|
+
⇒ Knit 这一侧自己先展开:宿主新增 `hostPathOf()`,下发的 `hostRoot`(工作区根)与
|
|
102
|
+
每条记录的 `path`(文件本身)都已是 canonical 形态;客户端**打开 / 定位一律用它们**,
|
|
103
|
+
`root` 只留给界面显示(用户看到的是自己选的那条路径)。
|
|
104
|
+
`scan()` 内部也改成从 canonical 根走一遍,所以 `rel` 一字不变 ——
|
|
105
|
+
检索 / Context Pack / 生命周期 / Usage Lens 的输入完全没动。
|
|
106
|
+
- **文档同步**:`knit/README.md` 补上代码档与「网页预览」两处说明、测试数刷成 588;
|
|
107
|
+
**`knit/README.en.md` 这次也补了一节 v0.19**(它同样进 npm 包 —— 英文 README 停在 v0.18,
|
|
108
|
+
包内文档就自相矛盾了);`knit/SECURITY.md` 属性表加一行「`/knit/api/doc` 只放行文本类产物」;
|
|
109
|
+
`package.json` 的 keywords 去掉了重复的 `code-context`。
|
|
110
|
+
|
|
111
|
+
### 一处刻意的收窄(引用图)
|
|
112
|
+
|
|
113
|
+
引用图(`md` 文件之间互相指路的那些边)的**源永远是 Markdown**:代码文件不再进图的
|
|
114
|
+
`list`。理由是不能给代码开一条靠「注释里恰好写了一句 `docs/X.md`」就进 Supporting 的
|
|
115
|
+
后门 —— 那条路不打分。反过来,**文档点名一个代码文件**(设计文档里写了 `src/x.js`)仍然
|
|
116
|
+
和文档指文档一样会被尊重:那不是特例,是同一条规则。
|
|
117
|
+
(代码作为「被指向的一方」能进 Supporting,正是需求 §18 要的混合竞争。)
|
|
118
|
+
|
|
119
|
+
### 为什么不需要改 DSH 核心 / 新增 model tool / 新增 Store
|
|
120
|
+
|
|
121
|
+
- **不改 DSH**:DSH 的文件访问走宿主已有的 `ctx.fs` 缝;预览走面板里已有的那块预览区。
|
|
122
|
+
代码与文档走的是同一个资源身份、同一个读取接口 —— 没有自造 OS 路径、没有
|
|
123
|
+
`window.open(local file)`、没有 fork DSH 的 preview 实现(代码预览一共就 4 条 CSS 规则)。
|
|
124
|
+
- **不新增 model tool**:`knit_docs` 工具本身没变,只是它现在能把代码算进同一个 Context Pack。
|
|
125
|
+
工具描述从「Markdown 文档」改成「文档与代码文件」,理由很直接:语料里已经有 `.ts` 了,
|
|
126
|
+
再说「Markdown documents」就是对模型说假话。
|
|
127
|
+
- **不新增 Store**:没有 `codeStore` / `codeContextStore` / `codeRetrievalStore` /
|
|
128
|
+
`workspaceArtifactStore`。代码只是一个多出来的 `artifact.kind`,通过既有状态投影出 UI。
|
|
129
|
+
- **不新建 benchmark framework**:V0.19 的前后对比直接扩在 `test/eval/fixture.mjs` 里 ——
|
|
130
|
+
同一个 `runEval`,同一个 `rankByRelevance`,只把语料换成「Markdown only」与
|
|
131
|
+
「Markdown + Code」两臂。
|
|
132
|
+
|
|
133
|
+
### 测试
|
|
134
|
+
- `npm test`:**588 / 588 通过**(v0.18 是 532)。v0.18 的 532 条**一条没删、一条没放宽**;
|
|
135
|
+
中间有 12 条 v0.18 断言因为契约变化而**同步**(不是降级):
|
|
136
|
+
`readDocument` 的「拒绝非 Markdown」拆成「拒绝不可预览的类型」+「v0.19 起代码可读并带分类结论」;
|
|
137
|
+
类型档从 3 个按钮改成 4 个;`knit_docs` 的文案与两处总数(样本工作区里的 `package.json`
|
|
138
|
+
现在是一个合法代码候选 —— 那个 `3 → 4` 本身就是「代码真的进了同一个检索池」的证据)。
|
|
139
|
+
- 新增 **`test/classification.test.mjs`(12 条)**:17 个支持后缀的 language 映射、
|
|
140
|
+
13 个不支持后缀、`.map`/min/generated/lock、锁文件与生成产物的**反例**
|
|
141
|
+
(`minify.js` / `bundle.js` / `tsconfig.json` 仍是代码)、判定顺序是契约、
|
|
142
|
+
以及「后缀知识只许活在分类层」的架构守卫。
|
|
143
|
+
- 新增 **`test/code-context.test.mjs`(25 条)**:代码穿过整条链路之后还对不对 ——
|
|
144
|
+
字段权重的三档可观测、代码进 Primary 的理由码是 `filenameMatch`、
|
|
145
|
+
只命中目录走 `pathMatch`、混合包里文档与代码公平竞争、条目投影与 v0.18 逐字相同、
|
|
146
|
+
引用图代码只能当靶不能当源、代码 read evidence 与包外读取、历史归因冻结、
|
|
147
|
+
代码四态生命周期、Epoch 的进入 / 离开 / 换层 / delta、七条噪声路径一条不进候选。
|
|
148
|
+
- `test/eval.test.mjs` 新增 **6 条 v0.19 基准守卫**(见下)。
|
|
149
|
+
- **发布前补的 3 条符号链接守卫**(`585 → 588`):`test/host.test.mjs` 造一条指向样本工作区的
|
|
150
|
+
符号链接当 `root`,断言「下发的 `hostRoot` / 每条 `path` 都满足 `realpath(p) === p`」
|
|
151
|
+
(这**就是** DSH 的判据)+「换成符号链接后 `rel` 集合一字不差」;
|
|
152
|
+
`test/path.test.mjs` 两条客户端守卫,分别覆盖「宿主给了 canonical `path`」与
|
|
153
|
+
「老宿主只有 `hostRoot`」时,reveal / 本地打开 / 打开工作区目录**都用 canonical 路径**,
|
|
154
|
+
而界面显示的仍是会话原本那条。写完全部做过**证伪**(把修复回滚,3 条如实变红)。
|
|
155
|
+
- `test/client.test.mjs` 新增 **9 条 v0.19 UI 守卫**:代码档请求 `kind=code` 且代码行带语言徽章、
|
|
156
|
+
文档行一个徽章都不加(整列都是 MD,挂 MD 是纯噪声)、点代码行就地出行号 + 正文且**不落到
|
|
157
|
+
Markdown 渲染**(夹具正文故意以 `#` 开头 —— 走错分支它就会变成标题)、同名 `.map` 才给
|
|
158
|
+
「Source map」入口且列表里始终没有 `.map` 那一行、「全部」档三区(文档 / 代码 / 媒体)
|
|
159
|
+
各自限流、Usage Lens 里的代码路径照常显示(仍是只有事实、没有分数)、
|
|
160
|
+
全屏隐藏名单必须覆盖列表上方每一块(含 `.knit-usage`)、**「网页预览」只有 HTML 出场
|
|
161
|
+
且走的是双击那条 `openResource` 通道(正文读到之前按钮就已在场 —— 否则头会长高一下)**,
|
|
162
|
+
以及一条样式守卫(横向滚动只归正文列,语言徽章无底色无边框无圆角,DSH 令牌必须带回落值)。
|
|
163
|
+
|
|
164
|
+
### 基准(V0.19 前后对比)
|
|
165
|
+
|
|
166
|
+
同一个排序器、同一批用例,**唯一变量是语料里有没有代码**:
|
|
167
|
+
|
|
168
|
+
| 指标 | Markdown only | Markdown + Code |
|
|
169
|
+
| --- | --- | --- |
|
|
170
|
+
| Document Recall (top-1) | 100% | **100%** |
|
|
171
|
+
| Document MRR | 1.000 | **1.000** |
|
|
172
|
+
| Code Recall (top-1) | 0% | **100%** |
|
|
173
|
+
| Code MRR | 0.000 | **1.000** |
|
|
174
|
+
|
|
175
|
+
- **Overall MRR(文档 + 代码一起量:21 条文档用例 + 3 条代码用例)= 1.000**,top-1 100%。
|
|
176
|
+
语料规模:Markdown only 16 条 → Markdown + Code 24 条(**只多 8 条代码**)。
|
|
177
|
+
- **Noise Rate = 0%** —— 7 条生成 / 噪声路径(`node_modules/foo.js`、`dist/app.js`、
|
|
178
|
+
`coverage/report.js`、`app.min.js`、`bundle.generated.js`、`app.js.map`、`package-lock.json`)
|
|
179
|
+
在真实扫描与评测语料里都是 0 条进入。
|
|
180
|
+
- 对照臂:同样三条代码用例放在**只有文档**的语料里 top-1 是 0% —— 所以「加了代码之后答对了」
|
|
181
|
+
不是碰巧。混合场景(Case C)里那篇讲分层的设计文档仍排在第 3 名,**没有被代码挤没**。
|
|
182
|
+
- ⚠️ 说清楚这份基准**不是难度竞赛**:三条代码用例的检索意图都很清晰,两臂都接近满分。
|
|
183
|
+
它的作用是**回归钉** —— 谁把代码候选、噪声过滤、字段权重或 corpus cap 改坏了,这里会红。
|
|
184
|
+
`node knit/tools/scale-benchmark.mjs` 会把这张表连同原有 20/60/180/540 规模基准一起打印。
|
|
185
|
+
- 真机工作区量到的数(`08_Knit`,扫描 4 ms):59 文档 + **54 代码** + 6 媒体,
|
|
186
|
+
0 generated / 10 ignored,语料 59 → 113。一个 1300+ 目录的大树(55 ms):
|
|
187
|
+
400 文档截断 + 300 代码(243 条被 cap 挡下)+ 400 媒体,语料 400 → 700 ——
|
|
188
|
+
`MAX_CODE = 300` 在这里正好起到「别让代码把原有 Markdown 上下文挤出去」的作用。
|
|
189
|
+
|
|
6
190
|
## [0.18.0] - 2026-10-06
|
|
7
191
|
|
|
8
|
-
>
|
|
9
|
-
>
|
|
10
|
-
>
|
|
11
|
-
>
|
|
12
|
-
>
|
|
13
|
-
>
|
|
14
|
-
>
|
|
192
|
+
> ✅ **2026-10-06 已发布**:`v0.18.0` = 轻量 tag = npm `gitHead` = `170ee8f` · npm `latest = 0.18.0`
|
|
193
|
+
> · **43 文件 / 428.7 kB 打包 / 1.3 MB 解包** / shasum `457e7842dda936fcadf671d3d490b7ea28de5629`。
|
|
194
|
+
> (本地 `npm pack --dry-run` 报的是 422.4 kB / `92a4ce9e…`;两个 tarball 的**文件清单与解包内容逐字一致**,
|
|
195
|
+
> 差的只是 tar/gzip 框架元数据 —— 与 v0.17 同一现象。)由 **npm 可信发布(Trusted Publisher / OIDC)**
|
|
196
|
+
> 经 GitHub Actions 发出(带 provenance),不设 `NODE_AUTH_TOKEN`。
|
|
197
|
+
> 纯客户端重构:宿主(`src/host/*`)**一行未改**,v0.17 的 517 条测试照旧通过。
|
|
198
|
+
> ℹ️ v0.16 / v0.17 的坑是「包内这份 CHANGELOG 的对应行还写着 🚧 尚未发布」;**本版节首写成发布前后都成立
|
|
199
|
+
> 的说法**,包内那份读起来不自相矛盾。改这一行的提交仍在 publish 之后,**同一版本号不能再发一次**。
|
|
200
|
+
> tag / `gitHead` / `dist-tags` / 解包自测的逐条结果见 `03_发布/发布清单-v0.18.0.md` §四。
|
|
15
201
|
|
|
16
202
|
**Context Usage Lens(依据 2026-10-05 用户给的 V0.18 规格)**:
|
|
17
203
|
v0.17 的「使用情况」是一行统计文字 + 三块折叠列表 —— 信息都在,但**读不出结构**:
|
package/README.en.md
CHANGED
|
@@ -5,13 +5,15 @@
|
|
|
5
5
|
>
|
|
6
6
|
> **Your agent has the same problem.** It gets the same ranking as a tool — the ranked documents plus the passage that matched in each.
|
|
7
7
|
|
|
8
|
-

|
|
9
|
+
|
|
10
|
+
*Screenshot from a real machine, not a mock-up: the same workspace, this one left on the **Code tab** —
|
|
11
|
+
since v0.19 source files are first-class citizens, just like Markdown.*
|
|
12
|
+
*The "why" line under each row says how it matched: a direct hit on the task text, a path hit, or a
|
|
13
|
+
workspace hit.*
|
|
14
|
+
*Click a row to expand the preview **in place**: here `knit/src/host/classification.js`, with line
|
|
15
|
+
numbers; the preview header holds only the path and four actions (copy / full screen / open locally / close).*
|
|
16
|
+
*The header holds only the path, one count and two toggles; whether the list runs by
|
|
15
17
|
relevance or by newest-first is decided by that pair of tabs on the left.*
|
|
16
18
|
*Since v0.14 the list is always one column: the rank number sits in its own column on the far left
|
|
17
19
|
(vertically centred on the title's first line), then Primary dot + title + relative time (time on the
|
|
@@ -297,21 +299,23 @@ feature request.
|
|
|
297
299
|
|
|
298
300
|
| | |
|
|
299
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 | ✅ |
|
|
300
303
|
| **Sorted by relevance to the current conversation** (BM25 + IDF, fully local, no model) | ✅ |
|
|
301
304
|
| **The `knit_docs` tool for the agent**: the model can look up this project's most relevant documents itself | ✅ |
|
|
302
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 | ✅ |
|
|
303
306
|
| One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
|
|
304
|
-
| Scans
|
|
307
|
+
| Scans **documents and code** in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist` / `build` / `out` / `coverage`) | ✅ |
|
|
305
308
|
| Each row shows H1 title (or filename) + relative time + first-paragraph summary | ✅ |
|
|
306
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 | ✅ |
|
|
307
310
|
| Click to preview inline, click again to collapse | ✅ |
|
|
308
311
|
| Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
|
|
309
|
-
| One-click switch between **Docs / Media / All** (
|
|
310
|
-
| Images & video: square thumbnail grid —
|
|
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 | ✅ |
|
|
311
315
|
| Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
|
|
312
|
-
| The **All** view splits into **
|
|
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) | ✅ |
|
|
313
317
|
| Preview pane is height-draggable (20%–80%, remembered), fullscreen-able, `Esc` to exit | ✅ |
|
|
314
|
-
| **"Open locally"
|
|
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 | ✅ |
|
|
315
319
|
| Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
|
|
316
320
|
| Filter box over title / summary / path | ✅ |
|
|
317
321
|
| **Click the workspace path** to open the project folder in your file manager | ✅ |
|
|
@@ -330,20 +334,22 @@ feature request.
|
|
|
330
334
|

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

|
|
339
343
|
|
|
340
|
-
*All: the documents section shows at most 4,
|
|
341
|
-
and the media grid
|
|
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.*
|
|
342
346
|
|
|
343
|
-
⚠️
|
|
344
|
-
|
|
345
|
-
|
|
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).*
|
|
347
353
|
|
|
348
354
|
---
|
|
349
355
|
|
|
@@ -509,10 +515,49 @@ The `knit_docs` tool output **did not grow**: it still only finds context.
|
|
|
509
515
|
|
|
510
516
|
---
|
|
511
517
|
|
|
518
|
+
### v0.19: code as context (Code Context)
|
|
519
|
+
|
|
520
|
+
Until v0.18 Knit understood Markdown, images and video. v0.19's product concept becomes
|
|
521
|
+
**documents / code / media** — not "a few more extensions", but letting Knit put the source files an
|
|
522
|
+
AI-coding task actually needs into the same Context Pack, on the same main line:
|
|
523
|
+
|
|
524
|
+
```text
|
|
525
|
+
Current task -> Workspace Retrieval -> Document + Code Candidates
|
|
526
|
+
-> Primary / Supporting / Related -> Context Pack -> Agent Read
|
|
527
|
+
-> Read Evidence -> File Changed -> Lifecycle -> Context Epoch / Delta -> Usage Lens
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
- **One classification layer, not scattered `if (ext === '.js')`** — `src/host/classification.js`
|
|
531
|
+
turns a filename into `{ kind, language, previewable, searchable, contextual, generated,
|
|
532
|
+
sourceMap }`. The scanner, retrieval, preview and UI all just read that verdict.
|
|
533
|
+
- **Supported in v0.19**: `.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm .css .scss .yaml .yml
|
|
534
|
+
.sh .bash .zsh`. **Not yet**: `.go .rs .java .kt .c .cpp .h .hpp .cs .php .rb .swift .sql`.
|
|
535
|
+
- **Code gets its own field weights** — filename x4, path x2, body (first 8 KB) x1, instead of the
|
|
536
|
+
document weights (title x4 / summary x2 / body x1). A filename like `context-manager.ts` carries
|
|
537
|
+
the task signal.
|
|
538
|
+
- **Generated files are not context**: `.map`, `*.min.js`, `*.min.css`, `*.bundle.js`,
|
|
539
|
+
`*.generated.js`, `*.gen.js`, `*.lock` classify as `generated` — previewable, but never in
|
|
540
|
+
retrieval, the Context Pack or the Usage Lens. When `app.js` and `app.js.map` both exist, the
|
|
541
|
+
`app.js` preview offers one low-key **"Source map"** entry; the `.map` never shows up as a row.
|
|
542
|
+
**Context eligibility is not file-system visibility** — the built-in file tree still opens them.
|
|
543
|
+
- **Bounded and capped**: at most `MAX_CODE = 300` code candidates and a head-limited body read, so
|
|
544
|
+
a large repo cannot flood the Markdown corpus. Corpus pressure is the thing to watch in this
|
|
545
|
+
version, not recall.
|
|
546
|
+
- **The type tabs become four**: `Docs / Code / Media / All`. The Code tab is **still driven by the
|
|
547
|
+
current task** — it is not a file tree of the project.
|
|
548
|
+
- **No second engine**: no second retrieval path, no second lifecycle, no second store, no new
|
|
549
|
+
dependencies, no AST, no LSP, no embedding, no model call, no network, no IDE.
|
|
550
|
+
|
|
551
|
+
---
|
|
552
|
+
|
|
512
553
|
## What it reads, and what it doesn't
|
|
513
554
|
|
|
514
|
-
- Scans
|
|
515
|
-
outside is rejected); for media it reads metadata only,
|
|
555
|
+
- Scans Markdown, **supported code files** (see the v0.19 list above) and media **inside the current
|
|
556
|
+
session workspace** (anything resolving outside is rejected); for media it reads metadata only,
|
|
557
|
+
never the pixels, and for code it reads a **bounded head** of the body, never the whole file
|
|
558
|
+
- **Generated / noisy files are excluded from context** (`.map`, `*.min.*`, `*.bundle.*`,
|
|
559
|
+
`*.generated.*`, `*.lock`): they classify as `generated`, so they never enter retrieval, the
|
|
560
|
+
Context Pack or the Usage Lens — but `/knit/api/doc` still serves them when you open one on purpose
|
|
516
561
|
- Reads only **the current session's** conversation events (used for ranking)
|
|
517
562
|
- The `knit_docs` tool is **read-only**: it writes no files and persists no index
|
|
518
563
|
- v0.15 usage accounting is **off by default**: when enabled it reads only the **current session's
|
|
@@ -521,9 +566,10 @@ The `knit_docs` tool output **did not grow**: it still only finds context.
|
|
|
521
566
|
the plugin's own same-origin routes
|
|
522
567
|
- **No install-time scripts** (no `install` / `postinstall`)
|
|
523
568
|
- **Zero dependencies** — nothing to build, no build-authorisation prompt
|
|
524
|
-
- The
|
|
569
|
+
- The media route only allows an **image/video-extension allowlist** (images ≤ 12MB,
|
|
525
570
|
video ≤ 256MB), serves video over HTTP Range, and responds with
|
|
526
|
-
`nosniff` plus `default-src 'none'; sandbox
|
|
571
|
+
`nosniff` plus `default-src 'none'; sandbox`; the **text route serves documents, code and
|
|
572
|
+
generated artifacts**, and refuses media and unknown extensions
|
|
527
573
|
|
|
528
574
|
The relevance figure only affects ordering — it is **never displayed and never sent anywhere**.
|
|
529
575
|
|
|
@@ -564,7 +610,7 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
564
610
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
565
611
|
cd dsh-knit
|
|
566
612
|
|
|
567
|
-
npm test #
|
|
613
|
+
npm test # 588 tests, zero dependencies, no npm install needed
|
|
568
614
|
```
|
|
569
615
|
|
|
570
616
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -584,11 +630,12 @@ knit/
|
|
|
584
630
|
│ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
|
|
585
631
|
│ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
|
|
586
632
|
│ ├── host/links.js # reference parsing (pure; never touches ranking)
|
|
633
|
+
│ ├── host/classification.js # v0.19 file classification: kind / language / searchable / contextual
|
|
587
634
|
│ ├── host/context.js # context assembly: the three-tier Context Pack (pure, zero I/O)
|
|
588
635
|
│ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
|
|
589
636
|
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
590
637
|
│ └── client/client.js # dual-host registration + panel UI
|
|
591
|
-
└── test/ #
|
|
638
|
+
└── test/ # 588 tests
|
|
592
639
|
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
593
640
|
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
594
641
|
```
|
package/README.md
CHANGED
|
@@ -5,11 +5,12 @@
|
|
|
5
5
|
>
|
|
6
6
|
> **你的 agent 也一样。** 同一份排序也给它当工具用 —— 它问「哪几篇相关」,拿回排名**加每篇里命中的那段原文**。
|
|
7
7
|
|
|
8
|
-

|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
10
|
+
*真机截图(不是原型):同一个工作区,这张停在 **「代码」档** —— v0.19 起,源码和 Markdown 一样是一等公民。*
|
|
11
|
+
*每行下面的「为什么」写着它是怎么被命中的(`直接命中:knit · readme` / `路径命中:knit · path` / `直接命中:knit · 工作区`)。*
|
|
12
|
+
*点一行**就地**展开预览:这里是 `knit/src/host/classification.js`,带行号;预览头里只有路径和四个动作(复制 / 全屏 / 本地打开 / 关闭)。*
|
|
13
|
+
*头部只放路径、一个计数与两个开关;列表按「相关」还是「最新」排,由左边那一对页签决定 —— 按「相关」时排的就是你正在聊什么。*
|
|
13
14
|
*v0.14 起文档列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
|
|
14
15
|
*Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
|
|
15
16
|
*序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
|
|
@@ -23,7 +24,7 @@
|
|
|
23
24
|
*这一屏里没有文档落进主要层,所以分组从「辅助上下文」开始。*
|
|
24
25
|
*⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
|
|
25
26
|
|
|
26
|
-
|
|
27
|
+
扫整个项目文件夹的文档 / 代码 / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
|
|
27
28
|
|
|
28
29
|
```sh
|
|
29
30
|
dsh plugin --profile web add dsh-knit
|
|
@@ -41,8 +42,8 @@ dsh plugin --profile web add dsh-knit
|
|
|
41
42
|
|
|
42
43
|
三句话说完它是什么:
|
|
43
44
|
|
|
44
|
-
1.
|
|
45
|
-
2.
|
|
45
|
+
1. 扫**整个项目文件夹**的文档与代码,不只是这一轮生成的那几篇 —— 重启、换会话、跨天都还在
|
|
46
|
+
2. 排序**跟着你正在聊什么走**:聊架构,架构文档浮上来;聊 loader 的 bug,`plugin-loader.ts` 浮上来
|
|
46
47
|
3. **不调模型、不联网**:全是本地字符串运算,零延迟、零成本、文档不出本机
|
|
47
48
|
|
|
48
49
|
---
|
|
@@ -166,18 +167,22 @@ dsh plugin --profile web add dsh-knit
|
|
|
166
167
|
| **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
|
|
167
168
|
| **文档生命周期**(v0.17):每篇推荐文档现在处于 `未读 / 已读 / 读后已更新 / 修改后已重新读取` 哪一档,另外给出最近读了哪篇、包外读了哪几篇、上下文最近一次怎么变 | ✅ |
|
|
168
169
|
| 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
|
|
169
|
-
| 扫描会话工作区里的 `.md
|
|
170
|
+
| 扫描会话工作区里的 `.md` 与上表那批代码后缀(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist` / `build` / `out` / `coverage` …) | ✅ |
|
|
171
|
+
| **生成 / 噪声产物不进检索**:`.map`、`*.min.js`、`*.min.css`、`*.bundle.js`、`*.generated.js`、`*.gen.js`、`*.lock`、`package-lock.json` —— 你能打开它们看,但它们**不会**成为主要 / 辅助 / 相关上下文 | ✅ |
|
|
172
|
+
| 代码预览:行号 + 等宽 + 横向滚动 + 复制 + 「本地打开」;同名 `app.js.map` 存在时预览页脚多一个低权重「Source map」入口(点开按纯文本看,`.map` 本身不进上下文) | ✅ |
|
|
170
173
|
| 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
|
|
171
174
|
| 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径**重复,只保留后者 | ✅ |
|
|
172
175
|
| 单击就地展开预览,再点收起 | ✅ |
|
|
173
176
|
| 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
|
|
174
|
-
|
|
|
177
|
+
| **代码上下文**(v0.19):`.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm .css .scss .yaml .yml .sh .bash .zsh` 与 Markdown **进同一个检索池**,共用同一份 BM25、同一个 Context Pack、同一套生命周期 —— 不是第二套「代码搜索」 | ✅ |
|
|
178
|
+
| **文档 / 代码 / 媒体 / 全部** 四类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边(页签「媒体」2026-10-06 由「图片与视频」改短,「代码」v0.19 加入) | ✅ |
|
|
175
179
|
| 图片与视频:方形缩略图网格,**格子基准固定 104px、列数由宽度连续数出来**(320px → 2 列 / 632px → 5 列 / 1200px → 10 列),格子大小基本不变;**纵向有多少行就铺多少行**,超出交给列表滚动;视频自动取首帧、叠播放三角与时长角标(零依赖、不转码) | ✅ |
|
|
176
180
|
| 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
|
|
177
181
|
| 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
|
|
178
|
-
| 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc`
|
|
179
|
-
|
|
|
182
|
+
| 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出;**全屏时头部 / 排序条 / 类型档 / 使用情况 / 列表全部让位**,预览铺满整个面板 | ✅ |
|
|
183
|
+
| **「本地打开」**:用系统默认应用打开当前预览的这篇文档;**预览头那条路径点开的是它「所在的文件夹」并顺带选中这个文件**(reveal,macOS 是 Finder 里 `open -R`;与顶部那行工作区路径同一套机制,差别只在「打开目录」vs「定位到文件」,完整相对路径在悬停提示里) | ✅ |
|
|
180
184
|
| 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
|
|
185
|
+
| **HTML 的「网页预览」**(v0.19 追加):预览头只对 `.html` / `.htm` 多一个按钮,点了在官方文档预览标签页里**按网页渲染** —— 那一侧是 DSH 自带的 HTML 渲染器(默认静态档:清洗过的文档 + 不给 sandbox 权限的 iframe + CSP 挡脚本 / 外部资源 / 表单 / 嵌套框架,内联 `<style>` 与 `data:` 图片保留)。就地预览给的是**源码**,两者不重复;其余代码类型不给这个按钮 | ✅ |
|
|
181
186
|
| 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
|
|
182
187
|
| **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
|
|
183
188
|
| **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局;浮层只有「头 + 列表」,没有多余的横线与提示语) | ✅ |
|
|
@@ -193,16 +198,17 @@ dsh plugin --profile web add dsh-knit
|
|
|
193
198
|
|
|
194
199
|

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

|
|
202
207
|
|
|
203
|
-
|
|
204
|
-
*⚠️
|
|
205
|
-
|
|
208
|
+
*全部:**文档区最多 4 条**、**代码区最多 4 条**(超出时各区右侧给「查看全部 →」,这一屏是「4 / 19」与「4 / 17」),最后是媒体网格。*
|
|
209
|
+
*⚠️ 三个区共用宿主返回的**同一个 40 条窗口**:某一类如果按相关性排到第 40 名之外,「全部」档就整个看不到它。*
|
|
210
|
+
*这张图用的是**「最新」排序** —— 在这个工作区里,默认的「相关」排序下媒体恒定掉在 40 条窗口之外*
|
|
211
|
+
*(`limit=40` 时那 40 条全是 34 篇文档 + 6 个代码文件)。**「媒体」/「代码」档不受影响**,它们各自单独取。*
|
|
206
212
|
*这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
|
|
207
213
|
|
|
208
214
|
---
|
|
@@ -283,6 +289,71 @@ Context Pack 是对这个问题的回答,但它是**数据层的结构**(主
|
|
|
283
289
|
|
|
284
290
|
---
|
|
285
291
|
|
|
292
|
+
## 代码上下文(v0.19)
|
|
293
|
+
|
|
294
|
+
上面这一整套(检索 → 三层 Context Pack → 读取证据 → 生命周期 → 上下文变化 → 使用情况)
|
|
295
|
+
v0.19 起**同样适用于代码**。没有第二条链路:代码文件走的是**同一个** BM25、**同一个** Context Pack、
|
|
296
|
+
**同一套** Read Evidence 与生命周期。
|
|
297
|
+
|
|
298
|
+
**为什么加了代码是有意义的。** 一个真实任务(「改 plugin loader,让它支持新的 plugin metadata」)
|
|
299
|
+
最该先看的往往不是某篇文档,而是 `plugin-loader.ts` 本身。v0.18 之前 Knit 扫不到它 ——
|
|
300
|
+
面板里只有 Markdown,agent 也只能靠 `glob` 猜路径。
|
|
301
|
+
|
|
302
|
+
### 第一批支持的后缀(严格限定)
|
|
303
|
+
|
|
304
|
+
```
|
|
305
|
+
.js .mjs .cjs .ts .tsx .jsx .py .json
|
|
306
|
+
.html .htm .css .scss .yaml .yml
|
|
307
|
+
.sh .bash .zsh
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
**明确不支持**(这一版刻意不做):`.go .rs .java .kt .c .cpp .h .hpp .cs .php .rb .swift .sql`。
|
|
311
|
+
|
|
312
|
+
为什么不一次全上:这一版要验证的命题是「**把当前任务真正需要的代码纳入上下文有没有用**」,
|
|
313
|
+
不是「支持了多少种语言」。范围越小,「没用」这个结论越可信。
|
|
314
|
+
|
|
315
|
+
### 代码的排序字段与 Markdown 不同
|
|
316
|
+
|
|
317
|
+
代码没有「标题 / 摘要 / 正文」这套结构,硬套会把文件名这个**最强的信号**降权。所以代码条目:
|
|
318
|
+
|
|
319
|
+
| 字段 | 权重 | 放什么 |
|
|
320
|
+
|---|---|---|
|
|
321
|
+
| `filename` | ×4 | `context-manager.ts` —— 文件名本身就带任务语义 |
|
|
322
|
+
| `path` | ×2 | `src/context/` —— 目录名是第二层信号 |
|
|
323
|
+
| `content` | ×1 | 文件**前 8 KB**(不是全文,见下) |
|
|
324
|
+
|
|
325
|
+
Markdown 仍是 `title ×4 / summary ×2 / body ×1`。**两套字段权重,同一个 BM25。**
|
|
326
|
+
|
|
327
|
+
### 有边界的三件事(都实测过)
|
|
328
|
+
|
|
329
|
+
- **正文有界**:代码只读前 8 KB 进语料。不是为了省磁盘,是为了让扫描时间与检索延迟
|
|
330
|
+
不随「项目里有多少 JS」线性爆炸。
|
|
331
|
+
- **候选有上限**:代码准入上限 **300 个**(Markdown 仍是 400)。
|
|
332
|
+
这个数字是**量过真实工作区**才定的 —— 不是拍的。上限存在的理由是需求里那条:
|
|
333
|
+
**代码不许把原有 Markdown 上下文挤出去。**
|
|
334
|
+
- **生成 / 噪声产物一个都不准入**:
|
|
335
|
+
|
|
336
|
+
| 不进入检索的东西 | 为什么 |
|
|
337
|
+
|---|---|
|
|
338
|
+
| `app.js.map` | source map 是调试产物,不是上下文;但同名源文件在时,它的预览里给一个「Source map」入口 |
|
|
339
|
+
| `*.min.js` `*.min.css` | 压缩产物,读它没有意义 |
|
|
340
|
+
| `*.bundle.js` `*.generated.js` `*.gen.js` | 打包 / 生成产物 |
|
|
341
|
+
| `*.lock` `package-lock.json` | 锁文件,几千行机器生成的 json |
|
|
342
|
+
| `node_modules/` `dist/` `build/` `out/` `coverage/` `…` | 沿用 v0.18 就有的目录排除,**没有重写** |
|
|
343
|
+
|
|
344
|
+
⚠️ 「不进上下文」≠「不能看」。你通过 DSH 原生文件树打开 `dist/app.js`,Knit 不拦你 ——
|
|
345
|
+
**上下文资格与文件可见性是两件事。**
|
|
346
|
+
|
|
347
|
+
### 代码预览
|
|
348
|
+
|
|
349
|
+
点一个代码文件,就在**面板下方就地展开**(和 Markdown 一模一样的位置、一样的交互,
|
|
350
|
+
没有新的弹窗):行号 + 等宽字体 + 横向滚动,页脚给复制与「本地打开」。
|
|
351
|
+
不做语法高亮、不做代码折叠、不做多标签、不做 git diff —— **Knit 不是代码浏览器**。
|
|
352
|
+
|
|
353
|
+
同类入口还有:双击进官方标签页预览(带 DSH 自己的渲染器)、`Esc` 收起、键盘 `↑↓` 预览。
|
|
354
|
+
|
|
355
|
+
---
|
|
356
|
+
|
|
286
357
|
## 也给 agent 用:`knit_docs` 工具
|
|
287
358
|
|
|
288
359
|
同一份排序,除了给你看,也开了一个口子给模型。
|
|
@@ -457,7 +528,8 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
457
528
|
|
|
458
529
|
## 它读什么,不读什么
|
|
459
530
|
|
|
460
|
-
- 扫描**当前会话工作区内**的 `.md
|
|
531
|
+
- 扫描**当前会话工作区内**的 `.md`、第一批代码后缀(见上文「代码上下文」)、图片与视频
|
|
532
|
+
(路径越出工作区一律拒绝);媒体只取元信息,不读画面内容;代码只读前 8 KB 进语料
|
|
461
533
|
- 只读**当前会话**的对话事件(用来排序)
|
|
462
534
|
- `knit_docs` 工具**只读**:不写任何文件、不落盘任何索引
|
|
463
535
|
- v0.15 的「使用情况」**默认关**:打开后也只读**当前会话已有**的工具事件(成功的 `read`),
|
|
@@ -491,8 +563,11 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
491
563
|
- **媒体只按文件名参与相关性匹配**:不解析画面 / 语音内容,截图与录屏建议用可检索的文件名
|
|
492
564
|
- **分层建立在召回之上**:如果 BM25 一篇都没把对的那篇捞进候选池,分层也只能在捞到的那几篇里分
|
|
493
565
|
—— 它救不了召回。词面错配(你问「图片和视频」,文档里写的是「媒体浏览」)就是这种情形
|
|
494
|
-
-
|
|
495
|
-
|
|
566
|
+
- **「当前任务上下文」覆盖文档与代码(v0.19,v0.14 起只覆盖文档)**:面板的媒体档、以及时间序模式都不分层
|
|
567
|
+
(那一档没有话题命中,就没有可解释的理由)。仍不解析 PDF / DOCX,也不支持第一批范围外的源码语言
|
|
568
|
+
- **代码只做词面检索,不做代码理解**:没有 AST、没有符号表、没有调用图、没有 LSP、不跳转定义。
|
|
569
|
+
文件名与路径是这一版最强的两个信号 —— 文件名起得含糊的文件(`utils.js`、`index.ts`)本来就难排上来
|
|
570
|
+
- **代码候选上限 300、正文只取前 8 KB**:超大仓库里这两条会生效,生效时面板头部的计数会显示被截断
|
|
496
571
|
- **引用关系只当上下文信号**:它能把文档放进辅助 / 相关层,**不会**把任何文档抬进主要上下文
|
|
497
572
|
- **测到的是「定位」,不是「省力」**:真机对照实验(冻结协议,四道题)里,能调 `knit_docs`
|
|
498
573
|
的 agent 总探索次数**没有下降** —— Control 4.75 → Treatment 6.0,四题逐题无一变少。
|
|
@@ -508,7 +583,7 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
508
583
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
509
584
|
cd dsh-knit
|
|
510
585
|
|
|
511
|
-
npm test #
|
|
586
|
+
npm test # 588 项,零依赖,不需要先 npm install
|
|
512
587
|
```
|
|
513
588
|
|
|
514
589
|
**改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
|
|
@@ -526,13 +601,14 @@ knit/
|
|
|
526
601
|
├── assets/ # 图标源文件(path 已内联进 client.js)
|
|
527
602
|
├── src/
|
|
528
603
|
│ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
|
|
604
|
+
│ ├── host/classification.js # 文件分类层:kind / language / 能力位(纯函数,零 I/O)
|
|
529
605
|
│ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
|
|
530
606
|
│ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
|
|
531
607
|
│ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
|
|
532
608
|
│ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
|
|
533
609
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
534
610
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
535
|
-
└── test/ #
|
|
611
|
+
└── test/ # 588 项测试
|
|
536
612
|
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
|
|
537
613
|
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
538
614
|
```
|