agentworkshop 0.2.1

package/server/services/workshop/scene-events.ts

@@ -0,0 +1,63 @@
+/**
+ * 场景/DAQ 事件广播总线 —— 从 ws 路由模块解耦出的常驻服务。
+ *
+ * 职责:持有 WS 在线 peer 注册表(由 workshop-ws 路由在连接/订阅时登记),
+ * 提供无频道归属事件(device.created|updated|deleted、daq.reading|
+ * daq.node.changed|daq.controller 等)的全员直推。device-twins 与 daq 的 REST
+ * 路由改为从本模块导入广播函数 —— 避免"路由文件被当库静态导入"引发
+ * nitro 打包的循环初始化(TDZ)问题。
+ */
+import type { AepEnvelope } from '../../../shared/workshop-protocol'
+
+const AEP_VERSION = 1
+
+/** 最小 peer 接口(crossws peer 的 duck typing) */
+interface WsPeer {
+  send(data: string | Uint8Array): void
+  close(code?: number, reason?: string): void
+}
+
+const g = globalThis as typeof globalThis & {
+  __sceneEventPeers?: Set<WsPeer>
+}
+
+/** 在线 peer 注册表(ws 路由 sub 成功时登记,断开/退订移除) */
+function peers(): Set<WsPeer> {
+  return g.__sceneEventPeers ??= new Set()
+}
+
+export function registerScenePeer(peer: WsPeer): void {
+  peers().add(peer)
+}
+
+export function unregisterScenePeer(peer: WsPeer): void {
+  peers().delete(peer)
+}
+
+export function sceneEventPeerCount(): number {
+  return peers().size
+}
+
+/** 全员直推(channelId='' 不落库;死连接静默剔除)。
+ *  信封序列化一次、全 peer 复用:dag 遥测经此出口 N 节点×P 页面/秒高频扇出,
+ *  per-peer 重复 stringify 是纯浪费。 */
+export function broadcastSceneEvent(type: string, payload: unknown): void {
+  if (peers().size === 0) return
+  const e: AepEnvelope = {
+    v: AEP_VERSION,
+    type,
+    seq: 0,
+    at: new Date().toISOString(),
+    channelId: '',
+    payload: payload as AepEnvelope['payload'],
+  }
+  const frame = JSON.stringify(e)
+  for (const peer of peers()) {
+    try {
+      peer.send(frame)
+    }
+    catch {
+      peers().delete(peer)
+    }
+  }
+}

package/server/services/workshop/types/a2a.ts

@@ -0,0 +1,61 @@
+/**
+ * A2A(Agent-to-Agent)数据模型 — L1 数据层。
+ * 定义 Channel 内 Agent 间通信消息、任务成果与错误的统一类型。
+ * 仅类型定义,无运行时逻辑;供 workspace 内持久化层(db)、运行时层(runtime)与 impl 层共同消费。
+ * 权威契约见 docs/superpowers/plans/2026-08-13-agent-workshop-multi-agent.md 核心契约块。
+ */
+
+/** A2A 消息内容片段:四种变体(text/data/url/raw),判别键分别为 text/data/url/raw */
+export type Part
+  = | { text: string, mediaType?: string, metadata?: Record<string, unknown> }
+    | { data: unknown, mediaType?: string, metadata?: Record<string, unknown> }
+    | { url: string, mediaType?: string, filename?: string, metadata?: Record<string, unknown> }
+    | { raw: string, mediaType?: string, filename?: string, metadata?: Record<string, unknown> }
+
+/** A2A 消息:Channel 内 Agent 点对点通信与平台任务投递的统一载体 */
+export interface A2AMessage {
+  messageId: string
+  contextId: string
+  taskId?: string
+  role: 'ROLE_USER' | 'ROLE_AGENT'
+  parts: Part[]
+  metadata?: Record<string, unknown>
+  extensions?: string[]
+  referenceTaskIds?: string[]
+}
+
+/**
+ * 渠道邮件视图:带路由/投递元信息的 A2A 消息。
+ * messages 表行的公开投影;lead 全览、调度快照与 REST/MCP 出口共用,
+ * 携带 from/to/state/time(纯 A2AMessage 只承载 parts,路由信息在 metadata,不适合作观察面)。
+ */
+export interface ChannelMail {
+  messageId: string
+  /** 关联任务(assign/cancel 等任务消息才有) */
+  taskId: string | null
+  fromAgentId: string | null
+  toAgentId: string | null
+  role: 'ROLE_USER' | 'ROLE_AGENT'
+  parts: Part[]
+  metadata: Record<string, unknown>
+  /** 投递状态:pending=未消费 / consuming=消费中 / consumed=已消费 */
+  state: 'pending' | 'consuming' | 'consumed'
+  createdAt: string
+  consumedAt: string | null
+}
+
+/** A2A 成果:任务作业产出的内容集合 */
+export interface A2AArtifact {
+  artifactId: string
+  name?: string
+  description?: string
+  parts: Part[]
+  metadata?: Record<string, unknown>
+}
+
+/** A2A 错误:统一错误语义(code + message + 可选附加数据) */
+export interface A2AError {
+  code: string
+  message: string
+  data?: unknown
+}

