前言¶

在 DeepSeek Harness（DSH）裏，智能體若要讓用戶從若干候選項裏只選一項，通常會用到內置的 ask_user_question。該工具會在當前輪次內阻塞，直到用戶作答。若選項裏需要縮略圖、試聽音頻，或希望先發出卡片、等用戶點選後再進入下一輪對話，dsh-choice 提供的是另一條路徑：在會話流裏插入一塊單選面板，工具調用立即返回，選擇結果以普通聊天消息回傳。

下面按定位、能力、安裝、用法和注意事項說明該插件。

這是什麼¶

dsh-choice（npm 包名 @machine202502/dsh-choice）由維護者 machine202502 發佈，分類爲客戶端插件。它在 DSH 聊天界面中渲染單選看板，與內置 ask_user_question 並列出現；每個選項可以是純文本、圖片或聲音。用戶在某一行按下勾選後，其餘行失效，所選內容作爲一條普通消息發送，從而開始下一輪對話。

核心功能¶

工具接口¶

智能體通過下列調用展示看板：

ask_user_choice({ title, subtitle?, options, noneLabel? })

各字段含義：title 爲卡片標題；subtitle 可選；options 爲選項數組；noneLabel 可選，用於末尾「以上都不是」一類行的文案。

交互行爲¶

• 每塊看板只能選一次：選中行的勾選按鈕生效後，其他行不可再點。
• 可選「以上都不是」：由 noneLabel 提供文案的尾部一行。
• 選定之後，聲音與圖片預覽仍可使用。
• 非阻塞：與 ask_user_question 不同，本工具調用後立即返回，不佔用當前輪次等待用戶輸入。
• 子智能體不可用：僅主智能體可展示看板；若由被其他在線智能體託管的調用方發起，會拒絕並提示人機交互不可用。

卡片上可見的文案（標題、副標題、選項標題與描述、noneLabel）均由智能體按對話語言提供；插件自帶的「選擇」「播放」「打開」等按鈕文案遵循下文語言設置。

卡片 UI¶

每一行約 52 px 高的預覽區（圖片縮略圖或 ▶ 播放按鈕）、標題與描述，右側爲圓形勾選按鈕。點擊圖片可放大；點 ▶ 使用普通 Audio 播放聲音。用戶確認選項後，編輯器中原有草稿文本保留，選擇結果單獨作爲一條消息發出。

選項結構¶

{
  "kind": "text",              // 必填: text | image | audio
  "title": "Keep as is",       // 行標題
  "description": "…",          // 可選第二行
  "value": "…",                // 發送到聊天的文本（默認等於 title）
  "src": "C:\\sounds\\a.wav"   // image/audio: http(s) URL 或本地絕對路徑
}

本地圖片或音頻會被複制到 %LOCALAPPDATA%\dsh-choice\media，並通過本機迴環地址提供訪問。

本機 Bridge¶

插件在 127.0.0.1:49236 提供 HTTP 服務：

界面語言¶

在插件行配置（plugins.row.config）中可選擇界面語言：Русский、English、中文或 Авто。值寫入 %LOCALAPPDATA%\dsh-choice\settings.json，無需重啓即可作用於卡片與表單。

解析順序爲：

1. 已保存的 language 爲 ru、en 或 zh 時直接使用；
2. auto 時跟隨應用語言：先 document.documentElement.lang，再 navigator.language；ru* → ru，zh* → zh，其餘 → en；
3. 未存儲時默認爲 ru。

可在 Plugins → Choice 中修改。卡片正文仍由智能體按對話語言填寫，僅插件自帶控件文案跟隨上述規則。

安裝與啓用¶

在 DSH 依賴配置中加入包版本（以 README 爲準）：

"@machine202502/dsh-choice": "^0.1.1"

並將 dsh-choice 加入 dsh.profile.bundles。主機側（host）加載需重啓 DSH；客戶端側隨頁面刷新即可。package.json 中當前發佈版本爲 0.1.2，引擎要求 Node >=20，許可證 MIT。

DSH 生態奉行「一切皆插件」；社區目錄站點 skillhub.cn 與 DeepSeek、幻方無官方從屬關係，安裝前請自行覈對源碼與許可證。插件在本機 dsh 進程權限下運行。

典型用法¶

智能體在需要用戶從多個方案（含配圖或試聽）中做唯一選擇時，調用 ask_user_choice，構造 options 數組。文本項只需 kind: "text" 與 title（及可選 description、value）。圖片或音頻項設置 kind 爲 image 或 audio，src 爲 HTTPS 地址或 Windows 本地絕對路徑；本地文件經 Bridge 的 /attach 流程進入 media 目錄後再展示。

若需要允許用戶明確表示「都不選」，傳入 noneLabel，看板末尾會出現對應行。

示例骨架（字段名與 README 一致，選項內容需按實際對話填寫）：

{
  "title": "請選擇要保留的配置",
  "subtitle": "只能選一項",
  "noneLabel": "以上都不適用",
  "options": [
    {
      "kind": "text",
      "title": "保持現狀",
      "description": "不修改當前配置",
      "value": "keep"
    },
    {
      "kind": "image",
      "title": "方案 A 示意圖",
      "src": "https://example.com/a.png"
    },
    {
      "kind": "audio",
      "title": "方案 B 試聽",
      "src": "C:\\sounds\\b.wav"
    }
  ]
}

調用後工具立即返回；用戶點選後，聊天流中出現代表所選 value（或默認 title）的消息，後續輪次可據此繼續推理。

適用場景與注意¶

適合：需要在同一會話裏展示帶圖、帶音的單選題；希望不阻塞當前 tool 輪次；主智能體直接與用戶交互的場景。

注意：

• 子智能體調用會被拒絕，編排時勿把該工具下放給子 agent。
• 本地媒體依賴 %LOCALAPPDATA%\dsh-choice\media 與 127.0.0.1:49236，部署或安全策略需允許本機迴環訪問。
• 界面語言默認與 auto 規則見上文；中文用戶可在插件設置中選「中文」或「Авто」。
• 安裝命令與版本以項目 README 與 npm 包爲準，勿憑倉庫名自行拼接 dsh plugin add github:... 一類未經文檔記載的命令。

結尾¶

dsh-choice 在 DSH 聊天中補上「單選看板 + 圖文音選項 + 非阻塞回傳」這一小塊交互能力，與 ask_user_question 形成互補。進一步瞭解可訪問社區目錄頁與源碼倉庫：

• 目錄頁：https://www.skillhub.cn/plugins/machine202502/dsh-choice
• GitHub：https://github.com/machine202502/dsh-choice