dsh-knit 0.20.0 → 0.22.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.
@@ -757,7 +757,27 @@ test('媒体:默认文档视图有四个类型按钮(文档/代码/媒体/
757
757
  // ⚠️ 列数改造后,**默认(1 列)形态的 DOM 与改造前逐字一致**:
758
758
  // 不多包一层容器(否则 byClass('knit-doc') 这类子串匹配会多命中一个)。
759
759
  assert.equal(byClass(nodes, 'knit-multicol').length, 0, '1 列不该有网格容器')
760
- assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /2 篇/)
760
+ assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /^2$/,
761
+ 'v0.21.x:计数只剩阿拉伯数字,量词只留在 title 里')
762
+ })
763
+
764
+ test('v0.21.x 顶行计数:可见的只有阿拉伯数字,量词只留在 title 里', async () => {
765
+ const mounted = await mountWithPayload(listPayload())
766
+
767
+ const count = byExactClass(mounted.nodes, 'knit-count')[0]
768
+ assert.ok(count, '顶行应有一个计数')
769
+ assert.equal(textOf(count), '2', '可见文本只有数字')
770
+ // 量词随档位变(篇 / 个代码文件 / 个媒体 / 项)—— 同一位置换个档就换一种中文,
771
+ // 所以整句降级进 title:悬停仍读得到,i18n 的 count.* 键也不被闲置。
772
+ assert.equal(count.props.title, '2 篇', '整句退到 title')
773
+ assert.match(textOf(count), /^[\d\s/]+$/, '可见计数里不许出现中文或字母')
774
+
775
+ // 过滤后是「命中 / 总数」,仍然只有数字与斜杠
776
+ byClass(mounted.nodes, 'knit-filter')[0].props.onChange({ target: { value: '技术' } })
777
+ const filtered = byExactClass(mounted.render(), 'knit-count')[0]
778
+ assert.equal(textOf(filtered), '1 / 2')
779
+ assert.equal(filtered.props.title, '1 / 2 篇')
780
+ assert.match(textOf(filtered), /^[\d\s/]+$/)
761
781
  })
762
782
 
763
783
  test('媒体:媒体视图渲染方形网格,图片出 img、视频出首帧 video 与播放三角', async () => {
@@ -782,7 +802,8 @@ test('媒体:媒体视图渲染方形网格,图片出 img、视频出首帧
782
802
  assert.equal(videos[0].props.preload, 'metadata')
783
803
  assert.ok(String(videos[0].props.src).includes('#t=0.5'), '用 #t=0.5 取首帧')
784
804
  assert.equal(byClass(nodes, 'knit-thumb-play').length, 1, '视频有中央播放三角')
785
- assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /2 个媒体/)
805
+ assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /^2$/,
806
+ 'v0.21.x:媒体档也只剩阿拉伯数字(不再「个媒体」)')
786
807
  })
787
808
 
