agentworkshop 0.2.1

package/cli/core/context.mjs

@@ -0,0 +1,264 @@
+// ============================================================
+// AgentWorkShop CLI — 运行上下文（Context）
+// ------------------------------------------------------------
+// 职责：运行模式判定（repo 检出 / home 全局安装）、.env 预载、有效配置
+// 加载与写入、nuxt 二进制解析、运行中服务器探测、子进程代理免疫环境。
+// 所有指令共享同一份 ctx。
+//
+// 配置引擎采用"懒加载 + 项目根优先"：
+//   全局安装的 aw 只是启动器，配置引擎从 <项目根 或 本包>/shared/config/engine.mjs
+//   动态加载（js-yaml 由对应 node_modules 解析）→ 轻量 npm i -g --omit=dev
+//   无需携带构建依赖；两种模式路径判定统一走 shared/config/home.mjs。
+// ============================================================
+import { existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { createRequire } from 'node:module'
+import { homedir } from 'node:os'
+import { awHome, ensureDataDir, findRepoRoot, resolveRunMode } from '../../shared/config/home.mjs'
+
+export const EXIT = { OK: 0, ERROR: 1, USAGE: 2 }
+
+/** 预载 .env（不覆盖已存在的环境变量） */
+export function preloadDotEnv(root) {
+  const envPath = join(root, '.env')
+  if (!existsSync(envPath)) return false
+  for (const line of readFileSync(envPath, 'utf8').split(/\r?\n/)) {
+    const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/)
+    if (!m || line.trim().startsWith('#')) continue
+    let val = m[2] ?? ''
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith('\'') && val.endsWith('\''))) val = val.slice(1, -1)
+    if (process.env[m[1]] === undefined) process.env[m[1]] = val
+  }
+  return true
+}
+
+/** 探测项目检出根：--root 显式 > cwd 向上找（config.yml + nuxt.config.ts） */
+export function detectProjectRoot({ cwd, explicitRoot } = {}) {
+  if (explicitRoot) {
+    const abs = resolve(cwd, explicitRoot)
+    return existsSync(join(abs, 'config.yml')) ? abs : null
+  }
+  return findRepoRoot(cwd)
+}
+
+/** 解析 nuxt CLI 入口（项目 node_modules 优先，退回本包） */
+export function resolveNuxtBin(projectRoot, packageRoot) {
+  const candidates = [projectRoot, packageRoot].filter(Boolean)
+  for (const base of candidates) {
+    try {
+      const req = createRequire(join(base, 'package.json'))
+      const pkg = req.resolve('nuxt/package.json')
+      const bin = pkg.replace(/package\.json$/, 'bin/nuxt.mjs')
+      if (existsSync(bin)) return bin
+    }
+    catch { /* 继续尝试 */ }
+  }
+  return null
+}
+
+/**
+ * 加载共享配置引擎：运行根（repo 检出 / 本包）优先，回退本包副本。
+ * 全部失败抛出带指引的错误。
+ */
+async function loadEngine(runRoot, packageRoot) {
+  const candidates = [
+    ...(runRoot ? [join(runRoot, 'shared', 'config', 'engine.mjs')] : []),
+    join(packageRoot, 'shared', 'config', 'engine.mjs'),
+  ]
+  let lastErr
+  for (const p of candidates) {
+    if (!existsSync(p)) continue
+    try {
+      return await import(pathToFileURL(p).href)
+    }
+    catch (err) {
+      lastErr = err
+    }
+  }
+  throw new Error(
+    `无法加载配置引擎(尝试过: ${candidates.join(' , ')})${lastErr ? `\n原因: ${lastErr.message}` : ''}`,
+  )
+}
+
+/**
+ * 项目经验：本机系统代理(如 7890)会拦截 localhost 回环请求。
+ * aw 启动的所有子进程统一注入 NO_PROXY/no_proxy，免疫代理劫持。
+ */
+export function localBypassEnv(extra = {}) {
+  const hosts = ['localhost', '127.0.0.1', '::1']
+  const env = { ...process.env, ...extra }
+  for (const key of ['NO_PROXY', 'no_proxy']) {
+    const parts = new Set(String(env[key] ?? '').split(',').map(s => s.trim()).filter(Boolean))
+    for (const h of hosts) parts.add(h)
+    env[key] = [...parts].join(',')
+  }
+  return env
+}
+
+/**
+ * 创建指令运行上下文。
+ * @returns {{
+ *   cwd, root, mode: 'repo'|'home', home, packageRoot, homeDir, isProject, json, debug,
+ *   config: { load(), save(), set(), unset(), reset(), validate() },   // 目标=repo 配置 ?? home 配置
+ *   configRoot, configPath, settingsPath, dataDir,
+ *   env: process.env, resolveNuxtBin(), registry, bypassEnv(extra), EXIT
+ * }}
+ */
+export async function createContext({ cwd = process.cwd(), explicitRoot, json = false, debug = false, registry } = {}) {
+  const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..')
+  const homeDir = homedir()
+  const root = detectProjectRoot({ cwd, explicitRoot })
+  const mode = root ? 'repo' : 'home'
+  const home = awHome(process.env)
+  const isProject = Boolean(root)
+
+  // 自定义命令目录：项目级(仅 repo 模式,与 prompts 外置约定同目录) + 用户级(=AW Home)
+  const localCommands = root ? join(root, '.AgentWorkShop', 'commands') : null
+  const globalCommands = join(home, 'commands')
+  for (const dir of [localCommands, globalCommands].filter(Boolean)) {
+    mkdirSync(dir, { recursive: true })
+  }
+
+  // 路径判定（单一入口）：repo 模式配置/数据在 <repo>/.AgentWorkShop;home 在 ~/.AgentWorkShop
+  const paths = resolveRunMode({ cwd, packageRoot, env: process.env })
+  // 显式 --root 时尊重显式值
+  if (explicitRoot && root) {
+    paths.configRoot = join(root, '.AgentWorkShop')
+    paths.configPath = join(root, 'config.yml')
+    paths.settingsPath = join(paths.configRoot, 'runtime-settings.json')
+    paths.dataDir = join(paths.configRoot, 'data')
+  }
+  // repo 模式:确保配置根数据目录 + 旧位置(cwd/data 等)迁移(幂等,与服务端同规则)
+  if (root) {
+    ensureDataDir(root)
+    paths.dataDir = join(paths.configRoot, 'data')
+  }
+
+  // 配置引擎（懒加载,运行根优先）+ 有效配置 API
+  const engine = await loadEngine(root ?? packageRoot, packageRoot)
+  const config = createConfigApi(paths, { engine, env: process.env })
+
+  return {
+    cwd,
+    root,
+    mode,
+    home,
+    packageRoot,
+    homeDir,
+    isProject,
+    json,
+    debug,
+    env: process.env,
+    commandsDir: { local: localCommands, global: globalCommands },
+    configRoot: paths.configRoot,
+    configPath: paths.configPath,
+    settingsPath: paths.settingsPath,
+    dataDir: paths.dataDir,
+    config,
+    registry,
+    resolveNuxtBin: () => resolveNuxtBin(root, packageRoot),
+    bypassEnv: localBypassEnv,
+    EXIT,
+  }
+}
+
+/**
+ * 配置操作 API（加载 / 保存 / 设置 / 移除 / 校验），基于共享引擎实例。
+ * @param {{configPath, settingsPath, dataDir, mode}} paths resolveRunMode 的结果
+ */
+export function createConfigApi(paths, { engine, env = process.env } = {}) {
+  const { configPath, settingsPath } = paths
+
+  const load = () => engine.loadEffective({ configPath, settingsPath, env })
+
+  const guard = () => {
+    if (!configPath || !existsSync(configPath))
+      throw new Error(`未找到配置 ${configPath} —— 请先运行 aw home 完成初始化，或 cd 到项目目录`)
+  }
+
+  return {
+    root: paths.mode === 'repo' ? paths.root : null,
+    mode: paths.mode,
+    load,
+    save(overrides) {
+      guard()
+      engine.saveSettings(overrides, settingsPath)
+    },
+    /** 设置单个键：校验 + 写入 overrides + 持久化。返回 { key, value, applies, ... } */
+    set(key, rawValue) {
+      guard()
+      const { descriptors, overrides, effective, sources } = load()
+      const map = Object.fromEntries(descriptors.map(d => [d.key, d]))
+      const desc = map[key]
+      if (!desc) throw new Error(`未知设置项 "${key}"（可用 aw config list 查看全部设置项）`)
+      const coerced = engine.coerceValue(desc, rawValue)
+      if (coerced === null) throw new Error(`无法把 "${rawValue}" 转为 ${desc.type} 类型`)
+      const errs = engine.validateValue(desc, coerced)
+      if (errs.length) throw new Error(`${desc.label} ${errs.join('，')}`)
+      const next = { ...overrides, [key]: coerced }
+      this.save(next)
+      return { key, value: coerced, source: 'runtime', applies: desc.applies, previousSource: sources[key], effectiveBefore: effective[key] }
+    },
+    /** 移除某个覆盖（回落到 config.yml 默认） */
+    unset(key) {
+      guard()
+      const { overrides } = load()
+      if (!(key in overrides)) return { key, removed: false }
+      const next = { ...overrides }
+      delete next[key]
+      this.save(next)
+      return { key, removed: true }
+    },
+    /** 清空全部覆盖 */
+    reset() {
+      guard()
+      this.save({})
+    },
+    validate() {
+      guard()
+      const { descriptors, overrides, defaults } = load()
+      const result = { ok: true, keys: {}, overridesChecked: 0 }
+      for (const desc of descriptors) {
+        const val = engine.getPath(defaults, desc.key)
+        if (val === undefined) continue
+        const errs = engine.validateValue(desc, val)
+        if (errs.length) {
+          result.ok = false
+          result.keys[desc.key] = [...(result.keys[desc.key] ?? []), ...errs.map(e => `config.yml: ${e}`)]
+        }
+      }
+      const ov = engine.validateOverrides(overrides, descriptors)
+      result.overridesChecked = Object.keys(overrides).length
+      if (!ov.ok) {
+        result.ok = false
+        for (const [k, e] of Object.entries(ov.errors)) result.keys[k] = [...(result.keys[k] ?? []), ...e.map(x => `runtime: ${x}`)]
+      }
+      return result
+    },
+  }
+}
+
+/**
+ * 探测正在运行的服务器（dev 优先，其次 prod），返回其 API 基址或 null。
+ * 探活语义：拿到**任何** HTTP 响应（含 401 —— /api/system/config 需鉴权）
+ * 即证明端口有服务在听；只有网络层失败才算离线。
+ */
+export async function findRunningServer(config, { timeoutMs = 400 } = {}) {
+  if (!config?.load) return null
+  const eff = config.load().effective
+  const host = String(eff['server.host'] ?? '127.0.0.1').replace(/^0\.0\.0\.0$/, '127.0.0.1')
+  const ports = [eff['server.dev.port'], eff['server.prod.port']].filter(p => p != null)
+  for (const port of ports) {
+    const url = `http://${host}:${port}/api/system/config`
+    try {
+      const ctl = new AbortController()
+      const timer = setTimeout(() => ctl.abort(), timeoutMs)
+      await fetch(url, { method: 'GET', signal: ctl.signal })
+      clearTimeout(timer)
+      return { port, base: url.replace(/\/config$/, '') }
+    }
+    catch { /* 端口未起服务，继续 */ }
+  }
+  return null
+}

