dsh-knit 0.16.0 → 0.18.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 +303 -5
- package/README.en.md +141 -29
- package/README.md +119 -23
- package/package.json +2 -2
- package/src/client/client.js +1224 -77
- package/src/host/feedback.js +241 -11
- package/src/host/index.js +189 -22
- package/test/client.test.mjs +1118 -17
- package/test/document-lifecycle.test.mjs +513 -0
- package/test/harness.mjs +11 -2
- package/test/host-http.test.mjs +129 -2
- package/test/i18n.test.mjs +223 -1
- package/test/tier1.test.mjs +4 -2
package/CHANGELOG.md
CHANGED
|
@@ -3,9 +3,307 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
-
## [0.
|
|
6
|
+
## [0.18.0] - 2026-10-06
|
|
7
7
|
|
|
8
|
-
>
|
|
8
|
+
> **状态:已备好发布**(`0.18.0`,2026-10-06)—— 纯客户端重构:宿主(`src/host/*`)**一行未改**,
|
|
9
|
+
> v0.17 的 517 条测试照旧通过。发布动作(跑 `knit/.github/workflows/publish.yml` / 打 tag)
|
|
10
|
+
> **只能由人执行**(`AGENTS.md` §11 规则 7);tag / `gitHead` / `dist-tags` 的逐条核对见
|
|
11
|
+
> `03_发布/发布清单-v0.18.0.md`。
|
|
12
|
+
> ⚠️ **这次不留「尚未发布」的尾巴**:v0.16 / v0.17 把 🚧 行留到 publish **之后**才改
|
|
13
|
+
> (`0.17.0` 那节的 ⚠️ 就是那处瑕疵,改不了)—— 本行写成**发布前后都成立**的说法,
|
|
14
|
+
> 真实发布状态以 `AGENTS.md` §1 与 npm `dist-tags` 为准。
|
|
15
|
+
|
|
16
|
+
**Context Usage Lens(依据 2026-10-05 用户给的 V0.18 规格)**:
|
|
17
|
+
v0.17 的「使用情况」是一行统计文字 + 三块折叠列表 —— 信息都在,但**读不出结构**:
|
|
18
|
+
哪一层读得多、最近读的是哪一篇、包外那二十篇里哪几篇被反复读、这次变化是进是出。
|
|
19
|
+
这一版把它重做成文档列表**上方**的一块轻量观察层 —— 不是弹窗、不是新页面、不是 Dashboard:
|
|
20
|
+
|
|
21
|
+
```
|
|
22
|
+
使用情况 Epoch 5 ˄
|
|
23
|
+
335 次读取 · 29 篇包外 · 上下文变化 1 次
|
|
24
|
+
当前上下文
|
|
25
|
+
主要 1 / 1 辅助 2 / 3 相关 0 / 5
|
|
26
|
+
● ● ○ ○ ○ ○ ○ ○
|
|
27
|
+
最近读取 docs/eval.md 12分钟前 ›
|
|
28
|
+
上下文外读取 20 ›
|
|
29
|
+
上下文变化 最近一次 ›
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
展开包外 / 变化那两行之后(菜单式,`›` 变 `⌃`):
|
|
33
|
+
|
|
34
|
+
```
|
|
35
|
+
上下文外读取 20 ⌃
|
|
36
|
+
01 docs/old-plan.md ×3 已读
|
|
37
|
+
02 docs/test-case.md ×1 已读
|
|
38
|
+
还有 10 篇
|
|
39
|
+
上下文变化 最近一次 ⌃
|
|
40
|
+
进入
|
|
41
|
+
+ docs/algo.md
|
|
42
|
+
换层
|
|
43
|
+
↔ docs/eval.md · 辅助 → 相关
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
**没有分数、没有百分比、没有进度条、没有图表、没有新 Store、没有新采集**:
|
|
47
|
+
数据全部来自 v0.17 已有的 `usage.lifecycle / recentRead / outsideDocs / latestDelta` 与
|
|
48
|
+
`context` 的三层 rels,Coverage 是**派生**出来的(`coverageOf`)。
|
|
49
|
+
|
|
50
|
+
### 变化
|
|
51
|
+
- 新增 **Context Coverage**:主要 / 辅助 / 相关三层各给「状态点 + `已读数 / 本层总数`」,
|
|
52
|
+
点某一层 → 滚到那一层并**短暂高亮**(`data-knit-tier` + `.flash`,1200ms 自己收掉)。
|
|
53
|
+
Primary 不存在时整列不显示(**不画 `0 / 0` 的假层**);没有进度条、没有百分比。
|
|
54
|
+
- 文档行新增**行内生命周期 glyph**:未读 `○` / 已读 `●` / 读后已更新 `△` / 修改后已重新读取 `↻`
|
|
55
|
+
(形态在「UI 迭代」一节里改成 **6px 真圆点**,只有 `↻` 还是字符;四态靠 `data-mark` 区分)。
|
|
56
|
+
glyph 与原来那行文字**同时**存在(glyph 说状态,文字说次数 `×3`)。glyph 是真 `button`,
|
|
57
|
+
带 `title` / `aria-label`,点它=打开 / 选中这一篇(**已经打开则保持原预览**)。
|
|
58
|
+
统计**关掉**时这一格退回 v0.17 的 Primary 黑点 —— 与 v0.17 逐字一致。
|
|
59
|
+
- 最近读取从「一行文字」改成**一行可点的事实**(`文件名 · 相对时间 ›`),点它直接打开该篇,
|
|
60
|
+
点的那一下**不敲宿主**(走已有的 `requestPreview`)。语义仍是「**最近一次成功 read**」,
|
|
61
|
+
没有改成「正在阅读 / Agent 正在查看」。
|
|
62
|
+
- 上下文外读取改成可浏览集合:默认最多 10 篇 + 「还有 N 篇」,每行是可点对象并带生命周期;
|
|
63
|
+
排序改成 **`count DESC`**(同次数再按 `lastReadAt` / `seq`)—— 这是**事实排序**,不是相关度评分。
|
|
64
|
+
⚠️ 宿主给的顺序是「首次读的先后」(`outsideDocsOf` 按 `seq` 升序),所以排序发生在客户端纯函数
|
|
65
|
+
`groupOutsideDocs` 里,宿主不改。
|
|
66
|
+
- 上下文变化:默认只给一条菜单行(`上下文变化 最近一次 ›`,UI 迭代后条数不再写在按钮上),
|
|
67
|
+
展开后按 **进入 / 离开 / 换层** 分三组,
|
|
68
|
+
每组最多 5 条(沿用 v0.17 规则)。
|
|
69
|
+
- 顺手修掉一个潜在 bug:`moved` 的**真实载荷是 `{tier, rank}`**(v0.17 新增的宿主形状),
|
|
70
|
+
v0.17 的渲染直接把它当层名用 —— 真机上会渲染出空层名(`↔ x.md · →`)。现在两种载荷都认。
|
|
71
|
+
- Lens 自己可以展开 / 收起(`.knit-lens-head`,`aria-expanded`)。
|
|
72
|
+
**收起 ≠ 关掉统计**:收起只收起细节,标题 / Epoch / 摘要仍在;关掉才一个统计 DOM 都不产生。
|
|
73
|
+
- 面板矮(< `COMPACT_PANEL_PX` = 420px)时降级:不铺变化摘要,其余照旧。
|
|
74
|
+
滚动**仍然只交给 `.knit-list`** —— Lens 自己不滚动、**没有第二个滚动容器**。
|
|
75
|
+
- 新增纯函数 `coverageOf` / `groupOutsideDocs` / `groupDelta` / `lifeStatusOf`(能派生就不存储)。
|
|
76
|
+
- 验收取证时(2026-10-05)拿**真实会话载荷**跑了一次渲染,抓到三处「同一份事实讲两遍 /
|
|
77
|
+
讲不齐」,在发布前修掉 —— 都不是新功能,是这一版自己的渲染问题:
|
|
78
|
+
- 上下文变化**展开**后,折叠时那三行摘要 + 「还有 N 条」还在,后面又接了一遍分组明细
|
|
79
|
+
(同一批进出/换层条目出现两次)。现在展开就只渲染分组那一份(`deltaOpen ? null : …`)。
|
|
80
|
+
- 包外读取的行里次数说了两遍:`.knit-out-count` 已经是 `×71`,生命周期又用短次数说了一遍
|
|
81
|
+
→ 真机渲染成 `client.js ×71 ×71`。新增 `lifeWord()`:**次数已经在同一行时只用状态词**
|
|
82
|
+
(`… ×71 已读`),次数是这一档的排序键,必须留着;文档行的 `● ×3` 不受影响。
|
|
83
|
+
- 反过来的一处**讲不齐**:`任务上下文已更新` 只进了折叠摘要,展开后不见了 ——
|
|
84
|
+
可是当时按钮上的数字(`上下文变化 · N`)算上了它,于是「说 6 条、只列 5 行」。
|
|
85
|
+
现在展开时它也照常列一行(它在摘要里本来就是最后一条)。
|
|
86
|
+
- 顺手补了两条**英文渲染**守卫:v0.18 之前那条「英文整棵树里一个汉字都没有」用的是
|
|
87
|
+
没有 `usage` 的语料 ⇒ **Lens 整块没进渲染树**,几十条新文案(含 `title` / `aria-label`)
|
|
88
|
+
其实不在覆盖里。现在英文下把 Lens 真的打开、把两块折叠集合也点开再查一遍(空态另有一条)。
|
|
89
|
+
- 发布前又拿同一份真实载荷做了一次**不变式对账**(14 条:摘要 / Epoch / Coverage / 展开行数与唯一性 /
|
|
90
|
+
折叠尾巴 / 包外计数 / 四态同屏 / 无百分比与评分 / 不自己滚动)⇒ **14/14 通过**,
|
|
91
|
+
并把它里最通用的一条(**展开后列出的行 + 每条组内尾巴里的数字,必须等于载荷算出的总数**)立成了守卫,
|
|
92
|
+
这样上面那处「讲不齐」不会再从别的分支回来。
|
|
93
|
+
- 变化按钮上不再写条数(`上下文变化 · N` → `上下文变化 最近一次 ›`),账目改由
|
|
94
|
+
**展开后的行 + 尾巴**承担 —— 这样「说 N 条」与「列了几行」不可能再不一致。
|
|
95
|
+
|
|
96
|
+
### v0.18 UI 迭代(2026-10-06)
|
|
97
|
+
|
|
98
|
+
> 依据:用户给的 `02_方案与 Demo/dsh-knit V0.18 UI 重构开发提示词.md` + 同名 Demo HTML。
|
|
99
|
+
> 只动客户端外观(`src/client/client.js` 的 CSS / JSX / i18n 与对应测试),宿主一行未改;
|
|
100
|
+
> 功能、数据来源、DOM 的**语义**都不变 —— 这是把 v0.18 的 Lens 从「能用」改到「好看」。
|
|
101
|
+
|
|
102
|
+
- **字体尺度收成一套**:15(Usage 标题)/ 14(文档标题、Tabs)/ 13(Segmented、过滤框、
|
|
103
|
+
「当前上下文」分节标题)/ 12(摘要行、Coverage 层名与数字、最近读取)/ 11(生命周期、时间、
|
|
104
|
+
包外与变化的行)—— 不再有 10.5px / 11.5px 这类半档。
|
|
105
|
+
- **控件尺寸与描边**:`使用情况` / `刷新` 24px→**28px**(radius 8px);Segmented 与过滤框
|
|
106
|
+
22px / 24px → **28px**、radius 10px、字号 13px —— 原来那两个「迷你胶囊」是这一版最显眼的审美缺口。
|
|
107
|
+
Segmented 内部只保留控件自己的边框;Tab 下划线仍是 2px。
|
|
108
|
+
(提示词文档写的是 36px;2026-10-06 用户看了真机后定成 28px:「太高了,不需要这么高」。)
|
|
109
|
+
这两个控件的**描边色改用 `--dsw-alias-border-l3`** —— 与 DSH 主区「对话」页签下面那条横线
|
|
110
|
+
(官方 header 的 `border-bottom`,浅色 `rgba(0,0,0,.12)`)同一档;原来的 `l4` 重一档,
|
|
111
|
+
摆在页签下面像两个输入框把内容框住了(2026-10-06 用户要求「跟那条横一样」)。
|
|
112
|
+
描边**粗细也跟那条横对齐:0.5px**(官方那条本身就是 `.5px`;2026-10-06 用户第二轮要求
|
|
113
|
+
「描边色值修改成 0.5px」)。色对上了粗细没对上,高分屏上会比旁边那条横粗一倍 —— 三处
|
|
114
|
+
(Segmented 外框、内部竖线、过滤框)一起 0.5px,有守卫不许只改其中一处。
|
|
115
|
+
- **类型页签文案「图片与视频」→「媒体」**(2026-10-06 用户定;英文 `Images & video` → `Media`):
|
|
116
|
+
同一档的计数本来就是 `{n} 个媒体` / `{n} media`,页签是唯一的例外;「多媒体」暗示音频,
|
|
117
|
+
而这一档只扫图片与视频;含义由空态兜住(`list.emptyMedia` = 这个工作区里还没有图片或视频。)。
|
|
118
|
+
一个 i18n 键 `kind.media` 同时供页签与「全部」档的分区标题 ⇒ 改一处即两处,有守卫钉着。
|
|
119
|
+
- **状态点统一成 6px 真圆**:Coverage 的空心 / 实心点与文档行左侧的生命周期点
|
|
120
|
+
**同一套 token、同一个直径**(未读 = 透明 + 1px `label-caption` 边框,已读 = 同色填充,
|
|
121
|
+
读后已更新 = 实心 + 内圈,修改后已重新读取 = `↻` 字符)。没有任何绿 / 红 / 黄 / 蓝。
|
|
122
|
+
(文档写 9px,2026-10-06 用户定成 6px;守卫改为**比对两处直径**,不再各写各的。)
|
|
123
|
+
- **两处折叠集合改成菜单行**:`上下文外读取 20 ›` 与 `上下文变化 最近一次 ›`
|
|
124
|
+
(label 左、数量 / 说明右、`›` 展开变 `⌃`),行高 38px、hover 只改背景、无位移;
|
|
125
|
+
包外明细每行带 `01` / `02` 序号。**条数不再写在变化按钮上**(见上)。
|
|
126
|
+
- **定位手感**:点 Coverage 某层 → 平滑滚到**视口中部**(`block: 'center'`),高亮 **1200ms**
|
|
127
|
+
(原 900ms → 650ms → 2026-10-06 用户看真机后定成 1200ms);`prefers-reduced-motion: reduce`
|
|
128
|
+
下改为瞬时滚动、所有新过渡 `none`。⚠️ `FLASH_MS` 与 `.knit-tier{transition:background 1.2s}`
|
|
129
|
+
**必须同一个数**(有守卫;只改一个不会报错,只会看见「高亮已取消、背景还在慢慢褪」的错帧)。
|
|
130
|
+
- **窄侧栏不撑破**:Coverage 三列改成 `minmax(0, …)` 轨道,层名超长时省略号截断。
|
|
131
|
+
- **没做**(提示词文档明确禁止或与既有设计冲突):没有卡片化、没有阴影、没有上浮 / 缩放 /
|
|
132
|
+
连续脉冲、没有新滚动容器、没有新增数据、没有新模型或网络请求。
|
|
133
|
+
- **与 Demo 不一致的三处,按提示词文档办**:① Demo 给 Coverage 组画了淡底 + 1px 边框 +
|
|
134
|
+
hover `translateY(-1px)`,文档要求「默认不要 border、hover 最多很淡背景、不许 translate」;
|
|
135
|
+
② Demo 有可见的「未读 / N 篇已读」帮助行,文档要求那句只给读屏(现在只在 `aria-label` 里);
|
|
136
|
+
③ Demo 的 Usage 块有全宽 `border-bottom`,文档要求 Usage 内部不画全宽线。三处都听文档。
|
|
137
|
+
|
|
138
|
+
### 测试
|
|
139
|
+
- `npm test`:**532 / 532 通过**(v0.17 是 517)。新增 15 条 v0.18 守卫:
|
|
140
|
+
Coverage 三层数值与「点它定位到那一层」、Primary 缺席不画假层、Lens 收起、空使用情况、
|
|
141
|
+
小高度面板的降级判据、点状态点 / 包外行不直接请求列表、轮询不重播动画、
|
|
142
|
+
样式(语义 token / 自己不滚动 / `prefers-reduced-motion`)、纯函数层、
|
|
143
|
+
以及英文 Lens(打开态 / 空态)里没有汉字(文字 + 属性)。
|
|
144
|
+
- 一条**账目**守卫(刻意给 8 条换层以跨过组内上限):载荷算出的总数必须等于
|
|
145
|
+
「展开后列出的行数 + 每条组内尾巴里写的数字」—— 证伪过(把那一行改回 `false && …` 会有 3 条变红)。
|
|
146
|
+
- 宿主侧一行未改:v0.17 的 517 条全部照旧通过。
|
|
147
|
+
|
|
148
|
+
## [0.17.0] - 2026-10-03
|
|
149
|
+
|
|
150
|
+
> ✅ **2026-10-05 已发布**:`v0.17.0` = 轻量 tag = npm `gitHead` = `4d0c74e` · npm `latest = 0.17.0`
|
|
151
|
+
> · **43 文件 / 394.6 kB 打包 / 1.2 MB 解包** / shasum `33bf6faac4de75170e2378ff9096dd4cdb1da81a`。
|
|
152
|
+
> 由 **npm 可信发布(Trusted Publisher / OIDC)** 经 GitHub Actions 发出(带 provenance),不再用 token。
|
|
153
|
+
> ⚠️ **包内这份 CHANGELOG 里对应的那两行仍写着「🚧 尚未发布」** —— 本次改它的提交在 publish 之后,
|
|
154
|
+
> **同一版本号不能再发一次**(与 v0.16 同一个坑)。
|
|
155
|
+
|
|
156
|
+
**Document Lifecycle(依据 `01_ Knit PRD/Knit-PRD-SDD-v0.17-Document-Lifecycle.md`)**:
|
|
157
|
+
前面几版回答的是「Knit 推荐了什么 → Agent 有没有读 → 读落在哪一层」;
|
|
158
|
+
这一版接着回答**一篇文档读完之后,现在处于什么状态**。
|
|
159
|
+
只做四件事:文档状态、最近读取、包外读取的明细、最近一次 Context Delta。
|
|
160
|
+
检索侧一行没改(BM25 / IDF / 关键词抽取 / 长度归一化 / freshness / 分层 / Context Pack 装配规则一个字没动),
|
|
161
|
+
**没有分数、没有百分比、没有进度条、没有时间线、没有新面板、没有第二份存储**。
|
|
162
|
+
|
|
163
|
+
### 新增:四个事实状态
|
|
164
|
+
|
|
165
|
+
| 状态(数据层) | 界面文案 | 判据 |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| `unread` | 未读 | 本会话没有一次成功 `read` |
|
|
168
|
+
| `read` | 已读 / 已读 ×N | 有过成功 `read`,且最后一次成功读取之后文件版本标记没变 |
|
|
169
|
+
| `updated_after_read` | 读后已更新 | 最后一次成功读取之后,文件的 `mtimeMs` 变过 |
|
|
170
|
+
| `reread_after_update` | 修改后已重新读取 | 变过之后又成功读过一次;再变一次就退回上一档 |
|
|
171
|
+
|
|
172
|
+
判据复用现有工作区扫描拿到的 `mtimeMs`:`src/host/index.js` 里的 `mtimeOf(root, rel)` 做一次 `statSync`,
|
|
173
|
+
在 `tool/call` 那一刻把结果交给 `ingestEvents(..., { stat })`,`feedback.js` 自己不碰 I/O。
|
|
174
|
+
**不引入内容哈希、不扫描全文、不新增索引、不落盘。**
|
|
175
|
+
|
|
176
|
+
事实就是事实,不做推断:状态只说「文件在上次成功读取之后变过 / 变过之后又读过」,
|
|
177
|
+
不写「Agent 还不知道最新版」「Agent 没看到你的修改」这类话(测试里钉死了这些词不出现)。
|
|
178
|
+
`grep` / `glob` / `bash` 不算 `read`;失败的 `read` 不算;拿不到当前 `mtimeMs` 或没记过
|
|
179
|
+
`lastReadMtimeMs` 时**不下结论**(宁可停在 `read`);文件只是被重新扫描过,不等于被重新读过。
|
|
180
|
+
|
|
181
|
+
### 新增:最近读取 / 包外明细 / 最近一次变化
|
|
182
|
+
|
|
183
|
+
- **最近读取:`<rel>` · <相对时间>** —— 最近一次**成功 `read`** 对应的文件,按事件 `seq` 判定「谁最近」,
|
|
184
|
+
墙钟只负责显示相对时间;它落在 Context Pack 之外也照实显示。
|
|
185
|
+
**不叫「正在阅读」**:Knit 无法证明 Agent 此刻还在读这篇。
|
|
186
|
+
- **上下文外读取 · N 篇**(可展开)—— 原来只有一个数字,现在点得开、看得到是哪几篇,
|
|
187
|
+
每行给 `rel` 和该篇的状态。只表达「这篇不在当前 Context Pack,但 Agent 确实成功读过它」;
|
|
188
|
+
不写「Knit 漏掉了 / 推荐错了」,也不做漏召回率、命中率、Context 质量。
|
|
189
|
+
- **上下文刚刚变化**(只展示**最近一次** Delta)—— `+` 进入 / `-` 离开 / `↔` 换层(层名用短名),
|
|
190
|
+
折叠时最多三行,展开按「进入 / 离开 / 换层」分组;`taskChanged` 只说一句「任务上下文已更新」。
|
|
191
|
+
不产出时间线,也不做事件浏览器。
|
|
192
|
+
|
|
193
|
+
### 数据层:扩现有 store,不加第二套
|
|
194
|
+
|
|
195
|
+
`src/host/feedback.js` 新增三个纯函数(`lifecycleOf(entry, mtimeMs)` / `latestReadOf(reads)` /
|
|
196
|
+
`outsideDocsOf(reads, items)`),`recordRead()` 每篇多冻三个标量
|
|
197
|
+
(`lastReadMtimeMs` / `prevReadMtimeMs` / `rereadAfterChange`);
|
|
198
|
+
`usageFrom(state, { mtimes })` 的返回值**顶层**多四个字段
|
|
199
|
+
(`lifecycle` / `recentRead` / `outsideDocs` / `latestDelta`),v0.16 的 `stats` 15 个键一个没动。
|
|
200
|
+
`/api/recent?usage=1` 用工作区扫描的全量列表(未截断)算 `mtimeMs`,
|
|
201
|
+
只回传当前文档列表 + 包外文档的状态行,每篇三字段(`status` / `count` / `lastReadAt`)。
|
|
202
|
+
|
|
203
|
+
历史归因继续冻结:`tier` / `rank` / `inside` / `epochId` 仍是**读发生时**那一份 Context 的结算值,
|
|
204
|
+
不会因为「现在」换了包而改口(v0.16 的行为原样保留)。
|
|
205
|
+
|
|
206
|
+
`knit_docs` 工具的**输出没有变**:它仍然只负责「找上下文」,不输出生命周期报告
|
|
207
|
+
(工具描述与工具结果都要吃模型上下文,这一版的主要消费者是人)。
|
|
208
|
+
|
|
209
|
+
### 修订(真机验收):闸门开晚也要说真话
|
|
210
|
+
|
|
211
|
+
验收时暴露一个来回:先让 Agent 读了一篇文档、**之后**才打开使用情况开关 —— 那两次读发生在订阅
|
|
212
|
+
回调开始按会话早退之前,事件根本没进过内存,于是面板把一篇**确实已经读过**的文档显示成「未读」。
|
|
213
|
+
那不是解析错误,是**没有证据**:闸门打开之前,Knit 一条读都没看见,却对「未读」下了断言。
|
|
214
|
+
|
|
215
|
+
修订:闸门打开的那一刻,宿主**回填一次**本会话已有的事件(`src/host/index.js` 的
|
|
216
|
+
`backfillFeedback()`,由 `activateFeedback()` 在面板与工具两条开闸路径上调用;一个会话只回填一次、
|
|
217
|
+
只在当前这一 tick,零 I/O、零网络、零模型)。**顺序是这个机制的组成部分**:先把手上那份 Context Pack
|
|
218
|
+
`noteSnapshot()` 记下、**再**喂事件 —— `recordRead()` 在事件入库那一刻就把归因冻结,先喂事件的话,
|
|
219
|
+
补记的读会在「一份快照都还没有」的状态下被判成包外,而「这篇不在当时的上下文里」是一句我们并不知道
|
|
220
|
+
真假的话(§6)。回填那次不传 `at`,于是这份「会话开头」快照的 `at` 仍是 0,第一次 `usage.at` 的语义
|
|
221
|
+
(还没有上一份包)不变。`session.snapshotEvents()` 的 deprecated 提示仍然有效:这是**闸门打开那一刻的
|
|
222
|
+
唯一例外**。
|
|
223
|
+
|
|
224
|
+
已知不精确,写在明面上:回填的读按**我们已知最早的那份包**归因,更早的包 Knit 无从得知。
|
|
225
|
+
|
|
226
|
+
### 界面
|
|
227
|
+
|
|
228
|
+
- 文档行在标题与时间之间多一个弱化状态文字,只在**使用情况打开 + 分层视图**里出现;
|
|
229
|
+
标题仍是视觉主体,状态不用红绿、不加重、不给分。
|
|
230
|
+
- 使用情况那一行下面多三块极轻的东西:最近读取、`上下文外读取 · N 篇`(可展开)、`上下文刚刚变化`(可展开);
|
|
231
|
+
折叠状态存在组件本地,不写进偏好。既有的「使用情况」行一个字没改。
|
|
232
|
+
- **使用情况默认关**:关着时 `usage=1` 不发、宿主不初始化生命周期、DOM 里**零新增节点**(测试钉死)。
|
|
233
|
+
|
|
234
|
+
### 新增:列表进出动效(2026-10-03 用户拍板)
|
|
235
|
+
|
|
236
|
+
验收时用户提的:「新读取跟挤掉旧的未读的,这里的交互可能要优化,因为现在是一闪一闪的,就非常的快…
|
|
237
|
+
从当前的、如辅助上下文中新增,它应该是从低向上的…消失的时候从上到下,渐隐掉」。做的还是同一件事,
|
|
238
|
+
只是把它**看得见**:一行文档被读到、换了层、被挤出列表时,不再是「瞬间落位」。
|
|
239
|
+
|
|
240
|
+
- **进来**:从下方 26px 处淡入上浮(高度 0 → 量出来的自然高度、`blur(3px)` 收敛到 0);
|
|
241
|
+
同一拍里多篇按屏幕顺序错开 45ms,**最多错 6 档**(一次涌进十几篇时不排长队)。
|
|
242
|
+
- **出去**:先把自然高度量下来,再把高度收到 0、**自上而下**擦除
|
|
243
|
+
(`clip-path: inset(T 0 0 0)`,T 从 0 到 100%)并渐隐;这一行留在列表里把动画播完才移除,
|
|
244
|
+
否则看起来像「跳到末尾才消失」。它插回的位置由上一帧的 `index` 决定(`mergeGhostRows()`)。
|
|
245
|
+
- **换层 / 重排**:走 **FLIP**(同一篇 `rel` 在新旧两帧都在 ⇒ 既不算进入也不算离开,
|
|
246
|
+
交给位置补间)。这一行的节点在跨分区时会被 React 重建,所以位置按 **`rel`** 记,
|
|
247
|
+
老节点量到的矩形照样能用在新节点上:先把它从老位置拉回来(`transform: translate(dx, dy)`)
|
|
248
|
+
再补到归位(340ms),于是「从包外升进 Primary」看起来是**飞上去的**,不是瞬移。
|
|
249
|
+
它跑在提交之后、绘制之前的 layout effect 里,且在 `DocRow` 的进 / 出补间**之后**
|
|
250
|
+
(React 是子先父后):那一刻新行已经是 0 高、幽灵行还占着原高度,所以量到的位移只剩
|
|
251
|
+
「真的挪了位置」的行,不会和进 / 出补间算两遍;正在进 / 出的行直接跳过。
|
|
252
|
+
位移小于 0.5px(含浏览器缩放 / 滚动的亚像素抖动)算没动过,否则整屏会一直在微微地飘。
|
|
253
|
+
- **什么时候不播**:首屏、换类型 / 换排序 / 搜索词变了(那是「换屏」、不是「来了新的」),
|
|
254
|
+
以及系统开了「减弱动态效果」(`prefers-reduced-motion: reduce`,连底色过渡一起去掉)。
|
|
255
|
+
|
|
256
|
+
两条硬约束:**补间在 JS 里走 WAAPI(`Element.animate`),CSS 里只有两笔静态规则**
|
|
257
|
+
(`.knit-doc.leaving` 与减弱动态效果那条媒体查询)—— 高度必须按量出来的自然高度补间,
|
|
258
|
+
写几个 `@keyframes` 会在动画收尾的瞬间跳一行间距。`motionAllowed()` 在没有 `document`、
|
|
259
|
+
没有 `Element.prototype.animate`、或系统要求减弱动态效果时返回假,于是宿主进程与测试进程里
|
|
260
|
+
**一行补间都不排、也不造幽灵行**:渲染树与没有这段动效时逐字一致
|
|
261
|
+
(`planRowMotion()` / `mergeGhostRows()` 都是纯函数,测试直接喂数据)。
|
|
262
|
+
|
|
263
|
+
### 测试
|
|
264
|
+
|
|
265
|
+
- 新增 `test/document-lifecycle.test.mjs`(24 例):四档状态、缺 mtime 不下结论、失败 `read` 不计、
|
|
266
|
+
`grep` / `glob` / `bash` 不计、按 `seq` 判最近读取、包外明细与排序、历史归因不漂移、
|
|
267
|
+
同一事件重复派发幂等(`count` 只 +1,且不重采样 mtime);另有 4 例钉住**开闸回填**
|
|
268
|
+
(补记的读归「会话开头那份包」⇒ 不再被误判成包外、只影响第一份快照、重复派发仍幂等)。
|
|
269
|
+
- `test/host-http.test.mjs` 多 3 例端到端:`usage` 顶层新字段与 `stats` 形状不变;
|
|
270
|
+
**真改盘上 mtime** ⇒ 读后已更新,再读一次 ⇒ 修改后已重新读取;
|
|
271
|
+
面板开晚的会话在开闸那一刻**回填**已有的成功读(`reads=1`、`firstReadTier='primary'`、`outside=0`),
|
|
272
|
+
且一个会话只回填一次(再请求一次仍是 1)。
|
|
273
|
+
- `test/client.test.mjs` 多 19 例:四档渲染、标题 / 状态 / 时间顺序、最近读取的相对时间、
|
|
274
|
+
包外折叠与展开、Delta 摘要与分组、溢出与 `taskChanged`、只用语义 token、英文环境无汉字;
|
|
275
|
+
关着时零新增节点;另有 7 例钉住**进出动效**只在真机上播 —— 首帧与「换屏」都不播、
|
|
276
|
+
交错按屏幕顺序且封顶、离开的行带着原有的区与位次、同一篇换层既不算进也不算出、
|
|
277
|
+
幽灵行插回原位(含「还活着的不造幽灵」与「别的区不插」)、Node 里恒被 `motionAllowed()` 挡掉、
|
|
278
|
+
CSS 里没有 `@keyframes`(只有 `.knit-doc.leaving` 与减弱动态效果那条媒体查询);
|
|
279
|
+
另有 3 例钉住**换层 / 重排的 FLIP** —— 位移的正负与阈值(亚像素抖动不算动)、
|
|
280
|
+
给挪过位置的幸存行排一段 `translate(dx,dy) → 0`(进 / 出的行跳过、位置表跨帧传递、
|
|
281
|
+
节点不认 WAAPI 时只记位置不抛错),以及那行 `applyRowFlips(...)` 确实接在提交之后。
|
|
282
|
+
- `test/i18n.test.mjs` 多 1 例:16 条新文案中英逐条对齐,且状态文案里不出现推断词。
|
|
283
|
+
- `npm test`:**517/517 通过**(v0.16 是 468,新增用例 49 条)。
|
|
284
|
+
|
|
285
|
+
### 修好:交互审的两处「列表自己跳」(2026-10-04)
|
|
286
|
+
|
|
287
|
+
**用户报了两件事**:①「我选中一个文档查看全文,特别是在最下方的文档,相关联文档,我一点它就跳,
|
|
288
|
+
我一点它就很跳,闪的很快」;②「我刚刚重启 DeepseekHarness,我没有输入任何的对话……
|
|
289
|
+
我们的文档列表就开始跳动,它怎么能够切换呢」。**先按数据查**:同一会话连续打 5 次
|
|
290
|
+
`/knit/api/recent` 返回逐字一致 ⇒ 服务端不抖,四个根因全在**客户端几何 / 时序**:
|
|
291
|
+
|
|
292
|
+
| 症状 | 根因 | 修法 |
|
|
293
|
+
|---|---|---|
|
|
294
|
+
| 点一下就跳 | 预览面板用 `maxHeight: 46%` ⇒ 面板高度由**内容**决定(「加载中」→正文、预览里换一篇都变高矮) | 打开期间高度**固定**成拖出来的比例;长文在正文区里滚,短文档下方留白是代价 |
|
|
295
|
+
| 整屏乱飘 | FLIP 拿 `getBoundingClientRect()`(**视口坐标**)当位置:容器滚动 / 容器变高矮 / 行上 `:hover{transform:translateX(-2px)}` 都凭空造出位移 | 改用**布局坐标** `offsetTop` / `offsetLeft`(`rowLayoutPoint()`) |
|
|
296
|
+
| 越补越飘 | 换屏与进 / 出补间**在飞的那几百毫秒里**也照量位置,量到中间态,落地后又被当成「挪了位置」 | 这两种时候**一个都不量**,并把位置表清空 |
|
|
297
|
+
| 空会话自己跳 | 「光标跟手滚进视口」的依赖里有 `state.docs`(每 5 秒一个新数组)⇒ 把「刷新到数据」当成「用户按了方向键」,光标默认在第一行,用户往下滚过之后每 5 秒被拽回去一次 | 依赖只剩 `[cursor, query]`,且只在列表自己拿着键盘焦点时才滚 |
|
|
298
|
+
|
|
299
|
+
四条都在源码注释里逐条写着「为什么」;两条硬规则进了 `AGENTS.md` §6.13,教训进了 §8.12。
|
|
300
|
+
测试 515 → **517**(`test/client.test.mjs` 多 2 例:`rowLayoutPoint` 的布局坐标优先与兜底分支、
|
|
301
|
+
「刷新不许动列表」= 那条 effect 的依赖里没有 `state.docs`;`test/tier1.test.mjs` 那条预览高度的断言
|
|
302
|
+
从 `maxHeight` 改成 `height` + 断言 `maxHeight === undefined`)。
|
|
303
|
+
|
|
304
|
+
## [0.16.0] - 2026-10-01
|
|
305
|
+
|
|
306
|
+
> ✅ **2026-10-03 已发布**:`v0.16.0` = `8c3ca2c` · npm `latest = 0.16.0`(42 文件 / 341.8 kB / shasum `771705d6…`)。
|
|
9
307
|
> 这一版把上一节那批「未发布」的界面收敛**一起**带上。
|
|
10
308
|
|
|
11
309
|
**Context Effectiveness(依据 `01_ Knit PRD/SDD-v0.16-Context-Effectiveness.md`)**:
|
|
@@ -146,10 +444,10 @@ v0-v4 三代并存都能读,以前写死 v4);`metricsFor()` 增 `epochs` /
|
|
|
146
444
|
- `test/client.test.mjs` 新增 2 条**可见性**用例:`visible === false` 时一次都不取数、也不挂轮询;
|
|
147
445
|
座位契约的 `tab.visible` 一路传到 `KnitBody`(拿不到 `useTabInfo` 时按「看得见」处理)。
|
|
148
446
|
|
|
149
|
-
## [0.15.1] - 2026-09-30 ·
|
|
447
|
+
## [0.15.1] - 2026-09-30 · 并入 0.16.0
|
|
150
448
|
|
|
151
|
-
> ⚠️
|
|
152
|
-
>
|
|
449
|
+
> ⚠️ 这一版**没有单独发布**(未打 tag、未单独 publish),**并进了 v0.16.0**(见上一节)——
|
|
450
|
+
> 下面这批界面收敛随 `0.16.0` 一起发出。
|
|
153
451
|
|
|
154
452
|
**界面收敛 + 一处真机修复**:没有新指标、没有新接口,BM25 一行没改,Context Pack 的装配规则一行没改。
|
|
155
453
|
|
package/README.en.md
CHANGED
|
@@ -7,12 +7,12 @@
|
|
|
7
7
|
|
|
8
8
|

