github.com/deepseek-ai/deepseek-harness
d
DeepSeek 開源工程 · AI Agent Harness

以外掛組合
AI Agent
執行環境

DeepSeek Harness（dsh）是 DeepSeek AI 開發的開源 agent harness。它以 Cordis 組合 plugin tree，讓模型轉接器、工具登錄、session log、agent loop 與介面都能透過設定替換。

163k
GitHub Stars
2
內建 Profile 範本
3080
Web UI 預設連接埠
MIT
開源授權
01
專案定位

可組合的
Agent Harness

DeepSeek Harness 將 agent 執行環境拆成 Cordis 外掛。模型轉接器、工具登錄、session log、agent loop、持久化、sandbox 與介面都是可替換的組件。

執行中的 dsh 是開機時組成的 plugin tree。Profile 定義要堆疊的 bundles；bundle 攜帶 Cordis 設定列與外掛程式碼；cordis.patch.yml 再於上層替換或新增設定列。

內建 web 與 headless profile 範本。前者加入瀏覽器應用，後者提供不啟動伺服器的單次執行器。

dsh 啟動組合順序
Base bundle→ Profile bundles→ Profile patch→ Home patch→ CLI overlay
「Everything is a Plugin.」
— DeepSeek Harness 專案簡介
02
啟動與初始設定

Web UI
首次啟動流程

安裝 Node.js 後，直接以 npm 套件啟動 Web UI。伺服器預設使用 http://127.0.0.1:3080。

npx @deepseek-ai/dsh web

原始碼啟動流程

參與開發時使用官方原始碼流程。專案要求 Node.js 22.19 以上或 24 以上，並將 pnpm 固定為 11.7.0。

git clone https://github.com/deepseek-ai/deepseek-harness.git cd deepseek-harness pnpm install pnpm run build pnpm dsh web
模型與工作區是執行前條件。進入 Settings → Models 儲存 API key，再選擇啟動 dsh 的專案目錄。尚未選定工作區時，session composer 不會開放。
03
外掛化能力地圖

從模型到介面的
可替換組件

官方架構將能力分成 Service Definition、Service Provider 與 Consumer。替換 provider 時，使用同一服務介面的消費者不需要建立專屬分支。

Surface · 01
dsh-web-app
Web UI
在瀏覽器中設定模型、選擇工作區、開啟 session 與送出任務。
Surface · 02
dsh-headless
單次執行器
以不啟動伺服器的 profile 執行一次性 agent 任務。
Core · 03
agent-loop
Agent 執行迴圈
讀取 prompt 區段與工具 schema，管理模型步驟、工具呼叫與終止狀態。
Core · 04
session
持久化對話記錄
保存可重放的 session 日誌，並維持事件順序與查詢投影。
Model · 05
llm adapters
模型轉接層
提供 DeepSeek、型錄 provider 與自訂 OpenAI-compatible endpoint 的設定路徑。
Tool · 06
tools registry
工具登錄與呼叫
外掛登錄具有 schema 的工具；agent loop 在每個步驟讀取當前登錄內容。
I/O · 07
filesystem
檔案系統政策
將工作區讀寫能力與政策分離，便於替換本機或遠端提供者。
I/O · 08
shell
命令列執行能力
以服務介面連接 bash、PowerShell 與執行消費者。
I/O · 09
subprocess
衍生程序生命週期
管理本機程序樹，並與 filesystem provider 共用執行世界。
I/O · 10
terminal
持久化終端 session
為需要持續互動的命令提供 PTY 與 session 管理。
I/O · 11
lsp
語言伺服器能力
將語言伺服器能力納入 agent 的可組合工具層。
Knowledge · 12
skills
Skill 登錄表
提供本機 skill provider、catalog 與載入工具。
Knowledge · 13
web
網頁搜尋與擷取
以 provider 與 tool consumer 分層提供 web 能力。
Context · 14
compaction
上下文壓縮
將壓縮機制與基礎 provider 放在可替換的能力邊界後。
Context · 15
request context
請求上下文
用外掛傳遞任務中的工作區、權限與執行環境資訊。
Agent · 16
subagent
子代理委派
以共通介面切換新的 child agent 或外部產品中的 delegated turn。
Agent · 17
workflow
工作流執行
將工作流能力、worker-thread provider 與工具消費者分開。
Agent · 18
plan
計畫狀態
讓 agent 維持可顯示、可更新的任務計畫。
Agent · 19
todo_write
待辦事項工具
在 session 中維持結構化待辦事項與完成狀態。
Policy · 20
approval
操作核准
依目前 permission policy 要求 Web UI 在受管操作前取得核准。
Policy · 21
sandbox
執行隔離
由 sandbox backend 包裝衍生程序命令，並集中維持限制。
Storage · 22
persistence
持久化服務
保存 session、設定與執行狀態，供其他外掛透過服務介面存取。
SDK · 23
Python SDK
程式化嵌入
以 deepseek-harness-sdk 建立最小 agent 組合，並自訂 workspace 與 session ID。

入口選擇

使用情境 入口 適合動作
本機互動使用 npx @deepseek-ai/dsh web 模型設定、工作區選擇、任務對話
單次自動化 headless profile 不需要 Web 伺服器的任務執行
嵌入 Python 程式 deepseek-harness-sdk 自訂組合、workspace 與 session ID
擴充執行環境 --patch 或 dsh plugin 載入本機外掛、bundle 或新 profile
04
官方架構原則

外掛組合的
操作邊界

以下原則來自官方 README、架構文件、Web UI 指南與外掛教學。先確認組合層次、權限與安裝來源，再將 agent 放入實際工作區。

TIP 01

預設 Web profile

首次使用時啟動 web，完成模型與工作區設定後再進入自訂組合。

