把 AI Agent 接进游戏，不该先绑死模型：用 Vifu 自建可替换的 Agent Gateway
给游戏加入“会思考的角色”时，最容易走向一条看似快捷、却很难维护的路：在游戏服务里直接调用某一家模型 API，把提示词、密钥、会话状态和角色逻辑写进同一个进程。原型当然能跑，但当你需要更换 Agent 提供方、追踪一次行为来自哪次调用、给不同项目分配不同密钥，或者把设计环境与正式运行环境分开时，原来的直连会迅速变成耦合点。
Vifu 是一个 Apache-2.0 许可的开源运行时与可视化创作产品，定位是为本地 AI Agent 提供稳定的项目端点。它把 Dashboard、Rust 编写的 vifu 运行时和 PostgreSQL 组合为一套可自托管的部署；运行时既可以担当 Server，也可以担当 Agent Gateway。对开发者来说，关键不是又多了一个“聊天接口”，而是多出了一层可独立管理的 Agent 接入与游戏运行时边界。
本文不把 Vifu 当成已经完成的万能游戏引擎。它仍是早期项目，官方也明确建议生产环境固定版本。更合适的切入方式是：先理解它怎样将 Provider、项目端点、密钥和可发布的游戏版本拆开，再决定它是否值得放进你的原型或内部工具链。
先把问题拆开：角色逻辑、Agent 接入与游戏发布不是一回事
一个带 Agent 的游戏通常至少有三种变化速度不同的东西：
- 创作侧状态：角色、工具、资源和交互流程会频繁调整；
- Agent 接入侧状态：模型或 Agent Provider 可能替换，连接会断开，也需要观测调用链；
- 运行侧状态：玩家进入的是一个明确的可发布版本，不能随着编辑器里的草稿悄悄变化。
如果所有部分都放在一个 Web 后端，团队往往会用环境变量和条件分支硬凑隔离，结果是“测试角色调用了生产 Provider”或“修复一个连接问题却无法判断影响了哪个项目”。Vifu 的划分比较直接：Server 管理 Profile、Binding、Endpoint、Project 与项目范围的 HTTP 调用；Gateway 与 Provider 连接、发现并调用 Agent；Dashboard 管理界面和本部署的用户会话；PostgreSQL 保存配置、端点、追踪等持久状态。
官方架构图里，应用先请求 Server，Server 通过一条可复用的 WebSocket 与 Gateway 通信，再由 Gateway 到达 Provider；Dashboard 的身份和会话仍保留在部署自己的数据库里。这种结构不能消除模型服务本身的风险，但能把“游戏调用什么”和“如何连到某个 Agent”分为两个可以独立检查的层。
用项目端点代替在代码里散落 Provider 配置
Vifu 给应用提供 OpenAI 兼容的调用面。调用方需要的是项目 base URL、项目 API key，以及作为 model 传入的目标 Agent slug 或 ID，而不是某个 Provider 的专用 SDK。下面的请求结构来自项目 README，地址仅适用于本地默认部署；实际项目应使用自己的端点与密钥：
curl http://localhost:6790/my-project/v1/chat/completions \
-H "Authorization: Bearer $VIFU_PROJECT_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "town-guide",
"messages": [
{"role": "user", "content": "Open the north gate"}
],
"stream": false
}'
这里最值得保留的是“项目范围”而不是 curl 本身。README 说明，一个项目 key 可以被配置为跟随该项目暴露的全部 Agent，也可以只绑定显式选择的一组 Agent。也就是说，游戏客户端或服务端拿到的不是部署级万能凭据；当某个 Agent 从玩法画布中移除，或其暴露状态被关闭，它会对项目 API 不可用。对于需要区分测试关卡、运营工具和正式游戏的团队，这比靠提示词约定“不要调用某角色”更容易审计。
不要把这个接口理解为绕过权限校验的捷径。项目 key 在创建时只返回一次，服务端保存的是经过 pepper 处理的哈希；因此，创建时应立即将原始 key 放入密钥管理系统或部署环境，而不是提交到仓库。远程自托管时还应配置 TLS，不能因为本地示例使用 localhost 就把未加密端点直接暴露到公网。
本地先跑通三层，而不是先猜测命令
Vifu 仓库提供本地开发与 Docker Compose 两种已写明的路径。完整安装包含 Dashboard、运行时和 PostgreSQL 三层；本地开发让 PostgreSQL 留在 Docker 中，而 Rust 运行时与 Dashboard 分别启动。下面是官方 README 给出的最小步骤：
# 在仓库根目录启动 PostgreSQL Docker compose -f docker-compose.yml -f docker-compose.local.yml up -d postgres # 另一个终端：运行 Server 与 Agent Gateway cd crates/vifu cargo run # 再开一个终端：运行 Dashboard cd npm-packages/dashboard bun dev
Dashboard 默认在 http://localhost:6791 提供本地入口。运行时首次启动会创建 ~/.vifu/config.json 和 ~/.vifu/providers.json，并启动 loopback Server 与 Agent Gateway。这里的“首次生成配置”意味着两件事：第一，不应把个人机器生成的配置直接复制到生产；第二，若要将 Server 与 Gateway 分离部署或改变地址，应参考仓库提供的运行时配置示例，而不是自行臆测字段名。
如果你只想验证自托管形态，官方也给出 Compose 入口：
cp .env.example .env docker compose up -d
这会启动 Dashboard、PostgreSQL，以及复用同一运行时镜像、但角色配置不同的两个容器。初次创建的本地账户会得到部署的 admin 角色，后续注册账户默认是 operator；是否开放注册可以通过文档列出的环境变量控制。这个身份模型是部署侧能力，不等于游戏内玩家身份系统，接入时应把两者保持分离。
发布时固定“游戏版本”，别让草稿改写在线体验
Vifu 的 Canvas 与 Short Drama 编辑的是同一份带修订的 gameplay graph。根据 README，发布会创建不可变的 Game Release；Web 游戏、原生引擎或无头进程可以通过持久 HTTP 会话和 CloudEvents over SSE 运行它。演示、资源与 Agent Profile 快照还可以导出为 .vf 项目文件；导入会创建新的可编辑项目，但不会搬运原部署中的凭据和运行历史。
这带来一个很实用的工作流：在开发环境制作并预览草稿，发布一个 Release 给测试人员；如果要修改角色或工具绑定，在新修订上改动并再次发布，而不是直接修改正在运行的配置。它不替代 Git 或数据库迁移，但为“当前玩家运行的是哪份玩法定义”提供了比临时配置开关更清晰的单位。
对于 Agent 有副作用的玩法，建议再加一道自己的业务控制：把游戏内可执行动作映射成最小权限的服务端操作，并记录请求、项目、Release 和业务事件 ID。Vifu 的 trace 与 Gateway 连接状态能帮助定位链路，不能自动替你定义经济系统、未成年人保护或敏感操作的授权规则。
先做一次小范围验收：四个检查点
把这类运行时接到真实项目时，建议不要从“把所有角色迁过去”开始，而是选一个没有高价值副作用的 NPC 或任务做验收。第一，创建一个只暴露单个 Agent 的项目 key，确认用另一个项目 key 调用时得到的是拒绝而非默认回退。第二，在 Gateway 临时断开 Provider 后，确认调用方能够给玩家返回可理解的失败状态，同时保留可定位的请求记录；不要把超时伪装成角色正常回复。第三，发布一个 Release 后修改草稿，确认测试环境仍指向原 Release，直到显式切换。第四，轮换项目 key 并验证旧 key 失效，避免把“只返回一次”的原始密钥散落在开发者终端历史里。
这四步并不要求掌握所有内部协议，却能提前暴露最常见的边界错误：端点权限过宽、连接失败被吞掉、草稿与发布版本混用，以及密钥生命周期没有闭环。等这些基础路径可观测、可回退后，再为复杂角色添加更多工具和长会话状态，整体风险会小得多。
什么时候值得用，什么时候先别用
Vifu 更适合这几类场景：你在做需要替换 Agent Provider 的 AI 原生游戏或互动原型；团队希望自托管 Dashboard、运行时与数据库；或者你需要把项目 API key、角色暴露范围和发布版本放在同一套可管理的边界中。它的 Rust 运行时、OpenAI 兼容端点与 Docker 部署，也让已有 HTTP 客户端能较低成本接入。
反过来，如果你的需求只是单一页面上的一次模型补全，或团队没有维护 PostgreSQL、容器和远程 TLS 的能力，先用更小的直连原型可能更经济。Vifu 的完整部署并不轻：Dashboard、数据库、Server、Gateway 和 Provider 配置都需要运维。README 也提醒其 API 在 1.0 前可能变化，生产使用应锁定版本并在升级前做兼容性验证。
真正有价值的不是“把 Agent 放进游戏”这句口号，而是让接入、权限和发布各自有清晰边界。先用本地三层部署验证 Provider 到项目端点的完整链路，再把一个可回滚的 Release 接进测试关卡；当这条路径稳定后，才值得扩大到更多角色和更复杂的玩法。
相关链接