@allbluecn/web-app 0.19.2 → 0.19.4

package/src/lib/collab/bindings/canvas-local.ts

@@ -106,6 +106,7 @@ import {
   type CanvasDragShadow,
   type CanvasDragShadowItem,
 } from './canvas-presence'
+import { createThrottledFlush } from '../throttle-core'
 
 /**
  * 拖拽影子上报节流窗口：拖拽中间态是帧级高频（编辑器 MOVE 逐帧读回），
@@ -202,9 +203,21 @@ function blindNodeDrift(before: SceneNode, node: SceneNode): boolean {
   return false
 }
 
+/** 键序无关的稳定序列化（对象键排序后拼接；undefined 值剔除，同 JSON 口径） */
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'null'
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(',')}}`
+}
+
 function looseEqual(a: unknown, b: unknown): boolean {
   if (a === b) return true
-  return JSON.stringify(a ?? null) === JSON.stringify(b ?? null)
+  // 原实现裸 JSON.stringify 深比较：键序不同但内容相等会误判 drift，
+  // 多触发一次 sceneToYTree 全量对账写（无数据错误，纯性能噪声）
+  return stableStringify(a ?? null) === stableStringify(b ?? null)
 }
 
 function hasBlindDrift(prev: SceneDocument | null, next: SceneDocument): boolean {
@@ -246,9 +259,6 @@ export function createCanvasLocalBinding(
   /** 引擎最新文档缓存（onDocChange 载荷；影子节流 flush 用，避免重复 getDoc 读树） */
   let latestDoc: SceneDocument | null = null
 
-  let shadowTimer: ReturnType<typeof setTimeout> | null = null
-  let lastShadowAt = 0
-
   // ---- 本地 → Y（§7.2 本地方向）----
 
   const writeSceneToY = (next: SceneDocument): void => {
@@ -315,23 +325,16 @@ export function createCanvasLocalBinding(
     setDragField({ items, ts: Date.now() })
   }
 
-  /** leading 即时 + 窗口内合并尾随（同 canvas-presence 节流形态） */
-  const flushShadow = (): void => {
-    shadowTimer = null
+  /** 拖拽影子节流（leading 即时 + 窗口内合并尾随，公共 throttle-core）：
+   *  守卫（destroyed/dragging）在 run 内自理，释放/销毁时 cancel */
+  const shadowFlush = createThrottledFlush(throttleMs, () => {
     if (destroyed || !dragging) return
-    lastShadowAt = Date.now()
     writeDragShadow()
-  }
+  }, { leading: true })
 
   const scheduleShadow = (): void => {
     if (destroyed || !awareness || !dragging) return
-    const elapsed = Date.now() - lastShadowAt
-    if (elapsed >= throttleMs) {
-      flushShadow()
-      return
-    }
-    if (shadowTimer) return
-    shadowTimer = setTimeout(flushShadow, throttleMs - elapsed)
+    shadowFlush.schedule()
   }
 
   // ---- 拖拽生命周期接线（冻结接力 + 影子会话 + 释放最终态写 Y）----
@@ -345,7 +348,7 @@ export function createCanvasLocalBinding(
       dragIds = engine
         .getSelection()
         .filter((id) => id !== BOARD_NODE_ID)
-      lastShadowAt = 0
+      shadowFlush.reset()
       scheduleShadow() // leading 即时影子（拖拽起点位置即刻可见）
       return
     }
@@ -354,10 +357,7 @@ export function createCanvasLocalBinding(
     // Y 后解冻，全量对账的 next=引擎（远端字段陈旧）会把 Y 里的远端变更
     // 回滚，且解冻 flush 再把回滚态灌回引擎，远端数据双端永久丢失。
     // 1) 作废挂起影子 timer（防释放后复活）
-    if (shadowTimer) {
-      clearTimeout(shadowTimer)
-      shadowTimer = null
-    }
+    shadowFlush.cancel()
     // 2) 摘拖拽态先行：解冻引发的引擎收敛（T27 flush → notifyDocChange）
     //    走普通 doc-change 通道（diff 空零写），不再进影子节流
     dragging = false
@@ -395,10 +395,7 @@ export function createCanvasLocalBinding(
     destroy: () => {
       if (destroyed) return
       destroyed = true
-      if (shadowTimer) {
-        clearTimeout(shadowTimer)
-        shadowTimer = null
-      }
+      shadowFlush.cancel()
       unsubscribeDoc()
       unsubscribeDrag()
       if (dragging) {

package/src/lib/collab/bindings/canvas-presence.ts

@@ -56,6 +56,7 @@
 // 分层：无 React / 无 Leafer 依赖（engine 以结构子集注入，可脱离组件树单测
 // ——双客户端真实 Y.Doc + Awareness 直连验证，同 bindings-fields 先例）。
 
+import { createThrottledFlush } from '../throttle-core'
 import type {
   CollabAwareness,
   CollabConnectionStatus,
@@ -280,9 +281,6 @@ export function createCanvasPresenceBinding(
   let latestSelection: string[] = []
   let latestViewport: CanvasViewport = { x: 0, y: 0, zoom: 1 }
 
-  let flushTimer: ReturnType<typeof setTimeout> | null = null
-  let lastFlushAt = 0
-
   const notify = () => {
     version += 1
     for (const listener of listeners) listener()
@@ -312,24 +310,17 @@ export function createCanvasPresenceBinding(
     awareness.setLocalStateField(CANVAS_AWARENESS_KEY, state)
   }
 
-  /** leading 即时 + 窗口内合并尾随（50ms 交互级节流） */
+  /** 选中集/视口上报节流（leading 即时 + 窗口内合并尾随，公共 throttle-core，50ms 交互级） */
+  const presenceFlush = createThrottledFlush(throttleMs, () => {
+    // 冻结/offline 在窗口内翻转：落地前再查一次（仅暂停不销毁语义）
+    if (destroyed || frozen || status === 'offline') return
+    flush()
+  }, { leading: true })
+
   const scheduleFlush = () => {
     if (destroyed || !awareness) return
     if (frozen || status === 'offline') return
-    const elapsed = Date.now() - lastFlushAt
-    if (elapsed >= throttleMs) {
-      lastFlushAt = Date.now()
-      flush()
-      return
-    }
-    if (flushTimer) return
-    flushTimer = setTimeout(() => {
-      flushTimer = null
-      // 冻结/offline 在窗口内翻转：落地前再查一次（仅暂停不销毁语义）
-      if (destroyed || frozen || status === 'offline') return
-      lastFlushAt = Date.now()
-      flush()
-    }, throttleMs - elapsed)
+    presenceFlush.schedule()
   }
 
   const onEngineSelection = (ids: string[]) => {
@@ -351,10 +342,7 @@ export function createCanvasPresenceBinding(
     if (next === 'offline') {
       // 断连自动清：对端靠 awareness 超时/removed 感知离场；缓存保留供重放；
       // 挂起的尾随上报作废（offline 期间 scheduleFlush/flush 均短路）
-      if (flushTimer) {
-        clearTimeout(flushTimer)
-        flushTimer = null
-      }
+      presenceFlush.cancel()
       if (awareness && prev !== 'offline') removeCanvasKey(awareness)
     } else if (prev === 'offline' && next === 'synced') {
       // 恢复重放最新缓存（detach/attach 往返可能丢 local state，同 fields 防御）
@@ -404,10 +392,7 @@ export function createCanvasPresenceBinding(
     destroy: () => {
       if (destroyed) return
       destroyed = true
-      if (flushTimer) {
-        clearTimeout(flushTimer)
-        flushTimer = null
-      }
+      presenceFlush.cancel()
       unsubscribeEngine()
       if (awareness) {
         awareness.off('update', onAwarenessUpdate)

package/src/lib/collab/bindings/canvas-remote.ts

@@ -63,6 +63,7 @@ import {
   type CollabSceneDocument,
 } from '@allbluecn/collab-core/canvas-tree'
 import { CANVAS_LOCAL_ORIGIN } from './canvas-local'
+import { createThrottledFlush } from '../throttle-core'
 
 /**
  * 远端 update → flush 防抖窗口：远端画布编辑是手柄释放级低频（§7.1：拖拽中
@@ -126,10 +127,8 @@ export function createCanvasRemoteBinding(
   let frozen = false
   // 冻结期有 update 到达（或 flush 被冻结打断）→ 解冻后需补一次对账
   let pending = false
-  let timer: ReturnType<typeof setTimeout> | null = null
 
   const flush = () => {
-    timer = null
     if (destroyed) return
     if (frozen) {
       pending = true
@@ -163,9 +162,12 @@ export function createCanvasRemoteBinding(
     }
   }
 
+  // 远端 update 尾随合并防抖（公共 throttle-core；冻结期改记 pending，
+  // 解冻 flushNow 同步补应用）
+  const debounce = createThrottledFlush(debounceMs, flush, { leading: false })
   const schedule = () => {
-    if (destroyed || timer) return
-    timer = setTimeout(flush, debounceMs)
+    if (destroyed) return
+    debounce.schedule()
   }
 
   // observeDeep 回调签名经 Parameters 提取（YEvent 泛型约束 AbstractType，
@@ -196,30 +198,19 @@ export function createCanvasRemoteBinding(
         // 时冻结期到达的远端变更已收敛进引擎」——先收敛再写 Y，否则全量对账
         // 会回滚拖拽期间到达的远端变更（审查 C1）。即时化同时收口 T27 审查
         // minor②「解冻补应用过防抖窗」
-        if (timer) {
-          clearTimeout(timer)
-          timer = null
-        }
-        flush()
+        debounce.flushNow()
       }
     },
 
     reconcileNow: () => {
       if (destroyed) return
-      if (timer) {
-        clearTimeout(timer)
-        timer = null
-      }
-      flush()
+      debounce.flushNow()
     },
 
     destroy: () => {
       if (destroyed) return
       destroyed = true
-      if (timer) {
-        clearTimeout(timer)
-        timer = null
-      }
+      debounce.cancel()
       rootMap.unobserveDeep(onCanvasChange)
     },
   }

package/src/lib/collab/bindings/steps.ts

@@ -120,8 +120,12 @@ export function createStepBinding(source: StepBindingSource): StepBinding {
   let cachedSteps: CollabStepValue[] = EMPTY_STEPS
   let cachedStepsVersion = -1
 
-  const clamp = (value: number, max: number) =>
-    Math.max(0, Math.min(Math.floor(value), max))
+  // NaN 防御：Math.floor(NaN)/Math.max(0, NaN) 均为 NaN，会把 NaN 传给
+  // Y.Array.insert 抛运行时错误（at() 有 Number.isFinite 防御，口径对齐）
+  const clamp = (value: number, max: number) => {
+    if (!Number.isFinite(value)) return 0
+    return Math.max(0, Math.min(Math.floor(value), max))
+  }
 
   /** 读合法索引处的条目；越界返回 null（防御远端并发位移后的 stale 索引） */
   const at = (index: number): Y.Map<unknown> | null => {

package/src/lib/collab/module-map.ts

@@ -73,11 +73,12 @@ export interface ModuleRouteDef {
 /**
  * route.id ↔ module 映射表。按 link 长度降序排列（前缀匹配优先命中最长
  * 前缀，防未来出现 /bugs 与 /bugs-board 类嵌套前缀时误判）。
+ * 排序不变量由 presence-store.test.ts 钉住。
  */
 export const MODULE_ROUTES: readonly ModuleRouteDef[] = [
+  { id: 'inspiration', module: 'inspiration', link: '/inspiration' },
   { id: 'testcase', module: 'test-cases', link: '/test-cases' },
   { id: 'knowledge', module: 'knowledge', link: '/knowledge' },
-  { id: 'inspiration', module: 'inspiration', link: '/inspiration' },
   { id: 'home', module: 'dashboard', link: '/dashboard' },
   { id: 'harness', module: 'harness', link: '/harness' },
   { id: 'story', module: 'stories', link: '/stories' },

package/src/lib/collab/provider.ts

@@ -86,8 +86,6 @@ interface LiveEntry {
   listeners: Set<StatusListener>
   authFailures: number
   retryTimer: ReturnType<typeof setTimeout> | null
-  /** 自定义 ticket 获取（presence/share 等非实体 room）；缺省走实体 ticket serverFn */
-  getTicket?: TicketFetcher
   handle: CollabProviderHandle
 }
 
@@ -152,14 +150,20 @@ function acquireSharedSocket(url: string): SharedSocket {
     WebSocketPolyfill: webSocketPolyfillOverride,
     onStatus: ({ status }) => {
       if (status !== WebSocketStatus.Disconnected) return
-      // 网络断开：未 offline 的活连接回到 connecting（重连后 onOpen 自动重鉴权）
+      // 网络断开：未 offline 的活连接回到 connecting（重连后 onOpen 自动重鉴权）。
+      // 仅影响本 socket（socketUrl 匹配）上的 entry——共享池按 url 分池，
+      // 其他 socket 的连接不应被误伤
       for (const entry of liveEntries()) {
+        if (entry.socketUrl !== url) continue
         if (entry.status === 'synced') setEntryStatus(entry, 'connecting')
       }
     },
     onMaxAttemptsFailed: () => {
-      // socket 级重试耗尽：所有活连接进入 offline
-      for (const entry of liveEntries()) setEntryStatus(entry, 'offline')
+      // socket 级重试耗尽：本 socket 上的活连接进入 offline
+      for (const entry of liveEntries()) {
+        if (entry.socketUrl !== url) continue
+        setEntryStatus(entry, 'offline')
+      }
     },
   })
   const shared: SharedSocket = { socket, refCount: 1 }
@@ -244,7 +248,6 @@ function createLiveEntry(roomName: string, getTicket?: TicketFetcher): LiveEntry
     listeners: new Set(),
     authFailures: 0,
     retryTimer: null,
-    getTicket,
     handle: null as unknown as CollabProviderHandle,
   }
   entry.handle = buildHandle(entry)

package/src/lib/collab/throttle-core.ts

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+// 协同绑定层的公共节流/防抖核心（无 React 依赖，30-100ms 性能红线档）。
+// 三处消费方：bindings/canvas-local（拖拽影子 leading+尾随）、
+// bindings/canvas-presence（选中/视口上报 leading+尾随）、
+// bindings/canvas-remote（远端 update 尾随合并防抖）。
+// 短路/冻结等业务守卫由 run 回调自理（守卫不通过时窗口时基仍前进，
+// 调用方可在前置判断后再 schedule 以避免）。
+
+export interface ThrottledFlushHandle {
+  /** 窗口内合并调度：leading 模式窗口空闲即同步执行，否则挂一次尾随 */
+  schedule(): void
+  /** 立即执行一轮（绕过节流窗口；挂起的尾随 timer 先取消，不二次触发） */
+  flushNow(): void
+  /** 取消挂起的尾随执行（幂等） */
+  cancel(): void
+  /** 重置节流时基（下一次 schedule 恢复 leading 即时），同时取消挂起执行 */
+  reset(): void
+  /** 是否有挂起的尾随执行 */
+  isPending(): boolean
+}
+
+export function createThrottledFlush(
+  ms: number,
+  run: () => void,
+  options: { leading?: boolean } = {},
+): ThrottledFlushHandle {
+  const leading = options.leading ?? true
+  let timer: ReturnType<typeof setTimeout> | null = null
+  let lastAt = 0
+
+  const execute = () => {
+    if (timer) {
+      clearTimeout(timer)
+      timer = null
+    }
+    lastAt = Date.now()
+    run()
+  }
+
+  return {
+    schedule() {
+      if (timer) return
+      if (leading) {
+        const elapsed = Date.now() - lastAt
+        if (elapsed >= ms) {
+          execute()
+          return
+        }
+        timer = setTimeout(execute, ms - elapsed)
+        return
+      }
+      timer = setTimeout(execute, ms)
+    },
+    flushNow() {
+      execute()
+    },
+    cancel() {
+      if (timer) {
+        clearTimeout(timer)
+        timer = null
+      }
+    },
+    reset() {
+      this.cancel()
+      lastAt = 0
+    },
+    isPending() {
+      return timer !== null
+    },
+  }
+}

package/src/lib/collab/use-collab-doc.ts

@@ -19,6 +19,11 @@
 //      unmount/remount——useState 重新初始化重建连接，路径安全；应用主树
 //      未启用 React StrictMode，若未来启用需复查「state 保留 + effect
 //      cleanup 销毁」的组合，届时改为 effect 内创建）
+//      ⚠ 消费约束：handle.destroy() 无引用计数——同一 room 若被两个组件
+//      同时消费（单例表复用同一连接），先卸载的一方会拆掉另一方仍在用的
+//      连接。当前契约是「一页一消费者」（编辑器页面独占实体 room，route
+//      key={id} 整树重建）；新增多组件消费同一 room 的场景前，必须先在
+//      provider 层补 refCount，勿直接复用本 hook。
 //
 // 返回 null 的情形：SSR（服务端不建连——HocuspocusProvider/WebSocket 是
 // 纯浏览器资源，模块级单例表也不能在服务端累积）。消费方按「协同不可用」

package/src/lib/collab/use-presence-report.ts

@@ -91,13 +91,18 @@ export function usePresenceReport(): void {
   const throttledReport = useThrottledCallback(reportLocation, {
     wait: PRESENCE_REPORT_THROTTLE_MS,
   })
+  // useThrottledCallback 每次渲染可能返回新函数（use-presence-list-refresh
+  // debouncedRef 同款稳定化口径）：effect 经 ref 间接调用，deps 只留 pathname，
+  // 避免函数身份不稳定导致 effect 每渲染重跑
+  const throttledRef = useRef(throttledReport)
+  throttledRef.current = throttledReport
 
   // §8.1：路由变化 → 2s 节流更新 awareness local state。只用节流调用——
   // Throttler leading 即时首报（进新模块当次广播），窗口内快速导航合并为
   // 一次尾随；此前的未节流直调使节流形同虚设（审查重要②，已删）。
   useEffect(() => {
-    throttledReport(pathname)
-  }, [pathname, throttledReport])
+    throttledRef.current(pathname)
+  }, [pathname])
 
   useEffect(() => {
     if (!isCollabEnabled()) return
@@ -153,8 +158,10 @@ export function usePresenceReport(): void {
         reportLocation(pathnameRef.current)
         onAwarenessUpdate()
       })
-      .catch(() => {
-        // 引导失败（未登录/网络抖动）：presence 静默降级为不上报
+      .catch((e: unknown) => {
+        // 引导失败（未登录/网络抖动）：presence 静默降级为不上报，
+        // 但保留一条排查线索（「presence 不显示」无从下手曾无任何日志）
+        console.warn('[presence] 引导失败，presence 降级不上报:', e instanceof Error ? e.message : String(e))
       })
 
     return () => {

package/src/lib/collab/use-self-profile-broadcast.ts

@@ -108,6 +108,19 @@ export function useSelfProfileBroadcast(handle: CollabProviderHandle | null): vo
     return () => {
       cancelled = true
       unsubscribe()
+      // 卸载时外科手术式摘除 profile key（不可 setLocalState(null)——那会把
+      // 其他 hook 写的 state 一起清掉）：room 连接被其他组件续命（单例复用）
+      // 时，避免已卸载方的头像残留在 awareness
+      try {
+        const local = awareness.getLocalState() as Record<string, unknown> | null
+        if (local && 'profile' in local) {
+          const next = { ...local }
+          delete next.profile
+          awareness.setLocalState(next)
+        }
+      } catch {
+        // awareness 已随 handle 销毁等场景：忽略
+      }
     }
   }, [handle])
 }

package/src/lib/collab/use-share-presence.ts

@@ -372,14 +372,15 @@ function reportSelf(awareness: CollabAwareness, identity: ShareTicketIdentity):
 function startJoin(state: JoinState): void {
   void (async () => {
     try {
+      // 密码只读一次存局部变量：避免同一 key 两次 sessionStorage IO 与
+      // 两次读取间值变化的微妙不一致
+      const joinPassword = readSharePassword(state.designId, state.designver)
       const { ticket } = await createSharePresenceTicketFn({
         data: {
           shareToken: state.shareToken,
           // member 身份由服务端 session 判定（nickname 仅 guest 生效）
           nickname: readGuestNickname(),
-          ...(readSharePassword(state.designId, state.designver)
-            ? { password: readSharePassword(state.designId, state.designver) }
-            : {}),
+          ...(joinPassword ? { password: joinPassword } : {}),
         },
       })
       if (state.cancelled) return
@@ -399,18 +400,13 @@ function startJoin(state: JoinState): void {
         // 重连重取（token 为 async 函数，每次 onOpen 重新执行）：昵称/密码
         // 读最新值；服务端拒签走 provider 鉴权失败退避 → offline
         getTicket: async () => {
+          // 密码单次读取存局部变量（原条件判断与取值各读一次）
+          const pwd = readSharePassword(state.designId, state.designver)
           const fresh = await createSharePresenceTicketFn({
             data: {
               shareToken: state.shareToken,
               nickname: readGuestNickname(),
-              ...(readSharePassword(state.designId, state.designver)
-                ? {
-                    password: readSharePassword(
-                      state.designId,
-                      state.designver,
-                    ),
-                  }
-                : {}),
+              ...(pwd ? { password: pwd } : {}),
             },
           })
           return fresh.ticket
@@ -526,11 +522,15 @@ export function useSharePresence(
       startJoin(state)
     }
     joinState.refCount += 1
+    const acquired = joinState
 
     return () => {
-      if (!joinState) return
-      joinState.refCount -= 1
-      if (joinState.refCount <= 0) teardown()
+      // 仅当全局 joinState 仍是本 effect 实例 acquire 的那份才减计：
+      // 跨 token 快速切换（teardown 换代）后，旧 effect 的 cleanup 不得
+      // 把新 joinState 的 refCount 减到 0 误杀新连接
+      if (!acquired || joinState !== acquired) return
+      acquired.refCount -= 1
+      if (acquired.refCount <= 0) teardown()
     }
   }, [shareToken, designId, designver])
 

package/src/lib/collections/reference/users-brief-collection.ts

@@ -17,13 +17,16 @@
 
 import { createCollection } from '@tanstack/db'
 import { queryCollectionOptions } from '@tanstack/query-db-collection'
-import { listUsersBriefFn } from '@/server/serverFns/story/story-crud/labels'
+import { listUsersBriefFn } from '@/server/serverFns/story/story-crud/user-brief'
 import { getQueryClient } from '@/lib/query-client-seam'
 
+// 缓存失效方 import 常量而非硬编码字符串（knowledge-bases/workspaces 同口径）
+export const USERS_BRIEF_QUERY_KEY = ['users-brief'] as const
+
 export const usersBriefCollection = createCollection(
   queryCollectionOptions({
     id: 'users-brief',
-    queryKey: ['users-brief'],
+    queryKey: USERS_BRIEF_QUERY_KEY,
     queryFn: () => listUsersBriefFn(),
     getKey: (item: { id: string }) => item.id,
     queryClient: getQueryClient(),

package/src/lib/commands/registry.ts

@@ -39,7 +39,9 @@ export const COMMAND_REGISTRY: CommandDefinition[] = [
   { id: "create-story", title: m.common_command_createStory, icon: "clipboardList", group: "action", action: { kind: "callback", id: "create-story" }, keywords: ["新建需求", "xjxq"], shortcut: ["N", "S"] },
   { id: "toggle-theme", title: m.common_command_toggleTheme, icon: "sunMoon", group: "action", action: { kind: "callback", id: "toggle-theme" }, keywords: ["切换主题", "暗黑", "主题", "qhzt"], chord: ["Mod", "Shift", "L"] },
   { id: "sign-out", title: m.common_command_signOut, icon: "logOut", group: "action", action: { kind: "callback", id: "sign-out" }, keywords: ["退出登录", "登出", "tcdl"] },
-] as const
+]
+// 原尾缀 `as const` 与显式 `: CommandDefinition[]` 注解并用时字面量推断被
+// 注解拓宽，完全无效果，已删（二选一：去注解留 as const，或删 as const）
 
 export function getSequencePairs(registry: CommandDefinition[]): string[] {
   return registry

package/src/lib/comment-utils.ts

@@ -15,8 +15,10 @@
 // You should have received a copy of the GNU Affero General Public License
 // along with this program. If not, see <https://www.gnu.org/licenses/>.
 
+import { m } from '@/paraglide/messages.js'
+
 export function maskEmail(email?: string | null): string {
-  if (!email) return "未知用户";
+  if (!email) return m.common_comment_unknownUser();
   const [local, domain] = email.split("@");
   if (!domain) return email;
   const prefix = local.length > 3 ? local.slice(0, 3) : local;
@@ -28,18 +30,18 @@ export function formatTime(date: Date | string): string {
   const now = new Date();
   const diff = now.getTime() - d.getTime();
   const minutes = Math.floor(diff / 60000);
-  if (minutes < 1) return "刚刚";
-  if (minutes < 60) return `${minutes}分钟前`;
+  if (minutes < 1) return m.common_comment_justNow();
+  if (minutes < 60) return m.common_comment_minutesAgo({ n: minutes });
   const hours = Math.floor(minutes / 60);
-  if (hours < 24) return `${hours}小时前`;
+  if (hours < 24) return m.common_comment_hoursAgo({ n: hours });
   const days = Math.floor(hours / 24);
-  if (days < 7) return `${days}天前`;
+  if (days < 7) return m.common_comment_daysAgo({ n: days });
   return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")} ${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
 }
 
 export function formatEditedTime(date: Date | string): string {
   const time = formatTime(date);
-  return `修改于${time}`;
+  return m.common_comment_editedAt({ time });
 }
 
 export function getUserInitial(username: string): string {

package/src/lib/crypto/api-key-cipher.ts

@@ -1 +1,6 @@
+// ⚠ SERVER-ONLY 桥：本文件把服务端模块（AES-GCM / node:crypto 链）re-export 进
+// src/lib 命名空间——仅限服务端代码（src/server/**）import，客户端组件/路由
+// 值引入会把 prisma 级重的 node 链拉进浏览器 bundle。新代码请直连
+// `@/server/lib/api-key-cipher`；本桥暂留是因测试（provider-router.test）与
+// ai-ports 仍按此路径 mock/import，删除需同步改 mock 目标（记录于审计修复报告）。
 export * from '@/server/lib/api-key-cipher'

package/src/lib/datetime.ts

@@ -17,9 +17,18 @@
 
 import { formatInTimeZone, toZonedTime, fromZonedTime } from 'date-fns-tz'
 import { startOfDay, subDays } from 'date-fns'
+import { getLocale } from '@/paraglide/runtime'
+import { m } from '@/paraglide/messages.js'
 
 const FALLBACK_TIMEZONE = 'Asia/Shanghai'
 
+/** 日期格式串的 locale 分支（en 用 date-fns 英文 pattern，zh 用中文模式串） */
+function localizedDatePatterns(): { monthDay: string; full: string } {
+  return getLocale() === 'en'
+    ? { monthDay: 'MMM d', full: 'MMM d, yyyy' }
+    : { monthDay: 'M月d日', full: 'yyyy年M月d日' }
+}
+
 /**
  * 解析生效时区：项目时区 > 用户时区 > 浏览器时区 > Asia/Shanghai
  */
@@ -86,8 +95,8 @@ export function formatRelative(
 
     const dateStart = startOfDayInTimeZone(date, timezone)
 
-    if (dateStart.getTime() === todayStart.getTime()) return '今天'
-    if (dateStart.getTime() === yesterdayStart.getTime()) return '昨天'
+    if (dateStart.getTime() === todayStart.getTime()) return m.common_datetime_today()
+    if (dateStart.getTime() === yesterdayStart.getTime()) return m.common_datetime_yesterday()
     return formatInTimeZone(date, timezone, 'yyyy-MM-dd')
   } catch {
     return formatInTimeZone(date, FALLBACK_TIMEZONE, 'yyyy-MM-dd')
@@ -117,16 +126,17 @@ export function formatChatDate(date: Date, timezone: string): string {
 
     const dateStart = startOfDayInTimeZone(date, timezone)
 
-    if (dateStart.getTime() === todayStart.getTime()) return '今天'
-    if (dateStart.getTime() === yesterdayStart.getTime()) return '昨天'
-    if (dateStart.getTime() >= weekStart.getTime()) return '本周'
+    if (dateStart.getTime() === todayStart.getTime()) return m.common_datetime_today()
+    if (dateStart.getTime() === yesterdayStart.getTime()) return m.common_datetime_yesterday()
+    if (dateStart.getTime() >= weekStart.getTime()) return m.common_datetime_thisWeek()
 
     const currentYear = Number(formatInTimeZone(now, timezone, 'yyyy'))
     const dateYear = Number(formatInTimeZone(date, timezone, 'yyyy'))
+    const patterns = localizedDatePatterns()
     if (dateYear === currentYear) {
-      return formatInTimeZone(date, timezone, 'M月d日')
+      return formatInTimeZone(date, timezone, patterns.monthDay)
     }
-    return formatInTimeZone(date, timezone, 'yyyy年M月d日')
+    return formatInTimeZone(date, timezone, patterns.full)
   } catch {
     return formatInTimeZone(date, FALLBACK_TIMEZONE, 'yyyy-MM-dd')
   }