Article

项目研究：agent-native

项目研究：agent-native

蓝色像素虾把一个业务 action 连接到多个应用入口
图 1：agent-native 的重点是让 Agent 住进应用，而不是挂在应用旁边。

> 仓库：<https://github.com/BuilderIO/agent-native> > 作者：Builder.io（商业公司，做无头 CMS + Figma 转代码） > Star / Fork：2,296 / 220（截至 2026-06-25） > 创建：2026-03-12（约 3.5 个月大） > 语言：TypeScript > Topics：agents · ai · react > License：README 自称 MIT，但仓库无 LICENSE 文件（GitHub API 返回 null）⚠️ > 自家站点：<https://agent-native.com> > 工程规模：114MB、2,012 commits、14 个子包、6 个开箱即用 skills

「这是什么」一句话定性

把"Agent 不再只是个聊天框"这件事变成一套有工程结构的框架——你写一次 action，UI、Agent、HTTP API、MCP、A2A、CLI 六种入口全部能用，让 Agent 像真实员工一样住在你的 SaaS 应用里，而不是挂在你 App 旁边的装饰品。

它不是 Agent SDK，它是"Agent-First 应用操作系统"。

「它怎么转」逻辑全景图

一个 action 同时驱动 UI、Agent、API、MCP、A2A 和 CLI
图 2：一个 action 是业务原子，六种入口只是它的不同外壳。
agent-native 运转链
│
├─ 触发层：什么时候会想到用它？
│   ├─ 做了个 SaaS，想让 Agent 能操作它的数据（不是只能问&quot;营业额多少&quot;）
│   ├─ 同时想给 AI 编程工具（Cursor / Claude Code / Codex）一套自家项目的 skill
│   ├─ 想给 SaaS 加&quot;AI 协作&quot;功能，但每次新需求都得重写一套工具注册
│   ├─ 内部工具想统一：UI 按钮、Agent tool、API、MCP server 都用同一份逻辑
│   └─ 想用 SQL 数据库作为唯一可信源（不是 vector DB、不是 KV）
│
├─ 核心层：做了什么？
│   │
│   │  ★ 核心抽象：Action
│   │   一个 defineAction({ schema, run }) 同时驱动：
│   │   ├─ UI 按钮（点击）
│   │   ├─ Agent tool（自然语言）
│   │   ├─ HTTP API（程序调用）
│   │   ├─ MCP server（外部 Agent 接入）
│   │   ├─ A2A（Agent 互相呼叫）
│   │   └─ CLI（脚本/调试）
│   │
│   │  ★ 内置能力（package 一览）
│   │   ├─ core        Agent runtime（chat / tools / skills / memory / jobs / handoffs）
│   │   ├─ frame       浏览器外壳（Cmd+I 选中调 Agent、实时多人协作）
│   │   ├─ dispatch    任务调度
│   │   ├─ scheduling  定时/计划任务
│   │   ├─ pinpoint   调试定位（agent 知道你在看哪个元素）
│   │   ├─ embedding  向量嵌入
│   │   ├─ migrate    数据迁移工具
│   │   └─ 多端适配   desktop-app / mobile-app / vscode-extension
│   │
│   │  ★ 开箱即用 skills
│   │   /visual-plan  → 写代码前先出可视规划（带 wireframe、文件改动图、批注）
│   │   /visual-recap → PR/diff 转成可视化复盘
│   │   还有 assets / content / context-xray / design-exploration
│   │
│   │  ★ 集成生态
│   │   ├─ 数据库：任意 Drizzle 支持的 SQL（Postgres/MySQL/SQLite…）
│   │   ├─ 部署：任意 Nitro 兼容主机（Vercel/Netlify/Cloudflare/Node…）
│   │   ├─ 模型：BYO（Anthropic/OpenAI/本地 Ollama…）
│   │   ├─ 编程工具：Claude Code / Codex / Cursor / Pi / OpenCode / Copilot
│   │   └─ 前端：React（先支持）
│   │
│   └─ 自带模板（6+ 个完整 SaaS 模板）
│       Clips（录屏+Agent 修 bug）/ Plans（可视化规划）/ Design（HTML 原型）
│       Content（Obsidian for MDX）/ Slides（演示文稿）/ Analytics（看板）
│
├─ 输出层：怎么判断做对了？
│   ├─ 写一个 action，UI、Agent、API、CLI 四端立刻可用
│   ├─ Agent 能改自己的代码（self-improving）
│   ├─ Agent 和人共同编辑同一个 document（real-time multiplayer）
│   ├─ 数据库是唯一可信源，UI 和 Agent 都基于它
│   └─ 你拥有全部代码（不像 SaaS 工具是租的）
│
└─ 卡点层：新手最容易在哪里翻车？
    ├─ ❌ 把它当&quot;AI 聊天框&quot;用——你只用了 1/10 的能力
    ├─ ❌ 期待它替你写前端——它要的是 action 层、不是组件库
    ├─ ❌ 不懂 Drizzle SQL 就上手——会被 schema 拖住
    ├─ ❌ 忽视 Nitro 部署假设——某些 edge runtime 不支持全部能力
    ├─ ❌ 把 skills 当营销噱头——/visual-plan 是真能省 PR review 时间的
    └─ ❌ 没看清 License——README 说 MIT，仓库却没 LICENSE 文件

