dsh-knit 0.13.1 → 0.15.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 +180 -0
- package/README.en.md +166 -20
- package/README.md +155 -22
- package/package.json +6 -2
- package/src/client/client.js +590 -199
- package/src/host/context.js +568 -0
- package/src/host/feedback.js +641 -0
- package/src/host/index.js +452 -20
- package/src/host/relevance.js +44 -6
- package/src/host/tool.js +335 -58
- package/test/client.test.mjs +587 -92
- package/test/context/fixture.mjs +553 -0
- package/test/context-delta.test.mjs +309 -0
- package/test/context-eval.test.mjs +576 -0
- package/test/context-feedback-eval.test.mjs +189 -0
- package/test/context.test.mjs +542 -0
- package/test/feedback.test.mjs +247 -0
- package/test/harness.mjs +33 -7
- package/test/host-http.test.mjs +264 -2
- package/test/host.test.mjs +105 -0
- package/test/i18n.test.mjs +49 -5
- package/test/tool.test.mjs +455 -98
- package/tools/context-feedback-eval.mjs +330 -0
- package/tools/json-schema-subset.mjs +89 -0
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,186 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.15.0] - 2026-09-30
|
|
7
|
+
|
|
8
|
+
**从「构建一份当前任务上下文」再往前一步:让上下文能回答「它到底有没有被用上」。**
|
|
9
|
+
排序(BM25)一行没改,Context Pack 的装配规则一行没改,**没有模型、没有联网、没有长期记忆** ——
|
|
10
|
+
这一版加的是**一层可核验的使用反馈**:把 agent 真实读过哪些文件(会话日志里的
|
|
11
|
+
`tool/call(name="read")` 与按 `callId` 配对的 `tool/result`)跟「**读发生那一刻**生效的那份
|
|
12
|
+
Context Pack」对起来,得到五个计数:**Primary follow-through / First read tier /
|
|
13
|
+
Supporting coverage / Outside-context / Delta churn**。**只报事实**:没有分数、没有百分比、
|
|
14
|
+
没有评分条、没有置信度。
|
|
15
|
+
|
|
16
|
+
⚠️ **两条硬边界(别越)**:
|
|
17
|
+
|
|
18
|
+
1. **默认关。** 只有人显式打开(面板头部「使用情况」开关 → 请求带 `usage=1`,或
|
|
19
|
+
`knit_docs` 传 `audit:true`)才开始记账;没打开时**不读一个事件、不攒一条数据**。
|
|
20
|
+
理由是这笔账有代价(每次轮询都要读一遍会话事件),不该由 Knit 替用户决定。
|
|
21
|
+
2. **不重复 DSH Trajectory。** 证据的**唯一来源**是会话里**已经存在**的 `tool/call` /
|
|
22
|
+
`tool/result` 事件(`session.snapshotEvents()`,沿用既有拉取式架构,用 `seq` 做幂等游标)——
|
|
23
|
+
**没有新的事件总线、没有 Runtime Trace、没有 Event Store**;数据只在内核内存里,
|
|
24
|
+
重启即失(不落盘、不进 `localStorage`)。
|
|
25
|
+
|
|
26
|
+
### 加了什么
|
|
27
|
+
|
|
28
|
+
| 新增 | 说明 |
|
|
29
|
+
|---|---|
|
|
30
|
+
| **`src/host/feedback.js`** | Context Snapshot / Context Delta / Usage matching。纯逻辑、只 import `node:path`。`snapshotOf()` 把一份包压成 `{seq, at, topic, task, total, items:[{rel,tier,rank}], sig}`;`diffContext()` 给「进 / 出 / 换层」;`normalizeReadEvidence()` 把真实事件流化成「哪一刻读了哪篇」(⚠️ `tool/call` 的 `arguments` 是 JSON **字符串**,必须 `JSON.parse`;`message.isError === true` 的读**不记账**;工作区根之外的路径丢掉);`ingestEvents()` / `noteSnapshot()` / `usageFor()`。会话与读都有上限(`MAX_SESSIONS 24` / `MAX_READS_PER_SESSION 200` / `MAX_SNAPSHOTS_PER_SESSION 2` / `MAX_DELTAS_PER_SESSION 20` / `MAX_PENDING_CALLS 64`),满员按 **LRU** 淘汰最久没碰的会话 |
|
|
31
|
+
| **读落在哪一层,看的是「读发生那一刻」的包** | 每篇读按 `firstReadSeq` 找 `seq ≤` 它的**最新一份快照**。少了这一步,一次话题切换会把之前所有读重新贴上「包外」的标签,指标全是噪声 |
|
|
32
|
+
| **`/knit/api/recent?usage=1`** | 开闸信号:**第一次带它就等于对本次会话说「开始记账」**,此后不带参数也回传 `usage`。`/api/context` 只推进快照、**从不激活**。顺序是契约:`usage` 先算(它报告的是**上一份**包),快照后记 |
|
|
33
|
+
| **`knit_docs` 的 `audit` 参数(默认 `false`)** | `audit:true` 时在工具结果末尾追加一行 `Usage since the last pack: …`(报告**上一份**包),并把这次装配记进快照。不传 `audit` 的一次普通调用**一个记账方法都不碰**(有测试钉住) |
|
|
34
|
+
| **面板头部的「使用情况」开关(默认关)** | 打开后列表上方多一行弱化文字:`先看的「x.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次`。**没有分数 / 百分比 / 进度条 / 品牌色**,风格与「相关性排序」那行同档 |
|
|
35
|
+
| **`tools/context-feedback-eval.mjs`** | 拿真实会话日志(`~/.dsh/sessions/<工作区>/<会话>/session.v4.jsonl.zstd`)**离线回放**;`--control` 时一份包都不交,做对照组。把「包外」拆成 **`missed`**(Knit 索引里有、却没进包 —— 真漏)与 **`outOfScope`**(压根不在索引里,例如 `.js`):不拆开的话 `outside` 恒高,读起来像「Context Pack 没用」,其实是**量错了东西** |
|
|
36
|
+
| **`test/feedback.test.mjs` · `test/context-delta.test.mjs` · `test/context-feedback-eval.test.mjs`** | 17 + 16 + 7 条:路径归一化的八种输入 / 配对与游标幂等 / 上限与降级不抛 / Delta 四类 / 审计开关 / **Control(不交包 ⇒ 读全在包外)vs Treatment(交包 ⇒ `firstReadTier === 'primary'`)的确定性对照** / 坏行不废整批 |
|
|
37
|
+
|
|
38
|
+
### 真机读数(本机 `08_Knit`,会话 `session-09a33302`,**只量事实、不下结论**)
|
|
39
|
+
|
|
40
|
+
- **Treatment**(交包):**392** 份包 · Primary follow-through **YES** · Supporting coverage **1.00** ·
|
|
41
|
+
包外 **25/32 篇(共 392 次)**,其中 Knit 看得到的 11 篇里漏了 **35** 次、真心漏的只有 4 篇
|
|
42
|
+
(`knit/CHANGELOG.md` · `knit/README.md` · `03_发布/验收-v0.14-重启后待执行.md` · `README.md`)·
|
|
43
|
+
Delta churn:**换过 66 次 / 进 177 / 出 177 / 换层 271 / 任务变了 14**。
|
|
44
|
+
- **Control**(`--control`,不交包):**0** 份包 · 包外 **32/32** · `missed` 11 篇(140 次)· churn 0 ·
|
|
45
|
+
自检退出码 0(**量尺没坏**)。
|
|
46
|
+
- ⇒ 可复述的只有一句:**agent 读的东西绝大多数是代码文件** —— 32 篇里 21 篇根本不在 Knit 的索引内
|
|
47
|
+
(`.js` / `.json`)。这是**量尺的读数**,不能读成「Context Pack 没用」,也不能读成「有用」。
|
|
48
|
+
|
|
49
|
+
**测试:`395 → 447 → 450`**(+33 `feedback`/`context-delta`、+7 `context-feedback-eval`、
|
|
50
|
+
+7 `tool` 的 audit 通道、+5 `host-http` 的真实回环 HTTP、+3 `client` 的「使用情况」;
|
|
51
|
+
`i18n` 与 `client` 里几条旧断言随「头部多了一个按钮」同步)。`test/context-feedback-eval.test.mjs`
|
|
52
|
+
与另两个新文件都**手写进了 `package.json` 的 `scripts.test`**(测试文件现共 19 个)。
|
|
53
|
+
|
|
54
|
+
⚠️ 这一版**宿主侧**(`src/host/*`)改了,要**重启 DSH** 才生效(`curl -s
|
|
55
|
+
"http://127.0.0.1:3080/knit/api/raw?rel=nope.png"`:空 body 的 404 = 旧代码;
|
|
56
|
+
`{"ok":false,"code":"knit/not-found"}` = 新代码在跑);前端那个开关只需 `Cmd + Shift + R`。
|
|
57
|
+
|
|
58
|
+
## [0.14.0] - 2026-09-29
|
|
59
|
+
|
|
60
|
+
**从「按当前对话给文档排序」升级成「按对话构建当前任务最需要的项目上下文」。**
|
|
61
|
+
排序引擎(BM25)一行没改,工具没有重写 —— 这一版加的是**排序之上的一层**;
|
|
62
|
+
面板只在相关模式下从一条平铺列表改成**三层分组**(单栏),没有重做 ——
|
|
63
|
+
当天稍后又按真机体验改了**四处形态**:右栏从「固定 310px」改成可以拖宽、可以拖出去浮动、
|
|
64
|
+
拖回右缘重新停靠;文档列表从「最多 2 列」改成**永远单列**,每篇的第一行改成
|
|
65
|
+
「序号 + Primary 点 + 相对时间」的元信息行、标题独占下一行;**列表行里的路径删掉了**
|
|
66
|
+
(它和预览头的面包屑重复 —— 用户原话「点开查看文档详情的时候已经有了」);**序号
|
|
67
|
+
从元信息行里搬了出来,成了每行最左边独立的一列**;最后**时间也回到标题那一行、靠右**,
|
|
68
|
+
序号与标题第一行**垂直居中**(见下)。
|
|
69
|
+
|
|
70
|
+
⚠️ **当天最后一条裁定(2026-09-29):右侧那个「当前任务上下文」说明栏被删除了。**
|
|
71
|
+
用户把 v0.14 的 UI 重新定了一条线 —— **Context Pack 是数据层的结构,不是一个要单独显示出来的
|
|
72
|
+
UI 卡片**;它直接落在文档列表的分组里(主要 / 辅助 / 相关,组名后跟一句极短说明)。理由是三重的:
|
|
73
|
+
右栏与左侧分组**信息重复**(当前任务=列表上方那行弱化元信息、「命中 N 篇」=头部总数、
|
|
74
|
+
三条证据类型=三个组名)、「视觉价值有限」、「容易把 Knit 做成 AI Dashboard」,也不符合 Knit
|
|
75
|
+
「安静、开发者工具、高信息密度、可信」的方向。随右栏一起删除的还有它那套
|
|
76
|
+
**调宽 / 拖出浮动 / 右缘吸附**与把手 —— 真正只有它用得上的代码,一起删干净。
|
|
77
|
+
同一条裁定还带来四处收窄:排序依据那行**不再出现关键词**(退到 `title` 属性里当低层 metadata,
|
|
78
|
+
可见文本只有「相关性排序」)、组与组之间**不再画横线**(只留 16px 空间)、`why` 文案从
|
|
79
|
+
「直接命中当前话题:a、b」缩成「直接命中:a · b」、文档标题从 12.5px 提到 **14px**
|
|
80
|
+
(序号的 `line-height` 同步成 19.6px = 14 × 1.4,这是两者垂直居中的唯一手段)。
|
|
81
|
+
|
|
82
|
+
### 加了什么
|
|
83
|
+
|
|
84
|
+
| 新增 | 说明 |
|
|
85
|
+
|---|---|
|
|
86
|
+
| **Context Pack(当前任务上下文)** | 把一次检索结果拆成 **主要上下文 / 辅助上下文 / 相关上下文** 三层,不再只有一条平铺的列表 |
|
|
87
|
+
| **每条都带「为什么在这里」** | 理由来自确定性事实:命中在标题 / 摘要 / 正文(附命中的词)、被主要上下文引用、引用了主要上下文。**不是**「AI 判断这篇重要」 |
|
|
88
|
+
| **面板的「当前任务上下文」视图** | 相关模式下文档档改成**三层分组**(主要 / 辅助 / 相关,组名后跟一句极短说明),列表本身仍是那份可搜索 / 可预览 / 可键盘导航的文档列表,**永远单栏**。⚠️ 它**先被做成双栏**(左列表 + 右说明栏),当天就被用户删掉 —— 见本节开头那条裁定 |
|
|
89
|
+
| ~~**右栏可拖宽 / 可拖出浮动**(当天追加、当天又删)~~ | 固定 310px 在 1000–1300px 这一段会把左栏挤到只剩一列,所以右栏一度改成:拖左侧把手调宽(260–420px,键盘 ←/→ 也能调)、拖面板头部拖出去变成浮窗、拖回右缘 28px 内松手重新停靠,头部还有「浮动 / 停靠」按钮。**面板本身被删除后,这套几何交互(把手 / 拖拽 / 吸附 / 宽度变量 / 三个纯函数)一起删干净了** —— 留着一套永远调用不到的代码,下一个人只会以为它还在生效 |
|
|
90
|
+
| **文档列表永远单列**(当天追加) | 用户原话:「文档列表最多一个就行,现在一行两个有点太多了」。**多列那套是整体删除,不是关掉**:`docLayoutFor` / `DOC_TRACK_PX` / `DOC_GRID_MAX_COLS` / `DOC_SUMMARY_MIN_PX` / `.knit-multicol*` 全部不存在(测试反过来守「它真的没了」)。**行一改成元信息行**:序号 + Primary 点 + 相对时间同一行,**标题独占下一行**,摘要再往下(这一行的形态当天又改了两次:序号先搬成最左边独立一列,随后时间也回到标题那一行 —— 见下面两行)|
|
|
91
|
+
| **列表行里不再有路径**(当天追加) | 用户原话:「文档列表中的文档路径,我觉得不需要出现了,因为点开查看文档详情的时候已经有了,所以这里是重复的,隐藏掉」。删掉的是 `.knit-meta` 这个节点本身(**不是 `display:none`**)—— 预览头那条**可点的路径面包屑**(`.knit-preview-path`:目录浅 + 文件名亮)始终显示完整路径。⚠️ 这**不是**「多列砍字段」那条教训的复发:那条守的是「不许因为排版窄就静默少给信息」,而路径是**重复信息**;**摘要仍然任何情况下都不许 `display:none`**。行的定位不走可见路径,`data-knit-rel` 仍在 |
|
|
92
|
+
| **序号独立成最左边一列**(当天追加) | 用户原话:「文档列表序号放在独立最左边,其他数据放在右边」(附了一张示意图)。列表行改成**两列 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`)与标题第一行**垂直居中** —— ⚠️ 改标题字号或行高时必须同步改它,否则序号会与标题错开 |
|
|
93
|
+
| **行的静止态不再有底色**(当天追加) | 用户原话:「深色模式下,文档列表没有选中,鼠标没有悬停,不需要有背景。或者是说,跟深色模式的最底下的背景一样」。`.knit-doc` 的静止态从 `bg-layer-1` 改成 **`transparent`**(露出面板 / 宿主侧边栏的底色)—— 浅色主题下这两个令牌都是 `#fff`(看不出差别),**暗色主题下 `bg-layer-1` 比底色亮一档**,于是每一行都像一张浮起来的小卡片,哪怕没选中、没悬停。hover 与 `.active` 各有自己的令牌,**不动**(都改成 transparent 的话,一屏灰里就认不出选中态了) |
|
|
94
|
+
| **`knit_docs` 返回分层上下文** | 模型拿到的从「Top N」变成 `Primary / Supporting / Related`,每项带 `source`(实现 / 测试 / 配置 / 设计 / 文档)与结构化 `reason` |
|
|
95
|
+
| **`/knit/api/context`** | 独立的上下文接口。`/api/recent` 里也顺带给一个可选的 `context` 字段(老客户端忽略它) |
|
|
96
|
+
| **`src/host/context.js`** | 上下文装配层。纯函数、零 I/O,只吃 `rankByRelevance()` 的名次与 `links.js` 的引用图 |
|
|
97
|
+
| **`test/context.test.mjs`** | 规则本身的单元测试(SDD 要的八组:Primary / 无相关 / Supporting / Related / 去重 / 确定性 / 理由 / 上限)。**手写输入、不调 `rankByRelevance()`** |
|
|
98
|
+
| **`test/context-eval.test.mjs` + `test/context/fixture.mjs`** | 24 篇语料 / 12 条真实任务型用例的**离线 Context Pack 评测**(与 BM25 评测**分开**,互不覆盖),末尾按 SDD §27 报 **Primary@1 / Supporting Recall / Role Precision** 三个具名指标 |
|
|
99
|
+
| **`tools/json-schema-subset.mjs`** | 测试与真机探针**共用**的一份 JSON Schema 子集校验器。不引 ajv —— 本包零依赖,引工作区外那份会让 `npm test` 依赖一个绝对路径 |
|
|
100
|
+
| **`tools/replay-cases.mjs`** | **在进程内重放**评审文档 §10 那 5 个真实案例(`import` 源码跑 `execute()`,**不需要重启宿主、也不看运行中的进程**),并打印「平铺 top6 / 前两层 / 提上来 / 降下去 / 零命中靠引用」。加了 `--full` 就打印 agent 真正收到的那段文本 |
|
|
101
|
+
|
|
102
|
+
测试:**285 → 402 → 403 → 395**(`cd knit && npm test`)。402 那次的最后 7 条是右栏拖宽 / 浮动 / 吸附;
|
|
103
|
+
403 是「列表永远单列 + 行一不含标题」两条守卫替换掉一条多列测试后的净增一条;
|
|
104
|
+
**最后降到 395 是删掉右栏的直接结果** —— 12 条双栏 / 右栏用例整条删掉,只补了 4 条单栏守卫
|
|
105
|
+
(「即使宿主给了 Context Pack,DOM 里也没有任何右栏骨架」「源码里不再有任何右栏 CSS 规则 / 函数 / 常量」
|
|
106
|
+
「组与组之间只靠 16px 空间(不再画横线)」「关键词退到 title」)。
|
|
107
|
+
|
|
108
|
+
> ⚠️ **评审文档 §10 那 5 个案例的旧输出已经作废。** 它们是**上限 3 / 5 / 12 那一版**的快照,
|
|
109
|
+
> 上限收敛到 1 / 3 / 5 之后「辅助 5 / 相关 12」不再可复现 —— 用 `node tools/replay-cases.mjs`
|
|
110
|
+
> 全部重跑过了,旧数字一个没留。重跑后最值得记的两条:**案例 3 从「没有主文档」变成
|
|
111
|
+
> 主文档就是那篇 SDD(本节唯一一条 `direct`)**;而**案例 1 的 Primary 是错的** ——
|
|
112
|
+
> 一篇 UI 设计文档靠摘要里「审美**关键词**」蹭进了主要上下文。
|
|
113
|
+
> ⇒ **「有落脚点」只保证话题词出现在标题或摘要里,不保证那篇讲的是这件事。**
|
|
114
|
+
|
|
115
|
+
### 分层规则(确定性,可逐条解释)
|
|
116
|
+
|
|
117
|
+
| 层 | 判据 | 上限 |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| 主要上下文 | 命中,**且**有「落脚点」(话题词命中标题或摘要),**且**相关度 ≥ 最高分的 30% | 1 |
|
|
120
|
+
| 辅助上下文 | 对某个「焦点词」有**深入命中**(该词不止一篇在讲,且这一篇是把它讲得最多的那一篇);**或**与某个主要上下文有引用关系 | 3 |
|
|
121
|
+
| 相关上下文 | 其余**有命中**的条目,以及零命中但有引用关系的邻居 | 5 |
|
|
122
|
+
|
|
123
|
+
上限是**上限,不是配额**:主要上下文允许为空,相关上下文也允许为空。
|
|
124
|
+
「说不出凭什么」的条目**不出场** —— 零命中又没有任何引用关系的文档不是「与当前任务有关」,
|
|
125
|
+
放它进来只能给它一句「与当前工作区相关」,那正是需求禁止的「可能对你有帮助」。
|
|
126
|
+
|
|
127
|
+
三条都是**实测调出来的**,踩过的三个坑写在 `src/host/context.js` 的文件头:
|
|
128
|
+
|
|
129
|
+
1. 只要求「命中 ≥2 个话题词」时,满篇话题词的 `CHANGELOG` 与「什么话题都提一句」的长归档霸占主要上下文;
|
|
130
|
+
2. 只看「话题词命中标题/摘要」时,摘要里正好出现话题词的文档也会被抬进主要上下文;
|
|
131
|
+
3. 只看「正文里出现过」时,每个话题词各提一句的长归档会进**每一条**任务的辅助上下文。
|
|
132
|
+
|
|
133
|
+
### 顺带修掉的四个真实缺陷
|
|
134
|
+
|
|
135
|
+
- **`knit_docs` 在 v0.14 上是坏的 —— 每次调用都在校验层失败**(最严重的一条)。
|
|
136
|
+
工具的输出 schema 是封闭的(`additionalProperties: false`),而三层条目实际带了三个
|
|
137
|
+
没被声明的字段(`kind`、`reason.term`、`totals`),`mtimeMs` 还是浮点
|
|
138
|
+
(`fs.Stats.mtimeMs` 本来就是浮点,schema 写的是 `integer`;时间序那条分支一直是取整的,
|
|
139
|
+
两边不一致)。结果是 agent 侧**一个 Context Pack 都拿不到**,而 335 条测试全绿 ——
|
|
140
|
+
因为所有 tool 测试都是拿手写的假 payload 测渲染,**从来没有把 `execute()` 的真实返回值
|
|
141
|
+
交给它自己的 schema 校验过**。是在做「Control vs Treatment」真机对照实验时暴露的:
|
|
142
|
+
4 个 Treatment 会话 100% 报
|
|
143
|
+
`tool "knit_docs" returned invalid output: "value.primary[0].mtimeMs" must be an integer; …`。
|
|
144
|
+
现在 schema 补齐、`mtimeMs` 在投影层取整,并新增两条测试:一条把真实 `execute()` 的返回值
|
|
145
|
+
(relevance 与 time 两种模式)喂给它自己的 schema,一条反向确认那个校验器真的抓得住
|
|
146
|
+
「漏声明字段」和「该整数给了浮点」。
|
|
147
|
+
- **`knit_docs` 的头部会写「0 matching documents」而下面列着结果**:返回的三层结果漏了 `totals.matched`,
|
|
148
|
+
渲染层回落成 0。测试当时是全绿的 —— 现在有两条回归用例钉住它。
|
|
149
|
+
- **`rankByRelevance` 的并列兜底键依赖输入排列**:`raw` 与 `mtimeMs` 都相同时按「输入下标」定序,
|
|
150
|
+
换个扫描顺序就会换序。改成按 `rel` 定序 —— 这是「相同输入必须产出完全相同顺序」那条承诺的前提。
|
|
151
|
+
- **工具在「工作区有文档、但一个词都没命中」时说了假话**:三层全空时它返回
|
|
152
|
+
`No Markdown documents found in the workspace.` —— 而工作区里明明有 49 篇。
|
|
153
|
+
代码注释里其实已经写明「`total` 是正数而三层全空」是另一种情形,**只有输出字符串没跟着分开**。
|
|
154
|
+
现在分开了,并且把限制和下一步一起说出来:
|
|
155
|
+
`No document matched the current topic — 0 of 49 Markdown documents contain the query terms.` /
|
|
156
|
+
`Matches come from the first 2500 characters of each file; use grep for anything deeper.`
|
|
157
|
+
真机触发场景:问「路径越界怎么防」,49 篇一篇都没命中 —— 因为文档侧只看每篇**前 2500 字**
|
|
158
|
+
(`index.js` 的 `HAYSTACK_CHARS`),而这个词在 5 篇 `.md` 里**全部**出现在 2500 字之后
|
|
159
|
+
(`knit/CHANGELOG.md` @29033、`knit/README.md` @9099、`03_发布/发布文档规划.md` @5200、
|
|
160
|
+
`01_ Knit PRD/Knit_SDD-v0.7-agent文档工具.md` @7342、`01_ Knit PRD/Knit_评审-v0.14-ContextPack.md` @7808)。
|
|
161
|
+
⚠️ **没有动那个 2500 字的窗口** —— 改它等于改检索行为,会推翻 `test/eval/` 里那套冻结的
|
|
162
|
+
v0.5.2 基线。所以这一版只是**不再说假话**,窗口本身留给下一版单独决策。
|
|
163
|
+
|
|
164
|
+
### 没有做的事(刻意)
|
|
165
|
+
|
|
166
|
+
- **不改 BM25**:`relevance.js` 的打分逻辑一行没动,`test/eval.test.mjs` 的 top-1 / MRR / 陷阱
|
|
167
|
+
四条断言原样保留、原样通过。新增的只是「把第 1 趟已经算过的命中词留下来」。
|
|
168
|
+
- **不引入 embedding / 模型 / 网络 / 数据库 / 长期记忆**。Context Pack 是一层**纯投影**。
|
|
169
|
+
- **不做任务理解**:`task` 字段装的是**最近一条用户消息的原文**,不是任何概括 ——
|
|
170
|
+
Knit 不解一句话的意思,只是把它如实摆出来给人看。工具返回值里**不带** `task`
|
|
171
|
+
(模型看到的是渲染后的文本,头部已经用话题标签说了「这次按什么排的」)。
|
|
172
|
+
- **不新增第二套打分**:没有 `contextScore`,界面上也没有百分比、星级、置信度条。
|
|
173
|
+
Eval 报的 `Primary@1 / Supporting Recall / Role Precision` 是**集合关系**,
|
|
174
|
+
不是分数门槛(没有「必须 > 80%」这种断言)。
|
|
175
|
+
- **不重扫工作区**:`collect → relevance → links → context assembly` 复用同一批结果,
|
|
176
|
+
引用图复用 `collectDocs` 已经读进内存的正文首部,零额外 I/O。
|
|
177
|
+
- **不声称「让 agent 少读几篇」—— 这一版实测是反的。** 重启后用冻结协议跑了
|
|
178
|
+
Control vs Treatment 各 4 次(同 4 条任务、同一个 50 篇工作区):Treatment 的工具调用
|
|
179
|
+
均值 **6.0** vs Control **4.75**,逐题 **6 vs 5 · 5 vs 5 · 9 vs 5 · 4 vs 4**,**没有一题变少**
|
|
180
|
+
(算上那次 `knit_docs` 调用则是 7.0 vs 4.75)。唯一被消掉的是 `glob`,代价是
|
|
181
|
+
`read` 从 1.75 涨到 3.75、`distinct files read` 从 1.5 涨到 2.75;四条答案**全部正确**,
|
|
182
|
+
所以不是「省了调用但答错」,是单纯没省。**它给出的价值是「定位 + 解释」**
|
|
183
|
+
(该看哪几篇、为什么、有没有主文档),**不是省力**。完整数据见
|
|
184
|
+
`01_ Knit PRD/Knit_评审-v0.14-ContextPack.md` 附三。
|
|
185
|
+
|
|
6
186
|
## [0.13.1] - 2026-09-23
|
|
7
187
|
|
|
8
188
|
**只改文档,插件行为一行没动。** 没有新功能、没有修 bug ——
|
package/README.en.md
CHANGED
|
@@ -7,18 +7,22 @@
|
|
|
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 51 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
|
+
*Since v0.14 the list is always one column: the rank number sits in its own column on the far left
|
|
17
|
+
(vertically centred on the title's first line), then Primary dot + title + relative time (time on the
|
|
18
|
+
right), then the summary. **The path lives in the preview header's breadcrumb only** — rows no longer repeat it.*
|
|
16
19
|
|
|
17
20
|

