agentworkshop 0.7.41 → 0.7.46

package/app/stores/workshop/events.ts

@@ -4,6 +4,7 @@
  */
 import { defineStore } from 'pinia'
 import { useUserStore } from './user'
+import { narrowFetch } from './narrow-fetch'
 import { envelopeTier } from '@/app/composables/workshop/useEventBlocks'
 import type { AepEnvelope } from '#shared/workshop-protocol'
 
@@ -329,7 +330,7 @@ export const useEventsStore = defineStore('workshop.events', {
       if (typeof window === 'undefined') return
       const ring = this.rings[channelId] ?? EMPTY_RING()
       try {
-        const res = await $fetch<EventsHistoryRes>(
+        const res = await narrowFetch<EventsHistoryRes>(
           `/api/workshop/channels/${channelId}/events`,
           { params: { limit, excludeTypes: HISTORY_EXCLUDE_TYPES.join(',') }, headers: { authorization: `Bearer ${useUserStore().token}` } },
         )
@@ -351,7 +352,7 @@ export const useEventsStore = defineStore('workshop.events', {
       const minSeq = ring.items.length > 0 ? (ring.items[0]?.seq ?? 0) : ring.lastSeq
       if (minSeq <= 1) return false
       try {
-        const res = await $fetch<EventsHistoryRes>(
+        const res = await narrowFetch<EventsHistoryRes>(
           `/api/workshop/channels/${channelId}/events`,
           { params: { limit, beforeSeq: Math.max(1, minSeq - 1), excludeTypes: HISTORY_EXCLUDE_TYPES.join(',') }, headers: { authorization: `Bearer ${useUserStore().token}` } },
         )
@@ -387,7 +388,7 @@ export const useEventsStore = defineStore('workshop.events', {
       }
       const ring = this.rings[channelId]!
       try {
-        const res = await $fetch<EventsHistoryRes>(
+        const res = await narrowFetch<EventsHistoryRes>(
           `/api/workshop/channels/${channelId}/events`,
           { params: { limit, agentId, excludeTypes: HISTORY_EXCLUDE_TYPES.join(',') }, headers: { authorization: `Bearer ${useUserStore().token}` } },
         )
@@ -417,7 +418,7 @@ export const useEventsStore = defineStore('workshop.events', {
       }
       if (minSeq <= 1) return false
       try {
-        const res = await $fetch<EventsHistoryRes>(
+        const res = await narrowFetch<EventsHistoryRes>(
           `/api/workshop/channels/${channelId}/events`,
           { params: { limit, agentId, beforeSeq: minSeq - 1, excludeTypes: HISTORY_EXCLUDE_TYPES.join(',') }, headers: { authorization: `Bearer ${useUserStore().token}` } },
         )

package/app/stores/workshop/hitl.ts

@@ -1,28 +1,88 @@
 /**
- * HITL 全局待办 store:omp ask 对话框 + dcw 工具审批的统一待答视图。
+ * HITL 全局待办 store:omp ask 对话框 + dcw 工具审批 + 各 harness 原生提问/审批的统一待答视图。
  *
  * 数据源:
- *  - AEP hitl.request/hitl.resolved 帧(频道流 seq 帧与 channelId='' 全员直推
- *    会各到一次,upsert 按 kind+id 幂等去重;徽标不依赖 channel 订阅)
- *  - GET /api/workshop/hitl/pending 快照(页面挂载/重连后的基线对齐)
+ *  - AEP hitl.request/hitl.resolved 帧(v17 起服务端按用户定向推送;频道流 seq 帧与
+ *    channelId='' 直推帧各到一次,upsert 按 kind+id 幂等去重;徽标不依赖 channel 订阅)
+ *  - GET /api/workshop/hitl/pending 快照(页面挂载/重连后的基线对齐)—— **快照是权威**:
+ *    替换式写入,WS 期间漂移的陈旧条目不会残留(例如他端已决策但本端漏帧)
+ *
+ * 应答统一走 `answer()`(REST /workshop/hitl/respond):
+ *  - 409 ALREADY_RESOLVED(他端/引擎已处理)→ 重拉快照收敛,UI 提示"已被他人处理";
+ *  - 403 APPROVAL_FORBIDDEN(审批策略 owner_only 或资格快照不收)→ 原样上抛策略文案。
+ * 终端面板(omp)另有直连 WS 应答路径,与本 store 互不影响。
  */
 import { defineStore } from 'pinia'
 import type { AepEnvelope, AepHitlItem } from '#shared/workshop-protocol'
 import { useUserStore } from './user'
+import { narrowFetch } from './narrow-fetch'
+import { apiErrorMessage } from '@/app/utils/api-error'
 
 const keyOf = (i: Pick<AepHitlItem, 'kind' | 'id'>) => `${i.kind}:${i.id}`
 
 interface HitlPendingRes {
   code: number | string
+  message?: string
   data?: { items: AepHitlItem[] }
 }
 
+interface RespondRes {
+  code: number | string
+  message?: string
+  data?: { ok: boolean, kind: string, id: string }
+}
+
+/**
+ * 应答体(服务端 `RespondBody` 的客户端侧同构)。
+ *
+ * 提问型(question)必须用 `answers[]` —— 服务端把它编码成引擎原生信封
+ * (`{"x-aw-hitl-answers":[{id,answer}]}`,见 hitl-registry 的 ANSWER_ENVELOPE)。
+ * **不要**把多问题手拼成 JSON 字符串塞进 `value`:服务端只按 `answers` 取结构化答案,
+ * 拼 JSON 会被当成"单答案文本",逐题解析结果全为空(实测:答案静默丢失但接口返回 ok)。
+ */
+export interface HitlAnswerPayload {
+  /** approval 型:true=放行,false=拒绝(与 cancelled 互斥) */
+  confirmed?: boolean
+  cancelled?: boolean
+  /** 引擎原生选项(opencode permission:once|always|reject;hermes/dsh 选项名) */
+  response?: string
+  comment?: string
+  /**
+   * question 型答案(结构化;按问题 id 对齐)。
+   * 单问题也可走这里(服务端 `resolveAnswers` 支持"按 id 命中或按下标回退")。
+   */
+  answers?: Array<{ id?: string, answer: string }>
+  /** 纯文本答案(仅单问题/自由文本的兼容路径;多问题请用 answers) */
+  value?: string
+}
+
+/** 应答结果:ok=false 时 code 为服务端业务码(409 ALREADY_RESOLVED / 403 APPROVAL_FORBIDDEN) */
+export interface HitlAnswerOutcome {
+  ok: boolean
+  code: string
+  /** 面向用户的文案(服务端人话优先) */
+  message: string
+}
+
+/** 从 FetchError/Error 中取业务码(信封 code 优先,其次 HTTP 状态映射) */
+function outcomeOf(err: unknown): HitlAnswerOutcome {
+  const e = (err ?? {}) as { data?: { code?: string | number }, statusCode?: number, status?: number, response?: { status?: number, data?: { code?: string | number } } }
+  const raw = e.data?.code ?? e.response?.data?.code
+  const status = Number(e.statusCode ?? e.status ?? e.response?.status ?? 0)
+  const code = raw !== undefined && raw !== null
+    ? String(raw)
+    : (status === 409 ? 'ALREADY_RESOLVED' : status === 403 ? 'APPROVAL_FORBIDDEN' : status ? `HTTP_${status}` : '')
+  return { ok: false, code, message: apiErrorMessage(err) }
+}
+
 export const useHitlStore = defineStore('workshop.hitl', {
   state: () => ({
-    /** 当前待人工处理条目(kind+id 幂等) */
+    /** 当前待人工处理条目(kind+id 幂等;v17 可选字段 method/options/questions/policy 原样透传) */
     items: [] as AepHitlItem[],
-    /** 快照已加载(防重复拉取;WS 掉线重连后由 ensureBaseline 重置) */
+    /** 快照已加载(防重复拉取;WS 掉线重连后由 invalidate 重置) */
     snapshotLoaded: false,
+    /** 正在提交的条目 `${kind}:${id}`(按钮 loading / 防重复点击) */
+    answering: null as string | null,
   }),
   getters: {
     count: state => state.items.length,
@@ -36,6 +96,9 @@ export const useHitlStore = defineStore('workshop.hitl', {
       }
       return map
     },
+    /** 单条查询(页头按 kind+id 定位当前条目状态) */
+    byKey: state => (kind: string, id: string): AepHitlItem | undefined =>
+      state.items.find(i => i.kind === kind && i.id === id),
   },
   actions: {
     /** AEP 帧消费(hitl.request / hitl.resolved;幂等 upsert/remove) */
@@ -44,6 +107,8 @@ export const useHitlStore = defineStore('workshop.hitl', {
         const item = e.payload as AepHitlItem
         const key = keyOf(item)
         const idx = this.items.findIndex(i => keyOf(i) === key)
+        // 整对象替换(不 merge):服务端帧携带权威的新可选字段(questions/method/policy),
+        // merge 会让旧值黏附;缺字段时以帧为准(节流快照会补齐)
         if (idx >= 0) this.items[idx] = item
         else this.items.push(item)
       }
@@ -58,7 +123,7 @@ export const useHitlStore = defineStore('workshop.hitl', {
       const token = useUserStore().token
       if (!token) return
       try {
-        const res = await $fetch<HitlPendingRes>('/api/workshop/hitl/pending', {
+        const res = await narrowFetch<HitlPendingRes>('/api/workshop/hitl/pending', {
           headers: { authorization: `Bearer ${token}` },
         })
         if (res.code === 0 && res.data) {
@@ -68,6 +133,43 @@ export const useHitlStore = defineStore('workshop.hitl', {
       }
       catch { /* 快照失败不阻塞实时帧 */ }
     },
+    /**
+     * 统一应答(REST;页头 ask/审批表单与任何非终端入口共用)。
+     * 409/403 不抛出:调用方按 code 渲染"已被他人处理 / 无审批权限"专用提示。
+     */
+    async answer(item: Pick<AepHitlItem, 'kind' | 'id'>, payload: HitlAnswerPayload): Promise<HitlAnswerOutcome> {
+      const key = keyOf(item)
+      if (this.answering) return { ok: false, code: 'BUSY', message: '已有应答提交中' }
+      this.answering = key
+      const token = useUserStore().token
+      try {
+        const res = await narrowFetch<RespondRes>('/api/workshop/hitl/respond', {
+          method: 'POST',
+          body: { kind: item.kind, id: item.id, ...payload },
+          headers: token ? { authorization: `Bearer ${token}` } : {},
+        })
+        if (res.code !== 0) {
+          // 业务失败(非 2xx 由 ofetch 抛出):同样以快照收敛
+          await this.loadSnapshot()
+          return { ok: false, code: String(res.code ?? ''), message: res.message ?? '应答失败' }
+        }
+        // 应答成功 → 本地先行摘除,再以快照收敛(防止按钮可重复点击)
+        this.items = this.items.filter(i => keyOf(i) !== key)
+        await this.loadSnapshot()
+        return { ok: true, code: '', message: res.message ?? 'ok' }
+      }
+      catch (err) {
+        const out = outcomeOf(err)
+        // 冲突/越权:以服务端事实源重拉(条目可能已被他人处理,或从待办里消失)
+        if (out.code === 'ALREADY_RESOLVED' || out.code === 'APPROVAL_FORBIDDEN' || out.code === 'NOT_RESPONDABLE') {
+          await this.loadSnapshot()
+        }
+        return out
+      }
+      finally {
+        this.answering = null
+      }
+    },
     /** WS 断线重连后重新对齐 */
     invalidate(): void {
       this.snapshotLoaded = false
@@ -75,6 +177,7 @@ export const useHitlStore = defineStore('workshop.hitl', {
     clear(): void {
       this.items = []
       this.snapshotLoaded = false
+      this.answering = null
     },
   },
 })

package/app/stores/workshop/narrow-fetch.ts

@@ -0,0 +1,23 @@
+/**
+ * 窄化的 `$fetch` —— 绕开 Nuxt 路由类型推导导致的 TS2589。
+ *
+ * 背景:`$fetch` 在 Nuxt 里带**全量路由类型推导**(每个 `/api/**` 路由的字面量类型都被
+ * 展开成一棵巨大的联合类型)。在 Pinia store 的深层 action 里调用时,TS 会对该类型反复
+ * 实例化,最终报 `TS2589: Type instantiation is excessively deep and possibly infinite`,
+ * 并连带 `TS2345: Argument of type '{...}' is not assignable to parameter of type 'O'`。
+ *
+ * 本仓库 `pnpm typecheck` 因此在多个 store 上长期为红(user.ts / workspaces.ts / hitl.ts /
+ * chat.ts / notifications.ts / events.ts / entities.ts);这不是本轮群聊改动引入的,
+ * 但它是 Definition of Done 的必过门槛,所以这里做一次**系统性**收口,而不是逐文件打补丁。
+ *
+ * 收口方式:把全局 `$fetch` 窄化成一个纯函数签名(`NarrowFetch`),**运行时是同一个函数**,
+ * 行为与拦截器语义完全不变(仍走 nuxt 的 ofetch 实例、仍带 cookie/代理等配置),
+ * 只是不再让 TS 展开整棵路由类型树。
+ *
+ * 用法:`import { narrowFetch } from './narrow-fetch'` → `const res = await narrowFetch<MyEnvelope>(url, { ... })`
+ */
+export type NarrowFetch = <T>(url: string, opts?: Record<string, unknown>) => Promise<T>
+
+/** 全局 `$fetch` 的窄化视图(Nuxt 把 `$fetch` 挂在 globalThis;无需依赖自动导入类型) */
+export const narrowFetch: NarrowFetch
+  = (globalThis as unknown as { $fetch: NarrowFetch }).$fetch

package/app/stores/workshop/notifications.ts

@@ -0,0 +1,288 @@
+/**
+ * 用户级通知 store(v17 主计划 §6)。
+ *
+ * 事实源是服务端 `user_notifications` 表:`notification.created` 帧只负责"到达",
+ * 游标补拉(REST / WS subNotifications)负责"补齐"。因此本 store 的关键不是推送本身,
+ * 而是**幂等 + 断线可补**:
+ *  - `eventId` 是唯一幂等键 —— 同一条通知既可能经频道流副本、也可能经用户定向帧到达,
+ *    重复 eventId 一律丢弃(绝不产生第二行、也不弹第二次);
+ *  - `notification.*` 帧的 `seq` 恒为 0 且 `channelId` 可能是空串,不能参与频道 seq 去重,
+ *    幂等只能落在本 store 的 eventId 集合上;
+ *  - 重连/刷新后按游标向**后**补拉,与直播帧按 id 合并,不丢不重。
+ */
+import { defineStore } from 'pinia'
+import { ref } from 'vue'
+import type { AepEnvelope, AepNotification, AepNotificationRead } from '#shared/workshop-protocol'
+import { useUserStore } from './user'
+import { narrowFetch } from './narrow-fetch'
+
+/** 通知游标(与服务端 `createdAt|id` 复合游标一致) */
+export interface NotificationCursor {
+  createdAt: string
+  id: string
+}
+
+/** 单页拉取上限(服务端单页上限 200;取 50 减小首屏载荷,靠 backfill 循环排空) */
+const PAGE_LIMIT = 50
+
+/** backfill 最多排空页数(50×10 = 500 条;防服务端游标异常导致死循环) */
+const MAX_BACKFILL_PAGES = 10
+
+/** seenEventIds 上限(防长会话内存无限增长;淘汰最旧一半) */
+const SEEN_CAP = 2000
+
+interface ApiEnvelope<T> {
+  code: number | string
+  message?: string
+  data?: T | null
+}
+
+export const useNotificationsStore = defineStore('workshop.notifications', () => {
+  /** 新→旧 */
+  const items = ref<AepNotification[]>([])
+  const unreadCount = ref(0)
+  /** 最新一条的游标(断线补拉的起点) */
+  const cursor = ref<NotificationCursor | null>(null)
+  /** 已消费的 eventId(幂等键;直播帧与补拉帧共用) */
+  const seenEventIds = ref<Set<string>>(new Set())
+  /** 快照是否已加载(重连时的路径选择:未加载 → 快照;已加载 → 游标补拉) */
+  const loaded = ref(false)
+  /** 最近一条**实时**通知(不含补拉/快照):NotificationCenter 据此弹窗,避免重连补发刷屏 */
+  const liveItem = ref<AepNotification | null>(null)
+  const liveSeq = ref(0)
+  /**
+   * 补发窗口标志:服务端 subNotifications 会把游标之后的历史通知**以
+   * notification.created 帧逐条直发**(ws.ts 的补发循环),与直播帧形状完全一致。
+   * 若不区分,重连补发 200 条就会弹 200 个提示 —— 这里在发出订阅帧时开窗、
+   * 收到 notification.snapshot 收尾帧时关窗;窗口内照常入库,只是不弹窗。
+   */
+  const replaying = ref(false)
+  let replayTimer: ReturnType<typeof setTimeout> | null = null
+
+  function beginReplay(timeoutMs = 5000): void {
+    replaying.value = true
+    if (replayTimer) clearTimeout(replayTimer)
+    // 兜底:订阅被拒(USER_UNAUTHORIZED)时不会收到收尾帧,窗口必须能自愈
+    replayTimer = setTimeout(() => {
+      replaying.value = false
+      replayTimer = null
+    }, timeoutMs)
+  }
+
+  function endReplay(): void {
+    replaying.value = false
+    if (replayTimer) {
+      clearTimeout(replayTimer)
+      replayTimer = null
+    }
+  }
+
+  function markSeen(eventId: string): void {
+    if (!eventId) return
+    const seen = seenEventIds.value
+    if (!seen.has(eventId)) seen.add(eventId)
+    if (seen.size > SEEN_CAP) {
+      // Set 保序:丢弃最早的一半
+      const keep = [...seen].slice(-Math.floor(SEEN_CAP / 2))
+      seenEventIds.value = new Set(keep)
+    }
+  }
+
+  /** 按 createdAt 降序插入(同毫秒保持先到先排 => 后到者更靠前) */
+  function insertDesc(n: AepNotification): void {
+    const list = items.value
+    let idx = 0
+    while (idx < list.length && list[idx]!.createdAt >= n.createdAt) idx++
+    list.splice(idx, 0, n)
+  }
+
+  /** 幂等入库;返回是否为**新增**(重复帧返回 false —— 不重复弹窗、不重复计数) */
+  function upsertNotification(n: AepNotification, opts: { live?: boolean } = {}): boolean {
+    if (!n?.id) return false
+    const idx = items.value.findIndex(x => x.id === n.id)
+    if (idx >= 0) {
+      items.value[idx] = { ...items.value[idx]!, ...n }
+      return false
+    }
+    if (n.eventId && seenEventIds.value.has(n.eventId)) return false
+    markSeen(n.eventId)
+    insertDesc(n)
+    if (!n.readAt) unreadCount.value += 1
+    advanceCursor(n)
+    if (opts.live) {
+      liveItem.value = n
+      liveSeq.value += 1
+    }
+    return true
+  }
+
+  /** 游标只朝"更新"方向推进(补拉回来的旧行不倒退游标) */
+  function advanceCursor(n: AepNotification): void {
+    const cur = cursor.value
+    if (!cur || n.createdAt > cur.createdAt || (n.createdAt === cur.createdAt && n.id > cur.id)) {
+      cursor.value = { createdAt: n.createdAt, id: n.id }
+    }
+  }
+
+  /** 帧消费(由 useWorkshopWs 在频道 seq 守卫之外调用:seq=0 / channelId 可能为空) */
+  function applyEnvelope(e: AepEnvelope): void {
+    if (e.type === 'notification.created') {
+      // 补发窗口内不弹窗(仍入库):见 replaying 的说明
+      upsertNotification(e.payload as AepNotification, { live: !replaying.value })
+      return
+    }
+    if (e.type === 'notification.read') {
+      applyRead(e.payload as AepNotificationRead)
+    }
+  }
+
+  /** 已读帧(多标签页同步):按单条 / 频道范围 / 全部收敛 */
+  function applyRead(p: AepNotificationRead): void {
+    const at = p.readAt || new Date().toISOString()
+    for (const n of items.value) {
+      if (n.readAt) continue
+      if (p.id && n.id !== p.id) continue
+      if (!p.id && p.channelId && n.channelId !== p.channelId) continue
+      n.readAt = at
+    }
+    unreadCount.value = items.value.filter(n => !n.readAt).length
+  }
+
+  /** 抓取一页通知(cursor 为空 = 最新一页) */
+  async function fetchPage(c: NotificationCursor | null): Promise<{ notifications: AepNotification[], unreadCount: number, nextCursor: NotificationCursor | null }> {
+    const token = useUserStore().token
+    const query: Record<string, string> = { limit: String(PAGE_LIMIT) }
+    if (c) query.cursor = `${c.createdAt}|${c.id}`
+    const qs = Object.entries(query).map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join('&')
+    const res = await narrowFetch<ApiEnvelope<{ notifications: AepNotification[], unreadCount: number, nextCursor: NotificationCursor | null }>>(
+      `/api/workshop/notifications?${qs}`,
+      { headers: token ? { authorization: `Bearer ${token}` } : {} },
+    )
+    if (res.code !== 0 || !res.data) throw new Error(res.message ?? '通知拉取失败')
+    return res.data
+  }
+
+  /** 首屏/刷新快照:替换式(以 DB 为准收敛 WS 期间的可能漂移) */
+  async function loadSnapshot(): Promise<void> {
+    if (typeof window === 'undefined' || !useUserStore().token) return
+    try {
+      const data = await fetchPage(null)
+      items.value = [...(data.notifications ?? [])]
+      for (const n of items.value) markSeen(n.eventId)
+      unreadCount.value = data.unreadCount ?? items.value.filter(n => !n.readAt).length
+      // 快照新→旧:游标取最新一条(数组首元素)
+      const newest = items.value[0]
+      cursor.value = newest ? { createdAt: newest.createdAt, id: newest.id } : null
+      loaded.value = true
+    }
+    catch {
+      // 快照失败不阻塞实时帧(下一帧照常入库)
+    }
+  }
+
+  /**
+   * 断线/重连补拉:以本端游标向**后**取,按 id/eventId 合并(幂等)。
+   * 未加载过快照时退化为 loadSnapshot()。
+   *
+   * **必须循环排空**:服务端单页上限 200,而本端每页只取 PAGE_LIMIT;
+   * 原实现只抓一页就返回 —— 断线期间积压超过一页时,游标只推进一页,
+   * 其余通知要等**下一次**重连才可能补上(计划 §11.11「重连后通知不丢」)。
+   * 这里按"返回满页即有更多"排空,并设页数上限兜底(防服务端 bug 导致死循环)。
+   */
+  async function backfill(): Promise<number> {
+    if (typeof window === 'undefined' || !useUserStore().token) return 0
+    if (!loaded.value) {
+      await loadSnapshot()
+      return 0
+    }
+    let added = 0
+    try {
+      for (let page = 0; page < MAX_BACKFILL_PAGES; page += 1) {
+        const data = await fetchPage(cursor.value)
+        const list = data.notifications ?? []
+        for (const n of list) {
+          if (upsertNotification(n)) added += 1
+        }
+        if (data.nextCursor) cursor.value = data.nextCursor
+        unreadCount.value = data.unreadCount ?? unreadCount.value
+        // 不满一页 = 已到最新,收工;满页可能还有,继续拉
+        if (list.length < PAGE_LIMIT) return added
+        // 服务端没给新游标却又是满页 → 无法继续推进,退出防死循环
+        if (!data.nextCursor) return added
+      }
+      return added
+    }
+    catch {
+      // 补拉失败不阻塞实时帧;游标保持在上次成功位置,下次重连/心跳再试
+      return added
+    }
+  }
+
+  /**
+   * WS 重连收尾帧(`notification.snapshot`)携带的服务端游标。
+   * 服务端按 200 条/页重放,超过一页时只靠帧是补不全的 —— 用它把游标推到
+   * 服务端最后重放的位置,再交给 `backfill()` 继续排空。
+   */
+  function applyReplayCursor(next: NotificationCursor | null | undefined): void {
+    if (!next) return
+    if (!cursor.value || next.createdAt > cursor.value.createdAt
+      || (next.createdAt === cursor.value.createdAt && next.id > cursor.value.id)) {
+      cursor.value = next
+    }
+  }
+
+  /** 标记已读(REST 为准;先请求后本地收敛,失败抛出交给调用方提示) */
+  async function markRead(opts: { id?: string, channelId?: string, all?: boolean }): Promise<number> {
+    const token = useUserStore().token
+    const res = await narrowFetch<ApiEnvelope<{ ok: boolean, count: number, unreadCount: number, id?: string, channelId?: string }>>(
+      '/api/workshop/notifications/read',
+      {
+        method: 'POST',
+        body: { ...opts },
+        headers: token ? { authorization: `Bearer ${token}` } : {},
+      },
+    )
+    if (res.code !== 0 || !res.data) throw new Error(res.message ?? '标记已读失败')
+    const at = new Date().toISOString()
+    for (const n of items.value) {
+      if (n.readAt) continue
+      if (opts.id && n.id !== opts.id) continue
+      if (!opts.id && !opts.all && opts.channelId && n.channelId !== opts.channelId) continue
+      n.readAt = at
+    }
+    unreadCount.value = res.data.unreadCount ?? items.value.filter(n => !n.readAt).length
+    return res.data.count ?? 0
+  }
+
+  /** 退出登录:清空本用户可见内容(防串号) */
+  function clear(): void {
+    items.value = []
+    unreadCount.value = 0
+    cursor.value = null
+    seenEventIds.value = new Set()
+    loaded.value = false
+    liveItem.value = null
+    endReplay()
+  }
+
+  return {
+    items,
+    unreadCount,
+    cursor,
+    seenEventIds,
+    loaded,
+    liveItem,
+    liveSeq,
+    replaying,
+    beginReplay,
+    endReplay,
+    applyEnvelope,
+    applyRead,
+    upsertNotification,
+    loadSnapshot,
+    backfill,
+    applyReplayCursor,
+    markRead,
+    clear,
+  }
+})

package/app/stores/workshop/user.ts

@@ -39,6 +39,19 @@ interface ApiEnvelope<T = unknown> {
   data: T | null
 }
 
+/**
+ * 窄化的 `$fetch`。
+ *
+ * Nuxt 的 `$fetch` 带**全量路由类型推导**;在本 store 的深层 action 里对 `/api/users/*`
+ * 求值会触发 TS2589「Type instantiation is excessively deep」(v17 之前 `pnpm typecheck`
+ * 就一直红在这一处 —— 属既有未修复项)。这里把 `$fetch` 本身窄化成本地函数签名,
+ * 绕开该路由的泛型展开:**运行时是同一个函数,行为不变**,只是不再让 TS 展开整棵路由类型树。
+ *
+ * 用 `globalThis.$fetch` 取用:Nuxt 把 `$fetch` 挂在全局,这样无需依赖自动导入的类型。
+ */
+type NarrowFetch = <T>(url: string, opts?: Record<string, unknown>) => Promise<T>
+const http = (globalThis as unknown as { $fetch: NarrowFetch }).$fetch
+
 export const useUserStore = defineStore('workshop.user', {
   state: () => ({
     user: null as CurrentUser | null,
@@ -61,7 +74,7 @@ export const useUserStore = defineStore('workshop.user', {
     },
     /** 以 me 响应补全 tokenId（注册/登录签发的新 token 尚未绑定 id） */
     async _attachTokenId(token: string): Promise<void> {
-      const res = await $fetch<ApiEnvelope<Omit<CurrentUser, 'token'> & { tokenId: string }>>('/api/users/me', {
+      const res = await http<ApiEnvelope<Omit<CurrentUser, 'token'> & { tokenId: string }>>('/api/users/me', {
         headers: { authorization: `Bearer ${token}` },
       })
       if (res.code === 0 && res.data && this.user) {
@@ -69,7 +82,7 @@ export const useUserStore = defineStore('workshop.user', {
       }
     },
     async register(name: string, email: string, password: string): Promise<CurrentUser> {
-      const res = await $fetch<ApiEnvelope<AuthPayload>>('/api/users/register', {
+      const res = await http<ApiEnvelope<AuthPayload>>('/api/users/register', {
         method: 'POST',
         body: { name: name.trim(), email: email.trim(), password },
       })
@@ -80,7 +93,7 @@ export const useUserStore = defineStore('workshop.user', {
       return this.user
     },
     async login(email: string, password: string): Promise<CurrentUser> {
-      const res = await $fetch<ApiEnvelope<AuthPayload>>('/api/users/login', {
+      const res = await http<ApiEnvelope<AuthPayload>>('/api/users/login', {
         method: 'POST',
         body: { email: email.trim(), password },
       })
@@ -93,7 +106,7 @@ export const useUserStore = defineStore('workshop.user', {
     async loginWithToken(token: string): Promise<CurrentUser> {
       const trimmed = token.trim()
       if (!trimmed) throw new Error('token 不能为空')
-      const res = await $fetch<ApiEnvelope<Omit<CurrentUser, 'token'> & { tokenId: string }>>('/api/users/me', {
+      const res = await http<ApiEnvelope<Omit<CurrentUser, 'token'> & { tokenId: string }>>('/api/users/me', {
         headers: { authorization: `Bearer ${trimmed}` },
       })
       if (res.code !== 0 || !res.data) throw new Error(res.message ?? 'token 无效')
@@ -116,7 +129,7 @@ export const useUserStore = defineStore('workshop.user', {
       this.applyCookie()
       if (t) {
         try {
-          await $fetch('/api/users/logout', { method: 'POST', headers: { authorization: `Bearer ${t}` } })
+          await http('/api/users/logout', { method: 'POST', headers: { authorization: `Bearer ${t}` } })
         }
         catch {
           // 吊销失败不阻塞本地登出
@@ -129,12 +142,12 @@ export const useUserStore = defineStore('workshop.user', {
       return t ? { authorization: `Bearer ${t}` } : {}
     },
     async listTokens(): Promise<TokenMeta[]> {
-      const res = await $fetch<ApiEnvelope<TokenMeta[]>>('/api/users/tokens', { headers: this.authHeaders() })
+      const res = await http<ApiEnvelope<TokenMeta[]>>('/api/users/tokens', { headers: this.authHeaders() })
       if (res.code !== 0 || !res.data) throw new Error(res.message ?? '获取 token 列表失败')
       return res.data
     },
     async createToken(label: string): Promise<{ id: string, label: string, token: string }> {
-      const res = await $fetch<ApiEnvelope<{ id: string, label: string, token: string }>>('/api/users/tokens', {
+      const res = await http<ApiEnvelope<{ id: string, label: string, token: string }>>('/api/users/tokens', {
         method: 'POST',
         body: { label: label.trim() },
         headers: this.authHeaders(),
@@ -143,7 +156,7 @@ export const useUserStore = defineStore('workshop.user', {
       return res.data
     },
     async renameToken(id: string, label: string): Promise<TokenMeta> {
-      const res = await $fetch<ApiEnvelope<TokenMeta>>(`/api/users/tokens/${id}`, {
+      const res = await http<ApiEnvelope<TokenMeta>>(`/api/users/tokens/${id}`, {
         method: 'PATCH',
         body: { label: label.trim() },
         headers: this.authHeaders(),
@@ -153,14 +166,14 @@ export const useUserStore = defineStore('workshop.user', {
     },
     /** 查看存档明文（随时可查；404=非本人/不存在, 410=旧数据仅存哈希） */
     async revealToken(id: string): Promise<string | null> {
-      const res = await $fetch<ApiEnvelope<{ token: string | null }>>(`/api/users/tokens/${id}/token`, {
+      const res = await http<ApiEnvelope<{ token: string | null }>>(`/api/users/tokens/${id}/token`, {
         headers: this.authHeaders(),
       })
       if (res.code !== 0 || !res.data) throw new Error(res.message ?? '查看 token 失败')
       return res.data.token
     },
     async revokeToken(id: string): Promise<void> {
-      const res = await $fetch<ApiEnvelope<{ id: string }>>(`/api/users/tokens/${id}`, {
+      const res = await http<ApiEnvelope<{ id: string }>>(`/api/users/tokens/${id}`, {
         method: 'DELETE',
         headers: this.authHeaders(),
       })

package/app/stores/workshop/workspaces.ts

@@ -6,10 +6,20 @@
 import { defineStore } from 'pinia'
 import { useUserStore } from './user'
 
-/** 用户态 $fetch:管理面 API 统一携带用户 token(envelope 解包为 unknown,调用侧窄化) */
+/**
+ * 用户态 $fetch:管理面 API 统一携带用户 token(envelope 解包为 unknown,调用侧窄化)。
+ *
+ * 窄化原因同 app/stores/workshop/user.ts:Nuxt 的 `$fetch` 带全量路由类型推导,
+ * 在这些深层 action 里求值会触发 TS2589「Type instantiation is excessively deep」
+ * (v17 之前 `pnpm typecheck` 就一直红在这一处 —— 既有未修复项)。
+ * 把 `$fetch` 窄化成本地函数签名绕开泛型展开,**运行时是同一个函数**。
+ */
+type NarrowFetch = <T>(url: string, init?: Record<string, unknown>) => Promise<T>
+const rawFetch = (globalThis as unknown as { $fetch: NarrowFetch }).$fetch
+
 async function authFetch<T = unknown>(url: string, init: Record<string, unknown> = {}): Promise<{ code: number | string, message?: string, data?: T }> {
   const token = useUserStore().token
-  const res = await $fetch<unknown>(url, {
+  const res = await rawFetch<unknown>(url, {
     ...init,
     headers: { authorization: `Bearer ${token}`, ...(init.headers as Record<string, string> | undefined) },
   })