xianren_studio/docs/FEATURES.md

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

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

最后更新：2026-08-16

---

## 1. 页面总览

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

| 选项卡 | 路由 | 页面 |
| --- | --- | --- |
| 对话 | `/chat` | `ui/src/pages/ChatPage.tsx` |
| 智能体 | `/agents`、`/agents/:agentId` | `ui/src/pages/AgentsPage.tsx`、`ui/src/pages/AgentChatPage.tsx` |
| 工作流 | `/workflows`、`/workflows/:workflowId` | `ui/src/pages/WorkflowsPage.tsx`、`ui/src/pages/WorkflowCanvasPage.tsx` |
| 知识库 | `/knowledge` | `ui/src/pages/KnowledgeBasePage.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. 智能体页（`/agents`）

### 3.1 智能体列表

- 左侧导航新增「智能体」选项卡，页面分为「预制智能体」与「自定义智能体」两组。
- **预制智能体**：随应用内置 6 个（通用助手、代码专家、写作助手、翻译官、数据分析师、提示词优化师），首次启动自动写入数据库（`settings` 键 `preset_agents_seeded` 标记，之后尊重用户删除）；可通过「恢复预制智能体」一键找回已删除的预制体。
- **自定义智能体**：支持新增 / 编辑 / 删除 / 启用停用。字段：名称、图标（emoji）、描述、系统提示词、默认大模型（可选）、启用开关。
- 删除智能体会同时删除其名下所有会话（消息随外键级联删除）。

### 3.2 智能体会话

- 点击智能体卡片「开始对话」进入 `/agents/:agentId`，该页面复用聊天页完整能力（流式输出、重新生成、版本历史、工具、预测建议等）。
- **会话隔离**：`conversations` 表新增 `agent_id` 字段。普通对话页只显示 `agent_id` 为空的会话，每个智能体只显示属于自己的会话，互不干扰。
- 新建智能体会话时自动写入该智能体的**系统提示词**（人设）与默认大模型；对话时仍可在右侧参数面板切换任意可用大模型（本地 / 在线 API 均可）。
- 系统提示词在 `chat_send` / `regenerate_message` / `edit_message` 三条链路统一注入到消息历史最前（工具说明紧随其后），重新生成与编辑重提同样生效。

---

## 4. 工作流页（`/workflows`）

### 4.1 工作流列表

- 左侧导航新增「工作流」选项卡，页面分为「预制工作流」与「自定义工作流」两组，支持新建 / 删除 / 启用停用 / 恢复预制。
- **预制工作流**：随应用内置 4 个（翻译助手、内容总结、两步润色、写作助手），首次启动自动写入数据库（`settings` 键 `preset_workflows_seeded` 标记，之后尊重用户删除）；「恢复预制工作流」可一键找回。
- 新建工作流会生成「开始 → 大模型 → 输出」的默认画布，随后进入画布编辑器。

### 4.2 画布编辑器（`/workflows/:workflowId`）

- 左侧节点面板可**点击或直接拖入** 4 类节点到画布：
  - **开始**：工作流入口，提供运行输入（提示词中可用 `{{input}}` 引用）；
  - **大模型**：配置提示词模板、节点级大模型（可选）、temperature、max_tokens，提示词可用 `{{input}}` 与 `{{节点id}}` 引用上游节点输出；
  - **文本**：静态文本内容（如风格要求），可被其他节点引用；
  - **输出**：决定最终输出（模板留空时自动取上游输出）。
- **画布交互**：节点可拖动布局；滚轮缩放（25%–250%，以光标为中心）；拖动画布空白处整体平移。
- **连线**：点击节点右侧圆点拖到另一节点左侧圆点建立连线（数据流）；单击连线不再删除，**右键**连线弹出菜单可删除。
- **节点右键菜单**：修改节点名称、说明/备注（显示在节点上）、收藏（节点显示 ★）、复制节点、删除节点。
- 右侧面板只显示**选中节点**的相关选项（未选中时提示点击节点）；运行工作流（输入内容 + 可选大模型）、工作流设置（图标/描述/默认大模型/启用/导入导出）为工作流级设置。
- **导入/导出**：导出为 JSON（含节点/连线/元数据），导入 JSON 覆盖当前画布并自动保存。
- 运行前自动保存画布；后端按拓扑顺序执行，`workflow://node-status` 事件实时推送每个节点 running/done 状态与输出。

