# 前端页面需求说明（开发版）

> 文档用途：供团队在第一阶段进行页面设计、Vue 开发、前后端联调和验收。  
> 文档性质：开发需求基线，不是最终视觉规范或产品宣传文档。  
> 依据：`../architecture/第一阶段分工表.md`、`../architecture/AI笔记软件技术栈说明-团队版-v2.3.md`、`后端接口契约-开发版.md`。

> 实现状态：更新至 2026-08-31。全部已注册业务路由均已有真实页面；Markdown 写作/源码模式、Search、Chat、智能体执行轨迹、扩展管理、设置、Provider 预设、模型发现和开发阶段加密凭据输入均已落地。Web Workspace 已连接 FastAPI 管理的真实单 Vault；Tauri 原生目录选择和多 Vault 尚未接入。

## 1. 第一阶段目标

桌面端需要形成一条可以完整演示的本地知识工作流：

```text
选择本地 Vault
→ 浏览并编辑 Markdown
→ 自动保存和建立索引
→ 搜索或向 AI 提问
→ Agent 调用 Tool / RAG
→ 展示回答、Citation 和 Agent Trace
→ 点击 Citation 定位并高亮原笔记
```

前端交付重点：

- 能完整操作 Workspace 和 Markdown 编辑器；
- 能使用全文、向量和混合模式搜索；
- 能使用普通 AI Chat 和 Agent 模式；
- 能展示 Streaming、Citation、Tool Call、权限确认和 Agent Trace；
- 能管理 Skill、Plugin、Theme 和 Provider；
- AI Core 不可用时，文件浏览与 Markdown 编辑仍可使用；
- 页面只调用 Service，不直接访问数据库、模型厂商协议或 Stronghold。

## 2. 技术与交互基线

| 项目 | 约定 |
| --- | --- |
| 框架 | Vue 3、Composition API、TypeScript、Vite |
| 状态管理 | Pinia，只保存跨组件或跨页面状态 |
| UI 基础 | 当前为项目公共组件、CSS Design Token 与 Element Plus 图标；复杂无障碍 Headless 组件后续按需引入 Reka UI |
| 编辑器 | Milkdown 为默认编辑模式，CodeMirror 6 为源码模式 |
| 桌面容器 | Tauri 2；文件、密钥、Sidecar 和系统能力通过 Rust Command |
| 本地 AI API | FastAPI；普通请求使用 HTTP JSON，流式数据使用 SSE |
| 样式 | 所有主题相关属性使用 Design Token / CSS Variables |
| 时间 | API 使用 UTC ISO 8601，页面按系统时区显示 |
| 错误 | 根据后端 `error.code` 处理，不解析第三方异常文本 |

## 3. 页面信息架构

建议使用一个常驻桌面壳层，避免主要功能之间频繁跳转和丢失编辑状态。

```text
App Shell
├── Title Bar / Window Controls
├── Primary Sidebar
│   ├── Workspace
│   ├── Search
│   ├── AI Chat
│   ├── Tasks
│   └── Extensions
├── Secondary Sidebar
│   ├── File Tree
│   ├── Search Filters
│   ├── Conversation List
│   └── Extension List
├── Main Content
│   ├── Markdown Editor
│   ├── Search Results
│   ├── Chat Conversation
│   ├── Agent Trace
│   └── Settings
├── Optional Right Panel
│   ├── AI Chat
│   ├── Agent Trace
│   ├── Outline
│   └── Backlinks
└── Status Bar
    ├── Save Status
    ├── Index Status
    ├── AI Core Status
    └── Provider / Model
```

### 3.1 建议路由

路由用于页面定位，不代表必须将编辑器销毁后重新创建。

| 路由 | 页面 | 优先级 |
| --- | --- | --- |
| `/` | 启动与 Vault 入口 | P0 |
| `/workspace` | Workspace 与 Markdown Editor | P0 |
| `/search` | Search | P0 |
| `/chat` | AI Chat | P0 |
| `/agent/runs/:runId` | Agent Run 与 Trace | P0 |
| `/tasks` | Tasks | P1 |
| `/extensions/skills` | Skill Manager | P0 |
| `/extensions/plugins` | Plugin Manager | P0 |
| `/themes` | Theme Manager | P1 |
| `/settings` | Settings | P0 |

## 4. App Shell 公共需求

### 4.1 左侧主导航

