1
DeepSeek Harness 架构深读系列
本系列面向想读懂 dsh 源码、写插件做二次开发、或在 Claude Code / Cursor / Codex 之外评估一个"全插件化"开源 harness 的工程师与架构师。它不重复讲"AI 会写代码"，而是回答一个具体问题： 一个把…
专栏
DeepSeek Harness 架构深读
从模型之外的一切入手，系统拆解 DeepSeek Harness 的全插件化 Agent 运行时与工程实践。
AI 编程更新于
42 篇文章0 人订阅 创建
专栏简介
面向希望理解 AI Coding Agent 底层架构的开发者。本专栏基于 mindcarver/91ai 的 DeepSeek Harness 系列，覆盖 Cordis 可组合性、插件树与 Profile、运行时核心、能力接缝、执行子系统、源码导读、扩展开发与横向评测。建议按“是什么与首次运行”→“Cordis 与插件组合”→“运行时和能力接缝”→“源码与工程化”顺序阅读。
文章目录
2
架构横评与可组合性的工程哲学：dsh vs Claude Code vs Cursor vs Codex
不比功能清单，不比模型能力，不比 benchmark 分数。这三样随版本剧烈变化，依赖太多外部因素，写下来三个月就过期。
3
Cordis 生态溯源：从 Koishi 到 DeepSeek Harness 的插件框架谱系
Cordis 的源头是 Koishi，一个 TypeScript 写的跨平台聊天机器人框架，从 2020 年左右开始开发。聊天机器人是插件框架最残酷的练兵场之一：平台多（每个聊天平台一个适配器）、用户杂（从爱好者到企业部署）、插件生态大，…
4
i18n 翻译配对与质量门禁：dsh 双语文档怎么不腐烂
dsh 的文档被两类读者消费：公司内外的人，和干活中的 agent。范围内的每一份文档都维护英文和简体中文两个版本，两种语言权威相等，先写哪边都合法，一份中文先写的 Agent Note 和一份英文先写的完全平权。绑定它们的只有一条纪律：…
5
文档即代码：dsh 用脚本生成图、目录和校验门禁
软件项目最常见的文档问题不是没有文档，是漂移。文档写的时候是对的，代码改了之后没人跟着改，文档就慢慢变成一份精心排版的谎言。读者不知道它过期了，照着配置，照着调 API，浪费一个小时才发现字段早改名了。
6
7
8
dsh Web 客户端：Chat Nodes 与多 agent 协议
传统的 Web 架构里，服务器渲染 HTML，浏览器只是显示。dsh 的 Web 客户端不走这条路：Host 和 Client 是两个独立的插件图，各自有完整的 Cordis 生命周期。
9
10
给 dsh 写一个 Conversation Node：Web 自定义渲染
想给对话界面加一张自己的卡片，比如一个代码审查的进度条，最直觉的写法是：开一个事件订阅，把属于这个审查的事件攒进一个自己的 store，store 变了就重渲染。单机演示这样能跑，放进 dsh 的 Web 客户端里它会在三个真实场景下坏掉。
11
排查与调试：dsh 这个全插件化 harness 怎么追问题
单体软件出问题，怀疑对象是那一个进程；微服务出问题，怀疑对象是某台服务。全插件化的 harness 出问题，怀疑对象是"组合"：同样是官方发布的一堆插件，你的 patch 层叠方式、你的 profile、你加载顺序里的某个第三方插件，任何…
12
13
14
配置、凭证与存储：dsh 的有状态底座三件套
dsh 的会话事件日志有自己的独立子系统，不在这篇的范围。这篇讲会话日志之外的三类有状态数据：用户配置（settings）、凭证（credentials）、键值存储（storage）。
15
web-cordis：dsh 里会改自己插件树的 agent
dsh 的一切能力都是 Cordis 插件挂上去的：模型适配器、工具注册表、会话日志、agent loop，全是插件。正常情况下你扩展这个系统的方式是编辑 cordis.yml、重启进程。这是开发时的扩展，动手的是人，时机是停机。
16
17
18
web-schedule：dsh 会话内的定时、提醒与自动化
看到 schedule 和 reminder 这两个词，多数人脑子里浮现的是一个通知系统：定个时间，到点了弹浏览器通知、推系统消息、发封邮件。web schedule 不是这个东西，把它当这个东西用，第一天就会失望。
19
20
21
22
23
dsh 的 Web 搜索抓取与 Skills 技能系统
把 web 和技能放一篇讲，不是因为功能相近（一个联网、一个管指令），而是因为它们面对同一个问题：接多个来源时，怎么不让来源差异泄漏到模型那一层。
24
25
26
27
dsh 命令执行三层：Subprocess / Shell / Terminal
让 agent 跑命令，最朴素的想法就是调操作系统的 exec：一句话跑命令，拿回输出。但这种"一句话"在真实场景里会立刻分成三种截然不同的需求。
28
29
30
给 dsh 写一个 LLM 适配器：接 OpenAI 兼容端点
拿到一个 OpenAI 兼容端点（自建 vLLM、第三方网关、任何实现了 chat completions 的服务），第一反应不该是写代码。dsh 的 llm pi ai 插件本身就是"接任意 OpenAI 兼容端点"的配置通道：pi a…
31
多模态与 Attachment：dsh 怎么让 agent"看图"
多数 agent 的图片处理停在"把图塞进下一个请求"。一次性对话这样够用，但 dsh 的会话是持久日志，要支撑 fork、resume、换 provider、重放。一张图一旦被接受，就不只服务当前这轮，它会作为历史的一部分，跟随这个会话…
32
LLM 适配器与 stream 契约：dsh 把 provider 差异关在适配器一层
agent loop 通过 ctx.llm 与中立 StreamChunk 隔离所有 provider
33
34
35
能力接缝：dsh 换一个 provider 等于换整个产品
很多项目自称"插件化"，但它们的插件只能在外围加点东西：换换主题、加加面板，核心能力换不掉。dsh 的"接缝（capability seam）"走得更远：一个接缝是一个可以被整体替换的能力。
36
37
事件系统：dsh 的四种派发模式与 waterfall 短路
先立一条总则： 一个事件的派发模式，是它公开契约的一部分。 这不是实现细节，是这个事件能被怎么用的规定。
38
会话日志：dsh 为什么坚守"模型可见即可重建"
先把模型立起来。dsh 里一个 Session，本质是一个 只追加的事件日志（append only log）：一个 agent 从生到死的全部交互，都记成一条条有类型的事件（SessionEvent），按顺序追加。这条日志是唯一真相源（…
39
40
41
从一篇论文到一棵插件树：Cordis 怎么撑起 DeepSeek Harness 的"一切皆插件"
写过后端的人都干过一件事：往框架里注册一个东西。往 Express 注册一个中间件、往 Koa 注册一个中间件、往 Webpack 注册一个 loader、往 Vue 注册一个全局组件。注册很容易，一行代码。
42
从 0 跑起来：first run 全流程
满足这三条就能开始。不需要先 clone 仓库、不需要装 pnpm、不需要编译——npx 会拉取已发布的包。