ht426/deepseek-harness-tutorial

DeepSeek Harness 教程

一份从源码出发、按模块组织的中文教程
带你从「dsh 是什么」一路走到「如何在 dsh 上写出自己的插件」

🚀 零基础导读 ·
📚 完整目录 ·
📖 术语速查 ·
🔗 官方仓库

这是什么

本仓库是一份系统性的 DeepSeek Harness（dsh）教程，用中文编写、按「教学顺序」组织。每一章都对应官方仓库里的一组真实包（packages///），并标注关键源码与类型定义的位置，方便你随时回到源码核对。

教程用中文编写；代码标识符、类型名、事件名、ctx 键等保持英文原文，首次出现时给出中文说明。

第一次接触？从这里开始

如果你对「agent / 智能体 / 大模型」这些词还不熟，先读 零基础导读 —— 它用大白话讲清「agent 是什么、大脑和手怎么配合、dsh 为什么一切皆插件」，几分钟读完，后面 14 章就都能跟上了。

这份教程适合谁

- 想读懂 dsh 源码、理清其模块边界的开发者。
- 想给 dsh 加工具、加能力、加模型适配器、加 Web UI 节点的插件作者。
- 想用 dsh 组装自己的 agent 应用（CLI / Web / ACP / JSON-RPC）的集成者。

前置知识

- 会写现代 JavaScript / TypeScript（本教程不重讲语法）。
- 装了 Node.js（要求 ^22.19 || >=24）与 pnpm。
- 对「大语言模型调用 + 工具调用」的基本流程有概念即可（没有也不怕，零基础导读会补齐）。

章节地图

按顺序读即可——每一章都建立在前一章的概念之上。第 3 章是 Cordis 框架速览，是理解后续所有章节的地基。

| 章节 | 内容 | 对应的仓库模块 |
|---|---|---|
| 零基础导读 | 用大白话讲清 agent、大脑/手、插件、接缝——第一次接触必读 | — |
| 第 1 章：总体架构 | 一切皆插件、profile/bundle、能力接缝、轮次流转、扩展点总览 | vendor/、packages/bundle/、packages/boot/ |
| 第 2 章：环境与运行 | 安装、从源码跑、profile、--dump-config、目录结构 | 仓库根、apps/cli |
| 第 3 章：Cordis 框架基础 | 插件、Context、服务、事件、effect/on、配置与组合 | vendor/cordis |
| 第 4 章：核心与 Agent 循环 | session / system-prompt / tools / agent / agent-loop，turn/step 流程 | packages/core/ |
| 第 5 章：LLM 能力 | Message/StreamChunk、LlmAdapter 接缝、DeepSeek 提供方、token-meter | packages/llm/ |
| 第 6 章：执行类能力 | shell、subprocess、terminal、code-runtime、sandbox、e2b | packages/shell/ 等 |
| 第 7 章：工具与数据类能力 | fs、lsp、skill、web、mcp、attachment、spill | packages/fs/ 等 |
| 第 8 章：编排 | subagent、workflow、todo、plan、goal、schedule、jobs、compaction、guard | packages/subagent/ 等 |
| 第 9 章：上下文与人类协作 | context、commands、approval、permission-presets、ask-user、feedback | packages/context/、packages/interaction/ |
| 第 10 章：持久化与数据平面 | session 持久化、投影、查询、storage、workspace、settings、credentials | packages/session/ 等 |
| 第 11 章：启动、组合与预设 | app-boot、bundle、preset、extensions（自修改） | packages/boot/、packages/bundle/ 等 |
| 第 12 章：接入与对外接口 | api/typert 网关、sdk、acp、hooks、Web GUI（host/client） | packages/api/、packages/sdk/ 等 |
| 第 13 章：如何扩展 dsh | 加工具、加提供方、加包、加 LLM 适配器、加 Chat 节点 | docs/cookbook/ |
| 第 14 章：开发、测试与文档 | 开发工作流、测试策略、文档规范、常用命令 | scripts/、docs/ |
| 附录：术语速查 | turn/step、seam、scope、goal 等规范术语 | docs/glossary.md |

官方文档索引

本教程是「教学顺序」的路线图；官方文档是「查找」用的权威参考。需要精确类型、事件签名或配置字段时，优先查官方 deepseek-ai/deepseek-harness 仓库。完整索引见 index.md。

⚠️ 注意：dsh 目前处于开发者预览阶段，接口会以破坏兼容的方式快速演进。本教程以官方仓库当前源码为准。

许可证

MIT