前言¶
DSH 的理念是「一切皆插件」，跨機器部署時各個插件各司其職。dsh-memex 負責卡片，dsh-cockpit-bridge 負責端口轉發，這兩端平時互不引用。問題在於：當 dsh-memex 跑在另一臺機器上時，它頁面上的「打開卡片」按鈕會把瀏覽器指向一個 localhost 地址，而那個地址並不屬於 memex 所在的機器，於是點下去打不開。
下面介紹的這個插件就是爲這個縫隙而生的部署側適配層。
這是什麼¶
dsh-cockpit-memex-browse-shim 由 prgrmrwy 維護，定位是「從 dsh-cockpit-bridge 端口發佈到 dsh-memex 瀏覽地址註冊表的部署本地適配器」。它把 bridge 的端口轉發註冊到 memex 通用瀏覽地址擴展裏，讓「打開卡片」按鈕改用 bridge 發佈的轉發地址，使卡片瀏覽器在真正能到達該設備的地址上打開。
它是唯一的部署側耦合點：兩端源碼和依賴互不引用，裝上 shim 才接線，移除 shim 即解耦。當前版本 0.2.0，源碼在 ohmydsh 倉庫的 packages/cockpit-memex-browse-shim 下維護，GitHub 上的 prgrmrwy/dsh-cockpit-memex-browse-shim 是發佈鏡像，以 MIT 許可證發佈。社區目錄將其歸入「工作流」分類。
核心功能與工作方式¶
1、讀取 cockpitBridge.forwards 端口轉發服務。要求 bridge >= 0.6.1（正式部署 pin 0.6.4），舊 portForward / channel register / publish 契約不再支持。
2、註冊到 dshMemex.browseAddress 註冊點。無頂層 inject，各服務通過完整 dotted name 單次 ctx.get() 讀取，因此兩端加載順序無關。
3、按端口單飛申請：調用 acquire(devicePort, holder)，holder 裏帶隨機綁定標識，避免舊綁定遲到釋放影響新綁定。
4、就緒等待：starting/retrying/paused 通過 onChange 等 ready，最長 15 秒；只交付當前 handle.address.url，不緩存 URL，不自行重試。打開後保留 holder，避免標籤頁剛打開隧道就被回收。
5、失敗語義收得很緊：只有結構化 CockpitForwardsError 且 code === 'local-device' 纔回落 http://localhost:<port>；unavailable 這類無法證明瀏覽器與設備同機的錯誤，連同網絡和業務失敗一樣原樣上拋，用戶仍可直接使用已知設備地址。
6、生命週期：從未發現 bridge 的 memex-only 部署保持默認本機行爲；發現 bridge 後再卸載或替換，取消等待並釋放舊句柄；bridge 消失期間保留失敗關閉（fail-closed）resolver，防止遠端地址悄悄回落瀏覽器 localhost；記憶端卸載或 shim dispose 時註銷 resolver。
適用場景¶
適合同時裝了 dsh-cockpit-bridge 和 dsh-memex，且希望跨機器用統一轉發地址打開卡片的場景。當不再通過 dsh-cockpit 跨機器打開卡片，或任一端原生提供該集成時，即可移除：刪除 manifest 條目 → dsh build → 重啓，兩端無需遷移。回滾舊版 shim 時必須把 bridge 一起回滾到提供舊服務的版本，不要把 0.1.1 shim 和 bridge 0.6.x 混用。
安裝與啓用¶
安裝它需要與兩端同機：dsh-cockpit-bridge（GitHub Release tarball）和 dsh-memex。
dsh plugin --profile web add https://github.com/prgrmrwy/dsh-cockpit/releases/download/dsh-cockpit-bridge-v0.6.4/dsh-cockpit-bridge-0.6.4.tgz
dsh plugin --profile web add dsh-cockpit-memex-browse-shim
先安裝 bridge 的 tarball，再裝 shim。隨後重啓 DSH web 生效。卸載用：
dsh plugin --profile web remove dsh-cockpit-memex-browse-shim
驗證與注意¶
作者提供了獨立 package 的 test / typecheck / build；集成迴歸用 memex 真實的 registry（未接線默認返回 localhost），而非會掩蓋誤路由的假 registry，覆蓋就緒等待、併發、地址變化、移除、失敗分類和服務生命週期。
兩點提醒：插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證（本插件爲 MIT，且依賴 @deepseek-ai/cordis ^4.0.4、Node >= 22.19）；它是連接兩個既有插件的薄適配層，不要單獨在沒有 bridge 的機器上裝，否則行爲等同於沒裝。
鏈接¶
- 目錄頁：https://www.skillhub.cn/plugins/prgrmrwy/dsh-cockpit-memex-browse-shim
- GitHub：https://github.com/prgrmrwy/dsh-cockpit-memex-browse-shim
