DeepSeek Harness 入門教學：安裝、操作與 Plugin 開發完整指南

AI
, , , ,
1

學習 DeepSeek Harness 核心架構、快速啟動 Web UI、Headless 自動化模式、Plugin 開發流程與安全權限設定，附完整指令範例與故障排除，適合 AI 工程師與自動化團隊。

DeepSeek Harness 核心概念

DeepSeek Harness（簡稱 dsh）是 DeepSeek AI 開發的開源 Agent 執行環境，採用「一切皆為 Plugin」的模組化架構，底層由 Cordis 框架驅動。專案目前處於 Developer Preview 階段，指令、套件與設定格式可能出現 Breaking Changes。

不同於單一聊天機器人，dsh 提供一套可組合的 Agent Runtime，將不同能力拆解為獨立 Plugin：

  • LLM Provider 整合
  • Shell 與 Subprocess 執行
  • Filesystem 存取
  • Web Search 與 Page Fetch
  • Skills、Subagents、Workflow
  • Session Persistence
  • Permission 與使用者互動
  • ACP、JSON-RPC 與遠端 API
  • Agent 自我修改與 Plugin 動態載入

核心架構採用 Service Definition → Service Provider → Consumer 三層分離，例如 Shell 能力可由 Local Shell 或 PowerShell 實作 Provider，Agent 透過 Tool 呼叫統一介面。這種設計適合需要自行組合能力、替換模型提供者、加入自訂工具，或建立長時間自動化工作流的開發者。

環境準備與安裝

必要軟體

環境 版本需求 安裝方式
Node.js ^22.19 或 >=24 建議使用 nvm 管理
pnpm 最新版 corepack enable && corepack prepare pnpm@latest --activate
Git - 系統套件管理器安裝
DeepSeek API Key - 從 DeepSeek 官方取得

Node.js 安裝（macOS / Linux）

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.zshrc
nvm install 24
nvm use 24
node --version

pnpm 安裝

corepack enable
corepack prepare pnpm@latest --activate
pnpm --version

若系統無 corepack，可改用 npm install --global pnpm。

快速啟動

方式一：直接使用 npm package（最簡單）

npx @deepseek-ai/dsh web

啟動後，Web UI 預設監聽 http://127.0.0.1:3080。若 Port 被佔用，請先執行 npx @deepseek-ai/dsh web --help 查看當前版本支援的參數。

方式二：從原始碼建置（適合開發與除錯）

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

設定 API Key

export DEEPSEEK_API_KEY="your_api_key"
export DEEPSEEK_BASE_URL="https://api.deepseek.com"  # 可選

或在專案根目錄建立 .env：

DEEPSEEK_API_KEY=your_api_key
DEEPSEEK_BASE_URL=https://api.deepseek.com

:warning: 安全提醒：切勿將 .env、API Key 或任何憑證提交至 Git。官方開發規範明確禁止提交 Credentials。

三大 CLI 執行模式

模式 指令 適用場景
Web 模式 pnpm dsh web 或 npx @deepseek-ai/dsh web 互動式使用、瀏覽 Session、觀察 Tool Calls、需 Approval 的操作、初次熟悉系統
Headless 模式 pnpm dsh --profile headless "任務描述" CI/CD、自動化腳本、批次執行、無需互動的工作
ACP 模式 pnpm run demo:acp IDE 整合、CI Worker、外部 Orchestrator、多 Agent Pipeline、企業內部自動化平台

Headless 範例

pnpm dsh --profile headless \
  "檢查所有 TypeScript 檔案是否存在未使用的 import，輸出檔名與行號，不要修改檔案"

Web UI 使用流程

  1. 啟動 npx @deepseek-ai/dsh web 並開啟 http://127.0.0.1:3080
  2. 設定模型或 API Credentials
  3. 建立新 Session
  4. 輸入任務描述
  5. 觀察 Agent 推理過程與 Tool Calls
  6. 在需要時批准敏感操作
  7. 檢查修改結果與 Session Log
  8. 讓 Agent 繼續處理後續任務

建議的首次測試順序

  1. 唯讀分析：「請分析目前專案的目錄結構，列出主要模組與可能的啟動指令。不要修改任何檔案。」
  2. 唯讀工具：「請找出所有 package.json，整理每個 package 的名稱、用途與主要 scripts。不要執行安裝或修改。」
  3. 寫入測試：「請建立一個 docs/agent-test.md，內容為目前專案的簡短說明。建立前先顯示預計寫入的內容。」

高效 Prompt 寫作原則

