DeepSeek Harness 完整原理学习文档

0全局心智模型

三层视角

五条设计公理

核心不变量（Invariants）

不变量的三层强制

因此，新的模型可见输入必须对应新的会话事件；agent/request 可以改变路由和调用配置，但不能偷偷改变 messages。

1底层完成 · 启动与插件组合

"一个运行中的 dsh"本质是一棵在启动时按有序层组合而成的插件树。组合的产物是一份 cordis.yml 配置行（entry）列表，Loader 据此导入插件、激活 fiber。

1.0 Cordis 插件内核：服务、依赖与效果

在 Harness 中，插件不是一段孤立的初始化函数，而是向当前 Context 注册服务与事件的可拆卸单元。 理解下面四个概念，再读后面的 profile、agent 和工具流程会更容易：

示意：插件的服务 + 可逆注册
class ExamplePlugin {
  static inject = ['session']
  apply(ctx) {
    ctx.provide(ExampleService, new ExampleService(ctx.session))
    return ctx.effect(() => ctx.on('agent/status', onStatus))
  }
}

1.1 Profile 与 Bundle

1.2 层的应用顺序

CLI 启动时所有层都被 patch 到一个空 entry 列表上，顺序如下（apps/cli/src/profile-boot.ts:131-170）：

patch 通过 id 定位一行并整体替换其 config，或插入新行。要查看本机实际启动的树：

$ 命令
dsh --profile web --dump-config   # 组合可导出的配置层，输出带来源注释的 YAML，不 boot、不求值 !!js

1.2.1 逻辑层与实际应用步骤

原理上可以把组合分成“核心能力、模式能力、用户覆盖”三类；源码执行时还会把覆盖拆成多个有序步骤，并附加 launcher 派生信息。 因此下面的五步是运行时应用步骤，不是五种互相独立的架构层：

1.2.2 组合算法与最终启动层

composeEntries()（packages/boot/app-boot/src/profile.ts:405-420）只负责把传入的 patch 列表折叠到空 entry 列表。 完整的 boot 层组合位于 apps/cli/src/profile-boot.ts:131-170；--dump-config 与 boot() 共用空根和 applyEntryPatches 算法， 但 dump 当前不会加入 launcher 派生的 agent-presets shipped-root 与遥测 overlay，因此两者的最终配置不完全相同。

1.3 boot() 启动序列

boot()（packages/boot/app-boot/src/index.ts:757-802）是核心驱动：

2底层完成 · 循环驱动状态机

ReactLoopAgent（packages/core/agent-loop/src/agent.ts）是默认驱动器，实现 Agent 接口。 它把一个 session 推过 turn 与 step 边界。每个请求都从会话日志派生。

2.1 三态状态机（Phase）

状态转换通过 setPhase() 提交，并在 idle ⇄ running 时发布 agent/status 事件（agent.ts:104-111）。 maintenance 不改变对外 status（仍是 idle）——它是"闲时的独占任务"。

2.2 Turn 与 Step 的关系

2.3 完整 Turn 流程（含事件）

docs/architecture.md:67-82 + agent.ts:246-330
turn/start                                       durable
  claim next-step 输入 + 一个排队消息
  组装 prompt sections + tool schemas
  → agent/pre-step live·waterfall        reject | enter(messages)
     reject，或首个 enter 被改写为空 → 关闭 turn（不消耗 step）
     step/start                                  durable
     把进入的消息追加为 user/message
     从日志派生模型历史 deriveMessages()
     agent/request → llm/stream → assistant/chunk* → assistant/message
     tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result*
     step/end                                    durable
     工具欠另一个请求，或 next-step 输入到达 → claim → 下一个 step
  → agent/turn-stopping live·serial
turn/end                                         durable

2.4 关键循环方法

2.5 turn 的结束原因（TurnEndReason）

注意 max-tokens 是粘性的（sticky）：一旦某个 step 撞到上限，后续正常完成的 step 不得降级 turn 结果（agent.ts:287-290）。 interrupted 是循环从不实时发出的原因——只有持久化重载路径产生它（见 §8）。

3底层完成 · 工具执行管线

executeToolCalls()（packages/core/agent-loop/src/tool-calls.ts）调度一个 assistant step 的工具调用。 互斥调用形成屏障；并行调用使用有界滚动池；在启动前重新分类。 调度可重叠，但策略、结果、结果上下文保持模型序。

3.1 调度器四阶段（TOOL_RUNTIME_SCHEDULER）

符号键 [TOOL_RUNTIME_SCHEDULER]（tools/src/index.ts:796）向循环暴露分阶段管线。 拆分是为了让 pre/post 策略保持有序，而 dispatch 可重叠：

