Skip to content

user-guide-web.md

Latest commit

 

History

History
234 lines (166 loc) · 9.73 KB

user-guide-web.md

File metadata and controls

234 lines (166 loc) · 9.73 KB
Raw

Jarvis Web UI 用户使用手册

面向最终用户的 Web 界面操作指南。
如果你是运维或开发者，想部署服务、配置后端或调用 API，请参阅根目录的 README.md 和 ARCHITECTURE.md。

项目简介

Jarvis 是一个基于 Rust + React 的 AI 对话助手。后端由 Rust 编写，提供 HTTP / WebSocket 服务；前端为 React 19 + Vite + TypeScript 单页应用，通过 WebSocket 与后端实时通信。

核心功能

  • 多轮对话：支持连续上下文交流，可新建、切换、恢复历史会话（需后端开启持久化）。
  • 实时流式回复：助手回复以流式方式逐字呈现，无需等待整段生成完毕。
  • 工具调用可视化：模型若调用工具（如读取文件、执行命令），前端会展示可折叠的工具卡片，包含参数与执行结果。
  • 交互式审批：涉及写文件、编辑文件、执行命令等敏感操作时，右侧面板会弹出审批卡片，用户可手动批准或拒绝。
  • Markdown 渲染：助手回复支持 Markdown，包括代码块高亮、列表、表格、引用等。
  • 模型与主题切换：可在界面内切换后端模型、明亮/暗色主题、界面语言。
  • 快捷键支持：常用操作可通过键盘快速完成。

前端技术栈

技术 说明
React 19 UI 框架
TypeScript 类型安全
Vite 构建工具，开发端口 5173
Zustand 全局状态管理
Tailwind CSS / 原生 CSS 样式方案
WebSocket 实时双向通信

前端目录结构速查

apps/jarvis-web/
├── src/
│   ├── App.tsx              # 根组件，布局与全局初始化
│   ├── main.tsx             # 入口
│   ├── md_render.tsx        # Markdown 渲染器
│   ├── components/
│   │   ├── Chat/
│   │   │   ├── Composer.tsx      # 底部输入框
│   │   │   └── MessageList.tsx   # 消息列表
│   │   ├── Sidebar/
│   │   │   └── ConvoList.tsx     # 左侧会话列表
│   │   ├── AssistantBubble.tsx   # 助手消息气泡
│   │   ├── ToolBlock.tsx         # 工具调用卡片
│   │   └── MarkdownView.tsx      # Markdown 内容区
│   ├── hooks/
│   │   ├── useWebSocket.ts       # WebSocket 连接与消息处理
│   │   └── useShortcuts.ts       # 全局快捷键
│   ├── services/
│   │   ├── api.ts                # HTTP API 封装
│   │   ├── socket.ts             # 底层 WebSocket 服务
│   │   ├── frames.ts             # 帧协议解析
│   │   └── boot.ts               # 应用初始化
│   └── store/
│       └── appStore.ts           # Zustand 全局状态
└── vite.config.ts           # base: '/' (与 harness-server 同域，无 /ui/ 前缀)

路由（react-router-dom v7）

  • / —— 主聊天界面（ChatLayout：sidebar + 聊天 + 工作区栏 + 审批栏）
  • /settings —— 设置中心（外观 / API / 工作区 / Provider / 关于）

