acpDetector = new AcpDetector()   // 模块级单例，导出供全局使用

initialize()
│
├── Promise.all([
│   ├── detectBuiltinAgents()     ← Source 1: 内置已知 CLI 列表
│   ├── detectExtensionAgents()   ← Source 2: 扩展注册表
│   └── detectCustomAgents()      ← Source 3: 用户自定义配置
│])
│
├── 合成 Gemini agent（始终存在，无需 CLI 检测）
│
├── 合并: [Aionrs, Gemini, ...Builtin, ...Other, ...Remote, ...Extension]
│
└── this.isInitialized = true

which <command>

1. bundledBunDir              ← 最高优先级，内置 bun 运行时
2. process.env.PATH           ← 当前进程环境
3. shellEnv.PATH              ← 用户登录 shell 环境
4. 平台额外工具路径           ← 按平台扫描已知安装目录
5. customEnv.PATH             ← 调用者自定义（如有）

用户选择 Claude Code → 发送消息
│
├── [IPC Bridge] acpConversationBridge
│   └── workerTaskManager.getOrBuildTask(conversationId)
│
├── [Task Manager] AcpAgentManager
│   ├── resolveCliPath('claude') → 'claude' 或用户配置路径
│   ├── new AcpAgent({ backend: 'claude', cliPath, ... })
│   └── agent.start()
│
├── [Agent] AcpAgent.start()
│   ├── connection.connect('claude', cliPath, workingDir)
│   ├── performAuthentication()
│   ├── createOrResumeSession()
│   ├── applyYoloMode() (if enabled)
│   └── applyModelFromSettings()
│
├── [Connection] AcpConnection.connect('claude')
│   └── doConnect() → switch('claude') → connectClaude()
│
├── [Connector] connectClaude()
│   └── connectNpxBackend({
│       npxPackage: '@zed-industries/[email protected]',
│       prepareFn: prepareClaude,
│   })
│
├── [Spawn] spawnNpxBackend()
│   └── spawn(npxCommand, ['--yes', '--prefer-offline',
│       '@zed-industries/[email protected]'], { stdio: 'pipe', detached: true })
│
├── [Protocol] setupChildProcessHandlers()
│   ├── stdout → NDJSON 解析 → handleMessage()
│   ├── stderr → 诊断缓冲
│   └── initialize() → JSON-RPC handshake
│
└── [Session] newSession() / sendPrompt()
    └── JSON-RPC over stdin/stdout

# 实际执行的命令 (macOS)
/usr/local/bin/npx --yes --prefer-offline @zed-industries/[email protected]

async function prepareClaude(): Promise<NpxPrepareResult> {
  const cleanEnv = await prepareCleanEnv();
  ensureMinNodeVersion(cleanEnv, 20, 10, 'Claude ACP bridge');
  return { cleanEnv, npxCommand: resolveNpxPath(cleanEnv) };
}

Phase 1: npx --yes --prefer-offline @zed-industries/[email protected]
         ↓ 失败?
Phase 2: npx --yes @zed-industries/[email protected]  (无 --prefer-offline)

spawn(
  npxCommand,
  [
    '--yes', // 自动确认安装
    '--prefer-offline', // Phase 1 only
    '@zed-industries/[email protected]',
  ],
  {
    cwd: workingDir,
    stdio: ['pipe', 'pipe', 'pipe'], // stdin/stdout/stderr 全部 pipe
    env: cleanEnv,
    shell: false, // Unix 不使用 shell
    detached: true, // macOS/Linux: 创建新 session，防止 SIGTTOU
  }
);
child.unref(); // 允许父进程正常退出

let buffer = '';
child.stdout?.on('data', (data: Buffer) => {
  buffer += data.toString();
  const lines = buffer.split('\n');
  buffer = lines.pop() || ''; // 保留不完整的最后一行

  for (const line of lines) {
    if (line.trim()) {
      const message = JSON.parse(line) as AcpMessage;
      this.handleMessage(message);
    }
  }
});

await Promise.race([
  this.initialize(), // 发送 initialize 请求
  new Promise((reject) => setTimeout(reject, 60000)), // 60 秒超时
  processExitPromise, // 进程提前退出则立即失败
]);

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": { "protocolVersion": 1, "clientCapabilities": { "fs": { "readTextFile": true, "writeTextFile": true } } }
}

// 发出：
{"jsonrpc":"2.0","id":2,"method":"session/new","params":{
  "cwd": ".",
  "mcpServers": [...],
  "_meta": {
    "claudeCode": {
      "options": {
        "resume": "<existing-session-id>"
      }
    }
  }
}}

// 发出：
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/prompt",
  "params": {
    "sessionId": "abc123",
    "prompt": [{ "type": "text", "text": "用户输入的消息" }]
  }
}

AcpConnection.onSessionUpdate
  → AcpAgent.handleSessionUpdate()
    → AcpAdapter.convertSessionUpdate()  // 转换为 TMessage[]
    → AcpAgent.emitMessage()
      → AcpAgentManager.onStreamEvent callback
        → transformMessage() → addOrUpdateMessage() (DB)
        → ipcBridge.acpConversation.responseStream.emit() (to renderer)

{ "jsonrpc": "2.0", "method": "session/cancel", "params": { "sessionId": "abc123" } }