3.1.1 执行关卡与持久结果

工具执行的安全性不是一个 try/catch，而是从模型提出调用到持久结果回到模型的一串有序关卡：

tools/result 是进程内的 live 观察事件；tool/result 才是写入 session 日志的 durable 事件。两者名称相近，但恢复职责不同。

3.2 三个 Waterfall 事件

3.3 并发分类与屏障

executionMode(exec)（index.ts:1276）：只有工具 isConcurrencySafe(args) 精确返回 true 才是 {kind:'parallel'}； 未知/隐藏/未声明/抛错的分类器全部 {kind:'exclusive'}——fail-closed。互斥调用形成排序屏障。

3.4 中止语义（关键）

3.5 restrict() 与作用域交集

restrict(filter)（index.ts:1071）是仅作用域的（需要 agent.ctx）：allow/deny 作用于全局工具名。 作用域链上多个 restriction 取交集：一个工具只有当链上每一层都 admits 时才可见。

3.6 审批与 loop-hygiene

真正单调的 guard（取消、超时、权限或策略拒绝）只能收紧执行结果，不会在已经拒绝后重新放行。 repeat-tool-reminder 是建议性插件：它识别连续相同的规范化调用并注入提醒，不阻止或改写调用，也不改变可执行集合。 工具执行失败仍必须回到统一的 tool/result durable 语义，保证日志配对和下一次请求可重建。

4上下文组装 · 全链路

这是文档要求的重点之一：从会话日志 + 已注册的 provider → 组装的提示 → 冻结的模型请求。 核心入口是 SystemPrompt.assemble()（packages/core/system-prompt/src/index.ts:467）。

4.1 数据流总览

4.2 SystemPrompt 注册的四种贡献

4.3 assemble() 内部步骤（system-prompt/index.ts:467-542）

4.4 renderPrompt 插值（严格 {{variable}}）

renderPrompt()（index.ts:212）对每个 section 插值，丢弃空段，用 \n\n 连接。 插值是严格的：畸形、未知、undefined 的引用都抛错；孤立的 {{（无后续 }}）当作字面散文，被替换的值不再扫描。

4.5 RuntimeContextProjection（去重的动态快照）

packages/core/agent-loop/src/runtime-context.ts 是把组装出的运行时上下文快照转成至多一条 UserMessage 的去重适配器。 它从不拥有提交（循环的 preStep 决定是否追加）。

4.6 deriveMessages（surface 投影的模型历史）

Session.deriveMessages()（session/index.ts:726）从日志派生模型可见的历史。只有三种事件类型是 surface-eligible （packages/core/session/src/surface.ts:15-28）：user/message、assistant/message、tool/result。

4.7 agent/pre-step 瀑布（拒绝 / 重写点）

preStep()（agent.ts:225-243）在组装后运行瀑布。默认 next() 把投影的运行时上下文并入 claimed 消息。

agent.ts:225-243
private async preStep(target, { turn, step }) {
  const claimed = this.inbox.claim(target, turn)
  const assembly = await this.loopCtx.systemPrompt.assemble(assembleContextFor(this, signal))
  const sections = renderContextSections(assembly)
  const context = this.runtimeContext.project(joinContextSections(sections), sections)
  const decision = await this.dispatch.waterfall(
    'agent/pre-step', { messages: claimed, ...position, signal },
    (): Promise<PreStepDecision> => Promise.resolve({ kind: 'enter', messages: context === undefined ? claimed : [...claimed, context] }),
  )
  return decision.kind === 'reject' ? decision : { ...decision, assembly }
}

4.8 冻结的模型请求（链路终点）

agent.ts:486-494
const request = markAgentLoopRequest(deepFreeze({
  ...header.config,
  messages: boundaryMessages,          // = session.deriveMessages()
  ...header.system !== undefined ? { system: header.system } : {},  // = renderPrompt(assembly)
  ...header.tools !== undefined ? { tools: header.tools } : {},   // = assembly.tools
  sessionId: this.session.id,
  signal,
}))

markAgentLoopRequest 用 WeakSet 标记该请求由循环构建；deepFreeze 深冻结但跳过 AbortSignal（那是活的取消通道，冻结会破坏中止）。 因为请求内容是日志的纯函数，监听器只读不改——这是"可重建性"不变量。

5上下文组装 · Scope 作用域基座

packages/core/scope 是让作用域提示/工具/变量注册生效的基座。它铸造一个带不透明身份标签的 Cordis context， 并为该身份构建仅用于路由的事件载体。

5.1 一个父关系，两个方向

同一个 parent 关系同时驱动两个方向（scope/index.ts:33-39）：

5.2 scopeTarget 准入规则

