🗃️ feat(database): add page shares schema

🔖 chore(release): release version v2.2.0 [skip ci]
🚀 release: v2.2.0 (#14915 )
2026-06-14 03:30:19 +00:00 · 2026-05-20 16:00:00 +08:00 · 2026-05-18 04:43:53 +00:00 · 2026-05-18 12:41:47 +08:00 · 2026-05-18 11:05:47 +08:00 · 2026-05-18 10:59:13 +08:00
1643 changed files with 119908 additions and 32181 deletions
@@ -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
@@ -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
@@ -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.
@@ -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                                  |

@@ -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.
@@ -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
@@ -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
 ---

@@ -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>;
+};
+```
@@ -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
@@ -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
 ---

@@ -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
 ---

@@ -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
@@ -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
@@ -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
@@ -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
@@ -76,7 +76,9 @@ find_project_pids() {
  port_pid=$(lsof -ti tcp:"$CDP_PORT" -sTCP:LISTEN 2>/dev/null || true)
  pids="$pids $port_pid"

-  echo "$pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' '
+  # `|| true` because `grep -v '^$'` exits 1 when input has no non-empty
+  # lines, which (with pipefail + set -e) silently kills the caller.
+  echo "$pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ' || true
 }

 # Wait for the CDP HTTP endpoint to respond, with a deadline + early bail-out
@@ -146,7 +148,7 @@ do_stop() {
  for pid in $seed_pids; do
    all_pids="$all_pids $(expand_descendants "$pid")"
  done
-  all_pids=$(echo "$all_pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ')
+  all_pids=$(echo "$all_pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ' || true)

  if [ -z "$all_pids" ]; then
    echo "[electron-dev] No project Electron/vite processes found."
@@ -270,10 +272,17 @@ do_start() {
  # Launch in a new session (setsid) so the whole process tree shares a PGID
  # we can later signal in one shot. `setsid bash -c '... exec ...' &` keeps
  # the bash shell as the session leader; its PID is what we save.
-  setsid bash -c "
+  # macOS doesn't ship setsid by default — fall back to plain bash; cleanup
+  # still works via `expand_descendants` walking the process tree.
+  local launch_cmd="
    cd '$PROJECT_ROOT/apps/desktop'
    exec npx electron-vite dev -- --remote-debugging-port=$CDP_PORT
-  " >> "$ELECTRON_LOG" 2>&1 < /dev/null &
+  "
+  if command -v setsid >/dev/null 2>&1; then
+    setsid bash -c "$launch_cmd" >> "$ELECTRON_LOG" 2>&1 < /dev/null &
+  else
+    bash -c "$launch_cmd" >> "$ELECTRON_LOG" 2>&1 < /dev/null &
+  fi
  local launcher_pid=$!
  echo "$launcher_pid" > "$PIDFILE"
  echo "[electron-dev] Launcher PID (session leader): $launcher_pid"
@@ -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
@@ -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
 ---

@@ -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

@@ -1,94 +1,96 @@
 ---
 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)            |
+| Text or icon-text actions built with `Flexbox`/`Text` + `onClick` | Use `Button type={'text'} size={'small'}` with `icon` when needed |
@@ -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
@@ -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.

@@ -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
@@ -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.
@@ -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.
@@ -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
@@ -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
@@ -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

@@ -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 });
+```
@@ -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
@@ -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.
@@ -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,
+    },
+  },
+);
+```
@@ -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.
@@ -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:
@@ -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
@@ -21,6 +21,46 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

+      # Remind contributors when a non-release PR targets `main`.
+      # Day-to-day PRs should target `canary`; `main` is reserved for releases
+      # (see .agents/skills/version-release/SKILL.md). Allowed exceptions:
+      #   - PR title matches `🚀 release: v{x.y.z}` (minor release)
+      #   - head branch matches `hotfix/*` or `release/*` (patch release)
+      - name: Remind contributor if base branch is not canary
+        if: github.event.action == 'opened' && github.event.pull_request.base.ref == 'main'
+        env:
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          GH_TOKEN: ${{ secrets.GH_TOKEN }}
+        run: |
+          if [[ "$HEAD_REF" == hotfix/* ]] || [[ "$HEAD_REF" == release/* ]]; then
+            echo "✅ Release/hotfix branch ($HEAD_REF) -> main is allowed"
+            exit 0
+          fi
+          if [[ "$PR_TITLE" =~ ^🚀[[:space:]]+release: ]]; then
+            echo "✅ Release-titled PR -> main is allowed"
+            exit 0
+          fi
+          echo "⚠️ Non-release PR targets main; posting reminder comment."
+          gh pr comment "$PR_NUMBER" --body "$(cat <<'EOF'
+          👋 Thanks for your contribution!
+
+          This PR currently targets the **`main`** branch, but `main` is reserved for release PRs only. Day-to-day development (features, fixes, refactors, docs, etc.) should target the **`canary`** branch.
+
+          ### How to fix
+
+          On the PR page, click **Edit** next to the title, then change the base branch from `main` to `canary`.
+
+          ### When targeting `main` is allowed
+
+          - PR title starts with `🚀 release: v{x.y.z}` (minor release)
+          - Head branch matches `hotfix/*` or `release/*` (patch release)
+
+          If your PR fits one of these cases, please ignore this message.
+          EOF
+          )"
+
      - name: Check if author is a team member
        id: check-team
        run: |
@@ -2,6 +2,279 @@

 # Changelog

+### [Version 2.2.0](https://github.com/lobehub/lobe-chat/compare/v2.1.59-canary.27...v2.2.0)
+
+<sup>Released on **2026-05-18**</sup>
+
+#### 💄 Styles
+
+- **pricing**: restore DeepSeek models to official pricing.
+
+#### 🐛 Bug Fixes
+
+- **conversation**: animate only the last markdown block + drop clearMessages hotkey.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### Styles
+
+- **pricing**: restore DeepSeek models to official pricing, closes [#14911](https://github.com/lobehub/lobe-chat/issues/14911) ([e566688](https://github.com/lobehub/lobe-chat/commit/e566688))
+
+#### What's fixed
+
+- **conversation**: animate only the last markdown block + drop clearMessages hotkey, closes [#14906](https://github.com/lobehub/lobe-chat/issues/14906) ([469a8e6](https://github.com/lobehub/lobe-chat/commit/469a8e6))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+## [Version 2.1.58](https://github.com/lobehub/lobe-chat/compare/v2.1.57...v2.1.58)
+
+<sup>Released on **2026-05-13**</sup>
+
+#### ✨ Features
+
+- **agent-runtime**: persist agent operations to `agent_operations` table.
+- **misc**: support slack mpim and fix discord dm problem.
+- **database**: add `agent_operations` table.
+- **markdown**: user_feedback card + task card polish + Run now context menu.
+- **documents**: add optimistic create/delete and inline rename for document tree.
+- **devtools**: add dev-only feature flag override panel.
+- **misc**: add service model assignments settings.
+- **misc**: inline skill auth in recommended task templates.
+- **activator**: require activation reason.
+- **agent-signal,server,prompts**: consolidate in self-review implemented.
+- **hetero-agent**: support AskUserQuestion tools for claude code.
+- **bot**: gate device tools by sender identity.
+- **misc**: add user activity business hook.
+- **misc**: add Gemini 3.1 Flash-Lite provider cards.
+- **misc**: home daily brief with linkable welcome + paired input hint.
+- **agent-signal,prompts,database**: self-review now proposal actions to briefs, and automatically execute actions.
+- **misc**: add signOperationJwt with 4h expiry for hetero-agent operations.
+- **misc**: migrate Notion to LobeHub Market.
+- **misc**: Cloud Claude Code V3 — repo picker, GitHub token, sandbox context.
+
+#### 🐛 Bug Fixes
+
+- **hetero-agent**: wire AskUserBridge response events to renderer.
+- **home**: blank user bubble when sending the placeholder hint.
+- **conversation**: prevent synthetic scroll from shrinking spacer.
+- **task-card**: localize task card date independent of dayjs global locale.
+- **web-crawler**: cap response body size to prevent serverless OOM.
+- **desktop**: focus onboarding auth success state.
+- **misc**: Docs image.
+- **desktop**: detect Windows npm .cmd shims for CLI agents (claude/codex/…).
+- **misc**: update Task page placeholder copy.
+- **builtin-tool-task**: expose `lobe-task` and add `setTaskSchedule`.
+- **desktop**: reset pendingLoginMethod on auth failure/cancel paths.
+- **utils**: cap image binary at 3.75MB so base64 payload stays under Anthropic 5MB limit.
+- **tasks**: scheduler, hotkey, comment & TodoList polish.
+- **cli**: remove stale cron entry from generated man page.
+- **misc**: sidebar add agent.
+- **misc**: replace ScrollShadow with ScrollArea to fix React #185 infinite render loop.
+- **heteroFinish**: trigger task lifecycle on cloud sandbox agent completion.
+- **hotkey**: remove redundant onClear to prevent double updateHotkey calls.
+- **misc**: reject inactive OIDC access.
+- **misc**: drop unreachable aihubmix empty-apiKey test.
+- **aihubmix**: use full models endpoint to return complete model list.
+- **onboarding**: skip marketplace on early exit, drop CJK in prompts.
+- **model-runtime**: enrich stream parse errors with provider/model context.
+- **home**: strip markdown links from daily-brief input placeholder.
+- **misc**: consume visual content parts in server runtime.
+- **misc**: store onboarding interests as keys.
+- **hetero-agent**: sync new-step assistant across replicas.
+- **misc**: remove the old cron job from lobehub.
+- **misc**: refresh content baseline from DB on every ingest call.
+- **hetero-agent**: disable Claude Code AskUserQuestion to avoid auto-decline.
+- **local-system**: guard readFile against binary blobs and oversized output.
+- **database,utils,userMemories**: should perfer to use `paradedb.match(...)` instead of hardcoded normalizer.
+- **database**: attach error listeners to Neon/Node pools to prevent Lambda crash.
+- **misc**: gateway client-tool pluginState + drop redundant `Exit code: 0` tail.
+- **gemini**: handle zero cachedContentTokenCount in usage conversion.
+- **misc**: first inject the cloudecc runtime session should use the existingStatus.
+- **misc**: slack connect error & slash commands.
+- **misc**: polish task agent manager.
+- **agent-runtime**: recover malformed tool_call names instead of finishing silently.
+- **misc**: remove signin captcha flow.
+- **misc**: add temporary email auth error locale.
+- **misc**: add bot callback service.
+- **misc**: sanitize sensitive comments and examples from production JS bundle.
+- **misc**: multiple account link.
+
+#### 💄 Styles
+
+- **misc**: use @lobehub/ui built-in HtmlPreview instead of custom component.
+- **misc**: polish desktop header icons, sidebar density, and task menus.
+- **review-panel**: hover revert button to discard per-file working-tree changes.
+- **misc**: standardize header action icon sizes.
+- **tool**: add word wrap toggle to tool arguments display.
+- **nav**: unify ActionIcon sizing and improve TodoList encapsulation.
+- **web-onboarding**: add Render for saveUserQuestion & showAgentMarketplace.
+- **misc**: add `reasoning_effort` support for Grok 4.3.
+- **misc**: increase chat topic title length.
+- **hetero-agent**: read-only SubAgent threads with breadcrumb header and thread switcher.
+- **chat-input**: show skeleton in action bar while config is loading.
+- **home**: add Recommendations module with hetero agent action library.
+- **copyable-label**: wrap long tool-call params instead of truncating.
+- **misc**: format tool execution time as Xmin Ys instead of X.Y min.
+- **misc**: Add new DeepSeek-V4 models.
+- **topic**: add copy session ID to topic dropdown menu.
+- **misc**: use visible divider between queued messages.
+- **intervention**: polish confirmation bar layout.
+- **settings**: remove image avatar from lab input markdown rendering item.
+- **task**: activity card stop run + register /tasks in SPA proxy.
+- **misc**: update auth captcha retry copy.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's improved
+
+- **agent-runtime**: persist agent operations to `agent_operations` table, closes [#14736](https://github.com/lobehub/lobe-chat/issues/14736) ([a772341](https://github.com/lobehub/lobe-chat/commit/a772341))
+- **misc**: support slack mpim and fix discord dm problem, closes [#14733](https://github.com/lobehub/lobe-chat/issues/14733) ([729265a](https://github.com/lobehub/lobe-chat/commit/729265a))
+- **database**: add `agent_operations` table, closes [#14416](https://github.com/lobehub/lobe-chat/issues/14416) ([cb8b616](https://github.com/lobehub/lobe-chat/commit/cb8b616))
+- **markdown**: user_feedback card + task card polish + Run now context menu, closes [#14727](https://github.com/lobehub/lobe-chat/issues/14727) ([79152fa](https://github.com/lobehub/lobe-chat/commit/79152fa))
+- **documents**: add optimistic create/delete and inline rename for document tree, closes [#14714](https://github.com/lobehub/lobe-chat/issues/14714) ([0007984](https://github.com/lobehub/lobe-chat/commit/0007984))
+- **devtools**: add dev-only feature flag override panel, closes [#14565](https://github.com/lobehub/lobe-chat/issues/14565) ([18b1c25](https://github.com/lobehub/lobe-chat/commit/18b1c25))
+- **misc**: add service model assignments settings, closes [#14712](https://github.com/lobehub/lobe-chat/issues/14712) ([eb924ec](https://github.com/lobehub/lobe-chat/commit/eb924ec))
+- **misc**: inline skill auth in recommended task templates, closes [#14676](https://github.com/lobehub/lobe-chat/issues/14676) ([4490e3e](https://github.com/lobehub/lobe-chat/commit/4490e3e))
+- **activator**: require activation reason, closes [#14597](https://github.com/lobehub/lobe-chat/issues/14597) ([5f14b7e](https://github.com/lobehub/lobe-chat/commit/5f14b7e))
+- **agent-signal,server,prompts**: consolidate in self-review implemented, closes [#14657](https://github.com/lobehub/lobe-chat/issues/14657) ([1374fd2](https://github.com/lobehub/lobe-chat/commit/1374fd2))
+- **hetero-agent**: support AskUserQuestion tools for claude code, closes [#14639](https://github.com/lobehub/lobe-chat/issues/14639) ([49c3d7e](https://github.com/lobehub/lobe-chat/commit/49c3d7e))
+- **bot**: gate device tools by sender identity, closes [#14634](https://github.com/lobehub/lobe-chat/issues/14634) ([3c81011](https://github.com/lobehub/lobe-chat/commit/3c81011))
+- **misc**: add user activity business hook, closes [#14601](https://github.com/lobehub/lobe-chat/issues/14601) ([521566b](https://github.com/lobehub/lobe-chat/commit/521566b))
+- **misc**: add Gemini 3.1 Flash-Lite provider cards, closes [#14604](https://github.com/lobehub/lobe-chat/issues/14604) ([9b032f0](https://github.com/lobehub/lobe-chat/commit/9b032f0))
+- **misc**: home daily brief with linkable welcome + paired input hint, closes [#14589](https://github.com/lobehub/lobe-chat/issues/14589) ([12e37f1](https://github.com/lobehub/lobe-chat/commit/12e37f1))
+- **agent-signal,prompts,database**: self-review now proposal actions to briefs, and automatically execute actions, closes [#14583](https://github.com/lobehub/lobe-chat/issues/14583) ([b7a5020](https://github.com/lobehub/lobe-chat/commit/b7a5020))
+- **misc**: add signOperationJwt with 4h expiry for hetero-agent operations, closes [#14586](https://github.com/lobehub/lobe-chat/issues/14586) ([d2c379c](https://github.com/lobehub/lobe-chat/commit/d2c379c))
+- **misc**: migrate Notion to LobeHub Market, closes [#14578](https://github.com/lobehub/lobe-chat/issues/14578) ([f1f2e58](https://github.com/lobehub/lobe-chat/commit/f1f2e58))
+- **misc**: Cloud Claude Code V3 — repo picker, GitHub token, sandbox context, closes [#14568](https://github.com/lobehub/lobe-chat/issues/14568) ([7792f63](https://github.com/lobehub/lobe-chat/commit/7792f63))
+
+#### What's fixed
+
+- **hetero-agent**: wire AskUserBridge response events to renderer, closes [#14732](https://github.com/lobehub/lobe-chat/issues/14732) ([5174c13](https://github.com/lobehub/lobe-chat/commit/5174c13))
+- **home**: blank user bubble when sending the placeholder hint, closes [#14678](https://github.com/lobehub/lobe-chat/issues/14678) ([fc275ca](https://github.com/lobehub/lobe-chat/commit/fc275ca))
+- **conversation**: prevent synthetic scroll from shrinking spacer, closes [#14584](https://github.com/lobehub/lobe-chat/issues/14584) ([217afcf](https://github.com/lobehub/lobe-chat/commit/217afcf))
+- **task-card**: localize task card date independent of dayjs global locale, closes [#14730](https://github.com/lobehub/lobe-chat/issues/14730) ([df0e635](https://github.com/lobehub/lobe-chat/commit/df0e635))
+- **web-crawler**: cap response body size to prevent serverless OOM, closes [#14660](https://github.com/lobehub/lobe-chat/issues/14660) ([2202189](https://github.com/lobehub/lobe-chat/commit/2202189))
+- **desktop**: focus onboarding auth success state, closes [#14694](https://github.com/lobehub/lobe-chat/issues/14694) ([4e4294f](https://github.com/lobehub/lobe-chat/commit/4e4294f))
+- **misc**: Docs image, closes [#14726](https://github.com/lobehub/lobe-chat/issues/14726) ([3a4bd4a](https://github.com/lobehub/lobe-chat/commit/3a4bd4a))
+- **desktop**: detect Windows npm .cmd shims for CLI agents (claude/codex/…), closes [#14720](https://github.com/lobehub/lobe-chat/issues/14720) ([a40fe91](https://github.com/lobehub/lobe-chat/commit/a40fe91))
+- **misc**: update Task page placeholder copy, closes [#14704](https://github.com/lobehub/lobe-chat/issues/14704) ([eea742f](https://github.com/lobehub/lobe-chat/commit/eea742f))
+- **builtin-tool-task**: expose `lobe-task` and add `setTaskSchedule`, closes [#14713](https://github.com/lobehub/lobe-chat/issues/14713) ([5ff4590](https://github.com/lobehub/lobe-chat/commit/5ff4590))
+- **desktop**: reset pendingLoginMethod on auth failure/cancel paths, closes [#14695](https://github.com/lobehub/lobe-chat/issues/14695) ([51cefe0](https://github.com/lobehub/lobe-chat/commit/51cefe0))
+- **utils**: cap image binary at 3.75MB so base64 payload stays under Anthropic 5MB limit, closes [#14711](https://github.com/lobehub/lobe-chat/issues/14711) ([948e48b](https://github.com/lobehub/lobe-chat/commit/948e48b))
+- **tasks**: scheduler, hotkey, comment & TodoList polish, closes [#14707](https://github.com/lobehub/lobe-chat/issues/14707) ([1ae774d](https://github.com/lobehub/lobe-chat/commit/1ae774d))
+- **cli**: remove stale cron entry from generated man page, closes [#14709](https://github.com/lobehub/lobe-chat/issues/14709) ([94e4ea6](https://github.com/lobehub/lobe-chat/commit/94e4ea6))
+- **misc**: sidebar add agent, closes [#14693](https://github.com/lobehub/lobe-chat/issues/14693) ([fdedc96](https://github.com/lobehub/lobe-chat/commit/fdedc96))
+- **misc**: replace ScrollShadow with ScrollArea to fix React #185 infinite render loop, closes [#185](https://github.com/lobehub/lobe-chat/issues/185), closes [#14689](https://github.com/lobehub/lobe-chat/issues/14689) ([7349ad0](https://github.com/lobehub/lobe-chat/commit/7349ad0))
+- **heteroFinish**: trigger task lifecycle on cloud sandbox agent completion, closes [#14681](https://github.com/lobehub/lobe-chat/issues/14681) ([744059c](https://github.com/lobehub/lobe-chat/commit/744059c))
+- **hotkey**: remove redundant onClear to prevent double updateHotkey calls, closes [#14663](https://github.com/lobehub/lobe-chat/issues/14663) ([dfe1932](https://github.com/lobehub/lobe-chat/commit/dfe1932))
+- **misc**: reject inactive OIDC access, closes [#14674](https://github.com/lobehub/lobe-chat/issues/14674) ([b79c5d8](https://github.com/lobehub/lobe-chat/commit/b79c5d8))
+- **misc**: drop unreachable aihubmix empty-apiKey test, closes [#14669](https://github.com/lobehub/lobe-chat/issues/14669) ([b0ee35d](https://github.com/lobehub/lobe-chat/commit/b0ee35d))
+- **aihubmix**: use full models endpoint to return complete model list, closes [#14511](https://github.com/lobehub/lobe-chat/issues/14511) ([f4de472](https://github.com/lobehub/lobe-chat/commit/f4de472))
+- **onboarding**: skip marketplace on early exit, drop CJK in prompts, closes [#14598](https://github.com/lobehub/lobe-chat/issues/14598) ([a9eb904](https://github.com/lobehub/lobe-chat/commit/a9eb904))
+- **model-runtime**: enrich stream parse errors with provider/model context, closes [#14636](https://github.com/lobehub/lobe-chat/issues/14636) ([7daed90](https://github.com/lobehub/lobe-chat/commit/7daed90))
+- **home**: strip markdown links from daily-brief input placeholder, closes [#14635](https://github.com/lobehub/lobe-chat/issues/14635) ([0babdcf](https://github.com/lobehub/lobe-chat/commit/0babdcf))
+- **misc**: consume visual content parts in server runtime, closes [#14637](https://github.com/lobehub/lobe-chat/issues/14637) ([d445a89](https://github.com/lobehub/lobe-chat/commit/d445a89))
+- **misc**: store onboarding interests as keys, closes [#14624](https://github.com/lobehub/lobe-chat/issues/14624) ([9982de3](https://github.com/lobehub/lobe-chat/commit/9982de3))
+- **hetero-agent**: sync new-step assistant across replicas, closes [#14631](https://github.com/lobehub/lobe-chat/issues/14631) ([7675bd9](https://github.com/lobehub/lobe-chat/commit/7675bd9))
+- **misc**: remove the old cron job from lobehub, closes [#14630](https://github.com/lobehub/lobe-chat/issues/14630) ([457d112](https://github.com/lobehub/lobe-chat/commit/457d112))
+- **misc**: refresh content baseline from DB on every ingest call, closes [#14603](https://github.com/lobehub/lobe-chat/issues/14603) ([6595961](https://github.com/lobehub/lobe-chat/commit/6595961))
+- **hetero-agent**: disable Claude Code AskUserQuestion to avoid auto-decline, closes [#14629](https://github.com/lobehub/lobe-chat/issues/14629) ([ae8f9cf](https://github.com/lobehub/lobe-chat/commit/ae8f9cf))
+- **local-system**: guard readFile against binary blobs and oversized output, closes [#14602](https://github.com/lobehub/lobe-chat/issues/14602) ([96165e4](https://github.com/lobehub/lobe-chat/commit/96165e4))
+- **database,utils,userMemories**: should perfer to use `paradedb.match(...)` instead of hardcoded normalizer, closes [#14590](https://github.com/lobehub/lobe-chat/issues/14590) ([38b793f](https://github.com/lobehub/lobe-chat/commit/38b793f))
+- **database**: attach error listeners to Neon/Node pools to prevent Lambda crash, closes [#14606](https://github.com/lobehub/lobe-chat/issues/14606) ([11ec59b](https://github.com/lobehub/lobe-chat/commit/11ec59b))
+- **misc**: gateway client-tool pluginState + drop redundant `Exit code: 0` tail, closes [#14596](https://github.com/lobehub/lobe-chat/issues/14596) ([4bfd434](https://github.com/lobehub/lobe-chat/commit/4bfd434))
+- **gemini**: handle zero cachedContentTokenCount in usage conversion, closes [#14567](https://github.com/lobehub/lobe-chat/issues/14567) ([307cd8e](https://github.com/lobehub/lobe-chat/commit/307cd8e))
+- **misc**: first inject the cloudecc runtime session should use the existingStatus, closes [#14592](https://github.com/lobehub/lobe-chat/issues/14592) ([09c66ff](https://github.com/lobehub/lobe-chat/commit/09c66ff))
+- **misc**: slack connect error & slash commands, closes [#14591](https://github.com/lobehub/lobe-chat/issues/14591) ([8274be0](https://github.com/lobehub/lobe-chat/commit/8274be0))
+- **misc**: polish task agent manager, closes [#14569](https://github.com/lobehub/lobe-chat/issues/14569) ([a02ecbc](https://github.com/lobehub/lobe-chat/commit/a02ecbc))
+- **agent-runtime**: recover malformed tool_call names instead of finishing silently, closes [#14577](https://github.com/lobehub/lobe-chat/issues/14577) ([5f8ec8b](https://github.com/lobehub/lobe-chat/commit/5f8ec8b))
+- **misc**: remove signin captcha flow, closes [#14573](https://github.com/lobehub/lobe-chat/issues/14573) ([181b7eb](https://github.com/lobehub/lobe-chat/commit/181b7eb))
+- **misc**: add temporary email auth error locale, closes [#14564](https://github.com/lobehub/lobe-chat/issues/14564) ([2bdd901](https://github.com/lobehub/lobe-chat/commit/2bdd901))
+- **misc**: add bot callback service, closes [#14570](https://github.com/lobehub/lobe-chat/issues/14570) ([e4b5e52](https://github.com/lobehub/lobe-chat/commit/e4b5e52))
+- **misc**: sanitize sensitive comments and examples from production JS bundle, closes [#14557](https://github.com/lobehub/lobe-chat/issues/14557) ([1a6e07b](https://github.com/lobehub/lobe-chat/commit/1a6e07b))
+- **misc**: multiple account link, closes [#14562](https://github.com/lobehub/lobe-chat/issues/14562) ([760a342](https://github.com/lobehub/lobe-chat/commit/760a342))
+
+#### Styles
+
+- **misc**: use @lobehub/ui built-in HtmlPreview instead of custom component, closes [#14703](https://github.com/lobehub/lobe-chat/issues/14703) ([266d102](https://github.com/lobehub/lobe-chat/commit/266d102))
+- **misc**: polish desktop header icons, sidebar density, and task menus, closes [#14724](https://github.com/lobehub/lobe-chat/issues/14724) ([e56edab](https://github.com/lobehub/lobe-chat/commit/e56edab))
+- **review-panel**: hover revert button to discard per-file working-tree changes, closes [#14716](https://github.com/lobehub/lobe-chat/issues/14716) ([846e648](https://github.com/lobehub/lobe-chat/commit/846e648))
+- **misc**: standardize header action icon sizes, closes [#14717](https://github.com/lobehub/lobe-chat/issues/14717) ([ca9a781](https://github.com/lobehub/lobe-chat/commit/ca9a781))
+- **tool**: add word wrap toggle to tool arguments display, closes [#14706](https://github.com/lobehub/lobe-chat/issues/14706) ([bfa2850](https://github.com/lobehub/lobe-chat/commit/bfa2850))
+- **nav**: unify ActionIcon sizing and improve TodoList encapsulation, closes [#14692](https://github.com/lobehub/lobe-chat/issues/14692) ([877052f](https://github.com/lobehub/lobe-chat/commit/877052f))
+- **web-onboarding**: add Render for saveUserQuestion & showAgentMarketplace, closes [#14667](https://github.com/lobehub/lobe-chat/issues/14667) ([f591f7a](https://github.com/lobehub/lobe-chat/commit/f591f7a))
+- **misc**: add `reasoning_effort` support for Grok 4.3, closes [#14642](https://github.com/lobehub/lobe-chat/issues/14642) ([a1fac45](https://github.com/lobehub/lobe-chat/commit/a1fac45))
+- **misc**: increase chat topic title length, closes [#14659](https://github.com/lobehub/lobe-chat/issues/14659) ([e0ead0c](https://github.com/lobehub/lobe-chat/commit/e0ead0c))
+- **hetero-agent**: read-only SubAgent threads with breadcrumb header and thread switcher, closes [#14658](https://github.com/lobehub/lobe-chat/issues/14658) ([31e9130](https://github.com/lobehub/lobe-chat/commit/31e9130))
+- **chat-input**: show skeleton in action bar while config is loading, closes [#14656](https://github.com/lobehub/lobe-chat/issues/14656) ([84b802c](https://github.com/lobehub/lobe-chat/commit/84b802c))
+- **home**: add Recommendations module with hetero agent action library, closes [#14645](https://github.com/lobehub/lobe-chat/issues/14645) ([e261a6f](https://github.com/lobehub/lobe-chat/commit/e261a6f))
+- **copyable-label**: wrap long tool-call params instead of truncating, closes [#14640](https://github.com/lobehub/lobe-chat/issues/14640) ([60a127b](https://github.com/lobehub/lobe-chat/commit/60a127b))
+- **misc**: format tool execution time as Xmin Ys instead of X.Y min, closes [#14641](https://github.com/lobehub/lobe-chat/issues/14641) ([b85a1ad](https://github.com/lobehub/lobe-chat/commit/b85a1ad))
+- **misc**: Add new DeepSeek-V4 models, closes [#14110](https://github.com/lobehub/lobe-chat/issues/14110) ([867e22a](https://github.com/lobehub/lobe-chat/commit/867e22a))
+- **topic**: add copy session ID to topic dropdown menu, closes [#14595](https://github.com/lobehub/lobe-chat/issues/14595) ([a275009](https://github.com/lobehub/lobe-chat/commit/a275009))
+- **misc**: use visible divider between queued messages, closes [#14593](https://github.com/lobehub/lobe-chat/issues/14593) ([909b1ec](https://github.com/lobehub/lobe-chat/commit/909b1ec))
+- **intervention**: polish confirmation bar layout, closes [#14587](https://github.com/lobehub/lobe-chat/issues/14587) ([5c11130](https://github.com/lobehub/lobe-chat/commit/5c11130))
+- **settings**: remove image avatar from lab input markdown rendering item, closes [#14582](https://github.com/lobehub/lobe-chat/issues/14582) ([d73de25](https://github.com/lobehub/lobe-chat/commit/d73de25))
+- **task**: activity card stop run + register /tasks in SPA proxy, closes [#14559](https://github.com/lobehub/lobe-chat/issues/14559) ([a7cc553](https://github.com/lobehub/lobe-chat/commit/a7cc553))
+- **misc**: update auth captcha retry copy, closes [#14561](https://github.com/lobehub/lobe-chat/issues/14561) ([c208723](https://github.com/lobehub/lobe-chat/commit/c208723))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+## [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>
@@ -89,7 +89,7 @@ RUN set -e && \
    pnpm i && \
    mkdir -p /deps && \
    cd /deps && \
-    pnpm init && \
+    echo '{"name":"deps","private":true}' > package.json && \
    pnpm add pg drizzle-orm

 COPY . .
@@ -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
@@ -1,6 +1,6 @@
 {
  "name": "@lobehub/cli",
-  "version": "0.0.14",
+  "version": "0.0.15",
  "type": "module",
  "bin": {
    "lh": "./dist/index.js",
@@ -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;
@@ -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
@@ -55,7 +55,7 @@ export function registerBriefCommand(program: Command) {
          typeBadge(b.type, b.priority),
          truncate(b.title, 40),
          truncate(b.summary, 50),
-          b.taskId ? pc.dim(b.taskId) : b.cronJobId ? pc.dim(b.cronJobId) : '-',
+          b.taskId ? pc.dim(b.taskId) : '-',
          b.resolvedAt ? pc.green('resolved') : b.readAt ? pc.dim('read') : 'new',
          timeAgo(b.createdAt),
        ]);
@@ -102,7 +102,6 @@ export function registerBriefCommand(program: Command) {
      console.log(`${pc.dim('Type:')} ${b.type}  ${pc.dim('Created:')} ${timeAgo(b.createdAt)}`);
      if (b.agentId) console.log(`${pc.dim('Agent:')} ${b.agentId}`);
      if (b.taskId) console.log(`${pc.dim('Task:')} ${b.taskId}`);
-      if (b.cronJobId) console.log(`${pc.dim('CronJob:')} ${b.cronJobId}`);
      if (b.topicId) console.log(`${pc.dim('Topic:')} ${b.topicId}`);
      console.log(`\n${b.summary}`);

@@ -121,14 +120,14 @@ export function registerBriefCommand(program: Command) {
          for (const a of actions) {
            const cmd =
              a.type === 'comment'
-                ? `lh brief resolve ${b.id} --action ${a.key} -m "内容"`
+                ? `lh brief resolve ${b.id} --action ${a.key} -m "message"`
                : `lh brief resolve ${b.id} --action ${a.key}`;
            console.log(`  ${a.label}  ${pc.dim(cmd)}`);
          }
        } else {
          console.log(pc.dim('Actions:'));
-          console.log(pc.dim(`  lh brief resolve ${b.id}                   # 确认通过`));
-          console.log(pc.dim(`  lh brief resolve ${b.id} --reply "修改意见"  # 反馈修改`));
+          console.log(pc.dim(`  lh brief resolve ${b.id}                   # Approve`));
+          console.log(pc.dim(`  lh brief resolve ${b.id} --reply "revision notes"  # Request revision`));
        }
      } else if ((b as any).resolvedComment) {
        console.log(`${pc.dim('Comment:')} ${(b as any).resolvedComment}`);
@@ -1,172 +0,0 @@
-import { Command } from 'commander';
-import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { registerCronCommand } from './cron';
-
-const { mockTrpcClient } = vi.hoisted(() => ({
-  mockTrpcClient: {
-    agentCronJob: {
-      batchUpdateStatus: { mutate: vi.fn() },
-      create: { mutate: vi.fn() },
-      delete: { mutate: vi.fn() },
-      findById: { query: vi.fn() },
-      getStats: { query: vi.fn() },
-      list: { query: vi.fn() },
-      resetExecutions: { mutate: vi.fn() },
-      update: { mutate: vi.fn() },
-    },
-  },
-}));
-
-const { getTrpcClient: mockGetTrpcClient } = vi.hoisted(() => ({
-  getTrpcClient: vi.fn(),
-}));
-
-vi.mock('../api/client', () => ({ getTrpcClient: mockGetTrpcClient }));
-vi.mock('../utils/logger', () => ({
-  log: { debug: vi.fn(), error: vi.fn(), info: vi.fn(), warn: vi.fn() },
-  setVerbose: vi.fn(),
-}));
-
-describe('cron command', () => {
-  let exitSpy: ReturnType<typeof vi.spyOn>;
-  let consoleSpy: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
-    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
-    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
-    for (const method of Object.values(mockTrpcClient.agentCronJob)) {
-      for (const fn of Object.values(method)) {
-        (fn as ReturnType<typeof vi.fn>).mockReset();
-      }
-    }
-  });
-
-  afterEach(() => {
-    exitSpy.mockRestore();
-    consoleSpy.mockRestore();
-  });
-
-  function createProgram() {
-    const program = new Command();
-    program.exitOverride();
-    registerCronCommand(program);
-    return program;
-  }
-
-  describe('list', () => {
-    it('should list cron jobs', async () => {
-      mockTrpcClient.agentCronJob.list.query.mockResolvedValue({
-        data: [{ enabled: true, id: 'c1', name: 'Test Job', schedule: '* * * * *' }],
-      });
-
-      const program = createProgram();
-      await program.parseAsync(['node', 'test', 'cron', 'list']);
-
-      expect(mockTrpcClient.agentCronJob.list.query).toHaveBeenCalled();
-    });
-
-    it('should filter by agent-id', async () => {
-      mockTrpcClient.agentCronJob.list.query.mockResolvedValue({ data: [] });
-
-      const program = createProgram();
-      await program.parseAsync(['node', 'test', 'cron', 'list', '--agent-id', 'a1']);
-
-      expect(mockTrpcClient.agentCronJob.list.query).toHaveBeenCalledWith(
-        expect.objectContaining({ agentId: 'a1' }),
-      );
-    });
-  });
-
-  describe('view', () => {
-    it('should view cron job details', async () => {
-      mockTrpcClient.agentCronJob.findById.query.mockResolvedValue({
-        data: { enabled: true, id: 'c1', name: 'Test', schedule: '* * * * *' },
-      });
-
-      const program = createProgram();
-      await program.parseAsync(['node', 'test', 'cron', 'view', 'c1']);
-
-      expect(mockTrpcClient.agentCronJob.findById.query).toHaveBeenCalledWith({ id: 'c1' });
-    });
-  });
-
-  describe('create', () => {
-    it('should create a cron job', async () => {
-      mockTrpcClient.agentCronJob.create.mutate.mockResolvedValue({ data: { id: 'c1' } });
-
-      const program = createProgram();
-      await program.parseAsync([
-        'node',
-        'test',
-        'cron',
-        'create',
-        '--agent-id',
-        'a1',
-        '-s',
-        '* * * * *',
-        '-n',
-        'My Job',
-      ]);
-
-      expect(mockTrpcClient.agentCronJob.create.mutate).toHaveBeenCalledWith(
-        expect.objectContaining({ agentId: 'a1', cronPattern: '* * * * *', name: 'My Job' }),
-      );
-    });
-  });
-
-  describe('delete', () => {
-    it('should delete a cron job', async () => {
-      mockTrpcClient.agentCronJob.delete.mutate.mockResolvedValue({});
-
-      const program = createProgram();
-      await program.parseAsync(['node', 'test', 'cron', 'delete', 'c1', '--yes']);
-
-      expect(mockTrpcClient.agentCronJob.delete.mutate).toHaveBeenCalledWith({ id: 'c1' });
-    });
-  });
-
-  describe('toggle', () => {
-    it('should batch enable cron jobs', async () => {
-      mockTrpcClient.agentCronJob.batchUpdateStatus.mutate.mockResolvedValue({
-        data: { updatedCount: 2 },
-      });
-
-      const program = createProgram();
-      await program.parseAsync(['node', 'test', 'cron', 'toggle', 'c1', 'c2', '--enable']);
-
-      expect(mockTrpcClient.agentCronJob.batchUpdateStatus.mutate).toHaveBeenCalledWith({
-        enabled: true,
-        ids: ['c1', 'c2'],
-      });
-    });
-  });
-
-  describe('reset', () => {
-    it('should reset execution count', async () => {
-      mockTrpcClient.agentCronJob.resetExecutions.mutate.mockResolvedValue({});
-
-      const program = createProgram();
-      await program.parseAsync(['node', 'test', 'cron', 'reset', 'c1', '--max', '100']);
-
-      expect(mockTrpcClient.agentCronJob.resetExecutions.mutate).toHaveBeenCalledWith({
-        id: 'c1',
-        newMaxExecutions: 100,
-      });
-    });
-  });
-
-  describe('stats', () => {
-    it('should get stats', async () => {
-      mockTrpcClient.agentCronJob.getStats.query.mockResolvedValue({
-        data: { totalJobs: 5, totalExecutions: 100 },
-      });
-
-      const program = createProgram();
-      await program.parseAsync(['node', 'test', 'cron', 'stats']);
-
-      expect(mockTrpcClient.agentCronJob.getStats.query).toHaveBeenCalled();
-    });
-  });
-});
@@ -1,271 +0,0 @@
-import type { Command } from 'commander';
-import pc from 'picocolors';
-
-import { getTrpcClient } from '../api/client';
-import { confirm, outputJson, printTable, timeAgo, truncate } from '../utils/format';
-import { log } from '../utils/logger';
-
-export function registerCronCommand(program: Command) {
-  const cron = program.command('cron').description('Manage agent cron jobs');
-
-  // ── list ──────────────────────────────────────────────
-
-  cron
-    .command('list')
-    .description('List cron jobs')
-    .option('--agent-id <id>', 'Filter by agent ID')
-    .option('--enabled', 'Only show enabled jobs')
-    .option('--disabled', 'Only show disabled jobs')
-    .option('-L, --limit <n>', 'Page size', '20')
-    .option('--offset <n>', 'Offset', '0')
-    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
-    .action(
-      async (options: {
-        agentId?: string;
-        disabled?: boolean;
-        enabled?: boolean;
-        json?: string | boolean;
-        limit?: string;
-        offset?: string;
-      }) => {
-        const client = await getTrpcClient();
-
-        const input: Record<string, any> = {};
-        if (options.agentId) input.agentId = options.agentId;
-        if (options.enabled) input.enabled = true;
-        if (options.disabled) input.enabled = false;
-        if (options.limit) input.limit = Number.parseInt(options.limit, 10);
-        if (options.offset) input.offset = Number.parseInt(options.offset, 10);
-
-        const result = await client.agentCronJob.list.query(input as any);
-        const items = (result as any).data ?? [];
-
-        if (options.json !== undefined) {
-          const fields = typeof options.json === 'string' ? options.json : undefined;
-          outputJson(items, fields);
-          return;
-        }
-
-        if (items.length === 0) {
-          console.log('No cron jobs found.');
-          return;
-        }
-
-        const rows = items.map((j: any) => [
-          j.id || '',
-          truncate(j.name || '', 30),
-          j.schedule || '',
-          j.enabled ? pc.green('enabled') : pc.dim('disabled'),
-          `${j.executionCount ?? 0}/${j.maxExecutions ?? '∞'}`,
-          j.updatedAt ? timeAgo(j.updatedAt) : '',
-        ]);
-
-        printTable(rows, ['ID', 'NAME', 'SCHEDULE', 'STATUS', 'EXECUTIONS', 'UPDATED']);
-      },
-    );
-
-  // ── view ──────────────────────────────────────────────
-
-  cron
-    .command('view <id>')
-    .description('View cron job details')
-    .option('--json [fields]', 'Output JSON')
-    .action(async (id: string, options: { json?: string | boolean }) => {
-      const client = await getTrpcClient();
-      const result = await client.agentCronJob.findById.query({ id });
-      const job = (result as any).data;
-
-      if (options.json !== undefined) {
-        const fields = typeof options.json === 'string' ? options.json : undefined;
-        outputJson(job, fields);
-        return;
-      }
-
-      if (!job) {
-        log.error('Cron job not found.');
-        process.exit(1);
-      }
-
-      console.log(`${pc.bold('ID:')}          ${job.id}`);
-      console.log(`${pc.bold('Name:')}        ${job.name || ''}`);
-      console.log(`${pc.bold('Agent ID:')}    ${job.agentId || ''}`);
-      console.log(`${pc.bold('Schedule:')}    ${job.schedule || ''}`);
-      console.log(
-        `${pc.bold('Status:')}      ${job.enabled ? pc.green('enabled') : pc.dim('disabled')}`,
-      );
-      console.log(
-        `${pc.bold('Executions:')}  ${job.executionCount ?? 0}/${job.maxExecutions ?? '∞'}`,
-      );
-      if (job.prompt) console.log(`${pc.bold('Prompt:')}      ${truncate(job.prompt, 80)}`);
-      if (job.createdAt) console.log(`${pc.bold('Created:')}     ${timeAgo(job.createdAt)}`);
-      if (job.updatedAt) console.log(`${pc.bold('Updated:')}     ${timeAgo(job.updatedAt)}`);
-    });
-
-  // ── create ────────────────────────────────────────────
-
-  cron
-    .command('create')
-    .description('Create a cron job')
-    .requiredOption('--agent-id <id>', 'Agent ID')
-    .requiredOption('-s, --schedule <cron>', 'Cron schedule expression')
-    .option('-n, --name <name>', 'Job name')
-    .option('-p, --prompt <prompt>', 'Prompt text')
-    .option('--max-executions <n>', 'Maximum number of executions')
-    .option('--json', 'Output JSON')
-    .action(
-      async (options: {
-        agentId: string;
-        json?: boolean;
-        maxExecutions?: string;
-        name?: string;
-        prompt?: string;
-        schedule: string;
-      }) => {
-        const client = await getTrpcClient();
-
-        const input: Record<string, any> = {
-          agentId: options.agentId,
-          cronPattern: options.schedule,
-        };
-        if (options.name) input.name = options.name;
-        if (options.prompt) input.content = options.prompt;
-        if (options.maxExecutions) input.maxExecutions = Number.parseInt(options.maxExecutions, 10);
-
-        const result = await client.agentCronJob.create.mutate(input as any);
-
-        if (options.json) {
-          console.log(JSON.stringify(result, null, 2));
-          return;
-        }
-
-        const data = (result as any).data;
-        console.log(`${pc.green('✓')} Created cron job ${pc.bold(data?.id || '')}`);
-      },
-    );
-
-  // ── edit ───────────────────────────────────────────────
-
-  cron
-    .command('edit <id>')
-    .description('Update a cron job')
-    .option('-n, --name <name>', 'Job name')
-    .option('-s, --schedule <cron>', 'Cron schedule expression')
-    .option('-p, --prompt <prompt>', 'Prompt text')
-    .option('--max-executions <n>', 'Maximum number of executions')
-    .option('--enable', 'Enable the job')
-    .option('--disable', 'Disable the job')
-    .action(
-      async (
-        id: string,
-        options: {
-          disable?: boolean;
-          enable?: boolean;
-          maxExecutions?: string;
-          name?: string;
-          prompt?: string;
-          schedule?: string;
-        },
-      ) => {
-        const data: Record<string, any> = {};
-        if (options.name) data.name = options.name;
-        if (options.schedule) data.cronPattern = options.schedule;
-        if (options.prompt) data.content = options.prompt;
-        if (options.maxExecutions) data.maxExecutions = Number.parseInt(options.maxExecutions, 10);
-        if (options.enable) data.enabled = true;
-        if (options.disable) data.enabled = false;
-
-        if (Object.keys(data).length === 0) {
-          log.error(
-            'No changes specified. Use --name, --schedule, --prompt, --enable, or --disable.',
-          );
-          process.exit(1);
-        }
-
-        const client = await getTrpcClient();
-        await client.agentCronJob.update.mutate({ data, id } as any);
-        console.log(`${pc.green('✓')} Updated cron job ${pc.bold(id)}`);
-      },
-    );
-
-  // ── delete ────────────────────────────────────────────
-
-  cron
-    .command('delete <id>')
-    .description('Delete a cron job')
-    .option('--yes', 'Skip confirmation prompt')
-    .action(async (id: string, options: { yes?: boolean }) => {
-      if (!options.yes) {
-        const confirmed = await confirm('Are you sure you want to delete this cron job?');
-        if (!confirmed) {
-          console.log('Cancelled.');
-          return;
-        }
-      }
-
-      const client = await getTrpcClient();
-      await client.agentCronJob.delete.mutate({ id });
-      console.log(`${pc.green('✓')} Deleted cron job ${pc.bold(id)}`);
-    });
-
-  // ── toggle ────────────────────────────────────────────
-
-  cron
-    .command('toggle <ids...>')
-    .description('Batch enable or disable cron jobs')
-    .option('--enable', 'Enable the jobs')
-    .option('--disable', 'Disable the jobs')
-    .action(async (ids: string[], options: { disable?: boolean; enable?: boolean }) => {
-      if (!options.enable && !options.disable) {
-        log.error('Specify --enable or --disable.');
-        process.exit(1);
-      }
-
-      const enabled = !!options.enable;
-      const client = await getTrpcClient();
-      const result = await client.agentCronJob.batchUpdateStatus.mutate({ enabled, ids });
-      const count = (result as any).data?.updatedCount ?? ids.length;
-      console.log(`${pc.green('✓')} ${enabled ? 'Enabled' : 'Disabled'} ${count} cron job(s)`);
-    });
-
-  // ── reset ─────────────────────────────────────────────
-
-  cron
-    .command('reset <id>')
-    .description('Reset execution count for a cron job')
-    .option('--max <n>', 'Set new max executions')
-    .action(async (id: string, options: { max?: string }) => {
-      const client = await getTrpcClient();
-
-      const input: Record<string, any> = { id };
-      if (options.max) input.newMaxExecutions = Number.parseInt(options.max, 10);
-
-      await client.agentCronJob.resetExecutions.mutate(input as any);
-      console.log(`${pc.green('✓')} Reset execution count for ${pc.bold(id)}`);
-    });
-
-  // ── stats ─────────────────────────────────────────────
-
-  cron
-    .command('stats')
-    .description('Get cron job execution statistics')
-    .option('--json', 'Output JSON')
-    .action(async (options: { json?: boolean }) => {
-      const client = await getTrpcClient();
-      const result = await client.agentCronJob.getStats.query();
-      const stats = (result as any).data;
-
-      if (options.json) {
-        console.log(JSON.stringify(stats, null, 2));
-        return;
-      }
-
-      if (!stats) {
-        console.log('No statistics available.');
-        return;
-      }
-
-      for (const [key, value] of Object.entries(stats as Record<string, any>)) {
-        console.log(`${pc.bold(key + ':')} ${value}`);
-      }
-    });
-}
@@ -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;
@@ -145,7 +145,7 @@ export function registerReviewCommands(task: Command) {

  rc.command('add <id>')
    .description('Add a review rubric')
-    .requiredOption('-n, --name <name>', 'Rubric name (e.g. "内容准确性")')
+    .requiredOption('-n, --name <name>', 'Rubric name (e.g. "Content Accuracy")')
    .option('--type <type>', 'Rubric type (default: llm-rubric)', 'llm-rubric')
    .option('-t, --threshold <n>', 'Pass threshold 0-100 (converted to 0-1)')
    .option('-d, --description <text>', 'Criteria description (for llm-rubric type)')
@@ -8,7 +8,6 @@ import { registerBotCommand } from './commands/bot';
 import { registerCompletionCommand } from './commands/completion';
 import { registerConfigCommand } from './commands/config';
 import { registerConnectCommand } from './commands/connect';
-import { registerCronCommand } from './commands/cron';
 import { registerDeviceCommand } from './commands/device';
 import { registerDocCommand } from './commands/doc';
 import { registerEvalCommand } from './commands/eval';
@@ -60,7 +59,6 @@ export function createProgram() {
  registerAgentCommand(program);
  registerAgentGroupCommand(program);
  registerBotCommand(program);
-  registerCronCommand(program);
  registerGenerateCommand(program);
  registerFileCommand(program);
  registerHeteroCommand(program);
@@ -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: {
@@ -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,17 +118,45 @@ 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',
        ],
        output: {
-          // Prevent debug package from being bundled into index.js to avoid side-effect pollution
+          // Prevent shared deps from being bundled into index.js to avoid side-effect pollution.
+          // Pattern: when a module is imported by both the main bundle (statically) and a
+          // dynamic-import chunk (lazy loader), rolldown places it in main and makes the
+          // chunk back-reference `require("./index.js")`. Electron's main entry isn't in
+          // Node's CJS cache, so that require recompiles `index.js` from scratch — which
+          // re-runs `new App()` at top-level and triggers `protocol.registerSchemesAsPrivileged`
+          // *after* the app is ready → throw.
+          //
+          // Same root cause as the original `debug` regression fixed in #11827. Isolate
+          // each shared module into its own vendor chunk so both ends reference the vendor
+          // chunk instead of back-referencing main.
          manualChunks(id) {
            if (id.includes('node_modules/debug')) {
              return 'vendor-debug';
            }

+            // Small text/binary detection utilities in file-loaders/utils. Imported by
+            // main (via `sniffBinaryFile`) and potentially by lazy loader chunks.
+            // Explicitly enumerated to avoid catching `parser-utils.ts`, which pulls in
+            // xmldom / yauzl / concat-stream — those belong in docx/pptx loader chunks.
+            if (
+              /packages\/file-loaders\/src\/utils\/(?:detectUtf16|isBinaryContent|isTextReadableFile)\.ts$/.test(
+                id,
+              )
+            ) {
+              return 'vendor-file-loaders-utils';
+            }
+
+            // jszip — imported by main (via some static path) AND by the docx loader chunk.
+            // Without this, reading a .docx file throws the protocol re-init error.
+            if (id.includes('node_modules/jszip')) {
+              return 'vendor-jszip';
+            }
+
            // Split i18n json resources by namespace (ns), not by locale.
            // Example: ".../resources/locales/zh-CN/common.json?import" -> "locales-common"
            const normalizedId = id.replaceAll('\\', '/').split('?')[0];
@@ -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');
+}
@@ -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);
+    }
+  }
+}
@@ -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');
 }
@@ -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"
  },
@@ -7,18 +7,18 @@ import { entryLocaleJsonFilepath, i18nConfig, localeDir, srcDefaultLocales } fro
 import { tagWhite, writeJSON } from './utils';

 export const genDefaultLocale = () => {
-  consola.info(`默认语言为 ${i18nConfig.entryLocale}...`);
+  consola.info(`Default locale: ${i18nConfig.entryLocale}...`);

  // Ensure entry locale directory exists
  const entryLocaleDir = localeDir(i18nConfig.entryLocale);
  if (!existsSync(entryLocaleDir)) {
    mkdirSync(entryLocaleDir, { recursive: true });
-    consola.info(`创建目录：${entryLocaleDir}`);
+    consola.info(`Creating directory: ${entryLocaleDir}`);
  }

  const resources = require(srcDefaultLocales);
  const data = Object.entries(resources.default);
-  consola.start(`生成默认语言 JSON 文件，发现 ${data.length} 个命名空间...`);
+  consola.start(`Generating default locale JSON files, found ${data.length} namespaces...`);

  for (const [ns, value] of data) {
    const filepath = entryLocaleJsonFilepath(`${ns}.json`);
@@ -13,7 +13,7 @@ import {
 import { readJSON, tagWhite, writeJSON } from './utils';

 export const genDiff = () => {
-  consola.start(`对比开发与生产环境中的本地化文件...`);
+  consola.start(`Comparing localization files between dev and prod environments...`);

  const resources = require(srcDefaultLocales);
  const data = Object.entries(resources.default);
@@ -21,7 +21,7 @@ export const genDiff = () => {
  for (const [ns, devJSON] of data) {
    const filepath = entryLocaleJsonFilepath(`${ns}.json`);
    if (!existsSync(filepath)) {
-      consola.info(`文件不存在，跳过：${filepath}`);
+      consola.info(`File does not exist, skipping: ${filepath}`);
      continue;
    }

@@ -50,7 +50,7 @@ export const genDiff = () => {
    }

    if (clearLocals.length > 0) {
-      consola.info('清理了以下语言的过期项目：', clearLocals.join(', '));
+      consola.info('Cleaned up stale entries for the following locales:', clearLocals.join(', '));
    }
    consola.success(tagWhite(ns), colors.gray(filepath));
  }
@@ -21,15 +21,15 @@ const run = async () => {
  ensureLocalesDirs();

  // Diff analysis
-  split('差异分析');
+  split('Diff Analysis');
  genDiff();

  // Generate default locale files
-  split('生成默认语言文件');
+  split('Generate Default Locale Files');
  genDefaultLocale();

  // Generate i18n files
-  split('生成国际化文件');
+  split('Generate i18n Files');
 };

 run();
@@ -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';
@@ -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,
@@ -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 };
+    }
+  }
 }
@@ -1,7 +1,9 @@
 import type { ChildProcess } from 'node:child_process';
 import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { access, appendFile, mkdir, writeFile } from 'node:fs/promises';
+import { unlinkSync } from 'node:fs';
+import { access, appendFile, mkdir, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 import type { Readable, Writable } from 'node:stream';
 import { finished as streamFinished } from 'node:stream/promises';
@@ -14,17 +16,23 @@ import {
  CODEX_CLI_INSTALL_DOCS_URL,
  HeterogeneousAgentSessionErrorCode,
 } from '@lobechat/electron-client-ipc';
+import type { AskUserBridge } from '@lobechat/heterogeneous-agents/askUser';
+import { AskUserMcpServer } from '@lobechat/heterogeneous-agents/askUser';
 import type { AgentContentBlock } from '@lobechat/heterogeneous-agents/spawn';
 import {
  AgentStreamPipeline,
  buildAgentInput,
  materializeImageToPath,
  normalizeImage,
+  resolveCliSpawnPlan,
 } from '@lobechat/heterogeneous-agents/spawn';
 import { app as electronApp, BrowserWindow } from 'electron';

 import { getHeterogeneousAgentDriver } from '@/modules/heterogeneousAgent';
-import type { HeterogeneousAgentImageAttachment } from '@/modules/heterogeneousAgent/types';
+import type {
+  HeterogeneousAgentBuildPlan,
+  HeterogeneousAgentImageAttachment,
+} from '@/modules/heterogeneousAgent/types';
 import { buildProxyEnv } from '@/modules/networkProxy/envBuilder';
 import { detectHeterogeneousCliCommand } from '@/modules/toolDetectors';
 import { createLogger } from '@/utils/logger';
@@ -99,6 +107,18 @@ interface CancelSessionParams {
  sessionId: string;
 }

+interface SubmitInterventionParams {
+  cancelled?: boolean;
+  /** When set, signals user-cancelled or timeout — the bridge resolves with isError. */
+  cancelReason?: 'timeout' | 'user_cancelled';
+  /** Operation id stamped on the request the renderer is responding to. */
+  operationId: string;
+  /** Structured user answer; ignored when `cancelled` is true. */
+  result?: unknown;
+  /** Correlation key carried on the original `agent_intervention_request`. */
+  toolCallId: string;
+}
+
 interface StopSessionParams {
  sessionId: string;
 }
