# 使用指南

## Sketch Graph（v0.7.0 开发预览）

打开参考板仍直接进入原来的草图编辑器。点「工作流总览」查看关系，点「新建草图」创建节点；单击节点改名称与用途，双击进入绘图，拖动节点整理布局。总览只加载缩略图，不同时运行多个 Excalidraw。

在草图中选中按钮、文字或多个元素，展开「关联」，选择页面跳转／细节展开及目标，点「创建关联」。没有选中元素时，同一个按钮进入区域框选。目标可以是新草图或已有节点；总览节点右上连接点也支持普通连接。蓝色实线表示实际导航，允许返回和循环；橙色虚线表示设计细化，不能循环，每个细节最多一个父节点。细节编辑顶部有可点击的父级面包屑。

单击连线可改类型、说明、定位来源、重新绑定或删除。删除来源元素后出现待重新绑定提示，关联不会自动换到其他元素。退出重新绑定或切换草图会结束该操作。

右上角全屏图标展开画板，原生对话变为可拖动、可收起、可调整大小的悬浮框；退出全屏恢复原分屏，草稿和画板保持。移动标题可用方向键调整。

总览「更多」可备份／恢复全部可编辑草图与关系。恢复会新增节点，保留原根草图；恢复任务先持久写入 IndexedDB，再开始服务器恢复，中断后可在本标签页刷新继续。数据库不可用或空间不足时提前停止，不开始部分恢复。最多 100 节点／300 连线，追加前显示明确容量限制；100 节点备份不能完整追加到已有根节点，需先减少备份节点，完整恢复模式暂未提供。

图布局与每张草图独立保存；连续拖动、平移和缩放会合并保存，进入编辑或关闭前等待最终状态落盘。各标签页的恢复记录隔离，多窗口冲突时先下载本窗口副本，再选择服务器版本。删除节点会删除该节点文档和关联，请先备份；清理失败会在后续保存或重启时补偿重试。

原生聊天可说：“先读取工作流，按页面草图实现网站，把 detail 关系作为组件细节，不要创建独立页面。”Agent 使用 `sketch_graph_read` 分页读摘要，再用 `sketch_read({nodeId})` 读取需要的节点；图片按需读取，把返回的 `imageReadArguments` 原样传给 `sketch_read_image`。省略 nodeId 始终表示根草图，不随 UI 当前编辑节点变化。根草图设置选区重点时，图遍历与其他节点读取受限制；需要全局理解时先清除重点。

子草图第一版提供 Agent 只读结构与图片；原生聊天批注、修改提案及直接加入原生附件仍限根草图。手动绘图、用途、独立 AI 分析与保存继续可用。[验收记录](validation-v0.7.0.md)

v0.6.5 支持 DSH Web 0.2.1-alpha.1 与 0.2.1-alpha.2，Excalidraw 0.18.1。两版云端实装功能回归见 [验证记录](validation-v0.6.5.md)；Windows／真实模型仍按 [清单](windows-acceptance-v0.6.4.md) 验收。

alpha.2 在同一会话改变有效执行目录时，仍保留原会话画板与存储身份；切换另一会话继续隔离。升级不需要迁移或重建草图存储。

安装只需官方管理器添加预构建 tgz；不需要单独安装 Excalidraw。来源、宿主前置与校验见 [安装指南](installation.md)。

## 用草图表达网页布局

在网页项目的 DSH 工作区中打开参考板，用矩形表示区域、文字标明用途。先表达区域关系，再由 Agent 完成排版、配色与应用实现。

保存后直接在原生聊天提出需求：

> 请按当前草图实现一个设计工作台网页，保留区域关系。重点做好视觉层级、留白和项目封面，搜索与筛选可用。文件放在当前工作区，不修改画板原图。

Agent 可按需读取结构和图片，通过 DSH 文件工具生成应用。生成结果仍需打开检查；草图不提供自动双向代码绑定。

局部纠正可直接说“右侧是本周安排，不是统计卡片”，也可让 Agent 为该区域添加批注，从卡片点「纠正」进入原生输入框。描述希望改变的视觉结果，例如“保留位置，把日程改为带日期的紧凑列表”。更新网页代码与修改画板是两件事；改图仍需提议、预览和确认。

## 批注与对话

点击「建议与批注」展开标题卡片。建议不设三条配额，只讨论有价值且不重复的问题；顶部每组显示三个标题，超过三个时可左右切换，点击画板编号自动切到相应标题。顶部只显示标题和必要状态；选中后，正文在画板里的批注卡片显示，追问与状态操作收进卡片右上角的「⋯」更多菜单，上方不再重复。图中标记的显示/隐藏位于该行最右侧；手动恢复可使用底部「作为参考发送」右边的「⋯ → 同步批注」，只重新读取已保存批注，不调用模型或生成新建议。顶部卡片非按钮区域可点击，悬停或键盘聚焦强调对应元素；画板编号也可激活卡片。全局批注在画板内显示，不要求伪造元素锚点。

「追问」「纠正」「修改这里」填入可编辑文字，保留原有文字与待发送附件，不自动发送。元素删除、批注过期或会话变化时，需要重新读取并生成有效批注。相同标题的批注按各自引用关联，勿复制旧引用作为新版本依据。

「AI 分析草图」是可选的独立模型分析，普通聊天不要求先执行。批注可以询问无标签区域的用途、提出有依据但不确定的理解，或讨论具体问题；画得完整不代表含义已经明确。含义清楚、没有值得讨论的点时可以返回零条建议，不凑数量。这不保证模型不会误判。仅结构模式不能识别自由手绘外观。

## 限定重点

用原生选择工具框选图形，在「更多操作」选「选区作为重点」。插件结构与图片读取均限制在重点及必要绑定文字；缺少重点图片时不会代发整图。

修改草图或重启宿主后需重新设置；需要整图时主动清除重点。此边界不约束其他 DSH 工具和已发送的附件。

## 保存与恢复

- 等待「已保存」后讨论；关闭重开、切换会话保留各自草稿。
- 同一浏览器按会话记住上次缩放与平移；关闭重开后恢复。视角只保存在本机，不改变草图版本，也不触发图片重导出。浏览器存储不可用或被清除时恢复默认视角。
- 「更多操作」可下载 `.excalidraw` 备份和 PNG；升级或卸载前建议备份。
- 保存冲突时先下载本地备份，再检查服务端版本。
- 预览不写入画板，确认后可原生撤销。历史“曾应用”只说明曾执行，撤销后修改可能已不存在；跨刷新撤销历史不保证恢复。

## 常见问题

**Agent 看不到最新图片**：确认已保存、重点有效，在「更多操作」更新视觉参考；也可「作为参考发送」添加 PNG，然后手动发送。

**模型报错或误读**：确认模型支持图片，按提示显式重试或自然语言纠正。插件不会用自动重试隐藏错误。

**批注没有同步**：刷新协作状态或重开参考板，不会主动调用模型。

**安装后没有入口**：确认安装进 `web` profile，退出并重启 DSH。卸载时退出宿主后执行：

```sh
dsh plugin --profile web remove dsh-sketch-reference
```

卸载不主动删除草稿或宿主附件。插件仅支持本地 loopback Web 使用。