scopeTarget(base, key)（scope/index.ts:170-185）构建一个不透明载体，其 [Context.filter] 准入：

1. 未标签的监听器——全局可见（tag === undefined → true）
2. 匹配 key 或其任一祖先的标签监听器（从 key 沿父链走）

dispatch key 之下的标签仍被排除——这就是为什么一个 standing composition 能观察到组合在其下的每个 agent。

5.3 ScopedLayers 的"最近者胜"遮蔽

chainLayers(scope) 返回最远祖先优先、最近作用域最后的现有 overlay。 merge() 先物化全局条目，再让链遮蔽，所以同名条目最近者胜。 这是 §4.3 中"作用域 section 遮蔽全局 persona"的底层机制。

5.4 Preset 是 standing mount

Preset 不是每次创建 agent 时重新组合整棵插件树，而是一个进程级的 standing mount：组合完成后常驻， 每个 agent 只在自己的 scope 中绑定 preset 选择。这样可以复用共享 provider，同时保留 per-agent 的提示、工具和变量隔离。

5.5 initiator 与因果归因

initiator 用异步上下文保存“这次嵌套工作由哪个 agent/session 发起”。工具、子 agent、遥测和日志观察者可以读取这条因果关系， 从而使用正确的 scope 与 session 标识；它不依赖全局可变的“当前 agent”变量，也不会把并发请求错误归到同一个 owner。

6失败恢复 · 会话日志与持久化

这是文档要求的重点之二。统一契约：会话事件日志是唯一持久真相，只追加，seq 连续。 每条恢复路径都从这条日志重建。存活内存状态（inbox、派生消息、头部折叠、AbortController）是投影，靠回放 splice/chunk/header 重建。

6.0 事件信封与来源链

会话事件不是“随手塞进数组的对象”，而是带统一信封的有序事实。声明合并扩展的 SessionEventMap 提供类型映射， 运行时再由 append() 统一盖章；持久化读侧另有生成的 KNOWN_SESSION_EVENT_TYPES catalog 判断当前构建是否认识事件类型。

6.1 Session.append（单一提交点）

Session.append()（session/index.ts:604-655）是唯一提交点，恢复契约在此强制：

6.2 持久化三态：load / inspect / prepare

包 @deepseek-ai/dsh-session-persistence（packages/session/session-persistence/）。PersistenceCoordinator 是共享写路径编排；JSONL 后端是文件实现。

6.3 prepareCore 的重建（coordinator.ts:892-931）

SESSION_FORMAT_VERSION = 0（types.ts:56），盖入 header，恢复时校验。无迁移代码——版本不符即硬拒 （SessionFormatUnsupportedError）。Pre-release 立场：后端拒绝旧格式。

6.3.1 持久化双版本与读侧三道门

读侧按三道门接纳数据：

1. 版本门：header/session format 与后端 schema 都必须在支持范围内。
2. 事件门：事件类型必须在当前构建生成的 KNOWN_SESSION_EVENT_TYPES catalog 中；未知事件只有明确标记 ignorable 才能跳过。
3. 必读门：默认事件是 required-on-read；构建不知道其类型时拒绝日志，只有结构化的可忽略事件可以携带 ignorable:true。

6.4 写后（write-behind）与失败保留

SessionWriteBehind（write-behind.ts）是每会话的批量写，带固定 deadline。失败时（write-behind.ts:138-157）： 批被保留在内存（pending = batch.concat(this.pending)）、定时器取消、automaticPaused 置位并上报；失败路径不会主动丢弃当前批， 但尚未持久化的事件不能抵抗进程崩溃。

6.5 Inbox 恢复（增量投影）

Inbox 是对 durable agent/inbox/spliced 事件的增量投影（packages/core/agent/src/inbox.ts:24-39）。构造时回放 seedLength 之后的所有 splice 重建状态。 每次 mutate() 在变更存活投影前先提交 durable 事件——所以同步 session/event 观察者看到的是 pre-splice 列表，能从归一化坐标重建被移除消息。

6.6 Fork（分叉活会话）

fork(source, boundary?, childSessionId?)（index.ts:1081-1138）切片活源会话的稳定前缀。_forkSeed 校验： boundary 是安全整数、存在、连续，且所选切片不得结束在开放 turn 内（否则 OPEN_TURN 错）。子会话带 meta.parentSession 与 meta.seedLength 血统。

6.7 投影缓存的三档读取

日志恢复之后，内存投影按成本和可信度分成三档：snapshot 是当前可直接使用的快照， checkpoint 是经过事件序号标记的中间投影，restore 则从 seed 与后续事件重新回放。任何缓存都不能成为新的事实来源； 实际 cache 以 projection stateVersion、checkpoint seq 和 session identity 判断可复用程度。日志缩短、身份不匹配或版本不匹配时丢弃缓存并从更早序号或完整日志 restore。 surfaceOp 与 fork 作为普通事件进入日志，由 projection 回放处理；不要把 generation 写成 projection cache 的通用失效条件。

