🗃️ feat(database): add page shares schema

🔖 chore(release): release version v2.2.0 [skip ci]
2026-06-17 13:06:21 +00:00 · 2026-05-20 16:00:00 +08:00 · 2026-05-18 04:43:53 +00:00
1392 changed files with 16871 additions and 51678 deletions
@@ -25,18 +25,17 @@ The two reference tools to read end-to-end:
 1. **先保证折叠态可读。** 每个 API 都必须有 Inspector；用户不展开也应该能看懂 “正在做什么 / 对什么做 / 当前结果是什么”。Inspector 不应该只展示函数名和原始参数。
 2. **Inspector 是一句话，不是详情页。** 优先表达动作、关键对象、数量、状态，例如 “分析图片 3 张”“搜索 12 个结果”“读取 config.json”。长文本、列表和结构化结果放到 Render 或 Portal。
 3. **Inspector 要覆盖执行生命周期。** `args` 还在 streaming、工具执行中、执行完成、执行失败时都应该有稳定展示；必要时同时读取 `args`、`partialArgs` 和 `pluginState`，避免出现空白、跳变或只显示半截参数。
-4. **文案要随状态切换时态。** 同一个动作在 loading 与 completed 两个阶段必须用不同的措辞：执行中用现在进行时（“正在创建任务 / Creating task / 正在搜索”），执行完成后切到完成态（“已创建任务 / Task created / 已找到 N 条”）。Inspector chip 会一直留在聊天记录里 —— 如果一直挂着 “正在 xxx”，几小时后回看历史时会读起来像还在跑。约定的 i18n 形式是 `<api>.loading` / `<api>.completed` 一对键（见 `lobe-agent.apiName.callSubAgent.{loading,completed}` 与 `lobe-claude-code.task.{create,list,update,get}.{loading,completed}`），渲染时按 `isArgumentsStreaming || isLoading` 决定取哪一个。只读 / 查询类（“查看任务” 这种本来就是名词性的）可以共用一个键。
-5. **只有结构化结果才需要 Render。** 如果工具结果只是自然语言总结，通常不需要 Render；如果结果包含列表、媒体、文件、表格、代码、diff、地图、时间线、权限请求等结构，就应该提供 Render。
-6. **Render 要帮助用户检查结果，而不是复述参数。** Render 的主体应该围绕工具产物组织：可预览、可比较、可筛选、可定位。参数只作为上下文辅助出现，不要把 Render 做成一块更大的 args dump。
-7. **参数和结果要一起参与渲染。** 好的 Tool UI 通常同时用 `args` 解释意图，用 `pluginState` 展示真实执行结果；但 `pluginState` 只放结果域数据，不要反向塞入可以从 `args` 推导出的内容。
-8. **慢操作要有 Placeholder。** 如果工具通常需要等待网络、文件系统、模型或外部进程，Placeholder 应该先占住最终 Render 的版式，让用户知道即将看到什么，而不是只显示一个泛化 loading。
-9. **Streaming 只用于连续产物。** 搜索列表、日志、长文本、文件分析、分阶段计划适合 Streaming；一次性小结果不需要强行做 Streaming。Streaming UI 要能渐进追加，并且完成后自然过渡到最终 Render。
-10. **有风险的动作必须 Intervention。** 写文件、删除、发送、安装、执行命令、外部可见操作、权限敏感操作，都应该在执行前给出可理解的确认界面；确认文案要说明影响范围，而不是只问 “是否继续”。
-11. **错误、空态和截断都是正式状态。** Render 不能在失败、无结果、超长结果时退化成空白。错误要说明发生在哪一步；空态要告诉用户没有产物；超长内容要明确 “展示前 N 项 / 还有 N 项”。
-12. **信息密度要克制。** 默认展示最有判断价值的部分：标题、来源、状态、摘要、少量关键字段。大对象、长列表、原文、调试数据放进可展开区域或 Portal，避免把聊天流撑成后台管理页。
-13. **视觉上融入聊天流。** Tool UI 应该使用 `@lobehub/ui` / base-ui、`Flexbox`、`createStaticStyles` 和 `cssVar.*`，遵循现有间距、圆角、颜色、字号；不要为单个工具发明一套独立视觉语言。
-14. **Devtools fixture 是验收入口。** 新增或修改 Tool UI 时，应在 `/devtools` 里准备覆盖典型态、loading/streaming、空态、错误态、长内容态的 fixture；一个 API 如果在真实聊天里会出现，就不应该在 devtools 中缺席。
-15. **先做用户会看的 UI，再做调试 UI。** Raw JSON、trace、schema、内部 id 可以存在，但应默认收起或放到调试区；主界面先回答用户最关心的问题：工具做了什么，结果值不值得信任，下一步能做什么。
+4. **只有结构化结果才需要 Render。** 如果工具结果只是自然语言总结，通常不需要 Render；如果结果包含列表、媒体、文件、表格、代码、diff、地图、时间线、权限请求等结构，就应该提供 Render。
+5. **Render 要帮助用户检查结果，而不是复述参数。** Render 的主体应该围绕工具产物组织：可预览、可比较、可筛选、可定位。参数只作为上下文辅助出现，不要把 Render 做成一块更大的 args dump。
+6. **参数和结果要一起参与渲染。** 好的 Tool UI 通常同时用 `args` 解释意图，用 `pluginState` 展示真实执行结果；但 `pluginState` 只放结果域数据，不要反向塞入可以从 `args` 推导出的内容。
+7. **慢操作要有 Placeholder。** 如果工具通常需要等待网络、文件系统、模型或外部进程，Placeholder 应该先占住最终 Render 的版式，让用户知道即将看到什么，而不是只显示一个泛化 loading。
+8. **Streaming 只用于连续产物。** 搜索列表、日志、长文本、文件分析、分阶段计划适合 Streaming；一次性小结果不需要强行做 Streaming。Streaming UI 要能渐进追加，并且完成后自然过渡到最终 Render。
+9. **有风险的动作必须 Intervention。** 写文件、删除、发送、安装、执行命令、外部可见操作、权限敏感操作，都应该在执行前给出可理解的确认界面；确认文案要说明影响范围，而不是只问 “是否继续”。
+10. **错误、空态和截断都是正式状态。** Render 不能在失败、无结果、超长结果时退化成空白。错误要说明发生在哪一步；空态要告诉用户没有产物；超长内容要明确 “展示前 N 项 / 还有 N 项”。
+11. **信息密度要克制。** 默认展示最有判断价值的部分：标题、来源、状态、摘要、少量关键字段。大对象、长列表、原文、调试数据放进可展开区域或 Portal，避免把聊天流撑成后台管理页。
+12. **视觉上融入聊天流。** Tool UI 应该使用 `@lobehub/ui` / base-ui、`Flexbox`、`createStaticStyles` 和 `cssVar.*`，遵循现有间距、圆角、颜色、字号；不要为单个工具发明一套独立视觉语言。
+13. **Devtools fixture 是验收入口。** 新增或修改 Tool UI 时，应在 `/devtools` 里准备覆盖典型态、loading/streaming、空态、错误态、长内容态的 fixture；一个 API 如果在真实聊天里会出现，就不应该在 devtools 中缺席。
+14. **先做用户会看的 UI，再做调试 UI。** Raw JSON、trace、schema、内部 id 可以存在，但应默认收起或放到调试区；主界面先回答用户最关心的问题：工具做了什么，结果值不值得信任，下一步能做什么。

 ---

@@ -201,7 +200,6 @@ export default SearchInspector;
 - Read both `args?.X` and `partialArgs?.X` together — `args` is final, `partialArgs` is in-stream.
 - Use chips/tags for distinct facets (identifier, name, parent, status, count). Each chip should clip with `text-overflow: ellipsis` and have a `max-width` so long values don't blow out the chat bubble.
 - Append `pluginState`-derived suffixes only **after** loading finishes — count or "(no results)" should not appear while still searching.
- **Switch copy by phase.** If the verb implies an ongoing action ("Creating", "Searching", "Listing"), define `<api>.loading` and `<api>.completed` keys and select via `isArgumentsStreaming || isLoading ? loadingKey : completedKey`. Inspector chips persist in chat history — leaving "Creating task" frozen on a finished call reads as if the tool is still running. Read-only labels that are already noun-form ("View task") can keep a single key. See `CallSubAgentInspector` for the canonical two-key pattern.

 ### Inspector registry — `client/Inspector/index.ts`

@@ -48,7 +48,6 @@ user-invocable: false
 - Replace magic numbers/strings with well-named constants
 - Defer formatting to tooling
 - Prefer **named exports** over `export default` — keeps refactor renames and IDE auto-import in sync, and avoids the `default` re-naming drift you get with `import Foo from './foo'`. Reserve `export default` for files where the framework requires it (Next.js page/route/layout, React.lazy targets, config files like `vitest.config.ts`)
- Before adding local helpers for common guards/parsing/normalization (record checks, string extraction, empty-string handling, timing helpers, JSON-safe utilities, etc.), search `packages/utils` first. If the helper already exists or clearly belongs there, import it from `@lobechat/utils` (or the relevant `@lobechat/utils/*` subpath) instead of duplicating tiny helpers across feature files.

 ## UI and Theming

@@ -1,10 +1,6 @@
 # Issue Triage Guide

-This guide is used for triaging GitHub issues — analyzing issues and applying only the most essential business-domain labels.
-
-## Core Principle
-
-**Each issue should have 1-3 labels that describe its core business domain.** Do NOT apply redundant labels that can be inferred from other labels. Less is more.
+This guide is used for batch triaging GitHub issues - analyzing issues and applying appropriate labels.

 ## Workflow

@@ -24,76 +20,23 @@ For each issue number, run:
 gh issue view [ISSUE_NUMBER] --json number,title,body,labels,comments
 ```

-### Step 3: Select Labels (1-3 per issue)
+### Step 3: Analyze and Select Labels

-Only apply labels from these THREE categories:
+Extract information from the issue template and content:

-#### Category 1: Technology Carrier
+#### Template Fields Mapping

-The runtime environment or technology wrapper where the issue occurs:
+- 📦 Platform field → `platform:web/desktop/mobile`
+- 💻 Operating System → `os:windows/macos/linux/ios`
+- 🌐 Browser → `device:pc/mobile`
+- 📦 Deployment mode → `deployment:server/client/pglite`
+- Platform (hosting) → `hosting:cloud/self-host/vercel/zeabur/railway`

-| Label | When to apply |
-|-------|--------------|
-| `electron` | Desktop/Electron-specific issues. This REPLACES `platform:desktop`, `os:*`, `deployment:*`, `hosting:*` — do NOT add those. |
-| `pwa` | PWA/mobile-app-specific issues |
-| `docker` | Docker-specific deployment issues |
+#### Provider Detection

-**Rule**: If `electron` is applied, do NOT add `platform:desktop`, `os:*`, `deployment:*`, or `hosting:*`. The `electron` label already implies all of these.
+**IMPORTANT**: Always check issue title and body for provider mentions!

-#### Category 2: Feature / Component
-
-The functional area affected. Select the 1-2 MOST relevant:
-
-Core Features:
-
- `feature:agent` - Agent/Assistant functionality
- `feature:topic` - Topic/Conversation management
- `feature:marketplace` - Agent/plugin marketplace
- `feature:settings` - Settings and configuration
-
-Content & Knowledge:
-
- `feature:editor` - Lobe Editor / rich text / markdown rendering
- `feature:markdown` - Markdown rendering (if separate from editor)
- `feature:files` - File upload/management
- `feature:knowledge-base` - Knowledge base and RAG
- `feature:export` - Export functionality
-
-Model Capabilities:
-
- `feature:tool` - Tool calling and function execution
- `feature:streaming` - Streaming responses
- `feature:vision` - Vision/multimodal capabilities
- `feature:image` - AI image generation
- `feature:tts` - Text-to-speech
-
-Technical:
-
- `feature:api` - Backend API
- `feature:auth` - Authentication/authorization
- `feature:sync` - Cloud sync functionality
- `feature:search` - Search functionality
- `feature:mcp` - MCP integration
- `feature:thread` - Thread/Subtopic functionality
-
-Collaboration:
-
- `feature:group-chat` - Group chat functionality
- `feature:memory` - Memory feature
- `feature:team-workspace` - Team workspace
- `feature:im-integration` - IM and bot integration
-
-Other:
-
- `feature:schedule-task` - Scheduled task functionality
-
-**Rule**: Pick only the 1-2 most specific feature labels. Don't stack multiple features unless the issue genuinely spans multiple areas.
-
-#### Category 3: Model Provider
-
-Only when the issue is SPECIFICALLY about a provider's behavior:
-
-**Official Providers** (check title and body for these keywords):
+**Official Providers** (check for these keywords in title/body):

 - `openai`, `gpt` → `provider:openai`
 - `gemini` → `provider:gemini`
@@ -114,100 +57,197 @@ Only when the issue is SPECIFICALLY about a provider's behavior:
 **Third-party Aggregation Providers**:

 - `aihubmix`, `AIHubMix`, `AIHUBMIX` → `provider:aihubmix`
- `zenmux` → `provider:zenmux`
+- Check environment variables like `AIHUBMIX_*` in issue body

-**Rule**: Only add a provider label if the issue is specifically about that provider's behavior (e.g., "Gemini returns error X"). Do NOT add provider labels just because the issue template mentions a provider.
+**Multiple Providers**: If issue mentions multiple providers, add ALL applicable provider labels.

-#### Special Labels (use sparingly)
+### Label Categories
+
+#### a) Issue Type (select ONE if applicable)
+
+- `💄 Design` - UI/UX design issues
+- `📝 Documentation` - Documentation improvements
+- `⚡️ Performance` - Performance optimization
+
+#### b) Priority (select ONE if applicable)
+
+- `priority:high` - Critical issues, data loss, security, maintainer mentions "urgent"/"serious"/"critical"
+- `priority:medium` - Important issues affecting multiple users, significant functionality impact
+- `priority:low` - Nice to have, minor issues, edge cases
+
+**Priority Guidelines**:
+
+- Set `priority:high` for: data loss, authentication failures, deployment blockers, critical bugs
+- Set `priority:medium` for: feature bugs affecting multiple users, workflow issues
+- Set `priority:low` for: cosmetic issues, feature requests, configuration questions
+
+#### c) Platform (select ALL applicable)
+
+- `platform:web`
+- `platform:desktop`
+- `platform:mobile`
+
+#### d) Device (for platform:web, select ONE)
+
+- `device:pc`
+- `device:mobile`
+
+#### e) Operating System (select ALL applicable)
+
+- `os:windows`
+- `os:macos`
+- `os:linux`
+- `os:ios`
+- `os:android`
+
+#### f) Hosting Platform (select ONE)
+
+- `hosting:cloud` - Official LobeHub Cloud
+- `hosting:self-host` - Self-hosted deployment
+- `hosting:vercel` - Vercel deployment
+- `hosting:zeabur` - Zeabur deployment
+- `hosting:railway` - Railway deployment
+
+#### g) Deployment Mode (select ONE if mentioned)
+
+- `deployment:server` - Server-side database mode
+- `deployment:client` - Client-side database mode
+- `deployment:pglite` - PGLite mode
+
+**Additional deployment tags**:
+
+- `docker` - If using Docker deployment
+- `electron` - If desktop/Electron specific
+
+#### h) Model Provider (select ALL applicable)
+
+See "Provider Detection" section above for complete list.
+
+**IMPORTANT**: Always scan issue title and body for provider keywords!
+
+#### i) Feature/Component (select ALL applicable)
+
+Core Features:
+
+- `feature:settings` - Settings and configuration
+- `feature:agent` - Agent/Assistant functionality
+- `feature:topic` - Topic/Conversation management
+- `feature:marketplace` - Agent marketplace
+
+File & Knowledge:
+
+- `feature:files` - File upload/management
+- `feature:knowledge-base` - Knowledge base and RAG
+- `feature:export` - Export functionality
+
+Model Capabilities:
+
+- `feature:streaming` - Streaming responses
+- `feature:tool` - Tool calling
+- `feature:vision` - Vision/multimodal capabilities
+- `feature:image` - AI image generation
+- `feature:dalle` - DALL-E specific
+- `feature:tts` - Text-to-speech
+
+Technical:
+
+- `feature:api` - Backend API
+- `feature:auth` - Authentication/authorization
+- `feature:sync` - Cloud sync functionality
+- `feature:search` - Search functionality
+- `feature:mcp` - MCP integration
+- `feature:editor` - Lobe Editor
+- `feature:markdown` - Markdown rendering
+- `feature:thread` - Thread/Subtopic functionality
+
+Collaboration:
+
+- `feature:group-chat` - Group chat functionality
+- `feature:memory` - Memory feature
+- `feature:team-workspace` - Team workspace
+
+#### j) Workflow/Status

- `i18n` - Internationalization / translation issues
 - `Duplicate` - Only if duplicate of an OPEN issue (mention issue number)
- `🤔 Need Reproduce` - Needs reproduction steps
+- `needs-reproduction` - Cannot reproduce, needs more information
 - `good-first-issue` - Good for first-time contributors
+- `🤔 Need Reproduce` - Needs reproduction steps

 ### Step 4: Apply Labels

+Add labels (comma-separated, no spaces after commas):
+
+```bash
+gh issue edit [ISSUE_NUMBER] --add-label "label1,label2,label3"
+```
+
+Remove "unconfirm" label if adding other labels:
+
 ```bash
-gh issue edit [ISSUE_NUMBER] --add-label "label1,label2"
 gh issue edit [ISSUE_NUMBER] --remove-label "unconfirm"
 ```

+**Important**: Combine both commands when possible for efficiency.
+
 ### Step 5: Log Summary

-For each issue, provide a brief reasoning (1-2 sentences) explaining why each label was chosen.
+For each issue, provide reasoning (2-4 sentences):

-## What NOT to Label
-
-These categories are INTENTIONALLY OMITTED — do NOT apply them:
-
-| Do NOT apply | Reason |
-|-------------|--------|
-| `platform:web`, `platform:desktop`, `platform:mobile` | Inferred from `electron`/`pwa` or issue context |
-| `os:windows`, `os:macos`, `os:linux`, `os:ios`, `os:android` | Low triage value; inferred from `electron` |
-| `device:pc`, `device:mobile` | Redundant with platform |
-| `hosting:cloud`, `hosting:self-host`, `hosting:vercel`, etc. | Low triage value unless deployment-specific |
-| `deployment:server`, `deployment:client`, `deployment:pglite` | Low triage value; inferred from `electron` |
-| `priority:high`, `priority:medium`, `priority:low` | Maintainers judge priority themselves |
-| `🐛 Bug`, `💄 Design`, `📝 Documentation`, `⚡️ Performance` | Issue type is already indicated by GitHub issue template |
-| `Inactive` | Handled separately; do NOT add during triage |
-
-## Examples
-
-### Example 1: Electron desktop bug
-
-**Issue**: "Connection failure when executing tasks on macOS desktop app"
-
-**Analysis**: Desktop Electron app issue with task scheduling.
-
-**Labels**: `electron,feature:schedule-task`
-
-**Why**: `electron` covers the desktop platform. `feature:schedule-task` identifies the affected feature. No need for `platform:desktop`, `os:macos`, `hosting:cloud`, `priority:*`, or `Bug`.
-
-### Example 2: Provider-specific issue
-
-**Issue**: "Gemini tool calling returns empty response on desktop"
-
-**Analysis**: Desktop app issue, but the core problem is Gemini provider behavior with tool calling.
-
-**Labels**: `electron,provider:gemini`
-
-**Why**: `electron` for the desktop context. `provider:gemini` because the issue is about Gemini's behavior. The tool calling aspect is secondary — the provider is the key domain.
-
-### Example 3: Feature-specific issue
-
-**Issue**: "Underscore auto-escaped in markdown editor"
-
-**Analysis**: Markdown rendering bug in the editor component.
-
-**Labels**: `feature:markdown`
-
-**Why**: Single label is sufficient — the issue is purely about markdown rendering. No need for platform, OS, or priority labels.
-
-### Example 4: Web-only feature request
-
-**Issue**: "Add search functionality to plugin marketplace"
-
-**Analysis**: Feature request for marketplace search. Web platform, no specific provider.
-
-**Labels**: `feature:marketplace,feature:search`
-
-**Why**: Two feature labels capture the core domain. No platform label needed — it's a web app by default.
-
-### Example 5: Ollama self-hosted issue
-
-**Issue**: "Ollama model not loading on self-hosted Docker deployment"
-
-**Analysis**: Provider-specific issue with Ollama on Docker.
-
-**Labels**: `docker,provider:ollama`
-
-**Why**: `docker` for the deployment context, `provider:ollama` for the model provider. No need for `hosting:self-host` or `platform:*`.
+- Labels applied and why
+- Key factors from issue template/comments
+- Provider detection reasoning (if applicable)

 ## Important Rules

-1. **1-3 labels per issue** — Never exceed 3 labels. If you find yourself adding more, you're being too granular.
-2. **`electron` replaces all platform/OS/deployment labels** — Never combine `electron` with `platform:desktop`, `os:*`, `deployment:*`, or `hosting:*`.
-3. **Provider only when relevant** — Only add `provider:*` if the issue is specifically about that provider's behavior.
-4. **No priority, no type** — Do NOT add `priority:*`, `🐛 Bug`, `💄 Design`, etc. Maintainers handle these.
-5. **No comments** — Only apply labels. Do NOT post comments to issues.
-6. **Remove `unconfirm`** — Always remove the `unconfirm` label when applying triage labels.
+1. **Read Carefully**: Read issue template fields AND issue body/title for complete context
+2. **Provider Detection**: ALWAYS check title and body for provider keywords (including aihubmix, etc.)
+3. **Multiple Categories**: Use ALL applicable labels from different categories
+4. **Label Prefixes**: Always use proper prefixes (`feature:`, `provider:`, `os:`, `platform:`, etc.)
+5. **Maintainer Comments**: Check maintainer comments for priority/status hints
+6. **No Comments**: Only apply labels, DO NOT post comments to issues
+7. **Batch Efficiency**: Process issues in parallel when possible
+
+## Common Patterns
+
+### Provider in Environment Variables
+
+If issue body contains `AIHUBMIX_*`, add `provider:aihubmix`
+
+### Multiple Provider Issues
+
+If comparing providers (e.g., "works with OpenAI but not Gemini"), add both provider labels
+
+### Desktop Issues
+
+Desktop issues often need: `platform:desktop`, `electron`, specific `os:*`, and `deployment:client` or `deployment:server`
+
+### Knowledge Base Issues
+
+Usually need: `feature:knowledge-base`, often with `feature:files`, may need `provider:*` for embedding models
+
+### Tool Calling Issues
+
+Usually need: `feature:tool`, specific `provider:*`, may need `feature:mcp` if MCP-related
+
+### Streaming Issues
+
+Usually need: `feature:streaming`, specific `provider:*`, check for timeout/performance issues
+
+## Example Triage
+
+**Issue #8850**: "aihubmix 的优惠 app 没有生效"
+
+**Analysis**:
+
+- Title contains "aihubmix" → `provider:aihubmix`
+- Template shows: Windows, Chrome, Docker, Client mode
+- About API discount codes not working
+
+**Labels Applied**:
+
+```bash
+gh issue edit 8850 --add-label "provider:aihubmix,platform:web,os:windows,deployment:client,hosting:self-host,docker"
+gh issue edit 8850 --remove-label "unconfirm"
+```
+
+**Reasoning**: AIHubMix provider discount feature not working. Client mode deployment on Windows with Docker. Provider detection from title keyword "aihubmix".
@@ -77,9 +77,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # use a proxy to connect to the Anthropic API
 # ANTHROPIC_PROXY_URL=https://api.anthropic.com

-# Anthropic SDK client timeout in milliseconds
-# ANTHROPIC_CLIENT_TIMEOUT=295000
-
 # ## Google AI  ####

 # GOOGLE_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -10,10 +10,6 @@ inputs:
    description: Pass-through to actions/setup-node package-manager-cache
    required: false
    default: 'false'
-  bun-version:
-    description: Bun version
-    required: false
-    default: '1.3.2'

 runs:
  using: composite
@@ -25,8 +21,6 @@ runs:

    - name: Install bun
      uses: oven-sh/setup-bun@v2
-      with:
-        bun-version: ${{ inputs.bun-version }}

    - name: Setup Node.js
      uses: actions/setup-node@v6
@@ -59,14 +59,7 @@ jobs:
    timeout-minutes: 30
    steps:
      - name: Checkout
-        env:
-          REF_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-          REPOSITORY: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
-        run: |
-          git init .
-          git remote add origin "https://github.com/${REPOSITORY}.git"
-          git fetch --no-tags --depth=1 origin "${REF_SHA}"
-          git checkout --force FETCH_HEAD
+        uses: actions/checkout@v6

      - name: Setup environment
        uses: ./.github/actions/setup-env
@@ -16,14 +16,14 @@ permissions:
 jobs:
  run:
    permissions:
-      issues: write
-      pull-requests: write
+      issues: write # for actions-cool/issues-helper to update issues
+      pull-requests: write # for actions-cool/issues-helper to update PRs
    runs-on: ubuntu-latest
    steps:
      - name: Auto Comment on Issues Closed
        uses: wow-actions/auto-comment@v1
        with:
-          GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+          GITHUB_TOKEN: ${{ secrets.GH_TOKEN}}
          issuesClosed: |
            ✅ @{{ author }}

@@ -51,4 +51,11 @@ jobs:
            The growth of project is inseparable from user feedback and contribution, thanks for your contribution! If you are interesting with the lobehub developer community, please join our [discord](https://discord.com/invite/AYFPHvv2jT) and then dm @arvinxx or @canisminor1990. They will invite you to our private developer channel. We are talking about the lobe-chat development or sharing ai newsletter around the world.
          emoji: 'hooray'
          pr-emoji: '+1, heart'
-
+      - name: Remove inactive
+        if: github.event.issue.state == 'open' && github.actor == github.event.issue.user.login
+        uses: actions-cool/issues-helper@v3
+        with:
+          actions: 'remove-labels'
+          token: ${{ secrets.GH_TOKEN }}
+          issue-number: ${{ github.event.issue.number }}
+          labels: 'Inactive'
@@ -0,0 +1,63 @@
+name: Issue Close Require
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+
+permissions:
+  contents: read
+
+jobs:
+  issue-check-inactive:
+    permissions:
+      issues: write # for actions-cool/issues-helper to update issues
+      pull-requests: write # for actions-cool/issues-helper to update PRs
+    runs-on: ubuntu-latest
+    steps:
+      - name: check-inactive
+        uses: actions-cool/issues-helper@v3
+        with:
+          actions: 'check-inactive'
+          token: ${{ secrets.GH_TOKEN }}
+          inactive-label: 'Inactive'
+          inactive-day: 60
+
+  issue-close-require:
+    permissions:
+      issues: write # for actions-cool/issues-helper to update issues
+      pull-requests: write # for actions-cool/issues-helper to update PRs
+    runs-on: ubuntu-latest
+    steps:
+      - name: need reproduce
+        uses: actions-cool/issues-helper@v3
+        with:
+          actions: 'close-issues'
+          token: ${{ secrets.GH_TOKEN }}
+          labels: '✅ Fixed'
+          inactive-day: 3
+          body: |
+            👋 @{{ author }}
+            <br/>
+            Since the issue was labeled with `✅ Fixed`, but no response in 3 days. This issue will be closed. If you have any questions, you can comment and reply.
+      - name: need reproduce
+        uses: actions-cool/issues-helper@v3
+        with:
+          actions: 'close-issues'
+          token: ${{ secrets.GH_TOKEN }}
+          labels: '🤔 Need Reproduce'
+          inactive-day: 3
+          body: |
+            👋 @{{ author }}
+            <br/>
+            Since the issue was labeled with `🤔 Need Reproduce`, but no response in 3 days. This issue will be closed. If you have any questions, you can comment and reply.
+      - name: need reproduce
+        uses: actions-cool/issues-helper@v3
+        with:
+          actions: 'close-issues'
+          token: ${{ secrets.GH_TOKEN }}
+          labels: "🙅🏻‍♀️ WON'T DO"
+          inactive-day: 3
+          body: |
+            👋 @{{ github.event.issue.user.login }}
+            <br/>
+            Since the issue was labeled with `🙅🏻‍♀️ WON'T DO`, and no response in 3 days. This issue will be closed. If you have any questions, you can comment and reply.
@@ -20,7 +20,7 @@ jobs:
      - uses: actions/checkout@v6

      - name: Clean issue notice
-        uses: actions-cool/issues-helper@e361abf610221f09495ad510cb1e69328d839e1c # v3.7.6
+        uses: actions-cool/issues-helper@v3
        with:
          actions: 'close-issues'
          labels: '🚨 Sync Fail'
@@ -37,7 +37,7 @@ jobs:

      - name: Sync check
        if: failure()
-        uses: actions-cool/issues-helper@e361abf610221f09495ad510cb1e69328d839e1c # v3.7.6
+        uses: actions-cool/issues-helper@v3
        with:
          actions: 'create-issue'
          title: '🚨 同步失败 | Sync Fail'
@@ -35,15 +35,7 @@ jobs:
      PACKAGES: '@lobechat/file-loaders @lobechat/prompts @lobechat/model-runtime @lobechat/web-crawler @lobechat/electron-server-ipc @lobechat/utils @lobechat/python-interpreter @lobechat/context-engine @lobechat/agent-runtime @lobechat/conversation-flow @lobechat/ssrf-safe-fetch @lobechat/memory-user-memory @lobechat/types @lobechat/builtin-tool-lobe-agent model-bank'

    steps:
-      - name: Checkout
-        env:
-          REF_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-          REPOSITORY: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
-        run: |
-          git init .
-          git remote add origin "https://github.com/${REPOSITORY}.git"
-          git fetch --no-tags --depth=1 origin "${REF_SHA}"
-          git checkout --force FETCH_HEAD
+      - uses: actions/checkout@v6

      - name: Setup environment
        uses: ./.github/actions/setup-env
@@ -109,15 +101,7 @@ jobs:
    name: Test App (shard ${{ matrix.shard }}/3)
    runs-on: ubuntu-latest
    steps:
-      - name: Checkout
-        env:
-          REF_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-          REPOSITORY: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
-        run: |
-          git init .
-          git remote add origin "https://github.com/${REPOSITORY}.git"
-          git fetch --no-tags --depth=1 origin "${REF_SHA}"
-          git checkout --force FETCH_HEAD
+      - uses: actions/checkout@v6

      - name: Setup environment
        uses: ./.github/actions/setup-env
@@ -144,15 +128,7 @@ jobs:
    name: Merge and Upload App Coverage
    runs-on: ubuntu-latest
    steps:
-      - name: Checkout
-        env:
-          REF_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-          REPOSITORY: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
-        run: |
-          git init .
-          git remote add origin "https://github.com/${REPOSITORY}.git"
-          git fetch --no-tags --depth=1 origin "${REF_SHA}"
-          git checkout --force FETCH_HEAD
+      - uses: actions/checkout@v6

      - name: Setup environment
        uses: ./.github/actions/setup-env
@@ -185,15 +161,7 @@ jobs:
    runs-on: ubuntu-latest

    steps:
-      - name: Checkout
-        env:
-          REF_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-          REPOSITORY: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
-        run: |
-          git init .
-          git remote add origin "https://github.com/${REPOSITORY}.git"
-          git fetch --no-tags --depth=1 origin "${REF_SHA}"
-          git checkout --force FETCH_HEAD
+      - uses: actions/checkout@v6

      - name: Setup environment
        uses: ./.github/actions/setup-env
@@ -239,15 +207,7 @@ jobs:
          - 5432:5432

    steps:
-      - name: Checkout
-        env:
-          REF_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.sha || github.sha }}
-          REPOSITORY: ${{ github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name || github.repository }}
-        run: |
-          git init .
-          git remote add origin "https://github.com/${REPOSITORY}.git"
-          git fetch --no-tags --depth=1 origin "${REF_SHA}"
-          git checkout --force FETCH_HEAD
+      - uses: actions/checkout@v6

      - name: Setup environment
        uses: ./.github/actions/setup-env
@@ -96,7 +96,7 @@ sitemap*.xml
 robots.txt

 # Git hooks
-.githooks/prepare-commit-msg
+.husky/prepare-commit-msg

 # Documents and media
 *.pdf
@@ -106,7 +106,6 @@ vertex-ai-key.json

 # Agent tracing snapshots
 .agent-tracing/
-.llm-generation-tracing/

 # AI coding tools
 .local/
@@ -1,13 +1,5 @@
-#!/usr/bin/env sh
-set -e
-
-[ "${HUSKY-}" = "0" ] && exit 0
-
-export PATH="node_modules/.bin:$PATH"
-
 BRANCH=$(git branch --show-current)
 if [ "$BRANCH" = "dev" ] || [ "$BRANCH" = "main" ]; then
  npm run type-check
 fi
-
-lint-staged
+npx --no-install lint-staged
@@ -8,7 +8,7 @@
 .history
 .temp
 .env.local
-.githooks
+.husky
 .npmrc
 .gitkeep
 venv
@@ -59,4 +59,4 @@ Dockerfile*

 # misc
 # add other ignore file below
-.next
+.next
@@ -219,7 +219,7 @@ ENV \
    # AiHubMix
    AIHUBMIX_API_KEY="" AIHUBMIX_MODEL_LIST="" \
    # Anthropic
-    ANTHROPIC_API_KEY="" ANTHROPIC_CLIENT_TIMEOUT="" ANTHROPIC_MODEL_LIST="" ANTHROPIC_PROXY_URL="" \
+    ANTHROPIC_API_KEY="" ANTHROPIC_MODEL_LIST="" ANTHROPIC_PROXY_URL="" \
    # Amazon Bedrock
    ENABLED_AWS_BEDROCK="" AWS_ACCESS_KEY_ID="" AWS_SECRET_ACCESS_KEY="" AWS_REGION="" AWS_BEDROCK_MODEL_LIST="" \
    # Azure OpenAI
@@ -4,11 +4,9 @@

 # LobeHub

-LobeHub organizes your agents into 7×24 operation.
-
-It hires, schedules, reports on your entire AI team.
-
-You stay in charge — without staying online.
+LobeHub is the ultimate space for work and life: <br/>
+to find, build, and collaborate with agent teammates that grow with you.<br/>
+We’re building the world’s largest human–agent co-evolving network.

 **English** · [简体中文](./README.zh-CN.md) · [Official Site][official-site] · [Changelog][changelog] · [Documents][docs] · [Blog][blog] · [Feedback][github-issues-link]

@@ -27,6 +25,7 @@ You stay in charge — without staying online.
 [![][github-stars-shield]][github-stars-link]
 [![][github-issues-shield]][github-issues-link]
 [![][github-license-shield]][github-license-link]<br>
+[![][sponsor-shield]][sponsor-link]

 **Share LobeHub Repository**

@@ -38,9 +37,9 @@ You stay in charge — without staying online.
 [![][share-mastodon-shield]][share-mastodon-link]
 [![][share-linkedin-shield]][share-linkedin-link]

-<sup>Your Chief Agent Operator</sup>
+<sup>Agent teammates that grow with you</sup>

-<a href="https://www.producthunt.com/products/lobehub?embed=true&amp;utm_source=badge-top-post-badge&amp;utm_medium=badge&amp;utm_campaign=badge-lobehub-2" target="_blank" rel="noopener noreferrer"><img alt="LobeHub - Your Chief Agent Operator for multi-agent work | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1147569&amp;theme=light&amp;period=daily&amp;t=1779247564355"></a> <a href="https://trendshift.io/repositories/19224" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19224" alt="lobehub%2Flobehub | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+[![][github-trending-shield]][github-trending-url]

 [![](https://vercel.com/oss/program-badge.svg)](https://vercel.com/oss)

@@ -53,10 +52,30 @@ You stay in charge — without staying online.

 - [👋🏻 Getting Started & Join Our Community](#-getting-started--join-our-community)
 - [✨ Features](#-features)
-  - [Operator: Agents as the Unit of Work](#operator-agents-as-the-unit-of-work)
  - [Create: Agents as the Unit of Work](#create-agents-as-the-unit-of-work)
  - [Collaborate: Scale New Forms of Collaboration Networks](#collaborate-scale-new-forms-of-collaboration-networks)
  - [Evolve: Co-evolution of Humans and Agents](#evolve-co-evolution-of-humans-and-agents)
+  - [MCP Plugin One-Click Installation](#mcp-plugin-one-click-installation)
+  - [MCP Marketplace](#mcp-marketplace)
+  - [Desktop App](#desktop-app)
+  - [Smart Internet Search](#smart-internet-search)
+  - [Chain of Thought](#chain-of-thought)
+  - [Branching Conversations](#branching-conversations)
+  - [Artifacts Support](#artifacts-support)
+  - [File Upload /Knowledge Base](#file-upload-knowledge-base)
+  - [Multi-Model Service Provider Support](#multi-model-service-provider-support)
+  - [Local Large Language Model (LLM) Support](#local-large-language-model-llm-support)
+  - [Model Visual Recognition](#model-visual-recognition)
+  - [TTS & STT Voice Conversation](#tts--stt-voice-conversation)
+  - [Text to Image Generation](#text-to-image-generation)
+  - [Plugin System (Function Calling)](#plugin-system-function-calling)
+  - [Agent Market (GPTs)](#agent-market-gpts)
+  - [Support Local / Remote Database](#support-local--remote-database)
+  - [Support Multi-User Management](#support-multi-user-management)
+  - [Progressive Web App (PWA)](#progressive-web-app-pwa)
+  - [Mobile Device Adaptation](#mobile-device-adaptation)
+  - [Custom Themes](#custom-themes)
+  - [`*` What's more](#-whats-more)
 - [🛳 Self Hosting](#-self-hosting)
  - [`A` Deploying with Vercel, Zeabur , Sealos or Alibaba Cloud](#a-deploying-with-vercel-zeabur--sealos-or-alibaba-cloud)
  - [`B` Deploying with Docker](#b-deploying-with-docker)
@@ -76,7 +95,7 @@ You stay in charge — without staying online.

 <br/>

-<https://github.com/user-attachments/assets/0a33365f-b786-48b5-9ed6-f8af7927bccb>
+<https://github.com/user-attachments/assets/6710ad97-03d0-4175-bd75-adff9b55eca2>

 ## 👋🏻 Getting Started & Join Our Community

@@ -85,9 +104,9 @@ By adopting the Bootstrapping approach, we aim to provide developers and users w

 Whether for users or professional developers, LobeHub will be your AI Agent playground. Please be aware that LobeHub is currently under active development, and feedback is welcome for any [issues][issues-link] encountered.

-| [![](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1065874&theme=light&t=1769347414733)](https://www.producthunt.com/products/lobehub?launch=lobehub-2&embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-lobehub) | We are live on Product Hunt! We are thrilled to bring LobeHub to the world. If you believe in a future where humans and agents co-evolve, please support our journey. |
-| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [![][discord-shield-badge]][discord-link]                                                                                                                                                                                                                          | Join our Discord community! This is where you can connect with developers and other enthusiastic users of LobeHub.                                                    |
+| [![](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) | We are live on Product Hunt! We are thrilled to bring LobeHub to the world. If you believe in a future where humans and agents co-evolve, please support our journey. |
+| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [![][discord-shield-badge]][discord-link]                                                                                                                                                                                                         | Join our Discord community! This is where you can connect with developers and other enthusiastic users of LobeHub.                                                    |

 > \[!IMPORTANT]
 >
@@ -111,26 +130,7 @@ Today’s agents are one-off, task-driven tools. They lack context, live in isol

 LobeHub is a work-and-lifestyle space to find, build, and collaborate with agent teammates that grow with you. In LobeHub, we treat **Agents as the unit of work**, providing an infrastructure where humans and agents co-evolve.

-![](https://github.com/user-attachments/assets/89d1c402-a62b-4794-82ea-17e5ee1a6165)
-
-### Operator: Agents as the Unit of Work
-
-Hires, schedules, and reports on your entire AI team.
-
- **More productivity. Fewer tools**: Bring all your agents under one roof.
- **IM Gateway**: Agents where you already chat.
-
-![](https://github.com/user-attachments/assets/7b08d6d9-9dff-4b06-a919-324630554509)
-
-[![][back-to-top]](#readme-top)
-
-<div align="right">
-
-[![][back-to-top]](#readme-top)
-
-</div>
-
-![](https://github.com/user-attachments/assets/81e89324-fc66-4024-99a3-aa8e16ec8184)
+![](https://hub-apac-1.lobeobjects.space/blog/assets/2204cde2228fb3f583f3f2c090bc49fb.webp)

 ### Create: Agents as the Unit of Work

@@ -139,8 +139,6 @@ Building a personalized AI team starts with the **Agent Builder**. You can descr
 - **Unified Intelligence**: Seamlessly access any model and any modality—all under your control.
 - **10,000+ Skills**: Connect your agents to the skills you use every day with a library of over 10,000 tools and MCP-compatible plugins.

-![](https://github.com/user-attachments/assets/949b8166-486d-4750-ad7a-cfe7bfcb84e3)
-
 [![][back-to-top]](#readme-top)

 <div align="right">
@@ -160,8 +158,6 @@ LobeHub introduces **Agent Groups**, allowing you to work with agents like real
 - **Project**: Organize work by project to keep everything structured and easy to track.
 - **Workspace**: A shared space for teams to collaborate with agents, ensuring clear ownership and visibility across the organization.

-![](https://github.com/user-attachments/assets/e51526c6-e09c-4a5a-9cec-dcd3fd68a3a8)
-
 [![][back-to-top]](#readme-top)

 <div align="right">
@@ -179,7 +175,113 @@ The best AI is one that understands you deeply. LobeHub features **Personal Memo
 - **Continual Learning**: Your agents learn from how you work, adapting their behavior to act at the right moment.
 - **White-Box Memory**: We believe in transparency. Your agents use structured, editable memory, giving you full control over what they remember.

-![](https://github.com/user-attachments/assets/5c6e16f0-7f47-4baf-9aeb-3a00deb8ff5b)
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+<details>
+<summary>More Features</summary>
+
+![][image-feat-mcp]
+
+### MCP Plugin One-Click Installation
+
+**Seamlessly Connect Your AI to the World**
+
+Unlock the full potential of your AI by enabling smooth, secure, and dynamic interactions with external tools, data sources, and services. LobeHub's MCP (Model Context Protocol) plugin system breaks down the barriers between your AI and the digital ecosystem, allowing for unprecedented connectivity and functionality.
+
+Transform your conversations into powerful workflows by connecting to databases, APIs, file systems, and more. Experience the freedom of AI that truly understands and interacts with your world.
+
+[![][back-to-top]](#readme-top)
+
+![][image-feat-mcp-market]
+
+### MCP Marketplace
+
+**Discover, Connect, Extend**
+
+Browse a growing library of MCP plugins to expand your AI's capabilities and streamline your workflows effortlessly. Visit [lobehub.com/mcp](https://lobehub.com/mcp) to explore the MCP Marketplace, which offers a curated collection of integrations that enhance your AI's ability to work with various tools and services.
+
+From productivity tools to development environments, discover new ways to extend your AI's reach and effectiveness. Connect with the community and find the perfect plugins for your specific needs.
+
+[![][back-to-top]](#readme-top)
+
+![][image-feat-desktop]
+
+### Desktop App
+
+**Peak Performance, Zero Distractions**
+
+Get the full LobeHub experience without browser limitations—comprehensive, focused, and always ready to go. Our desktop application provides a dedicated environment for your AI interactions, ensuring optimal performance and minimal distractions.
+
+Experience faster response times, better resource management, and a more stable connection to your AI assistant. The desktop app is designed for users who demand the best performance from their AI tools.
+
+[![][back-to-top]](#readme-top)
+
+![][image-feat-web-search]
+
+### Smart Internet Search
+
+**Online Knowledge On Demand**
+
+With real-time internet access, your AI keeps up with the world—news, data, trends, and more. Stay informed and get the most current information available, enabling your AI to provide accurate and up-to-date responses.
+
+Access live information, verify facts, and explore current events without leaving your conversation. Your AI becomes a gateway to the world's knowledge, always current and comprehensive.
+
+[![][back-to-top]](#readme-top)
+
+[![][image-feat-cot]][docs-feat-cot]
+
+### [Chain of Thought][docs-feat-cot]
+
+Experience AI reasoning like never before. Watch as complex problems unfold step by step through our innovative Chain of Thought (CoT) visualization. This breakthrough feature provides unprecedented transparency into AI's decision-making process, allowing you to observe how conclusions are reached in real-time.
+
+By breaking down complex reasoning into clear, logical steps, you can better understand and validate the AI's problem-solving approach. Whether you're debugging, learning, or simply curious about AI reasoning, CoT visualization transforms abstract thinking into an engaging, interactive experience.
+
+[![][back-to-top]](#readme-top)
+
+[![][image-feat-branch]][docs-feat-branch]
+
+### [Branching Conversations][docs-feat-branch]
+
+Introducing a more natural and flexible way to chat with AI. With Branch Conversations, your discussions can flow in multiple directions, just like human conversations do. Create new conversation branches from any message, giving you the freedom to explore different paths while preserving the original context.
+
+Choose between two powerful modes:
+
+- **Continuation Mode:** Seamlessly extend your current discussion while maintaining valuable context
+- **Standalone Mode:** Start fresh with a new topic based on any previous message
+
+This groundbreaking feature transforms linear conversations into dynamic, tree-like structures, enabling deeper exploration of ideas and more productive interactions.
+
+[![][back-to-top]](#readme-top)
+
+[![][image-feat-artifacts]][docs-feat-artifacts]
+
+### [Artifacts Support][docs-feat-artifacts]
+
+Experience the power of Claude Artifacts, now integrated into LobeHub. This revolutionary feature expands the boundaries of AI-human interaction, enabling real-time creation and visualization of diverse content formats.
+
+Create and visualize with unprecedented flexibility:
+
+- Generate and display dynamic SVG graphics
+- Build and render interactive HTML pages in real-time
+- Produce professional documents in multiple formats
+
+[![][back-to-top]](#readme-top)
+
+[![][image-feat-knowledgebase]][docs-feat-knowledgebase]
+
+### [File Upload /Knowledge Base][docs-feat-knowledgebase]
+
+LobeHub supports file upload and knowledge base functionality. You can upload various types of files including documents, images, audio, and video, as well as create knowledge bases, making it convenient for users to manage and search for files. Additionally, you can utilize files and knowledge base features during conversations, enabling a richer dialogue experience.
+
+<https://github.com/user-attachments/assets/faa8cf67-e743-4590-8bf6-ebf6ccc34175>
+
+> \[!TIP]
+>
+> Learn more on [📘 LobeHub Knowledge Base Launch — From Now On, Every Step Counts](https://lobehub.com/blog/knowledge-base)

 <div align="right">

@@ -187,6 +289,277 @@ The best AI is one that understands you deeply. LobeHub features **Personal Memo

 </div>

+[![][image-feat-privoder]][docs-feat-provider]
+
+### [Multi-Model Service Provider Support][docs-feat-provider]
+
+In the continuous development of LobeHub, we deeply understand the importance of diversity in model service providers for meeting the needs of the community when providing AI conversation services. Therefore, we have expanded our support to multiple model service providers, rather than being limited to a single one, in order to offer users a more diverse and rich selection of conversations.
+
+In this way, LobeHub can more flexibly adapt to the needs of different users, while also providing developers with a wider range of choices.
+
+#### Supported Model Service Providers
+
+We have implemented support for the following model service providers:
+
+<!-- PROVIDER LIST -->
+
+<details><summary><kbd>See more providers (+-10)</kbd></summary>
+
+</details>
+
+> 📊 Total providers: [<kbd>**0**</kbd>](https://lobechat.com/discover/providers)
+
+ <!-- PROVIDER LIST -->
+
+At the same time, we are also planning to support more model service providers. If you would like LobeHub to support your favorite service provider, feel free to join our [💬 community discussion](https://github.com/lobehub/lobehub/discussions/1284).
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-local]][docs-feat-local]
+
+### [Local Large Language Model (LLM) Support][docs-feat-local]
+
+To meet the specific needs of users, LobeHub also supports the use of local models based on [Ollama](https://ollama.ai), allowing users to flexibly use their own or third-party models.
+
+> \[!TIP]
+>
+> Learn more about [📘 Using Ollama in LobeHub][docs-usage-ollama] by checking it out.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-vision]][docs-feat-vision]
+
+### [Model Visual Recognition][docs-feat-vision]
+
+LobeHub now supports OpenAI's latest [`gpt-4-vision`](https://platform.openai.com/docs/guides/vision) model with visual recognition capabilities,
+a multimodal intelligence that can perceive visuals. Users can easily upload or drag and drop images into the dialogue box,
+and the agent will be able to recognize the content of the images and engage in intelligent conversation based on this,
+creating smarter and more diversified chat scenarios.
+
+This feature opens up new interactive methods, allowing communication to transcend text and include a wealth of visual elements.
+Whether it's sharing images in daily use or interpreting images within specific industries, the agent provides an outstanding conversational experience.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-tts]][docs-feat-tts]
+
+### [TTS & STT Voice Conversation][docs-feat-tts]
+
+LobeHub supports Text-to-Speech (TTS) and Speech-to-Text (STT) technologies, enabling our application to convert text messages into clear voice outputs,
+allowing users to interact with our conversational agent as if they were talking to a real person. Users can choose from a variety of voices to pair with the agent.
+
+Moreover, TTS offers an excellent solution for those who prefer auditory learning or desire to receive information while busy.
+In LobeHub, we have meticulously selected a range of high-quality voice options (OpenAI Audio, Microsoft Edge Speech) to meet the needs of users from different regions and cultural backgrounds.
+Users can choose the voice that suits their personal preferences or specific scenarios, resulting in a personalized communication experience.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-t2i]][docs-feat-t2i]
+
+### [Text to Image Generation][docs-feat-t2i]
+
+With support for the latest text-to-image generation technology, LobeHub now allows users to invoke image creation tools directly within conversations with the agent. By leveraging the capabilities of AI tools such as [`DALL-E 3`](https://openai.com/dall-e-3), [`MidJourney`](https://www.midjourney.com/), and [`Pollinations`](https://pollinations.ai/), the agents are now equipped to transform your ideas into images.
+
+This enables a more private and immersive creative process, allowing for the seamless integration of visual storytelling into your personal dialogue with the agent.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-plugin]][docs-feat-plugin]
+
+### [Plugin System (Function Calling)][docs-feat-plugin]
+
+The plugin ecosystem of LobeHub is an important extension of its core functionality, greatly enhancing the practicality and flexibility of the LobeHub assistant.
+
+<video controls src="https://github.com/lobehub/lobehub/assets/28616219/f29475a3-f346-4196-a435-41a6373ab9e2" muted="false"></video>
+
+By utilizing plugins, LobeHub assistants can obtain and process real-time information, such as searching for web information and providing users with instant and relevant news.
+
+In addition, these plugins are not limited to news aggregation, but can also extend to other practical functions, such as quickly searching documents, generating images, obtaining data from various platforms like Bilibili, Steam, and interacting with various third-party services.
+
+> \[!TIP]
+>
+> Learn more about [📘 Plugin Usage][docs-usage-plugin] by checking it out.
+
+<!-- PLUGIN LIST -->
+
+| Recent Submits                                                                                                             | Description                                                                                                                                     |
+| -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Shopping tools](https://lobechat.com/discover/plugin/ShoppingTools)<br/><sup>By **shoppingtools** on **2026-01-12**</sup> | Search for products on eBay & AliExpress, find eBay events & coupons. Get prompt examples.<br/>`shopping` `e-bay` `ali-express` `coupons`       |
+| [SEO Assistant](https://lobechat.com/discover/plugin/seo_assistant)<br/><sup>By **webfx** on **2026-01-12**</sup>          | The SEO Assistant can generate search engine keyword information in order to aid the creation of content.<br/>`seo` `keyword`                   |
+| [Video Captions](https://lobechat.com/discover/plugin/VideoCaptions)<br/><sup>By **maila** on **2025-12-13**</sup>         | Convert Youtube links into transcribed text, enable asking questions, create chapters, and summarize its content.<br/>`video-to-text` `youtube` |
+| [WeatherGPT](https://lobechat.com/discover/plugin/WeatherGPT)<br/><sup>By **steven-tey** on **2025-12-13**</sup>           | Get current weather information for a specific location.<br/>`weather`                                                                          |
+
+> 📊 Total plugins: [<kbd>**40**</kbd>](https://lobechat.com/discover/plugins)
+
+ <!-- PLUGIN LIST -->
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-agent]][docs-feat-agent]
+
+### [Agent Market (GPTs)][docs-feat-agent]
+
+In LobeHub Agent Marketplace, creators can discover a vibrant and innovative community that brings together a multitude of well-designed agents,
+which not only play an important role in work scenarios but also offer great convenience in learning processes.
+Our marketplace is not just a showcase platform but also a collaborative space. Here, everyone can contribute their wisdom and share the agents they have developed.
+
+> \[!TIP]
+>
+> By [🤖/🏪 Submit Agents][submit-agents-link], you can easily submit your agent creations to our platform.
+> Importantly, LobeHub has established a sophisticated automated internationalization (i18n) workflow,
+> capable of seamlessly translating your agent into multiple language versions.
+> This means that no matter what language your users speak, they can experience your agent without barriers.
+
+> \[!IMPORTANT]
+>
+> We welcome all users to join this growing ecosystem and participate in the iteration and optimization of agents.
+> Together, we can create more interesting, practical, and innovative agents, further enriching the diversity and practicality of the agent offerings.
+
+<!-- AGENT LIST -->
+
+| Recent Submits                                                                                                                                                                 | Description                                                                                                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| [Turtle Soup Host](https://lobechat.com/discover/assistant/lateral-thinking-puzzle)<br/><sup>By **[CSY2022](https://github.com/CSY2022)** on **2025-06-19**</sup>              | A turtle soup host needs to provide the scenario, the complete story (truth of the event), and the key point (the condition for guessing correctly).<br/>`turtle-soup` `reasoning` `interaction` `puzzle` `role-playing` |
+| [Academic Writing Assistant](https://lobechat.com/discover/assistant/academic-writing-assistant)<br/><sup>By **[swarfte](https://github.com/swarfte)** on **2025-06-17**</sup> | Expert in academic research paper writing and formal documentation<br/>`academic-writing` `research` `formal-style`                                                                                                      |
+| [Gourmet Reviewer🍟](https://lobechat.com/discover/assistant/food-reviewer)<br/><sup>By **[renhai-lab](https://github.com/renhai-lab)** on **2025-06-17**</sup>                | Food critique expert<br/>`gourmet` `review` `writing`                                                                                                                                                                    |
+| [Minecraft Senior Developer](https://lobechat.com/discover/assistant/java-development)<br/><sup>By **[iamyuuk](https://github.com/iamyuuk)** on **2025-06-17**</sup>           | Expert in advanced Java development and Minecraft mod and server plugin development<br/>`development` `programming` `minecraft` `java`                                                                                   |
+
+> 📊 Total agents: [<kbd>**505**</kbd> ](https://lobechat.com/discover/assistants)
+
+ <!-- AGENT LIST -->
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-database]][docs-feat-database]
+
+### [Support Local / Remote Database][docs-feat-database]
+
+LobeHub supports the use of both server-side and local databases. Depending on your needs, you can choose the appropriate deployment solution:
+
+- **Local database**: suitable for users who want more control over their data and privacy protection. LobeHub uses CRDT (Conflict-Free Replicated Data Type) technology to achieve multi-device synchronization. This is an experimental feature aimed at providing a seamless data synchronization experience.
+- **Server-side database**: suitable for users who want a more convenient user experience. LobeHub supports PostgreSQL as a server-side database. For detailed documentation on how to configure the server-side database, please visit [Configure Server-side Database](https://lobehub.com/docs/self-hosting/advanced/server-database).
+
+Regardless of which database you choose, LobeHub can provide you with an excellent user experience.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-auth]][docs-feat-auth]
+
+### [Support Multi-User Management][docs-feat-auth]
+
+LobeHub supports multi-user management and provides flexible user authentication solutions:
+
+- **Better Auth**: LobeHub integrates `Better Auth`, a modern and flexible authentication library that supports multiple authentication methods, including OAuth, email login, credential login, magic links, and more. With `Better Auth`, you can easily implement user registration, login, session management, social login, multi-factor authentication (MFA), and other functions to ensure the security and privacy of user data.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-pwa]][docs-feat-pwa]
+
+### [Progressive Web App (PWA)][docs-feat-pwa]
+
+We deeply understand the importance of providing a seamless experience for users in today's multi-device environment.
+Therefore, we have adopted Progressive Web Application ([PWA](https://support.google.com/chrome/answer/9658361)) technology,
+a modern web technology that elevates web applications to an experience close to that of native apps.
+
+Through PWA, LobeHub can offer a highly optimized user experience on both desktop and mobile devices while maintaining high-performance characteristics.
+Visually and in terms of feel, we have also meticulously designed the interface to ensure it is indistinguishable from native apps,
+providing smooth animations, responsive layouts, and adapting to different device screen resolutions.
+
+> \[!NOTE]
+>
+> If you are unfamiliar with the installation process of PWA, you can add LobeHub as your desktop application (also applicable to mobile devices) by following these steps:
+>
+> - Launch the Chrome or Edge browser on your computer.
+> - Visit the LobeHub webpage.
+> - In the upper right corner of the address bar, click on the <kbd>Install</kbd> icon.
+> - Follow the instructions on the screen to complete the PWA Installation.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-mobile]][docs-feat-mobile]
+
+### [Mobile Device Adaptation][docs-feat-mobile]
+
+We have carried out a series of optimization designs for mobile devices to enhance the user's mobile experience. Currently, we are iterating on the mobile user experience to achieve smoother and more intuitive interactions. If you have any suggestions or ideas, we welcome you to provide feedback through GitHub Issues or Pull Requests.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-theme]][docs-feat-theme]
+
+### [Custom Themes][docs-feat-theme]
+
+As a design-engineering-oriented application, LobeHub places great emphasis on users' personalized experiences,
+hence introducing flexible and diverse theme modes, including a light mode for daytime and a dark mode for nighttime.
+Beyond switching theme modes, a range of color customization options allow users to adjust the application's theme colors according to their preferences.
+Whether it's a desire for a sober dark blue, a lively peach pink, or a professional gray-white, users can find their style of color choices in LobeHub.
+
+> \[!TIP]
+>
+> The default configuration can intelligently recognize the user's system color mode and automatically switch themes to ensure a consistent visual experience with the operating system.
+> For users who like to manually control details, LobeHub also offers intuitive setting options and a choice between chat bubble mode and document mode for conversation scenarios.
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+### `*` What's more
+
+Beside these features, LobeHub also have much better basic technique underground:
+
+- [x] 💨 **Quick Deployment**: Using the Vercel platform or docker image, you can deploy with just one click and complete the process within 1 minute without any complex configuration.
+- [x] 🌐 **Custom Domain**: If users have their own domain, they can bind it to the platform for quick access to the dialogue agent from anywhere.
+- [x] 🔒 **Privacy Protection**: All data is stored locally in the user's browser, ensuring user privacy.
+- [x] 💎 **Exquisite UI Design**: With a carefully designed interface, it offers an elegant appearance and smooth interaction. It supports light and dark themes and is mobile-friendly. PWA support provides a more native-like experience.
+- [x] 🗣️ **Smooth Conversation Experience**: Fluid responses ensure a smooth conversation experience. It fully supports Markdown rendering, including code highlighting, LaTex formulas, Mermaid flowcharts, and more.
+
+</details>
+
 > ✨ more features will be added when LobeHub evolve.

 <div align="right">
@@ -482,10 +855,28 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [docs-dev-guide]: https://lobehub.com/docs/development/start
 [docs-docker]: https://lobehub.com/docs/self-hosting/server-database/docker-compose
 [docs-env-var]: https://lobehub.com/docs/self-hosting/environment-variables
+[docs-feat-agent]: https://lobehub.com/docs/usage/features/agent-market
+[docs-feat-artifacts]: https://lobehub.com/docs/usage/features/artifacts
+[docs-feat-auth]: https://lobehub.com/docs/usage/features/auth
+[docs-feat-branch]: https://lobehub.com/docs/usage/features/branching-conversations
+[docs-feat-cot]: https://lobehub.com/docs/usage/features/cot
+[docs-feat-database]: https://lobehub.com/docs/usage/features/database
+[docs-feat-knowledgebase]: https://lobehub.com/blog/knowledge-base
+[docs-feat-local]: https://lobehub.com/docs/usage/features/local-llm
+[docs-feat-mobile]: https://lobehub.com/docs/usage/features/mobile
+[docs-feat-plugin]: https://lobehub.com/docs/usage/features/plugin-system
+[docs-feat-provider]: https://lobehub.com/docs/usage/features/multi-ai-providers
+[docs-feat-pwa]: https://lobehub.com/docs/usage/features/pwa
+[docs-feat-t2i]: https://lobehub.com/docs/usage/features/text-to-image
+[docs-feat-theme]: https://lobehub.com/docs/usage/features/theme
+[docs-feat-tts]: https://lobehub.com/docs/usage/features/tts
+[docs-feat-vision]: https://lobehub.com/docs/usage/features/vision
 [docs-function-call]: https://lobehub.com/blog/openai-function-call
 [docs-plugin-dev]: https://lobehub.com/docs/usage/plugins/development
 [docs-self-hosting]: https://lobehub.com/docs/self-hosting/start
 [docs-upstream-sync]: https://lobehub.com/docs/self-hosting/advanced/upstream-sync
+[docs-usage-ollama]: https://lobehub.com/docs/usage/providers/ollama
+[docs-usage-plugin]: https://lobehub.com/docs/usage/plugins/basic
 [fossa-license-link]: https://app.fossa.com/projects/git%2Bgithub.com%2Flobehub%2Flobehub
 [fossa-license-shield]: https://app.fossa.com/api/projects/git%2Bgithub.com%2Flobehub%2Flobehub.svg?type=large
 [github-action-release-link]: https://github.com/actions/workflows/lobehub/lobehub/release.yml
@@ -507,7 +898,29 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [github-releasedate-shield]: https://img.shields.io/github/release-date/lobehub/lobehub?labelColor=black&style=flat-square
 [github-stars-link]: https://github.com/lobehub/lobehub/stargazers
 [github-stars-shield]: https://img.shields.io/github/stars/lobehub/lobehub?color=ffcb47&labelColor=black&style=flat-square
-[image-banner]: https://github.com/user-attachments/assets/5f78ae58-ed4f-4d38-8037-96109fbba58c
+[github-trending-shield]: https://trendshift.io/api/badge/repositories/2256
+[github-trending-url]: https://trendshift.io/repositories/2256
+[image-banner]: https://github.com/user-attachments/assets/0fe626a3-0ddc-4f67-b595-3c5b3f1701e0
+[image-feat-agent]: https://github.com/user-attachments/assets/b3ab6e35-4fbc-468d-af10-e3e0c687350f
+[image-feat-artifacts]: https://github.com/user-attachments/assets/7f95fad6-b210-4e6e-84a0-7f39e96f3a00
+[image-feat-auth]: https://github.com/user-attachments/assets/80bb232e-19d1-4f97-98d6-e291f3585e6d
+[image-feat-branch]: https://github.com/user-attachments/assets/92f72082-02bd-4835-9c54-b089aad7fd41
+[image-feat-cot]: https://github.com/user-attachments/assets/f74f1139-d115-4e9c-8c43-040a53797a5e
+[image-feat-database]: https://github.com/user-attachments/assets/f1697c8b-d1fb-4dac-ba05-153c6295d91d
+[image-feat-desktop]: https://github.com/user-attachments/assets/a7bac8d3-ea96-4000-bb39-fadc9b610f96
+[image-feat-knowledgebase]: https://github.com/user-attachments/assets/7da7a3b2-92fd-4630-9f4e-8560c74955ae
+[image-feat-local]: https://github.com/user-attachments/assets/1239da50-d832-4632-a7ef-bd754c0f3850
+[image-feat-mcp]: https://github.com/user-attachments/assets/1be85d36-3975-4413-931f-27e05e440995
+[image-feat-mcp-market]: https://github.com/user-attachments/assets/bb114f9f-24c5-4000-a984-c10d187da5a0
+[image-feat-mobile]: https://github.com/user-attachments/assets/32cf43c4-96bd-4a4c-bfb6-59acde6fe380
+[image-feat-plugin]: https://github.com/user-attachments/assets/66a891ac-01b6-4e3f-b978-2eb07b489b1b
+[image-feat-privoder]: https://github.com/user-attachments/assets/e553e407-42de-4919-977d-7dbfcf44a821
+[image-feat-pwa]: https://github.com/user-attachments/assets/9647f70f-b71b-43b6-9564-7cdd12d1c24d
+[image-feat-t2i]: https://github.com/user-attachments/assets/708274a7-2458-494b-a6ec-b73dfa1fa7c2
+[image-feat-theme]: https://github.com/user-attachments/assets/b47c39f1-806f-492b-8fcb-b0fa973937c1
+[image-feat-tts]: https://github.com/user-attachments/assets/50189597-2cc3-4002-b4c8-756a52ad5c0a
+[image-feat-vision]: https://github.com/user-attachments/assets/18574a1f-46c2-4cbc-af2c-35a86e128a07
+[image-feat-web-search]: https://github.com/user-attachments/assets/cfdc48ac-b5f8-4a00-acee-db8f2eba09ad
 [image-star]: https://github.com/user-attachments/assets/3216e25b-186f-4a54-9cb4-2f124aec0471
 [issues-link]: https://img.shields.io/github/issues/lobehub/lobehub.svg?style=flat
 [lobe-chat-plugins]: https://github.com/lobehub/lobe-chat-plugins
@@ -545,6 +958,8 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [share-whatsapp-shield]: https://img.shields.io/badge/-share%20on%20whatsapp-black?labelColor=black&logo=whatsapp&logoColor=white&style=flat-square
 [share-x-link]: https://x.com/intent/tweet?hashtags=chatbot%2CchatGPT%2CopenAI&text=Check%20this%20GitHub%20repository%20out%20%F0%9F%A4%AF%20LobeHub%20-%20An%20open-source%2C%20extensible%20%28Function%20Calling%29%2C%20high-performance%20chatbot%20framework.%20It%20supports%20one-click%20free%20deployment%20of%20your%20private%20ChatGPT%2FLLM%20web%20application.&url=https%3A%2F%2Fgithub.com%2Flobehub%2Flobehub
 [share-x-shield]: https://img.shields.io/badge/-share%20on%20x-black?labelColor=black&logo=x&logoColor=white&style=flat-square
+[sponsor-link]: https://opencollective.com/lobehub 'Become ❤️ LobeHub Sponsor'
+[sponsor-shield]: https://img.shields.io/badge/-Sponsor%20LobeHub-f04f88?logo=opencollective&logoColor=white&style=flat-square
 [submit-agents-link]: https://github.com/lobehub/lobe-chat-agents
 [submit-agents-shield]: https://img.shields.io/badge/🤖/🏪_submit_agent-%E2%86%92-c4f042?labelColor=black&style=for-the-badge
 [submit-plugin-link]: https://github.com/lobehub/lobe-chat-plugins
@@ -4,11 +4,8 @@

 # LobeHub

-LobeHub 帮你把专属 Agent 组织成 7×24 不打烊的高效队伍：
-
-自动为你招募适配的 AI 队友、调度任务排班、汇总生成工作报告，
-
-你始终掌控全局，从此不用再时刻在线盯守，真正解放自己的时间。
+LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您一起成长的 Agent 队友协作。<br/>
+在 LobeHub 中，我们将 **Agent 视为工作单元**，提供一个让人类与 Agent 共同进化的基础设施。

 [English](./README.md) · **简体中文** · [官网][official-site] · [更新日志][changelog] · [文档][docs] · [博客][blog] · [反馈问题][github-issues-link]

@@ -27,6 +24,7 @@ LobeHub 帮你把专属 Agent 组织成 7×24 不打烊的高效队伍：
 [![][github-stars-shield]][github-stars-link]
 [![][github-issues-shield]][github-issues-link]
 [![][github-license-shield]][github-license-link]<br>
+[![][sponsor-shield]][sponsor-link]

 **分享 LobeHub 给你的好友**

@@ -37,9 +35,9 @@ LobeHub 帮你把专属 Agent 组织成 7×24 不打烊的高效队伍：
 [![][share-weibo-shield]][share-weibo-link]
 [![][share-mastodon-shield]][share-mastodon-link]

-<sup>你的首席 Agent 运营官</sup>
+<sup>Agent teammates that grow with you</sup>

-<a href="https://www.producthunt.com/products/lobehub?embed=true&amp;utm_source=badge-top-post-badge&amp;utm_medium=badge&amp;utm_campaign=badge-lobehub-2" target="_blank" rel="noopener noreferrer"><img alt="LobeHub - Your Chief Agent Operator for multi-agent work | Product Hunt" width="250" height="54" src="https://api.producthunt.com/widgets/embed-image/v1/top-post-badge.svg?post_id=1147569&amp;theme=light&amp;period=daily&amp;t=1779247564355"></a> <a href="https://trendshift.io/repositories/19224" target="_blank"><img src="https://trendshift.io/api/badge/repositories/19224" alt="lobehub%2Flobehub | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+[![][github-trending-shield]][github-trending-url]
 [![][github-hello-shield]][github-hello-url]

 </div>
@@ -51,10 +49,30 @@ LobeHub 帮你把专属 Agent 组织成 7×24 不打烊的高效队伍：

 - [👋🏻 开始使用 & 交流](#-开始使用--交流)
 - [✨ 特性一览](#-特性一览)
-  - [运营：你制定策略，我们负责运行 Agent。](#运营你制定策略我们负责运行-agent)
  - [创建：以 Agent 为工作单元](#创建以-agent-为工作单元)
  - [协作：扩展新型协作网络](#协作扩展新型协作网络)
  - [进化：人类与 Agent 的共生进化](#进化人类与-agent-的共生进化)
+  - [MCP](#mcp)
+  - [发现、连接、扩展](#发现连接扩展)
+  - [巅峰性能，零干扰](#巅峰性能零干扰)
+  - [在线知识，按需获取](#在线知识按需获取)
+  - [思维链 (CoT)](#思维链-cot)
+  - [分支对话](#分支对话)
+  - [支持白板 (Artifacts)](#支持白板-artifacts)
+  - [文件上传 / 知识库](#文件上传--知识库)
+  - [多模型服务商支持](#多模型服务商支持)
+  - [支持本地大语言模型 (LLM)](#支持本地大语言模型-llm)
+  - [模型视觉识别 (Model Visual)](#模型视觉识别-model-visual)
+  - [TTS & STT 语音会话](#tts--stt-语音会话)
+  - [Text to Image 文生图](#text-to-image-文生图)
+  - [插件系统 (Tools Calling)](#插件系统-tools-calling)
+  - [助手市场 (GPTs)](#助手市场-gpts)
+  - [支持本地 / 远程数据库](#支持本地--远程数据库)
+  - [支持多用户管理](#支持多用户管理)
+  - [渐进式 Web 应用 (PWA)](#渐进式-web-应用-pwa)
+  - [移动设备适配](#移动设备适配)
+  - [自定义主题](#自定义主题)
+  - [`*` 更多特性](#-更多特性)
 - [🛳 开箱即用](#-开箱即用)
  - [`A` 使用 Vercel、Zeabur 、Sealos 或 阿里云计算巢 部署](#a-使用-vercelzeabur-sealos-或-阿里云计算巢-部署)
  - [`B` 使用 Docker 部署](#b-使用-docker-部署)
@@ -75,7 +93,7 @@ LobeHub 帮你把专属 Agent 组织成 7×24 不打烊的高效队伍：

 <br/>

-<https://github.com/user-attachments/assets/0a33365f-b786-48b5-9ed6-f8af7927bccb>
+<https://github.com/user-attachments/assets/6710ad97-03d0-4175-bd75-adff9b55eca2>

 ## 👋🏻 开始使用 & 交流

@@ -84,9 +102,9 @@ LobeHub 帮你把专属 Agent 组织成 7×24 不打烊的高效队伍：

 不论普通用户与专业开发者，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?launch=lobehub-2&embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-lobehub) | 我们已在 Product Hunt 上线！我们很高兴将 LobeHub 推向世界。如果您相信人类与 Agent 共同进化的未来，请支持我们的旅程。 |
-| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
-| [![][discord-shield-badge]][discord-link]                                                                                                                                                                                                                          | 加入我们的 Discord 社区！这是你可以与开发者和其他 LobeHub 热衷用户交流的地方                                         |
+| [![](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 共同进化的未来，请支持我们的旅程。 |
+| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------- |
+| [![][discord-shield-badge]][discord-link]                                                                                                                                                                                                         | 加入我们的 Discord 社区！这是你可以与开发者和其他 LobeHub 热衷用户交流的地方                                         |

 > \[!IMPORTANT]
 >
@@ -109,26 +127,7 @@ LobeHub 帮你把专属 Agent 组织成 7×24 不打烊的高效队伍：

 LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您一起成长的 Agent 队友协作。在 LobeHub 中，我们将 **Agent 视为工作单元**，提供一个让人类与 Agent 共同进化的基础设施。

-![](https://github.com/user-attachments/assets/89d1c402-a62b-4794-82ea-17e5ee1a6165)
-
-### 运营：你制定策略，我们负责运行 Agent。
-
-雇用、排程并汇报你整个 AI 团队的工作
-
- **更高生产力，更少工具**：将你所有的 Agent 集中在一个平台。
- **IM 网关**： Agent 连接到您每天使用的技能。
-
-![](https://github.com/user-attachments/assets/7b08d6d9-9dff-4b06-a919-324630554509)
-
-[![][back-to-top]](#readme-top)
-
-<div align="right">
-
-[![][back-to-top]](#readme-top)
-
-</div>
-
-![](https://github.com/user-attachments/assets/81e89324-fc66-4024-99a3-aa8e16ec8184)
+![](https://hub-apac-1.lobeobjects.space/blog/assets/2204cde2228fb3f583f3f2c090bc49fb.webp)

 ### 创建：以 Agent 为工作单元

@@ -137,8 +136,6 @@ LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您
 - **统一智能**：无缝访问任何模型与任何模态 —— 全部由您掌控。
 - **1 万 + 技能**：通过超过 10,000 个工具和与 MCP 兼容的插件，将 Agent 连接到您每天使用的技能。

-![](https://github.com/user-attachments/assets/949b8166-486d-4750-ad7a-cfe7bfcb84e3)
-
 [![][back-to-top]](#readme-top)

 <div align="right">
@@ -158,8 +155,6 @@ LobeHub 引入了 **Agent Groups**，让您可以像对待真实队友一样与
 - **项目（Project）**：按项目组织工作，保持一切结构化且易于跟踪。
 - **工作区（Workspace）**：供团队与 Agent 协作的共享空间，确保明确的所有权和组织内的可见性。

-![](https://github.com/user-attachments/assets/e51526c6-e09c-4a5a-9cec-dcd3fd68a3a8)
-
 [![][back-to-top]](#readme-top)

 <div align="right">
@@ -177,7 +172,105 @@ LobeHub 引入了 **Agent Groups**，让您可以像对待真实队友一样与
 - **持续学习**：您的 Agent 会从您的工作方式中学习，调整其行为以在恰当时刻采取行动。
 - **白盒记忆**：我们相信透明性。您的 Agent 使用结构化、可编辑的记忆，让您完全掌控它们记住的内容。

-![](https://github.com/user-attachments/assets/5c6e16f0-7f47-4baf-9aeb-3a00deb8ff5b)
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+<details>
+<summary>更多特性</summary>
+
+[![](https://github.com/user-attachments/assets/1be85d36-3975-4413-931f-27e05e440995)](https://lobehub.com/mcp)
+
+### MCP
+
+通过启用与外部工具、数据源和服务的平滑、安全和动态交互，释放你的 AI 的全部潜力。基于 MCP（模型上下文协议）的插件系统打破了 AI 与数字生态系统之间的壁垒，实现了前所未有的连接性和功能性。
+
+将对话转化为强大的工作流程，连接数据库、API、文件系统等。体验真正理解并与你的世界互动的 AI Agent。
+
+[![][back-to-top]](#readme-top)
+
+![][image-feat-mcp-market]
+
+### 发现、连接、扩展
+
+浏览不断增长的 MCP 插件库，轻松扩展你的 AI 能力并简化工作流程。访问 [lobehub.com/mcp](https://lobehub.com/mcp) 探索 MCP 市场，提供精选的集成集合，增强你的 AI 与各种工具和服务协作的能力。
+
+从生产力工具到开发环境，发现扩展 AI 覆盖范围和效率的新方式。与社区连接，找到满足特定需求的完美插件。
+
+[![][back-to-top]](#readme-top)
+
+![][image-feat-desktop]
+
+### 巅峰性能，零干扰
+
+获得完整的 LobeHub 体验，摆脱浏览器限制 —— 轻量级、专注且随时就绪。我们的桌面应用程序为你的 AI 交互提供专用环境，确保最佳性能和最小干扰。
+
+体验更快的响应时间、更好的资源管理和与 AI 助手的更稳定连接。桌面应用专为要求 AI 工具最佳性能的用户设计。
+
+[![][back-to-top]](#readme-top)
+
+![][image-feat-web-search]
+
+### 在线知识，按需获取
+
+通过实时联网访问，你的 AI 与世界保持同步 —— 新闻、数据、趋势等。保持信息更新，获取最新可用信息，使你的 AI 能够提供准确和最新的回复。
+
+访问实时信息，验证事实，探索当前事件，无需离开对话。你的 AI 成为通向世界知识的门户，始终保持最新和全面。
+
+[![][back-to-top]](#readme-top)
+
+[![][image-feat-cot]][docs-feat-cot]
+
+### [思维链 (CoT)][docs-feat-cot]
+
+体验前所未有的 AI 推理过程。通过创新的思维链（CoT）可视化功能，您可以实时观察复杂问题是如何一步步被解析的。这项突破性的功能为 AI 的决策过程提供了前所未有的透明度，让您能够清晰地了解结论是如何得出的。
+
+通过将复杂的推理过程分解为清晰的逻辑步骤，您可以更好地理解和验证 AI 的解题思路。无论您是在调试问题、学习知识，还是单纯对 AI 推理感兴趣，思维链可视化都能将抽象思维转化为一种引人入胜的互动体验。
+
+[![][back-to-top]](#readme-top)
+
+[![][image-feat-branch]][docs-feat-branch]
+
+### [分支对话][docs-feat-branch]
+
+为您带来更自然、更灵活的 AI 对话方式。通过分支对话功能，您的讨论可以像人类对话一样自然延伸。在任意消息处创建新的对话分支，让您在保留原有上下文的同时，自由探索不同的对话方向。
+
+两种强大模式任您选择：
+
+- **延续模式**：无缝延展当前讨论，保持宝贵的对话上下文
+- **独立模式**：基于任意历史消息，开启全新话题探讨
+
+这项突破性功能将线性对话转变为动态的树状结构，让您能够更深入地探索想法，实现更高效的互动体验。
+
+[![][back-to-top]](#readme-top)
+
+[![][image-feat-artifacts]][docs-feat-artifacts]
+
+### [支持白板 (Artifacts)][docs-feat-artifacts]
+
+体验集成于 LobeHub 的 Claude Artifacts 能力。这项革命性功能突破了 AI 人机交互的边界，让您能够实时创建和可视化各种格式的内容。
+
+以前所未有的灵活度进行创作与可视化：
+
+- 生成并展示动态 SVG 图形
+- 实时构建与渲染交互式 HTML 页面
+- 输出多种格式的专业文档
+
+[![][back-to-top]](#readme-top)
+
+[![][image-feat-knowledgebase]][docs-feat-knowledgebase]
+
+### [文件上传 / 知识库][docs-feat-knowledgebase]
+
+LobeHub 支持文件上传与知识库功能，你可以上传文件、图片、音频、视频等多种类型的文件，以及创建知识库，方便用户管理和查找文件。同时在对话中使用文件和知识库功能，实现更加丰富的对话体验。
+
+<https://github.com/user-attachments/assets/faa8cf67-e743-4590-8bf6-ebf6ccc34175>
+
+> \[!TIP]
+>
+> 查阅 [📘 LobeHub 知识库上线 —— 此刻起，跬步千里](https://lobehub.com/zh/blog/knowledge-base) 了解详情。

 <div align="right">

@@ -185,6 +278,262 @@ LobeHub 引入了 **Agent Groups**，让您可以像对待真实队友一样与

 </div>

+[![][image-feat-privoder]][docs-feat-provider]
+
+### [多模型服务商支持][docs-feat-provider]
+
+在 LobeHub 的不断发展过程中，我们深刻理解到在提供 AI 会话服务时模型服务商的多样性对于满足社区需求的重要性。因此，我们不再局限于单一的模型服务商，而是拓展了对多种模型服务商的支持，以便为用户提供更为丰富和多样化的会话选择。
+
+通过这种方式，LobeHub 能够更灵活地适应不同用户的需求，同时也为开发者提供了更为广泛的选择空间。
+
+#### 已支持的模型服务商
+
+我们已经实现了对以下模型服务商的支持：
+
+<!-- PROVIDER LIST -->
+
+<details><summary><kbd>See more providers (+-10)</kbd></summary>
+
+</details>
+
+> 📊 Total providers: [<kbd>**0**</kbd>](https://lobechat.com/discover/providers)
+
+ <!-- PROVIDER LIST -->
+
+同时，我们也在计划支持更多的模型服务商，以进一步丰富我们的服务商库。如果你希望让 LobeHub 支持你喜爱的服务商，欢迎加入我们的 [💬 社区讨论](https://github.com/lobehub/lobehub/discussions/6157)。
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-local]][docs-feat-local]
+
+### [支持本地大语言模型 (LLM)][docs-feat-local]
+
+为了满足特定用户的需求，LobeHub 还基于 [Ollama](https://ollama.ai) 支持了本地模型的使用，让用户能够更灵活地使用自己的或第三方的模型。
+
+> \[!TIP]
+>
+> 查阅 [📘 在 LobeHub 中使用 Ollama][docs-usage-ollama] 获得更多信息
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-vision]][docs-feat-vision]
+
+### [模型视觉识别 (Model Visual)][docs-feat-vision]
+
+LobeHub 已经支持 OpenAI 最新的 [`gpt-4-vision`](https://platform.openai.com/docs/guides/vision) 支持视觉识别的模型，这是一个具备视觉识别能力的多模态应用。
+用户可以轻松上传图片或者拖拽图片到对话框中，助手将能够识别图片内容，并在此基础上进行智能对话，构建更智能、更多元化的聊天场景。
+
+这一特性打开了新的互动方式，使得交流不再局限于文字，而是可以涵盖丰富的视觉元素。无论是日常使用中的图片分享，还是在特定行业内的图像解读，助手都能提供出色的对话体验。
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-tts]][docs-feat-tts]
+
+### [TTS & STT 语音会话][docs-feat-tts]
+
+LobeHub 支持文字转语音（Text-to-Speech，TTS）和语音转文字（Speech-to-Text，STT）技术，这使得我们的应用能够将文本信息转化为清晰的语音输出，用户可以像与真人交谈一样与我们的对话助手进行交流。
+用户可以从多种声音中选择，给助手搭配合适的音源。 同时，对于那些倾向于听觉学习或者想要在忙碌中获取信息的用户来说，TTS 提供了一个极佳的解决方案。
+
+在 LobeHub 中，我们精心挑选了一系列高品质的声音选项 (OpenAI Audio, Microsoft Edge Speech)，以满足不同地域和文化背景用户的需求。用户可以根据个人喜好或者特定场景来选择合适的语音，从而获得个性化的交流体验。
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-t2i]][docs-feat-t2i]
+
+### [Text to Image 文生图][docs-feat-t2i]
+
+支持最新的文本到图片生成技术，LobeHub 现在能够让用户在与助手对话中直接调用文生图工具进行创作。
+通过利用 [`DALL-E 3`](https://openai.com/dall-e-3)、[`MidJourney`](https://www.midjourney.com/) 和 [`Pollinations`](https://pollinations.ai/) 等 AI 工具的能力， 助手们现在可以将你的想法转化为图像。
+同时可以更私密和沉浸式地完成你的创作过程。
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-plugin]][docs-feat-plugin]
+
+### [插件系统 (Tools Calling)][docs-feat-plugin]
+
+LobeHub 的插件生态系统是其核心功能的重要扩展，它极大地增强了 ChatGPT 的实用性和灵活性。
+
+<video controls src="https://github.com/lobehub/lobehub/assets/28616219/f29475a3-f346-4196-a435-41a6373ab9e2" muted="false"></video>
+
+通过利用插件，ChatGPT 能够实现实时信息的获取和处理，例如自动获取最新新闻头条，为用户提供即时且相关的资讯。
+
+此外，这些插件不仅局限于新闻聚合，还可以扩展到其他实用的功能，如快速检索文档、生成图象、获取电商平台数据，以及其他各式各样的第三方服务。
+
+> 通过文档了解更多 [📘 插件使用][docs-usage-plugin]
+
+<!-- PLUGIN LIST -->
+
+| 最近新增                                                                                                             | 描述                                                                                                               |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| [购物工具](https://lobechat.com/discover/plugin/ShoppingTools)<br/><sup>By **shoppingtools** on **2026-01-12**</sup> | 在 eBay 和 AliExpress 上搜索产品，查找 eBay 活动和优惠券。获取快速示例。<br/>`购物` `e-bay` `ali-express` `优惠券` |
+| [SEO 助手](https://lobechat.com/discover/plugin/seo_assistant)<br/><sup>By **webfx** on **2026-01-12**</sup>         | SEO 助手可以生成搜索引擎关键词信息，以帮助创建内容。<br/>`seo` `关键词`                                            |
+| [视频字幕](https://lobechat.com/discover/plugin/VideoCaptions)<br/><sup>By **maila** on **2025-12-13**</sup>         | 将 Youtube 链接转换为转录文本，使其能够提问，创建章节，并总结其内容。<br/>`视频转文字` `you-tube`                  |
+| [天气 GPT](https://lobechat.com/discover/plugin/WeatherGPT)<br/><sup>By **steven-tey** on **2025-12-13**</sup>       | 获取特定位置的当前天气信息。<br/>`天气`                                                                            |
+
+> 📊 Total plugins: [<kbd>**40**</kbd>](https://lobechat.com/discover/plugins)
+
+ <!-- PLUGIN LIST -->
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-agent]][docs-feat-agent]
+
+### [助手市场 (GPTs)][docs-feat-agent]
+
+在 LobeHub 的助手市场中，创作者们可以发现一个充满活力和创新的社区，它汇聚了众多精心设计的助手，这些助手不仅在工作场景中发挥着重要作用，也在学习过程中提供了极大的便利。
+我们的市场不仅是一个展示平台，更是一个协作的空间。在这里，每个人都可以贡献自己的智慧，分享个人开发的助手。
+
+> \[!TIP]
+>
+> 通过 [🤖/🏪 提交助手][submit-agents-link] ，你可以轻松地将你的助手作品提交到我们的平台。我们特别强调的是，LobeHub 建立了一套精密的自动化国际化（i18n）工作流程， 它的强大之处在于能够无缝地将你的助手转化为多种语言版本。
+> 这意味着，不论你的用户使用何种语言，他们都能无障碍地体验到你的助手。
+
+> \[!IMPORTANT]
+>
+> 我欢迎所有用户加入这个不断成长的生态系统，共同参与到助手的迭代与优化中来。共同创造出更多有趣、实用且具有创新性的助手，进一步丰富助手的多样性和实用性。
+
+<!-- AGENT LIST -->
+
+| 最近新增                                                                                                                                                         | 描述                                                                                                              |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| [海龟汤主持人](https://lobechat.com/discover/assistant/lateral-thinking-puzzle)<br/><sup>By **[CSY2022](https://github.com/CSY2022)** on **2025-06-19**</sup>    | 一个海龟汤主持人，需要自己提供汤面，汤底与关键点（猜中的判定条件）。<br/>`海龟汤` `推理` `互动` `谜题` `角色扮演` |
+| [学术写作助手](https://lobechat.com/discover/assistant/academic-writing-assistant)<br/><sup>By **[swarfte](https://github.com/swarfte)** on **2025-06-17**</sup> | 专业的学术研究论文写作和正式文档编写专家<br/>`学术写作` `研究` `正式风格`                                         |
+| [美食评论员🍟](https://lobechat.com/discover/assistant/food-reviewer)<br/><sup>By **[renhai-lab](https://github.com/renhai-lab)** on **2025-06-17**</sup>        | 美食评价专家<br/>`美食` `评价` `写作`                                                                             |
+| [Minecraft 资深开发者](https://lobechat.com/discover/assistant/java-development)<br/><sup>By **[iamyuuk](https://github.com/iamyuuk)** on **2025-06-17**</sup>   | 擅长高级 Java 开发及 Minecraft 开发<br/>`开发` `编程` `minecraft` `java`                                          |
+
+> 📊 Total agents: [<kbd>**505**</kbd> ](https://lobechat.com/discover/assistants)
+
+ <!-- AGENT LIST -->
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-database]][docs-feat-database]
+
+### [支持本地 / 远程数据库][docs-feat-database]
+
+LobeHub 支持同时使用服务端数据库和本地数据库。根据您的需求，您可以选择合适的部署方案：
+
+- 本地数据库：适合希望对数据有更多掌控感和隐私保护的用户。LobeHub 采用了 CRDT (Conflict-Free Replicated Data Type) 技术，实现了多端同步功能。这是一项实验性功能，旨在提供无缝的数据同步体验。
+- 服务端数据库：适合希望更便捷使用体验的用户。LobeHub 支持 PostgreSQL 作为服务端数据库。关于如何配置服务端数据库的详细文档，请前往 [配置服务端数据库](https://lobehub.com/zh/docs/self-hosting/advanced/server-database)。
+
+无论您选择哪种数据库，LobeHub 都能为您提供卓越的用户体验。
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-auth]][docs-feat-auth]
+
+### [支持多用户管理][docs-feat-auth]
+
+LobeHub 支持多用户管理，提供了灵活的用户认证方案：
+
+- **Better Auth**：LobeHub 集成了 `Better Auth`，一个现代化且灵活的身份验证库，支持多种身份验证方式，包括 OAuth、邮件登录、凭证登录、魔法链接等。通过 `Better Auth`，您可以轻松实现用户的注册、登录、会话管理、社交登录、多因素认证 (MFA) 等功能，确保用户数据的安全性和隐私性。
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-pwa]][docs-feat-pwa]
+
+### [渐进式 Web 应用 (PWA)][docs-feat-pwa]
+
+我们深知在当今多设备环境下为用户提供无缝体验的重要性。为此，我们采用了渐进式 Web 应用 [PWA](https://support.google.com/chrome/answer/9658361) 技术，
+这是一种能够将网页应用提升至接近原生应用体验的现代 Web 技术。通过 PWA，LobeHub 能够在桌面和移动设备上提供高度优化的用户体验，同时保持轻量级和高性能的特点。
+在视觉和感觉上，我们也经过精心设计，以确保它的界面与原生应用无差别，提供流畅的动画、响应式布局和适配不同设备的屏幕分辨率。
+
+> \[!NOTE]
+>
+> 若您未熟悉 PWA 的安装过程，您可以按照以下步骤将 LobeHub 添加为您的桌面应用（也适用于移动设备）：
+>
+> - 在电脑上运行 Chrome 或 Edge 浏览器 .
+> - 访问 LobeHub 网页 .
+> - 在地址栏的右上角，单击 <kbd>安装</kbd> 图标 .
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-mobile]][docs-feat-mobile]
+
+### [移动设备适配][docs-feat-mobile]
+
+针对移动设备进行了一系列的优化设计，以提升用户的移动体验。目前，我们正在对移动端的用户体验进行版本迭代，以实现更加流畅和直观的交互。如果您有任何建议或想法，我们非常欢迎您通过 GitHub Issues 或者 Pull Requests 提供反馈。
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+[![][image-feat-theme]][docs-feat-theme]
+
+### [自定义主题][docs-feat-theme]
+
+作为设计工程师出身，LobeHub 在界面设计上充分考虑用户的个性化体验，因此引入了灵活多变的主题模式，其中包括日间的亮色模式和夜间的深色模式。
+除了主题模式的切换，还提供了一系列的颜色定制选项，允许用户根据自己的喜好来调整应用的主题色彩。无论是想要沉稳的深蓝，还是希望活泼的桃粉，或者是专业的灰白，用户都能够在 LobeHub 中找到匹配自己风格的颜色选择。
+
+> \[!TIP]
+>
+> 默认配置能够智能地识别用户系统的颜色模式，自动进行主题切换，以确保应用界面与操作系统保持一致的视觉体验。对于喜欢手动调控细节的用户，LobeHub 同样提供了直观的设置选项，针对聊天场景也提供了对话气泡模式和文档模式的选择。
+
+<div align="right">
+
+<div align="right">
+
+[![][back-to-top]](#readme-top)
+
+</div>
+
+</div>
+
+### `*` 更多特性
+
+除了上述功能特性以外，LobeHub 所具有的设计和技术能力将为你带来更多使用保障：
+
+- [x] 💎 **精致 UI 设计**：经过精心设计的界面，具有优雅的外观和流畅的交互效果，支持亮暗色主题，适配移动端。支持 PWA，提供更加接近原生应用的体验。
+- [x] 🗣️ **流畅的对话体验**：流式响应带来流畅的对话体验，并且支持完整的 Markdown 渲染，包括代码高亮、LaTex 公式、Mermaid 流程图等。
+- [x] 💨 **快速部署**：使用 Vercel 平台或者我们的 Docker 镜像，只需点击一键部署按钮，即可在 1 分钟内完成部署，无需复杂的配置过程。
+- [x] 🔒 **隐私安全**：所有数据保存在用户浏览器本地，保证用户的隐私安全。
+- [x] 🌐 **自定义域名**：如果用户拥有自己的域名，可以将其绑定到平台上，方便在任何地方快速访问对话助手。
+
+</details>
+
 > ✨ 随着产品迭代持续更新，我们将会带来更多更多令人激动的功能！

 <div align="right">
@@ -518,10 +867,28 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [docs-dev-guide]: https://lobehub.com/docs/development/start
 [docs-docker]: https://lobehub.com/zh/docs/self-hosting/server-database/docker-compose
 [docs-env-var]: https://lobehub.com/docs/self-hosting/environment-variables
+[docs-feat-agent]: https://lobehub.com/docs/usage/features/agent-market
+[docs-feat-artifacts]: https://lobehub.com/docs/usage/features/artifacts
+[docs-feat-auth]: https://lobehub.com/docs/usage/features/auth
+[docs-feat-branch]: https://lobehub.com/docs/usage/features/branching-conversations
+[docs-feat-cot]: https://lobehub.com/docs/usage/features/cot
+[docs-feat-database]: https://lobehub.com/docs/usage/features/database
+[docs-feat-knowledgebase]: https://lobehub.com/blog/knowledge-base
+[docs-feat-local]: https://lobehub.com/docs/usage/features/local-llm
+[docs-feat-mobile]: https://lobehub.com/docs/usage/features/mobile
+[docs-feat-plugin]: https://lobehub.com/docs/usage/features/plugin-system
+[docs-feat-provider]: https://lobehub.com/docs/usage/features/multi-ai-providers
+[docs-feat-pwa]: https://lobehub.com/docs/usage/features/pwa
+[docs-feat-t2i]: https://lobehub.com/docs/usage/features/text-to-image
+[docs-feat-theme]: https://lobehub.com/docs/usage/features/theme
+[docs-feat-tts]: https://lobehub.com/docs/usage/features/tts
+[docs-feat-vision]: https://lobehub.com/docs/usage/features/vision
 [docs-function-call]: https://lobehub.com/zh/blog/openai-function-call
 [docs-plugin-dev]: https://lobehub.com/docs/usage/plugins/development
 [docs-self-hosting]: https://lobehub.com/docs/self-hosting/start
 [docs-upstream-sync]: https://lobehub.com/docs/self-hosting/advanced/upstream-sync
+[docs-usage-ollama]: https://lobehub.com/docs/usage/providers/ollama
+[docs-usage-plugin]: https://lobehub.com/docs/usage/plugins/basic
 [fossa-license-link]: https://app.fossa.com/projects/git%2Bgithub.com%2Flobehub%2Flobehub
 [fossa-license-shield]: https://app.fossa.com/api/projects/git%2Bgithub.com%2Flobehub%2Flobehub.svg?type=large
 [github-action-release-link]: https://github.com/lobehub/lobehub/actions/workflows/release.yml
@@ -544,8 +911,29 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [github-releasedate-link]: https://github.com/lobehub/lobehub/releases
 [github-releasedate-shield]: https://img.shields.io/github/release-date/lobehub/lobehub?labelColor=black&style=flat-square
 [github-stars-link]: https://github.com/lobehub/lobehub/stargazers
-[github-stars-shield]: https://img.shields.io/github/stars/lobehub/lobehub?color=ffcb47&labelColor=black&style=flat-square
-[image-banner]: https://github.com/user-attachments/assets/5f78ae58-ed4f-4d38-8037-96109fbba58c
+[github-stars-shield]: https://github.com/user-attachments/assets/3216e25b-186f-4a54-9cb4-2f124aec0471
+[github-trending-shield]: https://trendshift.io/api/badge/repositories/2256
+[github-trending-url]: https://trendshift.io/repositories/2256
+[image-banner]: https://github.com/user-attachments/assets/0fe626a3-0ddc-4f67-b595-3c5b3f1701e0
+[image-feat-agent]: https://github.com/user-attachments/assets/b3ab6e35-4fbc-468d-af10-e3e0c687350f
+[image-feat-artifacts]: https://github.com/user-attachments/assets/7f95fad6-b210-4e6e-84a0-7f39e96f3a00
+[image-feat-auth]: https://github.com/user-attachments/assets/80bb232e-19d1-4f97-98d6-e291f3585e6d
+[image-feat-branch]: https://github.com/user-attachments/assets/92f72082-02bd-4835-9c54-b089aad7fd41
+[image-feat-cot]: https://github.com/user-attachments/assets/f74f1139-d115-4e9c-8c43-040a53797a5e
+[image-feat-database]: https://github.com/user-attachments/assets/f1697c8b-d1fb-4dac-ba05-153c6295d91d
+[image-feat-desktop]: https://github.com/user-attachments/assets/a7bac8d3-ea96-4000-bb39-fadc9b610f96
+[image-feat-knowledgebase]: https://github.com/user-attachments/assets/7da7a3b2-92fd-4630-9f4e-8560c74955ae
+[image-feat-local]: https://github.com/user-attachments/assets/1239da50-d832-4632-a7ef-bd754c0f3850
+[image-feat-mcp-market]: https://github.com/user-attachments/assets/bb114f9f-24c5-4000-a984-c10d187da5a0
+[image-feat-mobile]: https://github.com/user-attachments/assets/32cf43c4-96bd-4a4c-bfb6-59acde6fe380
+[image-feat-plugin]: https://github.com/user-attachments/assets/66a891ac-01b6-4e3f-b978-2eb07b489b1b
+[image-feat-privoder]: https://github.com/user-attachments/assets/e553e407-42de-4919-977d-7dbfcf44a821
+[image-feat-pwa]: https://github.com/user-attachments/assets/9647f70f-b71b-43b6-9564-7cdd12d1c24d
+[image-feat-t2i]: https://github.com/user-attachments/assets/708274a7-2458-494b-a6ec-b73dfa1fa7c2
+[image-feat-theme]: https://github.com/user-attachments/assets/b47c39f1-806f-492b-8fcb-b0fa973937c1
+[image-feat-tts]: https://github.com/user-attachments/assets/50189597-2cc3-4002-b4c8-756a52ad5c0a
+[image-feat-vision]: https://github.com/user-attachments/assets/18574a1f-46c2-4cbc-af2c-35a86e128a07
+[image-feat-web-search]: https://github.com/user-attachments/assets/cfdc48ac-b5f8-4a00-acee-db8f2eba09ad
 [image-star]: https://github.com/user-attachments/assets/c3b482e7-cef5-4e94-bef9-226900ecfaab
 [issues-link]: https://img.shields.io/github/issues/lobehub/lobehub.svg?style=flat
 [lobe-chat-plugins]: https://github.com/lobehub/lobe-chat-plugins
@@ -581,6 +969,8 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [share-whatsapp-shield]: https://img.shields.io/badge/-share%20on%20whatsapp-black?labelColor=black&logo=whatsapp&logoColor=white&style=flat-square
 [share-x-link]: https://x.com/intent/tweet?hashtags=chatbot%2CchatGPT%2CopenAI&text=%E6%8E%A8%E8%8D%90%E4%B8%80%E4%B8%AA%20GitHub%20%E5%BC%80%E6%BA%90%E9%A1%B9%E7%9B%AE%20%F0%9F%A4%AF%20LobeHub%20-%20%E5%BC%80%E6%BA%90%E7%9A%84%E3%80%81%E5%8F%AF%E6%89%A9%E5%B1%95%E7%9A%84%EF%BC%88Function%20Calling%EF%BC%89%E9%AB%98%E6%80%A7%E8%83%BD%E8%81%8A%E5%A4%A9%E6%9C%BA%E5%99%A8%E4%BA%BA%E6%A1%86%E6%9E%B6%E3%80%82%0A%E5%AE%83%E6%94%AF%E6%8C%81%E4%B8%80%E9%94%AE%E5%85%8D%E8%B4%B9%E9%83%A8%E7%BD%B2%E7%A7%81%E4%BA%BA%20ChatGPT%2FLLM%20%E7%BD%91%E9%A1%B5%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F&url=https%3A%2F%2Fgithub.com%2Flobehub%2Flobehub
 [share-x-shield]: https://img.shields.io/badge/-share%20on%20x-black?labelColor=black&logo=x&logoColor=white&style=flat-square
+[sponsor-link]: https://opencollective.com/lobehub 'Become ❤ LobeHub Sponsor'
+[sponsor-shield]: https://img.shields.io/badge/-Sponsor%20LobeHub-f04f88?logo=opencollective&logoColor=white&style=flat-square
 [submit-agents-link]: https://github.com/lobehub/lobe-chat-agents
 [submit-agents-shield]: https://img.shields.io/badge/🤖/🏪_submit_agent-%E2%86%92-c4f042?labelColor=black&style=for-the-badge
 [submit-plugin-link]: https://github.com/lobehub/lobe-chat-plugins
@@ -1,6 +1,6 @@
 .\" Code generated by `npm run man:generate`; DO NOT EDIT.
 .\" Manual command details come from the Commander command tree.
-.TH LH 1 "" "@lobehub/cli 0.0.20" "User Commands"
+.TH LH 1 "" "@lobehub/cli 0.0.15" "User Commands"
 .SH NAME
 lh \- LobeHub CLI \- manage and connect to LobeHub services
 .SH SYNOPSIS
@@ -1,6 +1,6 @@
 {
  "name": "@lobehub/cli",
-  "version": "0.0.20",
+  "version": "0.0.15",
  "type": "module",
  "bin": {
    "lh": "./dist/index.js",
@@ -6,7 +6,6 @@ import { getTrpcClient } from '../api/client';
 import { confirm, outputJson, printBoxTable, printTable, timeAgo } from '../utils/format';
 import { log } from '../utils/logger';
 import { registerBotMessageCommands } from './botMessage';
-import { registerBotMessengersCommands } from './botMessengers';

 // ── Access policy helpers ──────────────────────────────

@@ -476,9 +475,6 @@ export function registerBotCommand(program: Command) {
  // Register message subcommand group
  registerBotMessageCommands(bot);

-  // Register messengers subcommand group (System Bot installations + account links)
-  registerBotMessengersCommands(bot);
-
  // ── platforms ───────────────────────────────────────────

  bot
@@ -810,7 +806,7 @@ export function registerBotCommand(program: Command) {
    name: 'group-allowlist',
  });

-  // ── watch-keywords () ────────────────────────
+  // ── watch-keywords (LOBE-8891) ────────────────────────

  registerWatchKeywordsCommand(bot);

@@ -1,417 +0,0 @@
-import { mkdtemp, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
-import path from 'node:path';
-
-import { Command } from 'commander';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { registerBotMessageCommands } from './botMessage';
-
-const { mockTrpcClient } = vi.hoisted(() => ({
-  mockTrpcClient: {
-    botMessage: {
-      replyToThread: { mutate: vi.fn() },
-      sendDirectMessage: { mutate: vi.fn() },
-      sendMessage: { mutate: vi.fn() },
-    },
-  },
-}));
-
-const { getTrpcClient: mockGetTrpcClient } = vi.hoisted(() => ({
-  getTrpcClient: vi.fn(),
-}));
-
-vi.mock('../api/client', () => ({ getTrpcClient: mockGetTrpcClient }));
-vi.mock('../utils/logger', () => ({
-  log: { debug: vi.fn(), error: vi.fn(), info: vi.fn(), warn: vi.fn() },
-  setVerbose: vi.fn(),
-}));
-
-describe('bot message send --attachment', () => {
-  let exitSpy: ReturnType<typeof vi.spyOn>;
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
-    mockTrpcClient.botMessage.sendMessage.mutate.mockReset();
-    mockTrpcClient.botMessage.sendMessage.mutate.mockResolvedValue({ messageId: 'm-1' });
-    mockTrpcClient.botMessage.sendDirectMessage.mutate.mockReset();
-    mockTrpcClient.botMessage.sendDirectMessage.mutate.mockResolvedValue({
-      channelId: 'dm-1',
-      messageId: 'm-dm-1',
-    });
-    mockTrpcClient.botMessage.replyToThread.mutate.mockReset();
-    mockTrpcClient.botMessage.replyToThread.mutate.mockResolvedValue({ messageId: 'm-tr-1' });
-  });
-
-  afterEach(() => {
-    exitSpy.mockRestore();
-    consoleSpy.mockRestore();
-  });
-
-  function createProgram() {
-    const program = new Command();
-    program.exitOverride();
-    const bot = program.command('bot');
-    registerBotMessageCommands(bot);
-    return program;
-  }
-
-  it('passes a remote URL through as fetchUrl', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'send',
-      'bot-1',
-      '--target',
-      'ch-1',
-      '--message',
-      'hi',
-      '--attachment',
-      'https://cdn.example.com/foo.png',
-    ]);
-
-    expect(mockTrpcClient.botMessage.sendMessage.mutate).toHaveBeenCalledWith(
-      expect.objectContaining({
-        attachments: [
-          expect.objectContaining({
-            fetchUrl: 'https://cdn.example.com/foo.png',
-            mimeType: 'image/png',
-            name: 'foo.png',
-            type: 'image',
-          }),
-        ],
-        botId: 'bot-1',
-        channelId: 'ch-1',
-        content: 'hi',
-      }),
-    );
-  });
-
-  it('base64-encodes a local file path', async () => {
-    const dir = await mkdtemp(path.join(tmpdir(), 'lh-cli-attach-'));
-    const filePath = path.join(dir, 'tiny.txt');
-    await writeFile(filePath, 'hello');
-
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'send',
-      'bot-1',
-      '--target',
-      'ch-1',
-      '--message',
-      'm',
-      '--attachment',
-      filePath,
-    ]);
-
-    const call = mockTrpcClient.botMessage.sendMessage.mutate.mock.calls[0][0];
-    expect(call.attachments).toHaveLength(1);
-    expect(call.attachments[0]).toMatchObject({
-      mimeType: 'text/plain',
-      name: 'tiny.txt',
-      type: 'file',
-    });
-    expect(call.attachments[0].data).toBe(Buffer.from('hello').toString('base64'));
-    expect(call.attachments[0].fetchUrl).toBeUndefined();
-  });
-
-  it('accepts multiple --attachment flags', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'send',
-      'bot-1',
-      '--target',
-      'ch-1',
-      '--message',
-      'm',
-      '--attachment',
-      'https://cdn.example.com/a.png',
-      '--attachment',
-      'https://cdn.example.com/b.pdf',
-    ]);
-
-    const call = mockTrpcClient.botMessage.sendMessage.mutate.mock.calls[0][0];
-    expect(call.attachments).toHaveLength(2);
-    expect(call.attachments[0]).toMatchObject({ type: 'image', name: 'a.png' });
-    expect(call.attachments[1]).toMatchObject({ type: 'file', name: 'b.pdf' });
-  });
-
-  it('omits attachments field when no flag is given', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'send',
-      'bot-1',
-      '--target',
-      'ch-1',
-      '--message',
-      'm',
-    ]);
-
-    const call = mockTrpcClient.botMessage.sendMessage.mutate.mock.calls[0][0];
-    expect(call.attachments).toBeUndefined();
-  });
-});
-
-describe('bot message dm --attachment', () => {
-  let exitSpy: ReturnType<typeof vi.spyOn>;
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
-    mockTrpcClient.botMessage.sendDirectMessage.mutate.mockReset();
-    mockTrpcClient.botMessage.sendDirectMessage.mutate.mockResolvedValue({
-      channelId: 'dm-1',
-      messageId: 'm-dm-1',
-    });
-  });
-
-  afterEach(() => {
-    exitSpy.mockRestore();
-    consoleSpy.mockRestore();
-  });
-
-  function createProgram() {
-    const program = new Command();
-    program.exitOverride();
-    const bot = program.command('bot');
-    registerBotMessageCommands(bot);
-    return program;
-  }
-
-  it('sends a DM with a remote-URL attachment', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'dm',
-      'bot-1',
-      '--user-id',
-      'u-1',
-      '--message',
-      'hi',
-      '--attachment',
-      'https://cdn.example.com/foo.png',
-    ]);
-
-    expect(mockTrpcClient.botMessage.sendDirectMessage.mutate).toHaveBeenCalledWith(
-      expect.objectContaining({
-        attachments: [
-          expect.objectContaining({
-            fetchUrl: 'https://cdn.example.com/foo.png',
-            type: 'image',
-          }),
-        ],
-        botId: 'bot-1',
-        content: 'hi',
-        userId: 'u-1',
-      }),
-    );
-  });
-
-  it('omits attachments when no flag is given', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'dm',
-      'bot-1',
-      '--user-id',
-      'u-1',
-      '--message',
-      'plain',
-    ]);
-    const call = mockTrpcClient.botMessage.sendDirectMessage.mutate.mock.calls[0][0];
-    expect(call.attachments).toBeUndefined();
-  });
-});
-
-describe('bot message thread reply --attachment', () => {
-  let exitSpy: ReturnType<typeof vi.spyOn>;
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
-    mockTrpcClient.botMessage.replyToThread.mutate.mockReset();
-    mockTrpcClient.botMessage.replyToThread.mutate.mockResolvedValue({ messageId: 'm-tr-1' });
-  });
-
-  afterEach(() => {
-    exitSpy.mockRestore();
-    consoleSpy.mockRestore();
-  });
-
-  function createProgram() {
-    const program = new Command();
-    program.exitOverride();
-    const bot = program.command('bot');
-    registerBotMessageCommands(bot);
-    return program;
-  }
-
-  it('replies to a thread with attachments', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'thread',
-      'reply',
-      'bot-1',
-      '--thread-id',
-      'th-1',
-      '--message',
-      'reply',
-      '--attachment',
-      'https://cdn.example.com/a.png',
-    ]);
-
-    expect(mockTrpcClient.botMessage.replyToThread.mutate).toHaveBeenCalledWith(
-      expect.objectContaining({
-        attachments: [
-          expect.objectContaining({
-            fetchUrl: 'https://cdn.example.com/a.png',
-            type: 'image',
-          }),
-        ],
-        botId: 'bot-1',
-        content: 'reply',
-        threadId: 'th-1',
-      }),
-    );
-  });
-});
-
-describe('bot message send via System Bot messenger install (@id)', () => {
-  let exitSpy: ReturnType<typeof vi.spyOn>;
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
-    mockTrpcClient.botMessage.sendMessage.mutate.mockReset();
-    mockTrpcClient.botMessage.sendMessage.mutate.mockResolvedValue({ messageId: 'm-mi-1' });
-    mockTrpcClient.botMessage.sendDirectMessage.mutate.mockReset();
-    mockTrpcClient.botMessage.sendDirectMessage.mutate.mockResolvedValue({ messageId: 'm-mi-2' });
-    mockTrpcClient.botMessage.replyToThread.mutate.mockReset();
-    mockTrpcClient.botMessage.replyToThread.mutate.mockResolvedValue({ messageId: 'm-mi-3' });
-  });
-
-  afterEach(() => {
-    exitSpy.mockRestore();
-    consoleSpy.mockRestore();
-  });
-
-  function createProgram() {
-    const program = new Command();
-    program.exitOverride();
-    const bot = program.command('bot');
-    registerBotMessageCommands(bot);
-    return program;
-  }
-
-  it('@-prefixed positional arg routes to messengerInstallationId on send', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'send',
-      '@inst_abc',
-      '--target',
-      'C1',
-      '--message',
-      'hi',
-    ]);
-
-    const call = mockTrpcClient.botMessage.sendMessage.mutate.mock.calls[0][0];
-    expect(call.messengerInstallationId).toBe('inst_abc');
-    expect(call.botId).toBeUndefined();
-    expect(call.channelId).toBe('C1');
-  });
-
-  it('@-prefixed routes on dm', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'dm',
-      '@inst_xyz',
-      '--user-id',
-      'U1',
-      '--message',
-      'hi',
-    ]);
-    const call = mockTrpcClient.botMessage.sendDirectMessage.mutate.mock.calls[0][0];
-    expect(call.messengerInstallationId).toBe('inst_xyz');
-    expect(call.botId).toBeUndefined();
-  });
-
-  it('@-prefixed routes on thread reply', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'thread',
-      'reply',
-      '@inst_thr',
-      '--thread-id',
-      'T1',
-      '--message',
-      'r',
-    ]);
-    const call = mockTrpcClient.botMessage.replyToThread.mutate.mock.calls[0][0];
-    expect(call.messengerInstallationId).toBe('inst_thr');
-  });
-
-  it('plain (non-@) positional stays as botId', async () => {
-    const program = createProgram();
-    await program.parseAsync([
-      'node',
-      'test',
-      'bot',
-      'message',
-      'send',
-      'uuid-bot-id',
-      '--target',
-      'C1',
-      '--message',
-      'hi',
-    ]);
-    const call = mockTrpcClient.botMessage.sendMessage.mutate.mock.calls[0][0];
-    expect(call.botId).toBe('uuid-bot-id');
-    expect(call.messengerInstallationId).toBeUndefined();
-  });
-});
@@ -1,6 +1,3 @@
-import { readFile } from 'node:fs/promises';
-import { basename, extname } from 'node:path';
-
 import { DEFAULT_BOT_HISTORY_LIMIT } from '@lobechat/const';
 import type { Command } from 'commander';
 import pc from 'picocolors';
@@ -9,111 +6,6 @@ import { getTrpcClient } from '../api/client';
 import { confirm, outputJson, printTable, truncate } from '../utils/format';
 import { log } from '../utils/logger';

-type AttachmentInput = {
-  data?: string;
-  fetchUrl?: string;
-  mimeType?: string;
-  name?: string;
-  type: 'image' | 'file' | 'video' | 'audio';
-};
-
-const MIME_EXT_MAP: Record<string, string> = {
-  '.bmp': 'image/bmp',
-  '.gif': 'image/gif',
-  '.jpeg': 'image/jpeg',
-  '.jpg': 'image/jpeg',
-  '.m4a': 'audio/mp4',
-  '.mp3': 'audio/mpeg',
-  '.mp4': 'video/mp4',
-  '.ogg': 'audio/ogg',
-  '.pdf': 'application/pdf',
-  '.png': 'image/png',
-  '.svg': 'image/svg+xml',
-  '.txt': 'text/plain',
-  '.wav': 'audio/wav',
-  '.webm': 'video/webm',
-  '.webp': 'image/webp',
-};
-
-const inferMime = (path: string): string | undefined => MIME_EXT_MAP[extname(path).toLowerCase()];
-
-const inferAttachmentType = (mimeType?: string): AttachmentInput['type'] => {
-  if (!mimeType) return 'file';
-  if (mimeType.startsWith('image/')) return 'image';
-  if (mimeType.startsWith('video/')) return 'video';
-  if (mimeType.startsWith('audio/')) return 'audio';
-  return 'file';
-};
-
-/**
- * Resolve a list of `--attachment` flag values into `AttachmentInput[]`. Each
- * entry is either a URL or a local file path. Returns `undefined` when no
- * flags were passed so callers can omit the field on the wire entirely (the
- * TRPC schema treats absent vs empty differently). Bails the process on
- * load failures — a silently-dropped attachment would be worse than a
- * loud error here.
- */
-const resolveAttachmentFlags = async (flags: string[]): Promise<AttachmentInput[] | undefined> => {
-  if (flags.length === 0) return undefined;
-  const out: AttachmentInput[] = [];
-  for (const raw of flags) {
-    try {
-      out.push(await parseAttachmentArg(raw));
-    } catch (error) {
-      log.error(`Failed to load attachment "${raw}": ${(error as Error).message}`);
-      process.exit(1);
-    }
-  }
-  return out;
-};
-
-/**
- * Parse a single `--attachment <value>` argument. Accepted forms:
- *   - `https://…` / `http://…`           → fetchUrl, type inferred from extension
- *   - any other string                    → treated as a local file path;
- *                                           bytes are read + base64-encoded
- */
-const parseAttachmentArg = async (raw: string): Promise<AttachmentInput> => {
-  if (/^https?:\/\//.test(raw)) {
-    const pathname = new URL(raw).pathname;
-    const mimeType = inferMime(pathname);
-    return {
-      fetchUrl: raw,
-      mimeType,
-      name: basename(pathname) || undefined,
-      type: inferAttachmentType(mimeType),
-    };
-  }
-  const bytes = await readFile(raw);
-  const mimeType = inferMime(raw);
-  return {
-    data: bytes.toString('base64'),
-    mimeType,
-    name: basename(raw),
-    type: inferAttachmentType(mimeType),
-  };
-};
-
-/**
- * Resolve the `<botIdOrAtKey>` positional argument into a `{ botId? |
- * messengerInstallationId? }` shape that matches the TRPC send procedures'
- * `exactly-one-of` constraint.
- *
- * Convention: a value prefixed with `@` is treated as a System Bot
- * messenger installation id (e.g. `@inst_abc123`); anything else is a
- * per-agent bot id. The `@` was chosen because `agent_bot_providers`.id is
- * always a UUID — no UUID starts with `@`, so the prefix unambiguously
- * disambiguates without breaking the existing UUID-only call sites.
- */
-const resolveSendTargetArg = (
-  value: string,
-): { botId?: string; messengerInstallationId?: string } => {
-  if (value.startsWith('@')) {
-    return { messengerInstallationId: value.slice(1) };
-  }
-  return { botId: value };
-};
-
 export function registerBotMessageCommands(bot: Command) {
  const message = bot
    .command('message')
@@ -122,40 +14,20 @@ export function registerBotMessageCommands(bot: Command) {
  // ── send ────────────────────────────────────────────────

  message
-    .command('send <botIdOrAtKey>')
-    .description(
-      'Send a message to a channel. Pass a per-agent bot id, or "@<messenger-install-id>" ' +
-        'to send through a System Bot messenger installation (see `lh bot messengers list`).',
-    )
+    .command('send <botId>')
+    .description('Send a message to a channel')
    .requiredOption('--target <channelId>', 'Target channel / conversation ID')
    .requiredOption('--message <text>', 'Message content')
-    .option(
-      '--attachment <pathOrUrl>',
-      'Attach a file by local path or remote URL (repeatable). ' +
-        'Local paths are base64-encoded; http(s) URLs are passed as fetchUrl.',
-      collectOptions,
-      [],
-    )
    .option('--reply-to <messageId>', 'Reply to a specific message')
    .option('--json', 'Output JSON')
    .action(
      async (
-        botIdOrAtKey: string,
-        options: {
-          attachment: string[];
-          json?: boolean;
-          message: string;
-          replyTo?: string;
-          target: string;
-        },
+        botId: string,
+        options: { json?: boolean; message: string; replyTo?: string; target: string },
      ) => {
-        const attachments = await resolveAttachmentFlags(options.attachment);
-        const target = resolveSendTargetArg(botIdOrAtKey);
-
        const client = await getTrpcClient();
        const result = await client.botMessage.sendMessage.mutate({
-          ...target,
-          attachments,
+          botId,
          channelId: options.target,
          content: options.message,
          replyTo: options.replyTo,
@@ -167,56 +39,8 @@ export function registerBotMessageCommands(bot: Command) {
        }

        const r = result as any;
-        const suffix = attachments?.length ? ` with ${attachments.length} attachment(s)` : '';
        console.log(
-          `${pc.green('✓')} Message sent${r.messageId ? ` (${pc.dim(r.messageId)})` : ''}${suffix}`,
-        );
-      },
-    );
-
-  // ── dm (direct message) ─────────────────────────────────
-
-  message
-    .command('dm <botIdOrAtKey>')
-    .description(
-      'Send a direct message to a platform user. Pass a per-agent bot id, or ' +
-        '"@<messenger-install-id>" for a System Bot install.',
-    )
-    .requiredOption('--user-id <id>', 'Target user ID on the platform')
-    .requiredOption('--message <text>', 'Message content')
-    .option(
-      '--attachment <pathOrUrl>',
-      'Attach a file by local path or remote URL (repeatable). ' +
-        'Local paths are base64-encoded; http(s) URLs are passed as fetchUrl.',
-      collectOptions,
-      [],
-    )
-    .option('--json', 'Output JSON')
-    .action(
-      async (
-        botIdOrAtKey: string,
-        options: { attachment: string[]; json?: boolean; message: string; userId: string },
-      ) => {
-        const attachments = await resolveAttachmentFlags(options.attachment);
-        const target = resolveSendTargetArg(botIdOrAtKey);
-
-        const client = await getTrpcClient();
-        const result = await client.botMessage.sendDirectMessage.mutate({
-          ...target,
-          attachments,
-          content: options.message,
-          userId: options.userId,
-        });
-
-        if (options.json) {
-          outputJson(result);
-          return;
-        }
-
-        const r = result as any;
-        const suffix = attachments?.length ? ` with ${attachments.length} attachment(s)` : '';
-        console.log(
-          `${pc.green('✓')} DM sent${r.messageId ? ` (${pc.dim(r.messageId)})` : ''}${suffix}`,
+          `${pc.green('✓')} Message sent${r.messageId ? ` (${pc.dim(r.messageId)})` : ''}`,
        );
      },
    );
@@ -626,43 +450,21 @@ export function registerBotMessageCommands(bot: Command) {
    });

  thread
-    .command('reply <botIdOrAtKey>')
-    .description(
-      'Reply to a thread. Pass a per-agent bot id, or "@<messenger-install-id>" ' +
-        'for a System Bot install.',
-    )
+    .command('reply <botId>')
+    .description('Reply to a thread')
    .requiredOption('--thread-id <id>', 'Thread ID')
    .requiredOption('--message <text>', 'Reply content')
-    .option(
-      '--attachment <pathOrUrl>',
-      'Attach a file by local path or remote URL (repeatable). ' +
-        'Local paths are base64-encoded; http(s) URLs are passed as fetchUrl.',
-      collectOptions,
-      [],
-    )
-    .action(
-      async (
-        botIdOrAtKey: string,
-        options: { attachment: string[]; message: string; threadId: string },
-      ) => {
-        const attachments = await resolveAttachmentFlags(options.attachment);
-        const target = resolveSendTargetArg(botIdOrAtKey);
+    .action(async (botId: string, options: { message: string; threadId: string }) => {
+      const client = await getTrpcClient();
+      const result = await client.botMessage.replyToThread.mutate({
+        botId,
+        content: options.message,
+        threadId: options.threadId,
+      });

-        const client = await getTrpcClient();
-        const result = await client.botMessage.replyToThread.mutate({
-          ...target,
-          attachments,
-          content: options.message,
-          threadId: options.threadId,
-        });
-
-        const r = result as any;
-        const suffix = attachments?.length ? ` with ${attachments.length} attachment(s)` : '';
-        console.log(
-          `${pc.green('✓')} Reply sent${r.messageId ? ` (${pc.dim(r.messageId)})` : ''}${suffix}`,
-        );
-      },
-    );
+      const r = result as any;
+      console.log(`${pc.green('✓')} Reply sent${r.messageId ? ` (${pc.dim(r.messageId)})` : ''}`);
+    });

  // ── channel (subcommand group) ──────────────────────────

@@ -1,365 +0,0 @@
-import { Command } from 'commander';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import type * as FormatModule from '../utils/format';
-import { registerBotMessengersCommands } from './botMessengers';
-
-const { mockTrpcClient } = vi.hoisted(() => ({
-  mockTrpcClient: {
-    messenger: {
-      availablePlatforms: { query: vi.fn() },
-      getMyLink: { query: vi.fn() },
-      listMyInstallations: { query: vi.fn() },
-      listMyLinks: { query: vi.fn() },
-      setActiveAgent: { mutate: vi.fn() },
-      unlink: { mutate: vi.fn() },
-      uninstallInstallation: { mutate: vi.fn() },
-    },
-  },
-}));
-
-const { getTrpcClient: mockGetTrpcClient } = vi.hoisted(() => ({
-  getTrpcClient: vi.fn(),
-}));
-
-vi.mock('../api/client', () => ({ getTrpcClient: mockGetTrpcClient }));
-vi.mock('../utils/logger', () => ({
-  log: { debug: vi.fn(), error: vi.fn(), info: vi.fn(), warn: vi.fn() },
-  setVerbose: vi.fn(),
-}));
-
-// `confirm` always answers yes — we test uninstall/unlink under the explicit
-// `--yes` flag too, but for the prompt path we want a deterministic answer.
-vi.mock('../utils/format', async () => {
-  const actual = await vi.importActual<typeof FormatModule>('../utils/format');
-  return { ...actual, confirm: vi.fn(async () => true) };
-});
-
-describe('bot messengers', () => {
-  let exitSpy: ReturnType<typeof vi.spyOn>;
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-  let errorSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
-    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
-    for (const fn of [
-      mockTrpcClient.messenger.availablePlatforms.query,
-      mockTrpcClient.messenger.getMyLink.query,
-      mockTrpcClient.messenger.listMyInstallations.query,
-      mockTrpcClient.messenger.listMyLinks.query,
-      mockTrpcClient.messenger.setActiveAgent.mutate,
-      mockTrpcClient.messenger.unlink.mutate,
-      mockTrpcClient.messenger.uninstallInstallation.mutate,
-    ]) {
-      fn.mockReset();
-    }
-  });
-
-  afterEach(() => {
-    exitSpy.mockRestore();
-    consoleSpy.mockRestore();
-    errorSpy.mockRestore();
-  });
-
-  function createProgram() {
-    const program = new Command();
-    program.exitOverride();
-    const bot = program.command('bot');
-    registerBotMessengersCommands(bot);
-    return program;
-  }
-
-  function renderedOutput(): string {
-    return consoleSpy.mock.calls.map((c) => String(c[0])).join('\n');
-  }
-
-  // ── installations ──────────────────────────────────────
-
-  describe('list', () => {
-    it('renders the installation table with SEND ARG hint', async () => {
-      mockTrpcClient.messenger.listMyInstallations.query.mockResolvedValueOnce([
-        {
-          applicationId: 'A1',
-          id: 'inst_abc',
-          installedAt: '2026-01-15T00:00:00Z',
-          platform: 'slack',
-          tenantId: 'T1',
-          tenantName: 'Acme Corp',
-        },
-      ]);
-      await createProgram().parseAsync(['node', 'test', 'bot', 'messengers', 'list']);
-      const out = renderedOutput();
-      expect(mockTrpcClient.messenger.listMyInstallations.query).toHaveBeenCalled();
-      expect(out).toContain('inst_abc');
-      expect(out).toContain('Acme Corp');
-      // The hint should explain how to use the id with the send commands
-      expect(out).toContain('@<INSTALLATION ID>');
-    });
-
-    it('reports empty state with install guidance', async () => {
-      mockTrpcClient.messenger.listMyInstallations.query.mockResolvedValueOnce([]);
-      await createProgram().parseAsync(['node', 'test', 'bot', 'messengers', 'list']);
-      const out = renderedOutput();
-      expect(out).toContain('No System Bot installations connected.');
-      expect(out).toContain('Settings → Messenger');
-    });
-
-    it('--json passes through the payload', async () => {
-      const payload = [{ id: 'inst_only', platform: 'discord', tenantId: 'g1' }];
-      mockTrpcClient.messenger.listMyInstallations.query.mockResolvedValueOnce(payload);
-      await createProgram().parseAsync(['node', 'test', 'bot', 'messengers', 'list', '--json']);
-      expect(renderedOutput()).toContain('"id": "inst_only"');
-    });
-  });
-
-  describe('view', () => {
-    it('prints details for a matching install', async () => {
-      mockTrpcClient.messenger.listMyInstallations.query.mockResolvedValueOnce([
-        {
-          applicationId: 'A1',
-          id: 'inst_match',
-          installedAt: '2026-01-15T00:00:00Z',
-          platform: 'slack',
-          scope: 'chat:write,users:read',
-          tenantId: 'T1',
-          tenantName: 'Acme Corp',
-        },
-      ]);
-      await createProgram().parseAsync(['node', 'test', 'bot', 'messengers', 'view', 'inst_match']);
-      const out = renderedOutput();
-      expect(out).toContain('inst_match');
-      expect(out).toContain('slack');
-      expect(out).toContain('Acme Corp');
-      expect(out).toContain('chat:write,users:read');
-    });
-
-    it('exits non-zero when install missing', async () => {
-      mockTrpcClient.messenger.listMyInstallations.query.mockResolvedValueOnce([]);
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'view',
-        'inst_missing',
-      ]);
-      expect(errorSpy).toHaveBeenCalled();
-      expect(exitSpy).toHaveBeenCalledWith(1);
-    });
-
-    it('--json missing install emits JSON null + exit 1 (scriptable)', async () => {
-      mockTrpcClient.messenger.listMyInstallations.query.mockResolvedValueOnce([]);
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'view',
-        'inst_missing',
-        '--json',
-      ]);
-      // No human-readable error log; the JSON-pipe consumer gets `null`.
-      expect(errorSpy).not.toHaveBeenCalled();
-      expect(consoleSpy.mock.calls.map((c) => String(c[0])).join('\n')).toContain('null');
-      expect(exitSpy).toHaveBeenCalledWith(1);
-    });
-  });
-
-  describe('uninstall', () => {
-    it('--yes skips confirm and calls the mutation', async () => {
-      mockTrpcClient.messenger.uninstallInstallation.mutate.mockResolvedValueOnce({
-        success: true,
-      });
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'uninstall',
-        'inst_abc',
-        '--yes',
-      ]);
-      expect(mockTrpcClient.messenger.uninstallInstallation.mutate).toHaveBeenCalledWith({
-        installationId: 'inst_abc',
-      });
-      expect(renderedOutput()).toContain('revoked');
-    });
-
-    it('confirms before calling when --yes is omitted', async () => {
-      mockTrpcClient.messenger.listMyInstallations.query.mockResolvedValueOnce([
-        { id: 'inst_abc', platform: 'slack', tenantId: 'T1', tenantName: 'Acme' },
-      ]);
-      mockTrpcClient.messenger.uninstallInstallation.mutate.mockResolvedValueOnce({
-        success: true,
-      });
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'uninstall',
-        'inst_abc',
-      ]);
-      // Mocked confirm returns true → mutation still fires
-      expect(mockTrpcClient.messenger.uninstallInstallation.mutate).toHaveBeenCalled();
-    });
-  });
-
-  describe('platforms', () => {
-    it('renders the platforms table', async () => {
-      mockTrpcClient.messenger.availablePlatforms.query.mockResolvedValueOnce([
-        { appId: 'A123', id: 'slack', name: 'Slack' },
-        { botUsername: 'lobehub_bot', id: 'telegram', name: 'Telegram' },
-      ]);
-      await createProgram().parseAsync(['node', 'test', 'bot', 'messengers', 'platforms']);
-      const out = renderedOutput();
-      expect(out).toContain('slack');
-      expect(out).toContain('A123');
-      expect(out).toContain('lobehub_bot');
-    });
-
-    it('handles empty platform list gracefully', async () => {
-      mockTrpcClient.messenger.availablePlatforms.query.mockResolvedValueOnce([]);
-      await createProgram().parseAsync(['node', 'test', 'bot', 'messengers', 'platforms']);
-      expect(renderedOutput()).toContain('No System Bot platforms');
-    });
-  });
-
-  // ── links ──────────────────────────────────────────────
-
-  describe('links list', () => {
-    it('renders the links table', async () => {
-      mockTrpcClient.messenger.listMyLinks.query.mockResolvedValueOnce([
-        {
-          activeAgentId: 'agent_1',
-          platform: 'slack',
-          platformUserId: 'U1',
-          platformUsername: 'alice',
-          tenantId: 'T1',
-        },
-      ]);
-      await createProgram().parseAsync(['node', 'test', 'bot', 'messengers', 'links', 'list']);
-      const out = renderedOutput();
-      expect(out).toContain('agent_1');
-      expect(out).toContain('alice');
-    });
-
-    it('reports empty state', async () => {
-      mockTrpcClient.messenger.listMyLinks.query.mockResolvedValueOnce([]);
-      await createProgram().parseAsync(['node', 'test', 'bot', 'messengers', 'links', 'list']);
-      expect(renderedOutput()).toContain('No account links yet');
-    });
-  });
-
-  describe('links view', () => {
-    it('shows the link detail', async () => {
-      mockTrpcClient.messenger.getMyLink.query.mockResolvedValueOnce({
-        activeAgentId: 'agent_2',
-        platform: 'slack',
-        platformUserId: 'U2',
-        platformUsername: 'bob',
-        tenantId: 'T2',
-      });
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'links',
-        'view',
-        'slack',
-        '--tenant',
-        'T2',
-      ]);
-      expect(mockTrpcClient.messenger.getMyLink.query).toHaveBeenCalledWith({
-        platform: 'slack',
-        tenantId: 'T2',
-      });
-      expect(renderedOutput()).toContain('agent_2');
-    });
-
-    it('exits non-zero on missing link', async () => {
-      mockTrpcClient.messenger.getMyLink.query.mockResolvedValueOnce(null);
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'links',
-        'view',
-        'discord',
-      ]);
-      expect(errorSpy).toHaveBeenCalled();
-      expect(exitSpy).toHaveBeenCalledWith(1);
-    });
-  });
-
-  describe('links set-agent', () => {
-    it('passes agentId through to setActiveAgent', async () => {
-      mockTrpcClient.messenger.setActiveAgent.mutate.mockResolvedValueOnce({ success: true });
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'links',
-        'set-agent',
-        'slack',
-        '--agent',
-        'agent_xyz',
-        '--tenant',
-        'T1',
-      ]);
-      expect(mockTrpcClient.messenger.setActiveAgent.mutate).toHaveBeenCalledWith({
-        agentId: 'agent_xyz',
-        platform: 'slack',
-        tenantId: 'T1',
-      });
-    });
-
-    it('clears the agent when --agent none is passed', async () => {
-      mockTrpcClient.messenger.setActiveAgent.mutate.mockResolvedValueOnce({ success: true });
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'links',
-        'set-agent',
-        'telegram',
-        '--agent',
-        'none',
-      ]);
-      expect(mockTrpcClient.messenger.setActiveAgent.mutate).toHaveBeenCalledWith({
-        agentId: null,
-        platform: 'telegram',
-        tenantId: undefined,
-      });
-    });
-  });
-
-  describe('links unlink', () => {
-    it('passes platform + tenant to the unlink mutation with --yes', async () => {
-      mockTrpcClient.messenger.unlink.mutate.mockResolvedValueOnce({ success: true });
-      await createProgram().parseAsync([
-        'node',
-        'test',
-        'bot',
-        'messengers',
-        'links',
-        'unlink',
-        'slack',
-        '--tenant',
-        'T1',
-        '--yes',
-      ]);
-      expect(mockTrpcClient.messenger.unlink.mutate).toHaveBeenCalledWith({
-        platform: 'slack',
-        tenantId: 'T1',
-      });
-    });
-  });
-});
@@ -1,305 +0,0 @@
-/**
- * `lh bot messengers ...` — manages the user's System Bot installations
- * (Slack workspaces, Discord guilds, Telegram), distinct from per-agent bots.
- *
- * Mirrors `bot ...` (per-agent CRUD) and `bot message ...` (send/read), but
- * operates on `messenger_installations` (workspace-scoped) and
- * `messenger_account_links` (per-user routing). Subcommands talk directly to
- * `lambdaClient.messenger.*` — there's no shared CLI-side service layer for
- * this domain yet.
- *
- * **uninstall vs unlink** (recurring confusion — surface in command help):
- * - `uninstall <installationId>` revokes the install for the **whole
- *   workspace**. Other users in that workspace can no longer use the bot.
- * - `links unlink <platform>` only removes the **current user's** account
- *   binding. Workspace stays installed; colleagues are unaffected.
- */
-import type { Command } from 'commander';
-import pc from 'picocolors';
-
-import { getTrpcClient } from '../api/client';
-import { confirm, outputJson, printTable } from '../utils/format';
-
-const PLATFORMS = ['telegram', 'slack', 'discord'] as const;
-type MessengerPlatform = (typeof PLATFORMS)[number];
-
-const validatePlatform = (value: string): MessengerPlatform => {
-  if (!(PLATFORMS as readonly string[]).includes(value)) {
-    throw new Error(`Unknown messenger platform: ${value}. Valid values: ${PLATFORMS.join(', ')}.`);
-  }
-  return value as MessengerPlatform;
-};
-
-export function registerBotMessengersCommands(bot: Command) {
-  const messengers = bot
-    .command('messengers')
-    .description(
-      'Manage System Bot messenger installations (Slack workspaces, Discord guilds, Telegram) ' +
-        'and per-user account links',
-    );
-
-  // ── installations ──────────────────────────────────────
-
-  messengers
-    .command('list')
-    .description('List all System Bot installations the current user has connected.')
-    .option('--json', 'Output JSON')
-    .action(async (options: { json?: boolean }) => {
-      const client = await getTrpcClient();
-      const installations = await client.messenger.listMyInstallations.query();
-
-      if (options.json) {
-        outputJson(installations);
-        return;
-      }
-
-      if (installations.length === 0) {
-        console.log('No System Bot installations connected.');
-        console.log(
-          `\nRun ${pc.dim('lh bot messengers platforms')} to see what's available, then install via ` +
-            `${pc.dim('Settings → Messenger')} (OAuth requires a browser).`,
-        );
-        return;
-      }
-
-      const rows = installations.map((i: any) => [
-        i.id || '',
-        i.platform || '',
-        i.tenantName || i.tenantId || '(global)',
-        i.applicationId || '',
-        i.installedAt ? new Date(i.installedAt).toISOString().slice(0, 10) : '',
-      ]);
-      printTable(rows, ['INSTALLATION ID', 'PLATFORM', 'TENANT', 'APP ID', 'INSTALLED']);
-      console.log(
-        `\nUse ${pc.dim('@<INSTALLATION ID>')} as the positional argument on ` +
-          `${pc.dim('lh bot message send/dm/thread reply')} to route through a System Bot install.`,
-      );
-    });
-
-  messengers
-    .command('view <installationId>')
-    .description('Show detail for one installation.')
-    .option('--json', 'Output JSON')
-    .action(async (installationId: string, options: { json?: boolean }) => {
-      const client = await getTrpcClient();
-      const installations = (await client.messenger.listMyInstallations.query()) as any[];
-      const install = installations.find((i) => i.id === installationId);
-
-      if (!install) {
-        // Under `--json`, scripts need a parseable output even on miss —
-        // emit `null` to stdout (rather than a human-readable error), then
-        // exit non-zero so error handling still works in pipelines.
-        if (options.json) {
-          outputJson(null);
-        } else {
-          console.error(pc.red(`Installation not found: ${installationId}`));
-        }
-        process.exit(1);
-        return;
-      }
-
-      if (options.json) {
-        outputJson(install);
-        return;
-      }
-
-      console.log(`${pc.bold('Installation')} ${pc.dim(install.id)}`);
-      console.log(`  Platform:       ${install.platform}`);
-      console.log(`  Tenant:         ${install.tenantName || install.tenantId || '(global)'}`);
-      if (install.tenantId && install.tenantName) {
-        console.log(`  Tenant ID:      ${install.tenantId}`);
-      }
-      console.log(`  Application ID: ${install.applicationId}`);
-      if (install.scope) console.log(`  OAuth Scope:    ${install.scope}`);
-      if (install.installedAt) {
-        console.log(`  Installed:      ${new Date(install.installedAt).toISOString()}`);
-      }
-      if (install.enterpriseId) {
-        console.log(`  Enterprise ID:  ${install.enterpriseId}`);
-      }
-      if (install.isEnterpriseInstall) {
-        console.log(`  Enterprise:     yes`);
-      }
-    });
-
-  messengers
-    .command('uninstall <installationId>')
-    .description(
-      'Revoke a workspace install. AFFECTS EVERY USER IN THAT WORKSPACE — for Slack this freezes ' +
-        'the bot; for Discord it removes the audit entry (a guild admin must remove the bot ' +
-        'separately). To disconnect only your own account, use `bot messengers links unlink`.',
-    )
-    .option('--yes', 'Skip confirmation prompt')
-    .action(async (installationId: string, options: { yes?: boolean }) => {
-      const client = await getTrpcClient();
-
-      if (!options.yes) {
-        const installations = (await client.messenger.listMyInstallations.query()) as any[];
-        const install = installations.find((i) => i.id === installationId);
-        const label = install
-          ? `${install.platform} (${install.tenantName || install.tenantId || 'global'})`
-          : installationId;
-        const ok = await confirm(
-          `${pc.yellow('⚠')}  Uninstall ${pc.bold(label)} — this revokes the install for the whole workspace. Continue?`,
-        );
-        if (!ok) {
-          console.log('Aborted.');
-          return;
-        }
-      }
-
-      await client.messenger.uninstallInstallation.mutate({ installationId });
-      console.log(`${pc.green('✓')} Installation ${pc.dim(installationId)} revoked.`);
-    });
-
-  messengers
-    .command('platforms')
-    .description('List the platforms available for System Bot OAuth install.')
-    .option('--json', 'Output JSON')
-    .action(async (options: { json?: boolean }) => {
-      const client = await getTrpcClient();
-      const platforms = await client.messenger.availablePlatforms.query();
-
-      if (options.json) {
-        outputJson(platforms);
-        return;
-      }
-
-      if (platforms.length === 0) {
-        console.log('No System Bot platforms are configured on this deployment.');
-        return;
-      }
-
-      const rows = platforms.map((p: any) => [
-        p.id || '',
-        p.name || '',
-        p.appId || '',
-        p.botUsername || '',
-      ]);
-      printTable(rows, ['ID', 'NAME', 'APP ID', 'BOT USERNAME']);
-      console.log(
-        `\nInstalls are initiated via ${pc.dim('Settings → Messenger')} in the web UI ` +
-          '(OAuth needs a browser).',
-      );
-    });
-
-  // ── account links ──────────────────────────────────────
-
-  const links = messengers
-    .command('links')
-    .description('Manage per-user account links — routing of inbound IM to your agents');
-
-  links
-    .command('list')
-    .description('List all your account links across platforms and tenants.')
-    .option('--json', 'Output JSON')
-    .action(async (options: { json?: boolean }) => {
-      const client = await getTrpcClient();
-      const linkRows = await client.messenger.listMyLinks.query();
-
-      if (options.json) {
-        outputJson(linkRows);
-        return;
-      }
-
-      if (linkRows.length === 0) {
-        console.log('No account links yet. Complete verify-im on a platform first.');
-        return;
-      }
-
-      const rows = linkRows.map((l: any) => [
-        l.platform || '',
-        l.tenantId || '(global)',
-        l.activeAgentId || pc.dim('(unset)'),
-        l.platformUsername || l.platformUserId || '',
-      ]);
-      printTable(rows, ['PLATFORM', 'TENANT', 'ACTIVE AGENT', 'PLATFORM USER']);
-    });
-
-  links
-    .command('view <platform>')
-    .description('Show one account link.')
-    .option('--tenant <id>', 'Tenant scope (Slack workspace id). Omit for global-bot platforms.')
-    .option('--json', 'Output JSON')
-    .action(async (platform: string, options: { json?: boolean; tenant?: string }) => {
-      const client = await getTrpcClient();
-      const platformValidated = validatePlatform(platform);
-      const link = await client.messenger.getMyLink.query({
-        platform: platformValidated,
-        tenantId: options.tenant,
-      });
-
-      if (!link) {
-        console.error(
-          pc.red(
-            `No link found for ${platform}${options.tenant ? ` (tenant ${options.tenant})` : ''}`,
-          ),
-        );
-        process.exit(1);
-        return;
-      }
-
-      if (options.json) {
-        outputJson(link);
-        return;
-      }
-
-      console.log(`${pc.bold('Link')} ${pc.dim(link.platform)}`);
-      if (link.tenantId) console.log(`  Tenant ID:        ${link.tenantId}`);
-      console.log(`  Platform User ID: ${link.platformUserId}`);
-      if (link.platformUsername) {
-        console.log(`  Platform User:    ${link.platformUsername}`);
-      }
-      console.log(`  Active Agent:     ${link.activeAgentId ?? pc.dim('(unset)')}`);
-    });
-
-  links
-    .command('set-agent <platform>')
-    .description('Change which agent receives inbound IM on a platform link.')
-    .requiredOption('--agent <id>', 'Agent id to route to, or "none" to clear the active agent.')
-    .option('--tenant <id>', 'Tenant scope (Slack workspace id). Omit for global-bot platforms.')
-    .action(async (platform: string, options: { agent: string; tenant?: string }) => {
-      const client = await getTrpcClient();
-      const platformValidated = validatePlatform(platform);
-      const agentId = options.agent === 'none' ? null : options.agent;
-
-      await client.messenger.setActiveAgent.mutate({
-        agentId,
-        platform: platformValidated,
-        tenantId: options.tenant,
-      });
-
-      const scope = options.tenant ? ` (tenant ${options.tenant})` : '';
-      const target = agentId === null ? 'cleared' : `set to agent ${pc.dim(agentId)}`;
-      console.log(`${pc.green('✓')} Active agent for ${platform}${scope} ${target}.`);
-    });
-
-  links
-    .command('unlink <platform>')
-    .description(
-      'Remove your account link for a platform. Workspace install is unaffected — colleagues ' +
-        'can still use the bot.',
-    )
-    .option('--tenant <id>', 'Tenant scope (Slack workspace id). Omit for global-bot platforms.')
-    .option('--yes', 'Skip confirmation prompt')
-    .action(async (platform: string, options: { tenant?: string; yes?: boolean }) => {
-      const client = await getTrpcClient();
-      const platformValidated = validatePlatform(platform);
-
-      if (!options.yes) {
-        const ok = await confirm(
-          `Unlink your account from ${pc.bold(platform)}${options.tenant ? ` (tenant ${options.tenant})` : ''}?`,
-        );
-        if (!ok) {
-          console.log('Aborted.');
-          return;
-        }
-      }
-
-      await client.messenger.unlink.mutate({
-        platform: platformValidated,
-        tenantId: options.tenant,
-      });
-      console.log(`${pc.green('✓')} Unlinked.`);
-    });
-}
@@ -341,199 +341,4 @@ describe('hetero exec command', () => {
    expect(exitSpy).toHaveBeenCalledWith(2);
    expect(mockSpawnAgent).not.toHaveBeenCalled();
  });
-
-  describe('--resume auto-retry on session-not-found', () => {
-    it('retries without --resume when the error stream event indicates the session is gone', async () => {
-      // First spawn: exits non-zero, emits a resume-not-found error event
-      const resumeNotFoundEvent = {
-        data: {
-          error: 'No conversation found with session ID cc-stale',
-          message: 'No conversation found with session ID cc-stale',
-        },
-        operationId: 'op-r1',
-        stepIndex: 0,
-        timestamp: 1,
-        type: 'error',
-      };
-      mockSpawnAgent
-        .mockReturnValueOnce(createFakeHandle({ events: [resumeNotFoundEvent], exitCode: 1 }))
-        // Second spawn: succeeds
-        .mockReturnValueOnce(createFakeHandle({ exitCode: 0 }));
-
-      await runCmd([
-        'hetero',
-        'exec',
-        '--type',
-        'claude-code',
-        '--prompt',
-        'do the thing',
-        '--resume',
-        'cc-stale',
-        '--operation-id',
-        'op-r1',
-      ]);
-
-      // Two spawns: first with --resume, retry without
-      expect(mockSpawnAgent).toHaveBeenCalledTimes(2);
-      expect(mockSpawnAgent.mock.calls[0][0]).toMatchObject({ resumeSessionId: 'cc-stale' });
-      expect(mockSpawnAgent.mock.calls[1][0]).not.toHaveProperty('resumeSessionId');
-      expect(mockSpawnAgent.mock.calls[1][0].resumeSessionId).toBeUndefined();
-
-      // Final exit code comes from the retry (0 → success)
-      expect(exitSpy).toHaveBeenCalledWith(0);
-    });
-
-    it('retries without --resume when stderr contains a session-not-found message', async () => {
-      // First spawn: exits non-zero with no events, but stderr has the pattern
-      mockSpawnAgent
-        .mockReturnValueOnce(
-          createFakeHandle({
-            exitCode: 1,
-            stderrChunks: ['Error: No conversation found with session ID xyz\n'],
-          }),
-        )
-        .mockReturnValueOnce(createFakeHandle({ exitCode: 0 }));
-
-      await runCmd([
-        'hetero',
-        'exec',
-        '--type',
-        'claude-code',
-        '--prompt',
-        'continue',
-        '--resume',
-        'xyz',
-        '--operation-id',
-        'op-r2',
-      ]);
-
-      expect(mockSpawnAgent).toHaveBeenCalledTimes(2);
-      expect(mockSpawnAgent.mock.calls[1][0].resumeSessionId).toBeUndefined();
-      expect(exitSpy).toHaveBeenCalledWith(0);
-    });
-
-    it('retries without --resume when the error indicates context overflow', async () => {
-      const contextOverflowEvent = {
-        data: {
-          error: 'prompt is too long: 215168 tokens > 200000 maximum',
-          message: 'prompt is too long: 215168 tokens > 200000 maximum',
-        },
-        operationId: 'op-ctx',
-        stepIndex: 0,
-        timestamp: 1,
-        type: 'error',
-      };
-      mockSpawnAgent
-        .mockReturnValueOnce(createFakeHandle({ events: [contextOverflowEvent], exitCode: 1 }))
-        .mockReturnValueOnce(createFakeHandle({ exitCode: 0 }));
-
-      await runCmd([
-        'hetero',
-        'exec',
-        '--type',
-        'claude-code',
-        '--prompt',
-        'next question',
-        '--resume',
-        'cc-longctx',
-        '--operation-id',
-        'op-ctx',
-      ]);
-
-      expect(mockSpawnAgent).toHaveBeenCalledTimes(2);
-      expect(mockSpawnAgent.mock.calls[0][0]).toMatchObject({ resumeSessionId: 'cc-longctx' });
-      expect(mockSpawnAgent.mock.calls[1][0].resumeSessionId).toBeUndefined();
-      expect(exitSpy).toHaveBeenCalledWith(0);
-    });
-
-    it('does NOT retry on a non-resume error exit', async () => {
-      // Exit code 1 but no resume-related error message
-      mockSpawnAgent.mockReturnValueOnce(
-        createFakeHandle({ exitCode: 1, stderrChunks: ['rate limit exceeded\n'] }),
-      );
-
-      await runCmd([
-        'hetero',
-        'exec',
-        '--type',
-        'claude-code',
-        '--prompt',
-        'hi',
-        '--resume',
-        'cc-valid',
-      ]);
-
-      expect(mockSpawnAgent).toHaveBeenCalledTimes(1);
-      expect(exitSpy).toHaveBeenCalledWith(1);
-    });
-
-    it('does NOT retry when --resume is not provided', async () => {
-      const errorEvent = {
-        data: { error: 'No conversation found', message: 'No conversation found' },
-        operationId: 'op-nr',
-        stepIndex: 0,
-        timestamp: 1,
-        type: 'error',
-      };
-      mockSpawnAgent.mockReturnValueOnce(createFakeHandle({ events: [errorEvent], exitCode: 1 }));
-
-      await runCmd([
-        'hetero',
-        'exec',
-        '--type',
-        'claude-code',
-        '--prompt',
-        'fresh run',
-        '--operation-id',
-        'op-nr',
-      ]);
-
-      // No --resume → no interception → no retry
-      expect(mockSpawnAgent).toHaveBeenCalledTimes(1);
-      expect(exitSpy).toHaveBeenCalledWith(1);
-    });
-
-    it('does NOT suppress the resume-error event from JSONL output', async () => {
-      const resumeNotFoundEvent = {
-        data: {
-          error: 'No conversation found with session ID old',
-          message: 'No conversation found with session ID old',
-        },
-        operationId: 'op-jsonl',
-        stepIndex: 0,
-        timestamp: 1,
-        type: 'error',
-      };
-      mockSpawnAgent
-        .mockReturnValueOnce(createFakeHandle({ events: [resumeNotFoundEvent], exitCode: 1 }))
-        .mockReturnValueOnce(createFakeHandle({ exitCode: 0 }));
-
-      await runCmd([
-        'hetero',
-        'exec',
-        '--type',
-        'claude-code',
-        '--prompt',
-        'do thing',
-        '--resume',
-        'old',
-        '--render',
-        'jsonl',
-      ]);
-
-      // The error event is still emitted to JSONL (for observability) even
-      // though it was withheld from the ingester.
-      const lines = stdoutSpy.mock.calls
-        .map((c) => c[0])
-        .filter((s): s is string => typeof s === 'string');
-      const errorLine = lines.find((l) => {
-        try {
-          return JSON.parse(l).type === 'error';
-        } catch {
-          return false;
-        }
-      });
-      expect(errorLine).toBeDefined();
-    });
-  });
 });
@@ -17,40 +17,6 @@ import { TrpcIngestSink } from '../utils/TrpcIngestSink';

 const SUPPORTED_AGENT_TYPES = new Set(['claude-code', 'codex']);

-/**
- * Patterns that indicate a `--resume <sessionId>` run should be retried
- * without `--resume`.  Two classes of failure:
- *
- *   1. Session file missing (sandbox recycled): the container is ephemeral
- *      (~1 h idle TTL), so a new sandbox has an empty `~/.claude/projects/`
- *      and the stored session id is stale.
- *
- *   2. Context overflow (long conversation): the resumed session carries all
- *      accumulated history; when the combined token count exceeds the model's
- *      context window the API rejects the request immediately after CC
- *      initialises.  Starting fresh (no `--resume`) drops the old history and
- *      lets CC respond to the new prompt alone.
- *
- * Checked against:
- *   - `error` stream events emitted by the CC adapter from CC's result event
- *   - Accumulated stderr output (fallback when CC exits without a result event)
- */
-const RESUME_RETRY_PATTERNS = [
-  // Session file missing — sandbox was recycled
-  /no conversation found/i,
-  /session.*not found/i,
-  /conversation.*not found/i,
-  /resume.*not found/i,
-  // Context overflow — API rejected the resumed session's accumulated history
-  /prompt.*too long/i,
-  /context.*too long/i,
-  /context window.*exceed/i,
-  /maximum.*context.*length/i,
-] as const;
-
-const looksLikeNeedsRetryWithoutResume = (text: string): boolean =>
-  RESUME_RETRY_PATTERNS.some((p) => p.test(text));
-
 interface ExecOptions {
  command?: string;
  cwd?: string;
@@ -252,204 +218,95 @@ const exec = async (options: ExecOptions): Promise<void> => {
  }
  const ingester = new BatchIngester(sink);

-  /**
-   * Spawn one agent process and stream all its events into `ingester`.
-   *
-   * When `interceptResumeErrors` is true, any `error`-type event whose
-   * message matches `RESUME_RETRY_PATTERNS` is withheld from the
-   * ingester and signals a retry instead.  This keeps the server's
-   * operation state clean: no terminal error event is pushed, so the
-   * retry's events land on the same operationId without confusing the
-   * renderer.
-   *
-   * Returns:
-   *   code / signal — child exit info
-   *   sessionId     — CC session id from `system.init` (undefined on resume failure)
-   *   ingestError   — true when a batch could not be flushed after retries
-   *   resumeNotFound — true when a resume-not-found error was intercepted
-   *   stderrContent  — accumulated stderr (only when interceptResumeErrors=true)
-   */
-  const runOneAgent = async (
-    spawnOpts: Parameters<typeof spawnAgent>[0],
-    interceptResumeErrors: boolean,
-  ): Promise<{
-    code: number | null;
-    ingestError: boolean;
-    resumeNotFound: boolean;
-    sessionId: string | undefined;
-    signal: NodeJS.Signals | null;
-    stderrContent: string;
-  }> => {
-    // `spawnAgent` is async and can reject DURING image normalization — fetch
-    // failures, missing local --image paths, decode errors.
-    let handle: Awaited<ReturnType<typeof spawnAgent>>;
-    try {
-      handle = await spawnAgent(spawnOpts);
-    } catch (err) {
-      log.error('Failed to start agent:', err instanceof Error ? err.message : String(err));
-      process.exit(1);
-    }
-
-    // Always collect stderr — used for resume-error detection AND for
-    // surfacing a meaningful error message to the server when CC fails
-    // without emitting a structured error event.  Cap at 8 KB so the
-    // collector doesn't grow unboundedly on a chatty run.
-    // Always pipe to process.stderr too so users see auth prompts / warnings.
-    const STDERR_CAP = 8 * 1024;
-    let stderrContent = '';
-    handle.stderr.on('data', (chunk: Buffer) => {
-      if (stderrContent.length < STDERR_CAP) {
-        stderrContent += chunk.toString();
-      }
-    });
-    handle.stderr.pipe(process.stderr);
-
-    // Ctrl-C → SIGINT to the child's process group.
-    // Repeated Ctrl-C escalates to SIGKILL.
-    let interrupted = false;
-    const onSigint = async () => {
-      if (interrupted) {
-        handle.kill('SIGKILL');
-        return;
-      }
-      interrupted = true;
-      handle.kill('SIGINT');
-      if (serverIngest) {
-        try {
-          await ingester.drain();
-          await sink.finish({ result: 'cancelled' });
-        } catch {
-          // best-effort; process is exiting anyway
-        }
-      }
-    };
-    const onSigterm = async () => {
-      handle.kill('SIGTERM');
-      if (serverIngest) {
-        try {
-          await ingester.drain();
-          await sink.finish({ result: 'cancelled' });
-        } catch {
-          // best-effort
-        }
-      }
-    };
-    process.on('SIGINT', onSigint);
-    process.on('SIGTERM', onSigterm);
-
-    // Stream events. Each event is optionally written as JSONL and pushed
-    // into the ingester.  When intercepting resume errors, a matching
-    // `error` event is withheld from the ingester and flags a retry instead.
-    let resumeNotFound = false;
-    const ingestError = false;
-    try {
-      for await (const event of handle.events) {
-        if (interceptResumeErrors && event.type === 'error') {
-          const data = event.data as Record<string, unknown> | undefined;
-          const msg = String(data?.message ?? data?.error ?? '');
-          if (looksLikeNeedsRetryWithoutResume(msg)) {
-            resumeNotFound = true;
-            // Emit to JSONL for observability but do NOT push to ingester —
-            // we are about to retry; the server must not see a terminal error.
-            if (emitJsonl) process.stdout.write(`${JSON.stringify(event)}\n`);
-            continue;
-          }
-        }
-        if (emitJsonl) process.stdout.write(`${JSON.stringify(event)}\n`);
-        ingester.push(event);
-      }
-    } catch (err) {
-      log.error(
-        'Stream error from agent process:',
-        err instanceof Error ? err.message : String(err),
-      );
-      if (serverIngest) {
-        try {
-          await ingester.drain();
-          await sink.finish({
-            error: { message: String(err), type: 'stream_error' },
-            result: 'error',
-          });
-        } catch {
-          // best-effort
-        }
-      }
-      process.exit(1);
-    } finally {
-      process.off('SIGINT', onSigint);
-      process.off('SIGTERM', onSigterm);
-    }
-
-    const { code, signal } = await handle.exit;
-
-    // Fallback stderr detection: CC may exit non-zero without emitting a
-    // result event (e.g. it writes to stderr and quits immediately).
-    if (
-      interceptResumeErrors &&
-      !resumeNotFound &&
-      code !== 0 &&
-      looksLikeNeedsRetryWithoutResume(stderrContent)
-    ) {
-      resumeNotFound = true;
-    }
-
-    return {
-      code,
-      ingestError,
-      resumeNotFound,
-      sessionId: handle.sessionId,
-      signal,
-      stderrContent,
-    };
-  };
-
-  // ─── First run (with --resume if provided) ───────────────────────────────
-
-  const interceptResume = !!options.resume;
-  const first = await runOneAgent(
-    {
+  // `spawnAgent` is async and can reject DURING image normalization — fetch
+  // failures, missing local --image paths, decode errors. Surface those as a
+  // clean error + exit code instead of an unhandled promise rejection / stack
+  // trace, mirroring the validation try/catch above.
+  let handle: Awaited<ReturnType<typeof spawnAgent>>;
+  try {
+    handle = await spawnAgent({
      agentType: options.type,
      command: options.command,
      cwd: options.cwd || process.cwd(),
      operationId,
      prompt: resolved.prompt,
      resumeSessionId: options.resume,
-    },
-    interceptResume,
-  );
-
-  // ─── Auto-retry without --resume when the session cannot be used ─────────
-  //
-  // Two classes of failure detected via `RESUME_RETRY_PATTERNS`:
-  //   A. Sandbox recycled: container is ephemeral (~1 h idle TTL); new sandbox
-  //      has no CC session files so `--resume <staleId>` is rejected with a
-  //      "no conversation found" error.
-  //   B. Context overflow: the resumed session carries accumulated history that
-  //      pushes the combined token count past the model limit; the API rejects
-  //      the call with a "prompt is too long" error.
-  //
-  // In both cases we transparently restart CC without `--resume` so it starts a
-  // fresh session.  The server's `heteroSessionId` is updated with the new id,
-  // breaking the stale-session loop.
-  let result = first;
-  if (first.resumeNotFound) {
-    log.info('Resume failed (session not found or context overflow) — retrying without --resume');
-    result = await runOneAgent(
-      {
-        agentType: options.type,
-        command: options.command,
-        cwd: options.cwd || process.cwd(),
-        operationId,
-        prompt: resolved.prompt,
-        // No resumeSessionId — start fresh
-      },
-      false, // no need to intercept resume errors on a fresh run
-    );
+    });
+  } catch (err) {
+    log.error('Failed to start agent:', err instanceof Error ? err.message : String(err));
+    process.exit(1);
  }

-  // ─── Drain + finish ───────────────────────────────────────────────────────
+  // Forward the child's stderr to ours so users see CLI errors / warnings
+  // (auth prompts, missing-binary errors, etc.) in the terminal.
+  handle.stderr.pipe(process.stderr);

-  const { code, signal, sessionId } = result;
+  // Ctrl-C → SIGINT to the child's process group so the spawned CLI gets a
+  // chance to clean up. Repeated Ctrl-C escalates to SIGKILL via the
+  // standard "double-tap" pattern most CLIs implement themselves.
+  // In server-ingest mode, drain the ingester and call heteroFinish before
+  // exiting so the server knows the operation was cancelled.
+  let interrupted = false;
+  const onSigint = async () => {
+    if (interrupted) {
+      handle.kill('SIGKILL');
+      return;
+    }
+    interrupted = true;
+    handle.kill('SIGINT');
+    if (serverIngest) {
+      try {
+        await ingester.drain();
+        await sink.finish({ result: 'cancelled' });
+      } catch {
+        // best-effort; process is exiting anyway
+      }
+    }
+  };
+  process.on('SIGINT', onSigint);
+  process.on('SIGTERM', async () => {
+    handle.kill('SIGTERM');
+    if (serverIngest) {
+      try {
+        await ingester.drain();
+        await sink.finish({ result: 'cancelled' });
+      } catch {
+        // best-effort
+      }
+    }
+  });
+
+  // Stream events. Each event is optionally written as JSONL and always
+  // pushed into the ingester (which batches and sends to the server).
+  let ingestError = false;
+  try {
+    for await (const event of handle.events) {
+      if (emitJsonl) {
+        process.stdout.write(`${JSON.stringify(event)}\n`);
+      }
+      ingester.push(event);
+    }
+  } catch (err) {
+    log.error('Stream error from agent process:', err instanceof Error ? err.message : String(err));
+    if (serverIngest) {
+      try {
+        await ingester.drain();
+        await sink.finish({
+          result: 'error',
+          error: { message: String(err), type: 'stream_error' },
+        });
+      } catch {
+        // best-effort
+      }
+    }
+    process.exit(1);
+  } finally {
+    process.off('SIGINT', onSigint);
+  }
+
+  // Pass the child's exit code through. In server-ingest mode, drain the
+  // ingester and call heteroFinish before exiting.
+  const { code, signal } = await handle.exit;

  if (serverIngest) {
    try {
@@ -459,33 +316,21 @@ const exec = async (options: ExecOptions): Promise<void> => {
        'Failed to flush events to server:',
        err instanceof Error ? err.message : String(err),
      );
-      result = { ...result, ingestError: true };
+      ingestError = true;
    }

-    const exitedClean = !result.ingestError && (code === 0 || signal === 'SIGTERM');
-
-    // When the run failed, pass stderr as the error detail so the server can
-    // surface a useful message instead of the generic "Agent execution failed"
-    // fallback.  Trim to the last 1 KB — the tail is most informative and
-    // keeps the tRPC payload small.
-    const stderrTail = result.stderrContent.trim();
-    const finishError =
-      !exitedClean && stderrTail
-        ? { message: stderrTail.slice(-1024), type: 'AgentRuntimeError' }
-        : undefined;
-
+    const exitedClean = !ingestError && (code === 0 || signal === 'SIGTERM');
    try {
      await sink.finish({
-        error: finishError,
        result: exitedClean ? 'success' : 'error',
-        sessionId,
+        sessionId: handle.sessionId,
      });
    } catch (err) {
      log.error('Failed to send heteroFinish:', err instanceof Error ? err.message : String(err));
    }
  }

-  if (code !== null) process.exit(result.ingestError ? 1 : code);
+  if (code !== null) process.exit(ingestError ? 1 : code);
  if (signal === 'SIGINT') process.exit(130);
  if (signal === 'SIGTERM') process.exit(143);
  if (signal === 'SIGKILL') process.exit(137);
@@ -12,38 +12,16 @@ export function registerNotifyCommand(program: Command) {
    .requiredOption('-c, --content <content>', 'Message content')
    .option('--agent-id <agentId>', 'Agent ID (overrides topic default)')
    .option('--thread-id <threadId>', 'Thread ID for threaded conversations')
-    .option(
-      '--role <role>',
-      'Message role: user (default, triggers agent reply) | assistant (writes directly as agent message)',
-      'user',
-    )
-    .option(
-      '--message-id <messageId>',
-      'When --role assistant: update an existing message instead of creating a new one (keeps a single bubble)',
-    )
-    .option(
-      '--continue',
-      'When --role assistant: trigger a follow-up agent turn after writing the message',
-    )
    .option('--json', 'Output JSON')
    .action(
      async (options: {
        agentId?: string;
        content: string;
-        continue?: boolean;
        json?: boolean;
-        messageId?: string;
-        role?: 'assistant' | 'user';
        threadId?: string;
        topic: string;
      }) => {
-        log.debug(
-          'notify: topic=%s, agentId=%s, role=%s, messageId=%s',
-          options.topic,
-          options.agentId,
-          options.role,
-          options.messageId,
-        );
+        log.debug('notify: topic=%s, agentId=%s', options.topic, options.agentId);

        const client = await getTrpcClient();

@@ -51,9 +29,6 @@ export function registerNotifyCommand(program: Command) {
          const result = await client.agentNotify.notify.mutate({
            agentId: options.agentId,
            content: options.content,
-            continue: options.continue,
-            messageId: options.messageId,
-            role: options.role,
            threadId: options.threadId,
            topicId: options.topic,
          });
@@ -1,51 +0,0 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-
-export interface TaskEntry {
-  agentId?: string;
-  agentType: 'hermes' | 'openclaw';
-  operationId: string;
-  pid: number;
-  startedAt: string;
-  taskId: string;
-  topicId: string;
-}
-
-function getRegistryPath(): string {
-  return path.join(os.homedir(), '.lobehub', 'task-registry.json');
-}
-
-function readRegistry(): Record<string, TaskEntry> {
-  try {
-    return JSON.parse(fs.readFileSync(getRegistryPath(), 'utf8')) as Record<string, TaskEntry>;
-  } catch {
-    return {};
-  }
-}
-
-function writeRegistry(entries: Record<string, TaskEntry>): void {
-  const dir = path.dirname(getRegistryPath());
-  fs.mkdirSync(dir, { mode: 0o700, recursive: true });
-  fs.writeFileSync(getRegistryPath(), JSON.stringify(entries, null, 2), { mode: 0o600 });
-}
-
-export function saveTask(entry: TaskEntry): void {
-  const registry = readRegistry();
-  registry[entry.taskId] = entry;
-  writeRegistry(registry);
-}
-
-export function getTask(taskId: string): TaskEntry | undefined {
-  return readRegistry()[taskId];
-}
-
-export function removeTask(taskId: string): void {
-  const registry = readRegistry();
-  delete registry[taskId];
-  writeRegistry(registry);
-}
-
-export function listTasks(): TaskEntry[] {
-  return Object.values(readRegistry());
-}
@@ -1,10 +1,3 @@
 import { createProgram } from './program';
-import { log } from './utils/logger';

-void createProgram()
-  .parseAsync(process.argv, { from: 'node' })
-  .catch((error: unknown) => {
-    const message = error instanceof Error ? error.message : String(error);
-    log.error(message);
-    process.exit(1);
-  });
+createProgram().parse(process.argv, { from: 'node' });
@@ -1,251 +0,0 @@
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { removeTask, saveTask } from '../../daemon/taskRegistry';
-import { runHeteroTask } from '../heteroTask';
-
-// ─── Mocks ───
-
-const spawnMock = vi.hoisted(() => vi.fn());
-const execFileSyncMock = vi.hoisted(() => vi.fn());
-
-vi.mock('node:child_process', () => ({
-  execFileSync: execFileSyncMock,
-  spawn: spawnMock,
-}));
-
-// task registry — use real implementation backed by a temporary in-memory map
-const taskStore: Record<string, any> = {};
-vi.mock('../../daemon/taskRegistry', () => ({
-  getTask: vi.fn((id: string) => taskStore[id]),
-  listTasks: vi.fn(() => Object.values(taskStore)),
-  removeTask: vi.fn((id: string) => {
-    delete taskStore[id];
-  }),
-  saveTask: vi.fn((entry: any) => {
-    taskStore[entry.taskId] = entry;
-  }),
-}));
-
-vi.mock('../../api/client', () => ({
-  getTrpcClient: vi.fn().mockResolvedValue({
-    agentNotify: {
-      notify: { mutate: vi.fn().mockResolvedValue(undefined) },
-    },
-  }),
-}));
-
-vi.mock('../../utils/logger', () => ({
-  log: { error: vi.fn(), info: vi.fn(), warn: vi.fn() },
-}));
-
-// ─── Helpers ───
-
-function makeMockChild(pid = 9999) {
-  const listeners: Record<string, Array<(...a: any[]) => void>> = {};
-  return {
-    on: vi.fn((event: string, cb: (...a: any[]) => void) => {
-      (listeners[event] ??= []).push(cb);
-    }),
-    pid,
-    unref: vi.fn(),
-    _emit: (event: string, ...args: any[]) => listeners[event]?.forEach((cb) => cb(...args)),
-  };
-}
-
-// ─── Tests ───
-
-describe('runHeteroTask (openclaw)', () => {
-  beforeEach(() => {
-    vi.clearAllMocks();
-    // Clear task store
-    for (const key of Object.keys(taskStore)) delete taskStore[key];
-    execFileSyncMock.mockReturnValue('/usr/local/bin/lh\n');
-  });
-
-  afterEach(() => {
-    vi.restoreAllMocks();
-  });
-
-  it('always injects buildNotifyProtocol into the prompt regardless of session history', async () => {
-    const child = makeMockChild();
-    spawnMock.mockReturnValue(child);
-
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-1',
-      prompt: 'what time is it',
-      taskId: 'task-1',
-      topicId: 'topic-1',
-    });
-
-    expect(spawnMock).toHaveBeenCalledTimes(1);
-    const [, spawnArgs] = spawnMock.mock.calls[0] as [string, string[]];
-    const msgIdx = spawnArgs.indexOf('--message');
-    const messageArg = spawnArgs[msgIdx + 1];
-
-    expect(messageArg).toContain('what time is it');
-    expect(messageArg).toContain('lh notify');
-    expect(messageArg).toContain('MSG_ID');
-  });
-
-  it('always injects protocol even on the second turn of the same session', async () => {
-    const child1 = makeMockChild(1111);
-    const child2 = makeMockChild(2222);
-    spawnMock.mockReturnValueOnce(child1).mockReturnValueOnce(child2);
-
-    // First turn
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-1',
-      prompt: 'hello',
-      taskId: 'task-1',
-      topicId: 'topic-1',
-    });
-    // Simulate process exit so task is removed
-    child1._emit('close', 0, null);
-
-    // Second turn (same topicId)
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-2',
-      prompt: 'follow up',
-      taskId: 'task-2',
-      topicId: 'topic-1',
-    });
-
-    expect(spawnMock).toHaveBeenCalledTimes(2);
-    for (const call of spawnMock.mock.calls) {
-      const args = call[1] as string[];
-      const msg = args[args.indexOf('--message') + 1];
-      expect(msg).toContain('lh notify');
-    }
-  });
-
-  it('kills an existing concurrent process for the same topicId before spawning', async () => {
-    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
-
-    const child1 = makeMockChild(1111);
-    spawnMock.mockReturnValueOnce(child1);
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-1',
-      prompt: 'msg1',
-      taskId: 'task-1',
-      topicId: 'topic-same',
-    });
-    // task-1 is still "running" (close not fired)
-
-    const child2 = makeMockChild(2222);
-    spawnMock.mockReturnValueOnce(child2);
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-2',
-      prompt: 'msg2',
-      taskId: 'task-2',
-      topicId: 'topic-same',
-    });
-
-    expect(killSpy).toHaveBeenCalledWith(1111, 'SIGTERM');
-    expect(spawnMock).toHaveBeenCalledTimes(2);
-  });
-
-  it('does not kill processes for a different topicId', async () => {
-    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
-
-    const child1 = makeMockChild(3333);
-    spawnMock.mockReturnValueOnce(child1);
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-1',
-      prompt: 'a',
-      taskId: 'task-a',
-      topicId: 'topic-A',
-    });
-
-    const child2 = makeMockChild(4444);
-    spawnMock.mockReturnValueOnce(child2);
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-2',
-      prompt: 'b',
-      taskId: 'task-b',
-      topicId: 'topic-B',
-    });
-
-    expect(killSpy).not.toHaveBeenCalled();
-  });
-
-  it('saves task entry with correct fields after spawn', async () => {
-    const child = makeMockChild(5555);
-    spawnMock.mockReturnValue(child);
-
-    await runHeteroTask({
-      agentId: 'agent-1',
-      agentType: 'openclaw',
-      operationId: 'op-x',
-      prompt: 'test',
-      taskId: 'task-x',
-      topicId: 'topic-x',
-    });
-
-    expect(saveTask).toHaveBeenCalledWith(
-      expect.objectContaining({
-        agentType: 'openclaw',
-        pid: 5555,
-        taskId: 'task-x',
-        topicId: 'topic-x',
-      }),
-    );
-  });
-
-  it('passes --session-id and --agent args to openclaw', async () => {
-    const child = makeMockChild();
-    spawnMock.mockReturnValue(child);
-
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-1',
-      prompt: 'hello',
-      taskId: 'task-1',
-      topicId: 'my-topic-id',
-    });
-
-    const [, spawnArgs] = spawnMock.mock.calls[0] as [string, string[]];
-    expect(spawnArgs).toContain('--session-id');
-    expect(spawnArgs[spawnArgs.indexOf('--session-id') + 1]).toBe('my-topic-id');
-    expect(spawnArgs).toContain('--agent');
-    expect(spawnArgs).toContain('--local');
-  });
-
-  it('removes task and ignores already-exited process when killing concurrent task', async () => {
-    const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => {
-      throw new Error('No such process');
-    });
-
-    const child1 = makeMockChild(7777);
-    spawnMock.mockReturnValueOnce(child1);
-    await runHeteroTask({
-      agentType: 'openclaw',
-      operationId: 'op-1',
-      prompt: 'msg1',
-      taskId: 'task-1',
-      topicId: 'topic-gone',
-    });
-
-    const child2 = makeMockChild(8888);
-    spawnMock.mockReturnValueOnce(child2);
-    // Should not throw even though kill fails
-    await expect(
-      runHeteroTask({
-        agentType: 'openclaw',
-        operationId: 'op-2',
-        prompt: 'msg2',
-        taskId: 'task-2',
-        topicId: 'topic-gone',
-      }),
-    ).resolves.not.toThrow();
-
-    expect(removeTask).toHaveBeenCalledWith('task-1');
-    killSpy.mockRestore();
-  });
-});
@@ -1,70 +0,0 @@
-import { execFileSync } from 'node:child_process';
-
-import { getHermesPort } from './heteroTask';
-
-export interface CheckPlatformCapabilityParams {
-  platform: 'hermes' | 'openclaw';
-}
-
-export interface CheckPlatformCapabilityResult {
-  available: boolean;
-  reason?: string;
-  version?: string;
-}
-
-/**
- * Probe whether a specific agent platform is available on this device.
- * Dispatched by the server via `device.checkCapability` tRPC procedure.
- *
- * - openclaw: runs `openclaw --version` and parses the output
- * - hermes:   hits the gateway health endpoint on the configured port
- */
-export async function checkPlatformCapability(
-  params: CheckPlatformCapabilityParams,
-): Promise<CheckPlatformCapabilityResult> {
-  const { platform } = params;
-
-  if (platform === 'openclaw') {
-    try {
-      const output = execFileSync('openclaw', ['--version'], {
-        encoding: 'utf8',
-        timeout: 5000,
-      }).trim();
-      // output is typically "openclaw x.y.z"
-      const version = output.split(/\s+/).at(-1);
-      return { available: true, version };
-    } catch (err) {
-      return {
-        available: false,
-        reason: err instanceof Error ? err.message : 'openclaw not found or failed to run',
-      };
-    }
-  }
-
-  if (platform === 'hermes') {
-    const port = getHermesPort();
-    try {
-      const res = await fetch(`http://localhost:${port}/health`, {
-        signal: AbortSignal.timeout(5000),
-      });
-      if (res.ok) {
-        let version: string | undefined;
-        try {
-          const body = (await res.json()) as { version?: string };
-          version = body.version;
-        } catch {
-          /* ignore parse errors */
-        }
-        return { available: true, version };
-      }
-      return { available: false, reason: `Hermes gateway returned HTTP ${res.status}` };
-    } catch (err) {
-      return {
-        available: false,
-        reason: err instanceof Error ? err.message : `Hermes gateway not reachable on port ${port}`,
-      };
-    }
-  }
-
-  return { available: false, reason: `Unknown platform: ${platform as string}` };
-}
@@ -1,104 +0,0 @@
-import { execFileSync } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-
-import type { RemoteHeterogeneousAgentType } from '@lobechat/heterogeneous-agents';
-
-export interface GetAgentProfileParams {
-  /** Agent ID to query (openclaw only). Defaults to the default agent. */
-  agentId?: string;
-  platform: RemoteHeterogeneousAgentType;
-}
-
-export interface AgentProfileResult {
-  avatar?: string;
-  description?: string;
-  title?: string;
-}
-
-// Files to look for a description (tried in order)
-const IDENTITY_FILES = ['IDENTITY.md', 'SOUL.md'];
-
-/**
- * Try to extract a description from the workspace identity file.
- * Looks for Creature / Vibe / Description fields in IDENTITY.md or SOUL.md.
- */
-function readDescriptionFromWorkspace(workspacePath: string): string | undefined {
-  for (const filename of IDENTITY_FILES) {
-    const filePath = path.join(workspacePath, filename);
-    if (!fs.existsSync(filePath)) continue;
-
-    const content = fs.readFileSync(filePath, 'utf8');
-    const match = content.match(/\*{0,2}(?:Creature|Vibe|Description):?\*{0,2}\s*(.+)/i);
-    if (!match) continue;
-
-    const value = match[1].trim();
-    // Skip unfilled template placeholders like _(pick something)_ or (TBD)
-    if (/^[_*(（].*[）)*_]$|^(?:tbd|todo|n\/?a|none|待定|未定)$/i.test(value)) continue;
-    return value;
-  }
-}
-
-interface OpenClawAgentEntry {
-  id: string;
-  identityEmoji?: string;
-  identityName?: string;
-  isDefault?: boolean;
-  workspace?: string;
-}
-
-function getOpenClawProfile(agentId?: string): AgentProfileResult {
-  let output: string;
-  try {
-    output = execFileSync('openclaw', ['agents', 'list', '--json'], {
-      encoding: 'utf8',
-      timeout: 5000,
-    });
-  } catch {
-    return {};
-  }
-
-  let agents: OpenClawAgentEntry[];
-  try {
-    agents = JSON.parse(output) as OpenClawAgentEntry[];
-  } catch {
-    return {};
-  }
-
-  const agent = agentId
-    ? agents.find((a) => a.id === agentId)
-    : (agents.find((a) => a.isDefault) ?? agents[0]);
-
-  if (!agent) return {};
-
-  const title = agent.identityName || undefined;
-  const avatar = agent.identityEmoji || '🦞'; // OpenClaw brand mascot as default
-
-  // Description is not exposed by the CLI — read from the workspace IDENTITY.md
-  const description = agent.workspace ? readDescriptionFromWorkspace(agent.workspace) : undefined;
-
-  return { avatar, description, title };
-}
-
-/**
- * Fetch the agent profile (title, avatar, description) from the platform
- * installed on this device. Dispatched by the server via `device.getAgentProfile`.
- *
- * - openclaw: `openclaw agents list --json` for name + emoji, workspace
- *             IDENTITY.md for description fallback
- * - hermes:   not yet implemented — returns empty profile
- */
-export async function getAgentProfile(params: GetAgentProfileParams): Promise<AgentProfileResult> {
-  const { platform, agentId } = params;
-
-  if (platform === 'openclaw') {
-    return getOpenClawProfile(agentId);
-  }
-
-  if (platform === 'hermes') {
-    // Profile fetch not yet implemented for Hermes — return empty
-    return {};
-  }
-
-  return {};
-}
@@ -1,314 +0,0 @@
-import { execFileSync, spawn } from 'node:child_process';
-
-import type { RemoteHeterogeneousAgentType } from '@lobechat/heterogeneous-agents';
-
-import { getTrpcClient } from '../api/client';
-import { getTask, listTasks, removeTask, saveTask } from '../daemon/taskRegistry';
-import { log } from '../utils/logger';
-
-const DEFAULT_HERMES_PORT = 3456;
-
-/** Resolve the absolute path to the `lh` binary to avoid PATH issues in child processes. */
-function resolveLhPath(): string {
-  try {
-    return execFileSync('which', ['lh'], { encoding: 'utf8' }).trim();
-  } catch {
-    return 'lh';
-  }
-}
-
-export interface RunHeteroTaskParams {
-  agentId?: string;
-  agentType: RemoteHeterogeneousAgentType;
-  cwd?: string;
-  operationId: string;
-  prompt: string;
-  taskId: string;
-  topicId: string;
-}
-
-export interface CancelHeteroTaskParams {
-  signal?: 'SIGINT' | 'SIGKILL' | 'SIGTERM';
-  taskId: string;
-}
-
-export function getHermesPort(): number {
-  const env = process.env.HERMES_GATEWAY_PORT;
-  if (env) {
-    const parsed = Number.parseInt(env, 10);
-    if (!Number.isNaN(parsed)) return parsed;
-  }
-  return DEFAULT_HERMES_PORT;
-}
-
-async function isHermesGatewayRunning(port: number): Promise<boolean> {
-  try {
-    const res = await fetch(`http://localhost:${port}/health`);
-    return res.ok;
-  } catch {
-    return false;
-  }
-}
-
-async function startHermesGateway(port: number): Promise<void> {
-  const child = spawn('hermes', ['gateway', 'start'], {
-    detached: true,
-    env: { ...process.env },
-    stdio: 'ignore',
-  });
-  child.unref();
-
-  const deadline = Date.now() + 10_000;
-  while (Date.now() < deadline) {
-    await new Promise<void>((r) => setTimeout(r, 500));
-    if (await isHermesGatewayRunning(port)) return;
-  }
-  throw new Error(`Hermes gateway did not start within 10s on port ${port}`);
-}
-
-async function sendAutoNotify(
-  topicId: string,
-  taskId: string,
-  text: string,
-  agentId?: string,
-): Promise<void> {
-  try {
-    const client = await getTrpcClient();
-    await client.agentNotify.notify.mutate({
-      agentId,
-      content: text,
-      role: 'assistant',
-      topicId,
-    });
-  } catch (err) {
-    log.error('Failed to send auto-notify:', err instanceof Error ? err.message : String(err));
-  }
-}
-
-/**
- * Signal remote hetero task completion to the server so it can publish
- * `agent_runtime_end` to the gateway WS and close the frontend subscription.
- * Called on clean process exit (code=0, no signal) — error exits go through
- * `sendAutoNotify` which writes an error message AND triggers completion via
- * the `done` flag.
- */
-async function sendDoneSignal(topicId: string, agentId?: string): Promise<void> {
-  try {
-    const client = await getTrpcClient();
-    await client.agentNotify.notify.mutate({
-      agentId,
-      content: '',
-      done: true,
-      role: 'assistant',
-      topicId,
-    });
-  } catch (err) {
-    log.error('Failed to send done signal:', err instanceof Error ? err.message : String(err));
-  }
-}
-
-/**
- * Build the notify protocol injected into the first message of a new hetero-agent session.
- * Tells the agent how to push updates back to the LobeHub user via `lh notify`.
- */
-function buildNotifyProtocol(lhPath: string, topicId: string): string {
-  return (
-    `## Context: This task was dispatched by LobeHub\n\n` +
-    `This conversation / task was sent to you by the **LobeHub platform** on behalf of a user. You are running as a background agent; the user is waiting for your response inside the LobeHub chat interface.\n\n` +
-    `**When to call notify**: any time you have something meaningful to tell the user — a key finding, a decision you made, a result, a question, or your final answer. Think of it as speaking directly to the user in the chat window.\n\n` +
-    `**What to hide**: internal work details such as tool call sequences, file reads, intermediate command output, retries, or low-level reasoning steps. The user cares about outcomes and insights, not your step-by-step mechanics.\n\n` +
-    `## Sending messages back to the user\n\n` +
-    `Use the \`${lhPath} notify\` command. All your updates appear as a **single message bubble** in the UI — create it once and update it in place.\n\n` +
-    `**Step 1 — Open the bubble on your first meaningful update** (captures the messageId):\n` +
-    `\`\`\`\n` +
-    `MSG_ID=$(${lhPath} notify --topic ${topicId} --role assistant --content "Starting..." --json | grep -o '"messageId":"[^"]*"' | cut -d'"' -f4)\n` +
-    `\`\`\`\n\n` +
-    `**Step 2 — Update the same bubble as you make progress**:\n` +
-    `\`\`\`\n` +
-    `${lhPath} notify --topic ${topicId} --role assistant --message-id "$MSG_ID" --content "Still working..."\n` +
-    `\`\`\`\n\n` +
-    `**Step 3 — Replace with your complete, final response when done**:\n` +
-    `\`\`\`\n` +
-    `${lhPath} notify --topic ${topicId} --role assistant --message-id "$MSG_ID" --content "<your full response here>"\n` +
-    `\`\`\`\n\n` +
-    `Rules:\n` +
-    `- Always use \`--json\` on the first call and capture \`messageId\` from the output.\n` +
-    `- Always pass \`--message-id\` on every subsequent call so updates overwrite the same bubble.\n` +
-    `- Write what matters to the user — not implementation steps or internal tool calls.\n` +
-    `- Call notify at least once when the task is done, even if there were no intermediate updates.`
-  );
-}
-
-export async function runHeteroTask(params: RunHeteroTaskParams): Promise<string> {
-  const { agentId, agentType, cwd, operationId, prompt, taskId, topicId } = params;
-  const workDir = cwd || process.cwd();
-  const lhPath = resolveLhPath();
-
-  if (agentType === 'openclaw') {
-    // openclaw agent --local is one-shot: each invocation processes one message and exits.
-    // The --session-id links turns into the same conversation history on disk.
-    // Requires the `openclaw` binary to be on PATH with Node >=22.19.
-    const openclawAgent = process.env.OPENCLAW_AGENT_ID ?? 'main';
-
-    // Always inject the notify protocol so openclaw knows how to report results
-    // back to the LobeHub UI — even if the previous turn failed and the session
-    // history was not cleanly committed.
-    const enrichedPrompt = `${prompt}\n\n${buildNotifyProtocol(lhPath, topicId)}`;
-
-    // Kill any existing openclaw process for this topicId before spawning a new one.
-    // openclaw serialises session writes; a concurrent process holding the session
-    // lock will cause the new one to exit with code 1.
-    for (const existing of listTasks()) {
-      if (existing.topicId === topicId && existing.agentType === 'openclaw') {
-        try {
-          process.kill(existing.pid, 'SIGTERM');
-        } catch {
-          // Already exited — nothing to do.
-        }
-        removeTask(existing.taskId);
-      }
-    }
-
-    const child = spawn(
-      'openclaw',
-      [
-        'agent',
-        '--agent',
-        openclawAgent,
-        '--session-id',
-        topicId,
-        '--message',
-        enrichedPrompt,
-        '--local',
-      ],
-      {
-        cwd: workDir,
-        detached: true,
-        env: { ...process.env },
-        stdio: 'ignore',
-      },
-    );
-
-    const pid = child.pid;
-    if (pid === undefined) {
-      throw new Error('Failed to get PID for openclaw process');
-    }
-    child.unref();
-
-    saveTask({
-      agentId,
-      agentType,
-      operationId,
-      pid,
-      startedAt: new Date().toISOString(),
-      taskId,
-      topicId,
-    });
-    log.info(`OpenClaw task started: taskId=${taskId} pid=${pid} agent=${openclawAgent}`);
-
-    // On exit: notify the server so it can close the frontend gateway WS subscription.
-    // - Abnormal exit (signal or non-zero code): write an error message bubble.
-    // - Clean exit (code=0, no signal): openclaw already sent its final message via
-    //   `lh notify`; just send a done signal to publish `agent_runtime_end`.
-    child.on('close', (code, signal) => {
-      removeTask(taskId);
-      if (code !== 0 || signal !== null) {
-        const text = signal
-          ? `Task cancelled (signal: ${signal})`
-          : `Task failed (exit code: ${code})`;
-        // Send error message first, THEN signal done (sequential).
-        // Fire-and-forget both, but ensure done is always sent even if notify fails.
-        void sendAutoNotify(topicId, taskId, text, agentId).finally(() =>
-          sendDoneSignal(topicId, agentId),
-        );
-      } else {
-        // Clean exit — openclaw already sent its final message; just signal done.
-        void sendDoneSignal(topicId, agentId);
-      }
-    });
-
-    return JSON.stringify({ pid, taskId });
-  }
-
-  if (agentType === 'hermes') {
-    const port = getHermesPort();
-
-    if (!(await isHermesGatewayRunning(port))) {
-      log.info(`Hermes gateway not running on port ${port}, starting...`);
-      await startHermesGateway(port);
-    }
-
-    const res = await fetch(`http://localhost:${port}/message`, {
-      body: JSON.stringify({ content: prompt, operationId }),
-      headers: { 'Content-Type': 'application/json' },
-      method: 'POST',
-    });
-
-    if (!res.ok) {
-      throw new Error(`Hermes gateway returned ${res.status}: ${await res.text()}`);
-    }
-
-    // pid is 0 for Hermes — the gateway is long-lived and cancellation uses
-    // the HTTP /stop API rather than direct signal delivery.
-    saveTask({
-      agentId,
-      agentType,
-      operationId,
-      pid: 0,
-      startedAt: new Date().toISOString(),
-      taskId,
-      topicId,
-    });
-    log.info(`Hermes task dispatched: taskId=${taskId} operationId=${operationId}`);
-
-    return JSON.stringify({ operationId, taskId });
-  }
-
-  throw new Error(`Unsupported agentType: ${agentType as string}`);
-}
-
-export async function cancelHeteroTask(params: CancelHeteroTaskParams): Promise<string> {
-  const { signal = 'SIGINT', taskId } = params;
-  const entry = getTask(taskId);
-
-  if (!entry) {
-    return JSON.stringify({ message: `No task found with taskId: ${taskId}`, success: false });
-  }
-
-  if (entry.agentType === 'hermes') {
-    const port = getHermesPort();
-    try {
-      await fetch(`http://localhost:${port}/stop`, {
-        body: JSON.stringify({ operationId: entry.operationId }),
-        headers: { 'Content-Type': 'application/json' },
-        method: 'POST',
-      });
-    } catch (err) {
-      log.warn(
-        `Failed to send /stop to Hermes gateway: ${err instanceof Error ? err.message : String(err)}`,
-      );
-    }
-    removeTask(taskId);
-    await sendAutoNotify(entry.topicId, taskId, 'Task cancelled', entry.agentId);
-    return JSON.stringify({ taskId });
-  }
-
-  // OpenClaw: kill by PID and let the child's close handler send the notify.
-  try {
-    process.kill(entry.pid, signal);
-  } catch (err) {
-    // Process already exited — exit handler won't fire; clean up manually.
-    log.warn(
-      `Failed to send ${signal} to pid ${entry.pid}: ${err instanceof Error ? err.message : String(err)}`,
-    );
-    removeTask(taskId);
-    await sendAutoNotify(
-      entry.topicId,
-      taskId,
-      'Task already completed or cancelled',
-      entry.agentId,
-    );
-  }
-
-  return JSON.stringify({ pid: entry.pid, signal, taskId });
-}
@@ -1,5 +1,4 @@
 import { log } from '../utils/logger';
-import { checkPlatformCapability } from './checkPlatformCapability';
 import {
  editLocalFile,
  globLocalFiles,
@@ -9,14 +8,9 @@ import {
  searchLocalFiles,
  writeLocalFile,
 } from './file';
-import { getAgentProfile } from './getAgentProfile';
-import { cancelHeteroTask, runHeteroTask } from './heteroTask';
 import { getCommandOutput, killCommand, runCommand } from './shell';

 const methodMap: Record<string, (args: any) => Promise<unknown>> = {
-  cancelHeteroTask,
-  checkPlatformCapability,
-  getAgentProfile,
  editFile: editLocalFile,
  getCommandOutput,
  globFiles: globLocalFiles,
@@ -25,7 +19,6 @@ const methodMap: Record<string, (args: any) => Promise<unknown>> = {
  listFiles: listLocalFiles,
  readFile: readLocalFile,
  runCommand,
-  runHeteroTask,
  searchFiles: searchLocalFiles,
  writeFile: writeLocalFile,

@@ -427,35 +427,6 @@ describe('streamAgentEventsViaWebSocket', () => {
    ).rejects.toThrow('Gateway auth failed');
  });

-  it('should reject when websocket onerror fires', async () => {
-    const promise = streamAgentEventsViaWebSocket({
-      gatewayUrl: 'https://gw.test.com',
-      operationId: 'op-1',
-      token: 'test-token',
-    });
-
-    await flush();
-    capturedWs!.onerror?.({ message: 'socket exploded', type: 'error' });
-
-    await expect(promise).rejects.toThrow('Agent gateway WebSocket failed: [object Object]');
-  });
-
-  it('should reject when websocket closes before completion', async () => {
-    const promise = streamAgentEventsViaWebSocket({
-      gatewayUrl: 'https://gw.test.com',
-      operationId: 'op-1',
-      token: 'test-token',
-    });
-
-    await flush();
-    capturedWs!.readyState = MockWebSocket.CLOSED;
-    capturedWs!.onclose?.({ code: 1011, reason: 'gateway shutdown', type: 'close' });
-
-    await expect(promise).rejects.toThrow(
-      'Agent gateway WebSocket closed before completion: [object Object]',
-    );
-  });
-
  it('should resolve on session_complete', async () => {
    const promise = streamAgentEventsViaWebSocket({
      gatewayUrl: 'https://gw.test.com',
@@ -187,7 +187,6 @@ export async function streamAgentEventsViaWebSocket(
    const ctx = createRenderContext();
    let lastEventId = '';
    let heartbeatTimer: ReturnType<typeof setInterval> | undefined;
-    let isSettled = false;
    let jsonPrinted = false;

    const cleanup = () => {
@@ -244,8 +243,6 @@ export async function streamAgentEventsViaWebSocket(
          } else if (!streamOpts.json) {
            renderEnd(agentEvent);
          }
-          if (isSettled) return;
-          isSettled = true;
          cleanup();
          resolve();
          return;
@@ -269,8 +266,6 @@ export async function streamAgentEventsViaWebSocket(
          jsonPrinted = true;
          console.log(JSON.stringify(jsonEvents, null, 2));
        }
-        if (isSettled) return;
-        isSettled = true;
        cleanup();
        resolve();
      }
@@ -278,25 +273,16 @@ export async function streamAgentEventsViaWebSocket(

    ws.onerror = (err) => {
      cleanup();
-      if (isSettled) return;
-      if (streamOpts.json && jsonEvents.length > 0 && !jsonPrinted) {
-        jsonPrinted = true;
-        console.log(JSON.stringify(jsonEvents, null, 2));
-      }
-      isSettled = true;
-      reject(new Error(`Agent gateway WebSocket failed: ${String(err)}`));
+      reject(err);
    };

-    ws.onclose = (event) => {
+    ws.onclose = () => {
      if (heartbeatTimer) clearInterval(heartbeatTimer);
-      if (isSettled) return;
-
      if (streamOpts.json && jsonEvents.length > 0 && !jsonPrinted) {
        jsonPrinted = true;
        console.log(JSON.stringify(jsonEvents, null, 2));
      }
-      isSettled = true;
-      reject(new Error(`Agent gateway WebSocket closed before completion: ${String(event)}`));
+      resolve();
    };
  });
 }
@@ -64,12 +64,14 @@
    "@lobehub/i18n-cli": "^1.25.1",
    "@modelcontextprotocol/sdk": "^1.24.3",
    "@t3-oss/env-core": "^0.13.8",
+    "@types/async-retry": "^1.4.9",
    "@types/resolve": "^1.20.6",
    "@types/semver": "^7.7.1",
    "@types/set-cookie-parser": "^2.4.10",
    "@typescript/native-preview": "7.0.0-dev.20251210.1",
    "@vanilla-extract/css": "^1.17.4",
    "@vanilla-extract/vite-plugin": "^5.1.0",
+    "async-retry": "^1.3.3",
    "consola": "^3.4.2",
    "cookie": "^1.1.1",
    "cross-env": "^10.1.0",
@@ -107,7 +109,7 @@
    "typescript": "^5.9.3",
    "undici": "^7.16.0",
    "uuid": "^14.0.0",
-    "vite": "8.0.14",
+    "vite": "8.0.12",
    "vitest": "^3.2.4",
    "zod": "^3.25.76"
  },
@@ -37,7 +37,6 @@ export const STORE_DEFAULTS: ElectronMainStore = {
  locale: 'auto',
  localFileWorkspaceRoots: [],
  networkProxy: defaultProxySettings,
-  pendingRestoreRoute: '',
  shortcuts: DEFAULT_ELECTRON_DESKTOP_SHORTCUTS,
  storagePath: appStorageDir,
  themeMode: 'system',
@@ -21,12 +21,7 @@ const logger = createLogger('controllers:AuthCtr');

 const MAX_POLL_TIME = 2 * 60 * 1000; // 2 minutes (reduced from 5 minutes for better UX)
 const POLL_INTERVAL = 3000; // 3 seconds
-
-// Refresh the access token only once it is within this window of its expiry. Kept
-// small (minutes) on purpose: a buffer that is large relative to the server's
-// access-token lifetime makes the token look "expiring soon" right after login,
-// refreshing on every launch/activation and churning refresh-token rotations.
-const TOKEN_REFRESH_BUFFER = 10 * 60 * 1000; // 10 minutes
+const TOKEN_REFRESH_DEBOUNCE = 5 * 60 * 1000; // 5 minutes - debounce interval to prevent excessive refreshes on rapid app restarts

 /**
 * Authentication Controller
@@ -297,7 +292,8 @@ export default class AuthCtr extends ControllerModule {

    this.autoRefreshTimer = setInterval(async () => {
      try {
-        if (!this.remoteServerConfigCtr.isTokenExpiringSoon(TOKEN_REFRESH_BUFFER)) {
+        // Check if token is expiring soon (refresh 5 minutes in advance)
+        if (!this.remoteServerConfigCtr.isTokenExpiringSoon()) {
          return;
        }
        const expiresAt = this.remoteServerConfigCtr.getTokenExpiresAt();
@@ -687,7 +683,7 @@ export default class AuthCtr extends ControllerModule {
  /**
   * Initialize auto-refresh functionality
   * Checks for valid token at app startup and starts auto-refresh timer if token exists
-   * Proactively refreshes the token only when it is expired or near expiry
+   * Proactively refreshes token on every startup (with 5-minute debounce to prevent rapid restart issues)
   */
  private async initializeAutoRefresh() {
    try {
@@ -715,18 +711,26 @@ export default class AuthCtr extends ControllerModule {
        return;
      }

-      // Refresh proactively only when the token is actually near expiry. The access
-      // token is long-lived; refreshing on every launch just multiplies refresh-token
-      // rotations — and the chance of a lost-response logout — for no benefit.
-      if (this.remoteServerConfigCtr.isTokenExpiringSoon(TOKEN_REFRESH_BUFFER)) {
-        logger.info('Token is expired or expiring soon, refreshing on startup');
+      const currentTime = Date.now();
+
+      // Check if token has already expired
+      if (currentTime >= expiresAt) {
+        logger.info('Token has expired, attempting to refresh it');
+        await this.performProactiveRefresh();
+        return;
+      }
+
+      // Proactively refresh token if it hasn't been refreshed in the last 6 hours
+      // This ensures token validity even if the server has revoked it
+      if (this.shouldProactivelyRefresh()) {
+        logger.info('Token refresh interval exceeded, proactively refreshing token on startup');
        await this.performProactiveRefresh();
        return;
      }

      // Start auto-refresh timer
      logger.info(
-        `Token is valid, starting auto-refresh timer. Token expires at: ${new Date(expiresAt).toISOString()}`,
+        `Token is valid and recently refreshed, starting auto-refresh timer. Token expires at: ${new Date(expiresAt).toISOString()}`,
      );
      this.startAutoRefresh();
    } catch (error) {
@@ -734,6 +738,36 @@ export default class AuthCtr extends ControllerModule {
    }
  }

+  /**
+   * Check if token should be proactively refreshed
+   * Returns true if the token hasn't been refreshed recently (within debounce interval)
+   * This ensures we refresh on every app launch while preventing excessive refreshes on rapid restarts
+   */
+  private shouldProactivelyRefresh(): boolean {
+    const lastRefreshAt = this.remoteServerConfigCtr.getLastTokenRefreshAt();
+
+    // If never refreshed, should refresh
+    if (!lastRefreshAt) {
+      logger.debug('No last refresh time found, should proactively refresh');
+      return true;
+    }
+
+    const timeSinceLastRefresh = Date.now() - lastRefreshAt;
+    const shouldRefresh = timeSinceLastRefresh >= TOKEN_REFRESH_DEBOUNCE;
+
+    if (shouldRefresh) {
+      logger.debug(
+        `Time since last refresh: ${Math.round(timeSinceLastRefresh / 1000 / 60)} minutes, exceeds ${TOKEN_REFRESH_DEBOUNCE / 1000 / 60} minutes debounce threshold`,
+      );
+    } else {
+      logger.debug(
+        `Time since last refresh: ${Math.round(timeSinceLastRefresh / 1000 / 60)} minutes, within ${TOKEN_REFRESH_DEBOUNCE / 1000 / 60} minutes debounce threshold, skipping refresh`,
+      );
+    }
+
+    return shouldRefresh;
+  }
+
  /**
   * Perform proactive token refresh (used on startup and app activation)
   */
@@ -762,7 +796,7 @@ export default class AuthCtr extends ControllerModule {

  /**
   * Handle app activation event (e.g., Mac dock click, window focus)
-   * Proactively refresh token if it is expired or near expiry
+   * Proactively refresh token if needed (respects 6-hour interval)
   */
  async onAppActivate(): Promise<void> {
    logger.debug('App activated, checking if token refresh is needed');
@@ -783,12 +817,12 @@ export default class AuthCtr extends ControllerModule {
        return;
      }

-      // Refresh only when the token is actually near expiry (see initializeAutoRefresh).
-      if (this.remoteServerConfigCtr.isTokenExpiringSoon(TOKEN_REFRESH_BUFFER)) {
-        logger.info('Token is expiring soon on app activation, refreshing token');
+      // Only refresh if interval has passed
+      if (this.shouldProactivelyRefresh()) {
+        logger.info('Token refresh interval exceeded on app activation, refreshing token');
        await this.performProactiveRefresh();
      } else {
-        logger.debug('Token is still valid, skipping activation refresh');
+        logger.debug('Token was recently refreshed, skipping activation refresh');
      }
    } catch (error) {
      logger.error('Error during app activation refresh check:', error);
@@ -1,7 +1,3 @@
-import { execFileSync, execSync, spawn } from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-
 import type { AgentRunRequestMessage } from '@lobechat/device-gateway-client';
 import type { GatewayConnectionStatus } from '@lobechat/electron-client-ipc';

@@ -13,48 +9,6 @@ import LocalFileCtr from './LocalFileCtr';
 import RemoteServerConfigCtr from './RemoteServerConfigCtr';
 import ShellCommandCtr from './ShellCommandCtr';

-const DEFAULT_HERMES_PORT = 3456;
-
-/**
- * Inject the lh-notify protocol into the first turn of a new hetero-agent session.
- * Tells the agent binary how to push results back to the LobeHub chat UI via `lh notify`.
- * Ported directly from apps/cli/src/tools/heteroTask.ts so desktop and CLI stay in sync.
- */
-function buildNotifyProtocol(lhPath: string, topicId: string): string {
-  return (
-    `## Context: This task was dispatched by LobeHub\n\n` +
-    `This conversation / task was sent to you by the **LobeHub platform** on behalf of a user. You are running as a background agent; the user is waiting for your response inside the LobeHub chat interface.\n\n` +
-    `**When to call notify**: any time you have something meaningful to tell the user — a key finding, a decision you made, a result, a question, or your final answer.\n\n` +
-    `**What to hide**: internal work details such as tool call sequences, file reads, intermediate command output, retries, or low-level reasoning steps.\n\n` +
-    `## Sending messages back to the user\n\n` +
-    `Use the \`${lhPath} notify\` command. All your updates appear as a **single message bubble** in the UI — create it once and update it in place.\n\n` +
-    `**Step 1 — Open the bubble on your first meaningful update** (captures the messageId):\n` +
-    `\`\`\`\n` +
-    `MSG_ID=$(${lhPath} notify --topic ${topicId} --role assistant --content "Starting..." --json | grep -o '"messageId":"[^"]*"' | cut -d'"' -f4)\n` +
-    `\`\`\`\n\n` +
-    `**Step 2 — Update the same bubble as you make progress**:\n` +
-    `\`\`\`\n` +
-    `${lhPath} notify --topic ${topicId} --role assistant --message-id "$MSG_ID" --content "Still working..."\n` +
-    `\`\`\`\n\n` +
-    `**Step 3 — Replace with your complete, final response when done**:\n` +
-    `\`\`\`\n` +
-    `${lhPath} notify --topic ${topicId} --role assistant --message-id "$MSG_ID" --content "<your full response here>"\n` +
-    `\`\`\`\n\n` +
-    `Rules:\n` +
-    `- Always use \`--json\` on the first call and capture \`messageId\` from the output.\n` +
-    `- Always pass \`--message-id\` on every subsequent call so updates overwrite the same bubble.\n` +
-    `- Call notify at least once when the task is done, even if there were no intermediate updates.`
-  );
-}
-
-interface PlatformTaskEntry {
-  agentId?: string;
-  agentType: string;
-  operationId: string;
-  pid: number;
-  topicId: string;
-}
-
 /**
 * GatewayConnectionCtr
 *
@@ -63,9 +17,6 @@ interface PlatformTaskEntry {
 export default class GatewayConnectionCtr extends ControllerModule {
  static override readonly groupName = 'gatewayConnection';

-  /** In-memory registry for running platform agent tasks (openclaw / hermes). */
-  private readonly platformTasks = new Map<string, PlatformTaskEntry>();
-
  // ─── Service Accessor ───

  private get service() {
@@ -174,15 +125,11 @@ export default class GatewayConnectionCtr extends ControllerModule {
    try {
      const ctr = this.heterogeneousAgentCtr;

-      // Map agentType to binary name.
-      // claude-code → `claude` CLI; all other platforms use their type name as the binary.
-      const command = request.agentType === 'claude-code' ? 'claude' : request.agentType;
-
      // Create a session for the hetero agent.
      const { sessionId } = await ctr.startSession({
        agentType: request.agentType,
        args: [],
-        command,
+        command: request.agentType === 'codex' ? 'codex' : 'claude',
        cwd: request.cwd,
        // Inject LOBEHUB_JWT so the CLI authenticates against heteroIngest.
        env: { LOBEHUB_JWT: request.jwt },
@@ -245,14 +192,6 @@ export default class GatewayConnectionCtr extends ControllerModule {
      renameLocalFile: () => this.localFileCtr.handleRenameFile(args),
      searchLocalFiles: searchFiles,
      writeLocalFile: writeFile,
-
-      // Platform agent capability probing
-      checkPlatformCapability: () => this.checkPlatformCapability(args),
-      getAgentProfile: () => this.getAgentProfile(args),
-
-      // Platform agent task execution (openclaw / hermes)
-      cancelHeteroTask: () => this.cancelHeteroTask(args),
-      runHeteroTask: () => this.runHeteroTask(args),
    };

    const handler = methodMap[apiName];
@@ -264,331 +203,4 @@ export default class GatewayConnectionCtr extends ControllerModule {

    return handler();
  }
-
-  // ─── Platform Capability Probing ───
-
-  private async checkPlatformCapability(args: {
-    platform: string;
-  }): Promise<{ available: boolean; reason?: string; version?: string }> {
-    const { platform } = args;
-
-    const binaryMap: Record<string, string> = {
-      hermes: 'hermes',
-      openclaw: 'openclaw',
-    };
-
-    const binary = binaryMap[platform];
-    if (!binary) {
-      return { available: false, reason: `Unknown platform: ${platform}` };
-    }
-
-    const whichCmd = process.platform === 'win32' ? `where ${binary}` : `which ${binary}`;
-
-    try {
-      execSync(whichCmd, { stdio: 'pipe' });
-    } catch {
-      return { available: false, reason: `${platform} is not installed on this device` };
-    }
-
-    try {
-      const raw = execSync(`${binary} --version`, {
-        encoding: 'utf8',
-        stdio: 'pipe',
-      }).trim();
-      return { available: true, version: raw };
-    } catch {
-      return { available: true };
-    }
-  }
-
-  private async getAgentProfile(args: { agentId?: string; platform: string }): Promise<{
-    avatar?: string;
-    description?: string;
-    title?: string;
-  }> {
-    const { platform, agentId } = args;
-
-    if (platform === 'openclaw') {
-      return this.getOpenClawProfile(agentId);
-    }
-
-    // hermes and unknown platforms: not yet implemented
-    return {};
-  }
-
-  private getOpenClawProfile(agentId?: string): {
-    avatar?: string;
-    description?: string;
-    title?: string;
-  } {
-    let output: string;
-    try {
-      output = execFileSync('openclaw', ['agents', 'list', '--json'], {
-        encoding: 'utf8',
-        timeout: 5000,
-      });
-    } catch {
-      return {};
-    }
-
-    let agents: Array<{
-      id: string;
-      identityEmoji?: string;
-      identityName?: string;
-      isDefault?: boolean;
-      workspace?: string;
-    }>;
-    try {
-      agents = JSON.parse(output) as typeof agents;
-    } catch {
-      return {};
-    }
-
-    const agent = agentId
-      ? agents.find((a) => a.id === agentId)
-      : (agents.find((a) => a.isDefault) ?? agents[0]);
-
-    if (!agent) return {};
-
-    const title = agent.identityName || undefined;
-    const avatar = agent.identityEmoji || '🦞';
-    const description = agent.workspace
-      ? this.readDescriptionFromWorkspace(agent.workspace)
-      : undefined;
-
-    return { avatar, description, title };
-  }
-
-  private readDescriptionFromWorkspace(workspacePath: string): string | undefined {
-    for (const filename of ['IDENTITY.md', 'SOUL.md']) {
-      const filePath = path.join(workspacePath, filename);
-      if (!fs.existsSync(filePath)) continue;
-
-      const content = fs.readFileSync(filePath, 'utf8');
-      const match = content.match(/\*{0,2}(?:Creature|Vibe|Description):?\*{0,2}\s*(.+)/i);
-      if (!match) continue;
-
-      const value = match[1].trim();
-      if (/^[_*(（].*[）)*_]$|^(?:tbd|todo|n\/?a|none|待定|未定)$/i.test(value)) continue;
-      return value;
-    }
-  }
-
-  // ─── Platform Agent Task Execution ───
-  //
-  // Ported from apps/cli/src/tools/heteroTask.ts so that devices connected via
-  // the desktop gateway can execute openclaw/hermes tasks without requiring `lh connect`.
-
-  private async runHeteroTask(args: {
-    agentId?: string;
-    agentType: string;
-    cwd?: string;
-    operationId: string;
-    prompt: string;
-    taskId: string;
-    topicId: string;
-  }): Promise<string> {
-    const { agentId, agentType, cwd, operationId, prompt, taskId, topicId } = args;
-    const workDir = cwd || process.cwd();
-
-    if (agentType === 'openclaw') {
-      const lhPath = this.resolveLhPath();
-      const openclawAgent = process.env['OPENCLAW_AGENT_ID'] ?? 'main';
-
-      // Always inject the notify protocol so openclaw knows how to report results
-      // back to the LobeHub UI — even if the previous turn failed and the session
-      // history was not cleanly committed.
-      const enrichedPrompt = `${prompt}\n\n${buildNotifyProtocol(lhPath, topicId)}`;
-
-      // Kill any existing openclaw process for this topicId before spawning a new one.
-      // openclaw serialises session writes; a concurrent process holding the session
-      // lock will cause the new one to exit with code 1.
-      for (const [existingTaskId, entry] of this.platformTasks) {
-        if (entry.topicId === topicId && entry.agentType === 'openclaw') {
-          try {
-            process.kill(entry.pid, 'SIGTERM');
-          } catch {
-            // Already exited — nothing to do.
-          }
-          this.platformTasks.delete(existingTaskId);
-        }
-      }
-
-      const child = spawn(
-        'openclaw',
-        [
-          'agent',
-          '--agent',
-          openclawAgent,
-          '--session-id',
-          topicId,
-          '--message',
-          enrichedPrompt,
-          '--local',
-        ],
-        { cwd: workDir, detached: true, env: { ...process.env }, stdio: 'ignore' },
-      );
-
-      const pid = child.pid;
-      if (pid === undefined) throw new Error('Failed to get PID for openclaw process');
-      child.unref();
-
-      this.platformTasks.set(taskId, { agentId, agentType, operationId, pid, topicId });
-
-      child.on('close', (code, signal) => {
-        this.platformTasks.delete(taskId);
-        if (code !== 0 || signal !== null) {
-          const text = signal
-            ? `Task cancelled (signal: ${signal})`
-            : `Task failed (exit code: ${code})`;
-          void this.sendNotify({ agentId, content: text, role: 'assistant', topicId }).finally(() =>
-            this.sendNotify({ agentId, content: '', done: true, role: 'assistant', topicId }),
-          );
-        } else {
-          void this.sendNotify({ agentId, content: '', done: true, role: 'assistant', topicId });
-        }
-      });
-
-      return JSON.stringify({ pid, taskId });
-    }
-
-    if (agentType === 'hermes') {
-      const port = this.getHermesPort();
-      if (!(await this.isHermesRunning(port))) {
-        await this.startHermesGateway(port);
-      }
-
-      const res = await fetch(`http://localhost:${port}/message`, {
-        body: JSON.stringify({ content: prompt, operationId }),
-        headers: { 'Content-Type': 'application/json' },
-        method: 'POST',
-      });
-      if (!res.ok) throw new Error(`Hermes gateway returned ${res.status}: ${await res.text()}`);
-
-      this.platformTasks.set(taskId, { agentId, agentType, operationId, pid: 0, topicId });
-      return JSON.stringify({ operationId, taskId });
-    }
-
-    throw new Error(`Unsupported agentType: ${agentType}`);
-  }
-
-  private async cancelHeteroTask(args: { signal?: string; taskId: string }): Promise<string> {
-    const { signal = 'SIGINT', taskId } = args;
-    const entry = this.platformTasks.get(taskId);
-
-    if (!entry) {
-      return JSON.stringify({ message: `No task found with taskId: ${taskId}`, success: false });
-    }
-
-    if (entry.agentType === 'hermes') {
-      const port = this.getHermesPort();
-      try {
-        await fetch(`http://localhost:${port}/stop`, {
-          body: JSON.stringify({ operationId: entry.operationId }),
-          headers: { 'Content-Type': 'application/json' },
-          method: 'POST',
-        });
-      } catch {
-        // Hermes gateway may already have stopped; ignore
-      }
-      this.platformTasks.delete(taskId);
-      await this.sendNotify({
-        agentId: entry.agentId,
-        content: 'Task cancelled',
-        role: 'assistant',
-        topicId: entry.topicId,
-      });
-      return JSON.stringify({ taskId });
-    }
-
-    // openclaw: kill by PID; the close handler sends the done signal.
-    try {
-      process.kill(entry.pid, signal);
-    } catch {
-      this.platformTasks.delete(taskId);
-      await this.sendNotify({
-        agentId: entry.agentId,
-        content: 'Task already completed or cancelled',
-        role: 'assistant',
-        topicId: entry.topicId,
-      });
-    }
-
-    return JSON.stringify({ pid: entry.pid, signal, taskId });
-  }
-
-  /**
-   * Send a notify message to the server so the frontend receives agent output or
-   * a completion signal. Uses the tRPC agentNotify.notify endpoint directly —
-   * this is the desktop counterpart to `lh notify` used by the CLI path.
-   */
-  private async sendNotify(params: {
-    agentId?: string;
-    content: string;
-    done?: boolean;
-    role: string;
-    topicId: string;
-  }): Promise<void> {
-    try {
-      const [serverUrl, token] = await Promise.all([
-        this.remoteServerConfigCtr.getRemoteServerUrl(),
-        this.remoteServerConfigCtr.getAccessToken(),
-      ]);
-      if (!serverUrl || !token) return;
-
-      await fetch(`${serverUrl}/trpc/agentNotify.notify`, {
-        body: JSON.stringify({ json: params }),
-        headers: {
-          'Authorization': `Bearer ${token}`,
-          'Content-Type': 'application/json',
-        },
-        method: 'POST',
-      });
-    } catch {
-      // Fire-and-forget: openclaw's own `lh notify` calls are the primary channel.
-    }
-  }
-
-  // ─── Platform Agent Helpers ───
-
-  private resolveLhPath(): string {
-    try {
-      return execFileSync('which', ['lh'], { encoding: 'utf8' }).trim();
-    } catch {
-      return 'lh';
-    }
-  }
-
-  private getHermesPort(): number {
-    const env = process.env['HERMES_GATEWAY_PORT'];
-    if (env) {
-      const parsed = Number.parseInt(env, 10);
-      if (!Number.isNaN(parsed)) return parsed;
-    }
-    return DEFAULT_HERMES_PORT;
-  }
-
-  private async isHermesRunning(port: number): Promise<boolean> {
-    try {
-      return (await fetch(`http://localhost:${port}/health`)).ok;
-    } catch {
-      return false;
-    }
-  }
-
-  private async startHermesGateway(port: number): Promise<void> {
-    const child = spawn('hermes', ['gateway', 'start'], {
-      detached: true,
-      env: { ...process.env },
-      stdio: 'ignore',
-    });
-    child.unref();
-
-    const deadline = Date.now() + 10_000;
-    while (Date.now() < deadline) {
-      await new Promise<void>((r) => setTimeout(r, 500));
-      if (await this.isHermesRunning(port)) return;
-    }
-    throw new Error(`Hermes gateway did not start within 10s on port ${port}`);
-  }
 }
@@ -20,7 +20,6 @@ import type {
  GitWorkingTreePatch,
  GitWorkingTreePatches,
  GitWorkingTreeStatus,
-  SubmoduleWorkingTreePatches,
 } from '@lobechat/electron-client-ipc';

 import { detectRepoType, resolveGitDir } from '@/utils/git';
@@ -740,73 +739,9 @@ export default class GitController extends ControllerModule {
   *
   * Per-file patches are capped at 256 KB; oversized or binary entries get an
   * empty `patch` string and a flag the renderer can use for a placeholder.
-   *
-   * Dirty submodules are detected via `git submodule status` and surfaced as
-   * grouped `submodules[]` entries — their internal patches live under each
-   * group, not in the parent's flat `patches` list. Nested submodules are not
-   * traversed (phase 1).
   */
  @IpcMethod()
  async getGitWorkingTreePatches(dirPath: string): Promise<GitWorkingTreePatches> {
-    return this.collectWorkingTreePatches(dirPath, true);
-  }
-
-  /**
-   * List paths of initialized submodules registered in `dirPath`. Uninitialized
-   * entries (`-` prefix in `git submodule status`) are skipped — there's no
-   * working tree to inspect for those. Failures (no submodules, shell errors)
-   * return an empty set so callers gracefully fall back to the flat layout.
-   *
-   * Only direct submodules are listed; nested submodules would need
-   * `--recursive` plus a tree-aware renderer we don't have in phase 1.
-   */
-  private async listSubmodulePaths(dirPath: string): Promise<Set<string>> {
-    const execFileAsync = promisify(execFile);
-    try {
-      const { stdout } = await execFileAsync('git', ['submodule', 'status'], {
-        cwd: dirPath,
-        timeout: 5000,
-      });
-      const paths = new Set<string>();
-      for (const line of stdout.split('\n')) {
-        if (line.length < 2) continue;
-        // Status char: ' ' (clean), '+' (modified content), '-' (uninit), 'U' (conflict).
-        if (line[0] === '-') continue;
-        // Format: "<status><sha> <path>[ (<describe>)]". Parse via string ops
-        // rather than a single regex — combining `\s+` separators with a
-        // greedy/lazy path capture trips eslint's ReDoS rule.
-        const rest = line.slice(1);
-        const firstSpace = rest.indexOf(' ');
-        if (firstSpace < 0) continue;
-        const sha = rest.slice(0, firstSpace);
-        if (!/^[\da-f]{7,40}$/.test(sha)) continue;
-        let path = rest.slice(firstSpace + 1);
-        // Drop the trailing ` (<describe>)` suffix when present.
-        if (path.endsWith(')')) {
-          const describeStart = path.lastIndexOf(' (');
-          if (describeStart > 0) path = path.slice(0, describeStart);
-        }
-        if (path) paths.add(path);
-      }
-      return paths;
-    } catch (error: any) {
-      logger.debug('[listSubmodulePaths] failed', {
-        cwd: dirPath,
-        stderr: error?.stderr?.toString?.() ?? error?.stderr,
-      });
-      return new Set();
-    }
-  }
-
-  /**
-   * Shared implementation for working-tree patch collection. The IPC entry
-   * passes `recurseSubmodules: true`; recursive calls into each submodule pass
-   * `false` to avoid traversing nested submodules (phase 1).
-   */
-  private async collectWorkingTreePatches(
-    dirPath: string,
-    recurseSubmodules: boolean,
-  ): Promise<GitWorkingTreePatches> {
    const MAX_PATCH_BYTES = 256 * 1024;
    const execFileAsync = promisify(execFile);

@@ -816,19 +751,10 @@ export default class GitController extends ControllerModule {
      status: GitFileDiffStatus;
    }

-    // Step 0 — when recursion is enabled, learn which paths in the parent's
-    // status are submodule roots. Their internal diffs are collected separately
-    // (see Step 4) so we filter them out of the parent's flat patch list.
-    const submodulePaths = recurseSubmodules
-      ? await this.listSubmodulePaths(dirPath)
-      : new Set<string>();
-
    // Step 1 — classify every dirty path. Mirrors getGitWorkingTreeFiles but
    // also distinguishes untracked (`??`) from staged-add (`A`) so we can pick
-    // the right path (git diff vs raw read) per entry. Submodule entries are
-    // siphoned into `submoduleDirtyEntries` for separate recursion in Step 4.
+    // the right path (git diff vs raw read) per entry.
    const entries: Entry[] = [];
-    const submoduleDirtyEntries: Entry[] = [];
    try {
      const { stdout } = await execFileAsync('git', ['status', '--porcelain', '-z'], {
        cwd: dirPath,
@@ -846,27 +772,20 @@ export default class GitController extends ControllerModule {
        // R/C entries carry an extra source-path token we must consume.
        if (x === 'R' || x === 'C') i++;
        if (!filePath) continue;
-        let parsed: Entry | null = null;
        if (x === '?' && y === '?') {
-          parsed = { filePath, isUntracked: true, status: 'added' };
+          entries.push({ filePath, isUntracked: true, status: 'added' });
        } else if (x === '!' && y === '!') {
          // ignored
        } else if (x === 'D' || y === 'D') {
-          parsed = { filePath, isUntracked: false, status: 'deleted' };
+          entries.push({ filePath, isUntracked: false, status: 'deleted' });
        } else if (x === 'A' || y === 'A') {
-          parsed = { filePath, isUntracked: false, status: 'added' };
+          entries.push({ filePath, isUntracked: false, status: 'added' });
        } else {
-          parsed = { filePath, isUntracked: false, status: 'modified' };
-        }
-        if (!parsed) continue;
-        if (submodulePaths.has(filePath)) {
-          submoduleDirtyEntries.push(parsed);
-        } else {
-          entries.push(parsed);
+          entries.push({ filePath, isUntracked: false, status: 'modified' });
        }
      }
    } catch (error: any) {
-      logger.warn('[collectWorkingTreePatches] status failed', {
+      logger.warn('[getGitWorkingTreePatches] status failed', {
        cwd: dirPath,
        stderr: error?.stderr?.toString?.() ?? error?.stderr,
      });
@@ -899,7 +818,7 @@ export default class GitController extends ControllerModule {
          30_000,
        );
      } catch (error: any) {
-        logger.warn('[collectWorkingTreePatches] bulk diff failed; per-file fallback', {
+        logger.warn('[getGitWorkingTreePatches] bulk diff failed; per-file fallback', {
          cwd: dirPath,
          stderr: error?.stderr?.toString?.() ?? error?.stderr,
        });
@@ -936,33 +855,7 @@ export default class GitController extends ControllerModule {
    const allPatches: GitWorkingTreePatch[] = [...trackedPatches.values(), ...untrackedPatches];
    allPatches.sort((a, b) => order[a.status] - order[b.status]);

-    // Step 4 — for each dirty submodule, recurse for its own patches + branch.
-    // We only descend one level (`recurseSubmodules: false` on the inner call)
-    // because phase 1's UI groups direct children; nested submodules would
-    // need a tree view we don't have yet. Empty groups (pointer-only bumps)
-    // are kept so the user still sees the submodule surfaced in the panel.
-    let submodules: SubmoduleWorkingTreePatches[] | undefined;
-    if (submoduleDirtyEntries.length > 0) {
-      submodules = await Promise.all(
-        submoduleDirtyEntries.map(async (entry) => {
-          const absolutePath = path.resolve(dirPath, entry.filePath);
-          const [sub, branchInfo] = await Promise.all([
-            this.collectWorkingTreePatches(absolutePath, false),
-            this.getGitBranch(absolutePath),
-          ]);
-          return {
-            absolutePath,
-            branch: branchInfo.branch,
-            detached: branchInfo.detached,
-            name: path.basename(entry.filePath),
-            patches: sub.patches,
-            relativePath: entry.filePath,
-          };
-        }),
-      );
-    }
-
-    return { patches: allPatches, submodules };
+    return { patches: allPatches };
  }

  /**
@@ -983,23 +876,7 @@ export default class GitController extends ControllerModule {
   */
  @IpcMethod()
  async getGitBranchDiff(payload: GetGitBranchDiffPayload): Promise<GitBranchDiffPatches> {
-    return this.collectBranchDiff(payload.path, payload.baseRef, true);
-  }
-
-  /**
-   * Shared implementation for branch-diff collection. The IPC entry passes
-   * `recurseSubmodules: true`; recursive calls into each submodule pass
-   * `false` to avoid traversing nested submodules (phase 1). Each submodule's
-   * base ref is resolved independently — we don't try to derive it from the
-   * parent's base because (a) the parent's submodule pointer may not exist
-   * as a branch ref inside the submodule and (b) "this submodule's branch
-   * vs its own remote default" is what users typically want.
-   */
-  private async collectBranchDiff(
-    dirPath: string,
-    baseRefOverride: string | undefined,
-    recurseSubmodules: boolean,
-  ): Promise<GitBranchDiffPatches> {
+    const { path: dirPath, baseRef: baseRefOverride } = payload;
    const MAX_PATCH_BYTES = 256 * 1024;
    const execFileAsync = promisify(execFile);

@@ -1053,7 +930,7 @@ export default class GitController extends ControllerModule {
        30_000,
      );
    } catch (error: any) {
-      logger.warn('[collectBranchDiff] diff failed', {
+      logger.warn('[getGitBranchDiff] diff failed', {
        baseRef,
        cwd: dirPath,
        stderr: error?.stderr?.toString?.() ?? error?.stderr,
@@ -1061,20 +938,9 @@ export default class GitController extends ControllerModule {
      if (typeof error?.partialStdout === 'string') bulkDiff = error.partialStdout;
    }

-    // Step 4 — split per-file. When submodule recursion is enabled, peel out
-    // any pointer-bump entries (block path matches a registered submodule)
-    // into `pointerBumpPaths`; we'll surface those groups unconditionally in
-    // Step 5 even if the submodule's own branch is clean.
-    const submodulePaths = recurseSubmodules
-      ? await this.listSubmodulePaths(dirPath)
-      : new Set<string>();
+    // Step 4 — split + classify per-file from the diff preamble alone.
    const patches: GitWorkingTreePatch[] = [];
-    const pointerBumpPaths = new Set<string>();
    for (const block of splitBulkDiff(bulkDiff)) {
-      if (submodulePaths.has(block.path)) {
-        pointerBumpPaths.add(block.path);
-        continue;
-      }
      const status = detectDiffBlockStatus(block.patch);
      patches.push(buildTrackedPatch({ filePath: block.path, status }, block, MAX_PATCH_BYTES));
    }
@@ -1082,42 +948,7 @@ export default class GitController extends ControllerModule {
    const order: Record<GitFileDiffStatus, number> = { added: 0, modified: 1, deleted: 2 };
    patches.sort((a, b) => order[a.status] - order[b.status]);

-    // Step 5 — recurse for EVERY registered submodule (not just those with
-    // pointer-bumps) so we also surface submodules whose own branch diverges
-    // from its own origin/HEAD even when the parent's pointer is unchanged.
-    // Single-level only (`recurseSubmodules: false` on the inner call). A
-    // group is kept when EITHER its pointer changed in the parent OR its own
-    // branch diff has at least one patch; submodules that are clean on both
-    // axes are dropped to keep the panel quiet. Submodule count is expected
-    // to be small (single digits in practice), so per-submodule fetch + diff
-    // in parallel is acceptable.
-    let submodules: SubmoduleWorkingTreePatches[] | undefined;
-    if (submodulePaths.size > 0) {
-      const candidates = await Promise.all(
-        Array.from(submodulePaths).map(async (relativePath) => {
-          const absolutePath = path.resolve(dirPath, relativePath);
-          const [sub, branchInfo] = await Promise.all([
-            this.collectBranchDiff(absolutePath, undefined, false),
-            this.getGitBranch(absolutePath),
-          ]);
-          return {
-            group: {
-              absolutePath,
-              branch: branchInfo.branch,
-              detached: branchInfo.detached,
-              name: path.basename(relativePath),
-              patches: sub.patches,
-              relativePath,
-            },
-            keep: pointerBumpPaths.has(relativePath) || sub.patches.length > 0,
-          };
-        }),
-      );
-      const filtered = candidates.filter((c) => c.keep).map((c) => c.group);
-      if (filtered.length > 0) submodules = filtered;
-    }
-
-    return { baseRef, headRef, patches, submodules };
+    return { baseRef, headRef, patches };
  }

  /**
@@ -605,7 +605,7 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
    }
  }

-  // ─── AskUserQuestion MCP server () ───
+  // ─── AskUserQuestion MCP server (LOBE-8725) ───

  /**
   * Lazy single-instance MCP server for CC's AskUserQuestion replacement.
@@ -651,7 +651,7 @@ export default class HeterogeneousAgentCtr extends ControllerModule {

    // `alwaysLoad: true` is the undocumented CC flag that promotes our
    // server's tool out of the deferred set so the model calls it directly
-    // (no ToolSearch hop). See spike notes — falls back to the
+    // (no ToolSearch hop). See LOBE-8725 spike notes — falls back to the
    // 2-hop ToolSearch path if a future CC drops the flag, no breakage.
    const config = {
      mcpServers: {
@@ -43,18 +43,17 @@ import {
 import {
  editLocalFile,
  expandTilde,
-  type FileResult,
  listLocalFiles,
  moveLocalFiles,
  readLocalFile,
  renameLocalFile,
-  type SearchOptions,
  writeLocalFile,
 } from '@lobechat/local-file-shell';
 import { dialog, shell } from 'electron';
 import { execa } from 'execa';
 import { unzipSync } from 'fflate';

+import { type FileResult, type SearchOptions } from '@/modules/fileSearch';
 import ContentSearchService from '@/services/contentSearchSrv';
 import FileSearchService from '@/services/fileSearchSrv';
 import { createLogger } from '@/utils/logger';
@@ -2,6 +2,7 @@ import querystring from 'node:querystring';
 import { URL } from 'node:url';

 import type { DataSyncConfig } from '@lobechat/electron-client-ipc';
+import retry from 'async-retry';
 import { safeStorage, session as electronSession } from 'electron';

 import { OFFICIAL_CLOUD_SERVER } from '@/const/env';
@@ -377,8 +378,10 @@ export default class RemoteServerConfigCtr extends ControllerModule {
  }

  /**
-   * Refresh the access token using the stored refresh token (single attempt).
-   * Concurrent callers share the in-progress refresh promise.
+   * Refresh access token with retry mechanism
+   * Use stored refresh token to obtain a new access token
+   * Handles concurrent requests by returning the existing refresh promise if one is in progress.
+   * Retries up to 3 times with exponential backoff for transient errors.
   */
  async refreshAccessToken(): Promise<{ error?: string; success: boolean }> {
    // If a refresh is already in progress, return the existing promise
@@ -387,18 +390,60 @@ export default class RemoteServerConfigCtr extends ControllerModule {
      return this.refreshPromise;
    }

-    logger.info('Initiating new token refresh operation.');
+    // Start a new refresh operation with retry
+    logger.info('Initiating new token refresh operation with retry.');
+    this.refreshPromise = this.performTokenRefreshWithRetry();

-    // No retry: with refresh token rotation the server consumes the old token as soon
-    // as the request lands. Resending it (e.g. after a lost response) triggers reuse
-    // detection — invalid_grant + revocation of the whole grant — which logs the user
-    // out. Transient failures are recovered by the next refresh cycle instead.
-    this.refreshPromise = this.performTokenRefresh().finally(() => {
+    // Return the promise so callers can wait
+    return this.refreshPromise;
+  }
+
+  /**
+   * Performs token refresh with retry mechanism
+   * Uses exponential backoff: 1s, 2s, 4s
+   */
+  private async performTokenRefreshWithRetry(): Promise<{ error?: string; success: boolean }> {
+    try {
+      return await retry(
+        async (bail, attemptNumber) => {
+          logger.debug(`Token refresh attempt ${attemptNumber}/3`);
+
+          const result = await this.performTokenRefresh();
+
+          if (result.success) {
+            return result;
+          }
+
+          // Check if error is non-retryable
+          if (this.isNonRetryableError(result.error)) {
+            logger.warn(`Non-retryable error encountered: ${result.error}`);
+            // Use bail to stop retrying immediately
+            bail(new Error(result.error));
+            return result; // This won't be reached, but TypeScript needs it
+          }
+
+          // Throw error to trigger retry for transient errors
+          throw new Error(result.error);
+        },
+        {
+          factor: 2, // Exponential backoff factor
+          maxTimeout: 4000, // Max wait time between retries: 4s
+          minTimeout: 1000, // Min wait time between retries: 1s
+          onRetry: (err: Error, attempt: number) => {
+            logger.info(`Token refresh retry ${attempt}/3: ${err.message}`);
+          },
+          retries: 3, // Total retry attempts
+        },
+      );
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      logger.error('Token refresh failed after all retries:', errorMessage);
+      return { error: errorMessage, success: false };
+    } finally {
+      // Ensure the promise reference is cleared once the operation completes
      logger.debug('Clearing the refresh promise reference.');
      this.refreshPromise = null;
-    });
-
-    return this.refreshPromise;
+    }
  }

  /**
@@ -721,7 +721,10 @@ describe('AuthCtr', () => {
  });

  describe('Proactive Token Refresh', () => {
+    const FIVE_MINUTES = 5 * 60 * 1000; // Debounce interval
+
    beforeEach(() => {
+      // Reset mocks for proactive refresh tests
      vi.mocked(mockRemoteServerConfigCtr.getRemoteServerConfig).mockResolvedValue({
        active: true,
        remoteServerUrl: 'https://lobehub-cloud.com',
@@ -730,16 +733,22 @@ describe('AuthCtr', () => {
      vi.mocked(mockRemoteServerConfigCtr.isRemoteServerConfigured).mockResolvedValue(true);
      vi.mocked(mockRemoteServerConfigCtr.getAccessToken).mockResolvedValue('mock-access-token');
      vi.mocked(mockRemoteServerConfigCtr.getTokenExpiresAt).mockReturnValue(
-        Date.now() + 7 * 24 * 60 * 60 * 1000, // Token valid for 7 days
+        Date.now() + 3600000, // Token valid for 1 hour
      );
-      vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(false);
-      vi.mocked(mockRemoteServerConfigCtr.refreshAccessToken).mockResolvedValue({ success: true });
-      vi.mocked(mockRemoteServerConfigCtr.isNonRetryableError).mockReturnValue(false);
+      // Reset getLastTokenRefreshAt to a recent value by default
+      // Individual tests will override this as needed
+      vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(Date.now());
    });

    describe('onAppActivate', () => {
-      it('should refresh token when it is expiring soon', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(true);
+      it('should refresh token when last refresh was more than 5 minutes ago', async () => {
+        // Last refresh was 10 minutes ago (exceeds 5-minute debounce)
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 10 * 60 * 1000,
+        );
+        vi.mocked(mockRemoteServerConfigCtr.refreshAccessToken).mockResolvedValue({
+          success: true,
+        });

        await authCtr.onAppActivate();

@@ -747,27 +756,33 @@ describe('AuthCtr', () => {
        expect(mockWindow.webContents.send).toHaveBeenCalledWith('tokenRefreshed');
      });

-      it('should NOT refresh token when it is not expiring soon', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(false);
+      it('should NOT refresh token when last refresh was within 5 minutes', async () => {
+        // Last refresh was 2 minutes ago (within 5-minute debounce)
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 2 * 60 * 1000,
+        );

        await authCtr.onAppActivate();

        expect(mockRemoteServerConfigCtr.refreshAccessToken).not.toHaveBeenCalled();
      });

-      it('should check expiry with a small buffer, not the 24h default', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(false);
+      it('should refresh token when lastRefreshAt is undefined (never refreshed)', async () => {
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(undefined);
+        vi.mocked(mockRemoteServerConfigCtr.refreshAccessToken).mockResolvedValue({
+          success: true,
+        });

        await authCtr.onAppActivate();

-        const [buffer] = vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mock.calls[0];
-        expect(buffer).toBeGreaterThan(0);
-        expect(buffer).toBeLessThanOrEqual(60 * 60 * 1000);
+        expect(mockRemoteServerConfigCtr.refreshAccessToken).toHaveBeenCalled();
      });

      it('should skip refresh when remote server is not active', async () => {
        vi.mocked(mockRemoteServerConfigCtr.isRemoteServerConfigured).mockResolvedValue(false);
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(true);
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 10 * 60 * 1000,
+        );

        await authCtr.onAppActivate();

@@ -776,15 +791,19 @@ describe('AuthCtr', () => {

      it('should skip refresh when no access token exists', async () => {
        vi.mocked(mockRemoteServerConfigCtr.getAccessToken).mockResolvedValue(null);
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(true);
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 10 * 60 * 1000,
+        );

        await authCtr.onAppActivate();

        expect(mockRemoteServerConfigCtr.refreshAccessToken).not.toHaveBeenCalled();
      });

-      it('should clear tokens and require re-auth on non-retryable error', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(true);
+      it('should handle refresh failure with non-retryable error', async () => {
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 10 * 60 * 1000,
+        );
        vi.mocked(mockRemoteServerConfigCtr.refreshAccessToken).mockResolvedValue({
          error: 'invalid_grant',
          success: false,
@@ -800,8 +819,10 @@ describe('AuthCtr', () => {
        expect(mockWindow.webContents.send).toHaveBeenCalledWith('authorizationRequired');
      });

-      it('should preserve tokens on transient error', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(true);
+      it('should handle refresh failure with transient error (start auto-refresh)', async () => {
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 10 * 60 * 1000,
+        );
        vi.mocked(mockRemoteServerConfigCtr.refreshAccessToken).mockResolvedValue({
          error: 'network_error',
          success: false,
@@ -810,49 +831,90 @@ describe('AuthCtr', () => {

        await authCtr.onAppActivate();

+        // Should not clear tokens for transient errors
        expect(mockRemoteServerConfigCtr.clearTokens).not.toHaveBeenCalled();
      });
    });

    describe('afterAppReady (initializeAutoRefresh)', () => {
-      it('should proactively refresh on startup when token is expiring soon', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(true);
+      it('should proactively refresh token on startup when debounce interval exceeded', async () => {
+        // Last refresh was 10 minutes ago (exceeds 5-minute debounce)
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 10 * 60 * 1000,
+        );
+        vi.mocked(mockRemoteServerConfigCtr.refreshAccessToken).mockResolvedValue({
+          success: true,
+        });

        authCtr.afterAppReady();
+
+        // Wait for async initialization
        await new Promise((resolve) => setTimeout(resolve, 100));

        expect(mockRemoteServerConfigCtr.refreshAccessToken).toHaveBeenCalled();
      });

-      it('should NOT refresh on startup when token is not expiring soon', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(false);
+      it('should NOT refresh on startup when token was recently refreshed (within debounce)', async () => {
+        // Last refresh was 2 minutes ago (within 5-minute debounce)
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 2 * 60 * 1000,
+        );

        authCtr.afterAppReady();
+
+        // Wait for async initialization
        await new Promise((resolve) => setTimeout(resolve, 100));

        expect(mockRemoteServerConfigCtr.refreshAccessToken).not.toHaveBeenCalled();
      });

-      it('should check expiry with a small buffer, not the 24h default', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(false);
+      it('should refresh on startup when token is expired regardless of last refresh time', async () => {
+        // Token expired 1 hour ago
+        vi.mocked(mockRemoteServerConfigCtr.getTokenExpiresAt).mockReturnValue(
+          Date.now() - 60 * 60 * 1000,
+        );
+        // Last refresh was 2 minutes ago (within debounce, but token is expired)
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - 2 * 60 * 1000,
+        );
+        vi.mocked(mockRemoteServerConfigCtr.refreshAccessToken).mockResolvedValue({
+          success: true,
+        });

        authCtr.afterAppReady();
+
+        // Wait for async initialization
        await new Promise((resolve) => setTimeout(resolve, 100));

-        const [buffer] = vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mock.calls[0];
-        expect(buffer).toBeGreaterThan(0);
-        expect(buffer).toBeLessThanOrEqual(60 * 60 * 1000);
+        expect(mockRemoteServerConfigCtr.refreshAccessToken).toHaveBeenCalled();
      });
+    });

-      it('should skip initialization when no access token exists', async () => {
-        vi.mocked(mockRemoteServerConfigCtr.getAccessToken).mockResolvedValue(null);
-        vi.mocked(mockRemoteServerConfigCtr.isTokenExpiringSoon).mockReturnValue(true);
+    describe('refresh debounce boundary tests', () => {
+      it('should NOT refresh at exactly 5 minutes minus 1 second', async () => {
+        // Last refresh was 4 minutes 59 seconds ago
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - (FIVE_MINUTES - 1000),
+        );

-        authCtr.afterAppReady();
-        await new Promise((resolve) => setTimeout(resolve, 100));
+        await authCtr.onAppActivate();

        expect(mockRemoteServerConfigCtr.refreshAccessToken).not.toHaveBeenCalled();
      });
+
+      it('should refresh at exactly 5 minutes', async () => {
+        // Last refresh was exactly 5 minutes ago
+        vi.mocked(mockRemoteServerConfigCtr.getLastTokenRefreshAt).mockReturnValue(
+          Date.now() - FIVE_MINUTES,
+        );
+        vi.mocked(mockRemoteServerConfigCtr.refreshAccessToken).mockResolvedValue({
+          success: true,
+        });
+
+        await authCtr.onAppActivate();
+
+        expect(mockRemoteServerConfigCtr.refreshAccessToken).toHaveBeenCalled();
+      });
    });
  });
 });
@@ -1,12 +1,9 @@
-import type { execSync as ExecSyncType } from 'node:child_process';
-
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';

 import type { App } from '@/core/App';
 import GatewayConnectionService from '@/services/gatewayConnectionSrv';

 import GatewayConnectionCtr from '../GatewayConnectionCtr';
-import HeterogeneousAgentCtr from '../HeterogeneousAgentCtr';
 import LocalFileCtr from '../LocalFileCtr';
 import RemoteServerConfigCtr from '../RemoteServerConfigCtr';
 import ShellCommandCtr from '../ShellCommandCtr';
@@ -34,7 +31,6 @@ const { ipcMainHandleMock, MockGatewayClient } = vi.hoisted(() => {
    });

    sendToolCallResponse = vi.fn();
-    sendAgentRunAck = vi.fn();

    constructor(options: any) {
      super();
@@ -75,22 +71,6 @@ const { ipcMainHandleMock, MockGatewayClient } = vi.hoisted(() => {
      this.emit('error', new Error(message));
    }

-    simulateAgentRunRequest(
-      agentType: string,
-      operationId = 'op-1',
-      prompt = 'hello',
-      jwt = 'mock-jwt',
-    ) {
-      this.emit('agent_run_request', {
-        agentType,
-        jwt,
-        operationId,
-        prompt,
-        topicId: 'topic-1',
-        type: 'agent_run_request',
-      });
-    }
-
    simulateReconnecting(delay: number) {
      this.connectionStatus = 'reconnecting';
      this.emit('status_changed', 'reconnecting');
@@ -109,10 +89,6 @@ vi.mock('electron', () => ({
    getPath: vi.fn((name: string) => `/mock/${name}`),
  },
  ipcMain: { handle: ipcMainHandleMock },
-  powerSaveBlocker: {
-    start: vi.fn(() => 1),
-    stop: vi.fn(),
-  },
 }));

 vi.mock('@/utils/logger', () => ({
@@ -143,15 +119,6 @@ vi.mock('node:crypto', () => ({
  randomUUID: vi.fn(() => 'mock-device-uuid'),
 }));

-const execSyncMock = vi.hoisted(() => vi.fn());
-const execFileSyncMock = vi.hoisted(() => vi.fn());
-const spawnMock = vi.hoisted(() => vi.fn());
-
-vi.mock('node:child_process', async (importOriginal) => {
-  const actual = await importOriginal<{ execSync: typeof ExecSyncType }>();
-  return { ...actual, execFileSync: execFileSyncMock, execSync: execSyncMock, spawn: spawnMock };
-});
-
 vi.mock('node:os', () => ({
  default: { hostname: vi.fn(() => 'mock-hostname') },
 }));
@@ -160,13 +127,6 @@ vi.mock('@lobechat/device-gateway-client', () => ({
  GatewayClient: MockGatewayClient,
 }));

-vi.mock('execa', () => ({
-  execa: vi.fn().mockResolvedValue({ stdout: '', stderr: '' }),
-}));
-
-vi.mock('fast-glob', () => ({ default: vi.fn().mockResolvedValue([]) }));
-vi.mock('fflate', () => ({ unzipSync: vi.fn() }));
-
 // ─── Mock Controllers ───

 const mockLocalFileCtr = {
@@ -198,11 +158,6 @@ const mockShellCommandCtr = {
  handleRunCommand: vi.fn().mockResolvedValue({ success: true, stdout: '' }),
 } as unknown as ShellCommandCtr;

-const mockHeterogeneousAgentCtr = {
-  sendPrompt: vi.fn().mockResolvedValue(undefined),
-  startSession: vi.fn().mockResolvedValue({ sessionId: 'mock-session-id' }),
-} as unknown as HeterogeneousAgentCtr;
-
 const mockRemoteServerConfigCtr = {
  getAccessToken: vi.fn().mockResolvedValue('mock-access-token'),
  isRemoteServerConfigured: vi.fn().mockResolvedValue(true),
@@ -219,7 +174,6 @@ const mockApp = {
    if (Cls === RemoteServerConfigCtr) return mockRemoteServerConfigCtr;
    if (Cls === LocalFileCtr) return mockLocalFileCtr;
    if (Cls === ShellCommandCtr) return mockShellCommandCtr;
-    if (Cls === HeterogeneousAgentCtr) return mockHeterogeneousAgentCtr;
    return null;
  }),
  getService: vi.fn((Cls) => {
@@ -619,327 +573,6 @@ describe('GatewayConnectionCtr', () => {
    });
  });

-  // ─── Agent Run Routing ───
-
-  describe('agent run routing', () => {
-    async function connectAndOpen() {
-      ctr.afterAppReady();
-      await vi.advanceTimersByTimeAsync(0);
-      const client = MockGatewayClient.lastInstance!;
-      client.simulateConnected();
-      return client;
-    }
-
-    beforeEach(() => {
-      vi.mocked(mockHeterogeneousAgentCtr.startSession).mockClear();
-      vi.mocked(mockHeterogeneousAgentCtr.sendPrompt).mockClear();
-    });
-
-    it.each([
-      ['openclaw', 'openclaw'],
-      ['hermes', 'hermes'],
-      ['codex', 'codex'],
-      ['claude-code', 'claude'],
-    ] as const)('uses command "%s" for agentType "%s"', async (agentType, expectedCommand) => {
-      const client = await connectAndOpen();
-      client.simulateAgentRunRequest(agentType);
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(mockHeterogeneousAgentCtr.startSession).toHaveBeenCalledWith(
-        expect.objectContaining({ agentType, command: expectedCommand }),
-      );
-    });
-
-    it('sends accepted ack and fires sendPrompt', async () => {
-      const client = await connectAndOpen();
-      client.simulateAgentRunRequest('openclaw', 'op-xyz');
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(client.sendAgentRunAck).toHaveBeenCalledWith({
-        operationId: 'op-xyz',
-        status: 'accepted',
-      });
-      expect(mockHeterogeneousAgentCtr.sendPrompt).toHaveBeenCalledWith(
-        expect.objectContaining({ operationId: 'op-xyz', sessionId: 'mock-session-id' }),
-      );
-    });
-
-    it('sends rejected ack when startSession throws', async () => {
-      vi.mocked(mockHeterogeneousAgentCtr.startSession).mockRejectedValueOnce(
-        new Error('binary not found'),
-      );
-
-      const client = await connectAndOpen();
-      client.simulateAgentRunRequest('openclaw', 'op-fail');
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(client.sendAgentRunAck).toHaveBeenCalledWith({
-        operationId: 'op-fail',
-        reason: 'binary not found',
-        status: 'rejected',
-      });
-    });
-  });
-
-  // ─── runHeteroTask ───
-
-  describe('runHeteroTask', () => {
-    /** Creates a minimal mock child process returned by spawn(). */
-    function makeMockChild(pid = 9999) {
-      const listeners: Record<string, Array<(...a: any[]) => void>> = {};
-      return {
-        on: vi.fn((event: string, cb: (...a: any[]) => void) => {
-          listeners[event] = listeners[event] ?? [];
-          listeners[event].push(cb);
-        }),
-        pid,
-        unref: vi.fn(),
-        _emit: (event: string, ...args: any[]) => listeners[event]?.forEach((cb) => cb(...args)),
-      };
-    }
-
-    async function connectAndOpen() {
-      ctr.afterAppReady();
-      await vi.advanceTimersByTimeAsync(0);
-      const client = MockGatewayClient.lastInstance!;
-      client.simulateConnected();
-      return client;
-    }
-
-    beforeEach(() => {
-      execFileSyncMock.mockReturnValue('/usr/local/bin/lh\n');
-      spawnMock.mockReset();
-    });
-
-    it('always injects buildNotifyProtocol into the prompt', async () => {
-      const child = makeMockChild();
-      spawnMock.mockReturnValue(child);
-
-      const client = await connectAndOpen();
-      client.simulateToolCallRequest(
-        'runHeteroTask',
-        {
-          agentType: 'openclaw',
-          operationId: 'op-1',
-          prompt: 'hello',
-          taskId: 'task-1',
-          topicId: 'topic-1',
-        },
-        'req-run',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(spawnMock).toHaveBeenCalledTimes(1);
-      const [, spawnArgs] = spawnMock.mock.calls[0] as [string, string[]];
-      const messageArg = spawnArgs[spawnArgs.indexOf('--message') + 1];
-      expect(messageArg).toContain('hello');
-      expect(messageArg).toContain('lh notify');
-    });
-
-    it('kills an existing concurrent openclaw process for the same topicId before spawning', async () => {
-      const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
-
-      // First task
-      const child1 = makeMockChild(1111);
-      spawnMock.mockReturnValueOnce(child1);
-      const client = await connectAndOpen();
-      client.simulateToolCallRequest(
-        'runHeteroTask',
-        {
-          agentType: 'openclaw',
-          operationId: 'op-1',
-          prompt: 'msg1',
-          taskId: 'task-1',
-          topicId: 'topic-same',
-        },
-        'req-1',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      // Second task for same topicId — should kill task-1's pid first
-      const child2 = makeMockChild(2222);
-      spawnMock.mockReturnValueOnce(child2);
-      client.simulateToolCallRequest(
-        'runHeteroTask',
-        {
-          agentType: 'openclaw',
-          operationId: 'op-2',
-          prompt: 'msg2',
-          taskId: 'task-2',
-          topicId: 'topic-same',
-        },
-        'req-2',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(killSpy).toHaveBeenCalledWith(1111, 'SIGTERM');
-      expect(spawnMock).toHaveBeenCalledTimes(2);
-
-      killSpy.mockRestore();
-    });
-
-    it('does not kill processes for a different topicId', async () => {
-      const killSpy = vi.spyOn(process, 'kill').mockImplementation(() => true);
-
-      const child1 = makeMockChild(3333);
-      spawnMock.mockReturnValueOnce(child1);
-      const client = await connectAndOpen();
-      client.simulateToolCallRequest(
-        'runHeteroTask',
-        {
-          agentType: 'openclaw',
-          operationId: 'op-1',
-          prompt: 'a',
-          taskId: 'task-a',
-          topicId: 'topic-A',
-        },
-        'req-a',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      const child2 = makeMockChild(4444);
-      spawnMock.mockReturnValueOnce(child2);
-      client.simulateToolCallRequest(
-        'runHeteroTask',
-        {
-          agentType: 'openclaw',
-          operationId: 'op-2',
-          prompt: 'b',
-          taskId: 'task-b',
-          topicId: 'topic-B',
-        },
-        'req-b',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(killSpy).not.toHaveBeenCalled();
-
-      killSpy.mockRestore();
-    });
-  });
-
-  // ─── Platform Capability Probing ───
-
-  describe('platform capability probing', () => {
-    async function connectAndOpen() {
-      ctr.afterAppReady();
-      await vi.advanceTimersByTimeAsync(0);
-      const client = MockGatewayClient.lastInstance!;
-      client.simulateConnected();
-      return client;
-    }
-
-    beforeEach(() => {
-      execSyncMock.mockReset();
-    });
-
-    it('returns available:true with version when binary is installed', async () => {
-      execSyncMock.mockImplementation((cmd: string) => {
-        if (cmd.startsWith('which ') || cmd.startsWith('where '))
-          return '/usr/local/bin/openclaw\n';
-        if (cmd.includes('--version')) return 'openclaw 1.2.3\n';
-        return '';
-      });
-
-      const client = await connectAndOpen();
-      client.simulateToolCallRequest(
-        'checkPlatformCapability',
-        { platform: 'openclaw' },
-        'req-cap',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(client.sendToolCallResponse).toHaveBeenCalledWith({
-        requestId: 'req-cap',
-        result: {
-          content: JSON.stringify({ available: true, version: 'openclaw 1.2.3' }),
-          success: true,
-        },
-      });
-    });
-
-    it('returns available:true without version when --version command fails', async () => {
-      execSyncMock.mockImplementation((cmd: string) => {
-        if (cmd.startsWith('which ') || cmd.startsWith('where '))
-          return '/usr/local/bin/openclaw\n';
-        throw new Error('version command failed');
-      });
-
-      const client = await connectAndOpen();
-      client.simulateToolCallRequest(
-        'checkPlatformCapability',
-        { platform: 'openclaw' },
-        'req-cap-nover',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(client.sendToolCallResponse).toHaveBeenCalledWith({
-        requestId: 'req-cap-nover',
-        result: {
-          content: JSON.stringify({ available: true }),
-          success: true,
-        },
-      });
-    });
-
-    it('returns available:false when binary is not installed', async () => {
-      execSyncMock.mockImplementation(() => {
-        throw new Error('command not found');
-      });
-
-      const client = await connectAndOpen();
-      client.simulateToolCallRequest(
-        'checkPlatformCapability',
-        { platform: 'openclaw' },
-        'req-missing',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(client.sendToolCallResponse).toHaveBeenCalledWith({
-        requestId: 'req-missing',
-        result: {
-          content: JSON.stringify({
-            available: false,
-            reason: 'openclaw is not installed on this device',
-          }),
-          success: true,
-        },
-      });
-    });
-
-    it('returns available:false for unknown platform', async () => {
-      const client = await connectAndOpen();
-      client.simulateToolCallRequest(
-        'checkPlatformCapability',
-        { platform: 'unknownBot' },
-        'req-unknown-plat',
-      );
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(client.sendToolCallResponse).toHaveBeenCalledWith({
-        requestId: 'req-unknown-plat',
-        result: {
-          content: JSON.stringify({ available: false, reason: 'Unknown platform: unknownBot' }),
-          success: true,
-        },
-      });
-    });
-
-    it('getAgentProfile returns empty object', async () => {
-      const client = await connectAndOpen();
-      client.simulateToolCallRequest('getAgentProfile', { platform: 'openclaw' }, 'req-profile');
-      await vi.advanceTimersByTimeAsync(0);
-
-      expect(client.sendToolCallResponse).toHaveBeenCalledWith({
-        requestId: 'req-profile',
-        result: {
-          content: JSON.stringify({}),
-          success: true,
-        },
-      });
-    });
-  });
-
  // ─── IPC Methods ───

  describe('getConnectionStatus', () => {
@@ -717,7 +717,7 @@ describe('HeterogeneousAgentCtr', () => {
   * `stdout.on('end')` handler can schedule `pipeline.flush()` onto the
   * broadcast queue), then drain the queue, then broadcast complete.
   */
-  describe('exit-before-end ordering (phase 0 race)', () => {
+  describe('exit-before-end ordering (LOBE-8516 phase 0 race)', () => {
    let broadcasts: Array<{ channel: string; data: any }>;

    beforeEach(() => {
@@ -808,7 +808,7 @@ describe('HeterogeneousAgentCtr', () => {
    });
  });

-  describe('app-quit cleanup of AskUserQuestion temp configs ()', () => {
+  describe('app-quit cleanup of AskUserQuestion temp configs (LOBE-8725)', () => {
    // The async exit-handler cleanup races Electron's main-process teardown
    // and used to leak `lobe-cc-mcp-<opId>.json` files in `os.tmpdir()` on
    // every quit. The controller now unlinks pending intervention temp
@@ -535,7 +535,6 @@ describe('RemoteServerConfigCtr', () => {

      expect(result.success).toBe(false);
      expect(result.error).toContain('Token refresh failed');
-      expect(mockFetch).toHaveBeenCalledTimes(1);
    });

    it('should handle missing tokens in response', async () => {
@@ -619,7 +618,7 @@ describe('RemoteServerConfigCtr', () => {
      expect(mockFetch).toHaveBeenCalledTimes(1);
    });

-    it('should not retry after a network error', async () => {
+    it('should handle network errors with retry', async () => {
      const { safeStorage } = await import('electron');
      vi.mocked(safeStorage.isEncryptionAvailable).mockReturnValue(true);
      vi.mocked(safeStorage.decryptString).mockImplementation((buffer: Buffer) =>
@@ -645,8 +644,9 @@ describe('RemoteServerConfigCtr', () => {

      expect(result.success).toBe(false);
      expect(result.error).toContain('Network error');
-      expect(mockFetch).toHaveBeenCalledTimes(1);
-    });
+      // With retry mechanism, fetch should be called 4 times (1 initial + 3 retries)
+      expect(mockFetch).toHaveBeenCalledTimes(4);
+    }, 15000);
  });

  describe('afterAppReady', () => {
@@ -256,26 +256,6 @@ export class BrowserManager {
    });
  }

-  /**
-   * Consume a route captured before an update restart. The captured route is
-   * cleared before any navigation decision so a subsequent normal launch never
-   * restores a stale route.
-   */
-  private consumePendingRestoreRoute(): string {
-    const pendingRestoreRoute = this.app.storeManager.get('pendingRestoreRoute', '');
-    if (pendingRestoreRoute) this.app.storeManager.set('pendingRestoreRoute', '');
-    return pendingRestoreRoute;
-  }
-
-  private resolveMainWindowInitialPath(
-    isOnboardingCompleted: boolean,
-    pendingRestoreRoute: string,
-  ): string {
-    if (!isOnboardingCompleted) return '/desktop-onboarding';
-    if (pendingRestoreRoute) return pendingRestoreRoute;
-    return '/';
-  }
-
  /**
   * Initialize all browsers when app starts up
   */
@@ -291,11 +271,7 @@ export class BrowserManager {

      // Dynamically determine initial path for main window
      if (browser.identifier === BrowsersIdentifiers.app) {
-        const pendingRestoreRoute = this.consumePendingRestoreRoute();
-        const initialPath = this.resolveMainWindowInitialPath(
-          isOnboardingCompleted,
-          pendingRestoreRoute,
-        );
+        const initialPath = isOnboardingCompleted ? '/' : '/desktop-onboarding';
        browser = {
          ...browser,
          keepAlive: isLinux ? false : browser.keepAlive,
@@ -110,13 +110,6 @@ describe('BrowserManager', () => {
      getController: vi.fn().mockReturnValue({
        isRemoteServerConfigured: vi.fn().mockResolvedValue(true),
      }),
-      storeManager: {
-        get: vi.fn((key: string) => {
-          if (key === 'pendingRestoreRoute') return '';
-          return '';
-        }),
-        set: vi.fn(),
-      },
    } as unknown as AppCore;

    manager = new BrowserManager(mockApp);
@@ -273,43 +266,6 @@ describe('BrowserManager', () => {
      expect(manager.browsers.has('app')).toBe(true);
      expect(manager.browsers.has('settings')).toBe(false);
    });
-
-    it('restores a captured route as the main window initial path', async () => {
-      (mockApp.storeManager.get as any).mockImplementation((key: string) => {
-        if (key === 'pendingRestoreRoute') return '/agent/abc';
-        return '';
-      });
-
-      await manager.initializeBrowsers();
-
-      expect(manager.browsers.get('app')?.options.path).toBe('/agent/abc');
-    });
-
-    it('clears the captured route after consuming it', async () => {
-      (mockApp.storeManager.get as any).mockImplementation((key: string) => {
-        if (key === 'pendingRestoreRoute') return '/agent/abc';
-        return '';
-      });
-
-      await manager.initializeBrowsers();
-
-      expect(mockApp.storeManager.set).toHaveBeenCalledWith('pendingRestoreRoute', '');
-    });
-
-    it('ignores the captured route when onboarding is not completed', async () => {
-      (mockApp.storeManager.get as any).mockImplementation((key: string) => {
-        if (key === 'pendingRestoreRoute') return '/agent/abc';
-        return '';
-      });
-      (mockApp.getController as any).mockReturnValue({
-        isRemoteServerConfigured: vi.fn().mockResolvedValue(false),
-      });
-
-      await manager.initializeBrowsers();
-
-      expect(manager.browsers.get('app')?.options.path).toBe('/desktop-onboarding');
-      expect(mockApp.storeManager.set).toHaveBeenCalledWith('pendingRestoreRoute', '');
-    });
  });

  describe('broadcastToAllWindows', () => {
@@ -12,7 +12,6 @@ import { autoUpdater } from 'electron-updater';
 import { isDev, isWindows } from '@/const/env';
 import { getDesktopEnv } from '@/env';
 import { UPDATE_CHANNEL, UPDATE_SERVER_URL, updaterConfig } from '@/modules/updater/configs';
-import { extractRestoreRoute } from '@/modules/updater/utils';
 import { createLogger } from '@/utils/logger';

 import type { App as AppCore } from '../App';
@@ -240,29 +239,12 @@ export class UpdaterManager {
    }
  };

-  private captureRestoreRoute = () => {
-    try {
-      const url = this.mainWindow.webContents?.getURL();
-      if (!url) return;
-
-      const route = extractRestoreRoute(url);
-      if (!route) return;
-
-      this.app.storeManager.set('pendingRestoreRoute', route);
-      logger.info(`Captured route for restore after update restart: ${route}`);
-    } catch (error) {
-      logger.warn('Failed to capture route for restore after update restart:', error);
-    }
-  };
-
  /**
   * Install update immediately
   */
  public installNow = () => {
    logger.info('Installing update now...');

-    this.captureRestoreRoute();
-
    this.app.isQuiting = true;

    logger.info('Closing all windows before update installation...');
@@ -361,51 +361,6 @@ describe('UpdaterManager', () => {
    });
  });

-  describe('captureRestoreRoute', () => {
-    const callCapture = () => (updaterManager as any).captureRestoreRoute();
-
-    it('stores the derived route from the main window URL', () => {
-      (mockApp.browserManager.getMainWindow as any).mockReturnValue({
-        webContents: { getURL: () => 'app://renderer/agent/abc' },
-      });
-
-      callCapture();
-
-      expect(mockApp.storeManager.set).toHaveBeenCalledWith('pendingRestoreRoute', '/agent/abc');
-    });
-
-    it('stores nothing when the URL is not a restorable route', () => {
-      (mockApp.browserManager.getMainWindow as any).mockReturnValue({
-        webContents: { getURL: () => 'app://renderer/' },
-      });
-
-      callCapture();
-
-      expect(mockApp.storeManager.set).not.toHaveBeenCalled();
-    });
-
-    it('stores nothing when there is no webContents', () => {
-      (mockApp.browserManager.getMainWindow as any).mockReturnValue({ webContents: null });
-
-      callCapture();
-
-      expect(mockApp.storeManager.set).not.toHaveBeenCalled();
-    });
-
-    it('does not throw when reading the URL fails', () => {
-      (mockApp.browserManager.getMainWindow as any).mockReturnValue({
-        webContents: {
-          getURL: () => {
-            throw new Error('boom');
-          },
-        },
-      });
-
-      expect(() => callCapture()).not.toThrow();
-      expect(mockApp.storeManager.set).not.toHaveBeenCalled();
-    });
-  });
-
  describe('installLater', () => {
    it('should set autoInstallOnAppQuit to true', () => {
      updaterManager.installLater();
@@ -95,11 +95,6 @@ const createMockApp = () => {
      }),
    },
    browserManager: {
-      getMainWindow: vi.fn(() => ({
-        broadcast: vi.fn(),
-        loadUrl: vi.fn(),
-        show: vi.fn(),
-      })),
      showMainWindow: vi.fn(),
      retrieveByIdentifier: vi.fn(() => ({
        show: vi.fn(),
@@ -228,9 +223,6 @@ describe('LinuxMenu', () => {

  describe('menu item click handlers', () => {
    it('should handle preferences click', () => {
-      const mainWindow = { broadcast: vi.fn(), loadUrl: vi.fn(), show: vi.fn() };
-      (mockApp.browserManager.getMainWindow as any).mockReturnValue(mainWindow);
-
      linuxMenu.buildAndSetAppMenu();

      const template = (Menu.buildFromTemplate as any).mock.calls[0][0];
@@ -239,9 +231,7 @@ describe('LinuxMenu', () => {

      expect(preferencesItem).toBeDefined();
      preferencesItem.click();
-      expect(mockApp.browserManager.getMainWindow).toHaveBeenCalled();
-      expect(mainWindow.show).toHaveBeenCalled();
-      expect(mainWindow.broadcast).toHaveBeenCalledWith('navigate', { path: '/settings' });
+      expect(mockApp.browserManager.retrieveByIdentifier).toHaveBeenCalledWith('settings');
    });

    it('should handle check for updates click', () => {
@@ -103,11 +103,7 @@ export class LinuxMenu extends BaseMenuPlatform implements IMenuPlatform {
          },
          { type: 'separator' },
          {
-            click: async () => {
-              const mainWindow = this.app.browserManager.getMainWindow();
-              mainWindow.show();
-              mainWindow.broadcast('navigate', { path: '/settings' });
-            },
+            click: () => this.app.browserManager.retrieveByIdentifier('settings').show(),
            label: t('file.preferences'),
          },
          {
@@ -469,11 +465,7 @@ export class LinuxMenu extends BaseMenuPlatform implements IMenuPlatform {
      },
      { type: 'separator' },
      {
-        click: async () => {
-          const mainWindow = this.app.browserManager.getMainWindow();
-          mainWindow.show();
-          mainWindow.broadcast('navigate', { path: '/settings' });
-        },
+        click: () => this.app.browserManager.retrieveByIdentifier('settings').show(),
        label: t('tray.settings'),
      },
      { type: 'separator' },
@@ -205,9 +205,6 @@ describe('WindowsMenu', () => {

  describe('menu item click handlers', () => {
    it('should handle preferences click', () => {
-      const mainWindow = { broadcast: vi.fn(), loadUrl: vi.fn(), show: vi.fn() };
-      (mockApp.browserManager.getMainWindow as any).mockReturnValue(mainWindow);
-
      windowsMenu.buildAndSetAppMenu();

      const template = (Menu.buildFromTemplate as any).mock.calls[0][0];
@@ -216,9 +213,7 @@ describe('WindowsMenu', () => {

      expect(preferencesItem).toBeDefined();
      preferencesItem.click();
-      expect(mockApp.browserManager.getMainWindow).toHaveBeenCalled();
-      expect(mainWindow.show).toHaveBeenCalled();
-      expect(mainWindow.broadcast).toHaveBeenCalledWith('navigate', { path: '/settings' });
+      expect(mockApp.browserManager.retrieveByIdentifier).toHaveBeenCalledWith('settings');
    });

    it('should handle check for updates click', () => {
@@ -102,11 +102,7 @@ export class WindowsMenu extends BaseMenuPlatform implements IMenuPlatform {
          },
          { type: 'separator' },
          {
-            click: async () => {
-              const mainWindow = this.app.browserManager.getMainWindow();
-              mainWindow.show();
-              mainWindow.broadcast('navigate', { path: '/settings' });
-            },
+            click: () => this.app.browserManager.retrieveByIdentifier('settings').show(),
            label: t('file.preferences'),
          },
          this.getUpdateMenuItem(t),
@@ -476,11 +472,7 @@ export class WindowsMenu extends BaseMenuPlatform implements IMenuPlatform {
      },
      { type: 'separator' },
      {
-        click: async () => {
-          const mainWindow = this.app.browserManager.getMainWindow();
-          mainWindow.show();
-          mainWindow.broadcast('navigate', { path: '/settings' });
-        },
+        click: () => this.app.browserManager.retrieveByIdentifier('settings').show(),
        label: t('tray.settings'),
      },
      { type: 'separator' },
@@ -1,10 +1,10 @@
+import type { GrepContentParams, GrepContentResult } from '@lobechat/electron-client-ipc';
 import { beforeEach, describe, expect, it, vi } from 'vitest';

-import type { GrepContentParams, GrepContentResult } from '../../types';
 import { BaseContentSearch } from '../base';

 // Mock logger
-vi.mock('../../logger', () => ({
+vi.mock('@/utils/logger', () => ({
  createLogger: () => ({
    debug: vi.fn(),
    error: vi.fn(),
@@ -143,30 +143,6 @@ describe('BaseContentSearch', () => {
        expect(args).toContain('*.ts');
      });

-      it('should add --hidden when glob references a dot-prefixed segment', () => {
-        const params: GrepContentParams = {
-          glob: '.github/workflows/*.yml',
-          pattern: 'jobs',
-        };
-
-        const args = contentSearch.testBuildGrepArgs('rg', params);
-
-        expect(args).toContain('--hidden');
-        expect(args).toContain('-g');
-        expect(args).toContain('.github/workflows/*.yml');
-      });
-
-      it('should not add --hidden for a normal glob', () => {
-        const params: GrepContentParams = {
-          glob: '*.ts',
-          pattern: 'test',
-        };
-
-        const args = contentSearch.testBuildGrepArgs('rg', params);
-
-        expect(args).not.toContain('--hidden');
-      });
-
      it('should build rg args with type filter', () => {
        const params: GrepContentParams = {
          pattern: 'test',
@@ -229,17 +205,6 @@ describe('BaseContentSearch', () => {
        expect(args).toContain('*.tsx');
      });

-      it('should add --hidden when glob references a dot-prefixed segment', () => {
-        const params: GrepContentParams = {
-          glob: '.github/workflows/*.yml',
-          pattern: 'jobs',
-        };
-
-        const args = contentSearch.testBuildGrepArgs('ag', params);
-
-        expect(args).toContain('--hidden');
-      });
-
      it('should build ag args for count mode', () => {
        const params: GrepContentParams = {
          output_mode: 'count',
@@ -344,13 +309,13 @@ describe('BaseContentSearch', () => {
    });
  });

-  describe('setToolDetector', () => {
+  describe('setToolDetectorManager', () => {
    it('should set the tool detector manager', () => {
      const mockManager = {} as any;

-      contentSearch.setToolDetector(mockManager);
+      contentSearch.setToolDetectorManager(mockManager);

-      expect((contentSearch as any).toolDetector).toBe(mockManager);
+      expect((contentSearch as any).toolDetectorManager).toBe(mockManager);
    });
  });
 });
@@ -13,7 +13,7 @@ vi.mock('node:os', () => ({
 }));

 // Mock logger
-vi.mock('../../logger', () => ({
+vi.mock('@/utils/logger', () => ({
  createLogger: () => ({
    debug: vi.fn(),
    error: vi.fn(),
@@ -55,12 +55,12 @@ describe('createContentSearchImpl', () => {
    expect(impl).toBeInstanceOf(LinuxContentSearchImpl);
  });

-  it('should pass toolDetector to implementation', () => {
+  it('should pass toolDetectorManager to implementation', () => {
    vi.mocked(os.platform).mockReturnValue('linux');
-    const mockDetector = { getBestTool: async () => null } as any;
+    const mockManager = {} as any;

-    const impl = createContentSearchImpl(mockDetector);
+    const impl = createContentSearchImpl(mockManager);

-    expect((impl as any).toolDetector).toBe(mockDetector);
+    expect((impl as any).toolDetectorManager).toBe(mockManager);
  });
 });
@@ -1,75 +1,83 @@
 import { readFile, stat } from 'node:fs/promises';

+import type { GrepContentParams, GrepContentResult } from '@lobechat/electron-client-ipc';
 import fg from 'fast-glob';

-import { createLogger } from '../logger';
-import type { ToolDetector } from '../toolDetector';
-import type { GrepContentParams, GrepContentResult } from '../types';
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';

-const logger = createLogger('contentSearch:base');
+const logger = createLogger('module:ContentSearch:base');

 /**
 * Content search tool type
 */
-export type ContentSearchTool = 'ag' | 'grep' | 'nodejs' | 'rg';
+export type ContentSearchTool = 'rg' | 'ag' | 'grep' | 'nodejs';

 /**
 * Content Search Service Implementation Abstract Class
 * Defines the interface that different platform content search implementations need to implement
 */
 export abstract class BaseContentSearch {
-  protected toolDetector?: ToolDetector;
+  protected toolDetectorManager?: ToolDetectorManager;

-  constructor(toolDetector?: ToolDetector) {
-    this.toolDetector = toolDetector;
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    this.toolDetectorManager = toolDetectorManager;
  }

-  setToolDetector(detector: ToolDetector): void {
-    this.toolDetector = detector;
+  /**
+   * Set the tool detector manager
+   * @param manager ToolDetectorManager instance
+   */
+  setToolDetectorManager(manager: ToolDetectorManager): void {
+    this.toolDetectorManager = manager;
  }

+  /**
+   * Perform content search (grep)
+   * @param params Grep parameters
+   * @returns Promise of grep result
+   */
  abstract grep(params: GrepContentParams): Promise<GrepContentResult>;

+  /**
+   * Check if a specific tool is available
+   * @param tool Tool name to check
+   * @returns Promise indicating if tool is available
+   */
  abstract checkToolAvailable(tool: string): Promise<boolean>;

  /**
   * Resolve the directory to run the search in.
   *
-   * The builtin-tool manifest documents `scope`, while the legacy type also accepts
-   * `path` / `cwd`. Read all so an agent calling with `scope` (per the manifest)
-   * doesn't silently fall through to `process.cwd()` — which in a packaged
-   * Electron app isn't the project root and therefore has no `.gitignore` for
-   * ripgrep to honor.
+   * The builtin-tool manifest documents `scope`, while the legacy IPC type also accepts
+   * `path`. Read both so an agent calling with `scope` (per the manifest) doesn't silently
+   * fall through to `process.cwd()` — which in a packaged Electron app isn't the project
+   * root and therefore has no `.gitignore` for ripgrep to honor.
   */
  protected resolveSearchPath(params: GrepContentParams): string {
-    return params.path ?? params.scope ?? params.cwd ?? process.cwd();
+    return params.path ?? params.scope ?? process.cwd();
  }

  /**
   * Build command-line arguments for grep tools
   */
-  protected buildGrepArgs(tool: 'ag' | 'grep' | 'rg', params: GrepContentParams): string[] {
+  protected buildGrepArgs(tool: 'rg' | 'ag' | 'grep', params: GrepContentParams): string[] {
    const { pattern, output_mode = 'files_with_matches' } = params;
    const args: string[] = [];

-    // When the caller's glob references a dot-prefixed segment (e.g.
-    // `.github/workflows/*.yml`), rg and ag both default to skipping hidden
-    // paths and would silently return zero results. `.git/` is still excluded
-    // explicitly below.
-    const wantsHidden = !!params.glob && /(?:^|\/)\.[^./]/.test(params.glob);
-
    switch (tool) {
      case 'rg': {
+        // ripgrep arguments
        if (params['-i']) args.push('-i');
        if (params['-n']) args.push('-n');
        if (params['-A']) args.push('-A', String(params['-A']));
        if (params['-B']) args.push('-B', String(params['-B']));
        if (params['-C']) args.push('-C', String(params['-C']));
        if (params.multiline) args.push('-U');
-        if (wantsHidden) args.push('--hidden');
        if (params.glob) args.push('-g', params.glob);
        if (params.type) args.push('-t', params.type);

+        // Output mode
        switch (output_mode) {
          case 'files_with_matches': {
            args.push('-l');
@@ -81,18 +89,20 @@ export abstract class BaseContentSearch {
          }
        }

+        // Ignore common directories (use **/ prefix to match nested paths)
        args.push('--glob', '!**/node_modules/**', '--glob', '!**/.git/**', pattern, '.');
        break;
      }

      case 'ag': {
+        // Silver Searcher arguments
        if (params['-i']) args.push('-i');
        if (params['-A']) args.push('-A', String(params['-A']));
        if (params['-B']) args.push('-B', String(params['-B']));
        if (params['-C']) args.push('-C', String(params['-C']));
-        if (wantsHidden) args.push('--hidden');
        if (params.glob) args.push('-G', params.glob);

+        // Output mode
        switch (output_mode) {
          case 'files_with_matches': {
            args.push('-l');
@@ -109,7 +119,8 @@ export abstract class BaseContentSearch {
      }

      case 'grep': {
-        args.push('-r');
+        // GNU grep arguments
+        args.push('-r'); // recursive
        if (params['-i']) args.push('-i');
        if (params['-n']) args.push('-n');
        if (params['-A']) args.push('-A', String(params['-A']));
@@ -118,6 +129,7 @@ export abstract class BaseContentSearch {
        if (params.glob) args.push('--include', params.glob);
        if (params.type) args.push('--include', `*.${params.type}`);

+        // Output mode
        switch (output_mode) {
          case 'files_with_matches': {
            args.push('-l');
@@ -148,12 +160,14 @@ export abstract class BaseContentSearch {
    const flags = `${params['-i'] ? 'i' : ''}${params.multiline ? 's' : ''}`;
    const regex = new RegExp(pattern, flags);

+    // Determine files to search
    let filesToSearch: string[];
    const stats = await stat(searchPath);

    if (stats.isFile()) {
      filesToSearch = [searchPath];
    } else {
+      // Use glob pattern if provided, otherwise search all files
      let globPattern = params.glob || '**/*';
      if (params.glob && !params.glob.includes('/') && !params.glob.startsWith('**')) {
        globPattern = `**/${params.glob}`;
@@ -166,6 +180,7 @@ export abstract class BaseContentSearch {
        ignore: this.getDefaultIgnorePatterns(),
      });

+      // Filter by type if provided
      if (params.type) {
        const ext = `.${params.type}`;
        filesToSearch = filesToSearch.filter((file) => file.endsWith(ext));
@@ -1,19 +1,23 @@
-import { createLogger } from '../../logger';
-import type { ToolDetector } from '../../toolDetector';
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';
+
 import { UnixContentSearch } from './unix';

-const logger = createLogger('contentSearch:linux');
+const logger = createLogger('module:ContentSearch:linux');

 /**
 * Linux content search implementation
 * Inherits from UnixContentSearch with Linux-specific optimizations
 */
 export class LinuxContentSearchImpl extends UnixContentSearch {
-  constructor(toolDetector?: ToolDetector) {
-    super(toolDetector);
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    super(toolDetectorManager);
    logger.debug('LinuxContentSearchImpl initialized');
  }

+  /**
+   * Get Linux-specific ignore patterns
+   */
  protected override getDefaultIgnorePatterns(): string[] {
    return [...super.getDefaultIgnorePatterns(), '**/.cache/**', '**/snap/**'];
  }
@@ -1,19 +1,24 @@
-import { createLogger } from '../../logger';
-import type { ToolDetector } from '../../toolDetector';
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';
+
 import { UnixContentSearch } from './unix';

-const logger = createLogger('contentSearch:macOS');
+const logger = createLogger('module:ContentSearch:macOS');

 /**
 * macOS content search implementation
 * Inherits from UnixContentSearch with macOS-specific optimizations
 */
 export class MacOSContentSearchImpl extends UnixContentSearch {
-  constructor(toolDetector?: ToolDetector) {
-    super(toolDetector);
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    super(toolDetectorManager);
    logger.debug('MacOSContentSearchImpl initialized');
  }

+  /**
+   * Get macOS-specific ignore patterns
+   * Includes Library/Caches which is specific to macOS
+   */
  protected override getDefaultIgnorePatterns(): string[] {
    return [
      ...super.getDefaultIgnorePatterns(),
@@ -1,29 +1,38 @@
+import type { GrepContentParams, GrepContentResult } from '@lobechat/electron-client-ipc';
 import { execa } from 'execa';

-import { createLogger } from '../../logger';
-import type { ToolDetector } from '../../toolDetector';
-import type { GrepContentParams, GrepContentResult } from '../../types';
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';
+
 import { BaseContentSearch } from '../base';

-const logger = createLogger('contentSearch:unix');
+const logger = createLogger('module:ContentSearch:unix');

 /**
 * Unix content search tool type
 * Priority: rg (1) > ag (2) > grep (3)
 */
-export type UnixContentSearchTool = 'ag' | 'grep' | 'nodejs' | 'rg';
+export type UnixContentSearchTool = 'rg' | 'ag' | 'grep' | 'nodejs';

 /**
 * Unix content search base class
 * Provides common search implementations for macOS and Linux
 */
 export abstract class UnixContentSearch extends BaseContentSearch {
+  /**
+   * Current tool being used
+   */
  protected currentTool: UnixContentSearchTool | null = null;

-  constructor(toolDetector?: ToolDetector) {
-    super(toolDetector);
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    super(toolDetectorManager);
  }

+  /**
+   * Check if a tool is available using 'which' command
+   * @param tool Tool name to check
+   * @returns Promise indicating if tool is available
+   */
  async checkToolAvailable(tool: string): Promise<boolean> {
    try {
      await execa('which', [tool], { timeout: 3000 });
@@ -33,9 +42,14 @@ export abstract class UnixContentSearch extends BaseContentSearch {
    }
  }

+  /**
+   * Determine the best available Unix tool based on priority
+   * Priority: rg > ag > grep > nodejs
+   * @returns The best available tool
+   */
  protected async determineBestUnixTool(): Promise<UnixContentSearchTool> {
-    if (this.toolDetector) {
-      const bestTool = await this.toolDetector.getBestTool('content-search');
+    if (this.toolDetectorManager) {
+      const bestTool = await this.toolDetectorManager.getBestTool('content-search');
      if (bestTool && ['rg', 'ag', 'grep'].includes(bestTool)) {
        return bestTool as UnixContentSearchTool;
      }
@@ -56,6 +70,11 @@ export abstract class UnixContentSearch extends BaseContentSearch {
    return 'nodejs';
  }

+  /**
+   * Fallback to the next available tool
+   * @param currentTool Current tool that failed
+   * @returns Next tool to try
+   */
  protected async fallbackToNextTool(
    currentTool: UnixContentSearchTool,
  ): Promise<UnixContentSearchTool> {
@@ -65,7 +84,7 @@ export abstract class UnixContentSearch extends BaseContentSearch {
    for (let i = currentIndex + 1; i < priority.length; i++) {
      const nextTool = priority[i];
      if (nextTool === 'nodejs') {
-        return 'nodejs';
+        return 'nodejs'; // Always available
      }
      if (await this.checkToolAvailable(nextTool)) {
        return nextTool;
@@ -75,16 +94,21 @@ export abstract class UnixContentSearch extends BaseContentSearch {
    return 'nodejs';
  }

+  /**
+   * Perform content search (grep)
+   */
  async grep(params: GrepContentParams): Promise<GrepContentResult> {
    const { tool: preferredTool } = params;
    const logPrefix = `[grepContent: ${params.pattern}]`;

    try {
+      // If user specified a grep tool, try to use it
      if (preferredTool && ['rg', 'ag', 'grep'].includes(preferredTool)) {
        logger.debug(`${logPrefix} Using preferred tool: ${preferredTool}`);
        return this.grepWithTool(preferredTool as UnixContentSearchTool, params);
      }

+      // Determine the best available tool on first search
      if (this.currentTool === null) {
        this.currentTool = await this.determineBestUnixTool();
        logger.info(`Using content search tool: ${this.currentTool}`);
@@ -103,6 +127,9 @@ export abstract class UnixContentSearch extends BaseContentSearch {
    }
  }

+  /**
+   * Search using the specified tool
+   */
  protected async grepWithTool(
    tool: UnixContentSearchTool,
    params: GrepContentParams,
@@ -123,20 +150,32 @@ export abstract class UnixContentSearch extends BaseContentSearch {
    }
  }

+  /**
+   * Grep using ripgrep (rg)
+   */
  protected async grepWithRipgrep(params: GrepContentParams): Promise<GrepContentResult> {
    return this.grepWithExternalTool('rg', params);
  }

+  /**
+   * Grep using The Silver Searcher (ag)
+   */
  protected async grepWithAg(params: GrepContentParams): Promise<GrepContentResult> {
    return this.grepWithExternalTool('ag', params);
  }

+  /**
+   * Grep using GNU grep
+   */
  protected async grepWithGrep(params: GrepContentParams): Promise<GrepContentResult> {
    return this.grepWithExternalTool('grep', params);
  }

+  /**
+   * Grep using external tools (rg, ag, grep)
+   */
  protected async grepWithExternalTool(
-    tool: 'ag' | 'grep' | 'rg',
+    tool: 'rg' | 'ag' | 'grep',
    params: GrepContentParams,
  ): Promise<GrepContentResult> {
    const { output_mode = 'files_with_matches' } = params;
@@ -149,9 +188,10 @@ export abstract class UnixContentSearch extends BaseContentSearch {

      const { stdout, stderr, exitCode } = await execa(tool, args, {
        cwd: searchPath,
-        reject: false,
+        reject: false, // Don't throw on non-zero exit code
      });

+      // ripgrep returns 1 when no matches found, which is not an error
      if (exitCode !== 0 && exitCode !== 1 && stderr) {
        logger.warn(`${logPrefix} Tool exited with code ${exitCode}: ${stderr}`);
      }
@@ -168,8 +208,11 @@ export abstract class UnixContentSearch extends BaseContentSearch {
        }
        case 'content': {
          matches = lines;
+          // When context lines are used, lines.length includes context lines
+          // We need to get the actual match count separately
          const hasContext = params['-A'] || params['-B'] || params['-C'];
          if (hasContext) {
+            // Run a separate count query to get accurate match count
            totalMatches = await this.getActualMatchCount(tool, params);
          } else {
            totalMatches = lines.length;
@@ -177,6 +220,7 @@ export abstract class UnixContentSearch extends BaseContentSearch {
          break;
        }
        case 'count': {
+          // Parse count output (file:count format)
          for (const line of lines) {
            const match = line.match(/:(\d+)$/);
            if (match) {
@@ -188,6 +232,7 @@ export abstract class UnixContentSearch extends BaseContentSearch {
        }
      }

+      // Apply head_limit
      if (params.head_limit && matches.length > params.head_limit) {
        matches = matches.slice(0, params.head_limit);
      }
@@ -205,14 +250,18 @@ export abstract class UnixContentSearch extends BaseContentSearch {
      };
    } catch (error) {
      logger.warn(`${logPrefix} External tool failed, falling back to next tool:`, error);
+      // Fallback to next tool
      this.currentTool = await this.fallbackToNextTool(tool as UnixContentSearchTool);
      logger.info(`Falling back to: ${this.currentTool}`);
      return this.grepWithTool(this.currentTool, params);
    }
  }

+  /**
+   * Get actual match count for content mode when context lines are used
+   */
  protected async getActualMatchCount(
-    tool: 'ag' | 'grep' | 'rg',
+    tool: 'rg' | 'ag' | 'grep',
    params: GrepContentParams,
  ): Promise<number> {
    const countParams = { ...params, '-A': undefined, '-B': undefined, '-C': undefined };
@@ -1,30 +1,39 @@
+import type { GrepContentParams, GrepContentResult } from '@lobechat/electron-client-ipc';
 import { execa } from 'execa';

-import { createLogger } from '../../logger';
-import type { ToolDetector } from '../../toolDetector';
-import type { GrepContentParams, GrepContentResult } from '../../types';
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';
+
 import { BaseContentSearch } from '../base';

-const logger = createLogger('contentSearch:windows');
+const logger = createLogger('module:ContentSearch:windows');

 /**
 * Windows content search tool type
 * Priority: rg > findstr/powershell > nodejs
 */
-type WindowsContentSearchTool = 'findstr' | 'nodejs' | 'rg';
+type WindowsContentSearchTool = 'rg' | 'findstr' | 'nodejs';

 /**
 * Windows content search implementation
 * Uses rg > findstr > nodejs fallback strategy
 */
 export class WindowsContentSearchImpl extends BaseContentSearch {
+  /**
+   * Current tool being used
+   */
  private currentTool: WindowsContentSearchTool | null = null;

-  constructor(toolDetector?: ToolDetector) {
-    super(toolDetector);
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    super(toolDetectorManager);
    logger.debug('WindowsContentSearchImpl initialized');
  }

+  /**
+   * Check if a tool is available using 'where' command (Windows equivalent of 'which')
+   * @param tool Tool name to check
+   * @returns Promise indicating if tool is available
+   */
  async checkToolAvailable(tool: string): Promise<boolean> {
    try {
      await execa('where', [tool], { timeout: 3000 });
@@ -34,9 +43,13 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    }
  }

+  /**
+   * Determine the best available tool based on priority
+   * Priority: rg > findstr > nodejs
+   */
  private async determineBestTool(): Promise<WindowsContentSearchTool> {
-    if (this.toolDetector) {
-      const bestTool = await this.toolDetector.getBestTool('content-search');
+    if (this.toolDetectorManager) {
+      const bestTool = await this.toolDetectorManager.getBestTool('content-search');
      if (bestTool === 'rg') {
        return 'rg';
      }
@@ -50,6 +63,9 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    return 'findstr';
  }

+  /**
+   * Fallback to the next available tool
+   */
  private async fallbackToNextTool(
    currentTool: WindowsContentSearchTool,
  ): Promise<WindowsContentSearchTool> {
@@ -59,7 +75,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    for (let i = currentIndex + 1; i < priority.length; i++) {
      const nextTool = priority[i];
      if (nextTool === 'nodejs' || nextTool === 'findstr') {
-        return nextTool;
+        return nextTool; // Always available
      }
      if (await this.checkToolAvailable(nextTool)) {
        return nextTool;
@@ -69,11 +85,15 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    return 'nodejs';
  }

+  /**
+   * Perform content search (grep)
+   */
  async grep(params: GrepContentParams): Promise<GrepContentResult> {
    const { tool: preferredTool } = params;
    const logPrefix = `[grepContent: ${params.pattern}]`;

    try {
+      // If user specified ripgrep, try to use it
      if (preferredTool === 'rg') {
        if (await this.checkToolAvailable('rg')) {
          logger.debug(`${logPrefix} Using preferred tool: rg`);
@@ -82,6 +102,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
        logger.warn(`${logPrefix} ripgrep (rg) not available, falling back to other tools`);
      }

+      // Determine the best available tool on first search
      if (this.currentTool === null) {
        this.currentTool = await this.determineBestTool();
        logger.info(`Using content search tool: ${this.currentTool}`);
@@ -100,6 +121,9 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    }
  }

+  /**
+   * Search using the specified tool
+   */
  private async grepWithTool(
    tool: WindowsContentSearchTool,
    params: GrepContentParams,
@@ -117,6 +141,9 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    }
  }

+  /**
+   * Grep using ripgrep (rg) - cross-platform
+   */
  private async grepWithRipgrep(params: GrepContentParams): Promise<GrepContentResult> {
    const { output_mode = 'files_with_matches' } = params;
    const searchPath = this.resolveSearchPath(params);
@@ -131,6 +158,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
        reject: false,
      });

+      // ripgrep returns 1 when no matches found, which is not an error
      if (exitCode !== 0 && exitCode !== 1 && stderr) {
        logger.warn(`${logPrefix} rg exited with code ${exitCode}: ${stderr}`);
      }
@@ -167,6 +195,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
        }
      }

+      // Apply head_limit
      if (params.head_limit && matches.length > params.head_limit) {
        matches = matches.slice(0, params.head_limit);
      }
@@ -189,6 +218,9 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    }
  }

+  /**
+   * Get actual match count using ripgrep
+   */
  private async getActualMatchCount(params: GrepContentParams): Promise<number> {
    const countParams = { ...params, '-A': undefined, '-B': undefined, '-C': undefined };
    const args = this.buildGrepArgs('rg', {
@@ -215,25 +247,31 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    }
  }

+  /**
+   * Grep using Windows findstr command
+   * Note: findstr has limited functionality compared to ripgrep
+   */
  private async grepWithFindstr(params: GrepContentParams): Promise<GrepContentResult> {
    const { pattern, output_mode = 'files_with_matches' } = params;
    const searchPath = this.resolveSearchPath(params);
    const logPrefix = `[grepContent:findstr]`;

    try {
-      const args: string[] = ['/S'];
+      const args: string[] = ['/S']; // Recursive search

      if (params['-i']) {
-        args.push('/I');
+        args.push('/I'); // Case insensitive
      }

      if (params['-n']) {
-        args.push('/N');
+        args.push('/N'); // Line numbers
      }

-      args.push('/R');
+      // Pattern
+      args.push('/R'); // Regex
      args.push(`"${pattern}"`);

+      // Search files pattern
      const filePattern = params.glob || params.type ? `*.${params.type || '*'}` : '*.*';
      args.push(filePattern);

@@ -244,6 +282,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
        reject: false,
      });

+      // findstr returns 1 when no matches found
      if (exitCode !== 0 && exitCode !== 1) {
        logger.warn(`${logPrefix} findstr exited with code ${exitCode}`);
      }
@@ -254,6 +293,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {

      switch (output_mode) {
        case 'files_with_matches': {
+          // Extract unique file names from output
          const files = new Set<string>();
          for (const line of lines) {
            const match = line.match(/^([^:]+):/);
@@ -261,7 +301,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
              files.add(match[1]);
            }
          }
-          matches = [...files];
+          matches = Array.from(files);
          totalMatches = matches.length;
          break;
        }
@@ -271,6 +311,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
          break;
        }
        case 'count': {
+          // Count matches per file
          const fileCounts = new Map<string, number>();
          for (const line of lines) {
            const match = line.match(/^([^:]+):/);
@@ -278,12 +319,13 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
              fileCounts.set(match[1], (fileCounts.get(match[1]) || 0) + 1);
            }
          }
-          matches = [...fileCounts.entries()].map(([file, count]) => `${file}:${count}`);
+          matches = Array.from(fileCounts.entries()).map(([file, count]) => `${file}:${count}`);
          totalMatches = lines.length;
          break;
        }
      }

+      // Apply head_limit
      if (params.head_limit && matches.length > params.head_limit) {
        matches = matches.slice(0, params.head_limit);
      }
@@ -306,6 +348,9 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
    }
  }

+  /**
+   * Get Windows-specific ignore patterns
+   */
  protected override getDefaultIgnorePatterns(): string[] {
    return [
      ...super.getDefaultIgnorePatterns(),
@@ -1,6 +1,7 @@
 import * as os from 'node:os';

-import type { ToolDetector } from '../toolDetector';
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+
 import type { BaseContentSearch } from './base';
 import { LinuxContentSearchImpl } from './impl/linux';
 import { MacOSContentSearchImpl } from './impl/macOS';
@@ -14,19 +15,24 @@ export { WindowsContentSearchImpl } from './impl/windows';

 /**
 * Create platform-specific content search implementation
+ * @param toolDetectorManager Optional tool detector manager
+ * @returns Platform-specific content search implementation
 */
-export function createContentSearchImpl(toolDetector?: ToolDetector): BaseContentSearch {
+export function createContentSearchImpl(
+  toolDetectorManager?: ToolDetectorManager,
+): BaseContentSearch {
  const platform = os.platform();

  switch (platform) {
    case 'darwin': {
-      return new MacOSContentSearchImpl(toolDetector);
+      return new MacOSContentSearchImpl(toolDetectorManager);
    }
    case 'win32': {
-      return new WindowsContentSearchImpl(toolDetector);
+      return new WindowsContentSearchImpl(toolDetectorManager);
    }
    default: {
-      return new LinuxContentSearchImpl(toolDetector);
+      // Linux and other Unix-like systems
+      return new LinuxContentSearchImpl(toolDetectorManager);
    }
  }
 }
@@ -1,10 +1,11 @@
+import type { GlobFilesParams, GlobFilesResult } from '@lobechat/electron-client-ipc';
 import { beforeEach, describe, expect, it, vi } from 'vitest';

-import type { FileResult, GlobFilesParams, GlobFilesResult, SearchOptions } from '../../types';
 import { BaseFileSearch } from '../base';
+import type { FileResult, SearchOptions } from '../types';

 // Mock logger
-vi.mock('../../logger', () => ({
+vi.mock('@/utils/logger', () => ({
  createLogger: () => ({
    debug: vi.fn(),
    error: vi.fn(),
@@ -278,13 +279,13 @@ describe('BaseFileSearch', () => {
    });
  });

-  describe('setToolDetector', () => {
+  describe('setToolDetectorManager', () => {
    it('should set the tool detector manager', () => {
      const mockManager = {} as any;

-      fileSearch.setToolDetector(mockManager);
+      fileSearch.setToolDetectorManager(mockManager);

-      expect((fileSearch as any).toolDetector).toBe(mockManager);
+      expect((fileSearch as any).toolDetectorManager).toBe(mockManager);
    });
  });

@@ -14,7 +14,7 @@ vi.mock('node:os', () => ({
 }));

 // Mock logger
-vi.mock('../../logger', () => ({
+vi.mock('@/utils/logger', () => ({
  createLogger: () => ({
    debug: vi.fn(),
    error: vi.fn(),
@@ -56,12 +56,12 @@ describe('createFileSearchModule', () => {
    expect(impl).toBeInstanceOf(LinuxSearchServiceImpl);
  });

-  it('should pass toolDetector to implementation', () => {
+  it('should pass toolDetectorManager to implementation', () => {
    vi.mocked(platform).mockReturnValue('linux');
-    const mockDetector = { getBestTool: async () => null } as any;
+    const mockManager = {} as any;

-    const impl = createFileSearchModule(mockDetector);
+    const impl = createFileSearchModule(mockManager);

-    expect((impl as any).toolDetector).toBe(mockDetector);
+    expect((impl as any).toolDetectorManager).toBe(mockManager);
  });
 });
@@ -20,14 +20,14 @@ describe.skipIf(process.platform !== 'darwin')('MacOSSearchServiceImpl Integrati
  const searchService = new MacOSSearchServiceImpl();
  const ensureResults = (results: unknown[], context: string) => {
    if (results.length > 0) return true;
-
+     
    console.warn(`⚠️  Spotlight returned 0 results for ${context} - indexing may be incomplete`);
    return false;
  };

  const ensureResultsOrSkipAssertions = (results: unknown[], hint: string) => {
    if (results.length > 0) return true;
-
+     
    console.warn(
      `⚠️  Spotlight returned 0 results for "${hint}". This usually means indexing is incomplete/disabled. Skipping strict assertions.`,
    );
@@ -107,6 +107,7 @@ describe.skipIf(process.platform !== 'darwin')('MacOSSearchServiceImpl Integrati
          expect(result.path).toContain('apps/desktop');
        });
      } else {
+         
        console.warn(
          '⚠️  No results found in apps/desktop - Spotlight indexing may not be complete',
        );
@@ -372,5 +373,6 @@ describe.skipIf(process.platform !== 'darwin')('MacOSSearchServiceImpl Integrati

 // Skip message for non-macOS platforms
 if (process.platform !== 'darwin') {
+   
  console.log('⏭️  Skipping macOS integration tests on', process.platform, '(only runs on darwin)');
 }
@@ -2,7 +2,7 @@ import { describe, expect, it, vi } from 'vitest';

 import { buildFilenameKeywordExpression } from '../impl/macOS';

-vi.mock('../../logger', () => ({
+vi.mock('@/utils/logger', () => ({
  createLogger: () => ({
    debug: vi.fn(),
    error: vi.fn(),
@@ -7,7 +7,7 @@ vi.mock('node:os', () => ({
  platform: vi.fn().mockReturnValue('linux'),
 }));

-vi.mock('../../logger', () => ({
+vi.mock('@/utils/logger', () => ({
  createLogger: () => ({
    debug: vi.fn(),
    error: vi.fn(),
@@ -1,67 +1,79 @@
 import { stat } from 'node:fs/promises';
 import path from 'node:path';

-import type { ToolDetector } from '../toolDetector';
-import type { FileResult, GlobFilesParams, GlobFilesResult, SearchFilesParams } from '../types';
+import type { GlobFilesParams, GlobFilesResult } from '@lobechat/electron-client-ipc';
+
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+
+import type { FileResult, SearchOptions } from './types';

 /**
 * Content type mapping for common file extensions
 */
 const CONTENT_TYPE_MAP: Record<string, string> = {
+  // Archive
  '7z': 'archive',
+  'gz': 'archive',
+  'rar': 'archive',
+  'tar': 'archive',
+  'zip': 'archive',
+  // Audio
  'aac': 'audio',
-  'app': 'application',
+  'mp3': 'audio',
+  'ogg': 'audio',
+  'wav': 'audio',
+  // Video
  'avi': 'video',
+  'mkv': 'video',
+  'mov': 'video',
+  'mp4': 'video',
+  // Image
+  'gif': 'image',
+  'heic': 'image',
+  'ico': 'image',
+  'jpeg': 'image',
+  'jpg': 'image',
+  'png': 'image',
+  'svg': 'image',
+  'webp': 'image',
+  // Document
+  'doc': 'document',
+  'docx': 'document',
+  'pdf': 'document',
+  'rtf': 'text',
+  'txt': 'text',
+  // Spreadsheet
+  'xls': 'spreadsheet',
+  'xlsx': 'spreadsheet',
+  // Presentation
+  'ppt': 'presentation',
+  'pptx': 'presentation',
+  // Code
  'bat': 'code',
  'c': 'code',
  'cmd': 'code',
  'cpp': 'code',
  'cs': 'code',
  'css': 'code',
-  'deb': 'package',
-  'dmg': 'disk-image',
-  'doc': 'document',
-  'docx': 'document',
-  'exe': 'application',
-  'gif': 'image',
-  'gz': 'archive',
-  'heic': 'image',
  'html': 'code',
-  'ico': 'image',
-  'iso': 'disk-image',
  'java': 'code',
-  'jpeg': 'image',
-  'jpg': 'image',
  'js': 'code',
  'json': 'code',
-  'mkv': 'video',
-  'mov': 'video',
-  'mp3': 'audio',
-  'mp4': 'video',
-  'msi': 'installer',
-  'ogg': 'audio',
-  'pdf': 'document',
-  'png': 'image',
-  'ppt': 'presentation',
-  'pptx': 'presentation',
  'ps1': 'code',
  'py': 'code',
-  'rar': 'archive',
-  'rpm': 'package',
-  'rtf': 'text',
  'sh': 'code',
-  'svg': 'image',
  'swift': 'code',
-  'tar': 'archive',
  'ts': 'code',
  'tsx': 'code',
-  'txt': 'text',
  'vbs': 'code',
-  'wav': 'audio',
-  'webp': 'image',
-  'xls': 'spreadsheet',
-  'xlsx': 'spreadsheet',
-  'zip': 'archive',
+  // Application/Installer (platform-specific)
+  'app': 'application',
+  'deb': 'package',
+  'dmg': 'disk-image',
+  'exe': 'application',
+  'iso': 'disk-image',
+  'msi': 'installer',
+  'rpm': 'package',
 };

 /**
@@ -69,22 +81,33 @@ const CONTENT_TYPE_MAP: Record<string, string> = {
 * Defines the interface that different platform file search implementations need to implement
 */
 export abstract class BaseFileSearch {
-  protected toolDetector?: ToolDetector;
+  protected toolDetectorManager?: ToolDetectorManager;

-  constructor(toolDetector?: ToolDetector) {
-    this.toolDetector = toolDetector;
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    this.toolDetectorManager = toolDetectorManager;
  }

-  setToolDetector(detector: ToolDetector): void {
-    this.toolDetector = detector;
+  /**
+   * Set the tool detector manager
+   * @param manager ToolDetectorManager instance
+   */
+  setToolDetectorManager(manager: ToolDetectorManager): void {
+    this.toolDetectorManager = manager;
  }

+  /**
+   * Determine content type from file extension
+   * @param extension File extension (without dot)
+   * @returns Content type description
+   */
  protected determineContentType(extension: string): string {
    return CONTENT_TYPE_MAP[extension.toLowerCase()] || 'unknown';
  }

  /**
   * Escape special glob characters in the search pattern
+   * @param pattern The pattern to escape
+   * @returns Escaped pattern safe for glob matching
   */
  protected escapeGlobPattern(pattern: string): string {
    return pattern.replaceAll(/[$()*+.?[\\\]^{|}]/g, '\\$&');
@@ -92,10 +115,14 @@ export abstract class BaseFileSearch {

  /**
   * Process file paths and return FileResult objects
+   * @param filePaths Array of file path strings
+   * @param options Search options
+   * @param engine Optional search engine identifier
+   * @returns Formatted file result list
   */
  protected async processFilePaths(
    filePaths: string[],
-    options: SearchFilesParams,
+    options: SearchOptions,
    engine?: string,
  ): Promise<FileResult[]> {
    const results: FileResult[] = [];
@@ -126,9 +153,16 @@ export abstract class BaseFileSearch {
    return this.sortResults(results, options.sortBy, options.sortDirection);
  }

+  /**
+   * Sort results based on options
+   * @param results Result list
+   * @param sortBy Sort field
+   * @param direction Sort direction
+   * @returns Sorted result list
+   */
  protected sortResults(
    results: FileResult[],
-    sortBy?: 'date' | 'name' | 'size',
+    sortBy?: 'name' | 'date' | 'size',
    direction: 'asc' | 'desc' = 'asc',
  ): FileResult[] {
    if (!sortBy) return results;
@@ -153,11 +187,30 @@ export abstract class BaseFileSearch {
    });
  }

-  abstract search(options: SearchFilesParams): Promise<FileResult[]>;
+  /**
+   * Perform file search
+   * @param options Search options
+   * @returns Promise of search result list
+   */
+  abstract search(options: SearchOptions): Promise<FileResult[]>;

+  /**
+   * Perform glob pattern matching
+   * @param params Glob parameters
+   * @returns Promise of glob result
+   */
  abstract glob(params: GlobFilesParams): Promise<GlobFilesResult>;

+  /**
+   * Check search service status
+   * @returns Promise indicating if service is available
+   */
  abstract checkSearchServiceStatus(): Promise<boolean>;

+  /**
+   * Update search index
+   * @param path Optional specified path
+   * @returns Promise indicating operation success
+   */
  abstract updateSearchIndex(path?: string): Promise<boolean>;
 }
@@ -0,0 +1,52 @@
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';
+
+import type { FileResult, SearchOptions } from '../types';
+import type { UnixSearchTool } from './unix';
+import { UnixFileSearch } from './unix';
+
+const logger = createLogger('module:FileSearch:linux');
+
+/**
+ * Linux file search implementation
+ * Uses fd > find > fast-glob fallback strategy
+ */
+export class LinuxSearchServiceImpl extends UnixFileSearch {
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    super(toolDetectorManager);
+  }
+
+  /**
+   * Perform file search
+   * @param options Search options
+   * @returns Promise of search result list
+   */
+  async search(options: SearchOptions): Promise<FileResult[]> {
+    // Determine the best available tool on first search
+    if (this.currentTool === null) {
+      this.currentTool = await this.determineBestUnixTool();
+      logger.info(`Using file search tool: ${this.currentTool}`);
+    }
+
+    return this.searchWithUnixTool(this.currentTool as UnixSearchTool, options);
+  }
+
+  /**
+   * Check search service status
+   * @returns Promise indicating if service is available (always true for Linux)
+   */
+  async checkSearchServiceStatus(): Promise<boolean> {
+    // At minimum, fast-glob is always available
+    return true;
+  }
+
+  /**
+   * Update search index
+   * Linux doesn't have a system-wide search index like Spotlight
+   * @returns Promise indicating operation result (always false for Linux)
+   */
+  async updateSearchIndex(): Promise<boolean> {
+    logger.warn('updateSearchIndex is not supported on Linux (no system-wide index)');
+    return false;
+  }
+}
@@ -4,12 +4,14 @@ import path from 'node:path';

 import { execa } from 'execa';

-import { createLogger } from '../../logger';
-import type { ToolDetector } from '../../toolDetector';
-import type { FileResult, SearchFilesParams } from '../../types';
-import { UnixFileSearch, type UnixSearchTool } from './unix';
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';

-const logger = createLogger('fileSearch:macOS');
+import type { FileResult, SearchOptions } from '../types';
+import type { UnixSearchTool } from './unix';
+import { UnixFileSearch } from './unix';
+
+const logger = createLogger('module:FileSearch:macOS');

 /**
 * Build the kMDItemFSName expression for a free-form keyword string.
@@ -17,6 +19,8 @@ const logger = createLogger('fileSearch:macOS');
 * Splits on whitespace and ANDs each token as a case/diacritic-insensitive
 * substring match, so "Foo Bar" matches both `Bar_Foo.pdf` and `Foo Bar.pdf`
 * — instead of requiring the literal phrase "Foo Bar" to appear.
+ *
+ * Returns an empty string when the keywords contain no usable token.
 */
 export const buildFilenameKeywordExpression = (keywords: string): string => {
  const tokens = keywords
@@ -39,14 +43,28 @@ export const buildFilenameKeywordExpression = (keywords: string): string => {
 type MacOSSearchTool = 'mdfind' | UnixSearchTool;

 export class MacOSSearchServiceImpl extends UnixFileSearch {
+  /**
+   * Cache for Spotlight availability status
+   * null = not checked, true = available, false = not available
+   */
  private spotlightAvailable: boolean | null = null;
+
+  /**
+   * Current tool being used (macOS specific, includes mdfind)
+   */
  private macOSCurrentTool: MacOSSearchTool | null = null;

-  constructor(toolDetector?: ToolDetector) {
-    super(toolDetector);
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    super(toolDetectorManager);
  }

-  async search(options: SearchFilesParams): Promise<FileResult[]> {
+  /**
+   * Perform file search
+   * @param options Search options
+   * @returns Promise of search result list
+   */
+  async search(options: SearchOptions): Promise<FileResult[]> {
+    // Determine the best available tool on first search
    if (this.macOSCurrentTool === null) {
      this.macOSCurrentTool = await this.determineBestTool();
      logger.info(`Using file search tool: ${this.macOSCurrentTool}`);
@@ -55,9 +73,13 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    return this.searchWithTool(this.macOSCurrentTool, options);
  }

+  /**
+   * Determine the best available tool based on priority
+   * Priority: mdfind > fd > find > fast-glob
+   */
  private async determineBestTool(): Promise<MacOSSearchTool> {
-    if (this.toolDetector) {
-      const bestTool = await this.toolDetector.getBestTool('file-search');
+    if (this.toolDetectorManager) {
+      const bestTool = await this.toolDetectorManager.getBestTool('file-search');
      if (bestTool && ['mdfind', 'fd', 'find'].includes(bestTool)) {
        return bestTool as MacOSSearchTool;
      }
@@ -67,26 +89,40 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
      return 'mdfind';
    }

+    // Fallback to Unix tool detection
    return this.determineBestUnixTool();
  }

+  /**
+   * Search using the specified tool
+   */
  private async searchWithTool(
    tool: MacOSSearchTool,
-    options: SearchFilesParams,
+    options: SearchOptions,
  ): Promise<FileResult[]> {
    if (tool === 'mdfind') {
      return this.searchWithSpotlight(options);
    }
+    // Use parent class Unix tool implementation
    return this.searchWithUnixTool(tool, options);
  }

+  /**
+   * Fallback to the next available tool (macOS specific)
+   */
  private async fallbackFromMdfind(): Promise<MacOSSearchTool> {
    return this.determineBestUnixTool();
  }

-  private async searchWithSpotlight(options: SearchFilesParams): Promise<FileResult[]> {
+  /**
+   * Search using Spotlight (mdfind)
+   */
+  private async searchWithSpotlight(options: SearchOptions): Promise<FileResult[]> {
    const { cmd, args, commandString, hasQuery } = this.buildSearchCommand(options);

+    // Spotlight (mdfind) requires a query expression; running it with only flags
+    // (e.g. -onlyin) makes mdfind print its usage to stdout and we'd treat each
+    // line as a fake file. Short-circuit to an empty result instead.
    if (!hasQuery) {
      logger.warn('Skipping mdfind: no keywords/contentContains/fileTypes/date filter provided');
      return [];
@@ -110,6 +146,7 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
        .split('\n')
        .filter((line) => line.trim());

+      // If exited with error code and we have stderr and no results, fallback
      if (exitCode !== 0 && stderr && results.length === 0) {
        if (!stderr.includes('Index is unavailable') && !stderr.includes('kMD')) {
          logger.warn(
@@ -126,6 +163,7 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
        }
      }

+      // Apply limit
      const limitedResults =
        options.limit && results.length > options.limit ? results.slice(0, options.limit) : results;

@@ -139,19 +177,34 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    }
  }

+  /**
+   * Get macOS-specific ignore patterns including Library/Caches
+   */
  protected override getDefaultIgnorePatterns(): string[] {
    return [...super.getDefaultIgnorePatterns(), '**/Library/Caches/**'];
  }

+  /**
+   * Check search service status
+   * @returns Promise indicating if Spotlight service is available
+   */
  async checkSearchServiceStatus(): Promise<boolean> {
    return this.checkSpotlightStatus();
  }

+  /**
+   * Update search index
+   * @param path Optional specified path
+   * @returns Promise indicating operation success
+   */
  async updateSearchIndex(updatePath?: string): Promise<boolean> {
    return this.updateSpotlightIndex(updatePath);
  }

-  private buildSearchCommand(options: SearchFilesParams): {
+  /**
+   * Build mdfind command string
+   */
+  private buildSearchCommand(options: SearchOptions): {
    args: string[];
    cmd: string;
    commandString: string;
@@ -160,9 +213,8 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    const cmd = 'mdfind';
    const args: string[] = [];

-    const onlyIn = options.onlyIn || options.directory;
-    if (onlyIn) {
-      args.push('-onlyin', onlyIn);
+    if (options.onlyIn) {
+      args.push('-onlyin', options.onlyIn);
    }

    if (options.liveUpdate) {
@@ -184,25 +236,30 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    let queryExpression = '';

    if (options.keywords) {
-      if (options.keywords.includes('kMDItem')) {
-        queryExpression = options.keywords;
-      } else {
+      if (!options.keywords.includes('kMDItem')) {
        queryExpression = buildFilenameKeywordExpression(options.keywords);
+      } else {
+        queryExpression = options.keywords;
      }
    }

    if (options.contentContains) {
-      const contentTerm = `kMDItemTextContent == "*${options.contentContains}*"cd`;
-      queryExpression = queryExpression ? `${queryExpression} && ${contentTerm}` : contentTerm;
+      if (queryExpression) {
+        queryExpression = `${queryExpression} && kMDItemTextContent == "*${options.contentContains}*"cd`;
+      } else {
+        queryExpression = `kMDItemTextContent == "*${options.contentContains}*"cd`;
+      }
    }

    if (options.fileTypes && options.fileTypes.length > 0) {
      const typeConditions = options.fileTypes
        .map((type) => `kMDItemContentType == "${type}"`)
        .join(' || ');
-      queryExpression = queryExpression
-        ? `${queryExpression} && (${typeConditions})`
-        : `(${typeConditions})`;
+      if (queryExpression) {
+        queryExpression = `${queryExpression} && (${typeConditions})`;
+      } else {
+        queryExpression = `(${typeConditions})`;
+      }
    }

    if (options.modifiedAfter || options.modifiedBefore) {
@@ -219,9 +276,11 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
        dateCondition += `kMDItemFSContentChangeDate <= $time.iso(${dateString})`;
      }

-      queryExpression = queryExpression
-        ? `${queryExpression} && (${dateCondition})`
-        : dateCondition;
+      if (queryExpression) {
+        queryExpression = `${queryExpression} && (${dateCondition})`;
+      } else {
+        queryExpression = dateCondition;
+      }
    }

    if (options.createdAfter || options.createdBefore) {
@@ -238,9 +297,11 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
        dateCondition += `kMDItemFSCreationDate <= $time.iso(${dateString})`;
      }

-      queryExpression = queryExpression
-        ? `${queryExpression} && (${dateCondition})`
-        : dateCondition;
+      if (queryExpression) {
+        queryExpression = `${queryExpression} && (${dateCondition})`;
+      } else {
+        queryExpression = dateCondition;
+      }
    }

    const hasQuery = Boolean(queryExpression);
@@ -254,9 +315,12 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    return { args, cmd, commandString, hasQuery };
  }

+  /**
+   * Process Spotlight search results with optional metadata
+   */
  private async processSpotlightResults(
    filePaths: string[],
-    options: SearchFilesParams,
+    options: SearchOptions,
    engine?: string,
  ): Promise<FileResult[]> {
    const resultPromises = filePaths.map(async (filePath): Promise<FileResult | null> => {
@@ -305,11 +369,14 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    return results;
  }

-  private async getDetailedMetadata(filePath: string): Promise<Record<string, unknown>> {
+  /**
+   * Get detailed metadata for a file using mdls
+   */
+  private async getDetailedMetadata(filePath: string): Promise<Record<string, any>> {
    try {
      const { stdout } = await execa('mdls', [filePath]);

-      const metadata: Record<string, unknown> = {};
+      const metadata: Record<string, any> = {};
      const lines = stdout.split('\n');

      let currentKey = '';
@@ -350,7 +417,10 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    }
  }

-  private parseMetadataValue(input: string): unknown {
+  /**
+   * Parse metadata value from mdls output
+   */
+  private parseMetadataValue(input: string): any {
    let value = input;
    if (value.startsWith('"') && value.endsWith('"')) {
      value = value.slice(1, -1);
@@ -375,6 +445,9 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    return value;
  }

+  /**
+   * Check Spotlight service status
+   */
  private async checkSpotlightStatus(): Promise<boolean> {
    if (this.spotlightAvailable !== null) {
      return this.spotlightAvailable;
@@ -403,6 +476,9 @@ export class MacOSSearchServiceImpl extends UnixFileSearch {
    }
  }

+  /**
+   * Update Spotlight index
+   */
  private async updateSpotlightIndex(updatePath?: string): Promise<boolean> {
    try {
      await execa('mdutil', ['-E', updatePath || '/']);
@@ -2,33 +2,43 @@ import { type Stats } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import * as os from 'node:os';

+import { type GlobFilesParams, type GlobFilesResult } from '@lobechat/electron-client-ipc';
 import { execa } from 'execa';
 import fg from 'fast-glob';

-import { createLogger } from '../../logger';
-import { type ToolDetector } from '../../toolDetector';
-import type { FileResult, GlobFilesParams, GlobFilesResult, SearchFilesParams } from '../../types';
-import { BaseFileSearch } from '../base';
+import { type ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';

-const logger = createLogger('fileSearch:unix');
+import { BaseFileSearch } from '../base';
+import { type FileResult, type SearchOptions } from '../types';
+
+const logger = createLogger('module:FileSearch:unix');

 /**
 * Fallback tool type for Unix file search
 * Priority: fd > find > fast-glob
 */
-export type UnixSearchTool = 'fast-glob' | 'fd' | 'find';
+export type UnixSearchTool = 'fd' | 'find' | 'fast-glob';

 /**
 * Unix file search base class
 * Provides common search implementations for macOS and Linux
 */
 export abstract class UnixFileSearch extends BaseFileSearch {
+  /**
+   * Current fallback tool being used
+   */
  protected currentTool: UnixSearchTool | null = null;

-  constructor(toolDetector?: ToolDetector) {
-    super(toolDetector);
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    super(toolDetectorManager);
  }

+  /**
+   * Check if a tool is available using 'which' command
+   * @param tool Tool name to check
+   * @returns Promise indicating if tool is available
+   */
  protected async checkToolAvailable(tool: string): Promise<boolean> {
    try {
      await execa('which', [tool], { timeout: 3000 });
@@ -38,9 +48,14 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

+  /**
+   * Determine the best available Unix tool based on priority
+   * Priority: fd > find > fast-glob
+   * @returns The best available tool
+   */
  protected async determineBestUnixTool(): Promise<UnixSearchTool> {
-    if (this.toolDetector) {
-      const bestTool = await this.toolDetector.getBestTool('file-search');
+    if (this.toolDetectorManager) {
+      const bestTool = await this.toolDetectorManager.getBestTool('file-search');
      if (bestTool && ['fd', 'find'].includes(bestTool)) {
        return bestTool as UnixSearchTool;
      }
@@ -57,6 +72,11 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    return 'fast-glob';
  }

+  /**
+   * Fallback to the next available tool
+   * @param currentTool Current tool that failed
+   * @returns Next tool to try
+   */
  protected async fallbackToNextTool(currentTool: UnixSearchTool): Promise<UnixSearchTool> {
    const priority: UnixSearchTool[] = ['fd', 'find', 'fast-glob'];
    const currentIndex = priority.indexOf(currentTool);
@@ -64,7 +84,7 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    for (let i = currentIndex + 1; i < priority.length; i++) {
      const nextTool = priority[i];
      if (nextTool === 'fast-glob') {
-        return 'fast-glob';
+        return 'fast-glob'; // Always available
      }
      if (await this.checkToolAvailable(nextTool)) {
        return nextTool;
@@ -74,9 +94,15 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    return 'fast-glob';
  }

+  /**
+   * Search using the specified Unix tool
+   * @param tool Tool to use for search
+   * @param options Search options
+   * @returns Search results
+   */
  protected async searchWithUnixTool(
    tool: UnixSearchTool,
-    options: SearchFilesParams,
+    options: SearchOptions,
  ): Promise<FileResult[]> {
    switch (tool) {
      case 'fd': {
@@ -91,8 +117,13 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

-  protected async searchWithFd(options: SearchFilesParams): Promise<FileResult[]> {
-    const searchDir = options.onlyIn || options.directory || os.homedir() || '/';
+  /**
+   * Search using fd (fast find alternative)
+   * @param options Search options
+   * @returns Search results
+   */
+  protected async searchWithFd(options: SearchOptions): Promise<FileResult[]> {
+    const searchDir = options.onlyIn || os.homedir() || '/';
    const limit = options.limit || 30;

    logger.debug('Performing fd search', { keywords: options.keywords, searchDir });
@@ -100,12 +131,14 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    try {
      const args: string[] = [];

+      // Pattern matching
      if (options.keywords) {
        args.push(options.keywords);
      } else {
-        args.push('.');
+        args.push('.'); // Match all files
      }

+      // Search directory and options
      args.push(searchDir, '--type', 'f', '--hidden', '--ignore-case', '--max-depth', '10');
      args.push(
        '--max-results',
@@ -145,8 +178,13 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

-  protected async searchWithFind(options: SearchFilesParams): Promise<FileResult[]> {
-    const searchDir = options.onlyIn || options.directory || os.homedir() || '/';
+  /**
+   * Search using find (Unix standard tool)
+   * @param options Search options
+   * @returns Search results
+   */
+  protected async searchWithFind(options: SearchOptions): Promise<FileResult[]> {
+    const searchDir = options.onlyIn || os.homedir() || '/';
    const limit = options.limit || 30;

    logger.debug('Performing find search', { keywords: options.keywords, searchDir });
@@ -172,6 +210,9 @@ export abstract class UnixFileSearch extends BaseFileSearch {
        '-o',
      ];

+      // Limit depth and exclude common directories
+
+      // Pattern matching
      if (options.keywords) {
        args.push('-iname', `*${options.keywords}*`);
      }
@@ -206,13 +247,19 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

-  protected async searchWithFastGlob(options: SearchFilesParams): Promise<FileResult[]> {
-    const searchDir = options.onlyIn || options.directory || os.homedir() || '/';
+  /**
+   * Search using fast-glob (pure Node.js implementation)
+   * @param options Search options
+   * @returns Search results
+   */
+  protected async searchWithFastGlob(options: SearchOptions): Promise<FileResult[]> {
+    const searchDir = options.onlyIn || os.homedir() || '/';
    const limit = options.limit || 30;

    logger.debug('Performing fast-glob search', { keywords: options.keywords, searchDir });

    try {
+      // Build glob pattern from keywords
      const pattern = options.keywords
        ? `**/*${this.escapeGlobPattern(options.keywords)}*`
        : '**/*';
@@ -221,7 +268,7 @@ export abstract class UnixFileSearch extends BaseFileSearch {
        absolute: true,
        caseSensitiveMatch: false,
        cwd: searchDir,
-        deep: 10,
+        deep: 10, // Limit depth for performance
        dot: true,
        ignore: this.getDefaultIgnorePatterns(),
        onlyFiles: true,
@@ -238,6 +285,11 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

+  /**
+   * Get default ignore patterns for fast-glob
+   * Can be overridden by subclasses for platform-specific patterns
+   * @returns Array of ignore patterns
+   */
  protected getDefaultIgnorePatterns(): string[] {
    return ['**/node_modules/**', '**/.git/**', '**/.*cache*/**'];
  }
@@ -245,14 +297,23 @@ export abstract class UnixFileSearch extends BaseFileSearch {
  /**
   * Perform glob pattern matching
   * Uses fd > find > fast-glob fallback strategy
+   * @param params Glob parameters
+   * @returns Promise of glob result
   */
  async glob(params: GlobFilesParams): Promise<GlobFilesResult> {
+    // Determine the best available tool
    const tool = await this.determineBestUnixTool();
    logger.info(`Using glob tool: ${tool}`);

    return this.globWithUnixTool(tool, params);
  }

+  /**
+   * Glob using the specified Unix tool
+   * @param tool Tool to use for glob
+   * @param params Glob parameters
+   * @returns Glob results
+   */
  protected async globWithUnixTool(
    tool: UnixSearchTool,
    params: GlobFilesParams,
@@ -270,8 +331,13 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

+  /**
+   * Glob using fd
+   * @param params Glob parameters
+   * @returns Glob results
+   */
  protected async globWithFd(params: GlobFilesParams): Promise<GlobFilesResult> {
-    const searchPath = params.scope || params.cwd || os.homedir() || process.cwd();
+    const searchPath = params.scope || os.homedir() || process.cwd();
    const logPrefix = `[glob:fd: ${params.pattern}]`;

    logger.debug(`${logPrefix} Starting fd glob`, { searchPath });
@@ -284,10 +350,6 @@ export abstract class UnixFileSearch extends BaseFileSearch {
        '--absolute-path',
        '--hidden',
        '--no-ignore',
-        '--exclude',
-        'node_modules',
-        '--exclude',
-        '.git',
      ];

      const { stdout, exitCode } = await execa('fd', args, {
@@ -305,6 +367,7 @@ export abstract class UnixFileSearch extends BaseFileSearch {
        .split('\n')
        .filter((line) => line.trim());

+      // Get stats for sorting by mtime
      const filesWithStats = await this.getFilesWithStats(files);
      const sortedFiles = filesWithStats.sort((a, b) => b.mtime - a.mtime).map((f) => f.path);

@@ -323,19 +386,30 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

+  /**
+   * Glob using find
+   * Note: find has limited glob support, converts pattern to -name/-path
+   * @param params Glob parameters
+   * @returns Glob results
+   */
  protected async globWithFind(params: GlobFilesParams): Promise<GlobFilesResult> {
-    const searchPath = params.scope || params.cwd || os.homedir() || process.cwd();
+    const searchPath = params.scope || os.homedir() || process.cwd();
    const logPrefix = `[glob:find: ${params.pattern}]`;

    logger.debug(`${logPrefix} Starting find glob`, { searchPath });

    try {
+      // Convert glob pattern to find -name pattern
+      // find doesn't support full glob, so we do basic conversion
      const pattern = params.pattern;
      const args: string[] = [searchPath];

+      // Check if pattern contains directory separators
      if (pattern.includes('/')) {
+        // Use -path for patterns with directories
        args.push('-path', pattern);
      } else {
+        // Use -name for simple patterns
        args.push('-name', pattern);
      }

@@ -356,6 +430,7 @@ export abstract class UnixFileSearch extends BaseFileSearch {
        .split('\n')
        .filter((line) => line.trim());

+      // Get stats for sorting by mtime
      const filesWithStats = await this.getFilesWithStats(files);
      const sortedFiles = filesWithStats.sort((a, b) => b.mtime - a.mtime).map((f) => f.path);

@@ -374,8 +449,13 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

+  /**
+   * Glob using fast-glob (Node.js fallback)
+   * @param params Glob parameters
+   * @returns Glob results
+   */
  protected async globWithFastGlob(params: GlobFilesParams): Promise<GlobFilesResult> {
-    const searchPath = params.scope || params.cwd || os.homedir() || process.cwd();
+    const searchPath = params.scope || os.homedir() || process.cwd();
    const logPrefix = `[glob:fast-glob: ${params.pattern}]`;

    logger.debug(`${logPrefix} Starting fast-glob`, { searchPath });
@@ -385,11 +465,11 @@ export abstract class UnixFileSearch extends BaseFileSearch {
        absolute: true,
        cwd: searchPath,
        dot: true,
-        ignore: ['**/node_modules/**', '**/.git/**'],
        onlyFiles: false,
        stats: true,
      });

+      // Sort by modification time (most recent first)
      const sortedFiles = (files as unknown as Array<{ path: string; stats: Stats }>)
        .sort((a, b) => b.stats.mtime.getTime() - a.stats.mtime.getTime())
        .map((f) => f.path);
@@ -414,6 +494,11 @@ export abstract class UnixFileSearch extends BaseFileSearch {
    }
  }

+  /**
+   * Get file stats for sorting
+   * @param files File paths
+   * @returns Files with mtime
+   */
  private async getFilesWithStats(
    files: string[],
  ): Promise<Array<{ mtime: number; path: string }>> {
@@ -424,6 +509,7 @@ export abstract class UnixFileSearch extends BaseFileSearch {
        const stats = await stat(filePath);
        results.push({ mtime: stats.mtime.getTime(), path: filePath });
      } catch {
+        // Skip files that can't be stat'd
        results.push({ mtime: 0, path: filePath });
      }
    }
@@ -2,34 +2,45 @@ import { type Stats } from 'node:fs';
 import { stat } from 'node:fs/promises';
 import * as os from 'node:os';

+import { type GlobFilesParams, type GlobFilesResult } from '@lobechat/electron-client-ipc';
 import { execa } from 'execa';
 import fg from 'fast-glob';

-import { createLogger } from '../../logger';
-import { type ToolDetector } from '../../toolDetector';
-import type { FileResult, GlobFilesParams, GlobFilesResult, SearchFilesParams } from '../../types';
-import { BaseFileSearch } from '../base';
+import { type ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+import { createLogger } from '@/utils/logger';

-const logger = createLogger('fileSearch:windows');
+import { BaseFileSearch } from '../base';
+import { type FileResult, type SearchOptions } from '../types';
+
+const logger = createLogger('module:FileSearch:windows');

 /**
 * Fallback tool type for Windows file search
 * Priority: fd > powershell > fast-glob
 */
-type WindowsFallbackTool = 'fast-glob' | 'fd' | 'powershell';
+type WindowsFallbackTool = 'fd' | 'powershell' | 'fast-glob';

 /**
 * Windows file search implementation
 * Uses fd > PowerShell > fast-glob fallback strategy
 */
 export class WindowsSearchServiceImpl extends BaseFileSearch {
+  /**
+   * Current fallback tool being used
+   */
  private currentTool: WindowsFallbackTool | null = null;

-  constructor(toolDetector?: ToolDetector) {
-    super(toolDetector);
+  constructor(toolDetectorManager?: ToolDetectorManager) {
+    super(toolDetectorManager);
  }

-  async search(options: SearchFilesParams): Promise<FileResult[]> {
+  /**
+   * Perform file search
+   * @param options Search options
+   * @returns Promise of search result list
+   */
+  async search(options: SearchOptions): Promise<FileResult[]> {
+    // Determine the best available tool on first search
    if (this.currentTool === null) {
      this.currentTool = await this.determineBestTool();
      logger.info(`Using file search tool: ${this.currentTool}`);
@@ -38,9 +49,13 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    return this.searchWithTool(this.currentTool, options);
  }

+  /**
+   * Determine the best available tool based on priority
+   * Priority: fd > powershell > fast-glob
+   */
  private async determineBestTool(): Promise<WindowsFallbackTool> {
-    if (this.toolDetector) {
-      const bestTool = await this.toolDetector.getBestTool('file-search');
+    if (this.toolDetectorManager) {
+      const bestTool = await this.toolDetectorManager.getBestTool('file-search');
      if (bestTool && ['fd', 'powershell'].includes(bestTool)) {
        return bestTool as WindowsFallbackTool;
      }
@@ -50,9 +65,15 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
      return 'fd';
    }

+    // PowerShell is always available on Windows
    return 'powershell';
  }

+  /**
+   * Check if a tool is available using 'where' command (Windows equivalent of 'which')
+   * @param tool Tool name to check
+   * @returns Promise indicating if tool is available
+   */
  private async checkToolAvailable(tool: string): Promise<boolean> {
    try {
      await execa('where', [tool], { timeout: 3000 });
@@ -62,9 +83,12 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    }
  }

+  /**
+   * Search using the specified tool
+   */
  private async searchWithTool(
    tool: WindowsFallbackTool,
-    options: SearchFilesParams,
+    options: SearchOptions,
  ): Promise<FileResult[]> {
    switch (tool) {
      case 'fd': {
@@ -79,6 +103,9 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    }
  }

+  /**
+   * Fallback to the next available tool
+   */
  private async fallbackToNextTool(currentTool: WindowsFallbackTool): Promise<WindowsFallbackTool> {
    const priority: WindowsFallbackTool[] = ['fd', 'powershell', 'fast-glob'];
    const currentIndex = priority.indexOf(currentTool);
@@ -86,7 +113,7 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    for (let i = currentIndex + 1; i < priority.length; i++) {
      const nextTool = priority[i];
      if (nextTool === 'fast-glob' || nextTool === 'powershell') {
-        return nextTool;
+        return nextTool; // Always available
      }
      if (await this.checkToolAvailable(nextTool)) {
        return nextTool;
@@ -96,8 +123,13 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    return 'fast-glob';
  }

-  private async searchWithFd(options: SearchFilesParams): Promise<FileResult[]> {
-    const searchDir = options.onlyIn || options.directory || os.homedir() || 'C:\\';
+  /**
+   * Search using fd (cross-platform fast find alternative)
+   * @param options Search options
+   * @returns Search results
+   */
+  private async searchWithFd(options: SearchOptions): Promise<FileResult[]> {
+    const searchDir = options.onlyIn || os.homedir() || 'C:\\';
    const limit = options.limit || 30;

    logger.debug('Performing fd search', { keywords: options.keywords, searchDir });
@@ -105,12 +137,14 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    try {
      const args: string[] = [];

+      // Pattern matching
      if (options.keywords) {
        args.push(options.keywords);
      } else {
-        args.push('.');
+        args.push('.'); // Match all files
      }

+      // Search directory and options
      args.push(searchDir, '--type', 'f', '--hidden', '--ignore-case', '--max-depth', '10');
      args.push(
        '--max-results',
@@ -150,15 +184,26 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    }
  }

-  private async searchWithPowerShell(options: SearchFilesParams): Promise<FileResult[]> {
-    const searchDir = options.onlyIn || options.directory || os.homedir() || 'C:\\';
+  /**
+   * Search using PowerShell Get-ChildItem
+   * @param options Search options
+   * @returns Search results
+   */
+  private async searchWithPowerShell(options: SearchOptions): Promise<FileResult[]> {
+    const searchDir = options.onlyIn || os.homedir() || 'C:\\';
    const limit = options.limit || 30;

    logger.debug('Performing PowerShell search', { keywords: options.keywords, searchDir });

    try {
+      // Build PowerShell command
      const filter = options.keywords ? `*${options.keywords}*` : '*';

+      // PowerShell command to search files
+      // -Recurse: recursive search
+      // -File: only files
+      // -Depth: limit search depth
+      // -ErrorAction SilentlyContinue: ignore permission errors
      const psCommand = `
        Get-ChildItem -Path '${searchDir}' -Filter '${filter}' -Recurse -File -Depth 10 -ErrorAction SilentlyContinue |
        Where-Object {
@@ -201,13 +246,19 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    }
  }

-  private async searchWithFastGlob(options: SearchFilesParams): Promise<FileResult[]> {
-    const searchDir = options.onlyIn || options.directory || os.homedir() || 'C:\\';
+  /**
+   * Search using fast-glob (pure Node.js implementation)
+   * @param options Search options
+   * @returns Search results
+   */
+  private async searchWithFastGlob(options: SearchOptions): Promise<FileResult[]> {
+    const searchDir = options.onlyIn || os.homedir() || 'C:\\';
    const limit = options.limit || 30;

    logger.debug('Performing fast-glob search', { keywords: options.keywords, searchDir });

    try {
+      // Build glob pattern from keywords
      const pattern = options.keywords
        ? `**/*${this.escapeGlobPattern(options.keywords)}*`
        : '**/*';
@@ -217,8 +268,7 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
        caseSensitiveMatch: false,
        cwd: searchDir,
        deep: 10,
-        // Windows hidden files use attributes, not dot prefix
-        dot: false,
+        dot: false, // Windows hidden files use attributes, not dot prefix
        ignore: [
          '**/node_modules/**',
          '**/.git/**',
@@ -243,16 +293,33 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    }
  }

+  /**
+   * Check search service status
+   * @returns Promise indicating if service is available (always true)
+   */
  async checkSearchServiceStatus(): Promise<boolean> {
+    // At minimum, fast-glob is always available
    return true;
  }

+  /**
+   * Update search index
+   * Windows Search index is managed by the OS
+   * @returns Promise indicating operation result (always false)
+   */
  async updateSearchIndex(): Promise<boolean> {
    logger.warn('updateSearchIndex is not supported (using fast-glob instead of Windows Search)');
    return false;
  }

+  /**
+   * Perform glob pattern matching
+   * Uses fd > fast-glob fallback strategy
+   * @param params Glob parameters
+   * @returns Promise of glob result
+   */
  async glob(params: GlobFilesParams): Promise<GlobFilesResult> {
+    // Check if fd is available
    if (await this.checkToolAvailable('fd')) {
      logger.info('Using glob tool: fd');
      return this.globWithFd(params);
@@ -262,8 +329,13 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    return this.globWithFastGlob(params);
  }

+  /**
+   * Glob using fd
+   * @param params Glob parameters
+   * @returns Glob results
+   */
  private async globWithFd(params: GlobFilesParams): Promise<GlobFilesResult> {
-    const searchPath = params.scope || params.cwd || os.homedir() || process.cwd();
+    const searchPath = params.scope || os.homedir() || process.cwd();
    const logPrefix = `[glob:fd: ${params.pattern}]`;

    logger.debug(`${logPrefix} Starting fd glob`, { searchPath });
@@ -276,10 +348,6 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
        '--absolute-path',
        '--hidden',
        '--no-ignore',
-        '--exclude',
-        'node_modules',
-        '--exclude',
-        '.git',
      ];

      const { stdout, exitCode } = await execa('fd', args, {
@@ -294,9 +362,10 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {

      const files = stdout
        .trim()
-        .split('\r\n')
+        .split('\r\n') // Windows uses \r\n
        .filter((line) => line.trim());

+      // Get stats for sorting by mtime
      const filesWithStats = await this.getFilesWithStats(files);
      const sortedFiles = filesWithStats.sort((a, b) => b.mtime - a.mtime).map((f) => f.path);

@@ -315,8 +384,13 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    }
  }

+  /**
+   * Glob using fast-glob (Node.js fallback)
+   * @param params Glob parameters
+   * @returns Glob results
+   */
  private async globWithFastGlob(params: GlobFilesParams): Promise<GlobFilesResult> {
-    const searchPath = params.scope || params.cwd || os.homedir() || process.cwd();
+    const searchPath = params.scope || os.homedir() || process.cwd();
    const logPrefix = `[glob:fast-glob: ${params.pattern}]`;

    logger.debug(`${logPrefix} Starting fast-glob`, { searchPath });
@@ -325,13 +399,12 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
      const files = await fg(params.pattern, {
        absolute: true,
        cwd: searchPath,
-        // Windows hidden files use attributes, not dot prefix
-        dot: false,
-        ignore: ['**/node_modules/**', '**/.git/**'],
+        dot: false, // Windows hidden files use attributes, not dot prefix
        onlyFiles: false,
        stats: true,
      });

+      // Sort by modification time (most recent first)
      const sortedFiles = (files as unknown as Array<{ path: string; stats: Stats }>)
        .sort((a, b) => b.stats.mtime.getTime() - a.stats.mtime.getTime())
        .map((f) => f.path);
@@ -356,6 +429,11 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
    }
  }

+  /**
+   * Get file stats for sorting
+   * @param files File paths
+   * @returns Files with mtime
+   */
  private async getFilesWithStats(
    files: string[],
  ): Promise<Array<{ mtime: number; path: string }>> {
@@ -366,6 +444,7 @@ export class WindowsSearchServiceImpl extends BaseFileSearch {
        const stats = await stat(filePath);
        results.push({ mtime: stats.mtime.getTime(), path: filePath });
      } catch {
+        // Skip files that can't be stat'd
        results.push({ mtime: 0, path: filePath });
      }
    }
@@ -0,0 +1,31 @@
+import { platform } from 'node:os';
+
+import type { ToolDetectorManager } from '@/core/infrastructure/ToolDetectorManager';
+
+import { LinuxSearchServiceImpl } from './impl/linux';
+import { MacOSSearchServiceImpl } from './impl/macOS';
+import { WindowsSearchServiceImpl } from './impl/windows';
+
+export { BaseFileSearch } from './base';
+export type { FileResult, SearchOptions } from './types';
+
+export const createFileSearchModule = (toolDetectorManager?: ToolDetectorManager) => {
+  const currentPlatform = platform();
+
+  switch (currentPlatform) {
+    case 'darwin': {
+      return new MacOSSearchServiceImpl(toolDetectorManager);
+    }
+    case 'win32': {
+      return new WindowsSearchServiceImpl(toolDetectorManager);
+    }
+    case 'linux': {
+      return new LinuxSearchServiceImpl(toolDetectorManager);
+    }
+    default: {
+      // Fallback to Linux implementation (uses fast-glob, no external dependencies)
+      console.warn(`Unsupported platform: ${currentPlatform}, using Linux fallback`);
+      return new LinuxSearchServiceImpl(toolDetectorManager);
+    }
+  }
+};
@@ -0,0 +1,53 @@
+export interface FileResult {
+  contentType?: string;
+  createdTime: Date;
+  // Search engine used to find this file (e.g., 'mdfind', 'fd', 'find', 'fast-glob')
+  engine?: string;
+  isDirectory: boolean;
+  lastAccessTime: Date;
+  // Spotlight specific metadata
+  metadata?: {
+    [key: string]: any;
+  };
+  modifiedTime: Date;
+  name: string;
+  path: string;
+  size: number;
+  type: string;
+}
+
+export interface SearchOptions {
+  // Directory options
+  // Content options
+  contentContains?: string;
+  // Created after specific date
+  createdAfter?: Date;
+
+  // Created before specific date
+  createdBefore?: Date;
+  // Whether to return detailed results
+  detailed?: boolean;
+
+  // Limit search to specific directories
+  exclude?: string[]; // Files containing specific content
+
+  // File type options
+  fileTypes?: string[];
+
+  // Basic options
+  keywords: string;
+  limit?: number;
+  // Created before specific date
+  // Advanced options
+  liveUpdate?: boolean;
+  // File type filters, like "public.image", "public.movie"
+  // Time options
+  modifiedAfter?: Date;
+
+  // Modified after specific date
+  modifiedBefore?: Date;
+  // Path options
+  onlyIn?: string; // Whether to return detailed metadata
+  sortBy?: 'name' | 'date' | 'size'; // Result sorting
+  sortDirection?: 'asc' | 'desc'; // Sort direction
+}
@@ -28,7 +28,7 @@ export const claudeCodeDriver: HeterogeneousAgentDriver = {
      args: [
        ...DESKTOP_CLAUDE_CODE_ARGS,
        // Wire the controller-managed temp mcp.json (AskUserQuestion server,
-        // see ) when present. Path-based config is required — CC
+        // see LOBE-8725) when present. Path-based config is required — CC
        // does not accept inline JSON for `--mcp-config`.
        ...(mcpConfigPath ? ['--mcp-config', mcpConfigPath] : []),
        ...(resumeSessionId ? ['--resume', resumeSessionId] : []),
@@ -1,49 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { extractRestoreRoute } from '../utils';
-
-describe('extractRestoreRoute', () => {
-  it('extracts the route from a production renderer URL', () => {
-    expect(extractRestoreRoute('app://renderer/agent/abc')).toBe('/agent/abc');
-  });
-
-  it('extracts the route from a dev renderer URL', () => {
-    expect(extractRestoreRoute('http://localhost:5173/settings/provider')).toBe(
-      '/settings/provider',
-    );
-  });
-
-  it('strips the lng query param but keeps the rest', () => {
-    expect(extractRestoreRoute('app://renderer/agent?lng=zh-CN&x=1')).toBe('/agent?x=1');
-  });
-
-  it('strips a lone lng query param', () => {
-    expect(extractRestoreRoute('app://renderer/chat?lng=en-US')).toBe('/chat');
-  });
-
-  it('returns null for the root route', () => {
-    expect(extractRestoreRoute('app://renderer/')).toBeNull();
-  });
-
-  it('returns null for file: protocol (splash/error pages)', () => {
-    expect(extractRestoreRoute('file:///Users/x/resources/splash.html')).toBeNull();
-  });
-
-  it('returns null for static asset paths', () => {
-    expect(extractRestoreRoute('app://renderer/assets/index.js')).toBeNull();
-  });
-
-  it('returns null for root static files', () => {
-    expect(extractRestoreRoute('app://renderer/favicon.ico')).toBeNull();
-  });
-
-  it('preserves dotted SPA route slugs', () => {
-    expect(extractRestoreRoute('app://renderer/community/skill/github.owner.repo')).toBe(
-      '/community/skill/github.owner.repo',
-    );
-  });
-
-  it('returns null for an unparseable URL', () => {
-    expect(extractRestoreRoute('not a url')).toBeNull();
-  });
-});
@@ -1,12 +1,5 @@
 import semver from 'semver';

-const STATIC_ASSET_PATH_PREFIXES = ['/assets/', '/_next/', '/static/'];
-const ROOT_STATIC_FILE_RE = /^\/[^/]+\.[^/]+$/;
-
-const isStaticAssetPath = (pathname: string) =>
-  ROOT_STATIC_FILE_RE.test(pathname) ||
-  STATIC_ASSET_PATH_PREFIXES.some((prefix) => pathname.startsWith(prefix));
-
 /**
 * Determine if application update is needed rather than just renderer update
 * @param currentVersion Current version
@@ -38,29 +31,3 @@ export const shouldUpdateApp = (currentVersion: string, nextVersion: string): bo
    return true;
  }
 };
-
-/**
- * Extract a restorable SPA route (`pathname + search`) from a renderer window URL.
- * Returns `null` when the URL is not a restorable route — splash/error pages
- * (`file:` protocol), known static asset paths, or the root route (identical
- * to the default, nothing worth restoring).
- */
-export const extractRestoreRoute = (rawUrl: string): string | null => {
-  let url: URL;
-  try {
-    url = new URL(rawUrl);
-  } catch {
-    return null;
-  }
-
-  if (url.protocol === 'file:') return null;
-  if (isStaticAssetPath(url.pathname)) return null;
-
-  // `lng` is re-appended by Browser.buildUrlWithLocale on the next load
-  url.searchParams.delete('lng');
-
-  const route = `${url.pathname}${url.search}`;
-  if (route === '/' || route === '') return null;
-
-  return route;
-};
@@ -1,12 +1,12 @@
-import type { FileResult, SearchOptions } from '@lobechat/local-file-shell';
 import { beforeEach, describe, expect, it, vi } from 'vitest';

 import type { App } from '@/core/App';
+import type { FileResult, SearchOptions } from '@/modules/fileSearch';

 import FileSearchService from '../fileSearchSrv';

 // Mock the fileSearch module
-vi.mock('@lobechat/local-file-shell', () => {
+vi.mock('@/modules/fileSearch', () => {
  const MockFileSearchImpl = vi.fn().mockImplementation(() => ({
    search: vi.fn(),
    checkSearchServiceStatus: vi.fn(),
@@ -1,31 +1,31 @@
-import {
-  type BaseContentSearch,
-  createContentSearchImpl,
-  type GrepContentParams,
-  type GrepContentResult,
-} from '@lobechat/local-file-shell';
+import type { GrepContentParams, GrepContentResult } from '@lobechat/electron-client-ipc';
+
+import type { BaseContentSearch} from '@/modules/contentSearch';
+import { createContentSearchImpl } from '@/modules/contentSearch';

 import { ServiceModule } from './index';

 /**
 * Content Search Service
 * Provides content search functionality using platform-specific implementations
- * sunk into the shared `@lobechat/local-file-shell` package.
 */
 export default class ContentSearchService extends ServiceModule {
  private impl: BaseContentSearch = createContentSearchImpl();

+  /**
+   * Perform content search (grep)
+   */
  async grep(params: GrepContentParams): Promise<GrepContentResult> {
-    // Lazily wire the desktop ToolDetectorManager so we don't hit the
-    // class-field init-before-super-constructor gotcha. The manager already
-    // satisfies the minimal `ToolDetector` contract (only `getBestTool` is
-    // consumed by the search impls).
+    // Ensure toolDetectorManager is set
    if (this.app?.toolDetectorManager) {
-      this.impl.setToolDetector(this.app.toolDetectorManager);
+      this.impl.setToolDetectorManager(this.app.toolDetectorManager);
    }
    return this.impl.grep(params);
  }

+  /**
+   * Check if a specific tool is available
+   */
  async checkToolAvailable(tool: string): Promise<boolean> {
    return this.impl.checkToolAvailable(tool);
  }
@@ -1,44 +1,54 @@
+import type { GlobFilesParams, GlobFilesResult } from '@lobechat/electron-client-ipc';
+
+import type {
+  BaseFileSearch,
+  FileResult,
+  SearchOptions} from '@/modules/fileSearch';
 import {
-  type BaseFileSearch,
-  createFileSearchModule,
-  type FileResult,
-  type GlobFilesParams,
-  type GlobFilesResult,
-  type SearchOptions,
-} from '@lobechat/local-file-shell';
+  createFileSearchModule
+} from '@/modules/fileSearch';

 import { ServiceModule } from './index';

 /**
 * File Search Service
- * Main service class that delegates to platform-specific implementations from
- * `@lobechat/local-file-shell`.
+ * Main service class that uses platform-specific implementations internally
 */
 export default class FileSearchService extends ServiceModule {
  private impl: BaseFileSearch = createFileSearchModule();

+  /**
+   * Perform file search
+   */
  async search(
    query: string,
    options: Omit<SearchOptions, 'keywords'> = {},
  ): Promise<FileResult[]> {
-    if (this.app?.toolDetectorManager) {
-      this.impl.setToolDetector(this.app.toolDetectorManager);
-    }
    return this.impl.search({ ...options, keywords: query });
  }

+  /**
+   * Check search service status
+   */
  async checkSearchServiceStatus(): Promise<boolean> {
    return this.impl.checkSearchServiceStatus();
  }

+  /**
+   * Update search index
+   * @param path Optional specified path
+   * @returns Promise indicating operation success
+   */
  async updateSearchIndex(path?: string): Promise<boolean> {
    return this.impl.updateSearchIndex(path);
  }

+  /**
+   * Perform glob pattern matching
+   * @param params Glob parameters
+   * @returns Promise of glob result
+   */
  async glob(params: GlobFilesParams): Promise<GlobFilesResult> {
-    if (this.app?.toolDetectorManager) {
-      this.impl.setToolDetector(this.app.toolDetectorManager);
-    }
    return this.impl.glob(params);
  }
 }
@@ -8,7 +8,7 @@ import type {
 } from '@lobechat/device-gateway-client';
 import { GatewayClient } from '@lobechat/device-gateway-client';
 import type { GatewayConnectionStatus } from '@lobechat/electron-client-ipc';
-import { app, powerSaveBlocker } from 'electron';
+import { app } from 'electron';

 import { createLogger } from '@/utils/logger';

@@ -36,7 +36,6 @@ export default class GatewayConnectionService extends ServiceModule {
  private client: GatewayClient | null = null;
  private status: GatewayConnectionStatus = 'disconnected';
  private deviceId: string | null = null;
-  private powerSaveBlockerId: number | null = null;

  private tokenProvider: (() => Promise<string | null>) | null = null;
  private tokenRefresher: (() => Promise<{ error?: string; success: boolean }>) | null = null;
@@ -319,26 +318,6 @@ export default class GatewayConnectionService extends ServiceModule {
    }
  };

-  // ─── Power Save Blocker ───
-
-  /**
-   * Start power save blocker to prevent macOS App Nap from suspending the process
-   * while the gateway connection is active. Uses 'prevent-app-suspension' so the
-   * display can still sleep — only the app process is kept alive.
-   */
-  private startPowerSaveBlocker() {
-    if (this.powerSaveBlockerId !== null) return;
-    this.powerSaveBlockerId = powerSaveBlocker.start('prevent-app-suspension');
-    logger.info(`Power save blocker started (id=${this.powerSaveBlockerId})`);
-  }
-
-  private stopPowerSaveBlocker() {
-    if (this.powerSaveBlockerId === null) return;
-    powerSaveBlocker.stop(this.powerSaveBlockerId);
-    logger.info(`Power save blocker stopped (id=${this.powerSaveBlockerId})`);
-    this.powerSaveBlockerId = null;
-  }
-
  // ─── Status Broadcasting ───

  private setStatus(status: GatewayConnectionStatus) {
@@ -346,15 +325,6 @@ export default class GatewayConnectionService extends ServiceModule {

    logger.info(`Connection status: ${this.status} → ${status}`);
    this.status = status;
-
-    // Keep the app process alive while gateway is connected so macOS App Nap
-    // does not suspend it during display sleep, which would drop the WebSocket.
-    if (status === 'connected') {
-      this.startPowerSaveBlocker();
-    } else {
-      this.stopPowerSaveBlocker();
-    }
-
    this.app.browserManager.broadcastToAllWindows('gatewayConnectionStatusChanged', { status });
  }

@@ -21,7 +21,6 @@ export interface ElectronMainStore {
  locale: string;
  localFileWorkspaceRoots: string[];
  networkProxy: NetworkProxySettings;
-  pendingRestoreRoute: string;
  shortcuts: Record<string, string>;
  storagePath: string;
  themeMode: 'dark' | 'light' | 'system';
@@ -1,4 +1,3 @@
-import { setLoggerFactory } from '@lobechat/local-file-shell';
 import debug from 'debug';
 import electronLog from 'electron-log';

@@ -47,9 +46,3 @@ export const createLogger = (namespace: string) => {
    },
  };
 };
-
-// Route @lobechat/local-file-shell logs through desktop's electron-log +
-// debug pipeline so search failures from the sunk contentSearch / fileSearch
-// modules land in the same production log file users attach for support
-// (regression introduced when the modules moved out of the desktop tree).
-setLoggerFactory(createLogger);
@@ -1,39 +0,0 @@
---
-title: Introducing CAO — Your Chief Agent Operator
-description: >-
-  Meet CAO: agents that review their own work, recruit teammates when they need help, and only stop to ask you when it really matters.
-tags:
-  - CAO
-  - Agent Teams
-  - Tasks
-  - Models
---
-
-# Introducing CAO — Your Chief Agent Operator
-
-## Meet CAO
-
-CAO (Chief Agent Operator) turns short back-and-forth chats into agents that just keep going. Instead of waiting for you to say "ok, next step", your agent now checks its own work, decides what to do next, and gets on with it. When something genuinely needs your call, it pauses, tells you what it tried, and asks a clear question — no more guessing in the dark.
-
-CAO can also bring in help. If a task gets big, your agent can put together a small team of sub-agents and hand pieces off to them. You can peek into any of their conversations to see what they're up to, while your main agent stays in charge of the overall plan.
-
-[Learn more about CAO →](https://x.com/lobehub/status/2056371816265097337?s=20)
-
-## What else is new
-
- Recurring tasks are more reliable, with a cap on how many times a task can run and protection against schedules that fire too often
- A cleaner Agent Documents view — easier to find what you put there, and no more clutter from old web crawls
- Project skills now show up in the working sidebar, with a built-in markdown preview
- You can pick a different model for each kind of follow-up suggestion
- New model: Baidu Ernie 5.1
- DeepSeek pricing is back to official rates
-
-## Improvements and fixes
-
- Desktop no longer signs you out from background token refreshes, and remembers which page you were on after an app update.
- Chat input actions show as icon + label, and only the latest reply animates as it streams.
- Cleaner tab bar styling, and task schedule labels no longer wrap awkwardly.
- Local-file search handles hidden files starting with `.`, and grep parameters now flow through correctly.
- Documents fail clearly when they aren't supported, instead of producing confusing errors.
- Gemini tool calls handle thinking signatures and enums correctly, and per-tool timeouts now stick.
- Task pages keep the right agent context; memory updates stay out of your main thread.
@@ -1,38 +0,0 @@
---
-title: 隆重推出 CAO —— 你的首席智能体运营官
-description: 认识 CAO：会自己复盘、能临时组队，只在真正需要时才停下来问你的智能体。
-tags:
-  - CAO
-  - 智能体团队
-  - 任务
-  - 模型
---
-
-# 隆重推出 CAO —— 你的首席智能体运营官
-
-## 认识 CAO
-
-CAO（首席智能体运营官）让原本一问一答的对话，变成一个能自己往前推进的智能体。不必再每一步都告诉它「好，下一步」—— 它会自己复盘已完成的部分，决定接下来要做什么，然后继续推进。当遇到真正需要你来拍板的事，它会停下来，告诉你已经尝试了什么，并提出一个清晰的问题，而不是凭感觉硬猜。
-
-CAO 也会找帮手。任务变大时，它可以临时组建一支子智能体小队，把不同部分交给队友处理。你随时可以看任意一个子智能体的对话进展，而主智能体始终掌控整体节奏。
-
-[了解更多 CAO →](https://x.com/lobehub/status/2056371816265097337?s=20)
-
-## 还有这些新东西
-
- 周期性任务更稳了：可以限制总执行次数，也会阻止设置得过于频繁的计划
- 智能体文档视图更清爽 —— 更容易找到自己放进去的东西，也不再混着旧的网页抓取记录
- 项目技能现在会出现在工作侧栏，并自带 Markdown 预览
- 不同类型的后续建议可以分别选择不同的模型
- 新增模型：百度文心一言 5.1
- DeepSeek 价格已恢复官方定价
-
-## 体验优化与修复
-
- 桌面端不再因为后台刷新 token 而把你踢出登录，应用更新后也能回到你之前所在的页面。
- 聊天输入框的动作按钮调整为「图标 + 标签」样式，只有最新一条回复会有打字动画。
- 标签栏样式更清爽，任务计划标签不再换行错位。
- 本地文件搜索可以正确处理以 `.` 开头的隐藏文件，搜索参数也能完整传递。
- 不支持的文档现在会明确报错，而不是抛出令人困惑的提示。
- Gemini 工具调用对思考签名和枚举类型的处理已修复，每个工具的超时设置也确实生效。
- 任务页面会保留正确的智能体上下文，记忆更新也不会再混入主对话。
@@ -2,249 +2,359 @@
  "$schema": "https://github.com/lobehub/lobe-chat/blob/main/docs/changelog/schema.json",
  "cloud": [],
  "community": [
-    {
-      "image": "https://hub-apac-1.lobeobjects.space/billboard/covers/1778838542538-MDEMAEav.png",
-      "id": "2026-05-19-chief-agent-operator",
-      "date": "2026-05-19",
-      "versionRange": ["2.1.58", "2.2.0"]
-    },
    {
      "image": "/blog/assets4aa1732a45832afc780600e6e329860c.webp",
      "id": "2026-05-11-agent-tasks-ga",
      "date": "2026-05-11",
-      "versionRange": ["2.1.57"]
+      "versionRange": [
+        "2.1.57"
+      ]
    },
    {
      "image": "/blog/assetsb2bf4ddf0a45ff887a993c18cb7ab983.webp",
      "id": "2026-05-04-task-scheduler",
      "date": "2026-05-04",
-      "versionRange": ["2.1.54", "2.1.56"]
+      "versionRange": [
+        "2.1.54",
+        "2.1.56"
+      ]
    },
    {
      "image": "/blog/assetsfa267a02f20bc5ba6f1273bcf27b7c9f.webp",
      "id": "2026-04-27-heterogeneous-agent",
      "date": "2026-04-27",
-      "versionRange": ["2.1.53"]
+      "versionRange": [
+        "2.1.53"
+      ]
    },
    {
      "image": "/blog/assetsdfda32866c4bc59af0526e52f31d1da2.webp",
      "id": "2026-04-20-daily-brief",
      "date": "2026-04-20",
-      "versionRange": ["2.1.50", "2.1.52"]
+      "versionRange": [
+        "2.1.50",
+        "2.1.52"
+      ]
    },
    {
      "image": "/blog/assets300abe7e259d293da6c5ed4f642a1be6.webp",
      "id": "2026-04-13-gateway-sidebar",
      "date": "2026-04-13",
-      "versionRange": ["2.1.48", "2.1.49"]
+      "versionRange": [
+        "2.1.48",
+        "2.1.49"
+      ]
    },
    {
      "image": "/blog/assets7ea204859aeb5aa9be5810a20ba1669a.webp",
      "id": "2026-04-06-auto-completion",
      "date": "2026-04-06",
-      "versionRange": ["2.1.47"]
+      "versionRange": [
+        "2.1.47"
+      ]
    },
    {
      "id": "2026-03-30-agent-tasks",
      "date": "2026-03-30",
-      "versionRange": ["2.1.45", "2.1.46"]
+      "versionRange": [
+        "2.1.45",
+        "2.1.46"
+      ]
    },
    {
      "image": "/blog/assets53e6ec9cf72554dbc1f8224fc0550a03.webp",
      "id": "2026-03-23-media-memory",
      "date": "2026-03-23",
-      "versionRange": ["2.1.44"]
+      "versionRange": [
+        "2.1.44"
+      ]
    },
    {
      "image": "https://hub-apac-1.lobeobjects.space/blog/assets/4a68a7644501cb513d08670b102a446e.webp",
      "id": "2026-03-16-search",
      "date": "2026-03-16",
-      "versionRange": ["2.1.38", "2.1.43"]
+      "versionRange": [
+        "2.1.38",
+        "2.1.43"
+      ]
    },
    {
      "id": "2026-02-08-runtime-auth",
      "date": "2026-02-08",
-      "versionRange": ["2.1.6", "2.1.26"]
+      "versionRange": [
+        "2.1.6",
+        "2.1.26"
+      ]
    },
    {
      "image": "/blog/assetsa8e504275f2cd891fabecca985998de0.webp",
      "id": "2026-01-27-v2",
      "date": "2026-01-27",
-      "versionRange": ["2.0.1", "2.1.5"]
+      "versionRange": [
+        "2.0.1",
+        "2.1.5"
+      ]
    },
    {
      "image": "/blog/assets7f3b38c1d76cceb91edb29d6b1eb60db.webp",
      "id": "2025-12-20-mcp",
      "date": "2025-12-20",
-      "versionRange": ["1.142.8", "1.143.0"]
+      "versionRange": [
+        "1.142.8",
+        "1.143.0"
+      ]
    },
    {
      "image": "/blog/assets3a7f0b29839603336e39e923b423409b.webp",
      "id": "2025-11-08-comfy-ui",
      "date": "2025-11-08",
-      "versionRange": ["1.133.5", "1.142.8"]
+      "versionRange": [
+        "1.133.5",
+        "1.142.8"
+      ]
    },
    {
      "image": "/blog/assets35e6aa692b0c16009c61964279514166.webp",
      "id": "2025-10-08-python",
      "date": "2025-10-08",
-      "versionRange": ["1.120.7", "1.133.5"]
+      "versionRange": [
+        "1.120.7",
+        "1.133.5"
+      ]
    },
    {
      "image": "/blog/assetsce5d6dc93676f974be2e162e8ace03f0.webp",
      "id": "2025-09-08-gemini",
      "date": "2025-09-08",
-      "versionRange": ["1.109.1", "1.120.7"]
+      "versionRange": [
+        "1.109.1",
+        "1.120.7"
+      ]
    },
    {
      "image": "/blog/assetsdf48eed9de76b7e37c269b294285f09d.webp",
      "id": "2025-08-08-image-generation",
      "date": "2025-08-08",
-      "versionRange": ["1.97.10", "1.109.1"]
+      "versionRange": [
+        "1.97.10",
+        "1.109.1"
+      ]
    },
    {
      "image": "/blog/assets902eb746fe2042fc2ea831c71002be72.webp",
      "id": "2025-07-08-mcp-market",
      "date": "2025-07-08",
-      "versionRange": ["1.93.3", "1.97.10"]
+      "versionRange": [
+        "1.93.3",
+        "1.97.10"
+      ]
    },
    {
      "image": "/blog/assets5cc27b8cae995074da20d4ffe06a1460.webp",
      "id": "2025-06-08-claude-4",
      "date": "2025-06-08",
-      "versionRange": ["1.84.27", "1.93.3"]
+      "versionRange": [
+        "1.84.27",
+        "1.93.3"
+      ]
    },
    {
      "image": "/blog/assets2a36d86a4eed6e7938dd6e9c684701ed.webp",
      "id": "2025-05-08-desktop-app",
      "date": "2025-05-08",
-      "versionRange": ["1.77.17", "1.84.27"]
+      "versionRange": [
+        "1.77.17",
+        "1.84.27"
+      ]
    },
    {
      "image": "/blog/assetsc0efdb82443556ae3acefe00099b3f23.webp",
      "id": "2025-04-06-exports",
      "date": "2025-04-06",
-      "versionRange": ["1.67.2", "1.77.17"]
+      "versionRange": [
+        "1.67.2",
+        "1.77.17"
+      ]
    },
    {
      "image": "/blog/assetse743f0a47127390dde766a0a790476db.webp",
      "id": "2025-03-02-new-models",
      "date": "2025-03-02",
-      "versionRange": ["1.49.13", "1.67.2"]
+      "versionRange": [
+        "1.49.13",
+        "1.67.2"
+      ]
    },
    {
      "image": "/blog/assets18168d5fe64ea34905a7e52fd82d0e9d.webp",
      "id": "2025-02-02-deepseek-r1",
      "date": "2025-02-02",
-      "versionRange": ["1.47.8", "1.49.12"]
+      "versionRange": [
+        "1.47.8",
+        "1.49.12"
+      ]
    },
    {
      "image": "/blog/assetsf9ed064fe764cbeff2f46910e7099a91.webp",
      "id": "2025-01-22-new-ai-provider",
      "date": "2025-01-22",
-      "versionRange": ["1.43.1", "1.47.7"]
+      "versionRange": [
+        "1.43.1",
+        "1.47.7"
+      ]
    },
    {
      "image": "/blog/assets2d409f43b58953ad5396c6beab8a0719.webp",
      "id": "2025-01-03-user-profile",
      "date": "2025-01-03",
-      "versionRange": ["1.34.1", "1.43.0"]
+      "versionRange": [
+        "1.34.1",
+        "1.43.0"
+      ]
    },
    {
      "image": "/blog/assets/d9cbfcbef130183bc490d515d8a38aa4.webp",
      "id": "2024-11-27-forkable-chat",
      "date": "2024-11-27",
-      "versionRange": ["1.33.1", "1.34.0"]
+      "versionRange": [
+        "1.33.1",
+        "1.34.0"
+      ]
    },
    {
      "image": "/blog/assets/2d678631c55369ba7d753c3ffcb73782.webp",
      "id": "2024-11-25-november-providers",
      "date": "2024-11-25",
-      "versionRange": ["1.30.1", "1.33.0"]
+      "versionRange": [
+        "1.30.1",
+        "1.33.0"
+      ]
    },
    {
      "image": "/blog/assets/f10a4b98782e36797c38071eed785c6f.webp",
      "id": "2024-11-06-share-text-json",
      "date": "2024-11-06",
-      "versionRange": ["1.26.1", "1.28.0"]
+      "versionRange": [
+        "1.26.1",
+        "1.28.0"
+      ]
    },
    {
      "image": "/blog/assets/944c671604833cd2457445b211ebba33.webp",
      "id": "2024-10-27-pin-assistant",
      "date": "2024-10-27",
-      "versionRange": ["1.19.1", "1.26.0"]
+      "versionRange": [
+        "1.19.1",
+        "1.26.0"
+      ]
    },
    {
      "image": "/blog/assets/f6d047a345e47a52592cff916c9a64ce.webp",
      "id": "2024-09-20-artifacts",
      "date": "2024-09-20",
-      "versionRange": ["1.17.1", "1.19.0"]
+      "versionRange": [
+        "1.17.1",
+        "1.19.0"
+      ]
    },
    {
      "image": "/blog/assets/d7e57f8e69f97b76b3c2414f3441b6e4.webp",
      "id": "2024-09-13-openai-o1-models",
      "date": "2024-09-13",
-      "versionRange": ["1.12.1", "1.17.0"]
+      "versionRange": [
+        "1.12.1",
+        "1.17.0"
+      ]
    },
    {
      "image": "/blog/assets/d6129350de510a62fe87b2d2f0fb9477.webp",
      "id": "2024-08-21-file-upload-and-knowledge-base",
      "date": "2024-08-21",
-      "versionRange": ["1.8.1", "1.12.0"]
+      "versionRange": [
+        "1.8.1",
+        "1.12.0"
+      ]
    },
    {
      "image": "/blog/assets/37d85fdfccff9ed56e9c6827faee01c7.webp",
      "id": "2024-08-02-lobe-chat-database-docker",
      "date": "2024-08-02",
-      "versionRange": ["1.6.1", "1.8.0"]
+      "versionRange": [
+        "1.6.1",
+        "1.8.0"
+      ]
    },
    {
      "image": "/blog/assets/39d7890f8cbe21e77db8d3c94f7f22e4.webp",
      "id": "2024-07-19-gpt-4o-mini",
      "date": "2024-07-19",
-      "versionRange": ["1.0.1", "1.6.0"]
+      "versionRange": [
+        "1.0.1",
+        "1.6.0"
+      ]
    },
    {
      "image": "/blog/assets/eb477e62217f4d1b644eff975c7ac168.webp",
      "id": "2024-06-19-lobe-chat-v1",
      "date": "2024-06-19",
-      "versionRange": ["0.147.0", "1.0.0"]
+      "versionRange": [
+        "0.147.0",
+        "1.0.0"
+      ]
    },
    {
      "image": "/blog/assets/8a8d361b4c0cce6da350cc0de65c0ad6.webp",
      "id": "2024-02-14-ollama",
      "date": "2024-02-14",
-      "versionRange": ["0.125.1", "0.127.0"]
+      "versionRange": [
+        "0.125.1",
+        "0.127.0"
+      ]
    },
    {
      "image": "/blog/assets/9498087e85f27e692716a63cb3b58d79.webp",
      "id": "2024-02-08-sso-oauth",
      "date": "2024-02-08",
-      "versionRange": ["0.118.1", "0.125.0"]
+      "versionRange": [
+        "0.118.1",
+        "0.125.0"
+      ]
    },
    {
      "image": "/blog/assets/603fefbb944bc6761ebdab5956fc0084.webp",
      "id": "2023-12-22-dalle-3",
      "date": "2023-12-22",
-      "versionRange": ["0.102.1", "0.118.0"]
+      "versionRange": [
+        "0.102.1",
+        "0.118.0"
+      ]
    },
    {
      "image": "/blog/assets/8d4c2cc0ce8654fa8ac06cc036a7f941.webp",
      "id": "2023-11-19-tts-stt",
      "date": "2023-11-19",
-      "versionRange": ["0.101.1", "0.102.0"]
+      "versionRange": [
+        "0.101.1",
+        "0.102.0"
+      ]
    },
    {
      "image": "/blog/assets/d47654360d626f80144cdedb979a3526.webp",
      "id": "2023-11-14-gpt4-vision",
      "date": "2023-11-14",
-      "versionRange": ["0.90.0", "0.101.0"]
+      "versionRange": [
+        "0.90.0",
+        "0.101.0"
+      ]
    },
    {
      "image": "/blog/assets/50b38eac1769ae6f13aef72f3d725eec.webp",
      "id": "2023-09-09-plugin-system",
      "date": "2023-09-09",
-      "versionRange": ["0.67.0", "0.72.0"]
+      "versionRange": [
+        "0.67.0",
+        "0.72.0"
+      ]
    }
  ]
 }
@@ -41,7 +41,7 @@ We utilize stylelint to standardize the style of our CSS code. In the configurat

 ### Style Checking

-You don't need to manually run these checks. The project is configured with Git hooks to automatically run lint-staged when you commit code, which will check if your committed files comply with the above standards.
+You don't need to manually run these checks. The project is configured with husky to automatically run lint-staged when you commit code, which will check if your committed files comply with the above standards.

 ## Contribution Process

@@ -39,7 +39,7 @@ Prettier 负责代码格式化，以保证代码的一致性。您可以在 `.pr

 ### 风格检查

-你不需要手动运行这些检查，项目配置了 Git hooks 会在您提交代码时自动运行 lint-staged 检查你提交的文件是否符合以上规范。
+你不需要手动运行这些检查，项目配置了 husky 会在您提交代码时自动运行 lint-staged 检查你提交的文件是否符合以上规范。

 ## 贡献流程

@@ -188,7 +188,6 @@ table agent_eval_benchmarks {
 table agent_eval_datasets {
  id text [pk, not null]
  benchmark_id text [not null]
-  source_experiment_id text
  identifier text [not null]
  user_id text
  name text [not null]
@@ -203,39 +202,10 @@ table agent_eval_datasets {
  indexes {
    (identifier, user_id) [name: 'agent_eval_datasets_identifier_user_id_unique', unique]
    benchmark_id [name: 'agent_eval_datasets_benchmark_id_idx']
-    source_experiment_id [name: 'agent_eval_datasets_source_experiment_id_idx']
    user_id [name: 'agent_eval_datasets_user_id_idx']
  }
 }

-table agent_eval_experiment_benchmarks {
-  experiment_id text [not null]
-  benchmark_id text [not null]
-  user_id text [not null]
-  created_at "timestamp with time zone" [not null, default: `now()`]
-
-  indexes {
-    (experiment_id, benchmark_id) [pk]
-    benchmark_id [name: 'agent_eval_experiment_benchmarks_benchmark_id_idx']
-    user_id [name: 'agent_eval_experiment_benchmarks_user_id_idx']
-  }
-}
-
-table agent_eval_experiments {
-  id text [pk, not null]
-  user_id text [not null]
-  name text [not null]
-  description text
-  metadata jsonb
-  accessed_at "timestamp with time zone" [not null, default: `now()`]
-  created_at "timestamp with time zone" [not null, default: `now()`]
-  updated_at "timestamp with time zone" [not null, default: `now()`]
-
-  indexes {
-    user_id [name: 'agent_eval_experiments_user_id_idx']
-  }
-}
-
 table agent_eval_run_topics {
  user_id text [not null]
  run_id text [not null]
@@ -258,8 +228,6 @@ table agent_eval_run_topics {
 table agent_eval_runs {
  id text [pk, not null]
  dataset_id text [not null]
-  experiment_id text
-  parent_run_id text
  target_agent_id text
  user_id text [not null]
  name text
@@ -272,10 +240,7 @@ table agent_eval_runs {
  updated_at "timestamp with time zone" [not null, default: `now()`]

  indexes {
-    
    dataset_id [name: 'agent_eval_runs_dataset_id_idx']
-    experiment_id [name: 'agent_eval_runs_experiment_id_idx']
-    parent_run_id [name: 'agent_eval_runs_parent_run_id_idx']
    user_id [name: 'agent_eval_runs_user_id_idx']
    status [name: 'agent_eval_runs_status_idx']
    target_agent_id [name: 'agent_eval_runs_target_agent_id_idx']
@@ -782,56 +747,6 @@ table generations {
  }
 }

-table llm_generation_tracing {
-  id uuid [pk, not null, default: `gen_random_uuid()`]
-  scenario text [not null]
-  prompt_version text [not null]
-  prompt_hash text [not null]
-  schema_name text
-  user_id text [not null]
-  agent_id text
-  topic_id text
-  trigger text
-  parent_tracing_id uuid
-  provider text
-  model text
-  success boolean [not null]
-  error_code text
-  error_detail text
-  validation_failed boolean [not null, default: false]
-  input_hash text
-  input_hint text
-  latency_ms integer
-  input_tokens integer
-  output_tokens integer
-  cost_usd "numeric(12, 8)"
-  storage_key text
-  feedback_signal text
-  feedback_score "numeric(3, 2)"
-  feedback_source text
-  feedback_data jsonb
-  feedback_updated_at "timestamp with time zone"
-  trace_id text
-  span_id text
-  metadata jsonb [default: `{}`]
-  created_at "timestamp with time zone" [not null, default: `now()`]
-
-  indexes {
-    scenario [name: 'llm_generation_tracing_scenario_idx']
-    prompt_version [name: 'llm_generation_tracing_prompt_version_idx']
-    user_id [name: 'llm_generation_tracing_user_id_idx']
-    agent_id [name: 'llm_generation_tracing_agent_id_idx']
-    topic_id [name: 'llm_generation_tracing_topic_id_idx']
-    provider [name: 'llm_generation_tracing_provider_idx']
-    model [name: 'llm_generation_tracing_model_idx']
-    success [name: 'llm_generation_tracing_success_idx']
-    error_code [name: 'llm_generation_tracing_error_code_idx']
-    validation_failed [name: 'llm_generation_tracing_validation_failed_idx']
-    feedback_signal [name: 'llm_generation_tracing_feedback_signal_idx']
-    created_at [name: 'llm_generation_tracing_created_at_idx']
-  }
-}
-
 table message_chunks {
  message_id text
  chunk_id uuid
@@ -1297,6 +1212,22 @@ table oidc_sessions {
  }
 }

+table page_shares {
+  id text [pk, not null]
+  document_id text [not null]
+  user_id text [not null]
+  visibility text [not null, default: 'private']
+  page_view_count integer [not null, default: 0]
+  accessed_at "timestamp with time zone" [not null, default: `now()`]
+  created_at "timestamp with time zone" [not null, default: `now()`]
+  updated_at "timestamp with time zone" [not null, default: `now()`]
+
+  indexes {
+    document_id [name: 'page_shares_document_id_unique', unique]
+    user_id [name: 'page_shares_user_id_idx']
+  }
+}
+
 table chunks {
  id uuid [pk, not null, default: `gen_random_uuid()`]
  text text
@@ -2252,6 +2183,10 @@ ref: threads.source_message_id - messages.id

 ref: messages.message_group_id > message_groups.id

+ref: page_shares.document_id > documents.id
+
+ref: page_shares.user_id - users.id
+
 ref: sessions.group_id - session_groups.id

 ref: topic_documents.document_id > documents.id
@@ -51,23 +51,6 @@ Supported crawler types are listed below:

 ---

-## `JINA_USE_CN_DOMAINS`
-
-Switch Jina Reader/Search to the mainland China fallback domains.
-
-```env
-JINA_USE_CN_DOMAINS=true
-```
-
-When enabled, LobeHub replaces the Jina endpoints as follows:
-
- `https://r.jina.ai` → `https://r.jinaai.cn`
- `https://s.jina.ai` → `https://s.jinaai.cn`
-
-> 📌 Useful when `jina.ai` is unreachable from mainland China. Authentication and API behavior stay the same.
-
---
-
 ## `CRAWL_CONCURRENCY`

 Controls crawler concurrency per crawl task. The default is `3`. On low-resource servers, use `1` to reduce CPU spikes.
@@ -46,23 +46,6 @@ CRAWLER_IMPLS="naive,search1api"

 ---

-## `JINA_USE_CN_DOMAINS`
-
-将 Jina Reader / Search 切换到中国大陆可用的备用域名。
-
-```env
-JINA_USE_CN_DOMAINS=true
-```
-
-启用后，LobeHub 会将 Jina 端点替换为：
-
- `https://r.jina.ai` → `https://r.jinaai.cn`
- `https://s.jina.ai` → `https://s.jinaai.cn`
-
-> 📌 适用于中国大陆网络无法访问 `jina.ai` 的场景。认证方式与 API 行为保持不变。
-
---
-
 ## `CRAWL_CONCURRENCY`

 控制单次网页抓取任务的并发数量，默认值为 `3`。在低配置服务器上建议设置为 `1` 以降低 CPU 峰值。
@@ -52,18 +52,18 @@ When using the `turn` mode, the API Keys will be retrieved in a polling manner a

 The `DEFAULT_AGENT_CONFIG` is used to configure the default settings for the LobeHub default agent. It supports various data types and structures, including key-value pairs, nested fields, array values, and more. The table below provides detailed information on the configuration options, examples, and corresponding explanations for the `DEFAULT_AGENT_CONFIG` environment variable:

-| Configuration Type      | Example                                                                                                            | Explanation                                                                                                        |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
-| Basic Key-Value Pair    | `model=gpt-4`                                                                                                      | Set the model to `gpt-4`.                                                                                          |
-| Nested Field            | `tts.sttLocale=en-US`                                                                                              | Set the language locale for the text-to-speech service to `en-US`.                                                 |
-| Array                   | `plugins=search-engine,lobe-image-designer`                                                                        | Enable the `search-engine` and `lobe-image-designer` plugins.                                                      |
-| Chinese Comma           | `plugins=search-engine，lobe-image-designer`                                                                        | Same as above, demonstrating support for Chinese comma separation.                                                 |
-| Multiple Configurations | `model=glm-4;provider=zhipu`                                                                                       | Set the model to `glm-4` and the model provider to `zhipu`.                                                        |
-| Numeric Value           | `params.max_tokens=300`, `chatConfig.historyCount=5`                                                               | Set the maximum tokens to `300`, Set the number of historical messages to 5.                                       |
-| Boolean Value           | `chatConfig.enableHistoryCount=true`, `chatConfig.enableCompressThreshold=true`, `chatConfig.enableStreaming=true` | Enable history length limit, history length compression threshold, and streaming output.                           |
-| Special Characters      | `inputTemplate="Hello; I am a bot;"`                                                                               | Set the input template to `Hello; I am a bot;`.                                                                    |
-| Error Handling          | `model=gpt-4;maxToken`                                                                                             | Ignore invalid entry `maxToken` and only parse `model=gpt-4`.                                                      |
-| Value Override          | `model=gpt-4;model=gpt-4-1106-preview`                                                                             | If a key is repeated, use the value that appears last; in this case, the value of `model` is `gpt-4-1106-preview`. |
+| Configuration Type      | Example                                                                                                                  | Explanation                                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
+| Basic Key-Value Pair    | `model=gpt-4`                                                                                                            | Set the model to `gpt-4`.                                                                                          |
+| Nested Field            | `tts.sttLocale=en-US`                                                                                                    | Set the language locale for the text-to-speech service to `en-US`.                                                 |
+| Array                   | `plugins=search-engine,lobe-image-designer`                                                                              | Enable the `search-engine` and `lobe-image-designer` plugins.                                                      |
+| Chinese Comma           | `plugins=search-engine，lobe-image-designer`                                                                              | Same as above, demonstrating support for Chinese comma separation.                                                 |
+| Multiple Configurations | `model=glm-4;provider=zhipu`                                                                                             | Set the model to `glm-4` and the model provider to `zhipu`.                                                        |
+| Numeric Value           | `params.max_tokens=300`, `chatConfig.historyCount=5`                                                                     | Set the maximum tokens to `300`, Set the number of historical messages to 5.                                       |
+| Boolean Value           | `chatConfig.enableAutoCreateTopic=true`, `chatConfig.enableCompressThreshold=true`, `chatConfig.enableHistoryCount=true` | Enable automatic topic creation, History length compression threshold, number of historical records.               |
+| Special Characters      | `inputTemplate="Hello; I am a bot;"`                                                                                     | Set the input template to `Hello; I am a bot;`.                                                                    |
+| Error Handling          | `model=gpt-4;maxToken`                                                                                                   | Ignore invalid entry `maxToken` and only parse `model=gpt-4`.                                                      |
+| Value Override          | `model=gpt-4;model=gpt-4-1106-preview`                                                                                   | If a key is repeated, use the value that appears last; in this case, the value of `model` is `gpt-4-1106-preview`. |

 Further reading:

@@ -49,18 +49,18 @@ LobeHub 在部署时提供了一些额外的配置项，你可以使用环境变

 `DEFAULT_AGENT_CONFIG` 用于配置 LobeHub 默认助理的默认配置。它支持多种数据类型和结构，包括键值对、嵌套字段、数组值等。下表详细说明了 `DEFAULT_AGENT_CONFIG` 环境变量的配置项、示例以及相应解释：

-| 配置项类型 | 示例                                                                                                                | 解释                                                    |
-| ----- | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| 基本键值对 | `model=gpt-4`                                                                                                     | 设置模型为 `gpt-4`。                                        |
-| 嵌套字段  | `tts.sttLocale=en-US`                                                                                             | 设置文本到语音服务的语言区域为 `en-US`。                              |
-| 数组    | `plugins=search-engine,lobe-image-designer`                                                                       | 启用 `search-engine` 和 `lobe-image-designer` 插件。        |
-| 中文逗号  | `plugins=search-engine，lobe-image-designer`                                                                       | 同上，演示支持中文逗号分隔。                                        |
-| 多个配置项 | `model=glm-4;provider=zhipu`                                                                                      | 设置模型为 `glm-4` 且模型服务商为 `zhipu`。                        |
-| 数字值   | `params.max_tokens=300`, `chatConfig.historyCount=5`                                                              | 设置最大令牌数为 `300`，设置历史消息条数为 5。                           |
-| 布尔值   | `chatConfig.enableHistoryCount=true`,`chatConfig.enableCompressThreshold=true`, `chatConfig.enableStreaming=true` | 启用历史消息数量限制，历史长度压缩阈值，流式输出。                             |
-| 特殊字符  | `inputTemplate="Hello; I am a bot;"`                                                                              | 设置输入模板为 `Hello; I am a bot;`。                         |
-| 错误处理  | `model=gpt-4;maxToken`                                                                                            | 忽略无效条目 `maxToken`，仅解析出 `model=gpt-4`。                 |
-| 值覆盖   | `model=gpt-4;model=gpt-4-1106-preview`                                                                            | 如果键重复，使用最后一次出现的值，此处 `model` 的值为 `gpt-4-1106-preview`。 |
+| 配置项类型 | 示例                                                                                                                      | 解释                                                    |
+| ----- | ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| 基本键值对 | `model=gpt-4`                                                                                                           | 设置模型为 `gpt-4`。                                        |
+| 嵌套字段  | `tts.sttLocale=en-US`                                                                                                   | 设置文本到语音服务的语言区域为 `en-US`。                              |
+| 数组    | `plugins=search-engine,lobe-image-designer`                                                                             | 启用 `search-engine` 和 `lobe-image-designer` 插件。        |
+| 中文逗号  | `plugins=search-engine，lobe-image-designer`                                                                             | 同上，演示支持中文逗号分隔。                                        |
+| 多个配置项 | `model=glm-4;provider=zhipu`                                                                                            | 设置模型为 `glm-4` 且模型服务商为 `zhipu`。                        |
+| 数字值   | `params.max_tokens=300`, `chatConfig.historyCount=5`                                                                    | 设置最大令牌数为 `300`，设置历史消息条数为 5。                           |
+| 布尔值   | `chatConfig.enableAutoCreateTopic=true`,`chatConfig.enableCompressThreshold=true`, `chatConfig.enableHistoryCount=true` | 启用自动创建主题，历史长度压缩阈值，历史记录条数。                             |
+| 特殊字符  | `inputTemplate="Hello; I am a bot;"`                                                                                    | 设置输入模板为 `Hello; I am a bot;`。                         |
+| 错误处理  | `model=gpt-4;maxToken`                                                                                                  | 忽略无效条目 `maxToken`，仅解析出 `model=gpt-4`。                 |
+| 值覆盖   | `model=gpt-4;model=gpt-4-1106-preview`                                                                                  | 如果键重复，使用最后一次出现的值，此处 `model` 的值为 `gpt-4-1106-preview`。 |

 相关阅读：

@@ -167,13 +167,6 @@ If you need to use Azure OpenAI to provide model services, you can refer to the
 - Default: `https://api.anthropic.com`
 - Example: `https://my-anthropic-proxy.com`

-### `ANTHROPIC_CLIENT_TIMEOUT`
-
- Type: Optional
- Description: Anthropic SDK client request timeout in milliseconds. This timeout is also used by Anthropic-compatible providers that rely on the Anthropic SDK.
- Default: `295000`
- Example: `780000`
-
 ## AWS Bedrock

 ### `ENABLED_AWS_BEDROCK`
@@ -165,13 +165,6 @@ LobeHub 在部署时提供了丰富的模型服务商相关的环境变量，你
 - 默认值：`https://api.anthropic.com`
 - 示例：`https://my-anthropic-proxy.com`

-### `ANTHROPIC_CLIENT_TIMEOUT`
-
- 类型：可选
- 描述：Anthropic SDK 客户端请求超时时间，单位为毫秒。依赖 Anthropic SDK 的 Anthropic 兼容服务商也会使用此超时时间。
- 默认值：`295000`
- 示例：`780000`
-
 ## AWS Bedrock

 ### `ENABLED_AWS_BEDROCK`
@@ -117,13 +117,11 @@ By connecting a Discord channel to your LobeHub agent, users can interact with t
  ![](https://hub-apac-1.lobeobjects.space/docs/d83686461d14690e87512491c1349b6b.webp)

  Copy the generated URL, open it in your browser, select the server you want to add the bot to, and click **Authorize**.
-
-  > **Private channels need explicit access.** Server-level authorization only grants the bot category/server defaults. If a channel is marked **Private Channel**, Discord ignores the bot's server-wide role and the bot won't receive any events there — including @mentions — until you open the channel's **Settings → Permissions** and add the bot (or a role it has) under **Members and roles**. You can also click **Sync Now** to make the channel inherit its category's permissions.
 </Steps>

 ## Step 4: Test the Connection

-Back in LobeHub's channel settings for Discord, click **Test Connection** to verify everything is configured correctly. Then send a message to your bot on Discord to confirm it responds.
+Back in LobeHub's channel settings for Discord, click **Test Connection** to verify everything is configured correctly. Then send a message to your bot in Discord to confirm it responds.

 ## Step 5: Set Your Platform Identity (Recommended)

@@ -193,6 +191,5 @@ See the [Channels overview](/docs/usage/channels/overview#direct-message-policy)
 ## Troubleshooting

 - **Bot not responding in server:** Confirm the bot has been invited to the server with the correct permissions, and Message Content Intent is enabled. If **Group Policy** is `Disabled` or `Allowlist`, double-check the channel is in **Allowed Channel IDs**. If **Allowed User IDs** is set, the sender's user ID must be in it.
- **@mention doesn't reach the bot in one specific channel:** The channel is likely a **Private Channel**. Discord drops every event for users/bots not explicitly listed in that channel's permissions, no matter what server-wide role they have. Open the channel's **Settings → Permissions**, click **Add members or roles**, and add the bot (or a role it has). Alternatively click **Sync Now** to inherit the parent category's permissions. A quick visual check: if the bot's name renders without an underline/link styling when you type `@<botname>`, Discord thinks it has no access to that channel.
 - **Bot not responding to DMs:** Open **Advanced Settings** and confirm **DM Policy** is not set to `Disabled`. If **Allowed User IDs** is set, make sure the sender's Discord user ID is in it.
 - **Test Connection failed:** Double-check the Application ID, Bot Token, and Public Key are correct.
@@ -116,8 +116,6 @@ tags:
  ![](https://hub-apac-1.lobeobjects.space/docs/2f6350e6bfe770e0e64b18762af3b63e.webp)

  复制生成的链接，在浏览器中打开，选择您希望添加机器人的服务器，然后点击 **授权**。
-
-  > **私有频道需要单独授权。** 服务器层级的授权只会给机器人分类 / 服务器的默认权限。如果某个频道开启了 **Private Channel（私有频道）**，Discord 会忽略机器人在服务器层级的角色，机器人在该频道收不到任何事件（包括 @提及），直到你在频道的 **设置 → Permissions（权限）** 中点击 **Add members or roles**，把机器人本身或它持有的角色加进来。也可以直接点 **Sync Now** 让频道继承分类的权限。
 </Steps>

 ## 第四步：测试连接
@@ -192,6 +190,5 @@ LobeHub 通过三层叠加配置控制入站消息，全部位于 **高级设置
 ## 故障排除

 - **机器人未在服务器中响应：** 确认机器人已被邀请到服务器并拥有正确的权限，同时启用了消息内容意图。如果 **群组策略** 是 `Disabled` 或 `Allowlist`，确认目标频道在 **允许的频道 ID** 列表里。如果 **允许的用户 ID** 已填，发送者的用户 ID 必须在列表里。
- **某个频道里 @不到机器人：** 通常是因为该频道是 **Private Channel（私有频道）**。Discord 会丢弃所有未被显式加入频道权限列表的用户 / 机器人的事件，无论他们在服务器层级是什么角色。打开该频道的 **设置 → Permissions（权限）**，点击 **Add members or roles**，把机器人或它持有的角色加进来；或者点 **Sync Now** 让频道继承父分类的权限。一个快速肉眼判断：输入 `@<机器人名>` 时如果出现的机器人名字没有下划线 / 链接样式，说明 Discord 认为它无权访问该频道。
 - **机器人不回私信：** 打开 **高级设置**，确认 **私信策略** 不是 `Disabled`。如果 **允许的用户 ID** 已填，确认发起方的 Discord 用户 ID 在列表里。
 - **测试连接失败：** 仔细检查应用程序 ID、机器人令牌和公钥是否正确。
@@ -3,7 +3,7 @@ title: Connect LobeHub to Feishu (飞书)
 description: >-
  Learn how to create a Feishu custom app and connect it to your LobeHub agent
  as a message channel, enabling your AI assistant to interact with team members
-  on Feishu.
+  in Feishu chats.
 tags:
  - Feishu
  - 飞书
@@ -14,7 +14,7 @@ tags:

 # Connect LobeHub to Feishu (飞书)

-By connecting a Feishu channel to your LobeHub agent, team members can interact with the AI assistant directly on Feishu through private chats and group conversations.
+By connecting a Feishu channel to your LobeHub agent, team members can interact with the AI assistant directly in Feishu private chats and group conversations.

 > If you are using the international version (Lark), please refer to the [Lark setup guide](/docs/usage/channels/lark).

@@ -172,7 +172,7 @@ By connecting a Feishu channel to your LobeHub agent, team members can interact

 ## Step 6: Test the Connection

-Back in LobeHub's channel settings, click **Test Connection** to verify the credentials. Then find your bot on Feishu by searching its name and send it a message to confirm it responds.
+Back in LobeHub's channel settings, click **Test Connection** to verify the credentials. Then find your bot in Feishu by searching its name and send it a message to confirm it responds.

 ## Step 7: Set Your Platform Identity (Recommended)

@@ -13,7 +13,7 @@ tags:

 # Connect LobeHub to Lark

-By connecting a Lark channel to your LobeHub agent, team members can interact with the AI assistant directly on Lark through private chats and group conversations.
+By connecting a Lark channel to your LobeHub agent, team members can interact with the AI assistant directly in Lark private chats and group conversations.

 > If you are using the Chinese version (飞书), please refer to the [Feishu setup guide](/docs/usage/channels/feishu).

@@ -163,7 +163,7 @@ By connecting a Lark channel to your LobeHub agent, team members can interact wi

 ## Step 6: Test the Connection

-Back in LobeHub's channel settings, click **Test Connection** to verify the credentials. Then find your bot on Lark by searching its name and send it a message to confirm it responds.
+Back in LobeHub's channel settings, click **Test Connection** to verify the credentials. Then find your bot in Lark by searching its name and send it a message to confirm it responds.

 ## Step 7: Set Your Platform Identity (Recommended)

--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Innei	577c8e2869	🗃️ feat(database): add page shares schema	2026-05-20 16:00:00 +08:00
lobehubbot	694a25822f	🔖 chore(release): release version v2.2.0 [skip ci]	2026-05-18 04:43:53 +00:00