DeepSeek Harness 技术文档系列

项目：deepseek-ai/deepseek-harness（dsh）· MIT · 当前 developer preview

官方文档：https://deepseek-harness.github.io/deepseek-harness/

源码：https://github.com/deepseek-ai/deepseek-harness

本文档为「系列技术文档」的总计划，包含项目分析、系列结构、分阶段写作路线与参考资料索引。

0. 项目分析摘要

0.1 项目定位

DeepSeek Harness（dsh） ：DeepSeek AI 开源的智能体运行时（agent harness），用「一切皆插件」的架构驱动 LLM agent。
核心哲学 ：产品每一部分（模型适配器、工具注册表、会话日志、agent loop 本身）都是插件，全部可从配置替换；不存在需要打补丁的特权内核，扩展 = 在别的插件旁挂载插件，注册项作为副作用在插件卸载时自动撤销。
底层框架 ：Cordis（cordiverse 出品，设计理念见论文《A Programming Paradigm for Spatiotemporal Composability》），以 vendored 形式引入 vendor/。

0.2 技术栈

维度	选型
主语言	TypeScript（主）+ Python（`python/` 辅助）
包管理	pnpm workspace（`pnpm-workspace.yaml`）
构建	tsdown + tsc solution build（`tsconfig.host.json` / `tsconfig.base.client.json`）
测试	Vitest + PyTest
Lint	Oxlint / ESLint / lefthook / jscpd / knip
核心框架	Cordis 4.0.1（vendored）、cosmokit
沙箱	landlock-run（`native/`）、sandbox-exec

0.3 启动与运行

预构建：npx @deepseek-ai/dsh web → 默认 http://127.0.0.1:3080
源码：git clone ... && pnpm install && pnpm run build && pnpm dsh web
运行形态：web （浏览器应用）、headless （一次性运行器、无服务器）、cli 、ACP 、SDK

0.4 包结构地图（`packages/` 下 48 个包，按职责归类）

启动/宿主 ：boot host runtime-diagnostics util typert test-support
核心子系统 ：core（含 agent-loop）session system-prompt tools scope llm context identity
模型/执行 ：code-runtime shell subprocess terminal lsp fs
安全/策略 ：sandbox guard hooks preset plan credentials settings
能力插件 ：mcp subagent skill todo goal schedule jobs workflow compaction spill attachment feedback interaction storage workspace session-query extensions
协议/接口 ：acp api sdk client web e2b
组装/示例 ：bundle examples

0.5 关键概念速查