7失败恢复 · 取消与终止语义

7.1 四种取消原因

7.2 cancel() 行为（agent.ts:134-140）

agent.ts:134-140
cancel(cause: AgentCancelCause, options: CancelOptions = {}) {
  if (!options.keepInbox) {
    this.inbox.clear()                         // 持久 canceled splice
    if (this.phase.kind !== 'idle') this.phase.wakeRequested = false
  }
  if (this.phase.kind !== 'idle') this.phase.abort.abort(cause)   // cause 成为 AbortSignal.reason
}

turn 读取 signal.reason as AgentCancelCause，发射 turn/end{kind:'aborted', reason}。

7.3 keepInbox：两种停止的区别

7.4 aborted 后的唤醒输入（微妙之处）

在 abort 之后提交的唤醒输入，被分类为 wakingAfterAbort（在插入前捕获，agent.ts:116）， 路由到 next-turn，所以它存活下来并启动下一轮。唤醒本身被锁存（wakeRequested=true，agent.ts:179）—— 仅当 cause 非 disposed 且驱动处于 maintenance 或已中止时；收敛时若 inbox.hasPending，唤醒回放。

7.5 AgentLoop 生命周期：prepare / dispose 反向拆卸

AgentLoop.prepare()（agent-loop/index.ts:459）在任何资源存在前就注册反向 teardown。三个所有者的 abort 被熔合： 调用者取消信号、owner fiber 卸载、factory teardown。dispose 是记忆化的（disposing ??=），所以每个竞速的 owner 等待同一个静止点。

agent-loop/index.ts:497-520 （dispose 反向 teardown）
const dispose = (ownerTriggered = false) => (disposing ??= (async () => {
  abort.abort(new Error(`agent "${id}" lifecycle disposed`))
  // ...移除监听...
  try {
    if (machine === undefined) await machineReady.promise
    if (machine !== undefined) {
      machine.cancel({ kind: 'disposed' })   // disposed cause — 不锁存
      await machine.whenIdle()             // 等待静止
      await machine.scope.dispose()        // 解开作用域
    }
  } finally {
    detachAgent()?.(); detachSession()?.()   // 离开注册表
    untrack()
    if (!ownerTriggered) await unfollowOwner()
  }
})())

8失败恢复 · 崩溃修复与压缩

8.1 崩溃修复 interruptedTurnClosers（repair.ts:27）

修复的是被中断的最后一轮——崩溃让日志留下开放 turn/start 而无配对 turn/end。 它不修复任意损坏；它只合成缺失的边界（在已完整写入的事件前缀之后）。单次前向扫描，跟踪 openTurn / openStep / pendingCalls， 在平衡尾返回 []；否则合成（全部复用最后真实事件的 time，seq 从 last.seq+1 续）：

关键重置语义：每个 turn/start / turn/end / step/end 都 pendingCalls.clear()——更早轮的调用不会泄漏到尾修复。

8.2 撕裂尾检测（JSONL）

SessionLogScanner（session-persistence-jsonl/src/format.ts）：撕裂尾是最后一条无结尾换行的记录，或一个部分 Zstandard 帧。 consumeEventLine 只在每个完整换行终止的记录之后累加 committedBytes，所以撕裂尾的字节被排除出前缀。 JsonlTornMarker 带 truncateTo（字节偏移）+ recoveredEvents（从部分 Zstd 帧抢救的明文）。

8.3 commitRepair（持久化修复）

commitPrepared（coordinator.ts:934-963）：若 tornMarker !== undefined || closers.length > 0，调用 backend.commitRepair（JSONL：truncate 到 truncateTo + fsync，再 append recoveredEvents + closers）使修复持久， 然后返回 undefined 强制重载（修复改变了持久 revision）。两步 fsync，接缝不要求原子性。

8.4 上下文压缩（compaction）

packages/compaction。CompactionEngine 是 Service Definition，provider 子类化。两种触发：'pressure'（正常阈值）与 'context-overflow'（provider 确认溢出，可能在阈值下强制一次有用的平衡缩减）。

9附录 · 事件扩展点速查

事件是扩展点，选对域是大多数改动的第一个决策。Cordis 四种 dispatch 模式：

三大事件域

关键 Waterfall 事件清单

能力接缝：三角色必须成套

类型模式与工程门禁

扩展点选择

关键源码索引

读源码时建议按“接口 → 组合 → 提交 → 投影 → 驱动”的顺序跳转：

10附录 · 术语表