- 固定展示 Workspace、Search、AI、Tasks、Extensions 和 Settings 入口；
- 当前入口具有明确选中状态；
- 支持收起，只显示图标；
- 导航切换不得丢失未保存的编辑内容；
- Plugin 提供的 Sidebar Panel 只能挂载到预留区域，不能任意修改导航结构。

### 4.2 顶部与窗口区域

- 显示当前 Vault 名称和当前文件名；
- 文件有未保存修改时显示状态标识；
- Tauri 环境下预留窗口拖动区和窗口控制区域；
- Web 开发模式下不得依赖 Tauri API 才能完成基础页面渲染。

### 4.3 状态栏

至少显示：

- `已保存 / 保存中 / 保存失败 / 外部文件已变化`；
- `索引空闲 / 排队 / 处理中 / 失败`；
- `AI Core 正常 / 启动中 / 不可用`；
- 当前 Provider 和 Model；
- Agent 运行时显示运行、等待权限或取消状态。

状态栏中的异常项可点击进入对应恢复操作，例如重试保存、查看索引任务、重启 AI Core 或打开 Provider 设置。

### 4.4 Command Palette

第一阶段至少支持：

```text
打开文件
创建笔记
全局搜索
切换编辑模式
打开 AI Chat
运行当前 Skill
打开 Settings
执行已注册 Plugin Command
```

Command Palette 使用受控命令注册表，Plugin 不直接操作 Router 或 Pinia 内部状态。

## 5. 启动与 Vault 入口

### 5.1 页面目标

负责建立桌面工作区和 AI Core 连接。用户未选择 Vault 时，不进入空白编辑器。

### 5.2 页面内容

- 最近打开的 Vault；
- “打开本地 Vault”按钮；
- “创建 Vault”按钮；
- AI Core 启动状态；
- 最近一次打开失败的恢复提示；
- 开发模式下可显示后端地址和健康检查结果。

### 5.3 交互流程

```text
选择 Vault
→ Rust Host 校验目录权限
→ 启动或连接 AI Core
→ 轮询 /health
→ 建立带 Session Token 的 API Client
→ 读取目录树
→ 进入 Workspace
```

### 5.4 异常状态

- Vault 不存在：从最近列表移除或重新定位；
- Vault 无权限：提示重新授权，不自动更改目录；
- AI Core 启动失败：允许进入 Workspace，并明确标记“AI 功能不可用”；
- 索引未建立：进入 Workspace 后在后台启动索引任务。

## 6. Workspace 与 Markdown Editor

### 6.1 页面目标

提供本地 Markdown 笔记的浏览、创建、打开、编辑、保存、移动和删除能力，是应用的主工作区。

### 6.2 页面布局

| 区域 | 内容 |
| --- | --- |
| Secondary Sidebar | Vault 文件树、创建笔记/文件夹、刷新、折叠目录 |
| Editor Header | 文件名、路径、标签、保存状态、编辑模式切换 |
| Main Editor | Milkdown 或 CodeMirror 6 |
| Right Panel | Outline、Backlinks、AI Chat、Agent Trace |
| Status Bar | 字数、光标位置、保存、索引、AI Core 状态 |

### 6.3 文件树需求

- 展示 `Notes` 和允许展示的用户目录，不展示 `.ainote` 内部目录；
- 支持创建、重命名、移动和删除 Markdown 文件及文件夹；
- 删除前必须确认，并明确是否可恢复；
- 支持右键菜单和键盘操作；
- 外部编辑器修改文件后刷新对应节点；
- 当前文件、已打开文件和外部变化文件具有不同状态；
- 所有文件操作通过 `WorkspaceService` 调用 Rust Command，不在组件中直接散布文件系统调用。

### 6.4 编辑器需求

- 默认使用 Milkdown；
- 支持切换到 CodeMirror 6 Markdown 源码模式；
- 两种模式共享同一份 Markdown 字符串；
- 切换模式前同步当前内容，不能覆盖较新的编辑结果；
- 支持自动保存、手动保存和保存失败重试；
- 自动保存需要 debounce，并显示明确状态；
- 支持标题、列表、任务列表、引用、链接、图片、表格、代码块和数学公式的基础 Markdown 展示；
- 打开 Citation 时根据 `block_id` 或 offset 滚动定位并高亮；
- 高亮为临时状态，用户继续编辑后可自动取消；
- 外部文件发生变化且本地存在未保存内容时，不自动覆盖，需展示冲突处理提示。