dsh 會根據任務決定是否使用 Tools，Prompt 應明確描述：

  • 任務目標
  • 可使用的檔案或目錄
  • 是否允許修改
  • 是否允許執行命令
  • 預期輸出格式
  • 失敗時的處理方式

常用 Prompt 範本

唯讀分析

分析這個 repository 的架構。
限制：
- 只能讀取檔案
- 不要修改任何內容
- 不要安裝依賴
- 不要執行會改變環境的命令
請輸出：
1. 主要目錄用途
2. 應用程式入口
3. build 與 test 指令
4. 可能的 runtime 依賴
5. 對新開發者最重要的三個檔案

撰寫程式碼

請在 packages/example/src/ 新增一個 TypeScript utility。
要求：
- 先閱讀目前的 coding conventions
- 先提出實作計畫
- 未經確認不要修改檔案
- 新增 unit tests
- 使用現有套件與 TypeScript 設定
- 完成後執行相關的 focused tests

Debug 任務

請調查這個測試失敗的原因。
限制：
- 先重現問題
- 不要直接修改測試來掩蓋錯誤
- 先檢查最近相關的程式碼與設定
- 提出根因、修正方案與驗證方式
- 修正前先顯示計畫

Repository 結構概覽

目錄 用途
packages/core Agent、Session、System Prompt、Tools 與 Agent Loop 核心 API
packages/llm LLM Capability、Provider 與 DeepSeek Model 整合
packages/shell Shell Capability 與 Local / PowerShell Provider
packages/fs Filesystem Capability 與 Policy
packages/web Web Search、Page Fetch 與相關 Tools
packages/skill Skill Provider Registry、Loader 與 Catalog
packages/subagent Subagent Capability 與 Delegation
packages/workflow Workflow Capability 與 Worker-thread Provider
packages/session Durable Session Data、Persistence 與 Telemetry
packages/interaction Approval、Permission、Commands 與 Ask-user
packages/api Remote BFF Assembly 與 Typert RPC Gateway
examples 可執行範例與 cordis.yml 設定
docs Architecture、Development、Testing 與 Cookbook 文件
python Python SDK 與 Bundled Runtime
native Native Sandbox Runner 相關程式碼

Plugin 架構與自訂開發

核心原則

  • 不要直接修改 Agent Loop：新增 Tool、外部 API、Filesystem Adapter、Shell Provider、Workflow、Permission Policy 等，應建立 Plugin 或使用既有 Extension Point
  • Capability Seam 設計：將能力拆為 Service Definition → Service Provider → Consumer，便於替換 Provider 而不影響 Consumer
  • 生命週期管理：Plugin 註冊與清理應透過 ctx.effect() 或 ctx.on() 管理，並提供 Disposer

建立自訂 Plugin 四步驟

1. 定義能力介面

export interface ExampleService {
  execute(input: ExampleInput): Promise<ExampleOutput>
}

2. 實作 Provider

export class ExampleProvider implements ExampleService {
  async execute(input: ExampleInput): Promise<ExampleOutput> {
    return { result: `Processed: ${input.value}` }
  }
}

3. 註冊 Plugin

export function examplePlugin(ctx: Context) {
  ctx.effect(() => {
    ctx.provide(ExampleService, new ExampleProvider())
    return () => { /* 清理資源 */ }
  })
}

4. 建立 Consumer（Tool、Workflow Step、Subagent、API Endpoint、CLI Command 等）

實際 API 名稱與型別需依當前 Repository 實作調整，內部 API 仍可能變更。

從官方範例學習

# 查看範例結構
find examples -maxdepth 3 -type f | sort

# 找尋 cordis.yml 設定
find . -name "cordis.yml" -o -name "*.yaml" | sort

# 搜尋 Plugin 註冊位置
rg "ctx\.effect|ctx\.on|provide|plugin" packages examples

# 搜尋 CLI 入口
rg "dsh web|headless|profile" apps packages examples

建議閱讀順序：README.md → docs/architecture.md → docs/development.md → docs/cordis-primer.md → docs/cookbook → examples → AGENTS.md（需修改 Agent 行為時）。

開發與驗證指令

指令 用途
pnpm run typecheck TypeScript 型別檢查
pnpm run lint 程式碼風格檢查
pnpm run test Vitest Unit Tests
pnpm run test:coverage Coverage Gate
pnpm run test:e2e Real API End-to-End Tests
pnpm run test:snapshot Keyless ACP / Headless Replay
pnpm run build 建置 lib、Types 與 Runtime Bundle
pnpm run hygiene Knip、Publint 與 Workspace Constraints
pnpm run doc-sync 文件同步與檢查
pnpm run website:build 建置 VitePress Website 並檢查 Dead Links

