TencentDB-Agent-Memory 团队记忆控制台前端:MemoryPanel Web 开发与部署实战指南

原创2026-09-11 10:25:471,811 阅读
文章标签:人工智能AI AgentAgent 记忆本地部署MCP 服务知识图谱后端前端

TencentDB-Agent-Memory 团队记忆控制台前端:MemoryPanel Web 开发与部署实战指南

本指南以仓库中 MemoryPanel/web/README.md 为骨架,完整讲解 Team Memory Control 管理界面的技术栈、本地开发启动流程、Vite 开发代理配置、生产构建产物托管方式,以及前端与 Control API 的对接边界与凭证安全规范。读完本文,你将能够在本地一键拉起 Control + 前端两套服务,理解 /api/v1 与 /v3 两条请求链路的代理规则,并掌握基于 X-Tdai-Service-Id / X-Tdai-User-Key 的无 Cookie 无状态登录与请求鉴权机制。

一、项目定位:无状态 Control 的 Web 管理界面

MemoryPanel/web 是 Team Memory Control(简称 Control)的 Web 管理界面,负责对接同仓库的无状态 Control 服务。Control 本身是一个"不保存服务端登录会话、不维护本地用户数据库"的团队记忆管理控制台,用于管理团队、用户、Agent、任务及其关联的 Skill、Wiki、Code Graph 和 Chat Memory 资产(参见 MemoryPanel/README.md)。

前端在整个体系中的职责可以概括为三层:

  1. 管理界面:通过浏览器提供团队、成员、Agent、API Key、Skill、Wiki、Code Graph、Chat Memory 与任务工作台的可视化管理入口;
  2. 凭证持有者:登录凭证由前端自行持有并缓存(无 Cookie、无服务端会话),每次业务请求通过自定义 Header 注入;
  3. 请求代理消费者:开发期依赖 Vite Dev Server 的代理能力,把不同前缀的请求分发到 Control(/api/v1)与记忆网关(/v3)两套后端。

二、技术栈与目录结构

2.1 技术栈

按 package.json 实际依赖,前端技术栈如下:

类别 选型
框架 React 18(react@^18.3.1)
语言 TypeScript 5
构建工具 Vite 6(vite@^6.0.7)+ @vitejs/plugin-react
路由 React Router(react-router-dom@^7.18.1,采用 HashRouter)
状态管理 Zustand(zustand@^5.0.14)
样式 Tailwind CSS 3 + @tailwindcss/typography + TDesign(tea-component)
国际化 i18next + react-i18next
图可视化 sigma / graphology(用于 Code Graph 与 Wiki 知识图谱)
其他 lucide-react 图标、sonner 提示、react-markdown + remark-gfm 渲染 Markdown

值得注意的是,前端使用 createHashRouter(见 routes/index.tsx),而非 BrowserRouter。源码注释说明这是为了"保持与旧版 hash 路由兼容,避免刷新 404(静态部署不需要服务端 fallback 配置)"——这意味着构建产物可以直接以纯静态方式托管,无需在 Web 服务器上配置 SPA fallback 规则。

2.2 源码目录脉络

从 src 目录结构看,前端代码按职责划分:

src/
├── components/        # 通用组件(登录门、Markdown 渲染、路由守卫、设置弹窗)
├── constants/         # 菜单等常量
├── i18n/              # zh-CN / en-US 双语资源
├── layouts/           # GlobalHeader、TabBar、ConsoleLayout 整体布局
├── lib/
│   └── api/           # 对 Control API 的分域封装(base / auth / teams / users / agents / assets / skills / tasks / chat-memory / meta-instances)
├── pages/             # Workbench、Wiki、Code、Skills、ChatMemory、Team 各业务页面
├── routes/            # 路由表(HashRouter)
├── services/          # 账号、资产范围、权限、当前角色等业务 store
├── stores/            # auth / backend 状态
└── utils/

路由表定义了 8 个核心页面:工作台(/)、Wiki(/wiki)、Code(/code)、Skills(/skills)、Chat Memory(/memory)、成员(/team/members)、Agent(/team/agents)、API Key(/team/api-keys),全部挂在 ConsoleLayout 父路由之下。

