claude code

Gemini CLI 与 Claude Code SDK 适配文档

目录

1. [SDK 工作原理](#SDK 工作原理)
2. 协议规范
3. [Gemini CLI 当前实现](#Gemini CLI 当前实现)
4. 能力差距分析
5. 需要补充的功能
6. 使用示例

---

1. SDK 工作原理

1.1 架构概述

Claude Code SDK 通过子进程通信与 CLI 交互：

┌─────────────────┐         stdin           ┌──────────────────┐
│                 │  ──────────────────────>  │                  │
│   Python SDK    │                           │   Gemini CLI     │
│                 │  <──────────────────────  │                  │
└─────────────────┘         stdout          └──────────────────┘

1.2 启动流程

文件位置 : subprocess_cli.py:382-460

1. 构建命令行参数

   gemini --output-format stream-json \
          --input-format stream-json \
          --debug

2. 设置环境变量

   env = {
       "CLAUDE_CODE_ENTRYPOINT": "sdk-py",
       "CLAUDE_AGENT_SDK_VERSION": __version__,
       **os.environ,
       **user_env
   }

3. 启动子进程

   • stdin: TextSendStream (发送消息到 CLI)
   • stdout: TextReceiveStream (接收消息从 CLI)
   • stderr: TextReceiveStream (调试输出)

1.3 通信模式

文件位置 : subprocess_cli.py:571-644

消息格式

• 每行一个 JSON 对象
• 自动缓冲和拼接长 JSON
• 支持 1MB 默认缓冲区（可配置）

消息类型

# 从 SDK 到 CLI (通过 stdin)
ControlRequest -> stdin

# 从 CLI 到 SDK (通过 stdout)
UserMessage | AssistantMessage | SystemMessage |
ResultMessage | StreamEvent | ControlResponse -> stdout

---

2. 协议规范

2.1 消息协议

2.1.1 用户消息

{
  "type": "user",
  "uuid": "uuid",
  "session_id": "session-id",
  "parent_tool_use_id": null,
  "message": {
    "role": "user",
    "content": [
      {
        "type": "text",
        "text": "用户消息内容"
      }
    ]
  }
}

2.1.2 助手消息

{
  "type": "assistant",
  "uuid": "uuid",
  "session_id": "session-id",
  "parent_tool_use_id": null,
  "message": {
    "id": "msg-id",
    "type": "message",
    "role": "assistant",
    "model": "gemini-2.0-flash-exp",
    "content": [
      {
        "type": "text",
        "text": "助手回复内容"
      }
    ],
    "stop_reason": null,
    "usage": {
      "input_tokens": 100,
      "output_tokens": 50
    }
  }
}

2.1.3 工具使用块

{
  "type": "tool_use",
  "id": "tool-use-id",
  "name": "Bash",
  "input": {
    "command": "ls -la"
  }
}

2.1.4 工具结果块

{
  "type": "tool_result",
  "tool_use_id": "tool-use-id",
  "is_error": false,
  "content": "命令执行结果"
}

2.1.5 结果消息

{
  "type": "result",
  "subtype": "success",
  "uuid": "uuid",
  "session_id": "session-id",
  "is_error": false,
  "duration_ms": 5000,
  "duration_api_ms": 3000,
  "num_turns": 3,
  "result": "最终结果",
  "usage": {
    "input_tokens": 1000,
    "output_tokens": 500
  },
  "permission_denials": []
}

2.2 控制协议

文件位置:

• SDK: types.py:684-754
• Gemini CLI: sdk/controlProtocol.ts, sdk/types.ts

2.2.1 初始化请求 (SDK -> CLI)

{
  "type": "control_request",
  "request_id": "req-1",
  "request": {
    "subtype": "initialize",
    "hooks": {
      "PreToolUse": [
        {
          "matcher": "Bash|Write",
          "hookCallbackIds": ["callback-1"],
          "timeout": 60
        }
      ]
    },
    "sdkMcpServers": {
      "my-server": {
        "type": "sdk",
        "name": "my-server"
      }
    },
    "mcpServers": {
      "external-server": {
        "command": "node",
        "args": ["server.js"]
      }
    },
    "agents": [...]
  }
}

响应 (CLI -> SDK):

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "req-1",
    "response": {
      "commands": ["Bash", "Read", "Write", ...],
      "output_style": "stream-json",
      "capabilities": {
        "tools": [...],
        "mcpServers": true,
        "hooks": true,
        "permissionControl": true
      },
      "model": "gemini-2.0-flash-exp",
      "permissionMode": "default"
    }
  }
}

