agentworkshop 0.2.1

package/scripts/test-agent-multi-channel.ts

@@ -0,0 +1,160 @@
+/**
+ * Agent 多 Channel 复用测试 —— 验证「Agent 模板可复用,放入每个 Channel 克隆出独立身份 id 的实例」。
+ *
+ * 覆盖:
+ *  1. 同一模板放入两个 channel → 克隆出两个独立身份 id 的实例(id 互不相同且不同于模板)
+ *  2. role/token 按实例独立
+ *  3. 元数据复制:实例复制模板 name/harness/config
+ *  4. 独立 AgentRuntime:同一模板的两实例各装配独立运行时
+ *  5. mailbox 按 channel 隔离
+ *  6. 移除实例 ≠ 删除模板
+ *  7. 模板更新不传播到已克隆实例(复制语义),新克隆取新值
+ *  8. 删除模板后实例保留
+ *
+ * 运行: npx tsx scripts/test-agent-multi-channel.ts
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { openWorkshopDb } from '../server/services/workshop/db/database'
+import { createChannelRepo } from '../server/services/workshop/db/channel.repo'
+import { createAgentRepo } from '../server/services/workshop/db/agent.repo'
+import { createChannelAgentRepo } from '../server/services/workshop/db/channel-agent.repo'
+import { createTaskRepo } from '../server/services/workshop/db/task.repo'
+import { createMemoryRepo } from '../server/services/workshop/db/memory.repo'
+import { createChannelEventRepo } from '../server/services/workshop/db/channel-event.repo'
+import { createTeamRepo } from '../server/services/workshop/db/team.repo'
+import { createTeamMemberRepo } from '../server/services/workshop/db/team-member.repo'
+import { createMessageRepo } from '../server/services/workshop/db/message.repo'
+import { createSubscriptionRepo } from '../server/services/workshop/db/subscription.repo'
+import { createAgentChannelManager } from '../server/services/workshop/runtime/manager'
+import type { AgentChannelManager } from '../server/services/workshop/runtime/manager'
+import { createAgentImpl } from '../server/services/workshop/agents/factory'
+
+let failures = 0
+
+function check(name: string, ok: boolean, detail = ''): void {
+  if (ok) {
+    console.log(`  PASS ${name}`)
+  }
+  else {
+    failures += 1
+    console.log(`  FAIL ${name}${detail ? ` — ${detail}` : ''}`)
+  }
+}
+
+function makeManager(db: DatabaseSync): AgentChannelManager {
+  return createAgentChannelManager({
+    repos: {
+      channels: createChannelRepo(db),
+      agents: createAgentRepo(db),
+      channelAgents: createChannelAgentRepo(db),
+      messages: createMessageRepo(db),
+      subscriptions: createSubscriptionRepo(db),
+      tasks: createTaskRepo(db),
+      memories: createMemoryRepo(db),
+
+      channelEvents: createChannelEventRepo(db),
+
+      teams: createTeamRepo(db),
+
+      teamMembers: createTeamMemberRepo(db),
+    },
+    implFactory: createAgentImpl,
+    db,
+  })
+}
+
+async function main(): Promise<void> {
+  console.log('━━━ Agent 模板多 Channel 复用(克隆独立身份)━━━')
+  const db = openWorkshopDb(':memory:')
+  const messagesRepo = createMessageRepo(db)
+  const manager = makeManager(db)
+  try {
+    // ---- 1. 同一模板克隆出独立身份 id ----
+    console.log('\n--- 1. 克隆独立身份 id ---')
+    const chA = await manager.createChannel({ name: 'A' })
+    const chB = await manager.createChannel({ name: 'B' })
+    const tpl = await manager.createAgent({ name: 'shared', harness: 'mock', config: { delayMs: 10 } })
+
+    const a1 = await manager.addAgentToChannel({ channelId: chA.channelId, agentId: tpl.id, role: 'lead' })
+    const b1 = await manager.addAgentToChannel({ channelId: chB.channelId, agentId: tpl.id, role: 'worker' })
+
+    check('两实例 id 互不相同', a1.id !== b1.id, `a1=${a1.id.slice(0, 8)} b1=${b1.id.slice(0, 8)}`)
+    check('实例 id 不同于模板 id', a1.id !== tpl.id && b1.id !== tpl.id)
+    check('实例复制模板 name', a1.name === 'shared' && b1.name === 'shared')
+    check('实例复制模板 harness', a1.harness === 'mock' && b1.harness === 'mock')
+
+    // ---- 2. role/token 按实例独立 ----
+    console.log('\n--- 2. role/token 按实例独立 ---')
+    check('role 按 channel 独立(A=lead)', (await manager.listChannelAgents(chA.channelId))[0]!.role === 'lead')
+    check('role 按 channel 独立(B=worker)', (await manager.listChannelAgents(chB.channelId))[0]!.role === 'worker')
+    check('实例 token 各不相同', a1.token !== b1.token)
+    check('findByToken(A) 解析到 channel A', manager.findByToken(a1.token!)?.channelId === chA.channelId)
+    check('findByToken(B) 解析到 channel B', manager.findByToken(b1.token!)?.channelId === chB.channelId)
+
+    // ---- 3. 模板详情含实例 ----
+    console.log('\n--- 3. 模板详情 ---')
+    const tplDetail = manager.getAgent(tpl.id)!
+    check('模板 instances=2', tplDetail.instances.length === 2, `n=${tplDetail.instances.length}`)
+    check('模板 instances 含两实例 id', tplDetail.instances.some(i => i.id === a1.id) && tplDetail.instances.some(i => i.id === b1.id))
+
+    // ---- 4. 独立 AgentRuntime(同一模板两实例各装配)----
+    console.log('\n--- 4. 独立 AgentRuntime ---')
+    const chC = await manager.createChannel({ name: 'C' })
+    const chD = await manager.createChannel({ name: 'D' })
+    const dup = await manager.createAgent({ name: 'dup', harness: 'mock', config: { delayMs: 10 } })
+    const c1 = await manager.addAgentToChannel({ channelId: chC.channelId, agentId: dup.id, role: 'lead' })
+    const d1 = await manager.addAgentToChannel({ channelId: chD.channelId, agentId: dup.id, role: 'lead' })
+
+    manager.ensureChannelActive(chC.channelId, { tickMs: 60_000 })
+    manager.ensureChannelActive(chD.channelId, { tickMs: 60_000 })
+    const wired = manager.runtimeStatus().wiredAgents
+    check('两 channel 各装配一个 runtime(共 2)', wired.length === 2, `n=${wired.length}`)
+    check('两个 runtime 属于不同实例 id', wired.length === 2 && wired.includes(c1.id) && wired.includes(d1.id))
+
+    await manager.unloadAgent(chC.channelId, c1.id)
+    check('卸载 C 实例不影响 D 实例', manager.runtimeStatus().wiredAgents.length === 1)
+
+    // ---- 5. mailbox channel 隔离 ----
+    console.log('\n--- 5. mailbox channel 隔离 ---')
+    // 溯源守卫(v8):消息必须携带可追溯发送人(本 channel 成员或人类 fromLabel)
+    await manager.sendImmediateMessage({ channelId: chA.channelId, toAgentId: a1.id, parts: [{ text: 'hi-A' }], fromLabel: 'e2e-test' })
+    const recentA = messagesRepo.listRecentByChannel(chA.channelId, 10)
+    const recentB = messagesRepo.listRecentByChannel(chB.channelId, 10)
+    check('消息只落在 channel A', recentA.length === 1 && recentA[0]!.toAgentId === a1.id, `n=${recentA.length}`)
+    check('channel B 无该消息', recentB.length === 0, `n=${recentB.length}`)
+
+    // ---- 6. 移除实例 ≠ 删除模板 ----
+    console.log('\n--- 6. 移除实例 vs 删除模板 ---')
+    await manager.removeAgentFromChannel(chB.channelId, b1.id)
+    check('移除 B 实例后模板仍存在', manager.getAgent(tpl.id) !== undefined)
+    check('A 实例保留', (await manager.listChannelAgents(chA.channelId)).some(a => a.id === a1.id))
+    check('B 实例已移除', (await manager.listChannelAgents(chB.channelId)).length === 0)
+    check('移除后模板 instances=1', manager.getAgent(tpl.id)?.instances.length === 1)
+
+    // ---- 7. 模板更新不传播(复制语义)----
+    console.log('\n--- 7. 模板更新不传播 ---')
+    await manager.updateAgent(tpl.id, { name: 'renamed' })
+    check('更新后已克隆实例名不变', manager.getChannelAgent(a1.id)?.name === 'shared')
+    const chE = await manager.createChannel({ name: 'E' })
+    const e1 = await manager.addAgentToChannel({ channelId: chE.channelId, agentId: tpl.id, role: 'worker' })
+    check('新克隆取新模板名', e1.name === 'renamed')
+
+    // ---- 8. 删除模板后实例保留 ----
+    console.log('\n--- 8. 删除模板后实例保留 ---')
+    await manager.removeAgent(tpl.id)
+    check('删除模板后 getAgent 为 undefined', manager.getAgent(tpl.id) === undefined)
+    check('A 实例仍存在', manager.getChannelAgent(a1.id) !== undefined)
+  }
+  finally {
+    await manager.shutdown()
+    db.close()
+  }
+
+  console.log(`\n${failures === 0 ? 'ALL PASS' : `${failures} FAILED`}`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((e) => {
+  console.error(e)
+  process.exit(1)
+})

package/scripts/test-agent-runtime.ts

@@ -0,0 +1,348 @@
+/**
+ * AgentRuntime 运行时核心测试(node + tsx 直跑,无浏览器)。
+ *
+ * 覆盖:
+ *  1. idle 自动消费
+ *  2. busy 时 enqueue 不打断(排队)
+ *  3. 结束后续消费积压
+ *  4. assign 消息触发 transition('WORKING')
+ *  5. 单条 run 抛错不阻塞下一条
+ *  6. abort 终止事件流
+ *  7. stop 优雅(等当前事件流结束)
+ *
+ * 注入 fake TaskEngine(与契约相同签名),真实引擎装配留到集成阶段。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import { openWorkshopDb } from '../server/services/workshop/db/database'
+import { createMessageRepo } from '../server/services/workshop/db/message.repo'
+import type { MessageRepo } from '../server/services/workshop/db/message.repo'
+import { Mailbox } from '../server/services/workshop/runtime/mailbox'
+import { AgentRuntime } from '../server/services/workshop/runtime/agent-runtime'
+import type { ChannelBus, TaskEngine } from '../server/services/workshop/runtime/agent-runtime'
+import type { A2AMessage, Part } from '../server/services/workshop/types/a2a'
+import type { AgentTaskQueueView, TaskState, WorkspaceTask } from '../server/services/workshop/types/task'
+import type {
+  AgentEvent,
+  AgentInfo,
+  AgentInterface,
+  AgentRunContext,
+  AgentRunRequest,
+  AgentWorkspace,
+} from '../server/services/workshop/agents/agent-interface'
+
+let failures = 0
+function check(name: string, ok: boolean, detail = ''): void {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? ` — ${detail}` : ''}`)
+  if (!ok) {
+    failures += 1
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise(r => setTimeout(r, ms))
+}
+
+async function waitUntil(cond: () => boolean, timeoutMs = 3000): Promise<void> {
+  const start = Date.now()
+  while (!cond()) {
+    if (Date.now() - start > timeoutMs) throw new Error('等待超时')
+    await sleep(5)
+  }
+}
+
+/** 落库一个 channel(messages.channel_id 外键依赖) */
+function seedChannel(db: DatabaseSync, id: string): void {
+  const now = new Date().toISOString()
+  db.prepare(
+    `INSERT INTO channels (id, name, description, lead_agent_id, enabled, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?)`,
+  ).run(id, id, '', null, 1, now, now)
+}
+
+function mkAgent(id: string, role: 'lead' | 'worker', channelId: string): AgentInfo {
+  return { id, channelId, name: id, harness: 'mock', role, config: {} }
+}
+
+function mkMessage(channelId: string, parts: Part[], metadata?: Record<string, unknown>): A2AMessage {
+  return { messageId: randomUUID(), contextId: channelId, role: 'ROLE_USER', parts, metadata }
+}
+
+function mkTask(channelId: string, assigneeId: string, title: string): WorkspaceTask {
+  return {
+    id: randomUUID(),
+    channelId,
+    assigneeId,
+    creatorId: '',
+    title,
+    state: 'SUBMITTED',
+    progress: 0,
+    retryCount: 0,
+    artifacts: [],
+    history: [],
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  }
+}
+
+/** fake TaskEngine:记录 transition/applyEvent,提供 get/create 等(与契约相同签名) */
+function makeFakeEngine() {
+  const transitions: { taskId: string, state: TaskState, by: string }[] = []
+  const applied: { taskId: string, event: AgentEvent }[] = []
+  const tasks = new Map<string, WorkspaceTask>()
+  const engine = {
+    create(input: {
+      channelId: string
+      creatorId: string
+      assigneeId: string
+      title: string
+      description?: string
+      parentId?: string
+      parts?: Part[]
+    }): WorkspaceTask {
+      const t = mkTask(input.channelId, input.assigneeId, input.title)
+      tasks.set(t.id, t)
+      return t
+    },
+    dispatch(): WorkspaceTask {
+      throw new Error('dispatch 未在测试中使用')
+    },
+    transition(taskId: string, state: TaskState, by: string): WorkspaceTask {
+      transitions.push({ taskId, state, by })
+      const t = tasks.get(taskId)
+      if (t) t.state = state
+      return t ?? mkTask('', '', '')
+    },
+    applyEvent(taskId: string, event: AgentEvent): void {
+      applied.push({ taskId, event })
+    },
+    list(): WorkspaceTask[] {
+      return [...tasks.values()]
+    },
+    get(taskId: string): WorkspaceTask | undefined {
+      return tasks.get(taskId)
+    },
+    complete(): WorkspaceTask {
+      throw new Error('complete 未在测试中使用')
+    },
+    reassign(): WorkspaceTask {
+      throw new Error('reassign 未在测试中使用')
+    },
+    cancel(): WorkspaceTask {
+      throw new Error('cancel 未在测试中使用')
+    },
+    onChildCompleted(): void {},
+    queueViewOf(channelId: string, agentId: string): AgentTaskQueueView {
+      const mine = [...tasks.values()].filter(t => t.channelId === channelId && t.assigneeId === agentId)
+      return {
+        agentId,
+        channelId,
+        queued: mine.filter(t => t.state === 'SUBMITTED' || t.state === 'ASSIGNED'),
+        current: mine.find(t => t.state === 'WORKING'),
+        completed: mine.filter(t => t.state === 'COMPLETED'),
+      }
+    },
+  }
+  return { engine: engine as TaskEngine, transitions, applied, tasks }
+}
+
+/** 可配置 fake impl:记录 run 调用,按注入的生成器产出事件流 */
+class FakeImpl implements AgentInterface {
+  calls: AgentRunRequest[] = []
+  constructor(
+    private behavior: (req: AgentRunRequest, ctx: AgentRunContext) => AsyncGenerator<AgentEvent, void, unknown>,
+  ) {}
+
+  run(req: AgentRunRequest, ctx: AgentRunContext): AsyncIterable<AgentEvent> {
+    this.calls.push(req)
+    return this.behavior(req, ctx)
+  }
+}
+
+interface Setup {
+  messages: MessageRepo
+  busEvents: { event: AgentEvent, source: A2AMessage }[]
+  bus: ChannelBus
+  engine: ReturnType<typeof makeFakeEngine>
+}
+
+function setup(): Setup {
+  const db = openWorkshopDb(':memory:')
+  seedChannel(db, 'ch1')
+  const messages = createMessageRepo(db)
+  const busEvents: { event: AgentEvent, source: A2AMessage }[] = []
+  const bus: ChannelBus = {
+    emit: (event, source) => busEvents.push({ event, source }),
+    onEvent: () => () => {},
+    notifyTask: () => {},
+    notifyAgent: () => {},
+    onAgentStatus: () => {},
+    onTaskEvent: () => {},
+    wakeScheduler: () => {},
+  }
+  return { messages, busEvents, bus, engine: makeFakeEngine() }
+}
+
+function makeRuntime(s: Setup, agent: AgentInfo, impl: AgentInterface): AgentRuntime {
+  const mailbox = new Mailbox(s.messages, agent.channelId, agent.id, () => {})
+  const workspace = {} as AgentWorkspace
+  return new AgentRuntime(agent, impl, { mailbox, taskEngine: s.engine.engine, bus: s.bus, workspace })
+}
+
+async function testAutoConsume(): Promise<void> {
+  console.log('\n--- 1. idle 自动消费 ---')
+  const s = setup()
+  const impl = new FakeImpl(async function* () {
+    yield { kind: 'status', status: { state: 'working', timestamp: new Date().toISOString() } }
+    yield { kind: 'done' }
+  })
+  const rt = makeRuntime(s, mkAgent('a1', 'worker', 'ch1'), impl)
+  rt.start()
+  const msg = mkMessage('ch1', [])
+  rt.enqueue(msg)
+  await waitUntil(() => impl.calls.length === 1)
+  await waitUntil(() => rt.getState() === 'idle')
+  check('enqueue 后自动消费:run 被调用', impl.calls.length === 1)
+  check('自动消费:事件逐条广播', s.busEvents.length === 2, `收到 ${s.busEvents.length} 个事件`)
+  check('自动消费:消息标记已消费', s.messages.listPendingByChannelAgent('ch1', 'a1').length === 0)
+  await rt.stop()
+}
+
+async function testBusyQueue(): Promise<void> {
+  console.log('\n--- 2/3. busy 不打断 + 积压消费 ---')
+  const s = setup()
+  let release!: () => void
+  const hold = new Promise<void>((r) => {
+    release = r
+  })
+  const impl = new FakeImpl(async function* () {
+    yield { kind: 'status', status: { state: 'started', timestamp: new Date().toISOString() } }
+    await hold
+    yield { kind: 'done' }
+  })
+  const rt = makeRuntime(s, mkAgent('a1', 'worker', 'ch1'), impl)
+  rt.start()
+  const msgA = mkMessage('ch1', [])
+  const msgB = mkMessage('ch1', [])
+  rt.enqueue(msgA)
+  await waitUntil(() => impl.calls.length === 1)
+  check('busy 时不打断:state=busy', rt.getState() === 'busy')
+  rt.enqueue(msgB)
+  await sleep(30)
+  check('busy 时不打断:B 排队未处理', impl.calls.length === 1)
+  release()
+  await waitUntil(() => impl.calls.length === 2)
+  await waitUntil(() => rt.getState() === 'idle')
+  check('结束后续消费积压:B 被消费', impl.calls.length === 2)
+  check('积压消费:两条消息均已消费', s.messages.listPendingByChannelAgent('ch1', 'a1').length === 0)
+  await rt.stop()
+}
+
+async function testAssignTransition(): Promise<void> {
+  console.log('\n--- 4. assign 消息触发 transition WORKING ---')
+  const s = setup()
+  const impl = new FakeImpl(async function* () {
+    yield { kind: 'done' }
+  })
+  const rt = makeRuntime(s, mkAgent('a1', 'worker', 'ch1'), impl)
+  rt.start()
+  const task = mkTask('ch1', 'a1', '任务A')
+  s.engine.tasks.set(task.id, task)
+  const msg = mkMessage('ch1', [], { 'x-aw-task-kind': 'assign', 'x-aw-task-id': task.id })
+  msg.taskId = task.id
+  rt.enqueue(msg)
+  await waitUntil(() => impl.calls.length === 1)
+  await waitUntil(() => rt.getState() === 'idle')
+  check(
+    'assign 消息触发 transition("WORKING", agentId)',
+    s.engine.transitions.some(t => t.taskId === task.id && t.state === 'WORKING' && t.by === 'a1'),
+  )
+  await rt.stop()
+}
+
+async function testErrorDoesNotBlock(): Promise<void> {
+  console.log('\n--- 5. 单条 run 抛错不阻塞下一条 ---')
+  const s = setup()
+  let callCount = 0
+  const impl = new FakeImpl(async function* () {
+    callCount += 1
+    if (callCount === 1) {
+      yield { kind: 'status', status: { state: 'boom', timestamp: new Date().toISOString() } }
+      throw new Error('boom')
+    }
+    yield { kind: 'done' }
+  })
+  const rt = makeRuntime(s, mkAgent('a1', 'worker', 'ch1'), impl)
+  rt.start()
+  rt.enqueue(mkMessage('ch1', []))
+  rt.enqueue(mkMessage('ch1', []))
+  await waitUntil(() => impl.calls.length >= 3 && rt.getState() === 'idle')
+  check('单条抛错重投重试:失败消息重试成功且不阻塞下一条', impl.calls.length === 3)
+  check('重试后消息仍标记消费', s.messages.listPendingByChannelAgent('ch1', 'a1').length === 0)
+  await rt.stop()
+}
+
+async function testAbort(): Promise<void> {
+  console.log('\n--- 6. abort 终止事件流 ---')
+  const s = setup()
+  let events = 0
+  const impl = new FakeImpl(async function* (_req, ctx) {
+    for (let i = 0; i < 300; i++) {
+      if (ctx.signal.aborted) break
+      events += 1
+      yield { kind: 'status', status: { state: `step${i}`, timestamp: new Date().toISOString() } }
+      await sleep(2)
+    }
+    yield { kind: 'done' }
+  })
+  const rt = makeRuntime(s, mkAgent('a1', 'worker', 'ch1'), impl)
+  rt.start()
+  rt.enqueue(mkMessage('ch1', []))
+  await waitUntil(() => events >= 3)
+  rt.abortCurrent()
+  await waitUntil(() => rt.getState() === 'idle')
+  check('abort 后事件流终止', events < 300, `终止于第 ${events} 个事件`)
+  await rt.stop()
+}
+
+async function testStop(): Promise<void> {
+  console.log('\n--- 7. stop 优雅 ---')
+  const s = setup()
+  let release!: () => void
+  const hold = new Promise<void>((r) => {
+    release = r
+  })
+  const impl = new FakeImpl(async function* () {
+    yield { kind: 'status', status: { state: 'working', timestamp: new Date().toISOString() } }
+    await hold
+    yield { kind: 'done' }
+  })
+  const rt = makeRuntime(s, mkAgent('a1', 'worker', 'ch1'), impl)
+  rt.start()
+  rt.enqueue(mkMessage('ch1', []))
+  await waitUntil(() => impl.calls.length === 1)
+  let stopResolved = false
+  const _stopPromise = rt.stop().then(() => {
+    stopResolved = true
+  })
+  await sleep(30)
+  check('stop 等当前事件流结束(未提前返回)', !stopResolved)
+  release()
+  await waitUntil(() => stopResolved)
+  check('stop 优雅:state=stopped', rt.getState() === 'stopped')
+}
+
+async function main(): Promise<void> {
+  await testAutoConsume()
+  await testBusyQueue()
+  await testAssignTransition()
+  await testErrorDoesNotBlock()
+  await testAbort()
+  await testStop()
+  console.log(`\n${failures === 0 ? 'ALL PASS' : `${failures} FAILURE(S)`}`)
+  process.exit(failures === 0 ? 0 : 1)
+}
+
+main().catch((e) => {
+  console.error('测试异常:', e)
+  process.exit(1)
+})

