【2026 最新】DeepSeek Harness 教學：四種 Mode、Append-only Session 與第一個 Plugin

DeepSeek Harness 教學真正要回答的，不是又一個 Agent 名詞，而是：同一個 DeepSeek 模型，為什麼換了 Harness，完成率、工具循環與帳單就可能完全不同？答案在模型外面：system prompt、工具介面、session 改寫、權限、重試、停止條件與快取前綴，共同決定模型下一步看見什麼、能做什麼，以及失敗時怎麼恢復。

這個問題不是紙上談兵。8 月 13 日出現的 DeepSeek Harness Hacker News 討論在 2026 年 8 月 14 日查詢時已超過 680 points、接近 280 comments；8 月 14 日的 Reddit 比較串則直接問 DeepSeek Harness、Reasonix、Codex 怎麼比。截至同日查核，該 Reddit 串只看到一則缺少任務、版本與 trace 的實質回報，不能當排行榜。本文會從安裝、四種 Mode、append-only session、KV cache 到第一個 Cordis Plugin，最後把比較改造成你能重跑的 A/B test。

⚠️ Developer Preview：本文以 2026 年 8 月 14 日 NPM 的 @deepseek-ai/dsh 0.1.0-rc.6 與同日官方程式碼／文件查核。官方 README明示仍會有 compatibility-breaking changes。請保存頂層版本、resolved package versions 與 config hash；指令或欄位若與未來版本不同，以當下官方文件為準。

DeepSeek Harness 教學先看：它改變的是工作路徑，不是模型權重

🐋 記憶把手：實際完成率＝模型 × Harness × 工具面 × 權限 × 快取 × 任務。
換 Harness 不是把模型變聰明，而是改變它收到的上下文、一次能做幾步、失敗後看到什麼，以及何時被迫停止。

• 模型層：推理、生成與 tool calling 能力。
• Harness 層：把 repo、工具結果、記憶與規則編排成下一次 model request。
• 執行層：shell、檔案寫入、網路、sandbox 與批准政策。
• 評測層：hidden tests、成本上限、超時與外部 grader。

所以「DeepSeek Harness 比 Codex 好嗎」不是一個可直接回答的單一問題。若你還不熟悉 loop、tool result 與停止條件，先讀《AI Agent Harness 是什麼》；想看最小 while loop，再接《從零打造 AI Agent Harness》。本文只處理 DeepSeek 官方產品的實作差異。

若你想先判斷 V4 Pro、Responses API 與 Harness 同日發布到底補齊了哪一層，可讀《DeepSeek V4 Pro 與 Harness 同日雙發》；那篇處理發布與 stack 邊界，這篇則刻意跳過模型榜單，直接動手安裝、擴充與評測。

DeepSeek Harness 教學 Step 1：5 分鐘啟動 Web 與 CLI

路線 A｜用 npx 先跑 Web UI

先確認 Node.js 版本。官方 source checkout 的 engines 是 Node.js ≥22.19.0 且 <23，或 ≥24（Node 23 不在支援範圍）；NPM CLI package 本身沒有用 engines強制這個門檻。只想體驗時，不必先 clone 整個 monorepo。以下固定頂層 CLI 版本以降低漂移；但 npx 不等於鎖住完整相依圖，正式 A/B 仍要保存 lockfile／resolved package versions 與 config hash。

node --version
npx @deepseek-ai/dsh@0.1.0-rc.6 web

# 瀏覽器開啟
# http://127.0.0.1:3080

進入 Settings → Models，填入 DeepSeek API key、按 Apply，再選一個 workspace。新開 Web UI 不一定已綁定工作目錄；確認畫面顯示的 workspace 後，送出第一題：

Summarize this repository and identify its main packages.
先只讀取，不要修改檔案；最後列出你實際查看的路徑。

金鑰由本機 credential store 管理，不要貼進 repo 或 prompt。官方本機 credential 文件指出檔案權限設為 0600，但也明確說這只阻擋其他 OS 使用者，不代表同一帳號啟動的工具程序看不到它。預設 workspace-write 主要限制「修改位置」；讀取、程序與網路也不是完整隔離。測試陌生 Plugin 時，請改用不含生產密鑰的隔離 OS 帳號／容器，並清空啟動環境與 DSH_HOME；單靠拋棄式 workspace 不足以隔離同一使用者的 secrets。

路線 B｜用 headless profile 跑一個 CLI 任務

npx @deepseek-ai/dsh@0.1.0-rc.6 \
  --profile headless \
  "Run the tests, fix only the smallest root cause, then report changed files."

這個 one-shot 會建立可持久化 session、等 Agent 進入靜止狀態，再輸出最後一段非空 assistant 文字；完成時 exit 0，失敗時 exit 1。執行命令的資料夾就是預設 workspace。它適合 CI 與 fixture，但只看 final text 不夠做成本分析，後面的 A/B 仍要保存 provider usage 與完整 session trace。