2.2.2 工具权限请求 (SDK -> CLI)

{
  "type": "control_request",
  "request_id": "req-2",
  "request": {
    "subtype": "can_use_tool",
    "tool_name": "Bash",
    "tool_use_id": "tool-1",
    "input": {
      "command": "rm -rf /"
    },
    "permission_suggestions": [
      {
        "type": "deny",
        "label": "危险操作",
        "description": "删除根目录是不安全的"
      }
    ],
    "blocked_path": "/"
  }
}

响应:

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "req-2",
    "response": {
      "behavior": "deny",
      "message": "拒绝执行危险操作",
      "interrupt": false,
      "updatedInput": null
    }
  }
}

2.2.3 其他控制请求

设置权限模式:

{
  "type": "control_request",
  "request_id": "req-3",
  "request": {
    "subtype": "set_permission_mode",
    "mode": "auto-edit"
  }
}

设置模型:

{
  "type": "control_request",
  "request_id": "req-4",
  "request": {
    "subtype": "set_model",
    "model": "gemini-2.5-pro-exp"
  }
}

中断执行:

{
  "type": "control_request",
  "request_id": "req-5",
  "request": {
    "subtype": "interrupt"
  }
}

2.2.4 Hook 回调请求 (SDK -> CLI)

{
  "type": "control_request",
  "request_id": "req-6",
  "request": {
    "subtype": "hook_callback",
    "callback_id": "callback-1",
    "input": {
      "hook_event_name": "PreToolUse",
      "tool_name": "Bash",
      "tool_input": {...},
      "session_id": "...",
      "transcript_path": "...",
      "cwd": "...",
      "permission_mode": "default"
    },
    "tool_use_id": "tool-1"
  }
}

响应:

{
  "type": "control_response",
  "response": {
    "subtype": "success",
    "request_id": "req-6",
    "response": {
      "continue": true,
      "suppressOutput": false,
      "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "allow",
        "updatedInput": {...}
      }
    }
  }
}

2.3 流事件协议

文件位置 : nonInteractive/types.ts:199-249

当 include_partial_messages: true 时，CLI 会发送部分更新：

{
  "type": "stream_event",
  "uuid": "uuid",
  "session_id": "session-id",
  "parent_tool_use_id": null,
  "event": {
    "type": "message_start",
    "message": {
      "id": "msg-id",
      "role": "assistant",
      "model": "gemini-2.0-flash-exp"
    }
  }
}

事件类型:

• message_start: 消息开始
• content_block_start: 内容块开始
• content_block_delta: 内容增量 (text_delta, thinking_delta, input_json_delta)
• content_block_stop: 内容块结束
• message_stop: 消息结束

---

3. Gemini CLI 当前实现

3.1 已支持的核心功能

3.1.1 非交互模式 (Non-Interactive Mode)

文件位置 : nonInteractiveCli.ts:57-457

✅ 已实现:

• 流式 JSON 输出格式
• 多轮对话循环
• 工具调用和结果返回
• 会话管理 (resume)
• Ctrl+C 取消处理
• 最大轮次限制

关键代码:

// Line 207-214: 初始化事件
if (streamFormatter) {
  streamFormatter.emitEvent({
    type: JsonStreamEventType.INIT,
    timestamp: new Date().toISOString(),
    session_id: config.getSessionId(),
    model: config.getModel(),
  });
}

3.1.2 流式 JSON I/O

文件位置:

• 输入: nonInteractive/io/StreamJsonInputReader.ts
• 输出: nonInteractive/io/StreamJsonOutputAdapter.ts

✅ 已实现:

• 逐行 JSON 解析
• 类型验证
• 消息构建和发送
• 内容块管理

关键代码:

// StreamJsonOutputAdapter.ts:523-536
protected emitMessageImpl(message: CLIMessage): void {
  if (message.type === 'assistant') {
    this.updateLastAssistantMessage(message as CLIAssistantMessage);
  }
  process.stdout.write(`${JSON.stringify(message)}\n`);
}

3.1.3 控制协议处理

文件位置 : sdk/controlProtocol.ts:67-434

✅ 已实现:

1. 初始化 (Line 190-221)

   • Hooks 配置接收（未实现实际执行）
   • MCP 服务器配置接收（未实现实际执行）
   • 返回能力信息

