dsh-knit 0.13.0 → 0.14.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 +166 -0
- package/README.en.md +155 -9
- package/README.md +148 -14
- package/package.json +5 -2
- package/src/client/client.js +501 -197
- package/src/host/context.js +568 -0
- package/src/host/index.js +305 -20
- package/src/host/relevance.js +44 -6
- package/src/host/tool.js +274 -58
- package/test/client.test.mjs +488 -92
- package/test/context/fixture.mjs +553 -0
- package/test/context-eval.test.mjs +576 -0
- package/test/context.test.mjs +542 -0
- package/test/harness.mjs +33 -7
- package/test/host-http.test.mjs +71 -0
- package/test/host.test.mjs +105 -0
- package/test/i18n.test.mjs +46 -3
- package/test/tool.test.mjs +328 -96
- package/tools/json-schema-subset.mjs +89 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,172 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.14.0] - 2026-09-29
|
|
7
|
+
|
|
8
|
+
**从「按当前对话给文档排序」升级成「按对话构建当前任务最需要的项目上下文」。**
|
|
9
|
+
排序引擎(BM25)一行没改,工具没有重写 —— 这一版加的是**排序之上的一层**;
|
|
10
|
+
面板只在相关模式下从一条平铺列表改成**三层分组**(单栏),没有重做 ——
|
|
11
|
+
当天稍后又按真机体验改了**四处形态**:右栏从「固定 310px」改成可以拖宽、可以拖出去浮动、
|
|
12
|
+
拖回右缘重新停靠;文档列表从「最多 2 列」改成**永远单列**,每篇的第一行改成
|
|
13
|
+
「序号 + Primary 点 + 相对时间」的元信息行、标题独占下一行;**列表行里的路径删掉了**
|
|
14
|
+
(它和预览头的面包屑重复 —— 用户原话「点开查看文档详情的时候已经有了」);**序号
|
|
15
|
+
从元信息行里搬了出来,成了每行最左边独立的一列**;最后**时间也回到标题那一行、靠右**,
|
|
16
|
+
序号与标题第一行**垂直居中**(见下)。
|
|
17
|
+
|
|
18
|
+
⚠️ **当天最后一条裁定(2026-09-29):右侧那个「当前任务上下文」说明栏被删除了。**
|
|
19
|
+
用户把 v0.14 的 UI 重新定了一条线 —— **Context Pack 是数据层的结构,不是一个要单独显示出来的
|
|
20
|
+
UI 卡片**;它直接落在文档列表的分组里(主要 / 辅助 / 相关,组名后跟一句极短说明)。理由是三重的:
|
|
21
|
+
右栏与左侧分组**信息重复**(当前任务=列表上方那行弱化元信息、「命中 N 篇」=头部总数、
|
|
22
|
+
三条证据类型=三个组名)、「视觉价值有限」、「容易把 Knit 做成 AI Dashboard」,也不符合 Knit
|
|
23
|
+
「安静、开发者工具、高信息密度、可信」的方向。随右栏一起删除的还有它那套
|
|
24
|
+
**调宽 / 拖出浮动 / 右缘吸附**与把手 —— 真正只有它用得上的代码,一起删干净。
|
|
25
|
+
同一条裁定还带来四处收窄:排序依据那行**不再出现关键词**(退到 `title` 属性里当低层 metadata,
|
|
26
|
+
可见文本只有「相关性排序」)、组与组之间**不再画横线**(只留 16px 空间)、`why` 文案从
|
|
27
|
+
「直接命中当前话题:a、b」缩成「直接命中:a · b」、文档标题从 12.5px 提到 **14px**
|
|
28
|
+
(序号的 `line-height` 同步成 19.6px = 14 × 1.4,这是两者垂直居中的唯一手段)。
|
|
29
|
+
|
|
30
|
+
### 加了什么
|
|
31
|
+
|
|
32
|
+
| 新增 | 说明 |
|
|
33
|
+
|---|---|
|
|
34
|
+
| **Context Pack(当前任务上下文)** | 把一次检索结果拆成 **主要上下文 / 辅助上下文 / 相关上下文** 三层,不再只有一条平铺的列表 |
|
|
35
|
+
| **每条都带「为什么在这里」** | 理由来自确定性事实:命中在标题 / 摘要 / 正文(附命中的词)、被主要上下文引用、引用了主要上下文。**不是**「AI 判断这篇重要」 |
|
|
36
|
+
| **面板的「当前任务上下文」视图** | 相关模式下文档档改成**三层分组**(主要 / 辅助 / 相关,组名后跟一句极短说明),列表本身仍是那份可搜索 / 可预览 / 可键盘导航的文档列表,**永远单栏**。⚠️ 它**先被做成双栏**(左列表 + 右说明栏),当天就被用户删掉 —— 见本节开头那条裁定 |
|
|
37
|
+
| ~~**右栏可拖宽 / 可拖出浮动**(当天追加、当天又删)~~ | 固定 310px 在 1000–1300px 这一段会把左栏挤到只剩一列,所以右栏一度改成:拖左侧把手调宽(260–420px,键盘 ←/→ 也能调)、拖面板头部拖出去变成浮窗、拖回右缘 28px 内松手重新停靠,头部还有「浮动 / 停靠」按钮。**面板本身被删除后,这套几何交互(把手 / 拖拽 / 吸附 / 宽度变量 / 三个纯函数)一起删干净了** —— 留着一套永远调用不到的代码,下一个人只会以为它还在生效 |
|
|
38
|
+
| **文档列表永远单列**(当天追加) | 用户原话:「文档列表最多一个就行,现在一行两个有点太多了」。**多列那套是整体删除,不是关掉**:`docLayoutFor` / `DOC_TRACK_PX` / `DOC_GRID_MAX_COLS` / `DOC_SUMMARY_MIN_PX` / `.knit-multicol*` 全部不存在(测试反过来守「它真的没了」)。**行一改成元信息行**:序号 + Primary 点 + 相对时间同一行,**标题独占下一行**,摘要再往下(这一行的形态当天又改了两次:序号先搬成最左边独立一列,随后时间也回到标题那一行 —— 见下面两行)|
|
|
39
|
+
| **列表行里不再有路径**(当天追加) | 用户原话:「文档列表中的文档路径,我觉得不需要出现了,因为点开查看文档详情的时候已经有了,所以这里是重复的,隐藏掉」。删掉的是 `.knit-meta` 这个节点本身(**不是 `display:none`**)—— 预览头那条**可点的路径面包屑**(`.knit-preview-path`:目录浅 + 文件名亮)始终显示完整路径。⚠️ 这**不是**「多列砍字段」那条教训的复发:那条守的是「不许因为排版窄就静默少给信息」,而路径是**重复信息**;**摘要仍然任何情况下都不许 `display:none`**。行的定位不走可见路径,`data-knit-rel` 仍在 |
|
|
40
|
+
| **序号独立成最左边一列**(当天追加) | 用户原话:「文档列表序号放在独立最左边,其他数据放在右边」(附了一张示意图)。列表行改成**两列 grid**:第一列=序号(`.knit-num`,22px 固定轨道),第二列=其余全部数据(`.knit-body`,`minmax(0,1fr)` + 必须写 `min-width:0`,否则长标题会把行撑宽、省略号失效)。**行一从此只剩 Primary 点 + 相对时间**(序号不在它里面了)。**没有序号的行不渲染序号节点**(时间序 / 筛选结果 /「其他相关文档」),但那一列由 grid 轨道保着 —— `.knit-body` 的位置写死 `grid-column:2`,正文不会掉进第一列,左边缘始终和有条目的行对齐。**当天最后一条**:时间不再单独占一行 —— 用户要求「将时间放到标题同行,时间放在右边,然后标题跟时间就可以以序号平行,居中平行」⇒ **行一=Primary 点 + 标题 + 时间**(时间靠右,靠 `.knit-title` 的 `flex:1 1 auto` + `min-width:0` 把它推到行尾,长标题在时间之前省略);序号那一列靠 `.knit-num` 的 `line-height:17.5px`(=标题 `12.5px × 1.4`)与标题第一行**垂直居中** —— ⚠️ 改标题字号或行高时必须同步改它,否则序号会与标题错开 |
|
|
41
|
+
| **行的静止态不再有底色**(当天追加) | 用户原话:「深色模式下,文档列表没有选中,鼠标没有悬停,不需要有背景。或者是说,跟深色模式的最底下的背景一样」。`.knit-doc` 的静止态从 `bg-layer-1` 改成 **`transparent`**(露出面板 / 宿主侧边栏的底色)—— 浅色主题下这两个令牌都是 `#fff`(看不出差别),**暗色主题下 `bg-layer-1` 比底色亮一档**,于是每一行都像一张浮起来的小卡片,哪怕没选中、没悬停。hover 与 `.active` 各有自己的令牌,**不动**(都改成 transparent 的话,一屏灰里就认不出选中态了) |
|
|
42
|
+
| **`knit_docs` 返回分层上下文** | 模型拿到的从「Top N」变成 `Primary / Supporting / Related`,每项带 `source`(实现 / 测试 / 配置 / 设计 / 文档)与结构化 `reason` |
|
|
43
|
+
| **`/knit/api/context`** | 独立的上下文接口。`/api/recent` 里也顺带给一个可选的 `context` 字段(老客户端忽略它) |
|
|
44
|
+
| **`src/host/context.js`** | 上下文装配层。纯函数、零 I/O,只吃 `rankByRelevance()` 的名次与 `links.js` 的引用图 |
|
|
45
|
+
| **`test/context.test.mjs`** | 规则本身的单元测试(SDD 要的八组:Primary / 无相关 / Supporting / Related / 去重 / 确定性 / 理由 / 上限)。**手写输入、不调 `rankByRelevance()`** |
|
|
46
|
+
| **`test/context-eval.test.mjs` + `test/context/fixture.mjs`** | 24 篇语料 / 12 条真实任务型用例的**离线 Context Pack 评测**(与 BM25 评测**分开**,互不覆盖),末尾按 SDD §27 报 **Primary@1 / Supporting Recall / Role Precision** 三个具名指标 |
|
|
47
|
+
| **`tools/json-schema-subset.mjs`** | 测试与真机探针**共用**的一份 JSON Schema 子集校验器。不引 ajv —— 本包零依赖,引工作区外那份会让 `npm test` 依赖一个绝对路径 |
|
|
48
|
+
| **`tools/replay-cases.mjs`** | **在进程内重放**评审文档 §10 那 5 个真实案例(`import` 源码跑 `execute()`,**不需要重启宿主、也不看运行中的进程**),并打印「平铺 top6 / 前两层 / 提上来 / 降下去 / 零命中靠引用」。加了 `--full` 就打印 agent 真正收到的那段文本 |
|
|
49
|
+
|
|
50
|
+
测试:**285 → 402 → 403 → 395**(`cd knit && npm test`)。402 那次的最后 7 条是右栏拖宽 / 浮动 / 吸附;
|
|
51
|
+
403 是「列表永远单列 + 行一不含标题」两条守卫替换掉一条多列测试后的净增一条;
|
|
52
|
+
**最后降到 395 是删掉右栏的直接结果** —— 12 条双栏 / 右栏用例整条删掉,只补了 4 条单栏守卫
|
|
53
|
+
(「即使宿主给了 Context Pack,DOM 里也没有任何右栏骨架」「源码里不再有任何右栏 CSS 规则 / 函数 / 常量」
|
|
54
|
+
「组与组之间只靠 16px 空间(不再画横线)」「关键词退到 title」)。
|
|
55
|
+
|
|
56
|
+
> ⚠️ **评审文档 §10 那 5 个案例的旧输出已经作废。** 它们是**上限 3 / 5 / 12 那一版**的快照,
|
|
57
|
+
> 上限收敛到 1 / 3 / 5 之后「辅助 5 / 相关 12」不再可复现 —— 用 `node tools/replay-cases.mjs`
|
|
58
|
+
> 全部重跑过了,旧数字一个没留。重跑后最值得记的两条:**案例 3 从「没有主文档」变成
|
|
59
|
+
> 主文档就是那篇 SDD(本节唯一一条 `direct`)**;而**案例 1 的 Primary 是错的** ——
|
|
60
|
+
> 一篇 UI 设计文档靠摘要里「审美**关键词**」蹭进了主要上下文。
|
|
61
|
+
> ⇒ **「有落脚点」只保证话题词出现在标题或摘要里,不保证那篇讲的是这件事。**
|
|
62
|
+
|
|
63
|
+
### 分层规则(确定性,可逐条解释)
|
|
64
|
+
|
|
65
|
+
| 层 | 判据 | 上限 |
|
|
66
|
+
|---|---|---|
|
|
67
|
+
| 主要上下文 | 命中,**且**有「落脚点」(话题词命中标题或摘要),**且**相关度 ≥ 最高分的 30% | 1 |
|
|
68
|
+
| 辅助上下文 | 对某个「焦点词」有**深入命中**(该词不止一篇在讲,且这一篇是把它讲得最多的那一篇);**或**与某个主要上下文有引用关系 | 3 |
|
|
69
|
+
| 相关上下文 | 其余**有命中**的条目,以及零命中但有引用关系的邻居 | 5 |
|
|
70
|
+
|
|
71
|
+
上限是**上限,不是配额**:主要上下文允许为空,相关上下文也允许为空。
|
|
72
|
+
「说不出凭什么」的条目**不出场** —— 零命中又没有任何引用关系的文档不是「与当前任务有关」,
|
|
73
|
+
放它进来只能给它一句「与当前工作区相关」,那正是需求禁止的「可能对你有帮助」。
|
|
74
|
+
|
|
75
|
+
三条都是**实测调出来的**,踩过的三个坑写在 `src/host/context.js` 的文件头:
|
|
76
|
+
|
|
77
|
+
1. 只要求「命中 ≥2 个话题词」时,满篇话题词的 `CHANGELOG` 与「什么话题都提一句」的长归档霸占主要上下文;
|
|
78
|
+
2. 只看「话题词命中标题/摘要」时,摘要里正好出现话题词的文档也会被抬进主要上下文;
|
|
79
|
+
3. 只看「正文里出现过」时,每个话题词各提一句的长归档会进**每一条**任务的辅助上下文。
|
|
80
|
+
|
|
81
|
+
### 顺带修掉的四个真实缺陷
|
|
82
|
+
|
|
83
|
+
- **`knit_docs` 在 v0.14 上是坏的 —— 每次调用都在校验层失败**(最严重的一条)。
|
|
84
|
+
工具的输出 schema 是封闭的(`additionalProperties: false`),而三层条目实际带了三个
|
|
85
|
+
没被声明的字段(`kind`、`reason.term`、`totals`),`mtimeMs` 还是浮点
|
|
86
|
+
(`fs.Stats.mtimeMs` 本来就是浮点,schema 写的是 `integer`;时间序那条分支一直是取整的,
|
|
87
|
+
两边不一致)。结果是 agent 侧**一个 Context Pack 都拿不到**,而 335 条测试全绿 ——
|
|
88
|
+
因为所有 tool 测试都是拿手写的假 payload 测渲染,**从来没有把 `execute()` 的真实返回值
|
|
89
|
+
交给它自己的 schema 校验过**。是在做「Control vs Treatment」真机对照实验时暴露的:
|
|
90
|
+
4 个 Treatment 会话 100% 报
|
|
91
|
+
`tool "knit_docs" returned invalid output: "value.primary[0].mtimeMs" must be an integer; …`。
|
|
92
|
+
现在 schema 补齐、`mtimeMs` 在投影层取整,并新增两条测试:一条把真实 `execute()` 的返回值
|
|
93
|
+
(relevance 与 time 两种模式)喂给它自己的 schema,一条反向确认那个校验器真的抓得住
|
|
94
|
+
「漏声明字段」和「该整数给了浮点」。
|
|
95
|
+
- **`knit_docs` 的头部会写「0 matching documents」而下面列着结果**:返回的三层结果漏了 `totals.matched`,
|
|
96
|
+
渲染层回落成 0。测试当时是全绿的 —— 现在有两条回归用例钉住它。
|
|
97
|
+
- **`rankByRelevance` 的并列兜底键依赖输入排列**:`raw` 与 `mtimeMs` 都相同时按「输入下标」定序,
|
|
98
|
+
换个扫描顺序就会换序。改成按 `rel` 定序 —— 这是「相同输入必须产出完全相同顺序」那条承诺的前提。
|
|
99
|
+
- **工具在「工作区有文档、但一个词都没命中」时说了假话**:三层全空时它返回
|
|
100
|
+
`No Markdown documents found in the workspace.` —— 而工作区里明明有 49 篇。
|
|
101
|
+
代码注释里其实已经写明「`total` 是正数而三层全空」是另一种情形,**只有输出字符串没跟着分开**。
|
|
102
|
+
现在分开了,并且把限制和下一步一起说出来:
|
|
103
|
+
`No document matched the current topic — 0 of 49 Markdown documents contain the query terms.` /
|
|
104
|
+
`Matches come from the first 2500 characters of each file; use grep for anything deeper.`
|
|
105
|
+
真机触发场景:问「路径越界怎么防」,49 篇一篇都没命中 —— 因为文档侧只看每篇**前 2500 字**
|
|
106
|
+
(`index.js` 的 `HAYSTACK_CHARS`),而这个词在 5 篇 `.md` 里**全部**出现在 2500 字之后
|
|
107
|
+
(`knit/CHANGELOG.md` @29033、`knit/README.md` @9099、`03_发布/发布文档规划.md` @5200、
|
|
108
|
+
`01_ Knit PRD/Knit_SDD-v0.7-agent文档工具.md` @7342、`01_ Knit PRD/Knit_评审-v0.14-ContextPack.md` @7808)。
|
|
109
|
+
⚠️ **没有动那个 2500 字的窗口** —— 改它等于改检索行为,会推翻 `test/eval/` 里那套冻结的
|
|
110
|
+
v0.5.2 基线。所以这一版只是**不再说假话**,窗口本身留给下一版单独决策。
|
|
111
|
+
|
|
112
|
+
### 没有做的事(刻意)
|
|
113
|
+
|
|
114
|
+
- **不改 BM25**:`relevance.js` 的打分逻辑一行没动,`test/eval.test.mjs` 的 top-1 / MRR / 陷阱
|
|
115
|
+
四条断言原样保留、原样通过。新增的只是「把第 1 趟已经算过的命中词留下来」。
|
|
116
|
+
- **不引入 embedding / 模型 / 网络 / 数据库 / 长期记忆**。Context Pack 是一层**纯投影**。
|
|
117
|
+
- **不做任务理解**:`task` 字段装的是**最近一条用户消息的原文**,不是任何概括 ——
|
|
118
|
+
Knit 不解一句话的意思,只是把它如实摆出来给人看。工具返回值里**不带** `task`
|
|
119
|
+
(模型看到的是渲染后的文本,头部已经用话题标签说了「这次按什么排的」)。
|
|
120
|
+
- **不新增第二套打分**:没有 `contextScore`,界面上也没有百分比、星级、置信度条。
|
|
121
|
+
Eval 报的 `Primary@1 / Supporting Recall / Role Precision` 是**集合关系**,
|
|
122
|
+
不是分数门槛(没有「必须 > 80%」这种断言)。
|
|
123
|
+
- **不重扫工作区**:`collect → relevance → links → context assembly` 复用同一批结果,
|
|
124
|
+
引用图复用 `collectDocs` 已经读进内存的正文首部,零额外 I/O。
|
|
125
|
+
- **不声称「让 agent 少读几篇」—— 这一版实测是反的。** 重启后用冻结协议跑了
|
|
126
|
+
Control vs Treatment 各 4 次(同 4 条任务、同一个 50 篇工作区):Treatment 的工具调用
|
|
127
|
+
均值 **6.0** vs Control **4.75**,逐题 **6 vs 5 · 5 vs 5 · 9 vs 5 · 4 vs 4**,**没有一题变少**
|
|
128
|
+
(算上那次 `knit_docs` 调用则是 7.0 vs 4.75)。唯一被消掉的是 `glob`,代价是
|
|
129
|
+
`read` 从 1.75 涨到 3.75、`distinct files read` 从 1.5 涨到 2.75;四条答案**全部正确**,
|
|
130
|
+
所以不是「省了调用但答错」,是单纯没省。**它给出的价值是「定位 + 解释」**
|
|
131
|
+
(该看哪几篇、为什么、有没有主文档),**不是省力**。完整数据见
|
|
132
|
+
`01_ Knit PRD/Knit_评审-v0.14-ContextPack.md` 附三。
|
|
133
|
+
|
|
134
|
+
## [0.13.1] - 2026-09-23
|
|
135
|
+
|
|
136
|
+
**只改文档,插件行为一行没动。** 没有新功能、没有修 bug ——
|
|
137
|
+
**装过 `0.13.0` 的人没有任何必须升级的理由。**
|
|
138
|
+
|
|
139
|
+
那为什么还要发一版?因为 **npm 页面上渲染的 README 是「已发布 tarball 里的那一份」**。
|
|
140
|
+
`0.13.0` 之后我们往 README 里补了重排动图和两张真机截图,但那个包的 README 是**冻结**的 ——
|
|
141
|
+
不重新发一版,npm 那个页面就永远停在老版本:没有动图、没有反馈入口。
|
|
142
|
+
|
|
143
|
+
### 包内实际变化
|
|
144
|
+
|
|
145
|
+
只有两个文件(其余改动不在 `package.json` 的 `files` 白名单里,压根不进包):
|
|
146
|
+
|
|
147
|
+
| 文件 | 变化 |
|
|
148
|
+
|---|---|
|
|
149
|
+
| `README.md` / `README.en.md` | 第 1 屏接上**重排动图**;新增「反馈」与「升级」两节;补「图片与视频」「全部」两档真机截图;图注篇数 `34 → 36`;更正关于下载量的说法;修掉过期的测试数 |
|
|
150
|
+
| `CHANGELOG.md` | 本节 |
|
|
151
|
+
|
|
152
|
+
### 不进包的改动(在仓库里,但 `files` 没收录)
|
|
153
|
+
|
|
154
|
+
| 文件 | 说明 |
|
|
155
|
+
|---|---|
|
|
156
|
+
| `docs/demo-reorder.gif`(新增 1.3 MB) | README 用**绝对 raw URL** 引用,所以 npm 页面上照样显示 |
|
|
157
|
+
| `docs/screenshot-media.png` / `screenshot-all.png`(新增) | 同上 |
|
|
158
|
+
| `screenshots.json` | **1 张 → 3 张**(市场详情页的相册会自动跟着变,不用提 PR) |
|
|
159
|
+
| `tools/make-demo-gif.mjs`(新增) | 录屏 → GIF 的编码器,含 `--crop` |
|
|
160
|
+
| `tools/market-recheck.mjs`(新增) | 市场索引 + 下载量复查,含「形状判读」 |
|
|
161
|
+
|
|
162
|
+
### 顺带纠正一句我们自己说错的话
|
|
163
|
+
|
|
164
|
+
npm 的下载量**不是人**。决定性证据:`0.5.0` 只当了 **28 分 09 秒** `latest` 就被下载 **155** 次,
|
|
165
|
+
而 `0.13.0` 当了 **59.6 小时** 才 **161** 次 —— **曝光时长差 127 倍,下载量只差 1.04 倍**
|
|
166
|
+
(皮尔逊 r = 0.317;真实安装应当接近 +1)。`npm install` 只解析 `latest`,
|
|
167
|
+
**没有哪个真人渠道能造出这个形状**。版本分布也是平线:8 个版本几乎均分,
|
|
168
|
+
`latest` 占比只有 **14.4%**(对照真包 60–80%)。
|
|
169
|
+
|
|
170
|
+
⇒ README 里现在按这个口径写:**那个数字不能读成「这么多人在用」。**
|
|
171
|
+
|
|
6
172
|
## [0.13.0] - 2026-09-20
|
|
7
173
|
|
|
8
174
|
**三件事,都是真机体验打回来之后改的:**
|
package/README.en.md
CHANGED
|
@@ -7,13 +7,21 @@
|
|
|
7
7
|
|
|
8
8
|

