# 📦 @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`)。 | ## 🏛️ 系统架构关系图 ```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](https://github.com/GooDAnDReaDY)