【模块 2b】上下文与成本 — 架构设计分析
核心架构：上下文与成本管理
前置概念：理解上下文的职责
是什么：

上下文 = 发送给 LLM 的"背景信息"
包括：系统提示、用户上下文、系统上下文
目的：让 LLM 了解当前环境、项目状态、用户偏好

为什么需要缓存：

上下文构建涉及磁盘 I/O（读取文件、git 状态）
每次查询都重新构建 → 浪费资源
缓存 → 会话期间复用，提升性能


上下文三层架构
%%{init: {'theme': 'neutral'}}%%
flowchart TB
    subgraph L1[1. 系统提示 System Prompt]
        A1[工具描述]
        A2[权限规则]
        A3[工作目录]
        A4[MCP 服务器信息]
    end
    
    subgraph L2[2. 用户上下文 User Context]
        B1[.claudemd 文件内容]
        B2[当前日期]
        B3[额外工作目录]
    end
    
    subgraph L3[3. 系统上下文 System Context]
        C1[Git 状态 分支 提交 变更]
        C2[缓存破坏标记 内部调试]
    end
    
    L1 -->|缓存: 会话级| L2
    L2 -->|缓存: 会话级 memoize| L3





层级
缓存策略




系统提示
会话级缓存


用户上下文
会话级缓存 (memoize)


系统上下文
会话级缓存 (memoize)




1. context.ts：上下文管理
文件结构




函数
规模
职责




getGitStatus()
~100 行
并行获取 Git 状态


getSystemContext()
~30 行
系统上下文（缓存）


getUserContext()
~40 行
用户上下文（缓存）


fetchSystemPromptParts()
~50 行
统一获取三部分上下文




核心设计
前置概念：什么是"Memoize"？
通俗理解：

Memoize = 记忆化、缓存函数结果
第一次调用 → 执行并缓存结果
后续调用 → 直接返回缓存结果
前提：参数不变

为什么用 memoize：

上下文构建是异步 I/O 操作（读文件、git 命令）
会话期间上下文不变 → 只需计算一次
后续查询直接使用缓存 → 节省时间

例子：
export const getUserContext = memoize(async (): Promise<{[k: string]: string}> => {
  // 第一次调用：执行 I/O，缓存结果
  const claudeMd = await getMemoryFiles()
  return { claudeMd, currentDate: getLocalISODate() }
})

// 第二次调用：直接返回缓存，不执行 I/O
const ctx = await getUserContext()  // 瞬间返回


核心算法
算法 1：Git 状态并行获取
要解决的问题：

如何快速获取 Git 状态，避免串行执行导致的延迟？

通俗解释：
1. 检查是否是 Git 仓库（快速）
2. 如果是 → 并行执行 5 个 Git 命令：
   - getBranch() → 当前分支
   - getDefaultBranch() → 主分支
   - git status --short → 变更文件
   - git log --oneline -5 → 最近提交
   - git config user.name → 用户名
3. 合并结果，格式化输出
4. 截断超长状态（上限 2K 字符）

代码实现：
export const getGitStatus = memoize(async (): Promise<string | null> => {
  const isGit = await getIsGit()
  if (!isGit) return null

  // 并行执行 5 个 Git 命令
  const [branch, mainBranch, status, log, userName] = await Promise.all([
    getBranch(),
    getDefaultBranch(),
    execFileNoThrow(gitExe(), ['status', '--short']).then(r => r.stdout.trim()),
    execFileNoThrow(gitExe(), ['log', '--oneline', '-5']).then(r => r.stdout.trim()),
    execFileNoThrow(gitExe(), ['config', 'user.name']).then(r => r.stdout.trim()),
  ])

  // 截断超长状态
  const truncatedStatus = status.length > MAX_STATUS_CHARS
    ? status.substring(0, MAX_STATUS_CHARS) + '\n... (truncated)'
    : status

  return [
    `This is the git status at the start of the conversation.`,
    `Current branch: ${branch}`,
    `Main branch: ${mainBranch}`,
    ...(userName ? [`Git user: ${userName}`] : []),
    `Status:\n${truncatedStatus || '(clean)'}`,
    `Recent commits:\n${log}`,
  ].join('\n\n')
})

性能优化：

并行执行：5 个命令并发，总时间 ≈ 最慢的一个
结果缓存：memoize 保证会话期间只执行一次
截断保护：防止超长状态占用过多 Token

耗时：~50-150ms（取决于仓库大小）

前置概念：什么是"ClaudeMD"？
通俗理解：

ClaudeMD = .claudemd 文件
类似 .gitignore，但是给 Claude 看的
内容：项目说明、编码规范、偏好设置
位置：工作区根目录或子目录

例子：
# .claudemd

