dsh-knit 0.16.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.
@@ -9,6 +9,8 @@
9
9
  import test from 'node:test'
10
10
  import assert from 'node:assert/strict'
11
11
  import http from 'node:http'
12
+ import { utimesSync } from 'node:fs'
13
+ import { join } from 'node:path'
12
14
  import { fileURLToPath } from 'node:url'
13
15
  import { stat } from 'node:fs/promises'
14
16
 
@@ -393,10 +395,11 @@ test('HTTP 端到端:默认不记账,usage=1 开闸,读事件由 session/e
393
395
  assert.ok(!('usage' in body), '默认不该回传 usage(更不该偷偷记账)')
394
396
 
395
397
  // ② 打开:这一刻开始记。此刻还一次读事件都没发生 → 计数是 0。
396
- // v0.16 刻意**不回溯**订阅之前的事件:宁可少记,也不去猜一段没法按当时上下文归因的历史。
398
+ // 这个假会话没有 `snapshotEvents()`(= 没有可回填的历史),所以仍然是 0;
399
+ // 有历史的会话会在开闸这一刻回填一次 —— 见下面「面板开晚」那条用例。
397
400
  body = await (await fetch(`${base}/api/recent?sessionId=s1&sort=relevance&usage=1`)).json()
398
401
  assert.ok(body.usage, 'usage=1 应当回传使用情况')
399
- assert.equal(body.usage.stats.reads, 0, '订阅之前发生的事件不回溯')
402
+ assert.equal(body.usage.stats.reads, 0, '没有历史可回填时照旧从 0 开始')
400
403
  // ⚠️ `at` 是**上一份包**交出去的时间;第一次记账时还没有上一份,所以是 0。
401
404
  // 这不是缺陷,是顺序:usage 先算、快照后记(从下一次请求起才有「上一份」)。
402
405
  assert.equal(body.usage.at, 0)
@@ -525,3 +528,127 @@ test('HTTP 端到端:/api/context 也推进快照,但只在已记账的会
525
528
  await close()
526
529
  }
527
530
  })
