NotesAgentic/docs/development/前端壳子与接口层开发说明.md

前端壳子与接口层开发说明

更新日期：2026-08-30 适用范围：Vue 3 + TypeScript 页面、Workspace、公共 Service、FastAPI 接口适配和 SSE。 文档用途：帮助团队理解当前前端可用能力、模块边界、启动方式和后续页面开发入口。

1. 当前实现状态

当前前端已经形成一条可安装、可类型检查、可生产构建和可联调的基础链路：

Vue Router
→ App Shell
→ Pinia Store
→ Service / FastAPI DTO Adapter
→ HTTP 或 SSE
→ FastAPI

当前已经落地的页面和公共界面包括：

• Vault 入口页；
• 应用标题栏、主侧边栏、辅助侧边栏和状态栏；
• Workspace 文件树；
• Markdown 写作/源码模式、手动保存和自动保存状态；
• 文件打开、新建、删除和重命名交互壳子；
• Search 查询、筛选、结果列表和 Citation 定位；
• Chat 会话、Provider/Model/Skill 选择和 SSE 输出；
• Agent Run 创建、Trace、取消和权限确认；
• Task 筛选、创建、编辑、状态切换和删除；
• Skill、Plugin 生命周期管理；
• Theme 预览、切换和编辑器 Token 覆盖；
• Settings 的通用、编辑器、Provider、索引、权限和 AI Core 诊断分区；
• 可收起主导航、功能型二级侧栏、状态栏和 Ctrl+P 命令面板。
• Milkdown 可视化写作、CodeMirror 源码/代码块编辑、Markdown 格式栏和 Shiki 只读代码高亮；
• OpenAI、DeepSeek、Ollama 预设、自动模型发现和开发阶段加密 API Key 输入；
• 智能体页面、运行状态、事件、工具和权限详情的中文展示。

原统一占位页已经删除，所有已注册业务路由均指向真实页面。Web Workspace 已通过 FastAPI 连接后端配置的单一真实 Vault，不再回退 Mock 数据；Tauri 多 Vault、原生目录选择、Stronghold 和桌面窗口能力仍在桌面容器阶段接入，不影响页面与 Store 的调用边界。

2. 目录与职责

frontend/src/
├── components/common/          App Shell、导航、命令面板与扩展公共组件
├── contracts/index.ts          UI View Model 与 FastAPI Wire DTO
├── features/                   按页面领域拆分的业务组件
├── features/editor/            编辑器头部与写作/源码编辑区
├── features/vault/             Vault 入口
├── features/workspace/         Workspace 与递归文件树
├── router/index.ts             页面路由和 Vault Guard
├── services/                   HTTP、SSE、DTO 映射和模块 API
├── stores/                     Pinia 状态
└── styles/tokens.css           Design Token

职责约定：

• Component 不直接拼接后端 URL；
• Store 负责页面状态和业务操作编排；
• Service 负责 HTTP/SSE 调用以及 Wire DTO 到 View Model 的转换；
• contracts/index.ts 同时保留界面模型和以 Api 开头的 FastAPI DTO，两者不能混用；
• OpenAPI /openapi.json 是后端 Wire Contract 的最终依据。

3. 路由与页面壳子

已注册路由：

/
/workspace
/search
/chat
/agent/runs/:runId?
/tasks
/extensions/skills
/extensions/plugins
/themes
/settings

除 Vault 入口外，其余路由需要先打开 Vault。全部路由均使用懒加载真实页面组件，既保持首屏包体可控，也避免占位页面掩盖缺失实现。

4. 页面实现边界

页面	当前可用能力	主要 Store / Service
Workspace	文件树、新建、重命名、删除、打开、编辑、保存、模式切换	workspaceStore、editorStore、workspaceService
Search	FTS/Vector/Hybrid、文件夹与标签筛选、结果定位	searchStore、searchService
Chat	会话选择、模型配置、RAG、Skill、SSE、Citation	chatStore、providerStore、chatService
Agent	Run 配置、Tool 选择、Trace SSE、权限确认、取消	agentStore、agentService
Tasks	状态筛选、CRUD、完成与恢复	taskStore、taskService
Skills	列表、详情、安装、启停、卸载	skillStore、skillService
Plugins	列表、权限确认、安装、启停、卸载	pluginStore、pluginService
Themes	主题预览、应用、字体与行高覆盖、恢复默认	themeStore
Settings	通用、编辑器、Provider、索引、权限、诊断	settingsStore、providerStore、相关 Service

5. Workspace 与编辑器

Workspace 当前由以下组件构成：

WorkspaceView
├── EditorHeader
└── EditorPane

SecondarySidebar
└── FileTreePanel
    └── FileTreeNode（递归）

文件树把右键目标保存在 contextTarget，重命名和删除始终作用于实际被右键的节点，不再依赖当前编辑文件。根目录使用 / 表示，新增根级文件时直接写入 Store 顶层数组。

