dsh-knit 0.15.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,233 @@
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
+
6
233
  ## [0.15.0] - 2026-09-30
7
234
 
8
235
  **从「构建一份当前任务上下文」再往前一步:让上下文能回答「它到底有没有被用上」。**
package/README.en.md CHANGED
@@ -15,7 +15,7 @@ one to jump straight there.*
15
15
  falls back to newest-first and states its basis.*
16
16
  *Since v0.14 the list is always one column: the rank number sits in its own column on the far left
17
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.*
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.*
19
19
 
20
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)
21
21
 
@@ -166,7 +166,7 @@ from one flat list to **three tier groups**, each group name followed by a very
166
166
  > The sketch leaves out each entry's summary. **The real structure is: a number in its own column
167
167
  > on the far left (vertically centred with the first line), and to its right a stack of one line —
168
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
169
+ > shown in the list; the path lives in the preview header, with the directory collapsed to `…/`). And the list is
170
170
  > **always one column** however wide the pane gets.
171
171
 
172
172
  **No rules between groups**: hierarchy comes from 16px of space, the group name and type size,
@@ -301,7 +301,7 @@ feature request.
301
301
  | One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
302
302
  | Scans `.md` in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist`) | ✅ |
303
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 | ✅ |
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 | ✅ |
305
305
  | Click to preview inline, click again to collapse | ✅ |
306
306
  | Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
307
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 | ✅ |
@@ -309,11 +309,11 @@ feature request.
309
309
  | Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
310
310
  | The **All** view splits into **two stacked sections**: docs (max 4, with "View all →" when truncated) and images & video (**never truncated**, count only) | ✅ |
311
311
  | Preview pane is height-draggable (20%–80%, remembered), fullscreen-able, `Esc` to exit | ✅ |
312
- | **"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) | ✅ |
313
313
  | Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
314
314
  | Filter box over title / summary / path | ✅ |
315
315
  | **Click the workspace path** to open the project folder in your file manager | ✅ |
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) | ✅ |
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) | ✅ |
317
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) | ✅ |
318
318
  | Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
319
319
  | Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
@@ -346,30 +346,43 @@ recorded in [`docs/README.md`](docs/README.md).*
346
346
 
347
347
  ---
348
348
 
349
- ## Did it actually get used? (v0.15)
349
+ ## Did it actually get used? (v0.16)
350
350
 
351
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,
352
+ never checked**. v0.15 added a layer of **verifiable usage feedback**: the files the agent really read,
353
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).
354
357
 
355
358
  **Off by default.** There is a "Usage" toggle in the panel head; turning it on adds one muted line
356
359
  above the list:
357
360
 
358
361
  ```
359
- primary read (docs/xxx.md) · supporting 1/2 · 7 reads · 2 outside the pack · context changed 2×
362
+ Context · Epoch 4 · primary read (docs/xxx.md) · supporting 1/2 · 7 reads · 2 outside the pack · context changed 2×
360
363
  ```
361
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
+
362
371
  It reports **facts only**: was the primary doc read, how many reads happened, how many fell outside
363
372
  the pack, how often the context changed. **No score, no percentage, no progress bar** — these numbers
364
373
  are counted, not estimated.
365
374
 
366
375
  Three boundaries:
367
376
 
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.
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.
370
380
  - **No duplicate of the DSH trajectory**: the only evidence source is the `tool/call` / `tool/result`
371
381
  events the session **already has** (successful `read`s). **No new event bus, no runtime trace,
372
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.
373
386
  - **Nothing is persisted**: the numbers live in kernel memory only and are gone after a DSH restart —
374
387
  do not treat them as long-term statistics.
375
388
 
@@ -439,7 +452,7 @@ The relevance figure only affects ordering — it is **never displayed and never
439
452
  git clone https://github.com/PolinniZhong/dsh-knit.git
440
453
  cd dsh-knit
441
454
 
442
- npm test # 395 tests, zero dependencies, no npm install needed
455
+ npm test # 468 tests, zero dependencies, no npm install needed
443
456
  ```
444
457
 
445
458
  **How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
@@ -460,9 +473,10 @@ knit/
460
473
  │ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
461
474
  │ ├── host/links.js # reference parsing (pure; never touches ranking)
462
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)
463
477
  │ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
464
478
  │ └── client/client.js # dual-host registration + panel UI
465
- └── test/ # 395 tests
479
+ └── test/ # 468 tests
466
480
  ├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
467
481
  └── context/ # context tiering: 24-doc corpus + 12 real-task cases
