agentworkshop 0.7.24 → 0.7.33

package/app/stores/runtime-config.ts

@@ -26,8 +26,26 @@ export interface SettingsDescriptor {
   options?: string[]
 }
 
+/** 配置分组(服务端权威;前端只按序渲染分区,不自行猜分组) */
+export interface ConfigGroup {
+  id: string
+  label: string
+  labelKey?: string
+  description: string
+  order: number
+  /** 服务端默认折叠态(用户本地展开偏好优先,见设置页 aw.settings.groups) */
+  collapsed: boolean
+  collapsible: boolean
+  icon: string
+  source: 'builtin' | 'user' | 'plugin'
+  plugin?: string
+  /** 组内字段数(服务端实时统计) */
+  fieldCount?: number
+}
+
 interface Snapshot {
   descriptors: SettingsDescriptor[]
+  groups?: ConfigGroup[]
   effective: Record<string, unknown>
   overrides: Record<string, unknown>
   sources: Record<string, string>
@@ -45,6 +63,8 @@ interface SettingsEvent {
 
 export const useRuntimeConfigStore = defineStore('runtime-config', () => {
   const descriptors = ref<SettingsDescriptor[]>([])
+  /** 服务端下发的有序分组(唯一渲染权威);为空时退化为「按描述符出现顺序就地分组」 */
+  const groupsRaw = ref<ConfigGroup[]>([])
   const effective = ref<Record<string, unknown>>({})
   const overrides = ref<Record<string, unknown>>({})
   const sources = ref<Record<string, string>>({})
@@ -53,17 +73,59 @@ export const useRuntimeConfigStore = defineStore('runtime-config', () => {
   const loading = ref(false)
   const lastEvent = ref<SettingsEvent | null>(null)
 
-  // 分组后的设置项（computed：按 schema.json group 保持声明顺序）
-  const groups = computed(() => {
-    const out: Array<{ group: string, items: SettingsDescriptor[] }> = []
+  /**
+   * 渲染用分组(后端驱动):
+   *  - 服务端给了 groups → 完全按它的顺序与元数据(标签/说明/折叠态)渲染;
+   *  - 没给(旧服务端) → 按描述符首次出现顺序就地分组,保证不丢字段。
+   * 两种情况下,描述符引用了分组列表里没有的 id 时自动补一个兜底分组。
+   */
+  const groups = computed<ConfigGroup[]>(() => {
+    const byId = new Map<string, ConfigGroup>()
+    for (const g of groupsRaw.value) byId.set(g.id, g)
+    const items = new Map<string, SettingsDescriptor[]>()
     for (const d of descriptors.value) {
-      const g = out.find(x => x.group === d.group)
-      if (g) g.items.push(d)
-      else out.push({ group: d.group, items: [d] })
+      const gid = d.group || '__ungrouped__'
+      const list = items.get(gid)
+      if (list) list.push(d)
+      else items.set(gid, [d])
     }
-    return out
+    if (!groupsRaw.value.length) {
+      return [...items.entries()].map(([id, list], i) => ({
+        id,
+        label: id,
+        description: '',
+        order: i * 10,
+        collapsed: false,
+        collapsible: true,
+        icon: '',
+        source: 'builtin' as const,
+        fieldCount: list.length,
+      }))
+    }
+    const out = groupsRaw.value.map(g => ({ ...g, fieldCount: g.fieldCount ?? items.get(g.id)?.length ?? 0 }))
+    const known = new Set(out.map(g => g.id))
+    for (const [id, list] of items) {
+      if (known.has(id)) continue
+      out.push({
+        id,
+        label: id === '__ungrouped__' ? '其他' : id,
+        description: '',
+        order: 9999,
+        collapsed: false,
+        collapsible: true,
+        icon: '',
+        source: 'builtin',
+        fieldCount: list.length,
+      })
+    }
+    return out.sort((a, b) => (a.order - b.order) || a.id.localeCompare(b.id))
   })
 
+  /** 某分组内的字段(保持描述符声明顺序) */
+  function fieldsOf(groupId: string): SettingsDescriptor[] {
+    return descriptors.value.filter(d => (d.group || '__ungrouped__') === groupId)
+  }
+
   function sourceOf(key: string): string {
     return sources.value[key] ?? 'config.yml'
   }
@@ -91,6 +153,7 @@ export const useRuntimeConfigStore = defineStore('runtime-config', () => {
 
   function applySnapshot(snap: Snapshot): void {
     descriptors.value = snap.descriptors ?? []
+    groupsRaw.value = snap.groups ?? []
     effective.value = snap.effective ?? {}
     overrides.value = snap.overrides ?? {}
     sources.value = snap.sources ?? {}
@@ -98,6 +161,38 @@ export const useRuntimeConfigStore = defineStore('runtime-config', () => {
     loaded.value = true
   }
 
+  /** 重新拉取分组(仅分组,不重拉描述符/值;分组 CRUD 后调用) */
+  async function fetchGroups(): Promise<ConfigGroup[]> {
+    const http = useHttp()
+    const env = await http.get<{ data: { groups: ConfigGroup[] } }>('/system/config-groups')
+    const res = ((env as { data?: { groups: ConfigGroup[] } }).data ?? (env as unknown as { groups: ConfigGroup[] }))
+    groupsRaw.value = res.groups ?? []
+    return groupsRaw.value
+  }
+
+  /** 新建分组(admin) */
+  async function createGroup(def: Partial<ConfigGroup> & { label: string }): Promise<ConfigGroup> {
+    const http = useHttp()
+    const env = await http.post<{ data: { group: ConfigGroup } }>('/system/config-groups', def)
+    const res = ((env as { data?: { group: ConfigGroup } }).data ?? (env as unknown as { group: ConfigGroup }))
+    await fetchGroups()
+    return res.group
+  }
+
+  /** 更新分组(admin;标题/说明/排序/默认折叠/图标) */
+  async function updateGroup(id: string, patchMap: Partial<ConfigGroup>): Promise<void> {
+    const http = useHttp()
+    await http.request({ method: 'PATCH', url: `/system/config-groups/${encodeURIComponent(id)}`, data: patchMap })
+    await fetchGroups()
+  }
+
+  /** 删除分组(admin;仅自建组) */
+  async function deleteGroup(id: string, reassignTo?: string): Promise<void> {
+    const http = useHttp()
+    await http.request({ method: 'DELETE', url: `/system/config-groups/${encodeURIComponent(id)}${reassignTo ? `?reassignTo=${encodeURIComponent(reassignTo)}` : ''}` })
+    await fetchGroups()
+  }
+
   /**
    * 保存一组覆盖（同 PATCH 语义；值为 null 表示清除该键覆盖）。
    * @returns 服务端返回 { changed, restartRequired, effective, sources }
@@ -182,6 +277,11 @@ export const useRuntimeConfigStore = defineStore('runtime-config', () => {
     if (ev.effective) effective.value = ev.effective
     if (ev.sources) sources.value = ev.sources
     if (ev.overrides) overrides.value = ev.overrides
+    // 分组结构变更(管理员 CRUD / 插件装载或卸载声明了分组)→ 重拉分组,
+    // 让其它已打开设置页的会话即时看到新分区/分区消失
+    if (Array.isArray(ev.changed) && ev.changed.includes('config-groups')) {
+      void fetchGroups().catch(() => { /* 拉取失败保持现状 */ })
+    }
   }
 
   function stopEvents(): void {
@@ -193,6 +293,7 @@ export const useRuntimeConfigStore = defineStore('runtime-config', () => {
 
   return {
     descriptors,
+    groupsRaw,
     effective,
     overrides,
     sources,
@@ -201,9 +302,14 @@ export const useRuntimeConfigStore = defineStore('runtime-config', () => {
     loading,
     lastEvent,
     groups,
+    fieldsOf,
     sourceOf,
     valueOf,
     fetchAll,
+    fetchGroups,
+    createGroup,
+    updateGroup,
+    deleteGroup,
     patch,
     resetAll,
     startEvents,

package/cli/aw.mjs

@@ -15,7 +15,7 @@ import { homedir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { CommandRegistry, commandDirs } from './core/registry.mjs'
 import { createContext, EXIT } from './core/context.mjs'
-import { parseArgs } from './core/args.mjs'
+import { parseArgs, stripGlobals } from './core/args.mjs'
 import { renderHelp, renderCommandHelp } from './core/help.mjs'
 import { logger, color } from './core/logger.mjs'
 import { CliError, isUsageError } from './core/errors.mjs'
@@ -152,8 +152,14 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
   }
 
   // 指令参数（剥离指令名与全局项）
+  // 必须按 token 逐个定位全局选项的取值边界;旧实现用
+  //   .filter(a => a !== '--json' && a !== '--debug')
+  // 按字面量剔除,会把出现在「值」位置的同名 token 一并删掉:
+  //   aw foo --name --json      → --json 是 --name 的值,却被删 → --name 变布尔 true(值丢失)
+  //   aw foo --title=b --json   → 同理
+  // 传入 predicate 后由 parseArgs 在消费该 flag 时决定 skip 范围。
   const idx = argv.indexOf(commandName)
-  const cmdArgv = argv.slice(idx >= 0 ? idx + 1 : 0).filter(a => a !== '--json' && a !== '--debug')
+  const cmdArgv = stripGlobals(argv.slice(idx >= 0 ? idx + 1 : 0), ['--json', '--debug'])
   const local = parseArgs(cmdArgv, { shortMap: { h: 'help', ...(cmd.meta.short ?? {}) } })
 
   if (local.flags.help) {
@@ -183,9 +189,16 @@ export async function main(argv = process.argv.slice(2), { cwd = process.cwd() }
 }
 
 // 仅当直接以 cli/aw.mjs 作为入口时自动运行（bin/aw.mjs 会显式调用 main）
+//
+// 必须用 process.exit(code) 而非 process.exitCode = await main():
+// 当 stdout/stderr 是管道(fd 为 socket,如重定向、CI、父进程 spawn 捕获)且仍有
+// 未 flush 的挂起写入时,句柄会一直保活事件循环;Node 在 TLA 下因此以
+// **退出码 13**(ERR_UNSETTLED_TOP_LEVEL_AWAIT)收场,把 aw --help / aw version 这类
+// 纯诊断指令的成功退出写成 13。process.exit 会同步 flush 已排队的 stdio 写入
+// (writev 直写 fd),因此既保住输出又保住退出码。
 const thisEntry = process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))
 if (thisEntry) {
-  process.exitCode = await main()
+  process.exit(await main())
 }
 
 export default main

package/cli/commands/build.mjs

@@ -1,9 +1,9 @@
 // ============================================================
 // 指令:build — 生产构建（nuxt build → .output/）
 // ============================================================
-import { spawn } from 'node:child_process'
 import { color } from '../core/logger.mjs'
 import { localBypassEnv } from '../core/context.mjs'
+import { runChild } from '../core/child-lifecycle.mjs'
 
 export const meta = {
   name: 'build',
@@ -22,12 +22,12 @@ export async function run(argv, ctx) {
     return 1
   }
   console.log(`${color.cyan('›')} 构建生产产物 .output/ ...`)
-  const child = spawn(process.execPath, [nuxtBin, 'build'], { cwd: root, stdio: 'inherit', env: localBypassEnv() })
-  return await new Promise((resolve2) => {
-    child.on('close', code => resolve2(code ?? 0))
-    child.on('error', (err) => {
-      console.log(`${color.red('✖')} 构建失败: ${err.message}`)
-      resolve2(1)
-    })
+  // 统一生命周期:转发 SIGINT/SIGTERM(子进程不再变孤儿) + 等待退出 + 超时强杀
+  // + 退出码传播(被信号杀死 → 128+N,不再 code ?? 0 误报成功)
+  return await runChild(process.execPath, [nuxtBin, 'build'], {
+    cwd: root,
+    stdio: 'inherit',
+    env: localBypassEnv(),
+    onSpawnError: err => console.log(`${color.red('✖')} 构建失败: ${err.message}`),
   })
 }

package/cli/commands/dev.mjs

@@ -8,11 +8,11 @@
 //   · 端口/主机取自有效配置（config.yml < runtime-settings < env < CLI 参数）
 // 子进程统一注入 NO_PROXY（本机代理不再劫持 localhost 回环）。
 // ============================================================
-import { spawn } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { color } from '../core/logger.mjs'
 import { localBypassEnv } from '../core/context.mjs'
+import { runChild } from '../core/child-lifecycle.mjs'
 
 export const meta = {
   name: 'dev',
@@ -55,20 +55,12 @@ export async function run(argv, ctx) {
   console.log(`${color.cyan('›')} 开发服务器 -> http://${host}:${port}  ${color.dim(`(端口来源: ${portSource})`)}`)
   console.log(`${color.cyan('›')} 停止: Ctrl+C`)
 
-  const child = spawn(cmd, args, {
+  // 统一生命周期:转发 SIGINT/SIGTERM + 等待退出 + 5s 后 SIGKILL 强杀
+  // + 退出码传播(Ctrl+C 时子进程 code===null → 130,不再误报 0)
+  return await runChild(cmd, args, {
     cwd: root,
     stdio: 'inherit',
     env: localBypassEnv(),
-  })
-  const shutdown = () => child.kill('SIGTERM')
-  process.on('SIGINT', shutdown)
-  process.on('SIGTERM', shutdown)
-
-  return await new Promise((resolve2) => {
-    child.on('close', code => resolve2(code ?? 0))
-    child.on('error', (err) => {
-      console.log(`${color.red('✖')} dev 进程启动失败: ${err.message}`)
-      resolve2(1)
-    })
+    onSpawnError: err => console.log(`${color.red('✖')} dev 进程启动失败: ${err.message}`),
   })
 }

package/cli/commands/init.mjs

@@ -8,7 +8,7 @@
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
 import { join, resolve, basename } from 'node:path'
 import { color } from '../core/logger.mjs'
-import { CliError } from '../aw.mjs'
+import { CliError } from '../core/errors.mjs'
 
 export const meta = {
   name: 'init',

package/cli/commands/start.mjs

@@ -8,11 +8,11 @@
 // home 模式首启若无构建产物会自动构建一次(需依赖已安装)。
 // 子进程统一注入 NO_PROXY（本机代理不再劫持 localhost 回环）。
 // ============================================================
-import { spawn } from 'node:child_process'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { color } from '../core/logger.mjs'
 import { localBypassEnv, preloadDotEnv } from '../core/context.mjs'
+import { runChild } from '../core/child-lifecycle.mjs'
 import { runBootstrap } from '../../scripts/home-bootstrap.mjs'
 import { daqPreflight, printInfraGuidance } from '../infra.mjs'
 
@@ -48,10 +48,11 @@ export async function run(argv, ctx) {
       return 1
     }
     console.log(`${color.cyan('›')} 首次启动:正在构建生产产物(约 2-5 分钟,仅一次) ...`)
-    const buildCode = await new Promise((resolve2) => {
-      const c = spawn(process.execPath, [nuxtBin, 'build'], { cwd: appRoot, stdio: 'inherit', env: localBypassEnv() })
-      c.on('close', code => resolve2(code ?? 1))
-      c.on('error', () => resolve2(1))
+    // 同 build.mjs:转发信号 + 退出码传播(信号终止 → 128+N)
+    const buildCode = await runChild(process.execPath, [nuxtBin, 'build'], {
+      cwd: appRoot,
+      stdio: 'inherit',
+      env: localBypassEnv(),
     })
     if (buildCode !== 0 || !existsSync(outputEntry)) {
       console.log(`${color.red('✖')} 构建失败(exit=${buildCode})`)
@@ -110,20 +111,12 @@ export async function run(argv, ctx) {
   const launcher = join(appRoot, 'scripts', 'start.mjs')
   const args = existsSync(launcher) ? [launcher] : [outputEntry]
   if (flags.port !== undefined) args.push('--port', String(port))
-  const child = spawn(process.execPath, args, {
+  // 统一生命周期:转发 SIGINT/SIGTERM + 等待退出 + 5s 后 SIGKILL 强杀
+  // + 退出码传播(Ctrl+C 时子进程 code===null → 130,不再误报 0)
+  return await runChild(process.execPath, args, {
     cwd,
     stdio: 'inherit',
     env: localBypassEnv(envExtra),
-  })
-  const shutdown = () => child.kill('SIGTERM')
-  process.on('SIGINT', shutdown)
-  process.on('SIGTERM', shutdown)
-
-  return await new Promise((resolve2) => {
-    child.on('close', code => resolve2(code ?? 0))
-    child.on('error', (err) => {
-      console.log(`${color.red('✖')} start 进程启动失败: ${err.message}`)
-      resolve2(1)
-    })
+    onSpawnError: err => console.log(`${color.red('✖')} start 进程启动失败: ${err.message}`),
   })
 }

package/cli/core/args.mjs

@@ -8,12 +8,29 @@
 //   --                 → 之后全部为位置参数
 // ============================================================
 
-/** 解析 argv（不含 node/script 前两项）。返回 { flags, positionals } */
-export function parseArgs(argv, { shortMap = {} } = {}) {
+/**
+ * 解析 argv（不含 node/script 前两项）。返回 { flags, positionals, unknown }
+ *
+ * @param {string[]} argv
+ * @param {{
+ *   shortMap?: Record<string, string>,
+ *   skip?: (consumed: string[], next: string | undefined) => number,
+ * }} [options]
+ *   skip: 在某个 flag 被完整消费后调用,返回「额外跳过」的 token 数。
+ *         用于按位置剥离全局选项（不能按字面量过滤——见 stripGlobals）。
+ */
+export function parseArgs(argv, { shortMap = {}, skip } = {}) {
   const flags = {}
   const positionals = []
   const unknown = []
 
+  /** flag 被完整消费（含可能的取值 token）后,按 skip 决定额外跳过的 token 数 */
+  const extraSkip = (consumed, next) => {
+    if (typeof skip !== 'function') return 0
+    const n = skip(consumed, next)
+    return Number.isInteger(n) && n > 0 ? n : 0
+  }
+
   let i = 0
   let afterDoubleDash = false
   while (i < argv.length) {
@@ -48,7 +65,9 @@ export function parseArgs(argv, { shortMap = {} } = {}) {
         }
       }
       flags[name] = value
-      i++
+      // 注意:bare flag（value===true）的 next 是「未被本 flag 消费」的 token,
+      // 有意不传给 skip —— 全局选项只在带值时其取值 token 才可能同名。
+      i += 1 + extraSkip([tok], value === true ? undefined : argv[i + 1])
       continue
     }
 
@@ -66,7 +85,7 @@ export function parseArgs(argv, { shortMap = {} } = {}) {
           value = true
         }
         flags[name] = value
-        i++
+        i += 1 + extraSkip([tok], next)
         continue
       }
       unknown.push(tok)
@@ -81,6 +100,68 @@ export function parseArgs(argv, { shortMap = {} } = {}) {
   return { flags, positionals, unknown }
 }
 
+/**
+ * 按位置剥离全局选项（供 cli/aw.mjs 计算指令局部 argv）。
+ *
+ * 为什么不能按字面量过滤:同名 token 可能是某个 flag 的「值」而非选项本身,
+ *   ['--name', '--json']    --json 是 --name 的值 → 过滤会把它删掉,值丢失
+ *   ['--name=--json']       同理（等号形式的值）
+ *   ['--json', 'x']         位置 0 的 --json 才是真正的全局选项
+ * 这里复用 parseArgs 的消费逻辑,只在 token 处于「选项位」时剔除,
+ * 值位上的同名 token 原样保留;带值的全局选项连同其取值 token 一起移除。
+ *
+ * @param {string[]} argv
+ * @param {string[]} names 需剔除的长选项名（含 -- 前缀）,如 ['--json','--debug']
+ * @returns {string[]} 剔除全局选项后的 argv（保序;其余 token 原样保留）
+ */
+export function stripGlobals(argv, names) {
+  const drop = new Set(names)
+  const kept = []
+  let i = 0
+  let afterDoubleDash = false
+  while (i < argv.length) {
+    const tok = argv[i]
+    // '--' 之后全是位置参数,不再剥离
+    if (!afterDoubleDash && tok === '--') {
+      afterDoubleDash = true
+      kept.push(tok)
+      i++
+      continue
+    }
+    if (afterDoubleDash) {
+      kept.push(tok)
+      i++
+      continue
+    }
+    if (tok.startsWith('--')) {
+      const body = tok.slice(2)
+      const eq = body.indexOf('=')
+      const name = '--' + (eq >= 0 ? body.slice(0, eq) : body)
+      const hasInlineValue = eq >= 0
+      // 下一步会吃掉的取值 token（可能是「作为值出现的同名 token」,不得误删）
+      const next = argv[i + 1]
+      const willConsumeNext = !hasInlineValue
+        && next !== undefined && !next.startsWith('-') && next !== ''
+      if (drop.has(name)) {
+        // 全局选项及其值一并移除;--json=1 这类内联值随 token 一起消失
+        i += 1 + (willConsumeNext ? 1 : 0)
+        continue
+      }
+      kept.push(tok)
+      if (willConsumeNext) {
+        kept.push(next)
+        i += 2
+        continue
+      }
+      i++
+      continue
+    }
+    kept.push(tok)
+    i++
+  }
+  return kept
+}
+
 /** 便捷：读取 flags 中的值或默认 */
 export function flagValue(flags, name, fallback) {
   return flags[name] === undefined ? fallback : flags[name]

package/cli/core/child-lifecycle.mjs

@@ -0,0 +1,136 @@
+// ============================================================
+// AgentWorkShop CLI — 子进程生命周期工具（共享）
+// ------------------------------------------------------------
+// aw dev / start / build 都把「前台运行一个长命令」这件事交给子进程:
+// 若不统一处理，会出现三类真实缺陷:
+//   1. 子进程被信号杀死时 close 回调的 code === null，旧代码写 code ?? 0
+//      → Ctrl+C 打断构建却被报成「成功」。
+//   2. 不转发父进程信号 → Ctrl+C 只杀父进程，nuxt 变孤儿继续占用端口。
+//   3. 转发后不等子进程退出、无强杀兜底 → 僵尸残留。
+//
+// 本模块收敛为两个导出:
+//   · runChild()      —— spawn + 信号转发 + 等待退出 + 超时强杀 + 退出码/信号传播
+//   · signalExitCode()—— 退出码约定:被信号终止 → 128 + signalNumber
+//
+// 退出码约定（POSIX 惯例,与 bash 一致）:
+//   · 正常退出       → 子进程 exit code 原样透传
+//   · 被信号 N 终止  → 128 + N（SIGINT=2 → 130,SIGTERM=15 → 143；未知信号 → 1）
+//   · spawn 失败     → 1
+// ============================================================
+import { spawn } from 'node:child_process'
+
+/** 信号名 → 编号（跨平台:Windows 下 libuv 亦按此表上报 signal） */
+const SIGNAL_NUMBERS = {
+  SIGHUP: 1,
+  SIGINT: 2,
+  SIGQUIT: 3,
+  SIGILL: 4,
+  SIGTRAP: 5,
+  SIGABRT: 6,
+  SIGBUS: 7,
+  SIGFPE: 8,
+  SIGKILL: 9,
+  SIGUSR1: 10,
+  SIGSEGV: 11,
+  SIGUSR2: 12,
+  SIGPIPE: 13,
+  SIGALRM: 14,
+  SIGTERM: 15,
+}
+
+/** 优雅终止宽限期（毫秒）:转发 SIGTERM 后等待,超时仍存活则 SIGKILL */
+export const SHUTDOWN_GRACE_MS = 5000
+
+/** 被信号终止的退出码:128 + signalNumber（约定,未知信号退化为 1） */
+export function signalExitCode(signal) {
+  const n = SIGNAL_NUMBERS[signal]
+  return Number.isInteger(n) ? 128 + n : 1
+}
+
+/**
+ * 前台运行子进程并传播其退出语义（aw dev/start/build 唯一入口）。
+ *
+ * @param {string} command 可执行文件（如 process.execPath）
+ * @param {string[]} args  参数数组
+ * @param {{
+ *   cwd?: string,
+ *   env?: Record<string, string>,
+ *   stdio?: any,
+ *   forwardSignals?: boolean,    转发 SIGINT/SIGTERM/SIGHUP 到子进程（默认 true）
+ *   graceMs?: number,            优雅终止宽限期（默认 SHUTDOWN_GRACE_MS）
+ *   killSignal?: NodeJS.Signals, 首轮终止信号（默认 SIGTERM）
+ *   onSpawnError?: (err: Error) => void,
+ * }} [options]
+ * @returns {Promise<number>} 进程退出码（信号终止 → 128 + signalNumber）
+ */
+export function runChild(command, args = [], options = {}) {
+  const {
+    cwd,
+    env,
+    stdio = 'inherit',
+    forwardSignals = true,
+    graceMs = SHUTDOWN_GRACE_MS,
+    killSignal = 'SIGTERM',
+    onSpawnError,
+  } = options
+
+  return new Promise((resolveExit) => {
+    const child = spawn(command, args, { cwd, env, stdio })
+
+    let settled = false
+    let killTimer = null
+    let graceTimer = null
+
+    /** 幂等收口:先摘事件监听与定时器,再上报退出码 */
+    const finish = (code) => {
+      if (settled) return
+      settled = true
+      if (graceTimer) clearTimeout(graceTimer)
+      if (killTimer) clearTimeout(killTimer)
+      for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.removeListener(sig, onSignal)
+      resolveExit(code)
+    }
+
+    // 首轮终止 → 宽限期内未退出 → SIGKILL 强杀兜底（对齐 cli/commands/stop.mjs 的
+    // SIGTERM → 5s → SIGKILL 语义;强杀不等回执,由 close 事件收口）
+    const terminate = () => {
+      if (settled) return
+      try {
+        child.kill(killSignal)
+      }
+      catch { /* 已退出 */ }
+      if (graceTimer) return
+      graceTimer = setTimeout(() => {
+        try {
+          child.kill('SIGKILL')
+        }
+        catch { /* 已退出 */ }
+      }, graceMs)
+      // 强杀后仍不收口（极端情况:句柄泄漏）→ 定时硬收口,避免 aw 永不返回
+      graceTimer.unref?.()
+      if (!killTimer) {
+        killTimer = setTimeout(() => finish(signalExitCode('SIGTERM')), graceMs + 5000)
+        killTimer.unref?.()
+      }
+    }
+
+    const onSignal = () => terminate()
+
+    if (forwardSignals) {
+      for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, onSignal)
+    }
+
+    child.on('error', (err) => {
+      onSpawnError?.(err)
+      finish(1)
+    })
+
+    // close（而非 exit）:确保 stdio 已全部排空,长命令输出不丢失
+    child.on('close', (code, signal) => {
+      // code === null ⇔ 子进程被信号杀死 → 必须传播非 0
+      finish(code ?? (signal ? signalExitCode(signal) : 1))
+    })
+  })
+}
+
+export default runChild

package/config.yml

@@ -142,3 +142,27 @@ retention:
 # 服务端日志(env AWSHOP_LOG_LEVEL)
 log:
   level: info  # debug | info | warn | error
+
+# AML 自动建模平台(Python 训练运行时/作业限额/GC 保留/评测门禁;全部键见 shared/config/schema.json)
+aml:
+  python:
+    pythonBin: ''   # 空=自动探测 python / py -3
+    uvBin: ''       # 空=自动探测 uv(存在则优先)
+    indexUrl: ''    # PyPI 兼容镜像,空=默认源;仅 venv 供给阶段联网,训练进程不联网
+  job:
+    timeoutMs: 1800000
+    maxConcurrent: 2
+    diskQuotaMb: 2048
+    stallMs: 600000
+  dataset:
+    maxRows: 200000
+    retentionDays: 30
+    allowCrossRecipe: false
+  model:
+    retiredKeepDays: 90
+  gates:
+    nrmse: 0.10
+    rolloutNrmse: 0.25
+    valTestGap: 0.20
+    minRows: 500
+    minRuns: 3