CFzjyAI Engineer▍深耕领域AI Agent 架构设计Harness 插件开发Context Engineering多智能体协同 RAG▍技术底座PythonTypeScript·Cordis 插件MCP Skills·FastAPIDocker▍工程能力专注 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 声明和写代码能力无关——按速查表对号入座即可。验收验收验收验收阶段一跑起来(半天)阶段二看懂插件(1天)阶段三写插件(2~3天)阶段四打包分发(1天)Web UI 打开逐行读懂官方示例自己工具被模型调用干净 profile 可安装二、官方资料地图按需查的四本书官方文档体系分四层查资料时先定位层不要全网乱搜本表路径基于 2026-10 官方文档站资料定位什么时候读Cordis 入门概念速览五个核心概念 分发模式表概念忘了随时回来刷10 分钟Cordis 教程7 章动手实践每章一个可运行示例阶段二三的主线跟着敲开发手册基础第一个插件/Tool/配置/打包与安装harness 侧开发写真实插件时按主题查子系统参考页每个服务的 API 与事件全表cordis-surface 生成区用某个服务前查方法签名与事件模式一句导航口诀概念忘了刷入门动手不会跟教程写真插件查手册调 API 看子系统。四层各管一段重叠的部分比如服务与依赖以子系统页为准——官方原文说过“不要维护第二份静态列表”生成区才是权威。三、20 个核心概念速查表#概念一句话解释详见1插件 Plugin导出 apply(ctx) 的模块函数/对象/类三形态01 篇 2.12上下文 Context服务的容器ctx. 按名查服务01 篇 2.23服务 Service具名能力super(ctx, name) 注册03 篇 2.14依赖注入 inject声明所需服务就绪才启动消失自动卸载03 篇5事件 Events声明合并注册事件名互不知晓的通信04 篇6可逆副作用 effect注册的都能撤销返回 disposer02 篇7Fiber插件实例的运行时句柄与状态机02 篇 2.18PENDING依赖未就绪的合法排队状态装死的答案02 篇9分发模式emit/waterfall/parallel/serial/bail 五种协作拓扑04 篇 3.110waterfall 短路不调 next 直接 return拦截的框架语义04 篇 4.111bundle 组合包附带 patch 层的 npm 包回答贡献什么05 篇12profile$DSH_HOME/profiles/回答由什么组成05 篇13patch 层YAML 行数组后层按行胜出、整行替换05 篇14cordis.yml / cordis.patch.yml配置条目与补丁层文件05 篇15声明合并 declare module编译时给 ctx/Events 加类型不生成代码03/04 篇16服务隔离 isolate同服务名按组解析出独立实例01 篇 4.417HMR 热重载卸载释放 effect 加载遵循依赖02 篇 4.218PENDING 诊断ctx.registry 枚举 fiber 状态02 篇 4.319Schema 配置验证导出 Config 双重身份类型 运行时验证器05 篇 3.320扩展点tools/systemPrompt/agent/llm——宿主自己的事件组04 篇 2.2这张表建议存成自己的笔记骨架每学一个新概念往对应行后面补一句自己的理解——速查表就长成了你的知识库。四、卡住时回哪里问题 → 章节导航你遇到的问题第一反应查专栏回看插件没输出不报错是不是 PENDINGctx.registry 枚举02 篇 4.3apply 里 ctx.xxx undefined忘声明 inject03 篇监听器没反应/被吞事件模式 观察者忘 next04 篇装了插件不生效dsh.bundle 声明 层序05 篇配置被覆盖/丢键整行替换语义05 篇 3.1卸载后资源残留effect 三定律02 篇 3.1热重载行为异常配置条目缺 id02 篇 4.1结语这张地图的价值不在信息量在顺序跑起来 → 看懂 → 写出来 → 发出去四阶段各带验收标准资料四层各管一段20 个概念按编号串成体系。前五篇原理 本篇地图构成了这个专栏的上半场——地基已全。下半场第 07~14 篇是工程实战搭工程、写工具、改官方插件、迁移、发布、看趋势每一篇都建立在这张地图的地基上。收藏本篇卡住就回来。知识要点文字回顾① 四阶段路线半天跑起来、一天看懂、两三天写出来、一天发出去② 资料四层入门刷概念、教程跟敲、手册按题查、子系统查 API③ 20 个概念覆盖原理全貌逐行补理解④ 卡点导航表让报错 → 章节一步直达。下一篇连载预告《从 0 到 1 搭一个 DeepSeek Harness 插件工程:package.json 契约与 cordis.patch.yml 全拆》——开发篇开篇,关注 CSDN 主页 不错过更新。你学到第几篇了卡在哪个概念上?评论区聊聊,我挨个回,高频问题会写进后续篇目。本文资料路径基于 DeepSeek Harness 官方文档(2026-10 版本),文档站结构可能调整,有变动评论区提醒我。参考资料DeepSeek Harness 官方文档站结构、Cordis 教程总览、Cordis 入门、开发手册与子系统参考页。