✨ feat(runtime): refine runtime request types

* fix: attach diagnostic context to ProcessorError/PipelineError

* fix: include cause summary in PipelineError message

* fix: pass structured cause to ProcessorError

* fix: enhance PlaceholderVariablesProcessor with diagnostic context

* 🐛 fix: preserve placeholderVariablesProcessed count for no-op messages

processMessagePlaceholdersWithDiagnostics always returns a spread {...message},
so the identity check `processed !== message` was always true and the count
incremented even when content was unchanged (e.g. messages with no placeholders
or only unresolved `{{missing}}` tokens). Restore the JSON-equality comparison
used by the pre-PR `processMessagePlaceholders` path.

Add regression coverage for the no-op cases and for new error paths:
- only-unresolved string content, only-unresolved array text parts, mixed batch
- per-message isolation when a generator throws
- defensive validation when variableGenerators is undefined / null

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.agents/skills/add-provider-doc/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: add-provider-doc
-description: Guide for adding new AI provider documentation. Use when adding documentation for a new AI provider (like OpenAI, Anthropic, etc.), including usage docs, environment variables, Docker config, and image resources. Triggers on provider documentation tasks.
+description: Add documentation for a new AI provider — usage docs, env vars, Docker config, image resources.
+disable-model-invocation: true
+argument-hint: '[provider-name]'
 ---
 
 # Adding New AI Provider Documentation

.agents/skills/add-setting-env/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: add-setting-env
-description: Guide for adding environment variables to configure user settings. Use when implementing server-side environment variables that control default values for user settings. Triggers on env var configuration or setting default value tasks.
+description: Add server-side environment variables that control default values for user settings.
+disable-model-invocation: true
+argument-hint: '[setting-name]'
 ---
 
 # Adding Environment Variable for User Settings

.agents/skills/builtin-tool/SKILL.md

@@ -19,11 +19,11 @@ A builtin tool is a package the agent runtime can call. It ships **five faces**:
 
 ## Read These First
 
-| Question                                                                             | Doc                                |
-| ------------------------------------------------------------------------------------ | ---------------------------------- |
-| Where do files live? What does each face do? Wiring?                                 | [architecture.md](architecture.md) |
-| How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](tool-design.md)   |
-| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui.md](ui.md)                     |
+| Question                                                                             | Doc                                           |
+| ------------------------------------------------------------------------------------ | --------------------------------------------- |
+| Where do files live? What does each face do? Wiring?                                 | [architecture.md](references/architecture.md) |
+| How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](references/tool-design.md)   |
+| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui.md](references/ui.md)                     |
 
 ---
 
@@ -109,7 +109,7 @@ Before opening the PR:
 - [ ] Placeholder added if the API has a perceivable execution lag (search, list, crawl).
 - [ ] Streaming added for APIs that emit incremental output (run command, write file, code execution).
 - [ ] Intervention added if `humanIntervention` is set in the manifest.
