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

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

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

## 1. 当前实现状态

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

```text
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. 目录与职责

```text
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. 路由与页面壳子

已注册路由：

```text
/
/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 当前由以下组件构成：

```text
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 使用所选提供商保存的默认值，并支持手动输入。

## 8. 环境和启动

```powershell
cd frontend
pnpm install --frozen-lockfile
pnpm dev
```

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

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

生产构建：

```powershell
cd frontend
pnpm build
```

## 9. 当前验证基线

```text
pnpm build       passed
pnpm test        29 passed
uv run pytest    136 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 权限警告，不影响 136 项测试结果，也不涉及产品代码。

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 边界，并必须保留文件切换、自动保存和选区格式化回归测试。


## 阶段 F 前：前端真实数据清理

已删除运行时的聊天示例、Agent Run/Event/Tool/权限示例、Provider/Model、Task、Skill、Plugin、IndexStatus 常量和 searchMock。测试文件中的隔离桩保留，仅用于自动化验证。

- 所有业务 Store 从空集合开始，由真实 API 填充；连接失败显示错误，不回退演示记录。
- 普通聊天仅显示用户实际输入和 SSE 响应；当前会话列表保留在页面会话内，刷新后清空，后端暂无聊天历史持久化接口。切换会话保留本次会话内的真实消息，取消旧流并屏蔽迟到回调。
- 聊天页移除尚未接入的知识库与 Skill 开关，知识库工具和 Skill 通过 Agent 使用。
- 设置页不再伪造健康状态、版本、42 篇笔记/318 个 Block、模型名称和索引能力开关。状态未获取时显示 unknown/未获取；应用版本来自 package.json，后端版本来自 /api/status。
- GET /api/index/status 增加 total_notes、total_blocks，直接读取 SQLite 的当前索引统计。
- GET /api/permissions/policy 返回 PermissionPolicy 的实际生效值。设置页只读展示；全局策略编辑暂未开放，运行权限确认仍走原有 Agent 接口。
- 删除模拟重启成功逻辑，说明 Web 端不具备进程重启能力；索引页面只保留后端已实现的全量重建。
- Task DTO 不再填充后端未返回的优先级和来源，Agent Token 用量不再把未知输入/输出拆分填成 0。
- Plugin/Skill/Provider 无记录时显示空状态，模型发现失败时允许使用真实的手动模型 ID。

验证：前端 81 项测试、类型检查与生产构建通过；后端 454 项测试通过。新增测试覆盖空初始状态、离线错误、真实统计与权限、测试 Provider 过滤、真实聊天历史及旧流隔离。本次未调用真实付费推理 API。

### MCP 工具中文展示补充

Agent 工具列表按 `mcp.<server_id>.<remote_name>` 的远程工具名匹配中文展示，支持 `web_search`（网页搜索）、`understand_image`（图像理解），并补充 `text.uppercase`（文本转大写）。此映射只影响界面，工具调用与权限选择仍使用完整原始 ID。

卡片默认显示三行摘要，完整服务原文可展开查看，展开操作不会改变工具选择。服务已提供中文说明时优先保留；未收录的 MCP 工具明确提示暂无中文说明，不将本地摘要当作服务协议或自动翻译结果。原始说明及其中的参数规则完整保留。

验证：前端 84 项测试、类型检查与生产构建通过。新增回归覆盖不同服务器命名空间、未知工具、服务中文说明、原文完整性，以及选择工具时保留原始 ID。

### 聊天模型选择审阅修复

返回聊天页时保留仍启用的提供商与手动模型 ID，仅刷新其模型列表；未选择、已删除或已禁用的提供商才回退到默认值。提供商加载失败时保留当前选择并展示错误。新增页面重新挂载与异常分支回归，前端共 89 项测试通过。