像搭积木一样写网页：左边拖中文积木，右边实时预览，做完一键打包成真实项目下载。
积木不是玩具 —— 它生成的是干净的 HTML / CSS / JavaScript / PHP / SQL / Python，可以直接部署。
一个装在自己电脑上的图形化 Web 编程平台，面向零基础用户，也面向想快速搭原型的人。
- 想学做网页的人：不用先背标签和语法，拖「标题 / 卡片 / 横向排列 / 鼠标悬停」，右边立刻看到效果；
- 会写代码的人：它是代码优先的 —— 每个文件都能切到代码视图手写，改完再「转成积木」接着拖，认不出的部分原样保留，代码一行不丢；
- 要交付的人：点「下载」拿到的是真实目录结构的 ZIP，
php -S就能跑，也能直接丢到虚拟主机或服务器上。
平台本身零依赖：只要有 PHP 8，双击脚本就能用，不需要 Node、不需要构建、不需要数据库（没装 MySQL 会自动用项目内的 SQLite 跑通后端示例）。
git clone https://github.com/<你的账号>/Gra.git
cd Gra/visual-editor
./start.sh浏览器打开 http://127.0.0.1:8080 即可。默认只监听本机，不进公网。
| 命令 | 作用 |
|---|---|
./start.sh |
启动，默认 127.0.0.1:8080 |
./start.sh --port 9000 |
换端口 |
./start.sh --open |
启动后自动打开浏览器 |
./start.sh --lan |
允许局域网访问（见下方「安全边界」，只在可信网络用） |
./start.sh --check |
只做环境体检，不启动 |
PHP_BIN=/path/to/php8 ./start.sh |
本机有多个 PHP 时指定解释器 |
注意仓库根目录不是项目目录，平台在
visual-editor/子目录里。
打开后顶栏的 模板 里有三个能直接跑的样板：品牌官网（纯前端）、留言板（前端 + PHP + MySQL，连不上 MySQL 会自动改用 SQLite）、Python 动态页面。
覆盖 HTML 语义标签、CSS 属性（329 块）、JS 语言与 DOM/BOM、PHP 后端、SQL，外加「常用库」一键引入 Bootstrap / jQuery / Chart.js。967 块积木的用途、1794 个参数怎么填，全部有中文解释和能照抄的例子 —— 鼠标停在参数上就有提示，空输入框里就是示例值。这不是维护出来的文档，而是从积木定义本身生成的，所以加一行积木就有配套说明。
编辑 .html 时，积木箱里 HTML + CSS + JS 一起列出来：样式积木自动收进 <style>、交互动积木自动收进 <script>，不必先建 css / js 文件。每块积木右侧有 HTML / CSS / JS 语言徽章，一眼看出它写的是什么。
想让某段文字变红，不用建样式文件、不用想选择器 —— 直接把「文字颜色」积木拖到那块积木身上（悬停时会出现虚线的「样式区」）：
- 声明类样式 → 合并进这个元素的
style=""，不影响别的积木； - 「鼠标悬停时」「手机屏幕上」这类不能内联的 → 自动生成只属于它的类名（如
.gra-style-0iy3a0dl）； - 反向也成立：代码 → 积木时样式会还原成样式积木并保持类名不变，所以「积木 → 代码 → 积木 → 代码」两遍结果一模一样（有测试盯着）。
每个项目第一次保存时自动建本地 git 仓库，之后每次保存自动提交一次。按「今天 / 昨天 / 日期」分组看改了什么、增删几行，点一条看完整差异，随时回到从前。仓库就在项目目录里（projects/<项目>/.git），可以用 VSCode 或任何 git 工具接手 —— 只在本机提交，不设远端、不推送。
预览工具条上有「启动文件」和「方式」：
- 单文件预览：静态网页实时刷新；
- 完整启动：在 6565 端口把整个项目后台跑起来 —— 有
package.json就执行它的 dev/start 脚本（Astro / Vite / Next 会自动补--port 6565），有 PHP 就用php -S服务整个目录，启动文件是.py就跑它。预览 iframe 直接连http://127.0.0.1:6565/，相对路径、接口调用、热更新全是真的。
启动文件自己选（任何文件都能当），缺依赖会提示并给「装依赖」按钮，端口被占用会告诉你谁占的。
文件 / 文件夹 / ZIP / 直接粘贴都能导入，自动还原成积木，认不出的部分保留为「原样片段」，注释也保留成注释积木。永远不会丢代码 —— 这一点有往返测试保证。
仓库自带 llms.txt + docs/agent-faq.json（67 条带步骤的结构化问答）+ docs/客户文档.md。把地址丢给客户的 AI，它就能自助答疑，不用你一遍遍复述。
拖几块积木，生成的就是一个能直接部署的普通项目，没有任何运行时或框架锁定。示意：
我的官网/
├── index.html ← HTML 积木生成的结构
├── css/style.css ← CSS 积木（或内联在 <style> 里）
├── js/script.js ← JS 积木（或内联在 <script> 里）
├── api/list.php ← PHP 积木生成的后端接口
├── config/db.php ← 「数据库设置」一键生成（默认自动选 MySQL / SQLite）
└── sql/schema.sql ← SQL 积木生成的建表语句
下载 ZIP 后在目录里 php -S 127.0.0.1:8000，浏览器打开 http://127.0.0.1:8000 就能跑。
Gra/
├── visual-editor/ 平台本体（PHP + 原生 JS，无构建）
│ ├── index.html 编辑器界面
│ ├── start.sh 启动脚本（环境体检 / 版本检查 / 端口检查）
│ ├── router.php 开发服务器路由（MIME、PHP 执行、安全拦截）
│ ├── api/ 后端接口（项目 / 数据库 / 版本历史 / 时间线 / 运行 / 完整启动 / 上传）
│ ├── assets/js/ 积木表、生成器、反解析器、编辑器各模块
│ ├── docs/ 面向客户的文档 + AI agent 资料
│ ├── projects/ 用户项目落盘处（不入版本库）
│ ├── tests/ 7 套测试
│ └── README.md 完整说明书（功能、积木体系、安全边界、FAQ）
├── .github/workflows/ci.yml CI：真起服务、真跑全套测试
└── CHANGELOG.md
完整文档请看 visual-editor/README.md —— 那里有积木体系、目录结构逐文件说明、安全边界和常见问题。
cd visual-editor
./start.sh # 另开一个终端让服务跑着，端到端测试才会执行
./tests/run.sh # 生成器 / 反解析 / 零基础说明书 / 时间线 / 界面冒烟（+ e2e / 完整启动）7 套测试、540 项断言，全部是「真跑一遍」而不是打桩：
| 测试 | 断言 | 测什么 |
|---|---|---|
test_generator.mjs |
60 | 多文件多语言生成、967 块积木逐个渲染、嵌套缩进、转义 |
test_parser.mjs |
60 | 代码 → 积木往返一致、注释保留、原样兜底 |
test_help.mjs |
17 | 每块积木都有说明、每个参数都有解释和例子 |
test_git.mjs |
33 | 时间线用真实 git 跑：提交 / 差异 / 回到从前 / 越权保护 |
test_ui.mjs |
209 | jsdom 里真跑前端：拖拽、样式插块、撤销重做、模板、自动保存 |
test_e2e.mjs |
108 | 静态资源、源码泄露检查、保存落盘、SQLite 建表、PHP / Python 真跑、ZIP 打包 |
test_serve.mjs |
53 | 真的在 6565 起进程、抓页面、验停止、验依赖缺失与端口占用 |
界面冒烟测试需要 jsdom（只在测试时需要，平台本身零依赖）：
mkdir -p /tmp/gra-domtest && cd /tmp/gra-domtest && npm i jsdomCI 会真起服务、真占端口跑完整套，并断言没有哪一项被静默跳过。
这是本机开发工具，不是可以放上公网的多用户服务 —— 请不要部署成在线 SaaS。设计上已经做到的：
- 默认只绑定
127.0.0.1； - 只有
api/与projects/下的.php会被执行，其余位置的 PHP 一律 403，绝不返回源码； - Python 只执行项目目录下的
.py，只允许本机请求、强制超时； - 运行 / 上传接口只接受本机请求，路径统一规范化并拒绝
..，ZIP 采用「读出来再写」天然免疫 zip-slip； - 数据库口令随请求传递、用完即弃、不落盘。
--lan 会把「项目里的 PHP / Python 会被执行」一起暴露给同网段，只在可信网络里用。完整清单见 visual-editor/README.md 的「安全边界」一节。
预览一片空白？ 静态项目编辑即刷新；带后端的项目要点「运行」。状态栏会写清楚当前是哪种模式以及失败原因。
起不来？ 先跑 ./start.sh --check：它会检查 PHP 版本（需要 8.0+）、扩展、端口占用。
需要装 Node 吗？ 不需要，平台零依赖。只有 Astro / Vite 这类 Node 项目用「完整启动」时才需要 Node。
能把项目推到 GitHub 吗？ 平台内置的时间线刻意不做远端推送（安全边界）。需要上传就用「下载」拿 ZIP，或自己在终端里给项目目录加远端再推。
更多问题（样式贴不上、Python 没反应、上传过大、数据库连不上、时间线与「版本」的区别……）见 visual-editor/README.md#十常见问题。
项目鸣谢：大肥鱼
MIT —— 可自由使用、修改、分发、商用，只需保留版权声明。
Gra is a local-first, zero-dependency visual web programming platform with a fully Chinese UI. Drag blocks on the left, see a live preview on the right, and export a real, deployable project — clean HTML / CSS / JavaScript / PHP / SQL / Python, no runtime and no lock-in. It requires nothing but PHP 8.0+, ships with 967 blocks (every block and every parameter documented in plain Chinese), a real-git timeline per project, and a one-click "run the whole project" mode. The documentation in this repository is in Chinese.