helloagents 3.0.33 → 3.0.37

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.33",
+  "version": "3.0.37",
   "description": "Quality-driven orchestration kernel for AI CLIs",
   "contextFileName": "bootstrap.md",
   "author": "HelloWind",

package/install.ps1

@@ -15,6 +15,8 @@ $Target = if ($env:HELLOAGENTS_TARGET) { $env:HELLOAGENTS_TARGET } else { "" }
 $Mode = if ($env:HELLOAGENTS_MODE) { $env:HELLOAGENTS_MODE } else { "" }
 $Branch = if ($env:HELLOAGENTS_BRANCH) { $env:HELLOAGENTS_BRANCH } else { "" }
 $Package = if ($env:HELLOAGENTS_PACKAGE) { $env:HELLOAGENTS_PACKAGE } else { "" }
+$HasExplicitPackage = [bool]$Package
+$HasExplicitTarget = $false
 
 if ($env:HELLOAGENTS) {
     $Parts = $env:HELLOAGENTS.Split(":", 2)
@@ -25,6 +27,8 @@ if ($env:HELLOAGENTS) {
     if (-not $Mode -and $Parts.Count -gt 1) { $Mode = $Parts[1] }
 }
 
+$HasExplicitTarget = [bool]$Target
+
 if (-not $Target) { $Target = "all" }
 $Target = $Target.ToLowerInvariant()
 if ($Mode) { $Mode = $Mode.ToLowerInvariant() }
@@ -53,6 +57,23 @@ function Invoke-Npm {
     }
 }
 
