agentworkshop 0.2.1

package/app/composables/workshop/useWorkshopWs.ts

@@ -0,0 +1,113 @@
+/**
+ * Workshop WS 会话 hook:绑定 WorkshopWsSession ↔ stores。
+ * ingest 派发:events.ingest + entities.applyEvent + connection 游标;
+ * 订阅引用计数(多组件安全挂载/卸载),30s 心跳。
+ */
+import { onBeforeUnmount, onMounted } from 'vue'
+import { useUserStore } from '../../stores/workshop/user'
+import { WorkshopWsSession, useWsConnectionStore } from '../../stores/workshop/connection'
+import { useEventsStore } from '../../stores/workshop/events'
+import { useEntitiesStore } from '../../stores/workshop/entities'
+import { useTownBus } from './useTownBus'
+import type { AepEnvelope, AepSnapshot } from '#shared/workshop-protocol'
+
+export function useWorkshopWs() {
+  const conn = useWsConnectionStore()
+  const userStore = useUserStore()
+  const events = useEventsStore()
+  const entities = useEntitiesStore()
+  const townBus = useTownBus()
+
+  // 模块级单例:多组件共享一条连接
+  let session: WorkshopWsSession | null = (globalThis as { __workshopWs?: WorkshopWsSession }).__workshopWs ?? null
+  // per-channel 已应用 seq(断线续传重放/缓冲重叠的同帧在此单点丢弃;
+  // entities/场景计数等下游消费方不再各自防重)
+  const appliedSeq = new Map<string, number>()
+  if (!session) {
+    const s = new WorkshopWsSession(
+      (e: AepEnvelope) => {
+        // seq 去重收口:快照重置游标;非快照帧 seq 单调,重复帧直接丢弃
+        if (e.channelId && typeof e.seq === 'number' && e.seq > 0 && e.type !== 'channel.snapshot') {
+          const last = appliedSeq.get(e.channelId) ?? 0
+          if (e.seq <= last) return
+          appliedSeq.set(e.channelId, e.seq)
+          // 重连对齐确认:收到缺口后的新帧(或任意非重复帧)即视为已对齐
+          if (conn.pendingReplay) conn.pendingReplay = false
+        }
+        if (e.type === 'channel.snapshot' && e.channelId) {
+          // 快照 = 实体基线对齐(seq 游标以快照为准,服务重启 seq 倒退由此收敛)
+          appliedSeq.set(e.channelId, typeof e.seq === 'number' ? e.seq : 0)
+          conn.pendingReplay = false
+          events.ingest(e)
+          entities.applyEvent(e)
+          entities.applySnapshot(e.payload as AepSnapshot)
+          // 持久化历史(server 驱动):快照后从 DB 拉历史填充时间线
+          void events.loadHistory(e.channelId)
+        }
+        else {
+          events.ingest(e)
+          entities.applyEvent(e)
+        }
+        if (typeof e.seq === 'number' && e.seq > 0 && e.channelId) {
+          conn.cursors[e.channelId] = e.seq
+          s.updateCursor(e.channelId, e.seq) // 推进重连续传游标
+        }
+        // 旁路广播:小镇场景与时间线拿同一实时事件流(不改既有分发,可注释回退)
+        townBus.emit(e)
+      },
+      (state, retry) => {
+        conn.state = state
+        conn.retryCount = retry
+      },
+      // 断线且有订阅游标 → 重连后待对齐(状态条"同步中"提示)
+      () => { conn.pendingReplay = true },
+      // 重连后首帧到达 → 记录最后数据时间(诚实在线状态);
+      // pendingReplay 的清除由 ingest 的对齐语义决定(快照或非重复帧,而非任意首帧)
+      () => {
+        conn.lastDataAt = Date.now()
+      },
+    )
+    session = s
+    ;(globalThis as { __workshopWs?: WorkshopWsSession }).__workshopWs = session
+  }
+
+  // 用户 token 注入(登录态变化即时生效;未登录 sub 将被服务端 401 拒绝)
+  watch(() => userStore.token, (t) => {
+    if (session instanceof WorkshopWsSession) session.userToken = t
+  }, { immediate: true })
+
+  const subscribe = (channelId: string): void => {
+    // 游标未建立(lastSeq=0/无 ring)时不携带 lastSeq:服务端对其下发
+    // channel.snapshot 全量(agents/tasks/queue/messages 实体基线),否则走纯事件
+    // 重放路径,空闲成员/历史任务永远不会出现在前端(实体基线缺失)。
+    const lastSeq = events.lastSeq(channelId)
+    session?.subscribe(channelId, lastSeq > 0 ? lastSeq : undefined)
+  }
+  const unsubscribe = (channelId: string): void => {
+    if (!session) return
+    session.unsubscribe(channelId)
+    // 引用计数归零才清本地事件缓冲:仍有页面(如总览页)持有订阅时,
+    // 控制台卸载不得把对方的时间线/游标抹掉(清了会导致已订阅会话收不到快照重发,实时流静默死亡)
+    if (session.refCount(channelId) === 0) events.clear(channelId)
+  }
+  /** 建连但不订阅 channel:纯场景事件消费方(daq 实时帧)用。
+   *  服务端在连接层注册 scene peer,连上即收 daq.reading 等无频道广播。 */
+  const ensureConnected = (): void => {
+    session?.ensureConnected()
+  }
+
+  let heartbeat: ReturnType<typeof setInterval> | null = null
+  onMounted(() => {
+    // 15s 心跳:pong 停止后 checkStale 的断线感知最坏 ~20-35s(服务强杀的半开连接
+    // 无 RST,靠 pong 超时发现);ping 发送失败立即关闭走重连,不等 stale 检测
+    heartbeat = setInterval(() => {
+      session?.ping()
+      session?.checkStale()
+    }, 15_000)
+  })
+  onBeforeUnmount(() => {
+    if (heartbeat) clearInterval(heartbeat)
+  })
+
+  return { subscribe, unsubscribe, ensureConnected, conn }
+}

