前言¶
DeepSeek Harness（DSH）採用模塊化插件架構。在集成 pi-ai 模型時，認證流程通常需要 OAuth 支持。現有的基礎集成僅註冊協議和憑據記錄，缺乏直觀的交互界面和命令行管理手段。dsh-bundle-pi-ai-auth 插件爲 pi-ai 提供者添加了 Model 設置頁面的 Provider-card UI 控件，並保留 /auth-* 命令作爲 fallback，用於管理 OAuth 能力、啓用狀態和登錄狀態。
核心功能¶
此插件在 DSH 的 Web 或 Desktop 端提供以下能力：
- Provider-card OAuth 控制：在 Models 設置頁面，爲每個支持 OAuth 的 pi-ai 提供者顯示授權狀態和操作按鈕。
- Models settings UI 集成：提供 “Sign in” 和 “Sign out” 按鈕。點擊 Sign in 會啓動提供者流程，打開系統瀏覽器並顯示設備代碼或後續問題。
- 命令行回退：提供一組
/auth-*命令，用於手動管理提供者。 - 狀態管理：分離管理 OAuth 能力、啓用狀態和登錄狀態，不自動創建臨時 token 環境變量。
- 憑據清理：登出操作僅刪除本地憑據記錄，不撤銷遠程授權。
安裝與啓用¶
安裝前需確保環境滿足依賴要求。此插件依賴 @deepseek-ai/dsh-llm-pi-ai，需要 DeepSeek Harness 0.1.7-rc.2 或兼容的 0.1.x 版本。此外，Web/Desktop 組合需包含 authorization、credentials、settings、llm-pi-ai、Remote gateway 和 Models settings UI 組件。
在 Web 端安裝插件：
dsh plugin --profile web add github:dingyiliao/dsh-bundle-pi-ai-auth
安裝後重啓應用，在 Settings → Models 中添加提供者，然後使用提供者卡片上的 Sign in 操作。
典型用法¶
命令行操作¶
插件提供以下命令用於狀態檢查和操作：
- 列出狀態：
/auth-list- 查看所有支持 OAuth 的提供者及其啓用和登錄狀態。 - 添加並登錄：
/auth-add [provider]- 添加提供者並立即登錄。省略 provider 參數會觸發選擇提示。 - 登錄已啓用提供者：
/auth-login [provider]- 僅對已啓用的提供者執行登錄。 - 檢查狀態：
/auth-status [provider]- 檢查特定提供者的詳細狀態。不指定 provider 時等同於/auth-list。 - 登出：
/auth-logout [provider]- 移除本地憑據但保留提供者啓用狀態。 - 移除提供者：
/auth-remove [provider]- 移除用戶添加的提供者及其本地憑據。
UI 操作¶
在 Models 設置頁面，找到支持 OAuth 的提供者卡片：
1. 點擊 Sign in。系統會啓動授權流程，彈出模態框顯示設備代碼或後續問題。
2. 在系統瀏覽器中完成登錄後，憑證將保存至本地。
3. 點擊 Sign out 可刪除本地憑證。
適用場景與注意¶
- 依賴關係：此插件不實現 OAuth 協議，也不存儲和刷新 token。它僅作爲交互層，依賴
@deepseek-ai/dsh-llm-pi-ai處理底層邏輯。 - 手動啓用：安裝插件不會自動啓用任何提供者。用戶必須先在 Models 設置中添加提供者，然後才能進行登錄。
- UI 限制：對於純 OAuth 提供者，核心 Models UI 可能仍顯示通用的 API Key 編輯器，因爲此插件不通過 CSS 遮蔽核心 UI。
- 登出行爲：登出僅移除本地記錄，不會撤銷遠程的授權 grant。
- 依賴組件：必須安裝包含
authorization、credentials、settings、llm-pi-ai、Remote gateway 和 Models settings UI 的完整 DSH 環境方可正常工作。 - 提供者衝突：如果提供者是由其他 bundle 的基礎配置啓用的，不能通過
/auth-remove移除，需更新該 bundle。
總結¶
dsh-bundle-pi-ai-auth 補全了 pi-ai 集成在 DSH 中的交互短板。它通過 UI 卡片和命令行工具，讓開發者能夠更方便地管理 OAuth 提供者的啓用、登錄和登出狀態，而無需直接操作底層協議。
