04 Location 作用域与会话移动

04 Location 作用域与会话移动

本节摘要:前两节讲了「录入与执行分离」和「进程级协调」,这一节讲 V2 的最后一个关键机制——Location 作用域。在 V2 里,执行协调是进程级、按会话 ID 路由的,但模型、工具、权限、文件系统这些服务却是 Location 级缓存的。Location 是什么?它由「目录 + 工作区 + 版本控制 + 项目」组成,是服务层的缓存键。本节讲清这个看似奇怪的设计——为什么协调是进程级、服务是 Location 级?以及一个重要后果:移动会话(换 Location)会清空上下文纪元。这套设计不是无端复杂,而是为未来的多节点 clustering 留下了缝。

一、Location 是什么

Location(位置)是 V2 里一个核心的「作用域」概念。它由四样东西组成:

Location = 目录 + 工作区(workspaceID) + 版本控制(vcs) + 项目(project)
​

可以把它理解成「这次执行所处的环境坐标」。两个会话如果工作在同一个目录、同一个工作区、同一个 Git 仓库、同一个项目下,它们就共享同一个 Location。

二、关键区分:协调是进程级,服务是 Location 级

这是本节最需要记住的区分:

会话 A (Location X) ─┐
                     ├─► 执行协调:进程级,按会话 ID 路由
会话 B (Location X) ─┘      │
                           └─► 但它们用的服务层:Location 级,共享 Location X 的缓存
会话 C (Location Y) ──► 用 Location Y 的服务层缓存
​

💡 为什么这么设计:同一 Location 的多个会话,共享同一份文件系统视图、同一份模型配置、同一套权限——因为这些只跟「你在哪个项目里」有关,跟「哪个会话」无关。把它们按 Location 缓存,多个会话复用,避免重复加载。而协调必须按会话 ID,因为每个会话有自己的回合节奏。

三、Location 服务映射

V2 里有一个「Location 服务映射」机制,在 drain 时按 session.location 解析出对应 Location 的服务层:

drain 开始
   │
   ├─ 取 session.location(Location X)
   ├─ LocationServiceMap.get(Location X) ──► 返回 Location X 的服务层
   │     ├─ 文件系统服务(认 Location X 的目录)
   │     ├─ 模型服务(用 Location X 配置的模型)
   │     ├─ 工具注册表(Location X 的工具集)
   │     └─ 权限规则(Location X 的规则)
   └─ 用这套服务层跑这个会话的回合
​

如果 Location X 的服务层还没建好,就先构建一次并缓存;下次同 Location 的会话直接复用。这就是「Location 级缓存」的工作方式。

四、移动会话:为什么清空纪元

这套设计带来一个重要后果:如果一个会话被移动到另一个 Location,它的上下文纪元(Context Epoch)会被清空。

为什么?因为纪元里保存的「基准 System Context」是在旧 Location 下生成的——旧的工作目录、旧的 Git 状态、旧的指令。换到新 Location 后,这些基准都不再适用(新目录、新 Git 状态、新指令)。如果继续用旧基准,模型会拿到错误的环境信息。

会话在 Location X ──► 纪元基准 = Location X 的环境信息
   │
   ▼ 移动到 Location Y
会话在 Location Y ──► 旧基准失效(环境变了) ──► 清空纪元,重新建立新基准
​

⚠️ 这个后果要记住:「移动会话」不是免费的——它会触发纪元重建,意味着模型会重新建立上下文(第 8 章)。在大多数日常使用里你不会主动移动会话,但理解这一点能解释某些「为什么换了项目,Agent 好像失忆了」的现象。

五、为多节点 clustering 留的缝

读到这里你可能觉得「Location 级缓存」有点绕,为什么不干脆全进程级?答案是:这套设计为未来的多节点(multi-node)clustering 留下了缝。

考虑一个未来场景:OpenCode 跑在多台机器上,协同服务多个会话。这时:

• Location 成为「工作可以在哪台机器上做」的天然划分——同一 Location 的工作可以路由到同一台机器,复用那台机器上的服务层缓存。
• 进程级协调保持在单机内,跨机器的协调按 Location 分派。

如果现在就把所有服务做成进程级、与会话强绑定,未来想跨机器分派就得大改。Location 作用域让这个未来演进成为可能,而不需要推倒重来。这就是「为未来留缝」的工程智慧。

六、第 7 章收尾:你现在理解的 Session 核心

读完第 7 章四节,你现在掌握的 Session 核心画像:

这套 Session 核心是 OpenCode 的心脏。但心脏跳动的「血液」——给模型的上下文——还没细讲。第 8 章就钻进这个最硬核的主题:System Context 与 Context Epoch。

本节要点回顾

1. Location = 目录 + 工作区 + 版本控制 + 项目,是服务层的缓存键。
2. 关键区分:执行协调是进程级(按会话 ID),模型/工具/权限/文件系统服务是 Location 级(按 Location 缓存)。
3. Location 级缓存让同一 Location 的多个会话复用服务层,避免重复加载。
4. 移动会话清空纪元:因为旧 Location 的基准(System Context)在新 Location 不再适用。
5. 为多节点 clustering 留缝:Location 是「工作在哪台机器做」的天然划分,未来跨机器分派不用推倒重来。
6. 第 7 章结束:你已掌握 Session 核心画像(V1 现状、V2 演进、协调、Location)——下一章进入最硬核的上下文管理。

第 7 章结束。下一章是全书最深的主题——给模型的「上下文」如何被结构化、如何随对话安全演化、什么是「纪元」。