package/app/config/index.ts

@@ -0,0 +1,66 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join } from 'node:path'
+import YAML from 'js-yaml'
+import { appConfigSchema, type AppConfig } from './schema'
+import {
+  envOverridesFromEnv,
+  loadDescriptors,
+  readSettings,
+  setPath,
+  validateValue,
+} from '../../shared/config/engine.mjs'
+import { ensureDataDir, resolveRunMode } from '../../shared/config/home.mjs'
+
+// 配置路径双模式判定（shared/config/home.mjs 单一入口）：
+//   repo 模式（项目检出内构建/开发）→ config.yml 在检出根,运行时覆盖/数据在 <repo>/.AgentWorkShop
+//   home 模式（全局安装载荷构建,AW_MODE=home）→ config.yml/runtime-settings 在 ~/.AgentWorkShop
+// ensureDataDir 同时把旧 <repo>/data/runtime-settings.json 迁入配置根（幂等）
+const packageRoot = fileURLToPath(new URL('../..', import.meta.url))
+const runMode = resolveRunMode({ cwd: process.cwd(), packageRoot, env: process.env })
+const configPath = runMode.configPath
+const settingsPath = process.env.AW_MODE === 'home'
+  ? runMode.settingsPath
+  : join(ensureDataDir(process.cwd(), process.env), '..', 'runtime-settings.json')
+
+let cached: AppConfig | null = null
+
+/**
+ * 把运行时覆盖层合并进 config.yml 原始对象（就地修改）。
+ * 优先级：config.yml < runtime-settings.json < 环境变量(AW_*)。
+ * 每个键都过 schema.json 描述符校验，无效覆盖跳过并告警（不阻断启动）。
+ * 这是 `aw config set` → Web 端真正生效的汇合点：CLI 写 runtime-settings，
+ * 本函数在每次构建/启动时把它叠加到默认值上。
+ */
+function applyRuntimeOverrides(raw: Record<string, unknown>): void {
+  const descriptors = loadDescriptors()
+  const map = new Map(descriptors.map(d => [d.key, d]))
+  const runtime = readSettings(settingsPath)
+  const envOverrides = envOverridesFromEnv(process.env, descriptors)
+  const merged = { ...runtime, ...envOverrides }
+  for (const [key, value] of Object.entries(merged)) {
+    const desc = map.get(key)
+    if (!desc) continue
+    const errs = validateValue(desc, value)
+    if (errs.length) {
+      console.warn(`[config] 忽略无效运行时覆盖 ${key}=${JSON.stringify(value)}: ${errs.join('; ')}`)
+      continue
+    }
+    setPath(raw, key, value)
+  }
+}
+
+/**
+ * 读取并校验 config.yml（叠加运行时覆盖）。结果缓存，整个构建期只解析一次。
+ * 仅在构建期（nuxt.config）调用；应用运行时请使用 useRuntimeConfig().
+ */
+export function loadConfig(): AppConfig {
+  if (cached) return cached
+  const raw = (YAML.load(readFileSync(configPath, 'utf8')) ?? {}) as Record<string, unknown>
+  applyRuntimeOverrides(raw)
+  cached = appConfigSchema.parse(raw)
+  return cached
+}
+
+export { appConfigSchema } from './schema'
+export type { AppConfig } from './schema'

