Claude Code 会话管理与百万上下文窗口深度解析

# 概念模型：上下文窗口的组成
context_window = {
    "capacity": 1_000_000,  # 百万 Token 上限
    "components": [
        SystemPrompt(
            claude_md="项目配置与规则",
            tool_definitions=["read_file", "search", "bash", "..."],
            behavior_rules="安全规则、输出格式等"
        ),
        ConversationHistory([
            Turn(user="帮我重构 auth 模块", assistant="好的，让我先分析..."),
            Turn(user="改用 JWT 方案", assistant="了解，我来修改..."),
            # ... 每个 Turn 都占用 Token
        ]),
        ToolOutputs([
            ToolCall("read_file", "src/auth/middleware.ts", output="... 200行代码 ..."),
            ToolCall("bash", "npm test", output="... 测试输出 ..."),
            # ... 工具输出通常是最大的 Token 消耗者
        ])
    ]
}

# 关键洞察：上下文 ≠ 无限记忆
# 即使有百万 Token，也需要策略性地管理
used_tokens = sum(len(component) for component in context_window["components"])
remaining = context_window["capacity"] - used_tokens

# 简化的注意力机制示意
def attention(query, keys, values):
    """
    当 keys 和 values（即上下文）变得很长时：
    1. 注意力分数被更多 token 稀释
    2. 模型需要在更多信息中找到相关内容
    3. 早期的、不相关的信息开始"干扰"当前任务
    """
    scores = dot_product(query, keys) / sqrt(d_k)
    weights = softmax(scores)  # 注意力权重分散到更多 token 上
    return weighted_sum(weights, values)

# 上下文腐化的直觉理解：
# - 上下文较短时：注意力更容易集中在关键信息上
# - 上下文持续拉长时：检索相关线索和排除噪声的成本会上升
# - 当无关历史与工具输出堆积过多时：模型更容易"走神"

# 典型场景示例
# Turn 1: 实现了一个新的 API 端点
> 帮我实现 /api/users/profile 端点

# Claude 读取了路由配置、数据模型、中间件等文件，完成了实现

# Turn 2: 为刚实现的功能编写文档（继续对话是最优选择）
> 现在帮我为这个端点编写 API 文档

# 为什么继续比新建更好？
# - Claude 已经"记住"了端点的参数、返回格式、使用的中间件
# - 启动新会话意味着要重新读取所有这些文件
# - 继续对话节省了重新加载的 Token 成本和时间

# 场景：调试一个 API 响应格式问题

# Turn 1: Claude 读取了 5 个相关文件
> 调查为什么 /api/orders 返回的日期格式不对

# Turn 2: Claude 尝试了方案 A（修改序列化器）— 但不work
# 此时你发现问题其实在数据库层

# ❌ 错误做法：
> 那个方案不行，问题在数据库层，试试修改 migration

# 问题：Turn 2 中失败方案的所有代码变更和解释
#       仍然占用上下文空间，还可能误导后续推理

# ✅ 正确做法：
# 按 Esc Esc，回退到 Turn 1 之后
# 然后用你学到的知识重新提示：
> 问题不在序列化器层，是数据库 migration 中的日期列类型不对。
> foo 模块的序列化器没有问题不用改。直接修改 migration 文件。

# 效果：
# - Turn 1 中读取的 5 个文件仍然在上下文中 ✓
# - Turn 2 的失败尝试被完全移除 ✓
# - 新的 Turn 2 从干净状态开始，带着更精确的指令 ✓

# 在回退前，让 Claude 总结它学到的东西
> 在我回退之前，总结一下你从这次尝试中学到了什么，
> 以及你建议下一步尝试什么方案

# Claude 会输出一份总结
# 然后你 Esc Esc 回退
# 再把这份总结作为新提示的一部分发送

# 这就像收到了一封"来自未来的 Claude"的信——
# 它尝试了某个方案、失败了，然后把经验教训传回给你

# 基本用法
/compact

# 带引导的用法（推荐）
/compact 重点保留 auth 重构相关的上下文，测试调试的部分可以丢弃

