@civilization/dsh-drawio 0.2.1 → 0.4.0

package/skills/drawio-operation/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: drawio-operation
+description: 读取、检查、创建和语义化编辑 Draw.io 架构图与流程图，协同原生离线画板，并指导导出与排版工作流。
+---
+
+# Draw.io 画板与图表协同指南
+
+`dsh-drawio` 插件为 DeepSeek Harness (DSH) 提供 100% 本地离线的 Draw.io 画板，并向 Agent 注册结构化图表编辑工具。
+
+当用户询问 Draw.io 功能或需要绘制图表时，直接说明支持的画板功能与工具，无需探测工作区无关文件。
+
+## 核心模型工具
+
+### 1. `drawio_inspect`
+- **功能**：将现有 `.drawio` 文件解析为结构化的页面、节点、连线、文本内容及几何坐标。
+- **最佳实践**：修改已有图表前必须先调用 `drawio_inspect`，获取已有 cell ID、父子层级关系及连线端点。
+- **字段**：返回的 `plainText` 是已去除 HTML 格式的纯净标签；`children` 标识该容器节点包含的子节点 ID。
+- 仅在需要查看原始底层 XML 属性时设置 `include_xml: true`。
+
+### 2. `drawio_edit`
+- **功能**：对现有 `.drawio` 文件应用批量语义化增量修改，支持多页面管理。
+- **支持的批量操作类型**：
+  - `add_node`：新增节点。属性：`id`, `label`, `style`, `parent`, `x`, `y`, `width`, `height`。
+  - `add_edge`：新增连线。属性：`id`, `source`, `target`, `label`, `style`, `parent`。
+  - `update`：更新已有节点或连线属性。
+    - 推荐使用 `stylePatch: { fillColor: '#dae8fc', strokeColor: '#6c8ebf' }` 局部增量修改颜色或边框，避免冲掉节点的已有样式（如圆角、对齐等）。
+    - 也支持整体更新 `label`, `style`, `x`, `y`, `width`, `height`。
+  - `delete`：安全删除节点，并自动级联清理连接到该节点的孤立连线。
+  - `add_page`：在当前文档中新增图表页面。属性：`id`, `name`（如 `部署拓扑`、`时序交互`）。
+  - `rename_page`：重命名页面。属性：`page` (索引或ID), `name`。
+  - `delete_page`：删除指定页面。属性：`page`。
+- **规范**：节点 ID 应具备稳定且语义化的英文标识（例如 `client`, `api_gateway`, `auth_service`, `db_cluster`），严禁使用易冲突的纯数字 ID。
+
+### 3. `drawio_write`
+- **功能**：校验并写入完整的 Draw.io `mxfile` 或 `mxGraphModel` XML 文档。
+- 自动格式化为未压缩的规范 XML，便于后续 AI 审查与 Git diff 跟踪。
+- **建议**：从零构建新图表时首选 `drawio_write`；对现有图表进行局部修改或扩展时首选 `drawio_edit`。
+
+---
+
+## 架构图排版与设计规范
+
+为了保证大模型生成的图表整洁、专业、无重叠，请遵循以下工业级排版规范：
+
+### 1. 坐标与网格系统
+- **基准网格**：Draw.io 默认 `gridSize=10`，所有坐标 `x`, `y`, `width`, `height` 请取 10 的整数倍。
+- **标准节点尺寸**：
+  - 常规服务/模块：`width: 140, height: 60`
+  - 数据库/存储：`width: 120, height: 70`
+  - 外部系统/客户端：`width: 130, height: 50`
+  - 分组容器（Group/VPC）：根据内部节点数量自适应（如 `width: 600, height: 320`）
+- **间距推荐**：
+  - 横向流式布局：节点水平间距保持在 `80px ~ 120px`（如 `x1=40, x2=240, x3=440`）；
+  - 纵向分层架构：分层垂直间距保持在 `90px ~ 130px`（如 Layer 1: `y=40`，Layer 2: `y=160`，Layer 3: `y=280`）。
+
+### 2. 经典高质感现代配色方案（Flat Palette）
+
+| 分类/层级 | 填充色 `fillColor` | 边框色 `strokeColor` | 字体色 `fontColor` | 推荐使用场景 |
+| :--- | :--- | :--- | :--- | :--- |
+| **接入/网关** | `#dae8fc` (浅蓝) | `#6c8ebf` (深蓝) | `#000000` | Client, Nginx, API Gateway, CDN |
+| **业务服务** | `#d5e8d4` (浅绿) | `#82b366` (深绿) | `#000000` | OrderService, UserService, K8s Pods |
+| **存储/数据库** | `#ffe6cc` (暖橙) | `#d79b00` (深橙) | `#000000` | MySQL, Redis, MongoDB, S3 |
+| **异步队列/通信** | `#e1d5e7` (浅紫) | `#9673a6` (深紫) | `#000000` | Kafka, RabbitMQ, EventBus |
+| **告警/高风险** | `#f8cecc` (浅红) | `#b85450` (深红) | `#000000` | ErrorHandler, DeadLetter, Alert |
+| **容器/分组边框** | `#f5f5f5` (极浅灰) | `#cccccc` (浅灰) | `#333333` | VPC, Kubernetes Cluster, Subnet |
+
+### 3. 连线样式（Edge Styles）
+- 统一使用正交折线：`edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;`
+- 若要强调特定流向，可增加线宽 `strokeWidth=2;`，异步/订阅连线推荐增加虚线 `dashed=1;`。
+
+---
+
+## 离线画板协同与图片导出
+
+- **右侧栏实时双向协同**：
+  - 用户在 DSH 中打开任何 `.drawio` 文件即可在右侧栏全功能画板中直观交互；
+  - 模型调用 `drawio_edit` 或 `drawio_write` 保存后，画板会自动轻量检测版本变化并同步刷新，且不会中断用户正在进行的画布拖拽。
+- **纯本地离线图片导出**：
+  - 画板右上角内置纯本地导出面板，支持导出为 **PNG (2x 超清)**、**SVG (矢量无损)** 和 **XML-PNG (双模可编辑图)**；
+  - 支持一键**保存到工作区**（自动生成同名图片）、**写入系统剪贴板**（便于直接粘贴到文档或聊天窗口）或**下载到本地磁盘**。

