前言¶
在 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
