《Agent‑Native 怎么用？TypeScript AI Agent 框架安装与开发教程》

页面已经能聊天，Agent 却不能安全地改动业务记录，或 UI 与 Agent 操作后显示的状态对不上。

适合 UI 与 Agent 共用业务能力的获胜方案：Agent-Native。 如果团队使用 TypeScript，并希望两种入口共享 actions、数据与应用状态，先用官方 CLI 创建最小项目，再验证输入校验、权限和状态一致性，确认数据库及部署宿主兼容后再扩展；若只想给现有页面加聊天框，则不必先引入整套应用框架。官方仓库将它定位为 TypeScript 应用框架，而不是单独的聊天组件。

这篇教程适合想创建 TypeScript Agent 应用并实现首个共享 action 的开发者。
如果产品要求 Agent 与 UI 操作同一业务对象，可重点检查授权和状态边界。
负责远程开发或部署选型的工程师，可按依赖、数据库与持续运行要求评估环境。

最后更新于 2026 年 9 月 25 日；命令、接口与部署范围核对自 Agent-Native 官方仓库及文档。 CLI、action API、数据支持或部署说明更新时，应重新创建最小项目复核；本文没有 Zutcloud 实测数据，不据此推断性能、成本或生产可用性。

先判断：项目需要的是共享业务能力，还是聊天入口

Agent-Native 的核心设计是让 UI 与 Agent 通过同一 action 操作应用；action 还可以连接共享数据和应用状态。换句话说，页面按钮和 Agent 工具可以调用同一段业务实现，而不是各自维护一套近似逻辑。官方关键概念说明列出了这些调用面与共享状态的关系。

这对需要“能查看、能编辑、可追踪”的业务产品更有意义，例如任务管理、内容审核或工单处理：用户能在页面直接编辑记录，也能让 Agent 按指令执行相同操作。若产品只是提供不改变业务数据的问答框，或者现有后端已经有稳定的权限与 API 契约，迁移框架的收益可能抵不过改造成本。

选择	更匹配的需求	需要承担的代价	决策条件
Agent-Native	UI 与 Agent 共用业务操作、数据和应用状态	需要理解 actions、权限、数据库及框架部署方式	业务操作需要在页面和 Agent 两端复用
现有应用加聊天入口	Agent 仅回答问题，或调用既有服务接口	UI 与 Agent 的状态、权限和错误处理仍需自行衔接	不需要让 Agent 直接执行核心业务操作
仅用 Agent 工具层	工作主要发生在脚本、任务队列或外部自动化中	仍需自行提供用户查看、编辑和审核的界面	产品并不依赖应用 UI 与 Agent 的共同工作流

关键区别不是有没有聊天窗，而是业务操作是否以同一份契约暴露给两个入口。共享 action 能减少重复实现，却不替代产品自己的授权策略、审计流程或部署验收。

从空目录创建：先跑通官方模板

官方 Quickstart 给出的最小创建命令如下。它使用最新版 CLI 和 chat 模板，因此正式团队项目应把创建结果、依赖锁定方式与后续升级策略一并纳入代码评审。官方 Quickstart及部署单应用说明均列出了这一创建路径。

npx --yes @agent-native/core@latest create my-agent --standalone --template chat
cd my-agent
corepack enable
pnpm install
pnpm dev

启动后先确认模板能正常打开，再查看生成项目的 package.json、锁文件、脚本和环境变量说明。这样做能避免把框架开发仓库的要求误认成所有生成应用的统一下限：官方仓库的开发指南说明，仓库自身需要 Node.js 22 或更高版本、pnpm 10 或更高版本；这不是对每个脚手架生成项目的无条件承诺，应以当前模板和运行宿主的要求为准。仓库开发指南

第一次启动失败时，按这个顺序排查更容易定位问题：命令是否来自项目目录、依赖安装是否完整、模板要求的环境变量是否缺失，以及本地数据库目录是否可写。不要先复制其他项目的环境变量文件；其中的认证密钥或第三方凭据可能不属于当前应用。

写第一个共享 action：校验和业务逻辑只有一份

官方 action 由描述、输入 schema 和 run 执行函数组成。框架将 action 提供给 Agent 作为工具，React 页面则可以经由 useActionMutation 调用同一操作；无效输入应在进入业务执行逻辑前被 schema 拒绝。定义 actions 文档说明了这套结构。

下面采用官方文档中的改名 action 模式。示例假定项目已经定义相应的 deck 数据表和共享访问规则；实际落地时，表结构与授权模型应替换为本项目自己的定义。

