Claude Code CLI — 架构设计与使用指南

By - niubadomi
Posted on 4 7 月, 20265 7 月, 2026
Posted in Linux

Claude Code CLI — 架构设计与使用指南

1. 概述

Claude Code 是 Anthropic 官方推出的 AI 编程 CLI 工具，基于 React/Ink 终端渲染框架构建。它是一个庞大的终端应用，包含：

45+ 内置工具（文件操作、Shell 执行、Web 搜索、子智能体管理等）
多智能体编排系统（Coordinator 模式 + Agent Swarms）
MCP 协议集成（Model Context Protocol，支持外部工具服务器）
IDE 桥接层（与 VS Code、JetBrains 等编辑器集成）
内存/记忆系统（跨会话持久化知识）
技能系统（可复用的斜杠命令模板）
伴侣系统（Tamagotchi 风格的终端电子宠物）

技术指标

指标	数值
入口文件大小	~785KB (`main.tsx`)
总源文件数	500+
TypeScript 文件	380+
React 组件	389+
工具数量	45+
斜杠命令	88+
服务模块	21 个子目录

2. 总体架构

2.1 分层架构

┌─────────────────────────────────────────────────────┐
│                    入口层 (Entry)                     │
│  main.tsx  →  Commander.js CLI 解析  →  React/Ink   │
├─────────────────────────────────────────────────────┤
│                    界面层 (UI)                        │
│  screens/REPL.tsx  ←  components/  ←  ink/          │
│  主对话循环          389+ 组件       终端渲染基座     │
├─────────────────────────────────────────────────────┤
│                    编排层 (Orchestration)             │
│  coordinator/  ←  QueryEngine  ←  query.ts          │
│  多智能体协调       核心LLM查询      查询编排         │
├─────────────────────────────────────────────────────┤
│                    工具层 (Tools)                     │
│  45+ 工具: Bash, Read, Edit, Agent, Skill, MCP ...  │
├─────────────────────────────────────────────────────┤
│                    服务层 (Services)                  │
│  api/  compact/  mcp/  lsp/  analytics/  oauth/     │
│  autoDream/  plugins/  SessionMemory/  tips/         │
├─────────────────────────────────────────────────────┤
│                    基础层 (Utils)                     │
│  150+ 工具函数: git, config, permissions, env ...    │
└─────────────────────────────────────────────────────┘

2.2 数据流

用户输入
  ↓
PromptInput (React 组件，处理输入)
  ↓
REPL.tsx (会话状态机，路由到 QueryEngine 或 Command)
  ↓
QueryEngine.ts (构造 API 请求，管理上下文窗口)
  ↓
Claude API (Anthropic API / Bedrock / Vertex)
  ↓
响应解析 → 工具调用 / 文本输出
  ↓
工具执行 → 权限检查 → 结果返回 → UI 渲染
  ↓
消息列表更新 → 上下文压缩 (compact) → 下一轮

2.3 入口文件 `main.tsx` 结构

入口文件是 CLI 的启动枢纽，处理：

启动优化：预取 MDM 配置、Keychain 令牌（macOS），并行化启动任务
CLI 参数解析：基于 Commander.js 的命令行参数
认证流程：OAuth 登录、API Key 验证、Bedrock/Vertex 凭证
会话管理：--resume、--continue、会话恢复
模式切换：交互模式 (REPL)、非交互模式 (print/SDK)、Bare 模式
工具初始化：加载所有内置工具 + MCP 工具
GrowthBook 特性开关：运行时功能门控

3. 核心系统

3.1 查询引擎 (`QueryEngine.ts`)

QueryEngine 是 LLM 交互的核心入口：

职责：管理 API 请求的完整生命周期
关键方法：
构造系统提示词（含上下文、记忆、技能、工具定义）
规范化消息（工具结果截断、附件注入、签名块去除）
流式处理（增量式工具调用参数解析）
工具调用编排（processUserInput 方法串联 10+ 步骤）
上下文压缩触发（autoCompact / reactiveCompact）

3.2 查询流程 (`query.ts`)

query.ts 中的 processUserInput() 是请求处理的核心管道：

1. 预处理
   ├── 技能发现 (discoverSkillDirsForPaths)
   ├── 技能预取 (skillPrefetch)
   ├── CLAUDE.md 注入
   └── 记忆附件注入

2. 上下文准备
   ├── 用户上下文 (git status, 平台, 日期)
   ├── 系统上下文 (文件列表, 目录结构)
   ├── 记忆提示词 (MEMORY.md 内容)
   └── 动态提示词组装

3. 消息规范化
   ├── normalizeMessagesForAPI (strip UI-only messages)
   ├── 工具结果预算控制
   └── 缓存断点管理

4. API 调用
   ├── Claude API / Bedrock / Vertex
   ├── 重试逻辑 (withRetry)
   └── 速率限制处理

5. 后处理
   ├── 工具调用提取
   ├── 工具结果注入
   ├── 压缩检测 (compact/contextCollapse)
   └── 记录与持久化

3.3 工具框架 (`Tool.ts`)

工具框架定义了所有工具的公共接口。每个工具都是一个实现 Tool 接口的对象：