2. 工具权限检查 (Line 226-282)

   • 支持回调函数
   • 权限建议传递
   • 超时处理 (60秒)
   • 输入修改支持

3. 中断处理 (Line 287-296)

   • 设置中断标志
   • 触发中断事件

4. 权限模式设置 (Line 301-312)

   • 更新内部状态
   • 未实际应用到配置

5. 模型设置 (Line 317-330)

   • 更新模型名称
   • 未实际切换客户端

❌ 未实现/占位实现:

// Line 335-343: MCP 消息处理
private async handleMcpMessage(): Promise<unknown> {
  return {
    error: 'MCP servers are not supported in Gemini CLI',
    mcp_response: { jsonrpc: '2.0', result: {}, id: 0 },
  };
}

3.2 内容块支持

文件位置 : nonInteractive/io/StreamJsonOutputAdapter.ts

✅ 已支持:

• TextBlock - 文本内容
• ThinkingBlock - 思考内容 (Gemini Thought 事件)
• ToolUseBlock - 工具调用
• ToolResultBlock - 工具结果

代码实现:

// Line 229-258: 文本块
protected appendText(state: MessageState, fragment: string): void {
  this.ensureBlockTypeConsistency(state, 'text');
  // ... 创建或追加文本块
}

// Line 263-301: 思考块
protected appendThinking(state: MessageState, subject?: string, description?: string): void {
  this.ensureBlockTypeConsistency(state, 'thinking');
  // ... 创建或追加思考块
}

// Line 306-337: 工具使用块
protected appendToolUse(state: MessageState, request: ToolCallRequestInfo): void {
  this.ensureBlockTypeConsistency(state, 'tool_use');
  // ... 创建工具使用块
}

3.3 系统消息支持

文件位置 : StreamJsonOutputAdapter.ts:608-620

✅ 已实现:

emitSystemMessage(subtype: string, data?: unknown): void {
  const systemMessage = {
    type: 'system',
    subtype,
    uuid: randomUUID(),
    session_id: this.getSessionId(),
    parent_tool_use_id: null,
    data,
  } as const;
  this.emitMessageImpl(systemMessage);
}

---

4. 能力差距分析

4.1 功能对比矩阵

功能	SDK 要求	Gemini CLI 状态	完成度
消息协议
Stream-JSON I/O	✅ 必需	✅ 已实现	100%
用户消息	✅ 必需	✅ 已实现	100%
助手消息	✅ 必需	✅ 已实现	100%
系统消息	✅ 必需	✅ 已实现	100%
结果消息	✅ 必需	✅ 已实现	100%
部分消息流	⚡ 可选	⚠️ 部分实现	50%
内容块
TextBlock	✅ 必需	✅ 已实现	100%
ThinkingBlock	⚡ 可选	✅ 已实现	100%
ToolUseBlock	✅ 必需	✅ 已实现	100%
ToolResultBlock	✅ 必需	✅ 已实现	100%
控制协议
Initialize	✅ 必需	⚠️ 接收但不执行	40%
CanUseTool	✅ 必需	✅ 已实现	100%
Interrupt	✅ 必需	✅ 已实现	100%
SetPermissionMode	✅ 必需	⚠️ 仅更新状态	30%
SetModel	✅ 必需	⚠️ 仅更新状态	30%
HookCallback	✅ 必需	❌ 未实现	0%
McpMessage	⚡ 可选	❌ 占位错误	0%
McpServerStatus	⚡ 可选	⚠️ 空实现	20%
SupportedCommands	✅ 必需	✅ 已实现	100%
高级功能
MCP 服务器	⚡ 可选	❌ 未实现	0%
Hooks 系统	⚡ 可选	❌ 未实现	0%
Agents	⚡ 可选	❌ 未实现	0%
File Checkpointing	⚡ 可选	❌ 未实现	0%
Rewind Files	⚡ 可选	❌ 未实现	0%
Permission Updates	⚡ 可选	❌ 未实现	0%
Structured Output	⚡ 可选	❌ 未实现	0%

图例:

• ✅ 必需: SDK 要求的核心功能
• ⚡ 可选: 增强功能
• ✅ 已实现: 完全支持
• ⚠️ 部分实现: 部分支持
• ❌ 未实现: 不支持

4.2 详细差距分析

4.2.1 控制协议实现不足

Initialize 请求:

• ✅ 接收 hooks、mcpServers、agents 配置
• ❌ 不执行 hook 注册
• ❌ 不启动 MCP 服务器
• ❌ 不创建 agent 定义
• ✅ 返回基本能力信息