「怎么升级」三段位路线图

├─ 入门段（能用，30 分钟）
│   → 跑通两件事：
│     1. npx @agent-native/core@latest create my-app
│        → 选 Headless → 跑通 CLI 调用第一个 action
│     2. npx @agent-native/core@latest skills add visual-plan
│        → 在你的 Claude Code / Cursor 里体验 /visual-plan
│   → 验收：写一个 defineAction，UI 按钮能点、Agent 能调、CLI 也能跑
│
├─ 进阶段（用好，1–3 天）
│   → 需要补 3 个认知：
│     1. action 是&quot;原子操作&quot;——所有 UI / Agent / API 都从这里长出来
│        → 先把业务拆成 action，再让 Agent 反向消费它们
│     2. state 一律走 SQL——不要在 Agent 里塞 JSON KV
│        → Drizzle schema 定义即契约
│     3. skills 是&quot;项目记忆&quot;——不是 prompt 模板
│        → 写自己的 skill，让 Agent 记住你们项目的代码规范
│   → 习惯：每加一个 UI 按钮前，先写 action；再让 UI/Agent/API 共用
│
└─ 高手段（用活，做自己的）
    → 高手和普通人的差距在三件事：
      1. 让 Agent 改自己的代码——self-improving 模式
         业务跑通后，让 Agent 读 issues 自己提 PR
      2. 多 Agent 协作——A2A 协议 + handoffs
         客服 Agent → 转人工 Agent → 转账单 Agent，全靠 action 互联
      3. 把 skills 当作&quot;团队 Onboarding 手册&quot;
         新人入职不是读 wiki，是 npx 一行装上所有项目经验
    → 进阶动作：把你公司的&quot;知识资产&quot;沉淀为 skill 仓库
                像 document 一样每个新项目装一份

「能用在哪」场景迁移

底层逻辑：把"用户界面"和"Agent 能力"统一在同一个原子上（action），让任何 UI 改动天然就是 Agent 能力的扩展。

这个模式可以平移到任何"Agent 要深度融入业务系统"的场景：

场景 1：企业内部管理系统

  • ERP / CRM 的每个按钮都是 action → Agent 就能"代你点"
  • 迁移注意：权限校验必须放进 action 内部，不能依赖 UI 隐藏；Agent 看不见禁用按钮

场景 2：SaaS 的"AI 增值功能"

  • 用户原来点 5 次按钮填表，Agent 一次对话搞定
  • 不需要再写一套"AI 专用的接口"，原 action 直接暴露
  • 迁移注意：rate-limit 一定要区分"人点击"和"Agent 调用"，防止 Agent 误操作刷爆

场景 3：AI 编程工作流

  • /visual-plan 这种 skill 让 Agent 在写代码之前先出可视规划
  • PR review 变成看 wireframe 而不是看 diff
  • 迁移注意：skill 是项目级的，不要做成人人通用——每个 monorepo 装自己那份

部署这个项目的收益 & 风险

agent-native 生产采用前需要审查 license、生态和复杂度边界
图 3：框架很有想象力，但 license、生态锁定和复杂度都要先审清。

好处

  • ✅ 统一抽象：一个 action 6 种入口，DRY 做到极致
  • ✅ 自带 observability / memory / jobs：开箱即用，不重复造轮子
  • ✅ 商业公司背书：Builder.io 有 5 个万 Star 仓库（mitosis 13.8k、qwik-react 8.7k…），不会烂尾
  • ✅ 完整 SaaS 模板：6 个完整可商用的应用直接克隆，节省数月原型工作
  • ✅ SQL 一等公民：数据可控、可审计、不被框架绑架

注意事项

  • ⚠️ License 存疑：README 说 MIT，但 GitHub 仓库无 LICENSE 文件。商用前需向 Builder.io 书面确认
  • ⚠️ 生态锁定 Builder.io：核心 API 是 Builder.io 设计，未来迁移成本高
  • ⚠️ 学习曲线陡：必须懂 Drizzle（SQL 框架）+ Nitro（部署框架）+ Action schema 三件套
  • ⚠️ React-only：Vue/Svelte 暂时不支持，要等社区
  • ⚠️ 3.5 个月项目：API 还在快速演进，breaking change 风险高

风险

  • 🚨 Vendor 风险：框架高度抽象于 Builder.io 的世界观，如果公司调整方向，迁移成本巨大
  • 🚨 复杂度风险：114MB、2,012 commits、14 子包——一个"hello world"项目会很大
  • 🚨 License 风险：LICENSE 文件缺失是事实，不能仅凭 README 一行字当合同
  • 🚨 Skill 质量风险：开箱即用的 skills 也许够 demo，但生产环境可能需要大量调优
  • 🚨 商业化压力：Builder.io 是商业公司，未来可能收费或限制某些能力

一句话灵魂

agent-native 把"Agent 是 SaaS 的一部分"这件事，写进了一个 action 抽象里——你不写 Agent 接口，你写业务 action；Agent 能力是免费的副产品。

如果说 LangChain 是"Agent 的工具箱"，agent-native 是"Agent 住进你 App 的购房合同"——区别是后者让你搬家后还能继续住（own the code），而不是被房东涨租。

返回列表