DeepSeek Harness 外掛開發教學：寫你的第一個 dsh 外掛

dsh 外掛到底是什麼

一個 DeepSeek Harness 外掛就是一個 Cordis 外掛。Cordis 是 Harness 底層的元框架，只負責外掛的載入、卸載與依賴關係；Harness 的每個具體元件——工具、儲存、策略、主迴圈、UI 面板——都是不同的 Cordis 外掛，外掛之間透過服務與事件協作。

這是理解 dsh 外掛的第一要義：外掛不是「附加元件」，它可以替換或擴充代理的任意部分：

• 幫模型加一個能自主呼叫的工具（標題生成、資料庫連接……）
• 換掉系統提示詞，甚至換掉整個主迴圈
• 攔截工具執行，做審批、記錄、改寫
• 註冊新的 UI 面板、狀態列或皮膚
• 提供沙箱後端或新的模型供應商

先記住幾個官方錨點：

• npm 套件名：@deepseek-ai/dsh
• CLI 指令：dsh（安裝 npm install -g @deepseek-ai/dsh，執行 dsh --profile web）
• 社群外掛的 GitHub 官方指定 topic：dsh-plugin
• 底層框架：Cordis

能力接縫：服務、提供方、消費方

每種能力（執行指令、讀寫檔案、網路存取、模型呼叫、沙箱隔離）都被拆成三個相互獨立的角色：

1. 服務（Service） —— 介面規範；
2. 提供方（Provider） —— 具體實作；
3. 消費方（Consumer） —— 使用該能力的一方。

三者解耦，模型看到的介面恆定不變。想換搜尋引擎？註冊另一個提供方就行，消費方和模型毫無感知。社群外掛之所以能換掉 Harness 這麼多部件，靠的就是這套接縫。

外掛樹

執行中的 dsh 是一棵外掛樹，由多層設定按固定順序疊加：Bundle（官方成套設定）→ Profile（你的具名組裝清單）→ Patch（你的覆蓋層，可定位到單個外掛條目），上層覆蓋下層。外掛被卸載時，它註冊的一切自動撤銷——註冊必須是可逆副作用，這是硬性約定。

一個最小外掛的骨架

每個外掛是一個函式（或帶生命週期鉤子的物件），接收一個 Cordis context，宣告自己提供什麼、消費什麼。概念骨架長這樣：

import { Context, Service } from '@cordisjs/core';

export const name = 'my-plugin';

// 1. 外掛提供的服務
export class Greeting extends Service {
  constructor(ctx: Context) {
    super(ctx, 'greeting');
  }

  hello() {
    return 'hello from my-plugin';
  }
}

// 2. 外掛本體
export function apply(ctx: Context) {
  ctx.provide('greeting', new Greeting(ctx));

  // 3. 回應事件——例如代理啟動時
  ctx.on('agent/start', () => {
    ctx.logger.info('my-plugin loaded');
  });
}

Harness 目前是 v0.1、介面在快速迭代，上面的程式碼看「形狀」即可，別當契約用。動手前務必以官方文件和 plugin-template 倉庫的最新慣例為準。

官方倉庫強制執行的工程慣例

官方倉庫的自動化門禁把一套規則寫成了硬約束，你的外掛值得照抄：

• 註冊必須是可逆副作用 —— 卸載不留殘餘；
• 設定錯誤必須在載入時報錯，不能靜默跳過；
• 跨邊界識別符用品牌型別（branded types），不讓裸字串在各層之間洩漏；
• 隨部署變化的參數放進設定，不寫死。

品質門禁同樣硬核：原始碼目錄逐檔案 100% 單元測試覆蓋率、無 API Key 也能跑的快照回放測試、真實 API 端到端測試、跨檔案程式碼複製偵測、文件與程式碼同步檢查（文件過期直接阻斷 CI）。

不同能力往哪裡插

看你做什麼，接縫位置不同：

• 工具 —— 註冊模型可呼叫的工具，與內建工具走同一條管線（審批、守衛、記錄全生效）；
• Agent 事件 —— turn/start、step/start、工具執行前後、模型請求前後的鉤子；
• UI —— Web UI 本身就是第二棵外掛樹：頁面先宣告側邊欄、對話區、輸入區、設定區等掛載位，外掛把自己的元件註冊進去；
• 儲存 / 會話 —— 替換會話與記錄的持久化方式；
• 沙箱 / 模型 —— 提供自己的沙箱後端或模型適配器（任意 OpenAI 相容端點均可）。

發佈與收錄

1. 把外掛推到公開的 GitHub 倉庫；

2. README 寫清楚：一句話說明、安裝方式、（最好還有）它需要存取什麼；

3. 幫倉庫加上 dsh-plugin topic —— 它是官方指定的社群標記，其他工具和目錄靠它發現外掛；

4. 向我們的 awesome 清單提 PR —— 這是本站的唯一資料來源：

   • cccakeee/awesome-dsh-plugins —— 在對應分類標題（中英文均可）下加一行。

5. 有 npm 套件的話，掛到 registry 類索引上，讓 dsh 工具鏈能直接發現。

合併後，本目錄會在下一次同步時自動收錄（同步機制見生態盤點）。

最後一句提醒

外掛是以代理權限執行的程式碼。安裝別人的外掛前，讀原始碼、查授權條款、看要什麼權限，先在隔離工作區裡試用；你自己發佈的外掛，也應該如實說明它會讀什麼、寫什麼、往網路上發什麼。

繼續探索

• dsh 外掛安裝教學 —— 安裝行的另一頭
• dsh 外掛是什麼？ —— 你要建構之物的使用者視角
• Profile、Patch 與 Preset —— 你的外掛落在外掛樹的哪一層
• 沙箱、審批與金鑰 —— 外掛接入的安全模型
• 提交外掛 —— 完整的收錄清單