helloagents 2.3.8 → 3.0.2-beta.1

package/scripts/cli-codex.mjs

@@ -0,0 +1,428 @@
+import { join, dirname } from 'node:path';
+import { existsSync, copyFileSync, readdirSync } from 'node:fs';
+import {
+  ensureDir, safeRead, safeWrite, removeIfExists,
+  readJsonOrThrow, copyEntries,
+  createLink, removeLink, injectMarkedContent, removeMarkedContent,
+} from './cli-utils.mjs';
+import {
+  upsertTopLevelTomlKey,
+  upsertTopLevelTomlBlock,
+  readTopLevelTomlLine,
+  readTopLevelTomlBlock,
+  ensureTopLevelTomlLine,
+  ensureTopLevelTomlBlock,
+  readTomlKeyInSection,
+  removeTomlKeyInSection,
+  removeTopLevelTomlBlock,
+  ensureTomlKeyInSection,
+  stripTomlSection,
+  removeTopLevelTomlLines,
+} from './cli-toml.mjs';
+
+export const CODEX_MARKETPLACE_NAME = 'local-plugins';
+export const CODEX_PLUGIN_NAME = 'helloagents';
+export const CODEX_PLUGIN_KEY = `${CODEX_PLUGIN_NAME}@${CODEX_MARKETPLACE_NAME}`;
+export const CODEX_PLUGIN_CONFIG_HEADER = `[plugins."${CODEX_PLUGIN_KEY}"]`;
+export const CODEX_MANAGED_TOML_COMMENT = '# helloagents-managed';
+export const CODEX_RUNTIME_CARRIER = 'AGENTS.md';
+const CODEX_BACKUP_TIMESTAMP_RE = /^\d{8}-\d{6}$/;
+const CODEX_CONFIG_BASENAME = 'config.toml';
+const CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME = 'developer_instructions';
+export const CODEX_DEVELOPER_INSTRUCTIONS = `CRITICAL: These are HelloAGENTS global defaults for Codex. Use them as the baseline for main-agent behavior. Spawned sub-agents should focus on the delegated task unless they are explicitly required to follow main-agent-only workflow.
+If the current workspace contains a project-level AGENTS.md or other repo-specific instructions, treat those as the more specific and authoritative instructions. Use these global defaults only where they do not conflict. Standby/global behavior is determined by the active workspace instructions, not by this global default block.
+If work was already in progress and earlier context was compressed, first restore the active project state from the most relevant project state files or other project-local context artifacts, then continue from the actual interruption point without restarting the workflow or repeating completed steps.`;
+export const CODEX_RUNTIME_ENTRIES = [
+  '.codex-plugin',
+  'assets',
+  'bootstrap.md',
+  'hooks',
+  'LICENSE.md',
+  'package.json',
+  'README.md',
+  'README_CN.md',
+  'scripts',
+  'skills',
+  'templates',
+];
+
+function formatBackupTimestamp(date = new Date()) {
+  const pad = (value, size = 2) => String(value).padStart(size, '0');
+  return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+}
+
+function getTimestampedBackupPath(filePath, backupBaseName) {
+  return join(dirname(filePath), `${backupBaseName}_${formatBackupTimestamp()}.bak`);
+}
+
+function listTimestampedBackups(directory, backupBaseName) {
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory)
+    .filter((name) => name.startsWith(`${backupBaseName}_`) && name.endsWith('.bak'))
+    .filter((name) => CODEX_BACKUP_TIMESTAMP_RE.test(name.slice(backupBaseName.length + 1, -4)))
+    .sort();
+}
+
+function getLatestTimestampedBackupPath(filePath, backupBaseName) {
+  const directory = dirname(filePath);
+  const backups = listTimestampedBackups(directory, backupBaseName);
+  const latest = backups.at(-1);
+  return latest ? join(directory, latest) : '';
+}
+
+function readLatestTimestampedBackup(filePath, backupBaseName) {
+  const backupPath = getLatestTimestampedBackupPath(filePath, backupBaseName);
+  return backupPath ? safeRead(backupPath) || '' : '';
+}
+
+function removeLatestTimestampedBackup(filePath, backupBaseName) {
+  const backupPath = getLatestTimestampedBackupPath(filePath, backupBaseName);
+  if (backupPath) removeIfExists(backupPath);
+}
+
+function ensureTimestampedBackup(filePath, backupBaseName) {
+  if (!existsSync(filePath)) return '';
+  const existingBackup = getLatestTimestampedBackupPath(filePath, backupBaseName);
+  if (existingBackup) return existingBackup;
+  const backupPath = getTimestampedBackupPath(filePath, backupBaseName);
+  copyFileSync(filePath, backupPath);
+  return backupPath;
+}
+
+function readCodexBackup(filePath, backupBaseName) {
+  const latest = readLatestTimestampedBackup(filePath, backupBaseName);
+  if (latest) return latest;
+  const legacyPath = `${filePath}.bak`;
+  return safeRead(legacyPath) || '';
+}
+
+function removeCodexBackup(filePath, backupBaseName) {
+  removeLatestTimestampedBackup(filePath, backupBaseName);
+  removeIfExists(`${filePath}.bak`);
+}
+
+function isManagedCodexStandbyInstructionPath(normalized = '') {
+  return /\/\.codex\/AGENTS\.md/i.test(normalized)
+    || /\/\.codex\/helloagents\/bootstrap-lite\.md/i.test(normalized);
+}
+
+function isManagedCodexGlobalInstructionPath(normalized = '') {
+  return /\/plugins\/helloagents\/AGENTS\.md/i.test(normalized)
+    || /\/plugins\/helloagents\/bootstrap\.md/i.test(normalized);
+}
+
+function upsertCodexPluginConfig(text) {
+  const stripped = stripTomlSection(text, CODEX_PLUGIN_CONFIG_HEADER).text.trimEnd();
+  const block = `${CODEX_PLUGIN_CONFIG_HEADER}\nenabled = true`;
+  return stripped ? `${stripped}\n\n${block}\n` : `${block}\n`;
+}
+
+function removeCodexPluginConfig(text) {
+  return stripTomlSection(text, CODEX_PLUGIN_CONFIG_HEADER).text;
+}
+
+function isManagedCodexModelInstruction(line = '') {
+  const normalized = String(line || '').replace(/\\/g, '/');
+  return line.includes('model_instructions_file')
+    && (
+      line.includes(CODEX_MANAGED_TOML_COMMENT)
+      || isManagedCodexStandbyInstructionPath(normalized)
+      || isManagedCodexGlobalInstructionPath(normalized)
+    );
+}
+
+function isManagedCodexNotify(line = '') {
+  return line.includes('codex-notify') || (line.includes('helloagents') && line.includes('notify'));
+}
+
+function isManagedCodexBackupInstruction(line = '') {
+  return line.includes(CODEX_MANAGED_TOML_COMMENT);
+}
+
+function formatManagedCodexDeveloperInstructions() {
+  return `"""\n${CODEX_DEVELOPER_INSTRUCTIONS}\n"""`;
+}
+
+function backupUserCodexDeveloperInstructions(configPath, existingBlock) {
+  if (!existingBlock || existingBlock.includes('HelloAGENTS')) return;
+  const backupPath = getTimestampedBackupPath(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME);
+  safeWrite(backupPath, `${existingBlock}\n`);
+}
+
+function sanitizeCodexDeveloperInstructionsBackup(block = '') {
+  const normalized = String(block || '').trim();
+  if (!normalized.startsWith('developer_instructions =')) return '';
+  if (normalized.includes(CODEX_DEVELOPER_INSTRUCTIONS)) return '';
+  return normalized;
+}
+
+function readCodexDeveloperInstructionsBackup(configPath) {
+  return sanitizeCodexDeveloperInstructionsBackup(
+    readCodexBackup(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME),
+  );
+}
+
+function removeCodexDeveloperInstructionsBackup(configPath) {
+  removeCodexBackup(configPath, CODEX_DEVELOPER_INSTRUCTIONS_BACKUP_BASENAME);
+}
+
+function installCodexDeveloperInstructions(configPath, toml) {
+  const existing = readTopLevelTomlBlock(toml, 'developer_instructions');
+  backupUserCodexDeveloperInstructions(configPath, existing);
+  return upsertTopLevelTomlBlock(toml, 'developer_instructions', formatManagedCodexDeveloperInstructions());
+}
+
+function uninstallCodexDeveloperInstructions(configPath, toml) {
+  const existing = readTopLevelTomlBlock(toml, 'developer_instructions');
+  if (!existing.includes('HelloAGENTS')) return toml;
+  let next = removeTopLevelTomlBlock(toml, 'developer_instructions');
+  const backupDeveloperInstructions = readCodexDeveloperInstructionsBackup(configPath);
+  next = ensureTopLevelTomlBlock(next, 'developer_instructions', backupDeveloperInstructions);
+  removeCodexDeveloperInstructionsBackup(configPath);
+  return next;
+}
+
+function getDefaultCodexMarketplace() {
+  return {
+    name: CODEX_MARKETPLACE_NAME,
+    interface: {
+      displayName: 'Local Plugins',
+    },
+    plugins: [],
+  };
+}
+
+function updateCodexMarketplace(marketplaceFile) {
+  const marketplace = readJsonOrThrow(marketplaceFile, 'Codex marketplace 配置') || getDefaultCodexMarketplace();
+  marketplace.name = CODEX_MARKETPLACE_NAME;
+  marketplace.interface = marketplace.interface || { displayName: 'Local Plugins' };
+  marketplace.plugins = Array.isArray(marketplace.plugins) ? marketplace.plugins : [];
+
+  const nextEntry = {
+    name: CODEX_PLUGIN_NAME,
+    source: {
+      source: 'local',
+      path: `./plugins/${CODEX_PLUGIN_NAME}`,
+    },
+    policy: {
+      installation: 'AVAILABLE',
+      authentication: 'ON_INSTALL',
+    },
+    category: 'Coding',
+  };
+
+  const existingIndex = marketplace.plugins.findIndex((plugin) => plugin?.name === CODEX_PLUGIN_NAME);
+  if (existingIndex >= 0) {
+    marketplace.plugins.splice(existingIndex, 1, nextEntry);
+  } else {
+    marketplace.plugins.push(nextEntry);
+  }
+
+  safeWrite(marketplaceFile, JSON.stringify(marketplace, null, 2) + '\n');
+}
+
+function removeCodexMarketplaceEntry(marketplaceFile) {
+  if (!existsSync(marketplaceFile)) return false;
+  const marketplace = readJsonOrThrow(marketplaceFile, 'Codex marketplace 配置');
+  const plugins = Array.isArray(marketplace?.plugins) ? marketplace.plugins : [];
+  const nextPlugins = plugins.filter((plugin) => plugin?.name !== CODEX_PLUGIN_NAME);
+  const removedHelloagents = nextPlugins.length !== plugins.length;
+  const isManagedMarketplace = (marketplace?.name || CODEX_MARKETPLACE_NAME) === CODEX_MARKETPLACE_NAME;
+  if (!nextPlugins.length && isManagedMarketplace) {
+    removeIfExists(marketplaceFile);
+    return removedHelloagents || true;
+  }
+  if (!removedHelloagents) return false;
+  if (!nextPlugins.length) {
+    removeIfExists(marketplaceFile);
+    return true;
+  }
+  marketplace.plugins = nextPlugins;
+  safeWrite(marketplaceFile, JSON.stringify(marketplace, null, 2) + '\n');
+  return true;
+}
+
+function normalizePath(path) {
+  return path.replace(/\\/g, '/');
+}
+
+function buildCodexRuntimeCarrier(bootstrapContent) {
+  const normalized = String(bootstrapContent || '').trim();
+  return normalized ? `${normalized}\n` : '';
+}
+
+function writeCodexRuntimeCarrier(filePath, bootstrapPath) {
+  const bootstrapContent = safeRead(bootstrapPath);
+  if (!bootstrapContent) return false;
+  safeWrite(filePath, buildCodexRuntimeCarrier(bootstrapContent));
+  return true;
+}
+
+export function installCodexStandby(home, pkgRoot) {
+  const codexDir = join(home, '.codex');
+  if (!existsSync(codexDir)) return false;
+  ensureDir(codexDir);
+
+  const codexAgentsPath = join(codexDir, CODEX_RUNTIME_CARRIER);
+  const bootstrapContent = safeRead(join(pkgRoot, 'bootstrap-lite.md'));
+  if (bootstrapContent) {
+    injectMarkedContent(
+      codexAgentsPath,
+      buildCodexRuntimeCarrier(bootstrapContent).trimEnd(),
+    );
+  }
+
+  const configPath = join(codexDir, 'config.toml');
+  let toml = safeRead(configPath) || '';
+  ensureTimestampedBackup(configPath, CODEX_CONFIG_BASENAME);
+
+  toml = upsertTopLevelTomlKey(toml, 'notify', `["node", "${normalizePath(join(pkgRoot, 'scripts', 'notify.mjs'))}", "codex-notify"]`);
+  toml = installCodexDeveloperInstructions(configPath, toml);
+  safeWrite(configPath, toml);
+
+  createLink(pkgRoot, join(codexDir, 'helloagents'));
+  return true;
+}
+
+export function uninstallCodexStandby(home) {
+  const codexDir = join(home, '.codex');
+  let changed = false;
+
+  if (existsSync(codexDir)) {
+    removeMarkedContent(join(codexDir, 'AGENTS.md'));
+
+    const configPath = join(codexDir, 'config.toml');
+    const backupToml = readCodexBackup(configPath, CODEX_CONFIG_BASENAME);
+    let toml = safeRead(configPath) || '';
+    if (toml.includes('helloagents') || toml.includes('HelloAGENTS')) {
+      toml = removeTopLevelTomlLines(toml, (line) => {
+        if (!line) return false;
+        if (line.startsWith('model_instructions_file =') && isManagedCodexModelInstruction(line)) return true;
+        if (line.startsWith('notify =') && line.includes('codex-notify')) return true;
+        return false;
+      }).text;
+      toml = uninstallCodexDeveloperInstructions(configPath, toml);
+      toml = removeTomlKeyInSection(toml, '[features]', 'codex_hooks');
+      const backupModelInstructions = readTopLevelTomlLine(backupToml, 'model_instructions_file');
+      const backupNotify = readTopLevelTomlLine(backupToml, 'notify');
+      toml = ensureTopLevelTomlLine(
+        toml,
+        'model_instructions_file',
+        isManagedCodexBackupInstruction(backupModelInstructions) ? '' : backupModelInstructions,
+      );
+      toml = ensureTopLevelTomlLine(
+        toml,
+        'notify',
+        isManagedCodexNotify(backupNotify) ? '' : backupNotify,
+      );
+      toml = ensureTomlKeyInSection(toml, '[features]', 'codex_hooks', readTomlKeyInSection(backupToml, '[features]', 'codex_hooks'));
+      if (toml.trim()) safeWrite(configPath, toml);
+      else removeIfExists(configPath);
+      changed = true;
+    }
+    removeCodexBackup(configPath, CODEX_CONFIG_BASENAME);
+    removeIfExists(join(codexDir, 'hooks.json'));
+    removeLink(join(codexDir, 'helloagents'));
+    changed = true;
+  }
+
+  for (const path of [join(codexDir, 'skills', 'helloagents'), join(home, '.agents', 'skills', 'helloagents')]) {
+    changed = removeLink(path) || changed;
+  }
+
+  return changed;
+}
+
+export function installCodexGlobal(home, pkgRoot) {
+  const codexDir = join(home, '.codex');
+  if (!existsSync(codexDir)) return false;
+
+  const pluginRoot = join(home, 'plugins', CODEX_PLUGIN_NAME);
+  const installedPluginRoot = join(
+    codexDir,
+    'plugins',
+    'cache',
+    CODEX_MARKETPLACE_NAME,
+    CODEX_PLUGIN_NAME,
+    'local',
+  );
+  const marketplaceFile = join(home, '.agents', 'plugins', 'marketplace.json');
+  const configPath = join(codexDir, 'config.toml');
+
+  ensureDir(codexDir);
+  removeIfExists(pluginRoot);
+  removeIfExists(join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME));
+
+  ensureDir(join(home, 'plugins'));
+  ensureDir(installedPluginRoot);
+
+  copyEntries(pkgRoot, pluginRoot, CODEX_RUNTIME_ENTRIES);
+  copyEntries(pkgRoot, installedPluginRoot, CODEX_RUNTIME_ENTRIES);
+  writeCodexRuntimeCarrier(
+    join(pluginRoot, CODEX_RUNTIME_CARRIER),
+    join(pluginRoot, 'bootstrap.md'),
+  );
+  writeCodexRuntimeCarrier(
+    join(installedPluginRoot, CODEX_RUNTIME_CARRIER),
+    join(installedPluginRoot, 'bootstrap.md'),
+  );
+
+  ensureDir(join(home, '.agents', 'plugins'));
+  updateCodexMarketplace(marketplaceFile);
+
+  let toml = safeRead(configPath) || '';
+  ensureTimestampedBackup(configPath, CODEX_CONFIG_BASENAME);
+  toml = upsertTopLevelTomlKey(
+    toml,
+    'notify',
+    `["node", "${normalizePath(join(pluginRoot, 'scripts', 'notify.mjs'))}", "codex-notify"]`,
+  );
+  toml = upsertCodexPluginConfig(toml);
+  toml = installCodexDeveloperInstructions(configPath, toml);
+  safeWrite(configPath, toml);
+
+  return true;
+}
+
+export function uninstallCodexGlobal(home) {
+  const codexDir = join(home, '.codex');
+
+  const pluginRoot = join(home, 'plugins', CODEX_PLUGIN_NAME);
+  const pluginCacheRoot = join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME);
+  const marketplaceFile = join(home, '.agents', 'plugins', 'marketplace.json');
+  const configPath = join(codexDir, 'config.toml');
+
+  removeIfExists(pluginRoot);
+  removeIfExists(pluginCacheRoot);
+  removeCodexMarketplaceEntry(marketplaceFile);
+
+  const backupToml = readCodexBackup(configPath, CODEX_CONFIG_BASENAME);
+  let toml = safeRead(configPath) || '';
+  toml = removeCodexPluginConfig(toml);
+  toml = uninstallCodexDeveloperInstructions(configPath, toml);
+  toml = removeTomlKeyInSection(toml, '[features]', 'codex_hooks');
+  toml = removeTopLevelTomlLines(toml, (line) =>
+    line.startsWith('model_instructions_file =')
+    && isManagedCodexModelInstruction(line)).text;
+  toml = removeTopLevelTomlLines(toml, (line) =>
+    line.startsWith('notify =')
+    && line.includes('/plugins/helloagents/scripts/notify.mjs')).text;
+  const backupModelInstructions = readTopLevelTomlLine(backupToml, 'model_instructions_file');
+  const backupNotify = readTopLevelTomlLine(backupToml, 'notify');
+  toml = ensureTopLevelTomlLine(
+    toml,
+    'model_instructions_file',
+    isManagedCodexBackupInstruction(backupModelInstructions) ? '' : backupModelInstructions,
+  );
+  toml = ensureTopLevelTomlLine(
+    toml,
+    'notify',
+    isManagedCodexNotify(backupNotify) ? '' : backupNotify,
+  );
+  toml = ensureTomlKeyInSection(toml, '[features]', 'codex_hooks', readTomlKeyInSection(backupToml, '[features]', 'codex_hooks'));
+  if (toml.trim()) safeWrite(configPath, toml);
+  else removeIfExists(configPath);
+  removeCodexBackup(configPath, CODEX_CONFIG_BASENAME);
+
+  return true;
+}

