内容
<!-- data-lang-nav --><p align="right"><b>English</b> · <a href="README.zh.md">中文</a></p>
# QORM
**与 AI 助手一起构建 UI 应用 — 实时协作，共同开发。** QORM 是一个面向智能代理的声明式 UI 运行时：用小型、语言中立的 JSON 描述 UI，你的 AI（Claude、Cursor 等）可以**搭建、编辑、运行和验证**它，而你可以在同一个正在运行的应用中实时协作 — 你点击，它看到；它编辑，你实时看到。
<p align="center"><img src="assets/qorm-demo.gif" alt="人类和 AI 同时编辑 QORM 应用，带有 'AI 编辑' 提示框" width="380"></p>
<sub>GIF 由 QORM 自身记录 — AI 通过 MCP 驱动编辑，`qorm shot` 通过 WebKit 捕获每个帧。无需浏览器自动化；参见 [`scripts/record-demo.sh`](scripts/record-demo.sh)。</sub>
### 适用于 iOS 的相同应用
<p align="center">
<img src="assets/screenshots/dashboard.png" width="200" alt="iOS 仪表盘">
<img src="assets/screenshots/uikit.png" width="200" alt="iOS 自定义组件">
<img src="assets/screenshots/login.png" width="200" alt="iOS 登录表单">
<img src="assets/screenshots/counter.png" width="200" alt="iOS 计数器">
</p>
<sub>真正的 iOS 构建（`qorm package -p ios`），在 iOS 模拟器中捕获。相同的 JSON 应用也可在网页 / Android / 桌面 / 小程序上运行。</sub>
在底层，默认构建是纯 Go — 它在浏览器中实时运行应用，渲染静态 HTML 快照，用 ed25519 签名成可分发包，通过空中更新服务，暴露给智能代理，并打包成网页 / iOS / Android / 桌面 / 小程序 — 从任何机器跨编译。
与 Claude（Anthropic）合作开发 — 很合适，因为人类-AI 协作是 QORM 的整个前提。
## 与 AI 助手一起构建
QORM 面向智能代理：指向你的 AI 编程助手（Claude Code、Claude Desktop、Cursor、Windsurf 等），让它**搭建、编辑、运行和验证** QORM 应用 — 然后与你实时协作。你点击，它看到；它编辑，你看到 **"AI 编辑"** 提示。只需设置一次：
```sh
go install github.com/qorm/qorm/cmd/qorm@latest
claude mcp add qorm -- qorm mcp . # 或将 integrations/mcp.json 添加到你的代理
```
然后直接询问 — *"搭建一个习惯跟踪器"*, *"修复这个溢出"*, *"打包成网页版"*. 完整指南：**[与 AI 构建](docs/build-with-ai.md)** · [人类-AI 协作](docs/collaboration.md)。
## 平台支持
<!-- support-summary:start -->
| 目标平台 | 软件包 | 渲染 | 实时应用 | 智能代理 / MCP |
|---|---|---|---|---|
| 网页 | 支持 | 支持 | 支持 | 支持 |
| iOS | 支持 | 支持 | 支持 | 支持 |
| Android | 支持 | 支持 | 支持 | 支持 |
| macOS | 支持 | 支持 | 支持 | 支持 |
| Linux | 测试版 | 支持 | 支持 | 支持 |
| Windows | 测试版 | 支持 | 支持 | 支持 |
| 小程序 | 支持 | 测试版 | 测试版 | 测试版 |
<!-- support-summary:end -->
`支持` 表示已支持并测试 · `测试版` 表示基础 / 部分功能 · `—` 表示不支持。该功能列表（分发、渲染、运行时、智能代理 — 每个目标平台）是 [平台支持矩阵](docs/platforms/support-matrix.md)；每个平台的硬件接口都在 [capabilities.md](docs/platforms/capabilities.md) 中。两者都由代码生成并通过测试保持同步。
## 运行
```bash
go run ./cmd/qorm run examples/counter # 在浏览器中打开应用
go run ./cmd/qorm render examples/todo -o todo.html # 静态快照
```
在计数器中按 `+` / `-`，或在待办事项应用中添加/切换任务 — 按钮点击 POST 到 `/event`，服务器更新状态，重新运行操作，并交换重新渲染的 UI。
## 签名包（验证包，不要信任服务器）
将应用编译成单个内容寻址工件，并用 ed25519 签名。运行时验证完整性（篡改检测）和可信公钥的真实性 — 在运行一行代码之前。这是对安全空中 UI 分发的信任原语。
```bash
qorm keygen # -> qorm_key, qorm_key.pub
qorm build examples/counter -o counter.qorm.bundle --key qorm_key
qorm verify counter.qorm.bundle --trust qorm_key.pub
qorm run counter.qorm.bundle --trust qorm_key.pub # 拒绝篡改/未签名的包
```
篡改的包会失败哈希检查；由不受信任的密钥签名的包会失败签名检查；两者在运行时都会被拒绝。所有纯 Go（`crypto/ed25519`），因此它像其他所有内容一样跨编译。
## 跨编译每个平台
```bash
./scripts/build-all.sh # -> dist/qorm-{darwin,linux,windows}-{amd64,arm64}
```
每个目标都是一个静态的 ~7 MB 二进制文件，没有运行时依赖。在此默认（纯 Go）构建中，`qorm run --app` 在无浏览器窗口中打开应用。
## 原生桌面窗口（可选）
对于真正的原生窗口，使用 `-tags desktop` 构建。这通过 cgo 驱动平台原生的 WebView（WKWebView / WebView2 / WebKitGTK）— 使用一个 vendored WebView 绑定（[`internal/webview`](internal/webview））— 因此它**每个平台**构建，而不是从一台机器跨编译：
```bash
./scripts/build-desktop.sh # 当前 OS 的原生二进制文件
qorm-desktop-... run examples/counter --app # 打开原生窗口
```
这两个路径共存：默认 = 跨编译所有平台（浏览器窗口）；`-tags desktop` = 原生窗口（每个平台构建）。两者都渲染 **HTML/CSS 在 Web 引擎**，因此两者都保留完整的智能代理协作栈（通过 SSE + MCP 共享实时会话）。QORM 架构（加载器 → 运行时 → 渲染 → 服务器）在两者中都是相同的。
| 构建 | 渲染 | 绘制小部件 |
|---|---|---|
| 默认 | HTML/CSS → 浏览器 | Web 引擎 |
| `-tags desktop` | HTML/CSS → 原生 WebView | Web 引擎 |
## 通过 MCP 访问智能代理
通过模型上下文协议（stdio JSON-RPC）将应用暴露给智能代理（Claude、Cursor 等）：
```bash
qorm mcp examples/counter
```
智能代理可以**设计、运行、测试和操作**应用 — 人类-AI 协作的循环：
| 能力 | 工具 |
|---|---|
| 理解 | `qorm_inspect`, `qorm_render_html`, `qorm_get_node`, `qorm_list_actions` |
| 操作 | `qorm_dispatch`（运行操作），`qorm_set_state` |
| 测试 | `qorm_assert`（stateEquals / htmlContains / nodeExists） |
| 设计 | `qorm_preview_patch` → `qorm_apply_patch` |
| 推理 | `qorm_simulate_action`（无副作用） |
安全模型：`simulate` 和 `preview_patch` 永远不会触及实时应用；`apply_patch` 必须携带 **相同** 操作的 `previewToken` — 因此已提交的设计更改始终与审阅绑定。
### 共享实时会话（人类 + AI，一个应用）
`qorm run` 还通过 HTTP 在 `/mcp` 暴露智能代理，共享浏览器渲染的**相同**运行时。智能代理的编辑立即出现在每个连接的浏览器中 — 页面订阅 `/events` 处的服务器发送事件（带有 `/poll` 回退）— 人类的点击对智能代理的下一次 `qorm_inspect` 可见。真正的人类-AI 在一个运行的应用上实时协作。
<p align="center"><img src="assets/screenshots/logwindow.png" width="440" alt="活动面板：人类（你）和 AI 代理在一个共享会话中的操作，以颜色编码和实时显示"></p>
<sub>**活动面板** — 桌面应用打开的独立窗口，位于你的应用旁边 — 显示每个人类点击（绿色）和智能代理 MCP 调用（蓝色），在**相同**运行的应用上，以颜色编码和实时显示。这是人类看到的协作窗口。</sub>
```bash
qorm run examples/counter # 浏览器 UI + 智能代理端点在 /mcp
# 智能代理：POST http://127.0.0.1:PORT/mcp (JSON-RPC 2.0)
```
## 架构
```
应用 JSON（清单 + 场景 + 操作）
→ 加载器 解析成 model.App（节点树 / 操作 / 全局状态）
→ 运行时 状态存储 + {{expr}} 评估 + 操作调度
→ 渲染 节点 → HTML + CSS flexbox（浏览器执行布局）
→ 服务器 HTTP + /event 实时更新循环
```
| 包 | 角色 |
|---|---|
| `internal/model` | 应用 / 节点 / 操作数据模型 |
| `internal/loader` | 加载目录（跳过 `type:test`），解析清单/场景/操作 |
| `internal/expr` | 表达式求值器（`count + 1`，`state.x`，三元组，...） |
| `internal/runtime` | 状态，绑定插值，操作步骤（`state.set/append/appendObject/toggle`） |
| `internal/render` | 完整小部件集 → HTML/CSS，包括 `list` 重复使用 `{{item.*}}` 范围 |
| `internal/server` | 实时 HTTP 服务器 + 事件调度 |
| `internal/bundle` | 编译 + sha256 内容哈希 + ed25519 签名/验证 |
| `internal/keys` | ed25519 密钥对生成和存储 |
| `internal/ota` | 获取（http/file）+ 验证前激活，失效回滚 |
| `internal/mcp` | MCP stdio JSON-RPC 服务器（智能代理工具） |
| `cmd/qorm` | `run` / `render` / `build` / `keygen` / `verify` / `mcp` CLI |
## 小部件覆盖
顶级小部件词汇表，全部映射到语义 HTML/CSS：
- **布局**：行，列，堆栈/绝对，`scroll`，`grid`（N 列），`card`，`spacer`，`divider`，包装。
- **文本**：文本，`link`，`icon`，`badge` — 具有 fontFamily，lineHeight，letterSpacing，textDecoration，`lineClamp`/`ellipsis`，转换。
- **输入**：输入（双向状态绑定），`textarea`，`select`，复选框，开关，`radio`，滑块 — 具有 `onChange` 事件。
- **媒体/反馈**：图像，`avatar`（图像或首字母），`progress`，`spinner`，`video`。
- **结构**：`tabs`（客户端切换），`list`（数据绑定重复使用 `{{item.*}}` 范围）。
- **动画**：任意节点（或组件）上的 `animation` 属性在安装时播放进入效果（`fadeup`，`pop`，`bounce`，...）；`animatedcontainer` / `animatedopacity` 执行值驱动的转换；按钮获得 iOS 按下反馈。
参见 [animation](docs/reference/animation.md) 和 `examples/animations` / `examples/payment`。
此外，每个节点都有跨切割功能：条件渲染（`"if": "{{state.x}}"`)，无障碍（`role`，`ariaLabel`，`title`），以及丰富的样式（阴影，渐变，位置 + top/left/right/bottom，宽高比，最小/最大宽度/高度，不透明度，过渡，`animation`）。参见 `examples/gallery`。
## 空中更新
运行的应用（从包启动）接受热更新：`POST /update {"source": "<url-or-path>"}` 获取，验证（哈希 + 签名与受信任的密钥），并热交换应用；`POST /rollback` 恢复。拒绝的更新会使实时应用保持不变 — 不良更新永远不会使其崩溃。
## 文档
QORM 是双消费者 — 相同的工件为人类开发者和 AI 代理服务。
- **人类** 从 [`docs/`](docs/) 开始：[入门教程](docs/tutorials/getting-started.md)，[小部件目录](docs/reference/widgets.md) 和 [功能](docs/platforms/capabilities.md)（两者都从代码自动生成），平台指南，以及 [用户中间层](docs/platforms/native-middlelayer.md) — 在一个 `native/desktop.go` 中添加你自己的原生操作，它编译成桌面二进制文件 **和** 移动/网页 WASM。
- **AI 代理** 从 [`llms.txt`](llms.txt)（或 [`AGENTS.md`](AGENTS.md)）开始：一个精选的、机器可读的地图，包含上述所有内容。将 QORM 添加到你的代理，使用 [`integrations/`](integrations) 中的工具，通过 [MCP](docs/agent/mcp-tools.md) 驱动实时应用，并使用 `qorm measure` / `qorm check`（参见 [验证](docs/verification.md)）自行验证你的编辑。
## 许可证
源码是 [MIT](LICENSE) — 免费使用、修改和分发。一个品牌术语适用（[ops/TERMS.md](ops/TERMS.md)）：应用默认附带 QORM 徽标；个人 / 教育 / 开源使用可以免费更换图标，而**商业白标**（自定义图标，或删除“Made with QORM”元数据注释）需要 Patreon 会员资格 — **Indie $1/mo**（个人）或 **Studio $7/mo**（公司）。 **Supporter** 层 ($3/mo) 支持项目，具有优先功能请求；个人/教育/开源使用是免费的 **Community** 层。`qorm` CLI 会要求你确认（荣誉系统），当你打包商业功能时。支持者在 QORM Patreon 页面上被认可。
## 路线图
HTTPS OTA（`qorm run --tls`），密钥撤销列表（`--revoked`），以及智能代理 `apply_patch` 工具都已上线。剩余方向 — 一个托管文档门户，一个沙盒 Playground，以及生态系统注册表 — 在 `docs/planning/` 中跟踪。
## 致谢
可选的原生桌面窗口提供 [webview](https://github.com/webview/webview) C/C++ 库及其 [Go 绑定](https://github.com/webview/webview_go)（MIT，（c）Serge Zaitsev）— 谢谢。选择原生窗口的方法灵感来自 [Wails](https://github.com/wailsapp/wails)。