package/app/config/schema.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod'
+
+/**
+ * config.yml 的 Zod 校验模式。
+ * 任何不符合约束的配置都会在构建/启动期 fail-fast，避免错误配置流入运行时。
+ */
+export const appConfigSchema = z.object({
+  app: z.object({
+    name: z.string(),
+    title: z.string(),
+    version: z.string(),
+    description: z.string().optional().default(''),
+  }),
+  mode: z.enum(['dev', 'prod']).default('dev'),
+  server: z.object({
+    host: z.string().default('0.0.0.0'),
+    dev: z.object({
+      port: z.number().int().min(1).max(65535),
+    }),
+    prod: z.object({
+      port: z.number().int().min(1).max(65535),
+    }),
+  }),
+  api: z.object({
+    baseURL: z.string().default('/api'),
+    timeout: z.number().int().positive().default(15000),
+    // 服务端 API 默认分页与上限（config 驱动）
+    pageSize: z.number().int().positive().default(20),
+    maxPageSize: z.number().int().positive().default(100),
+  }),
+  i18n: z.object({
+    defaultLocale: z.string(),
+    locales: z.array(z.object({
+      code: z.string(),
+      name: z.string(),
+    })),
+  }),
+  theme: z.object({
+    primaryColor: z.string().regex(/^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, '须为合法十六进制颜色，如 #1677ff'),
+    mode: z.enum(['light', 'dark']).default('light'),
+  }),
+  security: z.object({
+    sessionPassword: z.string().min(16, 'session 密钥至少 16 位').default(''),
+    // R3:高危管理操作双人复核闸门(默认关;开启后 apply/controller/delete 需另一 admin 批核)
+    approvalGate: z.boolean().default(false),
+  }),
+  daq: z.object({
+    startInfrastructure: z.enum(['auto', 'always', 'never']).default('auto'),
+    mqtt: z.object({
+      host: z.string().default('127.0.0.1'),
+      port: z.number().int().min(1).max(65535).default(1883),
+      // S1:生产 broker 鉴权/TLS(可选项;dev 零配置 no-auth 不受影响;另可整体用 DAQ_MQTT_URL 覆盖)
+      username: z.string().default(''),
+      password: z.string().default(''),
+      secure: z.boolean().default(false), // true → mqtts://(8883 + CA)
+      caFile: z.string().default(''), // 自签 CA 证书路径(mqtts 时建议设置)
+    }),
+    timescale: z.object({
+      host: z.string().default('127.0.0.1'),
+      port: z.number().int().min(1).max(65535).default(5432),
+      user: z.string().default('postgres'),
+      password: z.string().default('awshop'),
+      database: z.string().default('awshop'),
+    }),
+  }).default({ startInfrastructure: 'auto', mqtt: { host: '127.0.0.1', port: 1883 }, timescale: { host: '127.0.0.1', port: 5432, user: 'postgres', password: 'awshop', database: 'awshop' } }),
+})
+
+export type AppConfig = z.infer<typeof appConfigSchema>

package/app/error.vue

