dsh-knit 0.15.0 → 0.17.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,386 @@
3
3
  本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
4
4
  版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
5
5
 
6
+ ## [0.17.0] - 2026-10-03
7
+
8
+ > 🚧 **尚未发布**:工作树 = `0.17.0`(`knit/package.json`),未打 tag、未 publish。
9
+ > 发布后把这一行补成 `✅ **… 已发布**:v0.17.0 = <sha> · npm latest = 0.17.0(<n> 文件 / <size> / shasum …)`。
10
+
11
+ **Document Lifecycle(依据 `01_ Knit PRD/Knit-PRD-SDD-v0.17-Document-Lifecycle.md`)**:
12
+ 前面几版回答的是「Knit 推荐了什么 → Agent 有没有读 → 读落在哪一层」;
13
+ 这一版接着回答**一篇文档读完之后,现在处于什么状态**。
14
+ 只做四件事:文档状态、最近读取、包外读取的明细、最近一次 Context Delta。
15
+ 检索侧一行没改(BM25 / IDF / 关键词抽取 / 长度归一化 / freshness / 分层 / Context Pack 装配规则一个字没动),
16
+ **没有分数、没有百分比、没有进度条、没有时间线、没有新面板、没有第二份存储**。
17
+
18
+ ### 新增:四个事实状态
19
+
20
+ | 状态(数据层) | 界面文案 | 判据 |
21
+ |---|---|---|
22
+ | `unread` | 未读 | 本会话没有一次成功 `read` |
23
+ | `read` | 已读 / 已读 ×N | 有过成功 `read`,且最后一次成功读取之后文件版本标记没变 |
24
+ | `updated_after_read` | 读后已更新 | 最后一次成功读取之后,文件的 `mtimeMs` 变过 |
25
+ | `reread_after_update` | 修改后已重新读取 | 变过之后又成功读过一次;再变一次就退回上一档 |
26
+
27
+ 判据复用现有工作区扫描拿到的 `mtimeMs`:`src/host/index.js` 里的 `mtimeOf(root, rel)` 做一次 `statSync`,
28
+ 在 `tool/call` 那一刻把结果交给 `ingestEvents(..., { stat })`,`feedback.js` 自己不碰 I/O。
29
+ **不引入内容哈希、不扫描全文、不新增索引、不落盘。**
30
+
31
+ 事实就是事实,不做推断:状态只说「文件在上次成功读取之后变过 / 变过之后又读过」,
32
+ 不写「Agent 还不知道最新版」「Agent 没看到你的修改」这类话(测试里钉死了这些词不出现)。
33
+ `grep` / `glob` / `bash` 不算 `read`;失败的 `read` 不算;拿不到当前 `mtimeMs` 或没记过
34
+ `lastReadMtimeMs` 时**不下结论**(宁可停在 `read`);文件只是被重新扫描过,不等于被重新读过。
35
+
36
+ ### 新增:最近读取 / 包外明细 / 最近一次变化
37
+
38
+ - **最近读取:`<rel>` · <相对时间>** —— 最近一次**成功 `read`** 对应的文件,按事件 `seq` 判定「谁最近」,
39
+ 墙钟只负责显示相对时间;它落在 Context Pack 之外也照实显示。
40
+ **不叫「正在阅读」**:Knit 无法证明 Agent 此刻还在读这篇。
41
+ - **上下文外读取 · N 篇**(可展开)—— 原来只有一个数字,现在点得开、看得到是哪几篇,
42
+ 每行给 `rel` 和该篇的状态。只表达「这篇不在当前 Context Pack,但 Agent 确实成功读过它」;
43
+ 不写「Knit 漏掉了 / 推荐错了」,也不做漏召回率、命中率、Context 质量。
44
+ - **上下文刚刚变化**(只展示**最近一次** Delta)—— `+` 进入 / `-` 离开 / `↔` 换层(层名用短名),
45
+ 折叠时最多三行,展开按「进入 / 离开 / 换层」分组;`taskChanged` 只说一句「任务上下文已更新」。
46
+ 不产出时间线,也不做事件浏览器。
47
+
48
+ ### 数据层:扩现有 store,不加第二套
49
+
50
+ `src/host/feedback.js` 新增三个纯函数(`lifecycleOf(entry, mtimeMs)` / `latestReadOf(reads)` /
51
+ `outsideDocsOf(reads, items)`),`recordRead()` 每篇多冻三个标量
52
+ (`lastReadMtimeMs` / `prevReadMtimeMs` / `rereadAfterChange`);
53
+ `usageFrom(state, { mtimes })` 的返回值**顶层**多四个字段
54
+ (`lifecycle` / `recentRead` / `outsideDocs` / `latestDelta`),v0.16 的 `stats` 15 个键一个没动。
55
+ `/api/recent?usage=1` 用工作区扫描的全量列表(未截断)算 `mtimeMs`,
56
+ 只回传当前文档列表 + 包外文档的状态行,每篇三字段(`status` / `count` / `lastReadAt`)。
57
+
58
+ 历史归因继续冻结:`tier` / `rank` / `inside` / `epochId` 仍是**读发生时**那一份 Context 的结算值,
59
+ 不会因为「现在」换了包而改口(v0.16 的行为原样保留)。
60
+
61
+ `knit_docs` 工具的**输出没有变**:它仍然只负责「找上下文」,不输出生命周期报告
62
+ (工具描述与工具结果都要吃模型上下文,这一版的主要消费者是人)。
63
+
64
+ ### 修订(真机验收):闸门开晚也要说真话
65
+
66
+ 验收时暴露一个来回:先让 Agent 读了一篇文档、**之后**才打开使用情况开关 —— 那两次读发生在订阅
67
+ 回调开始按会话早退之前,事件根本没进过内存,于是面板把一篇**确实已经读过**的文档显示成「未读」。
68
+ 那不是解析错误,是**没有证据**:闸门打开之前,Knit 一条读都没看见,却对「未读」下了断言。
69
+
70
+ 修订:闸门打开的那一刻,宿主**回填一次**本会话已有的事件(`src/host/index.js` 的
71
+ `backfillFeedback()`,由 `activateFeedback()` 在面板与工具两条开闸路径上调用;一个会话只回填一次、
72
+ 只在当前这一 tick,零 I/O、零网络、零模型)。**顺序是这个机制的组成部分**:先把手上那份 Context Pack
73
+ `noteSnapshot()` 记下、**再**喂事件 —— `recordRead()` 在事件入库那一刻就把归因冻结,先喂事件的话,
74
+ 补记的读会在「一份快照都还没有」的状态下被判成包外,而「这篇不在当时的上下文里」是一句我们并不知道
75
+ 真假的话(§6)。回填那次不传 `at`,于是这份「会话开头」快照的 `at` 仍是 0,第一次 `usage.at` 的语义
76
+ (还没有上一份包)不变。`session.snapshotEvents()` 的 deprecated 提示仍然有效:这是**闸门打开那一刻的
77
+ 唯一例外**。
78
+
79
+ 已知不精确,写在明面上:回填的读按**我们已知最早的那份包**归因,更早的包 Knit 无从得知。
80
+
81
+ ### 界面
82
+
83
+ - 文档行在标题与时间之间多一个弱化状态文字,只在**使用情况打开 + 分层视图**里出现;
84
+ 标题仍是视觉主体,状态不用红绿、不加重、不给分。
85
+ - 使用情况那一行下面多三块极轻的东西:最近读取、`上下文外读取 · N 篇`(可展开)、`上下文刚刚变化`(可展开);
86
+ 折叠状态存在组件本地,不写进偏好。既有的「使用情况」行一个字没改。
87
+ - **使用情况默认关**:关着时 `usage=1` 不发、宿主不初始化生命周期、DOM 里**零新增节点**(测试钉死)。
88
+
89
+ ### 新增:列表进出动效(2026-10-03 用户拍板)
90
+
91
+ 验收时用户提的:「新读取跟挤掉旧的未读的,这里的交互可能要优化,因为现在是一闪一闪的,就非常的快…
92
+ 从当前的、如辅助上下文中新增,它应该是从低向上的…消失的时候从上到下,渐隐掉」。做的还是同一件事,
93
+ 只是把它**看得见**:一行文档被读到、换了层、被挤出列表时,不再是「瞬间落位」。
94
+
95
+ - **进来**:从下方 26px 处淡入上浮(高度 0 → 量出来的自然高度、`blur(3px)` 收敛到 0);
96
+ 同一拍里多篇按屏幕顺序错开 45ms,**最多错 6 档**(一次涌进十几篇时不排长队)。
97
+ - **出去**:先把自然高度量下来,再把高度收到 0、**自上而下**擦除
98
+ (`clip-path: inset(T 0 0 0)`,T 从 0 到 100%)并渐隐;这一行留在列表里把动画播完才移除,
99
+ 否则看起来像「跳到末尾才消失」。它插回的位置由上一帧的 `index` 决定(`mergeGhostRows()`)。
100
+ - **换层 / 重排**:走 **FLIP**(同一篇 `rel` 在新旧两帧都在 ⇒ 既不算进入也不算离开,
101
+ 交给位置补间)。这一行的节点在跨分区时会被 React 重建,所以位置按 **`rel`** 记,
102
+ 老节点量到的矩形照样能用在新节点上:先把它从老位置拉回来(`transform: translate(dx, dy)`)
103
+ 再补到归位(340ms),于是「从包外升进 Primary」看起来是**飞上去的**,不是瞬移。
104
+ 它跑在提交之后、绘制之前的 layout effect 里,且在 `DocRow` 的进 / 出补间**之后**
105
+ (React 是子先父后):那一刻新行已经是 0 高、幽灵行还占着原高度,所以量到的位移只剩
106
+ 「真的挪了位置」的行,不会和进 / 出补间算两遍;正在进 / 出的行直接跳过。
107
+ 位移小于 0.5px(含浏览器缩放 / 滚动的亚像素抖动)算没动过,否则整屏会一直在微微地飘。
108
+ - **什么时候不播**:首屏、换类型 / 换排序 / 搜索词变了(那是「换屏」、不是「来了新的」),
109
+ 以及系统开了「减弱动态效果」(`prefers-reduced-motion: reduce`,连底色过渡一起去掉)。
110
+
111
+ 两条硬约束:**补间在 JS 里走 WAAPI(`Element.animate`),CSS 里只有两笔静态规则**
112
+ (`.knit-doc.leaving` 与减弱动态效果那条媒体查询)—— 高度必须按量出来的自然高度补间,
113
+ 写几个 `@keyframes` 会在动画收尾的瞬间跳一行间距。`motionAllowed()` 在没有 `document`、
114
+ 没有 `Element.prototype.animate`、或系统要求减弱动态效果时返回假,于是宿主进程与测试进程里
115
+ **一行补间都不排、也不造幽灵行**:渲染树与没有这段动效时逐字一致
116
+ (`planRowMotion()` / `mergeGhostRows()` 都是纯函数,测试直接喂数据)。
117
+
118
+ ### 测试
119
+
120
+ - 新增 `test/document-lifecycle.test.mjs`(24 例):四档状态、缺 mtime 不下结论、失败 `read` 不计、
121
+ `grep` / `glob` / `bash` 不计、按 `seq` 判最近读取、包外明细与排序、历史归因不漂移、
122
+ 同一事件重复派发幂等(`count` 只 +1,且不重采样 mtime);另有 4 例钉住**开闸回填**
123
+ (补记的读归「会话开头那份包」⇒ 不再被误判成包外、只影响第一份快照、重复派发仍幂等)。
124
+ - `test/host-http.test.mjs` 多 3 例端到端:`usage` 顶层新字段与 `stats` 形状不变;
125
+ **真改盘上 mtime** ⇒ 读后已更新,再读一次 ⇒ 修改后已重新读取;
126
+ 面板开晚的会话在开闸那一刻**回填**已有的成功读(`reads=1`、`firstReadTier='primary'`、`outside=0`),
127
+ 且一个会话只回填一次(再请求一次仍是 1)。
128
+ - `test/client.test.mjs` 多 19 例:四档渲染、标题 / 状态 / 时间顺序、最近读取的相对时间、
129
+ 包外折叠与展开、Delta 摘要与分组、溢出与 `taskChanged`、只用语义 token、英文环境无汉字;
130
+ 关着时零新增节点;另有 7 例钉住**进出动效**只在真机上播 —— 首帧与「换屏」都不播、
131
+ 交错按屏幕顺序且封顶、离开的行带着原有的区与位次、同一篇换层既不算进也不算出、
132
+ 幽灵行插回原位(含「还活着的不造幽灵」与「别的区不插」)、Node 里恒被 `motionAllowed()` 挡掉、
133
+ CSS 里没有 `@keyframes`(只有 `.knit-doc.leaving` 与减弱动态效果那条媒体查询);
134
+ 另有 3 例钉住**换层 / 重排的 FLIP** —— 位移的正负与阈值(亚像素抖动不算动)、
135
+ 给挪过位置的幸存行排一段 `translate(dx,dy) → 0`(进 / 出的行跳过、位置表跨帧传递、
136
+ 节点不认 WAAPI 时只记位置不抛错),以及那行 `applyRowFlips(...)` 确实接在提交之后。
137
+ - `test/i18n.test.mjs` 多 1 例:16 条新文案中英逐条对齐,且状态文案里不出现推断词。
138
+ - `npm test`:**517/517 通过**(v0.16 是 468,新增用例 49 条)。
139
+
140
+ ### 修好:交互审的两处「列表自己跳」(2026-10-04)
141
+
142
+ **用户报了两件事**:①「我选中一个文档查看全文,特别是在最下方的文档,相关联文档,我一点它就跳,
143
+ 我一点它就很跳,闪的很快」;②「我刚刚重启 DeepseekHarness,我没有输入任何的对话……
144
+ 我们的文档列表就开始跳动,它怎么能够切换呢」。**先按数据查**:同一会话连续打 5 次
145
+ `/knit/api/recent` 返回逐字一致 ⇒ 服务端不抖,四个根因全在**客户端几何 / 时序**:
146
+
147
+ | 症状 | 根因 | 修法 |
148
+ |---|---|---|
149
+ | 点一下就跳 | 预览面板用 `maxHeight: 46%` ⇒ 面板高度由**内容**决定(「加载中」→正文、预览里换一篇都变高矮) | 打开期间高度**固定**成拖出来的比例;长文在正文区里滚,短文档下方留白是代价 |
150
+ | 整屏乱飘 | FLIP 拿 `getBoundingClientRect()`(**视口坐标**)当位置:容器滚动 / 容器变高矮 / 行上 `:hover{transform:translateX(-2px)}` 都凭空造出位移 | 改用**布局坐标** `offsetTop` / `offsetLeft`(`rowLayoutPoint()`) |
151
+ | 越补越飘 | 换屏与进 / 出补间**在飞的那几百毫秒里**也照量位置,量到中间态,落地后又被当成「挪了位置」 | 这两种时候**一个都不量**,并把位置表清空 |
152
+ | 空会话自己跳 | 「光标跟手滚进视口」的依赖里有 `state.docs`(每 5 秒一个新数组)⇒ 把「刷新到数据」当成「用户按了方向键」,光标默认在第一行,用户往下滚过之后每 5 秒被拽回去一次 | 依赖只剩 `[cursor, query]`,且只在列表自己拿着键盘焦点时才滚 |
153
+
154
+ 四条都在源码注释里逐条写着「为什么」;两条硬规则进了 `AGENTS.md` §6.13,教训进了 §8.12。
155
+ 测试 515 → **517**(`test/client.test.mjs` 多 2 例:`rowLayoutPoint` 的布局坐标优先与兜底分支、
156
+ 「刷新不许动列表」= 那条 effect 的依赖里没有 `state.docs`;`test/tier1.test.mjs` 那条预览高度的断言
157
+ 从 `maxHeight` 改成 `height` + 断言 `maxHeight === undefined`)。
158
+
159
+ ## [0.16.0] - 2026-10-01
160
+
161
+ > ✅ **2026-10-03 已发布**:`v0.16.0` = `8c3ca2c` · npm `latest = 0.16.0`(42 文件 / 341.8 kB / shasum `771705d6…`)。
162
+ > 这一版把上一节那批「未发布」的界面收敛**一起**带上。
163
+
164
+ **Context Effectiveness(依据 `01_ Knit PRD/SDD-v0.16-Context-Effectiveness.md`)**:
165
+ 一次读落在哪一层,**在读发生那一刻结算并冻结**;并正式引入 **Context Epoch**。
166
+ 检索侧一行没改(BM25 / IDF / 分层 / Context Pack 装配规则一个字没动),
167
+ **没有分数、没有百分比、没有新面板**。
168
+
169
+ ### 修好:历史归因会被「现在」改口(split-brain)
170
+
171
+ v0.15 里「这次读落在哪一层」被算了两遍:读入库那一刻算一遍(`recordRead()` → `snapshotAt()`,
172
+ 冻进 `firstTier`),出报告那一刻又拿**最新**那份快照重算一遍(`usageFrom()`)——
173
+ `byTier[].read` / `outside` / `supportingCoverage` / `firstReadTier` 全吃重算值。
174
+ 于是同一条读可以同时是 `firstTier='primary'` 与 `tier='related'`。真实场景就是:
175
+
176
+ ```
177
+ 10:00 交 Context A(primary = A.md)→ 10:01 读 A.md → 10:03 换 Context B → 10:04 看 usage
178
+ ⇒ A.md 被算成「包外」—— 历史被现在改口了。
179
+ ```
180
+
181
+ 现在只有一条规则,由 `src/host/feedback.js` 的两个纯函数说了算:
182
+
183
+ | 函数 | 语义 |
184
+ |---|---|
185
+ | `snapshotAt(snapshots, readSeq)` | 取 `seq <= readSeq` 的**最新**快照 = 读发生时生效的那一份 |
186
+ | `attributeRead(snapshot, rel)` | 输出 `{ snapshotSeq, epochId, tierAtRead, rankAtRead, insideAtRead }`,读时冻结 |
187
+
188
+ `recordRead()` 在读那一刻调它并冻进 `firstRead` / `lastRead`;`usageFrom()` 只读冻结值。
189
+ `reads[]` 行上的 `tier` / `rank` / `outside` 也一律是**首读**的归因(不再是「它现在在哪一层」),
190
+ 旧字段名(`firstTier` / `firstReadAt` / `outsideCount` …)与旧键 `churn.snapshots` 全部保留为兼容别名。
191
+
192
+ ### 修好:右栏收起之后,Knit 还在每 5 秒敲一次宿主
193
+
194
+ **现象(2026-10-01 用户报)**:一旦点开过文件、再把右栏那一栏关掉或收起来,过一会儿它会变成
195
+ **一片空白** —— 没有芯片、没有文字,也没有「这类内容还没有可用的查看方式」。
196
+
197
+ **查到的**:官方右侧栏收起时**不卸载**标签身体(dockkit 的 `keepMounted`),而 `KnitBody` 的轮询
198
+ 过去只看「挂载了没有」——于是收起来之后照旧每 5 秒请求一次 `/knit/api/recent`(一次全工作区扫描)
199
+ 并 `setState`,等于往宿主正在收起 / 展开的那棵子树上又插了一帧重渲染。
200
+ 实测(headless Chrome 里的真客户端):收起状态 12 秒里发了 **2 次**请求;那一栏确实还在
201
+ `visibility:hidden` 里挂着(`knitVisible.visibility === 'hidden'`、`knitRoot === true`)。
202
+
203
+ **修法**:用座位契约里现成的 `tab.visible` 做闸门。官方在
204
+ `@deepseek-ai/dsh-client-ui-sidebar-right` 里算的是
205
+
206
+ ```js
207
+ visible: active && (pane.host === 'float' || layout.expanded && (title || pane.activeTabId === tabId))
208
+ ```
209
+
210
+ 也就是「收起」与「不是当前标签」两种情况都是 `false`。座位适配层把它传给 `KnitBody`:看不见时
211
+ **连请求都不发**,在途的那次回来也不落状态;`visible` 变回 `true` 时那个 effect 会重跑 ⇒
212
+ **立刻补一次**,不必等下一个 5 秒。
213
+
214
+ - 实测(同一台真客户端):收起 13 秒 **0 次**请求(修前 2 次);重新展开 7 秒内 **2 次**(立刻 + 5 秒那次)。
215
+ - 拿不到 `tab.visible` 时(别的宿主 / 降级路径)**当作看得见**,不会把面板冻住。
216
+
217
+ ### 修好:右侧栏「开始」页出现两行一模一样的入口
218
+
219
+ **现象(2026-10-01 用户报)**:右侧栏「开始」页上有两行同名胶囊(都是「Knit 最近文档」),
220
+ 点哪一行都进 Knit。
221
+
222
+ **查到的**:`dsh-better-sidebar` v0.24.1 起有个「原生表面」——把它自己每个 tab descriptor
223
+ 镜像成官方右侧栏的一个类型(`id = dsh-better-sidebar:<descriptor.id>`、`kind = descriptor.id`),
224
+ 并且**在 descriptor 没写 `hidden` 时连带注册一条 guide 条目**:
225
+
226
+ ```js
227
+ ...descriptor.hidden === true || isEditor ? {} : { guide: [{ id: descriptor.id, order: descriptor.order ?? 100, … }] }
228
+ ```
229
+
230
+ 于是「开始」页同时挂着 ① 我们自己的类型(`kind: 'knit'`)与镜像(`kind: 'knit:recent'`),
231
+ 标题都取 `guide.title` ⇒ 两行同名。(并不是 Knit 注册了两次。)
232
+
233
+ **修法**:给 `ctx.betterSidebar.registerTab` 的 descriptor 加 `hidden: true`。它只掐掉那一条镜像
234
+ guide 条目(连带 + 菜单项),镜像的类型 / 座位 / `ctx.betterSidebar.openTab` 都还在;入口保留 ①
235
+ 那条 —— 不依赖宿主装没装 better-sidebar。
236
+
237
+ - 实测(真客户端 + 刷新):修前 5 条胶囊里两条 Knit;修后只剩 `data-sidebar-right-guide-entry="knit"` 一条,
238
+ 点它照旧开 `tab8`「Knit」。
239
+
240
+ ### 新增:Context Epoch
241
+
242
+ - **一份快照 = 一个 Epoch**:`epochId` 从 1 开始,**内容真的换了才 +1**
243
+ (签名 = `task` + 三层 `tier:rank:rel`,与 v0.15 同一套判据)——5 秒轮询不会灌进几十个 Epoch。
244
+ - **`usage.epochs[]` 与快照栈同生共死**:每项 `{ epochId, snapshotSeq, topic, task,
245
+ primary/supporting/related: { rel|total, read }, outsideReads, continuedReadsAfterExit, reEntries }`。
246
+ **只供内部 / 离线回放 / 将来的评估** —— v0.16 不把它上任何工具输出。
247
+ - 保留上限:`MAX_SNAPSHOTS_PER_SESSION` **2 → 20**、`MAX_DELTAS_PER_SESSION` **20 → 50**。
248
+ 归因在读时结算,保留数量只决定「离开 / 重新进入」能回溯多远(**宁可漏记,也不猜**)。
249
+ - `churn` 口径:新增 `epochs`(换过几个不同的上下文 = 最后一份的编号),`changes = epochs - 1`;
250
+ 客户端在用的 `snapshots` / `deltas` 保留为 `changes` 的别名(文案「上下文换过 N 次」不变)。
251
+
252
+ ### 新增:两个事实字段(只记事实,不加解释)
253
+
254
+ | 字段 | 判据(只在保留窗口内推导) |
255
+ |---|---|
256
+ | `continuedReadAfterExit` | 这次读**在当时那份快照之外**,且更早的某份快照里有这篇 |
257
+ | `reEntry` | 这次读**在当时那份快照之内**,更早的某份快照里也有,但中间至少有一份没有它 |
258
+
259
+ ⚠️ 它们**不许**被读成「Agent 不认可新上下文」——那是推断,不是事实(SDD §5 Evidence Over Interpretation)。
260
+ `firstReadTier` 多一个取值 `'outside'`(读过、但读在包外);`null` 只留给「一次都还没读」。
261
+
262
+ ### 改法:读证据不再拉会话事件,改成订阅 `session/event`
263
+
264
+ `session.snapshotEvents()` 已被 DSH 标为 deprecated(`dsh-session/README.md:62`:
265
+ "new production calls are prohibited")。v0.16 把读证据的来源换成宿主事件流:
266
+
267
+ - `apply(ctx)` 顶部 `ctx.on('session/event', onSessionEvent, { global: true })`;回调首行按 `session.id`
268
+ **早退** —— 没开审计的会话只花一次 Map 查找,不建快照、不统计、不进内存。
269
+ - `ingestEvents(store, sessionId, [event], { root })` **单事件**入库;游标幂等不变。
270
+ - **两个行为变化**:① 订阅之前发生的事**不再回补**(不碰废弃 API 就读不到历史)——
271
+ 打开「使用情况」的那一刻起才开始计数;② fork 出来的会话**不再把父会话继承的读算进自己账上**
272
+ (seed 事件不派发;v0.15 从 `state.seq = -1` 拉全量时会算进去)。
273
+
274
+ ### 界面:只多一句「当前上下文 · Epoch N」
275
+
276
+ 不加 Dashboard、不加图表、不动布局;开关打开后那一行**开头**多一个累计编号,其余逐字不变。
277
+
278
+ ### 量尺
279
+
280
+ `tools/context-feedback-eval.mjs`:日志文件名改成**按形状认**(`session.v<N>.jsonl[.zstd]`,
281
+ v0-v4 三代并存都能读,以前写死 v4);`metricsFor()` 增 `epochs` / `continuedReadsAfterExit` / `reentries`、
282
+ `contextChanges` 改读 `churn.changes`;Control 自检的判据放宽成「不许有**落在层里**的读」
283
+ (`'outside'` 在对照组是正常的)。
284
+
285
+ ⚠️ **对齐的是规则,不是数字**:离线量尺与 runtime 共用同一份归因(都调 `feedback.js`),
286
+ 但**交付时刻**不同 —— 面板轮询 / 工具调用是采样,量尺是「每次读前合成一份包」。
287
+ 逐字段一致是**规则**级;数字级对齐做不到(SDD §3 G4 已据此改名并写明原因)。
288
+
289
+ ### 测试
290
+
291
+ - 新增 `test/context-effectiveness.test.mjs`(12 条):历史归因(§24.3)、离开后仍被读(§24.4)、
292
+ 重新进入(§24.5)、**规则一致**(§24.6:runtime 记下的归因逐字段等于 `snapshotAt()` +
293
+ `attributeRead()` 现算的结果)、Epoch 边界与上限。
294
+ - `test/context-delta.test.mjs` 里那条钉着 split-brain 的双轨断言(`firstTier='primary'` 与
295
+ `tier='related'` 同时成立)改写成「`tier` 也是首读的归因」。
296
+ - `test/host-http.test.mjs` 的「使用情况」整段改成**事件驱动**(假 ctx 收 `session/event` 派发),
297
+ 顺带覆盖:订阅前的事件不回补、同一 seq 派发 10 次仍只算一遍、畸形事件不影响接口。
298
+ - 测试数:**453 / 453 → 468 / 468**。
299
+ - `test/client.test.mjs` 新增 2 条**可见性**用例:`visible === false` 时一次都不取数、也不挂轮询;
300
+ 座位契约的 `tab.visible` 一路传到 `KnitBody`(拿不到 `useTabInfo` 时按「看得见」处理)。
301
+
302
+ ## [0.15.1] - 2026-09-30 · 并入 0.16.0
303
+
304
+ > ⚠️ 这一版**没有单独发布**(未打 tag、未单独 publish),**并进了 v0.16.0**(见上一节)——
305
+ > 下面这批界面收敛随 `0.16.0` 一起发出。
306
+
307
+ **界面收敛 + 一处真机修复**:没有新指标、没有新接口,BM25 一行没改,Context Pack 的装配规则一行没改。
308
+
309
+ 用户看过 v0.15 的真实界面之后提了五处收敛(2026-09-30),共同点是同一条审美主张 ——
310
+ **能用空间表达的层级,就别再画线**:
311
+
312
+ | 改动 | 说明 |
313
+ |---|---|
314
+ | **排序说明那一行整行删除** | 列表上方 `.knit-topic`(`Sorted by relevance` / `按修改时间倒序`,以及它 `title` 里的命中关键词)**整行删掉**:排序方式已经由「相关 / 最新」切换按钮自己表达,再写一行是重复。随之把 `topic.relevancePlain` / `topic.relevanceTerms` / `topic.needsConversation` / `topic.time` 四个文案键从**两种语言里一并删掉**(不为「以后可能用」留着),客户端那份因此变成死代码的 `topic` state 也清了(初始化 + 三处错误分支 + payload 赋值共 5 处) |
315
+ | **类型行不再画全宽底边** | `.knit-types` 的 `border-bottom` 删除 —— 层级只由选中页签自己那条 2px 下划线表达(**那条保留**,用户明确说删的不是它) |
316
+ | **列表行不再有描边** | `.knit-doc` 静止态那条 `.5px solid transparent` 占位、悬停与选中各自上的 `border-color` 三处一起删;「正在预览」只剩灰底,灰底成为唯一的分层信号。⚠️ 边框删了要用 `padding:10px 11px → 10.5px 11.5px` **把几何补回来**,否则每行矮 1px、左右各窄 .5px |
317
+ | **引用区上下两条细线都删** | 预览头的 `border-bottom: .5px border-l3` 与引用条的 `border-bottom: 1px border-l2` 一起删(38px 头部高度保留,排版不动,只是不画线)。这两条线把「被引用」夹在中间,视觉上割裂 |
318
+ | **过滤框提示简化** | `过滤标题 / 摘要 / 路径` → **「过滤文档」**(英文 `Filter title / summary / path` → `Filter docs`):不列字段清单,字段范围由行为本身说明 |
319
+
320
+ ### 修好:悬停浮层永远显示「0 篇」
321
+
322
+ 真机上对话头部右侧那个 Knit 图标,悬停后浮层只有「**0 篇 / 这个工作区里还没有 Markdown 文档。**」,
323
+ 可面板里同一个工作区的文档一切正常。根因**不在列表逻辑,而在取「当前会话 id」的方式**:
324
+
325
+ - 入口按钮坐在 `conversation.session.header.utilities` 这个 **session 作用域**的座位上,框架通过
326
+ **标准 props 直接把当前会话 id 递进来**(`SessionStandardProps.sessionId`,由 `dsh-client-ui-session`
327
+ 以 `props: ["sessionId"]` 注入;座位契约也写明「Header actions derive their state from standard Session props」)。
328
+ - Knit 从 v0.5.0 起读的却是 `ctx.sessions.list` 快照里的 `snapshot.current` —— **现行契约里没有这个字段**:
329
+ `SessionListState` 只有 `{ ids, byId, phase, projectionsBySession }`,契约注释是
330
+ 「navigation belongs to view owners」。⇒ 恒取到空串 ⇒ 每次都走「没有当前会话」分支 ⇒ 空态。
331
+
332
+ 改法:**座位 props 的 `sessionId` 优先**,取不到时才退回老读法(`snapshot.current`,给更老的内核兜底)。
333
+ 「点浮层里某一篇直接展开它的预览」这条通路一直是好的,只是列表为空时点不到 —— 会话 id 一恢复它就回来了。
334
+
335
+ ⚠️ **测试为什么没拦住**:`test/peek.test.mjs` 的假上下文把 `sessions.list.getSnapshot()` 假成了
336
+ `{ current: 's-1' }` —— 一个现行内核里根本不存在的字段,于是 450 条测试全绿、真机上永远是空态。
337
+ 现在假件照着契约写成 `{ ids, byId, phase, projectionsBySession }`,**当前会话 id 一律走座位 props**,
338
+ 并新增两条回归用例:① 座位 props 生效(快照里没有 `current` 也要照常拉列表);② 老内核退回 `current`。
339
+
340
+ 测试侧同步改了钉住这五条的断言,并把**「删除」本身写成防回潮断言** —— 新增一条用例守着:
341
+ 那三处描边、两条分割线、那一行的类名、四个文案键,**只要回来就红**。
342
+ 测试数:**453 / 453**(合并两条 i18n 用例、新增一条防回潮用例、上述两条会话 id 回归用例,
343
+ 再加下面这条「占位标记」用例)。
344
+
345
+ 顺带修掉 `knit/README.md` / `knit/README.en.md` 里两处陈旧数字:`395 项测试` → `450`(v0.15.0 时漏改),
346
+ 并在目录树里补上 v0.15.0 就存在、却一直没列出的 `src/host/feedback.js`。
347
+
348
+ ### 改动:没序号的行不再把序号那一列空着
349
+
350
+ 「其他相关文档」不在 Context Pack 里,所以按 v0.14 的规矩**不编号** —— 但那一格空着,
351
+ 读到的不是「对齐」,而是「漏了一个号」(用户 2026-10-01 原话:「其他相关文档…又没有这个序号,
352
+ 没有序号以后左边就空了,视觉上比较割裂,就觉得是个 bug 一样」)。
353
+
354
+ - **编号规则不变**:仍然是**跨三档连续**的一条序列(01…0N)。三层是**同一个包的一条阅读顺序**
355
+ (先看 / 辅助 / 背景),不是三个各自排名的清单 —— 所以不改成「每一档各自从 01 开始」。
356
+ - **没号的行在同一列渲染一个中性标记 `.knit-gapmark`(·)**:不冒充序号,也不让轨道断掉,
357
+ 「所有行左边缘对齐」那条纪律照旧。它和 `.knit-num` **共用同一条 CSS 选择器**,
358
+ 于是「序号行高 = 标题行高」这条纪律自动覆盖它(不用再同步第三处数字)。
359
+ - ⚠️ **只有这一屏里有号时才渲染**:时间序 / 平铺列表整屏都没号 ⇒ 一个标记都没有。
360
+ 刺眼的从来是**混着**(一半有号、一半空着),整屏一致就没人觉得缺东西 —— 这条也有用例守着。
361
+
362
+ ### 改动:预览头路径收敛成「…/文件名」+ 按钮改「本地打开」
363
+
364
+ 用户 2026-10-01 原话:「前面那一串都用三个点点点来表示就行了…我觉得这样就够了。…我是想让右边的空间多一点。
365
+ 另外右边的在本地打开,我觉得修改成本地打开就行。这样改下来,整个 UI 就变得更加鲜亮了」。
366
+
367
+ - **目录段不再上屏**:`.knit-preview-dir` 的内容由 `splitRelPath(preview.rel).dir`(整段目录)改成
368
+ **固定占位 `…/`**;`splitRelPath()` 函数本身一行没改(无目录时依旧只渲染文件名)。
369
+ **完整相对路径没丢** —— 它在 `.knit-preview-path` 的 `title` 里(悬停即见),
370
+ 路径按钮本身仍然可点、仍然是用系统默认应用打开这篇文档。
371
+ - **CSS**:`.knit-preview-dir{flex:0 0 auto;color:var(--dsw-alias-label-tertiary,…)}` —— 不再需要
372
+ `min-width:0` + `overflow:hidden` + `text-overflow:ellipsis` 那套收缩(目录已经不渲染了)。
373
+ - **文案**:中文 `'preview.openLocalBtn'`:`在本地打开` → **`本地打开`**(英文 `Open locally` 不动)。
374
+ - 测试同步:面包屑用例改成断言目录段文本 === `…/`、整条路径文本 === `…/需求 文档.md`,tooltip 仍带完整
375
+ `sub/需求 文档.md`;`test/path.test.mjs` 里「在本地打开」全部改成「本地打开」。测试数仍 **453 / 453**。
376
+
377
+ ### 改动:悬停浮层删掉页脚「点击打开面板」与它上面那条横线
378
+
379
+ 用户 2026-10-01 原话:「那个文档列表下面不是有"点击打开面板"还有上面那条横线,我觉得都可以删掉,有点多余了」。
380
+
381
+ - 删掉 `KnitPeek` 末尾那个页脚节点与 `'peek.openPanel'` 两个文案键(中英各一条,别处没有引用);
382
+ - 删掉专门给页脚画线的 `.knit-peek-list + .knit-peek-hint{… border-top: …}` 这条 CSS 规则;
383
+ - **保留** `.knit-peek .knit-peek-hint`(空态那句「这个工作区里还没有 Markdown 文档。」仍然在用)。
384
+ - 浮层那两条通路(点某一篇直接展开预览、点图标打开面板)一行没动。测试数仍 **453 / 453**。
385
+
6
386
  ## [0.15.0] - 2026-09-30
