AffrescoUI
任何应用,用一种格式定义、以原生方式渲染。它的用户只需向 AI 提出请求,就能实时重塑它。
愿景 · 应用 · 架构 · Lisp (Clojure) · 工作原理 · 快速开始 · 文档
演示内容:一个图像编辑器,通过向它的助手提问,获得了 3D 建模器和演示应用的功能;一个由名称和描述创建的新应用;对一个 home 应用做的小改动;以及带有其应用的 Launcher。
v1.0.0 的下载尚未进行代码签名,因此 macOS 和 Windows 在首次打开时会警告无法验证开发者。签名版本将在后续版本中提供。
目前最佳方式:从源码构建。只需一条命令,会为你的机器生成优化构建,且永远不会显示该警告(需要 CMake 3.25+ 和 C++23 编译器):
cmake -S . -B build && cmake --build build && ./build/affrescoui_launcher
AffrescoUI 是一个原生 UI 引擎,其应用用 Lisp 定义。AffrescoUI Lisp 是 Clojure 的一种沙箱方言,是标准:应用的窗口、视图、状态、行为、命令、按键、设置和文本都是具名的 Lisp 定义,引擎将它们构建成一个文档,用 C++ 和 OpenGL 绘制,并持续运行。如果你会写 Clojure,你就已经能读写这些应用。也支持 JSON:同一个文档可以直接用 JSON 编写,每个示例都同时提供两种格式。人和 AI agent 在应用运行时修改它:每次修改都会根据应用的权限进行检查,需要审批的会先预览,然后在毫秒内就地应用,无需重建、无需重启、不会丢失任何内容。
愿景
软件在构建时就被冻结:它只做制作者交付的功能,每次修改都要等下一个版本。AffrescoUI 应用在使用过程中持续演进,由使用它们的人来塑造。
- 所有应用使用同一种格式。一个待办事项列表和一个专业设计工具以相同方式编写,并由同一个原生引擎渲染。为一个应用构建的功能可以迁移到另一个应用。
- 复杂的应用,任何人都能构建。无需编程:描述你想要什么,AI agent 就会与你一起逐步构建它,从简单的看板到完整的工作台。
- 使用应用的人可以修改它。用平实的语言向应用本身提问:“加一个 Blocked 列”,“日落时调暗灯光”,“连续记录中断时提醒我”,或者指向要修改的部分并提问。你会实时看到修改,然后保留或撤销它,即使在后续修改之后也可以。未经你的批准,什么都不会改变。
- 不间断的原型设计。每个想法都在运行中的应用里试验:无需重建、无需重启、无需重新加载,你的工作保持原样。当原型正确时,它就已经是应用了。
应用如何成长
一个应用从文档开始,然后通过对话成长:“给这个列表加一个过滤器”,“让侧边栏可折叠”,“当总数为负数时用红色显示”。每个请求都会变成一个经过审查的修订。一连串修订组成一个变更集——一个像插件一样工作的可移植文件,整个功能可以在应用之间迁移:下面的 planetarium 复用了演示编辑器的幻灯片排序器。某人对应用的个性化版本也作为一个文件分享,每次安装都是他们在落地前审查的提案。
flowchart LR
app["📦 一个应用<br/>一个实时文档"]
ask["💬 你提问<br/>'给这个列表加一个过滤器'"]
propose["🤖 一个 agent 提议<br/>一个修订"]
approve["✅ 你预览,<br/>接受或拒绝"]
plugin[("🧩 变更集<br/>或功能")]
catalogue[("🌍 共享<br/>他人可安装")]
app --> ask --> propose --> approve --> plugin --> catalogue
catalogue -. "安装" .-> app
classDef step fill:#EEF2FF,stroke:#6366F1,color:#312E81
classDef win fill:#10B981,stroke:#047857,color:#fff
class app,ask,propose,approve step
class plugin,catalogue win
方向:把应用做到像人们日常使用的专业工具那样复杂,采用同一种格式,原生渲染,并由使用者在其运行过程中塑造。
应用
十三个应用,从日常应用到专业工具,全部采用同一种格式。它们是示例(examples/),不属于库的一部分,每个应用右下角都带有 AI 助手:用平实的话提出修改,或先 Point 出要修改的部分,然后审阅它生成的提案。每个都是一个 Lisp 程序(examples/<app>/lisp/),采用该方言的惯用风格,小型的具名视图和函数,文本提供英语、西班牙语和法语三种,并在旁边保留同一应用的 JSON 文档(examples/<app>/json/):在 Launcher 的 Settings 中选择用哪个打开。Calamaio,这个从内部重新编程的文本编辑器,只有 Lisp 版本。

