dsh-knit 0.23.0 → 0.24.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 +168 -0
- package/README.en.md +67 -37
- package/README.md +51 -28
- package/SECURITY.md +9 -3
- package/package.json +5 -3
- package/src/client/client.js +448 -141
- package/src/host/changes.js +208 -0
- package/src/host/git.js +377 -0
- package/src/host/index.js +228 -5
- package/test/client.test.mjs +633 -331
- package/test/git-changes.test.mjs +1238 -0
- package/test/host-http.test.mjs +4 -58
- package/test/http-harness.mjs +79 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,163 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.24.0] - 2026-10-14
|
|
7
|
+
|
|
8
|
+
> **本版定位**:新增一个**默认关闭**的能力 —— **Git 变更关联**:按工作区里**未提交的改动**
|
|
9
|
+
> 去找「还该一起看的文件」,依据是 Knit 已经有的那四类证据(引用 / 导入 / 测试配对 / 文档提及)。
|
|
10
|
+
> 按 semver 这是 minor:多了一条**用户可见**的能力、一条宿主路由,而且 `src/` 里**第一次**出现子进程。
|
|
11
|
+
>
|
|
12
|
+
> ⚠️ **本版占用了 `v0.24` 这个号**。v0.20.0 节曾把「语义/向量检索、把片段当排序基本实体、第二套预览框架」
|
|
13
|
+
> 写成「留 v0.24」—— 那是一次**非正式**的候选登记,不是承诺:其中「语义/向量检索」已由 **v0.23.0
|
|
14
|
+
> 的可选混合检索**落地;另外两条仍未做,**不因此占号**。旧节保持原样(历史不改写),以本节为准。
|
|
15
|
+
>
|
|
16
|
+
> **三条边界(本版的重点不是「找得更多」,而是「说得更准」)**:
|
|
17
|
+
> ① **`knit_docs` 与 `/knit/api/recent` 的契约一个字节未改** —— 关联走**独立接口**,专用结构,不往既有
|
|
18
|
+
> 响应里塞字段(`src/host/context.js` / `src/host/tool.js` 回到 v0.23.1 **逐字一致**);
|
|
19
|
+
> ② **只读** —— 固定 argv、不走 shell、关掉 fsmonitor 与可选索引刷新,且**子进程环境是白名单筛过的**;
|
|
20
|
+
> ③ **默认关** —— 关着时客户端一个请求都不发、宿主一个 git 进程都不 spawn。
|
|
21
|
+
|
|
22
|
+
### 新增
|
|
23
|
+
|
|
24
|
+
- **`GET /knit/api/changes`**:独立只读接口,返回**专用结构**
|
|
25
|
+
(`git{available,reason,filesTotal,truncated,files[]}` +
|
|
26
|
+
`links[{target, kind, source, title, summary, mtimeMs, evidence[{origin,type,dir,line}], evidenceTotal, types}]` +
|
|
27
|
+
`linksTotal / unresolved / outOfScope`)。**起点 / 目标 / 关系类型 / 方向 / 行号**逐条给全;
|
|
28
|
+
`tests` 那一类是文件名约定,`line` 如实为 `null`,不编行号。
|
|
29
|
+
- **面板状态行多一格二态开关「变更」**(默认关)。开态只把字色提亮(`aria-pressed`),不换底色、不用品牌色;
|
|
30
|
+
与「固定 / 关系」同属「这一份包里还装了什么」那一组,参与中点分隔、不参与编号。
|
|
31
|
+
- **变更关联区**:不编号的平行区,与三层互不影响;每条结果点开就是**既有那套行级证据**
|
|
32
|
+
(类型 · 起点 · 行号),零第二条渲染路径。
|
|
33
|
+
- **降级可辨(三种状态互不混淆)**:读到了没有变更写「变更 0」;有变更但零关联时**出区头 + 提示句**;
|
|
34
|
+
读不到写「变更 —」并把原因**直接写在列表里**(不是只放悬停)。
|
|
35
|
+
- **两个开发量尺**(`tools/`,**不进包**):`changes-value-eval.mjs`(回放真实提交,量「当时漏改、
|
|
36
|
+
后来被补上」)、`changes-forward-check.mjs`(前向对账:先写预判,再看它多说了什么)。
|
|
37
|
+
|
|
38
|
+
### 安全 / 只读边界
|
|
39
|
+
|
|
40
|
+
- **`src/` 里第一次起子进程**:只允许 `status --porcelain=v1 -z --untracked-files=all` 与
|
|
41
|
+
`rev-parse --show-prefix` 两个子命令,argv 是数组、**从不走 shell**;2.5 s 超时 / 1 MiB stdout /
|
|
42
|
+
200 条解析上限;五种失败各自收敛成一个 `reason`,**一条都不抛**。
|
|
43
|
+
- **每次都带 `--no-optional-locks --no-pager -c core.fsmonitor=false`**
|
|
44
|
+
—— 实测(git 2.50.1):裸 `status` 会**重写 `.git/index`**(300 文件 + untrackedCache + stat 缓存过期时 3/3 次)、
|
|
45
|
+
会**执行 `core.fsmonitor` 指向的钩子**、会在 `core.fsmonitor=true` 时**拉起 builtin 守护进程**;带开关后三种全为 0。
|
|
46
|
+
- **子进程环境白名单**:只继承 `PATH` / locale / `HOME` / `XDG_CONFIG_HOME` / 临时目录等运行时必需品,
|
|
47
|
+
**任何 `GIT_*` 一律不从父进程继承**。实测:`GIT_DIR`+`GIT_WORK_TREE` 会让它去读**另一个仓库**
|
|
48
|
+
(本工作区的改动直接消失)、`GIT_INDEX_FILE` 会换掉索引、`GIT_TRACE` 会往任意路径**写日志**。
|
|
49
|
+
- **不读 diff、不读文件内容、不发网络请求**;载荷里**不含绝对路径**(只有工作区相对路径)。
|
|
50
|
+
|
|
51
|
+
### 成本与降级
|
|
52
|
+
|
|
53
|
+
- 一轮轮询(两条请求)= **一次工作区扫描 + 一次 `git status`**:扫描备忘与 git 缓存**同窗 8 秒**、
|
|
54
|
+
并发去重;**关闭时两者都是 0**。真机用例正面证明过复用(窗口内删掉一个文件,两边都还看不见;
|
|
55
|
+
清掉缓存后同时反映)。
|
|
56
|
+
- 任何一步失败(不是仓库 / 没装 git / 超时 / 输出过大 / 读取失败 / 接口请求失败)都**只让这一区消失或说明原因**,
|
|
57
|
+
普通列表与 Context Pack **一个字节都不坏**。
|
|
58
|
+
|
|
59
|
+
### 变化
|
|
60
|
+
|
|
61
|
+
- **README / README.en.md**:安装示例里的测试数 775 → **828**(两份同步)。
|
|
62
|
+
- **`SECURITY.md`**:补上「只读 git」与「子进程环境白名单」两条,含实测数字。
|
|
63
|
+
- **测试 828 项 / 34 个文件**(新增 `test/git-changes.test.mjs` 与 `test/http-harness.mjs`;
|
|
64
|
+
`test/host-http.test.mjs` 的服务器替身抽到 `test/http-harness.mjs` 共用)。
|
|
65
|
+
|
|
66
|
+
### 需要重启 DSH
|
|
67
|
+
|
|
68
|
+
本版**改了宿主半边**(`src/host/*`)—— 与 v0.23.x「只要硬刷新」不同:**升级后需要重启 DSH**,
|
|
69
|
+
否则 `/knit/api/changes` 不存在,状态行那一格会显示「变更 —」并写明原因。
|
|
70
|
+
|
|
71
|
+
## [0.23.1] - 2026-10-13
|
|
72
|
+
|
|
73
|
+
> **本版定位**:这一版**不是纯 patch** —— 它一边修包装/文案,一边带了一次**用户可见的工具栏收敛**。
|
|
74
|
+
> 之所以仍出 `0.23` 这条线而不走 `0.24.0`(按 semver,用户可见的行为变化该是 minor):
|
|
75
|
+
> ① 它存在的**首要理由是包装修复**(已发布 `0.23.0` 的 tarball 内 `README.md` 写错测试数、`description`
|
|
76
|
+
> 把「零网络」说成绝对)—— 与 `v0.20.1 包装热修` 同一档;
|
|
77
|
+
> ② **`v0.24` 这个号已被文档预留给别的主题**(本文件 v0.20.0 节:「语义/向量检索、把片段当排序基本实体、
|
|
78
|
+
> 第二套预览框架 —— 留 v0.24」),拿它发一次工具栏整理会让「留 v0.24」的指向落空。
|
|
79
|
+
>
|
|
80
|
+
> **工具栏收敛** ——
|
|
81
|
+
> 类型档去掉「**全部**」(只剩 `文档 / 代码 / 媒体` 三档);**检索方式(词法 / 混合)从第二行整块搬进
|
|
82
|
+
> 第三行状态摘要**,做成一个**可点状态格**(`BM25 检索 ›`,点开菜单相对它弹出);`package.json` 描述与
|
|
83
|
+
> 两份 README 改成如实区分「**默认词法(完全本地)**」与「**可选混合(可能发往你自己配置的服务)**」。
|
|
84
|
+
> **这一版删的是一个 UI 视图,不是检索能力** —— 宿主检索 / 装配 / `knit_docs` / 统一 Context Pack / BM25 / 语义通道**一行未改**。
|
|
85
|
+
|
|
86
|
+
### 变化
|
|
87
|
+
|
|
88
|
+
- **类型档:四档 → 三档** `文档 / 代码 / 媒体`(等距,下划线式页签不变,不留空位)。
|
|
89
|
+
老用户 `localStorage` 里存着的 `'all'` **回落到 `文档`** —— 不空白、不抛错(有守卫)。
|
|
90
|
+
- **删掉「全部」这个 UI 视图**:v0.23.0 它刚被改成「整份包的原样」(三层混排文档 + 代码 + 末尾媒体网格),
|
|
91
|
+
本版又从界面上整个删除 —— 视图、渲染分支、`kind.all` / `count.all` 文案与相关守卫一并清掉。
|
|
92
|
+
⚠️ **内部跨类型检索能力保留**:宿主 `contextPayload()` 的 `kind === 'all'` 分支、`knit_docs`
|
|
93
|
+
与统一 Context Pack 都不动(`host-http.test.mjs` 里那条 `kind=all` e2e 仍在跑)。
|
|
94
|
+
- **检索方式从工具栏搬进状态行**(当日第二次裁决,推翻本版早先「挪到搜索框左侧」的中间版):
|
|
95
|
+
工具栏第二行只剩 `[相关|最新] [文档|代码|媒体] … [ ……搜索框…… ]`(搜索框仍是**唯一可伸缩项**,
|
|
96
|
+
窄面板先缩它 180–240px);状态摘要里原来那格静态文本 `BM25 词法检索` 变成**可点状态格**
|
|
97
|
+
`BM25 检索 ›` —— 点开菜单**相对这一格**弹出(`left:0;top:22px`,不是工具栏那套 `right:0/top:32px`),
|
|
98
|
+
菜单内容逐字沿用原来的:两个选项(`词法检索` / `混合检索 · 实验`)+ 当前生效状态说明 +
|
|
99
|
+
「混合没生效」时的就地配置入口。
|
|
100
|
+
- **箭头改成横向翻转**(2026-10-13 用户裁决「修改成横向翻转……默认箭头向下,交互展开箭头向上」):
|
|
101
|
+
展开态 `rotate(90deg)` → `rotate(90deg) scaleX(-1)`。两个终态是「关=朝下、开=朝上」,变的是那 0.14s
|
|
102
|
+
的过程:对调角度会让箭头**原地转 180°**(像风车),横向翻转则是「同一个字形左右翻个面」。
|
|
103
|
+
⚠️ **这里写错过一次**:先写成 `scaleY(-1)`(「垂直翻转」),文本上像有翻转、实际是**空操作** ——
|
|
104
|
+
`›` 本来就沿水平轴对称,上下镜像后还是它自己,矩阵算出来仍朝下;用户当场抓到。
|
|
105
|
+
⇒ 守卫从此是**几何**的:把 `transform` 真算成 2×2 矩阵、作用在「右箭头」的方向向量上,
|
|
106
|
+
断言关闭态 = 朝下 `(0,1)`、展开态 = 朝上 `(0,-1)`;只盯 CSS 文本的守卫**抓不到**这个空操作
|
|
107
|
+
(三条突变 —— 换回 `scaleY(-1)`、不翻转、对调角度 —— 都已确认会红)。
|
|
108
|
+
- **下划线只划文字层**(2026-10-13 用户裁决「› 悬停时不用带下划线」):下划线从按钮挪到包文字的那层
|
|
109
|
+
`.knit-pipe-method-label` —— CSS 里父级的 `text-decoration` 会传播到全部子节点、子级又取消不掉,
|
|
110
|
+
写在按钮上必然把箭头 `›` 一起划上。守卫有两面:CSS 面(按钮 hover 里**不许**出现 `text-decoration`)
|
|
111
|
+
与结构面(箭头必须是文字层的**兄弟**,不许塞进文字层里)。
|
|
112
|
+
- **状态格外观**(同日第三次、第四次裁决):文案从 `BM25 词法检索` 缩到 **`BM25 检索`**;
|
|
113
|
+
视觉**照命中段(`.knit-hit`)那套**逐条对齐 —— 底 `--knit-chip-bg`(三档灰底最深那档)、
|
|
114
|
+
**圆角 6px**、内边距 `1px 6px`、次级灰字、hover / 键盘焦点出下划线、**描边一根都没有**;
|
|
115
|
+
字号 / 行高 / 字重也与命中段**逐字同值**(`font:inherit` + `font-size:11px` + `line-height:15px`、不自己定字重)
|
|
116
|
+
—— 2026-10-13 用户裁决「字号与背景胶囊修改成命中段一样」;这一格因此比它所在的状态行(10.5px)大 0.5px,
|
|
117
|
+
那是有意的:它是这一行里唯一的可点控件,与命中段同一档才认得出「这是同一类东西」。
|
|
118
|
+
**菜单里那两个选项与「就地配置」入口同样沿用这套**(圆角 6px、选中态底 `--knit-chip-bg`);
|
|
119
|
+
菜单**面板本身保持浮层**(`bg-base` + `l3` 描边 + 阴影 + 10px 圆角)—— 浮层要读起来像浮层,
|
|
120
|
+
压成灰胶囊就没有层级了。守卫除钉数值外,还**逐值比对 `.knit-hit`**(圆角、底色两处都是取出来比,
|
|
121
|
+
不是写死常量):谁改了命中段而没改这一族控件,测试就红。行为照旧:默认词法;**「最新」档整条状态行不渲染**
|
|
122
|
+
(时间序没有 Context Pack)⇒ 格子不在,但**不重置**已存偏好 —— 切回「相关」仍是你上次选的模式。
|
|
123
|
+
- **`package.json` 描述重写**:原句「… Zero model calls, zero network, nothing leaves the machine.」**不准确**。
|
|
124
|
+
新描述说清三件事:① 默认是**纯词法**、完全本地、零模型调用、零网络出口;② **混合模式可选且默认关闭**,
|
|
125
|
+
需要你自己配置 provider;③ 配了**远程** provider 时,发出去的是工作区文件的**标题与摘要(不是正文)**,
|
|
126
|
+
指向**本机服务(loopback)**时内容不出这台机器。**不含**任何「更准 / 召回更高」的说法。
|
|
127
|
+
- **两份 README 同步**:加上「**默认词法模式下**」的限定、写明混合模式的发送范围(标题 + 摘要,正文不发送;
|
|
128
|
+
向量只在内存、配置存在 DSH 存储的独立单元 `knit_semantic`),并如实写上
|
|
129
|
+
「语义收益仍待真 provider 实测(`value-evidence: pending`)」;README.md 里「全部」视图的说明与截图段整段删除。
|
|
130
|
+
- **包内数字修正**:包内 `README.md` 的测试数改为 **775**(删掉 7 条「全部」用例、新增 4 条 → 778 − 3;
|
|
131
|
+
已发布的 `0.23.0` tarball 里那份写的还是 **728** —— 本版重新发一次把它换掉);`README.en.md` 里两处陈旧的
|
|
132
|
+
`641 tests` 也一并改成 775,并补上英文目录树缺的两个宿主文件。
|
|
133
|
+
⚠️ 这一条**连 `CHANGELOG.md` 自己也算在内**(它随包一起发):发版前核一遍**包内 README 的测试数与
|
|
134
|
+
`npm test` 的实测数一致、且旧数字 `728` 为 0 次**(`CHANGELOG.md` 里出现旧数字属于叙事,允许存在 ——
|
|
135
|
+
所以别拿 CHANGELOG 做 grep 判据,那个会自相矛盾)。
|
|
136
|
+
|
|
137
|
+
- **工具栏两处微调**(同日裁决):① 排序组与类型组之间**那根竖线删掉了**(类名与 CSS 规则整体移除,靠间距分界,
|
|
138
|
+
不留空位、不用 `display:none` 糊);② 检索模式下拉的箭头**重画** —— 不再自造向下的文本字形,改用
|
|
139
|
+
**「最近读取」行最右端那个 `›`** 旋转 90°(展开时转回朝上),箭头是 `aria-hidden` 的装饰节点,
|
|
140
|
+
可访问名仍由按钮的 `title` 承担。两条都有守卫,并各自做了突变证伪(加回竖线 / 把旧字形放回词典 ⇒ 都变红)。
|
|
141
|
+
|
|
142
|
+
**验证(2026-10-13 实测)**:`npm test` → **775 / 775**(33 个测试文件);
|
|
143
|
+
`node tools/clean-room-test.mjs` → `dsh-knit-0.23.1.tgz` · **65 个文件** · 解包后 **775 pass / 0 fail**;
|
|
144
|
+
包内核对:`version` = **0.23.1**、`README.md` 里 `728` 出现 **0** 次 / `775` 2 次、`screenshot-all` **0** 次。
|
|
145
|
+
|
|
146
|
+
### 刻意不做
|
|
147
|
+
|
|
148
|
+
- **不动宿主检索 / 装配 / BM25 / 语义通道**;不新增仪表盘、图谱、设置页;不显示分数 / 百分比 / 置信度;
|
|
149
|
+
不做禁用态的死控件;不重排三层、编号、预览与键盘导航的既有纪律。
|
|
150
|
+
- **不承诺**语义收益:真 provider 的实测仍未跑(`value-evidence: pending`),本版只改**信息准确性**与**工具栏形状**。
|
|
151
|
+
|
|
152
|
+
> ✅ **2026-10-13 已发布**:轻量 tag `v0.23.1` = 发布提交 `2925ad3` = npm `gitHead`;OIDC 可信发布
|
|
153
|
+
> run `38322653330`(**第 2 次尝试**才绿 —— 第 1 次红在 `test/index-incremental.test.mjs` 那条 v0.22 带来的
|
|
154
|
+
> **间歇性**用例上;与 0.23.0 那次是**同一根因、不同断言**,见发布 skill 台账 **B26**)、
|
|
155
|
+
> `conclusion=success`、**带 SLSA provenance**;registry `latest = 0.23.1`(共 **21 个**版本);
|
|
156
|
+
> GitHub Release `published_at 2026-10-12T23:36:24Z`。
|
|
157
|
+
> registry 上的真包 = **65 文件 / 748 583 B tarball / 2 190 275 B 解包**、
|
|
158
|
+
> shasum `1182685ac18cacd6ff337e1963f82a0528978af1`(= registry `dist.shasum`),下载解包后 `npm test` **775 / 0**。
|
|
159
|
+
> 🔑 **本版发布的首要判据已达成**:包内 `README.md` 的 `728` = **0**、`775` = **2**(0.23.0 那份是 728×2)。
|
|
160
|
+
> `check-published.mjs --online` **27/27 全过、零红** —— 0.23.0 那次唯一红掉的正是这条内容判据。
|
|
161
|
+
> ⚠️ **这一行不在已发布的 tarball 里** —— 改它的提交只能在 `npm publish` 之后(同一版本号不能再发一次)。
|
|
162
|
+
|
|
6
163
|
## [0.23.0] - 2026-10-12
|
|
7
164
|
|
|
8
165
|
> **Optional Hybrid Retrieval(可选混合检索)** —— 在**保留「可解释的词法检索」为默认**的前提下,
|
|
@@ -111,6 +268,17 @@
|
|
|
111
268
|
> 解包目录里 `npm test` **778 pass / 0 fail** ⇒ exit 0。
|
|
112
269
|
> ⚠️ 这组读数取自「界面第二条决定(「全部」档)落地过程中」的时刻;**提交 / 打包前必须重跑**
|
|
113
270
|
> (`knit/` 里任何一个在包内的字节被改,文件数与这一行都要重测)。
|
|
271
|
+
> ✅ **2026-10-12 已发布**:轻量 tag `v0.23.0` = 发布提交 `e4f5507` = npm `gitHead`;OIDC 可信发布
|
|
272
|
+
> run `38226035554`(**第 2 次尝试**才绿 —— 第 1 次红在 `test/index-incremental.test.mjs` 的抽验用例上,
|
|
273
|
+
> 那是 v0.22 带来的**间歇性**用例、不是本版回归,见该用例自己的注释)job **23 s**、
|
|
274
|
+
> `conclusion=success`、**带 SLSA provenance**;registry `latest = 0.23.0`(共 **20 个**版本);
|
|
275
|
+
> GitHub Release `published_at 2026-10-12T08:57:26Z`。
|
|
276
|
+
> registry 上的真包 = **65 文件 / 737 841 B tarball / 2 166 006 B 解包**、
|
|
277
|
+
> shasum `11efcf4ff2521c60e98c4d57c7eca77ac3a7ab81`(= registry `dist.shasum`),下载解包后 `npm test` **778 / 0**。
|
|
278
|
+
> ⚠️ **这一行不在已发布的 tarball 里** —— 改它的提交只能在 `npm publish` 之后(同一版本号不能再发一次)。
|
|
279
|
+
> ⚠️ **已发布的 tarball 里 `README.md` 仍写着「728 项」(两处)**:那是 v0.22 的数,本版漏更,
|
|
280
|
+
> 发版前没人跑内容判据、是 `check-published.mjs --online` 事后抓到的。修它的提交同样只能在发布之后
|
|
281
|
+
> ⇒ **要换掉 npm 上渲染的那份 README,必须再发一个版本。**
|
|
114
282
|
|
|
115
283
|
## [0.22.0] - 2026-10-10
|
|
116
284
|
|
package/README.en.md
CHANGED
|
@@ -9,8 +9,12 @@ relevant documents, source files and media, organises them into **Primary / Supp
|
|
|
9
9
|
context (the Context Pack) for both the panel and the agent, and keeps tracking **whether they were
|
|
10
10
|
read, and whether they changed after being read**.
|
|
11
11
|
|
|
12
|
-
**Find → Organise → Track**, all of it plain string work on your own machine
|
|
13
|
-
network, no latency, nothing leaves the machine.
|
|
12
|
+
**Find → Organise → Track**, all of it plain string work on your own machine in the **default lexical
|
|
13
|
+
mode** — no model calls, no network, no latency, nothing leaves the machine. The optional **hybrid mode
|
|
14
|
+
is off by default**: only if you configure a provider **and** switch to hybrid by hand does anything
|
|
15
|
+
leave the machine, and what leaves is **your query text plus each candidate file's title and summary**
|
|
16
|
+
(**never full bodies or absolute paths**) — with two easy-to-miss caveats spelled out under
|
|
17
|
+
**What hybrid mode actually sends** below.
|
|
14
18
|
|
|
15
19
|
```text
|
|
16
20
|
Current task
|
|
@@ -63,7 +67,7 @@ headings and the **continuous rank numbers across all tiers**, with a one-line "
|
|
|
63
67
|
only swapped once that turn had moved along (the tens of seconds in between were cut out).
|
|
64
68
|
The GIF runs faster than real time.*
|
|
65
69
|
|
|
66
|
-
Scans Markdown / images / video across the project folder · Order follows the conversation · No model calls, no network
|
|
70
|
+
Scans Markdown / images / video across the project folder · Order follows the conversation · No model calls, no network in the default lexical mode
|
|
67
71
|
|
|
68
72
|
```sh
|
|
69
73
|
dsh plugin --profile web add dsh-knit
|
|
@@ -114,7 +118,37 @@ The three differences that matter:
|
|
|
114
118
|
3. **It does not stop at finding**: after finding comes **organising** (three tiers, each with a
|
|
115
119
|
verifiable reason) and **tracking** (which were really read, and whether they changed).
|
|
116
120
|
|
|
117
|
-
**No model calls, no network
|
|
121
|
+
**No model calls, no network** in the default lexical mode: all plain string work, no latency, no cost,
|
|
122
|
+
nothing leaves the machine. Optional hybrid mode is off by default, and a **loopback** provider keeps
|
|
123
|
+
everything on this machine. ⚠️ The **benefit** of semantic retrieval still awaits a real-provider run
|
|
124
|
+
(tracked in-repo as `value-evidence: pending`) — no recall improvement is claimed.
|
|
125
|
+
|
|
126
|
+
### What hybrid mode actually sends
|
|
127
|
+
|
|
128
|
+
This section is written from **recorded request bodies**, not from design intent — for the exact
|
|
129
|
+
commands and per-claim assertions see
|
|
130
|
+
[`docs/evaluations/hybrid-retrieval.md`](https://github.com/PolinniZhong/dsh-knit/blob/main/docs/evaluations/hybrid-retrieval.md) (the audit script
|
|
131
|
+
`tools/semantic-request-audit.mjs` records the body of every request and then checks it claim by claim).
|
|
132
|
+
|
|
133
|
+
**What leaves the machine** (the request body has exactly two top-level fields, `{ model, input }`, and
|
|
134
|
+
`input` is a list of strings):
|
|
135
|
+
|
|
136
|
+
| # | What | Exact boundary |
|
|
137
|
+
|---|---|---|
|
|
138
|
+
| ① | **Your query text** | On the panel path it is the latest user message with substance, truncated to **80 characters**; on the `knit_docs(query=…)` path up to 2000. **Re-sent on every refresh** (document vectors are cached, the query is not) |
|
|
139
|
+
| ② | **Each candidate file's title** | Markdown: the first `# heading` in the body (falling back to the file name). Code: the file name **with** its extension. Images / video: the file name **without** its extension |
|
|
140
|
+
| ③ | **Each candidate file's summary** | Markdown: the **first real prose paragraph, truncated to ≤ 60 characters** — it **comes from the body**. Code: the **workspace-relative directory** (e.g. `src/host/`). Media: none |
|
|
141
|
+
|
|
142
|
+
**What does not leave the machine**: full bodies (the audit probed every long-enough file in the
|
|
143
|
+
workspace at both "first 200 chars" and "middle 200 chars" — not one hit), absolute paths (workspace
|
|
144
|
+
root / home directory / `file://` — not one hit), conversation history, files in your workspace that
|
|
145
|
+
were not selected.
|
|
146
|
+
|
|
147
|
+
⚠️ **Two things that are easy to assume wrongly**:
|
|
148
|
+
① **"summary" does not mean "metadata unrelated to the body"** — a Markdown summary is an excerpt of the
|
|
149
|
+
body, so **up to 60 characters of body text do leave the machine**;
|
|
150
|
+
② **image / video file names are sent too** (they have no summary, so what is sent is the file name
|
|
151
|
+
itself, e.g. `screenshot-media`).
|
|
118
152
|
|
|
119
153
|
---
|
|
120
154
|
|
|
@@ -149,7 +183,7 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
149
183
|
| **Relation evidence** (v0.21): every row carries `retrieval` / `relation` / `pinned`; "why" expands **line-level evidence** (references / imports / tests / documents, with the other file and the line number — at most 3 per item in the panel, 2 through the tool). Every one of them can be grepped back to its original line: not a word of the reasoning is invented | ✅ |
|
|
150
184
|
| **Pin / exclude** (v0.21): pinning moves an item into its own section at the top (unnumbered — the three tiers keep their numbering); excluding takes effect **before retrieval** (the counts and the status summary move together, and it is undoable); with host storage it **survives restarts**, without it the panel says "this session only (not persisted)" instead of pretending | ✅ |
|
|
151
185
|
| **Retrieval status summary** (v0.21.x): one honest line in the panel header — `collected · excluded · candidates | BM25 lexical retrieval · relations · pinned | in pack` (mid-dots inside a group, one thin rule between groups, no arrows); it follows the task, the kind tab, pins and exclusions | ✅ |
|
|
152
|
-
| **Toolbar in one row** (
|
|
186
|
+
| **Toolbar in one row** (2026-10-12): `Relevance / Newest` (sort) `Docs / Code / Media` (kind) — **no rule between the two groups**, spacing separates them | the filter box sits at the right (the only flexible item — 180–240px, shrinking first when the panel narrows). **Retrieval mode is not in this row**: it is a **clickable status cell** in the third row (`BM25 retrieval ›`); the **four options are independent** — switching sort / kind / retrieval mode never touches the query | ✅ |
|
|
153
187
|
| **Header count** (v0.21.x): digits only (`9`, or `3 / 79` while filtering) — the quantifier changes with the kind, so it stays off screen; hovering still gives the full phrase (`9 code files`) | ✅ |
|
|
154
188
|
| One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
|
|
155
189
|
| Scans **documents and code** in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist` / `build` / `out` / `coverage`) | ✅ |
|
|
@@ -157,11 +191,10 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
157
191
|
| 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 | ✅ |
|
|
158
192
|
| Click to preview inline, click again to collapse | ✅ |
|
|
159
193
|
| Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
|
|
160
|
-
| One-click switch between **Docs / Code / Media
|
|
194
|
+
| One-click switch between **Docs / Code / Media** (v0.19 adds Code; remembered, defaults to Docs); the selected tab is an **underline tab**, deliberately different from the list row's grey fill. The **All** tab was removed from the UI in v0.23.1 | ✅ |
|
|
161
195
|
| 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) | ✅ |
|
|
162
196
|
| **"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 | ✅ |
|
|
163
197
|
| Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
|
|
164
|
-
| 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) | ✅ |
|
|
165
198
|
| Preview pane is height-draggable (20%–80%, remembered), fullscreen-able, `Esc` to exit | ✅ |
|
|
166
199
|
| **"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 | ✅ |
|
|
167
200
|
| Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
|
|
@@ -171,13 +204,15 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
171
204
|
| 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) | ✅ |
|
|
172
205
|
| Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
|
|
173
206
|
| Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
|
|
174
|
-
| Zero model calls
|
|
207
|
+
| **Zero model calls / zero network egress by default**: the default **lexical mode** is plain string work on this machine | ✅ |
|
|
208
|
+
| **Optional hybrid mode (off by default)** (v0.23): needs a provider you configure (Ollama / OpenAI-compatible). With a **remote** provider, what leaves the machine is **your query text plus each candidate file's title and summary** — never full bodies or absolute paths, but note that a Markdown "summary" is a **≤ 60-character excerpt of the body** and image / video files send their **file name** (the exact boundaries are in **What hybrid mode actually sends** above); vectors live in memory only and the config sits in its own DSH storage unit (`knit_semantic`). A **loopback** provider keeps everything local. ⚠️ The **benefit** of semantic retrieval still awaits a real-provider run (`value-evidence: pending`) — no recall improvement is claimed | ✅ |
|
|
209
|
+
| **Git change links (off by default)** (v0.24): lists "what else to look at" from your **uncommitted changes**, using the evidence Knit already has (references / imports / test pairing / doc mentions) — every row names its **origin, kind and line**. **Read-only**: one `git status` (fsmonitor and optional index refresh disabled, child-process environment whitelisted so no `GIT_*` is inherited), **no diff, no file bodies, no network**; when it cannot read, it writes the reason in the panel instead of hiding it in a tooltip. ⚠️ This version adds a host route — **restart DSH after upgrading** | ✅ |
|
|
175
210
|
| **A `knit_docs` tool for the agent** — read-only, so the model can find this project's relevant docs itself | ✅ |
|
|
176
211
|
|
|
177
212
|
> Relevance is deliberately **not visualised** (no percentages, no bars) — the ranking itself is
|
|
178
213
|
> the answer; position is relevance.
|
|
179
214
|
|
|
180
|
-
### The
|
|
215
|
+
### The Media view
|
|
181
216
|
|
|
182
217
|

|
|
183
218
|
|
|
@@ -188,18 +223,6 @@ single-colour SVG icon (the solid black square is that icon, not a failed load).
|
|
|
188
223
|
frame as a poster with a play glyph and a duration badge — this workspace simply has no video, so none
|
|
189
224
|
shows here.*
|
|
190
225
|
|
|
191
|
-

|
|
192
|
-
|
|
193
|
-
*All: the documents section shows at most 4, the **code section** shows at most 4 (each gets its own
|
|
194
|
-
"View all →" when truncated — here "4 / 21" and "4 / 8"), and the media grid (11 rows) comes last.*
|
|
195
|
-
|
|
196
|
-
⚠️ All three sections share the **same 40-item window** the host returns — a category that ranks past
|
|
197
|
-
40th by relevance drops out of the All view entirely. This screenshot uses the **Newest** sort: in this
|
|
198
|
-
workspace, under the default Relevance sort, media rank outside that window every time (at `limit=40`
|
|
199
|
-
those 40 rows are documents + code files). The **Media** and **Code** tabs are unaffected — they
|
|
200
|
-
request their own kind. A known defect, with reproduction and the fix recorded in
|
|
201
|
-
[`docs/README.md`](docs/README.md).*
|
|
202
|
-
|
|
203
226
|
---
|
|
204
227
|
|
|
205
228
|
## Current task context (v0.14)
|
|
@@ -396,7 +419,7 @@ no percentage, no colour scale; in the flat list and under **Newest** none of th
|
|
|
396
419
|
### The retrieval status summary in the header
|
|
397
420
|
|
|
398
421
|
One line of fact in the panel header:
|
|
399
|
-
`collected N · excluded N · candidates N | BM25
|
|
422
|
+
`collected N · excluded N · candidates N | BM25 retrieval · relations N · pinned N | in pack N`.
|
|
400
423
|
The three groups are the reading order: **workspace candidates** (how many were scanned, how many
|
|
401
424
|
this batch really ruled out, how many went on into retrieval), **retrieval and adjustment** (this
|
|
402
425
|
path is plain local BM25, followed by how many relation evidence items are in the pack and how many
|
|
@@ -411,19 +434,24 @@ note → notice → lens → list).
|
|
|
411
434
|
|
|
412
435
|
### The toolbar row (v0.21.x)
|
|
413
436
|
|
|
414
|
-
`Relevance / Newest` (sort) | one light-grey rule | `Docs / Code / Media
|
|
415
|
-
box (
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
437
|
+
`Relevance / Newest` (sort) | one light-grey rule | `Docs / Code / Media` (kind) | a **right-aligned
|
|
438
|
+
group**: only the filter box (the **only flexible item**). **No rule between sort and kind** (the `.knit-bar-sep` class is gone).
|
|
439
|
+
**Retrieval mode lives in the status summary** as a clickable cell: `BM25 retrieval ›` (**visually the same recipe as the hit segment `.knit-hit`**: `--knit-chip-bg` background, 6px radius, `1px 6px` padding, secondary grey text, **font size / line-height / weight identical to the hit segment** (11px / 15px, no local font-weight); on hover only the **label** brightens and gets the underline — the `›` arrow never does; the arrow is the `›` from the Recent-read row, flipped horizontally when open). Its menu opens **relative to that cell** and holds the two options (same hit-segment recipe: 6px radius, `--knit-chip-bg` when selected), the current effective state, and the inline config entry when hybrid is unavailable. The menu **panel** itself stays a floating surface (`bg-base` + `l3` border + shadow).
|
|
440
|
+
|
|
441
|
+
- **Sort / kind / retrieval mode are three conditions, not one segmented control** (the rule that used to sit between sort and kind was removed on 2026-10-12, `.knit-bar-sep` no longer exists): the former `.knit-bar-sep`
|
|
442
|
+
(1px, `border-l3`, `aria-hidden`) is the boundary. The kind group used to sit on its own row; its
|
|
443
|
+
selected state is still the v0.14 **underline tab** — it did not fall back to a grey-filled button.
|
|
444
|
+
- **The far right is one right-aligned container (`.knit-bar-right`)**: it holds the **retrieval-mode**
|
|
445
|
+
dropdown (`flex:none`, compact) and the **filter box** (`flex:1 1 180px` + `min-width:0` +
|
|
446
|
+
`max-width:240px`). The filter box is the **only flexible item** ⇒ it sits at 180–240px against the
|
|
447
|
+
right edge and **shrinks first** when the panel narrows; sort / kind / retrieval mode are all
|
|
448
|
+
`flex:none` and are **never squeezed**.
|
|
449
|
+
- **The four conditions are independent**: pick Code and then Newest and you get the newest code;
|
|
450
|
+
switching retrieval mode does not touch the sort or the query; the query only filters the current
|
|
451
|
+
scope (`sort` / `kind` / `query` / `retrieval` are four separate pieces of state).
|
|
452
|
+
- ⚠️ **The retrieval-mode dropdown is not shown under Newest** (time order has no Context Pack, so there
|
|
453
|
+
is nowhere for semantic candidates to land), but it is **not reset** — switching back to Relevance
|
|
454
|
+
keeps the mode you picked.
|
|
427
455
|
- No icons, no loud pills; the other entries use secondary text, the selected one an underline plus
|
|
428
456
|
the primary text colour.
|
|
429
457
|
|
|
@@ -799,7 +827,7 @@ feature request.
|
|
|
799
827
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
800
828
|
cd dsh-knit
|
|
801
829
|
|
|
802
|
-
npm test #
|
|
830
|
+
npm test # 828 tests, zero dependencies, no npm install needed
|
|
803
831
|
```
|
|
804
832
|
|
|
805
833
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -822,10 +850,12 @@ knit/
|
|
|
822
850
|
│ ├── host/classification.js # v0.19 file classification: kind / language / searchable / contextual
|
|
823
851
|
│ ├── host/passage.js # passage layer: chunking / passage scoring / line mapping (pure, zero I/O)
|
|
824
852
|
│ ├── host/context.js # context assembly: the three-tier Context Pack (pure, zero I/O)
|
|
853
|
+
│ ├── host/index-store.js # incremental index store: per-record KV + head fingerprint + fallback (v0.22)
|
|
854
|
+
│ ├── host/semantic.js # optional semantic candidates: two provider protocols / bounded embedding / honest fallback (v0.23)
|
|
825
855
|
│ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
|
|
826
856
|
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
827
857
|
│ └── client/client.js # dual-host registration + panel UI
|
|
828
|
-
└── test/ #
|
|
858
|
+
└── test/ # 828 tests
|
|
829
859
|
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
830
860
|
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
831
861
|
```
|
package/README.md
CHANGED
|
@@ -8,7 +8,10 @@ Knit 接的是**当前任务**和**整个工作区**之间那一层:从工作
|
|
|
8
8
|
组织成 **主要 / 辅助 / 相关** 三层上下文(Context Pack),交给面板、也交给 agent;
|
|
9
9
|
再持续追踪这些上下文**有没有被读、被读之后有没有变**。
|
|
10
10
|
|
|
11
|
-
**找到 → 组织 →
|
|
11
|
+
**找到 → 组织 → 追踪**,默认的**词法模式**三步都在本机用字符串运算完成 —— 不调模型、不联网、零延迟、内容不出本机。
|
|
12
|
+
可选的**混合模式默认关闭**:只有你自己配好 provider **并且**手动切到混合检索,才会有出网请求;
|
|
13
|
+
那时发出去的是**你这句查询原话 + 每篇候选文件的标题与摘要**(**完整正文、绝对路径都不发**)——
|
|
14
|
+
⚠️ 这里有两个容易想当然的地方,见下面的「**混合模式到底发出去了什么**」。
|
|
12
15
|
|
|
13
16
|
```text
|
|
14
17
|
当前任务
|
|
@@ -55,7 +58,7 @@ Knit 接的是**当前任务**和**整个工作区**之间那一层:从工作
|
|
|
55
58
|
*⚠️ 面板是**每 5 秒轮询一次**的,重排不是发消息那一瞬间:这一屏里顶上几条是这一轮对话推进之后才整个换掉的*
|
|
56
59
|
*(中间那几十秒被剪掉了)。动图比真实时间快。*
|
|
57
60
|
|
|
58
|
-
扫整个项目文件夹的文档 / 代码 / 图片 / 视频 · 排序跟着对话走 ·
|
|
61
|
+
扫整个项目文件夹的文档 / 代码 / 图片 / 视频 · 排序跟着对话走 · 默认词法模式下不调模型、不联网
|
|
59
62
|
|
|
60
63
|
```sh
|
|
61
64
|
dsh plugin --profile web add dsh-knit
|
|
@@ -103,7 +106,30 @@ v0.19 起代码进了同一条链路。再往后,「排在前面」也不够
|
|
|
103
106
|
聊架构,架构文档浮上来;聊 loader 的 bug,`plugin-loader.ts` 浮上来。
|
|
104
107
|
3. **它不止于「找」**:找完还要**组织**(三层 + 可核验的理由)和**追踪**(哪些真被读了、读完有没有变)。
|
|
105
108
|
|
|
106
|
-
|
|
109
|
+
**默认词法模式下不调模型、不联网**:全是本地字符串运算,零延迟、零成本、内容不出本机。
|
|
110
|
+
可选的**混合模式默认关闭**,指向**本机服务(loopback)**时内容不出这台机器。
|
|
111
|
+
⚠️ 语义收益仍待真 provider 实测(`value-evidence: pending`),不承诺召回提升。
|
|
112
|
+
|
|
113
|
+
### 混合模式到底发出去了什么
|
|
114
|
+
|
|
115
|
+
这段是**按报文实测**写的,不是按设计意图写的 —— 复现命令与逐条断言见
|
|
116
|
+
[`docs/evaluations/hybrid-retrieval.md`](https://github.com/PolinniZhong/dsh-knit/blob/main/docs/evaluations/hybrid-retrieval.md)(审计脚本
|
|
117
|
+
`tools/semantic-request-audit.mjs` 会把每一次请求的 body 录下来再逐条判)。
|
|
118
|
+
|
|
119
|
+
**发出去了**(请求体只有 `{ model, input }` 两个字段,`input` 是一串文本):
|
|
120
|
+
|
|
121
|
+
| # | 内容 | 精确边界 |
|
|
122
|
+
|---|---|---|
|
|
123
|
+
| ① | **你这句查询原话** | 面板走会话路径时是「最近一条有实质内容的用户消息」,截到 **80 字**;`knit_docs(query=…)` 走显式路径时最多 2000 字。**每一轮刷新都会重发一次**(文档向量有缓存,查询没有) |
|
|
124
|
+
| ② | **每篇候选文件的标题** | Markdown 是正文里的第一个 `# 标题`(没有就用文件名);代码是**带扩展名的文件名**;图片 / 视频是**去掉扩展名的文件名** |
|
|
125
|
+
| ③ | **每篇候选文件的摘要** | Markdown 的「摘要」是**正文首个正文段落的节选(≤ 60 字)**——它**来自正文**;代码的「摘要」是**工作区相对目录**(如 `src/host/`);媒体没有摘要 |
|
|
126
|
+
|
|
127
|
+
**没有发出去**:完整正文(审计对工作区里每一篇够长的文件都做了「开头 200 字 + 中段 200 字」两处探针,一处都没出现)、
|
|
128
|
+
绝对路径(工作区根 / 家目录 / `file://` 一条都没出现)、会话历史、你工作区里没被选中的文件。
|
|
129
|
+
|
|
130
|
+
⚠️ **两个容易想当然的地方**:
|
|
131
|
+
①**「摘要」不等于「与正文无关的元数据」**——Markdown 的摘要是正文的节选,所以**会有至多 60 字的正文离开本机**;
|
|
132
|
+
②**图片 / 视频的文件名也会被发出去**(它们没有摘要,发的是文件名本身,例如 `screenshot-media`)。
|
|
107
133
|
|
|
108
134
|
---
|
|
109
135
|
|
|
@@ -131,12 +157,12 @@ dsh plugin --profile web add dsh-knit
|
|
|
131
157
|
|
|
132
158
|
| 能力 | |
|
|
133
159
|
|---|---|
|
|
134
|
-
| **按当前对话相关性排序**(BM25 + IDF
|
|
160
|
+
| **按当前对话相关性排序**(BM25 + IDF)—— **默认纯本地、零模型调用**;可选的混合模式默认关闭,见下 | ✅ |
|
|
135
161
|
| **当前任务上下文**:把排序结果拆成 **主要 / 辅助 / 相关** 三层,每条都写明「为什么在这里」 | ✅ |
|
|
136
162
|
| **关系证据**(v0.21):每行标出 `检索` / `关系` / `用户固定`;「为什么」展开**行级证据**(引用 / 导入 / 测试 / 文档,带对方文件与行号,面板最多 3 条、工具最多 2 条)—— 每条都能按行号 grep 回原文,一个字的理由都不是编的 | ✅ |
|
|
137
163
|
| **固定 / 排除**(v0.21):固定进最上方独立区(不编号,三层编号不变);排除在**检索之前**生效(计数与状态摘要同时变,可恢复);宿主给了存储就**活过重启**,没给就写明「本会话有效(未持久化)」 | ✅ |
|
|
138
164
|
| **检索状态摘要**(v0.21.x):面板头部一行如实显示 `收集 · 排除 · 候选 | BM25 词法检索 · 关系 · 固定 | 入包`(组内中点、组间细竖线、没有箭头),换任务 / 换档都跟着变 | ✅ |
|
|
139
|
-
| **工具栏一行**(
|
|
165
|
+
| **工具栏一行**(2026-10-12):`相关 / 最新`(排序)`文档 / 代码 / 媒体`(类型)—— 两组之间**没有竖线**,靠间距分界 | 右侧是搜索框(唯一可伸缩项,常规 180–240px,面板窄了先缩它,其余按钮永不被挤)。**检索方式不在这行** —— 它是第三行状态摘要里的**可点状态格**(`BM25 检索 ›`,见下一条);**四项彼此独立** —— 切排序 / 切类型 / 切检索方式都不动搜索词 | ✅ |
|
|
140
166
|
| **顶行计数**(v0.21.x):只显示阿拉伯数字(`9` / 过滤时 `3 / 79`)—— 量词随类型档变,索性不上屏;悬停提示里仍是完整那句(`9 个代码文件`) | ✅ |
|
|
141
167
|
| **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
|
|
142
168
|
| **文档生命周期**(v0.17):每篇推荐文档现在处于 `未读 / 已读 / 读后已更新 / 修改后已重新读取` 哪一档,另外给出最近读了哪篇、包外读了哪几篇、上下文最近一次怎么变 | ✅ |
|
|
@@ -149,10 +175,9 @@ dsh plugin --profile web add dsh-knit
|
|
|
149
175
|
| 单击就地展开预览,再点收起 | ✅ |
|
|
150
176
|
| 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
|
|
151
177
|
| **代码上下文**(v0.19):`.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm .css .scss .yaml .yml .sh .bash .zsh` 与 Markdown **进同一个检索池**,共用同一份 BM25、同一个 Context Pack、同一套生命周期 —— 不是第二套「代码搜索」 | ✅ |
|
|
152
|
-
| **文档 / 代码 /
|
|
178
|
+
| **文档 / 代码 / 媒体** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**下划线式页签**(v0.14 起就是这个;不带品牌色描边、也**没**退回灰底按钮 —— 2026-09-29 明确裁定过;页签「媒体」2026-10-06 由「图片与视频」改短,「代码」v0.19 加入;**「全部」档 v0.23.1 已从 UI 删除**) | ✅ |
|
|
153
179
|
| 图片与视频:方形缩略图网格,**格子基准固定 104px、列数由宽度连续数出来**(320px → 2 列 / 632px → 5 列 / 1200px → 10 列),格子大小基本不变;**纵向有多少行就铺多少行**,超出交给列表滚动;视频自动取首帧、叠播放三角与时长角标(零依赖、不转码) | ✅ |
|
|
154
180
|
| 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
|
|
155
|
-
| 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
|
|
156
181
|
| 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出;**全屏时头部 / 排序条 / 类型档 / 使用情况 / 列表全部让位**,预览铺满整个面板 | ✅ |
|
|
157
182
|
| **「本地打开」**:用系统默认应用打开当前预览的这篇文档;**预览头那条路径点开的是它「所在的文件夹」并顺带选中这个文件**(reveal,macOS 是 Finder 里 `open -R`;与顶部那行工作区路径同一套机制,差别只在「打开目录」vs「定位到文件」,完整相对路径在悬停提示里) | ✅ |
|
|
158
183
|
| 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
|
|
@@ -164,11 +189,13 @@ dsh plugin --profile web add dsh-knit
|
|
|
164
189
|
| 每 5 秒自动刷新 + 手动刷新;2 分钟内改动过的文档打 🆕 | ✅ |
|
|
165
190
|
| 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
|
|
166
191
|
| 列表是标准 `listbox`/`option` 语义,选中项用 `aria-activedescendant` 播报;媒体网格里的键盘焦点有可见描边 | ✅ |
|
|
167
|
-
|
|
|
192
|
+
| **默认零模型 / 零网络出口**:默认的**词法模式**全程在本机做字符串运算 —— 不调模型、不联网、零延迟 | ✅ |
|
|
193
|
+
| **可选混合模式(默认关闭)**(v0.23):需你自己配置 provider(Ollama / OpenAI 兼容)。配了**远程** provider 时,发出去的是**你这句查询原话 + 每篇候选文件的标题与摘要** —— 完整正文与绝对路径都不发,但 Markdown 的「摘要」是**正文首个段落 ≤ 60 字的节选**、图片 / 视频发的是**文件名**(逐条口径见上面的「**混合模式到底发出去了什么**」);向量只在内存里,配置存在 DSH 存储的独立单元 `knit_semantic`。指向**本机服务(loopback)**时内容不出这台机器。⚠️ **语义收益的证据仍待真 provider 实测**(`value-evidence: pending`)—— 本项目**不承诺**召回提升 | ✅ |
|
|
194
|
+
| **Git 变更关联(默认关闭)**(v0.24):按工作区里**未提交的改动**列出「还该一起看的文件」,依据是 Knit 已有的四类证据(引用 / 导入 / 测试配对 / 文档提及),每条都给出**起点 + 类型 + 行号**。**只读**:只跑一条 `git status`(关掉 fsmonitor 与可选索引刷新,子进程环境白名单 —— 任何 `GIT_*` 都不继承),**不读 diff、不读文件正文、不发网络**;读不到时如实写出原因(不是只放在悬停里)。⚠️ 本版新增宿主接口,**升级后需要重启 DSH** | ✅ |
|
|
168
195
|
|
|
169
196
|
> 相关度**不做可视化**(不显示百分比、不画长条)—— 排序本身就是答案,名次即相关度。
|
|
170
197
|
|
|
171
|
-
###
|
|
198
|
+
### 媒体档长什么样
|
|
172
199
|
|
|
173
200
|

|
|
174
201
|
|
|
@@ -177,14 +204,6 @@ dsh plugin --profile web add dsh-knit
|
|
|
177
204
|
*(那个纯黑方块是单色 SVG 图标本身,不是加载失败)。*
|
|
178
205
|
*视频会取首帧当海报、中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
|
|
179
206
|
|
|
180
|
-

|
|
181
|
-
|
|
182
|
-
*全部:**文档区最多 4 条**、**代码区最多 4 条**(超出时各区右侧给「查看全部 →」,这一屏是「4 / 21」与「4 / 8」),最后是媒体网格(11 条)。*
|
|
183
|
-
*⚠️ 三个区共用宿主返回的**同一个 40 条窗口**:某一类如果按相关性排到第 40 名之外,「全部」档就整个看不到它。*
|
|
184
|
-
*这张图用的是**「最新」排序** —— 在这个工作区里,默认的「相关」排序下媒体恒定掉在 40 条窗口之外*
|
|
185
|
-
*(`limit=40` 时那 40 条全是文档 + 代码)。**「媒体」/「代码」档不受影响**,它们各自单独取。*
|
|
186
|
-
*这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
|
|
187
|
-
|
|
188
207
|
---
|
|
189
208
|
|
|
190
209
|
## 当前任务上下文(v0.14)
|
|
@@ -259,7 +278,7 @@ Context Pack 是对这个问题的回答,但它是**数据层的结构**(主
|
|
|
259
278
|
(top-1 / MRR / 陷阱用例)一行没动。如果检索没把对的那篇找出来,分层也只能在
|
|
260
279
|
找到的那几篇里分 —— 它救不了召回。
|
|
261
280
|
- **不做任务理解。** Context Pack 里那个「当前任务」字段放的是**最近一条用户消息的原文**,
|
|
262
|
-
不是任何概括 —— Knit 不解一句话的意思,只是把它如实摆出来。真去概括需要模型,而 Knit
|
|
281
|
+
不是任何概括 —— Knit 不解一句话的意思,只是把它如实摆出来。真去概括需要模型,而 Knit 的默认词法模式不调模型。
|
|
263
282
|
|
|
264
283
|
---
|
|
265
284
|
|
|
@@ -386,7 +405,7 @@ Markdown 仍是 `title ×4 / summary ×2 / body ×1`。**两套字段权重,
|
|
|
386
405
|
|
|
387
406
|
### 头部那条检索状态摘要
|
|
388
407
|
|
|
389
|
-
面板头部一行事实:`收集 N · 排除 N · 候选 N | BM25
|
|
408
|
+
面板头部一行事实:`收集 N · 排除 N · 候选 N | BM25 检索 · 关系 N 条 · 固定 N | 入包 N`。
|
|
390
409
|
三组就是阅读顺序 —— **工作区候选**(扫描到多少、这一批真的排掉几篇、排除之后剩几篇进入检索)、
|
|
391
410
|
**检索与调整**(这一路是纯本地 BM25 词法检索,后面跟着包里的关系证据条数与被固定移出三层的篇数)、
|
|
392
411
|
**最终结果**(三层现有条目数)。
|
|
@@ -398,15 +417,18 @@ Markdown 仍是 `title ×4 / summary ×2 / body ×1`。**两套字段权重,
|
|
|
398
417
|
|
|
399
418
|
### 工具栏那一行(v0.21.x)
|
|
400
419
|
|
|
401
|
-
`相关 /
|
|
420
|
+
`相关 / 最新`(排序)`文档 / 代码 / 媒体`(类型)(**两组之间没有竖线**)|右侧只有搜索框(**唯一可伸缩项**)。
|
|
421
|
+
**检索方式 = 状态摘要里的可点状态格**:(`BM25 检索 ›`;视觉**照命中段 `.knit-hit` 那套**:底 `--knit-chip-bg`、圆角 6px、内边距 `1px 6px`、次级灰字、**字号 / 行高 / 字重与命中段逐字同值**(11px / 15px、不自己定字重);hover 只提亮文字并给**文字**加下划线,右边的箭头 `›` **不划线**(2026-10-13 用户裁决:那一格的下划线只属于文字层);箭头复用「最近读取」行那个 `›`,展开时**横向翻转**向上);点开菜单**相对这一格**弹出,里面是 `词法检索 / 混合检索 · 实验` 两个选项(**同样沿用命中段那套**:圆角 6px、选中态底 `--knit-chip-bg`)、当前生效状态的说明,以及「混合没生效」时的就地配置入口。菜单**面板本身**仍是浮层(`bg-base` 底 + `l3` 描边 + 阴影)—— 浮层要读起来像浮层。
|
|
402
422
|
|
|
403
|
-
-
|
|
423
|
+
- **排序 / 类型 / 检索方式是三个条件,不做成一个整体**:排序与类型之间的竖线 2026-10-12 已删除(`.knit-bar-sep` 整个类名不复存在,靠 `.knit-bar` 的间距分界);检索方式则**搬进了状态行**(第三行),不再占工具栏的位置 —— 从前那根线(1px、`border-l3`、`aria-hidden`)
|
|
404
424
|
就是边界。类型组原先自己占一行,现在并进工具栏 —— 选中态仍是 v0.14 的下划线式页签,没退回灰底按钮。
|
|
405
|
-
-
|
|
406
|
-
`
|
|
407
|
-
|
|
408
|
-
-
|
|
409
|
-
|
|
425
|
+
- **最右是一个右对齐容器(`.knit-bar-right`)**:里面是**检索模式**(`flex:none`,紧凑下拉)与**搜索框**
|
|
426
|
+
(`flex:1 1 180px` + `min-width:0` + `max-width:240px`)。搜索框是**唯一可伸缩项** ⇒
|
|
427
|
+
常规面板里它就是 180–240px 并贴住右端,面板变窄时**先缩它**;排序 / 类型 / 检索模式都是 `flex:none`,**永不被挤**。
|
|
428
|
+
- **四个条件彼此独立**:选「代码」再选「最新」= 最新的代码;切检索模式不动排序与搜索词;搜索只过滤当前范围
|
|
429
|
+
(`sort` / `kind` / `query` / `retrieval` 四个独立 state)。
|
|
430
|
+
- ⚠️ **「最新」档不显示检索模式**(时间序没有 Context Pack,语义无处可落),但**不重置**已存的偏好 ——
|
|
431
|
+
切回「相关」时仍是你上次选的那个模式。
|
|
410
432
|
- 没有图标、没有醒目的胶囊;其余项用次级文本,选中项用下划线 + 主色文字。
|
|
411
433
|
|
|
412
434
|
---
|
|
@@ -739,7 +761,7 @@ v0.17 的信息都在,但**摞在一行字和几个折叠块里**,读不出
|
|
|
739
761
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
740
762
|
cd dsh-knit
|
|
741
763
|
|
|
742
|
-
npm test #
|
|
764
|
+
npm test # 828 项,零依赖,不需要先 npm install
|
|
743
765
|
node tools/clean-room-test.mjs # 发版前闸门:npm pack → 解包 → 在解包目录里再跑一遍测试
|
|
744
766
|
```
|
|
745
767
|
|
|
@@ -766,10 +788,11 @@ knit/
|
|
|
766
788
|
│ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
|
|
767
789
|
│ ├── host/control.js # 固定 / 排除:纯逻辑 + 可选 ctx.storage 持久化
|
|
768
790
|
│ ├── host/index-store.js # 增量索引持久层:per-record KV + 头部指纹 + 降级 + 遗留键清理(v0.22)
|
|
791
|
+
│ ├── host/semantic.js # 可选语义候选:provider 两协议 / 有界嵌入 / 明着回退(v0.23)
|
|
769
792
|
│ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
|
|
770
793
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
771
794
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
772
|
-
└── test/ #
|
|
795
|
+
└── test/ # 828 项测试
|
|
773
796
|
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线 + Deep Context 四指标
|
|
774
797
|
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
775
798
|
```
|