7
387
 
8
388
  **从「构建一份当前任务上下文」再往前一步:让上下文能回答「它到底有没有被用上」。**
package/README.en.md CHANGED
@@ -7,22 +7,23 @@
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 51 documents — the list, an inline
10
+ *Screenshot from a real machine, not a mock-up: a workspace with 53 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
- *The top line follows whatever you're talking about; when there isn't enough conversation yet it
15
- falls back to newest-first and states its basis.*
14
+ *The header holds only the path, the document count and two toggles; whether the list runs by
15
+ relevance or by newest-first is decided by that pair of tabs on the left.*
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
 
22
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.*
23
+ anything, the list runs newest-first; ask "how is BM25 weighted for the ranking?" and the next poll
24
+ swaps the top of the list, with the tier headings and the **continuous rank numbers across all
25
+ three tiers** appearing alongside a one-line "why" under each row (what matched, and how).*
26
+ *In this particular frame no document landed in the primary tier, so the groups start at "supporting".*
26
27
  *⚠️ The panel polls **every 5 seconds**, so the re-rank lands **0–5 s** after the message rather than
27
28
  instantly, and the GIF runs faster than real time.*
28
29
 
@@ -166,7 +167,7 @@ from one flat list to **three tier groups**, each group name followed by a very
166
167
  > The sketch leaves out each entry's summary. **The real structure is: a number in its own column