四種 Mode 怎麼選？其實是四套 Agent preset

介面稱它們為 Mode，實作上是 shipped agent preset。只要 session 尚未跑過任何 turn 就能切換；第一個 turn 後，該 turn 使用的 preset 即鎖定，之後不可中途切換。所以 A/B test 必須每次新建空白 session。

Standard：一般 coding 任務的起點

Standard 提供檔案編輯、shell、檔案與網路搜尋、skills、planning、goals、subagents 與 workflows。你想先知道「這個 repo 任務能不能完成」，就從它開始；缺點是工具面最大，變因也最多。

Code：讓模型用 TypeScript 一次編排多步工具

Code 保留 Standard 的能力，但不把所有 end-tool schema 直接攤給模型；它提供產生出的 SDK 與一個 code transport，模型可在一次 TypeScript 程式裡呼叫多個工具。幾個連續操作因此有機會少掉 model-visible round trip，中間變數也不必全部回灌 context。

這不等於「一定更省 token」。SDK 文字本身有成本，錯誤程式也可能重跑；worker thread 是資源控制，不是安全邊界。用 Code 的理由應是工作流可組合，再用 provider requests、cache hit 與成功成本驗證，而不是先宣布省多少。

Minimal：只留 persistent bash＋str_replace_editor

Minimal 的 system prompt 只有一句「You are a helpful software engineer assistant.」，工具只剩持久化 bash 與 str_replace_editor，也不組合自動 context compaction。它不是最強模式，卻是最好用的診斷基線：若 Standard 成功、Minimal 失敗，差異可能來自工具與工作流；兩者都反覆卡住，才更值得檢查模型、任務或停止條件。

Creator：內部 ID 是 cordis，專門做擴充

Creator 是 Standard 加上 runtime inspection、Plugin 實驗與 preset authoring。目前工具鏈先用 cordis_inspect_list／cordis_inspect_query讀取實際 contract，再以 cordis_define定義、cordis_run啟用動態 Plugin。限制執行環境可防誤用，卻不是惡意程式碼的安全邊界；動態程式仍會接觸 real runtime，因此 Creator session 應視同 shell 權限，不要和一般 coding completion 混排。要改 preset，先複製到個人目錄再改；複製品是 snapshot，升級後不會自動同步。

Everything is a Plugin：Cordis 到底替你做了什麼？

官方架構文件顯示，DeepSeek Harness 的模型 adapter、工具 registry、session log、agent loop、sandbox 與 UI 都由 Plugin 組合。Plugin 透過共享 ctx 提供 service、typed event 與可撤銷 effect；卸載時，經由 context 註冊的 listener、tool 或 timer 會跟著清理。它的價值不是「Plugin 這個詞很新」，而是你能在同一 composition 裡替換一層，而不用 fork 一個神聖核心。

想看 profile 與 overlays 目前會組合出哪些層，可先輸出 pre-boot composed config：

npx @deepseek-ai/dsh@0.1.0-rc.6 \
  --profile web \
  --dump-config

bundle、profile、家目錄 override 與 --patch 會依序套用，後面的 layer 勝出。不過這份 dump 仍未求值 !!js，app arguments 也尚未執行；比較時要一起保存 config dump、環境值與 app arguments，不能只記「我用 Standard」。想理解更大的跨 Agent 封裝，可延伸《Agent Plugins v1 教學》；兩者不是同一套 Plugin API。

Append-only Session 與 KV Cache：完整紀錄不等於 Prompt 永遠變長

Session subsystem 文件把 source of truth 定義為 append-only typed event log：user input、model output、tool call、tool result 與 command lifecycle 依序追加，舊事件不被偷偷刪掉。但 model history 是「衍生 surface」；當 context 壓力升高，compaction 可以加入摘要，並用 surfaceOp replace 遮蔽較早訊息。原始 trace 仍在，下一次 request 卻不必把全部逐字送回模型。

KV cache 吃的是穩定 prefix。system prompt、tool schema 或歷史在某處改變後，只能期待重用變動前仍完整匹配的 cache prefix unit；換模型是否沿用快取，DeepSeek 公開文件未保證，應以 usage 驗證。DeepSeek API 也把上下文快取定義為自動、best-effort 的 prefix matching，不是 Harness 能保證的命中。正式計量要讀 API 的 cache-hit／cache-miss usage，而不是把「第二次執行」直接叫 warm cache。

