前言¶
在 DeepSeek Harness（dsh）裏做數學相關對話時，模型往往只能輸出 GeoGebra 命令文本，還要你複製到桌面版或網頁版畫板上執行。獨立項目 Geogebra-WebChat 把聊天和畫板放在同一頁，但自帶約 50MB 離線資源，且面板內再跑一套 LLM 循環，和 dsh 的「主對話 + 插件」形態重複。
dsh-geogebra-assistant（維護者 liangdabiao）是 dsh 的客戶端類插件：AI 留在主對話，側欄內嵌 GeoGebra（官方 CDN），模型通過 geogebra_draw 把命令經事件總線推到畫板自動渲染。插件包約 10KB，命令規範化、失敗回滾、導出與讀圖能力見項目 README。社區目錄：skillhub 插件頁；源碼：GitHub（MIT，截至資料記錄 GitHub 星標 3）。Skillhub 爲社區目錄，與 DeepSeek / 幻方無官方從屬關係。
這是什麼¶
一句話：在對話裏說需求（或發題目圖），模型調用工具，側欄「數學畫板」自動出圖；面板不提供對話輸入框，也不存對話歷史——和原版「左畫板右聊天」不同，dsh 版複用主對話，面板只做畫布。
相對 Geogebra-WebChat 的主要差異（據 README）：命令推送由 dsh 宿主完成；GeoGebra 從 geogebra.org CDN 加載；體量適合作爲 dsh 插件分發。
核心功能¶
AI 自動作圖¶
- 在主對話用自然語言描述圖形，例如：「畫一個直角三角形，標出三個角度」。
- 模型生成 GeoGebra 5 命令並調用
geogebra_draw（一行一條命令，可帶title、reset重畫時清空舊圖）。 - 命令經宿主內存事件總線與
GET /geogebra-assistant/api/events（SSE）推到側欄面板；面板未打開時，打開後會補畫最近一張。 - 面板可查看本次命令，改完後點「在畫板上執行」；圖形可拖動、縮放。
配套 geogebra-commands 技能教模型寫正確命令（鐵律、速查、讀圖規則、常見錯誤對照表）。
命令規範化¶
工具 geogebra_normalize（geogebra_draw 內部也會處理）：中文別名（如 圓(A,3)→Circle(A,3)）、LaTeX（如 \frac{\pi}{4}→(pi)/4）、全角標點（，→,）。手動模式粘貼命令時同樣會自動糾正。
拍照 / 截圖讀題¶
利用 dsh 主對話附件：把題目圖拖進對話（或點附件），說明「照這個圖作出來」。模型讀圖後會複述條件與標註；看不清會說明而不編造（技能裏有讀圖規則），再調 geogebra_draw 出圖。
導出¶
面板命令框下方四個按鈕：
| 格式 | 說明 |
|---|---|
.ggb |
幾何構造，可用 GeoGebra 再打開 |
PNG |
2 倍分辨率 |
SVG |
矢量 |
TikZ |
LaTeX 源碼；優先引擎原生 PGF，失敗用對象快照兜底 |
失敗自動回滾¶
一批命令中任意一條真失敗時，默認用執行前 getXML 快照 setXML 還原，避免半成品疊在舊圖上。面板提供「保留成功的 N 條」；開關可關。若 GeoGebra 版本無 setXML，則只報失敗、不動畫板。0.3.2 起區分樣式類命令（SetColor、SetPerspective 等）：evalCommand 可能返回 false 但實際已生效，不再誤判觸發整批迴滾。
數學畫板面板¶
內嵌 GeoGebra（CDN 加載）；支持手動粘命令執行、清空、規範化預覽、失敗命令逐條報告；頂部顯示「AI 通道」連接狀態。SSE 被代理擋住時，可退化爲 GET /api/pending?since=N 約 3 秒輪詢。
安裝與啓用¶
當前版本（package.json）：0.3.2。引擎要求 Node ^22.19.0 || >=24.0.0，dsh >=0.2.1-rc.2 <0.3.0。dist/client.js 已入庫，宿主通過 exports["./client"] 加載；缺此構建產物插件會激活失敗、側欄不出現。
從 GitHub 安裝（README 原文）：
# 從 GitHub 直接裝（dist/client.js 已入庫，裝完即可用）
dsh plugin --profile web add github:liangdabiao/dsh-geogebra-assistant
本地開發可把路徑換成你的倉庫目錄（示例路徑按本機修改）：
dsh plugin --profile web add D:/path/to/dsh-geogebra-assistant
修改 Host 側（工具/路由）後，需在 dsh 設置裏關掉再打開該插件條目，或重啓 dsh。改過瀏覽器側源碼後執行 npm run build，已打開頁面可通過 HMR 拿到新 dist/client.js。
CDN 與配置¶
畫板依賴能訪問 geogebra.org。網絡受限時，可僅用 geogebra_normalize 生成命令，複製到本地 GeoGebra。
插件 Configuration：
cdnBase：deployggb.js地址codebase：HTML5 codebase；留空則使用 deployggb.js 自帶默認值（僅自建鏡像時填寫）
典型用法¶
AI 作圖（主路徑）¶
- 對話中說：「畫一個直角三角形，標出三個角度」。
- 等待模型調用
geogebra_draw。 - 打開側欄「數學畫板」，應已自動出圖（若剛纔未開面板，打開時會補最近一張）。
- 需要時導出
.ggb/ PNG / SVG / TikZ，或在面板裏改命令後點「在畫板上執行」。
手動模式¶
- 複製 GeoGebra 命令，粘到面板輸入框。
- 點「在畫板上執行」；中文別名與 LaTeX 會自動糾正。
實現要點（便於排查）¶
- 作圖事件總線（
lib/bus.js）：保留最近 20 條事件，序號遞增；後開面板可補收。 - 推送：SSE 首連只補最近一條，避免重放整段歷史。
- 執行：收到
{type:'draw', commands, reset, title}後逐條evalCommand；失敗逐條列出。
維護者在倉庫用 npm install && npm test && npm run selftest && npm run build 自檢（含 22 個測試與零網絡 selftest）。
適用場景與注意¶
適合：在 dsh Web 配置下做幾何/函數可視化、講題出圖、需要 TikZ 或矢量導出、希望命令經模型規範化後直達畫板的開發者或教研場景。
注意：
- 插件以當前 dsh 進程權限運行；安裝前請閱讀源碼與 MIT 許可證，確認與自用環境一致。
- 需要穩定訪問 GeoGebra CDN；離線環境請降級爲命令生成 + 本地 GeoGebra。
- 面板不是第二個聊天窗口；所有意圖應在主對話表達。
- dsh 與插件版本需滿足
package.json的engines約束。
GeoGebra 版權歸 GeoGebra GmbH；命令規範化實現參考 Geogebra-WebChat 的 normalize.ts。
結尾¶
dsh-geogebra-assistant 把「說一句話 / 發一張題圖」和「側欄實時畫板」接到同一條 dsh 對話鏈上，用輕量 CDN 方案替代大體積內置資源，並補上回滾、導出與讀圖。若你已在用 dsh 做數學類智能體，可按上文命令安裝 web 配置條目，在主對話試一句作圖需求並打開側欄面板覈對渲染與導出。
