如何用 --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-memory
ai-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 name="ai-memory-base-path">—— 你的代码可以读它来拼接 API 地址，例如${basePath}/api/v1。
2. SPA 路由回退（Fallback）
访问/web/任意客户端路由都不会 404——未命中的路径自动回退到index.html，React Router、SvelteKit 等客户端路由开箱即用。
3. 与 API 同源、同鉴权
你的 SPA 和/api/v1挂在同一 origin下，走同一套 Bearer Token 鉴权（浏览器会弹出 HTTP Basic 提示，把 token 作为密码填入即可）。这意味着：
- 前端不需要处理 CORS；
- token 的作用域、多用户隔离与内置界面完全一致；
- 若你坚持用不同 origin部署 SPA，需自行配置
--cors-allow-origin（详见 docs/frontend-api.md 第 9 节）。
4. 安全防护
路径穿越攻击被静态服务层直接拒绝；注入体大小上限 10 MB，防止异常模板被无限读入内存。
四、前端数据从哪来：/api/v1 只读 API 速览
自定义前端的所有数据都来自/api/v1这套只读 JSON API（写入仍走 CLI 或 MCP，API 层零写操作，天然安全）。常用端点：
| 端点 | 用途 |
|---|---|
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 /wiki | AI_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），仅供参考
