前言¶

DeepSeek Harness（DSH）的智能體在輸出工具結果時，默認會將這部分摺疊爲”process”區段，用戶無法直接在消息內修改參數或進行交互。如果希望模型在回答後繼續收集參數、進行計算或對比，通常需要將工具結果展開爲文本，再讓用戶手動輸入。這中間的交互鏈路被切斷，用戶體驗較爲生硬。

dsh-tool-cards 是一個爲 DSH 提供交互式聊天卡片的插件。它在助手消息內渲染滑塊、下拉、分段控件、日期選擇器、表單、圖表和表格——用戶按下提交按鈕後，參數快照會作爲一條用戶消息回傳給智能體，讓模型在下一輪繼續處理。該插件實現了 chat-ui/1.0 消息格式的獨立版本，不依賴任何官方協議，也不復現私有實現。

功能說明¶

工作流程¶

模型調用 chat_ui 工具後，DSH host 會校驗載荷（組件白名單、樹深度、節點數、action 形狀），並將工具結果的 meta 攜帶 kind: 'chat-ui/1.0' 標識。插件會在會話輸出流上錨定一個自定義聊天節點（chat-ui-card），將卡片”提升”爲最終聊天輸出——不再摺疊進工具過程。

用戶在卡片上的拖動、勾選或輸入操作僅更新本地狀態，不產生網絡請求。只有按下提交按鈕時，纔會通過 POST /chat-ui/action 發送 action 請求，包含 cardToken、actionId、operation 和 values。host 根據卡片令牌解析出所屬會話，調用 agent.followup() 生成用戶消息。智能體在下一輪即可看到參數快照。

如果當前環境不支持 uiConversation，插件會回退到在工具行內渲染卡片，功能仍然可用。

組件類型¶

插件註冊了 26 種組件，分爲四類：

• 輸入：Slider、Checkbox、Radio、Select、Segmented、Input、Textarea、Date、Button
• 容器：Form、Pressable、Popover、Carousel
• 視覺：Chart（柱/線/餅/散點）、Map
• 展示：Card、Metric、Text、Heading、Row、Column、Divider、Badge、Alert、Table、KeyValue

Chart 和 Map 使用手繪 SVG 實現，Map 僅做座標投影示意，不連接任何瓦片服務。

表達式使用白名單 JSON AST，例如 { op: "mul", args: [{ var: "a" }, { var: "b" }] }，支持 add/sub/mul/div/round/eq/and/or/not 等運算。插件沒有使用 eval，也不會生成可執行代碼。

安全與限制¶

在 action 執行階段，client 永遠不會告知哪個會話屬於某個 action。host 在執行時記錄 card → session 映射，並通過 presentationMeta 向 client 傳遞一個不可見的 cardToken。action 路由只接受該 token，忽略請求體中的 sessionId，避免任意會話注入。如果 host 無法確定擁有者，插件將不發放 token，卡片以只讀方式渲染。

DSH host 對載荷有強制限制：每條消息最多 120 個節點，樹深度不超過 8，狀態鍵不超過 60 個，action 不超過 20 個，文本不超過 4000 字符。畸形載荷會在到達 client 前被拒絕。

安裝與啓用¶

在 DSH 的 profile 中執行：

dsh plugin --profile web add dsh-tool-cards

或在 ~/.dsh/profiles/<profile>/package.json 中手動添加 bundle 行：

{ "dsh": { "profile": { "bundles": ["...", "dsh-tool-cards"] } } }

然後重啓 DSH（profile patch 在啓動時讀取）。

典型用法¶

chat_ui 工具會出現在模型的工具集裏。其描述由模型按任務決定使用時機，例如調參數、多維對比、”給我做個計算器”等，不用於純解釋或一次性結論。

以下是一個最小載荷示例，用於藥劑投加量計算：

{
  "title": "藥劑投加量計算器",
  "ui": {
    "schemaVersion": "chat-ui/1.0",
    "initialState": { "soilTons": 1000, "doseGPerKg": 2 },
    "tree": {
      "id": "root",
      "type": "Card",
      "props": { "title": "藥劑投加量" },
      "children": [
        {
          "id": "soil",
          "type": "Input",
          "label": "土壤質量 (t)",
          "bind": "soilTons",
          "props": { "inputType": "number", "min": 0 }
        },
        {
          "id": "dose",
          "type": "Slider",
          "label": "投加量 (g/kg)",
          "bind": "doseGPerKg",
          "props": { "min": 0.1, "max": 5, "step": 0.1 }
        },
        {
          "id": "total",
          "type": "Metric",
          "label": "理論藥劑質量",
          "props": { "unit": "t" },
          "value": {
            "op": "round",
            "args": [
              {
                "op": "div",
                "args": [
                  { "op": "mul", "args": [{ "var": "soilTons" }, { "var": "doseGPerKg" }] },
                  1000
                ]
              },
              3
            ]
          }
        },
        {
          "id": "submit",
          "type": "Button",
          "label": "提交這次配比",
          "actionId": "apply"
        }
      ]
    },
    "actions": {
      "apply": {
        "kind": "submitToAgent",
        "operation": "apply-dose",
        "includeKeys": ["soilTons", "doseGPerKg"]
      }
    }
  }
}

Action 類型包括 submitToAgent、callTool 和 openUrl（僅限 http/https）。

按鈕是卡片唯一的出口：全寬、加粗、上方有分隔線。按鈕文案應描述用戶的下一個動作，由模型按當前任務決定，例如”應用這組參數”“計算推薦投加量”“提交這次配比”。

適用場景與注意¶

適合在需要模型在回答後繼續收集參數、進行計算或對比的場景中使用，例如計算器、配置嚮導、多維對比工具等。

插件以當前 DSH 進程的權限運行。安裝前應檢查源碼與許可證。插件僅使用 --dsw-alias-* 主題 token，自動跟隨亮/暗主題；React 保持爲 external，由 host 提供。

結語¶

dsh-tool-cards 爲 DeepSeek Harness 提供了在助手消息內直接進行交互的能力，讓模型在回答後仍能繼續收集參數、展示圖表或表格，並將結果回傳到下一輪對話中。通過白名單 JSON AST 表達式和安全的 action 路由機制，插件在功能與安全性之間取得了平衡。

• 目錄頁：https://www.skillhub.cn/plugins/wszw142857-beep/dsh-tool-cards
• GitHub：https://github.com/wszw142857-beep/dsh-tool-cards