Hook Callback 请求:

• ❌ 完全未实现
• SDK 期望在初始化时注册 hooks
• CLI 需要在工具调用前后执行 hook
• 需要实现完整的钩子系统

MCP 服务器:

• ❌ handleMcpMessage() 返回硬编码错误
• ❌ 没有服务器生命周期管理
• ❌ 没有工具发现和调用机制

4.2.2 高级功能缺失

文件检查点 (File Checkpointing):

• SDK 需要: enable_file_checkpointing: true
• CLI 需要: 在每个用户消息时保存文件快照
• SDK 方法: rewind_files(user_message_id)
• 状态: ❌ 完全未实现

权限更新 (Permission Updates):

• SDK 需要动态更新权限规则
• CLI 需要支持运行时规则修改
• 消息类型: addRules, replaceRules, removeRules, setMode
• 状态: ❌ 未实现

结构化输出 (Structured Output):

• SDK 支持: output_format: {"type": "json_schema", "schema": {...}}
• CLI 需要: 将 schema 传递给 Gemini API
• 状态: ❌ 未实现

---

5. 需要补充的功能

5.1 优先级 P0 (核心功能)

5.1.1 改进 Initialize 实现

当前状态 : controlProtocol.ts:190-221

需要改进:

1. 验证并存储 hooks 配置
2. 为后续 hook 回调做准备
3. 至少返回正确的 capabilities.hooks 状态

建议代码:

private async handleInitialize(payload: InitializeRequest): Promise<unknown> {
  // 存储配置
  this.hooksConfig = payload.hooks || {};
  this.sdkMcpServers = payload.sdkMcpServers || {};
  this.externalMcpServers = payload.mcpServers || {};
  this.agents = payload.agents || [];

  // 返回真实的能力状态
  this.initializationResult = {
    commands: this.supportedTools,
    output_style: 'stream-json',
    capabilities: {
      tools: this.supportedTools,
      mcpServers: false, // 暂不支持
      hooks: false, // 暂不支持
      permissionControl: !!this.canUseToolCallback,
    },
    model: this.currentModel,
    permissionMode: this.currentPermissionMode,
  };

  return this.initializationResult;
}

5.1.2 实现权限模式实际应用

当前状态 : controlProtocol.ts:301-312

需要改进:

• 将权限模式实际应用到 Config
• 修改现有行为以响应模式变化

建议代码:

private async handleSetPermissionMode(payload: SetPermissionModeRequest): Promise<unknown> {
  const { mode } = payload;

  // 实际更新配置（需要注入 Config 实例）
  if (this.config && this.config.setPermissionMode) {
    this.config.setPermissionMode(mode);
  }

  this.currentPermissionMode = mode;
  return null;
}

5.1.3 实现模型切换

当前状态 : controlProtocol.ts:317-330

需要改进:

• 重新创建 Gemini Client
• 验证模型名称有效性

建议代码:

private async handleSetModel(payload: SetModelRequest): Promise<unknown> {
  const { model } = payload;

  if (model) {
    // 验证模型名称
    const validModels = ['gemini-2.0-flash-exp', 'gemini-2.5-pro-exp', /* ... */];
    if (!validModels.includes(model)) {
      throw new Error(`Invalid model: ${model}`);
    }

    this.currentModel = model;

    // 重新创建客户端（需要注入 Config）
    if (this.config && this.config.setModel) {
      await this.config.setModel(model);
    }
  }

  return { model: this.currentModel };
}

5.2 优先级 P1 (增强功能)

5.2.1 实现流事件支持

文件位置 : StreamJsonOutputAdapter.ts:869-890

当前状态 : 部分实现，仅在 includePartialMessages 时发送

需要补充:

// 在 processEvent 中为每个事件类型发送流事件
processEvent(event: ServerGeminiStreamEvent): void {
  switch (event.type) {
    case GeminiEventType.Content:
      this.emitStreamEventIfEnabled({
        type: 'content_block_delta',
        index: 0,
        delta: { type: 'text_delta', text: event.value }
      });
      this.appendText(state, event.value, null);
      break;
    // ... 其他事件类型
  }
}

5.2.2 改进控制响应发送

文件位置 : StreamJsonOutputAdapter.ts:623-644

当前问题:

• 使用 fs.writeSync 可能失败
• 调试输出到 stderr 污染流

建议改进:

writeControlResponse(response: SDKControlResponse): void {
  const jsonStr = `${JSON.stringify(response)}\n`;

  // 使用普通写入，避免 writeSync 的问题
  if (process.stdout.writable) {
    process.stdout.write(jsonStr);
  } else {
    throw new Error('stdout is not writable');
  }
}

5.3 优先级 P2 (可选功能)

5.3.1 MCP 服务器支持

架构设计:

SDK Process                    CLI Process
    |                              |
    |--- initialize -------------> |  1. 接收外部 MCP 服务器配置
    |                              |  2. 启动 stdio/SSE/HTTP 服务器
    |                              |  3. 发现工具
    |<--- capabilities ------------|  4. 返回可用工具列表
    |                              |
    |--- mcp_message ------------> |  5. 转发 JSON-RPC 请求
    |<--- mcp_response ----------- |  6. 返回 JSON-RPC 响应

实现位置 : sdk/mcpHandler.ts (新文件)

5.3.2 Hooks 系统支持

架构设计:

SDK                          CLI
  |                            |
  |-- register hooks -------> |  1. 存储钩子配置
  |                            |
  |-- tool: Bash -----------> |  2. 检测 PreToolUse hooks
  |                            |  3. 发送 hook_callback 请求
  |<-- hook_callback -------- |  4. 等待 SDK 响应
  |                            |  5. 根据响应决定行为
  |-- permission: allow ----> |  6. 继续或阻止工具执行
  |                            |
  |<-- tool result ----------- |  7. 检测 PostToolUse hooks
  |                            |  8. 发送 hook_callback
  |-- hook_callback --------> |  9. SDK 可以添加上下文

实现位置 : sdk/hookManager.ts (新文件)

关键接口:

interface HookManager {
  // 注册钩子
  registerHooks(hooks: Record<string, HookMatcher[]>): void;

  // 检查是否有匹配的钩子
  hasHooks(eventType: string, toolName?: string): boolean;

  // 执行钩子（返回 SDK 响应）
  executeHook(
    eventType: HookEvent,
    input: HookInput,
    toolUseId?: string
  ): Promise<HookJSONOutput>;

  // 清理
  cleanup(): void;
}

5.3.3 文件检查点

架构设计:

1. 在每个用户消息开始时，扫描工作目录
2. 计算文件哈希值，保存到快照
3. SDK 可以调用 rewind_files(user_message_id) 恢复

实现位置 : sdk/fileCheckpointManager.ts (新文件)

数据结构:

interface FileSnapshot {
  userMessageId: string;
  timestamp: number;
  files: Map<string, string>; // path -> hash
}

class FileCheckpointManager {
  private snapshots: FileSnapshot[] = [];

  createSnapshot(messageId: string): void;
  rewindTo(messageId: string): void;
  cleanup(): void;
}

---

6. 使用示例

6.1 基础使用（当前已支持）

from claude_agent_sdk import ClaudeAgent

async def main():
    agent = ClaudeAgent()

    # 简单对话
    async for message in agent.run("列出当前目录的文件"):
        if message.type == "assistant":
            for block in message.content:
                if block.type == "text":
                    print(block.text)
                elif block.type == "tool_use":
                    print(f"调用工具: {block.name}")

6.2 带权限控制（当前已支持）

from claude_agent_sdk import ClaudeAgent, ClaudeAgentOptions
from claude_agent_sdk.types import CanUseTool, PermissionResult

async def check_permission(tool_name: str, tool_input: dict, context):
    """自定义权限检查"""
    if tool_name == "Bash":
        command = tool_input.get("command", "")
        if "rm -rf" in command:
            return PermissionResult(
                behavior="deny",
                message="不允许删除操作"
            )
    return PermissionResult(behavior="allow")

async def main():
    options = ClaudeAgentOptions(
        can_use_tool=check_permission
    )

    agent = ClaudeAgent(options=options)
    async for message in agent.run("删除所有文件"):
        # 会触发权限检查
        pass

6.3 带流事件（部分支持）

from claude_agent_sdk import ClaudeAgent, ClaudeAgentOptions

options = ClaudeAgentOptions(
    include_partial_messages=True  # 启用流事件
)

async def main():
    agent = ClaudeAgent(options=options)

    async for message in agent.run("写一首诗"):
        if message.type == "stream_event":
            print(f"流事件: {message.event}")
        elif message.type == "assistant":
            print(f"完整消息: {message.content}")

6.4 带模型切换（需要改进）

from claude_agent_sdk import ClaudeAgent, ClaudeAgentOptions

async def main():
    options = ClaudeAgentOptions(
        model="gemini-2.0-flash-exp",
        # 5.1.3: 需要实际应用这个配置
    )

    agent = ClaudeAgent(options=options)

    # SDK 可以在运行时切换模型
    await agent.set_model("gemini-2.5-pro-exp")

    async for message in agent.run("复杂的推理任务"):
        pass

6.5 带 Hooks（未实现，需要 P2 功能）

from claude_agent_sdk import ClaudeAgent, ClaudeAgentOptions, HookMatcher
from claude_agent_sdk.types import HookCallback, HookInput, HookContext, HookJSONOutput

async def pre_tool_use_hook(input: HookInput, tool_use_id: str, context: HookContext):
    """工具调用前的钩子"""
    tool_name = input["tool_name"]

    if tool_name == "Bash":
        command = input["tool_input"]["command"]

        # 检查命令是否安全
        if "docker" in command:
            return {
                "continue": True,
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "allow",
                    "additionalContext": "Docker 命令已验证"
                }
            }

    return {"continue": True}

options = ClaudeAgentOptions(
    hooks={
        "PreToolUse": [
            HookMatcher(
                matcher="Bash|Write",
                hooks=[pre_tool_use_hook],
                timeout=60
            )
        ]
    }
)

agent = ClaudeAgent(options=options)
async for message in agent.run("执行一些命令"):
    # 会触发 hook
    pass

---

附录 A: 相关文件路径

SDK 文件

Python SDK 安装目录:
C:\Users\LENOVO\AppData\Local\Programs\Python\Python313\Lib\site-packages\claude_agent_sdk\

关键文件:
├── _internal/transport/subprocess_cli.py   # 子进程通信实现
├── _internal/transport/__init__.py
├── types.py                                # 类型定义
├── _errors.py                              # 错误定义
└── _version.py                             # 版本信息

Gemini CLI 文件

工作目录:
C:\Users\LENOVO\Desktop\cli\quan\gemini-cli\

关键文件:
├── packages/cli/src/
│   ├── nonInteractiveCli.ts               # 非交互模式主逻辑
│   ├── nonInteractiveCliCommands.ts       # 非交互命令
│   ├── sdk/
│   │   ├── controlProtocol.ts             # 控制协议实现
│   │   └── types.ts                       # SDK 类型定义
│   ├── nonInteractive/
│   │   ├── types.ts                       # 非交互类型
│   │   ├── io/
│   │   │   ├── StreamJsonInputReader.ts   # JSON 输入
│   │   │   └── StreamJsonOutputAdapter.ts # JSON 输出
│   │   └── session.ts                     # 会话管理
│   └── ...

---

附录 B: 调试建议

B.1 启用调试模式

SDK 端:

import logging
logging.basicConfig(level=logging.DEBUG)

options = ClaudeAgentOptions(
    extra_args={"debug-to-stderr": None}
)

CLI 端:

gemini --debug --output-format stream-json --input-format stream-json

B.2 查看消息流

使用 jq 美化输出:

gemini --output-format stream-json "你好" | jq .

只看控制消息:

gemini --output-format stream-json "你好" | jq 'select(.type == "control_request" or .type == "control_response")'

B.3 测试控制协议

手动发送控制请求:

echo '{"type":"control_request","request_id":"1","request":{"subtype":"initialize"}}' | \
gemini --input-format stream-json --output-format stream-json

---

附录 C: 常见问题

Q1: 为什么控制请求没有响应？

A: 检查以下几点：

1. 确认 --input-format stream-json 参数存在
2. 确认 JSON 格式正确（使用 jq . 验证）
3. 检查 stderr 是否有错误信息
4. 确认 CLAUDE_CODE_ENTRYPOINT 环境变量设置正确

Q2: 流事件不发送？

A : 需要设置 include_partial_messages: true：

options = ClaudeAgentOptions(
    include_partial_messages=True
)

Q3: MCP 服务器不工作？

A: 当前 Gemini CLI 不支持 MCP，这是预期行为。

Q4: Hooks 不触发？

A: 当前 Gemini CLI 不支持 Hooks 系统，这是 P2 功能。

---

更新日志

• 2025-01-02: 初始版本，分析 SDK 和 Gemini CLI 当前实现
• 待补充: 后续实现进度跟踪

---

文档版本 : 1.0.0
最后更新 : 2025-01-02
作者: Claude Code Analysis