type Tool<Input, Output, Progress> = {
  name: string                    // 工具名称
  aliases?: string[]              // 别名（向后兼容）
  searchHint?: string             // 工具搜索关键词
  inputSchema: ZodType            // 输入参数 schema
  outputSchema?: ZodType          // 输出 schema

  // 核心方法
  call(input, context, canUseTool, msg, onProgress) → ToolResult
  description(input, options) → string
  prompt(options) → string

  // 权限与安全
  checkPermissions(input, context) → PermissionResult
  validateInput(input, context) → ValidationResult
  isReadOnly(input) → boolean
  isDestructive(input) → boolean
  isConcurrencySafe(input) → boolean

  // UI 渲染
  renderToolUseMessage(input, options) → ReactNode
  renderToolResultMessage(output, progress, options) → ReactNode
  renderToolUseRejectedMessage(...) → ReactNode
  renderToolUseErrorMessage(...) → ReactNode

  // 分类与优化
  isSearchOrReadCommand(input) → { isSearch, isRead, isList }
  toAutoClassifierInput(input) → unknown
  shouldDefer?: boolean           // 延迟加载（需 ToolSearch 发现）
  maxResultSizeChars: number      // 结果截断阈值
}

buildTool() 辅助函数：为通用方法提供安全默认值：

isEnabled → true
isConcurrencySafe → false（默认不安全）
isReadOnly → false（默认有写操作）
isDestructive → false
checkPermissions → 委托给通用权限系统

3.4 状态管理 (`state/AppState.tsx`)

使用 React Context + 外部 Store 模式：

AppStateProvider (React Context)
  └── AppStoreContext (外部 Store)
       ├── getState()     — 同步读取状态
       ├── setState(fn)   — 不可变更新
       └── subscribe(fn)  — 变更通知

useAppState(selector)     — 选择性子订阅（Object.is 比较）
useSetAppState()           — 仅获取 setter（不触发重渲染）
useAppStateStore()         — 获取原始 Store（非 React 代码使用）

3.5 上下文管理 (`context.ts`)

系统在每个请求前动态构建上下文：

用户上下文 (getUserContext)：
平台信息 (OS, shell, 工作目录)
日期/时间
Git 状态 (branch, status, recent commits)
项目结构概览
系统上下文 (getSystemContext)：
CLAUDE.md 内容（项目 + 父目录）
工具列表与权限模式
记忆系统状态
技能目录

4. 工具系统

4.1 工具注册机制 (`tools.ts`)

工具通过 getAllBaseTools() 函数注册，支持条件加载：

// 示例：条件加载模式
getAllBaseTools() {
  return [
    AgentTool,              // 始终加载
    BashTool,               // 始终加载
    ...(feature('WORKFLOW_SCRIPTS') ? [WorkflowTool] : []),    // 特性门控
    ...(USER_TYPE === 'ant' ? [TungstenTool, REPLTool] : []),  // 仅限内部
    ...(isWorktreeModeEnabled() ? [EnterWorktreeTool, ...] : []),
    ...cronTools,           // 运行时特性门控
    getPowerShellTool(),    // 平台检测
  ]
}

4.2 完整工具清单

文件操作工具

工具	描述	特性
Read	读取文件（文本、图片、PDF）	支持图像处理和 PDF 页面范围
Write	写入/覆盖文件	先读取后写入校验
Edit	精确字符串替换编辑	支持 replace_all 批量替换
Glob	文件名模式匹配搜索	`*/.ts` 递归模式
Grep	文件内容正则搜索	支持多文件并行搜索
NotebookEdit	Jupyter Notebook 编辑	cell 级别的增删改

Shell 执行工具

工具	描述	特性
Bash	执行 Shell 命令	沙箱模式、只读验证、权限规则
PowerShell	执行 PowerShell 命令	Windows 平台，CLM 模式支持

任务管理工具

工具	描述
TaskCreate	创建结构化任务
TaskGet	获取任务详情
TaskList	列出所有任务
TaskUpdate	更新任务状态
TaskOutput	获取后台任务输出
TaskStop	停止运行中的任务

智能体与团队工具

工具	描述
Agent	生成子智能体（支持内置类型：Explore, Plan, code-reviewer 等）
TeamCreate	创建团队成员
TeamDelete	删除团队成员
SendMessage	向队友发送消息

用户交互工具

工具	描述
AskUserQuestion	向用户提问（单选/多选）
SendUserMessage (Brief)	向用户发送消息/附件
EnterPlanMode	进入计划模式
ExitPlanMode	退出计划模式

搜索与网络工具

工具	描述
WebSearch	网络搜索
WebFetch	获取 URL 内容（80+ 预授权域名）
ToolSearch	搜索可用工具（关键词匹配）

工作流与调度工具

工具	描述
Workflow	执行工作流脚本（多智能体编排 DSL）
CronCreate	创建定时任务
CronDelete	删除定时任务
CronList	列出定时任务
ScheduleWakeup	调度动态间隔唤醒

工作区管理工具

工具	描述
EnterWorktree	创建/进入 Git 工作树
ExitWorktree	退出 Git 工作树

MCP 与 LSP 工具

工具	描述
MCPTool	通用 MCP 工具执行包装器
McpAuthTool	MCP OAuth 认证
ListMcpResourcesTool	列出 MCP 资源
ReadMcpResourceTool	读取 MCP 资源
LSP	语言服务器协议操作（跳转定义、引用、符号等）