package/server/services/workshop/types/task.ts

@@ -0,0 +1,85 @@
+/**
+ * 任务对象模型 — L1 数据层。
+ * 定义任务状态机与任务实体的统一类型(一等公民)。
+ * 仅类型定义,无运行时逻辑;供 task engine、repo 与 impl 层共同消费。
+ * 权威契约见 docs/superpowers/plans/2026-08-13-agent-workshop-multi-agent.md 核心契约块。
+ */
+import type { A2AArtifact, A2AMessage } from './a2a'
+
+/** 任务状态机:终态为 COMPLETED / FAILED / CANCELED */
+export type TaskState
+  = | 'SUBMITTED'
+    | 'ASSIGNED'
+    | 'WORKING'
+    | 'WAITING'
+    | 'COMPLETED'
+    | 'FAILED'
+    | 'CANCELED'
+
+/** 工作区任务:主理人编排与下属执行的最小作业单元 */
+export interface WorkspaceTask {
+  id: string
+  channelId: string
+  /** 子任务挂主任务(主理人分解) */
+  parentId?: string
+  /** 当前负责 Agent */
+  assigneeId: string
+  /** 创建者(lead / 用户) */
+  creatorId: string
+  title: string
+  description?: string
+  state: TaskState
+  /** 0-100,由 Agent 事件驱动 */
+  progress: number
+  retryCount: number
+  /** 作业成果 */
+  artifacts: A2AArtifact[]
+  /** 执行过程(消息/上报) */
+  history: A2AMessage[]
+  /** 派发路由理由(koda RouteDecision 借鉴):lead 留痕"为什么派给他" */
+  routeReason?: string
+  createdAt: string
+  updatedAt: string
+}
+
+/** 终态判定(COMPLETED / FAILED / CANCELED);membership:TERMINAL_TASK_STATES[state] */
+export const TERMINAL_TASK_STATES: Partial<Record<TaskState, true>> = {
+  COMPLETED: true,
+  FAILED: true,
+  CANCELED: true,
+}
+
+/**
+ * 单 Agent 任务队列视图(每个 AgentRuntime 自己的任务管理系统)。
+ * DB tasks 表是唯一事实源;本视图为派生只读投影,不持有第二份状态:
+ *  - queued:待执行队列(FIFO,createdAt ASC;含 SUBMITTED/ASSIGNED)
+ *  - current:执行中任务(WORKING;空闲时 undefined)
+ *  - completed:已完成任务(COMPLETED)
+ *  WAITING(已分解等待子任务)不计入 queued——它由子任务推进,不由本 agent 主动执行。
+ */
+export interface AgentTaskQueueView {
+  agentId: string
+  channelId: string
+  queued: WorkspaceTask[]
+  current?: WorkspaceTask
+  completed: WorkspaceTask[]
+}
+
+/** Agent 实时状态视图(状态管理机制:idle/busy/stopped + 队列上下文) */
+export interface AgentStatusView {
+  agentId: string
+  channelId: string
+  role: 'lead' | 'worker'
+  name: string
+  state: 'idle' | 'busy' | 'stopped'
+  /** 执行中的任务 id(空闲时 null) */
+  currentTaskId: string | null
+  /** 执行中任务的标题(空闲时 null;lead 观察 worker 在干什么,不必去翻任务表) */
+  currentTaskTitle: string | null
+  /** 执行中任务的进度 0-100(空闲/未上报进度时 null;lead 据此判断 worker 是否在推进) */
+  currentTaskProgress: number | null
+  /** 待执行队列长度(实时) */
+  queuedCount: number
+  /** 已完成任务数 */
+  completedCount: number
+}

