前言¶
DeepSeek Harness (DSH) 通過插件機制擴展能力，允許 AI Agent 在 Web UI 中與後端資源交互。在電子表格場景下，如果需要在瀏覽器界面中實時打開、新建或修改 Excel 文件，就需要一個前端驅動來橋接 AI 工具與 SpreadJS 引擎。該插件旨在解決 AI 無法直接操作 Web UI 中電子表格的問題。
這是什麼¶
grapecityxa/dsh-plugin-spreadjs-driver 是一個客戶端插件，由 GrapeCityXA 維護。它允許 AI 在 DSH Web UI 中打開、新建和操作 SpreadJS 工作簿。
其核心邏輯是“橋接”：
* Editor 負責：擁有 Workbook 實例、SpreadJS 引擎、界面加載、保存和恢復。
* Driver 負責：提供 AI 工具、路由聊天請求、執行 JavaScript 代碼。
插件不包含 SpreadJS/Designer 引擎，也沒有運行時依賴，完全依賴配套的 Editor 提供環境。
安裝與依賴¶
使用前需滿足環境要求：Node.js >= 22.19，DSH 版本 >= 0.2.0-rc.2。
該插件必須與 @grapecity-software/dsh-spreadjs-editor 配合使用。兩者需安裝到同一個 web profile 中：
dsh plugin --profile web add @grapecity-software/dsh-spreadjs-editor
dsh plugin --profile web add @grapecity-software/dsh-spreadjs-driver
配置完成後，在 DSH Web UI 的“設置 → 電子表格編輯器”中選擇該 driver，並等待加載完成。
核心工具¶
插件提供三個核心工具，用於狀態查詢、文件操作和代碼執行：
- sjs_live_status：查詢當前聊天的連接狀態及可用工作簿。
- sjs_live_open：打開工作區文件並等待 Workbook 就緒；通過
create: true參數可從內置空白模板新建.xlsx。 - sjs_live_execute：在 editor 提供的 Workbook 實例上執行 JavaScript 代碼。
典型用法¶
打開或新建工作簿¶
在 AI Skill 的上下文中調用工具：
// 新建文件
sjs_live_open({ path: "test-output/report.xlsx", create: true })
執行代碼修改數據¶
在執行工具中編寫 JavaScript，使用提供的 sheet()、setValue() 和 snapshot() 等輔助函數：
const s = sheet()
s.setValue(0, 0, '合計')
return snapshot()
執行期間，代碼運行在 editor 頁面環境，修改會立即顯示在界面上。
注意事項與機制¶
- 獨佔鎖機制：執行
sjs_live_execute期間，editor 會授予獨佔 lease，阻止用戶在執行期間進行併發編輯、保存或導出操作。 - 保存時機：修改僅實時顯示在 editor 中。只有當用戶在 Web UI 中手動請求保存時，數據纔會寫入磁盤。腳本中調用
save: true不會直接觸發保存，而是將狀態標記爲“待保存”。 - 環境隔離：執行環境提供
spread/workbook、GC、sheet(name?)、snapshot()、console和signal（AbortSignal）。結果必須可 JSON 序列化。 - 兼容性：同一聊天有多個可用實例（如多個標籤頁）時，必須通過
sjs_live_status獲取完整的id並指定給target，不要自行拼接路徑。 - 純 CLI 限制：服務端無需安裝 Chrome/Edge，但純命令行模式無法操作工作簿，必須依賴 Web UI。
生態與鏈接¶
該插件遵循 MIT 許可證。DSH 插件生態與 DeepSeek 或幻方無官方從屬關係。
- 目錄頁：[catalog_url]
- 源碼：[github_url]