### 4.3 执行引擎

- `apps/desktop/src/workflow.rs`：DAG 拓扑排序（Kahn，检测循环/未知节点/自连）、模板变量解析（`{{input}}`、`{{节点id}}`）、逐节点执行与结果收集；不依赖具体模型，通过注入的 `call_model` 闭包调用模型，便于单元测试。
- LLM 节点模型解析顺序：节点配置 → 工作流默认模型 → 运行参数模型 → 第一个本地模型 / 第一个已启用在线模型。
- 已内置 5 个执行引擎单元测试（单节点、链式传参、文本节点组合、循环检测、缺失变量报错）与 1 个真实模型端到端测试（`real_model_translation_workflow_e2e`，用本机已配置的在线模型跑通「翻译」工作流，默认忽略、显式运行）。

---

## 5. 知识库页（`/knowledge`）

- 左侧导航新增「知识库」选项卡，页面分左右两栏：左侧知识库列表，右侧选中库的管理区。
- **知识库管理**：新建 / 编辑 / 删除知识库，字段含名称、描述、**分块大小**（100–10000 字，默认 500）与**块间重叠**（默认 50）；删除知识库会级联删除其文档与分块。
- **文档导入**：支持多文件上传，格式覆盖文本类文件（txt / md / json / csv / 代码 / HTML 等）与 **PDF**（后端提取文本）；导入后按知识库分块设置自动切块并写入全文索引。
- **目录来源（批量导入）**：可为知识库添加多个本地目录，扫描目录批量导入文档：
  - **目录选择**：目录路径支持手动输入，或点击「浏览…」调起系统原生文件夹选择器；
  - **后缀过滤**：可指定只导入的后缀列表（如 `.txt,.md,.pdf`），留空默认全部；
  - **递归子目录**：可开关是否递归扫描所有子目录；
  - **类型过滤**：只收录**可读文本**（提取内容并分块检索）、**图片 / 视频**、**音频**三类文件（图片视频音频以文件名为内容登记，可按文件名检索），检测到其他类型自动忽略；
  - 同一目录重复添加自动更新配置不产生重复来源；按文件路径去重，可一键「重新扫描」增量导入新增文件；删除目录来源会同时删除它导入的文档。
  - **扫描进度**：添加目录 / 重新扫描时显示进度条与处理统计（处理 X / Y 个文件、成功、失败、忽略、分块数），失败文件在结尾汇总提示。
- **文档操作**：文档列表每页 10 条，带分页控件；展示类型 / 大小 / 字数 / 分块数；支持全文预览、「重切」（按最新分块设置重新切分，适用于修改设置后）、单条删除；标题「文档（共 x 个）」右侧提供「清空」按钮，一键清空该知识库全部文档（含分块与检索索引），清空前弹窗警告确认。
- **媒体预览**：图片 / 视频 / 音频文档点击「预览」直接展示实际内容——图片原图显示、视频/音频用原生播放器播放（经 Tauri asset protocol 直接读取本地文件，无需整文件过 IPC）；文件被移动/删除时提示无法加载。
- **检索**：全文检索基于 SQLite FTS5（trigram 分词，对中文友好），按 BM25 相关性排序；支持单库检索（也可全库检索），结果每页 10 条带分页控件，展示来源文档与分块序号，可一键复制分块内容用于对话。
- **页面布局**：知识库主区内自上而下依次为「目录来源」→「文档列表」→「检索」。
- 数据表：`knowledge_bases`、`kb_documents`（含提取后的纯文本）、`kb_chunks`（分块）、`kb_chunks_fts`（FTS5 全文索引，contentless-delete 模式 + 触发器同步）。

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

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

