deepseek-harness 学习手册
查得到就不用记›附录 · 术语表 · 包地图 · 时间线
工具页

术语表 · 包地图 · 时间线

术语中英对照、按 group 可视化的 227 包地图、上游关键节点时间线、外链库。

最后核对于 v0.1.1-rc.2 · commit b150a551b8 · 2026-08-22

三张查得到就不用记的表：术语中英对照、227 个包的分组地图、以及一条上游时间线。外加一份外链库。

A.1　术语表

本站的原则：术语保留英文原词，中文只作解释。理由跟仓库 glossary 一样——像 seam 这样的词，中文现成的译法（「缝合层」「接口」）都会丢掉它最关键的那层意思。

seam能力接缝
一个可替换的能力，由三个角色构成：Service Definition（拥有 ctx.<key> 和词汇类型的 Cordis Service——一个抽象类或具体注册表，从来不是 TypeScript interface）、一个或多个 Service Provider、一个或多个 inject 这个服务的 Consumer。seam 是完整的能力，从来不是其中某一个角色。
Service Definition
声明接口、拥有 ctx 上那个 key 的那个包。
Service Provider
把一个具体实现注册进 seam 的包。它不拥有 key。多个 provider 可以平级共存。
Consumer
只按接口取用能力的包，常见形态是一个面向模型的工具。
context / ctx
服务的仓库，也是插件的生存单位。插件按 key 找服务，不 import 具体实现。
effect
可撤销的注册动作。ctx.effect() 返回 disposer，插件卸载时自动调用。「注册即 effect」是整套架构的地基。
waterfall分发模式之一
around-middleware：监听器收到 (...args, next)。调 next() 才委托给下一个；不调就是短路。其余三种模式是 emit / parallel / serial。
profile
存在 Harness home（$DSH_HOME，默认 ~/.dsh）里的一个具名组合：一份列出所叠 bundle 的 package.json、树外插件依赖、以及用户自己的 cordis.patch.yml。web 和 headless 是出厂模板。
bundle
Cordis 配置行及其代码的分发格式。它插入的东西仍然可以被上面的层打补丁。dsh-base 是每个 profile 的第一层。
patch补丁层
按 id 定位一行并替换它整个 config（不深合并），或者 insert 新行。层序：各 bundle → profile → home → --patch overlay，后写的赢。
turn / step / round
turn：一次「把已接纳输入排干」的过程。step：一次模型请求加它引发的工具执行，一个 turn 含零个或多个 step。round：外层策略的一次迭代（goal round、Ralph round），它的计数属于那个策略。
session log
append-only 的 SessionEvent 日志，是模型所见上下文的唯一真相。deriveMessages() 从它投影出模型历史；fork、resume、transcript、遥测、持久化全部派生自它。
scopeagent 作用域
按 agent 注册的单位。一项贡献（工具、prompt section、变量、限制、监听器）要么是全局的，要么归恰好一个 scope key 所有。两级，扁平：scoped 注册不向下继承给 subagent。
shadowing遮蔽
最具体者胜的名字解析：一个 scoped 的工具 / section / 变量，只对那个 scope 取代同名的全局孪生体。这是「按 agent 换人设」和「按 agent 换工具变体」的机制。
spill溢出
把超大的工具输出落盘，把内联结果换成一个有界的预览加一个取回定位符。
compaction压缩
历史压缩能力。包含一个会调模型做摘要的后端，和一个不用模型的工具结果裁剪器。
Model Experience
每个包 README 末尾的固定小节，按上下文面分节，每节三个字段：What the model sees / Token effect / KV Cache effect。由 verify-package-readme-model-experience 校验结构。
Agent Note
这个仓库的 ADR 变体。路径即状态：{proposed|implemented|rejected|archived}/{类别}/yyyy-mm-dd-题目.md。非平凡改动必须在同一个 PR 里加或更新一篇。
Ralph loop
一次前台的、面向不可变目标的 fresh-agent 工作流。它是一个面向模型的工具策略，不是 agent-loop 的一个模式。每一轮起一个全新的子会话，靠共享工作区和一份有界的交接报告传递状态。
goal activation
「允许再跑一轮」的进程本地许可，刻意不进持久重放——所以 resume 和 fork 之后必须有一次人授权的恢复动作。
dynamic package动态包
M6 里模型自己定义的、只活在当前进程内存里的插件版本。pluginId 可变，packageId 不可变；改代码等于定义一个新 Package。

A.2　227 个包，按分组

这张图是本站的索引，也是一张诚实的分布图——包数在各组之间极不均匀，而这个不均匀本身就说明了问题。点任意一个分组名跳到它在 GitHub 上的目录。

3
包数中位数（均值 4.5）
17.6%
最大的一组 client 的占比（40 个包）
8
只有一个包的分组
28
个分组只有 3 个包或更少，占一半以上
图 A.2