package/scripts/test-api-client.ts

@@ -0,0 +1,108 @@
+/** apiClient 单测:信封解析 / ApiError 归一化 / GET 重试 / POST 不重试 / 网络错误映射 */
+import { apiFetch, ApiError } from '../app/composables/workshop/apiClient'
+
+interface StubStep { status?: number, body?: unknown, network?: boolean }
+let failed = 0
+const okIf = (m: string, c: boolean) => {
+  if (c) console.log(`PASS ${m}`)
+  else {
+    console.log(`FAIL ${m}`)
+    failed++
+  }
+}
+
+/** fetch 桩:按脚本逐次返回;记录调用次数 */
+function stubFetch(script: StubStep[]): { calls: () => number } {
+  let calls = 0
+  const g = globalThis as { fetch?: unknown }
+  // 全局桩:type 与原生 fetch 不完全兼容,单测内可控
+  g.fetch = async () => {
+    const step = script[Math.min(calls, script.length - 1)]!
+    calls++
+    if (step.network) throw new TypeError('Failed to fetch')
+    const status = step.status ?? 200
+    const body = step.body ?? (status >= 400 ? { code: 'HTTP', message: `http ${status}` } : { code: 0, message: 'ok', data: { v: calls } })
+    return { ok: status >= 200 && status < 300, status, json: async () => body } as Response
+  }
+  return { calls: () => calls }
+}
+
+/** 捕获 apiFetch 抛出的 ApiError */
+async function capture(p: Promise<unknown>): Promise<ApiError | null> {
+  try {
+    await p
+    return null
+  }
+  catch (e) {
+    return e instanceof ApiError ? e : null
+  }
+}
+
+const restore = (orig: unknown) => {
+  (globalThis as { fetch?: unknown }).fetch = orig
+}
+const origFetch = globalThis.fetch
+
+// ── 1. 成功信封 ──
+{
+  const s = stubFetch([{ body: { code: 0, message: 'ok', data: { v: 7 } } }])
+  const d = await apiFetch<{ v: number }>({ base: '/api/x', retries: 2 })
+  okIf(`成功信封解包: data.v=${d.v}`, d.v === 7 && s.calls() === 1)
+}
+
+// ── 2. 业务错误(code!==0)→ ApiError 保留 code/message,不重试 ──
+{
+  const s = stubFetch([{ status: 400, body: { code: 'VALIDATION_ERROR', message: '模板必填', data: null } }])
+  const err = await capture(apiFetch({ base: '/api/x', retries: 2, init: { method: 'POST', body: '{}' } }))
+  okIf(`业务错误归一化: ${err?.code}/${err?.message}`, err instanceof ApiError && err.code === 'VALIDATION_ERROR' && err.status === 400 && s.calls() === 1)
+}
+
+// ── 3. 非 2xx 无信封 → HTTP_xxx 兜底 ──
+{
+  const s = stubFetch([{ status: 502, body: 'Bad Gateway(html)' }])
+  const err = await capture(apiFetch({ base: '/api/x' }))
+  okIf(`非 JSON 非 2xx: ${err?.code}/${err?.message}`, err instanceof ApiError && err.code === 'HTTP_502' && s.calls() === 1)
+}
+
+// ── 4. 网络错误 → NETWORK ──
+{
+  const s = stubFetch([{ network: true }])
+  const err = await capture(apiFetch({ base: '/api/x' }))
+  okIf(`网络错误映射: ${err?.code}/${err?.message}`, err instanceof ApiError && err.code === 'NETWORK')
+  okIf(`网络错误不重试(默认 retries=0): 调用 ${s.calls()} 次`, s.calls() === 1)
+}
+
+// ── 5. GET 5xx 自动重试:失败一次后成功 ──
+{
+  const s = stubFetch([
+    { status: 500, body: { code: 'INTERNAL_ERROR', message: '服务器内部错误', data: null } },
+    { body: { code: 0, message: 'ok', data: { v: 1 } } },
+  ])
+  const d = await apiFetch<{ v: number }>({ base: '/api/x', retries: 2 })
+  okIf(`GET 重试成功: data.v=${d.v}, 调用 ${s.calls()} 次(重试 1 次)`, d.v === 1 && s.calls() === 2)
+}
+
+// ── 6. GET 重试耗尽:retries=2 → 共 3 次调用后抛错 ──
+{
+  const s = stubFetch([{ status: 500, body: { code: 'INTERNAL_ERROR', message: 'boom', data: null } }])
+  const err = await capture(apiFetch({ base: '/api/x', retries: 2 }))
+  okIf(`GET 重试耗尽: 调用 ${s.calls()} 次, code=${err?.code}`, s.calls() === 3 && err instanceof ApiError)
+}
+
+// ── 7. POST 永不重试(即使 retries 传了) ──
+{
+  const s = stubFetch([{ status: 500, body: { code: 'INTERNAL_ERROR', message: 'boom', data: null } }])
+  const err = await capture(apiFetch({ base: '/api/x', retries: 2, init: { method: 'POST', body: '{}' } }))
+  okIf(`POST 不重试: 调用 ${s.calls()} 次`, s.calls() === 1 && err instanceof ApiError)
+}
+
+// ── 8. 4xx 不重试(非 5xx) ──
+{
+  const s = stubFetch([{ status: 404, body: { code: 'NOT_FOUND', message: '接口不存在', data: null } }])
+  const err = await capture(apiFetch({ base: '/api/x', retries: 2 }))
+  okIf(`4xx 不重试: 调用 ${s.calls()} 次, code=${err?.code}`, s.calls() === 1 && err?.code === 'NOT_FOUND')
+}
+
+restore(origFetch)
+console.log(failed ? `API-CLIENT TEST FAILED(${failed})` : 'API-CLIENT TEST ALL PASS')
+process.exit(failed ? 1 : 0)