---

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

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

---

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

### 7.1 计划任务

- 页面顶部「计划任务」区块，支持新建 / 编辑 / 删除 / 启用停用 / 立即执行。
- **执行智能体**：每条计划指定一个智能体执行（下拉选择，默认「通用助手」），执行时使用该智能体的人设与默认模型；若指定智能体已被删除，自动回退到「通用助手」。
- **执行内容**：计划名称 + 提示词（每次到点发送给智能体的任务内容）。
- **执行间隔**：以分钟 / 小时 / 天为单位，提供快捷预设（30 分钟 / 1 小时 / 6 小时 / 1 天）与自定义；后端每 30 秒检查一次到点的计划。
- **执行方式**：到点后自动在对应智能体名下创建（或复用空）会话，写入用户消息 → 调用大模型（本地模型未启动时自动拉起引擎，在线 API 直接调用）→ 写入助手回答；结果可在该智能体的聊天页查看。
- **发送邮件**：每条计划可开启「发送邮件」，填写收件人（支持多个，逗号分隔），内容支持两种模式：
  - **固定内容**：邮件主题与正文由用户填写，每次执行原样发送；
  - **大模型生成**：邮件正文使用智能体本次生成的回答（主题可自定义，留空自动取回答第一行）。
  - 发件 SMTP 配置在「设置 → 邮件」统一管理（服务器 / 端口 / 加密方式 / 用户名 / 授权码 / 发件人），支持一键发送测试邮件；未配置 SMTP 时任务标记失败并提示。
- 每条计划展示：执行智能体、下次执行时间、上次执行时间、状态（待执行 / 执行中 / 成功 / 失败）与结果 / 错误摘要。
- 没有可用大模型时该次执行标记失败（提示先部署本地模型或启用在线模型），并按间隔继续安排下次执行。
- 应用重启会清理上次中断的「执行中」状态并标记为失败，避免计划永远卡住。

### 7.2 下载 / 部署任务

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

---

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

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

---

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

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

---

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

- **引擎与路径**：模型目录、llama-server 路径、模型下载源（hf-mirror / huggingface.co / modelscope.cn）、默认后端（auto/cpu/cuda/vulkan）、上传大小上限。
- **启动**：
  - **开机启动**：登录 Windows 后自动启动应用（经 `tauri-plugin-autostart` 写入注册表启动项，可随时开关）。
  - **自动加载模型列表**：维护一个**有序**的本地模型列表（支持添加 / 移除 / 上下调整顺序）；应用启动后按列表顺序**逐个部署加载**，由于同一时间只能运行一个本地模型，全部加载完成后保留列表最后一个模型在运行（加载参数使用默认值 ctx 4096 / GPU 层数 99）。
- **邮件**：SMTP 发件配置（服务器、端口、加密方式：隐式 SSL / STARTTLS / 无加密、用户名、授权码、发件人地址与名称），供计划任务发送结果邮件；可填写测试收件人一键验证配置。
- **对话**：
  - 自动生成对话标题（默认开）：首次回复后自动生成并覆盖标题。
  - **自动预测用户接下来说的话**（默认开）：见 2.4。
  - **预测条数**（默认 3，范围 1–5）。
- **推荐模型列表**：推荐 JSON 目录（可打开、可上传覆盖）。
- **关于**：版本、平台、数据目录、日志目录（可打开）、引擎是否可用。

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

---

## 12. 改动记录

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

### 2026-08-17

