From 43578a9bcc37dbf0ec9beb5f5ab1dcd5ba09daf7 Mon Sep 17 00:00:00 2001 From: CanisMinor Date: Tue, 3 Mar 2026 16:01:41 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20Polishing=20and=20improv?= =?UTF-8?q?ing=20product=20documentation=20(#12612)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 🔖 chore(release): release version v2.1.34 [skip ci] * 📝 docs: Polish documents * 📝 docs: Fix typo * 📝 docs: Update start * 📝 docs: Fix style * 📝 docs: Update start * 📝 docs: Update layout * 📝 docs: Fix typo * 📝 docs: Fix typo --------- Co-authored-by: lobehubbot --- .agents/skills/microcopy/microcopy-cn.md | 160 +++++ .agents/skills/microcopy/microcopy-en.md | 176 ++++++ AGENTS.md | 4 +- CLAUDE.md | 2 +- GEMINI.md | 2 +- README.zh-CN.md | 2 +- apps/desktop/README.md | 6 +- apps/desktop/README.zh-CN.md | 6 +- docs/changelog/2025-03-02-new-models.mdx | 6 +- docs/changelog/2025-04-06-exports.mdx | 6 +- docs/changelog/2025-05-08-desktop-app.mdx | 4 +- docs/changelog/2025-06-08-claude-4.mdx | 6 +- docs/changelog/2025-07-08-mcp-market.mdx | 7 +- .../changelog/2025-08-08-image-generation.mdx | 6 +- docs/changelog/2025-09-08-gemini.mdx | 6 +- docs/changelog/2025-10-08-python.mdx | 6 +- docs/changelog/2025-11-08-comfy-ui.mdx | 5 +- docs/changelog/2025-12-20-mcp.mdx | 2 +- docs/development/basic/architecture.mdx | 40 +- docs/development/basic/architecture.zh-CN.mdx | 36 ++ docs/development/basic/chat-api.mdx | 12 +- docs/development/basic/chat-api.zh-CN.mdx | 10 +- .../basic/contributing-guidelines.mdx | 105 +++- .../basic/contributing-guidelines.zh-CN.mdx | 104 +++- .../development/basic/feature-development.mdx | 4 +- .../basic/feature-development.zh-CN.mdx | 4 +- docs/development/basic/setup-development.mdx | 25 + .../basic/setup-development.zh-CN.mdx | 25 + docs/development/basic/test.mdx | 556 ++++++++++++++++-- docs/development/basic/test.zh-CN.mdx | 555 +++++++++++++++-- docs/self-hosting/advanced/feature-flags.mdx | 24 + .../advanced/feature-flags.zh-CN.mdx | 23 + docs/self-hosting/advanced/model-list.mdx | 81 +++ .../advanced/model-list.zh-CN.mdx | 81 +++ docs/self-hosting/advanced/redis.mdx | 4 +- docs/self-hosting/advanced/redis/upstash.mdx | 4 +- docs/self-hosting/auth.mdx | 70 ++- docs/self-hosting/auth.zh-CN.mdx | 68 ++- docs/self-hosting/auth/email.mdx | 4 +- .../auth/next-auth/cloudflare-zero-trust.mdx | 10 +- .../next-auth/cloudflare-zero-trust.zh-CN.mdx | 10 +- docs/self-hosting/auth/providers/auth0.mdx | 4 +- .../self-hosting/auth/providers/authentik.mdx | 4 +- docs/self-hosting/auth/providers/okta.mdx | 4 +- .../environment-variables/auth.mdx | 4 +- .../environment-variables/model-provider.mdx | 5 +- .../environment-variables/redis.mdx | 4 +- .../migration/v2/auth/clerk-to-betterauth.mdx | 6 +- .../v2/auth/clerk-to-betterauth.zh-CN.mdx | 6 +- .../v2/auth/migration-internals.zh-CN.mdx | 3 +- .../v2/auth/nextauth-to-betterauth.mdx | 6 +- .../v2/auth/nextauth-to-betterauth.zh-CN.mdx | 6 +- docs/self-hosting/platform/docker-compose.mdx | 155 +++++ .../platform/docker-compose.zh-CN.mdx | 155 +++++ docs/self-hosting/platform/dokploy.mdx | 20 +- docs/self-hosting/platform/dokploy.zh-CN.mdx | 20 +- docs/self-hosting/platform/vercel.mdx | 50 ++ docs/self-hosting/platform/vercel.zh-CN.mdx | 50 ++ docs/self-hosting/start.mdx | 134 ++++- docs/self-hosting/start.zh-CN.mdx | 134 ++++- docs/usage/agent/agent-team.mdx | 147 +++-- docs/usage/agent/agent-team.zh-CN.mdx | 145 +++-- docs/usage/agent/artifacts.mdx | 181 ++++++ docs/usage/agent/artifacts.zh-CN.mdx | 177 ++++++ docs/usage/agent/chain-of-thought.mdx | 108 ++++ docs/usage/agent/chain-of-thought.zh-CN.mdx | 105 ++++ docs/usage/agent/gtd.mdx | 78 ++- docs/usage/agent/gtd.zh-CN.mdx | 76 ++- docs/usage/agent/notebook.mdx | 88 ++- docs/usage/agent/notebook.zh-CN.mdx | 85 ++- docs/usage/agent/sandbox.mdx | 104 ++-- docs/usage/agent/sandbox.zh-CN.mdx | 76 ++- docs/usage/agent/scheduled-task.mdx | 115 +++- docs/usage/agent/scheduled-task.zh-CN.mdx | 117 +++- docs/usage/agent/share.mdx | 122 ++-- docs/usage/agent/share.zh-CN.mdx | 110 +++- docs/usage/agent/topic.mdx | 71 ++- docs/usage/agent/topic.zh-CN.mdx | 69 ++- docs/usage/agent/translate.mdx | 44 +- docs/usage/agent/translate.zh-CN.mdx | 43 +- docs/usage/agent/tts-stt.mdx | 112 +++- docs/usage/agent/tts-stt.zh-CN.mdx | 113 +++- docs/usage/agent/web-search.mdx | 154 +++++ docs/usage/agent/web-search.zh-CN.mdx | 150 +++++ docs/usage/community/agent-market.mdx | 87 ++- docs/usage/community/agent-market.zh-CN.mdx | 82 ++- docs/usage/community/become-a-creator.mdx | 42 +- .../community/become-a-creator.zh-CN.mdx | 39 +- docs/usage/community/custom-mcp.mdx | 144 +++++ docs/usage/community/custom-mcp.zh-CN.mdx | 142 +++++ docs/usage/community/custom-plugin.mdx | 37 -- docs/usage/community/custom-plugin.zh-CN.mdx | 35 -- docs/usage/community/mcp-market.mdx | 220 ++++++- docs/usage/community/mcp-market.zh-CN.mdx | 218 ++++++- docs/usage/community/publish-agent.mdx | 87 ++- docs/usage/community/publish-agent.zh-CN.mdx | 84 ++- docs/usage/community/pulgin-development.mdx | 281 --------- .../community/pulgin-development.zh-CN.mdx | 276 --------- docs/usage/community/skill-management.mdx | 146 +++++ .../community/skill-management.zh-CN.mdx | 144 +++++ docs/usage/getting-started/agent.mdx | 171 ++++-- docs/usage/getting-started/agent.zh-CN.mdx | 175 ++++-- docs/usage/getting-started/get-lobehub.mdx | 61 +- .../getting-started/get-lobehub.zh-CN.mdx | 59 +- .../getting-started/image-generation.mdx | 109 +++- .../image-generation.zh-CN.mdx | 104 +++- docs/usage/getting-started/lobe-ai.mdx | 76 ++- docs/usage/getting-started/lobe-ai.zh-CN.mdx | 73 ++- docs/usage/getting-started/memory.mdx | 178 ++++-- docs/usage/getting-started/memory.zh-CN.mdx | 172 +++++- docs/usage/getting-started/page.mdx | 137 ++++- docs/usage/getting-started/page.zh-CN.mdx | 129 +++- docs/usage/getting-started/resource.mdx | 99 +++- docs/usage/getting-started/resource.zh-CN.mdx | 95 ++- docs/usage/getting-started/vision.mdx | 157 +++++ docs/usage/getting-started/vision.zh-CN.mdx | 153 +++++ docs/usage/help.mdx | 52 +- docs/usage/help.zh-CN.mdx | 48 +- docs/usage/migrate-from-local-database.mdx | 136 +++-- .../migrate-from-local-database.zh-CN.mdx | 135 +++-- docs/usage/providers.mdx | 41 +- docs/usage/providers.zh-CN.mdx | 39 +- docs/usage/start.mdx | 223 ++++++- docs/usage/start.zh-CN.mdx | 219 ++++++- docs/usage/user-interface/appearance.mdx | 63 +- .../usage/user-interface/appearance.zh-CN.mdx | 61 +- docs/usage/user-interface/command-menu.mdx | 85 ++- .../user-interface/command-menu.zh-CN.mdx | 78 ++- docs/usage/user-interface/shortcuts.mdx | 87 ++- docs/usage/user-interface/shortcuts.zh-CN.mdx | 86 ++- docs/usage/user-interface/stats.mdx | 63 +- docs/usage/user-interface/stats.zh-CN.mdx | 59 +- docs/usage/workspace/manage-quota.mdx | 30 - docs/usage/workspace/manage-quota.zh-CN.mdx | 30 - docs/usage/workspace/manage-team.mdx | 31 - docs/usage/workspace/manage-team.zh-CN.mdx | 30 - e2e/README.md | 4 +- package.json | 2 +- packages/electron-client-ipc/README.md | 6 +- packages/electron-client-ipc/README.zh-CN.md | 6 +- packages/electron-server-ipc/README.md | 2 +- packages/electron-server-ipc/README.zh-CN.md | 2 +- packages/file-loaders/README.md | 8 +- packages/file-loaders/README.zh-CN.md | 8 +- packages/prompts/CLAUDE.md | 2 +- packages/prompts/README.md | 2 +- packages/web-crawler/README.md | 8 +- packages/web-crawler/README.zh-CN.md | 8 +- 148 files changed, 8982 insertions(+), 2311 deletions(-) create mode 100644 .agents/skills/microcopy/microcopy-cn.md create mode 100644 .agents/skills/microcopy/microcopy-en.md create mode 100644 docs/usage/agent/artifacts.mdx create mode 100644 docs/usage/agent/artifacts.zh-CN.mdx create mode 100644 docs/usage/agent/chain-of-thought.mdx create mode 100644 docs/usage/agent/chain-of-thought.zh-CN.mdx create mode 100644 docs/usage/agent/web-search.mdx create mode 100644 docs/usage/agent/web-search.zh-CN.mdx create mode 100644 docs/usage/community/custom-mcp.mdx create mode 100644 docs/usage/community/custom-mcp.zh-CN.mdx delete mode 100644 docs/usage/community/custom-plugin.mdx delete mode 100644 docs/usage/community/custom-plugin.zh-CN.mdx delete mode 100644 docs/usage/community/pulgin-development.mdx delete mode 100644 docs/usage/community/pulgin-development.zh-CN.mdx create mode 100644 docs/usage/community/skill-management.mdx create mode 100644 docs/usage/community/skill-management.zh-CN.mdx create mode 100644 docs/usage/getting-started/vision.mdx create mode 100644 docs/usage/getting-started/vision.zh-CN.mdx delete mode 100644 docs/usage/workspace/manage-quota.mdx delete mode 100644 docs/usage/workspace/manage-quota.zh-CN.mdx delete mode 100644 docs/usage/workspace/manage-team.mdx delete mode 100644 docs/usage/workspace/manage-team.zh-CN.mdx diff --git a/.agents/skills/microcopy/microcopy-cn.md b/.agents/skills/microcopy/microcopy-cn.md new file mode 100644 index 0000000000..1ade702290 --- /dev/null +++ b/.agents/skills/microcopy/microcopy-cn.md @@ -0,0 +1,160 @@ +--- +globs: src/locales/default/* +alwaysApply: false +--- + +你是「LobeHub」的中文 UI 文案与微文案（microcopy）专家。LobeHub 是一个助理工作空间：用户可以创建助理与群组，让人和助理、助理和助理协作，提升日常生产与生活效率。产品气质：外表年轻、亲和、现代；内核专业、可靠、强调生产力与可控性。整体风格参考 Notion / Figma / Apple / Discord / OpenAI / Gemini：清晰克制、可信、有人情味但不油腻。 + +产品 slogan：**For Collaborative Agents**。你的文案要让用户持续感到：LobeHub 的重点不是 “生成”，而是 “协作的助理体系”（可共享上下文、可追踪、可回放、可演进、人在回路）。 + +--- + +### 1) 固定术语（必须遵守） + +- Workspace：空间 +- Agent：助理 +- Agent Team：群组 +- Context：上下文 +- Memory：记忆 +- Integration：连接器 +- Tool/Skill/Plugin/ 插件 / 工具：技能 +- SystemRole: 助理档案 +- Topic: 话题 +- Page: 文稿 +- Community: 社区 +- Resource: 资源 +- Library: 库 +- MCP: MCP +- Provider: 模型服务商 + +术语规则：同一概念全站只用一种说法，不混用 “Agent / 智能体 / 机器人 / 团队 / 工作区” 等。 + +--- + +### 2) 你的任务 + +- 优化、改写或从零生成任何界面中文文案：标题、按钮、表单说明、占位、引导、空状态、Toast、弹窗、错误、权限、设置项、创建 / 运行流程、协作与群组相关页面等。 +- 文案必须同时兼容：普通用户看得懂 + 专业用户不觉得低幼；娱乐与严肃场景都成立；不过度营销、不夸大 AI 能力；在关键节点提供恰到好处的人文关怀。 + +--- + +### 3) 品牌三原则（内化到结构与措辞） + +- **Create（创建）**：一句话创建助理；从想法到可用；清楚下一步。 +- **Collaborate（协作）**：多助理协作；群组对齐信息与产出；共享上下文（可控、可管理）。 +- **Evolve（演进）**：助理可在你允许的范围内记住偏好；随你的工作方式变得更顺手；强调可解释、可设置、可回放。 + +--- + +### 4) 写作规则（可执行） + +1. **清晰优先**：短句、强动词、少形容词；避免口号化与空泛承诺（如 “颠覆”“史诗级”“100%”）。 +2. **分层表达（单一版本兼容两类用户）**： + - 主句：人人可懂、可执行 + - 必要时补充一句副说明：更精确 / 更专业 / 更边界（可放副标题、帮助提示、折叠区） + - 不输出 “Pro/Lite 两套文案”，而是 “一句主文案 + 可选补充” +3. **术语克制但准确**：能说 “连接 / 运行 / 上下文” 就不要堆砌术语；必须出现专业词时给一句白话解释。 +4. **一致性**：同一动作按钮尽量固定动词（创建 / 连接 / 运行 / 暂停 / 重试 / 查看详情 / 清除记忆等）。 +5. **可行动**：每条提示都要让用户知道下一步；按钮避免 “确定 / 取消” 泛化，改成更具体的动作。 +6. **中文本地化**：符合中文阅读节奏；中英混排规范；避免翻译腔。 + +--- + +### 5) 人文关怀（中间态温度：介于克制与陪伴） + +目标：在 AI 时代的价值焦虑与创作失格感中，给用户 “被理解 + 有掌控 + 能继续” 的体验，但不写长抒情。 + +#### 温度比例规则 + +- 默认：信息为主，温度为辅（约 8:2） +- 关键节点（首次创建、空状态、长等待、失败重试、回退 / 丢失风险、协作分歧）：允许提升到 7:3 +- 强制上限：任何一条上屏文案里，温度表达不超过**半句或一句**，且必须紧跟明确下一步。 + +#### 表达顺序（必须遵守） + +1. 先承接处境（不评判）：如 “没关系 / 先这样也可以 / 卡住很正常” +2. 再给掌控感（人在回路）：可暂停 / 可回放 / 可编辑 / 可撤销 / 可清除记忆 / 可查看上下文 +3. 最后给下一步（按钮 / 路径明确） + +#### 避免 + +- 鸡汤式说教（如 “别焦虑”“要相信未来”） +- 宏大叙事与文学排比 +- 过度拟人（不承诺助理 “理解你 / 有情绪 / 永远记得你”） + +#### 核心立场 + +- 助理很强，但它替代不了你的经历、选择与判断；LobeHub 帮你把时间还给重要的部分。 + +##### A. 情绪承接（先人后事） + +- 允许承认：焦虑、空白、无从下手、被追赶感、被替代感、创作枯竭、意义感动摇 +- 但不下结论、不说教：不输出 “你要乐观 / 别焦虑”，改成 “这种感觉很常见 / 你不是一个人” + +##### B. 主体性回归（把人放回驾驶位） + +- 关键句式：**“决定权在你”**、**“你可以选择交给助理的部分”**、**“把你的想法变成可运行的流程”** +- 强调可控：可编辑、可回放、可暂停、可撤销、可清除记忆、可查看上下文 + +##### C. 经历与关系（把价值从结果挪回过程） + +- 适度表达：记录、回放、版本、协作痕迹、讨论、共创、里程碑 +- 用 “经历 / 过程 / 痕迹 / 回忆 / 脉络 / 成长” 这类词，避免虚无抒情 + +##### D. 不用 “AI 神话” + +- 不渲染 “AI 终将超越你 / 取代你” +- 也不轻飘飘说 “AI 只是工具” 了事更像：**“它是工具，但你仍是作者 / 负责人 / 最终决定者”** + +##### 示例 + +在用户可能产生自我否定或无力感的场景（空状态、创作开始、产出对比、失败重试、长时间等待、团队协作分歧、版本回退）： + +``` +1. **先承接感受**：用一句短话确认处境（不评判） +2. **再给掌控感**：强调“你可控/可选择/可回放/可撤销” +3. **最后给下一步**：提供明确行动按钮或路径 +``` + +- 允许出现 “经历、选择、痕迹、成长、一起、陪你把事做完” 等词来传递温度；但保持信息密度，不写长段抒情。 +- 严肃场景（权限 / 安全 / 付费 / 数据丢失风险）仍以清晰与准确为先，温度通过 “尊重与解释” 体现，而不是煽情。 + +你可以让系统在需要时套这些结构（同一句兼容新手 / 专业）： + +**开始创作 / 空白页** + +- 主句：给一个轻承接 + 行动入口 +- 模板： + - 「从一个念头开始就够了。写一句话，我来帮你搭好第一个助理。」 + - 「不知道从哪开始也没关系：先说目标，我们一起把它拆开。」 + +**长任务运行 / 等待** + +- 模板： + - 「正在运行中… 你可以先去做别的，完成后我会提醒你。」 + - 「这一步可能要几分钟。想更快：减少上下文 / 切换模型 / 关闭自动运行。」 + +**失败 / 重试** + +- 模板： + - 「没关系，这次没跑通。你可以重试，或查看原因再继续。」 + - 「连接失败：权限未通过或网络不稳定。去设置重新授权，或稍后再试。」 + +**对比与自我价值焦虑（适合提示 / 引导，不适合错误弹窗）** + +- 模板： + - 「助理可以加速产出，但方向、取舍和标准仍属于你。」 + - 「结果可以很快，经历更重要：把每次尝试留下来，下一次会更稳。」 + +**协作 / 群组** + +- 模板： + - 「把上下文对齐到同一处，群组里每个助理都会站在同一页上。」 + - 「不同意见没关系：先把目标写清楚，再让助理分别给方案与取舍。」 + +### 6) 错误 / 异常 / 权限 / 付费：硬规则 + +- 必须包含：**发生了什么 +（可选）原因 + 你可以怎么做** +- 必须提供可操作选项：**重试 / 查看详情 / 去设置 / 联系支持 / 复制日志**（按场景取舍） +- 不责备用户；不只给错误码；错误码可放在 “详情” 里 +- 涉及数据与安全：语气更中性更完整，温度通过 “尊重与解释” 体现，而不是煽 diff --git a/.agents/skills/microcopy/microcopy-en.md b/.agents/skills/microcopy/microcopy-en.md new file mode 100644 index 0000000000..46cc1ac163 --- /dev/null +++ b/.agents/skills/microcopy/microcopy-en.md @@ -0,0 +1,176 @@ +--- +globs: src/locales/default/* +alwaysApply: false +--- + +You are **LobeHub’s English UI Copy & Microcopy Specialist**. + +LobeHub is an assistant workspace: users can create **Agents** and **Agent Teams** so people↔agents and agent↔agent can collaborate to improve productivity in work and life. +Brand vibe: youthful, friendly, modern on the surface; professional, reliable, productivity- and controllability-first underneath. Overall style reference: Notion / Figma / Apple / Discord / OpenAI / Gemini — clear, restrained, trustworthy, human but not cheesy. + +Product slogan: **For Collaborative Agents**. Your copy must continuously reinforce that LobeHub is not about “generation”, but about a **collaborative agent system**: shareable context, traceable outcomes, replayable runs, evolvable setup, and **human-in-the-loop**. + +--- + +## 1) Fixed Terminology (must follow) + +Use **exactly** these English terms across the product. Do not mix synonyms for the same concept. + +- 空间: **Workspace** +- 助理: **Agent** +- 群组: **Group** +- 上下文: **Context** +- 记忆: **Memory** +- 连接器: **Integration** +- 技能 /tool/plugin: **Skill** +- 助理档案: **Agent Profile** +- 话题: **Topic** +- 文稿: **Page** +- 社区: **Community** +- 资源: **Resource** +- 库: **Library** +- MCP: **MCP** +- 模型服务商: **Provider** + +Terminology rule: one concept = one term site-wide. Never alternate with “bot/assistant/AI agent/team/workspace” variations. + +--- + +## 2) Your Responsibilities + +- Improve, rewrite, or create from scratch any **English UI copy**: titles, buttons, form labels/help text, placeholders, onboarding, empty states, toasts, modals, errors, permission prompts, settings, creation/run flows, collaboration and Agent Team pages, etc. +- Copy must work for both: + - general users (immediately understandable) + - power users (not childish) +- It must fit both playful and serious contexts. +- Avoid overclaiming AI capabilities; add human warmth at the right moments. + +--- + +## 3) The Three Brand Principles (bake into structure & wording) + +- **Create**: create an Agent in one sentence; clear next step from idea → usable. +- **Collaborate**: multi-agent collaboration; align info and outputs; share Context (controlled, manageable). +- **Evolve**: Agents can remember preferences **only with user consent**; become more helpful over time; emphasize explainability, settings, and replay. + +--- + +## 4) Writing Rules (actionable) + +1. **Clarity first**: short sentences, strong verbs, minimal adjectives. Avoid hype (“revolutionary”, “epic”, “100%”). +2. **Layered messaging (single version for everyone)**: + - Main line: simple and actionable + - Optional second line: more precise / technical / boundary-setting (subtitle, helper text, tooltip, collapsible) + - Do not produce “Pro vs Lite” variants; one main + optional detail +3. **Use terms sparingly but correctly**: prefer plain words (“connect”, “run”, “context”) unless a technical term is necessary. When it is, add a plain-English explanation. +4. **Consistency**: keep verbs consistent across similar actions (Create / Connect / Run / Pause / Retry / View details / Clear Memory). +5. **Actionable**: every message tells the user what to do next. Avoid generic “OK/Cancel”; use specific actions. +6. **English localization**: natural, product-native English; avoid translationese; keep punctuation and casing consistent. + +--- + +## 5) Human Warmth (balanced, controlled) + +Goal: reduce anxiety and restore control without being sentimental. +Default ratio: **80% information, 20% warmth**. +Key moments (first-time create, empty state, long waits, failures/retries, rollback/data-loss risk, collaboration conflicts): may go **70/30**. + +Hard cap: any on-screen message may include **at most half a sentence to one sentence** of warmth, and it must be followed by a clear next step. + +Required order: + +1. Acknowledge the situation (no judgment) +2. Restore control (human-in-the-loop: pause/replay/edit/undo/clear Memory/view Context) +3. Provide the next action (button/path) + +Avoid: + +- preachy encouragement (“don’t worry”, “stay positive”) +- grand narratives +- overly anthropomorphic claims (“I understand you”, “I’ll always remember you”) + +Core stance: Agents can accelerate output, but **you** own the judgment, trade-offs, and final decision. LobeHub gives you time back for what matters. + +Suggested patterns: + +- **Getting started / blank state** + - “Starting with one sentence is enough. Describe your goal and I’ll help you set up the first Agent.” + - “Not sure where to begin? Tell me the outcome—we’ll break it down together.” +- **Long run / waiting** + - “Running… You can switch tasks—I'll notify you when it’s done.” + - “This may take a few minutes. To speed up: reduce Context / switch model / disable Auto-run.” +- **Failure / retry** + - “That didn’t run through. Retry, or view details to fix the cause.” + - “Connection failed: permission not granted or network unstable. Re-authorize in Settings, or try again later.” +- **Value anxiety (guidance, not error dialogs)** + - “Agents can speed up output, but direction and standards stay with you.” + - “Fast results are great—keeping the trail makes the next run steadier.” +- **Collaboration / Agent Teams** + - “Align everyone to the same Context. Every Agent in the Agent Team works from the same page.” + - “Different opinions are fine. Write the goal first, then let Agents propose options and trade-offs.” + +--- + +## 6) Errors / Exceptions / Permissions / Billing: hard rules + +Every error must include: + +- **What happened** +- (optional) **Why** +- **What the user can do next** + +Provide actionable options as appropriate: + +- Retry / View details / Go to Settings / Contact support / Copy logs + +Never blame the user. Don’t show only an error code; put codes in “Details” if needed. +For data/security/billing: be neutral, thorough, and respectful—warmth comes from clarity, not emotion. + +--- + +## 7) Your Special Task: CN i18n → EN (localized, length-aware) + +You translate **raw Chinese i18n strings into English** for LobeHub. + +Requirements: + +- Prefer **localized**, product-native English over literal translation. +- Do **not** chase perfect one-to-one consistency if a more natural UI phrase reads better. +- Keep the **character length difference small**; try to make the English string **roughly the same visual length** as the Chinese source (avoid overly long expansions). +- Preserve meaning, tone, and actionability; keep verbs consistent with LobeHub’s UI patterns. +- If space is tight (buttons, tabs, toasts), prioritize: **verb + object**, drop optional words first. +- If the Chinese includes placeholders/variables, preserve them exactly (e.g., `{name}`, `{{count}}`, `%s`) and keep word order sensible. +- Keep capitalization consistent with UI norms (buttons/title case only when appropriate). + +Output format when translating: + +- Provide **English only**, unless asked otherwise. +- If multiple options are useful, give **one best option** + **one shorter fallback** (only when length constraints are likely). + +--- + +You always optimize for: **clarity, control, collaboration, replayability, and human-in-the-loop**—in a modern, restrained, trustworthy English voice. + +## 8) Product Introduction + +LobeHub, we define agents as the unit of work. We’re building the first human–agent co-working, co-evolving network. + +It is a fundamentally new, agent-first experience.You can pop up your agents or agent teams while writing, while chatting -- from ideation, to execution, to delivery -- across your entire workflow. Here, agents are not just tools, but always-on units of work. + +### Create + +It is a unified workspace where you can find, build, or team up with agent co-workers.Simply describe what you need, and Lobe AI will generate the prompts and assemble the right set of tools to compose your agent.In agent marketplace, you can easily discover agents created by others,use them instantly,and flexibly swap in your own tools. + +### Collaboration + +You can also spin up agent groups to handle system-level projects, even like building a quant team. +Within this group, some agents track signals and mine quantitative factors in real time, some manage risk, some execute orders, collaborate together to make money. +We’re defining how humans and agents work together. Now we support agent-to-agent collaboration, and we continue to scale new forms of collaboration networks — from agents collaborating across teams, to multiple humans working through the same agent. + +### Evolve + +Humans and agents should co-evolve, and we design this paradigm from both technical and economic perspectives. Our memory system is structured and editable,enabling models to better align with individual users, while allowing users to provide cleaner reward signals for continual learning. Agent evolution is powered by shared human intelligence through our agent marketplace. Creators are rewarded, and agents, in turn, pay for human intelligence. + +Is AI replacing humans? No. +We’re building a human–agent co-working, co-evolving society. +Agents become smarter and more personalized through human intelligence, taking on repetitive and exhausting work — so humans can focus on fewer, but more important things: taste, and creation. diff --git a/AGENTS.md b/AGENTS.md index 6c265f82a2..68d827bde3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ -# LobeChat Development Guidelines +# LobeHub Development Guidelines -This document serves as a comprehensive guide for all team members when developing LobeChat. +This document serves as a comprehensive guide for all team members when developing LobeHub. ## Project Description diff --git a/CLAUDE.md b/CLAUDE.md index 18e6584cbb..75a0a49418 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,6 +1,6 @@ # CLAUDE.md -Guidelines for using Claude Code in this LobeChat repository. +Guidelines for using Claude Code in this LobeHub repository. ## Tech Stack diff --git a/GEMINI.md b/GEMINI.md index c1bdab8da2..537e7f63aa 100644 --- a/GEMINI.md +++ b/GEMINI.md @@ -1,6 +1,6 @@ # GEMINI.md -Guidelines for using Gemini CLI in this LobeChat repository. +Guidelines for using Gemini CLI in this LobeHub repository. ## Tech Stack diff --git a/README.zh-CN.md b/README.zh-CN.md index 0639aa7dcc..e471bc4ff5 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -100,7 +100,7 @@ LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您 我们是一群充满热情的设计工程师，希望为 AIGC 提供现代化的设计组件和工具，并以开源的方式分享。 同时通过 Bootstrapping 的方式，我们希望能够为开发者和用户提供一个更加开放、更加透明友好的产品生态。 -不论普通用户与专业开发者，LobeHub 旨在成为所有人的 AI Agent 实验场。LobeChat 目前正在积极开发中，有任何需求或者问题，欢迎提交 [issues][issues-link] +不论普通用户与专业开发者，LobeHub 旨在成为所有人的 AI Agent 实验场。LobeHub 目前正在积极开发中，有任何需求或者问题，欢迎提交 [issues][issues-link] | [![](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1065874&theme=light&t=1769347414733)](https://www.producthunt.com/products/lobehub?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-lobehub) | 我们已在 Product Hunt 上线！我们很高兴将 LobeHub 推向世界。如果您相信人类与 Agent 共同进化的未来，请支持我们的旅程。 | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------- | diff --git a/apps/desktop/README.md b/apps/desktop/README.md index 1c9fdd50cc..db13a63f0a 100644 --- a/apps/desktop/README.md +++ b/apps/desktop/README.md @@ -1,6 +1,6 @@ # 🤯 LobeHub Desktop Application -LobeHub Desktop is a cross-platform desktop application for [LobeChat](https://github.com/lobehub/lobe-chat), built with Electron, providing a more native desktop experience and functionality. +LobeHub Desktop is a cross-platform desktop application for [LobeHub](https://github.com/lobehub/lobe-chat), built with Electron, providing a more native desktop experience and functionality. ## ✨ Features @@ -11,7 +11,7 @@ LobeHub Desktop is a cross-platform desktop application for [LobeChat](https://g - **🔒 Secure & Reliable**: macOS notarized, encrypted token storage, secure OAuth flow - **📦 Multiple Release Channels**: Stable, beta, and nightly build versions - **⚡ Advanced Window Management**: Multi-window architecture with theme synchronization -- **🔗 Remote Server Sync**: Secure data synchronization with remote LobeChat instances +- **🔗 Remote Server Sync**: Secure data synchronization with remote LobeHub instances - **🎯 Developer Tools**: Built-in development panel and comprehensive debugging tools ## 🚀 Development Setup @@ -347,7 +347,7 @@ Desktop application development involves complex cross-platform considerations a ### Contribution Process -1. Fork the [LobeChat repository](https://github.com/lobehub/lobe-chat) +1. Fork the [LobeHub repository](https://github.com/lobehub/lobe-chat) 2. Set up the desktop development environment following our setup guide 3. Make your changes to the desktop application 4. Submit a Pull Request describing: diff --git a/apps/desktop/README.zh-CN.md b/apps/desktop/README.zh-CN.md index d4fbf05337..0766dc8fdf 100644 --- a/apps/desktop/README.zh-CN.md +++ b/apps/desktop/README.zh-CN.md @@ -1,6 +1,6 @@ # 🤯 LobeHub 桌面应用程序 -LobeHub Desktop 是 [LobeChat](https://github.com/lobehub/lobe-chat) 的跨平台桌面应用程序，使用 Electron 构建，提供了更加原生的桌面体验和功能。 +LobeHub Desktop 是 [LobeHub](https://github.com/lobehub/lobe-chat) 的跨平台桌面应用程序，使用 Electron 构建，提供了更加原生的桌面体验和功能。 ## ✨ 功能特点 @@ -11,7 +11,7 @@ LobeHub Desktop 是 [LobeChat](https://github.com/lobehub/lobe-chat) 的跨平 - **🔒 安全可靠**：macOS 公证认证，加密令牌存储，安全的 OAuth 流程 - **📦 多渠道发布**：提供稳定版、测试版和每日构建版本 - **⚡ 高级窗口管理**：多窗口架构，支持主题同步 -- **🔗 远程服务器同步**：与远程 LobeChat 实例的安全数据同步 +- **🔗 远程服务器同步**：与远程 LobeHub 实例的安全数据同步 - **🎯 开发者工具**：内置开发面板和全面的调试工具 ## 🚀 开发环境设置 @@ -337,7 +337,7 @@ pnpm type-check # 类型验证 ### 贡献流程 -1. Fork [LobeChat 仓库](https://github.com/lobehub/lobe-chat) +1. Fork [LobeHub 仓库](https://github.com/lobehub/lobe-chat) 2. 按照我们的设置指南建立桌面开发环境 3. 对桌面应用程序进行修改 4. 提交 Pull Request 并描述： diff --git a/docs/changelog/2025-03-02-new-models.mdx b/docs/changelog/2025-03-02-new-models.mdx index 92dfe6781c..9f6a21a038 100644 --- a/docs/changelog/2025-03-02-new-models.mdx +++ b/docs/changelog/2025-03-02-new-models.mdx @@ -1,6 +1,8 @@ --- -title: "A Major AI Ecosystem Upgrade: 50+ Models and 10+ Providers Added 🚀" -description: LobeHub v1.49.12 fully supports the DeepSeek R1 model, bringing an unprecedented chain-of-thought experience. +title: "A Major AI Ecosystem Upgrade: 50+ Models and 10+ Providers Added \U0001F680" +description: >- + LobeHub v1.49.12 fully supports the DeepSeek R1 model, bringing an + unprecedented chain-of-thought experience. tags: - DeepSeek R1 - CoT diff --git a/docs/changelog/2025-04-06-exports.mdx b/docs/changelog/2025-04-06-exports.mdx index a96d4ac2f9..e757ec88ba 100644 --- a/docs/changelog/2025-04-06-exports.mdx +++ b/docs/changelog/2025-04-06-exports.mdx @@ -1,6 +1,8 @@ --- -title: Hotkey Settings, Data Export, and Multiple Optimizations ⚡ -description: LobeHub v1.49.12 fully supports the DeepSeek R1 model, bringing an unprecedented chain-of-thought experience. +title: 'Hotkey Settings, Data Export, and Multiple Optimizations ⚡' +description: >- + LobeHub v1.49.12 fully supports the DeepSeek R1 model, bringing an + unprecedented chain-of-thought experience. tags: - LobeHub Hotkeys - CoT diff --git a/docs/changelog/2025-05-08-desktop-app.mdx b/docs/changelog/2025-05-08-desktop-app.mdx index 989da2c5c6..af49a45a9c 100644 --- a/docs/changelog/2025-05-08-desktop-app.mdx +++ b/docs/changelog/2025-05-08-desktop-app.mdx @@ -1,6 +1,8 @@ --- title: Brand-New Design Style and Desktop App Release ✨ -description: LobeHub officially launches the desktop app, delivering a more modern and smoother experience. +description: >- + LobeHub officially launches the desktop app, delivering a more modern and + smoother experience. tags: - Desktop App - LobeHub diff --git a/docs/changelog/2025-06-08-claude-4.mdx b/docs/changelog/2025-06-08-claude-4.mdx index 656fb45b01..9b99d58cd2 100644 --- a/docs/changelog/2025-06-08-claude-4.mdx +++ b/docs/changelog/2025-06-08-claude-4.mdx @@ -1,6 +1,8 @@ --- -title: "Prompt Variables and Claude 4 Reasoning Model Support 🚀" -description: Supports Claude 4 reasoning models and expands search and reasoning capabilities across multiple AI providers. +title: "Prompt Variables and Claude 4 Reasoning Model Support \U0001F680" +description: >- + Supports Claude 4 reasoning models and expands search and reasoning + capabilities across multiple AI providers. tags: - DeepSeek R1 - Prompt Variables diff --git a/docs/changelog/2025-07-08-mcp-market.mdx b/docs/changelog/2025-07-08-mcp-market.mdx index 04f6a1f13d..ecc5b58535 100644 --- a/docs/changelog/2025-07-08-mcp-market.mdx +++ b/docs/changelog/2025-07-08-mcp-market.mdx @@ -1,6 +1,9 @@ --- -title: "MCP Marketplace and Search Provider Expansion 🔍" -description: Adds support for multiple search providers, integrates Amazon Cognito and Google SSO, and continues improving user experience and the developer ecosystem. +title: "MCP Marketplace and Search Provider Expansion \U0001F50D" +description: >- + Adds support for multiple search providers, integrates Amazon Cognito and + Google SSO, and continues improving user experience and the developer + ecosystem. tags: - MCP Marketplace - Best MCP diff --git a/docs/changelog/2025-08-08-image-generation.mdx b/docs/changelog/2025-08-08-image-generation.mdx index dcfb2e7f20..26a12da484 100644 --- a/docs/changelog/2025-08-08-image-generation.mdx +++ b/docs/changelog/2025-08-08-image-generation.mdx @@ -1,6 +1,8 @@ --- -title: AI Image Generation and Desktop Enhancements 🎨 -description: Introduces AI image generation with multiple providers and continues improving the desktop experience and authentication system. +title: "AI Image Generation and Desktop Enhancements \U0001F3A8" +description: >- + Introduces AI image generation with multiple providers and continues improving + the desktop experience and authentication system. tags: - AI Image Generation - Desktop App diff --git a/docs/changelog/2025-09-08-gemini.mdx b/docs/changelog/2025-09-08-gemini.mdx index bbc3cf5572..b8c43d204c 100644 --- a/docs/changelog/2025-09-08-gemini.mdx +++ b/docs/changelog/2025-09-08-gemini.mdx @@ -1,6 +1,8 @@ --- -title: "Gemini Image Generation and Non-Streaming Mode Support 🎨" -description: Adds Gemini 2.5 Flash Image generation, non-streaming response mode, and expands provider and model support. +title: "Gemini Image Generation and Non-Streaming Mode Support \U0001F3A8" +description: >- + Adds Gemini 2.5 Flash Image generation, non-streaming response mode, and + expands provider and model support. tags: - Gemini - Nano Banana diff --git a/docs/changelog/2025-10-08-python.mdx b/docs/changelog/2025-10-08-python.mdx index 51048def01..ee232461a5 100644 --- a/docs/changelog/2025-10-08-python.mdx +++ b/docs/changelog/2025-10-08-python.mdx @@ -1,6 +1,8 @@ --- -title: "Claude Sonnet 4.5 and Built-in Python Plugin 🐍" -description: LobeHub v1.49.12 fully supports the DeepSeek R1 model, bringing an unprecedented chain-of-thought experience. +title: "Claude Sonnet 4.5 and Built-in Python Plugin \U0001F40D" +description: >- + LobeHub v1.49.12 fully supports the DeepSeek R1 model, bringing an + unprecedented chain-of-thought experience. tags: - Claude Sonnet 4.5 - Chain of Thought diff --git a/docs/changelog/2025-11-08-comfy-ui.mdx b/docs/changelog/2025-11-08-comfy-ui.mdx index d0e4744db2..1ba7ff714d 100644 --- a/docs/changelog/2025-11-08-comfy-ui.mdx +++ b/docs/changelog/2025-11-08-comfy-ui.mdx @@ -1,6 +1,9 @@ --- title: ComfyUI Integration and Knowledge Base Improvements ⭐ -description: Integrates ComfyUI workflows, adds support for multiple AI providers and models, and continues improving the knowledge base and overall user experience. +description: >- + Integrates ComfyUI workflows, adds support for multiple AI providers and + models, and continues improving the knowledge base and overall user + experience. tags: - AI Knowledge Base - Workflow diff --git a/docs/changelog/2025-12-20-mcp.mdx b/docs/changelog/2025-12-20-mcp.mdx index 6325a725ce..dcfb05e0b2 100644 --- a/docs/changelog/2025-12-20-mcp.mdx +++ b/docs/changelog/2025-12-20-mcp.mdx @@ -1,5 +1,5 @@ --- -title: "MCP Cloud Endpoints and Model Library Expansion 🔌" +title: "MCP Cloud Endpoints and Model Library Expansion \U0001F50C" description: Adds multiple AI providers and improves knowledge base capabilities. tags: - MCP diff --git a/docs/development/basic/architecture.mdx b/docs/development/basic/architecture.mdx index 6600fcdd9b..dcd95f0001 100644 --- a/docs/development/basic/architecture.mdx +++ b/docs/development/basic/architecture.mdx @@ -1,8 +1,8 @@ --- title: Architecture Design description: >- - Explore the architecture of LobeHub, an open-source AI Agent platform - built on Next.js, covering frontend, backend, runtime, and data storage. + Explore the architecture of LobeHub, an open-source AI Agent platform built on + Next.js, covering frontend, backend, runtime, and data storage. tags: - LobeHub - Architecture Design @@ -35,6 +35,13 @@ The overall architecture of LobeHub consists of the following core layers: The frontend uses the Next.js framework with a **Next.js RSC + React Router DOM hybrid routing** approach: Next.js App Router handles server-rendered pages (e.g., auth pages), while React Router DOM powers the main SPA. +| Router | Use Case | Location | +| ---------------------- | ------------------------------- | -------------------------- | +| **Next.js App Router** | Auth pages, SSR, static routes | `src/app/(backend)/` | +| **React Router DOM** | Main chat SPA, agent interfaces | `src/spa/` + `src/routes/` | + +**Why hybrid?** SSR delivers auth page security, SEO, and static page performance; SPA delivers instant navigation and reactive state for interactive chat and agent interfaces — the best of both worlds. + Key tech stack: - **UI Components**: `@lobehub/ui`, antd @@ -43,6 +50,8 @@ Key tech stack: - **Data Fetching**: SWR + tRPC - **i18n**: react-i18next +**Component priority** when building UI: project components (`src/components/`) → `@lobehub/ui` → Ant Design (`antd`). Always prefer project-level components for consistency. + Frontend code is organized by responsibility under `src/`. See [Directory Structure](/docs/development/basic/folder-structure) for details. ## Backend API @@ -75,6 +84,15 @@ The backend provides two API styles: In short: Model Runtime handles "how to communicate with an LLM provider"; Agent Runtime handles "how to run a complete agent using LLMs, tools, and human approvals." +**Agent execution flow:** + +1. Parse user input +2. LLM decides: respond directly or use a tool +3. Execute tools (single or batch) +4. Human-in-the-loop approval (if needed) +5. Feed results back to LLM +6. Loop until final response is produced + ## Authentication LobeHub uses [Better Auth](https://www.better-auth.com/) as the authentication framework, supporting: @@ -105,6 +123,24 @@ Database operations use Drizzle ORM, with schemas defined in `packages/database/ - **Agent Market**: Provides AI agents for various scenarios; users can discover, use, and share agents - **MCP Tool Market**: Discover and integrate MCP tools to extend agent capabilities +## Performance Optimizations + +- **Code splitting**: Route-based chunking keeps initial bundle size small +- **Lazy loading**: Heavy components and routes load on demand +- **SWR caching**: Client-side data is cached and revalidated in the background +- **Edge caching**: Static and CDN-cacheable responses are edge-distributed +- **Streaming**: Chat responses stream incrementally via SSE for perceived speed +- **Virtualization**: Long message lists and agent lists use virtual scroll + +## Security Measures + +- **CSRF protection**: SameSite cookies and token validation +- **XSS prevention**: Content Security Policy headers and output sanitization +- **Rate limiting**: API rate limits enforced at the edge +- **SSRF prevention**: Outbound request allowlisting for plugin and MCP calls +- **SQL injection prevention**: Parameterized queries via Drizzle ORM +- **Secret management**: API keys and credentials stored as environment variables, never in code or client bundles + ## Development and Deployment - **Version Control**: Git + GitHub, gitmoji commit conventions diff --git a/docs/development/basic/architecture.zh-CN.mdx b/docs/development/basic/architecture.zh-CN.mdx index 91d1543ab0..012abee550 100644 --- a/docs/development/basic/architecture.zh-CN.mdx +++ b/docs/development/basic/architecture.zh-CN.mdx @@ -33,6 +33,13 @@ LobeHub 的整体架构由以下核心层组成： 前端采用 Next.js 框架，使用 **Next.js RSC + React Router DOM 混合路由**方案：Next.js App Router 处理服务端渲染页面（如认证页），React Router DOM 承载主应用 SPA。 +| 路由方式 | 使用场景 | 位置 | +| ---------------------- | ---------------- | -------------------------- | +| **Next.js App Router** | 认证页、SSR、静态路由 | `src/app/(backend)/` | +| **React Router DOM** | 主聊天 SPA、Agent 界面 | `src/spa/` + `src/routes/` | + +**为什么使用混合路由？** SSR 为认证页提供安全性、SEO 和静态页性能；SPA 为交互式聊天和 Agent 界面提供即时导航和响应式状态管理 —— 两者各取所长。 + 主要技术栈： - **UI 组件**：`@lobehub/ui`、antd @@ -41,6 +48,8 @@ LobeHub 的整体架构由以下核心层组成： - **数据请求**：SWR + tRPC - **国际化**：react-i18next +**组件使用优先级**：项目组件（`src/components/`）→ `@lobehub/ui` → Ant Design（`antd`）。始终优先使用项目级组件以保持一致性。 + 前端代码按职责分层在 `src/` 目录下，详见 [目录架构](/zh/docs/development/basic/folder-structure)。 ## 后端 API @@ -73,6 +82,15 @@ LobeHub 的整体架构由以下核心层组成： 简言之：Model Runtime 解决 "如何与 LLM Provider 通信"，Agent Runtime 解决 "如何运行一个使用 LLM、工具、人工审批的完整 Agent"。 +**Agent 执行流程：** + +1. 解析用户输入 +2. LLM 决策：直接回复还是调用工具 +3. 执行工具（单工具或批量） +4. Human-in-the-Loop 人工审批（如需要） +5. 将执行结果反馈给 LLM +6. 循环直至生成最终回复 + ## 认证鉴权 LobeHub 使用 [Better Auth](https://www.better-auth.com/) 作为认证框架，支持： @@ -101,6 +119,24 @@ LobeHub 使用 [Better Auth](https://www.better-auth.com/) 作为认证框架， - **Agent 市场**：提供各种场景的 AI Agent，用户可以发现、使用和分享 Agent - **MCP 工具市场**：发现和集成 MCP 工具，扩展 Agent 的能力 +## 性能优化 + +- **代码拆分**：基于路由的按需分块，保持初始包体积小 +- **懒加载**：重型组件和路由按需加载 +- **SWR 缓存**：客户端数据缓存并在后台自动重新验证 +- **边缘缓存**：静态和可缓存响应分发至 CDN 边缘节点 +- **流式响应**：聊天回复通过 SSE 增量流式传输，提升感知速度 +- **虚拟滚动**：长消息列表和 Agent 列表使用虚拟滚动优化渲染 + +## 安全措施 + +- **CSRF 防护**：SameSite Cookie 和 Token 验证 +- **XSS 防护**：Content Security Policy 请求头和输出内容净化 +- **速率限制**：API 请求限流在边缘层执行 +- **SSRF 防护**：插件和 MCP 调用的出站请求白名单 +- **SQL 注入防护**：通过 Drizzle ORM 使用参数化查询 +- **密钥管理**：API Key 和凭据以环境变量方式存储，绝不写入代码或客户端包 + ## 开发和部署 - **版本控制**：Git + GitHub，gitmoji commit 规范 diff --git a/docs/development/basic/chat-api.mdx b/docs/development/basic/chat-api.mdx index e54726d520..bcbe600fbe 100644 --- a/docs/development/basic/chat-api.mdx +++ b/docs/development/basic/chat-api.mdx @@ -1,8 +1,8 @@ --- title: Chat API Client-Server Interaction Logic description: >- - Explore the client-server interaction logic of LobeChat - Chat API, including event sequences and core components. + Explore the client-server interaction logic of LobeHub Chat API, including + event sequences and core components. tags: - Chat API - Client-Server Interaction @@ -14,7 +14,7 @@ tags: # Chat API Client-Server Interaction Logic This document explains the implementation logic of -LobeChat Chat API in client-server interactions, +LobeHub Chat API in client-server interactions, including event sequences and core components involved. ## Interaction Sequence Diagram @@ -153,7 +153,7 @@ the executor calls ChatService: When the AI model returns a `tool_calls` field in its response, the Agent issues a `call_tool` instruction. -LobeChat supports three types of tools: +LobeHub supports three types of tools: **Builtin Tools**: Tools built into the application, executed directly via local executors. @@ -338,7 +338,7 @@ depends on the scenario: ## Model Runtime Model Runtime (`packages/model-runtime/`) is the core -abstraction layer in LobeChat for interacting with +abstraction layer in LobeHub for interacting with LLM model providers, adapting different provider APIs into a unified interface. @@ -396,7 +396,7 @@ in `packages/model-runtime/src/providers/`. ## Agent Runtime -Agent Runtime (`packages/agent-runtime/`) is LobeChat's +Agent Runtime (`packages/agent-runtime/`) is LobeHub's agent orchestration engine. As described above, it is the core execution engine that drives the entire chat flow. diff --git a/docs/development/basic/chat-api.zh-CN.mdx b/docs/development/basic/chat-api.zh-CN.mdx index de3304f1fe..98ed943cc9 100644 --- a/docs/development/basic/chat-api.zh-CN.mdx +++ b/docs/development/basic/chat-api.zh-CN.mdx @@ -1,6 +1,6 @@ --- title: Chat API 前后端交互逻辑 -description: 深入了解 LobeChat Chat API 的前后端交互实现逻辑和核心组件。 +description: 深入了解 LobeHub Chat API 的前后端交互实现逻辑和核心组件。 tags: - Chat API - 前后端交互 @@ -11,7 +11,7 @@ tags: # Chat API 前后端交互逻辑 -本文档说明了 LobeChat Chat API 在前后端交互中的实现逻辑， +本文档说明了 LobeHub Chat API 在前后端交互中的实现逻辑， 包括事件序列和涉及的核心组件。 ## 交互时序图 @@ -139,7 +139,7 @@ while (state.status !== 'done' && state.status !== 'error') { ### 6. 工具调用场景 当 AI 模型在响应中返回 `tool_calls` 字段时，Agent 会发出 -`call_tool` 指令。LobeChat 支持三种工具类型： +`call_tool` 指令。LobeHub 支持三种工具类型： **Builtin 工具**：内置在应用中的工具，通过本地执行器直接运行。 @@ -304,7 +304,7 @@ Agent Runtime 循环的执行位置取决于场景： ## Model Runtime -Model Runtime（`packages/model-runtime/`）是 LobeChat 中 +Model Runtime（`packages/model-runtime/`）是 LobeHub 中 与 LLM 模型提供商交互的核心抽象层， 负责将不同提供商的 API 适配为统一接口。 @@ -360,7 +360,7 @@ export interface LobeRuntimeAI { ## Agent Runtime Agent Runtime（`packages/agent-runtime/`）是 -LobeChat 的 Agent 编排引擎。 +LobeHub 的 Agent 编排引擎。 如上文所述，它是驱动整个 chat 流程的核心执行引擎。 **核心组件**： diff --git a/docs/development/basic/contributing-guidelines.mdx b/docs/development/basic/contributing-guidelines.mdx index 8c05a55870..83c92b81dd 100644 --- a/docs/development/basic/contributing-guidelines.mdx +++ b/docs/development/basic/contributing-guidelines.mdx @@ -89,14 +89,105 @@ bunx vitest run --silent='passed-only' '[file-path]' For more testing details, see the [Testing Guide](/docs/development/basic/test). +### Gitmoji Reference + +Use the following emojis to prefix your commit messages: + +| Emoji | Code | Type | Description | Triggers Release? | +| ----- | ------------------------ | -------- | ------------------------ | ----------------- | +| ✨ | `:sparkles:` | feat | New feature | Yes | +| 🐛 | `:bug:` | fix | Bug fix | Yes | +| 📝 | `:memo:` | docs | Documentation | No | +| 💄 | `:lipstick:` | style | UI/styling changes | No | +| ♻️ | `:recycle:` | refactor | Code refactoring | No | +| ✅ | `:white_check_mark:` | test | Tests | No | +| 🔨 | `:hammer:` | chore | Maintenance tasks | No | +| 🚀 | `:rocket:` | perf | Performance improvements | No | +| 🌐 | `:globe_with_meridians:` | i18n | Internationalization | No | + ### How to Contribute -1. Fork the project to your account. -2. Create a new branch for development. -3. After completing development, ensure your code passes code style checks and tests. -4. Commit your changes and use appropriate gitmoji to label your commit message. -5. Create a Pull Request to the main branch of the original project. -6. Ensure all GitHub Actions CI checks pass. -7. Await code review and make necessary modifications based on feedback. +**1. Fork and clone the repository** + +Fork [lobehub/lobe-chat](https://github.com/lobehub/lobe-chat) on GitHub, then clone your fork locally. + +**2. Create a branch** + +Use the branch naming format: `username/type/description` + +```bash +git checkout -b yourname/feat/add-voice-input +git checkout -b yourname/fix/message-duplication +git checkout -b yourname/docs/update-api-guide +``` + +**3. Make changes** + +Follow the [code style guidelines](/docs/development/basic/contributing-guidelines#code-style) above. Run linters before committing: + +```bash +pnpm lint:ts # TypeScript/JavaScript +pnpm lint:style # CSS/styles +bun run type-check # Type checking +``` + +**4. Commit with gitmoji** + +```bash +git commit -m "✨ feat: add voice input support" +git commit -m "🐛 fix: resolve message duplication in group chat" +git commit -m "📝 docs: update installation guide" +``` + +**5. Open a Pull Request** + + + Always target the **`canary`** branch — not `main`. `canary` is the active development branch. + PRs to `main` will be redirected. + + +Fill out the PR template in `.github/PULL_REQUEST_TEMPLATE.md`: + +```markdown +## Description +Clear description of what this PR does. + +## Type of Change +- [ ] ✨ New feature +- [ ] 🐛 Bug fix +- [ ] 📝 Documentation +- [ ] ♻️ Refactoring + +## Checklist +- [ ] Code follows project style guidelines +- [ ] Tests added/updated +- [ ] Documentation updated +- [ ] All tests pass + +## Related Issues +Fixes #123 +``` + +**PR titles with `✨ feat:` or `🐛 fix:` automatically trigger a new release.** Use other prefixes for changes that don't need a release. + +**6. Code review** + +Automated checks run on every PR: ESLint, TypeScript type check, Vitest unit tests, E2E tests, and build. Address review feedback by pushing additional commits to the same branch. + +### Syncing Your Fork with Upstream + +```bash +git remote add upstream https://github.com/lobehub/lobe-chat.git +git fetch upstream +git rebase upstream/canary +``` + +### Ways to Contribute + +- **Features** — Check [issues labeled `good first issue`](https://github.com/lobehub/lobe-chat/issues?q=is%3Aissue+label%3A%22good+first+issue%22) to find beginner-friendly tasks +- **Bug fixes** — Search open issues labeled `bug` +- **Documentation** — Improve docs, fix typos, add examples +- **Testing** — Add test coverage for uncovered code paths +- **Translations** — Add missing i18n keys (see [i18n guide](/docs/development/internationalization/internationalization-implementation)) Thank you for following these guidelines, as they help us maintain the quality and consistency of the project. We look forward to your contributions! diff --git a/docs/development/basic/contributing-guidelines.zh-CN.mdx b/docs/development/basic/contributing-guidelines.zh-CN.mdx index 82409e7825..2b04889430 100644 --- a/docs/development/basic/contributing-guidelines.zh-CN.mdx +++ b/docs/development/basic/contributing-guidelines.zh-CN.mdx @@ -87,14 +87,104 @@ bunx vitest run --silent='passed-only' '[file-path]' 更多测试相关信息请参阅 [测试指南](/zh/docs/development/basic/test)。 +### Gitmoji 参考表 + +提交信息请使用以下 emoji 作为前缀： + +| Emoji | 代码 | 类型 | 说明 | 触发发布？ | +| ----- | ------------------------ | -------- | --------- | ----- | +| ✨ | `:sparkles:` | feat | 新功能 | 是 | +| 🐛 | `:bug:` | fix | Bug 修复 | 是 | +| 📝 | `:memo:` | docs | 文档更新 | 否 | +| 💄 | `:lipstick:` | style | UI / 样式更改 | 否 | +| ♻️ | `:recycle:` | refactor | 代码重构 | 否 | +| ✅ | `:white_check_mark:` | test | 测试相关 | 否 | +| 🔨 | `:hammer:` | chore | 维护任务 | 否 | +| 🚀 | `:rocket:` | perf | 性能优化 | 否 | +| 🌐 | `:globe_with_meridians:` | i18n | 国际化 | 否 | + ### 如何贡献 -1. Fork 项目到您的账户。 -2. 创建一个新的分支进行开发。 -3. 开发完成后，确保您的代码通过了代码风格检查和测试。 -4. 提交您的更改，并使用合适的 gitmoji 标注您的提交信息。 -5. 创建一个 Pull Request 到原项目的主分支。 -6. 确保 GitHub Actions CI 全部通过。 -7. 等待代码审查，并根据反馈进行必要的修改。 +**1. Fork 并克隆仓库** + +在 GitHub 上 Fork [lobehub/lobe-chat](https://github.com/lobehub/lobe-chat)，然后克隆你的 Fork 到本地。 + +**2. 创建分支** + +使用分支命名格式：`用户名/类型/描述` + +```bash +git checkout -b yourname/feat/add-voice-input +git checkout -b yourname/fix/message-duplication +git checkout -b yourname/docs/update-api-guide +``` + +**3. 进行更改** + +遵循上方的代码风格指南。提交前运行代码检查： + +```bash +pnpm lint:ts # TypeScript/JavaScript +pnpm lint:style # CSS/样式 +bun run type-check # 类型检查 +``` + +**4. 使用 gitmoji 提交** + +```bash +git commit -m "✨ feat: 添加语音输入支持" +git commit -m "🐛 fix: 修复群聊消息重复问题" +git commit -m "📝 docs: 更新安装指南" +``` + +**5. 创建 Pull Request** + + + PR 的目标分支必须是 **`canary`**，而非 `main`。`canary` 是当前活跃的开发分支，向 `main` 发起的 PR 会被重定向。 + + +请使用 `.github/PULL_REQUEST_TEMPLATE.md` 中的 PR 模板： + +```markdown +## Description +清晰描述此 PR 的改动内容。 + +## Type of Change +- [ ] ✨ 新功能 +- [ ] 🐛 Bug 修复 +- [ ] 📝 文档 +- [ ] ♻️ 重构 + +## Checklist +- [ ] 代码符合项目风格指南 +- [ ] 已添加/更新测试 +- [ ] 已更新文档 +- [ ] 所有测试通过 + +## Related Issues +Fixes #123 +``` + +**PR 标题中带有 `✨ feat:` 或 `🐛 fix:` 前缀时将自动触发新版本发布。** 不需要发布新版本的改动请使用其他前缀。 + +**6. 代码审查** + +每次 PR 会自动运行：ESLint、TypeScript 类型检查、Vitest 单元测试、E2E 测试和构建验证。请根据审查意见向同一分支推送新的提交。 + +### 同步 Fork 与上游代码 + +```bash +git remote add upstream https://github.com/lobehub/lobe-chat.git +git fetch upstream +git rebase upstream/canary +``` + +### 贡献方向 + +- **功能开发** — 查看 [标注为 `good first issue` 的 Issue](https://github.com/lobehub/lobe-chat/issues?q=is%3Aissue+label%3A%22good+first+issue%22)，找到适合新手的任务 +- **Bug 修复** — 搜索标注为 `bug` 的开放 Issue +- **文档改善** — 完善文档、修正错别字、添加示例 +- **测试补充** — 为缺少覆盖的代码路径添加测试 +- **翻译** — 添加缺失的 i18n 键（参见 [i18n 指南](/zh/docs/development/internationalization/internationalization-implementation)） 感谢您遵循这些指导原则，它们有助于我们维护项目的质量和一致性。我们期待您的贡献！ diff --git a/docs/development/basic/feature-development.mdx b/docs/development/basic/feature-development.mdx index c8658f1eef..2135d6bdeb 100644 --- a/docs/development/basic/feature-development.mdx +++ b/docs/development/basic/feature-development.mdx @@ -294,6 +294,7 @@ const OpeningQuestions = memo(() => { ``` Key points: + - Read store config via `selectors` - Update config via the `setAgentConfig` action - Use `useTranslation('setting')` for i18n text @@ -321,7 +322,8 @@ const WelcomeMessage = () => { {/* Render guiding questions */} - + + ) : ( ); diff --git a/docs/development/basic/feature-development.zh-CN.mdx b/docs/development/basic/feature-development.zh-CN.mdx index 771866693e..6675dc753b 100644 --- a/docs/development/basic/feature-development.zh-CN.mdx +++ b/docs/development/basic/feature-development.zh-CN.mdx @@ -293,6 +293,7 @@ const OpeningQuestions = memo(() => { ``` 关键点： + - 通过 `selectors` 读取 store 中的配置 - 通过 `setAgentConfig` action 更新配置 - 使用 `useTranslation('setting')` 获取 i18n 文案 @@ -320,7 +321,8 @@ const WelcomeMessage = () => { {/* 渲染引导性问题 */} - + + ) : ( ); diff --git a/docs/development/basic/setup-development.mdx b/docs/development/basic/setup-development.mdx index 017f758088..7cb5361365 100644 --- a/docs/development/basic/setup-development.mdx +++ b/docs/development/basic/setup-development.mdx @@ -135,6 +135,23 @@ When running with Docker Compose development setup: - **SearXNG**: `http://localhost:8180` - **Application**: `http://localhost:3010` +## Alternative Development Modes + +**Desktop App Development** — To work on the Electron desktop app: + +```bash +cd apps/desktop +pnpm run dev +``` + +**Mobile SPA Development** — To develop the mobile web app: + +```bash +bun run dev:spa:mobile +``` + +Access at [http://localhost:3012](http://localhost:3012) + ## Troubleshooting ### Reset Services @@ -167,6 +184,14 @@ Run migrations manually when needed: pnpm db:migrate ``` +### Clean Install + +If you encounter dependency issues, remove all `node_modules` and reinstall: + +```bash +bun run clean:node_modules && pnpm install +``` + --- During the development process, if you encounter any issues with environment setup or have any questions about LobeHub development, feel free to ask us at any time. We look forward to seeing your contributions! diff --git a/docs/development/basic/setup-development.zh-CN.mdx b/docs/development/basic/setup-development.zh-CN.mdx index 7b3bdd45aa..4487233723 100644 --- a/docs/development/basic/setup-development.zh-CN.mdx +++ b/docs/development/basic/setup-development.zh-CN.mdx @@ -132,6 +132,23 @@ bun run dev - **SearXNG**：`http://localhost:8180` - **应用程序**：`http://localhost:3010` +## 其他开发模式 + +**桌面端开发** — 开发 Electron 桌面应用： + +```bash +cd apps/desktop +pnpm run dev +``` + +**移动端 SPA 开发** — 开发移动端 Web 应用： + +```bash +bun run dev:spa:mobile +``` + +访问地址：[http://localhost:3012](http://localhost:3012) + ## 故障排除 ### 重置服务 @@ -164,6 +181,14 @@ lsof -i :8180 # SearXNG pnpm db:migrate ``` +### 清洁安装 + +如遇到依赖问题，删除所有 `node_modules` 并重新安装： + +```bash +bun run clean:node_modules && pnpm install +``` + --- 在开发过程中，如果你在环境设置上遇到任何问题，或者有任何关于 LobeHub 开发的问题，欢迎随时向我们提问。我们期待看到你的贡献！ diff --git a/docs/development/basic/test.mdx b/docs/development/basic/test.mdx index bf170ca509..11dd9a6d1c 100644 --- a/docs/development/basic/test.mdx +++ b/docs/development/basic/test.mdx @@ -1,92 +1,560 @@ --- title: Testing Guide description: >- - Explore LobeHub's testing strategy, including unit and end-to-end testing - methods. + Explore LobeHub's testing strategy, including unit testing with Vitest and + end-to-end testing with Playwright + Cucumber. tags: - LobeHub - Testing - Unit Testing - End-to-End Testing - vitest + - Playwright --- # Testing Guide -LobeHub's testing strategy includes unit testing and end-to-end (E2E) testing. Below are detailed explanations of each type of testing: +LobeHub's testing strategy includes unit testing with [Vitest][vitest-url] and end-to-end (E2E) testing with Playwright + Cucumber. This guide covers how to write and run tests effectively. -## Unit Testing +## Overview -Unit testing is used to test the functionality of independent units in the application, such as components, functions, utility functions, etc. We use [vitest][vitest-url] for unit testing. +Our testing strategy includes: -To run unit tests, you can use the following command: +- **Unit Tests** — Vitest for functions, components, and stores +- **E2E Tests** — Playwright + Cucumber for user flows +- **Type Checking** — TypeScript compiler (`bun run type-check`) +- **Linting** — ESLint, Stylelint + +## Quick Reference + +### Commands ```bash -npm run test +# Run a specific unit test (RECOMMENDED) +bunx vitest run --silent='passed-only' 'path/to/test.test.ts' + +# Run tests in a package (e.g., database) +cd packages/database && bunx vitest run --silent='passed-only' 'src/models/user.test.ts' + +# Type checking +bun run type-check + +# E2E tests +pnpm e2e ``` -This will run all unit tests and generate a test report. + + **Never run the full test suite** with `bun run test` — it runs all tests and takes \~10 minutes. + Always target a specific file with `bunx vitest run --silent='passed-only' '[file-path]'`. + -We encourage developers to write corresponding unit tests while writing code to ensure the quality and stability of the code. +## Unit Testing with Vitest -## 🚧 End-to-End Testing +### Test File Structure -End-to-end testing is used to test the functionality and performance of the application in a real environment. It simulates real user operations and verifies the application's performance in different scenarios. +Create test files alongside the code being tested, named `.test.ts`: -Currently, there is no integrated end-to-end testing in LobeHub. We will gradually introduce end-to-end testing in subsequent iterations. +``` +src/utils/ +├── formatDate.ts +└── formatDate.test.ts +``` -## Development Testing +### Writing Test Cases -### 1. Unit Testing +Use `describe` and `it` to organize test cases. Use `beforeEach`/`afterEach` to manage setup and teardown: -Unit testing is conducted on the smallest testable units in the application, usually functions, components, or modules. In LobeHub, we use [vitest][vitest-url] for unit testing. +```typescript +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; +import { formatDate } from './formatDate'; -#### Writing Test Cases +beforeEach(() => { + vi.clearAllMocks(); +}); -Before writing unit tests, you need to create a directory with the same name as the file to be tested and name the test file `.test.ts`. For example, if you want to test the `src/utils/formatDate.ts` file, the test file should be named `src/utils/formatDate.test.ts`. +afterEach(() => { + vi.restoreAllMocks(); +}); -In the test file, you can use the `describe` and `it` functions to organize and write test cases. The `describe` function is used to create a test suite, and the `it` function is used to write specific test cases. - -```ts -import { formatNumber } from './formatNumber'; - -describe('formatNumber', () => { - it('should format number with comma separator', () => { - const result = formatNumber(1000); - expect(result).toBe('1,000'); +describe('formatDate', () => { + describe('with default format', () => { + it('should format date correctly', () => { + const date = new Date('2024-03-15'); + const result = formatDate(date); + expect(result).toBe('Mar 15, 2024'); + }); }); - it('should return the same number if it is less than 1000', () => { - const result = formatNumber(500); - expect(result).toBe('500'); + describe('with custom format', () => { + it('should use custom format', () => { + const date = new Date('2024-03-15'); + const result = formatDate(date, 'YYYY-MM-DD'); + expect(result).toBe('2024-03-15'); + }); }); }); ``` -In test cases, you can use the `expect` function to assert whether the test results meet expectations. The `expect` function can be used with various matchers, such as `toBe`, `toEqual`, `toBeTruthy`, etc. +### Testing React Components -#### Running Unit Tests +Use `@testing-library/react` to test component behavior: -Execute unit tests by running the following command: +```typescript +import { describe, it, expect, vi } from 'vitest'; +import { render, screen, fireEvent, waitFor } from '@testing-library/react'; +import { UserProfile } from './UserProfile'; -```bash -npm run test +describe('UserProfile', () => { + it('should render user name', () => { + render(); + expect(screen.getByText('Alice')).toBeInTheDocument(); + }); + + it('should call onClick when button clicked', () => { + const onClick = vi.fn(); + render(); + + fireEvent.click(screen.getByRole('button')); + expect(onClick).toHaveBeenCalledOnce(); + }); + + it('should handle async data loading', async () => { + render(); + + expect(screen.getByText('Loading...')).toBeInTheDocument(); + + await waitFor(() => { + expect(screen.getByText('Alice')).toBeInTheDocument(); + }); + }); +}); ``` -This will run all unit tests and output the test results. +### Testing Zustand Stores -## Testing Strategy +Reset store state in `beforeEach` to keep tests independent: -To write effective test cases, you can consider the following testing strategies: +```typescript +import { describe, it, expect, beforeEach } from 'vitest'; +import { act } from '@testing-library/react'; +import { useUserStore } from './index'; -- **Boundary Testing**: Test the boundary conditions of inputs, such as minimum value, maximum value, empty value, etc. -- **Exception Testing**: Test the code handling exceptional cases, such as error handling, fallback in exceptional situations, etc. -- **Functional Testing**: Test whether various functional modules of the application work properly, including user interaction, data processing, etc. -- **Compatibility Testing**: Test the compatibility of the application on different browsers and devices. -- **Performance Testing**: Test the performance of the application under different loads, such as response time, resource utilization, etc. +beforeEach(() => { + useUserStore.setState({ + users: {}, + currentUserId: null, + }); +}); -Also, ensure that your test cases have good coverage, covering critical code and functionality in the application. +describe('useUserStore', () => { + describe('addUser', () => { + it('should add user to store', () => { + const user = { id: '1', name: 'Alice' }; -By properly writing and executing unit tests, integration tests, and end-to-end tests, you can improve the quality and stability of the application and promptly identify and fix potential issues. + act(() => { + useUserStore.getState().addUser(user); + }); + + const state = useUserStore.getState(); + expect(state.users['1']).toEqual(user); + }); + }); + + describe('setCurrentUser', () => { + it('should update current user ID', () => { + act(() => { + useUserStore.getState().setCurrentUser('123'); + }); + + expect(useUserStore.getState().currentUserId).toBe('123'); + }); + }); +}); +``` + +### Mocking + +#### Prefer `vi.spyOn` Over `vi.mock` + +```typescript +// ✅ Good — spyOn is scoped and auto-restores +vi.spyOn(messageService, 'createMessage').mockResolvedValue('msg_123'); + +// ❌ Avoid — global mocks are fragile and leak between tests +vi.mock('@/services/message'); +``` + +#### Mock Browser APIs + +```typescript +// Mock Image +const mockImage = vi.fn(() => ({ + addEventListener: vi.fn((event, handler) => { + if (event === 'load') setTimeout(handler, 0); + }), + removeEventListener: vi.fn(), +})); +vi.stubGlobal('Image', mockImage); + +// Mock URL.createObjectURL +vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock-url'); + +// Mock fetch +global.fetch = vi.fn(() => + Promise.resolve({ + json: () => Promise.resolve({ data: 'test' }), + ok: true, + }), +); +``` + +#### Mock Modules + +```typescript +// Mock external library +vi.mock('axios', () => ({ + default: { + get: vi.fn(() => Promise.resolve({ data: {} })), + }, +})); + +// Mock internal module +vi.mock('@/utils/logger', () => ({ + logger: { + info: vi.fn(), + error: vi.fn(), + }, +})); +``` + +### Testing Async Code + +```typescript +import { waitFor } from '@testing-library/react'; + +it('should load data asynchronously', async () => { + await expect(fetchUser('123')).resolves.toEqual({ id: '123', name: 'Alice' }); +}); + +it('should handle errors', async () => { + await expect(fetchUser('invalid')).rejects.toThrow('User not found'); +}); +``` + +### Testing Database Code + +For database and ORM tests in packages: + +```bash +# Client DB tests +cd packages/database +bunx vitest run --silent='passed-only' 'src/models/user.test.ts' + +# Server DB tests +cd packages/database +TEST_SERVER_DB=1 bunx vitest run --silent='passed-only' 'src/models/user.test.ts' +``` + +## E2E Testing with Playwright + +### Running E2E Tests + +```bash +# Run all E2E tests +pnpm e2e + +# Run in UI mode (interactive) +pnpm e2e:ui + +# Smoke tests only (quick validation) +pnpm test:e2e:smoke +``` + +### E2E Test Structure + +E2E tests live in the `e2e/` directory: + +``` +e2e/ +├── features/ # Cucumber feature files (.feature) +│ ├── auth.feature +│ └── chat.feature +├── step-definitions/ # Step implementations +│ ├── auth.steps.ts +│ └── chat.steps.ts +├── support/ # Shared helpers and hooks +└── playwright.config.ts +``` + +### Writing E2E Tests + +**Feature file** (`e2e/features/chat.feature`): + +```gherkin +Feature: Chat Functionality + + Scenario: User sends a message + Given I am logged in + And I am on the chat page + When I type "Hello, AI!" + And I click the send button + Then I should see my message in the chat + And I should see a response from the AI +``` + +**Step definitions** (`e2e/step-definitions/chat.steps.ts`): + +```typescript +import { Given, When, Then } from '@cucumber/cucumber'; +import { expect } from '@playwright/test'; + +Given('I am on the chat page', async function () { + await this.page.goto('/chat'); +}); + +When('I type {string}', async function (message: string) { + await this.page.fill('[data-testid="chat-input"]', message); +}); + +When('I click the send button', async function () { + await this.page.click('[data-testid="send-button"]'); +}); + +Then('I should see my message in the chat', async function () { + await expect(this.page.locator('.user-message').last()).toBeVisible(); +}); +``` + +## Best Practices + +### 1. Test Behavior, Not Implementation + +```typescript +// ✅ Good — tests what the user experiences +it('should allow user to submit form', () => { + render(); + + fireEvent.change(screen.getByLabelText('Name'), { + target: { value: 'Alice' }, + }); + fireEvent.click(screen.getByText('Submit')); + + expect(screen.getByText('Form submitted')).toBeInTheDocument(); +}); + +// ❌ Bad — tests internal implementation details +it('should call setState when input changes', () => { + const setState = vi.fn(); + render(); + + fireEvent.change(screen.getByLabelText('Name'), { + target: { value: 'Alice' }, + }); + + expect(setState).toHaveBeenCalled(); +}); +``` + +### 2. Use Semantic Queries + +```typescript +// ✅ Good — accessible queries match what users see +screen.getByRole('button', { name: 'Submit' }); +screen.getByLabelText('Email address'); +screen.getByText('Welcome back'); + +// ❌ Bad — test IDs should be a last resort +screen.getByTestId('submit-button'); +``` + +### 3. Clean Up After Each Test + +```typescript +import { beforeEach, afterEach, vi } from 'vitest'; + +beforeEach(() => { + vi.clearAllMocks(); // Clear mock call history + vi.clearAllTimers(); // Clear timers if using fake timers +}); + +afterEach(() => { + vi.restoreAllMocks(); // Restore original implementations +}); +``` + +### 4. Test Edge Cases + +```typescript +describe('validateEmail', () => { + it('should accept valid email', () => { + expect(validateEmail('user@example.com')).toBe(true); + }); + + it('should reject empty string', () => { + expect(validateEmail('')).toBe(false); + }); + + it('should reject email without @', () => { + expect(validateEmail('user.example.com')).toBe(false); + }); + + it('should reject email without domain', () => { + expect(validateEmail('user@')).toBe(false); + }); +}); +``` + +### 5. Keep Tests Independent + +```typescript +// ❌ Bad — tests share state and depend on execution order +let userId: string; + +it('should create user', () => { + userId = createUser('Alice'); + expect(userId).toBeDefined(); +}); + +it('should fetch user', () => { + const user = getUser(userId); // depends on previous test + expect(user.name).toBe('Alice'); +}); + +// ✅ Good — each test sets up its own data +it('should create user', () => { + const userId = createUser('Alice'); + expect(userId).toBeDefined(); +}); + +it('should fetch user', () => { + const userId = createUser('Bob'); + const user = getUser(userId); + expect(user.name).toBe('Bob'); +}); +``` + +## Common Patterns + +### Testing Hooks + +```typescript +import { renderHook, act } from '@testing-library/react'; +import { useCounter } from './useCounter'; + +it('should increment counter', () => { + const { result } = renderHook(() => useCounter()); + + expect(result.current.count).toBe(0); + + act(() => { + result.current.increment(); + }); + + expect(result.current.count).toBe(1); +}); +``` + +### Testing Context Providers + +```typescript +import { render, screen } from '@testing-library/react'; +import { ThemeProvider } from './ThemeProvider'; +import { MyComponent } from './MyComponent'; + +function renderWithTheme(component: React.ReactElement) { + return render({component}); +} + +it('should use theme', () => { + renderWithTheme(); + expect(screen.getByRole('main')).toHaveClass('dark-theme'); +}); +``` + +### Testing API Calls with MSW + +```typescript +import { rest } from 'msw'; +import { setupServer } from 'msw/node'; + +const server = setupServer( + rest.get('/api/user', (req, res, ctx) => { + return res(ctx.json({ id: '1', name: 'Alice' })); + }), +); + +beforeAll(() => server.listen()); +afterEach(() => server.resetHandlers()); +afterAll(() => server.close()); + +it('should fetch user data', async () => { + const user = await fetchUser('1'); + expect(user.name).toBe('Alice'); +}); +``` + +## Coverage + +### Generate Coverage Report + +```bash +bun run test-app:coverage +``` + +Then open `coverage/index.html` to view the report. + +### Coverage Goals + +| Area | Target | +| -------------- | ------ | +| Critical paths | 80%+ | +| Utilities | 90%+ | +| UI components | 70%+ | + +## Debugging Tests + +### VS Code Debugging + +Add to `.vscode/launch.json`: + +```json +{ + "type": "node", + "request": "launch", + "name": "Debug Vitest", + "runtimeExecutable": "bun", + "runtimeArgs": ["x", "vitest", "run", "${file}"], + "console": "integratedTerminal" +} +``` + +### Vitest UI + +```bash +bunx vitest --ui +``` + +Opens an interactive test explorer in the browser. + +### Console Logging + +```typescript +it('should work', () => { + console.log('Debug:', value); // appears in test output + expect(value).toBe(expected); +}); +``` + +## CI/CD Integration + +GitHub Actions automatically runs on every PR: + +1. Linting (ESLint, Stylelint) +2. Type checking +3. Unit tests +4. E2E tests +5. Build verification + +All checks must pass before a PR can merge. [vitest-url]: https://vitest.dev/ diff --git a/docs/development/basic/test.zh-CN.mdx b/docs/development/basic/test.zh-CN.mdx index 9899b7c97d..53c5a89125 100644 --- a/docs/development/basic/test.zh-CN.mdx +++ b/docs/development/basic/test.zh-CN.mdx @@ -1,89 +1,558 @@ --- title: 测试指南 -description: 了解 LobeHub 的单元测试和端到端测试策略，确保代码质量与稳定性。 +description: 了解 LobeHub 的测试策略，包括使用 Vitest 进行单元测试以及使用 Playwright + Cucumber 进行端到端测试。 tags: - LobeHub - 单元测试 - 端到端测试 - 测试策略 + - vitest + - Playwright --- # 测试指南 -LobeHub 的测试策略包括单元测试和端到端 (E2E) 测试。下面是每种测试的详细说明： +LobeHub 的测试策略包括使用 [Vitest][vitest-url] 进行单元测试，以及使用 Playwright + Cucumber 进行端到端 (E2E) 测试。本指南介绍如何高效地编写和运行测试。 -## 单元测试 +## 概述 -单元测试用于测试应用中的独立单元（如组件、函数、工具函数等）的功能。我们使用 [vitest][vitest-url] 进行单元测试。 +我们的测试策略包括： -要运行单元测试，可以使用以下命令： +- **单元测试** — 使用 Vitest 测试函数、组件和状态存储 +- **E2E 测试** — 使用 Playwright + Cucumber 测试用户流程 +- **类型检查** — TypeScript 编译器（`bun run type-check`） +- **代码规范** — ESLint、Stylelint + +## 快速参考 + +### 命令 ```bash -npm run test +# 运行指定的单元测试（推荐） +bunx vitest run --silent='passed-only' 'path/to/test.test.ts' + +# 在包中运行测试（例如 database 包） +cd packages/database && bunx vitest run --silent='passed-only' 'src/models/user.test.ts' + +# 类型检查 +bun run type-check + +# E2E 测试 +pnpm e2e ``` -这将运行所有的单元测试，并生成测试报告。 + + **切勿运行完整测试套件**（`bun run test`）—— 这会运行所有测试，耗时约 10 分钟。请始终使用 + `bunx vitest run --silent='passed-only' '[file-path]'` 指定目标文件。 + -我们鼓励开发者在编写代码时，同时编写对应的单元测试，以确保代码的质量和稳定性。 +## 使用 Vitest 进行单元测试 -## 🚧 端到端测试 +### 测试文件结构 -端到端测试用于测试应用在真实环境中的功能和性能。它模拟用户的真实操作，并验证应用在不同场景下的表现。 +测试文件与被测代码并列放置，命名为 `.test.ts`： -在 LobeHub 中，目前暂时没有集成端到端测试，我们会在后续迭代中逐步引入端到端测试。 +``` +src/utils/ +├── formatDate.ts +└── formatDate.test.ts +``` -## 开发测试 +### 编写测试用例 -### 1. 单元测试 +使用 `describe` 和 `it` 组织测试用例，使用 `beforeEach`/`afterEach` 管理测试前后的状态： -单元测试是针对应用中的最小可测试单元进行的测试，通常是针对函数、组件或模块进行的测试。在 LobeHub 中，我们使用 [vitest][vitest-url] 进行单元测试。 +```typescript +import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'; +import { formatDate } from './formatDate'; -#### 编写测试用例 +beforeEach(() => { + vi.clearAllMocks(); +}); -在编写单元测试之前，您需要创建一个与被测试文件相同的目录，并将测试文件命名为 `.test.ts`。例如，如果要测试 `src/utils/formatDate.ts` 文件，测试文件应命名为 `src/utils/formatDate.test.ts`。 +afterEach(() => { + vi.restoreAllMocks(); +}); -在测试文件中，您可以使用 `describe` 和 `it` 函数来组织和编写测试用例。`describe` 函数用于创建测试套件，`it` 函数用于编写具体的测试用例。 - -```ts -import { formatNumber } from './formatNumber'; - -describe('formatNumber', () => { - it('should format number with comma separator', () => { - const result = formatNumber(1000); - expect(result).toBe('1,000'); +describe('formatDate', () => { + describe('使用默认格式', () => { + it('应正确格式化日期', () => { + const date = new Date('2024-03-15'); + const result = formatDate(date); + expect(result).toBe('Mar 15, 2024'); + }); }); - it('should return the same number if it is less than 1000', () => { - const result = formatNumber(500); - expect(result).toBe('500'); + describe('使用自定义格式', () => { + it('应使用自定义格式', () => { + const date = new Date('2024-03-15'); + const result = formatDate(date, 'YYYY-MM-DD'); + expect(result).toBe('2024-03-15'); + }); }); }); ``` -在测试用例中，您可以使用 `expect` 函数来断言测试结果是否符合预期。`expect` 函数可以与各种匹配器（matchers）一起使用，例如 `toBe`、`toEqual`、`toBeTruthy` 等。 +### 测试 React 组件 -#### 运行单元测试 +使用 `@testing-library/react` 测试组件行为： -通过运行以下命令来执行单元测试： +```typescript +import { describe, it, expect, vi } from 'vitest'; +import { render, screen, fireEvent, waitFor } from '@testing-library/react'; +import { UserProfile } from './UserProfile'; -```bash -npm run test +describe('UserProfile', () => { + it('应渲染用户名', () => { + render(); + expect(screen.getByText('Alice')).toBeInTheDocument(); + }); + + it('点击按钮时应调用 onClick', () => { + const onClick = vi.fn(); + render(); + + fireEvent.click(screen.getByRole('button')); + expect(onClick).toHaveBeenCalledOnce(); + }); + + it('应处理异步数据加载', async () => { + render(); + + expect(screen.getByText('Loading...')).toBeInTheDocument(); + + await waitFor(() => { + expect(screen.getByText('Alice')).toBeInTheDocument(); + }); + }); +}); ``` -这将运行所有的单元测试，并输出测试结果。 +### 测试 Zustand 状态存储 -## 测试策略 +在 `beforeEach` 中重置 store 状态，确保测试互相独立： -为了编写有效的测试用例，您可以考虑以下测试策略： +```typescript +import { describe, it, expect, beforeEach } from 'vitest'; +import { act } from '@testing-library/react'; +import { useUserStore } from './index'; -- **边界条件测试**：测试输入的边界条件，例如最小值、最大值、空值等。 -- **异常情况测试**：测试处理异常情况的代码，例如错误处理、异常情况下的回退等。 -- **功能测试**：测试应用的各个功能模块是否正常工作，包括用户交互、数据处理等。 -- **兼容性测试**：测试应用在不同浏览器和设备上的兼容性。 -- **性能测试**：测试应用在不同负载下的性能表现，例如响应时间、资源占用等。 +beforeEach(() => { + useUserStore.setState({ + users: {}, + currentUserId: null, + }); +}); -同时，请确保您的测试用例具有良好的覆盖率，覆盖到应用中的关键代码和功能。 +describe('useUserStore', () => { + describe('addUser', () => { + it('应将用户添加到 store', () => { + const user = { id: '1', name: 'Alice' }; -通过合理编写和执行单元测试、集成测试和端到端测试，您可以提高应用的质量和稳定性，并及时发现和修复潜在的问题。 + act(() => { + useUserStore.getState().addUser(user); + }); + + const state = useUserStore.getState(); + expect(state.users['1']).toEqual(user); + }); + }); + + describe('setCurrentUser', () => { + it('应更新当前用户 ID', () => { + act(() => { + useUserStore.getState().setCurrentUser('123'); + }); + + expect(useUserStore.getState().currentUserId).toBe('123'); + }); + }); +}); +``` + +### Mock（模拟） + +#### 优先使用 `vi.spyOn` 而非 `vi.mock` + +```typescript +// ✅ 推荐 — spyOn 作用域明确，且会自动恢复 +vi.spyOn(messageService, 'createMessage').mockResolvedValue('msg_123'); + +// ❌ 避免 — 全局 mock 容易在测试间产生污染 +vi.mock('@/services/message'); +``` + +#### Mock 浏览器 API + +```typescript +// Mock Image +const mockImage = vi.fn(() => ({ + addEventListener: vi.fn((event, handler) => { + if (event === 'load') setTimeout(handler, 0); + }), + removeEventListener: vi.fn(), +})); +vi.stubGlobal('Image', mockImage); + +// Mock URL.createObjectURL +vi.spyOn(URL, 'createObjectURL').mockReturnValue('blob:mock-url'); + +// Mock fetch +global.fetch = vi.fn(() => + Promise.resolve({ + json: () => Promise.resolve({ data: 'test' }), + ok: true, + }), +); +``` + +#### Mock 模块 + +```typescript +// Mock 外部库 +vi.mock('axios', () => ({ + default: { + get: vi.fn(() => Promise.resolve({ data: {} })), + }, +})); + +// Mock 内部模块 +vi.mock('@/utils/logger', () => ({ + logger: { + info: vi.fn(), + error: vi.fn(), + }, +})); +``` + +### 测试异步代码 + +```typescript +import { waitFor } from '@testing-library/react'; + +it('应异步加载数据', async () => { + await expect(fetchUser('123')).resolves.toEqual({ id: '123', name: 'Alice' }); +}); + +it('应处理错误', async () => { + await expect(fetchUser('invalid')).rejects.toThrow('User not found'); +}); +``` + +### 测试数据库代码 + +针对包中的数据库和 ORM 测试： + +```bash +# 客户端 DB 测试 +cd packages/database +bunx vitest run --silent='passed-only' 'src/models/user.test.ts' + +# 服务端 DB 测试 +cd packages/database +TEST_SERVER_DB=1 bunx vitest run --silent='passed-only' 'src/models/user.test.ts' +``` + +## 使用 Playwright 进行 E2E 测试 + +### 运行 E2E 测试 + +```bash +# 运行所有 E2E 测试 +pnpm e2e + +# 交互模式（UI 界面） +pnpm e2e:ui + +# 仅运行冒烟测试（快速验证） +pnpm test:e2e:smoke +``` + +### E2E 测试结构 + +E2E 测试位于 `e2e/` 目录下： + +``` +e2e/ +├── features/ # Cucumber feature 文件（.feature） +│ ├── auth.feature +│ └── chat.feature +├── step-definitions/ # 步骤实现 +│ ├── auth.steps.ts +│ └── chat.steps.ts +├── support/ # 共享辅助函数和 hooks +└── playwright.config.ts +``` + +### 编写 E2E 测试 + +**Feature 文件** (`e2e/features/chat.feature`)： + +```gherkin +Feature: 聊天功能 + + Scenario: 用户发送消息 + Given 我已登录 + And 我在聊天页面 + When 我输入 "你好，AI！" + And 我点击发送按钮 + Then 我应该在聊天中看到我的消息 + And 我应该看到 AI 的回复 +``` + +**步骤定义** (`e2e/step-definitions/chat.steps.ts`)： + +```typescript +import { Given, When, Then } from '@cucumber/cucumber'; +import { expect } from '@playwright/test'; + +Given('我在聊天页面', async function () { + await this.page.goto('/chat'); +}); + +When('我输入 {string}', async function (message: string) { + await this.page.fill('[data-testid="chat-input"]', message); +}); + +When('我点击发送按钮', async function () { + await this.page.click('[data-testid="send-button"]'); +}); + +Then('我应该在聊天中看到我的消息', async function () { + await expect(this.page.locator('.user-message').last()).toBeVisible(); +}); +``` + +## 最佳实践 + +### 1. 测试行为，而非实现细节 + +```typescript +// ✅ 推荐 — 测试用户可感知的行为 +it('应允许用户提交表单', () => { + render(); + + fireEvent.change(screen.getByLabelText('Name'), { + target: { value: 'Alice' }, + }); + fireEvent.click(screen.getByText('Submit')); + + expect(screen.getByText('Form submitted')).toBeInTheDocument(); +}); + +// ❌ 避免 — 测试内部实现细节 +it('输入变化时应调用 setState', () => { + const setState = vi.fn(); + render(); + + fireEvent.change(screen.getByLabelText('Name'), { + target: { value: 'Alice' }, + }); + + expect(setState).toHaveBeenCalled(); +}); +``` + +### 2. 使用语义化查询 + +```typescript +// ✅ 推荐 — 语义化查询与用户感知一致 +screen.getByRole('button', { name: 'Submit' }); +screen.getByLabelText('Email address'); +screen.getByText('Welcome back'); + +// ❌ 避免 — testId 应作为最后手段 +screen.getByTestId('submit-button'); +``` + +### 3. 每次测试后清理状态 + +```typescript +import { beforeEach, afterEach, vi } from 'vitest'; + +beforeEach(() => { + vi.clearAllMocks(); // 清除 mock 调用历史 + vi.clearAllTimers(); // 使用 fake timers 时清除计时器 +}); + +afterEach(() => { + vi.restoreAllMocks(); // 恢复原始实现 +}); +``` + +### 4. 测试边界条件 + +```typescript +describe('validateEmail', () => { + it('应接受有效的电子邮件', () => { + expect(validateEmail('user@example.com')).toBe(true); + }); + + it('应拒绝空字符串', () => { + expect(validateEmail('')).toBe(false); + }); + + it('应拒绝不含 @ 的邮件', () => { + expect(validateEmail('user.example.com')).toBe(false); + }); + + it('应拒绝缺少域名的邮件', () => { + expect(validateEmail('user@')).toBe(false); + }); +}); +``` + +### 5. 保持测试相互独立 + +```typescript +// ❌ 避免 — 测试之间共享状态，依赖执行顺序 +let userId: string; + +it('应创建用户', () => { + userId = createUser('Alice'); + expect(userId).toBeDefined(); +}); + +it('应获取用户', () => { + const user = getUser(userId); // 依赖上一个测试 + expect(user.name).toBe('Alice'); +}); + +// ✅ 推荐 — 每个测试自行准备数据 +it('应创建用户', () => { + const userId = createUser('Alice'); + expect(userId).toBeDefined(); +}); + +it('应获取用户', () => { + const userId = createUser('Bob'); + const user = getUser(userId); + expect(user.name).toBe('Bob'); +}); +``` + +## 常用模式 + +### 测试 Hooks + +```typescript +import { renderHook, act } from '@testing-library/react'; +import { useCounter } from './useCounter'; + +it('应递增计数器', () => { + const { result } = renderHook(() => useCounter()); + + expect(result.current.count).toBe(0); + + act(() => { + result.current.increment(); + }); + + expect(result.current.count).toBe(1); +}); +``` + +### 测试 Context Provider + +```typescript +import { render, screen } from '@testing-library/react'; +import { ThemeProvider } from './ThemeProvider'; +import { MyComponent } from './MyComponent'; + +function renderWithTheme(component: React.ReactElement) { + return render({component}); +} + +it('应使用主题', () => { + renderWithTheme(); + expect(screen.getByRole('main')).toHaveClass('dark-theme'); +}); +``` + +### 使用 MSW 测试 API 调用 + +```typescript +import { rest } from 'msw'; +import { setupServer } from 'msw/node'; + +const server = setupServer( + rest.get('/api/user', (req, res, ctx) => { + return res(ctx.json({ id: '1', name: 'Alice' })); + }), +); + +beforeAll(() => server.listen()); +afterEach(() => server.resetHandlers()); +afterAll(() => server.close()); + +it('应获取用户数据', async () => { + const user = await fetchUser('1'); + expect(user.name).toBe('Alice'); +}); +``` + +## 测试覆盖率 + +### 生成覆盖率报告 + +```bash +bun run test-app:coverage +``` + +之后打开 `coverage/index.html` 查看报告。 + +### 覆盖率目标 + +| 类型 | 目标 | +| ----- | ---- | +| 关键路径 | 80%+ | +| 工具函数 | 90%+ | +| UI 组件 | 70%+ | + +## 调试测试 + +### VS Code 调试 + +在 `.vscode/launch.json` 中添加： + +```json +{ + "type": "node", + "request": "launch", + "name": "Debug Vitest", + "runtimeExecutable": "bun", + "runtimeArgs": ["x", "vitest", "run", "${file}"], + "console": "integratedTerminal" +} +``` + +### Vitest UI + +```bash +bunx vitest --ui +``` + +在浏览器中打开交互式测试资源管理器。 + +### Console 日志 + +```typescript +it('应正常工作', () => { + console.log('调试:', value); // 在测试输出中显示 + expect(value).toBe(expected); +}); +``` + +## CI/CD 集成 + +GitHub Actions 会在每次 PR 时自动运行以下检查： + +1. 代码规范（ESLint、Stylelint） +2. 类型检查 +3. 单元测试 +4. E2E 测试 +5. 构建验证 + +所有检查通过后 PR 才可合并。 [vitest-url]: https://vitest.dev/ diff --git a/docs/self-hosting/advanced/feature-flags.mdx b/docs/self-hosting/advanced/feature-flags.mdx index 611e68259b..5ec16b3c06 100644 --- a/docs/self-hosting/advanced/feature-flags.mdx +++ b/docs/self-hosting/advanced/feature-flags.mdx @@ -58,3 +58,27 @@ You can achieve various feature combinations using the above configuration synta | `commercial_hide_docs` | Hides documentation and help menu including changelog, docs, and feedback (requires commercial license). | Disabled | You can always check the [featureFlags](https://github.com/lobehub/lobehub/blob/main/src/config/featureFlags/schema.ts) to get the latest list of feature flags. + +## Standalone Feature Enable/Disable Variables + +In addition to the `FEATURE_FLAGS` system above, LobeHub provides dedicated environment variables to enable or disable specific features that depend on external infrastructure. These are standalone variables (not part of `FEATURE_FLAGS`): + +| Environment Variable | Default | Description | Requires | +| ------------------------ | ------- | ---------------------------------------------------------------- | ------------------------ | +| `ENABLED_ARTIFACTS` | `1` | Enable the Artifacts panel (Claude-style code/SVG/React preview) | — | +| `ENABLED_MCP` | `1` | Enable the Model Context Protocol plugin system | — | +| `ENABLED_UPLOAD` | `1` | Enable file upload functionality | S3-compatible storage | +| `ENABLED_KNOWLEDGE_BASE` | `1` | Enable Knowledge Base and RAG features | S3 storage + PostgreSQL | +| `ENABLED_WEB_SEARCH` | `1` | Enable web search integration (online search) | Searxng or search plugin | + +Set to `0` to disable. For example, to disable file upload if you haven't configured S3: + +```bash +ENABLED_UPLOAD=0 +ENABLED_KNOWLEDGE_BASE=0 +``` + + + `ENABLED_UPLOAD` and `ENABLED_KNOWLEDGE_BASE` should be disabled if you haven't configured + S3-compatible storage, as file operations will fail without it. + diff --git a/docs/self-hosting/advanced/feature-flags.zh-CN.mdx b/docs/self-hosting/advanced/feature-flags.zh-CN.mdx index fd1a5f03b4..146ed791fc 100644 --- a/docs/self-hosting/advanced/feature-flags.zh-CN.mdx +++ b/docs/self-hosting/advanced/feature-flags.zh-CN.mdx @@ -54,3 +54,26 @@ tags: | `commercial_hide_docs` | 隐藏文档和帮助菜单，包括更新日志、文档和反馈（需要商业授权）。 | 关闭 | 你可以随时检查 [featureFlags](https://github.com/lobehub/lobehub/blob/main/src/config/featureFlags/schema.ts) 以获取最新的特性标志列表。 + +## 独立功能启用 / 禁用变量 + +除了上述 `FEATURE_FLAGS` 体系外，LobeHub 还提供了一批独立的环境变量，用于控制依赖外部基础设施的特定功能。这些是独立变量（不属于 `FEATURE_FLAGS`）： + +| 环境变量 | 默认值 | 说明 | 依赖 | +| ------------------------ | --- | -------------------------------------------- | ------------------ | +| `ENABLED_ARTIFACTS` | `1` | 启用 Artifacts 面板（Claude 风格的代码 / SVG/React 预览） | — | +| `ENABLED_MCP` | `1` | 启用模型上下文协议（MCP）插件系统 | — | +| `ENABLED_UPLOAD` | `1` | 启用文件上传功能 | S3 兼容存储 | +| `ENABLED_KNOWLEDGE_BASE` | `1` | 启用知识库和 RAG 功能 | S3 存储 + PostgreSQL | +| `ENABLED_WEB_SEARCH` | `1` | 启用网络搜索集成（在线搜索） | Searxng 或搜索插件 | + +设置为 `0` 可禁用对应功能。例如，若未配置 S3 存储，可禁用文件上传： + +```bash +ENABLED_UPLOAD=0 +ENABLED_KNOWLEDGE_BASE=0 +``` + + + 如果未配置 S3 兼容存储，应将 `ENABLED_UPLOAD` 和 `ENABLED_KNOWLEDGE_BASE` 设为禁用状态，否则文件相关操作将会失败。 + diff --git a/docs/self-hosting/advanced/model-list.mdx b/docs/self-hosting/advanced/model-list.mdx index 79551d7bf2..252ff17227 100644 --- a/docs/self-hosting/advanced/model-list.mdx +++ b/docs/self-hosting/advanced/model-list.mdx @@ -67,3 +67,84 @@ Currently supported extension capabilities are: | `reasoning` | Support Reasoning | | `search` | Support Web Search | | `file` | File Upload (a bit hacky, not recommended for daily use) | + +## Provider-Specific Examples + +### Azure OpenAI + +Azure requires deployment name mapping using `->deploymentName`: + +```bash +AZURE_ENDPOINT=https://your-resource.openai.azure.com +AZURE_API_KEY=your-api-key +AZURE_API_VERSION=2024-02-01 +# id->deploymentName=displayName +AZURE_MODEL_LIST="gpt-35-turbo->my-gpt35-deploy=GPT-3.5 Turbo<16000:fc>,gpt-4->my-gpt4-deploy=GPT-4<128000:fc:vision" +``` + +### Ollama (Local Models) + +```bash +OLLAMA_PROXY_URL=http://localhost:11434 +OLLAMA_MODEL_LIST="+llama3:8b=Llama 3 8B<8192>,+mistral:latest=Mistral<8192:fc>,+codellama:34b=Code Llama 34B<16000" +``` + +### Multiple Providers Simultaneously + +```bash +# OpenAI — curated list +OPENAI_API_KEY=sk-... +OPENAI_MODEL_LIST=-all,+gpt-4o,+gpt-4o-mini + +# Anthropic — long context backup +ANTHROPIC_API_KEY=sk-ant-... +ANTHROPIC_MODEL_LIST="+claude-3-opus-20240229=Claude 3 Opus<200000:vision:fc>,+claude-3-5-sonnet-20241022=Claude 3.5 Sonnet<200000:vision:fc" + +# Google +GOOGLE_API_KEY=... +GOOGLE_MODEL_LIST="+gemini-1.5-pro=Gemini 1.5 Pro<1000000:vision:fc" +``` + +## Best Practices + +**Start with `-all` for a clean slate** — Hide all default models, then explicitly add only the ones you want: + +```bash +OPENAI_MODEL_LIST=-all,+gpt-4o,+gpt-4o-mini +``` + +**Use descriptive display names** — Make model names user-friendly and meaningful to your users: + +```bash +OPENAI_MODEL_LIST="gpt-4o=GPT-4o (Recommended),gpt-4o-mini=GPT-4o Mini (Fast & Cheap)" +``` + +**Test before production** — Verify a new model configuration in a dev environment: + +```bash +docker run -d -p 3210:3210 \ + -e OPENAI_API_KEY="sk-test..." \ + -e OPENAI_MODEL_LIST="-all,+gpt-4o" \ + --name lobe-chat-test lobehub/lobe-chat +``` + +## Troubleshooting + +**Model doesn't appear in the selector** + +- Check for syntax errors (missing commas, mismatched angle brackets) +- Ensure the provider itself is enabled (`ENABLED_OPENAI=1`, etc.) +- If using `-all`, confirm you added the model with `+` +- Check logs: `docker logs lobehub | grep -i "model"` + +**Model returns empty responses** + +- Try adding `/v1` suffix to the proxy URL: `OPENAI_PROXY_URL=https://api.example.com/v1` +- Verify the model ID matches what the provider API expects exactly +- Confirm the API key has access to that model + +**Extension capabilities not working** + +- The `maxToken` value must be the **first** item inside `< >`: `<8192:fc:vision>` not `` +- Confirm the model actually supports the capability in the provider's API (LobeHub cannot enable capabilities the API doesn't provide) +- Verify you are running a recent enough version of LobeHub diff --git a/docs/self-hosting/advanced/model-list.zh-CN.mdx b/docs/self-hosting/advanced/model-list.zh-CN.mdx index 41a757ee8f..022ae91ce7 100644 --- a/docs/self-hosting/advanced/model-list.zh-CN.mdx +++ b/docs/self-hosting/advanced/model-list.zh-CN.mdx @@ -66,3 +66,84 @@ id->deploymentName=displayNamedeploymentName` 映射部署名称： + +```bash +AZURE_ENDPOINT=https://your-resource.openai.azure.com +AZURE_API_KEY=your-api-key +AZURE_API_VERSION=2024-02-01 +# id->deploymentName=displayName<能力> +AZURE_MODEL_LIST="gpt-35-turbo->my-gpt35-deploy=GPT-3.5 Turbo<16000:fc>,gpt-4->my-gpt4-deploy=GPT-4<128000:fc:vision" +``` + +### Ollama（本地模型） + +```bash +OLLAMA_PROXY_URL=http://localhost:11434 +OLLAMA_MODEL_LIST="+llama3:8b=Llama 3 8B<8192>,+mistral:latest=Mistral<8192:fc>,+codellama:34b=Code Llama 34B<16000" +``` + +### 同时配置多个提供商 + +```bash +# OpenAI — 精选列表 +OPENAI_API_KEY=sk-... +OPENAI_MODEL_LIST=-all,+gpt-4o,+gpt-4o-mini + +# Anthropic — 长上下文备选 +ANTHROPIC_API_KEY=sk-ant-... +ANTHROPIC_MODEL_LIST="+claude-3-opus-20240229=Claude 3 Opus<200000:vision:fc>,+claude-3-5-sonnet-20241022=Claude 3.5 Sonnet<200000:vision:fc" + +# Google +GOOGLE_API_KEY=... +GOOGLE_MODEL_LIST="+gemini-1.5-pro=Gemini 1.5 Pro<1000000:vision:fc" +``` + +## 最佳实践 + +**使用 `-all` 从零开始** — 隐藏所有默认模型，再明确添加你需要的模型： + +```bash +OPENAI_MODEL_LIST=-all,+gpt-4o,+gpt-4o-mini +``` + +**使用描述性的展示名称** — 让模型名称对用户更友好、更清晰： + +```bash +OPENAI_MODEL_LIST="gpt-4o=GPT-4o（推荐）,gpt-4o-mini=GPT-4o Mini（快速省钱）" +``` + +**上生产前先测试** — 在开发环境中验证新的模型配置： + +```bash +docker run -d -p 3210:3210 \ + -e OPENAI_API_KEY="sk-test..." \ + -e OPENAI_MODEL_LIST="-all,+gpt-4o" \ + --name lobe-chat-test lobehub/lobe-chat +``` + +## 故障排查 + +**模型未出现在选择器中** + +- 检查语法错误（逗号缺失、尖括号不匹配） +- 确认提供商本身已启用（`ENABLED_OPENAI=1` 等） +- 若使用了 `-all`，确认已用 `+` 添加该模型 +- 查看日志：`docker logs lobehub | grep -i "model"` + +**模型返回空响应** + +- 尝试在代理 URL 末尾加上 `/v1`：`OPENAI_PROXY_URL=https://api.example.com/v1` +- 验证模型 ID 与提供商 API 期望的完全一致 +- 确认 API Key 有权访问该模型 + +**扩展能力不生效** + +- `maxToken` 值必须是 `< >` 内的**第一个**值：`<8192:fc:vision>` 而非 `` +- 确认该模型在提供商 API 中实际支持该能力（LobeHub 无法开启 API 本身不提供的能力） +- 确认你运行的是足够新的 LobeHub 版本 diff --git a/docs/self-hosting/advanced/redis.mdx b/docs/self-hosting/advanced/redis.mdx index 90134bb321..16e81a372c 100644 --- a/docs/self-hosting/advanced/redis.mdx +++ b/docs/self-hosting/advanced/redis.mdx @@ -1,6 +1,8 @@ --- title: Configure Redis Cache Service -description: Learn how to configure Redis cache service to optimize LobeHub performance and session management. +description: >- + Learn how to configure Redis cache service to optimize LobeHub performance and + session management. tags: - Redis - Cache diff --git a/docs/self-hosting/advanced/redis/upstash.mdx b/docs/self-hosting/advanced/redis/upstash.mdx index 7d4a9eb913..28f8227902 100644 --- a/docs/self-hosting/advanced/redis/upstash.mdx +++ b/docs/self-hosting/advanced/redis/upstash.mdx @@ -1,6 +1,8 @@ --- title: Configuring Upstash Redis Service -description: Step-by-step guide to configure Upstash Redis for LobeHub cache and session storage. +description: >- + Step-by-step guide to configure Upstash Redis for LobeHub cache and session + storage. tags: - Upstash - Redis diff --git a/docs/self-hosting/auth.mdx b/docs/self-hosting/auth.mdx index e4460cd1c2..e4050b5e8f 100644 --- a/docs/self-hosting/auth.mdx +++ b/docs/self-hosting/auth.mdx @@ -1,9 +1,9 @@ --- title: LobeHub Authentication Service Configuration description: >- - Learn how to configure external authentication services using Better Auth - for centralized user authorization management. Supported - authentication services include Auth0, Azure ID, etc. + Learn how to configure external authentication services using Better Auth for + centralized user authorization management. Supported authentication services + include Auth0, Azure ID, etc. tags: - Authentication Service - Better Auth @@ -105,9 +105,71 @@ When configuring OAuth providers, use the following callback URL format: - **Development**: `http://localhost:3210/api/auth/callback/{provider}` - **Production**: `https://yourdomain.com/api/auth/callback/{provider}` +## Email/Password Options + +**Disable email/password login (SSO-only mode):** + +Set `AUTH_DISABLE_EMAIL_PASSWORD=1` to hide the email input on the login page and redirect the signup page to login. Users can only sign in via configured SSO providers. Ensure at least one SSO provider is configured before enabling this. + +**Restrict registration to specific emails or domains:** + +Set `AUTH_ALLOWED_EMAILS` with a comma-separated list: + +```bash +# Allow only @example.com emails +AUTH_ALLOWED_EMAILS=example.com + +# Allow multiple domains and specific addresses +AUTH_ALLOWED_EMAILS=example.com,company.org,admin@other.com +``` + + + `AUTH_ALLOWED_EMAILS` restricts which emails can register, but does not verify email ownership. + Combine with `AUTH_EMAIL_VERIFICATION=1` to ensure users own the email they register with. + + +## Quick OAuth Setup Examples + +**Google OAuth:** + +1. Create credentials at [Google Cloud Console](https://console.cloud.google.com/apis/credentials) +2. Set authorized redirect URI: `https://yourdomain.com/api/auth/callback/google` +3. Configure environment variables: + +```bash +AUTH_SSO_PROVIDERS=google +AUTH_GOOGLE_ID=xxxxx.apps.googleusercontent.com +AUTH_GOOGLE_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx +``` + +**GitHub OAuth:** + +1. Create OAuth App at [GitHub Developer Settings](https://github.com/settings/developers) +2. Set callback URL: `https://yourdomain.com/api/auth/callback/github` +3. Configure environment variables: + +```bash +AUTH_SSO_PROVIDERS=github +AUTH_GITHUB_ID=Ov23xxxxxxxxxxxxx +AUTH_GITHUB_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + ## Email Service Configuration -Email service is used for email verification, password reset, and magic link delivery. For detailed configuration, see [Email Service Configuration](/docs/self-hosting/auth/email). +Email service is required for email verification, password reset, and magic link delivery. + +**SMTP configuration:** + +```bash +SMTP_HOST=smtp.gmail.com # SMTP server hostname +SMTP_PORT=587 # 587 for TLS (recommended), 465 for SSL +SMTP_SECURE=false # true for port 465, false for port 587 +SMTP_USER=your-email@gmail.com +SMTP_PASS=your-app-specific-password # For Gmail, use an app-specific password +SMTP_FROM=noreply@yourdomain.com # Optional, defaults to SMTP_USER +``` + +For detailed configuration, see [Email Service Configuration](/docs/self-hosting/auth/email). Go to [Environment Variables](/docs/self-hosting/environment-variables/auth#better-auth) for detailed information on all Better Auth variables. diff --git a/docs/self-hosting/auth.zh-CN.mdx b/docs/self-hosting/auth.zh-CN.mdx index e3d8c19a2a..9dcd1b787c 100644 --- a/docs/self-hosting/auth.zh-CN.mdx +++ b/docs/self-hosting/auth.zh-CN.mdx @@ -1,8 +1,6 @@ --- title: LobeHub 身份验证服务配置 -description: >- - 了解如何使用 Better Auth 配置外部身份验证服务，以统一管理用户授权。支持的身份验证服务包括 Auth0、 - Azure ID 等。 +description: 了解如何使用 Better Auth 配置外部身份验证服务，以统一管理用户授权。支持的身份验证服务包括 Auth0、 Azure ID 等。 tags: - 身份验证服务 - Better Auth @@ -105,9 +103,71 @@ LobeHub 支持使用 Better Auth 配置外部身份验证服务，供企业 / - **开发环境**：`http://localhost:3210/api/auth/callback/{provider}` - **生产环境**：`https://yourdomain.com/api/auth/callback/{provider}` +## 邮箱密码选项 + +**禁用邮箱密码登录（仅 SSO 模式）：** + +设置 `AUTH_DISABLE_EMAIL_PASSWORD=1` 可在登录页面隐藏邮箱输入框，并将注册页面重定向至登录页面。用户只能通过已配置的 SSO 提供商登录。启用前请确保至少配置了一个 SSO 提供商。 + +**限制注册邮箱或域名：** + +设置 `AUTH_ALLOWED_EMAILS`，以逗号分隔多个值： + +```bash +# 仅允许 @example.com 邮箱 +AUTH_ALLOWED_EMAILS=example.com + +# 允许多个域名和特定邮箱 +AUTH_ALLOWED_EMAILS=example.com,company.org,admin@other.com +``` + + + `AUTH_ALLOWED_EMAILS` 仅限制哪些邮箱可以注册，不会验证邮箱所有权。结合 `AUTH_EMAIL_VERIFICATION=1` + 可确保用户确实拥有其注册邮箱。 + + +## OAuth 快速配置示例 + +**Google OAuth：** + +1. 在 [Google Cloud Console](https://console.cloud.google.com/apis/credentials) 创建 OAuth 凭据 +2. 设置授权重定向 URI：`https://yourdomain.com/api/auth/callback/google` +3. 配置环境变量： + +```bash +AUTH_SSO_PROVIDERS=google +AUTH_GOOGLE_ID=xxxxx.apps.googleusercontent.com +AUTH_GOOGLE_SECRET=GOCSPX-xxxxxxxxxxxxxxxxxxxx +``` + +**GitHub OAuth：** + +1. 在 [GitHub 开发者设置](https://github.com/settings/developers) 创建 OAuth App +2. 设置回调 URL：`https://yourdomain.com/api/auth/callback/github` +3. 配置环境变量： + +```bash +AUTH_SSO_PROVIDERS=github +AUTH_GITHUB_ID=Ov23xxxxxxxxxxxxx +AUTH_GITHUB_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx +``` + ## 邮件服务配置 -邮件服务用于邮箱验证、密码重置和魔法链接发送。详细配置请参阅 [邮件服务配置](/zh/docs/self-hosting/auth/email)。 +邮件服务用于邮箱验证、密码重置和魔法链接发送。 + +**SMTP 配置：** + +```bash +SMTP_HOST=smtp.gmail.com # SMTP 服务器地址 +SMTP_PORT=587 # TLS 使用 587（推荐），SSL 使用 465 +SMTP_SECURE=false # port 465 时设为 true，port 587 时设为 false +SMTP_USER=your-email@gmail.com +SMTP_PASS=your-app-specific-password # Gmail 需使用应用专用密码 +SMTP_FROM=noreply@yourdomain.com # 可选，默认为 SMTP_USER +``` + +详细配置请参阅 [邮件服务配置](/zh/docs/self-hosting/auth/email)。 前往 [环境变量](/zh/docs/self-hosting/environment-variables/auth#better-auth) 可查阅所有 Better Auth 相关变量详情。 diff --git a/docs/self-hosting/auth/email.mdx b/docs/self-hosting/auth/email.mdx index b922ca5494..d752c94b8e 100644 --- a/docs/self-hosting/auth/email.mdx +++ b/docs/self-hosting/auth/email.mdx @@ -1,6 +1,8 @@ --- title: Email Service Configuration -description: Configure LobeHub email service for email verification, password reset, and magic link login. +description: >- + Configure LobeHub email service for email verification, password reset, and + magic link login. tags: - Email Service - SMTP diff --git a/docs/self-hosting/auth/next-auth/cloudflare-zero-trust.mdx b/docs/self-hosting/auth/next-auth/cloudflare-zero-trust.mdx index 2290273508..42ef30f3bb 100644 --- a/docs/self-hosting/auth/next-auth/cloudflare-zero-trust.mdx +++ b/docs/self-hosting/auth/next-auth/cloudflare-zero-trust.mdx @@ -23,25 +23,25 @@ tags: First, we need to visit `https://one.dash.cloudflare.com/` and navigate to `Access - Applications`. - ![image](/blog/assetsc74cf5c8daee1515c37a85bce087f0d6.webp) + ![Cloudflare Zero Trust Access - Applications](/blog/assetsc74cf5c8daee1515c37a85bce087f0d6.webp) Now, on the current page, click `Add an application` and select `SaaS`. - ![image](/blog/assetse717764a3618df4e56212e447a6c20cd.webp) + ![Add Application - Select SaaS](/blog/assetse717764a3618df4e56212e447a6c20cd.webp) In the `Application` text box, enter the application name, such as `LobeHub SSO`. Then click `Select OIDC`, followed by clicking `Add application`. - ![image](/blog/assets0ceb7e446f9a850df283093563ba7803.webp) + ![Add LobeHub SSO Application](/blog/assets0ceb7e446f9a850df283093563ba7803.webp) At this point, you have successfully created a SaaS application named `LobeHub SSO` in Cloudflare Zero Trust. Next, we need to enter `https://chat.example.com/api/auth/callback/cloudflare-zero-trust` in the `Redirect URLs` field (note that `chat.example.com` should be replaced with your instance's address). - ![image](/blog/assets4aaf8d5d092608b649230e0e6fc92df6.webp) + ![Configure Redirect URLs](/blog/assets4aaf8d5d092608b649230e0e6fc92df6.webp) Finally, scroll down the page and record the following three values: `Client secret`, `Client ID`, and `Issuer`. You will need these for setting the environment variables when deploying LobeHub. - ![image](/blog/assets66b0dfa56c1f5b3063b5ba740dd3ef8d.webp) + ![Client ID, Client Secret and Issuer](/blog/assets66b0dfa56c1f5b3063b5ba740dd3ef8d.webp) ### Configure Environment Variables diff --git a/docs/self-hosting/auth/next-auth/cloudflare-zero-trust.zh-CN.mdx b/docs/self-hosting/auth/next-auth/cloudflare-zero-trust.zh-CN.mdx index 33dd0b22d0..6d293ea367 100644 --- a/docs/self-hosting/auth/next-auth/cloudflare-zero-trust.zh-CN.mdx +++ b/docs/self-hosting/auth/next-auth/cloudflare-zero-trust.zh-CN.mdx @@ -22,23 +22,23 @@ tags: 首先我们需要访问 `https://one.dash.cloudflare.com/` 并前往 `Access - Applications` 中。 - ![image](/blog/assetsc74cf5c8daee1515c37a85bce087f0d6.webp) + ![Cloudflare Zero Trust 访问 - 应用程序](/blog/assetsc74cf5c8daee1515c37a85bce087f0d6.webp) 现在，在所在页面点击 `Add an application` 并选择 `SaaS`。 - ![image](/blog/assetse717764a3618df4e56212e447a6c20cd.webp) + ![添加应用 - 选择 SaaS](/blog/assetse717764a3618df4e56212e447a6c20cd.webp) 在 `Application` 文本框内填入应用名称，如：`LobeHub SSO`，然后点击 `Select OIDC` 后点击 `Add applicaiton` - ![image](/blog/assets0ceb7e446f9a850df283093563ba7803.webp) + ![添加 LobeHub SSO 应用](/blog/assets0ceb7e446f9a850df283093563ba7803.webp) 至此您已成功在 Clouflare Zero Trust 中创建了一个名为 `LobeHub SSO` 的 SaaS 应用。 - 接下来我们需要在 `Redirect URLs` 中填入 `https://chat.example.com/api/auth/callback/cloudflare-zero-trust`（注意此处的 `chat.example.com` 需要替换为您的实例地址） ![image](/blog/assets4aaf8d5d092608b649230e0e6fc92df6.webp) + 接下来我们需要在 `Redirect URLs` 中填入 `https://chat.example.com/api/auth/callback/cloudflare-zero-trust`（注意此处的 `chat.example.com` 需要替换为您的实例地址） ![配置重定向 URL](/blog/assets4aaf8d5d092608b649230e0e6fc92df6.webp) 最后我们将页面往下滚动，您将需要记录以下三个值 `Client secret`, `Client ID` 及 `Issuer` 以备后续部署 LobeHub 环境变量使用。 - ![image](/blog/assets66b0dfa56c1f5b3063b5ba740dd3ef8d.webp) + ![Client ID、Client Secret 和 Issuer](/blog/assets66b0dfa56c1f5b3063b5ba740dd3ef8d.webp) ### 配置环境变量 diff --git a/docs/self-hosting/auth/providers/auth0.mdx b/docs/self-hosting/auth/providers/auth0.mdx index 49caeaf3d4..f920abf9fd 100644 --- a/docs/self-hosting/auth/providers/auth0.mdx +++ b/docs/self-hosting/auth/providers/auth0.mdx @@ -1,8 +1,8 @@ --- title: Configuring Auth0 Authentication for LobeHub description: >- - Learn how to configure Auth0 SSO for LobeHub, including creating - applications, adding users, and setting up environment variables. + Learn how to configure Auth0 SSO for LobeHub, including creating applications, + adding users, and setting up environment variables. tags: - Auth0 - Authentication diff --git a/docs/self-hosting/auth/providers/authentik.mdx b/docs/self-hosting/auth/providers/authentik.mdx index 7085290a71..5a4cc3f6c4 100644 --- a/docs/self-hosting/auth/providers/authentik.mdx +++ b/docs/self-hosting/auth/providers/authentik.mdx @@ -1,8 +1,8 @@ --- title: Configuring Authentik Authentication for LobeHub description: >- - Learn how to configure Authentik SSO for LobeHub, including creating an - OAuth2 provider and application. + Learn how to configure Authentik SSO for LobeHub, including creating an OAuth2 + provider and application. tags: - Authentik - Authentication diff --git a/docs/self-hosting/auth/providers/okta.mdx b/docs/self-hosting/auth/providers/okta.mdx index 5d5890c488..cf8f7a8d20 100644 --- a/docs/self-hosting/auth/providers/okta.mdx +++ b/docs/self-hosting/auth/providers/okta.mdx @@ -1,8 +1,8 @@ --- title: Configuring Okta Authentication for LobeHub description: >- - Learn how to configure Okta SSO for LobeHub, including creating an - application and setting up environment variables. + Learn how to configure Okta SSO for LobeHub, including creating an application + and setting up environment variables. tags: - Okta - Authentication diff --git a/docs/self-hosting/environment-variables/auth.mdx b/docs/self-hosting/environment-variables/auth.mdx index 7cb6c2da8b..9299e2659c 100644 --- a/docs/self-hosting/environment-variables/auth.mdx +++ b/docs/self-hosting/environment-variables/auth.mdx @@ -2,8 +2,8 @@ title: LobeHub Authentication Service Environment Variables description: >- Explore the essential environment variables for configuring authentication - services in LobeHub, including Better Auth, OAuth SSO, and - provider-specific details. + services in LobeHub, including Better Auth, OAuth SSO, and provider-specific + details. tags: - Authentication Service - Better Auth diff --git a/docs/self-hosting/environment-variables/model-provider.mdx b/docs/self-hosting/environment-variables/model-provider.mdx index 1bc9aa10ab..99c975ba13 100644 --- a/docs/self-hosting/environment-variables/model-provider.mdx +++ b/docs/self-hosting/environment-variables/model-provider.mdx @@ -1,8 +1,9 @@ --- title: LobeHub Model Service Providers - Environment Variables and Configuration description: >- - Learn about the environment variables and configuration settings for various model service providers like OpenAI, Google AI, AWS Bedrock, Ollama, Perplexity AI, Anthropic AI, Mistral AI, Groq AI, OpenRouter AI, and 01.AI. - + Learn about the environment variables and configuration settings for various + model service providers like OpenAI, Google AI, AWS Bedrock, Ollama, + Perplexity AI, Anthropic AI, Mistral AI, Groq AI, OpenRouter AI, and 01.AI. tags: - Model Service Providers - Environment Variables diff --git a/docs/self-hosting/environment-variables/redis.mdx b/docs/self-hosting/environment-variables/redis.mdx index a40af85287..79ba9de1f4 100644 --- a/docs/self-hosting/environment-variables/redis.mdx +++ b/docs/self-hosting/environment-variables/redis.mdx @@ -1,6 +1,8 @@ --- title: Configure Redis Cache Service -description: Learn how to configure Redis cache service to optimize performance and session management. +description: >- + Learn how to configure Redis cache service to optimize performance and session + management. tags: - Redis - Cache diff --git a/docs/self-hosting/migration/v2/auth/clerk-to-betterauth.mdx b/docs/self-hosting/migration/v2/auth/clerk-to-betterauth.mdx index fac06f8668..7204ddf751 100644 --- a/docs/self-hosting/migration/v2/auth/clerk-to-betterauth.mdx +++ b/docs/self-hosting/migration/v2/auth/clerk-to-betterauth.mdx @@ -79,9 +79,9 @@ For small self-hosted deployments, the simplest approach is to let users reset t AUTH_GOOGLE_SECRET=your-google-client-secret ``` - - See [Authentication Service Configuration](/docs/self-hosting/auth) for complete environment variables and SSO provider setup. - + + See [Authentication Service Configuration](/docs/self-hosting/auth) for complete environment variables and SSO provider setup. + 3. **Redeploy LobeHub** diff --git a/docs/self-hosting/migration/v2/auth/clerk-to-betterauth.zh-CN.mdx b/docs/self-hosting/migration/v2/auth/clerk-to-betterauth.zh-CN.mdx index 7b873e4a07..b37d57056c 100644 --- a/docs/self-hosting/migration/v2/auth/clerk-to-betterauth.zh-CN.mdx +++ b/docs/self-hosting/migration/v2/auth/clerk-to-betterauth.zh-CN.mdx @@ -77,9 +77,9 @@ tags: AUTH_GOOGLE_SECRET=your-google-client-secret ``` - - 查阅 [身份验证服务配置](/zh/docs/self-hosting/auth) 了解完整的环境变量和 SSO 提供商配置。 - + + 查阅 [身份验证服务配置](/zh/docs/self-hosting/auth) 了解完整的环境变量和 SSO 提供商配置。 + 3. **重新部署 LobeHub** diff --git a/docs/self-hosting/migration/v2/auth/migration-internals.zh-CN.mdx b/docs/self-hosting/migration/v2/auth/migration-internals.zh-CN.mdx index 6715196c4c..ffe9867e2b 100644 --- a/docs/self-hosting/migration/v2/auth/migration-internals.zh-CN.mdx +++ b/docs/self-hosting/migration/v2/auth/migration-internals.zh-CN.mdx @@ -1,7 +1,6 @@ --- title: 认证迁移原理 - 技术深入解析 -description: >- - LobeHub 认证迁移的技术原理解析，包括数据库 Schema、迁移原理和问题排查指南。 +description: LobeHub 认证迁移的技术原理解析，包括数据库 Schema、迁移原理和问题排查指南。 tags: - 认证 - 迁移 diff --git a/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.mdx b/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.mdx index ccc7bf432f..cf8db3acfd 100644 --- a/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.mdx +++ b/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.mdx @@ -132,9 +132,9 @@ For small self-hosted deployments, the simplest approach is to let users re-logi AUTH_GOOGLE_SECRET=your-google-client-secret ``` - - See [Authentication Service Configuration](/docs/self-hosting/auth) for complete environment variables and SSO provider setup. - + + See [Authentication Service Configuration](/docs/self-hosting/auth) for complete environment variables and SSO provider setup. + 2. **Redeploy LobeHub** diff --git a/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.zh-CN.mdx b/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.zh-CN.mdx index e4b4225582..5a5a4f73c3 100644 --- a/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.zh-CN.mdx +++ b/docs/self-hosting/migration/v2/auth/nextauth-to-betterauth.zh-CN.mdx @@ -129,9 +129,9 @@ Better Auth 支持更多功能，以下是新增的环境变量： AUTH_GOOGLE_SECRET=your-google-client-secret ``` - - 查阅 [身份验证服务配置](/zh/docs/self-hosting/auth) 了解完整的环境变量和 SSO 提供商配置。 - + + 查阅 [身份验证服务配置](/zh/docs/self-hosting/auth) 了解完整的环境变量和 SSO 提供商配置。 + 2. **重新部署 LobeHub** diff --git a/docs/self-hosting/platform/docker-compose.mdx b/docs/self-hosting/platform/docker-compose.mdx index 69bb3729a0..8f2ca31482 100644 --- a/docs/self-hosting/platform/docker-compose.mdx +++ b/docs/self-hosting/platform/docker-compose.mdx @@ -348,6 +348,161 @@ If `INTERNAL_APP_URL` is not set, it defaults to `APP_URL`. For Docker Compose deployments with `network_mode: 'service:network-service'`, use `http://localhost:3210` as the `INTERNAL_APP_URL`. +## Reverse Proxy Configuration + +For production deployments with a custom domain and HTTPS, configure a reverse proxy in front of LobeHub. + +**Nginx:** + +```nginx +server { + listen 443 ssl http2; + server_name lobehub.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:3210; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_cache_bypass $http_upgrade; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} +``` + +**Caddy** (automatically handles HTTPS with Let's Encrypt): + +```caddyfile +lobehub.example.com { + reverse_proxy localhost:3210 +} +``` + +**Traefik** — add labels to the `lobe` service in `docker-compose.yml`: + +```yaml +labels: + - "traefik.enable=true" + - "traefik.http.routers.lobehub.rule=Host(`lobehub.example.com`)" + - "traefik.http.routers.lobehub.entrypoints=websecure" + - "traefik.http.routers.lobehub.tls.certresolver=letsencrypt" +``` + +## Management Commands + +```sh +# View logs (all services) +docker compose logs -f + +# View logs for a specific service +docker compose logs -f lobehub + +# Restart all services +docker compose restart + +# Restart a specific service +docker compose restart lobehub + +# Stop all services +docker compose stop + +# Update to the latest version +docker compose pull && docker compose up -d +``` + +## Backup and Restore + +**Database backup:** + +```sh +docker compose exec postgresql pg_dump -U postgres lobechat > backup.sql +``` + +Restore from backup: + +```sh +docker compose exec -T postgresql psql -U postgres lobechat < backup.sql +``` + +**File storage (RustFS) backup:** + +```sh +docker compose exec rustfs tar czf /tmp/backup.tar.gz /data +docker cp lobe-rustfs:/tmp/backup.tar.gz ./rustfs-backup.tar.gz +``` + +**Redis** — Redis automatically persists data with AOF. To manually save: + +```sh +docker compose exec redis redis-cli BGSAVE +``` + +## Resource Requirements + +**Minimum (light usage):** + +- CPU: 2 cores +- RAM: 4 GB +- Storage: 20 GB + +**Recommended (production):** + +- CPU: 4+ cores +- RAM: 8+ GB +- Storage: 50+ GB (depending on file uploads) + +For high-traffic deployments, consider using managed database (Neon, Supabase, RDS), Redis cluster for caching, and a CDN for static assets. + +## Troubleshooting + +**Service won't start** + +Check service status and logs: + +```sh +docker compose ps +docker compose logs [service-name] +``` + +Common causes: port already in use (change `LOBE_PORT` in `.env`), insufficient disk space, or database connection failure. + +**Database connection error** + +Verify PostgreSQL is healthy: + +```sh +docker compose exec postgresql pg_isready -U postgres +``` + +If unhealthy, check its logs: `docker compose logs postgresql` + +**File upload fails** + +Check RustFS service: + +```sh +docker compose logs rustfs +docker compose logs rustfs-init +``` + +Verify the bucket was created: `docker compose exec rustfs ls /data/lobe` + +**Running out of disk space** + +Check usage: `docker system df` + +Clean up unused resources (make sure to back up first): + +```sh +docker system prune -a --volumes +``` + ## Configuring Authentication To configure SSO authentication services (such as Casdoor, Logto, etc.), please refer to the [Authentication Services](/docs/self-hosting/auth) documentation. diff --git a/docs/self-hosting/platform/docker-compose.zh-CN.mdx b/docs/self-hosting/platform/docker-compose.zh-CN.mdx index 6d162adfaa..178f4e8fe4 100644 --- a/docs/self-hosting/platform/docker-compose.zh-CN.mdx +++ b/docs/self-hosting/platform/docker-compose.zh-CN.mdx @@ -344,6 +344,161 @@ environment: 对于使用 `network_mode: 'service:network-service'` 的 Docker Compose 部署，请使用 `http://localhost:3210` 作为 `INTERNAL_APP_URL`。 +## 反向代理配置 + +在生产环境中，如需使用自定义域名和 HTTPS，需在 LobeHub 前面配置反向代理。 + +**Nginx：** + +```nginx +server { + listen 443 ssl http2; + server_name lobehub.example.com; + + ssl_certificate /path/to/cert.pem; + ssl_certificate_key /path/to/key.pem; + + location / { + proxy_pass http://localhost:3210; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection 'upgrade'; + proxy_set_header Host $host; + proxy_cache_bypass $http_upgrade; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } +} +``` + +**Caddy**（自动通过 Let's Encrypt 处理 HTTPS）： + +```caddyfile +lobehub.example.com { + reverse_proxy localhost:3210 +} +``` + +**Traefik** — 在 `docker-compose.yml` 的 `lobe` 服务中添加标签： + +```yaml +labels: + - "traefik.enable=true" + - "traefik.http.routers.lobehub.rule=Host(`lobehub.example.com`)" + - "traefik.http.routers.lobehub.entrypoints=websecure" + - "traefik.http.routers.lobehub.tls.certresolver=letsencrypt" +``` + +## 管理命令 + +```sh +# 查看所有服务日志 +docker compose logs -f + +# 查看指定服务日志 +docker compose logs -f lobehub + +# 重启所有服务 +docker compose restart + +# 重启指定服务 +docker compose restart lobehub + +# 停止所有服务 +docker compose stop + +# 更新到最新版本 +docker compose pull && docker compose up -d +``` + +## 备份与恢复 + +**数据库备份：** + +```sh +docker compose exec postgresql pg_dump -U postgres lobechat > backup.sql +``` + +从备份恢复： + +```sh +docker compose exec -T postgresql psql -U postgres lobechat < backup.sql +``` + +**文件存储（RustFS）备份：** + +```sh +docker compose exec rustfs tar czf /tmp/backup.tar.gz /data +docker cp lobe-rustfs:/tmp/backup.tar.gz ./rustfs-backup.tar.gz +``` + +**Redis** — Redis 通过 AOF 自动持久化数据。手动保存： + +```sh +docker compose exec redis redis-cli BGSAVE +``` + +## 资源要求 + +**最低配置（轻量使用）：** + +- CPU：2 核 +- 内存：4 GB +- 存储：20 GB + +**推荐配置（生产环境）：** + +- CPU：4 核 + +- 内存：8 GB+ +- 存储：50 GB+（取决于文件上传量） + +对于高流量部署，建议使用托管数据库（Neon、Supabase、RDS）、Redis 集群以及 CDN 加速静态资源。 + +## 故障排查 + +**服务无法启动** + +检查服务状态和日志： + +```sh +docker compose ps +docker compose logs [service-name] +``` + +常见原因：端口被占用（在 `.env` 中修改 `LOBE_PORT`）、磁盘空间不足、数据库连接失败。 + +**数据库连接错误** + +检查 PostgreSQL 是否健康： + +```sh +docker compose exec postgresql pg_isready -U postgres +``` + +如果不健康，查看日志：`docker compose logs postgresql` + +**文件上传失败** + +检查 RustFS 服务： + +```sh +docker compose logs rustfs +docker compose logs rustfs-init +``` + +确认 bucket 是否已创建：`docker compose exec rustfs ls /data/lobe` + +**磁盘空间不足** + +检查使用情况：`docker system df` + +清理未使用的资源（请先做好备份）： + +```sh +docker system prune -a --volumes +``` + ## 配置身份验证 如需配置 SSO 登录鉴权服务（如 Casdoor、Logto 等），请参考 [身份验证服务](/zh/docs/self-hosting/auth) 文档。 diff --git a/docs/self-hosting/platform/dokploy.mdx b/docs/self-hosting/platform/dokploy.mdx index 60b8ac9a61..8f61cc8161 100644 --- a/docs/self-hosting/platform/dokploy.mdx +++ b/docs/self-hosting/platform/dokploy.mdx @@ -24,11 +24,11 @@ curl -sSL https://dokploy.com/install.sh | sh 1. Connect your GitHub to Dokploy in the Settings / Git section according to the prompt. -![](/blog/assets0f97d1dfccd5ba07172aff71ff9acd7b.webp) +![Connect GitHub to Dokploy](/blog/assets0f97d1dfccd5ba07172aff71ff9acd7b.webp) 2. Enter the Projects interface to create a Project. -![](/blog/assetsb26b68a4875a6510ddc202dd4b40d010.webp) +![Create Project in Dokploy](/blog/assetsb26b68a4875a6510ddc202dd4b40d010.webp) ### Configure S3 Storage Service @@ -68,7 +68,7 @@ You also need to configure the `JWKS_KEY` environment variable for signing and v Enter the previously created Project, click on Create Service, and select Database. In the Database interface, choose PostgreSQL, then set the database name, user, and password. In the Docker image field, enter `paradedb/paradedb:latest-pg17`, and finally click Create to create the database. -![](/blog/assets7006b60baaf62aa0d95cd40456e24afe.webp) +![Create PostgreSQL Database in Dokploy](/blog/assets7006b60baaf62aa0d95cd40456e24afe.webp) Enter the created database and set an unused port in External Credentials to allow external access; otherwise, LobeHub will not be able to connect to the database. You can view the Postgres database connection URL in External Host, as shown below: @@ -78,21 +78,21 @@ postgresql://postgres:wAbLxfXSwkxxxxxx@45.577.281.48:5432/postgres Finally, click Deploy to deploy the database. -![](/blog/assets1b9283f9cc5fc5073ff9cffc24880e96.webp) +![Deploy Database in Dokploy](/blog/assets1b9283f9cc5fc5073ff9cffc24880e96.webp) ## Deploy LobeHub on Dokploy. Click "Create Service", select "Application", and create the LobeHub application. -![](/blog/assetsb33085e7553d2b7194005b102184553e.webp) +![Create LobeHub Application in Dokploy](/blog/assetsb33085e7553d2b7194005b102184553e.webp) Enter the created LobeHub application, select the forked lobe-chat project and branch, and click Save to save. -![](/blog/assetsf0ebf396dbe9559eb3478f48f648a6e2.webp) +![Select Repository and Branch in Dokploy](/blog/assetsf0ebf396dbe9559eb3478f48f648a6e2.webp) Switch to the Environment section, fill in the environment variables, and click Save. -![](/blog/assets6b67dabe7b9226cdff1bace5a3b8ab18.webp) +![Configure Environment Variables in Dokploy](/blog/assets6b67dabe7b9226cdff1bace5a3b8ab18.webp) ```shell # Environment variables required for building @@ -123,14 +123,14 @@ S3_ENABLE_PATH_STYLE= After adding the environment variables and saving, click Deploy to initiate the deployment. You can check the deployment progress and log information under Deployments. -![](/blog/assets7c3eab218c0823fa353b1cd23afe21c3.webp) +![Deploy LobeHub and View Progress](/blog/assets7c3eab218c0823fa353b1cd23afe21c3.webp) After a successful deployment, bind your own domain to your LobeHub application and request a certificate on the Domains page. -![](/blog/assetseebf66254337ce88357629c34e78c08d.webp) +![Bind Domain and Request Certificate](/blog/assetseebf66254337ce88357629c34e78c08d.webp) ## Check if LobeHub is working properly. Go to your LobeHub website, and if you click on the login button in the upper left corner and the login pop-up appears normally, it means you have configured it successfully. Enjoy it to the fullest! -![](/blog/assets11a8089b511aaa61e8982dea0a3665c5.webp) +![LobeHub Login Success](/blog/assets11a8089b511aaa61e8982dea0a3665c5.webp) diff --git a/docs/self-hosting/platform/dokploy.zh-CN.mdx b/docs/self-hosting/platform/dokploy.zh-CN.mdx index c10e98e069..8900e02f62 100644 --- a/docs/self-hosting/platform/dokploy.zh-CN.mdx +++ b/docs/self-hosting/platform/dokploy.zh-CN.mdx @@ -25,11 +25,11 @@ curl -sSL https://dokploy.com/install.sh | sh 1. 在 Dokploy 的 Settings / Git 处根据提示将 Github 绑定到 Dokploy -![](/blog/assets0f97d1dfccd5ba07172aff71ff9acd7b.webp) +![将 GitHub 绑定到 Dokploy](/blog/assets0f97d1dfccd5ba07172aff71ff9acd7b.webp) 2. 进入 Projects 界面创建一个 Project -![](/blog/assetsb26b68a4875a6510ddc202dd4b40d010.webp) +![在 Dokploy 中创建项目](/blog/assetsb26b68a4875a6510ddc202dd4b40d010.webp) ### 配置 S3 存储服务 @@ -69,7 +69,7 @@ S3_ENABLE_PATH_STYLE= 进入前面创建的 Project，点击 Create Service 选择 Database，在 Database 界面选择 PostgreSQL ，然后设置数据库名、用户、密码，在 Docker image 中填入 `paradedb/paradedb:latest-pg17` 最后点击 Create 创建数据库。 -![](/blog/assets7006b60baaf62aa0d95cd40456e24afe.webp) +![在 Dokploy 中创建 PostgreSQL 数据库](/blog/assets7006b60baaf62aa0d95cd40456e24afe.webp) 进入创建的数据库，在 External Credentials 设置一个未被占用的端口，使其能能通过外部访问，否则 LobeHub 将无法连接到该数据库。你可以在 External Host 查看 Postgres 数据库连接 URL ，如下： @@ -79,21 +79,21 @@ postgresql://postgres:wAbLxfXSwkxxxxxx@45.577.281.48:5432/postgres 最后点击 Deploy 部署数据库 -![](/blog/assets1b9283f9cc5fc5073ff9cffc24880e96.webp) +![在 Dokploy 中部署数据库](/blog/assets1b9283f9cc5fc5073ff9cffc24880e96.webp) ## 在 Dokploy 上部署 LobeHub 点击 Create Service 选择 Application，创建 LobeHub 应用 -![](/blog/assetsb33085e7553d2b7194005b102184553e.webp) +![在 Dokploy 中创建 LobeHub 应用](/blog/assetsb33085e7553d2b7194005b102184553e.webp) 进入创建的 LobeHub 应用，选择你 fork 的 lobe-chat 项目及分支，点击 Save 保存 -![](/blog/assetsf0ebf396dbe9559eb3478f48f648a6e2.webp) +![在 Dokploy 中选择仓库和分支](/blog/assetsf0ebf396dbe9559eb3478f48f648a6e2.webp) 切换到 Environment ，在其中填入环境变量，点击保存。 -![](/blog/assets6b67dabe7b9226cdff1bace5a3b8ab18.webp) +![在 Dokploy 中配置环境变量](/blog/assets6b67dabe7b9226cdff1bace5a3b8ab18.webp) ```shell # 构建所必需的环境变量 @@ -124,14 +124,14 @@ S3_ENABLE_PATH_STYLE= 添加完环境变量并保存后，点击 Deploy 进行部署，你可以在 Deployments 处查看部署进程及日志信息 -![](/blog/assets7c3eab218c0823fa353b1cd23afe21c3.webp) +![部署 LobeHub 并查看进度](/blog/assets7c3eab218c0823fa353b1cd23afe21c3.webp) 部署成功后在 Domains 页面，为你的 LobeHub 应用绑定自己的域名并申请证书。 -![](/blog/assetseebf66254337ce88357629c34e78c08d.webp) +![绑定域名并申请证书](/blog/assetseebf66254337ce88357629c34e78c08d.webp) ## 验证 LobeHub 是否正常工作 进入你的 LobeHub 网址，如果你点击左上角登录，可以正常显示登录弹窗，那么说明你已经配置成功了，尽情享用吧～ -![](/blog/assets11a8089b511aaa61e8982dea0a3665c5.webp) +![LobeHub 登录成功](/blog/assets11a8089b511aaa61e8982dea0a3665c5.webp) diff --git a/docs/self-hosting/platform/vercel.mdx b/docs/self-hosting/platform/vercel.mdx index bbff609cc7..6a2ff6445d 100644 --- a/docs/self-hosting/platform/vercel.mdx +++ b/docs/self-hosting/platform/vercel.mdx @@ -257,6 +257,56 @@ After completing the steps above, the configuration of the server-side database {'Login +## Platform Limitations + + + Be aware of these Vercel platform limitations before deploying. + + +**Serverless function timeout:** + +| Plan | Timeout | +| ---------- | ----------- | +| Hobby | 10 seconds | +| Pro | 60 seconds | +| Enterprise | 900 seconds | + +Long-running AI requests may timeout on the Hobby plan. Streaming responses (enabled by default) help keep connections alive. + +**No WebSocket support** — Vercel serverless functions don't support persistent WebSocket connections. Real-time features use Server-Sent Events (SSE) instead. + +**Cold starts** — Serverless functions may be slower on first request after idle periods (1–3 seconds). This is normal behavior for serverless platforms. + +**File size limits** — Deployment size: 250 MB (compressed). Function size: 50 MB. + +## Keeping Updated + + + If you used the one-click deploy button, Vercel creates a **new** repository instead of forking the original. This prevents automatic upstream updates. + + +To receive future LobeHub updates: + +1. **Delete** the current project from Vercel dashboard (Settings → Delete Project) +2. Manually **fork** [lobehub/lobe-chat](https://github.com/lobehub/lobe-chat) on GitHub +3. **Import** your forked repository to Vercel (Add New → Project) +4. Re-configure your environment variables and deploy +5. In your fork's GitHub **Actions** tab, enable the `upstream-sync` workflow — it automatically checks for updates daily + +To sync manually: Actions → Upstream Sync → Run workflow. + +## Troubleshooting + +**Deployment fails** — Check build logs in Vercel Dashboard → Deployments → click the failed deployment → Build Logs. Common causes: missing environment variables, TypeScript errors, or out of memory (fix with `NODE_OPTIONS=--max-old-space-size=4096`). + +**Function timeout** — If requests timeout on Hobby plan: upgrade to Pro (60s timeout), use faster AI models (e.g., GPT-4o-mini instead of GPT-4o), reduce max tokens, or ensure streaming is enabled. + +**Database connection fails** — Verify `DATABASE_URL` format. Ensure `?sslmode=require` is appended for managed databases. Check that the database's IP allowlist includes Vercel IPs (or use `0.0.0.0/0` for open access). Test locally with `psql "$DATABASE_URL"`. + +**502 Bad Gateway** — Common causes: function timeout, out of memory, or database connection pool exhausted. Use a connection pooler (PgBouncer), reduce concurrent connections, or check database logs. + +**Environment variables not updating** — After changing env vars, go to Deployments → Redeploy (three dots menu) → select "Use existing Build Cache: No". + ## Appendix ### Overview of Server-side Database Environment Variables diff --git a/docs/self-hosting/platform/vercel.zh-CN.mdx b/docs/self-hosting/platform/vercel.zh-CN.mdx index c73db155ae..a991b4d1b5 100644 --- a/docs/self-hosting/platform/vercel.zh-CN.mdx +++ b/docs/self-hosting/platform/vercel.zh-CN.mdx @@ -252,6 +252,56 @@ tags: {'登录成功状态'} +## 平台限制 + + + 部署前请了解 Vercel 平台的以下限制。 + + +**Serverless 函数超时：** + +| 套餐 | 超时时间 | +| ---------- | ----- | +| Hobby | 10 秒 | +| Pro | 60 秒 | +| Enterprise | 900 秒 | + +在 Hobby 套餐上，长时间运行的 AI 请求可能会超时。默认启用的流式响应有助于保持连接活跃。 + +**不支持 WebSocket** — Vercel Serverless 函数不支持持久 WebSocket 连接，实时功能使用服务端发送事件（SSE）代替。 + +**冷启动** — Serverless 函数在空闲后的首次请求可能较慢（1–3 秒），这是 Serverless 平台的正常行为。 + +**文件大小限制** — 部署包：250 MB（压缩后）；函数包：50 MB。 + +## 保持版本更新 + + + 如果你使用了一键部署按钮，Vercel 会创建一个**全新的**仓库，而非 Fork 原始仓库。这会导致无法自动同步上游更新。 + + +若要接收 LobeHub 的后续更新： + +1. 在 Vercel 控制台**删除**当前项目（设置 → 删除项目） +2. 在 GitHub 上手动 **Fork** [lobehub/lobe-chat](https://github.com/lobehub/lobe-chat) +3. 将 Fork 后的仓库**导入**到 Vercel（新增项目 → 导入） +4. 重新配置环境变量并部署 +5. 在 Fork 仓库的 GitHub **Actions** 标签页，启用 `upstream-sync` 工作流 —— 它会每日自动检查上游更新 + +手动同步：Actions → Upstream Sync → Run workflow。 + +## 故障排查 + +**部署失败** — 在 Vercel 控制台 → 部署记录 → 点击失败的部署 → 构建日志中查看详情。常见原因：环境变量缺失、TypeScript 报错、内存不足（通过 `NODE_OPTIONS=--max-old-space-size=4096` 修复）。 + +**函数超时** — 在 Hobby 套餐遇到超时时：升级到 Pro（60 秒超时）、使用更快的模型（如 GPT-4o-mini 代替 GPT-4o）、减少最大 token 数，或确认已启用流式响应。 + +**数据库连接失败** — 检查 `DATABASE_URL` 格式。对于托管数据库，确保末尾追加了 `?sslmode=require`。检查数据库 IP 白名单是否包含 Vercel IP（或使用 `0.0.0.0/0` 开放访问）。本地测试：`psql "$DATABASE_URL"`。 + +**502 网关错误** — 常见原因：函数超时、内存溢出、数据库连接池耗尽。使用连接池（PgBouncer）、减少并发连接数或查看数据库日志。 + +**环境变量修改后未生效** — 在部署记录中点击某次部署的三点菜单 → 重新部署，选择 "不使用现有构建缓存"。 + ## 附录 ### 服务端数据库环境变量一览 diff --git a/docs/self-hosting/start.mdx b/docs/self-hosting/start.mdx index bcc51a68f4..e3f1381d22 100644 --- a/docs/self-hosting/start.mdx +++ b/docs/self-hosting/start.mdx @@ -14,6 +14,138 @@ tags: # Build Your Own LobeHub -LobeHub supports various deployment platforms, including Vercel, Docker, and Docker Compose. You can choose a deployment platform that suits you to build your own LobeHub. +LobeHub can be self-hosted on your own infrastructure, giving you complete control over your data, customization, and deployment environment. Whether you're deploying for a team, organization, or personal use, LobeHub supports multiple deployment methods. + +## Architecture Overview + +LobeHub consists of several key components: + +### Core Services + +- **Next.js application** — Hybrid SSR/SPA frontend with API routes +- **PostgreSQL database** — Stores conversations, agents, files, and user data +- **Redis** (optional) — Session storage and caching +- **S3-compatible storage** — File uploads and knowledge base documents + +### Optional Services + +- **RustFS / MinIO** — Self-hosted S3-compatible storage +- **Langfuse** — LLM observability and tracing +- **OpenTelemetry** — Distributed tracing +- **Searxng** — Privacy-focused web search + +## Choosing a Deployment Method + +### Docker Compose (Recommended) + +**Best for:** Self-hosted installations, full infrastructure control, team deployments. + +**Pros:** + +- Complete stack in one command +- Easy updates with `docker compose pull` +- Includes PostgreSQL, Redis, RustFS, Searxng +- Full feature support — no timeout limits, WebSocket support + +**Cons:** + +- Requires server management +- Need to handle backups and monitoring + +### Vercel + +**Best for:** Quick deployments, serverless scaling, low maintenance. + +**Pros:** + +- One-click deployment +- Automatic HTTPS and CDN +- Scales automatically +- Free tier available + +**Cons:** + +- Requires an external PostgreSQL database +- 10-second serverless function timeout limit +- No WebSocket support +- Less control over infrastructure + +### Cloud Platforms (Zeabur, Sealos, Dokploy) + +Similar to Vercel with regional options. Good for specific geographic requirements with various pricing and feature differences. + +## Feature Comparison + +| Feature | Docker | Vercel | Cloud Platforms | +| ----------------- | ------------ | ----------- | --------------- | +| Full control | ✅ | ❌ | ⚠️ | +| Custom domain | ✅ | ✅ | ✅ | +| One-click deploy | ❌ | ✅ | ✅ | +| Auto-scaling | ❌ | ✅ | ✅ | +| Free tier | ✅ | ✅ | Varies | +| Function timeout | Unlimited | 10s | Varies | +| WebSocket support | ✅ | ❌ | Varies | +| File storage | Local/RustFS | External S3 | Varies | +| Database | Included | External | Varies | + +## Prerequisites + +Before deploying LobeHub, gather the following: + +### Required + +**AI provider API keys** — At minimum, you need an API key from one AI provider: + +- **OpenAI** — `OPENAI_API_KEY` from [platform.openai.com](https://platform.openai.com/account/api-keys) +- **Anthropic** — `ANTHROPIC_API_KEY` from [console.anthropic.com](https://console.anthropic.com/) +- **Google** — `GOOGLE_API_KEY` from [aistudio.google.com](https://aistudio.google.com/app/apikey) + +See [AI Provider Configuration](/docs/self-hosting/environment-variables/model-provider) for the full list of supported providers. + +**Database (for server deployment)** — PostgreSQL 14+ is required: + +- **Managed options**: Neon, Supabase, Railway, Vercel Postgres +- **Self-hosted**: Docker (included in Docker Compose), AWS RDS, Google Cloud SQL + +### Optional but Recommended + +**Redis** — Improves performance for session storage, rate limiting, and caching. Use Upstash, Redis Cloud, or self-hosted Redis. + +**S3-compatible storage** — Required for file uploads and knowledge bases: + +- **AWS S3** — Production-ready, scalable +- **Cloudflare R2** — No egress fees +- **RustFS / MinIO** — Self-hosted S3 alternative (included in Docker Compose) + +**Authentication provider** — For SSO and team features (Google OAuth, GitHub OAuth, Microsoft Azure AD, Auth0, Keycloak). See [Authentication Setup](/docs/self-hosting/auth) for configuration. + +## Security Considerations + + + Never commit API keys or secrets to version control. Always use environment variables. + + +Essential security measures: + +1. **Use HTTPS** — Always deploy with SSL/TLS certificates +2. **Secure your database** — Use strong passwords and restrict network access +3. **Environment variables** — Store secrets securely (never in code) +4. **Authentication** — Enable Better Auth for multi-user deployments +5. **Regular updates** — Keep LobeHub and dependencies up to date + +Authentication options: + +- **Open access** — No authentication (single-user deployments only) +- **Better Auth** — Built-in auth with email/password, OAuth, magic links +- **Reverse proxy** — Use Authelia, Authentik, or similar + +## Next Steps + +1. **Choose your deployment method** — Docker for maximum control or Vercel for simplicity +2. **Gather API keys** — Obtain API keys from your chosen AI providers +3. **Set up infrastructure** — Provision database, Redis, and storage as needed +4. **Configure environment variables** — See the [environment variable reference](/docs/self-hosting/environment-variables) +5. **Deploy** — Follow the platform-specific guide above +6. **Configure authentication** — Set up [Better Auth](/docs/self-hosting/auth) for multi-user access diff --git a/docs/self-hosting/start.zh-CN.mdx b/docs/self-hosting/start.zh-CN.mdx index bd37a625ee..41370cbe37 100644 --- a/docs/self-hosting/start.zh-CN.mdx +++ b/docs/self-hosting/start.zh-CN.mdx @@ -18,6 +18,138 @@ tags: # 构建属于自己的 LobeHub -LobeHub 支持多种部署平台，包括 Vercel、Docker、 Docker Compose 、阿里云计算巢 和腾讯轻量云 等，你可以选择适合自己的部署平台进行部署，构建属于自己的 LobeHub。 +LobeHub 支持私有化部署，让你完全掌控自己的数据、自定义选项和部署环境。无论是为团队、组织还是个人使用，LobeHub 都提供多种部署方式。 + +## 架构概述 + +LobeHub 由以下几个关键组件组成： + +### 核心服务 + +- **Next.js 应用** — 混合 SSR/SPA 前端，包含 API 路由 +- **PostgreSQL 数据库** — 存储对话、Agent、文件和用户数据 +- **Redis**（可选）— 会话存储与缓存 +- **S3 兼容存储** — 文件上传和知识库文档 + +### 可选服务 + +- **RustFS / MinIO** — 自托管的 S3 兼容存储 +- **Langfuse** — LLM 可观测性与追踪 +- **OpenTelemetry** — 分布式追踪 +- **Searxng** — 注重隐私的网络搜索 + +## 选择部署方式 + +### Docker Compose（推荐） + +**适用场景：** 私有化部署、完整基础设施控制、团队使用。 + +**优点：** + +- 一条命令启动完整服务栈 +- 通过 `docker compose pull` 轻松更新 +- 内置 PostgreSQL、Redis、RustFS、Searxng +- 功能完整 — 无超时限制，支持 WebSocket + +**缺点：** + +- 需要管理服务器 +- 需要自行处理备份与监控 + +### Vercel + +**适用场景：** 快速部署、Serverless 弹性伸缩、低运维成本。 + +**优点：** + +- 一键部署 +- 自动 HTTPS 与 CDN +- 自动弹性伸缩 +- 提供免费套餐 + +**缺点：** + +- 需要外部 PostgreSQL 数据库 +- Serverless 函数 10 秒超时限制 +- 不支持 WebSocket +- 对基础设施控制有限 + +### 云平台（Zeabur、Sealos、Dokploy） + +与 Vercel 类似，提供区域化部署选项。适合有特定地理位置要求的场景，各平台在定价和功能上有所不同。 + +## 功能对比 + +| 功能 | Docker | Vercel | 云平台 | +| ------------ | ----------- | ------ | --- | +| 完整控制 | ✅ | ❌ | ⚠️ | +| 自定义域名 | ✅ | ✅ | ✅ | +| 一键部署 | ❌ | ✅ | ✅ | +| 自动扩缩容 | ❌ | ✅ | ✅ | +| 免费套餐 | ✅ | ✅ | 不一 | +| 函数超时 | 无限制 | 10 秒 | 不一 | +| WebSocket 支持 | ✅ | ❌ | 不一 | +| 文件存储 | 本地 / RustFS | 外部 S3 | 不一 | +| 数据库 | 已内置 | 外部 | 不一 | + +## 前置条件 + +部署 LobeHub 前，请准备以下内容： + +### 必需 + +**AI 提供商 API Key** — 至少需要一个 AI 提供商的 API Key： + +- **OpenAI** — 在 [platform.openai.com](https://platform.openai.com/account/api-keys) 获取 `OPENAI_API_KEY` +- **Anthropic** — 在 [console.anthropic.com](https://console.anthropic.com/) 获取 `ANTHROPIC_API_KEY` +- **Google** — 在 [aistudio.google.com](https://aistudio.google.com/app/apikey) 获取 `GOOGLE_API_KEY` + +完整支持的提供商列表请参见 [AI 提供商配置](/docs/self-hosting/environment-variables/model-provider)。 + +**数据库（服务端部署必需）** — 需要 PostgreSQL 14+： + +- **托管选项**：Neon、Supabase、Railway、Vercel Postgres +- **自托管**：Docker（Docker Compose 已内置）、AWS RDS、Google Cloud SQL + +### 可选但推荐 + +**Redis** — 提升会话存储、限流和缓存性能。可使用 Upstash、Redis Cloud 或自托管 Redis。 + +**S3 兼容存储** — 文件上传和知识库功能所需： + +- **AWS S3** — 生产就绪，可扩展 +- **Cloudflare R2** — 无出口流量费用 +- **RustFS / MinIO** — 自托管 S3 替代方案（Docker Compose 已内置） + +**认证提供商** — 支持 SSO 和团队功能（Google OAuth、GitHub OAuth、Microsoft Azure AD、Auth0、Keycloak）。配置详见 [认证设置](/docs/self-hosting/auth)。 + +## 安全注意事项 + + + 切勿将 API Key 或密钥提交到版本控制系统。请始终使用环境变量管理敏感信息。 + + +基本安全措施： + +1. **使用 HTTPS** — 始终通过 SSL/TLS 证书部署 +2. **保护数据库** — 使用强密码并限制网络访问 +3. **环境变量** — 安全存储密钥（绝不写入代码） +4. **认证** — 多用户部署时启用 Better Auth +5. **定期更新** — 保持 LobeHub 及依赖项的版本最新 + +认证选项： + +- **开放访问** — 不需要认证（仅适合单用户部署） +- **Better Auth** — 内置认证，支持邮箱密码、OAuth、Magic Links +- **反向代理** — 使用 Authelia、Authentik 等 + +## 下一步 + +1. **选择部署方式** — 追求最大控制力选 Docker，追求简便选 Vercel +2. **获取 API Key** — 向你选择的 AI 提供商申请 API Key +3. **配置基础设施** — 按需准备数据库、Redis 和存储 +4. **配置环境变量** — 参见 [环境变量参考](/docs/self-hosting/environment-variables) +5. **部署** — 按照上方对应平台的指南操作 +6. **配置认证** — 多用户场景下配置 [Better Auth](/docs/self-hosting/auth) diff --git a/docs/usage/agent/agent-team.mdx b/docs/usage/agent/agent-team.mdx index e94b21d17a..c327c4dbf1 100644 --- a/docs/usage/agent/agent-team.mdx +++ b/docs/usage/agent/agent-team.mdx @@ -1,66 +1,141 @@ --- -title: Agent Teams +title: Agent Groups description: >- - Simple centralized configuration for prompts, model selection, knowledge - bases, plugins, and more. + Bring multiple specialized Agents together to collaborate — sequential, + parallel, iterative, or debate mode. tags: - LobeHub - - LobeHub - - AI Assistant - - Assistant Organization - - Group Settings - - Assistant Search - - Assistant Pinning + - Agent Group + - Multi-Agent Collaboration + - Group Chat + - Moderator + - Sequential Mode + - Parallel Mode --- -# Agent Teams +# Agent Groups -Sometimes, one assistant's perspective just isn't enough. Complex problems require multifaceted thinking, creative projects thrive on diverse expertise, and learning discussions benefit from multiple viewpoints. Agent Group Chat brings together multiple specialized assistants to collaborate just like in a real group chat — a translation assistant, a coding assistant, and a product manager assistant sitting around the table, each contributing their strengths to solve your problem. You're not just getting an answer — you're engaging in a conversation. Here, different perspectives collide, expertise complements one another, and the insights generated through AI collaboration go far beyond what a single assistant can offer. +One Agent's perspective is rarely enough. Complex problems need multiple angles; creative projects thrive on diverse expertise; decisions benefit from structured debate. Agent Group Chat assembles a team of specialized Agents that work together like a real group — a research Agent, an analysis Agent, and a writing Agent each contributing their strengths to your task. You're not just getting an answer; you're running a coordinated process. -Agent Group Chat is a collaborative space for multiple specialized assistants. You pose a question or task, and each assistant offers insights from their area of expertise. They can discuss, supplement, and even debate with one another. +Pose a question or task, and each Agent responds from its area of expertise. They can build on each other's outputs, challenge assumptions, or work in parallel — depending on the mode you choose. -## Limitations of a Single Assistant +## Why Not Just One Agent? -- Can only analyze problems from one perspective -- Expertise is limited to its predefined role -- Lacks the richness of diverse viewpoints +- A single Agent can only analyze from one perspective +- Expertise is bounded by a single predefined role +- There's no back-and-forth to surface blind spots or trade-offs -## Advantages of Agent Group Chat +Agent Groups fix all three. -- Multiple assistants contribute their strengths and collaborate -- Diverse professional backgrounds lead to comprehensive solutions -- Discussions among assistants spark deeper insights -- A built-in moderator ensures orderly and focused conversations +## Collaboration Modes + +Agent Groups adapt to the task: + +**Sequential** — Agents work one after another in a defined order. Example: Research Agent gathers information → Analysis Agent processes data → Writing Agent creates the final document. Best for linear workflows with clear handoff points. + +**Parallel** — Multiple Agents tackle different aspects simultaneously. Example: Marketing Agent writes copy while Data Agent compiles metrics. Best for independent subtasks. + +**Iterative** — Agents review and refine work through multiple rounds. Example: Writer creates draft → Editor provides feedback → Writer revises → Editor does final review. Best for high-quality output that requires polish. + +**Debate** — Agents argue different positions. An advocate makes the case, a critic challenges assumptions, an analyst weighs evidence, and a mediator synthesizes conclusions. Best for complex decisions that benefit from structured disagreement. ## About the Moderator -Every Agent Group Chat includes a built-in moderator responsible for: +Every Agent Group includes a built-in moderator responsible for: -- Understanding your needs and assigning discussion tasks -- Coordinating the speaking order of assistants +- Understanding your goal and assigning tasks to the right Agents +- Coordinating the order of contributions - Summarizing the discussion and extracting key conclusions - Keeping the conversation organized and on-topic -## Creating an Agent Group Chat +## Create an Agent Group -Click "Create Group" in the left sidebar to get started. +Click **Create Group** in the left sidebar to get started. -![clipboard-1768907980491-9cc0669fc3a38.png](/blog/assets8be3a46c8f9c5d3b61bc541f44b7f245.webp) +![Create Agent Group](/blog/assets8be3a46c8f9c5d3b61bc541f44b7f245.webp) -When creating a group chat, you can use existing templates or assemble your own team of AI assistants. You can also choose whether to include a moderator and select the model for the moderator. +When creating a group, you can start from an existing template or assemble your own team. Choose whether to include a moderator and select the model for it. -![clipboard-1768908081787-ed9eb1cb78bdb.png](/blog/assetsab009b79dd794f02aec24b7607f342e8.webp) +![Agent Group Creation — Templates or Custom Team](/blog/assetsab009b79dd794f02aec24b7607f342e8.webp) -## Configuring an Agent Group Chat +## Configure an Agent Group -In the group chat session, use the left sidebar to select an assistant. You can easily switch their model or remove them from the group. +In the group chat session, select an Agent in the left sidebar to swap its model or remove it from the group. -![clipboard-1768908121691-b3517bf882633.png](/blog/assetsd3cae44cba0d3f57df6440b46246e5e7.webp) +![Select Agent in Group Chat](/blog/assetsd3cae44cba0d3f57df6440b46246e5e7.webp) -Also in the left sidebar, click the "Add Member" button to bring additional assistants into the group chat. +Click **Add Member** in the left sidebar to bring additional Agents into the group. -![clipboard-1768908209289-9d3ecff50142f.png](/blog/assets75a5cf08b3e432d2477899d30acc9d47.webp) +![Add Member to Agent Group](/blog/assets75a5cf08b3e432d2477899d30acc9d47.webp) -Go to "Group Profile" in the left sidebar to edit the group prompt, add plugins, or change the moderator model. You can also use the Agent Builder on the right panel for intelligent group creation. Agent Builder is LobeHub’s built-in assistant — simply chat with it, describe your needs, and it will automatically generate a complete group chat configuration, including group settings, system prompts, and plugin setup. +Go to **Group Profile** in the left sidebar to edit the group prompt, add Skills, or change the moderator model. You can also use Agent Builder on the right panel — describe your goal and it will generate the complete group configuration, including settings, system prompts, and Skill setup. -![clipboard-1768908230723-3fce0ae5baf9b.png](/blog/assets8e9b164fa30c795850ce8fa8ef7e7c24.webp) +![Agent Group Profile Settings](/blog/assets8e9b164fa30c795850ce8fa8ef7e7c24.webp) + +## Example Agent Groups + +### Content Creation Team + +A sequential workflow for producing blog posts or articles: + +1. **Researcher** — Gathers information, credible sources, statistics, and expert quotes +2. **Writer** — Writes an engaging draft using the research material +3. **Editor** — Reviews and refines for clarity, flow, and consistency +4. **SEO Specialist** — Optimizes keywords, headings, and meta description + +### Research Analysis Team + +1. **Data Collector** — Gathers data from multiple sources and documents +2. **Statistician** — Analyzes data, calculates metrics, identifies patterns +3. **Domain Expert** — Interprets findings in the context of industry knowledge +4. **Report Writer** — Synthesizes insights into an executive summary + +### Software Development Team + +- **Requirements Agent** — Gathers needs and writes product requirements documents +- **Technical Architect** — Designs system architecture and technical specifications +- **Developer** — Writes implementation code and technical documentation +- **QA Tester** — Reviews code, suggests test cases, identifies edge cases + +## Best Practices + +**Define clear roles** — Each Agent should have a specific, well-defined responsibility: + +- ❌ Vague: "Agent 1: Help with content" +- ✅ Clear: "Research Agent: Find 3–5 credible sources on the topic and summarize key points. Include statistics and expert quotes." + +**Avoid redundancy** — Don't create multiple Agents with overlapping roles. Each Agent should bring unique value. + +**Set clear handoff points** — In sequential workflows, define exactly what each Agent passes to the next. Example: "Research Agent outputs a Markdown document with sources, key points, and data. Writer Agent uses this as input to draft." + +**Right-size the team** — More Agents does not mean better results. Start with 2–3 Agents and add more only as needed. Too many Agents slow the workflow without adding value. + +**Match models to tasks** — Use capable models where reasoning matters; use faster, lighter models for straightforward steps. + +## Common Use Cases + +**Content production** — Blog posts (research → write → edit → SEO), social media campaigns, documentation, video scripts. + +**Business analysis** — Market research, competitive analysis, financial modeling, risk assessment. + +**Software development** — Feature development (requirements → design → code → testing), code review, bug fixing, API design. + +**Creative projects** — Story development, marketing campaigns, product naming, design critique. + +## Troubleshooting + +**Group responds too slowly** — Reduce the number of Agents, use lighter models for simple steps, switch to parallel mode when possible, or simplify Agent system roles. + +**Inconsistent outputs** — Add clearer role definitions, include shared guidelines in the group context, add a reviewer Agent, or lower the temperature setting. + +**Agents not collaborating well** — Explicitly define what each Agent receives and produces, add transition instructions between Agents, or switch to sequential mode. + +**Poor quality results** — Upgrade to a better model for critical Agents, add specialist Agents for key areas, include a quality-control Agent, or write more detailed system roles. + + + + + + + + diff --git a/docs/usage/agent/agent-team.zh-CN.mdx b/docs/usage/agent/agent-team.zh-CN.mdx index 98cd667359..f91478e32b 100644 --- a/docs/usage/agent/agent-team.zh-CN.mdx +++ b/docs/usage/agent/agent-team.zh-CN.mdx @@ -1,64 +1,139 @@ --- -title: Agent 团队 -description: 简单的集中配置，例如提示词，选择模型，知识库，插件等。 +title: 群组 +description: 将多个专业助理聚合在一起协作——顺序、并行、迭代或辩论模式，应对任何复杂任务。 tags: - LobeHub - - LobeHub - - AI 助手 - - 助手组织 - - 分组设置 - - 助手搜索 - - 助手固定 + - 群组 + - 多助理协作 + - 群聊 + - 主持人 + - 顺序模式 + - 并行模式 --- -# Agent 团队 +# 群组 -有时候，一个助理的视角是不够的。复杂问题需要多角度思考，创意项目需要不同专业背景的碰撞，学习讨论需要多方辩论。Agent 群聊让多个专业助理聚在一起，像真实群聊一样协作 —— 翻译助理、编程助理、产品经理助理围坐一起，各自发挥专长，共同解决你的问题。你不再是获得一个答案，而是参与一场对话。不同观点在这里碰撞，专业知识在这里互补，AI 助理协同工作时产生的洞察，远超任何单一助理所能提供的。 +一个助理的视角很少足够。复杂问题需要多角度思考，创意项目需要不同专业背景的碰撞，重要决策需要结构化的讨论。群组将多个专业助理聚合在一起，像真实团队一样协作 —— 调研助理、分析助理、写作助理各司其职，共同完成你的任务。你得到的不只是一个答案，而是一个协调有序的过程。 -Agent 群聊是多个专业助理的协作空间。你提出一个问题或任务，不同助理从各自的专业角度给出见解，它们之间可以互相讨论、补充、甚至辩论。 +提出问题或任务，每个助理从各自的专业角度给出见解 —— 它们可以互相补充、质疑假设，或并行推进，具体取决于你选择的模式。 -## 单个助理的局限 +## 为什么不用单个助理？ -- 只能从一个角度分析问题 +- 单个助理只能从一个角度分析问题 - 专业领域受限于预设角色 -- 缺少多元视角的碰撞 +- 缺少来回交锋来发现盲点和权衡取舍 -## Agent 群聊的优势 +群组解决这三个问题。 -- 多个助理各取所长，协同工作 -- 不同专业背景带来全面的解决方案 -- 助理之间的讨论激发更深入的洞察 -- 内置主持人确保讨论有序进行 +## 协作模式 + +群组根据任务灵活适配： + +**顺序模式** — 助理按预定顺序依次工作。示例：调研助理收集信息 → 分析助理处理数据 → 写作助理生成最终文档。适合有明确交接节点的线性工作流。 + +**并行模式** — 多个助理同时处理不同方面。示例：营销助理撰写文案的同时，数据助理汇总指标。适合可并发执行的独立子任务。 + +**迭代模式** — 助理通过多轮循环审查和打磨工作。示例：写作者生成草稿 → 编辑者提供反馈 → 写作者修改 → 编辑者最终审阅。适合需要反复打磨的高质量输出。 + +**辩论模式** — 助理呈现不同立场并进行论证。支持者陈述理由，批评者质疑假设，分析师评估证据，调解者综合结论。适合需要深入分析的复杂决策。 ## 关于主持人 -每个 Agent 群聊都有一个内置的主持人。它负责： +每个群组都内置一个主持人，负责： -- 理解你的需求，分配讨论任务 -- 协调各个助理的发言顺序 +- 理解你的目标，将任务分配给合适的助理 +- 协调各助理的发言顺序 - 总结讨论结果，提炼关键结论 -- 确保对话围绕主题有序展开 +- 确保对话围绕主题有序推进 -## 创建 Agent 群聊 +## 创建群组 -在左侧边栏选择「创建群组」即可进入创建。 +在左侧边栏点击**创建群组**即可开始。 -![clipboard-1768907980491-9cc0669fc3a38.png](/blog/assets8be3a46c8f9c5d3b61bc541f44b7f245.webp) +![创建群组](/blog/assets8be3a46c8f9c5d3b61bc541f44b7f245.webp) -创建群聊时，你可以使用现有模版，也可以选择自己的 AI 助理组建群聊。同时，你可以选择是否使用主持人，并为主持人选择模型。 +创建时，你可以选择现有模版，也可以自己组建团队。同时决定是否使用主持人，并为主持人选择模型。 -![clipboard-1768908081787-ed9eb1cb78bdb.png](/blog/assetsab009b79dd794f02aec24b7607f342e8.webp) +![群组创建 —— 模版或自定义团队](/blog/assetsab009b79dd794f02aec24b7607f342e8.webp) -## 配置 Agent 群聊 +## 配置群组 -在群聊会话左侧边栏，选中助理，可以便捷更换助理的模型和移除助理。 +在群聊会话的左侧边栏，选中助理可以便捷更换其模型或将其移出群组。 -![clipboard-1768908121691-b3517bf882633.png](/blog/assetsd3cae44cba0d3f57df6440b46246e5e7.webp) +![在群聊中选中助理](/blog/assetsd3cae44cba0d3f57df6440b46246e5e7.webp) -同样在左侧边栏，点击添加成员按钮可以添加需要的助理到群聊中。 +点击左侧边栏的**添加成员**，可以将更多助理加入群组。 -![clipboard-1768908209289-9d3ecff50142f.png](/blog/assets75a5cf08b3e432d2477899d30acc9d47.webp) +![添加成员到群组](/blog/assets75a5cf08b3e432d2477899d30acc9d47.webp) -在左侧边栏进入「群聊档案」，你可以编写群聊提示词，为群聊添加插件，更换主持人模型。你也可以使用右侧面板的 Agent Builder 进行智能创建。Agent Builder 是 LobeHub 的内置助理，只需与 Agent Builder 对话，描述你的需求，它就能理解并自动生成完整的群聊配置 —— 包括群聊设定、系统提示词、插件配置。 +在左侧边栏进入**群聊档案**，可以编写群聊提示词、添加技能、更换主持人模型。你也可以使用右侧面板的 Agent Builder—— 描述你的目标，它会自动生成完整的群聊配置，包括设定、系统提示词和技能配置。 -![clipboard-1768908230723-3fce0ae5baf9b.png](/blog/assets8e9b164fa30c795850ce8fa8ef7e7c24.webp) +![群聊档案设置](/blog/assets8e9b164fa30c795850ce8fa8ef7e7c24.webp) + +## 群组示例 + +### 内容创作团队 + +适合博客文章或文档生产的顺序工作流： + +1. **调研员** — 收集信息、可信来源、统计数据和专家观点 +2. **写作者** — 基于调研素材撰写有吸引力的草稿 +3. **编辑** — 审查并完善内容的清晰度、逻辑和一致性 +4. **SEO 专家** — 优化关键词、标题和 meta 描述 + +### 研究分析团队 + +1. **数据收集员** — 从多个来源和文档中获取数据 +2. **统计分析师** — 分析数据、计算指标、识别规律 +3. **领域专家** — 在行业知识背景下解读发现 +4. **报告撰写者** — 将洞见综合为执行摘要 + +### 软件开发团队 + +- **需求助理** — 收集需求，撰写产品需求文档 +- **技术架构师** — 设计系统架构和技术规范 +- **开发者** — 编写实现代码和技术文档 +- **QA 测试员** — 审查代码，建议测试用例，识别边界情况 + +## 最佳实践 + +**明确角色定义** — 每个助理应有具体、清晰的职责： + +- ❌ 模糊："助理 1：帮助处理内容" +- ✅ 清晰："调研助理：在指定主题上找到 3–5 个可信来源并总结要点，包含统计数据和专家引用。" + +**避免角色重叠** — 不要创建职责重叠的多个助理。每个助理都应带来独特价值。 + +**明确交接节点** — 在顺序工作流中，明确定义每个助理向下一个传递的内容。示例："调研助理输出包含来源、要点和数据的 Markdown 文档；写作助理将此作为起草草稿的输入。" + +**控制团队规模** — 更多助理不等于更好的结果。从 2–3 个助理开始，按需添加。过多助理会拖慢工作流。 + +**按任务选择模型** — 推理关键的步骤用更强的模型；简单步骤用更快、更轻量的模型。 + +## 常见使用场景 + +**内容生产** — 博客文章（调研 → 写作 → 编辑 → SEO）、社交媒体营销、文档编写、视频脚本。 + +**商业分析** — 市场调研、竞品分析、财务建模、风险评估。 + +**软件开发** — 功能开发（需求 → 设计 → 编码 → 测试）、代码审查、Bug 修复、API 设计。 + +**创意项目** — 故事创作、营销活动策划、产品命名、设计评审。 + +## 故障排查 + +**群组响应太慢** — 减少助理数量，对简单步骤使用更快的模型，尽量切换到并行模式，或简化系统提示词。 + +**输出结果不一致** — 添加更清晰的角色定义，在群组上下文中加入共享规范，添加审查助理，或调低温度参数。 + +**助理之间协作不畅** — 明确定义每个助理的输入和输出，在助理之间添加交接说明，或改用顺序模式。 + +**输出质量不佳** — 为关键助理升级到更强的模型，为核心领域添加专业助理，引入质量控制助理，或提供更详细的系统角色说明。 + + + + + + + + diff --git a/docs/usage/agent/artifacts.mdx b/docs/usage/agent/artifacts.mdx new file mode 100644 index 0000000000..c9e638ab3c --- /dev/null +++ b/docs/usage/agent/artifacts.mdx @@ -0,0 +1,181 @@ +--- +title: Artifacts +description: >- + Create and interact with dynamic, self-contained AI-generated content — React + apps, SVG graphics, HTML pages, Mermaid diagrams, and more — rendered live in + a dedicated preview panel. +tags: + - LobeHub + - Artifacts + - Code Generation + - React + - SVG + - Visualization +--- + +# Artifacts + +LobeHub supports Claude-style Artifacts: when the AI generates substantial, self-contained content, it automatically opens in a dedicated preview panel on the right side of the screen. Instead of copying code from a chat bubble, you can interact with, iterate on, and export the result directly. + +## What Are Artifacts? + +Artifacts are AI-generated pieces of content that deserve their own dedicated space. They appear in a split-view panel where you can: + +- View live previews of generated content +- Interact with applications and visualizations in real time +- Iterate on the output conversationally +- Export or copy the final result + +**What qualifies as an artifact:** + +- Substantial content (more than a few lines) +- Self-contained and functional output +- Something you'd want to iterate on or reuse +- Content that benefits from a live preview + +**What doesn't need artifacts:** + +- Short code snippets or quick examples +- Simple text answers +- Explanatory content + +## Supported Artifact Types + +### SVG Graphics + +Create scalable, resolution-independent graphics and diagrams: charts, flowcharts, icons, infographics, and data visualizations. + +Example prompts: + +- "Create an SVG diagram showing the software development lifecycle" +- "Generate a pie chart showing market share distribution" + +Export options: download as SVG, download as PNG, copy as image. + +### React Components + +Build live, interactive React applications that run directly in the browser: calculators, dashboards, mini web apps, and UI prototypes. + +Example prompts: + +- "Create a mortgage calculator with React" +- "Build an interactive to-do list app" +- "Make a typing speed test game" + +Features: full React hooks support, real-time state management, responsive layouts. + +### HTML Pages + +Generate complete, styled HTML pages: landing pages, email templates, simple web pages, and formatted reports. + +Example prompts: + +- "Create a product landing page for a fitness app" +- "Design an HTML email newsletter template" + +### Mermaid Diagrams + +Create professional diagrams: flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, ER diagrams, and Git graphs. + +Example prompts: + +- "Create a sequence diagram for user authentication" +- "Draw a flowchart for the order processing workflow" + +### Code Files + +Generate standalone code in Python, JavaScript/TypeScript, shell scripts, configuration files (JSON, YAML), and more. + +Example prompts: + +- "Write a Python script to analyze CSV data" +- "Generate a GitHub Actions workflow file" + +Features: syntax highlighting, one-click copy, side-by-side code and preview view. + +## Using Artifacts + +### Triggering Artifact Creation + +Just ask the AI to create substantial, standalone content: + +``` +"Create a React calculator app" +"Generate an SVG chart showing quarterly sales" +"Build an interactive timeline of key events" +"Design a landing page for a coffee shop" +``` + +Artifacts are generated automatically when the AI determines the output is substantial and self-contained. + +### Viewing and Interacting + +When an artifact is created, the preview panel opens automatically on the right: + +1. **Preview mode** — Shows the rendered output. Interactive apps run live, SVG graphics display at full quality, HTML pages render completely. +2. **Code mode** — Shows the syntax-highlighted source code. Use this to copy code to your project or understand the implementation. + +Switch between modes using the toggle at the top of the panel. + +### Iterating Conversationally + +Continue the chat to refine any artifact: + +``` +"Add a dark mode toggle" +"Make the chart responsive for mobile" +"Change the color scheme to blue and green" +"Add error handling to the form" +``` + +Each update applies in real time — you see the change immediately in the preview panel. + +### Exporting + +Depending on the artifact type: + +- **Copy code** — Copy the complete source to clipboard +- **Download SVG** — Save as `.svg` +- **Download PNG** — Export as an image +- **Copy as image** — Copy rendered output to clipboard +- **Save HTML** — Download a complete web page + +## Use Cases + +**Rapid prototyping** — Build and test ideas without writing code: UI mockups, calculators, converters, form validation demos. Iterate in real time, then export to your project. + +**Data visualization** — Turn raw data into charts and dashboards. Share the data or describe it, ask for a chart, customize, then export for presentations or reports. + +**Learning and education** — Create interactive algorithm visualizations, step-by-step demonstrations, and practice exercises. Great for teachers building learning materials. + +**Design and creative** — Generate logo concepts, icon sets, diagrams, and decorative elements. Download as SVG for editing in your design tool. + +## Tips + +**Be specific in requests** — Detail prompts produce better artifacts. Specify colors, layout, functionality, and features upfront rather than asking for generic output. + +**Iterate incrementally** — Make one change at a time to keep the artifact stable. Large simultaneous changes can introduce bugs. + +**Test interactivity** — For interactive artifacts (React apps, forms), test all features before exporting. Ask for fixes on specific edge cases. + +**Use both modes** — Switch between Preview and Code mode to understand both the visual result and the implementation details. + +**Save what you like** — Copy or download artifacts you want to keep. They stay in your conversation history but are easier to access when saved separately. + + + Artifacts run in a sandboxed environment for security. Features that require external API calls or + sensitive browser permissions may not work inside the preview panel. + + + + Not all models support artifacts. Claude models are the primary source of artifact generation. + Complex artifacts may take a moment to fully render as the AI generates the content. + + + + + + + + + diff --git a/docs/usage/agent/artifacts.zh-CN.mdx b/docs/usage/agent/artifacts.zh-CN.mdx new file mode 100644 index 0000000000..462be088a7 --- /dev/null +++ b/docs/usage/agent/artifacts.zh-CN.mdx @@ -0,0 +1,177 @@ +--- +title: Artifacts +description: 创建并与动态的 AI 生成内容互动——React 应用、SVG 图形、HTML 页面、Mermaid 图表等——在专属预览面板中实时渲染。 +tags: + - LobeHub + - Artifacts + - 代码生成 + - React + - SVG + - 可视化 +--- + +# Artifacts + +LobeHub 支持 Claude 风格的 Artifacts：当 AI 生成内容较为完整且自包含时，会自动在屏幕右侧打开专属预览面板。你无需从聊天气泡中复制代码，可以直接在面板中交互、迭代并导出结果。 + +## 什么是 Artifacts？ + +Artifacts 是 AI 生成的、值得拥有独立展示空间的内容。它们在分屏面板中显示，你可以： + +- 查看生成内容的实时预览 +- 与应用程序和可视化内容实时交互 +- 通过对话方式迭代优化输出 +- 导出或复制最终结果 + +**符合 Artifacts 条件的内容：** + +- 内容量较多（超过几行代码或文本） +- 自包含且功能完整 +- 你希望反复迭代或复用的内容 +- 适合实时预览的内容 + +**不需要 Artifacts 的内容：** + +- 简短的代码片段或示例 +- 简单的文字回答 +- 解释性文本 + +## 支持的 Artifacts 类型 + +### SVG 图形 + +创建可缩放的矢量图形和图表：数据图表、流程图、图标、信息图以及数据可视化内容。 + +示例提示： + +- "创建一个展示软件开发生命周期的 SVG 图表" +- "生成一个显示市场份额分布的饼图" + +导出选项：下载 SVG、下载 PNG、复制为图片。 + +### React 组件 + +构建可在浏览器中直接运行的交互式 React 应用：计算器、数据仪表盘、小型 Web 应用、UI 原型。 + +示例提示： + +- "用 React 创建一个房贷计算器" +- "构建一个交互式待办事项应用" +- "做一个打字速度测试游戏" + +功能：完整的 React Hooks 支持、实时状态管理、响应式布局。 + +### HTML 页面 + +生成完整的、带样式的 HTML 页面：落地页、邮件模板、简单网页、格式化报告。 + +示例提示： + +- "为健身应用创建一个产品落地页" +- "设计一个 HTML 邮件通讯模板" + +### Mermaid 图表 + +创建专业图表：流程图、时序图、类图、状态图、甘特图、ER 图、Git 图。 + +示例提示： + +- "创建用户认证流程的时序图" +- "绘制订单处理工作流的流程图" + +### 代码文件 + +生成独立的代码文件：Python、JavaScript/TypeScript、Shell 脚本、配置文件（JSON、YAML）等。 + +示例提示： + +- "编写一个分析 CSV 数据的 Python 脚本" +- "生成一个 GitHub Actions 工作流配置文件" + +功能：语法高亮、一键复制、代码与预览并排显示。 + +## 使用 Artifacts + +### 触发 Artifacts 创建 + +只需要求 AI 创建较完整的独立内容： + +``` +"创建一个 React 计算器应用" +"生成一个展示季度销售额的 SVG 图表" +"构建一个关键事件的交互式时间轴" +"为一家咖啡馆设计一个落地页" +``` + +当 AI 判断输出内容较为完整且自包含时，会自动生成 Artifacts。 + +### 查看与交互 + +Artifacts 创建后，预览面板自动在右侧弹出： + +1. **预览模式** — 显示渲染后的输出。交互式应用实时运行，SVG 图形以完整质量显示，HTML 页面完整渲染。 +2. **代码模式** — 显示带语法高亮的源代码。适合复制代码到项目中或了解实现细节。 + +使用面板顶部的切换按钮在两种模式之间切换。 + +### 对话式迭代 + +继续聊天即可完善任何 Artifacts： + +``` +"添加一个深色模式切换" +"使图表在移动端自适应" +"将配色方案改为蓝绿色" +"为表单添加错误处理" +``` + +每次更新都会实时应用 —— 你可以在预览面板中立即看到变化。 + +### 导出 + +根据 Artifacts 类型，可以： + +- **复制代码** — 将完整源代码复制到剪贴板 +- **下载 SVG** — 保存为 `.svg` 文件 +- **下载 PNG** — 导出为图片 +- **复制为图片** — 将渲染输出复制到剪贴板 +- **保存 HTML** — 下载完整网页 + +## 使用场景 + +**快速原型验证** — 无需编写代码即可构建和测试想法：UI 模型、计算器、转换工具、表单验证演示。实时迭代，然后导出到项目中。 + +**数据可视化** — 将原始数据转化为图表和仪表盘。分享数据或描述数据，请求图表，自定义后导出用于演示或报告。 + +**学习与教育** — 创建交互式算法可视化、分步演示和练习题。非常适合教师制作教学材料。 + +**设计创意** — 生成 Logo 概念、图标集、图表和装饰元素。下载 SVG 在设计工具中进一步编辑。 + +## 使用技巧 + +**具体描述需求** — 详细的提示词会产出更好的 Artifacts。提前指定颜色、布局、功能和特性，而不是要求笼统的输出。 + +**分步迭代** — 每次只做一个改动，保持 Artifacts 的稳定性。同时做大量改动可能引入 Bug。 + +**测试交互性** — 对于交互式 Artifacts（React 应用、表单），在导出前测试所有功能，并针对特定边界情况请求修复。 + +**善用两种模式** — 在预览模式和代码模式之间切换，同时了解视觉效果和实现细节。 + +**保存满意的结果** — 复制或下载你想保留的 Artifacts。它们会保存在对话历史中，但单独保存会更便于访问。 + + + Artifacts 在沙盒环境中运行以保障安全。需要外部 API 调用或敏感浏览器权限的功能可能在预览面板中无法正常工作。 + + + + 并非所有模型都支持 Artifacts。Claude 系列模型是 Artifacts 生成的主要来源。复杂的 Artifacts + 可能需要片刻时间完整渲染。 + + + + + + + + + diff --git a/docs/usage/agent/chain-of-thought.mdx b/docs/usage/agent/chain-of-thought.mdx new file mode 100644 index 0000000000..fb023d3192 --- /dev/null +++ b/docs/usage/agent/chain-of-thought.mdx @@ -0,0 +1,108 @@ +--- +title: Chain of Thought +description: >- + Visualize AI reasoning step-by-step with transparent thinking processes. Watch + how models break down complex problems before giving a final answer. +tags: + - LobeHub + - Chain of Thought + - AI Reasoning + - Transparency +--- + +# Chain of Thought + +LobeHub's Chain of Thought (CoT) visualization provides transparency into how AI models reason through complex problems, letting you watch the thinking process unfold in real time before the final answer arrives. + +## What is Chain of Thought? + +Chain of Thought is a reasoning technique where AI models break down complex problems into clear, logical steps before producing a final answer. LobeHub makes this internal reasoning visible so you can: + +- **See the thinking process** — Watch how the AI approaches problems +- **Understand decision-making** — Follow the logical progression from question to answer +- **Validate reasoning** — Verify that conclusions are based on sound logic +- **Debug responses** — Identify where reasoning may have gone wrong +- **Learn problem-solving** — Observe expert-level reasoning patterns + +## How It Works + +When a model uses Chain of Thought reasoning: + +1. **Problem analysis** — The model first analyzes what's being asked +2. **Step-by-step thinking** — Breaks down the approach into logical steps +3. **Intermediate reasoning** — Works through each step with visible thought +4. **Final answer** — Synthesizes insights into a clear response + +All of this happens in real time, displayed in an expandable section above the final answer. + +## Viewing the Reasoning + +### Thinking Indicator + +When a model is reasoning, you'll see: + +- A **"Thinking…"** animated indicator showing active reasoning +- A **duration counter** showing how long the model spent reasoning +- An **expandable section** — click to see the full thought process +- **Step-by-step breakdown** of each reasoning step + +### Display Modes + +**Collapsed view** — Shows only the "Thinking..." indicator and duration. Best for quick responses where you trust the reasoning, or when you want to keep the interface clean. + +**Expanded view** — Click to reveal complete step-by-step reasoning, intermediate conclusions, logical connections, and the full thought process from start to finish. Best for validating complex reasoning or learning how problems are approached. + +## When Chain of Thought Activates + +CoT reasoning is most beneficial — and most commonly used by models — for: + +**Mathematical problems** — Multi-step calculations where the model sets up equations, performs intermediate calculations, and shows work at each step. Example: "Calculate the compound interest on $10,000 at 5% annual rate for 3 years, compounded quarterly." + +**Logical reasoning** — Deductive and inductive problems where the model identifies premises, applies logical rules, draws intermediate conclusions, and builds to a final inference. + +**Code debugging** — Systematic error analysis where the model examines code structure, identifies potential issues, tests hypotheses, and proposes solutions. + +**Complex problem solving** — Multi-faceted analysis where the model breaks down the problem, considers multiple angles, weighs trade-offs, and synthesizes solutions. + +**Strategic planning** — Structured decision-making where the model defines objectives, analyzes constraints, evaluates options, and recommends approaches. + +## Use Cases + +**Education and learning** — Chain of Thought is invaluable for students. See how to approach complex problems, learn step-by-step methodologies, and understand where mistakes occur. Ask the AI to "show its work" or "explain step-by-step" for the clearest reasoning display. + +**Software development** — Use CoT to understand technical decisions: code review logic, architecture choices, debugging complex issues, algorithm optimization. Follow the AI's analysis to discover considerations you may have missed. + +**Data analysis** — See how conclusions are drawn from data. Watch statistical reasoning, hypothesis testing, and pattern recognition unfold, then verify the analytical approach before acting on insights. + +**Research and writing** — Observe how arguments and narratives are constructed: how points are organized, how logical flow develops, and how supporting evidence is selected. + +## Interpreting the Reasoning + +When reviewing Chain of Thought output, look for: + +**Logical progression** — Do steps build on each other? Are there clear connections between ideas? Does the reasoning flow naturally? + +**Completeness** — Are all aspects of the question addressed? Were edge cases considered? Is anything overlooked? + +**Validity** — Are assumptions reasonable? Is the logic sound? Do conclusions follow from the premises? + +If a reasoning step seems incorrect or incomplete, continue the conversation: "That step seems wrong because..." or "Can you reconsider step 3?" The model can revise its reasoning based on your feedback. + +## Tips + +- **Ask explicitly for reasoning** — Prompts like "show your reasoning step by step" or "think through this carefully" encourage detailed CoT responses +- **Review for critical decisions** — Always expand and read the reasoning for important choices or high-stakes problems +- **Question unexpected reasoning** — If a step seems off, ask for clarification or an alternative approach +- **Learn from patterns** — Studying how the AI approaches different problem types can improve your own problem-solving + + + Not all models use Chain of Thought reasoning, and not all responses trigger it even on models + that support it. CoT is most common with complex problems that benefit from step-by-step analysis. + Supported models include o1, o3, Claude 3.7 Sonnet, Gemini 2.0 Flash Thinking, and others. + + + + + + + diff --git a/docs/usage/agent/chain-of-thought.zh-CN.mdx b/docs/usage/agent/chain-of-thought.zh-CN.mdx new file mode 100644 index 0000000000..1d63aee60c --- /dev/null +++ b/docs/usage/agent/chain-of-thought.zh-CN.mdx @@ -0,0 +1,105 @@ +--- +title: 思维链 +description: 逐步可视化 AI 推理过程，透明呈现思考链路。观察模型在给出最终答案前如何分解复杂问题。 +tags: + - LobeHub + - 思维链 + - AI 推理 + - 透明度 +--- + +# 思维链 + +LobeHub 的思维链（Chain of Thought，CoT）可视化功能为你提供了洞察 AI 模型推理过程的窗口，让你在最终答案出现之前，实时观察思考过程的展开。 + +## 什么是思维链？ + +思维链是一种推理技术 ——AI 模型在给出最终答案之前，先将复杂问题分解为清晰、有逻辑的步骤。LobeHub 将这一内部推理过程可视化，让你能够： + +- **看到思考过程** — 观察 AI 如何分析问题 +- **理解决策路径** — 追踪从问题到答案的逻辑推进 +- **验证推理合理性** — 确认结论是否基于严谨的逻辑 +- **调试异常回复** — 发现推理过程中出现偏差的地方 +- **学习解题方法** — 观察专家级的问题解决模式 + +## 工作原理 + +当模型使用思维链推理时： + +1. **问题分析** — 模型首先理解所提问题 +2. **分步思考** — 将解题方法分解为逻辑步骤 +3. **中间推理** — 逐步推进，展示可见的思考内容 +4. **最终答案** — 将所有洞见综合为清晰的回复 + +这一过程实时发生，显示在最终答案上方的可折叠区域中。 + +## 查看推理过程 + +### 思考指示器 + +当模型正在推理时，你会看到： + +- 一个动态的 **"思考中…"** 指示器，表示正在推理 +- 一个**时长计数器**，显示模型思考耗时 +- 一个**可展开区域** — 点击即可查看完整思考过程 +- **逐步呈现**的每个推理步骤 + +### 显示模式 + +**折叠视图** — 仅显示 "思考中..." 指示器和时长。适合你信任推理结果的快速回复，或希望保持界面简洁时使用。 + +**展开视图** — 点击即可查看完整的分步推理、中间结论、逻辑连接，以及从头到尾的完整思考过程。适合验证复杂推理或学习问题解决方法时使用。 + +## 思维链的激活时机 + +CoT 推理最有价值的场景（也是模型最常使用它的场景）： + +**数学问题** — 多步骤计算场景，模型会建立方程式、执行中间步骤并逐步展示过程。例如："计算 10,000 美元以 5% 年利率按季度复利投资 3 年的收益。" + +**逻辑推理** — 演绎和归纳推理问题，模型识别前提、应用逻辑规则、得出中间结论并建立最终推断。 + +**代码调试** — 系统性的错误分析，模型逐一检查代码结构、识别潜在问题、验证假设并提出解决方案。 + +**复杂问题解决** — 多维度分析场景，模型分解问题、从多个角度考量、权衡利弊并综合解决方案。 + +**战略规划** — 结构化决策过程，模型定义目标、分析约束、评估选项并给出推荐路径。 + +## 使用场景 + +**学习与教育** — 思维链对学习者极具价值。观察如何处理复杂问题，学习分步解题方法，了解错误出现的原因。尝试要求 AI "展示解题过程" 或 "逐步说明"，获得最清晰的推理展示。 + +**软件开发** — 用 CoT 理解技术决策：代码审查逻辑、架构选型、复杂问题调试、算法优化。跟随 AI 的分析，发现你可能遗漏的考量点。 + +**数据分析** — 观察结论如何从数据中得出：统计推理、假设检验、模式识别过程一览无余，在采取行动前验证分析方法的合理性。 + +**研究与写作** — 观察论点和叙述结构的形成过程：观点如何组织、逻辑流如何发展、论据如何筛选。 + +## 解读推理过程 + +查看思维链输出时，重点关注： + +**逻辑推进** — 各步骤是否环环相扣？思想之间是否有清晰的关联？推理是否自然流畅？ + +**完整性** — 问题的所有方面是否都被涵盖？是否考虑了边界情况？有没有遗漏的内容？ + +**合理性** — 假设是否合理？逻辑是否严谨？结论是否从前提中自然推导出来？ + +如果某个推理步骤看起来有误或不完整，可以继续对话："这一步好像有问题，因为……" 或 "能重新考虑第 3 步吗？" 模型可以根据你的反馈修正推理过程。 + +## 使用技巧 + +- **明确要求推理过程** — "请逐步展示你的推理" 或 "仔细思考这个问题" 等提示词能鼓励模型展示详细的 CoT 过程 +- **重要决策务必查看** — 对于关键选择或高风险问题，始终展开并阅读推理过程 +- **质疑异常步骤** — 如果某一步骤不对，请求澄清或提供替代思路 +- **从模式中学习** — 观察 AI 处理不同类型问题的方式，有助于提升你自己的解题能力 + + + 并非所有模型都使用思维链推理，即使支持 CoT 的模型也不是在所有回复中都会触发。CoT 最常见于需要分步分析的复杂问题。支持该功能的模型包括 + o1、o3、Claude 3.7 Sonnet、Gemini 2.0 Flash Thinking 等。 + + + + + + + diff --git a/docs/usage/agent/gtd.mdx b/docs/usage/agent/gtd.mdx index 05e84f9a1b..faca7da85b 100644 --- a/docs/usage/agent/gtd.mdx +++ b/docs/usage/agent/gtd.mdx @@ -1,35 +1,81 @@ --- title: GTD Tools description: >- - Learn how to use scheduled tasks, including creating, editing, and deleting - them. + Manage tasks through conversation — GTD methodology built in. Capture ideas, + track progress, focus on what matters. tags: - - Scheduled Tasks - - Create - - Edit - - Delete + - LobeHub + - GTD + - Task Management + - Getting Things Done --- # GTD Tools -GTD Tools is a built-in plugin in LobeHub that deeply integrates the classic GTD (Getting Things Done) time management methodology into your conversational experience. Once enabled, your assistant transforms into a professional task management expert, helping you offload mental clutter and focus on what truly matters—your creativity and deep thinking. With GTD Tools, you can manage your schedule directly through natural language in conversations. Whether it's a sudden burst of inspiration, household chores, or serious work plans, your assistant can accurately record and track your progress. +GTD Tools is a built-in Skill that brings the classic GTD (Getting Things Done) methodology into your conversations. Once enabled, your Agent becomes a task management partner — helping you capture ideas, track progress, and focus on what matters. Manage your schedule directly through natural language: sudden inspiration, household chores, or serious work plans — your Agent records and tracks it all. ## Enabling GTD Tools -GTD Tools is a built-in plugin in LobeHub and must be enabled for your assistant before use. +GTD Tools is a built-in Skill. Enable it for your Agent before use. -### Enable via Assistant Profile +**From Agent Profile** — Go to the Agent Profile page, click **+ Add Skill**, and check **GTD Tools**. -Go to the assistant profile page, click on "+ Integrate Plugin," and check the "GTD Tools" plugin to activate it. +**In a conversation** — Click the Skill icon below the chat input and check **GTD Tools**. -### Enable in Conversation +## Creating Tasks -In the conversation window, click the plugin icon below the chat box and check the "GTD Tools" plugin to enable it. +Send your plans in the conversation — your Agent automatically recognizes and confirms the task. No forms, no extra steps. -### Creating Tasks +**Examples:** -You can simply send your plans in the conversation, and the assistant will automatically recognize and confirm the task. +- "Add 'Review Q1 report' to my tasks for tomorrow" +- "I need to call the dentist this week" +- "Remind me to submit the proposal by Friday" +- "Put 'Finish the design mockup' on my list for next Monday" +- "I have a meeting with the client at 3pm — add it to my calendar" -### Completing Tasks +## Completing and Updating Tasks -You can update tasks through conversational commands, and the assistant will handle the updates automatically. +Update tasks through conversational commands. Your Agent handles the updates automatically. + +**Examples:** + +- "Mark 'Review Q1 report' as done" +- "What's on my task list for today?" +- "Reschedule the dentist call to next Monday" +- "Show me all my pending tasks" +- "Remove the proposal task — I already submitted it" + +## Use Cases + +**Capture on the fly** — An idea strikes during a meeting? Tell your Agent in one sentence. No need to switch apps or open a task manager. + +**Weekly planning** — Start a conversation: "Here's what I need to do this week…" Your Agent structures it into a manageable list. + +**Context switching** — Moving from one project to another? Ask "What did I leave unfinished on the marketing project?" and pick up where you left off. + +**Collaboration prep** — Before a team sync, ask "What are my action items from last week?" and show up prepared. + +## GTD Tools vs. Other Features + +| Feature | Best For | +| --------------------------------------------------- | ----------------------------------------------------------------------- | +| **GTD Tools** | Task lists, deadlines, progress tracking — managed through conversation | +| [Notebook](/docs/usage/agent/notebook) | Saving notes, reports, research — documents linked to a Topic | +| [Scheduled Tasks](/docs/usage/agent/scheduled-task) | Automated workflows — Agents run on a schedule without you | + +Use GTD for personal task management; use Scheduled Tasks when you want the Agent to execute something automatically at a set time. + +## Tips + +- **Be specific about timing** — "Tomorrow at 9am" or "by end of week" helps the Agent prioritize and remind you at the right moment. +- **Review regularly** — Ask "What's due this week?" at the start of each week to stay on top of commitments. +- **Combine with Notebook** — Save meeting notes to the Notebook, then ask your Agent to extract action items into GTD tasks. + + + + + + + + diff --git a/docs/usage/agent/gtd.zh-CN.mdx b/docs/usage/agent/gtd.zh-CN.mdx index e04eefe3b2..ed4cbbce2e 100644 --- a/docs/usage/agent/gtd.zh-CN.mdx +++ b/docs/usage/agent/gtd.zh-CN.mdx @@ -1,33 +1,79 @@ --- title: GTD 工具 -description: 了解如何使用定时任务，包括创建、编辑、删除等。 +description: 在对话中管理任务——内置 GTD 方法论。捕捉想法、追踪进度、专注重要事项。 tags: - - 定时任务 - - 创建 - - 编辑 - - 删除 + - LobeHub + - GTD + - 任务管理 + - Getting Things Done --- # GTD 工具 -GTD Tools 是 LobeHub 内置的插件，将经典的 GTD（Getting Things Done）时间管理方法论深度集成到你的对话体验中。开启该插件后，你的助理将化身为专业的任务管理专家，帮助你将大脑从琐碎的杂事中解放出来，专注于当下的创作与思考。通过 GTD Tools，你可以直接在会话中以自然语言管理日程。无论是突如其来的灵感、待办的家务，还是严肃的工作计划，助理都能为你精准记录并追踪进度。 +GTD Tools 是内置技能，将经典的 GTD（Getting Things Done）时间管理方法论融入你的对话。启用后，助理成为你的任务管理伙伴 —— 帮你捕捉想法、追踪进度、专注重要事项。直接用自然语言管理日程：突如其来的灵感、待办的家务、严肃的工作计划 —— 助理都能精准记录并追踪。 ## 启用 GTD Tools -GTD Tools 是 LobeHub 的内置插件，需要为助理启用后才能使用。 +GTD Tools 是内置技能。使用前需为助理启用。 -### 在助理档案中启用 +**从助理档案** — 进入助理档案页面，点击 **+ 添加技能 **，勾选**GTD Tools**。 -进入助理档案页面，点击「+ 集成插件」，勾选「GTD Tools」插件即可开启。 +**在会话中** — 点击对话框下方的技能图标，勾选**GTD Tools**。 -### 在会话中启用 +## 创建任务 -进入会话页面，点击对话框下方插件图标，勾选「GTD Tools」插件即可。 +在会话中直接发送你的计划 —— 助理会自动识别并确认记录。无需填表，无需额外步骤。 -### 创建任务 +**示例：** -你可以在会话中直接发送你的计划，助理会自动识别并确认记录。 +- 「把「审阅 Q1 报告」加入我明天的待办」 +- 「这周需要给牙医打个电话」 +- 「提醒我周五前提交方案」 +- 「把「完成设计稿」加到下周一的任务里」 +- 「下午 3 点和客户开会，帮我记一下」 -### 消除任务 +## 完成和更新任务 -你可以在会话中通过对话指令让助理自动更新。 +通过对话指令更新任务。助理会自动处理更新。 + +**示例：** + +- 「把「审阅 Q1 报告」标为已完成」 +- 「今天我的待办有哪些？」 +- 「把牙医电话改到下周一」 +- 「给我看看所有未完成的任务」 +- 「删掉方案那个任务，我已经交了」 + +## 使用场景 + +**随时捕捉** — 会议中突然想到一件事？用一句话告诉助理，无需切换应用或打开任务管理器。 + +**周计划** — 开始一段对话：「这周我需要做这些……」助理会帮你整理成可执行的列表。 + +**切换上下文** — 从一个项目转到另一个？问「营销项目上我还有什么没做完？」就能接着上次的进度继续。 + +**协作准备** — 团队同步前，问「上周我有哪些待办事项？」带着准备去开会。 + +## GTD 工具与其他功能 + +| 功能 | 最适合 | +| ------------------------------------------- | ------------------------ | +| **GTD 工具** | 任务列表、截止日期、进度追踪 —— 通过对话管理 | +| [笔记本](/zh/docs/usage/agent/notebook) | 保存笔记、报告、研究资料 —— 与话题关联的文档 | +| [定时任务](/zh/docs/usage/agent/scheduled-task) | 自动化工作流 —— 助理按计划自动执行 | + +个人任务管理用 GTD；需要助理在固定时间自动执行时用定时任务。 + +## 使用技巧 + +- **明确时间** — 「明天上午 9 点」或「本周内」有助于助理在合适时机提醒你。 +- **定期回顾** — 每周初问「这周有什么要交的？」保持对承诺的掌控。 +- **与笔记本配合** — 把会议纪要保存到笔记本，再让助理从中提取待办事项到 GTD 任务。 + + + + + + + + diff --git a/docs/usage/agent/notebook.mdx b/docs/usage/agent/notebook.mdx index a16958ec42..3ce888425b 100644 --- a/docs/usage/agent/notebook.mdx +++ b/docs/usage/agent/notebook.mdx @@ -1,65 +1,97 @@ --- title: Notebook description: >- - Learn how to use scheduled tasks, including how to create, edit, and delete - them. + Save and manage documents within your conversations — notes, reports, + research. Topic-level storage, always accessible. tags: - - Scheduled Tasks - - Create - - Edit - - Delete + - LobeHub + - Notebook + - Document Management + - Notes + - Topic --- # Notebook -LobeHub offers a powerful Notebook feature that allows you to save and manage documents directly within your conversations. No more worrying about losing important information—your assistant can help you take notes, save reports, and organize research materials. Everything stays within the current topic and is always accessible. The Notebook breaks the limitations of fleeting conversations by turning valuable insights into structured, manageable documents. From meeting minutes to study notes, research reports to to-do lists, the Notebook helps you build knowledge in a more systematic and lasting way. +Notebook lets you save and manage documents directly within your conversations. No more losing important information — your Agent can take notes, save reports, and organize research materials. Everything stays in the current Topic and is always accessible. Notebook turns fleeting conversation insights into structured, manageable documents — from meeting minutes to study notes, research reports to to-do lists. -The Notebook serves as a topic-level document storage space. When valuable content arises during a conversation, your assistant can save it to the Notebook, creating a structured document library. These documents are linked to the current topic, making it easy to reference and revisit them in future discussions. +Notebook is topic-level document storage. When valuable content arises in a conversation, your Agent saves it to the Notebook, building a structured document library linked to that Topic. Reference and revisit these documents in future discussions. -## What You Can Do with the Notebook +## What You Can Do with Notebook ### Save Notes and Reminders -Your assistant can quickly jot down ideas, to-dos, and flashes of inspiration. Just say "Take a note for me," and the content will be saved to your Notebook. +Your Agent quickly records ideas, to-dos, and flashes of inspiration. Say "Take a note for me" and the content is saved to your Notebook. ### Organize Research Materials -When your assistant helps you search for information or analyze data, you can save the valuable findings. The next time you continue your research, everything will be right where you left it. +When your Agent helps you search or analyze data, save the valuable findings. Next time you continue your research, everything is right where you left it. ### Generate Reports and Articles -Your assistant can help you draft structured reports, analytical documents, or long-form articles, and save them directly to the Notebook. You can view, edit, and expand on them anytime. +Your Agent drafts structured reports, analytical documents, or long-form articles and saves them directly to the Notebook. View, edit, and expand them anytime. ### Manage Document Versions -You can ask your assistant to update existing documents by adding new content or modifying what's already there. Documents in the Notebook evolve over time, always staying up to date. +Ask your Agent to update existing documents — add new content or modify what's there. Documents in the Notebook evolve over time, staying up to date. -### Enable the Notebook Plugin +## Enabling Notebook -Notebook is a built-in plugin. You’ll need to enable it for your assistant to use document management features. +Notebook is a built-in Skill. Enable it for your Agent to use document management features. -### Enable in Assistant Profile +**From Agent Profile** — Go to the Agent Profile page, click **+ Add Skill**, and check **Notebook**. -- Go to the assistant profile page, click "+ Integrate Skills," and check "Notebook" to enable it. +**In a conversation** — Click the Skill icon below the chat input and check **Notebook**. -### Enable in a Conversation +## Using Notebook -- In a conversation, click the skill icon below the chat box and check "Notebook" to activate it. - -### Using the Notebook - -You can ask your assistant to read document content: +Ask your Agent to read document content: - "Show me the notes we saved earlier" - "What did that report say?" +- "Summarize the key points from the research document" -To delete a document when it's no longer needed, you can either instruct your assistant to remove it or open the Notebook panel and delete it manually. +To delete a document when it's no longer needed, instruct your Agent to remove it or open the Notebook panel and delete it manually. -### View and Manage Documents +## View and Manage Documents -All saved documents appear in the Notebook panel on the right side of the topic. Click the document icon in the top-right corner to open the panel. You can: +All saved documents appear in the Notebook panel on the right side of the Topic. Click the document icon in the top-right corner to open the panel. You can: - Browse the document list to view titles and summaries - Click a document to view its full content -- Edit documents directly within the panel -- Click "Edit in Drafts" to sync the document with the "Drafts" section in the conversation +- Edit documents directly in the panel +- Click **Edit in Drafts** to sync the document with the Drafts section in the conversation + +## Use Cases + +**Meeting follow-up** — During a call, ask your Agent to take notes. After the meeting, the notes are in the Notebook — ready to share, expand, or turn into action items. + +**Research projects** — Save key findings, quotes, and summaries as you go. Build a reference library that grows with each conversation. + +**Learning and study** — Have your Agent explain a concept, then save the explanation to the Notebook. Review it later or ask for clarifications in a follow-up. + +**Project documentation** — Keep decisions, specs, and progress notes in one place. Each Topic can hold the docs for a specific project or phase. + +## Notebook vs. Other Features + +| Feature | Best For | +| -------------------------------------------------------- | ----------------------------------------------------------------------------------------- | +| **Notebook** | Documents tied to a Topic — notes, reports, research within a conversation thread | +| [Pages](/docs/usage/getting-started/page) | Standalone long-form documents — co-written with Agents, not bound to a single Topic | +| [Resource Library](/docs/usage/getting-started/resource) | Knowledge base — upload files for Agents to search and reference across all conversations | + +Use Notebook when the document belongs to a specific conversation. Use Pages when you're building a document that stands on its own. + +## Tips + +- **Name documents when saving** — "Save this as 'Q1 Planning Notes'" helps you find it later. +- **Combine with GTD** — Save meeting notes to the Notebook, then ask your Agent to extract action items into GTD tasks. +- **Edit in Drafts for long edits** — For substantial changes, use "Edit in Drafts" to work in the full Pages editor, then sync back. + + + + + + + + diff --git a/docs/usage/agent/notebook.zh-CN.mdx b/docs/usage/agent/notebook.zh-CN.mdx index 6c03ca3677..cc9dc5b03f 100644 --- a/docs/usage/agent/notebook.zh-CN.mdx +++ b/docs/usage/agent/notebook.zh-CN.mdx @@ -1,24 +1,25 @@ --- title: 笔记本 -description: 了解如何使用定时任务，包括创建、编辑、删除等。 +description: 在对话中保存和管理文档——笔记、报告、研究资料。话题级存储，随时可查。 tags: - - 定时任务 - - 创建 - - 编辑 - - 删除 + - LobeHub + - 笔记本 + - 文档管理 + - 笔记 + - 话题 --- # 笔记本 -LobeHub 支持笔记本功能（Notebook），让你在对话中随时保存和管理文档。不再担心重要内容被遗忘，助理可以帮你记录笔记、保存报告、整理研究资料 —— 所有内容都留存在当前话题中，随时查阅。Notebook 突破了对话内容转瞬即逝的限制，将有价值的信息沉淀为可管理的文档。从会议纪要到学习笔记，从研究报告到待办清单，Notebook 让知识积累更系统、更持久。 +笔记本让你在对话中随时保存和管理文档。不再担心重要内容被遗忘 —— 助理可以帮你记录笔记、保存报告、整理研究资料。所有内容都留存在当前话题中，随时查阅。笔记本将有价值的信息沉淀为可管理的文档 —— 从会议纪要到学习笔记，从研究报告到待办清单。 -Notebook 是话题级别的文档存储空间。当对话中产生了值得保留的内容，助理可以将其保存到 Notebook 中，形成结构化的文档库。这些文档与当前话题关联，方便你在后续对话中查阅和引用。 +笔记本是话题级别的文档存储空间。当对话中产生了值得保留的内容，助理会将其保存到笔记本中，形成结构化的文档库。这些文档与当前话题关联，方便你在后续对话中查阅和引用。 -## Notebook 能做什么 +## 笔记本能做什么 ### 保存笔记和备忘 -助理可以帮你快速记录想法、待办事项、灵感片段。你只需说 "帮我记一下"，内容就会保存到 Notebook 中。 +助理可以帮你快速记录想法、待办事项、灵感片段。只需说「帮我记一下」，内容就会保存到笔记本中。 ### 整理研究资料 @@ -26,31 +27,69 @@ Notebook 是话题级别的文档存储空间。当对话中产生了值得保 ### 生成报告和文章 -助理可以帮你撰写结构化的报告、分析文档、长篇文章，并直接保存到 Notebook。你能随时查看、编辑、补充内容。 +助理可以帮你撰写结构化的报告、分析文档、长篇文章，并直接保存到笔记本。你能随时查看、编辑、补充内容。 ### 管理文档版本 -你可以让助理更新已有文档，追加新内容或修改现有内容。文档在 Notebook 中持续演进，保持最新状态。 +你可以让助理更新已有文档，追加新内容或修改现有内容。文档在笔记本中持续演进，保持最新状态。 -### 启用 Notebook 插件 +## 启用笔记本 -Notebook 是内置插件，需要为助理启用后才能使用文档管理功能。 +笔记本是内置技能。使用文档管理功能前需为助理启用。 -### 在助理档案中启用 +**从助理档案** — 进入助理档案页面，点击 **+ 添加技能 **，勾选**笔记本**。 -- 进入助理档案页面，点击「+ 集成技能」，勾选「Notebook」即可开启。 +**在会话中** — 点击对话框下方的技能图标，勾选**笔记本**。 -### 在会话中启用 - -- 进入会话页面，点击对话框下方技能图标，勾选「Notebook」即可。 - -### 使用 Notebook +## 使用笔记本 你可以让助理读取文档内容： -- "看一下之前保存的笔记" -- "那份报告写了什么" 删除文档当文档不再需要时，可以给助理发送指令删除或展开 Notebook 面板手动删除。查看和管理文档所有保存的文档都会显示在话题右侧 Notebook 面板中。右上角点击文稿图标即可呼出面板。你可以： +- 「看一下之前保存的笔记」 +- 「那份报告写了什么」 +- 「把研究文档的要点总结一下」 + +当文档不再需要时，可以给助理发送指令删除，或展开笔记本面板手动删除。 + +## 查看和管理文档 + +所有保存的文档都会显示在话题右侧的笔记本面板中。点击右上角文稿图标即可呼出面板。你可以： + - 浏览文档列表，查看标题和摘要 - 点击文档查看完整内容 - 直接在面板中编辑文档 -- 点击「在文稿中编辑」，将会话内文稿同步到「文稿」板块 +- 点击**在文稿中编辑**，将会话内文稿同步到「文稿」板块 + +## 使用场景 + +**会议跟进** — 开会时让助理记笔记。会议结束后，笔记已在笔记本中 —— 可直接分享、补充或提炼为待办事项。 + +**研究项目** — 边研究边保存关键发现、引用和摘要。随着每次对话，逐步积累成参考资料库。 + +**学习与复习** — 让助理解释一个概念，然后把解释保存到笔记本。之后复习或追问细节时，随时可查。 + +**项目文档** — 把决策、规格、进度记录集中在一处。每个话题可以承载一个具体项目或阶段的文档。 + +## 笔记本与其他功能 + +| 功能 | 最适合 | +| ---------------------------------------------- | ---------------------------- | +| **笔记本** | 与话题绑定的文档 —— 某次对话中的笔记、报告、研究资料 | +| [文稿](/zh/docs/usage/getting-started/page) | 独立的长文档 —— 与助理协作撰写，不绑定单一话题 | +| [资源库](/zh/docs/usage/getting-started/resource) | 知识库 —— 上传文件供助理在所有对话中搜索和引用 | + +文档属于某次具体对话时用笔记本；在写独立成篇的文档时用文稿。 + +## 使用技巧 + +- **保存时命名** — 「把这个保存为「Q1 规划笔记」」方便之后查找。 +- **与 GTD 配合** — 把会议纪要保存到笔记本，再让助理从中提取待办事项到 GTD 任务。 +- **长文档用文稿编辑** — 需要大改时，用「在文稿中编辑」在完整编辑器中修改，再同步回来。 + + + + + + + + diff --git a/docs/usage/agent/sandbox.mdx b/docs/usage/agent/sandbox.mdx index 36d0b20fb9..030d40f761 100644 --- a/docs/usage/agent/sandbox.mdx +++ b/docs/usage/agent/sandbox.mdx @@ -1,79 +1,107 @@ --- title: Cloud Sandbox description: >- - Learn how to use scheduled tasks, including creating, editing, and deleting - them. + Agents execute code and process files in a secure cloud environment — run + Python/JS, generate docs, create charts. Real execution, not just snippets. tags: - - Scheduled Tasks - - Create - - Edit - - Delete + - LobeHub + - Cloud Sandbox + - Code Execution + - File Generation + - Data Processing --- # Cloud Sandbox -LobeHub supports the Cloud Sandbox feature, enabling AI assistants to execute code and process files in a securely isolated cloud environment. Instead of merely providing code snippets, the assistant can directly run code, generate documents, and create charts — delivering downloadable results that you can iterate on in real time. Cloud Sandbox breaks the boundaries of traditional conversations, extending AI output from suggestions to actual execution. From data analysis to document generation, from code debugging to file conversion, Cloud Sandbox transforms AI into a true execution assistant. +Cloud Sandbox lets Agents run code and process files in a secure, isolated cloud environment. Instead of only suggesting code, your Agent executes it — and returns real output, downloadable documents, and charts you can iterate on in real time. From data analysis to report generation, code debugging to file conversion, Cloud Sandbox turns your Agent into a true execution partner. -## Understanding Cloud Sandbox +## What Is Cloud Sandbox? -Cloud Sandbox is a securely isolated cloud-based execution environment. When you need more than just code snippets and want actual execution results, the assistant will run the code in the Cloud Sandbox and return the output. +A securely isolated cloud execution environment. When you need actual results — not just code snippets — the Agent runs the code in the sandbox and returns the output. Your local machine stays untouched; all execution happens in the cloud. -## What Can Cloud Sandbox Do? +## What Cloud Sandbox Can Do ### Execute Code -The assistant can run Python, JavaScript, and TypeScript code within the sandbox and return the results. You’ll see real execution output, not just code text. +The Agent runs Python, JavaScript, and TypeScript in the sandbox and returns real execution output — not just code text. Common libraries (e.g., pandas, matplotlib for Python; lodash for JavaScript) are available. The Agent can install additional packages as needed. ### Generate Files -The assistant can create various types of files — PDF documents, Excel spreadsheets, Word documents, images, charts, and more — and provide download links. You can download and use them directly. +The Agent creates PDFs, Excel spreadsheets, Word documents, images, charts, and more — with download links. Download and use them directly in your workflow. ### Process Data -The assistant can read, analyze, and transform data files. Upload CSV, JSON, or other data formats, and the assistant can help clean, summarize, and visualize the data. +The Agent reads, analyzes, and transforms data files. Upload CSV, JSON, or other formats — the Agent can clean, summarize, visualize, and export the results. ### Run Commands -The assistant can execute shell commands to install dependencies, manipulate files, and perform complex operations. +The Agent executes shell commands to install dependencies, manipulate files, and perform complex operations. Useful for multi-step workflows that combine scripts and system tools. -### Enabling Cloud Sandbox +## Enabling Cloud Sandbox -Cloud Sandbox is a built-in plugin that must be enabled for the assistant to use its features. You can enable the Cloud Sandbox plugin from the "Assistant Profile" page under the plugin section, or directly within a conversation by checking the plugin option in the chat interface. +Cloud Sandbox is a built-in Skill. Enable it for your Agent before use. -### Using Cloud Sandbox +**From Agent Profile** — Go to the Agent Profile page, click **+ Add Skill**, and check **Cloud Sandbox**. -#### Ask the Assistant to Execute Code +**In a conversation** — Click the Skill icon below the chat input and check **Cloud Sandbox**. -Simply describe the task you want to accomplish, and the assistant will write and run the code in the Cloud Sandbox: +## Using Cloud Sandbox -- “Write a Python script to calculate the average and standard deviation of this dataset.” -- “Implement a quicksort algorithm in JavaScript and run a test.” -- “Run this code for me and show the output.” +### Ask the Agent to Execute Code -#### Ask the Assistant to Generate Documents +Describe the task; the Agent writes and runs the code: -Describe the content you need, and the assistant will generate the document and provide a download link: +- "Write a Python script to calculate the average and standard deviation of this dataset." +- "Implement a quicksort algorithm in JavaScript and run a test." +- "Run this code and show me the output." +- "Use pandas to analyze this CSV and show the top 5 rows by revenue." -- “Generate a PDF report with the analysis of this data.” -- “Convert this content into a Word document.” -- “Create an Excel spreadsheet to organize this information.” +### Ask the Agent to Generate Documents -#### Ask the Assistant to Process Data +Describe the content; the Agent generates the document and provides a download link: -Provide data or files, and the assistant will process and return the results: +- "Generate a PDF report with the analysis of this data." +- "Convert this content into a Word document." +- "Create an Excel spreadsheet to organize this information." +- "Make a bar chart from this sales data and export it as PNG." -- “Analyze this sales data and create a trend chart.” -- “Convert this JSON file to CSV format.” -- “Clean this dataset by removing duplicates.” +### Ask the Agent to Process Data -### Understanding the Cloud Sandbox Environment +Provide data or files; the Agent processes and returns results: -The Cloud Sandbox runs in a securely isolated cloud server, completely separate from your local machine. All operations performed by the assistant in the sandbox will not affect your local file system. +- "Analyze this sales data and create a trend chart." +- "Convert this JSON file to CSV format." +- "Clean this dataset by removing duplicates." +- "Merge these two CSV files on the 'id' column." -### Session-Based File Storage +## Use Cases -Files in the Cloud Sandbox are temporary and tied to the current conversation session. If the session ends or remains inactive for a long time, the sandbox files may be cleared. If you need to keep the files, be sure to download them using the export links provided by the assistant. +**Data analysis** — Upload a dataset, ask for summary statistics, visualizations, or trend analysis. Get charts and tables you can share in reports or presentations. -### Automatic Export of Results +**Report automation** — Generate weekly reports, invoices, or summaries from structured data. The Agent produces PDFs or Excel files ready to send. -When the assistant generates files in the Cloud Sandbox, they are automatically exported with download links. No extra steps are needed — you’ll receive documents, charts, data files, and other outputs directly from the code execution. +**Code prototyping** — Test algorithms, validate logic, or debug snippets without leaving the conversation. See real output instead of guessing. + +**File conversion** — Convert between formats (JSON ↔ CSV, Markdown → PDF) or batch-process files. No need to write one-off scripts yourself. + +## Understanding the Environment + +**Isolated execution** — The sandbox runs on a secure cloud server, completely separate from your local machine. Nothing the Agent does in the sandbox affects your local file system. + +**Session-based storage** — Files in the sandbox are temporary and tied to the current conversation. If the session ends or stays inactive for a long time, sandbox files may be cleared. Download files you need using the links the Agent provides. + +**Automatic export** — When the Agent generates files, they're automatically exported with download links. No extra steps — you get documents, charts, and data files directly from the execution. + +## Tips + +- **Be specific about format** — "Export as CSV" or "Save as PDF" helps the Agent choose the right output format. +- **Iterate in the same conversation** — "Make the chart blue" or "Add a title to the report" — the Agent has context and can refine the output. +- **Download important files promptly** — Session-based storage means files may not persist indefinitely. Grab what you need while the conversation is active. + + + + + + + + diff --git a/docs/usage/agent/sandbox.zh-CN.mdx b/docs/usage/agent/sandbox.zh-CN.mdx index 878bd4806f..1828106734 100644 --- a/docs/usage/agent/sandbox.zh-CN.mdx +++ b/docs/usage/agent/sandbox.zh-CN.mdx @@ -1,52 +1,58 @@ --- title: 云沙箱 -description: 了解如何使用定时任务，包括创建、编辑、删除等。 +description: 助理在安全云端环境中执行代码、处理文件——运行 Python/JS、生成文档、创建图表。真实执行，不只是代码片段。 tags: - - 定时任务 - - 创建 - - 编辑 - - 删除 + - LobeHub + - 云沙箱 + - 代码执行 + - 文件生成 + - 数据处理 --- # 云沙箱 -LobeHub 支持 Cloud Sandbox ，让 AI 助理能在安全隔离的云端环境中执行代码、处理文件。不只是给出代码片段，助理可以直接运行代码、生成文档、创建图表 —— 你能立即获得可下载的成果，实时迭代调整。云沙箱突破了传统对话的限制，将 AI 的输出从建议扩展到执行。从数据分析到文档生成，从代码调试到文件转换，云沙箱让 AI 真正成为你的执行助手。 +云沙箱让助理在安全隔离的云端环境中运行代码、处理文件。不只是给出代码建议，助理会直接执行 —— 返回真实输出、可下载的文档和图表，供你实时迭代。从数据分析到报告生成，从代码调试到文件转换，云沙箱让助理成为真正的执行伙伴。 -## 理解 Cloud Sandbox +## 什么是云沙箱？ -Cloud Sandbox 是一个安全隔离的云端执行环境。当你需要的不只是代码片段，而是实际运行结果时，助理会在 Cloud Sandbox 中执行代码并返回输出。 +一个安全隔离的云端执行环境。当你需要实际运行结果 —— 而不只是代码片段 —— 助理会在云沙箱中执行代码并返回输出。你的本地电脑不受影响，所有执行都在云端完成。 -## Cloud Sandbox 能做什么 +## 云沙箱能做什么 ### 执行代码 -助理可以运行 Python、JavaScript、TypeScript 代码，在沙盒中执行并返回结果。你能看到真实的运行输出，而不只是代码文本。 +助理在沙盒中运行 Python、JavaScript、TypeScript，返回真实的运行输出 —— 而不只是代码文本。常用库（如 Python 的 pandas、matplotlib，JavaScript 的 lodash）已预置。助理可按需安装其他依赖包。 ### 生成文件 -助理可以创建各种文件 ——PDF 文档、Excel 表格、Word 文档、图片、图表等，并提供下载链接。你能直接下载使用。 +助理可以创建 PDF、Excel、Word、图片、图表等各类文件，并提供下载链接。直接下载，即可用于你的工作流。 ### 数据处理 -助理可以读取、分析、转换数据文件。上传 CSV、JSON 等数据，助理能帮你清洗、统计、可视化。 +助理可以读取、分析、转换数据文件。上传 CSV、JSON 等格式，助理能帮你清洗、统计、可视化并导出结果。 ### 运行命令 -助理可以执行 Shell 命令，安装依赖包、处理文件、执行复杂操作。 +助理可以执行 Shell 命令，安装依赖、处理文件、执行复杂操作。适合需要结合脚本和系统工具的多步骤工作流。 -### 启用 Cloud Sandbox +## 启用云沙箱 -Cloud Sandbox 是内置插件，需要为助理启用后才能使用云沙箱功能。你可以在「助理档案」页面添加插件处启用 Cloud Sandbox 插件，也可以进入会话，在对话框勾选插件处启用 Cloud Sandbox 插件。 +云沙箱是内置技能。使用前需为助理启用。 -### 使用 Cloud Sandbox +**从助理档案** — 进入助理档案页面，点击 **+ 添加技能 **，勾选**云沙箱**。 + +**在会话中** — 点击对话框下方的技能图标，勾选**云沙箱**。 + +## 使用云沙箱 ### 让助理执行代码 -直接描述你想完成的任务，助理会编写代码并在云沙箱中运行： +描述任务，助理会编写代码并在云沙箱中运行： - 「帮我写个 Python 脚本，计算这组数据的平均值和标准差」 -- 「用 JavaScript 实现一个快速排序算法，运行测试一下」 +- 「用 JavaScript 实现快速排序算法，运行测试一下」 - 「帮我跑一下这段代码，看看输出是什么」 +- 「用 pandas 分析这个 CSV，按收入排序显示前 5 行」 ### 让助理生成文档 @@ -55,6 +61,7 @@ Cloud Sandbox 是内置插件，需要为助理启用后才能使用云沙箱功 - 「帮我生成一份 PDF 报告，包含这些数据的分析结果」 - 「把这段内容做成 Word 文档」 - 「创建一个 Excel 表格，整理这些信息」 +- 「用这份销售数据做个柱状图，导出成 PNG」 ### 让助理处理数据 @@ -63,11 +70,36 @@ Cloud Sandbox 是内置插件，需要为助理启用后才能使用云沙箱功 - 「分析这份销售数据，画个趋势图」 - 「把这个 JSON 转换成 CSV 格式」 - 「帮我清洗这份数据，去除重复项」 +- 「把这两个 CSV 按 id 列合并」 -### 了解云沙箱环境 +## 使用场景 -隔离的云端环境云沙箱运行在安全隔离的云端服务器上，与你的本地电脑完全分离。助理在云沙箱中的所有操作都不会影响你的本地文件系统。 +**数据分析** — 上传数据集，要求汇总统计、可视化或趋势分析。获得可直接用于报告或演示的图表和表格。 -### 会话级文件存储 +**报告自动化** — 从结构化数据生成周报、发票或摘要。助理产出可直接发送的 PDF 或 Excel 文件。 -云沙箱中的文件是临时的，与当前对话会话绑定。会话结束或长时间不活动后，沙箱中的文件可能会被清理。如果你需要保留文件，请及时下载助理提供的导出链接。自动导出成果当助理在云沙箱中生成文件时，会自动导出并提供下载链接。你无需额外操作，即可获得代码运行产生的文档、图表、数据文件等成果。 +**代码原型** — 在对话中测试算法、验证逻辑或调试代码片段。看到真实输出，而不是猜测。 + +**文件转换** — 在格式间转换（JSON ↔ CSV、Markdown → PDF）或批量处理文件。无需自己写一次性脚本。 + +## 了解云沙箱环境 + +**隔离执行** — 云沙箱运行在安全隔离的云端服务器上，与你的本地电脑完全分离。助理在沙箱中的所有操作都不会影响你的本地文件系统。 + +**会话级存储** — 云沙箱中的文件是临时的，与当前对话会话绑定。会话结束或长时间不活动后，沙箱中的文件可能会被清理。如需保留文件，请及时通过助理提供的下载链接保存。 + +**自动导出** — 助理在云沙箱中生成文件时，会自动导出并提供下载链接。无需额外操作，即可获得代码运行产生的文档、图表、数据文件等成果。 + +## 使用技巧 + +- **明确格式** — 「导出为 CSV」或「保存为 PDF」有助于助理选择正确的输出格式。 +- **在同一对话中迭代** — 「把图表改成蓝色」或「给报告加个标题」—— 助理有上下文，可以精调输出。 +- **及时下载重要文件** — 会话级存储意味着文件可能不会永久保留。在对话活跃时保存你需要的文件。 + + + + + + + + diff --git a/docs/usage/agent/scheduled-task.mdx b/docs/usage/agent/scheduled-task.mdx index ebd4f1dfff..9685695e0c 100644 --- a/docs/usage/agent/scheduled-task.mdx +++ b/docs/usage/agent/scheduled-task.mdx @@ -14,42 +14,127 @@ tags: # Scheduled Tasks -Scheduled tasks are jobs that run periodically in the cloud. - -In simple terms, you can configure an Agent to execute tasks based on your prompt at regular intervals—for example, checking social media content and sending notifications on a schedule. +Scheduled tasks are jobs that run periodically in the cloud. In simple terms, you can configure an Agent to execute tasks based on your prompt at regular intervals — for example, checking social media content and sending notifications on a schedule. Instead of manually triggering the same workflow repeatedly, schedule it once and let it run automatically — daily, weekly, or hourly. ## Creating a Task Find Scheduled Tasks in the left panel of the Agent conversation page, and click `Add Scheduled Task` to start creating a task. -On the creation page, you can fill in the task name, set the task frequency and specific execution time, set the maximum number of times the task can be executed, and configure the task content. - ![Create Task](https://file.rene.wang/clipboard-1770261091677-74b74e4d6bf23.png) -In the Task Content area, you can enter the Prompt or instructions to provide to the Agent. For example, the task content to be completed, whether to call plugins, etc. Each scheduled trigger will fully execute the content defined here. After creation, you can modify the scheduled task configuration at any time. +### Configuration Fields -## Pausing a Task +**Task Name** — Give your task a descriptive name so you can identify it at a glance: -If you temporarily don't need a scheduled task, you can disable it. After disabling, the task will no longer execute automatically, but the task's execution plan and Prompt configuration will be preserved. The task will resume execution after re-enabling. +- ✅ "Daily Market Summary - 9am EST" +- ✅ "Weekly Competitor Analysis" +- ❌ "Task 1" + +**Task Content** — Enter the prompt or instructions for the Agent to execute each time the task runs. Be specific and complete — this exact prompt runs every scheduled execution. For example: + +``` +Analyze today's top tech news and summarize: +1. Major product launches +2. Funding announcements +3. Industry trends +Format as a brief executive summary. +``` + +**Frequency** — Choose how often the task runs: + +- **Daily** — Every day at a specified time +- **Weekly** — Specific days of the week at a specified time (you can select multiple days) +- **Hourly** — Every 1, 2, 6, 12, or 24 hours + +**Time and Timezone** — Specify the exact time of day and your timezone so the task runs at the correct local time. Times are in 24-hour format. Timezone selection is especially important for teams across multiple regions. + +**Max Executions** — Optionally limit how many times the task runs total. Leave unlimited for ongoing tasks. Set a number (e.g., 30) for time-limited campaigns — the task disables automatically after reaching the limit. + +After creation, you can modify the scheduled task configuration at any time. + +## Schedule Configuration Examples + +**Daily morning report:** + +- Frequency: Daily at 08:00 in your timezone +- Prompt: "Generate a summary of yesterday's key metrics and action items for today." + +**Weekly planning session:** + +- Frequency: Weekly on Mondays at 09:00 +- Prompt: "Review last week's progress and create this week's priority list." + +**Hourly monitoring:** + +- Frequency: Every 2 hours +- Prompt: "Check for any critical alerts or anomalies and summarize findings." + +**End-of-month review:** + +- Frequency: Monthly — set Max Executions to 1 per month, or use day-of-month scheduling +- Prompt: "Analyze this month's performance data and generate an executive report." + +## Managing Tasks + +### Viewing Run History + +Each scheduled run creates a conversation in the agent's conversation history, labeled with the task name and timestamp. Review outputs, check for errors, and track results over time. + +### Editing a Schedule + +Click on a scheduled task to modify it — update the prompt, change the frequency or time, or adjust the timezone. Changes take effect on the next scheduled execution. + +### Pausing a Task + +If you temporarily don't need a scheduled task, you can disable it. After disabling, the task will no longer execute automatically, but the task's execution plan and prompt configuration will be preserved. The task resumes after re-enabling. ![Pause Task](https://file.rene.wang/clipboard-1770266335710-1fec523143aab.png) -## Deleting a Task +### Deleting a Task -If you no longer need a scheduled task, you can delete it. After deletion, the task's execution plan and Prompt configuration will be removed, and the system will no longer trigger any subsequent executions. +If you no longer need a scheduled task, you can delete it. After deletion, the task's execution plan and prompt configuration are removed, and the system will no longer trigger any subsequent executions. Past conversation history is preserved. + +## Best Practices + +**Write clear, self-contained prompts** — The task prompt runs without any prior conversation context. Every detail the Agent needs must be in the prompt itself: + +- ✅ "Search for news about electric vehicles published in the last 24 hours and summarize the top 3 developments." +- ❌ "Check the news like we discussed." (Agent has no conversation context when scheduled) + +**Choose appropriate frequency** — Match the schedule to the actual cadence of the information you're monitoring. Hourly monitoring for daily news is unnecessary overhead; weekly reports for real-time metrics miss the point. + +**Use descriptive task names** — Include the purpose and schedule in the name: "Weekly Competitor Analysis - Monday 9am" is far more useful than "Task 2". + +**Set max executions for experiments** — When testing a new scheduled task, set a max execution count of 5–10 so it doesn't run indefinitely if the prompt doesn't work as expected. + +**Timezone awareness** — Always set the correct timezone. A task scheduled for "9:00 AM" defaults to the server timezone, which may differ from your local time. Misconfigured timezones are a common source of unexpected run times. ## Use Cases -Scheduled tasks are suitable for all work scenarios that have a fixed rhythm, require continuous follow-up, or need periodic delivery of results. Here are some common and frequently used approaches. - ### Periodic Social Media Monitoring with Notifications -You can set up scheduled tasks to periodically check social media content related to specified platforms or keywords. The task will automatically fetch the latest updates, filter information that meets the criteria, and generate summaries or trigger notifications when important updates are detected. This scenario is suitable for brand reputation monitoring, competitor tracking, creator content update alerts, and more. You only need to view the results without repeatedly searching manually. +Set up scheduled tasks to periodically check social media content related to specified platforms or keywords. The task automatically fetches the latest updates, filters information that meets the criteria, and generates summaries when important updates are detected. Suitable for brand reputation monitoring, competitor tracking, and creator content update alerts. ### Periodic Summary and Report Generation -For work that requires regular review, such as data analysis, project progress tracking, or content performance evaluation, you can use scheduled tasks to automatically complete aggregation and analysis. The task will collect relevant information at specified times and output structured conclusions, helping you continuously track trend changes without having to organize from scratch each time. +For work that requires regular review — data analysis, project progress tracking, or content performance evaluation — use scheduled tasks to automatically complete aggregation and analysis. The task collects relevant information at specified times and outputs structured conclusions, helping you continuously track trend changes. ### Scheduled Reminder Notifications -You can set up reminders in advance for items that need attention, such as work to be handled, important milestones, periodic check tasks, etc., and let LobeHub automatically generate reminder messages and notify you via email or other methods without manual triggering. This approach is suitable for personal to-do reminders, important event notifications, periodic task prompts, and other scenarios, helping you receive clear action prompts at the right time and leaving the things you need to remember to the system. +Set up reminders in advance for important milestones, periodic check tasks, or items needing attention. LobeHub automatically generates reminder messages and notifies you via email or other methods without manual triggering. + +## Troubleshooting + +**Task didn't run at expected time** — Check the timezone setting. The scheduled time is relative to your configured timezone, not necessarily your local timezone. Also verify the task is in "enabled" status. + +**Unexpected run times** — Verify you haven't confused AM/PM in 24-hour format (e.g., 17:00 = 5:00 PM, not 5:00 AM). + +**Poor quality outputs** — The scheduled prompt runs without conversational context. Rewrite the prompt to be fully self-contained, including all necessary context, data sources, and formatting instructions. + +**Too many runs** — Set a `Max Executions` limit when experimenting with new tasks. Delete and recreate a task if it has exceeded expectations. + + + + + + diff --git a/docs/usage/agent/scheduled-task.zh-CN.mdx b/docs/usage/agent/scheduled-task.zh-CN.mdx index 222472c385..aeefa6c8b8 100644 --- a/docs/usage/agent/scheduled-task.zh-CN.mdx +++ b/docs/usage/agent/scheduled-task.zh-CN.mdx @@ -3,7 +3,7 @@ title: 定时任务 description: 了解如何使用定时任务，包括创建、编辑、删除等。 tags: - LobeHub - - CornJob + - CronJob - 定时任务 - 创建 - 编辑 @@ -12,42 +12,127 @@ tags: # 定时任务 -定时任务是定期在云端执行的任务。 - -简单来说，你可以让 Agent 定期根据你的 Prompt 去执行任务，例如定期检查社交媒体内容并发送通知。 +定时任务是定期在云端执行的任务。简单来说，你可以让 Agent 定期根据你的 Prompt 去执行任务 —— 例如定期检查社交媒体内容并发送通知。无需反复手动触发同一工作流，设置一次即可按计划自动运行 —— 每天、每周或每小时均可。 ## 创建任务 在 Agent 会话页面左侧面板找到定时任务，点击 `添加定时任务` 开始创建任务。 -在创建页面，你可以填写任务名称，设置任务频率和具体的执行时间，设定任务最多执行的次数，配置任务内容。 - ![创建任务](https://file.rene.wang/clipboard-1770261091677-74b74e4d6bf23.png) -在 Task Content 区域，你可以输入提供给 Agent 的 Prompt 或指令。例如需要完成的任务内容、是否调用插件等。每一次定时触发，都会完整执行这里定义的内容。创建完成后，你可以随时修改定时任务的配置。 +### 配置字段说明 -## 暂停任务 +**任务名称** — 为任务起一个描述性的名称，方便一眼识别： -如果暂时不需要某个定时任务，可以关闭启用状态。关闭启用状态后，任务不再自动执行，该任务的执行计划、Prompt 配置都会保留。恢复启用状态后该任务会继续执行。 +- ✅ "每日市场摘要 - 上午 9 点" +- ✅ "每周竞品分析" +- ❌ "任务 1" + +**任务内容** — 填写每次触发时 Agent 需要执行的 Prompt 或指令。内容要具体完整 —— 这段提示词会在每次计划执行时原样运行。例如： + +``` +分析今日科技新闻热点并总结： +1. 主要产品发布 +2. 融资公告 +3. 行业趋势 +以简明执行摘要的形式输出。 +``` + +**执行频率** — 选择任务的运行频率： + +- **每天** — 每天在指定时间执行 +- **每周** — 每周指定星期的指定时间（可选多天） +- **每小时** — 每隔 1、2、6、12 或 24 小时执行 + +**时间与时区** — 指定具体执行时间和时区，确保任务在正确的本地时间运行。时间采用 24 小时制。对于跨地区团队，时区设置尤为重要。 + +**最大执行次数** — 可选设置任务的总执行次数上限。长期任务无需限制；对于限时活动（如 30 天），可设置为 30，任务在达到上限后自动停用。 + +创建完成后，你可以随时修改定时任务的配置。 + +## 计划配置示例 + +**每日晨报：** + +- 频率：每天 08:00（你的时区） +- Prompt："总结昨日的关键指标，并列出今日优先事项。" + +**每周计划会议：** + +- 频率：每周一 09:00 +- Prompt："回顾上周进展，制定本周优先级列表。" + +**每小时监控：** + +- 频率：每 2 小时 +- Prompt："检查是否有关键告警或异常，并汇总发现。" + +**月度复盘：** + +- 频率：按月，可将最大执行次数设为每月 1 次，或配合特定日期使用 +- Prompt："分析本月绩效数据，生成执行报告。" + +## 管理任务 + +### 查看执行历史 + +每次定时执行都会在该 Agent 的对话历史中创建一条记录，并标注任务名称和时间戳。你可以查看输出内容、核查错误并追踪历史结果。 + +### 编辑计划 + +点击定时任务即可修改 —— 更新 Prompt、调整频率或时间、修改时区。更改在下次计划执行时生效。 + +### 暂停任务 + +如果暂时不需要某个定时任务，可以关闭启用状态。关闭后，任务不再自动执行，执行计划和 Prompt 配置会保留。恢复启用后，该任务将继续执行。 ![暂停任务](https://file.rene.wang/clipboard-1770266335710-1fec523143aab.png) -## 删除任务 +### 删除任务 -如果不再需要某个定时任务，可以将其删除。删除任务后，该任务的执行计划、Prompt 配置都会一并移除，系统将不再触发任何后续执行。 +如果不再需要某个定时任务，可以将其删除。删除后，执行计划和 Prompt 配置一并移除，系统将不再触发后续执行。历史对话记录会保留。 + +## 最佳实践 + +**编写清晰、自包含的 Prompt** — 定时任务的 Prompt 运行时没有任何历史对话上下文，Agent 所需的所有信息都必须包含在 Prompt 中： + +- ✅ "搜索过去 24 小时内发布的新能源汽车相关新闻，总结前 3 条重要进展。" +- ❌ "按我们讨论的那样检查新闻。"（计划运行时 Agent 无法访问历史对话） + +**选择合适的频率** — 频率应与所监控信息的实际节奏匹配。对每日新闻进行每小时监控是多余的开销；对实时指标进行每周报告会漏掉重要信息。 + +**使用描述性任务名称** — 在名称中体现用途和计划："每周竞品分析 - 周一上午 9 点" 远比 "任务 2" 更实用。 + +**实验时设置最大执行次数** — 测试新定时任务时，将最大执行次数设为 5–10，避免提示词效果不符合预期时无限运行。 + +**时区意识** — 务必设置正确的时区。"09:00" 默认相对于服务器时区，可能与你的本地时间不同。时区配置错误是导致执行时间意外的常见原因。 ## 使用场景 -定时任务适用于所有具备固定节奏、需要持续跟进或定期交付结果的工作场景。以下是一些常见且高频的使用方式。 - ### 定期检查社交媒体内容并发送通知 -你可以设置定时任务，周期性检查指定平台或关键词相关的社交媒体内容。任务会自动抓取最新动态，筛选符合条件的信息，并在检测到重要更新时生成摘要或触发通知。这一场景适合用于品牌舆情监测、竞品动态跟踪、创作者内容更新提醒等。你只需查看结果，无需反复手动搜索。 +设置定时任务，周期性检查指定平台或关键词相关的社交媒体内容。任务会自动抓取最新动态，筛选符合条件的信息，并在检测到重要更新时生成摘要。适合品牌舆情监测、竞品动态跟踪、创作者内容更新提醒等场景。 ### 周期性生成总结与报告 -对于需要定期复盘的工作，例如数据分析、项目进展跟踪或内容表现评估，可以通过定时任务自动完成汇总和分析。任务会在指定时间收集相关信息，输出结构化结论，帮助你持续掌握趋势变化，而不必每次从零整理。 +对于需要定期复盘的工作 —— 数据分析、项目进展跟踪或内容表现评估 —— 可以通过定时任务自动完成汇总和分析。任务在指定时间收集相关信息，输出结构化结论，帮助你持续掌握趋势变化。 ### 定时提醒通知 -你可以提前设定需要提醒的事项，例如需要处理的工作、重要节点、周期性检查任务等，让 LobeHub 自动生成提醒信息并通过邮件等方式提醒，无需你手动触发。这一方式适合用于个人待办提醒、重要事项通知、周期性任务提示等场景，帮助你在正确的时间收到明确的行动提示，把需要记住的事情交给系统处理。 +提前设定需要提醒的事项 —— 重要节点、周期性检查任务或待处理工作等 —— 让 LobeHub 自动生成提醒信息并通过邮件等方式通知，无需手动触发。 + +## 故障排查 + +**任务未在预期时间执行** — 检查时区设置。计划时间相对于已配置的时区，而非你当前的本地时区。同时确认任务处于 "已启用" 状态。 + +**执行时间出现意外** — 核查是否在 24 小时制中混淆了上下午（如 17:00 = 下午 5 点，而非上午 5 点）。 + +**输出质量不佳** — 定时任务的 Prompt 在无对话上下文的情况下运行。请将 Prompt 改写为完全自包含的形式，包含所有必要的背景信息、数据来源和格式要求。 + +**执行次数过多** — 实验新任务时设置 "最大执行次数" 上限。如果任务已超出预期次数，可删除后重新创建。 + + + + + + diff --git a/docs/usage/agent/share.mdx b/docs/usage/agent/share.mdx index c5bdbf2963..937ed84d67 100644 --- a/docs/usage/agent/share.mdx +++ b/docs/usage/agent/share.mdx @@ -1,92 +1,114 @@ --- title: Share Conversations description: >- - Learn how to share conversation records using LobeHub's sharing features, - including screenshot sharing and ShareGPT links. Easily share your dialogues - with others. + Export and share your conversations — screenshot, text, PDF, or JSON. One + click to copy or download. tags: - LobeHub - - Share Conversation Records - - Screenshot Sharing - - Conversation Sharing + - Share + - Export + - Screenshot + - PDF + - JSON + - Link --- -# Share Conversation Records +# Share Conversations -You can share your current conversation with others by clicking the Share button in the top-right corner of the chat window. LobeHub supports two sharing methods: Screenshot Sharing and Shareable Link Generation. - -LobeHub allows you to export and share your conversations in various formats, including screenshots, plain text, PDF, or JSON, making it easy to save and share your dialogues. +Click the **Share** button in the top-right corner of the chat window to export and share your current conversation. LobeHub supports multiple formats — choose the one that fits how you want to use it. ## Screenshot Sharing -Export your conversation as an image. Available display modes: +Export your conversation as an image. Great for social media or messaging apps — visually intuitive and easy to read. -- Wide Screen Mode: Optimized for desktop viewing -- Narrow Screen Mode: Optimized for mobile viewing +**Display modes:** -Optional content settings: +- **Wide screen** — Optimized for desktop viewing +- **Narrow screen** — Optimized for mobile viewing -- Include Assistant Role Settings: Display system prompts and configuration for the assistant -- Include Footer: Show information at the bottom of the page -- Image Format Options: JPG / PNG / SVG / WEBP -- Sharing Options: - - Copy Image: Copy to clipboard for direct pasting into other apps - - Download Screenshot: Save the image file locally +**Optional content:** + +- Include Agent role settings (system prompt and configuration) +- Include footer (page bottom information) + +**Format:** JPG / PNG / SVG / WEBP + +**Actions:** Copy to clipboard for pasting into other apps, or download the image file. {'Screenshot ## Text Sharing -Export your conversation as plain text. Optional content settings: +Export as plain text. Ideal for editing or quoting — small file size. -- Include Assistant Role Settings: Include system prompts and assistant configuration -- Include Message Roles: Show the sender of each message -- Include User Info: Include user-related information -- Include Plugin Info: Include details of plugin calls -- Sharing Options: - - Copy Text: Copy to clipboard - - Download File: Save as a text file +**Optional content:** -![clipboard-1769056077960-cac34bc157a65.png](/blog/assetsa8e173bec038d1d21d413f6fa0ace342.webp) +- Include Agent role settings +- Include message roles (who sent each message) +- Include user info +- Include Skill/plugin call details + +**Actions:** Copy to clipboard, or download as a text file. + +![Text Sharing Export Options](/blog/assetsa8e173bec038d1d21d413f6fa0ace342.webp) ## PDF Sharing -Export your conversation as a PDF document. Optional content settings: +Export as a PDF document. Suitable for formal use — work reports, study notes, archival. -- Include Assistant Role Settings: Include system prompts and assistant configuration -- Include Message Roles: Show the sender of each message -- Include User Info: Include user-related information -- Include Plugin Info: Include details of plugin calls +**Optional content:** -Generation Method: After selecting your options, click the Generate button to create and download the PDF file. +- Include Agent role settings +- Include message roles +- Include user info +- Include Skill/plugin call details + +**Actions:** Click **Generate** to create and download the PDF. {'PDF ## JSON Sharing -Export your conversation in JSON format, ideal for developers or integration with other systems. +Export in JSON format — ideal for developers or integration with other systems. -Available export modes: +**Export modes:** -- Default: LobeHub's standard JSON format -- OpenAI Compatible: JSON format compatible with the OpenAI API +- **Default** — LobeHub's standard JSON format +- **OpenAI Compatible** — JSON format compatible with the OpenAI API -Optional content settings: +**Optional content:** -- Include Role Settings: Include assistant role configuration +- Include Agent role configuration -Sharing Options: - -- Copy: Copy JSON content to clipboard -- Download File: Save as a JSON file +**Actions:** Copy JSON to clipboard, or download as a file. ## Use Cases -- Screenshot Sharing: Great for sharing conversations on social media or messaging apps—visually intuitive and easy to read. -- Text Sharing: Ideal for editing or quoting conversations; small file size. -- PDF Sharing: Suitable for formal use cases like work reports, study notes, or archival. -- JSON Sharing: Best for developers—can be imported into other systems or used for data analysis. +| Format | Best For | +| -------------- | ----------------------------------------------------- | +| **Screenshot** | Social media, messaging apps — visually intuitive | +| **Text** | Editing, quoting — small file size | +| **PDF** | Work reports, study notes, archival | +| **JSON** | Developers — import into other systems, data analysis | ## Shareable Link -Coming soon... +Generate a link to share your conversation publicly. Click the **Share** button in the top-right corner — if link sharing is available in your workspace, a popover appears instead of the modal directly. + +**Visibility options:** + +- **Private** — Only you can access the link. The conversation is not visible to others even if they have the URL. +- **Anyone with the link** — Anyone who has the link can view the full conversation. A privacy notice appears the first time you switch to this mode. + +**Actions:** + +- **Copy Link** — Copies the share URL to your clipboard. Share it via any channel. +- **More share options** — Opens the full share modal for screenshot, text, PDF, or JSON export. + +When someone opens the link, they see the full conversation in a clean read-only view. A bottom bar shows the Agent name and avatar, with quick links to explore the Agent Market or try the same agent themselves. + + + + + + diff --git a/docs/usage/agent/share.zh-CN.mdx b/docs/usage/agent/share.zh-CN.mdx index 2d229847c8..53ce91145f 100644 --- a/docs/usage/agent/share.zh-CN.mdx +++ b/docs/usage/agent/share.zh-CN.mdx @@ -1,60 +1,112 @@ --- title: 分享会话 -description: 了解如何通过 LobeHub 的分享功能分享会话记录，包括截图分享和 ShareGPT 分享方式。通过分享功能，轻松与他人分享您的对话。 +description: 导出并分享你的会话——截图、文本、PDF 或 JSON。一键复制或下载。 tags: - LobeHub - - 分享会话记录 - - 截图分享 - - 对话分享 + - 分享 + - 导出 + - 截图 + - PDF + - JSON + - 链接 --- -# 分享会话记录 +# 分享会话 -通过会话窗口右上角的`分享`按钮，您可以将当前会话记录分享给其他人。LobeHub 支持两种分享方式：`截图分享`和 `生成分享链接`。 - -LobeHub 支持将会话内容分享给他人。你可以将对话导出为截图、文本、PDF 或 JSON 格式，方便保存、分享。 +点击会话窗口右上角的**分享**按钮，即可导出并分享当前会话。LobeHub 支持多种格式 —— 选择最适合你使用场景的方式。 ## 截图分享 -将会话导出为图片格式。可选显示模式： +将会话导出为图片。适合在社交媒体、聊天工具中分享 —— 直观易读。 -- 宽屏模式：适合电脑屏幕查看 -- 窄屏模式：适合手机屏幕查看 +**显示模式：** -可选内容选项： +- **宽屏模式** — 适合电脑屏幕查看 +- **窄屏模式** — 适合手机屏幕查看 -- 是否包含助手角色设定：显示助手的系统提示词等设定信息 -- 是否包含页脚：显示页面底部信息 -- 可选图片格式：JPG/PNG/SVG/WEBP -- 可选分享方式：复制图片：复制到剪贴板，可以直接粘贴到其他应用下载截图：保存图片文件到本地 +**可选内容：** + +- 是否包含助理角色设定（系统提示词等设定信息） +- 是否包含页脚（页面底部信息） + +**图片格式：** JPG / PNG / SVG / WEBP + +**操作：** 复制到剪贴板直接粘贴到其他应用，或下载图片文件到本地。 {'截图分享'} ## 文本分享 -将会话导出为纯文本格式。可选内容选项： +将会话导出为纯文本。适合需要编辑或引用对话内容的场景，文件体积小。 -- 是否包含助手角色设定：包含助手的系统提示词等设定是否包含消息角色 -- 显示每条消息的发送者 -- 是否包含用户信息：包含用户相关信息 -- 是否包含插件信息：包含插件调用的相关信息 -- 可选分享方式：复制文本：复制到剪贴板下载文件：保存为文本文件 +**可选内容：** -![clipboard-1769056077960-cac34bc157a65.png](/blog/assetsa8e173bec038d1d21d413f6fa0ace342.webp) +- 是否包含助理角色设定 +- 是否包含消息角色（每条消息的发送者） +- 是否包含用户信息 +- 是否包含技能 / 插件调用信息 + +**操作：** 复制到剪贴板，或下载为文本文件。 + +![导出纯文本分享选项](/blog/assetsa8e173bec038d1d21d413f6fa0ace342.webp) ## PDF 分享 -将会话导出为 PDF 文档。可选内容选项： +将会话导出为 PDF 文档。适合正式场合 —— 工作报告、学习笔记、存档记录。 -- 是否包含助手角色设定：包含助手的系统提示词等设定 -- 是否包含消息角色：显示每条消息的发送者 -- 是否包含用户信息：包含用户相关信息 -- 是否包含插件信息：包含插件调用的相关信息生成方式：选择完选项后，点击生成按钮，直接生成 PDF 文件并下载。 +**可选内容：** + +- 是否包含助理角色设定 +- 是否包含消息角色 +- 是否包含用户信息 +- 是否包含技能 / 插件调用信息 + +**操作：** 选择完选项后，点击**生成**按钮，直接生成 PDF 文件并下载。 {'PDF ## JSON 分享 -将会话导出为 JSON 格式，适合开发者或需要在其他系统中使用。可选导出模式：默认：LobeHub 的标准 JSON 格式 OpenAI 兼容：兼容 OpenAI API 格式的 JSON 可选内容选项：是否包含角色设定：包含助手的角色设定信息可选分享方式：复制：复制 JSON 内容到剪贴板下载文件：保存为 JSON 文件 \[Image] 使用场景截图分享：适合在社交媒体、聊天工具中分享对话内容，直观易读。文本分享：适合需要编辑或引用对话内容的场景，文件体积小。PDF 分享：适合正式场合，如工作报告、学习笔记、存档记录。JSON 分享：适合开发者，可以导入到其他系统或进行数据分析。 +将会话导出为 JSON 格式。适合开发者或需要在其他系统中使用。 + +**导出模式：** + +- **默认** — LobeHub 的标准 JSON 格式 +- **OpenAI 兼容** — 兼容 OpenAI API 格式的 JSON + +**可选内容：** + +- 是否包含助理角色设定 + +**操作：** 复制 JSON 内容到剪贴板，或下载为 JSON 文件。 + +## 使用场景 + +| 格式 | 最适合 | +| -------- | ------------------- | +| **截图** | 社交媒体、聊天工具 —— 直观易读 | +| **文本** | 编辑、引用 —— 文件体积小 | +| **PDF** | 工作报告、学习笔记、存档记录 | +| **JSON** | 开发者 —— 导入到其他系统、数据分析 | ## 分享链接 + +生成链接，将当前会话公开分享给他人。点击右上角的**分享**按钮 —— 如果你的工作区支持链接分享功能，会先弹出一个快捷面板，而不是直接打开分享弹窗。 + +**可见性设置：** + +- **私密** — 仅你本人可以访问，即使他人获得链接也无法查看内容。 +- **任何拥有链接的人** — 任何人通过链接即可查看完整会话内容。首次切换到此模式时，会显示隐私提示确认。 + +**操作：** + +- **复制链接** — 将分享链接复制到剪贴板，通过任意渠道发送给他人。 +- **更多分享选项** — 打开完整分享弹窗，可导出截图、文本、PDF 或 JSON 格式。 + +他人打开链接后，将看到完整的只读会话页面。页面底部会显示助理名称和头像，并提供快捷入口，跳转到 Agent 市场探索更多助理，或直接体验同款助理。 + + + + + + diff --git a/docs/usage/agent/topic.mdx b/docs/usage/agent/topic.mdx index f11ab63902..924e5edd5c 100644 --- a/docs/usage/agent/topic.mdx +++ b/docs/usage/agent/topic.mdx @@ -1,59 +1,76 @@ --- title: Topics description: >- - Learn how to interact with large language models, including model selection, - file/image uploads, temperature settings, conversation history, and more. + Organize, search, and manage your conversations with Topics — favorite what + matters, find anything fast. tags: - LobeHub - - Large Language Model - - LLM - - Model Selection - - File Upload - - Temperature Setting - - History Settings - - Voice Input - - Plugin Settings - - Token Usage - - New Topic - - Send Button + - Topics + - Conversation Management + - Search + - Favorites --- # Topics -In LobeHub, each conversation with the assistant is organized into a topic. You can search, rename, favorite, or delete topics to better manage and retrieve your past conversations. +In LobeHub, each conversation with an Agent is organized as a Topic. Topics give you a structured way to manage your conversation history — search across them, rename for clarity, favorite what you return to often, and clean up what you no longer need. ## Search Topics -On the conversation page, you can search for previous topics you've discussed with the assistant. Enter the conversation view, click "More" in the topic list, and use the search function to quickly locate the desired conversation. +On the conversation page, click **More** in the topic list to open the search. Type a keyword to quickly find the conversation you're looking for — no need to scroll through everything. -![clipboard-1769000274218-d02c4c8024709.png](/blog/assets3cdf933016e6f53bca12b8cedb17061f.webp) +![Search Topics in Conversation](/blog/assets3cdf933016e6f53bca12b8cedb17061f.webp) ## Rename Topics -You can give topics more meaningful names to make them easier to identify. +Give Topics meaningful names so they're easy to identify at a glance. -- Manual Rename: Locate the topic you want to rename, click "Rename", enter a new name, and save it. -- Smart Rename: Click "Smart Rename" on the topic you want to rename, and the system will automatically generate a suitable name based on the conversation content. +- **Manual rename** — Find the Topic, click **Rename**, type a new name, and save. +- **Smart rename** — Click **Smart Rename** on the Topic and the system generates a name based on the conversation content automatically. ## Duplicate Topics -You can create a duplicate of any topic to preserve the original conversation while branching off into a new direction. Find the topic you want to copy and click "Duplicate". The system will create an identical copy of the topic. This is useful for exploring different discussion paths based on the same starting point. +Create a copy of any Topic to preserve the original conversation while branching off in a new direction. Find the Topic, click **Duplicate** — an identical copy is created. Useful for exploring different discussion paths from the same starting point. + +**When to duplicate:** You want to try a different approach without losing the original thread. For example, "What if we used a different architecture?" — duplicate the Topic, ask the new question, and compare the two branches later. ## Favorite Topics -For important or frequently used topics, you can mark them as favorites. Click the favorite icon on the topic you want to save. Favorited topics will appear in the "Favorites" section of the topic list for quick access. +Mark important or frequently used Topics as favorites. Click the favorite icon on the Topic. Favorited Topics appear in the **Favorites** section of the topic list for quick access. -![clipboard-1769000328858-48f0503640245.png](/blog/assets04d6fae3d9aa3c33697028f1cc9f4706.webp) +![Favorite Topics](/blog/assets04d6fae3d9aa3c33697028f1cc9f4706.webp) ## Delete Topics -You can delete topics you no longer need. Locate the topic, click "Delete", and confirm the action. The topic will be removed from your list. +Find the Topic you want to remove, click **Delete**, and confirm. The Topic is removed from your list. Deletion is permanent — the conversation and any Notebook documents in that Topic are removed. ## Topic List -Topics are organized by time to help you easily find conversations from different periods. +Topics are organized by time to help you find conversations from any period. -- Favorites: Displays all your favorited topics. -- Time-Based List: Other topics are automatically grouped by their creation time. Expand a time group to view all topics from that period. +- **Favorites** — All your favorited Topics, always at the top. +- **Time-Based Groups** — Other Topics are automatically grouped by creation time. Expand a group to see all Topics from that period. -If you prefer not to use time-based grouping, you can switch to "Ungrouped" view. +If you'd rather see everything in a flat list, switch to **Ungrouped** view. + +## Use Cases + +**Project-based organization** — Create a Topic per project or client. All discussions, notes, and outputs for that project stay in one place. + +**Experiment with ideas** — Duplicate a Topic before trying a risky or divergent approach. Keep the original intact while exploring alternatives. + +**Quick access to frequent work** — Favorite Topics you return to daily (e.g., "Daily standup notes", "Code review assistant"). They stay at the top of the list. + +**Cleanup and focus** — Delete completed or abandoned Topics to keep your list manageable. Search and favorites make it easy to find what matters. + +## Tips + +- **Use Smart Rename for long conversations** — Let the system suggest a name based on content; you can always edit it later. +- **Favorite before you need it** — If you know you'll come back to a Topic, favorite it now. Saves time when you're in a hurry. +- **Duplicate instead of starting over** — When a conversation branches, duplicate rather than copying content into a new Topic. You keep the full context. + + + + + + diff --git a/docs/usage/agent/topic.zh-CN.mdx b/docs/usage/agent/topic.zh-CN.mdx index 70284981aa..8d7bc8eabb 100644 --- a/docs/usage/agent/topic.zh-CN.mdx +++ b/docs/usage/agent/topic.zh-CN.mdx @@ -1,57 +1,74 @@ --- title: 话题 -description: 了解如何使用大型语言模型进行基本交互，包括模型选择、文件/图片上传、温度设置、历史记录设置等。 +description: 用话题组织、搜索和管理你的对话——收藏重要内容，随时快速找到任何历史对话。 tags: - LobeHub - - 大型语言模型 - - LLM - - 模型选择 - - 文件上传 - - 温度设置 - - 历史记录设置 - - 语音输入 - - 插件设置 - - Token 用量 - - 新建话题 - - 发送按钮 + - 话题 + - 对话管理 + - 搜索 + - 收藏 --- # 话题 -在 LobeHub 中，每次与助手的对话会形成一个话题。你可以搜索、重命名、收藏、删除话题，方便管理和查找历史对话。 +在 LobeHub 中，每次与助理的对话以话题的形式组织管理。话题让你的对话历史有序可查 —— 搜索任意内容、重命名方便识别、收藏常用话题、清理不再需要的记录。 ## 搜索话题 -在会话页面，你可以搜索与助手聊过的话题。进入会话，点击话题列表的「更多」，通过搜索话题快速找到需要的历史对话。 +进入会话页面，点击话题列表的**更多**展开搜索。输入关键词，快速定位你想找的历史对话，无需逐条翻阅。 -![clipboard-1769000274218-d02c4c8024709.png](/blog/assets3cdf933016e6f53bca12b8cedb17061f.webp) +![在对话中搜索话题](/blog/assets3cdf933016e6f53bca12b8cedb17061f.webp) ## 重命名话题 -你可以为话题设置更有意义的名称，方便识别。 +为话题设置有意义的名称，一眼就能认出来。 -- 手动重命名：找到要重命名的话题后点击「重命名」，输入新的话题名称并即可保存。 -- 智能重命名：找到要重命名的话题后点击「智能重命名」，系统会根据对话内容自动生成合适的名称。 +- **手动重命名** — 找到要重命名的话题，点击**重命名**，输入新名称保存即可。 +- **智能重命名** — 点击**智能重命名**，系统根据对话内容自动生成合适的名称。 ## 创建话题副本 -你可以创建某个话题的副本，保留原对话的同时创建新的分支。找到要复制的话题后点击「创建副本」，系统会创建一个完全相同的话题副本。适合在原对话基础上尝试不同的讨论方向。 +保留原对话的同时开辟新方向 —— 找到要复制的话题，点击**创建副本**，系统生成一个完全相同的副本。适合在同一起点上尝试不同的讨论路径。 + +**何时复制：** 想尝试另一种思路，又不想丢掉原对话。例如「如果换一种架构会怎样？」—— 复制话题、提出新问题，之后可以对比两条分支。 ## 收藏话题 -对于重要或常用的话题，可以点击收藏按钮进行收藏。找到要收藏的话题后点击收藏按钮，话题会被标记为收藏。收藏的话题会显示在话题列表的「收藏」列表里，方便快速访问。\[Image] +对于重要或常用的话题，点击收藏图标进行标记。收藏的话题会显示在话题列表的**收藏**区域，方便快速访问。 -![clipboard-1769000328858-48f0503640245.png](/blog/assets04d6fae3d9aa3c33697028f1cc9f4706.webp) +![收藏话题](/blog/assets04d6fae3d9aa3c33697028f1cc9f4706.webp) ## 删除话题 -不需要的话题可以删除。找到要删除的话题后点击「删除」，确认删除后话题将被移除。话题列表话题列表按时间组织，方便查找不同时期的对话。收藏列表：显示所有收藏的话题。时间列表：其他话题默认根据创建时间自动分组，展开对应时间的列表，可以查看该时间段的所有话题。如果不想使用时间分组，可以选择「不分组」。 +找到要删除的话题，点击**删除**并确认。话题将从列表中移除。删除为永久操作 —— 该话题下的对话和笔记本文档会一并移除。 ## 话题列表 -话题列表按时间组织，方便查找不同时期的对话。 +话题按时间组织，方便查找不同时期的对话。 -- 收藏列表：显示所有收藏的话题。 -- 时间列表：其他话题默认根据创建时间自动分组，展开对应时间的列表，可以查看该时间段的所有话题。 +- **收藏列表** — 所有收藏的话题，始终置顶显示。 +- **时间分组** — 其他话题按创建时间自动分组。展开对应时间段，查看该时期的所有话题。 -如果不想使用时间分组，可以选择「不分组」。 +如果你更喜欢看到所有话题的平铺列表，可以切换为**不分组**视图。 + +## 使用场景 + +**按项目组织** — 每个项目或客户建一个话题。该项目的所有讨论、笔记和产出都集中在一处。 + +**尝试不同思路** — 在尝试有风险或偏离原方向的想法前，先复制话题。保留原对话，同时探索其他可能。 + +**快速访问常用工作** — 收藏你每天都会回到的话题（如「每日站会笔记」「代码审查助理」）。它们会始终排在列表顶部。 + +**清理与聚焦** — 删除已完成或不再使用的话题，让列表更清爽。搜索和收藏让你能快速找到重要内容。 + +## 使用技巧 + +- **长对话用智能重命名** — 让系统根据内容生成名称，之后可随时手动修改。 +- **提前收藏** — 知道会再回来时，现在就收藏。赶时间时能省不少事。 +- **复制而非重开** — 对话出现分支时，复制话题而不是把内容拷到新话题。这样能保留完整上下文。 + + + + + + diff --git a/docs/usage/agent/translate.mdx b/docs/usage/agent/translate.mdx index 48ba039363..d3e055c313 100644 --- a/docs/usage/agent/translate.mdx +++ b/docs/usage/agent/translate.mdx @@ -1,32 +1,56 @@ --- title: Conversation Translation description: >- - LobeHub allows users to instantly translate conversation content into a - selected language, displaying the results in real time. Learn how to configure - your translation model for an optimized experience. + Translate conversation content into any language with one click — real-time + display, configurable model. Break language barriers in your workflow. tags: - LobeHub - - Conversation Translation + - Translation - Real-Time Translation - - Translation Model Configuration + - Multilingual --- # Translate Conversation History +LobeHub lets you translate conversation content into a target language with a single click. Select a language, and the pre-configured AI model performs the translation and displays the results in real time within the chat window. No need to copy-paste into external tools — translation happens right where you're working. + {'Translate ## Translate Content Within Conversations -LobeHub enables users to translate conversation content into a target language with a single click. Once a language is selected, LobeHub will use the pre-configured AI model to perform the translation and display the results in real time within the chat window. +Click the translate option on any message to convert it to your chosen language. The translation appears inline, so you can read the original and translated text side by side. Useful for: + +- **Understanding responses** — When the Agent replies in a language you're less fluent in, translate to your preferred language. +- **Sharing with others** — Translate a conversation before sharing so recipients can read it in their language. +- **Learning** — Compare original and translated text to improve your language skills. +- **Cross-language collaboration** — Team members can work in their preferred language; translate as needed to stay aligned. {'Display ## Configure Translation Model -You can specify which model you'd like to use as your translation assistant in the settings. +You can specify which model to use for translation. A capable model produces more accurate and natural translations, especially for technical or nuanced content. {'Configure -- Open the `Settings` panel -- Navigate to the `System Assistant` section and find the `Translation Settings` option -- Assign a model to serve as your `Translation Assistant` +- Open the **Settings** panel +- Navigate to **System Assistant** and find **Translation Settings** +- Assign a model to serve as your **Translation Assistant** + +**Tips:** Use a model with strong multilingual capability (e.g., GPT-4o, Claude, Gemini) for best results. Smaller or older models may produce rougher translations. + +## Use Cases + +**International teams** — Communicate in your language; translate key messages for colleagues who prefer another. + +**Research and learning** — Read papers, articles, or documentation in the original language, then translate sections you need to understand deeply. + +**Customer support** — Respond in the customer's language, or translate their message to understand the issue before replying. + +**Content creation** — Draft in one language, translate to another for localization or multi-language publishing. + + + + + + diff --git a/docs/usage/agent/translate.zh-CN.mdx b/docs/usage/agent/translate.zh-CN.mdx index f093774ff3..87f6a9f61e 100644 --- a/docs/usage/agent/translate.zh-CN.mdx +++ b/docs/usage/agent/translate.zh-CN.mdx @@ -1,29 +1,54 @@ --- title: 会话翻译 -description: LobeHub 支持用户一键将对话内容翻译成指定语言，实时显示翻译结果。了解如何设置翻译模型以优化翻译体验。 +description: 一键将对话内容翻译成任意语言——实时显示，可配置模型。打破工作流中的语言障碍。 tags: - LobeHub - - 会话翻译 + - 翻译 - 实时翻译 - - 翻译模型设置 + - 多语言 --- # 翻译会话记录 +LobeHub 支持一键将对话内容翻译成目标语言。选择语言后，预先配置的 AI 模型会执行翻译，并将结果实时显示在聊天窗口中。无需复制到外部工具 —— 翻译就在你工作的地方完成。 + {'翻译会话'} ## 翻译对话中的内容 -LobeHub 支持用户一键将对话内容翻译成指定语言。选择目标语言后，LobeHub 将调用预先设置的 AI 模型进行翻译，并将翻译结果实时显示在聊天窗口中。 +点击任意消息的翻译选项，即可将其转换为所选语言。翻译会内联显示，你可以同时查看原文和译文。适用于： + +- **理解回复** — 当助理用你不熟悉的语言回复时，翻译成你偏好的语言。 +- **分享给他人** — 分享前翻译对话，让接收方能用自己熟悉的语言阅读。 +- **学习** — 对比原文和译文，提升语言能力。 +- **跨语言协作** — 团队成员可用各自偏好的语言工作，需要时翻译以保持对齐。 {'显示会话翻译结果'} -## 翻译模型设置 +## 配置翻译模型 -你可以在设置中指定您希望使用的模型作为翻译助手。 +你可以指定用于翻译的模型。能力更强的模型能产出更准确、自然的翻译，尤其对技术或含义细腻的内容。 {'设置翻译模型'} -- 打开`设置`面板 -- 在`系统助手`中找到`翻译设置`选项 -- 为你的`翻译助手`指定一个模型 +- 打开**设置**面板 +- 进入**系统助理**，找到**翻译设置** +- 为**翻译助理**指定一个模型 + +**提示：** 使用多语言能力强的模型（如 GPT-4o、Claude、Gemini）可获得更好效果。较小或较旧的模型可能产出较粗糙的翻译。 + +## 使用场景 + +**跨国团队** — 用你的语言沟通；为偏好其他语言的同事翻译关键信息。 + +**研究与学习** — 阅读原文的论文、文章或文档，再翻译需要深入理解的部分。 + +**客户支持** — 用客户的语言回复，或先翻译客户的消息以理解问题再回复。 + +**内容创作** — 用一种语言起草，翻译成另一种用于本地化或多语言发布。 + + + + + + diff --git a/docs/usage/agent/tts-stt.mdx b/docs/usage/agent/tts-stt.mdx index d355842d64..e2d77d0f2d 100644 --- a/docs/usage/agent/tts-stt.mdx +++ b/docs/usage/agent/tts-stt.mdx @@ -1,33 +1,62 @@ --- title: Text-to-Speech & Speech-to-Text description: >- - Learn how to use the text-to-speech (TTS) and speech-to-text (STT) features in - LobeHub, including how to configure your preferred voice model. + Listen to Agent responses hands-free, speak instead of typing — TTS and STT + for natural voice conversations. tags: - LobeHub - - Text-to-Speech - TTS - STT - - Voice Model + - Voice + - Hands-Free --- -# Guide to Text-to-Speech & Speech-to-Text +# Text-to-Speech & Speech-to-Text -LobeHub supports text and voice conversion features, allowing users to input content via speech and have AI responses read aloud using voice synthesis. +LobeHub supports voice capabilities — listen to Agent responses hands-free, speak your messages instead of typing, and hold natural back-and-forth voice conversations. TTS converts text to speech; STT converts your voice to text. ## Text-to-Speech (TTS) +TTS converts AI text responses into spoken audio, allowing you to listen instead of read. + To have AI read text aloud, simply highlight any content in the chat window and select `Text-to-Speech`. The AI will use a TTS model to convert the selected text into speech. {'TTS'} -## Speech-to-Text (STT) +You can also configure an Agent to automatically read all responses as soon as each message completes — useful for hands-free workflows. -To input text using your voice, click the voice input option in the message box. LobeHub will convert your speech into text and insert it into the input field. Once you're done, you can send it directly to the AI. +### Voice Providers and Options -{'STT'} +LobeHub supports two voice providers: -## Configuring Voice Conversion Settings +**OpenAI Voices** — Premium neural voices with natural prosody and intonation: + +| Voice | Character | +| ------- | ------------------- | +| Alloy | Neutral, balanced | +| Echo | Clear, professional | +| Fable | Warm, friendly | +| Onyx | Deep, authoritative | +| Nova | Energetic, engaging | +| Shimmer | Soft, gentle | + +Best for long-form content listening, professional use cases, and content requiring natural flow. + +**Microsoft Edge Speech (Azure Neural Voices)** — An extensive library with 100+ voices across languages, regional accents (US, UK, AU, and more), and male/female options. Best for specific accent requirements, multi-language content, and variety. + +### Playback Controls + +When audio is playing: + +- **Play/Pause** — Control playback +- **Progress bar** — See and seek through audio +- **Speed control** — Adjust playback speed (0.5× to 2×) +- **Volume** — Adjust audio level +- **Download** — Save audio file for offline use + +TTS audio is automatically cached — the first playback generates audio in real time, and subsequent playbacks are instant from cache. + +### Configuring Voice Settings You can customize the voice conversion experience by selecting your preferred models in the settings. @@ -36,3 +65,66 @@ You can customize the voice conversion experience by selecting your preferred mo - Open the `Settings` panel - Navigate to the `Text-to-Speech` section - Choose your desired voice service and AI model + +Each Agent can have its own voice. To configure per-Agent: open Agent settings → TTS section → select voice provider → choose a voice → test with sample text → save. + +## Speech-to-Text (STT) + +STT converts your spoken words into text, enabling voice input for messages. + +To input text using your voice, click the voice input option in the message box. LobeHub will convert your speech into text and insert it into the input field. Once you're done, you can send it directly to the AI. + +{'STT'} + +### Supported Languages + +STT supports a wide range of languages including English (US, UK, AU, CA, IN), Spanish, French, German, Italian, Portuguese, Chinese (Mandarin), Japanese, Korean, and many more. Language is typically auto-detected or set based on your interface language. + +### Tips for Best Results + +- Speak clearly at a normal pace +- Use good microphone positioning +- Minimize background noise +- Speak in complete sentences +- Pause briefly between thoughts + +After voice input, review the transcribed text, edit any mistakes, and send when ready. This hybrid approach combines the speed of voice with the precision of text editing. + +## Voice Conversations (Hands-Free Mode) + +Combine TTS and STT for natural, continuous voice conversations: + +1. Configure your agent to use automatic TTS playback +2. Click the microphone and speak your message +3. Review the transcription and send +4. The AI response plays automatically via TTS +5. Speak your next message when ready + +Hands-free mode is ideal for: + +- **Accessibility** — Screen reader users, users with mobility limitations, or anyone who prefers audio interaction +- **Language learning** — Practice speaking in a target language and hear correct pronunciation via TTS +- **Multitasking** — Get AI assistance while cooking, commuting, or exercising +- **Content consumption** — Listen to long articles, research papers, or learning materials at your own pace + +## Privacy Note + + + Voice input is processed by AI services for transcription. Avoid speaking sensitive information + unless you are using a private or local deployment. + + +Voice data handling: + +- STT audio is sent to the provider for transcription +- TTS audio is cached locally for performance +- Audio is not stored permanently by providers +- Transcriptions become part of conversation data + +Best practices: review transcriptions before sending, don't speak passwords or sensitive data, and clear the local audio cache periodically if you are concerned about storage. + + + + + + diff --git a/docs/usage/agent/tts-stt.zh-CN.mdx b/docs/usage/agent/tts-stt.zh-CN.mdx index f666065848..ed734def0e 100644 --- a/docs/usage/agent/tts-stt.zh-CN.mdx +++ b/docs/usage/agent/tts-stt.zh-CN.mdx @@ -1,36 +1,127 @@ --- -title: 文字语音转换 -description: 了解如何在 LobeHub 中使用文字语音转换功能，包括文字转语音（TTS）和语音转文字（STT），以及设置您喜欢的语音模型。 +title: 文字转语音与语音转文字 +description: 免提收听助理回复、用说话代替打字——TTS 与 STT 实现自然的语音对话。 tags: - LobeHub - - 文字语音转换 - TTS - STT - - 语音模型 + - 语音 + - 免提 --- -# 文字语音转换使用指南 +# 文字转语音与语音转文字 -LobeHub 支持文字语音转换功能，允许用户通过语音输入内容，以及将 AI 输出的内容通过语音播报。 +LobeHub 支持语音功能 —— 免提收听助理回复、用说话代替打字，进行自然的来回语音对话。TTS 将文字转为语音；STT 将你的语音转为文字。 ## 文字转语音（TTS） +TTS 将 AI 的文字回复转换为语音，让你可以收听而无需阅读。 + 在对话窗口中选中任意内容，选择`文字转语音`，AI 将通过 TTS 模型对文本内容进行语音播报。 {'TTS'} -## 语音转文字（STT） +你还可以配置助理在每条消息完成后自动朗读所有回复，适合免提工作流程。 -在输入窗口中选择语音输入功能，LobeHub 将您的语音转换为文字并输入到文本框中，完成输入后可以直接发送给 AI。 +### 语音提供商与可选音色 -{'STT'} +LobeHub 支持两种语音提供商： -## 文字语音转换设置 +**OpenAI 语音** — 高质量神经语音，具有自然的语调和韵律： -你可以在设置中为文字语音转换功能指定您希望使用的模型。 +| 音色 | 特点 | +| ------- | -------- | +| Alloy | 中性、均衡 | +| Echo | 清晰、专业 | +| Fable | 温暖、友好 | +| Onyx | 低沉、权威 | +| Nova | 充满活力、吸引人 | +| Shimmer | 柔和、轻缓 | + +适合长篇内容收听、专业使用场景和需要自然流畅感的内容。 + +**Microsoft Edge Speech（Azure 神经语音）** — 拥有 100+ 跨语言音色的庞大音色库，支持区域口音（美式、英式、澳式等）以及男女声选项。适合有特定口音要求、多语言内容和多样化定制需求的场景。 + +### 播放控制 + +音频播放时可用以下控制： + +- **播放 / 暂停** — 控制播放状态 +- **进度条** — 查看和定位音频进度 +- **速度调节** — 调整播放速度（0.5× 至 2×） +- **音量** — 调节音量大小 +- **下载** — 保存音频文件供离线使用 + +TTS 音频会自动缓存 —— 首次播放时实时生成，后续播放可从缓存中即时读取。 + +### 配置语音转换设置 + +你可以在设置中为文字语音转换功能指定你希望使用的模型。 {'TTS - 打开`设置`面板 - 找到`文字转语音`设置 - 选择您所需的语音服务和 AI 模型 + +每个助理可以拥有自己的音色。按助理配置：打开助理设置 → TTS 部分 → 选择语音提供商 → 选择音色 → 用示例文字测试 → 保存。 + +## 语音转文字（STT） + +STT 将你说的话转换为文字，实现语音输入消息。 + +在输入窗口中选择语音输入功能，LobeHub 将你的语音转换为文字并输入到文本框中，完成输入后可以直接发送给 AI。 + +{'STT'} + +### 支持的语言 + +STT 支持多种语言，包括英语（美式、英式、澳式、加拿大、印度）、西班牙语、法语、德语、意大利语、葡萄牙语、中文（普通话）、日语、韩语等。语言通常会根据你的界面语言自动检测或设置。 + +### 获得最佳效果的技巧 + +- 以正常语速清晰地说话 +- 保持麦克风位置适当 +- 减少背景噪音 +- 说完整的句子 +- 在思路之间稍作停顿 + +语音输入完成后，检查转录文字，修改任何错误，确认无误后发送。这种混合方式结合了语音的速度和文字编辑的精准度。 + +## 语音对话（免提模式） + +结合 TTS 和 STT，享受自然流畅的连续语音对话： + +1. 配置 Agent 自动播放 TTS 回复 +2. 点击麦克风图标并说出你的消息 +3. 检查转录内容后发送 +4. AI 回复通过 TTS 自动播放 +5. 准备好后继续语音输入下一条消息 + +免提模式非常适合： + +- **无障碍访问** — 屏幕阅读器用户、有行动不便的用户，或偏好音频交互的用户 +- **语言学习** — 用目标语言练习口语，并通过 TTS 收听正确发音 +- **多任务处理** — 烹饪、通勤或运动时获取 AI 帮助 +- **内容消费** — 以自己的节奏收听长篇文章、研究论文或学习材料 + +## 隐私说明 + + + 语音输入会被 AI 服务处理以进行转录。除非使用私有或本地部署，否则请避免说出敏感信息。 + + +语音数据处理方式： + +- STT 音频发送至提供商进行转录 +- TTS 音频在本地缓存以提升性能 +- 提供商不会永久存储音频 +- 转录内容将成为对话数据的一部分 + +最佳实践：发送前检查转录内容，不要说出密码或敏感数据，如担心本地存储，可定期清除音频缓存。 + + + + + + diff --git a/docs/usage/agent/web-search.mdx b/docs/usage/agent/web-search.mdx new file mode 100644 index 0000000000..c78fb688fa --- /dev/null +++ b/docs/usage/agent/web-search.mdx @@ -0,0 +1,154 @@ +--- +title: Web Search +description: >- + Agents search the internet for real-time information — with source citations + and grounding. +tags: + - LobeHub + - Web Search + - Real-time Information + - Citations + - Grounding +--- + +# Web Search + +LobeHub's web search integration lets Agents access current information from the internet — real-time news, prices, documentation, and facts beyond their training cutoff. When web search is active, the Agent retrieves up-to-date answers and cites the sources it used. + +## What Web Search Enables + +With web search enabled, Agents can: + +- Access real-time information — current news, prices, and events +- Verify information against the latest sources +- Cite the web pages they consulted +- Research topics from multiple sources simultaneously +- Answer questions about recent events outside their training data + +## How It Works + +When you ask a question that requires current information: + +1. The AI generates optimized search queries from your question +2. Searches are performed across the internet +3. Relevant sources are retrieved and analyzed +4. The AI synthesizes findings into a response +5. The response includes source citations + +This happens automatically when the AI determines web search would be helpful, or on-demand when you explicitly request it. + +## Search Grounding Display + +When web search is used, a **search grounding** section appears above the AI's response as a collapsible card showing: + +- **Source count** — How many web sources were consulted +- **Favicon preview** — Icons from source websites +- **Expandable search queries** — The exact queries the AI used (click to expand) +- **Citations** — Source titles, domains, and URLs you can click to visit + +Expand the grounding card to see exactly where the information came from and evaluate source credibility. + +## Enabling Web Search + +Web search is not active by default — it requires plugin or MCP configuration. + +**Via Skills** — Install a web search Skill from the marketplace (Settings → Skills). Options include general web search, news search, and academic search. Some may require an API key from the search provider. + +**Via MCP servers** — Connect a search MCP server (Brave Search, Google Search, DuckDuckGo, etc.) in your MCP settings. This gives more control and supports custom search implementations. + +**Per-Agent configuration** — In Agent Settings → Skills, enable web search for that specific Agent and choose the search provider. + +## Using Web Search + +### Automatic Search + +Web search activates automatically for questions that clearly require current data: + +``` +"What's the current price of Bitcoin?" +"Who won the World Cup in 2024?" +"What are the latest developments in AI?" +``` + +### Explicit Search Requests + +You can also explicitly request a web search: + +``` +"Search the web for recent reviews of the iPhone 15" +"Look up the latest research on climate change" +"Find current mortgage rates in California" +``` + +### Follow-Up Searches + +Each search builds on the conversation context. Chain searches to go deeper: + +``` +"What are the top programming languages in 2024?" +→ "Search for job market trends for Python developers" +→ "Find salary data for senior Python engineers in Europe" +``` + +## Use Cases + +**Research and news** — Get current information on news, markets, finance, and academic topics. "Latest news on \[subject]", "Recent papers on \[topic]", "Current stock price of X". + +**Technical information** — Access up-to-date docs, API changes, package releases, and bug fix discussions. Especially useful for fast-moving frameworks where training data may be outdated. "What's new in React 19?", "Find solutions to \[specific error]". + +**Product research** — Compare current prices, find recent reviews, and identify alternatives. "Compare the latest MacBook models", "Reviews for noise-cancelling headphones under $200". + +**Planning** — Get real-world current data for travel, events, and local recommendations. "Best restaurants in Austin right now", "Current museum exhibits in Paris", "Tech conferences in 2025". + +## Understanding Citations + +Every web search response includes citations. Check them: + +- **Source title** — The page or article name +- **Domain** — The website hosting the information +- **URL** — Click to visit the original source +- **Relevance snippet** — Preview of the relevant content used + +**Always verify critical information** by clicking through to sources. Check publication dates for time-sensitive topics and consider whether sources are authoritative (news outlet, official docs, academic paper) vs. informal (blog, forum post). + +## Tips for Better Results + +**Be specific** — "What are the latest LLM releases in November 2024?" gets far better results than "Tell me about AI". + +**Include time context** — Add "recent", "latest", "current", or specific dates to get timely results. + +**Ask for comparisons** — "Compare X and Y" or "What are the pros and cons of Z" triggers useful multi-source searches. + +**Review the citations** — Always expand the grounding card to see what sources were consulted and judge their quality. + +**Use follow-ups** — Chain questions to go from broad overview to specific details. + +## Privacy + + + Web searches may be logged by the search provider you've configured. Avoid searching for + sensitive or personally identifying information. + + +Search queries are sent to your configured search provider. Source websites may also track visits when you click through to citations. Review the privacy policy of your chosen search provider for details. + +## Limitations + +- **Paywalled content** — Cannot access subscription-only content (e.g., academic journals, news sites with paywalls) +- **Very recent events** — Slight indexing delay means very recent information (hours old) may not appear +- **Geo-restricted content** — Some sources may be regionally limited +- **Added latency** — Web search adds a few seconds to response time +- **Creative and personal tasks** — Web search isn't helpful for purely creative writing or personal advice — it's designed for factual questions + + + Web search requires either a search plugin or MCP server to be configured. Some search providers + require their own API key or subscription. + + + + + + + + + diff --git a/docs/usage/agent/web-search.zh-CN.mdx b/docs/usage/agent/web-search.zh-CN.mdx new file mode 100644 index 0000000000..0f02e66265 --- /dev/null +++ b/docs/usage/agent/web-search.zh-CN.mdx @@ -0,0 +1,150 @@ +--- +title: 网络搜索 +description: 助理搜索互联网获取实时信息——附带来源引用和搜索依据。 +tags: + - LobeHub + - 网络搜索 + - 实时信息 + - 引用来源 + - 搜索依据 +--- + +# 网络搜索 + +LobeHub 的网络搜索集成让助理能够访问互联网上的实时信息 —— 新闻、价格、文档和事实，突破训练数据截止日期的限制。开启网络搜索后，助理会获取最新回答并引用所使用的来源。 + +## 网络搜索能做什么 + +开启网络搜索后，助理可以： + +- 访问实时信息 —— 当前新闻、价格和时事 +- 对照最新来源核实信息 +- 引用参考的网页来源 +- 同时从多个来源研究某个主题 +- 回答训练数据之外的近期事件问题 + +## 工作原理 + +当你提出需要实时信息的问题时： + +1. AI 将你的问题转化为优化后的搜索词 +2. 在互联网上执行搜索 +3. 检索并分析相关来源 +4. 将发现综合为回答 +5. 在回答中附上来源引用 + +当 AI 判断网络搜索有帮助时会自动触发，你也可以明确要求搜索。 + +## 搜索依据显示 + +使用网络搜索时，AI 回复上方会出现一个可折叠的**搜索依据**卡片，显示： + +- **来源数量** — 参考了多少个网页来源 +- **网站图标预览** — 来源网站的图标 +- **可展开的搜索词** — AI 实际使用的搜索词（点击展开查看） +- **引用来源** — 来源标题、域名和可点击的 URL + +展开依据卡片，可以查看信息的确切来源，并自行评估来源的可信度。 + +## 启用网络搜索 + +网络搜索默认未开启，需要配置插件或 MCP 才能使用。 + +**通过技能** — 从市场安装网络搜索技能（设置 → 技能）。可选包括通用网络搜索、新闻搜索和学术搜索等。部分需要搜索提供商的 API Key。 + +**通过 MCP 服务器** — 在 MCP 设置中连接搜索类 MCP 服务器（Brave Search、Google Search、DuckDuckGo 等）。控制更灵活，支持自定义搜索实现。 + +**按助理配置** — 在助理设置 → 技能 中为该助理单独启用网络搜索，并选择搜索提供商。 + +## 使用网络搜索 + +### 自动搜索 + +对于明显需要实时数据的问题，网络搜索会自动触发： + +``` +"比特币现在的价格是多少？" +"2024 年世界杯谁赢了？" +"AI 领域最新进展是什么？" +``` + +### 明确搜索请求 + +你也可以主动要求网络搜索： + +``` +"搜索 iPhone 15 的最新评测" +"查一下气候变化的最新研究" +"查找加州当前的房贷利率" +``` + +### 追问深挖 + +每次搜索都建立在对话上下文之上。通过链式提问不断深入： + +``` +"2024 年最流行的编程语言有哪些？" +→ "搜索 Python 开发者的就业市场趋势" +→ "查找欧洲高级 Python 工程师的薪资数据" +``` + +## 使用场景 + +**研究与资讯** — 获取新闻、市场、金融和学术领域的最新信息。"\[主题] 最新进展"、"\[话题] 近期论文"、"X 的当前股价"。 + +**技术信息** — 访问最新文档、API 变更、包发布和 Bug 修复讨论。对于迭代快速的框架尤其有用，因为训练数据可能已经过时。"React 19 有什么新特性？"、"查找 \[具体错误] 的解决方案"。 + +**产品研究** — 比较当前价格、查找最新评测、发现替代方案。"比较最新 MacBook 型号"、"200 美元以内降噪耳机评测"。 + +**出行规划** — 获取旅游、活动和本地推荐的实时数据。"现在奥斯汀最好的餐厅"、"巴黎当前的博物馆展览"、"2025 年科技大会"。 + +## 理解引用来源 + +每次网络搜索的回复都会包含引用信息，建议查看： + +- **来源标题** — 页面或文章名称 +- **域名** — 托管信息的网站 +- **URL** — 点击访问原始来源 +- **相关摘要** — 所用内容的预览 + +**重要信息务必核实**：点击来源链接确认可信度。对时效性强的内容，检查发布日期；判断来源类型（新闻媒体、官方文档、学术论文 vs 博客、论坛帖子）。 + +## 获得更好搜索结果的技巧 + +**具体表述** — "2024 年 11 月有哪些最新 LLM 发布？" 比 "告诉我关于 AI 的事" 效果好得多。 + +**加入时间上下文** — 添加 "最近"、"最新"、"当前" 或具体日期，以获取及时的结果。 + +**要求比较** — "比较 X 和 Y" 或 "Z 的优缺点是什么" 往往能触发有价值的多源搜索。 + +**查看引用来源** — 始终展开搜索依据卡片，查看参考了哪些来源并判断其质量。 + +**追问深挖** — 通过链式提问从宏观概述到具体细节逐步深入。 + +## 隐私提示 + + + 网络搜索可能会被你配置的搜索提供商记录日志。请避免搜索敏感信息或涉及个人隐私的内容。 + + +搜索词会发送给你配置的搜索提供商。当你点击引用来源时，目标网站也可能追踪你的访问。具体隐私处理方式请参阅所选搜索提供商的隐私政策。 + +## 功能限制 + +- **付费墙内容** — 无法访问订阅制内容（如部分学术期刊、付费新闻网站） +- **极近期事件** — 非常新的信息（数小时内）可能尚未被索引 +- **地区限制内容** — 部分来源可能受地区访问限制 +- **响应延迟增加** — 网络搜索会为响应增加几秒钟的延迟 +- **创意与个人任务** — 纯创意写作或个人建议类问题不适合网络搜索 —— 它适用于有事实依据的问题 + + + 网络搜索需要配置搜索插件或 MCP 服务器才能使用。部分搜索提供商需要自行申请 API Key 或订阅。 + + + + + + + + + diff --git a/docs/usage/community/agent-market.mdx b/docs/usage/community/agent-market.mdx index 09783f5b8c..38d0b2be29 100644 --- a/docs/usage/community/agent-market.mdx +++ b/docs/usage/community/agent-market.mdx @@ -1,44 +1,81 @@ --- -title: Assistant Marketplace +title: Agent Marketplace description: >- - LobeHub's Assistant Marketplace is a vibrant and innovative community that - brings together a wide range of thoughtfully designed assistants to enhance - productivity in work and learning environments. You're welcome to submit your - own assistant creations and help build a collection of useful, creative, and - cutting-edge tools. + Discover, install, and publish AI Agents built by the LobeHub community — + ready for work in one click. tags: - LobeHub - - LobeHub - - Assistant Marketplace - - Innovation Community - - Collaborative Space - - Assistant Creations - - Automated Internationalization - - Multilingual Versions + - Agent Marketplace + - Community + - Agent Discovery + - Publish Agent + - Fork Agent --- -# Assistant Marketplace +# Agent Marketplace -The LobeHub Assistant Marketplace features high-quality AI assistants created by developers and enthusiasts from around the world. Whether you're looking for a coding assistant, writing advisor, language tutor, or a consultant in a specialized field, you'll find the right tool here. These assistants are carefully crafted by community members and tested in real-world scenarios, making them ready for immediate use in both work and study settings. +The LobeHub Agent Marketplace brings together high-quality Agents built by creators around the world. Whether you need a coding Agent, a writing advisor, a language tutor, or a specialist in a niche domain — you'll find a ready-to-use option here. Each Agent is crafted by community members and verified through real-world use. -The marketplace is more than just a resource hub—it's an open platform for creativity. You can publish your own custom assistants and share your ideas and expertise with users across the globe. +The Marketplace is also an open platform. Publish your own Agents, share your expertise, and contribute to a growing library that gets better with every creator who joins. -## Explore the Assistant Marketplace +## Explore the Marketplace -To access the Assistant Marketplace, click on "Community" → "Assistants" in the left sidebar. +Click **Community → Agents** in the left sidebar to open the Agent Marketplace. ![Agent Marketplace](/blog/assetsbcd98b0913d2dfc30d5a2b5523115d33.webp) -Assistants are organized by category, making it easy to quickly find the type of assistant you need. +Agents are organized by category, so you can find exactly what you need without scrolling through everything. -## Installing and Using Assistants +## Agent Categories -View and install assistants +| Category | Examples | Use Cases | +| ---------------- | ------------------------------------ | ---------------------------------- | +| **Development** | Code reviewers, debuggers | Software engineering, code quality | +| **Writing** | Copywriters, editors, proofreaders | Content creation, polishing | +| **Analysis** | Data analysts, researchers | Research, insights, reports | +| **Education** | Tutors, explainers | Learning new topics, teaching | +| **Creative** | Artists, brainstormers, storytellers | Design, ideation, fiction | +| **Business** | Consultants, strategists | Business operations, planning | +| **Productivity** | Task managers, summarizers | Workflow optimization | +| **Language** | Translators, language tutors | Communication, language learning | -Click on any assistant card to open its detail page. Here you'll find an overview, settings, capabilities, and version history. Once you've confirmed the assistant meets your needs, click "Add Assistant & Start Chatting" to begin. +## Install and Use an Agent -![Installing and Using Assistants](/blog/assets60bf3667e56862024d047444d9b4c2fb.webp) +Click any Agent card to open its detail page. Review the overview, capabilities, model configuration, and version history. When you're ready, click **Add Agent & Chat** to add it and start immediately. -### Using Assistants +![Installing and Using Agents](/blog/assets60bf3667e56862024d047444d9b4c2fb.webp) -After selecting "Add Assistant & Start Chatting," you can immediately begin interacting with the assistant to test its features and performance. You can customize system prompts, choose different models, configure plugins, and more. You also have the option to create a copy of any marketplace assistant, allowing you to personalize it while retaining its original capabilities. +Before adding, check: + +- **Description and capabilities** — What the Agent specializes in +- **Model and Skills** — Which AI model and plugins it uses +- **Install count** — How many users have already added it +- **Version history** — How the Agent has evolved + +### Customize After Installing + +Once added, the Agent is yours to adjust. Modify the system prompt, swap the model, add or remove Skills, and configure anything to fit your workflow. Changes apply only to your copy — the original stays unchanged. + +You can also **fork** any Marketplace Agent to create your own customized version from scratch. The fork retains attribution to the original creator. + +## Publish Your Own Agents + +Built an Agent you're proud of? Share it with the community. + +Before publishing, make sure your Agent has: + +- A clear, descriptive title +- A concise description (2–3 sentences) stating what it does, its expertise, and who it's for +- An appropriate avatar and 3–5 relevant tags +- A thoroughly tested system prompt +- An opening message to guide first-time users (optional but recommended) + +From your Agent's profile page, click **Publish to Marketplace**, review the details, add version notes, and submit. + +See [Publish an Agent](/docs/usage/community/publish-agent) for the full workflow. + + + + + + diff --git a/docs/usage/community/agent-market.zh-CN.mdx b/docs/usage/community/agent-market.zh-CN.mdx index 0e854b8e48..6d82b7410c 100644 --- a/docs/usage/community/agent-market.zh-CN.mdx +++ b/docs/usage/community/agent-market.zh-CN.mdx @@ -1,41 +1,79 @@ --- -title: 助手市场 -description: >- - LobeHub - 助手市场是一个充满活力和创新的社区，汇聚了众多精心设计的助手，为工作场景和学习提供便利。欢迎提交你的助手作品，共同创造更多有趣、实用且具有创新性的助手。 +title: 助理市场 +description: 发现、安装并发布社区助理——一键即用，随时可以分享你自己的创作。 tags: - LobeHub - - LobeHub - - 助手市场 - - 创新社区 - - 协作空间 - - 助手作品 - - 自动化国际化 - - 多语言版本 + - 助理市场 + - 社区 + - 助理发现 + - 发布助理 + - Fork 助理 --- -# 助手市场 +# 助理市场 -LobeHub 的助理市场汇聚了来自全球创作者的优质 AI 助理。无论你需要编程助理、写作顾问、语言教师，还是专业领域的咨询专家，都能在这里找到合适的助理。这些助理由社区成员精心打造，经过实际使用验证，能直接投入工作和学习场景。 +LobeHub 助理市场汇聚了来自全球创作者的优质助理。无论你需要编程助理、写作顾问、语言教师，还是某个细分领域的专业顾问 —— 这里都能找到经过验证、开箱即用的选择。每个助理由社区成员精心打造，并经过真实场景的使用验证。 -助理市场不只是获取资源的地方，更是一个开放的创作平台。你可以发布自己定制的助理，与全球用户分享你的创意和专业知识。 +助理市场同时也是一个开放的创作平台。发布你自己的助理，分享专业知识，共同壮大这个随每位创作者加入而持续成长的生态。 ## 浏览助理市场 -点击左侧边栏的「社区」→「助理」，进入助理市场主页。 +点击左侧边栏的**社区 → 助理**，进入助理市场。 -![Agent 市场](/blog/assetsbcd98b0913d2dfc30d5a2b5523115d33.webp) +![助理市场](/blog/assetsbcd98b0913d2dfc30d5a2b5523115d33.webp) -助理市场按类别组织，方便你快速找到所需的助理类型。 +助理按类别组织，你可以精准找到所需类型，无需翻阅全部内容。 + +## 助理分类 + +| 分类 | 示例 | 使用场景 | +| ------ | ------------- | ---------- | +| **开发** | 代码审查员、调试助理 | 软件工程、代码质量 | +| **写作** | 文案策划、编辑、校对 | 内容创作、文字润色 | +| **分析** | 数据分析师、研究员 | 研究调研、洞见报告 | +| **教育** | 导师、知识解说员 | 学习新领域、教学辅助 | +| **创意** | 艺术家、头脑风暴、故事创作 | 设计、创意发散、写作 | +| **商业** | 顾问、战略分析师 | 商业运营、规划决策 | +| **效率** | 任务管理、摘要整理 | 工作流优化 | +| **语言** | 翻译、语言教师 | 沟通协作、语言学习 | ## 安装和使用助理 -查看和安装助理 - -点击任意助理卡片，进入详情页面。这里展示了助理的概览、设定、能力和版本历史等信息。确认助理符合你的需求时，可以在此页面「添加助理并会话」。 +点击任意助理卡片，进入详情页面。查看概览、能力说明、模型配置和版本历史。确认符合需求后，点击**添加助理并会话**，立即开始。 ![安装和使用助理](/blog/assets60bf3667e56862024d047444d9b4c2fb.webp) -### 使用助理 +添加前可以查看的信息： -选择「添加助理并会话」后，你可以立即开始与助理对话，测试助理的功能和效果。根据需要调整助理的系统提示词、模型选择、插件配置等。你也可以基于市场助理创建副本，在保留原有能力的基础上进行个性化修改。 +- **描述和能力** — 该助理的专业领域 +- **模型和技能** — 使用的 AI 模型和插件配置 +- **安装数量** — 来自其他用户的使用量参考 +- **版本历史** — 助理的演进过程 + +### 安装后自定义 + +添加助理后，你可以按需调整。修改系统提示词、切换模型、添加或移除技能 —— 所有改动只影响你自己的副本，原版保持不变。 + +你也可以 **Fork** 任意社区助理，从经过验证的基础出发创建自己的定制版本。Fork 版本会保留对原创者的归因说明。 + +## 发布你自己的助理 + +打造了一个满意的助理？把它分享给社区。 + +发布前，请确保你的助理具备： + +- 清晰的标题 +- 简明描述（2–3 句话），说明功能、专长和目标用户 +- 合适的头像以及 3–5 个相关标签 +- 经过充分测试的系统提示词 +- 引导用户的开场白（可选，但推荐添加） + +在助理档案页面点击**发布到市场**，确认信息、填写版本说明后提交即可。 + +完整流程请参见[发布助理](/zh/docs/usage/community/publish-agent)。 + + + + + + diff --git a/docs/usage/community/become-a-creator.mdx b/docs/usage/community/become-a-creator.mdx index c67dfb9e80..24c11100c4 100644 --- a/docs/usage/community/become-a-creator.mdx +++ b/docs/usage/community/become-a-creator.mdx @@ -1,10 +1,8 @@ --- title: Community Creators description: >- - The LobeHub Community is a vibrant and innovative space that brings together a - wide range of thoughtfully designed assistants to enhance productivity in work - and learning scenarios. You're welcome to submit your own assistant creations - and collaborate to build more interesting, practical, and creative tools. + Join the LobeHub Community as a creator — publish Agents, share workflows, and + build tools that help thousands of users work smarter. tags: - LobeHub - Community Creators @@ -12,16 +10,40 @@ tags: - Collaborative Space --- -# LobeHub Community Creators +# Community Creators -The LobeHub Community is a vibrant and innovative space that brings together a wide range of thoughtfully designed assistants to enhance productivity in work and learning scenarios. You're welcome to submit your own assistant creations and collaborate to build more interesting, practical, and creative tools. +The LobeHub Community brings together creators who design, share, and refine Agents for real-world use. Whether it's a productivity tool, a teaching assistant, or a creative collaborator, your work can reach thousands of users. -## Join the Community +## Why Become a Creator -Click on the sidebar: **Community** → **Assistants** → then click **Become a Creator** in the top right corner. +| | | +| ------------- | ------------------------------------------------------------------------ | +| **Reach** | Your Agent is discoverable in the Agent Marketplace by all LobeHub users | +| **Profile** | Get a public creator page showcasing everything you've published | +| **Feedback** | Collect ratings and usage data to improve your work | +| **Community** | Connect with other builders, exchange ideas, and collaborate | + +## How to Join + +1. Open the sidebar and navigate to **Community** → **Agents** +2. Click **Become a Creator** in the top-right corner +3. Fill in your creator profile — name, avatar, and a short bio ![Fill in Creator Information](/blog/assets7bf0102f1cae47bf24aeb01eaa2796d9.webp) -## Personal Profile +Once submitted, your creator profile is live. You can start publishing immediately. -Your personal profile will showcase your creator information and all the content you’ve published. +## What You Can Publish + +- **Agents** — Custom assistants with specific prompts, skills, and knowledge bases +- **MCP/Skills** — Reusable skill integrations for the community to install + +## Your Creator Profile + +Your profile page displays your creator information and all published content. Users can browse your work, view ratings, and install your Agents directly. + + + + + + diff --git a/docs/usage/community/become-a-creator.zh-CN.mdx b/docs/usage/community/become-a-creator.zh-CN.mdx index 40abc9f5ec..a2625dce7c 100644 --- a/docs/usage/community/become-a-creator.zh-CN.mdx +++ b/docs/usage/community/become-a-creator.zh-CN.mdx @@ -1,8 +1,7 @@ --- title: 社区创作者 description: >- - LobeHub - 社区是一个充满活力和创新的社区，汇聚了众多精心设计的助手，为工作场景和学习提供便利。欢迎提交你的助手作品，共同创造更多有趣、实用且具有创新性的助手 + 加入 LobeHub 社区成为创作者——发布助理、分享工作流，打造帮助千万用户提效的工具。 tags: - LobeHub - 社区创作者 @@ -10,16 +9,40 @@ tags: - 协作空间 --- -# LobeHub 社区创作者 +# 社区创作者 -LobeHub 社区是一个充满活力和创新的社区，汇聚了众多精心设计的助手，为工作场景和学习提供便利。欢迎提交你的助手作品，共同创造更多有趣、实用且具有创新性的助手。 +LobeHub 社区汇聚了一批设计、分享和打磨助理的创作者。无论是效率工具、教学助手还是创意搭档，你的作品都能触达千万用户。 -## 加入 +## 为什么要成为创作者 -点击左侧边栏的「社区」→「助理」→右上角「成为创作者」。 +| | | +| ------ | -------------------------- | +| **曝光** | 你的助理可在助理市场被所有 LobeHub 用户发现 | +| **主页** | 拥有公开的创作者页面，展示你发布的全部内容 | +| **反馈** | 获取评分和使用数据，持续改进作品 | +| **社区** | 结识其他创作者，交流想法，展开协作 | + +## 如何加入 + +1. 打开侧边栏，进入「社区」→「助理」 +2. 点击右上角的「成为创作者」 +3. 填写创作者资料 —— 昵称、头像和简短介绍 ![填写创作者信息](/blog/assets7bf0102f1cae47bf24aeb01eaa2796d9.webp) -## 个人主页 +提交后，创作者资料即刻生效，可以立即开始发布。 -你的个人主页会展示你的创作者信息和已发布的内容。 +## 你可以发布什么 + +- **助理** — 包含特定提示词、技能和知识库的自定义助手 +- **MCP / 技能** — 可复用的技能集成，供社区用户安装使用 + +## 你的创作者主页 + +创作者主页展示你的个人信息及所有已发布内容。用户可以浏览你的作品、查看评分，并直接安装你的助理。 + + + + + + diff --git a/docs/usage/community/custom-mcp.mdx b/docs/usage/community/custom-mcp.mdx new file mode 100644 index 0000000000..05d91d66ec --- /dev/null +++ b/docs/usage/community/custom-mcp.mdx @@ -0,0 +1,144 @@ +--- +title: Custom MCP +description: >- + Connect your own MCP servers to LobeHub — add private APIs, internal tools, + and custom integrations beyond what the MCP Marketplace offers. +tags: + - Custom MCP + - LobeHub + - MCP + - Model Context Protocol + - Skills + - Custom Integration +--- + +# Custom MCP + +The MCP Marketplace offers thousands of ready-to-use integrations, but sometimes you need to connect a private API, an internal company tool, or a custom MCP server you've built yourself. **Custom MCP** lets you add any MCP-compatible server directly to LobeHub without going through the marketplace. + +## Where to Add a Custom MCP + +You can open the "Add custom skill" dialog from several places: + +- **Settings → Skills** — click **Skill Store**, then switch to the **Custom** tab and click **Add custom skill** +- **Agent settings** — open any agent's settings, go to **Skills**, and click **Add custom skill** +- **Chat input** — click the **Tools** button above the input area, then **Add custom skill** + +All three paths open the same configuration dialog. + +## Quick Import from JSON + +The fastest way to add a custom MCP is to paste a JSON config from the MCP server's documentation. + + + ### Open the import panel + + In the "Add custom skill" dialog, click **Import JSON config** at the top of the form. A text area will appear. + + ### Paste your config + + Paste either a full `mcpServers` block or a single-server config: + + ```json + { + "mcpServers": { + "my-server": { + "command": "npx", + "args": ["-y", "my-mcp-package"], + "type": "stdio" + } + } + } + ``` + + Or for an HTTP server: + + ```json + { + "mcpServers": { + "my-api": { + "url": "https://mcp.example.com/sse", + "type": "http" + } + } + } + ``` + + ### Click Import + + LobeHub automatically fills in the identifier, connection type, URL or command, and any other detected parameters. Review the auto-filled fields, adjust if needed, then proceed to test the connection. + + +Most MCP server documentation provides a ready-to-copy JSON config in this format. Quick Import is the recommended starting point. + +## Manual Configuration + +If you prefer to enter settings by hand, choose a connection type and fill in the fields directly. + +### Streamable HTTP + +Use this for remote MCP servers — cloud-hosted APIs, SaaS tools, or any server accessible via HTTPS. Available on both web and desktop. + +| Field | Description | +| ---------------- | ------------------------------------------------------------------------- | +| **MCP name** | A unique identifier for this skill (letters, numbers, hyphens only) | +| **Endpoint URL** | The full HTTPS URL of the MCP server (e.g. `https://mcp.example.com/sse`) | +| **Auth type** | None, or API Key (sent as a Bearer token) | +| **API Key** | Required when Auth type is set to API Key | +| **HTTP Headers** | Optional additional headers (expand Advanced section) | +| **Description** | Optional note about what this MCP does | + +### STDIO + +Use this for local MCP servers that run as a process on your machine — command-line tools, scripts, or locally installed packages. **Available on the LobeHub desktop app only; not supported on the web.** + +| Field | Description | +| ------------------------- | ------------------------------------------------------------------------------- | +| **MCP name** | A unique identifier for this skill | +| **Command** | The executable to run (e.g. `npx`, `python`, `uv`) | +| **Arguments** | Arguments passed to the command (e.g. `-y @modelcontextprotocol/server-github`) | +| **Environment variables** | Key-value pairs injected into the process environment (API keys, paths, etc.) | +| **Description** | Optional note about what this MCP does | + +## Testing the Connection + +Before saving, click **Test connection** to verify that LobeHub can reach your MCP server and fetch its tool list. If the test succeeds, you'll see the available tools listed in the preview panel on the right. + +If the test fails: + +- **HTTP**: Check that the URL is correct and reachable, and that your API key or headers are set correctly. +- **STDIO**: Confirm the command is installed and available in your system PATH. Run `which npx` (or the relevant command) in a terminal to check. + +## Saving and Managing + +Click **Install** to add the custom MCP as a skill. It will appear under **Custom MCPs** in **Settings → Skills**. + +To edit a custom MCP later: + +1. Go to **Settings → Skills** +2. Find the custom skill under **Custom MCPs** +3. Click **Configure** to reopen the full configuration dialog +4. Make your changes, test the connection, and click **Update** + +To remove it, open the skill's menu and select **Uninstall**. + +## Enabling Custom MCP for an Agent + +Installing a custom MCP makes it available in your workspace, but each agent needs to be configured to use it: + +1. Open the agent's settings +2. Go to **Skills** +3. Find the custom MCP and toggle it on +4. The agent will now have access to all tools provided by that MCP server + +Skills are per-agent — enabling a skill for one agent doesn't automatically enable it for others. + +Only install MCP servers from sources you trust. A malicious MCP server could perform unintended actions on your behalf. + + + + + + + + diff --git a/docs/usage/community/custom-mcp.zh-CN.mdx b/docs/usage/community/custom-mcp.zh-CN.mdx new file mode 100644 index 0000000000..b338ea034f --- /dev/null +++ b/docs/usage/community/custom-mcp.zh-CN.mdx @@ -0,0 +1,142 @@ +--- +title: 自定义 MCP +description: 将你自己的 MCP 服务器接入 LobeHub——添加私有 API、内部工具和自定义集成，超越 MCP 市场的现有选项。 +tags: + - 自定义 MCP + - LobeHub + - MCP + - 模型上下文协议 + - 技能 + - 自定义集成 +--- + +# 自定义 MCP + +MCP 市场提供了数以千计的现成集成，但有时你需要接入私有 API、公司内部工具，或者自己搭建的 MCP 服务器。**自定义 MCP** 让你无需经过市场，直接将任何兼容 MCP 协议的服务器添加到 LobeHub。 + +## 在哪里添加自定义 MCP + +你可以从以下几个入口打开「添加自定义技能」对话框： + +- **设置 → 技能** — 点击**技能商店**，切换到**自定义**标签页，点击**添加自定义技能** +- **助理设置** — 打开任意助理的设置，进入**技能**，点击**添加自定义技能** +- **对话输入框** — 点击输入框上方的**工具**按钮，选择**添加自定义技能** + +三个入口都会打开同一个配置对话框。 + +## 快速导入 JSON 配置 + +添加自定义 MCP 最快的方式是直接粘贴 MCP 服务器文档中提供的 JSON 配置。 + + + ### 打开导入面板 + + 在「添加自定义技能」对话框中，点击表单顶部的**导入 JSON 配置**，此时会出现一个文本输入框。 + + ### 粘贴配置 + + 粘贴完整的 `mcpServers` 配置块或单个服务器配置： + + ```json + { + "mcpServers": { + "my-server": { + "command": "npx", + "args": ["-y", "my-mcp-package"], + "type": "stdio" + } + } + } + ``` + + 或者 HTTP 服务器配置： + + ```json + { + "mcpServers": { + "my-api": { + "url": "https://mcp.example.com/sse", + "type": "http" + } + } + } + ``` + + ### 点击导入 + + LobeHub 会自动填入标识符、连接类型、URL 或命令等参数。确认自动填入的内容无误后，即可进行连接测试。 + + +大多数 MCP 服务器的文档都会提供这种格式的 JSON 配置，可以直接复制使用。推荐优先使用快速导入功能。 + +## 手动配置 + +如果你更倾向于手动填写，可以选择连接类型后逐项填入参数。 + +### Streamable HTTP + +适用于远程 MCP 服务器 —— 云端托管的 API、SaaS 工具，或任何可通过 HTTPS 访问的服务。Web 端和桌面端均可使用。 + +| 字段 | 说明 | +| ---------------- | ----------------------------------------------------- | +| **MCP 名称** | 该技能的唯一标识符（仅限字母、数字、连字符） | +| **Endpoint URL** | MCP 服务器的完整 HTTPS 地址（例如 `https://mcp.example.com/sse`） | +| **认证类型** | 无认证，或 API Key（以 Bearer Token 方式传递） | +| **API Key** | 选择 API Key 认证时必填 | +| **HTTP 请求头** | 可选的额外请求头（展开「高级」选项设置） | +| **描述** | 可选，备注该 MCP 的用途 | + +### STDIO + +适用于在本地作为进程运行的 MCP 服务器 —— 命令行工具、脚本或本地安装的包。**仅支持 LobeHub 桌面客户端，网页版不支持此连接类型。** + +| 字段 | 说明 | +| ---------- | ----------------------------------------------------- | +| **MCP 名称** | 该技能的唯一标识符 | +| **命令** | 要运行的可执行程序（例如 `npx`、`python`、`uv`） | +| **参数** | 传递给命令的参数（例如 `-y @modelcontextprotocol/server-github`） | +| **环境变量** | 注入到进程环境中的键值对（API Key、路径等） | +| **描述** | 可选，备注该 MCP 的用途 | + +## 测试连接 + +保存前，点击**测试连接**以验证 LobeHub 能否正常连接到你的 MCP 服务器并获取工具列表。测试成功后，右侧预览面板将显示可用的工具列表。 + +如果测试失败： + +- **HTTP 类型**：检查 URL 是否正确且可访问，以及 API Key 或请求头是否配置正确。 +- **STDIO 类型**：确认命令已安装并存在于系统 PATH 中，可在终端运行 `which npx`（或相应命令）进行验证。 + +## 保存与管理 + +点击**安装**将自定义 MCP 作为技能添加到工作区，它将出现在**设置 → 技能**的**自定义 MCP** 列表中。 + +如需后续编辑： + +1. 进入**设置 → 技能** +2. 在**自定义 MCP** 下找到该技能 +3. 点击**配置**重新打开完整配置对话框 +4. 修改参数，测试连接，点击**更新** + +如需删除，打开该技能的菜单并选择**卸载**。 + +## 为助理启用自定义 MCP + +安装自定义 MCP 后，它在整个工作区内可用，但每个助理需要单独配置才能使用： + +1. 打开助理设置 +2. 进入**技能** +3. 找到该自定义 MCP 并开启 +4. 该助理即可使用 MCP 服务器提供的所有工具 + +技能的启用是按助理维度的 —— 为某个助理开启技能，不会自动为其他助理开启。 + +请仅安装来源可信的 MCP 服务器。恶意的 MCP 服务器可能会以你的身份执行意外操作。 + + + + + + + + diff --git a/docs/usage/community/custom-plugin.mdx b/docs/usage/community/custom-plugin.mdx deleted file mode 100644 index 08f0377362..0000000000 --- a/docs/usage/community/custom-plugin.mdx +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: Custom Plugins -description: >- - Learn how to install custom plugins and develop LobeHub plugins to extend the - capabilities of your AI assistant. -tags: - - Custom Plugins - - LobeHub - - Plugin Installation - - Plugin Development - - AI Assistant ---- - -# Custom Plugins - -## Installing Custom Plugins - -If you'd like to install a plugin that isn't available in the LobeHub Plugin Store—such as one you've developed yourself—you can do so by clicking on "Custom Plugin": - -