cookiespiggy/deepseek-harness-stair-cookbook

DeepSeek Harness 阶梯式学习手册（Stair Cookbook）

📚 官方项目 deepseek-ai/deepseek-harness 的学习配套：从 Cordis 基础到二次开发，12 步、每步可独立运行。

本仓库不是官方仓库，而是一份社区学习资源，帮助 newcomers 降低上手门槛、把“文档里的概念”变成“脑子里的直觉”。

license steps comments offline

一套编号、可独立运行的目录，带你从 Cordis 基础一路走到 DeepSeek Harness（以下简称 dsh）的二次开发。每个目录都是一个独立的小项目，配套中文注释与运行说明。

本手册是独立于官方仓库的学习资源；官方源码与文档见 deepseek-ai/deepseek-harness。两者可对照阅读，本手册的 dsh 步骤均遵循官方 examples/ 的配置约定。

学习路径总览

| 编号 | 目录 | 阶段 | 主题 | 是否开箱即跑 |
|---|---|---|---|---|
| 01 | 01-cordis-plugins-and-effects | 基础 | Context / 插件 / effect 生命周期 | ✅ 只需 cordis |
| 02 | 02-cordis-services | 基础 | Service 子类、provide/inject、声明合并 | ✅ 只需 cordis |
| 03 | 03-cordis-events-and-waterfall | 基础 | 事件与 waterfall 拦截点 | ✅ 只需 cordis |
| 04 | 04-dsh-anatomy-and-config | 入门 | dsh 是什么、cordis.yml、dump-config | ⚙️ 需构建主工程 |
| 05 | 05-dsh-first-plugin | 入门 | 写一个 dsh 插件并挂到配置 | ⚙️ 需构建主工程 |
| 06 | 06-dsh-first-tool | 入门 | 在 ctx.tools 注册模型工具 | ⚙️ 需构建主工程 |
| 07 | 07-dsh-system-prompt-extension | 入门 | 用 ctx.systemPrompt.section 注入提示段 | ⚙️ 需构建主工程 |
| 08 | 08-dsh-run-with-model | 二次开发 | 跑一个完整 headless turn | 🔑 需 API Key |
| 09 | 09-dsh-custom-llm-adapter | 二次开发 | 实现自定义 LLM 适配器 | ⚙️ 需构建主工程 |
| 10 | 10-dsh-filesystem-provider | 二次开发 | 理解并替换 ctx.fs provider（seam 模式） | ⚙️ 需构建主工程 |
| 11 | 11-dsh-bundle-package | 二次开发 | 把插件打包成可安装的 bundle | ⚙️ 需构建主工程 |
| 12 | 12-dsh-self-modification | 二次开发 | cordis 工具集 / agent 自我修改 | ⚙️ 需构建主工程 |

✅ 开箱即跑：npm install 后 node 即可，无需 dsh、无需联网拉模型。
⚙️ 需构建主工程：依赖 dsh 运行时，按下方「前置准备」构建一次后即可运行。
🔑 需 API Key：除构建主工程外，还需 DEEPSEEK_API_KEY 才能真实调用模型。

前置准备（针对 ⚙️ / 🔑 步骤）

dsh 是一个 pnpm monorepo。先把它构建好，之后所有 dsh 步骤都能复用：

在 dsh 主工程目录里
cd ../deepseek-harness
pnpm install
pnpm run build

之后在本手册里运行 dsh 步骤时，统一从主工程用 CLI 调用：
pnpm dsh --profile headless --patch /cordis.yml ""
或仅查看组合结果（无需 Key）：
pnpm dsh --dump-config --profile headless --patch /cordis.yml

每个 dsh 步骤目录里的 cordis.yml 都是一块独立可拼装的配置叶，与 dsh 官方 examples/ 目录同构——官方示例正是这样被 dsh 加载运行的。

依赖策略说明（为什么要分两类）

- 01–03 用纯 cordis：dsh 站在 Cordis 之上，而 Cordis 是一个独立发布、稳定可用的框架。基础概念（Context、插件、effect、Service、事件、waterfall）在 cordis 包里就能 1:1 学到，且完全离线可跑。先吃透它，再看 dsh 时就不会被海量包淹没。
- 04–12 用 dsh 运行时：这一步起进入 dsh 专属概念（cordis.yml 组合、Profile/Bundle、工具注册、ctx.llm/ctx.fs 等 seam）。这些内容只在 dsh 运行时里存在，因此依赖你机器上那份源码构建出来的 dsh。

学习建议

1. 严格按编号顺序：基础三步走完，再碰 dsh。
2. 每个目录先读 README.md，再读源码，最后运行。
3. 运行后改一改参数，观察输出变化——这是把「文档里的概念」变成「你脑子里的直觉」的关键。
4. dsh 步骤若想看源码对照，主工程 docs/architecture.md 与 packages/README.md 是权威入口。