agentworkshop 0.7.41 → 0.7.46

package/server/services/workshop/db/database/seed-data.ts

@@ -0,0 +1,60 @@
+/**
+ * 内置 Agent 模板与内置编组常量
+ * (由 server/services/workshop/db/database.ts 按职责拆出;内容逐行原文搬运)
+ */
+
+export const DEFAULT_AGENT_TEMPLATES: Array<{ id: string, name: string, harness: string, config: Record<string, unknown> }> = [
+  { id: 'tpl-default-lead', name: '开发主管', harness: 'mock', config: { role: 'lead', intro: '统筹任务拆解与进度调度,分配 worker 执行' } },
+  { id: 'tpl-default-backend', name: '后端工程师', harness: 'mock', config: { role: 'worker', intro: '负责服务端接口、数据与集成逻辑' } },
+  { id: 'tpl-default-frontend', name: '前端工程师', harness: 'mock', config: { role: 'worker', intro: '负责页面、交互与前端工程' } },
+  { id: 'tpl-default-qa', name: '测试工程师', harness: 'mock', config: { role: 'worker', intro: '负责用例设计与质量验证' } },
+  { id: 'tpl-default-docs', name: '文档撰写', harness: 'mock', config: { role: 'worker', intro: '负责说明、报告与文档沉淀' } },
+  // 特定场景 lead 模板:带 systemPromptPrefix 预设,用户添加为 lead 时场景提示词自动注入 harness
+  {
+    id: 'tpl-scenario-payment-lead',
+    name: '支付网关交付主管(场景:高并发支付)',
+    harness: 'omp',
+    config: {
+      role: 'lead',
+      intro: '支付网关专项交付 lead;已预设高并发支付场景系统提示',
+      systemPromptPrefix: [
+        '你是支付网关专项交付组的 Lead 主管,负责拆解并推进支付网关的端到端交付。',
+        '## 场景背景',
+        '本团队聚焦高并发支付网关:订单支付、退款、对账、风控与降级预案。',
+        '## 你的调度原则',
+        '1. 每次只拆解当前最有价值的一个子任务,交给最空闲的 worker,不要并行铺开。',
+        '2. 子任务须包含明确的验收标准(接口契约/性能指标/失败路径)。',
+        '3. 支付类需求默认考虑:幂等、超时兜底、对账一致与限流降级。',
+        '4. worker 完成一个任务后要复核其成果是否满足验收标准,不满足则补充分发。',
+        '## 交付红线',
+        '涉及资金与订单状态的变更,必须以 artifact 显式标注幂等键与回滚方案;任何不确定项先 ask 用户确认。',
+      ].join('\n'),
+    },
+  },
+]
+
+/** 默认 AgentTeam(成员引用上述模板 id) */
+export const DEFAULT_TEAMS: Array<{ id: string, name: string, description: string, members: Array<{ templateId: string, role: 'lead' | 'worker' }> }> = [
+  {
+    id: 'team-default-fullstack',
+    name: '全栈交付组',
+    description: '默认编组:主管 + 后端 + 前端 + 测试,开箱即可部署到 Channel',
+    members: [
+      { templateId: 'tpl-default-lead', role: 'lead' },
+      { templateId: 'tpl-default-backend', role: 'worker' },
+      { templateId: 'tpl-default-frontend', role: 'worker' },
+      { templateId: 'tpl-default-qa', role: 'worker' },
+    ],
+  },
+  {
+    id: 'team-default-docs',
+    name: '文档维护组',
+    description: '默认编组:文档撰写(lead)+ 测试复核,适合文档与发布场景',
+    members: [
+      { templateId: 'tpl-default-docs', role: 'lead' },
+      { templateId: 'tpl-default-qa', role: 'worker' },
+    ],
+  },
+]
+
+/** 内置 Channel 模板成员条目(members_json 元素) */

package/server/services/workshop/db/database/seed.ts

