DeepSeek Harness 系列（07）：Capability Seam 如何通过配置切换能力

Agent 工具往往既要读写文件，又要执行命令、调用模型并适配不同运行环境。若这些逻辑直接绑定本地实现，测试、权限收敛和沙箱部署都会变得复杂。DeepSeek Harness 通过 Capability Seam 把能力接口与具体后端分离，让工具只依赖统一的 ctx 服务，而把实现选择放到 Bundle 配置中。

先从一个家用比喻开始

你家的电灯开关，它不关心电从哪里来——市电、太阳能还是发电机都行。开关只定义一件事："开/关"。只要背后接的东西遵守这个接口，你按下开关，灯就亮。

这就是 Seam（缝隙）的本质：一条接口边界，把"用这个能力"和"这个能力怎么实现"隔开来。

在 dsh 里：

• 文件系统操作是一个 Seam（ctx.fs）
• Shell 执行是一个 Seam（ctx.shell）
• LLM 调用是一个 Seam（ctx.llm）
• 进程沙箱是一个 Seam（ctx.sandbox）

你可以把默认的本地文件系统换成 E2B 沙箱文件系统，工具代码一行不改。这就是 Capability Seam 要解决的问题。

---

Seam 的三个角色

每个 Seam 都由三类参与者构成：

┌────────────────────────────────────────────────────────┐
│  Consumer: tool-fs                                     │
│  import ctx.fs → calls ctx.fs.readFile(path)           │
│                  ctx.fs.writeFile(path, content)       │
└─────────────────────┬──────────────────────────────────┘
                      │ 依赖服务 "ctx.fs"
┌─────────────────────▼──────────────────────────────────┐
│  Service Definition: dsh-fs                             │
│  interface FileSystem { readFile, writeFile, ... }     │
└─────────────────────┬──────────────────────────────────┘
                      │ 实现
      ┌───────────────┴───────────────┐
      ▼                               ▼
  fs-local                         fs-e2b
  (本地文件系统)                 (E2B 沙箱)

三个角色的分工：

角色	职责	举例
Service Definition	定义接口 + 服务名	dsh-fs：定义 ctx.fs 的方法签名
Service Provider	实现接口，注册到 ctx	fs-local、fs-e2b、fs-sandbox
Service Consumer	使用接口，不关心实现	tool-fs：读写文件的工具插件

Consumer 只知道服务名（如 ctx.fs），不知道背后是哪个 Provider。切换 Provider 只影响 Bundle 的配置，Consumer 完全无感。

---

核心 Seam 一览

dsh 内置了以下核心 Seam：

Seam	服务名	默认实现	可替换为
文件系统	ctx.fs	fs-local（本机）	fs-e2b（E2B 沙箱）、fs-sandbox（受限本机）
Shell 执行	ctx.shell	bash-local	bash-sandbox（受限执行）、远程 Shell
进程沙箱	ctx.sandbox	sandbox-local（bwrap/Seatbelt/ACL）	容器、microVM
LLM 适配器	ctx.llm	llm-deepseek	llm-pi-ai 等第三方
认证凭据	ctx.credentials	credentials-local	远程 vault
用户设置	ctx.settings	settings-file	远程设置服务
持久化存储	ctx.sessionPersistence	session-persistence-jsonl	SQLite、远端

---

重点：ctx.fs（文件系统 Seam）

为什么不直接 import fs from 'node:fs'？

直接 import Node.js 内置的 fs 模块，会带来三个具体问题：

1. 测试时：要测试"读文件"逻辑，必须在磁盘上真的创建文件。或者用 mock，但 mock Node.js 内置模块需要额外工具（jest.mock 等），很麻烦。
2. 在沙箱里跑时：E2B 有自己的文件系统接口，不是本地 Node.js fs。如果工具代码直接 import 了 node:fs，到 E2B 里就完全跑不起来。
3. 审计：你无法统一拦截所有文件读写操作，比如做日志、权限检查，因为调用点散落在每个工具里。

用 ctx.fs Seam，这三个问题都消失了：

• 测试时注入内存文件系统 Provider
• E2B 里注入 fs-e2b Provider
• 审计时在 Provider 层统一记录所有调用

Consumer 代码示例（概念示例）

// 工具插件：读文件——只依赖 ctx.fs，不关心实现
// 声明依赖 'fs' 服务
export const inject = ['fs']

export function apply(ctx: Context): void {
  ctx.tools.register(defineTool({
    name: 'read_file',
    description: '读取本地文件内容',
    execute: async (args, exec) => {
      // ctx.fs 是文件系统 Seam——本地、沙箱、E2B，取决于加载了哪个 Provider
      // 这里完全不关心背后用的是什么文件系统
      const content = await ctx.fs.readFile(args.path)
      return content
    },
  }))
}

// 想切换到沙箱文件系统？
// 只需在 Bundle 里换掉 Provider 插件：

// bundle.ts（概念示例）
export default [
  // 替换这一行就够了，工具代码不用改：
  // '@deepseek-ai/dsh-fs-local'     → 本地文件系统（默认）
  // '@deepseek-ai/dsh-fs-sandbox'   → 受限本地文件系统
  // '@deepseek-ai/dsh-fs-e2b'       → E2B 沙箱文件系统
  '@deepseek-ai/dsh-fs-sandbox',   // ← 只改这一行

  // Consumer 代码一行未动
  '@deepseek-ai/dsh-tool-fs',
  // ... 其他插件
]

