deepseek-harness-tutorial README

The project's README from github.com/ht426/deepseek-harness-tutorial. As one markdown file: README.md.

DeepSeek Harness 教程封面

DeepSeek Harness 教程

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

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


这是什么

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

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

第一次接触?从这里开始

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

这份教程适合谁

前置知识

章节地图

按顺序读即可——每一章都建立在前一章的概念之上。第 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

deepseek-harness-tutorial (ht426/deepseek-harness-tutorial)

Searching Database…

这是什么?一份系统组织的 DeepSeek Harness(dsh)中文教程,依据官方源码编写、按教学顺序编排,从“dsh 是什么”一路讲到编写你自己的 dsh 插件。
这是官方 dsh 文档,还是独立教程?它是一份由第三方独立编写的教程,充当教学路线图;官方 deepseek-ai/deepseek-harness 仓库仍是确切类型和 API 的权威参考。
我该怎么使用这份教程?如果你不熟悉代理(agent)概念,先从零基础导读开始,然后按顺序学完 14 章——每一章对应 dsh 源码中一个具体的包/模块,并在前一章的基础上展开。
开始之前我需要了解什么?你应该已经掌握现代 JavaScript/TypeScript,并安装了 Node.js(^22.19 或 >=24)和 pnpm;对“LLM 调用 + 工具调用”有基本了解会有帮助但并非必需,因为零基础导读会补上这块。
跟着这份教程学,dsh 的 API 稳定吗?不稳定——dsh 仍处于开发者预览阶段,其接口可能很快发生破坏性变更;教程会跟随当前官方源码的实际形态。
这份教程是写给谁的?想理解 dsh 源码和模块边界的开发者、要添加工具/模型适配器/Web UI 节点的插件作者,以及在 dsh 之上组装自己代理应用(CLI / Web / ACP / JSON-RPC)的集成者。
dsh(DeepSeek Harness)的核心是什么?dsh 是一个秉持“一切皆插件”原则构建的代理框架,搭建在 Cordis 插件框架之上,包含核心代理循环、LLM 适配器、执行能力(shell、沙箱)、工具(fs、web、mcp)、编排(子代理、工作流)和一个持久化层。
教程的章节是怎么安排的?一份零基础导读加 14 章正文,涵盖整体架构、环境搭建、Cordis 框架、核心代理循环、LLM 集成、执行/工具能力、编排、上下文与人机协作、持久化、启动/打包、外部接口以及如何扩展 dsh,最后附术语表。
Cordis 是什么?为什么第 3 章如此重要?Cordis 是 dsh 所依赖的底层插件框架;第 3 章讲解它的插件、Context、服务、事件和副作用,README 称其为后续所有章节的基础。
这里没讲到的确切 API 细节去哪里查?直接查阅官方 deepseek-ai/deepseek-harness 仓库,因为这份教程是学习路线图,而不是权威的 API 参考。
Creator
ht426
Size
1.9 MB
Stars
266
Updated
CommitAug 13
Age
2mo
Commits · 90 Days