helloagents 3.0.12 → 3.0.15-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,6 +10,55 @@ 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 { noteCN: successCN, noteEN: successEN }
+  return {
+    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'
@@ -36,24 +88,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,35 +129,41 @@ 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)'))
+  if (installCodexStandby(runtime.home, runtime.pkgRoot)) {
+    cleanupCodexGlobalResidueForStandby(runtime.home)
+    runtime.ok(runtime.msg('Codex CLI 已配置（standby 模式）', 'Codex CLI configured (standby mode)'))
+  }
   else console.log(runtime.msg('  - Codex CLI 未检测到，跳过', '  - Codex CLI not detected, skipped'))
 }
 
 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'))
+  for (const host of ['claude', 'gemini', 'codex']) {
+    reportHostAction(runtime, 'install', host, 'global', installHostGlobal(runtime, host))
+  }
 }
 
 export function installAllHosts(runtime, mode) {
@@ -107,8 +172,8 @@ export function installAllHosts(runtime, mode) {
 }
 
 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: '',
@@ -124,10 +125,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 +137,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,8 +175,8 @@ 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

package/scripts/cli-messages.mjs

@@ -20,7 +20,11 @@ function codexGlobalStatus({ home, msg }) {
 }
 
 function pluginCommands() {
-  return '    Claude Code:  /plugin marketplace add hellowind777/helloagents\n                  /plugin install helloagents@helloagents\n    Gemini CLI:   gemini extensions install https://github.com/hellowind777/helloagents'
+  return [
+    '    Claude Code:  /plugin marketplace add hellowind777/helloagents',
+    '                  /plugin install helloagents@helloagents',
+    '    Gemini CLI:   gemini extensions install https://github.com/hellowind777/helloagents',
+  ].join('\n')
 }
 
 function removeHint(msg) {
@@ -30,6 +34,13 @@ function removeHint(msg) {
   )
 }
 
+function restartHint(msg) {
+  return msg(
+    '重装、刷新或切换模式后，请重启对应 AI CLI 或新开会话；已运行会话不会自动重载注入规则。',
+    'After reinstalling, refreshing, or switching modes, restart the target AI CLI or open a new session; already running sessions do not reload injected rules automatically.',
+  )
+}
+
 function renderInstallMessage(context, mode, state) {
   const { msg } = context
   const install = state === 'install'
@@ -38,34 +49,34 @@ function renderInstallMessage(context, mode, state) {
   if (mode === 'global') {
     if (install) {
       return msg(
-        `\n  ✅ HelloAGENTS 已安装（global 模式）！\n\n${pluginCommands()}\n    Codex:        ${codexGlobalStatus(context)}（~/.agents/plugins/marketplace.json + ~/plugins/helloagents）\n\n  切换模式：\n    helloagents --standby   标准模式（默认，非插件安装）`,
-        `\n  ✅ HelloAGENTS installed (global mode)!\n\n${pluginCommands()}\n    Codex:        ${codexGlobalStatus(context)} (~/.agents/plugins/marketplace.json + ~/plugins/helloagents)\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
+        `\n  ✅ HelloAGENTS 已安装（global 模式）！\n\n    Claude Code / Gemini CLI: 已自动尝试宿主原生插件/扩展安装\n    Codex:        ${codexGlobalStatus(context)}（~/.agents/plugins/marketplace.json + ~/plugins/helloagents）\n\n  ${restartHint(msg)}\n\n  若宿主命令不可用，请手动执行：\n${pluginCommands()}\n\n  切换模式：\n    helloagents --standby   标准模式（默认，非插件安装）`,
+        `\n  ✅ HelloAGENTS installed (global mode)!\n\n    Claude Code / Gemini CLI: native plugin/extension install attempted automatically\n    Codex:        ${codexGlobalStatus(context)} (~/.agents/plugins/marketplace.json + ~/plugins/helloagents)\n\n  ${restartHint(msg)}\n\n  If a host command is unavailable, run manually:\n${pluginCommands()}\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
       )
     }
     return msg(
       refresh
-        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件已重装并同步最新文件。'
-        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动安装原生本地插件。',
+        ? `  global 模式已刷新。\n  Claude Code / Gemini 已自动尝试刷新宿主插件/扩展；Codex 原生本地插件已重装并同步最新文件。\n  ${restartHint(msg)}`
+        : `  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 已自动尝试安装宿主插件/扩展；Codex 已自动安装原生本地插件。\n  ${restartHint(msg)}\n\n若宿主命令不可用，请手动执行：\n${pluginCommands()}`,
       refresh
-        ? '  Global mode refreshed.\n  Keep Claude Code / Gemini plugins installed; Codex native local-plugin files were reinstalled and synced.'
-        : '  All projects will use full HelloAGENTS rules.\n  Install Claude Code / Gemini plugins manually; Codex now uses the native local-plugin path automatically.',
+        ? `  Global mode refreshed.\n  Claude Code / Gemini native plugin/extension refresh was attempted automatically; Codex native local-plugin files were reinstalled and synced.\n  ${restartHint(msg)}`
+        : `  All projects will use full HelloAGENTS rules.\n  Claude Code / Gemini native plugin/extension install was attempted automatically; Codex now uses the native local-plugin path automatically.\n  ${restartHint(msg)}\n\nIf a host command is unavailable, run manually:\n${pluginCommands()}`,
     )
   }
 
   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  standby 模式下，hello-* 技能不会自动触发。\n  在项目中使用 ~wiki 仅创建/同步知识库，或用 ~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  In standby mode, hello-* skills won't auto-trigger.\n  Use ~wiki to create or sync the KB only, or ~init for the full project bootstrap; ~command stays available on demand.\n\n  Switch modes:\n    helloagents --global    Global mode (manual plugins for Claude/Gemini; 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  在项目中使用 ~wiki 仅创建/同步知识库，或用 ~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 ~wiki to create or sync the KB only, or ~init for the full project bootstrap; ~command stays available on demand.\n\n  Switch modes:\n    helloagents --global    Global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)`,
     )
   }
 
   return msg(
     refresh
-      ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${removeHint(msg)}`
-      : `  项目可通过 ~wiki 创建/同步知识库，或通过 ~init 完整初始化；未激活项目仅注入通用规则。\n  ${removeHint(msg)}`,
+      ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`
+      : `  项目可通过 ~wiki 创建/同步知识库，或通过 ~init 完整初始化；未激活项目仅注入通用规则。\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
     refresh
-      ? `  Standby mode refreshed; injected files and links were synchronized.\n  ${removeHint(msg)}`
-      : `  Projects can use ~wiki for KB-only activation or ~init for the full bootstrap. Unactivated projects get lite rules only.\n  ${removeHint(msg)}`,
+      ? `  Standby mode refreshed; injected files and links were synchronized.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`
+      : `  Projects can use ~wiki for KB-only activation or ~init for the full bootstrap. Unactivated projects get lite rules only.\n  ${restartHint(msg)}\n  ${removeHint(msg)}`,
   )
 }
 
@@ -74,11 +85,12 @@ function renderHelp({ pkgVersion, msg }) {
 HelloAGENTS v${pkgVersion} — The orchestration kernel for AI CLIs
 
 ${msg('安装', 'Install')}:
-  npm install -g helloagents  ${msg('（只安装包与命令；CLI 部署需显式执行 helloagents install ...）', '(installs the package/command only; deploy to CLIs explicitly with helloagents install ...)')}
+  npm install -g helloagents  ${msg('（安装命令并同步稳定运行根目录；CLI 部署需显式执行 helloagents install ...）', '(installs the command and syncs the stable runtime root; deploy to CLIs explicitly with helloagents install ...)')}
+  HELLOAGENTS=codex:global npm install -g helloagents
   helloagents-js             ${msg('（稳定别名，避免与系统中同名可执行文件冲突）', '(stable alias to avoid conflicts with system executables of the same name)')}
 
 ${msg('模式切换', 'Mode switching')}:
-  helloagents --global     ${msg('全局模式（Claude/Gemini 装插件；Codex 自动装原生本地插件）', 'Global mode (manual plugins for Claude/Gemini; native local plugin auto-install for Codex)')}
+  helloagents --global     ${msg('全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）', 'Global mode (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')}:
@@ -89,6 +101,12 @@ ${msg('单 CLI 管理', 'Scoped CLI management')}:
   helloagents uninstall gemini
   ${msg('支持: claude | gemini | codex | --all；省略模式时优先沿用该 CLI 已记录/已检测的模式，否则回退 standby', 'Hosts: claude | gemini | codex | --all; omit mode to reuse the tracked/detected mode for that CLI, then fall back to standby')}
 
+${msg('分支切换', 'Branch switching')}:
+  helloagents switch-branch beta
+  helloagents switch-branch beta claude --global
+  helloagents branch github:hellowind777/helloagents#beta --all --standby
+  ${msg('先通过 npm 安装指定 ref，再通过 npm 脚本同步宿主 CLI', 'Installs the requested ref with npm first, then syncs host CLIs through npm scripts')}
+
 ${msg('诊断', 'Diagnostics')}:
   helloagents doctor
   helloagents doctor codex --json
@@ -97,7 +115,7 @@ ${msg('诊断', 'Diagnostics')}:
 ${msg('卸载', 'Uninstall')}:
   helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}
   npm uninstall -g helloagents
-  ${msg('如已安装插件，另需手动移除：', 'If plugins installed, also remove manually:')}
+  ${msg('如宿主命令不可用，另需手动移除：', 'If host commands are unavailable, also remove manually:')}
     Claude Code:  /plugin remove helloagents
     Gemini CLI:   gemini extensions uninstall helloagents
 `.trim()