其他工具

工具	描述
Skill	调用注册的技能
Config	读写配置设置
StructuredOutput	强制结构化的 JSON 输出
TodoWrite	写入待办事项列表
Sleep	等待指定时长（KAIROS 模式）
RemoteTrigger	管理远程智能体触发器

仅限内部 (Ant) 的工具

工具	描述
REPL	交互式 REPL 批量操作
Tungsten	tmux socket 隔离管理
SuggestBackgroundPR	PR 机会检测与建议
VerifyPlanExecution	计划执行结果验证

4.3 工具生命周期

1. 注册 (getAllBaseTools)
   ├── 特性门控检查
   └── 平台条件检查

2. 发现 (ToolSearch)
   └── 延迟加载工具通过 shouldDefer 暴露

3. 调用 (Tool.call)
   ├── validateInput() — 输入验证
   ├── checkPermissions() — 权限检查
   ├── 权限对话框（如需要）
   ├── 执行工具逻辑
   └── 返回 ToolResult

4. 渲染
   ├── renderToolUseMessage() — 输入预告
   ├── renderToolResultMessage() — 结果渲染
   └── extractSearchText() — 搜索索引

5. 服务层

5.1 MCP 集成 (`services/mcp/`)

MCP (Model Context Protocol) 是 Claude Code 与外部工具服务器通信的核心协议。

架构组件：

┌─────────────────────────────────┐
│       MCP 配置管理 (config.ts)    │
│  多源配置合并 (user/project/...)  │
│  企业策略过滤                      │
│  服务器签名去重                    │
└──────────┬──────────────────────┘
           │
┌──────────▼──────────────────────┐
│       连接管理 (client.ts)       │
│  多种传输协议支持                  │
│  工具/命令/资源获取               │
│  连接生命周期管理                  │
└──────────┬──────────────────────┘
           │
┌──────────▼──────────────────────┐
│    传输层 (多种传输类型)          │
│  stdio | sse | http | ws | sdk  │
└─────────────────────────────────┘

支持的传输类型：

传输类型	描述
`stdio`	本地子进程通信
`sse`	Server-Sent Events (远程)
`sse-ide`	IDE 扩展 SSE
`http`	可流式 HTTP
`ws` / `ws-ide`	WebSocket
`sdk`	进程内 SDK 桥接
`claudeai-proxy`	通过 claude.ai 代理

OAuth 认证流程 (services/oauth/)：

授权码流程 + PKCE
.well-known/oauth-authorization-server 自动发现
Token 刷新 + 安全密钥链存储
XAA (Cross-App Access) 企业 IdP 登录

SDK 桥接 (SdkControlTransport.ts)：

CLI 进程与 SDK 进程之间的传输桥接
JSONRPC 消息包装在控制请求中
用于 VS Code 扩展集成

5.2 API 客户端 (`services/api/`)

核心文件：

文件	功能
`claude.ts`	Claude API 集成（消息创建、流式处理）
`client.ts`	API 客户端基类
`bootstrap.ts`	启动引导数据
`filesApi.ts`	文件 API 操作
`errors.ts`	API 错误类型
`withRetry.ts`	重试逻辑（指数退避）
`usage.ts`	使用量跟踪
`logging.ts`	API 日志

多 Provider 支持：

Anthropic API (直接)
AWS Bedrock (@anthropic-ai/bedrock-sdk)
GCP Vertex AI (@anthropic-ai/vertex-sdk)
Azure Foundry (@anthropic-ai/foundry-sdk)

5.3 上下文压缩 (`services/compact/`)

防止上下文窗口溢出的关键系统：

压缩层次:
├── 微压缩 (microCompact)     — 单条消息内部压缩
├── 缓存微压缩 (cachedMicrocompact) — 利用 API 缓存断点
├── Snip 压缩 (snipCompact)   — 消息片段裁剪
├── 自动压缩 (autoCompact)    — 基于 token 阈值的主动压缩
├── 反应式压缩 (reactiveCompact) — 接近限制时的紧急压缩
├── 会话记忆压缩 (sessionMemoryCompact) — 记忆总结
└── 上下文折叠 (contextCollapse) — 长序列替换为摘要

压缩策略：

Pre-compact Hook → 用户可自定义压缩前行为
消息分组 → 按语义相关性分组
摘要替换 → 旧消息替换为结构化摘要
Post-compact Hook → 用户可自定义压缩后行为
压缩警告 → 通知用户上下文使用情况

5.4 记忆系统 (`memdir/` + `services/SessionMemory/` + `services/extractMemories/`)

记忆目录结构：

~/.claude/projects/<sanitized-project-root>/memory/
├── MEMORY.md              # 索引文件（200行/25KB 上限）
├── user_role.md           # 用户角色记忆
├── project_context.md     # 项目上下文记忆
└── team/                  # 团队记忆（可选）

记忆类型分类：

类型	用途	示例
`user`	用户身份、角色、偏好	“我是全栈开发者，偏好函数式编程”
`feedback`	用户反馈和纠正	“不要使用 class 组件，用 hooks”
`project`	项目约束和进展	“目标：2026Q3 前完成重构”
`reference`	外部资源链接	“API 文档: https://…”

记忆生命周期：

