agentworkshop 0.2.1

package/server/plugins/dev-stability-guard.ts

@@ -0,0 +1,42 @@
+/**
+ * Server 稳定性护栏:浏览器断开(WS/keep-alive socket 硬断)产生 ECONNRESET/EPIPE
+ * 类异步异常 —— Node 默认策略直接击穿进程,拖垮所有并发调试/运行会话。
+ *
+ * 严重性过滤(关键设计):只抑制 socket 级断连噪声;其余异常保留致命语义
+ * (记日志后按非零码退出)—— 安全插件的 fail-fast(如生产密钥校验失败拒绝启动)
+ * 依赖异常中止进程,绝不能被护栏吞掉。
+ */
+const SOCKET_NOISE = /ECONNRESET|EPIPE|ECONNABORTED|ETIMEDOUT|ERR_STREAM_PREMATURE_CLOSE/
+
+function isSocketNoise(reason: unknown): boolean {
+  if (reason == null) return false
+  const err = reason as NodeJS.ErrnoException
+  if (typeof err.code === 'string') return SOCKET_NOISE.test(err.code)
+  return SOCKET_NOISE.test(String(reason))
+}
+
+function describe(reason: unknown): string {
+  return reason instanceof Error
+    ? `${reason.message}\n${reason.stack?.slice(0, 600) ?? ''}`
+    : String(reason)
+}
+
+export default defineNitroPlugin(() => {
+  process.on('unhandledRejection', (reason) => {
+    if (isSocketNoise(reason)) {
+      console.warn(`[stability-guard] socket noise suppressed: ${describe(reason).slice(0, 120)}`)
+      return
+    }
+    console.error(`[stability-guard] fatal unhandledRejection, exiting:\n${describe(reason)}`)
+    process.exit(1)
+  })
+  process.on('uncaughtException', (err) => {
+    if (isSocketNoise(err)) {
+      console.warn(`[stability-guard] socket noise suppressed: ${describe(err).slice(0, 120)}`)
+      return
+    }
+    console.error(`[stability-guard] fatal uncaughtException, exiting:\n${describe(err)}`)
+    process.exit(1)
+  })
+  console.warn('[stability-guard] armed (socket disconnects → log & continue; real errors → exit 1)')
+})

package/server/plugins/security.ts

@@ -0,0 +1,29 @@
+/**
+ * 安全启动插件(S2,production-readiness-plan)。
+ *
+ * production 下 sessionPassword 仍是仓库默认值 → 拒绝启动(带明确修复指引):
+ * dev/测试环境零影响;经反向代理终止 TLS 的部署基线见 config.yml 注释与 README。
+ *
+ * 与 workshop.ts 同风格:defineNitroPlugin 为恒等包装,default 直接导出普通函数。
+ */
+import { useRuntimeConfig } from '#imports'
+
+/** 仓库默认密钥(泄漏在 config.yml/git 历史,绝不可用于生产) */
+const KNOWN_DEFAULT_PASSWORDS = new Set([
+  'awshop-dev-secret-change-me-0123456789',
+  'awshop-dev-secret-change-me',
+  'change-me',
+])
+
+export default function securityPlugin() {
+  if (process.env.NODE_ENV !== 'production') return
+  const password = (useRuntimeConfig() as { session?: { password?: string } }).session?.password ?? ''
+  // 空串同样拒绝:NUXT_SESSION_PASSWORD="" 会把烘焙配置覆盖为空值,不能放行
+  if (!password || KNOWN_DEFAULT_PASSWORDS.has(password)) {
+    throw new Error(
+      '[security] 拒绝启动:production 模式下 sessionPassword 为空或仍是仓库默认值。'
+      + '请在 config.yml 的 security.sessionPassword 设置强随机密钥(≥32 位)后重启。'
+      + 'TLS/WSS 部署基线见 README「部署」一节(建议由 caddy/nginx 反向代理终止)。',
+    )
+  }
+}

package/server/plugins/system-config.ts

