前言¶

在 DSH 裏做智能體或日常對話，模型調用往往走各自配置的提供方；若團隊已經部署星橋（StarBridge）這類 AI 中臺，還需要在 DSH 側單獨接網關地址、憑據，並區分「工具調用」和「整輪對話是否經中臺」。下面介紹社區插件 dsh-starbridge-client（維護者 LiHeng99）：在一個 profile 裏安裝後，提供統一網關接入、設置頁填地址或平臺賬號登錄、對話 / 反饋 / 知識庫相關工具，以及 Web UI 面板；可選打開「模型路由」，讓 DSH 的每一次 AI 調用都經星橋 OpenAI 兼容面。插件公開發布，出廠不含任何一家的網關地址或憑據。

這是什麼¶

dsh-starbridge-client 是星橋 AI 中臺的 DSH 客戶端類組合包（bundle）：同時提供 host 面（lib/index.js：服務、HTTP 路由、認證、工具實現）和 client 面（lib/client.js：對話面板、設置頁、反饋條）。分工是 host 負責網絡、認證、重試與流式解析，client 只做展示；瀏覽器不持有 access token，也不直接訪問網關。

• 目錄頁：https://www.skillhub.cn/plugins/LiHeng99/dsh-starbridge-client
• 源碼與說明：https://github.com/LiHeng99/dsh-starbridge-client
• 許可證：MIT（見倉庫 package.json）
• 當前資料中的版本：0.1.0

核心功能¶

接入與憑據¶

唯一推薦入口是 Web UI 「設置 → 星橋 StarBridge」，無需手改配置文件即可完成：

1. 填服務地址：支持服務根、/starbridge、/starbridge/gw、/starbridge/gw/v1 等粘貼形式，頁面會規範化並展示機器面與模型面地址。
2. 二選一登錄：
   - 訪問密鑰：中臺簽發的 Access Key，寫入 DSH 憑據庫（引用名 STARBRIDGE_GATEWAY_API_KEY），重啓後從同一引用讀取。
   - 平臺賬號：控制台賬號密碼登錄，換取平臺 JWT；勾選「在本機記住」時憑據 AES-256-GCM 加密落盤（$DSH_HOME/starbridge-gateway-session.enc 等），到期前自動續期。
3. 模型路由開關：打開後把 llm-pi-ai 的 starbridge 路由 baseURL 指向 <地址>/gw/v1，憑據寫入該路由的 apiKeyEnv，默認模型切到 starbridge / general；關閉則退回 DSH 當前默認提供方。

未配置網關時，starbridge_* 工具會返回 [GATEWAY_NOT_CONFIGURED] 並提示去設置頁填寫，而不是隻在日誌裏失敗。

非機密接入信息落在 $DSH_HOME/starbridge-gateway.json；密鑰優先可通過環境變量注入（見下文「配置」）。

四個 host 工具¶

需要模型能繞開的失敗（未登錄、網關不可達等）以 { ok: false, error } 返回，錯誤文本帶 [CODE] 與 Hint，便於模型轉述給用戶。

Web UI¶

client 面註冊對話面板（流式 + Markdown + 代碼高亮）、設置分節與反饋條；樣式使用 DSH 設計令牌（--dsw-alias-* 等），跟隨明暗主題，不單獨配色。

模型面（可選）¶

除工具面外，組合層通過 cordis.patch.yml 爲 @deepseek-ai/dsh-llm-pi-ai 聲明 starbridge 手工網關路由（OpenAI Completions API，不寫死 baseURL）。用戶在設置頁打開模型路由後，對話、子代理、摘要、標題生成等每一次模型調用都可經中臺；model 字段表示場景（如 general），具體上游由中臺路由規則決定。

安裝與啓用¶

在目標 profile（資料示例爲 web）安裝：

# 插件市場「設置 → 插件市場」一鍵安裝，或：
dsh plugin --profile web add dsh-starbridge-client

# 本地開發從目錄安裝（profile 內建立 pnpm 鏈接）：
dsh plugin --profile web add ./dsh-starbridge-client

# 查看組合是否包含該 bundle（無需啓動服務）：
dsh --profile web --dump-config | grep -A 20 starbridge

# 重啓 profile
dsh web

dsh plugin add 會把包加入 profile 依賴，並將聲明瞭 dsh.bundle 的包追加到 dsh.profile.bundles，其 cordis.patch.yml 成爲組合層的一層。

裝完後尚未連接任何網關：在 設置 → 星橋 StarBridge 填一次地址並完成憑據或登錄後，工具與（若開啓）模型路由纔可用。

運行環境要求（倉庫 package.json）：Node ^22.19.0 || >=24.0.0；peer 依賴含 @deepseek-ai/cordis、@deepseek-ai/dsh-tools、@deepseek-ai/schemastery 等，由 DSH profile 組合提供。

配置要點¶

部署參數在 Config Schema 中，均有默認值。除設置頁外，還可：

1. 在 profile 的 $DSH_HOME/profiles/<profile>/cordis.patch.yml 覆蓋單行配置；
2. 用環境變量注入（推薦用於密鑰）：STARBRIDGE_GATEWAY_URL、STARBRIDGE_GATEWAY_API_KEY、STARBRIDGE_OIDC_ISSUER_URL、STARBRIDGE_OIDC_CLIENT_ID、STARBRIDGE_OIDC_CLIENT_SECRET、STARBRIDGE_USER_ID、STARBRIDGE_DEPARTMENT 等。

常用字段摘要：

若啓用 OIDC SSO，網關側需註冊 Public client + Authorization Code + PKCE，回調爲 http(s)://<dsh-host>/starbridge/api/login/complete（可用 STARBRIDGE_REDIRECT_URI 指定）。

典型用法¶

智能體通過工具訪問中臺¶

模型在對話中可調用 starbridge_chat 向星橋發消息，或用 starbridge_kb_query 查知識庫；接入狀態與保存配置可用 starbridge_gateway 的 status / save / use_access_key / login / route_models 等 action（具體參數見倉庫 README「工具」一節）。

整 profile 模型走星橋¶

在設置頁完成地址與憑據後，打開「模型路由」。之後 DSH 默認模型指向 starbridge / general，無需爲每次對話再手動指定網關。

從源碼構建（維護者 / 二次開發）¶

npm install
npm run build          # build:host + build:client
npm run verify         # 離線冒煙（資料稱 228 項檢查）

安裝到 profile 前，host 的 tsc 與 client 的 tsdown 均需產出 lib/index.js、lib/client.js。

適用場景與注意¶

適合誰：已在組織內部署星橋網關、希望在 DSH Web profile 裏用統一設置頁接入，並可選讓全部 LLM 調用經中臺審計與路由的團隊或個人開發者。

權限與安全：插件與當前 dsh 進程同一權限運行，會讀寫 $DSH_HOME 下網關配置與加密會話文件，並向用戶配置的網關發起請求。安裝前應閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認網關地址與憑據來源可信；生產環境優先用環境變量注入密鑰，避免明文落盤。

生態說明：DSH 採用「一切皆插件」的擴展方式；SkillHub 目錄頁 是社區插件索引，與 DeepSeek / 幻方無官方從屬關係。

結尾¶

dsh-starbridge-client 把星橋的網關接入、登錄、工具與 Web 面板收進一個 bundle，並可選接管模型路由，適合要把 DSH 接到自有 StarBridge 中臺的場景。進一步細節以倉庫 README 爲準：

• 目錄：https://www.skillhub.cn/plugins/LiHeng99/dsh-starbridge-client
• GitHub：https://github.com/LiHeng99/dsh-starbridge-client