package/scripts/cli-config.mjs

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+
+export const DEFAULTS = {
+  output_language: '',
+  output_format: true,
+  notify_level: 0,
+  ralph_loop_enabled: true,
+  guard_enabled: true,
+  kb_create_mode: 1,
+  commit_attribution: '',
+  install_mode: 'standby',
+};
+
+export function loadPackageVersion(pkgRoot) {
+  try {
+    return JSON.parse(readFileSync(`${pkgRoot}/package.json`, 'utf-8'));
+  } catch {
+    return { version: '0.0.0' };
+  }
+}
+
+export function ensureConfig(helloagentsHome, configFile, safeJson, ensureDir) {
+  ensureDir(helloagentsHome);
+  if (!existsSync(configFile)) {
+    writeFileSync(configFile, JSON.stringify(DEFAULTS, null, 2), 'utf-8');
+    return;
+  }
+
+  const existing = safeJson(configFile) || {};
+  const reconciled = { ...existing };
+  for (const [key, val] of Object.entries(DEFAULTS)) {
+    if (!(key in reconciled)) reconciled[key] = val;
+  }
+  if (JSON.stringify(reconciled) !== JSON.stringify(existing)) {
+    writeFileSync(configFile, JSON.stringify(reconciled, null, 2), 'utf-8');
+  }
+}