package/server/types/user.ts

@@ -0,0 +1,53 @@
+import type { z } from 'zod'
+import type { userCreateSchema, userListQuerySchema } from '../schemas/user.schema'
+
+/** 用户实体（存储层领域模型，不含密码哈希——密码只进不出） */
+export interface User extends z.infer<typeof userCreateSchema> {
+  id: string
+  createdAt: string
+}
+
+/** 分页结果 */
+export interface Paginated<T> {
+  items: T[]
+  total: number
+  page: number
+  pageSize: number
+}
+
+/** 用户列表查询（service 入参；pageSize 缺省时由 config.yml 驱动默认值） */
+export type UserListInput = z.infer<typeof userListQuerySchema>
+
+/** 用户列表查询（repository 入参；pageSize 已由 service 解析为确定值） */
+export interface UserListQuery {
+  page: number
+  pageSize: number
+  keyword?: string
+}
+
+/** API Token（每用户多个；列表仅含掩码 preview，明文经 reveal 接口按需获取） */
+export interface UserToken {
+  id: string
+  userId: string
+  label: string
+  createdAt: string
+  lastUsedAt: string | null
+  /** 掩码预览（前 6 后 4）；旧 token 未存档明文时为 null */
+  preview: string | null
+  /** 是否可随时查看明文（旧数据仅存哈希 → false） */
+  hasPlain: boolean
+}
+
+/** 登录/注册成功载荷（token 明文仅此处一次性返回） */
+export interface AuthResult {
+  user: {
+    id: string
+    name: string
+    email: string
+    role: string
+    createdAt: string
+  }
+  token: string
+}
+
+export type { UserCreate } from '../schemas/user.schema'

package/server/utils/approval-gate.ts

@@ -0,0 +1,67 @@
+/**
+ * R3:高危管理操作双人复核闸门(maker-checker)。
+ *
+ * approvalGate 关闭(config.yml security.approvalGate,默认关)→ 直接放行,零开销;
+ * 开启后:首次调用创建待审记录(pending)返回 { pending: true },
+ * 另一 admin 经 POST /api/workshop/approvals/:id/decide 批准(申请人≠批核人硬校验),
+ * 申请人再携 approvalId 重放原请求 → 校验匹配且未消费 → 一次性核销放行。
+ * 全程经 audit() 留痕(与 R1 统一审计视图)。
+ */
+import { randomUUID } from 'node:crypto'
+import { AppError } from './errors'
+import { audit, getOps } from '../services/workshop/ops/ops'
+import type { ResolvedUser } from '../api/workshop/caller'
+
+/** 闸门主体:动作 + 目标(与 approval_requests 表的 action/target_id 对齐) */
+export interface GateSubject {
+  action: string
+  targetId: string
+  summary: string
+}
+
+export type GateVerdict = { pending: true, requestId: string } | { pending: false }
+
+/** 高危操作闸门:返回 pending = true 时端点应 202 短路返回;否则继续执行原逻辑 */
+export function gateDangerous(
+  approvalGate: boolean,
+  user: ResolvedUser,
+  subject: GateSubject,
+  approvalId?: string,
+): GateVerdict {
+  const repo = getOps()?.approvalRequests
+  if (!approvalGate || !repo) return { pending: false }
+
+  // 重放路径:携批准记录放行
+  if (approvalId) {
+    const req = repo.get(approvalId)
+    if (!req || req.action !== subject.action || req.targetId !== subject.targetId) {
+      throw new AppError(400, 'APPROVAL_INVALID', '复核记录不存在或与本次操作不匹配')
+    }
+    if (req.status !== 'approved') {
+      throw new AppError(403, 'APPROVAL_NOT_APPROVED', '复核尚未批准(或已被拒绝)')
+    }
+    if (req.requestedBy !== user.id) {
+      throw new AppError(403, 'APPROVAL_REQUESTER_MISMATCH', '仅申请人本人可携批准记录重放操作')
+    }
+    if (!repo.consume(approvalId)) {
+      throw new AppError(409, 'APPROVAL_CONSUMED', '该批准记录已被使用(一次性核销)')
+    }
+    audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: `${subject.action}.approved-exec`, targetKind: 'approval-request', targetId: approvalId, detail: { targetId: subject.targetId } })
+    return { pending: false }
+  }
+
+  // 首次路径:创建待审记录
+  const id = `ar-${randomUUID().slice(0, 8)}`
+  repo.request({
+    id,
+    action: subject.action,
+    targetId: subject.targetId,
+    payload: {},
+    summary: subject.summary,
+    byUserId: user.id,
+    byName: user.name,
+    at: new Date().toISOString(),
+  })
+  audit({ actor: user.id, actorName: user.name, actorKind: 'user', action: `${subject.action}.request`, targetKind: 'approval-request', targetId: id, detail: { targetId: subject.targetId } })
+  return { pending: true, requestId: id }
+}

