# @goodandready/dsh-live-canvas 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-live-canvas/

版本：0\.2\.37
npm 元数据更新时间：2026-11-13T11:46:41.305Z
中文译文更新时间：2026-11-16T19:13:20.604Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-live-canvas
原文对照：https://npmcn.com/package/%40goodandready/dsh-live-canvas/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-live-canvas#readme
源码仓库：https://github.com/GooDAnDReaDY/dsh-live-canvas

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：699 kB，40 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：1 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-tools \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0，@deepseek-ai/schemastery ^3\.18\.1，@deepseek-ai/dsh-settings \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0，@deepseek-ai/dsh-host-webserver \>=0\.1\.0-rc\.6 \<0\.1\.1 \|\| \>=0\.1\.1-rc\.1 \<0\.1\.2 \|\| \>=0\.1\.2-alpha\.1 \<1\.0\.0
- 首次发布：2026-08-31T09:20:03.036Z
- 最新版本发布：2026-11-13T11:46:41.144Z
- 近 30 天下载量：4155（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 70 个）

## 中文简介

HTML 、 React 组件、 SVG 和带有 SSE 热重装的图表实时预览的交互式浏览画布

## 安装

```sh
npm install @goodandready/dsh-live-canvas
```

也可以使用：`pnpm add @goodandready/dsh-live-canvas`、`yarn add @goodandready/dsh-live-canvas`、`bun add @goodandready/dsh-live-canvas`

## README

# 📦 @goodandready/dsh-live-canvas

