helloagents 3.0.33 → 3.0.35

package/install.ps1

@@ -15,6 +15,7 @@ $Target = if ($env:HELLOAGENTS_TARGET) { $env:HELLOAGENTS_TARGET } else { "" }
 $Mode = if ($env:HELLOAGENTS_MODE) { $env:HELLOAGENTS_MODE } else { "" }
 $Branch = if ($env:HELLOAGENTS_BRANCH) { $env:HELLOAGENTS_BRANCH } else { "" }
 $Package = if ($env:HELLOAGENTS_PACKAGE) { $env:HELLOAGENTS_PACKAGE } else { "" }
+$HasExplicitPackage = [bool]$Package
 
 if ($env:HELLOAGENTS) {
     $Parts = $env:HELLOAGENTS.Split(":", 2)
@@ -53,6 +54,23 @@ function Invoke-Npm {
     }
 }
 
+function Clear-HelloagentsEnv {
+    foreach ($name in @(
+        "HELLOAGENTS",
+        "HELLOAGENTS_ACTION",
+        "HELLOAGENTS_TARGET",
+        "HELLOAGENTS_HOST",
+        "HELLOAGENTS_MODE",
+        "HELLOAGENTS_BRANCH",
+        "HELLOAGENTS_PACKAGE",
+        "HELLOAGENTS_DEPLOY"
+    )) {
+        Remove-Item "Env:$name" -ErrorAction SilentlyContinue
+    }
+}
+
+Clear-HelloagentsEnv
+
 function Enable-PostinstallDeploy {
     $env:HELLOAGENTS_DEPLOY = "1"
     $env:HELLOAGENTS_TARGET = $Target
@@ -93,7 +111,7 @@ switch ($Action) {
         Invoke-Npm -NpmArgs @("install", "-g", $Package)
     }
     "update" {
-        if ($Branch -or $env:HELLOAGENTS_PACKAGE) {
+        if ($Branch -or $HasExplicitPackage) {
             Invoke-Npm -NpmArgs @("install", "-g", $Package)
         } else {
             & npm update -g helloagents
@@ -107,14 +125,14 @@ switch ($Action) {
         Cleanup-Hosts
     }
     "switch-branch" {
-        if (-not $Branch -and -not $env:HELLOAGENTS_PACKAGE) {
+        if (-not $Branch -and -not $HasExplicitPackage) {
             throw "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for switch-branch"
         }
         Invoke-Npm -NpmArgs @("install", "-g", $Package)
         Sync-Hosts
     }
     "branch" {
-        if (-not $Branch -and -not $env:HELLOAGENTS_PACKAGE) {
+        if (-not $Branch -and -not $HasExplicitPackage) {
             throw "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for branch"
         }
         Invoke-Npm -NpmArgs @("install", "-g", $Package)

package/install.sh

@@ -16,6 +16,10 @@ TARGET="${HELLOAGENTS_TARGET:-}"
 MODE="${HELLOAGENTS_MODE:-}"
 BRANCH="${HELLOAGENTS_BRANCH:-}"
 PACKAGE="${HELLOAGENTS_PACKAGE:-}"
+HAS_EXPLICIT_PACKAGE=0
+if [ -n "$PACKAGE" ]; then
+  HAS_EXPLICIT_PACKAGE=1
+fi
 
 if [ -n "${HELLOAGENTS:-}" ]; then
   SPEC_TARGET="${HELLOAGENTS%%:*}"
@@ -55,6 +59,19 @@ if [ -z "$PACKAGE" ]; then
   fi
 fi
 
+clear_lifecycle_env() {
+  unset HELLOAGENTS
+  unset HELLOAGENTS_ACTION
+  unset HELLOAGENTS_TARGET
+  unset HELLOAGENTS_HOST
+  unset HELLOAGENTS_MODE
+  unset HELLOAGENTS_BRANCH
+  unset HELLOAGENTS_PACKAGE
+  unset HELLOAGENTS_DEPLOY
+}
+
+clear_lifecycle_env
+
 sync_hosts() {
   if [ "$TARGET" = "all" ]; then
     if [ -n "$MODE" ]; then
@@ -115,7 +132,7 @@ case "$ACTION" in
     npm install -g "$PACKAGE"
     ;;
   update)
-    if [ -n "$BRANCH" ] || [ -n "${HELLOAGENTS_PACKAGE:-}" ]; then
+    if [ -n "$BRANCH" ] || [ "$HAS_EXPLICIT_PACKAGE" -eq 1 ]; then
       npm install -g "$PACKAGE"
     else
       npm update -g helloagents || npm install -g helloagents
@@ -126,7 +143,7 @@ case "$ACTION" in
     cleanup_hosts
     ;;
   switch-branch|branch)
-    if [ -z "$BRANCH" ] && [ -z "${HELLOAGENTS_PACKAGE:-}" ]; then
+    if [ -z "$BRANCH" ] && [ "$HAS_EXPLICIT_PACKAGE" -ne 1 ]; then
       echo "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for switch-branch" >&2
       exit 1
     fi

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "helloagents",
-  "version": "3.0.33",
+  "version": "3.0.35",
   "type": "module",
-  "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
+  "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, unified QA gates, safety guards, and notifications.",
   "author": "HelloWind",
   "license": "Apache-2.0",
   "homepage": "https://github.com/hellowind777/helloagents",

package/scripts/capability-registry.mjs

@@ -30,10 +30,12 @@ export function selectCapabilities({ cwd, skillName = '', options = {} }) {
         : '独立 advisor：当前契约要求进入收尾前写当前会话 `artifacts/advisor.json`，记录 advisor reason、focus、consultedSources 与结论。',
     })
   }
-  if (plan?.contract?.verifyMode === 'review-first') {
+  if ((plan?.contract?.qaFocus || []).length > 0) {
     capabilities.push({
-      id: 'review-evaluator',
-      description: '审查优先：当前验证主路径是 review-first，先做 hello-review，再做 hello-verify。',
+      id: 'qa-evaluator',
+      description: plan?.contract?.qaMode === 'deep'
+        ? `深度 qa-review：当前收尾主路径是 ~qa，按阻断性质量闭环执行；重点：${plan.contract.qaFocus.join('；')}。`
+        : `统一 qa-review：当前收尾主路径是 ~qa，重点：${plan.contract.qaFocus.join('；')}。`,
     })
   }
   if (plan?.contract?.ui?.required || existsSync(getProjectDesignContractPath(cwd))) {

package/scripts/cli-doctor-codex.mjs

@@ -1,3 +1,4 @@
+import { spawnSync } from 'node:child_process'
 import { existsSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
 
@@ -76,6 +77,141 @@ function buildDoctorIssue(runtime, code, cn, en) {
   }
 }
 
+function normalizeDoctorText(value = '') {
+  return String(value || '').replace(/\s+/g, ' ').trim()
+}
+
+function readFirstInteger(value = '') {
+  const match = String(value || '').match(/-?\d+/)
+  return match ? Number.parseInt(match[0], 10) : null
+}
+
+function readNativeDoctorDetail(checks, checkId, detailKey) {
+  return String(checks?.[checkId]?.details?.[detailKey] || '').trim()
+}
+
+function readNativeDoctorList(value = '') {
+  const normalized = normalizeDoctorText(value)
+  if (!normalized || normalized === '(none)') return []
+  return normalized.split(/\s*,\s*/).map((entry) => entry.trim()).filter(Boolean)
+}
+
+function summarizeNativeCodexDoctor(payload = {}) {
+  const checks = payload?.checks || {}
+  const configCheck = checks['config.load'] || {}
+  const sandboxCheck = checks['sandbox.helpers'] || {}
+  const mcpCount = readFirstInteger(readNativeDoctorDetail(checks, 'config.load', 'mcp servers'))
+  const fsSandbox = readNativeDoctorDetail(checks, 'sandbox.helpers', 'filesystem sandbox').toLowerCase()
+  const linuxHelper = readNativeDoctorDetail(checks, 'sandbox.helpers', 'codex-linux-sandbox helper').toLowerCase()
+    || readNativeDoctorDetail(checks, 'sandbox.helpers', 'linux helper').toLowerCase()
+  const execveHelper = readNativeDoctorDetail(checks, 'sandbox.helpers', 'execve wrapper helper').toLowerCase()
+
+  let sandboxAvailable = null
+  if (sandboxCheck && Object.keys(sandboxCheck).length > 0) {
+    sandboxAvailable = Boolean(
+      (fsSandbox && !fsSandbox.includes('unrestricted'))
+      || (linuxHelper && linuxHelper !== 'none')
+      || (execveHelper && execveHelper !== 'none')
+    )
+  }
+
+  return {
+    version: String(payload?.codexVersion || '').trim(),
+    configPath: readNativeDoctorDetail(checks, 'config.load', 'config.toml'),
+    resolvedProvider: readNativeDoctorDetail(checks, 'config.load', 'model provider'),
+    resolvedModel: readNativeDoctorDetail(checks, 'config.load', 'model'),
+    sandboxAvailable,
+    mcpPresent: typeof mcpCount === 'number' ? mcpCount > 0 : false,
+    skillsSelected: readNativeDoctorList(
+      readNativeDoctorDetail(checks, 'config.load', 'selected skills')
+      || readNativeDoctorDetail(checks, 'config.load', 'skills selected')
+    ),
+  }
+}
+
+function summarizeNativeCodexDoctorOutput(payload = {}) {
+  const checks = Object.values(payload?.checks || {})
+  const failedCheck = checks.find((check) => check?.status === 'fail')
+  if (failedCheck?.issues?.length) {
+    return normalizeDoctorText(failedCheck.issues.map((issue) => issue?.cause || issue?.measured || '').filter(Boolean).join(' | '))
+  }
+  if (failedCheck?.summary) return normalizeDoctorText(failedCheck.summary)
+
+  const warningCheck = checks.find((check) => check?.status === 'warn')
+  if (warningCheck?.issues?.length) {
+    return normalizeDoctorText(warningCheck.issues.map((issue) => issue?.cause || issue?.measured || '').filter(Boolean).join(' | '))
+  }
+  if (warningCheck?.summary) return normalizeDoctorText(warningCheck.summary)
+
+  return ''
+}
+
+function inspectNativeCodexDoctor(runtime) {
+  try {
+    const result = spawnSync('codex', ['doctor', '--json'], {
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        HOME: runtime.home || process.env.HOME,
+        USERPROFILE: runtime.home || process.env.USERPROFILE,
+        NO_COLOR: process.env.NO_COLOR || '1',
+      },
+      encoding: 'utf-8',
+      timeout: 20_000,
+      windowsHide: true,
+    })
+
+    if (result.error) {
+      return {
+        available: false,
+        ok: false,
+        status: '',
+        summary: null,
+        output: normalizeDoctorText(result.error.message || ''),
+      }
+    }
+
+    const stdout = String(result.stdout || '').trim()
+    if (!stdout) {
+      return {
+        available: true,
+        ok: result.status === 0,
+        status: '',
+        summary: null,
+        output: normalizeDoctorText(result.stderr || ''),
+      }
+    }
+
+    try {
+      const payload = JSON.parse(stdout)
+      const status = String(payload?.overallStatus || '').trim().toLowerCase()
+      return {
+        available: true,
+        ok: status ? status !== 'fail' : result.status === 0,
+        status,
+        summary: summarizeNativeCodexDoctor(payload),
+        output: summarizeNativeCodexDoctorOutput(payload),
+      }
+    } catch {
+      return {
+        available: true,
+        ok: result.status === 0,
+        status: '',
+        summary: null,
+        output: normalizeDoctorText(stdout || result.stderr || ''),
+      }
+    }
+  } catch (error) {
+    return {
+      available: false,
+      ok: false,
+      status: '',
+      summary: null,
+      output: normalizeDoctorText(error?.message || ''),
+    }
+  }
+}
+
 function normalizeDoctorMode(mode = '') {
   return mode || 'none'
 }
@@ -209,6 +345,7 @@ export function inspectCodexDoctor(runtime, settings) {
   const host = 'codex'
   const trackedMode = normalizeDoctorMode(runtime.getTrackedHostMode(settings, host))
   const detectedMode = normalizeDoctorMode(runtime.detectHostMode(host))
+  const nativeDoctor = inspectNativeCodexDoctor(runtime)
   const { checks, pluginVersion, cacheVersion } = buildCodexChecks(runtime, settings, trackedMode, detectedMode)
   checks.pluginVersionMatch = pluginVersion ? pluginVersion === runtime.pkgVersion : false
   checks.pluginCacheVersionMatch = cacheVersion ? cacheVersion === runtime.pkgVersion : false
@@ -230,7 +367,19 @@ export function inspectCodexDoctor(runtime, settings) {
   if (!checks.pluginCacheVersionMatch && !cacheVersion && detectedMode === 'global') notes.push(runtime.msg('未读到 global 插件缓存版本信息', 'Global plugin cache version was not readable'))
   if (detectedMode !== 'none' && !checks.codexGoalsFeature) notes.push(runtime.msg('Codex /goal 未启用；如需长程执行，可运行 `helloagents codex goals enable`。', 'Codex /goal is not enabled; run `helloagents codex goals enable` if you need long-running goals.'))
   if (detectedMode !== 'none' && checks.legacyCodexHooksFeature) notes.push(runtime.msg('检测到旧版 `codex_hooks`；HelloAGENTS 只兼容 Codex 最新版，请移除旧 key。', 'Legacy `codex_hooks` was detected; HelloAGENTS targets latest Codex only, so remove the old key.'))
+  if (!nativeDoctor.available) notes.push(runtime.msg('未检测到原生 `codex doctor`；当前仅检查 HelloAGENTS 受管覆盖层。', 'Native `codex doctor` was not available; only the HelloAGENTS managed overlay was checked.'))
 
   const status = summarizeDoctorStatus(issues, { trackedMode, detectedMode })
-  return { host, label: runtime.getHostLabel(host), trackedMode, detectedMode, status, checks, issues, notes, suggestedFix: suggestCodexDoctorFix(status, trackedMode) }
+  return {
+    host,
+    label: runtime.getHostLabel(host),
+    trackedMode,
+    detectedMode,
+    status,
+    checks,
+    nativeDoctor,
+    issues,
+    notes,
+    suggestedFix: suggestCodexDoctorFix(status, trackedMode),
+  }
 }

package/scripts/cli-doctor-render.mjs

@@ -20,7 +20,8 @@ export function printDoctorText(runtime, report) {
     if (entry.nativeDoctor) {
       console.log(`  native_doctor.available: ${entry.nativeDoctor.available ? 'ok' : 'missing'}`)
       if (entry.nativeDoctor.available) {
-        console.log(`  native_doctor.ok: ${entry.nativeDoctor.ok ? 'ok' : 'missing'}`)
+        console.log(`  native_doctor.ok: ${entry.nativeDoctor.ok ? 'ok' : 'fail'}`)
+        if (entry.nativeDoctor.status) console.log(`  native_doctor.status: ${entry.nativeDoctor.status}`)
       }
       if (entry.nativeDoctor.summary) {
         if (entry.nativeDoctor.summary.version) console.log(`  native_doctor.version: ${entry.nativeDoctor.summary.version}`)

package/scripts/cli-lifecycle-hosts.mjs

@@ -46,6 +46,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 命令' }
@@ -70,8 +77,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 +97,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)
@@ -137,41 +179,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 +235,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 +247,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

@@ -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')}: