helloagents 3.0.33 → 3.0.37

package/scripts/cli-lifecycle-hosts.mjs

@@ -1,4 +1,5 @@
 import { spawnSync } from 'node:child_process'
+import { platform } from 'node:os'
 
 import {
   installClaudeStandby,
@@ -17,23 +18,50 @@ import { getHostLabel } from './cli-host-detect.mjs'
 
 const CLAUDE_COMMAND = process.env.HELLOAGENTS_CLAUDE_CMD || 'claude'
 const GEMINI_COMMAND = process.env.HELLOAGENTS_GEMINI_CMD || 'gemini'
-const CLAUDE_MARKETPLACE = 'hellowind777/helloagents'
+const CLAUDE_MARKETPLACE = 'https://github.com/hellowind777/helloagents.git'
 const CLAUDE_PLUGIN = 'helloagents@helloagents'
-const GEMINI_EXTENSION = 'https://github.com/hellowind777/helloagents'
+
+function normalizeCommand(command = '') {
+  return String(command || '').trim()
+}
+
+function commandCandidates(command = '') {
+  const normalized = normalizeCommand(command)
+  if (!normalized) return []
+
+  if (platform() !== 'win32') return [normalized]
+
+  const candidates = new Set([normalized])
+  if (!/\.(cmd|bat|exe|ps1)$/i.test(normalized)) {
+    candidates.add(`${normalized}.cmd`)
+    candidates.add(`${normalized}.exe`)
+  }
+  return [...candidates]
+}
 
 function runHostCommand(command, args) {
-  const needsShell = process.platform === 'win32' && /\.cmd$/i.test(command)
-  const result = spawnSync(command, args, {
-    encoding: 'utf-8',
-    errors: 'replace',
-    shell: needsShell,
-    windowsHide: true,
-  })
-  const errorMessage = result.error?.message || ''
+  const attempts = commandCandidates(command)
+  let lastResult = null
+
+  for (const candidate of attempts) {
+    const needsShell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(candidate)
+    const result = spawnSync(candidate, args, {
+      encoding: 'utf-8',
+      errors: 'replace',
+      shell: needsShell,
+      windowsHide: true,
+    })
+    lastResult = result
+    if (!result.error || !['ENOENT', 'EINVAL'].includes(result.error.code)) {
+      break
+    }
+  }
+
+  const errorMessage = lastResult?.error?.message || ''
   return {
-    ok: result.status === 0,
-    missing: result.error?.code === 'ENOENT',
-    output: `${result.stdout || ''}${result.stderr || ''}${errorMessage}`.trim(),
+    ok: lastResult?.status === 0,
+    missing: ['ENOENT', 'EINVAL'].includes(lastResult?.error?.code || ''),
+    output: `${lastResult?.stdout || ''}${lastResult?.stderr || ''}${errorMessage}`.trim(),
   }
 }
 
@@ -46,6 +74,13 @@ function buildNativeResult(result, successCN, successEN, manualCN, manualEN) {
   }
 }
 
+function preserveTrackedModeOnFailure(result = {}, trackedMode = '') {
+  if (result.ok === false && trackedMode) {
+    return { ...result, trackedModeOnFailure: trackedMode }
+  }
+  return result
+}
+
 function installClaudeGlobalPlugin() {
   const add = runHostCommand(CLAUDE_COMMAND, ['plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE])
   if (!add.ok && add.missing) return { ok: false, output: '未找到 claude 命令' }
@@ -53,8 +88,8 @@ function installClaudeGlobalPlugin() {
   return { ok: install.ok, output: install.output || add.output }
 }
 
-function installGeminiGlobalExtension() {
-  return runHostCommand(GEMINI_COMMAND, ['extensions', 'install', GEMINI_EXTENSION])
+function installGeminiGlobalExtension(runtimeRoot) {
+  return runHostCommand(GEMINI_COMMAND, ['extensions', 'link', runtimeRoot])
 }
 
 function removeClaudeGlobalPlugin() {
@@ -70,8 +105,11 @@ function reportHostAction(runtime, action, host, mode, result = {}) {
   const isCleanup = action === 'cleanup' || action === 'uninstall'
   if (result.skipped) {
     console.log(runtime.msg(`  - ${label} 未检测到，跳过`, `  - ${label} not detected, skipped`))
-  } else if (result.ok === false && !isCleanup) {
-    console.log(runtime.msg(`  - ${label} 自动配置未完成`, `  - ${label} automatic setup did not complete`))
+  } else if (result.ok === false) {
+    console.log(runtime.msg(
+      isCleanup ? `  - ${label} 自动清理未完成` : `  - ${label} 自动配置未完成`,
+      isCleanup ? `  - ${label} automatic cleanup did not complete` : `  - ${label} automatic setup did not complete`,
+    ))
   } else if (isCleanup) {
     runtime.ok(runtime.msg(`${label} 已清理（${mode} 模式）`, `${label} cleaned (${mode} mode)`))
   } else if (mode === 'standby') {
@@ -87,14 +125,46 @@ function reportHostAction(runtime, action, host, mode, result = {}) {
   }
 }
 
-function installHostStandby(runtime, host) {
+function prepareClaudeStandby(previousMode) {
+  if (previousMode !== 'global') return {}
+  return preserveTrackedModeOnFailure(
+    buildNativeResult(
+      removeClaudeGlobalPlugin(),
+      '已自动移除 Claude Code 插件',
+      'Claude Code plugin removed automatically',
+      '切到 standby 前无法自动移除 Claude Code 插件，请先在 Claude Code 中执行: /plugin remove helloagents',
+      'Could not remove the Claude Code plugin before switching to standby. Run inside Claude Code: /plugin remove helloagents',
+    ),
+    'global',
+  )
+}
+
+function prepareGeminiStandby(previousMode) {
+  if (previousMode !== 'global') return {}
+  return preserveTrackedModeOnFailure(
+    buildNativeResult(
+      removeGeminiGlobalExtension(),
+      '已自动移除 Gemini CLI 扩展',
+      'Gemini CLI extension removed automatically',
+      '切到 standby 前无法自动移除 Gemini CLI 扩展，请先手动执行: gemini extensions uninstall helloagents',
+      'Could not remove the Gemini CLI extension before switching to standby. Run manually: gemini extensions uninstall helloagents',
+    ),
+    'global',
+  )
+}
+
+function installHostStandby(runtime, host, { previousMode = '' } = {}) {
   if (host === 'claude') {
+    const cleanupResult = prepareClaudeStandby(previousMode)
+    if (cleanupResult.ok === false) return cleanupResult
     installClaudeStandby(runtime.home, runtime.pkgRoot)
-    return {}
+    return cleanupResult
   }
   if (host === 'gemini') {
+    const cleanupResult = prepareGeminiStandby(previousMode)
+    if (cleanupResult.ok === false) return cleanupResult
     installGeminiStandby(runtime.home, runtime.pkgRoot)
-    return {}
+    return cleanupResult
   }
   if (!installCodexStandby(runtime.home, runtime.pkgRoot)) return { skipped: true }
   cleanupCodexGlobalResidueForStandby(runtime.home)
@@ -108,18 +178,18 @@ function installHostGlobal(runtime, host) {
       installClaudeGlobalPlugin(),
       '已自动安装 Claude Code 插件；重启 Claude Code 后生效',
       'Claude Code plugin installed automatically; restart Claude Code to apply',
-      'Claude Code 插件自动安装失败，请在 Claude Code 中执行: /plugin marketplace add hellowind777/helloagents；/plugin install helloagents@helloagents',
-      'Claude Code plugin auto-install failed. Run inside Claude Code: /plugin marketplace add hellowind777/helloagents; /plugin install helloagents@helloagents',
+      'Claude Code 插件自动安装失败，请在 Claude Code 中执行: /plugin marketplace add https://github.com/hellowind777/helloagents.git；/plugin install helloagents@helloagents',
+      'Claude Code plugin auto-install failed. Run inside Claude Code: /plugin marketplace add https://github.com/hellowind777/helloagents.git; /plugin install helloagents@helloagents',
     )
   }
   if (host === 'gemini') {
     uninstallGeminiStandby(runtime.home)
     return buildNativeResult(
-      installGeminiGlobalExtension(),
+      installGeminiGlobalExtension(runtime.pkgRoot),
       '已自动安装 Gemini CLI 扩展；重启 Gemini CLI 后生效',
       'Gemini CLI extension installed automatically; restart Gemini CLI to apply',
-      'Gemini CLI 扩展自动安装失败，请手动执行: gemini extensions install https://github.com/hellowind777/helloagents',
-      'Gemini CLI extension auto-install failed. Run manually: gemini extensions install https://github.com/hellowind777/helloagents',
+      `Gemini CLI 扩展自动安装失败，请手动执行: gemini extensions link ${runtime.pkgRoot}`,
+      `Gemini CLI extension auto-install failed. Run manually: gemini extensions link ${runtime.pkgRoot}`,
     )
   }
   uninstallCodexStandby(runtime.home)
@@ -137,41 +207,41 @@ function cleanupHostStandby(runtime, host) {
 function cleanupHostGlobal(runtime, host) {
   if (host === 'claude') {
     uninstallClaudeStandby(runtime.home)
-    return buildNativeResult(
-      removeClaudeGlobalPlugin(),
-      '已自动移除 Claude Code 插件',
-      'Claude Code plugin removed automatically',
-      'Claude Code 插件自动移除失败，请手动执行: /plugin remove helloagents',
-      'Claude Code plugin auto-remove failed. Run manually: /plugin remove helloagents',
+    return preserveTrackedModeOnFailure(
+      buildNativeResult(
+        removeClaudeGlobalPlugin(),
+        '已自动移除 Claude Code 插件',
+        'Claude Code plugin removed automatically',
+        'Claude Code 插件自动移除失败，请手动执行: /plugin remove helloagents',
+        'Claude Code plugin auto-remove failed. Run manually: /plugin remove helloagents',
+      ),
+      'global',
     )
   }
   if (host === 'gemini') {
     uninstallGeminiStandby(runtime.home)
-    return buildNativeResult(
-      removeGeminiGlobalExtension(),
-      '已自动移除 Gemini CLI 扩展',
-      'Gemini CLI extension removed automatically',
-      'Gemini CLI 扩展自动移除失败，请手动执行: gemini extensions uninstall helloagents',
-      'Gemini CLI extension auto-remove failed. Run manually: gemini extensions uninstall helloagents',
+    return preserveTrackedModeOnFailure(
+      buildNativeResult(
+        removeGeminiGlobalExtension(),
+        '已自动移除 Gemini CLI 扩展',
+        'Gemini CLI extension removed automatically',
+        'Gemini CLI 扩展自动移除失败，请手动执行: gemini extensions uninstall helloagents',
+        'Gemini CLI extension auto-remove failed. Run manually: gemini extensions uninstall helloagents',
+      ),
+      'global',
     )
   }
   return { skipped: !uninstallCodexGlobal(runtime.home) }
 }
 
-function installStandby(runtime) {
+function installStandby(runtime, previousModes = {}) {
   const results = {}
-  if (installClaudeStandby(runtime.home, runtime.pkgRoot)) {
-    runtime.ok(runtime.msg('Claude Code 已配置（standby 模式）', 'Claude Code configured (standby mode)'))
-    results.claude = {}
-  } else {
-    results.claude = { skipped: true }
-  }
-  if (installGeminiStandby(runtime.home, runtime.pkgRoot)) {
-    runtime.ok(runtime.msg('Gemini CLI 已配置（standby 模式）', 'Gemini CLI configured (standby mode)'))
-    results.gemini = {}
-  } else {
-    results.gemini = { skipped: true }
-  }
+  const claudeResult = installHostStandby(runtime, 'claude', { previousMode: previousModes.claude || '' })
+  reportHostAction(runtime, 'install', 'claude', 'standby', claudeResult)
+  results.claude = claudeResult.skipped ? { skipped: true } : claudeResult
+  const geminiResult = installHostStandby(runtime, 'gemini', { previousMode: previousModes.gemini || '' })
+  reportHostAction(runtime, 'install', 'gemini', 'standby', geminiResult)
+  results.gemini = geminiResult.skipped ? { skipped: true } : geminiResult
   if (installCodexStandby(runtime.home, runtime.pkgRoot)) {
     cleanupCodexGlobalResidueForStandby(runtime.home)
     runtime.ok(runtime.msg('Codex CLI 已配置（standby 模式）', 'Codex CLI configured (standby mode)'))
@@ -193,9 +263,9 @@ function installGlobal(runtime) {
   return results
 }
 
-export function installAllHosts(runtime, mode) {
+export function installAllHosts(runtime, mode, { previousModes = {} } = {}) {
   if (mode === 'global') return installGlobal(runtime)
-  return installStandby(runtime)
+  return installStandby(runtime, previousModes)
 }
 
 export function uninstallAllHosts(runtime) {
@@ -205,10 +275,10 @@ export function uninstallAllHosts(runtime) {
   uninstallCodexGlobal(runtime.home)
 }
 
-export function runHostLifecycle(runtime, action, host, mode) {
+export function runHostLifecycle(runtime, action, host, mode, options = {}) {
   const result = (action === 'cleanup' || action === 'uninstall')
     ? (mode === 'global' ? cleanupHostGlobal(runtime, host) : cleanupHostStandby(runtime, host))
-    : (mode === 'global' ? installHostGlobal(runtime, host) : installHostStandby(runtime, host))
+    : (mode === 'global' ? installHostGlobal(runtime, host) : installHostStandby(runtime, host, options))
 
   reportHostAction(runtime, action, host, mode, result)
   return result

package/scripts/cli-lifecycle.mjs

@@ -7,7 +7,7 @@ import {
   getHostLabel as resolveHostLabel,
   normalizeHost as normalizeLifecycleHost,
 } from './cli-host-detect.mjs'
-import { installAllHosts, runHostLifecycle, uninstallAllHosts } from './cli-lifecycle-hosts.mjs'
+import { installAllHosts, runHostLifecycle } from './cli-lifecycle-hosts.mjs'
 import { ensureDir, safeJson, safeWrite } from './cli-utils.mjs'
 
 export const HOSTS = ['claude', 'gemini', 'codex']
@@ -82,6 +82,18 @@ function syncTrackedHostMode(settings, host, result, mode) {
     setTrackedHostMode(settings, host, mode)
     return
   }
+  if (result?.trackedModeOnFailure) {
+    setTrackedHostMode(settings, host, result.trackedModeOnFailure)
+    return
+  }
+  clearTrackedHostMode(settings, host)
+}
+
+function syncCleanupTrackedHostMode(settings, host, result) {
+  if (result?.trackedModeOnFailure) {
+    setTrackedHostMode(settings, host, result.trackedModeOnFailure)
+    return
+  }
   clearTrackedHostMode(settings, host)
 }
 
@@ -129,6 +141,14 @@ export function getHostLabel(host) {
   return resolveHostLabel(host)
 }
 
+function resolvePreviousHostMode(settings, host) {
+  return detectHostMode(host) || getTrackedHostMode(settings, host) || ''
+}
+
+function buildPreviousHostModes(settings) {
+  return Object.fromEntries(HOSTS.map((host) => [host, resolvePreviousHostMode(settings, host)]))
+}
+
 function resolveHostMode(host, explicitMode, settings) {
   if (explicitMode) return explicitMode
   return detectHostMode(host)
@@ -167,6 +187,7 @@ export function switchMode(newMode) {
   const config = readSettings(true)
   const oldMode = config.install_mode || DEFAULTS.install_mode
   const isRefresh = oldMode === newMode
+  const previousModes = buildPreviousHostModes(config)
 
   if (!isRefresh) {
     config.install_mode = newMode
@@ -175,7 +196,7 @@ export function switchMode(newMode) {
     runtime.ok(runtime.msg(`当前已是 ${newMode} 模式，正在刷新安装`, `Already in ${newMode} mode, refreshing installation`))
   }
 
-  const results = installAllHosts(runtime, newMode)
+  const results = installAllHosts(runtime, newMode, { previousModes })
   clearAllTrackedHostModes(config)
   for (const host of HOSTS) {
     syncTrackedHostMode(config, host, results?.[host], newMode)
@@ -187,13 +208,25 @@ export function switchMode(newMode) {
 function runAllHostsLifecycle(action, explicitMode) {
   if (action === 'cleanup' || action === 'uninstall') {
     console.log(`\n  HelloAGENTS — ${runtime.msg('正在清理', 'Cleaning up')}\n`)
-    uninstallAllHosts(runtime)
+    const settings = existsSync(runtime.configFile) ? readSettings() : {}
+    const results = {}
+    for (const host of HOSTS) {
+      const mode = explicitMode || resolveHostMode(host, '', settings)
+      results[host] = runHostLifecycle(runtime, action, host, mode, {
+        previousMode: resolvePreviousHostMode(settings, host),
+      })
+    }
     if (existsSync(runtime.configFile)) {
-      const settings = readSettings()
-      clearAllTrackedHostModes(settings)
+      for (const host of HOSTS) {
+        syncCleanupTrackedHostMode(settings, host, results[host])
+      }
       writeSettings(settings)
     }
-    runtime.ok(runtime.msg('所有 CLI 配置已清理', 'All CLI configurations cleaned'))
+    const hasFailures = Object.values(results).some((result) => result?.ok === false)
+    runtime.ok(runtime.msg(
+      hasFailures ? '部分 CLI 仍需手动清理' : '所有 CLI 配置已清理',
+      hasFailures ? 'Some CLI cleanup still needs manual action' : 'All CLI configurations cleaned',
+    ))
     console.log(runtime.msg(
       '  ℹ ~/.helloagents/ 已保留（如需彻底清理请手动删除）\n  ℹ 已自动尝试移除 Claude/Gemini 插件或扩展；如宿主命令不可用，请手动执行对应移除命令',
       '  ℹ ~/.helloagents/ preserved (delete manually if desired)\n  ℹ Claude/Gemini plugin or extension removal was attempted automatically; if host commands are unavailable, remove them manually',
@@ -203,12 +236,14 @@ function runAllHostsLifecycle(action, explicitMode) {
   }
 
   const settings = readSettings(true)
+  const previousModes = buildPreviousHostModes(settings)
   if (!explicitMode) {
     for (const host of HOSTS) {
       const mode = resolveHostMode(host, '', settings)
-      const result = runHostLifecycle(runtime, action, host, mode)
-      if (!result.skipped && result.ok !== false) setTrackedHostMode(settings, host, mode)
-      else clearTrackedHostMode(settings, host)
+      const result = runHostLifecycle(runtime, action, host, mode, {
+        previousMode: previousModes[host],
+      })
+      syncTrackedHostMode(settings, host, result, mode)
     }
     writeSettings(settings)
     const modes = Object.values(settings.host_install_modes || {})
@@ -221,12 +256,10 @@ function runAllHostsLifecycle(action, explicitMode) {
 
   const mode = resolveInstallMode(explicitMode, settings)
   if (explicitMode) settings.install_mode = explicitMode
-  const results = installAllHosts(runtime, mode)
+  const results = installAllHosts(runtime, mode, { previousModes })
   settings.host_install_modes = {}
   for (const host of HOSTS) {
-    if (!results?.[host]?.skipped && results?.[host]?.ok !== false) {
-      settings.host_install_modes[host] = mode
-    }
+    syncTrackedHostMode(settings, host, results?.[host], mode)
   }
   writeSettings(settings)
   runtime.printInstallMsg(mode, action === 'update' ? 'refresh' : 'install')
@@ -242,11 +275,13 @@ export function runScopedLifecycle(action, rawArgs) {
   const shouldEnsure = action === 'install' || action === 'update'
   const settings = readSettings(shouldEnsure)
   const mode = resolveHostMode(host, explicitMode, settings)
-  const result = runHostLifecycle(runtime, action, host, mode)
+  const result = runHostLifecycle(runtime, action, host, mode, {
+    previousMode: resolvePreviousHostMode(settings, host),
+  })
 
   if (action === 'cleanup' || action === 'uninstall') {
     if (existsSync(runtime.configFile)) {
-      clearTrackedHostMode(settings, host)
+      syncCleanupTrackedHostMode(settings, host, result)
       writeSettings(settings)
     }
   } else if (!result.skipped) {

package/scripts/cli-messages.mjs

@@ -21,9 +21,9 @@ function codexGlobalStatus({ home, msg }) {
 
 function pluginCommands() {
   return [
-    '    Claude Code:  /plugin marketplace add hellowind777/helloagents',
+    '    Claude Code:  /plugin marketplace add https://github.com/hellowind777/helloagents.git',
     '                  /plugin install helloagents@helloagents',
-    '    Gemini CLI:   gemini extensions install https://github.com/hellowind777/helloagents',
+    '    Gemini CLI:   helloagents install gemini --global',
   ].join('\n')
 }
 
@@ -65,18 +65,18 @@ function renderInstallMessage(context, mode, state) {
 
   if (install) {
     return msg(
-      `\n  ✅ HelloAGENTS 已安装（standby 模式）！\n\n    Claude Code:  已自动配置（~/.claude/CLAUDE.md + hooks）\n    Gemini CLI:   已自动配置（~/.gemini/GEMINI.md）\n    Codex:        ${codexStandbyStatus(context)}\n\n  ${restartHint(msg)}\n\n  standby 模式下，hello-* 技能不会自动触发。\n  在项目中使用 ~wiki 或 ~init 仅创建/同步知识库；用 ~global 初始化项目级全局模式；也可用 ~command 按需调用。\n\n  切换模式：\n    helloagents --global    项目级全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）`,
-      `\n  ✅ HelloAGENTS installed (standby mode)!\n\n    Claude Code:  Auto-configured (~/.claude/CLAUDE.md + hooks)\n    Gemini CLI:   Auto-configured (~/.gemini/GEMINI.md)\n    Codex:        ${codexStandbyStatus(context)}\n\n  ${restartHint(msg)}\n\n  In standby mode, hello-* skills won't auto-trigger.\n  Use ~wiki or ~init to create or sync the KB only; use ~global to initialize project-level global mode; ~command stays available on demand.\n\n  Switch modes:\n    helloagents --global    Project-level global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)`,
+      `\n  ✅ HelloAGENTS 已安装（standby 模式）！\n\n    Claude Code:  已自动配置（~/.claude/CLAUDE.md + hooks）\n    Gemini CLI:   已自动配置（~/.gemini/GEMINI.md）\n    Codex:        ${codexStandbyStatus(context)}\n\n  ${restartHint(msg)}\n\n  standby 模式下，hello-* 技能不会自动触发。\n  在项目中使用 ~init 初始化完整项目工作流；未初始化时也可继续用 ~command 按需调用。\n\n  切换模式：\n    helloagents --global    宿主级全局部署（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）`,
+      `\n  ✅ HelloAGENTS installed (standby mode)!\n\n    Claude Code:  Auto-configured (~/.claude/CLAUDE.md + hooks)\n    Gemini CLI:   Auto-configured (~/.gemini/GEMINI.md)\n    Codex:        ${codexStandbyStatus(context)}\n\n  ${restartHint(msg)}\n\n  In standby mode, hello-* skills won't auto-trigger.\n  Use ~init to initialize the full project workflow; uninitialized repos can still use ~command on demand.\n\n  Switch modes:\n    helloagents --global    Host-wide global deployment (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)`,
     )
   }
 
   return msg(
     refresh
       ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`
-      : `  项目可通过 ~wiki 或 ~init 创建/同步知识库；用 ~global 初始化项目级全局模式；未初始化时仅注入轻量规则。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
+      : `  项目可通过 ~init 初始化完整工作流；未初始化时仅注入轻量规则。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
     refresh
       ? `  Standby mode refreshed; injected files and links were synchronized.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`
-      : `  Projects can use ~wiki or ~init to create/sync the KB; use ~global to initialize project-level global mode. Projects that are not initialized get lite rules only.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
+      : `  Projects can use ~init to initialize the full workflow; projects that are not initialized get lite rules only.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
   )
 }
 
@@ -90,7 +90,7 @@ HelloAGENTS v${pkgVersion} — The orchestration kernel for AI CLIs
   helloagents-js             ${msg('（受管宿主配置的跨平台稳定入口）', '(cross-platform stable entrypoint for managed host configs)')}
 
 ${msg('模式切换', 'Mode switching')}:
-  helloagents --global     ${msg('项目级全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）', 'Project-level global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)')}
+  helloagents --global     ${msg('宿主级全局部署（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）', 'Host-wide global deployment (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)')}
   helloagents --standby    ${msg('标准模式（非插件安装，hello-* 不自动触发，默认）', "Standby mode (non-plugin install, hello-* won't auto-trigger, default)")}
 
 ${msg('单 CLI 管理', 'Scoped CLI management')}:

package/scripts/cli-runtime-root.mjs

@@ -1,4 +1,4 @@
-import { mkdtempSync, realpathSync, renameSync } from 'node:fs'
+import { copyFileSync, existsSync, mkdtempSync, realpathSync, renameSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
 import { copyEntries, ensureDir, removeIfExists } from './cli-utils.mjs'
@@ -63,6 +63,13 @@ function retryTransientFs(operation) {
   throw lastError
 }
 
+function materializeGeminiHooks(root) {
+  const source = join(root, 'hooks', 'hooks-gemini.json')
+  const target = join(root, 'hooks', 'hooks.json')
+  if (!existsSync(source)) return
+  copyFileSync(source, target)
+}
+
 /** Sync package runtime files into the stable root without copying repo-only files. */
 export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
   const source = resolve(sourceRoot)
@@ -77,6 +84,7 @@ export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
 
   try {
     copyEntries(source, staging, RUNTIME_ROOT_ENTRIES)
+    materializeGeminiHooks(staging)
     retryTransientFs(() => {
       removeIfExists(target)
       renameSync(staging, target)

package/scripts/delivery-gate-messages.mjs

@@ -24,10 +24,8 @@ function issueHeading(issue) {
       return '任务缺少可交付元数据'
     case 'missing-contract':
       return '方案包缺少可信的结构化契约'
-    case 'missing-verify-evidence':
-      return '当前工作流缺少最新验证证据'
-    case 'missing-review-evidence':
-      return '当前工作流缺少最新审查证据'
+    case 'missing-qa-review-evidence':
+      return '当前工作流缺少最新 qa-review 证据'
     case 'missing-advisor-evidence':
       return '当前工作流缺少最新 advisor 证据'
     case 'missing-visual-evidence':
@@ -62,6 +60,9 @@ export function buildDeliveryBlockReason(issues, recommendation, gateHint) {
   if (issues.some((issue) => issue.type === 'missing-visual-evidence')) {
     lines.push('视觉验收动作：先写入当前会话 `artifacts/visual.json`，记录 `tooling`、`screensChecked`、`statesChecked`、`status` 和 `summary`，再报告完成。')
   }
+  if (issues.some((issue) => issue.type === 'missing-qa-review-evidence')) {
+    lines.push('质量闭环动作：先完成 `~qa` 或写入当前会话 `artifacts/qa-review.json`，记录结论、问题定位、验证命令与最新结果，再报告完成。')
+  }
   if (gateHint) {
     lines.push(gateHint)
   }

package/scripts/delivery-gate.mjs

@@ -9,10 +9,9 @@ import { fileURLToPath } from 'node:url'
 import { getAdvisorEvidenceStatus } from './advisor-state.mjs'
 import { getCloseoutEvidenceStatus } from './closeout-state.mjs'
 import { getAdvisorRequirement, getVisualValidationRequirement } from './plan-contract.mjs'
+import { getQaReviewEvidenceStatus } from './qa-review-state.mjs'
 import { getVisualEvidenceStatus } from './visual-state.mjs'
 import { buildDeliveryGateHint, getDeliveryAction, getWorkflowRecommendation, getWorkflowSnapshot } from './workflow-state.mjs'
-import { getReviewEvidenceStatus } from './review-state.mjs'
-import { getVerifyEvidenceStatus } from './verify-state.mjs'
 import { buildDeliveryBlockReason, buildUnderSpecifiedDetails } from './delivery-gate-messages.mjs'
 
 function selectGatePlans(snapshot) {
@@ -84,20 +83,12 @@ function collectPlanIssues(planEntries) {
   return issues
 }
 
-function collectEvidenceIssues(issues, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus) {
-  if (verificationStatus?.required && verificationStatus.status !== 'valid') {
+function collectEvidenceIssues(issues, qaStatus, advisorStatus, visualStatus, closeoutStatus) {
+  if (qaStatus?.required && qaStatus.status !== 'valid') {
     issues.push({
-      type: 'missing-verify-evidence',
+      type: 'missing-qa-review-evidence',
       planName: 'delivery',
-      details: verificationStatus.details,
-    })
-  }
-
-  if (reviewStatus?.required && reviewStatus.status !== 'valid') {
-    issues.push({
-      type: 'missing-review-evidence',
-      planName: 'delivery',
-      details: reviewStatus.details,
+      details: qaStatus.details,
     })
   }
   if (advisorStatus?.required && advisorStatus.status !== 'valid') {
@@ -124,9 +115,9 @@ function collectEvidenceIssues(issues, verificationStatus, reviewStatus, advisor
   }
 }
 
-function collectGateIssues(planEntries, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus) {
+function collectGateIssues(planEntries, qaStatus, advisorStatus, visualStatus, closeoutStatus) {
   const issues = collectPlanIssues(planEntries)
-  collectEvidenceIssues(issues, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
+  collectEvidenceIssues(issues, qaStatus, advisorStatus, visualStatus, closeoutStatus)
   return issues
 }
 
@@ -143,11 +134,10 @@ export function evaluateDeliveryGate(data = {}) {
   const workflowOptions = { payload: data }
   const snapshot = getWorkflowSnapshot(cwd, workflowOptions)
   const recommendation = getWorkflowRecommendation(cwd, workflowOptions)
-  const verificationStatus = getVerifyEvidenceStatus(cwd, workflowOptions)
   const deliveryAction = getDeliveryAction(cwd, workflowOptions)
   const gatePlans = selectGatePlans(snapshot)
-  const reviewStatus = getReviewEvidenceStatus(cwd, {
-    required: deliveryAction?.phase === 'verify' && deliveryAction?.mode === 'review-first',
+  const qaStatus = getQaReviewEvidenceStatus(cwd, {
+    required: deliveryAction?.phase === 'qa' || deliveryAction?.phase === 'consolidate',
     ...workflowOptions,
   })
   if (gatePlans.length === 0) {
@@ -169,8 +159,7 @@ export function evaluateDeliveryGate(data = {}) {
   })
   const closeoutRequired = (
     gatePlans.every((entry) => entry.missingFiles.length === 0 && entry.templateIssues.length === 0 && entry.taskSummary.total > 0 && entry.taskSummary.open === 0 && entry.taskSummary.underSpecifiedCount === 0)
-    && (!verificationStatus.required || verificationStatus.status === 'valid')
-    && (!reviewStatus.required || reviewStatus.status === 'valid')
+    && (!qaStatus.required || qaStatus.status === 'valid')
     && (!advisorStatus.required || advisorStatus.status === 'valid')
     && (!visualStatus.required || visualStatus.status === 'valid')
   )
@@ -179,7 +168,7 @@ export function evaluateDeliveryGate(data = {}) {
     ...workflowOptions,
   })
 
-  const issues = collectGateIssues(gatePlans, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
+  const issues = collectGateIssues(gatePlans, qaStatus, advisorStatus, visualStatus, closeoutStatus)
   if (issues.length === 0) {
     return { suppressOutput: true }
   }

package/scripts/guard.mjs

@@ -76,7 +76,7 @@ function buildHighRiskGate(matches, cwd, payload = {}) {
   if (!recommendation) return null
   if (matches.some((match) => match.gate === 'post-verify')) {
     return {
-      reason: `[HelloAGENTS Guard] 已阻止 T3 命令：当前工作流尚未进入 VERIFY / CONSOLIDATE。\n当前工作流：${recommendation.summary}\n处理路径：${recommendation.nextPath}\n${recommendation.guidance}`,
+      reason: `[HelloAGENTS Guard] 已阻止 T3 命令：当前工作流尚未进入 QA / CONSOLIDATE。\n当前工作流：${recommendation.summary}\n处理路径：${recommendation.nextPath}\n${recommendation.guidance}`,
     }
   }
   if (matches.some((match) => match.gate === 'plan-first') && recommendation.nextCommand === 'plan') {