package/src/client/index.tsx

@@ -6,7 +6,7 @@ const TAB_ID = '@civilization/dsh-drawio'
 const TAB_KIND = 'drawio'
 
 interface SessionScope { sessionId: string; cwd?: string }
-interface FileViewerProps { content?: string; truncated?: boolean; path: string; scope: SessionScope }
+interface FileViewerProps { content?: string; version?: string; truncated?: boolean; path: string; scope: SessionScope }
 interface OfficialContext extends Context { slots: any; sidebarRightTabs: any }
 
 export function apply(ctx: Context): void {
@@ -30,66 +30,111 @@ export function apply(ctx: Context): void {
 
 function OfficialDrawioTabTitle({ useTabInfo }: any): JSX.Element {
   const { tab } = useTabInfo()
-  return <><CanvasIcon size={15} /><span>{tab.title}</span></>
+  const title = tab?.title || (tab?.navigation?.address ? fileName(parseDrawioAddress(tab.navigation.address)?.path ?? 'Draw.io') : 'Draw.io')
+  return <><CanvasIcon size={15} /><span>{title}</span></>
 }
 
 function OfficialDrawioTabBody({ sessionId, useSessions, useTabInfo }: any): JSX.Element {
   const { tab } = useTabInfo()
-  const cwd = useSessions((sessions: any) => sessions?.byId?.[sessionId]?.cwd) as string | undefined
-  const resource = useMemo(() => parseDrawioAddress(tab.navigation.address), [tab.navigation.address])
-  const [file, setFile] = useState<{ key: string; content: string } | null>(null)
+  const rawAddress = tab?.navigation?.address
+  const resource = useMemo(() => parseDrawioAddress(rawAddress, sessionId), [rawAddress, sessionId])
+
+  const activeCwd = useSessions((sessions: any) => sessions?.byId?.[sessionId]?.cwd) as string | undefined
+  const resourceCwd = useSessions((sessions: any) => resource?.sessionId ? sessions?.byId?.[resource.sessionId]?.cwd : undefined) as string | undefined
+  const cwd = activeCwd || resourceCwd
+  const effectiveSessionId = sessionId || resource?.sessionId || ''
+
+  const [file, setFile] = useState<{ key: string; content: string; version?: string } | null>(null)
   const [error, setError] = useState<string | null>(null)
-  const key = `${sessionId}\0${cwd ?? ''}\0${resource?.path ?? ''}`
+  const key = `${effectiveSessionId}\0${cwd ?? ''}\0${resource?.path ?? ''}`
 
   useEffect(() => {
-    if (!resource || resource.sessionId !== sessionId || !cwd) return
+    if (!resource?.path || !effectiveSessionId || !cwd) return
     const controller = new AbortController()
     setError(null)
-    void fsRead({ sessionId, cwd }, resource.path, controller.signal)
-      .then(content => { if (!controller.signal.aborted) setFile({ key, content }) })
+    void fsRead({ sessionId: effectiveSessionId, cwd }, resource.path, controller.signal)
+      .then(res => { if (!controller.signal.aborted) setFile({ key, content: res.content, version: res.version }) })
       .catch(reason => { if (!controller.signal.aborted) setError(messageOf(reason)) })
     return () => controller.abort()
-  }, [key, resource?.sessionId, resource?.path, sessionId, cwd])
+  }, [key, resource?.path, effectiveSessionId, cwd])
 
-  if (!resource || resource.sessionId !== sessionId) return <CenteredMessage title="无法打开画板" detail="文件地址不是当前会话中的 Draw.io 文件。" />
-  if (!cwd) return <CenteredMessage title="无法打开画板" detail="当前会话没有可用的工作区。" />
+  if (!resource || !resource.path) {
+    return (
+      <CenteredMessage
+        title="无法打开画板"
+        detail={rawAddress ? `无法解析 Draw.io 文件地址：${rawAddress}` : '无法获取文件导航地址。'}
+      />
+    )
+  }
+  if (!cwd) {
+    return (
+      <CenteredMessage
+        title="无法打开画板"
+        detail="当前会话没有关联可用的工作区，请先在 DSH 中打开或选择一个工作区文件夹。"
+      />
+    )
+  }
   if (error) return <CenteredMessage title="画板载入失败" detail={error} />
   if (file?.key !== key) return <CenteredMessage title="正在载入画板" detail={fileName(resource.path)} />
-  return <DrawioCanvas content={file.content} path={resource.path} scope={{ sessionId, cwd }} />
+  return <DrawioCanvas content={file.content} version={file.version} path={resource.path} scope={{ sessionId: effectiveSessionId, cwd }} />
 }
 
