helloagents 3.0.12 → 3.0.16-beta.1

package/scripts/cli-doctor.mjs

@@ -2,14 +2,20 @@ import { existsSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_CONFIG_HEADER, CODEX_PLUGIN_NAME } from './cli-codex.mjs'
+import {
+  CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
+  CODEX_MANAGED_NOTIFY_VALUE,
+} from './cli-codex-config.mjs'
 import { DEFAULTS } from './cli-config.mjs'
 import { printDoctorText } from './cli-doctor-render.mjs'
+import { buildRuntimeCarrier } from './cli-runtime-carrier.mjs'
 import { readTopLevelTomlLine } from './cli-toml.mjs'
-import { loadHooksWithAbsPath, safeJson, safeRead } from './cli-utils.mjs'
+import { loadHooksWithCliEntry, safeJson, safeRead } from './cli-utils.mjs'
 
 const runtime = {
   home: '',
   pkgRoot: '',
+  sourceRoot: '',
   pkgVersion: '',
   msg: (cn, en) => en || cn,
   readSettings: () => ({}),
@@ -69,15 +75,16 @@ function pickManagedHooks(hooks) {
 }
 
 function readExpectedHooks(hooksFile, pathVar) {
-  return pickManagedHooks(loadHooksWithAbsPath(runtime.pkgRoot, hooksFile, pathVar)?.hooks || {})
+  return pickManagedHooks(loadHooksWithCliEntry(runtime.pkgRoot, hooksFile, pathVar)?.hooks || {})
 }
 
 function managedHooksMatch(actualHooks, expectedHooks) {
   return stringifySorted(pickManagedHooks(actualHooks || {})) === stringifySorted(expectedHooks || {})
 }
 
-function readBootstrapContent(fileName) {
-  return normalizeText(safeRead(join(runtime.pkgRoot, fileName)) || '')
+function readExpectedCarrierContent(fileName, settings) {
+  const bootstrap = safeRead(join(runtime.pkgRoot, fileName)) || ''
+  return normalizeText(buildRuntimeCarrier(bootstrap, settings))
 }
 
 function buildDoctorIssue(code, cn, en) {
@@ -104,7 +111,7 @@ function suggestDoctorFix(host, status, trackedMode) {
     return `helloagents update ${host}${trackedMode && trackedMode !== 'none' ? ` --${trackedMode}` : ''}`
   }
   if (status === 'manual-plugin') {
-    if (host === 'claude') return '/plugin marketplace add hellowind777/helloagents'
+    if (host === 'claude') return '/plugin marketplace add hellowind777/helloagents; /plugin install helloagents@helloagents'
     if (host === 'gemini') return 'gemini extensions install https://github.com/hellowind777/helloagents'
   }
   if (status === 'not-installed') {
@@ -126,12 +133,13 @@ function inspectClaudeDoctor(settings) {
   const expectedHooks = readExpectedHooks('hooks-claude.json', '${CLAUDE_PLUGIN_ROOT}')
   const checks = {
     carrierMarker: (safeRead(join(claudeDir, 'CLAUDE.md')) || '').includes('HELLOAGENTS_START'),
-    carrierContentMatch: extractManagedCarrierContent(join(claudeDir, 'CLAUDE.md')) === readBootstrapContent('bootstrap-lite.md'),
+    carrierContentMatch: extractManagedCarrierContent(join(claudeDir, 'CLAUDE.md'))
+      === readExpectedCarrierContent('bootstrap-lite.md', settings),
     homeLink: safeRealTarget(join(claudeDir, 'helloagents')) === runtime.pkgRoot,
     settingsHooks: JSON.stringify(claudeSettings.hooks || {}).includes('helloagents'),
     settingsHooksMatch: managedHooksMatch(claudeSettings.hooks || {}, expectedHooks),
     settingsPermission: Array.isArray(claudeSettings.permissions?.allow)
-      && claudeSettings.permissions.allow.includes('Read(~/.claude/helloagents/**)'),
+      && claudeSettings.permissions.allow.includes('Read(~/.helloagents/helloagents/**)'),
   }
 
   const issues = []
@@ -142,15 +150,15 @@ function inspectClaudeDoctor(settings) {
   if (detectedMode === 'standby') {
     if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 规则文件缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
     if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 规则文件内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
-    if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向当前包根目录', 'Standby home link is missing or points to a different package root'))
+    if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向稳定运行根目录', 'Standby home link is missing or points to a different runtime root'))
     if (!checks.settingsHooks) issues.push(buildDoctorIssue('standby-hooks-missing', 'standby settings hooks 缺失', 'Standby settings hooks are missing'))
     if (checks.settingsHooks && !checks.settingsHooksMatch) issues.push(buildDoctorIssue('standby-hooks-drift', 'standby settings hooks 与当前 hooks 配置不一致', 'Standby settings hooks differ from the current hook configuration'))
     if (!checks.settingsPermission) issues.push(buildDoctorIssue('standby-permission-missing', 'standby Claude 权限注入缺失', 'Standby Claude permission injection is missing'))
   }
   if (trackedMode === 'global') {
     notes.push(runtime.msg(
-      'Claude Code 的 global 模式插件需手动安装；doctor 只检查 standby 残留，不直接探测插件状态。',
-      'Claude Code global-mode plugins are manual; doctor only checks for standby residue and does not inspect plugin state directly.',
+      'Claude Code 的 global 模式由宿主插件系统管理；doctor 只检查 standby 残留，不直接探测插件状态。',
+      'Claude Code global mode is managed by the host plugin system; doctor only checks for standby residue and does not inspect plugin state directly.',
     ))
     if (checks.carrierMarker || checks.homeLink || checks.settingsHooks || checks.settingsPermission) {
       issues.push(buildDoctorIssue('global-standby-residue', 'global 模式下仍残留 standby 注入/链接', 'Standby injections or links still remain while the host is tracked as global'))
@@ -176,7 +184,8 @@ function inspectGeminiDoctor(settings) {
   const expectedHooks = readExpectedHooks('hooks.json', '${extensionPath}')
   const checks = {
     carrierMarker: (safeRead(join(geminiDir, 'GEMINI.md')) || '').includes('HELLOAGENTS_START'),
-    carrierContentMatch: extractManagedCarrierContent(join(geminiDir, 'GEMINI.md')) === readBootstrapContent('bootstrap-lite.md'),
+    carrierContentMatch: extractManagedCarrierContent(join(geminiDir, 'GEMINI.md'))
+      === readExpectedCarrierContent('bootstrap-lite.md', settings),
     homeLink: safeRealTarget(join(geminiDir, 'helloagents')) === runtime.pkgRoot,
     settingsHooks: JSON.stringify(geminiSettings.hooks || {}).includes('helloagents'),
     settingsHooksMatch: managedHooksMatch(geminiSettings.hooks || {}, expectedHooks),
@@ -190,14 +199,14 @@ function inspectGeminiDoctor(settings) {
   if (detectedMode === 'standby') {
     if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 规则文件缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
     if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 规则文件内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
-    if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向当前包根目录', 'Standby home link is missing or points to a different package root'))
+    if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向稳定运行根目录', 'Standby home link is missing or points to a different runtime root'))
     if (!checks.settingsHooks) issues.push(buildDoctorIssue('standby-hooks-missing', 'standby settings hooks 缺失', 'Standby settings hooks are missing'))
     if (checks.settingsHooks && !checks.settingsHooksMatch) issues.push(buildDoctorIssue('standby-hooks-drift', 'standby settings hooks 与当前 hooks 配置不一致', 'Standby settings hooks differ from the current hook configuration'))
   }
   if (trackedMode === 'global') {
     notes.push(runtime.msg(
-      'Gemini CLI 的 global 模式扩展需手动安装；doctor 只检查 standby 残留，不直接探测扩展状态。',
-      'Gemini CLI global-mode extensions are manual; doctor only checks for standby residue and does not inspect extension state directly.',
+      'Gemini CLI 的 global 模式由宿主扩展系统管理；doctor 只检查 standby 残留，不直接探测扩展状态。',
+      'Gemini CLI global mode is managed by the host extension system; doctor only checks for standby residue and does not inspect extension state directly.',
     ))
     if (checks.carrierMarker || checks.homeLink || checks.settingsHooks) {
       issues.push(buildDoctorIssue('global-standby-residue', 'global 模式下仍残留 standby 注入/链接', 'Standby injections or links still remain while the host is tracked as global'))
@@ -217,12 +226,12 @@ function inspectGeminiDoctor(settings) {
 function appendCodexStandbyIssues(issues, checks) {
   if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 规则文件缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
   if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 规则文件内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
-  if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向当前包根目录', 'Standby home link is missing or points to a different package root'))
+  if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向稳定运行根目录', 'Standby home link is missing or points to a different runtime root'))
   if (!checks.modelInstructionsFile) issues.push(buildDoctorIssue('standby-model-instructions-missing', 'standby config 缺少受管 model_instructions_file', 'Standby config is missing the managed model_instructions_file'))
   if (checks.modelInstructionsFile && !checks.modelInstructionsPathMatch) issues.push(buildDoctorIssue('standby-model-instructions-drift', 'standby model_instructions_file 未指向受管 `~/.codex/AGENTS.md`', 'Standby model_instructions_file does not point to the managed `~/.codex/AGENTS.md`'))
   if (!checks.codexNotify) issues.push(buildDoctorIssue('standby-notify-missing', 'standby notify 配置缺失', 'Standby notify configuration is missing'))
-  if (checks.codexNotify && !checks.notifyPathMatch) issues.push(buildDoctorIssue('standby-notify-drift', 'standby notify 路径未指向当前包根目录', 'Standby notify path does not point to the current package root'))
-  if (checks.pluginRoot || checks.pluginCache || checks.marketplaceEntry || checks.pluginEnabled || checks.globalNotifyPath) {
+  if (checks.codexNotify && !checks.notifyPathMatch) issues.push(buildDoctorIssue('standby-notify-drift', 'standby notify 未使用受管命令入口', 'Standby notify does not use the managed command entrypoint'))
+  if (checks.pluginRoot || checks.pluginCache || checks.marketplaceEntry || checks.pluginEnabled) {
     issues.push(buildDoctorIssue('standby-global-residue', 'standby 模式下仍残留 global 插件文件或配置', 'Global plugin artifacts still remain while Codex is in standby mode'))
   }
 }
@@ -239,8 +248,8 @@ function appendCodexGlobalIssues(issues, checks, pluginVersion, cacheVersion) {
   if (!checks.pluginEnabled) issues.push(buildDoctorIssue('global-plugin-disabled', 'global config 中缺少插件启用段', 'Global plugin enablement block is missing from config'))
   if (!checks.modelInstructionsFile) issues.push(buildDoctorIssue('global-model-instructions-missing', 'global config 缺少受管 model_instructions_file', 'Global config is missing the managed model_instructions_file'))
   if (checks.modelInstructionsFile && !checks.modelInstructionsPathMatch) issues.push(buildDoctorIssue('global-model-instructions-drift', 'global model_instructions_file 未指向受管 `~/.codex/AGENTS.md`', 'Global model_instructions_file does not point to the managed `~/.codex/AGENTS.md`'))
-  if (!checks.globalNotifyPath) issues.push(buildDoctorIssue('global-notify-missing', 'global notify 路径缺失', 'Global notify path is missing'))
-  if (checks.globalNotifyPath && !checks.globalNotifyPathMatch) issues.push(buildDoctorIssue('global-notify-drift', 'global notify 路径未指向当前插件根目录', 'Global notify path does not point to the current plugin root'))
+  if (!checks.codexNotify) issues.push(buildDoctorIssue('global-notify-missing', 'global notify 配置缺失', 'Global notify configuration is missing'))
+  if (checks.codexNotify && !checks.globalNotifyPathMatch) issues.push(buildDoctorIssue('global-notify-drift', 'global notify 未使用受管命令入口', 'Global notify does not use the managed command entrypoint'))
   if (pluginVersion && !checks.pluginVersionMatch) issues.push(buildDoctorIssue('global-plugin-version-drift', 'global 插件根目录版本与当前包版本不一致', 'Global plugin root version does not match the current package version'))
   if (cacheVersion && !checks.pluginCacheVersionMatch) issues.push(buildDoctorIssue('global-plugin-cache-version-drift', 'global 插件缓存版本与当前包版本不一致', 'Global plugin cache version does not match the current package version'))
   if (checks.homeLink) {
@@ -262,31 +271,31 @@ function inspectCodexDoctor(settings) {
   const homeLinkTarget = safeRealTarget(join(codexDir, 'helloagents'))
   const pkgRootTarget = safeRealTarget(runtime.pkgRoot) || normalizePath(runtime.pkgRoot)
   const pluginRootTarget = safeRealTarget(pluginRoot) || normalizePath(pluginRoot)
-  const standbyNotifyPath = normalizePath(join(runtime.pkgRoot, 'scripts', 'notify.mjs'))
-  const globalNotifyPath = normalizePath(join(pluginRoot, 'scripts', 'notify.mjs'))
-  const managedHomeCarrierPath = normalizePath(join(codexDir, 'AGENTS.md'))
   const modelInstructionsLine = readTopLevelTomlLine(codexConfig, 'model_instructions_file')
   const expectedHomeCarrier = (detectedMode === 'global' || (detectedMode === 'none' && trackedMode === 'global'))
     ? 'bootstrap.md'
     : 'bootstrap-lite.md'
   const checks = {
     carrierMarker: (safeRead(join(codexDir, 'AGENTS.md')) || '').includes('HELLOAGENTS_START'),
-    carrierContentMatch: extractManagedCarrierContent(join(codexDir, 'AGENTS.md')) === readBootstrapContent(expectedHomeCarrier),
+    carrierContentMatch: extractManagedCarrierContent(join(codexDir, 'AGENTS.md'))
+      === readExpectedCarrierContent(expectedHomeCarrier, settings),
     homeLink: homeLinkTarget === pkgRootTarget,
     globalHomeLink: homeLinkTarget === pluginRootTarget,
     modelInstructionsFile: !!modelInstructionsLine,
     modelInstructionsPathMatch: !!modelInstructionsLine
-      && normalizePath(modelInstructionsLine).includes(`"${managedHomeCarrierPath}"`),
+      && normalizePath(modelInstructionsLine).includes(`"${CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH}"`),
     codexNotify: codexConfig.includes('codex-notify'),
-    notifyPathMatch: codexConfig.includes(standbyNotifyPath),
+    notifyPathMatch: codexConfig.includes(CODEX_MANAGED_NOTIFY_VALUE),
     pluginRoot: existsSync(pluginRoot),
     pluginCache: existsSync(pluginCacheRoot),
-    pluginCarrierMatch: normalizeText(safeRead(join(pluginRoot, 'AGENTS.md')) || '') === readBootstrapContent('bootstrap.md'),
-    pluginCacheCarrierMatch: normalizeText(safeRead(join(pluginCacheRoot, 'AGENTS.md')) || '') === readBootstrapContent('bootstrap.md'),
+    pluginCarrierMatch: normalizeText(safeRead(join(pluginRoot, 'AGENTS.md')) || '')
+      === readExpectedCarrierContent('bootstrap.md', settings),
+    pluginCacheCarrierMatch: normalizeText(safeRead(join(pluginCacheRoot, 'AGENTS.md')) || '')
+      === readExpectedCarrierContent('bootstrap.md', settings),
     marketplaceEntry: Array.isArray(marketplace.plugins) && marketplace.plugins.some((plugin) => plugin?.name === CODEX_PLUGIN_NAME),
     pluginEnabled: codexConfig.includes(CODEX_PLUGIN_CONFIG_HEADER) && codexConfig.includes('enabled = true'),
-    globalNotifyPath: codexConfig.includes('/plugins/helloagents/scripts/notify.mjs'),
-    globalNotifyPathMatch: codexConfig.includes(globalNotifyPath),
+    globalNotifyPath: codexConfig.includes('codex-notify'),
+    globalNotifyPathMatch: codexConfig.includes(CODEX_MANAGED_NOTIFY_VALUE),
     pluginVersionMatch: pluginVersion ? pluginVersion === runtime.pkgVersion : false,
     pluginCacheVersionMatch: cacheVersion ? cacheVersion === runtime.pkgVersion : false,
   }
@@ -355,7 +364,8 @@ function buildDoctorReport(host) {
   return {
     config: {
       packageVersion: runtime.pkgVersion,
-      packageRoot: runtime.pkgRoot,
+      runtimeRoot: runtime.pkgRoot,
+      packageRoot: runtime.sourceRoot || runtime.pkgRoot,
       installMode: settings.install_mode || DEFAULTS.install_mode,
       trackedHostModes: settings.host_install_modes || {},
     },

package/scripts/cli-host-detect.mjs

@@ -75,7 +75,6 @@ function detectCodexMode(home) {
     || existsSync(join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME))
     || marketplace.includes(`"name": "${CODEX_PLUGIN_NAME}"`)
     || codexConfig.includes(CODEX_PLUGIN_KEY)
-    || codexConfig.includes(`/plugins/${CODEX_PLUGIN_NAME}/scripts/notify.mjs`)
     || codexHomeLinkTarget === globalPluginRoot
   ) {
     return 'global'

package/scripts/cli-hosts.mjs

@@ -3,15 +3,15 @@ import { existsSync } from 'node:fs';
 import {
   ensureDir,
   safeRead,
-  removeIfExists,
   createLink,
   removeLink,
   injectMarkedContent,
   removeMarkedContent,
   mergeSettingsHooks,
   cleanSettingsHooks,
-  loadHooksWithAbsPath,
+  loadHooksWithCliEntry,
 } from './cli-utils.mjs';
+import { buildRuntimeCarrier, readCarrierSettings } from './cli-runtime-carrier.mjs';
 
 export function installClaudeStandby(home, pkgRoot) {
   const claudeDir = join(home, '.claude');
@@ -19,15 +19,21 @@ export function installClaudeStandby(home, pkgRoot) {
 
   const bootstrapContent = safeRead(join(pkgRoot, 'bootstrap-lite.md'));
   if (bootstrapContent) {
-    injectMarkedContent(join(claudeDir, 'CLAUDE.md'), bootstrapContent);
+    injectMarkedContent(
+      join(claudeDir, 'CLAUDE.md'),
+      buildRuntimeCarrier(bootstrapContent, readCarrierSettings(home)).trimEnd(),
+    );
   }
 
   createLink(pkgRoot, join(claudeDir, 'helloagents'));
 
   const settingsPath = join(claudeDir, 'settings.json');
-  const hooksData = loadHooksWithAbsPath(pkgRoot, 'hooks-claude.json', '${CLAUDE_PLUGIN_ROOT}');
+  const hooksData = loadHooksWithCliEntry(pkgRoot, 'hooks-claude.json', '${CLAUDE_PLUGIN_ROOT}');
   if (hooksData) {
-    mergeSettingsHooks(settingsPath, hooksData, ['Read(~/.claude/helloagents/**)']);
+    mergeSettingsHooks(settingsPath, hooksData, [
+      'Read(~/.helloagents/helloagents/**)',
+      'Read(~/.claude/helloagents/**)',
+    ]);
   }
 
   return true;
@@ -50,13 +56,16 @@ export function installGeminiStandby(home, pkgRoot) {
 
   const bootstrapContent = safeRead(join(pkgRoot, 'bootstrap-lite.md'));
   if (bootstrapContent) {
-    injectMarkedContent(join(geminiDir, 'GEMINI.md'), bootstrapContent);
+    injectMarkedContent(
+      join(geminiDir, 'GEMINI.md'),
+      buildRuntimeCarrier(bootstrapContent, readCarrierSettings(home)).trimEnd(),
+    );
   }
 
   createLink(pkgRoot, join(geminiDir, 'helloagents'));
 
   const settingsPath = join(geminiDir, 'settings.json');
-  const hooksData = loadHooksWithAbsPath(pkgRoot, 'hooks.json', '${extensionPath}');
+  const hooksData = loadHooksWithCliEntry(pkgRoot, 'hooks.json', '${extensionPath}');
   if (hooksData) mergeSettingsHooks(settingsPath, hooksData);
 
   return true;
@@ -69,7 +78,6 @@ export function uninstallGeminiStandby(home) {
   removeMarkedContent(join(geminiDir, 'GEMINI.md'));
   removeLink(join(geminiDir, 'helloagents'));
   cleanSettingsHooks(join(geminiDir, 'settings.json'));
-  removeIfExists(join(geminiDir, 'helloagents-hooks.json'));
 
   return true;
 }

package/scripts/cli-lifecycle-hosts.mjs

@@ -1,5 +1,8 @@
+import { spawnSync } from 'node:child_process'
+
 import { installClaudeStandby, installGeminiStandby, uninstallClaudeStandby, uninstallGeminiStandby } from './cli-hosts.mjs'
 import {
+  cleanupCodexGlobalResidueForStandby,
   installCodexGlobal,
   installCodexStandby,
   uninstallCodexGlobal,
@@ -7,11 +10,63 @@ import {
 } from './cli-codex.mjs'
 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_PLUGIN = 'helloagents@helloagents'
+const GEMINI_EXTENSION = 'https://github.com/hellowind777/helloagents'
+
+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 || ''
+  return {
+    ok: result.status === 0,
+    missing: result.error?.code === 'ENOENT',
+    output: `${result.stdout || ''}${result.stderr || ''}${errorMessage}`.trim(),
+  }
+}
+
+function buildNativeResult(result, successCN, successEN, manualCN, manualEN) {
+  if (result.ok) return { ok: true, noteCN: successCN, noteEN: successEN }
+  return {
+    ok: false,
+    noteCN: `${manualCN}${result.output ? `；原因：${result.output}` : ''}`,
+    noteEN: `${manualEN}${result.output ? `; reason: ${result.output}` : ''}`,
+  }
+}
+
+function installClaudeGlobalPlugin() {
+  const add = runHostCommand(CLAUDE_COMMAND, ['plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE])
+  if (!add.ok && add.missing) return { ok: false, output: '未找到 claude 命令' }
+  const install = runHostCommand(CLAUDE_COMMAND, ['plugin', 'install', CLAUDE_PLUGIN, '--scope', 'user'])
+  return { ok: install.ok, output: install.output || add.output }
+}
+
+function installGeminiGlobalExtension() {
+  return runHostCommand(GEMINI_COMMAND, ['extensions', 'install', GEMINI_EXTENSION])
+}
+
+function removeClaudeGlobalPlugin() {
+  return runHostCommand(CLAUDE_COMMAND, ['plugin', 'remove', 'helloagents'])
+}
+
+function removeGeminiGlobalExtension() {
+  return runHostCommand(GEMINI_COMMAND, ['extensions', 'uninstall', 'helloagents'])
+}
+
 function reportHostAction(runtime, action, host, mode, result = {}) {
   const label = getHostLabel(host)
   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 (isCleanup) {
     runtime.ok(runtime.msg(`${label} 已清理（${mode} 模式）`, `${label} cleaned (${mode} mode)`))
   } else if (mode === 'standby') {
@@ -36,24 +91,31 @@ function installHostStandby(runtime, host) {
     installGeminiStandby(runtime.home, runtime.pkgRoot)
     return {}
   }
-  uninstallCodexGlobal(runtime.home)
-  return installCodexStandby(runtime.home, runtime.pkgRoot) ? {} : { skipped: true }
+  if (!installCodexStandby(runtime.home, runtime.pkgRoot)) return { skipped: true }
+  cleanupCodexGlobalResidueForStandby(runtime.home)
+  return {}
 }
 
 function installHostGlobal(runtime, host) {
   if (host === 'claude') {
     uninstallClaudeStandby(runtime.home)
-    return {
-      noteCN: 'Claude Code 的 global 模式需手动安装插件: /plugin marketplace add hellowind777/helloagents',
-      noteEN: 'Claude Code global mode still needs a manual plugin install: /plugin marketplace add hellowind777/helloagents',
-    }
+    return buildNativeResult(
+      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',
+    )
   }
   if (host === 'gemini') {
     uninstallGeminiStandby(runtime.home)
-    return {
-      noteCN: 'Gemini CLI 的 global 模式需手动安装扩展: gemini extensions install https://github.com/hellowind777/helloagents',
-      noteEN: 'Gemini CLI global mode still needs a manual extension install: gemini extensions install https://github.com/hellowind777/helloagents',
-    }
+    return buildNativeResult(
+      installGeminiGlobalExtension(),
+      '已自动安装 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',
+    )
   }
   uninstallCodexStandby(runtime.home)
   return installCodexGlobal(runtime.home, runtime.pkgRoot) ? {} : { skipped: true }
@@ -70,45 +132,70 @@ function cleanupHostStandby(runtime, host) {
 function cleanupHostGlobal(runtime, host) {
   if (host === 'claude') {
     uninstallClaudeStandby(runtime.home)
-    return {
-      noteCN: '如已安装 Claude Code 插件，请手动执行: /plugin remove helloagents',
-      noteEN: 'If the Claude Code plugin is installed, remove it manually: /plugin remove helloagents',
-    }
+    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',
+    )
   }
   if (host === 'gemini') {
     uninstallGeminiStandby(runtime.home)
-    return {
-      noteCN: '如已安装 Gemini CLI 扩展，请手动执行: gemini extensions uninstall helloagents',
-      noteEN: 'If the Gemini CLI extension is installed, remove it manually: gemini extensions uninstall helloagents',
-    }
+    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 { skipped: !uninstallCodexGlobal(runtime.home) }
 }
 
 function installStandby(runtime) {
-  uninstallCodexGlobal(runtime.home)
-  if (installClaudeStandby(runtime.home, runtime.pkgRoot)) runtime.ok(runtime.msg('Claude Code 已配置（standby 模式）', 'Claude Code configured (standby mode)'))
-  if (installGeminiStandby(runtime.home, runtime.pkgRoot)) runtime.ok(runtime.msg('Gemini CLI 已配置（standby 模式）', 'Gemini CLI configured (standby mode)'))
-  if (installCodexStandby(runtime.home, runtime.pkgRoot)) runtime.ok(runtime.msg('Codex CLI 已配置（standby 模式）', 'Codex CLI configured (standby mode)'))
-  else console.log(runtime.msg('  - Codex CLI 未检测到，跳过', '  - Codex CLI not detected, skipped'))
+  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 }
+  }
+  if (installCodexStandby(runtime.home, runtime.pkgRoot)) {
+    cleanupCodexGlobalResidueForStandby(runtime.home)
+    runtime.ok(runtime.msg('Codex CLI 已配置（standby 模式）', 'Codex CLI configured (standby mode)'))
+    results.codex = {}
+  } else {
+    console.log(runtime.msg('  - Codex CLI 未检测到，跳过', '  - Codex CLI not detected, skipped'))
+    results.codex = { skipped: true }
+  }
+  return results
 }
 
 function installGlobal(runtime) {
-  uninstallClaudeStandby(runtime.home)
-  uninstallGeminiStandby(runtime.home)
-  uninstallCodexStandby(runtime.home)
-  if (installCodexGlobal(runtime.home, runtime.pkgRoot)) runtime.ok(runtime.msg('Codex CLI 已安装原生本地插件（global 模式）', 'Codex CLI native local plugin installed (global mode)'))
-  else console.log(runtime.msg('  - Codex CLI 未检测到，跳过', '  - Codex CLI not detected, skipped'))
+  const results = {}
+  for (const host of ['claude', 'gemini', 'codex']) {
+    const result = installHostGlobal(runtime, host)
+    reportHostAction(runtime, 'install', host, 'global', result)
+    results[host] = result
+  }
+  return results
 }
 
 export function installAllHosts(runtime, mode) {
-  if (mode === 'global') installGlobal(runtime)
-  else installStandby(runtime)
+  if (mode === 'global') return installGlobal(runtime)
+  return installStandby(runtime)
 }
 
 export function uninstallAllHosts(runtime) {
-  uninstallClaudeStandby(runtime.home)
-  uninstallGeminiStandby(runtime.home)
+  cleanupHostGlobal(runtime, 'claude')
+  cleanupHostGlobal(runtime, 'gemini')
   uninstallCodexStandby(runtime.home)
   uninstallCodexGlobal(runtime.home)
 }

package/scripts/cli-lifecycle.mjs

@@ -15,6 +15,7 @@ export const HOSTS = ['claude', 'gemini', 'codex']
 const runtime = {
   home: '',
   pkgRoot: '',
+  sourceRoot: '',
   helloagentsHome: '',
   configFile: '',
   pkgVersion: '',
@@ -114,7 +115,6 @@ function resolveHostMode(host, explicitMode, settings) {
   if (explicitMode) return explicitMode
   return detectHostMode(host)
     || getTrackedHostMode(settings, host)
-    || (!hasTrackedHostModes(settings) ? (settings.install_mode || '') : '')
     || DEFAULTS.install_mode
 }
 
@@ -124,10 +124,11 @@ function resolveInstallMode(explicitMode, settings) {
 
 
 export function syncVersion() {
+  const packageRoot = runtime.sourceRoot || runtime.pkgRoot
   const targets = [
-    join(runtime.pkgRoot, '.claude-plugin', 'plugin.json'),
-    join(runtime.pkgRoot, '.codex-plugin', 'plugin.json'),
-    join(runtime.pkgRoot, 'gemini-extension.json'),
+    join(packageRoot, '.claude-plugin', 'plugin.json'),
+    join(packageRoot, '.codex-plugin', 'plugin.json'),
+    join(packageRoot, 'gemini-extension.json'),
   ]
   for (const path of targets) {
     const obj = safeJson(path)
@@ -135,9 +136,9 @@ export function syncVersion() {
     obj.version = runtime.pkgVersion
     safeWrite(path, JSON.stringify(obj, null, 2) + '\n')
   }
-  const marketPath = join(runtime.pkgRoot, '.claude-plugin', 'marketplace.json')
+  const marketPath = join(packageRoot, '.claude-plugin', 'marketplace.json')
   const market = safeJson(marketPath)
-  if (market?.plugins?.[0]) {
+  if (market?.plugins?.[0]?.version) {
     market.plugins[0].version = runtime.pkgVersion
     safeWrite(marketPath, JSON.stringify(market, null, 2) + '\n')
   }
@@ -173,29 +174,39 @@ function runAllHostsLifecycle(action, explicitMode) {
     }
     runtime.ok(runtime.msg('所有 CLI 配置已清理', 'All CLI configurations cleaned'))
     console.log(runtime.msg(
-      '  ℹ ~/.helloagents/ 已保留（如需彻底清理请手动删除）\n  ℹ 如已安装 Claude Code 插件，请手动执行: /plugin remove helloagents\n  ℹ 如已安装 Gemini CLI 扩展，请手动执行: gemini extensions uninstall helloagents',
-      '  ℹ ~/.helloagents/ preserved (delete manually if desired)\n  ℹ If Claude Code plugin installed, run: /plugin remove helloagents\n  ℹ If Gemini CLI extension installed, run: gemini extensions uninstall helloagents',
+      '  ℹ ~/.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',
     ))
     console.log()
     return
   }
 
   const settings = readSettings(true)
-  if (action === 'update' && !explicitMode) {
+  if (!explicitMode) {
     for (const host of HOSTS) {
       const mode = resolveHostMode(host, '', settings)
       const result = runHostLifecycle(runtime, action, host, mode)
-      if (!result.skipped) setTrackedHostMode(settings, host, mode)
+      if (!result.skipped && result.ok !== false) setTrackedHostMode(settings, host, mode)
+      else clearTrackedHostMode(settings, host)
     }
     writeSettings(settings)
-    runtime.printInstallMsg(settings.install_mode || DEFAULTS.install_mode, 'refresh')
+    const modes = Object.values(settings.host_install_modes || {})
+    const displayMode = modes.length && modes.every((mode) => mode === modes[0])
+      ? modes[0]
+      : settings.install_mode || DEFAULTS.install_mode
+    runtime.printInstallMsg(displayMode, action === 'update' ? 'refresh' : 'install')
     return
   }
 
   const mode = resolveInstallMode(explicitMode, settings)
   if (explicitMode) settings.install_mode = explicitMode
-  installAllHosts(runtime, mode)
-  setAllTrackedHostModes(settings, mode)
+  const results = installAllHosts(runtime, mode)
+  settings.host_install_modes = {}
+  for (const host of HOSTS) {
+    if (!results?.[host]?.skipped && results?.[host]?.ok !== false) {
+      settings.host_install_modes[host] = mode
+    }
+  }
   writeSettings(settings)
   runtime.printInstallMsg(mode, action === 'update' ? 'refresh' : 'install')
 }