存储：模型写入 .md 文件 + 更新 MEMORY.md 指针
检索：Sonnet 侧查询选择最相关的 5 条记忆
提取：后台智能体自动发现未记录的重要信息
老化：显示时间戳和新鲜度警告
Dream：夜间批量整合日志为结构化记忆

5.5 分析与遥测 (`services/analytics/`)

GrowthBook：特性开关管理（运行时功能门控）
Datadog：性能和应用监控
OpenTelemetry：分布式追踪、指标、日志
第一方事件记录：产品使用分析

5.6 插件系统 (`services/plugins/` + `src/plugins/`)

插件来源：本地目录、Marketplace、管理配置
生命周期：安装 → 验证 → 信任确认 → 激活
CLI 命令：/plugin install|uninstall|list|browse|validate
MCP 集成：插件可提供 MCP 服务器

5.7 LSP 服务 (`services/lsp/`)

LSP 客户端：管理多个语言服务器实例
诊断注册表：聚合和去重诊断信息
被动反馈：利用 LSP 诊断提供代码质量反馈

6. 多智能体系统

Claude Code 实现了一主一辅两个多智能体编排系统。

6.1 Agent 工具 (`tools/AgentTool/`)

基础子智能体系统，是 Coordinator 和 Swarm 的基石。

内置智能体类型：

智能体	用途	模型
general-purpose	通用任务执行	继承主会话
Explore	只读文件探索和搜索	继承
Plan	软件架构设计	继承
claude-code-guide	Claude Code 使用帮助	继承
code-reviewer	代码审查	继承
statusline-setup	状态栏配置	继承
verification	验证代码变更	继承

子智能体生命周期：

forkSubagent (克隆文件状态缓存)
  → runAgent (创建子上下文)
    → AgentTool.call (工具调用)
      → 流式响应处理
    → resumeAgent (通过 SendMessage 继续)
  → agentMemory (跨轮次记忆保持)

6.2 Coordinator 模式 (`coordinator/coordinatorMode.ts`)

轻量级编排，将多智能体协调作为 LLM 提示工程：

角色定义：Coordinator 分配任务、综合结果、与用户交互
Worker 工具：Bash, Read, Edit (Simple 模式) 或完整工具集
结果格式：<task-notification> XML 消息
工作流程：Research → Synthesis → Implementation → Verification
决策指南：继续 vs 新生的条件判断表

6.3 Agent Swarms (`utils/swarm/`)

完整的多进程团队协作系统，支持身份、IPC 和多种执行后端。

架构层次：

┌────────────────────────────────┐
│  身份系统 (teammate.ts)         │
│  AsyncLocalStorage / 环境变量   │
│  三层优先级解析                  │
├────────────────────────────────┤
│  通信系统 (teammateMailbox.ts)  │
│  文件邮箱 + 结构化协议消息       │
├────────────────────────────────┤
│  权限同步 (permissionSync.ts)   │
│  文件系统 / 邮箱双向权限委托     │
├────────────────────────────────┤
│  执行后端 (backends/)           │
│  tmux | iTerm2 | in-process    │
├────────────────────────────────┤
│  生命周期 (teamHelpers.ts)      │
│  团队文件: config.json          │
└────────────────────────────────┘

邮箱消息类型：

idle_notification — Worker 空闲通知
permission_request/response — 权限委托
shutdown_request/approved/rejected — 生命周期管理
plan_approval_request/response — 计划审批
task_assignment — 任务分派
team_permission_update — 权限广播

执行后端选择：

tmux 内 → tmux 后端（独立窗格）
iTerm2 → iTerm2 后端（it2 CLI）
无终端多路复用器 → 进程内模式

6.4 Workflow 系统 (`tools/WorkflowTool/`)

声明式多智能体编排 DSL，通过工作流脚本实现：

export const meta = {
  name: 'review-changes',
  description: '审查代码变更',
  phases: [{ title: 'Review' }, { title: 'Verify' }],
}

phase('Review')
const findings = await parallel(
  DIMENSIONS.map(d => () => agent(d.prompt, { schema }))
)

phase('Verify')
const confirmed = await pipeline(
  findings.flat(),
  f => agent(`Verify: ${f.title}`, { schema })
)

核心原语：

agent(prompt, opts) — 生成子智能体
parallel(thunks) — 并行执行（屏障）
pipeline(items, ...stages) — 流水线执行（无屏障）
phase(title) — 进度分组
log(message) — 进度报告

7. UI 架构

7.1 React/Ink 终端 UI

Claude Code 使用 React 19 + Ink 在终端中渲染 UI：

React 组件
  ↓ (React Reconciler)
Ink 渲染器
  ↓
终端输出 (ANSI 转义序列)

7.2 屏幕组件

屏幕	用途
REPL.tsx	主对话屏幕 — 消息列表 + 输入 + 权限对话框
Doctor.tsx	诊断/健康检查屏幕（`/doctor` 命令）
ResumeConversation.tsx	会话恢复屏幕

7.3 组件层次