@@ -0,0 +1,145 @@
+/**
+ * 内置 Channel 模板常量与首启种子写入
+ * (由 server/services/workshop/db/database.ts 按职责拆出;内容逐行原文搬运)
+ */
+import { AML_AGENT_TEMPLATES, AML_TEAM } from '../aml-team-seeds'
+import { DEFAULT_AGENT_TEMPLATES, DEFAULT_TEAMS } from './seed-data'
+import type { DatabaseSync } from 'node:sqlite'
+
+export type BuiltinChannelMember = { templateId: string, role: 'lead' | 'worker' } | { inline: { name: string, harness: string, config: Record<string, unknown> }, role: 'lead' | 'worker' }
+
+/** 默认 Channel 模板(场景 + 团队组合;实例化 = 一键建 channel 并装配成员) */
+export const DEFAULT_CHANNEL_TEMPLATES: Array<{
+  id: string
+  name: string
+  description: string
+  scenarioPrompt: string
+  members: BuiltinChannelMember[]
+}> = [
+  {
+    id: 'chtpl-default-fullstack',
+    name: '全栈交付通道',
+    description: '内置模板:主管带队 + 后端/前端/测试,适合常规交付任务',
+    scenarioPrompt: '团队按主管调度协作交付;每个子任务完成后由主管复核,产出统一沉淀为 artifact。',
+    members: [
+      { templateId: 'tpl-default-lead', role: 'lead' },
+      { templateId: 'tpl-default-backend', role: 'worker' },
+      { templateId: 'tpl-default-frontend', role: 'worker' },
+      { templateId: 'tpl-default-qa', role: 'worker' },
+    ],
+  },
+  {
+    id: 'chtpl-default-review',
+    name: '文档评审通道',
+    description: '内置模板:文档撰写 + 测试复核,适合文档、报告与评审场景',
+    scenarioPrompt: '以文档产出与质量复核为主线;撰写完成后由复核角色检查并反馈修改意见。',
+    members: [
+      { templateId: 'tpl-default-docs', role: 'lead' },
+      { templateId: 'tpl-default-qa', role: 'worker' },
+    ],
+  },
+  {
+    id: 'chtpl-preset-optical-film',
+    name: '光学薄膜涂布产线优化组',
+    description: '工业场景预设:涂布产线数字孪生优化 —— 生产主管 + 工艺工程师 + 数据分析师,面向烘箱温控与涂层质量闭环',
+    scenarioPrompt: `## 产线场景:光学薄膜涂布产线(精密涂布车间)
+本团队服务于一条光学薄膜涂布产线:PET 基材经放卷 → 电晕处理 → 精密涂布(光学胶)→ 烘箱多段干燥 → 收卷,成品为显示面板用光学级薄膜。烘箱温度是涂层厚度均匀性与气泡缺陷的第一工艺根因;供胶/熔体系统压力波动反映输胶健康度,与温度耦合影响流平效果。
+质量目标:涂层厚度均匀性 ±2% 以内,无气泡/橘皮缺陷;能耗约束下避免过热降解。产线的数控节点(烘箱温度设定等)与数采节点(涂布温度/系统压力等)已实时接入数字孪生;节点按产线分色渲染,操作前必须先调用 my_industrial_nodes 理解授权节点的物理意义、安全量程与活动配方工艺窗口。
+
+## 团队分工(每位成员按此定位协作)
+- 生产主管(lead):理解用户优化目标 → 拆解为「数据分析」与「工艺调整」子任务并派发 → 复核成员结论(必须带数据证据)→ 汇总汇报;不直接操作节点,协调跨成员信息(如把数据分析师的越限发现转给工艺工程师处置)。
+- 工艺工程师(worker):持有数控节点授权 —— 用 daq_query 取证 → 判定设定-响应关系 → 在「安全量程 ∩ 配方窗口」内小步幅下发 dcw_control(单变量调整);手动确认模式节点先说明理由等用户批准;调整后等待热惯性响应再复测。
+- 数据分析师(worker):持有数采节点授权 —— 用 daq_query 获取时序数据(支持按产品/配方/时间窗过滤),输出趋势/均值/极值/越限统计与工况判读(区分设定-响应滞后与真实异常);发现越限或异常趋势第一时间用 send_message_to_agent 通报 lead 与工艺工程师。
+协作规则:引用数值必带单位与时间窗;结论不确定时先补数据再下判断;所有阶段性结论沉淀为任务交付物。
+
+## 作业纪律
+数据先行(先看数再动手)→ 窗口内小步幅(单次 ≤ 量程 2%)→ 单变量调整 → 复测闭环(调整后等待工艺响应再评估,不连续大幅调整)→ 异常先判读再行动 → 结论必附数据证据。任何成员不得越权操作未绑定节点。`,
+    members: [
+      { templateId: 'tpl-default-lead', role: 'lead' },
+      { inline: { name: '工艺工程师', harness: 'omp', config: { rpcMode: 'rpc', systemPromptPrefix: '你是光学薄膜涂布产线的工艺工程师,精通烘箱多段温控与涂层质量的关联。操作数控节点的标准流程:my_industrial_nodes 理解节点 → daq_query 取证 → dcw_control 在配方窗口内小步幅下发 → 等待热惯性后复测。手动确认模式下发前必须说明理由。结论一律引用带单位与时间窗的数据。' } }, role: 'worker' },
+      { inline: { name: '数据分析师', harness: 'omp', config: { rpcMode: 'rpc', systemPromptPrefix: '你是光学薄膜涂布产线的数据分析师,擅长时序数据判读与工况诊断。用 daq_query 获取授权数采节点数据,输出趋势/统计/越限分析,判读时结合同产线数控设定考虑设定-响应滞后;发现越限或异常趋势立即通报 lead 与工艺工程师。结论一律引用具体数值。' } }, role: 'worker' },
+    ],
+  },
+  {
+    id: 'chtpl-preset-extrusion',
+    name: '薄膜挤出流延产线优化组',
+    description: '工业场景预设:挤出流延产线数字孪生优化 —— 生产主管 + 工艺工程师 + 数据分析师,面向熔体压力/温度耦合控制',
+    scenarioPrompt: `## 产线场景:薄膜挤出流延产线(挤出车间)
+本团队服务于一条薄膜挤出流延产线:原料经计量混料 → 螺杆挤出塑化 → 熔体泵计量 → 挤出模头流延 → 冷辊定型 → 测厚 → 收卷。熔体压力稳定性是挤出质量的脉搏:压力波动直接导致膜厚纵向偏差;熔体温度决定塑化质量,过热引发降解发黄、过低塑化不良。压力与温度强耦合(温度升高黏度下降、压力响应滞后),调参必须单变量小步幅。
+质量目标:膜厚纵向偏差 ≤ ±3%,无晶点/发黄;注意螺杆与熔体泵的机械损耗征兆(压力基线漂移)。产线的数控节点(熔体温度设定等)与数采节点(熔体压力/熔体温度等)已接入数字孪生;操作前必须先调用 my_industrial_nodes 理解授权节点。
+
+## 团队分工(每位成员按此定位协作)
+- 生产主管(lead):承接用户优化目标 → 拆解派发子任务 → 复核数据证据 → 汇总汇报;协调信息流(数据侧发现 → 工艺侧处置 → 数据侧复测确认);不直接操作节点。
+- 工艺工程师(worker):持有数控节点授权 —— 温度/转速设定调整遵循「先看数、小步幅、单变量、等响应」;目标值必须在安全量程与活动配方工艺窗口内;手动确认模式先说明理由等用户批准。
+- 数据分析师(worker):持有数采节点授权 —— 监控压力/温度时序,识别基线漂移、周期性波动(螺杆脉动)与越限报警;为工艺调整提供前后对照证据;异常立即通报。
+协作规则:引用数值必带单位与时间窗;跨成员信息经 send_message_to_agent 传递;结论沉淀为任务交付物。
+
+## 作业纪律
+数据先行 → 窗口内小步幅(单次 ≤ 量程 2%)→ 单变量调整(温度与转速禁止同时调)→ 复测闭环 → 压力异常优先判读(滤网堵塞倾向 vs 温度耦合 vs 真实波动)→ 结论必附数据证据。任何成员不得越权操作未绑定节点。`,
+    members: [
+      { templateId: 'tpl-default-lead', role: 'lead' },
+      { inline: { name: '工艺工程师', harness: 'omp', config: { rpcMode: 'rpc', systemPromptPrefix: '你是薄膜挤出流延产线的工艺工程师,精通熔体压力/温度耦合控制与流延质量。操作数控节点:my_industrial_nodes → daq_query 取证 → dcw_control 窗口内小步幅(温度与转速禁同调)→ 等响应后复测。结论引用带单位与时间窗的数据。' } }, role: 'worker' },
+      { inline: { name: '数据分析师', harness: 'omp', config: { rpcMode: 'rpc', systemPromptPrefix: '你是薄膜挤出流延产线的数据分析师,擅长熔体压力/温度时序判读。用 daq_query 输出趋势/统计/越限分析,识别基线漂移与周期波动;结合同线数控设定考虑耦合与滞后;异常立即通报 lead 与工艺工程师。结论引用具体数值。' } }, role: 'worker' },
+    ],
+  },
+  {
+    id: 'chtpl-hybrid-twin-mpc-default',
+    name: 'Hybrid Twin MPC 建模通道',
+    description: '通用 AML 混合孪生默认模板：物理主干、数据残差、VirtualTrial 与 recommendation-only MPC。实例化时注入具体场景和节点绑定。',
+    scenarioPrompt: `你是 Hybrid Twin AML/MPC 场景团队。场景提示词不是安全边界的权威来源，必须以已发布 SceneContract、节点绑定和服务端门禁为准。
+
+作业顺序：先读取节点语义和 DAQ 数据 → 建立/校准物理主干 → 训练有界数据残差 → 运行 TwinSnapshot/VirtualTrial → 评估 UQ/OOD/全轨迹硬约束 → 模型门禁未通过时只能 safe_small_step 试探并收集数据 → 门禁通过后才能做更精确的 recommendation-only 搜索。禁止任何 Agent 直接写 DCW；所有建议必须 candidateExecuted=false，真实写入另行经过安全授权。`,
+    members: [
+      { templateId: 'tpl-aml-lead', role: 'lead' },
+      { templateId: 'tpl-aml-data', role: 'worker' },
+      { templateId: 'tpl-aml-trainer', role: 'worker' },
+      { templateId: 'tpl-aml-eval', role: 'worker' },
+    ],
+  },
+]
+
+/**
+ * 默认模板与编组注入:
+ * - 固定 id + INSERT OR IGNORE,每次初始化幂等执行(重启安全;已有库补种,新库直接种)
+ * - owner_user_id = NULL + visibility = 'public':内置公共模板,所有用户可读可用,任何人(含 admin)不可修改删除
+ */
+export function seedDefaultWorkshopData(db: DatabaseSync): void {
+  const now = new Date().toISOString()
+  const insertAgent = db.prepare(
+    'INSERT OR IGNORE INTO agents (id, name, harness, config_json, enabled, visibility, owner_user_id, created_at, updated_at) VALUES (?, ?, ?, ?, 1, \'public\', NULL, ?, ?)',
+  )
+  for (const t of DEFAULT_AGENT_TEMPLATES) {
+    insertAgent.run(t.id, t.name, t.harness, JSON.stringify(t.config), now, now)
+  }
+  // v15:AML 自动建模团队种子(内置公共,同款 INSERT OR IGNORE 幂等)
+  for (const t of AML_AGENT_TEMPLATES) {
+    insertAgent.run(t.id, t.name, t.harness, JSON.stringify(t.config), now, now)
+  }
+  const insertTeam = db.prepare(
+    'INSERT OR IGNORE INTO teams (id, name, description, visibility, owner_user_id, created_at, updated_at) VALUES (?, ?, ?, \'public\', NULL, ?, ?)',
+  )
+  const insertMember = db.prepare(
+    'INSERT OR IGNORE INTO team_members (team_id, template_id, role, created_at) VALUES (?, ?, ?, ?)',
+  )
+  for (const team of DEFAULT_TEAMS) {
+    insertTeam.run(team.id, team.name, team.description, now, now)
+    for (const m of team.members) {
+      insertMember.run(team.id, m.templateId, m.role, now)
+    }
+  }
+  // v15:AML 编组种子(team + team_members 同款幂等注入)
+  for (const team of [AML_TEAM]) {
+    insertTeam.run(team.id, team.name, team.description, now, now)
+    for (const m of team.members) {
+      insertMember.run(team.id, m.templateId, m.role, now)
+    }
+  }
+  const insertChannelTpl = db.prepare(
+    'INSERT OR IGNORE INTO channel_templates (id, name, description, scenario_prompt, workspace, lead_json, members_json, visibility, owner_user_id, created_at, updated_at) VALUES (?, ?, ?, ?, \'\', \'\', ?, \'public\', NULL, ?, ?)',
+  )
+  for (const tpl of DEFAULT_CHANNEL_TEMPLATES) {
+    insertChannelTpl.run(tpl.id, tpl.name, tpl.description, tpl.scenarioPrompt, JSON.stringify(tpl.members), now, now)
+  }
+}
+
+/** channels 表行 */

