agentworkshop 0.5.9 → 0.6.1

package/scripts/test-memory-rrf-mmr.ts

@@ -1,114 +1,114 @@
-/**
- * 记忆检索 v2 算法测试:RRF 融合 / MMR 多样性 / kind 感知半衰期 / 任务关联加权 / 策展层排除。
- * 运行: npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/test-memory-rrf-mmr.ts
- */
-import type { DatabaseSync } from 'node:sqlite'
-import { openWorkshopDb } from '../server/services/workshop/db/database'
-import { createMemoryRepo, TEAM_AGENT_ID } from '../server/services/workshop/db/memory.repo'
-import { AgentMemory, buildMatchQuery, estimateTokens } from '../server/services/workshop/runtime/memory'
-
-let failures = 0
-function check(name: string, ok: boolean, detail = ''): void {
-  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
-  if (!ok) failures += 1
-}
-
-const db: DatabaseSync = openWorkshopDb(':memory:')
-const repo = createMemoryRepo(db)
-const seg = (s: string): string => s.replace(/([\u4e00-\u9fff])/g, ' $1 ')
-
-// ===== buildMatchQuery:CJK 词项扩容 + 去重 =====
-console.log('\n--- buildMatchQuery(CJK 词项扩容)---')
-{
-  const q = buildMatchQuery('网关限流方案讨论,部署脚本与令牌桶阈值约定')
-  const termCount = q ? q.split(' OR ').length : 0
-  check('CJK 单字词项上限提升(>12)', termCount > 12, `terms=${termCount}`)
-  const deduped = buildMatchQuery('限流 限流 限流')
-  check('词项去重', deduped !== null && deduped.split(' OR ').length === 2, `terms=${deduped}`) // 限/流
-  check('token 估算为正', estimateTokens('abc 中文') > 0)
-}
-
-// ===== RRF 融合:FTS+向量双榜融合(词袋 embedder)=====
-console.log('\n--- RRF 融合(混合检索)---')
-{
-  // hash 词袋 provider:同词集 → 相近向量(零网络)
-  const { createHashEmbeddingProvider } = await import('../server/services/workshop/runtime/embedding-provider')
-  const embedder = createHashEmbeddingProvider(64)
-
-  const rows = [
-    { dedup: 'task:a', title: 'Redis 缓存穿透方案', content: '布隆过滤器前置拦截,空值缓存五分钟' },
-    { dedup: 'task:b', title: 'Redis 雪崩预案', content: '过期时间加随机抖动,多级缓存兜底' },
-    { dedup: 'task:c', title: '部署脚本清单', content: 'docker compose 拉镜像,健康检查后切流量' },
-  ]
-  for (const r of rows) {
-    repo.upsert({ channelId: 'ch1', agentId: 'a1', kind: 'episodic-task', title: r.title, titleFts: seg(r.title), content: seg(r.content), importance: 0.8, taskId: r.dedup, dedupKey: `task:${r.dedup}` })
-  }
-  const mem = new AgentMemory(repo, { channelId: 'ch1', agentId: 'a1', embedder })
-  // 向量可命中(词袋相似)但 FTS 无词面匹配的查询:RRF 仍能通过向量榜给出结果
-  const hits = await mem.recallRows('cache 穿透 拦截')
-  check('向量榜独有命中可达(RRF 不丢向量结果)', hits.some(s => s.title === 'Redis 缓存穿透方案'), JSON.stringify(hits.map(s => s.title)))
-
-  // 双榜同时命中:融合排序应把两榜都命中的排前
-  const both = await mem.recallRows('Redis 雪崩')
-  check('双榜命中排序靠前', both.length > 0 && both[0]!.title === 'Redis 雪崩预案', JSON.stringify(both.map(s => `${s.title}:${s.score}`)))
-}
-
-// ===== kind 感知半衰期:semantic 不衰减,episodic-task 14d =====
-console.log('\n--- kind 感知半衰期 ---')
-{
-  const old = new Date(Date.now() - 60 * 86_400_000).toISOString()
-  repo.upsert({ channelId: 'ch1', agentId: 'old1', kind: 'semantic', title: '六十天前的架构决策', titleFts: seg('六十天前的架构决策'), content: seg('内核结论:单写多读'), importance: 0.9, taskId: null, dedupKey: 'manual:old-sem' })
-  repo.upsert({ channelId: 'ch1', agentId: 'old1', kind: 'episodic-task', title: '六十天前的任务', titleFts: seg('六十天前的任务'), content: seg('过程性记录,内容已过时'), importance: 0.9, taskId: 't-old', dedupKey: 'task:t-old' })
-  // 直接改 created_at 模拟老化(upsert ON CONFLICT 会刷新,故用参数化 UPDATE)
-  db.prepare('UPDATE agent_memories SET created_at = ? WHERE agent_id = ?').run(old, 'old1')
-
-  const mem = new AgentMemory(repo, { channelId: 'ch1', agentId: 'old1' })
-  const hits = await mem.recallRows('六十天前')
-  const sem = hits.find(s => s.title === '六十天前的架构决策')
-  const epi = hits.find(s => s.title === '六十天前的任务')
-  check('semantic 知识不随时近衰减(分高于 episodic)', sem !== undefined && epi !== undefined && sem.score > epi.score, `sem=${sem?.score} epi=${epi?.score}`)
-}
-
-// ===== 任务关联加权:兄弟/父任务记忆置顶 =====
-console.log('\n--- 任务关联加权(related-task boost)---')
-{
-  repo.upsert({ channelId: 'ch1', agentId: 'rel', kind: 'episodic-task', title: '无关旧任务', titleFts: seg('无关旧任务'), content: seg('数据库迁移完成,版本升到 v14'), importance: 0.8, taskId: 't-other', dedupKey: 'task:t-other' })
-  repo.upsert({ channelId: 'ch1', agentId: 'rel', kind: 'episodic-task', title: '兄弟任务结论', titleFts: seg('兄弟任务结论'), content: seg('API 网关路由表已生成'), importance: 0.55, taskId: 't-sib1', dedupKey: 'task:t-sib1' })
-  const mem = new AgentMemory(repo, { channelId: 'ch1', agentId: 'rel' })
-  // 查询词面同时弱命中两行;兄弟任务 id 加权后必须反超高重要度旧行
-  const hits = await mem.recallRows('任务 结论 数据库 网关', { relatedTaskIds: ['t-sib1', 't-parent'] })
-  check('兄弟任务记忆加权反超(置顶)', hits[0]?.title === '兄弟任务结论', JSON.stringify(hits.map(s => `${s.title}:${s.score}`)))
-  const hitsNoRel = await mem.recallRows('任务 结论 数据库 网关', { touch: false })
-  check('无关联集时高重要度旧行居前(对照)', hitsNoRel[0]?.title === '无关旧任务', JSON.stringify(hitsNoRel.map(s => `${s.title}:${s.score}`)))
-}
-
-// ===== 策展层:brief 走 L0 置顶,L1 引子不重复;chronicle 不进 L1 但 L2 可检索 =====
-console.log('\n--- 策展层(L0/L1/L2 分层)---')
-{
-  const mem = new AgentMemory(repo, { channelId: 'ch1', agentId: 'cur' })
-  await mem.save({ title: '普通结论', content: '普通检索应该能命中', scope: 'private', dedupKey: 'note:normal' })
-  mem.repo.upsert({ channelId: 'ch1', agentId: 'cur', kind: 'brief', title: '会话简报', titleFts: seg('会话简报'), content: seg('最近完成:普通结论'), importance: 0.6, taskId: null, dedupKey: 'brief:cur' })
-  mem.repo.upsert({ channelId: 'ch1', agentId: 'cur', kind: 'chronicle', title: '团队编年史', titleFts: seg('团队编年史'), content: seg('完成 普通结论'), importance: 0.9, taskId: null, dedupKey: 'chronicle:ch1' })
-
-  // L1(recall):brief 经 L0 路径恰好注入一次(去重靠 excludeCurated);chronicle 不进 L1
-  const primer = await mem.recall('普通')
-  const briefHits = (primer?.match(/会话简报/g) ?? []).length
-  check('brief 恰好注入一次(L0 路径)', briefHits === 1, `hits=${briefHits}`)
-  check('L1 引子不含 chronicle(防双份注入)', primer !== null && !primer.includes('编年史'))
-
-  // L2(search_memory/recallRows):策展层可被检索(特性)
-  const found = await mem.recallRows('编年史')
-  check('L2 search_memory 可命中 chronicle', found.some(s => s.title === '团队编年史'), JSON.stringify(found.map(s => s.title)))
-}
-
-// ===== team 域可见性:episodic-team-task 对全员 shared 可检索 =====
-console.log('\n--- team-task 共享域 ---')
-{
-  repo.upsert({ channelId: 'ch1', agentId: TEAM_AGENT_ID, kind: 'episodic-team-task', title: '团队任务成果', titleFts: seg('团队任务成果'), content: seg('数据迁移已全部完成并验证'), importance: 0.8, taskId: 't-team', dedupKey: 'team-task:t-team' })
-  const memB = new AgentMemory(repo, { channelId: 'ch1', agentId: 'member-b' })
-  const seen = await memB.recallRows('数据迁移', { scope: 'shared' })
-  check('其他成员 shared 域可命中 team-task 行', seen.some(s => s.title === '团队任务成果'), JSON.stringify(seen.map(s => s.title)))
-}
-
-console.log(failures === 0 ? '\nALL PASS' : `\n${failures} FAILED`)
-process.exit(failures === 0 ? 0 : 1)
+/**
+ * 记忆检索 v2 算法测试:RRF 融合 / MMR 多样性 / kind 感知半衰期 / 任务关联加权 / 策展层排除。
+ * 运行: npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/test-memory-rrf-mmr.ts
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { openWorkshopDb } from '../server/services/workshop/db/database'
+import { createMemoryRepo, TEAM_AGENT_ID } from '../server/services/workshop/db/memory.repo'
+import { AgentMemory, buildMatchQuery, estimateTokens } from '../server/services/workshop/runtime/memory'
+
+let failures = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failures += 1
+}
+
+const db: DatabaseSync = openWorkshopDb(':memory:')
+const repo = createMemoryRepo(db)
+const seg = (s: string): string => s.replace(/([\u4e00-\u9fff])/g, ' $1 ')
+
+// ===== buildMatchQuery:CJK 词项扩容 + 去重 =====
+console.log('\n--- buildMatchQuery(CJK 词项扩容)---')
+{
+  const q = buildMatchQuery('网关限流方案讨论,部署脚本与令牌桶阈值约定')
+  const termCount = q ? q.split(' OR ').length : 0
+  check('CJK 单字词项上限提升(>12)', termCount > 12, `terms=${termCount}`)
+  const deduped = buildMatchQuery('限流 限流 限流')
+  check('词项去重', deduped !== null && deduped.split(' OR ').length === 2, `terms=${deduped}`) // 限/流
+  check('token 估算为正', estimateTokens('abc 中文') > 0)
+}
+
+// ===== RRF 融合:FTS+向量双榜融合(词袋 embedder)=====
+console.log('\n--- RRF 融合(混合检索)---')
+{
+  // hash 词袋 provider:同词集 → 相近向量(零网络)
+  const { createHashEmbeddingProvider } = await import('../server/services/workshop/runtime/embedding-provider')
+  const embedder = createHashEmbeddingProvider(64)
+
+  const rows = [
+    { dedup: 'task:a', title: 'Redis 缓存穿透方案', content: '布隆过滤器前置拦截,空值缓存五分钟' },
+    { dedup: 'task:b', title: 'Redis 雪崩预案', content: '过期时间加随机抖动,多级缓存兜底' },
+    { dedup: 'task:c', title: '部署脚本清单', content: 'docker compose 拉镜像,健康检查后切流量' },
+  ]
+  for (const r of rows) {
+    repo.upsert({ channelId: 'ch1', agentId: 'a1', kind: 'episodic-task', title: r.title, titleFts: seg(r.title), content: seg(r.content), importance: 0.8, taskId: r.dedup, dedupKey: `task:${r.dedup}` })
+  }
+  const mem = new AgentMemory(repo, { channelId: 'ch1', agentId: 'a1', embedder })
+  // 向量可命中(词袋相似)但 FTS 无词面匹配的查询:RRF 仍能通过向量榜给出结果
+  const hits = await mem.recallRows('cache 穿透 拦截')
+  check('向量榜独有命中可达(RRF 不丢向量结果)', hits.some(s => s.title === 'Redis 缓存穿透方案'), JSON.stringify(hits.map(s => s.title)))
+
+  // 双榜同时命中:融合排序应把两榜都命中的排前
+  const both = await mem.recallRows('Redis 雪崩')
+  check('双榜命中排序靠前', both.length > 0 && both[0]!.title === 'Redis 雪崩预案', JSON.stringify(both.map(s => `${s.title}:${s.score}`)))
+}
+
+// ===== kind 感知半衰期:semantic 不衰减,episodic-task 14d =====
+console.log('\n--- kind 感知半衰期 ---')
+{
+  const old = new Date(Date.now() - 60 * 86_400_000).toISOString()
+  repo.upsert({ channelId: 'ch1', agentId: 'old1', kind: 'semantic', title: '六十天前的架构决策', titleFts: seg('六十天前的架构决策'), content: seg('内核结论:单写多读'), importance: 0.9, taskId: null, dedupKey: 'manual:old-sem' })
+  repo.upsert({ channelId: 'ch1', agentId: 'old1', kind: 'episodic-task', title: '六十天前的任务', titleFts: seg('六十天前的任务'), content: seg('过程性记录,内容已过时'), importance: 0.9, taskId: 't-old', dedupKey: 'task:t-old' })
+  // 直接改 created_at 模拟老化(upsert ON CONFLICT 会刷新,故用参数化 UPDATE)
+  db.prepare('UPDATE agent_memories SET created_at = ? WHERE agent_id = ?').run(old, 'old1')
+
+  const mem = new AgentMemory(repo, { channelId: 'ch1', agentId: 'old1' })
+  const hits = await mem.recallRows('六十天前')
+  const sem = hits.find(s => s.title === '六十天前的架构决策')
+  const epi = hits.find(s => s.title === '六十天前的任务')
+  check('semantic 知识不随时近衰减(分高于 episodic)', sem !== undefined && epi !== undefined && sem.score > epi.score, `sem=${sem?.score} epi=${epi?.score}`)
+}
+
+// ===== 任务关联加权:兄弟/父任务记忆置顶 =====
+console.log('\n--- 任务关联加权(related-task boost)---')
+{
+  repo.upsert({ channelId: 'ch1', agentId: 'rel', kind: 'episodic-task', title: '无关旧任务', titleFts: seg('无关旧任务'), content: seg('数据库迁移完成,版本升到 v14'), importance: 0.8, taskId: 't-other', dedupKey: 'task:t-other' })
+  repo.upsert({ channelId: 'ch1', agentId: 'rel', kind: 'episodic-task', title: '兄弟任务结论', titleFts: seg('兄弟任务结论'), content: seg('API 网关路由表已生成'), importance: 0.55, taskId: 't-sib1', dedupKey: 'task:t-sib1' })
+  const mem = new AgentMemory(repo, { channelId: 'ch1', agentId: 'rel' })
+  // 查询词面同时弱命中两行;兄弟任务 id 加权后必须反超高重要度旧行
+  const hits = await mem.recallRows('任务 结论 数据库 网关', { relatedTaskIds: ['t-sib1', 't-parent'] })
+  check('兄弟任务记忆加权反超(置顶)', hits[0]?.title === '兄弟任务结论', JSON.stringify(hits.map(s => `${s.title}:${s.score}`)))
+  const hitsNoRel = await mem.recallRows('任务 结论 数据库 网关', { touch: false })
+  check('无关联集时高重要度旧行居前(对照)', hitsNoRel[0]?.title === '无关旧任务', JSON.stringify(hitsNoRel.map(s => `${s.title}:${s.score}`)))
+}
+
+// ===== 策展层:brief 走 L0 置顶,L1 引子不重复;chronicle 不进 L1 但 L2 可检索 =====
+console.log('\n--- 策展层(L0/L1/L2 分层)---')
+{
+  const mem = new AgentMemory(repo, { channelId: 'ch1', agentId: 'cur' })
+  await mem.save({ title: '普通结论', content: '普通检索应该能命中', scope: 'private', dedupKey: 'note:normal' })
+  mem.repo.upsert({ channelId: 'ch1', agentId: 'cur', kind: 'brief', title: '会话简报', titleFts: seg('会话简报'), content: seg('最近完成:普通结论'), importance: 0.6, taskId: null, dedupKey: 'brief:cur' })
+  mem.repo.upsert({ channelId: 'ch1', agentId: 'cur', kind: 'chronicle', title: '团队编年史', titleFts: seg('团队编年史'), content: seg('完成 普通结论'), importance: 0.9, taskId: null, dedupKey: 'chronicle:ch1' })
+
+  // L1(recall):brief 经 L0 路径恰好注入一次(去重靠 excludeCurated);chronicle 不进 L1
+  const primer = await mem.recall('普通')
+  const briefHits = (primer?.match(/会话简报/g) ?? []).length
+  check('brief 恰好注入一次(L0 路径)', briefHits === 1, `hits=${briefHits}`)
+  check('L1 引子不含 chronicle(防双份注入)', primer !== null && !primer.includes('编年史'))
+
+  // L2(search_memory/recallRows):策展层可被检索(特性)
+  const found = await mem.recallRows('编年史')
+  check('L2 search_memory 可命中 chronicle', found.some(s => s.title === '团队编年史'), JSON.stringify(found.map(s => s.title)))
+}
+
+// ===== team 域可见性:episodic-team-task 对全员 shared 可检索 =====
+console.log('\n--- team-task 共享域 ---')
+{
+  repo.upsert({ channelId: 'ch1', agentId: TEAM_AGENT_ID, kind: 'episodic-team-task', title: '团队任务成果', titleFts: seg('团队任务成果'), content: seg('数据迁移已全部完成并验证'), importance: 0.8, taskId: 't-team', dedupKey: 'team-task:t-team' })
+  const memB = new AgentMemory(repo, { channelId: 'ch1', agentId: 'member-b' })
+  const seen = await memB.recallRows('数据迁移', { scope: 'shared' })
+  check('其他成员 shared 域可命中 team-task 行', seen.some(s => s.title === '团队任务成果'), JSON.stringify(seen.map(s => s.title)))
+}
+
+console.log(failures === 0 ? '\nALL PASS' : `\n${failures} FAILED`)
+process.exit(failures === 0 ? 0 : 1)

package/scripts/test-plugin-ext.ts

@@ -0,0 +1,173 @@
+/**
+ * 插件扩展面单元测试:omp 插件工具(桥/合并/分发/热注入)+ 插件 DAQ 模板(桥/覆盖/REST 守卫)。
+ * 运行: npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/test-plugin-ext.ts
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { openWorkshopDb } from '../server/services/workshop/db/database'
+import {
+  hostToolsForRole,
+} from '../server/services/workshop/agents/omp-agent'
+import { attachOmpPluginBridge, registerPluginTool, onPluginToolsChange, listPluginTools } from '../server/services/workshop/agents/plugin-tools'
+import { getDaqTemplateRegistry, findDaqTemplate } from '../server/services/workshop/daq/daq-templates'
+
+let failures = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  console.log(`  ${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) failures += 1
+}
+
+// 全局桥接管(模拟 host.mjs 先行的装载顺序)
+attachOmpPluginBridge()
+
+// ===== omp 插件工具:注册 → 合并进角色工具面 =====
+console.log('\n--- omp 插件工具注册与合并 ---')
+{
+  registerPluginTool('demo-plugin', {
+    name: 'plugin_echo',
+    description: '回显测试工具',
+    parameters: { type: 'object', properties: { msg: { type: 'string' } }, required: ['msg'] },
+    handler: args => ({ text: `echo:${String(args.msg ?? '')}` }),
+  })
+  registerPluginTool('demo-plugin', {
+    name: 'plugin_lead_only',
+    description: '仅 lead 可见的工具',
+    parameters: { type: 'object', properties: {} },
+    roles: ['lead'],
+    handler: () => ({ text: 'lead tool' }),
+  })
+
+  const lead = hostToolsForRole('lead')
+  const worker = hostToolsForRole('worker')
+  check('lead 工具面含 plugin_echo', lead.some(t => t.name === 'plugin_echo'))
+  check('worker 工具面含 plugin_echo(缺省双角色)', worker.some(t => t.name === 'plugin_echo'))
+  check('roles 过滤:plugin_lead_only 仅 lead 可见', lead.some(t => t.name === 'plugin_lead_only') && !worker.some(t => t.name === 'plugin_lead_only'))
+  check('内置工具不因插件合并丢失', lead.some(t => t.name === 'complete_task') && lead.some(t => t.name === 'daq_frames'))
+
+  // 分发(handleHostTool 为类私有,经实例 + 任意未知内置名走插件查表)
+  const { OmpRpcAgentImpl } = await import('../server/services/workshop/agents/omp-agent')
+  const impl = new OmpRpcAgentImpl({ agentId: 'a1', name: 'A', role: 'worker', channelId: 'ch1' })
+  const handle = (impl as unknown as Record<string, (req: unknown) => Promise<{ text: string, isError?: boolean }>>).handleHostTool.bind(impl)
+  const out = await handle({ toolName: 'plugin_echo', arguments: { msg: 'hello' } })
+  check('handleHostTool 分发到插件 handler', out.text === 'echo:hello', out.text)
+
+  // 同名覆盖(热重载幂等:再注册同插件同名,byName 不重复)
+  const before = listPluginTools().size
+  registerPluginTool('demo-plugin', {
+    name: 'plugin_echo',
+    description: '回显测试工具 v2',
+    parameters: { type: 'object', properties: {} },
+    handler: () => ({ text: 'echo2' }),
+  })
+  check('同名覆盖不增表(热重载幂等)', listPluginTools().size === before, `size=${listPluginTools().size}`)
+  const out2 = await handle({ toolName: 'plugin_echo', arguments: {} })
+  check('覆盖后新 handler 生效', out2.text === 'echo2')
+}
+
+// ===== 运行时热注入:注册表变更 → 在跑实例重发 set_host_tools =====
+console.log('\n--- 运行时热注入 ---')
+{
+  const { OmpRpcAgentImpl } = await import('../server/services/workshop/agents/omp-agent')
+  const impl = new OmpRpcAgentImpl({ agentId: 'a2', name: 'B', role: 'worker', channelId: 'ch1' })
+  const sent: Array<Record<string, unknown>> = []
+  const fakeClient = {
+    alive: true,
+    onEvent: () => () => {},
+    send: async (cmd: Record<string, unknown>) => {
+      sent.push(cmd)
+      return { success: true }
+    },
+    onHostToolCall: () => {},
+    getContextUsage: () => null,
+    setContextWindow: () => {},
+  }
+  ;(impl as unknown as Record<string, unknown>).client = fakeClient
+
+  let changeCount = 0
+  const off = onPluginToolsChange(() => changeCount++)
+  registerPluginTool('hot-plugin', {
+    name: 'plugin_hot',
+    description: '热注入工具',
+    parameters: { type: 'object', properties: {} },
+    handler: () => ({ text: 'hot' }),
+  })
+  off()
+  await new Promise(r => setTimeout(r, 20))
+  check('注册触发变更通知', changeCount >= 1, `changes=${changeCount}`)
+  const setTools = sent.filter(c => c.type === 'set_host_tools')
+  if (setTools.length > 0) {
+    const tools = setTools[setTools.length - 1]!.tools as Array<{ name: string }>
+    check('热注入重发 set_host_tools', true)
+    check('热注入载荷含新插件工具', tools.some(t => t.name === 'plugin_hot'))
+  }
+  else {
+    fail('热注入重发 set_host_tools')
+  }
+  impl.dispose()
+}
+
+// ===== 插件 DAQ 模板:注册 → 目录可见 → findDaqTemplate 可解析 → REST 守卫 =====
+console.log('\n--- 插件 DAQ 模板 ---')
+{
+  const registry = getDaqTemplateRegistry()
+  registry.registerPlugin({
+    key: 'plug-test-probe',
+    name: '插件测试模板',
+    code: 'PLUG · T',
+    ch: '测试信号',
+    unit: 'mm',
+    base: 0.5,
+    amp: 0.01,
+    min: 0.4,
+    max: 0.6,
+    decimals: 3,
+    icon: 'tension',
+    signalKind: 'vector',
+    vector: { points: 16, min: 0.4, max: 0.6 },
+    sink: { processors: [{ name: 'derive-metric', args: { name: 'avg', op: 'avg' } }] },
+    metrics: [{ key: 'avg', label: '均值', unit: 'mm' }],
+    plugin: 'test-plugin',
+  })
+  check('插件模板进入目录', registry.all().some(t => t.key === 'plug-test-probe'))
+  check('findDaqTemplate 可解析插件模板', findDaqTemplate('plug-test-probe')?.signalKind === 'vector')
+  check('插件标记透传', registry.all().find(t => t.key === 'plug-test-probe')?.plugin === 'test-plugin')
+
+  // 同 key 覆盖(热重载幂等,不增行)
+  const before = registry.all().length
+  registry.registerPlugin({
+    key: 'plug-test-probe', name: '插件测试模板 v2', code: 'PLUG · T', ch: '测试信号', unit: 'mm',
+    base: 0.5, amp: 0.01, min: 0.4, max: 0.6, decimals: 3, icon: 'tension', plugin: 'test-plugin',
+  })
+  check('同 key 覆盖幂等(不增行)', registry.all().length === before && registry.byKey('plug-test-probe')?.name === '插件测试模板 v2')
+
+  // REST 守卫:插件模板不可改/删
+  let guarded = false
+  try {
+    registry.update('plug-test-probe', { name: 'hack' })
+  }
+  catch { guarded = true }
+  check('update 插件模板被拒', guarded)
+  guarded = false
+  try {
+    registry.remove('plug-test-probe')
+  }
+  catch { guarded = true }
+  check('remove 插件模板被拒', guarded)
+
+  // 与内置冲突拒绝
+  let builtinClash = false
+  try {
+    registry.registerPlugin({ key: 'temp-tc', name: 'x', code: 'x', ch: 'x', unit: 'x', base: 0, amp: 1, min: 0, max: 1, decimals: 1, icon: 'thermo' })
+  }
+  catch { builtinClash = true }
+  check('与内置模板 key 冲突拒绝', builtinClash)
+}
+
+// ===== db 依赖声明(类型面冒烟,防 import 环断裂)=====
+console.log('\n--- 冒烟 ---')
+{
+  const db: DatabaseSync = openWorkshopDb(':memory:')
+  check('db 可用( import 链健康)', db !== null)
+}
+
+console.log(failures === 0 ? '\nALL PASS' : `\n${failures} FAILED`)
+process.exit(failures === 0 ? 0 : 1)

package/server/api/system/settings/events.get.ts

@@ -1,28 +1,27 @@
-/**
- * GET /api/system/settings/events —— 设置变更 SSE 事件流。
- * 客户端用 fetch + ReadableStream（带 Authorization 头）订阅；
- * 服务端任何写入（UI / CLI / 文件监听）都会 push { type, changed, restartRequired, effective }。
- * 连接前先鉴权（无效 token 直接 401，不开流）。
- */
-import { createEventStream } from 'h3'
-import { resolveUser } from '../../workshop/caller'
-import { getSystemConfigService, type ConfigEventPayload } from '../../../services/system-config'
-
-export default defineEventHandler(async (event) => {
-  resolveUser(event) // 开流前鉴权：无 token → 401
-  const service = getSystemConfigService()
-  const stream = createEventStream(event)
-
-  let listener: ((payload: ConfigEventPayload) => void) | undefined
-  listener = (payload) => {
-    void stream.push(JSON.stringify(payload))
-  }
-  const unsubscribe = service.subscribe(listener)
-
-  stream.onClosed(async () => {
-    unsubscribe()
-    await stream.close()
-  })
-
-  return stream.send()
-})
+/**
+ * GET /api/system/settings/events —— 设置变更 SSE 事件流。
+ * 客户端用 fetch + ReadableStream（带 Authorization 头）订阅；
+ * 服务端任何写入（UI / CLI / 文件监听）都会 push { type, changed, restartRequired, effective }。
+ * 连接前先鉴权（无效 token 直接 401，不开流）。
+ */
+import { createEventStream } from 'h3'
+import { resolveUser } from '../../workshop/caller'
+import { getSystemConfigService, type ConfigEventPayload } from '../../../services/system-config'
+
+export default defineEventHandler(async (event) => {
+  resolveUser(event) // 开流前鉴权：无 token → 401
+  const service = getSystemConfigService()
+  const stream = createEventStream(event)
+
+  const listener = (payload: ConfigEventPayload): void => {
+    void stream.push(JSON.stringify(payload))
+  }
+  const unsubscribe = service.subscribe(listener)
+
+  stream.onClosed(async () => {
+    unsubscribe()
+    await stream.close()
+  })
+
+  return stream.send()
+})

