#ClickDeck Core 使用指南

ClickDeck Core 是一个浏览器端可视化编辑器核心模块，作为 QuickUIDesign 的 DevTools 集成组件使用。本文档介绍如何在项目中安装、集成、配置和使用 ClickDeck Core。

#安装

ClickDeck Core 内置于 QuickUIDesign 中，在开发环境下自动激活。集成到项目的方式如下：

# 使用 QuickUIDesign 脚手架时，ClickDeck Core 已预配置
npm install
npm run dev

如需手动集成，请确保项目中包含以下依赖：

• TypeScript（严格模式）
• DOM API（MutationObserver、FileReader、Canvas、Fullscreen API）
• localStorage 持久化支持

#集成方式

#作为 DevTools 组件

ClickDeck Core 作为 DevTools 面板集成到应用的开发环境中：

import ClickDeckDevTools from '@dev/react/ClickDeckDevTools'
import { ClickDeckToggle } from '@/dev-tools/react/ClickDeckToggle'

//在根组件下引入
<ClickDeckDevTools />
<ClickDeckToggle />

#激活方式

首次激活时，编辑器会自动完成初始化（创建 Overlay、Panel、事件监听）。面板默认位于页面右下角，可拖拽到任意位置。

#基本工作流

#路径 A：直接样式编辑（快速微调）

适合轻量级样式修改（字号、颜色、间距、对齐等），所见即所得。

1. 激活编辑器        → Alt+Shift+C 或点击右上角按钮
2. 选中目标元素      → 鼠标悬停预览高亮，点击选中
3. 面板中做样式调整  → 点按各功能按钮
4. 可选：继续选其他  → 重复步骤 2-3
5. 撤销或重做        → 面板 Undo/Redo（或 Ctrl+Z / Ctrl+Shift+Z）
6. 关闭编辑器        → Alt+Shift+C 或点击 Close

#路径 B：意图标注 + AI Prompt 导出（复杂修改）

适合涉及移动、删除、自定义操作或需要描述具体意图的场景。

1. 激活编辑器         → Alt+Shift+C
2. 点击 "Add suggestion" → 进入框选模式
3. 页面拖拽框选区域   → 松开鼠标完成框选
4. 填写操作说明       → 标记操作类型
5. 可添加多条意图     → 重复步骤 2-4
6. 可选：做样式编辑   → 作为实际补丁一同导出
7. 点击 "Copy AI edit prompt" → 复制 Prompt
8. 粘贴给 AI 执行     → 让代码生成工具执行修改

#元素选中

选中后面板顶部显示 Selected: div.classname 形式的元素描述。文本标签（h1~h6、p、span、a、li、strong、em）点击后自动变为可编辑状态，可直接在页面上修改文字。

#样式调整

面板功能按钮根据选中元素类型动态切换：

#文本元素（h1-h6, p, span, a, li）

#容器元素（div, section）

#图片元素

#撤销 / 重做

• 面板操作：点击 History 区域的 Undo / Redo 按钮
• 快捷键：Ctrl+Z 撤销，Ctrl+Shift+Z 重做
• 分组撤销：同一时刻对同一元素的多个样式修改作为一组撤销/重做
• 注意事项：编辑文本时快捷键不生效（避免干扰原生输入撤销）

#导出为 AI Prompt

这是 ClickDeck Core 的核心能力。它将直接样式修改和意图标注合并输出为一份结构化的 AI 编辑指令。

#导出流程

1. 完成页面修改（样式调整 / 意图标注 / 文本编辑 / 图片替换等）
2. 点击 "Copy AI edit prompt" 按钮
3. Prompt 预览窗口弹出（支持英文和中文版本）
4. 可在预览窗口手动编辑 Prompt 文本
5. 点击 "Copy" 复制到剪贴板
6. 粘贴给 coding AI（如 Claude、Cursor、Copilot 等）
7. AI 根据任务清单逐项执行修改

#Prompt 内容结构

典型 AI Prompt 包含：

• 页面上下文：URL、标题、范围
• 执行任务清单：带目标和详细说明的任务项
• 定位提示：如何在 DOM 中查找元素
• 全局编辑规则：保持无关内容不变
• 任务详情：逐个补丁描述和意图说明
• 最终一致性检查清单：视觉对比指南

#何时使用哪种方式

#AI 页面评审

面板提供三类评审 Prompt，编辑前让 AI 分析页面：

使用方式：点击按钮 → Prompt 复制到剪贴板 → 粘贴给能看见页面的 AI（如 Gemini）。

#数据持久化

ClickDeck 在 localStorage 中保存编辑补丁，键为 clickdeck:page-edits:v1:{origin}{pathname}{search}。

恢复编辑： 刷新页面重新打开编辑器时，如果检测到未提交的编辑，面板显示 "Saved edits found (N)" 提示：

• Restore — 重新应用所有补丁
• Clear — 清除保存的编辑

注意： 持久化补丁仅包含可序列化的样式和属性修改。文本内容修改（ContentPatch）反序列化后需重新 DOM 匹配定位元素。

#面板操作

#架构概览

ClickDeck Core 采用分层架构：

┌─────────────────────────────────────┐
│         Controller（编排层）          │
├─────────────────────────────────────┤
│   Content 模块    │   Export 模块    │
│（选中、样式、     │  （Prompt 生成、 │
│  历史记录、意图）  │    序列化器）    │
├─────────────────────────────────────┤
│      DOM API 层（MutationObserver、   │
│     FileReader、Canvas、Fullscreen）  │
└─────────────────────────────────────┘

关键设计决策：

1. 非破坏性编辑：所有修改通过内联样式 + 补丁记录实现，不修改源文件
2. "软意图"模式：意图编辑产生 AI Prompt 而非直接操作 DOM
3. React 兼容：MutationObserver 检测并重新应用覆盖的修改
4. 渐进式调整：固定增量而非绝对值，适合快速迭代微调

#最佳实践

1. 先做直接编辑，再标注意图 — 面板能做的直接做，AI Prompt 会同时包含实际补丁和意图说明
2. 意图文字要具体 — 不要写 "优化这里"，而是写 "把这个标题字号加大、颜色改为蓝色、添加下方阴影"
3. 框选要精确 — 框选范围尽量贴合目标元素，减少 AI 误判
4. 检查 Prompt 内容 — 确认任务清单完整、定位信息准确后再复制
5. 逐页操作 — 每次 Prompt 只处理一个页面的修改，多页需求分别导出