App (FPS + Stats + AppState 上下文)
├── Onboarding (首次运行)
├── Doctor (诊断)
├── ResumeConversation (会话恢复)
└── REPL (主对话屏幕)
    ├── Messages (虚拟化消息列表)
    │   └── MessageRow → Message (分发到 ~30 种消息类型)
    │       ├── AssistantTextMessage
    │       ├── AssistantThinkingMessage
    │       ├── AssistantToolUseMessage
    │       ├── UserPromptMessage
    │       ├── UserToolResultMessage
    │       └── ...
    ├── PromptInput (文本输入 + IDE 集成)
    │   ├── PromptInputFooter (模式/状态栏)
    │   ├── VoiceIndicator (语音输入)
    │   └── ...
    ├── PermissionDialog (权限审批)
    │   ├── BashPermissionRequest
    │   ├── FileWritePermissionRequest
    │   └── ...
    ├── Settings (设置标签页)
    ├── MCPSettings (MCP 配置)
    └── 各种模态对话框

7.4 设计系统 (`components/design-system/`)

ThemeProvider — 主题上下文 (dark/light/auto)
ThemedBox / ThemedText — 主题感知组件
Dialog — 模态对话框容器
Tabs — 标签页导航
FuzzyPicker — 模糊搜索选择器
ProgressBar — 进度条
StatusIcon — 状态图标
KeyboardShortcutHint — 快捷键提示

7.5 键盘系统 (`keybindings/`)

架构：

配置: ~/.claude/keybindings.json（支持热重载）
解析: 修饰键规范化 + 和弦（多键序列）解析
匹配: 上下文感知 + 用户覆盖（后定义优先）
React 集成: KeybindingProvider + useKeybinding() Hook

18 种上下文：Global, Chat, Autocomplete, Confirmation, Tabs, Transcript, HistorySearch, Task, ThemePicker, Scroll, Help, Attachments, Footer, MessageSelector, MessageActions, DiffDialog, ModelPicker, Select

和弦机制：多键序列（如 ctrl+b d）通过 ChordInterceptor 在 PromptInput 之前拦截

7.6 Vim 模式 (`vim/`)

有限状态机实现：

INSERT 模式 ←→ NORMAL 模式
                  ├── idle
                  ├── count (数字前缀)
                  ├── operator (d/c/y)
                  ├── find (f/F/t/T)
                  └── textObject (i/a + 括号/引号)

支持的操作符：d (delete), c (change), y (yank), > (indent), < (outdent), ~ (toggle case), J (join)

