269 lines
11 KiB
Markdown
269 lines
11 KiB
Markdown
# Claude Code 项目运行记录
|
||
|
||
> 项目: `/Users/konghayao/code/ai/claude-code`
|
||
> 日期: 2026-03-31
|
||
> 包管理器: bun
|
||
|
||
---
|
||
|
||
## 零、项目目标
|
||
|
||
**将 claude-code 项目运行起来，必要时可以删减次级能力。**
|
||
|
||
这是一个 Anthropic 官方的 Claude Code CLI 工具的源码反编译/逆向还原项目。项目的核心目标是：
|
||
|
||
1. **使项目能够成功构建和运行** — 优先解决 `bun run build` 和 `bun run dev` 的阻塞问题
|
||
2. **删减次级能力以降低复杂度** — 对于依赖私有 npm 包（如 `@ant/*`）的功能，可以用 stub 替代或直接移除
|
||
3. **保留核心 CLI 交互能力** — 保留与 Anthropic API 通信、工具调用、REPL 交互等核心功能
|
||
|
||
### 可删减的次级能力
|
||
|
||
| 模块 | 说明 | 处理方式 |
|
||
|------|------|----------|
|
||
| Computer Use | `@ant/computer-use-*` 私有包 | stub 或移除 |
|
||
| Claude for Chrome | `@ant/claude-for-chrome-mcp` | stub 或移除 |
|
||
| Magic Docs | 私有文档处理 | 移除 |
|
||
| Voice Mode | 语音模式 | 移除 |
|
||
| LSP Server | `vscode-languageserver-*` | 移除 |
|
||
| Analytics/Telemetry | 数据上报 | 空实现 |
|
||
| GrowthBook | A/B 实验 | 空实现 |
|
||
| Plugins/Marketplace | 插件市场 | 移除 |
|
||
| Desktop Upsell | 桌面端推销 | 移除 |
|
||
| Ultraplan | 私有功能 | 移除 |
|
||
| Tungsten | 私有功能 | 移除 |
|
||
| Sentry | 错误上报 | 移除 |
|
||
| Auto Dream | 自动后台任务 | 移除 |
|
||
| MCP OAuth/IDP | 企业级认证 | 简化 |
|
||
|
||
### 核心保留能力
|
||
|
||
- API 通信（Anthropic SDK / Bedrock / Vertex）
|
||
- Bash/FileRead/FileWrite/FileEdit 等核心工具
|
||
- REPL 交互界面（ink 终端渲染）
|
||
- 对话历史与会话管理
|
||
- 权限系统（基础）
|
||
- Agent/子代理系统
|
||
|
||
---
|
||
|
||
## 一、整体进度
|
||
|
||
| 阶段 | 错误数 | 说明 |
|
||
|------|--------|------|
|
||
| 初始状态 | ~1800 | 仅缺少 npm 依赖的 TS2307 错误 |
|
||
| 补全依赖后 | ~1800 | npm 包已安装，开始处理类型 |
|
||
| 当前状态 | **2123** | 类型 stub 已创建，但存在质量待修问题 |
|
||
|
||
### 当前错误分布
|
||
|
||
| 错误码 | 数量 | 含义 |
|
||
|--------|------|------|
|
||
| TS2693 | 727 | `export type X` 被当作值使用（应为 `export const/function`） |
|
||
| TS2339 | 537 | 属性不存在（类型收窄、unknown 类型） |
|
||
| TS2614 | 468 | 模块只有默认导出，但代码用命名导入 |
|
||
| TS2322 | 128 | 类型不匹配 |
|
||
| TS2345 | 57 | 参数类型不匹配 |
|
||
| TS2300 | 34 | 重复标识符（stub 文件中 export 重复） |
|
||
| TS2307 | 29 | 仍有缺失模块 |
|
||
| TS2305 | 28 | 缺失导出成员 |
|
||
| TS2724 | 21 | 导出名称不匹配（如 HookEvent vs HOOK_EVENTS） |
|
||
| TS2367 | 17 | 比较类型无交集（`"external" === "ant"` 等） |
|
||
| 其他 | ~100 | TS2578/TS2315/TS2365/TS2741 等 |
|
||
|
||
---
|
||
|
||
## 二、已完成的工作
|
||
|
||
### 2.1 全局变量声明 (`src/types/global.d.ts`)
|
||
|
||
声明了编译时宏和内部标识符：
|
||
|
||
- **MACRO / MACRO.VERSION** — Bun 编译时宏，通过 `bun:bundle` 提供
|
||
- **MACRO.BUILD_TIME / FEEDBACK_CHANNEL / ISSUES_EXPLAINER** 等编译时常量
|
||
- **resolveAntModel / getAntModels / getAntModelOverrideConfig** — 内部模型解析
|
||
- **fireCompanionObserver** — Companion 观察器
|
||
- **apiMetricsRef / computeTtftText** — 指标计算
|
||
- **Gates / GateOverridesWarning / ExperimentEnrollmentNotice** — 功能门控
|
||
- **HOOK_TIMING_DISPLAY_THRESHOLD_MS** — Hook 时间阈值
|
||
- **UltraplanChoiceDialog / UltraplanLaunchDialog / launchUltraplan** — Ultraplan 功能
|
||
- **TungstenPill** — Tungsten 功能
|
||
- **T** — React compiler 输出泄露的泛型参数
|
||
|
||
### 2.2 内部包声明 (`src/types/internal-modules.d.ts`)
|
||
|
||
为 Anthropic 私有包提供了详细的类型导出：
|
||
|
||
- `@ant/claude-for-chrome-mcp` — BROWSER_TOOLS, ClaudeForChromeContext, Logger 等
|
||
- `@ant/computer-use-mcp` — ComputerExecutor, ScreenshotResult, buildComputerUseTools 等
|
||
- `@ant/computer-use-mcp/types` — ComputerUseHostAdapter, CoordinateMode 等
|
||
- `@ant/computer-use-mcp/sentinelApps` — getSentinelCategory
|
||
- `@ant/computer-use-input` — ComputerUseInput, ComputerUseInputAPI
|
||
- `@ant/computer-use-swift` — ComputerUseAPI
|
||
- `@anthropic-ai/mcpb` — McpbManifest, McpbUserConfigurationOption
|
||
- `color-diff-napi` — ColorDiff, SyntaxTheme, getSyntaxTheme
|
||
- `audio-capture-napi / image-processor-napi / url-handler-napi`
|
||
- `bun:bundle / bun:ffi`
|
||
|
||
### 2.3 SDK 模块补全 (`src/entrypoints/sdk/`)
|
||
|
||
为缺失的 SDK 子模块创建了 stub 文件：
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `controlTypes.ts` | 控制协议类型（SDKControlRequest/Response） |
|
||
| `runtimeTypes.ts` | 运行时类型（SDKSession, Query, Options, SdkMcpToolDefinition 等） |
|
||
| `coreTypes.generated.ts` | 从 Zod schema 生成的类型（ModelUsage, HookInput 系列, SDK 消息类型等） |
|
||
| `settingsTypes.generated.ts` | Settings 类型 |
|
||
| `toolTypes.ts` | 工具类型 |
|
||
| `sdkUtilityTypes.ts` | NonNullableUsage 等工具类型 |
|
||
|
||
### 2.4 自动化 stub 生成 (`scripts/create-type-stubs.mjs`)
|
||
|
||
编写了自动分析脚本，通过解析 `tsc` 错误和源码 `import` 语句，自动创建缺失模块的 stub 文件：
|
||
|
||
- 扫描 TS2305/TS2614/TS2724 获取缺失导出
|
||
- 扫描源码 import 语句获取命名导入
|
||
- 自动创建 `export type X = any` stub
|
||
- 已生成 **1206 个 stub 文件，覆盖 2067 个命名导出**
|
||
|
||
---
|
||
|
||
## 三、当前问题分析
|
||
|
||
### 3.1 TS2693 (727 个) — `export type` 被当作值使用 ⚠️ 关键
|
||
|
||
**原因**: `scripts/create-type-stubs.mjs` 统一使用 `export type X = any` 生成 stub，但代码中很多地方将导入的名称作为**值**使用（如调用函数、渲染 JSX 组件等）。
|
||
|
||
**示例**:
|
||
|
||
```typescript
|
||
// stub 中: export type performLogout = any
|
||
// 实际使用: performLogout() // TS2693: only refers to a type, but is being used as a value
|
||
```
|
||
|
||
**修复方案**: 将 `export type X = any` 改为 `declare const X: any` 或 `export const X: any`。需要区分哪些是纯类型、哪些是值/函数/组件。
|
||
|
||
### 3.2 TS2614 (468 个) — 模块只有默认导出
|
||
|
||
**原因**: 部分 stub 文件使用 `export default {} as any`（早期手动创建），但代码用命名导入 `import { Message } from ...`。
|
||
|
||
**示例**: `src/types/message.ts` 当前内容为 `export default {} as any`，但代码 `import type { Message } from '../types/message.js'`
|
||
|
||
**修复方案**: 将默认导出改为命名导出。
|
||
|
||
### 3.3 TS2300 (34 个) — 重复标识符
|
||
|
||
**原因**: stub 文件中有 `export type X = any` 行，同时源文件中也存在同名定义，造成冲突。部分 stub 文件路径不正确（如 `src/components/CustomSelect/select.ts` 既有真实代码又有 stub 导出）。
|
||
|
||
**修复方案**: 检查这些文件，如果真实文件存在则删除 stub 中的重复导出。
|
||
|
||
### 3.4 TS2339 (537 个) — 属性不存在
|
||
|
||
**原因**: `any` 类型的 stub 过于宽松时可以正常工作，但部分地方类型收窄后（如联合类型判别、`unknown` 类型）无法访问属性。
|
||
|
||
**分类**:
|
||
|
||
- 内部代码中 `unknown` 类型需要类型断言（源码问题）
|
||
- `McpServerConfigForProcessTransport` 等类型定义过窄（stub 精度问题）
|
||
- `{ ok: true } | { ok: false; error: string }` 联合类型访问 `.error`（源码惯用模式）
|
||
|
||
**修复方案**: 调整相关 stub 类型定义使其更精确。
|
||
|
||
### 3.5 TS2307 (29 个) — 仍有缺失模块
|
||
|
||
主要是路径解析问题产生的重复 stub（如 `src/cli/src/` 下的文件已被删除）以及一些深度嵌套的相对路径。
|
||
|
||
### 3.6 路径问题
|
||
|
||
部分 stub 文件被错误创建在 `src/cli/src/` 等嵌套路径下（因为 `import { X } from 'src/something'` 从 `src/cli/handlers/auth.ts` 解析时路径计算错误）。已手动删除部分重复文件，但可能仍有残留。
|
||
|
||
---
|
||
|
||
## 四、后续处理方案
|
||
|
||
### Phase 1: 修复脚本 — 区分类型导出 vs 值导出 (预计解决 ~1200 个错误)
|
||
|
||
改进 `scripts/create-type-stubs.mjs`：
|
||
|
||
1. **分析 import 语句上下文**：
|
||
- `import type { X }` → 纯类型，用 `export type X = any`
|
||
- `import { X }` (无 type) → 可能是值，用 `export const X: any = (() => {}) as any`
|
||
- JSX 组件（大写开头 + 在 JSX 中使用）→ `export const X: React.FC<any> = () => null`
|
||
|
||
2. **分析使用上下文**：
|
||
- `X()` 调用 → 函数/值导出
|
||
- `<X />` → React 组件
|
||
- `X.property` → 对象/命名空间
|
||
|
||
### Phase 2: 修复默认导出问题 (预计解决 ~468 个 TS2614)
|
||
|
||
将所有 `export default {} as any` 的 stub 文件替换为带命名导出的版本：
|
||
|
||
```typescript
|
||
// 之前
|
||
export default {} as any
|
||
|
||
// 之后 — 根据导入需求
|
||
export type Message = any
|
||
export type NormalizedUserMessage = any
|
||
// ... 等
|
||
```
|
||
|
||
### Phase 3: 清理冲突和路径问题 (预计解决 ~34 个 TS2300 + 29 个 TS2307)
|
||
|
||
1. 检查所有带 `TS2300` 错误的文件，删除与真实代码冲突的 stub
|
||
2. 清理 `src/cli/src/`、`src/components/*/src/` 等错误路径下的 stub 残留
|
||
3. 修复 `tsconfig.json` 的 `paths` 配置，确保 `src/*` 映射正确
|
||
|
||
### Phase 4: 精化关键类型定义 (预计解决 ~100+ 个 TS2322/TS2345)
|
||
|
||
对高频使用的类型提供更精确的定义：
|
||
|
||
1. **SDK 消息类型** — 使 `type` 字段为字面量联合类型，而非 `string`
|
||
2. **McpServerConfig** — 改为联合类型（stdio | sse | http | sse-ide）
|
||
3. **HookInput** 系列 — 添加 `hook_event_name` 字面量类型
|
||
4. **PermissionResult** — 改为判别联合 `allow | deny`
|
||
|
||
### Phase 5: 处理源码级别的类型问题 (需评估)
|
||
|
||
这些是源码本身的问题，不属于 stub 范畴：
|
||
|
||
- `TS2367`: `"external" === "ant"` — 构建时消除的死代码
|
||
- `TS2339`: 联合类型属性访问 — 需要类型收窄或断言
|
||
- `TS2322`: 类型字面量不匹配（如 `"result"` vs `"result_success"`）
|
||
|
||
---
|
||
|
||
## 五、关键文件清单
|
||
|
||
| 文件 | 用途 |
|
||
|------|------|
|
||
| `src/types/global.d.ts` | 全局变量/宏声明 |
|
||
| `src/types/internal-modules.d.ts` | 内部 npm 包类型声明 |
|
||
| `src/types/react-compiler-runtime.d.ts` | React compiler runtime |
|
||
| `src/types/sdk-stubs.d.ts` | SDK 通配符类型（备用） |
|
||
| `src/entrypoints/sdk/controlTypes.ts` | SDK 控制类型 stub |
|
||
| `src/entrypoints/sdk/runtimeTypes.ts` | SDK 运行时类型 stub |
|
||
| `src/entrypoints/sdk/coreTypes.generated.ts` | SDK 核心类型 stub |
|
||
| `src/entrypoints/sdk/settingsTypes.generated.ts` | SDK 设置类型 stub |
|
||
| `src/entrypoints/sdk/toolTypes.ts` | SDK 工具类型 stub |
|
||
| `src/entrypoints/sdk/sdkUtilityTypes.ts` | SDK 工具类型 |
|
||
| `scripts/create-type-stubs.mjs` | 自动 stub 生成脚本 |
|
||
| `tsconfig.json` | TypeScript 配置 |
|
||
| `package.json` | 依赖配置 |
|
||
|
||
---
|
||
|
||
## 六、运行命令
|
||
|
||
```bash
|
||
# 检查当前错误数
|
||
cd /Users/konghayao/code/ai/claude-code && npx tsc --noEmit 2>&1 | grep "error TS" | wc -l
|
||
|
||
# 错误分类统计
|
||
npx tsc --noEmit 2>&1 | grep "error TS" | sed 's/.*error //' | sed 's/:.*//' | sort | uniq -c | sort -rn
|
||
|
||
# 重新生成 stub（修复脚本后）
|
||
node scripts/create-type-stubs.mjs
|
||
```
|