cc-team-viewer 1.4.16

package/README.md

@@ -0,0 +1,114 @@
+# CC-Viewer
+
+Claude Code 请求监控系统，实时捕获并可视化展示 Claude Code 的所有 API 请求与响应(原始文本，不做阉割)。方便开发者监控自己的 Context，以便于 Vibe Coding 过程中回顾和排查问题。
+
+## 使用方法
+
+### 安装
+
+```bash
+npm install -g cc-viewer
+```
+
+### 运行与自动配置
+
+```bash
+ccv
+```
+
+该命令会自动检测本地 Claude Code 的安装方式（NPM 或 Native Install）并进行适配。
+
+- **NPM 安装**：自动向 Claude Code 的 `cli.js` 中注入拦截脚本。
+- **Native Install**：自动检测 `claude` 二进制文件，配置本地透明代理，并设置 Zsh Shell Hook 自动转发流量。
+
+### 配置覆盖 (Configuration Override)
+
+如果您需要使用自定义 API 端点（例如企业代理），只需在 `~/.claude/settings.json` 中配置或设置 `ANTHROPIC_BASE_URL` 环境变量。`ccv` 会自动识别并正确转发请求。
+
+### 静默模式 (Silent Mode)
+
+默认情况下，`ccv` 在包裹 `claude` 运行时处于静默模式，确保您的终端输出保持整洁，与原生体验一致。所有日志都在后台捕获，并可通过 `http://localhost:7008` 查看。
+
+配置完成后，正常使用 `claude` 命令即可。访问 `http://localhost:7008` 查看监控界面。
+
+### 常见问题排查 (Troubleshooting)
+
+如果你遇到无法启动的问题，有一个终极排查方案：
+第一步：任意目录打开 claude code；
+第二步：给claude code下指令，内容如下:
+```
+我已经安装了cc-viewer这个npm包，但是执行ccv以后仍然无法有效运行。查看cc-viewer的cli.js 和 findcc.js，根据具体的环境，适配本地的claude code的部署方式。适配的时候修改范围尽量约束在findcc.js中。
+```
+让Claude Code自己检查错误是比咨询任何人以及看任何文档更有效的手段！
+
+以上指令完成后，会更新findcc.js。如果你的项目工程经常需要本地部署。或者fork出去的代码要经常解决安装问题，保留这个文件就可以。下次直接copy 文件。现阶段很多项目和公司用claude code都不是mac部署，而是服务端托管部署，所以作者剥离了findcc.js 这个文件，方便后续跟踪cc-viewer的源代码更新。
+
+### 卸载
+
+```bash
+ccv --uninstall
+```
+
+### 检查版本
+
+```bash
+ccv --version
+```
+
+## 功能
+
+### 请求监控（原文模式）
+<img width="1500" height="720" alt="image" src="https://github.com/user-attachments/assets/519dd496-68bd-4e76-84d7-2a3d14ae3f61" />
+- 实时捕获 Claude Code 发出的所有 API 请求，确保是原文，而不是被阉割之后的日志（这很重要！！！）
+- 自动识别并标记 Main Agent 和 Sub Agent 请求（子类型：Bash、Task、Plan、General）
+- MainAgent 请求支持 Body Diff JSON，折叠展示与上一次 MainAgent 请求的差异（仅显示变更/新增字段）
+- 每个请求内联显示 Token 用量统计（输入/输出 Token、缓存创建/读取、命中率）
+- 兼容 Claude Code Router（CCR）及其他代理场景 — 通过 API 路径模式兜底匹配请求
+
+### 对话模式
+
+点击右上角「对话模式」按钮，将 Main Agent 的完整对话历史解析为聊天界面：
+<img width="1500" height="730" alt="image" src="https://github.com/user-attachments/assets/c973f142-748b-403f-b2b7-31a5d81e33e6" />
+
+
+- 暂不支持Agent Team的展示
+- 用户消息右对齐（蓝色气泡），Main Agent 回复左对齐（深色气泡）
+- `thinking` 块默认折叠，以 Markdown 渲染，点击展开查看思考过程；支持一键翻译（功能还不稳定）
+- 用户选择型消息（AskUserQuestion）以问答形式展示
+- 双向模式同步：切换到对话模式时自动定位到选中请求对应的对话；切回原文模式时自动定位到选中的请求
+- 设置面板：可切换工具结果和思考块的默认折叠状态
+- 手机端对话浏览：在手机端 CLI 模式下，点击顶部栏的「对话浏览」按钮，即可滑出只读对话视图，在手机上浏览完整对话历史
+
+
+### 统计工具
+
+Header 区域的「数据统计」悬浮面板：
+<img width="1500" height="729" alt="image" src="https://github.com/user-attachments/assets/b23f9a81-fc3d-4937-9700-e70d84e4e5ce" />
+
+- 显示 cache creation/read 数量及缓存命中率
+- 缓存重建统计：按原因分组（TTL、system/tools/model 变更、消息截断/修改、key 变更）显示次数和 cache_creation tokens
+- 工具使用统计：按调用次数排序展示各工具的调用频率
+- Skill 使用统计：按调用次数排序展示各 Skill 的调用频率
+- 概念帮助 (?) 图标：点击可查看 MainAgent、CacheRebuild 及各工具的内置文档
+
+### 日志管理
+
+通过左上角 CC-Viewer 下拉菜单：
+<img width="1200" height="672" alt="image" src="https://github.com/user-attachments/assets/8cf24f5b-9450-4790-b781-0cd074cd3b39" />
+
+- 导入本地日志：浏览历史日志文件，按项目分组，在新窗口打开
+- 加载本地 JSONL 文件：直接选择本地 `.jsonl` 文件加载查看（支持最大 500MB）
+- 当前日志另存为：下载当前监控的 JSONL 日志文件
+- 合并日志：将多个 JSONL 日志文件合并为一个会话，统一分析
+- 查看用户 Prompt：提取并展示所有用户输入，支持三种查看模式 — 原文模式（原始内容）、上下文模式（系统标签可折叠）、Text 模式（纯文本）；斜杠命令（`/model`、`/context` 等）作为独立条目展示；命令相关标签自动从 Prompt 内容中隐藏
+- 导出 Prompt 为 TXT：将用户 Prompt（纯文本，不含系统标签）导出为本地 `.txt` 文件
+
+### 自动更新
+
+CC-Viewer 启动时自动检查更新（每 4 小时最多一次）。同一大版本内（如 1.x.x → 1.y.z）自动更新，下次启动生效。跨大版本仅显示通知提示。
+
+自动更新跟随 Claude Code 全局配置 `~/.claude/settings.json`。如果 Claude Code 禁用了自动更新（`autoUpdates: false`），CC-Viewer 也会跳过自动更新。
+
+## License
+
+MIT

