前言

为什么要写这本书

DeepSeek Harness（dsh）是 DeepSeek AI 开源的 Agent 运行时（agent harness）。它与大多数"以 LLM 调用为核心的框架"不同：整个产品由插件构成，没有任何特权核心。模型适配器、工具注册表、会话日志、Agent 循环、沙箱、Web 界面……每一个能力都是一枚 Cordis 插件，都能在配置层被替换、被拦截、被扩展。

这种"一切皆插件"的架构让 dsh 拥有极强的可组合性，但也让初次接触它的人感到困惑：入口在哪里？插件如何装载？服务如何解析？事件如何在三层事件域中流转？

本书试图回答这些问题。它以源码为唯一依据，沿着 CLI 入口 → 启动链路 → Cordis 框架 → 核心子系统 → Web 客户端 → 插件开发 的主线，逐层拆解 dsh 的实现，并在最后一部分系统总结插件开发技巧。

本书面向的读者

• 想理解 Agent 运行时架构设计的工程师；
• 计划为 dsh 编写插件、或在其上构建产品的开发者；
• 对 Cordis 插件框架感兴趣、希望看到真实工业级用法的读者。

阅读本书需要具备 JavaScript/TypeScript 基础，并了解基本的 Node.js 概念（ESM、事件循环等）。书中所有关键结论都标注了源码位置（包路径/文件:行号），读者可以随时回到仓库中核实。

关于源码版本

本书写作时对应 deepseek-ai/deepseek-harness 仓库 0.1.0-rc.x 版本。该项目处于 developer preview 阶段，官方明确声明"THERE WILL BE COMPATIBILITY-BREAKING CHANGES"（存在破坏性变更），因此书中细节可能随版本演进而变化。阅读时请以最新源码为准，本书提供的是理解源码的"地图"与"方法论"，而非一份永不失效的 API 手册。

如何阅读本书

• 第一部分给出全景视角，适合所有读者；
• 第二部分深入 Cordis 框架，是理解后续所有章节的基石，建议精读；
• 第三、四部分按子系统展开，可挑感兴趣的章节跳读；
• 第五部分是插件开发技巧，动手写插件前建议通读。

书中大量引用了官方文档（docs/ 目录下的 architecture、subsystems、cookbook 等），它们是官方维护的一手资料，与本书互为补充。

版本提示：本书引用的文件路径与行号基于写作时的仓库快照（commit 47f9438，0.1.0-rc.5/rc.6）。

关于本书仓库

本书的 Markdown 源文件托管在 GitHub 仓库 anghunk/deepSeek-harness-docs。发现错误、有改进建议或希望参与修订，欢迎在该仓库提交 issue 或 PR；每一页底部也提供"在 GitHub 上编辑此页"链接，可直接跳转到对应源文件。