官方建議依修改範圍選擇驗證方式，而非每次執行完整測試套件。

安全權限分級最佳實踐

dsh 能讓 Agent 執行 Shell、讀寫 Filesystem、呼叫 Web Tool，建議採分級授權：

Level 1：唯讀

  • 允許：讀取程式碼、列出檔案、分析設定、搜尋 Repository
  • 禁止：寫檔、安裝、部署、呼叫外部 Mutation API

Level 2：受限寫入

  • 允許：修改指定目錄、建立測試檔案、執行 Local Tests
  • 禁止：讀取 Secrets、修改部署設定、執行 Destructive Commands

Level 3：受控自動化（僅隔離環境）

  • Sandbox、Container、Disposable VM、專用 Cloud Account、最小權限 API Token、可回滾 Workspace

絕對避免的高風險指令（無 Sandbox/Approval 時）

rm -rf
git reset --hard
git push --force
curl ... | sh
sudo ...
docker system prune
terraform destroy

切勿將 Production Credentials、SSH Private Key 或 Cloud Provider Root Key 放在 Agent 可讀取的工作目錄。

常見問題排查

問題 排查步驟
pnpm: command not found corepack enable && corepack prepare pnpm@latest --activate
Node.js 版本不符 nvm install 24 && nvm use 24 確認 node --version
找不到 API Key echo $DEEPSEEK_API_KEY 檢查環境變數；確認 .env 位於專案根目錄且格式正確
Web UI 無法開啟 `ps aux
Build 失敗 pnpm run clean && pnpm install && pnpm run build；檢查 Node/pnpm 版本、Lockfile、Workspace Dependency
Agent 執行不預期操作 停止進程 → 檢查 Prompt、Tools、Permission 設定、Session Log、檔案變更、cordis.yml → 改為唯讀模式並要求 Approval

適用場景與工作流設計

適合 AI 工程與自動化團隊的場景：

  • Repository Codebase Analysis
  • 自動化 Code Review
  • CI Failure Investigation
  • 多步驟 Research Agent
  • Web Research 與資料整理
  • Browser / Shell Automation
  • Subagent Delegation
  • 可重複執行的 Workflow
  • 企業內部 Agent Platform
  • 將 Agent 暴露為 ACP 或 JSON-RPC Service
  • 建立可替換的 LLM、Filesystem、Shell、Web Provider

典型 Research Workflow 設計

使用者任務
   ↓
Planner Agent
   ↓
Web Research Agent
   ↓
Data Extraction Agent
   ↓
Fact-check Agent
   ↓
Report Writer
   ↓
Session / Artifact Storage

建議將每個步驟建模為獨立 Capability，再透過 Workflow 或 Subagent Plugin 組合，避免將所有邏輯寫在單一巨大 Prompt 中。

建議入門路線圖

第一階段：Web UI 體驗

npx @deepseek-ai/dsh web

完成：建立 Session、執行唯讀任務、觀察 Tool Calls、測試 API Credentials、了解 Approval 行為。

第二階段：Source Code 執行

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

完成：閱讀 Repository Layout、執行 Unit Tests、找到 CLI Entrypoint、閱讀 Architecture 文件、執行 Headless Task。

第三階段：建立自訂能力

從簡單的唯讀 Tool 開始：不讀取 Secrets、不修改檔案、不執行 Destructive Commands、加入 Input Validation、加入 Focused Tests、讓 Tool Output 可被 Session Log 重建。

第四階段：導入自動化

加入：Workflow、Subagent、ACP、JSON-RPC、Sandbox、Permission Policy、Durable Sessions、外部 API Integrations。

最小可行操作清單

# 直接啟動 Web UI
npx @deepseek-ai/dsh web

# 從 Source 執行
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

# 設定 API Key
export DEEPSEEK_API_KEY="your_api_key"

# Headless 執行
pnpm dsh --profile headless "分析目前專案，不要修改任何檔案"

# 驗證程式碼
pnpm run typecheck
pnpm run lint
pnpm run test
pnpm run build

結語

DeepSeek Harness 以 Plugin 化架構提供高度可組合的 Agent Runtime，適合需要靈活擴充、長期運行自動化工作流的團隊。建議從 Web UI 熟悉核心流程，再逐步深入 Source Code、Plugin 開發與自動化整合。專案仍處於快速迭代階段，實際操作請以當前版本 CLI Help、官方文件與 AGENTS.md 為準。