老地址 /ui/* 已不再保留兼容；请直接使用根路径。

使用说明

1. 启动与访问

确保后端服务已启动（默认监听 0.0.0.0:7001），然后在浏览器打开：

http://<服务器地址>:7001/

如果是本地开发：

cd apps/jarvis-web
pnpm install
pnpm dev

开发服务器运行在 http://localhost:5173/。

2. 界面布局

Web UI 采用三栏布局：

  • 左栏 — 会话列表：展示历史对话（需后端配置持久化数据库）。可点击切换会话，或点击 × 删除。
  • 中栏 — 聊天主区：显示用户与助手的消息气泡。助手回复流式输出，工具调用以卡片形式嵌入。
  • 右栏 — 审批与状态面板：当助手请求执行敏感操作时，审批卡片会出现在此处；同时也可能包含模型选择、主题设置等快捷入口。

若后端未开启持久化，左栏会显示灰色提示 (persistence disabled — chat is ephemeral)，此时对话仅在当前页面生命周期内保留。

3. 开始对话

  1. 在底部输入框（Composer）中输入问题或指令。
  2. 按 Enter 发送（Shift + Enter 可换行）。
  3. 等待助手回复。回复会以打字机效果逐字出现。

4. 会话管理

操作 方式
新建会话 点击左栏顶部的 + New 按钮
切换会话 点击左栏中的会话标题
删除会话 鼠标悬停在会话条目上，点击右侧出现的 ×
恢复历史 左栏直接加载已有会话，点击即可继续对话

5. 工具调用与可视化

当助手需要调用工具时，界面会在对应的消息气泡内插入一张 ToolBlock 卡片：

  • 默认折叠，显示工具名称与状态。
  • 点击卡片头可展开，查看完整参数（arguments）与执行结果（output）。
  • 支持多次调用的顺序展示。

常见内置工具示例：

  • fs.read：读取文件内容
  • fs.list：列出目录
  • shell.exec：执行命令（需开启并审批）
  • code.grep：代码搜索

6. 审批面板

如果后端开启了审批模式（JARVIS_APPROVAL_MODE=deny 或未设置），且助手尝试执行敏感操作（如 fs.write、fs.edit、shell.exec），右侧面板会弹出审批卡片：

  • Approve（批准）：允许工具执行，模型将看到执行结果并继续。
  • Deny（拒绝）：阻止工具执行，可填写拒绝原因；模型会收到 tool denied: <reason> 并尝试调整策略。

若工具长时间未审批，对话会处于等待状态。此时发送新消息会被拒绝，需先处理 pending 的审批请求。

7. Markdown 渲染

助手消息支持完整 Markdown：

  • 标题、段落、引用块
  • 有序/无序列表、任务列表
  • 表格
  • 行内代码与代码块（带语法高亮）
  • 链接与图片

8. 模型与设置

根据后端配置，界面可能提供：

  • 模型选择：切换当前使用的 LLM（如 GPT-4o、Claude、Gemini 等）。
  • 主题切换：明亮 / 暗色模式。
  • 语言切换：切换界面显示语言（如中/英文）。

8a. 设置中心（/settings）

点 sidebar 底部的账户头像，下拉菜单底部有 Settings 链接，进入 设置中心。也可以直接打开 http://<host>:7001/settings。

设置中心分五个区段：

区段 内容
Appearance 主题（light / dark）、界面语言（English / 中文）。改动即时生效，写入 localStorage。
API 后端 origin 覆盖。同源部署不需要填；只有 vite preview、file:// 打开 dist、或前后端跨域时才需要。保存后需要刷新页面让 WebSocket 用新 origin 重连。
Workspace 只读展示当前 /v1/workspace 输出：root 路径、git branch / HEAD / dirty 状态。点 Refresh 重新探一次。
Providers 只读展示后端注册的所有 provider 与各自的模型清单（来自 /v1/providers）。要改请编辑 ~/.config/jarvis/config.toml 或跑 jarvis login --provider X。
About 版本号、构建模式、文档外链。

设置中心是独立页面，不是模态弹层 —— 直接走浏览器路由。可以独立 收藏 /settings，cmd-click Settings 链接也能在新 tab 打开。

9. 快捷键

快捷键 作用
Enter 发送消息
Shift + Enter 输入框换行
Ctrl + N 新建会话
Ctrl + / 聚焦到输入框
Esc 取消当前输入或关闭弹窗

快捷键可能因浏览器或操作系统差异略有不同。

故障排查

页面空白或加载失败

  • 确认后端服务已启动且能访问 http://<host>:7001/health。
  • 检查浏览器控制台是否有网络错误（如 404、CORS）。
  • 若通过反向代理访问，确认代理规则把 /、/assets/*、/v1/* 全部转给后端。老的 /ui/* 不再处理，请把代理规则切到根路径。

WebSocket 连接不上

  • 浏览器控制台若出现 mixed-content 警告，说明前端是 HTTPS 但后端是 HTTP。请统一协议，或在前端反向代理终结 TLS。
  • 跨域问题：Jarvis 默认在同源场景下运行。若 UI 单独部署，需通过反向代理统一域名。
  • 断线后 UI 会自动重连（约 1 秒间隔），若持续失败请检查网络或后端状态。

左栏会话列表为空

  • 说明后端未配置持久化。需要运维设置 JARVIS_DB_URL（如 sqlite://./jarvis.db）并重启服务。

工具调用不显示或卡顿

  • 检查浏览器性能面板，确认是否为前端渲染瓶颈。
  • 若对话历史极长，可尝试新建会话，减少单会话消息数量。

输入框无法发送

  • 确认当前没有 pending 的审批请求（右侧面板是否有未处理的 Approve/Deny）。
  • 检查 WebSocket 是否处于连接状态（通常断线时输入框会禁用或提示）。

注意事项

  1. 数据持久化：若后端未配置数据库，刷新页面或关闭浏览器后，当前对话将丢失。
  2. 敏感操作：fs.write、fs.edit、shell.exec 等工具可能修改你的文件系统，请谨慎审批。
  3. Token 消耗：长对话会消耗更多模型上下文。若响应变慢，建议开启后端 Memory 功能或新建会话。
  4. 多标签页：同一浏览器打开多个 / 标签页时，每个标签页独立维护 WebSocket 连接和本地状态，不会自动同步。

如需了解后端部署、API 调用、工具配置或记忆机制，请阅读项目根目录的：

  • README.md —— 快速开始与总体介绍
  • ARCHITECTURE.md —— 系统架构
  • DB.md —— 数据库结构
  • docs/user-guide.md —— 运维与开发者完整配置手册