AffrescoUI Launcher 本身就是一个实时文档:每个应用一键可达,你自己的应用,新建空白应用,从示例创建或从描述创建,一份可在审阅后安装的应用与功能目录,以及每个应用的助手所使用的 AI 提供商。
专业工具
| Forge · 一个 IDE 资源管理器、编辑器标签页与分屏编辑器、查找与替换、快速打开与命令面板、问题、输出与终端、源代码管理、调试器与语言服务器,提供深色、浅色和高对比度主题。examples/forge/lisp/index.screen.lisp ,使用 --folder DIR 打开文件夹 | Tempera · 一个图像编辑器 带弹出菜单的工具与上下文选项栏、带蒙版、组和调整图层的图层、画笔、选区、历史记录和导航器,基于分块图像引擎。代理只能提出建议:每处修改都需审阅。examples/tempera/lisp/index.screen.lisp |
|---|---|
| Sinopia · 一个演示文稿编辑器 带标签页和画廊的功能区、按节分组的幻灯片缩略图、带形状的画布、缩放与适应、演讲者备注和撤销。它的幻灯片排序器是一个可供其他应用安装的部件。examples/sinopia/lisp/index.screen.lisp | Modello · 一个 3D 建模器 带控制柄的受光照 3D 视口、大纲视图、属性编辑器、时间轴、对所有命令的搜索以及 glTF 导入。每次场景编辑都是一个修订版本,可审阅、可撤销。没有自己的 C++。examples/modello/lisp/index.screen.lisp |
| Quaderno · 一个代码编辑器 打开文件和文件夹、标签页、缩略图、在文件、符号和行之间快速切换、在文件中查找、命令面板和 console。examples/code-editor/lisp/index.screen.lisp | Orrery · 一个天象仪 3D 太阳系、从地面看到的天空、轨道图和日食时间轴。它的天体条是 Sinopia 的幻灯片排序器,从该应用安装而来。由一位外部人士依据公开文档构建。examples/orrery/lisp/index.screen.lisp |






日常应用
| Haven · 智能家居仪表盘 按楼层划分的房间、平面图、场景、灯光、气候、百叶窗和媒体,自动化以节点图形式呈现,包含日程、能耗图表、安防和通知,在模拟设备上运行。examples/haven/lisp/index.screen.lisp | Tempo · 音乐播放器 播放列表、3,000 首歌曲的曲库、专辑和艺人、可重新排序的队列、带可视化器和歌词的正在播放、均衡器和迷你播放器。播放为模拟。examples/tempo/lisp/index.screen.lisp |
|---|---|
| Streak · 习惯追踪器 带目标和日程的每日习惯、评分、图表、日历、笔记和提醒,全部保存在磁盘上,以 Lisp 程序编写。examples/streak/lisp/index.screen.lisp | Arcadia · 游戏启动器 带轮播的库和商店、游戏页面、下载、愿望单和购物车。由外部开发者依据公开文档构建。examples/arcadia/lisp/index.screen.lisp |
| Flow · 看板 带泳道的看板、每张卡片的表格和时间线、卡片抽屉、燃尽图、拖放及键盘替代操作、撤销和命令面板。examples/flow/lisp/index.screen.lisp | Sign in · 账户 登录和注册、两步验证码、密码重置、示例外部提供商、账户页面和会话过期,全部在文档中验证。examples/sign-in/lisp/index.screen.lisp |






