自学教程

DeepSeek Harness 服务隔离与作用域

DeepSeek Harness

DeepSeek Harness 依托 Cordis 内核实现多层级作用域与服务隔离。它采用层级上下文链机制，不同层级拥有独立的上下文实例，服务可见性遵循单向查找规则：子作用域可以读取父作用域注册的服务，父作用域无法访问子作用域内部的私有服务。借助这套机制，可以实现多会话、多Agent之间的能力隔离、工具私有化、凭据隔离，避免不同任务之间服务实例、状态、配置互相污染。

一、作用域层级划分

Harness 把运行环境划分为三层核心作用域，由顶层到底层依次为宿主层、会话层、任务层。

1. 宿主层（Host Scope，全局根作用域）

宿主层是整个 Harness 进程的全局根上下文，进程启动时初始化，进程销毁才释放。

  • 用途：放置全局基础设施服务，如日志、配置管理、模型适配器基础服务、全局事件总线。
  • 可见范围：所有下层作用域都可以访问宿主层注册的服务。
  • 隔离特性：宿主层注册的服务对所有会话共享，不适合存放会话私有数据、临时状态。

示例：全局 ctx.llm 模型适配器、日志服务都挂载在宿主层。

2. 会话层（Session Scope，会话私有作用域）

每新建一个Agent会话，内核就会创建独立会话作用域，会话销毁时自动回收。

  • 用途：会话专属工具、会话配置、会话级缓存、会话沙箱实例。
  • 可见范围：本会话下所有任务都能读取会话层服务；其他会话完全不可见。
  • 隔离特性：会话之间天然隔离，A会话注册的工具、状态，B会话无法访问。

示例：给某一个会话单独开启网页搜索工具，其他会话不受影响。

3. 任务层（Task Scope，临时子作用域）

会话内部可以派生多个子任务，每个子任务拥有独立任务作用域，任务执行结束立即销毁。

  • 用途：子任务临时变量、一次性工具调用、临时文件沙箱。
  • 可见范围：仅当前子任务内部可见；同级子任务之间互相隔离。
  • 隔离特性：生命周期最短，执行完成自动清理，不会污染上层会话状态。

作用域查找规则

当插件访问 ctx.xxx 服务时，内核会从当前作用域向上逐级查找：当前作用域 → 父作用域 → … → 宿主根作用域，找到第一个匹配的服务即返回。上层无法向下穿透访问子作用域内部服务，实现单向隔离。

二、服务隔离的两种模式

1. 实例隔离（推荐）

同一个服务名称，在不同作用域创建独立实例。
宿主层提供基础服务接口，会话层实例独立维护自己的状态、缓存、凭据。

  • 优点：多个Agent会话共用同一套插件代码，但各自状态互不干扰。
  • 典型场景：多会话同时运行，每个会话拥有独立沙箱与工具注册表。

2. 完全隔离 Realm（isolate 隔离域）

通过 isolate 标记创建完全独立的隔离域，隔离域拥有独立依赖图与独立服务注册表。

  • 适用场景：需要彻底隔离的高风险任务，比如不可信代码执行、第三方社区插件运行。
  • 特点：隔离域不会继承上层服务，需要手动声明依赖，适合安全沙箱场景，防止跨域服务泄露。

三、上下文与服务挂载示例

// 在会话层注册私有服务，仅当前会话可用
export default definePlugin({
  inject: ['log'],
  setup(ctx) {
    // 注册会话私有服务
    ctx.registerService('sessionPrivateStore', {
      data: {},
      set(key, value) {
        this.data[key] = value
      },
      get(key) {
        return this.data[key]
      }
    })
  }
})

该服务只会挂载在当前会话作用域，其他会话无法读取 sessionPrivateStore，天然实现会话状态隔离。

四、与沙箱文件隔离的关系

服务作用域隔离是运行时对象、插件服务、内存状态隔离；沙箱是文件系统、进程权限隔离，二者配合使用。

  • 作用域隔离：控制插件、服务实例、内存数据在哪个层级可见；
  • 沙箱隔离：限制Agent读写本地文件、执行命令的文件路径权限，支持只读、工作区可写、完全放开三种模式。

在安全场景下，一般同时启用：会话作用域隔离 + 沙箱文件隔离，保证内存状态和文件访问双重隔离。

五、典型使用场景

  1. 多会话并行运行
    多个Agent会话同时执行任务，每个会话独立的工具集、独立会话存储，互不干扰。可以给不同会话分配不同模型、不同权限工具。
  2. 第三方插件安全运行
    加载不可信社区插件时，放到独立 isolate 隔离域，限制其可访问的服务，避免插件读取全局凭据或篡改其他会话状态。
  3. 子任务临时执行
    Agent拆分多个子任务，子任务使用任务层作用域，临时数据在任务结束自动销毁，不污染主会话。
  4. 租户隔离（多用户场景）
    面向多用户部署时，一个用户对应一个会话作用域，用户之间的服务实例、缓存、API凭据隔离。

六、常见问题与排错

  1. 服务找不到
    检查挂载层级：如果服务注册在会话层，宿主层全局插件无法访问，属于正常隔离规则，不是bug。
  2. 会话之间状态互相影响
    大概率是将状态挂载到宿主全局作用域。会话私有数据必须挂载在session scope，不要直接挂全局ctx。
  3. isolate隔离域无法访问基础服务
    隔离域默认不继承上层，需要显式声明inject依赖，手动引入需要的基础服务。
  4. 内存泄漏
    子作用域销毁时，未解绑事件监听器。Harness会自动回收作用域内注册的事件，自定义插件要遵循生命周期，避免脱离ctx的全局回调。

七、最佳实践

  1. 全局基础设施放宿主层；会话专属配置、缓存放会话层；一次性临时数据放任务层。
  2. 私有凭据（API Key）不要注册到宿主全局，放在会话作用域，会话销毁自动清除。
  3. 高风险第三方插件，启用 isolate 隔离域，最小化依赖声明。
  4. 尽量利用作用域天然隔离，不要手动维护全局变量存储会话状态。
  5. 设计插件时区分：哪些能力是全局共享，哪些能力需要会话独立实例。

八、小结

DeepSeek Harness 的作用域与服务隔离基于层级上下文链实现，遵循子可见父、父不可见子的单向访问规则。三层作用域（宿主、会话、任务）搭配 isolate 隔离域，把服务实例、内存状态按会话与任务切分。服务隔离管控插件运行时对象，沙箱管控文件系统权限，二者组合，是构建安全多Agent并行任务、多租户系统的基础。

标签：

0 条笔记