agentworkshop 0.7.34 → 0.7.37

package/scripts/test-lru.mjs

@@ -2,12 +2,22 @@
 import { LruMap } from '../shared/lru.mjs'
 
 let pass = 0, fail = 0
-const check = (n, ok, d = '') => { if (ok) { pass++; console.log('  PASS  ' + n) } else { fail++; console.log('  FAIL  ' + n + (d ? '  — ' + d : '')) } }
+const check = (n, ok, d = '') => {
+  if (ok) {
+    pass++
+    console.log('  PASS  ' + n)
+    return
+  }
+  fail++
+  console.log('  FAIL  ' + n + (d ? '  — ' + d : ''))
+}
 
 console.log('\n━━━ 1. 容量与逐出 ━━━')
 {
   const l = new LruMap(3)
-  l.set('a', 1); l.set('b', 2); l.set('c', 3)
+  l.set('a', 1)
+  l.set('b', 2)
+  l.set('c', 3)
   check('未超限 size=3', l.size === 3)
   l.set('d', 4)
   check('超限后 size 仍为 3', l.size === 3, 'size=' + l.size)
@@ -19,9 +29,11 @@ console.log('\n━━━ 1. 容量与逐出 ━━━')
 console.log('\n━━━ 2. 访问提升(LRU 语义核心) ━━━')
 {
   const l = new LruMap(3)
-  l.set('a', 1); l.set('b', 2); l.set('c', 3)
-  l.get('a')            // a 变最新
-  l.set('d', 4)         // 应逐出 b(而非 a)
+  l.set('a', 1)
+  l.set('b', 2)
+  l.set('c', 3)
+  l.get('a') // a 变最新
+  l.set('d', 4) // 应逐出 b(而非 a)
   check('被访问过的 a 存活', l.has('a'))
   check('未访问的 b 被逐出', !l.has('b'))
   check('新写入的 d 在', l.has('d'))
@@ -31,8 +43,14 @@ console.log('\n━━━ 3. getOrSet 单入口 ━━━')
 {
   const l = new LruMap(2)
   let computed = 0
-  const v1 = l.getOrSet('k', () => { computed++; return 'V' })
-  const v2 = l.getOrSet('k', () => { computed++; return 'V' })
+  const v1 = l.getOrSet('k', () => {
+    computed++
+    return 'V'
+  })
+  const v2 = l.getOrSet('k', () => {
+    computed++
+    return 'V'
+  })
   check('值正确', v1 === 'V' && v2 === 'V')
   check('只计算一次(二次命中缓存)', computed === 1, 'computed=' + computed)
   check('命中数=1', l.hits === 1, 'hits=' + l.hits)
@@ -52,7 +70,7 @@ console.log('\n━━━ 5. 对比 clear() 抖动:LRU 不应造成全量穿透
   const l = new LruMap(500)
   for (let i = 0; i < 500; i++) l.set('k' + i, i)
   // 旧实现:第 501 次写入触发 clear(),之后 500 个条目全部回源
-  l.set('k500', 500)   // 触发一次逐出:k0 出局
+  l.set('k500', 500) // 触发一次逐出:k0 出局
   let survived = 0
   for (let i = 0; i < 500; i++) if (l.has('k' + i)) survived++
   // 500 条候选中恰好逐出 1 条 → 存活 499(旧 clear() 实现此处存活 0)
@@ -62,13 +80,18 @@ console.log('\n━━━ 5. 对比 clear() 抖动:LRU 不应造成全量穿透
 console.log('\n━━━ 6. 边界与回调 ━━━')
 {
   let evictedKeys = []
-  const l = new LruMap(2, (k) => evictedKeys.push(k))
-  l.set('a', 1); l.set('b', 2); l.set('c', 3)
+  const l = new LruMap(2, k => evictedKeys.push(k))
+  l.set('a', 1)
+  l.set('b', 2)
+  l.set('c', 3)
   check('onEvict 收到逐出键', evictedKeys.join(',') === 'a', evictedKeys.join(','))
   check('delete 可用', l.delete('b') === true && !l.has('b'))
   check('clear 后为空', (l.clear(), l.size === 0))
   let threw = false
-  try { new LruMap(0) } catch { threw = true }
+  try {
+    new LruMap(0)
+  }
+  catch { threw = true }
   check('max<1 抛错', threw)
   const s = l.stats()
   check('stats 形状正确', typeof s.hitRate === 'number' && s.max === 2)

package/scripts/test-memory-month-query.mjs

@@ -9,7 +9,15 @@ import { readFileSync } from 'node:fs'
 import { createMemoryRepo } from '../server/services/workshop/db/memory.repo.ts'
 
 let pass = 0, fail = 0
-const check = (n, ok, d = '') => { if (ok) { pass++; console.log('  PASS  ' + n) } else { fail++; console.log('  FAIL  ' + n + (d ? '  — ' + d : '')) } }
+const check = (n, ok, d = '') => {
+  if (ok) {
+    pass++
+    console.log('  PASS  ' + n)
+    return
+  }
+  fail++
+  console.log('  FAIL  ' + n + (d ? '  — ' + d : ''))
+}
 
 // 用真实 schema 建库:保证测试与生产表结构(索引/触发器/唯一约束)完全一致
 const db = new DatabaseSync(':memory:')
@@ -30,9 +38,9 @@ for (const [id, kind, at] of [
   ['m1', 'episodic-task', '2026-09-01T00:00:00.000Z'],
   ['m2', 'episodic-task', '2026-09-15T12:00:00.000Z'],
   ['m3', 'episodic-task', '2026-09-30T23:59:59.000Z'],
-  ['m4', 'episodic-task', '2026-10-01T00:00:00.000Z'],   // 下月首刻,必须排除
+  ['m4', 'episodic-task', '2026-10-01T00:00:00.000Z'], // 下月首刻,必须排除
   ['m5', 'episodic-session', '2026-09-10T00:00:00.000Z'], // 不同 kind,必须排除
-  ['m6', 'episodic-task', '2025-12-31T23:00:00.000Z'],    // 去年 12 月
+  ['m6', 'episodic-task', '2025-12-31T23:00:00.000Z'], // 去年 12 月
   ['m7', 'episodic-task', '2026-01-01T00:00:00.000Z'],
 ]) {
   ins.run(id, AGENT, kind, id, id, id, id, at)

package/scripts/test-plugin-hardening.mjs

@@ -10,8 +10,13 @@ import { isPathInside, createRouteTable } from '../sdk/context.mjs'
 
 let pass = 0, fail = 0
 const check = (name, ok, detail = '') => {
-  if (ok) { pass++; console.log(`  PASS  ${name}`) }
-  else { fail++; console.log(`  FAIL  ${name}${detail ? '  — ' + detail : ''}`) }
+  if (ok) {
+    pass++
+    console.log(`  PASS  ${name}`)
+    return
+  }
+  fail++
+  console.log(`  FAIL  ${name}${detail ? '  — ' + detail : ''}`)
 }
 
 console.log('\n━━━ 1. 路径包含判定(P0-2) ━━━')

package/scripts/test-plugin-lifecycle.mjs

@@ -0,0 +1,173 @@
+/**
+ * 回归测试 —— 插件生命周期的「回收真的会发生」
+ * 运行: node scripts/test-plugin-lifecycle.mjs
+ * 退出码: 0 全通过 / 1 有失败
+ *
+ * 背景(为什么需要这个测试):
+ *   sdk/context.mjs 的 createPluginContext 曾经**漏接** opts.onDispose —— 宿主
+ *   (host.mjs perPluginDisposables)明明注入了回收登记口,SDK 却把清理函数塞进一个
+ *   永远不会被 drain 的模块内数组。后果:ctx.onDispose / ctx.timer.* /
+ *   ctx.subscriptions.add 登记的清理**永不执行**,热重载后旧定时器继续跑,关停前
+ *   200ms 的 kv 写入丢失 —— 而文档一直承诺"服务关闭自动回收"。
+ *   该缺陷无任何测试覆盖,故在此把契约钉死。
+ */
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { HookBus } from '../sdk/hooks.mjs'
+import { createPluginContext, createRouteTable } from '../sdk/context.mjs'
+import { LIFECYCLE_EVENTS, CLIENT_EVENTS } from '../sdk/lifecycle.mjs'
+
+let pass = 0
+let fail = 0
+const check = (name, ok, detail = '') => {
+  if (ok) {
+    pass++
+    console.log(`  PASS  ${name}`)
+    return
+  }
+  fail++
+  console.log(`  FAIL  ${name}${detail ? '  — ' + detail : ''}`)
+}
+
+const sandbox = mkdtempSync(join(tmpdir(), 'aw-plugin-lifecycle-'))
+const dataDir = join(sandbox, 'data')
+
+/** 装配一个最小 ctx:宿主侧的 onDispose 换成可观察的收集器 */
+function makeCtx(extra = {}) {
+  const collected = []
+  const ctx = createPluginContext({
+    name: 'probe',
+    scope: 'builtin',
+    dir: sandbox,
+    hooks: new HookBus({ name: 'probe' }),
+    logger: { info: () => {} },
+    config: { effective: { 'plugins.probe.k': 1 } },
+    paths: { home: sandbox, configRoot: sandbox, dataDir },
+    emitter: { registerRoute: () => true },
+    onDispose: (fn) => {
+      collected.push(fn)
+      return fn
+    },
+    selfOrigin: () => '',
+    ...extra,
+  })
+  return { ctx, collected }
+}
+
+console.log('\n━━━ 1. onDispose 必须转发到宿主回收队列 ━━━')
+{
+  const { ctx, collected } = makeCtx()
+  let ran = 0
+  ctx.onDispose(() => {
+    ran++
+  })
+  check('ctx.onDispose(fn) 进入宿主队列', collected.length >= 1, `collected=${collected.length}`)
+  for (const fn of collected) fn()
+  check('宿主逐个调用后清理真的执行', ran === 1, `ran=${ran}`)
+}
+
+console.log('\n━━━ 2. ctx.timer 的定时器必须可被关停回收 ━━━')
+{
+  const { ctx, collected } = makeCtx()
+  const before = collected.length
+  const id = ctx.timer.setInterval(() => {}, 10_000)
+  const added = collected.length - before
+  check('setInterval 自动登记回收', added === 1, `added=${added}`)
+  for (const fn of collected) fn()
+  // Node 的 Timeout 被 clear 后 _destroyed 为 true;用公开可观察行为代替内部字段:
+  // 清理后不应再有回调触发(这里以 clearInterval 不抛 + hasRef 关闭为判据)
+  check('clearInterval 已执行(定时器不再保持事件循环)', typeof id === 'object' && id.hasRef() === false)
+}
+
+console.log('\n━━━ 3. ctx.subscriptions.add 与 onDispose 同队列 ━━━')
+{
+  const { ctx, collected } = makeCtx()
+  let disposed = 0
+  const bump = () => {
+    disposed++
+  }
+  ctx.subscriptions.add({ dispose: bump })
+  ctx.subscriptions.add(bump)
+  for (const fn of collected) fn()
+  check('{ dispose() } 形式被执行', disposed === 2, `disposed=${disposed}`)
+}
+
+console.log('\n━━━ 4. kv 关停兜底必须登记(否则退出前 200ms 写入丢失)━━━')
+{
+  // 用独立插件名:同名 kv 文件会被前面的用例顺带 flush 出来,导致"尚未落盘"断言失真
+  const { ctx, collected } = makeCtx({ name: 'probe-kv' })
+  ctx.kv.set('counter', 41)
+  ctx.kv.bump('counter')
+  check('内存态即时可见', ctx.kv.get('counter') === 42, `got=${ctx.kv.get('counter')}`)
+  const kvFile = join(dataDir, 'plugins', 'probe-kv', 'kv.json')
+  check('防抖期内尚未落盘(证明下面的 flush 来自回收钩子)', !existsSync(kvFile))
+  for (const fn of collected) fn()
+  const ok = existsSync(kvFile) && JSON.parse(readFileSync(kvFile, 'utf8')).counter === 42
+  check('执行回收钩子后 kv 已同步落盘', ok)
+}
+
+console.log('\n━━━ 5. 无宿主注入口时的本地兜底(单测/独立装配)━━━')
+{
+  // 不传 onDispose:不应抛错,清理留在本地数组(无法从外部 drain,但注册必须成功)
+  const ctx = createPluginContext({
+    name: 'probe2',
+    scope: 'user',
+    dir: sandbox,
+    hooks: new HookBus({ name: 'probe2' }),
+    logger: {},
+    config: { effective: {} },
+    paths: { home: sandbox, configRoot: sandbox, dataDir },
+    emitter: { registerRoute: () => true },
+    selfOrigin: () => '',
+  })
+  let threw = null
+  try {
+    ctx.onDispose(() => {})
+    ctx.subscriptions.add(() => {})
+  }
+  catch (err) {
+    threw = err
+  }
+  check('无 onDispose 注入时注册不抛错', threw === null, String(threw?.message ?? ''))
+}
+
+console.log('\n━━━ 6. ctx.route 返回布尔(与 sdk/index.d.mts 契约一致)━━━')
+{
+  const { ctx } = makeCtx()
+  check('注册成功 → true', ctx.route('GET', '/ok', () => 1) === true)
+  const t = createRouteTable()
+  const first = () => 'a'
+  const second = () => 'b'
+  check('首次注册 → true', t.register('p', 'GET', '/x', first) === true)
+  // 契约是「同键后注册覆盖」而非拒绝(host.registerRoute 依赖返回值决定是否记账)
+  check('同键再注册 → true(覆盖语义)', t.register('p', 'GET', '/x', second) === true)
+  check('resolve 取到最新 handler', t.resolve('p', 'GET', '/x') === second)
+  check('大小写/缺前导斜杠归一化后同键', t.resolve('p', 'get', 'x') === second)
+  check('非法 handler → false', t.register('p', 'GET', '/y', null) === false)
+}
+
+console.log('\n━━━ 7. scope 取值面完整(builtin / project / user)━━━')
+{
+  for (const scope of ['builtin', 'project', 'user']) {
+    const { ctx } = makeCtx({ scope })
+    check(`scope=${scope} 原样透出`, ctx.scope === scope, `got=${ctx.scope}`)
+  }
+}
+
+console.log('\n━━━ 8. 生命周期事件清单覆盖真实发射面 ━━━')
+{
+  const need = ['plugin:host:init', 'plugins:reloaded', 'config:changed', 'event:permissions:changed', 'event:*', 'daq:sample', 'daq:frame', 'dcw:write', 'line:start', 'line:stop', 'server:close']
+  const missing = need.filter(e => !LIFECYCLE_EVENTS.includes(e))
+  check('LIFECYCLE_EVENTS 无缺项', missing.length === 0, `missing=${missing.join(',')}`)
+  check('服务端通配是裸 \'*\'(不是 event:*)', LIFECYCLE_EVENTS.includes('event:*') && !LIFECYCLE_EVENTS.includes('*'))
+  const cneed = ['client:init', 'event:*', 'page:change', 'i18n:changed', 'client:destroy']
+  const cmissing = cneed.filter(e => !CLIENT_EVENTS.includes(e))
+  check('CLIENT_EVENTS 无缺项', cmissing.length === 0, `missing=${cmissing.join(',')}`)
+  check('客户端通配是 \'event:*\'(与服务端相反)', CLIENT_EVENTS.includes('event:*'))
+}
+
+rmSync(sandbox, { recursive: true, force: true })
+
+console.log(`\n${fail ? '✖' : '✅'} 插件生命周期:${pass} 通过 / ${fail} 失败`)
+process.exit(fail ? 1 : 0)

package/scripts/test-rollback-index.mjs

@@ -2,18 +2,58 @@
  * 回归 + 性能测试 —— DCW 回滚账本索引化(P1-8/P1-9)
  * 验证:索引版与原「逆序全扫」版**结果完全一致**,且热路径显著更快。
  * 运行: node scripts/test-rollback-index.mjs
+ *
+ * 注:被导入的 recipe-rollback.repo.ts 经 '@/' 别名引用 shared/config/home.mjs,
+ * 而 Node 原生 ESM 不认别名/省略扩展名 —— 必须先注册解析钩子,否则本脚本
+ * 在 import 阶段就 ERR_MODULE_NOT_FOUND(与 test-log-flooding.mjs 同一机制)。
  */
-import { RecipeRollBackRepo } from '../server/services/workshop/dcw/recipe-rollback.repo.ts'
+import { register } from 'node:module'
+
+register(new URL('./_audit/ts-resolve-hook.mjs', import.meta.url).href)
+
+const { RecipeRollBackRepo } = await import('../server/services/workshop/dcw/recipe-rollback.repo.ts')
 
 let pass = 0, fail = 0
-const check = (n, ok, d = '') => { if (ok) { pass++; console.log('  PASS  ' + n) } else { fail++; console.log('  FAIL  ' + n + (d ? '  — ' + d : '')) } }
+const check = (n, ok, d = '') => {
+  if (ok) {
+    pass++
+    console.log('  PASS  ' + n)
+    return
+  }
+  fail++
+  console.log('  FAIL  ' + n + (d ? '  — ' + d : ''))
+}
 
-// ---- 参照实现:旧版线性全扫语义 ----
+// ---- 参照实现:旧版线性全扫语义(结果必须与索引版逐条一致) ----
 const ref = {
-  lastAnchorOf: (anchors, nodeId) => { for (let i = anchors.length - 1; i >= 0; i--) if (anchors[i].nodeId === nodeId) return anchors[i]; return undefined },
-  lastStableAnchor: (anchors, nodeId) => { for (let i = anchors.length - 1; i >= 0; i--) { const a = anchors[i]; if (a.nodeId === nodeId && a.prevValue != null && a.prevValue !== a.newValue) return a } return undefined },
-  lastStableBefore: (anchors, nodeId, atMs) => { for (let i = anchors.length - 1; i >= 0; i--) { const a = anchors[i]; if (a.nodeId !== nodeId || a.prevValue == null || a.prevValue === a.newValue) continue; if (Date.parse(a.at) <= atMs) return a } return undefined },
-  lastRollbackAnchor: (anchors, nodeId) => { for (let i = anchors.length - 1; i >= 0; i--) { const a = anchors[i]; if (a.nodeId === nodeId && a.source === 'rollback') return a } return undefined },
+  lastAnchorOf(anchors, nodeId) {
+    for (let i = anchors.length - 1; i >= 0; i--) {
+      if (anchors[i].nodeId === nodeId) return anchors[i]
+    }
+    return undefined
+  },
+  lastStableAnchor(anchors, nodeId) {
+    for (let i = anchors.length - 1; i >= 0; i--) {
+      const a = anchors[i]
+      if (a.nodeId === nodeId && a.prevValue != null && a.prevValue !== a.newValue) return a
+    }
+    return undefined
+  },
+  lastStableBefore(anchors, nodeId, atMs) {
+    for (let i = anchors.length - 1; i >= 0; i--) {
+      const a = anchors[i]
+      if (a.nodeId !== nodeId || a.prevValue == null || a.prevValue === a.newValue) continue
+      if (Date.parse(a.at) <= atMs) return a
+    }
+    return undefined
+  },
+  lastRollbackAnchor(anchors, nodeId) {
+    for (let i = anchors.length - 1; i >= 0; i--) {
+      const a = anchors[i]
+      if (a.nodeId === nodeId && a.source === 'rollback') return a
+    }
+    return undefined
+  },
 }
 
 const repo = new RecipeRollBackRepo()
@@ -22,8 +62,8 @@ const N = 3000
 const t0 = Date.now()
 for (let i = 0; i < N; i++) {
   const nodeId = NODES[i % NODES.length]
-  const prev = i % 7 === 0 ? null : i - 1          // 制造 prevValue==null 的锚
-  const same = i % 11 === 0                        // 制造 prevValue==newValue 的锚
+  const prev = i % 7 === 0 ? null : i - 1 // 制造 prevValue==null 的锚
+  const same = i % 11 === 0 // 制造 prevValue==newValue 的锚
   repo.appendAnchor({
     nodeId,
     prevValue: prev,
@@ -36,7 +76,7 @@ for (let i = 0; i < N; i++) {
 console.log(`\n写入 ${N} 锚耗时 ${Date.now() - t0}ms`)
 
 console.log('\n━━━ 1. 索引版与线性扫描语义一致 ━━━')
-const all = repo.listAnchors({ limit: N + 10 })   // 正序取回全部(倒序后再 reverse)
+const all = repo.listAnchors({ limit: N + 10 }) // 正序取回全部(倒序后再 reverse)
 const anchorsAsc = [...all].reverse()
 for (const nodeId of NODES) {
   const a1 = repo.lastAnchorOf(nodeId), a2 = ref.lastAnchorOf(anchorsAsc, nodeId)
@@ -65,15 +105,33 @@ const s = repo.stats()
 check('stats.open 与索引一致', s.open === repo.listOpenRecords().length, `${s.open} vs ${repo.listOpenRecords().length}`)
 
 console.log('\n━━━ 3. 热路径性能(索引 vs 线性) ━━━')
+// 测量场景的选择很关键:用「尾部有锚」的节点测,**线性实现逆序第 3 步就命中**,
+// 两者都在亚毫秒级,ms 分辨率下测到的只是噪声(实测过 1ms vs 0ms 的假阴性)。
+// 索引真正解决的是**冷查询**:查询的节点在表中没有锚(或锚在很靠前),
+// 线性实现必须逆序扫完全表,索引实现是 O(1)。这才是应该被断言的性质。
+const COLD = 'n-absent'
+check('冷查询结果一致(索引 vs 线性)', repo.lastStableAnchor(COLD) === ref.lastStableAnchor(anchorsAsc, COLD))
+
+/** 单调高精度计时(ms,小数) */
+const nowMs = () => Number(process.hrtime.bigint()) / 1e6
 const ITER = 20000
-let t = Date.now()
-for (let i = 0; i < ITER; i++) repo.lastStableAnchor(NODES[i % 3])
-const indexedMs = Date.now() - t
-t = Date.now()
-for (let i = 0; i < ITER; i++) ref.lastStableAnchor(anchorsAsc, NODES[i % 3])
-const linearMs = Date.now() - t
-console.log(`  索引 ${indexedMs}ms  vs  线性 ${linearMs}ms  (${(linearMs / Math.max(indexedMs, 1)).toFixed(1)}x)`)
-check('索引版不慢于线性版', indexedMs <= linearMs, `${indexedMs} vs ${linearMs}`)
+// 预热(V8 JIT + 索引首次构建),否则首轮把编译开销算进结果
+for (let i = 0; i < 2000; i++) {
+  repo.lastStableAnchor(COLD)
+  ref.lastStableAnchor(anchorsAsc, COLD)
+}
+
+let t = nowMs()
+for (let i = 0; i < ITER; i++) repo.lastStableAnchor(COLD)
+const indexedMs = nowMs() - t
+t = nowMs()
+for (let i = 0; i < ITER; i++) ref.lastStableAnchor(anchorsAsc, COLD)
+const linearMs = nowMs() - t
+console.log(`  冷查询 ×${ITER}:索引 ${indexedMs.toFixed(2)}ms  vs  线性 ${linearMs.toFixed(2)}ms  (快 ${(linearMs / Math.max(indexedMs, 0.001)).toFixed(0)}x)`)
+// 断言留 1.5x 余量:索引是 O(1)、线性是 O(表长),在 20000×3000 规模下差距是数量级,
+// 不应用浮点相等去卡死(CI 机器抖动会误报)
+check('冷查询索引版显著快于线性版(≥1.5x)', indexedMs * 1.5 <= linearMs,
+  `索引 ${indexedMs.toFixed(2)}ms vs 线性 ${linearMs.toFixed(2)}ms`)
 
 console.log(`\n━━━ 结果:${pass} passed, ${fail} failed ━━━\n`)
 process.exit(fail === 0 ? 0 : 1)

package/scripts/test-sdk-surface.mjs

@@ -18,8 +18,11 @@ const HERE = dirname(fileURLToPath(import.meta.url))
 const ROOT = resolve(HERE, '..')
 
 let failures = 0
-const pass = (msg) => console.log(`  ✔ ${msg}`)
-const fail = (msg) => { failures += 1; console.error(`  ✘ ${msg}`) }
+const pass = msg => console.log(`  ✔ ${msg}`)
+const fail = (msg) => {
+  failures += 1
+  console.error(`  ✘ ${msg}`)
+}
 
 /** 从 .d.mts 源码抽取 `export declare const <NAME>: readonly [...]` 的字面量集合 */
 function extractTuple(file, name) {
@@ -32,7 +35,7 @@ function extractTuple(file, name) {
     .split(',')
     .map(s => s.trim())
     .filter(Boolean)
-    .map(s => {
+    .map((s) => {
       const q = s.match(/^'(.*)'$/) ?? s.match(/^"(.*)"$/)
       return q ? q[1] : s
     })

package/sdk/client.mjs

@@ -6,7 +6,12 @@
 // ctx 形态(浏览器侧,自包含、零框架依赖):
 //   ctx.name / ctx.sdkVersion
 //   ctx.hooks   客户端本地 HookBus(client:init / event:* / page:change / client:destroy)
-//   ctx.on(type, fn)      scene 实时事件订阅(与 WS 同源;'*' 通配)——自动登记 pagehide 回收
+//   ctx.on(type, fn)      scene 实时事件订阅 —— type 传 **scene 事件名本身**(如
+//                         'daq.reading' / 'line.start'),内部装到 `event:<type>`;
+//                         要收全部 scene 事件请传字面量 'event:*'(唯一通配写法)。
+//                         ⚠️ 生命周期钩子(client:init / page:change / i18n:changed /
+//                         client:destroy)不走这里,用 ctx.hooks.on(...) 直订。
+//                         pagehide 时自动回收。
 //   ctx.fetch(path, …)    同源平台 API 助手(JSON;自动解信封 data)
 //   ctx.el(tag, attrs, children)   DOM 助手(挂到任意面板/宿主节点)
 //   ctx.mount(selector|el, node)   挂载节点(缺失时挂 body 角落)
@@ -22,7 +27,10 @@ import { HookBus } from './hooks.mjs'
 
 export const CLIENT_SDK_VERSION = '0.3.0'
 
-function el(tag, attrs = {}, children = []) {
+/** DOM 构建助手。**具名导出** —— client.d.mts 早就声明了 `export function el(...)`,
+ *  但运行时只放进 default 对象,`import { el } from 'agentworkshop/sdk/client'` 会拿到
+ *  undefined。这里补成真具名导出,让类型声明与运行时一致。 */
+export function el(tag, attrs = {}, children = []) {
   const node = document.createElement(tag)
   for (const [k, v] of Object.entries(attrs)) {
     if (k === 'style') node.style.cssText = v
@@ -131,11 +139,12 @@ export function createClientContext({ name, eventBridge, baseUrl = '', ui, t, ge
     disposables.push(offBridge)
   }
 
-  // 页面卸载自动回收(pagehide 覆盖 bfcache 场景)
-  if (typeof document !== 'undefined') {
-    document.addEventListener('visibilitychange', () => {
-      if (document.visibilityState === 'hidden') ctx.dispose()
-    }, { once: true })
+  // 页面真正离开时回收。**用 pagehide 而不是 visibilitychange→hidden**:
+  // 后者在"切标签页/最小化"时就会触发,而 dispose() 是一次性的(disposed 标志不可回退),
+  // 于是用户切一次标签页 → 所有客户端插件永久失效,直到刷新页面。
+  // pagehide 覆盖「导航离开 + bfcache 入栈」两种真实卸载,切标签页不受影响。
+  if (typeof window !== 'undefined') {
+    window.addEventListener('pagehide', () => ctx.dispose(), { once: true })
   }
 
   return ctx

package/sdk/context.mjs

@@ -2,14 +2,16 @@
 // AgentWorkShop SDK — 服务端插件上下文工厂（宿主调用;插件经 setup(ctx) 获得）
 // ------------------------------------------------------------
 // ctx 形态(运行时完整变量面):
-//   身份    ctx.name / ctx.scope('home'|'project') / ctx.dir / ctx.sdkVersion
-//   钩子    ctx.hooks   HookBus(生命周期 + event:*)                  [SDK]
+//   身份    ctx.name / ctx.scope('builtin'|'project'|'user') / ctx.dir / ctx.sdkVersion
+//   钩子    ctx.hooks   HookBus 门面(生命周期 + event:*)             [SDK]
 //   日志    ctx.logger  { debug, info, warn, error } 插件名前缀      [SDK]
-//   配置    ctx.config  { get(key), all(), onChange(fn) }            [SDK]
+//   配置    ctx.config  { get,all,onChange,defineGroup,defineField,
+//                         removeGroup,removeField,groups,fields }    [SDK]
 //   存储    ctx.kv      { get,set,all,bump } 内存态+防抖落盘          [SDK]
 //   定时    ctx.timer   { setInterval, setTimeout } 服务关闭自动回收  [SDK]
 //   清理    ctx.onDispose(fn) / ctx.subscriptions                    [SDK]
-//   路由    ctx.route(method, path, handler) → /api/plugins/<name>… [SDK]
+//   路由    ctx.route(method, path, handler) → boolean               [SDK]
+//           /api/plugins/<name><path>;鉴权由插件入口 auth 字段声明
 //   平台    ctx.api     平台 REST 客户端(lines/daq/dcw/twins/teams…) [SDK]
 //   网络    ctx.http    { get, post } 带超时 fetch(仅 http/https)    [SDK]
 //   事件    ctx.events  { on(type,fn), off }  scene 实时事件          [SDK]
@@ -36,6 +38,10 @@ function safeUrl(raw, timeoutMs = 8000) {
  */
 export function createPluginContext(opts) {
   const { name, scope, dir, hooks, config, paths, emitter } = opts
+  // 宿主回收登记口(host.mjs perPluginDisposables)。**必须转发**:此前这里漏接
+  // opts.onDispose,导致 ctx.onDispose / ctx.timer.* / ctx.subscriptions.add 登记的
+  // 清理永不执行 —— 定时器泄漏 + 退出前 200ms 的 kv 写入丢失,而文档承诺"自动回收"。
+  const hostOnDispose = typeof opts.onDispose === 'function' ? opts.onDispose : null
   // 规范化 logger:宿主实现缺级时兜底 no-op(插件可用全套 debug/info/warn/error)
   const logger = {
     debug: () => {},
@@ -45,10 +51,14 @@ export function createPluginContext(opts) {
     ...(opts.logger ?? {}),
   }
 
-  // ---- 订阅回收(VSCode subscriptions 范式):服务关闭时宿主逐个调用 ----
+  // ---- 订阅回收(VSCode subscriptions 范式):服务关闭/热重载时宿主逐个调用 ----
+  //  有宿主注入口 → 直接进宿主回收队列(唯一事实源,避免两处各存一份被调用两次);
+  //  无宿主(单测/独立装配)→ 留在本地数组兜底。
   const disposables = []
   const onDispose = (fn) => {
-    if (typeof fn === 'function') disposables.push(fn)
+    if (typeof fn !== 'function') return fn
+    if (hostOnDispose) hostOnDispose(fn)
+    else disposables.push(fn)
     return fn
   }
 
@@ -157,17 +167,19 @@ export function createPluginContext(opts) {
      *  visibleLineIds(user)  → Set<lineId>|null(全量)
      *  listGrants(userId)    → [{lineId,mode,grantedBy,grantedAt}]
      *  setGrants(userId, [{lineId,mode}]) → 写授权(需 admin 上下文)
-     *  变更事件: hooks.on('permissions:changed', { userId }) */
+     *  变更事件:ctx.events.on('permissions:changed', fn)
+     *  ——宿主把平台事件统一加 `event:` 前缀,故订阅要走 ctx.events(它会补前缀),
+     *    直接 ctx.hooks.on('permissions:changed') 永远不触发。 */
     permissions: opts.permissions ?? {
       lineMode: () => 'none',
       visibleLineIds: () => new Set(),
       listGrants: () => [],
       setGrants: () => { throw new Error('[sdk] ctx.permissions 未由宿主注入') },
     },
-    /** 订阅式清理对象({ dispose(){} })集中登记 */
+    /** 订阅式清理对象({ dispose(){} })集中登记(与 ctx.onDispose 同一回收队列) */
     subscriptions: {
       add: (d) => {
-        disposables.push(typeof d === 'function' ? d : (...a) => d.dispose?.(...a))
+        onDispose(typeof d === 'function' ? d : (...a) => d.dispose?.(...a))
         return d
       },
     },

package/sdk/examples/line-sentinel/client.mjs

@@ -14,17 +14,24 @@ export function setup(ctx) {
   let n = 0
   let alarms = 0
 
-  ctx.on('daq:sample', () => {
+  // ctx.on(type) 的 type 是 **scene 事件名本身**(浏览器可见的那一类),内部装到 `event:<type>`。
+  // 真实 scene 事件清单见 daq-controller.ts 的 broadcast 调用点:
+  //   daq.reading / daq.frame / daq.alarm / daq.alarm.changed / daq.node.changed /
+  //   daq.controller / device.updated / error
+  // ⚠️ 服务端生命周期钩子(daq:sample / line:start / line:stop)不会过桥到浏览器,
+  //    在客户端订阅它们只会得到永不触发的静默空订阅。
+  ctx.on('daq.reading', () => {
     n++
     badge.textContent = `🛡 line-sentinel · ${n} 样本 · ${alarms} 告警`
   })
 
-  // 服务端告警状态变化经 event 桥可见(ops.log 或轮询 stats;此处演示事件订阅)
-  ctx.on('event:line.start', () => {
-    badge.style.borderColor = '#35e0a0'
+  ctx.on('daq.alarm', () => {
+    alarms++
+    badge.style.borderColor = '#ff6b6b'
+    badge.textContent = `🛡 line-sentinel · ${n} 样本 · ${alarms} 告警`
   })
-  ctx.on('event:line.stop', () => {
-    badge.style.borderColor = 'rgba(53,224,160,.35)'
+  ctx.on('daq.alarm.changed', () => {
+    badge.style.borderColor = 'rgba(53,224,160,.5)'
   })
 
   ctx.log.info('哨兵徽标已挂载(右下角)')

package/sdk/examples/line-sentinel/index.mjs

@@ -19,7 +19,9 @@ export default {
 
     // 平台服务消费:启动时经 SDK API 客户端读取产线清单(自环调用)
     try {
-      const lines = await ctx.api.lines.list()
+      // ⚠️ GET /api/workshop/dcw/lines 返回的是 { lines, states } —— **不是数组**。
+      // 旧写法 Array.isArray(lines) 恒为 false,linesTotal 永远是 0(静默错误)。
+      const { lines } = await ctx.api.lines.list()
       ctx.kv.set('linesTotal', Array.isArray(lines) ? lines.length : 0)
       ctx.logger.info(`平台产线清单: ${ctx.kv.get('linesTotal')} 条`)
     }
@@ -81,7 +83,8 @@ export default {
         .map(([k, v]) => ({ nodeId: k.slice(6), ...v }))
       return {
         plugin: ctx.name,
-        version: ctx.version,
+        // ctx 上没有 version(插件版本由 manifest 记录);这里报 SDK 版本才有意义
+        sdkVersion: ctx.sdkVersion,
         running: ctx.kv.get('running') ?? false,
         runningCount: ctx.kv.get('runningCount') ?? 0,
         heartbeat: ctx.kv.get('heartbeat'),

package/sdk/examples/ops-notifier/client.mjs

@@ -8,7 +8,9 @@ export function setup(ctx) {
   ctx.root().prepend(toast)
 
   let timer = null
-  ctx.on('dcw:write', (w) => {
+  // scene 事件名是 'dcw.written'(写控 ACK 后对浏览器广播);服务端钩子 'dcw:write'
+  // 不过桥到浏览器,在这里订阅它只会得到永不触发的空订阅。
+  ctx.on('dcw.written', (w) => {
     toast.textContent = w.ok
       ? `✔ 写入 ${w.name} → ${w.eng}${w.source ? `(${w.source})` : ''}`
       : `✖ 写入失败 ${w.name}`