DSH Client Canvas
@xindong/dsh-client-canvas 为 DeepSeek Harness 提供可与 Agent 共享的浏览器画布。它将 PixiBoardSDK 官方 site 接入 DSH 的画布 Tab，并通过 @xindong/dsh-canvas 保存文档与资源；浏览器不再保存另一份权威画布数据。两个插件均以 MIT 许可证发布。
要求与安装
- Node.js 22.18+、DSH 0.2.0-rc.2；不支持旧版 DSH。Core 还使用 DSH 的
tools 和 systemPrompt 服务，Web 插件使用 Web Server 和 Conversation UI；Office 预览需要 DSH 的 officeToPdf 服务。
- 本包依赖已发布的
pixiboardjs@0.1.0-alpha.5。官方 site 源码快照固定在 SDK commit 4a22b10b4d902afc351b710da0002e0ed8117740；这两个版本需保持匹配。
在已有 DSH 安装中，一条命令安装完整的画布 UI 与 Agent 工具：
dsh plugin --profile web add github:xindong/dsh-client-canvas
Web 包会从固定的 Core GitHub commit 传递安装 @xindong/dsh-canvas；其 bundle 补丁会先启用 Core，再启用 Web，无需单独安装 Core。启动 DSH：
dsh web
已有 DSH 进程需在安装或更新插件后重启，再刷新浏览器。打开 DSH 提供的完整登录地址（包括 ?token=...），在会话中切换到 Canvas Tab。插件沿用当前 DSH 的数据目录（$DSH_HOME，默认 ~/.dsh），不会自动迁移旧画布。
仅需要画布文档与 Agent 工具、不需要 Web UI 时，可单独安装 Core：dsh plugin --profile web add github:xindong/dsh-canvas。
**从旧版双插件安装迁移：**先停止 DSH，再依次运行：
dsh plugin --profile web add github:xindong/dsh-client-canvas
dsh plugin --profile web remove @xindong/dsh-canvas
第二条只移除 Core 的直接安装与独立 bundle 选择；Web 的依赖仍会提供 Core 代码。检查 $DSH_HOME/profiles/web/package.json（默认 ~/.dsh/profiles/web/package.json）的 dsh.profile.bundles：只保留 @xindong/dsh-client-canvas，不要同时选择 @xindong/dsh-canvas。若另有手写 profile/home patch 插入 xindong-canvas，先迁移其中的自定义配置并移除重复条目。不要删除画布目录或 canvas-storage.json；确认无重复条目后再启动 DSH，刷新浏览器。
快速开始
在 Canvas Tab 中创建或选择画布，拖入图片、音视频或文件；可使用官方 site 的选区、缩放、右键菜单、重命名、下载、截图和播放等交互。画布 Tab 保留 DSH 侧栏与导航，右侧可拖动、调整宽度并折叠的悬浮对话面板复用原生会话输入；切回其他 Tab 时恢复原生布局。节点底部可下载或使用「Agent 操作」；删除在右键菜单中。
Agent 通过 Core 提供的 canvas_read 和 canvas_write 读写同一份全局画布：
{"board_id":"board-id","node_ids":["source","result"],"limit":100}
{"board_id":"board-id","expected_revision":12,"operations":[{"type":"create","nodes":[{"id":"result","type":"processing","x":400,"y":100,"props":{"title":"生成结果","status":"running"}}]}]}
board_id 可省略，此时使用当前画布；写入前读取 revision，发生冲突后重新读取再提交。canvas_write 支持创建、更新、原位转换、删除、布局与有向连线的创建/修改/删除，节点和连线修改在同一事务提交。processing 只是占位节点，不会自行运行 AI 任务；用已有 DSH 工具生成内容，再以 asset_source 导入或转换节点。文件来源可为本地路径或公网 HTTP(S) URL（单文件上限 64 MiB），详细参数见 Core 文档。视口 fit、center、zoom、pan、reset 请求只作用于已打开的目标画布，不修改文档 revision。
选中节点后点「Agent 操作」，输入针对该节点的指令；Enter 发送、Shift+Enter 换行、Escape 关闭。发送前先保存画布，再将节点、关系和资源上下文送入当前 DSH 会话，不占用聊天草稿。发送失败保留指令；切换节点或会话不会继续发送旧指令。
数据与设置
- Core 是文档、revision、媒体二进制与 Agent 工具的唯一权威来源。默认画布位于
$DSH_HOME/canvas，资源位于其 assets 子目录；关系存放在文档 metadata.connections。保存经 revision 校验，Agent 修改会同步到 Web。
- 视口平移与缩放按画布保存在当前浏览器的
sessionStorage，刷新或切换 Tab 可恢复；它不属于共享文档。背景、网格、缩放限制与连线全局样式是浏览器偏好；网格仅供视觉参考，不参与吸附。连线选中后可用 Delete/Backspace 删除。
- 左侧齿轮中的画布、连线设置即时应用；节点与提示词设置保留草稿，点击「保存设置」后应用。节点工具栏入口、参考范围与上下文预算保存在当前浏览器；处理偏好和高级提示词保存在 DSH 的画布目录，供会话共用。共享设置保存失败时不提交浏览器草稿。
- 节点设置可选择只参考当前节点，或包含来源、后续、相连节点；处理偏好会随每次节点指令附带。提示词页可管理系统说明、动态概况并导入/导出
{version: 1, agent, prompts} 配置；「预览提示词」先保存画布、生成节点消息，但不调用模型。真正发送时重新采集上下文。
- 在设置的「配置」页填写已有目录的绝对路径或
~/... 路径；macOS 也可选择文件夹。目录指针存于 $DSH_HOME/canvas-storage.json，重启 DSH 后生效。切换只读取目标目录，不迁移或删除原目录。备份时同时保存画布目录和目录指针，迁移前停止 DSH 写入。
文件预览
导入 HTML/HTM、Markdown、文本/代码及 JSON/CSV/XML/YAML 等文件时先显示文件卡片，后台生成图片；PDF 默认渲染首页，Office 文件在可用的 officeToPdf 服务转换后走 PDF 通道。3D 模型由已发布的 mivo-model-viewer@0.7.0/node 预览，支持 GLB/GLTF、FBX、OBJ、STL、PLY、DAE、3MF、3DS、VRML/WRL、STEP/STP 和含模型的 ZIP。未知格式保留文件卡片及原文件，仍可下载或交给 Agent。
预览任务按类型有界调度，缓存源内容与规格对应的独立预览版本；首次缩略图长边默认 384px，选中时可请求更清晰的 detail（最长边 1024px），显式「重置预览」也请求 detail。后台结果通过 SSE 更新对应卡片，轮询用于断线恢复，不移动视口。拖动、缩放与网页刷新不会重新处理已有预览；失败保留原文件及已有图片，可从右键菜单重试。HTML 布局视口与画布节点尺寸分离，重置预览会保留布局宽度并按节点比例调整截图高度；PDF/Office 默认首页，长文档只显示有界的开头区域。
HTML 相对资源从同画布已导入资产的文件名或相对路径解析；单独导入 HTML 时缺失的资源不会自动补齐，补充资源后可刷新预览。HTML 文件夹/资源包 ZIP 的递归导入尚未接入，模型 ZIP 则单独识别。Office 排版受转换引擎和字体影响。插件依赖随安装提供；首次需要浏览器渲染时若缺少 Chromium，会自动安装（最多等待 5 分钟），安装失败可在插件目录运行 node scripts/setup-preview-runtime.mjs 手动准备后重试。预览性能与执行通道详见 预览说明。
架构与安全边界
@xindong/dsh-canvas 负责文档、资源、revision 和 Agent 工具；本插件负责 DSH conversation.view Tab、HTTP 桥接、预览任务与官方 site 的 DSH 适配。上游 site 保留画布交互和通用预览 UI，不另造画布实现。- site 在同源 iframe 中运行，以隔离 CSS、DOM 和快捷键；iframe 不是不可信代码的安全边界。HTTP project/media adapter 将 site 的存储接回 Core，而不是使用浏览器 IndexedDB/OPFS 保存第二份画布。
- site 源码快照位于
lib/site/upstream/，Pixi 和图标浏览器模块位于 lib/site/deps/；Three.js 由锁定版本的 npm 包在本机提供，锁定信息见 lib/site/upstream.json。lib/site-server.js 在请求时对上游 TypeScript 做 Node 类型擦除并提供 ESM；SDK 浏览器运行时的 pixiboardjs/browser、@pixi-board/core、@pixi-board/renderer-pixi 和 @pixi-board/adapter-browser 全部通过 import map 指向同一个已发布 npm 浏览器 bundle sdk/browser.js，不加载本机 SDK 源码或另外编译一份 SDK。
- 预览请求在本地服务端处理。HTML 渲染页不带 DSH 登录 Cookie，禁止访问
file: 和内网/回环 API；“打开原始文件”使用带 CSP 沙箱的资产响应，而不是同源 Blob 页面。不要把外部文件内容当作可信指令。URL 导入仅允许公网 HTTP(S)，不跟随重定向。保护完整登录链接、会话凭据和画布数据，报告问题时先去除敏感信息。
上游更新与开发
在仓库根目录安装依赖后，重新导入当前锁定的 SDK site 快照：
node scripts/update-upstream.mjs
更新到指定提交前，先将项目依赖 pixiboardjs 调整为该提交的 SDK 包版本，然后导入并核对变更：
node scripts/update-upstream.mjs --revision <40-character-commit-sha>
也可用 --latest 明确跟进 SDK main，但其包版本仍须与依赖一致。脚本通过 gh 获取不可变源码快照，按上游 lockfile 获取并校验浏览器依赖；若 site 接入点或公开预览契约变化则中止，不应手工修改 lib/site/upstream/。更新后检查 lib/site/upstream.json 的 revision/version、适配层兼容性与许可证，再同步运行副本并重启 DSH。
本地开发可把 Core 与 Web 仓库放在同一父目录，将两份源码链接到 DSH 的 web profile，然后从 Web 仓库运行 pnpm sync:runtime（或 bash scripts/sync-runtime.sh）。开发 profile 的 dsh.profile.bundles 只选择 Web bundle，不能再选 Core bundle。DSH_CANVAS_CORE_DIR 可指定 Core 仓库，DSH_WEB_PROFILE_DIR 可指定 profile；修改服务端代码后重启 DSH，修改浏览器代码后刷新页面。scripts/start-local.sh 是仓库开发辅助入口，可同步两个插件并使用独立的 DSH 运行时；普通用户不需要它。
问题与贡献请使用 GitHub Issues，提供版本、复现步骤与脱敏日志。许可证见 LICENSE；第三方依赖保留各自许可证。