Profile ：Harness home 中的具名组装，列出叠加的 bundles + 树外插件 + 用户 cordis.patch.yml；web / headless 作为模板随发行版交付。
Bundle ：Cordis 配置行 + 挂载代码的发布格式；在其 package.json 用 dsh.profile / dsh.bundle 声明；插入内容始终可被上层 patch。
Service / ctx key ：服务占据稳定 ctx.<key>（ctx.tools、ctx.llm...），按 key 查找而非 import 具体实现。
Event 三域 ：① 会话事件（持久、入日志、跨 reload 存活）② Agent 事件（agent/*，携带活跃 Agent、实时拦截）③ 能力事件（fs/* tools/* telemetry/*，向 seam 附加策略/适配器）。
分发模式 ：emit（观察）/ waterfall（需 next() 委托、可短路）/ parallel（并行）/ serial（按序、有返回值）。
Seam（能力接缝）：可替换能力三层 = Service Definition（接口）+ Service Provider（实现）+ Consumer（使用方，常为面向模型的工具）；换一个 Provider 即改变整个产品行为。
不变式 ：Model-visible means logged ------模型所见必须能从会话日志重建，新增模型可见输入必须新增一个会话事件（扩展 SessionEventMap 并从日志渲染）。

1. 文档系列总览

1.1 受众与前置

受众：智能体 / AI 应用开发者、平台工程师、对 Cordis 插件化架构与可替换 agent 运行时感兴趣者。
前置：TypeScript 基础 + 对 LLM agent loop 的基本认知；Cordis 教程无需 API key 即可动手。

1.2 五大模块（共 37 篇）

模块	主题	目标
一、架构篇	心智模型 + Cordis + 核心子系统	读懂官方架构文档与 `--dump-config`
二、源码篇	逐包走读	建立「改哪、怎么改」的源码地图
三、生产实践篇	部署 / 配置 / 安全 / 观测 / 编排	能独立落地一套可用实例
四、插件开发篇	hands-on 教程	能写出工具/钩子/UI/协议/适配器插件
五、进阶生态篇	对比 / ADR / 贡献	理解演进方向与社区参与

2. 模块一 · 架构篇（A1--A8）

A1. 项目总览与心智模型：一切皆插件

目标：建立「运行中的 dsh = 一棵插件树」的心智模型。
引用：README / docs/architecture.md / 架构参考页。
大纲：定位与哲学 → 与 Claude Code / LangGraph 的差异 → 分层组合直觉 → 本文系列导航。

A2. Cordis 内核五概念：Context / Service / Event / Effect / Inject

目标：讲清插件如何向共享 ctx 贡献服务、事件、可逆副作用。
引用：reference/cordis-primer。
大纲：插件即 Service 对象 → ctx 是服务容器 → inject 表达加载顺序 → 类型化事件通信 → effect 可逆注册。

A3. 事件分发四模式与 Waterfall 语义

目标：讲透 emit/waterfall/parallel/serial 及 waterfall 的 next() 包裹与短路。
引用：reference/cordis-primer#分发模式 / #waterfall 语义。
大纲：四种模式对照表 → waterfall 协作式包裹示例 → 单决策事件的短路即设计意图 → @mode 标签与目录交叉校验。

A4. Profile 与 Bundle：分层组合与 patch 覆盖机制

目标：讲清启动期各层叠加顺序与 patch 定位替换。
引用：docs/architecture.md#profiles-and-bundles / packages/boot/app-boot/README.md#profiles。
大纲：Profile 存什么 → Bundle 是什么 → 叠加顺序（bundle→profile.yml→home.yml→--patch）→ --dump-config 看真实树 → 自写 patch 替换任意一行。

A5. 核心子系统全景

目标：把 7 个核心包的 ctx key 与职责一次讲清。
引用：架构文档「核心包」表 + reference/subsystems/*。
大纲：session(ctx.sessions) / system-prompt(ctx.systemPrompt) / tools(ctx.tools) / agent+agent-loop(ctx.agents/ctx.agentLoop) / scope / llm(ctx.llm) 各自职责与协作。

A6. 事件体系与扩展点分类

目标：给读者「改行为先看事件域」的决策框架。
引用：reference/（事件段）/ docs/event-producer-consumer.md。
大纲：三事件域适用场景 → agent/* 事件清单 → 能力事件 seam 映射 → 「新行为归属位置」映射表串讲。

A7. 轮次与步骤生命周期（turn flow 时序）

目标：把 turn/step 状态机讲透（配合时序图）。
引用：架构文档「轮次流程」段 / reference/agent-lifecycle / reference/tool-execution-pipeline。
大纲：turn/start→agent/pre-step→step/*→tool/*→agent/turn-stopping→turn/end 全链路；waterfall vs serial 区别；输入 inbox 唤醒语义。

A8. 会话日志即真相源 + 能力 Seam 模型

目标：讲清两大架构支柱。
引用：架构文档「会话日志」「能力 seam」段 / reference/capability-seams。
大纲：deriveMessages() 投影 → assistant/chunk 保真回放 → 「模型所见即已记录」不变式；Seam 三角色与「换 Provider 即换产品」。

3. 模块二 · 源码篇（S1--S8）

S1. 仓库结构与 48 包地图 + 构建系统

引用：pnpm-workspace.yaml / tsconfig*.json / tsdown.config.ts / packages/ 目录。
大纲：monorepo 布局 → pnpm/tsdown/tsc 协作 → host/client 配置分离 → 按 §0.4 分类地图逐包一句话职责。

S2. dsh-base 启动层源码走读

引用：packages/bundle/base/README.md 及子模块。
大纲：模型适配器、工具、持久化、沙箱与审批策略、设置、凭据、遥测------第一层贡献了什么、如何被上层覆盖。

S3. boot/app-boot：Profile 组装与 loader

引用：packages/boot/app-boot/README.md#profiles / vendor/README.md（Cordis loader）。
大纲：@deepseek-ai/cordis-plugin-include 的 !!js 解析 → 注入激活后插值 config → disabled 基于 loader ctx 插值 → overlay 选插件。

S4. core/session：SessionEvent 日志与内存存储

引用：reference/subsystems/session / packages/core/session。
大纲：SessionEvent 仅追加日志 → deriveMessages() → fork(source, boundary?, childSessionId?) → resume/transcript/telemetry 派生。

S5. core/tools：作用域注册表与带把关的执行流水线

引用：reference/subsystems/tools / reference/cookbook/adding-a-tool。
大纲：ctx.tools.register()（defineTool vs 原始 JSON Schema）→ restrict() / guard() → tools/pre-execute → execute → post-execute → result 四事件链与拦截点选择规则。

S6. core/agent + agent-loop：接口 / 注册表 / 默认驱动器 / 取消恢复

引用：reference/subsystems/core / packages/core/agent packages/core/agent-loop。
大纲：Agent 接口与 AgentHandle → AgentRegistry（initiator 作用域）→ AgentLoop 默认驱动 → cancel()（4 种 cause）→ agent/request-error 重试恢复。

S7. llm/llm：消息/流式词汇表与适配器 seam

引用：reference/subsystems/llm-streaming / reference/cookbook/adding-an-llm-adapter。
大纲：消息与流式 chunk 词汇表 → registerAdapter 注册 LlmAdapter 子类 → dsh-llm-deepseek / dsh-llm-pi-ai 实现剖析。

S8. 安全与集成源码走读

引用：packages/sandbox guard hooks mcp subagent skill。
大纲：landlock/sandbox-exec 沙箱后端 → 权限门禁 tools/pre-execute → hooks 桥接（claude-code/codex）→ MCP 每服务器一插件 → subagent provider 注册表 → skill section+工具。

4. 模块三 · 生产实践篇（P1--P8）

P1. 部署形态对比与选型 ：web / headless / cli / acp / sdk 的适用场景与启动命令。

P2. 配置与 Patch 实战 ：--dump-config 读树 → 写 cordis.patch.yml 替换行 → 多环境配置管理。

P3. 模型适配与多供应商接入 ：自制 LlmAdapter、DeepSeek/Pi.ai/自建网关、twin LLM adapters（ADR 0010）。

P4. 安全与合规 ：沙箱边界、权限门禁、审批策略 ctx.approval、ask 决策、Prompt 注入防护。

P5. 可观测性 ：遥测、session/event→JSONL、sessions.create(id,{seed}) 回放、fork/resume。

P6. 性能与稳定性 ：上下文压缩（compaction seam + dsh-compaction-basic）、重试策略、取消与错误恢复。

P7. 多会话与子代理编排 ：subagent provider（spawn-in-process/-fork/-acp/-codex/-claude-code/-dsh-sdk）、ctx.goals、workflowEngine。

P8. 企业落地 ：私有化部署、混合云沙箱、CI/CD、灰度与 dsh-plugin 社区 topic 分发。

5. 模块四 · 插件开发篇（D1--D8，hands-on）

D1. 第一个插件 hello-plugin ：建 scratch-plugin → 导出 apply(ctx) → --patch ./scratch-plugin/cordis.yml 加载进 Web UI。

D2. 插件三形态 ：函数 / 对象 / 类（Service 子类，向其他插件提供服务时用）。

D3. 声明依赖与生命周期 ：inject 等待就绪 → ctx.effect() 自动清理（无需手动 removeListener/clearInterval）。

D4. 工具插件 defineTool DSL 全解 ：parameters 推导校验 args / output.schema+render / run_in_background / 嵌套 schema / Code Mode / UI 卡片。

D5. 钩子插件 ：权限门禁 = tools/pre-execute waterfall 返回类型化决策；guard()（单调拒绝）/ tools/execute（包裹超时重试）/ tools/post-execute（结果变换）/ tools/result（观察）。

D6. UI 插件 ：监听 session/event（assistant/chunk 文本流）→ agent.followup() / steer() 驱动输入 → 注册 ConversationNodeDefinition + keyed renderer。

D7. 外部协议驱动 ：ACP / JSON-RPC 接入 ctx.agents（followup()/cancel()、AgentHandle.dispose() 达 quiescence）；packages/acp/acp 完整示例。

D8. LLM 适配器 + Conversation Node + Seam 三层包 ：registerAdapter；Chat 节点注册；将能力拆为 Definition/Provider/Consumer 三包（参考 develop/practice/）。

6. 模块五 · 进阶生态篇（E1--E5）

E1. 热重载与 HMR 实践 ：每个注册都是 ctx.effect → 随仓库 HMR 直接生效。

E2. 与其他智能体框架对比 ：Claude Code / Codex / LangGraph / AutoGPT------插件化、seam 可替换、会话日志不变式维度的差异。

E3. 扩展实操手册精读 ：reference/cookbook/extension-cookbook 的「功能→机制映射」全表串讲（钩子、UI、协议、压缩、Plan mode、subagent、MCP、skill、定时任务...）。

E4. ADR 解读与架构演进 ：ADR 0009（capability seams）、0010（twin LLM adapters）等决策背景。

E5. 社区贡献与路线图 ：CONTRIBUTING.md、.agents/notes/*.md（已实现架构/特性笔记）、发布节奏与 developer preview 约定。

7. 参考资料索引

官方文档站点（https://deepseek-harness.github.io/deepseek-harness/）

架构参考：/reference/、/reference/cordis-primer、/reference/agent-lifecycle、/reference/tool-execution-pipeline、/reference/capability-seams、/reference/config-catalog
子系统：/reference/subsystems/session、/subsystems/system-prompt、/subsystems/tools、/subsystems/core、/subsystems/scope、/subsystems/llm-streaming、/subsystems/subagent
开发教程：/develop/basic/（第一个插件、工具、配置）、/develop/cordis-tutorial/、/develop/framework/service、/develop/practice/
实操手册：/reference/cookbook/extension-cookbook、/cookbook/adding-a-package、/cookbook/adding-a-tool、/cookbook/adding-an-llm-adapter、/cookbook/adding-a-conversation-node

源码关键路径

总架构：docs/architecture.md（及 architecture.zh.md）、docs/event-producer-consumer.md
启动层：packages/bundle/base/README.md、packages/bundle/web-app/README.md、packages/bundle/headless/README.md
组装：packages/boot/app-boot/README.md#profiles、vendor/README.md
核心：packages/core/{session,system-prompt,tools,agent,agent-loop,scope}、packages/llm/llm
示例/协议：packages/acp/acp/README.md、packages/examples/{acp-demo,jsonrpc-demo,agent-spine-demo}
决策与笔记：.agents/notes/implemented/architecture/*、/.agents/notes/implemented/feature/*、docs/（ADR）

命令速查

sh 复制代码

npx @deepseek-ai/dsh web                 # 预构建启动 Web UI
pnpm dsh web --patch ./scratch/cordis.yml  # 加载本地覆盖层
dsh --profile web --dump-config           # 打印实际启动的配置树
pnpm install && pnpm run build && pnpm dsh web   # 源码运行

DeepSeek Harness 技术文档系列