前言¶
在 DeepSeek Harness（DSH）裏，模型輸出多半是 Markdown 與純文本。指標對比、流程分支、表格排序這類信息，讀者往往要在長段文字裏自己「腦補結構」。社區裏也有各類增強方案；Mosaic 的定位是可選增強：需要時用緊湊的 React 組件呈現，不需要時純文字回答同樣有效，不必爲了用插件而強行加 UI。
下面介紹維護者 imwhatiam 發佈的 dsh-mosaic（分類：模型推理）。它在 SkillHub 目錄頁可見，GitHub 倉庫爲 imwhatiam/dsh-mosaic。插件 npm 包名 dsh-mosaic，當前版本 1.1.3，許可證 MIT。
這是什麼¶
Mosaic 是一個輕量的 DSH 可視化回答插件（README 簡介：Lightweight visual answers for DeepSeek Harness）。它把回答從純文本升級爲緊湊的原生 React 組件，並保留受控的沙箱 HTML/JS「逃生艙」（widget），用於固定組件難以覆蓋的遊戲、模擬器、音頻、地圖或自定義畫布。
插件刻意不追求「什麼都能畫」：主包不帶 ECharts / Three.js；部分 diagram 用官方 Mermaid 發行包懶加載，其餘示意圖由插件自行排布。普通文件與 Office 文檔只給鏈接，不在聊天裏硬解。
兩個輸出通道¶
模型可以通過兩種方式讓界面出現 Mosaic 視圖。
正文圍欄 dsh-view¶
在 assistant 回答裏寫 JSON，圍欄標記必須正好是 dsh-view（誤用 json 時客戶端有一層兼容，但不要依賴）。
{"title":"Ops snapshot","items":[
{"type":"stat","label":"Uptime","value":"99.96%","delta":"+0.02%"},
{"type":"callout","content":"No incidents in the last 7 days."}
]}
圍欄渲染依賴掃描 assistant 行內的代碼塊；Harness 0.2.1 起 Shiki 渲染的 `<code>` 沒有 `language-*` 類，識別路徑是「位於 assistant 行內且正文能解析成合法視圖 spec」。
## 工具 `render_view` / `validate_view`
適合獨立面板、表格、圖表或小組件。`validate_view` 可在發出前校驗；兩者除報錯外還可返回 `warnings=` 規模提示（詳見倉庫 SKILL.md）。
# 組件與示意圖
組件目錄保持精簡，字段與校驗來自同一份定義（完整字段見倉庫 [`SKILL.md`](https://github.com/imwhatiam/dsh-mosaic/blob/main/SKILL.md)）。
- 佈局：`text` `row` `col` `grid` `card` `divider` `spacer`
- 展示：`stat` `badge` `progress` `list` `table` `keyvalue` `steps` `callout` `code` `diff` `chart` `diagram`
- 媒體：`image` `video` `audio` `pdf` `link`
- 交互：`button` `input` `select` `slider` `tabs` `quiz`
- 高級：`widget`
`diagram` 支持 13 種 `kind`（如 `flowchart`、`sequence`、`timeline`、`tree`、`gantt`、`mindmap` 等）。`flowchart`、`sequence`、`state`、`er`、`gantt`、`mindmap` 走 Mermaid 懶加載（約 5.5 MB 原始包，gzip 約 1.3 MB）；`timeline`、`layers`、`quadrant` 等由插件排布。每張 diagram 卡片右上角提供 `svg` / `png` / `drawio` 導出。
界面只有一套輕卡片風格，顏色取自主題令牌 `--dsw-alias-*`，隨 DSH 淺色/深色與字號變化，無獨立主題切換器。
# 模型 Prompt 與設置頁
插件向模型貢獻一段說明可視化能力的 Prompt，默認來自包內文本。在 DSH 裏打開 **Settings → Mosaic** 可編輯當前生效內容，保存後從下一輪模型請求開始生效；可「恢復默認」。生效順序爲：你在頁面保存的內容 > 配置文件 `config.prompt` > 內置文本。也可在 `cordis.patch.yml` 的 mosaic 行設置 `config.prompt`（留空、類型不對或超過 128 KB 會回落）。覆蓋內容落在 Host 數據目錄的 `mosaic/prompt.json`，讀寫僅接受同源請求。
# 本地優先與沙箱 widget
表格排序/篩選/導出、tabs、quiz、slider 等默認在瀏覽器內完成。`button` 的 `local` 支持 `reset`、`copy`、`open`、`fullscreen`；只有聲明 `action` 的組件會把用戶動作發回模型。狀態按「會話 + 槽位 + 內容指紋」寫入 `localStorage`，最多 100 塊。
`widget.code` 渲染在 sandbox iframe 中（`allow-scripts allow-forms allow-popups`，無 `allow-same-origin`），CSP 禁止外網腳本；需庫時內聯進 widget。`window.mosaic.action()` 僅在真實用戶手勢後回模型（除非節點聲明 `actions: "programmatic"`），會話級限額爲每分鐘 10 次、單次 payload 16 KB（UTF-8 字節）。
# 安裝與啓用
在 DSH Plugin Manager 中安裝，或使用 README 給出的命令行：
```bash
# 發佈到 npm 後（普通 dsh web profile）
dsh plugin --profile web add dsh-mosaic
# 本地開發目錄
dsh plugin --profile desktop add link:/absolute/path/to/dsh-mosaic
安裝後重啓或刷新 DSH Web，新會話即可使用。bundle patch 只插入本插件一行，不會關閉或覆蓋其他插件。
兼容性（摘自 README）：npm 版本獨立於 Harness；package.json 聲明 engines.dsh 爲 >=0.2.1-rc.1 <0.3.0-0。插件 1.1.3 在 Harness 0.2.1-rc.5 上實測通過。Node 要求 >=24。
日誌與排查¶
運行情況寫入 JSONL：
# 未設置 DSH_HOME 時路徑爲 ~/.dsh/logs/dsh-mosaic/YYYY-MM-DD.jsonl
$DSH_HOME/logs/dsh-mosaic/YYYY-MM-DD.jsonl
默認級別 info；可在 mosaic 配置行加 config.logLevel: debug。日誌不記錄 Prompt 正文與組件 JSON 全文。排查示例：
grep -h '"level":"error"' "$DSH_HOME"/logs/dsh-mosaic/*.jsonl
適用場景與注意¶
適合誰：希望在 DSH 對話裏用 stat、表格、步驟、示意圖表達結構化答案，又希望 bundle 相對輕、交互儘量本地完成的開發者與使用者。
使用前請知悉：
- DSH 生態理念是「一切皆插件」；SkillHub 目錄 爲社區站點，與 DeepSeek / 幻方無官方從屬關係。
- 插件以當前 DSH 進程權限運行；安裝前應自行查看 GitHub 源碼 與 MIT 許可證，確認符合你的安全與合規要求。
- 自有路由（如 Prompt 編輯、
POST /dsh-mosaic/log）要求 Host 爲本機權威（loopback 或config.trustedHosts），並校驗同源，避免 DNS rebinding 場景誤配。 - 若同時安裝其他圍欄類插件，可能對同一段圍欄各渲染一套，可在 profile 中按需關閉其一。
- Harness 綁到非 loopback 地址時，需把主機名寫入
config.trustedHosts，否則 Mosaic 自有路由會拒絕請求。
結尾¶
dsh-mosaic 把「可選的可視化回答」收進一套主題一致的組件體系，並用 dsh-view 圍欄與 render_view 工具兩條通道接入模型；複雜交互交給沙箱 widget，重資源 diagram 按需懶加載。需要細節時以倉庫 README、SKILL.md 與 CHANGELOG 爲準。
- 目錄頁：https://www.skillhub.cn/plugins/imwhatiam/dsh-mosaic
- GitHub：https://github.com/imwhatiam/dsh-mosaic