|
|
18
21
|
|
|
19
|
-
*Order follows the conversation — same workspace,
|
|
20
|
-
|
|
21
|
-
|
|
22
|
+
*Order follows the conversation — same workspace, in a freshly opened session: before you have said
|
|
23
|
+
anything, the top line says so ("not enough conversation yet — sorted by time") and the list runs
|
|
24
|
+
newest-first; ask "how is BM25 weighted for the ranking?" and the ranking docs take over, with the
|
|
25
|
+
rank numbers and the primary / supporting / related tiers appearing alongside them.*
|
|
22
26
|
*⚠️ The panel polls **every 5 seconds**, so the re-rank lands **0–5 s** after the message rather than
|
|
23
27
|
instantly, and the GIF runs faster than real time.*
|
|
24
28
|
|
|
@@ -131,17 +135,102 @@ All of it is string arithmetic — **no embeddings, no model calls**.
|
|
|
131
135
|
|
|
132
136
|
---
|
|
133
137
|
|
|
138
|
+
## Current task context (v0.14)
|
|
139
|
+
|
|
140
|
+
Ranking answers "which documents look most like this conversation". But the question you
|
|
141
|
+
usually have is a different one:
|
|
142
|
+
|
|
143
|
+
> **For this task, what in the project should I read first?**
|
|
144
|
+
|
|
145
|
+
The Context Pack is the answer to that question, but it is a **data-layer structure**
|
|
146
|
+
(Primary / Supporting / Related, each entry carrying a deterministic reason) — **not a card of
|
|
147
|
+
its own**. So it lands directly in the document list: in relevance mode the document view goes
|
|
148
|
+
from one flat list to **three tier groups**, each group name followed by a very short hint.
|
|
149
|
+
|
|
150
|
+
```
|
|
151
|
+
┌─ Documents ──────────────────────────────┐
|
|
152
|
+
│ Primary read first │
|
|
153
|
+
│ 01 ● Relevance ranking algorithm 5m ago│
|
|
154
|
+
│ title matches: ranking │
|
|
155
|
+
│ │
|
|
156
|
+
│ Supporting supporting │
|
|
157
|
+
│ 02 Ranking evaluation set 2h ago │
|
|
158
|
+
│ body matches: term counting │
|
|
159
|
+
│ │
|
|
160
|
+
│ Related background │
|
|
161
|
+
│ 03 CHANGELOG.md 12d ago│
|
|
162
|
+
│ body matches: ranking │
|
|
163
|
+
└───────────────────────────────────────────┘
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
> The sketch leaves out each entry's summary. **The real structure is: a number in its own column
|
|
167
|
+
> on the far left (vertically centred with the first line), and to its right a stack of one line —
|
|
168
|
+
> Primary dot + title + relative time (right-aligned) — then the summary** (**no path** — it is not
|
|
169
|
+
> shown in the list; the path lives in the preview header's breadcrumb). And the list is
|
|
170
|
+
> **always one column** however wide the pane gets.
|
|
171
|
+
|
|
172
|
+
**No rules between groups**: hierarchy comes from 16px of space, the group name and type size,
|
|
173
|
+
never from separators. No scores, no percentages, no stars — "why is it here" states
|
|
174
|
+
deterministic facts only.
|
|
175
|
+
|
|
176
|
+
> **The right-hand "Current task context" panel has been removed** (2026-09-29). It said the same
|
|
177
|
+
> thing the three groups already say (the task sits in the quiet meta line above the list, the hit
|
|
178
|
+
> count duplicates the header total, and the three evidence kinds *are* the three group names), it
|
|
179
|
+
> added little visually, and it pushed Knit toward being an AI dashboard. Its
|
|
180
|
+
> resize / pull-out / snap-to-right-edge behaviour went with it — see `CHANGELOG.md`.
|
|
181
|
+
|
|
182
|
+
### The tiers are deterministic rules, not an AI judgement
|
|
183
|
+
|
|
184
|
+
| Tier | When a document enters it | Cap |
|
|
185
|
+
|---|---|---|
|
|
186
|
+
| **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 |
|
|
187
|
+
| **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 |
|
|
188
|
+
| **Related** | Everything else that matched, plus zero-hit link neighbours | 5 |
|
|
189
|
+
|
|
190
|
+
A cap is a **ceiling, not a quota**: primary is allowed to be empty (on real workspaces a fair
|
|
191
|
+
share of topics genuinely have no document that discusses them), and so is related. **If there
|
|
192
|
+
is no checkable reason, the document does not appear** — a document with zero hits and no link
|
|
193
|
+
is not "related to the current task"; the only caption it could carry is "this might help you",
|
|
194
|
+
which is exactly what this release refuses to print.
|
|
195
|
+
|
|
196
|
+
**"Why it is here"** is always a checkable fact:
|
|
197
|
+
|
|
198
|
+
| Reason | What it says |
|
|
199
|
+
|---|---|
|
|
200
|
+
| title / summary / body matches the topic: `term` | It really matched, and here is which term |
|
|
201
|
+
| referenced by a primary document | A path in the primary document points here |
|
|
202
|
+
| references a primary document | It mentions the primary document |
|
|
203
|
+
|
|
204
|
+
There is **no** "the AI thinks this matters" and **no** percentages, stars or confidence bars.
|
|
205
|
+
|
|
206
|
+
### Boundaries (stated, not oversold)
|
|
207
|
+
|
|
208
|
+
- **A link is not "more relevant".** Measured: the link graph does not close the vocabulary-mismatch
|
|
209
|
+
gap. So a link can only place a document in supporting / related — **never** in primary.
|
|
210
|
+
- **The ranking engine is unchanged.** This release adds a projection layer *above* ranking;
|
|
211
|
+
BM25 scoring and its evaluation (top-1 / MRR / trap cases) are untouched. If retrieval never
|
|
212
|
+
surfaced the right document, tiering can only tier what was surfaced — it cannot fix recall.
|
|
213
|
+
- **No task understanding.** The "Current task" line in the panel holds the **verbatim text of the
|
|
214
|
+
most recent user message**, not a summary of it — Knit does not interpret the sentence, it just
|
|
215
|
+
puts it where you can see it. Actually summarising it would need a model, and Knit calls none.
|
|
216
|
+
|
|
217
|
+
---
|
|
218
|
+
|
|
134
219
|
## Also for the agent: the `knit_docs` tool
|
|
135
220
|
|
|
136
221
|
The same ranking that you see in the panel is also exposed to the model.
|
|
137
222
|
|
|
138
223
|
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
|
-
|
|
224
|
+
project are most relevant to what we're discussing?"* and get back **the same Context Pack** the
|
|
225
|
+
panel shows — the `primary` / `supporting` / `related` tiers, each item carrying its path, title,
|
|
226
|
+
summary, a **structured reason** (`direct` / `titleMatch` / `summaryMatch` / `bodyMatch` /
|
|
227
|
+
`linkTarget` / `linkSource` / `related`), its **project role** (`impl` / `test` / `config` /
|
|
228
|
+
`design` / `doc`) and the matching snippet — then open one of them with its own `read` tool.
|
|
141
229
|
|
|
142
230
|
**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
|
-
|
|
231
|
+
and `read` them one by one. Knit has **already computed that ranking** every refresh; this tool
|
|
232
|
+
just hands it over — what it removes is **the "which few are relevant?" guess** (measured: an
|
|
233
|
+
agent holding the Pack no longer globs for candidates).
|
|
145
234
|
|
|
146
235
|
**Read-only, and it stores nothing**: it reads the files that are already in the project — this is
|
|
147
236
|
not "memory". The difference from memory plugins is that **theirs start empty** (the agent has to
|
|
@@ -212,6 +301,7 @@ feature request.
|
|
|
212
301
|
| One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
|
|
213
302
|
| Scans `.md` in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist`) | ✅ |
|
|
214
303
|
| Each row shows H1 title (or filename) + relative time + first-paragraph summary | ✅ |
|
|
304
|
+
| 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
305
|
| Click to preview inline, click again to collapse | ✅ |
|
|
216
306
|
| Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
|
|
217
307
|
| 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 +314,7 @@ feature request.
|
|
|
224
314
|
| Filter box over title / summary / path | ✅ |
|
|
225
315
|
| **Click the workspace path** to open the project folder in your file manager | ✅ |
|
|
226
316
|
| **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 | ✅ |
|
|
317
|
+
| 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
318
|
| Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
|
|
229
319
|
| Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
|
|
230
320
|
| Zero model calls, zero network egress | ✅ |
|
|
@@ -235,18 +325,62 @@ feature request.
|
|
|
235
325
|
|
|
236
326
|
### The other two views
|
|
237
327
|
|
|
238
|
-

