agentworkshop 0.7.27 → 0.7.34

package/app/pages/workshop/agents.vue

@@ -370,7 +370,16 @@ useHead({ title: () => tt('titles.agents') })
           <a-select
             v-model:value="form.harness"
             :options="harnessOptions"
-          />
+          >
+            <template #option="{ value, label }">
+              <span
+                class="h-opt"
+                :class="{ off: isUnavailable(String(value)) }"
+              >
+                <span class="h-opt-dot" /> {{ label }}
+              </span>
+            </template>
+          </a-select>
           <div
             v-if="harnesses.length > 0"
             class="harness-status"
@@ -378,6 +387,13 @@ useHead({ title: () => tt('titles.agents') })
           >
             <template v-if="isUnavailable(form.harness)">
               <span class="i-tabler-plug-off" /> {{ harnessById.get(form.harness)?.error }}
+              <a
+                v-if="harnessById.get(form.harness)?.homepage"
+                class="h-install"
+                :href="harnessById.get(form.harness)?.homepage"
+                target="_blank"
+                rel="noopener"
+              >{{ tt('agents.installLink') }}</a>
             </template>
             <template v-else-if="harnessById.get(form.harness)?.inprocess">
               <span class="i-tabler-plug-connected" /> {{ tt('agents.harnessInprocess') }}
@@ -428,6 +444,12 @@ useHead({ title: () => tt('titles.agents') })
   border-radius: 3px;
   opacity: 0.75;
 }
