前言¶

在 DSH 裏讓模型驅動瀏覽器時，導航、點擊、填表、提交都會直接改變頁面狀態。若缺少可審閱的上下文和明確的放行步驟，操作一旦發出就難以撤回，也不利於對照「執行前」與「執行後」的畫面判斷是否真的生效。

下面介紹社區插件 dsh-cua-preview（維護者 ffyfox）：用 Puppeteer 驅動本機 Chrome/Chromium，對會改頁面的工具調用走 DSH 審批；審批前截取當前屏幕供用戶查看，通過後再執行並在結果中按時間線返回截圖。審批思路參考 ZCode 的 cua-permission-broker 設計，未複製其源碼。插件在 SkillHub 目錄中歸類爲 admin-security。

這是什麼¶

dsh-cua-preview 是 DeepSeek Harness 的 bundle 插件（npm 包名 dsh-cua-preview，當前資料中版本 0.2.0，MIT 許可證）。它解決的是「瀏覽器自動化 + 人工把關」：只有用戶在一次審批中選擇允許後，導航與交互類操作纔會真正執行；只讀類工具不觸發審批。

核心功能¶

插件向 DSH 暴露四類瀏覽器相關工具，行爲如下（以倉庫 README 爲準）：

只讀的一對不會改頁面，因此不彈出審批。需要審批的一對會先詢問；僅在 Host 側得到「允許一次（allow once）」時纔會執行，否則不執行任何頁面操作。

截圖與審批的關係（簡要）：審批發生在動作之前。用戶做決定時，對話行裏會先展示審批時刻的屏幕（Host 在提問前瞬間捕獲）；若允許執行，結果裏通常先帶標註爲 before the action 的幀，再帶動作完成後的結果圖；若拒絕，則只返回審批時刻畫面並標註 at approval time (no action ran)。空白未加載頁不會強行輸出無意義白圖。

DSH 版本與審批文案：插件在 DSH 0.2.0-rc.2 上開發驗證（@deepseek-ai/dsh-tools 0.2.0-rc.2，@deepseek-ai/cordis 4.0.4），並向後兼容至 0.1.5-rc.2。在 0.2.0-rc.2 上審批提示行固定爲英文（Host 不再暴露可供插件讀取的語言偏好）；在 0.1.5-rc.2 / rc.3 上可本地化。

瀏覽器棧：選用 puppeteer-core，安裝時不下載瀏覽器包，直接連接本機已有的 Chrome/Chromium，與你在桌面上使用的瀏覽器一致。

安裝與啓用¶

環境要求（README 原文）：

• Node ≥ 22.12（puppeteer-core 要求）
• 本機已安裝 Chrome 或 Chromium 可執行文件；安裝插件時不會自動下載瀏覽器，缺失時會給出可操作的錯誤提示

DSH 插件通過 profile 安裝，dsh plugin 會把參數轉發到該 profile 目錄下的包管理器：

# 按包名安裝
dsh plugin --profile demo add dsh-cua-preview

# 從本地目錄安裝（例如已有 checkout）
dsh plugin --profile demo add ./dsh-cua-preview

dsh --profile demo --dump-config   # 配置層中會出現 "# == dsh-cua-preview"
dsh --profile demo                 # 啓動

該包是 DSH bundle：自帶配置層（cordis.patch.yml），由 profile 加載啓動。若要在已有 profile 上掛載而不重裝，可用 overlay（倉庫測試也採用此方式），示例片段：

- insert:
    - id: cua-preview
      name: 'dsh-cua-preview'
      config:
        artifactsDir: '/tmp/cua-artifacts'   # 可選
        headless: true                       # 可選，默認 true
        chromePath: '/usr/bin/google-chrome-stable'  # 可選，可自動探測

配置項¶

Chrome 路徑還會讀取環境變量 $DSH_CUA_CHROME_PATH，並在常見 Linux 路徑（如 /usr/bin/google-chrome-stable、/usr/bin/chromium 等）中探測。settle 可爲 false、數字（總毫秒預算）或對象覆蓋 graceMs / idleMs / capMs；非法值會記錄日誌並回退默認，避免錯誤定時器阻止插件加載。

頁面反應等待（爲何需要 settle）¶

page.click() 在輸入派發後即返回；goto 在 domcontentloaded 時返回也可能早於前端渲染完成。若在動作返回瞬間截圖，畫面往往仍是動作前的狀態。因此每個受審批的動作在截取「結果幀」前會按 settle 等待頁面有界時間內完成反應；設計細節見倉庫 docs/design.md。

典型用法¶

1. 按上文命令把 dsh-cua-preview 加入目標 profile，必要時配置 chromePath 或 headless: false 便於本地觀察。
2. 啓動 dsh --profile <name>，在會話中讓模型調用只讀工具（如 browser_snapshot）瞭解頁面，無需審批。
3. 當模型調用 browser_navigate 或 browser_act 時，在 Host 審批 UI 中查看當前屏幕截圖，選擇「允許一次」後操作纔會執行；在結果中對照 before the action 與動作後的畫面確認效果。
4. 需要留存證據時，注意 artifactsDir 下寫入的 PNG；調試等待策略時可調整 settle。

倉庫提供 npm test 及 acceptance / real-load 類腳本用於驗證加載與行爲，具體入口見 package.json 的 scripts 字段。

適用場景與注意¶

適合：需要在 DSH 智能體工作流中做受控的瀏覽器操作（填表、點擊、提交、導航），且希望在執行前用截圖做人工審閱的場景；與 admin-security 分類一致，強調操作門禁而非無限制自動化。

注意：

• 插件以當前 DSH 進程的用戶權限 運行，瀏覽器可訪問的範圍與該用戶一致；安裝與啓用前應自行審查 GitHub 源碼 與 MIT 許可證，確認符合你的安全策略。
• 依賴本機 Chrome/Chromium，容器或 CI 中需預先安裝並可通過 chromePath 或 $DSH_CUA_CHROME_PATH 指向。
• DeepSeek Harness 生態採用「一切皆插件」思路；SkillHub 插件目錄 爲社區站點，與 DeepSeek / 幻方無官方從屬關係，本文事實以倉庫 README 與 package 元數據爲準。

鏈接¶

• 目錄頁：https://www.skillhub.cn/plugins/ffyfox/dsh-cua-preview
• 源碼與文檔：https://github.com/ffyfox/dsh-cua-preview