dsh-consult：DeepSeek Harness 的跨供應商第二意見服務

前言¶

DeepSeek Harness (DSH) 提供了構建智能體的底層能力。在開發和調試過程中，獲取跨供應商的模型輸出、驗證路由邏輯或進行審計是常見需求。dsh-consult 是一個位於本地的輔助插件，它爲 DSH 提供了跨供應商的“第二意見”服務，同時提供了一個 OpenAI 兼容的本地 API 端點，讓外部 Harness（如 ZCode）也能調用輕量級的顧問功能。

它區別於被動式的 dsh-advisor，是一個主動的諮詢工具。

核心功能¶

該插件主要提供以下能力：

DSH_MODEL 直選模型：通過環境變量或配置改道，強制指定模型進行諮詢，不受用戶層 settings.yaml 中的默認模型壓制。
OpenAI 兼容端點：在 127.0.0.1:3080 提供標準的 POST /v1/chat/completions 接口，支持 SSE 流式和非流式響應，以及結構化輸出。
consult 工具：註冊給所有 agent，用於在會話中主動請求跨供應商的意見。
scout 調查模式：結合官方模型與實時 Web Search，用於解決人類和模型都無法處理的難題。
結構化輸出：默認要求 JSON 格式的 {recommendation, reasons, confidence, risks, alternatives}，支持 json_schema 約束。
上游溯源與審計：響應頭標註上游模型，審計日誌落盤至 audit.jsonl，記錄調用耗時與路由信息。

安裝與啓用¶

安裝步驟需要手動克隆倉庫並修改 profile 的配置文件。

克隆倉庫：

    git clone https://github.com/1339190177/dsh-consult ~/.dsh/local-plugins/dsh-advisor

修改 Profile 配置：
進入 DSH 的 web 和 headless profile 目錄，編輯 package.json，添加依賴和 bundle 引用：

    // ~/.dsh/profiles/web/package.json
    {
      "dependencies": {
        "dsh-advisor": "file:../local-plugins/dsh-advisor"
      },
      "dsh": {
        "profile.bundles": ["dsh-advisor"]
      }
    }

    // ~/.dsh/profiles/headless/package.json (同上結構)

安裝依賴：
分別在 web 和 headless 目錄下運行：

    cd ~/.dsh/profiles/web && pnpm install
    cd ~/.dsh/profiles/headless && pnpm install

web profile 重啓 `dsh web` 後生效，headless 每次運行即時生效。

配置說明¶

安裝完成後，需要在配置文件中啓用 HTTP 端點並設置認證 Token。

Bundle 層配置（cordis.patch.yml）：

- id: dsh-advisor
  name: 'dsh-advisor'
  config:
    httpEnabled: true   # 關閉後僅保留 consult 工具

用戶層配置（~/.dsh/settings.yaml）：

advisor:
  token: dsha_...      # 首次啓動自動生成，用於 HTTP 認證
  route:               # 可選：固定 consult 的默認路由
    provider: deepseek
    model: deepseek-v4-flash

使用方式¶

插件提供了多種調用方式。

1. CLI 模式（Headless）¶

通過環境變量 DSH_MODEL 指定模型，直接在命令行調用。

# 直選模型並諮詢
DSH_MODEL=deepseek/deepseek-v4-flash dsh --profile headless "問題"

# 驗證配置與選擇一致
DSH_MODEL=deepseek/deepseek-v4-flash dsh --profile headless --dump-config

2. HTTP API 模式¶

使用標準的 OpenAI 格式調用本地端點。

curl -X POST http://127.0.0.1:3080/v1/chat/completions \
  -H 'content-type: application/json' \
  -H 'authorization: Bearer dsha_...' \
  -d '{"model":"deepseek/deepseek-v4-flash","messages":[{"role":"user","content":"…"}]}'

支持流式 ("stream":true) 和結構化輸出 (response_format: json_schema)。

3. Scout 調查模式（多模態）¶

腳本 ask_advisor.sh 支持圖片輸入和 Web Search。

bash ask_advisor.sh "問題" "上下文" 圖1.png 圖2.png

注意事項¶

思維等級（Reasoning Effort）：默認不傳參數，遵循 provider 默認設置（官方 flash 默認爲 high 且自適應）。off 是唯一能強制關閉推理的開關。在跨中轉商（如 XQAPI）時，該參數可能無效，建議直連官方模型。
未實現功能：F7（配額限速）、F8（併發 quorum）目前未實現。
參數限制：CLI 的 --model 旗標本體需要修改 DSH 源碼（需提 issue）。本插件通過 DSH_MODEL 環境變量配合 agent/request 改道來實現更穩定的模型選擇。
安全邊界：HTTP 端點僅允許迴環連接，無 CORS。生產環境建議配置 API 層的 Origin 同源校驗。
審計回填：consult 工具返回中的 adopted 字段目前靠主模型在回覆文本中標註“已採納/未採納”，尚未實現自動回填。