前言¶

在 DeepSeek Harness（DSH）裏做智能體開發時，若背後接的是 New API 一類網關，常見做法是手寫 HTTP 調用、把 sk- 密鑰和系統訪問令牌塞進對話或環境變量，或在瀏覽器裏反覆切管理後臺。管理接口與 OpenAI 兼容的 /v1/* 認證方式不同，混用容易把 AI 密鑰打到管理路由上。

dsh-plugin-newapi 把網關上的常用操作做成 DSH 一等工具，並在 Web 的 設置 → New API 提供與 CLI 共用的站點與憑據配置。下面介紹它做什麼、如何安裝配置，以及典型調用順序。

這是什麼¶

維護者 zh-Littlebird 在 npm 發佈包名 dsh-plugin-newapi（當前資料版本 1.2.1，MIT）。社區目錄 SkillHub 將其歸類爲 admin-security。

插件定位：把 New API 的站點自檢、模型列表、對話、向量、令牌、渠道、日誌、系統設置，以及覆蓋全部端點族的通用調用入口，封裝爲 9 個 Host 工具；憑據在本機加密存放或走環境變量，模型側只看見「已配置 / 缺失」。通過 dsh.bundle.patch 安裝，不改 Harness 核心，無前端構建步驟，運行時僅依賴 Node.js 標準庫。

核心功能¶

工具與條件註冊¶

未配置網關根地址（baseUrl）時，只有 newapi_site 會註冊到模型上下文；其餘 8 個工具通過 when 條件隱藏，避免每個會話爲不可用工具付出上下文成本。配置完成後，下列工具可用：

認證與安全邊界¶

/v1/* 只使用 sk- 開頭的 AI 密鑰；/api/* 只使用系統訪問令牌，並配合管理頭 New-Api-User。sk- 密鑰不會被髮送到管理接口。

AI 密鑰與訪問令牌由用戶在本機用 CLI 錄入，加密存放在 $DSH_HOME/newapi/credentials.json；工具參數裏不出現明文憑據。返回結果對令牌 key、渠道 key、api_key、access_token、password 等字段統一掩碼；審計日誌記錄動作與路徑，不記錄請求體。

Web 設置頁¶

Host 側半暴露工具，Web 側在 設置 → New API 註冊頁面，讀寫同一份 site.json 與加密憑據庫，並與 newapi_site action="test" 共用自檢邏輯。設置頁經插件自有的 /newapi 迴環路由與宿主通信，僅接受本機地址；無瀏覽器的 headless 部署不會註冊該路由，工具與 CLI 仍可用。

安裝與啓用¶

前置條件¶

• DeepSeek Harness 0.2.2-rc.1 或同系列 0.2.x（engines.dsh: >=0.2.2-rc.1 <0.3.0）
• Node.js >= 22.19（推薦 24）
• 可訪問的 New API 站點；管理接口需要 Admin/Root 賬號的系統訪問令牌

安裝到 profile¶

在 profile 中安裝插件包（也可傳本地目錄絕對路徑，由包管理器建立 link）：

dsh plugin --profile desktop add dsh-plugin-newapi

dsh --profile desktop --dump-config | Select-String newapi

也可在 Web 的 Plugins 頁面安裝，或由 Agent 調用 plugin_manager 的 install_bundle，target 傳包名 dsh-plugin-newapi 或本地目錄絕對路徑。

安裝或更新 Host 插件後需重啓 Harness 進程，新的 newapi_* 工具纔會出現在模型中。

配置¶

用 CLI 寫入站點與憑據（推薦）¶

在自己的終端執行，勿在對話裏向模型發送密鑰。進入插件目錄後：

cd "dsh-plugin-newapi"

node scripts/dsh-newapi.mjs setup --base-url 192.0.2.10:3000 --user-id 1
node scripts/dsh-newapi.mjs set --api-key
node scripts/dsh-newapi.mjs set --access-token
node scripts/dsh-newapi.mjs status

setup 寫入網關根地址（不要帶 /v1 或 /api）；set --api-key 錄入 sk- 密鑰；set --access-token 錄入個人設置 → 安全 → 系統訪問令牌；status 只顯示 available/missing。

默認數據目錄爲 $DSH_HOME/newapi/，含 site.json、credentials.json（AES-256-GCM）、master.key、audit.log 及新建令牌時的一次性明文文件目錄 issued/。可用 --data-dir 或環境變量 DSH_NEWAPI_DATA_DIR 修改路徑。

環境變量與插件鍵¶

也可將配置放進 Harness 進程環境變量：

$env:NEWAPI_BASE_URL = "https://api.example.com"
$env:NEWAPI_API_KEY = "sk-..."
$env:NEWAPI_ACCESS_TOKEN = "..."
$env:NEWAPI_USER_ID = "1"

cordis.patch.yml 中常見項包括：baseUrl、userId、apiKeyEnv（默認 NEWAPI_API_KEY）、accessTokenEnv（默認 NEWAPI_ACCESS_TOKEN）、secretsBackend（auto / env / file / none）、timeoutMs（默認 120000）、maxResponseBytes（默認 8388608）、allowManagementWrites、audit、debug。優先級爲：顯式插件配置 > 環境變量 > site.json。

Web 設置 → New API 可完成與 CLI 等價的網關地址、用戶 ID 與憑據寫入，並支持測試連接；地址末尾的 /v1、/api 等會被自動規範化。

典型用法¶

資料中的推薦順序如下：

newapi_site { action: "test" }
newapi_models
newapi_chat { model: "gpt-4o-mini", messages: [...] }
newapi_tokens { action: "list", keyword: "my-app" }
newapi_tokens { action: "create", name: "my-app-v2", modelLimits: ["gpt-4o-mini"] }
newapi_tokens { action: "delete", id: 7, confirm: true }

先用 newapi_site 自檢網關可達性、管理令牌與 AI 密鑰能否列模型；再用 newapi_models 確認模型名，避免猜錯 gpt-4o 與帶前綴名稱的差異。創建令牌時默認 delivery="file"：完整密鑰寫入 $DSH_HOME/newapi/issued/ 下文件，工具結果只給掩碼與 keyFile 路徑，避免密鑰進入會話記錄。

管理寫操作通過 newapi_raw 時必須 confirm=true，並受 allowManagementWrites 約束；重定向一律拒絕，避免 Authorization 被轉發到其他站點。

適用場景與注意¶

適合在 DSH 會話中需要反覆查詢模型、試對話、管令牌與渠道、看日誌或讀系統選項，又不想每次複製 curl 或暴露密鑰的開發者與運維。也適合希望用 Web 設置頁與 Agent 工具共用一套配置的團隊。

務必注意：插件以當前 dsh 進程的用戶與權限運行，管理寫操作（令牌刪除、渠道測試、newapi_raw 寫請求等）具備與該進程等同的訪問能力。安裝前應閱讀 GitHub 倉庫 源碼與 MIT 許可證，確認符合本機安全策略。DSH 生態強調「一切皆插件」；SkillHub 爲社區目錄，與 DeepSeek / 幻方無官方從屬關係。

排障時可對照資料中的現象表：例如 CONFIG_MISSING 表示缺 baseUrl 或憑據；AI 與管理路由的 HTTP_401 含義不同；「無可用渠道」需結合令牌分組、渠道與 newapi_models 依次覈對。

結尾¶

dsh-plugin-newapi 把 New API 的管理面與推理面拆清認證路徑，用 9 個工具和一個設置頁覆蓋日常網關操作，並在未配置時儘量不佔用模型上下文。進一步瞭解可訪問目錄頁 zh-Littlebird/dsh-plugin-newapi 與源碼 github.com/zh-Littlebird/dsh-plugin-newapi。