每个分组的包数 · 按包数降序 · 共 227 个

client40
session13
subagent11
shell10
host8
core8
util7
fs7
web6
test-support6
context6
llm5
interaction5
workflow4
typert4
storage4
skill4
session-query4
sandbox4
goal4
extensions4
compaction4
terminal3
spill3
sdk3
lsp3
jobs3
hooks3
examples3
e2b3
credentials3
code-runtime3
bundle3
subprocess2
settings2
preset2
guard2
feedback2
experimental2
boot2
attachment2
api2
workspace1
todo1
schedule1
runtime-diagnostics1
plan1
mcp1
identity1
acp1
数据来自 packages/ 目录实际计数 · v0.1.1-rc.2 · commit b150a55 · 不含 vendor/ 与 native/。深色条是本站有专门章节讲过的分组。
怎么读这张图

一个分组不等于一个 seam。web 是完整的三件套（6 个包：1 定义 + 4 provider + 1 消费者），todo 只是一个工具（1 个包）。分组大小反映的是那块能力被切得多细，不是它多重要。

长尾很说明问题：一半以上的分组只有 3 个包或更少——正好是「定义 + 一个实现 + 一个消费者」的最小编制。这说明切分是有纪律的，同时也说明这条纪律被执行得非常彻底。

client 一家占 17.6%（40 个包）。这一个数字就解释了 M1 的形态之争：一个把 Web UI 也完全插件化的项目，前端自然会占掉很大一块。

A.3　时间线

这个项目很年轻。从第一个 commit 到 v0.1.1-rc.2，一共 73 天。

2026-06-10第一个 commit：「Initialize repo with README, AGENTS.md, and CLAUDE.md symlink」。AGENTS.md 和它的 CLAUDE.md 软链，是这个仓库最早的两个文件之一。
2026-06-11单仓基建：workspaces、tsc -b、vitest。
2026-06-13决策记录 capability-seams——三角色 seam 这个概念被确立下来，是整套架构的原点。
2026-06-21subagent-capability-seam：子代理成为一个可替换能力。
2026-06-24web-capability-seam：搜索与抓取共用一个 provider 选路服务。这就是 M2 拿来解剖的那个样本。
2026-07-05uniform-agent-note-format：决策记录本身有了被门禁校验的统一格式。
2026-07-08self-referential-cordis-toolset：agent 修改自己的运行时。同一天还有 tool-output-spill-files。
2026-07-12package-model-experience-contract——本站认为最有原创性的一条：token 成为每个包的公开契约。
2026-07-19fresh-agent-ralph-workflow-tool；同日 remove-generated-agent-note-index（「不要中心索引」本身也是一篇决策记录）。
2026-07-26frozen-agent-note-archive：归档树被永久冻结，用 hash 清单钉死。
2026-08-10session-log-version-mechanism：required-on-read 与 ignorable 的机制成型。
2026-08-17tag dsh-v0.1.0-rc.7。
2026-08-19tag dsh-v0.1.0-rc.8。
2026-08-21tag dsh-v0.1.1-rc.1 与 dsh-v0.1.1-rc.2——同一天两个 rc。本站全部内容核对于后者。

日期取自 git 历史与 Agent Note 文件名（文件名日期是该议题首次被提出的时间）。同类产品的发布对照本站不提供——那是二手数据。

一手 · 入口 仓库与官方文档 github.com/deepseek-ai/deepseek-harness
docs/architecture.md —— 改 packages/ 之前的必读
AGENTS.md —— 仓库宪法，M8 精读的对象
docs/glossary.md —— 官方术语表
一手 · 深入 框架与方法论 docs/cordis-primer.md —— Cordis 五个概念
cordiverse/cordis —— 框架上游
《A Programming Paradigm for Spatiotemporal Composability》 —— Cordis 的设计论文
docs/capability-seams.md —— 能力图谱
一手 · 生成式 不会跟代码分叉的那几份 tool-catalog.md —— 每个模型可见工具的精确 schema
config-catalog.md —— 每个插件的配置字段
docs/cordis-api/ —— 服务方法与事件
这几份都有 --check 形态的新鲜度门禁，见 M4.3
一手 · 决策 Agent Notes 精选 .agents/notes/README.md —— 体系说明
Model Experience 契约
capability-seams
self-referential cordis toolset
一手 · 工程 规范与门禁 docs/testing.md —— 测试政策
docs/defensive-patterns.md
.agents/skills/ —— 11 个 AI 可执行工作流
scripts/ —— 所有 verify-* 与 gen-*
社区 去哪儿问、去哪儿找插件 GitHub Discussions —— 反馈与 bug
GitHub topic dsh-plugin —— 社区插件
Discord
生态规模请自行去看，本站不做二手统计（见 M10.3）
目录

本页

附录 · 术语表 · 包地图 · 时间线