Harness 的重複工具提醒會在相同 canonical tool＋args「連續呼叫」的第 3、5、8 次注入提示；換成另一個受追蹤呼叫後，計數會重置，被 include／exclude 排除的呼叫則對 chain 透明，不會重置。它只是 advisory reminder，不會硬擋工具。timeout-policy 也只替有宣告 timeoutMs 的工具設定 cooperative deadline；工具還必須傳遞並遵守 exec.signal 才會停，shipped bash／read／write／edit 則刻意未宣告這個 budget。因此，append-only trace 很適合回答「它從哪一步開始沒進展」，卻不能等同「永不失控」。要把 trace 變成可操作指標，可搭配《Agent Observability 完整教學》。

第一個 Plugin：同時加入 greet 工具與 /hello 指令

官方的第一個 Plugin 教學目前走 source checkout，因為本機 TypeScript module 要在 monorepo composition 中載入。以下固定在本文實測的 source snapshot；若要改追最新分支，請另存實際 commit，並回到官方 Plugin 教學核對。

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git checkout 47f943859bef60e4160492346772ded9b24f765a
pnpm install
pnpm run build
mkdir -p scratch-plugin/src

repo 固定 pnpm@11.7.0；先確認 pnpm --version 能執行，只有已安裝 Corepack、但 pnpm 尚未啟用的環境才需要跑 corepack enable。這個 source snapshot 的 monorepo version 是 rc.5，前面的 npx 路線則是 rc.6；兩條路可各自學習，但 benchmark 紀錄不要混算。

建立 scratch-plugin/src/my-plugin.ts。這份範例已在上述 rc.5 source snapshot 實際完成型別檢查、載入與執行；另對 0.1.0-rc.6 公開套件完成型別檢查。後者只證明公開型別相容，不代表 rc.6 source runtime 已驗證。

import type { Context } from '@deepseek-ai/cordis'
import type { CommandInvocation } from '@deepseek-ai/dsh-commands'
import { defineTool } from '@deepseek-ai/dsh-tools'

export const name = 'hello-plugin'
export const inject = ['tools', 'commands']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'greet',
    description: 'Greet someone by name.',
    parameters: {
      name: { type: 'string', required: true, description: 'The name to greet' },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return `Hello, ${args.name}!`
    },
  }))

  ctx.commands.register({
    name: 'hello',
    description: 'greet someone without a model turn',
    input: { hint: '<name>' },
    handler: (invocation: CommandInvocation) => ({
      kind: 'success',
      text: `Hello, ${invocation.rawInput.trim() || 'world'}!`,
    }),
  })
}

greet 是模型看得到、能決定何時呼叫的 tool；/hello 是人類在 Web UI 直接執行的 command，不送進模型，也不增加 model token。這個區別很重要：確定性的 UI 操作不要繞模型一圈。隨附的 headless／ACP adapter 不消費 command registry，所以 /hello 要在 Web 測。

再建立 scratch-plugin/cordis.yml。這裡必須填絕對路徑；patch 檔不會改變 module path 的解析根目錄。

- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

pnpm dsh web --patch ./scratch-plugin/cordis.yml

1. 在 Web 輸入 /hello Ada，應直接得到 Hello, Ada!，不啟動 model turn。
2. 再輸入 Use the greet tool to greet Ada.，模型應呼叫 greet，tool result 是同一句問候。
3. 停止目前程序，拿掉 --patch 後重新啟動並刷新；tool／command 應一起消失，證明能力來自這個 Plugin。這只能驗證 composition 差異；若要測 live effect cleanup，需把 row 放進受監看的 profile／home cordis.patch.yml，再於執行中移除該 row。

若要把範例做成可安裝 bundle，先依官方 publish 教學建立 package.json（宣告 dsh.bundle.patch）與 bundle 的 cordis.patch.yml；之後才用 pnpm dsh plugin --profile web add <package-or-path> 安裝到 profile。這個 add 是安裝，不是發佈；Plugin 管理會轉交 pnpm，所以它必須在 PATH。第一輪先保持本機、可讀、可卸載。Plugin 能執行程式碼，來源與依賴都要當供應鏈審核，不要只看名稱。

同一 Repo 怎麼 A/B？先分「模型控制」與「原生產品」兩條賽道

本文查核的官方文件、HN 主串與 Reddit 比較串，沒有提供足以宣布 DeepSeek Harness、Reasonix、OpenCode 或 Codex 誰勝出的可重現 benchmark。最誠實的做法不是填一張示意排名，而是建立兩個不能混算的研究。

賽道 A｜同一 DeepSeek 模型，隔離 Harness 差異

