前言¶
在 DSH 的「一切皆插件」思路下，插件開發不只是寫一個 apply() 函數。更常見的問題是：依賴是否正確、配置是否能驗證、註冊是否能撤銷、服務是否能替換、模型可見內容是否能回放、測試是否覆蓋真實裝配路徑。
deepseek-harness-plugin-from-scratch 圍繞這些問題給出一套代碼審計後的漸進教程，並提供一個可以安裝、運行和逐步閱讀的 TypeScript 插件。
這是什麼¶
這是一個由 Opr4Mp3r 維護的非官方社區教程倉庫，項目採用 MIT License。
它面向想讀懂 DSH 插件裝配路徑的開發者，重點是生產級插件需要的檢查點：配置可驗證、註冊可撤銷、服務可替換、模型可見內容可回放、測試覆蓋真實裝配路徑。
倉庫當前尚未發佈到 npm registry。Harness 處於預發佈階段；上游在首個正式 tag 前明確不承諾兼容舊格式。
核心功能¶
下面介紹倉庫提供的能力：
- 可安裝、運行和逐步閱讀的 TypeScript 插件。
- 提供
greet-tool工具及cordis.patch.yml組合層。 - 提供
pnpm smoke:source、pnpm smoke:loader、pnpm check等本地驗證命令。 - 提供
pnpm preview本地交互閱讀器。 - 用真實裝配路徑覆蓋測試與發佈檢查。
本地運行與閱讀¶
環境要求是 Node.js ^22.19.0 或 >=24，以及 pnpm 11。審計和本地鎖定環境是 Node.js 22.21.1、pnpm 11.7.0。
先安裝依賴並執行本地驗證：
pnpm install --frozen-lockfile
pnpm smoke:source
pnpm smoke:loader
pnpm check
pnpm smoke:source 和 pnpm smoke:loader 用於本地驗證源碼與加載路徑，pnpm check 執行更完整的檢查。
啓動本地閱讀器：
pnpm preview
打開 http://127.0.0.1:4175，可以按章節閱讀插件代碼。
安裝進 Harness profile¶
由於當前倉庫尚未發佈到 npm registry，可以先從源碼生成 tarball，再安裝到 tutorial profile：
pnpm pack
dsh plugin --profile tutorial add ./deepseek-harness-plugin-from-scratch-0.1.0.tgz
安裝後檢查配置層：
dsh --profile tutorial --dump-config
這條命令用於確認 deepseek-harness-plugin-from-scratch 插件在 profile 中的配置層。
需要注意：如果缺少 dsh.bundle.patch 指向的 cordis.patch.yml，dsh plugin add 只會安裝普通依賴，不會激活插件。
如果要在該 profile 的 cordis.patch.yml 中覆蓋插件配置，patch 不會深度合併 config，因此覆蓋配置時相關字段都要重述。下面示意這種配置覆蓋方式：
- id: greet-tool
config:
# 需要重述要覆蓋的配置字段
完整安裝路徑檢查¶
倉庫提供一條獨立檢查命令，用於執行完整安裝路徑：
pnpm check:profile
這條命令會執行打包、dsh plugin add、配置層檢查、啓動 profile 並調用 greet。
GitHub 安裝與構建限制¶
倉庫中也給出從 GitHub commit 安裝的形式：
dsh plugin --profile tutorial add 'github:Opr4Mp3r/deepseek-harness-plugin-from-scratch#FULL_COMMIT_SHA'
這裏 FULL_COMMIT_SHA 是佔位符，需要替換爲具體 commit SHA。由於該安裝路徑可能觸發構建，且 pnpm 10 及以上可能要求加入 allowBuilds，如果希望避免在安裝時執行構建，可以使用前面的預構建 tarball 安裝方式。
適用場景與注意¶
適合以下情況：
- 想讀懂 DSH 插件的依賴、註冊、服務和回放路徑。
- 想用一個可運行的 TypeScript 插件對照真實裝配路徑。
- 想在本地先做
smoke、check、preview，再決定是否安裝進 profile。
需要注意：
- 插件會以當前 dsh 進程權限運行；安裝前應檢查源碼、依賴和許可證。
- 該倉庫是 MIT License 的非官方社區教程。
- Harness 處於預發佈階段；上游在首個正式 tag 前明確不承諾兼容舊格式。
- 當前倉庫尚未發佈到 npm registry；安裝路徑以倉庫給出的 tarball 或 GitHub commit 爲準。
- 從 GitHub commit 安裝時，注意佔位符、commit 選擇和 pnpm 構建限制。
結尾¶
這個倉庫的價值在於把 DSH 插件開發從“函數怎麼寫”推進到“插件如何被真實裝配、驗證和回放”。如果要繼續看源碼，可以從 GitHub 倉庫開始。
GitHub 倉庫：
https://github.com/Opr4Mp3r/deepseek-harness-plugin-from-scratch