531
+
532
+ /* ── v0.17 文档生命周期(端到端)────────────────────────────────────
533
+ v0.16 的 15 个 stats 键一个都不许动;生命周期是**新的事实投影**:
534
+ 宿主每次请求重新 scan → 拿到真实 `mtimeMs` → 与「最后一次成功 read 时
535
+ 记下的 mtimeMs」比对。所以这两条用例必须真的改磁盘上的文件时间
536
+ (`utimesSync`),否则测的只是替身。 */
537
+
538
+ /** v0.16 就有的 15 个 stats 键 —— v0.17 只在**顶层**加新字段,不许挤进 stats。 */
539
+ const STATS_KEYS = [
540
+ 'byTier', 'churn', 'continuedReadsAfterExit', 'distinct', 'firstReadAt',
541
+ 'firstReadEpoch', 'firstReadRel', 'firstReadTier', 'outside', 'outsideReads',
542
+ 'primaryFollowThrough', 'primaryRel', 'reEntries', 'reads', 'supportingCoverage',
543
+ ]
544
+
545
+ test('HTTP 端到端:usage 顶层多出生命周期 / 最近读取 / 包外明细,stats 形状不变', async () => {
546
+ const { base, close, emit } = await startKnitServer(
547
+ sessionWithEvents([userMessage(1, 'hub 这份文档')]), 's6',
548
+ )
549
+ try {
550
+ // ① 交第一份包(开闸)
551
+ await fetch(`${base}/api/recent?sessionId=s6&sort=relevance&usage=1`)
552
+ // ② 读一篇包内文档,再读一篇**不在文档包里的**文件(图片:扫描器只收 md)
553
+ emit(readCall(2, 'docs/hub.md'))
554
+ emit(toolResult(3, 'c2'))
555
+ emit(readCall(4, 'docs/screenshot.png'))
556
+ emit(toolResult(5, 'c4'))
557
+
558
+ const body = await (await fetch(`${base}/api/recent?sessionId=s6&sort=relevance`)).json()
559
+ assert.deepEqual(Object.keys(body.usage.stats).sort(), STATS_KEYS, 'stats 形状是 v0.16 的,一个键都不许加')
560
+
561
+ // 每篇文档的状态只留三个字段:状态、次数、最后一次读的时间(线上载荷要瘦)
562
+ assert.deepEqual(body.usage.lifecycle['docs/hub.md'], {
563
+ status: 'read', count: 1, lastReadAt: 1003,
564
+ })
565
+ assert.equal(body.usage.lifecycle['docs/screenshot.png'].status, 'read')
566
+
567
+ // 最近读取 = 最近一次成功 read 的文件(按 seq,不是按墙钟猜)
568
+ assert.deepEqual(body.usage.recentRead, {
569
+ rel: 'docs/screenshot.png', at: 1005, seq: 5, epochId: 1, tier: null, rank: null, inside: false,
570
+ })
571
+ // 包外明细:不在当前包里、但真的成功读过
572
+ assert.deepEqual(body.usage.outsideDocs, [
573
+ { rel: 'docs/screenshot.png', count: 1, lastReadAt: 1005, seq: 5 },
574
+ ])
575
+ // 同一份包连交两次不算「上下文变化」→ 没有最近一次 Delta
576
+ assert.equal(body.usage.latestDelta, null)
577
+ // 新字段同样只有相对路径
578
+ assert.ok(!JSON.stringify(body.usage).includes(PROJECT_ROOT), 'usage 里不许出现绝对路径')
579
+ } finally {
580
+ await close()
581
+ }
582
+ })
583
+
584
+ test('HTTP 端到端:真实改动文件 → 读后已更新;再读一次 → 修改后已重新读取', async () => {
585
+ const { base, close, emit } = await startKnitServer(
586
+ sessionWithEvents([userMessage(1, 'hub 这份文档')]), 's7',
587
+ )
588
+ try {
589
+ await fetch(`${base}/api/recent?sessionId=s7&sort=relevance&usage=1`)
590
+ emit(readCall(2, 'docs/hub.md'))
591
+ emit(toolResult(3, 'c2'))
592
+
593
+ let body = await (await fetch(`${base}/api/recent?sessionId=s7&sort=relevance`)).json()
594
+ assert.equal(body.usage.lifecycle['docs/hub.md'].status, 'read', '刚读完就是「已读」')
595
+
596
+ // 真的把文件时间往后推 —— 宿主这一轮 scan 会拿到新的 mtimeMs
597
+ const abs = join(PROJECT_ROOT, 'docs/hub.md')
598
+ const later = Date.now() / 1000 + 30
599
+ utimesSync(abs, later, later)
600
+
601
+ body = await (await fetch(`${base}/api/recent?sessionId=s7&sort=relevance`)).json()
602
+ assert.equal(
603
+ body.usage.lifecycle['docs/hub.md'].status, 'updated_after_read',
604
+ '上次成功 read 之后文件变过 —— 这只是「变过」,不是「Agent 用的是旧版」',
605
+ )
606
+ assert.equal(body.usage.lifecycle['docs/hub.md'].count, 1, '变化本身不是一次读')
607
+
608
+ // 变化之后又成功读了一次 → 事实升级为「修改后已重新读取」
609
+ emit(readCall(4, 'docs/hub.md'))
610
+ emit(toolResult(5, 'c4'))
611
+ body = await (await fetch(`${base}/api/recent?sessionId=s7&sort=relevance`)).json()
612
+ assert.equal(body.usage.lifecycle['docs/hub.md'].status, 'reread_after_update')
613
+ assert.equal(body.usage.lifecycle['docs/hub.md'].count, 2)
614
+ assert.equal(body.usage.stats.reads, 2, '两次成功 read 都算数')
615
+ } finally {
616
+ await close()
617
+ }
618
+ })
619
+
620
+ test('v0.17 修订:面板开晚了也能补记 —— 开闸那一刻回填会话已有的事件', async () => {
621
+ // 真机形状:用户在面板打开**之前**就已经让 agent 读过一篇包内文档。
622
+ const { base, close } = await startKnitServer(
623
+ sessionWithEvents([
624
+ userMessage(1, 'hub 这份文档'),
625
+ readCall(2, 'docs/hub.md'),
626
+ toolResult(3, 'c2'),
627
+ ]),
628
+ 's8',
629
+ )
630
+ try {
631
+ // ① 面板从没打开过:闸门关着,一个字节都不记(usage 根本不出现)
632
+ let body = await (await fetch(`${base}/api/recent?sessionId=s8&sort=relevance`)).json()
633
+ assert.ok(!('usage' in body), '默认关:连 usage 键都不该有')
634
+
635
+ // ② 用户读完了才打开开关:这一个请求把历史补进来
636
+ body = await (await fetch(`${base}/api/recent?sessionId=s8&sort=relevance&usage=1`)).json()
637
+ assert.equal(body.usage.stats.reads, 1, '开闸时回填会话已有的事件')
638
+ assert.equal(body.usage.lifecycle['docs/hub.md'].status, 'read')
639
+ assert.equal(body.usage.lifecycle['docs/hub.md'].count, 1)
640
+ // ⚠️ 补记的读按「我们已知最早的那份包」归因 —— 说它当时在包外,是我们不知道的事
641
+ assert.equal(body.usage.stats.firstReadTier, 'primary')
642
+ assert.equal(body.usage.stats.firstReadEpoch, 1)
643
+ assert.equal(body.usage.stats.outside, 0, '不许把包内文档说成包外')
644
+ assert.deepEqual(body.usage.outsideDocs, [])
645
+ assert.equal(body.usage.recentRead.rel, 'docs/hub.md')
646
+ assert.equal(body.usage.recentRead.inside, true)
647
+
648
+ // ③ 同一个会话不再回填第二次:再来一次请求,计数不动
649
+ body = await (await fetch(`${base}/api/recent?sessionId=s8&sort=relevance&usage=1`)).json()
650
+ assert.equal(body.usage.stats.reads, 1, '一个会话只回填一次')
651
+ } finally {
652
+ await close()
653
+ }
654
+ })
@@ -523,3 +523,42 @@ test('i18n: 宿主的每个 Context Pack 理由码都有中英译文', async ()
523
523
  assert.ok(used.has(key), `ZH 里的 why.${key} 已经没有一个宿主理由码在用它`)
524
524
  }
