80 lines
4.8 KiB
Markdown
80 lines
4.8 KiB
Markdown
# NotesAgent Frontend
|
||
|
||
NotesAgent Frontend 是基于 Vue 3、TypeScript、Vite、Pinia、Vue Router、Milkdown 和 CodeMirror 6 的 Web 联调前端。当前页面调用 FastAPI 真实接口，不使用业务 Mock 作为运行时回退；测试文件中的 mock 只用于隔离单元和组件测试。
|
||
|
||
## 初始化与运行
|
||
|
||
```powershell
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
开发地址为 <http://127.0.0.1:5173>。Vite 将 `/api` 和 `/health` 转发到 <http://127.0.0.1:8000>，因此联调前需要先启动后端。
|
||
|
||
## 页面与能力
|
||
|
||
| 路由 | 当前能力 |
|
||
| --- | --- |
|
||
| `/`、`/workspace` | 选择当前 Vault、浏览目录、编辑和保存 Markdown |
|
||
| `/search` | 全文、向量和混合检索；从后端读取并清空搜索历史 |
|
||
| `/chat` | 流式 AI 对话、知识库上下文与 Citation |
|
||
| `/agent/runs/:runId?` | 创建 Agent 运行，查看可恢复 Trace 与 Tool/Permission 事件 |
|
||
| `/media` | 上传音频、创建/取消/重试转写、修订结果并生成知识库笔记 |
|
||
| `/tasks` | 管理用户、笔记和 Agent 产生的任务 |
|
||
| `/extensions/skills` | Skill 安装、启停与配置 |
|
||
| `/extensions/mcp` | stdio、Streamable HTTP、旧 SSE Server 配置与工具发现 |
|
||
| `/extensions/plugins` | Plugin Host、Command、Settings、Secret 与 MCP 状态 |
|
||
| `/themes` | 内置 Design Token 主题和编辑器显示偏好 |
|
||
| `/settings` | Provider、模型路由、本地模型、CPU/CUDA 组件、请求 JSON、用量与诊断；全局中英文和拼写检查设置 |
|
||
|
||
## 技术结构
|
||
|
||
| 目录 | 职责 |
|
||
| --- | --- |
|
||
| `src/features` | 按页面和业务域组织的 Vue 组件 |
|
||
| `src/stores` | Pinia 状态与页面编排 |
|
||
| `src/services` | FastAPI HTTP/SSE 客户端和 DTO 转换 |
|
||
| `src/contracts` | 与后端契约对应的 TypeScript 类型 |
|
||
| `src/components` | 应用壳、命令面板和共享组件 |
|
||
| `src/utils` | Markdown 清洗、Shiki 高亮等纯工具 |
|
||
| `src/styles` | Design Token、布局、主题和动效 |
|
||
|
||
编辑器使用 Milkdown/Crepe 与 CodeMirror 6；Markdown 展示使用 marked、DOMPurify 和 Shiki。Provider logo 位于 `src/assets/providers`，授权与来源说明随目录保存。
|
||
|
||
语言设置会即时更新主导航、页面标题和各功能页面，并同步更新文档与编辑器的 `lang`。拼写检查使用浏览器或桌面 WebView 提供的本地词典，开关会即时作用于可视化 Markdown、源码编辑器以及普通文本输入；JSON、密码等结构化或敏感输入保持关闭。
|
||
|
||
## 数据边界
|
||
|
||
- 笔记、附件、搜索历史、会话、任务、Trace、模型配置和多模态结果都通过 FastAPI 读写。
|
||
- API Key 只存在于密码输入和提交请求期间，不进入 Pinia 或 `localStorage`。
|
||
- 页面内存可以保存尚未提交的临时状态；后端已经接收的任务和结果由 SQLite/Vault 持久化。
|
||
- 主题、编辑器偏好、侧栏状态和最近 Vault 路径目前保存在浏览器 `localStorage`；它们是设备界面偏好，不作为笔记或模型业务数据。Tauri 集成时由桌面配置存储接管。
|
||
- 前端不直接访问 SQLite，不拼装第三方模型协议；Provider Adapter 和请求覆盖规则由后端执行。
|
||
- 后端不可用时页面显示连接或操作错误，不生成演示数据替代真实结果。
|
||
|
||
当前仍运行在 Web/Vite 环境。后续 Tauri 集成将复用现有 Service/Contract 边界，并由 Rust Host 接管窗口、Vault 选择、Sidecar、Stronghold 和生产沙箱。
|
||
|
||
## 模型设置
|
||
|
||
设置页支持带 logo 的提供商预设、模型发现、聊天/Embedding/转写/声纹能力绑定，以及按 capability、model 和 stream 条件匹配的自定义请求 JSON。请求预览不联网；“发送测试推理请求”使用当前草稿和已保存凭据执行真实短请求。
|
||
|
||
本地模型页显示固定 revision、许可、下载状态和实际磁盘占用。CPU 是默认运行方式；Windows 可从页面安装独立 CUDA 12.8 组件，安装过程不修改显卡驱动。当前模型选型详见[多模态管线与模型运行](../docs/development/多模态管线与模型运行开发说明.md)。
|
||
|
||
## 测试与构建
|
||
|
||
```powershell
|
||
pnpm test
|
||
pnpm type-check
|
||
pnpm build
|
||
```
|
||
|
||
当前基线为 30 个测试文件、106 项测试通过，TypeScript 类型检查与 Vite 生产构建通过；构建仍有既有大 bundle 提示。产物位于 `dist`，不提交 Git。
|
||
|
||
## 开发约定
|
||
|
||
- 依赖统一使用 pnpm 管理，不混用 npm 或 yarn。
|
||
- 新接口先更新 `src/contracts` 与 `src/services`，页面和 Store 不直接散落 `fetch` 协议细节。
|
||
- 异步页面需要处理加载、空数据、后端错误、重复提交和迟到响应。
|
||
- 功能行为或契约变化时，同一提交同步更新测试和相关文档。
|
||
- 页面需求见[前端页面需求说明](../docs/contracts/前端页面需求说明-开发版.md)，后端行为以运行时 `/openapi.json` 为准。
|