-function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX.Element {
+function DrawioCanvas({ content, version, truncated, path, scope }: FileViewerProps): JSX.Element {
   const frame = useRef<HTMLIFrameElement>(null)
   const latestFile = useRef(content ?? '')
   const latestEditor = useRef(content ?? '')
+  const latestVersion = useRef(version)
   const saveTimer = useRef<number | undefined>(undefined)
   const saveGeneration = useRef(0)
   const [ready, setReady] = useState(false)
-  const [saveState, setSaveState] = useState<'loading' | 'saved' | 'saving' | 'external' | 'error'>('loading')
+  const [saveState, setSaveState] = useState<'loading' | 'saved' | 'saving' | 'external' | 'conflict' | 'error'>('loading')
   const [error, setError] = useState<string | null>(truncated ? '文件过大，DSH 只返回了截断内容，无法安全打开。' : null)
   const lastUserActivity = useRef(0)
   const isInteracting = useRef(false)
   const { dark, accent: accentColor } = useDshTheme()
-  const src = useMemo(() => `/dsh-drawio/runtime/index.html?embed=1&proto=json&spin=1&offline=1&local=1&ui=min&libraries=1&configure=1&noExitBtn=1&saveAndExit=0&dark=${dark ? '1' : '0'}`, [dark])
+  const initialDark = useRef(dark)
+  const src = useMemo(() => `/dsh-drawio/runtime/index.html?embed=1&proto=json&spin=1&offline=1&local=1&ui=min&libraries=1&configure=1&noExitBtn=1&saveAndExit=0&dark=${initialDark.current ? '1' : '0'}`, [])
 
   const post = useCallback((message: unknown) => {
     frame.current?.contentWindow?.postMessage(JSON.stringify(message), window.location.origin)
   }, [])
 
+  const reloadFromDisk = useCallback(async () => {
+    try {
+      setSaveState('loading')
+      const result = await fsRead(scope, path)
+      latestFile.current = result.content
+      latestEditor.current = result.content
+      latestVersion.current = result.version
+      post({ action: 'load', xml: result.content, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 })
+      setSaveState('saved')
+      setError(null)
+    } catch (reason) {
+      setError(messageOf(reason))
+    }
+  }, [scope, path, dark, post])
+
   const persist = useCallback(async (xml: string) => {
     const generation = ++saveGeneration.current
     setSaveState('saving')
     try {
-      await fsWrite(scope, path, xml)
+      const outcome = await fsWrite(scope, path, xml, latestVersion.current)
       if (generation !== saveGeneration.current) return
       latestFile.current = xml
       latestEditor.current = xml
+      if (outcome?.version) latestVersion.current = outcome.version
       setSaveState('saved')
       setError(null)
     } catch (reason) {
       if (generation !== saveGeneration.current) return
-      setSaveState('error')
-      setError(messageOf(reason))
+      const msg = messageOf(reason)
+      if (msg.includes('modified by an external process') || msg.includes('409')) {
+        setSaveState('conflict')
+        setError('文件已被外部或 AI 修改，当前存在并发冲突，点击可重新载入最新内容')
+      } else {
+        setSaveState('error')
+        setError(msg)
+      }
     }
   }, [scope.sessionId, scope.cwd, path])
 
@@ -113,7 +158,8 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
   useEffect(() => {
     latestFile.current = content ?? ''
     latestEditor.current = content ?? ''
-  }, [content, path])
+    latestVersion.current = version
+  }, [content, version, path])
 
   const markActivity = useCallback(() => {
     lastUserActivity.current = Date.now()
@@ -147,12 +193,101 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
     return () => window.clearInterval(timer)
   }, [])
 