package/server/services/workshop/db/hitl-request.repo.ts

@@ -0,0 +1,221 @@
+/**
+ * HitlRequest 仓储 —— v17 HITL 持久化事实源(hitl_requests)。
+ *
+ * 定位(主计划 §13.4):`hitl-registry` 只是进程内缓存门面;重启恢复、并发审批
+ * 抢占、策略资格判定都必须以本表为准。
+ *
+ * 状态机:
+ *   pending → resolving → answered | approved | rejected | cancelled | expired | failed
+ *                      ↘ delivery_unknown → reconciling →(answered|failed)
+ *
+ * 决策抢占必须用**条件更新**(`WHERE id=? AND status='pending'`),返回受影响行数:
+ * 只有 changes>0 的那一个调用者获得决策权,其余拿到 409(并发审批只允许一个成功)。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import type { HitlRequestRow } from './database'
+
+const COLS = `id, kind, request_type AS requestType, native_request_id AS nativeRequestId, channel_id AS channelId,
+  agent_id AS agentId, agent_name AS agentName, session_id AS sessionId, harness, mode, title, detail,
+  options_json AS optionsJson, questions_json AS questionsJson, schema_json AS schemaJson, status, policy,
+  policy_snapshot_json AS policySnapshotJson, policy_version AS policyVersion, decision_id AS decisionId,
+  responder_user_id AS responderUserId, decision_json AS decisionJson, native_confirmed AS nativeConfirmed,
+  error, created_at AS createdAt, updated_at AS updatedAt, resolved_at AS resolvedAt, expires_at AS expiresAt`
+
+/** 持久化状态(与 registry 的 AepHitlResolved.outcome 是三值映射关系) */
+export type HitlStatus
+  = 'pending'
+    | 'resolving'
+    | 'answered'
+    | 'approved'
+    | 'rejected'
+    | 'cancelled'
+    | 'expired'
+    | 'failed'
+    | 'delivery_unknown'
+    | 'reconciling'
+
+/** 终态集合(不再可决策) */
+export const HITL_TERMINAL_STATUSES: ReadonlySet<string> = new Set([
+  'answered', 'approved', 'rejected', 'cancelled', 'expired', 'failed',
+])
+
+export type HitlRequestType = 'question' | 'approval'
+
+/** 创建时冻结的策略快照(资格判定 = 创建时资格 ∩ 当前资格,§13.4) */
+export interface HitlPolicySnapshot {
+  /** owner_only | any_member */
+  policy: string
+  /** 创建时 channel 策略版本(设置变更会 +1) */
+  policyVersion: number
+  /** 创建时对该 Channel 有审批资格的用户 id(冻结集合) */
+  eligibleUserIds: string[]
+  /** 创建时的 membership generation(退出再加入的用户失去旧资格) */
+  memberGenerations: Record<string, number>
+  createdAt: string
+}
+
+export interface HitlRequestCreateInput {
+  id?: string
+  kind: string
+  requestType: HitlRequestType
+  nativeRequestId?: string
+  channelId: string
+  agentId: string
+  agentName?: string
+  sessionId?: string
+  harness?: string
+  mode?: string
+  title?: string
+  detail?: string
+  options?: string[]
+  questions?: unknown[]
+  schema?: Record<string, unknown>
+  policy: string
+  policySnapshot: HitlPolicySnapshot
+  expiresAt?: string | null
+}
+
+export type HitlRequestRepo = ReturnType<typeof createHitlRequestRepo>
+
+export function createHitlRequestRepo(db: DatabaseSync) {
+  const insert = db.prepare(
+    `INSERT INTO hitl_requests (id, kind, request_type, native_request_id, channel_id, agent_id, agent_name, session_id, harness, mode, title, detail, options_json, questions_json, schema_json, status, policy, policy_snapshot_json, policy_version, decision_id, responder_user_id, decision_json, native_confirmed, error, created_at, updated_at, resolved_at, expires_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, ?, NULL, NULL, '{}', 0, '', ?, ?, NULL, ?)`,
+  )
+  const selectById = db.prepare(`SELECT ${COLS} FROM hitl_requests WHERE id = ?`)
+  const selectByKindId = db.prepare(`SELECT ${COLS} FROM hitl_requests WHERE kind = ? AND id = ?`)
+  const selectByNative = db.prepare(`SELECT ${COLS} FROM hitl_requests WHERE kind = ? AND native_request_id = ? LIMIT 1`)
+  const selectPendingByChannel = db.prepare(`SELECT ${COLS} FROM hitl_requests WHERE channel_id = ? AND status IN ('pending', 'resolving') ORDER BY created_at ASC`)
+  const selectPendingAll = db.prepare(`SELECT ${COLS} FROM hitl_requests WHERE status IN ('pending', 'resolving') ORDER BY created_at ASC`)
+  const selectNonTerminal = db.prepare(`SELECT ${COLS} FROM hitl_requests WHERE status NOT IN ('answered', 'approved', 'rejected', 'cancelled', 'expired', 'failed') ORDER BY created_at ASC`)
+  const selectRecent = db.prepare(`SELECT ${COLS} FROM hitl_requests ORDER BY created_at DESC LIMIT ?`)
+  const selectByChannel = db.prepare(`SELECT ${COLS} FROM hitl_requests WHERE channel_id = ? ORDER BY created_at DESC LIMIT ?`)
+  const countByStatus = db.prepare(`SELECT status, COUNT(*) AS n FROM hitl_requests GROUP BY status`)
+  /** 条件抢占:仅当仍 pending 时才能置 resolving(并发审批的原子闸门) */
+  const claimStmt = db.prepare(
+    `UPDATE hitl_requests SET status = 'resolving', decision_id = ?, responder_user_id = ?, updated_at = ?
+     WHERE id = ? AND status = 'pending'`,
+  )
+  const finalizeStmt = db.prepare(
+    `UPDATE hitl_requests SET status = ?, decision_json = ?, native_confirmed = ?, error = ?, updated_at = ?, resolved_at = ?
+     WHERE id = ? AND status IN ('pending', 'resolving', 'delivery_unknown', 'reconciling')`,
+  )
+  const markDeliveryUnknownStmt = db.prepare(
+    `UPDATE hitl_requests SET status = 'delivery_unknown', error = ?, updated_at = ? WHERE id = ? AND status = 'resolving'`,
+  )
+  const markReconcilingStmt = db.prepare(
+    `UPDATE hitl_requests SET status = 'reconciling', updated_at = ? WHERE id = ? AND status = 'delivery_unknown'`,
+  )
+  /** 抢占回落:resolving 因原生调用失败需让出(回到 pending,允许他人重试或标记 failed) */
+  const releaseClaimStmt = db.prepare(
+    `UPDATE hitl_requests SET status = 'pending', decision_id = NULL, responder_user_id = NULL, error = ?, updated_at = ?
+     WHERE id = ? AND status = 'resolving'`,
+  )
+
+  return {
+    create(input: HitlRequestCreateInput): HitlRequestRow {
+      const id = input.id ?? randomUUID()
+      const now = new Date().toISOString()
+      insert.run(
+        id, input.kind, input.requestType, input.nativeRequestId ?? '', input.channelId, input.agentId,
+        input.agentName ?? '', input.sessionId ?? '', input.harness ?? '', input.mode ?? input.requestType,
+        input.title ?? '', input.detail ?? '',
+        JSON.stringify(input.options ?? []), JSON.stringify(input.questions ?? []), JSON.stringify(input.schema ?? {}),
+        input.policy, JSON.stringify(input.policySnapshot), input.policySnapshot.policyVersion ?? 0,
+        now, now, input.expiresAt ?? null,
+      )
+      return selectById.get(id) as unknown as HitlRequestRow
+    },
+
+    findById(id: string): HitlRequestRow | undefined {
+      return (selectById.get(id) as unknown as HitlRequestRow | undefined) ?? undefined
+    },
+
+    find(kind: string, id: string): HitlRequestRow | undefined {
+      return (selectByKindId.get(kind, id) as unknown as HitlRequestRow | undefined) ?? undefined
+    },
+
+    /** 原生 requestId 反查(重启后重挂/去重) */
+    findByNativeRequestId(kind: string, nativeRequestId: string): HitlRequestRow | undefined {
+      return (selectByNative.get(kind, nativeRequestId) as unknown as HitlRequestRow | undefined) ?? undefined
+    },
+
+    listPending(channelId?: string): HitlRequestRow[] {
+      return channelId
+        ? selectPendingByChannel.all(channelId) as unknown as HitlRequestRow[]
+        : selectPendingAll.all() as unknown as HitlRequestRow[]
+    },
+
+    /** 非终态(含 delivery_unknown/reconciling;启动恢复的对账清单) */
+    listNonTerminal(): HitlRequestRow[] {
+      return selectNonTerminal.all() as unknown as HitlRequestRow[]
+    },
+
+    listRecent(limit = 100): HitlRequestRow[] {
+      return selectRecent.all(limit) as unknown as HitlRequestRow[]
+    },
+
+    listByChannel(channelId: string, limit = 100): HitlRequestRow[] {
+      return selectByChannel.all(channelId, limit) as unknown as HitlRequestRow[]
+    },
+
+    counts(): Record<string, number> {
+      const rows = countByStatus.all() as unknown as Array<{ status: string, n: number }>
+      const out: Record<string, number> = {}
+      for (const r of rows) out[r.status] = Number(r.n)
+      return out
+    },
+
+    /**
+     * 原子抢占 pending → resolving。
+     * 返回 true = 本次调用获得决策权(唯一);false = 已被他人抢占/已终态 → 上层返回 409。
+     */
+    claimPending(id: string, decisionId: string, responderUserId: string): boolean {
+      return Number(claimStmt.run(decisionId, responderUserId, new Date().toISOString(), id).changes ?? 0) > 0
+    },
+
+    /** 落终态。`nativeConfirmed` 必须由 adapter 的引擎确认结果决定(§8 步骤 7)。 */
+    finalize(id: string, status: HitlStatus, opts: {
+      decision?: Record<string, unknown>
+      nativeConfirmed: boolean
+      error?: string
+    }): boolean {
+      return Number(finalizeStmt.run(
+        status,
+        JSON.stringify(opts.decision ?? {}),
+        opts.nativeConfirmed ? 1 : 0,
+        (opts.error ?? '').slice(0, 500),
+        new Date().toISOString(),
+        new Date().toISOString(),
+        id,
+      ).changes ?? 0) > 0
+    },
+
+    /** 原生调用结果未知 → delivery_unknown(不重试、不标记成功) */
+    markDeliveryUnknown(id: string, error: string): boolean {
+      return Number(markDeliveryUnknownStmt.run(error.slice(0, 500), new Date().toISOString(), id).changes ?? 0) > 0
+    },
+
+    markReconciling(id: string): boolean {
+      return Number(markReconcilingStmt.run(new Date().toISOString(), id).changes ?? 0) > 0
+    },
+
+    /** 抢占回落(原生调用明确失败且未产生副作用时) */
+    releaseClaim(id: string, error = ''): boolean {
+      return Number(releaseClaimStmt.run(error.slice(0, 500), new Date().toISOString(), id).changes ?? 0) > 0
+    },
+
+    /**
+     * 启动恢复:重启后**绝不自动批准**。
+     * 把所有非终态置 failed(error 说明原生会话已随进程消失),返回受影响行数。
+     * `resumable` 谓词允许调用方保留真正可恢复的条目(如 dcw 内存审批必定不可恢复)。
+     */
+    failAllNonTerminalOnRestart(error = '服务重启,原生会话已失效,未自动批准'): number {
+      return Number(db.prepare(
+        `UPDATE hitl_requests SET status = 'failed', error = ?, updated_at = ?, resolved_at = ?
+         WHERE status NOT IN ('answered', 'approved', 'rejected', 'cancelled', 'expired', 'failed')`,
+      ).run(error, new Date().toISOString(), new Date().toISOString()).changes ?? 0)
+    },
+  }
+}

