【开源】UI 和 AI 各写一套？它让两端共用一套

你给产品加了 AI 聊天框，本来想省事，结果呢？用户在页面上改的数据，AI 在聊天框里改不到；AI 干完的活，页面上根本看不见。到最后，你养出了两套系统、两套逻辑。

这事儿几乎所有做 AI 产品的团队都撞过，只是没人明说。

一个被默认接受、其实很贵的坑

一个正常的 Web 应用，界面本来就有完整的一套：表单校验、增删改查、权限判断、状态流转。你写得顺手，用户也用得顺。

然后你接了个大模型，加了个聊天入口。问题来了——AI 要干活，它得有自己的"手"，也就是一组 Tool。于是你又写了一套：同样的"创建订单""修改资料"，Tool 里再实现一遍，校验再写一遍，权限再配一遍。

两套逻辑从此各跑各的。需求一变，UI 改一遍，Tool 再改一遍；哪边漏了，数据就对不上。更糟的是同步：用户刚在页面改完，AI 不知道；AI 刚生成完，页面不刷新。

维护成本不是翻倍，是指数级往上走。

真正的麻烦不是"多写一份代码"，而是两份代码永远在彼此错位。

我见过一个真实的例子：团队先在 React 里写了"更新客户资料"，三个月后给 Agent 加了同款 Tool。半年过去，UI 那边加了"手机号脱敏"的校验，Tool 这边忘了加。结果 Agent 天天把脱敏后的号码原样写回数据库，对了一周才发现。两份实现的裂缝，就是这么来的。

更隐蔽的是，这种裂缝会随时间变大。项目早期还能靠人肉对齐，功能一多、人一换，两边就各自漂移。等到你想加个新能力，先得搞清楚"界面那份"和"Agent 那份"到底谁是对的——光梳理就够喝一壶。

Agent-Native：把能力定义一次，两端同时用

来自 Builder.io 的开源框架 Agent-Native（TypeScript 编写，官方定位是 "A framework for building agentic apps"），给出的思路很干脆：别再让 UI 和 Agent 各写一套了，把每个能力定义一次成 action，两端共用。

它有一句话我记下来了：The agent does not click through the UI. It works through the same action layer as the UI.（Agent 不去点界面，它走的是和 UI 同一个 action 层。）

这不是又包一层抽象，而是直接把"能力"做成唯一真相源。UI 和 Agent 不再各自为政，而是都挂在同一个 action 定义上。

你可能会问，这套思路为什么现在才成型？因为早几年大模型还做不到"可靠地调用一个带校验的函数"——那时候你给它的 Tool 经常乱填参数，根本不敢放权。如今模型足够稳，把一个 action 当成可被信任的能力交给它，才真正可行。Agent-Native 赌的就是这个时机。

核心能力一：一个 action，五端通用

这是整个框架的心脏。你用 defineAction 定义一个能力，它同时成为：

• UI 的能力
  ：React 直接调用
• Agent 的能力
  ：大模型把它当 Tool
• 还有 HTTP、MCP、A2A、CLI
   也自动暴露

一次定义，五处复用。校验、权限、实现只写一遍，从源头上消灭"两份实现分叉"。

import { defineAction } from"@agent-native/core/action"; import { z } from"zod";  exportdefaultdefineAction({   description:"Return a friendly greeting.",   schema:z.object({     name:z.string().default("world"),   }),   http: { method:"GET" },   run:async ({ name }) => {     return { message:`Hello, ${name}!` };   }, });

定义完，Agent 自动拿到 hello 这个 Tool；React 侧用一行 useActionQuery 就能调同一个函数，连参数类型都和 schema 对齐：

const { data } =useActionQuery("hello", {   name:"Alex", });

它 vs 同类方案：传统做法是 UI 写一遍业务逻辑、再给 Agent 写一套 Tool，两份实现迟早分叉，谁改了另一边都不知道；Agent-Native 让两端指向同一个 run，校验和权限也只有一份，分叉从架构上就不可能发生。

顺带一提，因为 action 自带 zod schema，UI 的表单校验和 Agent 的参数校验用的是同一份定义。UI 改了字段要求，Agent 那边立刻跟着变，不用你再手动同步一遍。这才是"一份实现"真正的意思——不止逻辑一份，连约束都只有一份。

核心能力二：数据互通，状态共享

光有 action 还不够。Agent-Native 还有两层共享，把"两套系统"彻底打通：

共享数据：Agent 做的工作直接出现在 UI 上，用户在 UI 上做的工作 Agent 也拿得到。两边看到的是同一份真相，不再需要你手动搬数据。

