DeepSeek Harness：外掛式代理框架

1. 專案概覽

DeepSeek Harness (dsh) 是由 DeepSeek AI 推出的開源外掛式代理框架，讓開發者能夠建構、執行並完整追蹤 AI 代理——從每一次模型呼叫、工具調用，乃至沙箱中的程式碼執行——系統中的任何組件皆可作為外掛進行替換或重組。

2. 背景與定位

DeepSeek Harness 的誕生旨在為社群提供開放、可重用且可組合的基礎設施，用以探索 AI 代理在真實環境中的能力邊界，而非讓每個團隊都必須從零開始重建相同的代理腳手架——包括模型路由、工具執行、沙箱隔離、對話儲存與排程等機制。

其核心使命正如專案所述：「萬物皆外掛」。該框架建構於 Cordis 之上，這是一個專為「時空可組合性」設計的外掛執行環境——意指無需重新設計周邊系統，即可新增、移除或熱替換各項功能（模型、工具、技能、沙箱、儲存空間）。

它與許多其他代理框架的最大區別在於這種端到端統一的外掛模型：模型、工具、技能、對話、沙箱、儲存空間、排程迴圈，甚至 Web UI，都是基於相同底層建構的一級外掛，而非僅在固定核心上附加少數擴充點。結合僅限追加的對話記錄以實現完整追蹤，它特別適合需要檢視、重播與稽核代理行為的團隊——而不僅僅是獲取答案。

3. 功能分類

🧩 外掛系統 — 基礎層級；每項功能（模型、工具、技能、對話、沙箱、儲存空間、迴圈、排程、UI）皆實作為 Cordis 外掛，可獨立替換，讓團隊無需分支核心即可混合搭配組件。
🤖 模型與工具編排 — 可插拔的模型後端及完整的程式設計代理工具集，包含檔案編輯、Shell 存取與網路搜尋，使代理能在真實程式碼庫與環境中運作。
📝 對話記錄與重播 — 僅限追加的對話日誌會捕捉每一次模型互動，支援對過往代理執行進行檢視、恢復、分支與重播，便於除錯與稽核。
🖥️ 多重執行模式 — Standard（完整程式設計代理工具集）、Code（基於 TypeScript 的工具編排）、Minimal（精簡基準測試環境）及 Creator（自訂預設開發與即時執行檢視），涵蓋從生產環境代理到受控基準測試等多種使用情境。
🌐 Web UI — 內建瀏覽器介面（本機提供服務，例如 http://127.0.0.1:3080），無需額外工具即可與執行中的代理互動並觀察其狀態。
🔌 社群外掛生態系 — GitHub 上有數百個標記為 dsh-plugin 的第三方外掛，涵蓋視覺/多模態擴充、沙箱、MCP 整合、終端機 UI 及工作流程工具。

4. 主要亮點

萬物皆外掛 — 模型、工具、技能、對話、沙箱、儲存空間、迴圈、排程及 UI 皆以相同方式實作與替換，擴展系統時只需一套心智模型，無需適應多種機制。
設計即具完整追蹤性 — 對話狀態採僅限追加模式，任何代理執行皆可被檢視、恢復、分支或重播，這對除錯非確定性代理行為至關重要。
基於 Cordis 建構 — 採用專門的外掛執行環境（詳見論文《A Programming Paradigm for Spatiotemporal Composability》），而非臨時拼湊的擴充機制，賦予外掛系統嚴謹的理論基礎。
Host/Client 聚合架構 — 程式碼庫將 Host 套件（tsconfig.host.json）與 Client 套件（tsconfig.client.json）清晰分離，確保雙方能安全地以不同服務擴展同一個 Cordis Context 介面，而不會發生型別衝突。
開箱即用的多重執行預設 — Standard、Code、Minimal 及 Creator 模式分別對應程式設計代理、TypeScript 編排工具使用、輕量級基準測試及自訂預設撰寫，無需額外設定。
免安裝快速入門 — 執行 npx @deepseek-ai/dsh web 即可立即啟動可用的 Web UI，降低初次使用門檻。

5. 依角色劃分的使用情境

一般開發者：使用 Standard 執行模式啟動具備檔案編輯、Shell 及網路搜尋工具的程式設計代理，並透過 Web UI 驅動日常開發任務。
DevOps/SRE：利用沙箱執行與僅限追加的對話日誌來運行並稽核自動化運維代理，在診斷事件時重播過往執行紀錄。
資料/研究科學家：使用 Minimal 模式作為受控基準測試環境，在精簡且可重現的工具集下評估代理或模型行為，並利用對話重播進行分析。
專案經理 / 平台團隊：採用 Creator 模式組裝並檢視針對團隊工作流程客製化的代理預設，再將其作為可重用外掛發佈。