## 项目说明
这是一个 TypeScript 博客项目，使用 Next.js + Tailwind CSS。

## 编码规范
- 使用 TypeScript strict 模式
- 优先使用函数组件
- 避免使用 `any` 类型

## 偏好设置
- 测试框架：Vitest
- 包管理器：pnpm


算法 2：用户上下文构建
要解决的问题：

如何收集用户项目信息，同时支持灵活配置？

通俗解释：
1. 检查是否禁用 ClaudeMD：
   - CLAUDE_CODE_DISABLE_CLAUDE_MDS 环境变量
   - --bare 模式（且无额外目录）
2. 如果未禁用 → 扫描工作区 .claudemd 文件
3. 收集记忆文件（memory/ 目录）
4. 返回用户上下文：
   - claudeMd：合并的 ClaudeMD 内容
   - currentDate：今天日期

代码实现：
export const getUserContext = memoize(async (): Promise<{[k: string]: string}> => {
  // 检查禁用条件
  const shouldDisableClaudeMd =
    isEnvTruthy(process.env.CLAUDE_CODE_DISABLE_CLAUDE_MDS) ||
    (isBareMode() && getAdditionalDirectoriesForClaudeMd().length === 0)

  // 扫描 ClaudeMD 文件
  const claudeMd = shouldDisableClaudeMd
    ? null
    : getClaudeMds(filterInjectedMemoryFiles(await getMemoryFiles()))

  // 缓存给 auto-mode classifier 使用
  setCachedClaudeMdContent(claudeMd || null)

  return {
    ...(claudeMd && { claudeMd }),
    currentDate: `Today's date is ${getLocalISODate()}.

全新 SOLO：More Than Coding！桌面端、网页端同步上线，抢先体验全新交互 + 双模式智能体，点击链接领取限量邀请码：https://solo.trae.cn/invitation/m1xtapfs

自从导入cpa露头就秒之后，好像就没有Gemini什么事了，我知道可以flow2api用香蕉，那Gemini就没其它用处了吗？能不能废物利用一下，比如再导入某个API用下Gemini3.1啥的

佬友分享的链接抽中，现在也分享给有需要的佬友
全新 SOLO：More Than Coding！点击链接领取限量邀请码

全新 SOLO：More Than Coding！桌面端、网页端同步上线，抢先体验全新交互 + 双模式智能体，点击链接领取限量邀请码：TRAE SOLO: More Than Coding

接力接力
全新 SOLO：More Than Coding！桌面端、网页端同步上线，抢先体验全新交互 + 双模式智能体，点击链接领取限量邀请码：TRAE SOLO: More Than Coding

虽然说现在的环境确实很差。。但是也没有差到说要倒卖公益站的邀请码的地步吧，人心不古，利欲熏心呀！！！

全新 SOLO：More Than Coding！桌面端、网页端同步上线，抢先体验全新交互 + 双模式智能体，点击链接领取限量邀请码：TRAE SOLO: More Than Coding

全新 SOLO：More Than Coding！桌面端、网页端同步上线，抢先体验全新交互 + 双模式智能体，点击链接领取限量邀请码：TRAE SOLO: More Than Coding

【模块 5】UI 渲染层 — 架构设计分析
核心架构：终端 UI 渲染系统
前置概念：理解 Ink
是什么：

Ink = React for CLI（用 React 构建终端界面）
使用 React 组件语法，渲染到终端而非浏览器
支持 JSX、Hooks、Context、状态管理

为什么选择 Ink：

组件化：可复用的 UI 组件
声明式：描述"应该显示什么"，而非"如何绘制"
生态系统：React 的丰富生态（Hooks、Context、DevTools）

类比：

就像"React DOM 渲染到浏览器"，Ink 渲染到终端


UI 渲染层架构
%%{init: {'theme': 'neutral'}}%%
flowchart TB
    subgraph L1[1. 全屏 UI Screens]
        A1[REPL.tsx 主界面]
        A2[Doctor.tsx 系统诊断]
        A3[ResumeConversation.tsx 恢复会话]
    end
    
    subgraph L2[2. 组件库 Components 346 个]
        B1[Messages 消息列表]
        B2[PromptInput 输入框]
        B3[PermissionRequest 权限请求]
        B4[Settings 设置界面]
        B5[TaskListV2 任务列表]
    end
    
    subgraph L3[3. 设计系统 Design System 15 个]
        C1[Box Text 基础布局]
        C2[Dialog 对话框]
        C3[Tabs 标签页]
        C4[ProgressBar 进度条]
    end
    
    subgraph L4[4. Hooks 层 85 个]
        D1[useCanUseTool 权限检查]
        D2[useMergedTools 工具合并]
        D3[useTerminalSize 终端尺寸]
        D4[useInput 键盘输入]
    end
    
    subgraph L5[5. Ink 渲染器 自研终端渲染引擎]
        E1[reconciler.ts React Reconciler]
        E2[screen.ts 屏幕缓冲区]
        E3[terminal.ts 终端通信]
        E4[selection.ts 文本选择]
    end
    
    L1 --> L2 --> L3 --> L4 --> L5


1. screens/：全屏 UI
文件结构




文件
规模
职责




REPL.tsx
~4.7K 行
主界面（对话、工具执行、权限请求）


Doctor.tsx
~500 行
系统诊断（配置、认证、环境检查）


ResumeConversation.tsx
~300 行
恢复会话界面




REPL.tsx：主界面核心
前置概念：理解 REPL
REPL = Read-Eval-Print Loop（读取 - 执行 - 输出循环）
在 Claude Code 中：

Read：用户输入（PromptInput 组件）
Eval：QueryEngine 执行（query() 调用）
Print：流式渲染响应（Messages 组件）
Loop：持续等待下一轮输入


核心架构：REPL 状态机
%%{init: {'theme': 'neutral'}}%%
stateDiagram-v2
    [*] --> Idle
    
    Idle --> Processing: 用户提交
    Idle: 显示 PromptInput
    Idle: 等待用户输入
    
    Processing --> Streaming: 流式响应
    Processing: 显示 Spinner
    Processing: 禁用输入
    Processing: QueryEngine 执行
    
    Streaming --> PermissionRequest: 工具调用
    Streaming: 实时显示 LLM 响应
    
    PermissionRequest --> ToolExecution: 允许
    PermissionRequest: 显示 PermissionRequest 组件
    PermissionRequest: 等待用户决策
    
    ToolExecution --> Idle: 完成
    ToolExecution: 显示工具进度
    ToolExecution: 实时更新输出


核心算法
算法 1：主循环流程
要解决的问题：

如何管理从用户输入到流式响应的完整流程？

通俗解释：
1. 用户输入 → handlePromptSubmit()
2. 添加到历史记录
3. 启动 QueryEngine
4. 流式处理响应：
   - assistant 消息 → 渲染到 Messages
   - tool_use → 触发权限检查
   - tool_result → 继续循环
5. 完成 → 恢复输入状态

代码结构：
// REPL.tsx — 简化的主循环
const handlePromptSubmit = async (prompt: string) => {
  // 1. 添加到历史
  addToHistory(prompt)
  
  // 2. 创建用户消息
  const userMessage = createUserMessage({ content: prompt })
  messages.push(userMessage)
  
  // 3. 启动 QueryEngine
  const queryGenerator = query({ messages, tools, ... })
  
  // 4. 流式处理
  for await (const message of queryGenerator) {
    switch (message.type) {
      case 'assistant':
        messages.push(message)
        break
      case 'tool_use_summary':
        // 触发权限检查
        setToolUseConfirmQueue([...])
        break
    }
  }
  
  // 5. 完成
  setAppState(prev => ({ ...prev, isProcessing: false }))
}

关键设计：

生成器消费：for await 流式处理
状态同步：messages 变化 → 自动重渲染
错误处理：catch 块捕获异常，显示错误消息


前置概念：什么是"特征门控"？
通俗理解：

特征门控 = Feature Flag（功能开关）
编译期：Bun 的 feature() 函数，剔除未启用代码
运行时：条件渲染，动态启用/禁用功能

在 REPL 中：
// 编译期门控
const useVoiceIntegration = feature('VOICE_MODE')
  ? require('../hooks/useVoiceIntegration.js').useVoiceIntegration
  : () => ({ stripTrailing: () => 0, handleKeyEvent: () => {} })

// 运行时门控
{appState.proactiveMode && <ProactivePanel />}


算法 2：特征门控注入
要解决的问题：

如何在 REPL 中注入可选功能（语音、主动模式、协调器），同时保持代码可维护？

通俗解释：
1. 编译期门控：
   - feature('VOICE_MODE') → 条件导入
   - 未启用 → 模块完全剔除（包括依赖）
2. 运行时门控：
   - 条件渲染组件
   - 条件调用 Hook
3. 降级处理：
   - 未启用 → 返回空实现（NOOP）

代码实现：
// REPL.tsx — 特征门控示例

// 1. 语音集成（编译期门控）
const useVoiceIntegration = feature('VOICE_MODE')
  ? require('../hooks/useVoiceIntegration.js').useVoiceIntegration
  : () => ({
      stripTrailing: () => 0,
      handleKeyEvent: () => {},
      re

全新 SOLO：More Than Coding！桌面端、网页端同步上线，抢先体验全新交互 + 双模式智能体，点击链接领取限量邀请码：TRAE SOLO: More Than Coding