---

重点：ctx.sandbox（进程沙箱 Seam）

Shell 执行背后是进程沙箱。dsh 定义了三种沙箱模式：

// 进程沙箱的三种模式（概念示例）
type SandboxMode =
  | 'read-only'          // 只读模式：子进程不能写入任何文件
  | 'workspace-write'    // 工作区写模式：只能在工作目录下写文件
  | 'danger-full-access' // 无限制模式：不经过沙箱，直接 spawn 子进程

平台实现是自动适配的：

平台	底层机制
Linux	bwrap + Landlock
macOS	Seatbelt
Windows	ACL 受限令牌

一行配置换后端（概念示例）：

# 本地开发：sandbox-local（平台原生沙箱）
# CI/CD：sandbox-e2b（E2B 容器，完全隔离，沙箱崩了也不影响宿主）

同一份 tool-shell 代码，在本地跑用 sandbox-local，在 CI 里跑用 sandbox-e2b，切换只发生在 Bundle 配置层。

---

重点：ctx.llm（LLM 适配器 Seam）

LLM 也是 Seam。这个设计乍一看有点出人意料，但仔细想想很合理。

为什么 LLM 调用也要抽象？

1. 切换供应商：同一个 Agent，本地测试用轻量模型，生产用 DeepSeek，只换 Provider 插件。
2. 回放测试：llm-replay Provider——不发真实 API 请求，直接按顺序回放历史 session 的 assistant 响应。测试 Agent 行为不需要 API key，也不会有随机性。
3. 多模型路由：可以实现一个 Provider，根据任务类型路由到不同模型。

// llm-replay 的用途（概念示例）
// 在测试里：
//   1. 先跑一次真实对话，保存 session 日志
//   2. 之后跑测试时，把 Provider 换成 llm-replay，
//      replay adapter 按顺序回放历史 assistant/message 事件
//   3. 测试完全确定性，不消耗 API quota，速度快 10x

// 切换方式：Bundle 里一行
// '@deepseek-ai/dsh-llm-deepseek'  → 真实 API
// '@deepseek-ai/dsh-llm-replay'    → 回放模式（测试用）

---

实战：自己实现一个 Provider

实现一个只读文件系统 Provider——所有写操作直接报错，适合给 Agent 开只读访问权限。

// 只读文件系统 Provider（概念示例）
// 适用场景：只想让 Agent 读代码库，不允许修改任何文件

export const name = 'my-readonly-fs'

export function apply(ctx: Context): void {
  // 向框架注册为 ctx.fs 的 Provider
  ctx.provide('fs', {
    // 读操作：正常执行
    async readFile(path: string): Promise<string> {
      return await localReadFile(path)
    },

    // 写操作：直接拦截，抛出明确错误
    async writeFile(path: string, content: string): Promise<void> {
      throw new Error(`Read-only filesystem: cannot write to ${path}`)
    },

    // 目录列表：正常执行
    async listFiles(dir: string): Promise<string[]> {
      return await localListFiles(dir)
    },

    // ... 其他方法（mkdir、rm 等都抛只读错误）
  })
}

// 在 Bundle 里使用自定义 Provider（概念示例）
export default [
  // 用自己的只读 Provider 替换默认的 fs-local
  './my-readonly-fs',

  // tool-fs 照常使用，它不知道背后是只读的
  '@deepseek-ai/dsh-tool-fs',
]

这个模式的强大之处：你不需要改 tool-fs 的任何代码，就限制了 Agent 的文件系统权限。

---

Seam 设计的核心价值

用一张表对比：

场景	不用 Seam	用 Seam
切换 LLM 供应商	改遍所有 API 调用代码	换一个 Provider 插件
单元测试文件操作	需要 mock node:fs，或在磁盘上建真实文件	直接注入内存文件系统 Provider
部署到沙箱环境	需要改大量工具代码适配沙箱 API	换 fs-sandbox 或 fs-e2b
新增平台/后端支持	改核心代码，可能引入 bug	实现新 Provider，Consumer 不受影响
权限控制	在每个工具里加 if 判断	在 Provider 层统一拦截

Seam 本质上是依赖注入（DI）的一种特化形式，只是在插件系统里，注入的粒度是"服务名"，而不是构造函数参数。

---

设计总结

dsh Capability Seam 的核心思路：

Consumer 只知道接口名，Provider 只知道接口，切换发生在配置层。

设计决策	原因
所有外部能力走 Seam	测试、部署、多后端支持全都受益
LLM 也是 Seam	支持 replay 测试、供应商切换、多模型路由
沙箱也是 Seam	本地/CI/远程环境用不同沙箱后端，Agent 代码不变
Consumer 只声明服务名	解耦彻底，不依赖任何具体实现
Bundle 是配置层	组合不同 Provider 只改一处，不改业务代码

---

系列下一篇

下一篇讲 多 Agent 协作：当一个 Agent 解决不了复杂任务时，dsh 是怎么支持多个 Agent 分工配合的——委托（delegation）、子 Agent、并行执行，以及这些机制在 Session 层面是怎么表示的。

---

在 PrimeSkills 可以找到已在真实企业场景验证过的 AI Agent 技能和工作流，不是演示级的，是用在实际项目里的。

更多内容见我的个人主页