788
809
  test('媒体:点图片卡片就地预览大图,且不请求 /api/doc', async () => {
@@ -848,7 +869,7 @@ test('媒体:「全部」分上下两区,文档上限 4、媒体一格不隐
848
869
  // 载荷里 5 图 + 4 视频 = 9 个媒体:一格都不隐藏,纵向也**不封顶**(有多少行铺多少行)
849
870
  assert.equal(byToken(nodes, 'knit-media-card').length, 9, '媒体区不截断,9 个全出')
850
871
  assert.equal(byExactClass(nodes, 'knit-media-grid in-section').length, 1, '媒体区用分区网格')
851
- assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /16 项/, '顶行仍报总数')
872
+ assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /^16$/, '顶行仍报总数')
852
873
 
853
874
  const grid = byExactClass(nodes, 'knit-media-grid in-section')[0]
854
875
  // 测试环境没有 ResizeObserver → 量不到宽度 → 走默认面板几何(632px)
@@ -1910,15 +1931,16 @@ test('上下文:键盘按屏幕顺序穿过三档(↓ 跨区不断链)', a
1910
1931
  任何右栏骨架。留着一套渲染不出来的样式,下一个人只会以为它还在生效。 */
1911
1932
 
1912
1933
  /**
1913
- * 收集一棵子树里所有元素节点的 className(展开函数组件)。
1934
+ * 展开函数组件,把一棵子树里的**元素节点**按文档顺序摊平。
1914
1935
  *
1915
- * `byClass` 只看扁平列表,答不了「谁在谁里面」;右栏必须在 listbox **外面**
1916
- * 这条断言需要真正的包含关系。
1936
+ * `byClass` / `byExactClass` 只看渲染树的扁平列表,答不了「谁在谁里面」「这一组里
1937
+ * 谁在谁前面」;操作组必须先证明它在证据行**里面**,再证明组内顺序是
1938
+ * 固定 → 排除 → 来源词(2026-10-08 用户规格)。
1917
1939
  *
1918
1940
  * @param {object} node - 节点
1919
- * @returns {string[]} className 列表
1941
+ * @returns {object[]} 元素节点(文档顺序)
1920
1942
  */
1921
- function classesUnder(node) {
1943
+ function flattenUnder(node) {
1922
1944
  const acc = []
1923
1945
  const walk = (n) => {
1924
1946
  if (!n || typeof n !== 'object') return
@@ -1926,13 +1948,34 @@ function classesUnder(node) {
1926
1948
  const type = n.type
1927
1949
  if (type && typeof type === 'object' && typeof type.type === 'function') { walk(type.type(n.props)); return }
1928
1950
  if (typeof type === 'function') { walk(type(n.props)); return }
1929
- if (n.props && n.props.className) acc.push(String(n.props.className))
1951
+ acc.push(n)
1930
1952
  ;(n.children || []).forEach(walk)
1931
1953
  }
1932
1954
  walk(node)
1933
1955
  return acc
1934
1956
  }
1935
1957
 
1958
+ /**
1959
+ * 收集一棵子树里所有元素节点的 className(展开函数组件)。
1960
+ *
1961
+ * `byClass` 只看扁平列表,答不了「谁在谁里面」;右栏必须在 listbox **外面**
1962
+ * 这条断言需要真正的包含关系。
1963
+ *
1964
+ * @param {object} node - 节点
1965
+ * @returns {string[]} className 列表
1966
+ */
1967
+ function classesUnder(node) {
1968
+ return flattenUnder(node)
1969
+ .map((n) => (n.props && n.props.className ? String(n.props.className) : ''))
1970
+ .filter(Boolean)
1971
+ }
1972
+
1973
+ /** 一棵子树里第一个带这个 class 词的节点(找不到给 null)。 */
1974
+ function nodeUnder(node, token) {
1975
+ return flattenUnder(node)
1976
+ .find((n) => String((n.props && n.props.className) || '').split(/\s+/).includes(token)) || null
1977
+ }
1978
+
1936
1979
  test('单栏:即使给了 Context Pack,DOM 里也没有任何右栏骨架', async () => {
1937
1980
  const { nodes } = await mountWithPayload(contextPayload())
1938
1981
  for (const dead of ['knit-context-layout', 'knit-col-list', 'knit-context-column',
@@ -3404,7 +3447,8 @@ test('v0.19 代码:「代码」档请求 kind=code,代码行带语言徽章
3404
3447
  // 徽章是**纯展示**:它把文件名后缀说给人看,不参与任何判定(判定在宿主分类层)。
3405
3448
  assert.deepEqual(byExactClass(nodes, 'knit-lang').map(textOf), ['TS', 'JS'])
3406
3449
  assert.equal(byExactClass(nodes, 'knit-media-grid').length, 0, '代码档没有媒体网格')
3407
- assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /2 个代码文件/)
3450
+ assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /^2$/,
3451
+ 'v0.21.x:代码档也只剩阿拉伯数字(不再「个代码文件」)')
3408
3452
  })
3409
3453
 
3410
3454
  test('v0.19 代码:文档行的语言徽章不出场 —— 整列都是 Markdown,挂 MD 是纯噪声', async () => {
@@ -3884,7 +3928,7 @@ test('v0.19 代码:「全部」档是三区(文档 / 代码 / 媒体),
3884
3928
  assert.equal(byToken(nodes, 'knit-doc').length, 8, '文档区与代码区各自限 4 条')
3885
3929
  assert.equal(byExactClass(nodes, 'knit-lang').length, 4, '语言徽章只跟着代码区那 4 行')
3886
3930
  assert.equal(byToken(nodes, 'knit-media-card').length, 3, '媒体一格不隐藏')
3887
- assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /16 项/, '顶行仍报总数')
3931
+ assert.match(byClass(nodes, 'knit-count').map(textOf).join(''), /^16$/, '顶行仍报总数')
3888
3932
  })
3889
3933
 
3890
3934
  test('v0.19 代码:Usage Lens 里的代码路径照常显示(读的是一份事实、不是两套)', async () => {
@@ -4170,8 +4214,14 @@ test('v0.20 命中段:与「直接命中」合成一条 metadata 行(命中
4170
4214
  await harness.flush()
4171
4215
  nodes = render()
4172
4216
 
4173
- assert.equal(byExactClass(nodes, 'knit-subrow').length, 1, '两条 metadata 共用一个行容器')
4217
+ // 2026-10-08 布局改造:证据行右端现在是操作组,于是**每一条文档行**都有这一行
4218
+ // (没有证据的那些行只是左边空着)。「命中段与理由共用一行」这条要求本身没变,
4219
+ // 所以按**行**来数,而不是数整屏。
4174
4220
  const row = byToken(nodes, 'knit-doc').find((r) => /README/.test(textOf(r)))
4221
+ assert.equal(
4222
+ classesUnder(row).filter((c) => c.split(/\s+/).includes('knit-subrow')).length, 1,
4223
+ '两条 metadata 共用一个行容器',
4224
+ )
4175
4225
  const txt = textOf(row)
4176
4226
  assert.ok(txt.includes('正文命中 sidebar'), `理由仍然在:${txt}`)
4177
4227
  assert.ok(txt.indexOf('命中段') < txt.indexOf('正文命中'), `命中段在理由前面:${txt}`)
@@ -4485,3 +4535,481 @@ test('v0.20 文档锚点:样式纪律 —— transition 在基础选择器上
4485
4535
  assert.ok(!/border/.test(hit[1]), '不许画边框(与代码那边的横带同一个纪律)')
4486
4536
  assert.ok(!/transform|position:/.test(hit[1]), '不许位移')
4487
4537
  })
4538
+
4539
+ /* ── v0.21 关系与控制(需求 §6、§8)────────────────────────────────────
4540
+ 这一层的纪律:**默认视图一个字节都不变**。固定区、来源徽标、行级证据、管道条、
4541
+ 排除说明全都是「有这件事才出现」的层,平铺列表(宿主没给 Context Pack)一个节点都不多。 */
4542
+
4543
+ /**
4544
+ * 造一份 v0.21 的载荷:三层 + 固定区 + 控制状态 + 行级关系。
4545
+ *
4546
+ * 只造**契约里真的会出现的形状**:
4547
+ * - 固定项同时出现在 `docs` 与 `context.pinned`(宿主是把它们从三层**移出**,
4548
+ * 不是从候选集里删掉);
4549
+ * - 被排除的文件**不在 `docs` 里**(宿主在检索之前就拿掉了),
4550
+ * 所以「能不能恢复」只能看宿主给的 `exists`。
4551
+ *
4552
+ * @param {object} options - 固定 / 排除 / 关系 / 来源
4553
+ * @returns {object} 载荷
4554
+ */
4555
+ function v021Payload(options = {}) {
4556
+ const {
4557
+ pinnedRels = [], excluded = [], provenance = 'retrieval',
4558
+ relations = null, relationsTotal = 0, skipped = 0,
4559
+ } = options
4560
+ const at = Date.now()
4561
+ const total = 2 + pinnedRels.length
4562
+ const item = (rel, title, extra = {}) => ({
4563
+ rel,
4564
+ path: `/p/${rel}`,
4565
+ name: rel.split('/').pop(),
4566
+ title,
4567
+ summary: `摘要 ${title}`,
4568
+ mtimeMs: at,
4569
+ kind: 'md',
4570
+ source: 'doc',
4571
+ reason: { code: 'titleMatch', terms: ['排序'], fields: 2 },
4572
+ provenance,
4573
+ ...extra,
4574
+ })
4575
+ const doc = (rel, title) => ({
4576
+ path: `/p/${rel}`, rel, name: rel.split('/').pop(), title, summary: `摘要 ${title}`,
4577
+ mtimeMs: at, score: 10,
4578
+ })
4579
+ const pinned = pinnedRels.map((rel) => item(rel, rel, { provenance: 'manual' }))
4580
+ return {
4581
+ ok: true, root: '/p', total, mode: 'relevance', topic: 'BM25、排序', keywords: ['排序'],
4582
+ control: { pinned: pinnedRels.map((rel) => ({ rel, at })), excluded, skipped, persisted: false },
4583
+ docs: [
4584
+ doc('docs/algo.md', '排序算法'),
4585
+ doc('docs/eval.md', '排序评测'),
4586
+ ...pinnedRels.map((rel) => doc(rel, rel)),
4587
+ ],
4588
+ context: {
4589
+ mode: 'relevance', topic: 'BM25、排序', task: '',
4590
+ pinned,
4591
+ primary: [item('docs/algo.md', '排序算法', { relations, relationsTotal })],
4592
+ supporting: [], related: [],
4593
+ totals: { primary: 1, supporting: 0, related: 0, matched: 1, total },
4594
+ summary: { primary: 1, supporting: 0, related: 0, shown: 1, matched: 1, total },
4595
+ },
4596
+ }
4597
+ }
4598
+
4599
+ test('v0.21 来源:检索 / 关系 / 用户固定 三个中性词,不是分数', async () => {
4600
+ const payload = v021Payload({ pinnedRels: ['docs/pin.md'] })
4601
+ // supporting 换成**靠关系进来**的那一条(宿主给的 provenance 就是 relation)
4602
+ payload.context.supporting = [{ ...payload.context.primary[0], rel: 'docs/eval.md', provenance: 'relation' }]
4603
+ const { nodes } = await mountWithPayload(payload)
4604
+ const provs = byExactClass(nodes, 'knit-prov').map(textOf).sort()
4605
+ assert.deepEqual(provs, ['关系', '用户固定', '检索'].sort(), '三个来源各一个中性词')
4606
+ // 来源**不是强弱**:不许带数字 / 百分比 / 颜色语义
4607
+ for (const text of provs) {
4608
+ assert.ok(!/\d|%/.test(text), `来源词里不许出现数字或百分比:${text}`)
4609
+ }
4610
+ })
4611
+
4612
+ test('v0.21.x 布局:标题行只剩标题与时间,来源与固定 / 排除搬到证据行右端(固定 → 排除 → 来源词)', async () => {
4613
+ /* 2026-10-08 用户规格(Context 列表操作布局优化):标题行右侧原来并排四样东西
4614
+ (来源词 + 固定 + 排除 + 时间)=信息过载。来源与命中段、理由说的是**同一层证据**,
4615
+ 固定 / 排除是**操作入口** —— 于是两者合成**一行**:证据在左、操作在右,
4616
+ 操作那一组默认不显示(`.knit-rowacts` 的 `visibility:hidden`,悬停 / 键盘光标 /
4617
+ 焦点进入这一行才出现)。这条用例守的就是这个结构本身。 */
4618
+ const { readFileSync } = await import('node:fs')
4619
+ const { fileURLToPath } = await import('node:url')
4620
+ const relations = [
4621
+ { type: 'references', dir: 'in', other: 'AGENTS.md', line: 83 },
4622
+ { type: 'tests', dir: 'out', other: 'a.test.mjs' },
4623
+ ]
4624
+ const { nodes } = await mountWithPayload(v021Payload({ relations, relationsTotal: 2 }))
4625
+
4626
+ // ① 标题行:序号 / 标记 / 标题 / 时间之外,一个 v0.21 节点都不许留
4627
+ const row1s = byExactClass(nodes, 'knit-row1')
4628
+ assert.equal(row1s.length, byToken(nodes, 'knit-doc').length, '每一条文档行恰好一个标题行')
4629
+ for (const row1 of row1s) {
4630
+ const under = classesUnder(row1)
4631
+ for (const gone of ['knit-prov', 'knit-rowacts', 'knit-act']) {
4632
+ assert.ok(!under.some((c) => c.split(/\s+/).includes(gone)), `${gone} 不该再留在标题行里`)
4633
+ }
4634
+ assert.ok(under.some((c) => c.split(/\s+/).includes('knit-time')), '时间仍在标题行(位置不变)')
4635
+ }
4636
+
4637
+ // ② 证据行:左证据 / 右操作是**同一条行**的两段,不是两行
4638
+ const algoRow = byToken(nodes, 'knit-doc').find((r) => r.props['data-knit-rel'] === 'docs/algo.md')
4639
+ const sub = nodeUnder(algoRow, 'knit-subrow')
4640
+ assert.ok(sub, '证据行在行里面')
4641
+ const main = nodeUnder(sub, 'knit-subrow-main')
4642
+ const acts = nodeUnder(sub, 'knit-rowacts')
4643
+ assert.ok(main && acts, '证据与操作组都在这一条证据行里')
4644
+ assert.ok(textOf(main).includes('标题命中 排序'), '左边仍然是原来那条理由')
4645
+ assert.ok(textOf(sub).indexOf(textOf(main)) < textOf(sub).indexOf(textOf(acts)), '证据靠左、操作靠右')
4646
+
4647
+ // ③ 组内顺序是硬的:固定 → 排除 → 来源词;而且**只有文字,没有任何图标**
4648
+ const controls = flattenUnder(acts)
4649
+ .filter((n) => /(^|\s)(knit-act|knit-prov)(\s|$)/.test(String((n.props && n.props.className) || '')))
4650
+ assert.deepEqual(controls.map(textOf), ['固定', '排除', '检索'], '顺序:固定 → 排除 → 来源词')
4651
+ for (const node of flattenUnder(acts)) {
4652
+ assert.ok(!/^(svg|path|use|img|i)$/.test(String(node.type)), `不许加图标:${String(node.type)}`)
4653
+ }
4654
+
4655
+ // ④ 默认不显示靠 `visibility`(真的退出焦点序),不是 `opacity:0`(那会「看不见却 Tab 得到」)
4656
+ const source = readFileSync(fileURLToPath(new URL('../src/client/client.js', import.meta.url)), 'utf8')
4657
+ const actsRule = source.match(/\.knit-rowacts\{([^}]*)\}/)[1]
4658
+ assert.match(actsRule, /visibility:hidden/, '默认整组隐藏')
4659
+ assert.ok(!/opacity/.test(actsRule), '不再用 opacity 压暗 —— 隐藏必须同时退出焦点序')
4660
+ assert.ok(!/transition/.test(actsRule), '不加悬停动画 / 过渡')
4661
+ assert.match(source.match(/\.knit-doc:hover \.knit-rowacts[^{]*\{([^}]*)\}/)[1], /visibility:visible/)
4662
+ for (const trigger of ['.knit-doc.active', '.knit-doc.cursor', ':focus-within']) {
4663
+ assert.ok(source.includes(`${trigger} .knit-rowacts`), `悬停之外还要认键盘与选中态:${trigger}`)
4664
+ }
4665
+ // 证据可以被截断(flex:1 1 auto + min-width:0),操作永远有位置(flex:none)
4666
+ assert.match(source.match(/\.knit-subrow-main\{([^}]*)\}/)[1], /flex:1 1 auto/)
4667
+ assert.match(actsRule, /flex:none/)
4668
+ })
4669
+
4670
+ test('v0.21.x 布局:没有命中段也没有理由的条目仍留着那一行,只是左边空着(不写占位文字)', async () => {
4671
+ const { nodes } = await mountWithPayload(v021Payload())
4672
+ const evalRow = byToken(nodes, 'knit-doc').find((r) => r.props['data-knit-rel'] === 'docs/eval.md')
4673
+ assert.ok(evalRow, '这一屏里有「其他相关文档」的条目')
4674
+ const sub = nodeUnder(evalRow, 'knit-subrow')
4675
+ assert.ok(sub, '没有证据也要留这一行 —— 否则这一条连固定 / 排除的入口都没有')
4676
+ const main = nodeUnder(sub, 'knit-subrow-main')
4677
+ // ⚠️ 先钉住「容器真的在」:`textOf(undefined)` 返回 `''`,缺了这一句,
4678
+ // 下面那条「不写占位文字」会在容器整个消失时**空转通过**(证伪时实测过)。
4679
+ assert.ok(main, '左边的证据容器在(只是空的)——它有偏移量,行才不跳')
4680
+ assert.equal(textOf(main).trim(), '', '不写占位文字(连一个「—」都不给)')
4681
+ assert.ok(
4682
+ !classesUnder(sub).some((c) => /knit-hit|knit-why|knit-subrow-sep/.test(c)),
4683
+ '一个证据节点都没有(没有证据就不装成有证据的样子)',
4684
+ )
4685
+ assert.ok(nodeUnder(sub, 'knit-rowacts'), '操作入口照旧在(默认隐藏)')
4686
+ })
4687
+
4688
+ test('v0.21 固定区:排在三层最上面、不编号,并给「取消固定」', async () => {
4689
+ const { nodes } = await mountWithPayload(v021Payload({ pinnedRels: ['docs/pin.md'] }))
4690
+ // 分区标题按**文档顺序**取(`byExactClass` 吃的是扁平节点表,不递归)
4691
+ assert.deepEqual(
4692
+ byExactClass(nodes, 'knit-tiername').map(textOf).slice(0, 2),
4693
+ ['固定上下文', '主要上下文'], '固定区在最上面,三层仍在它下面')
4694
+ assert.equal(textOf(byExactClass(nodes, 'knit-tierhint')[0]), '你自己标记的')
4695
+ const rows = byClass(nodes, 'knit-doc')
4696
+ const pinRow = rows.find((r) => r.props['data-knit-rel'] === 'docs/pin.md')
4697
+ const primaryRow = rows.find((r) => r.props['data-knit-rel'] === 'docs/algo.md')
4698
+ assert.match(textOf(pinRow), /用户固定/, '固定项的来源就是「用户固定」')
4699
+ assert.deepEqual(byExactClass(nodes, 'knit-num').map(textOf), ['01'],
4700
+ '编号只属于包内的阅读顺序 —— 固定项不编号,也不把它顶掉')
4701
+ assert.ok(byExactClass(nodes, 'knit-gapmark').length >= 1, '没号的位置给中性占位,不留空洞')
4702
+ assert.match(textOf(pinRow), /取消固定/)
4703
+ assert.match(textOf(primaryRow), /固定/)
4704
+ assert.ok(!textOf(primaryRow).includes('取消固定'), '包内条目给的是「固定」')
4705
+ })
4706
+
4707
+ test('v0.21 排除:说明行只列还能找回来的那些,点了发 restore', async () => {
4708
+ const payload = v021Payload({
4709
+ excluded: [
4710
+ { rel: 'docs/gone.md', at: 1, exists: false },
4711
+ { rel: 'docs/eval.md', at: 2, exists: true },
4712
+ ],
4713
+ skipped: 1,
4714
+ })
4715
+ const posts = []
4716
+ globalThis.fetch = async (url, init = {}) => {
4717
+ const target = String(url)
4718
+ if (target.includes('/api/control')) {
4719
+ posts.push({ url: target, body: JSON.parse(init.body) })
4720
+ return {
4721
+ json: async () => ({
4722
+ ok: true, action: 'restore', rel: 'docs/eval.md', changed: true, persisted: false,
4723
+ control: { pinned: [], excluded: [], skipped: 0, persisted: false },
4724
+ }),
4725
+ }
4726
+ }
4727
+ return {
4728
+ json: async () => (target.includes('/api/links')
4729
+ ? { ok: true, rel: 'x', incoming: [], outgoing: [], incomingTotal: 0, outgoingTotal: 0 }
4730
+ : payload),
4731
+ }
4732
+ }
4733
+ const { KnitBody } = loadClientModule().exports.__test
4734
+ harness.reset()
4735
+ harness.seed(['', 'relevance'])
4736
+ const render = () => harness.render(h(KnitBody, { sessionId: 's1' }))
4737
+ let nodes = render()
4738
+ await harness.flush()
4739
+ nodes = render()
4740
+
4741
+ const note = byExactClass(nodes, 'knit-excl')
4742
+ assert.equal(note.length, 1, '有能恢复的排除项时才出现这一行')
4743
+ assert.match(textOf(note[0]), /被用户排除:docs\/eval\.md/)
4744
+ assert.ok(!textOf(note[0]).includes('gone.md'), '文件已经不在的就不给「恢复」(按下去什么都不会发生)')
4745
+
4746
+ const restore = byClass(nodes, 'knit-act').find((b) => textOf(b) === '恢复')
4747
+ assert.ok(restore, '说明行里那个「恢复」是真的按钮')
4748
+ restore.props.onClick()
4749
+ await harness.flush()
4750
+ assert.equal(posts.length, 1, '恢复是一个真的写动作')
4751
+ assert.match(posts[0].url, /\/knit\/api\/control\?sessionId=s1/)
4752
+ assert.deepEqual(posts[0].body, { action: 'restore', rel: 'docs/eval.md' })
4753
+
4754
+ // 一个都找不回来 ⇒ 整行不出现、也不占位
4755
+ const nothing = await mountWithPayload(v021Payload({ excluded: [{ rel: 'docs/gone.md', at: 1, exists: false }] }))
4756
+ assert.equal(byExactClass(nothing.nodes, 'knit-excl').length, 0)
4757
+ })
4758
+
4759
+ test('v0.21.x 检索状态摘要:单行三组、竖线分隔、组内中点,且一个箭头都没有', async () => {
4760
+ /* 2026-10-09 用户规格(检索状态摘要布局优化):原来是「收集 4 ↓ 排除 1 → 3 ↓ 检索 / 排序
4761
+ (BM25 词法) ↓ 关系投影 1 ↓ 固定覆盖 1 ↓ 包 1」—— 六个格子五根箭头,把一条**已经完成**
4762
+ 的管线画成了流程图(用户:「用箭头表达内部处理流程,增加理解成本」)。现在改成
4763
+ 工作区候选 | 检索与调整 | 最终结果 三组、组内中点、组间一根细竖线,
4764
+ 并且**每一格都能独立读懂**(那个没有名字的光数字「→ 3」现在叫「候选 3」)。 */
4765
+ const { nodes } = await mountWithPayload(v021Payload({
4766
+ pinnedRels: ['docs/pin.md'],
4767
+ excluded: [{ rel: 'docs/eval.md', at: 2, exists: true }],
4768
+ skipped: 1,
4769
+ relations: [{ type: 'references', dir: 'out', other: 'docs/b.md', line: 7 }],
4770
+ }))
4771
+ const pipe = byExactClass(nodes, 'knit-pipe')
4772
+ assert.equal(pipe.length, 1)
4773
+
4774
+ // ① 逐个格子的**原文**,以及分隔符的种类与位置 —— 顺序就是这条设计要传达的信息
4775
+ const seq = flattenUnder(pipe[0]).slice(1).map(textOf)
4776
+ assert.deepEqual(seq, [
4777
+ '收集 4', '·', '排除 1', '·', '候选 3', '|',
4778
+ 'BM25 词法检索', '·', '关系 1 条', '·', '固定 1', '|',
4779
+ '入包 1',
4780
+ ], `三组 = 工作区候选 | 检索与调整 | 最终结果:${textOf(pipe[0])}`)
4781
+
4782
+ // ② 口径逐个钉住(不许因为改文案就改了统计含义)
4783
+ assert.match(seq[0], /收集 4/, '收集 = 候选 + 本批真被排掉的(3 + 1)')
4784
+ assert.match(seq[2], /排除 1/, '排除 = 宿主按候选集算的 skipped,不是 excluded 表的长度')
4785
+ assert.match(seq[4], /候选 3/, '候选 = 排除之后进入检索的篇数(原来的光数字)')
4786
+ assert.match(seq[6], /BM25 词法检索/, '零模型这条路要说出来')
4787
+ assert.match(seq[8], /关系 1 条/, '关系 = 这一份包里带了几条关系证据')
4788
+ assert.match(seq[10], /固定 1/, '固定 = 被固定、从三层移出进了固定区的篇数')
4789
+ assert.match(seq[12], /入包 1/, '入包 = 三层条目数(固定区不算)')
4790
+
4791
+ // ③ 分隔符恰好是 4 个中点 + 2 根竖线;箭头与「管道」时代的类名一个都不留
4792
+ assert.equal(seq.filter((s) => s === '·').length, 4, '组内中点:每组 n 格配 n-1 个')
4793
+ assert.equal(seq.filter((s) => s === '|').length, 2, '组间竖线:三组两根')
4794
+ assert.equal(byClass(nodes, 'knit-pipearrow').length, 0, '流程箭头已整体删除')
4795
+ assert.ok(!/[↓→←↑]/.test(textOf(pipe[0])), `状态摘要里不许再出现箭头:${textOf(pipe[0])}`)
4796
+ // 视觉纪律:没有图标、没有色块(需求 §三.5,与「不做 Dashboard」同一条)
4797
+ for (const node of flattenUnder(pipe[0])) {
4798
+ assert.ok(!/^(svg|path|use|img|i)$/.test(String(node.type)), `不许加图标:${String(node.type)}`)
4799
+ }
4800
+ for (const banned of ['%', '分数', '索引', '缓存', '命中率', '置信']) {
4801
+ assert.ok(!textOf(pipe[0]).includes(banned), `状态摘要不许出现「${banned}」:${textOf(pipe[0])}`)
4802
+ }
4803
+ })
4804
+
4805
+ test('v0.21.x 工具栏:排序 | 竖线 | 类型 | 搜索一行,两组不做成一个整体,搜索永远排尾', async () => {
4806
+ /* 2026-10-09 用户规格:左侧「相关 / 最新」负责排序;中间「文档 / 代码 / 媒体 / 全部」负责
4807
+ 内容类型;搜索框固定在最右侧、宽度自适应(常规面板 180–240px,窄屏先缩它)。三条要守住:
4808
+ ① 六个选项**不做成一个整体** —— 排序与类型是两个条件,中间一根浅灰竖线就是那道边界;
4809
+ ② 搜索排尾、贴右、`flex:1 1 180px` + `max-width:240px` + `min-width:0`;
4810
+ ③ 条件彼此独立:选「代码」再选「最新」= 最新的代码,搜索词两边都不重置。 */
4811
+ const { nodes: first, renderAgain } = await mountWithPayload(v021Payload())
4812
+ let nodes = first
4813
+
4814
+ const bar = byExactClass(nodes, 'knit-bar')
4815
+ assert.equal(bar.length, 1, '工具栏恰好一个')
4816
+ const under = flattenUnder(bar[0]).slice(1)
4817
+ const cls = under.map((n) => String(n.props.className || ''))
4818
+ const at = (name) => cls.findIndex((c) => c === name)
4819
+
4820
+ // ① 顺序:排序 → 竖线 → 类型 → 搜索(顺序本身就是这条规格要传达的信息)
4821
+ for (const name of ['knit-seg', 'knit-bar-sep', 'knit-types', 'knit-filter']) {
4822
+ assert.ok(at(name) >= 0, `工具栏里必须有 ${name}:${cls.join(' / ')}`)
4823
+ }
4824
+ assert.ok(at('knit-seg') < at('knit-bar-sep'), '竖线在排序组右边')
4825
+ assert.ok(at('knit-bar-sep') < at('knit-types'), '竖线在类型组左边')
4826
+ assert.equal(cls.at(-1), 'knit-filter', '搜索是工具栏里最后一个节点(工具栏尾部)')
4827
+ assert.equal(byClass(nodes, 'knit-bar-sep').length, 1, '两组之间**就一根**线')
4828
+ assert.equal(byExactClass(nodes, 'knit-bar-sep')[0].props['aria-hidden'], 'true',
4829
+ '分隔线是装饰,不进可达性树')
4830
+
4831
+ // ② 六个选项都在,而且两组各用各的控件(不是六个连排的按钮)
4832
+ assert.deepEqual(byClass(under, 'knit-seg-btn').map(textOf), ['相关', '最新'])
4833
+ assert.deepEqual(byClass(under, 'knit-type-btn').map(textOf), ['文档', '代码', '媒体', '全部'])
4834
+ for (const node of under) {
4835
+ assert.ok(!/^(svg|path|use|img|i)$/.test(String(node.type)), `不许加图标:${String(node.type)}`)
4836
+ }
4837
+
4838
+ // ③ 条件彼此独立
4839
+ const input = () => byClass(nodes, 'knit-filter')[0]
4840
+ const activeText = (name) => textOf(byClass(nodes, name).find((n) => String(n.props.className).includes('active')))
4841
+ input().props.onChange({ target: { value: '排序' } })
4842
+ nodes = await renderAgain()
4843
+ assert.equal(input().props.value, '排序', '搜索词落在输入框上')
4844
+
4845
+ byClass(nodes, 'knit-type-btn').find((b) => textOf(b) === '代码').props.onClick()
4846
+ nodes = await renderAgain()
4847
+ assert.equal(input().props.value, '排序', '切类型不许重置搜索词')
4848
+ assert.equal(activeText('knit-seg-btn'), '相关', '切类型不许改排序')
4849
+
4850
+ byClass(nodes, 'knit-seg-btn').find((b) => textOf(b) === '最新').props.onClick()
4851
+ nodes = await renderAgain()
4852
+ assert.equal(activeText('knit-type-btn'), '代码', '切排序不许改类型 ⇒ 看到的就是「最新的代码」')
4853
+ assert.equal(input().props.value, '排序', '切排序也不许重置搜索词')
4854
+
4855
+ // ④ 样式:搜索框自适应且贴右,前面两组 flex:none 永不被挤
4856
+ const { readFileSync } = await import('node:fs')
4857
+ const { fileURLToPath } = await import('node:url')
4858
+ const source = readFileSync(fileURLToPath(new URL('../src/client/client.js', import.meta.url)), 'utf8')
4859
+ const rule = (sel) => {
4860
+ const m = source.match(new RegExp(`\\.${sel}\\{([^}]*)\\}`))
4861
+ assert.ok(m, `必须有 .${sel} 这条规则`)
4862
+ return m[1]
4863
+ }
4864
+ const filter = rule('knit-filter')
4865
+ assert.match(filter, /flex:1 1 180px/, '搜索框:基础宽 180px,可长可缩')
4866
+ assert.match(filter, /max-width:240px/, '搜索框封顶 240px(常规面板 180–240px)')
4867
+ assert.match(filter, /margin-left:auto/, '封顶后剩下的空间留在左边 ⇒ 搜索框贴住右端')
4868
+ assert.match(filter, /min-width:0/, '面板窄了先缩搜索框')
4869
+ assert.match(rule('knit-seg'), /flex:none/, '排序组不被挤')
4870
+ assert.match(rule('knit-types'), /flex:none/, '类型组不被挤')
4871
+ assert.ok(!/\.knit-types\{[^}]*padding/.test(source), '类型组不再自带左右内边距(.knit-bar 统一给)')
4872
+ const sep = rule('knit-bar-sep')
4873
+ assert.match(sep, /width:1px/, '是竖线不是横线')
4874
+ assert.match(sep, /background:var\(--dsw-alias-border-l3/, '浅灰:与排序组外框、搜索框描边同一个 token')
4875
+ })
4876
+
4877
+ test('v0.21.x 开关「使用情况」不许把检索状态摘要顶下去(摘要紧贴工具栏,观察层在它下面)', async () => {
4878
+ /* 2026-10-09 用户反馈:原来观察层插在 `.knit-bar` 和状态摘要之间,一点「使用情况」,
4879
+ 那一行数字就被顶下去(原话「这一列…向下排,我觉得这列不用向下排,而是固定在原来的位置」)。
4880
+ 守住两条:① 摘要**永远紧贴工具栏**(它的前一个兄弟就是 `.knit-bar`);
4881
+ ② 开关前后摘要的位置**一模一样**,观察层排在它下面。 */
4882
+ const direct = (root) => {
4883
+ const out = []
4884
+ const push = (n) => {
4885
+ if (!n || typeof n !== 'object') return
4886
+ if (Array.isArray(n)) { n.forEach(push); return }
4887
+ const type = n.type
4888
+ if (type && typeof type === 'object' && typeof type.type === 'function') { push(type.type(n.props)); return }
4889
+ if (typeof type === 'function') { push(type(n.props)); return }
4890
+ out.push(String((n.props && n.props.className) || ''))
4891
+ }
4892
+ ;(root.children || []).forEach(push)
4893
+ return out
4894
+ }
4895
+ const { nodes: first, renderAgain } = await mountWithPayload(v021Payload())
4896
+ let nodes = first
4897
+ const rootOf = (list) => byExactClass(list, 'knit-root')[0]
4898
+
4899
+ const orderOff = direct(rootOf(nodes))
4900
+ const pipeOff = orderOff.indexOf('knit-pipe')
4901
+ assert.ok(pipeOff > 0, `状态摘要必须在(相关序): ${orderOff.join(' / ')}`)
4902
+ assert.equal(orderOff[pipeOff - 1], 'knit-bar', '摘要的前一个兄弟就是工具栏 —— 它钉在工具栏下面')
4903
+ assert.ok(!orderOff.some((c) => c === 'knit-usage'), '关着的时候观察层一个节点都没有')
4904
+
4905
+ const toggle = byExactClass(nodes, 'knit-btn').find((node) => textOf(node) === '使用情况')
4906
+ assert.ok(toggle, '头部必须有「使用情况」按钮')
4907
+ toggle.props.onClick()
4908
+ nodes = await renderAgain()
4909
+
4910
+ const orderOn = direct(rootOf(nodes))
4911
+ assert.ok(orderOn.includes('knit-usage'), '打开后有观察层')
4912
+ assert.equal(orderOn.indexOf('knit-pipe'), pipeOff, '开关前后摘要的位置一模一样(不许被顶下去)')
4913
+ assert.equal(orderOn[pipeOff - 1], 'knit-bar', '打开后它仍紧贴工具栏')
4914
+ assert.ok(orderOn.indexOf('knit-usage') > pipeOff, '观察层排在摘要下面,不是上面')
4915
+ })
4916
+
4917
+ test('v0.21 证据:默认一个节点都不渲染,点开「为什么」才有;最多 3 条 + 共 N 条', async () => {
4918
+ const relations = [
4919
+ { type: 'references', dir: 'in', other: 'AGENTS.md', line: 83 },
4920
+ { type: 'imports', dir: 'out', other: 'src/x.js', line: 22 },
4921
+ { type: 'tests', dir: 'out', other: 'a.test.mjs' },
4922
+ { type: 'documents', dir: 'in', other: 'PRD.md', line: 10 },
4923
+ ]
4924
+ const { nodes, renderAgain } = await mountWithPayload(v021Payload({ relations, relationsTotal: 6 }))
4925
+ assert.equal(byExactClass(nodes, 'knit-rellist').length, 0, '默认视图一个字节都不变')
4926
+ const why = byClass(nodes, 'knit-why')
4927
+ assert.equal(why.length, 1)
4928
+ assert.equal(why[0].type, 'button', '有关系可看时,「为什么」就是那个开关')
4929
+ assert.equal(why[0].props['aria-expanded'], 'false')
4930
+ assert.match(textOf(why[0]), /标题命中 排序/, '开关上的文本一个字节都没变')
4931
+
4932
+ why[0].props.onClick({ stopPropagation() {} })
4933
+ const after = await renderAgain()
4934
+ const list = byExactClass(after, 'knit-rellist')
4935
+ assert.equal(list.length, 1, '点开才有')
4936
+ assert.equal(byClass(after, 'knit-relrow').length, 3, '每项最多投影 3 条(预算是硬的)')
4937
+ const txt = textOf(list[0])
4938
+ assert.match(txt, /引用/)
4939
+ assert.match(txt, /← AGENTS\.md/, 'in 边的方向与对方都如实写出来')
4940
+ assert.match(txt, /第 83 行/)
4941
+ assert.match(txt, /共 6 条关系/, '被截断时必须说出总数,不然就是「我以为这就是全部」')
4942
+ assert.ok(!txt.includes('PRD.md'), '第 4 条按优先级被截掉了')
4943
+ const algoRow = byToken(after, 'knit-doc').find((r) => r.props['data-knit-rel'] === 'docs/algo.md')
4944
+ assert.equal(
4945
+ classesUnder(algoRow).filter((c) => c.split(/\s+/).includes('knit-subrow')).length, 1,
4946
+ '证据挂在行容器**之外**:这一行的 metadata / 操作行仍然只有一条',
4947
+ )
4948
+ for (const sub of byExactClass(after, 'knit-subrow')) {
4949
+ assert.ok(
4950
+ !classesUnder(sub).some((c) => c.split(/\s+/).includes('knit-rellist')),
4951
+ '关系证据挂在证据行**之外**(展开不能把那一行撑高)',
4952
+ )
4953
+ }
4954
+ assert.ok(textOf(byClass(after, 'knit-why')[0]).includes('标题命中'), '理由那一行仍是原文')
4955
+
4956
+ byClass(after, 'knit-why')[0].props.onClick({ stopPropagation() {} })
4957
+ const closed = await renderAgain()
4958
+ assert.equal(byExactClass(closed, 'knit-rellist').length, 0, '再点一次收起来')
4959
+ })
4960
+
4961
+ test('v0.21.x 行级证据是向下延展:入场补间播完要注销,不许把行高钉死(否则证据压在下一行上面)', async () => {
4962
+ // 真机上 DocRow 的入场补间是 WAAPI `fill:'both'`:它播完之后**仍然**按入场那一刻量到的
4963
+ // height 钉着这一行,`el.style.height=''` 清不掉(内联样式与补间效果是两层)。后果就是
4964
+ // 点开「检索」长出来的证据列表不把下面的行挤下去,而是压在下一行上面
4965
+ // (2026-10-09 用户真机截图:「检索的数据压在下一个列表的下面」)。
4966
+ // 测试替身没有 DOM(`motionAllowed()` 会把那段 layout effect 直接挡掉),所以这里喂纯对象。
4967
+ const { exports } = loadClientModule()
4968
+ const { settleEnterAnim } = exports.__test
4969
+ assert.equal(typeof settleEnterAnim, 'function', '收尾必须是一个可测的函数,不是内联箭头')
4970
+
4971
+ const el = { style: { height: '88px', overflow: 'hidden' } }
4972
+ const called = []
4973
+ settleEnterAnim(el, { cancel: () => called.push('cancel') })
4974
+ assert.deepEqual(called, ['cancel'], '必须注销补间 —— 只清内联样式等于把行高钉在入场那一刻')
4975
+ assert.equal(el.style.height, '', '内联高度也要清')
4976
+ assert.equal(el.style.overflow, '', '内联裁切也要清')
4977
+
4978
+ // 边界:补间没有 cancel / 整个传 null / cancel 自己抛错,都不许把收尾卡住
4979
+ settleEnterAnim({ style: {} }, {})
4980
+ settleEnterAnim(null, null)
4981
+ const bad = { style: { height: '10px' } }
4982
+ settleEnterAnim(bad, { cancel: () => { throw new Error('cancel 抛错') } })
4983
+ assert.equal(bad.style.height, '', 'cancel 抛错也必须把内联样式清掉')
4984
+
4985
+ // 调用点也钉住:一旦退回「补间播完只清内联样式」那种写法,这条就红。
4986
+ const { readFileSync } = await import('node:fs')
4987
+ const { fileURLToPath } = await import('node:url')
4988
+ const source = readFileSync(fileURLToPath(new URL('../src/client/client.js', import.meta.url)), 'utf8')
4989
+ assert.match(source, /const settle = \(\) => settleEnterAnim\(el, anim\)/, 'DocRow 的入场收尾必须走这一条')
4990
+ assert.ok(
4991
+ !/done\.then\(\(\) => \{ el\.style\.height/.test(source),
4992
+ '不许退回「补间播完只清 el.style」的老写法',
4993
+ )
4994
+ })
4995
+
4996
+ test('v0.21 平铺列表:一个 v0.21 节点都不多(时间序 / 媒体档逐字不变)', async () => {
4997
+ const flat = v021Payload()
4998
+ delete flat.context
4999
+ const { nodes } = await mountWithPayload(flat)
5000
+ for (const cls of ['knit-prov', 'knit-rowacts', 'knit-act', 'knit-pipe', 'knit-excl', 'knit-rellist', 'knit-num']) {
5001
+ assert.equal(byClass(nodes, cls).length, 0, `平铺列表不该出现 ${cls}`)
5002
+ }
5003
+ })
5004
+
5005
+ test('镜像常量:客户端的 REL_MAX 必须等于宿主的面板投影上限', async () => {
5006
+ const { readFileSync } = await import('node:fs')
5007
+ const { fileURLToPath } = await import('node:url')
5008
+ const host = readFileSync(fileURLToPath(new URL('../src/host/relations.js', import.meta.url)), 'utf8')
5009
+ const hostMax = Number((host.match(/MAX_RELATIONS_PER_ITEM\s*=\s*(\d+)/) || [])[1])
5010
+ assert.equal(hostMax, 3, '宿主的面板投影上限')
5011
+ assert.equal(
5012
+ loadClientModule().exports.__test.REL_MAX, hostMax,
5013
+ '客户端镜像必须与宿主一致 —— 否则「共 N 条关系」那句话会撒谎',
5014
+ )
5015
+ })
@@ -282,9 +282,11 @@ test('context: 混合包的条目投影与 v0.18 逐字相同(代码不引入
282
282
  })
283
283
 
284
284
  const item = pack.primary[0]
285
+ // v0.21 给条目加了 `provenance`(来源三值)—— 这是**唯一**新增的固定字段,
286
+ // 且它是给「为什么在这里」用的,不是给排序用的(关系/来源都不参与分层)。
285
287
  assert.deepEqual(
286
288
  Object.keys(item).sort(),
287
- ['kind', 'mtimeMs', 'reason', 'rel', 'source', 'summary', 'title'],
289
+ ['kind', 'mtimeMs', 'provenance', 'reason', 'rel', 'source', 'summary', 'title'],
288
290
  'Code Context 不许往包条目里塞新字段 —— 有的话 UI 与工具就得同步改两遍',
289
291
  )
290
292
  // 内部字段一个都不许漏出去。
@@ -344,11 +344,15 @@ test('context-eval: Context Pack 不出分数、不出正文、不出绝对路
344
344
  assert.ok(!serialized.includes('"text"'), '不该带原文')
345
345
  for (const item of [...pack.primary, ...pack.supporting, ...pack.related]) {
346
346
  assert.ok(!item.rel.startsWith('/'), `rel 必须是相对路径:${item.rel}`)
347
+ // v0.21:`provenance` 是来源三值,`relations` 只在真有关系时出现(这里的关系表是空的,
348
+ // 所以两个可选键都不该出现);`provenance` 说的是「怎么进来的」,不是分数。
347
349
  assert.deepEqual(
348
350
  Object.keys(item).sort(),
349
- ['kind', 'mtimeMs', 'reason', 'rel', 'source', 'summary', 'title'],
351
+ ['kind', 'mtimeMs', 'provenance', 'reason', 'rel', 'source', 'summary', 'title'],
350
352
  `条目字段必须固定:${Object.keys(item).join('/')}`,
351
353
  )
354
+ assert.ok(['retrieval', 'relation', 'manual'].includes(item.provenance),
355
+ `provenance 必须是三个值之一:${item.provenance}`)
352
356
  }
353
357
  })
354
358