• Arms：DSH Standard／Code／Minimal、Reasonix 固定解析後 config、OpenCode 固定 Build agent，並用隔離 config home／乾淨 repo 確認沒有載入外部 Plugin，以及 Codex 固定同一 DeepSeek model。
• 鎖定：同一 model ID、thinking／effort、API 帳戶、repo commit、instruction file、可寫路徑、外部命令與網路規則，以及 wall time、provider-request cap、美元上限。各產品的權限／sandbox 機制不同，必須逐 arm 驗證實際可讀寫範圍，不能把某個產品的 workspace-write 名稱當成等價控制。
• Codex 邊界：DeepSeek 已提供官方 Responses API 與 Codex 串接方式，因此可直接加入同模型賽道，不必自建 bridge。不過該相容層是 stateless，且部分不支援的參數會被靜默忽略；保存 Codex config、實際 request／usage 與 API 文件快照，這些協定差異仍是分析的一部分。

賽道 B｜各用原生推薦設定，測整套產品

DeepSeek Harness、Reasonix、OpenCode、Codex 各自保留當次解析後的原生設定與能力，包括模型、提示、工具、session／compaction 與 retry；逐項記錄實際配置。這回答「我每天用哪套比較容易完成」，不是純 Harness 因果。Codex 可用官方文件的 codex exec --json留下 JSONL；其他產品也保存自己的 session/export，但 token 與費用最後以 provider／gateway 原始 usage 為準。

一個可重跑的 fixture

1. 挑一個有失敗測試、hidden regression 與明確 allowed-files 的 bug fix；固定 immutable commit 與 container image。
2. 每次建立乾淨 worktree、獨立 home/config/session；先裝依賴。執行時封鎖 Agent 工具的一般外網，只在 Harness／控制平面 allowlist DeepSeek API（或統一 gateway）端點，並禁止 push／deploy。
3. 每 arm 至少跑 5 次，最好 10 次以上；隨機交錯順序，避免 provider 當時負載只偏向某一組。
4. Agent 停止後，由外部 grader 跑 visible＋hidden tests、lint／typecheck、diff scope 與秘密掃描；不要採信 final answer 自稱成功。
5. 把結果分成 complete、partial、fail、timeout、harness error、provider error。單一 repo 只能稱 case study，不能外推所有任務。

「循環」也要先定義。建議把 repeat loop 定義成相同正規化工具呼叫連續至少 3 次且結果近似；stagnation loop 則是連續至少 3 個 provider request 都回到相同 git tree hash、相同測試錯誤與相同工具類型，而且沒有查看新檔案或 symbol。timeout 不自動等於 infinite loop。

cache_hit_rate = hit_input / (hit_input + miss_input)

run_cost =
  miss_input / 1e6 * miss_price +
  hit_input  / 1e6 * hit_price  +
  output     / 1e6 * output_price

expected_cost_per_success = 全部 attempts 的總成本 / complete 次數

主指標用完成率、provider requests、tool calls、failed tool calls、loop incidence、longest no-progress streak、wall time、cache hit／miss、output tokens 與 expected cost per success。各家對「turn」定義不同，不要直接比原生 turn 數。若你想沿用更完整的 repo 評測流程，《Grok 4.6 API Coding Agent 實戰》已拆好驗收器、重跑與成本口徑；本文只加上 DeepSeek 的 Mode、trace 與 Plugin 變因。

DeepSeek Harness FAQ

DeepSeek Harness 就是 DeepSeek API 嗎？

不是。API 提供模型推理；Harness 負責工具、session、權限、loop、Plugin 與 UI。兩者疊在一起才形成實際 Coding Agent。

一定要全域安裝 dsh 嗎？

不用。先用 pin 版本的 npx @deepseek-ai/dsh@… web 最乾淨；要開發本機 Plugin，再走官方 source checkout。

四種 Mode 可以在同一個 Session 中途切換嗎？

第一個 turn 後不行。空白 session 仍能選 preset；第一個 turn 用哪套，之後就鎖定哪套，所以評測要每次建立新 session。

Append-only 是否代表 Prompt 永遠只增不減？

不代表。原始 event log 只追加，但送給模型的衍生 surface 可以 compact、replace 或遮蔽舊內容。

KV cache 命中是 DeepSeek Harness 保證的嗎？

不是。Harness 能維持較穩定前綴，但 provider 是否命中、何時淘汰仍是 best effort；以實際 usage 欄位判定。

Code Mode 一定比 Standard 便宜嗎？

不一定。它能把多步工具放進一次程式執行，但也增加 SDK 文字與 code runtime；要看成功成本與 provider requests，而非只算工具數。

Tool 和 slash command 有什麼差別？

呼叫者不同。Tool 暴露給模型並進入 agent loop；command 由人類 UI 直接執行，結果不自動送給模型。

能把 Codex 放進相同 DeepSeek 模型的 A/B 嗎？

可以。DeepSeek 現已官方支援 Responses API 與 Codex 設定，不必自建 bridge；但它是部分相容、stateless 的介面，仍要記錄被忽略的參數與實際 usage，不能把「同 model ID」誤當所有 request 完全相同。