dsh-knit 0.15.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -37,7 +37,6 @@ window.__ModuleLoader__.load({
37
37
  'count.all.filtered': '{hit} / {total} 项',
38
38
  'action.refresh': '刷新',
39
39
  'path.openTitle': '在文件管理器中打开',
40
- 'peek.openPanel': '点击打开面板',
41
40
  'peek.empty': '这个工作区里还没有 Markdown 文档。',
42
41
  'action.refreshNow': '立即刷新',
43
42
 
@@ -51,18 +50,13 @@ window.__ModuleLoader__.load({
51
50
  'kind.media': '图片与视频',
52
51
  'kind.title': '切换要列出的产物类型',
53
52
 
54
- 'filter.placeholder': '过滤标题 / 摘要 / 路径',
53
+ 'filter.placeholder': '过滤文档',
55
54
  'filter.aria': '过滤文档',
56
55
 
57
- // 关键词**退到 title 里当低层 metadata**(2026-09-29 用户要求弱化):
58
- // 可见的只有「相关性排序」一句,命中了哪几个词只在悬停时给。
59
- 'topic.relevanceTerms': '按相关度排序 · 命中的关键词:{topic}',
60
- 'topic.relevancePlain': '相关性排序',
61
- 'topic.needsConversation': '对话内容还不足,暂按最新排序',
62
- 'topic.time': '按修改时间倒序',
63
56
  'usage.toggle': '使用情况',
64
57
  'usage.toggleTitle': '打开后开始统计这个会话:先看的那篇有没有被读、有多少次读落在包外、上下文换过几回。只记事实,不给分数。',
65
58
  'usage.none': '还没有记录',
59
+ 'usage.epoch': '当前上下文 · Epoch {n}',
66
60
  'usage.primaryRead': '先看的「{rel}」已读',
67
61
  'usage.primaryUnread': '先看的「{rel}」还没读',
68
62
  'usage.supporting': '辅助 {read}/{total}',
@@ -71,6 +65,29 @@ window.__ModuleLoader__.load({
71
65
  'usage.changes': '上下文换过 {n} 次',
72
66
  'usage.note': '只统计本会话 · 数据在内核内存里,重启 DSH 就没了',
73
67
 
68
+ // ── v0.17 文档生命周期(Document Lifecycle)──────────────────
69
+ // ⚠️ 四态全是**事实**,不是评价:「读后已更新」只说「文件在最后一次成功读取之后
70
+ // 变过」,绝不许写成「Agent 还不知道最新版本」「Agent 用了旧版本」这类推断。
71
+ // ⚠️ 「最近读取」不是「正在阅读」—— Knit 证明不了 Agent 此刻是否还在读它。
72
+ // ⚠️ 「上下文外读取」只陈述「这篇不在当前包内、但被成功读过」,
73
+ // 不许写成「Knit 漏了 / 推荐错了 / 命中率低」。
74
+ 'usage.recentRead': '最近读取:{rel} · {time}',
75
+ 'usage.outsideDocs': '上下文外读取 · {n} 篇',
76
+ 'usage.deltaTitle': '上下文刚刚变化',
77
+ 'usage.deltaEnter': '进入',
78
+ 'usage.deltaLeave': '离开',
79
+ 'usage.deltaMove': '换层',
80
+ 'usage.deltaTask': '任务上下文已更新',
81
+ 'usage.deltaMore': '还有 {n} 条',
82
+ 'lifecycle.unread': '未读',
83
+ 'lifecycle.read': '已读',
84
+ 'lifecycle.readCount': '已读 ×{n}',
85
+ 'lifecycle.updatedAfterRead': '读后已更新',
86
+ 'lifecycle.rereadAfterUpdate': '修改后已重新读取',
87
+ 'tierName.primary': '主要',
88
+ 'tierName.supporting': '辅助',
89
+ 'tierName.related': '相关',
90
+
74
91
  // ── v0.14 当前任务上下文(Context Pack)──────────────────────
75
92
  // ⚠️ 文案纪律:不出现「AI / 智能 / 推荐 / 置信度 / 百分比」。
76
93
  // 这一层是确定性规则算出来的,说成 AI 就是在骗用户。也不能放表情符号
@@ -136,7 +153,7 @@ window.__ModuleLoader__.load({
136
153
  'preview.fullscreenTitle': '全屏阅读',
137
154
  'preview.exitFullscreenTitle': '退出全屏(Esc)',
138
155
  'preview.openLocal': '{path}\n用系统默认应用打开这篇文档',
139
- 'preview.openLocalBtn': '在本地打开',
156
+ 'preview.openLocalBtn': '本地打开',
140
157
  'preview.close': '收起预览',
141
158
  'preview.resizeTitle': '拖动调整高度',
142
159
  // v0.12 引用条。⚠️ 不放任何表情符号(test/i18n.test.mjs 有守卫)。
@@ -189,7 +206,6 @@ window.__ModuleLoader__.load({
189
206
  'count.all.filtered': '{hit} / {total} items',
190
207
  'action.refresh': 'Refresh',
191
208
  'path.openTitle': 'Open in file manager',
192
- 'peek.openPanel': 'Click to open the panel',
193
209
  'peek.empty': 'No Markdown documents in this workspace yet.',
194
210
  'action.refreshNow': 'Refresh now',
195
211
 
@@ -203,18 +219,13 @@ window.__ModuleLoader__.load({
203
219
  'kind.media': 'Images & video',
204
220
  'kind.title': 'Switch which artifacts are listed',
205
221
 
206
- 'filter.placeholder': 'Filter title / summary / path',
222
+ 'filter.placeholder': 'Filter docs',
207
223
  'filter.aria': 'Filter documents',
208
224
 
209
- // Keywords are **low-level metadata** now (2026-09-29): the visible text is just
210
- // "Sorted by relevance" — which terms matched only shows up on hover.
211
- 'topic.relevanceTerms': 'Sorted by relevance · matched keywords: {topic}',
212
- 'topic.relevancePlain': 'Sorted by relevance',
213
- 'topic.needsConversation': 'Not enough conversation yet — sorted by time',
214
- 'topic.time': 'Sorted by modified time',
215
225
  'usage.toggle': 'Usage',
216
226
  '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.',
217
227
  'usage.none': 'Nothing recorded yet',
228
+ 'usage.epoch': 'Context · Epoch {n}',
218
229
  'usage.primaryRead': 'primary read ({rel})',
219
230
  'usage.primaryUnread': 'primary not read yet ({rel})',
220
231
  'usage.supporting': 'supporting {read}/{total}',
@@ -223,6 +234,29 @@ window.__ModuleLoader__.load({
223
234
  'usage.changes': 'context changed {n}×',
224
235
  'usage.note': 'This session only · kept in kernel memory, gone after a DSH restart',
225
236
 
237
+ // ── v0.17 document lifecycle ───────────────────────────────
238
+ // ⚠️ All four states are facts, never judgements: "Updated after read" only says the
239
+ // file changed after the last successful read. Never "the agent has not seen the
240
+ // 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',
246
+ 'usage.deltaEnter': 'Entered',
247
+ 'usage.deltaLeave': 'Left',
248
+ 'usage.deltaMove': 'Moved tier',
249
+ 'usage.deltaTask': 'Task context updated',
250
+ 'usage.deltaMore': '+{n} more',
251
+ 'lifecycle.unread': 'Unread',
252
+ 'lifecycle.read': 'Read',
253
+ 'lifecycle.readCount': 'Read ×{n}',
254
+ 'lifecycle.updatedAfterRead': 'Updated after read',
255
+ 'lifecycle.rereadAfterUpdate': 'Re-read after update',
256
+ 'tierName.primary': 'Primary',
257
+ 'tierName.supporting': 'Supporting',
258
+ 'tierName.related': 'Related',
259
+
226
260
  // ── v0.14 current-task context (Context Pack) ──────────────
227
261
  // ⚠️ Never say "AI", "smart", "recommended", "confidence" or show percentages:
228
262
  // this tiering is deterministic local rules, and pretending otherwise is a lie.
@@ -607,18 +641,34 @@ body[data-ds-dark-theme] .knit-root{
607
641
  border:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.1));outline:none}
608
642
  .knit-filter:focus{border-color:var(--knit-accent)}
609
643
  .knit-filter::placeholder{color:var(--dsw-alias-label-caption,#80868b)}
610
- .knit-topic{flex:none;padding:0 12px 9px;font-size:10.5px;line-height:1.4;
611
- color:var(--dsw-alias-label-caption,#80868b);
612
- overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
613
- /* ⚠️ 这里以前有一条 border-bottom(全宽横线)。2026-09-29 用户要求**减少全宽分割线**
614
- ——「页面上横线一多,读起来就像文件管理表格」。层级改由空间与字号建立:
615
- 这一行只用 bottom padding 与列表拉开距离,不画线。 */
616
644
  /* v0.15「使用情况」:**一行事实**,不画卡片、不画进度条、不用品牌色。
617
- 它就在「相关性排序」那行下面 —— 与它同档的弱化文字,不是一块新面板。 */
645
+ 它占的就是原来「相关性排序」那一行的位置 —— 2026-09-30 用户裁决那一行
646
+ 整个删掉(排序方式由「相关 / 最新」那个切换按钮自己表达,再说一遍是重复),
647
+ 所以它现在是头部下面唯一的一行弱化文字,不是一块新面板。
648
+ ⚠️ 全宽横线一律不画:2026-09-29 用户要求**减少全宽分割线** ——
649
+ 「页面上横线一多,读起来就像文件管理表格」。层级由空间与字号建立。 */
618
650
  .knit-usage{flex:none;padding:0 12px 9px;font-size:10.5px;line-height:1.45;
619
651
  color:var(--dsw-alias-label-caption,#80868b);
620
652
  overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
621
653
 
654
+ /* v0.17 文档生命周期(Document Lifecycle)—— 三条新信息,都只是**事实**。
655
+ ⚠️ 状态是文字,不是徽章:不加底色、不加边框、不用红绿 —— 红绿会把「事实」读成
656
+ 「好 / 坏」(PRD §7.3)。字号 10.5px,比 14px 的标题弱一档,永远不抢标题。
657
+ ⚠️ 折叠块沿用 .knit-usage 的弱化灰阶:它们是同一行事实的展开,不是新卡片。
658
+ ⚠️ 这一段**不含反引号**,整段可以直接放在 CSS 模板串里。 */
659
+ .knit-life{flex:none;font-size:10.5px;line-height:1.4;white-space:nowrap;
660
+ 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)}
665
+ .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;
667
+ color:var(--dsw-alias-label-caption,#80868b)}
668
+ .knit-gap-rel,.knit-delta-rel{flex:1 1 auto;min-width:0;overflow:hidden;
669
+ text-overflow:ellipsis;white-space:nowrap}
670
+ .knit-delta-head{margin-top:3px;color:var(--dsw-alias-label-secondary,#9aa0a6)}
671
+
622
672
 
623
673
  /* ── v0.14 右栏(Context Pack 面板)已整体删除(2026-09-29)────────
624
674
  用户裁定:Context Pack 是**数据层**结构(Primary / Supporting / Related),
@@ -670,7 +720,9 @@ body[data-ds-dark-theme] .knit-root{
670
720
  其他数据放在右边」)。第一列=序号那条竖直的轴(.knit-num),第二列=其余全部数据
671
721
  (.knit-body)。用 grid 而不是「有号才插一个元素」,是因为没有号的条目(时间序 /
672
722
  筛选结果 /「其他相关文档」)也要和有的条目**左边缘对齐** —— 轨道一直在,
673
- 正文就永远不会因为少一个序号而左移。 */
723
+ 正文就永远不会因为少一个序号而左移。
724
+ 2026-10-01 补:光对齐还不够 —— **混着**才刺眼(整屏没号时没人觉得缺东西)。所以
725
+ 这一屏里有号时,没号的行在同一列渲染一个 .knit-gapmark(·)把格子顶住。 */
674
726
  /* 行的**静止态没有底色**(2026-09-29 用户反馈:「深色模式下,文档列表没有选中,鼠标没有悬停,
675
727
  不需要有背景。或者是说,跟深色模式的最底下的背景一样」)。
676
728
  ⚠️ 这里以前写的是 bg-layer-1 —— 浅色主题下它和面板底色都是 #fff(根本看不出来),
@@ -678,24 +730,37 @@ body[data-ds-dark-theme] .knit-root{
678
730
  现在静止态直接 transparent,露出宿主侧边栏的底色(.knit-root / .knit-list 都不画底色);
679
731
  ⚠️ 右栏删除后这段注释里提到的 .knit-pack 已经不存在了(2026-09-29),
680
732
  hover 与 .active 各有自己的令牌,
681
- 两者都**不该**跟着改成 transparent(那样一屏灰里就认不出选中态了)。 */
733
+ 两者都**不该**跟着改成 transparent(那样一屏灰里就认不出选中态了)。
734
+ ⚠️ 2026-09-30 用户反馈:「悬停跟选中,最外层那个描边,我觉得也不需要了,还是有点影响」
735
+ ⇒ 原来那圈 .5px solid transparent(悬停 / 选中时才上色)**整条删掉**。
736
+ padding 各加 .5px 补回那条边框占掉的宽度,行的几何尺寸与改前逐像素一致
737
+ (所以下面这两条 padding 数字是有来历的,不是随手写的小数)。 */
682
738
  .knit-doc{display:grid;grid-template-columns:22px minmax(0,1fr);column-gap:8px;align-items:start;
683
- padding:10px 11px;border-radius:10px;cursor:pointer;
684
- border:.5px solid transparent;background:transparent;
685
- transition:background .18s,border-color .18s,transform .18s,opacity .18s}
686
- .knit-doc:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));
687
- border-color:var(--dsw-alias-border-l4,rgba(255,255,255,.1));transform:translateX(-2px)}
688
- /* 选中(正在预览)用**中性描边**(Design §12 / 2026-09-29 用户裁决)。
689
- ⚠️ 这里曾经是品牌色描边。用户本次的决定是「按 Design 改成 neutral border」,
690
- 理由是 Design §8「用灰阶建立层级,而不是用颜色建立层级」——
691
- 选中态要能从一屏灰里被认出来,但不该在整个界面里唯一地跳成蓝色。
692
- 两个态不再靠色相区分,而是靠「选中=整行描边 + 灰底」。 */
693
- .knit-doc.active{border-color:var(--dsw-alias-border-l4,rgba(255,255,255,.22));
694
- background:var(--knit-active-bg,rgba(255,255,255,.085))}
739
+ padding:10.5px 11.5px;border-radius:10px;cursor:pointer;
740
+ background:transparent;
741
+ transition:background .18s,transform .18s,opacity .18s}
742
+ .knit-doc:hover{background:var(--knit-hover-bg,rgba(255,255,255,.03));transform:translateX(-2px)}
743
+ /* 选中(正在预览)=**只有灰底**(2026-09-30 用户裁决)。
744
+ ⚠️ 这条的上一版是「中性描边 + 灰底」(2026-09-29 裁决,用来取代更早的品牌色描边)。
745
+ 用户这次的原话是「文档列表悬停跟选中,最外层那个描边,我觉得也不需要了」⇒
746
+ 描边整条删掉,**选中态只剩灰底**。
747
+ ⚠️ 灰底是选中唯一的分层信号,**不许**跟着改成 transparent(一屏灰里就认不出选中了)。
748
+ ⚠️ hover 与选中的区别现在**只**是底色深浅(--knit-hover-bg / --knit-active-bg),
749
+ 不再有任何一圈线。 */
750
+ .knit-doc.active{background:var(--knit-active-bg,rgba(255,255,255,.085))}
695
751
  /* .knit-doc.cursor **故意不设样式**:键盘焦点靠「移动即预览」的预览面板表达,
696
752
  再加描边会与 .active 的整块背景重复,显得突兀。
697
753
  (曾经有一条 「.knit-multicol .knit-doc.cursor」 的中性环,是为多列网格补的 ——
698
754
  多列没了,那条也删了。) */
755
+ /* ── 列表进出动效的**静态**部分(v0.17,2026-10-03 用户要求)───────────────
756
+ 补间本身在 JS 里用 WAAPI 跑(见 client.js 的 DocRow 与 MOTION_* 那段)—— 高度要按
757
+ 量出来的自然高度补间,CSS 的 @keyframes 做不到(height:auto 不可插值)。这里只管两件事:
758
+ ① .leaving =正在离开的幽灵行:不吃指针事件、内容裁掉;
759
+ ② 系统开了「减弱动态效果」时,连底色过渡一起去掉(进出本来就不播)。 */
760
+ .knit-doc.leaving{pointer-events:none;user-select:none;overflow:hidden}
761
+ @media (prefers-reduced-motion: reduce){
762
+ .knit-doc{transition:none}
763
+ }
699
764
  /* 行一=**标题行**:Primary 点 + 标题 + 相对时间(**时间靠右**)。
700
765
  2026-09-29 这一天里这一行改了三次:先是「序号 + 标题 + 时间」,然后
701
766
  「时间跟那个置顶的序号可以一行」(序号留下、标题移出去),再后来
@@ -715,8 +780,14 @@ body[data-ds-dark-theme] .knit-root{
715
780
  它=.knit-title 的 14px × 1.4。格的 align-items:start 让这一列从卡片顶边
716
781
  开始排,所以只要这个行盒与标题行盒等高,两个字号不同的文本就自然居中。
717
782
  **改 .knit-title 的字号或行高时,这里必须同步改**,否则序号会与标题错开。 */
718
- .knit-num{grid-column:1;font-size:10.5px;line-height:19.6px;font-variant-numeric:tabular-nums;
783
+ .knit-num,.knit-gapmark{grid-column:1;font-size:10.5px;line-height:19.6px;font-variant-numeric:tabular-nums;
719
784
  color:var(--dsw-alias-label-caption,#80868b)}
785
+ /* 中性占位标记(2026-10-01 用户反馈):「其他相关文档」那一节没有序号,空着的那一格
786
+ 被读成「漏了一个号」(原话:「没有序号以后左边就空了,视觉上比较割裂,就觉得是个 bug 一样」)。
787
+ 没号的行就在同一列放一个最轻的 · —— 不冒充序号,也不让轨道断掉。
788
+ ⚠️ 只有**这一屏里有号**时才渲染(时间序 / 平铺列表整屏都没号 ⇒ 一个标记都没有:
789
+ 一屏里要么都有、要么都没有;混着才是刺眼的原因)。
790
+ ⚠️ 几何与 .knit-num 共用同一条选择器 —— 这就是「改一处必须改另一处」的执行方式。 */
720
791
  /* 右边这一列=其余全部数据(标题行 / 摘要 / 理由)。
721
792
  ⚠️ min-width:0 不能省:轨道是 minmax(0,1fr),但**单元格本身**默认也是按
722
793
  min-content 撑的,不写它标题的省略号和摘要的两行截断就不生效(会把行撑宽)。 */
@@ -789,21 +860,25 @@ body[data-ds-dark-theme] .knit-preview{box-shadow:0 -8px 24px rgba(0,0,0,.38)}
789
860
  .knit-resize::after{content:'';width:44px;height:3px;border-radius:2px;
790
861
  background:var(--dsw-alias-border-l3,rgba(255,255,255,.2));transition:background .15s,width .15s}
791
862
  .knit-resize:hover::after{background:var(--knit-accent);width:64px}
792
- /* 头对齐官方文档预览面板(.dhJKeW_header):38px 高 + border-l3,
793
- 里面放路径面包屑而不是标题 —— 正文 H1 已经写了标题,重复只添乱。 */
863
+ /* 头对齐官方文档预览面板(.dhJKeW_header):38px 高,
864
+ 里面放路径面包屑而不是标题 —— 正文 H1 已经写了标题,重复只添乱。
865
+ ⚠️ 2026-09-30 用户裁决:官方那条 border-l3 底边**不要** ——
866
+ 「查看文档详情被引用,上下那两条横线,细细的横线,我觉得也不需要的」。
867
+ 头部与引用条 / 正文之间现在只靠留白分层(配合 .knit-links 同时去掉的那条)。 */
794
868
  .knit-preview-head{box-sizing:border-box;display:flex;align-items:center;gap:4px;
795
- height:38px;padding:0 6px 0 12px;flex:none;
796
- border-bottom:.5px solid var(--dsw-alias-border-l3,rgba(255,255,255,.14))}
797
- /* 路径面包屑:**可点** —— 用系统默认应用打开这篇本地文档(阅读时多一个入口)。
798
- 目录可收缩并出省略号,文件名不收缩,所以长路径下仍然看得见是哪个文件。 */
869
+ height:38px;padding:0 6px 0 12px;flex:none}
870
+ /* 路径:**可点** —— 用系统默认应用打开这篇本地文档(阅读时多一个入口)。
871
+ 目录一律不展开,只留一个「…/」占位(2026-10-01 用户要求:「前面那一串都用三个点点点表示」,
872
+ 头部宽度让给文件名);文件名不收缩。**完整相对路径不丢** —— 在 .knit-preview-path 的悬停提示里。
873
+ ⚠️ 本段在 CSS 那一个大模板串里:注释里**不能出现反引号**(写 .knit-preview-path 这种
874
+ 带反引号的类名会把模板提前截断,客户端半边整个加载失败 —— 2026-10-01 又踩一次)。 */
799
875
  .knit-preview-path{flex:1 1 auto;min-width:0;display:flex;align-items:center;
800
876
  margin-right:6px;font-size:12px;white-space:nowrap;overflow:hidden;
801
877
  background:transparent;border:none;padding:0;font-family:inherit;text-align:left;
802
878
  color:inherit;cursor:pointer}
803
879
  .knit-preview-path:disabled{cursor:default}
804
880
  .knit-preview-path:hover:not(:disabled) .knit-preview-name{text-decoration:underline}
805
- .knit-preview-dir{flex:0 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;
806
- color:var(--dsw-alias-label-tertiary,rgba(255,255,255,.4))}
881
+ .knit-preview-dir{flex:0 0 auto;color:var(--dsw-alias-label-tertiary,rgba(255,255,255,.4))}
807
882
  .knit-preview-name{flex:0 0 auto;color:var(--dsw-alias-label-primary,#e8eaed)}
808
883
  /* 正文区把滚动条提到 l2 —— 与官方文档预览面板同一档(那边的 .body 也覆盖这两个变量)。
809
884
  不重写 ::-webkit-scrollbar,只覆盖变量,所以宽度/圆角/悬停都跟 DSH 完全一致。 */
@@ -821,9 +896,11 @@ body[data-ds-dark-theme] .knit-preview{box-shadow:0 -8px 24px rgba(0,0,0,.38)}
821
896
 
822
897
  /* ── 引用条(v0.12)────────────────────────────────────
823
898
  夹在预览头与正文之间的一层。全用中性令牌:它是「信息」,不是「操作」。
899
+ ⚠️ 2026-09-30 用户裁决:它自己那条 border-l2 底边**删掉** —— 与预览头的底边
900
+ 一上一下两条细线把这一小块夹成了独立一截,用户的原话是「有点割裂」。
901
+ 现在这一层不画任何横线,收紧的 padding 就是它的边界。
824
902
  注意 CSS 里不要写反引号 —— 这段样式是模板字符串,一个反引号就会把它截断。 */
825
- .knit-links{flex:none;border-bottom:1px solid var(--dsw-alias-border-l2,rgba(255,255,255,.08));
826
- font-size:11px;color:var(--dsw-alias-label-secondary,#9aa0a6)}
903
+ .knit-links{flex:none;font-size:11px;color:var(--dsw-alias-label-secondary,#9aa0a6)}
827
904
  .knit-links-state{padding:5px 12px;color:var(--dsw-alias-label-caption,#80868b)}
828
905
  .knit-links-head{box-sizing:border-box;display:flex;align-items:center;gap:6px;width:100%;
829
906
  padding:5px 12px;background:transparent;border:none;cursor:pointer;text-align:left;
@@ -847,14 +924,16 @@ body[data-ds-dark-theme] .knit-preview{box-shadow:0 -8px 24px rgba(0,0,0,.38)}
847
924
 
848
925
  /* ── 类型切换(文档 / 图片与视频 / 全部)────────────── */
849
926
  /* v0.14(Design §20):**不再是三个并排的灰底按钮**,改成下划线式页签 ——
850
- 底部一条 hairline,选中的那个用「深色文字 + 2px 深色下划线」表达。
927
+ 选中的那个用「深色文字 + 2px 深色下划线」表达。
851
928
  ⚠️ 2026-09-29 用户裁决:这条**覆盖**了早先那条「选中填充背景灰就可以」。
852
929
  当时用户的原话是「选中的时候不用加绿色、蓝色的描边,就跟下面列表一样」——
853
930
  诉求是「别用品牌色描边」;现在连灰底也不要了,层级交给下划线,
854
931
  依然不许出现 --knit-accent / --knit-accent-fill(Design §8:灰阶分层)。
932
+ ⚠️ 2026-09-30 用户反馈:页签条底下原本还有一条全宽 hairline(border-l1)——
933
+ 「最细最淡那条横线」与下面的列表割裂,**删掉**。层级现在只由选中项自己那条
934
+ 2px 下划线表达,页签条本身不画线(也不是「下划线悬空」:它画在自己的文字下面)。
855
935
  ⚠️ 排序切换(.knit-seg-btn,Design §18)是**另一个控件**,它保持灰底不变。 */
856
- .knit-types{display:flex;gap:14px;padding:0 12px;flex:none;
857
- border-bottom:1px solid var(--dsw-alias-border-l1,rgba(255,255,255,.06))}
936
+ .knit-types{display:flex;gap:14px;padding:0 12px;flex:none}
858
937
  .knit-type-btn{flex:none;height:28px;padding:0;cursor:pointer;
859
938
  border:none;border-bottom:2px solid transparent;background:transparent;
860
939
  color:var(--dsw-alias-label-secondary,#9aa0a6);font-family:inherit;font-size:11.5px;
@@ -965,8 +1044,6 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
965
1044
  .knit-peek-time{flex:none;font-size:10.5px;color:var(--dsw-alias-label-caption,#80868b)}
966
1045
  .knit-peek .knit-peek-hint{padding:7px;font-size:10.5px;
967
1046
  color:var(--dsw-alias-label-caption,#80868b)}
968
- .knit-peek-list + .knit-peek-hint{margin-top:4px;padding-top:8px;
969
- border-top:.5px solid var(--dsw-alias-border-l4,rgba(255,255,255,.08))}
970
1047
 
971
1048
  .knit-entry{display:inline-flex;align-items:center;justify-content:center;flex:none;
972
1049
  width:28px;height:28px;padding:0;border:none;border-radius:8px;cursor:pointer;
@@ -979,7 +1056,6 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
979
1056
  .knit-root.fullscreen .knit-head,
980
1057
  .knit-root.fullscreen .knit-bar,
981
1058
  .knit-root.fullscreen .knit-types,
982
- .knit-root.fullscreen .knit-topic,
983
1059
  .knit-root.fullscreen .knit-list{display:none}
984
1060
  /* 全屏时预览铺满整个面板:圆角与向上柔影是「浮在列表上」的隐喻,这里没有列表,去掉 */
985
1061
  .knit-root.fullscreen .knit-preview{flex:1 1 auto;max-height:none;
@@ -1344,16 +1420,273 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1344
1420
  return `knit-opt-${safe}-${(hash >>> 0).toString(36)}`
1345
1421
  }
1346
1422
 
1347
- function DocRow({ doc, now, active, cursor, relevance, why, num, primary, onSelect, onOpenTab, optionId }) {
1423
+ /* ── 列表进出动效(v0.17)─────────────────────────────────────────
1424
+ 用户原话(2026-10-03):「文档列表,新读取跟挤掉旧的未读的,这里的交互可能要优化,
1425
+ 因为现在是一闪一闪的,就非常的快……如果说从当前的,如辅助上下文中新增,它应该是
1426
+ 从低向上的,有种交互动效飞上的感觉,然后消失的时候从上到下,就隐掉了」。
1427
+
1428
+ 手感来自 `02_方案与 Demo/knit-list-motion-prototype.html`(用户点头的那一版):
1429
+ 缓动 cubic-bezier(.22,1,.36,1)、进入 translateY(26px)→0 + 渐现 + blur(3px)→0、
1430
+ 离开高度收到 0 且**自上而下**擦掉。参数照抄原型,不要再另调。
1431
+
1432
+ ⚠️ 只碰**文档行**(`.knit-doc`):媒体格子是网格布局,收起高度没有意义。
1433
+ ⚠️ 补间用 WAAPI(`Element.animate`)手写,不用 @keyframes —— 高度要按量出来的
1434
+ 自然高度补间,而 CSS 里 `height:auto` 不可插值。
1435
+ ⚠️ 行节点是按 key 复用的(`doc.path || doc.rel`),所以「闪」不是重挂 —— 是增删
1436
+ 瞬间落位、一点过渡都没有。因此动效分三件独立的事:**新来的行自己飞进来**、
1437
+ **走了的行留一个幽灵行把高度收掉**(React 一删节点就没机会补间了)、
1438
+ **活下来的行换了位置(换层 / 重排)走 FLIP** —— 量出新位置、先从老位置拉回来
1439
+ 再补间归位,逻辑也在 `KnitBody` 那次提交后的 layout effect 里(那里才有列表)。 */
1440
+ const MOTION_ENTER_MS = 320
1441
+ const MOTION_EXIT_MS = 260
1442
+ const MOTION_STAGGER_MS = 45
1443
+ const MOTION_STAGGER_MAX = 6
1444
+ const MOTION_EASE = 'cubic-bezier(.22,1,.36,1)'
1445
+ /** 幽灵行所在的「区」:分层视图用层名,平铺与「全部」各一个 —— 幽灵要插回原位。 */
1446
+ const MOTION_TIER_FLAT = 'flat'
1447
+ const MOTION_TIER_ALL_DOCS = 'all-docs'
1448
+ /** 幸存行位移(换层 / 重排)的 FLIP 时长:比进入略长,它要真的「走」完一段距离。 */
1449
+ const MOTION_MOVE_MS = 340
1450
+ /** 位移小于这个像素数(含亚像素抖动)就当没动过,不排补间。 */
1451
+ const MOTION_MOVE_EPS = 0.5
1452
+
1453
+ /**
1454
+ * 这台机器上要不要播动效。
1455
+ *
1456
+ * 三种情况**不播**:没有 DOM(Node 里的测试替身)、浏览器/系统要求「减弱动态效果」、
1457
+ * 以及不认 WAAPI 的宿主。返回假时一行补间都不排、也不留幽灵行 —— 渲染树与没有这段动效时逐字一致。
1458
+ *
1459
+ * @returns {boolean} 是否播动效
1460
+ */
1461
+ function motionAllowed() {
1462
+ if (typeof document === 'undefined' || typeof document.createElement !== 'function') return false
1463
+ if (typeof Element !== 'function' || typeof Element.prototype.animate !== 'function') return false
1464
+ const view = typeof window === 'undefined' ? null : window
1465
+ if (view && typeof view.matchMedia === 'function') {
1466
+ try {
1467
+ if (view.matchMedia('(prefers-reduced-motion: reduce)').matches) return false
1468
+ } catch (err) { /* matchMedia 抛错就当用户没提要求 */ }
1469
+ }
1470
+ return true
1471
+ }
1472
+
1473
+ /**
1474
+ * 算这一帧哪些行是**新来的**、哪些行**走了**(纯函数,测试直接喂它)。
1475
+ *
1476
+ * 「走了」的行带回它上一帧的 `tierKey` / `index` —— 幽灵行要靠这两个值插回原来的位置,
1477
+ * 不能一律塞到列表末尾(那样看起来是「这篇文档跳到了下面然后消失」)。
1478
+ *
1479
+ * ⚠️ 视图整体换掉时(换类型 / 换排序 / 搜索词变了)返回空:那是「换屏」,不是
1480
+ * 「列表里多了一行」,整屏一起飞会很吵(原型里首屏也刻意不播)。
1481
+ * ⚠️ 同一篇**换层**(rel 不变、tierKey 变了)既不算进入也不算离开 —— 这不是「不播」:
1482
+ * 那一行交给 `KnitBody` 里的 FLIP(`motionShift` + 上一帧按 rel 记下的矩形)。跨分区时
1483
+ * React 会重建节点,但位置是按 **rel** 记的,所以它照样能从老位置补间到新位置;
1484
+ * 在这里把它当「进入」反而会让它先闪一下再飞,两段补间会互相打架。
1485
+ *
1486
+ * @param {{view: string, rows: object[]}|null} prev - 上一帧的快照(没提交过就是 null)
1487
+ * @param {string} view - 本帧的视图签名
1488
+ * @param {object[]} rows - 本帧的行表,顺序=屏幕顺序
1489
+ * @returns {{entered: Array<{rel: string, delay: number}>, left: object[]}} 新来的 / 走了的
1490
+ */
1491
+ function planRowMotion(prev, view, rows) {
1492
+ const next = (Array.isArray(rows) ? rows : []).filter((row) => row && row.rel)
1493
+ if (!prev || prev.view !== view) return { entered: [], left: [] }
1494
+ const before = new Map((prev.rows || []).map((row) => [row.rel, row]))
1495
+ const after = new Set(next.map((row) => row.rel))
1496
+ const entered = []
1497
+ let order = 0
1498
+ for (const row of next) {
1499
+ if (before.has(row.rel)) continue
1500
+ entered.push({ rel: row.rel, delay: Math.min(order, MOTION_STAGGER_MAX) * MOTION_STAGGER_MS })
1501
+ order += 1
1502
+ }
1503
+ return {
1504
+ entered,
1505
+ left: (prev.rows || []).filter((row) => row && row.rel && !after.has(row.rel)),
1506
+ }
1507
+ }
1508
+
1509
+ /**
1510
+ * 幸存行这一帧**相对上一帧挪了多远**(FLIP 的第一步:算反方向的位移)。
1511
+ *
1512
+ * 纯函数:喂两个 `{left, top}` 位置(**布局坐标**,见 `rowLayoutPoint`),返回要「拉回来」的
1513
+ * 位移;没得比或者没动过就返回 `null`。
1514
+ *
1515
+ * ⚠️ 阈值不是洁癖:`offsetTop` 也会给亚像素值,浏览器缩放导致的零点几像素抖动如果也排一段
1516
+ * 补间,那一屏会一直有东西在微微地飘。
1517
+ *
1518
+ * @param {{left: number, top: number}|null} prev - 上一帧的位置(没记过就是 null)
1519
+ * @param {{left: number, top: number}|null} now - 这一帧的位置
1520
+ * @param {number} [threshold] - 小于它就算没动(默认 `MOTION_MOVE_EPS`)
1521
+ * @returns {{dx: number, dy: number}|null} 位移(正数=上一帧更靠右下,要往左上拉)
1522
+ */
1523
+ function motionShift(prev, now, threshold = MOTION_MOVE_EPS) {
1524
+ if (!prev || !now) return null
1525
+ const dx = prev.left - now.left
1526
+ const dy = prev.top - now.top
1527
+ if (!Number.isFinite(dx) || !Number.isFinite(dy)) return null
1528
+ if (Math.abs(dx) < threshold && Math.abs(dy) < threshold) return null
1529
+ return { dx, dy }
1530
+ }
1531
+
1532
+ /**
1533
+ * 一行在**列表自己的坐标系**里的位置 —— FLIP 量位置只能用这个。
1534
+ *
1535
+ * ⚠️ 不能拿 `getBoundingClientRect()` 当「位置」:它是**视口坐标**,于是三件与「谁换了位置」
1536
+ * 毫无关系的机械动作都会让整屏的行凭空产生位移 ——
1537
+ * ① 容器滚动(含滚动位置被 clamp);
1538
+ * ② 容器自己的高度 / 顶边变了(预览面板一开一合、头上那块「使用情况」长高一行);
1539
+ * ③ 行上挂着 transform(`.knit-doc:hover{transform:translateX(-2px)}` 是死区 0.5px 的四倍)。
1540
+ * 2026-10-04 交互审用户报的两件事都是它:「我一点它就跳……闪得很快」与「我没有输入任何对话,
1541
+ * 文档列表就开始跳动」。`offsetTop/offsetLeft` 是**布局坐标**:不含滚动、不含 transform,
1542
+ * 容器自己怎么变都不动它。节点拿不到 offset*(测试替身 / 已卸载)时才退回视口矩形,并减掉
1543
+ * 容器那一块,好歹把滚动与容器位移去掉。
1544
+ *
1545
+ * @param {{getBoundingClientRect?: Function, scrollLeft?: number, scrollTop?: number}|null} host - 列表容器
1546
+ * @param {object} el - 行节点
1547
+ * @returns {{left: number, top: number}|null} 布局坐标;量不到就是 null
1548
+ */
1549
+ function rowLayoutPoint(host, el) {
1550
+ if (!el) return null
1551
+ if (Number.isFinite(el.offsetTop) && Number.isFinite(el.offsetLeft)) {
1552
+ return { left: el.offsetLeft, top: el.offsetTop }
1553
+ }
1554
+ if (typeof el.getBoundingClientRect !== 'function') return null
1555
+ const box = el.getBoundingClientRect()
1556
+ if (!box) return null
1557
+ const base = host && typeof host.getBoundingClientRect === 'function'
1558
+ ? host.getBoundingClientRect()
1559
+ : null
1560
+ if (!base) return { left: box.left, top: box.top }
1561
+ return {
1562
+ left: box.left - base.left + (Number.isFinite(host.scrollLeft) ? host.scrollLeft : 0),
1563
+ top: box.top - base.top + (Number.isFinite(host.scrollTop) ? host.scrollTop : 0),
1564
+ }
1565
+ }
1566
+
1567
+ /**
1568
+ * 给这一帧**挪了位置**的幸存行排 FLIP,并返回这一帧的位置表留给下一帧。
1569
+ *
1570
+ * 换层(同一个 rel 从「包外」升进「Primary」)与区内重排都走这里。位置按 **rel** 记 ——
1571
+ * 跨分区时 React 会重建节点,老节点量到的位置照样能用在新节点上。
1572
+ *
1573
+ * ⚠️ 调用点必须是**提交之后**、绘制之前的 layout effect,而且在 `DocRow` 的进 / 出补间
1574
+ * **之后**(React 是子先父后):那一刻新行已经是 0 高、幽灵行还占着原高度,所以这里
1575
+ * 量到的位移就只剩「真的挪了位置」的行,不会和进 / 出补间算两遍。
1576
+ * ⚠️ `skip` 里的行(正在进 / 出的)一个都不碰:它们有自己的补间;幽灵行连数据都没有。
1577
+ * ⚠️ 只补 `transform`,不碰高度 —— 高度是进 / 出补间的事,两处都改会互相踩。
1578
+ *
1579
+ * @param {{querySelectorAll: Function}|null} host - 列表容器(`.knit-list`)
1580
+ * @param {Map<string, {left: number, top: number}>} before - 上一帧的位置表(按 rel,布局坐标)
1581
+ * @param {Set<string>} [skip] - 这一帧正在进 / 出的 rel
1582
+ * @returns {Map<string, {left: number, top: number}>} 这一帧的位置表(按 rel,布局坐标)
1583
+ */
1584
+ function applyRowFlips(host, before, skip) {
1585
+ const after = new Map()
1586
+ const was = before instanceof Map ? before : new Map()
1587
+ const nodes = host && typeof host.querySelectorAll === 'function'
1588
+ ? host.querySelectorAll('.knit-doc[data-knit-rel]') : []
1589
+ for (const el of nodes) {
1590
+ const rel = el && typeof el.getAttribute === 'function' ? el.getAttribute('data-knit-rel') : null
1591
+ if (!rel || (skip && skip.has(rel))) continue
1592
+ const point = rowLayoutPoint(host, el)
1593
+ if (!point) continue
1594
+ const shift = motionShift(was.get(rel), point)
1595
+ if (shift && typeof el.animate === 'function') {
1596
+ const anim = el.animate([
1597
+ { transform: `translate(${shift.dx}px, ${shift.dy}px)` },
1598
+ { transform: 'translate(0px, 0px)' },
1599
+ ], { duration: MOTION_MOVE_MS, easing: MOTION_EASE })
1600
+ if (anim && anim.finished && typeof anim.finished.catch === 'function') anim.finished.catch(() => {})
1601
+ }
1602
+ after.set(rel, { left: point.left, top: point.top })
1603
+ }
1604
+ return after
1605
+ }
1606
+
1607
+ /**
1608
+ * 把要「离开」的行插回它们**原来的位置**(纯函数)。
1609
+ *
1610
+ * 位置是上一帧记下来的 `index` —— 不插回原位的话,看到的会是「这篇文档跳到了列表
1611
+ * 末尾才消失」。数据里已经有同一篇时跳过:那一行还活着(比如它只是换了层),
1612
+ * 不该在同一区里再多出一个幽灵。
1613
+ *
1614
+ * @param {object[]} docs - 这一区这一帧的数据
1615
+ * @param {object[]} ghosts - 全部要离开的行(`{rel, doc, tierKey, index}`)
1616
+ * @param {string} tierKey - 哪一个区(分层视图=层名,平铺 / 「全部」各一个常量)
1617
+ * @returns {object[]} 带幽灵行的新数组(这一区没幽灵时原样返回)
1618
+ */
1619
+ function mergeGhostRows(docs, ghosts, tierKey) {
1620
+ const mine = []
1621
+ for (const ghost of Array.isArray(ghosts) ? ghosts : []) {
1622
+ if (ghost && ghost.tierKey === tierKey) mine.push(ghost)
1623
+ }
1624
+ if (mine.length === 0) return docs
1625
+ mine.sort((a, b) => a.index - b.index)
1626
+ const out = docs.slice()
1627
+ for (const ghost of mine) {
1628
+ if (out.some((doc) => doc.rel === ghost.rel)) continue
1629
+ out.splice(Math.min(ghost.index, out.length), 0, { ...ghost.doc, knitLeaving: true })
1630
+ }
1631
+ return out
1632
+ }
1633
+
1634
+ function DocRow({ doc, now, active, cursor, relevance, why, num, mark, primary, life,
1635
+ onSelect, onOpenTab, optionId, entering, leaving }) {
1348
1636
  const fresh = now - doc.mtimeMs < NEW_WINDOW_MS
1637
+ const rowRef = React.useRef(null)
1638
+
1639
+ /* 进 / 出两段补间都跑在 **layout effect** 里:放到 paint 之后会先闪一帧完整高度的
1640
+ 行,那正是用户抱怨的那一下。没有 DOM 时 `motionAllowed()` 直接挡掉。 */
1641
+ React.useLayoutEffect(() => {
1642
+ if (!motionAllowed()) return
1643
+ const el = rowRef.current
1644
+ if (!el || typeof el.getBoundingClientRect !== 'function') return
1645
+ const box = el.getBoundingClientRect()
1646
+ const height = box && box.height > 0 ? box.height : 0
1647
+ if (height <= 0) return
1648
+ // 量的高度是 border-box,补间也得按 border-box 算,否则第一帧会把行撑高一个内边距。
1649
+ el.style.boxSizing = 'border-box'
1650
+ if (leaving) {
1651
+ // 离开:高度收到 0,同时**自上而下**擦掉(clip-path 的 top 从 0 涨到 100%),
1652
+ // 末尾补一点模糊 —— 与原型里那条 mask 擦除是同一个读法。
1653
+ el.style.overflow = 'hidden'
1654
+ const anim = el.animate([
1655
+ { height: `${height}px`, clipPath: 'inset(0% 0 0 0)', opacity: 1, filter: 'blur(0px)' },
1656
+ { height: `${height * 0.55}px`, clipPath: 'inset(45% 0 0 0)', opacity: 0.7, filter: 'blur(1px)', offset: 0.55 },
1657
+ { height: '0px', clipPath: 'inset(100% 0 0 0)', opacity: 0, filter: 'blur(2px)' },
1658
+ ], { duration: MOTION_EXIT_MS, easing: MOTION_EASE, fill: 'forwards' })
1659
+ if (anim && anim.finished && typeof anim.finished.catch === 'function') anim.finished.catch(() => {})
1660
+ return
1661
+ }
1662
+ if (entering === null || entering === undefined) return
1663
+ // 进入:先把高度收成 0 再补间到自然高度 —— 下面的行是被**挤**下去的,不是跳下去的
1664
+ // (原型里踩过的坑:不先量自然高度,插入瞬间会把下面那行蹬一下)。
1665
+ el.style.overflow = 'hidden'
1666
+ const anim = el.animate([
1667
+ { height: '0px', transform: 'translateY(26px)', opacity: 0, filter: 'blur(3px)' },
1668
+ { height: `${height}px`, transform: 'translateY(0)', opacity: 1, filter: 'blur(0px)' },
1669
+ ], { duration: MOTION_ENTER_MS, delay: entering, easing: MOTION_EASE, fill: 'both' })
1670
+ const done = anim && anim.finished
1671
+ if (done && typeof done.then === 'function') {
1672
+ done.then(() => { el.style.height = ''; el.style.overflow = '' }).catch(() => {})
1673
+ } else {
1674
+ el.style.height = ''
1675
+ el.style.overflow = ''
1676
+ }
1677
+ })
1349
1678
 
1350
1679
  return h('div', {
1351
- className: `knit-doc${active ? ' active' : ''}${cursor ? ' cursor' : ''}${fresh ? ' fresh' : ''}`,
1680
+ className: `knit-doc${active ? ' active' : ''}${cursor ? ' cursor' : ''}${fresh ? ' fresh' : ''}${leaving ? ' leaving' : ''}`,
1681
+ ref: rowRef,
1352
1682
  // listbox 的选项语义:有 role 才能被读成「N 项中的第 i 项」,
1353
1683
  // 有 aria-selected 才能播报「当前选中」。
1354
1684
  role: 'option',
1355
1685
  id: optionId,
1356
1686
  'aria-selected': active ? 'true' : 'false',
1687
+ // 「正在离开」的幽灵行已经不在数据里了(点不动、键盘也到不了),
1688
+ // 只是占着位置把高度收掉 —— 别让它被读成一项。
1689
+ 'aria-hidden': leaving ? 'true' : undefined,
1357
1690
  'data-knit-rel': doc.rel,
1358
1691
  title: t('row.tooltip', { path: doc.rel }),
1359
1692
  onClick: () => onSelect(doc),
@@ -1363,9 +1696,12 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1363
1696
  // 用户原话:「文档列表序号放在独立最左边,其他数据放在右边」。所以序号从行一里
1364
1697
  // 搬了出来,成为 .knit-doc 这条两列 grid 的第一列,其余数据全在右边堆叠。
1365
1698
  // v0.14(Design §11):只有 Context Pack 前三层的条目有号;「其他相关文档」里的
1366
- // 没有 —— 那些不属于这个包,编号会把它们谎报成包的一部分。**没有号时整个节点不渲染**,
1367
- // 左边那一列由 grid 轨道保着(正文照样和有条目的行对齐,不会左移)。
1368
- num ? h('span', { className: 'knit-num' }, String(num).padStart(2, '0')) : null,
1699
+ // 没有 —— 那些不属于这个包,编号会把它们谎报成包的一部分。
1700
+ // 2026-10-01:**不再「没有号就整个节点不渲染」**。这一屏里有号时(`mark`,由
1701
+ // `docsGrid` 下发),这一列放一个中性占位标记,否则空着的那一格会被读成漏了一个号。
1702
+ // 整屏没号(时间序 / 平铺列表)时 `mark` 为假 —— 一个标记都不渲染。
1703
+ num ? h('span', { className: 'knit-num' }, String(num).padStart(2, '0'))
1704
+ : (mark ? h('span', { className: 'knit-gapmark', 'aria-hidden': 'true' }, '·') : null),
1369
1705
  // 右边这一列=其余全部数据。列位置由 .knit-body 的 grid-column 定死 ——
1370
1706
  // 靠自动排布的话,没有序号时正文会掉进第一列。
1371
1707
  h('div', { className: 'knit-body' },
@@ -1379,6 +1715,13 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1379
1715
  h('div', { className: 'knit-title' },
1380
1716
  fresh ? h('span', { className: 'knit-badge' }, '🆕') : null,
1381
1717
  doc.title || doc.name),
1718
+ // v0.17:生命周期状态(文案已算好;没有证据时是 null,一个节点都不加)。
1719
+ // 插在**标题与时间之间**:`.knit-title` 是 flex:1 1 auto,会把状态与时间一起推到
1720
+ // 行尾,状态在时间左侧、行尾仍然是时间。
1721
+ // ⚠️ 状态是**纯文字**:不加图标、不加底色、不加边框、不用红绿表达好坏 ——
1722
+ // 它陈述事实,不是评分(AGENTS.md §6.2 / PRD §7.3)。字号比标题弱一档,
1723
+ // 永远不抢标题。
1724
+ life ? h('span', { className: 'knit-life' }, life) : null,
1382
1725
  // 时间在标题右边的行尾 —— 靠 .knit-title 的 flex-grow 推过去,不是靠 margin。
1383
1726
  h('div', { className: 'knit-time' }, relTime(doc.mtimeMs, now))),
1384
1727
  doc.summary
@@ -1386,8 +1729,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1386
1729
  : h('div', { className: 'knit-sum empty' }, t('summary.empty')),
1387
1730
  // ⚠️ **列表行里不再有路径**(2026-09-29 用户要求):「文档列表中的文档路径,我觉得
1388
1731
  // 不需要出现了,因为点开查看文档详情的时候已经有了,所以这里是重复的,隐藏掉」。
1389
- // —— 这是**重复信息**,不是「多列砍字段」那种静默降级:预览头的面包屑
1390
- // (`.knit-preview-path`:目录浅 + 文件名亮,还可点)始终显示完整路径。
1732
+ // —— 这是**重复信息**,不是「多列砍字段」那种静默降级:预览头
1733
+ // (`.knit-preview-path`:目录收敛成 `…/` + 文件名亮,还可点)已经能定位到是哪一篇,
1734
+ // 完整相对路径在它的悬停提示里。
1391
1735
  // 所以删掉的是 `.knit-meta` 这一个节点,**摘要仍然任何情况下都不许 display:none**。
1392
1736
  // 行的定位不走可见路径:`data-knit-rel` 仍在(键盘 / 预览映射靠它)。
1393
1737
  // v0.14:为什么这一篇在这个层里。只有 Context Pack 的条目才有 ——
@@ -1574,13 +1918,22 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1574
1918
 
1575
1919
  return h('div', {
1576
1920
  className: 'knit-preview',
1577
- style: fullscreen ? undefined : { maxHeight: `${Math.round(ratio * 100)}%` },
1921
+ /* ⚠️ 高度**打开期间是固定的**(= 拖出来的那个比例),不是 `maxHeight`(2026-10-04 交互审)。
1922
+ 原来是 `maxHeight: 46%` ⇒ 面板高度由**内容**决定,于是:
1923
+ ① 点一篇 → 先出「加载中」(一两行高),正文到了再窜到 46% ⇒ 列表跟着一伸一缩;
1924
+ ② 在预览里点「相关文档」换一篇 ⇒ 正文长短变了 ⇒ 列表又跟着一伸一缩。
1925
+ 用户的原话是「我选中一个文档查看全文……我一点它就跳,我一点它就很跳,闪的很快」。
1926
+ 固定高度之后这两次几何变化一次都不发生:加载中 / 换篇都不再改动列表的高度,
1927
+ 长文照样在 `.knit-preview-body` 里滚(它本来就是 `overflow-y:auto`)。
1928
+ 短文档会因此下方留白 —— 这是拿「点一下不跳」换来的,别再改回 maxHeight。 */
1929
+ style: fullscreen ? undefined : { height: `${Math.round(ratio * 100)}%` },
1578
1930
  },
1579
1931
  fullscreen ? null : h('div', { className: 'knit-resize', onPointerDown: onResizeStart, title: t('preview.resizeTitle') }),
1580
1932
  h('div', { className: 'knit-preview-head' },
1581
- // 路径面包屑,**可点**:用系统默认应用打开这篇本地文档 —— 阅读时多一个
1933
+ // 路径,**可点**:用系统默认应用打开这篇本地文档 —— 阅读时多一个
1582
1934
  // 「跳到本地」的入口。不放标题:正文 H1 已经写了,重复会让
1583
1935
  // 「列表行 / 预览头 / 正文」出现三遍同一个词,反而分不清哪块是详情。
1936
+ // 目录收敛成 `…/`(2026-10-01 用户要求),完整相对路径在 title 里。
1584
1937
  h('button', {
1585
1938
  type: 'button',
1586
1939
  className: 'knit-preview-path',
@@ -1589,7 +1942,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1589
1942
  onClick: () => { if (onOpenLocal) onOpenLocal() },
1590
1943
  },
1591
1944
  previewPath.dir
1592
- ? h('span', { className: 'knit-preview-dir' }, previewPath.dir)
1945
+ ? h('span', { className: 'knit-preview-dir' }, '…/')
1593
1946
  : null,
1594
1947
  h('span', { className: 'knit-preview-name' }, previewPath.name)),
1595
1948
  h('button', {
@@ -1597,9 +1950,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1597
1950
  onClick: onToggleFullscreen,
1598
1951
  title: fullscreen ? t('preview.exitFullscreenTitle') : t('preview.fullscreenTitle'),
1599
1952
  }, fullscreen ? t('preview.exitFullscreen') : t('preview.fullscreen')),
1600
- // 「在本地打开」= 之前那个「新标签页」的位置(v0.10)。
1953
+ // 「本地打开」= 之前那个「新标签页」的位置(v0.10)。
1601
1954
  // 「新标签页」开的是官方文档预览,但面板里已经有就地预览,重复度高、用得少;
1602
- // 而「用默认应用打开这篇文档」原本只藏在路径面包屑的悬停提示里 ——
1955
+ // 而「用默认应用打开这篇文档」原本只藏在路径的悬停提示里 ——
1603
1956
  // 把值钱的那个放到显眼处,把鸡肋的那个让位(双击列表行仍能开新标签页)。
1604
1957
  h('button', {
1605
1958
  className: 'knit-btn',
@@ -1620,11 +1973,13 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1620
1973
  /**
1621
1974
  * 面板主体。两个宿主共用。
1622
1975
  *
1623
- * @param {{sessionId?:string, openInTab?:Function}} props - 渲染入参。
1976
+ * @param {{sessionId?:string, openInTab?:Function, visible?:boolean}} props - 渲染入参。
1624
1977
  * `openInTab(doc)` 返回空串表示成功,返回文案表示失败原因。
1978
+ * `visible === false` 表示宿主那边这块面板**看不见**(官方右侧栏收起 / 不是当前标签)——
1979
+ * 那时一次都不取数、也不落状态(见下)。
1625
1980
  * @returns {import('react').ReactElement} 元素
1626
1981
  */
1627
- function KnitBody({ sessionId, openInTab }) {
1982
+ function KnitBody({ sessionId, openInTab, visible }) {
1628
1983
  ensureStyle()
1629
1984
 
1630
1985
  const [notice, setNotice] = React.useState('')
@@ -1632,7 +1987,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1632
1987
  // 紧跟 sort:测试按 hook 顺序预置前两位(notice/sort),kind 放第三位不影响老用例。
1633
1988
  const [kind, setKind] = React.useState(readKindPref)
1634
1989
  const [state, setState] = React.useState({
1635
- status: 'loading', docs: [], root: '', total: 0, error: '', mode: 'time', topic: '',
1990
+ status: 'loading', docs: [], root: '', total: 0, error: '', mode: 'time',
1636
1991
  // v0.14:当前任务上下文(Context Pack)。宿主只在「文档档 + 相关序 + 有命中」时给,
1637
1992
  // 其余情形是 null —— 那时面板退回它一直在用的平铺列表(行为与 v0.13 逐字一致)。
1638
1993
  context: null,
@@ -1664,6 +2019,12 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1664
2019
  // 的顺序被测试按位预置,别插队。
1665
2020
  const [usageOn, setUsageOn] = React.useState(readUsagePref)
1666
2021
 
2022
+ // v0.17:两个折叠块的开合状态(上下文外读取 / 最近一次变化)。
2023
+ // **纯瞬时 UI 状态** —— 不写 pref、不进 `dsh-knit:*` 存储,刷新即回默认(收起)。
2024
+ // 仍然放在最后:前面那些 hook 的位置被测试按位预置,别插队。
2025
+ const [gapOpen, setGapOpen] = React.useState(false)
2026
+ const [deltaOpen, setDeltaOpen] = React.useState(false)
2027
+
1667
2028
  /* ── 曾经在这里的三个状态 + 一个 ref:右栏的形态 ──────────
1668
2029
  `packWidth`(310) / `packFloat`(null) / `packSnap`(false) / `packColRef`。
1669
2030
  **2026-09-29 随右栏一起删除**。当时它们**只存在内存里**(刷新回默认值),
@@ -1683,9 +2044,16 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1683
2044
  return () => observer.disconnect()
1684
2045
  }, [])
1685
2046
 
1686
- const load = React.useCallback(async () => {
2047
+ /* 官方右侧栏收起之后,标签身体**仍然挂着**(dockkit 的 `keepMounted`),v0.16 之前
2048
+ 这里照旧每 5 秒敲一次 `/knit/api/recent` 并 `setState`:白烧一次全工作区扫描,
2049
+ 还往宿主正在收起的那层 DOM 里插一帧重渲染。现在取数先问一句「还看得见吗」,看不见
2050
+ **连请求都不发**;请求在途时被折叠的那一次,回来也不落状态(`alive` 由轮询的
2051
+ cleanup 翻假)。重新可见时那个 effect 会重跑 ⇒ 立刻补一次,不必等下一个 5 秒。 */
2052
+ const load = React.useCallback(async (alive) => {
2053
+ const live = () => typeof alive !== 'function' || alive()
2054
+ if (!live()) return
1687
2055
  if (!sessionId) {
1688
- setState({ status: 'error', docs: [], root: '', total: 0, error: t('error.noSession'), mode: 'time', topic: '', context: null })
2056
+ setState({ status: 'error', docs: [], root: '', total: 0, error: t('error.noSession'), mode: 'time', context: null })
1689
2057
  return
1690
2058
  }
1691
2059
  try {
@@ -1694,6 +2062,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1694
2062
  const url = `${LIST_API}?sessionId=${encodeURIComponent(sessionId)}&limit=40&sort=${sort}&kind=${kind}${usageOn ? '&usage=1' : ''}`
1695
2063
  const res = await fetch(url, { headers: { accept: 'application/json' }, cache: 'no-store' })
1696
2064
  const data = await res.json()
2065
+ if (!live()) return
1697
2066
  if (data && data.ok) {
1698
2067
  setState({
1699
2068
  status: 'ready',
@@ -1702,30 +2071,33 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1702
2071
  total: data.total || 0,
1703
2072
  error: '',
1704
2073
  mode: data.mode || 'time',
1705
- topic: data.topic || '',
1706
2074
  context: data.context || null,
1707
2075
  usage: data.usage || null,
1708
2076
  })
1709
2077
 
1710
2078
  } else {
1711
- setState({ status: 'error', docs: [], root: '', total: 0, error: hostMessage(data), mode: 'time', topic: '', context: null, usage: null })
2079
+ setState({ status: 'error', docs: [], root: '', total: 0, error: hostMessage(data), mode: 'time', context: null, usage: null })
1712
2080
  }
1713
2081
  } catch (error) {
1714
- setState({ status: 'error', docs: [], root: '', total: 0, error: String((error && error.message) || error), mode: 'time', topic: '', context: null, usage: null })
2082
+ if (!live()) return
2083
+ setState({ status: 'error', docs: [], root: '', total: 0, error: String((error && error.message) || error), mode: 'time', context: null, usage: null })
1715
2084
  }
1716
2085
  setTick(Date.now())
1717
2086
  }, [sessionId, sort, kind, usageOn])
1718
2087
 
1719
2088
  React.useEffect(() => {
2089
+ // 看不见就一个定时器都不挂:`visible` 变回 true 时本 effect 重跑,立刻 load 一次。
2090
+ if (visible === false) return undefined
1720
2091
  let alive = true
1721
2092
  let timer = null
2093
+ const isAlive = () => alive
1722
2094
  const run = async () => {
1723
- await load()
2095
+ await load(isAlive)
1724
2096
  if (alive) timer = setTimeout(run, POLL_MS)
1725
2097
  }
1726
2098
  run()
1727
2099
  return () => { alive = false; if (timer) clearTimeout(timer) }
1728
- }, [load])
2100
+ }, [load, visible])
1729
2101
 
1730
2102
  /* ── 过滤:纯客户端,不重新请求宿主 ─────────────── */
1731
2103
  const visibleDocs = React.useMemo(() => {
@@ -1769,10 +2141,16 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1769
2141
  * 把「这一组的条目」映射成带序号 / Primary 标记的 `DocRow`。
1770
2142
  *
1771
2143
  * ⚠️ `num` 只有 Context Pack 前三层才有(见 `renderEntry` 的说明):
1772
- * 时间序、筛选结果、「其他相关文档」都不编号。
2144
+ * 时间序、筛选结果、「其他相关文档」都不编号 —— 但**这一屏里有号时**,没号的行会在
2145
+ * 同一列拿到 `mark`(渲染 `.knit-gapmark` 占位),算法见下面。
1773
2146
  */
1774
- const docsGrid = (docs, numbers, primary) => docs.map((doc) =>
1775
- renderEntry(doc, numbers ? numbers.get(doc.rel) || 0 : 0, Boolean(primary)))
2147
+ const docsGrid = (docs, numbers, primary, withLife) => {
2148
+ // 一屏里「要么都有号、要么都没有」(2026-10-01):只要这个视图里存在序号,
2149
+ // 没号的那些行(「其他相关文档」)就在同一列渲染占位标记;整屏没号时不渲染。
2150
+ const mark = Boolean(numbers && numbers.size > 0)
2151
+ return docs.map((doc) =>
2152
+ renderEntry(doc, numbers ? numbers.get(doc.rel) || 0 : 0, Boolean(primary), mark, withLife))
2153
+ }
1776
2154
 
1777
2155
  const relevance = state.mode === 'relevance'
1778
2156
  const filtering = query.trim().length > 0
@@ -1800,7 +2178,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1800
2178
  h('div', { className: 'knit-tierline', role: 'presentation' },
1801
2179
  h('span', { className: 'knit-tiername' }, t(section.titleKey)),
1802
2180
  section.hintKey ? h('span', { className: 'knit-tierhint' }, t(section.hintKey)) : null),
1803
- docsGrid(section.docs, view.numbers, section.key === 'primary')))
2181
+ // ⚠️ 幽灵行(正在离开的)也走 `docsGrid`,所以它照样是一个 `.knit-doc` ——
2182
+ // 会被 `byClass` 数到,但**不在** `navDocs` 里(键盘与 cursor 都到不了)。
2183
+ docsGrid(withGhosts(section.key, section.docs), view.numbers, section.key === 'primary', true)))
1804
2184
 
1805
2185
  /* ── 曾经在这里的一个函数:`contextPanel` ─────────────────
1806
2186
  它渲染右栏那三样东西(当前任务原文 / 「命中 N 篇」/ 三条证据行)。
@@ -1885,15 +2265,23 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
1885
2265
  if (!navDocs.some((doc) => doc.rel === cursor)) setCursor(navDocs[0].rel)
1886
2266
  }, [navDocs, cursor])
1887
2267
 
1888
- // 键盘焦点跟手滚进视口(测试环境没有 DOM,静默跳过)
2268
+ /* 键盘焦点跟手滚进视口(测试环境没有 DOM,静默跳过)。
2269
+ ⚠️ 2026-10-04(交互审的那个 bug):这里曾经把 `state.docs` 也放进依赖里,而那是**每 5 秒
2270
+ 轮询一次的新数组** —— 于是「刷新到了新数据」被当成了「用户按了方向键」。光标默认落在第一行,
2271
+ 用户往下滚过之后那一行必然不在视口里 ⇒ 列表每 5 秒被拽回第一行一次,用户的原话是
2272
+ 「我没有输入任何的对话……文档列表就开始跳动」。滚动**只在光标真的换了**(或搜索词变了)时发生,
2273
+ 而且只在列表拿着键盘焦点时发生 —— 这条服务的是键盘导航;鼠标点过 / 悬停过的行本来就在视口里,
2274
+ 而「数据刷新」一次都不该动列表。 */
1889
2275
  React.useEffect(() => {
1890
2276
  if (!cursor || typeof document === 'undefined') return
1891
2277
  const host = listRef.current
1892
2278
  if (!host || typeof host.querySelector !== 'function') return
2279
+ const active = document.activeElement
2280
+ if (active !== host && !(active && host.contains && host.contains(active))) return
1893
2281
  const escaped = typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(cursor) : cursor
1894
2282
  const el = host.querySelector(`[data-knit-rel="${escaped}"]`)
1895
2283
  if (el && typeof el.scrollIntoView === 'function') el.scrollIntoView({ block: 'nearest' })
1896
- }, [cursor, query, state.docs])
2284
+ }, [cursor, query])
1897
2285
 
1898
2286
  // 预览高度:拖完就记住
1899
2287
  React.useEffect(() => { writePref(RATIO_KEY, String(ratio)) }, [ratio])
@@ -2150,8 +2538,150 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2150
2538
 
2151
2539
 
2152
2540
 
2153
- /** 渲染一个条目:媒体一律出方形卡片(媒体视图与「全部」的媒体区共用),其余出文档行。 */
2154
- const renderEntry = (doc, num, primary) => {
2541
+ /**
2542
+ * v0.17:这一篇当前的**事实状态**,文案已按语言算好(没有证据时是 null)。
2543
+ *
2544
+ * ⚠️ 只有「使用情况」开着、并且宿主真的回传了 `usage` 时才有文案 —— 关掉时
2545
+ * 一个状态节点都不渲染,DOM 与 v0.16 逐字一致。
2546
+ * ⚠️ `lifecycle` 里没有这篇 = 本会话没有一次成功 read ⇒ 未读。这是事实陈述,
2547
+ * 不是「你漏了它」的提醒,更不许写成「Agent 忽略了它」(PRD §8)。
2548
+ * ⚠️ 状态值本身是英文(数据层只有一个口径),中文只存在于词典(§15.4 / §24)。
2549
+ *
2550
+ * @param {string} rel - 相对路径
2551
+ * @returns {string|null} 状态文案
2552
+ */
2553
+ const lifecycleLabel = (rel) => {
2554
+ if (!usageOn) return null
2555
+ const usageNow = state.usage
2556
+ if (!usageNow || !usageNow.stats) return null
2557
+ const row = usageNow.lifecycle && usageNow.lifecycle[rel]
2558
+ const status = row ? row.status : 'unread'
2559
+ if (status === 'unread') return t('lifecycle.unread')
2560
+ if (status === 'read') {
2561
+ return row && row.count >= 2 ? t('lifecycle.readCount', { n: row.count }) : t('lifecycle.read')
2562
+ }
2563
+ if (status === 'updated_after_read') return t('lifecycle.updatedAfterRead')
2564
+ if (status === 'reread_after_update') return t('lifecycle.rereadAfterUpdate')
2565
+ return null
2566
+ }
2567
+
2568
+ /* ── 列表进出动效:这一帧谁新来了、谁走了 ─────────────────────────
2569
+ (参数与手感见模块级 `planRowMotion` / `MOTION_*` 那段注释。)
2570
+
2571
+ ⚠️ 渲染期**只读** `motionRef`,落盘与计时器都在下面的 layout effect 里 ——
2572
+ 并发渲染下这一帧可能根本没提交,渲染里写 ref 会把幽灵行记进一个被丢掉的帧。 */
2573
+ const motionRef = React.useRef({
2574
+ committed: null,
2575
+ ghosts: new Map(),
2576
+ timers: new Map(),
2577
+ positions: new Map(),
2578
+ // 位置表是在**哪一屏**量下来的(视图签名)。换屏时必须整表作废:见下面 settled 那条。
2579
+ view: '',
2580
+ // 进 / 出补间还在飞的截止时刻(毫秒时间戳)。那段时间里行高是中间态,量不得。
2581
+ tweenUntil: 0,
2582
+ })
2583
+ const [, setMotionSeq] = React.useState(0)
2584
+ const motionOn = motionAllowed()
2585
+ // 视图签名:换类型 / 换排序 / 搜索词变了都算「换屏」——整屏一起飞会很吵。
2586
+ const motionView = `${kind}|${state.mode}|${query.trim()}`
2587
+ // 只列**真会渲染成 .knit-doc 的行**,顺序=屏幕顺序(幽灵行要按这个位置插回去)。
2588
+ const motionRows = (() => {
2589
+ if (state.status === 'error' || state.docs.length === 0 || visibleDocs.length === 0) return []
2590
+ if (kind === KIND_MEDIA) return [] // 媒体格子不参与:网格里收起高度没有意义
2591
+ 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 }))
2595
+ }
2596
+ if (contextView) {
2597
+ const rows = []
2598
+ for (const section of contextView.sections) {
2599
+ section.docs.forEach((doc, index) => rows.push(
2600
+ { rel: doc.rel, tierKey: section.key, index, doc }))
2601
+ }
2602
+ return rows
2603
+ }
2604
+ return visibleDocs.map((doc, index) => (
2605
+ { rel: doc.rel, tierKey: MOTION_TIER_FLAT, index, doc }))
2606
+ })()
2607
+ const motion = (() => {
2608
+ const live = new Set(motionRows.map((row) => row.rel))
2609
+ const plan = motionOn
2610
+ ? planRowMotion(motionRef.current.committed, motionView, motionRows)
2611
+ : { entered: [], left: [] }
2612
+ const ghosts = new Map()
2613
+ if (motionOn) {
2614
+ // 上一帧留下的幽灵,这一帧还不在数据里 ⇒ 继续收着(同一篇回来了就撤掉)。
2615
+ for (const [rel, ghost] of motionRef.current.ghosts) if (!live.has(rel)) ghosts.set(rel, ghost)
2616
+ for (const row of plan.left) {
2617
+ if (ghosts.has(row.rel)) continue
2618
+ ghosts.set(row.rel, { rel: row.rel, doc: row.doc, tierKey: row.tierKey, index: row.index })
2619
+ }
2620
+ }
2621
+ return { entered: new Map(plan.entered.map((row) => [row.rel, row.delay])), ghosts, live }
2622
+ })()
2623
+ React.useLayoutEffect(() => {
2624
+ const store = motionRef.current
2625
+ store.committed = motionOn && motionRows.length > 0 ? { view: motionView, rows: motionRows } : null
2626
+ store.ghosts = motion.ghosts
2627
+ for (const [rel, timer] of store.timers) {
2628
+ if (motion.ghosts.has(rel)) continue
2629
+ clearTimeout(timer)
2630
+ store.timers.delete(rel)
2631
+ }
2632
+ for (const rel of motion.ghosts.keys()) {
2633
+ if (store.timers.has(rel)) continue
2634
+ // 补间跑完(外加一点交错余量)就把幽灵行摘掉 —— 摘的时候高度已经是 0,
2635
+ // 所以下面的行不会再跳一下。
2636
+ const timer = setTimeout(() => {
2637
+ store.timers.delete(rel)
2638
+ if (!store.ghosts.has(rel)) return
2639
+ const next = new Map(store.ghosts)
2640
+ next.delete(rel)
2641
+ store.ghosts = next
2642
+ setMotionSeq((n) => n + 1)
2643
+ }, MOTION_EXIT_MS + MOTION_STAGGER_MS)
2644
+ store.timers.set(rel, timer)
2645
+ }
2646
+ /* ── 活下来的行换了位置:FLIP(算法在模块级 `applyRowFlips`)────
2647
+ 正在进 / 出的行不参与:它们有自己的补间(幽灵行连数据都没有,别去量)。
2648
+
2649
+ ⚠️ 另外两种时候**一个都不量**(2026-10-04 交互审那两个 bug 的正主):
2650
+ ① **换屏**(视图签名变了):那是「整屏换了一批内容」,不是「列表里有人挪了位置」。
2651
+ `planRowMotion` 对换屏就是不播,FLIP 却会照两张布局的差把每一行都补一遍 ——
2652
+ 换排序 / 第一次拿到数据 / 搜索词一变,整屏一起飞。
2653
+ ② **进 / 出补间还在飞**:那几百毫秒里行高在 0 与自然高之间,量到的全是中间态。
2654
+ 拿中间态当基准,等补间落地后下一帧就把这段位移当成「有人挪了位置」再补一遍 ——
2655
+ 一屏就这么飘起来(而且会一直飘:每次进 / 出都留下一个错基准)。
2656
+ 两种时候都把位置表**清空**(不是照记):清空等于「没有上一帧可比」,下一帧只会安静
2657
+ 落位、不补间;等落地后再量一帧,基准就又是干净的了。 */
2658
+ const tweening = store.tweenUntil > Date.now()
2659
+ if (motion.entered.size > 0 || motion.ghosts.size > 0) {
2660
+ // 取较长的那一套(进入 + 一点交错余量),离开比它短,等它一定够了。
2661
+ store.tweenUntil = Date.now() + MOTION_ENTER_MS + MOTION_STAGGER_MS
2662
+ }
2663
+ const skip = new Set([...motion.entered.keys(), ...motion.ghosts.keys()])
2664
+ const settled = motionOn
2665
+ && motionRows.length > 0
2666
+ && !tweening
2667
+ && motion.entered.size === 0
2668
+ && motion.ghosts.size === 0
2669
+ && store.view === motionView
2670
+ store.positions = settled ? applyRowFlips(listRef.current, store.positions, skip) : new Map()
2671
+ store.view = motionView
2672
+ })
2673
+ React.useEffect(() => () => {
2674
+ for (const timer of motionRef.current.timers.values()) clearTimeout(timer)
2675
+ motionRef.current.timers.clear()
2676
+ }, [])
2677
+ /** 把这一帧要「离开」的行按原位插回去(只在真机上会非空,逻辑在 `mergeGhostRows`)。 */
2678
+ const withGhosts = (tierKey, docs) =>
2679
+ mergeGhostRows(docs, [...motion.ghosts.values()], tierKey)
2680
+
2681
+ /** 渲染一个条目:媒体一律出方形卡片(媒体视图与「全部」的媒体区共用),其余出文档行。
2682
+ * `withLife` 只有**分层视图**(Context Pack 三层 + 其他相关文档)才给真 —— 时间序、
2683
+ * 筛选结果、「全部」都不显示生命周期:那一屏说的不是「这个包里的文档现在什么状态」。 */
2684
+ const renderEntry = (doc, num, primary, mark, withLife) => {
2155
2685
  const common = {
2156
2686
  key: doc.path || doc.rel,
2157
2687
  doc,
@@ -2166,7 +2696,13 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2166
2696
  // `whyText` 只认 Context Pack 条目上挂的 `reason` —— 平铺列表里没有这个字段,
2167
2697
  // 于是返回空串,那一行不渲染。
2168
2698
  // `num` / `primary` 只有分层视图会传(Design §11 / §13);平铺列表照旧无序号。
2169
- return h(DocRow, { ...common, relevance, why: whyText(doc.reason), num, primary })
2699
+ // `mark`=没号时同列的占位标记,只在「这一屏里有号」时为真。
2700
+ // 进出动效只在真机上跑(`motionOn`):测试替身没有 DOM,`motionAllowed()` 挡掉,
2701
+ // 于是渲染树里既没有 `entering` 也没有 `leaving`,与没有这段动效时逐字一致。
2702
+ return h(DocRow, { ...common, relevance, why: whyText(doc.reason), num, mark, primary,
2703
+ life: withLife ? lifecycleLabel(doc.rel) : null,
2704
+ entering: motion.entered.has(doc.rel) ? motion.entered.get(doc.rel) : null,
2705
+ leaving: Boolean(doc.knitLeaving) })
2170
2706
  }
2171
2707
 
2172
2708
  /** 「全部」的分区标题:类型名 + 「已显示 / 总数」+ 被截断时的「查看全部」。 */
@@ -2188,7 +2724,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2188
2724
  const allSections = [
2189
2725
  docItems.length === 0 ? null : h('div', { className: 'knit-section', key: 'docs' },
2190
2726
  sectionHead('kind.doc', shownDocs.length, docItems.length, KIND_DOC),
2191
- docsGrid(shownDocs)),
2727
+ docsGrid(withGhosts(MOTION_TIER_ALL_DOCS, shownDocs))),
2192
2728
  mediaItems.length === 0 ? null : h('div', { className: 'knit-section', key: 'media' },
2193
2729
  // 媒体不截断,所以只给一个标题,不给「已显示 / 总数」和「查看全部」
2194
2730
  h('div', { className: 'knit-section-head' },
@@ -2214,18 +2750,13 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2214
2750
  ? allSections
2215
2751
  : contextView
2216
2752
  ? contextBody(contextView)
2217
- : docsGrid(visibleDocs)
2218
-
2219
- // 排序依据那行**弱化**了(2026-09-29 用户要求):可见的只有一句
2220
- // 「相关性排序」,命中的关键词退到 title 里当低层 metadata ——
2221
- // 关键词是**系统依据**,不该被大号加粗地推到用户眼前。
2222
- // ⚠️ 可见文本里**不能**出现关键词:test/i18n.test.mjs 有守卫。
2223
- const topicText = relevance
2224
- ? t('topic.relevancePlain')
2225
- : (sort === 'relevance' ? t('topic.needsConversation') : t('topic.time'))
2226
- const topicTitle = relevance && state.topic
2227
- ? t('topic.relevanceTerms', { topic: state.topic })
2228
- : topicText
2753
+ : docsGrid(withGhosts(MOTION_TIER_FLAT, visibleDocs))
2754
+
2755
+ // 排序说明那一行(.knit-topic)**2026-09-30 已整体删除**:排序方式由头部那个
2756
+ // 「相关 / 最新」切换按钮自己表达(按钮上就写着当前选的是哪个),再补一句
2757
+ // 「相关性排序」是重复。命中的关键词**跟着一起消失** —— 它当时只在这行的
2758
+ // title 里(可见文本本来就不许出现关键词,test/i18n.test.mjs 有守卫)。
2759
+ // ⚠️ i18n 里那四个 topic.* 键已同时删除,不要为了「以后可能用」留着。
2229
2760
 
2230
2761
  /* v0.15「使用情况」:只把**事实**读出来 —— 先看的那篇读没读、辅助读了几篇、
2231
2762
  一共读了几次、几次落在包外、上下文换过几回。
@@ -2237,6 +2768,9 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2237
2768
  if (!u || !u.stats) return t('usage.none')
2238
2769
  const s = u.stats
2239
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 }))
2240
2774
  if (s.primaryRel) {
2241
2775
  parts.push(s.primaryFollowThrough
2242
2776
  ? t('usage.primaryRead', { rel: s.primaryRel })
@@ -2250,6 +2784,92 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2250
2784
  return parts.join(' · ')
2251
2785
  })()
2252
2786
 
2787
+ /* v0.17:三条新事实 —— 全部只在「使用情况」开着、且宿主真的回传了 `usage` 时出现。
2788
+ ① 最近读取(按事件 seq 认「谁是最近一次」,墙钟只用来算相对时间)
2789
+ ② 上下文外读取的明细(当前包外、但真实成功读过)
2790
+ ③ 最近**一次** Context Delta
2791
+ ⚠️ 关掉使用情况时**一个节点都不加**:DOM 与 v0.16 逐字一致。
2792
+ ⚠️ 这里没有时间线、没有全量事件、没有评分 —— 「最近一次」就只有一条。 */
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
+
2803
+ const outsideList = usageFacts && Array.isArray(usageFacts.outsideDocs) ? usageFacts.outsideDocs : []
2804
+ const gapNode = outsideList.length > 0
2805
+ ? h('div', { className: 'knit-usage-more', key: 'gap' },
2806
+ h('button', {
2807
+ className: 'knit-more-btn',
2808
+ type: 'button',
2809
+ 'aria-expanded': gapOpen ? 'true' : 'false',
2810
+ onClick: () => setGapOpen((value) => !value),
2811
+ }, t('usage.outsideDocs', { n: outsideList.length })),
2812
+ 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)
2816
+ : null
2817
+
2818
+ // 层级的**短名**:分组标题那套长文案(主要上下文 / 辅助上下文 / 相关上下文)在变化行里太长。
2819
+ const tierShort = (key) => {
2820
+ if (key === 'primary') return t('tierName.primary')
2821
+ if (key === 'supporting') return t('tierName.supporting')
2822
+ if (key === 'related') return t('tierName.related')
2823
+ return ''
2824
+ }
2825
+ const delta = usageFacts && usageFacts.latestDelta ? usageFacts.latestDelta : null
2826
+ const deltaLine = (text, key) => h('div', { className: 'knit-delta-row', key },
2827
+ h('span', { className: 'knit-delta-rel' }, text))
2828
+ // 摘要行的符号只用 `+` `-` `↔` 三个通用符号,不用颜色区分「进 / 出」。
2829
+ 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') })
2844
+ }
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
+ ] : []
2850
+ const deltaNode = delta
2851
+ ? h('div', { className: 'knit-usage-more', key: 'delta' },
2852
+ h('button', {
2853
+ className: 'knit-more-btn',
2854
+ type: 'button',
2855
+ 'aria-expanded': deltaOpen ? 'true' : 'false',
2856
+ 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')
2861
+ : null,
2862
+ deltaOpen ? deltaGroups
2863
+ .filter((group) => group.rows.length > 0)
2864
+ .map((group) => [
2865
+ 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`)
2869
+ : null,
2870
+ ]) : null)
2871
+ : null
2872
+
2253
2873
  // 不同类型用不同量词:文档「篇」、媒体「个」、混排「项」。
2254
2874
  const countKey = kind === KIND_MEDIA
2255
2875
  ? (filtering ? 'count.media.filtered' : 'count.media')
@@ -2318,9 +2938,13 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2318
2938
  title: t('kind.title'),
2319
2939
  onClick: () => pickKind(value),
2320
2940
  }, t(labelKey)))),
2321
- h('div', { className: 'knit-topic', title: topicTitle }, topicText),
2322
2941
  // v0.15:开了才显示。一行事实,没有卡片、没有分数条。
2323
- usageOn ? h('div', { className: 'knit-usage', title: t('usage.note') }, usageText || t('usage.none')) : null,
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,
2324
2948
  notice ? h('div', { className: 'knit-notice' }, notice) : null,
2325
2949
  // 列表节点**直接挂上去**(2026-09-29 起永远单栏;曾经它要交给一个 IIFE
2326
2950
  // 决定塞进单栏还是双栏的左列)。**输出与 v0.13 逐字一致** ——
@@ -2422,10 +3046,14 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2422
3046
  * @returns {Function} 组件
2423
3047
  */
2424
3048
  /**
2425
- * 取当前会话 id(悬停浮层要用它拉列表)。
3049
+ * 旧内核的兜底读法:从 `sessions` 列表快照里读「当前会话」。
2426
3050
  *
2427
- * 入口按钮坐在 list 座位上,座位不给任何 owner 参数,所以只能从
2428
- * sessions 列表里读「当前会话」——与聊天视图解析 cwd 用的是同一条路。
3051
+ * ⚠️ **这不是主路径**。2026-09-30 实测当前内核的契约:
3052
+ * `ctx.sessions.list` 的快照是 `SessionListState`
3053
+ * `{ ids, byId, phase, projectionsBySession }` —— **没有 `current` 字段**
3054
+ * (契约注释写着「navigation belongs to view owners」,当前会话归视图所有)。
3055
+ * 所以这个函数在现代内核上恒返回空串;悬停浮层的主路径是座位 props 里的
3056
+ * `sessionId`(见 `makeEntryButton`)。保留它只是让更老的内核上不至于全空。
2429
3057
  *
2430
3058
  * @returns {string} 会话 id,取不到为空串
2431
3059
  */
@@ -2479,8 +3107,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2479
3107
  h('div', { className: 'knit-peek-head' },
2480
3108
  h(KnitGlyph, { size: 13 }),
2481
3109
  h('span', null, t('count', { n: total }))),
2482
- h('div', { className: 'knit-peek-list' }, body),
2483
- h('div', { className: 'knit-peek-hint' }, t('peek.openPanel')))
3110
+ h('div', { className: 'knit-peek-list' }, body))
2484
3111
  }
2485
3112
 
2486
3113
  /**
@@ -2496,12 +3123,24 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2496
3123
  * @returns {Function} 组件
2497
3124
  */
2498
3125
  function makeEntryButton(onOpen) {
2499
- return function KnitEntryButton() {
3126
+ return function KnitEntryButton(props) {
2500
3127
  const [peek, setPeek] = React.useState(null)
2501
3128
  const btnRef = React.useRef(null)
2502
3129
  const showTimer = React.useRef(null)
2503
3130
  const hideTimer = React.useRef(null)
2504
3131
 
3132
+ // 当前会话 id:这个座位是 **session 作用域**
3133
+ // (`conversation.session.header.utilities`),框架通过标准 props
3134
+ // 直接把当前会话 id 递进来(`SessionStandardProps.sessionId`,
3135
+ // 由 `dsh-client-ui-session` 声明、座位契约注释也写明
3136
+ // 「Header actions derive their state from standard Session props」)。
3137
+ // 这是唯一可靠的来源 —— 老写法读 `sessions` 列表快照的 `current`,
3138
+ // 而那个字段在现行契约里不存在(见 `currentSessionId` 的注释)。
3139
+ // 属性留在 ref 里给定时器回调用,每次渲染刷新。
3140
+ const seatSessionId = (props && props.sessionId) || ''
3141
+ const sidRef = React.useRef(seatSessionId)
3142
+ sidRef.current = seatSessionId || currentSessionId()
3143
+
2505
3144
  /** 清掉两个定时器。 */
2506
3145
  const clearTimers = () => {
2507
3146
  if (showTimer.current) { clearTimeout(showTimer.current); showTimer.current = null }
@@ -2510,7 +3149,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2510
3149
 
2511
3150
  /** 拉浮层要显示的那几篇。 */
2512
3151
  const loadPeek = async () => {
2513
- const sessionId = currentSessionId()
3152
+ const sessionId = sidRef.current
2514
3153
  if (!sessionId) {
2515
3154
  setPeek((cur) => (cur ? { ...cur, status: 'ready', docs: [], total: 0 } : cur))
2516
3155
  return
@@ -2602,6 +3241,11 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2602
3241
  const tabInfo = typeof useTabInfo === 'function' ? useTabInfo() : null
2603
3242
  const actions = tabInfo && tabInfo.tab ? tabInfo.tab.actions : null
2604
3243
 
3244
+ // 座位契约里的 `tab.visible`:右栏收起、或本标签不是当前那个时是 `false`
3245
+ // (`SidebarRightTabInfo.tab.visible`,「Docked bodies require expansion and selection」)。
3246
+ // **折叠期间 dockkit 不卸载 tag 身体**,所以要自己停下来 —— 见 KnitBody 轮询那段。
3247
+ const visible = !tabInfo || !tabInfo.tab || tabInfo.tab.visible !== false
3248
+
2605
3249
  const openInTab = React.useCallback((doc) => {
2606
3250
  if (!actions || typeof actions.openResource !== 'function') {
2607
3251
  return t('error.noOpenResource')
@@ -2614,7 +3258,7 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2614
3258
  }
2615
3259
  }, [actions, sessionId])
2616
3260
 
2617
- return h(KnitBody, { sessionId, openInTab })
3261
+ return h(KnitBody, { sessionId, openInTab, visible })
2618
3262
  }
2619
3263
 
2620
3264
  /**
@@ -2875,12 +3519,19 @@ body[data-ds-dark-theme] .knit-icon{color:#fff}
2875
3519
  return
2876
3520
  }
2877
3521
 
3522
+ // hidden: true 是给 better-sidebar v0.24.1+ 的「原生表面」用的:那一版起它把
3523
+ // 每个 descriptor 镜像成官方右侧栏的一个类型(id `dsh-better-sidebar:<id>`、
3524
+ // kind 取这里的 id),并在 descriptor 没写 hidden 时**连带注册一条 guide 条目**。
3525
+ // 于是「开始」页上出现两行一模一样的「Knit 最近文档」:① 的 kind 'knit' 与镜像的
3526
+ // kind 'knit:recent'。hidden 只掐掉镜像那条 guide 条目(+ 菜单项),类型、座位与
3527
+ // ctx.betterSidebar.openTab 都还在 —— 入口保留 ① 那条(不看宿主装没装都在)。
2878
3528
  bsCtx.effect(() => bs.registerTab({
2879
3529
  id: BS_TAB_ID,
2880
3530
  title: () => t('guide.title'),
2881
3531
  icon: KnitGlyph,
2882
3532
  order: 30,
2883
3533
  single: true, // 同类型只开一个
3534
+ hidden: true, // 别让镜像在官方 guide 里再挂一行(见上)
2884
3535
  component: (props) => h(BetterSidebarTabBody, props),
2885
3536
  }), 'dsh-knit: better-sidebar tab')
2886
3537