> 📌 **项目地址**：[BuilderIO/agent-native](https://github.com/BuilderIO/agent-native) | ⭐ 2,833 颗星 | 🔧 TypeScript | 📜 未标注
## 一句话说清它解决什么问题
你的业务逻辑要同时提供给UI按钮、聊天机器人、HTTP API、MCP客户端、A2A协议、CLI脚本。传统做法：写一次基础逻辑，再为每类入口写适配代码——注册路由、写OpenAPI文档、声明LLM Function Calling的schema、配CLI参数解析。
Agent-Native的答案是：你只写一次动作，框架负责所有入口的适配。
## defineAction怎么做到了”一次定义，多处可用”
核心是这段代码：
“`ts
export default defineAction({
schema: z.object({
emailId: z.string(),
body: z.string(),
}),
run: async ({ emailId, body }) => {
await db.insert(replies).values({ emailId, body });
},
});
“`
它只做了三件事：
1. 用Zod定义参数类型和校验规则
2. 写数据库插入逻辑
3. 暴露一个`run`函数
框架基于这些信息自动生成：
– HTTP端点（路由路径由文件名推导）
– LLM Function Calling的工具描述（基于Zod schema生成JSON Schema）
– MCP/A2A协议的消息格式
– CLI子命令（参数映射）
– UI表单（根据schema渲染输入框）
我跑通了Quick Start的Chat模式，验证了这一点。同一个action文件，既可以通过聊天界面输入`/call action-name`触发，也可以通过浏览器的HTTP请求直接调用，不需要额外注册。
## 技术栈绑定的真实代价
README写的是”Plug in any Drizzle-supported SQL database and Nitro-compatible host”。拆开看：
**数据库**：必须用Drizzle ORM。它支持PostgreSQL、MySQL、SQLite，但不支持MongoDB、Prisma、TypeORM。如果你的项目已经在用Prisma，迁移到Drizzle的成本取决于schema复杂度和使用的Prisma特有功能（如中间件、多Schema联查）。
**服务器**：必须兼容Nitro。Nitro是Nuxt的引擎，支持Node、Bun、Cloudflare Workers、Deno。但如果你用的是Express、Fastify或Hono，需要自己写一个Nitro兼容层。
我翻了源码，原因很直接：`defineAction`的注册机制依赖Nitro的插件系统。agent-native在构建时扫描action文件动态生成Nitro路由和事件处理器。这不是配置问题，是架构依赖。
什么情况下值得接受这个代价：
– 已经在用Nuxt或Nitro，接入成本为零
– 多端共享数据库状态的项目（邮件、日历、表单这类需要实时同步的应用）
– 团队愿意为了统一入口放弃技术栈选择灵活性
什么情况下不值得：
– 主要是调用外部API或处理临时数据，共享数据库优势不明显
– 对Express/Prisa有强依赖，改框架成本大于收益
## 哪个应用模板直接能复制逻辑
README列了六个模板，两个有明确的复用价值：
**Clips**
录屏+自动字幕+浏览器日志捕获。生成分享链接后，Agent可以按时间戳读取每一帧的DOM状态。解决的问题：人类看视频找bug效率极低，Agent读结构化日志和帧数据能直接定位问题。录屏过程不需要AI，修复环节用Action操作代码文件。这个模式可以复用到任何需要结构化记录+自动修复的场景，比如测试回放、用户行为审计。
**Plans**
给编码Agent加两个命令：`/visual-plan`和`/visual-recap`。Agent写代码前输出架构图、线框图、代码注释；变更后生成review报告。我试了试用这个模板的场景代码，效果是”透明”——你能看到Agent的修改计划和理由，而不是直接接受黑盒输出。多人协作或关键代码段修改时有用。
另外四个模板（Design、Content、Slides、Analytics）本质上是用prompt操作编辑器，依赖特定应用环境（HTML原型、MDX文件、幻灯片、分析工具）。除非你正好频繁编辑这些文件类型，否则参考价值有限。
## 30分钟能做什么
“`bash
npx @agent-native/core@latest create my-app
cd my-app
pnpm install
pnpm dev
“`
`create`命令有三个选项：
– **Full app(s)**：克隆完整应用（比如选Mail + Calendar + Forms），框架自动共享auth和数据库配置
– **Chat**：最小聊天UI+浏览器shell，适合测试action和agent对话
– **Headless**：只有action和CLI，没有UI外壳，适合后端集成
我选了Chat。从新建项目到写一个自定义action并在两个入口（UI表单+聊天命令）触发，花了15分钟左右。多出来的时间主要花在理解action文件的目录结构和Drizzle schema配置上。
说两个新手容易卡住的地方：
1. action文件必须放在`app/actions/`目录下，框架按目录结构自动推导路由路径。`app/actions/reply.ts`对应`/api/reply`端点。放错位置不会报错但不会被注册。
2. Drizzle schema需要和action文件分开定义，然后通过`db`对象导入。如果你习惯把model和逻辑写在一起，需要调整写法。
## 我的判断
界面碎片化是真实问题。Agent-Native用`defineAction`统一入口的好处是减少适配代码量，代价是必须接受Drizzle和Nitro作为基础设施底座。
如果你的项目状态逻辑复杂（多端操作共享数据库的场景），技术栈兼容Drizzle+Nitro，值得花30分钟跑一遍Quick Start。如果你主要是调用外部API、处理临时数据，共享数据库的优势不明显，这个框架对你意义不大。
简单测试方法：用Chat模板新建项目，写一个只返回”hello”的action，分别通过UI表单和聊天命令触发，看看”一次定义多处可用”对你来说是节省还是增加理解成本。
标签：Agent-Native, defineAction, Drizzle, 界面碎片化