package/build.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { execSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// 执行 vite build，输出到 dist/
+console.log('🔨 正在执行 Vite 构建...');
+execSync('npx vite build --config src/vite.config.js', { cwd: __dirname, stdio: 'inherit' });
+
+console.log('✅ Build 完成，输出目录: dist/');
+console.log('   - dist/index.html');
+console.log('   - dist/assets/');

package/cli/cli.js

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+
+import { readFileSync, writeFileSync, existsSync, realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { spawn } from 'node:child_process';
+import { INJECT_IMPORT, resolveCliPath, resolveNativePath, buildShellCandidates } from './findcc.js';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+const INJECT_START = '// >>> Start CC Viewer Web Service >>>';
+const INJECT_END = '// <<< Start CC Viewer Web Service <<<';
+const INJECT_BLOCK = `${INJECT_START}\n${INJECT_IMPORT}\n${INJECT_END}`;
+
+
+const SHELL_HOOK_START = '# >>> CC-Team-Viewer Auto-Inject >>>';
+const SHELL_HOOK_END = '# <<< CC-Team-Viewer Auto-Inject <<<';
+
+const cliPath = resolveCliPath();
+
+function getShellConfigPath() {
+  const shell = process.env.SHELL || '';
+  if (shell.includes('zsh')) return resolve(homedir(), '.zshrc');
+  if (shell.includes('bash')) {
+    const bashProfile = resolve(homedir(), '.bash_profile');
+    if (process.platform === 'darwin' && existsSync(bashProfile)) return bashProfile;
+    return resolve(homedir(), '.bashrc');
+  }
+  return resolve(homedir(), '.zshrc');
+}
+
+function buildShellHook(isNative) {
+  // Commands/flags that should pass through directly without cctv interception
+  // These are non-interactive commands that don't involve API calls
+  const passthroughCommands = [
+    // Subcommands (no API calls)
+    'doctor',      // health check for auto-updater
+    'install',     // install native build
+    'update',      // self-update
+    'upgrade',     // alias for update
+    'auth',        // authentication management
+    'setup-token', // token setup
+    'agents',      // list configured agents
+    'mcp',         // MCP server configuration
+  ];
+
+  const passthroughFlags = [
+    // Version/help info
+    '--version', '-v', '--v',
+    '--help', '-h',
+  ];
+
+  if (isNative) {
+    return `${SHELL_HOOK_START}
+claude() {
+  # Avoid recursion if cctv invokes claude
+  if [ "$1" = "--cctv-internal" ]; then
+    shift
+    command claude "$@"
+    return
+  fi
+  # Pass through certain commands directly without cctv interception
+  case "$1" in
+    ${passthroughCommands.join('|')})
+      command claude "$@"
+      return
+      ;;
+    ${passthroughFlags.join('|')})
+      command claude "$@"
+      return
+      ;;
+  esac
+  cctv run -- claude --cctv-internal "$@"
+}
+${SHELL_HOOK_END}`;
+  }
+
+  const candidates = buildShellCandidates();
+  return `${SHELL_HOOK_START}
+claude() {
+  local cli_js=""
+  for candidate in ${candidates}; do
+    if [ -f "$candidate" ]; then
+      cli_js="$candidate"
+      break
+    fi
+  done
+  if [ -n "$cli_js" ] && ! grep -q "CC Viewer" "$cli_js" 2>/dev/null; then
+    cctv 2>/dev/null
+  fi
+  command claude "$@"
+}
+${SHELL_HOOK_END}`;
+}
+
+function installShellHook(isNative) {
+  const configPath = getShellConfigPath();
+  try {
+    let content = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : '';
+
+    if (content.includes(SHELL_HOOK_START)) {
+      // Check if existing hook matches desired mode
+      const isNativeHook = content.includes('cctv run -- claude');
+      if (!!isNative === !!isNativeHook) {
+        return { path: configPath, status: 'exists' };
+      }
+      // Mismatch: remove old hook first
+      removeShellHook();
+      content = existsSync(configPath) ? readFileSync(configPath, 'utf-8') : '';
+    }
+
+    const hook = buildShellHook(isNative);
+    const newContent = content.endsWith('\n') ? content + '\n' + hook + '\n' : content + '\n\n' + hook + '\n';
+    writeFileSync(configPath, newContent);
+    return { path: configPath, status: 'installed' };
+  } catch (err) {
+    return { path: configPath, status: 'error', error: err.message };
+  }
+}
+
+function removeShellHook() {
+  const configPath = getShellConfigPath();
+  try {
+    if (!existsSync(configPath)) return { path: configPath, status: 'not_found' };
+    const content = readFileSync(configPath, 'utf-8');
+    if (!content.includes(SHELL_HOOK_START)) return { path: configPath, status: 'clean' };
+    const regex = new RegExp(`\\n?${SHELL_HOOK_START}[\\s\\S]*?${SHELL_HOOK_END}\\n?`, 'g');
+    const newContent = content.replace(regex, '\n');
+    writeFileSync(configPath, newContent);
+    return { path: configPath, status: 'removed' };
+  } catch (err) {
+    return { path: configPath, status: 'error', error: err.message };
+  }
+}
+
+function injectCliJs() {
+  const content = readFileSync(cliPath, 'utf-8');
+  if (content.includes(INJECT_START)) {
+    return 'exists';
+  }
+  const lines = content.split('\n');
+  lines.splice(2, 0, INJECT_BLOCK);
+  writeFileSync(cliPath, lines.join('\n'));
+  return 'injected';
+}
+
+function removeCliJsInjection() {
+  try {
+    if (!existsSync(cliPath)) return 'not_found';
+    const content = readFileSync(cliPath, 'utf-8');
+    if (!content.includes(INJECT_START)) return 'clean';
+    const regex = new RegExp(`${INJECT_START}\\n${INJECT_IMPORT}\\n${INJECT_END}\\n?`, 'g');
+    writeFileSync(cliPath, content.replace(regex, ''));
+    return 'removed';
+  } catch {
+    return 'error';
+  }
+}
+
+async function runProxyCommand(args) {
+  try {
+    // Dynamic import to avoid side effects when just installing
+    const { startProxy } = await import('../proxy/proxy.js');
+    const proxyPort = await startProxy();
+
+    // args = ['run', '--', 'command', 'claude', ...] or ['run', 'claude', ...]
+    // Our hook uses: cctv run -- claude --cctv-internal "$@"
+    // args[0] is 'run'.
+    // If args[1] is '--', then command starts at args[2].
+
+    let cmdStartIndex = 1;
+    if (args[1] === '--') {
+      cmdStartIndex = 2;
+    }
+
+    let cmd = args[cmdStartIndex];
+    if (!cmd) {
+      console.error('No command provided to run.');
+      process.exit(1);
+    }
+    let cmdArgs = args.slice(cmdStartIndex + 1);
+
+    // If cmd is 'claude' and next arg is '--cctv-internal', remove it
+    // and we must use 'command claude' to avoid infinite recursion of the shell function?
+    // Node spawn doesn't use shell functions, so 'claude' should resolve to the binary in PATH.
+    // BUT, if 'claude' is a function in the current shell, spawn won't see it unless we use shell:true.
+    // We are using shell:false (default).
+    // So spawn('claude') should find /usr/local/bin/claude (the binary).
+    // The issue might be that cctv itself is running in a way that PATH is weird?
+
+    // Wait, the shell hook adds '--cctv-internal'. We should strip it before spawning.
+    if (cmdArgs[0] === '--cctv-internal') {
+      cmdArgs.shift();
+    }
+
+    const env = { ...process.env };
+    // Determine the path to the native 'claude' executable
+    if (cmd === 'claude') {
+      const nativePath = resolveNativePath();
+      if (nativePath) {
+        cmd = nativePath;
+      }
+    }
+
+    // 保存原始 API URL，供 proxy.js 使用
+    // 如果 ANTHROPIC_BASE_URL 未设置或指向 localhost，使用默认值
+    const originalApiUrl = process.env.ANTHROPIC_BASE_URL && !process.env.ANTHROPIC_BASE_URL.includes('127.0.0.1') && !process.env.ANTHROPIC_BASE_URL.includes('localhost')
+      ? process.env.ANTHROPIC_BASE_URL
+      : 'https://api.anthropic.com';
+
+    env.CC_ORIGINAL_API_URL = originalApiUrl;
+    env.ANTHROPIC_BASE_URL = `http://127.0.0.1:${proxyPort}`;
+    env.CCV_PROXY_MODE = '1'; // 告诉 interceptor.js 不要再启动 server
+
+    const settingsJson = JSON.stringify({
+      env: {
+        ANTHROPIC_BASE_URL: env.ANTHROPIC_BASE_URL,
+        CC_ORIGINAL_API_URL: env.CC_ORIGINAL_API_URL
+      }
+    });
+
+    cmdArgs.unshift(settingsJson);
+    cmdArgs.unshift('--settings');
+
+    const child = spawn(cmd, cmdArgs, { stdio: 'inherit', env });
+
+    child.on('exit', (code) => {
+      process.exit(code);
+    });
+
+    child.on('error', (err) => {
+      console.error('Failed to start command:', err);
+      process.exit(1);
+    });
+  } catch (err) {
+    console.error('Proxy error:', err);
+    process.exit(1);
+  }
+}
+
+async function runCliMode(extraClaudeArgs = []) {
+  const nativePath = resolveNativePath();
+  if (!nativePath) {
+    console.error('错误: 未找到 claude 命令，请确认已安装 Claude Code');
+    process.exit(1);
+  }
+
+  console.log('正在启动 CC Viewer CLI 模式...');
+
+  // 2. 设置 CLI 模式标记（必须在 import proxy.js 之前，
+  //    因为 proxy.js → interceptor.js 可能触发 server.js 加载，
+  //    server.js 的 isCliMode 在模块顶层求值且只执行一次）
+  process.env.CCV_CLI_MODE = '1';
+
+  // 1. 启动代理
+  const { startProxy } = await import('../proxy/proxy.js');
+  const proxyPort = await startProxy();
+
+  // 3. 启动 HTTP 服务器
+  const { getPort, stopViewer } = await import('../server/server.js');
+
+  // 等待服务器启动完成
+  await new Promise(resolve => {
+    const check = () => {
+      const port = getPort();
+      if (port) resolve(port);
+      else setTimeout(check, 100);
+    };
+    setTimeout(check, 200);
+  });
+
+  const port = getPort();
+
+  // 3. 自动打开浏览器
+  const url = `http://127.0.0.1:${port}`;
+  try {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    const { execSync } = await import('node:child_process');
+    execSync(`${cmd} ${url}`, { stdio: 'ignore', timeout: 5000 });
+  } catch {}
+
+  console.log(`CC Viewer: ${url}`);
+
+  // 4. 注册退出处理
+  const cleanup = () => {
+    stopViewer();
+    process.exit();
+  };
+  process.on('SIGINT', cleanup);
+  process.on('SIGTERM', cleanup);
+}
+
+// === 主逻辑 ===
+
+const args = process.argv.slice(2);
+const isUninstall = args.includes('--uninstall');
+const isHelp = args.includes('--help') || args.includes('-h') || args[0] === 'help';
+const isVersion = args.includes('--v') || args.includes('--version') || args.includes('-v');
+const isCliMode = args.includes('--c') || args.includes('-c');
+const isDangerousMode = args.includes('-d') || args.includes('--d');
+
+if (isHelp) {
+  console.log(`CC Viewer CLI\n\n用法:\n  cctv [options]\n  cctv run -- <command> [args...]\n\n选项:\n  -h, --help        显示帮助\n  -v, --version     显示版本\n  -c, --c           CLI 模式：自动打开浏览器\n  -d, --d           Dangerous 模式：CLI 模式 + --dangerously-skip-permissions\n  --uninstall       移除 CC Viewer 集成\n\n说明:\n  直接运行 cctv 将安装/修复 Claude Code 的集成 Hook。`);
+  process.exit(0);
+}
+
+if (isVersion) {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(__dirname, 'package.json'), 'utf-8'));
+    console.log(`cctv v${pkg.version}`);
+  } catch (e) {
+    console.error('Failed to read version:', e.message);
+  }
+  process.exit(0);
+}
+
+if (isCliMode || isDangerousMode) {
+  const extraArgs = isDangerousMode ? ['--dangerously-skip-permissions'] : [];
+  runCliMode(extraArgs).catch(err => {
+    console.error('CLI mode error:', err);
+    process.exit(1);
+  });
+} else if (args[0] === 'run') {
+  runProxyCommand(args);
+} else if (isUninstall) {
+  const cliResult = removeCliJsInjection();
+  const shellResult = removeShellHook();
+
+  if (cliResult === 'removed' || cliResult === 'clean') {
+    console.log('cli.js 已清理');
+  } else if (cliResult === 'not_found') {
+    // Silent is better for mixed mode uninstall
+  } else {
+    console.log('cli.js 清理失败');
+  }
+
+  if (shellResult.status === 'removed') {
+    console.log(`shell hook 已从 ${shellResult.path} 移除`);
+  } else if (shellResult.status === 'clean' || shellResult.status === 'not_found') {
+    console.log(`${shellResult.path} 中无需清理`);
+  } else {
+    console.log(`shell hook 清理失败: ${shellResult.error}`);
+  }
+
+  console.log('CC Viewer 集成已移除 (运行 \'npm uninstall -g cctv\' 以彻底删除命令)');
+  process.exit(0);
+} else {
+  // Installation Logic
+  let mode = 'unknown';
+
+  // Check PATH to determine priority
+  let prefersNative = true; // default to native if not found in PATH
+  const paths = (process.env.PATH || '').split(':');
+  for (const dir of paths) {
+    if (!dir) continue;
+    const exePath = resolve(dir, 'claude');
+    if (existsSync(exePath)) {
+      try {
+        const real = realpathSync(exePath);
+        if (real.includes('node_modules')) {
+          prefersNative = false;
+        } else {
+          prefersNative = true;
+        }
+        break;
+      } catch (e) {
+        // ignore
+      }
+    }
+  }
+
+  const nativePath = resolveNativePath();
+  const hasNpm = existsSync(cliPath);
+
+  if (prefersNative) {
+    if (nativePath) {
+      mode = 'native';
+    } else if (hasNpm) {
+      mode = 'npm';
+    }
+  } else {
+    if (hasNpm) {
+      mode = 'npm';
+    } else if (nativePath) {
+      mode = 'native';
+    }
+  }
+
+  if (mode === 'unknown') {
+    console.error(`找不到 Claude Code cli.js: ${cliPath}`);
+    console.error('Also could not find native "claude" command in PATH.');
+    console.error('Please make sure @anthropic-ai/claude-code is installed.');
+    process.exit(1);
+  }
+
+  if (mode === 'npm') {
+    try {
+      const cliResult = injectCliJs();
+      const shellResult = installShellHook(false);
+
+      if (cliResult === 'exists' && shellResult.status === 'exists') {
+        console.log('CC Viewer 已经能工作了');
+      } else {
+        if (cliResult === 'exists') {
+          console.log('CC Viewer 已安装，无需重复操作');
+        } else {
+          console.log('CC Viewer 安装成功');
+        }
+
+        if (shellResult.status === 'installed') {
+          console.log('All READY!');
+        } else if (shellResult.status !== 'exists') {
+          console.log(`shell hook 写入失败: ${shellResult.error}`);
+        }
+      }
+      console.log('如需卸载，请运行: cctv --uninstall');
+    } catch (err) {
+      if (err.code === 'ENOENT') {
+        console.error(`找不到 Claude Code cli.js: ${cliPath}`);
+        console.error('请确认 @anthropic-ai/claude-code 已安装');
+      } else {
+        console.error(`安装失败: ${err.message}`);
+      }
+      process.exit(1);
+    }
+  } else {
+    // Native Mode
+    try {
+      console.log('Detected Claude Code Native Install.');
+      const shellResult = installShellHook(true);
+
+      if (shellResult.status === 'exists') {
+        console.log('CC Viewer 已经能工作了');
+      } else if (shellResult.status === 'installed') {
+        console.log('Native Hook Installed! All READY!');
+      } else {
+        console.log(`shell hook 写入失败: ${shellResult.error}`);
+      }
+      console.log('如需卸载，请运行: cctv --uninstall');
+    } catch (err) {
+      console.error('Failed to install native hook:', err);
+      process.exit(1);
+    }
+  }
+}

