dsh-knit 0.17.0 → 0.19.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 +333 -2
- package/README.en.md +128 -31
- package/README.md +142 -25
- package/SECURITY.md +4 -3
- package/package.json +6 -4
- package/src/client/client.js +1146 -194
- package/src/host/classification.js +250 -0
- package/src/host/context.js +31 -9
- package/src/host/index.js +336 -77
- package/src/host/tool.js +29 -13
- package/test/classification.test.mjs +237 -0
- package/test/client.test.mjs +982 -54
- package/test/code-context.test.mjs +567 -0
- package/test/eval/fixture.mjs +309 -6
- package/test/eval.test.mjs +117 -1
- package/test/harness.mjs +4 -1
- package/test/host.test.mjs +63 -3
- package/test/i18n.test.mjs +188 -5
- package/test/path.test.mjs +97 -5
- package/test/tool.test.mjs +23 -15
package/CHANGELOG.md
CHANGED
|
@@ -3,10 +3,341 @@
|
|
|
3
3
|
本项目的重要变更都记在这里。格式参考 [Keep a Changelog](https://keepachangelog.com/),
|
|
4
4
|
版本号遵循[语义化版本](https://semver.org/lang/zh-CN/)。
|
|
5
5
|
|
|
6
|
+
## [0.19.0] - 2026-10-07
|
|
7
|
+
|
|
8
|
+
> **Code Context**。产品概念从「Markdown / 图片 / 视频」变成「**文档 / 代码 / 媒体**」——
|
|
9
|
+
> 这不是给后缀表加几行,而是让 Knit 把 AI Coding 任务**当前真正需要的那几个源码文件**
|
|
10
|
+
> 纳入同一条 Context Retrieval 链路。
|
|
11
|
+
> 关键约束:**没有第二条检索链路、没有第二套生命周期、没有第二个 Context Store、
|
|
12
|
+
> 没有 AST / LSP / embedding / 模型调用 / 网络请求、没有把 Knit 变成代码浏览器或 IDE。**
|
|
13
|
+
> 主线数据流一个字没改:当前任务 → Workspace Retrieval → Document + Code Candidates →
|
|
14
|
+
> Primary / Supporting / Related → Context Pack → Agent Read → Read Evidence →
|
|
15
|
+
> File Changed → Lifecycle → Context Epoch / Delta → Usage Lens。
|
|
16
|
+
|
|
17
|
+
### 变化
|
|
18
|
+
|
|
19
|
+
- **新增独立的文件分类层 `src/host/classification.js`**。在这之前,扩展名判定是
|
|
20
|
+
`src/host/index.js` 里一个返回 `''|'md'|'image'|'video'` 的 `kindOfName()`,散在扫描、
|
|
21
|
+
预览、UI 各处。现在只有一个入口:`classifyFile(name)` →
|
|
22
|
+
`{kind, language, previewable, searchable, contextual, generated, sourceMap}`,
|
|
23
|
+
扫描 / 检索 / 预览 / UI **全部消费它的产物**,没有一处再自己看扩展名
|
|
24
|
+
(有一条架构守卫:`src/host/index.js` 与 `src/client/client.js` 里不许出现
|
|
25
|
+
`'.ts'` `'.py'` `'.map'` `'.min.js'` 这类后缀字面量)。
|
|
26
|
+
- **第一批支持 17 个代码后缀**:`.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm
|
|
27
|
+
.css .scss .yaml .yml .sh .bash .zsh`。内部统一 `{kind:'code', language:'…'}`。
|
|
28
|
+
**刻意不支持** `.go .rs .java .kt .c .cpp .h .hpp .cs .php .rb .swift .sql` ——
|
|
29
|
+
范围越小,「代码上下文到底有没有用」这个结论越可信。
|
|
30
|
+
- **代码复用 Markdown 的 BM25,只换字段口径**。代码没有 Markdown 的 title/summary/body,
|
|
31
|
+
所以宿主按 `filename`(**带扩展名**,`plugin-loader.js` 与 `plugin.json` 的差别就在这儿)
|
|
32
|
+
→ `title` 字段、`目录`(保留结尾斜杠)→ `summary` 字段、`正文前 8 KB` → `body` 字段填充,
|
|
33
|
+
于是 `relevance.js` 里既有的 `FIELD_WEIGHTS = {title:4, summary:2, body:1}`
|
|
34
|
+
**一行未改**就是需求要的 filename×4 / path×2 / content×1。排序器、语料过滤、
|
|
35
|
+
门槛规则全是同一个。
|
|
36
|
+
- **`.map` / generated / noise 一律不进上下文**:`*.map`、`*.min.js`、`*.min.css`、
|
|
37
|
+
`*.bundle.js`、`*.generated.js`、`*.gen.js`、`*.lock`(含 `package-lock.json`)→
|
|
38
|
+
`{kind:'generated', searchable:false, contextual:false}`。它们不参与检索、不进 Context Pack、
|
|
39
|
+
不进 Usage Lens、不进代码列表、不进 BM25 语料 —— 但**仍然可以预览**(用户主动从
|
|
40
|
+
DSH 原生文件树点开时不拦):**Context eligibility ≠ File system visibility**。
|
|
41
|
+
- **有边界的扫描**:新增 `MAX_CODE = 300`(Markdown 仍是 400)、代码正文只读前 8 KB
|
|
42
|
+
(`CODE_HEAD_BYTES = 8*1024`,没有无界读取)。目录元信息 → 扩展名分类 → 候选准入 →
|
|
43
|
+
有界内容读取,顺序不变。数字是**量出来的**:真实项目根(`08_Knit`)59 文档 + 54 代码,
|
|
44
|
+
上限根本碰不到;而一个 1300+ 目录的大树正好在这里截住(400 文档 + 300 代码 + 400 媒体)。
|
|
45
|
+
- **代码预览就地展开,不新增交互**:复用面板下方那块现有预览区。行号 gutter + 等宽正文、
|
|
46
|
+
横向滚动只在正文列(纵向滚动仍归 `.knit-preview-body`,**没有第二个纵向滚动容器**)、
|
|
47
|
+
复制、`打开文件`、同一个 `Source map` 轻量入口(只在同名 `.map` 存在时出现)。
|
|
48
|
+
超过 4000 行只渲染前 4000 行并明说被截断。**没有**语法高亮 / 折叠 / 多标签 / mini-map /
|
|
49
|
+
git diff / symbol outline —— 也没有引入 Monaco 或 CodeMirror。
|
|
50
|
+
- **UI 类型档从三档变四档**:`文档 / 代码 / 媒体 / 全部`。代码档**仍然受当前任务检索支配**,
|
|
51
|
+
不是「项目代码文件树」:任务说「改 Skill loader 支持新 frontmatter」,这一档就该是
|
|
52
|
+
`skill-loader.ts` 在前,而不是 `src/` 下全部代码。没有第二层语言分类 UI;
|
|
53
|
+
代码行只多一个很弱的语言徽章(`TS` / `PY` …),文档行不挂(整列都是 MD,是纯噪声)。
|
|
54
|
+
「全部」档变成三区:文档区(≤4)→ 代码区(≤4)→ 媒体网格。
|
|
55
|
+
- **代码的理由码**:`filenameMatch`(文件名命中,与 Markdown 的 `titleMatch` 同级)与
|
|
56
|
+
`pathMatch`(目录命中,与 `summaryMatch` 同级)。`why.filenameMatch` / `why.pathMatch`
|
|
57
|
+
中英各一条;**没有**新增第 8 个条目字段 —— `{rel,title,summary,mtimeMs,kind,source,reason}`
|
|
58
|
+
与 v0.18 逐字相同,代码只是让 `kind` 多了一个取值。
|
|
59
|
+
- **生命周期 / Read Evidence / Epoch / Delta / Usage Lens 一行未改**。代码被读之后走的是
|
|
60
|
+
完全同一套归因:读的时候在哪一层就冻结在哪一层,历史证据不许因后来的 BM25 变化而重算;
|
|
61
|
+
四态(未读 / 已读 / 读后已更新 / 修改后已重新读取)也是同一套;Epoch 是同一份;
|
|
62
|
+
UI 上多出来的叫法一个都没有(仍然只叫「上下文变化」)。
|
|
63
|
+
- **预览头那条路径改成「在文件管理器里定位到这个文件」**。原文案是「用系统默认应用打开这篇文档」,
|
|
64
|
+
与页脚那个「本地打开」按钮**做的是同一件事** —— 一个东西两个入口,还偏要悬停才知道。
|
|
65
|
+
现在两者分工清楚:**路径点开它所在的文件夹、并且已经选中这个文件**
|
|
66
|
+
(`openWorkspacePath({ path, action: 'reveal' })`,macOS 走 `open -R`、Windows 走
|
|
67
|
+
`explorer /select,`,正是 Chrome「在文件夹中显示」那个手感 —— 不用在文件夹里自己再找一遍),
|
|
68
|
+
**「本地打开」点开文件本身**(不带 `action`,走默认应用)。文案随之换成
|
|
69
|
+
`preview.reveal`(中「在文件管理器中显示并选中这个文件」/ 英 `Show this file in your file manager (and select it)`)。
|
|
70
|
+
⚠️ 送过去的是**文件本身的绝对路径**而不是所在目录 —— reveal 一个目录会变成
|
|
71
|
+
「在上级目录里选中这个文件夹」,不是用户要的。Linux 的 `xdg-open` 没有「选中」这个概念,
|
|
72
|
+
那边只有打开目录(平台差异,不是少做一步)。
|
|
73
|
+
- **修:开着「使用情况」点全屏,预览没铺满**。全屏的隐藏名单写于 v0.12,当时面板里只有
|
|
74
|
+
「头部 / 排序条 / 类型档 / 列表 / 预览」这几块,所以只藏了前四块;v0.18 在列表**上方**
|
|
75
|
+
加了 Context Usage Lens(`.knit-usage`),谁也没回头去补那份名单 —— 于是开着「使用情况」
|
|
76
|
+
再点全屏,Lens 仍以 `flex:none` 的自然高度占掉面板上方约三分之一,预览被挤在下面,
|
|
77
|
+
看起来就像「全屏没生效」。补 `.knit-root.fullscreen .knit-usage{display:none}` 一块即可,
|
|
78
|
+
预览那条 `flex:1 1 auto` 本来就在等它让位。
|
|
79
|
+
守卫放在 `test/client.test.mjs`:全屏隐藏名单必须覆盖 `.knit-head` / `.knit-bar` /
|
|
80
|
+
`.knit-types` / `.knit-usage` / `.knit-list`,并跟真的渲染出来的全屏树对一次账 ——
|
|
81
|
+
以后谁再往列表上方加块,这条会响。
|
|
82
|
+
- **HTML 多了「网页预览」**。加了代码支持之后,`.html` 点开看到的是**源码**;
|
|
83
|
+
可 HTML 想看的恰恰是它渲染出来的样子。DSH 其实**自带**这个渲染器
|
|
84
|
+
(`dsh-client-ui-sidebar-documentpreview` 注册了 `["html","htm"]`,默认静态档:
|
|
85
|
+
DOMPurify 清洗过的文档塞进一个**不给任何 sandbox 权限**的 iframe,CSP 摆在最前挡脚本 /
|
|
86
|
+
外部资源 / 连接 / 表单 / 嵌套框架,内联 `<style>` 与 `data:` 图片保留),而 Knit 双击一行
|
|
87
|
+
本来就走 `actions.openResource` → 官方文档预览 —— 通路早就在,缺的只是一个入口。
|
|
88
|
+
所以预览头给 `.html` / `.htm` 加一个「网页预览」按钮,走的就是双击那条**同一个**
|
|
89
|
+
`openResource` 通道:**没有新开第二条打开路径、没有 iframe、没有把 DSH 的渲染器搬进面板**,
|
|
90
|
+
Knit 的零网络出口承诺一个字不用改。
|
|
91
|
+
这不算「把删掉的功能加回来」:v0.10 撤掉「新标签页」按钮的理由是「就地预览已经能看到内容,
|
|
92
|
+
重复度高」—— 那条前提对 HTML 不成立(就地给源码、官方给页面),是纠正而不是回退;
|
|
93
|
+
其余代码类型一个都不给这个按钮。
|
|
94
|
+
- **修掉「工作区是符号链接时,点路径一律报 `Path has no verified Host path`」**(发布前发现的真实 bug):
|
|
95
|
+
在 `DSH_Skill_Trace`(→ `10_DSH_Skill_Trace` 的符号链接)这类工作区里,点预览头路径 /
|
|
96
|
+
「本地打开」/ 点顶部工作区路径**全部失败**,而在真实目录(`08_Knit`)里没事。
|
|
97
|
+
根因不在 Knit,在 DSH 的校验方式:`dsh-api-session-controller` 的 `verifyDesktopPath()`
|
|
98
|
+
把路径送进 `ctx.fs`,要求
|
|
99
|
+
`processPath(await resolve(processPathFromHostPath(p))) === p`,而 `dsh-fs-local` 的
|
|
100
|
+
targetKey 落的是 **`realpath()`** —— 也就是说**含未展开符号链接的路径一定过不了**。
|
|
101
|
+
⇒ Knit 这一侧自己先展开:宿主新增 `hostPathOf()`,下发的 `hostRoot`(工作区根)与
|
|
102
|
+
每条记录的 `path`(文件本身)都已是 canonical 形态;客户端**打开 / 定位一律用它们**,
|
|
103
|
+
`root` 只留给界面显示(用户看到的是自己选的那条路径)。
|
|
104
|
+
`scan()` 内部也改成从 canonical 根走一遍,所以 `rel` 一字不变 ——
|
|
105
|
+
检索 / Context Pack / 生命周期 / Usage Lens 的输入完全没动。
|
|
106
|
+
- **文档同步**:`knit/README.md` 补上代码档与「网页预览」两处说明、测试数刷成 588;
|
|
107
|
+
**`knit/README.en.md` 这次也补了一节 v0.19**(它同样进 npm 包 —— 英文 README 停在 v0.18,
|
|
108
|
+
包内文档就自相矛盾了);`knit/SECURITY.md` 属性表加一行「`/knit/api/doc` 只放行文本类产物」;
|
|
109
|
+
`package.json` 的 keywords 去掉了重复的 `code-context`。
|
|
110
|
+
|
|
111
|
+
### 一处刻意的收窄(引用图)
|
|
112
|
+
|
|
113
|
+
引用图(`md` 文件之间互相指路的那些边)的**源永远是 Markdown**:代码文件不再进图的
|
|
114
|
+
`list`。理由是不能给代码开一条靠「注释里恰好写了一句 `docs/X.md`」就进 Supporting 的
|
|
115
|
+
后门 —— 那条路不打分。反过来,**文档点名一个代码文件**(设计文档里写了 `src/x.js`)仍然
|
|
116
|
+
和文档指文档一样会被尊重:那不是特例,是同一条规则。
|
|
117
|
+
(代码作为「被指向的一方」能进 Supporting,正是需求 §18 要的混合竞争。)
|
|
118
|
+
|
|
119
|
+
### 为什么不需要改 DSH 核心 / 新增 model tool / 新增 Store
|
|
120
|
+
|
|
121
|
+
- **不改 DSH**:DSH 的文件访问走宿主已有的 `ctx.fs` 缝;预览走面板里已有的那块预览区。
|
|
122
|
+
代码与文档走的是同一个资源身份、同一个读取接口 —— 没有自造 OS 路径、没有
|
|
123
|
+
`window.open(local file)`、没有 fork DSH 的 preview 实现(代码预览一共就 4 条 CSS 规则)。
|
|
124
|
+
- **不新增 model tool**:`knit_docs` 工具本身没变,只是它现在能把代码算进同一个 Context Pack。
|
|
125
|
+
工具描述从「Markdown 文档」改成「文档与代码文件」,理由很直接:语料里已经有 `.ts` 了,
|
|
126
|
+
再说「Markdown documents」就是对模型说假话。
|
|
127
|
+
- **不新增 Store**:没有 `codeStore` / `codeContextStore` / `codeRetrievalStore` /
|
|
128
|
+
`workspaceArtifactStore`。代码只是一个多出来的 `artifact.kind`,通过既有状态投影出 UI。
|
|
129
|
+
- **不新建 benchmark framework**:V0.19 的前后对比直接扩在 `test/eval/fixture.mjs` 里 ——
|
|
130
|
+
同一个 `runEval`,同一个 `rankByRelevance`,只把语料换成「Markdown only」与
|
|
131
|
+
「Markdown + Code」两臂。
|
|
132
|
+
|
|
133
|
+
### 测试
|
|
134
|
+
- `npm test`:**588 / 588 通过**(v0.18 是 532)。v0.18 的 532 条**一条没删、一条没放宽**;
|
|
135
|
+
中间有 12 条 v0.18 断言因为契约变化而**同步**(不是降级):
|
|
136
|
+
`readDocument` 的「拒绝非 Markdown」拆成「拒绝不可预览的类型」+「v0.19 起代码可读并带分类结论」;
|
|
137
|
+
类型档从 3 个按钮改成 4 个;`knit_docs` 的文案与两处总数(样本工作区里的 `package.json`
|
|
138
|
+
现在是一个合法代码候选 —— 那个 `3 → 4` 本身就是「代码真的进了同一个检索池」的证据)。
|
|
139
|
+
- 新增 **`test/classification.test.mjs`(12 条)**:17 个支持后缀的 language 映射、
|
|
140
|
+
13 个不支持后缀、`.map`/min/generated/lock、锁文件与生成产物的**反例**
|
|
141
|
+
(`minify.js` / `bundle.js` / `tsconfig.json` 仍是代码)、判定顺序是契约、
|
|
142
|
+
以及「后缀知识只许活在分类层」的架构守卫。
|
|
143
|
+
- 新增 **`test/code-context.test.mjs`(25 条)**:代码穿过整条链路之后还对不对 ——
|
|
144
|
+
字段权重的三档可观测、代码进 Primary 的理由码是 `filenameMatch`、
|
|
145
|
+
只命中目录走 `pathMatch`、混合包里文档与代码公平竞争、条目投影与 v0.18 逐字相同、
|
|
146
|
+
引用图代码只能当靶不能当源、代码 read evidence 与包外读取、历史归因冻结、
|
|
147
|
+
代码四态生命周期、Epoch 的进入 / 离开 / 换层 / delta、七条噪声路径一条不进候选。
|
|
148
|
+
- `test/eval.test.mjs` 新增 **6 条 v0.19 基准守卫**(见下)。
|
|
149
|
+
- **发布前补的 3 条符号链接守卫**(`585 → 588`):`test/host.test.mjs` 造一条指向样本工作区的
|
|
150
|
+
符号链接当 `root`,断言「下发的 `hostRoot` / 每条 `path` 都满足 `realpath(p) === p`」
|
|
151
|
+
(这**就是** DSH 的判据)+「换成符号链接后 `rel` 集合一字不差」;
|
|
152
|
+
`test/path.test.mjs` 两条客户端守卫,分别覆盖「宿主给了 canonical `path`」与
|
|
153
|
+
「老宿主只有 `hostRoot`」时,reveal / 本地打开 / 打开工作区目录**都用 canonical 路径**,
|
|
154
|
+
而界面显示的仍是会话原本那条。写完全部做过**证伪**(把修复回滚,3 条如实变红)。
|
|
155
|
+
- `test/client.test.mjs` 新增 **9 条 v0.19 UI 守卫**:代码档请求 `kind=code` 且代码行带语言徽章、
|
|
156
|
+
文档行一个徽章都不加(整列都是 MD,挂 MD 是纯噪声)、点代码行就地出行号 + 正文且**不落到
|
|
157
|
+
Markdown 渲染**(夹具正文故意以 `#` 开头 —— 走错分支它就会变成标题)、同名 `.map` 才给
|
|
158
|
+
「Source map」入口且列表里始终没有 `.map` 那一行、「全部」档三区(文档 / 代码 / 媒体)
|
|
159
|
+
各自限流、Usage Lens 里的代码路径照常显示(仍是只有事实、没有分数)、
|
|
160
|
+
全屏隐藏名单必须覆盖列表上方每一块(含 `.knit-usage`)、**「网页预览」只有 HTML 出场
|
|
161
|
+
且走的是双击那条 `openResource` 通道(正文读到之前按钮就已在场 —— 否则头会长高一下)**,
|
|
162
|
+
以及一条样式守卫(横向滚动只归正文列,语言徽章无底色无边框无圆角,DSH 令牌必须带回落值)。
|
|
163
|
+
|
|
164
|
+
### 基准(V0.19 前后对比)
|
|
165
|
+
|
|
166
|
+
同一个排序器、同一批用例,**唯一变量是语料里有没有代码**:
|
|
167
|
+
|
|
168
|
+
| 指标 | Markdown only | Markdown + Code |
|
|
169
|
+
| --- | --- | --- |
|
|
170
|
+
| Document Recall (top-1) | 100% | **100%** |
|
|
171
|
+
| Document MRR | 1.000 | **1.000** |
|
|
172
|
+
| Code Recall (top-1) | 0% | **100%** |
|
|
173
|
+
| Code MRR | 0.000 | **1.000** |
|
|
174
|
+
|
|
175
|
+
- **Overall MRR(文档 + 代码一起量:21 条文档用例 + 3 条代码用例)= 1.000**,top-1 100%。
|
|
176
|
+
语料规模:Markdown only 16 条 → Markdown + Code 24 条(**只多 8 条代码**)。
|
|
177
|
+
- **Noise Rate = 0%** —— 7 条生成 / 噪声路径(`node_modules/foo.js`、`dist/app.js`、
|
|
178
|
+
`coverage/report.js`、`app.min.js`、`bundle.generated.js`、`app.js.map`、`package-lock.json`)
|
|
179
|
+
在真实扫描与评测语料里都是 0 条进入。
|
|
180
|
+
- 对照臂:同样三条代码用例放在**只有文档**的语料里 top-1 是 0% —— 所以「加了代码之后答对了」
|
|
181
|
+
不是碰巧。混合场景(Case C)里那篇讲分层的设计文档仍排在第 3 名,**没有被代码挤没**。
|
|
182
|
+
- ⚠️ 说清楚这份基准**不是难度竞赛**:三条代码用例的检索意图都很清晰,两臂都接近满分。
|
|
183
|
+
它的作用是**回归钉** —— 谁把代码候选、噪声过滤、字段权重或 corpus cap 改坏了,这里会红。
|
|
184
|
+
`node knit/tools/scale-benchmark.mjs` 会把这张表连同原有 20/60/180/540 规模基准一起打印。
|
|
185
|
+
- 真机工作区量到的数(`08_Knit`,扫描 4 ms):59 文档 + **54 代码** + 6 媒体,
|
|
186
|
+
0 generated / 10 ignored,语料 59 → 113。一个 1300+ 目录的大树(55 ms):
|
|
187
|
+
400 文档截断 + 300 代码(243 条被 cap 挡下)+ 400 媒体,语料 400 → 700 ——
|
|
188
|
+
`MAX_CODE = 300` 在这里正好起到「别让代码把原有 Markdown 上下文挤出去」的作用。
|
|
189
|
+
|
|
190
|
+
## [0.18.0] - 2026-10-06
|
|
191
|
+
|
|
192
|
+
> ✅ **2026-10-06 已发布**:`v0.18.0` = 轻量 tag = npm `gitHead` = `170ee8f` · npm `latest = 0.18.0`
|
|
193
|
+
> · **43 文件 / 428.7 kB 打包 / 1.3 MB 解包** / shasum `457e7842dda936fcadf671d3d490b7ea28de5629`。
|
|
194
|
+
> (本地 `npm pack --dry-run` 报的是 422.4 kB / `92a4ce9e…`;两个 tarball 的**文件清单与解包内容逐字一致**,
|
|
195
|
+
> 差的只是 tar/gzip 框架元数据 —— 与 v0.17 同一现象。)由 **npm 可信发布(Trusted Publisher / OIDC)**
|
|
196
|
+
> 经 GitHub Actions 发出(带 provenance),不设 `NODE_AUTH_TOKEN`。
|
|
197
|
+
> 纯客户端重构:宿主(`src/host/*`)**一行未改**,v0.17 的 517 条测试照旧通过。
|
|
198
|
+
> ℹ️ v0.16 / v0.17 的坑是「包内这份 CHANGELOG 的对应行还写着 🚧 尚未发布」;**本版节首写成发布前后都成立
|
|
199
|
+
> 的说法**,包内那份读起来不自相矛盾。改这一行的提交仍在 publish 之后,**同一版本号不能再发一次**。
|
|
200
|
+
> tag / `gitHead` / `dist-tags` / 解包自测的逐条结果见 `03_发布/发布清单-v0.18.0.md` §四。
|
|
201
|
+
|
|
202
|
+
**Context Usage Lens(依据 2026-10-05 用户给的 V0.18 规格)**:
|
|
203
|
+
v0.17 的「使用情况」是一行统计文字 + 三块折叠列表 —— 信息都在,但**读不出结构**:
|
|
204
|
+
哪一层读得多、最近读的是哪一篇、包外那二十篇里哪几篇被反复读、这次变化是进是出。
|
|
205
|
+
这一版把它重做成文档列表**上方**的一块轻量观察层 —— 不是弹窗、不是新页面、不是 Dashboard:
|
|
206
|
+
|
|
207
|
+
```
|
|
208
|
+
使用情况 Epoch 5 ˄
|
|
209
|
+
335 次读取 · 29 篇包外 · 上下文变化 1 次
|
|
210
|
+
当前上下文
|
|
211
|
+
主要 1 / 1 辅助 2 / 3 相关 0 / 5
|
|
212
|
+
● ● ○ ○ ○ ○ ○ ○
|
|
213
|
+
最近读取 docs/eval.md 12分钟前 ›
|
|
214
|
+
上下文外读取 20 ›
|
|
215
|
+
上下文变化 最近一次 ›
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
展开包外 / 变化那两行之后(菜单式,`›` 变 `⌃`):
|
|
219
|
+
|
|
220
|
+
```
|
|
221
|
+
上下文外读取 20 ⌃
|
|
222
|
+
01 docs/old-plan.md ×3 已读
|
|
223
|
+
02 docs/test-case.md ×1 已读
|
|
224
|
+
还有 10 篇
|
|
225
|
+
上下文变化 最近一次 ⌃
|
|
226
|
+
进入
|
|
227
|
+
+ docs/algo.md
|
|
228
|
+
换层
|
|
229
|
+
↔ docs/eval.md · 辅助 → 相关
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
**没有分数、没有百分比、没有进度条、没有图表、没有新 Store、没有新采集**:
|
|
233
|
+
数据全部来自 v0.17 已有的 `usage.lifecycle / recentRead / outsideDocs / latestDelta` 与
|
|
234
|
+
`context` 的三层 rels,Coverage 是**派生**出来的(`coverageOf`)。
|
|
235
|
+
|
|
236
|
+
### 变化
|
|
237
|
+
- 新增 **Context Coverage**:主要 / 辅助 / 相关三层各给「状态点 + `已读数 / 本层总数`」,
|
|
238
|
+
点某一层 → 滚到那一层并**短暂高亮**(`data-knit-tier` + `.flash`,1200ms 自己收掉)。
|
|
239
|
+
Primary 不存在时整列不显示(**不画 `0 / 0` 的假层**);没有进度条、没有百分比。
|
|
240
|
+
- 文档行新增**行内生命周期 glyph**:未读 `○` / 已读 `●` / 读后已更新 `△` / 修改后已重新读取 `↻`
|
|
241
|
+
(形态在「UI 迭代」一节里改成 **6px 真圆点**,只有 `↻` 还是字符;四态靠 `data-mark` 区分)。
|
|
242
|
+
glyph 与原来那行文字**同时**存在(glyph 说状态,文字说次数 `×3`)。glyph 是真 `button`,
|
|
243
|
+
带 `title` / `aria-label`,点它=打开 / 选中这一篇(**已经打开则保持原预览**)。
|
|
244
|
+
统计**关掉**时这一格退回 v0.17 的 Primary 黑点 —— 与 v0.17 逐字一致。
|
|
245
|
+
- 最近读取从「一行文字」改成**一行可点的事实**(`文件名 · 相对时间 ›`),点它直接打开该篇,
|
|
246
|
+
点的那一下**不敲宿主**(走已有的 `requestPreview`)。语义仍是「**最近一次成功 read**」,
|
|
247
|
+
没有改成「正在阅读 / Agent 正在查看」。
|
|
248
|
+
- 上下文外读取改成可浏览集合:默认最多 10 篇 + 「还有 N 篇」,每行是可点对象并带生命周期;
|
|
249
|
+
排序改成 **`count DESC`**(同次数再按 `lastReadAt` / `seq`)—— 这是**事实排序**,不是相关度评分。
|
|
250
|
+
⚠️ 宿主给的顺序是「首次读的先后」(`outsideDocsOf` 按 `seq` 升序),所以排序发生在客户端纯函数
|
|
251
|
+
`groupOutsideDocs` 里,宿主不改。
|
|
252
|
+
- 上下文变化:默认只给一条菜单行(`上下文变化 最近一次 ›`,UI 迭代后条数不再写在按钮上),
|
|
253
|
+
展开后按 **进入 / 离开 / 换层** 分三组,
|
|
254
|
+
每组最多 5 条(沿用 v0.17 规则)。
|
|
255
|
+
- 顺手修掉一个潜在 bug:`moved` 的**真实载荷是 `{tier, rank}`**(v0.17 新增的宿主形状),
|
|
256
|
+
v0.17 的渲染直接把它当层名用 —— 真机上会渲染出空层名(`↔ x.md · →`)。现在两种载荷都认。
|
|
257
|
+
- Lens 自己可以展开 / 收起(`.knit-lens-head`,`aria-expanded`)。
|
|
258
|
+
**收起 ≠ 关掉统计**:收起只收起细节,标题 / Epoch / 摘要仍在;关掉才一个统计 DOM 都不产生。
|
|
259
|
+
- 面板矮(< `COMPACT_PANEL_PX` = 420px)时降级:不铺变化摘要,其余照旧。
|
|
260
|
+
滚动**仍然只交给 `.knit-list`** —— Lens 自己不滚动、**没有第二个滚动容器**。
|
|
261
|
+
- 新增纯函数 `coverageOf` / `groupOutsideDocs` / `groupDelta` / `lifeStatusOf`(能派生就不存储)。
|
|
262
|
+
- 验收取证时(2026-10-05)拿**真实会话载荷**跑了一次渲染,抓到三处「同一份事实讲两遍 /
|
|
263
|
+
讲不齐」,在发布前修掉 —— 都不是新功能,是这一版自己的渲染问题:
|
|
264
|
+
- 上下文变化**展开**后,折叠时那三行摘要 + 「还有 N 条」还在,后面又接了一遍分组明细
|
|
265
|
+
(同一批进出/换层条目出现两次)。现在展开就只渲染分组那一份(`deltaOpen ? null : …`)。
|
|
266
|
+
- 包外读取的行里次数说了两遍:`.knit-out-count` 已经是 `×71`,生命周期又用短次数说了一遍
|
|
267
|
+
→ 真机渲染成 `client.js ×71 ×71`。新增 `lifeWord()`:**次数已经在同一行时只用状态词**
|
|
268
|
+
(`… ×71 已读`),次数是这一档的排序键,必须留着;文档行的 `● ×3` 不受影响。
|
|
269
|
+
- 反过来的一处**讲不齐**:`任务上下文已更新` 只进了折叠摘要,展开后不见了 ——
|
|
270
|
+
可是当时按钮上的数字(`上下文变化 · N`)算上了它,于是「说 6 条、只列 5 行」。
|
|
271
|
+
现在展开时它也照常列一行(它在摘要里本来就是最后一条)。
|
|
272
|
+
- 顺手补了两条**英文渲染**守卫:v0.18 之前那条「英文整棵树里一个汉字都没有」用的是
|
|
273
|
+
没有 `usage` 的语料 ⇒ **Lens 整块没进渲染树**,几十条新文案(含 `title` / `aria-label`)
|
|
274
|
+
其实不在覆盖里。现在英文下把 Lens 真的打开、把两块折叠集合也点开再查一遍(空态另有一条)。
|
|
275
|
+
- 发布前又拿同一份真实载荷做了一次**不变式对账**(14 条:摘要 / Epoch / Coverage / 展开行数与唯一性 /
|
|
276
|
+
折叠尾巴 / 包外计数 / 四态同屏 / 无百分比与评分 / 不自己滚动)⇒ **14/14 通过**,
|
|
277
|
+
并把它里最通用的一条(**展开后列出的行 + 每条组内尾巴里的数字,必须等于载荷算出的总数**)立成了守卫,
|
|
278
|
+
这样上面那处「讲不齐」不会再从别的分支回来。
|
|
279
|
+
- 变化按钮上不再写条数(`上下文变化 · N` → `上下文变化 最近一次 ›`),账目改由
|
|
280
|
+
**展开后的行 + 尾巴**承担 —— 这样「说 N 条」与「列了几行」不可能再不一致。
|
|
281
|
+
|
|
282
|
+
### v0.18 UI 迭代(2026-10-06)
|
|
283
|
+
|
|
284
|
+
> 依据:用户给的 `02_方案与 Demo/dsh-knit V0.18 UI 重构开发提示词.md` + 同名 Demo HTML。
|
|
285
|
+
> 只动客户端外观(`src/client/client.js` 的 CSS / JSX / i18n 与对应测试),宿主一行未改;
|
|
286
|
+
> 功能、数据来源、DOM 的**语义**都不变 —— 这是把 v0.18 的 Lens 从「能用」改到「好看」。
|
|
287
|
+
|
|
288
|
+
- **字体尺度收成一套**:15(Usage 标题)/ 14(文档标题、Tabs)/ 13(Segmented、过滤框、
|
|
289
|
+
「当前上下文」分节标题)/ 12(摘要行、Coverage 层名与数字、最近读取)/ 11(生命周期、时间、
|
|
290
|
+
包外与变化的行)—— 不再有 10.5px / 11.5px 这类半档。
|
|
291
|
+
- **控件尺寸与描边**:`使用情况` / `刷新` 24px→**28px**(radius 8px);Segmented 与过滤框
|
|
292
|
+
22px / 24px → **28px**、radius 10px、字号 13px —— 原来那两个「迷你胶囊」是这一版最显眼的审美缺口。
|
|
293
|
+
Segmented 内部只保留控件自己的边框;Tab 下划线仍是 2px。
|
|
294
|
+
(提示词文档写的是 36px;2026-10-06 用户看了真机后定成 28px:「太高了,不需要这么高」。)
|
|
295
|
+
这两个控件的**描边色改用 `--dsw-alias-border-l3`** —— 与 DSH 主区「对话」页签下面那条横线
|
|
296
|
+
(官方 header 的 `border-bottom`,浅色 `rgba(0,0,0,.12)`)同一档;原来的 `l4` 重一档,
|
|
297
|
+
摆在页签下面像两个输入框把内容框住了(2026-10-06 用户要求「跟那条横一样」)。
|
|
298
|
+
描边**粗细也跟那条横对齐:0.5px**(官方那条本身就是 `.5px`;2026-10-06 用户第二轮要求
|
|
299
|
+
「描边色值修改成 0.5px」)。色对上了粗细没对上,高分屏上会比旁边那条横粗一倍 —— 三处
|
|
300
|
+
(Segmented 外框、内部竖线、过滤框)一起 0.5px,有守卫不许只改其中一处。
|
|
301
|
+
- **类型页签文案「图片与视频」→「媒体」**(2026-10-06 用户定;英文 `Images & video` → `Media`):
|
|
302
|
+
同一档的计数本来就是 `{n} 个媒体` / `{n} media`,页签是唯一的例外;「多媒体」暗示音频,
|
|
303
|
+
而这一档只扫图片与视频;含义由空态兜住(`list.emptyMedia` = 这个工作区里还没有图片或视频。)。
|
|
304
|
+
一个 i18n 键 `kind.media` 同时供页签与「全部」档的分区标题 ⇒ 改一处即两处,有守卫钉着。
|
|
305
|
+
- **状态点统一成 6px 真圆**:Coverage 的空心 / 实心点与文档行左侧的生命周期点
|
|
306
|
+
**同一套 token、同一个直径**(未读 = 透明 + 1px `label-caption` 边框,已读 = 同色填充,
|
|
307
|
+
读后已更新 = 实心 + 内圈,修改后已重新读取 = `↻` 字符)。没有任何绿 / 红 / 黄 / 蓝。
|
|
308
|
+
(文档写 9px,2026-10-06 用户定成 6px;守卫改为**比对两处直径**,不再各写各的。)
|
|
309
|
+
- **两处折叠集合改成菜单行**:`上下文外读取 20 ›` 与 `上下文变化 最近一次 ›`
|
|
310
|
+
(label 左、数量 / 说明右、`›` 展开变 `⌃`),行高 38px、hover 只改背景、无位移;
|
|
311
|
+
包外明细每行带 `01` / `02` 序号。**条数不再写在变化按钮上**(见上)。
|
|
312
|
+
- **定位手感**:点 Coverage 某层 → 平滑滚到**视口中部**(`block: 'center'`),高亮 **1200ms**
|
|
313
|
+
(原 900ms → 650ms → 2026-10-06 用户看真机后定成 1200ms);`prefers-reduced-motion: reduce`
|
|
314
|
+
下改为瞬时滚动、所有新过渡 `none`。⚠️ `FLASH_MS` 与 `.knit-tier{transition:background 1.2s}`
|
|
315
|
+
**必须同一个数**(有守卫;只改一个不会报错,只会看见「高亮已取消、背景还在慢慢褪」的错帧)。
|
|
316
|
+
- **窄侧栏不撑破**:Coverage 三列改成 `minmax(0, …)` 轨道,层名超长时省略号截断。
|
|
317
|
+
- **没做**(提示词文档明确禁止或与既有设计冲突):没有卡片化、没有阴影、没有上浮 / 缩放 /
|
|
318
|
+
连续脉冲、没有新滚动容器、没有新增数据、没有新模型或网络请求。
|
|
319
|
+
- **与 Demo 不一致的三处,按提示词文档办**:① Demo 给 Coverage 组画了淡底 + 1px 边框 +
|
|
320
|
+
hover `translateY(-1px)`,文档要求「默认不要 border、hover 最多很淡背景、不许 translate」;
|
|
321
|
+
② Demo 有可见的「未读 / N 篇已读」帮助行,文档要求那句只给读屏(现在只在 `aria-label` 里);
|
|
322
|
+
③ Demo 的 Usage 块有全宽 `border-bottom`,文档要求 Usage 内部不画全宽线。三处都听文档。
|
|
323
|
+
|
|
324
|
+
### 测试
|
|
325
|
+
- `npm test`:**532 / 532 通过**(v0.17 是 517)。新增 15 条 v0.18 守卫:
|
|
326
|
+
Coverage 三层数值与「点它定位到那一层」、Primary 缺席不画假层、Lens 收起、空使用情况、
|
|
327
|
+
小高度面板的降级判据、点状态点 / 包外行不直接请求列表、轮询不重播动画、
|
|
328
|
+
样式(语义 token / 自己不滚动 / `prefers-reduced-motion`)、纯函数层、
|
|
329
|
+
以及英文 Lens(打开态 / 空态)里没有汉字(文字 + 属性)。
|
|
330
|
+
- 一条**账目**守卫(刻意给 8 条换层以跨过组内上限):载荷算出的总数必须等于
|
|
331
|
+
「展开后列出的行数 + 每条组内尾巴里写的数字」—— 证伪过(把那一行改回 `false && …` 会有 3 条变红)。
|
|
332
|
+
- 宿主侧一行未改:v0.17 的 517 条全部照旧通过。
|
|
333
|
+
|
|
6
334
|
## [0.17.0] - 2026-10-03
|
|
7
335
|
|
|
8
|
-
>
|
|
9
|
-
>
|
|
336
|
+
> ✅ **2026-10-05 已发布**:`v0.17.0` = 轻量 tag = npm `gitHead` = `4d0c74e` · npm `latest = 0.17.0`
|
|
337
|
+
> · **43 文件 / 394.6 kB 打包 / 1.2 MB 解包** / shasum `33bf6faac4de75170e2378ff9096dd4cdb1da81a`。
|
|
338
|
+
> 由 **npm 可信发布(Trusted Publisher / OIDC)** 经 GitHub Actions 发出(带 provenance),不再用 token。
|
|
339
|
+
> ⚠️ **包内这份 CHANGELOG 里对应的那两行仍写着「🚧 尚未发布」** —— 本次改它的提交在 publish 之后,
|
|
340
|
+
> **同一版本号不能再发一次**(与 v0.16 同一个坑)。
|
|
10
341
|
|
|
11
342
|
**Document Lifecycle(依据 `01_ Knit PRD/Knit-PRD-SDD-v0.17-Document-Lifecycle.md`)**:
|
|
12
343
|
前面几版回答的是「Knit 推荐了什么 → Agent 有没有读 → 读落在哪一层」;
|
package/README.en.md
CHANGED
|
@@ -5,13 +5,15 @@
|
|
|
5
5
|
>
|
|
6
6
|
> **Your agent has the same problem.** It gets the same ranking as a tool — the ranked documents plus the passage that matched in each.
|
|
7
7
|
|
|
8
|
-

|
|
9
|
+
|
|
10
|
+
*Screenshot from a real machine, not a mock-up: the same workspace, this one left on the **Code tab** —
|
|
11
|
+
since v0.19 source files are first-class citizens, just like Markdown.*
|
|
12
|
+
*The "why" line under each row says how it matched: a direct hit on the task text, a path hit, or a
|
|
13
|
+
workspace hit.*
|
|
14
|
+
*Click a row to expand the preview **in place**: here `knit/src/host/classification.js`, with line
|
|
15
|
+
numbers; the preview header holds only the path and four actions (copy / full screen / open locally / close).*
|
|
16
|
+
*The header holds only the path, one count and two toggles; whether the list runs by
|
|
15
17
|
relevance or by newest-first is decided by that pair of tabs on the left.*
|
|
16
18
|
*Since v0.14 the list is always one column: the rank number sits in its own column on the far left
|
|
17
19
|
(vertically centred on the title's first line), then Primary dot + title + relative time (time on the
|
|
@@ -297,21 +299,23 @@ feature request.
|
|
|
297
299
|
|
|
298
300
|
| | |
|
|
299
301
|
|---|---|
|
|
302
|
+
| **Code Context** (v0.19): source files join the **same** retrieval pipeline as documents — classify, BM25, Context Pack, lifecycle. A dedicated classification layer decides what a file *is* and what it may do, so extension knowledge lives in exactly one place | ✅ |
|
|
300
303
|
| **Sorted by relevance to the current conversation** (BM25 + IDF, fully local, no model) | ✅ |
|
|
301
304
|
| **The `knit_docs` tool for the agent**: the model can look up this project's most relevant documents itself | ✅ |
|
|
302
305
|
| **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 | ✅ |
|
|
303
306
|
| One-click toggle between relevance / modification time (preference kept in localStorage) | ✅ |
|
|
304
|
-
| Scans
|
|
307
|
+
| Scans **documents and code** in the session workspace (recursive, depth ≤ 6, skips `node_modules` / `.git` / `dist` / `build` / `out` / `coverage`) | ✅ |
|
|
305
308
|
| Each row shows H1 title (or filename) + relative time + first-paragraph summary | ✅ |
|
|
306
309
|
| 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 | ✅ |
|
|
307
310
|
| Click to preview inline, click again to collapse | ✅ |
|
|
308
311
|
| Relative-path images actually render (`./img/a.png`, `../assets/b.png`) | ✅ |
|
|
309
|
-
| One-click switch between **Docs /
|
|
310
|
-
| Images & video: square thumbnail grid —
|
|
312
|
+
| One-click switch between **Docs / Code / Media / All** (v0.19 adds Code; remembered, defaults to Docs); the selected tab is an **underline tab**, deliberately different from the list row's grey fill | ✅ |
|
|
313
|
+
| Images & video: square thumbnail grid — cells have a **fixed 104px baseline independent of the item count**, columns come from CSS `repeat(auto-fill, minmax(104px, 1fr))`, and **as many rows as there are items are laid out** (no max height, the grid never scrolls itself — scrolling belongs to the list); videos auto-grab the first frame with a play glyph and duration badge (no deps, no transcoding) | ✅ |
|
|
314
|
+
| **"Web preview" for `.html`** (v0.19): the preview header hands the file to DSH's own document-preview tab (`openResource`) instead of showing source; the inline preview still shows source, so the two do not duplicate. Knit itself sends no request | ✅ |
|
|
311
315
|
| Click an image / video to preview **inline**: large image, playable & seekable video streamed over HTTP Range (no full download) | ✅ |
|
|
312
|
-
| The **All** view splits into **
|
|
316
|
+
| The **All** view splits into **three stacked sections**: docs (max 4, with "View all →" when truncated), **code** (max 4), then images & video (**never truncated**, count only) | ✅ |
|
|
313
317
|
| Preview pane is height-draggable (20%–80%, remembered), fullscreen-able, `Esc` to exit | ✅ |
|
|
314
|
-
| **"Open locally"
|
|
318
|
+
| **"Open locally"** opens the document in your default app; the **path in the preview header is clickable** and now opens the system file manager with the file **selected** (`action:'reveal'`), and its tooltip carries the full relative path | ✅ |
|
|
315
319
|
| Double-click opens in a new tab (the official document preview, with its PDF renderer and renderer switching) | ✅ |
|
|
316
320
|
| Filter box over title / summary / path | ✅ |
|
|
317
321
|
| **Click the workspace path** to open the project folder in your file manager | ✅ |
|
|
@@ -327,22 +331,24 @@ feature request.
|
|
|
327
331
|
|
|
328
332
|
### The other two views
|
|
329
333
|
|
|
330
|
-

|
|
331
335
|
|
|
332
|
-
*
|
|
333
|
-
six columns at this width, cells about
|
|
336
|
+
*Media: square thumbnails, with the **column count following the panel width continuously** —
|
|
337
|
+
six columns at this width, cells about 110px. These are the workspace's real image and SVG files; this
|
|
334
338
|
particular workspace happens to hold several screenshots, one demo GIF and one single-colour SVG icon
|
|
335
339
|
(the solid black square is that icon, not a failed load). Videos get their first frame as a poster with
|
|
336
340
|
a play glyph and a duration badge — this workspace simply has no video, so none shows here.*
|
|
337
341
|
|
|
338
|
-

|
|
339
343
|
|
|
340
|
-
*All: the documents section shows at most 4,
|
|
341
|
-
and
|
|
344
|
+
*All: the documents section shows at most 4, the **code section** shows at most 4 (each gets its own
|
|
345
|
+
"View all →" when truncated — here "4 / 19" and "4 / 17"), and the media grid comes last.*
|
|
342
346
|
|
|
343
|
-
⚠️
|
|
344
|
-
40th by relevance
|
|
345
|
-
|
|
347
|
+
⚠️ All three sections share the **same 40-item window** the host returns — a category that ranks past
|
|
348
|
+
40th by relevance drops out of the All view entirely. This screenshot uses the **Newest** sort: in this
|
|
349
|
+
workspace, under the default Relevance sort, media rank outside that window every time (at `limit=40`
|
|
350
|
+
those 40 rows are 34 documents + 6 code files). The **Media** and **Code** tabs are unaffected — they
|
|
351
|
+
request their own kind. A known defect, with reproduction and the fix recorded in
|
|
346
352
|
[`docs/README.md`](docs/README.md).*
|
|
347
353
|
|
|
348
354
|
---
|
|
@@ -356,11 +362,13 @@ v0.16 nails that down: **attribution is settled and frozen at read time** — ho
|
|
|
356
362
|
changes later, the historical numbers never change their story (in v0.15 a read could be
|
|
357
363
|
re-judged as "outside" by the present, which was a bug).
|
|
358
364
|
|
|
359
|
-
**Off by default.** There is a "Usage" toggle in the panel head; turning it on adds
|
|
360
|
-
above the list
|
|
365
|
+
**Off by default.** There is a "Usage" toggle in the panel head; turning it on adds a lightweight
|
|
366
|
+
**lens** above the list (called the Usage Lens since v0.18 — see "reading the usage" below).
|
|
367
|
+
Its top line still reports facts only:
|
|
361
368
|
|
|
362
369
|
```
|
|
363
|
-
|
|
370
|
+
Usage Epoch 5 ˄
|
|
371
|
+
174 reads · 28 outside the pack · context changed 3×
|
|
364
372
|
```
|
|
365
373
|
|
|
366
374
|
- **Context Epoch**: one **content-changed** context equals one epoch (identical content creates
|
|
@@ -401,10 +409,14 @@ To check offline: `node tools/context-feedback-eval.mjs` replays the latest real
|
|
|
401
409
|
|
|
402
410
|
### v0.17: what state is a document in, after it has been read?
|
|
403
411
|
|
|
404
|
-
Turning "Usage" on adds two more things besides the
|
|
412
|
+
Turning "Usage" on adds two more things besides the counts: **a status on each recommended
|
|
405
413
|
document**, and "which one was read last / what was read outside the pack / how the context last
|
|
406
414
|
changed".
|
|
407
415
|
|
|
416
|
+
> ⚠️ The ASCII below is the **v0.17 shape** of this UI. v0.18 rebuilt it into the Usage Lens above
|
|
417
|
+
> the list (next section) — **the criteria, the four states and the data sources did not change**;
|
|
418
|
+
> this section is about the data and the judgement.
|
|
419
|
+
|
|
408
420
|
```
|
|
409
421
|
Context · Epoch 4
|
|
410
422
|
Recently read: SDD-v0.17.md · 12 min ago
|
|
@@ -455,14 +467,97 @@ All four states are **facts**, not scores:
|
|
|
455
467
|
for reduced motion. This is not a new feature — it only makes "who arrived, who left, who moved"
|
|
456
468
|
visible. Indexing, ranking, tiers and the `knit_docs` output are unchanged.
|
|
457
469
|
|
|
470
|
+
### v0.18: reading the usage (Context Usage Lens)
|
|
471
|
+
|
|
472
|
+
v0.17 had all the information, but **crammed into one line and a few collapsed blocks** — you could
|
|
473
|
+
not read the structure: which tier got read, which document was read last, which of those twenty
|
|
474
|
+
outside documents were read over and over, whether the last change was an arrival or a departure.
|
|
475
|
+
v0.18 rebuilds it as a lightweight **lens above the list** — not a dialog, not a new page, and not a
|
|
476
|
+
dashboard:
|
|
477
|
+
|
|
478
|
+
```
|
|
479
|
+
Usage Epoch 5 ˄
|
|
480
|
+
174 reads · 28 outside the pack · context changed 3×
|
|
481
|
+
Current context
|
|
482
|
+
Primary 1 / 1 Supporting 2 / 3 Related 0 / 5
|
|
483
|
+
● ● ○ ○ ○ ○ ○ ○
|
|
484
|
+
Recent read docs/eval.md 12 min ago ›
|
|
485
|
+
Reads outside context 20 ›
|
|
486
|
+
Context changes Latest ›
|
|
487
|
+
```
|
|
488
|
+
|
|
489
|
+
- **Current-context coverage**: each tier gives "a state dot + `read / total in that tier`". Clicking
|
|
490
|
+
a tier scrolls to that tier and **flashes it briefly** (no arrows, no rules — space says "here").
|
|
491
|
+
**Facts only**: no progress bar, no percentage — Knit does not judge whether a context is "used up",
|
|
492
|
+
and when there is no Primary the whole column is hidden rather than drawing a fake `0 / 0`.
|
|
493
|
+
- **Inline state dot**: unread = hollow circle / read = filled circle / updated after read = filled
|
|
494
|
+
circle with an inner ring / re-read after update = `↻`, shown **alongside** the text (the dot states
|
|
495
|
+
the state, the text states the count). Clicking it opens that document. No red/green, no badge.
|
|
496
|
+
The coverage dots and this one share **the same tokens and the same 6px diameter** — one state language.
|
|
497
|
+
- **Recent read** is a clickable fact row (`file · relative time ›`) that opens that document directly
|
|
498
|
+
and **does not refetch the list**. It is still "the **last successful read**" — never "currently reading".
|
|
499
|
+
- **Reads outside context** shows up to 10 by default plus "N more"; every row is clickable and carries
|
|
500
|
+
its state, sorted by **most-read first** (`count DESC`) — a fact order, not a relevance score. You
|
|
501
|
+
**cannot** promote a document into the context from here (V0.18 does no context control).
|
|
502
|
+
- **Context changes** is collapsed by default; expanding groups it into Entered / Left / Moved tier,
|
|
503
|
+
at most 5 per group, and only the **latest** delta is shown.
|
|
504
|
+
- The lens itself expands / collapses. **Collapsing is not turning usage off** — collapsing means
|
|
505
|
+
"counting, but I do not want the details"; switching the toggle off produces no usage DOM at all.
|
|
506
|
+
- On a short panel (< 420px) it degrades to summary + coverage + recent read; the change details are
|
|
507
|
+
still one click away, and **scrolling always belongs to the list** — there is no second scroll
|
|
508
|
+
container, so a narrow sidebar never gets scroll-inside-scroll.
|
|
509
|
+
|
|
510
|
+
Not one new fact was added: everything comes from the v0.17 `lifecycle / recentRead / outsideDocs /
|
|
511
|
+
latestDelta` fields plus the current `context` tiers, and coverage is **derived** from them (pure
|
|
512
|
+
functions `coverageOf` / `groupOutsideDocs` / `groupDelta`).
|
|
513
|
+
|
|
458
514
|
The `knit_docs` tool output **did not grow**: it still only finds context.
|
|
459
515
|
|
|
460
516
|
---
|
|
461
517
|
|
|
518
|
+
### v0.19: code as context (Code Context)
|
|
519
|
+
|
|
520
|
+
Until v0.18 Knit understood Markdown, images and video. v0.19's product concept becomes
|
|
521
|
+
**documents / code / media** — not "a few more extensions", but letting Knit put the source files an
|
|
522
|
+
AI-coding task actually needs into the same Context Pack, on the same main line:
|
|
523
|
+
|
|
524
|
+
```text
|
|
525
|
+
Current task -> Workspace Retrieval -> Document + Code Candidates
|
|
526
|
+
-> Primary / Supporting / Related -> Context Pack -> Agent Read
|
|
527
|
+
-> Read Evidence -> File Changed -> Lifecycle -> Context Epoch / Delta -> Usage Lens
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
- **One classification layer, not scattered `if (ext === '.js')`** — `src/host/classification.js`
|
|
531
|
+
turns a filename into `{ kind, language, previewable, searchable, contextual, generated,
|
|
532
|
+
sourceMap }`. The scanner, retrieval, preview and UI all just read that verdict.
|
|
533
|
+
- **Supported in v0.19**: `.js .mjs .cjs .ts .tsx .jsx .py .json .html .htm .css .scss .yaml .yml
|
|
534
|
+
.sh .bash .zsh`. **Not yet**: `.go .rs .java .kt .c .cpp .h .hpp .cs .php .rb .swift .sql`.
|
|
535
|
+
- **Code gets its own field weights** — filename x4, path x2, body (first 8 KB) x1, instead of the
|
|
536
|
+
document weights (title x4 / summary x2 / body x1). A filename like `context-manager.ts` carries
|
|
537
|
+
the task signal.
|
|
538
|
+
- **Generated files are not context**: `.map`, `*.min.js`, `*.min.css`, `*.bundle.js`,
|
|
539
|
+
`*.generated.js`, `*.gen.js`, `*.lock` classify as `generated` — previewable, but never in
|
|
540
|
+
retrieval, the Context Pack or the Usage Lens. When `app.js` and `app.js.map` both exist, the
|
|
541
|
+
`app.js` preview offers one low-key **"Source map"** entry; the `.map` never shows up as a row.
|
|
542
|
+
**Context eligibility is not file-system visibility** — the built-in file tree still opens them.
|
|
543
|
+
- **Bounded and capped**: at most `MAX_CODE = 300` code candidates and a head-limited body read, so
|
|
544
|
+
a large repo cannot flood the Markdown corpus. Corpus pressure is the thing to watch in this
|
|
545
|
+
version, not recall.
|
|
546
|
+
- **The type tabs become four**: `Docs / Code / Media / All`. The Code tab is **still driven by the
|
|
547
|
+
current task** — it is not a file tree of the project.
|
|
548
|
+
- **No second engine**: no second retrieval path, no second lifecycle, no second store, no new
|
|
549
|
+
dependencies, no AST, no LSP, no embedding, no model call, no network, no IDE.
|
|
550
|
+
|
|
551
|
+
---
|
|
552
|
+
|
|
462
553
|
## What it reads, and what it doesn't
|
|
463
554
|
|
|
464
|
-
- Scans
|
|
465
|
-
outside is rejected); for media it reads metadata only,
|
|
555
|
+
- Scans Markdown, **supported code files** (see the v0.19 list above) and media **inside the current
|
|
556
|
+
session workspace** (anything resolving outside is rejected); for media it reads metadata only,
|
|
557
|
+
never the pixels, and for code it reads a **bounded head** of the body, never the whole file
|
|
558
|
+
- **Generated / noisy files are excluded from context** (`.map`, `*.min.*`, `*.bundle.*`,
|
|
559
|
+
`*.generated.*`, `*.lock`): they classify as `generated`, so they never enter retrieval, the
|
|
560
|
+
Context Pack or the Usage Lens — but `/knit/api/doc` still serves them when you open one on purpose
|
|
466
561
|
- Reads only **the current session's** conversation events (used for ranking)
|
|
467
562
|
- The `knit_docs` tool is **read-only**: it writes no files and persists no index
|
|
468
563
|
- v0.15 usage accounting is **off by default**: when enabled it reads only the **current session's
|
|
@@ -471,9 +566,10 @@ The `knit_docs` tool output **did not grow**: it still only finds context.
|
|
|
471
566
|
the plugin's own same-origin routes
|
|
472
567
|
- **No install-time scripts** (no `install` / `postinstall`)
|
|
473
568
|
- **Zero dependencies** — nothing to build, no build-authorisation prompt
|
|
474
|
-
- The
|
|
569
|
+
- The media route only allows an **image/video-extension allowlist** (images ≤ 12MB,
|
|
475
570
|
video ≤ 256MB), serves video over HTTP Range, and responds with
|
|
476
|
-
`nosniff` plus `default-src 'none'; sandbox
|
|
571
|
+
`nosniff` plus `default-src 'none'; sandbox`; the **text route serves documents, code and
|
|
572
|
+
generated artifacts**, and refuses media and unknown extensions
|
|
477
573
|
|
|
478
574
|
The relevance figure only affects ordering — it is **never displayed and never sent anywhere**.
|
|
479
575
|
|
|
@@ -514,7 +610,7 @@ The relevance figure only affects ordering — it is **never displayed and never
|
|
|
514
610
|
git clone https://github.com/PolinniZhong/dsh-knit.git
|
|
515
611
|
cd dsh-knit
|
|
516
612
|
|
|
517
|
-
npm test #
|
|
613
|
+
npm test # 588 tests, zero dependencies, no npm install needed
|
|
518
614
|
```
|
|
519
615
|
|
|
520
616
|
**How changes take effect**: the host half (`src/host/`) **requires a DSH restart** (no hot reload);
|
|
@@ -534,11 +630,12 @@ knit/
|
|
|
534
630
|
│ ├── host/index.js # /knit/api/recent · /doc · /raw · /links · /context
|
|
535
631
|
│ ├── host/relevance.js # the relevance engine: BM25 + keyword extraction
|
|
536
632
|
│ ├── host/links.js # reference parsing (pure; never touches ranking)
|
|
633
|
+
│ ├── host/classification.js # v0.19 file classification: kind / language / searchable / contextual
|
|
537
634
|
│ ├── host/context.js # context assembly: the three-tier Context Pack (pure, zero I/O)
|
|
538
635
|
│ ├── host/feedback.js # usage feedback: read-time attribution / Context Epoch / delta (pure)
|
|
539
636
|
│ ├── host/tool.js # the agent tool knit_docs (hand-written ToolDefinition)
|
|
540
637
|
│ └── client/client.js # dual-host registration + panel UI
|
|
541
|
-
└── test/ #
|
|
638
|
+
└── test/ # 588 tests
|
|
542
639
|
├── eval/ # retrieval quality: corpus + cases + frozen v0.5.2 baseline
|
|
543
640
|
└── context/ # context tiering: 24-doc corpus + 12 real-task cases
|
|
544
641
|
```
|