package/server/api/system/settings/index.get.ts

@@ -1,14 +1,14 @@
-/**
- * GET /api/system/settings —— 运行时设置全量快照。
- * 返回描述符 + 有效值 + 各键来源(config.yml/runtime/env) + 覆盖文件路径。
- * 前端「系统设置 → 运行配置」表单据此渲染;CLI `aw status` 也走同源概念。
- * 鉴权:任何已登录用户可读(config.get 同语义)。
- */
-import { defineApiHandler } from '../../../utils/response'
-import { resolveUser } from '../../workshop/caller'
-import { getSystemConfigService } from '../../../services/system-config'
-
-export default defineApiHandler((event) => {
-  resolveUser(event)
-  return getSystemConfigService().snapshot()
-})
+/**
+ * GET /api/system/settings —— 运行时设置全量快照。
+ * 返回描述符 + 有效值 + 各键来源(config.yml/runtime/env) + 覆盖文件路径。
+ * 前端「系统设置 → 运行配置」表单据此渲染;CLI `aw status` 也走同源概念。
+ * 鉴权:任何已登录用户可读(config.get 同语义)。
+ */
+import { defineApiHandler } from '../../../utils/response'
+import { resolveUser } from '../../workshop/caller'
+import { getSystemConfigService } from '../../../services/system-config'
+
+export default defineApiHandler((event) => {
+  resolveUser(event)
+  return getSystemConfigService().snapshot()
+})