468
482
  ```
package/README.md CHANGED
@@ -11,13 +11,15 @@
11
11
  *引用条是 v0.12 加的:展开就能看到「这篇被谁引用」,点一项直接跳过去。*
12
12
  *顶行会跟着你正在聊什么变;对话内容还不足时它退回按时间排,并如实说明依据。*
13
13
  *v0.14 起文档列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
14
- *Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头的面包屑里**,列表行不再重复。*
14
+ *Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
15
+ *序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
16
+ *空着会被读成「漏了一个号」(2026-10-01)。*
15
17
 
16
18
  ![排序跟着对话走:发一句话,右侧栏的文档列表按这句话重排](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/demo-reorder.gif)
17
19
 
18
20
  *排序跟着对话走(同一个工作区、刚新开一个会话):还没聊什么时,顶行如实写着「对话内容还不足,暂按最新排序」,*
19
21
  *列表按时间排;问一句「排序算法用的 BM25 是怎么加权的?」,顶上立刻换成排序那几篇 ——*
20
- *序号与「主要上下文 / 辅助上下文 / 相关上下文」三层随之一起出现。*
22
+ *序号与「主要上下文 / 辅助上下文 / 相关上下文」三层随之一起出现(跨三档连续编号)。*
21
23
  *⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
22
24
 
23
25
  扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
@@ -164,7 +166,7 @@ dsh plugin --profile web add dsh-knit
164
166
  | 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
165
167
  | 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
166
168
  | 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
167
- | 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径面包屑**重复,只保留后者 | ✅ |
169
+ | 文档列表**永远单列**(v0.14 起,多列那套已整体删除);**序号在每行最左边独立成一列**(与标题第一行**垂直居中**),其余数据全在右边堆叠(右边第一行=Primary 点 + 标题 + 相对时间,**时间靠右**),摘要再往下;**列表行里不再有路径** —— 它和预览头那行可点的**路径**重复,只保留后者 | ✅ |
168
170
  | 单击就地展开预览,再点收起 | ✅ |
169
171
  | 相对路径图片真正渲染(`./img/a.png`、`../assets/b.png`) | ✅ |
170
172
  | **文档 / 图片与视频 / 全部** 三类一键切换(偏好记住,默认仍是文档,老体验不变);选中态是**中性灰填充**,不带品牌色描边 | ✅ |
@@ -172,11 +174,11 @@ dsh plugin --profile web add dsh-knit
172
174
  | 点图片 / 视频在面板内**就地预览**:图片大图、视频可播放可拖动(HTTP Range 流式,不全量下载) | ✅ |
173
175
  | 「全部」视图**分上下两区**:文档最多 4 条(超出给「查看全部 →」);图片视频**不截断**,只给计数 | ✅ |
174
176
  | 预览面板可拖高度(20%–80%,位置记住)、可全屏,`Esc` 退出 | ✅ |
175
- | **「在本地打开」**:用系统默认应用打开当前预览的这篇文档(预览头的路径面包屑同样可点) | ✅ |
177
+ | **「本地打开」**:用系统默认应用打开当前预览的这篇文档(预览头的路径同样可点,完整路径在悬停提示里) | ✅ |
176
178
  | 双击在新标签页打开(官方文档预览,带 PDF 渲染器与渲染方式切换) | ✅ |
177
179
  | 过滤框:按标题 / 摘要 / 路径实时过滤 | ✅ |
178
180
  | **点工作区路径**:用系统文件管理器打开项目文件夹 | ✅ |
179
- | **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局) | ✅ |
181
+ | **悬停入口按钮偷看**:弹只读浮层列最近 5 篇,点击才进右边栏(不推挤布局;浮层只有「头 + 列表」,没有多余的横线与提示语) | ✅ |
180
182
  | 键盘导航:`↑` `↓` 移动即预览 / `Enter` 切换 / `Esc` 收起;**媒体档** `←` `→` 按屏幕位置跨行,`Home` / `End` 到首尾(文档档永远单列,`←` `→` 没有空间含义) | ✅ |
181
183
  | 每 5 秒自动刷新 + 手动刷新;2 分钟内改动过的文档打 🆕 | ✅ |
182
184
  | 中英双语,跟随 DSH 语言实时切换(不用重载插件) | ✅ |
@@ -232,7 +234,9 @@ Context Pack 是对这个问题的回答,但它是**数据层的结构**(主
232
234
 
233
235
  > 示意图省掉了每行的摘要。**真实的行结构是:最左边独立一列=序号(与右边第一行**垂直居中**),
234
236
  > 右边堆叠=第一行「Primary 点 + 标题 + 相对时间(**靠右**)」→ 摘要(**没有路径** ——
235
- > 列表行里不显示它,路径在预览头的面包屑上)。而且这个列表**永远是单列**(面板拖到多宽都一样)。
237
+ > 列表行里不显示它,路径在预览头上、目录收敛成 `…/`)。而且这个列表**永远是单列**(面板拖到多宽都一样)。
238
+ > 「其他相关文档」不在包里、不编号,那一列放一个中性的 `·` 占位 —— 但只在**这一屏里有号**时才放
239
+ > (时间序 / 平铺列表整屏没号 ⇒ 一个标记都没有;混着才刺眼)。
236
240
 
237
241
  **分组之间不画横线**:层级靠 16px 的空间、组名与字号建立,不靠分割线。
238
242
  分组里没有分数、没有百分比、没有星级 —— 「为什么在这里」只写**确定性的事实**。
@@ -313,26 +317,36 @@ Knit 一装上就有整个项目的历史文档可用。
313
317
 
314
318
  ---
315
319
 
316
- ## 它有没有被用上(v0.15)
320
+ ## 它有没有被用上(v0.16)
317
321
 
318
322
  Knit 会排出「现在最该先看的几篇」,但**排得对不对,过去只能靠感觉**。
319
- v0.15 加了一层**可核验的使用反馈**:把 agent 真实读过的文件,跟**读发生那一刻**生效的那份上下文对起来。
323
+ v0.15 起有一层**可核验的使用反馈**:把 agent 真实读过的文件,跟**读发生那一刻**生效的那份上下文对起来。
324
+ v0.16 把这件事钉死:**归因在读发生那一刻结算并冻结** —— 之后上下文怎么换,历史数字都不会改口
325
+ (v0.15 里同一个读会被「现在」重判成包外,那是 bug)。
320
326
 
321
327
  **默认关。** 面板头部有一个「使用情况」开关,打开之后列表上方会多一行字:
322
328
 
323
329
  ```
