Design Decisions¶
重要性：⭐⭐ 目标读者：架构师 / 贡献者 关联：analysis/architecture-history.md、analysis/extensibility.md
1. 概览¶
本文档记录 Claude Code 的重大设计决策。
5 大类： - 架构 - 技术选型 - 安全 - 性能 - UX
2. 10 大架构决策¶
2.1 决策: 单体 vs 微服务¶
选择：单体
原因： - 简单部署（单 binary） - 低延迟（IPC 0 开销） - 调试容易
代价： - 难以水平扩展 - 任何 bug 影响整个 CLI
替代方案： - ❌ 微服务：太重 - ❌ Serverless：不适用 CLI
2.2 决策: 自研 vs 用 React/Ink 框架¶
选择：自研 Ink
原因： - 复用 React 生态 - 终端渲染简单可控 - 跨平台
代价： - Ink 30+ 文件 - 需要 Yoga 等基础设施
替代方案： - ❌ blessed：老旧 - ❌ 直接 ANSI：太底层
2.3 决策: 集成 MCP 协议¶
选择：MCP
原因： - 跨厂商（Claude / Cursor） - 标准协议 - 生态
代价： - 协议复杂度 - 鉴权 / OAuth 流程
替代方案： - ❌ 自有协议：锁死 - ❌ OpenAPI：不适合 LLM 工具
2.4 决策: 插件系统¶
选择：6 源 + manifest
原因： - 用户灵活性（npm / git / 本地） - 团队分发 - Marketplace 生态
代价： - 25+ 文件 - 安全审计复杂度
替代方案： - ❌ npm only：不够灵活 - ❌ 无插件：限制扩展
2.5 决策: Hook 抽象¶
选择：9 事件 + 3 类型
原因： - 灵活（command / prompt / agent） - 用户可控 - 不绑死实现
代价： - 抽象复杂度 - 用户配置成本
2.6 决策: 状态管理¶
选择：Zustand-like AppStateStore
原因： - 简单（zustand-style） - 跨组件订阅 - TS 友好
代价： - 全局 store 调试 - 性能需优化（精确 selector）
2.7 决策: Settings 多源合并¶
选择：4 级（policy > local > project > user）
原因： - 灵活性（用户 / 项目 / 企业） - 强制（policy 不能覆盖） - 简单
2.8 决策: Agent 模式¶
选择：sub-agent 嵌套
原因： - 复杂任务分解 - 隔离上下文 - 并行
代价： - 状态同步 - 调试
2.9 决策: Bash 权限¶
选择：6 层决策
原因： - 纵深防御 - 灵活（rules + classifier） - 详细 reason
代价： - 25+ validator 维护 - 性能（classifier）
2.10 决策: ANT-ONLY 双版本¶
选择：编译时门控
原因： - 商业版干净 - 内部用更多功能 - 一份代码
代价： - 双版本测试 - 文档同步
3. 10 大技术选型¶
3.1 语言: TypeScript¶
选择：TypeScript
原因： - 强类型（防止错） - 生态 - AI 友好
3.2 运行时: Bun¶
选择：Bun
原因： - 启动快（~50ms） - 内置 TS - 单文件可执行
代价： - 部分 Node API 差异
3.3 UI: React + Ink¶
选择：React + Ink
原因： - 复用 React 生态 - 终端抽象 - 开发者熟悉
3.4 布局: Yoga (纯 TS 移植)¶
选择：Yoga 移植
原因： - 工业级 flexbox - 无 WASM - 启动快
3.5 LLM client: Anthropic SDK¶
选择：Anthropic SDK
原因： - 官方 - 完整功能（cache / streaming） - TS 类型
3.6 状态: AppStateStore (类 zustand)¶
选择：类 zustand
原因： - 简单 - 跨组件 - TS 友好
3.7 Schema: Zod¶
选择：Zod
原因： - TS 推断 - 验证 - 错误友好
3.8 缓存: 自研 3 memoize 变体¶
选择：自研
原因： - 简单（无依赖） - 控制力
代价： - 自己维护
3.9 日志: 自研 + Statsig¶
选择：自研 + Statsig
原因： - 控制输出 - 远程聚合
3.10 测试: Vitest (推测)¶
选择：Vitest
原因： - ESM 友好 - 速度快 - TS 支持
4. 10 大安全决策¶
4.1 决策: 多层防御¶
选择：6 层
原因：纵深防御标准实践。
4.2 决策: 25+ bash validator¶
选择：25+ 独立 validator
原因： - 单一规则易绕过 - 多个独立简单
4.3 决策: speculative classifier¶
选择：投机 LLM classifier
原因： - 用户感觉瞬时 - 规则 fallback
风险： - 浪费 LLM 调用 - classifier 可能误判
4.4 决策: sandbox 可选¶
选择：可选 sandbox
原因： - 灵活 - 不强制（怕误伤）
代价： - 用户需自己开
4.5 决策: OAuth 强制 (MCP)¶
选择：强制 OAuth
原因： - 标准 - 跨平台 - 不用自管密码
4.6 决策: 不 sandbox plugin¶
选择：plugin 在主进程
原因： - 性能 - 简单
代价： - 安全风险
未来：process isolation (推测)
4.7 决策: 信任对话框¶
选择：用户必须显式 accept
原因： - 安全 - 透明
4.8 决策: telemetry-safe 命名¶
选择：_I_VERIFIED_* 后缀
原因： - 强制作者审查 - 类型级契约
4.9 决策: 凭证脱敏¶
选择：redact 在多处
原因： - 错误信息保护 - telemetry 保护
4.10 决策: 反调试 (商业版)¶
选择：商业版反调试
原因： - 防破解
代价： - 调试不便
5. 10 大性能决策¶
5.1 决策: 顶部并行预取¶
选择：startMdmRawRead + startKeychainPrefetch
原因：~200ms 节省
5.2 决策: print fast-path¶
选择：print 模式早返回
原因：~50-100ms 节省
5.3 决策: DCE feature gate¶
选择：bun:bundle 编译时门控
原因：~50ms 节省 + 体积
5.4 决策: 30+ profileCheckpoint¶
选择：全程埋点
原因：可观测性
5.5 决策: 3 memoize 变体¶
选择：memoize / LRU / TTL
原因：3 种场景
5.6 决策: React hooks-first¶
选择：业务在 hooks
原因：可测 / 可复用 / 轻组件
5.7 决策: 4-slot LRU (Yoga)¶
选择：4-slot
原因：平衡内存 / 命中
5.8 决策: env-var 提到 mount-time¶
选择：useMemo 包装 env
原因：PageUp 优化
5.9 决策: speculative LLM¶
选择：投机调用
原因：UX 黑魔法
5.10 决策: 纯 TS 移植 (Yoga)¶
选择：纯 TS 而非 WASM
原因：启动优先
6. 10 大 UX 决策¶
6.1 决策: REPL 默认 5 阶段¶
选择：Bun → imports → main → preAction → run
原因：优化启动
6.2 决策: 60+ hooks 编排¶
选择：Hook 编排
原因：关注点分离
6.3 决策: God Component (REPL.tsx)¶
选择：5000 行单组件
原因：避免 props drilling
代价：难 navigate
6.4 决策: --bare 模式¶
选择：用户可控性能
原因：灵活
6.5 决策: 5 mode permission¶
选择：default / acceptEdits / bypass / plan / auto
原因：多场景
6.6 决策: 30+ notification hook¶
选择：每个 UX 细节一个 hook
原因：可定制
代价：噪声
6.7 决策: 桌宠 (BUDDY)¶
选择：ANT-ONLY 桌宠
原因：用户粘性
代价：仅 ANT
6.8 决策: cost 显示¶
选择：cost-tracker 累加
原因：用户可见
6.9 决策: /insights 命令¶
选择：LLM 提取结构化 facets
原因：用户自省
6.10 决策: settings 多级合并¶
选择：4 级合并
原因：灵活
7. 5 大类决策的 trade-off¶
7.1 架构¶
7.2 技术¶
7.3 安全¶
7.4 性能¶
7.5 UX¶
8. 5 个未来方向（推测）¶
8.1 方向 1: Plugin 沙箱¶
process isolation（推测）。
8.2 方向 2: 多 LLM 支持¶
OpenAI / Gemini（推测）。
8.3 方向 3: 移动端¶
iOS / Android（推测）。
8.4 方向 4: Web 化¶
浏览器版（推测）。
8.5 方向 5: 多语言¶
完整 i18n（推测）。
9. 5 个"反决策"（明确不做）¶
9.1 不做：Web UI¶
坚持 CLI。
9.2 不做：移动端¶
坚持桌面。
9.3 不做：IDE 嵌入（除 VSCode）¶
有限 IDE。
9.4 不做：自管 OAuth server¶
用现有。
9.5 不做：自研 LLM¶
用 API。
10. 5 个"反"反决策¶
10.1 决定做：CLI¶
CLI 是核心。
10.2 决定做：macOS¶
主要平台。
10.3 决定做：VSCode¶
主要 IDE。
10.4 决定做：Anthropic API¶
主 API。
10.5 决定做：subscription 模式¶
商业核心。
11. 5 个教训¶
11.1 lesson 1: 启动快比极致快重要¶
用户感知 优先。
11.2 lesson 2: 纵深防御胜单点¶
多层 保险。
11.3 lesson 3: 渐进比重写好¶
逐步 演进。
11.4 lesson 4: 可观测性是优化前提¶
埋点 必须。
11.5 lesson 5: 用户可控重要¶
旋钮 多给。
12. 总结¶
设计决策 = trade-off + 上下文。
核心： - 10 大架构 - 10 大技术 - 10 大安全 - 10 大性能 - 10 大 UX
下一步： - 看 architecture-history.md - 看 extensibility.md