package/server/api/system/settings/index.patch.ts

@@ -1,22 +1,22 @@
-/**
- * PATCH /api/system/settings —— 写入运行时设置（持久化 + 热重载）。
- * body: { "override": { "<key>": value | null } }
- *   value 非 null → 校验后写入 data/runtime-settings.json 并立即应用(live 键实时生效)
- *   value 为 null → 清除该键覆盖(回落 config.yml)
- * 返回 { changed, restartRequired, effective, sources, overrides }。
- * 鉴权:仅 admin（系统级设置变更属高危管理面）。
- */
-import { readBody } from 'h3'
-import { defineApiHandler } from '../../../utils/response'
-import { requireRole } from '../../workshop/caller'
-import { getSystemConfigService } from '../../../services/system-config'
-
-export default defineApiHandler(async (event) => {
-  requireRole(event, ['admin'])
-  const body = (await readBody(event)) ?? {}
-  const overrides = body.override ?? body.overrides ?? body
-  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
-    return { ok: false, message: '请求体应为 { "override": { key: value } }' }
-  }
-  return { ok: true, ...getSystemConfigService().patch(overrides as Record<string, unknown>) }
-})
+/**
+ * PATCH /api/system/settings —— 写入运行时设置（持久化 + 热重载）。
+ * body: { "override": { "<key>": value | null } }
+ *   value 非 null → 校验后写入 data/runtime-settings.json 并立即应用(live 键实时生效)
+ *   value 为 null → 清除该键覆盖(回落 config.yml)
+ * 返回 { changed, restartRequired, effective, sources, overrides }。
+ * 鉴权:仅 admin（系统级设置变更属高危管理面）。
+ */
+import { readBody } from 'h3'
+import { defineApiHandler } from '../../../utils/response'
+import { requireRole } from '../../workshop/caller'
+import { getSystemConfigService } from '../../../services/system-config'
+
+export default defineApiHandler(async (event) => {
+  requireRole(event, ['admin'])
+  const body = (await readBody(event)) ?? {}
+  const overrides = body.override ?? body.overrides ?? body
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides)) {
+    return { ok: false, message: '请求体应为 { "override": { key: value } }' }
+  }
+  return { ok: true, ...getSystemConfigService().patch(overrides as Record<string, unknown>) }
+})