6. 快速入門

尋找所需資源 — 瀏覽官方文件、開發指南，以及 GitHub 上標記為 dsh-plugin 的社群外掛。

安裝 / 整合 — 最快捷的方式是透過 npm，無需複製儲存庫：

npx @deepseek-ai/dsh web

這會在 http://127.0.0.1:3080 啟動 Web UI。若需從原始碼建置：

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

貢獻 — 請閱讀儲存庫中的 CONTRIBUTING.md 與 AGENTS.md，並在提交變更前執行相關檢查：

pnpm run typecheck
pnpm run lint
pnpm run check:all

7. 專案結構

deepseek-harness/
├── tsconfig.json          # 解決方案根目錄 / tsserver 探索入口
├── tsconfig.base.json      # 共用編譯器選項與路徑解析
├── tsconfig.host.json      # Host 聚合：host 套件、範例、測試、腳本、網站
├── tsconfig.client.json    # Client 聚合：packages/client/* 與瀏覽器應用程式
├── api/remotes/            # 唯一橫跨 Host 與 Client 設定的套件
├── docs/                   # 開發、架構與使用者指南
└── AGENTS.md                # 面向代理貢獻的規範

套件只能註冊於單一聚合（Host 或 Client），絕不能同時屬於兩者，這可避免雙方在共同編譯時，其宣告合併的 Cordis Context 介面發生命名衝突。

8. 相關生態系

Cordis — DeepSeek Harness 所依賴的底層外掛執行框架，為外掛提供「時空可組合性」模型。
Model Context Protocol (MCP) — 作為整合層受到支援，允許外部工具（如統計或資料分析工具）透過 MCP 伺服器暴露給代理使用。
社群外掛 — 在 dsh-plugin GitHub 主題下擁有超過 800 個儲存庫的成長中生態系，包含視覺/多模態外掛、沙箱提供者、終端機 UI 及 Web UI 佈景主題。

9. 授權條款

✅ 依據寬鬆的 MIT 授權，可使用、修改及散佈程式碼，包括用於商業用途。
✅ 可將 DeepSeek Harness 整合至專有產品中，前提是保留授權條款與版權聲明。
❌ 不提供任何擔保——軟體係按「現狀」提供。
ℹ️ 第三方依賴項適用其自身授權，另詳載於 THIRD_PARTY_NOTICES.md。

10. 常見問題

問：DeepSeek Harness 是否已準備好用於生產環境？
答：目前仍處於開發者預覽階段且迭代迅速，維護者明確警告可能存在破壞相容性的變更——在生產環境依賴此專案前請務必審慎評估。

問：什麼是 Cordis？為何專案依賴它？
答：Cordis 是支撐 DeepSeek Harness「萬物皆外掛」架構的底層外掛執行框架；設計理念請參閱儲存庫中引用的論文《A Programming Paradigm for Spatiotemporal Composability》。

問：如何在不從原始碼建置的情況下試用？
答：執行 npx @deepseek-ai/dsh web 即可在本機 http://127.0.0.1:3080 啟動 Web UI。

問：我可以撰寫自己的外掛嗎？
答：可以——外掛透過 @Remote 或 @RemoteScope 裝飾器在 Host 服務上宣告，並在 Client 端經由 ctx.remote 使用；詳情請參閱開發指南。

問：我在哪裡可以找到社群開發的外掛？
答：請瀏覽 GitHub 上的 dsh-plugin 主題，其中列出了視覺、沙箱、終端機 UI 等各類第三方外掛。

11. 快速連結

儲存庫：https://github.com/deepseek-ai/deepseek-harness
開發指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/docs/development.md
貢獻指南：https://github.com/deepseek-ai/deepseek-harness/blob/master/CONTRIBUTING.md
社群討論：儲存庫的 GitHub Discussions，以及專屬 Discord 社群

12. 總結

DeepSeek Harness 提供統一且具備完整追蹤能力的外掛架構來建構 AI 代理，讓團隊無需重构技術堆疊即可替換模型、工具、沙箱與儲存空間。它最適合需要可稽核、可重播代理執行紀錄，且能適應快速迭代的開發者預覽版（而非穩定的長期支援版本）的開發者與團隊。