DeepSeek 官方把 deepseek-harness（下文简称 dsh）开源后，文档工程化程度高得罕见——约 50 个子系统页、7 讲 Cordis 教程、cookbook 实操手册、中英双语。但很多想上手的人卡在同一个地方：文档是「地图」，不是「路线」。

本系列的目标，就是把它重新组织成一条由浅入深、每讲有产出的学习路线，做官方文档的导读与实践补充，而非替代。这篇是总纲，建议收藏当目录，后续 22 讲逐篇发出，照表打卡即可。

难度：全阶 ★☆☆ ~ ★★★ ｜ 路线：使用者 / 配置者 / 开发者 ｜ 投入：半天 ~ 两周

为什么需要这套教程？三个真实门槛：① 文档按子系统组织，得自己拼学习路径；② 强依赖 Cordis 前置知识，官方要求先读 primer 才能改 packages/；③ seam / bundle / profile / patch / SessionEvent / 可逆副作用 等概念集中出现，密度极高。

一、先选你的路线

同一套 dsh，不同人用法完全不同。先对号入座，决定你读到第几讲就够用：

路线画像建议学习范围投入
路线 A · 使用者用 Web UI / SDK 把 agent 当工具干活第 1–3 讲 + 第 10 讲半天
路线 B · 配置者用 profile / patch 定制、接 MCP、调审批第 1–10、18–19 讲2–3 天
路线 C · 开发者写插件、换 LLM 适配器、编排多智能体全部 22 讲1–2 周

二、七阶 22 讲总览（收藏这张表）

第一阶 · 快速上手（让 Agent 干活）

讲主题难度一句话目标
第 1 讲五分钟跑起来★☆☆装好 dsh，完成第一轮"读文件→改文件"真实任务
第 2 讲Web UI 完全指南★☆☆看懂每次"同意/拒绝"背后的含义，不脱离 UI 做多步任务
第 3 讲四种运行形态★☆☆掌握 Headless / TUI / Python SDK / ACP 四种调用方式

第二阶 · 核心概念（理解它为什么这样设计）

讲主题难度一句话目标
第 4 讲Cordis 插件框架极速入门★☆☆建立"一切皆插件"心智模型，看懂 ctx / 事件 / effect
第 5 讲Agent Loop 完整生命周期★☆☆~★★看懂 turn/step 主循环，模型-工具-模型怎么转起来
第 6 讲会话日志与三级事件体系★★☆理解"模型可见即已记录"，导出 JSONL 找 5 类事件
第 7 讲能力 Seam 一次替换全局生效★★☆掌握最核心架构抽象，为换引擎铺路

第三阶 · 配置与组装（不写代码的深度定制）

讲主题难度一句话目标
第 8 讲Profile + Bundle 组装模型★★☆看懂"运行中的 dsh 是怎么被拼出来的"
第 9 讲配置补丁实战★★☆用一行 YAML 给产品"换脑"（换模型/禁工具/改提示词）
第 10 讲权限预设与审批策略★☆☆为不同场景配合理的安全策略

第四阶 · 工具开发（给模型长出新手脚）

讲主题难度一句话目标
第 11 讲第一个自定义工具★★☆从零写个模型可调用工具并挂载（可逆副作用）
第 12 讲工具注册表与执行流水线★★☆理解工具从"被点名"到"结果返回"的完整链路
第 13 讲MCP 接入★★☆用 MCP 协议复用生态里现成工具服务器
第 14 讲实战领域工具包★★☆综合前三讲，做一个可复用领域工具包

第五阶 · 多智能体编排（agent 编排 agent）

讲主题难度一句话目标
第 15 讲Subagent 可续跑子代理★★☆主 agent 派子代理并行调研并汇总
第 16 讲Workflow 脚本化编排★★☆用 workflow 描述确定性多阶段流程
第 17 讲Goal 与 Jobs 跨轮次任务★★☆让 agent 记住目标、暂停恢复、定时执行

第六阶 · 安全与沙箱（把危险关进笼子）

讲主题难度一句话目标
第 18 讲Landlock 沙箱与进程隔离★★☆配置"只许写 /tmp"最小权限会话并验证越权被拒
第 19 讲凭据管理与 fail-closed★★☆掌握密钥安全与默认拒绝哲学，配生产自查表

第七阶 · 深度定制（成为框架级玩家）

讲主题难度一句话目标
第 20 讲开发第一个 Cordis 插件★★★从用户跨入框架开发者，发布最小插件包
第 21 讲替换引擎 LLM 适配器 + FS Provider★★★换两个核心 seam，体会"换脑不换壳"
第 22 讲自指涉开发 用 dsh 开发 dsh★★★运行时动态定义插件并即刻被模型使用
⏱ 时间紧？走「最小可行 10 讲」：1 → 3 → 4 → 5 → 8 → 9 → 11 → 13 → 15 → 18。跑起来 → 懂循环 → 会配置 → 能加工具 → 会编排 → 懂安全，刚好闭环。

三、读这套教程的姿势

  • 每讲固定结构：目标 → 前置检查 → 正文（步骤化、代码可复制）→ 动手练习 → 常见坑 → 官方文档对应章节。
  • 配套物料：每讲一个可运行示例目录、版本锚定（标验证过的 dsh 版本）、三张速查表（命令 / 配置项 / 工具目录）、读者勘误反馈。
  • 衔接关系：本系列与《DeepSeek Harness 开源项目深度介绍》互链；每讲发在"技术杂谈"，系列完结后汇总为合集导航。
  • 版本策略：项目处于 developer preview，破坏性变更频繁，每讲标注验证版本；重大变更会出"迁移备注"短文。

四、动手前的准备

前置项要求
必备命令行操作、基本 Git、JSON / YAML 语法
路线 B 起TypeScript 基本语法（async/await、泛型基础）
路线 C 起Node.js ≥ 22.19、pnpm、monorepo 概念；简单 npm 包开发经验
⚠️ 预览阶段提示：部分能力依赖 Linux（Landlock 沙箱），macOS / Windows 有替代路径；E2B 远程沙箱等为 POC，标注"实验性"不作为主线必需；模型调用产生费用，入门篇尽量用低成本示例。

本文基于 deepseek-ai/deepseek-harness 官方文档与开源介绍整理，项目处于 developer preview，命令以官方 README 为准。

开源仓库：github.com/deepseek-ai/deepseek-harness

咨询其他技术话题，请加微信：A0qingfengyuan_01

个人观点，仅供参考，如有不对之处，请多包涵，欢迎指出。本文由 AI 协助完成！