+.h-opt { display: inline-flex; align-items: center; gap: 7px; }
+.h-opt-dot { flex: none; width: 6px; height: 6px; border-radius: 50%; background: var(--tone-success-dot, #4a6b57); }
+.h-opt.off .h-opt-dot { background: var(--tone-danger-dot, #c25a4e); }
+.h-opt.off { opacity: 0.6; }
+.h-install { margin-left: 8px; color: var(--accent); text-decoration: none; }
+.h-install:hover { text-decoration: underline; }
 .harness-status {
   display: flex;
   gap: 6px;

package/app/pages/workshop/teams.vue

@@ -219,7 +219,7 @@ const openPlugins = (team: TeamDto): void => {
 const loadTeamPlugins = async (team: TeamDto): Promise<void> => {
   plugLoading.value = true
   try {
-    const res = await api.listChannelPlugins(team.id)
+    const res = await api.listTeamPlugins(team.id)
     const data = res?.data ?? {}
     plugRows.value = data.plugins ?? []
     plugSource.value = data.source === 'explicit' ? 'explicit' : 'default'
@@ -238,7 +238,7 @@ const toggleTeamPlugin = async (row: ChannelPluginStateDto, next: boolean): Prom
   try {
     // PUT 全量提交当前开关视图(仅翻转目标行)
     const payload = plugRows.value.map(r => ({ name: r.name, enabled: r.name === row.name ? next : r.enabled }))
-    const res = await api.putChannelPlugins(teamId, { plugins: payload })
+    const res = await api.putTeamPlugins(teamId, { plugins: payload })
     const data = res?.data ?? {}
     plugRows.value = data.plugins ?? payload.map(p => ({ ...p }))
     plugSource.value = data.source === 'explicit' ? 'explicit' : 'default'

package/app/plugins/aw-plugins.client.ts

@@ -1,21 +1,33 @@
 /**
  * aw 插件客户端装载器 —— 前端增强入口(支持热注入/热卸载)。
  * - 启动期拉取 /api/plugins/manifest → 对启用且含 client 的插件动态 import 装载
+ * - i18n:启动/热重载时拉取 /api/plugins/i18n(插件根目录 i18n.json 汇编),
+ *   按 vue-i18n 命名空间 `plugin.<name>` 合并 → 插件设置标签/面板文案多语言;
+ *   语言切换经 i18n:changed 钩子广播给全部客户端插件
+ * - UI 注入:ctx.ui.registerPanel → usePluginPanels 注册表 → 页面 <PluginSlot> 渲染;
+ *   ctx.t 为插件命名空间翻译
  * - 热通道双保险:WS `plugins.reloaded` 事件(TownBus 桥) + 15s 轮询 diff
- *   → 新启用插件即时注入;停用插件即时 dispose 卸载
+ *   → 新启用插件即时注入;停用插件即时 dispose 卸载(面板/订阅全回收)
  * - 错误隔离:单插件装载失败仅告警,不影响应用与其他插件
  * 插件契约见 docs/plugins.md;信任模型与 aw commands 相同(仅装可信代码)。
  */
+import { watch } from 'vue'
 import { createClientContext, type ClientContext } from '@/sdk/client.mjs'
+import { usePluginPanels } from '@/app/composables/workshop/usePluginPanels'
 import type { TownBus } from '~/composables/workshop/useTownBus'
 
 interface ManifestEntry { name: string, enabled?: boolean, hasClient?: boolean }
+interface I18nBundle { i18n?: Record<string, Record<string, Record<string, string>>> }
 
 export default defineNuxtPlugin(async (nuxtApp) => {
   if (!import.meta.client) return
 
   /** name → ctx(已装载客户端插件) */
   const loaded = new Map<string, ClientContext>()
+  const { unregisterPlugin } = usePluginPanels()
+  const panels = usePluginPanels()
+  const i18n: { mergeLocaleMessage?: (locale: string, messages: Record<string, unknown>) => void, locale?: unknown } | null
+    = (nuxtApp.$i18n as never) ?? null
   let bus: TownBus | null = null
   try {
     bus = useTownBus()
@@ -36,6 +48,50 @@ export default defineNuxtPlugin(async (nuxtApp) => {
     })
   }
 
+  /** 插件消息树(locale → plugin → key 树);ctx.t 自解析,不依赖 vue-i18n 实例差异 */
+  const messageTree: Record<string, Record<string, Record<string, string>>> = {}
+  let currentLocale = ''
+
+  function localeOf(): string {
+    const loc = i18n?.locale as { value?: string } | string | undefined
+    return typeof loc === 'string' ? loc : (loc?.value ?? 'zh-CN')
+  }
+
+  function resolveKey(locale: string, plugin: string, key: string): string {
+    let cur: unknown = messageTree[locale]?.[plugin]
+    for (const seg of key.split('.')) {
+      if (!cur || typeof cur !== 'object') return ''
+      cur = (cur as Record<string, unknown>)[seg]
+    }
+    return typeof cur === 'string' ? cur : ''
+  }
+
+  /** 拉取并合并插件 i18n 消息(命名空间 plugin.<name>;幂等) */
+  async function syncI18n(): Promise<void> {
+    try {
+      const res = await fetch('/api/plugins/i18n', { headers: { accept: 'application/json' } })
+      if (!res.ok) return
+      const body = (await res.json().catch(() => null)) as I18nBundle | null
+      for (const [plugin, locales] of Object.entries(body?.i18n ?? {})) {
+        for (const [locale, messages] of Object.entries(locales)) {
+          ;(messageTree[locale] ??= {})[plugin] = messages
+          // 同时并入 vue-i18n(设置页等宿主组件经 t() 解析插件设置标签)
+          i18n?.mergeLocaleMessage?.(locale, { plugin: { [plugin]: messages } })
+        }
+      }
+      currentLocale = localeOf()
+    }
+    catch { /* i18n 包不可达:插件文案回落声明里的 label */ }
+  }
+
+  /** 翻译助手:插件命名空间自解析(messageTree;未命中回落声明键) */
+  function translatorFor(name: string): (key: string, params?: Record<string, unknown>) => string {
+    return (key, _params) => {
+      const hit = resolveKey(localeOf(), name, key) || resolveKey(currentLocale, name, key)
+      return hit || key
+    }
+  }
+
   async function loadOne(name: string): Promise<boolean> {
     try {
       const mod = await import(/* @vite-ignore */ `/api/plugins/client/${encodeURIComponent(name)}`)
@@ -44,7 +100,19 @@ export default defineNuxtPlugin(async (nuxtApp) => {
         console.warn(`[aw-plugins] ${name} 客户端入口缺少 setup(ctx)`)
         return false
       }
-      const ctx = createClientContext({ name, eventBridge: bridgeFactory(bus) })
+      const ctx = createClientContext({
+        name,
+        eventBridge: bridgeFactory(bus),
+        ui: {
+          slots: ['plugins.page', 'settings.plugins', 'dashboard.widgets'],
+          registerPanel: entry => panels.registerPanel({ ...entry, plugin: name }),
+        },
+        t: translatorFor(name),
+        getLocale: () => {
+          const loc = i18n?.locale as { value?: string } | string | undefined
+          return typeof loc === 'string' ? loc : loc?.value ?? ''
+        },
+      })
       await (setup as (ctx: unknown) => void | Promise<void>)(ctx)
       void ctx.hooks.emit('client:init', { name })
       loaded.set(name, ctx)
@@ -62,32 +130,53 @@ export default defineNuxtPlugin(async (nuxtApp) => {
     if (!ctx) return
     ctx.dispose()
     loaded.delete(name)
+    unregisterPlugin(name) // 回收其注册的全部 UI 面板
     console.info(`[aw-plugins] 客户端插件已卸载: ${name}`)
   }
 
-  /** 全量同步:启用的新插件注入;停用/移除的插件卸载 */
+  /** 全量同步:启用的新插件注入;停用/移除的插件卸载;i18n 包随增量刷新 */
   async function syncPlugins(): Promise<void> {
     try {
       const res = await fetch('/api/plugins/manifest', { headers: { accept: 'application/json' } })
       if (!res.ok) return
       const body = await res.json().catch(() => null) as { plugins?: ManifestEntry[] } | null
       const list = body?.plugins ?? []
+      let changed = false
       for (const p of list) {
-        if (p.enabled !== false && p.hasClient && !loaded.has(p.name))
+        if (p.enabled !== false && p.hasClient && !loaded.has(p.name)) {
           await loadOne(p.name)
+          changed = true
+        }
       }
       for (const name of [...loaded.keys()]) {
         const p = list.find(x => x.name === name)
-        if (!p || p.enabled === false || !p.hasClient)
+        if (!p || p.enabled === false || !p.hasClient) {
           unloadOne(name)
+          changed = true
+        }
       }
+      if (changed) await syncI18n()
     }
     catch { /* 网络不可达:保留现状,下轮再试 */ }
   }
 
-  // 首次装载
+  // 首次装载(i18n 先行:面板/设置标签直接以正确语言渲染)
+  await syncI18n()
   await syncPlugins()
 
+  // 语言切换 → 广播 i18n:changed(插件面板据此重渲染)
+  const localeRef = i18n?.locale as { value?: string } | undefined
+  if (localeRef && typeof localeRef === 'object') {
+    watch(localeRef, (loc) => {
+      for (const { ctx } of loaded.values()) {
+        try {
+          ctx?.hooks?.emit('i18n:changed', { locale: loc })
+        }
+        catch { /* 单插件广播失败不阻断 */ }
+      }
+    })
+  }
+
   // 页面切换广播(已装载插件均可感知;防御性隔离——单插件异常不影响路由)
   if (loaded.size) {
     nuxtApp.hooks.hook('page:finish', () => {

package/app/plugins/runtime-config.client.ts

@@ -12,25 +12,15 @@ export default defineNuxtPlugin(() => {
   const store = useRuntimeConfigStore()
   const appStore = useAppStore()
 
-  let darkTouched = false
-  let lastDarkFromRuntime: boolean | null = null
-
-  // 用户手动切换过暗色后，禁止运行时主题覆盖（尊重本地偏好）
-  watch(
-    () => appStore.isDark,
-    (v) => {
-      if (lastDarkFromRuntime !== null && v !== lastDarkFromRuntime) darkTouched = true
-    },
-  )
-
-  // 主题模式:runtime 默认 → 应用首次暗态（仅当用户未手动切换）
+  // 主题模式:服务端 runtime 默认只对"从未显式选择过"的会话生效。
+  // 一旦用户在设置页/页头切过一次(toggleDark 置 themeTouched),本地偏好即锁定,
+  // 服务端 theme.mode 的热更新不再夺走控制权 —— 否则每次刷新都被默认值冲掉。
   watch(
     () => store.effective['theme.mode'],
     (v) => {
       if (v !== 'light' && v !== 'dark') return
-      if (darkTouched) return
+      if (appStore.themeTouched) return
       const target = v === 'dark'
-      lastDarkFromRuntime = target
       if (appStore.isDark !== target) appStore.isDark = target
     },
     { immediate: true },

package/app/plugins/theme.client.ts

@@ -2,14 +2,24 @@ import { useAppStore } from '~/stores/app'
 
 /**
  * 暗色模式同步插件（仅客户端）
- * 将 Pinia 的 isDark 状态同步为 <html> 的 .dark class，
- * 供 UnoCSS / 自定义暗色样式（main.css、布局层）消费。
- * antd 组件本身的暗色由 app.vue 的 ConfigProvider algorithm 驱动。
+ * 1. 将 Pinia 的 isDark 状态同步为 <html> 的 .dark class，
+ *    供 UnoCSS / 自定义暗色样式（main.css、布局层）消费。
+ *    antd 组件本身的暗色由 app.vue 的 ConfigProvider algorithm 驱动。
+ * 2. 把偏好镜像进 aw-theme cookie —— SSR 阶段读不到 localStorage，
+ *    没有这枚 cookie，服务端只能按 config.yml 渲浅色，客户端首帧再翻深色，
+ *    antd cssinjs 不会为相同 hash 重注入样式（深色下部分组件会掉样式）。
  */
 export default defineNuxtPlugin(() => {
   const store = useAppStore()
+  const cookie = useCookie<'dark' | 'light'>('aw-theme', {
+    maxAge: 60 * 60 * 24 * 365,
+    sameSite: 'lax',
+    path: '/',
+  })
 
   watchEffect(() => {
     document.documentElement.classList.toggle('dark', store.isDark)
+    const next = store.isDark ? 'dark' : 'light'
+    if (cookie.value !== next) cookie.value = next
   })
 })

package/app/stores/app.ts

@@ -5,6 +5,12 @@ export const useAppStore = defineStore('app', () => {
   // 默认暗色 = Digital Twin 控制室是产品首态(可切换亮色,选择被持久化)
   const isDark = ref(true)
   const sidebarCollapsed = ref(false)
+  /**
+   * 用户是否在设置页/页头显式切换过明暗。
+   * 只有"显式选择"才锁死主题,阻止服务端 theme.mode 的运行时跟随——
+   * 否则每次刷新都会被服务端默认值冲掉本地偏好(设置项形同虚设)。
+   */
+  const themeTouched = ref(false)
   /**
    * 主题强调色(warm-editorial:默认墨色药丸;设置页可换 muted 预设,实时生效并持久化)。
    * null = 跟随 config.yml 默认(config.primaryColor 注入的 --color-primary)。
@@ -13,6 +19,7 @@ export const useAppStore = defineStore('app', () => {
 
   function toggleDark() {
     isDark.value = !isDark.value
+    themeTouched.value = true
   }
 
   function toggleSidebar() {
@@ -23,10 +30,10 @@ export const useAppStore = defineStore('app', () => {
     accent.value = color
   }
 
-  return { isDark, sidebarCollapsed, accent, toggleDark, toggleSidebar, setAccent }
+  return { isDark, sidebarCollapsed, accent, themeTouched, toggleDark, toggleSidebar, setAccent }
 }, {
   persist: {
-    pick: ['isDark', 'sidebarCollapsed', 'accent'],
+    pick: ['isDark', 'sidebarCollapsed', 'accent', 'themeTouched'],
     storage: piniaPluginPersistedstate.localStorage(),
   },
 })

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',