@@ -0,0 +1,76 @@
+<script setup lang="ts">
+import type { NuxtError } from '#app'
+
+const props = defineProps<{ error: NuxtError }>()
+
+const { t } = useI18n()
+
+const handleClear = () => clearError({ redirect: '/' })
+
+const is404 = computed(() => props.error?.statusCode === 404)
+</script>
+
+<template>
+  <div class="err-page aw-orbs">
+    <div class="err-card">
+      <div class="aw-kicker">
+        {{ is404 ? 'not found' : 'runtime error' }}
+      </div>
+      <h1 class="err-code aw-display">
+        {{ error?.statusCode ?? 500 }}
+      </h1>
+      <p class="err-message">
+        {{ error?.message ?? t('error.lost') }}
+      </p>
+      <button
+        class="aw-pill err-cta"
+        @click="handleClear"
+      >
+        <span class="i-tabler-arrow-left" />
+        {{ $t('error.backHome') }}
+      </button>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.err-page {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  min-height: 100vh;
+  background: var(--paper);
+}
+
+.err-card {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  align-items: flex-start;
+  max-width: 460px;
+  padding: 40px 44px;
+  background: var(--paper-raised);
+  border: 1px solid var(--line);
+  border-radius: var(--radius-panel);
+}
+
+.err-code {
+  margin: 0;
+  font-size: 72px;
+  line-height: 1;
+  color: var(--ink);
+}
+
+.err-message {
+  margin: 0;
+  font-size: 14px;
+  line-height: 1.6;
+  color: var(--ink-faint);
+  word-break: break-word;
+}
+
+.err-cta {
+  margin-top: 14px;
+}
+</style>

package/app/layouts/default.vue

@@ -0,0 +1,100 @@
+<script setup lang="ts">
+import { theme } from 'ant-design-vue'
+
+// 响应式 token:随 ConfigProvider 算法(亮/暗)自动切换,注入 CSS 变量供布局子组件消费
+const { token } = theme.useToken()
+const site = useSiteConfig()
+</script>
+
+<template>
+  <a-layout class="app-layout">
+    <AppSidebar />
+
+    <a-layout
+      class="app-main"
+      :style="{
+        'background': 'transparent',
+        '--app-bg-container': token?.colorBgContainer,
+        '--app-bg-layout': token?.colorBgLayout,
+        '--app-text': token?.colorText,
+        '--app-text-secondary': token?.colorTextSecondary,
+        '--app-border': token?.colorBorderSecondary,
+        '--app-fill': token?.colorFillQuaternary,
+        '--app-header-h': '56px',
+        '--app-footer-h': '46px',
+      }"
+    >
+      <AppHeader />
+
+      <a-layout-content class="app-content">
+        <slot />
+      </a-layout-content>
+
+      <a-layout-footer
+        class="app-footer"
+        :style="{ color: token?.colorTextSecondary }"
+      >
+        <span class="footer-title aw-serif-accent">{{ site.title }}</span>
+        <span class="sep">/</span>
+        <span>v{{ site.version }}</span>
+        <span class="sep">/</span>
+        <span>mode={{ site.mode }}</span>
+      </a-layout-footer>
+    </a-layout>
+
+    <!-- 全局噪点:抵消数字平面冷感(固定覆盖,不挡交互) -->
+    <span
+      class="aw-noise"
+      aria-hidden="true"
+    />
+  </a-layout>
+</template>
+
+<style scoped>
+.app-layout {
+  min-height: 100vh;
+  background: transparent;
+}
+
+.app-main {
+  position: relative;
+  z-index: 1;
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+.app-content {
+  flex: 1;
+  margin: 12px 16px 0;
+  padding: 2px;
+}
+
+/* 页脚:mono 铭牌行(固定高度,供 harness 页计算视口高度);玻璃收边 */
+.app-footer {
+  background: linear-gradient(0deg, var(--frost-bg), color-mix(in srgb, var(--frost-bg) 60%, transparent));
+  backdrop-filter: var(--aurora-blur);
+  -webkit-backdrop-filter: var(--aurora-blur);
+  border-top: 1px solid var(--glass-line);
+  display: flex;
+  gap: 10px;
+  align-items: center;
+  justify-content: center;
+  height: var(--app-footer-h);
+  padding: 0 50px;
+  font-family: var(--font-mono);
+  font-size: 10.5px;
+  letter-spacing: 0.08em;
+  text-align: center;
+}
+
+.app-footer .sep {
+  color: var(--ink-fainter);
+}
+
+.footer-title {
+  font-size: 13px;
+}
+</style>

package/app/layouts/town.vue

@@ -0,0 +1,16 @@
+<template>
+  <div class="town-layout">
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+/* 全屏小镇布局:/town 页面独占整个视口(无侧栏/顶栏/页脚遮挡) */
+.town-layout {
+  position: fixed;
+  inset: 0;
+  z-index: 10;
+  overflow: hidden;
+  background: #0b0f17;
+}
+</style>