前言¶

DeepSeek Harness（dsh）是 DeepSeek 開源的 Agent 運行時，官方倉庫第一句就是：everything is a plugin——模型適配器、工具註冊表、會話日誌，連 Agent 循環本身都是插件，由 Cordis 裝配。它目前仍處於開發者預覽階段，官方 README 寫明會有破壞兼容的變更。

官方文檔適合「查」：想知道某個事件名、某個 profile 怎麼啓動，去倉庫和文檔站點檢索即可。但很多人第一次碰到這套架構時，缺的是「學」：Cordis 的五個概念怎麼落到代碼裏？headless 和 web 兩個 profile 差在哪？怎樣不接真實模型也能把 turn / step / 工具循環跑通？

社區維護者 yanhua1010 做了一份中文教程倉庫 dsh-harness-tutorial：VitePress 站點講原理和源碼，8 個 Demo 對着真實 dsh 包動手，最後再親手寫一個教學版 mini-harness（React 前端 + Node.js TypeScript 後端）。本文按社區目錄頁、GitHub 倉庫 README 與教程正文交叉覈對後整理。

這是什麼¶

dsh-harness-tutorial 是一份面向計算機本科畢業生和想讀懂 dsh 源碼的工程師的漸進式中文教程，由 yanhua1010 維護，許可證爲 MIT（LICENSE 文件版權年份爲 2026）。GitHub 倉庫在 2026-08-17 顯示 46 顆星；社區目錄頁收錄時標註爲 39 星。主要語言是 TypeScript。

它解決的不是「給正在跑的 Agent 加一個新工具」，而是把「一切皆插件」拆成能跟着做的課：

• 先建立心智模型：Harness、Cordis、接縫、turn / step
• 再對照真實倉庫逐包看實現
• 然後用 8 個已驗證的 Demo 把機制跑通
• 最後從零實現一個誠實簡化的教學版 Agent

它被收錄在社區站點 DeepSeek Harness 插件庫 的「工具與能力」分類，收錄日期爲 2026-08-15。需要說明：該目錄是獨立社區站點，與 DeepSeek / 幻方沒有官方從屬關係，不是官方應用商店。

還有一點邊界要先寫清。倉庫根目錄的 package.json 是 VitePress 教學站點（private: true，腳本是 docs:dev / docs:build），沒有聲明 dsh.bundle。README 給出的用法是克隆後用 npm 跑站點、Demo 和教學項目，而不是把它當作運行時能力插件掛進現有 profile。目錄頁仍然提供了 dsh plugin add 命令，下文會原樣記錄；真正跟着學，以倉庫 README 爲準。

GitHub 上另有一份 ht426/deepseek-harness-tutorial，也是中文教程，但是另一份資料，不要和本文介紹的 yanhua1010/dsh-harness-tutorial 混用。

課程結構¶

教程站點把內容分成四篇，對應倉庫裏的四個目錄。

原理篇（docs/guide/，8 章）¶

按教程首頁的路線，這一篇要建立的是心智模型，而不是 API 清單：

教程正文引用官方架構文檔的原意：產品的每個部分都是插件，因此每個部分都可以從配置裏替換。功能之間的耦合發生在運行時的註冊，而不是源碼裏的 import。

源碼拆解篇（docs/source/，6 章）¶

這一篇對照真實倉庫逐包拆：倉庫地圖、Cordis 內核、session、agent、llm、tools。教程自己的定位是：講清楚「爲什麼這麼設計」「每一步在解決什麼問題」，而不是羅列 API。需要精確類型或事件簽名時，仍應回到 deepseek-ai/deepseek-harness。

實戰 Demo 篇（demos/，8 個）¶

8 個 Demo 全部基於真實 npm 包，版本鎖定爲：

• DeepSeek Harness：@deepseek-ai/dsh@0.1.0-rc.6（以及同版本的 dsh-llm、dsh-tools）
• Cordis：@deepseek-ai/cordis@4.0.1

