外掛
能力的安裝與組合單元。它可以同時註冊工具、服務、事件和介面。
DEEPSEEK HARNESS · 外掛教學
DeepSeek Harness
外掛從 0 到 1 教學面向完全新手的實作手冊
閱讀導圖
先跑通，再理解，最後擴展。
你不需要先成為框架專家。按頁順序完成一個最小外掛，再根據自己的 Agent 選擇下一種能力。
01
認識外掛
第 03–05 頁：外掛是什麼、常見概念，以及開始前必須做的三項決定。
02做出第一個外掛
第 06–09 頁：15 分鐘跑通 Hello 外掛，再給模型增加一個真正可調用的 Tool。
03選擇外掛類型
第 10–13 頁：九種常見類型、練習題和適用條件。
04
理解組合與邊界
第 14–19 頁：Dynamic Plugin、Agent preset、權限邊界和能力預算。
05找到值得做的方向
第 20–23 頁：熱門方向、未來機會，以及與 WorkBuddy、Codex、Claude Code 的區別。
06交付一個能用的外掛
第 24–26 頁：從想法到交付、驗收清單、常見問題和後續入口。
01 · 概念起點
外掛，是 Agent 的「可插拔能力單元」。
一個 AI Agent 不只是模型。它還需要上下文、工具、循環、狀態、權限和介面。外掛讓這些部分可以被註冊、替換和組合。
外掛可以增加什麼
- 給模型增加一個可調用的 Tool
- 注入提示詞、Skill 或領域知識
- 監聽確定性的 Event / Hook
- 提供可複用的 Service
- 在 Client Slot 中增加介面
- 連接瀏覽器、數據庫、GitHub 等外部系統
- 保存會話狀態、執行 Workflow 或委派 SubAgent
最小心智模型
輸入：配置、上下文、用戶請求、外部系統。
註冊：外掛通過 Context 把能力放入 Harness 的註冊表或生命週期。
運行：Agent、模型或其他外掛在需要時調用它。
證據：結果要能通過工具輸出、文件、介面狀態或會話記錄被驗證。
一句話判斷
如果某項能力需要獨立安裝、配置、替換或組合，它通常適合成為外掛。
名詞總覽
先分清 7 個概念，後面就不會亂。
工具
模型可以主動調用的函數。要有名稱、描述、參數、執行邏輯和輸出。
技能
面向模型的可複用流程和上下文，告訴 Agent 在什麼情況下怎樣完成任務。
外部能力入口
把外部系統暴露為工具或命令。它們不是業務流程本身。
確定性動作
在明確生命週期點自動執行，例如記錄、校驗、清理或阻止錯誤狀態。
子 Agent
擁有獨立角色、上下文和權限的執行者，適合並行或專業任務。
Agent 預設
把已驗證的外掛、提示詞、Skill 和服務組合成一種穩定的 Agent 工作方式。
記憶方法
外掛負責分發；Tool 負責執行；Skill 負責步驟；Event 負責確定性。
開始前
開始前，只做三項決定。
這三項決定會影響代碼位置、權限、生命週期和交付方式。
在哪裡執行？
Host 適合文件、命令、網絡、持久狀態。Client 適合展示和交互。兩端都需要時，用 Host + Client。
由誰擁有？
所有 Agent 共用的基礎能力放在 Host 組合中；某類 Agent 專屬能力放在 preset 中。
怎樣發佈？
實驗用 Dynamic Plugin；長期維護用正式包；需要一次安裝整套能力時用 Bundle。
你的第一張設計卡
用戶結果：用戶最終能做什麼？ 執行位置：Host / Client / 兩端？ 證據：如何確認它真的完成？
02 · 首次運行
15 分鐘，跑通最短路徑。
這一輪只證明“外掛可以被加載”。不要先做完整產品。
01
準備倉庫
02
寫 apply
03
插入配置
04
啟動 Web
05
看見日誌
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
mkdir -p scratch-plugin/src
成功標準
啟動命令不報錯；瀏覽器能打開；終端出現外掛加載日誌。
本輪暫時不做
不做 UI、不接數據庫、不做複雜配置，也不加多個工具。
Hello 外掛
先讓 Harness 看見你的外掛。
import type { Context } from '@deepseek-ai/cordis'
export const name = 'hello-plugin'
export function apply(ctx: Context) {
console.log('[hello-plugin] plugin loaded!')
}
把外掛插入 composition
- insert:
- id: hello
name: '/absolute/path/to/
scratch-plugin/src/my-plugin.ts'
啟動並觀察
pnpm dsh web --patch \
./scratch-plugin/cordis.yml
打開 http://127.0.0.1:3080。終端出現 [hello-plugin] plugin loaded! 就說明最小路徑成立。
為什麼 apply 最重要
apply(ctx, config) 是外掛進入 Harness 的入口。下一步的 Tool、Service、Event 和 UI，都從這裡註冊。
你的第一個 Tool
現在，給模型一項真正的能力。
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'greet-tool'
export const inject = ['tools']
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}!`
},
}))
}
模型怎麼發現它
name 與 description模型怎麼調用它
parameters用戶怎麼看結果
output.renderTool 結構
一個好的 Tool，有 6 個清楚的部分。
inject
聲明硬依賴。這裡表示外掛加載前必須已有 tools 服務。
name
穩定、短、可區分。模型會用它發起調用。
description
說明“何時使用”和“得到什麼”，不要只重複名稱。
parameters
讓模型知道參數類型、是否必填及業務含義。
execute
真正執行工作。它的返回值必須符合輸出 schema。
render
把結果變成用戶能讀的介面。先保持簡短，再按需展開原始數據。
測試提示詞
Use the greet tool to greet Ada.
驗證重點
不是隻看最終文字。確認模型確實發起了 Tool call，並拿到了 Tool result。
export interface Config { greeting: string }
export const Config = Schema.object({
greeting: Schema.string().default('Hello'),
})
03 · 九種類型
九種外掛類型，一張圖選對起點。
Tool
讓模型執行一個動作。最適合第一個外掛。
Skill / Prompt
讓 Agent 穩定複用一套流程或領域知識。
Event / Hook
在明確生命週期點執行確定性動作。
Service
提供可被多個外掛複用或替換的能力。
Client Slot
在已有介面槽位中增加展示與交互。
Host + Client
後端執行，前端展示，兩端通過 JSON 通信。
Workflow / SubAgent
拆分長任務、並行任務或專業角色。
Session / Storage
保存需要跨輪次或跨會話使用的狀態。
Agent preset
把已驗證能力組合成穩定 Agent。
類型 01–03
執行、指引、確定性：三種最常用能力。
01
Tool
適合：讀文件、查接口、創建記錄、運行命令。
第一版：只讀、參數少、輸出短。
練習：做一個 project_summary 工具，返回文件數、語言和入口。
02
Skill / Prompt
適合：代碼審查、發佈流程、產品驗收、固定報告。
第一版：清楚寫“什麼時候用”和“按什麼步驟做”。
練習：寫一個“接口變更檢查”Skill。
03
Event / Hook
適合：日誌、校驗、自動清理、調用前後處理。
第一版：只監聽一個事件，並明確清理邏輯。
注意：waterfall 監聽器要調用 next() 繼續鏈路。
選擇口訣
需要模型決定何時執行，用 Tool；需要模型按步驟思考，用 Skill；無論模型怎麼想都必須發生，用 Event / Hook。
類型 04–06
當能力需要複用，或需要介面。
Service
把能力拆成 Definition、Provider、Consumer。只有在多個外掛需要複用，或實現需要被替換時才使用。否則，一個 Tool 更簡單。
Client Slot
查詢已有 Slot，再掛載最小介面。不要直接操作產品 DOM。介面只展示用戶需要確認、選擇或查看的內容。
Host + Client
Host 通過 harness.handle() 暴露方法；Client 通過 host.call() 調用。兩端只傳 JSON 可序列化數據。
練習
做一個“運行測試”面板：Host 執行命令，Client 顯示進行中、通過、失敗和日誌摘要。
邊界
前端負責交互，後端負責權限和真實執行。不要在 Client 中偷偷複製後端邏輯。
類型 07–09
當任務變長、狀態變多、能力要組合。
07
Workflow / SubAgent
把複雜任務拆成 Router 和專業 Worker。隔離角色、上下文、工具與權限，結果才容易複核。
練習
一個 Router 將任務分給“資料整理”和“代碼實現”兩個 Worker。
08
Session / Storage
提供 remember、find、forget。每條記憶保留來源、時間和作用域。
不要這樣做
不要自動保存所有對話；不要讓模型可見內容脫離會話記錄。
09
Agent preset
組合已驗證的 Tool、Skill、人格、提示詞和服務，形成穩定工作方式。
練習
做一個“發佈助手”preset，只加載發佈所需能力。
先確認一個能力單獨可靠，再把它放入 Workflow、記憶層或 preset。組合不會自動修復不穩定的組件。
“
04 · Dynamic Plugin
最快的學習方式，是讓 Agent 在運行時定義一個小外掛，然後立刻觀察結果。
Dynamic Plugin 適合實驗、探索接口和驗證想法。重啟後不會自動保留；長期使用時應轉成正式包。
七步循環
Dynamic Plugin 的七步閉環。
列出已運行外掛
cordis_inspect_list先看現場，不要猜已有能力。
查詢註冊表
cordis_inspect_query確認目標 Service、Slot 或 Event。
檢查當前運行體
cordis_inspect_self確認 Host / Client 位置和依賴。
定義外掛
cordis_define只寫 JS 函數體。定義不會自動執行。
啟動運行
cordis_run獲得新的 pluginRunId，等待最終狀態。
停止運行
cordis_stop釋放事件、介面和其他資源。
刪除定義
cordis_undefine實驗結束後清理定義。
驗收
重新 inspect 目標 run，確認狀態、診斷和輸出證據。
執行時規則
四條規則，避免「看起來成功」。
| 規則 | 你需要記住什麼 |
|---|---|
| 代碼形式 | 只寫 JavaScript 函數體。不要使用 import、require、TypeScript、裝飾器或 JSX。 |
| 運行環境 | 不要假設存在 window、document、process、Buffer、fetch 或定時器。Client 介面用 React.createElement。 |
| 生命週期 | 用 ctx.on() 和 ctx.effect() 註冊可清理副作用。awaiting-approval 與 starting 不是最終成功。 |
| 權限 | Host VM 不是安全邊界。能觸達文件、命令或網絡的動態外掛，應視為擁有與 shell 相近的權限。 |
不要混淆四種 ID
pluginId 指外掛；packageId 指定義包；pluginRunId 指一次運行；currentPackageId / nextPackageId 指切換前後定義。
從 Dynamic 轉正式包
當外掛需要重啟後保留、團隊版本管理、穩定配置、持久狀態或 preset 組合時，把它遷移到正式 TypeScript 包。
Agent 組合
Host 管基礎設施，preset 管角色能力。
Host composition
所有 Agent 共用、涉及系統權限的底座。
- 共享註冊表、持久化、設置與憑據
- 遙測、會話和模型路由
- Sandbox、權限、審批與文件策略
- SubAgent 註冊表和基礎 provider
Agent preset
某類 Agent 獨有的可組合工作方式。
- 專用 Tool、Skill、人格與提示詞
- 專用 compaction 策略
- 私有 Service 與 Consumer
- 委派工具和 Workflow 組合
關鍵限制
preset 不能降低 Host 權限，也不能替用戶安裝或登錄 Codex、Claude 等外部產品。Service 的 Provider 與 Consumer 要處於同一隔離組。
05 · 邊界
外掛能提供能力，但不能越過系統邊界。
| 方面 | 外掛可以做 | 外掛不能保證 |
|---|---|---|
| 模型 | 增加 Tool、Prompt、Skill、路由和上下文。 | 繞過模型能力、上下文窗口或服務商限制。 |
| 文件與命令 | 在授權範圍內讀寫文件、執行命令。 | 繞過 OS Sandbox、審批、目錄策略和賬戶權限。 |
| 網絡 | 連接 API、MCP、瀏覽器和數據庫。 | 繞過登錄、配額、網絡策略和外部服務故障。 |
| 介面 | 在可用 Slot 中展示狀態和交互。 | 穩定控制產品私有 DOM 或未公開介面。 |
| 持久化 | 通過正式存儲外掛保存狀態。 | 讓 Dynamic Plugin 重啟後自動存在。 |
| 安全 | 聲明並遵守權限、審批和執行位置。 | 自行取消審批，或把 Host VM 當安全沙箱。 |
邊界判斷四問
它是否適合所有任務？是否依賴外部系統、存儲或運行時？是否增加上下文、成本或啟動時間？沒有它，基礎 Agent 是否仍能工作？
能力預算
外掛不是越多越好。每項能力都在消耗預算。
少加載
只給當前 Agent 加載相關工具和 Skill。
短輸出
默認給摘要，原始結果按需展開。
留證據
展示調用、來源、成本和最終狀態。
06 · 熱門方向
九個熱門方向，九個小項目起點。
MCP / 連接器
接入一個業務系統，只開放 2–3 個高價值動作。
瀏覽器 / 電腦控制
完成一個帶截圖證據的網頁任務。
代碼智能
按需檢索符號、引用和項目結構。
知識 / 記憶
保存帶來源、時間和作用域的結構化事實。
Workflow / SubAgent
拆分研究、實現、驗收三個角色。
設計到代碼
讀取設計信息，輸出可運行頁面和對比截圖。
GitHub / CI
彙總 PR、檢查 CI，並輸出可追蹤連結。
可觀察性
展示耗時、成本、調用鏈和失敗位置。
語音 / 多模態
把音視頻輸入轉成可檢索、可確認的任務結果。
未來 12–24 個月
未來價值，不在外掛數量，而在可信組合。
現在就能做
以現有外掛機制構建更好的開發與使用體驗。
- inspect 驅動的外掛嚮導
- 摘要輸出與按需展開
- 業務知識 Skill
- 需求到驗收 Workflow
- 成本與調用鏈面板
- 多 Harness 適配層
需要平臺成熟
外掛生態擴大後，需要統一的治理和運行標準。
- 機器可讀權限與副作用
- 認證、兼容性和運行時聲明
- 簽名、來源、撤回和遷移
- 團隊策略與質量評分
- 持久任務和跨 Agent 協作
- 穩定 Slot 與 UI 隔離
不適合先做
這些方向看起來強大，但會快速擴大權限和錯誤成本。
- 默認全權限自動執行
- 保存全部對話為記憶
- 一次加載全部工具
- 直接依賴產品私有 DOM
- 無來源自動更新
- 未經複核寫入生產系統
產品地圖
四個產品，解決的是四種不同層級的問題。
DeepSeek Harness
用 Plugin、Service、Event、Tool、Slot 和 preset 構建自己的 Agent 運行時。強調能力替換、組合、權限和生命週期。
WorkBuddy
面向通用辦公與桌面任務的工作臺。通過 Skill、專家、連接器和 MCP 增加能力，更接近開箱即用產品。
Codex
圍繞本地、IDE、桌面和雲端的軟件開發 Agent。強調代碼工作流、工具、Skill、MCP、Hook、線程與 worktree。
Claude Code
圍繞終端、IDE、Web 與 CI 的工程 Agent。提供 Skill、Subagent、Hook、MCP、Plugin、LSP 與團隊協作機制。
如何選擇
不要問誰更強。先問你要控制哪一層。
01
我要做自己的 Agent 產品
選 DeepSeek Harness。你需要控制服務、事件、狀態、權限、客戶端 Slot 和 Agent 組合。
02
我要完成通用辦公任務
選 WorkBuddy。重點是開箱即用的桌面工作、專家角色和外部服務連接。
03
我要在開發流程中使用 OpenAI Agent
選 Codex。它適合代碼修改、並行任務、工作區隔離和雲端協作。
04
我要深度定製終端工程 Agent
選 Claude Code。它在 Hook、Subagent、Plugin、LSP 和工程自動化方面提供完整組合。
關係，而不是對立
DeepSeek Harness 可以通過外掛連接外部 CLI、MCP 或服務。Codex 與 Claude Code 也可以作為你的開發工具。它們可以位於同一工作流的不同層。
07 · 從想法到交付
把想法變成可交付外掛，只走九步。
寫用戶結果
用一句話說明用戶最終能完成什麼。
縮小第一版
只保留最短、可運行、可觀察路徑。
選外掛類型
Tool、Skill、Event、Service 或組合。
inspect 真實接口
確認註冊表、Slot、Service 和執行位置。
證明最小路徑
先讓外掛加載，再讓一次調用成功。
增加結果證據
輸出文件、連結、截圖、狀態或 diff。
處理生命週期
明確啟動、停止、更新和資源清理。
選擇發佈方式
Dynamic、正式包或 Bundle。
從真實失敗擴展
只有出現具體問題後，再增加複雜度。
最終檢查
交付前，用這張清單驗收。
九項驗收
- 用戶目標清楚
- 調用入口可發現
- 結果證據可複核
- 權限範圍明確
- 上下文開銷可控
- 啟動與停止可觀察
- 持久化策略明確
- 組合位置正確
- 失敗後知道下一步
常見問題
加載了，但模型不調用？
檢查工具是否在當前列表中，description 是否說明使用時機，參數是否過多。
Client 介面不出現？
檢查 Slot、審批、異步啟動狀態，並查看最新 pluginRunId 的診斷。
MCP 在終端能用，桌面不能？
比較 PATH、運行時、環境變量、啟動方式和認證上下文。
工具越多，Agent 反而越差？
減少當前工具集，縮短默認輸出，只按任務加載相關能力。
何時轉正式包？
需要重啟後保留、團隊版本管理、穩定配置、狀態或 preset 時。
最終原則
第一版必須可運行、可觀察、可驗證。穩定之後，再擴大能力。
持續打造
從一個能運行的小外掛開始。
讓你的 AI Agent 多一項真實、可控、可驗證的能力，然後再做下一項。