AI 原生开放教材

外观

驾驭工程：从 Claude Code 源码到 AI 编码最佳实践工程手册·中文原文 ↗原件 ↓仓库 ↗

Claude Code 逆向工程参考指南 ​

本指南提供从 Claude Code npm 包中提取和分析信息的系统化方法，适用于版本追踪和技术分析。

一、获取新版本 ​

1.1 下载 tarball ​

bash
# 从 npm registry 下载指定版本
npm pack @anthropic-ai/claude-code@2.1.91

# 下载最新版本
npm pack @anthropic-ai/claude-code

# 查看可用版本
npm view @anthropic-ai/claude-code versions --json | tail -20

1.2 tarball 结构 ​

package/
├── cli.js              # 主 bundle（Bun 打包，~13MB）
├── cli.js.map          # Source map（v2.1.88 有，v2.1.89+ 已移除）
├── package.json        # 包元数据
├── sdk-tools.d.ts      # SDK 公开 API 类型定义
├── LICENSE.md
├── README.md
├── bun.lock            # Bun 锁文件（v2.1.88 有，v2.1.89+ 已移除）
└── vendor/             # 原生模块和工具
    ├── ripgrep/        # rg 二进制（各平台）
    ├── audio-capture/  # 音频采集 .node 模块
    ├── image-processor/# 图像处理 .node 模块
    ├── modifiers-napi/ # 键盘修饰键 .node 模块
    └── url-handler/    # URL 协议处理 .node 模块

1.3 Source Map 可用性 ​

版本cli.js.map说明
v2.1.88有（57MB）可完整还原 4,756 个源文件
v2.1.89+无Anthropic 已移除 source map 分发

二、Source Map 路径（有 .map 文件时） ​

如果 tarball 中包含 cli.js.map，可以完整还原源码：

2.1 提取源码 ​

bash
# 解压 tarball
tar xzf anthropic-ai-claude-code-2.1.88.tgz

# 使用 source-map-explorer 可视化
npx source-map-explorer package/cli.js

# 使用 Node.js 提取所有源文件
node -e "
const fs = require('fs');
const { SourceMapConsumer } = require('source-map');

const map = JSON.parse(fs.readFileSync('package/cli.js.map', 'utf8'));
const sources = map.sources;
const contents = map.sourcesContent;