demos/README.md 寫明：Demo 4 起使用 Mock 適配器，不髮網絡請求，也不需要 API Key。

教程把 Demo 5 標成分水嶺：第一次讓真實的 dsh agent 循環跑起來，只是模型被換成自己寫的 Mock 插件。Demo 5–8 通過 --patch 覆蓋層，把本地插件掛進 dsh --profile headless，並用各自的 DSH_HOME 隔離會話目錄。

教學版項目（final-project/）¶

讀過之後再寫一遍。docs/project/overview.md 寫明：核心庫約 900 行 TypeScript、零運行時依賴；再配 Express + SSE 的 Node 後端，以及帶聊天和即時事件面板的 React 前端。教程首頁把整份教學實現合計約 1500 行。

它保留骨架：插件三形態、可逆 effect、四種事件分發、LLM 接縫、turn / step、工具四道閘門。砍掉的是生產級複雜度，例如 fiber / HMR、schemastery 配置校驗、JSONL / SQLite 持久化、沙箱與審批面、subagent。教程要求每砍一項都說明「真實 dsh 爲什麼需要它」。

安裝與啓用¶

社區目錄頁給出的安裝命令如下，在 DeepSeek Harness 終端中運行：

dsh plugin add github:yanhua1010/dsh-harness-tutorial

如需可復現安裝，目錄頁建議固定 commit 哈希。當前 main 最新提交爲 2a29d03a83859f79e0c93d66fad2d5b405780b0b（2026-08-13）：

dsh plugin add github:yanhua1010/dsh-harness-tutorial#2a29d03a83859f79e0c93d66fad2d5b405780b0b

目錄頁同時提示：插件以當前 dsh 進程的權限運行，安裝時可能執行代碼；安裝前應檢查源代碼倉庫和許可證。

如前所述，這份倉庫的設計用法是當教程來讀和跑，而不是當能力插件來裝。倉庫 README 的快速開始如下。

先克隆：

git clone https://github.com/yanhua1010/dsh-harness-tutorial.git
cd dsh-harness-tutorial

環境要求來自教程首頁和 README：

• Node.js ≥ 20.19（推薦 22+）
• 包管理器用 npm，教程不要求 pnpm
• DeepSeek API Key 可選：全部 Demo 用 Mock 適配器即可運行，僅「接入真實模型」小節需要

只想先閱讀、不在本地起站點，可以直接打開 GitHub Pages：

https://yanhua1010.github.io/dsh-harness-tutorial/

典型用法¶

下面的命令都來自倉庫 README 和 demos/README.md，可以按原樣復現。

1. 在本地打開教程站點¶

npm install
npm run docs:dev

開發服務器地址是 http://localhost:5173/dsh-harness-tutorial/（倉庫用 GitHub Pages 的 base 路徑，本地也走同一前綴）。建議按「原理篇 → 源碼拆解 → Demo → 教學項目」的順序讀，Demo 頁裏也標明瞭與原理章節的對應關係，例如 Demo 1–3 對應 docs/guide/02-cordis-core.md。

2. 跑通 Demo 1–4（獨立腳本）¶

cd demos
npm install
npm run demo:1
npm run demo:2
npm run demo:3
npm run demo:4

這四個腳本在 demos/package.json 裏分別調用 tsx 執行各 Demo 目錄下的 main.ts。Demo 1–3 只依賴 Cordis；Demo 4 引入 dsh-llm 包，用 Mock 適配器演示 StreamChunk 協議。

3. 用 headless overlay 跑 Demo 5¶

Demo 5–8 不再是獨立 tsx 腳本，而是把本地插件 patch 進真實的 dsh 進程。以 Demo 5 爲例：

cd demos/05-headless-mock
DSH_HOME="$PWD/.dsh-home" npx dsh --profile headless --patch mock.patch.yml "你好，介紹一下你自己"
node read-session.mjs