package/server/api/system/settings/reset.post.ts

@@ -1,12 +1,12 @@
-/**
- * POST /api/system/settings/reset —— 清空全部运行时覆盖（回落 config.yml/base + env）。
- * 鉴权:仅 admin。
- */
-import { defineApiHandler } from '../../../utils/response'
-import { requireRole } from '../../workshop/caller'
-import { getSystemConfigService } from '../../../services/system-config'
-
-export default defineApiHandler((event) => {
-  requireRole(event, ['admin'])
-  return { ok: true, ...getSystemConfigService().reset() }
-})
+/**
+ * POST /api/system/settings/reset —— 清空全部运行时覆盖（回落 config.yml/base + env）。
+ * 鉴权:仅 admin。
+ */
+import { defineApiHandler } from '../../../utils/response'
+import { requireRole } from '../../workshop/caller'
+import { getSystemConfigService } from '../../../services/system-config'
+
+export default defineApiHandler((event) => {
+  requireRole(event, ['admin'])
+  return { ok: true, ...getSystemConfigService().reset() }
+})

package/server/api/workshop/daq/[id]/frames/content.get.ts

@@ -0,0 +1,24 @@
+/**
+ * GET /api/workshop/daq/:id/frames/content —— 帧图像内容(对象存储流式输出)。
+ * query: ts(epoch ms,必填)、thumb?(1=缩略图,缺省主图)
+ * 像素不落 Timescale(元数据分离,plan D1);此处经 DaqObjectStore 读取后直出。
+ * 注意:二进制路由不走 defineApiHandler(JSON 信封会把 Buffer 序列化成
+ * {type:'Buffer',data:[…]} 文本,84 字节 500 事故实录),h3 对 Buffer 原生二进制响应。
+ */
+import { createError, defineEventHandler, getQuery, getRouterParam, setResponseHeader } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { getDaqController } from '@/server/services/workshop/daq/daq-controller'
+
+export default defineEventHandler(async (event) => {
+  resolveUser(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  const q = getQuery(event)
+  const ts = Number(q.ts)
+  if (!Number.isFinite(ts) || ts <= 0) {
+    throw createError({ statusCode: 400, statusMessage: '参数 ts(epoch ms)必填' })
+  }
+  const { data, mime } = await getDaqController().frameContent(id, ts, q.thumb === '1')
+  setResponseHeader(event, 'content-type', mime)
+  setResponseHeader(event, 'cache-control', 'private, max-age=86400')
+  return data
+})

package/server/api/workshop/daq/[id]/frames.get.ts

@@ -0,0 +1,44 @@
+/**
+ * GET /api/workshop/daq/:id/frames —— 节点帧历史(v2 多形态信号:向量/图像元数据)。
+ * query: from?/to?(epoch ms)、kind?(vector|image)、limit?(默认 100,上限 1000)
+ * 图像像素经 contentUrl(鉴权流式)按需取,本接口只返回元数据与派生指标。
+ */
+import { getQuery, getRouterParam } from 'h3'
+import { resolveUser } from '@/server/api/workshop/caller'
+import { defineApiHandler } from '@/server/utils/response'
+import { getDaqController } from '@/server/services/workshop/daq/daq-controller'
+
+export default defineApiHandler(async (event) => {
+  resolveUser(event)
+  const id = getRouterParam(event, 'id') ?? ''
+  const q = getQuery(event)
+  const num = (k: string): number | undefined => (q[k] != null && !Number.isNaN(Number(q[k])) ? Number(q[k]) : undefined)
+  const kind = q.kind === 'vector' || q.kind === 'image' ? q.kind : undefined
+  const frames = await getDaqController().frames(id, {
+    fromMs: num('from'),
+    toMs: num('to'),
+    kind,
+    limit: num('limit'),
+  })
+  return {
+    frames: frames.map(f => ({
+      at: f.at,
+      kind: f.kind,
+      points: f.points,
+      metrics: f.metrics,
+      /** 图像元数据(objectKey/thumbKey/mime/width/height) */
+      meta: f.meta,
+      deviceBindingId: f.deviceBindingId,
+      lineId: f.lineId,
+      productId: f.productId,
+      recipeId: f.recipeId,
+      runId: f.runId,
+      contentUrl: f.kind === 'image'
+        ? `/api/workshop/daq/${id}/frames/content?ts=${f.at}`
+        : undefined,
+      thumbUrl: f.kind === 'image'
+        ? `/api/workshop/daq/${id}/frames/content?ts=${f.at}&thumb=1`
+        : undefined,
+    })),
+  }
+})