Skip to content

EXPERIENCE.md

Latest commit

 

History

History
182 lines (140 loc) · 6.34 KB

EXPERIENCE.md

File metadata and controls

182 lines (140 loc) · 6.34 KB

工程经验总结

项目时间线

时间 版本 主要工作 耗时
2026-03-31 v0.1.0-v0.5.0 源码解压、分析、类型重建 ~2小时
2026-04-01 上午 v0.6.0-v1.0.0 课程开发 (12章节) ~3小时
2026-04-01 下午 v2.0.0-v2.0.2 恢复编译、创建 stub ~2小时
2026-04-01 晚间 v2.0.3-v2.0.5 程序可运行、功能测试 ~1小时
2026-04-01 夜间 v2.0.6-v2.0.7 文档完善、代码清理 ~1小时

关键经验

1. TypeScript 编译修复

问题: 6099 个编译错误

解决策略:

  1. 放宽 tsconfig 配置 - strict: false 减少 63% 错误
  2. 替换类型定义 - 使用参考项目的 message.ts
  3. 创建 stub 模块 - 35+ 模块解决缺失问题

教训:

  • 不要试图完美修复所有类型错误
  • 参考项目的 strict: false 策略是正确的
  • 运行时能跑比编译完美更重要

2. Bun 运行时适配

问题: bun:bundle feature flags 不存在

解决:

// Polyfill
const feature = (_name: string): boolean => false;
const MACRO = { VERSION: '0.0.1-learn', ... };

教训:

  • 构建时宏需要在入口点 polyfill
  • feature() 返回 false 跳过未实现功能

3. OpenTelemetry API 兼容

问题: resourceFromAttributes 导出不存在

解决:

// Polyfill for newer versions
const resourceFromAttributes = (attributes: Record<string, unknown>) => {
  return { attributes }
}

教训:

  • 新版 API 可能移除/重命名导出
  • 简单 polyfill 可快速解决兼容问题

4. Source Map 泄露利用

发现:

  • cli.js.map (57MB) 包含完整源码
  • 1900+ TypeScript 文件
  • 51万+ 行代码

利用方式:

  1. 分析工具框架设计
  2. 学习权限控制实现
  3. 理解上下文压缩算法
  4. 发现未公开功能

架构分析

Claude Code 核心架构

┌─────────────────────────────────────────────────────┐
│                    CLI Entry                         │
│              src/entrypoints/cli.tsx                 │
└─────────────────────┬───────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────┐
│                  Main Process                        │
│                 src/main.tsx                         │
│  • Commander.js CLI 解析                             │
│  • 认证初始化                                         │
│  • REPL 启动                                         │
└─────────────────────┬───────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────┐
│                   Query Engine                       │
│               src/QueryEngine.ts                     │
│  • 会话管理                                          │
│  • 消息处理                                          │
│  • 上下文压缩                                        │
└─────────────────────┬───────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────┐
│                    API Layer                         │
│           src/services/api/claude.ts                │
│  • SDK 封装                                          │
│  • 流式响应处理                                      │
│  • 多 Provider 支持                                  │
└─────────────────────┬───────────────────────────────┘
                      ▼
┌─────────────────────────────────────────────────────┐
│                   Tool System                        │
│                  src/Tool.ts                         │
│  • 工具注册                                          │
│  • 权限检查                                          │
│  • 结果处理                                          │
└─────────────────────────────────────────────────────┘

权限控制流程

用户请求 → 权限检查器 → 风险评估 → 用户确认 → 执行 → 结果返回
              ↓
         高风险操作?
              ↓
         沙箱隔离

技术债务

已发现的问题

文件 问题 影响
src/cli/print.ts 文件过长 (~3000行) 维护困难
src/utils/messages.ts 类型断言过多 106 个类型错误
src/screens/REPL.tsx 组件过大 105 个错误

修复建议

  1. print.ts - 拆分为多个模块
  2. messages.ts - 完善类型定义
  3. REPL.tsx - 组件拆分

未公开功能发现

名称 描述 状态
Buddy 终端电子宠物 可能是愚人节彩蛋
Kairos 长期记忆助手 开发中
Ultraplan 深度规划模式 开发中
多Agent协作 并行分工 开发中
守护进程 后台运行 开发中

参考项目对比

项目 特点 编译错误
claude-code2 最完整恢复 ~1341
open-claude-code 可运行版本 ~2000+
本项目 学习优化版 ~2180

下一步计划

  1. ✅ 程序可运行
  2. ✅ CLI 命令正常
  3. ⏳ API 调用测试 (需要 API key)
  4. ⏳ 功能完善
  5. ⏳ 文档网站

最后更新: 2026-04-01