package/cli/core/errors.mjs

@@ -0,0 +1,18 @@
+// ============================================================
+// AgentWorkShop CLI — 错误类型（独立模块,避免 commands → aw.mjs 循环依赖）
+// ------------------------------------------------------------
+// code: 'USAGE'(退出码 2,用法错误) | 其他(退出码 1,运行错误)
+// ============================================================
+export class CliError extends Error {
+  constructor(code, message) {
+    super(message)
+    this.name = 'CliError'
+    this.code = code
+  }
+}
+
+export function isUsageError(err) {
+  return err instanceof CliError && err.code === 'USAGE'
+}
+
+export default CliError

package/cli/core/help.mjs

@@ -0,0 +1,68 @@
+// ============================================================
+// AgentWorkShop CLI — 帮助渲染（自动由注册表 meta 生成）
+// ============================================================
+import { join } from 'node:path'
+import { color } from './logger.mjs'
+
+export function renderHelp({ registry, root, version }) {
+  const lines = []
+  lines.push('')
+  lines.push(`${color.bold('AgentWorkShop CLI')}${version ? color.dim(` v${version}`) : ''} — 配置驱动 · 指令系统`)
+  lines.push('')
+  lines.push(color.dim('用法:') + `  aw ${color.cyan('<command>')} [options] [args]`)
+  lines.push(`${color.dim('      agentworkshop <command> [options] [args]   (别名)')}`)
+  lines.push('')
+  if (root) {
+    lines.push(color.dim('项目根:') + `  ${root}  ${color.green('✓')}  ${color.dim('(repo 模式:配置/数据在项目内)')}`)
+  }
+  else {
+    lines.push(`${color.dim('当前目录非项目检出')} → ${color.cyan('home 模式')}${color.dim('(配置/数据在 ~/.AgentWorkShop,任意目录可跑 aw start)')}`)
+    lines.push(color.dim('  要开发/调试检出内的项目:') + `  cd <项目> 后运行;  ${color.cyan('aw home')} 查看/初始化配置中枢`)
+  }
+  lines.push('')
+
+  for (const [group, cmds] of registry.groups()) {
+    lines.push(color.bold(`  ${group}`))
+    for (const { meta } of cmds) {
+      const aliases = meta.aliases?.length ? color.dim(`  (${meta.aliases.join(', ')})`) : ''
+      lines.push(`    ${color.cyan(meta.name.padEnd(9))} ${meta.summary ?? ''}${aliases}`)
+    }
+    lines.push('')
+  }
+
+  lines.push(color.bold('  全局参数'))
+  lines.push('    --help, -h        显示帮助 / 指定命令的帮助')
+  lines.push('    --version, -v     显示版本')
+  lines.push('    --json            机器可读输出（config/status 等支持）')
+  lines.push('    --root <dir>      指定项目根（默认向上查找 config.yml）')
+  lines.push('    --debug           调试日志')
+  lines.push('')
+  lines.push(color.dim('设置优先级:') + '  config.yml 默认 < data/runtime-settings.json 运行时覆盖 < 环境变量 / CLI 参数')
+  lines.push(color.dim('指令注册:') + '    内建(随包) + 用户 ~/.agentworkshop/commands + 项目 .agentworkshop/commands（同名的后者覆盖前者）')
+  lines.push(color.dim('新指令:') + `        ${color.cyan('aw register <path|url|npm:pkg>')}  或直接放入上述目录(导出 {meta, run})`)
+  lines.push('')
+  return lines.join('\n')
+}
+
+export function renderCommandHelp(registry, name) {
+  const cmd = registry.find(name)
+  if (!cmd) return null
+  const { meta } = cmd
+  const source = typeof cmd.source === 'string'
+    ? (cmd.source.includes(join('cli', 'commands')) ? '内建' : cmd.source)
+    : '未知'
+  const lines = []
+  lines.push('')
+  lines.push(`${color.cyan(meta.name)} — ${meta.summary ?? ''}  ${color.dim(`(群组: ${meta.group}, 来源: ${source})`)}`)
+  if (meta.usage) lines.push(`  ${color.dim('用法:')} ${color.bold(meta.usage)}`)
+  if (meta.aliases?.length) lines.push(`  ${color.dim('别名:')} ${meta.aliases.join(', ')}`)
+  if (meta.description) {
+    lines.push('')
+    if (typeof meta.description === 'string') lines.push(`  ${meta.description}`)
+    else if (Array.isArray(meta.description)) lines.push(...meta.description.map(l => `  ${l}`))
+  }
+  lines.push('')
+  return lines.join('\n')
+}
+
+export default renderHelp

