DeepSeek Harness 学习路线图:0 基础到发布第一个插件,附 20 个核心概念速查表

CFzjy AI Engineer	▍深耕领域  AI Agent 架构设计 Harness 插件开发 Context Engineering 多智能体协同 & RAG   ▍技术底座  Python TypeScript · Cordis 插件 MCP & Skills · FastAPI Docker   ▍工程能力  专注 Agent 运行时与 Harness 插件开发、长上下文与流式交互优化、LLM 全链路工程化落地
「 让 AI 交互更智能，让技术落地更高效 」   ｜   欢迎技术探讨 / 项目合作，关注解锁大模型与智能交互的无限可能！

DeepSeek Harness 学习路线图：0 基础到发布第一个插件，附 20 个核心概念速查表

📚 《DeepSeek Harness 插件架构》连载专栏 · 第 06 篇

专栏前五篇把原理的地基打完了（架构全景、生命周期、依赖注入、事件系统、装配机制），这一篇把地图画出来：如果你从 0 开始学 DSH，按什么顺序、用什么资料、卡在哪一步该回看本专栏的哪一篇——一条完整的路线，外加一张 20 个核心概念的速查表。官方 Cordis 教程开篇的定位很适合当本篇的注脚：“本教程面向 agent 开发者。你不需要深入掌握 TypeScript……每一章都会给出确切命令和预期输出。” ——DSH 的学习门槛比想象的低，缺的从来不是能力，是一张不绕路的地图。

痛点一：文档很多，顺序难排。 官方有 Cordis 入门、Cordis 教程七章、开发手册、子系统参考——从哪本开始？先读哪章？没人告诉你。

痛点二：概念很密，记忆靠背。 bundle、profile、patch、fiber、effect、inject……每个词都见过，放一起就串不起来。

痛点三：学到一半找不到"我在哪"。 卡在某个报错上，不知道该查文档、查教程还是查源码。

本文是专栏的"中场导航篇"：路线图解决"怎么学"，概念百科解决"记什么"，导航表解决"卡住了回哪看"。想回看前五篇或追后续开发实战（下一篇：从 0 到 1 搭插件工程），可以先关注我的 CSDN 主页。

文章目录

• • DeepSeek Harness 学习路线图：0 基础到发布第一个插件，附 20 个核心概念速查表
  • • 一、学习路线图：四个阶段，各有验收标准
    • • 阶段一：跑起来（半天）
      • 阶段二：看懂一个插件（1 天）
      • 阶段三：写一个自己的插件（2~3 天）
      • 阶段四：打包与分发（1 天）
    • 二、官方资料地图：按需查的四本"书"
    • 三、20 个核心概念速查表
    • 四、卡住时回哪里：问题 → 章节导航
    • 结语

一、学习路线图：四个阶段，各有验收标准

阶段一：跑起来（半天）

目标：DSH 在你机器上启动，看到 Web UI。动作：按官方 README 的"从源码运行"路径 clone 仓库、pnpm install、pnpm dsh web。验收标准：http://127.0.0.1:3080 打开界面。心态提醒：这个阶段不需要懂任何原理——先让东西动起来，后面每个概念都有实物可对照。卡住就查官方开发指南的前置条件（Node 版本、pnpm 版本）。

阶段二：看懂一个插件（1 天）

目标：能读懂一个完整插件的每一行。动作：跟着官方 Cordis 教程第一、二章跑 hello-plugin 和 lifecycle 示例（本专栏第 01/02 篇是这两章的深度注解版）。验收标准：能回答"apply 是什么时候被调的、ctx.effect 返回的函数什么时候执行"。关键心态：官方教程的 TypeScript 就三类语法（类型注解、import type、声明合并），教程自带说明——别被 TS 吓退，DSH 的 TS 用量极低。

阶段三：写一个自己的插件（2~3 天）

目标：从 0 写一个"注册工具"的插件并跑通。动作：官方教程第三到七章（服务、事件、配置、组合、进入 harness）+ 开发手册的"开发一个 Tool"（本专栏第 03/04/08 篇对应）。验收标准：你的工具出现在模型可用工具列表里，且能被调用。卡点地图：依赖没就绪查第 03 篇（PENDING）；监听器没反应查第 04 篇（事件模式）；配置不生效查第 05 篇（层序与整行替换）。

阶段四：打包与分发（1 天）

目标：插件能装进另一个 profile 并给别人用。动作：官方《打包与安装插件》+ 本专栏第 05 篇；进阶走第 13 篇的 npm/市场发布全链路。验收标准：dsh plugin add ./your-plugin.tgz 后插件在干净 profile 里正常加载。心态提醒：这个阶段的坑全是"工程坑"（整行替换、prepare 脚本、engines 声明），和写代码能力无关——按速查表对号入座即可。

