agentworkshop 0.7.24 → 0.7.33

package/server/services/workshop/dcw/dcw-product.repo.ts

@@ -3,18 +3,18 @@
  * 产品 = 数据隔离顶层维度:一个产品多个配方;批次/样本逐条携带 productId。
  */
 
-import { createLogger } from '../logger'
-import path from 'node:path'
+import { createLogger } from '../logger'
+import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import type { ProductInput, ProductView } from '../../../../shared/dcw-protocol'
+import { ensureDataDir } from '@/shared/config/home.mjs'
 import { AppError, ErrorCodes } from '../../../utils/errors'
-import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
+import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
 
-const log = createLogger('dcw.product-repo')
-
-const DB_PATH = process.cwd().endsWith('server')
-  ? 'data/dcw-products.json'
-  : path.join(process.cwd(), 'server', 'data', 'dcw-products.json')
+const log = createLogger('dcw.product-repo')
+
+// 配置根 .AgentWorkShop/data（ensureDataDir 自动迁移旧 cwd/server/data 位置）
+const DB_PATH = join(ensureDataDir(), 'dcw-products.json')
 
 function load(): ProductView[] {
   try {

package/server/services/workshop/dcw/dcw-recipe.repo.ts

@@ -5,22 +5,21 @@
  * 按批次时间窗归属产品;写历史追加式落盘(上限 3000 条,超出丢最旧)。
  */
 
-import path from 'node:path'
+import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import type { RecipeDaqWindow, RecipeInput, RecipeParam, RecipeRunView, RecipeView } from '../../../../shared/dcw-protocol'
 import { dcwKeyFromRef } from '../../../../shared/dcw-protocol'
+import { ensureDataDir } from '@/shared/config/home.mjs'
 import { AppError, ErrorCodes } from '../../../utils/errors'
 import { getDcwProductRepo } from './dcw-product.repo'
 import { getDcwNodeRepo } from './dcw-node.repo'
 import { getDaqNodeRepo } from '../daq/daq-node.repo'
 import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
 
-const DATA_DIR = process.cwd().endsWith('server')
-  ? 'data'
-  : path.join(process.cwd(), 'server', 'data')
-const RECIPES_PATH = path.join(DATA_DIR, 'dcw-recipes.json')
-const RUNS_PATH = path.join(DATA_DIR, 'dcw-runs.json')
-const WRITES_PATH = path.join(DATA_DIR, 'dcw-writes.json')
+// 配置根 .AgentWorkShop/data（ensureDataDir 自动迁移旧 cwd/server/data 位置）
+const RECIPES_PATH = join(ensureDataDir(), 'dcw-recipes.json')
+const RUNS_PATH = join(ensureDataDir(), 'dcw-runs.json')
+const WRITES_PATH = join(ensureDataDir(), 'dcw-writes.json')
 
 const RUNS_CAP = 200
 const WRITES_CAP = 3000

package/server/services/workshop/dcw/dcw-runtime.ts

@@ -93,12 +93,26 @@ export class DcwNodeRuntime {
    *  (仅与在飞读互斥),failures 只记 lastReadError 不改写状态机。 */
   tick(now: number): void {
     const node = this.node
-    // 保写心跳:仅对已设定过的节点生效(尚无设定值无可保持)
+    // 保写心跳:仅对已设定过的节点生效(尚无设定值无可保持)。
+    // 必须与手动/配方写共享同一在飞闸门 —— 早先此处直调 host.executeWrite 绕过了 write() 的
+    // writing 互斥,心跳可与用户下发并发落到同一通道:驱动层交错、后到者覆盖先到者,
+    // 且 dcw-controller 的 prevValue 采样跨 await,会把过期值记进回滚账本导致回滚点错位。
+    // 语义:写冲突时心跳**跳过本拍**(不排队、不补发),下一拍自然重试 —— 保写是幂等重下发。
     if (!this.writing && node.enabled && node.value != null && node.state !== 'writing') {
       const hold = node.holdIntervalMs ?? this.host.defaults().holdIntervalMs
       if (hold && hold > 0 && now - this.lastHoldAt >= hold) {
         this.lastHoldAt = now
-        void this.host.executeWrite(node, node.value, writeTolerance(node), null).catch(() => {})
+        this.writing = true
+        node.state = 'writing'
+        // tick 是同步节拍(由 sweep 同步调用),这里 fire-and-forget 但**全程持锁**,
+        // 保证与 write() 互斥;finally 里收敛状态并释放闸门。
+        void Promise.resolve()
+          .then(() => this.host.executeWrite(node, node.value!, writeTolerance(node), null))
+          .catch(() => { /* 保写失败不抛出:下一拍重试 */ })
+          .finally(() => {
+            this.writing = false
+            if (node.state === 'writing') node.state = 'error'
+          })
       }
     }
     // 周期读:被动观测,不依赖写过、不与写在飞互斥(仅同节点读串行)

package/server/services/workshop/dcw/dcw-templates.ts

@@ -4,19 +4,19 @@
  */
 
 import { createLogger } from '../logger'
-import path from 'node:path'
+import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import { DCW_TEMPLATES, DCW_TEMPLATE_ICONS, dcwTemplateByKey, type DcwTemplateDef, type DcwTemplateIcon, type DcwTemplateInput } from '../../../../shared/dcw-protocol'
 
 // dcwTemplateByKey 用于内置判别
+import { ensureDataDir } from '@/shared/config/home.mjs'
 import { AppError, ErrorCodes } from '../../../utils/errors'
 import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
 
 const log = createLogger('dcw.templates')
 
-const DB_PATH = process.cwd().endsWith('server')
-  ? 'data/dcw-templates.json'
-  : path.join(process.cwd(), 'server', 'data', 'dcw-templates.json')
+// 配置根 .AgentWorkShop/data（ensureDataDir 自动迁移旧 cwd/server/data 位置）
+const DB_PATH = join(ensureDataDir(), 'dcw-templates.json')
 
 function load(): DcwTemplateDef[] {
   try {

package/server/services/workshop/dcw/line-run.ts

@@ -11,8 +11,9 @@
  * 落盘(写放大),恢复时从最近一次结构变更的值继续。
  */
 
-import path from 'node:path'
-import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
+import { join } from 'node:path'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
 
 export interface ActiveLineRun {
   lineId: string
@@ -26,9 +27,8 @@ export interface ActiveLineRun {
   taggedSamples: number
 }
 
-const PERSIST_PATH = process.cwd().endsWith('server')
-  ? path.join('data', 'line-runs.json')
-  : path.join(process.cwd(), 'server', 'data', 'line-runs.json')
+// 配置根 .AgentWorkShop/data（ensureDataDir 自动迁移旧 cwd/server/data 位置）
+const PERSIST_PATH = join(ensureDataDir(), 'line-runs.json')
 
 const g = globalThis as typeof globalThis & {
   __activeLineRuns?: Map<string, ActiveLineRun>

package/server/services/workshop/dcw/recipe-rollback-manager.ts

@@ -414,7 +414,9 @@ export class RecipeRollBackManager {
   // ================================================================
 
   evaluateOpenRecords(now: number): void {
-    for (const record of this.repo.listRecords({ status: 'open', limit: 500 })) {
+    // 走 open 索引(O(open))而非 listRecords 的「全量倒序 + limit 500」:
+    // 后者在 open 记录 >500 时会**静默漏评估**,且每次 sweep 都对全量 records 做一次拷贝。
+    for (const record of this.repo.listOpenRecords()) {
       if (record.policy === 'observe_only')
         continue
       const setMs = Date.parse(record.setAt)

package/server/services/workshop/dcw/recipe-rollback.repo.ts

@@ -10,16 +10,23 @@
  */
 
 import { randomUUID } from 'node:crypto'
-import path from 'node:path'
+import { join } from 'node:path'
 import type { DcwJournalAnchor, OptimizationRecord } from '../../../../shared/dcw-protocol'
-import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+import { loadJsonFile, saveJsonFileAtomic } from '../json-store.mjs'
 
-const DATA_DIR = process.cwd().endsWith('server')
-  ? 'data'
-  : path.join(process.cwd(), 'server', 'data')
-const ROLLBACK_PATH = path.join(DATA_DIR, 'dcw-rollback.json')
+// 配置根 .AgentWorkShop/data（ensureDataDir 自动迁移旧 cwd/server/data 位置）
+const ROLLBACK_PATH = join(ensureDataDir(), 'dcw-rollback.json')
 
 const RECORDS_CAP = 2000
+/**
+ * anchors 上限(环形淘汰最旧)。
+ * 早先注释自述「append-only 无上限」:anchors 随每次参数变更单调增长,而 flushNow() 是
+ * **整库序列化**(anchors + records),保写心跳 + Agent 连续调控下每次落盘的 CPU/IO 线性放大,
+ * 且四个 last* 查询各自逆序全扫也随长度线性劣化 —— 长跑必然抖动直至 OOM。
+ * 20000 条锚在 1.5s 防抖落盘下约数 MB,既能覆盖任意实际回退窗口,又给出确定上界。
+ */
+const ANCHORS_CAP = 20000
 
 interface RollbackDb {
   anchors: DcwJournalAnchor[]
@@ -28,17 +35,78 @@ interface RollbackDb {
 
 function loadDb(): RollbackDb {
   const parsed = loadJsonFile(ROLLBACK_PATH, { anchors: [], records: [] }) as Partial<RollbackDb>
-  return { anchors: parsed.anchors ?? [], records: parsed.records ?? [] }
+  const db = { anchors: parsed.anchors ?? [], records: parsed.records ?? [] }
+  // 兼容历史无界文件:启动即收敛到上限,避免一次载入就把内存顶满
+  if (db.anchors.length > ANCHORS_CAP) db.anchors.splice(0, db.anchors.length - ANCHORS_CAP)
+  return db
 }
 
 export class RecipeRollBackRepo {
   private db: RollbackDb = loadDb()
   private flushTimer: NodeJS.Timeout | null = null
+  /**
+   * 每节点倒序锚 id 索引 —— 把 lastAnchorOf / lastStableAnchor / lastStableBefore /
+   * lastRollbackAnchor 四个「逆序全扫」降为 O(1)(稳定锚)或短前缀扫描。
+   * 之前每次写都触发其中 1~2 次全扫,rollbackRun 更是 N 节点 × O(anchors);
+   * anchors 无上限时这是最坏路径,也是调控热路径上最贵的操作。
+   */
+  private readonly nodeAnchors = new Map<string, DcwJournalAnchor[]>()
+  /** 每节点「稳定锚」(prevValue≠newValue)倒序子序列,单步回退直接取头 */
+  private readonly stableAnchors = new Map<string, DcwJournalAnchor[]>()
+  /** open 优化记录索引(nodeId → record),消除 evaluateOpenRecords 的 500ms 全量扫描 */
+  private readonly openByNode = new Map<string, OptimizationRecord>()
 
   constructor() {
+    this.reindex()
     this.restore()
   }
 
+  /** 由 db 重建全部索引(构造与外部文件热替换后调用) */
+  private reindex(): void {
+    this.nodeAnchors.clear()
+    this.stableAnchors.clear()
+    this.openByNode.clear()
+    for (const a of this.db.anchors) {
+      const arr = this.nodeAnchors.get(a.nodeId)
+      if (arr) arr.push(a)
+      else this.nodeAnchors.set(a.nodeId, [a])
+      if (a.prevValue != null && a.prevValue !== a.newValue) {
+        const st = this.stableAnchors.get(a.nodeId)
+        if (st) st.push(a)
+        else this.stableAnchors.set(a.nodeId, [a])
+      }
+    }
+    for (const r of this.db.records) {
+      if (r.status === 'open') this.openByNode.set(r.nodeId, r)
+    }
+  }
+
+  /** 索引登记:新锚入账时增量维护,避免全量重建 */
+  private indexAnchor(a: DcwJournalAnchor): void {
+    const arr = this.nodeAnchors.get(a.nodeId)
+    if (arr) arr.push(a)
+    else this.nodeAnchors.set(a.nodeId, [a])
+    if (a.prevValue != null && a.prevValue !== a.newValue) {
+      const st = this.stableAnchors.get(a.nodeId)
+      if (st) st.push(a)
+      else this.stableAnchors.set(a.nodeId, [a])
+    }
+  }
+
+  /** 环形淘汰后按 id 集合重建索引(仅在触发淘汰时发生,摊销成本 O(cap)) */
+  private pruneIndexes(liveIds: Set<string>): void {
+    for (const [nodeId, arr] of this.nodeAnchors) {
+      const kept = arr.filter(a => liveIds.has(a.id))
+      if (kept.length) this.nodeAnchors.set(nodeId, kept)
+      else this.nodeAnchors.delete(nodeId)
+    }
+    for (const [nodeId, arr] of this.stableAnchors) {
+      const kept = arr.filter(a => liveIds.has(a.id))
+      if (kept.length) this.stableAnchors.set(nodeId, kept)
+      else this.stableAnchors.delete(nodeId)
+    }
+  }
+
   /** 启动重放(崩溃恢复;对齐 line-run.ts 模式) */
   restore(): void {
     // 构造即 loadDb;open 记录保持 open,由 manager 的 sweep 评估继续接管
@@ -71,60 +139,70 @@ export class RecipeRollBackRepo {
   appendAnchor(a: Omit<DcwJournalAnchor, 'id' | 'at'> & { id?: string, at?: string }): DcwJournalAnchor {
     const anchor: DcwJournalAnchor = { ...a, id: a.id ?? `anc-${randomUUID().slice(0, 8)}`, at: a.at ?? new Date().toISOString() }
     this.db.anchors.push(anchor)
+    this.indexAnchor(anchor)
+    if (this.db.anchors.length > ANCHORS_CAP) {
+      const evicted = this.db.anchors.splice(0, this.db.anchors.length - ANCHORS_CAP)
+      const live = new Set(this.db.anchors.map(x => x.id))
+      // 仅当被淘汰的锚确实进了索引时才重建(避免每次追加都 O(cap))
+      if (evicted.some(e => this.nodeAnchors.get(e.nodeId)?.some(x => x.id === e.id))) this.pruneIndexes(live)
+    }
     this.flushDebounced()
     return anchor
   }
 
+  /** 该节点最近一次锚(O(1):索引尾部) */
   lastAnchorOf(nodeId: string): DcwJournalAnchor | undefined {
-    for (let i = this.db.anchors.length - 1; i >= 0; i--) {
-      if (this.db.anchors[i]!.nodeId === nodeId)
-        return this.db.anchors[i]
-    }
-    return undefined
+    const arr = this.nodeAnchors.get(nodeId)
+    return arr?.[arr.length - 1]
   }
 
-  /** 该节点上一个「有效基线」锚:prevValue≠newValue 的最近一条(单步回退目标) */
+  /** 该节点上一个「有效基线」锚:prevValue≠newValue 的最近一条(单步回退目标,O(1)) */
   lastStableAnchor(nodeId: string): DcwJournalAnchor | undefined {
-    for (let i = this.db.anchors.length - 1; i >= 0; i--) {
-      const a = this.db.anchors[i]!
-      if (a.nodeId === nodeId && a.prevValue != null && a.prevValue !== a.newValue)
-        return a
-    }
-    return undefined
+    const arr = this.stableAnchors.get(nodeId)
+    return arr?.[arr.length - 1]
   }
 
   anchorById(id: string): DcwJournalAnchor | undefined {
     return this.db.anchors.find(a => a.id === id)
   }
 
-  /** 指定时刻之前该节点最近的稳定锚(批次级回退用) */
+  /** 指定时刻之前该节点最近的稳定锚(批次级回退用)。
+   *  只扫该节点的稳定锚子序列(通常远短于全量),并整体倒序短路。 */
   lastStableBefore(nodeId: string, atMs: number): DcwJournalAnchor | undefined {
-    for (let i = this.db.anchors.length - 1; i >= 0; i--) {
-      const a = this.db.anchors[i]!
-      if (a.nodeId !== nodeId || a.prevValue == null || a.prevValue === a.newValue)
-        continue
+    const arr = this.stableAnchors.get(nodeId)
+    if (!arr) return undefined
+    for (let i = arr.length - 1; i >= 0; i--) {
+      const a = arr[i]!
       if (Date.parse(a.at) <= atMs)
         return a
     }
     return undefined
   }
 
+  /** 倒序查询锚。按 nodeId 时走索引子序列(避免全量拷贝);limit 提前短路,不再先 reverse 整个数组。 */
   listAnchors(filter: { nodeId?: string, lineId?: string, source?: string, limit?: number }): DcwJournalAnchor[] {
-    let list = [...this.db.anchors].reverse()
-    if (filter.nodeId)
-      list = list.filter(a => a.nodeId === filter.nodeId)
-    if (filter.lineId)
-      list = list.filter(a => a.lineId === filter.lineId)
-    if (filter.source)
-      list = list.filter(a => a.source === filter.source)
-    return list.slice(0, filter.limit ?? 100)
+    const limit = filter.limit ?? 100
+    const out: DcwJournalAnchor[] = []
+    // 走索引:候选集已按 nodeId 收窄,且天然时间正序 → 倒序遍历
+    const source = filter.nodeId ? this.nodeAnchors.get(filter.nodeId) : this.db.anchors
+    if (!source) return out
+    for (let i = source.length - 1; i >= 0 && out.length < limit; i--) {
+      const a = source[i]!
+      if (filter.nodeId && a.nodeId !== filter.nodeId) continue
+      if (filter.lineId && a.lineId !== filter.lineId) continue
+      if (filter.source && a.source !== filter.source) continue
+      out.push(a)
+    }
+    return out
   }
 
-  /** 最近一次回退锚(冷却判断用) */
+  /** 最近一次回退锚(冷却判断用)。只扫该节点子序列,命中即返回 —— 绝大多数情况 O(1)。 */
   lastRollbackAnchor(nodeId: string): DcwJournalAnchor | undefined {
-    for (let i = this.db.anchors.length - 1; i >= 0; i--) {
-      const a = this.db.anchors[i]!
-      if (a.nodeId === nodeId && a.source === 'rollback')
+    const arr = this.nodeAnchors.get(nodeId)
+    if (!arr) return undefined
+    for (let i = arr.length - 1; i >= 0; i--) {
+      const a = arr[i]!
+      if (a.source === 'rollback')
         return a
     }
     return undefined
@@ -135,8 +213,14 @@ export class RecipeRollBackRepo {
   insertRecord(r: Omit<OptimizationRecord, 'id' | 'createdAt'> & { id?: string, createdAt?: string }): OptimizationRecord {
     const record: OptimizationRecord = { ...r, id: r.id ?? `opt-${randomUUID().slice(0, 8)}`, createdAt: r.createdAt ?? new Date().toISOString() }
     this.db.records.push(record)
-    if (this.db.records.length > RECORDS_CAP)
-      this.db.records.splice(0, this.db.records.length - RECORDS_CAP)
+    if (record.status === 'open') this.openByNode.set(record.nodeId, record)
+    if (this.db.records.length > RECORDS_CAP) {
+      const evicted = this.db.records.splice(0, this.db.records.length - RECORDS_CAP)
+      // 淘汰的记录若仍是索引里的 open,需要让其自然失效(索引指向已不在册的对象)
+      for (const e of evicted) {
+        if (this.openByNode.get(e.nodeId) === e) this.openByNode.delete(e.nodeId)
+      }
+    }
     this.flushDebounced()
     return record
   }
@@ -145,32 +229,49 @@ export class RecipeRollBackRepo {
     return this.db.records.find(r => r.id === id)
   }
 
+  /** 该节点当前 open 记录(O(1):索引) */
   openRecordOf(nodeId: string): OptimizationRecord | undefined {
-    return this.db.records.find(r => r.nodeId === nodeId && r.status === 'open')
+    const r = this.openByNode.get(nodeId)
+    return r && r.status === 'open' ? r : undefined
+  }
+
+  /** 当前全部 open 记录(供 sweep 评估;避免每次全量 reverse+filter 2000 条) */
+  listOpenRecords(): OptimizationRecord[] {
+    const out: OptimizationRecord[] = []
+    for (const r of this.openByNode.values()) {
+      if (r.status === 'open') out.push(r)
+    }
+    return out
   }
 
   updateRecord(id: string, patch: Partial<OptimizationRecord>): OptimizationRecord | undefined {
     const r = this.byId(id)
     if (!r)
       return undefined
+    const wasOpen = r.status === 'open'
     Object.assign(r, patch)
+    // 维护 open 索引(状态可能 open→judged/rolled-back/superseded)
+    if (r.status === 'open') this.openByNode.set(r.nodeId, r)
+    else if (wasOpen && this.openByNode.get(r.nodeId) === r) this.openByNode.delete(r.nodeId)
     this.flushDebounced()
     return r
   }
 
+  /** 倒序查询优化记录。单遍倒序 + limit 短路,替代「全量拷贝→reverse→逐条件 filter」的两次 O(n) 分配。 */
   listRecords(filter: { lineId?: string, recipeId?: string, nodeId?: string, status?: string, agentId?: string, limit?: number }): OptimizationRecord[] {
-    let list = [...this.db.records].reverse()
-    if (filter.lineId)
-      list = list.filter(r => r.lineId === filter.lineId)
-    if (filter.recipeId)
-      list = list.filter(r => r.recipeId === filter.recipeId)
-    if (filter.nodeId)
-      list = list.filter(r => r.nodeId === filter.nodeId)
-    if (filter.status)
-      list = list.filter(r => r.status === filter.status)
-    if (filter.agentId)
-      list = list.filter(r => r.agentId === filter.agentId)
-    return list.slice(0, filter.limit ?? 100)
+    const limit = filter.limit ?? 100
+    const out: OptimizationRecord[] = []
+    const src = this.db.records
+    for (let i = src.length - 1; i >= 0 && out.length < limit; i--) {
+      const r = src[i]!
+      if (filter.lineId && r.lineId !== filter.lineId) continue
+      if (filter.recipeId && r.recipeId !== filter.recipeId) continue
+      if (filter.nodeId && r.nodeId !== filter.nodeId) continue
+      if (filter.status && r.status !== filter.status) continue
+      if (filter.agentId && r.agentId !== filter.agentId) continue
+      out.push(r)
+    }
+    return out
   }
 
   /** 该节点的自动回退链长(防乒乓:链上已发生的回退记录数) */
@@ -179,7 +280,9 @@ export class RecipeRollBackRepo {
   }
 
   stats(): { anchors: number, records: number, open: number } {
-    return { anchors: this.db.anchors.length, records: this.db.records.length, open: this.db.records.filter(r => r.status === 'open').length }
+    let open = 0
+    for (const r of this.openByNode.values()) if (r.status === 'open') open++
+    return { anchors: this.db.anchors.length, records: this.db.records.length, open }
   }
 }
 

package/server/services/workshop/logger.ts

@@ -4,13 +4,28 @@
  * - 输出:单行 JSON(t/level/scope/msg/args),error/warn 走 stderr,其余 stdout
  * - 范围收敛:仅替换 server/services/workshop 目录的 console 直出
  *   (request-log、plugins、mcp 的 console 保留,见计划 R4-2,避免全量替换的回归面)
+ * - 同指纹限流(opt-in:warnThrottled / rateLimited):同 scope + 归一化后同文本在一个窗口内
+ *   只出首条,其余计数,窗口关闭补一条摘要 —— 防止单条消息刷盘淹没真实错误。
+ *   P0 背景:opcua 驱动每建连告警一条 securityMode=None,实测约 7 行/秒把生产日志灌到
+ *   18MB 且 100% 为同一句。基础四方法(debug/info/warn/error)语义不变。
  */
 import { settingOf } from './settings'
+// 必须走 @ 别名(与 shared/config/engine.mjs 一致):裸相对路径在 nitro dev 的
+// 服务端 bundle 里按输出目录重算,Windows 上 ../../.. 会溢出盘符根
+// → 'Cannot find module D:\shared\lru.mjs'(构建期 inline 兜不住 dev)。
+import { LruMap } from '@/shared/lru.mjs'
 
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
 
 const LEVELS: Record<LogLevel, number> = { debug: 10, info: 20, warn: 30, error: 40 }
 
+/** 同指纹限流窗口(ms):窗口内同 scope + 同归一化文本只出首条 */
+export const THROTTLE_WINDOW_MS = 60_000
+/** 指纹表容量上限(必须 > 0;LruMap 逐出最久未用,表永不无界增长) */
+export const THROTTLE_MAX_FINGERPRINTS = 512
+/** 过期窗口惰性结算的最小间隔(ms;避免每次调用都全表扫描) */
+const THROTTLE_SWEEP_MS = 1_000
+
 function minLevel(): LogLevel {
   // 配置未就绪/解析失败回落 info(日志层永不因配置抛错)
   try {
@@ -36,14 +51,76 @@ function safe(value: unknown): unknown {
   return value
 }
 
+/** 行输出槽:默认真实 stdout/stderr(生产行为不变);测试/嵌入方注入自有 sink */
+export interface LogSink {
+  /** 非 error/warn 级别(默认 stdout) */
+  out(line: string): void
+  /** error/warn 级别(默认 stderr) */
+  err(line: string): void
+}
+
+const consoleSink: LogSink = {
+  out: line => console.log(line),
+  err: line => console.error(line),
+}
+
+/**
+ * 归一化指纹文本:ISO 时间戳与数字串 → 占位符。
+ * 'poll 1234 ms' 与 'poll 5678 ms' 归为同键;键是廉价字符串,不做对象序列化。
+ */
+export function normalizeFingerprint(msg: string): string {
+  return msg
+    .replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:?\d{2})?/g, '<ts>')
+    .replace(/\d+/g, '<n>')
+}
+
+/** 单指纹窗口状态(仅 suppressed>0 的条目会在窗口关闭时补摘要) */
+interface ThrottleEntry {
+  level: LogLevel
+  windowStart: number
+  suppressed: number
+}
+
+/** 有界指纹表的最小类型面(LruMap 为树外 .mjs,无类型声明) */
+interface FingerprintTable {
+  readonly size: number
+  get(key: string): ThrottleEntry | undefined
+  set(key: string, value: ThrottleEntry): unknown
+  delete(key: string): unknown
+  entries(): Iterable<[string, ThrottleEntry]>
+  values(): Iterable<ThrottleEntry>
+  stats(): { size: number, max: number, evictions: number }
+}
+
+/** 限流器内部状态(回归测试断言表有界;不参与业务) */
+export interface ThrottleStats {
+  /** 当前指纹条目数(恒 ≤ max) */
+  size: number
+  max: number
+  /** 当前窗口内尚未结算的抑制计数合计 */
+  suppressed: number
+  /** 已结算(已补摘要)的窗口数 */
+  windows: number
+  /** 因容量上限被逐出的指纹数(逐出即丢弃其未结算计数) */
+  evictions: number
+}
+
 export interface Logger {
   debug(msg: string, ...args: unknown[]): void
   info(msg: string, ...args: unknown[]): void
   warn(msg: string, ...args: unknown[]): void
   error(msg: string, ...args: unknown[]): void
+  /** opt-in 同指纹限流(任意级别;上面四个方法不经过此路径) */
+  rateLimited(level: LogLevel, msg: string, ...args: unknown[]): void
+  /** warn 级同指纹限流(高频告警点收口:首条全量,窗口内其余计数,窗口关闭补摘要) */
+  warnThrottled(msg: string, ...args: unknown[]): void
+  /** 结算已到期窗口的抑制摘要(true = 连未到期窗口一并结算;进程退出/测试用) */
+  flushThrottled(force?: boolean): void
+  /** 限流器状态快照 */
+  throttleStats(): ThrottleStats
 }
 
-export function createLogger(scope: string): Logger {
+export function createLogger(scope: string, sink: LogSink = consoleSink): Logger {
   const emit = (level: LogLevel, msg: string, args: unknown[]): void => {
     if (LEVELS[level] < LEVELS[minLevel()]) return
     const line = JSON.stringify({
@@ -53,13 +130,78 @@ export function createLogger(scope: string): Logger {
       msg,
       ...(args.length ? { args: args.map(safe) } : {}),
     })
-    if (level === 'error' || level === 'warn') console.error(line)
-    else console.log(line)
+    if (level === 'error' || level === 'warn') sink.err(line)
+    else sink.out(line)
+  }
+
+  // ---------- opt-in 同指纹限流(表有界;基础四方法不经过此路径) ----------
+  const table = new LruMap(THROTTLE_MAX_FINGERPRINTS) as unknown as FingerprintTable
+  let lastSweep = 0
+  let windows = 0
+
+  /** 结算一个窗口:有抑制则补一条摘要,并移除条目(下次调用重建窗口,表随用随收) */
+  const settle = (key: string, entry: ThrottleEntry): void => {
+    table.delete(key)
+    if (entry.suppressed <= 0) return
+    windows += 1
+    emit(entry.level, `[log-throttle] 同指纹消息在 ${THROTTLE_WINDOW_MS}ms 窗口内被抑制 ${entry.suppressed} 条(scope=${scope})`, [])
+  }
+
+  /** 惰性结算已到期窗口(最多每秒一次;顺带回收条目,长时间静默的指纹不占表) */
+  const sweep = (now: number): void => {
+    if (now - lastSweep < THROTTLE_SWEEP_MS) return
+    lastSweep = now
+    for (const [key, entry] of table.entries()) {
+      if (entry.suppressed > 0 && now - entry.windowStart >= THROTTLE_WINDOW_MS) settle(key, entry)
+    }
+  }
+
+  const throttledEmit = (level: LogLevel, msg: string, args: unknown[]): void => {
+    if (LEVELS[level] < LEVELS[minLevel()]) return
+    const now = Date.now()
+    sweep(now)
+    const key = `${scope}\u0000${level}\u0000${normalizeFingerprint(msg)}`
+    const hit = table.get(key)
+    if (hit === undefined) {
+      table.set(key, { level, windowStart: now, suppressed: 0 })
+      emit(level, msg, args)
+      return
+    }
+    if (now - hit.windowStart < THROTTLE_WINDOW_MS) {
+      hit.suppressed += 1
+      return
+    }
+    // 窗口关闭:先补摘要,本条即新窗口首条(全量输出)
+    settle(key, hit)
+    table.set(key, { level, windowStart: now, suppressed: 0 })
+    emit(level, msg, args)
+  }
+
+  const flushThrottled = (force = false): void => {
+    const now = Date.now()
+    lastSweep = now
+    const due: [string, ThrottleEntry][] = []
+    for (const [key, entry] of table.entries()) {
+      if (entry.suppressed > 0 && (force || now - entry.windowStart >= THROTTLE_WINDOW_MS)) due.push([key, entry])
+    }
+    for (const [key, entry] of due) settle(key, entry)
+  }
+
+  const throttleStats = (): ThrottleStats => {
+    let suppressed = 0
+    for (const entry of table.values()) suppressed += entry.suppressed
+    const s = table.stats()
+    return { size: s.size, max: s.max, suppressed, windows, evictions: s.evictions }
   }
+
   return {
     debug: (msg, ...args) => emit('debug', msg, args),
     info: (msg, ...args) => emit('info', msg, args),
     warn: (msg, ...args) => emit('warn', msg, args),
     error: (msg, ...args) => emit('error', msg, args),
+    rateLimited: (level, msg, ...args) => throttledEmit(level, msg, args),
+    warnThrottled: (msg, ...args) => throttledEmit('warn', msg, args),
+    flushThrottled,
+    throttleStats,
   }
 }