一切皆插件的 Agent 运行时

一、全景概览

什么是 Agent Harness

LLM 本身只是一个接收消息、生成消息的函数。真正让它成为能完成真实任务的 Agent 的，是模型外面那整套运行系统——系统提示词、工具、工作目录、权限、沙箱、会话、重试、子 Agent、UI，以及把它们组织起来的生命周期。这套运行系统就是 Agent Harness。

Harness 需要回答的 8 个问题

两条理解主线

理解 DSH 可以沿两条主线展开，它们分别回答不同的问题：

五层架构

DSH 可以粗略分成五层，从入口到能力插件逐层深入：

二、配置系统

DSH 的配置描述了整个应用的插件树。配置不是一个静态文件，而是由多层 Patch 叠加合成的最终 Entry 列表，再由 Loader 转换为运行中的插件树。

Entry / Patch / Overlay

Entry 的核心字段

Profile 与 Bundle

配置层优先级

composeProfile() 按以下顺序合成配置，越靠后的 Patch 优先级越高：

启动器内部 Patch 的特殊性

最后两层内部 Patch 不能写在 Bundle 或 Profile 中：

三、Cordis 内核

Cordis 是 DSH 的插件运行内核，源自 Koishi 聊天机器人框架多年的工程经验。它解决的核心问题是：插件如何安全地加载、卸载，以及依赖变化时如何重新协调。

Context 与 Fiber

Context 是 Proxy

插件拿到的 ctx 不是普通对象，而是一个 Proxy。属性读取会先检查真实属性；如果没有，就交给 ReflectService 按服务、Accessor、Inject 和 Isolate 规则解析。因此可以直接写 ctx.tools.register(...) 而不需要手动查找容器。

子 Context 使用原型继承

ctx.extend(meta) 以当前 Context 为原型创建新对象，再把 meta 作为自有属性写入。由此形成原型链：

rootCtx
  ↑ prototype
pluginCtx  （fiber 在这里）
  ↑ prototype
scopedCtx   （继续派生，仍属同一 Fiber）

Fiber 状态机

依赖满足：   PENDING → LOADING → ACTIVE
依赖消失：   ACTIVE → UNLOADING → PENDING
再次满足：   PENDING → LOADING → ACTIVE
最终销毁：   任意可销毁状态 → UNLOADING → DISPOSED

Epoch：依赖实现的指纹

epoch 不是简单的执行次数，而是当前依赖实现组合的指纹：只要有一项依赖找不到可用实现，结果就是 INACTIVE；依赖全部满足时，则将各服务提供者的 Fiber uid 拼成一个字符串。它既能表示"依赖是否齐全"，也能识别"服务实现是否已经被替换"。

Service / Event / Effect

理解 DSH 的插件模型，需要先认识 Cordis 提供的三种基础机制：

三者通常会在同一个插件中配合使用：通过 Service 暴露能力，通过 Event 接入流程，再由 Effect 保证相关注册和资源随插件卸载一并撤销。

Effect 的核心价值

ctx.effect(() => {
  const resource = acquire()
  return () => resource.release()
})

这种局部性非常重要：创建资源和释放资源在同一段代码里，而不是分别散落在 start() 和 shutdown() 中。Fiber 卸载时，所有 Effect 按逆序清理。

Events 的分发模式

Inject / Isolate / Intercept

这三个概念经常混在一起，可以用三个问题区分：

四、Loader 配置树

Cordis Core 管理单个插件实例的生命周期，Loader 则管理配置中的一组插件：它把 EntryOptions[] 变成 Entry 和 Fiber，并在配置发生变化后，让运行中的插件树收敛到新的配置。

Loader 的三重身份

三个运行时对象

Group 与 Include：两种嵌套方式

事务式更新

配置文件变化时，更新单位不是一个 Entry，而是整个 EntryOptions[]。EntryGroup.update() 遵循事务语义：

1. 为缺少 ID 的条目生成 ID，拒绝重复 ID
2. 并行创建或更新新配置中的所有 Entry，等待全部结果
3. 只有全部成功后，才删除不存在的旧 Entry，提交新的 group.data
4. 任意一项失败时，反向移除新增 Entry，按旧配置恢复
5. 回滚本身也出错时，合并原始错误和回滚错误

这样尽量保证一次配置更新要么形成完整的新树，要么回到更新前的可用树，不让只更新了一半的配置成为新的稳定状态。

五、Agent 核心运行时