- 知识库文档预览支持多媒体：图片/视频/音频点击「预览」直接展示实际内容（asset protocol 直读本地文件，视频音频可播放）。
- 知识库文档列表标题增加「清空」按钮：一键清空当前知识库全部文档（分块与索引级联删除），清空前弹出警告确认。
- 知识库页调整：文档列表与检索结果增加分页控件；目录来源、文档列表区块移到检索上方；目录扫描增加进度条与处理统计（处理/成功/失败/忽略/分块数，事件驱动实时刷新）。
- 修复：知识库「添加目录 → 浏览…」无响应——为 dialog 插件在 capabilities 中补充权限（`dialog:default`），并让选择器异常在前端可见。
- 知识库「添加目录」弹窗支持两种方式选择目录：手动输入路径，或点击「浏览…」调起系统原生文件夹选择器（接入 tauri-plugin-dialog）。
- 知识库新增「目录来源」：支持添加多个本地目录批量导入（后缀过滤默认全部、可开关递归子目录），只收录文本 / 图片视频 / 音频三类文件其余忽略，支持重新扫描增量导入与按来源删除。
- 新增「知识库」选项卡与完整操作界面：知识库管理（新建/编辑/删除）、多格式文档上传（文本类 + PDF）、自动分块与全文检索（FTS5 trigram + BM25）、文档预览 / 重新切分 / 删除、检索结果一键复制。
- 计划任务支持发送邮件：任务设置中可开启邮件并填写收件人，内容支持固定内容与大模型生成两种模式；设置页新增「邮件」SMTP 配置与测试发送。
- 设置页新增「启动」：开机启动开关（写入 Windows 注册表启动项）；「自动加载模型」列表（多个本地模型按顺序在启动时逐个加载，最后一个保持运行）。
- 任务页新增「定时计划」：可指定执行智能体（默认通用助手）、执行内容与间隔（分钟 / 小时 / 天），后台到点自动在智能体会话中执行并记录结果；支持立即执行 / 编辑 / 删除 / 启用停用。
- 工作流画布顶栏微调：名称输入框宽度改为按文本实际宽度计算（中文按 2 倍字符宽折算，可完整显示名称），空间不足时自动收缩，保证右侧「保存 / 运行」按钮不被遮挡。

### 2026-08-16

- 工作流画布顶栏修正：名称输入框改为随内容自适应宽度（不再占大块空白），名称长度限制为英文 ≤150 字符 / 中文 ≤50 字符（混排按中文字符权重折算）；顶栏改为可收缩布局，保证「保存 / 运行」按钮始终靠右可见不被挤出。
- 工作流画布增强：节点支持从左侧面板拖入；画布滚轮缩放（25%–250%）与空白处拖动平移；节点右键菜单（修改名称/说明/收藏/复制/删除）、连线右键删除（单击不再误删）；右侧边栏只显示选中节点的选项并移除“各节点输出”总列表；新增画布导入/导出 JSON；顶栏「返回工作流」单行显示、名称框固定宽度、保存/运行右对齐。
- 新增「工作流」选项卡：画布式节点编辑器（开始/大模型/文本/输出，节点连线传参、拖动布局），内置 4 个预制工作流（翻译助手、内容总结、两步润色、写作助手）并支持自定义与恢复；新增 `workflows` 表与 `run_workflow` 命令，后端 `apps/desktop/src/workflow.rs` 执行引擎支持拓扑排序、模板变量（`{{input}}`/`{{节点id}}`）、循环检测，LLM 节点支持本地/在线大模型（节点 → 工作流 → 运行参数 → 自动回退）；`workflow://node-status` 事件实时推送节点状态；5 个引擎单元测试 + 1 个真实模型端到端测试全部跑通。
- 新增「智能体」选项卡：内置 6 个预制智能体 + 支持自定义智能体（名称/图标/描述/系统提示词/默认模型/启用开关）；每个智能体拥有独立会话区（`conversations.agent_id` 隔离），新建会话自动继承智能体系统提示词与默认模型；系统提示词统一注入 `chat_send` / `regenerate_message` / `edit_message` 链路；删除智能体时级联删除其会话；支持「恢复预制智能体」。
- 工具页新增「技能（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`，本机数据库内配置）。