isjunrod/buildev

`。 | | **与代码同步的活画布** | 场景图是唯一的真实来源。视觉编辑、AI 编辑和导出都作用于同一个模型。 | ## 核心功能 | 界面 | 当前功能 | 状态 | | --- | --- | --- | | **可编辑画布** | 选择、移动、调整大小、分组/取消分组、层级顺序、复制、删除、内联文本编辑 | 可用 | | **图层面板** | 节点树、可见性、锁定、重新排序 | 可用 | | **属性检查器** | 位置、大小、填充、圆角、排版、布局 | 可用 | | **AI 聊天 (模拟)** | 确定性提示词 → 编辑器动作规划器 | 可用 | | **AI 聊天 (真实提供者)** | 兼容 OpenAI 的 JSON 模式提供者，返回经过验证的动作 | 可用 (需要 API 密钥) | | **逆向 UI (截图)** | 启发式区块 + 列检测 → 可编辑框架 + 节点 | 可用，保真度较低 | | **React + Tailwind 导出** | 生成一个独立的 `App.tsx`，并提取重复的组件 | 可用，属于 MVP 质量 | | **本地持久化** | 通过 `localStorage` (`buildev-editor-state-v1`) 持久化编辑器状态 | 可用 | | **撤销 / 重做** | `editor-core` 中基于动作的历史记录 | 可用 | | **响应式预览** | 设备边框 (桌面/平板/移动端) | 部分实现 | | **Monaco 代码编辑器** | 实时代码/画布双向同步 | 未实现 | | **多人协作 / 身份验证 / 计费** | — | 超出此阶段范围 | ## 系统架构 Buildev 被组织为一个 **pnpm monorepo**，包含一个 Next.js 应用程序和一组领域包。每个包都有明确的职责和类型化契约，这使得 AI 和导出界面具有可组合性，而不是纠缠不清。 ``` flowchart TB subgraph App["apps/web — Next.js 16 App Router"] UI[Editor Shell
TopBar · Layers · Canvas · Properties · Chat · Export] Store[(Zustand Store
useEditorStore)] API1[/api/ai/chat/] API2[/api/reverse-ui/] UI <--> Store UI --> API1 UI --> API2 end subgraph Pkgs["packages/* — Domain Layer"] SG[scene-graph
Canonical Model] EC[editor-core
Actions · Undo · Reducers] AI[ai
Providers · Planner] VIS[vision
Reverse UI · CV Heuristics] EXP[exporters
React + Tailwind] UIPKG[ui
Shared primitives] SHARED[shared
IDs · Utils · Types] end Store --> EC EC --> SG API1 --> AI AI --> EC AI --> SG API2 --> VIS VIS --> SG UI --> EXP EXP --> SG UIPKG -.-> UI SHARED -.-> SG SHARED -.-> EC SHARED -.-> AI SHARED -.-> VIS SHARED -.-> EXP classDef app fill:#0d0d0d,stroke:#B8FF5A,color:#fff classDef pkg fill:#1a1a1a,stroke:#666,color:#fff class App app class Pkgs pkg ``` **为什么采用这种结构？** - **场景图**是规范模型。其他所有内容都是对它的转换。 - **editor-core** 包通过经过验证的动作（Zod schemas）管理状态变更，因此 AI 生成的编辑和用户生成的编辑经过相同的管道。 - **AI** 和 **vision** 包生成符合场景图契约的动作和节点——它们不会破坏该契约。 - **exporters** 包读取场景图并输出代码。它不需要内省 React 组件。 ## 场景图 场景图是用户看到和编辑的一切内容的唯一真实来源。每个节点都包含布局、样式、语义角色以及**来源**（是手动创建的、由 AI 创建的，还是从截图重建的？）。这种来源追溯使得可审计的往返操作成为可能。 ``` classDiagram class SceneDocument { +string id +string name +Record~ScenePage~ pages +string[] pageOrder +Record~SceneNode~ nodes +string activePageId } class ScenePage { +string id +string name +string[] rootIds +number width +number height } class SceneNode { +string id +SceneNodeType type +string name +string|null parentId +string[] children +number x, y, width, height +number rotation, opacity, zIndex +ColorFill fill +StrokeStyle stroke +number borderRadius +ShadowStyle[] shadows +TypographyStyle typography +SpacingStyle spacing +LayoutStyle layout +ConstraintsStyle constraints +boolean visible, locked +string semanticRole +Record variantProps +ExportMetadata exportMeta +SourceProvenance provenance +string textContent +string imageSrc } class SourceProvenance { +ProvenanceSource source +string prompt +string screenshotName +number confidence +string[] notes } SceneDocument "1" --> "*" ScenePage SceneDocument "1" --> "*" SceneNode SceneNode "1" --> "0..1" SceneNode : parent SceneNode "1" --> "*" SceneNode : children SceneNode "1" --> "1" SourceProvenance ``` ### 支持的节点类型 `Page` · `Frame` · `Group` · `Rectangle` · `Ellipse` · `Line` · `Text` · `Image` · `Icon` · `Button` · `Input` · `Textarea` · `Checkbox` · `Radio` · `Switch` · `Select` · `Tabs` · `Badge` · `Card` · `Modal` · `Navbar` · `Sidebar` · `List` · `Grid` · `Table` · `Chart` · `Container` 每个节点都通过 Zod 模式进行验证（参见 [packages/scene-graph/src/index.ts](packages/scene-graph/src/index.ts)），因此损坏的数据——包括 AI 产生的错误——无法进入文档。 ## AI 流水线 AI 界面遵循“规划 → 验证 → 应用”的模型。模型永远不会直接改变文档；它返回由 **editor-core** 验证并应用的**动作**。这为 Buildev 提供了一个单一的审查点，用于审计 AI 的所有行为。 ``` sequenceDiagram participant U as User participant CP as ChatPanel participant API as /api/ai/chat participant P as AI Provider participant V as editor-core
(Zod validator) participant S as Zustand Store participant C as Canvas U->>CP: Types prompt ("add a pricing section") CP->>API: POST { prompt, document, selectedIds } API->>P: getAIProvider().planEditorActions(ctx) alt BUILDEV_AI_MODE=provider P->>P: Call OpenAI-compatible chat completion
(JSON mode) else default P->>P: MockAIProvider — deterministic heuristics end P-->>API: { summary, actions[], mode } API-->>CP: Response CP->>V: applyAction(action) for each V->>V: editorActionSchema.parse(action) V->>S: Commit validated mutation S->>C: Re-render canvas C-->>U: Visible update + summary in chat ``` ### 动作类型 AI 可以发出（用户也可以重放）以下任何动作： - `createNode` — 在父节点下添加一个新的类型化节点。 - `setStyles` — 修补填充、排版、圆角、阴影、布局。 - `generateComponent` — 批量创建一个连贯的组（例如定价网格）。 - `replaceSubtree` — 原子性地替换子树（用于“将其变为表格”、截图导入、完整落地页种子）。 如果提示词不匹配更丰富的命令，模拟提供者会退而在画布上留下一个带标签的 `Text` 备注——这样用户总能得到一个可见的、可审计的响应，而不是无声的失败。 ## 逆向 UI 工程流水线 逆向 UI 是最具差异化的界面。纯 LLM 猜测对于布局来说太不可靠了；纯启发式方法不能单独推断出语义。Buildev 使用**分阶段混合流水线**（参见 [ADR-0003](docs/adr/0003-hybrid-reverse-ui-pipeline.md))： ``` flowchart LR A[Screenshot
data: URL] --> B[Decode
Jimp.read] B --> C[Preprocess
greyscale + contrast] C --> D[Row Density Scan
detect horizontal sections] D --> E[Column Density Scan
detect cards / columns per section] E --> F{Section type?} F -->|h<140 & first| G[Navbar] F -->|cols≥3| H[Grid + Cards] F -->|index=1| I[Card] F -->|else| J[Container + Text] G --> K[SceneNode] H --> K I --> K J --> K K --> L[Wrap in Frame
provenance: screenshot] L --> M[POST to store
importScreenshotNodes] M --> N[Editable canvas] classDef stage fill:#1a1a1a,stroke:#B8FF5A,color:#fff classDef decision fill:#2a2a2a,stroke:#FFB85A,color:#fff class A,B,C,D,E,K,L,M,N stage class F decision ``` **为什么采用这种设计？** - **确定性与可调试性。** 启发式方法是可检查的；故障模式是可重现的。 - **优雅降级。** 即使完全没有 LLM 访问权限也能工作。 - **明确的升级路径。** OCR（用于真实文本）、CV 升级（用于图标检测）以及可选的 LLM 规范化过程可以作为阶段插入，而无需重写流水线。 **目前还不能做到：** - 没有 OCR——检测到的文本块带有占位符内容。 - 没有图标/字形识别。 - 没有字体匹配。 - 除了默认调色板之外，没有颜色提取。 请将输出视为**忠实于布局的可编辑骨架**，而不是 1:1 的重建。 ## 编辑器 UI 流程 编辑器是一个顶部带有工具栏的三栏工作区。每个面板都读取并写入同一个 Zustand store，而该 store 是唯一与 `editor-core` 通信的组件。 ``` flowchart TB TB[TopBar
Undo · Redo · Toggle Chat · Toggle Code · Reset] LP[Layers Panel
tree · select · lock · visibility] CV[Canvas Panel
select · drag · resize · text edit] EX[Export Panel
generated React + Tailwind] PR[Properties Panel
position · size · fill · text · radius] CH[Chat Panel
AI prompt · summary · history] TB --> LP TB --> CV TB --> PR LP -.selection.-> CV CV -.selection.-> PR CH -.actions.-> CV CV -.scene graph.-> EX classDef panel fill:#0d0d0d,stroke:#444,color:#fff classDef top fill:#1a1a1a,stroke:#B8FF5A,color:#fff class LP,CV,PR,CH,EX panel class TB top ``` 源码: [apps/web/components/editor/editor-app.tsx](apps/web/components/editor/editor-app.tsx) ## 导出流水线 导出器遍历场景图，检测重复的同级子树（相同类型 + 相同子类型签名 + 相同大小），并将它们提取为可复用的组件。输出是一个单独的 `App.tsx` 及其支持文件。 ``` flowchart LR SG[SceneDocument] --> WALK[Walk active page
depth-first] WALK --> SIG[Compute node signatures
type:childTypes:w:h] SIG --> DUP{≥2 matching
siblings?} DUP -->|yes| EXTRACT[Extract as
named component] DUP -->|no| INLINE[Inline markup] EXTRACT --> RENDER INLINE --> RENDER[renderNode
per type] RENDER --> JSX[Generated JSX
+ Tailwind classes] JSX --> FILE[App.tsx] classDef stage fill:#1a1a1a,stroke:#B8FF5A,color:#fff classDef decision fill:#2a2a2a,stroke:#FFB85A,color:#fff class SG,WALK,SIG,EXTRACT,INLINE,RENDER,JSX,FILE stage class DUP decision ``` **干净之处在于：** 重复的卡片变成了一个真正的组件，而不是三个重复的代码块。 **还不够干净之处在于：** 布局仍然依赖于绝对定位和任意的 Tailwind 值（`w-[384px]`、`left-[48px]`）。未来的迭代需要将场景图中的 flex 布局转换为符合习惯的 Tailwind 实用类。 ## 技术栈 | 层级 | 选择 | 原因 | | --- | --- | --- | | **Monorepo** | pnpm workspaces | 快速、严格，与 Next.js + TS 项目引用配合良好 | | **应用框架** | Next.js 16 (App Router) | Server actions、路由处理程序、在有帮助的地方使用 RSC | | **语言** | TypeScript 5.8 (strict) | 场景图是强类型的；严格模式可以在验证时捕获 AI 生成的错误 | | **样式** | Tailwind CSS 4.1 | 与导出目标直接匹配 | | **状态管理** | Zustand 5 |一 store，没有 provider 嵌套地狱，易于持久化 | | **验证** | Zod 3.24 | 所有编辑器动作和节点类型都在边界处进行验证 | | **CV / 视觉** | Jimp | 纯 JS 图像处理，无本地依赖 | | **AI** | 兼容 OpenAI (可配置 base URL/模型) + 确定性模拟 | 支持离线和在线工作 | | **测试** | Vitest 3 + jsdom | 针对 editor-core 和 exporters 的快速单元测试 | | **Lint / 格式化** | ESLint 9 + Prettier 3 | — | | **图标** | lucide-react | — | ## 仓库目录结构 ``` buildev/ ├── apps/ │ └── web/ # Next.js 16 App Router shell │ ├── app/ │ │ ├── api/ │ │ │ ├── ai/chat/ # AI planner endpoint │ │ │ └── reverse-ui/ # Screenshot → scene endpoint │ │ ├── globals.css │ │ ├── layout.tsx │ │ └── page.tsx # Mounts │ ├── components/editor/ │ │ ├── editor-app.tsx │ │ ├── top-bar.tsx │ │ ├── layers-panel.tsx │ │ ├── canvas-panel.tsx │ │ ├── properties-panel.tsx │ │ ├── chat-panel.tsx │ │ └── export-panel.tsx │ ├── lib/store.ts # Zustand store + hydration │ └── public/ # Logos, marketing assets │ ├── packages/ │ ├── scene-graph/ # Canonical SceneDocument / SceneNode types │ ├── editor-core/ # Actions, reducers, undo/redo │ ├── ai/ # Mock + OpenAI-compatible providers │ ├── vision/ # Reverse-UI heuristic pipeline (Jimp) │ ├── exporters/ # React + Tailwind codegen │ ├── ui/ # Shared UI primitives │ └── shared/ # IDs, utils, common types │ ├── docs/ │ ├── product/brief.md │ ├── architecture/ │ │ ├── system-overview.md │ │ ├── roadmap.md │ │ └── progress-log.md │ └── adr/ │ ├── 0001-adopt-monorepo-and-domain-packages.md │ ├── 0002-scene-graph-as-canonical-model.md │ └── 0003-hybrid-reverse-ui-pipeline.md │ ├── pnpm-workspace.yaml ├── tsconfig.base.json ├── vitest.config.ts └── README.md ``` ## 开始使用 ### 前置条件 - **Node.js** ≥ 20 - **pnpm** ≥ 10.30 (`npm install -g pnpm`) ### 1. 克隆 ``` git clone https://github.com/isjunrod/Buildev.git cd Buildev ``` ### 2. 安装 ``` pnpm install ``` ### 3. 配置环境 ``` cp .env.example .env ``` 默认配置在开箱即用的**模拟 AI 模式**下即可正常工作——不需要 API 密钥即可查看运行中的编辑器。 ### 4. 运行 ``` pnpm dev ``` 打开 [http://localhost:3000](http://localhost:3000)。编辑器在首次加载时会使用一个金融科技着陆页模板进行自我初始化。 ### 5. 构建 ``` pnpm build pnpm start ``` ### 6. 测试 ``` pnpm test pnpm typecheck pnpm lint ``` ## 环境变量 | 变量 | 默认值 | 用途 | | --- | --- | --- | | `NEXT_PUBLIC_APP_URL` | `http://localhost:3000` | 面向公众的应用 URL | | `NEXT_PUBLIC_ENABLE_AI_FEATURES` | `true` | AI 界面的 UI 开关 | | `NEXT_PUBLIC_ENABLE_AUTH` | `false` | 身份验证目前超出范围 | | `BUILDEV_AI_MODE` | `mock` | 设置为 `provider` 以使用真实的 OpenAI 兼容模型 | | `OPENAI_API_KEY` | — | 当 `BUILDEV_AI_MODE=provider` 时必填 | | `OPENAI_BASE_URL` | `https://api.openai.com/v1` | 兼容 OpenAI 的网关覆盖 | | `OPENAI_MODEL` | `gpt-4.1-mini` | 提供者使用的模型名称 | ## 可用脚本 | 脚本 | 作用 | | --- | --- | | `pnpm dev` | 运行 Next.js 开发服务器 (`apps/web`) | | `pnpm build` | Web 应用的生产环境构建 | | `pnpm start` | 启动生产环境服务器 | | `pnpm lint` | 对 `apps/web` 和 `packages/*` 运行 ESLint | | `pnpm test` | 在所有包中运行 Vitest | | `pnpm typecheck` | 对 web 应用运行 `tsc --noEmit` | ## 路线图 以下阶段与 [docs/architecture/roadmap.md](docs/architecture/roadmap.md) 中的内容相匹配。 ``` gantt title Buildev Roadmap dateFormat YYYY-MM-DD section Phase 0 — Foundation Repo audit & ADRs :done, p0a, 2026-03-25, 2d Domain packages + scene graph :done, p0b, after p0a, 2d section Phase 1 — Stabilization Type-safe store contract :active, p1a, 2026-05-01, 14d Unify AI surfaces : p1b, after p1a, 10d Export MVP polish : p1c, after p1b, 10d section Phase 2 — Experience Dexie persistence : p2a, 2026-06-15, 14d Real Monaco code mode : p2b, after p2a, 14d Design tokens + constraints : p2c, after p2b, 14d section Phase 3 — Product Multi-file export : p3a, 2026-08-01, 21d Component library reuse : p3b, after p3a, 14d Observability for AI flows : p3c, after p3b, 14d ``` **P0 — 基础：** 可编辑画布、聊天 → 画布、截图 → 画布、React+Tailwind 导出、可靠的 UI。 **P1 — 稳定：** 额外的导出器、解析器改进、设计令牌、撤销/重做优化、本地版本控制。 **P2 — 体验：** 从实体照片/海报中恢复、实时协作、设计系统、插件系统。 **超出初始范围：** 计费 · 复杂身份验证 · 企业基础设施 · 完整多人协作 · 管理面板 · 插件市场 · 外观特性。 ## 已知问题与局限性 在提交 bug 之前请注意这些问题——它们都在跟踪中，并非意外： - **TypeScript 偏差。** 旧版文件夹（位于仓库根目录的 `app/`、`components/`，早于 monorepo 迁移）中的某些面板引用了已不存在的 store 字段。`pnpm typecheck` 可能会暴露出那里的错误。 - **两个并行的应用树。** 仓库目前同时包含 monorepo 之前根目录下的 `app/` + `components/` 目录以及新的 `apps/web/...` 树。活动的运行时**仅限** `apps/web`。一旦迁移完成，根目录的副本将被删除。 - **模拟 AI 是默认设置。** 除非你设置 `BUILDEV_AI_MODE=provider` 和有效的 `OPENAI_API_KEY`，否则所有聊天响应都来自一个小型确定性规划器。这是有意为之——UI 绝不能在等待 API 时卡住。 - **逆向 UI 没有 OCR。** 检测到的部分中的文本是占位符。接入 Tesseract 或视觉 LLM 属于 P2 路线图。 - **导出器使用任意的 Tailwind 值。** 位置和大小以 `left-[NNNpx]` 等形式输出。将 flex 布局转换为符合习惯的实用类是一项已知的后续工作。 - **没有真正的持久层。** 状态仅保存在 `localStorage` 中。`lib/db/` 中存在 Dexie 脚手架，但尚未接入编辑器流程。 - **没有多人协作、没有身份验证、没有计费。** 故意超出范围。 如果你遇到了不在此列表中的问题，请提交 issue。 ## 架构决策记录 Buildev 将非显而易见的设计选择记录为 ADR，以便未来的贡献者可以追踪*为什么*这样做，而不仅仅是做了*什么*： | # | 标题 | 状态 | | --- | --- | --- | | [0001](docs/adr/0001-adopt-monorepo-and-domain-packages.md) | 采用 monorepo 和领域包 | 已接受 | | [0002](docs/adr/0002-scene-graph-as-canonical-model.md) | 场景图作为规范模型 | 已接受 | | [0003](docs/adr/0003-hybrid-reverse-ui-pipeline.md) | 混合启发式 + AI 逆向 UI 流水线 | 已接受 | 其他设计说明位于 [docs/architecture/system-overview.md](docs/architecture/system-overview.md) 和 [docs/architecture/roadmap.md](docs/architecture/roadmap.md) 中。 ## 贡献指南 Buildev 欢迎那些习惯于开发**具有强烈架构愿景的未完成软件**的贡献者。贡献流程： 1. Fork 本仓库。 2. 创建功能分支：`git checkout -b feat/your-feature`。 3. 进行有针对性的更改。**在推送之前运行 `pnpm typecheck`、`pnpm test`、`pnpm lint`。** 4. 使用 [Conventional Commits](https://www.conventionalcommits.org/)：`feat:`、`fix:`、`refactor:`、`chore:`、`docs:`。 5. 提交一个清晰描述*为什么*这样改的 PR。 如有疑问，请优先选择： - 编辑**规范模型**（场景图），而不是创建一个并行的模型。 - 添加一个**编辑器动作**，而不是直接修改 store。 - 在修复之前编写一个**失败的测试**。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。

Buildev — 与代码同步的活 UI 画布。
早期预览。对此我们非常坦诚。

标签：AI Pipeline, AI前端开发, AI辅助编程, AST抽象语法树, MIT开源, pnpm, React代码生成, SVG处理, Tailwind CSS, TypeScript, UI反编译器, UI编译器, UI自动化, 代码生成, 低代码, 前端工程化, 前端逆向工程, 可编辑图层, 响应式设计, 图像识别, 场景图, 大语言模型应用, 威胁情报, 安全插件, 对话式UI设计, 开发者工具, 截图转代码, 智能UI设计, 渗透测试工具, 现代Web技术, 组件化开发, 组件库, 自动化攻击, 自动化流程, 设计工具, 设计系统, 设计转代码