dsh-knit 0.13.1 → 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 +128 -0
- package/README.en.md +113 -11
- package/README.md +112 -15
- 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,134 @@
|
|
|
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
|
+
|
|
6
134
|
## [0.13.1] - 2026-09-23
|
|
7
135
|
|
|
8
136
|
**只改文档,插件行为一行没动。** 没有新功能、没有修 bug ——
|
package/README.en.md
CHANGED
|
@@ -131,17 +131,102 @@ All of it is string arithmetic — **no embeddings, no model calls**.
|
|
|
131
131
|
|
|
132
132
|
---
|
|
133
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
|
+
|
|
134
215
|
## Also for the agent: the `knit_docs` tool
|
|
135
216
|
|
|
136
217
|
The same ranking that you see in the panel is also exposed to the model.
|
|
137
218
|
|
|
138
219
|
Once installed, the agent's tool list gains `knit_docs`: it can ask *"which documents in this
|
|
139
|
-
project are most relevant to what we're discussing?"* and get back **
|
|
140
|
-
|
|
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.
|
|
141
225
|
|
|
142
226
|
**Why it helps**: to cite a document that already exists, an agent can only guess paths or glob
|
|
143
|
-
and `read` them one by one
|
|
144
|
-
|
|
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).
|
|
145
230
|
|
|
146
231
|
**Read-only, and it stores nothing**: it reads the files that are already in the project — this is
|
|
147
232
|
not "memory". The difference from memory plugins is that **theirs start empty** (the agent has to
|
|
@@ -212,6 +297,7 @@ feature request.
|
|
|
212
297
|
| One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
|
|
213
298
|
| Scans `.md` in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist`) | ✅ |
|
|
214
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 | ✅ |
|
|
215
301
|
| Click to preview inline, click again to collapse | ✅ |
|
|
216
302
|
| Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
|
|
217
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 | ✅ |
|
|
@@ -224,7 +310,7 @@ feature request.
|
|
|
224
310
|
| Filter box over title / summary / path | ✅ |
|
|
225
311
|
| **Click the workspace path** to open the project folder in your file manager | ✅ |
|
|
226
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) | ✅ |
|
|
227
|
-
| 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) | ✅ |
|
|
228
314
|
| Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
|
|
229
315
|
| Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
|
|
230
316
|
| Zero model calls, zero network egress | ✅ |
|
|
@@ -242,11 +328,17 @@ six columns at this width, cells about 112px. Videos show their first frame as a
|
|
|
242
328
|
glyph and a duration badge. These are the workspace's real image and SVG files; this particular
|
|
243
329
|
workspace happens to hold several screenshots and two icon files.*
|
|
244
330
|
|
|
245
|
-

|
|
246
332
|
|
|
247
333
|
*All: documents on top (max 4, with a "View all →" link when truncated) and images & video below
|
|
248
|
-
(**never truncated**, count only).
|
|
249
|
-
|
|
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.
|
|
250
342
|
|
|
251
343
|
---
|
|
252
344
|
|
|
@@ -288,6 +380,11 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
288
380
|
video `mp4/m4v/webm/mov/ogv`; images ≤ 12MB and video ≤ 256MB or they are not listed
|
|
289
381
|
- **Media matches relevance by filename only**: no visual/audio content is parsed — give
|
|
290
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
|
|
291
388
|
- **Right-sidebar state is memory-only**: a refresh or a new session collapses it again
|
|
292
389
|
|
|
293
390
|
---
|
|
@@ -298,7 +395,7 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
298
395
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
299
396
|
cd dsh-knit
|
|
300
397
|
|
|
301
|
-
npm test #
|
|
398
|
+
npm test # 395 tests, zero dependencies, no npm install needed
|
|
302
399
|
```
|
|
303
400
|
|
|
304
401
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -315,10 +412,15 @@ knit/
|
|
|
315
412
|
├── cordis.patch.yml # the insert line mounted into the plugin tree
|
|
316
413
|
├── assets/ # icon source (path inlined into client.js)
|
|
317
414
|
├── src/
|
|
318
|
-
│ ├── host/index.js # /knit/api/recent · /doc · /raw
|
|
415
|
+
│ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
|
|
319
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)
|
|
320
420
|
│ └── client/client.js # dual-host registration + panel UI
|
|
321
|
-
└── 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
|
|
322
424
|
```
|
|
323
425
|
|
|
324
426
|
Details and trade-offs live in the source comments; see [CONTRIBUTING.md](CONTRIBUTING.md)
|
package/README.md
CHANGED
|
@@ -156,11 +156,12 @@ dsh plugin --profile web add dsh-knit
|
|
|
156
156
|
| 能力 | |
|
|
157
157
|
|---|---|
|
|
158
158
|
| **按当前对话相关性排序**(BM25 + IDF,纯本地,零模型) | ✅ |
|
|
159
|
-
|
|
|
159
|
+
| **当前任务上下文**:把排序结果拆成 **主要 / 辅助 / 相关** 三层,每条都写明「为什么在这里」 | ✅ |
|
|
160
|
+
| **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
|
|
160
161
|
| 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
|
|
161
162
|
| 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
|
|
162
163
|
| 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
|
|
163
|
-
|
|
|
164
|
+
| 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径面包屑**重复,只保留后者 | ✅ |
|
|
164
165
|
| 单击就地展开预览,再点收起 | ✅ |
|
|
165
166
|
| 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
|
|
166
167
|
| **文档 / 图片与视频 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边 | ✅ |
|
|
@@ -173,10 +174,10 @@ dsh plugin --profile web add dsh-knit
|
|
|
173
174
|
| 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
|
|
174
175
|
| **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
|
|
175
176
|
| **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局) | ✅ |
|
|
176
|
-
| 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc`
|
|
177
|
+
| 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc` 收起;**媒体档** `←` `→` 按屏幕位置跨行,`Home` / `End` 到首尾(文档档永远单列,`←` `→` 没有空间含义) | ✅ |
|
|
177
178
|
| 每 5 秒自动刷新 + 手动刷新;2 分钟内改动过的文档打 🆕 | ✅ |
|
|
178
179
|
| 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
|
|
179
|
-
| 列表是标准 `listbox`/`option` 语义,选中项用 `aria-activedescendant`
|
|
180
|
+
| 列表是标准 `listbox`/`option` 语义,选中项用 `aria-activedescendant` 播报;媒体网格里的键盘焦点有可见描边 | ✅ |
|
|
180
181
|
| 零模型调用、零网络出口 | ✅ |
|
|
181
182
|
|
|
182
183
|
> 相关度**不做可视化**(不显示百分比、不画长条)—— 排序本身就是答案,名次即相关度。
|
|
@@ -189,10 +190,89 @@ dsh plugin --profile web add dsh-knit
|
|
|
189
190
|
*视频取首帧当海报,中央叠播放三角、右下角叠时长。列出的就是工作区里真实的图片与 SVG 文件 ——*
|
|
190
191
|
*这个工作区里正好有几张截图和两个图标,所以看起来像一屏文件缩略图。*
|
|
191
192
|
|
|
192
|
-

|
|
193
194
|
|
|
194
195
|
*全部:上区文档(最多 4 条,超出时右侧给「查看全部 →」)、下区图片与视频(**不截断**,只给计数)。*
|
|
195
|
-
|
|
196
|
+
标题 / 时间 / 摘要 / 路径**四个字段一个不少**。
|
|
197
|
+
⚠️ **这张图是 v0.13 时代的**:那时候文档还能排 2 列,列表行里也还有路径,标题与时间各占一行;
|
|
198
|
+
**v0.14 起文档列表永远单列**(每篇最左边独立一列是序号,与标题第一行垂直居中;右边第一行=
|
|
199
|
+
Primary 点 + 标题 + 相对时间,**时间靠右**;摘要再往下),
|
|
200
|
+
而且**路径不再出现在列表行里**(预览头的面包屑始终显示完整路径,重复的那份删掉了),
|
|
201
|
+
截图尚未重拍。
|
|
202
|
+
|
|
203
|
+
---
|
|
204
|
+
|
|
205
|
+
## 当前任务上下文(v0.14)
|
|
206
|
+
|
|
207
|
+
排序解决的是「哪几篇跟这段对话最像」。但你要的往往是另一个问题的答案:
|
|
208
|
+
|
|
209
|
+
> **现在这个任务,项目里哪些东西最值得先看?**
|
|
210
|
+
|
|
211
|
+
Context Pack 是对这个问题的回答,但它是**数据层的结构**(主要 / 辅助 / 相关三层 + 每条的确定性理由),
|
|
212
|
+
**不是一张要单独显示的卡片**。所以它直接落在文档列表里:相关模式下,文档档从一条平铺列表
|
|
213
|
+
变成**三层分组**,组名后面跟一句极短的说明。
|
|
214
|
+
|
|
215
|
+
```
|
|
216
|
+
┌─ 文档列表 ────────────────────────────┐
|
|
217
|
+
│ 主要上下文 先看 │
|
|
218
|
+
│ 01 ● 相关性排序算法 5分钟前 │
|
|
219
|
+
│ 标题命中:排序 │
|
|
220
|
+
│ │
|
|
221
|
+
│ 辅助上下文 辅助 │
|
|
222
|
+
│ 02 排序评测集 2小时前 │
|
|
223
|
+
│ 正文命中:关键词计数 │
|
|
224
|
+
│ │
|
|
225
|
+
│ 相关上下文 背景 │
|
|
226
|
+
│ 03 CHANGELOG.md 12天前 │
|
|
227
|
+
│ 正文命中:排序 │
|
|
228
|
+
└────────────────────────────────────────┘
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
> 示意图省掉了每行的摘要。**真实的行结构是:最左边独立一列=序号(与右边第一行**垂直居中**),
|
|
232
|
+
> 右边堆叠=第一行「Primary 点 + 标题 + 相对时间(**靠右**)」→ 摘要(**没有路径** ——
|
|
233
|
+
> 列表行里不显示它,路径在预览头的面包屑上)。而且这个列表**永远是单列**(面板拖到多宽都一样)。
|
|
234
|
+
|
|
235
|
+
**分组之间不画横线**:层级靠 16px 的空间、组名与字号建立,不靠分割线。
|
|
236
|
+
分组里没有分数、没有百分比、没有星级 —— 「为什么在这里」只写**确定性的事实**。
|
|
237
|
+
|
|
238
|
+
> **右侧那个「当前任务上下文」说明栏已经删掉了**(2026-09-29)。它说的和左侧三个分组是同一件事
|
|
239
|
+
> —— 当前任务就在列表上方那行弱化元信息里,「命中 N 篇」与头部总数重复,三条证据类型**就是**
|
|
240
|
+
> 三个组名;视觉价值有限,而且容易把 Knit 做成 AI Dashboard。随它一起删除的还有
|
|
241
|
+
> 「调宽 / 拖出浮动 / 右缘吸附」那一套(见 `CHANGELOG.md`)。
|
|
242
|
+
|
|
243
|
+
### 分层是确定性规则,不是 AI 判断
|
|
244
|
+
|
|
245
|
+
| 层 | 什么时候进 | 上限 |
|
|
246
|
+
|---|---|---|
|
|
247
|
+
| **主要上下文** | 命中,**且**有「落脚点」(话题词命中标题或摘要),**且**相关度不是背景噪音(≥ 最高分的 30%) | 1 |
|
|
248
|
+
| **辅助上下文** | 对某个「焦点词」有**深入命中**(该词不止一篇在讲,而且这一篇是把它讲得最多的那一篇);**或**与某个主要上下文有引用关系(「被引用」/「引用了」,两个方向分别标注) | 3 |
|
|
249
|
+
| **相关上下文** | 其余**有命中**的条目,以及零命中但有引用关系的邻居 | 5 |
|
|
250
|
+
|
|
251
|
+
上限是**上限,不是配额**:主要上下文允许为空(实测真实工作区上有相当比例的话题
|
|
252
|
+
确实没有一篇文档在正经讲它),相关上下文也允许为空。**说不出的理由就不出场** ——
|
|
253
|
+
零命中又没有任何引用关系的文档不是「与当前任务有关」,放它进来只能配一句
|
|
254
|
+
「可能对你有帮助」,那是这一版明确不要的东西。
|
|
255
|
+
|
|
256
|
+
**「为什么在这里」**永远是一句可核验的事实:
|
|
257
|
+
|
|
258
|
+
| 理由 | 说的是什么 |
|
|
259
|
+
|---|---|
|
|
260
|
+
| 标题 / 摘要 / 正文命中当前话题:`词` | 真的命中了,而且告诉你命中了哪个词 |
|
|
261
|
+
| 被主要上下文引用 | 主文档里那条路径指过来的 —— 读主文档时你下一步就会点它 |
|
|
262
|
+
| 引用了主要上下文 | 它里面提到了主文档 |
|
|
263
|
+
|
|
264
|
+
**没有**「AI 判断这篇重要」「可能对你有帮助」这类句子,也**没有**百分比、星级、置信度条 ——
|
|
265
|
+
理由要么是可核验的事实,要么干脆不写。
|
|
266
|
+
|
|
267
|
+
### 边界(说清楚,不夸大)
|
|
268
|
+
|
|
269
|
+
- **引用关系不等于「更相关」。** 实测过:把引用图当排序信号补不上词面错配那个缺口。
|
|
270
|
+
所以引用关系**只能**把一篇文档放进辅助 / 相关层,**永远不能**把它抬进主要上下文。
|
|
271
|
+
- **排序引擎本身没变。** 这一版加的是排序**之上**的一层投影 —— BM25 的打分、评测
|
|
272
|
+
(top-1 / MRR / 陷阱用例)一行没动。如果检索没把对的那篇找出来,分层也只能在
|
|
273
|
+
找到的那几篇里分 —— 它救不了召回。
|
|
274
|
+
- **不做任务理解。** Context Pack 里那个「当前任务」字段放的是**最近一条用户消息的原文**,
|
|
275
|
+
不是任何概括 —— Knit 不解一句话的意思,只是把它如实摆出来。真去概括需要模型,而 Knit 不调模型。
|
|
196
276
|
|
|
197
277
|
---
|
|
198
278
|
|
|
@@ -201,19 +281,24 @@ dsh plugin --profile web add dsh-knit
|
|
|
201
281
|
同一份排序,除了给你看,也开了一个口子给模型。
|
|
202
282
|
|
|
203
283
|
装好之后,agent 的工具列表里会多一个 `knit_docs`:它可以问
|
|
204
|
-
|
|
205
|
-
|
|
284
|
+
「这个项目里跟当前话题最相关的文档是哪几篇」,拿回**同一个 Context Pack** ——
|
|
285
|
+
`primary` / `supporting` / `related` 三层,每项带路径 + 标题 + 摘要 +
|
|
286
|
+
**结构化理由**(`direct` / `summaryMatch` / `bodyMatch` / `linkTarget` / `linkSource` / `related`)
|
|
287
|
+
+ **项目角色**(`impl` / `test` / `config` / `design` / `doc`)+
|
|
288
|
+
命中的那一小段原文,再用它自己的 `read` 打开其中一篇。
|
|
206
289
|
|
|
207
290
|
**为什么有用**:agent 想引用项目里已有的文档时,只能靠猜路径、或者把 `glob`
|
|
208
|
-
出来的路径一个个 `read`
|
|
209
|
-
|
|
291
|
+
出来的路径一个个 `read` 试过去。这份排序 Knit **每一轮已经算好了**,这个工具只是把它交出去 ——
|
|
292
|
+
省掉的是**「先猜哪几篇相关」这一步判断**(实测:拿到包的 agent 不再需要 `glob` 去凑候选)。
|
|
210
293
|
|
|
211
294
|
**只读,且不存储任何东西**:它读的是项目里**现成的文件**,不是「记忆」。
|
|
212
295
|
和记忆类插件的区别是:**它们起点是空的**(agent 得先记过才有东西可召回),
|
|
213
296
|
Knit 一装上就有整个项目的历史文档可用。
|
|
214
297
|
|
|
215
|
-
|
|
298
|
+
四个细节:
|
|
216
299
|
|
|
300
|
+
- **给的是任务上下文,不是一条平铺列表**。面板与工具**共用同一个 Context Model** ——
|
|
301
|
+
没有两套排序逻辑,也没有两份规则。
|
|
217
302
|
- **不返回相关度分数**。它是**相对**分数(永远有一篇 100%,每次刷新可能换人当),
|
|
218
303
|
给模型看会被当成绝对置信度去推理。**顺序即相关度** —— 与面板同一条规矩。
|
|
219
304
|
- **不返回正文**。agent 有自己的 `read` 工具;Knit 负责**发现**,不负责**搬运**。
|
|
@@ -258,6 +343,15 @@ Knit 一装上就有整个项目的历史文档可用。
|
|
|
258
343
|
- **媒体只认常见格式与大小**:图片 `png/jpg/jpeg/gif/webp/avif/bmp/ico/svg`、
|
|
259
344
|
视频 `mp4/m4v/webm/mov/ogv`;图片 ≤ 12MB、视频 ≤ 256MB,超出不列出
|
|
260
345
|
- **媒体只按文件名参与相关性匹配**:不解析画面 / 语音内容,截图与录屏建议用可检索的文件名
|
|
346
|
+
- **分层建立在召回之上**:如果 BM25 一篇都没把对的那篇捞进候选池,分层也只能在捞到的那几篇里分
|
|
347
|
+
—— 它救不了召回。词面错配(你问「图片和视频」,文档里写的是「媒体浏览」)就是这种情形
|
|
348
|
+
- **「当前任务上下文」只覆盖 Markdown**:面板的图片与视频两档、以及时间序模式都不分层
|
|
349
|
+
(那两档没有话题命中,就没有可解释的理由)。第一版也不解析 PDF / DOCX / 源码
|
|
350
|
+
- **引用关系只当上下文信号**:它能把文档放进辅助 / 相关层,**不会**把任何文档抬进主要上下文
|
|
351
|
+
- **测到的是「定位」,不是「省力」**:真机对照实验(冻结协议,四道题)里,能调 `knit_docs`
|
|
352
|
+
的 agent 总探索次数**没有下降** —— Control 4.75 → Treatment 6.0,四题逐题无一变少。
|
|
353
|
+
包确实替掉了「先 `glob` 找候选」那一步,但省下的被**翻倍的 `read`** 吃了回去:
|
|
354
|
+
它把注意力指向了正确的文件,**不等于** agent 少读几次文件
|
|
261
355
|
- **右侧栏状态是 memory-only**:刷新或新会话会回到收起状态
|
|
262
356
|
|
|
263
357
|
---
|
|
@@ -268,7 +362,7 @@ Knit 一装上就有整个项目的历史文档可用。
|
|
|
268
362
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
269
363
|
cd dsh-knit
|
|
270
364
|
|
|
271
|
-
npm test #
|
|
365
|
+
npm test # 395 项,零依赖,不需要先 npm install
|
|
272
366
|
```
|
|
273
367
|
|
|
274
368
|
**改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
|
|
@@ -285,12 +379,15 @@ knit/
|
|
|
285
379
|
├── cordis.patch.yml # 挂进 plugin tree 的 insert 行
|
|
286
380
|
├── assets/ # 图标源文件(path 已内联进 client.js)
|
|
287
381
|
├── src/
|
|
288
|
-
│ ├── host/index.js # /knit/api/recent · /doc · /raw
|
|
382
|
+
│ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
|
|
289
383
|
│ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
|
|
384
|
+
│ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
|
|
385
|
+
│ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
|
|
290
386
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
291
387
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
292
|
-
└── test/ #
|
|
293
|
-
|
|
388
|
+
└── test/ # 395 项测试
|
|
389
|
+
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
|
|
390
|
+
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
294
391
|
```
|
|
295
392
|
|
|
296
393
|
细节和取舍写在源码注释里;贡献流程见 [CONTRIBUTING.md](CONTRIBUTING.md),
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.0",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "Find the doc your agent just wrote. Lists the DSH workspace's Markdown, images and video in the sidebar, ranked by relevance to the current conversation, with inline preview — and hands the same ranking to the agent as a tool, returning the passage that matched in each document. Zero model calls, zero network.",
|
|
6
6
|
"main": "./src/host/index.js",
|
|
@@ -14,6 +14,7 @@
|
|
|
14
14
|
"assets",
|
|
15
15
|
"src",
|
|
16
16
|
"test",
|
|
17
|
+
"tools/json-schema-subset.mjs",
|
|
17
18
|
"cordis.patch.yml",
|
|
18
19
|
"CHANGELOG.md",
|
|
19
20
|
"README.md",
|
|
@@ -21,7 +22,7 @@
|
|
|
21
22
|
"LICENSE"
|
|
22
23
|
],
|
|
23
24
|
"scripts": {
|
|
24
|
-
"test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/security.test.mjs"
|
|
25
|
+
"test": "node --test test/host.test.mjs test/host-http.test.mjs test/client.test.mjs test/tier1.test.mjs test/entry.test.mjs test/i18n.test.mjs test/icon.test.mjs test/path.test.mjs test/peek.test.mjs test/eval.test.mjs test/tool.test.mjs test/label.test.mjs test/links.test.mjs test/security.test.mjs test/context.test.mjs test/context-eval.test.mjs"
|
|
25
26
|
},
|
|
26
27
|
"dsh": {
|
|
27
28
|
"bundle": {
|
|
@@ -47,6 +48,8 @@
|
|
|
47
48
|
"right-sidebar",
|
|
48
49
|
"recent-files",
|
|
49
50
|
"relevance",
|
|
51
|
+
"context-pack",
|
|
52
|
+
"task-context",
|
|
50
53
|
"knowledge-base",
|
|
51
54
|
"images",
|
|
52
55
|
"video",
|