NotesAgent Frontend

NotesAgent Frontend 是基于 Vue 3、TypeScript、Vite、Pinia、Vue Router、Milkdown 和 CodeMirror 6 的 Web 联调前端。当前页面调用 FastAPI 真实接口，不使用业务 Mock 作为运行时回退；测试文件中的 mock 只用于隔离单元和组件测试。

初始化与运行

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，授权与来源说明随目录保存。

数据边界

笔记、附件、搜索历史、会话、任务、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 组件，安装过程不修改显卡驱动。当前模型选型详见多模态管线与模型运行。

测试与构建

pnpm test
pnpm type-check
pnpm build

阶段 F 合并基线为 29 个测试文件、103 项测试通过，TypeScript 类型检查与 Vite 生产构建通过；构建仍有既有大 bundle 提示。产物位于 dist，不提交 Git。

开发约定

依赖统一使用 pnpm 管理，不混用 npm 或 yarn。
新接口先更新 src/contracts 与 src/services，页面和 Store 不直接散落 fetch 协议细节。
异步页面需要处理加载、空数据、后端错误、重复提交和迟到响应。
功能行为或契约变化时，同一提交同步更新测试和相关文档。
页面需求见前端页面需求说明，后端行为以运行时 /openapi.json 为准。

4.5 KiB Raw Blame History Unescape Escape