// actions/rename-deck.ts
import { defineAction } from "@agent-native/core/action";
import { assertAccess } from "@agent-native/core/sharing";
import { eq } from "drizzle-orm";
import { z } from "zod";
import { getDb, schema } from "../server/db/index.js";

export default defineAction({
  description: "Rename a deck.",
  schema: z.object({
    id: z.string(),
    title: z.string(),
  }),
  run: async ({ id, title }) => {
    await assertAccess("deck", id, "editor");
    const db = getDb();
    await db.update(schema.decks)
      .set({ title })
      .where(eq(schema.decks.id, id));
    return { ok: true };
  },
});

页面按钮用相同 action 名称发起修改：

import { useActionMutation } from "@agent-native/core/client/hooks";

const renameDeck = useActionMutation("rename-deck");

renameDeck.mutate({ id, title });

这就是“共享 actions”的实际含义：UI 和 Agent 重用的是同一套输入约束与业务执行逻辑，而不是自动继承同一份生产级安全保证。schema 负责校验输入形状；示例中的 assertAccess 在写入前检查调用者对目标记录的访问权。读取列表还应按用户可见范围过滤，不能因更新操作有权限检查，就推断查询也已隔离。官方访问控制文档进一步区分了调用资格与记录级访问范围。

验证项	要做的检查	通过条件
输入 schema	传入缺失字段、错误类型或不符合业务规则的值	请求被拒绝，run 不执行
记录权限	使用无权编辑目标记录的身份调用 action	写入前拒绝，数据不改变
UI 调用	页面通过 useActionMutation 修改记录	收到成功或失败状态，页面能反馈结果
Agent 调用	让 Agent 对同一业务对象执行修改	经过同一 action 和对应授权检查
共享状态	Agent 改动后重新检查页面数据	UI 刷新后显示数据库中的实际结果

再验证数据和权限：一次成功演示不等于安全验收

建议先建立只包含测试记录的隔离环境，再按下面的过程回归。Agent 和 UI 是否共用 action，只能说明调用路径有复用；它不能证明用户身份解析、记录归属、错误处理、并发写入或外部调用策略都满足产品要求。

• ✅ 用 UI 创建或修改一条测试记录，记下预期的内容和归属用户。
• ✅ 让 Agent 查询并操作这条记录，再从页面确认显示结果与数据库一致。
• ✅ 换成无权访问该记录的用户测试读取和修改，分别确认被拒绝。
• ✅ 提交缺字段、非法类型或违反业务规则的输入，确认错误清晰且没有部分写入。
• ✅ 检查失败反馈、日志与重试方式，特别是 Agent 发起写入而页面尚未刷新时的用户提示。

Agent-Native 的数据文档说明，action 写入数据库后，客户端会借助同步机制更新相关查询；部署和运行方式会影响同步路径，因此应在预期宿主上复测，而不是只在本机观察页面变化。数据库与同步说明也指出，应用数据通过 PostgreSQL 和 Drizzle 管理，本地开发与部署场景的存储要求不同。

最后核对依赖：本地可运行不代表可部署

下表把开发时容易混淆的依赖拆开。判断宿主时，应查看当前官方部署说明和模板具体配置，不能仅凭“框架支持 Nitro”就推断任意服务都满足持久化、密钥注入和运行时要求。

依赖或环境	本地开发检查	部署前检查
Node.js 与包管理器	按生成模板的配置安装；框架仓库开发指南的版本要求只适用于仓库开发	与构建产物及宿主运行时兼容
数据库	确认本地数据库可以初始化并读写	配置持久化 PostgreSQL；不要将本地 PGlite 文件当作生产数据库
认证与密钥	区分本地测试值与真实凭据	在宿主的环境变量或密钥管理中配置稳定的认证密钥
Nitro 部署目标	默认以本地开发脚本检查应用启动	按目标设置 Nitro preset，验证构建、登录与数据库读写
模型和工具凭据	只添加当前模板和功能实际需要的变量	核验提供方的官方接口、权限范围、密钥存放与失败行为

官方部署文档列出了多个 Nitro 部署目标，并要求部署应用使用持久化 PostgreSQL；本地 PGlite 适合开发，但不应作为生产数据存储。部署范围与数据库要求及生产环境变量说明应在选宿主时一并核对。模型或外部工具的接入也要以当前文档明确支持的接口为准，不要把“可通过 action 调用”误写成框架已保证某个供应商即插即用。

