Bytebase Page Agent 设计解析内置控制台 AI 助手的前端运行时、工具层与后端代理契约【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebase本文以 docs/plans/2026-03-12-page-agent-design.md 为骨架结合当前仓库frontend/src/modules/agent/的源码实现与 proto/v1/v1/ai_service.proto 的接口契约完整解析 Bytebase 控制台内置页面 AgentPage Agent的架构。读完本文你将掌握该 Agent 的四大组成模块、八个工具的执行语义、系统提示词与页面上下文的注入机制以及前端 Agent 循环与后端 AI 代理之间的数据契约并能在真实代码库中按图索骥继续深入。设计目标与边界Page Agent 的目标是在 Bytebase 控制台内提供一个应用级的 AI 助手它需要具备五项能力理解当前页面当前路由、页面标题、角色与相关业务上下文在控制台内导航调用 Vue Router/React Router 跳转或列出合法路由使用 Bytebase API以当前登录用户身份调用后端接口在页面局部 UI 状态重要时直接操作 DOM按需加载常见任务的复用工作流指引skills。设计文档明确强调Page Agent 是对既有 SQL 编辑器 AI 体验的补充而非替代。它的非目标Non-goals同样清晰不控制非 Bytebase 页面不依赖浏览器扩展或外部页面控制器不会脱离正常 UI 与 API 契约独立改变生产行为。这些边界决定了后续所有设计取舍Agent 的所有动作最终都收敛到页面内可观察的 UI 操作或已有 API 调用这两条合规路径上。架构总览四大组成部分实现由四部分组成形成UI 表面 → 前端运行时 → 工具层 → 后端代理的纵向链路全局 UI 表面浮动 Agent 窗口与应用入口、快捷键前端 Agent 运行时Agent 循环agentLoop.ts串起构建提示词 → 调用 Chat → 执行工具 → 回填结果 → 循环工具层search_api、call_api、navigate、get_page_state、dom_action、get_skill等工具的定义与浏览器端执行后端 AI 代理以 proto/v1/v1/ai_service.proto 为契约的AIService.Chat负责供应商集成与工具调用响应的归一化。设计上最关键的决策是页面感知的操作全部留在前端执行后端仅充当面向模型供应商的代理前端从不直接与模型供应商通信。全局 UI 表面浮动窗口、入口与快捷键设计文档描述的实现挂载点是frontend/src/layouts/BodyLayout.vueVue 时代的入口但当前仓库已完成前端 React 迁移实际挂载位置为 frontend/src/app/RootLayout.tsx——该文件在渲染树中挂载AgentWindow组件并保留了Watermark / Toaster / AgentWindow等全局层级的定位注释。这意味着 Agent 窗口是跨页面常驻的应用级组件而非绑定到某个业务页。各入口的当前实现位置入口文档所述路径当前仓库实际路径Agent 窗口挂载frontend/src/layouts/BodyLayout.vuefrontend/src/app/RootLayout.tsx 内挂载AgentWindow定义于 frontend/src/modules/agent/components/AgentWindow.tsx头部切换按钮frontend/src/views/DashboardHeader.vuefrontend/src/components/header/DashboardHeader.tsx 通过动态import(/modules/agent/store/agent)懒加载接入快捷键定义frontend/src/plugins/agent/index.tsfrontend/src/modules/agent/index.tsx状态存储frontend/src/plugins/agent/store/agent.tsfrontend/src/modules/agent/store/agent.ts其中状态存储使用 zustand immer 实现store/agent.ts其持久化键可在源码中直接确认AGENT_STATE_KEY bb-agent-state-v2会话历史与AGENT_WINDOW_KEY bb-agent-window浮动窗口的位置与尺寸均写入localStorage。会话记录还包含createdTs、updatedTs、totalTokensUsed、page快照、archived、lastError、requiresAIConfiguration、interrupted、runId等字段可见会话维度不仅保存消息还保存了页面临时快照与 token 用量统计。前端 Agent 运行时agentLoop.ts的循环语义Agent 循环实现在 frontend/src/modules/agent/logic/agentLoop.ts对应设计文档描述的六步流程构建系统提示词prompt.ts将会话消息与工具定义发给AIService.Chat接收助手文本与/或工具调用在浏览器本地执行工具调用将工具结果追加进会话重复直到模型返回最终文本响应。源码中可确认的工程细节迭代上限MAX_ITERATIONS 1000防止死循环调用重试MAX_RETRIES 2、RETRY_DELAY_MS 1000指数退避但对400/401/403/404状态不重试这类错误重试无意义且支持AbortSignal中止角色映射通过ROLE_MAP将前端消息角色映射为 proto 的AIChatMessageRole枚举SYSTEM/USER/ASSISTANT/TOOL而非原始字符串工具调用回填助手消息携带tool_calls工具结果消息携带tool_call_id且会保留工具调用的metadata供应商不透明元数据原样回传这一点与 proto 契约严格对应终止语义循环只接受两种终止结果——done({ text, success })完成任务或ask_user(...)挂起等待用户输入若模型返回纯文本而没有调用终止工具循环会以error结束提示 Agent must finish with done(...) or ask_user(...)。同一轮中若已出现ask_user或done其余工具调用会被标记为skipped并生成占位结果避免一个回合内多次终止。工具层八个工具的定义与执行语义设计文档记载的工具集为六个search_api、call_api、navigate、get_page_state、dom_action、get_skill。当前仓库的工具定义文件 frontend/src/modules/agent/logic/tools/index.ts 中实际注册了八个工具——除上述六个外新增了ask_user向用户索要输入/确认/选择与done显式完成任务它们配合agentLoop的终止语义工作。所有工具定义以 JSON Schema 形式声明参数统一的createToolExecutor分发执行。search_api结构化 OpenAPI 索引浏览器这不是自由文本关键词搜索而是结构化 API 索引浏览器实现在 frontend/src/modules/agent/logic/tools/searchApi.ts由./gen/openapi-index生成的端点与 Schema 数据在模块导入时构建内存索引。它支持四种模式模式参数返回内容列出服务无全部服务列表及各自端点数量浏览服务的端点serviceSQLService该服务的全部端点查看端点详情operationIdSQLService/Query请求/响应 JSON Schema查看消息类型schemaInstance消息类型定义对象属性或枚举值实现细节包括operationId支持短格式SQLService/Query自动补全为bytebase.v1.SQLService.Queryschema同样支持Instance→bytebase.v1.Instance前缀补全对google.protobuf.Timestamp/Duration/FieldMask/Empty/Any/Struct/Value等类型提供内建的人类可读说明如时间戳注为 ISO 8601端点详情中会检测 protobufbytes字段并提示通过 call_api 传入的普通字符串会自动按 UTF-8 编码。该文件注释明确标注Ported from backend/api/mcp/openapi_index.go and tool_search.go说明它与仓库 MCP 层backend/api/mcp/openapi_index.go同源。预期工作流是先从提示词中的 API 目录识别服务 →search_api(service...)→search_api(operationId...)→ 再call_api(...)。call_api以当前用户身份执行 API实现在 frontend/src/modules/agent/logic/tools/callApi.ts按operationId执行 Bytebase API可选 JSON body。这是 Agent 直通当前已登录用户可用 API的桥梁。源码中的关键工程点通过getEndpointPath(operationId)从索引解析 HTTP 路径请求以POSTConnect-Protocol-Version: 1头 credentials: include发出复用 Connect RPC 的 HTTP 语义30 秒超时AbortControllersetTimeout请求体会依据请求 Schema 递归做类型规整coerceRequestBody包括把format: byte的字符串字段自动做 UTF-8 → Base64 编码遇到401且非刷新端点自身时先调用/bytebase.v1.AuthService/Refresh刷新令牌后重试一次错误响应会尽量提取message或code字段返回给模型保证 Agent 能读懂失败原因。navigate路由导航或列出路由navigate使用应用路由器实现两种模式给具体path时执行跳转支持/projects/:projectId这类参数占位符传listtrue时返回全部合法路由模式。提示词明确要求模型在不确定路径时先 list 再跳转绝不猜测路径错误路径会导致 404。get_page_state当前页面上下文读取这是读侧核心工具实现在 frontend/src/modules/agent/logic/tools/pageState.ts两种模式默认semantic模式返回path、路由name、params、query、title并叠加extractRouteContext提取的结构化业务上下文mode: dom模式在基础页面状态之上追加 DOM 快照交互元素数量interactiveElements与带引用标记的domTree。需要特别指出没有独立的get_dom_tree工具DOM 检查是get_page_state(modedom)的一部分。DOM 树由 frontend/src/modules/agent/dom/index.ts 的lazyExtractDomTree惰性提取元素以e1、e2等快照内引用标记仅在返回该快照时有效不是持久 ID。语义模式当前只抽取窄上下文集user、project、database、issue。从 frontend/src/modules/agent/logic/context.ts 的实现看这些值由路由感知的 store 查找填充user始终尝试从 app store 取当前用户含 name/email/titleproject由路由参数projectId从 store 查projects/${projectId}database由instanceIddatabaseName组装instances/${instanceId}/databases/${databaseName}资源名查询失败时回退到项目作用域资源名issue由projectIdissueId拉取projects/${projectId}/issues/${issueId}附带状态与类型枚举。dom_action浏览器端 UI 交互dom_action是浏览器端 UI 交互工具实现在 frontend/src/modules/agent/logic/tools/domAction.ts支持的动作包括click、input、select、read、scroll。预期工作流为get_page_state(modedom)获取快照检查快照内的元素引用如[e1]dom_action(refe1, actionclick)或使用 value 参数的输入/选择动作。工具定义里把 DOM 交互定位为最后手段last-resort仅在无 API 覆盖该操作时使用且必须先获取 DOM 快照取 ref。这类引用的生命周期严格限于返回它的快照。get_skill按需加载工作流指引get_skill实现在 frontend/src/modules/agent/logic/skills/index.ts当前内置三个技能query、database-change、grant-permission分别对应 skills/query.ts、skills/databaseChange.ts、skills/grantPermission.ts。不带name时列出技能及描述带name时返回该技能的完整分步指引。设计意图是把多步工作流指引排除在主提示词之外、按需注入从而控制上下文长度。ask_user与doneAgent 的两种终止手段ask_user向用户索要信息支持kindinput自由文本、kindconfirm确认/取消、kindchoose显式选项要求非空options数组每项含label与稳定value还可附带defaultValue、confirmLabel、cancelLabeldone显式结束任务必须提供非空text作为最终展示给用户的回复success标记任务是否成功。这两个工具与agentLoop.ts的终止协议一一对应是 Agent 回合如何收敛到等待用户或完成状态的关键。页面变更锁frontend/src/modules/agent/logic/tools/index.ts 中还实现了一个页面变更互斥锁withPageMutationLocknavigate与dom_action被标记为页面变更类工具当另一个会话正在使用此类工具时当前会话会被拒绝并提示等待。这避免了多个并发 Agent 会话互相抢页面控制权属于工具层之上的并发安全设计。Prompt 与上下文模型提示词构建位于 frontend/src/modules/agent/logic/prompt.ts其buildSystemPrompt生成的系统提示词包含助手身份Bytebase Assistant与安全/使用规则API 服务目录serviceDirectory按数据库管理、SQL 与查询、变更管理、访问与身份、基础设施、策略与合规、工作区、工具类分组列出主要服务及其职责例如DatabaseServiceCRUD、schema 元数据、慢查询、备份、SQLService执行查询、导出、SQL 检查、PlanService/IssueService/RolloutService变更管理、AuthService/AccessGrantService身份与数据访问授权等精简的 Bytebase 领域概念Workspace → Project → Database → Instance → Environment以及 Change ticket 的 create → review → approve → roll out 流程动态页面信息当前路径、页面标题、可用时的角色。当前行为的关键点与设计文档一致且可在 prompt.ts 中直接验证动态路由/页面上下文被折叠进系统提示词而非作为单独的用户消息追加提示词要求模型先调用get_page_state理解当前页面提示词要求模型在常见多步工作流前先get_skill工具选择是上下文敏感的而非一律 API 优先表单、预览、编辑器、创建类页面存在未保存/进行中的 UI 状态API 无法触达时以 DOM 交互优先拉取当前页面不可见的持久化数据、跨资源查询或批量操作时以 API 优先对持久化资源的变更则两者皆可用户在相关页面上则用 DOM 以便看到交互否则用 API 求快明确要求破坏性动作必须先经ask_user确认不得猜测不得用纯文本回复收尾必须以done或ask_user结束。后端 AI 代理契约AIService.Chat后端契约以 proto/v1/v1/ai_service.proto 为唯一事实来源后端实现在 backend/api/v1/ai_service.go。核心要点AIService.Chat(AIChatRequest) returns (AIChatResponse)HTTP 映射为POST /v1/ai/chat认证方式为CUSTOM该 RPC 被标记为mcp_method_class EXCLUDEDMCP 拒绝原因为SENDS_DATA_TO_A_THIRD_PARTY发送数据到第三方说明它不在 MCP 工具面暴露消息角色使用AIChatMessageRole枚举UNSPECIFIED/SYSTEM/USER/ASSISTANT/TOOL而非原始字符串AIChatMessagerole 可选content 仅助手消息携带的tool_calls 仅工具消息携带的tool_call_idAIChatToolDefinitionnamedescriptionparameters_schemaJSON Schema 字符串——前端agentLoop.ts的toolDefToProto正是把 JSON Schema 对象JSON.stringify后填入该字段AIChatToolCallidname JSON 编码的argumentsmetadata其中metadata被注释为供应商不透明元数据如 Gemini thought_signature前端回传工具结果时必须原样回显——这与agentLoop.ts中tc.metadata的保留逻辑一致AIChatRequest.messages与tool_definitions均带audit_behavior OMIT标注审计日志不记录消息与工具定义内容AIChatResponse携带可选usage.total_tokens供前端累计 token 用量。也就是说后端是供应商集成的唯一事实来源并负责归一化各家模型供应商的工具调用响应格式前端循环只需按这一稳定契约序列化即可messageToProto。实现文件地图设计文档给出的持久实现清单与当前仓库的对应关系如下已按当前迁移后的真实路径列出UI 挂载与入口frontend/src/app/RootLayout.tsx、frontend/src/components/header/DashboardHeader.tsx、frontend/src/modules/agent/index.tsx会话/窗口状态frontend/src/modules/agent/store/agent.tsAgent 循环frontend/src/modules/agent/logic/agentLoop.ts提示词构建frontend/src/modules/agent/logic/prompt.ts页面上下文抽取frontend/src/modules/agent/logic/context.ts工具定义与分发frontend/src/modules/agent/logic/tools/index.ts工具实现searchApi.ts、callApi.ts、pageState.ts、domAction.ts、navigate.ts技能frontend/src/modules/agent/logic/skills/index.tsDOM 快照frontend/src/modules/agent/dom/index.ts后端契约与实现proto/v1/v1/ai_service.proto、backend/api/v1/ai_service.go值得注意的是设计文档撰写时引用的路径前缀为frontend/src/plugins/agent/Vue 时代当前仓库已将该模块迁移至frontend/src/modules/agent/并随前端 React 化重构窗口由RootLayout.tsx挂载。阅读本文时若对照设计文档原文请以modules/agent下的路径为准。与之配套的测试同样位于模块内例如 agentLoop.test.ts、tools/index.test.ts、store/agent.test.ts 等可作为验证上述行为细节的直接依据。范围说明与演进设计文档明确指出它作为页面 Agent 的持久设计参考durable design reference刻意排除了早期分阶段实施计划、交接笔记与探索性备选方案——那些内容仅对实现过程有价值不再是当前的事实来源。这也解释了为何文档只描述当前已实现的能力而非愿景式的 roadmap例如 DOM 交互被限定在快照级 ref 语义、上下文抽取被收敛到四个核心实体、工具选择策略被写成上下文敏感的双路径规则。理解这一点有助于把本文档当作一份实现契约而非提案来阅读——文档描述的内容均可在上述源码路径中找到对应实现。【免费下载链接】bytebaseDatabase governance built for humans and agents — controlling changes and access across every major database.项目地址: https://gitcode.com/GitHub_Trending/by/bytebase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考