來源 · 官方 Web UI 指南
TIP 02

工作區選擇順序

新的 Web UI 不會自動選中工作區。加入啟動 dsh 的專案目錄，再啟動 session composer。

來源 · 官方 Web UI 指南
TIP 03

Profile 執行組合

Profile 記錄 bundles 順序、外部外掛與使用者 patch。使用 dsh --profile <name> 啟動指定組合。

來源 · 官方架構文件
TIP 04

Bundle 設定層

Bundle 的 package.json 以 dsh.bundle 指向 patch 檔。未宣告這個欄位的套件只是依賴，不會自動啟用設定層。

來源 · 官方外掛打包教學
TIP 05

組合設定檢查

執行 dsh --profile web --dump-config 檢查本機實際啟動的 plugin tree。每個列都可以由上層 patch 替換。

來源 · 官方架構文件
TIP 06

可逆註冊效果

透過 ctx 註冊的 event listener、tool 與 timer 會在外掛卸載時清除。新行為應建立於這個生命週期。

來源 · 官方第一個外掛教學
TIP 07

必要服務依賴

外掛使用 inject 宣告 tools、llm 等必要服務。Cordis 會等待依賴可用後才載入外掛。

來源 · 官方第一個外掛教學
TIP 08

Home patch 機器偏好

$DSH_HOME/cordis.patch.yml 會套用到每個 profile。用它保存本機共用的設定，不要直接修改 bundle。

來源 · 官方外掛打包教學
TIP 09

GitHub 外掛版本固定

pnpm 10 以上需要明確允許 git dependency 的 build script。只允許已檢查來源，並以 #<sha> 固定內容。

來源 · 官方外掛打包教學
TIP 10

核准政策與 sandbox 分層

核准決定操作是否需要使用者確認；sandbox 限制執行環境。啟動實際專案前同時檢查兩者。

來源 · 官方架構與 Web UI 指南
05
Web UI 使用實例

專案摘要工作流

以官方指南的專案摘要任務驗證安裝。範例只描述可觀察的介面狀態與執行順序，不預設 agent 的實際回答內容。

~/projects/sample-repo · dsh web
$ npx @deepseek-ai/dsh web [Web UI 啟動；終端顯示連線 URL]
Browser › Settings → Models [輸入 DeepSeek API key 並儲存；無需重啟伺服器]
Browser › Choose workspace → ~/projects/sample-repo [session composer 變為可用]
You › Summarize this repository and identify its main packages.
[agent 讀取工作區檔案並維持計畫] [需核准的操作由 Web UI 依目前 permission policy 詢問] [以 agent 實際輸出與 session log 驗證任務結果]
「There is no privileged core to patch.」
— DeepSeek Harness 架構文件

驗收條件

頁面可儲存模型設定，選定工作區後 session composer 可用。任務送出後，介面顯示 agent 的回應與 session 記錄。

任何需要核准的檔案修改或命令執行都應在介面中出現明確請求。若策略未如預期生效，先檢查當前 profile 與實際組合設定。

06
限制與安全條件

Developer Preview 的
使用邊界

  • 相容性不保證。官方將專案標示為 developer preview，並明確預告會有破壞相容性的變更。固定版本並在更新前驗證 profile 與持久化資料。
  • 權限核准不等於 sandbox。核准政策決定是否詢問使用者；sandbox backend 限制執行環境。針對檔案與衍生程序分別檢查兩層設定。
  • 外掛可在安裝時執行程式碼。允許 GitHub 依賴的 build script 會在 agent sandbox 之外執行。只允許已審查來源，並固定 commit SHA。
  • 工作區是 agent 的檔案作用範圍。選擇目錄前先確認內容，並將敏感檔案移出 agent 可讀取的範圍。
  • 模型憑證需要受控儲存。Web UI 的 Models 頁面會儲存 API key。使用專用金鑰，並依組織政策輪替與撤銷。
  • 原始碼開發有固定環境下限。使用 Node.js 22.19 以上或 24 以上、pnpm 11.7.0 與 Git 2.26 以上。安裝後執行 pnpm run typecheck 作為完成條件。
  • Patch 會替換整個設定列。上層 patch 以 row ID 為目標，並替換整個 config。修改前先以 --dump-config 檢查當前列。
  • 第三方套件有獨立授權條件。專案本體採 MIT 授權；分發或嵌入時同時檢查 THIRD_PARTY_NOTICES.md。
07
進階路徑

外掛作者進階路徑

DeepSeek Harness 的擴充路徑從本機 TypeScript 外掛開始，再進入工具、設定 schema、bundle 與 profile。使用官方教學的 --patch 流程驗證生命週期後，再打包分發。

進階實作地圖

1. 建立第一個外掛。建立匯出 apply 的 TypeScript 模組，以絕對路徑寫入 cordis.yml，再執行 pnpm dsh web --patch ./scratch-plugin/cordis.yml。

2. 註冊自訂工具。宣告 tools 依賴，註冊工具名稱、說明、輸入 schema 與 handler，再於 Web UI 中要求 agent 呼叫它。

3. 加入外掛設定。定義 TypeScript Config 型別與 Cordis Schema，使無效設定在載入階段明確失敗。

4. 打包 bundle。在 npm 套件的 package.json 宣告 dsh.bundle，以 patch 插入或替換外掛列。

5. 安裝到 profile。執行 dsh plugin --profile demo add ./hello-plugin，再以 dsh --profile demo --dump-config 檢查設定層。

延伸閱讀

① Web UI 指南：模型、工作區與第一個任務。
② 架構文件：Cordis、profiles、bundles、turn flow 與 capability seams。
③ 第一個外掛：外掛模組、patch、自動清理與依賴宣告。

「Every part of the product is a plugin.」
— DeepSeek Harness 架構文件