进入试点前，建议完成这份可勾选清单：

• ✅ 在干净目录重新执行 CLI 创建与依赖安装，确认不是依赖开发机残留文件才可启动。
• ✅ 执行项目的构建与类型检查，并记录模板、运行时和依赖锁定方式。
• ✅ 在试点环境验证登录、持久化数据库读写、action 调用及权限拒绝路径。
• ✅ 确认环境变量由部署环境注入，日志能帮助定位失败，但不会泄漏密钥或敏感记录。
• ✅ 让真实产品使用者走一遍 UI 修改、Agent 操作、页面复核和失败回退流程，再决定是否增加自动化或外部工具。

常见问题

Agent-Native 应该怎样安装并新建一个项目？
先使用官方 Quickstart 创建独立 chat 模板，再进入项目目录启用 Corepack、安装 pnpm 依赖并启动开发服务。创建后检查模板的 package.json、锁文件与运行脚本；不要把框架仓库自身的 Node.js 和 pnpm 要求直接视为每个生成项目的统一最低版本。

同一个 action 怎样同时供页面按钮和 Agent 调用？
在 actions 目录通过 defineAction 配置描述、schema 和 run；React 页面用 useActionMutation 调用同名 action，Agent 将其作为工具使用。两种入口共享业务逻辑与输入校验，但页面交互、错误提示和用户确认仍需要分别设计。

怎样确认 UI 与 Agent 操作同一状态且没有越权？
先从 UI 修改一条测试记录，让 Agent 查询并更新它，再回到页面核对结果；随后用无权限身份和非法输入重复验证。共享调用路径不等于授权完整，读取范围、写入前的记录级权限检查和失败反馈都必须单独测试。

Agent-Native 项目部署前要核对哪些依赖？
检查宿主与 Nitro preset、持久化 PostgreSQL、认证密钥，以及项目实际使用的模型或工具凭据；之后执行构建，验证登录、数据库读写和回调。不要把本地 PGlite 或本地启动成功当作生产环境验收结果。

需要远程开发时，按项目阶段选环境

如果当前方案是在个人电脑上长期启动服务，环境差异、设备休眠和个人凭据管理都可能干扰团队复现；通用远程 Linux 环境则无法替代必须依赖 macOS 的构建或验证环节。反过来，若项目持续高负载运行、需要专用硬件接口，或已有长期稳定的自有设备，租用环境未必比自购更合适。

当团队只是需要阶段性远程开发、复现问题或评估 macOS 相关工作流时，可以把 Zutcloud 的 Mac 租用作为一个可选环境，先对照租用 Mac mini 的方案和Mac mini 租用价格信息，再按数据库连通、依赖安装和持续运行要求验证是否匹配。Agent-Native 项目的长期线上服务仍应部署在经过验证的应用宿主与持久化数据库上；租用 Mac 更适合补齐开发或测试环境，而不是默认充当生产服务器。

FAQ

Agent-Native 应该怎样安装并新建一个项目？

先按官方 Quickstart 用 npx 创建独立 chat 模板，再进入项目目录启用 Corepack、安装 pnpm 依赖并启动开发服务。不要把框架仓库自身的 Node.js 与 pnpm 前置要求直接套到每个生成项目；先检查模板中的 package.json、锁文件和运行脚本，再按目标环境匹配版本。

同一个 action 怎样同时供页面按钮和 Agent 调用？

把业务操作定义在 actions 目录，用 defineAction 配置描述、输入 schema 和 run 函数；React 页面通过 useActionMutation 调用同名 action，Agent 则将它作为工具使用。两种入口共用执行逻辑和输入校验，但页面展示、错误提示和用户确认仍要分别设计。

怎样确认 UI 与 Agent 看到的是同一份状态，而且没有越权？

先用 UI 修改一条测试记录，再让 Agent 查询并更新同一记录，随后回到页面确认刷新结果；另外分别用无权限账号、无效输入和无权访问的记录验证拒绝行为。共享 action 不会自动证明授权正确，读取范围、写入前的记录级检查以及失败反馈都要单独测试。

把 Agent-Native 项目部署之前，要先核对哪些依赖？

重点确认目标宿主与 Nitro preset 匹配，生产环境已配置持久化 PostgreSQL 连接、稳定的认证密钥和实际用到的模型或工具凭据；随后执行构建并验证登录、数据库读写及回调。官方文档明确区分本地存储与部署所需的持久化数据库，不能把本地演示成功当作部署验收。