dsh-plugin-practice：一個能裝進 profile 的 DSH 插件開發練習倉庫

DeepSeek Harness 插件 dsh-plugin-practice DeepSeek Harness dsh插件 插件開發 Cordis 2026-09-07

前言

DeepSeek Harness（下文簡稱 DSH）的理念是「一切皆插件」：Tool、Config、Service、Event、middleware 最終都要以插件的方式接入。對剛開始接觸插件開發的人來說，難點通常不是缺文檔，而是缺一個把概念串起來、能裝進 profile 跑通、每一步都有可觀察輸出的最小例子。

下面介紹 dsh-plugin-practice。它把插件開發的核心概念拆成六個遞進的小課，代碼按課程逐步累積，本身同時也是一個標準 DSH Bundle，可以用官方命令安裝和卸載。

這是什麼

dsh-plugin-practice 由 Ri0n72Y 維護，定位是用於學習 DeepSeek Harness / Cordis 插件開發的最小練習倉庫，版本 0.1.0。它是 TypeScript 包，通過 prepare 腳本用 tsdown 從 src/ 構建到 lib/。

它解決的具體問題是：每個概念都落成一段可運行代碼，並給出從構建、安裝、啓動到驗證的完整命令鏈；每課都有對應的 Agent 測試語句和預期輸出，學完即可自行驗證。

倉庫裏有兩個 patch 文件，對應兩種加載方式：cordis.patch.yml 供正式 Bundle 使用；cordis.dev.patch.yml 用於 overlay 模式直接加載本地 TypeScript 源碼。

課程內容

當前內容覆蓋六個小課：

Lesson 文件 核心概念
1 src/plugin.ts apply(ctx)、ctx.effect()、disposer、插件生命週期
2 src/workspace-info.ts inject = ['tools']、defineTool()、參數與 canonical output
3 src/configurable-greet.ts Config interface、Schemastery、默認值、運行時配置校驗
4 src/workspace-name-service.ts + src/workspace-name-tool.ts Service Provider、Context declaration merging、Consumer / inject
5 src/workspace-event-* typed Events、ctx.emit()、ctx.on()、松耦合廣播
6 src/workspace-transform-* ctx.waterfall()、next()、around middleware、短路

幾點說明：

  • Lesson 1 的插件運行時每 5 秒輸出一次 [practice-lifecycle] heartbeat，卸載時輸出 disposed，用來觀察 ctx.effect() 註冊的副作用和 disposer 的清理時機。
  • Lesson 3 的 configured_greet 工具使用 Bundle patch 中的 greeting: Hi，對應 Config 默認值與運行時配置校驗。
  • Lesson 4 通過 Context declaration merging 自定義 ctx.workspaceName Service，Provider 與 Consumer 分屬兩個文件。
  • Lesson 6 同時演示 around middleware 的包裝與 block middleware 的短路：輸入 hello 經 uppercase 後返回 HELLO；輸入 blocked words 會在 block middleware 中短路默認處理，最終得到 ** BLOCKED **。

環境要求

1、Node.js ^22.19.0 || >=24.0.0；
2、pnpm（倉庫聲明 pnpm@11.7.0）；
3、本機已安裝可直接執行的 dsh CLI。

先運行下面命令確認 CLI 可用，再進行後面的步驟：

dsh --help

本地開發與一鍵部署

克隆倉庫並安裝依賴：

git clone https://github.com/Ri0n72Y/dsh-plugin-practice.git
cd dsh-plugin-practice
pnpm install

日常開發完成後執行：

pnpm deploy

deploy 在 package.json 中定義爲：

{
  "scripts": {
    "deploy": "pnpm run prepare && dsh plugin --profile practice add ."
  }
}

也就是先用 tsdown 從 src/ 構建出 lib/，再把當前 checkout 安裝或更新進 practice profile。然後啓動 DSH：

dsh --profile practice

如果想先檢查最終組合配置：

dsh --profile practice --dump-config

默認開發 profile 固定爲 practice，需要換名字時直接調整 package.json 中的 deploy script。

用官方命令安裝

pnpm deploy 只是把構建和官方安裝命令串起來，插件安裝和 profile 管理仍然由 DSH 完成。也可以跳過本地步驟，直接安裝 Git 倉庫：

dsh plugin --profile practice add github:Ri0n72Y/dsh-plugin-practice

本倉庫是 TypeScript 包，package.json 提供了 prepare，Git 安裝後會自動從 src/ 構建 lib/。注意 pnpm 10+ 第一次安裝 Git 依賴時，可能需要在 profile 的 pnpm-workspace.yaml 中通過 allowBuilds 授權構建腳本。

