DeepSeek Harness 术语表：六个核心概念

DeepSeek Harness 是 DeepSeek 开源在 GitHub 上的 agent 工程 harness，采用 MIT 协议。翻开它的 docs 目录，会看到一份很短但地位特殊的文档：术语表（glossary）。它开篇只有一条原则：每个概念只保留一个规范术语，全仓库统一使用，实现细节则下沉到各包的 README 与内部笔记里。这份术语表一共覆盖六组概念：能力接缝、agent 作用域、目标、人类命令、循环层级和 Ralph。本篇按官方中文版的口径，把这六组术语整理成一篇速查。

一、capability-seam：一个接缝，三种角色

seam（接缝）是术语表的第一个词条，指一种可替换的能力。它不是单个类，也不是单个包，而是三种角色的组合：

• Service Definition：拥有自己的 ctx.<key> 和词汇类型的 Cordis Service。它可以是 ShellExecutor 这样的抽象类，也可以是 WebRuntime 这样的具体注册表，但绝不是 TypeScript interface；
• Service Provider：服务的提供方，一个或多个；
• Consumer：注入并使用该服务的消费方，一个或多个。

官方给出的规范范例是 packages/shell：dsh-shell 扮演 Service Definition，dsh-bash-local 与 dsh-bash-sandbox 是两个 Provider，dsh-tool-bash 则是 Consumer。三个角色需要独立演进时通常各占一个包；但属于同一关注点时也可以合并，比如 dsh-llm 就同时承担 Definition 与 Consumer。术语表还特意划了红线：seam 永远指完整的能力整体，不指其中任何一个角色；要称呼组成部分，请按角色、类、服务、约定或扩展点来命名。

二、agent-scope：扁平两层的注册单位

scope 是按 agent 划分的注册单位。一项贡献（工具、提示词段、变量、限制、监听器）要么是全局的，对所有 agent 可见；要么是带作用域的，归属于恰好一个 scope key。层级只有两层，而且是扁平的：带作用域的注册不会向下继承给 subagent；子树级别的行为用 lineage 数据表达，不靠作用域结构。

围绕这个模型还有一组词：

• scope key：scope 的不透明标识，按对象同一性比较。约定是，一个活跃的 agent 就是它自己 scope 的 key；
• agent 上下文：即 agent.ctx。通过它做的注册既有 scope 可见性，生命周期也绑定到该 scope，一个事实同时决定两件事；挂在它上面的监听器会参与该 agent 的作用域过滤分发；
• scope carrier：作用域过滤分发所携带的 thisArg，由 scopeTarget 构建；没有主体的 carrier 只放行无标签监听器；
• scoped dispatch：关于某个 agent 活动的事件，用该 agent 的 carrier 分发；而关于注册表本身的事件，比如"一个工具被添加了"，按各自的事件约定保持不过滤；
• shadowing：最具体者胜出的名称解析。带作用域的工具、提示词段或变量，仅在该 scope 内替换同名的全局对应项，这就是按 agent 定制 persona 和工具变体的机制；
• restriction：为单个 scope 过滤全局工具集合，多个 restriction 取交集组合，scope-local 注册在过滤之后合并；被过滤掉的工具既不出现在提示词中，也拒绝执行，与不存在的工具无法区分；
• setup window：创建者组装 agent 作用域环境的时隙（CreateAgentOptions.setup）。此时 scope 与 agent 对象已经存在，但 agent 或会话尚未发布，agent/session-start 尚未触发，首次提示词尚未组装。setup 只负责注册，从不驱动 agent；
• lineage：以数据形式携带的父子关系事实，例如 parentSession、持久的 delegationDepth、运行时的 subagentDepth，它从不影响可见性。

三、goal：是状态，不是调度器

goal 是附着在现有会话上的单个持久完成目标，带按修订号演进的 active、paused、blocked、complete 四个阶段，并有一个 goal round 上限；blocked 状态会保留策略代码与说明。术语表强调：目标是状态，不是调度器，也不是一段独立对话，会话日志始终是真源。

goal round 是为当前目标接纳的一次续行周期，由同会话驱动器具体化为一个目标触发的轮次，可含零到多个 step；同一会话里无关的人类轮次不消耗这个上限。goal activation 则是续行消费方接纳下一个 goal round 的进程本地权限，只有 armed 与 disarmed 两态。它有意不参与持久回放，因此恢复或 fork 之后，必须先通过 /goal 或模型工具执行一次经人类授权的恢复变更，自动工作才能开始。

四、human command：斜杠命令住在命令平面

human command 是以斜杠开头的指令，由面向人类的适配器经 ctx.commands 解释并执行，不会变成模型消息。它既不同于面向模型的工具，也不同于经 ctx.shell 执行的 shell 命令。发现、解析、分发、取消与结果渲染合称 command plane（命令平面），归 UI 适配器与命令插件所有；除非处理器另行改动持久领域，命令输出属于 UI 状态。/goal 命令由 dsh-command-goal 提供，直接观察或更改当前目标，而每条持久且模型可见的记录都归目标领域所有。

五、loop hierarchy：round、turn 与 step

循环层级自外向内三层。round 是承载一个轮次的外层策略迭代，例如一个 goal round，或一次使用全新 agent 的 Ralph 尝试；turn 是会话中一次对已接纳输入的排空过程，在模型及其工具停止工作或终止策略介入后结束；step 是一次模型请求加上由响应引发的工具执行，一个 turn 包含零到多个 step。注意 round 计数器归策略所有，并不统计会话中的每个 turn。

六、Ralph：全新子会话与有界交接

Ralph loop 是一次面向不可变目标的前台全新 agent 工作流运行，由工作流与 subagent 原语组合而成，本质是面向模型的工具策略；它不是同会话目标，不是 agent loop 模式，也不是调度器或通用工作流脚本功能。

Ralph round 是 Ralph loop 中的一个全新子会话。子会话不接收父会话或此前子会话的任何对话种子；跨 round 的状态只靠两样东西承载：共享工作区，和一份有界的 Ralph handoff。handoff 是规范化的结构化报告，包含状态、摘要、证据、后续步骤、阻塞说明五个部分；它是共享工作区的补充，而不取代工作区的权威地位。

一词一义的价值

这份术语表真正想解决的是协作语言的歧义：seam 只指完整能力，lineage 只记事实不影响可见性，goal 只做状态不做调度，Ralph loop 只是一种工具策略而不是循环模式。读 DeepSeek Harness 的源码或文档时，遇到这些词按规范义理解，不会再出现同一个词各有各的理解的情况。完整双语版本见仓库 docs 目录下的 glossary.md 与 glossary.zh.md。