xianren_studio/docs/FEATURES.md

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

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

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

代码组织与布局见 ARCHITECTURE.md。

最后更新：2026-08-16

---

1. 页面总览

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

选项卡	路由	页面
对话	/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
模型管理	/	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. 模型管理页（/）

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

---

6. 模型广场页（/plaza）

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

---

7. 任务页（/tasks）

7.1 计划任务

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

7.2 下载 / 部署任务

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

---

8. 工具页（/tools）

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

---

9. 服务管理页（/server）

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

---

10. 设置页（/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。

---

11. 改动记录

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

2026-08-17

• 计划任务支持发送邮件：任务设置中可开启邮件并填写收件人，内容支持固定内容与大模型生成两种模式；设置页新增「邮件」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，本机数据库内配置）。