支持的文本对象：iw, aw, i(, a(, i”, a”, i{, a{, i[, a[, i<, a<

持久化状态：. (dot-repeat), ;/, (find-repeat), 寄存器

8. 技能与命令系统

8.1 技能系统 (`skills/`)

技能是存储在 SKILL.md 文件中的可复用提示词模板。

技能来源（优先级从高到低）：

管理/策略技能 (<managed-path>/.claude/skills/)
用户技能 (~/.claude/skills/)
项目技能 (.claude/skills/ — 从 CWD 向上遍历)
附加目录 (--add-dir)
内置技能（编译到二进制中）

SKILL.md 格式：

---
name: my-skill
description: 我的技能描述
when_to_use: 当需要执行特定任务时使用
allowed-tools: Bash, Read, Edit
argument-hint: <参数提示>
model: sonnet
---

技能的提示词内容...
支持 ${ARGUMENTS} 变量替换。

条件技能：带有 paths 字段的技能根据文件模式自动激活

内置技能：

updateConfig — 配置 Claude Code
keybindings — 自定义键盘快捷键
verify — 验证代码变更
code-review — 代码审查
simplify — 代码简化重构
init — 初始化 CLAUDE.md
loop — 循环执行定时任务
claude-api — Claude API 参考
security-review — 安全审查

8.2 斜杠命令 (`commands/` — 88+ 个)

分类如下：

会话管理：
/resume, /clear, /compact, /rewind, /rename, /session, /summary, /export, /share, /exit

Git 操作：
/commit, /branch, /diff, /pr_comments, /issue, /review

配置：
/config, /model, /effort, /fast, /output-style, /theme, /status, /permissions, /sandbox-toggle

工具与集成：
/mcp, /ide, /bridge, /chrome, /terminalSetup, /install-github-app, /install-slack-app

信息：
/help, /cost, /usage, /stats, /context, /doctor, /release-notes, /version

其他：
/agents, /tasks, /memory, /skills, /hooks, /plugin, /vim, /voice, /keybindings, /feedback

9. IDE 集成与桥接

9.1 Bridge 系统 (`bridge/`)

连接 Claude Code CLI 与 IDE 扩展的通信层：

bridgeMain.ts — 主桥接逻辑
bridgeApi.ts — API 定义
bridgeMessaging.ts — 进程间消息传递

9.2 服务器层 (`server/`)

directConnectManager.ts — 直接连接管理
createDirectConnectSession.ts — 会话创建

9.3 IDE 特性

自动连接：检测运行中的 IDE 并自动桥接
Diff 展示：在 IDE 中显示差异对比
文件打开：在 IDE 中快速打开文件
Inline 评论：PR 审查评论集成

10. 特殊系统

10.1 KAIROS — 主动助手

“始终在线”的助手模式，无需用户输入即可主动行动：

监控终端输出和文件变更
检测到问题（构建失败、测试报错）时主动提供帮助
Sleep 工具支持等待和轮询
每日日志式记忆（追加式日期命名日志）

10.2 ULTRAPLAN — 深度规划

将复杂任务卸载到远程 Opus 4.6 会话：

最多 30 分钟深度思考
适合架构设计、复杂重构
通过 /ultraplan 命令触发

10.3 Undercover Mode — 隐蔽模式

Anthropic 员工在公共仓库中工作时使用，防止泄漏内部信息：

屏蔽内部模型代号（Capybara, Tengu 等）
隐藏用户是 AI 的事实
防止提及内部基础设施

10.4 Buddy — 终端电子宠物

Tamagotchi 风格的伴侣系统：

确定性抽卡：基于 userId 种子的 Mulberry32 PRNG
18 种物种：Common (Pebblecrab) 到 Legendary (Nebulynx)
属性系统：DEBUGGING, CHAOS, SNARK 等
灵魂描述：Claude 生成的角色描述

10.5 Dream 系统 — 记忆整合

后台子智能体在空闲时运行：

Orient：读取 MEMORY.md
Gather：从日志中发现新信号
Consolidate：更新持久记忆
Prune：保持上下文高效

10.6 提示词缓存策略

全局缓存断点：内置工具列表后
前缀匹配：工具名称排序保证缓存稳定性
独立分区：内置工具和 MCP 工具分离以避免缓存失效

11. 使用指南

11.1 安装与启动

# 前置要求
# - Bun 或 Node.js v18+
# - Git (可选但推荐)

# 安装依赖
npm install

# 构建
npm run build

# 运行 CLI
node dist/main.js

# 开发模式
npm run dev

11.2 基本使用流程

# 进入项目目录启动
cd /path/to/my-project
claude

# 常用命令
> 帮我修复这个 bug              # 自由对话
/edit src/foo.ts               # 快速编辑文件
/commit                        # 生成提交信息
/diff                          # 查看变更
/clear                         # 清空对话
/model                          # 切换模型

11.3 权限模式

Claude Code 支持多种权限模式，控制工具是否需要用户确认：

模式	描述
`default`	标准模式，敏感操作需要确认
`accept-edits`	自动接受文件编辑
`bypass`	跳过所有权限检查（企业环境）
`plan`	计划模式，先规划后执行

# 启动时指定模式
claude --permission-mode accept-edits

# 运行时切换
/permissions

11.4 项目配置 (CLAUDE.md)

# CLAUDE.md

## 构建与运行
npm install && npm run dev

## 架构
- 前端: React + TypeScript
- 后端: Express + PostgreSQL
- 测试: Vitest

## 代码规范
- 使用函数组件 + Hooks
- 避免 any 类型
- 测试覆盖率 > 80%

11.5 记忆系统使用

# 查看当前记忆
/memory

# Claude 会自动在对话中建议保存记忆
# 也可以手动输入:
记住：用户偏好使用 TypeScript strict 模式

11.6 MCP 服务器配置

// ~/.claude/mcp.json 或 .mcp.json
{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    },
    "github": {
      "type": "sse",
      "url": "https://api.github.com/mcp"
    }
  }
}

# 管理 MCP 服务器
/mcp add <name> -- <command>
/mcp list
/mcp remove <name>

11.7 键盘快捷键

快捷键	功能
`Ctrl+C`	中断当前操作
`Ctrl+D`	退出
`Ctrl+O`	展开/折叠详情
`Ctrl+R`	搜索历史
`Ctrl+T`	切换待办视图
`Ctrl+B`	后台化任务
`Esc`	取消/返回
`Up/Down`	历史导航

11.8 工作树 (Worktree)

# 创建独立工作树
/ EnterWorktree

# 离开工作树
/ ExitWorktree keep   # 保留
/ ExitWorktree remove  # 删除

12. 配置参考

12.1 设置层级

层级	路径	优先级
策略 (Policy)	MDM 管理配置	最高
企业 (Enterprise)	远程管理配置	↑
托管 (Managed)	`managed-settings.json`	↑
本地 (Local)	`.claude/settings.local.json`	↑
项目 (Project)	`.claude/settings.json`	↑
用户 (User)	`~/.claude/settings.json`	最低

12.2 CLI 参数

claude [options] [prompt]

# 会话选项
--resume [id]            # 恢复之前的会话
--continue               # 继续最近的会话
--session-id <id>        # 指定会话 ID

# 模式选项
--print                  # 非交互模式（管道友好）
--permission-mode <mode> # 权限模式
--output-format <format> # 输出格式 (text/json/stream-json)
--model <model>          # 指定模型

# 上下文选项
--add-dir <path>         # 附加目录
--allowedTools <tools>   # 限制可用工具
--append-system-prompt   # 附加系统提示词
--custom-system-prompt   # 自定义系统提示词

# 功能选项
--agent-teams            # 启用 Agent Swarms
--fast                   # 快速模式 (Opus)
--thinking               # 启用扩展思考
--debug                  # 调试模式
--verbose                # 详细输出

12.3 环境变量

变量	用途
`ANTHROPIC_API_KEY`	API 密钥
`ANTHROPIC_BASE_URL`	API 端点
`CLAUDE_CODE_SIMPLE`	简单模式 (仅 Bash/Read/Edit)
`CLAUDE_CODE_PERMISSION_MODE`	默认权限模式
`CLAUDE_CODE_COORDINATOR_MODE`	Coordinator 模式
`ENABLE_LSP_TOOL`	LSP 工具开关
`CLAUDE_CODE_WORKTREE_MODE`	Worktree 模式

12.4 特性开关 (GrowthBook)

主要特性开关：

开关	功能
`WORKFLOW_SCRIPTS`	Workflow 工具
`COORDINATOR_MODE`	Coordinator 多智能体模式
`CONTEXT_COLLAPSE`	上下文折叠
`REACTIVE_COMPACT`	反应式压缩
`AGENT_TRIGGERS`	Cron 调度任务
`KAIROS`	主动助手模式
`HISTORY_SNIP`	历史片段
`TODO_V2`	新版待办系统
`BASH_CLASSIFIER`	Bash 命令安全分类器

13. 技术栈与依赖

13.1 核心依赖

框架	用途
React 19	UI 框架
Ink	React → 终端渲染器
Commander.js	CLI 参数解析
Bun	运行时 + 打包器
Zod v4	Schema 验证
TypeScript 5.7	类型系统

13.2 API/SDK

库	用途
`@anthropic-ai/sdk`	Anthropic API 客户端
`@anthropic-ai/bedrock-sdk`	AWS Bedrock 集成
`@anthropic-ai/vertex-sdk`	GCP Vertex AI 集成
`@anthropic-ai/foundry-sdk`	Azure Foundry 集成
`@modelcontextprotocol/sdk`	MCP 协议实现

13.3 工具库

库	用途
`lodash-es`	通用工具函数
`chalk`	终端颜色
`marked`	Markdown 渲染
`diff`	文本差异比较
`highlight.js`	代码高亮
`sharp`	图像处理
`fuse.js`	模糊搜索
`picomatch`	Glob 模式匹配
`chokidar`	文件监听
`semver`	版本比较

13.4 遥测

库	用途
`@opentelemetry/*`	追踪/指标/日志
`@growthbook/growthbook`	特性开关

14. Stub 补全模块

以下模块在源码缺失的情况下被补全实现：

模块	文件	功能
contextCollapse	`services/contextCollapse/index.js`	上下文折叠：长消息替换为摘要
connectorText	`types/connectorText.js`	Connector text block 类型
WorkflowTool	`tools/WorkflowTool/WorkflowTool.js`	工作流脚本执行器
WorkflowTool bundled	`tools/WorkflowTool/bundled/index.js`	内置工作流注册
REPLTool	`tools/REPLTool/REPLTool.js`	REPL 命令解析器
TungstenTool	`tools/TungstenTool/TungstenTool.js`	tmux socket 隔离管理
SuggestBackgroundPRTool	`tools/SuggestBackgroundPRTool/`	PR 机会检测
VerifyPlanExecutionTool	`tools/VerifyPlanExecutionTool/`	计划验证
verifyContent	`skills/bundled/verifyContent.js`	verify 技能内容
filePersistenceTypes	`utils/filePersistence/`	文件持久化类型

15. 安全与权限模型

15.1 权限检查流程

工具调用请求
  ↓
1. 规则匹配 (Deny Rules)
  ├── 工具名称匹配 → 自动拒绝
  └── MCP 服务器前缀匹配 → 自动拒绝
  ↓
2. 工具级验证 (validateInput)
  ├── 路径安全检查
  ├── 命令安全检查
  └── 模式验证
  ↓
3. 工具级权限 (checkPermissions)
  ├── 特定工具逻辑
  └── 上下文感知决策
  ↓
4. 通用权限系统
  ├── Always Allow 规则
  ├── Always Deny 规则
  ├── Classifier 自动审批 (Bash)
  ├── Hook 审批 (PreToolUse)
  └── 用户对话框
  ↓
5. 沙箱 (可选)
  └── 隔离执行环境

15.2 权限规则

{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(git:*)",
      "Read(/home/user/projects/*)",
      "Edit(/home/user/projects/*)"
    ],
    "deny": [
      "Bash(rm:*)",
      "Bash(sudo:*)",
      "WebFetch(*)"
    ]
  }
}

15.3 Bash 安全

破坏性命令警告：rm -rf, sudo, chmod 777 等触发警告
只读验证：区分只读命令 (ls, cat, git status) 和修改命令
沙箱模式：可选隔离执行环境
Git 安全检查：防止危险 Git 操作（push --force 到 main）

15.4 Web 安全

预授权域名：80+ 开发者文档站点无需确认
URL 验证：防止 SSRF 攻击
内容过滤：结果缓存 15 分钟

附录：快速参考

A. 工具名称映射

Agent         → 生成子智能体      Task (历史别名)
AskUserQuestion → 向用户提问
Bash          → Shell 命令
Brief/SendUserMessage → 发送消息
Config        → 配置管理
CronCreate    → 创建定时任务
CronDelete    → 删除定时任务
CronList      → 列出定时任务
Edit          → 文件编辑
EnterPlanMode → 进入计划模式
EnterWorktree → 创建工作树
ExitPlanMode  → 退出计划模式
ExitWorktree  → 退出工作树
Glob          → 文件搜索
Grep          → 内容搜索
LSP           → 语言服务器
NotebookEdit  → Jupyter 编辑
PowerShell    → PowerShell
Read          → 文件读取
REPL          → 交互式 REPL
ReadMcpResource → MCP 资源
RemoteTrigger → 远程触发
Skill         → 技能调用
Sleep         → 等待
StructuredOutput → 结构化输出
TaskCreate    → 创建任务
TaskGet       → 获取任务
TaskList      → 任务列表
TaskUpdate    → 更新任务
TaskOutput    → 任务输出
TaskStop      → 停止任务
TeamCreate    → 创建团队
TeamDelete    → 删除团队
TodoWrite     → 待办事项
ToolSearch    → 工具搜索
Tungsten      → tmux 管理
WebFetch      → URL 获取
WebSearch     → 网络搜索
Workflow      → 工作流

B. 常用命令速查

/help            帮助
/clear           清空对话
/compact         压缩上下文
/config          配置管理
/model           切换模型
/commit          生成提交
/diff            查看变更
/branch          创建分支
/resume          恢复会话
/rename          重命名会话
/cost            查看费用
/usage           查看使用量
/doctor          系统诊断
/mcp             MCP 管理
/ide             IDE 连接
/agents          智能体管理
/memory          记忆管理
/skills          技能管理
/plugin          插件管理
/theme           主题切换
/vim             Vim 模式
/voice           语音输入
/feedback        发送反馈
/export          导出对话
/exit            退出

Domi Zone

Claude Code CLI — 架构设计与使用指南

目录

1. 概述

技术指标

2. 总体架构

2.1 分层架构

2.2 数据流

2.3 入口文件 main.tsx 结构

3. 核心系统

3.1 查询引擎 (QueryEngine.ts)

3.2 查询流程 (query.ts)

3.3 工具框架 (Tool.ts)

3.4 状态管理 (state/AppState.tsx)

3.5 上下文管理 (context.ts)

4. 工具系统

4.1 工具注册机制 (tools.ts)

4.2 完整工具清单

文件操作工具

Shell 执行工具

任务管理工具

智能体与团队工具

用户交互工具

搜索与网络工具

工作流与调度工具

工作区管理工具

MCP 与 LSP 工具

其他工具

仅限内部 (Ant) 的工具

4.3 工具生命周期

5. 服务层

5.1 MCP 集成 (services/mcp/)

5.2 API 客户端 (services/api/)

5.3 上下文压缩 (services/compact/)

5.4 记忆系统 (memdir/ + services/SessionMemory/ + services/extractMemories/)

5.5 分析与遥测 (services/analytics/)

5.6 插件系统 (services/plugins/ + src/plugins/)

5.7 LSP 服务 (services/lsp/)

6. 多智能体系统

6.1 Agent 工具 (tools/AgentTool/)

6.2 Coordinator 模式 (coordinator/coordinatorMode.ts)

6.3 Agent Swarms (utils/swarm/)

6.4 Workflow 系统 (tools/WorkflowTool/)

7. UI 架构

7.1 React/Ink 终端 UI

7.2 屏幕组件

7.3 组件层次

7.4 设计系统 (components/design-system/)

7.5 键盘系统 (keybindings/)

7.6 Vim 模式 (vim/)

8. 技能与命令系统

8.1 技能系统 (skills/)

8.2 斜杠命令 (commands/ — 88+ 个)

9. IDE 集成与桥接

9.1 Bridge 系统 (bridge/)

9.2 服务器层 (server/)

9.3 IDE 特性

10. 特殊系统

10.1 KAIROS — 主动助手

10.2 ULTRAPLAN — 深度规划

10.3 Undercover Mode — 隐蔽模式

10.4 Buddy — 终端电子宠物

10.5 Dream 系统 — 记忆整合

10.6 提示词缓存策略

11. 使用指南

11.1 安装与启动

11.2 基本使用流程

11.3 权限模式

11.4 项目配置 (CLAUDE.md)

11.5 记忆系统使用

11.6 MCP 服务器配置

11.7 键盘快捷键

11.8 工作树 (Worktree)

12. 配置参考

12.1 设置层级

12.2 CLI 参数

12.3 环境变量

12.4 特性开关 (GrowthBook)

13. 技术栈与依赖

13.1 核心依赖

2.3 入口文件 `main.tsx` 结构

3.1 查询引擎 (`QueryEngine.ts`)

3.2 查询流程 (`query.ts`)

3.3 工具框架 (`Tool.ts`)

3.4 状态管理 (`state/AppState.tsx`)

3.5 上下文管理 (`context.ts`)

4.1 工具注册机制 (`tools.ts`)

5.1 MCP 集成 (`services/mcp/`)

5.2 API 客户端 (`services/api/`)

5.3 上下文压缩 (`services/compact/`)

5.4 记忆系统 (`memdir/` + `services/SessionMemory/` + `services/extractMemories/`)

5.5 分析与遥测 (`services/analytics/`)

5.6 插件系统 (`services/plugins/` + `src/plugins/`)

5.7 LSP 服务 (`services/lsp/`)

6.1 Agent 工具 (`tools/AgentTool/`)

6.2 Coordinator 模式 (`coordinator/coordinatorMode.ts`)

6.3 Agent Swarms (`utils/swarm/`)

6.4 Workflow 系统 (`tools/WorkflowTool/`)

7.4 设计系统 (`components/design-system/`)

7.5 键盘系统 (`keybindings/`)

7.6 Vim 模式 (`vim/`)

8.1 技能系统 (`skills/`)

8.2 斜杠命令 (`commands/` — 88+ 个)

9.1 Bridge 系统 (`bridge/`)

9.2 服务器层 (`server/`)