AcpConnection.disconnect()
  → stopPromptKeepalive()
  → terminateChild()
    → killChild()
      macOS/Linux (detached): process.kill(-pid, 'SIGTERM')  // 杀进程组
      Windows: taskkill /PID <pid> /T /F
    → 等待最多 3 秒
  → 重置所有状态

@agentclientprotocol/claude-agent-acp
  ├── @agentclientprotocol/sdk (0.17.0)         -- ACP 协议实现
  ├── @anthropic-ai/claude-agent-sdk (0.2.83+)   -- Claude Code SDK
  │     ├── @anthropic-ai/sdk (^0.80.0)          -- Anthropic API client
  │     ├── @modelcontextprotocol/sdk (^1.27.1)  -- MCP 协议
  │     └── cli.js                               -- 内嵌的 Claude Code CLI (~13MB)
  └── zod (^3.25.0 || ^4.0.0)

// --cli 模式: 直接运行 SDK 内嵌的 Claude CLI
if (process.argv.includes('--cli')) {
  await import(await claudeCliPath());
}

// 默认模式: 作为 ACP agent 运行
runAcp();

export function runAcp() {
  const input = nodeToWebWritable(process.stdout);
  const output = nodeToWebReadable(process.stdin);
  const stream = ndJsonStream(input, output);
  new AgentSideConnection((client) => new ClaudeAcpAgent(client), stream);
}

import { getSessionMessages, listSessions, query } from '@anthropic-ai/claude-agent-sdk';

const q = query({
  prompt: input, // AsyncIterable<SDKUserMessage> (Pushable)
  options, // session 配置
});

// sdk.mjs 反混淆后的伪代码
let pathToClaudeCodeExecutable = options.pathToClaudeCodeExecutable;
if (!pathToClaudeCodeExecutable) {
  const currentDir = fileURLToPath(import.meta.url);
  const parentDir = path.join(currentDir, '..');
  pathToClaudeCodeExecutable = path.join(parentDir, 'cli.js');
}

export async function claudeCliPath() {
  return isStaticBinary()
    ? (await import('@anthropic-ai/claude-agent-sdk/embed')).default
    : import.meta.resolve('@anthropic-ai/claude-agent-sdk').replace('sdk.mjs', 'cli.js');
}

...(process.env.CLAUDE_CODE_EXECUTABLE
    ? { pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_EXECUTABLE }
    : isStaticBinary()
        ? { pathToClaudeCodeExecutable: await claudeCliPath() }
        : {}),

// sdk.mjs 反混淆
const isNativeBinary =
  !pathToClaudeCodeExecutable.endsWith('.js') &&
  !pathToClaudeCodeExecutable.endsWith('.mjs') &&
  !pathToClaudeCodeExecutable.endsWith('.tsx') &&
  !pathToClaudeCodeExecutable.endsWith('.ts') &&
  !pathToClaudeCodeExecutable.endsWith('.jsx');

const command = isNativeBinary ? pathToClaudeCodeExecutable : executable;
// executable 默认: isBun ? "bun" : "node"

this.process = spawn(command, args, {
  cwd: cwd,
  stdio: ['pipe', 'pipe', stderrMode],
  signal: abortSignal,
  env: env,
  windowsHide: true,
});

executable: isStaticBinary() ? undefined : process.execPath,

┌─────────────────────────────────────────────────────┐
│          AionUi                                     │
│                                                     │
│  通过 npx 以子进程方式 spawn 适配器                 │
│  stdin/stdout NDJSON (JSON-RPC) 通信                │
└────────────────────┬────────────────────────────────┘
                     │ stdin/stdout (NDJSON, JSON-RPC)
                     ▼
┌─────────────────────────────────────────────────────┐
│      claude-agent-acp (ACP Agent Adapter)           │
│                                                     │
│  ClaudeAcpAgent: 翻译 ACP ↔ SDK 消息                │
│  AgentSideConnection: ACP JSON-RPC 分发             │
│  SettingsManager: 读取 .claude/settings.json        │
│  Permission 代理: canUseTool → requestPermission    │
└────────────────────┬────────────────────────────────┘
                     │ SDK query() API
                     ▼
┌─────────────────────────────────────────────────────┐
│       @anthropic-ai/claude-agent-sdk                │
│                                                     │
│  query(): 创建 ProcessTransport                     │
│  ProcessTransport: spawn cli.js 为子进程            │
│  默认路径:                                          │
│    path.join(dirname(import.meta.url), "cli.js")    │
└────────────────────┬────────────────────────────────┘
                     │ child_process.spawn()
                     │ stdin/stdout (streaming NDJSON)
                     ▼
┌─────────────────────────────────────────────────────┐
│    cli.js (内嵌 Claude Code ~13MB)                  │
│                                                     │
│  完整的 Claude Code 运行时                          │
│  --output-format stream-json                        │
│  --input-format stream-json                         │
│  --permission-prompt-tool stdio                     │
│  通过 HTTPS 与 Anthropic API 通信                   │
└─────────────────────────────────────────────────────┘

AionUi (Electron main)
  → npx claude-agent-acp (Node.js)
    → node cli.js (Claude Code runtime)
      → HTTPS → api.anthropic.com