167
168
  > on the far left (vertically centred with the first line), and to its right a stack of one line —
168
169
  > 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
+ > shown in the list; the path lives in the preview header, with the directory collapsed to `…/`). And the list is
170
171
  > **always one column** however wide the pane gets.
171
172
 
172
173
  **No rules between groups**: hierarchy comes from 16px of space, the group name and type size,
@@ -298,10 +299,11 @@ feature request.
298
299
  |---|---|
299
300
  | **Sorted by relevance to the current conversation** (BM25 + IDF, fully local, no model) | ✅ |
300
301
  | **The `knit_docs` tool for the agent**: the model can look up this project's most relevant documents itself | ✅ |
302
+ | **Document lifecycle** (v0.17): each recommended document is shown as `Unread / Read / Updated after read / Re-read after update`, alongside the most recent read, how many reads fell outside the pack (expandable to which ones), and the latest context change | ✅ |
301
303
  | One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
302
304
  | Scans `.md` in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist`) | ✅ |
303
305
  | 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 | ✅ |
306
+ | 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
307
  | Click to preview inline, click again to collapse | ✅ |
306
308
  | Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
307
309
  | 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 +311,11 @@ feature request.
309
311
  | Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
310
312
  | The **All** view splits into **two stacked sections**: docs (max 4, with "View all →" when truncated) and images & video (**never truncated**, count only) | ✅ |
311
313
  | 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) | ✅ |
314
+ | **"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
315
  | Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
314
316
  | Filter box over title / summary / path | ✅ |
315
317
  | **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) | ✅ |
318
+ | **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
319
  | 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
320
  | Auto-refresh every 5s plus a manual button; docs changed in the last 2 min get 🆕 | ✅ |
319
321
  | Bilingual (zh/en), follows the DSH language live — no plugin reload needed | ✅ |
@@ -329,47 +331,62 @@ feature request.
329
331
 
330
332
  *Images & video: square thumbnails, with the **column count following the panel width continuously** —
331
333
  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.*
334
+ particular workspace happens to hold several screenshots, one demo GIF and one single-colour SVG icon
335
+ (the solid black square is that icon, not a failed load). Videos get their first frame as a poster with
336
+ a play glyph and a duration badge — this workspace simply has no video, so none shows here.*
335
337
 
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)
338
+ ![Screenshot of the All tab: the documents section showing the first 4 with a "View all →" link, and the images-and-video grid below](https://raw.githubusercontent.com/PolinniZhong/dsh-knit/main/docs/screenshot-all.png)
337
339
 
338
- *All: the documents section shows at most 4, with a "View all →" link when truncated (here "4 / 40").*
340
+ *All: the documents section shows at most 4, with a "View all →" link when truncated (here "4 / 36"),
341
+ and the images-and-video grid below it.*
339
342
 
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).*
343
+ ⚠️ Both sections share the **same 40-item window** the host returns — if images and video rank past
344
+ 40th by relevance, the All view shows **none of them at all** (the Images & video tab is unaffected,
345
+ because it requests media on its own). A known defect, with reproduction and the fix recorded in
346
+ [`docs/README.md`](docs/README.md).*
346
347
 
347
348
  ---
348
349
 
349
- ## Did it actually get used? (v0.15)
350
+ ## Did it actually get used? (v0.16 → v0.17)
350
351
 
351
352
  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
+ never checked**. v0.15 added a layer of **verifiable usage feedback**: the files the agent really read,
353
354
  matched against the context pack that was in effect **at the moment of the read**.
355
+ v0.16 nails that down: **attribution is settled and frozen at read time** — however the context
356
+ changes later, the historical numbers never change their story (in v0.15 a read could be
357
+ re-judged as "outside" by the present, which was a bug).
354
358
 
355
359
  **Off by default.** There is a "Usage" toggle in the panel head; turning it on adds one muted line
356
360
  above the list:
357
361
 
358
362
  ```
