前言¶

在 DeepSeek Harness (DSH) 插件開發中，AI 生成的交付物通常以文本形式呈現。但當問題需要用戶進行多步驟交互、參數調試、拖拽決策或實時試配時，純文本交互顯得力不從心。

dsh-web-app 旨在解決這個問題。它將 AI 生成的交付物從靜態文本轉化爲單文件 HTML 的可交互產物——小工具、小遊戲或操作面板。這些產物以 Git 倉庫爲事實源，在對話中通過 /webapp 命令內嵌打開，用戶在頁面內操作後，結果通過填空模板回傳給模型，形成「人機接力」的工作流。

它是什麼¶

dsh-web-app 是一個 DSH 客戶端插件。它允許開發者部署單文件 HTML 應用到本地 Git 倉庫，並在 DSH 對話流中通過 iframe 無縫嵌入運行。交互過程對模型不可見，但交互結果會通過用戶確認後注入會話，驅動模型繼續決策。

維護者：frankshi2024。
許可證：MIT。

核心功能¶

該插件提供了以下核心能力：

• 部署後自動浮現：當本回合部署或更新了應用時，對話尾部會自動出現體驗卡，點擊「立即體驗」展開。
• 模型主動插卡：通過 dsh-web-app-show 工具，可在對話中途強制插入應用卡片。
• 零模型調用的打開：/webapp 是純 UI 命令，打開應用的過程不消耗模型 Token。
• 一次性門票機制：每次加載生成唯一的 loadId 和 token，10 分鐘過期。token 伺服時寫入 HTML，絕不暴露在 URL 中，用於安全校驗。
• 嚴格校驗鏈：攔截回傳時，依次校驗 event.source、門票有效性、鍵集與類型（TEXT/NUMBER/BOOLEAN/JSON）嚴格匹配。
• 默認用戶確認：回傳結果前展示完整渲染文本，防止誤操作。可在配置中關閉。
• 同 turn 去重：同一回合內，若未打斷且 payload 嚴格一致，攔截重複提交。
• Git 即事實源：應用版本由分支+提交號決定，修改倉庫內容並提交後，卡片「刷新」即可拉取新版。
• 全屏模式：支持一鍵全屏（ESC 退出），適合複雜交互。
• 分層 Skills：提供 dsh-web-app-author（部署/修改）與 dsh-web-app-interpret（解讀回傳）兩套 skill。

安裝與啓用¶

在 DSH 的 profile 目錄（例如 ~/.dsh/profiles/<profile>）中執行安裝：

pnpm add link:/path/to/dsh-web-app

安裝後，需在該 profile 的 package.json 文件中，將 "dsh-web-app" 加入 dsh.profile.bundles 數組，然後重啓或熱載插件。

環境要求：Node.js ^22.19.0 或 >=24.0.0。

典型用法¶

• 打開應用：在對話輸入 /webapp 選擇應用，或使用 /webapp <name> 直接打開指定應用。
• 全屏操作：卡片右上角點擊「全屏」，或按 ESC 退出。
• 更新版本：在本地 Git 倉庫修改代碼並 git commit，然後在卡片上點擊「刷新」按鈕。
• 管理應用：點擊側邊欄的「Web 應用」圖標，查看版本、倉庫狀態或刪除應用。
• 部署新應用：讓 AI 執行 dsh-web-app-author skill 流程，或直接使用 dsh-web-app-deploy 工具。

技術細節與注意事項¶

• 填空模板而非源碼讀取：模型消費的是交互結果，而非過程。回傳時使用預定義的填空模板（callback.template.md）填充用戶操作結果，而非讀取 HTML 源碼。
• 定位對照：如果只是簡單的結構化表單問答，GenUI 的表單類組件（如 ask-user-question）更輕量。dsh-web-app 適合複雜交互產物，如運維面板、旅行決策樹等。
• 安全模型：
  • 使用 sandbox="allow-scripts" 的 iframe 運行，不授予 allow-same-origin，應用無法訪問 Cookie 或 DOM，也無法直接請求 /api。
  • 數據通道使用插件自有前綴路由。
  • 僞造回傳由門票校驗和結構校驗攔截，用戶確認是最終兜底。
• 對等依賴：dsh-commands、dsh-tools、dsh-host-webserver 爲硬注入；若 dsh-skill 缺失，插件會跳過 skills 註冊。

總結¶

dsh-web-app 通過 Git 倉庫和單文件 HTML 的結合，實現了 DSH 生態中「可交互產物」的落地。它解決了 AI 文本交付的侷限性，讓複雜的交互邏輯（如參數調優、狀態切換）能夠由模型設計、由人操作、由數據驅動。