mirror of
https://github.com/roger2ai/Claude-Code-Compiled.git
synced 2026-09-03 12:57:27 +08:00
restructure: move docs to docs/, rewrite README in English
- Move all .md documentation into docs/ directory - Rewrite README.md with English documentation covering: - All 22 missing source stubs added - Source code fixes (useEffectEvent, version check, auth, sandbox-runtime) - Bun compatibility shims (macro, bun-bundle) - 28 missing npm dependencies - Build and run instructions - Remove dist/ from tracking (users compile themselves)
This commit is contained in:
Roger
439
docs/API-CONFIG.md
Normal file
439
docs/API-CONFIG.md
Normal file
@@ -0,0 +1,439 @@
|
||||
# Claude Code API 配置指南
|
||||
|
||||
> 基于 2026-03-31 泄露的 Claude Code CLI 源码
|
||||
> 最后更新：2026-04-01
|
||||
|
||||
---
|
||||
|
||||
## 1. API 提供商概览
|
||||
|
||||
Claude Code 支持 **4 种 API 后端**，通过环境变量切换：
|
||||
|
||||
| 提供商 | 启用变量 | 说明 |
|
||||
|--------|----------|------|
|
||||
| **Direct API** | 默认（无需设置） | Anthropic 官方 API |
|
||||
| **AWS Bedrock** | `CLAUDE_CODE_USE_BEDROCK=1` | AWS 托管的 Claude |
|
||||
| **Google Vertex AI** | `CLAUDE_CODE_USE_VERTEX=1` | GCP 托管的 Claude |
|
||||
| **Azure Foundry** | `CLAUDE_CODE_USE_FOUNDRY=1` | Azure 托管的 Claude |
|
||||
|
||||
优先级判断逻辑（`src/utils/model/providers.ts`）：
|
||||
|
||||
```typescript
|
||||
export function getAPIProvider(): APIProvider {
|
||||
return isEnvTruthy(process.env.CLAUDE_CODE_USE_BEDROCK) ? 'bedrock'
|
||||
: isEnvTruthy(process.env.CLAUDE_CODE_USE_VERTEX) ? 'vertex'
|
||||
: isEnvTruthy(process.env.CLAUDE_CODE_USE_FOUNDRY) ? 'foundry'
|
||||
: 'firstParty'
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Direct API（默认）
|
||||
|
||||
### 2.1 认证
|
||||
|
||||
| 环境变量 | 必需 | 说明 |
|
||||
|----------|------|------|
|
||||
| `ANTHROPIC_API_KEY` | ✅ | Anthropic API 密钥 |
|
||||
| `ANTHROPIC_AUTH_TOKEN` | — | Bearer token 替代方式 |
|
||||
|
||||
**二选一**，`ANTHROPIC_API_KEY` 优先级更高。也支持 OAuth 登录（`/login` 命令），token 存储在 `~/.claude/` 配置目录。
|
||||
|
||||
### 2.2 端点配置
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
|----------|--------|------|
|
||||
| `ANTHROPIC_BASE_URL` | `https://api.anthropic.com` | API 基础 URL |
|
||||
| `ANTHROPIC_UNIX_SOCKET` | — | Unix socket 路径（替代 TCP） |
|
||||
|
||||
自定义代理或本地网关时设置 `ANTHROPIC_BASE_URL`。代码中通过 `isFirstPartyAnthropicBaseUrl()` 判断是否为官方端点：
|
||||
|
||||
```typescript
|
||||
export function isFirstPartyAnthropicBaseUrl(): boolean {
|
||||
const baseUrl = process.env.ANTHROPIC_BASE_URL
|
||||
if (!baseUrl) return true
|
||||
const host = new URL(baseUrl).host
|
||||
return ['api.anthropic.com'].includes(host)
|
||||
}
|
||||
```
|
||||
|
||||
### 2.3 模型选择
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `ANTHROPIC_MODEL` | 主循环模型（最高优先级的用户可配变量） |
|
||||
| `ANTHROPIC_SMALL_FAST_MODEL` | 轻量模型（默认 Haiku，用于 token 估算等） |
|
||||
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | 覆盖默认 Opus 模型 |
|
||||
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | 覆盖默认 Sonnet 模型 |
|
||||
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | 覆盖默认 Haiku 模型 |
|
||||
|
||||
**模型选择优先级**（`getMainLoopModel()`）：
|
||||
|
||||
1. 会话中 `/model` 命令覆盖 — 最高
|
||||
2. `--model` CLI 参数
|
||||
3. `ANTHROPIC_MODEL` 环境变量
|
||||
4. 用户 settings 中保存的模型
|
||||
5. 内置默认值（Sonnet）
|
||||
|
||||
### 2.4 Beta 功能
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `ANTHROPIC_BETAS` | 追加 beta header（逗号分隔） |
|
||||
|
||||
Claude Code 内部会自动附加多个 beta header，如 `files-api-2025-04-14`、`oauth-2025-04-20` 等。
|
||||
|
||||
### 2.5 请求自定义
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `ANTHROPIC_CUSTOM_HEADERS` | 自定义 HTTP 头（JSON 格式） |
|
||||
| `CLAUDE_CODE_EXTRA_BODY` | 请求体额外字段（JSON 格式） |
|
||||
|
||||
---
|
||||
|
||||
## 3. AWS Bedrock
|
||||
|
||||
### 3.1 启用
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_BEDROCK=1
|
||||
```
|
||||
|
||||
### 3.2 认证
|
||||
|
||||
使用 AWS SDK 默认凭证链（`@aws-sdk/credential-provider-node`）：
|
||||
|
||||
- 环境变量：`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_SESSION_TOKEN`
|
||||
- AWS CLI 配置：`~/.aws/credentials`
|
||||
- IAM Role（EC2 / ECS / Lambda）
|
||||
- SSO
|
||||
|
||||
跳过 Bedrock 认证检查（开发/测试用）：
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_SKIP_BEDROCK_AUTH=1
|
||||
```
|
||||
|
||||
### 3.3 区域配置
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
|----------|--------|------|
|
||||
| `AWS_REGION` / `AWS_DEFAULT_REGION` | `us-east-1` | 全局 AWS 区域 |
|
||||
| `ANTHROPIC_SMALL_FAST_MODEL_AWS_REGION` | — | 轻量模型独立区域 |
|
||||
|
||||
### 3.4 端点
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `ANTHROPIC_BEDROCK_BASE_URL` | 自定义 Bedrock 端点 |
|
||||
|
||||
---
|
||||
|
||||
## 4. Google Vertex AI
|
||||
|
||||
### 4.1 启用
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_VERTEX=1
|
||||
```
|
||||
|
||||
### 4.2 认证
|
||||
|
||||
使用 `google-auth-library` 默认凭证链：
|
||||
|
||||
- `GOOGLE_APPLICATION_CREDENTIALS` — 服务账号 JSON 路径
|
||||
- `gcloud auth application-default login` — 用户凭证
|
||||
- Workload Identity（GKE / Cloud Run）
|
||||
|
||||
跳过 Vertex 认证检查：
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_SKIP_VERTEX_AUTH=1
|
||||
```
|
||||
|
||||
### 4.3 项目与区域
|
||||
|
||||
| 环境变量 | 必需 | 说明 |
|
||||
|----------|------|------|
|
||||
| `ANTHROPIC_VERTEX_PROJECT_ID` | ✅ | GCP 项目 ID |
|
||||
| `CLOUD_ML_REGION` | — | 默认区域（回退 `us-east5`） |
|
||||
| `VERTEX_REGION_CLAUDE_3_5_HAIKU` | — | Claude 3.5 Haiku 专属区域 |
|
||||
| `VERTEX_REGION_CLAUDE_HAIKU_4_5` | — | Claude Haiku 4.5 专属区域 |
|
||||
| `VERTEX_REGION_CLAUDE_3_5_SONNET` | — | Claude 3.5 Sonnet 专属区域 |
|
||||
| `VERTEX_REGION_CLAUDE_3_7_SONNET` | — | Claude 3.7 Sonnet 专属区域 |
|
||||
|
||||
区域优先级：模型专属变量 > `CLOUD_ML_REGION` > 配置默认 > `us-east5`。
|
||||
|
||||
---
|
||||
|
||||
## 5. Azure Foundry
|
||||
|
||||
### 5.1 启用
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_FOUNDRY=1
|
||||
```
|
||||
|
||||
### 5.2 端点配置（二选一）
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `ANTHROPIC_FOUNDRY_RESOURCE` | Azure 资源名，自动生成端点 `https://{resource}.services.ai.azure.com/anthropic/v1/messages` |
|
||||
| `ANTHROPIC_FOUNDRY_BASE_URL` | 完整端点 URL（优先级更高） |
|
||||
|
||||
### 5.3 认证
|
||||
|
||||
| 方式 | 环境变量 | 说明 |
|
||||
|------|----------|------|
|
||||
| API Key | `ANTHROPIC_FOUNDRY_API_KEY` | 直接使用密钥 |
|
||||
| Azure AD | — | 无 API key 时自动使用 `DefaultAzureCredential` |
|
||||
|
||||
Azure AD 支持的凭证方式：环境变量、Managed Identity、Azure CLI、Visual Studio Code 等。
|
||||
|
||||
跳过 Foundry 认证检查：
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_SKIP_FOUNDRY_AUTH=1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 代理（Proxy）
|
||||
|
||||
### 6.1 HTTP 代理
|
||||
|
||||
| 环境变量 | 优先级 | 说明 |
|
||||
|----------|--------|------|
|
||||
| `https_proxy` | 1 | 小写（最高优先级） |
|
||||
| `HTTPS_PROXY` | 2 | 大写 |
|
||||
| `http_proxy` | 3 | HTTP 代理 |
|
||||
| `HTTP_PROXY` | 4 | HTTP 大写 |
|
||||
| `no_proxy` / `NO_PROXY` | — | 代理排除列表 |
|
||||
|
||||
### 6.2 代理行为
|
||||
|
||||
```typescript
|
||||
export function getProxyUrl(): string | undefined {
|
||||
return env.https_proxy || env.HTTPS_PROXY || env.http_proxy || env.HTTP_PROXY
|
||||
}
|
||||
```
|
||||
|
||||
`NO_PROXY` 支持逗号分隔的域名/IP 列表，支持通配符 `*`。
|
||||
|
||||
### 6.3 代理 DNS 解析
|
||||
|
||||
```bash
|
||||
# 让代理端解析域名（适用于沙箱环境）
|
||||
export CLAUDE_CODE_PROXY_RESOLVES_HOSTS=1
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. mTLS 与 TLS 配置
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `CLAUDE_CODE_CLIENT_CERT` | 客户端证书文件路径 |
|
||||
| `CLAUDE_CODE_CLIENT_KEY` | 客户端私钥文件路径 |
|
||||
| `CLAUDE_CODE_CLIENT_KEY_PASSPHRASE` | 私钥密码 |
|
||||
| `NODE_EXTRA_CA_CERTS` | 额外 CA 证书（Node.js 自动加载） |
|
||||
|
||||
---
|
||||
|
||||
## 8. OAuth 认证
|
||||
|
||||
### 8.1 流程
|
||||
|
||||
Claude Code 实现了完整的 OAuth 2.0 流程（`src/services/oauth/`）：
|
||||
|
||||
1. 用户执行 `/login`
|
||||
2. 浏览器打开 Anthropic 授权页面
|
||||
3. 用户授权后回调到本地监听端口
|
||||
4. 交换 access_token / refresh_token
|
||||
5. Token 存储在 `~/.claude/` 安全存储中
|
||||
|
||||
### 8.2 OAuth Scopes
|
||||
|
||||
| Scope | 用途 |
|
||||
|-------|------|
|
||||
| `user:inference` | API 推理调用 |
|
||||
| `user:profile` | 用户信息读取 |
|
||||
| `user:sessions:claude_code` | Claude Code 会话管理 |
|
||||
| `user:mcp_servers` | MCP 服务器管理 |
|
||||
| `user:file_upload` | 文件上传 |
|
||||
| `org:create_api_key` | Console 端 API key 创建 |
|
||||
|
||||
### 8.3 OAuth 环境变量
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `CLAUDE_CODE_OAUTH_CLIENT_ID` | 自定义 OAuth client ID |
|
||||
| `CLAUDE_CODE_OAUTH_TOKEN` | 直接注入 OAuth token |
|
||||
| `CLAUDE_CODE_OAUTH_REFRESH_TOKEN` | 注入 refresh token |
|
||||
| `CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR` | 从文件描述符读取 token |
|
||||
| `CLAUDE_CODE_CUSTOM_OAUTH_URL` | 自定义 OAuth 端点 URL |
|
||||
|
||||
---
|
||||
|
||||
## 9. 其他关键配置
|
||||
|
||||
### 9.1 会话与上下文
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
|----------|--------|------|
|
||||
| `CLAUDE_CODE_MAX_CONTEXT_TOKENS` | — | 最大上下文 token 数 |
|
||||
| `CLAUDE_CODE_MAX_OUTPUT_TOKENS` | — | 最大输出 token 数 |
|
||||
| `CLAUDE_CODE_MAX_RETRIES` | — | API 重试次数 |
|
||||
| `CLAUDE_CODE_AUTO_COMPACT_WINDOW` | — | 自动压缩窗口大小 |
|
||||
| `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE` | — | 压缩阈值百分比 |
|
||||
|
||||
### 9.2 功能开关
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `CLAUDE_CODE_DISABLE_THINKING` | 禁用 thinking 模式 |
|
||||
| `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` | 禁用自适应 thinking |
|
||||
| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 禁用非必要网络请求 |
|
||||
| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 禁用自动记忆提取 |
|
||||
| `CLAUDE_CODE_DISABLE_CRON` | 禁用定时任务 |
|
||||
| `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` | 禁用后台任务 |
|
||||
| `CLAUDE_CODE_ALWAYS_ENABLE_EFFORT` | 始终启用 extended thinking |
|
||||
| `CLAUDE_CODE_EFFORT_LEVEL` | thinking effort 级别 |
|
||||
| `CLAUDE_CODE_SIMPLE` | 简化模式（减少输出） |
|
||||
| `CLAUDE_CODE_BRIEF` | 简洁模式 |
|
||||
|
||||
### 9.3 调试与诊断
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `CLAUDE_DEBUG` | 调试模式 |
|
||||
| `CLAUDE_CODE_DEBUG_LOGS_DIR` | 调试日志目录 |
|
||||
| `CLAUDE_CODE_DEBUG_LOG_LEVEL` | 调试日志级别 |
|
||||
| `CLAUDE_CODE_PROFILE_STARTUP` | 启动性能分析 |
|
||||
| `CLAUDE_CODE_PROFILE_QUERY` | 查询性能分析 |
|
||||
| `CLAUDE_CODE_DIAGNOSTICS_FILE` | 诊断输出文件 |
|
||||
| `CLAUDE_CODE_JSONL_TRANSCRIPT` | JSONL 格式对话记录 |
|
||||
|
||||
### 9.4 配置目录
|
||||
|
||||
| 环境变量 | 默认值 | 说明 |
|
||||
|----------|--------|------|
|
||||
| `CLAUDE_CONFIG_DIR` | `~/.claude` | 配置目录 |
|
||||
|
||||
配置目录结构：
|
||||
|
||||
```
|
||||
~/.claude/
|
||||
├── config.json # 全局配置（模型、设置）
|
||||
├── settings.json # 用户设置
|
||||
├── oauth-tokens.json # OAuth token 存储
|
||||
├── mcp-servers.json # MCP 服务器配置
|
||||
├── projects/ # 项目级配置
|
||||
└── memory/ # 持久化记忆
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 自定义模型选项
|
||||
|
||||
允许在模型选择菜单中添加自定义模型：
|
||||
|
||||
| 环境变量 | 说明 |
|
||||
|----------|------|
|
||||
| `ANTHROPIC_CUSTOM_MODEL_OPTION` | 自定义模型 ID |
|
||||
| `ANTHROPIC_CUSTOM_MODEL_OPTION_NAME` | 显示名称 |
|
||||
| `ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION` | 模型描述 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 完整配置示例
|
||||
|
||||
### 11.1 Direct API（最简）
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY=sk-ant-xxx
|
||||
bun dist/bundle.js -p "hello"
|
||||
```
|
||||
|
||||
### 11.2 自定义代理
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY=sk-ant-xxx
|
||||
export ANTHROPIC_BASE_URL=https://my-proxy.example.com
|
||||
bun dist/bundle.js
|
||||
```
|
||||
|
||||
### 11.3 AWS Bedrock
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_BEDROCK=1
|
||||
export AWS_REGION=us-west-2
|
||||
export AWS_ACCESS_KEY_ID=AKIAxxx
|
||||
export AWS_SECRET_ACCESS_KEY=xxx
|
||||
bun dist/bundle.js
|
||||
```
|
||||
|
||||
### 11.4 Vertex AI
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_VERTEX=1
|
||||
export ANTHROPIC_VERTEX_PROJECT_ID=my-gcp-project
|
||||
export CLOUD_ML_REGION=us-central1
|
||||
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
|
||||
bun dist/bundle.js
|
||||
```
|
||||
|
||||
### 11.5 Azure Foundry + API Key
|
||||
|
||||
```bash
|
||||
export CLAUDE_CODE_USE_FOUNDRY=1
|
||||
export ANTHROPIC_FOUNDRY_RESOURCE=my-azure-resource
|
||||
export ANTHROPIC_FOUNDRY_API_KEY=xxx
|
||||
bun dist/bundle.js
|
||||
```
|
||||
|
||||
### 11.6 带代理 + mTLS
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY=sk-ant-xxx
|
||||
export HTTPS_PROXY=http://proxy.corp.com:8080
|
||||
export NO_PROXY=localhost,127.0.0.1
|
||||
export CLAUDE_CODE_CLIENT_CERT=/path/to/client.pem
|
||||
export CLAUDE_CODE_CLIENT_KEY=/path/to/client-key.pem
|
||||
bun dist/bundle.js
|
||||
```
|
||||
|
||||
### 11.7 调试模式
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY=sk-ant-xxx
|
||||
export CLAUDE_DEBUG=1
|
||||
export CLAUDE_CODE_DEBUG_LOGS_DIR=/tmp/claude-debug
|
||||
export CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose
|
||||
bun dist/bundle.js
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 认证优先级
|
||||
|
||||
Claude Code 的认证解析顺序（`src/utils/auth.ts`）：
|
||||
|
||||
1. **文件描述符注入** — `CLAUDE_CODE_API_KEY_FILE_DESCRIPTOR` / `CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR`
|
||||
2. **环境变量** — `ANTHROPIC_API_KEY` / `CLAUDE_CODE_OAUTH_TOKEN`
|
||||
3. **macOS Keychain** — 安全存储的凭证
|
||||
4. **配置文件** — `~/.claude/config.json` 中的 API key
|
||||
5. **API key helper** — `CLAUDE_CODE_API_KEY_HELPER_TTL_MS` 控制的外部脚本
|
||||
6. **OAuth 登录** — `/login` 流程获取的 token
|
||||
|
||||
---
|
||||
|
||||
## 13. 注意事项
|
||||
|
||||
1. **`isFirstPartyAnthropicBaseUrl()` 影响行为** — 只有指向 `api.anthropic.com` 时才被视为官方端点，影响 bootstrap 请求、模型默认值等
|
||||
2. **第三方提供商模型延迟** — Bedrock/Vertex/Foundry 的模型可用性滞后于 Direct API，代码中为它们保留了独立的默认模型分支
|
||||
3. **macOS Keychain 回退** — Linux 环境下安全存储回退到明文文件，注意权限控制
|
||||
4. **代理 + mTLS 同时使用** — 代码同时支持 HTTPS 代理 + 客户端证书认证，按需组合
|
||||
5. **OAuth token 自动刷新** — `withOAuth401Retry()` 会自动处理 401 错误并刷新 token
|
||||
298
docs/ARCHITECTURE-BRIDGE-REMOTE.md
Normal file
298
docs/ARCHITECTURE-BRIDGE-REMOTE.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# Bridge / Remote / Coordinator 架构详细文档
|
||||
|
||||
---
|
||||
|
||||
## Bridge 系统 (src/bridge/, 31 文件)
|
||||
|
||||
### 概述
|
||||
|
||||
Bridge 是 Claude Code 的 **远程控制核心**，实现本地 CLI 与 claude.ai/web/mobile 之间的双向通信。核心场景：用户通过手机上的 Claude 应用控制本地终端中的 Claude Code 会话。
|
||||
|
||||
### 文件清单与职责
|
||||
|
||||
#### 核心会话管理
|
||||
|
||||
| 文件 | 行数(估) | 职责 |
|
||||
|------|---------|------|
|
||||
| `bridgeMain.ts` | ~3000 | 桥接主循环。连接 claude.ai bridge API、轮询 work、生成 session、管理生命周期 |
|
||||
| `sessionRunner.ts` | ~400 | 会话执行器：生成子进程执行 work item，管理 worktree 隔离 |
|
||||
| `createSession.ts` | ~200 | 会话创建辅助 |
|
||||
| `replBridge.ts` | ~2400 | REPL 与远程的桥接核心。处理 SDK 消息的 ingress/egress、权限转发 |
|
||||
| `replBridgeHandle.ts` | ~200 | Bridge handle 管理 |
|
||||
| `replBridgeTransport.ts` | ~300 | 传输层抽象：v1 (WebSocket) 和 v2 (HybridTransport) |
|
||||
|
||||
#### 消息与控制
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `bridgeMessaging.ts` | 共享传输层：SDK 消息解析、控制请求处理、echo 去重、结果消息构建 |
|
||||
| `inboundMessages.ts` | 入站消息处理 |
|
||||
| `inboundAttachments.ts` | 入站附件处理 |
|
||||
| `bridgeApi.ts` | Bridge API 客户端：环境发现、work 轮询、session 报告 |
|
||||
| `bridgePermissionCallbacks.ts` | 权限回调代理：将远程权限请求转发到本地 REPL |
|
||||
|
||||
#### 安全与认证
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `jwtUtils.ts` | JWT token 管理：创建、刷新调度、过期检测 |
|
||||
| `trustedDevice.ts` | 可信设备认证：注册设备 token，用于 Remote Control 安全验证 |
|
||||
| `workSecret.ts` | Work secret 解码/构建：解析 server 下发的 session ingress token、API base URL 等 |
|
||||
| `sessionIdCompat.ts` | Session ID 兼容层：infra session ID 与 compat session ID 转换 |
|
||||
|
||||
#### 配置与控制
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `bridgeConfig.ts` | Bridge 配置：token、org UUID、environment ID |
|
||||
| `envLessBridgeConfig.ts` | 无环境变量的 Bridge 配置 |
|
||||
| `bridgeEnabled.ts` | 功能开关检查：是否启用 Remote Control |
|
||||
| `initReplBridge.ts` | REPL Bridge 初始化 |
|
||||
| `pollConfig.ts` / `pollConfigDefaults.ts` | 轮询间隔配置（指数退避） |
|
||||
| `flushGate.ts` | 消息刷新门控 |
|
||||
|
||||
#### 其他
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `bridgeUI.ts` | Bridge UI 日志工具 |
|
||||
| `bridgeDebug.ts` / `debugUtils.ts` | 调试工具 |
|
||||
| `bridgeStatusUtil.ts` | 状态格式化 |
|
||||
| `bridgePointer.ts` | Bridge 指针管理 |
|
||||
| `capacityWake.ts` | 容量唤醒：检测是否有 capacity 来处理新的 work |
|
||||
| `codeSessionApi.ts` | 代码会话 API |
|
||||
| `types.ts` | 类型定义：BridgeConfig, SessionHandle, SpawnMode 等 |
|
||||
|
||||
### 核心流程
|
||||
|
||||
```
|
||||
claude remote-control
|
||||
│
|
||||
├─ bridgeMain.ts: 连接 claude.ai bridge API
|
||||
│ ├─ 获取 environment ID
|
||||
│ ├─ 注册 trusted device
|
||||
│ └─ 开始轮询 work
|
||||
│
|
||||
├─ 轮询循环 (指数退避):
|
||||
│ ├─ GET /environments/{id}/work
|
||||
│ ├─ 收到 work item → sessionRunner 生成子进程
|
||||
│ │ ├─ 创建 worktree (隔离)
|
||||
│ │ ├─ 解析 work secret → session ingress token
|
||||
│ │ ├─ spawn claude CLI 子进程
|
||||
│ │ └─ 收集输出 → 上报
|
||||
│ └─ 无 work → 继续轮询
|
||||
│
|
||||
└─ 子进程通过 SDK 流式输出消息
|
||||
└─ bridgeMessaging.ts 处理 ingress
|
||||
├─ SDKMessage → 转发到远程
|
||||
├─ control_request → 权限代理
|
||||
└─ echo → 去重跳过
|
||||
```
|
||||
|
||||
### 协议层
|
||||
|
||||
Bridge 使用 **SDK 消息协议** (与 Anthropic Agent SDK 兼容):
|
||||
|
||||
```
|
||||
SDKMessage =
|
||||
| assistant message (text, tool_use blocks)
|
||||
| user message (tool_result blocks)
|
||||
| system message (info, warning)
|
||||
| result message (usage, cost, duration)
|
||||
| control_request (permission prompts)
|
||||
| control_response (permission decisions)
|
||||
```
|
||||
|
||||
传输层支持两种模式：
|
||||
- **v1**: WebSocket 直连
|
||||
- **v2**: HybridTransport (WebSocket + HTTP fallback)
|
||||
|
||||
---
|
||||
|
||||
## Remote 系统 (src/remote/, 4 文件)
|
||||
|
||||
### 概述
|
||||
|
||||
Remote 系统实现 **CCR (Claude Code Remote)** 模式：用户通过 `--remote` 标志创建远程会话，本地 TUI 作为 viewer/client。
|
||||
|
||||
### 文件清单
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `RemoteSessionManager.ts` | 远程会话管理器：创建会话配置、处理 SDK 消息和控制请求 |
|
||||
| `SessionsWebSocket.ts` | WebSocket 客户端：连接 CCR 后端、处理消息、重连逻辑 |
|
||||
| `remotePermissionBridge.ts` | 远程权限桥接 |
|
||||
| `sdkMessageAdapter.ts` | SDK 消息适配器 |
|
||||
|
||||
### 核心流程
|
||||
|
||||
```
|
||||
claude --remote "task description"
|
||||
│
|
||||
├─ prepareApiRequest() → 获取 OAuth token
|
||||
├─ teleportToRemoteWithErrorHandling() → 创建远程会话
|
||||
├─ createRemoteSessionConfig() → 生成连接配置
|
||||
│
|
||||
└─ REPL 启动:
|
||||
├─ SessionsWebSocket 连接远程
|
||||
├─ RemoteSessionManager 管理消息流
|
||||
│ ├─ 用户输入 → WebSocket → 远程执行
|
||||
│ └─ 远程输出 → WebSocket → 本地显示
|
||||
└─ 权限请求 → remotePermissionBridge → 本地确认
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Server 系统 (src/server/, 3 文件)
|
||||
|
||||
### Direct Connect
|
||||
|
||||
`createDirectConnectSession.ts` — 创建直连会话。POST 到 `${serverUrl}/sessions`，返回 `DirectConnectConfig` 供 REPL 使用。
|
||||
|
||||
`directConnectManager.ts` — 直连会话管理。
|
||||
|
||||
`types.ts` — 连接响应 schema 验证。
|
||||
|
||||
### 使用场景
|
||||
|
||||
```
|
||||
claude connect cc://server-url
|
||||
│
|
||||
├─ parseConnectUrl() → 提取 serverUrl + authToken
|
||||
├─ createDirectConnectSession() → 创建会话
|
||||
└─ launchRepl() with directConnectConfig
|
||||
└─ REPL 通过 DirectConnectConfig 与远程通信
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Coordinator 系统 (src/coordinator/)
|
||||
|
||||
### 概述
|
||||
|
||||
`coordinatorMode.ts` — 多 Agent 协调模式。一个 "协调者" Agent 分发任务给多个 "工作器" Agent。
|
||||
|
||||
### 核心机制
|
||||
|
||||
协调模式通过环境变量 `CLAUDE_CODE_COORDINATOR_MODE=1` 启用。
|
||||
|
||||
工具过滤：
|
||||
- 协调者只能使用：AgentTool, TaskStopTool, SendMessageTool, TeamCreateTool, TeamDeleteTool
|
||||
- 工作器使用：BashTool, FileReadTool, FileEditTool, FileWriteTool 等基础工具
|
||||
- 工作器禁止：AgentTool (防止递归), TeamCreateTool, TeamDeleteTool
|
||||
|
||||
### 协调者工具集
|
||||
|
||||
```typescript
|
||||
const COORDINATOR_MODE_ALLOWED_TOOLS = [
|
||||
AGENT_TOOL_NAME, // 派发子任务给工作器
|
||||
BASH_TOOL_NAME, // 读取文件/检查状态
|
||||
FILE_READ_TOOL_NAME, // 读文件
|
||||
FILE_EDIT_TOOL_NAME, // 编辑文件
|
||||
TASK_STOP_TOOL_NAME, // 停止工作器
|
||||
SEND_MESSAGE_TOOL_NAME, // 与工作器通信
|
||||
]
|
||||
```
|
||||
|
||||
### 工作器执行
|
||||
|
||||
工作器以 in-process 或 tmux 方式启动：
|
||||
- `in-process`: 子 Agent 在同一进程内运行
|
||||
- `tmux`: 子 Agent 在独立 tmux 窗格中运行
|
||||
|
||||
每个工作器有独立的工作树 (worktree)、独立的工具权限上下文。
|
||||
|
||||
---
|
||||
|
||||
## Swarm 团队系统 (utils/swarm/)
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
utils/swarm/
|
||||
├── backends/
|
||||
│ ├── InProcessBackend.ts — 进程内执行后端
|
||||
│ ├── TmuxBackend.ts — tmux 执行后端
|
||||
│ ├── ITermBackend.ts — iTerm2 执行后端
|
||||
│ ├── PaneBackendExecutor.ts — 窗格执行器
|
||||
│ ├── detection.ts — 后端检测
|
||||
│ ├── registry.ts — 后端注册
|
||||
│ └── types.ts — 类型定义
|
||||
├── constants.ts — 常量
|
||||
├── inProcessRunner.ts — 进程内运行器
|
||||
├── leaderPermissionBridge.ts — 领导者权限桥接
|
||||
├── permissionSync.ts — 权限同步
|
||||
├── reconnection.ts — 重连逻辑
|
||||
├── spawnInProcess.ts — 进程内生成
|
||||
├── spawnUtils.ts — 生成工具
|
||||
├── teamHelpers.ts — 团队辅助
|
||||
├── teammateInit.ts — 队友初始化
|
||||
├── teammateLayoutManager.ts — 队友布局管理
|
||||
├── teammateModel.ts — 队友模型
|
||||
└── teammatePromptAddendum.ts — 队友提示补充
|
||||
```
|
||||
|
||||
### 架构
|
||||
|
||||
Swarm 团队由一个 Leader 和多个 Teammate 组成：
|
||||
|
||||
```
|
||||
Leader (协调者)
|
||||
│
|
||||
├─ Teammate 1 (tmux/in-process)
|
||||
├─ Teammate 2 (tmux/in-process)
|
||||
└─ Teammate N (tmux/in-process)
|
||||
```
|
||||
|
||||
Leader 通过 `TeamCreateTool` 创建队友，通过 `SendMessageTool` 与队友通信。
|
||||
|
||||
权限同步：Leader 的权限决策通过 `leaderPermissionBridge` 同步给所有队友。
|
||||
|
||||
---
|
||||
|
||||
## 系统间协作关系
|
||||
|
||||
```
|
||||
┌──────────────────┐ ┌──────────────────┐
|
||||
│ claude.ai │ │ Mobile/Web App │
|
||||
│ Bridge API │ │ (CCR Client) │
|
||||
└────────┬─────────┘ └────────┬─────────┘
|
||||
│ │
|
||||
Bridge 协议 Remote 协议
|
||||
(JWT auth) (OAuth auth)
|
||||
│ │
|
||||
┌────────▼────────────────────────▼────────┐
|
||||
│ 本地 Claude Code CLI │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌────────┐ │
|
||||
│ │ Bridge │ │ Remote │ │ Server │ │
|
||||
│ │ Manager │ │ Session │ │ Mode │ │
|
||||
│ └────┬─────┘ └────┬─────┘ └───┬────┘ │
|
||||
│ │ │ │ │
|
||||
│ └─────────────┼────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼──────┐ │
|
||||
│ │ REPL │ │
|
||||
│ │ (本地交互) │ │
|
||||
│ └──────┬──────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼──────┐ │
|
||||
│ │ Query │ │
|
||||
│ │ Engine │ │
|
||||
│ └──────┬──────┘ │
|
||||
│ │ │
|
||||
│ ┌──────▼──────┐ │
|
||||
│ │ Tools │ │
|
||||
│ │ (执行层) │ │
|
||||
│ └─────────────┘ │
|
||||
└──────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 关键设计决策
|
||||
|
||||
1. **Worktree 隔离**：每个远程会话在独立 worktree 中执行，避免污染本地工作区
|
||||
2. **JWT 认证**：Bridge 使用 JWT 而非 OAuth，支持 token 刷新调度
|
||||
3. **Echo 去重**：bridgeMessaging.ts 中的 BoundedUUIDSet 防止消息回环
|
||||
4. **指数退避轮询**：pollConfig.ts 实现智能轮询，空闲时降低频率
|
||||
5. **Trusted Device**：远程控制需要设备注册，增强安全性
|
||||
6. **v1/v2 传输**：支持 WebSocket (v1) 和 HybridTransport (v2) 两种传输模式
|
||||
727
docs/ARCHITECTURE-COMMANDS.md
Normal file
727
docs/ARCHITECTURE-COMMANDS.md
Normal file
@@ -0,0 +1,727 @@
|
||||
# Claude Code 命令系统架构
|
||||
|
||||
> 基于 `claude-code` 源码分析 (`/src/commands/`, `commands.ts`, `skills/`, `plugins/`, `keybindings/`)
|
||||
|
||||
---
|
||||
|
||||
## 1. Command 类型系统
|
||||
|
||||
命令定义在 `src/types/command.ts`，核心类型为：
|
||||
|
||||
```typescript
|
||||
type Command = CommandBase & (PromptCommand | LocalCommand | LocalJSXCommand)
|
||||
```
|
||||
|
||||
### 三种命令类型
|
||||
|
||||
| 类型 | 说明 | 用途 |
|
||||
|------|------|------|
|
||||
| `prompt` | 展开为一段 prompt 发送给模型 | Skill 型命令，如 `/commit`, `/review`, `/init` |
|
||||
| `local` | 本地执行，返回文本结果 | 不需要 UI 的命令，如 `/compact` |
|
||||
| `local-jsx` | 本地执行，渲染 React/Ink UI 组件 | 需要交互式界面的命令，如 `/config`, `/mcp`, `/doctor` |
|
||||
|
||||
### CommandBase 通用属性
|
||||
|
||||
```typescript
|
||||
type CommandBase = {
|
||||
name: string
|
||||
description: string
|
||||
aliases?: string[]
|
||||
type: 'prompt' | 'local' | 'local-jsx'
|
||||
isEnabled?: () => boolean // 条件启用（feature flags、env check）
|
||||
isHidden?: boolean // 是否从自动完成/帮助中隐藏
|
||||
availability?: CommandAvailability[] // 认证要求 ('claude-ai' | 'console')
|
||||
argumentHint?: string // 参数提示文字
|
||||
whenToUse?: string // 详细的使用场景说明
|
||||
version?: string
|
||||
disableModelInvocation?: boolean // 禁止模型调用
|
||||
userInvocable?: boolean
|
||||
loadedFrom?: 'skills' | 'plugin' | 'managed' | 'bundled' | 'mcp' | 'commands_DEPRECATED'
|
||||
kind?: 'workflow'
|
||||
immediate?: boolean // 立即执行，不等待队列
|
||||
isSensitive?: boolean // 参数脱敏
|
||||
source?: 'builtin' | 'plugin' | 'bundled' | 'mcp'
|
||||
}
|
||||
```
|
||||
|
||||
### PromptCommand
|
||||
|
||||
```typescript
|
||||
type PromptCommand = {
|
||||
type: 'prompt'
|
||||
source: 'builtin' | 'plugin' | 'bundled' | 'mcp'
|
||||
progressMessage: string
|
||||
contentLength: number // 0 = 动态内容
|
||||
allowedTools?: string[]
|
||||
getPromptForCommand: (args, context) => Promise<ContentBlockParam[]>
|
||||
}
|
||||
```
|
||||
|
||||
### LocalCommand
|
||||
|
||||
```typescript
|
||||
type LocalCommand = {
|
||||
type: 'local'
|
||||
supportsNonInteractive?: boolean
|
||||
call: LocalCommandCall // (args, context) => Promise<LocalCommandResult>
|
||||
}
|
||||
```
|
||||
|
||||
### LocalJSXCommand
|
||||
|
||||
```typescript
|
||||
type LocalJSXCommand = {
|
||||
type: 'local-jsx'
|
||||
load: () => Promise<{ call: LocalJSXCommandCall }>
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 命令注册机制
|
||||
|
||||
### 主入口：`src/commands.ts`
|
||||
|
||||
所有内置命令在 `src/commands.ts` 中以 **静态 import** 方式导入，然后通过 `COMMANDS()` memoize 函数组装。
|
||||
|
||||
```typescript
|
||||
// commands.ts 中的核心结构
|
||||
const COMMANDS = memoize((): Command[] => [
|
||||
addDir, advisor, agents, branch, btw, chrome, clear, color,
|
||||
compact, config, copy, desktop, context, cost, diff, doctor,
|
||||
effort, exit, fast, files, heapDump, help, ide, init, keybindings,
|
||||
mcp, memory, mobile, model, outputStyle, plugin, resume, session,
|
||||
skills, status, theme, review, ultrareview, ...,
|
||||
// 条件命令
|
||||
...(webCmd ? [webCmd] : []),
|
||||
...(buddy ? [buddy] : []),
|
||||
...(bridge ? [bridge] : []),
|
||||
...(voiceCommand ? [voiceCommand] : []),
|
||||
// 内部命令（仅 ant 用户）
|
||||
...(process.env.USER_TYPE === 'ant' ? INTERNAL_ONLY_COMMANDS : []),
|
||||
])
|
||||
```
|
||||
|
||||
### 命令发现层次（5 层叠加）
|
||||
|
||||
`getCommands(cwd)` 按以下优先级组装最终命令列表：
|
||||
|
||||
```
|
||||
1. bundledSkills — 内置捆绑 Skills（registerBundledSkill 注册）
|
||||
2. builtinPluginSkills — 内置插件提供的 Skills
|
||||
3. skillDirCommands — 项目/用户 skills/ 目录中发现的 Markdown Skills
|
||||
4. workflowCommands — Workflow 脚本生成的命令
|
||||
5. pluginCommands — 第三方插件提供的命令
|
||||
6. pluginSkills — 插件提供的 Skills
|
||||
7. COMMANDS() — 内置命令（最高优先级，覆盖前面同名命令）
|
||||
```
|
||||
|
||||
```typescript
|
||||
export async function getCommands(cwd: string): Promise<Command[]> {
|
||||
const allCommands = await loadAllCommands(cwd)
|
||||
// 过滤：availability + isEnabled
|
||||
const baseCommands = allCommands.filter(
|
||||
_ => meetsAvailabilityRequirement(_) && isCommandEnabled(_),
|
||||
)
|
||||
// 动态 Skills 插入到 plugin skills 之后、builtin 之前
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 加载来源（loadedFrom 枚举）
|
||||
|
||||
| 值 | 含义 |
|
||||
|---|------|
|
||||
| `skills` | 从 `skills/` 目录加载的 Markdown Skill |
|
||||
| `plugin` | 从插件加载 |
|
||||
| `managed` | 托管路径加载 |
|
||||
| `bundled` | 随 CLI 捆绑的内置 Skill |
|
||||
| `mcp` | MCP 服务器提供的 Skill |
|
||||
| `commands_DEPRECATED` | 旧版 `commands/` 目录（已废弃） |
|
||||
|
||||
---
|
||||
|
||||
## 3. 全部命令清单
|
||||
|
||||
### 3.1 内置斜杠命令（60+）
|
||||
|
||||
按目录列出：
|
||||
|
||||
| 命令 | 目录 | 类型 | 说明 |
|
||||
|------|------|------|------|
|
||||
| `/add-dir` | `add-dir/` | local-jsx | 添加额外工作目录 |
|
||||
| `/agents` | `agents/` | local-jsx | 多 agent 管理 |
|
||||
| `/branch` | `branch/` | local | 分支操作 |
|
||||
| `/btw` | `btw/` | local-jsx | 快速笔记 |
|
||||
| `/chrome` | `chrome/` | local-jsx | Chrome 浏览器集成 |
|
||||
| `/clear` | `clear/` | local | 清空对话 |
|
||||
| `/color` | `color/` | local | 切换 agent 颜色 |
|
||||
| `/compact` | `compact/` | local | 压缩对话历史（保留摘要） |
|
||||
| `/config` | `config/` | local-jsx | 打开配置面板 (aliases: `settings`) |
|
||||
| `/copy` | `copy/` | local-jsx | 复制最后一条消息 |
|
||||
| `/cost` | `cost/` | local-jsx | 显示会话费用 |
|
||||
| `/desktop` | `desktop/` | local-jsx | 桌面应用集成 |
|
||||
| `/diff` | `diff/` | local-jsx | 查看代码差异 |
|
||||
| `/doctor` | `doctor/` | local-jsx | 诊断安装和配置 |
|
||||
| `/effort` | `effort/` | local-jsx | 设置推理努力级别 |
|
||||
| `/exit` | `exit/` | local-jsx | 退出 REPL (aliases: `quit`) |
|
||||
| `/export` | `export/` | local-jsx | 导出会话 |
|
||||
| `/extra-usage` | `extra-usage/` | local-jsx | 额外使用量报告 |
|
||||
| `/fast` | `fast/` | local-jsx | 快速模式切换 |
|
||||
| `/feedback` | `feedback/` | local-jsx | 发送反馈 |
|
||||
| `/files` | `files/` | local | 列出跟踪文件 |
|
||||
| `/heapdump` | `heapdump/` | local | 堆转储（调试用） |
|
||||
| `/help` | `help/` | local-jsx | 显示帮助和可用命令 |
|
||||
| `/hooks` | `hooks/` | local-jsx | 管理 hooks |
|
||||
| `/ide` | `ide/` | local-jsx | IDE 集成 |
|
||||
| `/init` | `init.ts` | prompt | 初始化 CLAUDE.md |
|
||||
| `/install` | `install.tsx` | local-jsx | 安装配置 |
|
||||
| `/install-github-app` | `install-github-app/` | local-jsx | 安装 GitHub App |
|
||||
| `/install-slack-app` | `install-slack-app/` | local-jsx | 安装 Slack App |
|
||||
| `/keybindings` | `keybindings/` | local | 管理键绑定 |
|
||||
| `/login` | `login/` | local-jsx | 登录 Anthropic 账号 |
|
||||
| `/logout` | `logout/` | local-jsx | 登出 |
|
||||
| `/mcp` | `mcp/` | local-jsx | 管理 MCP 服务器 |
|
||||
| `/memory` | `memory/` | local-jsx | 管理记忆文件 |
|
||||
| `/mobile` | `mobile/` | local-jsx | 移动端 QR 码 |
|
||||
| `/model` | `model/` | local-jsx | 设置 AI 模型 |
|
||||
| `/output-style` | `output-style/` | local-jsx | 输出样式 |
|
||||
| `/passes` | `passes/` | local-jsx | 通行证管理 |
|
||||
| `/permissions` | `permissions/` | local-jsx | 权限管理 |
|
||||
| `/plan` | `plan/` | local-jsx | 计划模式 |
|
||||
| `/plugin` | `plugin/` | local-jsx | 插件管理 |
|
||||
| `/privacy-settings` | `privacy-settings/` | local-jsx | 隐私设置 |
|
||||
| `/rate-limit-options` | `rate-limit-options/` | local-jsx | 速率限制选项 |
|
||||
| `/release-notes` | `release-notes/` | local | 显示版本说明 |
|
||||
| `/reload-plugins` | `reload-plugins/` | local | 重新加载插件 |
|
||||
| `/remote-env` | `remote-env/` | local-jsx | 远程环境 |
|
||||
| `/rename` | `rename/` | local | 重命名会话 |
|
||||
| `/resume` | `resume/` | local-jsx | 恢复会话 |
|
||||
| `/rewind` | `rewind/` | local-jsx | 回退对话 |
|
||||
| `/sandbox-toggle` | `sandbox-toggle/` | local-jsx | 沙箱切换 |
|
||||
| `/session` | `session/` | local-jsx | 会话管理 |
|
||||
| `/skills` | `skills/` | local-jsx | Skills 管理 |
|
||||
| `/stats` | `stats/` | local-jsx | 统计信息 |
|
||||
| `/status` | `status/` | local-jsx | 显示状态（版本、模型、账号等） |
|
||||
| `/stickers` | `stickers/` | local | 贴纸 |
|
||||
| `/tag` | `tag/` | local-jsx | 标签管理 |
|
||||
| `/tasks` | `tasks/` | local-jsx | 任务管理 |
|
||||
| `/terminalSetup` | `terminalSetup/` | local-jsx | 终端设置 |
|
||||
| `/theme` | `theme/` | local-jsx | 切换主题 |
|
||||
| `/thinkback` | `thinkback/` | local-jsx | Thinkback 功能 |
|
||||
| `/thinkback-play` | `thinkback-play/` | local-jsx | Thinkback 播放 |
|
||||
| `/upgrade` | `upgrade/` | local-jsx | 升级 |
|
||||
| `/usage` | `usage/` | local-jsx | 使用量 |
|
||||
| `/vim` | `vim/` | local | Vim 模式切换 |
|
||||
|
||||
### 3.2 Prompt 型命令
|
||||
|
||||
| 命令 | 文件 | 说明 |
|
||||
|------|------|------|
|
||||
| `/commit` | `commit.ts` | 创建 git commit（展开为 prompt 让模型执行） |
|
||||
| `/review` | `review.ts` | Review PR（本地 prompt 模式） |
|
||||
| `/init` | `init.ts` | 分析代码库创建 CLAUDE.md |
|
||||
| `/advisor` | `advisor.ts` | 提供建议 |
|
||||
| `/security-review` | `security-review.ts` | 安全审查 |
|
||||
| `/insights` | (lazy import) | 会话分析报告（113KB 大模块，懒加载） |
|
||||
|
||||
### 3.3 条件命令（Feature Flag 门控）
|
||||
|
||||
```typescript
|
||||
// 基于 bun:bundle feature flags
|
||||
const proactive = feature('PROACTIVE') || feature('KAIROS') ? ... : null
|
||||
const briefCommand = feature('KAIROS') || feature('KAIROS_BRIEF') ? ... : null
|
||||
const assistantCommand = feature('KAIROS') ? ... : null
|
||||
const bridge = feature('BRIDGE_MODE') ? ... : null
|
||||
const voiceCommand = feature('VOICE_MODE') ? ... : null
|
||||
const workflowsCmd = feature('WORKFLOW_SCRIPTS') ? ... : null
|
||||
const webCmd = feature('CCR_REMOTE_SETUP') ? ... : null
|
||||
const ultraplan = feature('ULTRAPLAN') ? ... : null
|
||||
const torch = feature('TORCH') ? ... : null
|
||||
const peersCmd = feature('UDS_INBOX') ? ... : null
|
||||
const forkCmd = feature('FORK_SUBAGENT') ? ... : null
|
||||
const buddy = feature('BUDDY') ? ... : null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心命令详细分析
|
||||
|
||||
### `/commit` — Git Commit
|
||||
|
||||
**文件**: `src/commands/commit.ts`
|
||||
**类型**: `prompt`
|
||||
**源**: `builtin`
|
||||
|
||||
**机制**:
|
||||
- 展开为一段 prompt，注入当前 `git status`、`git diff HEAD`、`git log` 信息
|
||||
- 模型分析变更并执行 `git add` + `git commit`
|
||||
- 限制允许的工具：`Bash(git add:*)`, `Bash(git status:*)`, `Bash(git commit:*)`
|
||||
- 使用 HEREDOC 语法创建 commit message
|
||||
- 内置安全协议：禁止 `--amend`、禁止跳过 hooks、禁止提交包含密钥的文件
|
||||
|
||||
### `/review` — PR Review
|
||||
|
||||
**文件**: `src/review.ts`
|
||||
**类型**: `prompt` (本地) + `local-jsx` (ultrareview)
|
||||
**源**: `builtin`
|
||||
|
||||
**机制**:
|
||||
- `/review`：本地 prompt 模式，使用 `gh` CLI 查看 PR、获取 diff、生成代码审查
|
||||
- `/ultrareview`：`local-jsx` 类型，远程 Claude Code on the Web 模式
|
||||
- `ultrareview` 有 `isEnabled()` 检查，受功能开关控制
|
||||
- 超出免费额度时弹出 overage dialog (`UltrareviewOverageDialog.tsx`)
|
||||
|
||||
### `/compact` — 压缩对话
|
||||
|
||||
**文件**: `src/commands/compact/index.ts` + `compact.ts`
|
||||
**类型**: `local`
|
||||
**源**: `builtin`
|
||||
|
||||
**机制**:
|
||||
- 调用 `compactConversation()` 服务压缩对话历史
|
||||
- 支持自定义压缩指令：`/compact [instructions]`
|
||||
- 支持 session memory compaction（无自定义指令时优先）
|
||||
- 支持 microcompact（短对话）
|
||||
- 支持 reactive compact（feature flag）
|
||||
- 运行 post-compact cleanup 和 pre-compact hooks
|
||||
- `supportsNonInteractive: true`
|
||||
|
||||
### `/config` — 配置面板
|
||||
|
||||
**文件**: `src/commands/config/index.ts` + `config.tsx`
|
||||
**类型**: `local-jsx`
|
||||
**别名**: `settings`
|
||||
|
||||
**机制**:
|
||||
- 懒加载 React/Ink UI 组件
|
||||
- 渲染交互式配置界面
|
||||
|
||||
### `/mcp` — MCP 服务器管理
|
||||
|
||||
**文件**: `src/commands/mcp/index.ts` + `mcp.tsx`, `addCommand.ts`, `xaaIdpCommand.ts`
|
||||
**类型**: `local-jsx`
|
||||
**源**: `builtin`
|
||||
|
||||
**机制**:
|
||||
- `immediate: true` — 立即执行不等待队列
|
||||
- 支持子命令：`enable`, `disable`
|
||||
- UI 组件管理 MCP server 的增删改查
|
||||
|
||||
### `/login` — 登录
|
||||
|
||||
**文件**: `src/commands/login/index.ts` + `login.tsx`
|
||||
**类型**: `local-jsx`
|
||||
**源**: `builtin`
|
||||
|
||||
**机制**:
|
||||
- 动态 description：根据当前认证状态显示不同文字
|
||||
- 使用工厂函数 `export default () => ({...})` — 可延迟评估 `hasAnthropicApiKeyAuth()`
|
||||
- 有 `isEnabled()` 检查：`DISABLE_LOGIN_COMMAND` 环境变量可禁用
|
||||
- 只在非 3P 服务模式下出现（在 `COMMANDS()` 中条件包含）
|
||||
|
||||
### `/doctor` — 诊断
|
||||
|
||||
**文件**: `src/commands/doctor/index.ts` + `doctor.tsx`
|
||||
**类型**: `local-jsx`
|
||||
**源**: `builtin`
|
||||
|
||||
**机制**:
|
||||
- 诊断安装和设置
|
||||
- `DISABLE_DOCTOR_COMMAND` 环境变量可禁用
|
||||
|
||||
### `/status` — 状态
|
||||
|
||||
**文件**: `src/commands/status/index.ts` + `status.tsx`
|
||||
**类型**: `local-jsx`
|
||||
**源**: `builtin`
|
||||
|
||||
**机制**:
|
||||
- `immediate: true`
|
||||
- 显示版本、模型、账号、API 连通性、工具状态
|
||||
|
||||
### `/help` — 帮助
|
||||
|
||||
**文件**: `src/commands/help/index.ts` + `help.tsx`
|
||||
**类型**: `local-jsx`
|
||||
|
||||
---
|
||||
|
||||
## 5. 命令目录结构模式
|
||||
|
||||
### 标准模式（目录型）
|
||||
|
||||
```
|
||||
commands/<command-name>/
|
||||
├── index.ts # 导出 Command 定义（类型、名称、描述、load 函数）
|
||||
├── <command-name>.tsx # 实现文件（local-jsx 型通常为 .tsx，local 型为 .ts）
|
||||
└── ...辅助文件
|
||||
```
|
||||
|
||||
`index.ts` 的典型结构：
|
||||
|
||||
```typescript
|
||||
import type { Command } from '../../commands.js'
|
||||
|
||||
const myCommand = {
|
||||
type: 'local-jsx', // 或 'local' 或 'prompt'
|
||||
name: 'mycommand',
|
||||
description: 'Description text',
|
||||
load: () => import('./mycommand.js'), // 懒加载实现
|
||||
// prompt 型需要 getPromptForCommand
|
||||
// local 型需要 call
|
||||
} satisfies Command
|
||||
|
||||
export default myCommand
|
||||
```
|
||||
|
||||
### 简单模式（单文件型）
|
||||
|
||||
```
|
||||
commands/
|
||||
├── commit.ts # 单文件导出 Command（prompt 型常见）
|
||||
├── advisor.ts
|
||||
├── security-review.ts
|
||||
├── version.ts
|
||||
├── brief.ts
|
||||
└── init.ts
|
||||
```
|
||||
|
||||
这些直接在 `commands.ts` 中 import，没有独立目录。
|
||||
|
||||
### 复杂模式（多子文件型）
|
||||
|
||||
```
|
||||
commands/plugin/ # 最复杂的命令之一
|
||||
├── index.tsx
|
||||
├── plugin.tsx
|
||||
├── parseArgs.ts
|
||||
├── ValidatePlugin.tsx
|
||||
├── DiscoverPlugins.tsx
|
||||
├── BrowseMarketplace.tsx
|
||||
├── AddMarketplace.tsx
|
||||
├── ManagePlugins.tsx
|
||||
├── ManageMarketplaces.tsx
|
||||
├── PluginOptionsFlow.tsx
|
||||
├── PluginOptionsDialog.tsx
|
||||
├── PluginSettings.tsx
|
||||
├── PluginTrustWarning.tsx
|
||||
├── PluginErrors.tsx
|
||||
├── pluginDetailsHelpers.tsx
|
||||
├── UnifiedInstalledCell.tsx
|
||||
└── usePagination.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Skill 系统
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
src/skills/
|
||||
├── index.ts # 入口（可能调用 registerBundledSkill）
|
||||
├── bundledSkills.ts # 注册捆绑 Skill 的 API
|
||||
├── loadSkillsDir.ts # 从文件系统发现 Skill（1007 行）
|
||||
├── mcpSkillBuilders.ts # 从 MCP 注册 Skill
|
||||
└── bundled/ # 内置捆绑的 Skills
|
||||
├── batch.ts
|
||||
├── claudeApi.ts
|
||||
├── claudeApiContent.ts
|
||||
├── claudeInChrome.ts
|
||||
├── debug.ts
|
||||
├── index.ts
|
||||
├── keybindings.ts
|
||||
├── loop.ts
|
||||
├── loremIpsum.ts
|
||||
├── remember.ts
|
||||
├── scheduleRemoteAgents.ts
|
||||
├── simplify.ts
|
||||
├── skillify.ts
|
||||
├── stuck.ts
|
||||
├── updateConfig.ts
|
||||
├── verify.ts
|
||||
└── verifyContent.ts
|
||||
```
|
||||
|
||||
### Skill 发现流程
|
||||
|
||||
`loadSkillsDir.ts` 实现了完整的 Skill 发现管道：
|
||||
|
||||
1. **扫描目录**: 搜索以下路径的 `skills/` 子目录：
|
||||
- 项目目录 `.claude/skills/`
|
||||
- 用户配置目录 `~/.claude/skills/`
|
||||
- 托管路径（managed）
|
||||
|
||||
2. **解析 Markdown**: 读取 `.md` 文件，解析 frontmatter
|
||||
|
||||
3. **Frontmatter 字段**:
|
||||
- `name` — 命令名称
|
||||
- `description` — 命令描述
|
||||
- `aliases` — 别名
|
||||
- `whenToUse` — 使用场景
|
||||
- `allowedTools` — 允许的工具
|
||||
- `model` — 指定模型
|
||||
- `hooks` — Hooks 配置
|
||||
- `argumentHint` — 参数提示
|
||||
|
||||
4. **生成 Command**: 将 Markdown Skill 转换为 `Command` 类型（`type: 'prompt'`）
|
||||
|
||||
### 捆绑 Skill 注册
|
||||
|
||||
```typescript
|
||||
// bundledSkills.ts
|
||||
export function registerBundledSkill(definition: BundledSkillDefinition): void {
|
||||
const command: Command = {
|
||||
type: 'prompt',
|
||||
name: definition.name,
|
||||
description: definition.description,
|
||||
loadedFrom: 'bundled',
|
||||
// ...
|
||||
}
|
||||
bundledSkills.push(command)
|
||||
}
|
||||
```
|
||||
|
||||
捆绑 Skills 支持：
|
||||
- `files` — 附加引用文件，首次调用时提取到磁盘
|
||||
- `hooks` — 绑定的 hooks
|
||||
- `context` — `'inline'` 或 `'fork'` 上下文模式
|
||||
- `agent` — 指定 agent
|
||||
|
||||
---
|
||||
|
||||
## 7. 插件系统
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
src/plugins/
|
||||
├── builtinPlugins.ts # 内置插件注册表
|
||||
├── bundled/
|
||||
│ └── index.ts # 捆绑插件入口
|
||||
└── (通过 loadPluginCommands.ts 加载第三方插件)
|
||||
```
|
||||
|
||||
### 插件 vs Skill 的区别
|
||||
|
||||
| 方面 | Skill | Plugin |
|
||||
|------|-------|--------|
|
||||
| 来源 | `skills/` 目录中的 `.md` 文件 | 插件市场或内置 |
|
||||
| 注册 | 自动发现 | 需要启用 |
|
||||
| UI | 无单独 UI | `/plugin` 命令管理 |
|
||||
| ID 格式 | `<name>` | `<name>@<marketplace>` (内置为 `<name>@builtin`) |
|
||||
| 提供内容 | 仅 prompt 命令 | Skills + Hooks + MCP 服务器 |
|
||||
|
||||
### 内置插件 API
|
||||
|
||||
```typescript
|
||||
// builtinPlugins.ts
|
||||
export function registerBuiltinPlugin(definition: BuiltinPluginDefinition): void
|
||||
export function isBuiltinPluginId(pluginId: string): boolean
|
||||
export function getBuiltinPlugins(): { enabled: LoadedPlugin[], disabled: LoadedPlugin[] }
|
||||
export function getBuiltinPluginSkillCommands(): Command[]
|
||||
```
|
||||
|
||||
### 命令优先级（插件侧）
|
||||
|
||||
```
|
||||
pluginCommands (插件的 slash commands)
|
||||
↓
|
||||
pluginSkills (插件的 skills，prompt 型)
|
||||
↓
|
||||
COMMANDS() (内置命令，最终覆盖)
|
||||
```
|
||||
|
||||
### 插件命令加载
|
||||
|
||||
```typescript
|
||||
// src/utils/plugins/loadPluginCommands.ts
|
||||
export function getPluginCommands(): Promise<Command[]>
|
||||
export function getPluginSkills(): Promise<Command[]>
|
||||
export function clearPluginCommandCache(): void
|
||||
export function clearPluginSkillsCache(): void
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 键绑定系统
|
||||
|
||||
### 目录结构
|
||||
|
||||
```
|
||||
src/keybindings/
|
||||
├── defaultBindings.ts # 默认绑定定义
|
||||
├── loadUserBindings.ts # 加载用户自定义绑定
|
||||
├── parser.ts # 解析按键语法
|
||||
├── match.ts # 按键匹配逻辑
|
||||
├── resolver.ts # 解析按键到动作
|
||||
├── schema.ts # JSON Schema 验证
|
||||
├── validate.ts # 绑定验证
|
||||
├── template.ts # 模板
|
||||
├── shortcutFormat.ts # 快捷键显示格式
|
||||
├── reservedShortcuts.ts # 保留快捷键（不可重映射）
|
||||
├── KeybindingContext.tsx # React Context
|
||||
├── KeybindingProviderSetup.tsx # Provider 设置
|
||||
├── useKeybinding.ts # Hook：注册键绑定
|
||||
└── useShortcutDisplay.ts # Hook：显示快捷键
|
||||
```
|
||||
|
||||
### 默认绑定
|
||||
|
||||
`defaultBindings.ts` 定义了默认键绑定，按上下文分组：
|
||||
|
||||
```typescript
|
||||
export const DEFAULT_BINDINGS: KeybindingBlock[] = [
|
||||
{
|
||||
context: 'Global',
|
||||
bindings: {
|
||||
'ctrl+c': 'app:interrupt',
|
||||
'ctrl+d': 'app:exit',
|
||||
'ctrl+l': 'app:redraw',
|
||||
'ctrl+t': 'app:toggleTodos',
|
||||
'ctrl+o': 'app:toggleTranscript',
|
||||
'ctrl+r': 'history:search',
|
||||
// ...
|
||||
}
|
||||
},
|
||||
// 更多上下文...
|
||||
]
|
||||
```
|
||||
|
||||
### 解析流程
|
||||
|
||||
1. `parser.ts` — 解析按键字符串（如 `"ctrl+shift+f"`）为结构化对象
|
||||
2. `match.ts` — 匹配实际输入与绑定
|
||||
3. `resolver.ts` — 解析按键到动作（支持和弦序列）
|
||||
4. `match.ts` 中的 `matchesBinding()` — 核心匹配逻辑
|
||||
|
||||
### 上下文感知
|
||||
|
||||
键绑定支持上下文切换：
|
||||
- `Global` — 全局上下文
|
||||
- `Chat` — 聊天输入模式
|
||||
- 更多上下文...
|
||||
|
||||
### 用户自定义
|
||||
|
||||
`loadUserBindings.ts` 加载用户自定义绑定，覆盖默认值：
|
||||
- 用户绑定优先（last one wins）
|
||||
- `reservedShortcuts.ts` 定义不可重映射的快捷键（如 `ctrl+c`, `ctrl+d`）
|
||||
|
||||
---
|
||||
|
||||
## 9. 远程安全命令
|
||||
|
||||
### REMOTE_SAFE_COMMANDS
|
||||
|
||||
这些命令在 `--remote` 模式下安全可用：
|
||||
|
||||
```typescript
|
||||
export const REMOTE_SAFE_COMMANDS = new Set([
|
||||
session, exit, clear, help, theme, color, vim,
|
||||
cost, usage, copy, btw, feedback, plan, keybindings,
|
||||
statusline, stickers, mobile,
|
||||
])
|
||||
```
|
||||
|
||||
### BRIDGE_SAFE_COMMANDS
|
||||
|
||||
这些 `local` 型命令可通过 Remote Control bridge 执行：
|
||||
|
||||
```typescript
|
||||
export const BRIDGE_SAFE_COMMANDS = new Set([
|
||||
compact, clear, cost, summary, releaseNotes, files,
|
||||
])
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 命令缓存管理
|
||||
|
||||
```typescript
|
||||
// 清除命令缓存（保留 skill 缓存）
|
||||
export function clearCommandMemoizationCaches(): void
|
||||
|
||||
// 清除所有缓存（命令 + 插件 + skill）
|
||||
export function clearCommandsCache(): void
|
||||
```
|
||||
|
||||
所有加载函数使用 `lodash-es/memoize` 缓存。`getCommands()` 在每次调用时重新评估 `availability` 和 `isEnabled()` 以支持认证变更（如 `/login` 后）。
|
||||
|
||||
---
|
||||
|
||||
## 11. 命令查找 API
|
||||
|
||||
```typescript
|
||||
// 查找命令（按名称或别名）
|
||||
export function findCommand(commandName: string, commands: Command[]): Command | undefined
|
||||
|
||||
// 获取命令（找不到抛异常）
|
||||
export function getCommand(commandName: string, commands: Command[]): Command
|
||||
|
||||
// 格式化描述（带来源标注）
|
||||
export function formatDescriptionWithSource(cmd: Command): string
|
||||
|
||||
// 检查是否桥接安全
|
||||
export function isBridgeSafeCommand(cmd: Command): boolean
|
||||
|
||||
// 检查是否远程安全
|
||||
export function filterCommandsForRemoteMode(commands: Command[]): Command[]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 命令执行流程总结
|
||||
|
||||
```
|
||||
用户输入 /commit
|
||||
↓
|
||||
REPL 解析命令名，调用 findCommand('commit', commands)
|
||||
↓
|
||||
找到 Command { type: 'prompt', name: 'commit', ... }
|
||||
↓
|
||||
调用 getPromptForCommand(args, context)
|
||||
↓
|
||||
返回 ContentBlockParam[]（含 git status/diff 信息的 prompt）
|
||||
↓
|
||||
将 prompt 发送给 AI 模型
|
||||
↓
|
||||
模型执行允许的工具（git add, git commit）
|
||||
↓
|
||||
命令完成
|
||||
```
|
||||
|
||||
对于 `local-jsx` 命令：
|
||||
|
||||
```
|
||||
用户输入 /config
|
||||
↓
|
||||
REPL 解析命令名，找到 Command { type: 'local-jsx', load: () => import('./config.js') }
|
||||
↓
|
||||
调用 load() 获取模块
|
||||
↓
|
||||
调用 module.call(onDone, context, args)
|
||||
↓
|
||||
渲染 React/Ink 组件
|
||||
↓
|
||||
用户交互完成后调用 onDone(result)
|
||||
↓
|
||||
命令完成
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附录：内部命令（ANT 用户专用）
|
||||
|
||||
```typescript
|
||||
export const INTERNAL_ONLY_COMMANDS = [
|
||||
backfillSessions, breakCache, bughunter, commit, commitPushPr,
|
||||
ctx_viz, goodClaude, issue, initVerifiers, mockLimits, bridgeKick,
|
||||
version, resetLimits, resetLimitsNonInteractive, onboarding,
|
||||
share, summary, teleport, antTrace, perfIssue, env, oauthRefresh,
|
||||
debugToolCall, agentsPlatform, autofixPr,
|
||||
]
|
||||
```
|
||||
|
||||
这些命令仅在 `USER_TYPE === 'ant'` 时可见。
|
||||
676
docs/ARCHITECTURE-COMPONENTS.md
Normal file
676
docs/ARCHITECTURE-COMPONENTS.md
Normal file
@@ -0,0 +1,676 @@
|
||||
# Claude Code 组件架构文档
|
||||
|
||||
> 基于 `/src/components/` 目录的实际代码分析
|
||||
|
||||
## 概览
|
||||
|
||||
- **总文件数**: 389 个文件（`.tsx` + `.ts`）
|
||||
- **目录结构**: 40+ 子目录
|
||||
- **渲染引擎**: [Ink](https://github.com/vadimdemedes/ink)（React 终端渲染器）
|
||||
- **编译器**: React Compiler（`react/compiler-runtime` 自动 memo 化）
|
||||
- **状态管理**: 自定义 `useAppState` / `useSetAppState`（基于 `AppState` context）
|
||||
- **布局模式**: 全屏模式（`FullscreenLayout`）+ 内联模式
|
||||
|
||||
---
|
||||
|
||||
## 1. 主应用组件
|
||||
|
||||
### `App.tsx` — 顶层 Provider 嵌套
|
||||
|
||||
```
|
||||
FpsMetricsProvider
|
||||
└── StatsProvider
|
||||
└── AppStateProvider
|
||||
└── {children} (REPL 内容)
|
||||
```
|
||||
|
||||
提供三个上下文层：FPS 指标、统计信息、应用状态。本身无 UI，纯 Provider 包装。
|
||||
|
||||
### REPL 与主布局
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`FullscreenLayout.tsx`** | 全屏布局：scrollable 区（消息列表）+ bottom 区（输入框）+ overlay/modal 区 |
|
||||
| **`Messages.tsx`** | 消息列表主容器。负责消息过滤、重排、分组、构建 lookups，渲染 LogoHeader + MessageRow 列表 |
|
||||
| **`VirtualMessageList.tsx`** | 虚拟滚动消息列表。管理滚动位置、搜索导航（`JumpHandle`）、sticky header |
|
||||
| **`MessageRow.tsx`** | 单行消息包装。管理消息折叠/展开状态、model 标签、时间戳 |
|
||||
| **`Message.tsx`** | 消息类型分发器。根据消息类型渲染对应的子组件 |
|
||||
| **`MessageResponse.tsx`** | 助手回复渲染（流式输出） |
|
||||
| **`Spinner.tsx`** | 加载动画。显示旋转字符 + 任务列表 + 闪烁文字 |
|
||||
|
||||
### 数据流
|
||||
|
||||
```
|
||||
AppState → Messages → VirtualMessageList → MessageRow → Message → 具体消息类型组件
|
||||
↓
|
||||
(permissions, tool use, etc.)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 消息渲染组件 (`messages/`)
|
||||
|
||||
### 助手消息
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`AssistantTextMessage.tsx`** | 助手文本回复（Markdown 渲染） |
|
||||
| **`AssistantThinkingMessage.tsx`** | 助手思考过程（可折叠/展开） |
|
||||
| **`AssistantRedactedThinkingMessage.tsx`** | 加密思考块 |
|
||||
| **`AssistantToolUseMessage.tsx`** | 工具调用展示（紧凑/详细模式） |
|
||||
|
||||
### 用户消息
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`UserTextMessage.tsx`** | 用户文本输入 |
|
||||
| **`UserPromptMessage.tsx`** | 用户 prompt 展示 |
|
||||
| **`UserImageMessage.tsx`** | 用户上传图片 |
|
||||
| **`UserBashInputMessage.tsx`** | 用户 bash 输入 |
|
||||
| **`UserBashOutputMessage.tsx`** | bash 输出结果 |
|
||||
| **`UserChannelMessage.tsx`** | 频道消息 |
|
||||
| **`UserCommandMessage.tsx`** | 用户命令 |
|
||||
| **`UserPlanMessage.tsx`** | 计划模式消息 |
|
||||
| **`UserTeammateMessage.tsx`** | 队友消息 |
|
||||
| **`UserMemoryInputMessage.tsx`** | Memory 输入 |
|
||||
| **`UserResourceUpdateMessage.tsx`** | 资源更新 |
|
||||
| **`UserLocalCommandOutputMessage.tsx`** | 本地命令输出 |
|
||||
| **`UserAgentNotificationMessage.tsx`** | Agent 通知消息 |
|
||||
|
||||
### 工具结果消息 (`UserToolResultMessage/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`UserToolResultMessage.tsx`** | 工具结果主容器（分发器） |
|
||||
| **`UserToolSuccessMessage.tsx`** | 成功结果 |
|
||||
| **`UserToolErrorMessage.tsx`** | 错误结果 |
|
||||
| **`UserToolRejectMessage.tsx`** | 拒绝结果 |
|
||||
| **`UserToolCanceledMessage.tsx`** | 取消结果 |
|
||||
| **`RejectedToolUseMessage.tsx`** | 被拒绝的工具调用 |
|
||||
| **`RejectedPlanMessage.tsx`** | 被拒绝的计划 |
|
||||
|
||||
### 系统消息
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`SystemTextMessage.tsx`** | 系统文本消息 |
|
||||
| **`SystemAPIErrorMessage.tsx`** | API 错误消息 |
|
||||
| **`ShutdownMessage.tsx`** | 关闭/退出消息 |
|
||||
| **`RateLimitMessage.tsx`** | 速率限制消息 |
|
||||
|
||||
### 聚合/折叠消息
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`CollapsedReadSearchContent.tsx`** | 折叠的 read/search 组（灰点 + "Reading…"） |
|
||||
| **`GroupedToolUseContent.tsx`** | 分组工具调用 |
|
||||
| **`CompactBoundaryMessage.tsx`** | Compact 边界标记 |
|
||||
| **`HookProgressMessage.tsx`** | Hook 进度 |
|
||||
| **`PlanApprovalMessage.tsx`** | 计划审批 |
|
||||
| **`TaskAssignmentMessage.tsx`** | 任务分配 |
|
||||
| **`AdvisorMessage.tsx`** | Advisor 消息 |
|
||||
| **`AttachmentMessage.tsx`** | 附件消息 |
|
||||
| **`HighlightedThinkingText.tsx`** | 高亮思考文本 |
|
||||
|
||||
### 辅助文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| **`nullRenderingAttachments.ts`** | 标记不渲染的附件 |
|
||||
| **`teamMemCollapsed.tsx`** | 队友消息折叠逻辑 |
|
||||
| **`teamMemSaved.ts`** | 队友消息保存状态 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 权限对话框组件 (`permissions/`)
|
||||
|
||||
### 核心组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`PermissionRequest.tsx`** | 权限请求分发器。根据工具类型选择对应的权限请求组件 |
|
||||
| **`PermissionDialog.tsx`** | 权限对话框容器（标题 + subtitle + children） |
|
||||
| **`PermissionPrompt.tsx`** | 权限提示（带快捷键操作） |
|
||||
| **`PermissionExplanation.tsx`** | 权限解释说明 |
|
||||
| **`PermissionRequestTitle.tsx`** | 权限请求标题 |
|
||||
| **`PermissionRuleExplanation.tsx`** | 权限规则解释 |
|
||||
| **`PermissionDecisionDebugInfo.tsx`** | 调试信息 |
|
||||
| **`FallbackPermissionRequest.tsx`** | 通用兜底权限请求 |
|
||||
| **`WorkerBadge.tsx`** | Worker 标记 |
|
||||
| **`WorkerPendingPermission.tsx`** | 待处理 Worker 权限 |
|
||||
| **`SandboxPermissionRequest.tsx`** | 沙箱权限 |
|
||||
|
||||
### 工具级权限请求
|
||||
|
||||
| 子目录/组件 | 工具 |
|
||||
|-------------|------|
|
||||
| **`BashPermissionRequest/`** | Bash 命令执行权限 |
|
||||
| **`PowerShellPermissionRequest/`** | PowerShell 权限 |
|
||||
| **`FileEditPermissionRequest/`** | 文件编辑权限 |
|
||||
| **`FileWritePermissionRequest/`** | 文件写入权限（含 diff） |
|
||||
| **`FilePermissionDialog/`** | 通用文件权限对话框（含 hook、IDE diff 配置） |
|
||||
| **`FilesystemPermissionRequest/`** | 文件系统操作权限 |
|
||||
| **`NotebookEditPermissionRequest/`** | Notebook 编辑权限 |
|
||||
| **`SedEditPermissionRequest/`** | Sed 编辑权限 |
|
||||
| **`WebFetchPermissionRequest/`** | 网络请求权限 |
|
||||
| **`SkillPermissionRequest/`** | Skill 执行权限 |
|
||||
| **`ComputerUseApproval/`** | Computer Use 权限 |
|
||||
| **`AskUserQuestionPermissionRequest/`** | AskUserQuestion 工具权限 |
|
||||
| **`EnterPlanModePermissionRequest/`** | 进入计划模式权限 |
|
||||
| **`ExitPlanModePermissionRequest/`** | 退出计划模式权限 |
|
||||
|
||||
### 权限规则管理 (`rules/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`AddPermissionRules.tsx`** | 添加权限规则 |
|
||||
| **`PermissionRuleInput.tsx`** | 规则输入 |
|
||||
| **`PermissionRuleList.tsx`** | 规则列表 |
|
||||
| **`PermissionRuleDescription.tsx`** | 规则描述 |
|
||||
| **`AddWorkspaceDirectory.tsx`** | 添加工作目录 |
|
||||
| **`RemoveWorkspaceDirectory.tsx`** | 移除工作目录 |
|
||||
| **`RecentDenialsTab.tsx`** | 最近拒绝记录 |
|
||||
| **`WorkspaceTab.tsx`** | 工作目录标签页 |
|
||||
|
||||
### 辅助
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| **`hooks.ts`** | 权限相关 hooks |
|
||||
| **`utils.ts`** | 权限工具函数 |
|
||||
| **`shellPermissionHelpers.tsx`** | Shell 权限辅助 |
|
||||
| **`useShellPermissionFeedback.ts`** | Shell 权限反馈 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 设计系统组件 (`design-system/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`Dialog.tsx`** | 对话框容器（标题、subtitle、ESC 取消、输入指南） |
|
||||
| **`Pane.tsx`** | 面板容器（边框、内边距） |
|
||||
| **`Tabs.tsx`** | 标签页（Tab 切换） |
|
||||
| **`Divider.tsx`** | 分隔线 |
|
||||
| **`Byline.tsx`** | 副标题/署名 |
|
||||
| **`ListItem.tsx`** | 列表项 |
|
||||
| **`LoadingState.tsx`** | 加载状态 |
|
||||
| **`ProgressBar.tsx`** | 进度条 |
|
||||
| **`StatusIcon.tsx`** | 状态图标（✓ ✗ ⚠ 等） |
|
||||
| **`Ratchet.tsx`** | 步进器（数字递增/递减） |
|
||||
| **`KeyboardShortcutHint.tsx`** | 键盘快捷键提示 |
|
||||
| **`FuzzyPicker.tsx`** | 模糊搜索选择器 |
|
||||
| **`ThemeProvider.tsx`** | 主题提供者 |
|
||||
| **`ThemedBox.tsx`** | 主题化 Box |
|
||||
| **`ThemedText.tsx`** | 主题化 Text |
|
||||
| **`color.ts`** | 颜色工具函数 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 提示输入组件 (`PromptInput/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`PromptInput.tsx`** | 主输入组件（~600 行）。处理键盘输入、历史导航、粘贴、快捷键、模式切换 |
|
||||
| **`PromptInputFooter.tsx`** | 输入框底部（模式指示器 + 建议） |
|
||||
| **`PromptInputFooterLeftSide.tsx`** | 底部左侧内容 |
|
||||
| **`PromptInputFooterSuggestions.tsx`** | 输入建议（命令、文件路径） |
|
||||
| **`PromptInputHelpMenu.tsx`** | 帮助菜单 |
|
||||
| **`PromptInputModeIndicator.tsx`** | 模式指示器（编辑/vim/计划等） |
|
||||
| **`PromptInputQueuedCommands.tsx`** | 队列命令显示 |
|
||||
| **`PromptInputStashNotice.tsx`** | Stash 通知 |
|
||||
| **`ShimmeredInput.tsx`** | 闪烁输入效果 |
|
||||
| **`VoiceIndicator.tsx`** | 语音输入指示器 |
|
||||
| **`HistorySearchInput.tsx`** | 历史搜索输入 |
|
||||
| **`IssueFlagBanner.tsx`** | Issue 标记横幅 |
|
||||
| **`Notifications.tsx`** | 通知组件 |
|
||||
| **`SandboxPromptFooterHint.tsx`** | 沙箱模式提示 |
|
||||
|
||||
### 工具/辅助
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| **`inputModes.ts`** | 输入模式定义（normal/vim/edit） |
|
||||
| **`inputPaste.ts`** | 粘贴处理逻辑 |
|
||||
| **`utils.ts`** | Vim 模式检测等工具 |
|
||||
| **`useMaybeTruncateInput.ts`** | 输入截断 hook |
|
||||
| **`usePromptInputPlaceholder.ts`** | 占位符 hook |
|
||||
| **`useShowFastIconHint.ts`** | 快速模式图标提示 |
|
||||
| **`useSwarmBanner.ts`** | Swarm 横幅 hook |
|
||||
|
||||
---
|
||||
|
||||
## 6. 任务管理组件 (`tasks/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`BackgroundTasksDialog.tsx`** | 后台任务列表对话框（支持多种任务类型） |
|
||||
| **`BackgroundTask.tsx`** | 单个后台任务条目 |
|
||||
| **`BackgroundTaskStatus.tsx`** | 任务状态显示 |
|
||||
| **`AsyncAgentDetailDialog.tsx`** | 异步 Agent 详情对话框 |
|
||||
| **`InProcessTeammateDetailDialog.tsx`** | 进程内队友详情 |
|
||||
| **`RemoteSessionDetailDialog.tsx`** | 远程会话详情 |
|
||||
| **`RemoteSessionProgress.tsx`** | 远程会话进度 |
|
||||
| **`DreamDetailDialog.tsx`** | Dream 任务详情 |
|
||||
| **`ShellDetailDialog.tsx`** | Shell 任务详情 |
|
||||
| **`ShellProgress.tsx`** | Shell 进度 |
|
||||
| **`renderToolActivity.tsx`** | 工具活动渲染 |
|
||||
| **`taskStatusUtils.tsx`** | 任务状态工具函数 |
|
||||
|
||||
支持的任务类型：
|
||||
- `local_bash` — 本地 Bash
|
||||
- `local_agent` — 本地 Agent
|
||||
- `remote_agent` — 远程 Agent
|
||||
- `in_process_teammate` — 进程内队友
|
||||
- `dream` — Dream 任务
|
||||
- `local_shell` — Shell 任务
|
||||
- `local_workflow` — Workflow 任务
|
||||
- `monitor_mcp` — MCP Monitor
|
||||
|
||||
---
|
||||
|
||||
## 7. Agent 管理组件 (`agents/`)
|
||||
|
||||
### 核心
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`AgentsMenu.tsx`** | Agent 管理主菜单（列表 → 详情 → 编辑） |
|
||||
| **`AgentsList.tsx`** | Agent 列表（分组：project/global/built-in） |
|
||||
| **`AgentDetail.tsx`** | Agent 详情展示 |
|
||||
| **`AgentEditor.tsx`** | Agent 配置编辑器 |
|
||||
| **`AgentNavigationFooter.tsx`** | 导航底部 |
|
||||
| **`ColorPicker.tsx`** | 颜色选择器 |
|
||||
| **`ModelSelector.tsx`** | 模型选择器 |
|
||||
| **`ToolSelector.tsx`** | 工具选择器 |
|
||||
|
||||
### Agent 创建向导 (`new-agent-creation/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`CreateAgentWizard.tsx`** | 创建 Agent 向导主控 |
|
||||
| **`wizard-steps/MethodStep.tsx`** | 选择方式（手动/AI 生成） |
|
||||
| **`wizard-steps/TypeStep.tsx`** | Agent 类型 |
|
||||
| **`wizard-steps/DescriptionStep.tsx`** | 描述 |
|
||||
| **`wizard-steps/PromptStep.tsx`** | System Prompt |
|
||||
| **`wizard-steps/ToolsStep.tsx`** | 工具选择 |
|
||||
| **`wizard-steps/ModelStep.tsx`** | 模型选择 |
|
||||
| **`wizard-steps/ColorStep.tsx`** | 颜色选择 |
|
||||
| **`wizard-steps/LocationStep.tsx`** | 保存位置 |
|
||||
| **`wizard-steps/MemoryStep.tsx`** | Memory 配置 |
|
||||
| **`wizard-steps/GenerateStep.tsx`** | AI 生成 |
|
||||
| **`wizard-steps/ConfirmStep.tsx`** | 确认 |
|
||||
| **`wizard-steps/ConfirmStepWrapper.tsx`** | 确认包装 |
|
||||
|
||||
### 工具
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| **`types.ts`** | Agent 类型定义 |
|
||||
| **`utils.ts`** | Agent 工具函数 |
|
||||
| **`validateAgent.ts`** | Agent 验证 |
|
||||
| **`agentFileUtils.ts`** | Agent 文件操作 |
|
||||
| **`generateAgent.ts`** | AI 生成 Agent |
|
||||
|
||||
---
|
||||
|
||||
## 8. MCP 相关组件 (`mcp/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`MCPSettings.tsx`** | MCP 设置主入口（列表 → 详情） |
|
||||
| **`MCPListPanel.tsx`** | MCP 服务器列表 |
|
||||
| **`MCPStdioServerMenu.tsx`** | Stdio 服务器配置菜单 |
|
||||
| **`MCPRemoteServerMenu.tsx`** | 远程服务器配置菜单 |
|
||||
| **`MCPAgentServerMenu.tsx`** | Agent 级 MCP 服务器菜单 |
|
||||
| **`MCPToolListView.tsx`** | MCP 工具列表 |
|
||||
| **`MCPToolDetailView.tsx`** | MCP 工具详情 |
|
||||
| **`CapabilitiesSection.tsx`** | 服务器能力展示 |
|
||||
| **`MCPReconnect.tsx`** | 重连组件 |
|
||||
| **`ElicitationDialog.tsx`** | MCP Elicitation 对话框 |
|
||||
| **`McpParsingWarnings.tsx`** | 解析警告 |
|
||||
|
||||
---
|
||||
|
||||
## 9. Settings 组件 (`Settings/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`Settings.tsx`** | 设置主界面（Tab 切换：Status/Config/Usage） |
|
||||
| **`Status.tsx`** | 状态页（诊断信息、连接状态） |
|
||||
| **`Config.tsx`** | 配置页（设置项编辑） |
|
||||
| **`Usage.tsx`** | 使用统计页 |
|
||||
|
||||
---
|
||||
|
||||
## 10. Spinner 组件 (`Spinner/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`SpinnerAnimationRow.tsx`** | 动画行（旋转字符 + 文字） |
|
||||
| **`SpinnerGlyph.tsx`** | 旋转字符渲染 |
|
||||
| **`ShimmerChar.tsx`** | 闪烁字符 |
|
||||
| **`FlashingChar.tsx`** | 闪烁字符 |
|
||||
| **`GlimmerMessage.tsx`** | 微光消息 |
|
||||
| **`TeammateSpinnerLine.tsx`** | 队友 Spinner 行 |
|
||||
| **`TeammateSpinnerTree.tsx`** | 队友 Spinner 树（递归任务树） |
|
||||
|
||||
---
|
||||
|
||||
## 11. Logo 与欢迎组件 (`LogoV2/`)
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`LogoV2.tsx`** | 主 Logo + 欢迎界面（最近活动、what's new、项目入门） |
|
||||
| **`WelcomeV2.tsx`** | 欢迎消息 |
|
||||
| **`CondensedLogo.tsx`** | 精简 Logo（窄终端） |
|
||||
| **`Clawd.tsx`** | Clawd 角色 |
|
||||
| **`AnimatedClawd.tsx`** | 动画 Clawd |
|
||||
| **`AnimatedAsterisk.tsx`** | 动画星号 |
|
||||
| **`Feed.tsx`** | 信息流容器 |
|
||||
| **`FeedColumn.tsx`** | 信息流列 |
|
||||
| **`feedConfigs.tsx`** | 信息流配置（最近活动、what's new、项目入门） |
|
||||
| **`EmergencyTip.tsx`** | 紧急提示 |
|
||||
| **`VoiceModeNotice.tsx`** | 语音模式通知 |
|
||||
| **`Opus1mMergeNotice.tsx`** | Opus 1M 合并通知 |
|
||||
| **`ChannelsNotice.tsx`** | 频道通知 |
|
||||
| **`GuestPassesUpsell.tsx`** | Guest Pass 推广 |
|
||||
| **`OverageCreditUpsell.tsx`** | 超额信用推广 |
|
||||
|
||||
---
|
||||
|
||||
## 12. 其他重要组件
|
||||
|
||||
### 对话框/覆盖层
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`Onboarding.tsx`** | 首次使用引导（主题、OAuth、API Key、安全） |
|
||||
| **`ExitFlow.tsx`** | 退出流程 |
|
||||
| **`ExportDialog.tsx`** | 导出对话框 |
|
||||
| **`GlobalSearchDialog.tsx`** | 全局搜索（Transcript 搜索） |
|
||||
| **`HistorySearchDialog.tsx`** | 历史搜索 |
|
||||
| **`QuickOpenDialog.tsx`** | 快速打开 |
|
||||
| **`ModelPicker.tsx`** | 模型选择器 |
|
||||
| **`ThemePicker.tsx`** | 主题选择器 |
|
||||
| **`LanguagePicker.tsx`** | 语言选择器 |
|
||||
| **`OutputStylePicker.tsx`** | 输出风格选择器 |
|
||||
| **`BridgeDialog.tsx`** | Bridge 对话框 |
|
||||
| **`CostThresholdDialog.tsx`** | 成本阈值对话框 |
|
||||
| **`BypassPermissionsModeDialog.tsx`** | 绕过权限模式对话框 |
|
||||
| **`ChannelDowngradeDialog.tsx`** | 频道降级对话框 |
|
||||
| **`AutoModeOptInDialog.tsx`** | 自动模式加入对话框 |
|
||||
| **`IdeOnboardingDialog.tsx`** | IDE 入门对话框 |
|
||||
| **`IdeAutoConnectDialog.tsx`** | IDE 自动连接 |
|
||||
| **`InvalidConfigDialog.tsx`** | 无效配置 |
|
||||
| **`InvalidSettingsDialog.tsx`** | 无效设置 |
|
||||
| **`IdleReturnDialog.tsx`** | 空闲返回对话框 |
|
||||
| **`WorktreeExitDialog.tsx`** | Worktree 退出对话框 |
|
||||
| **`TeleportRepoMismatchDialog.tsx`** | 仓库不匹配 |
|
||||
| **`ClaudeMdExternalIncludesDialog.tsx`** | CLAUDE.md 外部引用 |
|
||||
| **`DevChannelsDialog.tsx`** | 开发频道对话框 |
|
||||
| **`WorkflowMultiselectDialog.tsx`** | Workflow 多选对话框 |
|
||||
| **`ManagedSettingsSecurityDialog/`** | 托管设置安全对话框 |
|
||||
| **`TrustDialog/`** | 信任对话框 |
|
||||
| **`MCPServerApprovalDialog.tsx`** | MCP 服务器审批 |
|
||||
| **`MCPServerDesktopImportDialog.tsx`** | MCP 桌面导入 |
|
||||
| **`MCPServerMultiselectDialog.tsx`** | MCP 多选对话框 |
|
||||
| **`MCPServerDialogCopy.tsx`** | MCP 对话框副本 |
|
||||
| **`ClaudeInChromeOnboarding.tsx`** | Chrome 入门 |
|
||||
|
||||
### 显示/工具组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`Markdown.tsx`** | Markdown 渲染（`StreamingMarkdown`） |
|
||||
| **`MarkdownTable.tsx`** | Markdown 表格 |
|
||||
| **`HighlightedCode.tsx`** | 代码高亮 |
|
||||
| **`StructuredDiff.tsx`** | 结构化 Diff |
|
||||
| **`StructuredDiffList.tsx`** | Diff 列表 |
|
||||
| **`FileEditToolDiff.tsx`** | 文件编辑 Diff |
|
||||
| **`FilePathLink.tsx`** | 文件路径链接（可点击） |
|
||||
| **`ClickableImageRef.tsx`** | 可点击图片引用 |
|
||||
| **`Stats.tsx`** | 统计信息（tokens、成本、时长） |
|
||||
| **`StatusLine.tsx`** | 状态栏（模型、权限模式、cwd、context） |
|
||||
| **`StatusNotices.tsx`** | 状态通知 |
|
||||
| **`ThinkingToggle.tsx`** | Thinking 开关 |
|
||||
| **`EffortCallout.tsx`** | Effort 提示 |
|
||||
| **`EffortIndicator.ts`** | Effort 指示器 |
|
||||
| **`TokenWarning.tsx`** | Token 警告 |
|
||||
| **`MemoryUsageIndicator.tsx`** | 内存使用指示器 |
|
||||
| **`ToolUseLoader.tsx`** | 工具使用加载器 |
|
||||
| **`SearchBox.tsx`** | 搜索框 |
|
||||
| **`LogSelector.tsx`** | 日志选择器 |
|
||||
| **`TagTabs.tsx`** | 标签标签页 |
|
||||
| **`PrBadge.tsx`** | PR 标记 |
|
||||
| **`ContextSuggestions.tsx`** | 上下文建议 |
|
||||
| **`ContextVisualization.tsx`** | 上下文可视化 |
|
||||
| **`CompactSummary.tsx`** | Compact 摘要 |
|
||||
| **`ResumeTask.tsx`** | 恢复任务 |
|
||||
| **`SessionPreview.tsx`** | 会话预览 |
|
||||
| **`SessionBackgroundHint.tsx`** | 会话背景提示 |
|
||||
| **`ShowInIDEPrompt.tsx`** | IDE 中显示提示 |
|
||||
| **`TaskListV2.tsx`** | 任务列表 V2 |
|
||||
| **`TeammateViewHeader.tsx`** | 队友视图头部 |
|
||||
| **`CoordinatorAgentStatus.tsx`** | 协调者 Agent 状态 |
|
||||
| **`AgentProgressLine.tsx`** | Agent 进度行 |
|
||||
|
||||
### Teleport 相关
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`DesktopHandoff.tsx`** | 桌面端交接 |
|
||||
| **`TeleportError.tsx`** | Teleport 错误 |
|
||||
| **`TeleportProgress.tsx`** | Teleport 进度 |
|
||||
| **`TeleportResumeWrapper.tsx`** | Teleport 恢复包装 |
|
||||
| **`TeleportStash.tsx`** | Teleport Stash |
|
||||
| **`RemoteCallout.tsx`** | 远程提示 |
|
||||
| **`RemoteEnvironmentDialog.tsx`** | 远程环境对话框 |
|
||||
|
||||
### 自动更新
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`AutoUpdater.tsx`** | 自动更新逻辑 |
|
||||
| **`AutoUpdaterWrapper.tsx`** | 自动更新包装 |
|
||||
| **`NativeAutoUpdater.tsx`** | 原生自动更新 |
|
||||
| **`PackageManagerAutoUpdater.tsx`** | 包管理器自动更新 |
|
||||
|
||||
### 反馈/调查
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`Feedback.tsx`** | 反馈入口 |
|
||||
| **`FeedbackSurvey/`** | 反馈调查（评分、transcript 分享） |
|
||||
| **`SkillImprovementSurvey.tsx`** | Skill 改进调查 |
|
||||
|
||||
### 输入/交互
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`TextInput.tsx`** | 文本输入组件 |
|
||||
| **`BaseTextInput.tsx`** | 基础文本输入 |
|
||||
| **`VimTextInput.tsx`** | Vim 模式文本输入 |
|
||||
| **`ConfigurableShortcutHint.tsx`** | 可配置快捷键提示 |
|
||||
| **`PressEnterToContinue.tsx`** | "按 Enter 继续" |
|
||||
| **`CtrlOToExpand.tsx`** | Ctrl+O 展开提示 |
|
||||
| **`ScrollKeybindingHandler.tsx`** | 滚动键绑定处理 |
|
||||
| **`KeybindingWarnings.tsx`** | 键绑定警告 |
|
||||
| **`InterruptedByUser.tsx`** | 用户中断显示 |
|
||||
| **`ValidationErrorsList.tsx`** | 验证错误列表 |
|
||||
| **`ApproveApiKey.tsx`** | API Key 审批 |
|
||||
| **`AwsAuthStatusBox.tsx`** | AWS 认证状态 |
|
||||
| **`ConsoleOAuthFlow.tsx`** | Console OAuth 流程 |
|
||||
|
||||
### 其他子目录
|
||||
|
||||
| 目录 | 组件 | 职责 |
|
||||
|------|------|------|
|
||||
| **`CustomSelect/`** | `select.tsx`, `SelectMulti.tsx`, `select-option.tsx`, `select-input-option.tsx` | 自定义选择器（单选/多选/输入） |
|
||||
| **`HelpV2/`** | `HelpV2.tsx`, `Commands.tsx`, `General.tsx` | 帮助界面 |
|
||||
| **`hooks/`** | `HooksConfigMenu.tsx`, `SelectEventMode.tsx`, `SelectHookMode.tsx` 等 | Hooks 配置管理 |
|
||||
| **`memory/`** | `MemoryFileSelector.tsx`, `MemoryUpdateNotification.tsx` | Memory 管理 |
|
||||
| **`sandbox/`** | `SandboxSettings.tsx`, `SandboxConfigTab.tsx` 等 | 沙箱设置 |
|
||||
| **`shell/`** | `ShellProgressMessage.tsx`, `OutputLine.tsx` 等 | Shell 输出展示 |
|
||||
| **`skills/`** | `SkillsMenu.tsx` | Skills 菜单 |
|
||||
| **`teams/`** | `TeamsDialog.tsx`, `TeamStatus.tsx` | 团队管理 |
|
||||
| **`diff/`** | `DiffDialog.tsx`, `DiffDetailView.tsx`, `DiffFileList.tsx` | Diff 查看器 |
|
||||
| **`grove/`** | `Grove.tsx` | Grove 功能 |
|
||||
| **`passes/`** | `Passes.tsx` | Passes 功能 |
|
||||
| **`wizard/`** | `WizardDialogLayout.tsx`, `WizardProvider.tsx`, `useWizard.ts` | 通用向导框架 |
|
||||
| **`ui/`** | `OrderedList.tsx`, `OrderedListItem.tsx`, `TreeSelect.tsx` | 通用 UI 原语 |
|
||||
| **`ClaudeCodeHint/`** | `PluginHintMenu.tsx` | 插件提示菜单 |
|
||||
| **`DesktopUpsell/`** | `DesktopUpsellStartup.tsx` | 桌面版推广 |
|
||||
| **`LspRecommendation/`** | `LspRecommendationMenu.tsx` | LSP 推荐菜单 |
|
||||
| **`Passes/`** | `Passes.tsx` | Passes |
|
||||
| **`HighlightCode/`** | `Fallback.tsx` | 代码高亮回退 |
|
||||
| **`StructuredDiff/`** | `Fallback.tsx`, `colorDiff.ts` | Diff 回退/颜色 |
|
||||
|
||||
### 独立组件
|
||||
|
||||
| 组件 | 职责 |
|
||||
|------|------|
|
||||
| **`messageActions.tsx`** | 消息动作状态管理（`MessageActionsState`、导航） |
|
||||
| **`OffscreenFreeze.tsx`** | 离屏冻结（React Compiler 优化） |
|
||||
| **`SentryErrorBoundary.ts`** | Sentry 错误边界 |
|
||||
| **`DevBar.tsx`** | 开发者工具栏 |
|
||||
| **`DiagnosticsDisplay.tsx`** | 诊断信息展示 |
|
||||
| **`FallbackToolUseErrorMessage.tsx`** | 兜底工具错误消息 |
|
||||
| **`FallbackToolUseRejectedMessage.tsx`** | 兜底工具拒绝消息 |
|
||||
| **`FileEditToolUpdatedMessage.tsx`** | 文件编辑更新消息 |
|
||||
| **`FileEditToolUseRejectedMessage.tsx`** | 文件编辑拒绝消息 |
|
||||
| **`NotebookEditToolUseRejectedMessage.tsx`** | Notebook 编辑拒绝消息 |
|
||||
| **`SandboxViolationExpandedView.tsx`** | 沙箱违规展开视图 |
|
||||
| **`FastIcon.tsx`** | 快速模式图标 |
|
||||
| **`MessageModel.tsx`** | 消息模型标签 |
|
||||
| **`MessageTimestamp.tsx`** | 消息时间戳 |
|
||||
| **`MessageSelector.tsx`** | 消息选择器 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 父子关系与数据流
|
||||
|
||||
### 核心渲染链
|
||||
|
||||
```
|
||||
App (Provider 嵌套)
|
||||
└── FullscreenLayout
|
||||
├── scrollable 区
|
||||
│ └── Messages
|
||||
│ ├── LogoHeader (LogoV2 + StatusNotices)
|
||||
│ └── VirtualMessageList
|
||||
│ └── MessageRow (per message)
|
||||
│ ├── MessageModel
|
||||
│ ├── MessageTimestamp
|
||||
│ └── Message
|
||||
│ ├── AssistantTextMessage → StreamingMarkdown
|
||||
│ ├── AssistantThinkingMessage
|
||||
│ ├── AssistantToolUseMessage
|
||||
│ ├── UserTextMessage
|
||||
│ ├── UserToolResultMessage → 具体结果组件
|
||||
│ ├── SystemTextMessage
|
||||
│ ├── CollapsedReadSearchContent
|
||||
│ ├── GroupedToolUseContent
|
||||
│ └── ... (30+ 种消息类型)
|
||||
├── bottom 区
|
||||
│ ├── Spinner (加载中)
|
||||
│ └── PromptInput
|
||||
│ ├── PromptInputFooter
|
||||
│ │ ├── PromptInputModeIndicator
|
||||
│ │ └── PromptInputFooterSuggestions
|
||||
│ ├── Notifications
|
||||
│ └── VoiceIndicator
|
||||
├── overlay 区
|
||||
│ └── PermissionRequest → 具体权限组件
|
||||
└── modal 区
|
||||
└── Settings / MCPSettings / AgentsMenu / BackgroundTasksDialog ...
|
||||
```
|
||||
|
||||
### 权限请求链
|
||||
|
||||
```
|
||||
PermissionRequest (分发器)
|
||||
├── BashPermissionRequest
|
||||
├── FileEditPermissionRequest
|
||||
├── FileWritePermissionRequest → FileWriteToolDiff
|
||||
├── NotebookEditPermissionRequest → NotebookEditToolDiff
|
||||
├── WebFetchPermissionRequest
|
||||
├── SkillPermissionRequest
|
||||
├── PowerShellPermissionRequest
|
||||
├── AskUserQuestionPermissionRequest
|
||||
├── EnterPlanModePermissionRequest
|
||||
├── ExitPlanModePermissionRequest
|
||||
├── FilesystemPermissionRequest
|
||||
├── SedEditPermissionRequest
|
||||
├── ComputerUseApproval
|
||||
└── FallbackPermissionRequest
|
||||
|
||||
所有权限组件 → PermissionDialog → PermissionRequestTitle
|
||||
```
|
||||
|
||||
### Agent 创建向导链
|
||||
|
||||
```
|
||||
AgentsMenu
|
||||
├── AgentsList
|
||||
├── AgentDetail
|
||||
├── AgentEditor
|
||||
└── CreateAgentWizard (WizardProvider)
|
||||
└── WizardDialogLayout → Dialog
|
||||
└── wizard-steps/* (12 步)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. 状态管理方式
|
||||
|
||||
### 核心状态
|
||||
|
||||
| 状态源 | Hook/Context | 管理内容 |
|
||||
|--------|-------------|----------|
|
||||
| **AppState** | `useAppState()` / `useSetAppState()` | 全局应用状态（消息、工具、MCP、Agent 定义等） |
|
||||
| **AppStateStore** | `useAppStateStore()` | 状态存储（Footer items 等） |
|
||||
| **Settings** | `useSettings()` | 用户设置 |
|
||||
| **Theme** | `useTheme()` | 主题 |
|
||||
| **Modal Context** | `useIsInsideModal()` | 是否在 modal 内 |
|
||||
| **Overlay Context** | `usePromptOverlay()` | Prompt overlay 状态 |
|
||||
| **Notifications** | `useNotifications()` | 通知系统 |
|
||||
| **FPS Metrics** | `useFpsMetrics()` | 性能指标 |
|
||||
| **Stats** | `useStats()` | 统计信息 |
|
||||
| **Terminal Size** | `useTerminalSize()` | 终端尺寸 |
|
||||
|
||||
### 状态流向
|
||||
|
||||
1. **AppState** 是中央状态容器，包含消息数组、工具列表、MCP 连接、Agent 定义等
|
||||
2. **PromptInput** 通过 `useSetAppState()` 写入用户输入，触发消息处理
|
||||
3. **Messages** 从 `useAppState()` 读取消息数组，经过过滤/重排后渲染
|
||||
4. **PermissionRequest** 从 `useAppState()` 读取当前工具使用，显示对应权限 UI
|
||||
5. **Settings/MCP/Agents** 等 modal 通过 `useSetAppState()` 修改配置
|
||||
|
||||
### 性能优化
|
||||
|
||||
- **React Compiler**: 所有组件使用 `_c()` memo 缓存，自动避免不必要重渲染
|
||||
- **`OffscreenFreeze`**: 离屏组件冻结，防止不可见区域的渲染开销
|
||||
- **`VirtualMessageList`**: 虚拟滚动，只渲染可见消息
|
||||
- **`React.memo`**: 关键子树（如 `LogoHeader`）显式 memo
|
||||
- **`useSyncExternalStore`**: 外部状态（终端尺寸、scroll 位置）订阅
|
||||
|
||||
---
|
||||
|
||||
## 15. 组件数量统计
|
||||
|
||||
| 分类 | 组件数 |
|
||||
|------|--------|
|
||||
| 主应用/布局 | ~6 |
|
||||
| 消息渲染 | ~40 |
|
||||
| 权限对话框 | ~35 |
|
||||
| 设计系统 | ~16 |
|
||||
| PromptInput | ~20 |
|
||||
| 任务管理 | ~12 |
|
||||
| Agent 管理 | ~20 |
|
||||
| MCP | ~12 |
|
||||
| Settings | 4 |
|
||||
| Spinner | ~10 |
|
||||
| LogoV2 | ~18 |
|
||||
| 其他独立组件 | ~50+ |
|
||||
| 辅助/工具文件 | ~100+ |
|
||||
| **总计** | **389 个文件** |
|
||||
542
docs/ARCHITECTURE-SERVICES.md
Normal file
542
docs/ARCHITECTURE-SERVICES.md
Normal file
@@ -0,0 +1,542 @@
|
||||
# Claude Code 服务层架构分析
|
||||
|
||||
> 基于 `src/services/` 目录下的实际源码分析。共 **21 个服务子目录** + **11 个独立服务文件**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 服务总览
|
||||
|
||||
| 服务 | 类型 | 核心职责 |
|
||||
|------|------|----------|
|
||||
| `api/` | 核心基础设施 | API 客户端、bootstrap、usage tracking、重试逻辑 |
|
||||
| `mcp/` | 核心协议 | MCP (Model Context Protocol) 协议实现与连接管理 |
|
||||
| `oauth/` | 核心认证 | OAuth 2.0 + PKCE 认证流程 |
|
||||
| `lsp/` | 核心IDE集成 | LSP 语言服务器管理与诊断 |
|
||||
| `analytics/` | 核心可观测性 | 事件日志、Datadog、GrowthBook 特性开关 |
|
||||
| `compact/` | 核心上下文管理 | 上下文压缩（自动/微压缩/会话记忆） |
|
||||
| `plugins/` | 核心扩展性 | 插件安装、市场管理、CLI 命令 |
|
||||
| `tools/` | 核心执行层 | 工具编排、执行、hook、流式执行 |
|
||||
| `oauth/` | 核心认证 | OAuth 2.0 + PKCE 授权码流 |
|
||||
| `settingsSync/` | 基础设施 | 跨环境设置同步 |
|
||||
| `remoteManagedSettings/` | 企业管理 | 远程托管配置拉取与缓存 |
|
||||
| `policyLimits/` | 企业管理 | 组织级策略限制 |
|
||||
| `teamMemorySync/` | 协作 | 团队记忆文件同步 |
|
||||
| `SessionMemory/` | AI记忆 | 会话级持久化记忆 |
|
||||
| `extractMemories/` | AI记忆 | 从会话中提取持久化记忆 |
|
||||
| `autoDream/` | AI记忆 | 后台记忆整合（/dream） |
|
||||
| `AgentSummary/` | 协调器 | 子代理进度摘要 |
|
||||
| `PromptSuggestion/` | UX增强 | 智能提示建议 |
|
||||
| `MagicDocs/` | UX增强 | 自动文档更新 |
|
||||
| `tips/` | UX增强 | Spinner 期间的提示展示 |
|
||||
| `toolUseSummary/` | SDK | 工具调用批次的可读摘要 |
|
||||
|
||||
### 独立服务文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `voice.ts` | 音频录制（push-to-talk），原生 cpal/SoX 回退 |
|
||||
| `voiceStreamSTT.ts` | 流式语音转文字 |
|
||||
| `voiceKeyterms.ts` | 语音关键词处理 |
|
||||
| `notifier.ts` | 系统通知（macOS/Linux/Windows） |
|
||||
| `preventSleep.ts` | 阻止系统休眠 |
|
||||
| `diagnosticTracking.ts` | 诊断跟踪状态管理 |
|
||||
| `tokenEstimation.ts` | Token 用量估算 |
|
||||
| `internalLogging.ts` | 内部日志 |
|
||||
| `vcr.ts` | 录制/回放功能 |
|
||||
| `claudeAiLimits.ts` | Claude.ai 速率限制处理 |
|
||||
| `rateLimitMocking.ts` | 速率限制模拟（测试用） |
|
||||
| `mockRateLimits.ts` | 速率限制 mock |
|
||||
| `awaySummary.ts` | 离开时的会话摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心服务详细分析
|
||||
|
||||
### 2.1 `api/` — API 客户端层
|
||||
|
||||
**职责：** 与 Anthropic API 的所有通信。支持 Direct API、AWS Bedrock、Google Vertex AI、Azure Foundry 四种后端。
|
||||
|
||||
**关键文件与接口：**
|
||||
|
||||
| 文件 | 功能 | 对外接口 |
|
||||
|------|------|----------|
|
||||
| `client.ts` | Anthropic SDK 客户端工厂 | `createAnthropicClient()`, 多 provider 配置 |
|
||||
| `claude.ts` | 消息发送核心 | `query()`, `streamClaudeResponse()`, `getMaxOutputTokensForModel()` |
|
||||
| `bootstrap.ts` | 启动时获取客户端配置 | `fetchBootstrap()`, 返回 `client_data` + `additional_model_options` |
|
||||
| `usage.ts` | 用量/速率追踪 | `fetchUtilization()`, `Utilization` (5h/7d 限制) |
|
||||
| `withRetry.ts` | 智能重试 | `withRetry()`, 指数退避, 529 熔断, 前台/后台区分 |
|
||||
| `errors.ts` | 错误处理 | `formatAPIError()`, 速率限制消息, 订阅检测 |
|
||||
| `filesApi.ts` | 文件 API | 文件上传/下载，beta header `files-api-2025-04-14` |
|
||||
| `grove.ts` | Grove (组织功能) | `fetchGroveConfig()`, 24h 缓存 |
|
||||
| `logging.ts` | API 请求日志 | 请求/响应记录 |
|
||||
| `sessionIngress.ts` | 会话入口 | 会话注册 |
|
||||
| `referral.ts` | 推荐系统 | 推荐链接管理 |
|
||||
| `adminRequests.ts` | 管理请求 | 管理员 API 调用 |
|
||||
|
||||
**多 Provider 支持：**
|
||||
- **Direct API**: `ANTHROPIC_API_KEY`
|
||||
- **AWS Bedrock**: AWS credentials + region 配置
|
||||
- **Vertex AI**: `ANTHROPIC_VERTEX_PROJECT_ID` + model-specific region
|
||||
- **Azure Foundry**: `ANTHROPIC_FOUNDRY_RESOURCE` + Azure AD / API key
|
||||
|
||||
**重试策略：**
|
||||
- 默认最大重试 10 次，指数退避（500ms 基础延迟）
|
||||
- 529 错误：前台查询重试最多 3 次，后台查询立即放弃
|
||||
- OAuth 401 自动刷新重试（`withOAuth401Retry`）
|
||||
- AWS/GCP 凭证自动刷新
|
||||
|
||||
---
|
||||
|
||||
### 2.2 `mcp/` — MCP 协议实现
|
||||
|
||||
**职责：** Model Context Protocol 的完整实现，管理 MCP 服务器连接、工具发现、资源读取。
|
||||
|
||||
**关键文件与接口：**
|
||||
|
||||
| 文件 | 功能 | 对外接口 |
|
||||
|------|------|----------|
|
||||
| `client.ts` | MCP 客户端核心 | `MCPClient` 类, 工具/资源/提示发现与调用 |
|
||||
| `config.ts` | MCP 配置管理 | `getClaudeCodeMcpConfigs()`, 配置合并（local/user/project/enterprise） |
|
||||
| `types.ts` | 类型定义 | `McpServerConfig`, `MCPServerConnection`, 7 种配置作用域 |
|
||||
| `useManageMCPConnections.ts` | 连接管理 React Hook | 连接/断开/重连，工具列表刷新 |
|
||||
| `auth.ts` | MCP OAuth 认证 | `discoverAuthorizationServerMetadata()`, PKCE, token 刷新 |
|
||||
| `normalization.ts` | 工具/资源归一化 | 名称规范化，冲突解决 |
|
||||
| `InProcessTransport.ts` | 进程内传输 | 内存中 MCP 服务器 |
|
||||
| `SdkControlTransport.ts` | SDK 控制传输 | SDK 控制的 MCP 传输 |
|
||||
| `channelAllowlist.ts` | 通道白名单 | 通道级 MCP 访问控制 |
|
||||
| `channelPermissions.ts` | 通道权限 | 工具级细粒度权限 |
|
||||
| `officialRegistry.ts` | 官方注册表 | MCP 服务器注册表查询 |
|
||||
| `envExpansion.ts` | 环境变量展开 | `${VAR}` 语法支持 |
|
||||
| `headersHelper.ts` | HTTP Headers | 自定义 header 处理 |
|
||||
| `elicitationHandler.ts` | 引出处理 | MCP elicitation 协议 |
|
||||
| `oauthPort.ts` | OAuth 端口 | MCP OAuth 回调端口管理 |
|
||||
| `xaa.ts` | 跨应用访问 (XAA) | IdP 联合认证 |
|
||||
| `claudeai.ts` | Claude.ai 集成 | Claude.ai MCP 配置获取 |
|
||||
|
||||
**配置作用域（ConfigScope）：**
|
||||
1. `local` — 本地项目配置
|
||||
2. `user` — 用户全局配置
|
||||
3. `project` — 项目共享配置
|
||||
4. `dynamic` — 动态添加
|
||||
5. `enterprise` — 企业管理配置
|
||||
6. `claudeai` — Claude.ai 配置
|
||||
7. `managed` — 托管配置
|
||||
|
||||
**传输协议支持：**
|
||||
- `stdio` — 标准输入/输出
|
||||
- `sse` — Server-Sent Events
|
||||
- `http` — Streamable HTTP
|
||||
- `ws` — WebSocket
|
||||
- `sdk` — SDK 内部
|
||||
|
||||
---
|
||||
|
||||
### 2.3 `oauth/` — OAuth 认证服务
|
||||
|
||||
**职责：** OAuth 2.0 + PKCE 授权码流的完整实现。
|
||||
|
||||
**关键文件与接口：**
|
||||
|
||||
| 文件 | 功能 | 对外接口 |
|
||||
|------|------|----------|
|
||||
| `index.ts` | `OAuthService` 类 | `startOAuthFlow()`, 支持自动/手动两种授权码获取方式 |
|
||||
| `client.ts` | OAuth API 客户端 | `buildAuthUrl()`, `exchangeCodeForTokens()`, `refreshTokens()`, 用户信息获取 |
|
||||
| `crypto.ts` | PKCE 加密 | `generateCodeVerifier()`, `generateCodeChallenge()`, `generateState()` |
|
||||
| `auth-code-listener.ts` | 回调监听器 | `AuthCodeListener`, localhost 回调服务器 |
|
||||
| `getOauthProfile.ts` | 用户画像 | OAuth profile 获取 |
|
||||
|
||||
**OAuth 流程：**
|
||||
1. 生成 PKCE code_verifier + code_challenge
|
||||
2. 构建授权 URL（支持 Claude.ai 和 Console 两种入口）
|
||||
3. **自动模式**：打开浏览器 → localhost 回调捕获授权码
|
||||
4. **手动模式**：用户手动复制粘贴授权码
|
||||
5. 交换 token → 存储 OAuth tokens
|
||||
6. token 过期自动刷新
|
||||
|
||||
**支持的登录方式：**
|
||||
- `loginWithClaudeAi` — Claude.ai 订阅者
|
||||
- `inferenceOnly` — 仅推理权限
|
||||
- 自定义 `orgUUID` — 组织级登录
|
||||
- `loginHint` — 登录提示
|
||||
|
||||
---
|
||||
|
||||
### 2.4 `lsp/` — LSP 语言服务器
|
||||
|
||||
**职责：** 管理多个 LSP 语言服务器实例，按文件扩展名路由请求。
|
||||
|
||||
**关键文件与接口：**
|
||||
|
||||
| 文件 | 功能 | 对外接口 |
|
||||
|------|------|----------|
|
||||
| `manager.ts` | 全局单例管理 | `getLspServerManager()`, `initializeLspServerManager()`, `shutdownLspServerManager()` |
|
||||
| `LSPServerManager.ts` | 服务器管理器 | `initialize()`, `shutdown()`, `getServerForFile()`, `sendRequest()`, `openFile()`/`changeFile()`/`saveFile()`/`closeFile()` |
|
||||
| `LSPClient.ts` | LSP 客户端 | `createLSPClient()`, 基于 `vscode-jsonrpc`, stdio 通信 |
|
||||
| `LSPServerInstance.ts` | 服务器实例 | 单个 LSP 服务器的生命周期管理 |
|
||||
| `config.ts` | 配置加载 | `getAllLspServers()`, 从 settings 读取 LSP 配置 |
|
||||
| `passiveFeedback.ts` | 被动反馈 | LSP 诊断 → Claude 诊断格式转换 |
|
||||
| `LSPDiagnosticRegistry.ts` | 诊断注册 | LSP 诊断事件注册与追踪 |
|
||||
|
||||
**管理器接口（LSPServerManager）：**
|
||||
```typescript
|
||||
interface LSPServerManager {
|
||||
initialize(): Promise<void>
|
||||
shutdown(): Promise<void>
|
||||
getServerForFile(filePath: string): LSPServerInstance | undefined
|
||||
ensureServerStarted(filePath: string): Promise<LSPServerInstance | undefined>
|
||||
sendRequest<T>(filePath: string, method: string, params: unknown): Promise<T | undefined>
|
||||
openFile(filePath: string, content: string): Promise<void>
|
||||
changeFile(filePath: string, content: string): Promise<void>
|
||||
saveFile(filePath: string): Promise<void>
|
||||
closeFile(filePath: string): Promise<void>
|
||||
isFileOpen(filePath: string): boolean
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.5 `analytics/` — 分析与特性开关
|
||||
|
||||
**职责：** 事件日志路由（Datadog + 一阶方事件）、GrowthBook 特性开关。
|
||||
|
||||
**关键文件与接口：**
|
||||
|
||||
| 文件 | 功能 | 对外接口 |
|
||||
|------|------|----------|
|
||||
| `index.ts` | 公共 API | `logEvent()`, `logEventAsync()`, 事件队列, `AnalyticsSink` 接口 |
|
||||
| `sink.ts` | 路由实现 | `initializeAnalyticsSink()`, Datadog + 1P 双路路由 |
|
||||
| `datadog.ts` | Datadog 集成 | `trackDatadogEvent()`, 批量发送（100条/15s）, 允许事件白名单 |
|
||||
| `growthbook.ts` | GrowthBook | `getFeatureValue_CACHED_MAY_BE_STALE()`, `checkStatsigFeatureGate_CACHED_MAY_BE_STALE()`, A/B 测试 |
|
||||
| `firstPartyEventLogger.ts` | 一阶方事件 | `logEventTo1P()`, `shouldSampleEvent()`, 实验曝光日志 |
|
||||
| `firstPartyEventLoggingExporter.ts` | 事件导出 | 一阶方事件导出器 |
|
||||
| `metadata.ts` | 事件元数据 | `getEventMetadata()`, 平台/模型/版本信息 |
|
||||
| `config.ts` | 配置 | `isAnalyticsDisabled()`, 分析开关 |
|
||||
| `sinkKillswitch.ts` | 杀开关 | `isSinkKilled()`, 紧急关闭特定 sink |
|
||||
|
||||
**设计特点：**
|
||||
- **零依赖设计**：`index.ts` 无任何外部依赖，避免循环引用
|
||||
- **事件排队**：sink 未初始化前事件入队，attach 后批量消费
|
||||
- **PII 保护**：`_PROTO_*` 前缀字段仅 1P exporter 可见，Datadog 自动过滤
|
||||
- **GrowthBook 集成**：远程特性评估，支持 targeting（用户属性/订阅类型/平台）
|
||||
|
||||
---
|
||||
|
||||
### 2.6 `compact/` — 上下文压缩
|
||||
|
||||
**职责：** 当上下文窗口接近上限时自动压缩对话历史。
|
||||
|
||||
**关键文件与接口：**
|
||||
|
||||
| 文件 | 功能 | 对外接口 |
|
||||
|------|------|----------|
|
||||
| `compact.ts` | 核心压缩 | `compactConversation()`, 将对话历史压缩为摘要 |
|
||||
| `autoCompact.ts` | 自动压缩 | `isAutoCompactEnabled()`, 基于 token 阈值触发 |
|
||||
| `microCompact.ts` | 微压缩 | 时间基微压缩，清理旧工具结果，保留最近内容 |
|
||||
| `apiMicrocompact.ts` | API 微压缩 | 基于 API 的微压缩策略 |
|
||||
| `sessionMemoryCompact.ts` | 会话记忆压缩 | 压缩时更新会话记忆 |
|
||||
| `grouping.ts` | 消息分组 | 将消息按主题分组以优化压缩 |
|
||||
| `compactWarningHook.ts` | 压缩警告 | 接近上限时的用户警告 hook |
|
||||
| `compactWarningState.ts` | 警告状态 | 警告抑制/清除状态管理 |
|
||||
| `postCompactCleanup.ts` | 压缩后清理 | 压缩后的资源清理 |
|
||||
| `prompt.ts` | 压缩提示 | 压缩摘要的 prompt 构建 |
|
||||
| `timeBasedMCConfig.ts` | 时间配置 | 微压缩的时间阈值配置 |
|
||||
|
||||
**压缩策略层次：**
|
||||
1. **微压缩 (Micro-compact)**：清理旧工具结果内容，替换为 stub
|
||||
2. **API 微压缩**：通过 API 端点执行微压缩
|
||||
3. **自动压缩 (Auto-compact)**：当 token 用量超过阈值时触发完整压缩
|
||||
4. **会话记忆压缩**：压缩时同步更新会话记忆文件
|
||||
|
||||
**关键常量：**
|
||||
- `MAX_OUTPUT_TOKENS_FOR_SUMMARY = 20,000`
|
||||
- `CAPPED_DEFAULT_MAX_TOKENS` — 模型最大输出
|
||||
- 上下文窗口 = 模型窗口 - 预留压缩输出空间
|
||||
|
||||
---
|
||||
|
||||
### 2.7 `plugins/` — 插件系统
|
||||
|
||||
**职责：** 后台插件安装、市场管理、CLI 命令处理。
|
||||
|
||||
**关键文件与接口：**
|
||||
|
||||
| 文件 | 功能 | 对外接口 |
|
||||
|------|------|----------|
|
||||
| `PluginInstallationManager.ts` | 后台安装管理 | `performBackgroundPluginInstallations()`, 市场 reconciliation |
|
||||
| `pluginOperations.ts` | 插件操作 | 插件安装/卸载/更新操作 |
|
||||
| `pluginCliCommands.ts` | CLI 命令 | `/plugin` 相关命令处理 |
|
||||
|
||||
**安装流程：**
|
||||
1. 加载已知市场配置 (`loadKnownMarketplacesConfig`)
|
||||
2. Diff 新旧市场 (`diffMarketplaces`)
|
||||
3. Reconcile 市场 (`reconcileMarketplaces`)
|
||||
4. 刷新活跃插件 (`refreshActivePlugins`)
|
||||
5. 更新 AppState 安装状态
|
||||
|
||||
**依赖的工具层：**
|
||||
- `utils/plugins/marketplaceManager.ts` — 市场管理
|
||||
- `utils/plugins/pluginLoader.ts` — 插件加载
|
||||
- `utils/plugins/reconciler.ts` — 市场协调
|
||||
- `utils/plugins/refresh.ts` — 插件刷新
|
||||
- `utils/plugins/mcpPluginIntegration.ts` — MCP 插件集成
|
||||
|
||||
---
|
||||
|
||||
## 3. 辅助服务分析
|
||||
|
||||
### 3.1 `tools/` — 工具执行层
|
||||
|
||||
| 文件 | 功能 |
|
||||
|------|------|
|
||||
| `toolExecution.ts` | 单工具执行，权限检查，hook 执行 |
|
||||
| `toolOrchestration.ts` | 并发安全工具编排（read-only 并发，write 串行） |
|
||||
| `StreamingToolExecutor.ts` | 流式工具执行器，实时处理到达的工具调用 |
|
||||
| `toolHooks.ts` | Pre/post tool hook 执行，规则权限检查 |
|
||||
|
||||
**并发策略：**
|
||||
- `isConcurrencySafe` 标记的工具（read-only）可并行执行
|
||||
- 最大并发数由 `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY` 控制（默认 10）
|
||||
- 写操作必须串行执行
|
||||
|
||||
### 3.2 `settingsSync/` — 设置同步
|
||||
|
||||
- **方向**：交互式 CLI 上传 → 远程；CCR 下载 → 本地
|
||||
- **增量同步**：只同步变更的条目
|
||||
- **文件大小限制**：500KB/文件
|
||||
- **重试**：最多 3 次，带退避
|
||||
|
||||
### 3.3 `remoteManagedSettings/` — 远程托管配置
|
||||
|
||||
- **目标用户**：Enterprise/C4E 和 Team 订阅者
|
||||
- **设计**：Fail-open（失败不阻塞），ETag 缓存，后台轮询（1 小时间隔）
|
||||
- **安全**：配置签名验证
|
||||
|
||||
### 3.4 `policyLimits/` — 策略限制
|
||||
|
||||
- **来源**：组织级 API 策略
|
||||
- **行为**：禁用特定 CLI 功能
|
||||
- **设计**：与 remoteManagedSettings 相同的 fail-open + ETag + 轮询模式
|
||||
|
||||
### 3.5 `teamMemorySync/` — 团队记忆同步
|
||||
|
||||
- **作用域**：per-repo（基于 git remote hash）
|
||||
- **同步语义**：Server wins per-key；delta upload（只上传内容变更的 key）
|
||||
- **安全**：secret scanner 扫描敏感信息
|
||||
|
||||
### 3.6 `SessionMemory/` — 会话记忆
|
||||
|
||||
- **机制**：forked subagent 后台运行，从对话中提取关键信息
|
||||
- **输出**：Markdown 文件，持久化到项目记忆目录
|
||||
- **触发**：注册到 post-sampling hook
|
||||
|
||||
### 3.7 `extractMemories/` — 记忆提取
|
||||
|
||||
- **时机**：每个完整 query loop 结束时（stop hook）
|
||||
- **机制**：forked agent 共享父 prompt cache
|
||||
- **输出**：`~/.claude/projects/<path>/memory/` 下的记忆文件
|
||||
|
||||
### 3.8 `autoDream/` — 记忆整合
|
||||
|
||||
- **触发条件**：时间门（小时）+ 会话积累数
|
||||
- **机制**：forked subagent 执行 `/dream` prompt
|
||||
- **锁机制**：`consolidationLock` 防止并发整合
|
||||
|
||||
### 3.9 `AgentSummary/` — 子代理摘要
|
||||
|
||||
- **频率**：每 ~30 秒
|
||||
- **方式**：forked subagent 生成 3-5 词进度描述
|
||||
- **用途**：协调器模式的 UI 展示
|
||||
|
||||
### 3.10 `PromptSuggestion/` — 提示建议
|
||||
|
||||
- **特性**：智能意图预测、推测执行（speculation）
|
||||
- **控制**：GrowthBook feature gate + 环境变量覆盖
|
||||
|
||||
### 3.11 `MagicDocs/` — 自动文档
|
||||
|
||||
- **触发**：读取包含 `# MAGIC DOC: [title]` header 的文件
|
||||
- **机制**：post-sampling hook 驱动后台更新
|
||||
|
||||
### 3.12 `tips/` — Spinner 提示
|
||||
|
||||
- **展示时机**：Spinner 等待期间
|
||||
- **选择策略**：优先展示最久未展示的 tip
|
||||
|
||||
### 3.13 `toolUseSummary/` — 工具摘要
|
||||
|
||||
- **方式**：调用 Haiku 模型生成单行摘要
|
||||
- **限制**：~30 字符截断（移动应用适配）
|
||||
|
||||
---
|
||||
|
||||
## 4. 服务间依赖关系
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ 用户界面层 (REPL/CLI) │
|
||||
└───────────────────────────────┬─────────────────────────────────┘
|
||||
│
|
||||
┌───────────────────────┼───────────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌───────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
||||
│ tools/ │ │ compact/ │ │ plugins/ │
|
||||
│ (工具执行层) │ │ (上下文压缩) │ │ (插件系统) │
|
||||
└───────┬───────┘ └────────┬────────┘ └────────┬────────┘
|
||||
│ │ │
|
||||
│ ┌─────────────────┼───────────────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ api/ (API 客户端层) │
|
||||
│ client.ts → claude.ts → withRetry.ts → bootstrap.ts → usage.ts │
|
||||
└──────────────────────────┬───────────────────────────────────────┘
|
||||
│
|
||||
┌──────────────────┼──────────────────┐
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ oauth/ │ │ mcp/ │ │ lsp/ │
|
||||
│ (OAuth认证) │ │ (MCP协议) │ │ (语言服务器) │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│ │
|
||||
└──────────┬───────┘
|
||||
│
|
||||
▼
|
||||
┌──────────────────┐
|
||||
│ analytics/ │
|
||||
│ (分析 & 特性开关) │
|
||||
└──────────────────┘
|
||||
```
|
||||
|
||||
### 核心依赖矩阵
|
||||
|
||||
| 下游服务 ↑ \ 下游依赖 → | api/ | oauth/ | analytics/ | mcp/ | lsp/ | compact/ | tools/ |
|
||||
|--------------------------|------|--------|------------|------|------|----------|--------|
|
||||
| **tools/** | ✅ | | ✅ | ✅ | | | |
|
||||
| **compact/** | ✅ | | ✅ | | | | |
|
||||
| **plugins/** | ✅ | | ✅ | ✅ | | | |
|
||||
| **mcp/** | ✅ | ✅ | ✅ | | | | |
|
||||
| **oauth/** | | | ✅ | | | | |
|
||||
| **lsp/** | | | | | | | |
|
||||
| **analytics/** | | | | | | | |
|
||||
| **SessionMemory/** | ✅ | | ✅ | | | ✅ | |
|
||||
| **extractMemories/** | | | ✅ | | | | |
|
||||
| **autoDream/** | | | ✅ | | | | |
|
||||
| **settingsSync/** | ✅ | ✅ | ✅ | | | | |
|
||||
| **teamMemorySync/** | ✅ | ✅ | ✅ | | | | |
|
||||
| **remoteManagedSettings/**| ✅ | ✅ | | | | | |
|
||||
| **policyLimits/** | ✅ | ✅ | | | | | |
|
||||
| **PromptSuggestion/** | ✅ | | ✅ | | | | |
|
||||
|
||||
### 关键依赖链
|
||||
|
||||
1. **api/ ← oauth/**: `client.ts` 调用 `checkAndRefreshOAuthTokenIfNeeded()`, `getClaudeAIOAuthTokens()`
|
||||
2. **api/ ← analytics/**: `errors.ts` 调用 `logEvent()` 记录 API 错误
|
||||
3. **mcp/ ← oauth/**: `auth.ts` 实现 MCP 服务器的独立 OAuth 流
|
||||
4. **mcp/ ← analytics/**: 连接事件、工具调用事件日志
|
||||
5. **compact/ ← api/**: `autoCompact.ts` 调用 `getMaxOutputTokensForModel()`
|
||||
6. **compact/ ← analytics/**: `microCompact.ts` 记录压缩事件
|
||||
7. **tools/ ← analytics/**: `toolExecution.ts` 记录工具执行元数据
|
||||
8. **tools/ ← mcp/**: `toolExecution.ts` 调用 `isMcpTool()` 判断 MCP 工具
|
||||
9. **settingsSync/ ← api/**: 使用 `withRetry` 和 OAuth 认证
|
||||
10. **SessionMemory/ ← compact/**: `sessionMemory.ts` 检查 `isAutoCompactEnabled()`
|
||||
|
||||
### analytics/ 是全系统的横切关注点
|
||||
|
||||
`analytics/index.ts` 的 `logEvent()` 几乎被所有服务调用。它被设计为零依赖（无外部 import），通过事件队列 + sink 注入模式避免循环引用。
|
||||
|
||||
---
|
||||
|
||||
## 5. 架构设计模式
|
||||
|
||||
### 5.1 工厂函数 + 闭包（非类）
|
||||
|
||||
LSP、MCP 客户端等核心组件均使用工厂函数模式（`createLSPClient()`, `createLSPServerManager()`），通过闭包封装私有状态，避免 class 的 `this` 绑定问题。
|
||||
|
||||
### 5.2 Forked Agent 模式
|
||||
|
||||
多个服务（SessionMemory, extractMemories, autoDream, AgentSummary, PromptSuggestion）使用 `runForkedAgent()` 模式：
|
||||
- 创建主对话的完美 fork
|
||||
- 共享父级 prompt cache（CacheSafeParams）
|
||||
- 通过 `canUseTool` 回调限制工具使用
|
||||
- 在后台运行，不阻塞主对话
|
||||
|
||||
### 5.3 Hook 系统
|
||||
|
||||
服务间通过 hook 解耦：
|
||||
- `postSamplingHooks` — 采样后 hook（SessionMemory, MagicDocs）
|
||||
- `preCompactHooks` / `postCompactHooks` — 压缩前后 hook
|
||||
- `preToolHooks` / `postToolHooks` — 工具调用前后 hook
|
||||
- `stopHooks` — 停止时 hook（extractMemories）
|
||||
|
||||
### 5.4 Fail-Open 设计
|
||||
|
||||
企业级服务（remoteManagedSettings, policyLimits）均采用 fail-open 设计：
|
||||
- API 失败不阻塞启动
|
||||
- ETag 缓存减少网络请求
|
||||
- 后台轮询更新（1 小时间隔）
|
||||
- 最多 5 次重试 + 指数退避
|
||||
|
||||
### 5.5 Feature Gate 分层
|
||||
|
||||
```
|
||||
环境变量 > GrowthBook feature gate > 默认值
|
||||
```
|
||||
- 环境变量覆盖一切（测试用）
|
||||
- GrowthBook 远程评估（生产）
|
||||
- 安全默认值
|
||||
|
||||
---
|
||||
|
||||
## 6. 数据流总结
|
||||
|
||||
### 启动流程
|
||||
|
||||
```
|
||||
bootstrap.ts (获取客户端配置)
|
||||
↓
|
||||
remoteManagedSettings (拉取远程配置)
|
||||
↓
|
||||
policyLimits (拉取策略限制)
|
||||
↓
|
||||
oauth (验证/刷新 token)
|
||||
↓
|
||||
mcp/config (加载 MCP 服务器配置)
|
||||
↓
|
||||
lsp/manager (初始化语言服务器)
|
||||
↓
|
||||
analytics/sink (初始化事件路由)
|
||||
↓
|
||||
plugins/PluginInstallationManager (后台安装插件)
|
||||
```
|
||||
|
||||
### 请求流程
|
||||
|
||||
```
|
||||
用户输入
|
||||
↓
|
||||
compact/autoCompact (检查是否需要压缩)
|
||||
↓
|
||||
api/claude.ts (发送 API 请求, withRetry)
|
||||
↓
|
||||
tools/toolOrchestration (编排工具调用)
|
||||
↓
|
||||
┌─────────┴──────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
mcp/client.ts tools/toolExecution.ts
|
||||
(远程工具) (本地工具)
|
||||
│ │
|
||||
└─────────┬──────────┘
|
||||
│
|
||||
▼
|
||||
analytics/logEvent (记录事件)
|
||||
│
|
||||
▼
|
||||
SessionMemory / extractMemories (后台记忆更新)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*生成时间: 2026-03-31 | 基于 claude-code 源码分析*
|
||||
686
docs/ARCHITECTURE-TOOLS.md
Normal file
686
docs/ARCHITECTURE-TOOLS.md
Normal file
@@ -0,0 +1,686 @@
|
||||
# Claude Code 工具系统架构分析
|
||||
|
||||
> 源码路径: `/src/tools/`
|
||||
> 总计 **43 个工具目录** + 2 个辅助目录 (`shared/`, `testing/`)
|
||||
|
||||
---
|
||||
|
||||
## 1. 工具系统基础架构
|
||||
|
||||
### 1.1 `buildTool()` — 工具构建模式
|
||||
|
||||
所有工具通过 `buildTool()` 函数（定义在 `src/Tool.ts`）构建。这是一个工厂函数，接收 `ToolDef` 部分定义，自动填充安全默认值：
|
||||
|
||||
```ts
|
||||
// Tool.ts 中的 TOOL_DEFAULTS
|
||||
{
|
||||
isEnabled: () => true,
|
||||
isConcurrencySafe: (_input?: unknown) => false, // 默认不安全
|
||||
isReadOnly: (_input?: unknown) => false, // 默认可写
|
||||
isDestructive: (_input?: unknown) => false,
|
||||
checkPermissions: () => ({ behavior: 'allow' }), // 默认允许
|
||||
toAutoClassifierInput: () => '', // 默认跳过分类器
|
||||
userFacingName: () => def.name,
|
||||
}
|
||||
```
|
||||
|
||||
### 1.2 标准工具结构
|
||||
|
||||
每个工具目录通常包含：
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `*Tool.ts(x)` | 主工具定义（调用 `buildTool()`） |
|
||||
| `prompt.ts` | 工具描述、系统提示文本、Schema 导出名 |
|
||||
| `constants.ts` | 工具名常量、错误消息常量 |
|
||||
| `UI.tsx` | React 渲染组件（tool use 消息、结果、错误、进度） |
|
||||
| `types.ts` | Zod Schema 定义（input/output 类型） |
|
||||
| `utils.ts` | 辅助函数 |
|
||||
|
||||
### 1.3 权限模型（Permission System）
|
||||
|
||||
#### PermissionResult / PermissionDecision
|
||||
|
||||
```ts
|
||||
// 权限行为：'allow' | 'ask' | 'deny' | 'passthrough'
|
||||
type PermissionResult = {
|
||||
behavior: 'allow' // 自动放行
|
||||
updatedInput?: any // 可修改 input
|
||||
} | {
|
||||
behavior: 'ask' // 询问用户
|
||||
message?: string
|
||||
} | {
|
||||
behavior: 'deny' // 直接拒绝
|
||||
message: string
|
||||
} | {
|
||||
behavior: 'passthrough' // 交给下一层处理
|
||||
message?: string
|
||||
}
|
||||
```
|
||||
|
||||
#### 权限模式（PermissionMode）
|
||||
|
||||
五种外部模式 + 两种内部模式：
|
||||
|
||||
| 模式 | 行为 |
|
||||
|------|------|
|
||||
| `default` | 每次操作都询问 |
|
||||
| `acceptEdits` | 文件系统操作自动放行（mkdir/touch/rm/mv/cp/sed） |
|
||||
| `bypassPermissions` | 全部自动放行 |
|
||||
| `dontAsk` | 不询问，直接执行 |
|
||||
| `plan` | 需要计划审批 |
|
||||
| `auto` | 内部模式，transcript classifier 驱动 |
|
||||
| `bubble` | 内部模式 |
|
||||
|
||||
#### 多层权限检查链
|
||||
|
||||
每个工具的 `checkPermissions()` 是工具级检查，之后还有：
|
||||
1. **Mode validation** (`modeValidation.ts`) — 基于当前模式
|
||||
2. **Path validation** (`pathValidation.ts`) — 路径约束
|
||||
3. **Read-only validation** (`readOnlyValidation.ts`) — 只读约束
|
||||
4. **Sed validation** (`sedValidation.ts`) — sed 编辑约束
|
||||
5. **Security checks** (`bashSecurity.ts`) — 命令安全分析
|
||||
6. **Sandbox** (`shouldUseSandbox.ts`) — 沙箱执行判定
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心工具详细分析
|
||||
|
||||
### 2.1 BashTool ⭐
|
||||
|
||||
**文件**: `BashTool/BashTool.tsx` (~160KB, 最大工具)
|
||||
**名称**: `Bash`
|
||||
**用途**: 执行 bash shell 命令
|
||||
|
||||
#### 内部结构（21 个文件）
|
||||
|
||||
| 文件 | 行数 | 用途 |
|
||||
|------|------|------|
|
||||
| `BashTool.tsx` | ~3600 | 主工具定义、命令分类、执行逻辑 |
|
||||
| `bashPermissions.ts` | ~2600 | 权限规则匹配、通配符、前缀规则 |
|
||||
| `bashSecurity.ts` | ~2800 | 安全分析：命令替换检测、危险模式、AST 解析 |
|
||||
| `readOnlyValidation.ts` | ~1900 | 只读命令验证（git/rg/fd 等安全标志） |
|
||||
| `pathValidation.ts` | ~1200 | 路径约束检查 |
|
||||
| `sedValidation.ts` | ~600 | sed 编辑命令安全验证 |
|
||||
| `prompt.ts` | ~500 | 系统提示：git 操作指引、沙箱说明、sleep 规范 |
|
||||
| `UI.tsx` | ~700 | React 渲染：命令输出、搜索结果折叠 |
|
||||
| `bashCommandHelpers.ts` | ~250 | 命令操作符权限检查 |
|
||||
| `commandSemantics.ts` | ~100 | 命令结果语义解释 |
|
||||
| `destructiveCommandWarning.ts` | ~80 | 破坏性命令警告 |
|
||||
| `modeValidation.ts` | ~170 | 模式级权限（acceptEdits 自动放行 fs 命令） |
|
||||
| `shouldUseSandbox.ts` | ~150 | 沙箱使用判定 |
|
||||
| `sedEditParser.ts` | ~280 | sed 编辑命令解析为 FileEditTool 格式 |
|
||||
| `commentLabel.ts` | ~20 | 注释标签提取 |
|
||||
| `toolName.ts` | ~3 | 工具名常量 |
|
||||
| `utils.ts` | ~200 | 图像输出处理、路径重置等 |
|
||||
|
||||
#### Input Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
command: string // 要执行的命令
|
||||
timeout?: number // 可选超时 (ms, max 600000)
|
||||
description?: string // 命令描述（活跃语态）
|
||||
run_in_background?: boolean // 后台运行
|
||||
dangerouslyDisableSandbox?: boolean // 禁用沙箱
|
||||
_simulatedSedEdit?: { // 内部字段，模型不可见
|
||||
filePath: string
|
||||
newString: string
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
stdout: string // 标准输出
|
||||
stderr: string // 标准错误
|
||||
interrupted: boolean // 是否被中断
|
||||
isImage?: boolean // 输出是否为图像
|
||||
backgroundTaskId?: string // 后台任务 ID
|
||||
returnCodeInterpretation?: string // 退出码语义解释
|
||||
noOutputExpected?: boolean // 命令是否预期无输出
|
||||
structuredContent?: any[] // 结构化内容块
|
||||
persistedOutputPath?: string // 大输出持久化路径
|
||||
}
|
||||
```
|
||||
|
||||
#### 权限模型（最复杂）
|
||||
|
||||
BashTool 拥有整个工具系统中最复杂的权限链：
|
||||
|
||||
1. **`checkPermissionMode()`** — acceptEdits 模式下自动放行 fs 命令
|
||||
2. **`bashCommandIsSafeAsync()`** — AST 级安全分析（tree-sitter 解析）
|
||||
3. **`checkReadOnlyConstraints()`** — 只读命令验证（68KB 代码）
|
||||
4. **`checkPathConstraints()`** — 路径约束（43KB 代码）
|
||||
5. **`checkSedConstraints()`** — sed 编辑约束
|
||||
6. **`shouldUseSandbox()`** — 沙箱模式判定
|
||||
7. **`bashToolHasPermission()`** — 总权限判定（98KB 代码）
|
||||
8. **Classifier** — `classifyBashCommand()` 用于 AI 驱动的权限分类
|
||||
|
||||
**安全特性**：
|
||||
- Tree-sitter AST 解析，检测命令替换 (`$()`, `<()`, 反引号)
|
||||
- 阻止 Zsh 特定危险命令（zmodload, emulate, sysopen 等）
|
||||
- 阻止设备文件（/dev/zero, /dev/random 等无限输出设备）
|
||||
- 阻止 PowerShell 语法（`<#` 注释）
|
||||
- 破坏性命令警告（git reset --hard, git push --force 等）
|
||||
|
||||
---
|
||||
|
||||
### 2.2 FileEditTool ⭐
|
||||
|
||||
**文件**: `FileEditTool/FileEditTool.ts` (~630KB)
|
||||
**名称**: `Edit`
|
||||
**用途**: 原地编辑文件内容
|
||||
|
||||
#### 内部结构
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `FileEditTool.ts` | 主工具：验证、权限、执行、Git diff 追踪 |
|
||||
| `types.ts` | Zod Schema（input/output） |
|
||||
| `constants.ts` | 工具名、权限模式常量 |
|
||||
| `prompt.ts` | 工具描述文本 |
|
||||
| `UI.tsx` | React 渲染 |
|
||||
| `utils.ts` | 字符串匹配、diff 生成、引号保留 |
|
||||
|
||||
#### Input Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
file_path: string // 绝对路径
|
||||
old_string: string // 要替换的文本
|
||||
new_string: string // 替换后的文本
|
||||
replace_all?: boolean // 替换所有匹配（默认 false）
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
filePath: string // 文件路径
|
||||
oldString: string // 原始文本
|
||||
newString: string // 新文本
|
||||
originalFile: string // 编辑前文件内容
|
||||
structuredPatch: Hunk[] // Diff patch
|
||||
userModified: boolean // 用户是否修改了提议
|
||||
replaceAll: boolean // 是否全部替换
|
||||
gitDiff?: GitDiff // Git diff 信息
|
||||
}
|
||||
```
|
||||
|
||||
#### 权限检查
|
||||
|
||||
```ts
|
||||
checkPermissions(input, context):
|
||||
→ checkWritePermissionForTool(FileEditTool, input, permissionContext)
|
||||
```
|
||||
|
||||
- 路径展开（`~` → 绝对路径）
|
||||
- 团队记忆文件秘密检测（`checkTeamMemSecrets`）
|
||||
- `old_string !== new_string` 验证
|
||||
- 文件大小限制（1 GiB）
|
||||
- 文件未修改验证（防止覆盖他人更改）
|
||||
- LSP 诊断清理
|
||||
- 技能目录自动发现和激活
|
||||
|
||||
---
|
||||
|
||||
### 2.3 FileReadTool ⭐
|
||||
|
||||
**文件**: `FileReadTool/FileReadTool.ts` (~1034KB)
|
||||
**名称**: `Read`
|
||||
**用途**: 读取文件内容
|
||||
|
||||
#### 内部结构
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `FileReadTool.ts` | 主工具：文件读取、PDF 处理、图像处理、notebook 支持 |
|
||||
| `prompt.ts` | 工具描述、提示模板、常量（MAX_LINES=2000） |
|
||||
| `limits.ts` | 文件读取限制配置 |
|
||||
| `imageProcessor.ts` | 图像处理管线 |
|
||||
| `UI.tsx` | React 渲染 |
|
||||
|
||||
#### Input Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
file_path: string // 绝对路径
|
||||
offset?: number // 起始行号（可选）
|
||||
limit?: number // 读取行数（可选，max 2000）
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Schema
|
||||
|
||||
```ts
|
||||
// 结构化内容块数组，支持：
|
||||
// - 文本内容（带行号）
|
||||
// - 图像（Base64 PNG/JPG）
|
||||
// - PDF 页面
|
||||
// - Jupyter notebook 单元格
|
||||
```
|
||||
|
||||
#### 特殊能力
|
||||
|
||||
- **图像读取**: PNG, JPG, GIF, WebP → 直接展示
|
||||
- **PDF 支持**: 分页读取，max 20 页/次
|
||||
- **Notebook 支持**: .ipynb 文件解析
|
||||
- **设备文件阻止**: /dev/zero, /dev/random, /dev/tty 等
|
||||
- **macOS 截图路径**: 处理普通空格和窄空格（U+202F）差异
|
||||
- **文件未变更缓存**: 返回 "File unchanged since last read" 避免重复传输
|
||||
|
||||
#### 权限检查
|
||||
|
||||
```ts
|
||||
checkPermissions(input, context):
|
||||
→ checkReadPermissionForTool(FileReadTool, input, permissionContext)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2.4 FileWriteTool ⭐
|
||||
|
||||
**文件**: `FileWriteTool/FileWriteTool.ts` (~435KB)
|
||||
**名称**: `Write`
|
||||
**用途**: 创建或覆写文件
|
||||
|
||||
#### Input Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
file_path: string // 绝对路径
|
||||
content: string // 文件内容
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
type: 'create' | 'update' // 创建或更新
|
||||
filePath: string // 文件路径
|
||||
content: string // 写入内容
|
||||
structuredPatch: Hunk[] // Diff patch
|
||||
originalFile: string | null // 原始内容（新文件为 null）
|
||||
gitDiff?: GitDiff // Git diff 信息
|
||||
}
|
||||
```
|
||||
|
||||
#### 权限检查
|
||||
|
||||
```ts
|
||||
checkPermissions(input, context):
|
||||
→ checkWritePermissionForTool(FileWriteTool, input, permissionContext)
|
||||
```
|
||||
|
||||
- 团队记忆秘密检测
|
||||
- 文件修改时间追踪
|
||||
- 技能目录发现和激活
|
||||
- LSP 诊断清理
|
||||
|
||||
---
|
||||
|
||||
### 2.5 AgentTool ⭐
|
||||
|
||||
**文件**: `AgentTool/AgentTool.tsx` (~234KB)
|
||||
**名称**: `Agent`
|
||||
**用途**: 派生子代理执行任务
|
||||
|
||||
#### 内部结构（16 个文件）
|
||||
|
||||
| 文件 | 行数 | 用途 |
|
||||
|------|------|------|
|
||||
| `AgentTool.tsx` | ~6800 | 主工具定义、schema、执行逻辑 |
|
||||
| `UI.tsx` | ~3700 | React 渲染（多代理进度、分组显示） |
|
||||
| `runAgent.ts` | ~973 | 代理运行时：query 调度、消息传递、MCP 连接 |
|
||||
| `agentToolUtils.ts` | ~686 | 工具过滤、异步生命周期、结果处理 |
|
||||
| `loadAgentsDir.ts` | ~755 | 从 .claude/agents/ 加载代理定义 |
|
||||
| `prompt.ts` | ~287 | 代理列表格式化、工具描述生成 |
|
||||
| `forkSubagent.ts` | ~210 | Fork 子代理（worktree 隔离） |
|
||||
| `resumeAgent.ts` | ~265 | 恢复代理执行 |
|
||||
| `agentMemory.ts` | ~177 | 代理记忆管理 |
|
||||
| `agentMemorySnapshot.ts` | ~197 | 记忆快照 |
|
||||
| `agentDisplay.ts` | ~104 | 显示名称格式化 |
|
||||
| `builtInAgents.ts` | ~72 | 内置代理注册 |
|
||||
| `agentColorManager.ts` | ~66 | 代理颜色管理 |
|
||||
| `constants.ts` | ~12 | 常量定义 |
|
||||
|
||||
#### 内置代理类型
|
||||
|
||||
| 代理类型 | 文件 | 用途 |
|
||||
|----------|------|------|
|
||||
| `general-purpose` | `generalPurposeAgent.ts` | 通用代理 |
|
||||
| `Explore` | `exploreAgent.ts` | 代码探索 |
|
||||
| `Plan` | `planAgent.ts` | 规划代理 |
|
||||
| `Claude Code Guide` | `claudeCodeGuideAgent.ts` | 使用指南 |
|
||||
| `Statusline Setup` | `statuslineSetup.ts` | 状态栏配置 |
|
||||
| `verification` | `verificationAgent.ts` | 验证代理 |
|
||||
|
||||
#### Input Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
description: string // 简短描述 (3-5 词)
|
||||
prompt: string // 任务指令
|
||||
subagent_type?: string // 代理类型
|
||||
model?: 'sonnet' | 'opus' | 'haiku' // 模型覆盖
|
||||
run_in_background?: boolean // 后台运行
|
||||
// 以下为多代理功能（feature gate）
|
||||
name?: string // 代理名称
|
||||
team_name?: string // 团队名称
|
||||
mode?: PermissionMode // 权限模式
|
||||
isolation?: 'worktree' | 'remote' // 隔离模式
|
||||
cwd?: string // 工作目录覆盖
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Schema
|
||||
|
||||
```ts
|
||||
{
|
||||
result: string // 代理执行结果
|
||||
agentId: string // 代理 ID
|
||||
// 可能包含 structured content
|
||||
}
|
||||
```
|
||||
|
||||
#### 权限检查
|
||||
|
||||
- `filterDeniedAgents()` — 检查代理类型是否被允许
|
||||
- `isSourceAdminTrusted()` — 信任来源检查
|
||||
- `isRestrictedToPluginOnly()` — 插件限制
|
||||
|
||||
#### 工具过滤
|
||||
|
||||
AgentTool 会根据代理类型过滤可用工具：
|
||||
- `ALL_AGENT_DISALLOWED_TOOLS` — 所有代理都禁用的工具
|
||||
- `CUSTOM_AGENT_DISALLOWED_TOOLS` — 自定义代理禁用的工具
|
||||
- `ASYNC_AGENT_ALLOWED_TOOLS` — 异步代理允许的工具
|
||||
- `IN_PROCESS_TEAMMATE_ALLOWED_TOOLS` — 进程内伙伴允许的工具
|
||||
|
||||
---
|
||||
|
||||
### 2.6 MCPTool ⭐
|
||||
|
||||
**文件**: `MCPTool/MCPTool.ts` (~100 行)
|
||||
**名称**: `mcp`（动态覆盖）
|
||||
**用途**: MCP（Model Context Protocol）工具桥接
|
||||
|
||||
#### 设计哲学
|
||||
|
||||
MCPTool 是一个 **模板工具**。真正的工具名、Schema、描述都在 `mcpClient.ts` 运行时覆盖。每个 MCP 服务器注册的工具都会动态创建 MCPTool 实例。
|
||||
|
||||
#### 核心定义
|
||||
|
||||
```ts
|
||||
export const MCPTool = buildTool({
|
||||
isMcp: true,
|
||||
name: 'mcp', // 运行时被覆盖
|
||||
maxResultSizeChars: 100_000,
|
||||
// 所有关键方法都在 mcpClient.ts 中覆盖
|
||||
inputSchema: z.object({}).passthrough(), // 接受任意输入
|
||||
outputSchema: z.string(), // 字符串输出
|
||||
async checkPermissions() {
|
||||
return { behavior: 'passthrough', message: 'MCPTool requires permission.' }
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
#### 相关工具
|
||||
|
||||
| 工具 | 用途 |
|
||||
|------|------|
|
||||
| `MCPTool` | 执行 MCP 工具 |
|
||||
| `ListMcpResourcesTool` | 列出 MCP 资源 |
|
||||
| `ReadMcpResourceTool` | 读取 MCP 资源 |
|
||||
| `McpAuthTool` | MCP 认证管理 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 其他工具一览
|
||||
|
||||
### 3.1 文件系统工具
|
||||
|
||||
| 工具 | 名称 | Input | Output | 说明 |
|
||||
|------|------|-------|--------|------|
|
||||
| `GlobTool` | `Glob` | `{pattern, path?}` | `{durationMs, numFiles, filenames}` | 文件模式匹配 |
|
||||
| `GrepTool` | `Grep` | `{pattern, path?, include?, -A?, -B?, context?, output_mode?}` | `{durationMs, numMatches, matches}` | 内容搜索 |
|
||||
| `NotebookEditTool` | `NotebookEdit` | `{notebook_path, cell_number?, new_source, cell_type?, edit_mode?}` | 结构化 | Jupyter 编辑 |
|
||||
|
||||
### 3.2 网络工具
|
||||
|
||||
| 工具 | 名称 | Input | Output | 说明 |
|
||||
|------|------|-------|--------|------|
|
||||
| `WebFetchTool` | `WebFetch` | `{url, prompt}` | `{bytes, code, codeText, result}` | URL 获取+处理 |
|
||||
| `WebSearchTool` | `WebSearch` | `{query, allowed_domains?, blocked_domains?}` | `{hits[], total_results}` | 网络搜索 |
|
||||
| `RemoteTriggerTool` | `RemoteTrigger` | `{action, trigger_id?, ...}` | 结构化 | 远程触发器管理 |
|
||||
|
||||
### 3.3 代码智能
|
||||
|
||||
| 工具 | 名称 | Input | Output | 说明 |
|
||||
|------|------|-------|--------|------|
|
||||
| `LSPTool` | `LSP` | `{operation, filePath, line, column}` | 结构化 | LSP 操作（定义、引用、hover） |
|
||||
|
||||
### 3.4 任务管理
|
||||
|
||||
| 工具 | 名称 | Input | Output | 说明 |
|
||||
|------|------|-------|--------|------|
|
||||
| `TaskCreateTool` | `TaskCreate` | `{title, description?, priority?}` | `{id, ...}` | 创建任务 |
|
||||
| `TaskGetTool` | `TaskGet` | `{id}` | `{task}` | 获取任务 |
|
||||
| `TaskListTool` | `TaskList` | `{status?, limit?}` | `{tasks[]}` | 列出任务 |
|
||||
| `TaskUpdateTool` | `TaskUpdate` | `{id, ...}` | `{task}` | 更新任务 |
|
||||
| `TaskStopTool` | `TaskStop` | `{id, reason?}` | `{task}` | 停止任务 |
|
||||
| `TaskOutputTool` | `TaskOutput` | `{id}` | 结构化 | 获取任务输出 |
|
||||
|
||||
### 3.5 多代理/团队
|
||||
|
||||
| 工具 | 名称 | Input | Output | 说明 |
|
||||
|------|------|-------|--------|------|
|
||||
| `SendMessageTool` | `SendMessage` | `{to, content}` | 结构化 | 代理间通信 |
|
||||
| `TeamCreateTool` | `TeamCreate` | `{name, ...}` | 结构化 | 创建团队 |
|
||||
| `TeamDeleteTool` | `TeamDelete` | `{name}` | 结构化 | 删除团队 |
|
||||
|
||||
### 3.6 规划与工作流
|
||||
|
||||
| 工具 | 名称 | Input | Output | 说明 |
|
||||
|------|------|-------|--------|------|
|
||||
| `EnterPlanModeTool` | `EnterPlanMode` | `{}` | `{message}` | 进入计划模式 |
|
||||
| `ExitPlanModeTool` | `ExitPlanMode` | `{plan, allowedPrompts?}` | `{plan, isAgent}` | 退出计划模式 |
|
||||
| `EnterWorktreeTool` | `EnterWorktree` | `{name}` | `{worktreePath, ...}` | 进入 worktree |
|
||||
| `ExitWorktreeTool` | `ExitWorktree` | `{action}` | 结构化 | 退出 worktree |
|
||||
| `TodoWriteTool` | `TodoWrite` | `{todos}` | `{oldTodos, newTodos}` | 待办列表管理 |
|
||||
|
||||
### 3.7 杂项
|
||||
|
||||
| 工具 | 名称 | Input | Output | 说明 |
|
||||
|------|------|-------|--------|------|
|
||||
| `AskUserQuestionTool` | `AskUserQuestion` | `{questions[]}` | `{answers[]}` | 交互式问答 |
|
||||
| `BriefTool` | `SendUserMessage` | `{message, attachments?, status?}` | `{message, attachments}` | 向用户发消息 |
|
||||
| `ConfigTool` | `Config` | `{setting, value?}` | 结构化 | 读写配置 |
|
||||
| `SkillTool` | `Skill` | `{skill, args?}` | 结构化 | 执行技能命令 |
|
||||
| `ScheduleCronTool` | `CronCreate` | `{cron, prompt, recurring?, durable?}` | 结构化 | 定时任务 |
|
||||
| `SleepTool` | `Sleep` | — | — | 延迟（简单工具） |
|
||||
| `ToolSearchTool` | `ToolSearch` | `{query}` | `{matches, query, total_deferred_tools}` | 搜索延迟加载工具 |
|
||||
| `SyntheticOutputTool` | `StructuredOutput` | `{}` (passthrough) | `string` | 结构化输出 |
|
||||
| `TungstenTool` | — | — | — | Stub（内部 Anthropic 工具，`null`） |
|
||||
| `REPLTool` | — | — | — | 交互式 REPL 包装 |
|
||||
| `PowerShellTool` | — | — | — | Windows PowerShell（类似 BashTool 的 Windows 版） |
|
||||
|
||||
---
|
||||
|
||||
## 4. 工具间依赖关系
|
||||
|
||||
### 4.1 导入依赖图
|
||||
|
||||
```
|
||||
BashTool
|
||||
├── FileEditTool (sed 编辑时调用)
|
||||
├── shared/gitOperationTracking (Git 操作追踪)
|
||||
└── SandboxManager (沙箱执行)
|
||||
|
||||
FileEditTool
|
||||
├── FileReadTool (常量引用)
|
||||
├── NotebookEditTool (notebook 文件检测)
|
||||
└── shared (技能发现)
|
||||
|
||||
FileReadTool
|
||||
└── BashTool (常量引用，只读约束)
|
||||
|
||||
FileWriteTool
|
||||
├── FileEditTool (常量引用、diff schema)
|
||||
└── shared (技能发现)
|
||||
|
||||
AgentTool
|
||||
├── BashTool (工具名引用)
|
||||
├── FileReadTool (工具名引用)
|
||||
├── SendMessageTool (代理间通信)
|
||||
├── shared/spawnMultiAgent (多代理启动)
|
||||
├── loadAgentsDir (代理定义加载)
|
||||
├── builtInAgents (内置代理)
|
||||
└── runAgent (代理执行引擎)
|
||||
|
||||
MCPTool
|
||||
├── mcpClient.ts (运行时覆盖：name, schema, call, description)
|
||||
└── ListMcpResourcesTool / ReadMcpResourceTool (MCP 资源)
|
||||
|
||||
PowerShellTool
|
||||
└── 类似 BashTool 的 Windows 版本（共享结构，独立实现）
|
||||
|
||||
REPLTool
|
||||
├── AgentTool
|
||||
└── BashTool (作为可调用子工具)
|
||||
```
|
||||
|
||||
### 4.2 共享基础设施
|
||||
|
||||
| 模块 | 路径 | 用途 |
|
||||
|------|------|------|
|
||||
| `spawnMultiAgent.ts` | `tools/shared/` | 多代理启动（tmux、in-process、remote） |
|
||||
| `gitOperationTracking.ts` | `tools/shared/` | Git 操作性能追踪 |
|
||||
| `TestingPermissionTool.tsx` | `tools/testing/` | 测试专用权限工具 |
|
||||
| `utils.ts` | `tools/` | 消息标签、工具 ID 提取 |
|
||||
| `SandboxManager` | `utils/sandbox/` | 沙箱执行管理 |
|
||||
| `PermissionResult` | `types/permissions.ts` | 权限类型定义 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 工具注册与发现
|
||||
|
||||
### 5.1 静态注册
|
||||
|
||||
大多数工具在 `src/tools.ts` 中静态导入和注册。
|
||||
|
||||
### 5.2 动态发现
|
||||
|
||||
- **MCP 工具**: 通过 `mcpClient.ts` 动态创建，每个 MCP 服务器注册独立工具
|
||||
- **Agent 定义**: 从 `.claude/agents/` 目录加载（`loadAgentsDir.ts`）
|
||||
- 支持 Markdown frontmatter 定义工具白名单/黑名单
|
||||
- 支持 MCP 服务器需求声明
|
||||
- **Skill 工具**: `SkillTool` 通过 `Skill` 名称动态调用
|
||||
- **ToolSearchTool**: 延迟加载机制，支持 `select:<name>` 直接选择
|
||||
|
||||
### 5.3 Feature Gates
|
||||
|
||||
工具功能通过 `feature()` 函数控制（Bun bundler 常量折叠）：
|
||||
|
||||
| Feature | 影响 |
|
||||
|---------|------|
|
||||
| `KAIROS` | AgentTool `cwd` 参数 |
|
||||
| `PROACTIVE` | AgentTool 主动式模块 |
|
||||
| `COORDINATOR_MODE` | 协调器模式代理 |
|
||||
| `BUILTIN_EXPLORE_PLAN_AGENTS` | 内置 Explore/Plan 代理 |
|
||||
| `VERIFICATION_AGENT` | 验证代理 |
|
||||
| `TRANSCRIPT_CLASSIFIER` | `auto` 权限模式 |
|
||||
| `BASH_CLASSIFIER` | Bash 命令 AI 分类权限 |
|
||||
| `MONITOR_TOOL` | 监控工具（替代 sleep 轮询） |
|
||||
| `AGENT_SUMMARIZATION` | 代理结果摘要 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 安全架构总结
|
||||
|
||||
### 6.1 防御层级（以 BashTool 为例）
|
||||
|
||||
```
|
||||
用户请求 → tool call
|
||||
↓
|
||||
1. Input Schema 验证 (Zod)
|
||||
↓
|
||||
2. Tool.checkPermissions() — 工具级
|
||||
↓
|
||||
3. checkPermissionMode() — 模式级
|
||||
↓
|
||||
4. bashCommandIsSafeAsync() — AST 安全分析
|
||||
↓
|
||||
5. checkReadOnlyConstraints() — 只读约束
|
||||
↓
|
||||
6. checkPathConstraints() — 路径约束
|
||||
↓
|
||||
7. checkSedConstraints() — sed 约束
|
||||
↓
|
||||
8. shouldUseSandbox() — 沙箱判定
|
||||
↓
|
||||
9. bashToolHasPermission() — 权限规则匹配
|
||||
↓
|
||||
10. classifyBashCommand() — AI 分类器（可选）
|
||||
↓
|
||||
allow / ask / deny
|
||||
```
|
||||
|
||||
### 6.2 写入工具安全共性
|
||||
|
||||
`FileEditTool`、`FileWriteTool`、`NotebookEditTool` 共享：
|
||||
- 路径展开和规范化
|
||||
- 写权限检查 (`checkWritePermissionForTool`)
|
||||
- 团队记忆秘密检测
|
||||
- 文件修改时间一致性验证
|
||||
- Git diff 追踪
|
||||
- 技能目录自动发现
|
||||
|
||||
### 6.3 沙箱机制
|
||||
|
||||
`SandboxManager` 提供：
|
||||
- 文件系统读/写白名单/黑名单
|
||||
- 网络访问控制（允许/拒绝主机列表）
|
||||
- Unix socket 控制
|
||||
- 违规忽略规则
|
||||
- `dangerouslyDisableSandbox` 逃生口（需用户确认）
|
||||
|
||||
---
|
||||
|
||||
## 7. 关键设计模式
|
||||
|
||||
### 7.1 Lazy Schema
|
||||
|
||||
所有 Schema 使用 `lazySchema()` 包装，延迟求值以避免循环依赖和模块初始化问题：
|
||||
|
||||
```ts
|
||||
const inputSchema = lazySchema(() => z.strictObject({ ... }))
|
||||
```
|
||||
|
||||
### 7.2 UI 组件分离
|
||||
|
||||
每个工具的 React 渲染组件分离到 `UI.tsx`：
|
||||
- `renderToolUseMessage()` — 工具调用显示
|
||||
- `renderToolResultMessage()` — 结果显示
|
||||
- `renderToolUseErrorMessage()` — 错误显示
|
||||
- `renderToolUseProgressMessage()` — 进度显示
|
||||
- `renderToolUseRejectedMessage()` — 拒绝显示
|
||||
- `userFacingName()` — 用户可见名称
|
||||
|
||||
### 7.3 Semantic Boolean/Number
|
||||
|
||||
`semanticBoolean()` 和 `semanticNumber()` 是 Zod 扩展，用于在 schema 层面标记布尔值和数字，使 AI 模型更容易理解参数类型：
|
||||
|
||||
```ts
|
||||
run_in_background: semanticBoolean(z.boolean().optional())
|
||||
timeout: semanticNumber(z.number().optional())
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*文档生成时间: 2026-03-31*
|
||||
295
docs/ARCHITECTURE-UTILS.md
Normal file
295
docs/ARCHITECTURE-UTILS.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# Utils 架构详细文档
|
||||
|
||||
> 290 个独立工具文件 + 32 个子目录，总计 ~88,500 行代码
|
||||
> 占项目总代码量的 ~17%，是最大的单一模块
|
||||
|
||||
---
|
||||
|
||||
## 1. 子目录概览 (32 个)
|
||||
|
||||
按文件数量排序：
|
||||
|
||||
| 目录 | 文件数 | 职责 |
|
||||
|------|--------|------|
|
||||
| `plugins/` | 44 | 插件系统：加载、安装、版本、市场、验证 |
|
||||
| `permissions/` | 24 | 权限引擎：模式、规则、分类器、路径验证 |
|
||||
| `bash/` | 23 | Bash 解析器：AST、heredoc、shell completion |
|
||||
| `swarm/` | 22 | 团队协作：后端、生成、权限同步、重连 |
|
||||
| `settings/` | 19 | 配置系统：验证、缓存、MDM、变更检测 |
|
||||
| `hooks/` | 17 | 钩子系统：注册、执行、事件、配置 |
|
||||
| `model/` | 16 | 模型管理：别名、能力、deprecation、提供商 |
|
||||
| `computerUse/` | 15 | 计算机使用：执行器、截图、输入、清理 |
|
||||
| `shell/` | 10 | Shell 抽象：Bash/PowerShell 提供者、前缀 |
|
||||
| `telemetry/` | 9 | 遥测：事件、追踪、性能、插件追踪 |
|
||||
| `claudeInChrome/` | 7 | Chrome 集成：native host、MCP server |
|
||||
| `secureStorage/` | 6 | 安全存储：macOS Keychain、明文 fallback |
|
||||
| `deepLink/` | 6 | 深度链接：解析、协议处理、终端启动 |
|
||||
| `task/` | 5 | 任务框架：输出格式化、磁盘持久化 |
|
||||
| `suggestions/` | 5 | 补全建议：命令、目录、shell 历史 |
|
||||
| `nativeInstaller/` | 5 | 原生安装器：下载、安装、包管理器 |
|
||||
| `teleport/` | 4 | 远程传送：API、环境选择、git bundle |
|
||||
| `processUserInput/` | 4 | 用户输入处理：bash 命令、斜杠命令、文本 |
|
||||
| `powershell/` | 3 | PowerShell：危险 cmdlet、解析器 |
|
||||
| `git/` | 3 | Git 操作：config 解析、文件系统、gitignore |
|
||||
| `ultraplan/` | 2 | 超级计划：CCR 会话、关键词 |
|
||||
| `sandbox/` | 2 | 沙箱：适配器、UI 工具 |
|
||||
| `messages/` | 2 | 消息映射：SDK 消息转换 |
|
||||
| `memory/` | 2 | 记忆：类型、版本 |
|
||||
| `mcp/` | 2 | MCP 工具：日期解析、验证 |
|
||||
| `filePersistence/` | 2 | 文件持久化：扫描器 |
|
||||
| `dxt/` | 2 | DXT：辅助函数、zip |
|
||||
| `background/` | 2 | 后台任务：远程预检查、会话 |
|
||||
| `todo/` | 1 | Todo 类型定义 |
|
||||
| `skills/` | 1 | 技能变更检测 |
|
||||
| `github/` | 1 | GitHub 认证状态 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心工具文件 (根目录 290 个)
|
||||
|
||||
### 2.1 文件系统与路径 (~25 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `file.ts` | 文件操作辅助 |
|
||||
| `fileRead.ts` | 文件读取（带缓存、限制） |
|
||||
| `fileReadCache.ts` | 文件读取缓存 |
|
||||
| `fileStateCache.ts` | 文件状态缓存 (clone, merge, size limit) |
|
||||
| `fileHistory.ts` | 文件历史快照追踪 |
|
||||
| `fileOperationAnalytics.ts` | 文件操作分析 |
|
||||
| `filePersistence/filePersistence.ts` | 文件持久化 |
|
||||
| `glob.ts` | Glob 模式匹配 |
|
||||
| `ripgrep.ts` | ripgrep 封装（代码搜索） |
|
||||
| `fsOperations.ts` | 文件系统操作 |
|
||||
| `path.ts` | 路径工具 |
|
||||
| `tempfile.ts` | 临时文件生成 |
|
||||
| `xdg.ts` | XDG 目录标准 |
|
||||
| `systemDirectories.ts` | 系统目录 |
|
||||
| `cachePaths.ts` | 缓存路径 |
|
||||
| `getWorktreePaths.ts` | Worktree 路径 |
|
||||
| `getWorktreePathsPortable.ts` | 跨平台 worktree 路径 |
|
||||
| `worktree.ts` | Worktree 管理 |
|
||||
| `worktreeModeEnabled.ts` | Worktree 模式开关 |
|
||||
| `windowsPaths.ts` | Windows 路径处理 |
|
||||
|
||||
### 2.2 Git 相关 (~10 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `git.ts` | Git 操作：findGitRoot, getBranch, getIsGit, getWorktreeCount |
|
||||
| `gitDiff.ts` | Git diff 解析和格式化 |
|
||||
| `git/gitConfigParser.ts` | Git config 解析 |
|
||||
| `git/gitFilesystem.ts` | Git 文件系统抽象 |
|
||||
| `git/gitignore.ts` | Gitignore 处理 |
|
||||
| `gitSettings.ts` | Git 设置 |
|
||||
| `github/ghAuthStatus.ts` | GitHub 认证状态 |
|
||||
| `githubRepoPathMapping.ts` | GitHub 仓库路径映射 |
|
||||
| `ghPrStatus.ts` | PR 状态查询 |
|
||||
| `commitAttribution.ts` | Commit 归因 |
|
||||
|
||||
### 2.3 进程与执行 (~10 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `process.ts` | 进程工具：writeToStderr, peekForStdinData |
|
||||
| `execFileNoThrow.ts` | 安全 exec (无异常) |
|
||||
| `execFileNoThrowPortable.ts` | 跨平台 exec |
|
||||
| `execSyncWrapper.ts` | 同步 exec 包装 |
|
||||
| `genericProcessUtils.ts` | 通用进程工具 |
|
||||
| `subprocessEnv.ts` | 子进程环境变量 |
|
||||
| `Shell.ts` | Shell 管理：cwd、执行 |
|
||||
| `ShellCommand.ts` | Shell 命令构建 |
|
||||
| `which.ts` | 可执行文件查找 |
|
||||
| `findExecutable.ts` | 可执行文件发现 |
|
||||
| `tree-kill` | 进程树终止 |
|
||||
|
||||
### 2.4 加密与安全 (~8 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `crypto.ts` | 加密工具 |
|
||||
| `secureStorage/index.ts` | 安全存储入口 |
|
||||
| `secureStorage/macOsKeychainStorage.ts` | macOS Keychain |
|
||||
| `secureStorage/keychainPrefetch.ts` | Keychain 预取 (启动优化) |
|
||||
| `secureStorage/fallbackStorage.ts` | Fallback 明文存储 |
|
||||
| `secureStorage/plainTextStorage.ts` | 明文存储 |
|
||||
| `caCerts.ts` / `caCertsConfig.ts` | CA 证书 |
|
||||
| `mtls.ts` | mTLS 支持 |
|
||||
|
||||
### 2.5 配置与设置 (~15 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `config.ts` | 全局配置：读写 ~/.claude/ |
|
||||
| `configConstants.ts` | 配置常量 |
|
||||
| `env.ts` / `envDynamic.ts` / `envUtils.ts` / `envValidation.ts` | 环境变量管理 |
|
||||
| `managedEnv.ts` / `managedEnvConstants.ts` | 管理环境变量 |
|
||||
| `settings/settings.ts` | 设置加载（多源合并） |
|
||||
| `settings/validation.ts` | Zod schema 验证 |
|
||||
| `settings/settingsCache.ts` | 设置缓存 |
|
||||
| `settings/changeDetector.ts` | 文件变更检测 |
|
||||
| `settings/mdm/` | MDM 企业设置 |
|
||||
|
||||
### 2.6 认证与 API (~12 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `auth.ts` | 认证：OAuth token、Claude.ai 订阅 |
|
||||
| `authFileDescriptor.ts` | 认证文件描述符 |
|
||||
| `authPortable.ts` | 跨平台认证 |
|
||||
| `api.ts` | API 工具 |
|
||||
| `apiPreconnect.ts` | API 预连接 (启动优化) |
|
||||
| `billing.ts` | 计费 |
|
||||
| `user.ts` | 用户信息 |
|
||||
| `sessionIngressAuth.ts` | 会话入口认证 |
|
||||
| `jwt` 相关 | JWT 工具 |
|
||||
| `proxy.ts` | 代理配置 |
|
||||
|
||||
### 2.7 Diff 与比较 (~5 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `diff.ts` | Diff 工具 |
|
||||
| `treeify.ts` | 树形展示 |
|
||||
| `highlightMatch.tsx` | 匹配高亮 |
|
||||
| `contentArray.ts` | 内容数组操作 |
|
||||
| `truncate.ts` | 文本截断 |
|
||||
|
||||
### 2.8 UI 与渲染 (~12 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `ansiToPng.ts` / `ansiToSvg.ts` | ANSI 转图片/SVG |
|
||||
| `cliHighlight.ts` | CLI 高亮 |
|
||||
| `format.ts` | 格式化（token、时间、文件大小） |
|
||||
| `markdown.ts` | Markdown 处理 |
|
||||
| `renderOptions.ts` | 渲染选项 |
|
||||
| `staticRender.tsx` | 静态渲染 |
|
||||
| `fullscreen.ts` | 全屏模式 |
|
||||
| `hyperlink.ts` | 终端超链接 |
|
||||
| `ink.ts` | Ink 工具 |
|
||||
| `screenshotClipboard.ts` | 截图剪贴板 |
|
||||
| `theme.ts` / `systemTheme.ts` | 主题管理 |
|
||||
| `exportRenderer.tsx` | 导出渲染器 |
|
||||
|
||||
### 2.9 会话管理 (~12 文件)
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `sessionStart.ts` | 会话启动钩子 |
|
||||
| `sessionState.ts` | 会话状态 |
|
||||
| `sessionStorage.ts` | 会话存储（transcript 读写） |
|
||||
| `sessionStoragePortable.ts` | 跨平台会话存储 |
|
||||
| `sessionRestore.ts` | 会话恢复 |
|
||||
| `sessionTitle.ts` | 会话标题 |
|
||||
| `sessionUrl.ts` | 会话 URL |
|
||||
| `sessionActivity.ts` | 会话活动追踪 |
|
||||
| `sessionEnvVars.ts` | 会话环境变量 |
|
||||
| `sessionEnvironment.ts` | 会话环境 |
|
||||
| `concurrentSessions.ts` | 并发会话检测 |
|
||||
| `conversationRecovery.ts` | 对话恢复 |
|
||||
|
||||
### 2.10 其他重要文件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `abortController.ts` | AbortController 工具 |
|
||||
| `array.ts` | 数组工具（count, uniq 等） |
|
||||
| `bufferedWriter.ts` | 缓冲写入 |
|
||||
| `circularBuffer.ts` | 环形缓冲区 |
|
||||
| `cleanupRegistry.ts` | 清理注册表 |
|
||||
| `cron.ts` / `cronScheduler.ts` / `cronTasks.ts` | Cron 定时任务 |
|
||||
| `debug.ts` / `debugFilter.ts` | 调试工具 |
|
||||
| `errors.ts` | 错误处理 |
|
||||
| `fpsTracker.ts` | FPS 追踪 |
|
||||
| `gracefulShutdown.ts` | 优雅关闭 |
|
||||
| `hash.ts` | 哈希工具 |
|
||||
| `http.ts` | HTTP 工具 |
|
||||
| `json.ts` / `jsonRead.ts` | JSON 解析 |
|
||||
| `lockfile.ts` | 文件锁 |
|
||||
| `log.ts` | 日志 |
|
||||
| `memoize.ts` | Memoize 工具 |
|
||||
| `modifiers.ts` | 修饰键检测 |
|
||||
| `platform.ts` | 平台检测 |
|
||||
| `queueProcessor.ts` | 队列处理器 |
|
||||
| `sanitization.ts` | 输入清理 |
|
||||
| `semver.ts` | 语义版本 |
|
||||
| `sequential.ts` | 顺序执行器 |
|
||||
| `signal.ts` | 信号处理 |
|
||||
| `sleep.ts` | 延迟 |
|
||||
| `stringUtils.ts` | 字符串工具 |
|
||||
| `uuid.ts` | UUID 生成/验证 |
|
||||
| `words.ts` | 单词工具 |
|
||||
| `yaml.ts` | YAML 解析 |
|
||||
| `xml.ts` | XML 工具 |
|
||||
| `zodToJsonSchema.ts` | Zod → JSON Schema 转换 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 关键设计模式
|
||||
|
||||
### 3.1 启动预取
|
||||
|
||||
多个文件实现启动时并行预取：
|
||||
- `apiPreconnect.ts` — API 连接预热
|
||||
- `secureStorage/keychainPrefetch.ts` — macOS Keychain 预读
|
||||
- `settings/mdm/rawRead.ts` — MDM 设置预读
|
||||
|
||||
### 3.2 缓存层级
|
||||
|
||||
```
|
||||
内存缓存 (memoize / LRU)
|
||||
→ 文件缓存 (settingsCache, fileReadCache)
|
||||
→ 文件系统 (config.json, settings.json)
|
||||
```
|
||||
|
||||
### 3.3 多源配置合并
|
||||
|
||||
`settings/settings.ts` 实现多层配置合并：
|
||||
```
|
||||
远程管理 → 策略 → 用户 → 项目 → 本地 → CLI → 环境变量
|
||||
(优先级从低到高)
|
||||
```
|
||||
|
||||
### 3.4 安全沙箱
|
||||
|
||||
- `sandbox/sandbox-adapter.ts` — 沙箱适配器
|
||||
- `permissions/dangerousPatterns.ts` — 危险模式检测
|
||||
- `permissions/bashClassifier.ts` — Bash 命令分类器
|
||||
- `permissions/yoloClassifier.ts` — YOLO 分类器
|
||||
|
||||
### 3.5 跨平台兼容
|
||||
|
||||
多处实现平台抽象：
|
||||
- `shell/shellProvider.ts` — Bash/PowerShell 抽象
|
||||
- `secureStorage/` — macOS Keychain / 明文 fallback
|
||||
- `getWorktreePathsPortable.ts` — 跨平台路径
|
||||
- `execFileNoThrowPortable.ts` — 跨平台 exec
|
||||
|
||||
---
|
||||
|
||||
## 4. 依赖关系
|
||||
|
||||
utils/ 是最底层的模块，被所有其他模块依赖：
|
||||
|
||||
```
|
||||
main.tsx → utils/ (config, env, auth, platform, ...)
|
||||
REPL.tsx → utils/ (session, file, git, ...)
|
||||
QueryEngine → utils/ (model, tokens, ...)
|
||||
Tools → utils/ (bash, permissions, ...)
|
||||
Components → utils/ (format, theme, ...)
|
||||
Services → utils/ (http, crypto, ...)
|
||||
|
||||
utils/ ← 无外部依赖（纯工具层）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 代码质量特征
|
||||
|
||||
- **88,500 行**，占项目 17%
|
||||
- **290 + 32×N 个文件**，高度模块化
|
||||
- 大量 memoize 使用（lodash-es）
|
||||
- Zod schema 验证贯穿配置系统
|
||||
- 完善的错误处理（`errors.ts` 统一错误类型）
|
||||
- 详细的调试日志（`debug.ts`, `log.ts`）
|
||||
493
docs/ARCHITECTURE.md
Normal file
493
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,493 @@
|
||||
# Claude Code — 架构全景
|
||||
|
||||
> 项目规模：~1,900 源文件，512,000+ 行 TypeScript/TSX
|
||||
> 运行时：Bun | 终端 UI：React + Ink (自定义渲染器) | CLI：Commander.js
|
||||
|
||||
---
|
||||
|
||||
## 1. 整体架构分层
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ CLI 入口 (main.tsx) │
|
||||
│ Commander.js 参数解析 → 会话初始化 → 渲染上下文 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ REPL 屏幕 (REPL.tsx) │
|
||||
│ 主交互循环：用户输入 → LLM 查询 → 工具执行 → UI 渲染 │
|
||||
├──────────┬──────────┬──────────┬────────────────────────┤
|
||||
│ Commands │ Tools │ Services │ Bridge/Remote │
|
||||
│ (斜杠命令)│ (工具系统)│ (服务层) │ (IDE/远程集成) │
|
||||
├──────────┴──────────┴──────────┴────────────────────────┤
|
||||
│ State Management │
|
||||
│ Zustand store + onChangeAppState + hooks │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Ink 渲染器 (ink/) │
|
||||
│ 自定义 React 渲染器 → 终端 ANSI 输出 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 组件层 (components/) │
|
||||
│ 346 个 React 组件：消息渲染、权限对话框、导航等 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ Hooks 层 (hooks/) │
|
||||
│ 104 个自定义 hooks：输入处理、权限、IDE集成、通知等 │
|
||||
├─────────────────────────────────────────────────────────┤
|
||||
│ 工具函数层 (utils/) │
|
||||
│ ~300 个工具文件：git、shell、权限、插件、模型等 │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 入口与初始化流程
|
||||
|
||||
### main.tsx (4,683 行)
|
||||
|
||||
程序的唯一入口。初始化顺序：
|
||||
|
||||
```
|
||||
1. 启动优化：profileCheckpoint + MDM 子进程 + Keychain 预取 (并行)
|
||||
2. 导入权重模块 (~135ms)
|
||||
3. 检测调试模式 → 拦截调试器
|
||||
4. main() 函数:
|
||||
├─ 安全设置 (Windows PATH 安全)
|
||||
├─ URL 处理 (cc://, deep link, SSH, assistant)
|
||||
├─ 检测 -p/--print (非交互模式) vs 交互模式
|
||||
├─ Commander.js 程序定义 (~100 个 CLI 选项)
|
||||
├─ preAction hook:
|
||||
│ ├─ init() - 配置、认证、特性开关初始化
|
||||
│ ├─ 运行迁移 (11 个版本迁移)
|
||||
│ ├─ 加载远程管理设置
|
||||
│ └─ 加载策略限制
|
||||
└─ 主命令 action:
|
||||
├─ initializeToolPermissionContext()
|
||||
├─ setup() - 工作目录、工作树
|
||||
├─ getCommands() + getAgentDefinitions() (并行)
|
||||
├─ showSetupScreens() - 信任对话框、OAuth、引导
|
||||
├─ MCP 配置加载和连接
|
||||
├─ 构建初始 AppState
|
||||
└─ 分支:
|
||||
├─ --continue → 加载最近对话 → launchRepl()
|
||||
├─ --resume <id> → 恢复指定会话 → launchRepl()
|
||||
├─ --teleport → 远程恢复 → launchRepl()
|
||||
├─ --remote → 远程会话 → launchRepl()
|
||||
├─ -p/--print → runHeadless() (非交互)
|
||||
└─ 默认 → launchRepl() (新会话)
|
||||
```
|
||||
|
||||
### 初始化优化策略
|
||||
|
||||
- **并行预取**：MDM 读取、Keychain 读取、API 预连接在导入前并行启动
|
||||
- **延迟加载**：OpenTelemetry (~400KB)、gRPC (~700KB) 等通过 `import()` 延迟
|
||||
- **Feature Flag 死码消除**：`bun:bundle` 的 `feature()` 在构建时裁剪未启用的功能
|
||||
- **Memoize 缓存**：`getCommands()`、`getTools()` 等昂贵操作通过 lodash memoize 缓存
|
||||
|
||||
### Feature Flags (关键)
|
||||
|
||||
| Flag | 功能 |
|
||||
|------|------|
|
||||
| `PROACTIVE` / `KAIROS` | 主动模式 / 助手模式 |
|
||||
| `BRIDGE_MODE` | 远程控制 (Remote Control) |
|
||||
| `DIRECT_CONNECT` | cc:// URL 直连 |
|
||||
| `SSH_REMOTE` | SSH 远程会话 |
|
||||
| `COORDINATOR_MODE` | 多 Agent 协调模式 |
|
||||
| `TRANSCRIPT_CLASSIFIER` | 自动模式 (auto-mode) |
|
||||
| `VOICE_MODE` | 语音输入 |
|
||||
| `AGENT_TRIGGERS` | Cron 定时触发 |
|
||||
| `WORKFLOW_SCRIPTS` | 工作流脚本 |
|
||||
| `TERMINAL_PANEL` | 终端面板捕获 |
|
||||
| `WEB_BROWSER_TOOL` | 内嵌浏览器 |
|
||||
|
||||
---
|
||||
|
||||
## 3. REPL 交互循环 (REPL.tsx, 5,005 行)
|
||||
|
||||
核心交互界面。数据流：
|
||||
|
||||
```
|
||||
用户输入 (PromptInput)
|
||||
│
|
||||
├─ /命令 → processSlashCommand() → 命令处理
|
||||
│
|
||||
└─ 普通文本 → processUserInput()
|
||||
│
|
||||
├─ fetchSystemPromptParts() → 系统提示
|
||||
├─ loadMemoryPrompt() → 记忆
|
||||
├─ buildEffectiveSystemPrompt() → 合成最终系统提示
|
||||
│
|
||||
└─ query() [QueryEngine.ts, 1,295 行]
|
||||
│
|
||||
├─ API 调用 (Anthropic SDK, 流式)
|
||||
├─ 思考模式 (thinking config)
|
||||
├─ Token 预算管理
|
||||
│
|
||||
└─ 工具调用循环:
|
||||
│
|
||||
├─ 工具使用块 → 权限检查
|
||||
│ ├─ 通过 → 执行工具
|
||||
│ └─ 拒绝 → 提示用户批准/拒绝
|
||||
│
|
||||
└─ 继续 API 调用直到完成
|
||||
```
|
||||
|
||||
### QueryEngine.ts 核心职责
|
||||
|
||||
1. 构建 API 请求（消息、系统提示、工具定义）
|
||||
2. 处理流式响应（thinking、工具使用、文本）
|
||||
3. Token 计数和预算管理
|
||||
4. 重试逻辑和错误处理
|
||||
5. 紧凑/压缩触发
|
||||
6. 副本记录 (transcript recording)
|
||||
|
||||
---
|
||||
|
||||
## 4. 状态管理
|
||||
|
||||
### AppStateStore.ts (569 行)
|
||||
|
||||
使用自定义的 `createStore()` 实现（非 Redux，非 Zustand），类型安全。
|
||||
|
||||
核心状态字段：
|
||||
|
||||
```typescript
|
||||
AppState {
|
||||
// 核心
|
||||
verbose: boolean
|
||||
mainLoopModel: ModelSetting
|
||||
toolPermissionContext: ToolPermissionContext
|
||||
isBriefOnly: boolean
|
||||
|
||||
// MCP
|
||||
mcp: { clients, tools, commands, resources }
|
||||
|
||||
// 插件
|
||||
plugins: { enabled, disabled, commands, errors }
|
||||
|
||||
// 远程控制
|
||||
replBridgeEnabled: boolean
|
||||
replBridgeConnected: boolean
|
||||
|
||||
// 任务
|
||||
tasks: Record<string, TaskState>
|
||||
todos: Record<string, TodoList>
|
||||
|
||||
// 团队
|
||||
teamContext: TeamContext
|
||||
|
||||
// 通知
|
||||
notifications: { current, queue }
|
||||
|
||||
// 会话
|
||||
inbox: { messages }
|
||||
speculation: SpeculationState
|
||||
attribution: AttributionState
|
||||
sessionHooks: Map
|
||||
}
|
||||
```
|
||||
|
||||
### onChangeAppState
|
||||
|
||||
状态变更时触发的副作用集合。`store.setState()` 后会执行 `onChangeAppState` 中注册的所有回调。
|
||||
|
||||
---
|
||||
|
||||
## 5. 工具系统 (tools/, 42 个工具)
|
||||
|
||||
### 工具接口 (Tool.ts, 792 行)
|
||||
|
||||
每个工具实现 `Tool` 接口：
|
||||
|
||||
```typescript
|
||||
Tool {
|
||||
name: string // 工具名称
|
||||
description: string // 描述 (用于系统提示)
|
||||
inputSchema: JSONSchema // 输入 JSON Schema
|
||||
userFacingName(): string // 用户显示名
|
||||
isEnabled(): boolean // 是否启用
|
||||
needsPermissions(input): boolean // 是否需要权限
|
||||
call(input, context): Result // 执行函数
|
||||
renderToolUseMessage(input): UI // UI 渲染
|
||||
renderToolResultMessage(): UI // 结果渲染
|
||||
}
|
||||
```
|
||||
|
||||
### 核心工具分类
|
||||
|
||||
**文件操作**: FileReadTool, FileEditTool, FileWriteTool, GlobTool, GrepTool
|
||||
**执行**: BashTool, PowerShellTool (Windows)
|
||||
**AI**: AgentTool (子 Agent), SkillTool (技能执行)
|
||||
**外部**: WebFetchTool, WebSearchTool
|
||||
**MCP**: MCPTool, ListMcpResourcesTool, ReadMcpResourceTool
|
||||
**规划**: EnterPlanModeTool, ExitPlanModeV2Tool
|
||||
**任务**: TaskCreateTool, TaskGetTool, TaskUpdateTool, TaskListTool, TaskStopTool
|
||||
**团队**: TeamCreateTool, TeamDeleteTool, SendMessageTool
|
||||
**其他**: TodoWriteTool, BriefTool, AskUserQuestionTool, ConfigTool
|
||||
|
||||
### 工具执行流程
|
||||
|
||||
```
|
||||
1. QueryEngine 产出 ToolUseBlock
|
||||
2. useCanUseTool hook → 权限检查
|
||||
3. 工具 handler 执行
|
||||
4. 结果 → ToolResultBlock → 回到 QueryEngine
|
||||
```
|
||||
|
||||
### 权限系统
|
||||
|
||||
`ToolPermissionContext` 定义权限模式：
|
||||
- `default` — 每次询问用户
|
||||
- `plan` — 只读，编辑需批准
|
||||
- `bypassPermissions` — 跳过所有检查（危险）
|
||||
- `auto` — 基于分类器自动决策
|
||||
|
||||
权限规则通过 `PermissionRule` 配置，支持 allow/deny 规则匹配。
|
||||
|
||||
---
|
||||
|
||||
## 6. 命令系统 (commands/, 80+ 命令)
|
||||
|
||||
### 命令类型
|
||||
|
||||
- **`prompt` 型** — 扩展为文本发送给 LLM（如 `/commit`）
|
||||
- **`local` 型** — 本地执行并显示结果（如 `/cost`）
|
||||
- **`local-jsx` 型** — 渲染 JSX UI（如 `/config`）
|
||||
|
||||
### 命令来源
|
||||
|
||||
1. **内置命令** — `commands.ts` 中的 `COMMANDS()` (memoize)
|
||||
2. **技能命令** — `skills/` 目录中的 `.md` 文件
|
||||
3. **插件命令** — 插件注册的命令
|
||||
4. **Bundled 技能** — `skills/bundled/` 中的内置技能
|
||||
5. **MCP 命令** — MCP 服务器提供的 prompt 资源
|
||||
|
||||
### 加载优先级
|
||||
|
||||
```
|
||||
Bundled Skills → Plugin Skills → Skill Dir → Workflows → Plugin Commands → Built-in
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 服务层 (services/)
|
||||
|
||||
### 核心服务
|
||||
|
||||
| 服务 | 职责 |
|
||||
|------|------|
|
||||
| `api/` | Anthropic API 客户端、使用量跟踪、bootstrap |
|
||||
| `mcp/` | MCP 协议：服务器连接、工具发现、认证 |
|
||||
| `oauth/` | OAuth 2.0 认证流程 |
|
||||
| `lsp/` | LSP 语言服务器管理 |
|
||||
| `analytics/` | GrowthBook 特性开关 + 遥测 |
|
||||
| `compact/` | 上下文压缩（microcompact、auto-compact） |
|
||||
| `plugins/` | 插件安装、加载、版本管理 |
|
||||
| `extractMemories/` | 自动记忆提取 |
|
||||
| `tokenEstimation.ts` | Token 计数估算 |
|
||||
| `teamMemorySync/` | 团队记忆同步 |
|
||||
| `tips/` | 提示系统 |
|
||||
| `policyLimits/` | 组织策略限制 |
|
||||
|
||||
---
|
||||
|
||||
## 8. Bridge / 远程系统 (bridge/, remote/, server/)
|
||||
|
||||
### Bridge (IDE 集成)
|
||||
|
||||
双向通信层，连接 VS Code / JetBrains 扩展与 CLI。
|
||||
|
||||
```
|
||||
IDE Extension ←── JSON-RPC ──→ Bridge Manager ←── Session ──→ REPL
|
||||
(ws/stdio) (权限桥接)
|
||||
```
|
||||
|
||||
关键组件：
|
||||
- `bridgeMain.ts` — 桥接主循环
|
||||
- `bridgeMessaging.ts` — 消息协议
|
||||
- `bridgePermissionCallbacks.ts` — 权限回调代理
|
||||
- `replBridge.ts` — REPL 会话桥接
|
||||
- `sessionRunner.ts` — 会话执行管理
|
||||
- `trustedDevice.ts` — 可信设备认证
|
||||
|
||||
### Remote Control
|
||||
|
||||
用户从 claude.ai/web/mobile 控制本地会话：
|
||||
- `bridge/bridgeMain.ts` — 服务器连接
|
||||
- `remote/RemoteSessionManager.ts` — 远程会话管理
|
||||
- `remote/SessionsWebSocket.ts` — WebSocket 连接
|
||||
|
||||
### Server 模式
|
||||
|
||||
独立的 HTTP 服务器模式（`server/`），支持多会话并发。
|
||||
|
||||
---
|
||||
|
||||
## 9. Ink 渲染器 (ink/, 96 个文件)
|
||||
|
||||
**自定义的 React 终端渲染器**，不是直接使用 npm ink 包，而是 fork 并深度定制。
|
||||
|
||||
核心模块：
|
||||
- `reconciler.ts` — React reconciler 实现
|
||||
- `renderer.ts` — 终端 ANSI 输出渲染
|
||||
- `layout/` — Yoga 布局引擎集成
|
||||
- `events/` — 键盘/鼠标/终端事件系统
|
||||
- `screen.ts` — 屏幕管理
|
||||
- `selection.ts` — 文本选择
|
||||
- `searchHighlight.ts` — 搜索高亮
|
||||
- `termio/` — 终端 I/O 解析（ANSI/CSI/OSC/SGR）
|
||||
|
||||
---
|
||||
|
||||
## 10. 钩子系统 (hooks/)
|
||||
|
||||
### 工具权限钩子
|
||||
|
||||
```
|
||||
toolPermission/
|
||||
├── PermissionContext.ts — 权限上下文
|
||||
├── handlers/
|
||||
│ ├── interactiveHandler.ts — 交互模式处理器
|
||||
│ ├── coordinatorHandler.ts — 协调器模式处理器
|
||||
│ └── swarmWorkerHandler.ts — Swarm 工作器处理器
|
||||
└── permissionLogging.ts — 权限日志
|
||||
```
|
||||
|
||||
### 通知钩子
|
||||
|
||||
`hooks/notifs/` — 16 个通知钩子，处理各种状态通知（模型迁移、速率限制、IDE 状态等）。
|
||||
|
||||
### 关键 hooks
|
||||
|
||||
| Hook | 职责 |
|
||||
|------|------|
|
||||
| `useReplBridge.tsx` | 远程控制桥接 |
|
||||
| `useCanUseTool.tsx` | 工具权限检查 |
|
||||
| `useGlobalKeybindings.tsx` | 全局键盘快捷键 |
|
||||
| `useVoice.ts` / `useVoiceIntegration.tsx` | 语音输入 |
|
||||
| `useTasksV2.ts` | 任务管理 |
|
||||
| `useSwarmInitialization.ts` | Swarm 团队初始化 |
|
||||
| `useMergedTools.ts` | 工具池合并 (内置 + MCP) |
|
||||
| `useMergedCommands.ts` | 命令池合并 |
|
||||
| `useSettings.ts` | 设置管理 |
|
||||
|
||||
---
|
||||
|
||||
## 11. 插件系统 (plugins/)
|
||||
|
||||
### 架构
|
||||
|
||||
```
|
||||
plugins/
|
||||
├── builtinPlugins.ts — 内置插件列表
|
||||
├── bundled/
|
||||
│ └── index.ts — 捆绑插件初始化
|
||||
utils/plugins/
|
||||
├── pluginLoader.ts — 插件加载器
|
||||
├── installedPluginsManager.ts — 已安装插件管理
|
||||
├── marketplaceManager.ts — 市场管理
|
||||
├── validatePlugin.ts — 插件验证
|
||||
├── loadPluginCommands.ts — 加载插件命令
|
||||
├── loadPluginHooks.ts — 加载插件钩子
|
||||
├── loadPluginAgents.ts — 加载插件 Agent
|
||||
└── loadPluginOutputStyles.ts — 加载输出样式
|
||||
```
|
||||
|
||||
插件可以提供：命令、工具、钩子、Agent 定义、输出样式。
|
||||
|
||||
---
|
||||
|
||||
## 12. 配置系统
|
||||
|
||||
### 多层级配置
|
||||
|
||||
```
|
||||
1. 远程管理设置 (enterprise MDM)
|
||||
2. 策略设置 (organization policy)
|
||||
3. 用户设置 (~/.claude/settings.json)
|
||||
4. 项目设置 (.claude/settings.json)
|
||||
5. 本地设置 (.claude/settings.local.json)
|
||||
6. CLI 标志 (--model, --permission-mode 等)
|
||||
7. 环境变量 (ANTHROPIC_API_KEY, CLAUDE_CODE_* 等)
|
||||
```
|
||||
|
||||
### 设置验证
|
||||
|
||||
`utils/settings/validation.ts` — Zod schema 验证，支持类型检查和错误报告。
|
||||
|
||||
### 迁移系统
|
||||
|
||||
`migrations/` — 11 个版本迁移脚本，按序号执行（模型名称迁移、配置迁移等）。
|
||||
|
||||
---
|
||||
|
||||
## 13. 记忆系统 (memdir/)
|
||||
|
||||
```
|
||||
memdir/
|
||||
├── memdir.ts — 记忆目录操作
|
||||
├── paths.ts — 路径解析
|
||||
├── memoryScan.ts — 记忆扫描
|
||||
├── memoryAge.ts — 记忆年龄管理
|
||||
├── memoryTypes.ts — 类型定义
|
||||
├── findRelevantMemories.ts — 相关记忆查找
|
||||
├── teamMemPaths.ts — 团队记忆路径
|
||||
└── teamMemPrompts.ts — 团队记忆提示
|
||||
```
|
||||
|
||||
记忆存储在 `~/.claude/memory/` 目录，自动从对话中提取。
|
||||
|
||||
---
|
||||
|
||||
## 14. 性能优化
|
||||
|
||||
### 启动优化
|
||||
|
||||
1. **并行子进程**：MDM 读取 + Keychain 预取 + 导入并行 (~135ms)
|
||||
2. **延迟加载**：重型模块动态导入（OpenTelemetry, gRPC, print.ts）
|
||||
3. **Feature Flag DCE**：未启用的功能在构建时完全裁剪
|
||||
4. **Memoize**：`getCommands()`, `getTools()`, `getSkills()` 等结果缓存
|
||||
5. **预连接**：API 预连接在用户输入前完成
|
||||
|
||||
### 运行时优化
|
||||
|
||||
1. **Token 预算**：上下文压缩触发管理
|
||||
2. **文件历史快照**：高效的文件变更追踪
|
||||
3. **虚拟滚动**：`VirtualMessageList` 支持大量消息
|
||||
4. **流式渲染**：增量 ANSI 输出
|
||||
|
||||
---
|
||||
|
||||
## 15. 关键数据流总结
|
||||
|
||||
```
|
||||
用户输入
|
||||
│
|
||||
├→ /command → processSlashCommand → 命令执行 → 可能触发 query()
|
||||
│
|
||||
└→ 文本输入 → processUserInput
|
||||
│
|
||||
├→ processBashCommand (以 ! 开头)
|
||||
└→ processTextPrompt
|
||||
│
|
||||
└→ QueryEngine.query()
|
||||
│
|
||||
├→ 构建 system prompt (fetchSystemPromptParts + buildEffectiveSystemPrompt)
|
||||
├→ 构建 messages (对话历史)
|
||||
├→ 构建 tools (getTools + MCP tools)
|
||||
│
|
||||
├→ API 调用 (Anthropic SDK, streaming)
|
||||
│
|
||||
└→ 循环处理响应:
|
||||
│
|
||||
├→ text block → 显示消息
|
||||
├→ thinking block → 显示思考过程
|
||||
└→ tool_use block → 权限检查 → 执行 → 结果回传 API
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 附录：详细模块文档
|
||||
|
||||
- [Tools 详细分析](./ARCHITECTURE-TOOLS.md)
|
||||
- [Services 详细分析](./ARCHITECTURE-SERVICES.md)
|
||||
- [Components 详细分析](./ARCHITECTURE-COMPONENTS.md)
|
||||
- [Bridge/Remote 详细分析](./ARCHITECTURE-BRIDGE-REMOTE.md)
|
||||
- [Utils 详细分析](./ARCHITECTURE-UTILS.md)
|
||||
- [Commands/Skills/Plugins 详细分析](./ARCHITECTURE-COMMANDS.md)
|
||||
354
docs/BUILD.md
Normal file
354
docs/BUILD.md
Normal file
@@ -0,0 +1,354 @@
|
||||
# Claude Code 编译与运行指南
|
||||
|
||||
> 基于 2026-03-31 泄露的 Claude Code CLI 源码
|
||||
> 最后更新：2026-04-01
|
||||
|
||||
---
|
||||
|
||||
## 1. 前置条件
|
||||
|
||||
### 1.1 必须安装
|
||||
|
||||
| 工具 | 版本 | 安装命令 |
|
||||
|------|------|----------|
|
||||
| **Bun** | 1.3+ | `curl -fsSL https://bun.sh/install \| bash` |
|
||||
| **Node.js** | 18+ | 已有则跳过（Bun 自带 npm） |
|
||||
|
||||
### 1.2 验证安装
|
||||
|
||||
```bash
|
||||
bun --version # 应输出 1.x.x
|
||||
node --version # 应输出 v18+ 或 v22+
|
||||
```
|
||||
|
||||
### 1.3 工作目录
|
||||
|
||||
所有命令在以下目录执行：
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace/claude-code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 项目结构概览
|
||||
|
||||
```
|
||||
claude-code/
|
||||
├── src/ # 源码（1,886 个 TypeScript 文件）
|
||||
│ ├── main.tsx # CLI 入口（4,683 行）
|
||||
│ ├── QueryEngine.ts # LLM 查询引擎（1,295 行）
|
||||
│ ├── Tool.ts # 工具接口定义（792 行）
|
||||
│ ├── commands.ts # 命令注册（754 行）
|
||||
│ ├── tools.ts # 工具注册（389 行）
|
||||
│ ├── screens/ # 全屏 UI（REPL.tsx 5,005 行）
|
||||
│ ├── components/ # React 组件（346 个）
|
||||
│ ├── tools/ # 工具实现（42 个目录）
|
||||
│ ├── services/ # 服务层（21 个子目录）
|
||||
│ ├── commands/ # 斜杠命令（80+ 个）
|
||||
│ ├── utils/ # 工具函数（290+ 文件, 88K 行）
|
||||
│ ├── hooks/ # React hooks（104 个）
|
||||
│ ├── bridge/ # IDE 桥接（31 文件）
|
||||
│ └── ink/ # 自定义 Ink 渲染器（96 文件）
|
||||
├── shims/ # 编译 shim
|
||||
│ ├── bun-bundle.ts # bun:bundle feature() 替代
|
||||
│ └── macro.ts # MACRO 全局变量注入
|
||||
├── dist/ # 编译输出
|
||||
├── ARCHITECTURE*.md # 架构文档（7 份）
|
||||
└── package.json # 依赖声明
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 缺失文件与修复
|
||||
|
||||
泄露的源码不完整。以下是编译前必须补充的内容：
|
||||
|
||||
### 3.1 缺失的源文件（22 个 stub）
|
||||
|
||||
这些文件在 `src/` 下，是内部工具引用但泄露包中不存在的：
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `src/global.d.ts` | TypeScript 全局类型声明 |
|
||||
| `src/utils/protectedNamespace.ts` | 命名空间保护检查 |
|
||||
| `src/utils/useEffectEvent.ts` | React useEffectEvent shim |
|
||||
| `src/entrypoints/sdk/coreTypes.generated.ts` | SDK 生成类型 |
|
||||
| `src/entrypoints/sdk/runtimeTypes.ts` | SDK 运行时类型 |
|
||||
| `src/entrypoints/sdk/toolTypes.ts` | SDK 工具类型 |
|
||||
| `src/tools/REPLTool/REPLTool.ts` | REPL 工具 stub |
|
||||
| `src/tools/SuggestBackgroundPRTool/` | PR 建议工具 stub |
|
||||
| `src/tools/VerifyPlanExecutionTool/` | 计划验证工具 stub |
|
||||
| `src/tools/WorkflowTool/` | 工作流工具 stub |
|
||||
| `src/tools/TungstenTool/TungstenLiveMonitor.tsx` | Tungsten 监控 stub |
|
||||
| `src/commands/agents-platform/` | Agent 平台命令 stub |
|
||||
| `src/commands/assistant/` | 助手命令 stub |
|
||||
| `src/components/agents/SnapshotUpdateDialog.tsx` | 快照对话框 stub |
|
||||
| `src/assistant/AssistantSessionChooser.tsx` | 会话选择器 stub |
|
||||
| `src/services/compact/snipCompact.ts` | 剪裁压缩 stub |
|
||||
| `src/services/compact/cachedMicrocompact.ts` | 微压缩 stub |
|
||||
| `src/services/contextCollapse/` | 上下文折叠 stub |
|
||||
| `src/ink/devtools.ts` | 开发工具 stub |
|
||||
| `src/skills/bundled/verify/` | 验证 skill stub |
|
||||
| `src/utils/filePersistence/types.ts` | 文件持久化类型 stub |
|
||||
|
||||
这些 stub 已经在仓库中，编译时会自动包含。
|
||||
|
||||
### 3.2 缺失的 npm 包
|
||||
|
||||
泄露的 `package.json` 缺少 28 个依赖。运行以下命令安装：
|
||||
|
||||
```bash
|
||||
bun install
|
||||
```
|
||||
|
||||
这会安装 `package.json` 中声明的所有依赖（已补充完整）。
|
||||
|
||||
### 3.3 内部 Anthropic 包（stub）
|
||||
|
||||
以下两个包是 Anthropic 内部包，无法从 npm 安装：
|
||||
|
||||
- `@ant/claude-for-chrome-mcp` — Chrome 集成 MCP
|
||||
- `@anthropic-ai/sandbox-runtime` — 沙箱运行时
|
||||
|
||||
它们在 `node_modules/` 中以 stub 形式存在（已创建）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 需要修改的源码
|
||||
|
||||
### 4.1 Commander.js 短标志
|
||||
|
||||
原代码使用 `-d2e` 这种多字符短标志，Commander.js 不支持。
|
||||
|
||||
**修改文件**：`node_modules/commander/lib/option.js`
|
||||
|
||||
```javascript
|
||||
// 原代码
|
||||
const shortFlagExp = /^-[^-]$/;
|
||||
|
||||
// 修改为（允许任意长度短标志）
|
||||
const shortFlagExp = /^-[^-]+$/;
|
||||
```
|
||||
|
||||
> ⚠️ 修改的是 `node_modules/` 中的文件。每次 `bun install` 后需要重新修改。建议创建 postinstall 脚本自动 patch。
|
||||
|
||||
### 4.2 MACRO 全局变量
|
||||
|
||||
原代码使用 `MACRO.VERSION` 等全局变量，Bun 编译时会自动注入。开源版本没有这个机制。
|
||||
|
||||
**创建文件**：`shims/macro.ts`
|
||||
|
||||
```typescript
|
||||
globalThis.MACRO = {
|
||||
VERSION: "1.0.0",
|
||||
BUILD_TIME: undefined,
|
||||
ISSUES_EXPLAINER: "https://github.com/anthropics/claude-code/issues",
|
||||
FEEDBACK_CHANNEL: "#claude-code-feedback",
|
||||
NATIVE_PACKAGE_URL: "https://claude.ai/download",
|
||||
PACKAGE_URL: "https://www.npmjs.com/package/@anthropic-ai/claude-code",
|
||||
VERSION_CHANGELOG: "https://github.com/anthropics/claude-code/releases",
|
||||
};
|
||||
```
|
||||
|
||||
编译时作为额外入口点注入。
|
||||
|
||||
### 4.3 bun:bundle feature()
|
||||
|
||||
原代码使用 `import { feature } from 'bun:bundle'` 实现编译时死码消除。开源 Bun 没有这个功能。
|
||||
|
||||
**创建文件**：`shims/bun-bundle.ts`
|
||||
|
||||
```typescript
|
||||
export function feature(name: string): boolean {
|
||||
const flags: Record<string, boolean> = {
|
||||
WORKFLOW_SCRIPTS: false,
|
||||
AGENT_TRIGGERS: false,
|
||||
// ... 其他 flag 默认 false
|
||||
};
|
||||
return flags[name] ?? false;
|
||||
}
|
||||
```
|
||||
|
||||
Bun 的 `bunfig.toml` 配置了 `.js` → `.ts` 的 loader 映射，会自动解析这个 shim。
|
||||
|
||||
### 4.4 useEffectEvent 兼容
|
||||
|
||||
代码使用了 React 19 实验性 Hook `useEffectEvent`，但 `react-reconciler@0.31` 不支持。
|
||||
|
||||
**创建文件**：`src/utils/useEffectEvent.ts`
|
||||
|
||||
```typescript
|
||||
import { useCallback, useRef } from 'react';
|
||||
|
||||
export function useEffectEvent<T extends (...args: any[]) => any>(callback: T): T {
|
||||
const ref = useRef(callback);
|
||||
ref.current = callback;
|
||||
return useCallback(((...args: any[]) => ref.current(...args)) as T, []);
|
||||
}
|
||||
```
|
||||
|
||||
**修改**：`src/components/tasks/BackgroundTasksDialog.tsx` 和 `src/state/AppState.tsx` 中将 `import { ... useEffectEvent ... } from 'react'` 改为从 `../../utils/useEffectEvent.js` 导入。
|
||||
|
||||
### 4.5 版本检查跳过
|
||||
|
||||
原代码调用 `assertMinVersion()` 检查远程最低版本配置，会访问 Anthropic 服务器。
|
||||
|
||||
**修改文件**：`src/utils/autoUpdater.ts`
|
||||
|
||||
```typescript
|
||||
export async function assertMinVersion(): Promise<void> {
|
||||
return; // 直接返回，跳过检查
|
||||
// ... 原有代码
|
||||
}
|
||||
```
|
||||
|
||||
### 4.6 组织验证跳过
|
||||
|
||||
原代码调用 `validateForceLoginOrg()` 检查组织限制。
|
||||
|
||||
**修改文件**：`src/main.tsx`
|
||||
|
||||
注释掉两处 `validateForceLoginOrg` 调用（约第 2302 行和第 2614 行）：
|
||||
|
||||
```typescript
|
||||
// const orgValidation = await validateForceLoginOrg();
|
||||
// if (!orgValidation.valid) {
|
||||
// process.exit(1);
|
||||
// }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 编译步骤
|
||||
|
||||
### 5.1 完整编译命令
|
||||
|
||||
```bash
|
||||
cd ~/.openclaw/workspace/claude-code
|
||||
|
||||
# 1. 安装依赖
|
||||
bun install
|
||||
|
||||
# 2. 编译 TypeScript → JavaScript bundle
|
||||
bun build shims/macro.ts src/main.tsx --target=bun --outdir=./dist
|
||||
|
||||
# 3. 合并为单文件（macro shim + main bundle + auto-execute）
|
||||
cat dist/shims/macro.js dist/src/main.js > dist/bundle.js
|
||||
echo 'if (typeof main === "function") main().catch(e => { console.error(e); process.exit(1); });' >> dist/bundle.js
|
||||
```
|
||||
|
||||
### 5.2 编译结果
|
||||
|
||||
```
|
||||
Bundled 5745 modules in ~300ms
|
||||
dist/bundle.js ~23 MB (单文件可执行)
|
||||
```
|
||||
|
||||
- **模块数**：5,745（含源码 + 依赖）
|
||||
- **文件大小**：~23 MB
|
||||
- **编译时间**：~300ms
|
||||
- **输出**：`dist/bundle.js`（单文件）
|
||||
|
||||
### 5.3 一键编译脚本
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
set -e
|
||||
cd ~/.openclaw/workspace/claude-code
|
||||
|
||||
echo "Building..."
|
||||
bun build shims/macro.ts src/main.tsx --target=bun --outdir=./dist 2>&1
|
||||
|
||||
echo "Bundling..."
|
||||
cat dist/shims/macro.js dist/src/main.js > dist/bundle.js
|
||||
echo 'if (typeof main === "function") main().catch(e => { console.error(e); process.exit(1); });' >> dist/bundle.js
|
||||
|
||||
echo "Done: $(ls -lh dist/bundle.js | awk '{print $5}')"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 运行
|
||||
|
||||
### 6.1 基本用法
|
||||
|
||||
```bash
|
||||
# 查看帮助（不需要 API key）
|
||||
bun dist/bundle.js --help
|
||||
|
||||
# 查看 MCP 子命令帮助
|
||||
bun dist/bundle.js mcp --help
|
||||
|
||||
# 查看版本
|
||||
bun dist/bundle.js --version
|
||||
```
|
||||
|
||||
### 6.2 交互模式（需要真实终端）
|
||||
|
||||
```bash
|
||||
# 进入 REPL 交互界面
|
||||
bun dist/bundle.js
|
||||
```
|
||||
|
||||
会显示：
|
||||
1. **信任对话框** — 确认信任当前目录
|
||||
2. **欢迎界面** — Logo + 版本信息
|
||||
3. **REPL 输入框** — 等待输入
|
||||
|
||||
### 6.3 非交互模式（-p）
|
||||
|
||||
```bash
|
||||
# 需要 API key
|
||||
export ANTHROPIC_API_KEY=你的密钥
|
||||
bun dist/bundle.js -p "say hello"
|
||||
```
|
||||
|
||||
### 6.4 配置管理
|
||||
|
||||
```bash
|
||||
# 添加 MCP 服务器
|
||||
bun dist/bundle.js mcp add myserver http://localhost:3000
|
||||
|
||||
# 查看配置
|
||||
bun dist/bundle.js config
|
||||
|
||||
# 查看已添加的 MCP 服务器
|
||||
bun dist/bundle.js mcp list
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 文档索引
|
||||
|
||||
### 7.1 API 配置
|
||||
|
||||
完整的 API 配置指南（环境变量、认证方式、多云后端、代理、mTLS）：
|
||||
|
||||
→ **[API-CONFIG.md](./API-CONFIG.md)**
|
||||
|
||||
### 7.2 架构文档
|
||||
|
||||
项目包含 8 份架构分析文档：
|
||||
|
||||
| 文档 | 大小 | 内容 |
|
||||
|------|------|------|
|
||||
| `ARCHITECTURE.md` | 20KB | 全景架构总览 |
|
||||
| `ARCHITECTURE-TOOLS.md` | 24KB | 43 个工具详细分析 |
|
||||
| `ARCHITECTURE-SERVICES.md` | 28KB | 21 个服务详细分析 |
|
||||
| `ARCHITECTURE-COMPONENTS.md` | 28KB | 389 个组件分析 |
|
||||
| `ARCHITECTURE-COMMANDS.md` | 24KB | 60+ 命令/Skill/Plugin |
|
||||
| `ARCHITECTURE-UTILS.md` | 12KB | 290+ 工具文件 |
|
||||
| `ARCHITECTURE-BRIDGE-REMOTE.md` | 12KB | Bridge/Remote/Coordinator |
|
||||
| `REFACTORING-ASSESSMENT.md` | 12KB | 重构可行性评估 |
|
||||
| **`API-CONFIG.md`** | **10KB** | **API 配置完整参考** |
|
||||
|
||||
---
|
||||
|
||||
## 8. 已知问题
|
||||
|
||||
1. **TUI 需要真实终端** — SSH 管道或非 TTY 环境下会静默退出
|
||||
2. **API 调用需要密钥** — 没有 `ANTHROPIC_API_KEY` 时发送消息会失败
|
||||
3. **部分功能为 stub** — REPLTool、WorkflowTool 等是空实现
|
||||
4. **macOS Keychain** — 安全存储在 Linux 上回退到明文文件
|
||||
5. **Windows 支持** — PowerShell 工具需要 Windows 环境测试
|
||||
358
docs/REFACTORING-ASSESSMENT.md
Normal file
358
docs/REFACTORING-ASSESSMENT.md
Normal file
@@ -0,0 +1,358 @@
|
||||
# Claude Code 重构可行性评估
|
||||
|
||||
> 评估日期：2026-03-31
|
||||
> 基于 7 份架构文档 + 源码静态分析
|
||||
> 项目规模：1,886 源文件，512,670 行 TypeScript/TSX
|
||||
|
||||
---
|
||||
|
||||
## 1. 架构耦合度评估
|
||||
|
||||
### 1.1 God Modules（巨型模块）
|
||||
|
||||
| 文件 | 行数 | 被引用数 | 导出数 | 问题 |
|
||||
|------|------|----------|--------|------|
|
||||
| `bootstrap/state.ts` | 1,758 | **251** | **215** | 经典 God Module — 全局状态容器，session/cost/duration/cwd 全塞一个文件 |
|
||||
| `utils/messages.ts` | 5,512 | 108 | 80+ | 消息常量 + 工具函数混杂，5500 行纯工具文件 |
|
||||
| `utils/sessionStorage.ts` | 5,105 | — | — | 会话存储逻辑臃肿 |
|
||||
| `utils/hooks.ts` | 5,022 | — | — | 与 React hooks 概念冲突（在 utils/ 下） |
|
||||
| `utils/attachments.ts` | 3,997 | — | — | 附件处理逻辑过于集中 |
|
||||
| `Tool.js` | ~792 | **259** | — | 工具接口定义被 259 个文件引用，变更成本极高 |
|
||||
| `state/AppState.ts` | 1,190 | **171** | — | 应用状态类型 + store 混合 |
|
||||
| `utils/config.ts` | 1,817 | **129** | — | 配置读写 + 全局缓存混杂 |
|
||||
|
||||
**关键判断：** `bootstrap/state.ts` 是最严重的耦合瓶颈。215 个导出、251 个消费者，任何修改都可能波及半个代码库。它本质上是一个伪装成模块的全局变量空间。
|
||||
|
||||
### 1.2 巨型文件
|
||||
|
||||
| 文件 | 行数 | 职责 | 问题 |
|
||||
|------|------|------|------|
|
||||
| `cli/print.ts` | 5,594 | 非交互输出模式 | 单文件 5500+ 行，职责不清 |
|
||||
| `screens/REPL.tsx` | 5,005 | 主交互循环 | 244 个 import，是项目中 import 最多的文件 |
|
||||
| `main.tsx` | 4,683 | CLI 入口 | 164 个 import，初始化 + 参数解析 + 会话管理全混 |
|
||||
| `utils/bash/bashParser.ts` | 4,436 | Bash 解析 | 单一职责但体积过大 |
|
||||
| `services/api/claude.ts` | 3,419 | API 客户端 | API 调用 + 流处理 + 重试 + token 管理 |
|
||||
| `services/mcp/client.ts` | 3,348 | MCP 客户端 | 协议 + 连接 + 工具发现 + 资源管理 |
|
||||
| `utils/plugins/pluginLoader.ts` | 3,302 | 插件加载 | 安装 + 验证 + 加载 + 版本管理 |
|
||||
| `commands/insights.ts` | 3,200 | Insights 命令 | 单命令文件过大 |
|
||||
| `bridge/bridgeMain.ts` | 2,999 | Bridge 主循环 | IDE 集成核心，耦合多协议 |
|
||||
|
||||
### 1.3 循环依赖与耦合热点
|
||||
|
||||
#### 确认的高耦合区域
|
||||
|
||||
```
|
||||
bootstrap/state.ts ←——→ 251 个文件（星型拓扑，所有东西都连它）
|
||||
↑
|
||||
├── REPL.tsx (直接引用多个 state getter/setter)
|
||||
├── main.tsx (直接引用多个 state getter/setter)
|
||||
├── QueryEngine.ts
|
||||
├── 几乎所有 commands/
|
||||
├── 几乎所有 tools/
|
||||
└── 大部分 hooks/
|
||||
```
|
||||
|
||||
#### 潜在循环依赖
|
||||
|
||||
1. **`tools.ts` ↔ `commands.ts`**：tools.ts 不直接引用 commands.ts，但 QueryEngine.ts 同时引用两者，形成三角耦合
|
||||
2. **`REPL.tsx` ↔ 多个 hooks**：REPL 导入 244 个模块，多个 hooks 又依赖 REPL 暴露的 context，形成隐式循环
|
||||
3. **`permissions/` 跨层耦合**：权限逻辑分散在 `utils/permissions/`(24 文件)、`tools/BashTool/bashPermissions.ts`、`components/permissions/`(77 文件)、`hooks/toolPermission/` 四个位置
|
||||
|
||||
### 1.4 依赖扇出（Fan-out）热力图
|
||||
|
||||
```
|
||||
bootstrap/state.ts ████████████████████████████ 251 文件
|
||||
Tool.js ██████████████████████████ 259 文件
|
||||
utils/config.ts ████████████████ 129 文件
|
||||
AppState ████████████████████ 171 文件
|
||||
utils/messages.ts ████████████ 108 文件
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 重构优先级矩阵（影响度 × 可行性）
|
||||
|
||||
```
|
||||
高可行性 ─────────────────── 低可行性
|
||||
┌─────────────────┬──────────────────┐
|
||||
│ │ │
|
||||
高 │ ★ P0 立即做 │ ★ P1 规划做 │
|
||||
影 │ │ │
|
||||
响 │ ① 拆分 bootstrap │ ④ REPL.tsx 拆分 │
|
||||
度 │ /state.ts │ (5005 行) │
|
||||
│ │ │
|
||||
│ ② 提取权限模块 │ ⑤ main.tsx 拆分 │
|
||||
│ (跨 4 层) │ (4683 行) │
|
||||
│ │ │
|
||||
│ ③ utils/ 整理 │ ⑥ 工具系统重构 │
|
||||
│ (清理巨型文件) │ (42 工具统一) │
|
||||
│ │ │
|
||||
├─────────────────┼──────────────────┤
|
||||
│ │ │
|
||||
低 │ ★ P2 随时做 │ ★ P3 长期目标 │
|
||||
影 │ │ │
|
||||
响 │ ⑦ BashTool/PS │ ⑧ Bridge/Remote │
|
||||
度 │ 代码去重 │ 解耦 │
|
||||
│ │ │
|
||||
│ ⑨ 组件层 >800行 │ ⑩ 插件系统重构 │
|
||||
│ 文件拆分 │ (3302 行加载器) │
|
||||
│ │ │
|
||||
└─────────────────┴──────────────────┘
|
||||
```
|
||||
|
||||
### 优先级详情
|
||||
|
||||
| # | 项目 | 影响 | 可行 | 理由 |
|
||||
|---|------|------|------|------|
|
||||
| ① | 拆分 `bootstrap/state.ts` | 🔴 极高 | 🟢 高 | 按领域拆成 6-8 个子模块（session, cost, cwd, duration, tools, hooks），251 个引用点可通过 barrel export 过渡 |
|
||||
| ② | 提取权限模块 | 🔴 高 | 🟡 中 | 当前跨 4 个目录，需要先统一接口，再迁移，逐步替换 |
|
||||
| ③ | 清理 utils/ 巨型文件 | 🟡 中 | 🟢 高 | messages.ts / sessionStorage.ts / hooks.ts 各 5000+ 行，按职责拆分 |
|
||||
| ④ | REPL.tsx 拆分 | 🔴 高 | 🔴 低 | 244 个 import，高度耦合 UI + 业务逻辑，需要先抽取业务逻辑层 |
|
||||
| ⑤ | main.tsx 拆分 | 🔴 高 | 🔴 低 | 4683 行初始化 + CLI 解析混杂，Commander.js 定义可提取 |
|
||||
| ⑥ | 工具系统统一 | 🟡 中 | 🔴 低 | 42 个工具接口已统一，但权限检查链分散 |
|
||||
| ⑦ | BashTool/PS 去重 | 🟢 低 | 🟢 高 | 5706 行 readOnlyValidation 有明显重复，可提取共享层 |
|
||||
| ⑧ | Bridge/Remote 解耦 | 🟡 中 | 🔴 低 | 涉及 WebSocket/JSON-RPC 协议层，需谨慎 |
|
||||
| ⑨ | 大组件拆分 | 🟢 低 | 🟢 高 | PromptInput(2338), Config(1821) 等可直接拆 |
|
||||
| ⑩ | 插件系统重构 | 🟡 中 | 🔴 低 | 3302 行加载器 + 2643 行市场管理器，复杂度高 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 模块化拆分方案
|
||||
|
||||
### 3.1 Phase 1: `bootstrap/state.ts` 拆分（立即开始）
|
||||
|
||||
**现状：** 1 文件，215 导出，251 个引用者
|
||||
|
||||
**目标拆分：**
|
||||
|
||||
```
|
||||
bootstrap/
|
||||
├── state.ts ← barrel re-export（保持兼容）
|
||||
├── session/
|
||||
│ └── sessionState.ts ← getSessionId, switchSession, parent session
|
||||
├── cost/
|
||||
│ └── costState.ts ← totalCost, totalDuration, API duration
|
||||
├── cwd/
|
||||
│ └── cwdState.ts ← getOriginalCwd, setProjectRoot, getCwdState
|
||||
├── tools/
|
||||
│ └── toolState.ts ← turnToolDuration, turnHookDuration, counters
|
||||
├── tokens/
|
||||
│ └── tokenState.ts ← token budget, turn output tokens
|
||||
└── runtime/
|
||||
└── runtimeState.ts ← session hooks, direct connect, speculation
|
||||
```
|
||||
|
||||
**策略：**
|
||||
1. 创建子模块，从 state.ts 导出
|
||||
2. state.ts 变为 barrel file（`export * from './session/sessionState.js'`）
|
||||
3. 逐步将消费者迁移到直接导入子模块
|
||||
4. 最终废弃 barrel file
|
||||
|
||||
**风险：** 低。barrel re-export 保证向后兼容。
|
||||
|
||||
### 3.2 Phase 2: 权限系统统一（2-4 周）
|
||||
|
||||
**现状：** 4 个位置分散实现
|
||||
|
||||
```
|
||||
当前:
|
||||
utils/permissions/ (24 files) — 引擎核心
|
||||
tools/BashTool/bashPermissions.ts — Bash 专用
|
||||
tools/PowerShellTool/powershellPermissions.ts — PS 专用
|
||||
components/permissions/ (77 files) — UI 组件
|
||||
hooks/toolPermission/ (4 files) — React hooks
|
||||
|
||||
目标:
|
||||
core/permissions/
|
||||
├── engine.ts ← 统一权限判断引擎
|
||||
├── rules.ts ← 规则匹配
|
||||
├── modes.ts ← 模式管理
|
||||
├── classifiers.ts ← AI 分类器
|
||||
└── types.ts ← 统一类型
|
||||
|
||||
tools/*/ ← 各工具只保留 tool-specific 逻辑
|
||||
components/permissions/ ← 不变，依赖 core/permissions
|
||||
hooks/toolPermission/ ← 不变，依赖 core/permissions
|
||||
```
|
||||
|
||||
### 3.3 Phase 3: REPL.tsx 拆分（4-8 周）
|
||||
|
||||
**原则：** 先抽业务逻辑，再动 UI 组件
|
||||
|
||||
```
|
||||
当前: screens/REPL.tsx (5005 行, 244 imports)
|
||||
|
||||
目标:
|
||||
screens/
|
||||
├── REPL.tsx ← 纯 UI 组合 (~1500 行)
|
||||
├── useReplSession.ts ← 会话生命周期管理
|
||||
├── useReplInput.ts ← 输入处理（从 244 import 中抽取）
|
||||
├── useReplCommands.ts ← 命令调度
|
||||
└── useReplQuery.ts ← 查询执行编排
|
||||
|
||||
services/repl/
|
||||
├── queryOrchestrator.ts ← 查询编排（当前 REPL 中的 query 逻辑）
|
||||
├── sessionManager.ts ← 会话管理
|
||||
└── inputProcessor.ts ← 输入分类处理
|
||||
```
|
||||
|
||||
**关键前置条件：** ① 已完成（bootstrap/state 拆分减少直接状态操作）
|
||||
|
||||
### 3.4 Phase 4: main.tsx 拆分
|
||||
|
||||
```
|
||||
当前: main.tsx (4683 行)
|
||||
|
||||
目标:
|
||||
main.tsx ← 入口 + 路由分发 (~800 行)
|
||||
cli/
|
||||
├── commanderSetup.ts ← Commander.js 配置 (~1500 行)
|
||||
├── initialization.ts ← init 流程 (~800 行)
|
||||
├── sessionLauncher.ts ← 会话启动分支 (~600 行)
|
||||
└── urlHandlers.ts ← URL/deep link 处理 (~500 行)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 技术债务识别
|
||||
|
||||
### 4.1 代码异味
|
||||
|
||||
| 异味 | 严重度 | 位置 | 说明 |
|
||||
|------|--------|------|------|
|
||||
| **God Module** | 🔴 严重 | `bootstrap/state.ts` | 215 导出，251 消费者，全局状态倾倒场 |
|
||||
| **Blob** | 🔴 严重 | `REPL.tsx`, `main.tsx` | 5000+ 行单文件，违反 SRP |
|
||||
| **Feature Envy** | 🟡 中等 | `utils/hooks.ts` | 5022 行工具函数文件名为 "hooks"，但不是 React hooks |
|
||||
| **Shotgun Surgery** | 🔴 严重 | 权限系统 | 改一个权限逻辑要改 4 个目录 |
|
||||
| **Divergent Change** | 🟡 中等 | `utils/messages.ts` | 5512 行，每次修改可能触及不同职责 |
|
||||
| **Data Clumps** | 🟡 中等 | `Tool.ts` + `AppState` | session/cwd/model 经常一起传递但没有组合类型 |
|
||||
|
||||
### 4.2 反模式
|
||||
|
||||
| 反模式 | 位置 | 说明 |
|
||||
|--------|------|------|
|
||||
| **全局状态滥用** | `bootstrap/state.ts` | 215 个 getter/setter 实质是全局变量，无依赖注入，不可测试 |
|
||||
| **隐式依赖** | `REPL.tsx` | 244 个 import 使得组件无法独立测试或复用 |
|
||||
| **跨层耦合** | 权限系统 | 业务逻辑（utils/permissions）、UI（components/permissions）、Hooks（hooks/toolPermission）、工具级（tools/BashTool/bashPermissions）四层互相引用 |
|
||||
| **重复实现** | BashTool ↔ PowerShellTool | readOnlyValidation 两个文件各 ~1900 行，逻辑高度相似但独立实现 |
|
||||
| **命名混淆** | `utils/hooks.ts` | 不是 React hooks，是通用工具函数，与 `hooks/` 目录产生歧义 |
|
||||
|
||||
### 4.3 动态导入使用评估
|
||||
|
||||
**当前状态：** 302 个 `await import()` + 277 个 `require()` + 960 个 `feature()` 调用
|
||||
|
||||
**评估：** 动态导入使用**已较充分**，但存在不一致：
|
||||
|
||||
- ✅ `main.tsx` 中重型模块（OpenTelemetry, gRPC, print.ts）已做延迟加载
|
||||
- ✅ `feature('...')` 用于构建时死码消除，覆盖 12+ feature flags
|
||||
- ⚠️ `REPL.tsx` 仅 4 处动态 import，大部分依赖是静态的
|
||||
- ⚠️ `commands.ts` 静态导入所有 60+ 命令，应改为动态加载
|
||||
- ❌ `tools.ts` 静态导入 42 个工具，启动时全部加载
|
||||
|
||||
**建议：** commands.ts 和 tools.ts 应按需动态导入，可减少初始 bundle ~30%。
|
||||
|
||||
### 4.4 类型安全问题
|
||||
|
||||
| 问题 | 位置 | 说明 |
|
||||
|------|------|------|
|
||||
| `any` 类型 | 多处 | permission result、tool output 等处有 `any` 残留 |
|
||||
| 状态类型弱 | `bootstrap/state.ts` | 使用 module-level 变量而非 typed store，缺少变更追踪 |
|
||||
| 条件类型分支 | `Command` 联合类型 | prompt/local/local-jsx 三种分支，模式匹配不完整 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 重构路径建议
|
||||
|
||||
### 总体路线图
|
||||
|
||||
```
|
||||
Phase 1 (1-2 周) Phase 2 (2-4 周) Phase 3 (4-8 周)
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ bootstrap/ │ │ 权限系统统一 │ │ REPL.tsx │
|
||||
│ state.ts 拆分 │ ──────→ │ │ ──────→ │ 业务逻辑抽取 │
|
||||
│ │ │ 核心引擎提取 │ │ │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
Phase 4 (6-10 周) Phase 5 (8-12 周) Phase 6 (持续)
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ main.tsx 拆分 │ │ commands.ts │ │ 工具系统优化 │
|
||||
│ │ ──────→ │ tools.ts │ ──────→ │ 组件层拆分 │
|
||||
│ CLI 解析分离 │ │ 动态加载改造 │ │ 测试覆盖补全 │
|
||||
└──────────────┘ └──────────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
### Phase 1 详细步骤（立即可执行）
|
||||
|
||||
1. **创建子模块目录结构**（30 分钟）
|
||||
```
|
||||
mkdir -p bootstrap/{session,cost,cwd,tools,tokens,runtime}
|
||||
```
|
||||
|
||||
2. **提取 `sessionState.ts`**（2 小时）
|
||||
- 移动 `getSessionId`, `switchSession`, `parentSession*` 等 ~25 个导出
|
||||
- 在 `state.ts` 中添加 `export * from './session/sessionState.js'`
|
||||
|
||||
3. **提取 `costState.ts`**（2 小时）
|
||||
- 移动 cost/duration 相关 ~30 个导出
|
||||
|
||||
4. **提取 `cwdState.ts`**（1 小时）
|
||||
- 移动 cwd/project 相关 ~15 个导出
|
||||
|
||||
5. **提取 `toolState.ts`**（2 小时）
|
||||
- 移动 tool duration/counter 相关 ~40 个导出
|
||||
|
||||
6. **提取 `tokenState.ts`**（1 小时）
|
||||
- 移动 token budget 相关 ~20 个导出
|
||||
|
||||
7. **提取 `runtimeState.ts`**（2 小时）
|
||||
- 移动 hooks/speculation/directConnect 等 ~85 个导出
|
||||
|
||||
8. **验证 barrel file 兼容性**（1 小时）
|
||||
- 确保所有 251 个消费者的 import 路径不变
|
||||
- 运行类型检查 + 单元测试
|
||||
|
||||
### Phase 2: 权限系统统一（关键路径）
|
||||
|
||||
**前置条件：** Phase 1 完成
|
||||
|
||||
1. 定义 `core/permissions/types.ts` — 统一 PermissionResult, PermissionMode 等类型
|
||||
2. 实现 `core/permissions/engine.ts` — 通用权限判断引擎
|
||||
3. 将 `utils/permissions/` (24 文件) 迁移到 `core/permissions/`
|
||||
4. 创建 adapter 层让 BashTool/PowerShellTool 使用统一引擎
|
||||
5. 迁移 `components/permissions/` 依赖到 `core/permissions/`
|
||||
6. 迁移 `hooks/toolPermission/` 依赖到 `core/permissions/`
|
||||
|
||||
### 测试策略
|
||||
|
||||
每个 Phase 完成后必须验证：
|
||||
- ✅ TypeScript 编译无新增错误
|
||||
- ✅ 现有单元测试全部通过
|
||||
- ✅ 启动时间无回退（`main.tsx` 的 profileCheckpoint 可用于测量）
|
||||
- ✅ Bundle 大小无显著增长
|
||||
|
||||
---
|
||||
|
||||
## 6. 风险评估
|
||||
|
||||
| 风险 | 概率 | 影响 | 缓解 |
|
||||
|------|------|------|------|
|
||||
| barrel file 过渡期引入循环依赖 | 中 | 中 | 严格使用 `export * from`，不引入新逻辑 |
|
||||
| REPL 拆分破坏流式渲染 | 高 | 高 | 以 hook 边界拆分，不动渲染层 |
|
||||
| 权限系统迁移遗漏 | 中 | 极高 | 端到端测试覆盖 + 灰度 |
|
||||
| 动态加载改造影响启动时间 | 低 | 中 | 保留 profileCheckpoint 监控 |
|
||||
| 多 provider（Bedrock/Vertex）兼容性 | 低 | 高 | 每个 provider 独立测试 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 结论
|
||||
|
||||
Claude Code 的架构在**工具系统**（`buildTool()` 接口统一）和**延迟加载**（960 个 feature flag）方面做得不错。但有三个结构性债务需要优先处理：
|
||||
|
||||
1. **`bootstrap/state.ts`** 是全局耦合的核心节点。215 个导出被 251 个文件引用，修改任何状态逻辑都可能产生级联影响。拆分它是最高 ROI 的重构动作。
|
||||
|
||||
2. **权限系统跨四层分散**是维护噩梦的根源。统一权限引擎能同时提升可维护性和安全性。
|
||||
|
||||
3. **REPL.tsx 和 main.tsx 的体积**使新人上手和 bug 定位变得困难。但拆分它们是 Phase 3+ 的工作，需要先解决底层耦合。
|
||||
|
||||
Phase 1（bootstrap/state 拆分）可在 1-2 周内完成，零风险，立即可启动。
|
||||
Reference in New Issue
Block a user