|
|
9
9
|
|
|
10
|
-
*Screenshot from a real machine, not a mock-up: a workspace with
|
|
10
|
+
*Screenshot from a real machine, not a mock-up: a workspace with 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
|
|
15
|
-
|
|
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
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.*
|
|
@@ -20,9 +20,10 @@ right), then the summary. **The path lives in the preview header only** — the
|
|
|
20
20
|

|
|
21
21
|
|
|
22
22
|
*Order follows the conversation — same workspace, in a freshly opened session: before you have said
|
|
23
|
-
anything, the
|
|
24
|
-
|
|
25
|
-
|
|
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
|
|
|
@@ -298,13 +299,14 @@ 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
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
|
-
| One-click switch between **Docs /
|
|
309
|
+
| One-click switch between **Docs / Media / All** (remembered; defaults to Docs, unchanged); the selected tab is a **neutral grey fill**, with no coloured outline (the tab label became "Media" on 2026-10-06, was "Images & video") | ✅ |
|
|
308
310
|
| Images & video: square thumbnail grid — **at least 3 columns, more only as the pane gets wider**; cells start at 64px and the baseline is **8 per screen**; past 8 nothing is hidden, the whole grid scales down proportionally; videos auto-grab the first frame with a play glyph and duration badge (no deps, no transcoding) | ✅ |
|
|
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) | ✅ |
|
|
@@ -325,28 +327,27 @@ feature request.
|
|
|
325
327
|
|
|
326
328
|
### The other two views
|
|
327
329
|
|
|
328
|
-

