Personal Agent Template 开发指南：基于 Eve 与 Nuxt 构建跨渠道持久化个人 AI 助手

人工智能AI AgentAgent 框架后端工具调用【免费下载链接】eveThe Open Framework for Building Agents项目地址https://gitcode.com/gh_mirrors/eve28/eve点击查看免费下载本指南面向希望在 Eve 生态中快速搭建持久化个人 AI 助手的开发者以仓库内apps/templates/personal-agent-template模板下称 Personal Agent Template为研究对象系统讲解其双服务架构、环境变量配置、内部 API 通信模式、长期记忆流程以及自定义与部署全流程。读完本文后你将掌握该模板从本地启动、接入 Slack / iMessage / Linear 到定制自己的 Agent 与记忆体系的一整套实战方案并能读懂其源码级实现细节。模板是什么Personal Agent Template 是一个由 Eve 与 Nuxt 4 驱动的开源个人 AI 助手模板定位为durable personal AI assistant。它的核心卖点是Web 聊天、Slack、iMessage 三种交互表面共享同一个 Agent、同一份长期记忆且所有记忆写入都必须经过用户显式批准。模板默认以V作为示例 persona你可直接 fork 后按需改造。在仓库中模板的入口文档apps/templates/personal-agent-template/CLAUDE.md以AGENTS.md的方式引入其配套的 AI 编码助手速查文档后者汇总了全部开发要点命令速查、目录结构、文档索引、内部 API 调用模式、记忆流程与自定义检查清单。本文将沿这条主线展开并结合 docs/ARCHITECTURE.md、docs/ENVIRONMENT.md、docs/CUSTOMIZATION.md 三份文档及源码做深度扩充。快速参考常用命令一览在开始之前先熟悉模板的构建与开发命令定义见 package.json命令作用pnpm install安装依赖pnpm dev启动 Nuxt Web 应用本地http://localhost:3000pnpm dev:all通过 Vercel CLI 启动本地双服务图Nuxt Eve agent 对等服务pnpm build生产构建内部为eve buildnuxt build两步pnpm typecheckTypeScript 类型检查pnpm db:generate生成 Drizzle 迁移文件pnpm db:migrate应用数据库迁移需要说明的是模板要求 Node.js 24 与 pnpmengines.node: 24、packageManager: pnpm11.25.0。项目结构三层各司其职personal-agent-template/ ├── agent/ # Eve agentchannels、tools、skills、connections ├── apps/web/ # Nuxt UI、Nitro API、共享应用代码 ├── lib/ # 跨层共享类型与常量agent 与 web 共用 ├── vercel.ts # Vercel 对等服务编排 └── docs/ # 架构、环境变量、自定义指南关键子目录职责如下agent/Eve Agent 的全部逻辑包括agent.ts模型配置、channels/eve、slack、sendblue三个渠道、tools/weather、save_memory、github、skills/如daily-summary.md、connections/Linear MCP、lib/基础指令、内存/ Slack/ 电话内部 API 客户端、instructions.tssession.started钩子用于记忆注入。apps/web/Nuxt 前端app/、Nitro 服务端server/含/api/*、/api/internal/*、数据库 schema 与迁移、Better Auth以及跨层共享代码shared/。lib/Agent 与 Web 两端共享的常量与类型例如lib/agent.ts品牌信息、lib/types/memory.ts记忆类别、lib/connect.tsVercel Connect connector UID。#号 import 别名#*: ./agent/*让 agent 目录内的文件可以以#agent/xxx形式被 Web 侧引用这是模板刻意设计的共享通道。系统架构Vercel 上的对等双服务模板在 Vercel 上以两个协作服务运行vercel.ts通过withEve在构建期编排这两个对等服务Vercel 服务入口职责web/Nuxt UI Nitro APIeve/_eve_internal/eveEve agent 运行时// apps/templates/personal-agent-template/vercel.ts import { withEve } from eve/vercel; export default await withEve({ services: { web: { framework: nuxt, root: apps/web }, }, routes: [{ src: ^(.*)$, destination: { type: service, service: web } }], });整体数据流为用户表面Web 聊天 · Slack DM/提及 · iMessage/Sendblue │ ▼ Eve agentchannels: eve · slack · sendblue / tools: weather · save_memory / connections: Linear MCP │ HTTP Authorization: Bearer INTERNAL_API_SECRET ▼ Nuxt 应用/api/* 公开 API · /api/internal/* agent 专用 · Better Auth · NuxtHub SQLite │ ▼ Vercel ConnectLinear · Slack 等集成也就是说用户从任意渠道发消息都由 Eve Agent 处理Agent 需要读写业务数据时通过带 Bearer 密钥的内部 API 回调 NuxtNuxt 负责认证、数据库与集成授权。这种Agent 无状态、数据收敛在 Web 服务的设计是模板实现跨渠道持久化的基石。内部 API 模式Agent 与 Nuxt 的通信契约模板中最值得复用的工程模式是Agent 侧客户端 →/api/internal/*→server/utils/*这一 HTTP 调用链agent/lib/*-internal.ts → /api/internal/* → server/utils/*所有/api/internal/*路由都要求请求头携带Authorization: Bearer INTERNAL_API_SECRET校验逻辑集中在 apps/web/server/utils/internal-api.tsexport function requireInternalRequest(event: H3Event) { const secret process.env.INTERNAL_API_SECRET?.trim(); if (!secret) { throw createError({ statusCode: 503, statusMessage: Internal API is not configured }); } const authorization getRequestHeader(event, authorization); if (authorization ! Bearer ${secret}) { throw createError({ statusCode: 401, statusMessage: Unauthorized }); } }Agent 侧的调用封装在 agent/lib/internal-api.tsappOrigin()依次取BETTER_AUTH_URL→VERCEL_URL→ 默认http://localhost:3000internalHeaders()则拼装Bearer头并强制要求INTERNAL_API_SECRET已配置。现有内部路由清单路由用途GET /api/internal/memory拉取用户记忆用于会话注入POST /api/internal/memory由 Agent 工具保存记忆GET /api/internal/phone/link根据电话号码解析 App 用户Sendblue/iMessageGET /api/internal/slack/link/member根据 Slack 用户解析 App 用户POST /api/internal/slack/link/consume消费 Slack 链接码例如 apps/web/server/api/internal/memory.get.ts 内部会并行调用getOrCreateProfileForUser与listMemoryForUser返回{ profile, memory }而memory.post.ts用 zod 校验{ userId, category, content, source }后调用setMemoryForCategory落库。这组路由被以下 Agent 侧客户端消费agent/lib/memory-internal.ts—fetchUserContextGET与saveMemoryRemotePOSTagent/lib/phone-internal.ts/agent/lib/slack-internal.ts— 渠道身份绑定。环境变量从本地三件套到生产全量最小启动集本地开发只需这三个变量获取方式BETTER_AUTH_SECRET执行openssl rand -base64 32BETTER_AUTH_URL本地为http://localhost:3000生产为你的线上 URLINTERNAL_API_SECRET执行openssl rand -base64 32web 与 eve 两个服务必须一致cp .env.example .env这三个变量足以支撑本地开发。上 Vercel 时需在web 与 eve 两个服务上都配置并额外准备数据库。数据库本地 SQLite 与线上 Turso本地开发时NuxtHubhub.db: sqlite直接使用.data/db/sqlite.db文件无需任何配置。但在 Vercel 等 serverless 平台无法创建本地文件若不配置托管数据库每个请求都会报错Error: ConnectionFailed(Unable to open connection to local database .../.data/db/sqlite.db: 14)解决方案是从 Vercel Marketplace 开通 Turso 数据库README 中的 Deploy 按钮会自动附带也可以对已有项目执行vercel integration add turso。这会为项目注入TURSO_DATABASE_URL与TURSO_AUTH_TOKENNuxtHub 在构建期检测到这两个变量后自动从本地文件切换到远端 libSQL因此配置后需要重新部署。随后拉取环境并迁移vercel env pull .env --yes pnpm db:migrate可选变量NUXT_PUBLIC_SITE_URL用于 SEO 规范化 URLOpen Graph、Twitter card、canonical缺省时回退到请求源地址。认证与内部密钥BETTER_AUTH_SECRET必需Better Auth 用于签名会话与令牌的随机密钥。BETTER_AUTH_URL必需Nuxt 应用的公开 URL既用于认证回调也作为 Agent → Nuxt 内部 API 调用的基础 URL。INTERNAL_API_SECRET必需Eve agent 服务与 Nuxt 内部 API 共享的 Bearer 令牌用于记忆读写、Slack 账号绑定、iMessage 电话绑定。两个服务必须完全一致缺失或不一致时记忆注入、Slack 绑定、iMessage 认证会静默失败或返回 401。SendblueiMessage可选以下变量设置在eve服务上BETTER_AUTH_URL则两个服务都要设以便 Agent 解析电话绑定变量必填说明SENDBLUE_API_KEY是Sendblue 控制台的 API key IDSENDBLUE_API_SECRET是API 密钥SENDBLUE_FROM_NUMBER是你的 Sendblue 号码E.164 格式如15551234567SENDBLUE_WEBHOOK_SECRET是通过sb-signing-secret头校验的共享密钥SENDBLUE_STATUS_CALLBACK_URL否外发消息的送达状态回调SENDBLUE_ALLOWED_SERVICES否逗号分隔的服务白名单默认仅iMessage设为iMessage,SMS,RCS可全部接受AI 模型模板不在.env.example中定义 AI 密钥默认模型在 agent/agent.ts 中export default defineAgent({ model: anthropic/claude-sonnet-4.6, modelOptions: { providerOptions: { anthropic: { thinking: { type: enabled, budgetTokens: 2048 }, }, }, }, });在 Vercel 上由 Eve 平台负责 provider 配置本地开发时按 Eve 文档为你选择的 provider 配置环境。本地勿提交的文件.env本地密钥、.data/NuxtHub SQLite、.eve/Eve 开发缓存、.vercel/Vercel CLI 链接元数据均已被 gitignore。重置本地数据库rm -rf .data/db pnpm db:migrate长期记忆从注入到保存的完整闭环记忆是模板的灵魂功能其数据流可分为三个环节1. 会话注入session.startedagent/instructions.ts 监听session.started事件先取ctx.session.auth.current?.principalId若用户已认证则调用fetchUserContext(userId)拉取GET /api/internal/memory返回的{ profile, memory }再经buildUserContextPrompt拼装成关于用户 记忆的提示段落追加到BASE_INSTRUCTIONS之后注入本会话。提示段落的结构agent/lib/memory-internal.ts# About this userbio如有、时区、首选语言# Memory按类别逐个输出## 类别名 该类别完整内容。注意注入发生在会话建立时因此导入或修改记忆后必须新开一个聊天Agent 才会拾取最新上下文。2. Agent 保存save_memory工具 Web 审批 UIagent/tools/save_memory.ts 用defineTool定义关键特征输入 schema 用 zod 约束reason保存理由updates15 条每条{ category, content }其中content必须是该类别整段替换文本而非增量approval: always()— 每次保存都必须经过用户审批Web 端由ToolSaveMemory.vue渲染审批 UIexecute中逐条调用saveMemoryRemotePOST/api/internal/memorysource: agent服务端由 apps/web/server/api/internal/memory.post.ts 落库。3. 档案管理 UISettings → Profile用户可在设置页对记忆执行导入、查看、编辑、删除。记忆类别固定为 5 个见 lib/types/memory.ts类别枚举UI 标签导入解析别名work_contextWork Contextwork contextpersonal_contextPersonal Contextpersonal contextactive_focusActive Focusactive focus/active contextinstructions_preferencesInstructions Preferencesinstructions preferences/instructions and preferencesproject_historyProject Historyproject history每类只保存一段散文文本保存时整块替换setMemoryForCategory会清空该类别旧行再写入新行。对应的 Drizzle 表user_memory定义于 apps/web/server/db/schema/memory.ts含user_id category联合索引。此外模板还提供 Raycast 风格的 ChatGPT 导出粘贴导入解析器apps/web/server/utils/memory-import.ts。渠道接入Slack 与 iMessage 的实战实现Slack账号绑定与上下文注入agent/channels/slack.ts 基于slackChannel实现凭据来自 Vercel ConnectconnectSlackCredentials(slack/v)自定义 fork 时替换 slug消息到达后先尝试解析link code命令调用consumeSlackLinkCodeRemote消费 Web 端生成的链接码成功则回复绑定完成未绑定的 Slack 用户会收到指引打开集成页生成链接码再在 DM 中发送link code已绑定用户通过fetchSlackLinkForMember查到 App 用户用buildAppSessionAuth构造会话认证使 Slack 会话复用与 Web 相同的身份、记忆与集成授权同时把发送者的 display name、username、email 及最近线程消息注入上下文让 Agent 知道是谁在说话、上文说了什么。iMessage / Sendblue纯文本世界的审批降级agent/channels/sendblue.ts 实现了完整的 Sendblue 渠道值得注意的设计点Webhook 路由为POST /eve/v1/sendblue/webhook先校验sb-signing-secret头、跳过 typing 事件与is_outbound/非RECEIVED消息、默认拒绝群聊入站消息按 E.164 号码通过GET /api/internal/phone/link解析 App 用户未绑定号码会收到去 Settings → Profile 添加号码的指引由于 iMessage 没有浏览器审批 UI工具审批被降级为纯文本 YES/NO 回复input.requested事件把 pending 工具请求记录到pendingInputByThread用户回复yes/y/ok/approve或no/n/skip/deny触发source.respondsave_memory在 iMessage 上被特殊处理模板明确告知用户记忆保存需在 Web 档案中完成Memory saves are not available in iMessage…避免在无 UI 渠道上执行记忆写入。LinearMCP 连接即工具agent/connections/linear.ts 使用defineMcpClientConnection连接https://mcp.linear.app/mcp凭据通过 Vercel Connectmcp.linear.app/linear按用户维度下发completeAuthorization还带 0/500/1000/2000ms 的重试退避。连接成功后Agent 即可直接调用 Linear 的 issues/projects/cycles 等工具。基础指令agent/lib/base-instructions.ts为此内置了强约束Always call the tools first绝不用state: openLinear 没有该状态总结时输出 identifier/title/status/priority——这些规则直接避免了大模型凭记忆作答和无效查询。自定义清单把 V 变成你的 Agent模板以V为示例 personafork 后按以下清单逐项替换lib/agent.ts — 品牌信息name/slug/tagline/description/avatar.iconagent/lib/base-instructions.ts — persona、语气、工具使用与记忆行为规则agent/channels/slack.ts —connectSlackCredentials(slack/你的slug)agent/agent.ts — AI 模型与 provider 选项。同时需要同步更新的还有apps/web/app/app.config.ts中的站点元数据site.name/title/description/tagline、apps/web/public/下的banner.png/og.png/favicon.ico品牌素材以及发布 fork 时的package.json元信息。扩展点新工具、新技能、新集成新增工具在agent/tools/创建defineTool参考 agent/tools/weather.ts 与 agent/tools/save_memory.ts如需自定义渲染在apps/web/app/components/chat/tool/添加组件并挂到MessageContentEve.vue。工具目录按约定自动发现具体以 Eve 文档为准。新增技能在agent/skills/写 Markdown 即可参考 agent/skills/daily-summary.md晨间简报从注入的记忆取 active focus → 查 Linear 未完成 issues → 输出 Today/Linear/Suggested next 三段式并在首页快捷操作中引用。GitHub 集成通过 Vercel Connect OAuth github-tools/sdk/eveconnector UID 在 lib/connect.tsGITHUB_CONNECTOR github/personal-agent与server/connectors.ts保持同步工具在session.started时按用户 token 动态装配agent/tools/github.ts。创建命令vercel connect create github --name personal-agent与vercel connect attach github/personal-agent。Linear / Slack 集成均走 Vercel ConnectLinear 无需改代码connector 固定为mcp.linear.app/linearSlack 需把 slug 换成自己的。数据库模型一览SQLite 经由 NuxtHubschema 定义在 apps/web/server/db/schema/迁移文件在server/db/migrations/。核心表表用途user/session/accountBetter Auth 认证threads聊天线程user_profile姓名、时区、电话user_memory按类别的长期记忆phone_links电话 ↔ App 用户映射Sendblue/iMessageslack_linksSlack ↔ App 用户映射slack_link_codes临时链接码迁移流程为pnpm db:generate→pnpm db:migrate。本地开发与 Vercel 部署本地自托管pnpm install cp .env.example .env pnpm db:migrate pnpm dev打开http://localhost:3000注册账号即可开始聊天。如需同时跑起 Agent 侧使用pnpm dev:allVercel CLI 本地模式同时运行 Nuxt 与 eve 对等服务。部署 fork核心注意事项双服务webeve由 vercel.ts 编排两侧环境变量一致尤其是INTERNAL_API_SECRET与BETTER_AUTH_URL生产数据库开通 Turso 后vercel env pull .env --yes pnpm db:migrate应用迁移生产迁移在部署后执行不要在构建期依赖本地 SQLite 文件。小结这套模板的工程价值从源码与文档可以看出Personal Agent Template 的工程要点可以归纳为四点Eve 与 Nuxt 双服务对等部署、Bearer 密钥保护的内部 API 作为 Agent ↔ 业务数据通道、按类别整块替换的长期记忆模型注入 审批保存 UI 管理三段式、多渠道Web/Slack/iMessage共享同一身份与记忆的绑定机制。无论你是想 fork 它直接产出个人助手还是研究 Eve 框架下Agent 全栈 Web 服务的协作范式这份模板都提供了完整且可运行的最佳实践参考。深入源码的入口包括 agent/、apps/web/server/ 与 docs/ 三处配合仓库根目录的 AGENTS.md 可快速建立全局认知。赞分享人工智能AI AgentAgent 框架后端工具调用【免费下载链接】eveThe Open Framework for Building Agents项目地址https://gitcode.com/gh_mirrors/eve28/eve点击查看免费下载相关推荐个人助理 AI Agent 开发指南从任务调度到习惯学习构建你的 Personal Assistant个人助理 AI Agent 开发指南从任务调度到习惯学习构建你的 Personal Assistant 个人助理Personal AssistantAI文档教程知识库OpenAgent 实战指南基于 LLM、RAG 与 Agent 循环构建自托管个人 AI 助手OpenAgent 实战指南基于 LLM、RAG 与 Agent 循环构建自托管个人 AI 助手 OpenAgent 是一个开源的下一代个人 AI 助手平台人工智能大模型AI 应用AI AgentRAGMCP Clients交互助手浏览器控制代码智能体GUI 自动化AI 技能后端前端本地部署agentmemory 开发指南基于 iii-engine 三原语构建的 AI 编码 Agent 持久化记忆系统agentmemory 开发指南基于 iii engine 三原语构建的 AI 编码 Agent 持久化记忆系统 agentmemory 是一个为 AI 编码人工智能AI 应用Agent 记忆RAGMCP 服务知识图谱上一篇Loop完全免费的 macOS 窗口管理工具用径向菜单告别拖拽窗口下一篇Liger-Kernel 模型适配决策矩阵为 HuggingFace 模型自动补丁的 12 个架构判定创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考