package/cli/core/logger.mjs

@@ -0,0 +1,40 @@
+// ============================================================
+// AgentWorkShop CLI — logger（轻量彩色日志；无第三方依赖）
+// ============================================================
+const NO_COLOR = process.env.NO_COLOR !== undefined || !process.stdout.isTTY || process.env.TERM === 'dumb'
+
+const c = n => s => (NO_COLOR ? s : `\u001b[${n}m${s}\u001b[0m`)
+export const color = {
+  bold: c(1),
+  dim: c(2),
+  red: c(31),
+  green: c(32),
+  yellow: c(33),
+  blue: c(34),
+  magenta: c(35),
+  cyan: c(36),
+  grey: c(90),
+}
+
+export const logger = {
+  info(...args) { console.log(...args) },
+  ok(...args) { console.log(`${color.green('✔')} ${args.join(' ')}`) },
+  warn(...args) { console.log(`${color.yellow('⚠')} ${args.join(' ')}`) },
+  error(...args) { console.error(`${color.red('✖')} ${args.join(' ')}`) },
+  step(...args) { console.log(`${color.cyan('›')} ${args.join(' ')}`) },
+  debug(...args) { if (process.env.AW_DEBUG) console.log(`${color.grey('[debug]')}`, ...args) },
+  table(rows) {
+    if (!rows.length) return
+    const width = i => Math.max(...rows.map(r => String(r[i] ?? '').length))
+    const pads = [0, 1, 2].map((i, idx) => idx === 0 ? width(0) : width(idx))
+    for (const r of rows) {
+      console.log(
+        `  ${String(r[0] ?? '').padEnd(pads[0])}  `
+        + `${color.grey(String(r[1] ?? '').padEnd(pads[1]))}  `
+        + `${String(r[2] ?? '')}`,
+      )
+    }
+  },
+}
+
+export default logger

