前言¶
在 DeepSeek Harness（DSH）裏做界面原型或 UI 說明時，常見做法是把 HTML 貼在消息裏當普通代碼塊，模型和用戶都只能「看文本」，無法在聊天流裏按固定視口預覽佈局，也很難把畫布上某個按鈕、卡片精確指回輸入框。維護者 YukimuraSol 的客戶端插件 dsh-ui-block 針對這類需求：在消息裏用一行指令引用 ui-blocks/ 下的 .uiblock 文件，在沙箱 iframe 裏按聲明分辨率渲染；並在畫布內點選 DOM，把 element«…» token 作爲 chip 寫進 composer，序列化仍回到原文 token。
下面介紹插件定位、已文檔化的能力、安裝方式與典型寫法。功能與語法以倉庫 README 爲準；社區目錄 SkillHub 與 GitHub 同源，與 DeepSeek / 幻方無官方從屬關係。
這是什麼¶
dsh-ui-block 是 DSH 的 web 客戶端插件（package.json 中 dsh.client.platform: web，immediately: true），通過 Cordis bundle patch 注入聊天與會話 UI 依賴。一句話：解析消息中獨立一行的 ::dsh-ui <name> [res=WxH]::，讀取 ui-blocks/<name>.uiblock，在消息流裏用與宿主一致的 CodeBlock 外殼掛載沙箱畫布；選區模式下選中元素時，經 conversation.input.overlay 把 element token 插入輸入區，渲染與複製行爲複用 dsh-element-chip 的 source: 'element' 路徑。
當前 npm 包版本爲 v0.2.2（MIT）。倉庫：https://github.com/YukimuraSol/dsh-ui-block。
觸發方式與文件引用（2026-10-24 起）¶
2026-10-24 起，觸發方式改爲消息裏單獨一行（前後可有空白，不帶反引號、不在圍欄裏、不帶別的字）：
::dsh-ui 名字::
或指定畫布邏輯分辨率（寬×高）：
::dsh-ui 名字 res=820x510::
該行在界面上會被隱藏，畫布插入在原位置。res= 決定 iframe 的 CSS 視口，缺省爲 1440×900。橫欄語言標籤固定爲 dsh-ui；複製按鈕複製的是路徑 ui-blocks/<name>.uiblock（code 傳路徑，<pre> 僅作隱藏）。
舊寫法（裸圍欄 + 塊體首行 dsh-ui ref: ui-blocks/<name>.uiblock）已從代碼中刪除，無兜底識別。若仍在用圍欄首行 dsh-ui res=… 內聯 HTML 的舊 meta 行，且沒有 dsh-ui 前綴的遷移形態，將不再渲染，控制台會出現 missing-dsh-ui-prefix 類診斷。
核心功能¶
沙箱畫布與尺寸模型¶
插件把每個塊當作「看畫布的窗戶」：
- 畫布分辨率（
res=）：改 iframe 真實視口，內容會重新排版，media query 生效。非法或缺失的res回退 1440×900，整塊仍渲染，不退回普通代碼塊。 - 縮放：光標在畫布上滾輪，以光標點爲中心縮放（約 20%–400%），僅
transform，不重排；雙擊畫布可復位爲適應寬度。 - 外框高度：默認
min(畫布高×初始適應, 480px)；歷史文檔中的h=等圍欄 meta 隨舊觸發方式退役，當前以橫欄與拖曳下緣把手（約 120px–視口高）調整爲主。
畫布大於窗格時可拖拽平移；iframe 自身 pointer-events: none，交互由插件透明層接管。縮放、選區、讀文件與報錯處理在 README 變更說明中標註爲與早期實現一致的部分未改。
按消息時刻還原（2026-10-25）¶
引用語法不變，仍是一行 ::dsh-ui <name>:: / ::dsh-ui <name> res=WxH::。一條消息裏顯示的塊內容是該消息首次渲染時的版本；之後修改 .uiblock 隻影響之後的新消息。釘住狀態在宿主側 ui-blocks/.pins.json，刷新後各消息仍各顯示各的版本。
歷史存於 ui-blocks/.history/<名字>/：首次見到的基線 base.uiblock，log.json 每行 {at, patch} 行級補丁。宿主可通過查詢參數還原：?at=<epoch毫秒> 取某一時刻內容；?pin=<對話節點鍵>&i=<第幾條> 首次請求釘住「現在」後沿用；都不帶則顯示最新（兼容舊客戶端）。釘住後的引用不再週期性重讀文件。找不到 [data-chat-node-key] 祖先時（如草稿預覽）退回不帶 pin、顯示最新。
注意：升級前已存在的歷史消息在首次渲染時才釘住，釘的是當時的「現在」，無法 retroactive 還原更早版本——README 明確說明這是信息缺失，補不回來。
畫布內選區（v0.4.0）¶
橫欄分辨率控件右側有選區按鈕（13×13 SVG，無文字）。點亮後可在畫布內：
- 移動鼠標高亮元素；滾輪在層疊棧中切換（不觸發縮放）；
- ↑↓←→ 在父子、兄弟間導航（焦點需在 iframe 內）；
- 點擊確認選中，token 直接插入 composer（不經剪貼板）；
- 再點一次圖標退出；Enter / Esc 不綁定。
同頁僅一個塊可處於選區 armed 狀態。token 爲三行 element«…» 格式（DOM Path、Position、HTML Element），規則與 element-picker 對齊；插入走 slash/input-insert-reference，source 爲 'element' 以複用 chip 實現。座位 id 爲 dsh-ui-block-picker，與 dsh-element-chip 的 overlay 座位 additive 共存。
自檢¶
倉庫提供：
node self-check-uiblock-directive.mjs
README 稱當前約 46 條斷言，覆蓋新指令解析、舊寫法不命中、代碼塊內不命中、非法 res、補丁鏈與 pin 還原等。
安裝與啓用¶
DSH 生態按「一切皆插件」擴展；安裝方式以你在用的 Harness 與社區目錄爲準，不要在未覈對文檔的情況下自行拼接未出現的 CLI。
SkillHub 目錄頁 給出的 Harness 安裝表述爲：
請安裝 DSH 插件 YukimuraSol/dsh-ui-block。
安裝前建議在 GitHub 閱讀 README.md、cordis.patch.yml 與 client.js 入口行爲，確認與當前 DSH 客戶端版本匹配。插件標記爲可安裝客戶端，啓用後會在 web 端立即注入（immediately: true）。
典型用法¶
1. 準備 ui-blocks 文件¶
在宿主約定的 ui-blocks/ 目錄下放置與名字對應的文件，例如 ui-blocks/login-modal.uiblock（內容爲要在沙箱中渲染的 HTML/CSS/JS，以你項目實際約定爲準）。
2. 在消息中引用¶
發送單獨一行（示例名與分辨率可按需替換）：
::dsh-ui login-modal::
需要更窄的預覽視口時：
::dsh-ui login-modal res=820x510::
3. 從畫布指回輸入框¶
點亮選區按鈕，在畫布內選中目標元素，確認後 composer 會出現 element chip；複製或發送時仍序列化爲完整 element«…» token，便於模型定位 DOM。
4. 開發與迴歸¶
改插件或塊文件後，可在倉庫根目錄運行 node self-check-uiblock-directive.mjs 做指令與還原邏輯自檢。
適用場景與注意¶
適合：需要在對話流中預覽 ui-blocks 靜態/輕交互原型；希望用與瀏覽器選區一致的方式把具體節點引用進下一輪 prompt；與 dsh-element-chip 共用 token 格式的 UI 協作流。
注意：
- 插件在 當前 DSH 進程權限 下運行，能讀寫的路徑以 Harness 與插件實現爲準；安裝前請審查源碼與 MIT 許可證。
- 觸發行必須滿足「單獨一行、無反引號、無圍欄」；寫在普通代碼塊裏的
::dsh-ui …::不會命中。 - 消息級 pin 與補丁鏈依賴宿主側
ui-blocks/.pins.json與.history/；備份或遷移工作區時需一併考慮。 - README 中關於雙 profile（如 3080 / 4000）junction 的說明面向插件開發者同步副本，普通使用者以單一安裝路徑爲準即可。
結尾¶
dsh-ui-block 把「一行引用 + 外部 .uiblock 文件」變成聊天裏的沙箱預覽，並把畫布選區接進 composer chip，減少在 HTML 字符串與真實佈局之間來回對照的成本。