-- [ ] All registry files updated (see [architecture.md → Registry wiring](architecture.md#registry-wiring)).
+- [ ] All registry files updated (see [architecture.md → Registry wiring](references/architecture.md#registry-wiring)).
 - [ ] i18n keys in `src/locales/default/plugin.ts` plus dev seeds in `en-US`/`zh-CN`.
 - [ ] `bunx vitest run --silent='passed-only' 'packages/builtin-tool-<name>'` passes.
 - [ ] `bun run type-check` passes.

.agents/skills/builtin-tool/references/architecture.md

@@ -213,7 +213,7 @@ The runtime hands every executor method an optional `BuiltinToolContext` as the
 | `operationId`                 | Operation lineage (use for cancellation, tracing)              |
 | `scope`                       | `'task' \| 'agent' \| …` — toggles default behaviors           |
 | `signal: AbortSignal`         | Honor for long-running ops                                     |
-| `stepContext`                 | Cross-message runtime state (GTD todos, etc.)                  |
+| `stepContext`                 | Cross-message runtime state (lobe-agent todos, etc.)           |
 | `registerAfterCompletion(cb)` | Defer side-effects past message-update race                    |
 | `groupOrchestration`          | Group orchestration callbacks                                  |
 

.agents/skills/builtin-tool/references/ui.md

@@ -18,6 +18,27 @@ The two reference tools to read end-to-end:
 
 ---
 
+## Tool Render 设计原则（中文草案）
+
+这些原则用于判断一个 builtin tool 的 Inspector / Render / Placeholder / Streaming / Intervention / Portal 应该做什么，以及做到什么程度。
+
+1. **先保证折叠态可读。** 每个 API 都必须有 Inspector；用户不展开也应该能看懂 “正在做什么 / 对什么做 / 当前结果是什么”。Inspector 不应该只展示函数名和原始参数。
+2. **Inspector 是一句话，不是详情页。** 优先表达动作、关键对象、数量、状态，例如 “分析图片 3 张”“搜索 12 个结果”“读取 config.json”。长文本、列表和结构化结果放到 Render 或 Portal。
+3. **Inspector 要覆盖执行生命周期。** `args` 还在 streaming、工具执行中、执行完成、执行失败时都应该有稳定展示；必要时同时读取 `args`、`partialArgs` 和 `pluginState`，避免出现空白、跳变或只显示半截参数。
+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 可以存在，但应默认收起或放到调试区；主界面先回答用户最关心的问题：工具做了什么，结果值不值得信任，下一步能做什么。
+
+---
+
 ## 0. Shared Style Rules
 
 These apply across every surface.

.agents/skills/chat-sdk/SKILL.md

@@ -8,6 +8,7 @@ description: >
   (4) Send interactive cards or stream AI responses to chat platforms.
   Triggers on "chat sdk", "chat bot", "slack bot", "teams bot", "discord bot", "@chat-adapter",
   building bots that work across multiple chat platforms.
+user-invocable: false
 ---
 
 # Chat SDK

.agents/skills/cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cli
-description: LobeHub CLI (@lobehub/cli) development guide. Use when working on CLI commands, adding new subcommands, fixing CLI bugs, or understanding CLI architecture. Triggers on CLI development, command implementation, or `lh` command questions.
+description: LobeHub CLI (@lobehub/cli) development guide — commands, subcommands, architecture.
 disable-model-invocation: true
 ---
 

.agents/skills/data-fetching/references/walkthrough.md

@@ -0,0 +1,244 @@
+# Walkthrough: Adding a New Feature End-to-End
+
+This is a worked example of the canonical 6-step recipe applied to a new entity (`Dataset`), showing a variant of the main skill's pattern: **a list keyed by a parent id** (`datasetMap[benchmarkId]`), useful when the same shape appears under different parents.
+
+If you only need the canonical (single-array) pattern, the main `SKILL.md` already shows it for `Benchmark`. Read this file when you need the parent-keyed Map variant, or when you want a checklist-style walkthrough.
+
+## Step 1: Add Service methods
+
+```typescript
+class AgentEvalService {
+  async listDatasets(benchmarkId: string) {
+    return lambdaClient.agentEval.listDatasets.query({ benchmarkId });
+  }
+  async getDataset(id: string) {
+    return lambdaClient.agentEval.getDataset.query({ id });
+  }
+  async createDataset(params: CreateDatasetParams) {
+    return lambdaClient.agentEval.createDataset.mutate(params);
+  }
+  // updateDataset / deleteDataset follow the same shape
+}
+```
+
+## Step 2: Reducer (optimistic updates)
+
+```typescript
+// src/store/eval/slices/dataset/reducer.ts
+export type DatasetDispatch =
+  | { type: 'addDataset'; value: Dataset }
+  | { type: 'updateDataset'; id: string; value: Partial<Dataset> }
+  | { type: 'deleteDataset'; id: string };
+
+export const datasetReducer = (state: Dataset[] = [], payload: DatasetDispatch): Dataset[] =>
+  produce(state, (draft) => {
+    switch (payload.type) {
+      case 'addDataset':
+        draft.unshift(payload.value);
+        break;
+      case 'updateDataset': {
+        const i = draft.findIndex((item) => item.id === payload.id);
+        if (i !== -1) draft[i] = { ...draft[i], ...payload.value };
+        break;
+      }
+      case 'deleteDataset': {
+        const i = draft.findIndex((item) => item.id === payload.id);
+        if (i !== -1) draft.splice(i, 1);
+        break;
+      }
+    }
+  });
+```
+
+## Step 3: Store slice
+
+```typescript
+// src/store/eval/slices/dataset/initialState.ts
+export interface DatasetData {
+  currentPage: number;
+  hasMore: boolean;
+  isLoading: boolean;
+  items: Dataset[];
+  pageSize: number;
+  total: number;
+}
+
+export interface DatasetSliceState {
+  // Map keyed by benchmarkId — multiple parent contexts share the slice
+  datasetMap: Record<string, DatasetData>;
+  // Single item for modal display
+  datasetDetail: Dataset | null;
+  isLoadingDatasetDetail: boolean;
+  loadingDatasetIds: string[];
+}
+
+export const datasetInitialState: DatasetSliceState = {
+  datasetMap: {},
+  datasetDetail: null,
+  isLoadingDatasetDetail: false,
+  loadingDatasetIds: [],
+};
+```
+
+```typescript
+// src/store/eval/slices/dataset/action.ts
+const FETCH_DATASETS_KEY = 'FETCH_DATASETS';
+const FETCH_DATASET_DETAIL_KEY = 'FETCH_DATASET_DETAIL';
+
+export const createDatasetSlice: StateCreator<EvalStore, any, [], DatasetAction> = (set, get) => ({
+  // Cache key includes benchmarkId so each parent has its own SWR entry
+  useFetchDatasets: (benchmarkId) =>
+    useClientDataSWR(
+      benchmarkId ? [FETCH_DATASETS_KEY, benchmarkId] : null,
+      () => agentEvalService.listDatasets(benchmarkId!),
+      {
+        onSuccess: (data) => {
+          set({
+            datasetMap: {
+              ...get().datasetMap,
+              [benchmarkId!]: {
+                currentPage: 1,
+                hasMore: false,
+                isLoading: false,
+                items: data,
+                pageSize: data.length,
+                total: data.length,
+              },
+            },
+          });
+        },
+      },
+    ),
+
+  useFetchDatasetDetail: (id) =>
+    useClientDataSWR(
+      id ? [FETCH_DATASET_DETAIL_KEY, id] : null,
+      () => agentEvalService.getDataset(id!),
+      {
+        onSuccess: (data) => set({ datasetDetail: data, isLoadingDatasetDetail: false }),
+      },
+    ),
+
+  refreshDatasets: (benchmarkId) => mutate([FETCH_DATASETS_KEY, benchmarkId]),
+  refreshDatasetDetail: (id) => mutate([FETCH_DATASET_DETAIL_KEY, id]),
+
+  // CREATE with optimistic update — note the temp id pattern
+  createDataset: async (params) => {
+    const tmpId = Date.now().toString();
+    const { benchmarkId } = params;
+
+    get().internal_dispatchDataset(
+      { type: 'addDataset', value: { ...params, id: tmpId, createdAt: Date.now() } as any },
+      benchmarkId,
+    );
+    get().internal_updateDatasetLoading(tmpId, true);
+
+    try {
+      const result = await agentEvalService.createDataset(params);
+      await get().refreshDatasets(benchmarkId);
+      return result;
+    } finally {
+      get().internal_updateDatasetLoading(tmpId, false);
+    }
+  },
+
+  // UPDATE / DELETE follow the same optimistic + refresh pattern as BenchmarkSlice
+  // (see the main SKILL.md)
+
+  // Internal — dispatch reducer scoped to a parent
+  internal_dispatchDataset: (payload, benchmarkId) => {
+    const currentData = get().datasetMap[benchmarkId];
+    const nextItems = datasetReducer(currentData?.items, payload);
+
+    // Skip set when nothing changed — avoids unnecessary re-renders
+    if (isEqual(nextItems, currentData?.items)) return;
+
+    set({
+      datasetMap: {
+        ...get().datasetMap,
+        [benchmarkId]: {
+          ...currentData,
+          currentPage: currentData?.currentPage ?? 1,
+          hasMore: currentData?.hasMore ?? false,
+          isLoading: false,
+          items: nextItems,
+          pageSize: currentData?.pageSize ?? nextItems.length,
+          total: currentData?.total ?? nextItems.length,
+        },
+      },
+    });
+  },
+
+  internal_updateDatasetLoading: (id, loading) => {
+    set((state) => ({
+      loadingDatasetIds: loading
+        ? [...state.loadingDatasetIds, id]
+        : state.loadingDatasetIds.filter((i) => i !== id),
+    }));
+  },
+});
+```
+
+## Step 4: Wire into the store
+
+```typescript
+// src/store/eval/store.ts
+export type EvalStore = EvalStoreState & BenchmarkAction & DatasetAction & RunAction;
+
+const createStore: StateCreator<EvalStore, [['zustand/devtools', never]]> = (set, get, store) => ({
+  ...initialState,
+  ...createBenchmarkSlice(set, get, store),
+  ...createDatasetSlice(set, get, store),
+  ...createRunSlice(set, get, store),
+});
+
+// src/store/eval/initialState.ts
+export const initialState: EvalStoreState = {
+  ...benchmarkInitialState,
+  ...datasetInitialState,
+  ...runInitialState,
+};
+```
+
+## Step 5: Selectors (optional but recommended)
+
+```typescript
+export const datasetSelectors = {
+  getDatasetData: (benchmarkId: string) => (s: EvalStore) => s.datasetMap[benchmarkId],
+  getDatasets: (benchmarkId: string) => (s: EvalStore) => s.datasetMap[benchmarkId]?.items ?? [],
+  isLoadingDataset: (id: string) => (s: EvalStore) => s.loadingDatasetIds.includes(id),
+};
+```
+
+## Step 6: Use in component
+
+```tsx
+// List scoped to a parent
+const DatasetList = ({ benchmarkId }: { benchmarkId: string }) => {
+  const useFetchDatasets = useEvalStore((s) => s.useFetchDatasets);
+  const datasets = useEvalStore(datasetSelectors.getDatasets(benchmarkId));
+  const datasetData = useEvalStore(datasetSelectors.getDatasetData(benchmarkId));
+
+  useFetchDatasets(benchmarkId);
+
+  if (datasetData?.isLoading) return <Loading />;
+  return (
+    <div>
+      <h2>Total: {datasetData?.total ?? 0}</h2>
+      <List data={datasets} />
+    </div>
+  );
+};
+
+// Single item for modal — conditional fetching pattern
+const DatasetImportModal = ({ open, datasetId }: Props) => {
+  const useFetchDatasetDetail = useEvalStore((s) => s.useFetchDatasetDetail);
+  const dataset = useEvalStore((s) => s.datasetDetail);
+  const isLoading = useEvalStore((s) => s.isLoadingDatasetDetail);
+
+  // Only fetch when modal is open AND id present
+  useFetchDatasetDetail(open && datasetId ? datasetId : undefined);
+
+  return <Modal open={open}>{isLoading ? <Loading /> : <div>{dataset?.name}</div>}</Modal>;
+};
+```

.agents/skills/db-migrations/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: db-migrations
 description: 'Use when generating or regenerating Drizzle migration files, changing database schema tables or columns, resolving migration sequence conflicts after rebase, reviewing migration SQL for idempotent patterns, or renaming migration files.'
+user-invocable: false
 ---
 
 # Database Migrations Guide

.agents/skills/debug-package/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: debug
-description: Debug package usage guide. Use when adding debug logging, understanding log namespaces, or implementing debugging features. Triggers on debug logging requests or logging implementation.
+name: debug-package
+description: "Guide for the `debug` npm package and LobeHub log namespaces (lobe-server:*, lobe-desktop:*, lobe-client:*, lobe-*-router:*). Use whenever adding a `debug(...)` logger, picking a namespace for new server/desktop/client/router code, troubleshooting why DEBUG=lobe-* logs don't show up, or when the user asks to 'add logging', 'add a logger', 'instrument this', 'trace this call', 'why isn't my log printing', or mentions `debug(`, `DEBUG=`, `localStorage.debug`, or log format specifiers like %O / %o / %s / %d in a LobeHub codebase."
 user-invocable: false
 ---
 

.agents/skills/desktop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: desktop
-description: Electron desktop development guide. Use when implementing desktop features, IPC handlers, controllers, preload scripts, window management, menu configuration, or Electron-specific functionality. Triggers on desktop app development, Electron IPC, or desktop local tools implementation.
+description: Electron desktop development guide — IPC handlers, controllers, preload scripts, window/menu management.
 disable-model-invocation: true
 ---
 

.agents/skills/drizzle/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: drizzle
-description: Drizzle ORM schema and database guide. Use when working with database schemas (src/database/schemas/*), defining tables, creating migrations, or database model code. Triggers on Drizzle schema definition, database migrations, or ORM usage questions.
+description: "Drizzle ORM schema authoring and query style for LobeHub (postgres, strict mode). Use when editing anything under `src/database/schemas/`, defining `pgTable` columns/indexes/junction tables, spreading `...timestamps`, generating `createInsertSchema`/`$inferSelect`/`$inferInsert` types, writing `db.select().from(...).leftJoin(...)` queries, or deciding when to split a relational `with:` into two queries. Triggers on `pgTable`, `db.select`, `db.query`, `eq()`/`and()`/`inArray()`, `uniqueIndex`, `primaryKey`, `references({ onDelete })`, 'add a column', 'new table', 'foreign key', 'junction table', 'schema field'. For migration files specifically, see the `db-migrations` skill."
+user-invocable: false
 ---
 
 # Drizzle ORM Schema Style Guide
@@ -125,11 +126,7 @@ The relational API generates complex lateral joins with `json_build_array` that
 
 ```typescript
 // ✅ Good
-const [result] = await this.db
-  .select()
-  .from(agents)
-  .where(eq(agents.id, id))
-  .limit(1);
+const [result] = await this.db.select().from(agents).where(eq(agents.id, id)).limit(1);
 return result;
 
 // ❌ Bad: relational API

.agents/skills/hotkey/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: hotkey
-description: Guide for adding keyboard shortcuts. Use when implementing new hotkeys, registering shortcuts, or working with keyboard interactions. Triggers on hotkey implementation or keyboard shortcut tasks.
+description: "Adding or editing keyboard shortcuts in LobeHub. Use when registering a new hotkey, changing a key combo, scoping a shortcut to chat vs global, or wiring a hotkey hook + tooltip. Covers the 5-step flow: add to `HotkeyEnum` in `src/types/hotkey.ts`, register in `HOTKEYS_REGISTRATION` (`src/const/hotkeys.ts`) with `combineKeys([Key.Mod, …])`, add i18n in `src/locales/default/hotkey.ts`, expose via `useHotkeyById` in `src/hooks/useHotkeys/`, and render `<Tooltip hotkey={…}>`. Triggers on `HotkeyEnum`, `HOTKEYS_REGISTRATION`, `useHotkeyById`, `combineKeys`, `Key.Mod`/`Key.Shift`, 'add a hotkey', 'add a shortcut', '加快捷键', '快捷键', 'Cmd+K', 'keyboard shortcut', 'hotkey scope', 'hotkey conflict'."
+user-invocable: false
 ---
 
 # Adding Keyboard Shortcuts Guide

.agents/skills/i18n/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: i18n
-description: Internationalization guide using react-i18next. Use when adding translations, creating i18n keys, or working with localized text in React components (.tsx files). Triggers on translation tasks, locale management, or i18n implementation.
+description: "LobeHub internationalization with react-i18next. Use when adding any user-facing string in `.tsx`/`.ts` files, creating or renaming a key under `src/locales/default/{namespace}.ts`, deciding the `{feature}.{context}.{action}` flat-key pattern, wiring a new namespace into `src/locales/default/index.ts`, or translating zh-CN/en-US JSON for dev preview. Triggers on `useTranslation`, `t('foo.bar')`, `i18next.t`, `{{variable}}` interpolation, hardcoded UI strings (zh or en) that should be extracted, 'add i18n', '加 i18n key', '翻译', 'locale key', 'namespace', 'pnpm i18n'."
+user-invocable: false
 ---
 
 # LobeHub Internationalization Guide

.agents/skills/linear/SKILL.md

@@ -1,55 +1,55 @@
 ---
 name: linear
-description: "Linear issue management. MUST USE when: (1) user mentions LOBE-xxx issue IDs (e.g. LOBE-4540), (2) user says 'linear', 'linear issue', 'link linear', (3) creating PRs that reference Linear issues. Provides workflows for retrieving issues, updating status, and adding comments."
+description: "Linear issue management. Use when the user mentions LOBE-xxx issue IDs (e.g. LOBE-4540), says 'linear' / 'linear issue' / 'link linear', or when creating PRs that reference Linear issues. Covers retrieving issues, updating status, adding completion comments, and creating sub-issue trees."
+user-invocable: false
 ---
 
 # Linear Issue Management
 
 Before using Linear workflows, search for `linear` MCP tools. If not found, treat as not installed.
 
-## ⚠️ CRITICAL: PR Creation with Linear Issues
+## PR Creation with Linear Issues
 
-**When creating a PR that references Linear issues (LOBE-xxx), you MUST:**
+A PR that fixes a Linear issue has **two separate jobs to do**, and both matter:
 
-1. Create the PR with magic keywords (`Fixes LOBE-xxx`)
-2. **IMMEDIATELY after PR creation**, add completion comments to ALL referenced Linear issues
-3. Do NOT consider the task complete until Linear comments are added
+1. **`Fixes LOBE-xxx` in the PR body** — Linear watches GitHub for these magic keywords and auto-links the PR and auto-closes the issue on merge. This is the machine-readable side.
+2. **A completion comment on the Linear issue** — gives the reviewer/PM/teammate landing in Linear a human-readable summary of what changed and why, without forcing them to click through to GitHub and read a diff.
 
-This is NON-NEGOTIABLE. Skipping Linear comments is a workflow violation.
+If you only do step 1, Linear watchers (often non-engineers) hit the issue and see no context. So pair PR creation with the Linear comment as part of the same task — finish both before considering the work done.
 
 ## Workflow
 
 1. **Retrieve issue details** before starting: `mcp__linear-server__get_issue`
-2. **Read images**: If the issue description contains images, MUST use `mcp__linear-server__extract_images` to read image content for full context
-3. **Check for sub-issues**: Use `mcp__linear-server__list_issues` with `parentId` filter
-4. **Mark as In Progress**: When starting to plan or implement an issue, immediately update status to **"In Progress"** via `mcp__linear-server__update_issue`
+2. **Read images** — issue descriptions often contain screenshots with critical context (mockups, error states, before/after). Use `mcp__linear-server__extract_images` so you actually see them; reading raw markdown alone misses what the reporter was looking at.
+3. **Check for sub-issues**: `mcp__linear-server__list_issues` with `parentId` filter
+4. **Mark as In Progress** at the moment you start planning or implementing — this signals to teammates the issue is owned, so they don't double-pick it up.
 5. **Update issue status** when completing: `mcp__linear-server__update_issue`
-6. **Add completion comment** (REQUIRED): `mcp__linear-server__create_comment`
+6. **Add completion comment** (see [format below](#completion-comment-format))
 
 ## Creating Issues
 
-When creating issues with `mcp__linear-server__create_issue`, **MUST add the `claude code` label**.
+When creating issues with `mcp__linear-server__create_issue`, add the `claude code` label. Reason: the label is how the team filters/audits AI-generated issues; without it those issues vanish into the general backlog and the team loses visibility into AI contribution patterns.
 
 ## Language
 
-Issue titles, descriptions, and comments **MUST follow the language of the current conversation**, not default to English.
+Match the issue language to the conversation that produced it — if you're discussing in 中文，write the issue in 中文；if discussing in English, write it in English. Reason: the issue is a continuation of the conversation, and forcing a language switch creates translation friction for the collaborator who started the thread.
 
-- Conversation in 中文 → issue body in 中文；technical terms (file paths, identifiers, library names, commands, error messages) stay in English.
-- Conversation in English → issue body in English.
+Specifics:
+
+- 中文 conversation → 中文 body; technical terms (file paths, identifiers, library names, commands, error messages) stay in English.
+- English conversation → English body.
 - Code blocks, file paths, and quoted strings always stay in their original form regardless of surrounding language.
-- This applies equally to **updates** — when editing an existing issue (description **and titles**), preserve the language of the conversation that triggered the edit; do not switch the issue language during a refactor (Chinese → English or vice versa).
-
-Rationale: the issue is a continuation of the conversation. Forcing English when the discussion is in Chinese creates translation friction for the collaborator who came from that thread.
+- This applies equally to **updates** — when editing an existing issue (description **and titles**), preserve the language of the conversation that triggered the edit; don't switch the issue language mid-refactor.
 
 ## Creating Sub-issue Trees
 
 When breaking a parent issue into a tree of sub-issues (e.g., task decomposition for LOBE-xxx), follow these rules — they work around real limitations of the Linear MCP tools.
 
-### 1. ALWAYS prefix titles with an ordering index
+### 1. Prefix titles with an ordering index
 
-The Linear Sub-issues panel displays children by `sortOrder`, which **defaults to newest-first** (most recently created appears on top). Neither parallel nor serial creation will produce the intended top-to-bottom reading order, and the MCP `save_issue` tool does **not expose a `sortOrder` parameter** — you cannot set order at create time.
+The Linear Sub-issues panel orders children by `sortOrder`, which **defaults to newest-first** (most recently created appears on top). Neither parallel nor serial creation produces the intended top-to-bottom reading order, and the MCP `save_issue` tool does **not expose a `sortOrder` parameter** — you can't set order at create time.
 
-**Workaround**: encode execution order in the title itself:
+Workaround: encode execution order in the title itself:
 
 ```plaintext
 [1]     [db]       add schema fields
@@ -100,7 +100,7 @@ The implementer may open only the sub-issue, not the parent — don't rely on co
 
 ## Completion Comment Format
 
-Every completed issue MUST have a comment summarizing work done:
+Each completed issue gets a comment summarizing the work, so reviewers and future readers don't have to reconstruct it from the PR diff:
 
 ```markdown
 ## Changes Summary
@@ -116,34 +116,28 @@ Every completed issue MUST have a comment summarizing work done:
 - ...
 ```
 
-This is critical for:
+This gives team visibility, code-review context, and a paper trail for future reference.
 
-- Team visibility
-- Code review context
-- Future reference
+## PR Association
 
-## PR Association (REQUIRED)
-
-When creating PRs for Linear issues, include magic keywords in PR body:
+When creating PRs for Linear issues, include magic keywords in the PR body:
 
 - `Fixes LOBE-123`
 - `Closes LOBE-123`
 - `Resolves LOBE-123`
 
+These trigger Linear's auto-link + auto-close on merge.
+
 ## Per-Issue Completion Rule
 
-When working on multiple issues, update EACH issue IMMEDIATELY after completing it:
+When working on multiple issues, close out **each one before starting the next** — don't batch all the Linear updates to the end. Batching is where comments get forgotten and issues stay stuck in "In Progress" days after the PR shipped.
+
+For each issue:
 
 1. Complete implementation
 2. Run `bun run type-check`
 3. Run related tests
 4. Create PR if needed
-5. Update status to **"In Review"** (NOT "Done")
-6. **Add completion comment immediately**
-7. Move to next issue
-
-**Note:** Status → "In Review" when PR created. "Done" only after PR merged.
-
-**❌ Wrong:** Complete all → Create PR → Forget Linear comments
-
-**✅ Correct:** Complete → Create PR → Add Linear comments → Task done
+5. Update status to **"In Review"** (not "Done" — "Done" is for after the PR merges)
+6. Add the completion comment
+7. Move to the next issue

.agents/skills/microcopy/SKILL.md

@@ -1,10 +1,16 @@
 ---
 name: microcopy
 description: UI copy and microcopy guidelines. Use when writing UI text, buttons, error messages, empty states, onboarding, or any user-facing copy. Triggers on i18n translation, UI text writing, or copy improvement tasks. Supports both Chinese and English.
+user-invocable: false
 ---
 
 # LobeHub UI Microcopy Guidelines
 
+This file is the quick-reference summary. For full prompt-style guidelines with extensive examples (anti-patterns, tone matrices, scenario walk-throughs), load the language-specific reference:
+
+- **中文文案** — [`references/zh.md`](./references/zh.md)
+- **English copy** — [`references/en.md`](./references/en.md)
+
 Brand: **Where Agents Collaborate** - Focus on collaborative agent system, not just "generation".
 
 ## Fixed Terminology

.agents/skills/modal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: modal
-description: MUST use when creating, editing, or writing modal dialogs or imperative modals. Prefer createModal / useModalContext / confirmModal from @lobehub/ui/base-ui; root @lobehub/ui is legacy (antd Modal). Covers patterns, ModalHost, and migration notes.
+description: "LobeHub imperative-modal conventions. Use whenever creating, editing, opening, or migrating a modal/dialog/popup — prefer `createModal` / `confirmModal` / `useModalContext` from `@lobehub/ui/base-ui` (headless) over the legacy root `@lobehub/ui` `createModal` (antd Modal props) and over any declarative `open` state + `<Modal />` pattern. Covers required `ModalHost` mounting, the `Content` + `index.tsx` file layout, `content` vs `children` slot, i18n inside `createModal()` (`import { t } from 'i18next'`), and migration notes. Triggers on `createModal`, `confirmModal`, `useModalContext`, `ModalHost`, `antd Modal`, `<Modal open>`, 'open a modal', 'popup', 'dialog', 'confirm dialog', '弹框', '弹窗', '确认框', 'migrate to base-ui'."
 user-invocable: false
 ---
 

.agents/skills/project-overview/SKILL.md

@@ -1,10 +1,15 @@
 ---
 name: project-overview
 description: Complete project architecture and structure guide. Use when exploring the codebase, understanding project organization, finding files, or needing comprehensive architectural context. Triggers on architecture questions, directory navigation, or project overview needs.
+user-invocable: false
 ---
 
 # LobeHub Project Overview
 
+> The directory listings below are a **curated map of key locations**, not an
+> exhaustive tree. `packages/`, `src/store/`, route groups etc. grow over time —
+> run `ls` against the real directory for the current set.
+
 ## Project Description
 
 Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat).
@@ -13,7 +18,7 @@ Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat)
 
 - Web desktop/mobile
 - Desktop (Electron)
-- Mobile app (React Native) - coming soon
+- Mobile app (React Native) — **separate repo, already launched** (not in this monorepo)
 
 **Logo emoji:** 🤯
 
@@ -38,147 +43,92 @@ Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat)
 | Database      | Neon PostgreSQL + Drizzle ORM              |
 | Testing       | Vitest                                     |
 
-## Complete Project Structure
+> Exact versions live in the root `package.json` — check there, not here.
 
-Monorepo using `@lobechat/` namespace for workspace packages.
+## Monorepo Layout
+
+This is a monorepo extending the open-source `lobehub` submodule. Two repos:
+
+- **cloud repo root** — `src/` and `packages/business/` (`config`, `const`, `model-runtime`) hold cloud-only SaaS code that overrides/extends the submodule. See `AGENTS.md` for the override mechanism.
+- **`lobehub/` submodule** — the open-source product core.
+
+### `lobehub/` submodule — key directories
 
 ```
 lobehub/
 ├── apps/
-│   └── desktop/                 # Electron desktop app
-├── docs/
-│   ├── changelog/
-│   ├── development/
-│   ├── self-hosting/
-│   └── usage/
-├── locales/
-│   ├── en-US/
-│   └── zh-CN/
-├── packages/
-│   ├── agent-runtime/           # Agent runtime
-│   ├── builtin-agents/
-│   ├── builtin-tool-*/          # Builtin tool packages
-│   ├── business/                # Cloud-only business logic
-│   │   ├── config/
-│   │   ├── const/
-│   │   └── model-runtime/
-│   ├── config/
-│   ├── const/
+│   ├── cli/                 # LobeHub CLI
+│   ├── desktop/             # Electron desktop app
+│   └── device-gateway/      # Device gateway service
+├── docs/                    # changelog, development, self-hosting, usage
+├── locales/                 # en-US, zh-CN, ...
+├── packages/                # ~80 @lobechat/* workspace packages — `ls` for the full set. Key ones:
+│   ├── agent-runtime/        # Agent runtime
+│   ├── agent-signal/         # Agent Signal pipeline
+│   ├── builtin-tool-*/       # Builtin tool packages
+│   ├── builtin-tools/        # Builtin tool registries
 │   ├── context-engine/
-│   ├── conversation-flow/
-│   ├── database/
-│   │   └── src/
-│   │       ├── models/
-│   │       ├── schemas/
-│   │       └── repositories/
-│   ├── desktop-bridge/
-│   ├── edge-config/
-│   ├── editor-runtime/
-│   ├── electron-client-ipc/
-│   ├── electron-server-ipc/
-│   ├── fetch-sse/
-│   ├── file-loaders/
-│   ├── memory-user-memory/
-│   ├── model-bank/
-│   ├── model-runtime/
-│   │   └── src/
-│   │       ├── core/
-│   │       └── providers/
-│   ├── observability-otel/
-│   ├── prompts/
-│   ├── python-interpreter/
-│   ├── ssrf-safe-fetch/
-│   ├── types/
-│   ├── utils/
-│   └── web-crawler/
-├── src/
-│   ├── app/
-│   │   ├── (backend)/
-│   │   │   ├── api/
-│   │   │   ├── f/
-│   │   │   ├── market/
-│   │   │   ├── middleware/
-│   │   │   ├── oidc/
-│   │   │   ├── trpc/
-│   │   │   └── webapi/
-│   │   ├── spa/                  # SPA HTML template service
-│   │   └── [variants]/
-│   │       └── (auth)/           # Auth pages (SSR required)
-│   ├── routes/                  # SPA page components (Vite)
-│   │   ├── (main)/
-│   │   ├── (mobile)/
-│   │   ├── (desktop)/
-│   │   ├── onboarding/
-│   │   └── share/
-│   ├── spa/                     # SPA entry points and router config
-│   │   ├── entry.web.tsx
-│   │   ├── entry.mobile.tsx
-│   │   ├── entry.desktop.tsx
-│   │   └── router/
-│   ├── business/                # Cloud-only (client/server)
-│   │   ├── client/
-│   │   ├── locales/
-│   │   └── server/
-│   ├── components/
-│   ├── config/
-│   ├── const/
-│   ├── envs/
-│   ├── features/
-│   ├── helpers/
-│   ├── hooks/
-│   ├── layout/
-│   │   ├── AuthProvider/
-│   │   └── GlobalProvider/
-│   ├── libs/
-│   │   ├── better-auth/
-│   │   ├── oidc-provider/
-│   │   └── trpc/
-│   ├── locales/
-│   │   └── default/
-│   ├── server/
-│   │   ├── featureFlags/
-│   │   ├── globalConfig/
-│   │   ├── modules/
-│   │   ├── routers/
-│   │   │   ├── async/
-│   │   │   ├── lambda/
-│   │   │   ├── mobile/
-│   │   │   └── tools/
-│   │   └── services/
-│   ├── services/
-│   ├── store/
-│   │   ├── agent/
-│   │   ├── chat/
-│   │   └── user/
-│   ├── styles/
-│   ├── tools/
+│   ├── database/             # src/{models,schemas,repositories}
+│   ├── model-bank/           # Model definitions & provider cards
+│   ├── model-runtime/        # src/{core,providers}
 │   ├── types/
 │   └── utils/
-└── e2e/                         # E2E tests (Cucumber + Playwright)
+└── src/
+    ├── app/
+    │   ├── (backend)/        # api, f, market, middleware, oidc, trpc, webapi
+    │   ├── spa/              # SPA HTML template service
+    │   └── [variants]/(auth)/ # Auth pages (SSR required)
+    ├── routes/               # SPA page segments (thin — delegate to features/)
+    │   └── (main)/ (mobile)/ (desktop)/ (popup)/ onboarding/ share/
+    ├── spa/                  # SPA entries + router config
+    │   ├── entry.{web,mobile,desktop,popup}.tsx
+    │   └── router/
+    ├── business/             # Open-source stubs (~50) overridden by cloud src/business/
+    ├── features/             # Domain business components
+    ├── store/                # ~28 zustand stores — `ls` for the full set
+    ├── server/               # featureFlags, globalConfig, modules, routers, services
+    └── ...                   # components, hooks, layout, libs, locales, services, types, utils
 ```
 
+### cloud repo — key directories
+
+```
+(cloud root)
+├── packages/business/        # Cloud overrides: config, const, model-runtime
+├── src/
+│   ├── business/             # Cloud impls of submodule stubs (client/server/locales)
+│   ├── routes/               # Cloud-only route groups: (cloud)/, embed/
+│   ├── store/                # Cloud-only stores (e.g. subscription/)
+│   ├── server/               # Cloud routers & services (billing, budget, risk control...)
+│   └── app/(backend)/cron/   # Vercel cron routes (schedules declared in root vercel.ts)
+└── vercel.ts                 # Cron schedule declarations
+```
+
+> File search rule: a path like `@/store/x` resolves cloud `src/store/x` first, then
+> `lobehub/packages/store/src/x`, then `lobehub/src/store/x`. Cloud override wins.
+
 ## Architecture Map
 
-| Layer            | Location                                            |
-| ---------------- | --------------------------------------------------- |
-| UI Components    | `src/components`, `src/features`                    |
-| SPA Pages        | `src/routes/`                                       |
-| React Router     | `src/spa/router/`                                   |
-| Global Providers | `src/layout`                                        |
-| Zustand Stores   | `src/store`                                         |
-| Client Services  | `src/services/`                                     |
-| REST API         | `src/app/(backend)/webapi`                          |
-| tRPC Routers     | `src/server/routers/{async\|lambda\|mobile\|tools}` |
-| Server Services  | `src/server/services` (can access DB)               |
-| Server Modules   | `src/server/modules` (no DB access)                 |
-| Feature Flags    | `src/server/featureFlags`                           |
-| Global Config    | `src/server/globalConfig`                           |
-| DB Schema        | `packages/database/src/schemas`                     |
-| DB Model         | `packages/database/src/models`                      |
-| DB Repository    | `packages/database/src/repositories`                |
-| Third-party      | `src/libs` (analytics, oidc, etc.)                  |
-| Builtin Tools    | `src/tools`, `packages/builtin-tool-*`              |
-| Cloud-only       | `src/business/*`, `packages/business/*`             |
+| Layer            | Location                                             |
+| ---------------- | ---------------------------------------------------- |
+| UI Components    | `src/components`, `src/features`                     |
+| SPA Pages        | `src/routes/`                                        |
+| React Router     | `src/spa/router/`                                    |
+| Global Providers | `src/layout`                                         |
+| Zustand Stores   | `src/store`                                          |
+| Client Services  | `src/services/`                                      |
+| REST API         | `src/app/(backend)/webapi`                           |
+| tRPC Routers     | `src/server/routers/{async\|lambda\|mobile\|tools}`  |
+| Server Services  | `src/server/services` (can access DB)                |
+| Server Modules   | `src/server/modules` (no DB access)                  |
+| Feature Flags    | `src/server/featureFlags`                            |
+| Global Config    | `src/server/globalConfig`                            |
+| DB Schema        | `packages/database/src/schemas`                      |
+| DB Model         | `packages/database/src/models`                       |
+| DB Repository    | `packages/database/src/repositories`                 |
+| Third-party      | `src/libs` (analytics, oidc, etc.)                   |
+| Builtin Tools    | `src/tools`, `packages/builtin-tool-*`               |
+| Cloud-only       | `src/business/*`, `packages/business/*` (cloud repo) |
 
 ## Data Flow
 

.agents/skills/react/SKILL.md

@@ -1,94 +1,95 @@
 ---
 name: react
-description: React component development guide. Use when working with React components (.tsx files), creating UI, using @lobehub/ui components, implementing routing, or building frontend features. Triggers on React component creation, modification, layout implementation, or navigation tasks.
+description: 'Use when writing or editing any `.tsx` under `src/**`. Triggers: createStaticStyles, createStyles, cssVar, antd-style, Flexbox, Center, Select, Modal, Drawer, Button, Tooltip, DropdownMenu, Popover, Switch, ScrollArea, Link, useNavigate, react-router-dom, next/link, desktopRouter, componentMap.desktop, .desktop.tsx, new component, new page, edit layout, add styles, zustand selector, @lobehub/ui, antd import.'
+user-invocable: false
 ---
 
 # React Component Writing Guide
 
-- Use antd-style for complex styles; for simple cases, use inline `style` attribute
-  - **Prefer `createStaticStyles` with `cssVar.*`** (zero-runtime) — module-level, no hook call required
-  - Only fall back to `createStyles` + `token` when styles genuinely need runtime computation (dynamic props, JS color fns like `readableColor`/`chroma`)
-  - See `.cursor/docs/createStaticStyles_migration_guide.md` for full pattern
-- Use `Flexbox` and `Center` from `@lobehub/ui` for layouts (see `references/layout-kit.md`)
-- Component priority: `src/components` > `@lobehub/ui/base-ui` > `@lobehub/ui` > custom implementation
-  - Always prefer `@lobehub/ui/base-ui` primitives (Select, Modal, DropdownMenu, Popover, Switch, ScrollArea…) over antd equivalents
-  - Fall back to `@lobehub/ui` higher-level components when base-ui has no match
-  - Only implement a custom component as a last resort — never reach for antd directly
-- Use selectors to access zustand store data
+## Styling
 
-## @lobehub/ui Components
+| Scenario                                                   | Approach                                                       |
+| ---------------------------------------------------------- | -------------------------------------------------------------- |
+| Most cases                                                 | `createStaticStyles` + `cssVar.*` (zero-runtime, module-level) |
+| Simple one-off                                             | Inline `style` attribute                                       |
+| Truly dynamic (JS color fns like `readableColor`/`chroma`) | `createStyles` + `token` — **last resort**                     |
 
-If unsure about component usage, search existing code in this project. Most components extend antd with additional props.
+## Component Priority
 
-Reference: `node_modules/@lobehub/ui/es/index.mjs` for all available components.
+1. **`src/components`** — project-specific reusable components
+2. **`@lobehub/ui/base-ui`** — headless primitives (Select, Modal, DropdownMenu, Popover, Switch, ScrollArea…)
+3. **`@lobehub/ui`** — higher-level components (ActionIcon, Markdown, DragPage…)
+4. **Custom implementation** — last resort; never reach for antd directly
 
-**Common Components:**
+If unsure about available components, search existing code or check `node_modules/@lobehub/ui/es/index.mjs`.
 
-- General: ActionIcon, ActionIconGroup, Block, Button, Icon
-- Data Display: Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip
-- Data Entry: CodeEditor, CopyButton, EditableText, Form, FormModal, Input, SearchBar, Select
-- Feedback: Alert, Drawer, Modal
-- Layout: Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow
-- Navigation: Burger, Dropdown, Menu, SideNav, Tabs
+### Common @lobehub/ui Components
+
+| Category     | Components                                                                      |
+| ------------ | ------------------------------------------------------------------------------- |
+| General      | ActionIcon, ActionIconGroup, Block, Button, Icon                                |
+| Data Display | Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip                    |
+| Data Entry   | CodeEditor, CopyButton, EditableText, Form, FormModal, Input, SearchBar, Select |
+| Feedback     | Alert, Drawer, Modal                                                            |
+| Layout       | Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow                       |
+| Navigation   | Burger, Dropdown, Menu, SideNav, Tabs                                           |
+
+## Layout
+
+Use `Flexbox` and `Center` from `@lobehub/ui`. See `references/layout-kit.md` for full props and examples.
+
+- Use `gap` instead of `margin` for spacing between flex children
+- Use `flex={1}` to fill available space
+- Nest Flexbox for complex layouts; set `overflow: 'auto'` for scrollable regions
+
+## Navigation
+
+**For SPA pages, use `react-router-dom`, NOT `next/link`.**
+
+```tsx
+// ❌ Wrong
+import Link from 'next/link';
+
+// ✅ Correct
+import { Link, useNavigate } from 'react-router-dom';
+```
+
+Access navigate from stores: `useGlobalStore.getState().navigate?.('/settings');`
+
+## Desktop File Sync Rule
+
+Files with a `.desktop.ts(x)` variant must be edited **in sync**. Drift causes blank pages in Electron.
+
+| Base file (web)            | Desktop file (Electron)            |
+| -------------------------- | ---------------------------------- |
+| `desktopRouter.config.tsx` | `desktopRouter.config.desktop.tsx` |
+| `componentMap.ts`          | `componentMap.desktop.ts`          |
+
+**After editing any `.ts`/`.tsx`:** glob for `<filename>.desktop.{ts,tsx}` in the same directory. If found, apply the equivalent sync-import change.
 
 ## Routing Architecture
 
-Hybrid routing: Next.js App Router (static pages) + React Router DOM (main SPA).
+| Route Type         | Use Case   | Implementation                                     |
+| ------------------ | ---------- | -------------------------------------------------- |
+| Next.js App Router | Auth pages | `src/app/[variants]/(auth)/`                       |
+| React Router DOM   | Main SPA   | `desktopRouter.config.tsx` + `.desktop.tsx` (pair) |
 
-| Route Type         | Use Case                          | Implementation                                                               |
-| ------------------ | --------------------------------- | ---------------------------------------------------------------------------- |
-| Next.js App Router | Auth pages (login, signup, oauth) | `src/app/[variants]/(auth)/`                                                 |
-| React Router DOM   | Main SPA (chat, settings)         | `desktopRouter.config.tsx` + `desktopRouter.config.desktop.tsx` (must match) |
-
-### Key Files
-
-- Entry: `src/spa/entry.web.tsx` (web), `src/spa/entry.mobile.tsx`, `src/spa/entry.desktop.tsx`
-- Desktop router (pair — **always edit both** when changing routes): `src/spa/router/desktopRouter.config.tsx` (dynamic imports) and `src/spa/router/desktopRouter.config.desktop.tsx` (sync imports). Drift can cause unregistered routes / blank screen.
-- Mobile router: `src/spa/router/mobileRouter.config.tsx`
-- Router utilities: `src/utils/router.tsx`
-
-### `.desktop.{ts,tsx}` File Sync Rule
-
-**CRITICAL**: Some files have a `.desktop.ts(x)` variant that Electron uses instead of the base file. When editing a base file, **always check** if a `.desktop` counterpart exists and update it in sync. Drift causes blank pages or missing features in Electron.
-
-Known pairs that must stay in sync:
-
-| Base file (web, dynamic imports)                      | Desktop file (Electron, sync imports)                         |
-| ----------------------------------------------------- | ------------------------------------------------------------- |
-| `src/spa/router/desktopRouter.config.tsx`             | `src/spa/router/desktopRouter.config.desktop.tsx`             |
-| `src/routes/(main)/settings/features/componentMap.ts` | `src/routes/(main)/settings/features/componentMap.desktop.ts` |
-
-**How to check**: After editing any `.ts` / `.tsx` file, run `Glob` for `<filename>.desktop.{ts,tsx}` in the same directory. If a match exists, update it with the equivalent sync-import change.
-
-### Router Utilities
+Router utilities:
 
 ```tsx
 import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
-
 element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
 element: redirectElement('/settings/profile');
 errorElement: <ErrorBoundary />;
 ```
 
-### Navigation
+## Common Mistakes
 
-**Important**: For SPA pages, use `Link` from `react-router-dom`, NOT `next/link`.
-
-```tsx
-// ❌ Wrong
-import Link from 'next/link';
-<Link href="/">Home</Link>;
-
-// ✅ Correct
-import { Link } from 'react-router-dom';
-<Link to="/">Home</Link>;
-
-// In components
-import { useNavigate } from 'react-router-dom';
-const navigate = useNavigate();
-navigate('/chat');
-
-// From stores
-const navigate = useGlobalStore.getState().navigate;
-navigate?.('/settings');
-```
+| Mistake                                  | Fix                                                    |
+| ---------------------------------------- | ------------------------------------------------------ |
+| Using `next/link` in SPA                 | Use `react-router-dom` `Link`                          |
+| Using antd directly                      | Use `@lobehub/ui/base-ui` first, then `@lobehub/ui`    |
+| `createStyles` for static styles         | Use `createStaticStyles` + `cssVar`                    |
+| Editing only `desktopRouter.config.tsx`  | Must edit both `.tsx` and `.desktop.tsx`               |
+| Using `margin` for flex spacing          | Use `gap` prop on Flexbox                              |
+| Accessing zustand store without selector | Use selectors to access store data (see zustand skill) |

.agents/skills/review-checklist/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: review-checklist
 description: 'Common recurring mistakes in LobeHub code review — console leftovers, missing return await, hardcoded secrets, hardcoded i18n strings, desktop router pair drift, antd vs @lobehub/ui, non-idempotent migrations, cloud impact red flags. Use as a quick checklist when reviewing PRs, diffs, or branch changes.'
+user-invocable: false
 ---
 
 # Review Checklist

.agents/skills/spa-routes/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spa-routes
 description: MUST use when editing src/routes/ segments, src/spa/router/desktopRouter.config.tsx or desktopRouter.config.desktop.tsx (always change both together), mobileRouter.config.tsx, or when moving UI/logic between routes and src/features/.
+user-invocable: false
 ---
 
 # SPA Routes and Features Guide
@@ -84,10 +85,10 @@ Each feature should:
 
 ## 3a. Desktop router pair (`desktopRouter.config` × 2)
 
-| File | Role |
-|------|------|
-| `desktopRouter.config.tsx` | Dynamic imports via `dynamicElement` / `dynamicLayout` — code-splitting; used by `entry.web.tsx` and `entry.desktop.tsx`. |
-| `desktopRouter.config.desktop.tsx` | Same route tree with **synchronous** imports — kept for Electron / local parity and predictable bundling. |
+| File                               | Role                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `desktopRouter.config.tsx`         | Dynamic imports via `dynamicElement` / `dynamicLayout` — code-splitting; used by `entry.web.tsx` and `entry.desktop.tsx`. |
+| `desktopRouter.config.desktop.tsx` | Same route tree with **synchronous** imports — kept for Electron / local parity and predictable bundling.                 |
 
 Anything that changes the tree (new segment, renamed `path`, moved layout, new child route) must be reflected in **both** files in one PR or commit. Remove routes from both when deleting.
 

.agents/skills/store-data-structures/SKILL.md

@@ -1,257 +1,91 @@
 ---
 name: store-data-structures
 description: Zustand store data structure patterns for LobeHub. Covers List vs Detail data structures, Map + Reducer patterns, type definitions, and when to use each pattern. Use when designing store state, choosing data structures, or implementing list/detail pages.
+user-invocable: false
 ---
 
 # LobeHub Store Data Structures
 
-This guide covers how to structure data in Zustand stores for optimal performance and user experience.
+How to structure data in Zustand stores for fast list rendering, multi-detail caching, and ergonomic optimistic updates.
 
 ## Core Principles
 
 ### ✅ DO
 
-1. **Separate List and Detail** - Use different structures for list pages and detail pages
-2. **Use Map for Details** - Cache multiple detail pages with `Record<string, Detail>`
-3. **Use Array for Lists** - Simple arrays for list display
-4. **Types from @lobechat/types** - Never use `@lobechat/database` types in stores
-5. **Distinguish List and Detail types** - List types may have computed UI fields
+1. **Separate List and Detail** — different structures for list pages and detail pages
+2. **Use Map for Details** — cache multiple detail pages with `Record<string, Detail>`
+3. **Use Array for Lists** — simple arrays for list display
+4. **Types from `@lobechat/types`** — never use `@lobechat/database` types in stores
+5. **Distinguish List and Detail types** — List types may have computed UI fields
 
 ### ❌ DON'T
 
-1. **Don't use single detail object** - Can't cache multiple pages
-2. **Don't mix List and Detail types** - They have different purposes
-3. **Don't use database types** - Use types from `@lobechat/types`
-4. **Don't use Map for lists** - Simple arrays are sufficient
+1. **Don't use a single detail object** — can't cache multiple pages
+2. **Don't mix List and Detail types** — they have different purposes
+3. **Don't use database types** — use types from `@lobechat/types`
+4. **Don't use Map for lists** — simple arrays are sufficient
 
 ---
 
 ## Type Definitions
 
-Types should be organized by entity in separate files:
+Each entity gets its own file under `@lobechat/types/`. Each file exports two types:
 
-```
-@lobechat/types/src/eval/
-├── benchmark.ts        # Benchmark types
-├── agentEvalDataset.ts # Dataset types
-├── agentEvalRun.ts     # Run types
-└── index.ts           # Re-exports
-```
+- **Detail type** — full entity, including heavy fields (rubrics, content, editor state, …)
+- **List item type** — a **subset** that excludes heavy fields, may add computed UI fields (counts, timestamps formatted for display)
 
-### Example: Benchmark Types
+**Important:** the List type is a **subset**, not an `extends` of Detail. Extending pulls the heavy fields right back in.
 
-```typescript
-// packages/types/src/eval/benchmark.ts
-import type { EvalBenchmarkRubric } from './rubric';
-
-// ============================================
-// Detail Type - Full entity (for detail pages)
-// ============================================
-
-/**
- * Full benchmark entity with all fields including heavy data
- */
-export interface AgentEvalBenchmark {
-  createdAt: Date;
-  description?: string | null;
-  id: string;
-  identifier: string;
-  isSystem: boolean;
-  metadata?: Record<string, unknown> | null;
-  name: string;
-  referenceUrl?: string | null;
-  rubrics: EvalBenchmarkRubric[]; // Heavy field
-  updatedAt: Date;
-}
-
-// ============================================
-// List Type - Lightweight (for list display)
-// ============================================
-
-/**
- * Lightweight benchmark item - excludes heavy fields
- * May include computed statistics for UI
- */
-export interface AgentEvalBenchmarkListItem {
-  createdAt: Date;
-  description?: string | null;
-  id: string;
-  identifier: string;
-  isSystem: boolean;
-  name: string;
-  // Note: rubrics NOT included (heavy field)
-
-  // Computed statistics for UI display
-  datasetCount?: number;
-  runCount?: number;
-  testCaseCount?: number;
-}
-```
-
-### Example: Document Types (with heavy content)
-
-```typescript
-// packages/types/src/document.ts
-
-/**
- * Full document entity - includes heavy content fields
- */
-export interface Document {
-  id: string;
-  title: string;
-  description?: string;
-  content: string; // Heavy field - full markdown content
-  editorData: any; // Heavy field - editor state
-  metadata?: Record<string, unknown>;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-/**
- * Lightweight document item - excludes heavy content
- */
-export interface DocumentListItem {
-  id: string;
-  title: string;
-  description?: string;
-  // Note: content and editorData NOT included
-  createdAt: Date;
-  updatedAt: Date;
-
-  // Computed statistics
-  wordCount?: number;
-  lastEditedBy?: string;
-}
-```
-
-**Key Points:**
-
-- **Detail types** include ALL fields from database (full entity)
-- **List types** are **subsets** that exclude heavy/large fields
-- List types may add computed statistics for UI (e.g., `testCaseCount`)
-- **Each entity gets its own file** (not mixed together)
-- **All types** exported from `@lobechat/types`, NOT `@lobechat/database`
-
-**Heavy fields to exclude from List:**
-
-- Large text content (`content`, `editorData`, `fullDescription`)
-- Complex objects (`rubrics`, `config`, `metrics`)
-- Binary data (`image`, `file`)
-- Large arrays (`messages`, `items`)
+> See [`references/types.md`](./references/types.md) for full worked examples (Benchmark, Document) and the heavy-field exclusion checklist.
 
 ---
 
 ## When to Use Map vs Array
 
-### Use Map + Reducer (for Detail Data)
+### Use Map + Reducer — for Detail Data
 
-✅ **Detail page data caching** - Cache multiple detail pages simultaneously
-✅ **Optimistic updates** - Update UI before API responds
-✅ **Per-item loading states** - Track which items are being updated
-✅ **Multiple pages open** - User can navigate between details without refetching
-
-**Structure:**
+✅ Detail page data caching — multiple detail pages cached simultaneously
+✅ Optimistic updates — update UI before API responds
+✅ Per-item loading states — track which items are being updated
+✅ Multi-page navigation — user can switch between details without refetching
 
 ```typescript
 benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
 ```
 
-**Example:** Benchmark detail pages, Dataset detail pages, User profiles
+Examples: benchmark detail pages, dataset detail pages, user profiles.
 
-### Use Simple Array (for List Data)
+### Use Simple Array — for List Data
 
-✅ **List display** - Lists, tables, cards
-✅ **Read-only or refresh-as-whole** - Entire list refreshes together
-✅ **No per-item updates** - No need to update individual items
-✅ **Simple data flow** - Easier to understand and maintain
-
-**Structure:**
+✅ List display — lists, tables, cards
+✅ Refresh as a whole — entire list refreshes together
+✅ No per-item updates — no need to mutate individual rows in place
+✅ Simple data flow — fewer moving parts
 
 ```typescript
-benchmarkList: AgentEvalBenchmarkListItem[]
+benchmarkList: AgentEvalBenchmarkListItem[];
 ```
 
-**Example:** Benchmark list, Dataset list, User list
+Examples: benchmark list, dataset list, user list.
 
 ---
 
 ## State Structure Pattern
 
-### Complete Example
-
-```typescript
-// packages/types/src/eval/benchmark.ts
-import type { EvalBenchmarkRubric } from './rubric';
-
-/**
- * Full benchmark entity (for detail pages)
- */
-export interface AgentEvalBenchmark {
-  id: string;
-  name: string;
-  description?: string | null;
-  identifier: string;
-  rubrics: EvalBenchmarkRubric[]; // Heavy field
-  metadata?: Record<string, unknown> | null;
-  isSystem: boolean;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-/**
- * Lightweight benchmark (for list display)
- * Excludes heavy fields like rubrics
- */
-export interface AgentEvalBenchmarkListItem {
-  id: string;
-  name: string;
-  description?: string | null;
-  identifier: string;
-  isSystem: boolean;
-  createdAt: Date;
-  // Note: rubrics excluded
-
-  // Computed statistics
-  testCaseCount?: number;
-  datasetCount?: number;
-  runCount?: number;
-}
-```
-
 ```typescript
 // src/store/eval/slices/benchmark/initialState.ts
 import type { AgentEvalBenchmark, AgentEvalBenchmarkListItem } from '@lobechat/types';
 
 export interface BenchmarkSliceState {
-  // ============================================
-  // List Data - Simple Array
-  // ============================================
-  /**
-   * List of benchmarks for list page display
-   * May include computed fields like testCaseCount
-   */
+  // List — simple array
   benchmarkList: AgentEvalBenchmarkListItem[];
   benchmarkListInit: boolean;
 
-  // ============================================
-  // Detail Data - Map for Caching
-  // ============================================
-  /**
-   * Map of benchmark details keyed by ID
-   * Caches detail page data for multiple benchmarks
-   * Enables optimistic updates and per-item loading
-   */
+  // Detail — map for multi-entity caching
   benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
+  loadingBenchmarkDetailIds: string[]; // per-item loading
 
-  /**
-   * Track which benchmark details are being loaded/updated
-   * For showing spinners on specific items
-   */
-  loadingBenchmarkDetailIds: string[];
-
-  // ============================================
-  // Mutation States
-  // ============================================
+  // Mutation states (drive form-level UI)
   isCreatingBenchmark: boolean;
   isUpdatingBenchmark: boolean;
   isDeletingBenchmark: boolean;
@@ -272,180 +106,51 @@ export const benchmarkInitialState: BenchmarkSliceState = {
 
 ## Reducer Pattern (for Detail Map)
 
-### Why Use Reducer?
+When the Detail Map needs optimistic updates (i.e. the user edits a row and the UI should reflect it before the server confirms), wire a typed reducer instead of inlining `set` calls. This keeps mutations testable and the dispatch surface small.
 
-- **Immutable updates** - Immer ensures immutability
-- **Type-safe actions** - TypeScript discriminated unions
-- **Testable** - Pure functions easy to test
-- **Reusable** - Same reducer for optimistic updates and server data
-
-### Reducer Structure
-
-```typescript
-// src/store/eval/slices/benchmark/reducer.ts
-import { produce } from 'immer';
-import type { AgentEvalBenchmark } from '@lobechat/types';
-
-// ============================================
-// Action Types
-// ============================================
-
-type SetBenchmarkDetailAction = {
-  id: string;
-  type: 'setBenchmarkDetail';
-  value: AgentEvalBenchmark;
-};
-
-type UpdateBenchmarkDetailAction = {
-  id: string;
-  type: 'updateBenchmarkDetail';
-  value: Partial<AgentEvalBenchmark>;
-};
-
-type DeleteBenchmarkDetailAction = {
-  id: string;
-  type: 'deleteBenchmarkDetail';
-};
-
-export type BenchmarkDetailDispatch =
-  | SetBenchmarkDetailAction
-  | UpdateBenchmarkDetailAction
-  | DeleteBenchmarkDetailAction;
-
-// ============================================
-// Reducer Function
-// ============================================
-
-export const benchmarkDetailReducer = (
-  state: Record<string, AgentEvalBenchmark> = {},
-  payload: BenchmarkDetailDispatch,
-): Record<string, AgentEvalBenchmark> => {
-  switch (payload.type) {
-    case 'setBenchmarkDetail': {
-      return produce(state, (draft) => {
-        draft[payload.id] = payload.value;
-      });
-    }
-
-    case 'updateBenchmarkDetail': {
-      return produce(state, (draft) => {
-        if (draft[payload.id]) {
-          draft[payload.id] = { ...draft[payload.id], ...payload.value };
-        }
-      });
-    }
-
-    case 'deleteBenchmarkDetail': {
-      return produce(state, (draft) => {
-        delete draft[payload.id];
-      });
-    }
-
-    default:
-      return state;
-  }
-};
-```
-
-### Internal Dispatch Methods
-
-```typescript
-// In action.ts
-export interface BenchmarkAction {
-  // ... other methods ...
-
-  // Internal methods - not for direct UI use
-  internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
-  internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
-}
-
-export const createBenchmarkSlice: StateCreator<...> = (set, get) => ({
-  // ... other methods ...
-
-  // Internal - Dispatch to reducer
-  internal_dispatchBenchmarkDetail: (payload) => {
-    const currentMap = get().benchmarkDetailMap;
-    const nextMap = benchmarkDetailReducer(currentMap, payload);
-
-    // Only update if changed
-    if (isEqual(nextMap, currentMap)) return;
-
-    set(
-      { benchmarkDetailMap: nextMap },
-      false,
-      `dispatchBenchmarkDetail/${payload.type}`,
-    );
-  },
-
-  // Internal - Update loading state
-  internal_updateBenchmarkDetailLoading: (id, loading) => {
-    set(
-      (state) => {
-        if (loading) {
-          return { loadingBenchmarkDetailIds: [...state.loadingBenchmarkDetailIds, id] };
-        }
-        return {
-          loadingBenchmarkDetailIds: state.loadingBenchmarkDetailIds.filter((i) => i !== id),
-        };
-      },
-      false,
-      'updateBenchmarkDetailLoading',
-    );
-  },
-});
-```
+> See [`references/reducer.md`](./references/reducer.md) for the full discriminated-union action types, the `produce`-based reducer, and the `internal_dispatch*` slice methods that connect them to Zustand.
 
 ---
 
 ## Data Structure Comparison
 
-### ❌ WRONG - Single Detail Object
+### ❌ WRONG — Single Detail Object
 
 ```typescript
 interface BenchmarkSliceState {
-  // ❌ Can only cache one detail
   benchmarkDetail: AgentEvalBenchmark | null;
-
-  // ❌ Global loading state
   isLoadingBenchmarkDetail: boolean;
 }
 ```
 
-**Problems:**
+Problems:
 
 - Can only cache one detail page at a time
-- Switching between details causes unnecessary refetches
+- Switching between details forces refetch
 - No optimistic updates
 - No per-item loading states
 
-### ✅ CORRECT - Separate List and Detail
+### ✅ CORRECT — Separate List and Detail
 
 ```typescript
-import type { AgentEvalBenchmark, AgentEvalBenchmarkListItem } from '@lobechat/types';
-
 interface BenchmarkSliceState {
-  // ✅ List data - simple array
   benchmarkList: AgentEvalBenchmarkListItem[];
   benchmarkListInit: boolean;
 
-  // ✅ Detail data - map for caching
   benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
-
-  // ✅ Per-item loading
   loadingBenchmarkDetailIds: string[];
 
-  // ✅ Mutation states
   isCreatingBenchmark: boolean;
   isUpdatingBenchmark: boolean;
   isDeletingBenchmark: boolean;
 }
 ```
 
-**Benefits:**
+Benefits:
 
 - Cache multiple detail pages
 - Fast navigation between cached details
-- Optimistic updates with reducer
+- Optimistic updates via reducer
 - Per-item loading states
 - Clear separation of concerns
 
@@ -455,22 +160,16 @@ interface BenchmarkSliceState {
 
 ### Accessing List Data
 
-```typescript
+```tsx
 const BenchmarkList = () => {
-  // Simple array access
   const benchmarks = useEvalStore((s) => s.benchmarkList);
   const isInit = useEvalStore((s) => s.benchmarkListInit);
 
   if (!isInit) return <Loading />;
-
   return (
     <div>
-      {benchmarks.map(b => (
-        <BenchmarkCard
-          key={b.id}
-          name={b.name}
-          testCaseCount={b.testCaseCount} // Computed field
-        />
+      {benchmarks.map((b) => (
+        <BenchmarkCard key={b.id} name={b.name} testCaseCount={b.testCaseCount} />
       ))}
     </div>
   );
@@ -479,22 +178,18 @@ const BenchmarkList = () => {
 
 ### Accessing Detail Data
 
-```typescript
+```tsx
 const BenchmarkDetail = () => {
   const { benchmarkId } = useParams<{ benchmarkId: string }>();
 
-  // Get from map
   const benchmark = useEvalStore((s) =>
     benchmarkId ? s.benchmarkDetailMap[benchmarkId] : undefined,
   );
-
-  // Check loading
   const isLoading = useEvalStore((s) =>
     benchmarkId ? s.loadingBenchmarkDetailIds.includes(benchmarkId) : false,
   );
 
   if (!benchmark) return <Loading />;
-
   return (
     <div>
       <h1>{benchmark.name}</h1>
@@ -510,7 +205,6 @@ const BenchmarkDetail = () => {
 // src/store/eval/slices/benchmark/selectors.ts
 export const benchmarkSelectors = {
   getBenchmarkDetail: (id: string) => (s: EvalStore) => s.benchmarkDetailMap[id],
-
   isLoadingBenchmarkDetail: (id: string) => (s: EvalStore) =>
     s.loadingBenchmarkDetailIds.includes(id),
 };
@@ -524,7 +218,7 @@ const isLoading = useEvalStore(benchmarkSelectors.isLoadingBenchmarkDetail(bench
 
 ## Decision Tree
 
-```
+```text
 Need to store data?
 │
 ├─ Is it a LIST for display?
@@ -547,43 +241,40 @@ Need to store data?
 
 When designing store state structure:
 
-- [ ] **Organize types by entity** in separate files (e.g., `benchmark.ts`, `agentEvalDataset.ts`)
+- [ ] **Organize types by entity** in separate files (e.g. `benchmark.ts`, `agentEvalDataset.ts`)
 - [ ] Create **Detail** type (full entity with all fields including heavy ones)
 - [ ] Create **ListItem** type:
-  - [ ] Subset of Detail type (exclude heavy fields)
+  - [ ] Subset of Detail (exclude heavy fields)
   - [ ] May include computed statistics for UI
-  - [ ] **NOT** extending Detail type (it's a subset, not extension)
+  - [ ] **NOT** `extends` Detail
 - [ ] Use **array** for list data: `xxxList: XxxListItem[]`
 - [ ] Use **Map** for detail data: `xxxDetailMap: Record<string, Xxx>`
-- [ ] Add per-item loading: `loadingXxxDetailIds: string[]`
-- [ ] Create **reducer** for detail map if optimistic updates needed
-- [ ] Add **internal dispatch** and **loading** methods
-- [ ] Create **selectors** for clean access (optional but recommended)
-- [ ] Document in comments:
-  - [ ] What fields are excluded from List and why
-  - [ ] What computed fields mean
-  - [ ] What each Map is for
+- [ ] Per-item loading: `loadingXxxDetailIds: string[]`
+- [ ] **Reducer** for detail map if optimistic updates needed (see [`references/reducer.md`](./references/reducer.md))
+- [ ] **Internal dispatch** and **loading** methods
+- [ ] **Selectors** for clean access (optional but recommended)
+- [ ] Document in comments which fields are excluded from List and why
 
 ---
 
 ## Best Practices
 
-1. **File organization** - One entity per file, not mixed together
-2. **List is subset** - ListItem excludes heavy fields, not extends Detail
-3. **Clear naming** - `xxxList` for arrays, `xxxDetailMap` for maps
-4. **Consistent patterns** - All detail maps follow same structure
-5. **Type safety** - Never use `any`, always use proper types
-6. **Document exclusions** - Comment which fields are excluded from List and why
-7. **Selectors** - Encapsulate access patterns
-8. **Loading states** - Per-item for details, global for lists
-9. **Immutability** - Use Immer in reducers
+1. **File organization** — one entity per file, not mixed
+2. **List is a subset** — ListItem excludes heavy fields, does not `extends` Detail
+3. **Clear naming** — `xxxList` for arrays, `xxxDetailMap` for maps
+4. **Consistent patterns** — all detail maps follow the same shape
+5. **Type safety** — never use `any`, always use proper types
+6. **Document exclusions** — comment which fields are excluded and why
+7. **Selectors** — encapsulate access patterns
+8. **Loading states** — per-item for details, global for mutations
+9. **Immutability** — use Immer in reducers
 
 ### Common Mistakes to Avoid
 
 ❌ **DON'T extend Detail in List:**
 
 ```typescript
-// Wrong - List should not extend Detail
+// Wrong — pulls heavy fields back in
 export interface BenchmarkListItem extends Benchmark {
   testCaseCount?: number;
 }
@@ -592,7 +283,6 @@ export interface BenchmarkListItem extends Benchmark {
 ✅ **DO create separate subset:**
 
 ```typescript
-// Correct - List is a subset with computed fields
 export interface BenchmarkListItem {
   id: string;
   name: string;
@@ -603,14 +293,14 @@ export interface BenchmarkListItem {
 
 ❌ **DON'T mix entities in one file:**
 
-```typescript
-// Wrong - all entities in agentEvalEntities.ts
+```text
+// Wrong — all entities in agentEvalEntities.ts
 ```
 
 ✅ **DO separate by entity:**
 
-```typescript
-// Correct - separate files
+```text
+// Correct — separate files
 // benchmark.ts
 // agentEvalDataset.ts
 // agentEvalRun.ts
@@ -620,5 +310,5 @@ export interface BenchmarkListItem {
 
 ## Related Skills
 
-- `data-fetching` - How to fetch and update this data
-- `zustand` - General Zustand patterns
+- `data-fetching` — how to fetch and update this data
+- `zustand` — general Zustand patterns

.agents/skills/store-data-structures/references/reducer.md

@@ -0,0 +1,118 @@
+# Reducer Pattern (for Detail Map)
+
+## Why Use a Reducer?
+
+- **Immutable updates** — Immer makes immutability easy
+- **Type-safe actions** — discriminated union of action types prevents typos
+- **Testable** — pure function, easy to unit test
+- **Reusable** — same reducer powers optimistic updates and server-data writes
+
+## Reducer Structure
+
+```typescript
+// src/store/eval/slices/benchmark/reducer.ts
+import { produce } from 'immer';
+import type { AgentEvalBenchmark } from '@lobechat/types';
+
+// Action types — discriminated union
+type SetBenchmarkDetailAction = {
+  id: string;
+  type: 'setBenchmarkDetail';
+  value: AgentEvalBenchmark;
+};
+
+type UpdateBenchmarkDetailAction = {
+  id: string;
+  type: 'updateBenchmarkDetail';
+  value: Partial<AgentEvalBenchmark>;
+};
+
+type DeleteBenchmarkDetailAction = {
+  id: string;
+  type: 'deleteBenchmarkDetail';
+};
+
+export type BenchmarkDetailDispatch =
+  | SetBenchmarkDetailAction
+  | UpdateBenchmarkDetailAction
+  | DeleteBenchmarkDetailAction;
+
+export const benchmarkDetailReducer = (
+  state: Record<string, AgentEvalBenchmark> = {},
+  payload: BenchmarkDetailDispatch,
+): Record<string, AgentEvalBenchmark> => {
+  switch (payload.type) {
+    case 'setBenchmarkDetail': {
+      return produce(state, (draft) => {
+        draft[payload.id] = payload.value;
+      });
+    }
+
+    case 'updateBenchmarkDetail': {
+      return produce(state, (draft) => {
+        if (draft[payload.id]) {
+          draft[payload.id] = { ...draft[payload.id], ...payload.value };
+        }
+      });
+    }
+
+    case 'deleteBenchmarkDetail': {
+      return produce(state, (draft) => {
+        delete draft[payload.id];
+      });
+    }
+
+    default:
+      return state;
+  }
+};
+```
+
+## Internal Dispatch Methods
+
+The slice exposes two `internal_*` methods so the reducer and the loading state stay encapsulated behind a stable contract:
+
+```typescript
+// In action.ts
+export interface BenchmarkAction {
+  // ... other methods ...
+
+  // Internal — not for direct UI use
+  internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
+  internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
+}
+
+export const createBenchmarkSlice: StateCreator<...> = (set, get) => ({
+  // ... other methods ...
+
+  // Dispatch to reducer
+  internal_dispatchBenchmarkDetail: (payload) => {
+    const currentMap = get().benchmarkDetailMap;
+    const nextMap = benchmarkDetailReducer(currentMap, payload);
+
+    // Skip set when nothing changed — avoids unnecessary re-renders
+    if (isEqual(nextMap, currentMap)) return;
+
+    set(
+      { benchmarkDetailMap: nextMap },
+      false,
+      `dispatchBenchmarkDetail/${payload.type}`,
+    );
+  },
+
+  // Update loading state for a specific id
+  internal_updateBenchmarkDetailLoading: (id, loading) => {
+    set(
+      (state) => ({
+        loadingBenchmarkDetailIds: loading
+          ? [...state.loadingBenchmarkDetailIds, id]
+          : state.loadingBenchmarkDetailIds.filter((i) => i !== id),
+      }),
+      false,
+      'updateBenchmarkDetailLoading',
+    );
+  },
+});
+```
+
+The `internal_` prefix is a convention — UI components should call the public mutation methods (e.g. `updateBenchmark`), which in turn call `internal_dispatch*`. This keeps reducer dispatch shapes out of the component layer.

.agents/skills/store-data-structures/references/types.md

@@ -0,0 +1,101 @@
+# Type Definitions in Detail
+
+The skill body's Type Definitions section covers the rules; this file holds the full worked examples to keep SKILL.md lean.
+
+## Organization
+
+Types should be organized by entity in separate files (not mixed):
+
+```text
+@lobechat/types/src/eval/
+├── benchmark.ts        # Benchmark types
+├── agentEvalDataset.ts # Dataset types
+├── agentEvalRun.ts     # Run types
+└── index.ts            # Re-exports
+```
+
+## Example: Benchmark Types
+
+```typescript
+// packages/types/src/eval/benchmark.ts
+import type { EvalBenchmarkRubric } from './rubric';
+
+/**
+ * Full benchmark entity with all fields including heavy data.
+ */
+export interface AgentEvalBenchmark {
+  createdAt: Date;
+  description?: string | null;
+  id: string;
+  identifier: string;
+  isSystem: boolean;
+  metadata?: Record<string, unknown> | null;
+  name: string;
+  referenceUrl?: string | null;
+  rubrics: EvalBenchmarkRubric[]; // Heavy field
+  updatedAt: Date;
+}
+
+/**
+ * Lightweight benchmark item — excludes heavy fields, may add computed stats.
+ */
+export interface AgentEvalBenchmarkListItem {
+  createdAt: Date;
+  description?: string | null;
+  id: string;
+  identifier: string;
+  isSystem: boolean;
+  name: string;
+  // Note: rubrics NOT included (heavy field)
+
+  // Computed statistics for UI display
+  datasetCount?: number;
+  runCount?: number;
+  testCaseCount?: number;
+}
+```
+
+## Example: Document Types (with heavy content)
+
+```typescript
+// packages/types/src/document.ts
+
+/**
+ * Full document entity — includes heavy content fields.
+ */
+export interface Document {
+  id: string;
+  title: string;
+  description?: string;
+  content: string; // Heavy field — full markdown content
+  editorData: any; // Heavy field — editor state
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Lightweight document item — excludes heavy content.
+ */
+export interface DocumentListItem {
+  id: string;
+  title: string;
+  description?: string;
+  // Note: content and editorData NOT included
+  createdAt: Date;
+  updatedAt: Date;
+
+  // Computed statistics
+  wordCount?: number;
+  lastEditedBy?: string;
+}
+```
+
+## Heavy Fields to Exclude from List
+
+- Large text content (`content`, `editorData`, `fullDescription`)
+- Complex objects (`rubrics`, `config`, `metrics`)
+- Binary data (`image`, `file`)
+- Large arrays (`messages`, `items`)
+
+The reason these belong only on Detail: list pages render many rows, so pulling heavy fields blows up payload size and slows render. Detail pages render one entity, so the full payload is fine.

.agents/skills/testing/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: testing
 description: Testing guide using Vitest. Use when writing tests (.test.ts, .test.tsx), fixing failing tests, improving test coverage, or debugging test issues. Triggers on test creation, test debugging, mock setup, or test-related questions.
+user-invocable: false
 ---
 
 # LobeHub Testing Guide

.agents/skills/trpc-router/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: trpc-router
 description: TRPC router development guide. Use when creating or modifying TRPC routers (src/server/routers/**), adding procedures, or working with server-side API endpoints. Triggers on TRPC router creation, procedure implementation, or API endpoint tasks.
+user-invocable: false
 ---
 
 # TRPC Router Guide

.agents/skills/typescript/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: typescript
-description: TypeScript code style and optimization guidelines. MUST READ before writing or modifying any TypeScript code (.ts, .tsx, .mts files). Also use when reviewing code quality or implementing type-safe patterns. Triggers on any TypeScript file edit, code style discussions, or type safety questions.
+description: "TypeScript code style and type-safety guide for LobeHub. Read before writing or editing any `.ts` / `.tsx` / `.mts` — covers `interface` vs `type`, `Record<PropertyKey, unknown>` over `any`/`object`, `as const satisfies`, `@ts-expect-error` over `@ts-ignore`, `import type` (`separate-type-imports`), `async`/`await` + `Promise.all`, `for…of` over indexed `for`, and the no-silent-`.catch(() => fallback)` rule. Also use when reviewing type quality, deciding module augmentation (`declare module`) over `namespace`, or designing extensible types (e.g. `PipelineContext.metadata`). Triggers on any TypeScript file edit, 'fix the type', 'why is this `any`', 'should this be interface or type', 'eslint type-import', 'ts-expect-error'."
+user-invocable: false
 ---
 
 # TypeScript Code Style Guide
@@ -28,12 +29,16 @@ description: TypeScript code style and optimization guidelines. MUST READ before
 ## Imports
 
 - This project uses `simple-import-sort/imports` and `consistent-type-imports` (`fixStyle: 'separate-type-imports'`)
+
 - **Separate type imports**: always use `import type { ... }` for type-only imports, NOT `import { type ... }` inline syntax
+
 - When a file already has `import type { ... }` from a package and you need to add a value import, keep them as **two separate statements**:
+
   ```ts
   import type { ChatTopicBotContext } from '@lobechat/types';
   import { RequestTrigger } from '@lobechat/types';
   ```
+
 - Within each import statement, specifiers are sorted **alphabetically by name**
 
 ## Code Structure
@@ -42,6 +47,7 @@ description: TypeScript code style and optimization guidelines. MUST READ before
 - Use consistent, descriptive naming; avoid obscure abbreviations
 - 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`)
 
 ## UI and Theming
 
@@ -51,7 +57,6 @@ description: TypeScript code style and optimization guidelines. MUST READ before
 
 ## Performance
 
-- Prefer `for…of` loops over index-based `for` loops
 - Reuse existing utils in `packages/utils` or installed npm packages
 - Query only required columns from database
 

.agents/skills/upstash-workflow/references/best-practices.md

@@ -0,0 +1,226 @@
+# Best Practices & Common Pitfalls
+
+Apply these once your scaffold from `implementation.md` is in place.
+
+## Table of Contents
+
+1. [Error Handling](#1-error-handling)
+2. [Logging](#2-logging)
+3. [Return Values](#3-return-values)
+4. [flowControl Configuration](#4-flowcontrol-configuration)
+5. [context.run() Best Practices](#5-contextrun-best-practices)
+6. [Payload Validation](#6-payload-validation)
+7. [Database Connection](#7-database-connection)
+8. [Testing](#8-testing)
+9. [Common Pitfalls](#common-pitfalls)
+
+---
+
+## 1. Error Handling
+
+```typescript
+export const { POST } = serve<Payload>(
+  async (context) => {
+    const { itemId } = context.requestPayload ?? {};
+
+    if (!itemId) {
+      return { success: false, error: 'Missing itemId in payload' };
+    }
+
+    try {
+      const result = await context.run('step-name', () => doWork(itemId));
+      return { success: true, itemId, result };
+    } catch (error) {
+      console.error('[workflow:error]', error);
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  },
+  { flowControl: { ... } },
+);
+```
+
+## 2. Logging
+
+Consistent prefixes make debugging much easier across QStash dashboards and grep:
+
+```typescript
+console.log('[{workflow}:{layer}] Starting with payload:', payload);
+console.log('[{workflow}:{layer}] Processing items:', { count: items.length });
+console.log('[{workflow}:{layer}] Completed:', result);
+console.error('[{workflow}:{layer}:error]', error);
+```
+
+## 3. Return Values
+
+Pick the shape that matches the layer's purpose — entry points return statistics, execution layers return per-item results.
+
+```typescript
+// Success
+return { success: true, itemId, result, message: 'Optional success message' };
+
+// Error
+return { success: false, error: 'Error description', itemId };
+
+// Statistics (entry point)
+return {
+  success: true,
+  totalEligible: 100,
+  toProcess: 80,
+  alreadyProcessed: 20,
+  dryRun: true, // if applicable
+  message: 'Summary message',
+};
+```
+
+## 4. flowControl Configuration
+
+Tune concurrency by layer — entry points are singletons, execution layers fan out.
+
+```typescript
+// Layer 1: Entry — single instance to avoid duplicate processing
+flowControl: { key: '{workflow}.process',  parallelism: 1,  ratePerSecond: 1 }
+
+// Layer 2: Pagination — moderate concurrency
+flowControl: { key: '{workflow}.paginate', parallelism: 20, ratePerSecond: 5 }
+
+// Layer 3: Execution — higher concurrency for parallel item work
+flowControl: { key: '{workflow}.execute',  parallelism: 10, ratePerSecond: 5 }
+```
+
+**Why these defaults:**
+
+- **Layer 1** always uses `parallelism: 1` so concurrent triggers don't both start the same batch.
+- **Layer 2** can fan out widely (10-20) since pagination is cheap.
+- **Layer 3** caps at 5-10 by default; raise/lower based on external API rate limits.
+
+## 5. context.run() Best Practices
+
+- Use descriptive step names with prefixes: `{workflow}:step-name`
+- Each step should be idempotent (safe to retry)
+- Don't nest `context.run()` calls — keep them flat
+- Use unique step names when processing multiple items:
+
+```typescript
+// ✅ Unique step names
+await Promise.all(
+  items.map((item) => context.run(`{workflow}:execute:${item.id}`, () => processItem(item))),
+);
+
+// ❌ Same step name — Upstash de-dupes by step name and you'll lose data
+await Promise.all(items.map((item) => context.run(`{workflow}:execute`, () => processItem(item))));
+```
+
+## 6. Payload Validation
+
+Validate at the top so failures are explicit, not silent `undefined` cascades:
+
+```typescript
+export const { POST } = serve<Payload>(
+  async (context) => {
+    const { itemId, configId } = context.requestPayload ?? {};
+
+    if (!itemId)   return { success: false, error: 'Missing itemId in payload' };
+    if (!configId) return { success: false, error: 'Missing configId in payload' };
+
+    // Proceed with work...
+  },
+  { flowControl: { ... } },
+);
+```
+
+## 7. Database Connection
+
+Get the connection once per workflow — `getServerDB()` is async, repeating it inside each step adds latency:
+
+```typescript
+export const { POST } = serve<Payload>(
+  async (context) => {
+    const db = await getServerDB();
+
+    const item = await context.run('get-item', () => itemModel.findById(db, itemId));
+    const result = await context.run('save-result', () => resultModel.create(db, result));
+  },
+  { flowControl: { ... } },
+);
+```
+
+## 8. Testing
+
+Integration tests should exercise both the dry-run statistics path and the full execution path:
+
+```typescript
+describe('WorkflowName', () => {
+  it('should process items successfully', async () => {
+    const items = await createTestItems();
+    await WorkflowClass.triggerProcessItems({ dryRun: false });
+    await waitForCompletion();
+    const results = await getResults();
+    expect(results).toHaveLength(items.length);
+  });
+
+  it('should support dryRun mode', async () => {
+    const result = await WorkflowClass.triggerProcessItems({ dryRun: true });
+    expect(result).toMatchObject({
+      success: true,
+      dryRun: true,
+      totalEligible: expect.any(Number),
+      toProcess: expect.any(Number),
+    });
+  });
+});
+```
+
+---
+
+## Common Pitfalls
+
+### ❌ Reusing `context.run()` step names
+
+```typescript
+// Bad — Upstash dedupes by step name
+await Promise.all(items.map((item) => context.run('process', () => process(item))));
+
+// Good
+await Promise.all(items.map((item) => context.run(`process:${item.id}`, () => process(item))));
+```
+
+### ❌ Skipping payload validation
+
+```typescript
+// Bad — undefined cascades into a confusing failure later
+const { itemId } = context.requestPayload ?? {};
+const result = await process(itemId);
+
+// Good — fail fast with a clear error
+if (!itemId) return { success: false, error: 'Missing itemId' };
+```
+
+### ❌ Skipping the filter step
+
+```typescript
+// Bad — duplicates work for items that were already processed
+const allItems = await getAllItems();
+await Promise.all(allItems.map((item) => triggerExecute(item)));
+
+// Good — keeps the pipeline idempotent
+const allItems = await getAllItems();
+const itemsNeedingProcessing = await filterExisting(allItems);
+await Promise.all(itemsNeedingProcessing.map((item) => triggerExecute(item)));
+```
+
+### ❌ Inconsistent logging
+
+```typescript
+// Bad — different prefixes, mixed formats
+console.log('Starting workflow');
+log.info('Processing item:', itemId);
+console.log(`Done with ${itemId}`);
+
+// Good — uniform prefix lets you grep by workflow+layer
+console.log('[workflow:layer] Starting with payload:', payload);
+console.log('[workflow:layer] Processing item:', { itemId });
+console.log('[workflow:layer] Completed:', { itemId, result });
+```

.agents/skills/upstash-workflow/references/cloud.md

@@ -1,6 +1,20 @@
 # Cloud Project Workflow Configuration
 
-This document covers cloud-specific workflow configurations and patterns for the lobehub-cloud project.
+Cloud-specific workflow configurations and patterns for the lobehub-cloud project.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Directory Structure](#directory-structure) — submodule + cloud layout
+3. [Cloud-Specific Patterns](#cloud-specific-patterns) — cloud-only workflows + re-export pattern
+4. [TypeScript Path Mappings](#typescript-path-mappings)
+5. [Workflow Class Location](#workflow-class-location) — cloud-only vs shared
+6. [Environment Variables](#environment-variables)
+7. [Best Practices](#best-practices) — decide cloud vs OSS, re-export rules, naming
+8. [Migration Guide](#migration-guide) — moving workflows from cloud to lobehub
+9. [Examples](#examples) — `welcome-placeholder`, `agent-eval-run`
+10. [Troubleshooting](#troubleshooting) — circular imports, 404s, type errors
+11. [Related Documentation](#related-documentation)
 
 ## Overview
 
@@ -15,7 +29,7 @@ The lobehub-cloud project extends the open-source lobehub codebase with cloud-sp
 
 ### Lobehub Submodule (Open-source)
 
-```
+```text
 lobehub/
 └── src/
     ├── app/(backend)/api/workflows/
@@ -28,7 +42,7 @@ lobehub/
 
 ### Lobehub-cloud (Proprietary)
 
-```
+```text
 lobehub-cloud/
 └── src/
     ├── app/(backend)/api/workflows/
@@ -60,7 +74,7 @@ lobehub-cloud/
 
 **Structure**:
 
-```
+```text
 lobehub-cloud/src/
 ├── app/(backend)/api/workflows/
 │   └── feature-name/
@@ -162,7 +176,7 @@ This allows cloud to override specific modules while using lobehub defaults.
 
 Place workflow class in cloud:
 
-```
+```text
 lobehub-cloud/src/server/workflows/featureName/index.ts
 ```
 
@@ -170,7 +184,7 @@ lobehub-cloud/src/server/workflows/featureName/index.ts
 
 Place workflow class in lobehub, re-export in cloud if needed:
 
-```
+```text
 lobehub/src/server/workflows/featureName/index.ts
 ```
 
@@ -245,7 +259,7 @@ For shared features:
 
 Follow consistent naming across lobehub and cloud:
 
-```
+```text
 # Both should use same structure
 lobehub/src/app/(backend)/api/workflows/feature-name/
 lobehub-cloud/src/app/(backend)/api/workflows/feature-name/
@@ -306,7 +320,7 @@ import { Workflow } from 'lobehub/src/server/workflows/feature';
 
 **Structure**:
 
-```
+```text
 lobehub-cloud/
 ├── src/app/(backend)/api/workflows/welcome-placeholder/
 │   ├── process-users/route.ts

.agents/skills/upstash-workflow/references/examples.md

@@ -0,0 +1,91 @@
+# Worked Examples
+
+Two real workflows already in the codebase that follow this skill's pattern verbatim. Skim them when you want to see the pattern applied to concrete entities.
+
+## Example 1: Welcome Placeholder
+
+**Use case:** Generate AI-powered welcome placeholders for users.
+
+**Structure:**
+
+- Layer 1: `process-users` — entry point, checks eligible users
+- Layer 2: `paginate-users` — paginates through active users
+- Layer 3: `generate-user` — generates placeholders for ONE user
+
+**Key features:**
+
+- Filters users who already have cached placeholders in Redis
+- `paidOnly` flag to scope to subscribed users
+- `dryRun` mode for statistics
+- Fan-out for large user batches (`CHUNK_SIZE=20`)
+
+**Layer 3 shape:**
+
+```typescript
+export const { POST } = serve<GenerateUserPlaceholderPayload>(async (context) => {
+  const { userId } = context.requestPayload ?? {};
+
+  const workflow = new WelcomePlaceholderWorkflow(db, userId);
+  const placeholders = await context.run('generate', () => workflow.generate());
+
+  return { success: true, userId, placeholdersCount: placeholders.length };
+});
+```
+
+**Files:**
+
+- `/api/workflows/welcome-placeholder/process-users/route.ts`
+- `/api/workflows/welcome-placeholder/paginate-users/route.ts`
+- `/api/workflows/welcome-placeholder/generate-user/route.ts`
+- `/server/workflows/welcomePlaceholder/index.ts`
+
+---
+
+## Example 2: Agent Welcome
+
+**Use case:** Generate welcome messages and open questions for AI agents.
+
+**Structure:**
+
+- Layer 1: `process-agents` — entry point, checks eligible agents
+- Layer 2: `paginate-agents` — paginates through active agents
+- Layer 3: `generate-agent` — generates welcome data for ONE agent
+
+**Key features:**
+
+- Filters agents who already have cached data in Redis
+- `paidOnly` flag for subscribed users' agents only
+- `dryRun` mode for statistics
+- Fan-out for large agent batches (`CHUNK_SIZE=20`)
+
+**Layer 3 shape:**
+
+```typescript
+export const { POST } = serve<GenerateAgentWelcomePayload>(async (context) => {
+  const { agentId } = context.requestPayload ?? {};
+
+  const workflow = new AgentWelcomeWorkflow(db, agentId);
+  const data = await context.run('generate', () => workflow.generate());
+
+  return { success: true, agentId, data };
+});
+```
+
+**Files:**
+
+- `/api/workflows/agent-welcome/process-agents/route.ts`
+- `/api/workflows/agent-welcome/paginate-agents/route.ts`
+- `/api/workflows/agent-welcome/generate-agent/route.ts`
+- `/server/workflows/agentWelcome/index.ts`
+
+---
+
+## What's identical, what differs
+
+Both workflows are the **same pattern** — they only differ in:
+
+- Entity type (users vs agents)
+- Business logic (placeholder generation vs welcome generation)
+- Data source (different database queries)
+
+Everything else — the 3-layer split, dry-run handling, fan-out, filter-existing, flowControl tuning — is identical. That's the whole point: once you internalize the pattern, adding a new workflow is mostly entity-substitution.

.agents/skills/upstash-workflow/references/implementation.md

@@ -0,0 +1,333 @@
+# Implementation Patterns
+
+Full code templates for the 3-layer architecture. Read this when actually writing workflow files.
+
+## Table of Contents
+
+1. [Workflow Class](#workflow-class) — `src/server/workflows/{workflowName}/index.ts`
+2. [Layer 1: Entry Point](#layer-1-entry-point-process-) — `process-*` route
+3. [Layer 2: Pagination](#layer-2-pagination-paginate-) — `paginate-*` route
+4. [Layer 3: Execution](#layer-3-execution-execute--generate-) — `execute-*` / `generate-*` route
+
+---
+
+## Workflow Class
+
+**Location:** `src/server/workflows/{workflowName}/index.ts`
+
+```typescript
+import { Client } from '@upstash/workflow';
+import debug from 'debug';
+
+const log = debug('lobe-server:workflows:{workflow-name}');
+
+// Workflow paths
+const WORKFLOW_PATHS = {
+  processItems: '/api/workflows/{workflow-name}/process-items',
+  paginateItems: '/api/workflows/{workflow-name}/paginate-items',
+  executeItem: '/api/workflows/{workflow-name}/execute-item',
+} as const;
+
+// Payload types
+export interface ProcessItemsPayload {
+  dryRun?: boolean;
+  force?: boolean;
+}
+
+export interface PaginateItemsPayload {
+  cursor?: string;
+  itemIds?: string[]; // For fanout chunks
+}
+
+export interface ExecuteItemPayload {
+  itemId: string;
+}
+
+const getWorkflowUrl = (path: string): string => {
+  const baseUrl = process.env.APP_URL;
+  if (!baseUrl) throw new Error('APP_URL is required to trigger workflows');
+  return new URL(path, baseUrl).toString();
+};
+
+const getWorkflowClient = (): Client => {
+  const token = process.env.QSTASH_TOKEN;
+  if (!token) throw new Error('QSTASH_TOKEN is required to trigger workflows');
+
+  const config: ConstructorParameters<typeof Client>[0] = { token };
+  if (process.env.QSTASH_URL) {
+    (config as Record<string, unknown>).url = process.env.QSTASH_URL;
+  }
+  return new Client(config);
+};
+
+export class {WorkflowName}Workflow {
+  private static client: Client;
+
+  private static getClient(): Client {
+    if (!this.client) this.client = getWorkflowClient();
+    return this.client;
+  }
+
+  static triggerProcessItems(payload: ProcessItemsPayload) {
+    const url = getWorkflowUrl(WORKFLOW_PATHS.processItems);
+    log('Triggering process-items workflow');
+    return this.getClient().trigger({ body: payload, url });
+  }
+
+  static triggerPaginateItems(payload: PaginateItemsPayload) {
+    const url = getWorkflowUrl(WORKFLOW_PATHS.paginateItems);
+    log('Triggering paginate-items workflow');
+    return this.getClient().trigger({ body: payload, url });
+  }
+
+  static triggerExecuteItem(payload: ExecuteItemPayload) {
+    const url = getWorkflowUrl(WORKFLOW_PATHS.executeItem);
+    log('Triggering execute-item workflow: %s', payload.itemId);
+    return this.getClient().trigger({ body: payload, url });
+  }
+
+  /**
+   * Filter items that need processing (e.g. check Redis cache, database state).
+   * Return only the ones that actually need work — keeps the pipeline idempotent.
+   */
+  static async filterItemsNeedingProcessing(itemIds: string[]): Promise<string[]> {
+    if (itemIds.length === 0) return [];
+    // Check existing state and return items that need processing
+    return itemIds;
+  }
+}
+```
+
+---
+
+## Layer 1: Entry Point (process-\*)
+
+**Purpose:** Validates prerequisites, calculates statistics, supports dry-run mode.
+
+```typescript
+import { serve } from '@upstash/workflow/nextjs';
+import { getServerDB } from '@/database/server';
+import { WorkflowClass, type ProcessPayload } from '@/server/workflows/{workflowName}';
+
+export const { POST } = serve<ProcessPayload>(
+  async (context) => {
+    const { dryRun, force } = context.requestPayload ?? {};
+
+    console.log('[{workflow}:process] Starting with payload:', { dryRun, force });
+
+    const allItemIds = await context.run('{workflow}:get-all-items', async () => {
+      const db = await getServerDB();
+      // Query database for eligible items
+      return items.map((item) => item.id);
+    });
+
+    console.log('[{workflow}:process] Total eligible items:', allItemIds.length);
+
+    if (allItemIds.length === 0) {
+      return { success: true, totalEligible: 0, message: 'No eligible items found' };
+    }
+
+    const itemsNeedingProcessing = await context.run('{workflow}:filter-existing', () =>
+      WorkflowClass.filterItemsNeedingProcessing(allItemIds),
+    );
+
+    const result = {
+      success: true,
+      totalEligible: allItemIds.length,
+      toProcess: itemsNeedingProcessing.length,
+      alreadyProcessed: allItemIds.length - itemsNeedingProcessing.length,
+    };
+
+    // Dry-run short-circuits before any side effects
+    if (dryRun) {
+      console.log('[{workflow}:process] Dry run mode, returning statistics only');
+      return {
+        ...result,
+        dryRun: true,
+        message: `[DryRun] Would process ${itemsNeedingProcessing.length} items`,
+      };
+    }
+
+    if (itemsNeedingProcessing.length === 0) {
+      return { ...result, message: 'All items already processed' };
+    }
+
+    await context.run('{workflow}:trigger-paginate', () => WorkflowClass.triggerPaginateItems({}));
+
+    return {
+      ...result,
+      message: `Triggered pagination for ${itemsNeedingProcessing.length} items`,
+    };
+  },
+  {
+    flowControl: {
+      key: '{workflow}.process',
+      parallelism: 1, // single instance — avoids duplicate processing
+      ratePerSecond: 1,
+    },
+  },
+);
+```
+
+---
+
+## Layer 2: Pagination (paginate-\*)
+
+**Purpose:** Handles cursor-based pagination, implements fan-out for large batches.
+
+```typescript
+import { serve } from '@upstash/workflow/nextjs';
+import { chunk } from 'es-toolkit/compat';
+import { getServerDB } from '@/database/server';
+import { WorkflowClass, type PaginatePayload } from '@/server/workflows/{workflowName}';
+
+const PAGE_SIZE = 50;
+const CHUNK_SIZE = 20;
+
+export const { POST } = serve<PaginatePayload>(
+  async (context) => {
+    const { cursor, itemIds: payloadItemIds } = context.requestPayload ?? {};
+
+    console.log('[{workflow}:paginate] Starting:', {
+      cursor,
+      itemIdsCount: payloadItemIds?.length ?? 0,
+    });
+
+    // If specific itemIds were passed in (from a fanout chunk), process them directly
+    if (payloadItemIds && payloadItemIds.length > 0) {
+      await Promise.all(
+        payloadItemIds.map((itemId) =>
+          context.run(`{workflow}:execute:${itemId}`, () =>
+            WorkflowClass.triggerExecuteItem({ itemId }),
+          ),
+        ),
+      );
+      return { success: true, processedItems: payloadItemIds.length };
+    }
+
+    // Paginate through all items
+    const itemBatch = await context.run('{workflow}:get-batch', async () => {
+      const db = await getServerDB();
+      const items = await db.query(...);
+      if (!items.length) return { ids: [] };
+      const last = items.at(-1);
+      return {
+        ids: items.map((item) => item.id),
+        cursor: last ? last.id : undefined,
+      };
+    });
+
+    const batchItemIds = itemBatch.ids;
+    const nextCursor = 'cursor' in itemBatch ? itemBatch.cursor : undefined;
+
+    if (batchItemIds.length === 0) {
+      return { success: true, message: 'Pagination complete' };
+    }
+
+    const itemIds = await context.run('{workflow}:filter-existing', () =>
+      WorkflowClass.filterItemsNeedingProcessing(batchItemIds),
+    );
+
+    if (itemIds.length > 0) {
+      if (itemIds.length > CHUNK_SIZE) {
+        // Fan out — recursively re-enter pagination with each chunk
+        const chunks = chunk(itemIds, CHUNK_SIZE);
+        console.log('[{workflow}:paginate] Fanout mode:', {
+          chunks: chunks.length,
+          chunkSize: CHUNK_SIZE,
+        });
+
+        await Promise.all(
+          chunks.map((ids, idx) =>
+            context.run(`{workflow}:fanout:${idx + 1}/${chunks.length}`, () =>
+              WorkflowClass.triggerPaginateItems({ itemIds: ids }),
+            ),
+          ),
+        );
+      } else {
+        // Process this page directly
+        await Promise.all(
+          itemIds.map((itemId) =>
+            context.run(`{workflow}:execute:${itemId}`, () =>
+              WorkflowClass.triggerExecuteItem({ itemId }),
+            ),
+          ),
+        );
+      }
+    }
+
+    // Tail-call into the next page
+    if (nextCursor) {
+      await context.run('{workflow}:next-page', () =>
+        WorkflowClass.triggerPaginateItems({ cursor: nextCursor }),
+      );
+    }
+
+    return {
+      success: true,
+      processedItems: itemIds.length,
+      skippedItems: batchItemIds.length - itemIds.length,
+      nextCursor: nextCursor ?? null,
+    };
+  },
+  {
+    flowControl: {
+      key: '{workflow}.paginate',
+      parallelism: 20,
+      ratePerSecond: 5,
+    },
+  },
+);
+```
+
+---
+
+## Layer 3: Execution (execute-\* / generate-\*)
+
+**Purpose:** Performs the actual business logic for exactly ONE item.
+
+```typescript
+import { serve } from '@upstash/workflow/nextjs';
+import { getServerDB } from '@/database/server';
+import { WorkflowClass, type ExecutePayload } from '@/server/workflows/{workflowName}';
+
+export const { POST } = serve<ExecutePayload>(
+  async (context) => {
+    const { itemId } = context.requestPayload ?? {};
+
+    if (!itemId) {
+      return { success: false, error: 'Missing itemId' };
+    }
+
+    const db = await getServerDB();
+
+    const item = await context.run('{workflow}:get-item', async () => {
+      // Query database for item
+      return item;
+    });
+
+    if (!item) {
+      return { success: false, error: 'Item not found' };
+    }
+
+    const result = await context.run('{workflow}:process-item', async () => {
+      const workflow = new WorkflowClass(db, itemId);
+      return workflow.generate(); // or process(), execute(), etc.
+    });
+
+    await context.run('{workflow}:save-result', async () => {
+      const workflow = new WorkflowClass(db, itemId);
+      return workflow.saveToRedis(result); // or saveToDatabase(), etc.
+    });
+
+    return { success: true, itemId, result };
+  },
+  {
+    flowControl: {
+      key: '{workflow}.execute',
+      parallelism: 10,
+      ratePerSecond: 5,
+    },
+  },
+);
+```

.agents/skills/version-release/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: version-release
-description: "Version release workflow. Use when the user mentions 'release', 'hotfix', 'version upgrade', 'weekly release', or '发版'/'发布'/'小班车'. This skill is for release process and GitHub Release notes (not docs/changelog page writing)."
+description: 'Version release workflow — release process and GitHub Release notes (not docs/changelog pages).'
+disable-model-invocation: true
+argument-hint: '[minor|patch] [version?]'
 ---
 
 # Version Release Workflow
 
-This skill is a router. The detailed steps live in `reference/`.
+This skill is a router. The detailed steps live in `references/`.
 
 ## Scope Boundary (Important)
 
@@ -30,12 +32,12 @@ The primary development branch is **canary**. All day-to-day development happens
 
 Only two release types are used in practice (major releases are extremely rare and can be ignored):
 
-| Type  | Use Case                                       | Frequency             | Source Branch  | PR Title Format                      | Version       | Reference                              |
-| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- | -------------------------------------- |
-| Minor | Feature iteration release                      | \~Every 4 weeks       | canary         | `🚀 release: v{x.y.0}`               | Manually set  | `reference/minor-release.md`           |
-| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 | `reference/patch-release-scenarios.md` |
+| Type  | Use Case                                       | Frequency             | Source Branch  | PR Title Format                      | Version       | Reference                               |
+| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- | --------------------------------------- |
+| Minor | Feature iteration release                      | \~Every 4 weeks       | canary         | `🚀 release: v{x.y.0}`               | Manually set  | `references/minor-release.md`           |
+| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 | `references/patch-release-scenarios.md` |
 
-For writing the release-note body (any release type), see `reference/release-notes-style.md`.
+For writing the release-note body (any release type), see `references/release-notes-style.md`.
 
 ## Auto-Release Trigger Rules (`auto-tag-release.yml`)
 
@@ -85,9 +87,9 @@ Before creating the release branch, verify the source branch:
 
 Pick the right reference and follow it end-to-end:
 
-- **Minor release** → `reference/minor-release.md`
-- **Patch release** (weekly / hotfix / model launch / DB migration) → `reference/patch-release-scenarios.md`
-- **Writing the PR body / release notes** (any release type) → `reference/release-notes-style.md`
+- **Minor release** → `references/minor-release.md`
+- **Patch release** (weekly / hotfix / model launch / DB migration) → `references/patch-release-scenarios.md`
+- **Writing the PR body / release notes** (any release type) → `references/release-notes-style.md`
 
 ### Hard Rules (apply to every release type)
 
@@ -95,4 +97,4 @@ Pick the right reference and follow it end-to-end:
 - **Do NOT** manually create tags — CI handles them.
 - Minor PR title format is strict (`🚀 release: v{x.y.z}`).
 - Patch PRs do not need an explicit version number.
-- Keep release facts accurate; do not invent metrics or availability statements. Release-note inputs (compare base, PR refs, contributor list) **must be derived from `git`** per `reference/release-notes-style.md` § Computing Inputs — never from memory or descriptions.
+- Keep release facts accurate; do not invent metrics or availability statements. Release-note inputs (compare base, PR refs, contributor list) **must be derived from `git`** per `references/release-notes-style.md` § Computing Inputs — never from memory or descriptions.

.agents/skills/version-release/references/release-notes-style.md

@@ -2,6 +2,20 @@
 
 Use this guide for **GitHub Release notes** — the body of a release PR that becomes the GitHub Release after merge. Do **not** use it for `docs/changelog/*.mdx` website pages (load `../../docs-changelog/SKILL.md` instead).
 
+## Table of Contents
+
+1. [Positioning](#positioning) — what this style optimizes for
+2. [Required Inputs Before Writing](#required-inputs-before-writing)
+3. [Computing Inputs (Hard Rules — Verify, Never Guess)](#computing-inputs-hard-rules--verify-never-guess) — base ref, PR refs, metrics, authors, pre-publish verification
+4. [Canonical Structure (Long-Form: Minor / Weekly)](#canonical-structure-long-form-minor--weekly)
+5. [Variants for Shorter Releases](#variants-for-shorter-releases) — hotfix, DB migration
+6. [Writing Rules (Hard)](#writing-rules-hard)
+7. [Style Rules (Long-Form)](#style-rules-long-form)
+8. [Release Size Heuristics](#release-size-heuristics) — when to use which variant
+9. [Contributor Ordering](#contributor-ordering)
+10. [Template](#template) — copy-paste skeleton
+11. [Quick Checklist](#quick-checklist) — long-form + hotfix
+
 ## Positioning
 
 This release-note style is:

.agents/skills/zustand/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: zustand
-description: Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
+description: "LobeHub Zustand store conventions: public/internal/dispatch action layers, optimistic update pattern, slice composition via `flattenActions`, and class-based action migration. Use whenever working under `src/store/**`, adding a `createXxxSlice`, writing `internal_*` or `internal_dispatch*` actions, designing `messagesMap`/`topicsMap` reducers, refactoring a `StateCreator` object slice into a `XxxActionImpl` class, or debugging stale store reads. Triggers on `useChatStore`/`useUserStore`/`useGlobalStore`, `createStore`, `flattenActions`, `StoreSetter`, `internal_dispatch`, 'add an action', 'zustand selector', 'store slice', 'class action', 'optimistic update'."
+user-invocable: false
 ---
 
 # LobeHub Zustand State Management

CHANGELOG.md

@@ -2,6 +2,43 @@
 
 # Changelog
 
+## [Version 2.1.57](https://github.com/lobehub/lobe-chat/compare/v2.1.57-canary.33...v2.1.57)
+
+<sup>Released on **2026-05-09**</sup>
+
+#### 🐛 Bug Fixes
+
+- **docker**: replace pnpm init with static package.json in /deps.
+- **onboarding**: guard skip/mode-switch footer with feature flag, desktop & init checks.
+- **misc**: hide runtime-only model aliases.
+
+#### ✨ Features
+
+- **misc**: set OSS default model to DeepSeek V4 Pro.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **docker**: replace pnpm init with static package.json in /deps, closes [#14576](https://github.com/lobehub/lobe-chat/issues/14576) ([8ed31df](https://github.com/lobehub/lobe-chat/commit/8ed31df))
+- **onboarding**: guard skip/mode-switch footer with feature flag, desktop & init checks, closes [#14560](https://github.com/lobehub/lobe-chat/issues/14560) ([9756dab](https://github.com/lobehub/lobe-chat/commit/9756dab))
+- **misc**: hide runtime-only model aliases, closes [#14552](https://github.com/lobehub/lobe-chat/issues/14552) ([2d33322](https://github.com/lobehub/lobe-chat/commit/2d33322))
+
+#### What's improved
+
+- **misc**: set OSS default model to DeepSeek V4 Pro, closes [#14555](https://github.com/lobehub/lobe-chat/issues/14555) ([8105fc0](https://github.com/lobehub/lobe-chat/commit/8105fc0))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ### [Version 2.1.56](https://github.com/lobehub/lobe-chat/compare/v2.1.55...v2.1.56)
 
 <sup>Released on **2026-05-01**</sup>

apps/cli/man/man1/lh.1

@@ -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.14" "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
@@ -68,9 +68,6 @@ Manage agent groups
 .B bot
 Manage bot integrations
 .TP
-.B cron
-Manage agent cron jobs
-.TP
 .B generate
 Generate content (text, image, video, speech) Alias: gen.
 .TP

apps/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lobehub/cli",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "type": "module",
   "bin": {
     "lh": "./dist/index.js",

apps/cli/src/commands/agent.ts

@@ -318,7 +318,7 @@ export function registerAgentCommand(program: Command) {
         }
 
         // 1. Exec agent to get operationId
-        const input: Record<string, any> = { prompt: options.prompt };
+        const input: Record<string, any> = { prompt: options.prompt, trigger: 'cli' };
         if (options.agentId) input.agentId = options.agentId;
         if (deviceId) input.deviceId = deviceId;
         if (options.slug) input.slug = options.slug;

apps/cli/src/commands/bot.ts

@@ -269,6 +269,204 @@ function registerAllowlistCommand(bot: Command, opts: AllowlistGroupOptions) {
     });
 }
 
+// ── Watch keywords subcommand factory ──────────────────
+
+interface WatchKeywordEntry {
+  instruction?: string;
+  keyword: string;
+}
+
+/**
+ * Normalise `settings.watchKeywords` into the canonical
+ * `{keyword, instruction?}[]` shape. Mirrors `extractWatchKeywordEntries`
+ * in `src/server/services/bot/platforms/const.ts` so the CLI accepts the
+ * same legacy on-disk shapes (`string`, `string[]`, `{keyword, …}[]`)
+ * the runtime is forgiving about — including the rare comma/whitespace
+ * separated string from a hand-pasted upgrade.
+ */
+function normalizeWatchKeywords(raw: unknown): WatchKeywordEntry[] {
+  const push = (out: Map<string, WatchKeywordEntry>, keyword: unknown, instruction?: unknown) => {
+    if (typeof keyword !== 'string') return;
+    const normalised = keyword.trim().toLowerCase();
+    if (!normalised) return;
+    const trimmedInstruction =
+      typeof instruction === 'string' && instruction.trim() ? instruction.trim() : undefined;
+    const existing = out.get(normalised);
+    if (!existing) {
+      out.set(normalised, { instruction: trimmedInstruction, keyword: normalised });
+      return;
+    }
+    if (!existing.instruction && trimmedInstruction) existing.instruction = trimmedInstruction;
+  };
+  const collected = new Map<string, WatchKeywordEntry>();
+  if (typeof raw === 'string') {
+    for (const piece of raw.split(/[\s,]+/)) push(collected, piece);
+  } else if (Array.isArray(raw)) {
+    for (const entry of raw) {
+      if (typeof entry === 'string') {
+        push(collected, entry);
+        continue;
+      }
+      if (entry && typeof entry === 'object' && 'keyword' in entry) {
+        const obj = entry as { instruction?: unknown; keyword?: unknown };
+        push(collected, obj.keyword, obj.instruction);
+      }
+    }
+  }
+  return [...collected.values()];
+}
+
+/**
+ * Build a `list / add / remove / clear` subcommand group around
+ * `settings.watchKeywords`. Shape differs from the user/channel allowlists
+ * (`{keyword, instruction?}` vs `{id, name?}`), so we duplicate the
+ * scaffolding instead of squeezing both shapes through one factory — the
+ * help text, column headers, and `--instruction` flag are all keyword-
+ * specific and would just bloat the unified version.
+ */
+function registerWatchKeywordsCommand(bot: Command) {
+  const group = bot
+    .command('watch-keywords')
+    .description(
+      'Manage watch keywords (non-mention channel triggers; the optional instruction is prepended to the user message before being sent to the AI)',
+    );
+
+  const readEntries = (bot: any): WatchKeywordEntry[] =>
+    normalizeWatchKeywords((bot.settings as Record<string, unknown> | null)?.watchKeywords);
+
+  const buildPayload = (bot: any, nextEntries: WatchKeywordEntry[]) => ({
+    id: bot.id,
+    settings: {
+      ...(bot.settings as Record<string, unknown>),
+      watchKeywords: nextEntries,
+    },
+  });
+
+  group
+    .command('list <botId>')
+    .description('List watch-keyword entries')
+    .option('--json', 'Output JSON')
+    .action(async (botId: string, options: { json?: boolean }) => {
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      if (options.json) {
+        outputJson(entries);
+        return;
+      }
+
+      if (entries.length === 0) {
+        console.log(`${pc.dim('No watch-keyword entries.')}`);
+        return;
+      }
+
+      printTable(
+        entries.map((e) => [e.keyword, e.instruction ?? pc.dim('-')]),
+        ['KEYWORD', 'INSTRUCTION'],
+      );
+    });
+
+  group
+    .command('add <botId> <keyword>')
+    .description('Add a watch keyword (with optional instruction prefix)')
+    .option(
+      '--instruction <text>',
+      'Prompt prepended to the user message when this keyword fires (omit for "just wake the bot")',
+    )
+    .action(async (botId: string, keyword: string, options: { instruction?: string }) => {
+      const trimmedKeyword = keyword.trim().toLowerCase();
+      if (!trimmedKeyword) {
+        log.error('Keyword cannot be empty.');
+        process.exit(1);
+        return;
+      }
+
+      const trimmedInstruction = options.instruction?.trim();
+
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      const existing = entries.find((e) => e.keyword === trimmedKeyword);
+      if (existing) {
+        // Upsert instruction on duplicate keyword — operators commonly
+        // re-run `add` to tweak the prompt without remembering to remove first.
+        if (trimmedInstruction && existing.instruction !== trimmedInstruction) {
+          existing.instruction = trimmedInstruction;
+          await client.agentBotProvider.update.mutate(buildPayload(b, entries) as any);
+          console.log(
+            `${pc.green('✓')} Updated instruction for ${pc.bold(trimmedKeyword)} (${entries.length} entr${entries.length === 1 ? 'y' : 'ies'})`,
+          );
+          return;
+        }
+        log.info(`${trimmedKeyword} is already on watchKeywords — nothing to do.`);
+        return;
+      }
+
+      const next = [
+        ...entries,
+        trimmedInstruction
+          ? { instruction: trimmedInstruction, keyword: trimmedKeyword }
+          : { keyword: trimmedKeyword },
+      ];
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, next) as any);
+      console.log(
+        `${pc.green('✓')} Added ${pc.bold(trimmedKeyword)}${trimmedInstruction ? ' (with instruction)' : ''} to watchKeywords (now ${next.length} entr${next.length === 1 ? 'y' : 'ies'})`,
+      );
+    });
+
+  group
+    .command('remove <botId> <keyword>')
+    .description('Remove a watch keyword')
+    .action(async (botId: string, keyword: string) => {
+      const trimmedKeyword = keyword.trim().toLowerCase();
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+      const next = entries.filter((e) => e.keyword !== trimmedKeyword);
+
+      if (next.length === entries.length) {
+        log.info(`${trimmedKeyword} is not on watchKeywords — nothing to do.`);
+        return;
+      }
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, next) as any);
+      console.log(
+        `${pc.green('✓')} Removed ${pc.bold(trimmedKeyword)} from watchKeywords (${next.length} entr${next.length === 1 ? 'y' : 'ies'} left)`,
+      );
+    });
+
+  group
+    .command('clear <botId>')
+    .description('Clear all watch keywords')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(async (botId: string, options: { yes?: boolean }) => {
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      if (entries.length === 0) {
+        log.info('watchKeywords is already empty — nothing to do.');
+        return;
+      }
+
+      if (!options.yes) {
+        const confirmed = await confirm(
+          `Clear all ${entries.length} watch-keyword entr${entries.length === 1 ? 'y' : 'ies'} from this bot?`,
+        );
+        if (!confirmed) {
+          console.log('Cancelled.');
+          return;
+        }
+      }
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, []) as any);
+      console.log(`${pc.green('✓')} Cleared watchKeywords on bot ${pc.bold(botId)}`);
+    });
+}
+
 // ── Command Registration ─────────────────────────────────
 
 export function registerBotCommand(program: Command) {
@@ -608,6 +806,10 @@ export function registerBotCommand(program: Command) {
     name: 'group-allowlist',
   });
 
+  // ── watch-keywords (LOBE-8891) ────────────────────────
+
+  registerWatchKeywordsCommand(bot);
+
   // ── remove ────────────────────────────────────────────
 
   bot

apps/cli/src/commands/migrate/openclaw.ts

@@ -208,7 +208,7 @@ function readAgentProfile(workspacePath: string): AgentProfile {
     // Try to extract **Emoji:** value (single emoji)
     const emojiMatch = content.match(/\*{0,2}Emoji:?\*{0,2}\s*(.+)/i);
     const rawAvatar = emojiMatch ? emojiMatch[1].trim() : undefined;
-    // Filter out placeholder text like （待定）(Chinese TBD), _(待定)_, (TBD), N/A, etc.
+    // Filter out placeholder text like (TBD), _(TBD)_, N/A, and Chinese-language equivalents.
     const isPlaceholder =
       rawAvatar && /^[_*（(].*[)）_*]$|^(?:tbd|todo|n\/?a|none|待定|未定)$/i.test(rawAvatar);
     const avatar = rawAvatar && !isPlaceholder ? rawAvatar : undefined;

apps/desktop/electron-builder.mjs

@@ -6,6 +6,10 @@ import { fileURLToPath } from 'node:url';
 
 import dotenv from 'dotenv';
 
+import {
+  copyExternalRuntimeModulesToSource,
+  getExternalRuntimeModulesFilesConfig,
+} from './external-runtime-deps.config.mjs';
 import {
   copyNativeModules,
   copyNativeModulesToSource,
@@ -106,6 +110,7 @@ const config = {
    */
   beforePack: async () => {
     await copyNativeModulesToSource();
+    await copyExternalRuntimeModulesToSource();
 
     console.info('📦 Downloading agent-browser binary...');
     execSync('node scripts/download-agent-browser.mjs', { stdio: 'inherit', cwd: __dirname });
@@ -251,6 +256,8 @@ const config = {
     '!node_modules',
     // Then explicitly include native modules using object form (handles pnpm symlinks)
     ...getNativeModulesFilesConfig(),
+    // Include non-native runtime modules that are intentionally externalized from Vite.
+    ...getExternalRuntimeModulesFilesConfig(),
   ],
   generateUpdatesFilesForAllChannels: true,
   linux: {

apps/desktop/electron.vite.config.ts

@@ -13,7 +13,8 @@ import {
   sharedRendererPlugins,
   sharedRollupOutput,
 } from '../../plugins/vite/sharedRendererConfig';
-import { getExternalDependencies } from './native-deps.config.mjs';
+import { externalRuntimeModules } from './external-runtime-deps.config.mjs';
+import { getNativeExternalDependencies } from './native-deps.config.mjs';
 
 /**
  * Force `base: '/'` in renderer config. The `electron-vite` preset
@@ -99,7 +100,11 @@ const desktopPackageJson = JSON.parse(
   readFileSync(path.resolve(__dirname, 'package.json'), 'utf8'),
 ) as { version: string };
 const electronRuntimeExternals = ['electron'];
-const mainProcessRuntimeExternals = [...electronRuntimeExternals, 'node-mac-permissions'];
+const mainProcessRuntimeExternals = [
+  ...electronRuntimeExternals,
+  ...externalRuntimeModules,
+  'node-mac-permissions',
+];
 
 console.info(`[electron-vite.config.ts] Detected UPDATE_CHANNEL: ${updateChannel}`);
 
@@ -113,7 +118,7 @@ export default defineConfig({
         // bufferutil and utf-8-validate are optional peer deps of ws that may not be installed.
         external: [
           ...mainProcessRuntimeExternals,
-          ...getExternalDependencies(),
+          ...getNativeExternalDependencies(),
           'bufferutil',
           'utf-8-validate',
         ],

apps/desktop/external-runtime-deps.config.mjs

@@ -0,0 +1,33 @@
+import {
+  copyModulesToSource,
+  getDependenciesForModules,
+  getModuleFilesConfig,
+} from './module-deps.config.mjs';
+
+/**
+ * Non-native modules intentionally externalized from the main-process bundle.
+ *
+ * These modules are not native dependencies. They stay external because their
+ * process-level side effects must be owned by one Node runtime module instance.
+ */
+export const externalRuntimeModules = ['electron-log'];
+
+/**
+ * Get all dependencies for runtime external modules.
+ * @returns {string[]}
+ */
+export function getAllExternalRuntimeDependencies() {
+  return getDependenciesForModules(externalRuntimeModules);
+}
+
+/**
+ * Generate files config objects for non-native runtime external modules.
+ * @returns {Array<{from: string, to: string, filter: string[]}>}
+ */
+export function getExternalRuntimeModulesFilesConfig() {
+  return getModuleFilesConfig(externalRuntimeModules);
+}
+
+export async function copyExternalRuntimeModulesToSource() {
+  await copyModulesToSource(externalRuntimeModules, 'runtime external module');
+}

apps/desktop/module-deps.config.mjs

@@ -0,0 +1,189 @@
+/* eslint-disable no-console */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const sourceNodeModules = path.join(__dirname, 'node_modules');
+
+/**
+ * Recursively resolve all dependencies of a module.
+ * @param {string} moduleName - The module to resolve
+ * @param {Set<string>} visited - Set of already visited modules
+ * @param {string} nodeModulesPath - Path to node_modules directory
+ * @returns {Set<string>} Set of all dependencies
+ */
+function resolveDependencies(moduleName, visited = new Set(), nodeModulesPath = sourceNodeModules) {
+  if (visited.has(moduleName)) {
+    return visited;
+  }
+
+  // Always add the module name first. Workspace and optional platform modules
+  // may not be materialized locally, but they still need stable package rules.
+  visited.add(moduleName);
+
+  const packageJsonPath = path.join(nodeModulesPath, moduleName, 'package.json');
+
+  if (!fs.existsSync(packageJsonPath)) {
+    return visited;
+  }
+
+  try {
+    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+    const dependencies = packageJson.dependencies || {};
+    const optionalDependencies = packageJson.optionalDependencies || {};
+
+    for (const dep of Object.keys(dependencies)) {
+      resolveDependencies(dep, visited, nodeModulesPath);
+    }
+
+    for (const dep of Object.keys(optionalDependencies)) {
+      resolveDependencies(dep, visited, nodeModulesPath);
+    }
+  } catch {
+    // Ignore unreadable package.json files; electron-builder will surface any
+    // actual missing runtime dependency during packaging or startup.
+  }
+
+  return visited;
+}
+
+/**
+ * Get all transitive dependencies for a set of top-level modules.
+ * @param {string[]} modules
+ * @returns {string[]}
+ */
+export function getDependenciesForModules(modules) {
+  const allDeps = new Set();
+
+  for (const moduleName of modules) {
+    const deps = resolveDependencies(moduleName);
+    for (const dep of deps) {
+      allDeps.add(dep);
+    }
+  }
+
+  return [...allDeps];
+}
+
+/**
+ * Generate glob patterns for electron-builder files config.
+ * @param {string[]} modules
+ * @returns {string[]}
+ */
+export function getModuleFilesPatterns(modules) {
+  return getDependenciesForModules(modules).map((dep) => `node_modules/${dep}/**/*`);
+}
+
+/**
+ * Generate object-form electron-builder files config.
+ * Object form is required because pnpm symlinks are resolved before packaging.
+ * @param {string[]} modules
+ * @returns {Array<{from: string, to: string, filter: string[]}>}
+ */
+export function getModuleFilesConfig(modules) {
+  return getDependenciesForModules(modules).map((dep) => ({
+    filter: ['**/*'],
+    from: `node_modules/${dep}`,
+    to: `node_modules/${dep}`,
+  }));
+}
+
+/**
+ * Copy module symlinks in source node_modules to real directories so
+ * electron-builder can include them via file rules.
+ * @param {string[]} modules
+ * @param {string} label
+ */
+export async function copyModulesToSource(modules, label) {
+  const deps = getDependenciesForModules(modules);
+
+  console.log(`📦 Resolving ${deps.length} ${label} symlinks for packaging...`);
+
+  for (const dep of deps) {
+    const modulePath = path.join(sourceNodeModules, dep);
+
+    try {
+      const stat = await fs.promises.lstat(modulePath);
+
+      if (stat.isSymbolicLink()) {
+        const realPath = await fs.promises.realpath(modulePath);
+        console.log(`  📎 ${dep} (resolving symlink)`);
+
+        await fs.promises.rm(modulePath, { force: true, recursive: true });
+        await fs.promises.mkdir(path.dirname(modulePath), { recursive: true });
+        await copyDir(realPath, modulePath);
+      }
+    } catch (err) {
+      console.log(`  ⏭️  ${dep} (skipped: ${err.code || err.message})`);
+    }
+  }
+
+  console.log(`✅ ${label} symlinks resolved`);
+}
+
+/**
+ * Copy modules to a destination node_modules directory, resolving symlinks.
+ * @param {string[]} modules
+ * @param {string} destNodeModules
+ * @param {string} label
+ */
+export async function copyModulesToDirectory(modules, destNodeModules, label) {
+  const deps = getDependenciesForModules(modules);
+
+  console.log(`📦 Copying ${deps.length} ${label} to unpacked directory...`);
+
+  for (const dep of deps) {
+    const sourcePath = path.join(sourceNodeModules, dep);
+    const destPath = path.join(destNodeModules, dep);
+
+    try {
+      const stat = await fs.promises.lstat(sourcePath);
+
+      if (stat.isSymbolicLink()) {
+        const realPath = await fs.promises.realpath(sourcePath);
+        console.log(`  📎 ${dep} (symlink -> ${path.relative(sourceNodeModules, realPath)})`);
+
+        await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+        await copyDir(realPath, destPath);
+      } else if (stat.isDirectory()) {
+        console.log(`  📁 ${dep}`);
+        await fs.promises.mkdir(path.dirname(destPath), { recursive: true });
+        await copyDir(sourcePath, destPath);
+      }
+    } catch (err) {
+      console.log(`  ⏭️  ${dep} (skipped: ${err.code || err.message})`);
+    }
+  }
+
+  console.log(`✅ ${label} copied successfully`);
+}
+
+/**
+ * Recursively copy a directory.
+ * @param {string} src
+ * @param {string} dest
+ */
+async function copyDir(src, dest) {
+  await fs.promises.mkdir(dest, { recursive: true });
+  const entries = await fs.promises.readdir(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      await copyDir(srcPath, destPath);
+    } else if (entry.isSymbolicLink()) {
+      const realPath = await fs.promises.realpath(srcPath);
+      const realStat = await fs.promises.stat(realPath);
+      if (realStat.isDirectory()) {
+        await copyDir(realPath, destPath);
+      } else {
+        await fs.promises.copyFile(realPath, destPath);
+      }
+    } else {
+      await fs.promises.copyFile(srcPath, destPath);
+    }
+  }
+}

apps/desktop/native-deps.config.mjs

@@ -1,4 +1,3 @@
-/* eslint-disable no-console */
 /**
  * Native dependencies configuration for Electron build
  *
@@ -9,12 +8,15 @@
  *
  * This module automatically resolves the full dependency tree.
  */
-import fs from 'node:fs';
 import os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import {
+  copyModulesToDirectory,
+  copyModulesToSource,
+  getDependenciesForModules,
+  getModuleFilesConfig,
+  getModuleFilesPatterns,
+} from './module-deps.config.mjs';
 
 /**
  * Get the current target platform
@@ -40,78 +42,20 @@ export const nativeModules = [
   'node-screenshots',
 ];
 
-/**
- * Recursively resolve all dependencies of a module
- * @param {string} moduleName - The module to resolve
- * @param {Set<string>} visited - Set of already visited modules (to avoid cycles)
- * @param {string} nodeModulesPath - Path to node_modules directory
- * @returns {Set<string>} Set of all dependencies
- */
-function resolveDependencies(
-  moduleName,
-  visited = new Set(),
-  nodeModulesPath = path.join(__dirname, 'node_modules'),
-) {
-  if (visited.has(moduleName)) {
-    return visited;
-  }
-
-  // Always add the module name first (important for workspace dependencies
-  // that may not be in local node_modules but are declared in nativeModules)
-  visited.add(moduleName);
-
-  const packageJsonPath = path.join(nodeModulesPath, moduleName, 'package.json');
-
-  // If module doesn't exist locally, still keep it in visited but skip dependency resolution
-  if (!fs.existsSync(packageJsonPath)) {
-    return visited;
-  }
-
-  try {
-    const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-    const dependencies = packageJson.dependencies || {};
-    const optionalDependencies = packageJson.optionalDependencies || {};
-
-    // Resolve regular dependencies
-    for (const dep of Object.keys(dependencies)) {
-      resolveDependencies(dep, visited, nodeModulesPath);
-    }
-
-    // Also resolve optional dependencies (important for native modules like @napi-rs/canvas
-    // which have platform-specific binaries in optional deps)
-    for (const dep of Object.keys(optionalDependencies)) {
-      resolveDependencies(dep, visited, nodeModulesPath);
-    }
-  } catch {
-    // Ignore errors reading package.json
-  }
-
-  return visited;
-}
-
 /**
  * Get all dependencies for all native modules (including transitive dependencies)
  * @returns {string[]} Array of all dependency names
  */
-export function getAllDependencies() {
-  const allDeps = new Set();
-
-  for (const nativeModule of nativeModules) {
-    const deps = resolveDependencies(nativeModule);
-    for (const dep of deps) {
-      allDeps.add(dep);
-    }
-  }
-
-  return [...allDeps];
+export function getAllNativeDependencies() {
+  return getDependenciesForModules(nativeModules);
 }
 
 /**
  * Generate glob patterns for electron-builder files config
  * @returns {string[]} Array of glob patterns
  */
-export function getFilesPatterns() {
-  return getAllDependencies().map((dep) => `node_modules/${dep}/**/*`);
+export function getNativeModuleFilesPatterns() {
+  return getModuleFilesPatterns(nativeModules);
 }
 
 /**
@@ -120,11 +64,7 @@ export function getFilesPatterns() {
  * @returns {Array<{from: string, to: string, filter: string[]}>}
  */
 export function getNativeModulesFilesConfig() {
-  return getAllDependencies().map((dep) => ({
-    filter: ['**/*'],
-    from: `node_modules/${dep}`,
-    to: `node_modules/${dep}`,
-  }));
+  return getModuleFilesConfig(nativeModules);
 }
 
 /**
@@ -132,15 +72,15 @@ export function getNativeModulesFilesConfig() {
  * @returns {string[]} Array of glob patterns
  */
 export function getAsarUnpackPatterns() {
-  return getAllDependencies().map((dep) => `node_modules/${dep}/**/*`);
+  return getNativeModuleFilesPatterns();
 }
 
 /**
  * Get the list of native dependencies for Vite external config
  * @returns {string[]} Array of dependency names
  */
-export function getExternalDependencies() {
-  return getAllDependencies();
+export function getNativeExternalDependencies() {
+  return getAllNativeDependencies();
 }
 
 /**
@@ -149,39 +89,7 @@ export function getExternalDependencies() {
  * included in the asar archive (electron-builder glob doesn't follow symlinks).
  */
 export async function copyNativeModulesToSource() {
-  const fsPromises = await import('node:fs/promises');
-  const deps = getAllDependencies();
-  const sourceNodeModules = path.join(__dirname, 'node_modules');
-
-  console.log(`📦 Resolving ${deps.length} native module symlinks for packaging...`);
-
-  for (const dep of deps) {
-    const modulePath = path.join(sourceNodeModules, dep);
-
-    try {
-      const stat = await fsPromises.lstat(modulePath);
-
-      if (stat.isSymbolicLink()) {
-        // Resolve the symlink to get the real path
-        const realPath = await fsPromises.realpath(modulePath);
-        console.log(`  📎 ${dep} (resolving symlink)`);
-
-        // Remove the symlink
-        await fsPromises.rm(modulePath, { force: true, recursive: true });
-
-        // Create parent directory if needed (for scoped packages like @napi-rs)
-        await fsPromises.mkdir(path.dirname(modulePath), { recursive: true });
-
-        // Copy the actual directory content in place of the symlink
-        await copyDir(realPath, modulePath);
-      }
-    } catch (err) {
-      // Module might not exist (optional dependency for different platform)
-      console.log(`  ⏭️  ${dep} (skipped: ${err.code || err.message})`);
-    }
-  }
-
-  console.log(`✅ Native module symlinks resolved`);
+  await copyModulesToSource(nativeModules, 'native module');
 }
 
 /**
@@ -190,72 +98,5 @@ export async function copyNativeModulesToSource() {
  * @param {string} destNodeModules - Destination node_modules path
  */
 export async function copyNativeModules(destNodeModules) {
-  const fsPromises = await import('node:fs/promises');
-  const deps = getAllDependencies();
-  const sourceNodeModules = path.join(__dirname, 'node_modules');
-
-  console.log(`📦 Copying ${deps.length} native modules to unpacked directory...`);
-
-  for (const dep of deps) {
-    const sourcePath = path.join(sourceNodeModules, dep);
-    const destPath = path.join(destNodeModules, dep);
-
-    try {
-      // Check if source exists (might be a symlink)
-      const stat = await fsPromises.lstat(sourcePath);
-
-      if (stat.isSymbolicLink()) {
-        // Resolve the symlink to get the real path
-        const realPath = await fsPromises.realpath(sourcePath);
-        console.log(`  📎 ${dep} (symlink -> ${path.relative(sourceNodeModules, realPath)})`);
-
-        // Create destination directory
-        await fsPromises.mkdir(path.dirname(destPath), { recursive: true });
-
-        // Copy the actual directory content (not the symlink)
-        await copyDir(realPath, destPath);
-      } else if (stat.isDirectory()) {
-        console.log(`  📁 ${dep}`);
-        await fsPromises.mkdir(path.dirname(destPath), { recursive: true });
-        await copyDir(sourcePath, destPath);
-      }
-    } catch (err) {
-      // Module might not exist (optional dependency for different platform)
-      console.log(`  ⏭️  ${dep} (skipped: ${err.code || err.message})`);
-    }
-  }
-
-  console.log(`✅ Native modules copied successfully`);
-}
-
-/**
- * Recursively copy a directory
- * @param {string} src - Source directory
- * @param {string} dest - Destination directory
- */
-async function copyDir(src, dest) {
-  const fsPromises = await import('node:fs/promises');
-
-  await fsPromises.mkdir(dest, { recursive: true });
-  const entries = await fsPromises.readdir(src, { withFileTypes: true });
-
-  for (const entry of entries) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-
-    if (entry.isDirectory()) {
-      await copyDir(srcPath, destPath);
-    } else if (entry.isSymbolicLink()) {
-      // For symlinks within the module, resolve and copy the actual file
-      const realPath = await fsPromises.realpath(srcPath);
-      const realStat = await fsPromises.stat(realPath);
-      if (realStat.isDirectory()) {
-        await copyDir(realPath, destPath);
-      } else {
-        await fsPromises.copyFile(realPath, destPath);
-      }
-    } else {
-      await fsPromises.copyFile(srcPath, destPath);
-    }
-  }
+  await copyModulesToDirectory(nativeModules, destNodeModules, 'native modules');
 }

apps/desktop/package.json

@@ -44,6 +44,7 @@
   "dependencies": {
     "@lobehub/fluent-emoji": "^4.1.0",
     "@napi-rs/canvas": "^0.1.70",
+    "electron-log": "^5.4.3",
     "get-windows": "^9.3.0",
     "node-screenshots": "^0.2.8"
   },
@@ -79,7 +80,6 @@
     "electron-builder": "^26.8.1",
     "electron-devtools-installer": "4.0.0",
     "electron-is": "^3.0.0",
-    "electron-log": "^5.4.3",
     "electron-store": "^8.2.0",
     "electron-updater": "^6.6.2",
     "electron-vite": "6.0.0-beta.1",
@@ -109,7 +109,7 @@
     "typescript": "^5.9.3",
     "undici": "^7.16.0",
     "uuid": "^14.0.0",
-    "vite": "^8.0.9",
+    "vite": "8.0.12",
     "vitest": "^3.2.4",
     "zod": "^3.25.76"
   },

apps/desktop/src/main/const/protocol.ts

@@ -1 +1,4 @@
 export const ELECTRON_BE_PROTOCOL_SCHEME = 'lobe-backend';
+
+export const LOCAL_FILE_PROTOCOL_SCHEME = 'localfile';
+export const LOCAL_FILE_PROTOCOL_HOST = 'file';

apps/desktop/src/main/const/store.ts

@@ -35,6 +35,7 @@ export const STORE_DEFAULTS: ElectronMainStore = {
   gatewayEnabled: true,
   gatewayUrl: 'https://device-gateway.lobehub.com',
   locale: 'auto',
+  localFileWorkspaceRoots: [],
   networkProxy: defaultProxySettings,
   shortcuts: DEFAULT_ELECTRON_DESKTOP_SHORTCUTS,
   storagePath: appStorageDir,

apps/desktop/src/main/controllers/GitCtr.ts

@@ -1,5 +1,5 @@
 import { execFile, spawn } from 'node:child_process';
-import { readFile, stat } from 'node:fs/promises';
+import { readFile, rm, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { promisify } from 'node:util';
 
@@ -11,6 +11,7 @@ import type {
   GitBranchListItem,
   GitCheckoutResult,
   GitFileDiffStatus,
+  GitFileRevertResult,
   GitLinkedPullRequestResult,
   GitPullResult,
   GitPushResult,
@@ -1106,4 +1107,70 @@ export default class GitController extends ControllerModule {
       return { error: stderr || 'git push failed', success: false };
     }
   }
+
+  /**
+   * Revert a single working-tree change. Mirrors what "Discard changes" does
+   * in GitHub Desktop / VSCode SCM: restore the file to its HEAD state,
+   * dropping any unstaged / staged edits — and physically delete the file
+   * when it doesn't exist at HEAD (untracked or staged-add).
+   *
+   * Branch logic by HEAD presence:
+   *  - present at HEAD  → `git checkout HEAD -- <file>` (covers modified,
+   *    deleted, staged-D — restores both index + worktree from HEAD)
+   *  - absent at HEAD   → `git rm --cached` (unstage if staged-A; silent
+   *    no-op for untracked) + `fs.rm` to delete the file from disk
+   *
+   * filePath is the repo-relative path from `git status` output, the same
+   * shape we hand to the renderer in `GitWorkingTreePatch.filePath`. We
+   * reject absolute paths and `..` traversal so the renderer can't poke
+   * outside the repo even if its payload were tampered with.
+   */
+  @IpcMethod()
+  async revertGitFile(payload: { filePath: string; path: string }): Promise<GitFileRevertResult> {
+    const { path: dirPath, filePath } = payload;
+    if (!filePath?.trim()) return { error: 'File path is required', success: false };
+    if (path.isAbsolute(filePath) || filePath.split(/[/\\]/).includes('..')) {
+      return { error: `Invalid file path: ${filePath}`, success: false };
+    }
+
+    const execFileAsync = promisify(execFile);
+
+    // Probe HEAD via cat-file -e — exit 0 means the blob exists at HEAD.
+    let existsAtHead: boolean;
+    try {
+      await execFileAsync('git', ['cat-file', '-e', `HEAD:${filePath}`], {
+        cwd: dirPath,
+        timeout: 5000,
+      });
+      existsAtHead = true;
+    } catch {
+      existsAtHead = false;
+    }
+
+    try {
+      if (existsAtHead) {
+        await execFileAsync('git', ['checkout', 'HEAD', '--', filePath], {
+          cwd: dirPath,
+          timeout: 15_000,
+        });
+      } else {
+        // Unstage if the file is in the index (staged-add). `git rm --cached`
+        // exits non-zero on untracked paths, which is fine — swallow it.
+        try {
+          await execFileAsync('git', ['rm', '--cached', '--quiet', '--', filePath], {
+            cwd: dirPath,
+            timeout: 5000,
+          });
+        } catch {
+          // not staged — fall through to the disk-delete
+        }
+        await rm(path.resolve(dirPath, filePath), { force: true, recursive: false });
+      }
+      return { success: true };
+    } catch (error: any) {
+      const stderr: string = (error?.stderr ?? error?.message ?? '').toString().trim();
+      logger.debug('[revertGitFile] failed', { filePath, stderr });
+      return { error: stderr || 'git revert failed', success: false };
+    }
+  }
 }

apps/desktop/src/main/controllers/LocalFileCtr.ts

@@ -12,6 +12,8 @@ import {
   type GrepContentParams,
   type GrepContentResult,
   type ListLocalFileParams,
+  type LocalFilePreviewUrlParams,
+  type LocalFilePreviewUrlResult,
   type LocalMoveFilesResultItem,
   type LocalReadFileParams,
   type LocalReadFileResult,
@@ -370,6 +372,28 @@ export default class LocalFileCtr extends ControllerModule {
     };
   }
 
+  @IpcMethod()
+  async getLocalFilePreviewUrl({
+    path: filePath,
+    workingDirectory,
+  }: LocalFilePreviewUrlParams): Promise<LocalFilePreviewUrlResult> {
+    try {
+      const url = await this.app.localFileProtocolManager.createPreviewUrl({
+        filePath,
+        workspaceRoot: workingDirectory,
+      });
+
+      if (!url) {
+        return { error: 'File is outside the approved workspace', success: false };
+      }
+
+      return { success: true, url };
+    } catch (error) {
+      logger.error('Failed to create local file preview URL:', error);
+      return { error: (error as Error).message, success: false };
+    }
+  }
+
   @IpcMethod()
   async handlePrepareSkillDirectory({
     forceRefresh,
@@ -532,6 +556,7 @@ export default class LocalFileCtr extends ControllerModule {
           requestedScope,
           root,
         });
+        await this.approveProjectRootForPreview(root);
 
         return {
           entries,
@@ -560,6 +585,7 @@ export default class LocalFileCtr extends ControllerModule {
       engine: fallback.engine,
       requestedScope,
     });
+    await this.approveProjectRootForPreview(requestedScope);
 
     return {
       entries,
@@ -641,4 +667,12 @@ export default class LocalFileCtr extends ControllerModule {
     logger.debug(`Editing file ${params.file_path}`, { replace_all: params.replace_all });
     return editLocalFile(params);
   }
+
+  private async approveProjectRootForPreview(root: string) {
+    try {
+      await this.app.localFileProtocolManager.approveIndexedProjectRoot(root);
+    } catch (error) {
+      logger.error(`Failed to approve project preview root ${root}:`, error);
+    }
+  }
 }

apps/desktop/src/main/controllers/OpenInAppCtr.ts

@@ -0,0 +1,43 @@
+import type {
+  DetectAppsResult,
+  OpenInAppParams,
+  OpenInAppResult,
+} from '@lobechat/electron-client-ipc';
+
+import { getCachedDetection } from '@/modules/openInApp/cache';
+import { detectApp } from '@/modules/openInApp/detectors';
+import { launchApp } from '@/modules/openInApp/launchers';
+import { createLogger } from '@/utils/logger';
+
+import { ControllerModule, IpcMethod } from './index';
+
+const logger = createLogger('controllers:OpenInAppCtr');
+
+export default class OpenInAppCtr extends ControllerModule {
+  static override readonly groupName = 'openInApp';
+
+  @IpcMethod()
+  async detectApps(): Promise<DetectAppsResult> {
+    const apps = await getCachedDetection();
+    return { apps };
+  }
+
+  @IpcMethod()
+  async openInApp({ appId, path }: OpenInAppParams): Promise<OpenInAppResult> {
+    // Re-validate installation status before launching: per spec, the main
+    // process must reject if the app disappeared between probe and launch.
+    const installed = await detectApp(appId, process.platform);
+    if (!installed) {
+      logger.warn(`openInApp: ${appId} reported not installed`);
+      return { error: `${appId} is not installed`, success: false };
+    }
+
+    const result = await launchApp(appId, path, process.platform);
+    if (result.success) {
+      logger.info(`openInApp: launched ${appId} with path ${path}`);
+    } else {
+      logger.error(`openInApp: launch failed for ${appId}: ${result.error}`);
+    }
+    return result;
+  }
+}

apps/desktop/src/main/controllers/SystemCtr.ts

@@ -186,6 +186,19 @@ export default class SystemController extends ControllerModule {
     const folderPath = result.filePaths[0];
     const repoType = await detectRepoType(folderPath);
 
+    try {
+      const approvedRoot = await this.app.localFileProtocolManager.approveWorkspaceRoot(folderPath);
+
+      if (approvedRoot) {
+        const storedRoots = this.app.storeManager.get('localFileWorkspaceRoots', []);
+        if (!storedRoots.includes(approvedRoot)) {
+          this.app.storeManager.set('localFileWorkspaceRoots', [approvedRoot, ...storedRoots]);
+        }
+      }
+    } catch (error) {
+      logger.error(`Failed to approve local file workspace root ${folderPath}:`, error);
+    }
+
     return { path: folderPath, repoType };
   }
 

apps/desktop/src/main/controllers/__tests__/LocalFileCtr.test.ts

@@ -84,6 +84,12 @@ const mockContentSearchService = {
   checkToolAvailable: vi.fn(),
 };
 
+const mockLocalFileProtocolManager = {
+  approveIndexedProjectRoot: vi.fn(),
+  approveProjectRootFromScope: vi.fn(),
+  createPreviewUrl: vi.fn(),
+};
+
 // Mock makeSureDirExist
 vi.mock('@/utils/file-system', () => ({
   makeSureDirExist: vi.fn(),
@@ -98,6 +104,7 @@ const mockApp = {
     }
     return mockSearchService;
   }),
+  localFileProtocolManager: mockLocalFileProtocolManager,
   toolDetectorManager: {
     getBestTool: vi.fn(() => null), // No external tools available, use Node.js fallback
   },
@@ -180,6 +187,42 @@ describe('LocalFileCtr', () => {
   // they exercise real fs + file-loaders without fighting the heavy mocks
   // this suite needs for execa-driven tools, electron, and the like.
 
+  describe('getLocalFilePreviewUrl', () => {
+    it('should return a main-issued preview URL for an approved workspace file', async () => {
+      mockLocalFileProtocolManager.createPreviewUrl.mockResolvedValue(
+        'localfile://file/workspace/app.ts?token=abc',
+      );
+
+      const result = await localFileCtr.getLocalFilePreviewUrl({
+        path: '/workspace/app.ts',
+        workingDirectory: '/workspace',
+      });
+
+      expect(mockLocalFileProtocolManager.createPreviewUrl).toHaveBeenCalledWith({
+        filePath: '/workspace/app.ts',
+        workspaceRoot: '/workspace',
+      });
+      expect(result).toEqual({
+        success: true,
+        url: 'localfile://file/workspace/app.ts?token=abc',
+      });
+    });
+
+    it('should reject preview URL creation outside an approved workspace', async () => {
+      mockLocalFileProtocolManager.createPreviewUrl.mockResolvedValue(null);
+
+      const result = await localFileCtr.getLocalFilePreviewUrl({
+        path: '/Users/alice/.ssh/id_rsa',
+        workingDirectory: '/workspace',
+      });
+
+      expect(result).toEqual({
+        error: 'File is outside the approved workspace',
+        success: false,
+      });
+    });
+  });
+
   describe('handleWriteFile', () => {
     it('should write file successfully', async () => {
       vi.mocked(mockFsPromises.mkdir).mockResolvedValue(undefined);

apps/desktop/src/main/controllers/__tests__/OpenInAppCtr.test.ts

@@ -0,0 +1,147 @@
+import type { DetectedApp, OpenInAppResult } from '@lobechat/electron-client-ipc';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { App } from '@/core/App';
+import type { IpcContext } from '@/utils/ipc';
+import { IpcHandler } from '@/utils/ipc/base';
+
+import OpenInAppCtr from '../OpenInAppCtr';
+
+const { getCachedDetectionMock, detectAppMock, launchAppMock, ipcHandlers, ipcMainHandleMock } =
+  vi.hoisted(() => {
+    const handlers = new Map<string, (event: any, ...args: any[]) => any>();
+    const handle = vi.fn((channel: string, handler: any) => {
+      handlers.set(channel, handler);
+    });
+    return {
+      detectAppMock: vi.fn(),
+      getCachedDetectionMock: vi.fn(),
+      ipcHandlers: handlers,
+      ipcMainHandleMock: handle,
+      launchAppMock: vi.fn(),
+    };
+  });
+
+const invokeIpc = async <T = any>(
+  channel: string,
+  payload?: any,
+  context?: Partial<IpcContext>,
+): Promise<T> => {
+  const handler = ipcHandlers.get(channel);
+  if (!handler) throw new Error(`IPC handler for ${channel} not found`);
+
+  const fakeEvent = {
+    sender: context?.sender ?? ({ id: 'test' } as any),
+  };
+
+  if (payload === undefined) {
+    return handler(fakeEvent);
+  }
+
+  return handler(fakeEvent, payload);
+};
+
+vi.mock('@/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  }),
+}));
+
+vi.mock('electron', () => ({
+  ipcMain: {
+    handle: ipcMainHandleMock,
+  },
+}));
+
+vi.mock('@/modules/openInApp/cache', () => ({
+  getCachedDetection: getCachedDetectionMock,
+}));
+
+vi.mock('@/modules/openInApp/detectors', () => ({
+  detectApp: detectAppMock,
+}));
+
+vi.mock('@/modules/openInApp/launchers', () => ({
+  launchApp: launchAppMock,
+}));
+
+const mockApp = {} as unknown as App;
+
+describe('OpenInAppCtr', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    ipcHandlers.clear();
+    ipcMainHandleMock.mockClear();
+    (IpcHandler.getInstance() as any).registeredChannels?.clear();
+    new OpenInAppCtr(mockApp);
+  });
+
+  describe('detectApps', () => {
+    it('should call getCachedDetection and return the apps list', async () => {
+      const apps: DetectedApp[] = [
+        { displayName: 'Visual Studio Code', id: 'vscode', installed: true },
+        { displayName: 'Cursor', id: 'cursor', installed: false },
+      ];
+      getCachedDetectionMock.mockResolvedValue(apps);
+
+      const result = await invokeIpc('openInApp.detectApps');
+
+      expect(getCachedDetectionMock).toHaveBeenCalledTimes(1);
+      expect(result).toEqual({ apps });
+    });
+  });
+
+  describe('openInApp', () => {
+    it('should launch the app when installed', async () => {
+      detectAppMock.mockResolvedValue(true);
+      const launchResult: OpenInAppResult = { success: true };
+      launchAppMock.mockResolvedValue(launchResult);
+
+      const result = await invokeIpc('openInApp.openInApp', {
+        appId: 'vscode',
+        path: '/tmp/project',
+      });
+
+      expect(detectAppMock).toHaveBeenCalledWith('vscode', process.platform);
+      expect(launchAppMock).toHaveBeenCalledWith('vscode', '/tmp/project', process.platform);
+      expect(result).toEqual({ success: true });
+    });
+
+    it('should not launch and return error when app is not installed', async () => {
+      detectAppMock.mockResolvedValue(false);
+
+      const result = await invokeIpc('openInApp.openInApp', {
+        appId: 'cursor',
+        path: '/tmp/project',
+      });
+
+      expect(detectAppMock).toHaveBeenCalledWith('cursor', process.platform);
+      expect(launchAppMock).not.toHaveBeenCalled();
+      expect(result).toEqual({
+        error: 'cursor is not installed',
+        success: false,
+      });
+    });
+
+    it('should pass through launch errors when launchApp fails', async () => {
+      detectAppMock.mockResolvedValue(true);
+      const launchResult: OpenInAppResult = {
+        error: 'Path not found: /tmp/missing',
+        success: false,
+      };
+      launchAppMock.mockResolvedValue(launchResult);
+
+      const result = await invokeIpc('openInApp.openInApp', {
+        appId: 'vscode',
+        path: '/tmp/missing',
+      });
+
+      expect(detectAppMock).toHaveBeenCalledWith('vscode', process.platform);
+      expect(launchAppMock).toHaveBeenCalledWith('vscode', '/tmp/missing', process.platform);
+      expect(result).toEqual(launchResult);
+    });
+  });
+});

apps/desktop/src/main/controllers/registry.ts

@@ -13,6 +13,7 @@ import McpInstallCtr from './McpInstallCtr';
 import MenuController from './MenuCtr';
 import NetworkProxyCtr from './NetworkProxyCtr';
 import NotificationCtr from './NotificationCtr';
+import OpenInAppCtr from './OpenInAppCtr';
 import RemoteServerConfigCtr from './RemoteServerConfigCtr';
 import RemoteServerSyncCtr from './RemoteServerSyncCtr';
 import ScreenCaptureCtr from './ScreenCaptureCtr';
@@ -37,6 +38,7 @@ export const controllerIpcConstructors = [
   MenuController,
   NetworkProxyCtr,
   NotificationCtr,
+  OpenInAppCtr,
   RemoteServerConfigCtr,
   RemoteServerSyncCtr,
   ScreenCaptureCtr,

apps/desktop/src/main/core/App.ts

@@ -31,6 +31,7 @@ import { createLogger } from '@/utils/logger';
 import { BrowserManager } from './browser/BrowserManager';
 import { I18nManager } from './infrastructure/I18nManager';
 import { IoCContainer } from './infrastructure/IoCContainer';
+import { LocalFileProtocolManager } from './infrastructure/LocalFileProtocolManager';
 import { ProtocolManager } from './infrastructure/ProtocolManager';
 import { RendererUrlManager } from './infrastructure/RendererUrlManager';
 import { StaticFileServerManager } from './infrastructure/StaticFileServerManager';
@@ -62,6 +63,7 @@ export class App {
   staticFileServerManager: StaticFileServerManager;
   protocolManager: ProtocolManager;
   rendererUrlManager: RendererUrlManager;
+  localFileProtocolManager: LocalFileProtocolManager;
   toolDetectorManager: ToolDetectorManager;
   screenCaptureManager: ScreenCaptureManager;
   chromeFlags: string[] = ['OverlayScrollbar', 'FluentOverlayScrollbar', 'FluentScrollbar'];
@@ -102,6 +104,10 @@ export class App {
     this.storeManager = new StoreManager(this);
 
     this.rendererUrlManager = new RendererUrlManager();
+    this.localFileProtocolManager = new LocalFileProtocolManager();
+    void this.localFileProtocolManager.approveWorkspaceRoots(
+      this.storeManager.get('localFileWorkspaceRoots', []),
+    );
     protocol.registerSchemesAsPrivileged([
       {
         privileges: {
@@ -114,6 +120,7 @@ export class App {
         scheme: ELECTRON_BE_PROTOCOL_SCHEME,
       },
       this.rendererUrlManager.protocolScheme,
+      this.localFileProtocolManager.protocolScheme,
     ]);
 
     // load controllers
@@ -152,6 +159,10 @@ export class App {
     // should register before app ready
     this.rendererUrlManager.configureRendererLoader();
 
+    // Serves arbitrary local files (e.g. project file previews) via
+    // `localfile://` to the renderer. Active in both dev and prod.
+    this.localFileProtocolManager.registerHandler();
+
     // initialize protocol handlers
     this.protocolManager.initialize();
 

apps/desktop/src/main/core/__tests__/App.test.ts

@@ -115,9 +115,9 @@ vi.mock('../infrastructure/I18nManager', () => ({
 
 vi.mock('../infrastructure/StoreManager', () => ({
   StoreManager: vi.fn().mockImplementation(() => ({
-    get: vi.fn((key) => {
-      if (key === 'storagePath') return '/mock/storage/path';
-      return undefined;
+    get: vi.fn((_key, defaultValue) => {
+      if (_key === 'storagePath') return '/mock/storage/path';
+      return defaultValue;
     }),
     set: vi.fn(),
   })),

apps/desktop/src/main/core/infrastructure/LocalFileProtocolManager.ts

@@ -0,0 +1,327 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, realpath, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+import { app, protocol } from 'electron';
+
+import { LOCAL_FILE_PROTOCOL_HOST, LOCAL_FILE_PROTOCOL_SCHEME } from '@/const/protocol';
+import { createLogger } from '@/utils/logger';
+
+import { getExportMimeType } from '../../utils/mime';
+
+const LOCAL_FILE_PROTOCOL_PRIVILEGES = {
+  allowServiceWorkers: false,
+  bypassCSP: false,
+  corsEnabled: true,
+  secure: true,
+  standard: true,
+  stream: true,
+  supportFetchAPI: true,
+} as const;
+
+const logger = createLogger('core:LocalFileProtocolManager');
+const PREVIEW_TOKEN_TTL_MS = 5 * 60 * 1000;
+
+const EXTRA_MIME_TYPES: Record<string, string> = {
+  '.avif': 'image/avif',
+  '.bmp': 'image/bmp',
+  '.heic': 'image/heic',
+  '.heif': 'image/heif',
+  '.tif': 'image/tiff',
+  '.tiff': 'image/tiff',
+};
+
+const getMimeType = (filePath: string): string => {
+  const ext = path.extname(filePath).toLowerCase();
+  return getExportMimeType(filePath) ?? EXTRA_MIME_TYPES[ext] ?? 'application/octet-stream';
+};
+
+const normalizeAbsolutePath = (filePath: string): string | null => {
+  const normalized = path.normalize(filePath);
+  return path.isAbsolute(normalized) ? normalized : null;
+};
+
+const isPathWithinRoot = (targetPath: string, rootPath: string): boolean => {
+  const relative = path.relative(rootPath, targetPath);
+  return (
+    relative === '' || (!!relative && !relative.startsWith('..') && !path.isAbsolute(relative))
+  );
+};
+
+const buildLocalFileUrl = (absolutePath: string, token: string): string => {
+  const forwardSlashed = absolutePath.replaceAll('\\', '/');
+  const stripped = forwardSlashed.startsWith('/') ? forwardSlashed.slice(1) : forwardSlashed;
+  const encoded = stripped.split('/').map(encodeURIComponent).join('/');
+  const url = new URL(`${LOCAL_FILE_PROTOCOL_SCHEME}://${LOCAL_FILE_PROTOCOL_HOST}/${encoded}`);
+  url.searchParams.set('token', token);
+  return url.toString();
+};
+
+interface PreviewTokenRecord {
+  expiresAt: number;
+  realPath: string;
+}
+
+/**
+ * Custom `localfile://` protocol for project file previews.
+ *
+ * URL shape: `localfile://file/<percent-encoded-absolute-path>?token=<main-issued-token>`
+ *   - host is fixed to `file` so the scheme behaves as `standard`
+ *   - the absolute path is encoded in the URL pathname
+ *   - every request must carry a short-lived token minted by the main process
+ *
+ * Examples:
+ *   localfile://file//Users/alice/project/cat.png?token=...
+ *   localfile://file/C:/Users/alice/project/cat.png?token=...
+ */
+export class LocalFileProtocolManager {
+  private readonly approvedWorkspaceRoots = new Set<string>();
+
+  private readonly indexedProjectRoots = new Set<string>();
+
+  private handlerRegistered = false;
+
+  private readonly previewTokens = new Map<string, PreviewTokenRecord>();
+
+  get protocolScheme() {
+    return {
+      privileges: LOCAL_FILE_PROTOCOL_PRIVILEGES,
+      scheme: LOCAL_FILE_PROTOCOL_SCHEME,
+    };
+  }
+
+  registerHandler() {
+    if (this.handlerRegistered) return;
+
+    const register = () => {
+      if (this.handlerRegistered) return;
+
+      protocol.handle(LOCAL_FILE_PROTOCOL_SCHEME, async (request) => {
+        try {
+          const url = new URL(request.url);
+
+          if (url.hostname !== LOCAL_FILE_PROTOCOL_HOST) {
+            return new Response('Not Found', { status: 404 });
+          }
+
+          const resolvedPath = this.resolveFilePath(url.pathname);
+          if (!resolvedPath) {
+            return new Response('Invalid path', { status: 400 });
+          }
+
+          const token = url.searchParams.get('token');
+          if (!token) {
+            return new Response('Forbidden', { status: 403 });
+          }
+
+          if (!this.hasPreviewToken(token)) {
+            return new Response('Forbidden', { status: 403 });
+          }
+
+          const realResolvedPath = normalizeAbsolutePath(await realpath(resolvedPath));
+          if (!realResolvedPath || !this.verifyPreviewToken(token, realResolvedPath)) {
+            return new Response('Forbidden', { status: 403 });
+          }
+
+          const fileStat = await stat(realResolvedPath);
+          if (!fileStat.isFile()) {
+            return new Response('Not a file', { status: 404 });
+          }
+
+          const buffer = await readFile(realResolvedPath);
+          const headers = new Headers();
+          headers.set('Content-Type', getMimeType(realResolvedPath));
+          headers.set('Content-Length', String(buffer.byteLength));
+          // Local files are immutable from the renderer's perspective for a
+          // single preview session; allow short-lived caching to avoid
+          // re-reading large images during scrolling/refresh.
+          headers.set('Cache-Control', 'private, max-age=60');
+
+          return new Response(buffer, { headers, status: 200 });
+        } catch (error) {
+          const code = (error as NodeJS.ErrnoException).code;
+          if (code === 'ENOENT' || code === 'ENOTDIR') {
+            return new Response('Not Found', { status: 404 });
+          }
+          if (code === 'EACCES' || code === 'EPERM') {
+            return new Response('Forbidden', { status: 403 });
+          }
+          logger.error(`Failed to serve localfile request ${request.url}:`, error);
+          return new Response('Internal Server Error', { status: 500 });
+        }
+      });
+
+      this.handlerRegistered = true;
+      logger.debug(`Registered ${LOCAL_FILE_PROTOCOL_SCHEME}:// handler`);
+    };
+
+    if (app.isReady()) {
+      register();
+    } else {
+      app.whenReady().then(register);
+    }
+  }
+
+  async approveWorkspaceRoot(rootPath: string): Promise<string | null> {
+    const normalizedRoot = normalizeAbsolutePath(rootPath);
+    if (!normalizedRoot) return null;
+
+    const realRoot = normalizeAbsolutePath(await realpath(normalizedRoot));
+    if (!realRoot) return null;
+
+    this.approvedWorkspaceRoots.add(realRoot);
+    return realRoot;
+  }
+
+  async approveWorkspaceRoots(rootPaths: string[] = []): Promise<string[]> {
+    const approvedRoots = await Promise.allSettled(
+      rootPaths.map((rootPath) => this.approveWorkspaceRoot(rootPath)),
+    );
+
+    return approvedRoots
+      .map((result) => (result.status === 'fulfilled' ? result.value : null))
+      .filter((rootPath): rootPath is string => !!rootPath);
+  }
+
+  async approveProjectRootFromScope({
+    projectRoot,
+    requestedScope,
+  }: {
+    projectRoot: string;
+    requestedScope: string;
+  }): Promise<string | null> {
+    const [realProjectRoot, realRequestedScope] = await Promise.all([
+      realpath(projectRoot),
+      realpath(requestedScope),
+    ]);
+    const normalizedProjectRoot = normalizeAbsolutePath(realProjectRoot);
+    const normalizedRequestedScope = normalizeAbsolutePath(realRequestedScope);
+    if (!normalizedProjectRoot || !normalizedRequestedScope) return null;
+
+    const scopeIsApproved = [...this.approvedWorkspaceRoots].some(
+      (approvedRoot) =>
+        normalizedRequestedScope === approvedRoot ||
+        isPathWithinRoot(normalizedRequestedScope, approvedRoot),
+    );
+    if (!scopeIsApproved) return null;
+
+    this.approvedWorkspaceRoots.add(normalizedProjectRoot);
+    return normalizedProjectRoot;
+  }
+
+  async approveIndexedProjectRoot(projectRoot: string): Promise<string | null> {
+    const normalizedProjectRoot = normalizeAbsolutePath(projectRoot);
+    if (!normalizedProjectRoot) return null;
+
+    const realProjectRoot = normalizeAbsolutePath(await realpath(normalizedProjectRoot));
+    if (!realProjectRoot) return null;
+
+    this.indexedProjectRoots.add(realProjectRoot);
+    return realProjectRoot;
+  }
+
+  async createPreviewUrl({
+    filePath,
+    workspaceRoot,
+  }: {
+    filePath: string;
+    workspaceRoot: string;
+  }): Promise<string | null> {
+    const normalizedFilePath = normalizeAbsolutePath(filePath);
+    const normalizedWorkspaceRoot = normalizeAbsolutePath(workspaceRoot);
+    if (!normalizedFilePath || !normalizedWorkspaceRoot) return null;
+
+    const [realFilePath, realWorkspaceRoot] = await Promise.all([
+      realpath(normalizedFilePath),
+      realpath(normalizedWorkspaceRoot),
+    ]);
+    const normalizedRealFilePath = normalizeAbsolutePath(realFilePath);
+    const normalizedRealWorkspaceRoot = normalizeAbsolutePath(realWorkspaceRoot);
+
+    if (!normalizedRealFilePath || !normalizedRealWorkspaceRoot) return null;
+    if (
+      !this.approvedWorkspaceRoots.has(normalizedRealWorkspaceRoot) &&
+      !this.indexedProjectRoots.has(normalizedRealWorkspaceRoot)
+    ) {
+      return null;
+    }
+    if (!isPathWithinRoot(normalizedRealFilePath, normalizedRealWorkspaceRoot)) return null;
+
+    this.cleanupExpiredTokens();
+
+    const token = randomUUID();
+    this.previewTokens.set(token, {
+      expiresAt: Date.now() + PREVIEW_TOKEN_TTL_MS,
+      realPath: normalizedRealFilePath,
+    });
+
+    return buildLocalFileUrl(normalizedFilePath, token);
+  }
+
+  /**
+   * Decode the URL pathname back into an absolute filesystem path.
+   *
+   * Pathname examples produced by `new URL('localfile://file//abs/path')`:
+   *   posix:    `//abs/path`           -> `/abs/path`
+   *   windows:  `/C:/abs/path`         -> `C:/abs/path`
+   *
+   * Returns null when the path is non-absolute or escapes via segments we
+   * cannot safely normalize (defense-in-depth, not a sandbox).
+   */
+  private resolveFilePath(pathname: string): string | null {
+    let decoded: string;
+    try {
+      decoded = decodeURIComponent(pathname);
+    } catch {
+      return null;
+    }
+
+    // Strip the single leading slash inserted by URL parsing on standard
+    // schemes; what remains should already be an absolute filesystem path.
+    let candidate = decoded.startsWith('/') ? decoded.slice(1) : decoded;
+    if (!candidate) return null;
+
+    if (process.platform === 'win32') {
+      // posix-style absolute path won't have a drive letter; treat as invalid
+      // on Windows.
+      candidate = candidate.replaceAll('/', '\\');
+    } else if (!candidate.startsWith('/')) {
+      // We expect an absolute POSIX path: `localfile://file//abs/path` yields
+      // pathname `//abs/path` -> after stripping one slash -> `/abs/path`.
+      candidate = `/${candidate}`;
+    }
+
+    const normalized = path.normalize(candidate);
+    if (!path.isAbsolute(normalized)) return null;
+
+    return normalized;
+  }
+
+  private cleanupExpiredTokens() {
+    const now = Date.now();
+    for (const [token, record] of this.previewTokens) {
+      if (record.expiresAt <= now) {
+        this.previewTokens.delete(token);
+      }
+    }
+  }
+
+  private hasPreviewToken(token: string): boolean {
+    const record = this.previewTokens.get(token);
+    if (!record) return false;
+
+    if (record.expiresAt <= Date.now()) {
+      this.previewTokens.delete(token);
+      return false;
+    }
+
+    return true;
+  }
+
+  private verifyPreviewToken(token: string, realResolvedPath: string): boolean {
+    const record = this.previewTokens.get(token);
+    if (!record) return false;
+
+    return record.realPath === realResolvedPath;
+  }
+}

apps/desktop/src/main/core/infrastructure/__tests__/LocalFileProtocolManager.test.ts

@@ -0,0 +1,298 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { LocalFileProtocolManager } from '../LocalFileProtocolManager';
+
+const { mockApp, mockProtocol, mockReadFile, mockRealpath, mockStat, protocolHandlerRef } =
+  vi.hoisted(() => {
+    const protocolHandlerRef = { current: null as any };
+
+    return {
+      mockApp: {
+        isReady: vi.fn().mockReturnValue(true),
+        whenReady: vi.fn().mockResolvedValue(undefined),
+      },
+      mockProtocol: {
+        handle: vi.fn((_scheme: string, handler: any) => {
+          protocolHandlerRef.current = handler;
+        }),
+      },
+      mockReadFile: vi.fn(),
+      mockRealpath: vi.fn(),
+      mockStat: vi.fn(),
+      protocolHandlerRef,
+    };
+  });
+
+vi.mock('electron', () => ({
+  app: mockApp,
+  protocol: mockProtocol,
+}));
+
+vi.mock('node:fs/promises', () => ({
+  realpath: mockRealpath,
+  readFile: mockReadFile,
+  stat: mockStat,
+}));
+
+vi.mock('@/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  }),
+}));
+
+describe('LocalFileProtocolManager', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    protocolHandlerRef.current = null;
+    mockApp.isReady.mockReturnValue(true);
+    mockRealpath.mockImplementation(async (filePath: string) => filePath);
+    mockStat.mockImplementation(async () => ({ isFile: () => true, size: 1024 }));
+    mockReadFile.mockImplementation(async () => Buffer.from('image-bytes'));
+  });
+
+  afterEach(() => {
+    protocolHandlerRef.current = null;
+  });
+
+  it('exposes scheme metadata for registerSchemesAsPrivileged', () => {
+    const manager = new LocalFileProtocolManager();
+    expect(manager.protocolScheme).toEqual({
+      privileges: expect.objectContaining({
+        bypassCSP: false,
+        secure: true,
+        standard: true,
+        supportFetchAPI: true,
+      }),
+      scheme: 'localfile',
+    });
+  });
+
+  it('serves a POSIX absolute path with the correct mime type', async () => {
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+    await manager.approveWorkspaceRoot('/Users/alice');
+    const url = await manager.createPreviewUrl({
+      filePath: '/Users/alice/Pictures/cat.png',
+      workspaceRoot: '/Users/alice',
+    });
+    if (!url) throw new Error('Expected local file preview URL');
+
+    expect(mockProtocol.handle).toHaveBeenCalledWith('localfile', expect.any(Function));
+    const handler = protocolHandlerRef.current;
+
+    const response = await handler({
+      headers: new Headers(),
+      method: 'GET',
+      url,
+    });
+
+    expect(mockStat).toHaveBeenCalledWith('/Users/alice/Pictures/cat.png');
+    expect(mockReadFile).toHaveBeenCalledWith('/Users/alice/Pictures/cat.png');
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toBe('image/png');
+    expect(response.headers.get('Content-Length')).toBe('11'); // 'image-bytes'.length
+  });
+
+  it('serves source files as text through the localfile protocol', async () => {
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+    await manager.approveWorkspaceRoot('/Users/alice/project');
+    const url = await manager.createPreviewUrl({
+      filePath: '/Users/alice/project/App.tsx',
+      workspaceRoot: '/Users/alice/project',
+    });
+    if (!url) throw new Error('Expected local file preview URL');
+    const handler = protocolHandlerRef.current;
+
+    const response = await handler({
+      headers: new Headers(),
+      method: 'GET',
+      url,
+    });
+
+    expect(mockStat).toHaveBeenCalledWith('/Users/alice/project/App.tsx');
+    expect(mockReadFile).toHaveBeenCalledWith('/Users/alice/project/App.tsx');
+    expect(response.status).toBe(200);
+    expect(response.headers.get('Content-Type')).toBe('text/plain; charset=utf-8');
+  });
+
+  it('decodes percent-encoded characters in the path', async () => {
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+    await manager.approveWorkspaceRoot('/Users/alice');
+    const url = await manager.createPreviewUrl({
+      filePath: '/Users/alice/My Pictures/图 #.png',
+      workspaceRoot: '/Users/alice',
+    });
+    if (!url) throw new Error('Expected local file preview URL');
+    const handler = protocolHandlerRef.current;
+
+    await handler({
+      headers: new Headers(),
+      method: 'GET',
+      url,
+    });
+
+    expect(mockStat).toHaveBeenCalledWith('/Users/alice/My Pictures/图 #.png');
+  });
+
+  it('rejects requests to a different host', async () => {
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+    const handler = protocolHandlerRef.current;
+
+    const response = await handler({
+      headers: new Headers(),
+      method: 'GET',
+      url: 'localfile://other/Users/alice/cat.png',
+    });
+
+    expect(response.status).toBe(404);
+    expect(mockStat).not.toHaveBeenCalled();
+  });
+
+  it('returns 404 when the path is a directory', async () => {
+    mockStat.mockImplementation(async () => ({ isFile: () => false, size: 0 }));
+
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+    await manager.approveWorkspaceRoot('/Users/alice');
+    const url = await manager.createPreviewUrl({
+      filePath: '/Users/alice/folder',
+      workspaceRoot: '/Users/alice',
+    });
+    if (!url) throw new Error('Expected local file preview URL');
+    const handler = protocolHandlerRef.current;
+
+    const response = await handler({
+      headers: new Headers(),
+      method: 'GET',
+      url,
+    });
+
+    expect(response.status).toBe(404);
+    expect(mockReadFile).not.toHaveBeenCalled();
+  });
+
+  it('maps ENOENT errors to a 404 response', async () => {
+    mockStat.mockImplementation(async () => {
+      const err: NodeJS.ErrnoException = new Error('no such file');
+      err.code = 'ENOENT';
+      throw err;
+    });
+
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+    await manager.approveWorkspaceRoot('/');
+    const handler = protocolHandlerRef.current;
+    const url = await manager.createPreviewUrl({
+      filePath: '/nonexistent.png',
+      workspaceRoot: '/',
+    });
+    if (!url) throw new Error('Expected local file preview URL');
+
+    const response = await handler({
+      headers: new Headers(),
+      method: 'GET',
+      url,
+    });
+
+    expect(response.status).toBe(404);
+  });
+
+  it('rejects direct localfile requests without a main-issued preview token', async () => {
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+    const handler = protocolHandlerRef.current;
+
+    const response = await handler({
+      headers: new Headers(),
+      method: 'GET',
+      url: 'localfile://file/Users/alice/.ssh/id_rsa',
+    });
+
+    expect(response.status).toBe(403);
+    expect(mockStat).not.toHaveBeenCalled();
+    expect(mockReadFile).not.toHaveBeenCalled();
+  });
+
+  it('rejects forged preview tokens before resolving the requested path', async () => {
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+    const handler = protocolHandlerRef.current;
+
+    const response = await handler({
+      headers: new Headers(),
+      method: 'GET',
+      url: 'localfile://file/Users/alice/.ssh/id_rsa?token=forged',
+    });
+
+    expect(response.status).toBe(403);
+    expect(mockRealpath).not.toHaveBeenCalled();
+    expect(mockStat).not.toHaveBeenCalled();
+    expect(mockReadFile).not.toHaveBeenCalled();
+  });
+
+  it('does not mint preview URLs outside an approved workspace root', async () => {
+    const manager = new LocalFileProtocolManager();
+    await manager.approveWorkspaceRoot('/Users/alice/project');
+
+    const url = await manager.createPreviewUrl({
+      filePath: '/Users/alice/.ssh/id_rsa',
+      workspaceRoot: '/Users/alice/project',
+    });
+
+    expect(url).toBeNull();
+  });
+
+  it('can approve a project root derived from an already approved nested scope', async () => {
+    const manager = new LocalFileProtocolManager();
+    await manager.approveWorkspaceRoot('/Users/alice/project/packages/app');
+    await manager.approveProjectRootFromScope({
+      projectRoot: '/Users/alice/project',
+      requestedScope: '/Users/alice/project/packages/app',
+    });
+
+    const url = await manager.createPreviewUrl({
+      filePath: '/Users/alice/project/root.ts',
+      workspaceRoot: '/Users/alice/project',
+    });
+    if (!url) throw new Error('Expected local file preview URL');
+
+    expect(url).toContain('token=');
+  });
+
+  it('can mint preview URLs for roots produced by the main-process project index', async () => {
+    const manager = new LocalFileProtocolManager();
+    await manager.approveIndexedProjectRoot('/Users/alice/project');
+
+    const url = await manager.createPreviewUrl({
+      filePath: '/Users/alice/project/App.tsx',
+      workspaceRoot: '/Users/alice/project',
+    });
+    if (!url) throw new Error('Expected local file preview URL');
+
+    expect(url).toContain('token=');
+  });
+
+  it('defers registration until app ready when not yet ready', async () => {
+    mockApp.isReady.mockReturnValue(false);
+    let resolveReady: () => void = () => undefined;
+    mockApp.whenReady.mockReturnValue(
+      new Promise<void>((resolve) => {
+        resolveReady = resolve;
+      }),
+    );
+
+    const manager = new LocalFileProtocolManager();
+    manager.registerHandler();
+
+    expect(mockProtocol.handle).not.toHaveBeenCalled();
+    resolveReady();
+    await new Promise((r) => setImmediate(r));
+    expect(mockProtocol.handle).toHaveBeenCalled();
+  });
+});

apps/desktop/src/main/modules/openInApp/__tests__/cache.test.ts

@@ -0,0 +1,87 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { clearDetectionCache, getCachedDetection } from '../cache';
+import { detectAllApps } from '../detectors';
+
+vi.mock('@/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  }),
+}));
+
+vi.mock('../detectors', () => ({
+  detectAllApps: vi.fn(),
+}));
+
+const mockedDetectAll = vi.mocked(detectAllApps);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  clearDetectionCache();
+});
+
+describe('getCachedDetection', () => {
+  it('invokes detection on first call', async () => {
+    mockedDetectAll.mockResolvedValueOnce([
+      { displayName: 'VS Code', id: 'vscode', installed: true },
+    ]);
+
+    const result = await getCachedDetection('darwin');
+
+    expect(result).toEqual([{ displayName: 'VS Code', id: 'vscode', installed: true }]);
+    expect(mockedDetectAll).toHaveBeenCalledTimes(1);
+  });
+
+  it('concurrent callers share a single inflight promise', async () => {
+    let resolveFn: (value: any) => void = () => {};
+    const inflight = new Promise<any>((resolve) => {
+      resolveFn = resolve;
+    });
+    mockedDetectAll.mockReturnValueOnce(inflight);
+
+    const p1 = getCachedDetection('darwin');
+    const p2 = getCachedDetection('darwin');
+    const p3 = getCachedDetection('darwin');
+
+    expect(mockedDetectAll).toHaveBeenCalledTimes(1);
+
+    resolveFn([{ displayName: 'VS Code', id: 'vscode', installed: true }]);
+    const results = await Promise.all([p1, p2, p3]);
+
+    // all three share the same resolved value
+    expect(results[0]).toBe(results[1]);
+    expect(results[1]).toBe(results[2]);
+    expect(mockedDetectAll).toHaveBeenCalledTimes(1);
+  });
+
+  it('subsequent serial calls reuse the cached promise', async () => {
+    mockedDetectAll.mockResolvedValueOnce([
+      { displayName: 'VS Code', id: 'vscode', installed: true },
+    ]);
+
+    await getCachedDetection('darwin');
+    await getCachedDetection('darwin');
+    await getCachedDetection('darwin');
+
+    expect(mockedDetectAll).toHaveBeenCalledTimes(1);
+  });
+
+  it('re-invokes detection after clearDetectionCache', async () => {
+    mockedDetectAll.mockResolvedValueOnce([
+      { displayName: 'VS Code', id: 'vscode', installed: true },
+    ]);
+    await getCachedDetection('darwin');
+    expect(mockedDetectAll).toHaveBeenCalledTimes(1);
+
+    clearDetectionCache();
+    mockedDetectAll.mockResolvedValueOnce([
+      { displayName: 'VS Code', id: 'vscode', installed: false },
+    ]);
+    await getCachedDetection('darwin');
+
+    expect(mockedDetectAll).toHaveBeenCalledTimes(2);
+  });
+});

apps/desktop/src/main/modules/openInApp/__tests__/detectors.test.ts

@@ -0,0 +1,274 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { detectAllApps, detectApp } from '../detectors';
+import { extractAllIcons } from '../iconExtractor';
+
+// Mock logger
+vi.mock('@/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  }),
+}));
+
+// Mock node:fs/promises
+vi.mock('node:fs/promises', () => ({
+  access: vi.fn(),
+}));
+
+// Mock node:child_process - execFile is wrapped via promisify, so the mock must
+// expose execFile as the underlying callback-style function we can drive.
+vi.mock('node:child_process', () => ({
+  execFile: vi.fn(),
+}));
+
+// Mock the icon extractor — detection tests should not depend on real icon
+// extraction. The default returns an empty Map (no icons) which leaves the
+// `icon` field absent from all detection results.
+vi.mock('../iconExtractor', () => ({
+  extractAllIcons: vi.fn(async () => new Map<string, string>()),
+}));
+
+const mockedAccess = vi.mocked(access);
+const mockedExecFile = vi.mocked(execFile) as unknown as ReturnType<typeof vi.fn>;
+
+interface ExecOutcome {
+  code: number;
+  error?: NodeJS.ErrnoException;
+  stderr?: string;
+  stdout?: string;
+}
+
+const respondExec = (outcome: ExecOutcome) => {
+  mockedExecFile.mockImplementationOnce(
+    (_file: string, _args: string[], _opts: unknown, cb: any) => {
+      const callback = typeof _opts === 'function' ? _opts : cb;
+      if (outcome.code === 0) {
+        callback(null, outcome.stdout ?? '', outcome.stderr ?? '');
+      } else {
+        const err: NodeJS.ErrnoException & { stderr?: string } =
+          outcome.error ?? new Error('exec failed');
+        err.stderr = outcome.stderr ?? '';
+        (err as any).code = outcome.code;
+        callback(err, '', outcome.stderr ?? '');
+      }
+      return undefined as any;
+    },
+  );
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe('detectApp', () => {
+  describe('appBundle strategy', () => {
+    it('returns true when fs.access resolves for any path', async () => {
+      mockedAccess.mockRejectedValueOnce(new Error('missing'));
+      mockedAccess.mockResolvedValueOnce(undefined);
+
+      const result = await detectApp('terminal', 'darwin');
+
+      expect(result).toBe(true);
+      expect(mockedAccess).toHaveBeenCalledTimes(2);
+    });
+
+    it('returns false when all paths reject', async () => {
+      mockedAccess.mockRejectedValue(new Error('missing'));
+
+      const result = await detectApp('vscode', 'darwin');
+
+      expect(result).toBe(false);
+    });
+  });
+
+  describe('commandV strategy', () => {
+    it('returns true on exit 0', async () => {
+      respondExec({ code: 0, stdout: '/usr/bin/zed' });
+
+      const result = await detectApp('zed', 'linux');
+
+      expect(result).toBe(true);
+      expect(mockedExecFile).toHaveBeenCalledWith(
+        '/bin/sh',
+        ['-c', 'command -v "zed"'],
+        expect.any(Function),
+      );
+    });
+
+    it('returns false on non-zero exit', async () => {
+      respondExec({ code: 1, stderr: 'not found' });
+
+      const result = await detectApp('zed', 'linux');
+
+      expect(result).toBe(false);
+    });
+
+    it('rejects unsafe binary names without spawning a shell', async () => {
+      // We monkey-patch a registry entry transiently to inject a malicious binary.
+      const registry = await import('../registry');
+      const originalGhostty = registry.APP_REGISTRY.ghostty.detect.linux;
+      registry.APP_REGISTRY.ghostty.detect.linux = {
+        binary: 'foo; rm -rf /',
+        type: 'commandV',
+      };
+
+      const result = await detectApp('ghostty', 'linux');
+
+      expect(result).toBe(false);
+      expect(mockedExecFile).not.toHaveBeenCalled();
+
+      registry.APP_REGISTRY.ghostty.detect.linux = originalGhostty;
+    });
+  });
+
+  describe('registryAppPaths strategy', () => {
+    it('returns true on exit 0', async () => {
+      respondExec({ code: 0, stdout: 'C:\\Program Files\\code.exe' });
+
+      const result = await detectApp('vscode', 'win32');
+
+      expect(result).toBe(true);
+      expect(mockedExecFile).toHaveBeenCalledWith(
+        'where',
+        ['Code.exe'],
+        { windowsHide: true },
+        expect.any(Function),
+      );
+    });
+
+    it('returns false on non-zero exit', async () => {
+      respondExec({ code: 1, stderr: 'not found' });
+
+      const result = await detectApp('vscode', 'win32');
+
+      expect(result).toBe(false);
+    });
+  });
+
+  it('returns false when platform has no detect entry for the app', async () => {
+    const result = await detectApp('xcode', 'linux');
+
+    expect(result).toBe(false);
+    expect(mockedAccess).not.toHaveBeenCalled();
+    expect(mockedExecFile).not.toHaveBeenCalled();
+  });
+
+  it('returns true for ALWAYS_INSTALLED entries without probing', async () => {
+    const darwinFinder = await detectApp('finder', 'darwin');
+    const win32Explorer = await detectApp('explorer', 'win32');
+    const linuxFiles = await detectApp('files', 'linux');
+
+    expect(darwinFinder).toBe(true);
+    expect(win32Explorer).toBe(true);
+    expect(linuxFiles).toBe(true);
+    expect(mockedAccess).not.toHaveBeenCalled();
+    expect(mockedExecFile).not.toHaveBeenCalled();
+  });
+});
+
+describe('detectAllApps', () => {
+  it('returns one entry per AppId regardless of platform', async () => {
+    mockedAccess.mockRejectedValue(new Error('missing'));
+    mockedExecFile.mockImplementation((_file: string, _args: string[], _opts: unknown, cb: any) => {
+      const callback = typeof _opts === 'function' ? _opts : cb;
+      const err: NodeJS.ErrnoException = new Error('fail');
+      callback(err, '', '');
+      return undefined as any;
+    });
+
+    const apps = await detectAllApps('linux');
+
+    const registry = await import('../registry');
+    expect(apps.length).toBe(Object.keys(registry.APP_REGISTRY).length);
+    // every entry has the three required fields
+    for (const app of apps) {
+      expect(app).toEqual(
+        expect.objectContaining({
+          displayName: expect.any(String),
+          id: expect.any(String),
+          installed: expect.any(Boolean),
+        }),
+      );
+    }
+  });
+
+  it('marks unsupported-on-platform apps as not installed', async () => {
+    mockedAccess.mockRejectedValue(new Error('missing'));
+    mockedExecFile.mockImplementation((_file: string, _args: string[], _opts: unknown, cb: any) => {
+      const callback = typeof _opts === 'function' ? _opts : cb;
+      const err: NodeJS.ErrnoException = new Error('fail');
+      callback(err, '', '');
+      return undefined as any;
+    });
+
+    const apps = await detectAllApps('linux');
+
+    const xcode = apps.find((a) => a.id === 'xcode');
+    expect(xcode?.installed).toBe(false);
+  });
+
+  it('marks ALWAYS_INSTALLED platform file manager as installed without probes', async () => {
+    mockedAccess.mockRejectedValue(new Error('missing'));
+    mockedExecFile.mockImplementation((_file: string, _args: string[], _opts: unknown, cb: any) => {
+      const callback = typeof _opts === 'function' ? _opts : cb;
+      const err: NodeJS.ErrnoException = new Error('fail');
+      callback(err, '', '');
+      return undefined as any;
+    });
+
+    const apps = await detectAllApps('darwin');
+
+    const finder = apps.find((a) => a.id === 'finder');
+    expect(finder?.installed).toBe(true);
+  });
+
+  it('merges extracted icons onto installed apps only', async () => {
+    mockedAccess.mockRejectedValue(new Error('missing'));
+    mockedExecFile.mockImplementation((_file: string, _args: string[], _opts: unknown, cb: any) => {
+      const callback = typeof _opts === 'function' ? _opts : cb;
+      const err: NodeJS.ErrnoException = new Error('fail');
+      callback(err, '', '');
+      return undefined as any;
+    });
+
+    vi.mocked(extractAllIcons).mockResolvedValueOnce(
+      new Map([['finder', 'data:image/png;base64,FAKE']]),
+    );
+
+    const apps = await detectAllApps('darwin');
+
+    const finder = apps.find((a) => a.id === 'finder');
+    expect(finder?.icon).toBe('data:image/png;base64,FAKE');
+
+    // not-installed apps must not have an icon field
+    const xcode = apps.find((a) => a.id === 'xcode');
+    expect(xcode?.installed).toBe(false);
+    expect(xcode?.icon).toBeUndefined();
+  });
+
+  it('passes only installed AppIds to extractAllIcons', async () => {
+    mockedAccess.mockRejectedValue(new Error('missing'));
+    mockedExecFile.mockImplementation((_file: string, _args: string[], _opts: unknown, cb: any) => {
+      const callback = typeof _opts === 'function' ? _opts : cb;
+      const err: NodeJS.ErrnoException = new Error('fail');
+      callback(err, '', '');
+      return undefined as any;
+    });
+
+    vi.mocked(extractAllIcons).mockResolvedValueOnce(new Map());
+
+    await detectAllApps('darwin');
+
+    expect(extractAllIcons).toHaveBeenCalledTimes(1);
+    const [ids, platform] = vi.mocked(extractAllIcons).mock.calls[0];
+    expect(platform).toBe('darwin');
+    // only finder is ALWAYS_INSTALLED on darwin; all others fail probes
+    expect(ids).toEqual(['finder']);
+  });
+});

apps/desktop/src/main/modules/openInApp/__tests__/iconExtractor.test.ts

@@ -0,0 +1,261 @@
+import { execFile } from 'node:child_process';
+import { access, mkdtemp, readFile, unlink } from 'node:fs/promises';
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { __resetForTest, extractAllIcons, extractAppIcon } from '../iconExtractor';
+
+vi.mock('@/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  }),
+}));
+
+vi.mock('node:fs/promises', () => ({
+  access: vi.fn(),
+  mkdtemp: vi.fn(),
+  readFile: vi.fn(),
+  unlink: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execFile: vi.fn(),
+}));
+
+const mockedAccess = vi.mocked(access);
+const mockedMkdtemp = vi.mocked(mkdtemp);
+const mockedReadFile = vi.mocked(readFile);
+const mockedUnlink = vi.mocked(unlink);
+const mockedExecFile = vi.mocked(execFile) as unknown as ReturnType<typeof vi.fn>;
+
+/**
+ * Drives the next execFile call. The promisified callback signature is
+ * `(error, stdout, stderr)`; non-error responses resolve with stdout.
+ */
+const respondExec = (
+  match: { args?: string[]; binary: string },
+  outcome: { error?: Error; stderr?: string; stdout?: string },
+) => {
+  mockedExecFile.mockImplementationOnce(
+    (_file: string, _args: string[], _opts: unknown, cb: any) => {
+      const callback = typeof _opts === 'function' ? _opts : cb;
+      if (_file !== match.binary) {
+        callback(new Error(`unexpected binary: ${_file}`), '', '');
+        return undefined as any;
+      }
+      if (match.args && JSON.stringify(_args) !== JSON.stringify(match.args)) {
+        callback(new Error(`unexpected args: ${JSON.stringify(_args)}`), '', '');
+        return undefined as any;
+      }
+      if (outcome.error) {
+        callback(outcome.error, '', outcome.stderr ?? '');
+      } else {
+        callback(null, outcome.stdout ?? '', outcome.stderr ?? '');
+      }
+      return undefined as any;
+    },
+  );
+};
+
+// Shorthand: tools-available probe passes (which plutil + which sips both 0).
+const respondToolsAvailable = () => {
+  // /usr/bin/which plutil
+  respondExec({ binary: '/usr/bin/which' }, { stdout: '/usr/bin/plutil\n' });
+  // /usr/bin/which sips
+  respondExec({ binary: '/usr/bin/which' }, { stdout: '/usr/bin/sips\n' });
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockedAccess.mockReset();
+  mockedMkdtemp.mockReset();
+  mockedReadFile.mockReset();
+  mockedUnlink.mockReset();
+  mockedExecFile.mockReset();
+  mockedUnlink.mockResolvedValue(undefined);
+  __resetForTest();
+});
+
+describe('extractAppIcon', () => {
+  it('returns a data URL when plutil + sips succeed on darwin', async () => {
+    respondToolsAvailable();
+    mockedAccess.mockResolvedValueOnce(undefined); // bundle exists
+    // plutil CFBundleIconFile lookup
+    respondExec({ binary: 'plutil' }, { stdout: 'Code.icns\n' });
+    mockedAccess.mockResolvedValueOnce(undefined); // .icns exists
+    mockedMkdtemp.mockResolvedValueOnce('/tmp/lobehub-openinapp-test');
+    // sips conversion
+    respondExec({ binary: 'sips' }, { stdout: '' });
+    mockedReadFile.mockResolvedValueOnce(Buffer.from([0x89, 0x50, 0x4e, 0x47])); // PNG header
+
+    const result = await extractAppIcon('vscode', 'darwin');
+
+    expect(result).toBe(
+      `data:image/png;base64,${Buffer.from([0x89, 0x50, 0x4e, 0x47]).toString('base64')}`,
+    );
+  });
+
+  it('appends .icns suffix when CFBundleIconFile has no extension', async () => {
+    respondToolsAvailable();
+    mockedAccess.mockResolvedValueOnce(undefined); // bundle exists
+    respondExec({ binary: 'plutil' }, { stdout: 'Terminal\n' });
+    mockedAccess.mockImplementationOnce(async (p: any) => {
+      // .icns existence check — verify suffix appended
+      if (typeof p === 'string' && p.endsWith('Terminal.icns')) return undefined;
+      throw new Error('wrong path: ' + String(p));
+    });
+    mockedMkdtemp.mockResolvedValueOnce('/tmp/lobehub-openinapp-test');
+    respondExec({ binary: 'sips' }, { stdout: '' });
+    mockedReadFile.mockResolvedValueOnce(Buffer.from([0x89, 0x50]));
+
+    const result = await extractAppIcon('terminal', 'darwin');
+
+    expect(result).toBeDefined();
+    expect(result!.startsWith('data:image/png;base64,')).toBe(true);
+  });
+
+  it('falls back to the next path when the first bundle does not exist', async () => {
+    respondToolsAvailable();
+    // terminal has two candidate paths; first fails, second succeeds.
+    mockedAccess.mockRejectedValueOnce(new Error('missing'));
+    mockedAccess.mockResolvedValueOnce(undefined);
+    respondExec({ binary: 'plutil' }, { stdout: 'Terminal\n' });
+    mockedAccess.mockResolvedValueOnce(undefined);
+    mockedMkdtemp.mockResolvedValueOnce('/tmp/lobehub-openinapp-test');
+    respondExec({ binary: 'sips' }, { stdout: '' });
+    mockedReadFile.mockResolvedValueOnce(Buffer.from([0xff]));
+
+    const result = await extractAppIcon('terminal', 'darwin');
+
+    expect(result).toBeDefined();
+  });
+
+  it('returns undefined when no bundle path exists', async () => {
+    respondToolsAvailable();
+    mockedAccess.mockRejectedValue(new Error('missing'));
+
+    const result = await extractAppIcon('vscode', 'darwin');
+
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined when plutil cannot read CFBundleIconFile', async () => {
+    respondToolsAvailable();
+    mockedAccess.mockResolvedValueOnce(undefined);
+    respondExec({ binary: 'plutil' }, { error: new Error('plutil: not found') });
+
+    const result = await extractAppIcon('vscode', 'darwin');
+
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined when the resolved .icns is missing', async () => {
+    respondToolsAvailable();
+    mockedAccess.mockResolvedValueOnce(undefined); // bundle exists
+    respondExec({ binary: 'plutil' }, { stdout: 'Code.icns\n' });
+    mockedAccess.mockRejectedValueOnce(new Error('missing icns')); // .icns missing
+
+    const result = await extractAppIcon('vscode', 'darwin');
+
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined when sips fails', async () => {
+    respondToolsAvailable();
+    mockedAccess.mockResolvedValueOnce(undefined);
+    respondExec({ binary: 'plutil' }, { stdout: 'Code.icns\n' });
+    mockedAccess.mockResolvedValueOnce(undefined);
+    mockedMkdtemp.mockResolvedValueOnce('/tmp/lobehub-openinapp-test');
+    respondExec({ binary: 'sips' }, { error: new Error('sips error') });
+
+    const result = await extractAppIcon('vscode', 'darwin');
+
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined when the produced PNG is empty', async () => {
+    respondToolsAvailable();
+    mockedAccess.mockResolvedValueOnce(undefined);
+    respondExec({ binary: 'plutil' }, { stdout: 'Code.icns\n' });
+    mockedAccess.mockResolvedValueOnce(undefined);
+    mockedMkdtemp.mockResolvedValueOnce('/tmp/lobehub-openinapp-test');
+    respondExec({ binary: 'sips' }, { stdout: '' });
+    mockedReadFile.mockResolvedValueOnce(Buffer.alloc(0));
+
+    const result = await extractAppIcon('vscode', 'darwin');
+
+    expect(result).toBeUndefined();
+  });
+
+  it('returns undefined when registry has no darwin entry for the app', async () => {
+    respondToolsAvailable();
+    const result = await extractAppIcon('explorer', 'darwin');
+    expect(result).toBeUndefined();
+    expect(mockedAccess).not.toHaveBeenCalled();
+  });
+
+  it('returns undefined on win32 (extractor is macOS-only)', async () => {
+    const result = await extractAppIcon('vscode', 'win32');
+    expect(result).toBeUndefined();
+    expect(mockedExecFile).not.toHaveBeenCalled();
+  });
+
+  it('returns undefined on linux (extractor is macOS-only)', async () => {
+    const result = await extractAppIcon('vscode', 'linux');
+    expect(result).toBeUndefined();
+    expect(mockedExecFile).not.toHaveBeenCalled();
+  });
+});
+
+describe('extractAllIcons', () => {
+  it('returns a map of only AppIds with successfully extracted icons', async () => {
+    respondToolsAvailable();
+
+    // vscode succeeds
+    mockedAccess.mockResolvedValueOnce(undefined); // bundle
+    respondExec({ binary: 'plutil' }, { stdout: 'Code.icns\n' });
+    mockedAccess.mockResolvedValueOnce(undefined); // .icns
+    mockedMkdtemp.mockResolvedValueOnce('/tmp/lobehub-openinapp-test');
+    respondExec({ binary: 'sips' }, { stdout: '' });
+    mockedReadFile.mockResolvedValueOnce(Buffer.from('vscode'));
+
+    // cursor fails at bundle access (try all paths fail)
+    mockedAccess.mockRejectedValue(new Error('missing'));
+
+    // xcode succeeds — reset access for it
+    // (subsequent calls to mockedAccess will keep returning rejection)
+    // So this test exercises: success, fail-no-bundle.
+
+    const map = await extractAllIcons(['vscode', 'cursor'], 'darwin');
+
+    expect(map.has('vscode')).toBe(true);
+    expect(map.has('cursor')).toBe(false);
+  });
+
+  it('returns empty map when input list is empty', async () => {
+    const map = await extractAllIcons([], 'darwin');
+    expect(map.size).toBe(0);
+  });
+
+  it('does not throw when extraction errors', async () => {
+    respondToolsAvailable();
+    mockedAccess.mockResolvedValueOnce(undefined);
+    respondExec({ binary: 'plutil' }, { error: new Error('boom') });
+
+    const map = await extractAllIcons(['vscode'], 'darwin');
+
+    expect(map.size).toBe(0);
+  });
+
+  it('skips all when tools are unavailable', async () => {
+    // /usr/bin/which plutil fails
+    respondExec({ binary: '/usr/bin/which' }, { error: new Error('not found') });
+
+    const map = await extractAllIcons(['vscode', 'terminal'], 'darwin');
+
+    expect(map.size).toBe(0);
+  });
+});

apps/desktop/src/main/modules/openInApp/__tests__/launchers.test.ts

@@ -0,0 +1,247 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+
+import { shell } from 'electron';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { launchApp } from '../launchers';
+
+vi.mock('@/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  }),
+}));
+
+vi.mock('node:fs/promises', () => ({
+  access: vi.fn(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execFile: vi.fn(),
+}));
+
+vi.mock('electron', () => ({
+  shell: {
+    openPath: vi.fn(),
+  },
+}));
+
+const mockedAccess = vi.mocked(access);
+const mockedExecFile = vi.mocked(execFile) as unknown as ReturnType<typeof vi.fn>;
+const mockedShell = vi.mocked(shell);
+
+type LastCall = { file: string; args: string[] };
+
+const captureExec = (): LastCall => {
+  expect(mockedExecFile).toHaveBeenCalled();
+  const [file, args] = mockedExecFile.mock.calls[0];
+  return { args: args as string[], file: file as string };
+};
+
+interface ExecOutcome {
+  code: number;
+  stderr?: string;
+  stdout?: string;
+}
+
+const respondExec = (outcome: ExecOutcome) => {
+  mockedExecFile.mockImplementationOnce(
+    (_file: string, _args: string[], _opts: unknown, cb: any) => {
+      const callback = typeof _opts === 'function' ? _opts : cb;
+      if (outcome.code === 0) {
+        callback(null, outcome.stdout ?? '', outcome.stderr ?? '');
+      } else {
+        const err: NodeJS.ErrnoException & { stderr?: string } = new Error('exec failed');
+        err.stderr = outcome.stderr ?? '';
+        (err as any).code = outcome.code;
+        callback(err, '', outcome.stderr ?? '');
+      }
+      return undefined as any;
+    },
+  );
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockedAccess.mockResolvedValue(undefined);
+});
+
+describe('launchApp - path validation', () => {
+  it('rejects relative paths', async () => {
+    const result = await launchApp('vscode', 'relative/path', 'darwin');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Path must be absolute');
+    expect(mockedExecFile).not.toHaveBeenCalled();
+  });
+
+  it('rejects paths that do not exist', async () => {
+    mockedAccess.mockRejectedValueOnce(new Error('ENOENT'));
+
+    const result = await launchApp('vscode', '/missing', 'darwin');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Path not found: /missing');
+    expect(mockedExecFile).not.toHaveBeenCalled();
+  });
+
+  it('returns error when app is not available on platform', async () => {
+    const result = await launchApp('xcode', '/some/path', 'linux');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toContain('Xcode');
+    expect(result.error).toContain('not available on this platform');
+  });
+});
+
+describe('launchApp - macOpenA strategy', () => {
+  it('spawns open -a <appName> <path>', async () => {
+    respondExec({ code: 0 });
+
+    const result = await launchApp('vscode', '/work/dir', 'darwin');
+
+    expect(result.success).toBe(true);
+    const call = captureExec();
+    expect(call.file).toBe('open');
+    expect(call.args).toEqual(['-a', 'Visual Studio Code', '/work/dir']);
+  });
+
+  it('returns stderr substring on failure', async () => {
+    respondExec({ code: 1, stderr: '  cannot open Cursor.app  ' });
+
+    const result = await launchApp('cursor', '/work/dir', 'darwin');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('cannot open Cursor.app');
+  });
+});
+
+describe('launchApp - macOpen strategy', () => {
+  it('spawns open <path>', async () => {
+    respondExec({ code: 0 });
+
+    const result = await launchApp('finder', '/work/dir', 'darwin');
+
+    expect(result.success).toBe(true);
+    const call = captureExec();
+    expect(call.file).toBe('open');
+    expect(call.args).toEqual(['/work/dir']);
+  });
+});
+
+describe('launchApp - exec strategy', () => {
+  it('spawns <binary> <path>', async () => {
+    respondExec({ code: 0 });
+
+    const result = await launchApp('vscode', '/work/dir', 'linux');
+
+    expect(result.success).toBe(true);
+    const call = captureExec();
+    expect(call.file).toBe('code');
+    expect(call.args).toEqual(['/work/dir']);
+  });
+
+  it('appends registry-provided args before path', async () => {
+    const registry = await import('../registry');
+    const original = registry.APP_REGISTRY.vscode.launch.linux;
+    registry.APP_REGISTRY.vscode.launch.linux = {
+      args: ['--new-window'],
+      binary: 'code',
+      type: 'exec',
+    };
+
+    respondExec({ code: 0 });
+
+    const result = await launchApp('vscode', '/work/dir', 'linux');
+
+    expect(result.success).toBe(true);
+    const call = captureExec();
+    expect(call.args).toEqual(['--new-window', '/work/dir']);
+
+    registry.APP_REGISTRY.vscode.launch.linux = original;
+  });
+
+  it('rejects suspicious binary names', async () => {
+    const registry = await import('../registry');
+    const original = registry.APP_REGISTRY.vscode.launch.linux;
+    registry.APP_REGISTRY.vscode.launch.linux = {
+      binary: 'rm; ls',
+      type: 'exec',
+    };
+
+    const result = await launchApp('vscode', '/work/dir', 'linux');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Invalid binary name');
+    expect(mockedExecFile).not.toHaveBeenCalled();
+
+    registry.APP_REGISTRY.vscode.launch.linux = original;
+  });
+
+  it('rejects binary names with spaces', async () => {
+    const registry = await import('../registry');
+    const original = registry.APP_REGISTRY.vscode.launch.linux;
+    registry.APP_REGISTRY.vscode.launch.linux = {
+      binary: 'foo bar',
+      type: 'exec',
+    };
+
+    const result = await launchApp('vscode', '/work/dir', 'linux');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Invalid binary name');
+
+    registry.APP_REGISTRY.vscode.launch.linux = original;
+  });
+
+  it('accepts absolute-path binary names', async () => {
+    const registry = await import('../registry');
+    const original = registry.APP_REGISTRY.vscode.launch.linux;
+    registry.APP_REGISTRY.vscode.launch.linux = {
+      binary: '/usr/local/bin/code',
+      type: 'exec',
+    };
+
+    respondExec({ code: 0 });
+
+    const result = await launchApp('vscode', '/work/dir', 'linux');
+
+    expect(result.success).toBe(true);
+    const call = captureExec();
+    expect(call.file).toBe('/usr/local/bin/code');
+
+    registry.APP_REGISTRY.vscode.launch.linux = original;
+  });
+
+  it('returns stderr substring on non-zero exit', async () => {
+    respondExec({ code: 1, stderr: 'command not found' });
+
+    const result = await launchApp('vscode', '/work/dir', 'linux');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('command not found');
+  });
+});
+
+describe('launchApp - shellOpenPath strategy', () => {
+  it('delegates to shell.openPath', async () => {
+    mockedShell.openPath.mockResolvedValueOnce('');
+
+    const result = await launchApp('explorer', '/abs/work-dir', 'win32');
+
+    expect(result.success).toBe(true);
+    expect(mockedShell.openPath).toHaveBeenCalledWith('/abs/work-dir');
+  });
+
+  it('returns error string from shell.openPath as error', async () => {
+    mockedShell.openPath.mockResolvedValueOnce('cannot open');
+
+    const result = await launchApp('files', '/some/dir', 'linux');
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('cannot open');
+  });
+});

apps/desktop/src/main/modules/openInApp/cache.ts

@@ -0,0 +1,18 @@
+import type { DetectedApp } from '@lobechat/electron-client-ipc';
+
+import { detectAllApps } from './detectors';
+
+let cachedPromise: Promise<DetectedApp[]> | null = null;
+
+export const getCachedDetection = (
+  platform: NodeJS.Platform = process.platform,
+): Promise<DetectedApp[]> => {
+  if (!cachedPromise) {
+    cachedPromise = detectAllApps(platform);
+  }
+  return cachedPromise;
+};
+
+export const clearDetectionCache = (): void => {
+  cachedPromise = null;
+};

apps/desktop/src/main/modules/openInApp/detectors.ts

@@ -0,0 +1,109 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+import type { DetectedApp, OpenInAppId } from '@lobechat/electron-client-ipc';
+
+import { createLogger } from '@/utils/logger';
+
+import { extractAllIcons } from './iconExtractor';
+import type { DetectStrategy } from './registry';
+import { ALWAYS_INSTALLED, APP_REGISTRY } from './registry';
+
+// Icon extraction shells out to plutil + sips on macOS (see iconExtractor.ts)
+// so Electron itself cannot crash on `app.getFileIcon` regressions. Renderer
+// falls back to lucide if extraction returns undefined.
+
+const logger = createLogger('modules:openInApp:detectors');
+
+const execFileAsync = promisify(execFile);
+
+const SAFE_BINARY_REGEX = /^[\w.-]+$/;
+
+const probeAppBundle = async (paths: string[]): Promise<boolean> => {
+  for (const path of paths) {
+    try {
+      await access(path);
+      return true;
+    } catch {
+      // try next
+    }
+  }
+  return false;
+};
+
+const probeCommandV = async (binary: string): Promise<boolean> => {
+  if (!SAFE_BINARY_REGEX.test(binary)) {
+    logger.debug(`rejecting unsafe binary name for commandV: ${binary}`);
+    return false;
+  }
+  try {
+    await execFileAsync('/bin/sh', ['-c', `command -v "${binary}"`]);
+    return true;
+  } catch (error) {
+    logger.debug(`commandV probe failed for ${binary}: ${(error as Error).message}`);
+    return false;
+  }
+};
+
+const probeRegistryAppPaths = async (exeName: string): Promise<boolean> => {
+  try {
+    await execFileAsync('where', [exeName], { windowsHide: true });
+    return true;
+  } catch (error) {
+    logger.debug(`where probe failed for ${exeName}: ${(error as Error).message}`);
+    return false;
+  }
+};
+
+const runDetectStrategy = (strategy: DetectStrategy): Promise<boolean> => {
+  switch (strategy.type) {
+    case 'appBundle': {
+      return probeAppBundle(strategy.paths);
+    }
+    case 'commandV': {
+      return probeCommandV(strategy.binary);
+    }
+    case 'registryAppPaths': {
+      return probeRegistryAppPaths(strategy.exeName);
+    }
+  }
+};
+
+export const detectApp = async (id: OpenInAppId, platform: NodeJS.Platform): Promise<boolean> => {
+  if (ALWAYS_INSTALLED[platform] === id) {
+    return true;
+  }
+  const descriptor = APP_REGISTRY[id];
+  const strategy = descriptor?.detect[platform];
+  if (!strategy) {
+    return false;
+  }
+  return runDetectStrategy(strategy);
+};
+
+export const detectAllApps = async (
+  platform: NodeJS.Platform = process.platform,
+): Promise<DetectedApp[]> => {
+  const entries = Object.entries(APP_REGISTRY) as Array<
+    [OpenInAppId, (typeof APP_REGISTRY)[OpenInAppId]]
+  >;
+  const installedFlags = await Promise.all(entries.map(([id]) => detectApp(id, platform)));
+
+  // Extract icons for installed apps only. Extraction shells out to plutil +
+  // sips (see iconExtractor.ts) so it cannot crash the renderer; failures
+  // resolve to undefined and the renderer falls back to lucide icons.
+  const installedIds = entries.filter((_entry, i) => installedFlags[i]).map(([id]) => id);
+  const icons = await extractAllIcons(installedIds, platform);
+
+  return entries.map(([id, descriptor], i) => {
+    const installed = installedFlags[i];
+    const icon = installed ? icons.get(id) : undefined;
+    return {
+      displayName: descriptor.displayName,
+      id,
+      installed,
+      ...(icon ? { icon } : {}),
+    } satisfies DetectedApp;
+  });
+};

apps/desktop/src/main/modules/openInApp/iconExtractor.ts

@@ -0,0 +1,210 @@
+import { execFile } from 'node:child_process';
+import { access, mkdtemp, readFile, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import type { OpenInAppId } from '@lobechat/electron-client-ipc';
+
+import { createLogger } from '@/utils/logger';
+
+import { APP_REGISTRY } from './registry';
+
+const logger = createLogger('modules:openInApp:iconExtractor');
+
+// Manual promise wrapper rather than util.promisify(execFile): the latter
+// relies on execFile's custom `util.promisify.custom` symbol to return
+// `{ stdout, stderr }`, which vi.fn() mocks don't carry — so destructuring
+// silently yields `undefined` under test. This wrapper resolves directly to
+// the stdout string and is mock-friendly.
+const execFileToString = (
+  file: string,
+  args: string[],
+  opts?: { timeout?: number },
+): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const cb = (err: Error | null, stdout: string, stderr: string) => {
+      if (err) {
+        (err as Error & { stderr?: string }).stderr = stderr;
+        reject(err);
+      } else {
+        resolve(stdout);
+      }
+    };
+    if (opts) execFile(file, args, opts, cb);
+    else execFile(file, args, cb);
+  });
+
+/** Render dimensions for the extracted PNG. 64 keeps the payload tiny while
+ *  staying crisp at the renderer's 16-20 px display size on retina. */
+const ICON_SIZE = 64;
+
+/** Per-extraction bound. plutil and sips are local file ops; tens of ms is
+ *  typical, so a generous timeout still catches real hangs. */
+const EXEC_TIMEOUT_MS = 5000;
+
+let tmpDirPromise: Promise<string | undefined> | undefined;
+
+const ensureTmpDir = async (): Promise<string | undefined> => {
+  if (tmpDirPromise) return tmpDirPromise;
+  tmpDirPromise = (async () => {
+    try {
+      return await mkdtemp(path.join(tmpdir(), 'lobehub-openinapp-'));
+    } catch (error) {
+      logger.debug(`failed to create tmp dir: ${(error as Error).message}`);
+      return undefined;
+    }
+  })();
+  return tmpDirPromise;
+};
+
+let toolsAvailablePromise: Promise<boolean> | undefined;
+
+/**
+ * Confirm `plutil` and `sips` are both on PATH. Both ship with every macOS
+ * install so this is effectively a sanity check; cached for the process lifetime.
+ */
+const areToolsAvailable = (): Promise<boolean> => {
+  if (toolsAvailablePromise) return toolsAvailablePromise;
+  toolsAvailablePromise = (async () => {
+    try {
+      await execFileToString('/usr/bin/which', ['plutil']);
+      await execFileToString('/usr/bin/which', ['sips']);
+      return true;
+    } catch {
+      logger.debug('plutil or sips missing from PATH; falling back to renderer icons');
+      return false;
+    }
+  })();
+  return toolsAvailablePromise;
+};
+
+const resolveDarwinBundlePath = async (id: OpenInAppId): Promise<string | undefined> => {
+  const strategy = APP_REGISTRY[id]?.detect.darwin;
+  if (!strategy || strategy.type !== 'appBundle') return undefined;
+  for (const candidate of strategy.paths) {
+    try {
+      await access(candidate);
+      return candidate;
+    } catch {
+      // try next
+    }
+  }
+  return undefined;
+};
+
+/**
+ * Look up the bundle's icon file name via Info.plist (`CFBundleIconFile`).
+ * Returns the resolved absolute .icns path, or undefined if not derivable.
+ */
+const resolveIcnsPath = async (bundlePath: string): Promise<string | undefined> => {
+  const plistPath = path.join(bundlePath, 'Contents', 'Info.plist');
+  try {
+    const stdout = await execFileToString(
+      'plutil',
+      ['-extract', 'CFBundleIconFile', 'raw', plistPath],
+      { timeout: EXEC_TIMEOUT_MS },
+    );
+    const iconName = stdout.trim();
+    if (!iconName) return undefined;
+    const fileName = iconName.endsWith('.icns') ? iconName : `${iconName}.icns`;
+    const icnsPath = path.join(bundlePath, 'Contents', 'Resources', fileName);
+    await access(icnsPath);
+    return icnsPath;
+  } catch (error) {
+    logger.debug(`resolveIcnsPath failed for ${bundlePath}: ${(error as Error).message}`);
+    return undefined;
+  }
+};
+
+/**
+ * Resize/convert the given .icns to a 64×64 PNG using sips, then return the
+ * base64 data URL. The PNG file is unlinked after read.
+ */
+const renderIcnsToDataUrl = async (
+  icnsPath: string,
+  tmpDir: string,
+  filename: string,
+): Promise<string | undefined> => {
+  const outPath = path.join(tmpDir, filename);
+  try {
+    await execFileToString(
+      'sips',
+      [
+        '-z',
+        String(ICON_SIZE),
+        String(ICON_SIZE),
+        '-s',
+        'format',
+        'png',
+        icnsPath,
+        '--out',
+        outPath,
+      ],
+      { timeout: EXEC_TIMEOUT_MS },
+    );
+    const buf = await readFile(outPath);
+    if (buf.length === 0) return undefined;
+    return `data:image/png;base64,${buf.toString('base64')}`;
+  } catch (error) {
+    logger.debug(`sips failed for ${icnsPath}: ${(error as Error).message}`);
+    return undefined;
+  } finally {
+    unlink(outPath).catch(() => undefined);
+  }
+};
+
+/**
+ * Extract the real macOS app icon for the given AppId by reading the bundle's
+ * Info.plist (`CFBundleIconFile`) and rendering the resolved .icns via `sips`.
+ * Both `plutil` and `sips` ship with every macOS install — no Xcode, swift, or
+ * electron-builder bundling required, and no JXA / NSImage drawing path
+ * (which is broken in JXA: lockFocus and NSGraphicsContext class methods are
+ * not exposed). macOS only; other platforms return undefined.
+ */
+export const extractAppIcon = async (
+  id: OpenInAppId,
+  platform: NodeJS.Platform = process.platform,
+): Promise<string | undefined> => {
+  if (platform !== 'darwin') return undefined;
+  try {
+    if (!(await areToolsAvailable())) return undefined;
+    const bundlePath = await resolveDarwinBundlePath(id);
+    if (!bundlePath) return undefined;
+    const icnsPath = await resolveIcnsPath(bundlePath);
+    if (!icnsPath) return undefined;
+    const tmpDir = await ensureTmpDir();
+    if (!tmpDir) return undefined;
+    return await renderIcnsToDataUrl(icnsPath, tmpDir, `${id}.png`);
+  } catch (error) {
+    logger.debug(`extractAppIcon error for ${id}: ${(error as Error).message}`);
+    return undefined;
+  }
+};
+
+/**
+ * Resolve icons for a list of installed AppIds. Sequential — keeps spawn
+ * pressure low and matches the underlying single-thread tools.
+ */
+export const extractAllIcons = async (
+  installedIds: OpenInAppId[],
+  platform: NodeJS.Platform = process.platform,
+): Promise<Map<OpenInAppId, string>> => {
+  const map = new Map<OpenInAppId, string>();
+  for (const id of installedIds) {
+    try {
+      const icon = await extractAppIcon(id, platform);
+      if (icon) map.set(id, icon);
+    } catch (error) {
+      logger.debug(`extractAllIcons: skipping ${id} after error: ${(error as Error).message}`);
+    }
+  }
+  return map;
+};
+
+/**
+ * Test-only: reset the module-level caches so each test starts fresh.
+ */
+export const __resetForTest = () => {
+  tmpDirPromise = undefined;
+  toolsAvailablePromise = undefined;
+};

apps/desktop/src/main/modules/openInApp/launchers.ts

@@ -0,0 +1,106 @@
+import { execFile } from 'node:child_process';
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import type { OpenInAppId, OpenInAppResult } from '@lobechat/electron-client-ipc';
+import { shell } from 'electron';
+
+import { createLogger } from '@/utils/logger';
+
+import type { LaunchStrategy } from './registry';
+import { APP_REGISTRY } from './registry';
+
+const logger = createLogger('modules:openInApp:launchers');
+
+const execFileAsync = promisify(execFile);
+
+const SAFE_BINARY_REGEX = /^[\w.-]+$/;
+
+const isAllowedBinary = (binary: string): boolean =>
+  SAFE_BINARY_REGEX.test(binary) || path.isAbsolute(binary);
+
+interface ExecError extends Error {
+  stderr?: string;
+}
+
+const formatExecError = (error: unknown): string => {
+  const err = error as ExecError;
+  const stderr = typeof err?.stderr === 'string' ? err.stderr.trim() : '';
+  const fallback = err?.message ?? 'Launch failed';
+  return (stderr || fallback).slice(0, 200);
+};
+
+const runLaunchStrategy = async (
+  strategy: LaunchStrategy,
+  absolutePath: string,
+): Promise<OpenInAppResult> => {
+  switch (strategy.type) {
+    case 'macOpenA': {
+      try {
+        await execFileAsync('open', ['-a', strategy.appName, absolutePath]);
+        return { success: true };
+      } catch (error) {
+        return { error: formatExecError(error), success: false };
+      }
+    }
+    case 'macOpen': {
+      try {
+        await execFileAsync('open', [absolutePath]);
+        return { success: true };
+      } catch (error) {
+        return { error: formatExecError(error), success: false };
+      }
+    }
+    case 'exec': {
+      if (!isAllowedBinary(strategy.binary)) {
+        return { error: 'Invalid binary name', success: false };
+      }
+      const extraArgs = strategy.args ?? [];
+      try {
+        await execFileAsync(strategy.binary, [...extraArgs, absolutePath]);
+        return { success: true };
+      } catch (error) {
+        return { error: formatExecError(error), success: false };
+      }
+    }
+    case 'shellOpenPath': {
+      const result = await shell.openPath(absolutePath);
+      return result ? { error: result, success: false } : { success: true };
+    }
+  }
+};
+
+export const launchApp = async (
+  id: OpenInAppId,
+  absolutePath: string,
+  platform: NodeJS.Platform = process.platform,
+): Promise<OpenInAppResult> => {
+  const descriptor = APP_REGISTRY[id];
+  const strategy = descriptor?.launch[platform];
+  if (!descriptor || !strategy) {
+    const displayName = descriptor?.displayName ?? id;
+    return {
+      error: `${displayName} is not available on this platform`,
+      success: false,
+    };
+  }
+
+  if (!path.isAbsolute(absolutePath)) {
+    return { error: 'Path must be absolute', success: false };
+  }
+
+  try {
+    await access(absolutePath);
+  } catch {
+    return { error: `Path not found: ${absolutePath}`, success: false };
+  }
+
+  const result = await runLaunchStrategy(strategy, absolutePath);
+  if (result.success) {
+    logger.info(`launched ${id} at ${absolutePath}`);
+  } else {
+    logger.error(`failed to launch ${id} at ${absolutePath}: ${result.error}`);
+  }
+  return result;
+};

apps/desktop/src/main/modules/openInApp/registry.ts

@@ -0,0 +1,129 @@
+import type { OpenInAppId } from '@lobechat/electron-client-ipc';
+
+export type DetectStrategy =
+  | { paths: string[]; type: 'appBundle' }
+  | { exeName: string; type: 'registryAppPaths' }
+  | { binary: string; type: 'commandV' };
+
+export type LaunchStrategy =
+  | { appName: string; type: 'macOpenA' }
+  | { type: 'macOpen' }
+  | { args?: string[]; binary: string; type: 'exec' }
+  | { type: 'shellOpenPath' };
+
+export interface AppDescriptor {
+  detect: Partial<Record<NodeJS.Platform, DetectStrategy>>;
+  displayName: string;
+  launch: Partial<Record<NodeJS.Platform, LaunchStrategy>>;
+}
+
+export const APP_REGISTRY: Record<OpenInAppId, AppDescriptor> = {
+  vscode: {
+    detect: {
+      darwin: { paths: ['/Applications/Visual Studio Code.app'], type: 'appBundle' },
+      linux: { binary: 'code', type: 'commandV' },
+      win32: { exeName: 'Code.exe', type: 'registryAppPaths' },
+    },
+    displayName: 'VS Code',
+    launch: {
+      darwin: { appName: 'Visual Studio Code', type: 'macOpenA' },
+      linux: { binary: 'code', type: 'exec' },
+      win32: { binary: 'code', type: 'exec' },
+    },
+  },
+  cursor: {
+    detect: {
+      darwin: { paths: ['/Applications/Cursor.app'], type: 'appBundle' },
+      linux: { binary: 'cursor', type: 'commandV' },
+      win32: { exeName: 'Cursor.exe', type: 'registryAppPaths' },
+    },
+    displayName: 'Cursor',
+    launch: {
+      darwin: { appName: 'Cursor', type: 'macOpenA' },
+      linux: { binary: 'cursor', type: 'exec' },
+      win32: { binary: 'cursor', type: 'exec' },
+    },
+  },
+  zed: {
+    detect: {
+      darwin: { paths: ['/Applications/Zed.app'], type: 'appBundle' },
+      linux: { binary: 'zed', type: 'commandV' },
+    },
+    displayName: 'Zed',
+    launch: {
+      darwin: { appName: 'Zed', type: 'macOpenA' },
+      linux: { binary: 'zed', type: 'exec' },
+    },
+  },
+  webstorm: {
+    detect: {
+      darwin: { paths: ['/Applications/WebStorm.app'], type: 'appBundle' },
+      linux: { binary: 'webstorm', type: 'commandV' },
+      win32: { exeName: 'webstorm64.exe', type: 'registryAppPaths' },
+    },
+    displayName: 'WebStorm',
+    launch: {
+      darwin: { appName: 'WebStorm', type: 'macOpenA' },
+      linux: { binary: 'webstorm', type: 'exec' },
+      win32: { binary: 'webstorm', type: 'exec' },
+    },
+  },
+  xcode: {
+    detect: { darwin: { paths: ['/Applications/Xcode.app'], type: 'appBundle' } },
+    displayName: 'Xcode',
+    launch: { darwin: { appName: 'Xcode', type: 'macOpenA' } },
+  },
+  finder: {
+    detect: {
+      darwin: { paths: ['/System/Library/CoreServices/Finder.app'], type: 'appBundle' },
+    },
+    displayName: 'Finder',
+    launch: { darwin: { type: 'macOpen' } },
+  },
+  explorer: {
+    detect: { win32: { exeName: 'explorer.exe', type: 'registryAppPaths' } },
+    displayName: 'Explorer',
+    launch: { win32: { type: 'shellOpenPath' } },
+  },
+  files: {
+    detect: { linux: { binary: 'xdg-open', type: 'commandV' } },
+    displayName: 'Files',
+    launch: { linux: { type: 'shellOpenPath' } },
+  },
+  terminal: {
+    detect: {
+      darwin: {
+        paths: [
+          '/System/Applications/Utilities/Terminal.app',
+          '/Applications/Utilities/Terminal.app',
+        ],
+        type: 'appBundle',
+      },
+    },
+    displayName: 'Terminal',
+    launch: { darwin: { appName: 'Terminal', type: 'macOpenA' } },
+  },
+  iterm2: {
+    detect: { darwin: { paths: ['/Applications/iTerm.app'], type: 'appBundle' } },
+    displayName: 'iTerm2',
+    launch: { darwin: { appName: 'iTerm', type: 'macOpenA' } },
+  },
+  ghostty: {
+    detect: {
+      darwin: { paths: ['/Applications/Ghostty.app'], type: 'appBundle' },
+      linux: { binary: 'ghostty', type: 'commandV' },
+    },
+    displayName: 'Ghostty',
+    launch: {
+      darwin: { appName: 'Ghostty', type: 'macOpenA' },
+      linux: { binary: 'ghostty', type: 'exec' },
+    },
+  },
+};
+
+/** AppIds that are always considered "installed" — file managers, which we treat as platform-provided. */
+export const ALWAYS_INSTALLED: Partial<Record<NodeJS.Platform, OpenInAppId>> = {
+  darwin: 'finder',
+  linux: 'files',
+  win32: 'explorer',
+};

apps/desktop/src/main/modules/toolDetectors/__tests__/cliAgentDetectors.test.ts

@@ -0,0 +1,185 @@
+import * as childProcess from 'node:child_process';
+import * as os from 'node:os';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mocks must be set up before importing the module under test, because the
+// module captures `promisify(execFile)` / `promisify(exec)` at import time.
+vi.mock('node:os', async () => {
+  const actual = await vi.importActual<typeof os>('node:os');
+  return { ...actual, platform: vi.fn(() => actual.platform()) };
+});
+
+vi.mock('node:child_process', () => ({
+  exec: vi.fn(),
+  execFile: vi.fn(),
+}));
+
+const platformMock = vi.mocked(os.platform);
+const execFileMock = vi.mocked(childProcess.execFile);
+const execMock = vi.mocked(childProcess.exec);
+
+const noErr = null;
+const callExecFile = (stdout: string, stderr = '') => {
+  execFileMock.mockImplementationOnce(((file: string, args: any, opts: any, cb: any) => {
+    // promisify-wrapped: the callback is always the last positional arg.
+    const callback = typeof opts === 'function' ? opts : cb;
+    callback(noErr, { stdout, stderr });
+    return {} as any;
+  }) as any);
+};
+const callExecFileError = (err: Error) => {
+  execFileMock.mockImplementationOnce(((file: string, args: any, opts: any, cb: any) => {
+    const callback = typeof opts === 'function' ? opts : cb;
+    callback(err, { stdout: '', stderr: '' });
+    return {} as any;
+  }) as any);
+};
+const callExec = (stdout: string, stderr = '') => {
+  execMock.mockImplementationOnce(((cmd: string, opts: any, cb: any) => {
+    const callback = typeof opts === 'function' ? opts : cb;
+    callback(noErr, { stdout, stderr });
+    return {} as any;
+  }) as any);
+};
+
+describe('cliAgentDetectors', () => {
+  beforeEach(() => {
+    execFileMock.mockReset();
+    execMock.mockReset();
+  });
+
+  afterEach(() => {
+    vi.resetModules();
+  });
+
+  describe('on Windows with an npm-installed `claude.cmd` shim', () => {
+    beforeEach(() => {
+      platformMock.mockReturnValue('win32');
+    });
+
+    it('resolves `claude` to the .cmd path via `where`, then runs it through the shell', async () => {
+      // 1) `where claude` → resolves to the .cmd shim under %APPDATA%\npm
+      callExecFile('C:\\Users\\Hanam\\AppData\\Roaming\\npm\\claude.cmd\r\n');
+      // 2) `cmd /c "...\\claude.cmd" --version` → keyword match
+      callExec('1.2.3 (Claude Code)');
+
+      const { claudeCodeDetector } = await import('../cliAgentDetectors');
+      const status = await claudeCodeDetector.detect();
+
+      expect(status.available).toBe(true);
+      expect(status.path).toBe('C:\\Users\\Hanam\\AppData\\Roaming\\npm\\claude.cmd');
+      expect(status.version).toBe('1.2.3 (Claude Code)');
+
+      // The validation call must go via `exec` (shell), NOT `execFile`, so
+      // cmd.exe can actually interpret the .cmd shim.
+      expect(execMock).toHaveBeenCalledTimes(1);
+      const execCall = execMock.mock.calls[0]!;
+      expect(execCall[0]).toBe('"C:\\Users\\Hanam\\AppData\\Roaming\\npm\\claude.cmd" --version');
+    });
+
+    it('returns unavailable when `where` finds nothing', async () => {
+      callExecFileError(new Error('not found'));
+
+      const { claudeCodeDetector } = await import('../cliAgentDetectors');
+      const status = await claudeCodeDetector.detect();
+
+      expect(status.available).toBe(false);
+      // We should NOT proceed to invoke anything after a failed resolve.
+      expect(execMock).not.toHaveBeenCalled();
+    });
+
+    it('rejects custom commands containing shell metacharacters', async () => {
+      const { detectHeterogeneousCliCommand } = await import('../cliAgentDetectors');
+      const status = await detectHeterogeneousCliCommand('claude-code', 'claude & calc.exe');
+
+      expect(status.available).toBe(false);
+      expect(execFileMock).not.toHaveBeenCalled();
+      expect(execMock).not.toHaveBeenCalled();
+    });
+
+    it('fails detection when version output does not match the expected keyword', async () => {
+      callExecFile('C:\\some\\other\\claude.cmd\r\n');
+      callExec('this is some other binary v1.0');
+
+      const { claudeCodeDetector } = await import('../cliAgentDetectors');
+      const status = await claudeCodeDetector.detect();
+
+      expect(status.available).toBe(false);
+    });
+
+    it('prefers a .cmd shim when `where` returns multiple PATHEXT matches (codex case)', async () => {
+      // npm drops a Unix shell-script wrapper (extensionless) alongside the
+      // Windows `.cmd` / `.ps1` shims. `where` lists every PATHEXT match;
+      // taking the first line would land us on the unrunnable wrapper.
+      callExecFile(
+        [
+          'C:\\Users\\Hanam\\AppData\\Roaming\\npm\\codex',
+          'C:\\Users\\Hanam\\AppData\\Roaming\\npm\\codex.cmd',
+          'C:\\Users\\Hanam\\AppData\\Roaming\\npm\\codex.ps1',
+        ].join('\r\n'),
+      );
+      callExec('codex 0.130.0');
+
+      const { codexDetector } = await import('../cliAgentDetectors');
+      const status = await codexDetector.detect();
+
+      expect(status.available).toBe(true);
+      expect(status.path).toBe('C:\\Users\\Hanam\\AppData\\Roaming\\npm\\codex.cmd');
+      expect(execMock.mock.calls[0]![0]).toBe(
+        '"C:\\Users\\Hanam\\AppData\\Roaming\\npm\\codex.cmd" --version',
+      );
+    });
+
+    it('prefers .exe over .cmd when both are present', async () => {
+      callExecFile(['C:\\tools\\foo.exe', 'C:\\tools\\foo.cmd'].join('\r\n'));
+      callExecFile('claude code 1.0.0');
+
+      const { claudeCodeDetector } = await import('../cliAgentDetectors');
+      const status = await claudeCodeDetector.detect();
+
+      expect(status.available).toBe(true);
+      expect(status.path).toBe('C:\\tools\\foo.exe');
+      // .exe runs directly via execFile — no shell.
+      expect(execMock).not.toHaveBeenCalled();
+      expect(execFileMock).toHaveBeenCalledTimes(2);
+      expect(execFileMock.mock.calls[1]![0]).toBe('C:\\tools\\foo.exe');
+    });
+
+    it('reports unavailable when `where` only returns unrunnable matches (.ps1 / extensionless)', async () => {
+      callExecFile(
+        [
+          'C:\\Users\\Hanam\\AppData\\Roaming\\npm\\claude',
+          'C:\\Users\\Hanam\\AppData\\Roaming\\npm\\claude.ps1',
+        ].join('\r\n'),
+      );
+
+      const { claudeCodeDetector } = await import('../cliAgentDetectors');
+      const status = await claudeCodeDetector.detect();
+
+      expect(status.available).toBe(false);
+      // Must not attempt to invoke the unrunnable matches.
+      expect(execMock).not.toHaveBeenCalled();
+      expect(execFileMock).toHaveBeenCalledTimes(1); // just `where`
+    });
+  });
+
+  describe('on macOS / Linux with a Unix-style claude binary', () => {
+    beforeEach(() => {
+      platformMock.mockReturnValue('darwin');
+    });
+
+    it('runs the binary directly via execFile (no shell)', async () => {
+      callExecFile('/usr/local/bin/claude\n');
+      callExecFile('1.2.3 (Claude Code)');
+
+      const { claudeCodeDetector } = await import('../cliAgentDetectors');
+      const status = await claudeCodeDetector.detect();
+
+      expect(status.available).toBe(true);
+      expect(status.path).toBe('/usr/local/bin/claude');
+      expect(execMock).not.toHaveBeenCalled();
+      expect(execFileMock).toHaveBeenCalledTimes(2);
+    });
+  });
+});

apps/desktop/src/main/modules/toolDetectors/cliAgentDetectors.ts

@@ -1,11 +1,13 @@
-import { execFile } from 'node:child_process';
+import { exec, execFile } from 'node:child_process';
 import { platform } from 'node:os';
+import path from 'node:path';
 import { promisify } from 'node:util';
 
 import type { IToolDetector, ToolStatus } from '@/core/infrastructure/ToolDetectorManager';
 import { createCommandDetector } from '@/core/infrastructure/ToolDetectorManager';
 
 const execFilePromise = promisify(execFile);
+const execPromise = promisify(exec);
 
 type HeterogeneousCliAgentType = 'claude-code' | 'codex';
 
@@ -17,17 +19,54 @@ interface ValidatedDetectorOptions {
   validateKeywords: string[];
 }
 
+const isWindows = () => platform() === 'win32';
+
+// Reject anything that could break out of the `cmd /c "<path>" --version`
+// shell line we build for Windows .cmd shims (see `detectValidatedCommand`).
+// User-supplied custom commands flow through here via `detectHeterogeneousCliCommand`.
+const WINDOWS_SHELL_METAS = /[&|;<>^`!"]/;
+
+// Extensions we can actually execute on Windows, in preference order:
+// `.exe` runs directly via `execFile`, `.cmd` / `.bat` runs via `cmd.exe`.
+// `.ps1` and extensionless wrappers (npm sometimes drops a Unix shell script
+// next to the `.cmd` shim) are deliberately excluded — we can't run them.
+const WINDOWS_RUNNABLE_EXTS = ['.exe', '.cmd', '.bat'] as const;
+
+const pickWindowsRunnable = (lines: string[]): string | undefined => {
+  for (const ext of WINDOWS_RUNNABLE_EXTS) {
+    const match = lines.find((line) => line.toLowerCase().endsWith(ext));
+    if (match) return match;
+  }
+  return undefined;
+};
+
 const resolveCommandPath = async (command: string): Promise<string | undefined> => {
   const trimmedCommand = command.trim();
   if (!trimmedCommand) return;
 
-  const whichCommand = platform() === 'win32' ? 'where' : 'which';
+  if (path.isAbsolute(trimmedCommand) || trimmedCommand.includes(path.sep)) {
+    return trimmedCommand;
+  }
+
+  const whichCommand = isWindows() ? 'where' : 'which';
 
   try {
     const { stdout } = await execFilePromise(whichCommand, [trimmedCommand], { timeout: 3000 });
-    return stdout.trim().split(/\r?\n/)[0] || trimmedCommand;
+    const lines = stdout
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter(Boolean);
+    if (lines.length === 0) return undefined;
+
+    // Windows `where` lists every PATHEXT match (e.g. for `codex` npm ships
+    // a Unix shell wrapper alongside `codex.cmd` and `codex.ps1`). Picking
+    // the first line can land us on something we can't execute, so prefer a
+    // runnable extension and bail otherwise.
+    if (isWindows()) return pickWindowsRunnable(lines);
+
+    return lines[0];
   } catch {
-    return trimmedCommand;
+    return undefined;
   }
 };
 
@@ -37,14 +76,27 @@ const detectValidatedCommand = async (
 ): Promise<ToolStatus> => {
   const trimmedCommand = command.trim();
   if (!trimmedCommand) return { available: false };
+  if (isWindows() && WINDOWS_SHELL_METAS.test(trimmedCommand)) return { available: false };
 
   const { validateFlag = '--version', validateKeywords } = options;
 
+  // Resolve via where/which BEFORE invoking. On Windows this is what discovers
+  // npm-installed shims like `claude.cmd` under %APPDATA%\npm — `execFile`
+  // alone won't apply PATHEXT and can't run .cmd files directly.
+  const resolvedPath = await resolveCommandPath(trimmedCommand);
+  if (!resolvedPath) return { available: false };
+
   try {
-    const { stderr, stdout } = await execFilePromise(trimmedCommand, [validateFlag], {
-      timeout: 5000,
-      windowsHide: true,
-    });
+    const needsShell = isWindows() && /\.(?:cmd|bat)$/i.test(resolvedPath);
+    const { stderr, stdout } = needsShell
+      ? await execPromise(`"${resolvedPath}" ${validateFlag}`, {
+          timeout: 5000,
+          windowsHide: true,
+        })
+      : await execFilePromise(resolvedPath, [validateFlag], {
+          timeout: 5000,
+          windowsHide: true,
+        });
     const output = `${stdout}\n${stderr}`.trim();
     const loweredOutput = output.toLowerCase();
 
@@ -54,7 +106,7 @@ const detectValidatedCommand = async (
 
     return {
       available: true,
-      path: await resolveCommandPath(trimmedCommand),
+      path: resolvedPath,
       version: output.split(/\r?\n/)[0],
     };
   } catch {

apps/desktop/src/main/types/store.ts

@@ -19,6 +19,7 @@ export interface ElectronMainStore {
   gatewayEnabled: boolean;
   gatewayUrl: string;
   locale: string;
+  localFileWorkspaceRoots: string[];
   networkProxy: NetworkProxySettings;
   shortcuts: Record<string, string>;
   storagePath: string;

apps/desktop/src/main/utils/mime.ts

@@ -4,22 +4,46 @@ export const getExportMimeType = (filePath: string) => {
   const ext = path.extname(filePath).toLowerCase();
 
   const map: Record<string, string> = {
+    '.bash': 'text/plain; charset=utf-8',
+    '.c': 'text/plain; charset=utf-8',
+    '.cpp': 'text/plain; charset=utf-8',
     '.css': 'text/css; charset=utf-8',
+    '.csv': 'text/csv; charset=utf-8',
+    '.dockerfile': 'text/plain; charset=utf-8',
+    '.fish': 'text/plain; charset=utf-8',
     '.gif': 'image/gif',
+    '.go': 'text/plain; charset=utf-8',
+    '.graphql': 'application/graphql; charset=utf-8',
+    '.h': 'text/plain; charset=utf-8',
+    '.hpp': 'text/plain; charset=utf-8',
     '.html': 'text/html; charset=utf-8',
     '.ico': 'image/x-icon',
     '.jpeg': 'image/jpeg',
     '.jpg': 'image/jpeg',
     '.js': 'application/javascript; charset=utf-8',
+    '.jsx': 'application/javascript; charset=utf-8',
     '.json': 'application/json; charset=utf-8',
+    '.log': 'text/plain; charset=utf-8',
     '.map': 'application/json; charset=utf-8',
+    '.md': 'text/markdown; charset=utf-8',
+    '.mdx': 'text/markdown; charset=utf-8',
     '.mp4': 'video/mp4',
     '.png': 'image/png',
+    '.py': 'text/plain; charset=utf-8',
+    '.rs': 'text/plain; charset=utf-8',
+    '.sh': 'text/plain; charset=utf-8',
     '.svg': 'image/svg+xml; charset=utf-8',
+    '.toml': 'application/toml; charset=utf-8',
+    '.ts': 'text/plain; charset=utf-8',
+    '.tsx': 'text/plain; charset=utf-8',
     '.txt': 'text/plain; charset=utf-8',
+    '.xml': 'application/xml; charset=utf-8',
+    '.yaml': 'application/yaml; charset=utf-8',
+    '.yml': 'application/yaml; charset=utf-8',
     '.webp': 'image/webp',
     '.woff': 'font/woff',
     '.woff2': 'font/woff2',
+    '.zsh': 'text/plain; charset=utf-8',
   };
 
   return map[ext];

changelog/v2.json

@@ -1,4 +1,12 @@
 [
+  {
+    "children": {
+      "fixes": ["hide runtime-only model aliases."],
+      "features": ["set OSS default model to DeepSeek V4 Pro."]
+    },
+    "date": "2026-05-09",
+    "version": "2.1.57"
+  },
   {
     "children": {},
     "date": "2026-05-01",

docs/.cdn.cache.json

@@ -471,5 +471,6 @@
   "https://github.com/user-attachments/assets/fa8fab19-ace2-4f85-8428-a3a0e28845bb": "/blog/assets/2d678631c55369ba7d753c3ffcb73782.webp",
   "https://github.com/user-attachments/assets/facdc83c-e789-4649-8060-7f7a10a1b1dd": "/blog/assets05b20e40c03ced0ec8707fed2e8e0f25.webp",
   "https://github.com/user-attachments/assets/fcdfb9c5-819a-488f-b28d-0857fe861219": "/blog/assets8477415ecec1f37e38ab38ff1217d0a7.webp",
-  "https://github.com/user-attachments/assets/fd60ab55-ead2-4930-ad00-fdf77662f5a0": "/blog/assets276a4e8748e9bd300b30dcd9d0e24980.webp"
-}
+  "https://github.com/user-attachments/assets/fd60ab55-ead2-4930-ad00-fdf77662f5a0": "/blog/assets276a4e8748e9bd300b30dcd9d0e24980.webp",
+  "https://file.rene.wang/task.png": "/blog/assets4aa1732a45832afc780600e6e329860c.webp"
+}

docs/changelog/2026-05-11-agent-tasks-ga.mdx

@@ -0,0 +1,43 @@
+---
+title: Agent Tasks GA & Cloud Heterogeneous Agent
+description: >-
+  Agent Tasks reaches GA with templates, cron, and batch runs; heterogeneous
+  agents now run in the cloud; bot platforms expand to Messenger, Line, and
+  Telegram.
+tags:
+  - Agent Tasks
+  - Heterogeneous Agent
+  - Bots
+  - Models
+---
+
+# Agent Tasks GA & Cloud Heterogeneous Agent
+
+## Tasks
+
+Think of Agent Tasks like Linear, but with agents as your teammates. Create tasks the same way you'd file an issue — title, description, optional template — and assign them to an agent instead of a person. The agent picks up the task, executes the work, posts updates in comments, and moves the status forward (todo → in progress → done) as it makes progress.
+
+Tasks can have subtasks with explicit dependencies, so a parent task can fan out work and the agent will run subtasks in dependency order. Recurring tasks can be wired to a cron schedule, parent assignments can be reshuffled at any time, and every task has its own thread of comments where you and the agent can coordinate.
+
+Learn more in the [Task guide](/docs/usage/getting-started/task).
+
+## Features
+
+- Agent Tasks goes GA: the full task platform with templates, scheduled cron, comment tools, parent reassignment, and dependency-ordered batch subtask runs
+- Nightly self-review: Agent Signal pipeline runs automatic self-review with skill-aware policies and pushes activity into briefs
+- Cloud heterogeneous agents: Claude Code and Codex now execute server-side with persistent sessions that survive Vercel replica restarts
+- `lh hetero exec` CLI: run a standalone heterogeneous agent from the terminal, with multimodal input support across desktop / CLI
+- Claude Code can now pause and ask you a question mid-execution
+- Inline agents in chat: `lobeAgents` markdown tag renders agent profile cards, and a newly created agent shows up as a clickable card
+- Bot platforms expand: Messenger, Line, and Telegram integrations with DM pair policy and per-sender device tool gating
+- New models: Gemini 3.1 Flash-Lite, SiliconCloud model sync, and DeepSeek V4 Pro as the new OSS default
+
+## Improvements and fixes
+
+- Inline document grounding in the KB tool via BM25 search and `docs_*` reads.
+- Daily Brief redesigned with linkable welcome card and a paired input hint; resolved briefs now show a mute icon.
+- Long tool-call parameters now wrap instead of truncating; tool execution time formatted as `Xmin Ys`.
+- Visible divider between queued messages so it's clear which sends are pending.
+- Copy session ID added to the topic dropdown menu.
+- Home sidebar collapse state persists across reloads.
+- Desktop app tray visibility is now a setting.

docs/changelog/2026-05-11-agent-tasks-ga.zh-CN.mdx

@@ -0,0 +1,42 @@
+---
+title: Agent 任务系统 GA 与云端异构 Agent
+description: >-
+  Agent 任务系统正式发布，支持模板、Cron 与批量子任务；异构 Agent 进入云端；Bot 平台新增 Messenger、Line 与
+  Telegram。
+tags:
+  - Agent 任务
+  - 异构 Agent
+  - Bot
+  - 模型
+---
+
+# Agent 任务系统 GA 与云端异构 Agent
+
+## Agent 任务系统
+
+Agent 任务系统的体感类似 Linear，但「队友」是 Agent。你像建 Issue 一样创建任务 —— 标题、描述、可选模板 —— 把它分配给 Agent 而不是某个人。Agent 接到任务后会执行工作、在评论中同步进展，并随着推进更新状态（待办 → 进行中 → 已完成）。
+
+任务支持带显式依赖的子任务，父任务可以拆分工作，Agent 会按依赖顺序运行子任务。周期性任务可以挂接 Cron 计划；父任务的指派可以随时重新调整；每个任务都有自己的评论线，方便你和 Agent 协作沟通。
+
+详见 [任务使用指南](/docs/usage/getting-started/task)。
+
+## 新功能
+
+- Agent 任务系统 GA：完整的任务平台，支持模板、Cron 定时、评论工具、父任务重指派，以及按依赖顺序的批量子任务运行
+- 夜间自审：Agent Signal 流水线自动运行自审，结合技能感知策略并将活动推送到简报
+- 云端异构 Agent：Claude Code 与 Codex 在服务端运行，会话持久化可跨 Vercel 副本恢复
+- `lh hetero exec` CLI：在终端独立运行异构 Agent，桌面端 / CLI 支持多模态输入
+- AskUserQuestion 工具：Claude Code 可在执行过程中暂停并向你提问
+- 聊天内联 Agent：`lobeAgents` Markdown 标签渲染 Agent 卡片，新建的 Agent 会以可点击卡片形式出现
+- Bot 平台扩展：新增 Messenger、Line、Telegram 接入，支持 DM 配对策略与按发送者识别的设备工具网关
+- 新模型：Gemini 3.1 Flash-Lite、SiliconCloud 模型同步，DeepSeek V4 Pro 成为开源版默认模型
+
+## 体验优化与修复
+
+- 知识库工具支持通过 BM25 搜索与 `docs_*` 读取实现内联文档落地。
+- 每日简报改版：欢迎卡片可链接、输入提示成对出现；已处理的简报展示静音图标。
+- 工具调用参数过长时自动换行，不再截断；工具执行时间格式化为 `Xmin Ys`。
+- 排队消息之间新增可见分隔线，方便辨认待发送的内容。
+- 话题下拉菜单新增「复制会话 ID」操作。
+- 首页侧边栏的折叠状态在刷新后会保留。
+- 桌面应用托盘可见性现已纳入设置。

docs/changelog/index.json

@@ -2,6 +2,14 @@
   "$schema": "https://github.com/lobehub/lobe-chat/blob/main/docs/changelog/schema.json",
   "cloud": [],
   "community": [
+    {
+      "image": "/blog/assets4aa1732a45832afc780600e6e329860c.webp",
+      "id": "2026-05-11-agent-tasks-ga",
+      "date": "2026-05-11",
+      "versionRange": [
+        "2.1.57"
+      ]
+    },
     {
       "image": "/blog/assetsb2bf4ddf0a45ff887a993c18cb7ab983.webp",
       "id": "2026-05-04-task-scheduler",

docs/development/database-schema.dbml

@@ -267,6 +267,62 @@ table agent_eval_test_cases {
   }
 }
 
+table agent_operations {
+  id text [pk, not null]
+  user_id text [not null]
+  agent_id text
+  topic_id text
+  thread_id text
+  task_id text
+  chat_group_id text
+  parent_operation_id text
+  status text [not null]
+  completion_reason text
+  started_at "timestamp with time zone"
+  completed_at "timestamp with time zone"
+  step_count integer
+  max_steps integer
+  force_finish boolean
+  interruption jsonb
+  error jsonb
+  total_cost "numeric(20, 6)"
+  currency text [not null, default: 'USD']
+  total_input_tokens integer
+  total_output_tokens integer
+  total_tokens integer
+  llm_calls integer
+  tool_calls integer
+  human_interventions integer
+  processing_time_ms integer
+  human_waiting_time_ms integer
+  cost jsonb
+  usage jsonb
+  cost_limit jsonb
+  model text
+  provider text
+  model_runtime_config jsonb
+  trigger text
+  app_context jsonb
+  trace_s3_key text
+  metadata jsonb [default: `{}`]
+  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_operations_user_id_idx']
+    agent_id [name: 'agent_operations_agent_id_idx']
+    topic_id [name: 'agent_operations_topic_id_idx']
+    thread_id [name: 'agent_operations_thread_id_idx']
+    task_id [name: 'agent_operations_task_id_idx']
+    chat_group_id [name: 'agent_operations_chat_group_id_idx']
+    parent_operation_id [name: 'agent_operations_parent_operation_id_idx']
+    status [name: 'agent_operations_status_idx']
+    (user_id, created_at) [name: 'agent_operations_user_id_created_at_idx']
+    metadata [name: 'agent_operations_metadata_idx']
+  }
+}
+
 table agent_skills {
   id text [pk, not null]
   name text [not null]

docs/usage/channels/qq.zh-CN.mdx

@@ -19,10 +19,10 @@ tags:
 
 ## 连接模式
 
-LobeHub ��持两种 QQ 机器人连接模式：
+LobeHub 支持两种 QQ 机器人连接模式：
 
 - **WebSocket（推荐）** — 持久连接。事件通过 WebSocket 实时推送，无需配置回调地址。这是新机器人的默认模式。
-- **Webhook** — 无状态 HTTP ��调。如果您的机器人已在 QQ 开放平台配置了回调地址且无法切换，请使用此模式。
+- **Webhook** — 无状态 HTTP 回调。如果您的机器人已在 QQ 开放平台配置了回调地址且无法切换，请使用此模式。
 
 > **注意：** 在 QQ 开放平台上，一旦机器人配置了 Webhook 回调地址，就无法切换到 WebSocket 模式。尚未配置回调地址的新机器人应使用 WebSocket 模式。
 
@@ -60,7 +60,7 @@ LobeHub ��持两种 QQ 机器人连接模式：
 <Steps>
   ### 打开渠道设置
 
-  在 LobeHub 中，导航到您的代理设置，然后选择 **渠道** 标签页。��平台列表中点击 **QQ**。
+  在 LobeHub 中，导航到您的代理设置，然后选择 **渠道** 标签页。从平台列表中点击 **QQ**。
 
   ### 输入应用凭证
 
@@ -199,7 +199,7 @@ LobeHub ��持两种 QQ 机器人连接模式：
 
 ## 故障排除
 
-- **机器人无法连接（WebSocket 模式）：** 验证 App ID 和 App Secret 是否正确。确保机��人在 QQ 开放平台上未配置回调地址 — 一旦设置了回调地址，WebSocket 模式将不可用。
+- **机器人无法连接（WebSocket 模式）：** 验证 App ID 和 App Secret 是否正确。确保机器人在 QQ 开放平台上未配置回调地址 — 一旦设置了回调地址，WebSocket 模式将不可用。
 - **回调地址验证失败（Webhook 模式）：** 确保您已在 LobeHub 中保存配置，并正确复制了 URL。LobeHub 会自动处理 Ed25519 验证。
 - **机器人未响应：** 验证 App ID 和 App Secret 是否正确，机器人是否已发布（或您是沙盒测试用户），以及是否订阅了所需的消息事件。
 - **群聊问题：** 确保机器人已被添加到群聊中。@提及机器人以触发响应。

docs/usage/getting-started/task.mdx

@@ -0,0 +1,149 @@
+---
+title: Task
+description: >-
+  Learn how to use Tasks in LobeHub to delegate work to agents. Create tasks, assign them to agents, track status, comment for follow-ups, and run tasks one-off or on a recurring schedule.
+
+
+tags:
+  - Task
+  - Issue Tracker
+  - Agent Assignment
+  - Recurring Task
+  - Workflow
+---
+
+# Task
+
+![](https://hub-apac-1.lobeobjects.space/blog/assets4aa1732a45832afc780600e6e329860c.webp)
+
+**Task** turns a conversation with an agent into trackable work. Instead of chatting in real time and copying results around, you write down what you want, assign it to an agent, and let the agent run it in the background. The agent posts progress, updates the status when it's done, and replies when you leave a comment.
+
+If you've used Linear or GitHub Issues, the mental model is the same — only the assignee is an agent, and the agent actually does the work.
+
+## When to Use a Task
+
+Use a Task when you want an agent to:
+
+- Do work that takes more than a few minutes to finish.
+- Run on a schedule (every morning, every Monday, every month).
+- Report back asynchronously while you focus on something else.
+- Be re-assigned, commented on, or revisited later with full history preserved.
+
+For quick, one-shot questions, stay in the regular chat. For anything you'd otherwise track in a todo list or ticket, create a Task.
+
+## Task Lifecycle
+
+Every task moves through a small set of statuses:
+
+| Status             | Meaning                                                         |
+| ------------------ | --------------------------------------------------------------- |
+| **Backlog**        | Created but not yet picked up by the agent.                     |
+| **In Progress**    | The agent is actively working on the task.                      |
+| **Pending Review** | The agent finished and is waiting for you to verify the result. |
+| **Done**           | You confirmed the result; the task is closed.                   |
+| **Canceled**       | You closed the task before completion.                          |
+
+The agent moves a task from `Backlog` to `In Progress`, then to `Pending Review` when it thinks the work is done. The transition to `Done` is yours to make — see [Reviewing Results](#reviewing-results) below.
+
+## Creating a Task
+
+<Steps>
+  ### Open the Tasks Panel
+
+Click **Tasks** in the left sidebar to open the task list for your workspace.
+
+### Create a New Task
+
+Click **New Task** in the top right. Give it a clear title — the agent uses the title and description to understand what you want.
+
+### Write a Description
+
+Describe the work the same way you'd describe it to a teammate. Include any links, files, or constraints the agent needs. You can paste images and attach Resources just like in a regular chat.
+
+### Assign an Agent
+
+Pick an agent from the **Assignee** dropdown. Choose an agent whose capabilities match the task — for example, the **Research Agent** for reading and summarizing, or a custom agent you've built. You can reassign later if the first agent isn't the right fit.
+
+### Choose a Schedule
+
+Pick **Run once** for a one-off task, or **Repeat** to put it on a schedule. See [One-off vs. Recurring](#one-off-vs-recurring) below.
+
+### Submit
+
+Click **Create**. The task lands in **Backlog**, and the agent picks it up shortly after.
+
+</Steps>
+
+<Callout type="info">
+  You can create a Task directly from any chat message — open the message menu and choose **Turn
+  into Task**. The conversation context is carried over automatically.
+</Callout>
+
+## Working With the Agent
+
+While the task is `In Progress`, the agent posts updates inside the task — every step it takes, every tool call, and every intermediate result. You don't have to watch in real time; open the task whenever you want to see where things stand.
+
+### Reviewing Results
+
+When the agent thinks it's finished, the task moves to `Pending Review`. Open the task detail page to verify the result. You have two options:
+
+- **Confirm Complete** — if the result is good, click the **Confirm Complete** button. The task moves to `Done` and closes out.
+- **Follow up** — if something needs adjustment, leave a comment instead. The agent picks the task back up and continues from where it left off.
+
+A `Pending Review` task never auto-completes; you stay in control of when work is done.
+
+### Comments and Follow-ups
+
+Every task has a comment thread. Use comments to:
+
+- **Clarify** when the agent asks a question mid-run.
+- **Course-correct** if the agent is heading in the wrong direction.
+- **Iterate** at review time — leave a comment like _"Same thing but exclude weekends"_ and the agent reopens the task and tries again.
+
+The agent reads new comments automatically and follows up. There's no separate "send" — your comment is the instruction.
+
+<Callout type="info">
+  If the agent is in the middle of a run, your comment is queued until the next checkpoint so it
+  doesn't interrupt mid-step.
+</Callout>
+
+### Artifacts
+
+Pages the agent creates during execution — research notes, summaries, drafts, anything written to your workspace — are listed in the **Artifacts** section of the task detail page. Open, share, or keep editing them directly from there without leaving the task.
+
+## One-off vs. Recurring
+
+Tasks support two schedule modes.
+
+### Run Once
+
+The default. The agent runs the task immediately, posts a result, and moves it to `Pending Review` for you to confirm. Use this for everything that doesn't need to repeat.
+
+### Repeat
+
+Put the task on a schedule and the agent re-runs it automatically. Each run is appended to the same task as a new entry, so you build up a history you can compare across runs.
+
+Supported intervals:
+
+- **Hourly** — every _N_ hours.
+- **Daily** — at a specific time each day.
+- **Weekly** — on chosen days of the week.
+- **Monthly** — on a specific day of the month.
+- **Custom** — any cron expression.
+
+<Callout type="warning">
+  Recurring tasks consume credits on every run. Check the estimated credit cost shown in the
+  scheduler before saving, and pause the task if you no longer need it.
+</Callout>
+
+You can pause, resume, or change the schedule at any time from the task detail page. Pausing keeps history intact; deleting removes the task and its run history.
+
+## Examples
+
+A few patterns that work well as Tasks:
+
+- **Daily market digest** — a Research Agent that summarizes overnight news every weekday at 8 AM.
+- **Weekly competitor scan** — an agent that visits five competitor sites and flags pricing changes.
+- **One-off deep research** — a long-running task ("compare these 12 vector databases") you check on later.
+- **Recurring data pull** — an agent that queries a database and posts the result on Mondays.
+- **Triage queue** — an inbox-like project where you drop ideas and an agent prepares first-draft answers overnight.

docs/usage/getting-started/task.zh-CN.mdx

@@ -0,0 +1,147 @@
+---
+title: 任务
+description: >-
+  了解如何在 LobeHub 中使用任务（Task）将工作委派给 Agent。创建任务、分配给 Agent、跟踪状态、通过评论进行追问，以及一次性运行或按周期重复执行。
+
+
+tags:
+  - Task
+  - 任务
+  - Issue 跟踪
+  - Agent 分配
+  - 周期任务
+  - 工作流
+---
+
+# 任务
+
+![](https://hub-apac-1.lobeobjects.space/blog/assets4aa1732a45832afc780600e6e329860c.webp)
+
+**任务（Task）** 把你和 Agent 的对话变成可追踪的工作。不必实时聊天再到处复制结果，你可以写下需求、把它指派给一个 Agent，让 Agent 在后台为你完成。Agent 会回报进度、在完成后更新状态，并在你留下评论时继续跟进。
+
+如果你用过 Linear 或 GitHub Issues，思维模型完全一致 —— 只是这里的执行人是 Agent，并且它会真的把活干完。
+
+## 什么时候用任务
+
+当你希望 Agent 做下面这些事情时，就适合开任务：
+
+- 完成耗时超过几分钟的工作。
+- 按计划运行（每天早上、每周一、每月一次）。
+- 异步反馈进度，让你可以同时处理其他事情。
+- 留下完整历史，便于后续重新分配、评论或回溯。
+
+对于一次性的、很快能答完的问题，留在普通对话里就好。任何你原本会记在待办列表或工单里的事情，都建议开一个任务。
+
+## 任务生命周期
+
+每个任务会在一组简单的状态之间流转：
+
+| 状态               | 含义                               |
+| ------------------ | ---------------------------------- |
+| **Backlog**        | 已创建，Agent 还没开始处理。       |
+| **In Progress**    | Agent 正在执行该任务。             |
+| **Pending Review** | Agent 完成了工作，等待你验收结果。 |
+| **Done**           | 你已确认结果，任务关闭。           |
+| **Canceled**       | 在完成前你主动关闭了该任务。       |
+
+Agent 会自动把任务从 `Backlog` 推进到 `In Progress`，再到 `Pending Review`。任务什么时候变成 `Done`，由你决定 —— 详见下方的 [验收结果](#验收结果)。
+
+## 创建任务
+
+<Steps>
+  ### 打开任务面板
+
+点击左侧导航中的 **Tasks**，进入当前工作区的任务列表。
+
+### 新建任务
+
+在右上角点击 **New Task**。给任务起一个清晰的标题 —— Agent 会根据标题和描述来理解你的意图。
+
+### 填写描述
+
+像给同事派活一样描述工作内容，包含必要的链接、文件或限制条件。你可以像在普通对话里一样粘贴图片、附加 Resource。
+
+### 指派 Agent
+
+在 **Assignee** 下拉框中选择合适的 Agent。根据任务挑选能力匹配的 Agent —— 比如 **Research Agent** 适合阅读和总结，或者使用你自己创建的自定义 Agent。后续也可以重新分配。
+
+### 选择运行方式
+
+选择 **Run once** 进行一次性运行，或选择 **Repeat** 设置为周期任务。详见下方的 [一次性任务 vs. 周期任务](#一次性任务-vs-周期任务)。
+
+### 提交
+
+点击 **Create**。任务会进入 **Backlog** 状态，Agent 很快就会开始执行。
+
+</Steps>
+
+<Callout type="info">
+  你也可以从任意聊天消息直接创建任务 —— 打开消息菜单选择 **Turn into Task**，对话上下文会自动带入。
+</Callout>
+
+## 与 Agent 协作
+
+当任务进入 `In Progress` 后，Agent 会在任务内部持续记录进度 —— 每一步动作、每一次工具调用、每一个中间结果。你不需要盯着看，随时打开任务就能看到当前状态。
+
+### 验收结果
+
+当 Agent 认为工作完成后，任务会进入 `Pending Review` 状态。打开任务详情页验收结果，你有两种选择：
+
+- **Confirm Complete** —— 如果结果满意，点击 **Confirm Complete** 按钮。任务进入 `Done` 状态并归档。
+- **追加评论** —— 如果还需要调整，直接留下评论。Agent 会从上次中断的地方继续推进。
+
+`Pending Review` 任务不会自动完成 —— 任务是否结束完全由你决定。
+
+### 评论与追问
+
+每个任务都有一条评论线索，可以用来：
+
+- **澄清**：当 Agent 在执行过程中提问时回复它。
+- **纠偏**：当 Agent 走偏方向时及时拉回。
+- **迭代**：在验收阶段留一条 _"同样的内容但排除周末"_ 这类评论，Agent 会重新打开任务再跑一次。
+
+Agent 会自动读取新评论并继续跟进，不需要单独的 "发送" 动作 —— 你的评论就是新的指令。
+
+<Callout type="info">
+  如果 Agent 正在执行某一步，你的评论会排在下一个检查点处理，避免中途打断它。
+</Callout>
+
+### 产出物（Artifacts）
+
+Agent 在任务执行过程中创建的所有页面 —— 研究笔记、摘要、初稿，以及任何写入工作区的内容 —— 都会列在任务详情页的 **Artifacts** 区域。你可以直接打开、分享或继续编辑，全程不离开任务。
+
+## 一次性任务 vs. 周期任务
+
+任务支持两种运行方式。
+
+### 一次性运行（Run Once）
+
+默认方式。Agent 立即执行任务、提交结果，然后把任务推进到 `Pending Review` 等待你确认。绝大多数不需要重复的需求都用这种。
+
+### 周期运行（Repeat）
+
+把任务设置成定时计划，Agent 会按计划自动重新执行。每次运行的结果都会追加到同一个任务里，形成一份可对比的历史记录。
+
+支持的周期：
+
+- **Hourly** —— 每隔 _N_ 小时。
+- **Daily** —— 每天的指定时间。
+- **Weekly** —— 每周指定的几天。
+- **Monthly** —— 每月指定的一天。
+- **Custom** —— 任意 cron 表达式。
+
+<Callout type="warning">
+  周期任务每次运行都会消耗积分。保存前请查看调度面板上预估的积分开销；如果不再需要，记得及时暂停任务。
+</Callout>
+
+你可以在任务详情页随时暂停、恢复或修改计划。暂停会保留历史；删除会同时清除任务及其所有运行记录。
+
+## 使用示例
+
+下面这些场景特别适合做成任务：
+
+- **每日市场摘要** —— 一个 Research Agent，在每个工作日早上 8 点汇总隔夜资讯。
+- **每周竞品扫描** —— 一个 Agent 访问 5 个竞品网站并提示定价变化。
+- **一次性深度研究** —— 一个长跑任务（"对比这 12 个向量数据库"），你过一会儿再回来看结果。
+- **周期数据拉取** —— 一个 Agent 每周一查询数据库并把结果发到任务里。
+- **想法收件箱** —— 把临时灵感丢进任务列表，让 Agent 在夜里准备好初稿，第二天直接修改。

docs/usage/messenger/discord.mdx

@@ -0,0 +1,105 @@
+---
+title: Use LobeHub on Discord
+description: >-
+  Add the official LobeHub bot to a Discord server, then link your Discord
+  account to LobeHub. Pick a default agent and chat with your AI assistants in
+  Discord DMs — no bot setup required.
+tags:
+  - Messenger
+  - Discord
+  - LobeHub Bot
+  - Account Linking
+  - Server Install
+---
+
+# Use LobeHub on Discord
+
+Discord works in two phases: a **server admin adds** the official LobeHub bot to a Discord server once, and then **each member links** their personal Discord account to LobeHub. Both phases happen from **Settings → Messenger → Discord**.
+
+> The Discord install audit is per-server, but your **personal link is global** to your Discord account — you only link once, and the same link works in every server that has the bot.
+
+## Prerequisites
+
+- A LobeHub account
+- A Discord account
+- For the install step: **Manage Server** permission on the target Discord server
+
+## Phase A — Add the LobeHub bot to a server (server admin)
+
+<Steps>
+  ### Open Settings → Messenger → Discord
+
+  In LobeHub, open **Settings → Messenger** and click the **Discord** card. Click **Connect** in the top-right.
+
+  {/* TODO: screenshot — Discord detail page with empty Connections list and the Connect button */}
+
+  ### Authorise in Discord
+
+  You'll be redirected to Discord's bot-add screen. Pick the server you want to add the bot to and click **Authorise**.
+
+  {/* TODO: screenshot — Discord OAuth consent screen with the server picker */}
+
+  ### Server appears under Connections
+
+  After approval you're redirected back to LobeHub. The server appears as a **server** row in **Connections**.
+
+  {/* TODO: screenshot — Discord detail page showing one connected server row */}
+
+  > **Server already connected by someone else?** LobeHub shows a "Server already connected" notice. You don't need to add the bot again — just DM the LobeHub bot in Discord to link your personal account.
+</Steps>
+
+## Phase B — Link your personal account (each member)
+
+<Steps>
+  ### Open the LobeHub bot in Discord
+
+  Open the LobeHub bot in Discord — the **Open in Discord** button on the Discord detail page (or the pending-link row) takes you straight there.
+
+  {/* TODO: screenshot — Discord detail page with the pending user row + Open in Discord button */}
+
+  ### Send any message
+
+  In the bot DM, send any message to trigger the linking flow. The bot replies with a one-time confirmation link.
+
+  {/* TODO: screenshot — Discord DM with the bot's reply containing the link button */}
+
+  ### Confirm the link in your browser
+
+  Tap the link, sign in to LobeHub if asked, and choose a **default agent**. Every message you DM the LobeHub bot in Discord (across all servers) will route to this agent.
+
+  {/* TODO: screenshot — confirm-link page in LobeHub with the agent picker */}
+
+  Your link appears as a **user** row in **Connections**.
+
+  {/* TODO: screenshot — Discord detail page showing server row + connected user row */}
+</Steps>
+
+## Switching the Active Agent
+
+Two equivalent ways:
+
+- **In Discord** — DM the bot `/agents` and pick a different agent.
+- **In LobeHub** — open **Settings → Messenger → Discord** and use the agent picker on your link row.
+
+The change takes effect on the next message you send.
+
+## Disconnecting
+
+Discord has two distinct disconnect actions, with one important difference from Slack:
+
+| Action                           | Effect                                                                                                                                                                  |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Disconnect** on a *user* row   | Unlinks **your** LobeHub account from your Discord account. The bot stops accepting your DMs until you message it and link again.                                       |
+| **Disconnect** on a *server* row | Removes the install **audit entry only**. **The bot stays in the Discord server** until a server admin manually kicks it. Other people's personal links are unaffected. |
+
+You can re-add the bot to a server (or re-link personally) at any time by repeating the relevant phase.
+
+## Troubleshooting
+
+- **"Server already connected"** — Another LobeHub user already added the bot to this server. DM the LobeHub bot in Discord to link your personal account; you do not need to add the bot again.
+- **Discord install failed (`<reason>`)** — Common reasons: authorisation cancelled, install session expired (re-open the modal and try again), Discord returned incomplete data (retry; if persistent, contact support).
+- **Bot is in the server but doesn't reply** — Check that you have a personal link under **Settings → Messenger → Discord**. The bot only answers users with a confirmed personal link.
+- **Removed the audit row but the bot is still in my server** — That's expected. Disconnecting in LobeHub only removes the audit entry; a Discord server admin must kick the bot from Discord itself.
+- **"This link is already used"** — One-time confirmation links expire after one use. DM the bot again to get a new link.
+- **"This account is already linked"** — Your Discord account is bound to a different LobeHub account. Sign in to that LobeHub account to manage the link, or unlink there before retrying.
+- **"Another Discord account is already linked"** — Your LobeHub account already has a Discord link. Disconnect it in **Settings → Messenger → Discord** before linking a new Discord account.

docs/usage/messenger/discord.zh-CN.mdx

@@ -0,0 +1,104 @@
+---
+title: 在 Discord 使用 LobeHub
+description: >-
+  把官方 LobeHub 机器人加入 Discord 服务器，再把自己的 Discord 账号关联到
+  LobeHub；选择默认 Agent，就能在 Discord DM 里直接和 AI 助手对话，无需自建机器人。
+tags:
+  - Messenger
+  - Discord
+  - LobeHub 机器人
+  - 账号关联
+  - 服务器安装
+---
+
+# 在 Discord 使用 LobeHub
+
+Discord 接入分两步：**服务器管理员把 LobeHub 机器人加入 Discord 服务器**（每个服务器一次），然后 **每位成员把自己的 Discord 账号关联到 LobeHub**。两步都在 **设置 → Messenger → Discord** 里完成。
+
+> Discord 安装审计是按服务器记录的，但你的 **个人关联是全局的**，挂在你的 Discord 账号下 —— 只需关联一次，所有装了机器人的服务器里它都生效。
+
+## 前置条件
+
+- 一个 LobeHub 账号
+- 一个 Discord 账号
+- 安装环节：目标 Discord 服务器的 **Manage Server（管理服务器）** 权限
+
+## 阶段 A —— 把 LobeHub 机器人加入服务器（服务器管理员）
+
+<Steps>
+  ### 打开「设置 → Messenger → Discord」
+
+  在 LobeHub 中打开 **设置 → Messenger**，点击 **Discord** 卡片，再点右上角的 **连接**。
+
+  {/* TODO: 截图 —— Discord 详情页（Connections 列表为空 + Connect 按钮） */}
+
+  ### 在 Discord 中授权
+
+  页面跳转到 Discord 添加机器人页面。选择目标服务器，点击 **Authorise（授权）**。
+
+  {/* TODO: 截图 —— Discord OAuth 授权页（含服务器选择器） */}
+
+  ### 服务器出现在 Connections 列表
+
+  授权成功后跳回 LobeHub。该服务器会以 **server** 行的形式出现在 **Connections** 中。
+
+  {/* TODO: 截图 —— Discord 详情页：已连接的 server 行 */}
+
+  > **服务器已被他人连接？** LobeHub 会提示「Server already connected」。你**不需要**再次添加机器人，只要在 Discord 里私聊 LobeHub 机器人完成个人账号关联即可。
+</Steps>
+
+## 阶段 B —— 关联个人账号（每位成员）
+
+<Steps>
+  ### 在 Discord 中打开 LobeHub 机器人
+
+  在 Discord 中打开 LobeHub 机器人 —— Discord 详情页（或 pending 状态的 user 行）上的 **在 Discord 中打开** 按钮可以直接跳过去。
+
+  {/* TODO: 截图 —— Discord 详情页：pending 的 user 行 + Open in Discord 按钮 */}
+
+  ### 发送任意一条消息
+
+  在机器人 DM 里发送任意一条消息触发关联流程。机器人会回复一个一次性确认链接。
+
+  {/* TODO: 截图 —— Discord DM 中机器人发送的关联按钮消息 */}
+
+  ### 在浏览器里确认关联
+
+  点击链接，必要时登录 LobeHub，然后选择一个 **默认 Agent**。之后你在 Discord 任意服务器里私聊 LobeHub 机器人的每条消息都会路由到这个 Agent。
+
+  {/* TODO: 截图 —— LobeHub 确认关联页面，含 Agent 选择器 */}
+
+  关联完成后会在 **Connections** 里以 **user** 行的形式出现。
+
+  {/* TODO: 截图 —— Discord 详情页：server 行 + 已连接的 user 行 */}
+</Steps>
+
+## 切换接收消息的 Agent
+
+两种等价方式：
+
+- **在 Discord 里** —— 私聊机器人发送 `/agents`，挑一个新的 Agent。
+- **在 LobeHub 里** —— 打开 **设置 → Messenger → Discord**，在你的关联行里使用 Agent 选择器。
+
+切换会对你发送的下一条消息立即生效。
+
+## 断开连接
+
+Discord 也有两种含义不同的断开操作，有一处和 Slack 不同需要特别注意：
+
+| 操作                   | 效果                                                                            |
+| -------------------- | ----------------------------------------------------------------------------- |
+| 在 *user* 行点 **断开**   | 解除 **你自己** 的 LobeHub 账号与 Discord 账号的关联。机器人不再接收你的 DM，直到你再次发消息并完成关联。            |
+| 在 *server* 行点 **断开** | **只移除安装审计记录**。**机器人会继续留在 Discord 服务器里**，直到 Discord 服务器管理员手动把它踢出。其他人的个人关联不受影响。 |
+
+任何时候都可以重新走对应阶段把机器人加回服务器、或重新建立个人关联。
+
+## 故障排查
+
+- **"Server already connected"（服务器已连接）** —— 服务器已被另一位 LobeHub 用户加过机器人。直接在 Discord 私聊 LobeHub 机器人完成个人关联即可，无需重新添加。
+- **Discord 安装失败（`<原因>`）** —— 常见原因：用户取消授权、安装会话过期（重新打开弹窗再试）、Discord 返回的数据不完整（重试；持续失败请联系支持）。
+- **机器人在服务器但不回我消息** —— 检查 **设置 → Messenger → Discord** 下你是否有个人关联。机器人只回复完成了个人关联的用户。
+- **断开了审计行，但机器人还在服务器里** —— 这是预期行为。在 LobeHub 里断开只移除审计记录，需要 Discord 服务器管理员手动从 Discord 那边把机器人踢出。
+- **"This link is already used"** —— 一次性确认链接只能用一次，给机器人再发一条消息获取新链接。
+- **"This account is already linked"** —— 这个 Discord 账号已绑定到另一个 LobeHub 账号。请用那个 LobeHub 账号登录管理，或先在那边解绑。
+- **"Another Discord account is already linked"** —— 你的 LobeHub 账号在 Discord 上已有关联。先在 **设置 → Messenger → Discord** 断开旧关联，再绑定新的 Discord 账号。

docs/usage/messenger/overview.mdx

@@ -0,0 +1,84 @@
+---
+title: Messenger Overview
+description: >-
+  Connect your LobeHub account to the official LobeHub bot on Telegram, Slack,
+  and Discord. Link once, pick an active agent, and chat with your assistants
+  from the chat apps you already use — no bot setup required.
+tags:
+  - Messenger
+  - Telegram
+  - Slack
+  - Discord
+  - Integration
+---
+
+# Messenger
+
+Messenger lets you talk to your LobeHub agents through the **official LobeHub bot** on Telegram, Slack, and Discord. Link your LobeHub account once, choose which agent should answer, and you're done — every message you send to the bot is routed to your agent and replied to in the same conversation.
+
+You manage everything from **Settings → Messenger** in LobeHub.
+
+> \[!NOTE]
+>
+> Messenger is for **personal use** of LobeHub agents from your favourite chat app. If you want to expose an agent to a public community with your own bot identity, set up a [Channel](/docs/usage/channels/overview) on the agent instead.
+
+## Messenger vs. Channels
+
+|               | **Messenger**                                 | **Channels**                                                          |
+| ------------- | --------------------------------------------- | --------------------------------------------------------------------- |
+| Bot identity  | Official **@LobeHub** bot, hosted by LobeHub  | Your own bot, you bring the token                                     |
+| Setup effort  | Tap **Connect**, send `/start`, pick an agent | Create the bot on the platform, paste credentials, configure policies |
+| Scope         | Personal — only you talk to the bot           | Public — anyone in the channel/server can talk to it                  |
+| Active agent  | One per platform link, switchable any time    | One agent per channel binding                                         |
+| Configured at | Settings → Messenger                          | Agent → Channels                                                      |
+
+## Supported Platforms
+
+| Platform     | Setup model                              | Guide                                                     |
+| ------------ | ---------------------------------------- | --------------------------------------------------------- |
+| **Telegram** | Global bot — any account can DM directly | [Use LobeHub on Telegram](/docs/usage/messenger/telegram) |
+| **Slack**    | Per-workspace install + per-member link  | [Use LobeHub on Slack](/docs/usage/messenger/slack)       |
+| **Discord**  | Per-server install + per-member link     | [Use LobeHub on Discord](/docs/usage/messenger/discord)   |
+
+If a platform card does not appear at **Settings → Messenger**, it has not been enabled on your deployment yet — check back later or ask your administrator.
+
+{/* TODO: screenshot — Settings → Messenger landing screen showing the three platform cards */}
+
+## How It Works
+
+1. You **link** your LobeHub account to a platform account through a short OAuth-style flow.
+2. You pick a **default agent** during linking. Every message you send to the bot from that platform routes to this agent.
+3. To switch agents, send `/agents` inside the bot or open **Settings → Messenger** in LobeHub.
+4. **Disconnect** any time from the same screen — inbound messages stop until you `/start` again.
+
+Each LobeHub account can hold one link per platform (Slack also tracks one link per workspace).
+
+## Switching the Active Agent
+
+You can switch the agent that answers your messages at any time:
+
+- **From the bot** — send `/agents` and pick a different agent.
+- **From LobeHub** — open **Settings → Messenger**, select the platform, and use the agent picker on your link row.
+
+Changes take effect immediately for the next message you send.
+
+## Disconnecting
+
+There are two distinct disconnect actions per platform:
+
+| Action                                       | Effect                                                                                                                                                              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Disconnect** on a *user* row               | Unlinks **your** LobeHub account from the platform account. Inbound messages stop until you `/start` again.                                                         |
+| **Disconnect** on a *workspace / server* row | Removes the install audit entry. On Slack, this also freezes the workspace bot for everyone. On Discord, the bot stays in the server until a server admin kicks it. |
+
+You can re-link at any time by repeating the **Connect** flow.
+
+## Common Errors
+
+These messages can appear during linking regardless of platform:
+
+- **"This link is already used"** — The one-time confirm link can only be used once. Return to the bot and send `/start` again to issue a new link.
+- **"This account is already linked"** — The platform account is bound to a different LobeHub account. Sign in to that account to manage it, or unlink it there before retrying.
+- **"Another \<platform> account is already linked"** — Your LobeHub account already has a link on this platform. Disconnect the existing link in **Settings → Messenger** before linking a new one.
+
+For platform-specific issues, see the troubleshooting section on each platform's guide.

docs/usage/messenger/overview.zh-CN.mdx

@@ -0,0 +1,83 @@
+---
+title: Messenger 概览
+description: >-
+  将 LobeHub 账号一键关联到 Telegram、Slack、Discord 上的官方 LobeHub
+  机器人。只需绑定一次，选择默认 Agent，就能在常用聊天工具里直接和你的 AI 助手对话，无需自建机器人。
+tags:
+  - Messenger
+  - Telegram
+  - Slack
+  - Discord
+  - 集成
+---
+
+# Messenger
+
+Messenger 让你通过 **官方 LobeHub 机器人** 在 Telegram、Slack、Discord 上直接和 LobeHub Agent 对话。只需将 LobeHub 账号绑定一次、选好接收消息的 Agent，之后你在机器人里发的每一条消息都会被路由到该 Agent 并在同一会话里回复给你。
+
+所有配置都集中在 LobeHub 的 **设置 → Messenger** 页面。
+
+> \[!NOTE]
+>
+> Messenger 面向 **个人使用** —— 让你在常用聊天工具里方便地用自己的 LobeHub Agent。如果你想以自家机器人身份把某个 Agent 公开给社区使用，请改用 Agent 上的 [渠道（Channels）](/docs/usage/channels/overview)。
+
+## Messenger 与渠道（Channels）的区别
+
+|          | **Messenger**                    | **渠道（Channels）**       |
+| -------- | -------------------------------- | ---------------------- |
+| 机器人身份    | 官方 **@LobeHub** 机器人，由 LobeHub 托管 | 你自己的机器人，需要自带 Token     |
+| 配置成本     | 点 **连接**、发送 `/start`、选一个 Agent   | 在平台上创建机器人、粘贴凭据、配置策略    |
+| 适用场景     | 个人 —— 只有你自己和机器人对话                | 公开 —— 频道 / 服务器里所有人都能对话 |
+| 接收 Agent | 每个平台绑定一个，可随时切换                   | 每个频道绑定一个 Agent         |
+| 配置入口     | 设置 → Messenger                   | Agent → 渠道             |
+
+## 支持的平台
+
+| 平台           | 接入模式                | 文档                                                      |
+| ------------ | ------------------- | ------------------------------------------------------- |
+| **Telegram** | 全局机器人 —— 任意账号都可直接私聊 | [在 Telegram 使用 LobeHub](/docs/usage/messenger/telegram) |
+| **Slack**    | 按工作区安装 + 成员各自关联     | [在 Slack 使用 LobeHub](/docs/usage/messenger/slack)       |
+| **Discord**  | 按服务器安装 + 成员各自关联     | [在 Discord 使用 LobeHub](/docs/usage/messenger/discord)   |
+
+如果 **设置 → Messenger** 页面没有出现某个平台的卡片，说明当前部署尚未启用该平台 —— 请稍后再来，或联系管理员开启。
+
+{/* TODO: 截图 —— 设置 → Messenger 入口页，三个平台卡片 */}
+
+## 工作原理
+
+1. 通过一段类 OAuth 的流程，将你的 LobeHub 账号 **关联** 到平台账号。
+2. 关联时选择一个 **默认 Agent**，之后该平台收到的消息都会路由到这个 Agent。
+3. 切换 Agent：在机器人里发送 `/agents`，或回到 LobeHub 的 **设置 → Messenger**。
+4. 随时可以在同一页面 **断开连接** —— 断开后机器人将不再接收消息，直到你重新 `/start`。
+
+每个 LobeHub 账号在每个平台上可保留一条关联（Slack 还会按工作区各保留一条）。
+
+## 切换接收消息的 Agent
+
+你可以随时切换接收你消息的 Agent：
+
+- **在机器人里** —— 发送 `/agents`，挑一个新的 Agent。
+- **在 LobeHub 里** —— 打开 **设置 → Messenger**，选择平台，在你的关联行里使用 Agent 选择器。
+
+切换会立即对你发送的下一条消息生效。
+
+## 断开连接
+
+每个平台有两种含义不同的断开操作：
+
+| 操作                               | 效果                                                                       |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| 在 *user* 行点 **断开**               | 解除 **你自己** 的 LobeHub 账号与该平台账号的关联。机器人不再接收你的消息，直到你重新 `/start`。             |
+| 在 *workspace / server* 行点 **断开** | 移除安装审计记录。Slack 会因此让该工作区的整个机器人失效；Discord 上机器人会继续留在服务器，直到 Discord 管理员把它踢出。 |
+
+任何时候都可以重新走一次 **连接** 流程恢复关联。
+
+## 通用报错
+
+下面这几条提示在任何平台关联时都可能出现：
+
+- **"This link is already used"（链接已被使用）** —— 一次性确认链接只能使用一次。请回到机器人重新发送 `/start` 获取新链接。
+- **"This account is already linked"（该账号已被关联）** —— 该平台账号已绑定到另一个 LobeHub 账号。请用那个 LobeHub 账号登录管理；或先在那边解绑后再尝试。
+- **"Another \<platform> account is already linked"（另一个平台账号已关联）** —— 你的 LobeHub 账号在该平台上已有关联。先在 **设置 → Messenger** 里断开旧关联，再绑定新账号。
+
+平台特有的报错和细节请见各平台文档的「故障排查」一节。

docs/usage/messenger/slack.mdx

@@ -0,0 +1,102 @@
+---
+title: Use LobeHub on Slack
+description: >-
+  Install the official LobeHub Slack app to your workspace, then link each
+  member's Slack account to LobeHub. Pick a default agent and chat with your AI
+  assistants from Slack DMs — no bot setup required.
+tags:
+  - Messenger
+  - Slack
+  - LobeHub Bot
+  - Account Linking
+  - Workspace Install
+---
+
+# Use LobeHub on Slack
+
+Slack works in two phases: a **workspace admin installs** the official LobeHub Slack app once, and then **each member links** their personal LobeHub account. Both phases happen from **Settings → Messenger → Slack**.
+
+## Prerequisites
+
+- A LobeHub account
+- A Slack workspace
+- For the install step: permission to install Slack apps in that workspace (typically Workspace Admin or a permission granted by one)
+
+## Phase A — Install the LobeHub Slack app (admin, once per workspace)
+
+<Steps>
+  ### Open Settings → Messenger → Slack
+
+  In LobeHub, open **Settings → Messenger** and click the **Slack** card. Click **Connect** in the top-right.
+
+  {/* TODO: screenshot — Slack detail page with empty Connections list and the Connect button */}
+
+  ### Authorise in Slack
+
+  You'll be redirected to Slack's authorisation screen. Pick the workspace you want to install into and click **Allow**.
+
+  {/* TODO: screenshot — Slack OAuth consent screen */}
+
+  ### Workspace appears under Connections
+
+  After approval you're redirected back to LobeHub. The workspace shows up as a **workspace** row in **Connections**, with a status of **Connected**.
+
+  {/* TODO: screenshot — Slack detail page showing one connected workspace row */}
+
+  > **Workspace already connected by someone else?** LobeHub blocks the install and shows a "Workspace already connected" notice. You don't need to install again — just DM **@LobeHub** in Slack to link your personal account. If you want to take over ownership, ask the original installer to disconnect the workspace first.
+</Steps>
+
+## Phase B — Link your personal account (each member)
+
+<Steps>
+  ### Open the LobeHub bot in Slack
+
+  In Slack, open the **Apps** sidebar and find **LobeHub**, or search for `@LobeHub`. Open a DM with the bot.
+
+  {/* TODO: screenshot — Slack apps sidebar with LobeHub highlighted */}
+
+  ### Send any message
+
+  Send any message to the bot to trigger the linking flow. The bot replies with a one-time confirmation link.
+
+  {/* TODO: screenshot — Slack DM showing the bot's "Link Account" reply */}
+
+  ### Confirm the link in your browser
+
+  Tap the link, sign in to LobeHub if asked, and choose a **default agent**. Every message you DM the bot in this workspace will route to this agent.
+
+  {/* TODO: screenshot — confirm-link page in LobeHub with the agent picker */}
+
+  Your link appears as a **user** row under the workspace install in **Connections**.
+
+  {/* TODO: screenshot — Slack detail page showing the workspace row + a connected user row */}
+</Steps>
+
+## Switching the Active Agent
+
+Two equivalent ways:
+
+- **In Slack** — DM the bot `/agents` and pick a different agent.
+- **In LobeHub** — open **Settings → Messenger → Slack** and use the agent picker on your link row.
+
+The change takes effect on the next message you send.
+
+## Disconnecting
+
+Slack has two distinct disconnect actions:
+
+| Action                              | Effect                                                                                                                                                                                                  |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Disconnect** on a *user* row      | Unlinks **your** LobeHub account from your Slack account in this workspace. Your inbound DMs stop until you message the bot and link again.                                                             |
+| **Disconnect** on a *workspace* row | Removes the workspace install. The bot is **frozen for everyone** in that workspace because dispatch is token-gated — existing user links remain on file but pause until the workspace is re-installed. |
+
+You can re-install (workspace) or re-link (personal) at any time by repeating the relevant phase.
+
+## Troubleshooting
+
+- **"Workspace already connected"** — Another LobeHub user already installed the app to this workspace. DM **@LobeHub** to link your personal account; you do not need to install again. To take over ownership, ask the original installer to disconnect first.
+- **Slack install failed (`<reason>`)** — Common reasons: authorisation cancelled, install session expired (re-open the modal and try again), Slack returned incomplete data (retry; if persistent, contact support).
+- **Bot does not reply to your DM** — The workspace install may have been disconnected. Check **Settings → Messenger → Slack** for a workspace row; if missing, ask an admin to re-install.
+- **"This link is already used"** — One-time confirmation links expire after one use. DM the bot again to get a new link.
+- **"This account is already linked"** — Your Slack account is bound to a different LobeHub account. Sign in to that LobeHub account to manage the link, or unlink there before retrying.
+- **"Another Slack account is already linked"** — Your LobeHub account already has a Slack link in this workspace. Disconnect it in **Settings → Messenger → Slack** before linking a new Slack account.

docs/usage/messenger/slack.zh-CN.mdx

@@ -0,0 +1,101 @@
+---
+title: 在 Slack 使用 LobeHub
+description: >-
+  在 Slack 工作区安装官方 LobeHub Slack 应用，再让每位成员各自关联自己的 LobeHub
+  账号；选择默认 Agent，就能在 Slack DM 里直接和 AI 助手对话，无需自建机器人。
+tags:
+  - Messenger
+  - Slack
+  - LobeHub 机器人
+  - 账号关联
+  - 工作区安装
+---
+
+# 在 Slack 使用 LobeHub
+
+Slack 接入分两步：**工作区管理员安装一次** 官方 LobeHub Slack 应用，然后 **每位成员各自关联** 自己的 LobeHub 账号。两步都在 **设置 → Messenger → Slack** 里完成。
+
+## 前置条件
+
+- 一个 LobeHub 账号
+- 一个 Slack 工作区
+- 安装环节：在该工作区里安装 Slack 应用的权限（通常是 Workspace Admin，或由管理员授予的权限）
+
+## 阶段 A —— 安装 LobeHub Slack 应用（管理员，每个工作区一次）
+
+<Steps>
+  ### 打开「设置 → Messenger → Slack」
+
+  在 LobeHub 中打开 **设置 → Messenger**，点击 **Slack** 卡片，再点右上角的 **连接**。
+
+  {/* TODO: 截图 —— Slack 详情页（Connections 列表为空 + Connect 按钮） */}
+
+  ### 在 Slack 中授权
+
+  页面跳转到 Slack 授权界面。选择要安装的目标工作区，点击 **Allow（允许）**。
+
+  {/* TODO: 截图 —— Slack OAuth 授权页 */}
+
+  ### 工作区出现在 Connections 列表
+
+  授权成功后跳回 LobeHub。该工作区会以 **workspace** 行的形式出现在 **Connections** 中，状态为 **已连接 (Connected)**。
+
+  {/* TODO: 截图 —— Slack 详情页：已连接的 workspace 行 */}
+
+  > **工作区已被他人连接？** LobeHub 会阻止安装并提示「Workspace already connected」。你**不需要**重新安装，只要在 Slack 里私聊 **@LobeHub** 完成个人账号关联即可。如果想接管所有权，请请求最初的安装者先断开连接。
+</Steps>
+
+## 阶段 B —— 关联个人账号（每位成员）
+
+<Steps>
+  ### 在 Slack 里打开 LobeHub 机器人
+
+  在 Slack 左侧 **Apps** 栏里找到 **LobeHub**，或直接搜索 `@LobeHub`，打开它的 DM 会话。
+
+  {/* TODO: 截图 —— Slack Apps 栏里高亮 LobeHub */}
+
+  ### 发送任意一条消息
+
+  给机器人发送任意一条消息触发关联流程。机器人会回复一个一次性确认链接。
+
+  {/* TODO: 截图 —— Slack DM 中机器人发送 "Link Account" 按钮 */}
+
+  ### 在浏览器里确认关联
+
+  点击链接，必要时登录 LobeHub，然后选择一个 **默认 Agent**。之后在该工作区私聊机器人的每条消息都会路由到这个 Agent。
+
+  {/* TODO: 截图 —— LobeHub 确认关联页面，含 Agent 选择器 */}
+
+  关联完成后，会在 **Connections** 里以 **user** 行的形式出现在该工作区下方。
+
+  {/* TODO: 截图 —— Slack 详情页：workspace 行 + 一条已连接的 user 行 */}
+</Steps>
+
+## 切换接收消息的 Agent
+
+两种等价方式：
+
+- **在 Slack 里** —— 私聊机器人发送 `/agents`，挑一个新的 Agent。
+- **在 LobeHub 里** —— 打开 **设置 → Messenger → Slack**，在你的关联行里使用 Agent 选择器。
+
+切换会对你发送的下一条消息立即生效。
+
+## 断开连接
+
+Slack 有两种含义不同的断开操作：
+
+| 操作                      | 效果                                                                              |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| 在 *user* 行点 **断开**      | 解除 **你自己** 的 LobeHub 账号与该工作区 Slack 账号的关联。你的 DM 不再被接收，直到你再次给机器人发消息并完成关联。         |
+| 在 *workspace* 行点 **断开** | 移除工作区安装。由于消息分发受 token 控制，这会让该工作区里**所有人的机器人都失效**；现有 user 关联记录还在，但暂停工作直到工作区被重新安装。 |
+
+任何时候都可以重走对应阶段重新安装（工作区）或重新关联（个人）。
+
+## 故障排查
+
+- **"Workspace already connected"（工作区已连接）** —— 工作区已被另一位 LobeHub 用户安装过。私聊 **@LobeHub** 完成个人关联即可，无需重装。如需接管，请请求最初的安装者先断开。
+- **Slack 安装失败（`<原因>`）** —— 常见原因：用户取消授权、安装会话过期（重新打开弹窗再试）、Slack 返回的数据不完整（重试；持续失败请联系支持）。
+- **机器人不回 DM** —— 工作区安装可能已被断开。检查 **设置 → Messenger → Slack** 是否还有 workspace 行；没有就请管理员重新安装。
+- **"This link is already used"** —— 一次性确认链接只能用一次，给机器人再发一条消息获取新链接。
+- **"This account is already linked"** —— 这个 Slack 账号已绑定到另一个 LobeHub 账号。请用那个 LobeHub 账号登录管理，或先在那边解绑。
+- **"Another Slack account is already linked"** —— 你的 LobeHub 账号在该工作区里已有 Slack 关联。先在 **设置 → Messenger → Slack** 断开旧关联，再绑定新的 Slack 账号。

docs/usage/messenger/telegram.mdx

@@ -0,0 +1,77 @@
+---
+title: Use LobeHub on Telegram
+description: >-
+  Link your LobeHub account to the official LobeHub bot on Telegram. Send /start
+  to the bot, pick a default agent, and chat with your AI assistants directly
+  from any Telegram conversation — no bot setup required.
+tags:
+  - Messenger
+  - Telegram
+  - LobeHub Bot
+  - Account Linking
+---
+
+# Use LobeHub on Telegram
+
+Telegram is the simplest Messenger platform: there is one global LobeHub bot, and any Telegram account can DM it. You only need to link your LobeHub account once.
+
+## Prerequisites
+
+- A LobeHub account
+- A Telegram account on any device
+
+## Step 1: Open Settings → Messenger
+
+In LobeHub, open **Settings → Messenger** and click the **Telegram** card.
+
+{/* TODO: screenshot — Settings → Messenger with Telegram card highlighted */}
+
+## Step 2: Click Connect
+
+On the Telegram detail page, click **Connect** in the top-right corner. A modal opens with two ways to reach the bot.
+
+{/* TODO: screenshot — Telegram detail page with empty Connections list and the Connect button */}
+
+## Step 3: Open the bot in Telegram
+
+Either tap **Open in Telegram** in the modal, or scan the QR code with your phone. Telegram opens the official LobeHub bot.
+
+{/* TODO: screenshot — LinkModal showing the Open in Telegram button + QR code */}
+
+## Step 4: Send `/start`
+
+Inside the bot, send the `/start` command. The bot replies with a one-time confirmation link.
+
+{/* TODO: screenshot — Telegram bot conversation showing /start sent and the bot's reply with the Link Account button */}
+
+## Step 5: Confirm the link in your browser
+
+Tap the link in the bot's reply. You'll be taken back to LobeHub. Sign in if asked, then choose a **default agent** — every message you DM the bot from now on will route to this agent.
+
+{/* TODO: screenshot — confirm-link page in LobeHub with the agent picker visible */}
+
+After confirming, the Telegram detail page shows your link as a "user" row with the active agent.
+
+{/* TODO: screenshot — Telegram detail page with one connected user row */}
+
+## Switching the Active Agent
+
+Two equivalent ways:
+
+- **In Telegram** — send `/agents` to the bot and pick a different agent.
+- **In LobeHub** — open **Settings → Messenger → Telegram** and use the agent picker on your link row.
+
+The change takes effect on the next message you send.
+
+## Disconnecting
+
+In **Settings → Messenger → Telegram**, click **Disconnect** on the link row. The bot will stop accepting your messages until you re-link by sending `/start` again.
+
+> Disconnecting from LobeHub does not remove the bot from your Telegram chat list — you can manually delete the chat in Telegram if you no longer want to see it.
+
+## Troubleshooting
+
+- **The bot does not reply to `/start`** — Check that the platform card actually exists in **Settings → Messenger**. If your deployment hasn't enabled Telegram yet, the bot won't respond.
+- **"This link is already used"** — One-time links can only be used once. Send `/start` again to get a new link.
+- **"This account is already linked"** — Your Telegram account is bound to a different LobeHub account. Sign in to that LobeHub account to manage the link, or unlink there first.
+- **"Another Telegram account is already linked"** — Your LobeHub account already has a Telegram link. Disconnect it in **Settings → Messenger → Telegram** before linking a new Telegram account.

docs/usage/messenger/telegram.zh-CN.mdx

@@ -0,0 +1,76 @@
+---
+title: 在 Telegram 使用 LobeHub
+description: >-
+  将 LobeHub 账号关联到 Telegram 上的官方 LobeHub 机器人。给机器人发送
+  /start，选择默认 Agent，就能在任意 Telegram 会话里直接和你的 AI 助手对话，无需自建机器人。
+tags:
+  - Messenger
+  - Telegram
+  - LobeHub 机器人
+  - 账号关联
+---
+
+# 在 Telegram 使用 LobeHub
+
+Telegram 是 Messenger 里最简单的平台：只有一个全局 LobeHub 机器人，任何 Telegram 账号都能直接私聊它。你只需要把自己的 LobeHub 账号绑一次。
+
+## 前置条件
+
+- 一个 LobeHub 账号
+- 任意设备上的 Telegram 账号
+
+## 第 1 步：打开「设置 → Messenger」
+
+在 LobeHub 中打开 **设置 → Messenger**，点击 **Telegram** 卡片。
+
+{/* TODO: 截图 —— 设置 → Messenger 入口页，高亮 Telegram 卡片 */}
+
+## 第 2 步：点击「连接」
+
+在 Telegram 详情页右上角点击 **连接**。弹窗里会给出两种方式打开机器人。
+
+{/* TODO: 截图 —— Telegram 详情页（Connections 列表为空 + Connect 按钮） */}
+
+## 第 3 步：在 Telegram 中打开机器人
+
+在弹窗里点 **在 Telegram 中打开**，或用手机扫描二维码，Telegram 会自动打开官方 LobeHub 机器人。
+
+{/* TODO: 截图 —— LinkModal 弹窗（含 Open in Telegram 按钮和二维码） */}
+
+## 第 4 步：发送 `/start`
+
+在机器人会话里发送 `/start`。机器人会回复一个一次性确认链接。
+
+{/* TODO: 截图 —— Telegram 机器人会话：用户发送 /start，机器人回复带 Link Account 按钮的消息 */}
+
+## 第 5 步：在浏览器里确认关联
+
+点击机器人回复里的链接，会跳回 LobeHub 网页。如未登录请先登录，然后选择一个 **默认 Agent** —— 之后你在该机器人里发的每条消息都会路由到这个 Agent。
+
+{/* TODO: 截图 —— LobeHub 确认关联页面，含 Agent 选择器 */}
+
+确认后，Telegram 详情页会以 “user” 行的形式显示你的关联，旁边可以看到当前 Agent。
+
+{/* TODO: 截图 —— Telegram 详情页：已连接的 user 行 */}
+
+## 切换接收消息的 Agent
+
+两种等价方式：
+
+- **在 Telegram 里** —— 给机器人发送 `/agents`，挑一个新的 Agent。
+- **在 LobeHub 里** —— 打开 **设置 → Messenger → Telegram**，在你的关联行里使用 Agent 选择器。
+
+切换会对你发送的下一条消息立即生效。
+
+## 断开连接
+
+在 **设置 → Messenger → Telegram** 里点关联行上的 **断开**。断开后机器人不再接收你的消息，直到你重新发送 `/start` 关联。
+
+> 在 LobeHub 里断开不会从 Telegram 聊天列表里删掉机器人 —— 如果不想再看到它，可以在 Telegram 里手动删除该会话。
+
+## 故障排查
+
+- **机器人不回复 `/start`** —— 先确认 **设置 → Messenger** 里有 Telegram 卡片。如果当前部署没启用 Telegram，机器人不会响应。
+- **"This link is already used"** —— 一次性链接只能用一次，重新发送 `/start` 获取新链接。
+- **"This account is already linked"** —— 这个 Telegram 账号已绑定到另一个 LobeHub 账号。请用那个 LobeHub 账号登录管理，或先在那边解绑。
+- **"Another Telegram account is already linked"** —— 你的 LobeHub 账号在 Telegram 上已有关联。先在 **设置 → Messenger → Telegram** 断开旧关联，再绑定新的 Telegram 账号。

e2e/src/features/journeys/agent/agent-scroll.feature

@@ -55,3 +55,16 @@ Feature: 发送消息与流式输出期间的视口滚动行为
     And 等待流式响应结束
     And 用户发送一条触发长文输出的消息
     Then 用户消息应固定在聊天列表顶部
+
+  # Regression guard for the spacer-shrink issue: after streaming has ended,
+  # layout/virtual-list offset corrections can emit scroll events without any
+  # wheel, touch, keyboard, or pointer scroll input. Those synthetic negative
+  # offsets must not be treated as user scroll-up intent.
+  @AGENT-SCROLL-006 @P0 @journey
+  Scenario: 非用户触发的上移不应收缩底部补偿区域
+    Given 用户进入 Lobe AI 对话页面
+    When 用户完成一轮用于垫高列表的长回复对话
+    And 用户发送一条触发短回复的消息并等待回复完成
+    And 记录聊天列表底部补偿区域高度
+    And 模拟非用户触发的聊天列表上移 120 像素
+    Then 聊天列表底部补偿区域高度不应收缩