Skip to content

CLAUDE.md

Latest commit

 

History

History
176 lines (133 loc) · 7 KB

CLAUDE.md

File metadata and controls

176 lines (133 loc) · 7 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

这是 @anthropic-ai/claude-code v2.1.88 的分发包，通过 sourceMap 反编译还原了所有 TypeScript 源代码到 source/src/ 目录。

  • 编译产物: cli.js（13MB）+ cli.js.map（60MB sourceMap）
  • 还原源码: source/src/（TypeScript/TSX，4756 个文件）
  • 模块系统: ES Module（"type": "module"）
  • 运行环境: Node.js 18+，编译器为 Bun

运行已编译版本

# 直接运行本地包
node cli.js

# 或全局安装后运行
npm install -g @anthropic-ai/claude-code
claude

从 TypeScript 源码运行（开发环境）

源码位于 source/src/（不可直接运行），需先通过 dev-patch.ts 生成可运行的副本：

cd /Users/admin/Desktop/package/source

# 第一次设置
bun install  # 安装依赖

# 生成可运行的 src-dev/（每次修改 src/ 后需重新运行）
bun run dev-patch.ts

# 运行
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --version
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx --help
bun --preload ./macros-preload.ts src-dev/entrypoints/cli.tsx

dev-patch.ts 做了什么

将 src/ 复制到 src-dev/，同时进行以下转换：

  1. from 'bun:bundle' → 绝对路径指向 bun-bundle-shim.ts（运行时 feature flag 模拟）
  2. from 'src/xxx' → 相对路径（指向 src-dev/ 内部）
  3. import xx from '*.md' → const xx = ''（文本文件内联 stub）
  4. import '*.d.ts' → 删除（类型声明不需要运行时加载）
  5. '-d2e, --debug-to-stderr' → '--debug-to-stderr'（commander v13 兼容）

重要文件

  • source/bun-bundle-shim.ts — feature flag 模拟（控制哪些功能被启用）
  • source/macros-preload.ts — 注入 MACRO.VERSION 等构建时常量
  • source/dev-patch.ts — 生成 src-dev/ 的脚本
  • source/bunfig.toml — Bun 配置（alias、registry）
  • source/src/ — 只读：原始提取的 TypeScript 源码 + 手动创建的 stub 文件
  • source/src-dev/ — 运行目录：由 dev-patch.ts 生成，勿手动修改

注意事项

  • 不要在 source/ 目录内运行 bun add xxx，会触发父包的 prepare 脚本报错。添加依赖时：修改 source/package.json 后运行 bun install
  • src-dev/ 会被 dev-patch.ts 完整重建，手动修改 src-dev/ 中的文件会被覆盖
  • 需要修改或 stub 缺失文件时，应修改 src/ 中的对应文件

代码架构

目录结构（source/src/）

src/
├── entrypoints/cli.tsx   # CLI 真正的入口，处理快速路径（--version、--daemon 等）
├── main.tsx              # 主应用初始化（auth、settings、MCP、插件加载）
├── query.ts              # 核心查询循环（生成器函数，驱动 AI↔Tool 交互）
├── QueryEngine.ts        # 查询引擎封装
├── Tool.ts               # Tool 接口定义（所有工具的契约）
├── tools.ts              # 工具注册表（getAllBaseTools、assembleToolPool）
├── Task.ts               # Task 类型与状态定义
├── commands.ts           # 斜杠命令注册
├── context.ts            # 系统上下文注入（gitStatus、CLAUDE.md 等）
├── tools/                # 70+ 内置工具实现
├── commands/             # 斜杠命令实现
├── components/           # React/Ink UI 组件
├── hooks/                # React hooks（权限决策、历史导航等）
├── services/             # 业务逻辑（MCP、auth、settings 等）
├── state/                # AppState（Zustand store）
├── utils/                # 工具函数
├── coordinator/          # 多 Worker 协调器模式
├── skills/               # 技能系统
└── permissions/          # 权限系统

核心执行流程

entrypoints/cli.tsx
  → main.tsx（初始化 auth/settings/MCP/plugins）
    → query.ts: query()  ← 生成器，yield 每条消息
        ├─ normalizeMessagesForAPI()
        ├─ 注入系统提示（context.ts）
        ├─ 调用 Claude Streaming API
        ├─ 检测 stop_reason === 'tool_use'
        ├─ runTools()  ← 并行或串行执行工具
        └─ 追加 tool_result，继续循环

Tool 系统设计

每个 Tool 实现 Tool<Input, Output, P> 接口（Tool.ts），关键方法：

  • call() — 实际执行逻辑
  • checkPermissions() — 工具级权限检查
  • validateInput() — 输入验证（Zod schema）
  • renderToolUseMessage() / renderToolResultMessage() — UI 渲染
  • isConcurrencySafe() — 是否可并行执行
  • isReadOnly() / isDestructive() — 操作性质声明

工具注册通过 getAllBaseTools()（tools.ts），MCP 工具动态合并到工具池：assembleToolPool(permissionContext, mcpTools)。

权限系统

权限模式（PermissionMode）：

  • default — 提示用户确认
  • acceptEdits — 自动接受文件编辑
  • bypassPermissions — 跳过所有权限检查
  • plan — 计划模式（只读审查）
  • dontAsk — 静默允许

权限决策链：deny 规则检查 → allow 规则检查 → canUseTool() hook → 自动分类器（auto 模式）→ UI 提示。

状态管理

全局状态通过 Zustand store（state/AppStateStore.ts）管理，React 层使用：

useAppState(selector)       // 订阅状态切片
useSetAppState()            // 获取 setter（不订阅）
useAppStateStore()          // 直接访问 store

AppState 包含：消息历史、工具权限上下文、MCP 连接、插件、后台任务、Swarm 协作状态、Todo 列表等。

Hook 系统（sessionHooks）

在工具执行前后插入自定义逻辑：

  • pre_tool_use / post_tool_use — 可修改输入、中止执行
  • session_start / setup — 会话级初始化
  • pre_compact / post_compact — 上下文压缩前后

配置来源：~/.claude/hooks.json、项目级 .claudehooks.json、插件 hooks。

多 Agent / Task 模型

Task 类型（Task.ts）：

  • local_agent — Agent 工具生成的子代理（独立上下文）
  • local_bash — 后台 bash 任务
  • remote_agent — CCR 远程代理
  • in_process_teammate — Swarm 进程内协作
  • local_workflow — 工作流脚本

Coordinator 模式（CLAUDE_CODE_COORDINATOR_MODE=1）：主循环变为协调器，Agent 工具生成 worker，通过 <task-notification> 消息汇报结果。

重要文件速查

文件 职责
source/src/query.ts 核心 AI↔Tool 交互循环（1729 行）
source/src/Tool.ts Tool 接口定义（793 行）
source/src/tools.ts 工具注册表
source/src/state/AppStateStore.ts 全局状态定义（454 行）
source/src/hooks/useCanUseTool.tsx 权限决策逻辑
source/src/services/mcp/ MCP 连接与工具集成
source/src/coordinator/ 多 Worker 协调器
source/src/entrypoints/cli.tsx CLI 启动入口