# Xianren Studio（仙人工作室）功能记录

> 本文档是**当前实现功能**的权威记录。每次功能新增、修改或删除，都必须同步更新本文档：
> - 修改对应功能章节的描述；
> - 在文末「改动记录」中追加一条说明（日期 + 改动内容）。
>
> 代码组织与布局见 [ARCHITECTURE.md](./ARCHITECTURE.md)。

最后更新：2026-08-16

---

## 1. 页面总览

应用共 7 个选项卡（导航左侧栏）：

| 选项卡 | 路由 | 页面 |
| --- | --- | --- |
| 对话 | `/chat` | `ui/src/pages/ChatPage.tsx` |
| 模型管理 | `/` | `ui/src/pages/ModelsPage.tsx` |
| 模型广场 | `/plaza` | `ui/src/pages/ModelPlazaPage.tsx` |
| 任务 | `/tasks` | `ui/src/pages/TasksPage.tsx` |
| 工具 | `/tools` | `ui/src/pages/ToolsPage.tsx` |
| 服务管理 | `/server` | `ui/src/pages/ServerPage.tsx` |
| 设置 | `/settings` | `ui/src/pages/SettingsPage.tsx` |

---

## 2. 对话页（`/chat`）

### 2.1 会话列表（左侧）

- 多会话管理：新建对话、删除、修改标题、置顶、收藏、导出 JSON、导入 JSON、分享（复制为文本）。
- **空会话复用**：点击「新建对话」时，若已存在一个没有任何消息的空会话（数据库 `messages` 表中无该会话消息），则不新建，直接复用最近的那个空会话；否则才真正创建。该逻辑在后端 `create_conversation` 命令中实现。

### 2.2 右侧参数面板

- **当前大模型**：显示当前选中模型的名称（不带 `.gguf` 后缀），附带「本地 / 在线API」标记。
- **可选大模型服务**（自定义下拉列表）：
  - 只列出**有部署/运行状态**的大模型：本地模型按部署状态展示（运行中=绿点、启动中=灰点、出错=红点）；在线 API 模型需在「模型管理」中**启用**后才会出现（绿点，视为始终可用）。
  - 没有任何可用模型时显示占位文案：`暂无，请进模型管理部署`。
  - 模型名一律不显示 `.gguf` 后缀；在线 API 模型带「API」小标签。
  - 切换选项卡再回来时，**保持上次选择的会话与大模型**，不会自动换模型（模型选择逻辑只在所选模型被删除时才回退）。
- **工具**：联网搜索（Tavily）开关。
- **请求参数**：temperature、top_p、max_tokens 滑块。
- 聊天页**不再提供**「启动引擎 / 停止引擎」按钮，也**不再有部署参数**（ctx_size、GPU 层数），部署统一到「模型管理」页完成。

### 2.3 消息区

- 流式输出、Markdown 渲染、代码高亮、思考过程折叠展示、消息统计（首字延迟 / tokens / tok/s / 总耗时）。
- **每条助手回答下方用浅色小字显示该回答实际使用的大模型名**（数据来自 `messages.model_id`，加载历史会话也能还原）。
- 支持复制、重新生成、版本历史（保存旧版本并可恢复）、编辑用户消息后重新提交。
- 支持粘贴/上传图片与文本文件（本地文本模型会把图片替换为占位说明）。

### 2.4 预测用户接下来说的话（建议标签）

- 大模型回答完成后，自动调用**同一个模型**预测用户接下来最可能输入的几条简短消息，以可点击标签显示在该回答下方。
- 点击标签自动填入输入框并聚焦，等待用户编辑或发送。
- 生成方式：统一要求模型输出 **JSON 字符串数组**（所有模型一致，不区分本地/远程）；解析失败或条数不足时**最多重试 3 次**，保留已解析到的最好结果。
- 每条建议**不超过 30 字**，且过滤两类内容：模型输出的元信息行（“以下是…”“预测…”等）、与 AI 回答原文重叠的片段。
- 可在「设置 → 对话」中关闭该功能（默认开启）或调整条数（默认 3，范围 1–5）。
- 建议事件在 App 全局接收并存入共享状态，切换选项卡后回来仍能看到。

### 2.6 对话工具（技能 / MCP / 联网搜索）

- 右侧面板「工具」区域可按会话勾选：联网搜索（Tavily）、已启用的技能、已启用的 MCP 服务（每个会话独立记忆）。
- 后端向模型注入可用工具说明；模型如需使用工具，在回复中**单独输出一行标记**：
  - 技能：`[[skill:技能名]]`（可带参数 `[[skill:技能名:参数]]`）
  - MCP ：`[[mcp:服务名:工具名:参数]]`
- 流式输出时标记会被过滤不显示；生成完成后系统执行工具并把结果回填给模型继续回答（最多 3 轮工具循环）。
- 工具调用期间输入框上方显示「正在调用工具：…」提示。

### 2.5 会话连续性

- 切换选项卡会卸载聊天页，但页面内维护一份**模块级会话快照**（`ChatPage.tsx` 中的 `chatSession`），保存：当前会话、所选模型、消息列表、输入草稿、请求参数、右侧面板开合、工具勾选、版本数据、附件。
- 切走再回来时自动恢复上述状态；若离开时回答仍在生成中，回到页面会从数据库拉取该回答的最终结果。

---

## 3. 模型管理页（`/`）