package/server/utils/auth.ts

@@ -0,0 +1,13 @@
+import { getRequestHeader } from 'h3'
+import type { H3Event } from 'h3'
+import { AppError } from './errors'
+
+/** 从 Authorization: Bearer <token> 提取 token；缺失 → 401 */
+export function extractBearerToken(event: H3Event): string {
+  const auth = getRequestHeader(event, 'authorization')
+  const token = auth?.match(/^Bearer\s+(.+)$/i)?.[1]?.trim()
+  if (!token) {
+    throw new AppError(401, 'UNAUTHORIZED', '需要有效的 token(Authorization: Bearer <token>)')
+  }
+  return token
+}

package/server/utils/config.ts

@@ -0,0 +1,40 @@
+import { useRuntimeConfig } from '#imports'
+
+/**
+ * 服务端配置读取 —— 与前端同源（config.yml -> nuxt.config runtimeConfig -> useRuntimeConfig）
+ * 前端对应 useSiteConfig()，两侧看到的配置完全一致，保证「配置一致性」。
+ */
+export function useServerConfig() {
+  const c = useRuntimeConfig()
+
+  return {
+    app: {
+      name: c.public.appName as string,
+      title: c.public.appTitle as string,
+      version: c.public.version as string,
+      description: c.public.description as string,
+      mode: c.public.mode as string,
+    },
+    server: {
+      host: c.public.serverHost as string,
+      devPort: c.public.devPort as number,
+      prodPort: c.public.prodPort as number,
+    },
+    api: {
+      baseURL: c.public.apiBase as string,
+      timeout: c.public.apiTimeout as number,
+      // 服务端专用键（仅 Nitro 可见，同样来自 config.yml -> api）
+      pageSize: c.apiPageSize as number,
+      maxPageSize: c.apiMaxPageSize as number,
+    },
+    theme: {
+      primaryColor: c.public.primaryColor as string,
+      themeMode: c.public.themeMode as 'light' | 'dark',
+    },
+    i18n: {
+      defaultLocale: c.public.defaultLocale as string,
+    },
+  }
+}
+
+export type ServerConfig = ReturnType<typeof useServerConfig>

package/server/utils/errors.ts

@@ -0,0 +1,24 @@
+/**
+ * 统一业务异常
+ * service 层通过抛出 AppError 表达业务失败，由路由层统一转换为响应。
+ */
+export class AppError extends Error {
+  readonly status: number
+  readonly code: string
+
+  constructor(status: number, code: string, message: string) {
+    super(message)
+    this.name = 'AppError'
+    this.status = status
+    this.code = code
+  }
+}
+
+/** 统一错误码枚举 */
+export const ErrorCodes = {
+  BAD_REQUEST: 'BAD_REQUEST',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  INTERNAL: 'INTERNAL_ERROR',
+} as const

package/server/utils/response.ts