324
- 先看的「docs/xxx.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次
330
+ 当前上下文 · Epoch 4 · 先看的「docs/xxx.md」已读 · 辅助 1/2 · 读了 7 次 · 包外 2 篇 · 上下文换过 2 次
325
331
  ```
326
332
 
333
+ - **Context Epoch**:一份**内容有变化**的上下文 = 一个 Epoch(内容没变就不新建,轮询不会灌进几十个)。
334
+ `Epoch 4` 是累计编号,不是「第几份包」。
335
+ - **两个只记事实的字段**:`continuedReadAfterExit`(离开这份上下文之后它仍然被读)、
336
+ `reEntry`(离开过、又回到包里、又被读)。它们**不许**被读成「Agent 不认可新上下文」——
337
+ 那是推断,不是事实。
338
+
327
339
  它只报**事实**:先看的那篇被读了没有、读了几次、多少篇落在包外、上下文换过几回。
328
340
  **没有分数、没有百分比、没有进度条** —— 这些数字不是估算出来的,是数出来的。
329
341
 
330
342
  三条边界:
331
343
 
332
- - **默认关闭**:不打开就**不读一个事件、不攒一条数据**。这笔账是有代价的
333
- (每次轮询都要读一遍会话事件),该由你决定要不要付。
334
- - **不重复 DSH 的轨迹**:证据只有一个来源 —— 会话里**已经存在**的 `tool/call` / `tool/result`
335
- 事件(成功的 `read`)。**没有新的事件总线、没有 Runtime Trace、也没有 Event Store。**
344
+ - **默认关闭**:不打开就**不统计任何东西**(Knit 订阅宿主事件流,但回调第一行就按会话早退,
345
+ 没开审计的会话只花一次 Map 查找)。这笔账该由你决定要不要付。
346
+ - **不重复 DSH 的轨迹**:证据只有一个来源 —— 会话事件流里**已经存在**的 `tool/call` /
347
+ `tool/result` 事件(成功的 `read`)。**没有新的事件总线、没有 Runtime Trace、也没有 Event Store。**
348
+ - **只从现在开始**:订阅是 v0.16 唯一的读证据来源(旧的 `session.snapshotEvents()` 已被 DSH
349
+ 标为 deprecated),所以**打开开关之前发生的读不会回补** —— 那一刻起才开始计数。
336
350
  - **不落盘**:数据只在宿主内存里,重启 DSH 就没了,**别把它当长期统计**。
337
351
 
338
352
  agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工具结果末尾会多一行
@@ -398,7 +412,7 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
398
412
  git clone https://github.com/PolinniZhong/dsh-knit.git
399
413
  cd dsh-knit
400
414
 
401
- npm test # 395 项,零依赖,不需要先 npm install
415
+ npm test # 468 项,零依赖,不需要先 npm install
402
416
  ```
403
417
 
404
418
  **改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
@@ -419,9 +433,10 @@ knit/
419
433
  │ ├── host/relevance.js # 相关性引擎:BM25 + 关键词抽取(纯函数)
420
434
  │ ├── host/links.js # 引用关系解析(纯解析,不碰排序)
421
435
  │ ├── host/context.js # 上下文装配:Context Pack 三层(纯函数,零 I/O)
436
+ │ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
422
437
  │ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
423
438
  │ └── client/client.js # 双宿主注册 + 面板 UI
424
- └── test/ # 395 项测试
439
+ └── test/ # 468 项测试
425
440
  ├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
426
441
  └── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
427
442
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-knit",
3
- "version": "0.15.0",
3
+ "version": "0.16.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",
@@ -23,7 +23,7 @@
23
23
  "LICENSE"
24
24
  ],
25
25
  "scripts": {
26
- "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 test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs"
26
+ "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 test/feedback.test.mjs test/context-delta.test.mjs test/context-feedback-eval.test.mjs test/context-effectiveness.test.mjs"
27
27
  },
28
28
  "dsh": {
29
29
  "bundle": {