- **本地模型**：启动时自动扫描模型目录（可手动重新扫描）；支持导入本地 GGUF 文件；可「部署」（后台加载 llama-server 并显示进度）或「停止」；可打开所在目录、移除。
- **在线 API 模型**（OpenAI 兼容）：添加时填写显示名称、Base URL、API Key（可选）、上游模型 ID。
  - 新增 **启用/停用** 开关（数据库 `models.enabled` 字段）：**只有启用后的在线 API 模型才会出现在聊天页的「可选大模型服务」列表中**；未启用显示为「未启用」。
- 部署状态：loading（加载中）、ready（就绪）、error（出错），在任务页也有对应记录。

---

## 4. 模型广场页（`/plaza`）

- 搜索 Hugging Face / ModelScope 上的 GGUF 模型，支持热门榜（空关键词）。
- 查看仓库的 GGUF 量化版本文件列表，选择版本一键下载（ModelScope 文件自动附带 SHA256 校验）。
- 推荐模型列表：软件内置默认推荐（`apps/desktop/src/default_recommendations.json`），也支持在设置中上传自定义 JSON；空目录时自动写入默认列表。
- 模型详情页可内嵌抓取展示（`fetch_model_page`）。

---

## 5. 任务页（`/tasks`）

- 展示下载任务与部署任务的实时进度、状态（进行中 / 完成 / 失败）。
- 空状态提示：暂无任务时引导去模型广场下载或部署本地模型。

---

## 6. 工具页（`/tools`）

- **联网搜索**：配置 Tavily API Key，支持手动测试搜索；对话中的「联网搜索」开关依赖该配置。
- **技能（Skill）**：
  - 新增/编辑/删除技能：名称、描述（给模型看）、内容（指令/知识，调用时注入给模型）。
  - 启用/停用开关；「测试」按钮可预览技能内容。
- **MCP 服务**：
  - 新增/编辑/删除服务：名称、描述、端点地址（Streamable HTTP）、认证 Token（Bearer）。
  - 「测试连接」验证连通性；「列出工具」读取服务端 `tools/list` 并展示每个工具；
    每个工具可填参数并「调用」测试（走 `tools/call`）。
- 对话中的技能/MCP 工具需在工具页**启用**后，才会出现在对话页右侧面板供按会话勾选。

---

## 7. 服务管理页（`/server`）

- OpenAI 兼容的本地 API 服务：`/v1/models`、`/v1/chat/completions`（SSE 流式）、`/v1/embeddings`。
- 可设置端口与 API Key，仅本机监听；可启动/停止并查看状态。

---

## 8. 设置页（`/settings`）

- **引擎与路径**：模型目录、llama-server 路径、模型下载源（hf-mirror / huggingface.co / modelscope.cn）、默认后端（auto/cpu/cuda/vulkan）、上传大小上限。
- **对话**：
  - 自动生成对话标题（默认开）：首次回复后自动生成并覆盖标题。
  - **自动预测用户接下来说的话**（默认开）：见 2.4。
  - **预测条数**（默认 3，范围 1–5）。
- **推荐模型列表**：推荐 JSON 目录（可打开、可上传覆盖）。
- **关于**：版本、平台、数据目录、日志目录（可打开）、引擎是否可用。

设置键完整列表见 [ARCHITECTURE.md](./ARCHITECTURE.md#82-设置项设置键默认值)。

---

## 9. 改动记录

> 按时间倒序追加；每次改动功能都要在此登记。

### 2026-08-16

- 工具页新增「技能（Skill）」与「MCP 服务」管理；对话工具协议上线：模型用 `[[skill:…]]` / `[[mcp:…]]` 标记调用技能与 MCP 工具，系统执行后回填结果（最多 3 轮）。新增本地 MCP 测试服务器 `scripts/test_mcp_server.py` 与 3 个示例技能。
- 会话列表「更多操作」菜单：鼠标移出按钮/菜单所在区域时自动关闭，避免遮挡其他对话标题的查看与操作。
- 新建对话时复用已有空会话（无消息的会话），避免堆积多个空的「新会话」。
- 聊天页会话快照：切换选项卡后保持上次的会话、大模型、消息、输入草稿等状态；回答生成中途切走再回来会拉取最终结果。
- 预测建议统一为 JSON 输出：所有模型同一套提示词与解析，解析失败/条数不足时最多重试 3 次；每条不超过 30 字，过滤元信息行与回答原文片段；建议事件改为全局接收（跨选项卡不丢）。
- 本地模型不再单独区分提示词策略（与在线 API 模型完全一致）。
- 对话页右侧栏重构：
  - 移除「启动引擎 / 停止引擎」按钮与「部署参数」（ctx_size、ngl）滑块，部署统一到模型管理页；
  - 新增「可选大模型服务」列表：只显示有部署状态的大模型（绿=运行、灰=启动中、红=出错），空列表提示「暂无，请进模型管理部署」；
  - 在线 API 模型需在模型管理启用后才出现在该列表（新增 `models.enabled` 字段与启用/停用开关）；
  - 「当前大模型」与列表中模型名均不显示 `.gguf` 后缀。
- 每条助手回答下方以浅色字体显示所用大模型名（`messages` 表新增 `model_id` 字段，含旧库迁移）。
- 对话页新增「预测用户接下来说的话」功能（设置可开关/调条数），点击预测标签自动填入输入框。
- 配置并启用了 DeepSeek-V4-Flash 在线模型（Base URL `https://api.deepseek.com`，本机数据库内配置）。