@@ -0,0 +1,49 @@
+import { defineEventHandler, H3Error, setResponseStatus, type H3Event } from 'h3'
+import { AppError } from './errors'
+
+/** 统一响应信封 */
+export interface ApiEnvelope<T = unknown> {
+  code: number | string
+  message: string
+  data: T | null
+}
+
+/** 成功响应 */
+export function createSuccess<T>(data: T, message = 'ok'): ApiEnvelope<T> {
+  return { code: 0, message, data }
+}
+
+/**
+ * API 路由统一包装器
+ * - 业务成功 -> { code: 0, message: 'ok', data }
+ * - AppError  -> 对应 HTTP 状态 + 业务错误码
+ * - H3Error（含校验失败）-> 对应 HTTP 状态
+ * - 未捕获异常 -> 500 + INTERNAL_ERROR（并记录日志）
+ */
+export function defineApiHandler<T>(handler: (event: H3Event) => Promise<T> | T) {
+  return defineEventHandler(async (event): Promise<ApiEnvelope<T>> => {
+    try {
+      const data = await handler(event)
+      return createSuccess(data)
+    }
+    catch (error) {
+      if (error instanceof AppError) {
+        setResponseStatus(event, error.status)
+        return { code: error.code, message: error.message, data: null }
+      }
+      if (error instanceof H3Error) {
+        // zValidator 抛出的 AppError 会被 h3 包装为 H3Error，此处还原精确信息
+        const inner = error.data instanceof AppError ? error.data : null
+        setResponseStatus(event, error.statusCode ?? 500)
+        return {
+          code: inner?.code ?? 'REQUEST_ERROR',
+          message: inner?.message || error.message || error.statusMessage || '请求失败',
+          data: null,
+        }
+      }
+      console.error('[api] unhandled error:', error)
+      setResponseStatus(event, 500)
+      return { code: 'INTERNAL_ERROR', message: '服务器内部错误', data: null }
+    }
+  })
+}

package/server/utils/validate.ts

@@ -0,0 +1,19 @@
+import type { ZodType } from 'zod'
+import { AppError, ErrorCodes } from './errors'
+
+/**
+ * 将 Zod schema 包装为 h3 兼容的校验函数
+ * 校验失败抛出 AppError(400)，由 h3 统一包装为 400 响应，错误信息精确到首个字段。
+ */
+export function zValidator<T>(schema: ZodType<T>) {
+  return (data: unknown): T => {
+    const result = schema.safeParse(data)
+    if (!result.success) {
+      const issue = result.error.issues[0]
+      const field = issue?.path.join('.') || '参数'
+      const detail = issue ? `${field}: ${issue.message}` : '参数校验失败'
+      throw new AppError(400, ErrorCodes.VALIDATION_ERROR, detail)
+    }
+    return result.data
+  }
+}

package/shared/config/engine.d.mts

@@ -0,0 +1,41 @@
+// Type declarations for shared/config/engine.mjs (editor/typecheck convenience)
+export interface SettingsDescriptor {
+  key: string
+  type: 'string' | 'number' | 'boolean' | 'color' | 'select'
+  group: string
+  label: string
+  labelKey?: string
+  description?: string
+  applies: 'live' | 'restart'
+  default?: unknown
+  min?: number
+  max?: number
+  options?: string[]
+}
+
+export interface EffectiveConfig {
+  defaults: Record<string, unknown>
+  overrides: Record<string, unknown>
+  envOverrides: Record<string, unknown>
+  effective: Record<string, unknown>
+  sources: Record<string, 'config.yml' | 'runtime' | 'env'>
+  descriptors: SettingsDescriptor[]
+  configPath?: string
+  settingsPath?: string
+}
+
+export function keyPath(key: string): string[]
+export function getPath(obj: unknown, key: string): unknown
+export function setPath(obj: Record<string, unknown>, key: string, value: unknown): boolean
+export function unsetPath(obj: Record<string, unknown>, key: string): boolean
+export function loadDescriptors(): SettingsDescriptor[]
+export function loadDescriptorMap(descriptors?: SettingsDescriptor[]): Record<string, SettingsDescriptor>
+export function coerceValue(desc: SettingsDescriptor, value: unknown): unknown
+export function validateValue(desc: SettingsDescriptor, value: unknown): string[]
+export function validateOverrides(overrides: Record<string, unknown>, descriptors?: SettingsDescriptor[]): { ok: boolean, errors: Record<string, string[]> }
+export function findUp(startDir: string, filename: string): string | null
+export function readSettings(settingsPath: string): Record<string, unknown>
+export function saveSettings(overrides: Record<string, unknown>, settingsPath: string, opts?: { version?: number }): { updatedAt: string, overrides: Record<string, unknown> }
+export function envOverridesFromEnv(env?: NodeJS.ProcessEnv, descriptors?: SettingsDescriptor[], mode?: string): Record<string, unknown>
+export function loadEffective(opts?: { configPath?: string, settingsPath?: string, env?: NodeJS.ProcessEnv, mode?: string }): EffectiveConfig
+export function settingsPathFor(root: string): string