359
- primary read (docs/xxx.md) · supporting 1/2 · 7 reads · 2 outside the pack · context changed 2×
363
+ Context · Epoch 4 · primary read (docs/xxx.md) · supporting 1/2 · 7 reads · 2 outside the pack · context changed 2×
360
364
  ```
361
365
 
366
+ - **Context Epoch**: one **content-changed** context equals one epoch (identical content creates
367
+ none, so polling cannot flood it). `Epoch 4` is a cumulative number, not "the 4th pack".
368
+ - **Two fact-only fields**: `continuedReadAfterExit` (it was still read after leaving this context)
369
+ and `reEntry` (it left, came back into the pack, and was read again). They must **never** be read
370
+ as "the agent rejected the new context" — that is inference, not fact.
371
+
362
372
  It reports **facts only**: was the primary doc read, how many reads happened, how many fell outside
363
373
  the pack, how often the context changed. **No score, no percentage, no progress bar** — these numbers
364
374
  are counted, not estimated.
365
375
 
366
376
  Three boundaries:
367
377
 
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.
378
+ - **Off by default**: while it is off, Knit **counts nothing** (it subscribes to the host event
379
+ stream, but the callback bails out on the first line for unaudited sessions — one Map lookup).
380
+ That accounting is the user's call, not ours.
370
381
  - **No duplicate of the DSH trajectory**: the only evidence source is the `tool/call` / `tool/result`
371
382
  events the session **already has** (successful `read`s). **No new event bus, no runtime trace,
372
383
  no event store.**
384
+ - **One backfill when you flip the toggle**: the subscription is the sole read-evidence source (the
385
+ old `session.snapshotEvents()` is deprecated by DSH, and no new production call was added), so reads
386
+ that happened before the gate opened were genuinely invisible to Knit. Since v0.17 the moment the
387
+ toggle flips, the host **backfills once** the events this session already produced — which turns
388
+ "Unread" into a claim with evidence behind it. ⚠️ Backfilled reads are attributed to the *earliest
389
+ pack we know about* (earlier packs are unknowable).
373
390
  - **Nothing is persisted**: the numbers live in kernel memory only and are gone after a DSH restart —
374
391
  do not treat them as long-term statistics.
375
392
 
@@ -382,6 +399,64 @@ To check offline: `node tools/context-feedback-eval.mjs` replays the latest real
382
399
  `.json`, which Knit never indexes). Without that split the outside ratio stays high and reads like
383
400
  "the Context Pack is useless", when in fact **the wrong thing was measured**.
384
401
 
402
+ ### v0.17: what state is a document in, after it has been read?
403
+
404
+ Turning "Usage" on adds two more things besides the line above: **a status on each recommended
405
+ document**, and "which one was read last / what was read outside the pack / how the context last
406
+ changed".
407
+
408
+ ```
409
+ Context · Epoch 4
410
+ Recently read: SDD-v0.17.md · 12 min ago
411
+
412
+ Primary
413
+ 01 ● SDD-v0.17.md Read ×3
414
+ 02 feedback.md Unread
415
+
416
+ Supporting
417
+ 03 context.md Read
418
+ 04 eval.md Updated after read
419
+
420
+ Related
421
+ 05 README.md Re-read after update
422
+
423
+ Read outside the pack · 2 ← clickable: which ones
424
+ Context just changed ← clickable: Entered / Left / Moved tier
425
+ ```
426
+
427
+ All four states are **facts**, not scores:
428
+
429
+ | Label | The fact |
430
+ |---|---|
431
+ | Unread | No successful `read` in this session |
432
+ | Read / Read ×N | It was read successfully, and the file has not changed since the last successful read |
433
+ | Updated after read | The file's `mtimeMs` changed after the last successful read |
434
+ | Re-read after update | It changed and was then read successfully again (another change drops it back one state) |
435
+
436
+ - **The evidence is the file's `mtimeMs`** — which the workspace scan already collects — so nothing
437
+ compares content, scans full text, or adds an index. When mtime is unavailable, **no claim is made**
438
+ (it stays at "Read").
439
+ - `grep` / `glob` / `bash` do not count as reads, and neither does a failed `read`.
440
+ - "Recently read" is decided by event sequence number and is **never called "currently reading"**:
441
+ Knit cannot prove the agent is still reading it. If it falls outside the Context Pack, it is still
442
+ shown as-is.
443
+ - **Read outside the pack · N** expresses only "this document is not in the current pack, but the
444
+ agent did successfully read it" — never "Knit missed it", and no recall rate, hit rate or
445
+ context-quality number.
446
+ - **Context just changed** shows only the **single latest** delta (`+` entered / `-` left /
447
+ `↔` moved tier; a changed task adds one line, "Task context updated") — **no timeline, no event
448
+ explorer**.
449
+ - The status sits between the title and the time, and **the title stays the visual anchor**: no red
450
+ or green, no score. With the toggle off, **none of it appears** (and nothing is counted).
451
+ - **The list no longer flickers** (requested 2026-10-03): a row that was just read fades in from
452
+ below, a row squeezed out is wiped away **top-down**, several at once stagger by 45ms (6 steps at
453
+ most), and a row that changed tier or rank **flies there from where it was** (FLIP, 340ms).
454
+ Nothing is animated on first paint, when the kind / sort / query changes, or when the system asks
455
+ for reduced motion. This is not a new feature — it only makes "who arrived, who left, who moved"
456
+ visible. Indexing, ranking, tiers and the `knit_docs` output are unchanged.
457
+
458
+ The `knit_docs` tool output **did not grow**: it still only finds context.
459
+
385
460
  ---
386
461
 
387
462
  ## What it reads, and what it doesn't
@@ -439,7 +514,7 @@ The relevance figure only affects ordering — it is **never displayed and never
439
514
  git clone https://github.com/PolinniZhong/dsh-knit.git
440
515
  cd dsh-knit
441
516
 
442
- npm test # 395 tests, zero dependencies, no npm install needed
517
+ npm test # 517 tests, zero dependencies, no npm install needed
443
518
  ```
444
519
 
445
520
  **How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
@@ -460,9 +535,10 @@ knit/
460
535
  │ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
461
536
  │ ├── host/links.js # reference parsing (pure; never touches ranking)
462
537
  │ ├── host/context.js # context assembly: the three-tier Context Pack (pure, zero I/O)
538
+ │ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
463
539
  │ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
464
540
  │ └── client/client.js # dual-host registration + panel UI
465
- └── test/ # 395 tests
541
+ └── test/ # 517 tests
466
542
  ├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
467
543
  └── context/ # context tiering: 24-doc corpus + 12 real-task cases
468
544
  ```