+  const [menuOpen, setMenuOpen] = useState(false)
+  const [exportFormat, setExportFormat] = useState<'png' | 'svg' | 'xmlpng'>('png')
+  const [isTransparent, setIsTransparent] = useState(false)
+  const [isExporting, setIsExporting] = useState(false)
+  const [toast, setToast] = useState<string | null>(null)
+  const pendingExport = useRef<{ format: 'png' | 'svg' | 'xmlpng'; target: 'workspace' | 'download' | 'clipboard'; targetPath: string } | null>(null)
+  const menuRef = useRef<HTMLDivElement>(null)
+
+  const showToast = useCallback((msg: string) => {
+    setToast(msg)
+    window.setTimeout(() => setToast(current => current === msg ? null : current), 3200)
+  }, [])
+
+  const startExport = useCallback((target: 'workspace' | 'download' | 'clipboard') => {
+    if (!ready || isExporting) return
+    const ext = exportFormat === 'svg' ? '.svg' : exportFormat === 'xmlpng' ? '.drawio.png' : '.png'
+    const base = path.replace(/\.drawio$/i, '')
+    const targetPath = `${base}${ext}`
+
+    pendingExport.current = {
+      format: exportFormat,
+      target,
+      targetPath,
+    }
+    setIsExporting(true)
+    setMenuOpen(false)
+    post({
+      action: 'export',
+      format: exportFormat,
+      scale: exportFormat === 'svg' ? 1 : 2,
+      transparent: isTransparent,
+      border: 10,
+      spin: '正在渲染导出图片...',
+    })
+  }, [ready, isExporting, exportFormat, isTransparent, path, post])
+
+  const handleExportResult = useCallback(async (pending: { format: 'png' | 'svg' | 'xmlpng'; target: 'workspace' | 'download' | 'clipboard'; targetPath: string }, data: string) => {
+    try {
+      if (pending.target === 'download') {
+        const link = document.createElement('a')
+        link.download = fileName(pending.targetPath)
+        link.href = data
+        document.body.appendChild(link)
+        link.click()
+        document.body.removeChild(link)
+        showToast(`已开始下载：${fileName(pending.targetPath)}`)
+      } else if (pending.target === 'clipboard') {
+        try {
+          if (pending.format === 'svg') {
+            const svgText = data.startsWith('data:image/svg+xml')
+              ? decodeURIComponent(data.split(',')[1] || '')
+              : data
+            await navigator.clipboard.writeText(svgText)
+            showToast('已复制 SVG 代码到剪贴板')
+          } else {
+            const res = await fetch(data)
+            const blob = await res.blob()
+            await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })])
+            showToast('已复制图片到剪贴板')
+          }
+        } catch {
+          // 剪贴板受限或报错时降级为自动下载
+          const link = document.createElement('a')
+          link.download = fileName(pending.targetPath)
+          link.href = data
+          document.body.appendChild(link)
+          link.click()
+          document.body.removeChild(link)
+          showToast(`剪贴板无权限，已自动下载：${fileName(pending.targetPath)}`)
+        }
+      } else if (pending.target === 'workspace') {
+        const result = await fsSaveImage(scope, pending.targetPath, data)
+        showToast(`已保存到工作区：${fileName(result.path)} (${Math.round(result.bytes / 1024)} KB)`)
+      }
+    } catch (reason) {
+      setError(`导出失败：${messageOf(reason)}`)
+    }
+  }, [scope, showToast])
+
+  useEffect(() => {
+    const handleOutsideClick = (e: MouseEvent) => {
+      if (menuOpen && menuRef.current && !menuRef.current.contains(e.target as Node)) {
+        setMenuOpen(false)
+      }
+    }
+    window.addEventListener('pointerdown', handleOutsideClick)
+    return () => window.removeEventListener('pointerdown', handleOutsideClick)
+  }, [menuOpen])
+
   useEffect(() => {
     setReady(false)
     setSaveState('loading')
     const receive = (event: MessageEvent) => {
       if (event.source !== frame.current?.contentWindow || event.origin !== window.location.origin) return
-      let message: { event?: string; xml?: string }
+      let message: { event?: string; xml?: string; format?: string; data?: string }
       try { message = typeof event.data === 'string' ? JSON.parse(event.data) : event.data }
       catch { return }
       if (message.event === 'configure') {
@@ -163,11 +298,18 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
         setSaveState('saved')
       } else if ((message.event === 'autosave' || message.event === 'save') && typeof message.xml === 'string') {
         scheduleSave(message.xml, message.event === 'save')
+      } else if (message.event === 'export' && typeof message.data === 'string') {
+        const pending = pendingExport.current
+        pendingExport.current = null
+        setIsExporting(false)
+        if (pending) {
+          void handleExportResult(pending, message.data)
+        }
       }
     }
     window.addEventListener('message', receive)
     return () => window.removeEventListener('message', receive)
-  }, [src, dark, path, post, scheduleSave])
+  }, [src, dark, path, post, scheduleSave, handleExportResult])
 
   useEffect(() => {
     if (!ready || truncated) return
@@ -183,14 +325,23 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
       if (typeof document !== 'undefined' && document.hidden) return
 
       try {
-        const xml = await fsRead(scope, path)
+        // 轻量检查版本号
+        const stat = await fsStat(scope, path)
+        if (cancelled || isInteracting.current || Date.now() - lastUserActivity.current < 1200) return
+        if (stat.version && latestVersion.current && stat.version === latestVersion.current) return
+
+        const res = await fsRead(scope, path)
         // 5. 响应返回后二次防护：若这期间用户按下了鼠标或开始拖动，果断丢弃本次结果
         if (cancelled || isInteracting.current || Date.now() - lastUserActivity.current < 1200) return
-        if (xml === latestFile.current || xml === latestEditor.current) return
+        if (res.content === latestFile.current || res.content === latestEditor.current) {
+          latestVersion.current = res.version
+          return
+        }
 
-        latestFile.current = xml
-        latestEditor.current = xml
-        post({ action: 'load', xml, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 })
+        latestFile.current = res.content
+        latestEditor.current = res.content
+        latestVersion.current = res.version
+        post({ action: 'load', xml: res.content, autosave: 1, title: fileName(path), dark, noExitBtn: 1, saveAndExit: 0 })
         setSaveState('external')
         window.setTimeout(() => { if (!cancelled) setSaveState('saved') }, 1200)
       } catch (reason) {
@@ -204,17 +355,123 @@ function DrawioCanvas({ content, truncated, path, scope }: FileViewerProps): JSX
 
   useEffect(() => () => {
     if (saveTimer.current !== undefined) window.clearTimeout(saveTimer.current)
-    if (latestEditor.current !== latestFile.current) void fsWrite(scope, path, latestEditor.current, true)
+    if (latestEditor.current !== latestFile.current) void fsWrite(scope, path, latestEditor.current, latestVersion.current, true)
   }, [scope.sessionId, scope.cwd, path])
 
   if (truncated) return <CenteredMessage title="无法打开画板" detail="文件内容已被截断，继续编辑可能损坏原文件。" />
+
+  const targetExt = exportFormat === 'svg' ? '.svg' : exportFormat === 'xmlpng' ? '.drawio.png' : '.png'
+  const previewName = `${fileName(path).replace(/\.drawio$/i, '')}${targetExt}`
+
   return (
     <div style={styles.root}>
       <iframe ref={frame} title={`${fileName(path)} Draw.io 画板`} src={src} style={styles.frame} />
-      <div role="status" aria-live="polite" style={{ ...styles.status, ...(saveState === 'error' ? styles.statusError : {}) }}>
-        <span style={{ ...styles.dot, background: accentColor }} />{statusText(saveState)}
+
+      {/* 右上角悬浮导出工具面板 */}
+      <div ref={menuRef} style={styles.toolbar}>
+        <button
+          type="button"
+          onClick={() => setMenuOpen(open => !open)}
+          disabled={!ready || isExporting}
+          style={{ ...styles.exportTrigger, ...(isExporting ? styles.triggerActive : {}) }}
+          title="导出当前画板为图片"
+        >
+          <CameraIcon size={14} />
+          <span>{isExporting ? '正在导出...' : '导出图片'}</span>
+          <span style={styles.arrowIcon}>▾</span>
+        </button>
+
+        {menuOpen ? (
+          <div style={styles.exportMenu}>
+            <div style={styles.menuHeader}>
+              <span style={styles.menuTitle}>导出画板图片</span>
+              <span style={styles.menuSub}>{previewName}</span>
+            </div>
+
+            <div style={styles.formatRow}>
+              {(['png', 'svg', 'xmlpng'] as const).map(fmt => (
+                <button
+                  key={fmt}
+                  type="button"
+                  onClick={() => setExportFormat(fmt)}
+                  style={{
+                    ...styles.formatBtn,
+                    ...(exportFormat === fmt ? { ...styles.formatBtnActive, borderColor: accentColor } : {}),
+                  }}
+                >
+                  {fmt === 'png' ? 'PNG (超清)' : fmt === 'svg' ? 'SVG (矢量)' : 'XML-PNG'}
+                </button>
+              ))}
+            </div>
+
+            {exportFormat !== 'svg' ? (
+              <label style={styles.checkRow}>
+                <input
+                  type="checkbox"
+                  checked={isTransparent}
+                  onChange={e => setIsTransparent(e.target.checked)}
+                  style={styles.checkbox}
+                />
+                <span>透明背景</span>
+              </label>
+            ) : null}
+
+            <div style={styles.actionCol}>
+              <button
+                type="button"
+                onClick={() => startExport('workspace')}
+                style={{ ...styles.actionBtn, ...styles.actionBtnPrimary, background: accentColor }}
+              >
+                <SaveIcon size={13} />
+                <span>保存到工作区 ({targetExt})</span>
+              </button>
+
+              <button
+                type="button"
+                onClick={() => startExport('clipboard')}
+                style={styles.actionBtn}
+              >
+                <CopyIcon size={13} />
+                <span>复制到剪贴板</span>
+              </button>
+
+              <button
+                type="button"
+                onClick={() => startExport('download')}
+                style={styles.actionBtn}
+              >
+                <DownloadIcon size={13} />
+                <span>下载图片文件</span>
+              </button>
+            </div>
+          </div>
+        ) : null}
+      </div>
+
+      {/* Toast 提示 */}
+      {toast ? (
+        <div style={styles.toast}>
+          <CheckIcon size={14} />
+          <span>{toast}</span>
+        </div>
+      ) : null}
+
+      <div role="status" aria-live="polite" style={{ ...styles.status, ...(saveState === 'error' || saveState === 'conflict' ? styles.statusError : {}) }}>
+        <span style={{ ...styles.dot, background: saveState === 'conflict' ? 'var(--dsw-alias-warning, #e6a23c)' : accentColor }} />{statusText(saveState)}
       </div>
-      {error ? <button type="button" title={error} onClick={() => setError(null)} style={styles.error}>保存失败 · 点击关闭</button> : null}
+      {error ? (
+        <button
+          type="button"
+          title={error}
+          onClick={() => {
+            if (saveState === 'conflict') void reloadFromDisk()
+            setError(null)
+          }}
+          style={styles.error}
+        >
+          {saveState === 'conflict' ? '⚠️ 检测到外部修改 · 点击重新载入' : '保存失败 · 点击关闭'}
+        </button>
+      ) : null}
     </div>
   )
 }
@@ -260,13 +517,20 @@ function detectDark(): boolean {
   return document.documentElement.classList.contains('dark') || window.matchMedia('(prefers-color-scheme: dark)').matches
 }
 
-async function fsRead(scope: SessionScope, path: string, signal?: AbortSignal): Promise<string> {
-  const value = await call<{ content: string }>('read', scope, { path }, false, signal)
-  return value.content
+async function fsStat(scope: SessionScope, path: string, signal?: AbortSignal): Promise<{ version: string; size: number }> {
+  return call<{ version: string; size: number }>('stat', scope, { path }, false, signal)
 }
 
-async function fsWrite(scope: SessionScope, path: string, content: string, keepalive = false): Promise<void> {
-  await call('write', scope, { path, content }, keepalive)
+async function fsRead(scope: SessionScope, path: string, signal?: AbortSignal): Promise<{ content: string; version: string }> {
+  return call<{ content: string; version: string }>('read', scope, { path }, false, signal)
+}
+
+async function fsWrite(scope: SessionScope, path: string, content: string, version?: string, keepalive = false): Promise<{ version?: string }> {
+  return call<{ version?: string }>('write', scope, { path, content, ...(version ? { version } : {}) }, keepalive)
+}
+
+async function fsSaveImage(scope: SessionScope, path: string, data: string): Promise<{ path: string; bytes: number }> {
+  return call<{ path: string; bytes: number }>('save-image', scope, { path, data })
 }
 
 async function call<T = { ok: true }>(method: string, scope: SessionScope, extra: Record<string, unknown>, keepalive = false, signal?: AbortSignal): Promise<T> {
@@ -280,24 +544,78 @@ function CanvasIcon({ size = 16, className }: { size?: number; className?: strin
   return <svg className={className} aria-hidden viewBox="0 0 20 20" width={size} height={size} fill="none"><rect x="2.5" y="2.5" width="15" height="15" rx="2.5" stroke="currentColor"/><circle cx="7" cy="7" r="1.5" fill="currentColor"/><circle cx="13" cy="13" r="1.5" fill="currentColor"/><path d="M8.4 7.8l3.2 4.4M8.2 6.2h3.6M6.2 8.2v3.6" stroke="currentColor" strokeLinecap="round"/></svg>
 }
 
+function CameraIcon({ size = 16, className }: { size?: number; className?: string }): JSX.Element {
+  return <svg className={className} aria-hidden viewBox="0 0 20 20" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"><path d="M4 6.5A1.5 1.5 0 0 1 5.5 5h1.8a1.5 1.5 0 0 0 1.2-.6l.5-.7A1.5 1.5 0 0 1 10.2 3h1.6a1.5 1.5 0 0 1 1.2.7l.5.7a1.5 1.5 0 0 0 1.2.6h1.8A1.5 1.5 0 0 1 18 6.5v9a1.5 1.5 0 0 1-1.5 1.5h-13A1.5 1.5 0 0 1 2 15.5v-9z"/><circle cx="10" cy="11" r="3.5"/></svg>
+}
+
+function SaveIcon({ size = 16, className }: { size?: number; className?: string }): JSX.Element {
+  return <svg className={className} aria-hidden viewBox="0 0 20 20" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"><path d="M16 17H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h9.5l3.5 3.5V16a1 1 0 0 1-1 1z"/><path d="M13 17v-6H7v6"/><path d="M7 3v4h6"/></svg>
+}
+
+function CopyIcon({ size = 16, className }: { size?: number; className?: string }): JSX.Element {
+  return <svg className={className} aria-hidden viewBox="0 0 20 20" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"><rect x="7" y="7" width="10" height="10" rx="1.5"/><path d="M4 13H3.5A1.5 1.5 0 0 1 2 11.5v-8A1.5 1.5 0 0 1 3.5 2h8A1.5 1.5 0 0 1 13 3.5V4"/></svg>
+}
+
+function DownloadIcon({ size = 16, className }: { size?: number; className?: string }): JSX.Element {
+  return <svg className={className} aria-hidden viewBox="0 0 20 20" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round"><path d="M10 3v10m0 0l-3.5-3.5M10 13l3.5-3.5"/><path d="M3 14v2a1.5 1.5 0 0 0 1.5 1.5h11a1.5 1.5 0 0 0 1.5-1.5v-2"/></svg>
+}
+
+function CheckIcon({ size = 16, className }: { size?: number; className?: string }): JSX.Element {
+  return <svg className={className} aria-hidden viewBox="0 0 20 20" width={size} height={size} fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M4 10.5l4 4 8-9"/></svg>
+}
+
 function CenteredMessage({ title, detail }: { title: string; detail: string }): JSX.Element {
   return <div style={styles.center}><strong>{title}</strong><span style={styles.muted}>{detail}</span></div>
 }
 
 const fileName = (path: string): string => path.replace(/\\/g, '/').split('/').pop() || path
-function parseDrawioAddress(address: string): { sessionId: string; path: string } | null {
-  const prefix = 'dsh-resource://file/session/'
-  if (!address.startsWith(prefix)) return null
+
+export function parseDrawioAddress(address?: string, fallbackSessionId?: string): { sessionId: string; path: string } | null {
+  if (!address || typeof address !== 'string') return null
   try {
-    const parts = address.slice(prefix.length).split('/').map(decodeURIComponent)
-    const sessionId = parts.shift() ?? ''
-    const path = parts.join('/')
-    if (!sessionId || !path || !/\.drawio$/i.test(path) || parts.some(part => part.includes('/') || part.includes('\\') || part.includes('\0'))) return null
-    return { sessionId, path }
-  } catch { return null }
+    let clean = address.trim()
+    let parsedSessionId = ''
+
+    if (clean.startsWith('dsh-resource://file/session/')) {
+      const rest = clean.slice('dsh-resource://file/session/'.length)
+      const slashIdx = rest.indexOf('/')
+      if (slashIdx >= 0) {
+        parsedSessionId = decodeURIComponent(rest.slice(0, slashIdx))
+        clean = rest.slice(slashIdx + 1)
+      } else {
+        clean = rest
+      }
+    } else if (clean.startsWith('dsh-resource://file/')) {
+      clean = clean.slice('dsh-resource://file/'.length)
+    } else if (clean.startsWith('file:///')) {
+      clean = clean.slice('file:///'.length)
+    }
+
+    // 处理可能是 URL 编码的 path（支持嵌套目录 %2F）
+    let decodedPath = clean
+    try {
+      decodedPath = decodeURIComponent(clean)
+    } catch {}
+
+    // 规范化斜杠并去除开头的斜杠
+    decodedPath = decodedPath.replace(/\\/g, '/').replace(/^\/+/, '')
+
+    // 必须是 .drawio 文件
+    if (!/\.drawio$/i.test(decodedPath)) return null
+
+    // 防空字符
+    if (decodedPath.includes('\0')) return null
+
+    return {
+      sessionId: parsedSessionId || fallbackSessionId || '',
+      path: decodedPath,
+    }
+  } catch {
+    return null
+  }
 }
 const messageOf = (reason: unknown): string => reason instanceof Error ? reason.message : String(reason)
-const statusText = (state: string): string => state === 'loading' ? '正在载入' : state === 'saving' ? '正在保存' : state === 'external' ? '已同步 AI 修改' : state === 'error' ? '保存失败' : '已保存'
+const statusText = (state: string): string => state === 'loading' ? '正在载入' : state === 'saving' ? '正在保存' : state === 'external' ? '已同步 AI 修改' : state === 'conflict' ? '检测到冲突' : state === 'error' ? '保存失败' : '已保存'
 const fg = 'var(--dsw-alias-label-primary, currentColor)'
 const muted = 'var(--dsw-alias-label-secondary, rgba(127,127,127,.9))'
 const layer = 'var(--dsw-alias-container-bg, Canvas)'
@@ -306,6 +624,23 @@ const accent = 'var(--dsw-alias-brand-primary, #ed67ad)'
 const styles: Record<string, React.CSSProperties> = {
   root: { position: 'relative', width: '100%', height: '100%', minHeight: 0, overflow: 'hidden', color: fg, background: layer },
   frame: { display: 'block', width: '100%', height: '100%', border: 0, background: layer },
+  toolbar: { position: 'absolute', right: 12, top: 12, zIndex: 10, display: 'flex', flexDirection: 'column', alignItems: 'flex-end' },
+  exportTrigger: { display: 'flex', alignItems: 'center', gap: 6, padding: '5px 10px', border: `1px solid ${border}`, borderRadius: 6, color: fg, background: layer, boxShadow: 'var(--dsw-alias-shadow-sm, 0 2px 8px rgba(0,0,0,.12))', fontSize: 12, fontWeight: 500, cursor: 'pointer', backdropFilter: 'blur(8px)', transition: 'all 0.15s ease' },
+  triggerActive: { opacity: 0.75, cursor: 'wait' },
+  arrowIcon: { fontSize: 10, opacity: 0.6, marginLeft: 2 },
+  exportMenu: { marginTop: 6, width: 220, padding: 12, border: `1px solid ${border}`, borderRadius: 8, background: layer, boxShadow: 'var(--dsw-alias-shadow-md, 0 6px 20px rgba(0,0,0,.18))', backdropFilter: 'blur(12px)', display: 'flex', flexDirection: 'column', gap: 10 },
+  menuHeader: { display: 'flex', flexDirection: 'column', gap: 2, paddingBottom: 6, borderBottom: `1px solid ${border}` },
+  menuTitle: { fontSize: 12, fontWeight: 600, color: fg },
+  menuSub: { fontSize: 10, color: muted, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' },
+  formatRow: { display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: 4 },
+  formatBtn: { padding: '4px 2px', border: `1px solid ${border}`, borderRadius: 4, background: 'transparent', color: muted, fontSize: 10.5, cursor: 'pointer', textAlign: 'center', transition: 'all 0.1s ease' },
+  formatBtnActive: { color: fg, fontWeight: 600, background: 'var(--dsw-alias-fill-quaternary, rgba(127,127,127,0.12))' },
+  checkRow: { display: 'flex', alignItems: 'center', gap: 6, fontSize: 11, color: muted, cursor: 'pointer', userSelect: 'none' },
+  checkbox: { cursor: 'pointer', margin: 0 },
+  actionCol: { display: 'flex', flexDirection: 'column', gap: 6, paddingTop: 4 },
+  actionBtn: { display: 'flex', alignItems: 'center', justifyContent: 'center', gap: 6, padding: '6px 10px', border: `1px solid ${border}`, borderRadius: 5, background: 'transparent', color: fg, fontSize: 11.5, cursor: 'pointer', transition: 'all 0.12s ease' },
+  actionBtnPrimary: { color: '#ffffff', border: 'none', fontWeight: 500 },
+  toast: { position: 'absolute', top: 12, left: '50%', transform: 'translateX(-50%)', zIndex: 12, display: 'flex', alignItems: 'center', gap: 6, padding: '6px 14px', border: `1px solid ${border}`, borderRadius: 20, background: layer, color: fg, boxShadow: 'var(--dsw-alias-shadow-md, 0 4px 14px rgba(0,0,0,.16))', fontSize: 12, backdropFilter: 'blur(10px)', pointerEvents: 'none' },
   status: { position: 'absolute', right: 10, bottom: 9, zIndex: 2, display: 'flex', alignItems: 'center', gap: 6, padding: '4px 8px', border: `1px solid ${border}`, borderRadius: 999, color: muted, background: layer, boxShadow: 'var(--dsw-alias-shadow-sm, 0 2px 8px rgba(0,0,0,.12))', fontSize: 11, pointerEvents: 'none' },
   statusError: { color: 'var(--dsw-alias-danger, #d84f5f)' },
   dot: { width: 6, height: 6, borderRadius: 99, background: accent },