package/scripts/cli-hosts.mjs

@@ -0,0 +1,75 @@
+import { join } from 'node:path';
+import { existsSync } from 'node:fs';
+import {
+  ensureDir,
+  safeRead,
+  removeIfExists,
+  createLink,
+  removeLink,
+  injectMarkedContent,
+  removeMarkedContent,
+  mergeSettingsHooks,
+  cleanSettingsHooks,
+  loadHooksWithAbsPath,
+} from './cli-utils.mjs';
+
+export function installClaudeStandby(home, pkgRoot) {
+  const claudeDir = join(home, '.claude');
+  ensureDir(claudeDir);
+
+  const bootstrapContent = safeRead(join(pkgRoot, 'bootstrap-lite.md'));
+  if (bootstrapContent) {
+    injectMarkedContent(join(claudeDir, 'CLAUDE.md'), bootstrapContent);
+  }
+
+  createLink(pkgRoot, join(claudeDir, 'helloagents'));
+
+  const settingsPath = join(claudeDir, 'settings.json');
+  const hooksData = loadHooksWithAbsPath(pkgRoot, 'hooks-claude.json', '${CLAUDE_PLUGIN_ROOT}');
+  if (hooksData) {
+    mergeSettingsHooks(settingsPath, hooksData, ['Read(~/.claude/helloagents/**)']);
+  }
+
+  return true;
+}
+
+export function uninstallClaudeStandby(home) {
+  const claudeDir = join(home, '.claude');
+  if (!existsSync(claudeDir)) return false;
+
+  removeMarkedContent(join(claudeDir, 'CLAUDE.md'));
+  removeLink(join(claudeDir, 'helloagents'));
+  cleanSettingsHooks(join(claudeDir, 'settings.json'), true);
+
+  return true;
+}
+
+export function installGeminiStandby(home, pkgRoot) {
+  const geminiDir = join(home, '.gemini');
+  ensureDir(geminiDir);
+
+  const bootstrapContent = safeRead(join(pkgRoot, 'bootstrap-lite.md'));
+  if (bootstrapContent) {
+    injectMarkedContent(join(geminiDir, 'GEMINI.md'), bootstrapContent);
+  }
+
+  createLink(pkgRoot, join(geminiDir, 'helloagents'));
+
+  const settingsPath = join(geminiDir, 'settings.json');
+  const hooksData = loadHooksWithAbsPath(pkgRoot, 'hooks.json', '${extensionPath}');
+  if (hooksData) mergeSettingsHooks(settingsPath, hooksData);
+
+  return true;
+}
+
+export function uninstallGeminiStandby(home) {
+  const geminiDir = join(home, '.gemini');
+  if (!existsSync(geminiDir)) return false;
+
+  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-messages.mjs

@@ -0,0 +1,92 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function createMessageHelpers(isCN) {
+  const msg = (cn, en) => (isCN ? cn : en);
+  const ok = (message) => console.log(`  ✓ ${message}`);
+  return { msg, ok };
+}
+
+export function createInstallMessagePrinter({ home, pkgVersion, msg }) {
+  const codexStandbyStatus = () => existsSync(join(home, '.codex'))
+    ? msg('已自动配置', 'Auto-configured')
+    : msg('安装 Codex CLI 后重新运行 npm install -g helloagents', 'Install Codex CLI then re-run npm install -g helloagents');
+
+  const codexGlobalStatus = () => existsSync(join(home, '.codex'))
+    ? msg('已自动安装原生本地插件', 'Native local plugin auto-installed')
+    : msg('安装 Codex CLI 后重新运行 npm install -g helloagents', 'Install Codex CLI then re-run npm install -g helloagents');
+
+  const PLUGIN_CMDS = '    Claude Code:  /plugin marketplace add hellowind777/helloagents\n                  /plugin install helloagents@helloagents\n    Gemini CLI:   gemini extensions install https://github.com/hellowind777/helloagents';
+  const REMOVE_HINT = msg(
+    '如已安装 Claude Code 插件，建议手动移除: /plugin remove helloagents\n  如已安装 Gemini CLI 扩展，建议手动移除: gemini extensions uninstall helloagents',
+    'If Claude Code plugin installed, consider removing: /plugin remove helloagents\n  If Gemini CLI extension installed, consider removing: gemini extensions uninstall helloagents',
+  );
+
+  function printInstallMsg(mode, context) {
+    const isSwitch = context === 'switch';
+    const isRefresh = context === 'refresh';
+    const isInstall = !isSwitch && !isRefresh;
+    if (mode === 'global') {
+      if (isInstall) console.log(msg(
+        `\n  ✅ HelloAGENTS 已安装（global 模式）！\n\n${PLUGIN_CMDS}\n    Codex:        ${codexGlobalStatus()}（~/.agents/plugins/marketplace.json + ~/plugins/helloagents）\n\n  切换模式：\n    helloagents --standby   标准模式（默认，非插件安装）`,
+        `\n  ✅ HelloAGENTS installed (global mode)!\n\n${PLUGIN_CMDS}\n    Codex:        ${codexGlobalStatus()} (~/.agents/plugins/marketplace.json + ~/plugins/helloagents)\n\n  Switch modes:\n    helloagents --standby   Standby mode (default, non-plugin install)`,
+      ));
+      else console.log(msg(
+        isRefresh
+          ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件链路已重装并同步最新文件。'
+          : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动走原生本地插件链路。',
+        isRefresh
+          ? '  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.',
+      ));
+    } else {
+      if (isInstall) console.log(msg(
+        `\n  ✅ HelloAGENTS 已安装（standby 模式）！\n\n    Claude Code:  已自动配置（~/.claude/CLAUDE.md + hooks）\n    Gemini CLI:   已自动配置（~/.gemini/GEMINI.md）\n    Codex:        ${codexStandbyStatus()}\n\n  standby 模式下，hello-* 技能不会自动触发。\n  在项目中使用 ~init 激活完整功能，或使用 ~command 按需调用。\n\n  切换模式：\n    helloagents --global    全局模式（Claude/Gemini 装插件；Codex 自动装原生本地插件）`,
+        `\n  ✅ HelloAGENTS installed (standby mode)!\n\n    Claude Code:  Auto-configured (~/.claude/CLAUDE.md + hooks)\n    Gemini CLI:   Auto-configured (~/.gemini/GEMINI.md)\n    Codex:        ${codexStandbyStatus()}\n\n  In standby mode, hello-* skills won't auto-trigger.\n  Use ~init in a project to activate full features, or use ~command on demand.\n\n  Switch modes:\n    helloagents --global    Global mode (manual plugins for Claude/Gemini; native local plugin auto-install for Codex)`,
+      ));
+      else console.log(msg(
+        isRefresh
+          ? `  standby 模式已刷新，CLI 注入与链接已同步最新文件。\n  ${REMOVE_HINT}`
+          : `  项目需通过 ~init 激活完整功能，未激活项目仅注入通用规则。\n  ${REMOVE_HINT}`,
+        isRefresh
+          ? `  Standby mode refreshed; injected files and links were synchronized.\n  ${REMOVE_HINT}`
+          : `  Projects need ~init to activate full features. Unactivated projects get lite rules only.\n  ${REMOVE_HINT}`,
+      ));
+    }
+    if (isInstall || isRefresh) console.log();
+  }
+
+  function printHelp() {
+    console.log(`
+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 ...)')}
+  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 --standby    ${msg('标准模式（非插件安装，hello-* 不自动触发，默认）', "Standby mode (non-plugin install, hello-* won't auto-trigger, default)")}
+
+${msg('单 CLI 管理', 'Scoped CLI management')}:
+  helloagents install codex --standby
+  helloagents install --all --global
+  helloagents update codex
+  helloagents cleanup claude --global
+  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('卸载', 'Uninstall')}:
+  helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}
+  npm uninstall -g helloagents
+  ${msg('如已安装插件，另需手动移除：', 'If plugins installed, also remove manually:')}
+    Claude Code:  /plugin remove helloagents
+    Gemini CLI:   gemini extensions uninstall helloagents
+`.trim());
+  }
+
+  return {
+    printHelp,
+    printInstallMsg,
+  };
+}