当前 workspaceService 是 FastAPI Workspace Adapter。打开 Vault 时只允许后端 APP_VAULT_PATH 配置的目录，随后通过 Workspace/Note API 读取真实文件树和 Markdown，并完成文件、目录的新建、重命名、移动、保存和删除。接口错误直接进入统一错误链路，不再用 Mock Fallback 掩盖连接或契约失败。

浏览器不能获得任意本地文件系统权限，因此 Web 模式不提供目录选择和多 Vault 管理。进入桌面端阶段后，由 Tauri Host 实现同一 Service 边界下的原生适配器，组件和 Store 无需感知底层传输变化。

6. HTTP 接口层

公共请求由 apiClient.ts 处理：

• 支持 GET、POST、PUT、PATCH 和 DELETE；
• 使用 VITE_API_BASE_URL，并兼容旧的 VITE_API_BASE；
• 自动附加 X-Request-Id；
• 将后端统一错误体转换为 ApiErrorClass；
• 204 响应返回 undefined。

Service 已适配当前 FastAPI Contract：

模块	主要适配内容
Notes	folder、markdown、直接 Note 响应和 {items, page}
Search	数组筛选字段、items/page 响应和 Search View Model 映射
Chat	provider_id、model、messages 和 ModelEvent SSE
Agent	input、秒级 Timeout 字段、Run DTO 和 Permission Decision
Skill / Plugin	嵌套 manifest、安装 package_path 和 Plugin Permission PUT
Provider	Provider Type、Capability 数组、模型列表包装和 Test 响应
Task	due_at、分页响应和当前后端支持字段
Index	all/notes/vectors Scope、Job 与状态 DTO
System	/health 和 /api/status 的真实响应字段

界面模型中存在的展示字段不能直接发送给后端。例如 Task View Model 的 priority 和 source 当前只是界面层字段，Service 创建与更新请求不会把它们发送给不支持这些字段的 FastAPI Contract。

7. SSE

SseClient 同时服务于 Chat 和 Agent Event：

• 使用与普通 HTTP 相同的 API Base URL；
• 支持 POST Chat Stream 和 GET Agent Event Stream；
• 使用 TextDecoder 处理 UTF-8 增量字节；
• 在网络分片之间保留 event 和多行 data 状态；
• 以空行作为单个 SSE Event 的结束标志；
• 识别 Done、RunCompleted、RunFailed 和 RunCancelled；
• 支持 AbortController 主动取消。

Chat Store 已从定时器模拟输出切换为真实 /api/chat SSE。默认离线联调配置为：

provider_id = mock
model       = mock-1

8. 环境和启动

cd frontend
pnpm install --frozen-lockfile
pnpm dev

联调前在另一个终端启动后端：

cd backend
uv run uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

生产构建：

cd frontend
pnpm build

9. 当前验证基线

pnpm build       passed
pnpm test        29 passed
uv run pytest    103 passed
preview smoke    HTTP 200
git diff --check passed

当前前端使用 Vitest 执行 Store、Workspace API Adapter、SSE 恢复游标、Plugin Command/Settings Service、文件树、编辑器组件、智能体标签、轻量动效约束、Markdown 对比度 Token、scoped CSS 选择器约束和 Shiki GitHub 双主题测试；pnpm build 同时执行 vue-tsc -b 与 Vite 生产构建。后端测试出现过 .pytest_cache 无法写入的 Windows 权限警告，不影响 103 项测试结果，也不涉及产品代码。

Vite 当前会提示 Chat 与 Workspace 的部分异步 Chunk 超过 500 kB，这是 Milkdown、CodeMirror、KaTeX 和 Shiki 等编辑/渲染依赖带来的性能优化项，不影响构建成功或功能正确性；进入桌面打包前应通过手动分包或更细粒度动态加载继续优化。

浏览器可视化冒烟在本次执行环境中因浏览器运行资源缺失未能启动；HTTP 冒烟已确认前端入口、后端健康检查与 OpenAPI 均能访问。进入合并验收前，仍建议团队在本机打开各路由完成一次人工视觉检查。

10. 后续开发要求

• 新页面文件与路由修改必须在同一提交中出现；
• 新增或修改接口时同步更新 FastAPI DTO、Service 映射和接口文档；
• 不允许用 as any 或错误返回类型掩盖 Contract 差异；
• SSE 相关变更需要覆盖跨 Chunk、CRLF、多行 data、终态事件和取消；
• Workspace 接入 Tauri 后，需要增加路径规范化、写入失败恢复和外部修改冲突测试；
• 页面新增交互必须经过键盘、空状态、加载状态、错误状态和窄窗口检查；
• Workspace 的 Milkdown 写作模式与 CodeMirror 源码模式共享同一 Markdown 数据源；后续修改编辑器时不得改变 Store/Service 边界，并必须保留文件切换、自动保存和选区格式化回归测试。