|
|
239
329
|
|
|
240
330
|
*Images & video: square thumbnails, with the **column count following the panel width continuously** —
|
|
241
|
-
six columns at this width, cells about 112px.
|
|
242
|
-
|
|
243
|
-
|
|
331
|
+
six columns at this width, cells about 112px. These are the workspace's real image and SVG files; this
|
|
332
|
+
particular workspace happens to hold several screenshots and two single-colour SVG icons (the two solid
|
|
333
|
+
black squares are those icons). Videos get their first frame as a poster with a play glyph and a
|
|
334
|
+
duration badge — this workspace simply has no video, so none shows here.*
|
|
335
|
+
|
|
336
|
+

|
|
337
|
+
|
|
338
|
+
*All: the documents section shows at most 4, with a "View all →" link when truncated (here "4 / 40").*
|
|
339
|
+
|
|
340
|
+
⚠️ **There is no media section in this screenshot, and that is not a layout accident** — for the All
|
|
341
|
+
view the host fetches a **40-item window**. This workspace has 51 documents plus 8 media files, and the
|
|
342
|
+
media rank 50th–58th by relevance, so they fall outside the window; the client's
|
|
343
|
+
`visibleDocs.filter(isMedia)` is then empty and the media section is not rendered at all. **Any
|
|
344
|
+
workspace with 40 or more documents behaves this way** — a known defect, with reproduction and the fix
|
|
345
|
+
recorded in [`docs/README.md`](docs/README.md).*
|
|
346
|
+
|
|
347
|
+
---
|
|
348
|
+
|
|
349
|
+
## Did it actually get used? (v0.15)
|
|
350
|
+
|
|
351
|
+
Knit orders "what to read first right now" — but **whether that order was right could only be felt,
|
|
352
|
+
never checked**. v0.15 adds a layer of **verifiable usage feedback**: the files the agent really read,
|
|
353
|
+
matched against the context pack that was in effect **at the moment of the read**.
|
|
354
|
+
|
|
355
|
+
**Off by default.** There is a "Usage" toggle in the panel head; turning it on adds one muted line
|
|
356
|
+
above the list:
|
|
357
|
+
|
|
358
|
+
```
|
|
359
|
+
primary read (docs/xxx.md) · supporting 1/2 · 7 reads · 2 outside the pack · context changed 2×
|
|
360
|
+
```
|
|
361
|
+
|
|
362
|
+
It reports **facts only**: was the primary doc read, how many reads happened, how many fell outside
|
|
363
|
+
the pack, how often the context changed. **No score, no percentage, no progress bar** — these numbers
|
|
364
|
+
are counted, not estimated.
|
|
365
|
+
|
|
366
|
+
Three boundaries:
|
|
367
|
+
|
|
368
|
+
- **Off by default**: while it is off, Knit reads **no events and stores nothing**. This accounting
|
|
369
|
+
has a cost (every poll would walk the session's events), and that is the user's call, not ours.
|
|
370
|
+
- **No duplicate of the DSH trajectory**: the only evidence source is the `tool/call` / `tool/result`
|
|
371
|
+
events the session **already has** (successful `read`s). **No new event bus, no runtime trace,
|
|
372
|
+
no event store.**
|
|
373
|
+
- **Nothing is persisted**: the numbers live in kernel memory only and are gone after a DSH restart —
|
|
374
|
+
do not treat them as long-term statistics.
|
|
244
375
|
|
|
245
|
-
|
|
376
|
+
Agents get the same thing optionally: `knit_docs` accepts `audit: true` (default `false`), which
|
|
377
|
+
appends one line, `Usage since the last pack: …` (a report on the **previous** pack).
|
|
246
378
|
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
379
|
+
To check offline: `node tools/context-feedback-eval.mjs` replays the latest real session log;
|
|
380
|
+
`--control` is the "deliver no pack at all" arm. ⚠️ It splits "outside the pack" in two —
|
|
381
|
+
**in Knit's index but not in the pack** (a real miss) versus **not in the index at all** (`.js` /
|
|
382
|
+
`.json`, which Knit never indexes). Without that split the outside ratio stays high and reads like
|
|
383
|
+
"the Context Pack is useless", when in fact **the wrong thing was measured**.
|
|
250
384
|
|
|
251
385
|
---
|
|
252
386
|
|
|
@@ -256,6 +390,8 @@ title, time, summary, path — are still present: column count changes the layou
|
|
|
256
390
|
outside is rejected); for media it reads metadata only, never the pixels
|
|
257
391
|
- Reads only **the current session's** conversation events (used for ranking)
|
|
258
392
|
- The `knit_docs` tool is **read-only**: it writes no files and persists no index
|
|
393
|
+
- v0.15 usage accounting is **off by default**: when enabled it reads only the **current session's
|
|
394
|
+
existing** tool events (successful `read`s) — still no file writes, no persisted counters, gone on restart
|
|
259
395
|
- **Makes no outbound network requests**: the client's `fetch` calls all point to
|
|
260
396
|
the plugin's own same-origin routes
|
|
261
397
|
- **No install-time scripts** (no `install` / `postinstall`)
|
|
@@ -288,6 +424,11 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
288
424
|
video `mp4/m4v/webm/mov/ogv`; images ≤ 12MB and video ≤ 256MB or they are not listed
|
|
289
425
|
- **Media matches relevance by filename only**: no visual/audio content is parsed — give
|
|
290
426
|
screenshots and recordings searchable names
|
|
427
|
+
- **What we measured is *locating*, not *saving work***: in the on-machine A/B (frozen protocol,
|
|
428
|
+
four questions), an agent that could call `knit_docs` did **not** explore less — Control 4.75 →
|
|
429
|
+
Treatment 6.0 total tool calls, and no single question went down. The Pack did replace the
|
|
430
|
+
initial `glob` for candidates, but the **doubled `read` count** ate that back. It points
|
|
431
|
+
attention at the right file; that is **not** the same as the agent reading fewer files
|
|
291
432
|
- **Right-sidebar state is memory-only**: a refresh or a new session collapses it again
|
|
292
433
|
|
|
293
434
|
---
|
|
@@ -298,7 +439,7 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
298
439
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
299
440
|
cd dsh-knit
|
|
300
441
|
|
|
301
|
-
npm test #
|
|
442
|
+
npm test # 395 tests, zero dependencies, no npm install needed
|
|
302
443
|
```
|
|
303
444
|
|
|
304
445
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -315,10 +456,15 @@ knit/
|
|
|
315
456
|
├── cordis.patch.yml # the insert line mounted into the plugin tree
|
|
316
457
|
├── assets/ # icon source (path inlined into client.js)
|
|
317
458
|
├── src/
|
|
318
|
-
│ ├── host/index.js # /knit/api/recent · /doc · /raw
|
|
459
|
+
│ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
|
|
319
460
|
│ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
|
|
461
|
+
│ ├── host/links.js # reference parsing (pure; never touches ranking)
|
|
462
|
+
│ ├── host/context.js # context assembly: the three-tier Context Pack (pure, zero I/O)
|
|
463
|
+
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
320
464
|
│ └── client/client.js # dual-host registration + panel UI
|
|
321
|
-
└── test/ #
|
|
465
|
+
└── test/ # 395 tests
|
|
466
|
+
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
467
|
+
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
322
468
|
```
|
|
323
469
|
|
|
324
470
|
Details and trade-offs live in the source comments; see [CONTRIBUTING.md](CONTRIBUTING.md)
|