pengc0066-star/dsh-visual-studio

@deepseek-ai/dsh-visual-studio

中文介绍

英文

Visual HTML/SVG Studio（可视化 HTML/SVG 工作室）是一个持久化的 DeepSeek Harness 网页插件：在浏览器里打开、新建、实时预览并保存工作区内的 HTML/SVG 文件，支持「元素检查」与「手动批注」，批注会直接送回当前 Agent 会话，由 AI 精确修改源码。

功能特性

- 打开 / 新建 / 保存 工作区内的 .html / .htm / .svg 文件。
- 实时预览：源码编辑器旁是隔离 iframe 预览（sandbox="allow-scripts"、无 allow-same-origin，预览脚本运行在独立源，无法访问父页面 DOM / Cookie）。
- 元素检查模式：在预览中点击任意 HTML/SVG 元素，显示选框、元素路径、稳定 selector、尺寸与主要 computed styles。
- 会话产物中心：编写区上方有产物栏，自动追踪当前会话 Agent 创建/修改的文件（显示相对路径、版本、更新时间，点击即打开），按 HTML/SVG、图片、文本分派到对应编辑器；图片可点选/框选定位，文本可在编辑器中选中段落。
- 手动批注：对选中元素、图片坐标或代码选区添加批注，提交时连同文件相对路径、版本、类型、定位（selector / 坐标 / 行列范围）与选中文本一起送回当前 Agent 会话。
- 自动刷新 + 状态保留：Agent 修改源码后自动刷新预览，批注的「已处理 / 未处理」状态保留。
- 撤销 / 重做 / 保存 / 刷新 / 桌面-手机视口切换。
- 版本备份与恢复：覆盖文件前把旧内容写到同目录 .dsh-visual-studio-backup-，可一键恢复上一版本。

快速开始

构建
corepack pnpm install
corepack pnpm run build   # tsc -b && tsdown

测试
corepack pnpm test

安装到当前 web profile（重启后仍存在）
dsh plugin --profile web add

安装后重启 dsh web，右下角会出现 Visual Studio 浮动面板。示例见 examples/demo.html 与 examples/demo.svg。

English

Visual HTML/SVG Studio — a persistent DeepSeek Harness web plugin that opens,
creates, previews, and saves workspace HTML/SVG files, with an element inspector
and agent-routed annotations.

Features

- Open / new / save workspace .html / .htm / .svg files.
- Live preview in a sandboxed iframe (sandbox="allow-scripts", no
allow-same-origin, so previewed scripts run in an opaque origin with no
parent-DOM or cookie access), beside a source editor.
- Element inspector: click any element in the preview to see a highlight
box, breadcrumb path, stable CSS selector, size, and selected computed styles.
- Session artifacts center: an artifacts bar above the composer tracks the
files the current session's agent creates or edits (relative path, version,
update time) and opens each by type — HTML/SVG preview, image point/box
select, or text selection.
- Annotations: attach a note to an inspected element, an image coordinate,
or a text selection; the submitted message carries the file's relative path,
version, kind, location (selector / coordinates / line-column range), and the
selected text.
- Undo / redo / save / refresh / desktop-mobile viewport controls.
- Versioned backups: before overwriting a file, the previous content is
written to a sibling .dsh-visual-studio-backup- file and can be
restored with one click.

Architecture

A dual-face Cordis plugin (one package, two halves):

- Node half (src/index.ts, host tree): registers the /visual-studio
Connection RPC channel (authority: loopback) serving list / read /
write / create / artifacts.list / backups.restore, and records each
session's deliverable artifacts (path, version, relative path) from the
fs/observed event. Every target path is containment-checked against the
任何读取或写入之前的工作区根目录。
- 浏览器半部分（src/client/，客户端树）：将 StudioPanel
注册到 shell.overlay 插槽中，并通过
Connection 传输注入文件/会话回调。

该包同时携带 dsh.client（浏览器名册）和 dsh.bundle
（cordis.patch.yml 插入自己的行），因此它既可以通过
dsh plugin add 安装，也可以通过将该行添加到配置文件的 cordis.patch.yml 来安装。

注解通过现有的 session.prompt RPC
（mode: 'queue'）到达 agent——与聊天编辑器使用的路径相同——因此不需要自定义的
会话注入机制。

要求

- 对等包 @deepseek-ai/* 版本为 ^0.1.0-rc.5（DeepSeek Harness
运行时）。这些来自 deepseek-ai/deepseek-harness monorepo（npm 或
检出副本）；它们并未在此处内置。
- Node >=22.19 || >=24。

构建

corepack pnpm install   # 或 npm install
corepack pnpm run build # tsc -b && tsdown

这会生成 lib/index.js（node 半部分）、lib/invariant.js 和 lib/client.js
（浏览器包）。

测试

corepack pnpm test

安装到 Harness web 配置文件

dsh plugin --profile web add

或手动操作：将此包链接到 $DSH_HOME/profiles/node_modules/@deepseek-ai/
中，并将 - insert: [{ id: visual-studio, name: '@deepseek-ai/dsh-visual-studio' }]
添加到 $DSH_HOME/profiles/web/cordis.patch.yml，然后重启 dsh web。

卸载

从 $DSH_HOME/profiles/web/cordis.patch.yml 中移除该行，并删除
$DSH_HOME/profiles/node_modules/@deepseek-ai/dsh-visual-studio 链接（或运行
dsh plugin --profile web remove @deepseek-ai/dsh-visual-studio），然后重启
dsh web。

示例

examples/demo.html 和 examples/demo.svg 是用于演练
“点击元素 → 注解 → agent 编辑 → 自动刷新”循环的文件。

已知限制与待完成工作

- 预览 iframe 仍会运行用户编写的脚本（allow-scripts）；它们
被限制在不透明源中，但未经过清理。
- 撤销历史和注解状态是会话本地的（注解通过
localStorage 持久化；撤销历史在页面重新加载后不会保留）。
- 会话产物注册表是内存中的：当 dsh web
重启时会重置，并随着 agent 再次写入文件而重新填充。
- 当通过配置文件补丁层而不是 dsh plugin add 安装时，dsh.bundle 补丁处于休眠状态。