package/server/services/workshop/db/notification.repo.ts

@@ -0,0 +1,199 @@
+/**
+ * Notification 仓储 —— v17 用户级通知事实源(user_notifications)。
+ *
+ * 关键语义(主计划 §6):
+ * - 通知**必须**按 recipient_user_id 定向;禁止把全局 `broadcastPeerEvent`(seq=0)当通知通道。
+ * - `event_id` 是幂等键:同 (recipient, event) 只落一行(重复投递不产生重复弹窗)。
+ * - 通知表是事实源:断线/刷新后按游标(created_at + rowid)补发。
+ */
+import { randomUUID } from 'node:crypto'
+import type { DatabaseSync } from 'node:sqlite'
+import type { UserNotificationRow } from './database'
+
+const COLS = 'id, recipient_user_id AS recipientUserId, channel_id AS channelId, chat_message_id AS chatMessageId, hitl_kind AS hitlKind, hitl_id AS hitlId, event_id AS eventId, type, title, body, payload_json AS payloadJson, created_at AS createdAt, read_at AS readAt'
+
+export type NotificationType = 'mention' | 'agent_reply' | 'hitl_request' | 'hitl_resolved' | 'member'
+
+export interface NotificationCreateInput {
+  recipientUserId: string
+  channelId?: string | null
+  chatMessageId?: string | null
+  hitlKind?: string | null
+  hitlId?: string | null
+  /** 幂等键(必填):建议 `${type}:${聚合 id}:${recipient}` 或事件 id */
+  eventId: string
+  type: NotificationType
+  title?: string
+  body?: string
+  payload?: Record<string, unknown>
+  id?: string
+  createdAt?: string
+}
+
+export type NotificationRepo = ReturnType<typeof createNotificationRepo>
+
+export function createNotificationRepo(db: DatabaseSync) {
+  const insert = db.prepare(
+    `INSERT INTO user_notifications (id, recipient_user_id, channel_id, chat_message_id, hitl_kind, hitl_id, event_id, type, title, body, payload_json, created_at, read_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL)`,
+  )
+  const selectByEvent = db.prepare(`SELECT ${COLS} FROM user_notifications WHERE recipient_user_id = ? AND event_id = ?`)
+  const selectById = db.prepare(`SELECT ${COLS} FROM user_notifications WHERE id = ?`)
+  const selectRecent = db.prepare(`SELECT ${COLS} FROM user_notifications WHERE recipient_user_id = ? ORDER BY created_at DESC, rowid DESC LIMIT ?`)
+  const selectUnread = db.prepare(`SELECT ${COLS} FROM user_notifications WHERE recipient_user_id = ? AND read_at IS NULL ORDER BY created_at DESC, rowid DESC LIMIT ?`)
+  const selectAfterCursor = db.prepare(
+    `SELECT ${COLS} FROM user_notifications
+     WHERE recipient_user_id = ?
+       AND (created_at > ? OR (created_at = ? AND rowid > ?))
+     ORDER BY created_at ASC, rowid ASC LIMIT ?`,
+  )
+  const selectAnyByEvent = db.prepare(`SELECT ${COLS} FROM user_notifications WHERE event_id = ? LIMIT 1`)
+  /** 游标锚点丢失时的退化路径:严格大于该时刻(同毫秒的行无法再定位) */
+  const selectAfterCreatedAt = db.prepare(
+    `SELECT ${COLS} FROM user_notifications WHERE recipient_user_id = ? AND created_at > ? ORDER BY created_at ASC, rowid ASC LIMIT ?`,
+  )
+  const rowidOf = db.prepare(`SELECT rowid AS rid FROM user_notifications WHERE id = ?`)
+  const createdOf = db.prepare(`SELECT created_at AS createdAt FROM user_notifications WHERE id = ?`)
+  const countUnread = db.prepare(`SELECT COUNT(*) AS n FROM user_notifications WHERE recipient_user_id = ? AND read_at IS NULL`)
+  const markReadStmt = db.prepare(`UPDATE user_notifications SET read_at = ? WHERE recipient_user_id = ? AND id = ? AND read_at IS NULL`)
+  const markAllReadStmt = db.prepare(`UPDATE user_notifications SET read_at = ? WHERE recipient_user_id = ? AND read_at IS NULL`)
+  const markChannelReadStmt = db.prepare(`UPDATE user_notifications SET read_at = ? WHERE recipient_user_id = ? AND channel_id = ? AND read_at IS NULL`)
+  const deleteForRecipientStmt = db.prepare(`DELETE FROM user_notifications WHERE recipient_user_id = ?`)
+  /** 撤权清理:只删该用户在**该频道**的通知(不波及其它频道) */
+  const deleteChannelForRecipientStmt = db.prepare(`DELETE FROM user_notifications WHERE recipient_user_id = ? AND channel_id = ?`)
+  /** 保留期清理:删除 created_at 早于给定时刻的**已读**通知(表按时间有界;未读永不清理) */
+  const sweepReadStmt = db.prepare(`DELETE FROM user_notifications WHERE read_at IS NOT NULL AND created_at < ?`)
+
+  return {
+    /**
+     * 幂等写入通知。已存在 (recipient, eventId) 时返回既有行 + inserted=false。
+     */
+    create(input: NotificationCreateInput): { row: UserNotificationRow, inserted: boolean } {
+      const existing = selectByEvent.get(input.recipientUserId, input.eventId) as unknown as UserNotificationRow | undefined
+      if (existing) return { row: existing, inserted: false }
+      const row: UserNotificationRow = {
+        id: input.id ?? randomUUID(),
+        recipientUserId: input.recipientUserId,
+        channelId: input.channelId ?? null,
+        chatMessageId: input.chatMessageId ?? null,
+        hitlKind: input.hitlKind ?? null,
+        hitlId: input.hitlId ?? null,
+        eventId: input.eventId,
+        type: input.type,
+        title: input.title ?? '',
+        body: input.body ?? '',
+        payloadJson: JSON.stringify(input.payload ?? {}),
+        createdAt: input.createdAt ?? new Date().toISOString(),
+        readAt: null,
+      }
+      insert.run(
+        row.id, row.recipientUserId, row.channelId, row.chatMessageId, row.hitlKind, row.hitlId,
+        row.eventId, row.type, row.title, row.body, row.payloadJson, row.createdAt,
+      )
+      return { row, inserted: true }
+    },
+
+    findById(id: string): UserNotificationRow | undefined {
+      return (selectById.get(id) as unknown as UserNotificationRow | undefined) ?? undefined
+    },
+
+    findByEventId(recipientUserId: string, eventId: string): UserNotificationRow | undefined {
+      return (selectByEvent.get(recipientUserId, eventId) as unknown as UserNotificationRow | undefined) ?? undefined
+    },
+
+    /**
+     * 按 eventId 跨 recipient 取整行("刚写入的通知"发布用,调用方手上只有 eventId)。
+     *
+     * 前置约定:`eventId` 在实践中**全局唯一** —— 所有生成点都把聚合 id 与 recipient
+     * 编进键里(`mention:<chatMessageId>:<userId>` / `agent_reply:<chatMessageId>:<userId>` /
+     * `hitl_request:<hitlId>:<userId>` …)。表上的唯一约束是 `(recipient_user_id, event_id)`,
+     * 因此这里 `LIMIT 1` 是安全的;若将来引入可跨 recipient 复用的 eventId,
+     * 发布路径必须改为显式传 recipient(而不是依赖本方法)。
+     */
+    findAnyByEventId(eventId: string): UserNotificationRow | undefined {
+      return (selectAnyByEvent.get(eventId) as unknown as UserNotificationRow | undefined) ?? undefined
+    },
+
+    listRecent(recipientUserId: string, limit = 50): UserNotificationRow[] {
+      return selectRecent.all(recipientUserId, limit) as unknown as UserNotificationRow[]
+    },
+
+    listUnread(recipientUserId: string, limit = 100): UserNotificationRow[] {
+      return selectUnread.all(recipientUserId, limit) as unknown as UserNotificationRow[]
+    },
+
+    /**
+     * 游标补发:取 cursor 之后的通知(升序)。
+     *
+     * cursor = { createdAt, id };`null` 表示"没有游标"→ 返回最近 limit 条(升序)。
+     * 复合游标 `(created_at, rowid)`:同毫秒批量写入也不丢不重。
+     *
+     * **游标行已不存在时**不能把 rowid 退化成 0 —— 那会返回所有 created_at 等于该时刻的行
+     * (重复投递)。此时改为严格的 `created_at > ?`,只可能漏掉"同一毫秒且排在原行之后"的行,
+     * 而那种行本就无法定位(锚点已删),属可接受退化。
+     */
+    listAfterCursor(recipientUserId: string, cursor: { createdAt: string, id: string } | null, limit = 200): UserNotificationRow[] {
+      if (!cursor) {
+        return (selectRecent.all(recipientUserId, limit) as unknown as UserNotificationRow[]).reverse()
+      }
+      const rid = (rowidOf.get(cursor.id) as { rid: number } | undefined)?.rid
+      if (rid === undefined) {
+        return selectAfterCreatedAt.all(recipientUserId, cursor.createdAt, limit) as unknown as UserNotificationRow[]
+      }
+      return selectAfterCursor.all(recipientUserId, cursor.createdAt, cursor.createdAt, rid, limit) as unknown as UserNotificationRow[]
+    },
+
+    /** 由通知 id 构造游标(补发起点);不存在返回 null */
+    cursorOf(id: string): { createdAt: string, id: string } | null {
+      const c = createdOf.get(id) as { createdAt: string } | undefined
+      if (!c) return null
+      return { createdAt: c.createdAt, id }
+    },
+
+    unreadCount(recipientUserId: string): number {
+      return Number((countUnread.get(recipientUserId) as { n: number } | undefined)?.n ?? 0)
+    },
+
+    /** 标记单条已读(仅本人;已读则返回 false 表示无变化) */
+    markRead(recipientUserId: string, id: string): boolean {
+      return markReadStmt.run(new Date().toISOString(), recipientUserId, id).changes > 0
+    },
+
+    markAllRead(recipientUserId: string): number {
+      return Number(markAllReadStmt.run(new Date().toISOString(), recipientUserId).changes ?? 0)
+    },
+
+    markChannelRead(recipientUserId: string, channelId: string): number {
+      return Number(markChannelReadStmt.run(new Date().toISOString(), recipientUserId, channelId).changes ?? 0)
+    },
+
+    /**
+     * 成员被移除/退出:清理其通知,使其**不再补拉**(§13.7
+     * "removed 成员立即失去读、发言、审批、通知补拉权限")。
+     *
+     * 按 channel 限定:全量 `deleteForRecipient` 会连带抹掉该用户**其它频道**的通知,
+     * 而撤权只针对一个 Channel。`channelId` 为空时退化为全量清理(账号注销等场景)。
+     */
+    deleteForChannel(recipientUserId: string, channelId: string | null): number {
+      if (!channelId) {
+        return Number(deleteForRecipientStmt.run(recipientUserId).changes ?? 0)
+      }
+      return Number(deleteChannelForRecipientStmt.run(recipientUserId, channelId).changes ?? 0)
+    },
+
+    /**
+     * 保留期清理:删除 `created_at < beforeIso` 的**已读**通知,返回清理行数。
+     *
+     * 按 `created_at`(而非 `read_at`)判龄:保留期的目的是让表**按时间有界**,
+     * 若按 read_at 判龄,"很久以前创建、刚刚才读"的行会再存活一整个窗口,
+     * 表的有界性取决于用户何时点开,不可预测。
+     *
+     * **未读行永不清理** —— 未读是"用户还没看到"的事实,删掉就是丢通知。
+     * 已读且过期的行可以回收:客户端游标只推进不回退,补发不需要远古已读行;
+     * 即使游标恰好指向被删行,`listAfterCursor` 也有"锚点缺失"的安全退化路径。
+     */
+    sweepRead(beforeIso: string): number {
+      return Number(sweepReadStmt.run(beforeIso).changes ?? 0)
+    },
+  }
+}