@goodandready/dsh-live-canvas

中文文档
0.2.37发布于 2026/11/13MITES Module近 30 天下载 4155

Interactive in-browser canvas for real-time preview of HTML, React components, SVGs, and diagrams with SSE hot-reload

原始使用文档
文档目录13 节
  1. 交互式前端开发工作室、Retool 风格 CRUD 数据看板引擎、Time-Travel 时间旅行调试器、多平台一键部…
  2. ⚡ 概述与核心解决痛点
  3. 🚀 v0.2.14 新增核心体验
  4. 解决方案: dsh-live-canvas
  5. 🧭 侧边栏布局与兼容性 (Sidebar Compatibility)
  6. 🏛️ 系统架构关系图
  7. 🛠️ 30 个智能体工具完整速查表
  8. 🛠️ 画布内置开发者工具与智能体闭环反馈
  9. 📦 安装说明
  10. ⚙️ 完整配置说明 ( settings.yaml )
  11. 🔒 安全机制与路径沙箱
  12. 🔄 宿主一键更新器
  13. 📄 开源许可证

📦 @goodandready/dsh-live-canvas

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

npm version license DSH Plugin Node version

GoodAndReady Showcase

🇬🇧 English • 🇷🇺 Русский • 🇨🇳 中文说明

⭐ 如果您喜欢这个插件,请在 GitHub 上为它点亮 Star — 这能让我知道插件对您有用,并鼓励我继续开发和维护它。

🐛 如果您发现 Bug 或希望增加功能,请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议,并在后续版本中实现有价值的改进。

⚡ 概述与核心解决痛点

🚀 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)。

🏛️ 系统架构关系图

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 个智能体工具完整速查表

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

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

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

⚙️ 完整配置说明 (settings.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

版本与发布记录

@goodandready/dsh-live-canvas 共发布 70 个版本,首次发布于 2026/08/31;过去 12 个月发布了 70 个版本。

版本发布日期距今
0.2.37latest2026/11/133 天前
0.2.362026/11/097 天前
0.2.352026/10/2819 天前
0.2.342026/10/2621 天前
0.2.332026/10/2225 天前
0.2.322026/10/2126 天前

关于 @goodandready/dsh-live-canvas 的常见问题

@goodandready/dsh-live-canvas 是什么?

Interactive in-browser canvas for real-time preview of HTML, React components, SVGs, and diagrams with SSE hot-reload

如何安装 @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 和提交记录判断。