xianren_studio/docs/FEATURES.md

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

本文档是当前实现功能的权威记录。每次功能新增、修改或删除，都必须同步更新本文档：

• 修改对应功能章节的描述；
• 在文末「改动记录」中追加一条说明（日期 + 改动内容）。

代码组织与布局见 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。

---

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，本机数据库内配置）。