dsh-knit 0.17.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -47,7 +47,13 @@ window.__ModuleLoader__.load({
47
47
 
48
48
  'kind.all': '全部',
49
49
  'kind.doc': '文档',
50
- 'kind.media': '图片与视频',
50
+ // ⚠️ 2026-10-06 用户定:类型页签与「全部」分区标题都用**「媒体」**,不用「图片与视频」
51
+ // (原话:「我想修改成 媒体 或者 多媒体,你觉得呢?」→ 随后确认「媒体」)。
52
+ // 理由:① 这一档的计数本来就是「{n} 个媒体」(count.media),页签叫「图片与视频」
53
+ // 是唯一的例外;② 「多媒体」在中文 IT 语境里带 AV / 课件味,还暗示音频,而这一档
54
+ // 只扫图片与视频(宿主按扩展名放行,没有音频);③ 「媒体」省 3 个字,窄侧栏少一次
55
+ // 省略号。**含义由空态说明**(list.emptyMedia 仍写「还没有图片或视频」)。
56
+ 'kind.media': '媒体',
51
57
  'kind.title': '切换要列出的产物类型',
52
58
 
53
59
  'filter.placeholder': '过滤文档',
@@ -56,24 +62,42 @@ window.__ModuleLoader__.load({
56
62
  'usage.toggle': '使用情况',
57
63
  'usage.toggleTitle': '打开后开始统计这个会话:先看的那篇有没有被读、有多少次读落在包外、上下文换过几回。只记事实,不给分数。',
58
64
  '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
65
  'usage.note': '只统计本会话 · 数据在内核内存里,重启 DSH 就没了',
67
66
 
67
+ // ── v0.18 Context Usage Lens ────────────────────────────────
68
+ // 这一层只回答一件事:「Knit 交出去的那份 Context,被怎样消费了」。
69
+ // ⚠️ 它**不是** Dashboard:没有 KPI 大数字、没有百分比、没有评分、没有图表、
70
+ // 没有进度条、没有「使用率 / 健康度 / 认可度」。字号一律弱于文档标题 ——
71
+ // 层级只靠空间与灰阶(AGENTS.md §6.3 / §7.1)。
72
+ // ⚠️ 每一条都是**事实陈述**,不是评价:不许写成「Agent 没看这篇 / 用错了 /
73
+ // Knit 漏了 / 推荐得不准」。「最近读取」也不是「正在阅读」—— 证明不了。
74
+ 'lens.title': '使用情况',
75
+ 'lens.expand': '展开使用情况',
76
+ 'lens.collapse': '收起使用情况',
77
+ 'lens.epoch': 'Epoch {n}',
78
+ 'lens.reads': '{n} 次读取',
79
+ 'lens.outside': '{n} 篇包外',
80
+ 'lens.changes': '上下文变化 {n} 次',
81
+ 'lens.currentContext': '当前上下文',
82
+ 'lens.recentRead': '最近读取',
83
+ 'lens.recentNone': '暂无记录',
84
+ 'lens.outsideDocs': '上下文外读取',
85
+ 'lens.more': '还有 {n} 篇',
86
+ 'lens.openDoc': '打开 {rel}',
87
+ 'lens.delta': '上下文变化',
88
+ 'lens.locate': '定位到{tier}上下文',
89
+ // 读屏专用(md §六十三):**屏幕上不出现这句话**,视觉给的是「层名 + n / m + 圆点」。
90
+ 'lens.coverageAria': '{tier}上下文:{read} / {total} 篇已读',
91
+ // 上下文变化那一行的右侧说明(md §三十八「上下文变化 最近一次 ›」):
92
+ // 变化永远只说**最近一次**,所以这里不写条数(条数由展开后的行数承担)。
93
+ 'lens.deltaLatest': '最近一次',
94
+
68
95
  // ── v0.17 文档生命周期(Document Lifecycle)──────────────────
69
96
  // ⚠️ 四态全是**事实**,不是评价:「读后已更新」只说「文件在最后一次成功读取之后
70
97
  // 变过」,绝不许写成「Agent 还不知道最新版本」「Agent 用了旧版本」这类推断。
71
- // ⚠️ 「最近读取」不是「正在阅读」—— Knit 证明不了 Agent 此刻是否还在读它。
72
- // ⚠️ 「上下文外读取」只陈述「这篇不在当前包内、但被成功读过」,
73
- // 不许写成「Knit 漏了 / 推荐错了 / 命中率低」。
74
- 'usage.recentRead': '最近读取:{rel} · {time}',
75
- 'usage.outsideDocs': '上下文外读取 · {n} 篇',
76
- 'usage.deltaTitle': '上下文刚刚变化',
98
+ // ⚠️ 「上下文外读取」只陈述「这篇不在当前包内、但被成功读过」。
99
+ // ⚠️ `readCountShort` 是给行尾用的:行首的 glyph 已经说了「读过了」,
100
+ // 行尾只需要补一个「几次」—— 再说一遍「已读」是重复信息。
77
101
  'usage.deltaEnter': '进入',
78
102
  'usage.deltaLeave': '离开',
79
103
  'usage.deltaMove': '换层',
@@ -82,6 +106,7 @@ window.__ModuleLoader__.load({
82
106
  'lifecycle.unread': '未读',
83
107
  'lifecycle.read': '已读',
84
108
  'lifecycle.readCount': '已读 ×{n}',
109
+ 'lifecycle.readCountShort': '×{n}',
85
110
  'lifecycle.updatedAfterRead': '读后已更新',
86
111
  'lifecycle.rereadAfterUpdate': '修改后已重新读取',
87
112
  'tierName.primary': '主要',
@@ -216,7 +241,10 @@ window.__ModuleLoader__.load({
216
241
 
217
242
  'kind.all': 'All',
218
243
  'kind.doc': 'Docs',
219
- 'kind.media': 'Images & video',
244
+ // 2026-10-06: user picked 「媒体」 for the tab + the "All" section title, so English
245
+ // follows the same word as count.media ("{n} media"): the tab says Media, and the
246
+ // explicit "images and videos" wording stays in the empty state / README prose.
247
+ 'kind.media': 'Media',
220
248
  'kind.title': 'Switch which artifacts are listed',
221
249
 
222
250
  'filter.placeholder': 'Filter docs',
@@ -225,24 +253,37 @@ window.__ModuleLoader__.load({
225
253
  'usage.toggle': 'Usage',
226
254
  '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
255
  '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
256
  'usage.note': 'This session only · kept in kernel memory, gone after a DSH restart',
236
257
 
258
+ // ── v0.18 Context Usage Lens ───────────────────────────────
259
+ // Answers exactly one question: how was the context Knit handed over actually
260
+ // consumed. ⚠️ Not a dashboard: no KPI figures, no percentages, no scores, no
261
+ // charts, no progress bars, no "usage rate / health / confidence". Every line is
262
+ // a fact, never a judgement — and "recent read" is not "currently reading".
263
+ 'lens.title': 'Usage',
264
+ 'lens.expand': 'Expand usage',
265
+ 'lens.collapse': 'Collapse usage',
266
+ 'lens.epoch': 'Epoch {n}',
267
+ 'lens.reads': '{n} reads',
268
+ 'lens.outside': '{n} outside the pack',
269
+ 'lens.changes': 'context changed {n}×',
270
+ 'lens.currentContext': 'Current context',
271
+ 'lens.recentRead': 'Recent read',
272
+ 'lens.recentNone': 'Nothing yet',
273
+ 'lens.outsideDocs': 'Reads outside context',
274
+ 'lens.more': '{n} more',
275
+ 'lens.openDoc': 'Open {rel}',
276
+ 'lens.delta': 'Context changes',
277
+ 'lens.locate': 'Locate {tier} context',
278
+ 'lens.coverageAria': '{tier} context: {read} / {total} read',
279
+ 'lens.deltaLatest': 'Latest',
280
+
237
281
  // ── v0.17 document lifecycle ───────────────────────────────
238
282
  // ⚠️ All four states are facts, never judgements: "Updated after read" only says the
239
283
  // file changed after the last successful read. Never "the agent has not seen the
240
284
  // 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',
285
+ // ⚠️ `readCountShort` is for the row tail: the leading glyph already says it was
286
+ // read, so the tail only adds the count — repeating "read" would be redundant.
246
287
  'usage.deltaEnter': 'Entered',
247
288
  'usage.deltaLeave': 'Left',
248
289
  'usage.deltaMove': 'Moved tier',
@@ -251,6 +292,7 @@ window.__ModuleLoader__.load({
251
292
  'lifecycle.unread': 'Unread',
252
293
  'lifecycle.read': 'Read',
253
294
  'lifecycle.readCount': 'Read ×{n}',
295
+ 'lifecycle.readCountShort': '×{n}',
254
296
  'lifecycle.updatedAfterRead': 'Updated after read',
255
297
  'lifecycle.rereadAfterUpdate': 'Re-read after update',
256
298
  'tierName.primary': 'Primary',
@@ -621,53 +663,201 @@ body[data-ds-dark-theme] .knit-root{
621
663
  .knit-head .knit-root-path:disabled{cursor:default;text-decoration:none}
622
664
  .knit-count{font-size:11px;color:var(--dsw-alias-label-caption,#80868b);flex:none}
623
665
  .knit-btn{flex:none;display:inline-flex;align-items:center;justify-content:center;
624
- height:24px;padding:0 9px;border-radius:6px;cursor:pointer;
666
+ height:28px;padding:0 10px;border-radius:8px;cursor:pointer;
625
667
  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}
668
+ border:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.08));font-size:12px;
669
+ transition:background .16s ease,color .16s ease}
627
670
  .knit-btn:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));
628
671
  color:var(--dsw-alias-label-primary,#e8eaed)}
629
672
  .knit-btn.active{background:var(--knit-active-bg,rgba(255,255,255,.085));
630
673
  color:var(--dsw-alias-label-primary,#e8eaed);border-color:var(--dsw-alias-border-l4,rgba(255,255,255,.22))}
674
+ /* 排序切换与搜索框:v0.18 UI 迭代(md §四~§六)把这两个控件**按输入控件的尺度重做** ——
675
+ 圆角 10px / 字号 13px。原来那套 22px 迷你胶囊读起来像「标签」而不是控件,
676
+ 与 14px 的页签、15px 的 Usage 标题差了两档,是「审美欠缺」最直观的一处。
677
+ ⚠️ 高度:md 写 36px,2026-10-06 用户看了真机后定成 **28px**(「太高了,不需要这么高」),
678
+ 与左边的「使用情况 / 刷新」同高。
679
+ ⚠️ 描边色:用 **--dsw-alias-border-l3**,与 DSH 主区「对话」页签下面那条横线(官方
680
+ .wSkVaW_header 的 border-bottom: .5px solid rgba(0,0,0,.12) = 浅色下的 border-l3)
681
+ 同一个 token —— 2026-10-06 用户要求「描边色值改成跟那条横一样」。不用更深的 l4:
682
+ l4(浅色 rgba(0,0,0,.161))比官方分割线重一档,摆在页签下面像两个输入框框住了内容。
683
+ ⚠️ 描边粗细:**0.5px**(2026-10-06 用户第二轮要求「描边色值修改成 0.5px」)—— 官方那条
684
+ 横本身就是 .5px,色值对上而粗细仍写 1px,高分屏上比它粗一倍。三处同粗:.knit-seg
685
+ 外框、.knit-seg 内部竖线、.knit-filter。CSS 里统一写 0.5px(与官方 .wSkVaW_header 的 .5px 同值)。
686
+ ⚠️ 选中态只改**底色 + 字重 600**(不是 700),hover 只改底色 —— 不许 scale / translate /
687
+ box-shadow(md §五)。暗色下靠 --knit-active-bg 这个 token,不写死颜色。 */
631
688
  .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)}
689
+ .knit-seg{display:inline-flex;flex:none;border-radius:10px;overflow:hidden;
690
+ border:0.5px solid var(--dsw-alias-border-l3,rgba(255,255,255,.12))}
691
+ .knit-seg-btn{height:28px;padding:0 15px;cursor:pointer;font-size:13px;font-weight:400;
692
+ border:none;background:transparent;color:var(--dsw-alias-label-secondary,#9aa0a6);
693
+ transition:background .16s ease,color .16s ease}
694
+ .knit-seg-btn + .knit-seg-btn{border-left:0.5px solid var(--dsw-alias-border-l3,rgba(255,255,255,.12))}
636
695
  .knit-seg-btn:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03))}
637
696
  .knit-seg-btn.active{background:var(--knit-active-bg,rgba(255,255,255,.085));
638
697
  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;
698
+ .knit-filter{flex:1;min-width:0;height:28px;padding:0 12px;border-radius:10px;font-size:13px;
640
699
  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}
700
+ border:0.5px solid var(--dsw-alias-border-l3,rgba(255,255,255,.12));outline:none;
701
+ transition:border-color .16s ease}
642
702
  .knit-filter:focus{border-color:var(--knit-accent)}
643
703
  .knit-filter::placeholder{color:var(--dsw-alias-label-caption,#80868b)}
644
- /* v0.15「使用情况」:**一行事实**,不画卡片、不画进度条、不用品牌色。
645
- 它占的就是原来「相关性排序」那一行的位置 —— 2026-09-30 用户裁决那一行
646
- 整个删掉(排序方式由「相关 / 最新」那个切换按钮自己表达,再说一遍是重复),
647
- 所以它现在是头部下面唯一的一行弱化文字,不是一块新面板。
704
+ /* v0.15「使用情况」→ v0.18「Context Usage Lens」:**列表上方的一块轻量观察层**。
705
+ 不是弹窗、不是新页面、不是 Dashboard、不画卡片、不画进度条、不用品牌色。
706
+ 它占的是原来「相关性排序」那一行的位置 —— 2026-09-30 用户裁决那一行整个删掉
707
+ (排序方式由「相关 / 最新」那个切换按钮自己表达,再说一遍是重复),
708
+ 于是它是类型页签下面、列表上面唯一的一块弱化信息,不是一块新面板。
648
709
  ⚠️ 全宽横线一律不画: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}
710
+ 「页面上横线一多,读起来就像文件管理表格」。层级由空间与字号建立。
711
+ ⚠️ 它**自己不滚动**:滚动统一交给 .knit-list —— 窄侧栏里滚轮套滚轮很难用。
712
+ ⚠️ 这一条不许加 background / width / 品牌色(有守卫盯着,见 client.test.mjs)。 */
713
+ .knit-usage{flex:none;padding:12px 12px 10px;font-size:12px;line-height:1.5;
714
+ color:var(--dsw-alias-label-caption,#80868b)}
715
+ /* Lens 标题行:整行可点,展开 / 收起。**「使用情况」开关管统计开不开,
716
+ 这一行管「统计开着但看不看细节」—— 两件事**(2026-10-05 规格 §25)。
717
+ v0.18 UI 迭代(2026-10-06,依 '02_方案与 Demo/dsh-knit V0.18 UI 重构开发提示词.md'
718
+ §七 / §四十七 的尺度表):标题 15px/600(它是这一块的**标题**,不是元信息)、
719
+ Epoch 12px 弱化靠右、**不做成 Badge**(不画底、不画边)。 */
720
+ .knit-lens-head{display:flex;align-items:baseline;gap:8px;width:100%;appearance:none;
721
+ border:0;background:none;margin:0;padding:0;font:inherit;cursor:pointer;text-align:left;
722
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
723
+ .knit-lens-head:hover{color:var(--dsw-alias-label-primary,#e8eaed)}
724
+ .knit-lens-head:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
725
+ .knit-lens-title{flex:none;font-size:15px;font-weight:600;line-height:20px;
726
+ color:var(--dsw-alias-label-primary,#e8eaed)}
727
+ .knit-lens-epoch{flex:none;margin-left:auto;font-size:12px;font-weight:400;line-height:20px;
728
+ color:var(--dsw-alias-label-caption,#80868b)}
729
+ /* 摘要行:三件事实,一行。放不下就省略号 —— 绝不换行把列表顶下去。
730
+ 12px/18px、与标题 4~6px(md §九 / §十)。 */
731
+ .knit-lens-sum{overflow:hidden;text-overflow:ellipsis;white-space:nowrap;
732
+ margin-top:5px;font-size:12px;line-height:18px}
733
+ .knit-lens-sec{margin-top:13px}
734
+ .knit-lens-name{margin-bottom:6px;font-size:12px;font-weight:500;
735
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
736
+ /* 「当前上下文」这一句是**分节标题**(比层名与行标签高一档,md §十三:13px/500);
737
+ 距摘要行 12~14px 由 .knit-lens-sec 的 margin-top 给。 */
738
+ .knit-lens-cap{margin-bottom:6px;font-size:13px;font-weight:500;
739
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
740
+ /* 当前上下文 Coverage:三层各「层名 + 已读 ÷ 总数 + 状态点」。
741
+ v0.18 UI 迭代(md §十二~§十九):三层用 '1fr 1.2fr 1.8fr' 的**网格**(Related 通常
742
+ 最多),层名与 'n / m' 落在**同一行**(数值右对齐),状态点是**真的 9px 圆点** ——
743
+ 不再是 '○ ●' 字符:字符圆点在不同字体 / 字号下大小不一,正是「不像设计稿」的那一处。
744
+ ⚠️ 不是三张 Card:默认不画底、不画边,只有 hover 时一层很淡的底(md §十三 / §五十一)。
745
+ ⚠️ 分母是这一层当前真实几篇:Primary 不存在时整列不显示(不画 0 / 0 的假层)。 */
746
+ .knit-cov{display:grid;grid-template-columns:minmax(0,1fr) minmax(0,1.2fr) minmax(0,1.8fr);
747
+ column-gap:14px;align-items:start;margin:0 -8px}
748
+ .knit-cov-col{display:grid;grid-template-columns:1fr auto;column-gap:8px;row-gap:7px;
749
+ align-items:center;appearance:none;border:0;margin:0;padding:6px 8px;
750
+ background:transparent;font:inherit;cursor:pointer;text-align:left;border-radius:10px;
751
+ color:var(--dsw-alias-label-caption,#80868b);transition:background .16s ease}
752
+ .knit-cov-col:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03))}
753
+ .knit-cov-col:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
754
+ .knit-cov-name{grid-column:1;min-width:0;overflow:hidden;text-overflow:ellipsis;
755
+ white-space:nowrap;font-size:12px;font-weight:500;
756
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
757
+ /* 状态点:**真 CSS 圆** —— 未读=空心环(1px 中性边)、已读=中性填充;'○→●' 只做
758
+ background / border-color 两笔 220ms 过渡,不弹跳、不闪烁。
759
+ ⚠️ 轮询不动数据就不动 className,于是补间不会被重播。
760
+ ⚠️ 只用中性 token:没有绿 / 红 / 黄 / 蓝 —— 读没读过不是「好 / 坏」(PRD §7.3)。
761
+ ⚠️ 与文档行里的 .knit-glyph-mark **同一对 token、同一个直径**:md §二十九 要求
762
+ 生命周期那枚空心圆与这里的空心圆「视觉完全一致」。 */
763
+ .knit-cov-dots{grid-column:1 / -1;display:flex;flex-wrap:wrap;gap:6px;row-gap:5px;
764
+ min-height:6px;align-items:center}
765
+ /* ⚠️ 圆点直径 6px(2026-10-06 用户定:「9px 真圆请改成 6px」)。
766
+ Coverage 与文档行的 glyph 必须**同一个直径、同一对 token**(守卫会比对两处)。 */
767
+ .knit-cov-dot{flex:none;display:block;width:6px;height:6px;border-radius:50%;
768
+ border:1px solid var(--dsw-alias-label-caption,#80868b);background:transparent;
769
+ transition:background .22s ease,border-color .22s ease}
770
+ .knit-cov-dot.on{background:var(--dsw-alias-label-caption,#80868b);
771
+ border-color:var(--dsw-alias-label-caption,#80868b)}
772
+ .knit-cov-num{grid-column:2;text-align:right;font-size:11px;font-weight:400;
773
+ font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-caption,#80868b)}
774
+ /* 最近读取:**可点的一行**(文件名 · 相对时间 ›)。整行可点、hover 只改底色。
775
+ v0.18 UI 迭代(md §二十一 / §二十二):高 38px、左右 10px、圆角 8px、
776
+ 文件 12px、时间 11px、箭头 16px。
777
+ ⚠️ 语义仍是「最近一次成功 read」:文案不许写成「当前正在阅读」。 */
778
+ .knit-read-row{display:flex;align-items:center;gap:10px;width:100%;appearance:none;
779
+ border:0;background:none;margin:0;padding:0 10px;height:38px;border-radius:8px;font:inherit;
780
+ text-align:left;cursor:pointer;color:var(--dsw-alias-label-primary,#e8eaed);
781
+ transition:background .16s ease}
782
+ .knit-read-row:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03))}
783
+ .knit-read-row:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
784
+ .knit-read-rel{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;
785
+ white-space:nowrap;font-size:12px}
786
+ .knit-read-time{flex:none;font-size:11px;color:var(--dsw-alias-label-caption,#80868b)}
787
+ .knit-read-go{flex:none;font-size:16px;line-height:1;
788
+ color:var(--dsw-alias-label-caption,#80868b)}
789
+ .knit-lens-empty{opacity:.75}
790
+ /* 包外读取:每一行都是**可点对象**(点开预览),但不许加入 Context ——
791
+ V0.18 不做 Context Control,这里是「看一眼」,不是「改上下文」。
792
+ v0.18 UI 迭代(md §三十四~§三十七):展开后逐行
793
+ '01 docs/… ×3 已读'(序号 + 路径 + 次数 + 状态),11px、行内不画线。 */
794
+ .knit-out-row{display:flex;align-items:center;gap:9px;width:100%;appearance:none;
795
+ border:0;background:none;margin:0;padding:5px 9px 5px 17px;border-radius:8px;font:inherit;
796
+ text-align:left;cursor:pointer;color:var(--dsw-alias-label-caption,#80868b);
797
+ transition:background .16s ease}
798
+ .knit-out-row:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));
799
+ color:var(--dsw-alias-label-primary,#e8eaed)}
800
+ .knit-out-row:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
801
+ .knit-out-num{flex:none;width:18px;text-align:right;font-size:11px;
802
+ font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-caption,#80868b);opacity:.75}
803
+ .knit-out-rel{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;
804
+ white-space:nowrap;font-size:11px}
805
+ .knit-out-count{flex:none;font-size:11px;font-variant-numeric:tabular-nums}
806
+ /* 行内生命周期 glyph(v0.17 起):**极小、中性、不抢标题**。点它 = 打开 / 选中这篇。
807
+ v0.18 UI 迭代(md §二十七~§二十九):四态改成与 Coverage **同一套**圆点语言 ——
808
+ 未读=空心环、已读=实心、读后已更新=空心环 + 中心点、修改后已重新读取= ↻ 字符。
809
+ 两者用同一对 token、同一个 9px 直径,所以「同一套状态语言」不靠自觉。
810
+ ⚠️ 类名不能叫 knit-life-*:byClass 是子串匹配,会和 .knit-life 撞。 */
811
+ .knit-glyph{flex:none;display:inline-flex;align-items:center;justify-content:center;
812
+ appearance:none;border:0;background:none;margin:0;padding:0;width:14px;height:18px;
813
+ cursor:pointer;color:var(--dsw-alias-label-caption,#80868b)}
814
+ .knit-glyph:hover{color:var(--dsw-alias-label-primary,#e8eaed)}
815
+ .knit-glyph:focus-visible{outline:1px solid var(--knit-accent);outline-offset:1px}
816
+ .knit-glyph-mark{flex:none;display:block;width:6px;height:6px;border-radius:50%;
817
+ border:1px solid var(--dsw-alias-label-caption,#80868b);background:transparent;
818
+ transition:background .22s ease,border-color .22s ease}
819
+ .knit-glyph-mark[data-mark="read"]{background:var(--dsw-alias-label-caption,#80868b)}
820
+ .knit-glyph-mark[data-mark="updated"]{position:relative}
821
+ .knit-glyph-mark[data-mark="updated"]::after{content:'';position:absolute;inset:1.5px;
822
+ border-radius:50%;background:var(--dsw-alias-label-caption,#80868b)}
823
+ .knit-glyph-mark[data-mark="reread"]{width:9px;height:9px;border:0;background:transparent;
824
+ font-size:9px;line-height:9px;text-align:center}
825
+ /* Coverage 点某一层 → 那一层**短暂高亮**(空间定位,不画横线、不加箭头)。
826
+ 1200ms 轻微背景(md §十七原写 500~700ms,2026-10-06 用户看真机后定成 1200ms),
827
+ 不许闪红、不许位移。CSS transition 的时长必须与 FLASH_MS 一致,否则会出现「已经取消高亮
828
+ 但背景还在慢慢褪」的错帧。 */
829
+ .knit-tier{transition:background 1.2s ease}
830
+ .knit-tier.flash{background:var(--knit-hover-bg,rgba(255,255,255,.03));border-radius:10px}
653
831
 
654
832
  /* v0.17 文档生命周期(Document Lifecycle)—— 三条新信息,都只是**事实**。
655
833
  ⚠️ 状态是文字,不是徽章:不加底色、不加边框、不用红绿 —— 红绿会把「事实」读成
656
- 「好 / 坏」(PRD §7.3)。字号 10.5px,比 14px 的标题弱一档,永远不抢标题。
834
+ 「好 / 坏」(PRD §7.3)。永远不抢标题(标题 14px)。
835
+ v0.18 UI 迭代:10.5px → **11px** —— md §四十七 的尺度表里最小一档就是 11px。
657
836
  ⚠️ 折叠块沿用 .knit-usage 的弱化灰阶:它们是同一行事实的展开,不是新卡片。
658
837
  ⚠️ 这一段**不含反引号**,整段可以直接放在 CSS 模板串里。 */
659
- .knit-life{flex:none;font-size:10.5px;line-height:1.4;white-space:nowrap;
838
+ .knit-life{flex:none;font-size:11px;line-height:1.4;white-space:nowrap;
660
839
  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)}
840
+ .knit-usage-more{margin-top:10px}
841
+ /* 菜单式展开行(包外读取 / 上下文变化):整行可点、高 38px、圆角 8px、hover 只改底色;
842
+ 左边是标题,右边是「数量 / 最近一次 + ›」,展开后箭头换成 ⌃(md §三十四 / §三十八)。 */
843
+ .knit-more-btn{display:flex;align-items:center;gap:10px;width:100%;
844
+ appearance:none;border:0;background:none;margin:0;padding:0 10px;height:38px;
845
+ border-radius:8px;font:inherit;font-size:12px;line-height:1;cursor:pointer;text-align:left;
846
+ color:var(--dsw-alias-label-secondary,#9aa0a6);transition:background .16s ease}
847
+ .knit-more-btn:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));
848
+ color:var(--dsw-alias-label-primary,#e8eaed)}
665
849
  .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;
850
+ .knit-more-label{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;
851
+ white-space:nowrap}
852
+ .knit-more-meta{flex:none;font-size:11px;font-variant-numeric:tabular-nums;
853
+ color:var(--dsw-alias-label-caption,#80868b)}
854
+ .knit-gap-row,.knit-delta-row{display:flex;gap:9px;align-items:baseline;
855
+ padding:3px 9px 3px 17px;font-size:11px;
667
856
  color:var(--dsw-alias-label-caption,#80868b)}
668
857
  .knit-gap-rel,.knit-delta-rel{flex:1 1 auto;min-width:0;overflow:hidden;
669
858
  text-overflow:ellipsis;white-space:nowrap}
670
- .knit-delta-head{margin-top:3px;color:var(--dsw-alias-label-secondary,#9aa0a6)}
859
+ .knit-delta-head{margin-top:8px;padding:0 9px 0 17px;font-size:11px;font-weight:500;
860
+ color:var(--dsw-alias-label-secondary,#9aa0a6)}
671
861
 
672
862
 
673
863
  /* ── v0.14 右栏(Context Pack 面板)已整体删除(2026-09-29)────────
@@ -703,7 +893,7 @@ body[data-ds-dark-theme] .knit-root{
703
893
  .knit-tierhint{font-weight:400}
704
894
  /* 「为什么在这里」:比摘要更弱的一行,只在 Context Pack 的条目上出现。
705
895
  11px 而不是 10px,因为它承担的是**信息**(可核验的理由),不是装饰标注。 */
706
- .knit-why{padding-top:2px;font-size:11px;line-height:1.5;color:var(--dsw-alias-text-tertiary)}
896
+ .knit-why{padding-top:2px;font-size:11px;line-height:17px;color:var(--dsw-alias-text-tertiary)}
707
897
  /* 滚动条**不要自己画**:DSH 主题里已有全局样式
708
898
  (::-webkit-scrollbar 宽 8px + --dsh-scrollbar-thumb,见 dsh-client-ui-theme)。
709
899
  曾经在这里写死 6px 宽 + rgba(255,255,255,.14) 的滑块 —— 白色 14% 在白底上完全隐形,
@@ -760,6 +950,9 @@ body[data-ds-dark-theme] .knit-root{
760
950
  .knit-doc.leaving{pointer-events:none;user-select:none;overflow:hidden}
761
951
  @media (prefers-reduced-motion: reduce){
762
952
  .knit-doc{transition:none}
953
+ .knit-cov-dots,.knit-cov-dot{transition:none}
954
+ .knit-tier,.knit-tier.flash{transition:none}
955
+ .knit-cov-col,.knit-read-row,.knit-out-row,.knit-more-btn,.knit-glyph-mark{transition:none}
763
956
  }
764
957
  /* 行一=**标题行**:Primary 点 + 标题 + 相对时间(**时间靠右**)。
765
958
  2026-09-29 这一天里这一行改了三次:先是「序号 + 标题 + 时间」,然后
@@ -780,7 +973,7 @@ body[data-ds-dark-theme] .knit-root{
780
973
  它=.knit-title 的 14px × 1.4。格的 align-items:start 让这一列从卡片顶边
781
974
  开始排,所以只要这个行盒与标题行盒等高,两个字号不同的文本就自然居中。
782
975
  **改 .knit-title 的字号或行高时,这里必须同步改**,否则序号会与标题错开。 */
783
- .knit-num,.knit-gapmark{grid-column:1;font-size:10.5px;line-height:19.6px;font-variant-numeric:tabular-nums;
976
+ .knit-num,.knit-gapmark{grid-column:1;font-size:11px;line-height:19.6px;font-variant-numeric:tabular-nums;
784
977
  color:var(--dsw-alias-label-caption,#80868b)}
785
978
  /* 中性占位标记(2026-10-01 用户反馈):「其他相关文档」那一节没有序号,空着的那一格
786
979
  被读成「漏了一个号」(原话:「没有序号以后左边就空了,视觉上比较割裂,就觉得是个 bug 一样」)。
@@ -798,7 +991,7 @@ body[data-ds-dark-theme] .knit-root{
798
991
  ⚠️ 这条推翻了同一天早先的写法(那时候时间跟在点后面左对齐,理由是
799
992
  「元信息行读起来像一句话」)—— 时间现在和标题同一行,左对齐会把标题夹在中间。
800
993
  靠 .knit-title 的 flex:1 1 auto 把时间挤到行尾;这里只要 flex:none 不被压扁。 */
801
- .knit-time{flex:none;font-size:10.5px;color:var(--dsw-alias-label-caption,#80868b)}
994
+ .knit-time{flex:none;font-size:11px;color:var(--dsw-alias-label-caption,#80868b)}
802
995
  /* 标题现在和 Primary 点、时间**同行**(见 .knit-row1 的说明;margin-bottom 移到了那一行)。
803
996
  仍是单行省略 —— 列表是扫读用的,想看全标题就预览或打开;折行会让每条卡高度不一,
804
997
  「移动到下一项」的位移就没法预期。
@@ -806,7 +999,7 @@ body[data-ds-dark-theme] .knit-root{
806
999
  去掉 min-width:0,标题会把整行撑宽(省略号失效);去掉 flex-grow,时间会紧贴标题而不是靠右。 */
807
1000
  .knit-title{flex:1 1 auto;min-width:0;font-weight:600;font-size:14px;line-height:1.4;
808
1001
  overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
809
- .knit-sum{font-size:12px;line-height:19px;color:var(--dsw-alias-label-secondary,#9aa0a6);
1002
+ .knit-sum{font-size:12px;line-height:18px;color:var(--dsw-alias-label-secondary,#9aa0a6);
810
1003
  display:-webkit-box;-webkit-line-clamp:2;-webkit-box-orient:vertical;overflow:hidden}
811
1004
  .knit-sum.empty{font-style:italic;color:var(--dsw-alias-label-caption,#80868b)}
812
1005
  /* ── 列表行里为什么没有路径(2026-09-29) ────────────────────
@@ -934,9 +1127,9 @@ body[data-ds-dark-theme] .knit-preview{box-shadow:0 -8px 24px rgba(0,0,0,.38)}
934
1127
  2px 下划线表达,页签条本身不画线(也不是「下划线悬空」:它画在自己的文字下面)。
935
1128
  ⚠️ 排序切换(.knit-seg-btn,Design §18)是**另一个控件**,它保持灰底不变。 */
936
1129
  .knit-types{display:flex;gap:14px;padding:0 12px;flex:none}
937
- .knit-type-btn{flex:none;height:28px;padding:0;cursor:pointer;
1130
+ .knit-type-btn{flex:none;height:30px;padding:0;cursor:pointer;
938
1131
  border:none;border-bottom:2px solid transparent;background:transparent;
939
- color:var(--dsw-alias-label-secondary,#9aa0a6);font-family:inherit;font-size:11.5px;
1132
+ color:var(--dsw-alias-label-secondary,#9aa0a6);font-family:inherit;font-size:14px;
940
1133
  white-space:nowrap;overflow:hidden;text-overflow:ellipsis;
941
1134
  transition:color .15s,border-color .15s}
942
1135
  .knit-type-btn:hover{color:var(--dsw-alias-label-primary,#e8eaed)}
@@ -1420,6 +1613,106 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1420
1613
  return `knit-opt-${safe}-${(hash >>> 0).toString(36)}`
1421
1614
  }
1422
1615
 
1616
+ /* ── v0.18 Context Usage Lens 的纯函数 ────────────────────────────
1617
+ 这一层只把**已经有的事实**重新组织一遍:不新增采集、不新增存储、不新增事件、
1618
+ 不新增第二个生命周期口径。「能派生就不要存储」—— Coverage 是拿当前 Context
1619
+ Pack 的三层 rels 加上 `usage.lifecycle` **现算**出来的,没有任何一份自己的 state。
1620
+ ⚠️ 全部是纯函数(不吃 React、不读 DOM),所以测试可以直接对拍。
1621
+ ⚠️ 这一段**不含反引号**,整段可以直接放进 CSS/代码模板串里。 */
1622
+
1623
+ /** 生命周期四态的 glyph。**不是颜色、不是徽章** —— 它只是一枚字符。
1624
+ * ⚠️ 四态一律中性:不许「绿=已读 / 红=未读 / 黄=更新」——
1625
+ * 生命周期是**事实**,不是风险等级(PRD §7.3)。 */
1626
+ const LIFE_GLYPH = {
1627
+ unread: '○',
1628
+ read: '●',
1629
+ updated_after_read: '△',
1630
+ reread_after_update: '↻',
1631
+ }
1632
+
1633
+ /** 某篇的读取状态:**没有记录就是未读**(这是事实,不是猜测)。
1634
+ * 认不出的状态一律退回 `unread` —— 宿主加了新状态时,界面显示「未读」而不是空白。 */
1635
+ function lifeStatusOf(lifecycle, rel) {
1636
+ const row = lifecycle && typeof lifecycle === 'object' ? lifecycle[rel] : null
1637
+ const status = row && typeof row.status === 'string' ? row.status : 'unread'
1638
+ return LIFE_GLYPH[status] ? status : 'unread'
1639
+ }
1640
+
1641
+ /** Coverage:三层各自的 `{ total, read, rels }`。
1642
+ * `tierRels` = `{ primary: [...rel], supporting: [...], related: [...] }`;
1643
+ * `rels` 里每一项带 `read` 布尔(状态点要用它)。
1644
+ * ⚠️ 分母是**这一层当前真实有几篇**,不是 Context Pack 的 `matched/total`;
1645
+ * 所以 Primary 不存在时是 `{ total: 0, read: 0, rels: [] }`,面板显示 `0 / 0`
1646
+ * —— Knit 不能假设每一份上下文都有 Primary。 */
1647
+ function coverageOf(tierRels, lifecycle) {
1648
+ const out = {}
1649
+ for (const key of ['primary', 'supporting', 'related']) {
1650
+ const list = tierRels && Array.isArray(tierRels[key]) ? tierRels[key] : []
1651
+ const rels = []
1652
+ let read = 0
1653
+ for (const item of list) {
1654
+ const rel = typeof item === 'string' ? item : (item && item.rel)
1655
+ if (!rel) continue
1656
+ const isRead = lifeStatusOf(lifecycle, rel) !== 'unread'
1657
+ if (isRead) read += 1
1658
+ rels.push({ rel, read: isRead })
1659
+ }
1660
+ out[key] = { total: rels.length, read, rels }
1661
+ }
1662
+ return out
1663
+ }
1664
+
1665
+ /** 包外读取的**事实排序**:读得最多的在前,同次数按**最后读**的先后。
1666
+ * ⚠️ 宿主回的是**首次读的顺序**(`seq` = firstRead.seq,阅读顺序);面板要回答的是
1667
+ * 「哪几篇被反复读」—— 两件事,所以在客户端重排,不动宿主。
1668
+ * ⚠️ 载荷里没有 `lastRead.seq`(只有首次读的 `seq` 与 `lastReadAt`),
1669
+ * 于是同计数时按 `lastReadAt` 降序 —— 它对应的就是规格里的「最后读的那一次更靠前」。 */
1670
+ function groupOutsideDocs(outsideDocs) {
1671
+ const list = Array.isArray(outsideDocs) ? outsideDocs.slice() : []
1672
+ return list.sort((a, b) => {
1673
+ const ca = Number(a && a.count) || 0
1674
+ const cb = Number(b && b.count) || 0
1675
+ if (cb !== ca) return cb - ca
1676
+ const ta = Number(a && a.lastReadAt) || 0
1677
+ const tb = Number(b && b.lastReadAt) || 0
1678
+ if (tb !== ta) return tb - ta
1679
+ const sa = Number(a && a.seq) || 0
1680
+ const sb = Number(b && b.seq) || 0
1681
+ if (sb !== sa) return sb - sa
1682
+ return String((a && a.rel) || '').localeCompare(String((b && b.rel) || ''))
1683
+ })
1684
+ }
1685
+
1686
+ /** 最近一次 Context Delta 按「进 / 出 / 换层」拆开(只拆,不排序、不丢弃)。
1687
+ * ⚠️ v0.15 那种把 `appeared` 写成**字符串数组**的旧载荷也认 ——
1688
+ * 客户端不能因为宿主版本不同就崩。 */
1689
+ function groupDelta(delta) {
1690
+ const out = { enter: [], leave: [], move: [] }
1691
+ if (!delta) return out
1692
+ const push = (target, item) => {
1693
+ const rel = typeof item === 'string' ? item : (item && item.rel)
1694
+ if (!rel) return
1695
+ target.push(typeof item === 'string' ? { rel } : item)
1696
+ }
1697
+ for (const item of Array.isArray(delta.appeared) ? delta.appeared : []) push(out.enter, item)
1698
+ for (const item of Array.isArray(delta.disappeared) ? delta.disappeared : []) push(out.leave, item)
1699
+ for (const item of Array.isArray(delta.moved) ? delta.moved : []) push(out.move, item)
1700
+ return out
1701
+ }
1702
+
1703
+ /** 面板矮到这个高度以下就进「小高度」档:只留 Summary / Coverage / Recent Read,
1704
+ * Outside / Delta 收成标题(点开照常能用)。⚠️ 不是「藏起来」,是「别先占高度」。 */
1705
+ const COMPACT_PANEL_PX = 420
1706
+ /** 包外读取默认最多铺几行,其余折成「还有 N 篇」。 */
1707
+ const MAX_OUTSIDE_SHOWN = 10
1708
+ /** 上下文变化:收起时最多 3 条,展开后每个分类最多 5 条(v0.17 规则,保持不变)。 */
1709
+ const MAX_DELTA_SHOWN = 3
1710
+ const MAX_DELTA_GROUP = 5
1711
+ /** 点 Coverage 之后那一层高亮多久(毫秒)。只是「我把你送到这儿了」的一下提示。
1712
+ * v0.18 UI 迭代(md §十七):原写 500~700ms、取 650;2026-10-06 用户看真机后定成 **1200**,
1713
+ * 「停留久一点才看得清是哪一层」。CSS 里 `.knit-tier{transition:background 1.2s}` 必须同步。 */
1714
+ const FLASH_MS = 1200
1715
+
1423
1716
  /* ── 列表进出动效(v0.17)─────────────────────────────────────────
1424
1717
  用户原话(2026-10-03):「文档列表,新读取跟挤掉旧的未读的,这里的交互可能要优化,
1425
1718
  因为现在是一闪一闪的,就非常的快……如果说从当前的,如辅助上下文中新增,它应该是
@@ -1632,7 +1925,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1632
1925
  }
1633
1926
 
1634
1927
  function DocRow({ doc, now, active, cursor, relevance, why, num, mark, primary, life,
1635
- onSelect, onOpenTab, optionId, entering, leaving }) {
1928
+ glyph, onGlyph, onSelect, onOpenTab, optionId, entering, leaving }) {
1636
1929
  const fresh = now - doc.mtimeMs < NEW_WINDOW_MS
1637
1930
  const rowRef = React.useRef(null)
1638
1931
 
@@ -1711,7 +2004,34 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1711
2004
  h('div', { className: 'knit-row1' },
1712
2005
  // v0.14(Design §13):Primary 唯一允许的标记 —— 5px 黑点。
1713
2006
  // 不是星标、不是徽章、不是 AI 图标:「重要来自位置和结构,不来自图标」。
1714
- primary ? h('span', { className: 'knit-dot', 'aria-hidden': 'true' }) : null,
2007
+ // v0.18:**统计开着时这一格让给生命周期 glyph**(○ ● △ ↻)——
2008
+ // 2026-10-05 规格 §13 给的 ASCII 每一行只有一个标记,而层名已经由分组标题
2009
+ // (「主要上下文」)说了,glyph 才是这一版新加的那条事实。usage 关掉时
2010
+ // 这一行与 v0.17 逐字一致(`knit-dot` 照旧)。
2011
+ primary && !glyph ? h('span', { className: 'knit-dot', 'aria-hidden': 'true' }) : null,
2012
+ // 生命周期 glyph:极小、中性、点它=打开 / 选中这篇(**已经打开则保持原预览**)。
2013
+ // ⚠️ 它是真 `button`:键盘 Tab 得到、读屏读得出,不是 div + onClick。
2014
+ glyph ? h('button', {
2015
+ className: 'knit-glyph',
2016
+ type: 'button',
2017
+ title: glyph.title,
2018
+ 'aria-label': glyph.title,
2019
+ onClick: (event) => {
2020
+ if (event && typeof event.stopPropagation === 'function') event.stopPropagation()
2021
+ onGlyph(doc)
2022
+ },
2023
+ },
2024
+ // v0.18 UI 迭代(md §二十七~§二十九):四态画成与 Coverage **同一套** 9px 圆点 ——
2025
+ // 未读=空心环、已读=实心、读后已更新=空心环 + 中心点、修改后已重新读取= ↻ 字符。
2026
+ // 两处用同一对 token、同一个直径,所以「同一套状态语言」不靠自觉。
2027
+ // ⚠️ 状态词仍然只在 title / aria-label 里;行尾那一段文字由 `.knit-life` 说。
2028
+ h('span', {
2029
+ className: 'knit-glyph-mark',
2030
+ 'data-mark': glyph.status === 'read' ? 'read'
2031
+ : glyph.status === 'updated_after_read' ? 'updated'
2032
+ : glyph.status === 'reread_after_update' ? 'reread' : 'unread',
2033
+ 'aria-hidden': 'true',
2034
+ }, glyph.status === 'reread_after_update' ? glyph.char : null)) : null,
1715
2035
  h('div', { className: 'knit-title' },
1716
2036
  fresh ? h('span', { className: 'knit-badge' }, '🆕') : null,
1717
2037
  doc.title || doc.name),
@@ -2168,8 +2488,12 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2168
2488
  * @returns {Array} 节点数组
2169
2489
  */
2170
2490
  const contextBody = (view) => view.sections.map((section) => h('div', {
2171
- className: 'knit-tier',
2491
+ // 点 Coverage 定位过来时,这一层短暂亮一下(`flashTier`,900ms 后自己收掉)。
2492
+ // 不画箭头、不画横线 —— 用**空间**说「就是这里」。
2493
+ className: `knit-tier${flashTier === section.key ? ' flash' : ''}`,
2172
2494
  key: section.key,
2495
+ // Coverage 的定位锚点:点某一层 → `[data-knit-tier=...]` 滚进视口。
2496
+ 'data-knit-tier': section.key,
2173
2497
  role: 'presentation',
2174
2498
  },
2175
2499
  // ⚠️ 这几个类名**互不为子串**:`byClass` 是子串匹配,若叫
@@ -2547,22 +2871,58 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2547
2871
  * 不是「你漏了它」的提醒,更不许写成「Agent 忽略了它」(PRD §8)。
2548
2872
  * ⚠️ 状态值本身是英文(数据层只有一个口径),中文只存在于词典(§15.4 / §24)。
2549
2873
  *
2874
+ /**
2875
+ * v0.17 → v0.18:生命周期现在是**一枚 glyph + 一段极短的文字**。
2876
+ * `○ 未读` / `● 已读 ×n` / `△ 读后已更新` / `↻ 修改后已重新读取`。
2877
+ *
2878
+ * ⚠️ tooltip 与 `aria-label` 挂在 **glyph** 上:`.knit-life` 只许有一个 `className`
2879
+ * prop(client.test.mjs 有守卫盯着)—— 状态是文字,不是可交互控件。
2880
+ * ⚠️ 没有记录就是「未读」:这是**事实**,不是猜测。
2881
+ *
2550
2882
  * @param {string} rel - 相对路径
2551
- * @returns {string|null} 状态文案
2883
+ * @returns {{status:string,char:string,text:string,title:string}|null}
2552
2884
  */
2553
- const lifecycleLabel = (rel) => {
2885
+ const lifeInfo = (rel) => {
2554
2886
  if (!usageOn) return null
2555
2887
  const usageNow = state.usage
2556
2888
  if (!usageNow || !usageNow.stats) return null
2557
2889
  const row = usageNow.lifecycle && usageNow.lifecycle[rel]
2558
- const status = row ? row.status : 'unread'
2559
- if (status === 'unread') return t('lifecycle.unread')
2890
+ const status = row && row.status ? row.status : 'unread'
2891
+ const char = LIFE_GLYPH[status] || LIFE_GLYPH.unread
2892
+ const count = row && Number.isFinite(row.count) ? row.count : 0
2893
+ if (status === 'updated_after_read') {
2894
+ return { status, char, text: t('lifecycle.updatedAfterRead'),
2895
+ title: t('lifecycle.updatedAfterRead') }
2896
+ }
2897
+ if (status === 'reread_after_update') {
2898
+ return { status, char, text: t('lifecycle.rereadAfterUpdate'),
2899
+ title: t('lifecycle.rereadAfterUpdate') }
2900
+ }
2560
2901
  if (status === 'read') {
2561
- return row && row.count >= 2 ? t('lifecycle.readCount', { n: row.count }) : t('lifecycle.read')
2902
+ // 读了几次只说次数:`×3`。**不排序、不评分、不建议**。
2903
+ return { status, char, text: t('lifecycle.readCountShort', { n: count }),
2904
+ title: t('lifecycle.readCount', { n: count }) }
2562
2905
  }
2563
- if (status === 'updated_after_read') return t('lifecycle.updatedAfterRead')
2564
- if (status === 'reread_after_update') return t('lifecycle.rereadAfterUpdate')
2565
- return null
2906
+ return { status: 'unread', char: LIFE_GLYPH.unread,
2907
+ text: t('lifecycle.unread'), title: t('lifecycle.unread') }
2908
+ }
2909
+
2910
+ /** 只有文字的那一半(行尾 `.knit-life`);没有证据时 null,一个节点都不加。 */
2911
+ const lifecycleLabel = (rel) => {
2912
+ const info = lifeInfo(rel)
2913
+ return info ? info.text : null
2914
+ }
2915
+
2916
+ /**
2917
+ * 状态词(**不带次数**)—— 给「次数已经在同一行单独显示」的地方用。
2918
+ * 包外行左边已经有一个 `×N`(它同时是这一档的排序键),再让 lifecycle 说一遍 `×N`
2919
+ * 就会渲染成 `client.js ×71 ×71`(2026-10-05 用真实载荷渲染时抓到)。
2920
+ * `read` 换成短词「已读」;其余三态本来就是词,照旧。
2921
+ */
2922
+ const lifeWord = (rel) => {
2923
+ const info = lifeInfo(rel)
2924
+ if (!info) return null
2925
+ return info.status === 'read' ? t('lifecycle.read') : info.text
2566
2926
  }
2567
2927
 
2568
2928
  /* ── 列表进出动效:这一帧谁新来了、谁走了 ─────────────────────────
@@ -2581,6 +2941,63 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2581
2941
  tweenUntil: 0,
2582
2942
  })
2583
2943
  const [, setMotionSeq] = React.useState(0)
2944
+
2945
+ /* ── v0.18 Usage Lens:三个新状态 + 两个新 effect ────────────────
2946
+ ⚠️ 这些 hook 必须留在**本组件最后一个 hook 之后**:假 React(test/harness.mjs)
2947
+ 按调用顺序分配槽位,`harness.seed()` 又按顺序预置 —— 插在中间会让所有老用例错位。 */
2948
+
2949
+ /** Lens 的展开 / 收起。它与「使用情况」开关是**两个状态**(规格 §25):
2950
+ * 开关管「统计开不开」,这一位只管「统计开着,但暂时不想看细节」。默认展开。 */
2951
+ const [lensOpen, setLensOpen] = React.useState(true)
2952
+ /** 正在短暂高亮的那一层(点 Coverage 定位用);空串=没有高亮。 */
2953
+ const [flashTier, setFlashTier] = React.useState('')
2954
+ /** 面板高度(px)。0 = 量不到(测试替身 / 首帧)——那时按「不矮」处理,不降级。 */
2955
+ const [panelH, setPanelH] = React.useState(0)
2956
+
2957
+ /** 点 Coverage 的某一层 → 滚到那一层 + 短暂高亮。
2958
+ * ⚠️ 滚的是 `.knit-list`(唯一滚动容器):Lens 自己不滚动,也不新增容器。
2959
+ * ⚠️ 高亮走 state 而不是直接改 classList —— 这样测试替身里也能断言到结果。 */
2960
+ const locateTier = (key) => {
2961
+ setFlashTier(key)
2962
+ const host = listRef.current
2963
+ if (host && typeof host.querySelector === 'function') {
2964
+ const el = host.querySelector(`[data-knit-tier="${key}"]`)
2965
+ if (el && typeof el.scrollIntoView === 'function') {
2966
+ // v0.18 UI 迭代(md §十七):把那一层滚到**视口中部**,并且只在允许动效时
2967
+ // 用平滑滚动(`motionAllowed()` 已经把「减弱动态效果」挡在外面 ⇒ 那时是瞬移,
2968
+ // 与 md §十八 的 `scroll-behavior:auto` 同义)。
2969
+ el.scrollIntoView({ behavior: motionAllowed() ? 'smooth' : 'auto', block: 'center' })
2970
+ }
2971
+ }
2972
+ }
2973
+
2974
+ /** 打开某一篇 —— 它**可能不在当前列表里**(包外文档就不在 `state.docs` 里)。
2975
+ * 走模块级 `requestPreview`:与工具输出、其他座位共用同一条打开路径。
2976
+ * ⚠️ **不重新请求列表**:只换预览(规格 §16)。已经打开同一篇就保持原预览。 */
2977
+ const openDocByRel = (rel) => {
2978
+ if (!rel) return
2979
+ if (preview && preview.rel === rel) return
2980
+ requestPreview({ rel, title: rel })
2981
+ }
2982
+
2983
+ // 高亮只亮一下,然后自己收掉(不靠 hover、不靠「点了别处」)。
2984
+ React.useEffect(() => {
2985
+ if (!flashTier) return undefined
2986
+ const timer = setTimeout(() => setFlashTier(''), FLASH_MS)
2987
+ return () => clearTimeout(timer)
2988
+ }, [flashTier])
2989
+
2990
+ // 面板矮的时候 Lens 要降级(Summary + Coverage + 最近读取;Outside / Delta 收成标题)。
2991
+ React.useEffect(() => {
2992
+ if (typeof ResizeObserver !== 'function' || !rootRef.current) return undefined
2993
+ const observer = new ResizeObserver((entries) => {
2994
+ const box = entries && entries[0] && entries[0].contentRect
2995
+ const height = box ? box.height : 0
2996
+ if (height) setPanelH((current) => (Math.abs(current - height) < 1 ? current : height))
2997
+ })
2998
+ observer.observe(rootRef.current)
2999
+ return () => observer.disconnect()
3000
+ }, [])
2584
3001
  const motionOn = motionAllowed()
2585
3002
  // 视图签名:换类型 / 换排序 / 搜索词变了都算「换屏」——整屏一起飞会很吵。
2586
3003
  const motionView = `${kind}|${state.mode}|${query.trim()}`
@@ -2699,8 +3116,16 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2699
3116
  // `mark`=没号时同列的占位标记,只在「这一屏里有号」时为真。
2700
3117
  // 进出动效只在真机上跑(`motionOn`):测试替身没有 DOM,`motionAllowed()` 挡掉,
2701
3118
  // 于是渲染树里既没有 `entering` 也没有 `leaving`,与没有这段动效时逐字一致。
3119
+ // v0.18:生命周期现在是**一枚 glyph + 一段极短的文字**。glyph 可点:
3120
+ // 点它=打开 / 选中这一篇(**已经打开则保持原预览**,不重开也不重拉)。
3121
+ const info = withLife ? lifeInfo(doc.rel) : null
2702
3122
  return h(DocRow, { ...common, relevance, why: whyText(doc.reason), num, mark, primary,
2703
- life: withLife ? lifecycleLabel(doc.rel) : null,
3123
+ life: info ? info.text : null,
3124
+ glyph: info,
3125
+ onGlyph: (target) => {
3126
+ if (preview && preview.rel === target.rel) return
3127
+ openPreview(target)
3128
+ },
2704
3129
  entering: motion.entered.has(doc.rel) ? motion.entered.get(doc.rel) : null,
2705
3130
  leaving: Boolean(doc.knitLeaving) })
2706
3131
  }
@@ -2758,61 +3183,144 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2758
3183
  // title 里(可见文本本来就不许出现关键词,test/i18n.test.mjs 有守卫)。
2759
3184
  // ⚠️ i18n 里那四个 topic.* 键已同时删除,不要为了「以后可能用」留着。
2760
3185
 
2761
- /* v0.15「使用情况」:只把**事实**读出来 —— 先看的那篇读没读、辅助读了几篇、
2762
- 一共读了几次、几次落在包外、上下文换过几回。
3186
+ /* v0.18「Context Usage Lens」:列表**上方**的一块轻量观察层。
3187
+ 它按**视觉层级**回答四件事(规格 §9 的三层):
3188
+ Level 1 当前上下文 Coverage(这一份上下文被用到什么程度)
3189
+ Level 2 最近读取(最近一次成功读的是什么)
3190
+ Level 3 上下文外读取 / 上下文变化(辅助事实)
3191
+ 三块不能一样重 —— 靠**空间与字号**拉开,不靠横线、不靠颜色、不靠卡片。
2763
3192
  ⚠️ 不许出现分数 / 百分比 / 评分条 / 置信度 / 「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 }))
3193
+ 「这份上下文有没有被用上」,不是「它好不好用」。**没有任何一行是估算出来的。**
3194
+ ⚠️ 关掉使用情况时**一个节点都不加**(`.knit-usage` 整个不渲染,与 v0.17 一致)。*/
3195
+
3196
+ const usageNow = usageOn && state.usage && state.usage.stats ? state.usage : null
3197
+ // 「Epoch N」只在标题行显示一次:`epochId` 是**累计编号**(换一次 +1),
3198
+ // 一份包都没交过时是 null,整个角标不显示(SDD §20)。
3199
+ const epochText = usageNow && Number.isInteger(usageNow.epochId)
3200
+ ? t('lens.epoch', { n: usageNow.epochId })
3201
+ : ''
3202
+ // 摘要行=三件纯事实,一行读完。**不写 Primary 文件名、不写「辅助 0/3」**——
3203
+ // 那两件事下面的 Coverage 说得更准、更短(规格 §10)。
3204
+ const lensSummary = (() => {
3205
+ if (!usageNow) return t('usage.none')
3206
+ const s = usageNow.stats
3207
+ const parts = [t('lens.reads', { n: s.reads || 0 })]
3208
+ if (s.outside) parts.push(t('lens.outside', { n: s.outside }))
3209
+ const changes = s.churn && s.churn.snapshots ? s.churn.snapshots : 0
3210
+ if (changes) parts.push(t('lens.changes', { n: changes }))
2784
3211
  return parts.join(' · ')
2785
3212
  })()
2786
3213
 
2787
- /* v0.17:三条新事实 —— 全部只在「使用情况」开着、且宿主真的回传了 `usage` 时出现。
2788
- ① 最近读取(按事件 seq 认「谁是最近一次」,墙钟只用来算相对时间)
2789
- ② 上下文外读取的明细(当前包外、但真实成功读过)
2790
- ③ 最近**一次** Context Delta
2791
- ⚠️ 关掉使用情况时**一个节点都不加**:DOM 与 v0.16 逐字一致。
3214
+ /* v0.17 的三条事实 —— 全部只在「使用情况」开着、且宿主真的回传了 `usage` 时出现。
2792
3215
  ⚠️ 这里没有时间线、没有全量事件、没有评分 —— 「最近一次」就只有一条。 */
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
3216
 
2803
- const outsideList = usageFacts && Array.isArray(usageFacts.outsideDocs) ? usageFacts.outsideDocs : []
2804
- const gapNode = outsideList.length > 0
3217
+ // ── Level 1:当前上下文 Coverage ────────────────────────────────
3218
+ // ⚠️ 用 `state.context` 的三层**原始** rels(不是 `contextView`:那一份被过滤框
3219
+ // 子集化、而且只在文档档 + 相关序成立),再叠上 `usage.lifecycle` —— 纯派生,
3220
+ // 不新增任何一份自己的状态(「能派生就不要存储」)。
3221
+ const coverage = coverageOf({
3222
+ primary: (state.context && state.context.primary) || [],
3223
+ supporting: (state.context && state.context.supporting) || [],
3224
+ related: (state.context && state.context.related) || [],
3225
+ }, usageNow ? usageNow.lifecycle : null)
3226
+ const coverageNode = contextView ? h('div', { className: 'knit-lens-sec', key: 'cov' },
3227
+ h('div', { className: 'knit-lens-cap' }, t('lens.currentContext')),
3228
+ h('div', { className: 'knit-cov' },
3229
+ ['primary', 'supporting', 'related']
3230
+ // Primary 可以被一份包整体缺席 —— 那就整列不显示,而不是画一个
3231
+ // 「0 / 0」的假层(规格 §11:Knit 不能假设一定有 Primary)。
3232
+ .filter((key) => !(key === 'primary' && coverage.primary.total === 0))
3233
+ .map((key) => h('button', {
3234
+ className: 'knit-cov-col',
3235
+ key,
3236
+ type: 'button',
3237
+ title: t('lens.locate', { tier: t(`tierName.${key}`) }),
3238
+ // 读屏的说法是完整一句「主要上下文:0 / 1 篇已读」(md §六十三)——
3239
+ // 但**视觉上不显示这句话**:屏幕上给的是层名 + `n / m` + 圆点。
3240
+ 'aria-label': t('lens.coverageAria', {
3241
+ tier: t(`tierName.${key}`),
3242
+ read: coverage[key].read,
3243
+ total: coverage[key].total,
3244
+ }),
3245
+ onClick: () => locateTier(key),
3246
+ },
3247
+ // 视觉(点)与文本(已读 ÷ 本层总数)**同时**存在:只给点读不出「读了几篇」,
3248
+ // 只给数字又看不出「是哪几篇」。没有进度条、没有百分比。
3249
+ // ⚠️ **顺序**是「层名 → 数字 → 圆点」,不要调换:这三个是 grid 的同一套单元格,
3250
+ // 自动排布按 DOM 顺序找空位 —— 层名占第 1 行第 1 列、数字占第 1 行第 2 列、
3251
+ // 圆点那一条横跨两列,于是必然落到第 2 行(换顺序数字会被挤到圆点下面一行)。
3252
+ h('span', { className: 'knit-cov-name' }, t(`tierName.${key}`)),
3253
+ h('span', { className: 'knit-cov-num' },
3254
+ `${coverage[key].read} / ${coverage[key].total}`),
3255
+ // v0.18 UI 迭代:**真的圆**(9px,见 CSS),不再是 `○ ●` 字符 —— 字符圆点在不同
3256
+ // 字体下大小不一,正是「不像设计稿」的那一处。点本身对读屏是装饰(aria-hidden),
3257
+ // 「几篇已读」由上面那个 aria-label 的完整句子说。
3258
+ h('span', { className: 'knit-cov-dots' },
3259
+ coverage[key].rels.map((item) => h('span', {
3260
+ className: `knit-cov-dot${item.read ? ' on' : ''}`,
3261
+ key: item.rel,
3262
+ 'aria-hidden': 'true',
3263
+ }))))))) : null
3264
+
3265
+ // ── Level 2:最近读取(最近一次**成功** read;不是「正在阅读」)──────
3266
+ const recent = usageNow && usageNow.recentRead ? usageNow.recentRead : null
3267
+ const recentNode = h('div', { className: 'knit-lens-sec', key: 'recent' },
3268
+ h('div', { className: 'knit-lens-name' }, t('lens.recentRead')),
3269
+ recent && recent.rel
3270
+ ? h('button', {
3271
+ className: 'knit-read-row',
3272
+ type: 'button',
3273
+ title: t('lens.openDoc', { rel: recent.rel }),
3274
+ // 这一行整行可点(打开预览),所以它需要一个**完整的可访问名**(md §二十二):
3275
+ // 只有 title 的话读屏在部分平台读不出「这是干什么的」。
3276
+ 'aria-label': t('lens.openDoc', { rel: recent.rel }),
3277
+ onClick: () => openDocByRel(recent.rel),
3278
+ },
3279
+ h('span', { className: 'knit-read-rel' }, recent.rel),
3280
+ h('span', { className: 'knit-read-time' }, relTime(recent.at, tick)),
3281
+ // 箭头是装饰(对读屏隐藏);不要前导空格 —— 间距由 .knit-read-row 的 gap 给。
3282
+ h('span', { className: 'knit-read-go', 'aria-hidden': 'true' }, '›'))
3283
+ : h('div', { className: 'knit-lens-empty' }, t('lens.recentNone')))
3284
+
3285
+ // ── Level 3a:上下文外读取(可浏览集合;排序是**事实排序**)─────────
3286
+ const outsideList = usageNow && Array.isArray(usageNow.outsideDocs) ? usageNow.outsideDocs : []
3287
+ const outsideSorted = groupOutsideDocs(outsideList)
3288
+ const outsideNode = outsideSorted.length > 0
2805
3289
  ? h('div', { className: 'knit-usage-more', key: 'gap' },
2806
3290
  h('button', {
2807
3291
  className: 'knit-more-btn',
2808
3292
  type: 'button',
2809
3293
  'aria-expanded': gapOpen ? 'true' : 'false',
2810
3294
  onClick: () => setGapOpen((value) => !value),
2811
- }, t('usage.outsideDocs', { n: outsideList.length })),
3295
+ },
3296
+ // 菜单行的三段(md §三十四):「label ── 数量 ›」。原来把两条信息压在一个字符串里
3297
+ // (`上下文外读取 · 20`),数字既不右对齐、也不能单独参与排版。
3298
+ h('span', { className: 'knit-more-label' }, t('lens.outsideDocs')),
3299
+ h('span', { className: 'knit-more-meta' }, String(outsideSorted.length)),
3300
+ h('span', { className: 'knit-read-go', 'aria-hidden': 'true' }, gapOpen ? '⌃' : '›')),
2812
3301
  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)
3302
+ // 每一行都是**可点对象**(点开预览),但**不许**加入 Context ——
3303
+ // V0.18 不做 Context Control(规格 §19)。
3304
+ // 行首序号(md §三十六):让展开的包外列表可数,并把 rel 与次数隔开。
3305
+ // 序号说的是**位置**(第几篇),不是评分。
3306
+ outsideSorted.slice(0, MAX_OUTSIDE_SHOWN).map((row, i) => h('button', {
3307
+ className: 'knit-out-row',
3308
+ key: row.rel,
3309
+ type: 'button',
3310
+ title: t('lens.openDoc', { rel: row.rel }),
3311
+ onClick: () => openDocByRel(row.rel),
3312
+ },
3313
+ h('span', { className: 'knit-out-num' }, String(i + 1).padStart(2, '0')),
3314
+ h('span', { className: 'knit-out-rel' }, row.rel),
3315
+ h('span', { className: 'knit-out-count' }, `×${row.count}`),
3316
+ // 每一行都带生命周期:**复用 v0.17 那一份数据**,不维护第二套。
3317
+ // ⚠️ 用 `lifeWord`(状态词)而不是 `lifecycleLabel`(短次数):左边已经有 `×N` 了。
3318
+ h('span', { className: 'knit-life' }, lifeWord(row.rel)))),
3319
+ outsideSorted.length > MAX_OUTSIDE_SHOWN
3320
+ ? h('div', { className: 'knit-gap-row' },
3321
+ h('span', { className: 'knit-gap-rel' },
3322
+ t('lens.more', { n: outsideSorted.length - MAX_OUTSIDE_SHOWN })))
3323
+ : null) : null)
2816
3324
  : null
2817
3325
 
2818
3326
  // 层级的**短名**:分组标题那套长文案(主要上下文 / 辅助上下文 / 相关上下文)在变化行里太长。
@@ -2822,31 +3330,41 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2822
3330
  if (key === 'related') return t('tierName.related')
2823
3331
  return ''
2824
3332
  }
2825
- const delta = usageFacts && usageFacts.latestDelta ? usageFacts.latestDelta : null
3333
+ const delta = usageNow && usageNow.latestDelta ? usageNow.latestDelta : null
2826
3334
  const deltaLine = (text, key) => h('div', { className: 'knit-delta-row', key },
2827
3335
  h('span', { className: 'knit-delta-rel' }, text))
3336
+ /** `moved` 的两种载荷都认:v0.17 起宿主给的是 `{tier,rank}`,旧夹具里是裸层名。 */
3337
+ const tierOf = (value) => (value && typeof value === 'object' ? value.tier : value)
3338
+ const deltaText = (kind, item) => {
3339
+ if (kind === 'enter') return `+ ${item.rel}`
3340
+ if (kind === 'leave') return `- ${item.rel}`
3341
+ return `↔ ${item.rel} · ${tierShort(tierOf(item.from))} → ${tierShort(tierOf(item.to))}`
3342
+ }
2828
3343
  // 摘要行的符号只用 `+` `-` `↔` 三个通用符号,不用颜色区分「进 / 出」。
3344
+ const grouped = groupDelta(delta)
2829
3345
  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') })
3346
+ for (const item of grouped.enter) {
3347
+ deltaDigest.push({ key: `plus-${item.rel}`, text: deltaText('enter', item) })
3348
+ }
3349
+ for (const item of grouped.leave) {
3350
+ deltaDigest.push({ key: `minus-${item.rel}`, text: deltaText('leave', item) })
2844
3351
  }
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
- ] : []
3352
+ for (const item of grouped.move) {
3353
+ deltaDigest.push({ key: `move-${item.rel}`, text: deltaText('move', item) })
3354
+ }
3355
+ if (delta && delta.taskChanged) deltaDigest.push({ key: 'task', text: t('usage.deltaTask') })
3356
+ const deltaGroups = [
3357
+ { key: 'enter', label: t('usage.deltaEnter'),
3358
+ rows: grouped.enter.map((item) => ({ key: `plus-${item.rel}`, text: deltaText('enter', item) })) },
3359
+ { key: 'leave', label: t('usage.deltaLeave'),
3360
+ rows: grouped.leave.map((item) => ({ key: `minus-${item.rel}`, text: deltaText('leave', item) })) },
3361
+ { key: 'move', label: t('usage.deltaMove'),
3362
+ rows: grouped.move.map((item) => ({ key: `move-${item.rel}`, text: deltaText('move', item) })) },
3363
+ ].filter((group) => group.rows.length > 0)
3364
+ // ⚠️ `compact` 必须在 `previewLines` 之前算出来(TDZ)。
3365
+ const compact = panelH > 0 && panelH < COMPACT_PANEL_PX
3366
+ // 面板矮的时候收起态**不铺摘要行** —— 只留标题,点开照常看得到。
3367
+ const previewLines = compact ? [] : deltaDigest.slice(0, MAX_DELTA_SHOWN)
2850
3368
  const deltaNode = delta
2851
3369
  ? h('div', { className: 'knit-usage-more', key: 'delta' },
2852
3370
  h('button', {
@@ -2854,22 +3372,56 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2854
3372
  type: 'button',
2855
3373
  'aria-expanded': deltaOpen ? 'true' : 'false',
2856
3374
  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')
3375
+ },
3376
+ // 菜单行的三段(md §三十八):「上下文变化 ── 最近一次 ›」。
3377
+ // ⚠️ 这里**不再写条数**(原来是 `上下文变化 · 11`):变化永远只说最近一次,
3378
+ // 「有几条」由展开后的行数与「还有 N 条」承担 —— 数字写在按钮上时,
3379
+ // 折叠摘要、分组尾巴、按钮三处会各自算一遍,很容易自相矛盾。
3380
+ h('span', { className: 'knit-more-label' }, t('lens.delta')),
3381
+ h('span', { className: 'knit-more-meta' }, t('lens.deltaLatest')),
3382
+ h('span', { className: 'knit-read-go', 'aria-hidden': 'true' }, deltaOpen ? '⌃' : '›')),
3383
+ // ⚠️ 展开后**不再画折叠摘要**:分组视图是它的超集(三行摘要 + 「还有 N 条」再叠上
3384
+ // 分组明细,同一条事实会在同一块里出现两遍 —— 2026-10-05 用真实载荷渲染时抓到)。
3385
+ deltaOpen ? null : previewLines.map((line) => deltaLine(line.text, line.key)),
3386
+ !deltaOpen && !compact && deltaDigest.length > MAX_DELTA_SHOWN
3387
+ ? deltaLine(t('usage.deltaMore', { n: deltaDigest.length - MAX_DELTA_SHOWN }), 'more')
2861
3388
  : null,
2862
3389
  deltaOpen ? deltaGroups
2863
- .filter((group) => group.rows.length > 0)
2864
3390
  .map((group) => [
2865
3391
  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`)
3392
+ ...group.rows.slice(0, MAX_DELTA_GROUP)
3393
+ .map((line) => deltaLine(line.text, `${group.key}-${line.key}`)),
3394
+ group.rows.length > MAX_DELTA_GROUP
3395
+ ? deltaLine(t('usage.deltaMore', { n: group.rows.length - MAX_DELTA_GROUP }),
3396
+ `${group.key}-more`)
2869
3397
  : null,
2870
- ]) : null)
3398
+ ]) : null,
3399
+ // ⚠️ 「任务上下文已更新」不是进出换层,没有分组标题可挂 —— 但它算在
3400
+ // `deltaDigest.length` 里(按钮上那个数字就是它)。展开时漏掉这一行,
3401
+ // 就会出现「按钮说 6 条、下面只列出 5 行」的自相矛盾(2026-10-05 用真实载荷渲染时抓到)。
3402
+ // 它在摘要里的位置本来就是最后一条,这里也放最后。
3403
+ deltaOpen && delta && delta.taskChanged
3404
+ ? deltaLine(t('usage.deltaTask'), 'task')
3405
+ : null)
2871
3406
  : null
2872
3407
 
3408
+ // ── Lens 整块:标题行(可点,展开 / 收起)+ 摘要行 + 细节 ──────────
3409
+ // ⚠️ 「收起」不等于「关掉统计」:收起只表示「统计开着,但暂时不想看细节」(规格 §25)。
3410
+ const lensNode = h('div', { className: 'knit-usage', title: t('usage.note') },
3411
+ h('button', {
3412
+ className: 'knit-lens-head',
3413
+ type: 'button',
3414
+ 'aria-expanded': lensOpen ? 'true' : 'false',
3415
+ title: lensOpen ? t('lens.collapse') : t('lens.expand'),
3416
+ onClick: () => setLensOpen((value) => !value),
3417
+ },
3418
+ h('span', { className: 'knit-lens-title' }, t('lens.title')),
3419
+ epochText ? h('span', { className: 'knit-lens-epoch' }, epochText) : null,
3420
+ h('span', { className: 'knit-read-go', 'aria-hidden': 'true' }, lensOpen ? ' ˄' : ' ˅')),
3421
+ h('div', { className: 'knit-lens-sum' }, lensSummary),
3422
+ lensOpen ? h('div', { className: 'knit-lens-body' },
3423
+ coverageNode, recentNode, outsideNode, deltaNode) : null)
3424
+
2873
3425
  // 不同类型用不同量词:文档「篇」、媒体「个」、混排「项」。
2874
3426
  const countKey = kind === KIND_MEDIA
2875
3427
  ? (filtering ? 'count.media.filtered' : 'count.media')
@@ -2938,13 +3490,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2938
3490
  title: t('kind.title'),
2939
3491
  onClick: () => pickKind(value),
2940
3492
  }, 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,
3493
+ // v0.15:开了才显示。v0.18:这一块是「Context Usage Lens」——
3494
+ // 列表**上方**的观察层,不是弹窗、不是新页面、不是 Dashboard。
3495
+ usageOn ? lensNode : null,
2948
3496
  notice ? h('div', { className: 'knit-notice' }, notice) : null,
2949
3497
  // 列表节点**直接挂上去**(2026-09-29 起永远单栏;曾经它要交给一个 IIFE
2950
3498
  // 决定塞进单栏还是双栏的左列)。**输出与 v0.13 逐字一致** ——