三、本地开发:完整启动流程

前端依赖 Control 后端才能正常工作,因此正确顺序是先启动 Control,再启动前端。

3.1 第一步:启动 Control(仓库根目录 / MemoryPanel)

在仓库根目录(即 MemoryPanel/)执行:

pnpm install
cp .env.example .env
cp config/metadata-instances.example.json config/metadata-instances.json
pnpm dev

三点实操提示:

  • config/metadata-instances.json 是实例注册表,内含部署环境提供的实例 ID、Gateway 地址和 API Key,属于敏感文件,已被 Git 忽略,不得提交(字段说明见 metadata-instances.README.md 与 metadata-instances.example.json);
  • Control 默认监听 http://127.0.0.1:8123,健康检查端点为 GET /health;
  • 使用 Wiki 或 Code Graph 功能时,还需要可访问的 Knowledge Service 与 Memory Gateway 作为外部依赖。

3.2 第二步:启动前端

cd web
npm install
cp .env.example .env
npm run dev

浏览器访问 http://127.0.0.1:5173 即可打开管理界面。.env.example 中给出了两个可选环境变量(详见 .env.example):

# Control 后端地址(vite proxy),默认 http://127.0.0.1:8123
# VITE_TMC_BACKEND_URL=http://127.0.0.1:8123

# 记忆 Gateway(可选,/v3 代理),默认 http://127.0.0.1:8420
# VITE_SKILL_GATEWAY_URL=http://127.0.0.1:8420

注意:Vite 不会热加载环境变量,修改 .env 后需要重启 dev server 才会生效。

3.3 前端包管理说明

后端使用 pnpm、前端使用 npm(见 MemoryPanel/README.md 与 package.json),两个目录的依赖互相独立,务必在对应目录下分别安装,不要混用包管理器。

四、开发代理:双链路请求转发

vite.config.ts 是前端开发期的"路由器"。对照源码 vite.config.ts,默认代理配置如下:

请求前缀 默认目标 环境变量 说明
/api/v1、/health http://127.0.0.1:8123 VITE_TMC_BACKEND_URL 链路 A:Control 后端(Meta / Skill / Chat Memory / Knowledge / Agent 等公开 API)
/v3 http://127.0.0.1:8420 VITE_SKILL_GATEWAY_URL 记忆网关(/v3/skill/* 等数据面接口)

从源码可以看到两个关键实现细节:

  • host: '0.0.0.0':开发服务器对所有网卡开放,方便容器或局域网内其他设备访问(而 Control 后端默认只监听 127.0.0.1);
  • changeOrigin: true:代理时会改写请求头中的 Host 为后端目标,避免后端因 Host 校验而拒绝请求。

如需连接其他开发环境,请在未提交的 web/.env 中写入实际地址(通过 VITE_TMC_BACKEND_URL / VITE_SKILL_GATEWAY_URL 覆盖默认目标),不要把内部地址、账号或凭证写入 README、源码或已跟踪的环境文件。

五、生产构建与产物托管

npm run build

build 脚本实际执行 tsc && vite build(见 package.json),即先做 TypeScript 类型检查、再执行 Vite 构建,任何类型错误都会直接中断构建。产物输出到 web/dist/(源码中 outDir: 'dist' 且 emptyOutDir: true)。

Control 支持通过 UI_DIST_DIR=./web/dist 配置项同源托管这些静态文件——即由 Control 服务直接对外提供页面与 API,前端无需单独部署 Nginx 或静态服务器。结合前面提到的 HashRouter,这种静态托管不需要任何 SPA fallback 规则即可支持页面刷新与深链直达。

构建完成后可用 npm run preview 本地预览产物效果。

六、API 边界:前端对接的公开契约

6.1 前端使用的 Control API