@@ -0,0 +1,38 @@
+/**
+ * 系统配置启动插件。
+ * Nitro 启动时:初始化 SystemConfigService(root=data 所在根) → 把 data/runtime-settings.json
+ * 的运行时覆盖应用到 runtimeConfig → 挂载文件监听（CLI/手工外部写入自动热重载 + 广播）。
+ * 与 workshop.ts 同风格:defineNitroPlugin 为恒等包装,default 直接导出普通函数。
+ * 幂等:globalThis.__systemConfig 已存在则跳过（测试预置场景）。
+ */
+import { mkdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { getSystemConfigService } from '../services/system-config'
+
+export default function systemConfigPlugin(nitroApp: {
+  hooks: { hook(name: string, fn: (...args: unknown[]) => void | Promise<void>): void }
+}): void {
+  // 先检查已设置:避免重复装配覆盖既有单例
+  if (globalThis.__systemConfig) return
+
+  const root = resolve(process.cwd())
+  // data/ 目录须存在（settings 文件落盘依赖目录）
+  try {
+    mkdirSync(resolve(root, 'data'), { recursive: true })
+  }
+  catch { /* 只读环境:init 内部会降级 */ }
+
+  const service = getSystemConfigService(root)
+  try {
+    service.init()
+    console.log(`[system-config] 运行时设置已加载 -> ${resolve(root, 'data', 'runtime-settings.json')}`)
+  }
+  catch (err) {
+    // 初始化失败不阻断服务（设置系统降级为只读构建配置）
+    console.warn('[system-config] 初始化失败(设置系统降级):', String(err?.message ?? err))
+  }
+
+  nitroApp.hooks.hook('close', () => {
+    service.dispose()
+  })
+}

package/server/plugins/workshop.ts

@@ -0,0 +1,145 @@
+/**
+ * Workshop 启动插件(设计文档 §8)。
+ * Nitro 启动时:创建 data/ 目录 → openWorkshopDb(data/workshop.sqlite)→ 装配 5 个 repo
+ * + createAgentImpl 工厂 → createAgentChannelManager → restore() 恢复运行时
+ * → 为有 lead 的 channel 启动 SchedulerLoop → 挂 globalThis.__workshopManager。
+ *
+ * 导出:
+ *  - getWorkshopManager():读取进程级 manager 单例(先检查已设置;未初始化抛 503)
+ *  - ensureLeadSchedulerLoop():为 channel 装配并启动 lead 的 SchedulerLoop(幂等)
+ *
+ * 注意:不静态 import 'nitropack/runtime/plugin'——defineNitroPlugin 是恒等函数,
+ * 插件 default 直接导出普通函数即可,避免把 nitropack 依赖引入可被 tsx 直跑测试
+ * 导入的模块图(顶层 node_modules 无 nitropack 符号链接)。
+ */
+import { mkdirSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+import { openWorkshopDb, initWorkshopDb } from '../services/workshop/db/database'
+import { createChannelRepo } from '../services/workshop/db/channel.repo'
+import { createAgentRepo } from '../services/workshop/db/agent.repo'
+import { createChannelAgentRepo } from '../services/workshop/db/channel-agent.repo'
+import { createTeamRepo } from '../services/workshop/db/team.repo'
+import { createTeamMemberRepo } from '../services/workshop/db/team-member.repo'
+import { createChannelTemplateRepo } from '../services/workshop/db/channel-template.repo'
+import { createTaskRepo } from '../services/workshop/db/task.repo'
+import { createMessageRepo } from '../services/workshop/db/message.repo'
+import { createSubscriptionRepo } from '../services/workshop/db/subscription.repo'
+import { createMemoryRepo } from '../services/workshop/db/memory.repo'
+import { createUserRepo } from '../services/workshop/db/user.repo'
+import { createChannelEventRepo } from '../services/workshop/db/channel-event.repo'
+import { createApprovalHistoryRepo, createAlarmEventRepo, createAuditRepo, createApprovalRequestRepo } from '../services/workshop/db/ops.repo'
+import { bindOpsRepos } from '../services/workshop/ops/ops'
+import { ensureAllEventRecorders } from '../api/workshop/ws'
+import { createAgentImpl } from '../services/workshop/agents/factory'
+import {
+  createAgentChannelManager,
+  type AgentChannelManager,
+  type AllRepos,
+  type ManagerDeps,
+} from '../services/workshop/runtime/manager'
+import { AppError } from '../utils/errors'
+
+declare global {
+
+  var __workshopManager: AgentChannelManager | undefined
+}
+
+/** 读取进程级 manager 单例(先检查已设置;未初始化抛 503) */
+export function getWorkshopManager(): AgentChannelManager {
+  const manager = globalThis.__workshopManager
+  if (!manager) {
+    throw new AppError(503, 'WORKSHOP_NOT_READY', 'workshop 尚未初始化(plugin 未执行)')
+  }
+  return manager
+}
+
+/**
+ * 为 channel 装配并启动 lead 的 SchedulerLoop(幂等)。
+ * 委托 manager.ensureChannelActive(懒加载:装配 lead + 调度循环)。
+ */
+export function ensureLeadSchedulerLoop(
+  manager: AgentChannelManager,
+  channelId: string,
+  options?: { tickMs?: number, stallMs?: number },
+): void {
+  manager.ensureChannelActive(channelId, options)
+}
+
+/**
+ * Nitro 启动插件(默认导出普通函数;defineNitroPlugin 为恒等包装)。
+ * 注意:runNitroPlugins 同步调用 plugin,不 await 返回值;manager.restore() 方法体全同步
+ * (无 await 语句),直接调用即同步完成恢复,故此处不 await。
+ * 幂等:globalThis.__workshopManager 已设置(如测试预置)则跳过初始化。
+ */
+export default function workshopPlugin(nitroApp: {
+  hooks: { hook(name: string, fn: (...args: unknown[]) => void | Promise<void>): void }
+}): void {
+  // 进程级未处理拒绝兜底(Node ≥23 默认对 unhandledRejection 抛错可击穿整个服务)。
+  // 环境型连接复位(休眠/断网后陈旧 socket read ECONNRESET、omp 子进程管道抖动等)
+  // 不应让服务崩溃;记录上下文后继续运行(正常业务错误仍走各自显式处理路径)。
+  process.on('unhandledRejection', (reason) => {
+    console.error('[workshop] 未处理 Promise rejection(已兜底,不影响服务):', reason)
+  })
+
+  // 先检查已设置:避免重复装配覆盖既有单例
+  if (globalThis.__workshopManager) return
+
+  // 数据目录经配置根解析（repo: <repo>/.AgentWorkShop/data;home: ~/.AgentWorkShop/data;
+  // ensureDataDir 自动迁移旧 cwd/data 位置,目录不存在则创建）
+  const dataDir = ensureDataDir()
+  mkdirSync(dataDir, { recursive: true })
+
+  // 打开(或创建)数据库 → 初始化(建表 + PRAGMA;openWorkshopDb 已内置,显式再调一次保持幂等)
+  const db = openWorkshopDb(resolve(dataDir, 'workshop.sqlite'))
+  initWorkshopDb(db)
+
+  // 装配 repos + Agent impl 工厂
+  const repos: AllRepos = {
+    users: createUserRepo(db),
+    channelEvents: createChannelEventRepo(db),
+    channels: createChannelRepo(db),
+    agents: createAgentRepo(db),
+    teams: createTeamRepo(db),
+    teamMembers: createTeamMemberRepo(db),
+    channelTemplates: createChannelTemplateRepo(db),
+    channelAgents: createChannelAgentRepo(db),
+    messages: createMessageRepo(db),
+    subscriptions: createSubscriptionRepo(db),
+    tasks: createTaskRepo(db),
+    memories: createMemoryRepo(db),
+  }
+  // S4/S5/R1/R3:合规三表仓储接线(审批历史/报警事件/审计日志/高危复核)
+  bindOpsRepos({
+    approvalHistory: createApprovalHistoryRepo(db),
+    alarmEvents: createAlarmEventRepo(db),
+    audit: createAuditRepo(db),
+    approvalRequests: createApprovalRequestRepo(db),
+  })
+  const deps: ManagerDeps = { repos, implFactory: createAgentImpl, db }
+
+  // 创建 manager → 挂全局单例(后续 REST/A2A/WS 经 getWorkshopManager() 读取)
+  const manager = createAgentChannelManager(deps)
+  globalThis.__workshopManager = manager
+
+  // 懒加载恢复:仅激活有待办任务的 channel(装配 lead + 调度循环);其余纯持久化
+  manager.restore()
+
+  // 全时事件录制:为全部存量 channel 建立常驻流(事件 server 驱动落库,与 client 无关)
+  void ensureAllEventRecorders(manager).catch(err => console.error('[workshop] 事件录制器初始化失败:', err))
+
+  // idle sweeper:空闲 agent 超时自动卸载(释放 omp 子进程与内存)。
+  // busy 成员有三重守卫(state!==idle / 信箱 pending / lead 活跃任务)不会被卸载,
+  // "作业期间进程不断开"由守卫保证;空闲宽限可经 env 调整 —— 需要进程更长常驻
+  // (免冷启动 30~90s)时调大 WORKSHOP_IDLE_GRACE_MS。
+  const idleSweepMs = Number(process.env.WORKSHOP_IDLE_SWEEP_MS) || 30_000
+  const idleGraceMs = Number(process.env.WORKSHOP_IDLE_GRACE_MS) || 120_000
+  const stopSweeper = manager.startIdleSweeper({ intervalMs: idleSweepMs, graceMs: idleGraceMs })
+
+  // 关机:完整关闭 manager(sweeper + 调度循环 + agent 运行时),关闭数据库
+  nitroApp.hooks.hook('close', async () => {
+    stopSweeper()
+    await manager.shutdown()
+    db.close()
+  })
+}

package/server/repositories/user.repository.ts

@@ -0,0 +1,391 @@
+import { existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { randomBytes, randomUUID, scryptSync, createHash, timingSafeEqual } from 'node:crypto'
+import { DatabaseSync } from 'node:sqlite'
+import { ensureDataDir } from '@/shared/config/home.mjs'
+import type { Paginated, User, UserListQuery, UserToken } from '../types/user'
+import type { UserCreate, UserUpdate } from '../schemas/user.schema'
+
+/**
+ * 全局用户数据访问层（Repository）—— SQLite 持久化（配置根 .AgentWorkShop/data/users.sqlite;
+ * repo 模式 <repo>/.AgentWorkShop/data,home 模式 ~/.AgentWorkShop/data,经 ensureDataDir 统一解析
+ * 并自动迁移旧 cwd/data 位置）。
+ * - users 表：用户档案 + 密码哈希（scrypt，salt 内嵌，明文不进库）
+ * - user_tokens 表：每用户多个 API Token（仅存 SHA-256 哈希；明文只在签发时返回一次）
+ * 进程内单例 DB 懒加载；数据源与业务逻辑解耦，service 层零改动。
+ */
+
+// 配置根 .AgentWorkShop/data（repo: <repo>/.AgentWorkShop/data,home: ~/.AgentWorkShop/data;
+// ensureDataDir 统一解析并自动迁移旧 cwd/data 位置）
+const DB_PATH = join(ensureDataDir(), 'users.sqlite')
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS users (
+  id            TEXT PRIMARY KEY,
+  name          TEXT NOT NULL,
+  email         TEXT NOT NULL UNIQUE,
+  password_hash TEXT NOT NULL,
+  role          TEXT NOT NULL DEFAULT 'user',
+  status        TEXT NOT NULL DEFAULT 'active',
+  created_at    TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS user_tokens (
+  id           TEXT PRIMARY KEY,
+  user_id      TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  label        TEXT NOT NULL DEFAULT '',
+  token_hash   TEXT NOT NULL UNIQUE,
+  token_plain  TEXT,
+  created_at   TEXT NOT NULL,
+  last_used_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_user_tokens_user ON user_tokens(user_id);
+`
+
+/** 种子用户（首次建库时写入；默认密码 Awshop@123，便于开箱登录） */
+const SEED_USERS = [
+  { name: '张伟', email: 'zhangwei@awshop.io', role: 'admin', status: 'active' },
+  { name: '王芳', email: 'wangfang@awshop.io', role: 'editor', status: 'active' },
+  { name: '李娜', email: 'lina@awshop.io', role: 'user', status: 'disabled' },
+  { name: '刘洋', email: 'liuyang@awshop.io', role: 'editor', status: 'active' },
+  { name: '陈静', email: 'chenjing@awshop.io', role: 'user', status: 'active' },
+  { name: 'Michael Chen', email: 'michael@awshop.io', role: 'user', status: 'active' },
+]
+
+let db: DatabaseSync | null = null
+
+function getDb(): DatabaseSync {
+  if (!db) {
+    // 目录由 ensureDataDir 内部创建(含旧位置迁移)
+    db = new DatabaseSync(DB_PATH)
+    db.exec(SCHEMA_SQL)
+    migrateSchema(db)
+    seedIfEmpty()
+    importLegacyWorkshopUsers(db)
+  }
+  return db
+}
+
+/** 轻量迁移：旧库 user_tokens 补 token_plain 列（明文存档，支持随时查看）+ expires_at（R2 后端过期） */
+function migrateSchema(d: DatabaseSync): void {
+  const cols = d.prepare('PRAGMA table_info(user_tokens)').all() as Array<{ name: string }>
+  if (!cols.some(c => c.name === 'token_plain')) {
+    d.exec('ALTER TABLE user_tokens ADD COLUMN token_plain TEXT')
+  }
+  if (!cols.some(c => c.name === 'expires_at')) {
+    d.exec('ALTER TABLE user_tokens ADD COLUMN expires_at TEXT')
+  }
+  // 存量 token 宽限 30 天(从部署时刻起算,避免升级即全员掉线)
+  d.prepare('UPDATE user_tokens SET expires_at = ? WHERE expires_at IS NULL').run(isoInDays(TOKEN_TTL_DAYS))
+}
+
+/** token 有效期(天,R2):过期后 findByToken 拒绝,用户重新登录即可 */
+const TOKEN_TTL_DAYS = 30
+
+/** 当前时刻 + n 天的 ISO 时间戳 */
+function isoInDays(days: number): string {
+  return new Date(Date.now() + days * 86_400_000).toISOString()
+}
+
+/** 掩码预览：前 6 后 4（token 形如 ut-xxxxxxxx…，前 6 含前缀可辨识） */
+function maskPreview(raw: string): string {
+  return `${raw.slice(0, 6)}${'•'.repeat(8)}${raw.slice(-4)}`
+}
+
+/** 首次建库写入种子用户（幂等：users 非空即跳过） */
+function seedIfEmpty(): void {
+  const d = db!
+  const { n } = d.prepare('SELECT COUNT(*) AS n FROM users').get() as { n: number }
+  if (n > 0) return
+  const insert = d.prepare('INSERT INTO users (id, name, email, password_hash, role, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
+  const hash = hashPassword('Awshop@123')
+  for (const u of SEED_USERS) {
+    insert.run(randomUUID(), u.name, u.email, hash, u.role, u.status, now())
+  }
+}
+/**
+ * 一次性迁移：旧 workshop 本地用户（data/workshop.sqlite 的 users 表）导入全局用户系统。
+ * - 保留原 id/name（资源归属 owner_user_id 不变，历史数据不丢）
+ * - 旧 token 原值重新注册为全局 token（老客户端免重新登录）
+ * - email 派生 + 随机密码（不可经密码登录，可用管理面重置）
+ * 幂等：按 id 判断已存在则跳过。
+ */
+function importLegacyWorkshopUsers(d: DatabaseSync): void {
+  // 迁移后配置根已有 workshop.sqlite;旧 cwd/data 位置兜底(仅历史未迁移场景)
+  const migrated = join(ensureDataDir(), 'workshop.sqlite')
+  const wsPath = existsSync(migrated) ? migrated : resolve(process.cwd(), 'data', 'workshop.sqlite')
+  if (!existsSync(wsPath)) return
+  let wdb: DatabaseSync
+  try {
+    wdb = new DatabaseSync(wsPath, { readOnly: true })
+  }
+  catch {
+    return // workshop 库尚不存在或不可读：跳过
+  }
+  let rows: Array<{ id: string, name: string, token: string, created_at: string }>
+  try {
+    rows = wdb.prepare('SELECT id, name, token, created_at FROM users').all() as Array<{ id: string, name: string, token: string, created_at: string }>
+  }
+  catch {
+    wdb.close()
+    return
+  }
+  wdb.close()
+
+  const exists = d.prepare('SELECT 1 FROM users WHERE id = ?')
+  const insertUser = d.prepare('INSERT INTO users (id, name, email, password_hash, role, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
+  const tokenExists = d.prepare('SELECT 1 FROM user_tokens WHERE token_hash = ?')
+  const insertToken = d.prepare('INSERT INTO user_tokens (id, user_id, label, token_hash, token_plain, created_at) VALUES (?, ?, ?, ?, ?, ?)')
+
+  for (const row of rows) {
+    if (exists.get(row.id)) continue
+    const email = `legacy-${row.id.slice(0, 8)}@workshop.local`
+    insertUser.run(row.id, row.name, email, hashPassword(randomPassword()), 'user', 'active', row.created_at ?? now())
+    const hash = hashToken(row.token)
+    if (!tokenExists.get(hash)) {
+      insertToken.run(randomUUID(), row.id, 'legacy', hash, row.token, row.created_at ?? now())
+    }
+  }
+}
+
+/** 20 位随机口令（legacy 导入用户与自动建号共用） */
+function randomPassword(): string {
+  const chars = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789'
+  const bytes = randomBytes(20)
+  let out = ''
+  for (const b of bytes) out += chars[b % chars.length]
+  return out
+}
+
+function now(): string {
+  return new Date().toISOString().slice(0, 19).replace('T', ' ')
+}
+
+// ===== 密码哈希（scrypt）=====
+
+/** 生成 scrypt 哈希（格式 salt:hash，均为 hex） */
+export function hashPassword(password: string): string {
+  const salt = randomBytes(16).toString('hex')
+  const hash = scryptSync(password, salt, 64).toString('hex')
+  return `${salt}:${hash}`
+}
+
+/** 校验密码：长度与哈希双重防御（timingSafeEqual 防时序侧信道） */
+export function verifyPassword(password: string, stored: string): boolean {
+  const [salt, hex] = stored.split(':')
+  if (!salt || !hex) return false
+  const expected = Buffer.from(hex, 'hex')
+  const actual = scryptSync(password, salt, expected.length)
+  return expected.length === actual.length && timingSafeEqual(expected, actual)
+}
+
+// ===== Token 哈希 =====
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex')
+}
+
+/** 签发新 token：明文返回一次并存档（token_plain，支持随时查看），库中另存哈希用于认证比对 */
+function issueToken(userId: string, label: string): { raw: string, row: UserToken } {
+  const raw = `ut-${randomUUID().replace(/-/g, '')}`
+  const hash = hashToken(raw)
+  const row: UserToken = {
+    id: randomUUID(),
+    userId,
+    label,
+    createdAt: now(),
+    lastUsedAt: null,
+    preview: maskPreview(raw),
+    hasPlain: true,
+  }
+  const d = getDb()
+  d.prepare('INSERT INTO user_tokens (id, user_id, label, token_hash, token_plain, created_at, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
+    .run(row.id, userId, label, hash, raw, row.createdAt, isoInDays(TOKEN_TTL_DAYS))
+  return { raw, row }
+}
+
+/** 按 token 明文查用户（命中且未过期则刷新 last_used_at）；无效/已过期返回 null。tokenId 供前端识别当前会话 token。 */
+export function findByToken(token: string): (User & { tokenId: string }) | null {
+  const d = getDb()
+  const hash = hashToken(token)
+  const row = d.prepare(
+    `SELECT u.id, u.name, u.email, u.role, u.status, u.created_at AS createdAt, t.id AS tokenId, t.expires_at AS expiresAt
+FROM user_tokens t JOIN users u ON u.id = t.user_id
+WHERE t.token_hash = ?`,
+  ).get(hash) as (User & { tokenId: string, expiresAt: string | null }) | undefined
+  if (!row) return null
+  // R2:过期单点判定(resolveUser/resolveAgentOrUser/me 全部经此收敛)
+  if (row.expiresAt && Date.parse(row.expiresAt) < Date.now()) return null
+  d.prepare('UPDATE user_tokens SET last_used_at = ? WHERE token_hash = ?').run(now(), hash)
+  return row
+}
+
+/** users 行 → User 领域对象（禁带 password_hash） */
+function toUser(row: Record<string, unknown>): User {
+  return {
+    id: String(row.id),
+    name: String(row.name),
+    email: String(row.email),
+    role: row.role as User['role'],
+    status: row.status as User['status'],
+    createdAt: String(row.created_at ?? row.createdAt),
+  }
+}
+
+export const userRepository = {
+  list({ page, pageSize, keyword }: UserListQuery): Paginated<User> {
+    const d = getDb()
+    const kw = keyword?.toLowerCase() ?? ''
+    const where = kw
+      ? `WHERE LOWER(name) LIKE ? OR LOWER(email) LIKE ?`
+      : ''
+    const params = kw ? [`%${kw}%`, `%${kw}%`] : []
+    const total = (d.prepare(`SELECT COUNT(*) AS n FROM users ${where}`).get(...params) as { n: number }).n
+    const rows = d.prepare(
+      `SELECT id, name, email, role, status, created_at AS createdAt FROM users ${where}
+       ORDER BY created_at DESC LIMIT ? OFFSET ?`,
+    ).all(...params, pageSize, (page - 1) * pageSize) as Array<Record<string, unknown>>
+    return { items: rows.map(toUser), total, page, pageSize }
+  },
+
+  findById(id: string): User | undefined {
+    const d = getDb()
+    const row = d.prepare('SELECT id, name, email, role, status, created_at AS createdAt FROM users WHERE id = ?').get(id) as Record<string, unknown> | undefined
+    return row ? toUser(row) : undefined
+  },
+
+  findByEmail(email: string): User | undefined {
+    const d = getDb()
+    const row = d.prepare('SELECT id, name, email, role, status, created_at AS createdAt FROM users WHERE LOWER(email) = LOWER(?)').get(email) as Record<string, unknown> | undefined
+    return row ? toUser(row) : undefined
+  },
+
+  findByName(name: string): User | undefined {
+    const d = getDb()
+    const row = d.prepare('SELECT id, name, email, role, status, created_at AS createdAt FROM users WHERE name = ?').get(name) as Record<string, unknown> | undefined
+    return row ? toUser(row) : undefined
+  },
+
+  /** 内部：取密码哈希（仅认证路径使用，不参与领域对象外泄） */
+  getPasswordHash(email: string): { id: string, hash: string } | null {
+    const d = getDb()
+    const row = d.prepare('SELECT id, password_hash AS hash FROM users WHERE LOWER(email) = LOWER(?)').get(email) as { id: string, hash: string } | undefined
+    return row ?? null
+  },
+
+  create(input: UserCreate & { password: string }): User {
+    const d = getDb()
+    const user: User = {
+      id: randomUUID(),
+      name: input.name,
+      email: input.email,
+      role: input.role,
+      status: input.status,
+      createdAt: now(),
+    }
+    d.prepare('INSERT INTO users (id, name, email, password_hash, role, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)')
+      .run(user.id, user.name, user.email, hashPassword(input.password), user.role, user.status, user.createdAt)
+    return user
+  },
+
+  update(id: string, input: UserUpdate): User | undefined {
+    const d = getDb()
+    const current = this.findById(id)
+    if (!current) return undefined
+    const fields: string[] = []
+    const params: string[] = []
+    if (input.name !== undefined) {
+      fields.push('name = ?')
+      params.push(input.name)
+    }
+    if (input.email !== undefined) {
+      fields.push('email = ?')
+      params.push(input.email)
+    }
+    if (input.role !== undefined) {
+      fields.push('role = ?')
+      params.push(input.role)
+    }
+    if (input.status !== undefined) {
+      fields.push('status = ?')
+      params.push(input.status)
+    }
+    if (input.password !== undefined) {
+      fields.push('password_hash = ?')
+      params.push(hashPassword(input.password))
+    }
+    if (fields.length === 0) return current
+    d.prepare(`UPDATE users SET ${fields.join(', ')} WHERE id = ?`).run(...params, id)
+    return this.findById(id)
+  },
+
+  remove(id: string): boolean {
+    const d = getDb()
+    return d.prepare('DELETE FROM users WHERE id = ?').run(id).changes > 0
+  },
+
+  // ===== API Token（每用户多个，CRUD）=====
+
+  /** 列出某用户全部 token（含掩码 preview，不含哈希/明文） */
+  listTokens(userId: string): UserToken[] {
+    const d = getDb()
+    const rows = d.prepare(
+      'SELECT id, user_id AS userId, label, token_plain AS tokenPlain, created_at AS createdAt, last_used_at AS lastUsedAt FROM user_tokens WHERE user_id = ? ORDER BY created_at ASC',
+    ).all(userId) as Array<{ id: string, userId: string, label: string, tokenPlain: string | null, createdAt: string, lastUsedAt: string | null }>
+    return rows.map(r => ({
+      id: r.id,
+      userId: r.userId,
+      label: r.label,
+      createdAt: r.createdAt,
+      lastUsedAt: r.lastUsedAt,
+      preview: r.tokenPlain ? maskPreview(r.tokenPlain) : null,
+      hasPlain: r.tokenPlain != null && r.tokenPlain !== '',
+    }))
+  },
+
+  /** 创建 token（label 缺省空串；明文仅此一次返回） */
+  createToken(userId: string, label: string): { raw: string, row: UserToken } {
+    return issueToken(userId, label)
+  },
+
+  /** 按 id 找某用户的 token（越权场景返回 null） */
+  findTokenById(userId: string, tokenId: string): UserToken | undefined {
+    const d = getDb()
+    const row = d.prepare(
+      'SELECT id, user_id AS userId, label, created_at AS createdAt, last_used_at AS lastUsedAt FROM user_tokens WHERE id = ? AND user_id = ?',
+    ).get(tokenId, userId) as unknown as UserToken | undefined
+    return row
+  },
+
+  /** 按 id 取某用户 token 的存档明文；非本人/不存在 → undefined，未存档（旧数据）→ null */
+  findTokenPlain(userId: string, tokenId: string): string | null | undefined {
+    const d = getDb()
+    const row = d.prepare(
+      'SELECT token_plain AS tokenPlain FROM user_tokens WHERE id = ? AND user_id = ?',
+    ).get(tokenId, userId) as { tokenPlain: string | null } | undefined
+    return row ? row.tokenPlain : undefined
+  },
+
+  /** 改 token 标签；不存在或非本人返回 false */
+  updateTokenLabel(userId: string, tokenId: string, label: string): boolean {
+    const d = getDb()
+    return d.prepare('UPDATE user_tokens SET label = ? WHERE id = ? AND user_id = ?').run(label, tokenId, userId).changes > 0
+  },
+
+  /** 删除/吊销 token；不存在或非本人返回 false */
+  revokeToken(userId: string, tokenId: string): boolean {
+    const d = getDb()
+    return d.prepare('DELETE FROM user_tokens WHERE id = ? AND user_id = ?').run(tokenId, userId).changes > 0
+  },
+
+  /** 登出当前 token（仅吊销该 token 本身） */
+  revokeTokenByValue(token: string): boolean {
+    const d = getDb()
+    return d.prepare('DELETE FROM user_tokens WHERE token_hash = ?').run(hashToken(token)).changes > 0
+  },
+
+  /** 测试钩子：替换内部 DB（重开内存库等） */
+  _resetForTest(): void {
+    db?.close()
+    db = null
+  },
+}