Files
xianren_studio/docs/FEATURES.md
T

265 lines
24 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 条,带分页控件;展示类型 / 大小 / 字数 / 分块数;支持全文预览、「重切」(按最新分块设置重新切分,适用于修改设置后)与删除。
- **检索**:全文检索基于 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)、认证 TokenBearer)。
- 「测试连接」验证连通性;「列出工具」读取服务端 `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
- 知识库页调整:文档列表与检索结果增加分页控件;目录来源、文档列表区块移到检索上方;目录扫描增加进度条与处理统计(处理/成功/失败/忽略/分块数,事件驱动实时刷新)。
- 修复:知识库「添加目录 → 浏览…」无响应——为 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`,本机数据库内配置)。