从 Launcher(./build/affrescoui_launcher)打开它们,或用 ./build/affrescoui_launcher <file> 运行其中一个。它们都没有自己的原生代码:文件、终端和像素都归库所有。在 Lisp 中,每个应用都支持英语、西班牙语和法语(Sign in:英语、意大利语和阿拉伯语,从右到左)。
架构
AffrescoUI 只渲染被告知的内容:一个应用就是一个文档文件夹(而在嵌入该库的程序中,还包括它注册的任何原生代码),引擎对它一无所知。它分三层构建,每一层只由下一层构成:
- 应用:由 Launcher 打开的文件文件夹(屏幕文档、数据、资源),没有为它们编译任何东西。
- 主题(modules/themes):套件的组件(工具栏、菜单、停靠栏、对话框)和主题的设计令牌,作为 JSON 文件内置于库中。
- 引擎(其他所有模块):仅提供机制。它会去已安装的套件和主题中查找文档未定义的组件或令牌,且不按名称认识其中任何一个;文档自身的组件优先于套件的。
一项更改会沿着一叠层向下传递,每一层只负责一件事。
文章标题:为什么止步于 Emacs?用 Clojure 在运行中重新编程的原生应用
正文:
%%{init: {"theme": "base", "flowchart": {"nodeSpacing": 30, "rankSpacing": 34, "padding": 14, "wrappingWidth": 400}, "themeVariables": {"fontFamily": "Helvetica, Arial, sans-serif", "fontSize": "14px", "lineColor": "#94A3B8", "primaryTextColor": "#0F172A", "edgeLabelBackground": "#FFFFFF"}}}%%
flowchart TB
studio(["<b>你</b> · 应用的助手或脚本"])
agent(["<b>AI agent</b> · Claude Code"])
mcp["🤖 <b>MCP server</b> · mcp/<br/>双向连接 AI agent"]
channel["🔌 <b>Channel</b> · modules/channel, modules/net<br/>本地套接字 · 进程 · WebSocket · 每个对端一个会话"]
vcs["🛡️ <b>版本控制</b> · modules/vcs<br/>允许 / 询问 / 拒绝 · 提案 · 提交 · 历史"]
format["📄 <b>屏幕格式</b> · modules/format<br/>检查文档 · 求值 · 原地协调"]
lisp["λ <b>Lisp 语言</b> · modules/lisp<br/>构建程序的树 · 运行其函数"]
render["🎨 <b>渲染器</b> · modules/render<br/>布局 · 字形文本 · 输入 · 无障碍 · OpenGL"]
themes["🧩 <b>套件与主题</b> · modules/themes<br/>组件 · 设计令牌 · JSON"]
agent --> mcp
mcp --> channel
studio --> channel
channel -- "revision" --> vcs
vcs -- "accepted commit" --> format
format -- "panels" --> render
themes -. "components, tokens" .-> format
lisp -. "programs" .-> format
classDef peer fill:#FFFFFF,stroke:#CBD5E1,color:#0F172A
classDef c_mcp fill:#F3E8FF,stroke:#9333EA,stroke-width:1.5px,color:#3B0764
classDef c_channel fill:#E0F2FE,stroke:#0284C7,stroke-width:1.5px,color:#0C4A6E
classDef c_vcs fill:#FEF3C7,stroke:#D97706,stroke-width:1.5px,color:#78350F
classDef c_format fill:#D1FAE5,stroke:#059669,stroke-width:1.5px,color:#064E3B
classDef c_render fill:#EDE9FE,stroke:#7C3AED,stroke-width:1.5px,color:#4C1D95
class studio,agent peer
class mcp c_mcp
class channel c_channel
class vcs c_vcs
class format c_format
class themes c_format
class lisp c_format
class render c_render
- 用 Lisp 编写。一个应用就是一个用 AffrescoUI Lisp(LISP.md, modules/lisp)编写的程序:具名定义(defscreen、defview、defstate、defn、defcommand、defkey、defcustom、add-hook、advice),由该库自有的解释器运行。每个定义独立进行版本管理,因此一个 diff 会指明发生变化的视图或函数,提案会按它所构建的树重新构建并评判。该语言无法访问文件、进程或网络。它唯一的出口是宿主授予的步骤,每一步都会对照正在运行的代码的作者进行校验。
- 单一文档,原生绘制。程序所构建的是一个屏幕文档(SCREEN_FORMAT.md,带 JSON Schema):布局、组件、主题、状态、绑定、事件、定时器、服务和权限。它也可以直接用 JSON 编写,适用于数据和工具。通常需要代码的行为(把按钮连接到列表、校验表单、过滤、拖放、快捷键、导航、调用服务)被声明化,因此 agent 修改它的安全性等同于修改一个颜色。
- 对 agent 而言紧凑。编辑通过 id 定位节点({"set": {"#title/text": "Q4"}},以 JSON Patch 存储),重读只返回变化的部分:一次典型编辑为 28 tokens,一次提交后重读为 27(BENCHMARKS.md)。当人指向某个部分时,agent 只读取构建它的那个定义。
- agent 可用的应用。应用的命令就是工具:agent 列出它们,以自己的名义在应用的运行规则下运行其中一个(绝不使用人的名义),并可以撤销自己的运行(VERSION_CONTROL.md)。
- 可替换的层。模块之间只通过 modules/core 中的接口通信,由 affresco::Screen 将它们组合在一起。没有任何公共头文件暴露 OpenGL 或 GLFW,每个模块可单独链接(affrescoui::render、affrescoui::vcs……)或全部一起链接(affrescoui::affrescoui)。
文章标题:何必止步于 Emacs?你或 AI 在应用运行时用 Clojure 重新编程的原生应用
- 功能可流动。一个部件声明它所需的贡献点和契约,因此一个应用可以安装另一个应用的功能,并在落地前进行检查。一个功能可以包含 Lisp 代码,该代码以其作者的权限运行,而一个人对某个应用的版本被共享为单个文件(VERSION_CONTROL.md)。
modules/core/ 模块之间的接口:Executor, Channel, VersionControl, Services, Network
modules/render/ 窗口、面板、布局、整形文本、输入、无障碍;OpenGL 4.1 core 或 ES 3.0
modules/format/ 屏幕格式:规则、检查器、{{expressions}}、就地协调的运行时
modules/themes/ 工具包(kits)的组件和主题(themes)的设计令牌,以 JSON 构建进库中
modules/notation/ 以 JSON 或 Lisp 记法读写的文档
modules/lisp/ Lisp 语言,一个 Clojure 方言:读取器、解释器、纯构建成文档的程序
modules/data/ 应用的记录存于 SQLite,与其文档分开保存:模型与迁移
modules/audio/ 声音:文件、流和生成器的声部,混合到系统输出
modules/vcs/ 版本控制:提交、提案、权限、历史
modules/channel/ 对等节点以及基于本地套接字和进程的实时协议
modules/net/ HTTP(S)、服务器发送事件、WebSocket、远程对等节点
modules/services/ 语言服务器、主机授予的本地程序和文件夹
modules/intelligence/ 应用助手所请求的提供方(API 或命令行),位于助手能力之后
modules/screen/ affresco::Screen,组合根,以及总头文件 affresco/affresco.hpp
modules/automation/ 场景:脚本化输入、期望、黄金图像
modules/imaging/ 基于写时复制瓦片的分层图像
modules/scene3d/ 3D 场景,glTF 2.0 进出
modules/export/ 面板树导出为矢量 PDF
modules/capi/ C API,affresco/affresco.h
mcp/ 面向 AI 代理的 MCP 服务器
apps/server/ 文档服务器:基于 WebSocket 的共享、持久文档
apps/host/ 标准主机 affrescoui_launcher:它打开一个应用的文件夹并询问应用所用的东西
examples/ 各应用(每个都带一个 lisp/ 和一个 json/ 文件夹),其中包括 Launcher,以及助手插件
catalogue/ Launcher 的 Catalogue 列出并安装的应用版本和功能
editors/ 一个 VS Code 扩展,以及面向 Lisp 程序的 clj-kondo 配置
web/ WebAssembly 构建
各层、一次修订和一次事件的路径,以及安全边界:ARCHITECTURE.md。
用 Lisp 编写,一种 Clojure 方言
一个 AffrescoUI 应用是以 AffrescoUI Lisp 编写的程序,它是 Clojure 的一个沙箱方言,拥有自己的运行时,并构建进库中(LISP.md 以表格形式列出每个定义和规则;modules/lisp,RFC 0005,RFC 0006)。它的形式、函数和读取器形式都是 Clojure 的:在 186 个日常 Clojure 形式中,163 个给出 Clojure 自身的值,另外 23 个被略去或有意不同(everyday.lisp,每次测试运行都会检查)。它还会对照 Clojure 的跨方言测试套件进行衡量(CONFORMANCE.md),每一处差异都以该写什么来代替的方式记录下来(differences.md),并且 clj-kondo 用其配置对程序进行 lint。每个示例都以其惯用风格编写(style.md)。程序是一个由小的、具名定义组成的文件夹。构建它便给出引擎所绘制的文档,其函数会在按钮被按下、键入按键或绑定值变化时运行。以下来自 Flow 自己的代码(examples/flow/lisp/flow.lisp):
(ns flow.flow)
(defn cards-of "A column's cards, in their order." [c]
(:cards (column c)))
(defn next-order "The order that puts a card at the end of a column." [c]
(->> (cards-of c) (map :order) (reduce max -1) inc))
(defn column-of "持有卡片的列,或 -1。" [ref]
(or (first (keep-indexed (fn [c col]
(when (some #(= (:ref %) ref) (:cards col)) c))
computed.columns))
-1))
| 你定义 | 在 AffrescoUI Lisp 中 |
|---|---|
| 窗口,作为其各部分的大纲 | defscreen main |
| 它的各个部分,小而具名 | defview、defcomponent |
| 它的数据 | defstate、defcomputed |
| 它的外观 | deftokens、defstyle、defmenu |
| 它的行为 | defn、defcommand |
| 快捷键与设置 | defkey、defcustom |
| 扩展点 | defhook、add-hook、advice |
| 它的文本,支持每种语言 | (t "key") 和 locales/<language>.lisp |
| 它的文件 | (ns board.index (:require "toolbar.lisp" ...)) |
Lisp 还是 JSON:同一个应用
程序构建出的文档也可以直接用 JSON 编写。引擎两种都能读取:每个示例都附带一个 lisp/ 文件夹和一个 json/ 文件夹,Launcher 的设置决定打开哪一个。两者是同一个应用。它们的第一帧逐像素一致,通过相同的场景测试,并且共享同一份历史、相同的 diff 和相同的权限。在分别用两种方式做相同改动的测试中,AI 代理编辑 Lisp 的准确度与编辑 JSON 相当,成本也大致相同(BENCHMARKS.md)。
| Lisp:你编写的程序 | JSON:它构建出的文档 |
|---|---|
| (defview card-view " One card, in bold when it is a bug. " [card] ` (label#card :text ~card.title :bold ~( = card.tag " bug " ))) (defscreen main :window { :title " Board " } (column#cards ~(repeat [card state.cards] (card-view card)))) | { "type" : " column " , "id" : " cards " , "children" : [ { "type" : " label " , "id" : " card " , "repeat" : { "for" : " card " , "in" : " state.cards " }, "text" : " {{card.title}} " , "bold" : " {{(card.tag == 'bug')}} " } ] } |
(defview card-view "One card, in bold when it is a bug." [card]
`(label#card :text ~card.title :bold ~(= card.tag "bug")))
(defscreen main :window {:title "Board"}
(column#cards
~(repeat [card state.cards] (card-view card))))
{ "type": "column", "id": "cards", "children": [
{ "type": "label", "id": "card",
"repeat": { "for": "card", "in": "state.cards" },
"text": "{{card.title}}",
"bold": "{{(card.tag == 'bug')}}" } ] }
从内部改动,在它运行时
运行中的应用可以从内部重新编程。在 Calamaio——示例中的文本编辑器——中,打开 scratch 缓冲区(C-x b scratch RET),输入一条命令的新定义,并用 C-M-x 求值:
(defcommand kill-line "Says so." :title "Kill Line" :category "Killing" [] (message "redefined"))
下一次 C-k 就会运行新的定义,C-x C-z 则将其撤销。describe-key、apropos 以及 describe-* 函数可以检查正在运行的程序。
你自己的编辑器可以在任何 Lisp 应用中做同样的事:用 --nrepl 启动它,并连接任意 nREPL 客户端。窗口会询问一次是否允许该编辑器以你的身份求值;此后你求值的每个定义都会成为你自己的修订,落在你缓冲区所在的文件中(LISP.md)。
./build/affrescoui_launcher examples/flow/lisp/index.screen.lisp --nrepl
只有发生改动的那个定义会被重建,运行中的应用会在读取该定义的地方得到更新。
自由,且仍在版本控制之下
- 每次改动都是一个修订。每次求值都会修订一个定义:它被保留在历史中、显示在 diff 中,并像其他任何改动一样可以撤销。
- 代理的代码要经过审查。它以提案的形式到来,从其源码重建,并以它构建出的结果来评判。一旦被接受,它仍然以代理的权限运行,而非人的权限。
- 你的权限只覆盖你自己输入的内容。粘贴进来或由他人编写的文本以更低的权限运行,除非你在应用本身绘制的提问中读取了它(任何文档或代理都无法绘制或回答该提问)并回答是。
- Hook 和 advice 无法让你的命令失效。代理的 hook 和 advice 密封运行:它们无法阻止人的命令生效。
为什么它与众不同
| 🎨 真正的原生 从零构建的 C++23 引擎,运行在 OpenGL 4.1 core 或 ES 3.0(浏览器中为 WebGL2)上。没有浏览器引擎,没有 web view。一次变更只更新读取它的部分,只重绘发生变化的部分,文本在任何显示缩放下都清晰锐利,空闲窗口会休眠。 | 📄 活文档 整个应用就是一份可读的文档:布局、组件、状态、{{expressions}}、事件、服务。变更按节点 id 做紧凑编辑,原子化,并原地协调。 | 🛡️ 内置版本控制 内容寻址的提交,提案作为带实时预览的分支,diff,以及对任意早期变更的撤销(同时保留后续变更);allow / ask / deny 规则和变更预算。AI 可以改动你的应用,但永远无法批准自己的变更。 |
|---|---|---|
| 🤖 为 Agent 而生 双向 MCP 服务器:来自应用的请求连同你所指向的内容一起到达 agent,其修订和回复再返回。Agent 还能以工具的形式运行应用的命令,且遵循各自的规则。开箱即可与 Claude Code 配合使用。 | 🔌 任意数量的对等端 客户端、agent 和脚本通过本地 socket 连接,或经由文档服务器通过网络连接。身份来自连接本身,而非对等端的自称。 | 🧩 变更化为插件 任意一串修订都可导出为变更集,一个小的可移植文件,任何拥有同一应用的人都能审查并安装。应用的整个版本可作为一个文件分享,仅在审查之后才安装。 |
🎨 真正的原生
从零构建的 C++23 引擎,运行在 OpenGL 4.1 core 或 ES 3.0(浏览器中为 WebGL2)上。没有浏览器引擎,没有 web view。一次变更只更新读取它的部分,只重绘发生变化的部分,文本在任何显示缩放下都清晰锐利,空闲窗口会休眠。
📄 活文档
整个应用就是一份可读的文档:布局、组件、状态、{{expressions}}、事件、服务。变更按节点 id 做紧凑编辑,原子化,并原地协调。
🛡️ 内置版本控制
内容寻址的提交,提案作为带实时预览的分支,diff,以及对任意早期变更的撤销(同时保留后续变更);allow / ask / deny 规则和变更预算。AI 可以改动你的应用,但永远无法批准自己的变更。
🤖 为 Agent 而生
双向 MCP 服务器:来自应用的请求连同你所指向的内容一起到达 agent,其修订和回复再返回。Agent 还能以工具的形式运行应用的命令,且遵循各自的规则。开箱即可与 Claude Code 配合使用。
🔌 任意数量的对等端
客户端、agent 和脚本通过本地 socket 连接,或经由文档服务器通过网络连接。身份来自连接本身,而非对等端的自称。
🧩 变更化为插件
任意一串修订都可导出为变更集,一个小的可移植文件,任何拥有同一应用的人都能审查并安装。应用的整个版本可作为一个文件分享,仅在审查之后才安装。
工作原理
%%{init: {"theme": "base", "flowchart": {"curve": "basis", "nodeSpacing": 28, "rankSpacing": 46, "padding": 14}, "themeVariables": {"fontFamily": "Helvetica, Arial, sans-serif", "fontSize": "14px", "lineColor": "#94A3B8", "primaryTextColor": "#0F172A", "edgeLabelBackground": "#FFFFFF"}}}%%
flowchart LR
subgraph P["Who changes it"]
direction TB
you["<b>You</b><br/>the app's assistant"]
ai["<b>AI agent</b><br/>Claude Code · MCP"]
any["<b>Scripts & apps</b><br/>any socket client"]
end
subgraph V["Version control"]
direction TB
rules{"<b>Permission rules</b><br/>deny · ask · allow"}
pr["<b>Proposal</b><br/>branch · live preview"]
no["<b>Rejected</b><br/>nothing changes"]
end
subgraph E["Engine"]
direction TB
main[("<b>main</b><br/>SHA-256 commits")]
rt["<b>Runtime</b><br/>reconcile in place"]
gl["<b>Renderer</b><br/>C++23 · OpenGL"]
end
app(["<b>Your running app</b><br/>never restarts"])
you & ai & any -- "revision" --> rules
rules -- "allow" --> main
rules -- "ask" --> pr
rules -- "deny" --> no
pr -- "you accept" --> main
main --> rt --> gl --> app
classDef peer fill:#FFFFFF,stroke:#CBD5E1,stroke-width:1px,color:#0F172A
classDef gate fill:#FFFBEB,stroke:#D97706,stroke-width:1.5px,color:#78350F
classDef wait fill:#FFFFFF,stroke:#D97706,stroke-width:1px,stroke-dasharray:4 3,color:#78350F
classDef stop fill:#FFFFFF,stroke:#E11D48,stroke-width:1px,color:#9F1239
classDef core fill:#EEF2FF,stroke:#6366F1,stroke-width:1.5px,color:#1E1B4B
classDef out fill:#0F172A,stroke:#0F172A,color:#FFFFFF
class you,ai,any peer
class rules gate
class pr wait
class no stop
class main,rt,gl core
class app out
style P fill:#F8FAFC,stroke:#E2E8F0,color:#64748B
style V fill:#F8FAFC,stroke:#E2E8F0,color:#64748B
style E fill:#F8FAFC,stroke:#E2E8F0,color:#64748B
linkStyle 0,1,2 stroke:#94A3B8
linkStyle 3 stroke:#16A34A,stroke-width:2px
linkStyle 4 stroke:#D97706,stroke-width:1.5px
linkStyle 5 stroke:#E11D48,stroke-width:1.5px
linkStyle 6 stroke:#16A34A,stroke-width:2px
linkStyle 7,8,9 stroke:#6366F1,stroke-width:2px
- 任何人都可以提出更改。宿主(affrescoui_launcher)渲染屏幕,并在本地套接字上监听对等方。你通过应用的助手提出请求,如果愿意可以指明要更改什么;AI 通过 Launcher 中选择的 provider 作答,或者 agent 通过 MCP server 连接,双向都可;任何脚本也可以连接。每一次更改都是紧凑编辑的 revision。
- 权限规则负责裁决:deny 拒绝,ask 将更改送去评审,allow 则直接应用。规则判断的是更改做了什么,而非它是如何写的。例如 Flow 的规则允许用户自己的客户端更改任何内容,在 agent 更改行为前会询问,并保护状态栏不被任何人改动。
- 你来评审提案。提案是一个分支,就像 pull request:agent 可以在你实时预览时继续完善它。然后接受、始终允许(对于屏幕的那一部分不再询问)或带理由拒绝。模式 accept edits 和 plan 会改变被询问的程度。
- 被接受的更改成为 main 上的 commit,带有 SHA-256 id、作者和批准者。运行时原地更新正在运行的应用,保持焦点和输入状态。任何 commit 都可以撤销,同时保留其后所做的更改(若某个更改建立在其上,由你选择),或恢复(VERSION_CONTROL.md)。
快速开始
cmake -S . -B build && cmake --build build
./build/affrescoui_launcher # the Launcher: every app, your own apps, the AI settings
在 Launcher 的 Settings 中,选择助手使用的 AI:Anthropic、OpenAI、OpenAI 兼容服务器(例如 Ollama)或你的 Claude Code 登录,以及一个模型。密钥保存在系统钥匙串中。此后你打开的每个应用都有一个可用的助手,无需 MCP。若要通过 MCP 连接 AI agent(mcp/README.md):
claude mcp add affrescoui -- python3 /path/to/AffrescoUI/mcp/affrescoui_mcp.py
claude --dangerously-load-development-channels server:affrescoui # requests are pushed into the session
打开 Flow,在面板的助手中说"在 In progress 和 In review 之间添加一个 Blocked 列"。Claude 会更改正在运行的面板,更改以提案的形式返回:接受它,应用就原地更新;或者选择始终允许,不再被询问屏幕的那一部分。
./build/affrescoui_launcher examples/haven/lisp/index.screen.lisp # any application, no C++
./build/affrescoui_launcher examples/flow/lisp/index.screen.lisp --mode acceptEdits # agent changes apply unless a rule asks
./build/affrescoui_launcher examples/flow/lisp/index.screen.lisp --plugin my.json # start with a change set applied
需要 CMake 3.25 或更高版本,以及一个 C++23 编译器;CMake 会拉取锁定版本的依赖(cmake/dependencies.json)。CI 在 Linux、Windows 和 macOS 上构建并测试它,它也是在 macOS 上开发的;web/ 目录则把它构建到浏览器中。ctest --test-dir build 会运行单元测试、每个应用的场景,以及渲染检查——渲染检查会把每一帧与一张黄金图像逐像素比较(tests/render/README.md)。
在你的应用中使用
#include <affresco/affresco.hpp>
int main() {
affresco::Application app;
affresco::Screen screen = affresco::Screen::fromFile("app.screen.json");
screen.createWindow(app);
screen.onAction("save", [&](affresco::Panel&) { /* native code, if needed */ });
screen.listen(app, "/tmp/my-app/agent.sock", "agent"); // optional: let other programs change it live
return app.run();
}
find_package(AffrescoUI REQUIRED) # or add_subdirectory(AffrescoUI) / FetchContent
target_link_libraries(my_app PRIVATE affrescoui::affrescoui)
从 C 或其他语言使用时,C API(affresco/affresco.h)可以加载、驱动并嵌入一个界面;bindings/python 对它做了封装。
- 界面格式:布局(锚点、行、列、网格、分割、标签页、滚动、覆盖层)、样式、带参数和插槽的组件、主题与 token、字体、界面与导航、state、computed、watch、JS 风格的 {{expressions}}、repeat / when / let / check、双向绑定、带冒泡的事件、命令、菜单、键位绑定与设置、拖放、计时器、动画、channel、persist、include、带 ICU 复数与区域设置的字符串。
- 节点:标签、文本区域、带声明式语言和语法树的代码编辑器、diff、列表、树与虚拟化表格、节点图、时间线、日历、矢量路径、可编辑画布、图像与图像操作、栅格图层、3D 场景、原生 OpenGL 表面、取色器、渐变与曲线,外加一套桌面与聊天组件。
- 活动文档:原地协调;修订以紧凑编辑或 JSON Patch 表示,原子生效,按 #id 定位;任意数量的对等方可通过本地套接字、进程或网络连接;请求与回复的中继;从应用内部询问 agent,并指出要改动什么;更新只运行读取了该变更的部分(依赖追踪)。
- 版本控制:SHA-256 提交、只追加的 main、以分支形式提出的提案与合并提交、log、diff、blame、revert、restore、保留后续改动的 undo、三方合并、HEAD~1 这类名称;allow / ask / deny 规则按效果判定、模式、授权、预算、审阅者、受保护的控件、绑定到所审阅版本的批准;变更集、整个应用的包以及一个目录,各自在审阅后安装;历史保存在磁盘上。
- 服务与网络:宿主允许的语言服务器和本地程序、它授予的文件夹、HTTP(S)、服务器发送事件、WebSocket、登录,以及一个可实时共享文档的文档服务器。
- Agent:一个双向 MCP 服务器,支持压缩读取、大纲、单节点读取和仅变更重读、当事人所指内容的来源、屏幕截图、场景、对部分的租约、把应用命令作为带运行规则与 undo 的工具,以及由连接设定而非自我声明的作者身份。
- Lisp:一个沙箱化的 Clojure 方言,以 Clojure 的测试套件为衡量标准;定义逐个版本化,改动过的定义单独重建;为编辑器提供 nREPL 服务器,由本人配对。
- 引擎:HarfBuzz 字形整形与带回退的 FreeType 字形、从右到左的文本、彩色 emoji、100% 到 400% 的显示缩放(2× 以下文本采用锐利 hinting)、损伤区域重绘、平台的无障碍 API(VoiceOver、Narrator、Orca)、用于测试的无头窗口、矢量 PDF 导出。
- 工具:affrescoui CLI(run、check、test、render、fmt、在 JSON 与 Lisp 之间转换、migrate、从 A2UI 和 Adaptive Cards 导入、export、打包与安装、一个 REPL)、带黄金图像的场景、VS Code 扩展、clj-kondo 配置、带 Python 绑定的 C API、WebAssembly 构建。
文档
| 文档 | 涵盖内容 |
|---|---|
| LISP.md | 以表格形式呈现的 AffrescoUI Lisp:每个定义、视图与绑定、运行、应用布局、限制、工具 |
| SCREEN_FORMAT.md | 屏幕格式,逐节点说明 |
| VERSION_CONTROL.md | 提交、提案、权限与审查 |
| modules/lisp/README.md | Lisp 语言:其值、特殊形式、函数与限制 |
| ARCHITECTURE.md | 各模块、一次修订与一个事件的路径、安全边界 |
| mcp/README.md | MCP 服务器及其工具 |
| BENCHMARKS.md | 速度、内存与 token 预算,含每一项测量 |
| ACCESSIBILITY.md | 屏幕阅读器在每个平台上能看到和驱动的内容 |
| SECURITY.md | 信任模型、受保护的内容,以及如何报告漏洞 |
| CHANGELOG.md | 每个版本中的变更 |
故事

AffrescoUI 始于 2017 年 12 月,当时名为 sGLGUI,那时我 16 岁,用它来自学 OpenGL 和 C++:嵌套面板、像素/百分比尺寸、锚点,以及一个信号/槽事件系统,全部从零实现。2018 年我加入了一个文本区域。它能收集击键,却始终无法把它们绘制出来,项目就此停滞。2020 年的一次重启重写了布局引擎(右图就是那次演示),随后又再次停滞。
2026 年,我用 Claude Code 让它重获新生。最初的目标是一个真正可用的库:我们把它移植到 OpenGL 4.1 core,用 C++23 重写,并最终实现了文本渲染。随后一个想法萌生:如果 AI agent 能在原生应用运行时修改它,而每一次修改都由你批准,会怎样?这让它远远超出了最初的计划:用 JSON 描述的 UI、实时修订、版本控制,以及面向 AI agent 的双向 MCP 桥接。
它是如何构建的。需要说明清楚:2026 年的全部代码都由 Claude Code 通过 agent 驱动的开发方式编写。我带来的是方向与架构。我在许多次迭代中塑造它,尝试一个想法,观察它的效果,然后调整方向,直到它按我想要的方式运作。git 历史记录了每一步。
timeline
2017 : Started at 16 : nested panels, anchors, signal → slot events
2018 : A text area that can't draw text : the project stalls
2020 : Restarted : new layout engine, stalled again
2026 : Revived with Claude Code : C++23 · OpenGL 4.1 core · real text : live JSON screens · version control · MCP
许可证
Apache License 2.0:可自由使用、修改和分发,无论商业与否。任何分发它的人都必须一并传递 NOTICE 文件,其中注明作者。参见 LICENSE 和 THIRD_PARTY_NOTICES.md。
由 Riccardo Sottini 创建 · 2017–2026
如果 AffrescoUI 让你想到“等等,AI 能在原生应用运行时修改它?”,那就留下一个 ⭐。