dsh-knit 0.16.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 +158 -5
- package/README.en.md +85 -23
- package/README.md +73 -18
- package/package.json +2 -2
- package/src/client/client.js +613 -14
- package/src/host/feedback.js +241 -11
- package/src/host/index.js +189 -22
- package/test/client.test.mjs +601 -0
- package/test/document-lifecycle.test.mjs +513 -0
- package/test/harness.mjs +7 -1
- package/test/host-http.test.mjs +129 -2
- package/test/i18n.test.mjs +39 -0
- package/test/tier1.test.mjs +4 -2
package/CHANGELOG.md
CHANGED
|
@@ -3,9 +3,162 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
-
## [0.
|
|
6
|
+
## [0.17.0] - 2026-10-03
|
|
7
7
|
|
|
8
|
-
>
|
|
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…`)。
|
|
9
162
|
> 这一版把上一节那批「未发布」的界面收敛**一起**带上。
|
|
10
163
|
|
|
11
164
|
**Context Effectiveness(依据 `01_ Knit PRD/SDD-v0.16-Context-Effectiveness.md`)**:
|
|
@@ -146,10 +299,10 @@ v0-v4 三代并存都能读,以前写死 v4);`metricsFor()` 增 `epochs` /
|
|
|
146
299
|
- `test/client.test.mjs` 新增 2 条**可见性**用例:`visible === false` 时一次都不取数、也不挂轮询;
|
|
147
300
|
座位契约的 `tab.visible` 一路传到 `KnitBody`(拿不到 `useTabInfo` 时按「看得见」处理)。
|
|
148
301
|
|
|
149
|
-
## [0.15.1] - 2026-09-30 ·
|
|
302
|
+
## [0.15.1] - 2026-09-30 · 并入 0.16.0
|
|
150
303
|
|
|
151
|
-
> ⚠️
|
|
152
|
-
>
|
|
304
|
+
> ⚠️ 这一版**没有单独发布**(未打 tag、未单独 publish),**并进了 v0.16.0**(见上一节)——
|
|
305
|
+
> 下面这批界面收敛随 `0.16.0` 一起发出。
|
|
153
306
|
|
|
154
307
|
**界面收敛 + 一处真机修复**:没有新指标、没有新接口,BM25 一行没改,Context Pack 的装配规则一行没改。
|
|
155
308
|
|
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,6 +299,7 @@ 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 | ✅ |
|
|
@@ -329,24 +331,23 @@ 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
|
|
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 / 36"),
|
|
341
|
+
and the images-and-video 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 — 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.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,
|
|
@@ -380,9 +381,12 @@ Three boundaries:
|
|
|
380
381
|
- **No duplicate of the DSH trajectory**: the only evidence source is the `tool/call` / `tool/result`
|
|
381
382
|
events the session **already has** (successful `read`s). **No new event bus, no runtime trace,
|
|
382
383
|
no event store.**
|
|
383
|
-
- **
|
|
384
|
-
`session.snapshotEvents()` is deprecated by DSH
|
|
385
|
-
|
|
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).
|
|
386
390
|
- **Nothing is persisted**: the numbers live in kernel memory only and are gone after a DSH restart —
|
|
387
391
|
do not treat them as long-term statistics.
|
|
388
392
|
|
|
@@ -395,6 +399,64 @@ To check offline: `node tools/context-feedback-eval.mjs` replays the latest real
|
|
|
395
399
|
`.json`, which Knit never indexes). Without that split the outside ratio stays high and reads like
|
|
396
400
|
"the Context Pack is useless", when in fact **the wrong thing was measured**.
|
|
397
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
|
+
|
|
398
460
|
---
|
|
399
461
|
|
|
400
462
|
## What it reads, and what it doesn't
|
|
@@ -452,7 +514,7 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
452
514
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
453
515
|
cd dsh-knit
|
|
454
516
|
|
|
455
|
-
npm test #
|
|
517
|
+
npm test # 517 tests, zero dependencies, no npm install needed
|
|
456
518
|
```
|
|
457
519
|
|
|
458
520
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -476,7 +538,7 @@ knit/
|
|
|
476
538
|
│ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
|
|
477
539
|
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
478
540
|
│ └── client/client.js # dual-host registration + panel UI
|
|
479
|
-
└── test/ #
|
|
541
|
+
└── test/ # 517 tests
|
|
480
542
|
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
481
543
|
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
482
544
|
```
|
package/README.md
CHANGED
|
@@ -7,9 +7,9 @@
|
|
|
7
7
|
|
|
8
8
|

|
|
9
9
|
|
|
10
|
-
*真机截图(不是原型):一个含
|
|
10
|
+
*真机截图(不是原型):一个含 53 篇文档的工作区 —— 列表 + 就地预览 + 引用条。*
|
|
11
11
|
*引用条是 v0.12 加的:展开就能看到「这篇被谁引用」,点一项直接跳过去。*
|
|
12
|
-
|
|
12
|
+
*头部只放路径、篇数与两个开关;列表按「相关」还是「最新」排,由左边那一对页签决定 —— 按「相关」时排的就是你正在聊什么。*
|
|
13
13
|
*v0.14 起文档列表永远单列:最左边独立一列是序号(与标题第一行垂直居中),右边第一行=*
|
|
14
14
|
*Primary 点 + 标题 + 相对时间(**时间靠右**),摘要再往下;**路径只出现在预览头里**(目录收敛成一个 `…/` 占位,完整相对路径在悬停提示里),列表行不再重复。*
|
|
15
15
|
*序号是**跨三档连续**的一条(先看 / 辅助 / 背景);「其他相关文档」不在包里、不编号,那一格用一个 `·` 占位 ——*
|
|
@@ -17,9 +17,10 @@
|
|
|
17
17
|
|
|
18
18
|

|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
20
|
+
*排序跟着对话走(同一个工作区、刚新开一个会话):还没聊什么时,列表按修改时间排;*
|
|
21
|
+
*问一句「排序算法用的 BM25 是怎么加权的?」,下一次轮询就把顶上几条整个换掉 ——*
|
|
22
|
+
*分组标题与**跨三档连续的序号**随之一起出现,每篇下面多一行「为什么」(命中在哪、怎么命中的)。*
|
|
23
|
+
*这一屏里没有文档落进主要层,所以分组从「辅助上下文」开始。*
|
|
23
24
|
*⚠️ 面板是**每 5 秒轮询一次**的,所以重排落在发消息之后的 **0–5 秒**内、不是瞬时;动图比真实时间快。*
|
|
24
25
|
|
|
25
26
|
扫整个项目文件夹的 Markdown / 图片 / 视频 · 排序跟着对话走 · 不调模型、不联网
|
|
@@ -163,6 +164,7 @@ dsh plugin --profile web add dsh-knit
|
|
|
163
164
|
| **按当前对话相关性排序**(BM25 + IDF,纯本地,零模型) | ✅ |
|
|
164
165
|
| **当前任务上下文**:把排序结果拆成 **主要 / 辅助 / 相关** 三层,每条都写明「为什么在这里」 | ✅ |
|
|
165
166
|
| **给 agent 用的 `knit_docs` 工具**:让模型拿回**三层任务上下文**(不是一条平铺列表) | ✅ |
|
|
167
|
+
| **文档生命周期**(v0.17):每篇推荐文档现在处于 `未读 / 已读 / 读后已更新 / 修改后已重新读取` 哪一档,另外给出最近读了哪篇、包外读了哪几篇、上下文最近一次怎么变 | ✅ |
|
|
166
168
|
| 相关性 / 修改时间双模式一键切换(偏好记在 localStorage) | ✅ |
|
|
167
169
|
| 扫描会话工作区里的 `.md`(递归,深度 ≤ 6,跳过 `node_modules` / `.git` / `dist`) | ✅ |
|
|
168
170
|
| 每项显示:H1 标题(无则文件名)+ 相对时间 + 首段摘要 | ✅ |
|
|
@@ -192,16 +194,15 @@ dsh plugin --profile web add dsh-knit
|
|
|
192
194
|

|
|
193
195
|
|
|
194
196
|
*图片与视频:方形缩略图,**列数跟着面板宽度连续变** —— 这一屏是 6 列,格子约 112px。*
|
|
195
|
-
*列出的就是工作区里真实的图片与 SVG 文件 ——
|
|
196
|
-
|
|
197
|
-
|
|
197
|
+
*列出的就是工作区里真实的图片与 SVG 文件 —— 这个工作区正好有几张截图、一张演示动图和一个*
|
|
198
|
+
*单色 SVG 图标,所以看起来像一屏文件缩略图(那个纯黑方块就是图标本身,不是加载失败)。*
|
|
199
|
+
*视频会取首帧当海报、中央叠播放三角、右下角叠时长,只是这个工作区里没有视频,所以这一屏看不到。*
|
|
198
200
|
|
|
199
|
-

|
|
200
202
|
|
|
201
|
-
|
|
202
|
-
*⚠️
|
|
203
|
-
|
|
204
|
-
*`visibleDocs.filter(isMedia)` 恒为空、媒体区整个不渲染。**文档数 ≥ 40 的工作区都会这样**,*
|
|
203
|
+
*全部:上区文档最多 4 条,超出时右侧给「查看全部 →」(这一屏是「4 / 36」),下区是图片与视频网格。*
|
|
204
|
+
*⚠️ 上下两区共用宿主返回的**同一个 40 条窗口**:图片与视频如果按相关性排到第 40 名之外,*
|
|
205
|
+
*「全部」档就**整段看不到它们**(「图片与视频」档不受影响,它单独取媒体)。*
|
|
205
206
|
*这是已知缺陷,复现与修法记在 [`docs/README.md`](docs/README.md)。*
|
|
206
207
|
|
|
207
208
|
---
|
|
@@ -317,7 +318,7 @@ Knit 一装上就有整个项目的历史文档可用。
|
|
|
317
318
|
|
|
318
319
|
---
|
|
319
320
|
|
|
320
|
-
## 它有没有被用上(v0.16)
|
|
321
|
+
## 它有没有被用上(v0.16 → v0.17)
|
|
321
322
|
|
|
322
323
|
Knit 会排出「现在最该先看的几篇」,但**排得对不对,过去只能靠感觉**。
|
|
323
324
|
v0.15 起有一层**可核验的使用反馈**:把 agent 真实读过的文件,跟**读发生那一刻**生效的那份上下文对起来。
|
|
@@ -345,8 +346,10 @@ v0.16 把这件事钉死:**归因在读发生那一刻结算并冻结** ——
|
|
|
345
346
|
没开审计的会话只花一次 Map 查找)。这笔账该由你决定要不要付。
|
|
346
347
|
- **不重复 DSH 的轨迹**:证据只有一个来源 —— 会话事件流里**已经存在**的 `tool/call` /
|
|
347
348
|
`tool/result` 事件(成功的 `read`)。**没有新的事件总线、没有 Runtime Trace、也没有 Event Store。**
|
|
348
|
-
-
|
|
349
|
-
标为 deprecated
|
|
349
|
+
- **打开开关的那一刻会回填一次**:订阅是唯一的读证据来源(旧的 `session.snapshotEvents()` 已被
|
|
350
|
+
DSH 标为 deprecated,不再新增生产调用),所以**闸门打开之前发生的读,Knit 当时确实看不见**;
|
|
351
|
+
v0.17 起在闸门打开的那一刻**回填一次**本会话已有的事件,让「未读」变成有证据的结论。
|
|
352
|
+
⚠️ 回填的读按**我们已知最早的那份包**归因(更早的包无从得知)。
|
|
350
353
|
- **不落盘**:数据只在宿主内存里,重启 DSH 就没了,**别把它当长期统计**。
|
|
351
354
|
|
|
352
355
|
agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工具结果末尾会多一行
|
|
@@ -357,6 +360,58 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
|
|
|
357
360
|
**Knit 索引里有、却没进包**(真漏)与**压根不在索引里**(`.js` / `.json`,Knit 本来就不索引这些);
|
|
358
361
|
不拆开的话包外比例恒高,读起来像「Context Pack 没用」,其实是**量错了东西**。
|
|
359
362
|
|
|
363
|
+
### v0.17:读完之后,这篇文档现在是什么状态
|
|
364
|
+
|
|
365
|
+
打开「使用情况」之后,除了上面那一行,还会多两样东西:**每篇推荐文档的状态**,
|
|
366
|
+
以及「最近读了哪篇 / 包外读了哪几篇 / 上下文最近一次怎么变」。
|
|
367
|
+
|
|
368
|
+
```
|
|
369
|
+
当前上下文 · Epoch 4
|
|
370
|
+
最近读取:SDD-v0.17.md · 12 分钟前
|
|
371
|
+
|
|
372
|
+
主要上下文
|
|
373
|
+
01 ● SDD-v0.17.md 已读 ×3
|
|
374
|
+
02 feedback.md 未读
|
|
375
|
+
|
|
376
|
+
辅助上下文
|
|
377
|
+
03 context.md 已读
|
|
378
|
+
04 eval.md 读后已更新
|
|
379
|
+
|
|
380
|
+
相关上下文
|
|
381
|
+
05 README.md 修改后已重新读取
|
|
382
|
+
|
|
383
|
+
上下文外读取 · 2 篇 ← 点得开,展开是「哪几篇」
|
|
384
|
+
上下文刚刚变化 ← 点得开,展开是「进入 / 离开 / 换层」
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
四档状态全是**事实**,不是评分:
|
|
388
|
+
|
|
389
|
+
| 界面文案 | 事实 |
|
|
390
|
+
|---|---|
|
|
391
|
+
| 未读 | 本会话没有一次成功 `read` |
|
|
392
|
+
| 已读 / 已读 ×N | 成功读过,且最后一次读取之后文件没变 |
|
|
393
|
+
| 读后已更新 | 最后一次成功读取之后,文件的 `mtimeMs` 变过 |
|
|
394
|
+
| 修改后已重新读取 | 变过之后又成功读过一次(再变一次就退回上一档) |
|
|
395
|
+
|
|
396
|
+
- **判据就是文件的 `mtimeMs`** —— 工作区扫描本来就拿得到它,所以**不比对内容、不扫描全文、不新增索引**。
|
|
397
|
+
拿不到 mtime 时**不下结论**(宁可停在「已读」)。
|
|
398
|
+
- `grep` / `glob` / `bash` 不算读;失败的 `read` 也不算。
|
|
399
|
+
- 「最近读取」按事件序号判定「谁最近」,**不叫「正在阅读」**:Knit 无法证明 Agent 此刻还在读它;
|
|
400
|
+
它落在 Context Pack 之外也照实显示。
|
|
401
|
+
- **上下文外读取 · N 篇**只表达「这篇不在当前包,但 Agent 确实成功读过它」——
|
|
402
|
+
不写「Knit 漏掉了」,也不做漏召回率、命中率、Context 质量。
|
|
403
|
+
- **上下文刚刚变化**只展示**最近一次** Delta(`+` 进入 / `-` 离开 / `↔` 换层,
|
|
404
|
+
任务变了就说一句「任务上下文已更新」)—— **没有时间线,也没有事件浏览器**。
|
|
405
|
+
- 状态文字排在标题和时间之间,**标题仍然是视觉主体**;不用红绿、不给分。
|
|
406
|
+
关掉开关则**一个都不出现**(也不统计)。
|
|
407
|
+
- **列表不再「一闪一闪」**(2026-10-03 用户要求):被读到的行从下方淡入上浮,被挤掉的行
|
|
408
|
+
**自上而下**擦除渐隐;同一拍里多篇按 45ms 错开(最多 6 档);换了层或名次变了的那篇
|
|
409
|
+
**从老位置飞过去**(FLIP,340ms)。首屏、换类型 / 换排序 / 搜索词,
|
|
410
|
+
以及系统开了「减弱动态效果」时都**不播**。这不是新功能,只是把「谁进来了、谁走了、
|
|
411
|
+
谁挪了位置」演给人看 —— 索引、排序、分层与 `knit_docs` 的输出一个字都没改。
|
|
412
|
+
|
|
413
|
+
`knit_docs` 的工具输出**没有跟着变大**:它仍然只负责找上下文。
|
|
414
|
+
|
|
360
415
|
---
|
|
361
416
|
|
|
362
417
|
## 它读什么,不读什么
|
|
@@ -412,7 +467,7 @@ agent 侧同样可选:`knit_docs` 加 `audit: true`(默认 `false`),工
|
|
|
412
467
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
413
468
|
cd dsh-knit
|
|
414
469
|
|
|
415
|
-
npm test #
|
|
470
|
+
npm test # 517 项,零依赖,不需要先 npm install
|
|
416
471
|
```
|
|
417
472
|
|
|
418
473
|
**改动生效方式**:宿主半边(`src/host/`)改了**必须重启 DSH**(实测不热加载);
|
|
@@ -436,7 +491,7 @@ knit/
|
|
|
436
491
|
│ ├── host/feedback.js # 使用反馈:读时归因 / Context Epoch / Delta(纯逻辑,只读事件流)
|
|
437
492
|
│ ├── host/tool.js # agent 文档工具 knit_docs(手写 ToolDefinition)
|
|
438
493
|
│ └── client/client.js # 双宿主注册 + 面板 UI
|
|
439
|
-
└── test/ #
|
|
494
|
+
└── test/ # 517 项测试
|
|
440
495
|
├── eval/ # 检索质量评测:语料 + 用例 + 冻结的 v0.5.2 基线
|
|
441
496
|
└── context/ # 上下文分层评测:24 篇语料 + 12 条任务型用例
|
|
442
497
|
```
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-knit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.17.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 test/context-effectiveness.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 test/document-lifecycle.test.mjs"
|
|
27
27
|
},
|
|
28
28
|
"dsh": {
|
|
29
29
|
"bundle": {
|