文章目录概述一、Cordis：dsh 的插件底座1.1 五个核心概念1.2 四种事件分发模式1.3 Waterfall 语义：环绕中间件1.4 Loader 与配置二、Profile 与 Bundle：组合的艺术2.1 核心概念2.2 五层叠加模型2.3 dsh-base：78 个插件行的基础层2.4 模式 Bundle：Web 与 Headless三、核心包：六包构成的脊柱3.1 Session：追加式日志，唯一真相源3.2 System Prompt：提示词组装器3.3 Tools：作用域注册表 + 守卫流水线3.4 Agent：接口、注册表与生命周期3.5 Agent Loop：默认驱动器3.6 Scope：按 Agent 划分作用域的原语四、轮次流程：一次问答的完整生命周期4.1 Turn 与 Step 的定义4.2 流程图解4.3 Turn/Start 与 Claim4.4 Pre-Step：决策点4.5 Step/Start 与消息追加4.6 模型历史派生4.7 模型请求与流式响应4.8 工具调用批次4.9 Turn-Stopping 与 Turn/End4.10 输入路由：同一个 Inbox4.11 取消与错误恢复五、工具执行流水线5.1 流水线全景5.2 Pre-Execute：允许/拒绝/询问5.3 Monotonic Guards：不可撤销的拒绝5.4 Execute：环绕分发5.5 Tool Body：实际执行5.6 Post-Execute：结果处理5.7 FinalizeContent：最后的内容守卫5.8 Tools/Result：不可变的权威结果5.9 并行工具调用5.10 UI 展示词汇六、能力缝（Capability Seam）：可替换性的设计模式6.1 三角色模型6.2 核心能力缝一览6.3 Seam 的威力：一键切换执行环境6.4 新行为的归属位置七、事件三域：选择正确的事件7.1 会话事件（Session Events）7.2 Agent 事件（`agent/*`）7.3 能力事件（Seam Events）7.4 Waterfall 事件汇总7.5 Serial 事件八、Agent Preset：按会话组合能力8.1 为什么需要 Preset8.2 Preset 工作机制8.3 Isolate Realm九、LLM 流式接口9.1 消息与内容块9.2 适配器注册9.3 请求配置十、其他关键子系统10.1 Approval（审批）10.2 Credentials（凭证）10.3 Settings（设置）10.4 Sandbox（沙箱）10.5 Spill（溢出文件）10.6 Compaction（上下文压缩）10.7 Subagent（子Agent）10.8 Goal（目标）10.9 Workflow 与 Ralph10.10 Session Telemetry（遥测）十一、全仓通用类型模式11.1 Map → Derived Union 模式11.2 品牌化 ID（Branded IDs）十二、运行时架构总览图附录 A：Cordis 核心 API 深度参考A.1 Context 上下文A.2 Service 与 ConfigA.3 Fiber：上下文隔离与继承A.4 Inject 依赖声明A.5 事件分发四种模式十三、会话日志深度解析13.1 SessionEventMap 完整事件词汇13.2 请求头事件：可重建性的保证13.3 TurnEndReason：轮次为何结束13.4 deriveMessages()：从日志到模型历史13.5 追加式日志的不变量十四、Shell 与沙箱子系统深度解析14.1 Shell 执行器：请求与规格分离14.2 正交结果独立报告14.3 沙箱模式与强制执行14.4 沙箱 argv 包装与方言分类14.5 沙箱策略解析十五、持久化子系统深度解析15.1 持久化 Seam 架构15.2 批量写入与 Flush 检查点15.3 崩溃恢复15.4 SessionHeader：日志旁的元数据15.5 格式拒绝十六、审批子系统深度解析16.1 审批模型16.2 按会话策略16.3 请求与分发16.4 审计事件十七、API Gateway 与 Typert 类型安全 RPC17.1 编程模型17.2 组件职责17.3 严格生成流水线17.4 运行时调用流程十八、LLM 流式接口与适配器 Seam18.1 消息词汇表18.2 适配器注册与重试策略18.3 请求配置与解析十九、其他关键子系统19.1 文件系统子系统（ctx.fs）19.2 子进程子系统（ctx.subprocess）19.3 Jobs 后台任务（ctx.jobs）19.4 技能系统（ctx.skills）19.5 子 Agent（ctx.subagents）19.6 代码运行时（ctx.codeRuntime）19.7 会话投影与查询（ctx.sessionProjection / ctx.sessionQuery）19.8 会话遥测（ctx.sessionTelemetry）19.9 用户问题与命令19.10 定时器（ctx.timer）19.11 Web 能力（ctx.web）二十、系统提示词组装流水线二十一、工具定义 DSL 详解工具输出的三种呈现工具结果的 additionalContexts二十二、测试架构与策略22.1 单元测试（vitest）22.2 覆盖率门控（test:coverage）22.3 真实 API 端到端测试（test:e2e）22.4 快照测试（test:snapshot）22.5 源码启动测试二十三、防御性编程模式详解23.1 正交结果独立报告23.2 空 catch 块必须命名所吞之物23.3 注册即副作用23.4 信任 TypeScript，在边界验证23.5 Waterfall 监听器必须调用 next()23.6 失败关闭（Fail-Closed）二十四、常见问题解答（FAQ）二十五、架构设计原则总结结语概述在 AI Agent 框架百花齐放的今天，大多数框架要么选择"黑盒魔法"路线，把循环逻辑硬编码在核心模块中；要么选择"极简内核"路线，把几乎所有能力都推给用户自行组装。DeepSeek Harness（以下简称 dsh）走出了第三条路：一切皆插件，但不是无政府主义的插件——而是有明确契约、可替换能力缝、严格生命周期管理的插件体系。dsh 构建在自研的 Cordis 插件框架之上，采用"服务定义 + 服务提供方 + 消费方"三角色能力缝（capability seam）模式，使得从 LLM 适配器到文件系统、从 Shell 执行器到子 Agent 委派，每一个环节都可以被替换、被扩展、被组合，而无需修改核心循环代码。本文将带你从底层框架到上层运行时，逐层拆解 dsh 的架构设计，理解它如何做到"没有特权内核"的同时保持系统的健壮性和可预测性。一、Cordis：dsh 的插件底座1.1 五个核心概念Cordis 是 dsh 以 vendor 方式引入的插件框架，理解它是理解整个 dsh 架构的前提。Cordis 的设计可以概括为五个核心概念：插件是实现 Service 的对象：一个插件可以是一个带有可选inject和apply(ctx)字段的函数，也可以是一个Service子类。它的生命周期由 Cordi