# 更具体的引导
/compact focus on the database schema changes and API contract, 
drop the CSS debugging and test fixture setup details

# 典型用法
/clear

# 然后手动提供精炼的上下文：
> 我正在重构 auth 中间件。
> 约束条件：必须保持向后兼容，不能修改公开的 API 接口。
> 关键文件：src/middleware/auth.ts 和 src/models/user.ts
> 已排除的方案：直接替换 session 为 JWT（会破坏现有客户端）
> 当前进展：已完成 token 验证逻辑，接下来需要处理 refresh token 流程。

# 场景 1：验证工作结果
> 生成一个子代理，根据以下规范文件验证我们刚完成的 auth 重构是否符合要求

# 子代理会：读取规范文件 → 读取实现代码 → 逐条验证 → 返回验证报告
# 所有中间的文件读取和分析过程不会污染父级上下文

# 场景 2：学习另一个代码库的实现方式
> 生成一个子代理，研究 stripe-node SDK 的错误处理模式，
> 总结它的 retry 机制和 error 类型层级，
> 然后我们在自己的项目中实现类似的方案

# 场景 3：编写文档
> 根据我最近的 git changes，生成一个子代理来编写这个功能的用户文档

# 场景 4：大规模代码库搜索
> 生成一个子代理，搜索整个代码库中所有使用 deprecated API 的地方，
> 列出需要迁移的文件和具体行号

def choose_session_strategy(current_state):
    """
    根据当前状态选择最优的会话管理策略
    """
    if current_state.is_new_unrelated_task:
        return "/clear"  # 新任务，干净起步
    
    if current_state.claude_went_wrong_direction:
        if current_state.has_useful_file_reads:
            return "rewind"  # 保留文件读取，删除错误尝试
        else:
            return "/clear"  # 没什么值得保留的
    
    if current_state.context_is_stale:
        if current_state.continuing_same_task:
            return "/compact"  # 压缩后继续
        else:
            return "/clear"  # 换方向了
    
    if current_state.next_step_produces_lots_of_intermediate_output:
        return "subagent"  # 隔离中间输出
    
    if current_state.context_still_relevant:
        return "continue"  # 上下文仍有价值，继续
    
    # 默认：如果不确定，倾向于 /compact
    return "/compact"

# ❌ 等到自动压缩被触发（模型此时最不智能）
# 会话越来越长... 突然自动压缩触发
# 压缩结果可能很糟糕，因为模型无法预测你的下一步

# ✅ 主动在"关键转折点"压缩
# 完成一个子任务后：
/compact 保留数据库 schema 变更和 API 接口定义，
调试 CSS 的部分和 test fixture 的设置细节可以丢弃，
接下来我要做前端组件

# ✅ 或者在任务切换前清除
/clear
# 然后提供精炼的上下文简报

# 查看当前会话的使用情况
/usage

# 你可以据此判断：
# - 当前会话是否已经堆积了太多文件读取和工具输出
# - 下一步是否还会引入大量新上下文
# - 此时是继续、压缩、清空，还是交给子代理更合适

# 类比：上下文管理 ≈ 内存管理
class ContextManager:
    """管理 Claude Code 会话的上下文，就像管理内存一样"""
    
    capacity = 1_000_000  # 百万 Token
    
    def continue_session(self):
        """最高效——直接复用现有上下文"""
        pass  # 不做任何清理，继续使用
    
    def rewind(self, checkpoint):
        """回滚到检查点——保留有用数据，丢弃错误尝试"""
        self.state = self.snapshots[checkpoint]
    
    def compact(self, hint=None):
        """垃圾回收——压缩但有损"""
        summary = self.summarize(self.history, focus=hint)
        self.history = summary  # 用总结替换历史
    
    def clear(self, briefing):
        """硬重置——零腐化但需要手动重建"""
        self.history = []
        self.add(briefing)  # 用你的简报作为新起点
    
    def spawn_subagent(self, task):
        """独立进程——中间状态不影响主上下文"""
        child = ContextManager()  # 全新上下文
        result = child.execute(task)
        return result.summary  # 只返回结论