NotesAgentic/docs/前端页面需求说明-开发版.md

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

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

1. 第一阶段目标

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

选择本地 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. 页面信息架构

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

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

第一阶段至少支持：

打开文件
创建笔记
全局搜索
切换编辑模式
打开 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 交互流程

选择 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 笔记状态

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 定位信息。

点击结果执行：

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

7.4 页面状态

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

7.5 接口

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 接口

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：

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；
• 权限命名空间；
• 操作影响；
• 参数摘要；
• 仅本次允许 / 本次会话允许 / 拒绝。

提交接口：

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

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

9.5 Run 状态

queued
running
waiting_permission
completed
failed
cancelled

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

9.6 接口

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 接口

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 列表状态

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 接口

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 接口

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。页面回显只能显示“已配置/未配置”，不得回显完整密钥。

接口：

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 层要求

建议至少建立：

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. 公共组件

第一阶段建议优先沉淀：

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 分类

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 总体验收

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

23. 协作边界

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

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

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

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