docs: 重组文档目录并补充CI/CD细则
This commit is contained in:
@@ -0,0 +1,913 @@
|
||||
# 前端页面需求说明（开发版）
|
||||
|
||||
> 文档用途：供团队在第一阶段进行页面设计、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 与后续视觉稿继续收敛，但不能改变本文档中的数据边界、安全约束和关键交互状态。
|
||||
Reference in New Issue
Block a user