dsh-kubejs：以腳本包定製已安裝 DSH 插件

在 DeepSeek Harness（DSH）的插件生態中，修改現有插件通常意味着直接編輯其源碼，這會導致版本更新後修改失效、改壞拖垮啓動等風險。dsh-kubejs 引入了 KubeJS 的核心模式：將修改邏輯剝離到獨立的腳本包中，通過聲明式配置讓腳本作用於已安裝的插件，而不觸碰插件源碼。

核心功能¶

dsh-kubejs 自身是普通 DSH 插件，負責加載腳本；腳本存放在獨立目錄，與插件代碼完全隔離。

修改者與修改分離¶

腳本集中放在獨立目錄，與插件代碼完全隔離，插件更新或重裝不會丟失修改。修改邏輯通過 activate(api) 導出，作用於已存在的東西。

目標插件依賴管理¶

腳本按目標插件分包，通過 manifest.json 聲明依賴。若目標插件未安裝或版本失配，整包禁用並報警，絕不靜默失效。

配置覆寫賬本¶

通過 api.config.override 寫入配置，所有變更記錄在 cordis.patch.yml 的託管區塊中，支持精確摘除。同一插件實例分多次寫不同路徑是累加而非覆蓋。

五大 API 原語¶

腳本通過 activate(api) 獲得五個原語：

api.on(event, handler)：事件鉤子（真實掛在宿主 cordis 事件上）。
api.slot(id, props, Component)：向 client 槽位註冊 UI 組件。
api.config.override(path, value)：配置覆寫。
api.service.wrap(name, wrapper)：服務包裝（洋蔥式）。
api.fetch.wrap(matcher, handler)：全局 fetch 攔截（洋蔥式）。

管理面板與工具集¶

提供管理面板瀏覽腳本包狀態、失配紅標、執行狀態與配置賬本。同時提供四個專用工具：kubejs_inspect、kubejs_write_script、kubejs_reload、kubejs_check。

安裝¶

在 DSH Desktop 的「插件」面板中輸入以下任一地址安裝：

github:YuMo-233/dsh-kubejs

或直接填倉庫地址 https://github.com/YuMo-233/dsh-kubejs。官方安裝器會自動完成拉包、bundles 登記、cordis.patch.yml 註冊，裝完重啓即可。

典型用法¶

事件鉤子¶

export function activate(api) {
    // 只看不動：返回 undefined 就是完全透傳，絕不干擾 DSH
    api.on('agent/pre-step', (payload) => {
        api.log.debug('當前步:', payload.step);
    });

    // 改決策：一定要先 await next() 拿到宿主的內建決策，再 spread 它
    api.on('agent/pre-step', async (payload, next) => {
        const decision = await next();          // { kind: 'enter', messages: [...] }
        return { ...decision, delayHint: 800 };
    });
}

fetch 攔截¶

export function activate(api) {
    api.fetch.wrap({ urlIncludes: '/v1/chat/completions' }, async (request, next, helpers) => {
        // 把「整條請求一刀切超時」換成「沒字節流動才超時」的看門狗
        const idle = helpers.createIdleSignal({ firstByteMs: 60_000, idleMs: 300_000, upstream: request.signal });
        request.init.signal = idle.signal;

        const res = await next();                          // 返回 undefined 則由框架代發
        return helpers.wrapResponseBody(res, idle.pulse, idle.dispose);
    });
}

熱重載¶

kubejs_reload 即時生效（無需重啓），用於修改事件鉤子、配置覆寫或 fetch 攔截規則。

使用注意事項¶

鉤子與決策¶

不擁有決策就返回 undefined（透傳），別自造對象——自造會頂掉宿主的內建決策字段。
想改就先 await next()，再 spread 它的返回值。
鉤子是異步的，handler 可以是 async；慢 handler 會拖慢事件。
api.ctx 全量直通（讀或改場景），但想造新東西時請寫成獨立插件。

腳本約束¶

腳本不能造新接入點（provide 新服務/註冊新工具/新路由）。
client 腳本不能 import/export（只能用 require()）。
manifest.json 不能帶 BOM（會導致解析失敗）。
腳本必須用 ESM 導出 activate（寫成 CJS 會靜默失效）。
標記行必須是註釋，以 # 開頭（寫在 cordis.patch.yml 中）。

價值總結¶

dsh-kubejs 允許開發者在不修改插件源碼的情況下，通過獨立腳本包對已安裝插件進行定製。這種模式解決了直接改插件導致的版本更新丟失、改壞拖垮啓動以及修改散落難以審查的問題。腳本按目標插件分包，配合配置覆寫賬本和熱重載機制，提供了安全、可回滾的修改能力。

瞭解更多或獲取源碼，請訪問 GitHub 倉庫。