|
|
9
9
|
|
|
10
|
-
*Screenshot from a real machine, not a mock-up: a workspace with
|
|
10
|
+
*Screenshot from a real machine, not a mock-up: a workspace with 36 documents — the list, an inline
|
|
11
11
|
preview, and the references bar.*
|
|
12
12
|
*The references bar is new in v0.12: expand it to see which documents reference this one, and click
|
|
13
13
|
one to jump straight there.*
|
|
14
14
|
*The top line follows whatever you're talking about; when there isn't enough conversation yet it
|
|
15
15
|
falls back to newest-first and states its basis.*
|
|
16
16
|
|
|
17
|
+

|
|
18
|
+
|
|
19
|
+
*Order follows the conversation — same workspace, same session: ask "how is BM25 weighted for the
|
|
20
|
+
ranking?" and the sorting docs move to the top; then ask "how do I check plugin-market listings and
|
|
21
|
+
download counts?" and the market-research docs take over.*
|
|
22
|
+
*⚠️ The panel polls **every 5 seconds**, so the re-rank lands **0–5 s** after the message rather than
|
|
23
|
+
instantly, and the GIF runs faster than real time.*
|
|
24
|
+
|
|
17
25
|
Scans Markdown / images / video across the project folder · Order follows the conversation · No model calls, no network
|
|
18
26
|
|
|
19
27
|
```sh
|
|
@@ -123,17 +131,102 @@ All of it is string arithmetic — **no embeddings, no model calls**.
|
|
|
123
131
|
|
|
124
132
|
---
|
|
125
133
|
|
|
134
|
+
## Current task context (v0.14)
|
|
135
|
+
|
|
136
|
+
Ranking answers "which documents look most like this conversation". But the question you
|
|
137
|
+
usually have is a different one:
|
|
138
|
+
|
|
139
|
+
> **For this task, what in the project should I read first?**
|
|
140
|
+
|
|
141
|
+
The Context Pack is the answer to that question, but it is a **data-layer structure**
|
|
142
|
+
(Primary / Supporting / Related, each entry carrying a deterministic reason) — **not a card of
|
|
143
|
+
its own**. So it lands directly in the document list: in relevance mode the document view goes
|
|
144
|
+
from one flat list to **three tier groups**, each group name followed by a very short hint.
|
|
145
|
+
|
|
146
|
+
```
|
|
147
|
+
┌─ Documents ──────────────────────────────┐
|
|
148
|
+
│ Primary read first │
|
|
149
|
+
│ 01 ● Relevance ranking algorithm 5m ago│
|
|
150
|
+
│ title matches: ranking │
|
|
151
|
+
│ │
|
|
152
|
+
│ Supporting supporting │
|
|
153
|
+
│ 02 Ranking evaluation set 2h ago │
|
|
154
|
+
│ body matches: term counting │
|
|
155
|
+
│ │
|
|
156
|
+
│ Related background │
|
|
157
|
+
│ 03 CHANGELOG.md 12d ago│
|
|
158
|
+
│ body matches: ranking │
|
|
159
|
+
└───────────────────────────────────────────┘
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
> The sketch leaves out each entry's summary. **The real structure is: a number in its own column
|
|
163
|
+
> on the far left (vertically centred with the first line), and to its right a stack of one line —
|
|
164
|
+
> Primary dot + title + relative time (right-aligned) — then the summary** (**no path** — it is not
|
|
165
|
+
> shown in the list; the path lives in the preview header's breadcrumb). And the list is
|
|
166
|
+
> **always one column** however wide the pane gets.
|
|
167
|
+
|
|
168
|
+
**No rules between groups**: hierarchy comes from 16px of space, the group name and type size,
|
|
169
|
+
never from separators. No scores, no percentages, no stars — "why is it here" states
|
|
170
|
+
deterministic facts only.
|
|
171
|
+
|
|
172
|
+
> **The right-hand "Current task context" panel has been removed** (2026-09-29). It said the same
|
|
173
|
+
> thing the three groups already say (the task sits in the quiet meta line above the list, the hit
|
|
174
|
+
> count duplicates the header total, and the three evidence kinds *are* the three group names), it
|
|
175
|
+
> added little visually, and it pushed Knit toward being an AI dashboard. Its
|
|
176
|
+
> resize / pull-out / snap-to-right-edge behaviour went with it — see `CHANGELOG.md`.
|
|
177
|
+
|
|
178
|
+
### The tiers are deterministic rules, not an AI judgement
|
|
179
|
+
|
|
180
|
+
| Tier | When a document enters it | Cap |
|
|
181
|
+
|---|---|---|
|
|
182
|
+
| **Primary** | It matched, **and** it is *grounded* (a topic term hits its title or summary), **and** its relevance is not background noise (≥ 30% of the top score) | 1 |
|
|
183
|
+
| **Supporting** | It has a **deep hit** on a *focus term* (that term is discussed in more than one document, and this document discusses it the most); **or** it is linked to a primary document (either direction, labelled separately) | 3 |
|
|
184
|
+
| **Related** | Everything else that matched, plus zero-hit link neighbours | 5 |
|
|
185
|
+
|
|
186
|
+
A cap is a **ceiling, not a quota**: primary is allowed to be empty (on real workspaces a fair
|
|
187
|
+
share of topics genuinely have no document that discusses them), and so is related. **If there
|
|
188
|
+
is no checkable reason, the document does not appear** — a document with zero hits and no link
|
|
189
|
+
is not "related to the current task"; the only caption it could carry is "this might help you",
|
|
190
|
+
which is exactly what this release refuses to print.
|
|
191
|
+
|
|
192
|
+
**"Why it is here"** is always a checkable fact:
|
|
193
|
+
|
|
194
|
+
| Reason | What it says |
|
|
195
|
+
|---|---|
|
|
196
|
+
| title / summary / body matches the topic: `term` | It really matched, and here is which term |
|
|
197
|
+
| referenced by a primary document | A path in the primary document points here |
|
|
198
|
+
| references a primary document | It mentions the primary document |
|
|
199
|
+
|
|
200
|
+
There is **no** "the AI thinks this matters" and **no** percentages, stars or confidence bars.
|
|
201
|
+
|
|
202
|
+
### Boundaries (stated, not oversold)
|
|
203
|
+
|
|
204
|
+
- **A link is not "more relevant".** Measured: the link graph does not close the vocabulary-mismatch
|
|
205
|
+
gap. So a link can only place a document in supporting / related — **never** in primary.
|
|
206
|
+
- **The ranking engine is unchanged.** This release adds a projection layer *above* ranking;
|
|
207
|
+
BM25 scoring and its evaluation (top-1 / MRR / trap cases) are untouched. If retrieval never
|
|
208
|
+
surfaced the right document, tiering can only tier what was surfaced — it cannot fix recall.
|
|
209
|
+
- **No task understanding.** The "Current task" line in the panel holds the **verbatim text of the
|
|
210
|
+
most recent user message**, not a summary of it — Knit does not interpret the sentence, it just
|
|
211
|
+
puts it where you can see it. Actually summarising it would need a model, and Knit calls none.
|
|
212
|
+
|
|
213
|
+
---
|
|
214
|
+
|
|
126
215
|
## Also for the agent: the `knit_docs` tool
|
|
127
216
|
|
|
128
217
|
The same ranking that you see in the panel is also exposed to the model.
|
|
129
218
|
|
|
130
219
|
Once installed, the agent's tool list gains `knit_docs`: it can ask *"which documents in this
|
|
131
|
-
project are most relevant to what we're discussing?"* and get back **
|
|
132
|
-
|
|
220
|
+
project are most relevant to what we're discussing?"* and get back **the same Context Pack** the
|
|
221
|
+
panel shows — the `primary` / `supporting` / `related` tiers, each item carrying its path, title,
|
|
222
|
+
summary, a **structured reason** (`direct` / `titleMatch` / `summaryMatch` / `bodyMatch` /
|
|
223
|
+
`linkTarget` / `linkSource` / `related`), its **project role** (`impl` / `test` / `config` /
|
|
224
|
+
`design` / `doc`) and the matching snippet — then open one of them with its own `read` tool.
|
|
133
225
|
|
|
134
226
|
**Why it helps**: to cite a document that already exists, an agent can only guess paths or glob
|
|
135
|
-
and `read` them one by one
|
|
136
|
-
|
|
227
|
+
and `read` them one by one. Knit has **already computed that ranking** every refresh; this tool
|
|
228
|
+
just hands it over — what it removes is **the "which few are relevant?" guess** (measured: an
|
|
229
|
+
agent holding the Pack no longer globs for candidates).
|
|
137
230
|
|
|
138
231
|
**Read-only, and it stores nothing**: it reads the files that are already in the project — this is
|
|
139
232
|
not "memory". The difference from memory plugins is that **theirs start empty** (the agent has to
|
|
@@ -172,6 +265,27 @@ Then **restart DSH** and hard-refresh the browser (`Cmd + Shift + R`).
|
|
|
172
265
|
**Optional**: if `dsh-better-sidebar` is installed, the panel also registers
|
|
173
266
|
as one of its tabs. Each host is an independent optional dependency; missing one doesn't affect the other.
|
|
174
267
|
|
|
268
|
+
**Upgrading**: same command as installing, and the same restart + hard-refresh afterwards.
|
|
269
|
+
|
|
270
|
+
---
|
|
271
|
+
|
|
272
|
+
## Feedback
|
|
273
|
+
|
|
274
|
+
**Right now this project is not about adding features — it's about finding out whether
|
|
275
|
+
"rank project docs by the current conversation" is something anyone actually uses.**
|
|
276
|
+
So the most valuable thing you can send is not "could you add X" but **how you work around
|
|
277
|
+
this today** — including "I installed it and never opened it", which is more useful than a
|
|
278
|
+
feature request.
|
|
279
|
+
|
|
280
|
+
- 💬 [Tell us when you actually open it](https://github.com/PolinniZhong/dsh-knit/issues/new?template=feature.yml) — two fields, thirty seconds
|
|
281
|
+
- 🐞 [Won't install / panel won't open / ranking looks wrong](https://github.com/PolinniZhong/dsh-knit/issues/new?template=bug.yml)
|
|
282
|
+
- 📖 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
|
|
283
|
+
|
|
284
|
+
> A single issue is treated as a real signal. So far this plugin has **no trace of a single
|
|
285
|
+
> real user** — the npm download count is automated version enumeration, not people
|
|
286
|
+
> (only 14% of it is `latest`, and a human install only ever pulls `latest`). One human reply
|
|
287
|
+
> changes what gets built next.
|
|
288
|
+
|
|
175
289
|
---
|
|
176
290
|
|
|
177
291
|
## Features
|
|
@@ -183,6 +297,7 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
183
297
|
| One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
|
|
184
298
|
| Scans `.md` in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist`) | ✅ |
|
|
185
299
|
| Each row shows H1 title (or filename) + relative time + first-paragraph summary | ✅ |
|
|
300
|
+
| 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 breadcrumb** in the preview header, which is the one that stays | ✅ |
|
|
186
301
|
| Click to preview inline, click again to collapse | ✅ |
|
|
187
302
|
| Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
|
|
188
303
|
| One-click switch between **Docs / Images & video / All** (remembered; defaults to Docs, unchanged); the selected tab is a **neutral grey fill**, with no coloured outline | ✅ |
|
|
@@ -195,7 +310,7 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
195
310
|
| Filter box over title / summary / path | ✅ |
|
|
196
311
|
| **Click the workspace path** to open the project folder in your file manager | ✅ |
|
|
197
312
|
| **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) | ✅ |
|
|
198
|
-
| Keyboard: `↑` `↓` move-and-preview, `Enter` toggle, `Esc` collapse | ✅ |
|
|
313
|
+
| 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) | ✅ |
|
|
199
314
|
| Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
|
|
200
315
|
| Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
|
|
201
316
|
| Zero model calls, zero network egress | ✅ |
|
|
@@ -204,6 +319,27 @@ as one of its tabs. Each host is an independent optional dependency; missing one
|
|
|
204
319
|
> Relevance is deliberately **not visualised** (no percentages, no bars) — the ranking itself is
|
|
205
320
|
> the answer; position is relevance.
|
|
206
321
|
|
|
322
|
+
### The other two views
|
|
323
|
+
|
|
324
|
+

|
|
325
|
+
|
|
326
|
+
*Images & video: square thumbnails, with the **column count following the panel width continuously** —
|
|
327
|
+
six columns at this width, cells about 112px. Videos show their first frame as a poster with a play
|
|
328
|
+
glyph and a duration badge. These are the workspace's real image and SVG files; this particular
|
|
329
|
+
workspace happens to hold several screenshots and two icon files.*
|
|
330
|
+
|
|
331
|
+

|
|
332
|
+
|
|
333
|
+
*All: documents on top (max 4, with a "View all →" link when truncated) and images & video below
|
|
334
|
+
(**never truncated**, count only). All four fields — title, time, summary, path — were present.*
|
|
335
|
+
|
|
336
|
+
⚠️ **This screenshot is from v0.13**, when documents could still lay out in two columns *and* rows still
|
|
337
|
+
carried the path. **Since v0.14 the list is always one column** (the number now sits in its own column
|
|
338
|
+
on the far left, with Primary dot + relative time, then the title, stacked to its right), and **the path
|
|
339
|
+
is no longer shown in the list** (the preview header's breadcrumb always shows the full path, so the
|
|
340
|
+
duplicate was dropped).
|
|
341
|
+
The screenshot has not been retaken yet.
|
|
342
|
+
|
|
207
343
|
---
|
|
208
344
|
|
|
209
345
|
## What it reads, and what it doesn't
|
|
@@ -244,6 +380,11 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
244
380
|
video `mp4/m4v/webm/mov/ogv`; images ≤ 12MB and video ≤ 256MB or they are not listed
|
|
245
381
|
- **Media matches relevance by filename only**: no visual/audio content is parsed — give
|
|
246
382
|
screenshots and recordings searchable names
|
|
383
|
+
- **What we measured is *locating*, not *saving work***: in the on-machine A/B (frozen protocol,
|
|
384
|
+
four questions), an agent that could call `knit_docs` did **not** explore less — Control 4.75 →
|
|
385
|
+
Treatment 6.0 total tool calls, and no single question went down. The Pack did replace the
|
|
386
|
+
initial `glob` for candidates, but the **doubled `read` count** ate that back. It points
|
|
387
|
+
attention at the right file; that is **not** the same as the agent reading fewer files
|
|
247
388
|
- **Right-sidebar state is memory-only**: a refresh or a new session collapses it again
|
|
248
389
|
|
|
249
390
|
---
|
|
@@ -254,7 +395,7 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
254
395
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
255
396
|
cd dsh-knit
|
|
256
397
|
|
|
257
|
-
npm test #
|
|
398
|
+
npm test # 395 tests, zero dependencies, no npm install needed
|
|
258
399
|
```
|
|
259
400
|
|
|
260
401
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -271,10 +412,15 @@ knit/
|
|
|
271
412
|
├── cordis.patch.yml # the insert line mounted into the plugin tree
|
|
272
413
|
├── assets/ # icon source (path inlined into client.js)
|
|
273
414
|
├── src/
|
|
274
|
-
│ ├── host/index.js # /knit/api/recent · /doc · /raw
|
|
415
|
+
│ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
|
|
275
416
|
│ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
|
|
417
|
+
│ ├── host/links.js # reference parsing (pure; never touches ranking)
|
|
418
|
+
│ ├── host/context.js # context assembly: the three-tier Context Pack (pure, zero I/O)
|
|
419
|
+
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
276
420
|
│ └── client/client.js # dual-host registration + panel UI
|
|
277
|
-
└── test/ #
|
|
421
|
+
└── test/ # 395 tests
|
|
422
|
+
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
423
|
+
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
278
424
|
```
|
|
279
425
|
|
|
280
426
|
Details and trade-offs live in the source comments; see [CONTRIBUTING.md](CONTRIBUTING.md)
|