dsh-knit 0.14.0 → 0.16.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 CHANGED
@@ -3,6 +3,285 @@
3
3
  本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
4
4
  版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
5
5
 
6
+ ## [0.16.0] - 2026-10-01 · 未发布
7
+
8
+ > ⚠️ **未打 tag、未 publish** —— npm 上的最新版仍是 `0.15.0`。
9
+ > 这一版把上一节那批「未发布」的界面收敛**一起**带上。
10
+
11
+ **Context Effectiveness(依据 `01_ Knit PRD/SDD-v0.16-Context-Effectiveness.md`)**:
12
+ 一次读落在哪一层,**在读发生那一刻结算并冻结**;并正式引入 **Context Epoch**。
13
+ 检索侧一行没改(BM25 / IDF / 分层 / Context Pack 装配规则一个字没动),
14
+ **没有分数、没有百分比、没有新面板**。
15
+
16
+ ### 修好:历史归因会被「现在」改口(split-brain)
17
+
18
+ v0.15 里「这次读落在哪一层」被算了两遍:读入库那一刻算一遍(`recordRead()` → `snapshotAt()`,
19
+ 冻进 `firstTier`),出报告那一刻又拿**最新**那份快照重算一遍(`usageFrom()`)——
20
+ `byTier[].read` / `outside` / `supportingCoverage` / `firstReadTier` 全吃重算值。
21
+ 于是同一条读可以同时是 `firstTier='primary'` 与 `tier='related'`。真实场景就是:
22
+
23
+ ```
24
+ 10:00 交 Context A(primary = A.md)→ 10:01 读 A.md → 10:03 换 Context B → 10:04 看 usage
25
+ ⇒ A.md 被算成「包外」—— 历史被现在改口了。
26
+ ```
27
+
28
+ 现在只有一条规则,由 `src/host/feedback.js` 的两个纯函数说了算:
29
+
30
+ | 函数 | 语义 |
31
+ |---|---|
32
+ | `snapshotAt(snapshots, readSeq)` | 取 `seq <= readSeq` 的**最新**快照 = 读发生时生效的那一份 |
33
+ | `attributeRead(snapshot, rel)` | 输出 `{ snapshotSeq, epochId, tierAtRead, rankAtRead, insideAtRead }`,读时冻结 |
34
+
35
+ `recordRead()` 在读那一刻调它并冻进 `firstRead` / `lastRead`;`usageFrom()` 只读冻结值。
36
+ `reads[]` 行上的 `tier` / `rank` / `outside` 也一律是**首读**的归因(不再是「它现在在哪一层」),
37
+ 旧字段名(`firstTier` / `firstReadAt` / `outsideCount` …)与旧键 `churn.snapshots` 全部保留为兼容别名。
38
+
39
+ ### 修好:右栏收起之后,Knit 还在每 5 秒敲一次宿主
40
+
41
+ **现象(2026-10-01 用户报)**:一旦点开过文件、再把右栏那一栏关掉或收起来,过一会儿它会变成
42
+ **一片空白** —— 没有芯片、没有文字,也没有「这类内容还没有可用的查看方式」。
43
+
44
+ **查到的**:官方右侧栏收起时**不卸载**标签身体(dockkit 的 `keepMounted`),而 `KnitBody` 的轮询
45
+ 过去只看「挂载了没有」——于是收起来之后照旧每 5 秒请求一次 `/knit/api/recent`(一次全工作区扫描)
46
+ 并 `setState`,等于往宿主正在收起 / 展开的那棵子树上又插了一帧重渲染。
47
+ 实测(headless Chrome 里的真客户端):收起状态 12 秒里发了 **2 次**请求;那一栏确实还在
48
+ `visibility:hidden` 里挂着(`knitVisible.visibility === 'hidden'`、`knitRoot === true`)。
49
+
50
+ **修法**:用座位契约里现成的 `tab.visible` 做闸门。官方在
51
+ `@deepseek-ai/dsh-client-ui-sidebar-right` 里算的是
52
+
53
+ ```js
54
+ visible: active && (pane.host === 'float' || layout.expanded && (title || pane.activeTabId === tabId))
55
+ ```
56
+
57
+ 也就是「收起」与「不是当前标签」两种情况都是 `false`。座位适配层把它传给 `KnitBody`:看不见时
58
+ **连请求都不发**,在途的那次回来也不落状态;`visible` 变回 `true` 时那个 effect 会重跑 ⇒
59
+ **立刻补一次**,不必等下一个 5 秒。
60
+
61
+ - 实测(同一台真客户端):收起 13 秒 **0 次**请求(修前 2 次);重新展开 7 秒内 **2 次**(立刻 + 5 秒那次)。
62
+ - 拿不到 `tab.visible` 时(别的宿主 / 降级路径)**当作看得见**,不会把面板冻住。
63
+
64
+ ### 修好:右侧栏「开始」页出现两行一模一样的入口
65
+
66
+ **现象(2026-10-01 用户报)**:右侧栏「开始」页上有两行同名胶囊(都是「Knit 最近文档」),
67
+ 点哪一行都进 Knit。
68
+
69
+ **查到的**:`dsh-better-sidebar` v0.24.1 起有个「原生表面」——把它自己每个 tab descriptor
70
+ 镜像成官方右侧栏的一个类型(`id = dsh-better-sidebar:<descriptor.id>`、`kind = descriptor.id`),
71
+ 并且**在 descriptor 没写 `hidden` 时连带注册一条 guide 条目**:
72
+
73
+ ```js
74
+ ...descriptor.hidden === true || isEditor ? {} : { guide: [{ id: descriptor.id, order: descriptor.order ?? 100, … }] }
75
+ ```
76
+
77
+ 于是「开始」页同时挂着 ① 我们自己的类型(`kind: 'knit'`)与镜像(`kind: 'knit:recent'`),
78
+ 标题都取 `guide.title` ⇒ 两行同名。(并不是 Knit 注册了两次。)
79
+
80
+ **修法**:给 `ctx.betterSidebar.registerTab` 的 descriptor 加 `hidden: true`。它只掐掉那一条镜像
81
+ guide 条目(连带 + 菜单项),镜像的类型 / 座位 / `ctx.betterSidebar.openTab` 都还在;入口保留 ①
82
+ 那条 —— 不依赖宿主装没装 better-sidebar。
83
+
84
+ - 实测(真客户端 + 刷新):修前 5 条胶囊里两条 Knit;修后只剩 `data-sidebar-right-guide-entry="knit"` 一条,
85
+ 点它照旧开 `tab8`「Knit」。
86
+
87
+ ### 新增:Context Epoch
88
+
89
+ - **一份快照 = 一个 Epoch**:`epochId` 从 1 开始,**内容真的换了才 +1**
90
+ (签名 = `task` + 三层 `tier:rank:rel`,与 v0.15 同一套判据)——5 秒轮询不会灌进几十个 Epoch。
91
+ - **`usage.epochs[]` 与快照栈同生共死**:每项 `{ epochId, snapshotSeq, topic, task,
92
+ primary/supporting/related: { rel|total, read }, outsideReads, continuedReadsAfterExit, reEntries }`。
93
+ **只供内部 / 离线回放 / 将来的评估** —— v0.16 不把它上任何工具输出。
94
+ - 保留上限:`MAX_SNAPSHOTS_PER_SESSION` **2 → 20**、`MAX_DELTAS_PER_SESSION` **20 → 50**。
95
+ 归因在读时结算,保留数量只决定「离开 / 重新进入」能回溯多远(**宁可漏记,也不猜**)。
96
+ - `churn` 口径:新增 `epochs`(换过几个不同的上下文 = 最后一份的编号),`changes = epochs - 1`;
97
+ 客户端在用的 `snapshots` / `deltas` 保留为 `changes` 的别名(文案「上下文换过 N 次」不变)。
98
+
99
+ ### 新增:两个事实字段(只记事实,不加解释)
100
+
101
+ | 字段 | 判据(只在保留窗口内推导) |
102
+ |---|---|
103
+ | `continuedReadAfterExit` | 这次读**在当时那份快照之外**,且更早的某份快照里有这篇 |
104
+ | `reEntry` | 这次读**在当时那份快照之内**,更早的某份快照里也有,但中间至少有一份没有它 |
105
+
106
+ ⚠️ 它们**不许**被读成「Agent 不认可新上下文」——那是推断,不是事实(SDD §5 Evidence Over Interpretation)。
107
+ `firstReadTier` 多一个取值 `'outside'`(读过、但读在包外);`null` 只留给「一次都还没读」。
108
+
109
+ ### 改法:读证据不再拉会话事件,改成订阅 `session/event`
110
+
111
+ `session.snapshotEvents()` 已被 DSH 标为 deprecated(`dsh-session/README.md:62`:
112
+ "new production calls are prohibited")。v0.16 把读证据的来源换成宿主事件流:
113
+
114
+ - `apply(ctx)` 顶部 `ctx.on('session/event', onSessionEvent, { global: true })`;回调首行按 `session.id`
115
+ **早退** —— 没开审计的会话只花一次 Map 查找,不建快照、不统计、不进内存。
116
+ - `ingestEvents(store, sessionId, [event], { root })` **单事件**入库;游标幂等不变。
117
+ - **两个行为变化**:① 订阅之前发生的事**不再回补**(不碰废弃 API 就读不到历史)——
118
+ 打开「使用情况」的那一刻起才开始计数;② fork 出来的会话**不再把父会话继承的读算进自己账上**
119
+ (seed 事件不派发;v0.15 从 `state.seq = -1` 拉全量时会算进去)。
120
+
121
+ ### 界面:只多一句「当前上下文 · Epoch N」
122
+
123
+ 不加 Dashboard、不加图表、不动布局;开关打开后那一行**开头**多一个累计编号,其余逐字不变。
124
+
125
+ ### 量尺
126
+
127
+ `tools/context-feedback-eval.mjs`:日志文件名改成**按形状认**(`session.v<N>.jsonl[.zstd]`,
128
+ v0-v4 三代并存都能读,以前写死 v4);`metricsFor()` 增 `epochs` / `continuedReadsAfterExit` / `reentries`、
129
+ `contextChanges` 改读 `churn.changes`;Control 自检的判据放宽成「不许有**落在层里**的读」
130
+ (`'outside'` 在对照组是正常的)。
131
+
132
+ ⚠️ **对齐的是规则,不是数字**:离线量尺与 runtime 共用同一份归因(都调 `feedback.js`),
133
+ 但**交付时刻**不同 —— 面板轮询 / 工具调用是采样,量尺是「每次读前合成一份包」。
134
+ 逐字段一致是**规则**级;数字级对齐做不到(SDD §3 G4 已据此改名并写明原因)。
135
+
136
+ ### 测试
137
+
138
+ - 新增 `test/context-effectiveness.test.mjs`(12 条):历史归因(§24.3)、离开后仍被读(§24.4)、
139
+ 重新进入(§24.5)、**规则一致**(§24.6:runtime 记下的归因逐字段等于 `snapshotAt()` +
140
+ `attributeRead()` 现算的结果)、Epoch 边界与上限。
141
+ - `test/context-delta.test.mjs` 里那条钉着 split-brain 的双轨断言(`firstTier='primary'` 与
142
+ `tier='related'` 同时成立)改写成「`tier` 也是首读的归因」。
143
+ - `test/host-http.test.mjs` 的「使用情况」整段改成**事件驱动**(假 ctx 收 `session/event` 派发),
144
+ 顺带覆盖:订阅前的事件不回补、同一 seq 派发 10 次仍只算一遍、畸形事件不影响接口。
145
+ - 测试数:**453 / 453 → 468 / 468**。
146
+ - `test/client.test.mjs` 新增 2 条**可见性**用例:`visible === false` 时一次都不取数、也不挂轮询;
147
+ 座位契约的 `tab.visible` 一路传到 `KnitBody`(拿不到 `useTabInfo` 时按「看得见」处理)。
148
+
149
+ ## [0.15.1] - 2026-09-30 · 未发布
150
+
151
+ > ⚠️ 这一版**已提交、未打 tag、未 publish**,随后**并进了 v0.16.0**(见上一节)——
152
+ > npm 上的最新版仍是 `0.15.0`,下面这批界面收敛会**一起**出现在 0.16.0 里。
153
+
154
+ **界面收敛 + 一处真机修复**:没有新指标、没有新接口,BM25 一行没改,Context Pack 的装配规则一行没改。
155
+
156
+ 用户看过 v0.15 的真实界面之后提了五处收敛(2026-09-30),共同点是同一条审美主张 ——
157
+ **能用空间表达的层级,就别再画线**:
158
+
159
+ | 改动 | 说明 |
160
+ |---|---|
161
+ | **排序说明那一行整行删除** | 列表上方 `.knit-topic`(`Sorted by relevance` / `按修改时间倒序`,以及它 `title` 里的命中关键词)**整行删掉**:排序方式已经由「相关 / 最新」切换按钮自己表达,再写一行是重复。随之把 `topic.relevancePlain` / `topic.relevanceTerms` / `topic.needsConversation` / `topic.time` 四个文案键从**两种语言里一并删掉**(不为「以后可能用」留着),客户端那份因此变成死代码的 `topic` state 也清了(初始化 + 三处错误分支 + payload 赋值共 5 处) |
162
+ | **类型行不再画全宽底边** | `.knit-types` 的 `border-bottom` 删除 —— 层级只由选中页签自己那条 2px 下划线表达(**那条保留**,用户明确说删的不是它) |
163
+ | **列表行不再有描边** | `.knit-doc` 静止态那条 `.5px solid transparent` 占位、悬停与选中各自上的 `border-color` 三处一起删;「正在预览」只剩灰底,灰底成为唯一的分层信号。⚠️ 边框删了要用 `padding:10px 11px → 10.5px 11.5px` **把几何补回来**,否则每行矮 1px、左右各窄 .5px |
164
+ | **引用区上下两条细线都删** | 预览头的 `border-bottom: .5px border-l3` 与引用条的 `border-bottom: 1px border-l2` 一起删(38px 头部高度保留,排版不动,只是不画线)。这两条线把「被引用」夹在中间,视觉上割裂 |
165
+ | **过滤框提示简化** | `过滤标题 / 摘要 / 路径` → **「过滤文档」**(英文 `Filter title / summary / path` → `Filter docs`):不列字段清单,字段范围由行为本身说明 |
166
+
167
+ ### 修好:悬停浮层永远显示「0 篇」
168
+
169
+ 真机上对话头部右侧那个 Knit 图标,悬停后浮层只有「**0 篇 / 这个工作区里还没有 Markdown 文档。**」,
170
+ 可面板里同一个工作区的文档一切正常。根因**不在列表逻辑,而在取「当前会话 id」的方式**:
171
+
172
+ - 入口按钮坐在 `conversation.session.header.utilities` 这个 **session 作用域**的座位上,框架通过
173
+ **标准 props 直接把当前会话 id 递进来**(`SessionStandardProps.sessionId`,由 `dsh-client-ui-session`
174
+ 以 `props: ["sessionId"]` 注入;座位契约也写明「Header actions derive their state from standard Session props」)。
175
+ - Knit 从 v0.5.0 起读的却是 `ctx.sessions.list` 快照里的 `snapshot.current` —— **现行契约里没有这个字段**:
176
+ `SessionListState` 只有 `{ ids, byId, phase, projectionsBySession }`,契约注释是
177
+ 「navigation belongs to view owners」。⇒ 恒取到空串 ⇒ 每次都走「没有当前会话」分支 ⇒ 空态。
178
+
179
+ 改法:**座位 props 的 `sessionId` 优先**,取不到时才退回老读法(`snapshot.current`,给更老的内核兜底)。
180
+ 「点浮层里某一篇直接展开它的预览」这条通路一直是好的,只是列表为空时点不到 —— 会话 id 一恢复它就回来了。
181
+
182
+ ⚠️ **测试为什么没拦住**:`test/peek.test.mjs` 的假上下文把 `sessions.list.getSnapshot()` 假成了
183
+ `{ current: 's-1' }` —— 一个现行内核里根本不存在的字段,于是 450 条测试全绿、真机上永远是空态。
184
+ 现在假件照着契约写成 `{ ids, byId, phase, projectionsBySession }`,**当前会话 id 一律走座位 props**,
185
+ 并新增两条回归用例:① 座位 props 生效(快照里没有 `current` 也要照常拉列表);② 老内核退回 `current`。
186
+
187
+ 测试侧同步改了钉住这五条的断言,并把**「删除」本身写成防回潮断言** —— 新增一条用例守着:
188
+ 那三处描边、两条分割线、那一行的类名、四个文案键,**只要回来就红**。
189
+ 测试数:**453 / 453**(合并两条 i18n 用例、新增一条防回潮用例、上述两条会话 id 回归用例,
190
+ 再加下面这条「占位标记」用例)。
191
+
192
+ 顺带修掉 `knit/README.md` / `knit/README.en.md` 里两处陈旧数字:`395 项测试` → `450`(v0.15.0 时漏改),
193
+ 并在目录树里补上 v0.15.0 就存在、却一直没列出的 `src/host/feedback.js`。
194
+
195
+ ### 改动:没序号的行不再把序号那一列空着
196
+
197
+ 「其他相关文档」不在 Context Pack 里,所以按 v0.14 的规矩**不编号** —— 但那一格空着,
198
+ 读到的不是「对齐」,而是「漏了一个号」(用户 2026-10-01 原话:「其他相关文档…又没有这个序号,
199
+ 没有序号以后左边就空了,视觉上比较割裂,就觉得是个 bug 一样」)。
200
+
201
+ - **编号规则不变**:仍然是**跨三档连续**的一条序列(01…0N)。三层是**同一个包的一条阅读顺序**
202
+ (先看 / 辅助 / 背景),不是三个各自排名的清单 —— 所以不改成「每一档各自从 01 开始」。
203
+ - **没号的行在同一列渲染一个中性标记 `.knit-gapmark`(·)**:不冒充序号,也不让轨道断掉,
204
+ 「所有行左边缘对齐」那条纪律照旧。它和 `.knit-num` **共用同一条 CSS 选择器**,
205
+ 于是「序号行高 = 标题行高」这条纪律自动覆盖它(不用再同步第三处数字)。
206
+ - ⚠️ **只有这一屏里有号时才渲染**:时间序 / 平铺列表整屏都没号 ⇒ 一个标记都没有。
207
+ 刺眼的从来是**混着**(一半有号、一半空着),整屏一致就没人觉得缺东西 —— 这条也有用例守着。
208
+
209
+ ### 改动:预览头路径收敛成「…/文件名」+ 按钮改「本地打开」
210
+
211
+ 用户 2026-10-01 原话:「前面那一串都用三个点点点来表示就行了…我觉得这样就够了。…我是想让右边的空间多一点。
212
+ 另外右边的在本地打开,我觉得修改成本地打开就行。这样改下来,整个 UI 就变得更加鲜亮了」。
213
+
214
+ - **目录段不再上屏**:`.knit-preview-dir` 的内容由 `splitRelPath(preview.rel).dir`(整段目录)改成
215
+ **固定占位 `…/`**;`splitRelPath()` 函数本身一行没改(无目录时依旧只渲染文件名)。
216
+ **完整相对路径没丢** —— 它在 `.knit-preview-path` 的 `title` 里(悬停即见),
217
+ 路径按钮本身仍然可点、仍然是用系统默认应用打开这篇文档。
218
+ - **CSS**:`.knit-preview-dir{flex:0 0 auto;color:var(--dsw-alias-label-tertiary,…)}` —— 不再需要
219
+ `min-width:0` + `overflow:hidden` + `text-overflow:ellipsis` 那套收缩(目录已经不渲染了)。
220
+ - **文案**:中文 `'preview.openLocalBtn'`:`在本地打开` → **`本地打开`**(英文 `Open locally` 不动)。
221
+ - 测试同步:面包屑用例改成断言目录段文本 === `…/`、整条路径文本 === `…/需求 文档.md`,tooltip 仍带完整
222
+ `sub/需求 文档.md`;`test/path.test.mjs` 里「在本地打开」全部改成「本地打开」。测试数仍 **453 / 453**。
223
+
224
+ ### 改动:悬停浮层删掉页脚「点击打开面板」与它上面那条横线
225
+
226
+ 用户 2026-10-01 原话:「那个文档列表下面不是有"点击打开面板"还有上面那条横线,我觉得都可以删掉,有点多余了」。
227
+
228
+ - 删掉 `KnitPeek` 末尾那个页脚节点与 `'peek.openPanel'` 两个文案键(中英各一条,别处没有引用);
229
+ - 删掉专门给页脚画线的 `.knit-peek-list + .knit-peek-hint{… border-top: …}` 这条 CSS 规则;
230
+ - **保留** `.knit-peek .knit-peek-hint`(空态那句「这个工作区里还没有 Markdown 文档。」仍然在用)。
231
+ - 浮层那两条通路(点某一篇直接展开预览、点图标打开面板)一行没动。测试数仍 **453 / 453**。
232
+
233
+ ## [0.15.0] - 2026-09-30
234
+
235
+ **从「构建一份当前任务上下文」再往前一步:让上下文能回答「它到底有没有被用上」。**
236
+ 排序(BM25)一行没改,Context Pack 的装配规则一行没改,**没有模型、没有联网、没有长期记忆** ——
237
+ 这一版加的是**一层可核验的使用反馈**:把 agent 真实读过哪些文件(会话日志里的
238
+ `tool/call(name="read")` 与按 `callId` 配对的 `tool/result`)跟「**读发生那一刻**生效的那份
239
+ Context Pack」对起来,得到五个计数:**Primary follow-through / First read tier /
240
+ Supporting coverage / Outside-context / Delta churn**。**只报事实**:没有分数、没有百分比、
241
+ 没有评分条、没有置信度。
242
+
243
+ ⚠️ **两条硬边界(别越)**:
244
+
245
+ 1. **默认关。** 只有人显式打开(面板头部「使用情况」开关 → 请求带 `usage=1`,或
246
+ `knit_docs` 传 `audit:true`)才开始记账;没打开时**不读一个事件、不攒一条数据**。
247
+ 理由是这笔账有代价(每次轮询都要读一遍会话事件),不该由 Knit 替用户决定。
248
+ 2. **不重复 DSH Trajectory。** 证据的**唯一来源**是会话里**已经存在**的 `tool/call` /
249
+ `tool/result` 事件(`session.snapshotEvents()`,沿用既有拉取式架构,用 `seq` 做幂等游标)——
250
+ **没有新的事件总线、没有 Runtime Trace、没有 Event Store**;数据只在内核内存里,
251
+ 重启即失(不落盘、不进 `localStorage`)。
252
+
253
+ ### 加了什么
254
+
255
+ | 新增 | 说明 |
256
+ |---|---|
257
+ | **`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** 淘汰最久没碰的会话 |
258
+ | **读落在哪一层,看的是「读发生那一刻」的包** | 每篇读按 `firstReadSeq` 找 `seq ≤` 它的**最新一份快照**。少了这一步,一次话题切换会把之前所有读重新贴上「包外」的标签,指标全是噪声 |
259
+ | **`/knit/api/recent?usage=1`** | 开闸信号:**第一次带它就等于对本次会话说「开始记账」**,此后不带参数也回传 `usage`。`/api/context` 只推进快照、**从不激活**。顺序是契约:`usage` 先算(它报告的是**上一份**包),快照后记 |
260
+ | **`knit_docs` 的 `audit` 参数(默认 `false`)** | `audit:true` 时在工具结果末尾追加一行 `Usage since the last pack: …`(报告**上一份**包),并把这次装配记进快照。不传 `audit` 的一次普通调用**一个记账方法都不碰**(有测试钉住) |
261
+ | **面板头部的「使用情况」开关(默认关)** | 打开后列表上方多一行弱化文字:`先看的「x.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次`。**没有分数 / 百分比 / 进度条 / 品牌色**,风格与「相关性排序」那行同档 |
262
+ | **`tools/context-feedback-eval.mjs`** | 拿真实会话日志(`~/.dsh/sessions/<工作区>/<会话>/session.v4.jsonl.zstd`)**离线回放**;`--control` 时一份包都不交,做对照组。把「包外」拆成 **`missed`**(Knit 索引里有、却没进包 —— 真漏)与 **`outOfScope`**(压根不在索引里,例如 `.js`):不拆开的话 `outside` 恒高,读起来像「Context Pack 没用」,其实是**量错了东西** |
263
+ | **`test/feedback.test.mjs` · `test/context-delta.test.mjs` · `test/context-feedback-eval.test.mjs`** | 17 + 16 + 7 条:路径归一化的八种输入 / 配对与游标幂等 / 上限与降级不抛 / Delta 四类 / 审计开关 / **Control(不交包 ⇒ 读全在包外)vs Treatment(交包 ⇒ `firstReadTier === 'primary'`)的确定性对照** / 坏行不废整批 |
264
+
265
+ ### 真机读数(本机 `08_Knit`,会话 `session-09a33302`,**只量事实、不下结论**)
266
+
267
+ - **Treatment**(交包):**392** 份包 · Primary follow-through **YES** · Supporting coverage **1.00** ·
268
+ 包外 **25/32 篇(共 392 次)**,其中 Knit 看得到的 11 篇里漏了 **35** 次、真心漏的只有 4 篇
269
+ (`knit/CHANGELOG.md` · `knit/README.md` · `03_发布/验收-v0.14-重启后待执行.md` · `README.md`)·
270
+ Delta churn:**换过 66 次 / 进 177 / 出 177 / 换层 271 / 任务变了 14**。
271
+ - **Control**(`--control`,不交包):**0** 份包 · 包外 **32/32** · `missed` 11 篇(140 次)· churn 0 ·
272
+ 自检退出码 0(**量尺没坏**)。
273
+ - ⇒ 可复述的只有一句:**agent 读的东西绝大多数是代码文件** —— 32 篇里 21 篇根本不在 Knit 的索引内
274
+ (`.js` / `.json`)。这是**量尺的读数**,不能读成「Context Pack 没用」,也不能读成「有用」。
275
+
276
+ **测试:`395 → 447 → 450`**(+33 `feedback`/`context-delta`、+7 `context-feedback-eval`、
277
+ +7 `tool` 的 audit 通道、+5 `host-http` 的真实回环 HTTP、+3 `client` 的「使用情况」;
278
+ `i18n` 与 `client` 里几条旧断言随「头部多了一个按钮」同步)。`test/context-feedback-eval.test.mjs`
279
+ 与另两个新文件都**手写进了 `package.json` 的 `scripts.test`**(测试文件现共 19 个)。
280
+
281
+ ⚠️ 这一版**宿主侧**(`src/host/*`)改了,要**重启 DSH** 才生效(`curl -s
282
+ "http://127.0.0.1:3080/knit/api/raw?rel=nope.png"`:空 body 的 404 = 旧代码;
283
+ `{"ok":false,"code":"knit/not-found"}` = 新代码在跑);前端那个开关只需 `Cmd + Shift + R`。
284
+
6
285
  ## [0.14.0] - 2026-09-29
7
286
 
8
287
  **从「按当前对话给文档排序」升级成「按对话构建当前任务最需要的项目上下文」。**
package/README.en.md CHANGED
@@ -7,18 +7,22 @@
7
7
 
8
8
  ![Screenshot from a real machine: the Knit sidebar ranking the workspace documents by relevance, with a Markdown preview expanded in place and the references bar below the preview header](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot.png)
9
9
 
10
- *Screenshot from a real machine, not a mock-up: a workspace with 36 documents — the list, an inline
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 only** — the directory collapses to a `…/` placeholder (hover the path for the full relative path); rows no longer repeat it.*
16
19
 
17
20
  ![Order follows the conversation: send a message and the sidebar re-ranks the document list by it](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/demo-reorder.gif)
18
21
 
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
+ *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
 
@@ -162,7 +166,7 @@ from one flat list to **three tier groups**, each group name followed by a very
162
166
  > The sketch leaves out each entry's summary. **The real structure is: a number in its own column
163
167
  > on the far left (vertically centred with the first line), and to its right a stack of one line —
164
168
  > 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
169
+ > shown in the list; the path lives in the preview header, with the directory collapsed to `…/`). And the list is
166
170
  > **always one column** however wide the pane gets.
167
171
 
168
172
  **No rules between groups**: hierarchy comes from 16px of space, the group name and type size,
@@ -297,7 +301,7 @@ feature request.
297
301
  | One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
298
302
  | Scans `.md` in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist`) | ✅ |
299
303
  | 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 | ✅ |
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** in the preview header, which is the one that stays | ✅ |
301
305
  | Click to preview inline, click again to collapse | ✅ |
302
306
  | Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
303
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 | ✅ |
@@ -305,11 +309,11 @@ feature request.
305
309
  | Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
306
310
  | The **All** view splits into **two stacked sections**: docs (max 4, with "View all →" when truncated) and images & video (**never truncated**, count only) | ✅ |
307
311
  | Preview pane is height-draggable (20%–80%, remembered), fullscreen-able, `Esc` to exit | ✅ |
308
- | **"Open locally"**: opens the previewed document in your default app (the path breadcrumb in the preview header is clickable too) | ✅ |
312
+ | **"Open locally"**: opens the previewed document in your default app (the path in the preview header is clickable too, and its tooltip carries the full relative path) | ✅ |
309
313
  | Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
310
314
  | Filter box over title / summary / path | ✅ |
311
315
  | **Click the workspace path** to open the project folder in your file manager | ✅ |
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) | ✅ |
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; the popover is just header + list — no extra divider or hint line) | ✅ |
313
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) | ✅ |
314
318
  | Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
315
319
  | Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
@@ -321,24 +325,75 @@ feature request.
321
325
 
322
326
  ### The other two views
323
327
 
324
- ![Screenshot of the Images & video tab: a square thumbnail grid, six columns at this panel width, with a video thumbnail carrying a play glyph and a duration badge](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
328
+ ![Screenshot of the Images & video tab: a square thumbnail grid, six columns at this panel width](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-media.png)
325
329
 
326
330
  *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.*
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.*
330
335
 
331
- ![Screenshot of the All tab: documents above, media with a count only below](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
336
+ ![Screenshot of the All tab: the documents section showing the first 4 with a "View all →" link, and no media section](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
332
337
 
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.*
338
+ *All: the documents section shows at most 4, with a "View all →" link when truncated (here "4 / 40").*
335
339
 
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.
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.16)
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 added 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
+ v0.16 nails that down: **attribution is settled and frozen at read time** — however the context
355
+ changes later, the historical numbers never change their story (in v0.15 a read could be
356
+ re-judged as "outside" by the present, which was a bug).
357
+
358
+ **Off by default.** There is a "Usage" toggle in the panel head; turning it on adds one muted line
359
+ above the list:
360
+
361
+ ```
362
+ Context · Epoch 4 · primary read (docs/xxx.md) · supporting 1/2 · 7 reads · 2 outside the pack · context changed 2×
363
+ ```
364
+
365
+ - **Context Epoch**: one **content-changed** context equals one epoch (identical content creates
366
+ none, so polling cannot flood it). `Epoch 4` is a cumulative number, not "the 4th pack".
367
+ - **Two fact-only fields**: `continuedReadAfterExit` (it was still read after leaving this context)
368
+ and `reEntry` (it left, came back into the pack, and was read again). They must **never** be read
369
+ as "the agent rejected the new context" — that is inference, not fact.
370
+
371
+ It reports **facts only**: was the primary doc read, how many reads happened, how many fell outside
372
+ the pack, how often the context changed. **No score, no percentage, no progress bar** — these numbers
373
+ are counted, not estimated.
374
+
375
+ Three boundaries:
376
+
377
+ - **Off by default**: while it is off, Knit **counts nothing** (it subscribes to the host event
378
+ stream, but the callback bails out on the first line for unaudited sessions — one Map lookup).
379
+ That accounting is the user's call, not ours.
380
+ - **No duplicate of the DSH trajectory**: the only evidence source is the `tool/call` / `tool/result`
381
+ events the session **already has** (successful `read`s). **No new event bus, no runtime trace,
382
+ no event store.**
383
+ - **From now on only**: the subscription is v0.16's sole read-evidence source (the old
384
+ `session.snapshotEvents()` is deprecated by DSH), so **reads that happened before you flipped the
385
+ toggle are not backfilled** — counting starts at that moment.
386
+ - **Nothing is persisted**: the numbers live in kernel memory only and are gone after a DSH restart —
387
+ do not treat them as long-term statistics.
388
+
389
+ Agents get the same thing optionally: `knit_docs` accepts `audit: true` (default `false`), which
390
+ appends one line, `Usage since the last pack: …` (a report on the **previous** pack).
391
+
392
+ To check offline: `node tools/context-feedback-eval.mjs` replays the latest real session log;
393
+ `--control` is the "deliver no pack at all" arm. ⚠️ It splits "outside the pack" in two —
394
+ **in Knit's index but not in the pack** (a real miss) versus **not in the index at all** (`.js` /
395
+ `.json`, which Knit never indexes). Without that split the outside ratio stays high and reads like
396
+ "the Context Pack is useless", when in fact **the wrong thing was measured**.
342
397
 
343
398
  ---
344
399
 
@@ -348,6 +403,8 @@ The screenshot has not been retaken yet.
348
403
  outside is rejected); for media it reads metadata only, never the pixels
349
404
  - Reads only **the current session's** conversation events (used for ranking)
350
405
  - The `knit_docs` tool is **read-only**: it writes no files and persists no index
406
+ - v0.15 usage accounting is **off by default**: when enabled it reads only the **current session's
407
+ existing** tool events (successful `read`s) — still no file writes, no persisted counters, gone on restart
351
408
  - **Makes no outbound network requests**: the client's `fetch` calls all point to
352
409
  the plugin's own same-origin routes
353
410
  - **No install-time scripts** (no `install` / `postinstall`)
@@ -395,7 +452,7 @@ The relevance figure only affects ordering — it is **never displayed and never
395
452
  git clone https://github.com/PolinniZhong/dsh-knit.git
396
453
  cd dsh-knit
397
454
 
398
- npm test # 395 tests, zero dependencies, no npm install needed
455
+ npm test # 468 tests, zero dependencies, no npm install needed
399
456
  ```
400
457
 
401
458
  **How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
@@ -416,9 +473,10 @@ knit/
416
473
  │ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
417
474
  │ ├── host/links.js # reference parsing (pure; never touches ranking)
418
475
  │ ├── host/context.js # context assembly: the three-tier Context Pack (pure, zero I/O)
476
+ │ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
419
477
  │ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
420
478
  │ └── client/client.js # dual-host registration + panel UI
421
- └── test/ # 395 tests
479
+ └── test/ # 468 tests
422
480
  ├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
423
481
  └── context/ # context tiering: 24-doc corpus + 12 real-task cases
424
482
  ```