共享应用状态：Agent 能拿到当前 UI 的上下文——你在第几页、选中了哪条记录、正开着哪个视图。它不用瞎猜，直接基于你眼前的界面接着干。

// Agent 自动获得当前页面 / 选中记录等上下文// 无需手动把界面状态拼进 promptconstctx=useAgentContext();

它 vs 同类方案：多数 Agent 框架把"界面状态"当成额外输入，要你手动拼进 prompt，漏一项 Agent 就理解偏了；Agent-Native 把状态当成一等公民，UI 和 Agent 天然同频，你少写一堆胶水代码。

举个具体场景：你在列表页选中了第 3 条订单，转头对 Agent 说"把这条的备注改成已发货"。它不需要你告诉它订单 ID，因为当前选中的记录已经在共享状态里。这种"所见即所操作"的顺滑，靠手动传状态是调不出来的。

核心能力三：开箱即用的 Agent 套件

框架不只是"定义 action"这么薄，它把做 AI 应用常见的一块块都备好了：

• Agent 对话
  ：在同一个 UI 里派活、提问、复核结果
• 鉴权与权限
  ：谁能看、谁能改共享数据，统一管控
• Skills 与记忆
  ：给 Agent 可复用的专业能力和长期上下文
• 自动化
  ：按计划或事件触发 Agent 工作
• Agent 团队
  ：把活派给更专业的子 Agent
• PostgreSQL 后端
  ：生产用 PostgreSQL，本地用 PGlite，跑在任意 Nitro 兼容环境

npx --yes @agent-native/core@latest create \   my-agent --standalone --template chat

一句命令拉起一个带聊天界面的可运行项目，无需自己从零拼脚手架、接数据库、写鉴权。

对独立开发者尤其友好：你不必先成为"全栈 + AI 工程"双修选手，也能在一个项目里同时拥有可交互界面和会干活的 Agent。脚手架、数据库、鉴权这些脏活，框架先替你扛了。

它怎么把 UI 和 AI 拧成一股绳

一句话概括它的设计哲学：UI、Agent、HTTP、MCP、A2A、CLI 全部挂在同一个 action 层上。Agent 通过 action 层干活，而不是去模拟点击；UI 也通过 action 层读写。两端共享数据、共享状态，于是"界面上发生的事"和"AI 干的事"第一次成了同一件事。

这正是它最反直觉也最有价值的地方——很多人做 AI 应用，第一反应是"给 AI 加个能操作界面的自动化"，于是去模拟点击、去抓 DOM。Agent-Native 直接绕开这条路：既然 UI 本来就在调 action，那就让 Agent 也调同一个 action，谁也别绕路。

换个角度想，这其实把"前端工程师"和"AI 工程师"的边界抹平了。过去一个需求要两人对一遍接口，现在一个 action 写定，前端拿去渲染、Agent 拿去执行，接口只有一份。团队协作的摩擦点直接少了一个。

五分钟跑起来

环境要求：Node 18+，有手就行。

# 1. 拉一个独立可运行的 agent 项目 npx --yes @agent-native/core@latest create \   my-agent --standalone --template chat

# 2. 进入目录并安装依赖cd my-agent && npm install

# 3. 启动，打开给出的本地地址即可对话 npm run dev

跑起来后，你定义的每个 action，UI 侧能点、Agent 侧能调、外部还能走 HTTP/MCP——全部一份实现，三种入口。

想更进阶？在 Claude Code 里用 /visual-edit 直接在画布上改运行中的应用，改完让 Claude 把编辑落回源码，不用再一句句 prompt 调 UI。

如果你也踩过这个坑

如果你曾经为了"让 AI 和页面别各说各话"反复填坑，Agent-Native 的思路值得花半小时看看。它把"能力只定义一次"当成铁律，UI 与 Agent 从此共用同一套实现、同一份状态，而不是各写各的、再花力气去同步。

它也不是银弹。如果你的场景里 UI 和 Agent 本就没什么交集，硬套这套模型只会多一层概念负担。但凡你打算让"人能在界面上操作、AI 也能在同样的数据上操作"，Agent-Native 这套"一次定义、五端复用"的打法，基本是目前最省心的那一种。

据 README，该项目已有 7 千 Star，由 Builder.io 团队维护，采用 MIT 许可证，整体仍非常活跃，几乎每天都有提交。文档、示例应用（Clips 会议记录、Slides 演示稿、Mail 邮件、Analytics 看板等）都在官网一站备齐，照着抄就能跑。

仓库在此：github.com/BuilderIO/agent-native。文档与社区入口：agent-native.com 与官方 Discord。