diff --git a/README.md b/README.md
index 5d8a5c6..a5c8bb5 100644
--- a/README.md
+++ b/README.md
@@ -111,3 +111,4 @@ pnpm build
 - API 默认监听 `127.0.0.1:8000`，前端默认监听 `127.0.0.1:5173`。
 - 跨模块接口发生变化时，需要同步更新前后端类型和 `docs` 中的接口说明。
 - 当前前后端接口清单见 `docs/后端接口契约-开发版.md`，OpenAPI 以 `/openapi.json` 为准。
+- 前端页面、交互、状态管理和第一阶段验收要求见 `docs/前端页面需求说明-开发版.md`。
diff --git a/docs/前端页面需求说明-开发版.md b/docs/前端页面需求说明-开发版.md
new file mode 100644
index 0000000..624ebce
--- /dev/null
+++ b/docs/前端页面需求说明-开发版.md
@@ -0,0 +1,907 @@
+# 前端页面需求说明（开发版）
+
+> 文档用途：供团队在第一阶段进行页面设计、Vue 开发、前后端联调和验收。  
+> 文档性质：开发需求基线，不是最终视觉规范或产品宣传文档。  
+> 依据：`第一阶段分工表.md`、`AI笔记软件技术栈说明-团队版-v2.2.md`、`后端接口契约-开发版.md`。
+
+## 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 基础 | Reka UI / Headless Components |
+| 编辑器 | 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 等。
+
+API Key 输入后立即交给 Rust Stronghold，前端仅保存 `credential_id`。页面回显只能显示“已配置/未配置”，不得回显完整密钥。
+
+接口：
+
+```text
+GET    /api/providers
+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
+```
+
+### 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
+
+- 统一封装 Tauri 文件命令；
+- 规范化路径；
+- 处理文件锁、自动保存和冲突；
+- Web 开发模式提供可替换的 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 与后续视觉稿继续收敛，但不能改变本文档中的数据边界、安全约束和关键交互状态。