sources.forEach((src, i) => {
  if (contents[i]) {
    const outPath = 'restored-src/' + src.replace(/^\.\.\//g, '');
    fs.mkdirSync(require('path').dirname(outPath), { recursive: true });
    fs.writeFileSync(outPath, contents[i]);
  }
});
console.log('Extracted', sources.length, 'files');
"

2.2 与基线做 diff ​

bash
# 使用 diff 对比两个版本的还原源码
diff -rq restored-src-v88/src/ restored-src-v91/src/ | head -50

# 使用 git 管理版本
cd restored-src && git init && git add . && git commit -m "v2.1.88"
# 覆盖新版本源码后
git diff --stat

三、无 Source Map 路径（v2.1.89+ 情况） ​

当 source map 不可用时，需要从 minified bundle 中提取信号。

3.1 可提取的信号（字符串常量挖掘） ​

使用 scripts/extract-signals.sh 自动提取：

bash
# 提取所有信号
./scripts/extract-signals.sh package/cli.js

# 只提取 tengu 事件
./scripts/extract-signals.sh package/cli.js --section tengu

# 输出 JSON 格式
./scripts/extract-signals.sh package/cli.js --json

信号类型详解 ​

1. Tengu 事件名（~860 个）

所有遥测事件使用 tengu_ 前缀。事件名直接反映功能模块：

tengu_api_query        → API 调用
tengu_compact          → 压缩系统
tengu_mcp_*            → MCP 协议
tengu_tool_use_*       → 工具执行
tengu_powerup_*        → 新功能（v2.1.91 新增）

变化含义：

  • 新增事件 → 新功能或新追踪点
  • 移除事件 → 功能废弃或重构
  • 带实验代码名的事件（如 tengu_birch_trellis）→ A/B 测试

2. CLAUDE_CODE_ 环境变量（~180 个）*

环境变量控制运行时行为：

CLAUDE_CODE_AUTO_COMPACT_WINDOW  → 自动压缩窗口大小
CLAUDE_CODE_API_BASE_URL         → API 基础 URL
CLAUDE_CODE_BRIEF                → 简洁模式
CLAUDE_CODE_AGENT_COST_STEER     → 代理成本控制（v2.1.91 新增）

3. GrowthBook 配置名（~17 个）

Feature flag 和实验配置：

tengu_auto_mode_config           → YOLO 自动模式
tengu_prompt_cache_1h_config     → 1 小时缓存
tengu_sm_compact_config          → 会话内存压缩

4. 工具名

从工具注册代码中提取：Bash, Read, Write, Edit, Glob, Grep, Agent, Skill, ...

5. API 端点路径

/v1/messages                     → Claude API
/api/event_logging/batch         → 遥测事件导出
/api/oauth/usage                 → 使用量查询
/api/oauth/profile               → OAuth 用户资料

3.2 结构化差异分析 ​

使用 scripts/cc-version-diff.sh 进行版本间对比：

bash
# 两版本对比
./scripts/cc-version-diff.sh old.tgz new.tgz

# 与 v2.1.88 基线对比（单参数模式）
./scripts/cc-version-diff.sh new.tgz

# 输出到文件
./scripts/cc-version-diff.sh old.tgz new.tgz -o docs/version-diffs/report.md

报告包含：

  • cli.js 大小变化
  • Tengu 事件增删
  • 环境变量增删
  • GrowthBook 配置变化
  • 包文件变化
  • sdk-tools.d.ts 差异（公开 API 变化）
  • package.json 差异

3.3 语义级分析方法 ​

当需要更深入的分析时，可以手动搜索已知模式：

bash
# 搜索 logEvent 调用附近的上下文
grep -b 'tengu_powerup' cli.js | head

# 搜索环境变量引用
grep -oE 'CLAUDE_CODE_[A-Z_]+' cli.js | sort -u

# 搜索 API 端点
grep -oE '"/v[0-9]/[a-z_/]+"' cli.js | sort -u

# 搜索版本信息
grep -oE '"version":"[0-9]+\.[0-9]+\.[0-9]+"' cli.js

# 搜索 feature() 调用（注意：Bun DCE 可能已消除）
grep -c 'feature(' cli.js  # 如果为 0，说明已被 DCE 消除

# 搜索唯一错误类名
grep -oE '[A-Z][a-zA-Z]+Error' cli.js | sort -u | head -20

四、锚点文件索引 ​

详见 anchor-points.md — 从 v2.1.88 源码中提取的 120+ 个子系统锚点。

锚点是在 minified bundle 中定位特定子系统的关键。每个锚点是一个唯一的字符串常量，在不同版本中通常保持一致。

示例使用：

bash
# 确认 API 重试逻辑是否仍存在
grep -c 'tengu_api_retry' cli.js

# 检查 YOLO 分类器是否仍在使用
grep -c 'classify_result' cli.js

# 检查 Datadog 集成
grep -c 'datadoghq.com' cli.js

# 检查压缩阈值是否改变
grep -oE 'AUTOCOMPACT_BUFFER[^,}]+' cli.js

五、版本间差异速查 ​

v2.1.88 → v2.1.91 变化要点 ​

指标v2.1.88v2.1.91变化
cli.js 大小12.4MB12.5MB+115KB
Source Map有无已移除
Tengu 事件827860+39 / -6
环境变量178183+8 / -3
GrowthBook 配置1718+1

关键新增功能信号（v2.1.91）：

  • tengu_powerup_lesson_* — 学习/教程系统
  • tengu_cold_compact — 冷压缩（新压缩策略）
  • tengu_memory_toggled — 内存开关
  • tengu_message_rated — 消息评分
  • tengu_ultraplan_* — 超级计划功能
  • tengu_mcp_subagent_prompt — MCP 子代理提示

移除的功能信号：

  • tengu_tree_sitter_* — Tree-sitter 相关（已移除或重构）
  • tengu_basalt_ / tengu_birch_trellis — 实验结束

详细报告见 version-diffs/v2.1.88-vs-v2.1.91.md。

六、工作流建议 ​

追踪新版本的标准流程 ​

1. npm pack @anthropic-ai/claude-code@<新版本>
2. ./scripts/cc-version-diff.sh claude-code-<旧>.tgz claude-code-<新>.tgz -o docs/version-diffs/<旧>-vs-<新>.md
3. 审查差异报告，重点关注：
   a. 新增 tengu 事件 → 识别新功能
   b. 移除 tengu 事件 → 识别废弃功能
   c. 新增环境变量 → 识别新配置选项
   d. sdk-tools.d.ts 变化 → 识别公开 API 变化
4. 如需深入分析特定子系统，使用锚点在 cli.js 中定位
5. 将分析结果记录到 docs/version-diffs/ 目录

持续追踪建议 ​

  • 保留每个版本的 tarball 作为基线
  • 维护 docs/version-diffs/ 目录下的差异报告
  • 当发现新的稳定锚点时，更新 docs/anchor-points.md
  • 关注 sdk-tools.d.ts 的变化——这是唯一的官方公开 API 定义

本指南基于 Claude Code v2.1.88（含 source map）的逆向工程经验编写