@@ -150,10 +170,28 @@ interface CliTraceSession {
 *
 * Lifecycle: startSession → sendPrompt → (heteroAgentEvent broadcasts) → stopSession
 */
+interface InterventionSlot {
+  bridge: AskUserBridge;
+  /** Resolves once bridge.events() iterator ends (after `cancelAll`). */
+  pumpDone: Promise<void>;
+  /** Path to the per-op temp `mcp.json` we wrote for `--mcp-config`. */
+  tmpConfigPath: string;
+}
+
 export default class HeterogeneousAgentCtr extends ControllerModule {
  static override readonly groupName = 'heterogeneousAgent';

  private sessions = new Map<string, AgentSession>();
+  /**
+   * Per-operation AskUserQuestion bridge state. Keyed by `operationId` so the
+   * `submitIntervention` IPC can route an answer to the right pending MCP
+   * handler regardless of which `sessionId` it belongs to (one session can
+   * fire many ops over its lifetime).
+   */
+  private opIdToIntervention = new Map<string, InterventionSlot>();
+  /** Lazy single MCP server, started on first claude-code prompt. */
+  private askUserMcpServer?: AskUserMcpServer;
+  private askUserMcpStartPromise?: Promise<AskUserMcpServer>;

  private resolveSessionCommand(session: AgentSession): string {
    const resolvedCommand = session.command.trim();
@@ -567,6 +605,92 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
    }
  }

+  // ─── AskUserQuestion MCP server (LOBE-8725) ───
+
+  /**
+   * Lazy single-instance MCP server for CC's AskUserQuestion replacement.
+   * First claude-code prompt triggers `start()`; subsequent prompts reuse
+   * the same listener. Concurrent first-callers de-dupe via the in-flight
+   * promise so we don't bind two ports.
+   */
+  private async ensureAskUserMcpServerStarted(): Promise<AskUserMcpServer> {
+    if (this.askUserMcpServer) return this.askUserMcpServer;
+    if (!this.askUserMcpStartPromise) {
+      this.askUserMcpStartPromise = (async () => {
+        const server = new AskUserMcpServer();
+        await server.start();
+        this.askUserMcpServer = server;
+        logger.info('AskUserQuestion MCP server started:', server.url);
+        return server;
+      })().catch((err) => {
+        // Reset so a later sendPrompt can retry; surface the error.
+        this.askUserMcpStartPromise = undefined;
+        logger.error('Failed to start AskUserQuestion MCP server:', err);
+        throw err;
+      });
+    }
+    return this.askUserMcpStartPromise;
+  }
+
+  /**
+   * Register a per-op AskUserQuestion bridge, write its temp `mcp.json`,
+   * and start pumping the bridge's outbound events into the regular
+   * `heteroAgentEvent` broadcast. Caller must invoke the returned cleanup
+   * after the spawn finishes (success, error, or cancel) to remove the
+   * temp file and tear down the bridge.
+   *
+   * Pump errors are logged but never thrown — they don't fail the spawn.
+   */
+  private async setupInterventionForOp(
+    operationId: string,
+    sessionId: string,
+  ): Promise<{ cleanup: () => Promise<void>; tmpConfigPath: string }> {
+    const server = await this.ensureAskUserMcpServerStarted();
+    const bridge = server.registerOperation(operationId);
+    const tmpConfigPath = path.join(os.tmpdir(), `lobe-cc-mcp-${operationId}.json`);
+
+    // `alwaysLoad: true` is the undocumented CC flag that promotes our
+    // server's tool out of the deferred set so the model calls it directly
+    // (no ToolSearch hop). See LOBE-8725 spike notes — falls back to the
+    // 2-hop ToolSearch path if a future CC drops the flag, no breakage.
+    const config = {
+      mcpServers: {
+        lobe_cc: {
+          alwaysLoad: true,
+          type: 'http' as const,
+          url: server.urlForOperation(operationId),
+        },
+      },
+    };
+    await writeFile(tmpConfigPath, JSON.stringify(config), 'utf8');
+
+    // Pump bridge.events() into the `heteroAgentEvent` broadcast. The
+    // iterator only ends after `cancelAll()`, so `pumpDone` resolves at
+    // cleanup time and gates teardown.
+    const pumpDone = (async () => {
+      for await (const event of bridge.events()) {
+        this.broadcast('heteroAgentEvent', { event, sessionId });
+      }
+    })().catch((err) => {
+      logger.warn('AskUserQuestion bridge pump error:', err);
+    });
+
+    this.opIdToIntervention.set(operationId, { bridge, pumpDone, tmpConfigPath });
+
+    const cleanup = async () => {
+      // Unregistering on the server cancels all bridge pendings AND closes
+      // the events iterator (cancelAll fires from within unregisterOperation).
+      this.askUserMcpServer?.unregisterOperation(operationId);
+      await pumpDone;
+      this.opIdToIntervention.delete(operationId);
+      await unlink(tmpConfigPath).catch(() => {
+        /* file may already be gone if app crashed mid-prompt */
+      });
+    };
+
+    return { cleanup, tmpConfigPath };
+  }
+
  // ─── File cache ───

  private get fileCacheDir(): string {
@@ -697,185 +821,261 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
      throw new Error(preflightError.message);
    }

-    const driver = getHeterogeneousAgentDriver(session.agentType);
-    const spawnPlan = await driver.buildSpawnPlan({
-      args: session.args,
-      helpers: {
-        buildClaudeStreamJsonInput: (prompt, imageList) =>
-          this.buildStreamJsonInput(prompt, imageList),
-        resolveCliImagePaths: (imageList) => this.resolveCliImagePaths(imageList),
-      },
-      imageList: params.imageList ?? [],
-      prompt: params.prompt,
-      resumeSessionId: session.agentSessionId,
-    });
-    const useStdin = spawnPlan.stdinPayload !== undefined;
-    const cliArgs = spawnPlan.args;
+    // Stand up the AskUserQuestion MCP bridge for claude-code prompts BEFORE
+    // building the spawn plan so the driver can wire the temp config path
+    // into `--mcp-config`. Codex / future agents skip this entirely.
+    const intervention =
+      session.agentType === 'claude-code'
+        ? await this.setupInterventionForOp(params.operationId, session.sessionId).catch((err) => {
+            logger.warn('Failed to set up AskUserQuestion bridge — proceeding without it:', err);
+            return undefined;
+          })
+        : undefined;

-    // Fall back to the user's Desktop so the process never inherits
-    // the Electron parent's cwd (which is `/` when launched from Finder).
-    const cwd = session.cwd || electronApp.getPath('desktop');
-    const traceSession = await this.createCliTraceSession({
-      cliArgs,
-      cwd,
-      imageList: params.imageList ?? [],
-      session,
-      stdinPayload: spawnPlan.stdinPayload,
-    });
-
-    return new Promise<void>((resolve, reject) => {
-      logger.info('Spawning agent:', session.command, cliArgs.join(' '), `(cwd: ${cwd})`);
-
-      // `detached: true` on Unix puts the child in a new process group so we
-      // can SIGINT/SIGKILL the whole tree (claude + any tool subprocesses)
-      // via `process.kill(-pid, sig)` on cancel. Without this, SIGINT to just
-      // the claude binary can leave bash/grep/etc. tool children running and
-      // the CLI hung waiting on them. Windows has different semantics — use
-      // taskkill /T /F there; no detached flag needed.
-      // Forward the user's proxy settings to the CLI. The main-process undici
-      // dispatcher doesn't reach child processes — they need env vars.
-      const proxyEnv = buildProxyEnv(this.app.storeManager.get('networkProxy'));
-
-      const proc = spawn(session.command, cliArgs, {
-        cwd,
-        detached: process.platform !== 'win32',
-        env: { ...process.env, ...proxyEnv, ...session.env },
-        stdio: [useStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+    let spawnPlan;
+    let traceSession;
+    let cwd: string;
+    try {
+      const driver = getHeterogeneousAgentDriver(session.agentType);
+      spawnPlan = await driver.buildSpawnPlan({
+        args: session.args,
+        helpers: {
+          buildClaudeStreamJsonInput: (prompt, imageList) =>
+            this.buildStreamJsonInput(prompt, imageList),
+          resolveCliImagePaths: (imageList) => this.resolveCliImagePaths(imageList),
+        },
+        imageList: params.imageList ?? [],
+        mcpConfigPath: intervention?.tmpConfigPath,
+        prompt: params.prompt,
+        resumeSessionId: session.agentSessionId,
      });

-      // In stdin mode, write the prepared payload and close stdin.
-      if (useStdin && spawnPlan.stdinPayload !== undefined && proc.stdin) {
-        void this.writeCliTraceFile(traceSession, 'stdin.txt', spawnPlan.stdinPayload);
-        const stdin = proc.stdin as Writable;
-        stdin.write(spawnPlan.stdinPayload, () => {
-          stdin.end();
+      // Fall back to the user's Desktop so the process never inherits
+      // the Electron parent's cwd (which is `/` when launched from Finder).
+      cwd = session.cwd || electronApp.getPath('desktop');
+      traceSession = await this.createCliTraceSession({
+        cliArgs: spawnPlan.args,
+        cwd,
+        imageList: params.imageList ?? [],
+        session,
+        stdinPayload: spawnPlan.stdinPayload,
+      });
+    } catch (err) {
+      // We never made it to spawn — the `proc.on('exit')` cleanup path
+      // won't run, so tear the intervention bridge down right here.
+      if (intervention) {
+        await intervention.cleanup().catch((cleanupErr) => {
+          logger.warn('AskUserQuestion cleanup error during pre-spawn failure:', cleanupErr);
        });
      }
+      throw err;
+    }
+    const useStdin = spawnPlan.stdinPayload !== undefined;
+    const cliArgs = spawnPlan.args;
+    const resolvedCliSpawnPlan = await resolveCliSpawnPlan(session.command, cliArgs);

-      session.process = proc;
+    logger.info(
+      'Spawning agent:',
+      resolvedCliSpawnPlan.command,
+      resolvedCliSpawnPlan.args.join(' '),
+      `(cwd: ${cwd})`,
+    );

-      // Producer-side conversion (V3 contract): JSONL framing + adapter +
-      // toStreamEvent all run inside the shared pipeline, so renderer + future
-      // server `heteroIngest` see the same `AgentStreamEvent` wire shape with
-      // no per-consumer adapter. The pipeline auto-wires the Codex
-      // file-change line-stat tracker when `agentType === 'codex'`, so this
-      // controller stays agent-agnostic.
-      const pipeline = new AgentStreamPipeline({
-        agentType: session.agentType,
-        operationId: params.operationId,
+    // `detached: true` on Unix puts the child in a new process group so we
+    // can SIGINT/SIGKILL the whole tree (claude + any tool subprocesses)
+    // via `process.kill(-pid, sig)` on cancel. Without this, SIGINT to just
+    // the claude binary can leave bash/grep/etc. tool children running and
+    // the CLI hung waiting on them. Windows has different semantics — use
+    // taskkill /T /F there; no detached flag needed.
+    // Forward the user's proxy settings to the CLI. The main-process undici
+    // dispatcher doesn't reach child processes — they need env vars.
+    const proxyEnv = buildProxyEnv(this.app.storeManager.get('networkProxy'));
+
+    const spawnOptions = {
+      cwd,
+      detached: process.platform !== 'win32',
+      env: { ...process.env, ...proxyEnv, ...session.env },
+      stdio: [useStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'] as ['pipe' | 'ignore', 'pipe', 'pipe'],
+    };
+
+    return new Promise<void>((resolve, reject) => {
+      const proc = spawn(resolvedCliSpawnPlan.command, resolvedCliSpawnPlan.args, spawnOptions);
+      this.handleSpawnedAgentProcess({
+        intervention,
+        params,
+        proc,
+        reject,
+        resolve,
+        session,
+        traceSession,
+        useStdin,
+        spawnPlan,
      });
-      let stdoutBroadcastQueue: Promise<void> = Promise.resolve();
+    });
+  }

-      const broadcastPipelineBatch = (produce: () => ReturnType<AgentStreamPipeline['push']>) => {
-        stdoutBroadcastQueue = stdoutBroadcastQueue
-          .then(async () => {
-            const events = await produce();
-            // Adapter-extracted CC/Codex session id powers `--resume` on the
-            // next prompt; surface it through the existing `getSessionInfo`
-            // IPC by mirroring the freshest value onto the session record.
-            if (pipeline.sessionId && pipeline.sessionId !== session.agentSessionId) {
-              session.agentSessionId = pipeline.sessionId;
-            }
-            for (const event of events) {
-              this.broadcast('heteroAgentEvent', {
-                event,
-                sessionId: session.sessionId,
-              });
-            }
-          })
-          .catch((error) => {
-            logger.error('Failed to broadcast agent stream batch:', error);
-          });
-      };
-
-      // Stream stdout events through the producer pipeline.
-      const stdout = proc.stdout as Readable;
-      stdout.on('data', (chunk: Buffer) => {
-        void this.appendCliTraceFile(traceSession, 'stdout.jsonl', chunk);
-        broadcastPipelineBatch(() => pipeline.push(chunk));
+  private handleSpawnedAgentProcess({
+    intervention,
+    params,
+    proc,
+    reject,
+    resolve,
+    session,
+    spawnPlan,
+    traceSession,
+    useStdin,
+  }: {
+    intervention?: Awaited<ReturnType<HeterogeneousAgentCtr['setupInterventionForOp']>>;
+    params: SendPromptParams;
+    proc: ChildProcess;
+    reject: (reason?: unknown) => void;
+    resolve: () => void;
+    session: AgentSession;
+    spawnPlan: HeterogeneousAgentBuildPlan;
+    traceSession: CliTraceSession | undefined;
+    useStdin: boolean;
+  }) {
+    proc.on('error', (err) => {
+      logger.error('Agent process error:', err);
+      void this.writeCliTraceJson(traceSession, 'process-error.json', {
+        message: err.message,
+        name: err.name,
      });
-      stdout.on('end', () => {
-        broadcastPipelineBatch(() => pipeline.flush());
+      void this.flushCliTrace(traceSession);
+      const sessionError = this.getSessionErrorPayload(err, session);
+      this.broadcast('heteroAgentSessionError', {
+        error: sessionError,
+        sessionId: session.sessionId,
      });
+      reject(new Error(typeof sessionError === 'string' ? sessionError : sessionError.message));
+    });

-      // Capture stderr
-      const stderrChunks: string[] = [];
-      const stderr = proc.stderr as Readable;
-      stderr.on('data', (chunk: Buffer) => {
-        void this.appendCliTraceFile(traceSession, 'stderr.log', chunk);
-        stderrChunks.push(chunk.toString('utf8'));
+    // In stdin mode, write the prepared payload and close stdin.
+    if (useStdin && spawnPlan.stdinPayload !== undefined && proc.stdin) {
+      void this.writeCliTraceFile(traceSession, 'stdin.txt', spawnPlan.stdinPayload);
+      const stdin = proc.stdin as Writable;
+      stdin.write(spawnPlan.stdinPayload, () => {
+        stdin.end();
      });
+    }

-      proc.on('error', (err) => {
-        logger.error('Agent process error:', err);
-        void this.writeCliTraceJson(traceSession, 'process-error.json', {
-          message: err.message,
-          name: err.name,
-        });
-        void this.flushCliTrace(traceSession);
-        const sessionError = this.getSessionErrorPayload(err, session);
-        this.broadcast('heteroAgentSessionError', {
-          error: sessionError,
-          sessionId: session.sessionId,
-        });
-        reject(new Error(typeof sessionError === 'string' ? sessionError : sessionError.message));
-      });
+    session.process = proc;

-      proc.on('exit', (code, signal) => {
-        // Node may emit `'exit'` BEFORE stdio finishes draining (documented:
-        // child_process docs note "stdio streams might still be open" at exit
-        // time). Wait for stdout to fully end/close so the `stdout.on('end')`
-        // handler has scheduled `pipeline.flush()` onto `stdoutBroadcastQueue`,
-        // THEN wait for the queue itself to settle. Without this two-step
-        // gate, trailing flushed events (final synthesized tool_end /
-        // tool_result) would race against — and lose to — the
-        // `heteroAgentSessionComplete` broadcast, leaving renderer-side
-        // persistence to finalize on incomplete state.
-        const stdoutDrained = streamFinished(stdout, { writable: false }).catch(() => {
-          /* end / close / error are all "done"; we still want to settle. */
-        });
+    // Producer-side conversion (V3 contract): JSONL framing + adapter +
+    // toStreamEvent all run inside the shared pipeline, so renderer + future
+    // server `heteroIngest` see the same `AgentStreamEvent` wire shape with
+    // no per-consumer adapter. The pipeline auto-wires the Codex
+    // file-change line-stat tracker when `agentType === 'codex'`, so this
+    // controller stays agent-agnostic.
+    const pipeline = new AgentStreamPipeline({
+      agentType: session.agentType,
+      operationId: params.operationId,
+    });
+    let stdoutBroadcastQueue: Promise<void> = Promise.resolve();

-        void stdoutDrained
-          .then(() => stdoutBroadcastQueue)
-          .finally(async () => {
-            void this.writeCliTraceJson(traceSession, 'exit.json', {
-              code,
-              finishedAt: new Date().toISOString(),
-              signal,
+    const broadcastPipelineBatch = (produce: () => ReturnType<AgentStreamPipeline['push']>) => {
+      stdoutBroadcastQueue = stdoutBroadcastQueue
+        .then(async () => {
+          const events = await produce();
+          // Adapter-extracted CC/Codex session id powers `--resume` on the
+          // next prompt; surface it through the existing `getSessionInfo`
+          // IPC by mirroring the freshest value onto the session record.
+          if (pipeline.sessionId && pipeline.sessionId !== session.agentSessionId) {
+            session.agentSessionId = pipeline.sessionId;
+          }
+          for (const event of events) {
+            this.broadcast('heteroAgentEvent', {
+              event,
+              sessionId: session.sessionId,
            });
-            await this.flushCliTrace(traceSession);
+          }
+        })
+        .catch((error) => {
+          logger.error('Failed to broadcast agent stream batch:', error);
+        });
+    };

-            logger.info('Agent process exited:', { code, sessionId: session.sessionId, signal });
-            session.process = undefined;
+    // Stream stdout events through the producer pipeline.
+    const stdout = proc.stdout as Readable;
+    stdout.on('data', (chunk: Buffer) => {
+      void this.appendCliTraceFile(traceSession, 'stdout.jsonl', chunk);
+      broadcastPipelineBatch(() => pipeline.push(chunk));
+    });
+    stdout.on('end', () => {
+      broadcastPipelineBatch(() => pipeline.flush());
+    });

-            // If *we* killed it (cancel / stop / before-quit), treat the non-zero
-            // exit as a clean shutdown — surfacing it as an error would make a
-            // user-initiated cancel look like an agent failure, and an Electron
-            // shutdown affecting OTHER running CC sessions would pollute their
-            // topics with a misleading "Agent exited with code 143" message.
-            if (session.cancelledByUs) {
-              this.broadcast('heteroAgentSessionComplete', { sessionId: session.sessionId });
-              resolve();
-              return;
-            }
+    // Capture stderr
+    const stderrChunks: string[] = [];
+    const stderr = proc.stderr as Readable;
+    stderr.on('data', (chunk: Buffer) => {
+      void this.appendCliTraceFile(traceSession, 'stderr.log', chunk);
+      stderrChunks.push(chunk.toString('utf8'));
+    });

-            if (code === 0) {
-              this.broadcast('heteroAgentSessionComplete', { sessionId: session.sessionId });
-              resolve();
-            } else {
-              const stderrOutput = stderrChunks.join('').trim();
-              const errorMsg = this.getExitErrorMessage(code, session, stderrOutput);
-              const sessionError = this.getSessionErrorPayload(errorMsg, session);
-              this.broadcast('heteroAgentSessionError', {
-                error: sessionError,
-                sessionId: session.sessionId,
-              });
-              reject(
-                new Error(typeof sessionError === 'string' ? sessionError : sessionError.message),
-              );
-            }
-          });
+    proc.on('exit', (code, signal) => {
+      // Node may emit `'exit'` BEFORE stdio finishes draining (documented:
+      // child_process docs note "stdio streams might still be open" at exit
+      // time). Wait for stdout to fully end/close so the `stdout.on('end')`
+      // handler has scheduled `pipeline.flush()` onto `stdoutBroadcastQueue`,
+      // THEN wait for the queue itself to settle. Without this two-step
+      // gate, trailing flushed events (final synthesized tool_end /
+      // tool_result) would race against — and lose to — the
+      // `heteroAgentSessionComplete` broadcast, leaving renderer-side
+      // persistence to finalize on incomplete state.
+      const stdoutDrained = streamFinished(stdout, { writable: false }).catch(() => {
+        /* end / close / error are all "done"; we still want to settle. */
      });
+
+      void stdoutDrained
+        .then(() => stdoutBroadcastQueue)
+        .finally(async () => {
+          // Tear down the AskUserQuestion bridge / temp `mcp.json` for this
+          // op. Pending MCP handlers get a `session_ended` cancellation so
+          // they return cleanly even if CC was killed mid-tool-call.
+          if (intervention) {
+            await intervention.cleanup().catch((err) => {
+              logger.warn('AskUserQuestion cleanup error:', err);
+            });
+          }
+
+          void this.writeCliTraceJson(traceSession, 'exit.json', {
+            code,
+            finishedAt: new Date().toISOString(),
+            signal,
+          });
+          await this.flushCliTrace(traceSession);
+
+          logger.info('Agent process exited:', { code, sessionId: session.sessionId, signal });
+          session.process = undefined;
+
+          // If *we* killed it (cancel / stop / before-quit), treat the non-zero
+          // exit as a clean shutdown — surfacing it as an error would make a
+          // user-initiated cancel look like an agent failure, and an Electron
+          // shutdown affecting OTHER running CC sessions would pollute their
+          // topics with a misleading "Agent exited with code 143" message.
+          if (session.cancelledByUs) {
+            this.broadcast('heteroAgentSessionComplete', { sessionId: session.sessionId });
+            resolve();
+            return;
+          }
+
+          if (code === 0) {
+            this.broadcast('heteroAgentSessionComplete', { sessionId: session.sessionId });
+            resolve();
+          } else {
+            const stderrOutput = stderrChunks.join('').trim();
+            const errorMsg = this.getExitErrorMessage(code, session, stderrOutput);
+            const sessionError = this.getSessionErrorPayload(errorMsg, session);
+            this.broadcast('heteroAgentSessionError', {
+              error: sessionError,
+              sessionId: session.sessionId,
+            });
+            reject(
+              new Error(typeof sessionError === 'string' ? sessionError : sessionError.message),
+            );
+          }
+        });
    });
  }

@@ -972,10 +1172,54 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
  }

  /**
-   * Cleanup on app quit.
+   * Renderer → main: deliver the user's answer to a pending CC AskUserQuestion
+   * (or signal cancellation). The matching bridge resolves its blocked
+   * `pending()` Promise, the local MCP handler returns to CC, and CC's
+   * `tool_result` flows back through the normal stream pipeline.
+   *
+   * Idempotent — late submissions for already-resolved tool calls are no-ops.
+   * No-op when called for an unknown opId; the bridge may have been cleaned
+   * up already (op finished / cancelled).
+   */
+  @IpcMethod()
+  async submitIntervention(params: SubmitInterventionParams): Promise<void> {
+    const slot = this.opIdToIntervention.get(params.operationId);
+    if (!slot) {
+      logger.warn('submitIntervention: no active intervention for operationId', params.operationId);
+      return;
+    }
+    slot.bridge.resolve(params.toolCallId, {
+      cancelReason: params.cancelled ? (params.cancelReason ?? 'user_cancelled') : undefined,
+      cancelled: params.cancelled,
+      result: params.result,
+    });
+  }
+
+  /**
+   * Synchronously unlink every pending intervention's temp `mcp.json`. The
+   * async exit-handler cleanup loses to Electron's main-process teardown
+   * often enough that we'd leak `lobe-cc-mcp-<opId>.json` files into
+   * `os.tmpdir()` on real shutdowns; sync unlink here is the only reliable
+   * guarantee. Safe to call multiple times.
+   */
+  private unlinkPendingInterventionConfigsSync = (): void => {
+    for (const [, intervention] of this.opIdToIntervention) {
+      try {
+        unlinkSync(intervention.tmpConfigPath);
+      } catch {
+        /* file may already be gone — fine */
+      }
+    }
+  };
+
+  /**
+   * Cleanup on app quit. `before-quit` covers the user-driven Cmd+Q /
+   * `app.quit()` path; SIGTERM / SIGINT cover external kills (test
+   * harnesses, OS shutdown) where Electron's lifecycle events never fire.
   */
  afterAppReady() {
    electronApp.on('before-quit', () => {
+      this.unlinkPendingInterventionConfigsSync();
      for (const [, session] of this.sessions) {
        if (session.process && !session.process.killed) {
          session.cancelledByUs = true;
@@ -983,6 +1227,28 @@ export default class HeterogeneousAgentCtr extends ControllerModule {
        }
      }
      this.sessions.clear();
+      // The exit handlers will tear each per-op intervention down, but if
+      // CC's stdio close races shutdown we'd leave the MCP server bound to
+      // a port. Stopping it here cancels every still-pending bridge with
+      // `session_ended` and closes the listener.
+      void this.askUserMcpServer?.stop().catch((err) => {
+        logger.warn('AskUserQuestion MCP server stop error:', err);
+      });
    });
+
+    const onSignal = (signal: NodeJS.Signals) => {
+      this.unlinkPendingInterventionConfigsSync();
+      // Defer to Electron's normal quit flow so the rest of the app gets a
+      // chance to tear down. The `before-quit` handler above is idempotent.
+      try {
+        electronApp.quit();
+      } catch {
+        /* during late shutdown app.quit may throw — fine */
+      }
+      // Last-resort exit if Electron is wedged and won't quit on its own.
+      setTimeout(() => process.exit(signal === 'SIGINT' ? 130 : 143), 1000).unref();
+    };
+    process.on('SIGTERM', onSignal);
+    process.on('SIGINT', onSignal);
  }
 }
@@ -1,5 +1,5 @@
 import { constants } from 'node:fs';
-import { access, mkdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
+import { access, mkdir, readdir, readFile, realpath, rm, stat, writeFile } from 'node:fs/promises';
 import path from 'node:path';

 import {
@@ -12,6 +12,10 @@ import {
  type GrepContentParams,
  type GrepContentResult,
  type ListLocalFileParams,
+  type ListProjectSkillsParams,
+  type ListProjectSkillsResult,
+  type LocalFilePreviewUrlParams,
+  type LocalFilePreviewUrlResult,
  type LocalMoveFilesResultItem,
  type LocalReadFileParams,
  type LocalReadFileResult,
@@ -118,6 +122,62 @@ const collectProjectDirectories = (files: string[], root: string): ProjectFileIn
  return [...directories].map((directory) => createProjectFileEntry(root, directory, true));
 };

+const SKILL_FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+// Cap recursion to guard against pathological directory trees.
+const MAX_SKILL_FILE_COUNT = 1000;
+
+const listSkillFilesRecursive = async (dir: string): Promise<string[]> => {
+  const results: string[] = [];
+  const stack: string[] = [dir];
+
+  while (stack.length > 0 && results.length < MAX_SKILL_FILE_COUNT) {
+    const current = stack.pop()!;
+    let entries;
+    try {
+      entries = await readdir(current, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(full);
+      } else if (entry.isFile()) {
+        results.push(toPosixRelativePath(path.relative(dir, full)));
+        if (results.length >= MAX_SKILL_FILE_COUNT) break;
+      }
+    }
+  }
+  return results.sort();
+};
+
+// Parse a minimal YAML frontmatter block for SKILL.md files.
+// Only handles `key: value` lines; multi-line block scalars fall back to the first line.
+const parseSkillFrontmatter = (raw: string): Record<string, string> => {
+  const match = raw.match(SKILL_FRONTMATTER_RE);
+  if (!match) return {};
+
+  const fields: Record<string, string> = {};
+  for (const line of match[1].split(/\r?\n/)) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim();
+    if (!key || key.startsWith('#')) continue;
+    let value = line.slice(colonIdx + 1).trim();
+    if (value.startsWith('|') || value.startsWith('>')) continue;
+    if (
+      (value.startsWith('"') && value.endsWith('"')) ||
+      (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    fields[key] = value;
+  }
+  return fields;
+};
+
 const createDetectedProjectFileEntry = async (
  root: string,
  absolutePath: string,
@@ -370,6 +430,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 +614,7 @@ export default class LocalFileCtr extends ControllerModule {
          requestedScope,
          root,
        });
+        await this.approveProjectRootForPreview(root);

        return {
          entries,
@@ -560,6 +643,7 @@ export default class LocalFileCtr extends ControllerModule {
      engine: fallback.engine,
      requestedScope,
    });
+    await this.approveProjectRootForPreview(requestedScope);

    return {
      entries,
@@ -570,6 +654,61 @@ export default class LocalFileCtr extends ControllerModule {
    };
  }

+  /**
+   * Scan agent skill directories under the project root and return parsed
+   * frontmatter for each SKILL.md. Used by the hetero agent's working sidebar
+   * to surface skills available in the current project.
+   */
+  @IpcMethod()
+  async listProjectSkills(params: ListProjectSkillsParams): Promise<ListProjectSkillsResult> {
+    const root = params.scope;
+    const sources = ['.agents/skills', '.claude/skills'] as const;
+
+    for (const source of sources) {
+      const dir = path.join(root, source);
+      try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const skills = (
+          await Promise.all(
+            entries
+              .filter((entry) => entry.isDirectory() || entry.isSymbolicLink())
+              .map(async (entry) => {
+                const skillDir = path.join(dir, entry.name);
+                const skillFile = path.join(skillDir, 'SKILL.md');
+                try {
+                  const raw = await readFile(skillFile, 'utf8');
+                  const fields = parseSkillFrontmatter(raw);
+                  const files = await listSkillFilesRecursive(skillDir);
+                  return {
+                    description: fields.description || undefined,
+                    fileCount: files.length,
+                    files,
+                    name: fields.name || entry.name,
+                    path: skillFile,
+                    skillDir,
+                    source,
+                  };
+                } catch {
+                  return null;
+                }
+              }),
+          )
+        )
+          .filter((skill): skill is NonNullable<typeof skill> => skill !== null)
+          .sort((a, b) => a.name.localeCompare(b.name));
+
+        if (skills.length > 0) {
+          await this.approveProjectRootForPreview(root);
+          return { root, skills, source };
+        }
+      } catch {
+        // Directory does not exist or is not readable; try the next candidate.
+      }
+    }
+
+    return { root, skills: [], source: null };
+  }
+
  /**
   * Handle IPC event for local file search
   */
@@ -641,4 +780,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);
+    }
+  }
 }
@@ -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;
+  }
+}
@@ -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 };
  }

@@ -1,6 +1,6 @@
 import { EventEmitter } from 'node:events';
 import { access, mkdtemp, readdir, readFile, rm, unlink, writeFile } from 'node:fs/promises';
-import { tmpdir } from 'node:os';
+import * as os from 'node:os';
 import path from 'node:path';
 import { PassThrough } from 'node:stream';

@@ -9,6 +9,11 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';

 import HeterogeneousAgentCtr from '../HeterogeneousAgentCtr';

+vi.mock('node:os', async () => {
+  const actual = await vi.importActual<typeof os>('node:os');
+  return { ...actual, platform: vi.fn(() => 'linux') };
+});
+
 const FAKE_DESKTOP_PATH = '/Users/fake/Desktop';

 const { mockGetAllWindows } = vi.hoisted(() => ({
@@ -111,7 +116,7 @@ describe('HeterogeneousAgentCtr', () => {
  let appStoragePath: string;

  beforeEach(async () => {
-    appStoragePath = await mkdtemp(path.join(tmpdir(), 'lobehub-hetero-'));
+    appStoragePath = await mkdtemp(path.join(os.tmpdir(), 'lobehub-hetero-'));
  });

  afterEach(async () => {
@@ -802,4 +807,131 @@ describe('HeterogeneousAgentCtr', () => {
      expect(toolEnds.length).toBeGreaterThan(0);
    });
  });
+
+  describe('app-quit cleanup of AskUserQuestion temp configs (LOBE-8725)', () => {
+    // The async exit-handler cleanup races Electron's main-process teardown
+    // and used to leak `lobe-cc-mcp-<opId>.json` files in `os.tmpdir()` on
+    // every quit. The controller now unlinks pending intervention temp
+    // configs *synchronously* from `before-quit` AND from process signal
+    // handlers (SIGTERM / SIGINT — `before-quit` doesn't fire on external
+    // kills). These tests exercise both paths against real files.
+
+    /**
+     * Drop a temp `lobe-cc-mcp-<id>.json` and stash it on the controller's
+     * `opIdToIntervention` map under the same key, so the quit hook treats
+     * it like a real pending intervention and tries to unlink it.
+     */
+    const seedPendingIntervention = async (ctr: HeterogeneousAgentCtr, opId: string) => {
+      const tmpConfigPath = path.join(os.tmpdir(), `lobe-cc-mcp-test-${opId}.json`);
+      await writeFile(tmpConfigPath, '{"mcpServers":{}}');
+      const slot = {
+        bridge: {} as any,
+        pumpDone: Promise.resolve(),
+        tmpConfigPath,
+      };
+      (ctr as any).opIdToIntervention.set(opId, slot);
+      return tmpConfigPath;
+    };
+
+    const captureRegisteredHandler = (
+      registerSpy: ReturnType<typeof vi.fn> | ReturnType<typeof vi.spyOn>,
+      eventName: string,
+    ): (() => void) => {
+      const calls = (registerSpy as any).mock.calls as Array<[string, () => void]>;
+      const match = calls.findLast(([evt]) => evt === eventName);
+      if (!match) throw new Error(`no handler registered for "${eventName}"`);
+      return match[1];
+    };
+
+    it('before-quit synchronously unlinks every pending intervention temp config', async () => {
+      const electron = (await import('electron')) as any;
+      electron.app.on.mockClear();
+
+      const ctr = new HeterogeneousAgentCtr({
+        appStoragePath,
+        storeManager: { get: vi.fn() },
+      } as any);
+
+      const fileA = await seedPendingIntervention(ctr, 'opA');
+      const fileB = await seedPendingIntervention(ctr, 'opB');
+
+      ctr.afterAppReady();
+      const beforeQuit = captureRegisteredHandler(electron.app.on, 'before-quit');
+      beforeQuit();
+
+      await expect(access(fileA)).rejects.toThrow();
+      await expect(access(fileB)).rejects.toThrow();
+    });
+
+    it('SIGTERM handler unlinks pending intervention temp configs (external-kill path)', async () => {
+      // External kills (test harness, OS shutdown) skip Electron's lifecycle
+      // events entirely — `before-quit` never fires, so the controller has to
+      // hook the raw process signal too. Stub `process.on` so the handler is
+      // *recorded* but never actually attached to the test runner's process
+      // (otherwise the test leaks a SIGTERM listener that survives the test).
+      // Same for `process.exit` — the controller's fail-safe shouldn't get a
+      // chance to actually exit the worker if its `setTimeout(...).unref()`
+      // ever fires before mockRestore.
+      const electron = (await import('electron')) as any;
+      electron.app.on.mockClear();
+      const processOnSpy = vi.spyOn(process, 'on').mockImplementation(() => process);
+      const processExitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+
+      const ctr = new HeterogeneousAgentCtr({
+        appStoragePath,
+        storeManager: { get: vi.fn() },
+      } as any);
+      const file = await seedPendingIntervention(ctr, 'opSigterm');
+
+      ctr.afterAppReady();
+      const sigterm = captureRegisteredHandler(processOnSpy, 'SIGTERM');
+      sigterm();
+
+      await expect(access(file)).rejects.toThrow();
+
+      processOnSpy.mockRestore();
+      processExitSpy.mockRestore();
+    });
+
+    it('SIGINT handler unlinks pending intervention temp configs (Ctrl-C path)', async () => {
+      const electron = (await import('electron')) as any;
+      electron.app.on.mockClear();
+      const processOnSpy = vi.spyOn(process, 'on').mockImplementation(() => process);
+      const processExitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never);
+
+      const ctr = new HeterogeneousAgentCtr({
+        appStoragePath,
+        storeManager: { get: vi.fn() },
+      } as any);
+      const file = await seedPendingIntervention(ctr, 'opSigint');
+
+      ctr.afterAppReady();
+      const sigint = captureRegisteredHandler(processOnSpy, 'SIGINT');
+      sigint();
+
+      await expect(access(file)).rejects.toThrow();
+
+      processOnSpy.mockRestore();
+      processExitSpy.mockRestore();
+    });
+
+    it('cleanup is idempotent — already-deleted files do not throw', async () => {
+      const electron = (await import('electron')) as any;
+      electron.app.on.mockClear();
+
+      const ctr = new HeterogeneousAgentCtr({
+        appStoragePath,
+        storeManager: { get: vi.fn() },
+      } as any);
+      const file = await seedPendingIntervention(ctr, 'opIdempotent');
+
+      // Pre-delete the file out from under the controller — simulates a
+      // partial cleanup race where the async exit handler beat us to it.
+      await unlink(file);
+
+      ctr.afterAppReady();
+      const beforeQuit = captureRegisteredHandler(electron.app.on, 'before-quit');
+      expect(() => beforeQuit()).not.toThrow();
+    });
+  });
 });
@@ -0,0 +1,176 @@
+import fs from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { type App } from '@/core/App';
+
+import LocalFileCtr from '../LocalFileCtr';
+
+// Real fs + real @lobechat/file-loaders end-to-end. We only mock the
+// boundaries we genuinely cannot run in a test process: electron IPC,
+// execa shell-outs, logger, net fetch.
+vi.mock('electron', () => ({
+  dialog: { showOpenDialog: vi.fn(), showSaveDialog: vi.fn() },
+  ipcMain: { handle: vi.fn() },
+  shell: { openPath: vi.fn() },
+}));
+
+vi.mock('execa', () => ({ execa: vi.fn() }));
+
+vi.mock('@/utils/logger', () => ({
+  createLogger: () => ({
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  }),
+}));
+
+vi.mock('@/utils/net-fetch', () => ({ netFetch: vi.fn() }));
+
+vi.mock('@/utils/file-system', () => ({ makeSureDirExist: vi.fn() }));
+
+const mockApp = {
+  appStoragePath: '/mock/app/storage',
+  getService: vi.fn(),
+  toolDetectorManager: { getBestTool: vi.fn(() => null) },
+} as unknown as App;
+
+describe('LocalFileCtr — readFile / readFiles (real fs)', () => {
+  const tmpDir = path.join(os.tmpdir(), 'localfilectr-readfile-test-' + process.pid);
+  let localFileCtr: LocalFileCtr;
+
+  beforeEach(async () => {
+    vi.clearAllMocks();
+    await mkdir(tmpDir, { recursive: true });
+    localFileCtr = new LocalFileCtr(mockApp);
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { force: true, recursive: true });
+  });
+
+  describe('readFile', () => {
+    it('should read file successfully with default location', async () => {
+      const filePath = path.join(tmpDir, 'test.txt');
+      const content = 'line1\nline2\nline3\nline4\nline5';
+      await writeFile(filePath, content);
+
+      const result = await localFileCtr.readFile({ path: filePath });
+
+      expect(result).toEqual({
+        charCount: 29,
+        content,
+        createdTime: expect.any(Date),
+        fileType: 'txt',
+        filename: 'test.txt',
+        lineCount: 5,
+        loc: [0, 200],
+        modifiedTime: expect.any(Date),
+        totalCharCount: 29,
+        totalLineCount: 5,
+      });
+    });
+
+    it('should read file with custom location range', async () => {
+      const filePath = path.join(tmpDir, 'range.txt');
+      await writeFile(filePath, 'line1\nline2\nline3\nline4\nline5');
+
+      const result = await localFileCtr.readFile({ loc: [1, 3], path: filePath });
+
+      expect(result).toEqual({
+        charCount: 11,
+        content: 'line2\nline3',
+        createdTime: expect.any(Date),
+        fileType: 'txt',
+        filename: 'range.txt',
+        lineCount: 2,
+        loc: [1, 3],
+        modifiedTime: expect.any(Date),
+        totalCharCount: 29,
+        totalLineCount: 5,
+      });
+    });
+
+    it('should read full file content when fullContent is true', async () => {
+      const filePath = path.join(tmpDir, 'full.txt');
+      const content = 'line1\nline2\nline3\nline4\nline5';
+      await writeFile(filePath, content);
+
+      const result = await localFileCtr.readFile({ fullContent: true, path: filePath });
+
+      expect(result).toEqual({
+        charCount: 29,
+        content,
+        createdTime: expect.any(Date),
+        fileType: 'txt',
+        filename: 'full.txt',
+        lineCount: 5,
+        loc: [0, 5],
+        modifiedTime: expect.any(Date),
+        totalCharCount: 29,
+        totalLineCount: 5,
+      });
+    });
+
+    it('should handle file read error', async () => {
+      const result = await localFileCtr.readFile({
+        path: path.join(tmpDir, 'does-not-exist.txt'),
+      });
+
+      expect(result).toEqual({
+        charCount: 0,
+        content: expect.stringContaining('Error accessing or processing file'),
+        createdTime: expect.any(Date),
+        fileType: 'txt',
+        filename: 'does-not-exist.txt',
+        lineCount: 0,
+        loc: [0, 0],
+        modifiedTime: expect.any(Date),
+        totalCharCount: 0,
+        totalLineCount: 0,
+      });
+    });
+  });
+
+  describe('readFiles', () => {
+    it('should read multiple files successfully', async () => {
+      const file1 = path.join(tmpDir, 'a.txt');
+      const file2 = path.join(tmpDir, 'b.txt');
+      await writeFile(file1, 'content a');
+      await writeFile(file2, 'content b');
+
+      const result = await localFileCtr.readFiles({ paths: [file1, file2] });
+
+      expect(result).toEqual([
+        {
+          charCount: 9,
+          content: 'content a',
+          createdTime: expect.any(Date),
+          fileType: 'txt',
+          filename: 'a.txt',
+          lineCount: 1,
+          loc: [0, 200],
+          modifiedTime: expect.any(Date),
+          totalCharCount: 9,
+          totalLineCount: 1,
+        },
+        {
+          charCount: 9,
+          content: 'content b',
+          createdTime: expect.any(Date),
+          fileType: 'txt',
+          filename: 'b.txt',
+          lineCount: 1,
+          loc: [0, 200],
+          modifiedTime: expect.any(Date),
+          totalCharCount: 9,
+          totalLineCount: 1,
+        },
+      ]);
+    });
+  });
+});
@@ -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
  },
@@ -106,7 +113,6 @@ const mockApp = {
 describe('LocalFileCtr', () => {
  let localFileCtr: LocalFileCtr;
  let mockShell: any;
-  let mockLoadFile: any;
  let mockFsPromises: any;

  beforeEach(async () => {
@@ -114,7 +120,6 @@ describe('LocalFileCtr', () => {

    // Import mocks
    mockShell = (await import('electron')).shell;
-    mockLoadFile = (await import('@lobechat/file-loaders')).loadFile;
    mockFsPromises = await import('node:fs/promises');

    localFileCtr = new LocalFileCtr(mockApp);
@@ -178,89 +183,43 @@ describe('LocalFileCtr', () => {
    });
  });

-  describe('readFile', () => {
-    it('should read file successfully with default location', async () => {
-      const mockFileContent = 'line1\nline2\nline3\nline4\nline5';
-      vi.mocked(mockLoadFile).mockResolvedValue({
-        content: mockFileContent,
-        filename: 'test.txt',
-        fileType: 'txt',
-        createdTime: new Date('2024-01-01'),
-        modifiedTime: new Date('2024-01-02'),
+  // readFile / readFiles e2e tests live in LocalFileCtr.readFile.test.ts so
+  // 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',
      });

-      const result = await localFileCtr.readFile({ path: '/test/file.txt' });
-
-      expect(result.filename).toBe('test.txt');
-      expect(result.fileType).toBe('txt');
-      expect(result.totalLineCount).toBe(5);
-      expect(result.content).toBe(mockFileContent);
+      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 read file with custom location range', async () => {
-      const mockFileContent = 'line1\nline2\nline3\nline4\nline5';
-      vi.mocked(mockLoadFile).mockResolvedValue({
-        content: mockFileContent,
-        filename: 'test.txt',
-        fileType: 'txt',
-        createdTime: new Date('2024-01-01'),
-        modifiedTime: new Date('2024-01-02'),
+    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',
      });

-      const result = await localFileCtr.readFile({ path: '/test/file.txt', loc: [1, 3] });
-
-      expect(result.content).toBe('line2\nline3');
-      expect(result.lineCount).toBe(2);
-      expect(result.totalLineCount).toBe(5);
-    });
-
-    it('should read full file content when fullContent is true', async () => {
-      const mockFileContent = 'line1\nline2\nline3\nline4\nline5';
-      vi.mocked(mockLoadFile).mockResolvedValue({
-        content: mockFileContent,
-        filename: 'test.txt',
-        fileType: 'txt',
-        createdTime: new Date('2024-01-01'),
-        modifiedTime: new Date('2024-01-02'),
+      expect(result).toEqual({
+        error: 'File is outside the approved workspace',
+        success: false,
      });
-
-      const result = await localFileCtr.readFile({ path: '/test/file.txt', fullContent: true });
-
-      expect(result.content).toBe(mockFileContent);
-      expect(result.lineCount).toBe(5);
-      expect(result.charCount).toBe(mockFileContent.length);
-      expect(result.totalLineCount).toBe(5);
-      expect(result.totalCharCount).toBe(mockFileContent.length);
-      expect(result.loc).toEqual([0, 5]);
-    });
-
-    it('should handle file read error', async () => {
-      vi.mocked(mockLoadFile).mockRejectedValue(new Error('File not found'));
-
-      const result = await localFileCtr.readFile({ path: '/test/missing.txt' });
-
-      expect(result.content).toContain('Error accessing or processing file');
-      expect(result.lineCount).toBe(0);
-      expect(result.charCount).toBe(0);
-    });
-  });
-
-  describe('readFiles', () => {
-    it('should read multiple files successfully', async () => {
-      vi.mocked(mockLoadFile).mockResolvedValue({
-        content: 'file content',
-        filename: 'test.txt',
-        fileType: 'txt',
-        createdTime: new Date('2024-01-01'),
-        modifiedTime: new Date('2024-01-02'),
-      });
-
-      const result = await localFileCtr.readFiles({
-        paths: ['/test/file1.txt', '/test/file2.txt'],
-      });
-
-      expect(result).toHaveLength(2);
-      expect(mockLoadFile).toHaveBeenCalledTimes(2);
    });
  });

@@ -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);
+    });
+  });
+});
@@ -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,
@@ -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();

@@ -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(),
  })),
@@ -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;
+  }
+}
@@ -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();
+  });
+});
@@ -49,6 +49,10 @@ class TestContentSearch extends BaseContentSearch {
  public testGetDefaultIgnorePatterns(): string[] {
    return this.getDefaultIgnorePatterns();
  }
+
+  public testResolveSearchPath(params: GrepContentParams): string {
+    return this.resolveSearchPath(params);
+  }
 }

 describe('BaseContentSearch', () => {
@@ -255,6 +259,33 @@ describe('BaseContentSearch', () => {
    });
  });

+  describe('resolveSearchPath', () => {
+    it('prefers scope when path is not set', () => {
+      const resolved = contentSearch.testResolveSearchPath({
+        pattern: 'x',
+        scope: '/Users/arvinxx/repo',
+      });
+
+      expect(resolved).toBe('/Users/arvinxx/repo');
+    });
+
+    it('honors legacy path over scope when both are set', () => {
+      const resolved = contentSearch.testResolveSearchPath({
+        path: '/legacy/path',
+        pattern: 'x',
+        scope: '/scope/path',
+      });
+
+      expect(resolved).toBe('/legacy/path');
+    });
+
+    it('falls back to process.cwd() when neither is provided', () => {
+      const resolved = contentSearch.testResolveSearchPath({ pattern: 'x' });
+
+      expect(resolved).toBe(process.cwd());
+    });
+  });
+
  describe('getDefaultIgnorePatterns', () => {
    it('should return default ignore patterns', () => {
      const patterns = contentSearch.testGetDefaultIgnorePatterns();
@@ -46,6 +46,18 @@ export abstract class BaseContentSearch {
   */
  abstract checkToolAvailable(tool: string): Promise<boolean>;

+  /**
+   * Resolve the directory to run the search in.
+   *
+   * The builtin-tool manifest documents `scope`, while the legacy IPC type also accepts
+   * `path`. Read both so an agent calling with `scope` (per the manifest) doesn't silently
+   * fall through to `process.cwd()` — which in a packaged Electron app isn't the project
+   * root and therefore has no `.gitignore` for ripgrep to honor.
+   */
+  protected resolveSearchPath(params: GrepContentParams): string {
+    return params.path ?? params.scope ?? process.cwd();
+  }
+
  /**
   * Build command-line arguments for grep tools
   */
@@ -141,11 +153,8 @@ export abstract class BaseContentSearch {
   * Grep using Node.js native implementation (fallback)
   */
  protected async grepWithNodejs(params: GrepContentParams): Promise<GrepContentResult> {
-    const {
-      pattern,
-      path: searchPath = process.cwd(),
-      output_mode = 'files_with_matches',
-    } = params;
+    const { pattern, output_mode = 'files_with_matches' } = params;
+    const searchPath = this.resolveSearchPath(params);
    const logPrefix = `[grepContent:nodejs]`;

    const flags = `${params['-i'] ? 'i' : ''}${params.multiline ? 's' : ''}`;
@@ -1,4 +1,3 @@
- 
 import type { GrepContentParams, GrepContentResult } from '@lobechat/electron-client-ipc';
 import { execa } from 'execa';

@@ -179,7 +178,8 @@ export abstract class UnixContentSearch extends BaseContentSearch {
    tool: 'rg' | 'ag' | 'grep',
    params: GrepContentParams,
  ): Promise<GrepContentResult> {
-    const { path: searchPath = process.cwd(), output_mode = 'files_with_matches' } = params;
+    const { output_mode = 'files_with_matches' } = params;
+    const searchPath = this.resolveSearchPath(params);
    const logPrefix = `[grepContent:${tool}]`;

    try {
@@ -272,7 +272,7 @@ export abstract class UnixContentSearch extends BaseContentSearch {

    try {
      const { stdout } = await execa(tool, args, {
-        cwd: params.path || process.cwd(),
+        cwd: this.resolveSearchPath(params),
        reject: false,
      });

@@ -1,4 +1,3 @@
- 
 import type { GrepContentParams, GrepContentResult } from '@lobechat/electron-client-ipc';
 import { execa } from 'execa';

@@ -146,7 +145,8 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
   * Grep using ripgrep (rg) - cross-platform
   */
  private async grepWithRipgrep(params: GrepContentParams): Promise<GrepContentResult> {
-    const { path: searchPath = process.cwd(), output_mode = 'files_with_matches' } = params;
+    const { output_mode = 'files_with_matches' } = params;
+    const searchPath = this.resolveSearchPath(params);
    const logPrefix = `[grepContent:rg]`;

    try {
@@ -230,7 +230,7 @@ export class WindowsContentSearchImpl extends BaseContentSearch {

    try {
      const { stdout } = await execa('rg', args, {
-        cwd: params.path || process.cwd(),
+        cwd: this.resolveSearchPath(params),
        reject: false,
      });

@@ -252,11 +252,8 @@ export class WindowsContentSearchImpl extends BaseContentSearch {
   * Note: findstr has limited functionality compared to ripgrep
   */
  private async grepWithFindstr(params: GrepContentParams): Promise<GrepContentResult> {
-    const {
-      pattern,
-      path: searchPath = process.cwd(),
-      output_mode = 'files_with_matches',
-    } = params;
+    const { pattern, output_mode = 'files_with_matches' } = params;
+    const searchPath = this.resolveSearchPath(params);
    const logPrefix = `[grepContent:findstr]`;

    try {
@@ -0,0 +1,62 @@
+import { describe, expect, it } from 'vitest';
+
+import type {
+  HeterogeneousAgentBuildPlanHelpers,
+  HeterogeneousAgentBuildPlanParams,
+} from '../types';
+import { claudeCodeDriver } from './claudeCode';
+
+const stubHelpers: HeterogeneousAgentBuildPlanHelpers = {
+  buildClaudeStreamJsonInput: async () => '{"type":"user","message":{}}\n',
+  resolveCliImagePaths: async () => [],
+};
+
+const buildParams = (
+  overrides: Partial<HeterogeneousAgentBuildPlanParams> = {},
+): HeterogeneousAgentBuildPlanParams => ({
+  args: [],
+  helpers: stubHelpers,
+  imageList: [],
+  prompt: 'hi',
+  ...overrides,
+});
+
+describe('claudeCodeDriver', () => {
+  it('omits --mcp-config when mcpConfigPath is undefined', async () => {
+    const { args } = await claudeCodeDriver.buildSpawnPlan(buildParams());
+    expect(args).not.toContain('--mcp-config');
+  });
+
+  it('appends --mcp-config <path> when mcpConfigPath is provided', async () => {
+    const { args } = await claudeCodeDriver.buildSpawnPlan(
+      buildParams({ mcpConfigPath: '/tmp/lobe-cc-mcp-op-1.json' }),
+    );
+    const idx = args.indexOf('--mcp-config');
+    expect(idx).toBeGreaterThan(-1);
+    expect(args[idx + 1]).toBe('/tmp/lobe-cc-mcp-op-1.json');
+  });
+
+  it('still pins --disallowedTools AskUserQuestion alongside --mcp-config', async () => {
+    // Even with our local MCP replacement available, CC's built-in stays
+    // disabled — leaving both visible would let the model double-register
+    // the same name and pick the broken one.
+    const { args } = await claudeCodeDriver.buildSpawnPlan(
+      buildParams({ mcpConfigPath: '/tmp/x.json' }),
+    );
+    const disallowedIdx = args.indexOf('--disallowedTools');
+    expect(disallowedIdx).toBeGreaterThan(-1);
+    expect(args[disallowedIdx + 1]).toBe('AskUserQuestion');
+  });
+
+  it('--mcp-config goes before --resume so user --args can still override the resume id', async () => {
+    const { args } = await claudeCodeDriver.buildSpawnPlan(
+      buildParams({ mcpConfigPath: '/tmp/x.json', resumeSessionId: 'cc-prev-1' }),
+    );
+    const mcpIdx = args.indexOf('--mcp-config');
+    const resumeIdx = args.indexOf('--resume');
+    expect(mcpIdx).toBeGreaterThan(-1);
+    expect(resumeIdx).toBeGreaterThan(-1);
+    expect(mcpIdx).toBeLessThan(resumeIdx);
+    expect(args[resumeIdx + 1]).toBe('cc-prev-1');
+  });
+});
@@ -1,12 +1,13 @@
+import { CLAUDE_CODE_BASE_ARGS } from '@lobechat/heterogeneous-agents/spawn';
+
 import type { HeterogeneousAgentBuildPlanParams, HeterogeneousAgentDriver } from '../types';

-const CLAUDE_CODE_BASE_ARGS = [
-  '-p',
-  '--input-format',
-  'stream-json',
-  '--output-format',
-  'stream-json',
-  '--verbose',
+// Desktop runs CC as the user (never root, so bypassPermissions is fine) and
+// renders the chat bubble live, so it always wants partial deltas. Compose
+// the shared invariant base args (`@lobechat/heterogeneous-agents/spawn`)
+// with those caller-specific flags.
+const DESKTOP_CLAUDE_CODE_ARGS = [
+  ...CLAUDE_CODE_BASE_ARGS,
  '--include-partial-messages',
  '--permission-mode',
  'bypassPermissions',
@@ -17,6 +18,7 @@ export const claudeCodeDriver: HeterogeneousAgentDriver = {
    args,
    helpers,
    imageList,
+    mcpConfigPath,
    prompt,
    resumeSessionId,
  }: HeterogeneousAgentBuildPlanParams) {
@@ -24,7 +26,11 @@ export const claudeCodeDriver: HeterogeneousAgentDriver = {

    return {
      args: [
-        ...CLAUDE_CODE_BASE_ARGS,
+        ...DESKTOP_CLAUDE_CODE_ARGS,
+        // Wire the controller-managed temp mcp.json (AskUserQuestion server,
+        // see LOBE-8725) when present. Path-based config is required — CC
+        // does not accept inline JSON for `--mcp-config`.
+        ...(mcpConfigPath ? ['--mcp-config', mcpConfigPath] : []),
        ...(resumeSessionId ? ['--resume', resumeSessionId] : []),
        ...args,
      ],
@@ -20,6 +20,12 @@ export interface HeterogeneousAgentBuildPlanParams {
  args: string[];
  helpers: HeterogeneousAgentBuildPlanHelpers;
  imageList: HeterogeneousAgentImageAttachment[];
+  /**
+   * Optional path to an MCP config JSON written by the controller (e.g. for
+   * the local `lobe_cc` AskUserQuestion server). Drivers that recognize the
+   * field append `--mcp-config <path>`; others ignore it.
+   */
+  mcpConfigPath?: string;
  prompt: string;
  resumeSessionId?: string;
 }
@@ -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);
+  });
+});
@@ -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']);
+  });
+});
@@ -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);
+  });
+});
@@ -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');
+  });
+});
@@ -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;
+};
@@ -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;
+  });
+};
@@ -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;
+};
@@ -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;
+};
@@ -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',
+};
@@ -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);
+    });
+  });
+});
--- a/Show More
+++ b/Show More