如何用 --web-ui-dir 打造 ai-memory 自定义前端完整实战指南【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memoryai-memory是专为 AI 编码 Agent 设计的长期记忆系统自动沉淀会话中的项目知识、决策与踩坑记录。它自带的/web浏览器足够好用但如果你想拥有品牌化界面或更强的交互体验只需要一个参数——--web-ui-dir就能把任意你构建的前端SPA直接挂到 ai-memory 服务上与 API 同源、共享鉴权零反向代理成本。本文面向新手带你从零看懂 ai-memory 的 Web 界面再用一条命令切换成自己的自定义前端。一、先认识 ai-memory 的内置 Web 界面内置浏览器是服务端渲染的只读界面可以浏览工作区、项目、Markdown 页面还能做全文搜索。它也是你开发自定义前端时的参考样式。启动方式开启 Web 界面只需加一个开关ai-memory serve --transport http \ --bind 127.0..0.1:49374 \ --enable-web⚠️ 注意把绑定点写为127.0.0.1确保只有本机可以访问。从这两张界面截图可以看到页面结构就是项目列表 → 页面树 → Markdown 正文 最近活动。你的自定义前端只需要把这三块数据用自己喜欢的 UI 重新呈现即可——数据全部来自同一个 JSON API。二、核心机制--web-ui-dir 参数详解--web-ui-dir的作用一句话概括在/web或自定义 slug处托管你自己的静态 SPA 目录替代内置浏览器。它对应的环境变量是AI_MEMORY_WEB_UI_DIR参数定义见 cli.rs。ai-memory serve --transport http \ --bind 127.0.0.1:49374 \ --enable-web \ --web-ui-dir /path/to/your-spa/dist服务启动前会做预校验校验逻辑位于 serve.rs。三条规则新手最容易踩中校验规则不满足时的报错必须同时传--enable-web--web-ui-dir requires --enable-web目录必须真实存在--web-ui-dir is not a directory: ...目录内必须有index.html--web-ui-dir is missing index.html: ...✅新手提示--web-ui-dir指向的是前端项目的构建产物目录如 Vite/React 的dist/不是源码目录。三、你的 SPA 会自动获得什么这是 ai-memory 自定义前端最贴心的部分。挂载逻辑实现在 mount.rs服务端会自动为你的 SPA 做四件事1. 自动注入base href和路径元信息ai-memory 会往index.html的head里注入base href/web/—— 保证 SPA 的相对资源与路由在任意前缀下都能正确解析无需重新构建meta nameai-memory-base-path—— 你的代码可以读它来拼接 API 地址例如${basePath}/api/v1。2. SPA 路由回退Fallback访问/web/任意客户端路由都不会 404——未命中的路径自动回退到index.htmlReact Router、SvelteKit 等客户端路由开箱即用。3. 与 API 同源、同鉴权你的 SPA 和/api/v1挂在同一 origin下走同一套 Bearer Token 鉴权浏览器会弹出 HTTP Basic 提示把 token 作为密码填入即可。这意味着前端不需要处理 CORStoken 的作用域、多用户隔离与内置界面完全一致若你坚持用不同 origin部署 SPA需自行配置--cors-allow-origin详见 docs/frontend-api.md 第 9 节。4. 安全防护路径穿越攻击被静态服务层直接拒绝注入体大小上限 10 MB防止异常模板被无限读入内存。四、前端数据从哪来/api/v1 只读 API 速览自定义前端的所有数据都来自/api/v1这套只读 JSON API写入仍走 CLI 或 MCPAPI 层零写操作天然安全。常用端点端点用途GET /api/v1/workspaces列出所有工作区GET /api/v1/projects?workspace...列出项目GET .../projects/{project}/pages/{path}读取页面 Markdown frontmatter 反向链接GET .../projects/{project}/recent?limit...最近页面活动GET .../projects/{project}/overview?limit...一次性拿到交接 简报 记忆健康度项目总览页一次请求搞定GET /api/v1/search?q.../POST /api/v1/search全文搜索POST 支持多项目范围最多 25 个响应统一为 JSON错误返回{ error: 人类可读信息 }及 400/401/403/404/500 状态码。完整字段、分页、ETag 缓存规则请查官方文档 docs/frontend-api.md。 最简前端骨架其实只需要三步overview渲染首页 →pages渲染目录树 →search接搜索框。五、进阶配置反向代理与子路径部署当 ai-memory 被 Nginx 等反向代理挂在 URL 子路径下时配合另外两个参数即可整体平移前端无需改动代码参数环境变量作用--base-path /wikiAI_MEMORY_BASE_PATH整个 HTTP 面/mcp、/api/v1、/hook、/web整体挪到/wiki前缀下--web-slug /AI_MEMORY_WEB_SLUG把 Web UI / 自定义 SPA 从/wiki/web提升到/wiki根ai-memory serve --transport http --bind 127.0.0.1:49374 \ --enable-web --web-ui-dir ./my-ui/dist \ --base-path /wiki --web-slug /前缀会经过严格的安全归一化只接受 RFC 3986 保留外字符./..段直接拒绝非法值会降级为根路径并打印 WARN不会污染你的 HTML。HTTPS 部署场景可参考 docs/https-via-proxy.md。六、常见问题排查清单症状原因与解决启动即报错退出检查三条预校验规则缺--enable-web/ 路径不存在 / 缺index.html前端资源 404 或路径错乱确认你读的是注入的ai-memory-base-path元信息而不是硬编码前缀API 返回 401服务器配置了 Bearer 鉴权浏览器需通过 Basic 弹窗填入ai-memory generate-auth-token生成的 token多租户下看到别人的数据正常行为actor 级 API 只返回该用户 共享交接的数据想要写入/编辑能力/api/v1是只读设计写操作请走 CLI 或 MCP或在 companion crate 中扩展见 docs/companion-crates.md七、总结一张表看懂你的部署组合场景命令要点只浏览不想写前端--enable-web上线自研 SPA本机--enable-web --web-ui-dir ./dist反代子路径 自定义 SPA再加--base-path /wiki --web-slug /跨域 SPA加--cors-allow-origin https://app.example.com核心材料索引前端集成完整指南docs/frontend-api.md服务参数与安装说明docs/install.md挂载与注入实现crates/ai-memory-web/src/mount.rs参数校验实现crates/ai-memory-cli/src/commands/serve.rs从内置浏览器到品牌化界面--web-ui-dir让 ai-memory 的前端变得完全可插拔。你现在可以 fork 一个自己熟悉的框架对着/api/v1十分钟就能搭出第一版原型——剩下的就是 UI 想象力了 【免费下载链接】ai-memorySolution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors项目地址: https://gitcode.com/GitHub_Trending/ai/ai-memory创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考