|
|
329
331
|
|
|
330
|
-
*
|
|
332
|
+
*Media: 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
|
|
333
|
-
black
|
|
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
|
-

|
|
337
339
|
|
|
338
|
-
*All: the documents section shows at most 4, with a "View all →" link when truncated (here "4 /
|
|
340
|
+
*All: the documents section shows at most 4, with a "View all →" link when truncated (here "4 / 39"),
|
|
341
|
+
and the media grid below it.*
|
|
339
342
|
|
|
340
|
-
⚠️
|
|
341
|
-
|
|
342
|
-
media
|
|
343
|
-
`
|
|
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 — when media rank past 40th by
|
|
344
|
+
relevance, the All view keeps only the few inside that window (this screen keeps just one; the Media
|
|
345
|
+
tab is unaffected, because it requests media on its own). A known defect, with reproduction and the
|
|
346
|
+
fix recorded in [`docs/README.md`](docs/README.md).*
|
|
346
347
|
|
|
347
348
|
---
|
|
348
349
|
|
|
349
|
-
## Did it actually get used? (v0.16)
|
|
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
353
|
never checked**. v0.15 added a layer of **verifiable usage feedback**: the files the agent really read,
|
|
@@ -355,11 +356,13 @@ v0.16 nails that down: **attribution is settled and frozen at read time** — ho
|
|
|
355
356
|
changes later, the historical numbers never change their story (in v0.15 a read could be
|
|
356
357
|
re-judged as "outside" by the present, which was a bug).
|
|
357
358
|
|
|
358
|
-
**Off by default.** There is a "Usage" toggle in the panel head; turning it on adds
|
|
359
|
-
above the list
|
|
359
|
+
**Off by default.** There is a "Usage" toggle in the panel head; turning it on adds a lightweight
|
|
360
|
+
**lens** above the list (called the Usage Lens since v0.18 — see "reading the usage" below).
|
|
361
|
+
Its top line still reports facts only:
|
|
360
362
|
|
|
361
363
|
```
|
|
362
|
-
|
|
364
|
+
Usage Epoch 5 ˄
|
|
365
|
+
174 reads · 28 outside the pack · context changed 3×
|
|
363
366
|
```
|
|
364
367
|
|
|
365
368
|
- **Context Epoch**: one **content-changed** context equals one epoch (identical content creates
|
|
@@ -380,9 +383,12 @@ Three boundaries:
|
|
|
380
383
|
- **No duplicate of the DSH trajectory**: the only evidence source is the `tool/call` / `tool/result`
|
|
381
384
|
events the session **already has** (successful `read`s). **No new event bus, no runtime trace,
|
|
382
385
|
no event store.**
|
|
383
|
-
- **
|
|
384
|
-
`session.snapshotEvents()` is deprecated by DSH
|
|
385
|
-
|
|
386
|
+
- **One backfill when you flip the toggle**: the subscription is the sole read-evidence source (the
|
|
387
|
+
old `session.snapshotEvents()` is deprecated by DSH, and no new production call was added), so reads
|
|
388
|
+
that happened before the gate opened were genuinely invisible to Knit. Since v0.17 the moment the
|
|
389
|
+
toggle flips, the host **backfills once** the events this session already produced — which turns
|
|
390
|
+
"Unread" into a claim with evidence behind it. ⚠️ Backfilled reads are attributed to the *earliest
|
|
391
|
+
pack we know about* (earlier packs are unknowable).
|
|
386
392
|
- **Nothing is persisted**: the numbers live in kernel memory only and are gone after a DSH restart —
|
|
387
393
|
do not treat them as long-term statistics.
|
|
388
394
|
|
|
@@ -395,6 +401,112 @@ To check offline: `node tools/context-feedback-eval.mjs` replays the latest real
|
|
|
395
401
|
`.json`, which Knit never indexes). Without that split the outside ratio stays high and reads like
|
|
396
402
|
"the Context Pack is useless", when in fact **the wrong thing was measured**.
|
|
397
403
|
|
|
404
|
+
### v0.17: what state is a document in, after it has been read?
|
|
405
|
+
|
|
406
|
+
Turning "Usage" on adds two more things besides the counts: **a status on each recommended
|
|
407
|
+
document**, and "which one was read last / what was read outside the pack / how the context last
|
|
408
|
+
changed".
|
|
409
|
+
|
|
410
|
+
> ⚠️ The ASCII below is the **v0.17 shape** of this UI. v0.18 rebuilt it into the Usage Lens above
|
|
411
|
+
> the list (next section) — **the criteria, the four states and the data sources did not change**;
|
|
412
|
+
> this section is about the data and the judgement.
|
|
413
|
+
|
|
414
|
+
```
|
|
415
|
+
Context · Epoch 4
|
|
416
|
+
Recently read: SDD-v0.17.md · 12 min ago
|
|
417
|
+
|
|
418
|
+
Primary
|
|
419
|
+
01 ● SDD-v0.17.md Read ×3
|
|
420
|
+
02 feedback.md Unread
|
|
421
|
+
|
|
422
|
+
Supporting
|
|
423
|
+
03 context.md Read
|
|
424
|
+
04 eval.md Updated after read
|
|
425
|
+
|
|
426
|
+
Related
|
|
427
|
+
05 README.md Re-read after update
|
|
428
|
+
|
|
429
|
+
Read outside the pack · 2 ← clickable: which ones
|
|
430
|
+
Context just changed ← clickable: Entered / Left / Moved tier
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
All four states are **facts**, not scores:
|
|
434
|
+
|
|
435
|
+
| Label | The fact |
|
|
436
|
+
|---|---|
|
|
437
|
+
| Unread | No successful `read` in this session |
|
|
438
|
+
| Read / Read ×N | It was read successfully, and the file has not changed since the last successful read |
|
|
439
|
+
| Updated after read | The file's `mtimeMs` changed after the last successful read |
|
|
440
|
+
| Re-read after update | It changed and was then read successfully again (another change drops it back one state) |
|
|
441
|
+
|
|
442
|
+
- **The evidence is the file's `mtimeMs`** — which the workspace scan already collects — so nothing
|
|
443
|
+
compares content, scans full text, or adds an index. When mtime is unavailable, **no claim is made**
|
|
444
|
+
(it stays at "Read").
|
|
445
|
+
- `grep` / `glob` / `bash` do not count as reads, and neither does a failed `read`.
|
|
446
|
+
- "Recently read" is decided by event sequence number and is **never called "currently reading"**:
|
|
447
|
+
Knit cannot prove the agent is still reading it. If it falls outside the Context Pack, it is still
|
|
448
|
+
shown as-is.
|
|
449
|
+
- **Read outside the pack · N** expresses only "this document is not in the current pack, but the
|
|
450
|
+
agent did successfully read it" — never "Knit missed it", and no recall rate, hit rate or
|
|
451
|
+
context-quality number.
|
|
452
|
+
- **Context just changed** shows only the **single latest** delta (`+` entered / `-` left /
|
|
453
|
+
`↔` moved tier; a changed task adds one line, "Task context updated") — **no timeline, no event
|
|
454
|
+
explorer**.
|
|
455
|
+
- The status sits between the title and the time, and **the title stays the visual anchor**: no red
|
|
456
|
+
or green, no score. With the toggle off, **none of it appears** (and nothing is counted).
|
|
457
|
+
- **The list no longer flickers** (requested 2026-10-03): a row that was just read fades in from
|
|
458
|
+
below, a row squeezed out is wiped away **top-down**, several at once stagger by 45ms (6 steps at
|
|
459
|
+
most), and a row that changed tier or rank **flies there from where it was** (FLIP, 340ms).
|
|
460
|
+
Nothing is animated on first paint, when the kind / sort / query changes, or when the system asks
|
|
461
|
+
for reduced motion. This is not a new feature — it only makes "who arrived, who left, who moved"
|
|
462
|
+
visible. Indexing, ranking, tiers and the `knit_docs` output are unchanged.
|
|
463
|
+
|
|
464
|
+
### v0.18: reading the usage (Context Usage Lens)
|
|
465
|
+
|
|
466
|
+
v0.17 had all the information, but **crammed into one line and a few collapsed blocks** — you could
|
|
467
|
+
not read the structure: which tier got read, which document was read last, which of those twenty
|
|
468
|
+
outside documents were read over and over, whether the last change was an arrival or a departure.
|
|
469
|
+
v0.18 rebuilds it as a lightweight **lens above the list** — not a dialog, not a new page, and not a
|
|
470
|
+
dashboard:
|
|
471
|
+
|
|
472
|
+
```
|
|
473
|
+
Usage Epoch 5 ˄
|
|
474
|
+
174 reads · 28 outside the pack · context changed 3×
|
|
475
|
+
Current context
|
|
476
|
+
Primary 1 / 1 Supporting 2 / 3 Related 0 / 5
|
|
477
|
+
● ● ○ ○ ○ ○ ○ ○
|
|
478
|
+
Recent read docs/eval.md 12 min ago ›
|
|
479
|
+
Reads outside context 20 ›
|
|
480
|
+
Context changes Latest ›
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
- **Current-context coverage**: each tier gives "a state dot + `read / total in that tier`". Clicking
|
|
484
|
+
a tier scrolls to that tier and **flashes it briefly** (no arrows, no rules — space says "here").
|
|
485
|
+
**Facts only**: no progress bar, no percentage — Knit does not judge whether a context is "used up",
|
|
486
|
+
and when there is no Primary the whole column is hidden rather than drawing a fake `0 / 0`.
|
|
487
|
+
- **Inline state dot**: unread = hollow circle / read = filled circle / updated after read = filled
|
|
488
|
+
circle with an inner ring / re-read after update = `↻`, shown **alongside** the text (the dot states
|
|
489
|
+
the state, the text states the count). Clicking it opens that document. No red/green, no badge.
|
|
490
|
+
The coverage dots and this one share **the same tokens and the same 6px diameter** — one state language.
|
|
491
|
+
- **Recent read** is a clickable fact row (`file · relative time ›`) that opens that document directly
|
|
492
|
+
and **does not refetch the list**. It is still "the **last successful read**" — never "currently reading".
|
|
493
|
+
- **Reads outside context** shows up to 10 by default plus "N more"; every row is clickable and carries
|
|
494
|
+
its state, sorted by **most-read first** (`count DESC`) — a fact order, not a relevance score. You
|
|
495
|
+
**cannot** promote a document into the context from here (V0.18 does no context control).
|
|
496
|
+
- **Context changes** is collapsed by default; expanding groups it into Entered / Left / Moved tier,
|
|
497
|
+
at most 5 per group, and only the **latest** delta is shown.
|
|
498
|
+
- The lens itself expands / collapses. **Collapsing is not turning usage off** — collapsing means
|
|
499
|
+
"counting, but I do not want the details"; switching the toggle off produces no usage DOM at all.
|
|
500
|
+
- On a short panel (< 420px) it degrades to summary + coverage + recent read; the change details are
|
|
501
|
+
still one click away, and **scrolling always belongs to the list** — there is no second scroll
|
|
502
|
+
container, so a narrow sidebar never gets scroll-inside-scroll.
|
|
503
|
+
|
|
504
|
+
Not one new fact was added: everything comes from the v0.17 `lifecycle / recentRead / outsideDocs /
|
|
505
|
+
latestDelta` fields plus the current `context` tiers, and coverage is **derived** from them (pure
|
|
506
|
+
functions `coverageOf` / `groupOutsideDocs` / `groupDelta`).
|
|
507
|
+
|
|
508
|
+
The `knit_docs` tool output **did not grow**: it still only finds context.
|
|
509
|
+
|
|
398
510
|
---
|
|
399
511
|
|
|
400
512
|
## What it reads, and what it doesn't
|
|
@@ -452,7 +564,7 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
452
564
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
453
565
|
cd dsh-knit
|
|
454
566
|
|
|
455
|
-
npm test #
|
|
567
|
+
npm test # 532 tests, zero dependencies, no npm install needed
|
|
456
568
|
```
|
|
457
569
|
|
|
458
570
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -476,7 +588,7 @@ knit/
|
|
|
476
588
|
│ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
|
|
477
589
|
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
478
590
|
│ └── client/client.js # dual-host registration + panel UI
|
|
479
|
-
└── test/ #
|
|
591
|
+
└── test/ # 532 tests
|
|
480
592
|
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
481
593
|
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
482
594
|
```
|