xianren_studio/docs/FEATURES.md

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

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

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

---

## 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）、上传大小上限。
- **对话**：
  - 自动生成对话标题（默认开）：首次回复后自动生成并覆盖标题。
  - **自动预测用户接下来说的话**（默认开）：见 2.4。
  - **预测条数**（默认 3，范围 1–5）。
- **推荐模型列表**：推荐 JSON 目录（可打开、可上传覆盖）。
- **关于**：版本、平台、数据目录、日志目录（可打开）、引擎是否可用。

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

---

## 11. 改动记录

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

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