helloagents 3.0.39 → 3.1.2

package/scripts/cli-doctor-codex.mjs

@@ -1,12 +1,11 @@
-import { spawnSync } from 'node:child_process'
 import { existsSync, realpathSync } from 'node:fs'
 import { platform } from 'node:os'
 import { join } from 'node:path'
 
 import { CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_CONFIG_HEADER, CODEX_PLUGIN_NAME } from './cli-codex.mjs'
 import {
+  analyzeCodexNotifyBlock,
   CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
-  CODEX_MANAGED_NOTIFY_VALUE,
   readCodexGoalsFeatureLine,
   readCodexHooksFeatureLine,
 } from './cli-codex-config.mjs'
@@ -16,7 +15,8 @@ import {
 } from './cli-codex-hooks-state.mjs'
 import { getStableRuntimeRoot } from './cli-runtime-root.mjs'
 import { buildRuntimeCarrier } from './cli-runtime-carrier.mjs'
-import { readTopLevelTomlLine } from './cli-toml.mjs'
+import { readTopLevelTomlBlock, readTopLevelTomlLine } from './cli-toml.mjs'
+import { spawnCommandSync } from './cli-process.mjs'
 import { loadHooksWithCliEntry, safeJson, safeRead } from './cli-utils.mjs'
 
 function safeRealTarget(linkPath) {
@@ -149,7 +149,7 @@ function summarizeNativeCodexDoctorOutput(payload = {}) {
 function inspectNativeCodexDoctor(runtime) {
   const command = platform() === 'win32' ? 'codex.cmd' : 'codex'
   try {
-    const result = spawnSync(command, ['doctor', '--json'], {
+    const result = spawnCommandSync(command, ['doctor', '--json'], {
       cwd: process.cwd(),
       env: {
         ...process.env,
@@ -159,7 +159,6 @@ function inspectNativeCodexDoctor(runtime) {
       },
       encoding: 'utf-8',
       timeout: 20_000,
-      shell: platform() === 'win32',
       windowsHide: true,
     })
 
@@ -259,6 +258,8 @@ function appendCodexGlobalIssues(runtime, issues, checks, pluginVersion, cacheVe
   if (!checks.pluginCache) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-missing', 'global 插件缓存目录缺失', 'Global plugin cache directory is missing'))
   if (checks.pluginRoot && !checks.pluginRootLink) issues.push(buildDoctorIssue(runtime, 'global-plugin-root-link-drift', 'global 插件根目录未链接到稳定运行根目录', 'Global plugin root does not link to the stable runtime root'))
   if (checks.pluginCache && !checks.pluginCacheLink) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-link-drift', 'global 插件缓存未链接到稳定运行根目录', 'Global plugin cache does not link to the stable runtime root'))
+  if (checks.pluginGenericHooks) issues.push(buildDoctorIssue(runtime, 'global-plugin-generic-hooks-present', 'global 插件根目录中意外存在通用 `hooks/hooks.json`，可能污染 Codex 本地插件 hook 加载', 'Global plugin root unexpectedly contains a generic `hooks/hooks.json`, which can pollute Codex local-plugin hook loading'))
+  if (checks.pluginCacheGenericHooks) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-generic-hooks-present', 'global 插件缓存中意外存在通用 `hooks/hooks.json`，可能污染 Codex 本地插件 hook 加载', 'Global plugin cache unexpectedly contains a generic `hooks/hooks.json`, which can pollute Codex local-plugin hook loading'))
   if (checks.pluginRoot && !checks.pluginCarrierMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-carrier-drift', 'global 插件根目录中的 AGENTS.md 与当前全局模式规则不一致', 'Global plugin AGENTS.md differs from the current global rules'))
   if (checks.pluginCache && !checks.pluginCacheCarrierMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-carrier-drift', 'global 插件缓存中的 AGENTS.md 与当前全局模式规则不一致', 'Global plugin cache AGENTS.md differs from the current global rules'))
   if (!checks.marketplaceEntry) issues.push(buildDoctorIssue(runtime, 'global-marketplace-missing', 'global marketplace 条目缺失', 'Global marketplace entry is missing'))
@@ -285,12 +286,16 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
   const homeLinkTarget = safeRealTarget(join(codexDir, 'helloagents'))
   const pluginRootTarget = safeRealTarget(pluginRoot)
   const pluginCacheTarget = safeRealTarget(pluginCacheRoot)
+  const pluginGenericHooks = !!safeRead(join(pluginRoot, 'hooks', 'hooks.json'))
+  const pluginCacheGenericHooks = !!safeRead(join(pluginCacheRoot, 'hooks', 'hooks.json'))
   const expectedHomeCarrier = (detectedMode === 'global' || (detectedMode === 'none' && trackedMode === 'global'))
     ? 'bootstrap.md'
     : 'bootstrap-lite.md'
   const codexHooks = safeJson(join(codexDir, 'hooks.json')) || {}
   const marketplace = safeJson(join(runtime.home, '.agents', 'plugins', 'marketplace.json')) || {}
   const modelInstructionsLine = readTopLevelTomlLine(codexConfig, 'model_instructions_file')
+  const notifyBlock = readTopLevelTomlBlock(codexConfig, 'notify')
+  const notifyAnalysis = analyzeCodexNotifyBlock(notifyBlock)
   const expectedHooks = readExpectedHooks(runtime, 'hooks-codex.json', '${PLUGIN_ROOT}')
   const expectedHookTrust = buildManagedCodexHookTrustEntries(join(codexDir, 'hooks.json'), codexHooks)
   const managedHookTrust = new Map(
@@ -314,8 +319,9 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
       globalHomeLink: homeLinkTarget === runtimeRoot,
       modelInstructionsFile: !!modelInstructionsLine,
       modelInstructionsPathMatch: !!modelInstructionsLine && normalizePath(modelInstructionsLine).includes(`"${CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH}"`),
-      codexNotify: codexConfig.includes('codex-notify'),
-      notifyPathMatch: codexConfig.includes(CODEX_MANAGED_NOTIFY_VALUE),
+      codexNotify: notifyAnalysis.containsCodexNotify,
+      notifyPathMatch: notifyAnalysis.managed,
+      notifyShape: notifyAnalysis.shape,
       codexHooksFeature: !/^\s*hooks\s*=\s*false\b/.test(hooksFeatureLine),
       codexGoalsFeature: /^\s*goals\s*=\s*true\b/.test(goalsFeatureLine),
       standaloneHooks: JSON.stringify(codexHooks.hooks || {}).includes('helloagents'),
@@ -326,11 +332,13 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
       pluginCache: existsSync(pluginCacheRoot),
       pluginRootLink: pluginRootTarget === runtimeRoot,
       pluginCacheLink: pluginCacheTarget === runtimeRoot,
+      pluginGenericHooks,
+      pluginCacheGenericHooks,
       pluginCarrierMatch: normalizeText(safeRead(join(pluginRoot, 'AGENTS.md')) || '') === readExpectedCarrierContent(runtime, 'bootstrap.md', settings, { profile: 'full' }),
       pluginCacheCarrierMatch: normalizeText(safeRead(join(pluginCacheRoot, 'AGENTS.md')) || '') === readExpectedCarrierContent(runtime, 'bootstrap.md', settings, { profile: 'full' }),
       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'),
-      globalNotifyPathMatch: codexConfig.includes(CODEX_MANAGED_NOTIFY_VALUE),
+      globalNotifyPathMatch: notifyAnalysis.managed,
       pluginVersionMatch: false,
       pluginCacheVersionMatch: false,
     },
@@ -364,6 +372,7 @@ export function inspectCodexDoctor(runtime, settings) {
   if (!checks.pluginVersionMatch && !pluginVersion && detectedMode === 'global') notes.push(runtime.msg('未读到 global 插件根目录版本信息', 'Global plugin root version was not readable'))
   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 (checks.notifyShape === 'chained') notes.push(runtime.msg('HelloAGENTS notify 当前通过 Codex Computer Use / wrapper 链式转发，仍视为有效。', 'HelloAGENTS notify is currently chained through Codex Computer Use / a wrapper and is still treated as valid.'))
   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 })

package/scripts/cli-doctor.mjs

@@ -1,12 +1,16 @@
-import { realpathSync } from 'node:fs'
+import { existsSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
 
 import { DEFAULTS } from './cli-config.mjs'
 import { inspectCodexDoctor as inspectCodexDoctorImpl } from './cli-doctor-codex.mjs'
 import { printDoctorText } from './cli-doctor-render.mjs'
 import { buildRuntimeCarrier } from './cli-runtime-carrier.mjs'
+import { getClaudeMarketplaceRoot, getGeminiExtensionRoot } from './cli-runtime-root.mjs'
 import { loadHooksWithCliEntry, safeJson, safeRead } from './cli-utils.mjs'
 
+const CLAUDE_PLUGIN = 'helloagents@helloagents'
+const GEMINI_EXTENSION = 'helloagents'
+
 const runtime = {
   home: '',
   pkgRoot: '',
@@ -93,6 +97,16 @@ function normalizeDoctorMode(mode = '') {
   return mode || 'none'
 }
 
+function hasEnabledPlugin(enabledPlugins, pluginName) {
+  if (Array.isArray(enabledPlugins)) {
+    return enabledPlugins.includes(pluginName)
+  }
+  if (enabledPlugins && typeof enabledPlugins === 'object') {
+    return Boolean(enabledPlugins[pluginName])
+  }
+  return false
+}
+
 function summarizeDoctorStatus(issues, { host, trackedMode, detectedMode } = {}) {
   if (issues.length > 0) return 'drift'
   if (detectedMode !== 'none') return 'ok'
@@ -106,8 +120,8 @@ function suggestDoctorFix(host, status, trackedMode) {
     return `helloagents update ${host}${trackedMode && trackedMode !== 'none' ? ` --${trackedMode}` : ''}`
   }
   if (status === 'manual-plugin') {
-    if (host === 'claude') return '/plugin marketplace add https://github.com/hellowind777/helloagents.git; /plugin install helloagents@helloagents'
-    if (host === 'gemini') return 'helloagents install gemini --global'
+    if (host === 'claude') return `/plugin marketplace add "${getClaudeMarketplaceRoot(runtime.home)}"; /plugin install helloagents@helloagents`
+    if (host === 'gemini') return `gemini extensions link "${getGeminiExtensionRoot(runtime.home)}"`
   }
   if (status === 'not-installed') {
     return `helloagents install ${host} --standby`
@@ -125,12 +139,18 @@ function inspectClaudeDoctor(settings) {
   const detectedMode = normalizeDoctorMode(runtime.detectHostMode(host))
   const claudeDir = join(runtime.home, '.claude')
   const claudeSettings = safeJson(join(claudeDir, 'settings.json')) || {}
+  const claudePlugins = safeJson(join(claudeDir, 'plugins', 'installed_plugins.json')) || {}
   const expectedHooks = readExpectedHooks('hooks-claude.json', '${CLAUDE_PLUGIN_ROOT}')
+  const marketplaceRoot = getClaudeMarketplaceRoot(runtime.home)
+  const globalPluginInstalled = Boolean(claudePlugins.plugins?.[CLAUDE_PLUGIN]?.length)
+    || hasEnabledPlugin(claudeSettings.enabledPlugins, CLAUDE_PLUGIN)
   const checks = {
     carrierMarker: (safeRead(join(claudeDir, 'CLAUDE.md')) || '').includes('HELLOAGENTS_START'),
     carrierContentMatch: extractManagedCarrierContent(join(claudeDir, 'CLAUDE.md'))
       === readExpectedCarrierContent('bootstrap-lite.md', settings),
     homeLink: safeRealTarget(join(claudeDir, 'helloagents')) === runtime.pkgRoot,
+    globalMarketplaceRoot: existsSync(marketplaceRoot),
+    globalPluginInstalled,
     settingsHooks: JSON.stringify(claudeSettings.hooks || {}).includes('helloagents'),
     settingsHooksMatch: managedHooksMatch(claudeSettings.hooks || {}, expectedHooks),
     settingsPermission: Array.isArray(claudeSettings.permissions?.allow)
@@ -150,14 +170,17 @@ function inspectClaudeDoctor(settings) {
     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 is managed by the host plugin system; doctor only checks for standby residue and does not inspect plugin state directly.',
-    ))
+  if (detectedMode === 'global') {
+    if (!checks.globalMarketplaceRoot) issues.push(buildDoctorIssue('global-marketplace-root-missing', 'global marketplace 投影缺失', 'Global marketplace projection is missing'))
+    if (!checks.globalPluginInstalled) issues.push(buildDoctorIssue('global-plugin-missing', 'global Claude 插件未安装', 'Global Claude plugin is not installed'))
     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'))
+      issues.push(buildDoctorIssue('global-standby-residue', 'global 模式下仍残留 standby 注入/链接', 'Standby injections or links still remain while the host is detected as global'))
     }
+  } else if (trackedMode === 'global') {
+    notes.push(runtime.msg(
+      'Claude Code 的 global 模式由宿主插件系统管理；doctor 会检查本地 marketplace 投影、已安装插件记录与 standby 残留。',
+      'Claude Code global mode is managed by the host plugin system; doctor checks the local marketplace projection, installed-plugin records, and standby residue.',
+    ))
   }
   if (trackedMode === 'none' && detectedMode !== 'none') {
     issues.push(buildDoctorIssue('untracked-managed-state', '检测到受管状态，但配置中未记录该 CLI 模式', 'Managed state detected but this CLI mode is not tracked in config'))
@@ -177,11 +200,17 @@ function inspectGeminiDoctor(settings) {
   const geminiDir = join(runtime.home, '.gemini')
   const geminiSettings = safeJson(join(geminiDir, 'settings.json')) || {}
   const expectedHooks = readExpectedHooks('hooks-gemini.json', '${extensionPath}')
+  const extensionRoot = getGeminiExtensionRoot(runtime.home)
+  const extensionInstallRoot = join(geminiDir, 'extensions', GEMINI_EXTENSION)
+  const expectedExtensionTarget = safeRealTarget(extensionRoot) || normalizePath(extensionRoot)
   const checks = {
     carrierMarker: (safeRead(join(geminiDir, 'GEMINI.md')) || '').includes('HELLOAGENTS_START'),
     carrierContentMatch: extractManagedCarrierContent(join(geminiDir, 'GEMINI.md'))
       === readExpectedCarrierContent('bootstrap-lite.md', settings),
     homeLink: safeRealTarget(join(geminiDir, 'helloagents')) === runtime.pkgRoot,
+    globalExtensionRoot: existsSync(extensionRoot),
+    globalExtensionLink: safeRealTarget(extensionInstallRoot) === expectedExtensionTarget,
+    globalExtensionInstall: existsSync(extensionInstallRoot),
     settingsHooks: JSON.stringify(geminiSettings.hooks || {}).includes('helloagents'),
     settingsHooksMatch: managedHooksMatch(geminiSettings.hooks || {}, expectedHooks),
   }
@@ -198,14 +227,18 @@ function inspectGeminiDoctor(settings) {
     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 is managed by the host extension system; doctor only checks for standby residue and does not inspect extension state directly.',
-    ))
+  if (detectedMode === 'global') {
+    if (!checks.globalExtensionRoot) issues.push(buildDoctorIssue('global-extension-root-missing', 'global extension 投影缺失', 'Global extension projection is missing'))
+    if (!checks.globalExtensionInstall) issues.push(buildDoctorIssue('global-extension-missing', 'global Gemini 扩展未安装', 'Global Gemini extension is not installed'))
+    if (!checks.globalExtensionLink) issues.push(buildDoctorIssue('global-extension-link-missing', 'global Gemini 扩展链接未指向投影目录', 'Global Gemini extension link does not point to the projection root'))
     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'))
+      issues.push(buildDoctorIssue('global-standby-residue', 'global 模式下仍残留 standby 注入/链接', 'Standby injections or links still remain while the host is detected as global'))
     }
+  } else if (trackedMode === 'global') {
+    notes.push(runtime.msg(
+      'Gemini CLI 的 global 模式由宿主扩展系统管理；doctor 会检查本地扩展投影、已安装链接与 standby 残留。',
+      'Gemini CLI global mode is managed by the host extension system; doctor checks the local extension projection, installed link, and standby residue.',
+    ))
   }
   if (trackedMode === 'none' && detectedMode !== 'none') {
     issues.push(buildDoctorIssue('untracked-managed-state', '检测到受管状态，但配置中未记录该 CLI 模式', 'Managed state detected but this CLI mode is not tracked in config'))

package/scripts/cli-host-detect.mjs

@@ -6,9 +6,12 @@ import {
   CODEX_PLUGIN_KEY,
   CODEX_PLUGIN_NAME,
 } from './cli-codex.mjs'
-import { getStableRuntimeRoot } from './cli-runtime-root.mjs'
+import { getGeminiExtensionRoot, getStableRuntimeRoot } from './cli-runtime-root.mjs'
 import { safeJson, safeRead } from './cli-utils.mjs'
 
+const CLAUDE_PLUGIN = 'helloagents@helloagents'
+const GEMINI_EXTENSION = 'helloagents'
+
 const HOST_ALIASES = new Map([
   ['all', 'all'],
   ['*', 'all'],
@@ -24,8 +27,14 @@ function hasHelloagentsMarker(filePath) {
   return (safeRead(filePath) || '').includes('HELLOAGENTS_START')
 }
 
-function hasHelloagentsSettings(filePath) {
-  return JSON.stringify(safeJson(filePath) || {}).includes('helloagents')
+function hasHelloagentsSettings(filePath, host = '') {
+  const settings = safeJson(filePath) || {}
+  const hooksText = JSON.stringify(settings.hooks || {})
+  if (hooksText.includes('helloagents')) return true
+  if (host === 'claude') {
+    return JSON.stringify(settings.permissions?.allow || []).includes('~/.helloagents/helloagents')
+  }
+  return false
 }
 
 function normalizePath(value = '') {
@@ -40,12 +49,27 @@ function safeRealTarget(linkPath) {
   }
 }
 
+function hasEnabledPlugin(enabledPlugins, pluginName) {
+  if (Array.isArray(enabledPlugins)) {
+    return enabledPlugins.includes(pluginName)
+  }
+  if (enabledPlugins && typeof enabledPlugins === 'object') {
+    return Boolean(enabledPlugins[pluginName])
+  }
+  return false
+}
+
 function detectClaudeMode(home) {
   const claudeDir = join(home, '.claude')
+  const settings = safeJson(join(claudeDir, 'settings.json')) || {}
+  const installedPlugins = safeJson(join(claudeDir, 'plugins', 'installed_plugins.json')) || {}
+  if (hasEnabledPlugin(settings.enabledPlugins, CLAUDE_PLUGIN) || installedPlugins.plugins?.[CLAUDE_PLUGIN]?.length) {
+    return 'global'
+  }
   if (
     existsSync(join(claudeDir, 'helloagents'))
     || hasHelloagentsMarker(join(claudeDir, 'CLAUDE.md'))
-    || hasHelloagentsSettings(join(claudeDir, 'settings.json'))
+    || hasHelloagentsSettings(join(claudeDir, 'settings.json'), 'claude')
   ) {
     return 'standby'
   }
@@ -54,10 +78,19 @@ function detectClaudeMode(home) {
 
 function detectGeminiMode(home) {
   const geminiDir = join(home, '.gemini')
+  const extensionRoot = safeRealTarget(getGeminiExtensionRoot(home)) || normalizePath(getGeminiExtensionRoot(home))
+  const installedExtensionRoot = join(geminiDir, 'extensions', GEMINI_EXTENSION)
+  const installedExtension = safeJson(join(installedExtensionRoot, 'gemini-extension.json')) || {}
+  if (
+    existsSync(installedExtensionRoot)
+    && (safeRealTarget(installedExtensionRoot) === extensionRoot || installedExtension.name === GEMINI_EXTENSION)
+  ) {
+    return 'global'
+  }
   if (
     existsSync(join(geminiDir, 'helloagents'))
     || hasHelloagentsMarker(join(geminiDir, 'GEMINI.md'))
-    || hasHelloagentsSettings(join(geminiDir, 'settings.json'))
+    || hasHelloagentsSettings(join(geminiDir, 'settings.json'), 'gemini')
   ) {
     return 'standby'
   }

package/scripts/cli-lifecycle-hosts.mjs

@@ -1,4 +1,3 @@
-import { spawnSync } from 'node:child_process'
 import { platform } from 'node:os'
 
 import {
@@ -14,11 +13,22 @@ import {
   uninstallCodexGlobal,
   uninstallCodexStandby,
 } from './cli-codex.mjs'
-import { getHostLabel } from './cli-host-detect.mjs'
+import { spawnCommandSync } from './cli-process.mjs'
+import {
+  detectHostMode as detectRuntimeHostMode,
+  getHostLabel,
+} from './cli-host-detect.mjs'
+import {
+  getClaudeMarketplaceRoot,
+  getGeminiExtensionRoot,
+  removeClaudeMarketplaceRoot,
+  removeGeminiExtensionRoot,
+  syncClaudeMarketplaceRoot,
+  syncGeminiExtensionRoot,
+} from './cli-runtime-root.mjs'
 
 const CLAUDE_COMMAND = process.env.HELLOAGENTS_CLAUDE_CMD || 'claude'
 const GEMINI_COMMAND = process.env.HELLOAGENTS_GEMINI_CMD || 'gemini'
-const CLAUDE_MARKETPLACE = 'https://github.com/hellowind777/helloagents.git'
 const CLAUDE_PLUGIN = 'helloagents@helloagents'
 
 function normalizeCommand(command = '') {
@@ -44,11 +54,9 @@ function runHostCommand(command, args) {
   let lastResult = null
 
   for (const candidate of attempts) {
-    const needsShell = process.platform === 'win32' && /\.(cmd|bat)$/i.test(candidate)
-    const result = spawnSync(candidate, args, {
+    const result = spawnCommandSync(candidate, args, {
       encoding: 'utf-8',
       errors: 'replace',
-      shell: needsShell,
       windowsHide: true,
     })
     lastResult = result
@@ -81,8 +89,8 @@ function preserveTrackedModeOnFailure(result = {}, trackedMode = '') {
   return result
 }
 
-function installClaudeGlobalPlugin() {
-  const add = runHostCommand(CLAUDE_COMMAND, ['plugin', 'marketplace', 'add', CLAUDE_MARKETPLACE])
+function installClaudeGlobalPlugin(marketplaceRoot) {
+  const add = runHostCommand(CLAUDE_COMMAND, ['plugin', 'marketplace', 'add', marketplaceRoot])
   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 }
@@ -158,12 +166,14 @@ function installHostStandby(runtime, host, { previousMode = '' } = {}) {
     const cleanupResult = prepareClaudeStandby(previousMode)
     if (cleanupResult.ok === false) return cleanupResult
     installClaudeStandby(runtime.home, runtime.pkgRoot)
+    if (detectRuntimeHostMode('claude', runtime) !== 'global') removeClaudeMarketplaceRoot(runtime.home)
     return cleanupResult
   }
   if (host === 'gemini') {
     const cleanupResult = prepareGeminiStandby(previousMode)
     if (cleanupResult.ok === false) return cleanupResult
     installGeminiStandby(runtime.home, runtime.pkgRoot)
+    if (detectRuntimeHostMode('gemini', runtime) !== 'global') removeGeminiExtensionRoot(runtime.home)
     return cleanupResult
   }
   if (!installCodexStandby(runtime.home, runtime.pkgRoot)) return { skipped: true }
@@ -174,31 +184,45 @@ function installHostStandby(runtime, host, { previousMode = '' } = {}) {
 function installHostGlobal(runtime, host) {
   if (host === 'claude') {
     uninstallClaudeStandby(runtime.home)
-    return buildNativeResult(
-      installClaudeGlobalPlugin(),
+    const marketplaceRoot = getClaudeMarketplaceRoot(runtime.home)
+    syncClaudeMarketplaceRoot(runtime.pkgRoot, marketplaceRoot)
+    const result = buildNativeResult(
+      installClaudeGlobalPlugin(marketplaceRoot),
       '已自动安装 Claude Code 插件；重启 Claude Code 后生效',
       'Claude Code plugin installed automatically; restart Claude Code to apply',
-      'Claude Code 插件自动安装失败，请在 Claude Code 中执行: /plugin marketplace add https://github.com/hellowind777/helloagents.git；/plugin install helloagents@helloagents',
-      'Claude Code plugin auto-install failed. Run inside Claude Code: /plugin marketplace add https://github.com/hellowind777/helloagents.git; /plugin install helloagents@helloagents',
+      `Claude Code 插件自动安装失败，请在 Claude Code 中执行: /plugin marketplace add "${marketplaceRoot}"；/plugin install helloagents@helloagents`,
+      `Claude Code plugin auto-install failed. Run inside Claude Code: /plugin marketplace add "${marketplaceRoot}"; /plugin install helloagents@helloagents`,
     )
+    return result
   }
   if (host === 'gemini') {
     uninstallGeminiStandby(runtime.home)
-    return buildNativeResult(
-      installGeminiGlobalExtension(runtime.pkgRoot),
+    const extensionRoot = getGeminiExtensionRoot(runtime.home)
+    syncGeminiExtensionRoot(runtime.pkgRoot, extensionRoot)
+    const result = buildNativeResult(
+      installGeminiGlobalExtension(extensionRoot),
       '已自动安装 Gemini CLI 扩展；重启 Gemini CLI 后生效',
       'Gemini CLI extension installed automatically; restart Gemini CLI to apply',
-      `Gemini CLI 扩展自动安装失败，请手动执行: gemini extensions link ${runtime.pkgRoot}`,
-      `Gemini CLI extension auto-install failed. Run manually: gemini extensions link ${runtime.pkgRoot}`,
+      `Gemini CLI 扩展自动安装失败，请手动执行: gemini extensions link "${extensionRoot}"`,
+      `Gemini CLI extension auto-install failed. Run manually: gemini extensions link "${extensionRoot}"`,
     )
+    return result
   }
   uninstallCodexStandby(runtime.home)
   return installCodexGlobal(runtime.home, runtime.pkgRoot) ? {} : { skipped: true }
 }
 
 function cleanupHostStandby(runtime, host) {
-  if (host === 'claude') return { skipped: !uninstallClaudeStandby(runtime.home) }
-  if (host === 'gemini') return { skipped: !uninstallGeminiStandby(runtime.home) }
+  if (host === 'claude') {
+    const skipped = !uninstallClaudeStandby(runtime.home)
+    if (detectRuntimeHostMode('claude', runtime) !== 'global') removeClaudeMarketplaceRoot(runtime.home)
+    return { skipped }
+  }
+  if (host === 'gemini') {
+    const skipped = !uninstallGeminiStandby(runtime.home)
+    if (detectRuntimeHostMode('gemini', runtime) !== 'global') removeGeminiExtensionRoot(runtime.home)
+    return { skipped }
+  }
   const standbyCleaned = uninstallCodexStandby(runtime.home)
   const globalResidueCleaned = uninstallCodexGlobal(runtime.home)
   return { skipped: !(standbyCleaned || globalResidueCleaned) }
@@ -207,7 +231,7 @@ function cleanupHostStandby(runtime, host) {
 function cleanupHostGlobal(runtime, host) {
   if (host === 'claude') {
     uninstallClaudeStandby(runtime.home)
-    return preserveTrackedModeOnFailure(
+    const result = preserveTrackedModeOnFailure(
       buildNativeResult(
         removeClaudeGlobalPlugin(),
         '已自动移除 Claude Code 插件',
@@ -217,10 +241,12 @@ function cleanupHostGlobal(runtime, host) {
       ),
       'global',
     )
+    if (result.ok) removeClaudeMarketplaceRoot(runtime.home)
+    return result
   }
   if (host === 'gemini') {
     uninstallGeminiStandby(runtime.home)
-    return preserveTrackedModeOnFailure(
+    const result = preserveTrackedModeOnFailure(
       buildNativeResult(
         removeGeminiGlobalExtension(),
         '已自动移除 Gemini CLI 扩展',
@@ -230,6 +256,8 @@ function cleanupHostGlobal(runtime, host) {
       ),
       'global',
     )
+    if (result.ok) removeGeminiExtensionRoot(runtime.home)
+    return result
   }
   return { skipped: !uninstallCodexGlobal(runtime.home) }
 }

package/scripts/cli-messages.mjs

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
+import { getClaudeMarketplaceRoot, getGeminiExtensionRoot } from './cli-runtime-root.mjs'
 
 export function createMessageHelpers(isCN) {
   const msg = (cn, en) => (isCN ? cn : en)
@@ -19,11 +20,11 @@ function codexGlobalStatus({ home, msg }) {
     : msg('安装 Codex CLI 后重新运行 npm install -g helloagents', 'Install Codex CLI then re-run npm install -g helloagents')
 }
 
-function pluginCommands() {
+function pluginCommands(home) {
   return [
-    '    Claude Code:  /plugin marketplace add https://github.com/hellowind777/helloagents.git',
+    `    Claude Code:  /plugin marketplace add "${getClaudeMarketplaceRoot(home)}"`,
     '                  /plugin install helloagents@helloagents',
-    '    Gemini CLI:   helloagents install gemini --global',
+    `    Gemini CLI:   gemini extensions link "${getGeminiExtensionRoot(home)}"`,
   ].join('\n')
 }
 
@@ -42,24 +43,24 @@ function restartHint(msg) {
 }
 
 function renderInstallMessage(context, mode, state) {
-  const { msg } = context
+  const { home, msg } = context
   const install = state === 'install'
   const refresh = state === 'refresh'
 
   if (mode === 'global') {
     if (install) {
       return msg(
-        `\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)`,
+        `\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(home)}\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(home)}\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
       )
     }
     return msg(
       refresh
         ? `  global 模式已刷新。\n  Claude Code / Gemini 已自动尝试刷新宿主插件/扩展；Codex 原生本地插件已重装并同步最新文件。\n  ${restartHint(msg)}`
-        : `  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 已自动尝试安装宿主插件/扩展；Codex 已自动安装原生本地插件。\n  ${restartHint(msg)}\n\n若宿主命令不可用，请手动执行：\n${pluginCommands()}`,
+        : `  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 已自动尝试安装宿主插件/扩展；Codex 已自动安装原生本地插件。\n  ${restartHint(msg)}\n\n若宿主命令不可用，请手动执行：\n${pluginCommands(home)}`,
       refresh
         ? `  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()}`,
+        : `  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(home)}`,
     )
   }
 

package/scripts/cli-process.mjs

@@ -0,0 +1,16 @@
+import { spawnSync } from 'node:child_process'
+
+/**
+ * Run a command on all platforms, including Windows .cmd/.bat files, without
+ * relying on child_process shell=true argument concatenation.
+ */
+export function spawnCommandSync(command, args = [], options = {}) {
+  const normalizedArgs = Array.isArray(args) ? args.map((arg) => String(arg)) : []
+  const isWindowsShellScript = process.platform === 'win32' && /\.(cmd|bat)$/i.test(String(command || ''))
+  if (!isWindowsShellScript) {
+    return spawnSync(command, normalizedArgs, options)
+  }
+
+  const comspec = process.env.ComSpec || 'cmd.exe'
+  return spawnSync(comspec, ['/d', '/s', '/c', String(command || ''), ...normalizedArgs], options)
+}

package/scripts/cli-runtime-root.mjs

@@ -1,7 +1,7 @@
 import { copyFileSync, existsSync, mkdtempSync, realpathSync, renameSync } from 'node:fs'
 import { dirname, join, resolve } from 'node:path'
 
-import { copyEntries, ensureDir, removeIfExists } from './cli-utils.mjs'
+import { copyEntries, createLink, ensureDir, removeIfExists } from './cli-utils.mjs'
 
 export const RUNTIME_ROOT_ENTRIES = [
   '.claude-plugin',
@@ -28,6 +28,16 @@ export function getStableRuntimeRoot(home) {
   return join(home, '.helloagents', 'helloagents')
 }
 
+/** Return the Claude local marketplace projection root derived from the shared runtime copy. */
+export function getClaudeMarketplaceRoot(home) {
+  return join(home, '.helloagents', 'host-projections', 'claude-marketplace')
+}
+
+/** Return the Gemini extension projection root derived from the shared runtime copy. */
+export function getGeminiExtensionRoot(home) {
+  return join(home, '.helloagents', 'host-projections', 'gemini')
+}
+
 function normalizePath(path) {
   const resolved = resolve(path)
   try {
@@ -63,17 +73,9 @@ function retryTransientFs(operation) {
   throw lastError
 }
 
-function materializeGeminiHooks(root) {
-  const source = join(root, 'hooks', 'hooks-gemini.json')
-  const target = join(root, 'hooks', 'hooks.json')
-  if (!existsSync(source)) return
-  copyFileSync(source, target)
-}
-
-/** Sync package runtime files into the stable root without copying repo-only files. */
-export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
+function syncRuntimeTree(sourceRoot, targetRoot, { materializeGeminiHooks = false } = {}) {
   const source = resolve(sourceRoot)
-  const target = resolve(runtimeRoot)
+  const target = resolve(targetRoot)
   if (samePath(source, target)) {
     return { synced: false, root: target }
   }
@@ -84,7 +86,13 @@ export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
 
   try {
     copyEntries(source, staging, RUNTIME_ROOT_ENTRIES)
-    materializeGeminiHooks(staging)
+    if (materializeGeminiHooks) {
+      const sourceHooks = join(staging, 'hooks', 'hooks-gemini.json')
+      const targetHooks = join(staging, 'hooks', 'hooks.json')
+      if (existsSync(sourceHooks)) {
+        copyFileSync(sourceHooks, targetHooks)
+      }
+    }
     retryTransientFs(() => {
       removeIfExists(target)
       renameSync(staging, target)
@@ -96,7 +104,42 @@ export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
   }
 }
 
+/** Sync package runtime files into the stable root without copying repo-only files. */
+export function syncRuntimeRoot(sourceRoot, runtimeRoot) {
+  return syncRuntimeTree(sourceRoot, runtimeRoot)
+}
+
+/** Sync a Claude local marketplace root that resolves to the stable runtime copy. */
+export function syncClaudeMarketplaceRoot(sourceRoot, marketplaceRoot) {
+  const source = resolve(sourceRoot)
+  const target = resolve(marketplaceRoot)
+  if (samePath(source, target)) {
+    return { synced: false, root: target }
+  }
+
+  removeIfExists(target)
+  if (createLink(source, target)) {
+    return { synced: true, root: target }
+  }
+  return syncRuntimeTree(source, target)
+}
+
+/** Sync a host-specific extension root derived from the stable runtime copy. */
+export function syncGeminiExtensionRoot(sourceRoot, extensionRoot) {
+  return syncRuntimeTree(sourceRoot, extensionRoot, { materializeGeminiHooks: true })
+}
+
 /** Remove the stable runtime copy while leaving user settings under ~/.helloagents intact. */
 export function removeRuntimeRoot(runtimeRoot) {
   removeIfExists(runtimeRoot)
 }
+
+/** Remove the Claude marketplace projection root. */
+export function removeClaudeMarketplaceRoot(home) {
+  removeIfExists(getClaudeMarketplaceRoot(home))
+}
+
+/** Remove the Gemini extension projection root. */
+export function removeGeminiExtensionRoot(home) {
+  removeIfExists(getGeminiExtensionRoot(home))
+}