使用手冊

DeepSeek 開源工程 · AI Agent Harness

以外掛組合 AI Agent 執行環境

DeepSeek Harness 繁體中文欄位手冊：Web UI 啟動、模型與工作區設定、plugin tree 架構、profiles、bundles、Python SDK、權限邊界與開發者預覽風險。

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

deepseek-ai/deepseek-harness
星標
—
分支
—
授權
—
資料截至
—
閱讀時間
7 分
更新日期
開啟原始報告
GitHub Stars
163k
內建 Profile 範本
2
Web UI 預設連接埠
3080
開源授權
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 範本。前者加入瀏覽器應用，後者提供不啟動伺服器的單次執行器。

  1. Base bundle

  2. Profile bundles

  3. Profile patch

  4. Home patch

  5. CLI overlay

「Everything is a Plugin.」

— DeepSeek Harness 專案簡介

02啟動與初始設定

Web UI 首次啟動流程

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

bash
npx @deepseek-ai/dsh web

原始碼啟動流程

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

bash
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

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 放入實際工作區。

預設 Web profile

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

來源 · 官方 Web UI 指南

工作區選擇順序

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

來源 · 官方 Web UI 指南

Profile 執行組合

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

來源 · 官方架構文件

Bundle 設定層

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

來源 · 官方外掛打包教學

組合設定檢查

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

來源 · 官方架構文件

可逆註冊效果

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

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

必要服務依賴

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

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

Home patch 機器偏好

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

來源 · 官方外掛打包教學

GitHub 外掛版本固定

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

來源 · 官方外掛打包教學

核准政策與 sandbox 分層

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

來源 · 官方架構與 Web UI 指南

05Web 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 讀取工作區檔案並維持計畫]
hl: [需核准的操作由 Web UI 依目前 permission policy 詢問]
ok: [以 agent 實際輸出與 session log 驗證任務結果]

「There is no privileged core to patch.」

— DeepSeek Harness 架構文件

驗收條件

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

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

06限制與安全條件

Developer Preview 的使用邊界

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 架構文件