525
525
  })
526
+
527
+ /* ── v0.17 文档生命周期:数据层英文,界面按语言映射 ─────────────────── */
528
+
529
+ test('词典:v0.17 的十六条生命周期 / 变化文案中英都对得上', () => {
530
+ const { registered } = boot('zh')
531
+ const { zh, en } = registered.knit
532
+
533
+ // 状态值本身在数据层是英文(unread / read / ...),中文只活在词典里(SDD §15.4)
534
+ const expected = {
535
+ 'usage.recentRead': ['最近读取:{rel} · {time}', 'Recently read: {rel} · {time}'],
536
+ 'usage.outsideDocs': ['上下文外读取 · {n} 篇', 'Read outside the pack · {n}'],
537
+ 'usage.deltaTitle': ['上下文刚刚变化', 'Context just changed'],
538
+ 'usage.deltaEnter': ['进入', 'Entered'],
539
+ 'usage.deltaLeave': ['离开', 'Left'],
540
+ 'usage.deltaMove': ['换层', 'Moved tier'],
541
+ 'usage.deltaTask': ['任务上下文已更新', 'Task context updated'],
542
+ 'usage.deltaMore': ['还有 {n} 条', '+{n} more'],
543
+ 'lifecycle.unread': ['未读', 'Unread'],
544
+ 'lifecycle.read': ['已读', 'Read'],
545
+ 'lifecycle.readCount': ['已读 ×{n}', 'Read ×{n}'],
546
+ 'lifecycle.updatedAfterRead': ['读后已更新', 'Updated after read'],
547
+ 'lifecycle.rereadAfterUpdate': ['修改后已重新读取', 'Re-read after update'],
548
+ 'tierName.primary': ['主要', 'Primary'],
549
+ 'tierName.supporting': ['辅助', 'Supporting'],
550
+ 'tierName.related': ['相关', 'Related'],
551
+ }
552
+
553
+ for (const [key, [zhText, enText]] of Object.entries(expected)) {
554
+ assert.equal(zh[key], zhText, `ZH ${key}`)
555
+ assert.equal(en[key], enText, `EN ${key}`)
556
+ assert.ok(!/[\u4e00-\u9fff]/.test(en[key]), `EN ${key} 里不许出现汉字`)
557
+ }
558
+ // 四档事实状态只陈述事实:不许写成「Agent 还不知道最新版」这类推断
559
+ const stateWords = ['lifecycle.unread', 'lifecycle.read', 'lifecycle.updatedAfterRead', 'lifecycle.rereadAfterUpdate']
560
+ for (const key of stateWords) {
561
+ assert.ok(!/Agent|还不知道|旧版|没看到|忽略了/.test(zh[key]), `ZH ${key} 不许写推断`)
562
+ assert.ok(!/Agent|outdated|stale version|missed|ignored/i.test(en[key]), `EN ${key} 不许写推断`)
563
+ }
564
+ })
@@ -173,7 +173,7 @@ test('clampRatio:夹在 20%–80%,非法值回落默认', () => {
173
173
  assert.equal(clampRatio(NaN), 0.46)
174
174
  })
175
175
 
176
- test('渲染:预览高度接到 maxHeight 上,且拖拽条存在', async () => {
176
+ test('渲染:预览高度是**固定高度**(不是最高高度),且拖拽条存在', async () => {
177
177
  installFetch((url) => (url.includes('/api/doc')
178
178
  ? { ok: true, rel: '技术方案.md', title: '技术方案', text: '# T', truncated: false }
179
179
  : listPayload()))
@@ -186,7 +186,9 @@ test('渲染:预览高度接到 maxHeight 上,且拖拽条存在', async ()
186
186
 
187
187
  const panel = panelOf(after)[0]
188
188
  assert.ok(panel, '应有预览面板')
189
- assert.equal(panel.props.style.maxHeight, '46%', '默认高度应接到 maxHeight')
189
+ assert.equal(panel.props.style.height, '46%', '打开期间高度固定:加载中 / 换篇都不许再动列表的高度')
190
+ assert.equal(panel.props.style.maxHeight, undefined,
191
+ '不许走 maxHeight —— 那样高度由内容决定,正文一到列表就跟着伸缩(2026-10-04 交互审:「我一点它就跳,闪得很快」)')
190
192
  assert.equal(byClass(after, 'knit-resize').length, 1, '应有拖拽条')
191
193
  })
192
194