914 lines
27 KiB
Markdown
914 lines
27 KiB
Markdown
# 前端页面需求说明（开发版）
|
||
|
||
> 文档用途：供团队在第一阶段进行页面设计、Vue 开发、前后端联调和验收。
|
||
> 文档性质：开发需求基线，不是最终视觉规范或产品宣传文档。
|
||
> 依据：`第一阶段分工表.md`、`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 与后续视觉稿继续收敛，但不能改变本文档中的数据边界、安全约束和关键交互状态。
|