// docs / design-mode

Design Mode

在 Studio live preview 里点选元素，微调文案与样式，并写回源码。定位靠编译期源坐标；写盘靠服务端 JSX AST（ADR-0001）。

概览

Preview DOM 不是源码。Design Mode 用编译期注入的 data-ox-source（file:line:col）把选中节点映射到唯一 JSX，再在服务端突变静态 className / 静态文案。

能力	说明
点选	iframe bridge 采集带 source 的 VisualEdit
可调属性	color · font-size · padding · border-radius · 静态文案
Direct Apply	POST …/design-mode/patch → AST 写盘 → HMR
失败出口	预填 Modify 草稿，用户确认后走 Agent

数据流

Preview (instrumented next-dev)
  └── data-ox-source on DOM
  └── design-mode-bridge.js
        │  VisualEdit[] { source, tag, props… }
Studio  └── DesignModePreviewOverlay / useDesignMode
        │
        ├── Direct capable?
        │     yes → POST /api/projects/[id]/design-mode/patch
        │            snapshot → AST mutate → prettier → verify → hot refresh
        └── no / A-class fail
              → Modify draft prefill → user confirm → runModifyProject

Preview 只负责采集，不写盘。唯一自动写盘路径是 Direct Apply；Modify 不是第二条的 Apply 适配器。

Direct Apply

定位

主键 = data-ox-source。无坐标或歧义时不猜，走预检失败 → Modify。遗留的 data-ox-id / ripgrep 不再作为主路径。

突变范围

服务端 JSX AST：静态字符串 className（Tailwind utility upsert）与静态 JSX 文本。动态表达式、条件渲染歧义 → 不写盘。

API

POST /api/projects/[id]/design-mode/patch
Body: { edits: VisualEdit[] }

POST /api/projects/[id]/design-mode/backfill
  → 为历史项目补齐源坐标锚点

Modify 出口

静态 site-previews、非 local 后端、或 AST 无法安全突变时： Studio 把选中上下文预填进 Modify 输入，用户确认后走完整 Agent + build。

开关与前提

NEXT_PUBLIC_STUDIO_DESIGN_MODE=1
OPEN_OX_PREVIEW_BACKEND=local   # Direct Apply 需要 local next-dev

# Direct Apply 关闭时返回 403 DIRECT_EDIT_DISABLED

生产若默认 storage 静态预览，点选仍可采集并走 Modify 出口；Direct Apply 仅在 local 预览链路启用。

系统架构修改 Agent