### 6.5 笔记状态

```text
idle
dirty
saving
saved
save_failed
external_changed
conflict
```

### 6.6 接口与服务

| 操作 | 调用 |
| --- | --- |
| 文件读取与保存 | `WorkspaceService` / Tauri IPC |
| 笔记元数据 | `GET /api/notes`、`GET /api/notes/{note_id}` |
| 创建笔记 | `POST /api/notes` |
| 更新笔记 | `PATCH /api/notes/{note_id}` |
| 移动笔记 | `POST /api/notes/{note_id}/move` |
| 删除笔记 | `DELETE /api/notes/{note_id}` |

Markdown 正文以本地文件为持久化载体。前端不得把 Pinia 或浏览器存储当作正文的最终存储。

## 7. Search 页面

### 7.1 页面目标

统一提供全文、向量和 Hybrid Search，并允许用户从结果直接回到原笔记位置。

### 7.2 查询区

- 搜索输入框；
- 模式选择：`fts / vector / hybrid`；
- 文件夹范围；
- 指定笔记；
- 标签；
- 创建和更新时间范围；
- 分页或继续加载；
- 是否显示命中片段。

### 7.3 结果项

每项至少显示：

- 笔记标题和文件路径；
- Heading Path；
- 命中片段；
- 检索分数；
- 标签或必要元数据；
- Citation 定位信息。

点击结果执行：

```text
打开对应 Note
→ 切换到 Workspace
→ 定位 block_id / offset
→ 高亮命中内容
```

### 7.4 页面状态

- 初始状态：显示搜索说明或最近查询；
- 加载状态：保留旧结果并标记正在更新；
- 空结果：给出调整关键词、范围或模式的建议；
- Vector 不可用：保留 FTS 搜索，并提示向量索引状态；
- Reranker 不可用：展示降级结果，不阻断搜索；
- 索引重建中：提示结果可能不完整。

### 7.5 接口

```text
POST /api/search
GET  /api/index/status
POST /api/index/rebuild
GET  /api/index/jobs/{job_id}
```

## 8. AI Chat 页面与侧边面板

### 8.1 页面目标

支持普通模型对话和基于当前 Vault 的知识问答。独立页面与 Workspace 右侧面板复用相同 Chat 组件和 Store。

### 8.2 页面布局

- 会话列表；
- 消息时间线；
- Provider / Model 选择器；
- RAG 开关及检索范围；
- Skill 选择器；
- 附件入口；
- 输入框、发送、停止生成；
- Citation 区域；
- 打开对应 Agent Trace 的入口。

### 8.3 Streaming 展示

前端只处理统一 ModelEvent：

| 事件 | 页面行为 |
| --- | --- |
| `TextDelta` | 追加回答正文 |
| `ThinkingDelta` | 写入可折叠思考区域，不与正文混合 |
| `ToolCallStart` | 创建 Tool Call 占位卡片 |
| `ToolCallDelta` | 更新参数预览 |
| `ToolCallEnd` | 标记 Tool Call 参数接收完成 |
| `Usage` | 更新 Token Usage |
| `Error` | 结束加载并显示按 code 分类的恢复操作 |
| `Done` | 完成消息并释放 Streaming 状态 |

页面不能把第三方 Provider 的原始流事件直接写入组件。

### 8.4 Citation 展示

- 回答正文中显示编号引用；
- 消息底部展示 Citation 列表；
- Citation 包含笔记标题、路径、Heading Path 和片段；
- 点击后打开笔记并高亮 Block；
- 音频 Citation 额外显示时间范围和说话人，并支持跳转到音频时间；
- Citation 丢失或文件已移动时显示不可定位状态，不导致整条回答消失。

### 8.5 接口

```text
POST /api/chat              ModelEvent SSE
GET  /api/providers
GET  /api/providers/{provider_id}/models
GET  /api/skills
```

## 9. Agent Run 与 Trace 页面

### 9.1 页面目标

展示 Agent 的运行状态、模型步骤、Tool Call、Tool Result、权限确认、Token Usage、Citation 和最终结果。

### 9.2 创建 Agent Run

创建前允许配置：

- 用户任务；
- Provider 和 Model；
- Skill；
- 允许使用的 Tool；
- `max_steps`；
- Tool Timeout；
- Run Timeout；
- Token Budget；
- 是否允许网络；
- 最大并发 Tool 数量。

### 9.3 Trace 时间线

按 `sequence` 排序展示 AgentEvent：

```text
RunStarted
ThinkingDelta / TextDelta
ToolCall
PermissionRequired
ToolResult
Usage
Citation
RunCompleted / RunFailed / RunCancelled
```

Tool Call 卡片至少显示：

- Tool 名称与来源；
- 参数摘要，默认折叠长文本；
- 权限名称和授权状态；
- 开始时间、耗时；
- 成功或失败；
- Tool Result 摘要；
- 可展开的错误 code 和 message。

Trace 不显示完整 API Key、Authorization Header 或未经用户允许的完整笔记正文。

### 9.4 权限确认

收到 `PermissionRequired` 后显示阻塞式确认组件，内容包括：

- 请求的 Tool；
- 权限命名空间；
- 操作影响；
- 参数摘要；
- `仅本次允许 / 本次会话允许 / 拒绝`。

提交接口：

```text
POST /api/agent/runs/{run_id}/permissions/{request_id}
```

不得默认批准 `notes.delete`、`notes.write`、`network.request`、`secrets.use` 等高影响权限。

### 9.5 Run 状态

```text
queued
running
waiting_permission
completed
failed
cancelled
```

页面刷新后先读取 Run，再重新订阅 SSE。收到重复事件时按 `run_id + sequence` 去重。

### 9.6 接口

```text
GET  /api/agent/runs
POST /api/agent/runs
GET  /api/agent/runs/{run_id}
POST /api/agent/runs/{run_id}/cancel
GET  /api/agent/runs/{run_id}/events
POST /api/agent/runs/{run_id}/permissions/{request_id}
GET  /api/tools
```

## 10. Skill Manager

### 10.1 页面目标

查看、安装、启用、停用和卸载 Skill，并在运行前展示 Tool、权限、检索配置和模型能力要求。

### 10.2 列表与详情

列表项显示：

- 名称、版本、描述；
- 启用状态；
- 状态：`installed / disabled / ready / dependency_missing / permission_required / error`；
- 缺失依赖数量；
- 所需权限摘要。

详情显示：

- Manifest；
- Prompt 说明；
- Tool 列表及来源；
- Retrieval 配置；
- Required Capabilities；
- 缺失的 Plugin 或 Tool；
- 安装或升级时新增的权限。

### 10.3 交互规则

- 安装前显示权限确认；
- 更新后新增权限必须重新确认；
- `dependency_missing` 时禁用“运行”；
- Provider 不满足 Required Capabilities 时提示切换 Provider/Model；
- Skill 不执行 Python 或 JavaScript，不展示“运行脚本”入口。

### 10.4 接口

```text
GET    /api/skills
POST   /api/skills/install
GET    /api/skills/{skill_id}
POST   /api/skills/{skill_id}/enable
POST   /api/skills/{skill_id}/disable
DELETE /api/skills/{skill_id}
```

## 11. Plugin Manager

### 11.1 页面目标

管理 Plugin 生命周期、权限和 Contribution，并展示 Plugin 为 Agent/Skill 提供的 Tool。

### 11.2 列表状态

```text
installed
disabled
starting
ready
error
dependency_missing
permission_required
```

列表项显示名称、版本、描述、状态、启用开关、权限数量和 Contribution 数量。

### 11.3 详情内容

- Plugin Manifest；
- Backend 类型与 Transport；
- 权限列表；
- Tool、Command、Importer、Exporter；
- Sidebar Panel、Settings Section；
- 依赖它的 Skill；
- Host 健康状态和最近错误；
- 启用、停用和卸载操作。

### 11.4 安全要求

- 安装和权限升级必须确认；
- 停用后立即从 UI 隐藏其 Contribution；
- 卸载前展示受影响的 Skill；
- Plugin UI 只能使用 Plugin Bridge，不得直接访问 Rust Command、Stronghold、Pinia 内部状态或任意本地路径；
- Plugin 错误不能阻断 Workspace 和其他 Plugin。

### 11.5 接口

```text
GET    /api/plugins
POST   /api/plugins/install
GET    /api/plugins/{plugin_id}
POST   /api/plugins/{plugin_id}/enable
POST   /api/plugins/{plugin_id}/disable
DELETE /api/plugins/{plugin_id}
```

## 12. Theme Manager

### 12.1 页面目标

查看内置和已安装主题、预览 Design Token、切换主题，并在主题异常时恢复默认主题。

### 12.2 页面内容

- 主题卡片：名称、作者、版本、明暗类型、缩略预览；
- 当前主题标识；
- 实时预览区域；
- 编辑器字体、字号等允许用户覆盖的 Token；
- 恢复默认主题；
- 导入主题入口作为后续能力预留。

### 12.3 约束

- 业务组件只能引用 Design Token，不写主题专用颜色；
- 主题 CSS 只能覆盖允许开放的变量和样式；
- 主题资源路径需要由 Host 校验，不能读取 Vault 外任意文件；
- 主题加载失败时立即回退默认主题，并保留错误提示。

## 13. Tasks 页面

### 13.1 页面目标

统一展示 Markdown 中的任务和 Agent 创建的任务，支持基本筛选和状态更新。

### 13.2 页面内容

- `todo / in_progress / done / cancelled` 分组或筛选；
- 标题、描述、关联 Note、截止时间；
- 来源标识：用户创建、笔记解析或 Agent 创建；
- 打开关联笔记；
- 创建、编辑、完成和删除任务。

### 13.3 接口

```text
GET    /api/tasks
POST   /api/tasks
GET    /api/tasks/{task_id}
PATCH  /api/tasks/{task_id}
DELETE /api/tasks/{task_id}
```

## 14. Settings

Settings 使用分区导航，不把全部配置堆在一个表单中。

### 14.1 General

- 启动时恢复上次 Vault；
- 自动保存间隔；
- 界面语言和时间显示；
- 日志目录入口；
- 应用版本与 AI Core 版本。

### 14.2 Editor

- 默认编辑模式；
- 编辑器字体与字号；
- 行宽、行高、自动换行；
- Markdown 预览行为；
- 拼写检查和代码块选项。

### 14.3 Providers

列表展示 Provider 类型、名称、Base URL、默认模型、启用状态和 Capability。

支持：

- 新建、编辑、启用、禁用和删除 Provider；
- 拉取模型列表；
- 选择默认模型；
- 测试连接并显示耗时；
- 根据 Capability 标记是否支持 Chat、Tool Calling、Vision、Streaming 等。

当前 Web 联调阶段，API Key 通过 Credential API 交给 FastAPI，由 Fernet 加密保存；前端仅在提交期间持有明文，Provider 和 Store 只保留 `credential_id`。页面只能回显“已配置/未配置”，不得回显完整密钥。Tauri 集成后由 Stronghold 替换后端开发存储实现，接口边界保持不变。

接口：

```text
GET    /api/providers
GET    /api/providers/presets
POST   /api/providers
GET    /api/providers/{provider_id}
PATCH  /api/providers/{provider_id}
DELETE /api/providers/{provider_id}
GET    /api/providers/{provider_id}/models
POST   /api/providers/test
GET    /api/credentials/{credential_id}
PUT    /api/credentials/{credential_id}
DELETE /api/credentials/{credential_id}
```

### 14.4 Index 与 Models

- 当前索引状态；
- Pending Job 数量；
- Embedding Provider / Model；
- Reranker；
- 重建全部、文本或向量索引；
- 模型下载、失败和磁盘占用状态；
- FTS 可用但向量不可用时展示降级说明。

### 14.5 Permissions

- 展示 Skill 和 Plugin 已授权权限；
- 撤销持续授权；
- 配置高影响 Tool 的确认策略；
- 明确 `allow / confirm / deny`；
- 不显示 Stronghold 中的明文 Secret。

### 14.6 AI Core Diagnostics

- `/health` 和 `/api/status`；
- Sidecar 状态和重启按钮；
- 当前 API 地址仅在开发或诊断模式显示；
- 日志入口；
- 最近启动失败信息；
- “AI Core 不可用时仍可编辑 Markdown”的说明。

## 15. 公共状态管理

| Store | 负责状态 | 不应负责 |
| --- | --- | --- |
| `workspaceStore` | Vault、目录树、打开文件、监听状态 | Markdown 编辑器内部文档状态 |
| `noteStore` | Note 元数据、当前 Note、最近访问 | 直接读写 SQLite |
| `editorStore` | 模式、活动编辑器、保存状态 | 保存完整历史版本 |
| `searchStore` | 查询条件、模式、结果、分页 | 执行 FTS/Vector 算法 |
| `chatStore` | 会话、消息、SSE、Citation | 拼接厂商请求体 |
| `agentStore` | Run、Event、Tool Call、权限请求 | 执行 Tool |
| `skillStore` | Skill 列表、状态、依赖 | 运行独立 Agent Loop |
| `themeStore` | 当前主题、Manifest、Token 覆盖 | 任意加载本地 CSS |
| `taskStore` | Task 列表、筛选和编辑状态 | 直接修改 Markdown |
| `providerStore` | Provider、Model、Capability | 保存 API Key 明文 |
| `settingsStore` | 应用级非敏感设置 | 保存 Secret |

Store 通过 Service 调用外部能力；组件通过 Store 或 Feature Service 组织交互。

## 16. Service 层要求

建议至少建立：

```text
ApiClient
SseClient
WorkspaceService
EditorDocumentService
NoteService
SearchService
ChatService
AgentService
SkillService
PluginService
ProviderService
TaskService
IndexService
SecretService
```

### 16.1 ApiClient

- Base URL 和 Session Token 由 Rust Sidecar Manager 提供；
- 统一添加认证 Header、Request ID 和 JSON Header；
- 统一解析 `ErrorResponse`；
- 不在业务组件中重复拼接 URL；
- 支持开发环境固定端口和正式环境随机端口。

### 16.2 SseClient

- 支持 ModelEvent 和 AgentEvent；
- 支持取消订阅；
- 网络断开时展示状态，不重复提交原请求；
- Agent Event 根据 `run_id + sequence` 去重；
- 收到终止事件后主动释放连接；
- 页面卸载时清理连接和 AbortController。

### 16.3 WorkspaceService

- 统一封装 FastAPI Workspace/Note API，并为 Tauri 文件命令保留适配边界；
- 规范化路径；
- 处理文件锁、自动保存和冲突；
- Web 开发模式连接后端配置的单一 Vault，禁止失败后回退 Mock；
- 不把任意本地路径直接暴露给 Plugin UI。

## 17. 公共组件

第一阶段建议优先沉淀：

```text
AppShell
PrimarySidebar
SecondarySidebar
StatusBar
CommandPalette
ServiceStatusBadge
EmptyState
ErrorState
LoadingSkeleton
ConfirmDialog
PermissionDialog
ProviderModelSelect
MarkdownEditorAdapter
CitationChip / CitationList
AgentTraceTimeline
ToolCallCard
StreamingMessage
ExtensionStatusBadge
IndexStatusIndicator
```

Dialog、Popover、Menu、Tabs、Select、Tooltip 和 Command Palette 优先基于 Reka UI / Headless Components 封装。

## 18. Design Token 与可访问性

### 18.1 Token 分类

```text
color.background.*
color.text.*
color.border.*
color.accent.*
color.status.*
font.ui.*
font.editor.*
space.*
radius.*
shadow.*
motion.*
```

- 页面不得散布无法被主题覆盖的颜色值；
- Loading、Success、Warning、Error、Disabled 需要统一 Token；
- 编辑器 Token 与普通 UI Token 分开；
- 默认同时提供浅色和深色基础 Token。

### 18.2 可访问性

- 所有主要功能可通过键盘操作；
- 图标按钮提供可读名称和 Tooltip；
- 焦点状态清晰可见；
- 不能只通过颜色表达错误或状态；
- Dialog 打开时管理焦点，关闭后返回触发点；
- Streaming 更新使用合适的 `aria-live`，避免每个 Token 都触发朗读；
- 尊重系统的 reduced motion 设置。

## 19. 错误与降级

| 错误场景 | 页面行为 |
| --- | --- |
| `PROVIDER_AUTH_FAILED` | 引导到 Provider Credential 设置 |
| `PROVIDER_RATE_LIMITED` | 显示稍后重试，不自动无限重试 |
| `PROVIDER_TIMEOUT` | 保留已有 Streaming 内容并允许重试 |
| `PROVIDER_UNAVAILABLE` | 提示切换 Provider 或检查本地服务 |
| `MODEL_NOT_FOUND` | 刷新模型列表并提示重新选择 |
| `MODEL_CAPABILITY_MISMATCH` | 展示缺失 Capability |
| `VALIDATION_ERROR` | 定位到对应表单字段 |
| `PERMISSION_DENIED` | 在 Trace 中记录拒绝，不显示为程序崩溃 |
| `TOOL_TIMEOUT` | 标记对应 Tool Call 失败 |
| `PLUGIN_UNAVAILABLE` | 隐藏失效 Contribution，并显示 Plugin 状态 |
| AI Core 不可用 | 禁用 AI、Search、Index 等入口，但保留 Workspace/Editor |
| Vector / Reranker 不可用 | 降级到 FTS，不阻断搜索 |

全局通知用于跨页面或需要立即关注的结果；字段错误、页面加载错误和 Tool 错误应在其上下文内展示，避免所有错误都使用 Toast。

## 20. 响应式与桌面窗口

项目以桌面端为主，不以手机页面为第一阶段目标。

- 推荐最小窗口宽度：`960px`；
- 宽窗口显示主导航、Secondary Sidebar、Main Content 和 Right Panel；
- 中等窗口自动收起 Right Panel，通过按钮打开；
- 接近最小宽度时收起主导航文字和 Secondary Sidebar；
- Editor、Chat 和 Trace 的滚动区域独立，不让整个窗口出现多层不可控滚动；
- 面板尺寸调整后保存非敏感布局设置。

## 21. 开发优先级

### P0：第一阶段 Demo 必须完成

1. App Shell、Vault 入口和 Workspace；
2. 文件树与 Milkdown / CodeMirror 编辑；
3. 自动保存和 AI Core 离线降级；
4. Search 与 Citation 定位；
5. AI Chat Streaming；
6. Agent Run、Trace、Tool Call 和 Permission；
7. Skill / Plugin 基础管理；
8. Provider 设置和模型切换；
9. 基础 Design Token、错误和加载状态。

### P1：第一阶段完善项

1. Tasks；
2. Theme Manager；
3. Outline 与 Backlinks；
4. Command Palette；
5. Index 和 AI Core Diagnostics；
6. 简单 Plugin Sidebar Panel / Settings Section。

### P2：后续阶段

1. 复杂 Plugin UI API；
2. 音频转写完整工作台；
3. 主题社区与扩展分发；
4. Sync Client 页面；
5. 多设备版本历史与冲突合并；
6. 高级 Agent Trace 可视化和 Benchmark 页面。

## 22. 第一阶段验收标准

### 22.1 Workspace / Editor

- 可以选择 Vault、浏览目录、创建并打开 Markdown；
- 可以在 Milkdown 和 CodeMirror 间切换且内容不丢失；
- 保存状态清晰，保存失败可恢复；
- AI Core 不可用时仍可编辑和保存。

### 22.2 Search / Citation

- 可以选择检索模式和范围；
- 可以展示 SearchResult；
- 点击 Citation 能打开对应 Note 并定位、高亮 Block；
- Vector 不可用时能降级到 FTS。

### 22.3 Chat / Agent

- Provider 和 Model 可以切换；
- Streaming 文本正常追加并可停止；
- Agent 可以创建、取消并查看状态；
- Tool Call、Tool Result、Usage 和错误可以在 Trace 中查看；
- 高风险 Tool 会等待用户确认；
- 页面刷新后可以重新读取 Run 并恢复 Trace 展示。

### 22.4 Extension / Settings

- Skill 和 Plugin 可以查看状态并执行安装、启用、停用和卸载入口；
- 缺少依赖和权限时不能错误地显示为 Ready；
- Provider 可以新增、编辑、测试、启用和删除；
- API Key 不出现在普通配置、日志和 Pinia 持久化中；
- 主题异常时能恢复默认主题。

### 22.5 总体验收

```text
用户编辑 Markdown
→ 后端建立索引
→ 用户发起知识库问题
→ Agent 调用 RAG Tool
→ 返回回答与 Citation
→ 前端展示 Agent Trace
→ 用户点击 Citation
→ 编辑器定位并高亮原笔记
```

## 23. 协作边界

| 内容 | 主负责人 | 前端配合点 |
| --- | --- | --- |
| 页面、组件、交互、Store、Design Token | 吉海燕 | 前端主实现 |
| API Contract、Agent、Provider、Permission、Trace | 范涵宇 | SSE 与页面联调 |
| Note、Block、Search、Citation、RAG | 杨星萱 | 编辑器定位和搜索展示联调 |

跨模块字段变化时，需要同时更新：

```text
Pydantic Contract
OpenAPI
TypeScript Contract
Service
Store
本需求文档中的接口或状态说明
```

第一阶段优先保证完整工作流和可恢复性。页面视觉细节由 Design Token 与后续视觉稿继续收敛，但不能改变本文档中的数据边界、安全约束和关键交互状态。