package/cli/core/registry.mjs

@@ -0,0 +1,111 @@
+// ============================================================
+// AgentWorkShop CLI — 指令注册表（Command Registry）
+// ------------------------------------------------------------
+// 指令注册机制（三层扫描，同名后扫描者覆盖 → 项目级 > 用户级 > 内建）：
+//   1. 内建指令   ：<packageRoot>/cli/commands/*.mjs（随包发布，永远存在）
+//   2. 用户级指令 ：~/.agentworkshop/commands/*.mjs（经 aw register --global 注册）
+//   3. 项目级指令 ：<projectRoot>/.agentworkshop/commands/*.mjs（经 aw register 注册）
+// 任何 .mjs 文件只需导出 { meta, run } 即自动成为一条指令：
+//   export const meta = { name, summary, usage, group, aliases?, needsProject? }
+//   export async function run(argv, ctx) { ... }
+// 这是「约定优于配置」的注册模型：放文件即注册，无需任何登记的集中式清单。
+// ============================================================
+import { readdirSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export class CommandRegistry {
+  constructor({ dirs = [] } = {}) {
+    this.dirs = dirs
+    this.commands = new Map() // name → { meta, run, source }
+    this.aliases = new Map() // alias → name
+    this.failures = [] // 扫描失败的模块（不阻断其他指令）
+  }
+
+  /** 注册一个命令模块（meta + run） */
+  register(mod, source = 'builtin') {
+    if (!mod?.meta?.name || typeof mod.run !== 'function') {
+      this.failures.push({ source, error: '模块缺少 meta.name 或 run()' })
+      return false
+    }
+    const meta = { ...mod.meta, group: mod.meta.group ?? 'other' }
+    this.commands.set(meta.name, { meta, run: mod.run, source })
+    for (const alias of meta.aliases ?? []) this.aliases.set(alias, meta.name)
+    return true
+  }
+
+  /** 从单个文件注册（动态 import） */
+  async registerFile(file) {
+    const url = pathToFileURL(file).href
+    try {
+      const mod = await import(url)
+      const candidate = mod.default?.meta && typeof mod.default.run === 'function' ? mod.default : mod
+      if (this.register(candidate, file)) return true
+    }
+    catch (err) {
+      this.failures.push({ source: file, error: String(err?.message ?? err) })
+    }
+    return false
+  }
+
+  /** 扫描一批目录下的可执行命令文件（*.mjs / *.js / *.cjs） */
+  async scanDirs(dirs) {
+    for (const dir of dirs) {
+      let entries
+      try {
+        entries = readdirSync(dir)
+      }
+      catch {
+        continue // 目录不存在 → 跳过
+      }
+      const files = entries
+        .filter(name => /\.(mjs|js|cjs)$/.test(name) && !name.startsWith('_'))
+        .map(name => join(dir, name))
+        .filter((path) => {
+          try {
+            return statSync(path).isFile()
+          }
+          catch {
+            return false // 失效符号链接等,跳过不阻断
+          }
+        })
+      for (const file of files) {
+        await this.registerFile(file)
+      }
+    }
+  }
+
+  /** 查找指令（名字或别名） */
+  find(name) {
+    return this.commands.get(name) ?? this.commands.get(this.aliases.get(name))
+  }
+
+  has(name) {
+    return this.find(name) !== undefined
+  }
+
+  /** 全量指令（含别名信息），可按 group 分组 */
+  list() {
+    return [...this.commands.values()]
+  }
+
+  groups() {
+    const out = new Map()
+    for (const cmd of this.list()) {
+      if (!out.has(cmd.meta.group)) out.set(cmd.meta.group, [])
+      out.get(cmd.meta.group).push(cmd)
+    }
+    return out
+  }
+}
+
+/** 拼接指令扫描目录清单（内建 → 用户级 → 项目级;配合同名后者覆盖,项目级优先级最高） */
+export function commandDirs({ packageRoot, projectRoot, homeDir }) {
+  const dirs = []
+  if (packageRoot) dirs.push(join(packageRoot, 'cli', 'commands'))
+  if (homeDir) dirs.push(join(homeDir, '.agentworkshop', 'commands'))
+  if (projectRoot) dirs.push(join(projectRoot, '.agentworkshop', 'commands'))
+  return dirs
+}
+
+export default CommandRegistry

package/config.yml

@@ -0,0 +1,70 @@
+# ============================================================
+# AgentWorkShop 运行配置 —— 单一事实来源（Single Source of Truth）
+# ------------------------------------------------------------
+# 本文件由 nuxt.config.ts（构建/开发期）与 scripts/start.mjs（生产启动期）
+# 读取并解析，驱动整个运行时。修改后重启对应模式即可生效：
+#   开发：pnpm dev     -> 读取 server.dev
+#   生产：pnpm start   -> 读取 server.prod
+# ============================================================
+
+app:
+  name: AgentWorkShop
+  title: AgentWorkShop
+  version: 0.2.0
+  description: 基于 Nuxt 4 的配置驱动运行范式
+
+# 运行模式（dev/prod 实际由启动命令决定，此处仅作运行时展示）
+mode: dev
+
+# ------------------------------------------------------------
+# 服务端口：dev 与 prod 可分别自定义
+# ------------------------------------------------------------
+server:
+  host: 0.0.0.0
+  dev:
+    port: 3000
+  prod:
+    port: 3001
+
+# 后端 API（前端 axios 基址 + 服务端行为均由本段驱动）
+api:
+  baseURL: /api
+  timeout: 15000
+  pageSize: 20      # 服务端默认分页大小
+  maxPageSize: 100  # 服务端分页大小上限
+
+# 国际化
+i18n:
+  defaultLocale: zh-CN
+  locales:
+    - code: zh-CN
+      name: 简体中文
+    - code: en
+      name: English
+
+# 主题
+theme:
+  # Agent Harness · Digital Twin 控制室色板:品牌绿(交互/确认/DAQ)+ 数据青,见 TownView.vue --hud-*
+  primaryColor: "#35e0a0"
+  mode: light # light | dark
+
+# 安全配置
+# 数据采集基础设施(数采 DAQ;地址与 docker-compose.yml 默认一致)
+# startInfrastructure: never=启动探测,不通且有 Docker 则自动 docker compose 拉起;
+#   always=仅 Docker 拉起;never=只直连。连接失败降级并警告,可前端一键重连。
+daq:
+  startInfrastructure: auto
+  mqtt:
+    host: 127.0.0.1
+    port: 1883
+  timescale:
+    host: 127.0.0.1
+    port: 5432
+    user: postgres
+    password: awshop
+    database: awshop
+
+security:
+  # Session cookie 加密密钥（nuxt-auth-utils 使用）
+  # 生产环境必须修改为强随机值；可用环境变量 NUXT_SESSION_PASSWORD 覆盖
+  sessionPassword: awshop-dev-secret-change-me-0123456789

package/docker-compose.yml

@@ -0,0 +1,34 @@
+# ============================================================
+# AgentWorkShop 数采基础设施(DAQ infrastructure)
+# ------------------------------------------------------------
+# 与 config.yml `daq:` 段默认一致;项目启动时若端口不通且存在 Docker,
+# 服务端自动执行 `docker compose up -d daq-mosquitto daq-timescale`。
+#   - daq-mosquitto:标准 MQTT 3.1.1/5 broker(数采下沉队列)
+#   - daq-timescale:TimescaleDB(时序数据持久化;named volume 常驻)
+# 手动启动:docker compose up -d
+# ============================================================
+services:
+  daq-mosquitto:
+    image: eclipse-mosquitto:2
+    container_name: awshop-daq-mosquitto
+    # no-auth 配置:内网/开发态;生产请挂载自定义 mosquitto.conf 启用鉴权/TLS
+    command: ["mosquitto", "-c", "/mosquitto-no-auth.conf"]
+    ports:
+      - "1883:1883"   # 与 config.yml daq.mqtt.port 一致
+    restart: unless-stopped
+
+  daq-timescale:
+    image: timescale/timescaledb:latest-pg16
+    container_name: awshop-daq-timescale
+    environment:
+      POSTGRES_USER: postgres        # config.yml daq.timescale.user
+      POSTGRES_PASSWORD: awshop      # config.yml daq.timescale.password
+      POSTGRES_DB: awshop            # config.yml daq.timescale.database
+    ports:
+      - "5432:5432"                  # 与 config.yml daq.timescale.port 一致
+    volumes:
+      - awshop-daq-tsdata:/var/lib/postgresql/data
+    restart: unless-stopped
+
+volumes:
+  awshop-daq-tsdata: