本章总览

src/cli/ 是 Claude Code 命令行层的「协议与运维内核」（20 文件 · 约 12380 行）。它不负责 Ink REPL 的 React 树渲染——那在 entrypoints/cli.tsx（P5 entrypoints 专题）——而是承载：SDK/headless 的 NDJSON stdio 协议（StructuredIO）、远程 Session Ingress 传输（WebSocket / Hybrid / SSE + CCR v2）、子命令 handler（auth / mcp / plugin / agents / auto-mode）、以及 claude update 与上传原语。理解 cli 模块 = 理解「进程如何与外界对话」与「非 REPL 子命令如何懒加载」。

总览图

渲染图表中…

学完本章你应该能

• 区分 entrypoints/cli.tsx（入口编排）与 src/cli/（协议实现）的边界
• 建立 StructuredIO → print.ts runHeadless → query 循环的数据流心智模型
• 知道 RemoteIO + transports 在 --sdk-url / bridge / CCR v2 场景下的选型
• 会从子章节进入 handlers 与 update 路径

建议学习步骤

1. 阅读下方边界说明，确认 main CLI 入口在 entrypoints
2. 浏览 SourceTree module=cli，点击文件跳转子章节
3. 建议顺序：structured-io → transports → handlers → update-util
4. 对照 print.ts runHeadless 验证 StructuredIO 如何注入 canUseTool

模块在架构中的位置

cli 是 src/ 下的一级目录，共 20 个文件、12,380 行。一句话概括：CLI 启动、参数解析、OAuth 认证、GrowthBook 特性开关初始化，决定走 REPL 交互还是 Headless/SDK 模式。

概览

指标	数值
行数	12,380
文件	20

与 entrypoints 的边界

主 CLI 入口在 entrypoints/cli.tsx（P5 entrypoints 专题覆盖）：Commander 子命令注册、preAction hook、REPL vs headless 分支、动态 import handlers。

src/cli/ 提供可被 entrypoints import 的实现库：

职责	路径	消费者
NDJSON SDK 协议	structuredIO.ts, remoteIO.ts, print.ts	runHeadless, SDK host, bridge worker
网络传输	transports/*	RemoteIO, CCR v2
子命令逻辑	handlers/*	cli.tsx 懒加载
自更新	update.ts	claude update
小工具	exit.ts, ndjsonSafeStringify.ts	handlers + StructuredIO

不要在 cli 模块里找 Ink 组件或 REPL 布局；那些在 screens/ 与 components/。cli 的 print.ts 虽巨大（约 5500 行），核心是 headless query 编排，不是 TUI。

子章节导航

子章节	状态	主题	核心路径
Structured IO	已完成	NDJSON 协议、权限 control_request	structuredIO.ts, remoteIO.ts, print.ts, ndjsonSafeStringify.ts, exit.ts
Transports	已完成	WS / Hybrid / SSE / CCR	transports/*
Handlers	已完成	auth、mcp、plugin、agents、auto-mode	handlers/*
Update & Upload	已完成	自更新与串行上传	update.ts, WorkerStateUploader, SerialBatchEventUploader

目录簇划分（20 文件）

src/cli/
├── structuredIO.ts      # SDK stdin/stdout 协议核心
├── remoteIO.ts          # StructuredIO + Transport
├── print.ts             # runHeadless、canUseTool 工厂、MCP reconcile
├── ndjsonSafeStringify.ts
├── exit.ts              # cliError / cliOk
├── update.ts            # claude update
├── transports/
│   ├── Transport.ts     # 接口
│   ├── transportUtils.ts
│   ├── WebSocketTransport.ts
│   ├── HybridTransport.ts
│   ├── SSETransport.ts
│   ├── ccrClient.ts     # CCR v2 客户端
│   ├── WorkerStateUploader.ts
│   └── SerialBatchEventUploader.ts
└── handlers/
    ├── auth.ts
    ├── mcp.tsx
    ├── plugins.ts
    ├── agents.ts
    ├── autoMode.ts
    └── util.tsx

数据流简图（headless / SDK）：

entrypoints/cli.tsx
  → print.runHeadless(...)
       → StructuredIO | RemoteIO(sdkUrl)
            → read(): NDJSON stdin → SDKMessage
            → outbound Stream → write(): NDJSON stdout
            → createCanUseTool() → control_request can_use_tool
       → query 循环 + tools

Bridge / Remote Control 场景下 RemoteIO 替换纯 stdio，getTransportForUrl 按 env 选 WS、Hybrid 或 SSE+CCR。

本章小结与延伸

cli 模块四篇子章节均已完稿。入口边界见 entrypoints；本模块聚焦协议、传输与子命令实现。 继续学习：

• Structured IO