agentworkshop 0.7.41 → 0.7.46

package/scripts/test-group-chat-hardening.ts

@@ -0,0 +1,265 @@
+/**
+ * 群聊层"加固"回归测试(本轮 review 修复项).
+ *
+ * 覆盖的是**行为契约**,不是实现细节 —— 每条都对应一个真实缺陷:
+ *  1. `withTransaction` 可重入:SQLite 不支持嵌套 BEGIN(实测会抛
+ *     `cannot start a transaction within a transaction` 且**外层仍开着**),
+ *     而群聊写入路径会互相调用。这里断言嵌套不抛、内层回滚不伤外层、外层回滚全丢。
+ *  2. `isTransactionOpen()` 在事务内外正确翻转 —— WS 落库缓冲靠它决定是否推迟刷盘
+ *     (同连接的非事务写入会被并入事务,回滚会连带丢弃已推给 peer 的帧)。
+ *  3. `listBefore` 遇失效/跨频道游标返回**空页**(旧实现回落最新页 → 客户端"加载更早"死循环)。
+ *  4. `listAfterCursor` 游标行被删时不得返回重复行(旧实现把 rowid 退化为 0 → 同毫秒行全返)。
+ *  5. 撤权只清理**该 Channel** 的通知,不波及其它频道(§13.7)。
+ *  6. outbox `markPublishedIfPending` 幂等;`sweepPublished` 只回收已发布行。
+ *  7. 通知保留期只回收**已读**行(未读永不删)。
+ *  8. 成员投影与快照投影同源(displayName 回落 id 前缀),不再"列表与快照显示不同"。
+ *
+ * 运行: npx tsx --tsconfig .nuxt/tsconfig.server.json scripts/test-group-chat-hardening.ts
+ */
+import type { DatabaseSync } from 'node:sqlite'
+import { mkdtempSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+// 隔离:用户仓储惰性 getDb() 会走 AW_DATA_DIR;指向临时目录,绝不触碰真实数据
+process.env.AW_DATA_DIR = mkdtempSync(join(tmpdir(), 'aw-chat-hardening-'))
+process.env.AGENTWORKSHOP_TEST = '1'
+
+const { openWorkshopDb } = await import('../server/services/workshop/db/database')
+const { withTransaction, isTransactionOpen, transactionDepth } = await import('../server/services/workshop/db/transaction')
+const { createChannelRepo } = await import('../server/services/workshop/db/channel.repo')
+const { createChannelMemberRepo } = await import('../server/services/workshop/db/channel-member.repo')
+const { createChatMessageRepo } = await import('../server/services/workshop/db/chat-message.repo')
+const { createNotificationRepo } = await import('../server/services/workshop/db/notification.repo')
+const { createOutboxRepo } = await import('../server/services/workshop/db/outbox.repo')
+const { projectChannelMember } = await import('../server/services/workshop/runtime/chat-projection')
+
+let passed = 0
+const failures: string[] = []
+function check(name: string, ok: boolean, detail = ''): void {
+  if (ok) {
+    passed++
+    console.log(`  PASS  ${name}${detail ? ` — ${detail}` : ''}`)
+  }
+  else {
+    failures.push(name)
+    console.log(`  FAIL  ${name}${detail ? ` — ${detail}` : ''}`)
+  }
+}
+function section(title: string): void {
+  console.log(`\n=== ${title} ===`)
+}
+
+const db: DatabaseSync = openWorkshopDb(':memory:')
+const channels = createChannelRepo(db)
+const members = createChannelMemberRepo(db)
+const chat = createChatMessageRepo(db)
+const notifications = createNotificationRepo(db)
+const outbox = createOutboxRepo(db)
+
+/** 建一个 channel(直接落库,不经 manager —— 本测试只关心 db/仓储层契约) */
+function makeChannel(name: string): string {
+  const row = channels.create({ name, ownerUserId: 'u-owner' })
+  members.ensureOwner(row.id, 'u-owner')
+  return row.id
+}
+
+// ============================================================================
+section('1. 事务可重入(SQLite 不支持嵌套 BEGIN)')
+// ============================================================================
+{
+  const chId = makeChannel('tx')
+  check('事务外 isTransactionOpen()=false', isTransactionOpen() === false)
+
+  // 嵌套事务不得抛错;内层写入与外层写入在同一最外层事务里
+  let innerOpened = false
+  let outerDepthSeen = 0
+  withTransaction(db, () => {
+    outerDepthSeen = transactionDepth()
+    chat.create({ channelId: chId, senderType: 'user', senderId: 'u1', text: 'outer', clientMessageId: 'tx-outer' })
+    withTransaction(db, () => {
+      innerOpened = isTransactionOpen()
+      chat.create({ channelId: chId, senderType: 'user', senderId: 'u1', text: 'inner', clientMessageId: 'tx-inner' })
+    })
+  })
+  check('嵌套事务不抛错(SQLite 嵌套 BEGIN 会抛)', outerDepthSeen >= 1, `outerDepth=${outerDepthSeen}`)
+  check('内层 isTransactionOpen()=true(WS 刷盘守卫据此推迟)', innerOpened === true)
+  check('提交后 isTransactionOpen()=false', isTransactionOpen() === false)
+  check('嵌套提交后两条写入都可见', chat.count(chId) === 2, `count=${chat.count(chId)}`)
+
+  // 内层抛错:只回滚内层(外层可选择继续并提交)
+  let innerThrew = false
+  withTransaction(db, () => {
+    chat.create({ channelId: chId, senderType: 'user', senderId: 'u1', text: 'keep-me', clientMessageId: 'tx-keep' })
+    try {
+      withTransaction(db, () => {
+        chat.create({ channelId: chId, senderType: 'user', senderId: 'u1', text: 'rollback-me', clientMessageId: 'tx-rb' })
+        throw new Error('inner-boom')
+      })
+    }
+    catch {
+      innerThrew = true
+    }
+  })
+  check('内层抛错被捕获且外层仍提交', innerThrew && chat.count(chId) === 3, `count=${chat.count(chId)}`)
+  check('内层回滚只丢弃内层写入(rollback-me 不存在)', chat.findByClientId(chId, 'tx-rb') === undefined)
+  check('内层回滚不影响外层已写行(keep-me 存在)', chat.findByClientId(chId, 'tx-keep') !== undefined)
+
+  // 外层抛错:整体回滚(含已成功的内层)
+  let outerThrew = false
+  const before = chat.count(chId)
+  try {
+    withTransaction(db, () => {
+      chat.create({ channelId: chId, senderType: 'user', senderId: 'u1', text: 'a', clientMessageId: 'tx-o1' })
+      withTransaction(db, () => {
+        chat.create({ channelId: chId, senderType: 'user', senderId: 'u1', text: 'b', clientMessageId: 'tx-o2' })
+      })
+      throw new Error('outer-boom')
+    })
+  }
+  catch {
+    outerThrew = true
+  }
+  check('外层抛错 → 全部回滚(含已提交的内层写入)', outerThrew && chat.count(chId) === before, `before=${before} after=${chat.count(chId)}`)
+  check('回滚后事务深度归零(不留悬挂事务)', transactionDepth() === 0)
+  check('回滚后 isTransactionOpen()=false', isTransactionOpen() === false)
+}
+
+// ============================================================================
+section('2. 游标正确性:失效游标不得回落到最新页')
+// ============================================================================
+{
+  const chId = makeChannel('cursor')
+  const other = makeChannel('cursor-other')
+  const ids: string[] = []
+  for (let i = 0; i < 5; i++) {
+    ids.push(chat.create({ channelId: chId, senderType: 'user', senderId: 'u1', text: `m${i}`, clientMessageId: `c${i}` }).row.id)
+  }
+  check('无游标 → 最新页(新→旧)', chat.listBefore(chId, undefined, 3)[0]!.text === 'm4')
+
+  const anchorIdx = ids[2]!
+  const before = chat.listBefore(chId, anchorIdx, 10)
+  check('有效游标 → 严格取更早的 2 条', before.length === 2 && before.every(m => ['m0', 'm1'].includes(m.text)), before.map(m => m.text).join(','))
+
+  // 旧实现:anchor 不存在时 return selectRecent(...) → 客户端"加载更早"永远拿到最新页(死循环)
+  const ghost = chat.listBefore(chId, 'no-such-message-id', 10)
+  check('失效游标 → 空页(旧实现会回落最新页,导致分页死循环)', ghost.length === 0, `len=${ghost.length}`)
+
+  // 跨频道游标同样必须空页(否则能把别的群的消息当锚点,泄漏其 createdAt 位置)
+  const foreign = chat.create({ channelId: other, senderType: 'user', senderId: 'u1', text: 'x', clientMessageId: 'cx' }).row.id
+  const cross = chat.listBefore(chId, foreign, 10)
+  check('跨频道游标 → 空页', cross.length === 0, `len=${cross.length}`)
+}
+
+// ============================================================================
+section('3. 通知游标:锚点被删不得返回重复行')
+// ============================================================================
+{
+  const me = 'user-cursor'
+  // 三条同 created_at 的通知(模拟同毫秒批量写入)
+  const stamp = '2026-01-01T00:00:00.000Z'
+  const n1 = notifications.create({ recipientUserId: me, type: 'mention', eventId: 'e1', createdAt: stamp }).row
+  notifications.create({ recipientUserId: me, type: 'mention', eventId: 'e2', createdAt: stamp })
+  notifications.create({ recipientUserId: me, type: 'mention', eventId: 'e3', createdAt: stamp })
+
+  const afterFirst = notifications.listAfterCursor(me, { createdAt: n1.createdAt, id: n1.id }, 50)
+  check('锚点存在 → 用 (created_at,rowid) 严格取其后(不含同刻更早行)', afterFirst.length === 2, `len=${afterFirst.length}`)
+
+  // 旧实现:rowidOf 缺失 → rid=0 → 返回所有 created_at 等于锚点时刻的行(重复投递)
+  const ghost = notifications.listAfterCursor(me, { createdAt: stamp, id: 'deleted-anchor' }, 50)
+  check('锚点被删 → 严格 > createdAt(不重复返回同刻行)', ghost.length === 0, `len=${ghost.length}`)
+
+  const cursor = notifications.cursorOf(n1.id)
+  check('cursorOf 返回可用游标', cursor?.id === n1.id && cursor.createdAt === stamp)
+  check('cursorOf 对不存在的 id 返回 null', notifications.cursorOf('nope') === null)
+}
+
+// ============================================================================
+section('4. 撤权只清本频道通知(§13.7)')
+// ============================================================================
+{
+  const a = makeChannel('revoke-a')
+  const b = makeChannel('revoke-b')
+  const target = 'user-target'
+  notifications.create({ recipientUserId: target, channelId: a, type: 'mention', eventId: 'ra' })
+  notifications.create({ recipientUserId: target, channelId: b, type: 'mention', eventId: 'rb' })
+  notifications.create({ recipientUserId: 'user-other', channelId: a, type: 'mention', eventId: 'ro' })
+
+  const purged = notifications.deleteForChannel(target, a)
+  check('撤权清理返回删除行数', purged === 1, `purged=${purged}`)
+  check('本频道通知已删(不再补拉)', notifications.listRecent(target, 10).every(n => n.channelId !== a))
+  check('其它频道通知保留(不误删)', notifications.listRecent(target, 10).some(n => n.channelId === b))
+  check('其它用户在同频道的通知不受影响', notifications.listRecent('user-other', 10).some(n => n.channelId === a))
+}
+
+// ============================================================================
+section('5. outbox:幂等发布 + 有界化')
+// ============================================================================
+{
+  const evId = 'chat.message:test-1'
+  outbox.enqueue({ aggregateType: 'chat_message', aggregateId: 'test-1', eventType: 'chat.message', eventId: evId })
+  check('enqueue 后为 pending', outbox.findById(evId)?.status === 'pending')
+
+  const first = outbox.markPublishedIfPending(evId)
+  const second = outbox.markPublishedIfPending(evId)
+  check('首次条件发布返回 true', first === true)
+  check('重复条件发布返回 false(幂等,attempts 不重复增长)', second === false)
+  check('attempts 只 +1', outbox.findById(evId)?.attempts === 1, `attempts=${outbox.findById(evId)?.attempts}`)
+
+  // failed 行不得被"发布成功"覆盖(失败留痕不能被抹掉)
+  const failedId = 'chat.delivery.status:test-f'
+  outbox.enqueue({ aggregateType: 'chat_delivery', aggregateId: 'test-f', eventType: 'chat.delivery.status', eventId: failedId })
+  outbox.markFailed(failedId, 'boom')
+  check('条件发布不改动 failed 行', outbox.markPublishedIfPending(failedId) === false && outbox.findById(failedId)?.status === 'failed')
+
+  // 保留期只回收已发布行
+  const pendingId = 'chat.message:test-pending'
+  outbox.enqueue({ aggregateType: 'chat_message', aggregateId: 'test-pending', eventType: 'chat.message', eventId: pendingId })
+  const removed = outbox.sweepPublished(new Date(Date.now() + 60_000).toISOString())
+  check('保留期回收已发布行', removed >= 1, `removed=${removed}`)
+  check('pending 行不被回收(欠账必须保留)', outbox.findById(pendingId)?.status === 'pending')
+  check('failed 行不被回收(失败留痕)', outbox.findById(failedId)?.status === 'failed')
+}
+
+// ============================================================================
+section('6. 通知保留期:只回收已读')
+// ============================================================================
+{
+  const me = 'user-sweep'
+  const old = '2020-01-01T00:00:00.000Z'
+  const readRow = notifications.create({ recipientUserId: me, type: 'mention', eventId: 'sw-read', createdAt: old }).row
+  notifications.create({ recipientUserId: me, type: 'mention', eventId: 'sw-unread', createdAt: old })
+  notifications.markRead(me, readRow.id)
+
+  const removed = notifications.sweepRead(new Date(Date.now() - 86_400_000).toISOString())
+  check('已读旧行被回收', removed === 1, `removed=${removed}`)
+  check('未读行**永不**回收(删掉就是丢通知)', notifications.listRecent(me, 10).some(n => n.eventId === 'sw-unread'))
+  check('未读数仍为 1', notifications.unreadCount(me) === 1, `unread=${notifications.unreadCount(me)}`)
+}
+
+// ============================================================================
+section('7. 成员投影两处同源(displayName 回落一致)')
+// ============================================================================
+{
+  const chId = makeChannel('proj')
+  members.upsert({ channelId: chId, userId: 'user-without-name', role: 'member', status: 'active' })
+  const row = members.listByChannel(chId).find(m => m.userId === 'user-without-name')!
+
+  // 用户仓储不可用时 resolveOwnerName 返回 null;投影必须回落到 id 前 8 位(而不是露出 null)
+  const projected = projectChannelMember(row, null)
+  check('projectChannelMember(null) 保留 null(投影层不做兜底,由调用方给值)', projected.displayName === null)
+  const withFallback = projectChannelMember(row, 'user-wit')
+  check('projectChannelMember 原样透传调用方给的展示名', withFallback.displayName === 'user-wit')
+  check('成员行字段完整(role/status/joinedAt)', !!row.role && !!row.status && !!row.joinedAt)
+}
+
+// ============================================================================
+console.log(`\n${'='.repeat(64)}`)
+console.log(`群聊加固回归: PASS=${passed}  FAIL=${failures.length}`)
+if (failures.length > 0) {
+  console.log('失败项:')
+  for (const f of failures) console.log(`  - ${f}`)
+}
+console.log('='.repeat(64))
+db.close()
+process.exit(failures.length > 0 ? 1 : 0)

package/scripts/test-group-chat-unit/lib.ts

@@ -0,0 +1,186 @@
+/**
+ * 群聊/权限/HITL 单测共享库:断言框架 + 场景搭建辅助。
+ *
+ * 由 scripts/test-group-chat-unit.ts 拆分而来(原文第 20–168 行),语句逐行原文搬运,仅做机械改写:
+ *  - 断言框架 / ChatReplyRow / makeManager / 场景搭建原样保留;`passed` / `failures` 两个模块级自由变量
+ *    改为导出的 `assertion` 对象(计数语义、调用顺序完全不变);
+ *  - 场景搭建的顶层顺序代码包成 createGroupChatTestContext() 工厂,共享状态经 ctx 显式传递;
+ *  - server 模块 import 顺序与拆分前逐条一致,且刻意保持 dynamic import ——
+ *    它们必须在入口设置 AW_DATA_DIR / AGENTWORKSHOP_TEST 之后才求值。
+ */
+import type { DatabaseSync } from 'node:sqlite'
+
+const { openWorkshopDb, initWorkshopDb } = await import('../../server/services/workshop/db/database')
+const { createChannelRepo } = await import('../../server/services/workshop/db/channel.repo')
+const { createAgentRepo } = await import('../../server/services/workshop/db/agent.repo')
+const { createChannelAgentRepo } = await import('../../server/services/workshop/db/channel-agent.repo')
+const { createTaskRepo } = await import('../../server/services/workshop/db/task.repo')
+const { createMemoryRepo } = await import('../../server/services/workshop/db/memory.repo')
+const { createChannelEventRepo } = await import('../../server/services/workshop/db/channel-event.repo')
+const { createTeamRepo } = await import('../../server/services/workshop/db/team.repo')
+const { createTeamMemberRepo } = await import('../../server/services/workshop/db/team-member.repo')
+const { createMessageRepo } = await import('../../server/services/workshop/db/message.repo')
+const { createSubscriptionRepo } = await import('../../server/services/workshop/db/subscription.repo')
+const managerMod = await import('../../server/services/workshop/runtime/manager')
+const createAgentChannelManager = managerMod.createAgentChannelManager
+export type AgentChannelManager = InstanceType<typeof managerMod.AgentChannelManager>
+const { createAgentImpl } = await import('../../server/services/workshop/agents/factory')
+const { resolveMentions, extractMentionTokens } = await import('../../server/services/workshop/runtime/chat-mention')
+const { projectManagementSnapshotForMember } = await import('../../server/services/workshop/runtime/chat-projection')
+const { checkToolAgainstScope, MANAGEMENT_TOOL_NAMES } = await import('../../server/services/workshop/runtime/permission-scope')
+const {
+  WORKSHOP_PERMISSION_SCOPE_HEADER,
+  parseWorkshopPermissionScope,
+  intersectWorkshopPermissionScope,
+} = await import('../../shared/workshop-protocol')
+const { userRepository } = await import('../../server/repositories/user.repository')
+
+// ===== 断言框架(与仓库既有 scripts/test-*.ts 同风格) =====
+/** 断言累计状态:拆分前为模块级 `let passed` / `const failures`(语义等价,main.ts 读同一对象汇总) */
+export const assertion: { passed: number, failures: string[] } = { passed: 0, failures: [] }
+export function check(name: string, ok: boolean, detail = ''): void {
+  if (ok) {
+    assertion.passed++
+    console.log(`  PASS  ${name}${detail ? ` — ${detail}` : ''}`)
+  }
+  else {
+    assertion.failures.push(name)
+    console.log(`  FAIL  ${name}${detail ? ` — ${detail}` : ''}`)
+  }
+}
+export function section(title: string): void {
+  console.log(`\n=== ${title} ===`)
+}
+/** 断言抛出 AppError 且 code 匹配 */
+export function checkThrows(name: string, fn: () => unknown, code: string): void {
+  try {
+    fn()
+    check(name, false, '未抛出异常')
+  }
+  catch (err) {
+    const e = err as { code?: string, statusCode?: number, message?: string }
+    check(name, e.code === code, `实际 code=${e.code ?? '(none)'} status=${e.statusCode ?? '?'} msg=${e.message ?? ''}`)
+  }
+}
+/**
+ * async 版本:await 型接口拒绝的是 Promise,**不会**同步抛出 ——
+ * 用 checkThrows 调 async 方法会永远得到"未抛出异常"(实测踩过,断言假通过)。
+ */
+export async function checkRejects(name: string, fn: () => Promise<unknown>, code: string): Promise<void> {
+  try {
+    await fn()
+    check(name, false, '未抛出异常(期望拒绝)')
+  }
+  catch (err) {
+    const e = err as { code?: string, statusCode?: number, message?: string }
+    check(name, e.code === code, `实际 code=${e.code ?? '(none)'} status=${e.statusCode ?? '?'} msg=${e.message ?? ''}`)
+  }
+}
+
+/** 群聊事实表里 Agent 回复行的证据字段(§12 关联 ID 对照) */
+export interface ChatReplyRow {
+  id: string
+  sourceChatMessageId: string | null
+  requesterUserId: string | null
+  mentionsJson: string
+}
+
+export function makeManager(db: DatabaseSync): AgentChannelManager {
+  return createAgentChannelManager({
+    repos: {
+      users: undefined as never,
+      channelEvents: createChannelEventRepo(db),
+      channels: createChannelRepo(db),
+      agents: createAgentRepo(db),
+      teams: createTeamRepo(db),
+      teamMembers: createTeamMemberRepo(db),
+      channelAgents: createChannelAgentRepo(db),
+      messages: createMessageRepo(db),
+      subscriptions: createSubscriptionRepo(db),
+      tasks: createTaskRepo(db),
+      memories: createMemoryRepo(db),
+      schedules: undefined as never,
+    },
+    implFactory: createAgentImpl,
+    db,
+  })
+}
+
+/** 场景搭建后的共享状态类型(拆分前为模块级 ADMIN/A/B/C/D、db、manager、buildChannel) */
+export interface GroupChatTestUser {
+  id: string
+  name: string
+  role: string
+}
+
+export interface GroupChatTestContext {
+  db: DatabaseSync
+  manager: AgentChannelManager
+  ADMIN: GroupChatTestUser
+  A: GroupChatTestUser
+  B: GroupChatTestUser
+  C: GroupChatTestUser
+  D: GroupChatTestUser
+  mkUser: (name: string) => GroupChatTestUser
+  buildChannel: (name: string) => Promise<{ channelId: string, leadId: string, workerId: string }>
+}
+
+// ===== 场景搭建:owner=A / 成员=B、C / 非成员=D =====
+// 用户注册到**全局用户系统**(与线上同源):这样 resolveOwnerName 能解析展示名,
+// mention 的"展示名解析"路径才被真实覆盖,而不是退化成 id 前缀兜底。
+// 注意:不能 import user.service(它经 #imports 依赖 nitro 运行时),直接用仓储。
+export function createGroupChatTestContext(): GroupChatTestContext {
+  const registered: Array<{ id: string, name: string, role: string }> = []
+  function mkUser(name: string): { id: string, name: string, role: string } {
+    const { user } = userRepository.createWithRoleBootstrap({
+      name,
+      email: `${name}@chat-test.local`,
+      password: 'Passw0rd!123',
+      role: 'user',
+      status: 'active',
+    })
+    const u = { id: user.id, name: user.name, role: user.role }
+    registered.push(u)
+    return u
+  }
+  // 首个注册账号会被 bootstrap 为 admin(线上同规则)→ 先建 admin,再建业务用户
+  const ADMIN = mkUser('root-admin')
+  const A = mkUser('alice')
+  const B = mkUser('bob')
+  const C = mkUser('carol')
+  const D = mkUser('dave')
+
+  const db = openWorkshopDb(':memory:')
+  const manager = makeManager(db)
+
+  /** 建一个 owner=A 的 channel(mock lead + 1 worker) */
+  async function buildChannel(name: string): Promise<{ channelId: string, leadId: string, workerId: string }> {
+    const leadTpl = await manager.createAgent({ name: `${name}-lead`, harness: 'mock', config: { delayMs: 5 } })
+    const workerTpl = await manager.createAgent({ name: `${name}-worker`, harness: 'mock', config: { delayMs: 5 } })
+    const { channelId, leadAgentId } = await manager.createChannel({
+      name,
+      description: '群聊单测',
+      ownerUserId: A.id,
+      leadAgent: { name: `${name}-lead`, harness: 'mock', config: { delayMs: 5 } },
+    })
+    void leadTpl
+    await manager.addAgentToChannel({ channelId, agentId: workerTpl.id, role: 'worker' })
+    manager.ensureChannelActive(channelId)
+    const worker = manager.deps.repos.channelAgents.listByChannel(channelId).find(m => m.role === 'worker')!
+    return { channelId, leadId: leadAgentId!, workerId: worker.id }
+  }
+  return { db, manager, ADMIN, A, B, C, D, mkUser, buildChannel }
+}
+
+// 供各分节场景模块复用(原文中这些是同一作用域内的自由绑定,顺序同 import)
+export {
+  initWorkshopDb,
+  resolveMentions,
+  extractMentionTokens,
+  projectManagementSnapshotForMember,
+  checkToolAgainstScope,
+  MANAGEMENT_TOOL_NAMES,
+  WORKSHOP_PERMISSION_SCOPE_HEADER,
+  parseWorkshopPermissionScope,
+  intersectWorkshopPermissionScope,
+}

package/scripts/test-group-chat-unit/main.ts

@@ -0,0 +1,45 @@
+/**
+ * 群聊/权限/HITL 单测编排入口:按原文顺序依次 await 各分节场景,再做汇总与收尾。
+ *
+ * 由 scripts/test-group-chat-unit.ts 拆分而来(原文第 739–749 行为汇总/收尾段)。
+ * 各段之间通过 ctx 共享 manager / db / 用户 id,顺序即原文顶层顺序,不得调换。
+ */
+import { assertion, createGroupChatTestContext } from './lib'
+import { runSectionA } from './section-a-migration'
+import { runSectionB } from './section-b-permission-matrix'
+import { runSectionC } from './section-c-member-lifecycle'
+import { runSectionD } from './section-d-mention-resolution'
+import { runSectionE } from './section-e-chat-facts'
+import { runSectionF } from './section-f-user-notifications'
+import { runSectionG } from './section-g-member-projection'
+import { runSectionH } from './section-h-outbox-consistency'
+import { runSectionI } from './section-i-read-idempotency'
+import { runSectionJ } from './section-j-permission-scope'
+
+export async function runGroupChatUnitSuite(): Promise<void> {
+  const ctx = createGroupChatTestContext()
+
+  await runSectionA(ctx)
+  await runSectionB(ctx)
+  await runSectionC(ctx)
+  await runSectionD(ctx)
+  await runSectionE(ctx)
+  await runSectionF(ctx)
+  await runSectionG(ctx)
+  await runSectionH(ctx)
+  await runSectionI(ctx)
+  await runSectionJ(ctx)
+
+  // ============================================================================
+  console.log(`\n${'='.repeat(64)}`)
+  console.log(`群聊/权限单测结果:  PASS=${assertion.passed}  FAIL=${assertion.failures.length}`)
+  if (assertion.failures.length > 0) {
+    console.log('失败项:')
+    for (const f of assertion.failures) console.log(`  - ${f}`)
+  }
+  console.log('='.repeat(64))
+  const { manager, db } = ctx
+  await manager.shutdown()
+  db.close()
+  process.exit(assertion.failures.length > 0 ? 1 : 0)
+}

package/scripts/test-group-chat-unit/section-a-migration.ts

@@ -0,0 +1,75 @@
+/**
+ * 场景 A —— v17 迁移与不变量回填:新表/新列存在;旧结构库升级后既有 Channel 保持 private/owner_approve/owner_only/chat 关(行为零变化);owner 成员回填幂等、非法取值收敛为最保守档。
+ *
+ * 原文 scripts/test-group-chat-unit.ts 第 170–232 行(section 横幅 + 顶层语句块):
+ * 语句逐行原文搬运,仅把顶层块包成函数、把共享状态改为 ctx 参数。
+ *
+ * 本段用**旧结构库**验证真实升级路径,故 node:sqlite 仍是函数内原位 dynamic import(与拆分前一致)。
+ */
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import { check, initWorkshopDb, section } from './lib'
+import type { GroupChatTestContext } from './lib'
+
+export async function runSectionA(ctx: GroupChatTestContext): Promise<void> {
+  const { db, A } = ctx
+  section('A. v17 迁移与不变量回填')
+  const tables = (db.prepare('SELECT name FROM sqlite_master WHERE type=\'table\'').all() as Array<{ name: string }>).map(r => r.name)
+  for (const t of ['channel_members', 'chat_messages', 'chat_deliveries', 'user_notifications', 'outbox_events', 'hitl_requests']) {
+    check(`表 ${t} 已创建`, tables.includes(t))
+  }
+  const cols = (db.prepare('PRAGMA table_info(channels)').all() as Array<{ name: string }>).map(c => c.name)
+  for (const c of ['visibility', 'join_policy', 'approval_policy', 'chat_enabled', 'version']) {
+    check(`channels.${c} 已加列`, cols.includes(c))
+  }
+  // 迁移安全:用**旧结构库**验证真实升级路径。
+  // 关键语义:ALTER TABLE ADD COLUMN 的 DEFAULT 会填充既有行 → 升级后既有 Channel
+  // 一律 private/owner_approve/owner_only/chat_enabled=0,**行为零变化**;
+  // 且迁移**不得**在每次启动时把 owner 显式设置的 public 打回 private(否则设置无法持久)。
+  const { DatabaseSync } = await import('node:sqlite')
+  const legacyPath = join(process.env.AW_DATA_DIR!, 'legacy-upgrade.sqlite')
+  const legacyDb = new DatabaseSync(legacyPath)
+  legacyDb.exec(`CREATE TABLE channels (
+    id             TEXT PRIMARY KEY,
+    name           TEXT NOT NULL,
+    description    TEXT NOT NULL DEFAULT '',
+    scenario_prompt TEXT NOT NULL DEFAULT '',
+    llm_json       TEXT NOT NULL DEFAULT '',
+    lead_agent_id  TEXT,
+    workspace      TEXT NOT NULL DEFAULT '',
+    enabled        INTEGER NOT NULL DEFAULT 1,
+    owner_user_id  TEXT,
+    created_at     TEXT NOT NULL,
+    updated_at     TEXT NOT NULL
+  )`)
+  const now = new Date().toISOString()
+  const legacyId = randomUUID()
+  legacyDb.prepare('INSERT INTO channels (id, name, description, scenario_prompt, llm_json, lead_agent_id, workspace, enabled, owner_user_id, created_at, updated_at) VALUES (?, ?, \'\', \'\', \'\', NULL, \'\', 1, ?, ?, ?)')
+    .run(legacyId, 'legacy', A.id, now, now)
+  const orphanId = randomUUID()
+  legacyDb.prepare('INSERT INTO channels (id, name, description, scenario_prompt, llm_json, lead_agent_id, workspace, enabled, owner_user_id, created_at, updated_at) VALUES (?, ?, \'\', \'\', \'\', NULL, \'\', 1, NULL, ?, ?)')
+    .run(orphanId, 'orphan', now, now)
+  // 升级
+  initWorkshopDb(legacyDb)
+  const upg = legacyDb.prepare('SELECT id, visibility, join_policy AS joinPolicy, approval_policy AS approvalPolicy, chat_enabled AS chatEnabled FROM channels WHERE id = ?').get(legacyId) as { visibility: string, joinPolicy: string, approvalPolicy: string, chatEnabled: number }
+  check('升级后既有 Channel visibility=private', upg.visibility === 'private', upg.visibility)
+  check('升级后既有 Channel joinPolicy=owner_approve', upg.joinPolicy === 'owner_approve', upg.joinPolicy)
+  check('升级后既有 Channel approvalPolicy=owner_only', upg.approvalPolicy === 'owner_only', upg.approvalPolicy)
+  check('升级后既有 Channel chatEnabled=0(不可写公开群聊)', upg.chatEnabled === 0, String(upg.chatEnabled))
+  const upgOwnerMembers = legacyDb.prepare('SELECT user_id AS userId, role, status FROM channel_members WHERE channel_id = ?').all(legacyId) as Array<{ userId: string, role: string, status: string }>
+  check('升级回填 owner 成员且恰好一条 active owner', upgOwnerMembers.length === 1 && upgOwnerMembers[0]!.userId === A.id && upgOwnerMembers[0]!.role === 'owner' && upgOwnerMembers[0]!.status === 'active', JSON.stringify(upgOwnerMembers))
+  const upgOrphan = legacyDb.prepare('SELECT visibility, chat_enabled AS chatEnabled FROM channels WHERE id = ?').get(orphanId) as { visibility: string, chatEnabled: number }
+  check('升级后 owner=NULL 遗留 Channel 仍为 private + chat 关', upgOrphan.visibility === 'private' && upgOrphan.chatEnabled === 0)
+  check('升级后 owner=NULL 遗留 Channel 无 owner 成员行', (legacyDb.prepare('SELECT COUNT(*) AS n FROM channel_members WHERE channel_id = ?').get(orphanId) as { n: number }).n === 0)
+  // 幂等 + 不覆盖合法设置:owner 显式开启 public 后再次 init 必须保持 public(设置可持久)
+  legacyDb.exec(`UPDATE channels SET visibility = 'public', join_policy = 'open', approval_policy = 'any_member', chat_enabled = 1 WHERE id = '${legacyId}'`)
+  initWorkshopDb(legacyDb)
+  const again = legacyDb.prepare('SELECT visibility, join_policy AS joinPolicy, approval_policy AS approvalPolicy, chat_enabled AS chatEnabled FROM channels WHERE id = ?').get(legacyId) as { visibility: string, joinPolicy: string, approvalPolicy: string, chatEnabled: number }
+  check('重复 init 幂等且不覆盖 owner 显式设置', again.visibility === 'public' && again.joinPolicy === 'open' && again.approvalPolicy === 'any_member' && again.chatEnabled === 1, JSON.stringify(again))
+  // 非法值收敛:未知取值回落最保守档(不放宽权限)
+  legacyDb.exec(`UPDATE channels SET visibility = 'PUBLIC_BOGUS', join_policy = 'bogus', approval_policy = 'bogus', chat_enabled = 7 WHERE id = '${legacyId}'`)
+  initWorkshopDb(legacyDb)
+  const clamped = legacyDb.prepare('SELECT visibility, join_policy AS joinPolicy, approval_policy AS approvalPolicy, chat_enabled AS chatEnabled FROM channels WHERE id = ?').get(legacyId) as { visibility: string, joinPolicy: string, approvalPolicy: string, chatEnabled: number }
+  check('非法取值收敛为最保守档', clamped.visibility === 'private' && clamped.joinPolicy === 'owner_approve' && clamped.approvalPolicy === 'owner_only' && clamped.chatEnabled === 0, JSON.stringify(clamped))
+  legacyDb.close()
+}