#mermaid-svg-HfYfFGiWPZoT6Pln{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-HfYfFGiWPZoT6Pln .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-HfYfFGiWPZoT6Pln .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-HfYfFGiWPZoT6Pln .error-icon{fill:#552222;}#mermaid-svg-HfYfFGiWPZoT6Pln .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-HfYfFGiWPZoT6Pln .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-HfYfFGiWPZoT6Pln .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-HfYfFGiWPZoT6Pln .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-HfYfFGiWPZoT6Pln .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-HfYfFGiWPZoT6Pln .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-HfYfFGiWPZoT6Pln .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-HfYfFGiWPZoT6Pln .marker{fill:#333333;stroke:#333333;}#mermaid-svg-HfYfFGiWPZoT6Pln .marker.cross{stroke:#333333;}#mermaid-svg-HfYfFGiWPZoT6Pln svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-HfYfFGiWPZoT6Pln p{margin:0;}#mermaid-svg-HfYfFGiWPZoT6Pln .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-HfYfFGiWPZoT6Pln .cluster-label text{fill:#333;}#mermaid-svg-HfYfFGiWPZoT6Pln .cluster-label span{color:#333;}#mermaid-svg-HfYfFGiWPZoT6Pln .cluster-label span p{background-color:transparent;}#mermaid-svg-HfYfFGiWPZoT6Pln .label text,#mermaid-svg-HfYfFGiWPZoT6Pln span{fill:#333;color:#333;}#mermaid-svg-HfYfFGiWPZoT6Pln .node rect,#mermaid-svg-HfYfFGiWPZoT6Pln .node circle,#mermaid-svg-HfYfFGiWPZoT6Pln .node ellipse,#mermaid-svg-HfYfFGiWPZoT6Pln .node polygon,#mermaid-svg-HfYfFGiWPZoT6Pln .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-HfYfFGiWPZoT6Pln .rough-node .label text,#mermaid-svg-HfYfFGiWPZoT6Pln .node .label text,#mermaid-svg-HfYfFGiWPZoT6Pln .image-shape .label,#mermaid-svg-HfYfFGiWPZoT6Pln .icon-shape .label{text-anchor:middle;}#mermaid-svg-HfYfFGiWPZoT6Pln .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-HfYfFGiWPZoT6Pln .rough-node .label,#mermaid-svg-HfYfFGiWPZoT6Pln .node .label,#mermaid-svg-HfYfFGiWPZoT6Pln .image-shape .label,#mermaid-svg-HfYfFGiWPZoT6Pln .icon-shape .label{text-align:center;}#mermaid-svg-HfYfFGiWPZoT6Pln .node.clickable{cursor:pointer;}#mermaid-svg-HfYfFGiWPZoT6Pln .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-HfYfFGiWPZoT6Pln .arrowheadPath{fill:#333333;}#mermaid-svg-HfYfFGiWPZoT6Pln .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-HfYfFGiWPZoT6Pln .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-HfYfFGiWPZoT6Pln .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-HfYfFGiWPZoT6Pln .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-HfYfFGiWPZoT6Pln .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-HfYfFGiWPZoT6Pln .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-HfYfFGiWPZoT6Pln .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-HfYfFGiWPZoT6Pln .cluster text{fill:#333;}#mermaid-svg-HfYfFGiWPZoT6Pln .cluster span{color:#333;}#mermaid-svg-HfYfFGiWPZoT6Pln div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-HfYfFGiWPZoT6Pln .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-HfYfFGiWPZoT6Pln rect.text{fill:none;stroke-width:0;}#mermaid-svg-HfYfFGiWPZoT6Pln .icon-shape,#mermaid-svg-HfYfFGiWPZoT6Pln .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-HfYfFGiWPZoT6Pln .icon-shape p,#mermaid-svg-HfYfFGiWPZoT6Pln .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-HfYfFGiWPZoT6Pln .icon-shape .label rect,#mermaid-svg-HfYfFGiWPZoT6Pln .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-HfYfFGiWPZoT6Pln .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-HfYfFGiWPZoT6Pln .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-HfYfFGiWPZoT6Pln :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

验收

验收

验收

验收

阶段一跑起来(半天)

阶段二看懂插件(1天)

阶段三写插件(2~3天)

阶段四打包分发(1天)

Web UI 打开

逐行读懂官方示例

自己工具被模型调用

干净 profile 可安装

二、官方资料地图：按需查的四本"书"

官方文档体系分四层，查资料时先定位层，不要全网乱搜（本表路径基于 2026-10 官方文档站）：

一句导航口诀：概念忘了刷入门，动手不会跟教程，写真插件查手册，调 API 看子系统。四层各管一段，重叠的部分（比如服务与依赖）以子系统页为准——官方原文说过，“不要维护第二份静态列表”，生成区才是权威。

三、20 个核心概念速查表

这张表建议存成自己的笔记骨架：每学一个新概念，往对应行后面补一句自己的理解——速查表就长成了你的知识库。

四、卡住时回哪里：问题 → 章节导航

结语

这张地图的价值不在信息量，在顺序：跑起来 → 看懂 → 写出来 → 发出去，四阶段各带验收标准；资料四层各管一段；20 个概念按编号串成体系。前五篇原理 + 本篇地图，构成了这个专栏的"上半场"——地基已全。下半场（第 07~14 篇）是工程实战：搭工程、写工具、改官方插件、迁移、发布、看趋势，每一篇都建立在这张地图的地基上。收藏本篇，卡住就回来。

知识要点文字回顾：① 四阶段路线：半天跑起来、一天看懂、两三天写出来、一天发出去；② 资料四层：入门刷概念、教程跟敲、手册按题查、子系统查 API；③ 20 个概念覆盖原理全貌，逐行补理解；④ 卡点导航表让"报错 → 章节"一步直达。

下一篇连载预告：《从 0 到 1 搭一个 DeepSeek Harness 插件工程:package.json 契约与 cordis.patch.yml 全拆》——开发篇开篇,关注 CSDN 主页 不错过更新。

你学到第几篇了？卡在哪个概念上?评论区聊聊,我挨个回,高频问题会写进后续篇目。 本文资料路径基于 DeepSeek Harness 官方文档(2026-10 版本),文档站结构可能调整,有变动评论区提醒我。

参考资料：DeepSeek Harness 官方文档站结构、Cordis 教程总览、Cordis 入门、开发手册与子系统参考页。