### 交互式前端开发工作室、Retool 风格 CRUD 数据看板引擎、Time-Travel 时间旅行调试器、多平台一键部署 (Vercel, Cloudflare, Netlify, Gist)、Figma 矢量桥接、UI 音效及 31 个智能体工具 (适用于 DeepSeek Harness)

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-live-canvas.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-live-canvas) [![license](https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-live-canvas/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![GoodAndReady Showcase](https://img.shields.io/badge/%F0%9F%8C%90_%E4%BD%9C%E8%80%85%E5%85%A8%E9%83%A8%E6%8F%92%E4%BB%B6%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-live-canvas/README.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-live-canvas/README.ru.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-live-canvas/README.zh.md)

<table><tbody><tr><td align="center">⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。<br><br>🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。</td></tr></tbody></table>

* * *

## ⚡ 概述与核心解决痛点

### 🚀 v0.2.14 新增核心体验

-   **🏠 项目仪表盘与最近会话 (Projects Hub)**: 聚合所有历史预览会话与工作区前端组件 (React, HTML, Vue, SVG, Markdown)，按最近活动排序，内置即时过滤搜索，一键加载至画布。
-   **↕️ 对话预览卡片高度自由调节**: 底部拖拽把手平滑调整高度 (160px - 800px)，提供 `S` (200px) / `M` (320px) / `L` (480px) 快速预设与宽屏模式 (`⤢` Wide View)。
-   **🔄 画布独立即时刷新**: 工具栏新增刷新按钮，支持框架内快捷键 F5 / Ctrl+R，无需刷新整个 DSH 页面即可重载预览。
-   **🛡️ 智能体工具防御性输出契约**: 当路径访问越界时返回结构化拒绝字段 (`code`, `allowedRoots`, `reason`, `valid: false`)，使智能体能够自主纠正路径。

在传统的终端与对话框环境中，代码智能体通常仅输出静态的代码片段或 Markdown 文本。这会导致：

1.  **缺乏即时交互反馈**：开发者无法直接测试按钮点击、表单校验、动画转场或响应式屏幕断点，必须手动复制代码到本地工程。
2.  **上下文严重割裂**：进行 UI 评审时需要在 IDE、终端、浏览器和设计工具间反复横跳。
3.  **文本信息过载**：用长篇纯文本描述系统架构与项目路线图难以直观审阅。

### 解决方案：`dsh-live-canvas`

受 _The Unreasonable Effectiveness of HTML_、Plannotator 与现代可视化设计平台启发，**`@goodandready/dsh-live-canvas`** 将 DeepSeek Harness 升级为完整的独立前端开发与构件运行环境。提供内存级 ESM 模块打包、SSE 热重载、对话框内实时预览卡片、分屏代码编辑器、版本时间旅行、多平台一键部署及 **30 个专用智能体工具**。

* * *

## 🧭 侧边栏布局与兼容性 (Sidebar Compatibility)

`@goodandready/dsh-live-canvas` 无缝支持所有 DSH 导航布局，且无需任何外部插件依赖：

| DSH 环境 | 支持的界面组件 | 功能特性 |
| --- | --- | --- |
| **DSH 0.1.5-alpha.1+ (原生)** | 原生右侧边栏 (`sidebarRightTabs`, `sidebar.right.pane.tab`) | 完整的 Live Canvas 工作区标签页 + `dsh-resource://file` 原生文件查看器。 |
| **传统配置文件** | `dsh-better-sidebar` 适配 | 独立标签页 (`live-canvas`) 与文件查看器 (`live-canvas-viewer`)。 |
| **双边栏同时启用** | 完美共存 | 确定性独立 ID，杜绝重复挂载，具备幂等清理功能。 |
| **无边栏环境** | 独立抽屉与模态窗口 | 纯自包含 slide-over 抽屉及快捷键 (`Alt+C`)。 |

## 🏛️ 系统架构关系图

```mermaid
graph TD
    classDef agent fill:#1e1b4b,stroke:#6366f1,stroke-width:2px,color:#fff;
    classDef core fill:#064e3b,stroke:#10b981,stroke-width:2px,color:#fff;
    classDef ui fill:#451a03,stroke:#f59e0b,stroke-width:2px,color:#fff;
    classDef sandbox fill:#18181b,stroke:#71717a,stroke-width:2px,color:#fff;

    Agent[🤖 DeepSeek Harness Agent / 30 个工具]:::agent
    Store[💾 PreviewStore LRU 缓存与历史快照]:::core
    Watcher[📁 WorkspaceWatcher 文件监控与同步]:::core
    Bundler[⚡ Smart 递归 ESM 打包器与编译器]:::core
    Deployer[🌍 多平台一键部署引擎]:::core
    FigmaBridge[🎨 Figma 矢量桥接与转换]:::core
    SoundEngine[🔊 Web Audio 交互音效引擎]:::core
    Themes[🎨 AI 设计系统令牌引擎]:::core

    WebUI[💻 DSH WebUI BetterSidebar 工作区]:::ui
    ChatCards[💬 对话流内嵌交互式预览卡片]:::ui
    EditorDrawer[📝 Split-View 分屏代码编辑器]:::ui
    TimeTravelUI[⏳ Time-Travel 历史时间轴]:::ui
    DeployModal[🌍 一键部署配置弹窗]:::ui

    SandboxFrame[🛡️ 沙箱 Iframe 独立预览环境]:::sandbox
    WYSIWYG[✏️ 双击行内 WYSIWYG 文本编辑]:::sandbox
    DnD[↕️ 拖拽重排页面区块]:::sandbox
    Blueprint[📐 蓝图黑白草图模式]:::sandbox

    Agent --> Store
    Watcher --> Store
    Store --> Bundler
    Deployer --> Store
    FigmaBridge --> Store
    Themes --> SandboxFrame
    Bundler --> SandboxFrame
    SoundEngine --> SandboxFrame

    WebUI --> EditorDrawer
    WebUI --> TimeTravelUI
    WebUI --> DeployModal
    WebUI --> SandboxFrame
    ChatCards -->|一键唤起工作区| WebUI

    SandboxFrame --> WYSIWYG
    SandboxFrame --> DnD
    SandboxFrame --> Blueprint
```

* * *

## 🛠️ 30 个智能体工具完整速查表

| # | 工具名称 | 功能描述 | 核心参数 | 返回输出 / 触发动作 |
| --- | --- | --- | --- | --- |
| 1 | `live_canvas_preview` | 渲染或更新 HTML/React/SVG/Mermaid 预览会话 | `content`, `componentType`, `title`, `theme` | `previewUrl`, `canvasId`, `success` |
| 2 | `live_canvas_inspect` | 获取用户点击的 DOM 元素、CSS 选择器与属性 | `canvasId`, `limit` | `inspections: [...]`, `count` |
| 3 | `live_canvas_reload` | 强制向当前打开的预览画布广播 SSE 热重载事件 | `canvasId` | `reloaded`, `timestamp` |
| 4 | `live_canvas_diagnose` | 查询沙箱控制台错误与异常，实现智能体自主修复 | `canvasId`, `level` | `logs: [...]`, `hasErrors` |
| 5 | `live_canvas_export` | 导出包含预渲染标记及渐进式运行时的独立 HTML 演示包 | `canvasId`, `saveToDisk` | `downloadUrl`, `savedPath` |
| 6 | `live_canvas_annotations` | 检索或清除画布上的矩形批注与用户反馈 | `canvasId`, `action` | `annotations: [...]`, `count` |
| 7 | `live_canvas_gallery` | 渲染多组件状态 Storybook 并排对比矩阵 | `variants`, `title` | `variantsCount`, `previewUrl` |
| 8 | `live_canvas_watch` | 扫描工作区文件并绑定实时文件监控器 | `subDir`, `exts` | `files: [...]`, `watchedFiles` |
| 9 | `live_canvas_controls` | 调整 Storybook 风格的交互式 Props 滑块与开关 | `canvasId`, `values`, `schema` | `values: {...}`, `schema: {...}` |
| 10 | `live_canvas_diff` | 分屏滑块对比两个版本快照的视觉差异 | `canvasId`, `fromId`, `toId` | `diffUrl`, `snapshotCount` |
| 11 | `live_canvas_matrix` | 渲染多设备响应式屏幕矩阵 (手机、平板、桌面) | `canvasId` | `matrixUrl` |
| 12 | `live_canvas_mock` | 配置沙箱内部拦截的 Mock REST API 接口及数据集 | `canvasId`, `endpoints` | `endpointsCount`, `mockData` |
| 13 | `live_canvas_pack` | 一键生成包含完整依赖的 Vite+React / Vite+Vue ZIP 包 | `canvasId`, `framework` | `downloadUrl`, `writtenDir` |
| 14 | `live_canvas_refine_element` | 针对特定 DOM 元素执行精准的 AI 样式与结构优化 | `canvasId`, `selector`, `prompt` | `success`, `message` |
| 15 | `live_canvas_storybook` | 自动扫描组件并构建 Storybook UI Kit 对比画廊 | `subDir`, `framework` | `galleryUrl`, `componentsCount` |
| 16 | `live_canvas_insert_block` | 在项目中插入预置高端设计模块 (Hero, Bento, Pricing 等) | `blockId`, `canvasId` | `blockId`, `title` |
| 17 | `live_canvas_vision_import` | 将参考 UI 设计稿/截图导入为 Live Canvas 预览脚手架 | `imagePath`, `framework` | `previewUrl`, `framework` |
| 18 | `live_canvas_visual_audit` | 自动化视觉审计：检查溢出、色彩对比度与响应式断点 | `canvasId` | `score`, `issuesCount`, `issues` |
| 19 | `live_canvas_generate_mock` | 生成逼真的 JSON Mock 数据集并挂载至沙箱拦截器 | `type`, `count`, `canvasId` | `datasetType`, `mockData` |
| 20 | `live_canvas_share` | 生成手机端实时预览二维码及局域网共享链接 | `canvasId` | `shareUrl`, `qrSvg` |
| 21 | `live_canvas_create_wireframe` | 生成低保真结构蓝图线框图 HTML 构件 | `title`, `layout`, `canvasId` | `previewUrl`, `layout` |
| 22 | `live_canvas_create_plan` | 生成包含持久化状态的交互式发布计划与路线图 | `title`, `version`, `canvasId` | `previewUrl`, `version` |
| 23 | `live_canvas_create_diagram` | 生成动态交互式架构系统关系与数据流向图 | `title`, `diagramType`, `canvasId` | `previewUrl`, `diagramType` |
| 24 | `live_canvas_create_prototype` | 生成包含平滑转场的多步骤交互向导原型 | `title`, `flowType`, `canvasId` | `previewUrl`, `flowType` |
| 25 | `live_canvas_resolve_annotation` | 将画布上的用户批注标记为已解决并记录说明 | `canvasId`, `annotationId`, `note` | `status: 'resolved'` |
| 26 | `live_canvas_create_crud` | 生成包含搜索、筛选与弹窗的 Retool 风格 CRUD 数据看板 | `title`, `entityName`, `canvasId` | `previewUrl`, `entityName` |
| 27 | `live_canvas_timetravel` | 历史版本时间旅行滑动对比与一键回滚 | `canvasId`, `action`, `snapshotIndex` | `timetravelUrl`, `snapshotsCount` |
| 28 | `live_canvas_instant_deploy` | 生成适用于 Vercel、Cloudflare、Netlify 与 Gist 的部署包 | `canvasId`, `target` | `downloadUrl`, `instructions` |
| 29 | `live_canvas_figma_bridge` | Figma SVG 矢量代码转换为 Tailwind 组件或导出 SVG | `svg`, `action`, `canvasId` | `action`, `componentName` |
| 30 | `live_canvas_sound_fx` | Web Audio 交互音效合成与预览 (点击、弹窗、成功音) | `action`, `soundType` | `presetsCount`, `soundType` |
| 31 | `live_canvas_capture_snapshot` | 捕获当前画布元数据、DOM 树或完整 HTML 快照，实现视觉反馈闭环 | `canvasId`, `format` | `snapshot`, `format` |

* * *

### 🛠️ 画布内置开发者工具与智能体闭环反馈

-   **迷你控制台抽屉 (Mini-Console Drawer)**：沙箱内拦截 `console.log/warn/error` 与 `window.onerror`，底部可折叠诊断抽屉与工具栏错误计数。
-   **组件状态预设切换器 (State Presets)**：工具栏一键切换 `Default`、`Loading`、`Empty`、`Error` 与 `Overflow` 状态。
-   **视觉反馈闭环 (Vision Snapshot Loop)**：`live_canvas_capture_snapshot` 工具让智能体可直接读取渲染后 DOM 结构与快照。
-   **单文件独立 HTML 导出**：一键导出包含预渲染离线标记的独立 HTML 包 (`/dsh-live-canvas/api/standalone`)。
-   **W3C 设计令牌解析器 (Design Tokens Bridge)**：一键解析 W3C / Figma Design Tokens JSON 并注入 CSS 变量。

## 📦 安装说明

在 DeepSeek Harness 环境中一键安装：

```bash
dsh plugin --profile web add @goodandready/dsh-live-canvas
```

* * *

这些值在插件页的 **Live Canvas Preview** 中编辑。标题下方是一行说明，下面是设置表单。保存时，每个字段都通过插件的设置服务写入。服务仍在加载时，表单显示加载状态；服务不可用时，表单显示不可用状态，而不是错误页。设置命名空间是 `dsh-live-canvas`；包名不是合法的设置标识符。

## ⚙️ 完整配置说明 (`settings.yaml`)

```yaml
plugins:
  "@goodandready/dsh-live-canvas":
    defaultViewport: "responsive" # 可选项: responsive, mobile, tablet, desktop, matrix
    autoOpenOnHtmlGen: true       # 当智能体生成界面时自动打开 Live Canvas 侧边栏
    enableHotReload: true         # 启用 SSE 实时热重载数据流
    maxSessionCache: 50           # 内存 LRU 缓存中保留的最大活跃会话数
    enableFileWatcher: true       # 启用工作区文件变动实时监控
    workspaceDir: ""              # 自定义工程根路径 (默认当前工作目录)
    workspaceRoots: []            # 安全沙箱明确允许的工作区根目录列表
```

* * *

## 🔒 安全机制与路径沙箱

Live Canvas 具备企业级防御与沙箱隔离机制：

-   **严格路径沙箱 (`resolveSafePath`)**：所有通过 API 和智能体工具 (`live_canvas_preview`、`/dsh-live-canvas/api/open-file`、`/dsh-live-canvas/api/workspace/files`) 访问文件的请求必须严格位于授权工作区根目录 (`workspaceRoots` 或当前工作目录) 内部。企图跨越至父级敏感目录（如 `/etc` 或同级未授权目录）的操作均会被拦截，返回 `ERR_PATH_OUTSIDE_ROOTS` 及 HTTP 403 Forbidden。
-   **CSRF 与源验证 (`isTrustedRequest`)**：所有写操作端点均校验同源请求头 (`Sec-Fetch-Site: same-origin`、`Origin` 或 `Referer`) 或本地回环网络调用。
-   **内容安全策略 (CSP)**：画布预览于沙箱 iframe 中呈现，具备严格安全策略 (`X-Frame-Options: SAMEORIGIN`、`X-Content-Type-Options: nosniff` 等)。
-   **DOM 属性转义与同源消息投递**：项目中心 (`Projects Hub`) 对所有 `data-file-path`、`data-title` 和 `data-path` 属性执行严格 `escapeHtml` 转义（支持含引号与特殊字符的文件名），并将跨帧 `postMessage` 严格限制在明确的 `targetOrigin` (`window.location.origin`)。
-   **全路由族访问防护与动态易失配置响应**：所有已注册的路由族（`/events`、`/sandbox`、`/diff`、`/matrix`、`/timetravel`、`/assets`、`/api` 及更新器状态）均通过 `isTrustedRequest` / `isTrustedStatusRequest` 进行严格源验证，阻断非受信外网及跨站请求（返回 403 Forbidden）。运行时配置变更通过 Cordis `loader/volatile-update` 与 `config` 事件即时响应并应用于会话存储、文件监视器和工具，无需重启 Cordis 服务。

* * *

## 🔄 宿主一键更新器

Live Canvas 集成了符合 DSH 插件规范的宿主一键更新器：

-   **自动检查版本**：定时查询 `registry.npmjs.org`，完整支持 semver 预发布版本比较。
-   **设置卡片 UI 集成**：清晰展示当前版本、最新版本状态及一键更新按钮。
-   **宿主安全安装**：通过本地包管理器 (`pnpm` / `dsh plugin add`) 升级，并受本地回环与 `X-DSH-Update-Key` 鉴权保护。

* * *

## 📄 开源许可证

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

## 常见问题

### @goodandready/dsh-live-canvas 是什么？

HTML 、 React 组件、 SVG 和带有 SSE 热重装的图表实时预览的交互式浏览画布

### 如何安装 @goodandready/dsh-live-canvas？

在项目目录运行 npm install @goodandready/dsh-live-canvas，或使用 pnpm add / yarn add / bun add。

### @goodandready/dsh-live-canvas 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-live-canvas 是否存在。

### @goodandready/dsh-live-canvas 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-live-canvas 可以商用吗？

@goodandready/dsh-live-canvas 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-live-canvas 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-live-canvas 在 2026/10/17 – 2026/11/15 这 30 天内被下载 4,155 次，日均约 139 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-live-canvas 还在维护吗？

最新版本 0\.2\.37 发布于 2026/11/13（3 天前）；至今共发布 70 个版本，其中过去 12 个月发布了 70 个；首次发布于 2026/08/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