packages/core 包含九个子包，它们共同构成了 Agent 的运行核心。Scope 和 Session 是底座，Agent 把它们组合成一个运行主体，Agent Loop 再使用 Prompt、LLM 和 Tools 驱动这个主体完成工作。

Scope：按 Agent 划分注册可见性

createScope(ctx, key) 创建一个由空插件 Fiber 支撑的子 Context，并给它写入 Scope key。通过这个 Context 完成的注册同时获得两种属性：

Session：事件日志是真相

Event Log 与 Surface 的分离

这与"直接维护一个 messages 数组"有本质区别。日志里可以保存 turn/start、step/start、assistant/chunk、tool/call、tool/result 等多种事件，其中只有一部分进入模型历史。

新的替换事件可以遮蔽旧 Surface 节点，而不删除原日志。这既保留了审计和回放事实，也允许压缩旧上下文——Compaction 不再意味着删除历史。

SessionStore ≠ 持久化后端

Core 中的 SessionStore 创建并持有内存 Session，提供 create()、get()、list()、fork() 和 flush() 等能力，但它故意不直接负责磁盘持久化。持久化插件订阅 session/event 并在 session/flush 上建立写入屏障——JSONL、本地数据库或其他存储实现可以替换，而 Session 的事件语义保持不变。

Agent Loop

Turn 与 Step

一次 Step 的完整过程

1. 追加 step/start
2. 把获准消息追加为 user/message
3. 从 Session Surface 派生历史
4. 组装 System Prompt 与 Tool Schema
5. 解析 Provider、Model 和 Adapter 默认值
6. 通过 agent/request 和 llm/stream 请求模型
7. 持续记录 assistant/chunk
8. 请求成功后提交完整 assistant/message
9. 调度模型给出的 Tool Calls
10. 按模型顺序提交 tool/call 和 tool/result
11. 追加 step/end
12. 判断是否还欠下一次请求

为什么既记录 Chunk 又记录 Message

流式 Chunk 用于忠实回放、UI 增量展示和 Usage 统计；完整 Message 是成功 Provider 调用的完成锚点，也是后续模型历史的稳定来源。如果请求失败，不会伪造成功消息。若用户取消时已经看到了非空文本前缀，循环会提交带 interrupted: true 的消息，使后续请求知道用户实际看见过什么。

工具并发

工具是否可并发由工具定义的 isConcurrencySafe(args) 分类：

• 独占调用形成屏障
• 声明安全的调用进入有界滚动池
• 启动前会重新分类，避免定义在排队期间变化
• 执行主体可以重叠，但策略、持久结果和结果上下文仍按模型顺序提交

Agent Loop 刻意不负责什么

默认循环只负责"请求模型、执行工具、判断是否继续"。其他行为通过插件接入：

工具流水线

一次工具调用不是直接执行 definition.execute()，而是经过一条可插入策略的流水线：

各阶段的职责

工具的三种呈现模式

六、完整调用链

前面分别拆开了配置、Cordis、Loader 和 Agent Core。现在把它们重新接起来，区分两条链：

• 组装主线：进程里最终有哪些能力？
• 运行主线：这些能力如何共同完成一次任务？

组装主线：dsh 如何变成一棵运行中的插件树

运行主线：一次 Agent 请求如何完成

这张图省略了插件事件，但保留了三条关键不变量：

1. 用户、Assistant 和工具的可见结果先成为 Session 事实，再用于后续模型请求
2. 每个 Step 至多对应一次模型请求，工具调用可能触发下一个 Step
3. Agent Loop 控制流程，策略插件通过事件和 Service seam 介入，不需要接管整个循环

两条主线在哪里汇合

组装主线最终产出 ctx.agents、ctx.systemPrompt、ctx.tools、模型 Provider 等服务；运行主线消费这些服务完成任务。插件树一旦更新，服务供给随之变化，运行中的任务则通过 Scope、依赖跟踪和 Step 边界感知这些变化。

七、设计原则与取舍

动态能力的代价

五个常见误解

八、调试与阅读指南

推荐源码阅读顺序

按源码目录从上到下读，容易先掉进大量具体插件。更高效的路径对应三个逐层深入的问题：

阅读一个插件时问四个问题

面对任意插件，不必一开始追完全部代码，先回答：

1. 它通过 inject 依赖哪些 Service？
2. 它通过 provide、事件或注册表贡献什么？
3. 它创建的副作用由哪个 Fiber/Scope 所有？
4. 卸载、失败和依赖消失时如何清理？

这四个问题通常比"它 export 了哪些函数"更接近 DSH 的真实架构。

按现象定位层次

三类问题的排查路径

九、术语速查