第7讲 · 能力 Seam——一次替换、全局生效

《DeepSeek Harness 从上手到精通》系列 · 第二阶核心概念篇

🎯 目标：掌握 dsh 最核心架构抽象，为第 8、21 讲铺路难度 ★★☆ ⏱ 约 25 分钟前置：第 6 讲事件体系

如果说 Cordis 是 dsh 的骨架，那么 Seam（接缝）就是骨架上的"关节"。它是 dsh 最核心的架构抽象，理解它，你就拿到了"换脑不换壳"的钥匙。本讲基于 0.1.0-rc.5。

一、三角色模型：定义 / 实现 / 消费

每一个 Seam 都由三个角色组成，这是 dsh 解耦的精髓：

Seam 三角色模型 — **图 1** 每个 Seam = 接口定义 + 实现（Provider）+ 消费者（Consumer），三者解耦。

角色	它做什么
Service Definition（接口）	定义"能力长什么样"：方法、参数、返回
Provider（实现）	真正干活的那个插件，挂到 `ctx.xxx`
Consumer（消费者）	只认接口、不认实现，通过 `ctx.xxx` 取用能力

关键点：Consumer 永远只依赖"定义"，不依赖"是哪个 Provider"。所以换 Provider，Consumer 一行不用改。

二、以 ctx.fs 为例：FsTarget 与结果结构

最直观的 Seam 是文件系统 ctx.fs。它的定义描述了一组能力：read / write / edit，以及对"目标位置" FsTarget 的抽象。每次操作返回一个结构化结果（不是随便抛字符串），调用方据此判断成功/失败、拿到内容或错误。

// Consumer 只认接口，不关心底层是本地盘还是云端
const fs = ctx.fs;            // 拿到当前 Provider
const res = await fs.read(target);
// res: { ok: true, content, path } | { ok: false, error }

三、"执行世界"：换一处，全家搬家

Seam 最妙的地方在"执行世界（execution world）"这个概念：fs 与 subprocess 共享同一个沙箱。它们是同一片"世界"的两个视图。

执行世界共享沙箱 — **图 2** fs 与 subprocess 同处一个执行世界：换掉这个世界的 Provider，Bash/PTY/LSP 全跟着搬家。

这意味着：你只要替换一次"执行世界"的 Provider，Bash 工具、终端（PTY）、LSP 全部自动跟着换——因为它们都消费同一个 Seam。这就是"一次替换、全局生效"。

这正是第 21 讲要动手做的事：写一个自定义 FS/Subprocess Provider，把"换脑"变成"换世界"。

四、对照 graph-atlas.md 看 seam 分布

官方 graph-atlas.md 的模块图里，那些被多个模块共同指向的"中枢"，多半就是 Seam。带着"定义/实现/消费"三色眼镜去看，整张图会突然清晰。

五、动手练习：列出 6 个主要 Seam

本讲产出是一张表格。基于你目前学到的，列出 dsh 中 6 个主要 Seam，并填出各自的 Provider / Consumer（下表是参考答案，鼓励你对照源码补充）：

Seam	Provider（实现）	Consumer（消费者）
`ctx.llm`	LLM 适配插件	agent-loop
`ctx.fs`	本地/云端 FS Provider	read/write/edit 工具
`ctx.subprocess`	执行世界 Provider	Bash / PTY / LSP
`ctx.tools`	各工具插件	agent-loop、system-prompt
`ctx.sessions`	会话持久化插件	Web UI / TUI
`ctx.mcp`	MCP client 插件	工具注册表（第 13 讲）

六、常见坑

把 Seam 当成普通函数：它是"接口契约"，换实现不动契约，Consumer 才稳；
低估执行世界的联动：换 fs 没换 subprocess，会导致 Bash 读写和文件读写不在同一沙箱；
Consumer 直接依赖 Provider 的具体类：一旦换实现就崩，应只依赖 ctx.xxx；
模块图看不懂：先用"定义/实现/消费"三色标注，再看 graph-atlas。

七、官方文档对应章节

docs/graph-atlas.md 模块图与 Seam 分布
packages/fs 与 packages/subprocess 实现
建议阅读顺序：先本讲建立三角色模型，再读模块图与第 8、21 讲

本讲内容基于 DeepSeek Harness 官方文档与项目源码整理，仅供学习参考，具体命令与配置请以官方最新版本为准。系列文章配合源码仓库食用效果更佳：https://github.com/deepseek-ai/deepseek-harness

咨询 DeepSeek Harness 相关问题，请加微信：A0qingfengyuan_01

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由 AI 协助完成！

DeepSeek Harness 教程 · 第7讲 能力 Seam