package/cli/findcc.js

@@ -0,0 +1,107 @@
+import { resolve, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+
+// ============ 配置区（第三方适配只需修改此处）============
+
+// 日志存储根目录（所有项目日志、偏好设置均存放于此）
+export const LOG_DIR = join(homedir(), '.claude', 'cc-team-viewer');
+
+// npm 包名候选列表（按优先级排列）
+export const PACKAGES = ['@anthropic-ai/claude-code', '@ali/claude-code'];
+
+// npm 包内的入口文件（相对于包根目录）
+export const CLI_ENTRY = 'cli.js';
+
+// native 二进制候选路径（~ 会在运行时展开为 homedir()）
+const NATIVE_CANDIDATES = [
+  '~/.claude/local/claude',
+  '/usr/local/bin/claude',
+  '~/.local/bin/claude',
+  '/opt/homebrew/bin/claude',
+];
+
+// 用于 which/command -v 查找的命令名
+export const BINARY_NAME = 'claude';
+
+// 注入到 cli.js 的 import 语句（相对路径，基于 cli.js 所在位置）
+export const INJECT_IMPORT = "import '../../cc-viewer/proxy/interceptor.js';";
+
+// ============ 导出函数 ============
+
+export function getGlobalNodeModulesDir() {
+  try {
+    return execSync('npm root -g', { encoding: 'utf-8' }).trim();
+  } catch {
+    return null;
+  }
+}
+
+export function resolveCliPath() {
+  // 候选基础目录：__dirname 的上级（适用于常规 npm 安装）+ 全局 node_modules（适用于符号链接安装）
+  const baseDirs = [resolve(__dirname, '..')];
+  const globalRoot = getGlobalNodeModulesDir();
+  if (globalRoot && globalRoot !== resolve(__dirname, '..')) {
+    baseDirs.push(globalRoot);
+  }
+
+  for (const baseDir of baseDirs) {
+    for (const packageName of PACKAGES) {
+      const candidate = join(baseDir, packageName, CLI_ENTRY);
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  }
+  // 兜底：返回全局目录下的默认路径，便于错误提示
+  return join(globalRoot || resolve(__dirname, '..'), PACKAGES[0], CLI_ENTRY);
+}
+
+export function resolveNativePath() {
+  // 1. 尝试 which/command -v（继承当前 process.env PATH）
+  for (const cmd of [`which ${BINARY_NAME}`, `command -v ${BINARY_NAME}`]) {
+    try {
+      const result = execSync(cmd, { encoding: 'utf-8', shell: true, env: process.env }).trim();
+      // 排除 shell function 的输出（多行说明不是路径）
+      if (result && !result.includes('\n') && existsSync(result)) {
+        return result;
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  // 2. 检查常见 native 安装路径
+  const home = homedir();
+  const candidates = NATIVE_CANDIDATES.map(p =>
+    p.startsWith('~') ? join(home, p.slice(2)) : p
+  );
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      return p;
+    }
+  }
+
+  return null;
+}
+
+export function buildShellCandidates() {
+  const globalRoot = getGlobalNodeModulesDir();
+  // 使用 $HOME 而非硬编码绝对路径，保证 shell 可移植性
+  const dirs = [];
+  if (globalRoot) {
+    // 将绝对路径中的 homedir 替换为 $HOME
+    const home = homedir();
+    const shellRoot = globalRoot.startsWith(home)
+      ? '$HOME' + globalRoot.slice(home.length)
+      : globalRoot;
+    for (const pkg of PACKAGES) {
+      dirs.push(`"${shellRoot}/${pkg}/${CLI_ENTRY}"`);
+    }
+  }
+  return dirs.join(' ');
+}