前端仅对接以下 Control 公开 API 前缀(同时登记在 MemoryPanel/README.md 中):

  • /api/v1/meta/*:实例、身份与元数据管理
  • /api/v1/skill/*:Skill 管理
  • /api/v1/chat-memory/*:Chat Memory 管理
  • /api/v1/knowledge/*:Wiki 与 Code Graph 管理
  • /api/v1/agent-overview/*:Agent 资产聚合
  • /api/v1/agent/*:Agent 生命周期操作

对接边界以仓库 docs/api 下的公开契约为准(如 meta-api.openapi.yaml);未列入公开契约的外部服务接口不属于前端对接范围,前端也不得直接调用。

6.2 无 Cookie 鉴权模型:Header 注入

README 强调"登录凭证保存在浏览器 localStorage,业务请求通过 X-Tdai-Service-Id 和 X-Tdai-User-Key Header 发送"。源码给出了完整的实现证据链:

  1. 会话缓存(panelSession.ts):登录凭证(instanceId + userKey + 可选的 user)以 JSON 形式缓存在 localStorage 的 tdai-panel.session 键下。源码注释说明:早期版本曾用 sessionStorage(tab 级,新开 tab 需重新登录),改为 localStorage 后多 tab 共享登录态,登出时通过 storage 事件同步;
  2. 请求注入(base.ts):metaPost 每次请求自动从会话中读取凭证并注入两个 Header——X-Tdai-Service-Id(实例 ID,即注册表 id = 内核 x-tdai-service-id)与 X-Tdai-User-Key(用户 API Key);⚠️ Header 名以 meta-api.openapi.yaml v1.1.0 为准,早期文档使用的 X-Metadata-Instance-Id 已改名,若仍按旧名发送,Control 会返回 400 MISSING_INSTANCE_ID;
  3. 登录验活(auth.ts):登录流程为 ① GET /meta/instances 选择实例 → ② 用户输入自持的 user_key(sk-mem-… 格式)→ ③ POST /meta/auth/verify(此时 Header 仅带 X-Tdai-Service-Id,user_key 只放 body)→ ④ 返回 valid === true 后把凭证写入会话;
  4. 401 全局处理:请求层在收到 401 时会派发 auth:unauthorized 自定义事件,App 层监听后清空 auth 状态并展示登录页;
  5. Meta 信封解析:所有 Meta 接口返回统一信封,code !== 0 或 data 为空时按错误处理,并优先从信封中提取 message / request_id 构造可读错误信息(error-message.ts 负责最终格式化)。

安全底线:前端不得记录、展示或上传完整凭证。user_key 是用户凭证,只能通过请求 Header 传递;实例注册表中的 api_key 仅供服务端调用外部服务,绝不返回浏览器。

七、常用命令速查

命令 说明
npm run dev 启动 Vite 开发服务器(默认端口 5173)
npm run mock 以 mock 入口启动(VITE_ENTRY=mock vite)
npm run build TypeScript 类型检查并构建到 web/dist/
npm run preview 本地预览构建产物
npm run lint:check ESLint 检查 src/**/*.{ts,tsx}(lint 带 --fix 自动修复)
npm run format:check Prettier 格式检查 src/**/*.{ts,tsx,css}(format 自动格式化)

八、安全与提交规范

综合前端 README 与 MemoryPanel/README.md 的安全要求,前端开发与提交需遵守:

  • .env、真实实例注册表、日志和测试报告不得提交到版本库;
  • 文档与示例只能使用 example.com、回环地址及明显占位符,禁止出现内部地址、账号或凭证;
  • 提交前建议运行 bash scripts/secret-scan.sh --strict 扫描敏感信息(脚本位于 MemoryPanel/scripts/secret-scan.sh);
  • 若凭证曾进入 Git 历史,应立即轮换凭证,并在发布前清理历史记录。

九、小结

MemoryPanel/web 是一个典型的"无状态后端 + 纯前端凭证持有"管理控制台实现:本地开发依赖 Vite 代理把 /api/v1 与 /v3 双链路分别转发给 Control 与记忆网关;生产构建产物可直接交给 Control 同源托管;鉴权完全基于 localStorage 会话与 X-Tdai-Service-Id / X-Tdai-User-Key Header 注入,无 Cookie、无服务端会话。理解这套启动流程、代理边界与凭证模型,是继续深入阅读前端各业务页面(pages)、API 分域封装(lib/api)以及 Meta OpenAPI 契约 的前提。

登录后查看全文
TencentDB-Agent-Memory