摘要本章是 DeepSeek Harness 框架的术语速查字典按「核心名词、流程与状态、日志与数据、消息与模型、工具与安全、Cordis 机制、应用与宿主」七个维度逐条解释官方文档中高频出现的概念。每个词条都给出其在框架内的确切含义并特别标注了与其他框架的语义差异如ctx不是上下文窗口、profile不是用户档案、surface不是界面。核心要点包括会话日志是唯一真相来源、事件溯源与派生历史、模型可见即已记录、fail-closed 的安全默认方向以及 Cordis 的分发模式与副作用机制。适合作为阅读架构文档时的对照参考。11.1 核心名词术语英文 / 代码在这个框架里的含义Harnessdsh承载 Agent 循环的整套工程设施。管的是循环之外的脏活会话存储、提示词组装、权限审批、插件组合、多端入口。它本身不是模型也不是循环AgentAgent两层含义概念上指「模型 工具 循环」代码上指那个句柄对象插件通过它对话。注意Agent 句柄是「面向编程的接口」不是「一个 AI」Agent Loopctx.agentLoop驱动「请求模型 → 执行工具 → 回填结果」的循环。它也是一个插件而且不是唯一的实现插件plugin框架里唯一的零件单位。一个带apply(ctx)的函数或一个Service子类上下文ctx / Context共用的接线板。服务按名字挂在这上面插件按名字取用。不是「语言模型的上下文窗口」——那叫 contextWindow服务Service一项能力在上下文里占一个稳定名字ctx.tools、ctx.llm。服务本身也是插件提供的组合包bundle一包零件一个打包好、可安装的插件集合附一份 patch 文件。在package.json里用dsh.bundle声明profileprofile一张装配单列出要按顺序叠放哪些组合包、装了哪些树外插件、自己那层 patch 在哪。在package.json里用dsh.profile声明。不是「用户档案」patchcordis.patch.yml按 id 定位条目并整体替换它的 config。不是深度合并——覆盖时要重述想保留的字段HMRHot Module Replacement热重载。配置或代码改动后不重启就生效。由 YAML 决定启用与否由组合包层的声明控制seamcapability seam一项可替换能力由三个角色构成Service Definition接口、Service Provider实现、Consumer消费方作用域scope / ScopeKey「这个注册只对某个 Agent 生效」的机制。一次注册同时表达可见性和卸载所有权realms / 隔离域isolaterealm一个隔离区域让一组插件在里面运行即使和外部插件同名也不互相干扰。agent preset 用它隔离自己的服务行11.2 流程与状态术语英文 / 代码含义轮次turn从「领取首条输入」到「不再欠下任何工作」。包含零个或多个步骤。典型含义你按一次回车到模型彻底停手步骤step一次模型请求加上它调用的工具inboxinboxAgent 自己的收件箱有两条有序队列next-turn等待各自轮次和next-step等待下一个步骤边界领取claim把消息从待处理队列移走。领取后它要么进入这一步要么被明确丢弃不会两头都在steeringagent.steer()中途引导别停我补充一句你下一个步骤就按这个来injectagent.inject()为下一次 pre-step 排队「模型可见的上下文」不唤醒驱动器followupagent.followup()排一个普通的后续轮次并唤醒驱动器。界面上的「发送」就是它pre-stepagent/pre-step「这一步进不进」的 waterfall。请求发出前唯一的拦截点压缩也挂在这里turn-stoppingagent/turn-stopping轮次关闭前的 serial 检查点。想阻止结束就 steer 一条消息而不是返回 veto取消收敛cancel convergence取消之后活动逐步排空直到彻底停下来。这个过程中提交的唤醒输入会被排到下一轮静态 / idleidle没有驱动器在活跃。它是两个状态之一另一个是running运行中running从唤醒输入开始 pre-step 处理时进入持续到驱动器排空、关闭或检查点化。它可能跨越多个排队轮次不能用来判断某个轮次是否还开着11.3 日志与数据术语英文 / 代码含义会话日志Session log由类型化事件组成的仅追加流水账。整个系统唯一的真相来源事件溯源event sourcing不直接存「当前状态」而是存下所有发生过的事件需要时再推算出来派生历史deriveMessages()从日志推算出的「模型看到的对话」。从不单独存储每次需要时从日志重算surfaceSessionSurface日志里「真正会变成模型消息」的那一层有序视图。不是「界面」也不等于完整日志surfaceOpappend/replace一个事件是怎么加进 surface 的追加到末尾还是替换一段遮蔽shadow / shadowedSeqsreplace 会把一段节点盖住让它们不再出现在派生历史里。它们并没有从日志消失代次generation两种含义① surface 的替换代次replaceGenerationcontentGeneration② 会话文件的版本代次session.vN.jsonl。「已提交代次的路径绝不重命名、替换或删除」结算settlement一次尝试最终落定的结果。成功的落成assistant/message失败的落成assistant/attempt尝试attempt一次模型调用。一次适配器调用 一次提供方尝试重试会开一个新的种子seed创建会话时传入的初始事件序列用于回放或 forkforkfork在轮次边界从某个会话切一份新的会话出来投影projection从事件流折叠出「当前状态」的单元。比如「待办列表现在有哪些项」压缩compaction上下文太长时的处理先把过大的工具结果剪枝再选择摘要。没有面向模型的压缩工具可重建性reconstructability「每个对话请求都是日志的纯函数」。运行时会主动检查这条不变量模型可见即已记录model-visible means logged想让模型看到新输入就必须写事件。往前面的章节里藏东西是没用的11.4 消息与模型术语英文 / 代码含义内容块ContentBlock一条消息里的一个片段文字、推理、图片、文件、工具调用等。联合类型从ContentBlockMap派生推理块ReasoningBlock模型的「思考」内容和它可见的回答文字分开存工具结果ToolResultMessage**它是一个消息不是一个内容块。**含有toolCallId、结果 content 和可选的isError分片StreamChunk模型吐回来的原始流式数据。有 7 种block-start、text-delta、reasoning-delta、tool-call-delta、block-end、usage、finish装配器BlockAssembler把分片流折回完整内容块、usage 和结束原因的唯一共享实现。不要自己写第二份紧凑 streamAssistantStreamRecord把原始分片流压缩存储的形式合并连续增量但不合并 token 边界也不丢时间戳结束原因模型FinishReason模型为什么停stoptool-callsmax-tokensabortederror结束原因轮次TurnEndReason轮次为什么结束七种。max-tokens优先于completed适配器LlmAdapter提供方协议到框架消息词汇的翻译层。只有一个抽象方法必须实现stream()回放状态ReplayEnvelope适配器私有的、用于重现提供方响应的不透明状态。内容对框架不透明只有「切分方式」是共享的优雅降级degrade读取适配器无法使用的已存状态时只把这一条消息降级为与提供方无关的转换并带出诊断而不是让整个请求失败上下文窗口contextWindow「请求 响应」合计的最大 token 数。这是模型的能力和「上下文 ctx」完全是两回事请求信封EpochHeader记录调用配置provider、model、推理强度、采样参数 适配器默认值标记 组装好的工具 schema。系统提示词不属于它11.5 工具与安全术语英文 / 代码含义规范值canonical value工具函数体返回的那个结构化 JSON 值按output.schema校验。给它程序用渲染output.render把规范值投影成模型能读的内容块。给它模型用守卫ToolGuard单调的最终预分派策略。只能拒绝没有「强制放行」这个结果所以顺序无法把拒绝翻回允许决策Decisionwaterfall 返回的类型化结果。前置有 4 种后置有 3 种前置流水线tools/pre-execute可重排的允许拒绝取消询问策略层环绕分派tools/execute包装层。只允许替换exec.signal不能移除它——替换后注册表还会重新融合调用方的 signal后置流水线tools/post-execute接受 / 替换内容 / 替换值 / 阻止结果 / 附加下文最终内容不变式finalizeContent面向模型内容的同步最后一公里变换。恰好调用一次包括绕过 post-execute 的失败。必须不抛异常执行模式ToolExecutionModeparallel可与兄弟重叠或exclusive独占形成屏障。默认 exclusivefail-closed渲染意图ToolCallView / ToolResultView工具描述「我在界面里长什么样」的中性词汇genericterminaldiffreadsearchweb。必须是纯函数沙箱ctx.sandbox消费方交出即将 spawn 的确切 argv后端按每次调用的策略包装它并报告强制执行情况审批ctx.approval一次性权限决策。allowed-once才继续没有回答方时以unavailable关闭失败也就是拒绝权限预设ctx.permissionPresets把沙箱模式和审批策略选项组合在一起的用户可见预设workspace-writedanger-full-accessPTCPTC mode / run_code让模型写一段代码来批量调用工具而不是一次次单独调用。传输名是保留字run_code。它不绕过任何安全检查spillctx.spillStore过大的工具文本会被存到后端返回给模型的是「定位信息 取回提示」避免撑爆上下文11.6 Cordis 机制术语英文 / 代码含义分发模式emit / waterfall / parallel / serial / bail事件的五种传播方式。分发模式是事件公开约定的一部分用错方法就收不到waterfallctx.waterfall环绕中间件。监听器拿(...args, next)调next()往下传不调就直接返回短路短路short-circuit不调next()直接返回。对单决策事件来说这是设计意图不是 bug副作用 / effectctx.effect()一种会随插件卸载而自动撤销的注册。所有注册都应该是它disposerdisposer资源释放函数。每个注册都要有。如果 teardown 有顺序要求相关工作要放进同一个 effect声明合并declaration mergingTypeScript 机制。插件用它往框架的类型里加条目不需要修改框架源码Map → 派生联合…Map→ union全仓库通用的扩展模式。五个规范 MapContentBlock、MessageSource、FinishReason、TurnEndReason、SessionEvent品牌化 IDBranded /brandStringT()结构上是字符串但类型上不可互换。SessionId不能传给需要ToolCallId的地方作用域载体ScopedT/scopeTarget()一个只用于路由的接收器。它不暴露主体的属性真正的事件主体仍然作为显式参数传入惰性创建lazy layer作用域层不预建用到才建。读取不会创建 layer——否则查询会导致内存增长发起方initiator /withInitiator同进程内的因果归因。「有发起方」不等于「有权限」——归因和授权是两件事fail-closedfail closed出问题时默认「关闭」拒绝而不是默认「放行」。这套架构里反复出现这个方向11.7 应用与宿主术语英文 / 代码含义启动器launcher / dsh唯一的应用入口。它拒绝任何绕过dsh的 Node 应用路径app-bootdsh-app-boot启动器背后的库加载环境层、组合 profile、启动插件、激活审计、返回运行中的应用required 条目required entry启动的关键条目。它失败就要拆卸整个应用并非零码退出而不是带病运行ACPAgent Client Protocol一个用于自动化客户端的协议。acpprofile 就是仅用于自动化的 ACP 服务器Harness home$DSH_HOME框架的数据目录。profile 放在$DSH_HOME/profiles/name用户级.env和cordis.patch.yml也在这里环境层layered env.env的加载顺序调用目录的文件优先于 harness home 的文件两者都低于继承环境runtime resolutionruntime resolution由「安装依赖图 有序组合包依赖图」算出的不可变解析结果在挂载插件前装进 Node 的解析器这一章之后到这里十一章正文就全部结束了。剩下的四个附录是纯工具性的速查表不需要按顺序读按需查阅即可写扩展时查附录 A写服务名时查附录 B写完自查附录 C跟同事争论口径时查附录 D。内容整理自 DeepSeek Harness 官方仓库docs/architecture.zh.md及其引用的全部子系统与包文档。官方项目处于开发者预览阶段具体字段与命令请以你手上的代码为准。