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.
@@ -31,6 +31,8 @@ window.__ModuleLoader__.load({
31
31
 
32
32
  'count': '{n} 篇',
33
33
  'count.filtered': '{hit} / {total} 篇',
34
+ 'count.code': '{n} 个代码文件',
35
+ 'count.code.filtered': '{hit} / {total} 个代码文件',
34
36
  'count.media': '{n} 个媒体',
35
37
  'count.media.filtered': '{hit} / {total} 个媒体',
36
38
  'count.all': '{n} 项',
@@ -47,7 +49,17 @@ window.__ModuleLoader__.load({
47
49
 
48
50
  'kind.all': '全部',
49
51
  'kind.doc': '文档',
50
- 'kind.media': '图片与视频',
52
+ // v0.19:「代码」这一档。文案口径刻意保持朴素 —— 不写「代码知识库 / AI Code
53
+ // Intelligence / 智能代码分析」。Knit 只是把**当前任务真正需要的**代码文件
54
+ // 纳入同一份 Context Pack,它不是代码浏览器、不是 grep、不是 IDE(需求 §44)。
55
+ 'kind.code': '代码',
56
+ // ⚠️ 2026-10-06 用户定:类型页签与「全部」分区标题都用**「媒体」**,不用「图片与视频」
57
+ // (原话:「我想修改成 媒体 或者 多媒体,你觉得呢?」→ 随后确认「媒体」)。
58
+ // 理由:① 这一档的计数本来就是「{n} 个媒体」(count.media),页签叫「图片与视频」
59
+ // 是唯一的例外;② 「多媒体」在中文 IT 语境里带 AV / 课件味,还暗示音频,而这一档
60
+ // 只扫图片与视频(宿主按扩展名放行,没有音频);③ 「媒体」省 3 个字,窄侧栏少一次
61
+ // 省略号。**含义由空态说明**(list.emptyMedia 仍写「还没有图片或视频」)。
62
+ 'kind.media': '媒体',
51
63
  'kind.title': '切换要列出的产物类型',
52
64
 
53
65
  'filter.placeholder': '过滤文档',
@@ -56,24 +68,42 @@ window.__ModuleLoader__.load({
56
68
  'usage.toggle': '使用情况',
57
69
  'usage.toggleTitle': '打开后开始统计这个会话:先看的那篇有没有被读、有多少次读落在包外、上下文换过几回。只记事实,不给分数。',
58
70
  'usage.none': '还没有记录',
59
- 'usage.epoch': '当前上下文 · Epoch {n}',
60
- 'usage.primaryRead': '先看的「{rel}」已读',
61
- 'usage.primaryUnread': '先看的「{rel}」还没读',
62
- 'usage.supporting': '辅助 {read}/{total}',
63
- 'usage.reads': '读了 {n} 次',
64
- 'usage.outside': '包外 {n} 篇',
65
- 'usage.changes': '上下文换过 {n} 次',
66
71
  'usage.note': '只统计本会话 · 数据在内核内存里,重启 DSH 就没了',
67
72
 
73
+ // ── v0.18 Context Usage Lens ────────────────────────────────
74
+ // 这一层只回答一件事:「Knit 交出去的那份 Context,被怎样消费了」。
75
+ // ⚠️ 它**不是** Dashboard:没有 KPI 大数字、没有百分比、没有评分、没有图表、
76
+ // 没有进度条、没有「使用率 / 健康度 / 认可度」。字号一律弱于文档标题 ——
77
+ // 层级只靠空间与灰阶(AGENTS.md §6.3 / §7.1)。
78
+ // ⚠️ 每一条都是**事实陈述**,不是评价:不许写成「Agent 没看这篇 / 用错了 /
79
+ // Knit 漏了 / 推荐得不准」。「最近读取」也不是「正在阅读」—— 证明不了。
80
+ 'lens.title': '使用情况',
81
+ 'lens.expand': '展开使用情况',
82
+ 'lens.collapse': '收起使用情况',
83
+ 'lens.epoch': 'Epoch {n}',
84
+ 'lens.reads': '{n} 次读取',
85
+ 'lens.outside': '{n} 篇包外',
86
+ 'lens.changes': '上下文变化 {n} 次',
87
+ 'lens.currentContext': '当前上下文',
88
+ 'lens.recentRead': '最近读取',
89
+ 'lens.recentNone': '暂无记录',
90
+ 'lens.outsideDocs': '上下文外读取',
91
+ 'lens.more': '还有 {n} 篇',
92
+ 'lens.openDoc': '打开 {rel}',
93
+ 'lens.delta': '上下文变化',
94
+ 'lens.locate': '定位到{tier}上下文',
95
+ // 读屏专用(md §六十三):**屏幕上不出现这句话**,视觉给的是「层名 + n / m + 圆点」。
96
+ 'lens.coverageAria': '{tier}上下文:{read} / {total} 篇已读',
97
+ // 上下文变化那一行的右侧说明(md §三十八「上下文变化 最近一次 ›」):
98
+ // 变化永远只说**最近一次**,所以这里不写条数(条数由展开后的行数承担)。
99
+ 'lens.deltaLatest': '最近一次',
100
+
68
101
  // ── v0.17 文档生命周期(Document Lifecycle)──────────────────
69
102
  // ⚠️ 四态全是**事实**,不是评价:「读后已更新」只说「文件在最后一次成功读取之后
70
103
  // 变过」,绝不许写成「Agent 还不知道最新版本」「Agent 用了旧版本」这类推断。
71
- // ⚠️ 「最近读取」不是「正在阅读」—— Knit 证明不了 Agent 此刻是否还在读它。
72
- // ⚠️ 「上下文外读取」只陈述「这篇不在当前包内、但被成功读过」,
73
- // 不许写成「Knit 漏了 / 推荐错了 / 命中率低」。
74
- 'usage.recentRead': '最近读取:{rel} · {time}',
75
- 'usage.outsideDocs': '上下文外读取 · {n} 篇',
76
- 'usage.deltaTitle': '上下文刚刚变化',
104
+ // ⚠️ 「上下文外读取」只陈述「这篇不在当前包内、但被成功读过」。
105
+ // ⚠️ `readCountShort` 是给行尾用的:行首的 glyph 已经说了「读过了」,
106
+ // 行尾只需要补一个「几次」—— 再说一遍「已读」是重复信息。
77
107
  'usage.deltaEnter': '进入',
78
108
  'usage.deltaLeave': '离开',
79
109
  'usage.deltaMove': '换层',
@@ -82,6 +112,7 @@ window.__ModuleLoader__.load({
82
112
  'lifecycle.unread': '未读',
83
113
  'lifecycle.read': '已读',
84
114
  'lifecycle.readCount': '已读 ×{n}',
115
+ 'lifecycle.readCountShort': '×{n}',
85
116
  'lifecycle.updatedAfterRead': '读后已更新',
86
117
  'lifecycle.rereadAfterUpdate': '修改后已重新读取',
87
118
  'tierName.primary': '主要',
@@ -112,6 +143,12 @@ window.__ModuleLoader__.load({
112
143
  // 读起来像调试信息。现在它是**标签 + 值**,词之间用「 · 」分隔。
113
144
  'why.direct': '直接命中:{term}',
114
145
  'why.titleMatch': '标题命中:{term}',
146
+ // v0.19:代码占的是 `title` / `summary` 两个槽位(文件名、所在目录),
147
+ // 但**不能**对 `.ts` 文件说「标题命中」—— 判据一样,称谓必须分开。
148
+ // 这两个码由宿主直接给出(`context.js` 的 `explainContext()`),
149
+ // 客户端不做 kind → key 的重映射:宿主给什么码就翻什么码。
150
+ 'why.filenameMatch': '文件名命中:{term}',
151
+ 'why.pathMatch': '路径命中:{term}',
115
152
  'why.summaryMatch': '摘要命中:{term}',
116
153
  'why.bodyMatch': '正文命中:{term}',
117
154
  'why.bodyMatchPlain': '正文命中',
@@ -126,6 +163,7 @@ window.__ModuleLoader__.load({
126
163
  'list.failed': '读取失败:{error}',
127
164
  'list.failedHint': '确认插件宿主半边已加载。',
128
165
  'list.empty': '这个工作区里还没有 Markdown 文档。',
166
+ 'list.emptyCode': '这个工作区里还没有可纳入上下文的代码文件。',
129
167
  'list.emptyMedia': '这个工作区里还没有图片或视频。',
130
168
  'list.noMatch': '没有匹配「{query}」的文档。',
131
169
  // 文档列表这个 listbox 的无障碍名字(原先硬编码在 JSX 里,英文界面下会漏出中文)
@@ -152,9 +190,31 @@ window.__ModuleLoader__.load({
152
190
  'preview.exitFullscreen': '退出全屏',
153
191
  'preview.fullscreenTitle': '全屏阅读',
154
192
  'preview.exitFullscreenTitle': '退出全屏(Esc)',
193
+ // v0.19 追加:HTML 的「网页预览」入口。
194
+ // 就地预览给的是**源码**,这个按钮开的是**官方文档预览标签页** ——
195
+ // 那一侧有 DSH 自带的 HTML 渲染器(`extensions:['html','htm']`,默认走静态档:
196
+ // 清洗过的完整文档 + 不给任何 sandbox 权限的 iframe + 摆在 `<head>` 最前的 CSP,
197
+ // 挡脚本 / 外部资源 / 表单 / 嵌套框架,内联 `<style>` 与 `data:` 图片保留)。
198
+ // 两者**不重复**,所以它不是把 v0.10 撤掉的那个「新标签页」按钮原样搬回来。
199
+ 'preview.openWeb': '网页预览',
200
+ 'preview.openWebTitle': '{path}\n在官方文档预览里按网页渲染',
155
201
  'preview.openLocal': '{path}\n用系统默认应用打开这篇文档',
156
202
  'preview.openLocalBtn': '本地打开',
203
+ // 面包屑那条路径点开的是**文件管理器里这个文件所在的位置**(并把文件选中),
204
+ // 不是「打开文件」—— 那是页脚「本地打开」的事,所以文案也得说清。
205
+ 'preview.reveal': '{path}\n在文件管理器中显示并选中这个文件',
157
206
  'preview.close': '收起预览',
207
+ // v0.19:同名 source map 的入口。**它是低权重动作,不是文件列表条目** ——
208
+ // `.map` 不参与检索、不进上下文、不进代码列表(需求 §6 §28),
209
+ // 只有用户在这个 .js 的预览里主动点它才会打开,且以纯文本/JSON 呈现。
210
+ 'preview.sourceMap': 'Source map',
211
+ 'preview.sourceMapTitle': '查看同名 source map(不进入上下文检索)',
212
+ // v0.19:代码预览的两条边界提示。
213
+ // `codeTruncated` —— 渲染侧的行数上限(与宿主 512 KB 字节上限是两道不同的闸门)。
214
+ // `copyFailed` —— 剪贴板两条路都失败时才出现。**不能静默**:点了没反应,
215
+ // 用户会以为是按钮坏了,而不是「浏览器不给权限」。
216
+ 'preview.codeTruncated': '(文件较大,仅显示前 {n} 行)',
217
+ 'preview.copyFailed': '复制失败,请手动选择文本',
158
218
  'preview.resizeTitle': '拖动调整高度',
159
219
  // v0.12 引用条。⚠️ 不放任何表情符号(test/i18n.test.mjs 有守卫)。
160
220
  'links.summary': '被引用 {in} · 引用了 {out}',
@@ -179,7 +239,9 @@ window.__ModuleLoader__.load({
179
239
  'error.bsEditorDisabled': 'better-sidebar 的「编辑器」标签页被禁用了(设置 → 侧边卡片)',
180
240
 
181
241
  'host.outsideWorkspace': '路径越出工作区',
182
- 'host.markdownOnly': '只支持 Markdown',
242
+ // v0.19:从 `host.markdownOnly`(「只支持 Markdown」)改名。能力已经不止
243
+ // Markdown 了,文案必须跟着说清**真正的**边界:这个类型不支持在面板里预览。
244
+ 'host.notPreviewable': '这个类型不支持在面板里预览',
183
245
  'host.notFound': '文件不存在',
184
246
  'host.notAFile': '不是普通文件',
185
247
  'host.imageOnly': '只允许图片类型',
@@ -200,6 +262,8 @@ window.__ModuleLoader__.load({
200
262
 
201
263
  'count': '{n} docs',
202
264
  'count.filtered': '{hit} / {total} docs',
265
+ 'count.code': '{n} code files',
266
+ 'count.code.filtered': '{hit} / {total} code files',
203
267
  'count.media': '{n} media',
204
268
  'count.media.filtered': '{hit} / {total} media',
205
269
  'count.all': '{n} items',
@@ -216,7 +280,11 @@ window.__ModuleLoader__.load({
216
280
 
217
281
  'kind.all': 'All',
218
282
  'kind.doc': 'Docs',
219
- 'kind.media': 'Images & video',
283
+ 'kind.code': 'Code',
284
+ // 2026-10-06: user picked 「媒体」 for the tab + the "All" section title, so English
285
+ // follows the same word as count.media ("{n} media"): the tab says Media, and the
286
+ // explicit "images and videos" wording stays in the empty state / README prose.
287
+ 'kind.media': 'Media',
220
288
  'kind.title': 'Switch which artifacts are listed',
221
289
 
222
290
  'filter.placeholder': 'Filter docs',
@@ -225,24 +293,37 @@ window.__ModuleLoader__.load({
225
293
  'usage.toggle': 'Usage',
226
294
  'usage.toggleTitle': 'Measure this session: whether the primary doc was read, how many reads fell outside the pack, how often the context changed. Facts only — no score.',
227
295
  'usage.none': 'Nothing recorded yet',
228
- 'usage.epoch': 'Context · Epoch {n}',
229
- 'usage.primaryRead': 'primary read ({rel})',
230
- 'usage.primaryUnread': 'primary not read yet ({rel})',
231
- 'usage.supporting': 'supporting {read}/{total}',
232
- 'usage.reads': '{n} reads',
233
- 'usage.outside': '{n} outside the pack',
234
- 'usage.changes': 'context changed {n}×',
235
296
  'usage.note': 'This session only · kept in kernel memory, gone after a DSH restart',
236
297
 
298
+ // ── v0.18 Context Usage Lens ───────────────────────────────
299
+ // Answers exactly one question: how was the context Knit handed over actually
300
+ // consumed. ⚠️ Not a dashboard: no KPI figures, no percentages, no scores, no
301
+ // charts, no progress bars, no "usage rate / health / confidence". Every line is
302
+ // a fact, never a judgement — and "recent read" is not "currently reading".
303
+ 'lens.title': 'Usage',
304
+ 'lens.expand': 'Expand usage',
305
+ 'lens.collapse': 'Collapse usage',
306
+ 'lens.epoch': 'Epoch {n}',
307
+ 'lens.reads': '{n} reads',
308
+ 'lens.outside': '{n} outside the pack',
309
+ 'lens.changes': 'context changed {n}×',
310
+ 'lens.currentContext': 'Current context',
311
+ 'lens.recentRead': 'Recent read',
312
+ 'lens.recentNone': 'Nothing yet',
313
+ 'lens.outsideDocs': 'Reads outside context',
314
+ 'lens.more': '{n} more',
315
+ 'lens.openDoc': 'Open {rel}',
316
+ 'lens.delta': 'Context changes',
317
+ 'lens.locate': 'Locate {tier} context',
318
+ 'lens.coverageAria': '{tier} context: {read} / {total} read',
319
+ 'lens.deltaLatest': 'Latest',
320
+
237
321
  // ── v0.17 document lifecycle ───────────────────────────────
238
322
  // ⚠️ All four states are facts, never judgements: "Updated after read" only says the
239
323
  // file changed after the last successful read. Never "the agent has not seen the
240
324
  // latest version" or "the agent used a stale copy" — that would be inference.
241
- // ⚠️ "Recently read" is not "currently reading": Knit cannot prove the agent is
242
- // still reading it. An out-of-pack file is shown as-is, with no explanation.
243
- 'usage.recentRead': 'Recently read: {rel} · {time}',
244
- 'usage.outsideDocs': 'Read outside the pack · {n}',
245
- 'usage.deltaTitle': 'Context just changed',
325
+ // ⚠️ `readCountShort` is for the row tail: the leading glyph already says it was
326
+ // read, so the tail only adds the count — repeating "read" would be redundant.
246
327
  'usage.deltaEnter': 'Entered',
247
328
  'usage.deltaLeave': 'Left',
248
329
  'usage.deltaMove': 'Moved tier',
@@ -251,6 +332,7 @@ window.__ModuleLoader__.load({
251
332
  'lifecycle.unread': 'Unread',
252
333
  'lifecycle.read': 'Read',
253
334
  'lifecycle.readCount': 'Read ×{n}',
335
+ 'lifecycle.readCountShort': '×{n}',
254
336
  'lifecycle.updatedAfterRead': 'Updated after read',
255
337
  'lifecycle.rereadAfterUpdate': 'Re-read after update',
256
338
  'tierName.primary': 'Primary',
@@ -278,6 +360,8 @@ window.__ModuleLoader__.load({
278
360
  // ⚠️ Flattened on 2026-09-29: "direct topic match: …" read like debug output.
279
361
  'why.direct': 'direct match: {term}',
280
362
  'why.titleMatch': 'title match: {term}',
363
+ 'why.filenameMatch': 'filename match: {term}',
364
+ 'why.pathMatch': 'path match: {term}',
281
365
  'why.summaryMatch': 'summary match: {term}',
282
366
  'why.bodyMatch': 'body match: {term}',
283
367
  'why.bodyMatchPlain': 'body match',
@@ -292,6 +376,7 @@ window.__ModuleLoader__.load({
292
376
  'list.failed': 'Failed to read: {error}',
293
377
  'list.failedHint': 'Make sure the plugin’s host half is loaded.',
294
378
  'list.empty': 'No Markdown documents in this workspace yet.',
379
+ 'list.emptyCode': 'No code files eligible for context in this workspace yet.',
295
380
  'list.emptyMedia': 'No images or videos in this workspace yet.',
296
381
  'list.noMatch': 'No documents match “{query}”.',
297
382
  // Accessible name of the document listbox (was hardcoded in JSX before)
@@ -319,9 +404,16 @@ window.__ModuleLoader__.load({
319
404
  'preview.exitFullscreen': 'Exit fullscreen',
320
405
  'preview.fullscreenTitle': 'Read fullscreen',
321
406
  'preview.exitFullscreenTitle': 'Exit fullscreen (Esc)',
407
+ 'preview.openWeb': 'Web preview',
408
+ 'preview.openWebTitle': '{path}\nRender as a web page in the official document preview',
322
409
  'preview.openLocal': '{path}\nOpen this document in your default app',
323
410
  'preview.openLocalBtn': 'Open locally',
411
+ 'preview.reveal': '{path}\nShow this file in your file manager (and select it)',
324
412
  'preview.close': 'Close preview',
413
+ 'preview.sourceMap': 'Source map',
414
+ 'preview.sourceMapTitle': 'View the sibling source map (not part of context retrieval)',
415
+ 'preview.codeTruncated': '(large file — showing the first {n} lines)',
416
+ 'preview.copyFailed': 'Copy failed — select the text manually',
325
417
  'preview.resizeTitle': 'Drag to resize',
326
418
  'links.summary': 'Referenced by {in} · links to {out}',
327
419
  'links.incoming': 'Referenced by',
@@ -345,7 +437,7 @@ window.__ModuleLoader__.load({
345
437
  'error.bsEditorDisabled': 'better-sidebar’s Editor tab is disabled (Settings → Side card)',
346
438
 
347
439
  'host.outsideWorkspace': 'Path escapes the workspace',
348
- 'host.markdownOnly': 'Markdown only',
440
+ 'host.notPreviewable': 'This type cannot be previewed here',
349
441
  'host.notFound': 'File not found',
350
442
  'host.notAFile': 'Not a regular file',
351
443
  'host.imageOnly': 'Images only',
@@ -384,7 +476,7 @@ window.__ModuleLoader__.load({
384
476
  */
385
477
  const HOST_ERROR_KEY = {
386
478
  'knit/outside-workspace': 'host.outsideWorkspace',
387
- 'knit/markdown-only': 'host.markdownOnly',
479
+ 'knit/not-previewable': 'host.notPreviewable',
388
480
  'knit/not-found': 'host.notFound',
389
481
  'knit/not-a-file': 'host.notAFile',
390
482
  'knit/image-only': 'host.imageOnly',
@@ -465,11 +557,37 @@ window.__ModuleLoader__.load({
465
557
  */
466
558
  const USAGE_KEY = 'dsh-knit:usage'
467
559
 
468
- /** 列表类型:仅文档 / 仅图片视频 / 全部混排。默认 doc,与旧版体验一致。 */
560
+ /** 列表类型:仅文档 / 仅代码 / 仅图片视频 / 全部混排。默认 doc,与旧版体验一致。 */
469
561
  const KIND_DOC = 'doc'
562
+ /**
563
+ * v0.19:代码档。**它是同一份 Context Retrieval 结果的另一个切片,不是代码工具页。**
564
+ * 这一档里显示的仍然是「按当前任务排出来的代码候选」,不是仓库的代码文件树
565
+ * (需求 §24:任务「修改 Skill loader 使它支持新的 frontmatter」时,
566
+ * 应该看到 skill-loader.ts / frontmatter.ts,而不是 src/ 下的全部 .ts)。
567
+ */
568
+ const KIND_CODE = 'code'
470
569
  const KIND_MEDIA = 'media'
471
570
  const KIND_ALL = 'all'
472
571
 
572
+ /**
573
+ * v0.19:分类层给的「生成产物」档(`.map` / `*.min.js` / `package-lock.json` …)。
574
+ *
575
+ * **它不出现在任何列表里**(`contextual:false`、`searchable:false`,宿主根本不会
576
+ * 把它放进候选),但它**可以预览** —— 用户主动点「Source map」时才走到这里。
577
+ * 「能不能进上下文」与「能不能看」是两件事(需求 §29:Context eligibility ≠
578
+ * File system visibility)。
579
+ */
580
+ const KIND_GENERATED = 'generated'
581
+
582
+ /* ── 产物 kind(宿主 `classification.js` 的取值)─────────────────────
583
+ ⚠️ **不要把它和上面的页签常量 `KIND_DOC` 混起来**:`KIND_DOC` 是**页签值**
584
+ (`'doc'`,只活在 URL 参数与 localStorage 里),而宿主下发的 `doc.kind` 是
585
+ **分类层的产物类型**(Markdown 是 `'md'`)。两者字面量不同、语义也不同,
586
+ 写成 `doc.kind === KIND_DOC` 会恒为假 —— 那正是「代码区永远空白」这类
587
+ 看起来像没数据、其实是比较写错的问题。 */
588
+ const ARTIFACT_DOC = 'md'
589
+ const ARTIFACT_CODE = 'code'
590
+
473
591
  /** 预览面板高度的上下限:任何一端都不把对方挤没。 */
474
592
  const MIN_RATIO = 0.2
475
593
  const MAX_RATIO = 0.8
@@ -487,6 +605,8 @@ window.__ModuleLoader__.load({
487
605
 
488
606
  /** 「全部」视图里文档区的固定上限。 */
489
607
  const ALL_DOC_CAP = 4
608
+ /** 「全部」视图里代码区的固定上限(与文档区同量级 —— 代码不该在这一档里压过文档)。 */
609
+ const ALL_CODE_CAP = 4
490
610
  /**
491
611
  * 一屏基准:两行 × 4 列的观感(只在「媒体」这一档决定一屏铺几行时用)。
492
612
  * **它不决定列数** —— 列数交给 CSS 的 `auto-fill`,见 mediaLayoutFor。
@@ -621,53 +741,208 @@ body[data-ds-dark-theme] .knit-root{
621
741
  .knit-head .knit-root-path:disabled{cursor:default;text-decoration:none}
622
742
  .knit-count{font-size:11px;color:var(--dsw-alias-label-caption,#80868b);flex:none}
623
743
  .knit-btn{flex:none;display:inline-flex;align-items:center;justify-content:center;
624
- height:24px;padding:0 9px;border-radius:6px;cursor:pointer;
744
+ height:28px;padding:0 10px;border-radius:8px;cursor:pointer;
625
745
  background:transparent;color:var(--dsw-alias-label-secondary,#9aa0a6);
626
- border:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.08));font-size:11px}
746
+ border:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.08));font-size:12px;
747
+ transition:background .16s ease,color .16s ease}
627
748
  .knit-btn:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));
628
749
  color:var(--dsw-alias-label-primary,#e8eaed)}
629
750
  .knit-btn.active{background:var(--knit-active-bg,rgba(255,255,255,.085));
630
751
  color:var(--dsw-alias-label-primary,#e8eaed);border-color:var(--dsw-alias-border-l4,rgba(255,255,255,.22))}
752
+ /* v0.19「低权重动作」:Source map。
753
+ 它**不是**主要操作 —— .map 不参与检索,只是一个「顺手看一眼」的旁路。
754
+ 所以去掉边框、压到 caption 色,让「复制 / 全屏 / 本地打开」保持主次分明。
755
+ ⚠️ 不要在这里加 accent 色(类型页签那条守卫也是这个道理)。
756
+ ⚠️ 这段注释在模板串里:**任何反引号都会截断样式表**(AGENTS.md 的老坑)。 */
757
+ .knit-btn-quiet{border-color:transparent;color:var(--dsw-alias-label-caption,#80868b);font-size:11px;padding:0 8px}
758
+ .knit-btn-quiet:hover{color:var(--dsw-alias-label-secondary,#9aa0a6)}
759
+ /* 排序切换与搜索框:v0.18 UI 迭代(md §四~§六)把这两个控件**按输入控件的尺度重做** ——
760
+ 圆角 10px / 字号 13px。原来那套 22px 迷你胶囊读起来像「标签」而不是控件,
761
+ 与 14px 的页签、15px 的 Usage 标题差了两档,是「审美欠缺」最直观的一处。
762
+ ⚠️ 高度:md 写 36px,2026-10-06 用户看了真机后定成 **28px**(「太高了,不需要这么高」),
763
+ 与左边的「使用情况 / 刷新」同高。
764
+ ⚠️ 描边色:用 **--dsw-alias-border-l3**,与 DSH 主区「对话」页签下面那条横线(官方
765
+ .wSkVaW_header 的 border-bottom: .5px solid rgba(0,0,0,.12) = 浅色下的 border-l3)
766
+ 同一个 token —— 2026-10-06 用户要求「描边色值改成跟那条横一样」。不用更深的 l4:
767
+ l4(浅色 rgba(0,0,0,.161))比官方分割线重一档,摆在页签下面像两个输入框框住了内容。
768
+ ⚠️ 描边粗细:**0.5px**(2026-10-06 用户第二轮要求「描边色值修改成 0.5px」)—— 官方那条
769
+ 横本身就是 .5px,色值对上而粗细仍写 1px,高分屏上比它粗一倍。三处同粗:.knit-seg
770
+ 外框、.knit-seg 内部竖线、.knit-filter。CSS 里统一写 0.5px(与官方 .wSkVaW_header 的 .5px 同值)。
771
+ ⚠️ 选中态只改**底色 + 字重 600**(不是 700),hover 只改底色 —— 不许 scale / translate /
772
+ box-shadow(md §五)。暗色下靠 --knit-active-bg 这个 token,不写死颜色。 */
631
773
  .knit-bar{display:flex;align-items:center;gap:8px;padding:0 12px 8px;flex:none}
632
- .knit-seg{display:inline-flex;flex:none;border-radius:7px;overflow:hidden;
633
- border:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.1))}
634
- .knit-seg-btn{height:22px;padding:0 10px;cursor:pointer;font-size:11px;border:none;
635
- background:transparent;color:var(--dsw-alias-label-secondary,#9aa0a6)}
774
+ .knit-seg{display:inline-flex;flex:none;border-radius:10px;overflow:hidden;
775
+ border:0.5px solid var(--dsw-alias-border-l3,rgba(255,255,255,.12))}
776
+ .knit-seg-btn{height:28px;padding:0 15px;cursor:pointer;font-size:13px;font-weight:400;
777
+ border:none;background:transparent;color:var(--dsw-alias-label-secondary,#9aa0a6);
778
+ transition:background .16s ease,color .16s ease}
779
+ .knit-seg-btn + .knit-seg-btn{border-left:0.5px solid var(--dsw-alias-border-l3,rgba(255,255,255,.12))}
636
780
  .knit-seg-btn:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03))}
637
781
  .knit-seg-btn.active{background:var(--knit-active-bg,rgba(255,255,255,.085));
638
782
  color:var(--dsw-alias-label-primary,#e8eaed);font-weight:600}
639
- .knit-filter{flex:1;min-width:0;height:24px;padding:0 9px;border-radius:7px;font-size:11px;
783
+ .knit-filter{flex:1;min-width:0;height:28px;padding:0 12px;border-radius:10px;font-size:13px;
640
784
  background:transparent;color:var(--dsw-alias-label-primary,#e8eaed);
641
- border:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.1));outline:none}
785
+ border:0.5px solid var(--dsw-alias-border-l3,rgba(255,255,255,.12));outline:none;
786
+ transition:border-color .16s ease}
642
787
  .knit-filter:focus{border-color:var(--knit-accent)}
643
788
  .knit-filter::placeholder{color:var(--dsw-alias-label-caption,#80868b)}
644
- /* v0.15「使用情况」:**一行事实**,不画卡片、不画进度条、不用品牌色。
645
- 它占的就是原来「相关性排序」那一行的位置 —— 2026-09-30 用户裁决那一行
646
- 整个删掉(排序方式由「相关 / 最新」那个切换按钮自己表达,再说一遍是重复),
647
- 所以它现在是头部下面唯一的一行弱化文字,不是一块新面板。
789
+ /* v0.15「使用情况」→ v0.18「Context Usage Lens」:**列表上方的一块轻量观察层**。
790
+ 不是弹窗、不是新页面、不是 Dashboard、不画卡片、不画进度条、不用品牌色。
791
+ 它占的是原来「相关性排序」那一行的位置 —— 2026-09-30 用户裁决那一行整个删掉
792
+ (排序方式由「相关 / 最新」那个切换按钮自己表达,再说一遍是重复),
793
+ 于是它是类型页签下面、列表上面唯一的一块弱化信息,不是一块新面板。
648
794
  ⚠️ 全宽横线一律不画:2026-09-29 用户要求**减少全宽分割线** ——
649
- 「页面上横线一多,读起来就像文件管理表格」。层级由空间与字号建立。 */
650
- .knit-usage{flex:none;padding:0 12px 9px;font-size:10.5px;line-height:1.45;
651
- color:var(--dsw-alias-label-caption,#80868b);
652
- overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
795
+ 「页面上横线一多,读起来就像文件管理表格」。层级由空间与字号建立。
796
+ ⚠️ 它**自己不滚动**:滚动统一交给 .knit-list —— 窄侧栏里滚轮套滚轮很难用。
797
+ ⚠️ 这一条不许加 background / width / 品牌色(有守卫盯着,见 client.test.mjs)。 */
798
+ .knit-usage{flex:none;padding:12px 12px 10px;font-size:12px;line-height:1.5;
799
+ color:var(--dsw-alias-label-caption,#80868b)}
800
+ /* Lens 标题行:整行可点,展开 / 收起。**「使用情况」开关管统计开不开,
801
+ 这一行管「统计开着但看不看细节」—— 两件事**(2026-10-05 规格 §25)。
802
+ v0.18 UI 迭代(2026-10-06,依 '02_方案与 Demo/dsh-knit V0.18 UI 重构开发提示词.md'
803
+ §七 / §四十七 的尺度表):标题 15px/600(它是这一块的**标题**,不是元信息)、
804
+ Epoch 12px 弱化靠右、**不做成 Badge**(不画底、不画边)。 */
805
+ .knit-lens-head{display:flex;align-items:baseline;gap:8px;width:100%;appearance:none;
806
+ border:0;background:none;margin:0;padding:0;font:inherit;cursor:pointer;text-align:left;
807
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
808
+ .knit-lens-head:hover{color:var(--dsw-alias-label-primary,#e8eaed)}
809
+ .knit-lens-head:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
810
+ .knit-lens-title{flex:none;font-size:15px;font-weight:600;line-height:20px;
811
+ color:var(--dsw-alias-label-primary,#e8eaed)}
812
+ .knit-lens-epoch{flex:none;margin-left:auto;font-size:12px;font-weight:400;line-height:20px;
813
+ color:var(--dsw-alias-label-caption,#80868b)}
814
+ /* 摘要行:三件事实,一行。放不下就省略号 —— 绝不换行把列表顶下去。
815
+ 12px/18px、与标题 4~6px(md §九 / §十)。 */
816
+ .knit-lens-sum{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;
817
+ margin-top:5px;font-size:12px;line-height:18px}
818
+ .knit-lens-sec{margin-top:13px}
819
+ .knit-lens-name{margin-bottom:6px;font-size:12px;font-weight:500;
820
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
821
+ /* 「当前上下文」这一句是**分节标题**(比层名与行标签高一档,md §十三:13px/500);
822
+ 距摘要行 12~14px 由 .knit-lens-sec 的 margin-top 给。 */
823
+ .knit-lens-cap{margin-bottom:6px;font-size:13px;font-weight:500;
824
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
825
+ /* 当前上下文 Coverage:三层各「层名 + 已读 ÷ 总数 + 状态点」。
826
+ v0.18 UI 迭代(md §十二~§十九):三层用 '1fr 1.2fr 1.8fr' 的**网格**(Related 通常
827
+ 最多),层名与 'n / m' 落在**同一行**(数值右对齐),状态点是**真的 9px 圆点** ——
828
+ 不再是 '○ ●' 字符:字符圆点在不同字体 / 字号下大小不一,正是「不像设计稿」的那一处。
829
+ ⚠️ 不是三张 Card:默认不画底、不画边,只有 hover 时一层很淡的底(md §十三 / §五十一)。
830
+ ⚠️ 分母是这一层当前真实几篇:Primary 不存在时整列不显示(不画 0 / 0 的假层)。 */
831
+ .knit-cov{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1.2fr) minmax(0,1.8fr);
832
+ column-gap:14px;align-items:start;margin:0 -8px}
833
+ .knit-cov-col{display:grid;grid-template-columns:1fr auto;column-gap:8px;row-gap:7px;
834
+ align-items:center;appearance:none;border:0;margin:0;padding:6px 8px;
835
+ background:transparent;font:inherit;cursor:pointer;text-align:left;border-radius:10px;
836
+ color:var(--dsw-alias-label-caption,#80868b);transition:background .16s ease}
837
+ .knit-cov-col:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03))}
838
+ .knit-cov-col:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
839
+ .knit-cov-name{grid-column:1;min-width:0;overflow:hidden;text-overflow:ellipsis;
840
+ white-space:nowrap;font-size:12px;font-weight:500;
841
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
842
+ /* 状态点:**真 CSS 圆** —— 未读=空心环(1px 中性边)、已读=中性填充;'○→●' 只做
843
+ background / border-color 两笔 220ms 过渡,不弹跳、不闪烁。
844
+ ⚠️ 轮询不动数据就不动 className,于是补间不会被重播。
845
+ ⚠️ 只用中性 token:没有绿 / 红 / 黄 / 蓝 —— 读没读过不是「好 / 坏」(PRD §7.3)。
846
+ ⚠️ 与文档行里的 .knit-glyph-mark **同一对 token、同一个直径**:md §二十九 要求
847
+ 生命周期那枚空心圆与这里的空心圆「视觉完全一致」。 */
848
+ .knit-cov-dots{grid-column:1 / -1;display:flex;flex-wrap:wrap;gap:6px;row-gap:5px;
849
+ min-height:6px;align-items:center}
850
+ /* ⚠️ 圆点直径 6px(2026-10-06 用户定:「9px 真圆请改成 6px」)。
851
+ Coverage 与文档行的 glyph 必须**同一个直径、同一对 token**(守卫会比对两处)。 */
852
+ .knit-cov-dot{flex:none;display:block;width:6px;height:6px;border-radius:50%;
853
+ border:1px solid var(--dsw-alias-label-caption,#80868b);background:transparent;
854
+ transition:background .22s ease,border-color .22s ease}
855
+ .knit-cov-dot.on{background:var(--dsw-alias-label-caption,#80868b);
856
+ border-color:var(--dsw-alias-label-caption,#80868b)}
857
+ .knit-cov-num{grid-column:2;text-align:right;font-size:11px;font-weight:400;
858
+ font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-caption,#80868b)}
859
+ /* 最近读取:**可点的一行**(文件名 · 相对时间 ›)。整行可点、hover 只改底色。
860
+ v0.18 UI 迭代(md §二十一 / §二十二):高 38px、左右 10px、圆角 8px、
861
+ 文件 12px、时间 11px、箭头 16px。
862
+ ⚠️ 语义仍是「最近一次成功 read」:文案不许写成「当前正在阅读」。 */
863
+ .knit-read-row{display:flex;align-items:center;gap:10px;width:100%;appearance:none;
864
+ border:0;background:none;margin:0;padding:0 10px;height:38px;border-radius:8px;font:inherit;
865
+ text-align:left;cursor:pointer;color:var(--dsw-alias-label-primary,#e8eaed);
866
+ transition:background .16s ease}
867
+ .knit-read-row:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03))}
868
+ .knit-read-row:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
869
+ .knit-read-rel{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;
870
+ white-space:nowrap;font-size:12px}
871
+ .knit-read-time{flex:none;font-size:11px;color:var(--dsw-alias-label-caption,#80868b)}
872
+ .knit-read-go{flex:none;font-size:16px;line-height:1;
873
+ color:var(--dsw-alias-label-caption,#80868b)}
874
+ .knit-lens-empty{opacity:.75}
875
+ /* 包外读取:每一行都是**可点对象**(点开预览),但不许加入 Context ——
876
+ V0.18 不做 Context Control,这里是「看一眼」,不是「改上下文」。
877
+ v0.18 UI 迭代(md §三十四~§三十七):展开后逐行
878
+ '01 docs/… ×3 已读'(序号 + 路径 + 次数 + 状态),11px、行内不画线。 */
879
+ .knit-out-row{display:flex;align-items:center;gap:9px;width:100%;appearance:none;
880
+ border:0;background:none;margin:0;padding:5px 9px 5px 17px;border-radius:8px;font:inherit;
881
+ text-align:left;cursor:pointer;color:var(--dsw-alias-label-caption,#80868b);
882
+ transition:background .16s ease}
883
+ .knit-out-row:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));
884
+ color:var(--dsw-alias-label-primary,#e8eaed)}
885
+ .knit-out-row:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
886
+ .knit-out-num{flex:none;width:18px;text-align:right;font-size:11px;
887
+ font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-caption,#80868b);opacity:.75}
888
+ .knit-out-rel{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;
889
+ white-space:nowrap;font-size:11px}
890
+ .knit-out-count{flex:none;font-size:11px;font-variant-numeric:tabular-nums}
891
+ /* 行内生命周期 glyph(v0.17 起):**极小、中性、不抢标题**。点它 = 打开 / 选中这篇。
892
+ v0.18 UI 迭代(md §二十七~§二十九):四态改成与 Coverage **同一套**圆点语言 ——
893
+ 未读=空心环、已读=实心、读后已更新=空心环 + 中心点、修改后已重新读取= ↻ 字符。
894
+ 两者用同一对 token、同一个 9px 直径,所以「同一套状态语言」不靠自觉。
895
+ ⚠️ 类名不能叫 knit-life-*:byClass 是子串匹配,会和 .knit-life 撞。 */
896
+ .knit-glyph{flex:none;display:inline-flex;align-items:center;justify-content:center;
897
+ appearance:none;border:0;background:none;margin:0;padding:0;width:14px;height:18px;
898
+ cursor:pointer;color:var(--dsw-alias-label-caption,#80868b)}
899
+ .knit-glyph:hover{color:var(--dsw-alias-label-primary,#e8eaed)}
900
+ .knit-glyph:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
901
+ .knit-glyph-mark{flex:none;display:block;width:6px;height:6px;border-radius:50%;
902
+ border:1px solid var(--dsw-alias-label-caption,#80868b);background:transparent;
903
+ transition:background .22s ease,border-color .22s ease}
904
+ .knit-glyph-mark[data-mark="read"]{background:var(--dsw-alias-label-caption,#80868b)}
905
+ .knit-glyph-mark[data-mark="updated"]{position:relative}
906
+ .knit-glyph-mark[data-mark="updated"]::after{content:'';position:absolute;inset:1.5px;
907
+ border-radius:50%;background:var(--dsw-alias-label-caption,#80868b)}
908
+ .knit-glyph-mark[data-mark="reread"]{width:9px;height:9px;border:0;background:transparent;
909
+ font-size:9px;line-height:9px;text-align:center}
910
+ /* Coverage 点某一层 → 那一层**短暂高亮**(空间定位,不画横线、不加箭头)。
911
+ 1200ms 轻微背景(md §十七原写 500~700ms,2026-10-06 用户看真机后定成 1200ms),
912
+ 不许闪红、不许位移。CSS transition 的时长必须与 FLASH_MS 一致,否则会出现「已经取消高亮
913
+ 但背景还在慢慢褪」的错帧。 */
914
+ .knit-tier{transition:background 1.2s ease}
915
+ .knit-tier.flash{background:var(--knit-hover-bg,rgba(255,255,255,.03));border-radius:10px}
653
916
 
654
917
  /* v0.17 文档生命周期(Document Lifecycle)—— 三条新信息,都只是**事实**。
655
918
  ⚠️ 状态是文字,不是徽章:不加底色、不加边框、不用红绿 —— 红绿会把「事实」读成
656
- 「好 / 坏」(PRD §7.3)。字号 10.5px,比 14px 的标题弱一档,永远不抢标题。
919
+ 「好 / 坏」(PRD §7.3)。永远不抢标题(标题 14px)。
920
+ v0.18 UI 迭代:10.5px → **11px** —— md §四十七 的尺度表里最小一档就是 11px。
657
921
  ⚠️ 折叠块沿用 .knit-usage 的弱化灰阶:它们是同一行事实的展开,不是新卡片。
658
922
  ⚠️ 这一段**不含反引号**,整段可以直接放在 CSS 模板串里。 */
659
- .knit-life{flex:none;font-size:10.5px;line-height:1.4;white-space:nowrap;
923
+ .knit-life{flex:none;font-size:11px;line-height:1.4;white-space:nowrap;
660
924
  color:var(--dsw-alias-label-caption,#80868b)}
661
- .knit-usage-more{margin-top:3px}
662
- .knit-more-btn{appearance:none;border:0;background:none;margin:0;padding:0;
663
- font:inherit;line-height:inherit;color:var(--dsw-alias-label-secondary,#9aa0a6);cursor:pointer}
664
- .knit-more-btn:hover{color:var(--knit-accent)}
925
+ .knit-usage-more{margin-top:10px}
926
+ /* 菜单式展开行(包外读取 / 上下文变化):整行可点、高 38px、圆角 8px、hover 只改底色;
927
+ 左边是标题,右边是「数量 / 最近一次 + ›」,展开后箭头换成 ⌃(md §三十四 / §三十八)。 */
928
+ .knit-more-btn{display:flex;align-items:center;gap:10px;width:100%;
929
+ appearance:none;border:0;background:none;margin:0;padding:0 10px;height:38px;
930
+ border-radius:8px;font:inherit;font-size:12px;line-height:1;cursor:pointer;text-align:left;
931
+ color:var(--dsw-alias-label-secondary,#9aa0a6);transition:background .16s ease}
932
+ .knit-more-btn:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));
933
+ color:var(--dsw-alias-label-primary,#e8eaed)}
665
934
  .knit-more-btn:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
666
- .knit-gap-row,.knit-delta-row{display:flex;gap:6px;align-items:baseline;margin-top:2px;
935
+ .knit-more-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;
936
+ white-space:nowrap}
937
+ .knit-more-meta{flex:none;font-size:11px;font-variant-numeric:tabular-nums;
938
+ color:var(--dsw-alias-label-caption,#80868b)}
939
+ .knit-gap-row,.knit-delta-row{display:flex;gap:9px;align-items:baseline;
940
+ padding:3px 9px 3px 17px;font-size:11px;
667
941
  color:var(--dsw-alias-label-caption,#80868b)}
668
942
  .knit-gap-rel,.knit-delta-rel{flex:1 1 auto;min-width:0;overflow:hidden;
669
943
  text-overflow:ellipsis;white-space:nowrap}
670
- .knit-delta-head{margin-top:3px;color:var(--dsw-alias-label-secondary,#9aa0a6)}
944
+ .knit-delta-head{margin-top:8px;padding:0 9px 0 17px;font-size:11px;font-weight:500;
945
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
671
946
 
672
947
 
673
948
  /* ── v0.14 右栏(Context Pack 面板)已整体删除(2026-09-29)────────
@@ -703,7 +978,7 @@ body[data-ds-dark-theme] .knit-root{
703
978
  .knit-tierhint{font-weight:400}
704
979
  /* 「为什么在这里」:比摘要更弱的一行,只在 Context Pack 的条目上出现。
705
980
  11px 而不是 10px,因为它承担的是**信息**(可核验的理由),不是装饰标注。 */
706
- .knit-why{padding-top:2px;font-size:11px;line-height:1.5;color:var(--dsw-alias-text-tertiary)}
981
+ .knit-why{padding-top:2px;font-size:11px;line-height:17px;color:var(--dsw-alias-text-tertiary)}
707
982
  /* 滚动条**不要自己画**:DSH 主题里已有全局样式
708
983
  (::-webkit-scrollbar 宽 8px + --dsh-scrollbar-thumb,见 dsh-client-ui-theme)。
709
984
  曾经在这里写死 6px 宽 + rgba(255,255,255,.14) 的滑块 —— 白色 14% 在白底上完全隐形,
@@ -760,6 +1035,9 @@ body[data-ds-dark-theme] .knit-root{
760
1035
  .knit-doc.leaving{pointer-events:none;user-select:none;overflow:hidden}
761
1036
  @media (prefers-reduced-motion: reduce){
762
1037
  .knit-doc{transition:none}
1038
+ .knit-cov-dots,.knit-cov-dot{transition:none}
1039
+ .knit-tier,.knit-tier.flash{transition:none}
1040
+ .knit-cov-col,.knit-read-row,.knit-out-row,.knit-more-btn,.knit-glyph-mark{transition:none}
763
1041
  }
764
1042
  /* 行一=**标题行**:Primary 点 + 标题 + 相对时间(**时间靠右**)。
765
1043
  2026-09-29 这一天里这一行改了三次:先是「序号 + 标题 + 时间」,然后
@@ -780,7 +1058,7 @@ body[data-ds-dark-theme] .knit-root{
780
1058
  它=.knit-title 的 14px × 1.4。格的 align-items:start 让这一列从卡片顶边
781
1059
  开始排,所以只要这个行盒与标题行盒等高,两个字号不同的文本就自然居中。
782
1060
  **改 .knit-title 的字号或行高时,这里必须同步改**,否则序号会与标题错开。 */
783
- .knit-num,.knit-gapmark{grid-column:1;font-size:10.5px;line-height:19.6px;font-variant-numeric:tabular-nums;
1061
+ .knit-num,.knit-gapmark{grid-column:1;font-size:11px;line-height:19.6px;font-variant-numeric:tabular-nums;
784
1062
  color:var(--dsw-alias-label-caption,#80868b)}
785
1063
  /* 中性占位标记(2026-10-01 用户反馈):「其他相关文档」那一节没有序号,空着的那一格
786
1064
  被读成「漏了一个号」(原话:「没有序号以后左边就空了,视觉上比较割裂,就觉得是个 bug 一样」)。
@@ -798,7 +1076,7 @@ body[data-ds-dark-theme] .knit-root{
798
1076
  ⚠️ 这条推翻了同一天早先的写法(那时候时间跟在点后面左对齐,理由是
799
1077
  「元信息行读起来像一句话」)—— 时间现在和标题同一行,左对齐会把标题夹在中间。
800
1078
  靠 .knit-title 的 flex:1 1 auto 把时间挤到行尾;这里只要 flex:none 不被压扁。 */
801
- .knit-time{flex:none;font-size:10.5px;color:var(--dsw-alias-label-caption,#80868b)}
1079
+ .knit-time{flex:none;font-size:11px;color:var(--dsw-alias-label-caption,#80868b)}
802
1080
  /* 标题现在和 Primary 点、时间**同行**(见 .knit-row1 的说明;margin-bottom 移到了那一行)。
803
1081
  仍是单行省略 —— 列表是扫读用的,想看全标题就预览或打开;折行会让每条卡高度不一,
804
1082
  「移动到下一项」的位移就没法预期。
@@ -806,7 +1084,7 @@ body[data-ds-dark-theme] .knit-root{
806
1084
  去掉 min-width:0,标题会把整行撑宽(省略号失效);去掉 flex-grow,时间会紧贴标题而不是靠右。 */
807
1085
  .knit-title{flex:1 1 auto;min-width:0;font-weight:600;font-size:14px;line-height:1.4;
808
1086
  overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
809
- .knit-sum{font-size:12px;line-height:19px;color:var(--dsw-alias-label-secondary,#9aa0a6);
1087
+ .knit-sum{font-size:12px;line-height:18px;color:var(--dsw-alias-label-secondary,#9aa0a6);
810
1088
  display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
811
1089
  .knit-sum.empty{font-style:italic;color:var(--dsw-alias-label-caption,#80868b)}
812
1090
  /* ── 列表行里为什么没有路径(2026-09-29) ────────────────────
@@ -894,6 +1172,27 @@ body[data-ds-dark-theme] .knit-preview{box-shadow:0 -8px 24px rgba(0,0,0,.38)}
894
1172
  color:var(--dsw-alias-label-secondary,#9aa0a6);font-family:ui-monospace,SFMono-Regular,Menlo,monospace}
895
1173
  .knit-preview-note{font-size:11px;color:var(--dsw-alias-label-caption,#80868b);padding:2px 0 8px}
896
1174
 
1175
+ /* v0.19:代码行的语言徽章(TS / JS / PY …)。
1176
+ 刻意**不是**一个胶囊:没有底色、没有边框、没有圆角 —— 它是一条弱注释,
1177
+ 不是标签墙。字号比标题小两档,颜色用 caption,永远不抢标题。
1178
+ 窄侧边栏里它 flex:none,压缩的是标题(.knit-title 会省略号收尾)而不是它。 */
1179
+ .knit-lang{flex:none;margin-left:6px;font-size:10px;letter-spacing:.04em;
1180
+ text-transform:uppercase;color:var(--dsw-alias-label-caption,#80868b)}
1181
+
1182
+ /* ── 代码预览(v0.19)────────────────────────────────────
1183
+ 轻量:行号栏 + 代码正文。**不做语法高亮、不做折叠、不做 minimap**,
1184
+ 也没引入 Monaco / CodeMirror —— Knit 不是编辑器(需求 §8 §25)。
1185
+ 横向滚动只发生在正文那一格(overflow-x:auto + min-width:0),
1186
+ 行号栏 flex:none 留在左边;纵向滚动仍由外面的 .knit-preview-body 负责,
1187
+ 所以这里**不开第二个纵向滚动容器**(两个纵向滚动条会互相打架)。 */
1188
+ .knit-codepane{display:flex;align-items:stretch;min-height:100%;
1189
+ font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:11.5px;line-height:1.6}
1190
+ .knit-code-gutter{flex:none;white-space:pre;text-align:right;user-select:none;
1191
+ padding:0 8px 0 2px;color:var(--dsw-alias-label-caption,#80868b);
1192
+ border-right:1px solid var(--dsw-alias-border-l3,rgba(255,255,255,.08))}
1193
+ .knit-code-src{flex:1 1 auto;min-width:0;margin:0;padding:0 0 0 10px;
1194
+ white-space:pre;overflow-x:auto;color:var(--dsw-alias-label-primary,#e8eaed)}
1195
+
897
1196
  /* ── 引用条(v0.12)────────────────────────────────────
898
1197
  夹在预览头与正文之间的一层。全用中性令牌:它是「信息」,不是「操作」。
899
1198
  ⚠️ 2026-09-30 用户裁决:它自己那条 border-l2 底边**删掉** —— 与预览头的底边
@@ -934,9 +1233,9 @@ body[data-ds-dark-theme] .knit-preview{box-shadow:0 -8px 24px rgba(0,0,0,.38)}
934
1233
  2px 下划线表达,页签条本身不画线(也不是「下划线悬空」:它画在自己的文字下面)。
935
1234
  ⚠️ 排序切换(.knit-seg-btn,Design §18)是**另一个控件**,它保持灰底不变。 */
936
1235
  .knit-types{display:flex;gap:14px;padding:0 12px;flex:none}
937
- .knit-type-btn{flex:none;height:28px;padding:0;cursor:pointer;
1236
+ .knit-type-btn{flex:none;height:30px;padding:0;cursor:pointer;
938
1237
  border:none;border-bottom:2px solid transparent;background:transparent;
939
- color:var(--dsw-alias-label-secondary,#9aa0a6);font-family:inherit;font-size:11.5px;
1238
+ color:var(--dsw-alias-label-secondary,#9aa0a6);font-family:inherit;font-size:14px;
940
1239
  white-space:nowrap;overflow:hidden;text-overflow:ellipsis;
941
1240
  transition:color .15s,border-color .15s}
942
1241
  .knit-type-btn:hover{color:var(--dsw-alias-label-primary,#e8eaed)}
@@ -1057,6 +1356,11 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1057
1356
  .knit-root.fullscreen .knit-bar,
1058
1357
  .knit-root.fullscreen .knit-types,
1059
1358
  .knit-root.fullscreen .knit-list{display:none}
1359
+ /* v0.19 修补(2026-10-07 用户反馈):**使用情况也是列表上方的观察层**,全屏时同样让位。
1360
+ 这条规则漏了它 ⇒ 开着「使用情况」再点全屏,Lens 仍占掉面板上方约三分之一,
1361
+ 预览被挤在下面 —— 看起来就像「全屏没生效」。它是 flex:none 的自然高度,
1362
+ 不是浮层,所以必须显式 display:none,光靠预览 flex:1 抢不回来。 */
1363
+ .knit-root.fullscreen .knit-usage{display:none}
1060
1364
  /* 全屏时预览铺满整个面板:圆角与向上柔影是「浮在列表上」的隐喻,这里没有列表,去掉 */
1061
1365
  .knit-root.fullscreen .knit-preview{flex:1 1 auto;max-height:none;
1062
1366
  border-top:none;border-radius:0;box-shadow:none}
@@ -1114,7 +1418,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1114
1418
  */
1115
1419
  function readKindPref() {
1116
1420
  const v = readPref(KIND_KEY)
1117
- return v === KIND_MEDIA || v === KIND_ALL ? v : KIND_DOC
1421
+ return v === KIND_MEDIA || v === KIND_ALL || v === KIND_CODE ? v : KIND_DOC
1118
1422
  }
1119
1423
 
1120
1424
  /**
@@ -1420,6 +1724,106 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1420
1724
  return `knit-opt-${safe}-${(hash >>> 0).toString(36)}`
1421
1725
  }
1422
1726
 
1727
+ /* ── v0.18 Context Usage Lens 的纯函数 ────────────────────────────
1728
+ 这一层只把**已经有的事实**重新组织一遍:不新增采集、不新增存储、不新增事件、
1729
+ 不新增第二个生命周期口径。「能派生就不要存储」—— Coverage 是拿当前 Context
1730
+ Pack 的三层 rels 加上 `usage.lifecycle` **现算**出来的,没有任何一份自己的 state。
1731
+ ⚠️ 全部是纯函数(不吃 React、不读 DOM),所以测试可以直接对拍。
1732
+ ⚠️ 这一段**不含反引号**,整段可以直接放进 CSS/代码模板串里。 */
1733
+
1734
+ /** 生命周期四态的 glyph。**不是颜色、不是徽章** —— 它只是一枚字符。
1735
+ * ⚠️ 四态一律中性:不许「绿=已读 / 红=未读 / 黄=更新」——
1736
+ * 生命周期是**事实**,不是风险等级(PRD §7.3)。 */
1737
+ const LIFE_GLYPH = {
1738
+ unread: '○',
1739
+ read: '●',
1740
+ updated_after_read: '△',
1741
+ reread_after_update: '↻',
1742
+ }
1743
+
1744
+ /** 某篇的读取状态:**没有记录就是未读**(这是事实,不是猜测)。
1745
+ * 认不出的状态一律退回 `unread` —— 宿主加了新状态时,界面显示「未读」而不是空白。 */
1746
+ function lifeStatusOf(lifecycle, rel) {
1747
+ const row = lifecycle && typeof lifecycle === 'object' ? lifecycle[rel] : null
1748
+ const status = row && typeof row.status === 'string' ? row.status : 'unread'
1749
+ return LIFE_GLYPH[status] ? status : 'unread'
1750
+ }
1751
+
1752
+ /** Coverage:三层各自的 `{ total, read, rels }`。
1753
+ * `tierRels` = `{ primary: [...rel], supporting: [...], related: [...] }`;
1754
+ * `rels` 里每一项带 `read` 布尔(状态点要用它)。
1755
+ * ⚠️ 分母是**这一层当前真实有几篇**,不是 Context Pack 的 `matched/total`;
1756
+ * 所以 Primary 不存在时是 `{ total: 0, read: 0, rels: [] }`,面板显示 `0 / 0`
1757
+ * —— Knit 不能假设每一份上下文都有 Primary。 */
1758
+ function coverageOf(tierRels, lifecycle) {
1759
+ const out = {}
1760
+ for (const key of ['primary', 'supporting', 'related']) {
1761
+ const list = tierRels && Array.isArray(tierRels[key]) ? tierRels[key] : []
1762
+ const rels = []
1763
+ let read = 0
1764
+ for (const item of list) {
1765
+ const rel = typeof item === 'string' ? item : (item && item.rel)
1766
+ if (!rel) continue
1767
+ const isRead = lifeStatusOf(lifecycle, rel) !== 'unread'
1768
+ if (isRead) read += 1
1769
+ rels.push({ rel, read: isRead })
1770
+ }
1771
+ out[key] = { total: rels.length, read, rels }
1772
+ }
1773
+ return out
1774
+ }
1775
+
1776
+ /** 包外读取的**事实排序**:读得最多的在前,同次数按**最后读**的先后。
1777
+ * ⚠️ 宿主回的是**首次读的顺序**(`seq` = firstRead.seq,阅读顺序);面板要回答的是
1778
+ * 「哪几篇被反复读」—— 两件事,所以在客户端重排,不动宿主。
1779
+ * ⚠️ 载荷里没有 `lastRead.seq`(只有首次读的 `seq` 与 `lastReadAt`),
1780
+ * 于是同计数时按 `lastReadAt` 降序 —— 它对应的就是规格里的「最后读的那一次更靠前」。 */
1781
+ function groupOutsideDocs(outsideDocs) {
1782
+ const list = Array.isArray(outsideDocs) ? outsideDocs.slice() : []
1783
+ return list.sort((a, b) => {
1784
+ const ca = Number(a && a.count) || 0
1785
+ const cb = Number(b && b.count) || 0
1786
+ if (cb !== ca) return cb - ca
1787
+ const ta = Number(a && a.lastReadAt) || 0
1788
+ const tb = Number(b && b.lastReadAt) || 0
1789
+ if (tb !== ta) return tb - ta
1790
+ const sa = Number(a && a.seq) || 0
1791
+ const sb = Number(b && b.seq) || 0
1792
+ if (sb !== sa) return sb - sa
1793
+ return String((a && a.rel) || '').localeCompare(String((b && b.rel) || ''))
1794
+ })
1795
+ }
1796
+
1797
+ /** 最近一次 Context Delta 按「进 / 出 / 换层」拆开(只拆,不排序、不丢弃)。
1798
+ * ⚠️ v0.15 那种把 `appeared` 写成**字符串数组**的旧载荷也认 ——
1799
+ * 客户端不能因为宿主版本不同就崩。 */
1800
+ function groupDelta(delta) {
1801
+ const out = { enter: [], leave: [], move: [] }
1802
+ if (!delta) return out
1803
+ const push = (target, item) => {
1804
+ const rel = typeof item === 'string' ? item : (item && item.rel)
1805
+ if (!rel) return
1806
+ target.push(typeof item === 'string' ? { rel } : item)
1807
+ }
1808
+ for (const item of Array.isArray(delta.appeared) ? delta.appeared : []) push(out.enter, item)
1809
+ for (const item of Array.isArray(delta.disappeared) ? delta.disappeared : []) push(out.leave, item)
1810
+ for (const item of Array.isArray(delta.moved) ? delta.moved : []) push(out.move, item)
1811
+ return out
1812
+ }
1813
+
1814
+ /** 面板矮到这个高度以下就进「小高度」档:只留 Summary / Coverage / Recent Read,
1815
+ * Outside / Delta 收成标题(点开照常能用)。⚠️ 不是「藏起来」,是「别先占高度」。 */
1816
+ const COMPACT_PANEL_PX = 420
1817
+ /** 包外读取默认最多铺几行,其余折成「还有 N 篇」。 */
1818
+ const MAX_OUTSIDE_SHOWN = 10
1819
+ /** 上下文变化:收起时最多 3 条,展开后每个分类最多 5 条(v0.17 规则,保持不变)。 */
1820
+ const MAX_DELTA_SHOWN = 3
1821
+ const MAX_DELTA_GROUP = 5
1822
+ /** 点 Coverage 之后那一层高亮多久(毫秒)。只是「我把你送到这儿了」的一下提示。
1823
+ * v0.18 UI 迭代(md §十七):原写 500~700ms、取 650;2026-10-06 用户看真机后定成 **1200**,
1824
+ * 「停留久一点才看得清是哪一层」。CSS 里 `.knit-tier{transition:background 1.2s}` 必须同步。 */
1825
+ const FLASH_MS = 1200
1826
+
1423
1827
  /* ── 列表进出动效(v0.17)─────────────────────────────────────────
1424
1828
  用户原话(2026-10-03):「文档列表,新读取跟挤掉旧的未读的,这里的交互可能要优化,
1425
1829
  因为现在是一闪一闪的,就非常的快……如果说从当前的,如辅助上下文中新增,它应该是
@@ -1445,6 +1849,8 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1445
1849
  /** 幽灵行所在的「区」:分层视图用层名,平铺与「全部」各一个 —— 幽灵要插回原位。 */
1446
1850
  const MOTION_TIER_FLAT = 'flat'
1447
1851
  const MOTION_TIER_ALL_DOCS = 'all-docs'
1852
+ /** v0.19:「全部」档里的代码区自己的区名 —— 幽灵行要插回**它原来那一区**,共用会插错位置。 */
1853
+ const MOTION_TIER_ALL_CODE = 'all-code'
1448
1854
  /** 幸存行位移(换层 / 重排)的 FLIP 时长:比进入略长,它要真的「走」完一段距离。 */
1449
1855
  const MOTION_MOVE_MS = 340
1450
1856
  /** 位移小于这个像素数(含亚像素抖动)就当没动过,不排补间。 */
@@ -1632,9 +2038,14 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1632
2038
  }
1633
2039
 
1634
2040
  function DocRow({ doc, now, active, cursor, relevance, why, num, mark, primary, life,
1635
- onSelect, onOpenTab, optionId, entering, leaving }) {
2041
+ glyph, onGlyph, onSelect, onOpenTab, optionId, entering, leaving }) {
1636
2042
  const fresh = now - doc.mtimeMs < NEW_WINDOW_MS
1637
2043
  const rowRef = React.useRef(null)
2044
+ /* v0.19:只有**代码行**带语言徽章。
2045
+ 文档列表整列都是 Markdown,给每一行都挂一个「MD」是纯噪声 —— 信息量为零,
2046
+ 还多占横向空间(§47 要求窄侧边栏不许溢出)。代码行混在文档里时才需要
2047
+ 「这是 TS 还是 PY」这一眼。 */
2048
+ const lang = doc.kind === ARTIFACT_CODE ? langBadge(doc.name || doc.rel) : ''
1638
2049
 
1639
2050
  /* 进 / 出两段补间都跑在 **layout effect** 里:放到 paint 之后会先闪一帧完整高度的
1640
2051
  行,那正是用户抱怨的那一下。没有 DOM 时 `motionAllowed()` 直接挡掉。 */
@@ -1711,10 +2122,38 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1711
2122
  h('div', { className: 'knit-row1' },
1712
2123
  // v0.14(Design §13):Primary 唯一允许的标记 —— 5px 黑点。
1713
2124
  // 不是星标、不是徽章、不是 AI 图标:「重要来自位置和结构,不来自图标」。
1714
- primary ? h('span', { className: 'knit-dot', 'aria-hidden': 'true' }) : null,
2125
+ // v0.18:**统计开着时这一格让给生命周期 glyph**(○ ● △ ↻)——
2126
+ // 2026-10-05 规格 §13 给的 ASCII 每一行只有一个标记,而层名已经由分组标题
2127
+ // (「主要上下文」)说了,glyph 才是这一版新加的那条事实。usage 关掉时
2128
+ // 这一行与 v0.17 逐字一致(`knit-dot` 照旧)。
2129
+ primary && !glyph ? h('span', { className: 'knit-dot', 'aria-hidden': 'true' }) : null,
2130
+ // 生命周期 glyph:极小、中性、点它=打开 / 选中这篇(**已经打开则保持原预览**)。
2131
+ // ⚠️ 它是真 `button`:键盘 Tab 得到、读屏读得出,不是 div + onClick。
2132
+ glyph ? h('button', {
2133
+ className: 'knit-glyph',
2134
+ type: 'button',
2135
+ title: glyph.title,
2136
+ 'aria-label': glyph.title,
2137
+ onClick: (event) => {
2138
+ if (event && typeof event.stopPropagation === 'function') event.stopPropagation()
2139
+ onGlyph(doc)
2140
+ },
2141
+ },
2142
+ // v0.18 UI 迭代(md §二十七~§二十九):四态画成与 Coverage **同一套** 9px 圆点 ——
2143
+ // 未读=空心环、已读=实心、读后已更新=空心环 + 中心点、修改后已重新读取= ↻ 字符。
2144
+ // 两处用同一对 token、同一个直径,所以「同一套状态语言」不靠自觉。
2145
+ // ⚠️ 状态词仍然只在 title / aria-label 里;行尾那一段文字由 `.knit-life` 说。
2146
+ h('span', {
2147
+ className: 'knit-glyph-mark',
2148
+ 'data-mark': glyph.status === 'read' ? 'read'
2149
+ : glyph.status === 'updated_after_read' ? 'updated'
2150
+ : glyph.status === 'reread_after_update' ? 'reread' : 'unread',
2151
+ 'aria-hidden': 'true',
2152
+ }, glyph.status === 'reread_after_update' ? glyph.char : null)) : null,
1715
2153
  h('div', { className: 'knit-title' },
1716
2154
  fresh ? h('span', { className: 'knit-badge' }, '🆕') : null,
1717
- doc.title || doc.name),
2155
+ doc.title || doc.name,
2156
+ lang ? h('span', { className: 'knit-lang' }, lang) : null),
1718
2157
  // v0.17:生命周期状态(文案已算好;没有证据时是 null,一个节点都不加)。
1719
2158
  // 插在**标题与时间之间**:`.knit-title` 是 flex:1 1 auto,会把状态与时间一起推到
1720
2159
  // 行尾,状态在时间左侧、行尾仍然是时间。
@@ -1814,13 +2253,149 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1814
2253
 
1815
2254
  /**
1816
2255
  * 列表下方的预览面板。
1817
- * @param {{preview:object,pathImages:object|null,fullscreen:boolean,onClose:Function,onOpenLocal:Function|null,onToggleFullscreen:Function,onResizeStart:Function}} props - 渲染入参
2256
+ * @param {{preview:object,pathImages:object|null,fullscreen:boolean,onClose:Function,onOpenLocal:Function|null,onReveal:Function|null,onToggleFullscreen:Function,onResizeStart:Function}} props - 渲染入参
1818
2257
  * @returns {import('react').ReactElement} 元素
1819
2258
  */
1820
- function PreviewPanel({ preview, pathImages, fullscreen, ratio, links, linksExpanded, onToggleLinks, onOpenLink, onClose, onOpenLocal, onToggleFullscreen, onResizeStart }) {
2259
+ /**
2260
+ * 复制一段文本。
2261
+ *
2262
+ * 优先 `navigator.clipboard`(异步;非 secure context 里可能根本没有);
2263
+ * 拿不到就退回 `document.execCommand('copy')` + 一个离屏 textarea。
2264
+ * 两条路都失败返回 `false` —— **由调用方决定怎么告诉用户**(静默失败比报错更糟)。
2265
+ *
2266
+ * @param {string} text - 要复制的文本
2267
+ * @returns {Promise<boolean>} 是否成功
2268
+ */
2269
+ function copyText(text) {
2270
+ const value = String(text == null ? '' : text)
2271
+ const legacy = () => {
2272
+ try {
2273
+ const area = document.createElement('textarea')
2274
+ area.value = value
2275
+ area.setAttribute('readonly', 'readonly')
2276
+ area.style.position = 'fixed'
2277
+ area.style.top = '-1000px'
2278
+ document.body.appendChild(area)
2279
+ area.select()
2280
+ const ok = document.execCommand('copy')
2281
+ document.body.removeChild(area)
2282
+ return ok
2283
+ } catch (error) {
2284
+ return false
2285
+ }
2286
+ }
2287
+ if (navigator.clipboard && navigator.clipboard.writeText) {
2288
+ return navigator.clipboard.writeText(value).then(() => true, legacy)
2289
+ }
2290
+ return Promise.resolve(legacy())
2291
+ }
2292
+
2293
+ /**
2294
+ * 语言徽章:文件后缀 → 短标签(TS / JS / PY / JSON / MD …)。
2295
+ *
2296
+ * **纯展示,不是判据。** 「这是什么类型、能不能进上下文、能不能预览」的权威
2297
+ * 一律是宿主的分类层(`src/host/classification.js`);这里只是把后缀压成一个
2298
+ * 窄标签给列表行和预览头用。认不出的后缀返回空串 —— **不猜**,宁可不显示。
2299
+ *
2300
+ * ⚠️ 这份表**不决定**任何文件是否被接纳:加一个后缀进这张表不会让 `.go` 变成
2301
+ * 上下文候选(宿主那边它是 `ignored`)。反过来也一样。
2302
+ */
2303
+ const LANG_BADGE = {
2304
+ js: 'JS', mjs: 'JS', cjs: 'JS', ts: 'TS', tsx: 'TSX', jsx: 'JSX', py: 'PY',
2305
+ json: 'JSON', html: 'HTML', htm: 'HTML', css: 'CSS', scss: 'SCSS',
2306
+ yaml: 'YAML', yml: 'YAML', sh: 'SH', bash: 'SH', zsh: 'SH',
2307
+ md: 'MD', map: 'MAP',
2308
+ }
2309
+
2310
+ /**
2311
+ * @param {string} name - 文件名(带后缀)
2312
+ * @returns {string} 徽章文本,认不出时为空串
2313
+ */
2314
+ function langBadge(name) {
2315
+ const m = /\.([a-z0-9]+)$/i.exec(String(name || ''))
2316
+ return m ? (LANG_BADGE[m[1].toLowerCase()] || '') : ''
2317
+ }
2318
+
2319
+ /**
2320
+ * 代码预览里最多渲染多少行。
2321
+ *
2322
+ * 一次最多这么多行号 —— 长文件不会把 DOM 撑爆(`readDocument` 那边已经按
2323
+ * `DOC_MAX_BYTES` 截过字节,这里是第二道、面向渲染的边界)。
2324
+ * 超出的部分明说「只显示前 N 行」,不静默砍掉。
2325
+ */
2326
+ const CODE_LINES_MAX = 4000
2327
+
2328
+ /**
2329
+ * 轻量代码预览:行号栏 + 代码正文。
2330
+ *
2331
+ * 刻意的取舍(需求 §8 §25 §26):
2332
+ * - **不做语法高亮、不做折叠、不做 minimap、不做 AST / symbol outline**,
2333
+ * 不引入 Monaco / CodeMirror。Knit 不是编辑器。
2334
+ * - 行号与正文**各是一个文本节点**(靠 `white-space: pre` 换行),不是每行一个
2335
+ * 元素 —— 4000 行代码因此只有两个节点,横向滚动交给 CSS 的 `overflow-x:auto`。
2336
+ * - 字体、配色全部走既有 `--knit-*` / `--dsw-alias-*` 变量,随 light/dark 主题走。
2337
+ *
2338
+ * @param {{text: string}} props - `preview.text` 原文
2339
+ * @returns {import('react').ReactElement} 元素
2340
+ */
2341
+ function CodePane({ text }) {
2342
+ const lines = String(text == null ? '' : text).split('\n')
2343
+ // 末尾换行会切出一个空尾行 —— 显示它会让行数比编辑器里多一行。
2344
+ if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop()
2345
+ const clipped = lines.length > CODE_LINES_MAX
2346
+ const shown = clipped ? lines.slice(0, CODE_LINES_MAX) : lines
2347
+ let gutter = ''
2348
+ for (let i = 1; i <= shown.length; i += 1) gutter += (i === 1 ? '' : '\n') + i
2349
+ return h('div', { className: 'knit-codepane' },
2350
+ h('div', { className: 'knit-code-gutter', 'aria-hidden': 'true' }, gutter),
2351
+ h('pre', { className: 'knit-code-src' }, shown.join('\n')),
2352
+ clipped
2353
+ ? h('div', { className: 'knit-preview-note' },
2354
+ t('preview.codeTruncated', { n: CODE_LINES_MAX }))
2355
+ : null)
2356
+ }
2357
+
2358
+ function PreviewPanel({ preview, pathImages, fullscreen, ratio, links, linksExpanded, onToggleLinks, onOpenLink, onClose, onOpenLocal, onReveal, onOpenMap, onOpenWeb, onToggleFullscreen, onResizeStart }) {
1821
2359
  const isMedia = preview.kind === 'image' || preview.kind === 'video'
1822
2360
  const previewPath = splitRelPath(preview.rel)
1823
2361
 
2362
+ /* ── v0.19:复制整篇 + Source map ──────────────────────
2363
+ * 「复制」只给代码 —— Markdown 那边 MarkdownText 自带每个代码块的复制按钮,
2364
+ * 再给一个「复制整篇」会和它挤在一起,而且很少用。
2365
+ * `copied` 只活在这个组件里(1.6s 后自己复位),不落盘、不进任何 store。 */
2366
+ const isCodeView = preview.kind === ARTIFACT_CODE || preview.kind === KIND_GENERATED
2367
+ /* v0.19 追加:**网页预览**只给 HTML。
2368
+ 判据优先用宿主给的 `language` —— 那是分类层(`src/host/classification.js`)
2369
+ 的结论,v0.19 起客户端不再自己看扩展名。正文还没到手时 `language` 是空的,
2370
+ 退回列表徽章那张表(`LANG_BADGE`)兜一下:它**只决定这个按钮出不出场**,
2371
+ 不改变任何文件的接纳结论 —— 该表自己的注释也是这么写的。 */
2372
+ const isWebPage = isCodeView && (preview.language === 'html'
2373
+ || (!preview.language && langBadge(preview.title || preview.rel) === 'HTML'))
2374
+ const [copied, setCopied] = React.useState(false)
2375
+ const [copyFailed, setCopyFailed] = React.useState(false)
2376
+ // 两个提示都自己复位(1.6s / 2.4s)—— 它们只活在组件里,不落盘、不进 store。
2377
+ React.useEffect(() => {
2378
+ if (!copied) return undefined
2379
+ const id = setTimeout(() => setCopied(false), 1600)
2380
+ return () => clearTimeout(id)
2381
+ }, [copied])
2382
+ React.useEffect(() => {
2383
+ if (!copyFailed) return undefined
2384
+ const id = setTimeout(() => setCopyFailed(false), 2400)
2385
+ return () => clearTimeout(id)
2386
+ }, [copyFailed])
2387
+ // 换一篇就复位 —— 否则「已复制」会跟着下一篇继续亮着,说的是上一篇的事。
2388
+ React.useEffect(() => {
2389
+ setCopied(false)
2390
+ setCopyFailed(false)
2391
+ }, [preview.rel])
2392
+ const onCopySource = React.useCallback(() => {
2393
+ copyText(preview.text).then((ok) => {
2394
+ if (ok) setCopied(true)
2395
+ else setCopyFailed(true)
2396
+ })
2397
+ }, [preview.text])
2398
+
1824
2399
  /* ── v0.12 引用条 ────────────────────────────────────
1825
2400
  * 位置:预览头**下面**、正文**上面** —— 一条可折叠的窄条。
1826
2401
  *
@@ -1888,6 +2463,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1888
2463
  })()
1889
2464
 
1890
2465
  // 图片/视频不读正文,直接用同源字节地址渲染;Markdown 才走加载 / MarkdownText / 降级。
2466
+ // v0.19:代码(含 `.map` 这类生成产物)走轻量 CodePane —— **绝不能落到
2467
+ // MarkdownText 那支**,否则 `#` 开头的注释会变成标题、`*` 会变成列表。
2468
+ const isCode = preview.kind === ARTIFACT_CODE || preview.kind === KIND_GENERATED
1891
2469
  const body = preview.status === 'loading'
1892
2470
  ? h('div', { className: 'knit-preview-note' }, t('preview.loading'))
1893
2471
  : preview.status === 'error'
@@ -1904,7 +2482,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1904
2482
  playsInline: true,
1905
2483
  'aria-label': t('media.play'),
1906
2484
  })
1907
- : MarkdownText
2485
+ : isCode
2486
+ ? h(CodePane, { text: preview.text })
2487
+ : MarkdownText
1908
2488
  ? h(MarkdownText, {
1909
2489
  text: preview.text,
1910
2490
  labels: { code: { copyLabel: t('code.copy'), copiedLabel: t('code.copied') }, footnotes: '' },
@@ -1930,30 +2510,68 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1930
2510
  },
1931
2511
  fullscreen ? null : h('div', { className: 'knit-resize', onPointerDown: onResizeStart, title: t('preview.resizeTitle') }),
1932
2512
  h('div', { className: 'knit-preview-head' },
1933
- // 路径,**可点**:用系统默认应用打开这篇本地文档 —— 阅读时多一个
1934
- // 「跳到本地」的入口。不放标题:正文 H1 已经写了,重复会让
1935
- // 「列表行 / 预览头 / 正文」出现三遍同一个词,反而分不清哪块是详情。
2513
+ // 路径,**可点**:在文件管理器里打开它所在的文件夹**并选中这个文件**
2514
+ // (`action: 'reveal'` → macOS `open -R` / Windows `explorer /select,`)。
2515
+ // 与面板顶部那行工作区路径是同一套 remote(`openWorkspacePath`),
2516
+ // 差别只在多带一个 `action` —— 那行是「打开目录」,这条是「定位到文件」。
2517
+ // **打开文件本身**是页脚那个「本地打开」按钮的事,两者刻意分开。
2518
+ // 不放标题:正文 H1 已经写了,重复会让「列表行 / 预览头 / 正文」出现三遍
2519
+ // 同一个词,反而分不清哪块是详情。
1936
2520
  // 目录收敛成 `…/`(2026-10-01 用户要求),完整相对路径在 title 里。
1937
2521
  h('button', {
1938
2522
  type: 'button',
1939
2523
  className: 'knit-preview-path',
1940
- title: onOpenLocal ? t('preview.openLocal', { path: preview.rel }) : preview.rel,
1941
- disabled: !onOpenLocal,
1942
- onClick: () => { if (onOpenLocal) onOpenLocal() },
2524
+ title: onReveal ? t('preview.reveal', { path: preview.rel }) : preview.rel,
2525
+ disabled: !onReveal,
2526
+ onClick: () => { if (onReveal) onReveal() },
1943
2527
  },
1944
2528
  previewPath.dir
1945
2529
  ? h('span', { className: 'knit-preview-dir' }, '…/')
1946
2530
  : null,
1947
2531
  h('span', { className: 'knit-preview-name' }, previewPath.name)),
2532
+ // 复制整篇(只给代码;MarkdownText 自己带代码块复制)
2533
+ isCodeView
2534
+ ? h('button', {
2535
+ className: 'knit-btn',
2536
+ onClick: onCopySource,
2537
+ title: copyFailed ? t('preview.copyFailed') : t('code.copy'),
2538
+ }, copied ? t('code.copied') : t('code.copy'))
2539
+ : null,
2540
+ // Source map:**低权重**入口 —— 只在同名 `<file>.map` 真的存在时出现,
2541
+ // 且 `.map` 本身不参与检索(需求 §6 §28)。点开仍是这个面板,纯文本。
2542
+ isCodeView && preview.mapRel
2543
+ ? h('button', {
2544
+ className: 'knit-btn knit-btn-quiet',
2545
+ onClick: () => { if (onOpenMap) onOpenMap(preview.mapRel) },
2546
+ title: t('preview.sourceMapTitle'),
2547
+ }, t('preview.sourceMap'))
2548
+ : null,
1948
2549
  h('button', {
1949
2550
  className: 'knit-btn',
1950
2551
  onClick: onToggleFullscreen,
1951
2552
  title: fullscreen ? t('preview.exitFullscreenTitle') : t('preview.fullscreenTitle'),
1952
2553
  }, fullscreen ? t('preview.exitFullscreen') : t('preview.fullscreen')),
2554
+ // v0.19 追加:**网页预览** —— 只给 HTML。
2555
+ // 它开的是官方文档预览标签页(`actions.openResource`,与双击列表行**同一条**路),
2556
+ // 那一侧有 DSH 自带的 HTML 渲染器,出来的是**网页**而不是源码。
2557
+ // ⚠️ 这不是把 v0.10 撤掉的那个「新标签页」按钮原样搬回来:当时撤的理由是
2558
+ // 「面板里已经有就地预览,重复度高、用得少」—— 那个判断对 Markdown / 图片 /
2559
+ // 视频成立,对 HTML **不成立**(就地给源码,那边给页面)。所以这里按类型放它出来,
2560
+ // 其余类型仍然只靠双击开新标签页。
2561
+ isWebPage
2562
+ ? h('button', {
2563
+ className: 'knit-btn',
2564
+ onClick: () => { if (onOpenWeb) onOpenWeb() },
2565
+ disabled: !onOpenWeb,
2566
+ title: onOpenWeb ? t('preview.openWebTitle', { path: preview.rel }) : preview.rel,
2567
+ }, t('preview.openWeb'))
2568
+ : null,
1953
2569
  // 「本地打开」= 之前那个「新标签页」的位置(v0.10)。
1954
2570
  // 「新标签页」开的是官方文档预览,但面板里已经有就地预览,重复度高、用得少;
1955
2571
  // 而「用默认应用打开这篇文档」原本只藏在路径的悬停提示里 ——
1956
2572
  // 把值钱的那个放到显眼处,把鸡肋的那个让位(双击列表行仍能开新标签页)。
2573
+ // v0.19 例外:HTML 那边就地预览给不了网页,所以「网页预览」按钮又回来了
2574
+ // (见上面那条);这条注释描述的取舍对其余类型仍然成立。
1957
2575
  h('button', {
1958
2576
  className: 'knit-btn',
1959
2577
  onClick: () => { if (onOpenLocal) onOpenLocal() },
@@ -2068,6 +2686,11 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2068
2686
  status: 'ready',
2069
2687
  docs: data.docs || [],
2070
2688
  root: data.root || '',
2689
+ // v0.19 修订:`hostRoot` 是同一个工作区、但符号链接已展开的那份路径。
2690
+ // 界面**显示**仍用 `root`(用户看到的是自己选的那条路径),凡是**交给宿主
2691
+ // 去打开 / 定位**的路径一律用 `hostRoot` —— DSH 的 `openWorkspacePath` 只认
2692
+ // realpath,含未展开链接的路径会被它判成 `Path has no verified Host path`。
2693
+ hostRoot: data.hostRoot || data.root || '',
2071
2694
  total: data.total || 0,
2072
2695
  error: '',
2073
2696
  mode: data.mode || 'time',
@@ -2110,12 +2733,16 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2110
2733
  || String(doc.rel || '').toLowerCase().includes(q))
2111
2734
  }, [state.docs, query])
2112
2735
 
2113
- /* ── 「全部」:按类型分上下两区 ─────────────────────
2114
- 文档区固定 4 条,多余的在分区标题给「查看全部」;
2115
- 媒体区**不截断** —— 一屏两行以外交给媒体区内部滚动(不隐藏、也不压小格子)。 */
2116
- const docItems = kind === KIND_ALL ? visibleDocs.filter((doc) => !isMedia(doc)) : []
2736
+ /* ── 「全部」:按类型分三区 ─────────────────────
2737
+ 文档区与代码区各固定 4 条,多余的在分区标题给「查看全部」;
2738
+ 媒体区**不截断** —— 一屏两行以外交给媒体区内部滚动(不隐藏、也不压小格子)。
2739
+ v0.19 新增代码区,**顺序放在文档之后**:这不是排序(各区的条目顺序都来自
2740
+ 同一套任务检索),只是混排时的展示次序 —— Markdown 仍然是这个面板的主角。 */
2741
+ const docItems = kind === KIND_ALL ? visibleDocs.filter((doc) => doc.kind === ARTIFACT_DOC) : []
2742
+ const codeItems = kind === KIND_ALL ? visibleDocs.filter((doc) => doc.kind === ARTIFACT_CODE) : []
2117
2743
  const mediaItems = kind === KIND_ALL ? visibleDocs.filter(isMedia) : []
2118
2744
  const shownDocs = docItems.slice(0, ALL_DOC_CAP)
2745
+ const shownCode = codeItems.slice(0, ALL_CODE_CAP)
2119
2746
  // ResizeObserver 量到的是 .knit-list(它自己也有左右内边距),
2120
2747
  // 网格的可用宽度 = 列表宽度 − 列表内边距 − 网格内边距。
2121
2748
  // 文档列表**没有列数可算**:永远一个文档一行(见 `DOC_GRID` 那段说明)。
@@ -2168,8 +2795,12 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2168
2795
  * @returns {Array} 节点数组
2169
2796
  */
2170
2797
  const contextBody = (view) => view.sections.map((section) => h('div', {
2171
- className: 'knit-tier',
2798
+ // 点 Coverage 定位过来时,这一层短暂亮一下(`flashTier`,900ms 后自己收掉)。
2799
+ // 不画箭头、不画横线 —— 用**空间**说「就是这里」。
2800
+ className: `knit-tier${flashTier === section.key ? ' flash' : ''}`,
2172
2801
  key: section.key,
2802
+ // Coverage 的定位锚点:点某一层 → `[data-knit-tier=...]` 滚进视口。
2803
+ 'data-knit-tier': section.key,
2173
2804
  role: 'presentation',
2174
2805
  },
2175
2806
  // ⚠️ 这几个类名**互不为子串**:`byClass` 是子串匹配,若叫
@@ -2196,8 +2827,13 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2196
2827
  /**
2197
2828
  * v0.14:当前任务上下文的分层视图。
2198
2829
  *
2199
- * **只在「文档档 + 相关序 + 宿主给了 context」时成立**;否则返回 null,
2200
- * 下面的渲染退回与 v0.13 逐字一致的平铺列表。
2830
+ * **只在「文档档 / 代码档 + 相关序 + 宿主给了 context」时成立**;否则返回 null,
2831
+ * 下面的渲染退回平铺列表。
2832
+ *
2833
+ * v0.19:多认一档 `KIND_CODE` —— 代码和文档走的是**同一个 Context Pack**
2834
+ * (同一份 Primary / Supporting / Related),只是列表按 `kind` 切了一刀。
2835
+ * 宿主在 `code` 档下同样给 `context`(见 `index.js` 的 `contextPayload()`),
2836
+ * 「全部」档不给 —— 混排视图的分区已经是它自己的结构了。
2201
2837
  *
2202
2838
  * 这一层是**纯投影**:分组、顺序、理由都来自宿主(同一个 Context Model),
2203
2839
  * 客户端不重算任何东西 —— 面板与 `knit_docs` 用的是同一份结果。
@@ -2207,7 +2843,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2207
2843
  */
2208
2844
  const contextView = React.useMemo(() => {
2209
2845
  const pack = state.context
2210
- if (!relevance || kind !== KIND_DOC || !pack) return null
2846
+ if (!relevance || (kind !== KIND_DOC && kind !== KIND_CODE) || !pack) return null
2211
2847
  const tiers = [
2212
2848
  ['primary', 'context.primary', 'context.primaryHint'],
2213
2849
  ['supporting', 'context.supporting', 'context.supportingHint'],
@@ -2292,14 +2928,19 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2292
2928
 
2293
2929
  /**
2294
2930
  * 为一个条目造预览状态:图片/视频直接 ready(字节地址交给 <img>/<video>),
2295
- * Markdown 才进 loading 去拉正文。
2931
+ * 其余(Markdown / 代码)进 loading 去拉正文。
2932
+ *
2933
+ * v0.19:`kind` 必须**原样透传**。这里以前无条件写 `KIND_DOC`,代码接进来之后
2934
+ * 那个写法会让 `.ts` 文件走 MarkdownText 渲染 —— 一行行代码会被当成 Markdown
2935
+ * 排版(`#` 变标题、`*` 变列表、缩进被吃掉)。宿主已经在 `/api/doc` 的响应里
2936
+ * 给了分类结论,客户端照抄即可,不再自己看扩展名。
2296
2937
  */
2297
2938
  const previewFor = React.useCallback((doc) => {
2298
2939
  const base = { rel: doc.rel, title: doc.title || doc.name, path: doc.path || '', text: '', truncated: false }
2299
2940
  if (isMedia(doc)) {
2300
2941
  return { ...base, kind: doc.kind, src: mediaUrl(sessionId, doc.rel), status: 'ready' }
2301
2942
  }
2302
- return { ...base, kind: KIND_DOC, status: 'loading' }
2943
+ return { ...base, kind: doc.kind || ARTIFACT_DOC, status: 'loading' }
2303
2944
  }, [sessionId])
2304
2945
 
2305
2946
  /** 打开(不切换)某篇的预览。 */
@@ -2399,8 +3040,17 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2399
3040
  */
2400
3041
  const apply = (target) => {
2401
3042
  setNotice('')
2402
- // 悬停浮层只列 Markdown,这里固定按文档走 loading→拉正文。
2403
- setPreview({ rel: target.rel, title: target.title, path: target.path || '', kind: KIND_DOC, status: 'loading', text: '', truncated: false })
3043
+ // 悬停浮层由宿主下发 `kind`(v0.19 起浮层也可能列代码)—— 拿不到就当文档,
3044
+ // 走 loading→拉正文。**不要在这里写死**,否则代码会进 MarkdownText。
3045
+ setPreview({
3046
+ rel: target.rel,
3047
+ title: target.title,
3048
+ path: target.path || '',
3049
+ kind: target.kind || ARTIFACT_DOC,
3050
+ status: 'loading',
3051
+ text: '',
3052
+ truncated: false,
3053
+ })
2404
3054
  }
2405
3055
  if (pendingPreview) {
2406
3056
  const queued = pendingPreview
@@ -2418,14 +3068,32 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2418
3068
  * 必然拿到 `knit/not-found`,面板会把它显示成「读取失败」。
2419
3069
  * **与其显示一个假的失败,不如压根不请求、也不显示这一条。**
2420
3070
  */
2421
- const previewIsDoc = !preview || (preview.kind !== 'image' && preview.kind !== 'video')
3071
+ const previewIsDoc = !preview || preview.kind === ARTIFACT_DOC
2422
3072
 
2423
- /** 这篇文档在磁盘上的绝对路径:宿主给的 path 优先,拿不到就用 root + rel 拼。 */
3073
+ /**
3074
+ * 这篇文档在磁盘上的绝对路径,优先级:
3075
+ * ① 宿主 `/api/doc` 给的 `path`(它已经展开过符号链接);
3076
+ * ② `hostRoot + rel`(同一个工作区根,也是 canonical 的);
3077
+ * ③ `root + rel`(老宿主,可能含符号链接 —— 点了会被 DSH 拒)。
3078
+ * 「打开 / 定位」要的是**宿主验证得过的路径**,不是看起来对的那条。
3079
+ */
2424
3080
  const previewAbsPath = preview
2425
- ? (preview.path || joinPath(state.root, preview.rel))
3081
+ ? (preview.path || joinPath(state.hostRoot || state.root, preview.rel))
2426
3082
  : ''
2427
3083
 
2428
- /** 点预览头那行路径 → 用系统默认应用打开本地文档。 */
3084
+ /**
3085
+ * 点预览头那条面包屑 → 在文件管理器里**打开它所在的文件夹并选中这个文件**
3086
+ * (`action: 'reveal'`,macOS 上是 `open -R`)。用户不必在文件夹里自己找。
3087
+ *
3088
+ * 与页脚「本地打开」的分工:那个用默认应用**打开文件**,这个只**定位文件**。
3089
+ * reveal 要的是**文件本身的绝对路径**(不是所在目录)—— 传目录过去会变成
3090
+ * 「在上级目录里选中这个文件夹」,不是我们要的。
3091
+ */
3092
+ const openPreviewReveal = React.useCallback(async () => {
3093
+ setNotice((await openLocalPath(previewAbsPath, { reveal: true })) || '')
3094
+ }, [previewAbsPath])
3095
+
3096
+ /** 页脚「本地打开」→ 用系统默认应用打开这篇文档本身。 */
2429
3097
  const openPreviewLocal = React.useCallback(async () => {
2430
3098
  setNotice((await openLocalPath(previewAbsPath)) || '')
2431
3099
  }, [previewAbsPath])
@@ -2441,9 +3109,24 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2441
3109
  if (!alive) return
2442
3110
  setPreview((cur) => {
2443
3111
  if (!cur || cur.rel !== previewRel) return cur
2444
- return data && data.ok
2445
- ? { ...cur, status: 'ready', text: data.text || '', truncated: Boolean(data.truncated) }
2446
- : { ...cur, status: 'error', error: hostMessage(data) }
3112
+ if (!data || !data.ok) return { ...cur, status: 'error', error: hostMessage(data) }
3113
+ return {
3114
+ ...cur,
3115
+ status: 'ready',
3116
+ text: data.text || '',
3117
+ truncated: Boolean(data.truncated),
3118
+ /* v0.19:分类结论以宿主响应为准 —— 本地点开时已经带上了,但
3119
+ 「悬停浮层点的」「引用条点的」这些入口未必知道,正文到手后
3120
+ 就地校正一次,渲染分支(CodePane vs MarkdownText)才不会选错。
3121
+ `mapRel` 是宿主那次有界 stat 的结果:有同名 `.map` 才给入口。 */
3122
+ kind: data.kind || cur.kind,
3123
+ language: data.language || cur.language,
3124
+ mapRel: data.mapRel || '',
3125
+ /* v0.19 修订:正文到手后把「打开用」的绝对路径也校正过来 ——
3126
+ 自己用 root + rel 拼的那份在符号链接工作区里会被 DSH 判成
3127
+ `Path has no verified Host path`(见宿主 `hostPathOf()`)。 */
3128
+ path: data.path || cur.path,
3129
+ }
2447
3130
  })
2448
3131
  } catch (error) {
2449
3132
  if (!alive) return
@@ -2547,22 +3230,58 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2547
3230
  * 不是「你漏了它」的提醒,更不许写成「Agent 忽略了它」(PRD §8)。
2548
3231
  * ⚠️ 状态值本身是英文(数据层只有一个口径),中文只存在于词典(§15.4 / §24)。
2549
3232
  *
3233
+ /**
3234
+ * v0.17 → v0.18:生命周期现在是**一枚 glyph + 一段极短的文字**。
3235
+ * `○ 未读` / `● 已读 ×n` / `△ 读后已更新` / `↻ 修改后已重新读取`。
3236
+ *
3237
+ * ⚠️ tooltip 与 `aria-label` 挂在 **glyph** 上:`.knit-life` 只许有一个 `className`
3238
+ * prop(client.test.mjs 有守卫盯着)—— 状态是文字,不是可交互控件。
3239
+ * ⚠️ 没有记录就是「未读」:这是**事实**,不是猜测。
3240
+ *
2550
3241
  * @param {string} rel - 相对路径
2551
- * @returns {string|null} 状态文案
3242
+ * @returns {{status:string,char:string,text:string,title:string}|null}
2552
3243
  */
2553
- const lifecycleLabel = (rel) => {
3244
+ const lifeInfo = (rel) => {
2554
3245
  if (!usageOn) return null
2555
3246
  const usageNow = state.usage
2556
3247
  if (!usageNow || !usageNow.stats) return null
2557
3248
  const row = usageNow.lifecycle && usageNow.lifecycle[rel]
2558
- const status = row ? row.status : 'unread'
2559
- if (status === 'unread') return t('lifecycle.unread')
3249
+ const status = row && row.status ? row.status : 'unread'
3250
+ const char = LIFE_GLYPH[status] || LIFE_GLYPH.unread
3251
+ const count = row && Number.isFinite(row.count) ? row.count : 0
3252
+ if (status === 'updated_after_read') {
3253
+ return { status, char, text: t('lifecycle.updatedAfterRead'),
3254
+ title: t('lifecycle.updatedAfterRead') }
3255
+ }
3256
+ if (status === 'reread_after_update') {
3257
+ return { status, char, text: t('lifecycle.rereadAfterUpdate'),
3258
+ title: t('lifecycle.rereadAfterUpdate') }
3259
+ }
2560
3260
  if (status === 'read') {
2561
- return row && row.count >= 2 ? t('lifecycle.readCount', { n: row.count }) : t('lifecycle.read')
3261
+ // 读了几次只说次数:`×3`。**不排序、不评分、不建议**。
3262
+ return { status, char, text: t('lifecycle.readCountShort', { n: count }),
3263
+ title: t('lifecycle.readCount', { n: count }) }
2562
3264
  }
2563
- if (status === 'updated_after_read') return t('lifecycle.updatedAfterRead')
2564
- if (status === 'reread_after_update') return t('lifecycle.rereadAfterUpdate')
2565
- return null
3265
+ return { status: 'unread', char: LIFE_GLYPH.unread,
3266
+ text: t('lifecycle.unread'), title: t('lifecycle.unread') }
3267
+ }
3268
+
3269
+ /** 只有文字的那一半(行尾 `.knit-life`);没有证据时 null,一个节点都不加。 */
3270
+ const lifecycleLabel = (rel) => {
3271
+ const info = lifeInfo(rel)
3272
+ return info ? info.text : null
3273
+ }
3274
+
3275
+ /**
3276
+ * 状态词(**不带次数**)—— 给「次数已经在同一行单独显示」的地方用。
3277
+ * 包外行左边已经有一个 `×N`(它同时是这一档的排序键),再让 lifecycle 说一遍 `×N`
3278
+ * 就会渲染成 `client.js ×71 ×71`(2026-10-05 用真实载荷渲染时抓到)。
3279
+ * `read` 换成短词「已读」;其余三态本来就是词,照旧。
3280
+ */
3281
+ const lifeWord = (rel) => {
3282
+ const info = lifeInfo(rel)
3283
+ if (!info) return null
3284
+ return info.status === 'read' ? t('lifecycle.read') : info.text
2566
3285
  }
2567
3286
 
2568
3287
  /* ── 列表进出动效:这一帧谁新来了、谁走了 ─────────────────────────
@@ -2581,6 +3300,63 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2581
3300
  tweenUntil: 0,
2582
3301
  })
2583
3302
  const [, setMotionSeq] = React.useState(0)
3303
+
3304
+ /* ── v0.18 Usage Lens:三个新状态 + 两个新 effect ────────────────
3305
+ ⚠️ 这些 hook 必须留在**本组件最后一个 hook 之后**:假 React(test/harness.mjs)
3306
+ 按调用顺序分配槽位,`harness.seed()` 又按顺序预置 —— 插在中间会让所有老用例错位。 */
3307
+
3308
+ /** Lens 的展开 / 收起。它与「使用情况」开关是**两个状态**(规格 §25):
3309
+ * 开关管「统计开不开」,这一位只管「统计开着,但暂时不想看细节」。默认展开。 */
3310
+ const [lensOpen, setLensOpen] = React.useState(true)
3311
+ /** 正在短暂高亮的那一层(点 Coverage 定位用);空串=没有高亮。 */
3312
+ const [flashTier, setFlashTier] = React.useState('')
3313
+ /** 面板高度(px)。0 = 量不到(测试替身 / 首帧)——那时按「不矮」处理,不降级。 */
3314
+ const [panelH, setPanelH] = React.useState(0)
3315
+
3316
+ /** 点 Coverage 的某一层 → 滚到那一层 + 短暂高亮。
3317
+ * ⚠️ 滚的是 `.knit-list`(唯一滚动容器):Lens 自己不滚动,也不新增容器。
3318
+ * ⚠️ 高亮走 state 而不是直接改 classList —— 这样测试替身里也能断言到结果。 */
3319
+ const locateTier = (key) => {
3320
+ setFlashTier(key)
3321
+ const host = listRef.current
3322
+ if (host && typeof host.querySelector === 'function') {
3323
+ const el = host.querySelector(`[data-knit-tier="${key}"]`)
3324
+ if (el && typeof el.scrollIntoView === 'function') {
3325
+ // v0.18 UI 迭代(md §十七):把那一层滚到**视口中部**,并且只在允许动效时
3326
+ // 用平滑滚动(`motionAllowed()` 已经把「减弱动态效果」挡在外面 ⇒ 那时是瞬移,
3327
+ // 与 md §十八 的 `scroll-behavior:auto` 同义)。
3328
+ el.scrollIntoView({ behavior: motionAllowed() ? 'smooth' : 'auto', block: 'center' })
3329
+ }
3330
+ }
3331
+ }
3332
+
3333
+ /** 打开某一篇 —— 它**可能不在当前列表里**(包外文档就不在 `state.docs` 里)。
3334
+ * 走模块级 `requestPreview`:与工具输出、其他座位共用同一条打开路径。
3335
+ * ⚠️ **不重新请求列表**:只换预览(规格 §16)。已经打开同一篇就保持原预览。 */
3336
+ const openDocByRel = (rel) => {
3337
+ if (!rel) return
3338
+ if (preview && preview.rel === rel) return
3339
+ requestPreview({ rel, title: rel })
3340
+ }
3341
+
3342
+ // 高亮只亮一下,然后自己收掉(不靠 hover、不靠「点了别处」)。
3343
+ React.useEffect(() => {
3344
+ if (!flashTier) return undefined
3345
+ const timer = setTimeout(() => setFlashTier(''), FLASH_MS)
3346
+ return () => clearTimeout(timer)
3347
+ }, [flashTier])
3348
+
3349
+ // 面板矮的时候 Lens 要降级(Summary + Coverage + 最近读取;Outside / Delta 收成标题)。
3350
+ React.useEffect(() => {
3351
+ if (typeof ResizeObserver !== 'function' || !rootRef.current) return undefined
3352
+ const observer = new ResizeObserver((entries) => {
3353
+ const box = entries && entries[0] && entries[0].contentRect
3354
+ const height = box ? box.height : 0
3355
+ if (height) setPanelH((current) => (Math.abs(current - height) < 1 ? current : height))
3356
+ })
3357
+ observer.observe(rootRef.current)
3358
+ return () => observer.disconnect()
3359
+ }, [])
2584
3360
  const motionOn = motionAllowed()
2585
3361
  // 视图签名:换类型 / 换排序 / 搜索词变了都算「换屏」——整屏一起飞会很吵。
2586
3362
  const motionView = `${kind}|${state.mode}|${query.trim()}`
@@ -2589,9 +3365,13 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2589
3365
  if (state.status === 'error' || state.docs.length === 0 || visibleDocs.length === 0) return []
2590
3366
  if (kind === KIND_MEDIA) return [] // 媒体格子不参与:网格里收起高度没有意义
2591
3367
  if (kind === KIND_ALL) {
2592
- if (docItems.length === 0) return []
2593
- return shownDocs.map((doc, index) => (
2594
- { rel: doc.rel, tierKey: MOTION_TIER_ALL_DOCS, index, doc }))
3368
+ if (docItems.length === 0 && codeItems.length === 0) return []
3369
+ return [
3370
+ ...shownDocs.map((doc, index) => (
3371
+ { rel: doc.rel, tierKey: MOTION_TIER_ALL_DOCS, index, doc })),
3372
+ ...shownCode.map((doc, index) => (
3373
+ { rel: doc.rel, tierKey: MOTION_TIER_ALL_CODE, index, doc })),
3374
+ ]
2595
3375
  }
2596
3376
  if (contextView) {
2597
3377
  const rows = []
@@ -2699,8 +3479,16 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2699
3479
  // `mark`=没号时同列的占位标记,只在「这一屏里有号」时为真。
2700
3480
  // 进出动效只在真机上跑(`motionOn`):测试替身没有 DOM,`motionAllowed()` 挡掉,
2701
3481
  // 于是渲染树里既没有 `entering` 也没有 `leaving`,与没有这段动效时逐字一致。
3482
+ // v0.18:生命周期现在是**一枚 glyph + 一段极短的文字**。glyph 可点:
3483
+ // 点它=打开 / 选中这一篇(**已经打开则保持原预览**,不重开也不重拉)。
3484
+ const info = withLife ? lifeInfo(doc.rel) : null
2702
3485
  return h(DocRow, { ...common, relevance, why: whyText(doc.reason), num, mark, primary,
2703
- life: withLife ? lifecycleLabel(doc.rel) : null,
3486
+ life: info ? info.text : null,
3487
+ glyph: info,
3488
+ onGlyph: (target) => {
3489
+ if (preview && preview.rel === target.rel) return
3490
+ openPreview(target)
3491
+ },
2704
3492
  entering: motion.entered.has(doc.rel) ? motion.entered.get(doc.rel) : null,
2705
3493
  leaving: Boolean(doc.knitLeaving) })
2706
3494
  }
@@ -2725,6 +3513,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2725
3513
  docItems.length === 0 ? null : h('div', { className: 'knit-section', key: 'docs' },
2726
3514
  sectionHead('kind.doc', shownDocs.length, docItems.length, KIND_DOC),
2727
3515
  docsGrid(withGhosts(MOTION_TIER_ALL_DOCS, shownDocs))),
3516
+ codeItems.length === 0 ? null : h('div', { className: 'knit-section', key: 'code' },
3517
+ sectionHead('kind.code', shownCode.length, codeItems.length, KIND_CODE),
3518
+ docsGrid(withGhosts(MOTION_TIER_ALL_CODE, shownCode))),
2728
3519
  mediaItems.length === 0 ? null : h('div', { className: 'knit-section', key: 'media' },
2729
3520
  // 媒体不截断,所以只给一个标题,不给「已显示 / 总数」和「查看全部」
2730
3521
  h('div', { className: 'knit-section-head' },
@@ -2735,7 +3526,11 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2735
3526
 
2736
3527
  // 媒体视图:一格都不隐藏 —— 一屏两行以外的部分在媒体区**内部滚动**,
2737
3528
  // 既不让面板被整面媒体墙顶爆,也不会像旧版那样把剩下的条目直接切掉。
2738
- const emptyText = kind === KIND_MEDIA ? t('list.emptyMedia') : t('list.empty')
3529
+ const emptyText = kind === KIND_MEDIA
3530
+ ? t('list.emptyMedia')
3531
+ : kind === KIND_CODE
3532
+ ? t('list.emptyCode')
3533
+ : t('list.empty')
2739
3534
  const body = state.status === 'loading' && state.docs.length === 0
2740
3535
  ? h('div', { className: 'knit-msg' }, t('list.scanning'))
2741
3536
  : state.status === 'error'
@@ -2758,61 +3553,144 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2758
3553
  // title 里(可见文本本来就不许出现关键词,test/i18n.test.mjs 有守卫)。
2759
3554
  // ⚠️ i18n 里那四个 topic.* 键已同时删除,不要为了「以后可能用」留着。
2760
3555
 
2761
- /* v0.15「使用情况」:只把**事实**读出来 —— 先看的那篇读没读、辅助读了几篇、
2762
- 一共读了几次、几次落在包外、上下文换过几回。
3556
+ /* v0.18「Context Usage Lens」:列表**上方**的一块轻量观察层。
3557
+ 它按**视觉层级**回答四件事(规格 §9 的三层):
3558
+ Level 1 当前上下文 Coverage(这一份上下文被用到什么程度)
3559
+ Level 2 最近读取(最近一次成功读的是什么)
3560
+ Level 3 上下文外读取 / 上下文变化(辅助事实)
3561
+ 三块不能一样重 —— 靠**空间与字号**拉开,不靠横线、不靠颜色、不靠卡片。
2763
3562
  ⚠️ 不许出现分数 / 百分比 / 评分条 / 置信度 / 「AI 判断」这类词:用户要知道的是
2764
- 「这份上下文有没有被用上」,不是「它好不好用」。**没有任何一行是估算出来的。** */
2765
- const usageText = (() => {
2766
- if (!usageOn) return ''
2767
- const u = state.usage
2768
- if (!u || !u.stats) return t('usage.none')
2769
- const s = u.stats
2770
- const parts = []
2771
- // SDD §20:只多一句「当前上下文 · Epoch N」—— `epochId` 是**累计编号**(换一次 +1),
2772
- // 不是「第几份包」;一份包都没交过时是 null,整句不显示。
2773
- if (Number.isInteger(u.epochId)) parts.push(t('usage.epoch', { n: u.epochId }))
2774
- if (s.primaryRel) {
2775
- parts.push(s.primaryFollowThrough
2776
- ? t('usage.primaryRead', { rel: s.primaryRel })
2777
- : t('usage.primaryUnread', { rel: s.primaryRel }))
2778
- }
2779
- const sup = (s.byTier && s.byTier.supporting) || { read: 0, total: 0 }
2780
- if (sup.total > 0) parts.push(t('usage.supporting', { read: sup.read, total: sup.total }))
2781
- if (s.reads) parts.push(t('usage.reads', { n: s.reads }))
2782
- if (s.outside) parts.push(t('usage.outside', { n: s.outside }))
2783
- if (s.churn && s.churn.snapshots) parts.push(t('usage.changes', { n: s.churn.snapshots }))
3563
+ 「这份上下文有没有被用上」,不是「它好不好用」。**没有任何一行是估算出来的。**
3564
+ ⚠️ 关掉使用情况时**一个节点都不加**(`.knit-usage` 整个不渲染,与 v0.17 一致)。*/
3565
+
3566
+ const usageNow = usageOn && state.usage && state.usage.stats ? state.usage : null
3567
+ // 「Epoch N」只在标题行显示一次:`epochId` 是**累计编号**(换一次 +1),
3568
+ // 一份包都没交过时是 null,整个角标不显示(SDD §20)。
3569
+ const epochText = usageNow && Number.isInteger(usageNow.epochId)
3570
+ ? t('lens.epoch', { n: usageNow.epochId })
3571
+ : ''
3572
+ // 摘要行=三件纯事实,一行读完。**不写 Primary 文件名、不写「辅助 0/3」**——
3573
+ // 那两件事下面的 Coverage 说得更准、更短(规格 §10)。
3574
+ const lensSummary = (() => {
3575
+ if (!usageNow) return t('usage.none')
3576
+ const s = usageNow.stats
3577
+ const parts = [t('lens.reads', { n: s.reads || 0 })]
3578
+ if (s.outside) parts.push(t('lens.outside', { n: s.outside }))
3579
+ const changes = s.churn && s.churn.snapshots ? s.churn.snapshots : 0
3580
+ if (changes) parts.push(t('lens.changes', { n: changes }))
2784
3581
  return parts.join(' · ')
2785
3582
  })()
2786
3583
 
2787
- /* v0.17:三条新事实 —— 全部只在「使用情况」开着、且宿主真的回传了 `usage` 时出现。
2788
- ① 最近读取(按事件 seq 认「谁是最近一次」,墙钟只用来算相对时间)
2789
- ② 上下文外读取的明细(当前包外、但真实成功读过)
2790
- ③ 最近**一次** Context Delta
2791
- ⚠️ 关掉使用情况时**一个节点都不加**:DOM 与 v0.16 逐字一致。
3584
+ /* v0.17 的三条事实 —— 全部只在「使用情况」开着、且宿主真的回传了 `usage` 时出现。
2792
3585
  ⚠️ 这里没有时间线、没有全量事件、没有评分 —— 「最近一次」就只有一条。 */
2793
- const usageFacts = usageOn && state.usage && state.usage.stats ? state.usage : null
2794
-
2795
- const recentReadNode = usageFacts && usageFacts.recentRead && usageFacts.recentRead.rel
2796
- ? h('div', { className: 'knit-usage-more' },
2797
- t('usage.recentRead', {
2798
- rel: usageFacts.recentRead.rel,
2799
- time: relTime(usageFacts.recentRead.at, tick),
2800
- }))
2801
- : null
2802
3586
 
2803
- const outsideList = usageFacts && Array.isArray(usageFacts.outsideDocs) ? usageFacts.outsideDocs : []
2804
- const gapNode = outsideList.length > 0
3587
+ // ── Level 1:当前上下文 Coverage ────────────────────────────────
3588
+ // ⚠️ 用 `state.context` 的三层**原始** rels(不是 `contextView`:那一份被过滤框
3589
+ // 子集化、而且只在文档档 + 相关序成立),再叠上 `usage.lifecycle` —— 纯派生,
3590
+ // 不新增任何一份自己的状态(「能派生就不要存储」)。
3591
+ const coverage = coverageOf({
3592
+ primary: (state.context && state.context.primary) || [],
3593
+ supporting: (state.context && state.context.supporting) || [],
3594
+ related: (state.context && state.context.related) || [],
3595
+ }, usageNow ? usageNow.lifecycle : null)
3596
+ const coverageNode = contextView ? h('div', { className: 'knit-lens-sec', key: 'cov' },
3597
+ h('div', { className: 'knit-lens-cap' }, t('lens.currentContext')),
3598
+ h('div', { className: 'knit-cov' },
3599
+ ['primary', 'supporting', 'related']
3600
+ // Primary 可以被一份包整体缺席 —— 那就整列不显示,而不是画一个
3601
+ // 「0 / 0」的假层(规格 §11:Knit 不能假设一定有 Primary)。
3602
+ .filter((key) => !(key === 'primary' && coverage.primary.total === 0))
3603
+ .map((key) => h('button', {
3604
+ className: 'knit-cov-col',
3605
+ key,
3606
+ type: 'button',
3607
+ title: t('lens.locate', { tier: t(`tierName.${key}`) }),
3608
+ // 读屏的说法是完整一句「主要上下文:0 / 1 篇已读」(md §六十三)——
3609
+ // 但**视觉上不显示这句话**:屏幕上给的是层名 + `n / m` + 圆点。
3610
+ 'aria-label': t('lens.coverageAria', {
3611
+ tier: t(`tierName.${key}`),
3612
+ read: coverage[key].read,
3613
+ total: coverage[key].total,
3614
+ }),
3615
+ onClick: () => locateTier(key),
3616
+ },
3617
+ // 视觉(点)与文本(已读 ÷ 本层总数)**同时**存在:只给点读不出「读了几篇」,
3618
+ // 只给数字又看不出「是哪几篇」。没有进度条、没有百分比。
3619
+ // ⚠️ **顺序**是「层名 → 数字 → 圆点」,不要调换:这三个是 grid 的同一套单元格,
3620
+ // 自动排布按 DOM 顺序找空位 —— 层名占第 1 行第 1 列、数字占第 1 行第 2 列、
3621
+ // 圆点那一条横跨两列,于是必然落到第 2 行(换顺序数字会被挤到圆点下面一行)。
3622
+ h('span', { className: 'knit-cov-name' }, t(`tierName.${key}`)),
3623
+ h('span', { className: 'knit-cov-num' },
3624
+ `${coverage[key].read} / ${coverage[key].total}`),
3625
+ // v0.18 UI 迭代:**真的圆**(9px,见 CSS),不再是 `○ ●` 字符 —— 字符圆点在不同
3626
+ // 字体下大小不一,正是「不像设计稿」的那一处。点本身对读屏是装饰(aria-hidden),
3627
+ // 「几篇已读」由上面那个 aria-label 的完整句子说。
3628
+ h('span', { className: 'knit-cov-dots' },
3629
+ coverage[key].rels.map((item) => h('span', {
3630
+ className: `knit-cov-dot${item.read ? ' on' : ''}`,
3631
+ key: item.rel,
3632
+ 'aria-hidden': 'true',
3633
+ }))))))) : null
3634
+
3635
+ // ── Level 2:最近读取(最近一次**成功** read;不是「正在阅读」)──────
3636
+ const recent = usageNow && usageNow.recentRead ? usageNow.recentRead : null
3637
+ const recentNode = h('div', { className: 'knit-lens-sec', key: 'recent' },
3638
+ h('div', { className: 'knit-lens-name' }, t('lens.recentRead')),
3639
+ recent && recent.rel
3640
+ ? h('button', {
3641
+ className: 'knit-read-row',
3642
+ type: 'button',
3643
+ title: t('lens.openDoc', { rel: recent.rel }),
3644
+ // 这一行整行可点(打开预览),所以它需要一个**完整的可访问名**(md §二十二):
3645
+ // 只有 title 的话读屏在部分平台读不出「这是干什么的」。
3646
+ 'aria-label': t('lens.openDoc', { rel: recent.rel }),
3647
+ onClick: () => openDocByRel(recent.rel),
3648
+ },
3649
+ h('span', { className: 'knit-read-rel' }, recent.rel),
3650
+ h('span', { className: 'knit-read-time' }, relTime(recent.at, tick)),
3651
+ // 箭头是装饰(对读屏隐藏);不要前导空格 —— 间距由 .knit-read-row 的 gap 给。
3652
+ h('span', { className: 'knit-read-go', 'aria-hidden': 'true' }, '›'))
3653
+ : h('div', { className: 'knit-lens-empty' }, t('lens.recentNone')))
3654
+
3655
+ // ── Level 3a:上下文外读取(可浏览集合;排序是**事实排序**)─────────
3656
+ const outsideList = usageNow && Array.isArray(usageNow.outsideDocs) ? usageNow.outsideDocs : []
3657
+ const outsideSorted = groupOutsideDocs(outsideList)
3658
+ const outsideNode = outsideSorted.length > 0
2805
3659
  ? h('div', { className: 'knit-usage-more', key: 'gap' },
2806
3660
  h('button', {
2807
3661
  className: 'knit-more-btn',
2808
3662
  type: 'button',
2809
3663
  'aria-expanded': gapOpen ? 'true' : 'false',
2810
3664
  onClick: () => setGapOpen((value) => !value),
2811
- }, t('usage.outsideDocs', { n: outsideList.length })),
3665
+ },
3666
+ // 菜单行的三段(md §三十四):「label ── 数量 ›」。原来把两条信息压在一个字符串里
3667
+ // (`上下文外读取 · 20`),数字既不右对齐、也不能单独参与排版。
3668
+ h('span', { className: 'knit-more-label' }, t('lens.outsideDocs')),
3669
+ h('span', { className: 'knit-more-meta' }, String(outsideSorted.length)),
3670
+ h('span', { className: 'knit-read-go', 'aria-hidden': 'true' }, gapOpen ? '⌃' : '›')),
2812
3671
  gapOpen ? h('div', { className: 'knit-gap-list' },
2813
- outsideList.slice(0, 10).map((row) => h('div', { className: 'knit-gap-row', key: row.rel },
2814
- h('span', { className: 'knit-gap-rel', title: row.rel }, row.rel),
2815
- h('span', { className: 'knit-life' }, lifecycleLabel(row.rel))))) : null)
3672
+ // 每一行都是**可点对象**(点开预览),但**不许**加入 Context ——
3673
+ // V0.18 不做 Context Control(规格 §19)。
3674
+ // 行首序号(md §三十六):让展开的包外列表可数,并把 rel 与次数隔开。
3675
+ // 序号说的是**位置**(第几篇),不是评分。
3676
+ outsideSorted.slice(0, MAX_OUTSIDE_SHOWN).map((row, i) => h('button', {
3677
+ className: 'knit-out-row',
3678
+ key: row.rel,
3679
+ type: 'button',
3680
+ title: t('lens.openDoc', { rel: row.rel }),
3681
+ onClick: () => openDocByRel(row.rel),
3682
+ },
3683
+ h('span', { className: 'knit-out-num' }, String(i + 1).padStart(2, '0')),
3684
+ h('span', { className: 'knit-out-rel' }, row.rel),
3685
+ h('span', { className: 'knit-out-count' }, `×${row.count}`),
3686
+ // 每一行都带生命周期:**复用 v0.17 那一份数据**,不维护第二套。
3687
+ // ⚠️ 用 `lifeWord`(状态词)而不是 `lifecycleLabel`(短次数):左边已经有 `×N` 了。
3688
+ h('span', { className: 'knit-life' }, lifeWord(row.rel)))),
3689
+ outsideSorted.length > MAX_OUTSIDE_SHOWN
3690
+ ? h('div', { className: 'knit-gap-row' },
3691
+ h('span', { className: 'knit-gap-rel' },
3692
+ t('lens.more', { n: outsideSorted.length - MAX_OUTSIDE_SHOWN })))
3693
+ : null) : null)
2816
3694
  : null
2817
3695
 
2818
3696
  // 层级的**短名**:分组标题那套长文案(主要上下文 / 辅助上下文 / 相关上下文)在变化行里太长。
@@ -2822,31 +3700,41 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2822
3700
  if (key === 'related') return t('tierName.related')
2823
3701
  return ''
2824
3702
  }
2825
- const delta = usageFacts && usageFacts.latestDelta ? usageFacts.latestDelta : null
3703
+ const delta = usageNow && usageNow.latestDelta ? usageNow.latestDelta : null
2826
3704
  const deltaLine = (text, key) => h('div', { className: 'knit-delta-row', key },
2827
3705
  h('span', { className: 'knit-delta-rel' }, text))
3706
+ /** `moved` 的两种载荷都认:v0.17 起宿主给的是 `{tier,rank}`,旧夹具里是裸层名。 */
3707
+ const tierOf = (value) => (value && typeof value === 'object' ? value.tier : value)
3708
+ const deltaText = (kind, item) => {
3709
+ if (kind === 'enter') return `+ ${item.rel}`
3710
+ if (kind === 'leave') return `- ${item.rel}`
3711
+ return `↔ ${item.rel} · ${tierShort(tierOf(item.from))} → ${tierShort(tierOf(item.to))}`
3712
+ }
2828
3713
  // 摘要行的符号只用 `+` `-` `↔` 三个通用符号,不用颜色区分「进 / 出」。
3714
+ const grouped = groupDelta(delta)
2829
3715
  const deltaDigest = []
2830
- if (delta) {
2831
- for (const item of (Array.isArray(delta.appeared) ? delta.appeared : [])) {
2832
- deltaDigest.push({ key: `plus-${item.rel}`, text: `+ ${item.rel}` })
2833
- }
2834
- for (const item of (Array.isArray(delta.disappeared) ? delta.disappeared : [])) {
2835
- deltaDigest.push({ key: `minus-${item.rel}`, text: `- ${item.rel}` })
2836
- }
2837
- for (const item of (Array.isArray(delta.moved) ? delta.moved : [])) {
2838
- deltaDigest.push({
2839
- key: `move-${item.rel}`,
2840
- text: `↔ ${item.rel} · ${tierShort(item.from)} → ${tierShort(item.to)}`,
2841
- })
2842
- }
2843
- if (delta.taskChanged) deltaDigest.push({ key: 'task', text: t('usage.deltaTask') })
3716
+ for (const item of grouped.enter) {
3717
+ deltaDigest.push({ key: `plus-${item.rel}`, text: deltaText('enter', item) })
2844
3718
  }
2845
- const deltaGroups = delta ? [
2846
- { key: 'enter', label: t('usage.deltaEnter'), rows: deltaDigest.filter((line) => line.key.startsWith('plus-')) },
2847
- { key: 'leave', label: t('usage.deltaLeave'), rows: deltaDigest.filter((line) => line.key.startsWith('minus-')) },
2848
- { key: 'move', label: t('usage.deltaMove'), rows: deltaDigest.filter((line) => line.key.startsWith('move-')) },
2849
- ] : []
3719
+ for (const item of grouped.leave) {
3720
+ deltaDigest.push({ key: `minus-${item.rel}`, text: deltaText('leave', item) })
3721
+ }
3722
+ for (const item of grouped.move) {
3723
+ deltaDigest.push({ key: `move-${item.rel}`, text: deltaText('move', item) })
3724
+ }
3725
+ if (delta && delta.taskChanged) deltaDigest.push({ key: 'task', text: t('usage.deltaTask') })
3726
+ const deltaGroups = [
3727
+ { key: 'enter', label: t('usage.deltaEnter'),
3728
+ rows: grouped.enter.map((item) => ({ key: `plus-${item.rel}`, text: deltaText('enter', item) })) },
3729
+ { key: 'leave', label: t('usage.deltaLeave'),
3730
+ rows: grouped.leave.map((item) => ({ key: `minus-${item.rel}`, text: deltaText('leave', item) })) },
3731
+ { key: 'move', label: t('usage.deltaMove'),
3732
+ rows: grouped.move.map((item) => ({ key: `move-${item.rel}`, text: deltaText('move', item) })) },
3733
+ ].filter((group) => group.rows.length > 0)
3734
+ // ⚠️ `compact` 必须在 `previewLines` 之前算出来(TDZ)。
3735
+ const compact = panelH > 0 && panelH < COMPACT_PANEL_PX
3736
+ // 面板矮的时候收起态**不铺摘要行** —— 只留标题,点开照常看得到。
3737
+ const previewLines = compact ? [] : deltaDigest.slice(0, MAX_DELTA_SHOWN)
2850
3738
  const deltaNode = delta
2851
3739
  ? h('div', { className: 'knit-usage-more', key: 'delta' },
2852
3740
  h('button', {
@@ -2854,28 +3742,64 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2854
3742
  type: 'button',
2855
3743
  'aria-expanded': deltaOpen ? 'true' : 'false',
2856
3744
  onClick: () => setDeltaOpen((value) => !value),
2857
- }, t('usage.deltaTitle')),
2858
- deltaDigest.slice(0, 3).map((line) => deltaLine(line.text, line.key)),
2859
- deltaDigest.length > 3
2860
- ? deltaLine(t('usage.deltaMore', { n: deltaDigest.length - 3 }), 'more')
3745
+ },
3746
+ // 菜单行的三段(md §三十八):「上下文变化 ── 最近一次 ›」。
3747
+ // ⚠️ 这里**不再写条数**(原来是 `上下文变化 · 11`):变化永远只说最近一次,
3748
+ // 「有几条」由展开后的行数与「还有 N 条」承担 —— 数字写在按钮上时,
3749
+ // 折叠摘要、分组尾巴、按钮三处会各自算一遍,很容易自相矛盾。
3750
+ h('span', { className: 'knit-more-label' }, t('lens.delta')),
3751
+ h('span', { className: 'knit-more-meta' }, t('lens.deltaLatest')),
3752
+ h('span', { className: 'knit-read-go', 'aria-hidden': 'true' }, deltaOpen ? '⌃' : '›')),
3753
+ // ⚠️ 展开后**不再画折叠摘要**:分组视图是它的超集(三行摘要 + 「还有 N 条」再叠上
3754
+ // 分组明细,同一条事实会在同一块里出现两遍 —— 2026-10-05 用真实载荷渲染时抓到)。
3755
+ deltaOpen ? null : previewLines.map((line) => deltaLine(line.text, line.key)),
3756
+ !deltaOpen && !compact && deltaDigest.length > MAX_DELTA_SHOWN
3757
+ ? deltaLine(t('usage.deltaMore', { n: deltaDigest.length - MAX_DELTA_SHOWN }), 'more')
2861
3758
  : null,
2862
3759
  deltaOpen ? deltaGroups
2863
- .filter((group) => group.rows.length > 0)
2864
3760
  .map((group) => [
2865
3761
  h('div', { className: 'knit-delta-head', key: `${group.key}-head` }, group.label),
2866
- ...group.rows.slice(0, 5).map((line) => deltaLine(line.text, `${group.key}-${line.key}`)),
2867
- group.rows.length > 5
2868
- ? deltaLine(t('usage.deltaMore', { n: group.rows.length - 5 }), `${group.key}-more`)
3762
+ ...group.rows.slice(0, MAX_DELTA_GROUP)
3763
+ .map((line) => deltaLine(line.text, `${group.key}-${line.key}`)),
3764
+ group.rows.length > MAX_DELTA_GROUP
3765
+ ? deltaLine(t('usage.deltaMore', { n: group.rows.length - MAX_DELTA_GROUP }),
3766
+ `${group.key}-more`)
2869
3767
  : null,
2870
- ]) : null)
3768
+ ]) : null,
3769
+ // ⚠️ 「任务上下文已更新」不是进出换层,没有分组标题可挂 —— 但它算在
3770
+ // `deltaDigest.length` 里(按钮上那个数字就是它)。展开时漏掉这一行,
3771
+ // 就会出现「按钮说 6 条、下面只列出 5 行」的自相矛盾(2026-10-05 用真实载荷渲染时抓到)。
3772
+ // 它在摘要里的位置本来就是最后一条,这里也放最后。
3773
+ deltaOpen && delta && delta.taskChanged
3774
+ ? deltaLine(t('usage.deltaTask'), 'task')
3775
+ : null)
2871
3776
  : null
2872
3777
 
2873
- // 不同类型用不同量词:文档「篇」、媒体「个」、混排「项」。
3778
+ // ── Lens 整块:标题行(可点,展开 / 收起)+ 摘要行 + 细节 ──────────
3779
+ // ⚠️ 「收起」不等于「关掉统计」:收起只表示「统计开着,但暂时不想看细节」(规格 §25)。
3780
+ const lensNode = h('div', { className: 'knit-usage', title: t('usage.note') },
3781
+ h('button', {
3782
+ className: 'knit-lens-head',
3783
+ type: 'button',
3784
+ 'aria-expanded': lensOpen ? 'true' : 'false',
3785
+ title: lensOpen ? t('lens.collapse') : t('lens.expand'),
3786
+ onClick: () => setLensOpen((value) => !value),
3787
+ },
3788
+ h('span', { className: 'knit-lens-title' }, t('lens.title')),
3789
+ epochText ? h('span', { className: 'knit-lens-epoch' }, epochText) : null,
3790
+ h('span', { className: 'knit-read-go', 'aria-hidden': 'true' }, lensOpen ? ' ˄' : ' ˅')),
3791
+ h('div', { className: 'knit-lens-sum' }, lensSummary),
3792
+ lensOpen ? h('div', { className: 'knit-lens-body' },
3793
+ coverageNode, recentNode, outsideNode, deltaNode) : null)
3794
+
3795
+ // 不同类型用不同量词:文档「篇」、代码「个」、媒体「个」、混排「项」。
2874
3796
  const countKey = kind === KIND_MEDIA
2875
3797
  ? (filtering ? 'count.media.filtered' : 'count.media')
2876
- : kind === KIND_ALL
2877
- ? (filtering ? 'count.all.filtered' : 'count.all')
2878
- : (filtering ? 'count.filtered' : 'count')
3798
+ : kind === KIND_CODE
3799
+ ? (filtering ? 'count.code.filtered' : 'count.code')
3800
+ : kind === KIND_ALL
3801
+ ? (filtering ? 'count.all.filtered' : 'count.all')
3802
+ : (filtering ? 'count.filtered' : 'count')
2879
3803
  const countText = filtering
2880
3804
  ? t(countKey, { hit: visibleDocs.length, total: state.total })
2881
3805
  : t(countKey, { n: state.total })
@@ -2892,7 +3816,8 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2892
3816
  title: state.root ? t('path.openTitle') : '',
2893
3817
  disabled: !state.root,
2894
3818
  onClick: async () => {
2895
- setNotice((await openLocalPath(state.root)) || '')
3819
+ // 打开文件夹同样要走 canonical 路径 —— 目录也会被同一条 `verifyDesktopPath` 拒。
3820
+ setNotice((await openLocalPath(state.hostRoot || state.root)) || '')
2896
3821
  },
2897
3822
  }, state.root || '—'),
2898
3823
  h('div', { className: 'knit-count' }, countText),
@@ -2928,7 +3853,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2928
3853
  },
2929
3854
  })),
2930
3855
  h('div', { className: 'knit-types', role: 'tablist', 'aria-label': t('kind.title') },
2931
- [[KIND_DOC, 'kind.doc'], [KIND_MEDIA, 'kind.media'], [KIND_ALL, 'kind.all']].map(([value, labelKey]) =>
3856
+ // v0.19:四档「文档 / 代码 / 媒体 / 全部」。**没有第二层分类** ——
3857
+ // 代码里不再按语言(JS / TS / Python…)分组(需求 §46:不给代码加视觉层级压迫)。
3858
+ [[KIND_DOC, 'kind.doc'], [KIND_CODE, 'kind.code'], [KIND_MEDIA, 'kind.media'], [KIND_ALL, 'kind.all']].map(([value, labelKey]) =>
2932
3859
  h('button', {
2933
3860
  type: 'button',
2934
3861
  key: value,
@@ -2938,13 +3865,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2938
3865
  title: t('kind.title'),
2939
3866
  onClick: () => pickKind(value),
2940
3867
  }, t(labelKey)))),
2941
- // v0.15:开了才显示。一行事实,没有卡片、没有分数条。
2942
- // v0.17:这一行下面最多再加三块 —— 最近读取、上下文外读取(折叠)、最近一次变化(折叠)。
2943
- usageOn ? h('div', { className: 'knit-usage', title: t('usage.note') },
2944
- usageText || t('usage.none'),
2945
- recentReadNode,
2946
- gapNode,
2947
- deltaNode) : null,
3868
+ // v0.15:开了才显示。v0.18:这一块是「Context Usage Lens」——
3869
+ // 列表**上方**的观察层,不是弹窗、不是新页面、不是 Dashboard。
3870
+ usageOn ? lensNode : null,
2948
3871
  notice ? h('div', { className: 'knit-notice' }, notice) : null,
2949
3872
  // 列表节点**直接挂上去**(2026-09-29 起永远单栏;曾经它要交给一个 IIFE
2950
3873
  // 决定塞进单栏还是双栏的左列)。**输出与 v0.13 逐字一致** ——
@@ -2992,6 +3915,18 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2992
3915
  onOpenLink: (item) => requestPreview(item),
2993
3916
  // 拿不到绝对路径就不给点(而不是点了没反应)
2994
3917
  onOpenLocal: previewAbsPath ? openPreviewLocal : null,
3918
+ onReveal: previewAbsPath ? openPreviewReveal : null,
3919
+ /* v0.19 Source map:仍走 `requestPreview` 这条既有通道,不新开一条打开路径。
3920
+ `.map` 是宿主分类层判定的 `generated`(previewable 但 contextual:false)——
3921
+ 面板能看它,列表与检索永远见不到它(需求 §6 §28 §29)。 */
3922
+ onOpenMap: (rel) => requestPreview({
3923
+ rel,
3924
+ title: rel.split('/').pop(),
3925
+ kind: KIND_GENERATED,
3926
+ }),
3927
+ /* v0.19 追加:HTML 的「网页预览」走**同一条**官方标签页通道(`onOpenTab`),
3928
+ 不新开第二条打开路径。宿主没提供这条能力时按钮置灰,而不是点了没反应。 */
3929
+ onOpenWeb: typeof openInTab === 'function' ? () => onOpenTab(preview) : null,
2995
3930
  onClose: closePreview,
2996
3931
  onToggleFullscreen: () => setFullscreen((v) => !v),
2997
3932
  onResizeStart,
@@ -3392,12 +4327,19 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
3392
4327
 
3393
4328
  /**
3394
4329
  * 请求在面板里打开某一篇。面板挂着就立刻生效,没挂就留一份挂起。
3395
- * @param {{rel:string, title?:string, name?:string}} doc - 目标文档
4330
+ * @param {{rel:string, title?:string, name?:string, path?:string, kind?:string}} doc - 目标文档
3396
4331
  * @returns {void}
3397
4332
  */
3398
4333
  function requestPreview(doc) {
3399
4334
  if (!doc || !doc.rel) return
3400
4335
  const target = { rel: doc.rel, title: doc.title || doc.name || doc.rel }
4336
+ /* v0.19:把 `path` / `kind` 一起带过去。
4337
+ 以前这里只传 `rel` + `title`,于是接收端只能自己猜类型(猜的结果就是
4338
+ 「一律当 Markdown」)。分类结论在宿主,这一路上不该被丢掉。
4339
+ ⚠️ 两个字段都**只在有值时**写入:调用方常传 `{rel, title}`,别把
4340
+ `kind: undefined` 传下去,那会覆盖掉接收端的兜底默认值。 */
4341
+ if (doc.path) target.path = doc.path
4342
+ if (doc.kind) target.kind = doc.kind
3401
4343
  if (previewSubscribers.size === 0) {
3402
4344
  pendingPreview = target
3403
4345
  return
@@ -3422,17 +4364,27 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
3422
4364
  * 它把业务值折进一个信封(`{ ok: true, value } | { ok: false, error }`),
3423
4365
  * 所以这里要拆信封而不是直接 await 出结果。
3424
4366
  *
3425
- * @param {string} path - 绝对路径
4367
+ * `options.reveal` 走的是**同一个** remote 的同一个方法,只是多带一个
4368
+ * `action: 'reveal'`(DSH 的 `SessionOpenWorkspacePathRequest.action`)。
4369
+ * 主机侧落在 `revealNativePath` 上:macOS 是 `open -R`、Windows 是
4370
+ * `explorer /select,`,也就是**打开所在文件夹并选中这个文件** ——
4371
+ * 用户不必再在文件夹里自己找(Chrome「在文件夹中显示」是同一件事)。
4372
+ * ⚠️ Linux 的 xdg-open 没有「选中」这个概念,那边只有打开目录,
4373
+ * 这是平台差异,不是我们少做了一步。
4374
+ *
4375
+ * @param {string} path - 绝对路径(reveal 要的是**文件本身**,不是它所在的目录)
4376
+ * @param {{reveal?:boolean}} [options] - `reveal` 为真则在文件管理器里选中它
3426
4377
  * @returns {Promise<string>} 空串表示成功,否则是失败原因
3427
4378
  */
3428
- async function openLocalPath(path) {
4379
+ async function openLocalPath(path, options = {}) {
3429
4380
  if (!path) return t('error.hostFailed')
3430
4381
  const services = rootCtx && typeof rootCtx.get === 'function' ? rootCtx.get('remote.session') : null
3431
4382
  if (!services || typeof services.openWorkspacePath !== 'function') {
3432
4383
  return t('error.noHostTab')
3433
4384
  }
4385
+ const request = options.reveal ? { path, action: 'reveal' } : { path }
3434
4386
  try {
3435
- const result = await services.openWorkspacePath({ path })
4387
+ const result = await services.openWorkspacePath(request)
3436
4388
  if (result && result.ok === false) {
3437
4389
  const detail = result.error && (result.error.message || result.error.code)
3438
4390
  return t('error.openFailed', { error: String(detail || 'unknown') })