+function Clear-HelloagentsEnv {
+    foreach ($name in @(
+        "HELLOAGENTS",
+        "HELLOAGENTS_ACTION",
+        "HELLOAGENTS_TARGET",
+        "HELLOAGENTS_HOST",
+        "HELLOAGENTS_MODE",
+        "HELLOAGENTS_BRANCH",
+        "HELLOAGENTS_PACKAGE",
+        "HELLOAGENTS_DEPLOY"
+    )) {
+        Remove-Item "Env:$name" -ErrorAction SilentlyContinue
+    }
+}
+
+Clear-HelloagentsEnv
+
 function Enable-PostinstallDeploy {
     $env:HELLOAGENTS_DEPLOY = "1"
     $env:HELLOAGENTS_TARGET = $Target
@@ -89,11 +110,13 @@ function Uninstall-Hosts {
 
 switch ($Action) {
     "install" {
-        Enable-PostinstallDeploy
+        if ($HasExplicitTarget) {
+            Enable-PostinstallDeploy
+        }
         Invoke-Npm -NpmArgs @("install", "-g", $Package)
     }
     "update" {
-        if ($Branch -or $env:HELLOAGENTS_PACKAGE) {
+        if ($Branch -or $HasExplicitPackage) {
             Invoke-Npm -NpmArgs @("install", "-g", $Package)
         } else {
             & npm update -g helloagents
@@ -107,14 +130,14 @@ switch ($Action) {
         Cleanup-Hosts
     }
     "switch-branch" {
-        if (-not $Branch -and -not $env:HELLOAGENTS_PACKAGE) {
+        if (-not $Branch -and -not $HasExplicitPackage) {
             throw "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for switch-branch"
         }
         Invoke-Npm -NpmArgs @("install", "-g", $Package)
         Sync-Hosts
     }
     "branch" {
-        if (-not $Branch -and -not $env:HELLOAGENTS_PACKAGE) {
+        if (-not $Branch -and -not $HasExplicitPackage) {
             throw "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for branch"
         }
         Invoke-Npm -NpmArgs @("install", "-g", $Package)

package/install.sh

@@ -16,6 +16,11 @@ TARGET="${HELLOAGENTS_TARGET:-}"
 MODE="${HELLOAGENTS_MODE:-}"
 BRANCH="${HELLOAGENTS_BRANCH:-}"
 PACKAGE="${HELLOAGENTS_PACKAGE:-}"
+HAS_EXPLICIT_PACKAGE=0
+HAS_EXPLICIT_TARGET=0
+if [ -n "$PACKAGE" ]; then
+  HAS_EXPLICIT_PACKAGE=1
+fi
 
 if [ -n "${HELLOAGENTS:-}" ]; then
   SPEC_TARGET="${HELLOAGENTS%%:*}"
@@ -31,6 +36,10 @@ if [ -n "${HELLOAGENTS:-}" ]; then
   MODE="${MODE:-$SPEC_MODE}"
 fi
 
+if [ -n "$TARGET" ]; then
+  HAS_EXPLICIT_TARGET=1
+fi
+
 TARGET="${TARGET:-all}"
 TARGET="$(printf '%s' "$TARGET" | tr '[:upper:]' '[:lower:]')"
 MODE="$(printf '%s' "$MODE" | tr '[:upper:]' '[:lower:]')"
@@ -55,6 +64,19 @@ if [ -z "$PACKAGE" ]; then
   fi
 fi
 
+clear_lifecycle_env() {
+  unset HELLOAGENTS
+  unset HELLOAGENTS_ACTION
+  unset HELLOAGENTS_TARGET
+  unset HELLOAGENTS_HOST
+  unset HELLOAGENTS_MODE
+  unset HELLOAGENTS_BRANCH
+  unset HELLOAGENTS_PACKAGE
+  unset HELLOAGENTS_DEPLOY
+}
+
+clear_lifecycle_env
+
 sync_hosts() {
   if [ "$TARGET" = "all" ]; then
     if [ -n "$MODE" ]; then
@@ -111,11 +133,13 @@ enable_postinstall_deploy() {
 
 case "$ACTION" in
   install)
-    enable_postinstall_deploy
+    if [ "$HAS_EXPLICIT_TARGET" -eq 1 ]; then
+      enable_postinstall_deploy
+    fi
     npm install -g "$PACKAGE"
     ;;
   update)
-    if [ -n "$BRANCH" ] || [ -n "${HELLOAGENTS_PACKAGE:-}" ]; then
+    if [ -n "$BRANCH" ] || [ "$HAS_EXPLICIT_PACKAGE" -eq 1 ]; then
       npm install -g "$PACKAGE"
     else
       npm update -g helloagents || npm install -g helloagents
@@ -126,7 +150,7 @@ case "$ACTION" in
     cleanup_hosts
     ;;
   switch-branch|branch)
-    if [ -z "$BRANCH" ] && [ -z "${HELLOAGENTS_PACKAGE:-}" ]; then
+    if [ -z "$BRANCH" ] && [ "$HAS_EXPLICIT_PACKAGE" -ne 1 ]; then
       echo "HELLOAGENTS_BRANCH or HELLOAGENTS_PACKAGE is required for switch-branch" >&2
       exit 1
     fi

package/package.json

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

package/scripts/capability-registry.mjs

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

package/scripts/cli-doctor-codex.mjs

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

package/scripts/cli-doctor-render.mjs

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

package/scripts/cli-doctor.mjs

@@ -106,8 +106,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 hellowind777/helloagents; /plugin install helloagents@helloagents'
-    if (host === 'gemini') return 'gemini extensions install https://github.com/hellowind777/helloagents'
+    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 (status === 'not-installed') {
     return `helloagents install ${host} --standby`
@@ -176,7 +176,7 @@ function inspectGeminiDoctor(settings) {
   const detectedMode = normalizeDoctorMode(runtime.detectHostMode(host))
   const geminiDir = join(runtime.home, '.gemini')
   const geminiSettings = safeJson(join(geminiDir, 'settings.json')) || {}
-  const expectedHooks = readExpectedHooks('hooks.json', '${extensionPath}')
+  const expectedHooks = readExpectedHooks('hooks-gemini.json', '${extensionPath}')
   const checks = {
     carrierMarker: (safeRead(join(geminiDir, 'GEMINI.md')) || '').includes('HELLOAGENTS_START'),
     carrierContentMatch: extractManagedCarrierContent(join(geminiDir, 'GEMINI.md'))

package/scripts/cli-hosts.mjs

@@ -65,7 +65,7 @@ export function installGeminiStandby(home, pkgRoot) {
   createLink(pkgRoot, join(geminiDir, 'helloagents'));
 
   const settingsPath = join(geminiDir, 'settings.json');
-  const hooksData = loadHooksWithCliEntry(pkgRoot, 'hooks.json', '${extensionPath}');
+  const hooksData = loadHooksWithCliEntry(pkgRoot, 'hooks-gemini.json', '${extensionPath}');
   if (hooksData) mergeSettingsHooks(settingsPath, hooksData);
 
   return true;