要點有兩條，都寫在 Demo 準備頁裏：

• DSH_HOME 必須指向該 Demo 自己的 .dsh-home，避免會話和設置串到本機其他 profile
• patch 裏本地插件路徑是 ../../../plugins/xxx.ts，因爲 Loader 的 baseUrl 是 $DSH_HOME/profiles/headless/

Demo 6 驗證工具循環，Demo 7 可用環境變量 DSH_DEMO_DENY_ECHO=1 走拒絕路徑，Demo 8 換成自定義 profile demo8，並用 --dump-config 觀察組合後的配置樹：

cd demos/08-profile
DSH_HOME="$PWD/.dsh-home" npx dsh --profile demo8 "你好，自定義 profile"
DSH_HOME="$PWD/.dsh-home" npx dsh --profile demo8 --dump-config | tail -12

教程說明：headless 輸出乾淨、生命週期一次到位，更適合觀察；學完 Demo 8 後，可以把 --profile headless 換成 --profile web，在瀏覽器裏走同一條 Mock 鏈路。

4. 啓動教學版 mini-harness¶

cd final-project
npm install
npm run demo

npm run demo 是核心庫冒煙測試。要看帶界面的端到端效果，開兩個終端：

npm run dev:server    # 後端 http://127.0.0.1:4317
npm run dev:web       # 前端 http://localhost:5174

項目總覽裏給了一段 npm run demo 的節選：Mock 適配器和 echo 工具註冊後，一次任務會打出 turn/start → step/start → tool/call → tool/result → 再開第二個 step 做後續模型調用 → turn/end。這就是教學版要你親手寫出來的工具循環。

適用場景與注意事項¶

適合誰，教程首頁寫得很具體：

• 寫過 TypeScript / JavaScript，瞭解 HTTP 與 JSON，聽說過 Function Calling，但沒見過 Agent 框架內部結構的計算機本科畢業生
• 想讀懂 DeepSeek Harness 源碼的工程師：官方文檔以查爲主，這份教程以學爲主，兩者配合
• 想自己搭一套 Agent 系統、需要一份約一千多行的誠實簡化實現的人

不適合把它當成「裝上立刻多一個工具」的生產插件。根包是教學站點；要給正在運行的 dsh 加工具，應去寫帶 dsh.bundle 的 bundle，或直接參考官方 插件發佈文檔。

使用前注意這幾件事：

1. 版本鎖定與預覽階段。 教程基於 0.1.0-rc.6 撰寫，Demo 依賴已 pin，照着做可以跑通。DeepSeek Harness 官方仍標註 developer preview，架構思想相對穩定，API 細節以官方文檔最新版爲準。
2. 權限與許可證。 無論是 dsh plugin add 還是 npx dsh，代碼都以當前進程權限運行。安裝或運行前應閱讀倉庫源碼和 MIT 許可證。
3. Windows 環境變量。 Demo 準備頁給出的是 POSIX 寫法；PowerShell 要用 $env:DSH_HOME = "$PWD\.dsh-home"，路徑分隔符按 PowerShell 調整。
4. 常見運行問題。 npx dsh 找不到包時，確認已在 demos/ 下執行過 npm install；headless 是一次性進程，改完插件重新跑命令即可。
5. 社區目錄不是官方商店。 插件庫由社區維護，收錄條目與 GitHub 星標可能不同步。

小結¶

dsh-harness-tutorial 把 DeepSeek Harness 的「一切皆插件」拆成一條能跟着做的中文路徑：8 章原理、6 章源碼對照、8 個鎖定在 0.1.0-rc.6 上的 Demo，再加一個可運行的教學版 mini-harness。官方文檔繼續用來查接口，這份教程用來建立機制和動手經驗。

目錄頁：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-harness-tutorial/

GitHub：https://github.com/yanhua1010/dsh-harness-tutorial

在線閱讀：https://yanhua1010.github.io/dsh-harness-tutorial/