dsh-knit 0.14.0 → 0.16.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.
@@ -126,6 +126,9 @@ test('注册:有 betterSidebar 时注册一个 tab descriptor', () => {
126
126
  const d = log.bsTabs[0]
127
127
  assert.equal(d.id, 'knit:recent')
128
128
  assert.equal(d.single, true, '同类型只开一个')
129
+ // hidden 是给 better-sidebar v0.24.1+ 的「原生表面」看的:它会镜像成一个官方类型,
130
+ // 并在没有 hidden 时连带挂一条 guide 条目 ⇒ 「开始」页出现两行同名入口。
131
+ assert.equal(d.hidden, true, '不许镜像再挂一条 guide 入口(官方那条已够)')
129
132
  assert.equal(typeof d.component, 'function')
130
133
  assert.equal(d.title(), 'Knit 最近文档')
131
134
  })
@@ -150,7 +153,7 @@ test('注册:better-sidebar 缺失时官方右侧栏照常注册', () => {
150
153
 
151
154
  /* ── 渲染:排序模式 ─────────────────────────────────── */
152
155
 
153
- test('渲染:relevance 模式不做任何相关度可视化,只解释排序依据', async () => {
156
+ test('渲染:relevance 模式不做任何相关度可视化(排序即答案)', async () => {
154
157
  installFetch(() => listPayload({
155
158
  mode: 'relevance',
156
159
  topic: '相关性、sidebar',
@@ -179,13 +182,12 @@ test('渲染:relevance 模式不做任何相关度可视化,只解释排序
179
182
 
180
183
  assert.equal(byClass(nodes, 'knit-time').length, 2, '时间对所有行都一样显示')
181
184
 
182
- // 2026-09-29 用户要求**弱化关键词**:可见文本只剩一句中性的「相关性排序」,
183
- // 命中了哪几个词退到 title 里当低层 metadata(关键词是系统依据,不是主角)。
184
- const topicNode = byClass(nodes, 'knit-topic')[0]
185
- assert.equal(textOf(topicNode), '相关性排序', '可见文本里不许再出现关键词')
186
- assert.ok(!textOf(topicNode).includes('sidebar'), '关键词不进可见文本')
187
- assert.match(String(topicNode.props.title), /命中的关键词:相关性、sidebar/,
188
- '关键词退到 title 里,悬停才给')
185
+ // 2026-09-30 用户裁决:排序说明那一行(.knit-topic)**整体删除** ——
186
+ // 排序方式由头部那个「相关 / 最新」切换按钮自己表达,再补一句是重复;
187
+ // 命中的关键词随行一起消失(它当时只在这一行的 title 里)。
188
+ // 这段守卫从当年的「可见文本里不许出现关键词」升级成「那一行根本不存在」——
189
+ // 只要行还在,关键词就可能再漏出来。
190
+ assert.equal(byClass(nodes, 'knit-topic').length, 0, '排序说明行已整体删除')
189
191
  })
190
192
 
191
193
  test('渲染:相关度分数只影响顺序,不影响任何一行的渲染', async () => {
@@ -267,7 +269,8 @@ test('渲染:time 模式不显示分数,显示相对时间', async () => {
267
269
 
268
270
  assert.equal(byClass(nodes, 'knit-rel-num').length, 0, '时间模式不应有分数')
269
271
  assert.equal(byClass(nodes, 'knit-time').length, 2, '应显示相对时间')
270
- assert.ok(byClass(nodes, 'knit-topic').map(textOf)[0].includes('修改时间'))
272
+ // 排序说明行已整体删除:切到「最新」也不会把它带回来
273
+ assert.equal(byClass(nodes, 'knit-topic').length, 0, '排序说明行已整体删除')
271
274
  })
272
275
 
273
276
  test('渲染:请求 URL 带上当前排序方式', async () => {
@@ -351,11 +354,14 @@ test('渲染:预览头显示路径面包屑(目录 + 文件名),不再
351
354
  nodes = harness.render(h(KnitBody, { sessionId: 's1' }))
352
355
 
353
356
  assert.equal(byExactClass(nodes, 'knit-preview-head').length, 1)
354
- assert.equal(byExactClass(nodes, 'knit-preview-dir').map(textOf).join(''), 'sub/')
357
+ // 2026-10-01:目录不再展开,收敛成一个 `…/` 占位(用户要求「前面那一串都用三个点点点表示」,把宽度让给文件名)
358
+ assert.equal(byExactClass(nodes, 'knit-preview-dir').map(textOf).join(''), '…/')
355
359
  assert.equal(byExactClass(nodes, 'knit-preview-name').map(textOf).join(''), '需求 文档.md')
360
+ // 整条路径的字面形态就是「…/文件名」—— 目录名一个字都不许漏到界面上
361
+ assert.equal(textOf(byExactClass(nodes, 'knit-preview-path')[0]), '…/需求 文档.md')
356
362
  // 头部不再放标题:正文 H1 已经写了,重复会让「列表 / 头 / 正文」出现三遍同一个词
357
363
  assert.equal(byClass(nodes, 'knit-preview-title').length, 0)
358
- // 长目录被省略号截掉时,完整路径靠 tooltip 悬停仍能看到(与列表行的 row.tooltip 同一套)
364
+ // 目录被收敛掉之后,完整路径靠 tooltip 悬停仍能看到(与列表行的 row.tooltip 同一套)
359
365
  const pathBtn = byExactClass(nodes, 'knit-preview-path')[0]
360
366
  assert.match(String(pathBtn.props.title), /sub\/需求 文档\.md/, 'tooltip 里带完整相对路径')
361
367
  assert.equal(pathBtn.props.type, 'button', '路径是可点的')
@@ -1072,13 +1078,19 @@ test('文档:序号是最左边一列,行一=「点 + 标题 + 时间」
1072
1078
  '一行=最左边一列序号 + 右边一列其余数据',
1073
1079
  )
1074
1080
  }
1075
- // 没有序号的行(时间序 / 筛选结果 /「其他相关文档」)**不渲染序号节点**,但它们
1076
- // 也**不许掉进第一列** —— 靠 .knit-body 的 grid-column 定死位置(用自动排布就会掉)。
1081
+ // 没有序号的行(时间序 / 筛选结果 /「其他相关文档」)**也不许掉进第一列** ——
1082
+ // 靠 .knit-body 的 grid-column 定死位置(用自动排布就会掉)。
1083
+ // 2026-10-01:这一列**不再整格空着**(用户原话:「其他相关文档…没有序号以后左边就空了,
1084
+ // 视觉上比较割裂,就觉得是个 bug 一样」)。这一屏里有号时,没号的行在同一列渲染一个
1085
+ // 中性占位标记 `.knit-gapmark`(·)—— 不冒充序号,也不让轨道断掉。
1077
1086
  const unnumbered = docs.filter((d) => !classesUnder(d).includes('knit-num'))
1078
1087
  assert.ok(unnumbered.length > 0, '这个 payload 里有不编号的条目')
1079
1088
  for (const doc of unnumbered) {
1080
- assert.equal(String((doc.children[0] && doc.children[0].props.className) || ''), 'knit-body',
1081
- '没有序号时正文也要落在第二列,和有条目的行左边缘对齐')
1089
+ assert.deepEqual(
1090
+ doc.children.slice(0, 2).map((c) => String((c && c.props && c.props.className) || '')),
1091
+ ['knit-gapmark', 'knit-body'],
1092
+ '没号的行用同列的占位标记顶住,正文仍然落在第二列',
1093
+ )
1082
1094
  }
1083
1095
 
1084
1096
  const rows = byExactClass(nodes, 'knit-row1')
@@ -1129,26 +1141,53 @@ test('样式:类型切换是下划线式页签,选中态不用品牌色也
1129
1141
  assert.match(rule[1], /border-bottom-color:/, '选中态靠下划线表达层级')
1130
1142
  assert.ok(!rule[1].includes('background:var(--knit-active-bg'),
1131
1143
  '下划线式页签不许再退回灰底按钮——两者叠加会同时占用两种「选中」表达')
1132
- // 页签条本身要有那条 hairline,否则下划线悬空
1133
- assert.match(source, /\.knit-types\{[^}]*border-bottom:1px solid/, '页签条要有底边')
1144
+ // ⚠️ 2026-09-30 用户裁决(**覆盖**上面那条「页签条要有底边」):那条全宽 hairline
1145
+ // 与下面的列表割裂,删掉。层级现在只由选中项自己那条 2px 下划线表达 ——
1146
+ // 它是画在自己文字下面的,所以不是「下划线悬空」。
1147
+ assert.ok(!/\.knit-types\{[^}]*border/.test(source), '页签条不再画底边')
1134
1148
  })
1135
1149
 
1136
- test('样式:列表行的「正在预览」是中性描边,不再是品牌色描边', async () => {
1150
+ test('样式:列表行的「正在预览」只有灰底,描边已整体删除', async () => {
1137
1151
  const { readFileSync } = await import('node:fs')
1138
1152
  const { fileURLToPath } = await import('node:url')
1139
1153
  const source = readFileSync(fileURLToPath(new URL('../src/client/client.js', import.meta.url)), 'utf8')
1140
1154
 
1141
- // v0.14(Design §12 / §8):用户 2026-09-29 裁决改成 neutral border。
1142
- // ⚠️ 这条**覆盖**了 AGENTS.md §4.1.2 里那句「列表行『正在预览』的品牌色描边是故意留的」。
1143
- // 理由是 Design §8「用灰阶建立层级,而不是用颜色建立层级」。
1155
+ // v0.14(Design §12 / §8):2026-09-29 用户裁决先把品牌色描边改成 neutral border。
1156
+ // ⚠️ 2026-09-30 用户裁决**再覆盖一次**:「悬停跟选中,最外层那个描边,我觉得也不需要了」
1157
+ // ⇒ 描边整条删掉,选中态只剩灰底。这条断言因此从「必须是中性描边」翻成「不许有任何描边」。
1144
1158
  const rule = source.match(/\.knit-doc\.active\{([^}]*)\}/)
1145
1159
  assert.ok(rule, '必须还有 .knit-doc.active 这条规则')
1146
1160
  assert.ok(!rule[1].includes('--knit-accent'),
1147
1161
  `列表行选中态不许再出现品牌色:${rule[1]}`)
1148
- assert.match(rule[1], /border-color:var\(--dsw-alias-border-l4/,
1149
- '选中态用中性描边(与键盘光标同一档工具色)')
1162
+ assert.ok(!rule[1].includes('border'),
1163
+ `选中态不许再有描边(2026-09-30 用户裁决):${rule[1]}`)
1150
1164
  assert.match(rule[1], /background:var\(--knit-active-bg/,
1151
- '选中态仍然保留灰底——描边只说明「在哪儿」,填充才说明「选中了」')
1165
+ '选中态保留灰底——现在它是唯一的分层信号')
1166
+ })
1167
+
1168
+ test('样式:这一轮的「去线 / 去描边」都不许回潮(2026-09-30 用户裁决)', async () => {
1169
+ const { readFileSync } = await import('node:fs')
1170
+ const { fileURLToPath } = await import('node:url')
1171
+ const source = readFileSync(fileURLToPath(new URL('../src/client/client.js', import.meta.url)), 'utf8')
1172
+ const start = source.indexOf('const CSS = `') + 'const CSS = `'.length
1173
+ const css = source.slice(start, source.indexOf('`', start)).replace(/\/\*[\s\S]*?\*\//g, '')
1174
+
1175
+ // ① 列表行的描边:静止那圈透明占位 + 悬停 / 选中各自上的色,三处一起删
1176
+ assert.ok(!css.includes('border:.5px solid transparent'), '那条 .5px 透明边框占位已删')
1177
+ assert.ok(!/\.knit-doc:hover\{[^}]*border-color/.test(css), '悬停态没有描边')
1178
+ assert.ok(!/\.knit-doc\.active\{[^}]*border-color/.test(css), '选中态没有描边')
1179
+ // ⚠️ 边框删了就得用 padding 补回它占掉的 .5px×2,否则每一行矮 1px、左右各窄 .5px
1180
+ assert.match(css, /\.knit-doc\{[^}]*padding:10\.5px 11\.5px/,
1181
+ 'padding 要把删掉的边框补回来')
1182
+ // ② 引用条自己不再画线(预览头那条由另一条用例守)
1183
+ assert.ok(!/\.knit-links\{[^}]*border/.test(css), '引用条不画线')
1184
+ // ③ 排序说明行的四个 i18n 键随行一起删掉,不许留在字典里「以后可能用」
1185
+ for (const key of ['topic.relevancePlain', 'topic.relevanceTerms', 'topic.needsConversation', 'topic.time']) {
1186
+ assert.ok(!source.includes(`'${key}'`), `${key} 已随那一行删除`)
1187
+ }
1188
+ // ④ 过滤框提示改成不列字段的一句话(两种语言都在)
1189
+ assert.match(source, /'filter\.placeholder': '过滤文档'/)
1190
+ assert.match(source, /'filter\.placeholder': 'Filter docs'/)
1152
1191
  })
1153
1192
 
1154
1193
  test('样式:悬停 / 选中的灰底各降一档(悬停 −60% / 选中 −40%),两个主题都给了值', async () => {
@@ -1229,7 +1268,9 @@ test('样式:文档列表没有网格 —— 多列那套已整体删除,容
1229
1268
  // **垂直居中**靠的正是这两个数字对齐,改一处必须改另一处
1230
1269
  // (v0.14 规格 §15 把文档标题提到 14px,所以这一对数字一起变了)。
1231
1270
  assert.match(css, /\.knit-title\{flex:1 1 auto;min-width:0;font-weight:600;font-size:14px;line-height:1\.4;/)
1232
- assert.match(css, /\.knit-num\{grid-column:1;font-size:10\.5px;line-height:19\.6px;/)
1271
+ // 2026-10-01:`.knit-gapmark`(没号时的中性占位标记)与序号**共用同一条选择器**,
1272
+ // 所以「序号的行高必须等于标题行高」这条纪律自动覆盖它。
1273
+ assert.match(css, /\.knit-num,\.knit-gapmark\{grid-column:1;font-size:10\.5px;line-height:19\.6px;/)
1233
1274
 
1234
1275
  // ⚠️ 行的**静止态没有底色**(2026-09-29 用户看了暗色主题之后要求:
1235
1276
  // 「深色模式下,文档列表没有选中,鼠标没有悬停,不需要有背景。或者是说,跟深色模式的最底下的
@@ -1248,7 +1289,7 @@ test('样式:文档列表没有网格 —— 多列那套已整体删除,容
1248
1289
  // (用户原话:「文档列表序号放在独立最左边,其他数据放在右边」)。
1249
1290
  // 第二列必须是 minmax(0,1fr):不然长标题会把行撑宽,省略号失效。
1250
1291
  assert.match(css, /\.knit-doc\{display:grid;grid-template-columns:22px minmax\(0,1fr\)/)
1251
- assert.match(css, /\.knit-num\{grid-column:1;/)
1292
+ assert.match(css, /\.knit-num,\.knit-gapmark\{grid-column:1;/)
1252
1293
  assert.match(css, /\.knit-body\{grid-column:2;min-width:0\}/,
1253
1294
  '第二列的位置与 min-width:0 都要写死 —— 少一个长标题就会把行撑宽')
1254
1295
  })
@@ -1384,9 +1425,10 @@ test('样式:预览面板底色恒为纯阅读底色,不靠底色分层;
1384
1425
  // 分层三件套仍在:上边界 + 圆角 + 柔影
1385
1426
  assert.match(css, /\.knit-preview\{[^}]*border-top-left-radius:12px/)
1386
1427
  assert.match(css, /\.knit-preview\{[^}]*box-shadow:0 -8px 24px/)
1387
- // 头部对齐官方 .dhJKeW_header:38px + border-l3
1428
+ // 头部高度仍对齐官方 .dhJKeW_header:38px;但官方那条 border-l3 底边
1429
+ // 已按 2026-09-30 用户裁决删掉(与引用条那条一起,两条细线把引用区夹得割裂)
1388
1430
  assert.match(css, /\.knit-preview-head\{[^}]*height:38px/)
1389
- assert.match(css, /\.knit-preview-head\{[^}]*border-bottom:\.5px solid var\(--dsw-alias-border-l3/)
1431
+ assert.ok(!/\.knit-preview-head\{[^}]*border-bottom/.test(css), '预览头不再画底边')
1390
1432
  // 全屏时要去掉圆角与柔影(那时没有「浮在列表上」的隐喻)
1391
1433
  assert.match(css, /\.knit-root\.fullscreen \.knit-preview\{[^}]*border-radius:0/)
1392
1434
  // ⚠️ 旧行为已废:不再有 .knit-preview.reading,也没有背景过渡
@@ -1855,6 +1897,24 @@ test('上下文:行首序号跨三档连续,且「其他相关文档」不
1855
1897
  assert.equal(docs.length, 5)
1856
1898
  assert.equal(docs[4].props['data-knit-rel'], 'docs/other.md', '最后一档是「其他相关文档」')
1857
1899
  assert.equal(byExactClass(nodes, 'knit-num').length, 4, '它不在这个包里,所以不编号')
1900
+ // 2026-10-01:它那一格不空着了 —— 同列一个中性标记(用户要「不要像 bug」,
1901
+ // 同时保住「所有行左边缘对齐」)。但它**不是**序号:整数序列里没有第 5 个数字。
1902
+ assert.deepEqual(byExactClass(nodes, 'knit-gapmark').map(textOf), ['·'])
1903
+ assert.equal(classesUnder(docs[4]).includes('knit-num'), false, '占位标记不许被当成序号')
1904
+ })
1905
+
1906
+ test('上下文:占位标记跟「这一屏有没有号」走 —— 混着才有,整屏没号就一个都没有', async () => {
1907
+ // 有号的一屏:只有「其他相关文档」那一行拿到标记
1908
+ const { nodes } = await mountWithPayload(contextPayload())
1909
+ assert.equal(byExactClass(nodes, 'knit-num').length, 4)
1910
+ assert.deepEqual(byExactClass(nodes, 'knit-gapmark').map(textOf), ['·'])
1911
+ // 过滤到「无关」之后只剩「其他相关文档」这一档:整屏没号 ⇒ 一个标记都不许有
1912
+ // (这才是「像 bug」的真正判据:混着才刺眼,整屏一致就没人觉得缺东西)
1913
+ const mounted = await mountWithPayload(contextPayload())
1914
+ byClass(mounted.nodes, 'knit-filter')[0].props.onChange({ target: { value: '无关' } })
1915
+ const after = mounted.render()
1916
+ assert.equal(byExactClass(after, 'knit-num').length, 0, '只剩包外那一档 ⇒ 没有号')
1917
+ assert.equal(byExactClass(after, 'knit-gapmark').length, 0, '没有号的一屏里也不放占位标记')
1858
1918
  })
1859
1919
 
1860
1920
  test('上下文:Primary 那颗点是位置信号,只有主上下文那一行有', async () => {
@@ -1872,6 +1932,8 @@ test('上下文:时间序不分层,行首也不编号(平铺列表照旧
1872
1932
  const { nodes } = await mountWithPayload(contextPayload({ mode: 'time' }))
1873
1933
  assert.equal(byExactClass(nodes, 'knit-tier').length, 0, '时间序不分层')
1874
1934
  assert.equal(byExactClass(nodes, 'knit-num').length, 0, '平铺列表不编号')
1935
+ assert.equal(byExactClass(nodes, 'knit-gapmark').length, 0,
1936
+ '整屏都没号时一个占位标记都不渲染 —— 一屏里要么都有、要么都没有')
1875
1937
  assert.equal(byExactClass(nodes, 'knit-dot').length, 0, '平铺列表没有主上下文点')
1876
1938
  assert.equal(byClass(nodes, 'knit-doc').length, 5, '文档本身照常列全')
1877
1939
  })
@@ -1919,11 +1981,197 @@ test('样式:组与组之间只靠 16px 空间(不再画横线),序号
1919
1981
  // 用户要求「减少横向分割线」:组间距靠空间,不靠 border-top
1920
1982
  assert.match(source, /\.knit-tier \+ \.knit-tier\{margin-top:16px\}/)
1921
1983
  assert.ok(!/\.knit-tier \+ \.knit-tier\{[^}]*border-top/.test(source), '组之间不该再有横线')
1922
- // 顶部那行排序依据也不再带全宽下划线
1923
- assert.ok(!/\.knit-topic\{[^}]*border-bottom/.test(source), '排序依据那一行不画线')
1984
+ // 排序说明那一行(原名 .knit-topic)2026-09-30 已**整体删除** ——
1985
+ // 当年这条断言问的是「那一行有没有画线」,现在问的是「那一行还在不在」。
1986
+ // ⚠️ 必须剥掉注释再查 CSS:历史注释里还会提到这个类名(那是给后人 grep 的)。
1987
+ const start = source.indexOf('const CSS = `') + 'const CSS = `'.length
1988
+ const css = source.slice(start, source.indexOf('`', start)).replace(/\/\*[\s\S]*?\*\//g, '')
1989
+ assert.ok(!css.includes('.knit-topic'), '排序依据那一行的样式已整体删除')
1990
+ assert.ok(!source.includes("'knit-topic'"), '排序依据那一行的节点已整体删除')
1924
1991
  // 字号:标题 14px / 行高 1.4 = 19.6px;序号的 line-height 必须与它同步,
1925
1992
  // 这是「序号与标题第一行垂直居中」的唯一手段(改一处必须改两处)
1926
1993
  assert.match(source, /\.knit-title\{flex:1 1 auto;min-width:0;font-weight:600;font-size:14px;line-height:1\.4;/)
1927
- assert.match(source, /\.knit-num\{grid-column:1;font-size:10\.5px;line-height:19\.6px;/)
1994
+ assert.match(source, /\.knit-num,\.knit-gapmark\{grid-column:1;font-size:10\.5px;line-height:19\.6px;/)
1928
1995
  assert.match(source, /\.knit-sum\{font-size:12px;line-height:19px;/)
1929
1996
  })
1997
+
1998
+ /* ── v0.15「使用情况」 ───────────────────────────────────────────────
1999
+ 三条纪律要一起守住:① **默认关**(没打开就一个事件都不读);
2000
+ ② 打开后请求带 `usage=1`(那是宿主侧的开闸信号,不是可选参数);
2001
+ ③ 显示的只有**事实**:读了几次、落在哪一层、上下文换过几回 ——
2002
+ **没有分数、没有百分比、没有评分条**(用户明确要求过)。 */
2003
+
2004
+ /** 一份带 usage 的宿主载荷:先看的那篇(docs/algo.md)已被读。 */
2005
+ function usagePayload() {
2006
+ return contextPayload({
2007
+ usage: {
2008
+ at: 1_700_000_000_000,
2009
+ epochId: 4,
2010
+ stats: {
2011
+ reads: 7,
2012
+ distinct: 3,
2013
+ outside: 2,
2014
+ outsideReads: ['knit/src/host/index.js'],
2015
+ firstReadTier: 'primary',
2016
+ firstReadRel: 'docs/algo.md',
2017
+ firstReadAt: 1,
2018
+ primaryRel: 'docs/algo.md',
2019
+ primaryFollowThrough: true,
2020
+ byTier: {
2021
+ primary: { total: 1, read: 1 },
2022
+ supporting: { total: 2, read: 1 },
2023
+ related: { total: 1, read: 0 },
2024
+ },
2025
+ supportingCoverage: 0.5,
2026
+ churn: { snapshots: 2, deltas: 2, retained: 2, appeared: 1, disappeared: 0, moved: 0, taskChanged: 0 },
2027
+ },
2028
+ delta: { appeared: ['docs/eval.md'], disappeared: [], moved: [], taskChanged: false },
2029
+ },
2030
+ })
2031
+ }
2032
+
2033
+ test('使用情况:默认关 —— 请求里没有 usage=1,DOM 里也没有那一行', async () => {
2034
+ const { calls } = installFetch(() => usagePayload())
2035
+ const { KnitBody } = loadClientModule().exports.__test
2036
+ harness.reset()
2037
+ harness.seed(['', 'relevance'])
2038
+ const render = () => harness.render(h(KnitBody, { sessionId: 's1' }))
2039
+ let nodes = render()
2040
+ await harness.flush()
2041
+ nodes = render()
2042
+ await harness.flush()
2043
+ nodes = render()
2044
+
2045
+ assert.ok(!calls.some((url) => url.includes('usage=1')), '默认关:一个会话事件都不该被读')
2046
+ assert.equal(byExactClass(nodes, 'knit-usage').length, 0, '默认关:不显示那一行')
2047
+ })
2048
+
2049
+ test('使用情况:打开后请求带 usage=1,那一行只报事实(没有分数 / 百分比)', async () => {
2050
+ const { calls } = installFetch(() => usagePayload())
2051
+ const { KnitBody } = loadClientModule().exports.__test
2052
+ harness.reset()
2053
+ harness.seed(['', 'relevance'])
2054
+ const render = () => harness.render(h(KnitBody, { sessionId: 's1' }))
2055
+ let nodes = render()
2056
+ await harness.flush()
2057
+ nodes = render()
2058
+ await harness.flush()
2059
+ nodes = render()
2060
+
2061
+ const toggle = byExactClass(nodes, 'knit-btn').find((node) => textOf(node) === '使用情况')
2062
+ assert.ok(toggle, '头部必须有「使用情况」按钮')
2063
+ assert.equal(toggle.props['aria-pressed'], false, '默认关')
2064
+ toggle.props.onClick()
2065
+ await harness.flush()
2066
+ nodes = render()
2067
+ await harness.flush()
2068
+ nodes = render()
2069
+
2070
+ assert.ok(calls.some((url) => url.includes('usage=1')), '打开后必须带 usage=1')
2071
+ const line = byExactClass(nodes, 'knit-usage')[0]
2072
+ assert.ok(line, '打开后必须出现那一行')
2073
+ const text = textOf(line)
2074
+ assert.match(text, /当前上下文 · Epoch 4/, '当前上下文的编号要如实说出来')
2075
+ assert.match(text, /已读/, '先看的那篇被读了要如实说出来')
2076
+ assert.match(text, /辅助 1\/2/)
2077
+ assert.match(text, /读了 7 次/)
2078
+ assert.match(text, /包外 2 篇/)
2079
+ assert.match(text, /上下文换过 2 次/)
2080
+ assert.ok(!text.includes('%'), '不许有百分比')
2081
+ assert.ok(!/评分|置信|分数/.test(text), '不许有评分 / 置信度这类词')
2082
+ })
2083
+
2084
+ test('样式:使用情况那一行是弱化文字 —— 没有卡片 / 进度条 / 品牌色', async () => {
2085
+ const { readFileSync } = await import('node:fs')
2086
+ const { fileURLToPath } = await import('node:url')
2087
+ const source = readFileSync(
2088
+ fileURLToPath(new URL('../src/client/client.js', import.meta.url)),
2089
+ 'utf8',
2090
+ )
2091
+ assert.match(source, /\.knit-usage\{[^}]*font-size:10\.5px/)
2092
+ assert.ok(!/\.knit-usage\{[^}]*background/.test(source), '不画卡片底色')
2093
+ assert.ok(!/\.knit-usage\{[^}]*knit-accent/.test(source), '不用品牌色')
2094
+ assert.ok(!/\.knit-usage\{[^}]*width:\s*\d/.test(source), '不是进度条')
2095
+ // 开关本身也不许染色
2096
+ assert.ok(!/\.knit-btn\.active\{[^}]*knit-accent/.test(source), '开关的选中态走中性灰')
2097
+ })
2098
+
2099
+ /* ── 可见性(v0.16 · 收起右栏时不许再敲宿主)────────────────────
2100
+ 官方右侧栏收起后,dockkit **不卸载**标签身体,v0.16 之前这里照旧每 5 秒请求一次
2101
+ `/knit/api/recent` 并 `setState`:白烧一次全工作区扫描,还往宿主正在收起的那层 DOM 里
2102
+ 插一帧重渲染(2026-10-01 用户报的「右栏收起来变成一条空白」)。契约给的
2103
+ `tab.visible` 就是「宿主还看得见吗」,用它做闸门。 */
2104
+
2105
+ test('可见性:宿主说看不见时一次都不取数,也不挂轮询', async () => {
2106
+ const { calls } = installFetch(() => listPayload())
2107
+ const { KnitBody } = loadClientModule().exports.__test
2108
+ harness.reset()
2109
+ harness.seed(['', 'relevance'])
2110
+ const render = (visible) => harness.render(h(KnitBody, { sessionId: 's1', visible }))
2111
+ const listCalls = () => calls.filter((url) => url.includes('/knit/api/recent'))
2112
+ // harness 的定时器是**整个测试文件共用**的(`reset()` 只清 hook 槽,不清定时器),所以看增量。
2113
+ const timers = () => harness.pendingTimers()
2114
+ const timersBefore = timers()
2115
+
2116
+ // 1. 折叠着挂载:连请求都不发,也不留定时器
2117
+ render(false)
2118
+ await harness.flush()
2119
+ assert.equal(listCalls().length, 0, '看不见就不该敲宿主 —— 折叠期间身体仍然挂着')
2120
+ assert.equal(timers() - timersBefore, 0, '看不见就不该挂轮询')
2121
+
2122
+ // 2. 重新可见:effect 重跑 ⇒ 立刻补一次,不必等下一个 5 秒
2123
+ let nodes = render(true)
2124
+ await harness.flush()
2125
+ assert.equal(listCalls().length, 1, '重新可见必须立刻取一次')
2126
+ assert.equal(timers() - timersBefore, 1, '看得见才挂下一次轮询')
2127
+ nodes = render(true)
2128
+ await harness.flush()
2129
+ assert.equal(byClass(nodes, 'knit-doc').length, 2, '列表照常渲染')
2130
+
2131
+ // 3. 又看不见:新登记的 effect 直接返回,不再取数
2132
+ const before = listCalls().length
2133
+ render(false)
2134
+ await harness.flush()
2135
+ assert.equal(listCalls().length, before, '再次折叠就该停手')
2136
+ })
2137
+
2138
+ test('可见性:官方座位把契约的 `tab.visible` 一路传到 KnitBody', async () => {
2139
+ const { ctx, log } = fakeCtx({ sidebarRightTabs: true })
2140
+ const { exports } = loadClientModule()
2141
+ exports.apply(ctx)
2142
+
2143
+ const body = log.slots.find((s) => s.opts && s.opts.name === 'sidebar.right.pane.tab')
2144
+ assert.ok(body, '官方座位必须注册 body')
2145
+
2146
+ // 座位给的真身:`tab.visible === false` 表示右栏收起 / 本标签不是当前那个
2147
+ const seat = (visible) => ({
2148
+ sessionId: 's1',
2149
+ useTabInfo: () => ({ tab: { visible, actions: { openResource() {} } } }),
2150
+ })
2151
+ const listCalls = (calls) => calls.filter((url) => url.includes('/knit/api/recent'))
2152
+
2153
+ // ① 收起时挂载:适配层要把 visible=false 传下去,否则下面这个断言会红
2154
+ let { calls } = installFetch(() => listPayload())
2155
+ harness.reset()
2156
+ harness.seed(['', 'relevance'])
2157
+ harness.render(h(body.component, seat(false)))
2158
+ await harness.flush()
2159
+ assert.equal(listCalls(calls).length, 0, '收起时不该取数(座位说了 visible=false)')
2160
+
2161
+ // ② 展开:同一个座位,立刻取一次
2162
+ ;({ calls } = installFetch(() => listPayload()))
2163
+ harness.reset()
2164
+ harness.seed(['', 'relevance'])
2165
+ harness.render(h(body.component, seat(true)))
2166
+ await harness.flush()
2167
+ assert.equal(listCalls(calls).length, 1, '展开时必须取数')
2168
+
2169
+ // ③ 座位没给 `useTabInfo`(降级 / 别的宿主):当作看得见,不能把面板冻住
2170
+ ;({ calls } = installFetch(() => listPayload()))
2171
+ harness.reset()
2172
+ harness.seed(['', 'relevance'])
2173
+ harness.render(h(body.component, { sessionId: 's1' }))
2174
+ await harness.flush()
2175
+ assert.equal(listCalls(calls).length, 1, '拿不到 visible 时要照旧取数')
2176
+ })
2177
+