能被這樣安裝，是因爲 package.json 按官方約定聲明瞭 Bundle manifest：

{
  "dsh": {
    "bundle": {
      "patch": "./cordis.patch.yml"
    }
  }
}

安裝鏈路是：dsh plugin add 讀取 dsh.bundle 指向的 cordis.patch.yml，patch 再通過包導出路徑加載構建後的 lib/*.js。

源碼開發 / overlay 模式

改源碼時如果不想每次都構建，可以走 overlay 模式直接加載 .ts 文件。先把 cordis.dev.patch.yml 中的 /ABSOLUTE/PATH/TO/dsh-plugin-practice 替換爲倉庫真實絕對路徑，然後運行：

dsh web --patch /ABSOLUTE/PATH/TO/dsh-plugin-practice/cordis.dev.patch.yml

如果是從 DeepSeek Harness 源碼倉庫運行 CLI，則使用：

pnpm dsh web --patch /ABSOLUTE/PATH/TO/dsh-plugin-practice/cordis.dev.patch.yml

安裝後測試

經過上面的步驟部署並啓動後，在 Agent 中逐條測試：

Use the workspace_info tool and tell me the current workspace.
Use configured_greet to greet Ada.
Use workspace_name and return only the workspace name.
Use announce_workspace to announce the current workspace.
Use waterfall_demo with input "hello".
Use waterfall_demo with input "blocked words".

預期行爲：

  • workspace_info 返回當前 DSH Node 進程的 cwd 和目錄名。
  • configured_greet 使用 patch 中的 greeting: Hi，例如返回 Hi, Ada!。
  • workspace_name 通過自定義的 ctx.workspaceName Service 獲取目錄名。
  • announce_workspace 發出 practice/workspace-announced 事件，監聽插件在終端輸出 [workspace-event] announced: <name>。
  • waterfall_demo("hello") 返回 HELLO；waterfall_demo("blocked words") 返回 ** BLOCKED **。
  • 後臺每 5 秒輸出一次 [practice-lifecycle] heartbeat，卸載時輸出 disposed。

六個小課對應的運行時行爲都能直接觀察到。

卸載與常用命令

卸載插件：

dsh plugin --profile practice remove dsh-plugin-practice

常用開發命令：

pnpm run typecheck
pnpm run build
pnpm run check
pnpm deploy

dsh --profile practice --dump-config
dsh --profile practice

適用場景與注意

適合想上手 DSH / Cordis 插件開發的開發者，尤其是希望按 lifecycle → Tool → Config → Service → Event → middleware 的順序把概念過一遍的人。倉庫體量小，主要依賴爲 @deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-tools ^0.1.0-rc.5、@deepseek-ai/schemastery ^3.18.1，適合直接讀源碼。

使用前注意：

1、插件以當前 dsh 進程的權限運行。安裝任何第三方插件前都應先檢查源碼；本倉庫的許可證在抓取的資料中沒有明確聲明（package.json 的 files 中列有 LICENSE 文件），以倉庫實際內容爲準。

2、DSH 仍處於快速迭代階段，如果 API 發生 breaking change，應優先對照官方開發文檔和當前 TypeScript 接口調整，不要假設倉庫代碼始終可用。

3、本文命令統一使用 practice profile；與現有 profile 衝突或需要隔離時，對應調整 deploy script 及安裝命令中的 --profile 參數。

結尾

dsh-plugin-practice 的價值在於「可運行」：每個概念對應一段源碼、一條測試語句和一份預期輸出，學習路徑閉環。如果你在找 DSH 插件開發的第一個練手項目，可以從它開始。

  • 社區目錄頁（獨立站點，與 DeepSeek / 幻方無官方從屬關係）：https://www.skillhub.cn/plugins/Ri0n72Y/dsh-plugin-practice
  • GitHub 倉庫：https://github.com/Ri0n72Y/dsh-plugin-practice

相關文章

使用 DSH-better-sidebar 爲 DeepSeek Harness 網頁界面增加側邊欄工作臺 2026-08-17 使用 dsh-balance-monitor 在 DeepSeek Harness 側邊欄查看餘額與今日花費 2026-08-18 一句話拉起 Agent 團隊：DeepSeek Harness 插件 dsh-agent-teams 上手 2026-08-25 粘貼圖片就能看圖：DeepSeek Harness 視覺插件 dsh-vision-toolkit 上手 2026-08-25 dsh-at-file：在 DeepSeek Harness 輸入框裏用 @ 引用工作區文件 2026-08-25
羽毛球分组比赛记分
小程序二维码

欢迎使用《羽毛球分组比赛记分》微信小程序

小夜