dsh-live-canvas
在隔离的 iframe 沙箱中实时渲染 Agent 生成的 HTML、React (JSX/TSX)、Vue、SVG、Mermaid 和 Markdown，支持 SSE 热重载，并提供 DOM 点击检查器、并排视觉对比、响应式设备矩阵和一键 Vite ZIP 导出。
工具能力
README📦 @goodandready/dsh-live-canvas
交互式前端开发工作室、Retool 风格 CRUD 数据看板引擎、Time-Travel 时间旅行调试器、多平台一键部署 (Vercel, Cloudflare, Netlify, Gist)、Figma 矢量桥接、UI 音效及 31 个智能体工具 (适用于 DeepSeek Harness)
🇬🇧 English • 🇷🇺 Русский • 🇨🇳 中文说明
▼text复制代码⭐ **如果您喜欢这个插件，请在 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 文本。这会导致：
- 缺乏即时交互反馈：开发者无法直接测试按钮点击、表单校验、动画转场或响应式屏幕断点，必须手动复制代码到本地工程。
- 上下文严重割裂：进行 UI 评审时需要在 IDE、终端、浏览器和设计工具间反复横跳。
- 文本信息过载：用长篇纯文本描述系统架构与项目路线图难以直观审阅。
解决方案：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 | 导入屏幕截图 / 设计稿并转换为实时交互代码 | 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
⚙️ 完整配置说明 (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等)。
🔄 宿主一键更新器
Live Canvas 集成了符合 DSH 插件规范的宿主一键更新器：
- 自动检查版本：定时查询
registry.npmjs.org，完整支持 semver 预发布版本比较。 - 设置卡片 UI 集成：清晰展示当前版本、最新版本状态及一键更新按钮。
- 宿主安全安装：通过本地包管理器 (
pnpm/dsh plugin add) 升级，并受本地回环与X-DSH-Update-Key鉴权保护。
📄 开源许可证
MIT © GooDAnDReaDY
工具能力
