Fix message edit send behavior

📝 docs(skills): add sub-issue tree guide to linear skill (#14076 )
📝 docs: add April 20 weekly changelog (#14072 )
2026-06-14 03:30:19 +00:00 · 2026-04-23 13:20:20 +08:00 · 2026-04-23 11:33:30 +08:00 · 2026-04-23 10:38:46 +08:00 · 2026-04-23 10:31:14 +08:00 · 2026-04-23 02:13:09 +08:00
2158 changed files with 142561 additions and 18526 deletions
@@ -0,0 +1,298 @@
+---
+name: bot
+description: 'Bot platform architecture (Discord, Slack, Telegram, Feishu/Lark, QQ, WeChat). Use when working on inbound webhooks, Chat SDK message routing, agent execution from chat platforms, queue-mode callbacks, gateway lifecycle (websocket/polling), bot provider CRUD/credentials, or platform-specific clients/adapters/schemas. Triggers on bot, channel, webhook, mention, Chat SDK, agent bot provider, gateway, bot-callback, qstash bot.'
+---
+
+# Bot System
+
+> **Last updated: 2026-04-08.** Implementation evolves quickly — this doc is a map, not the source of truth. Always read the key files below to verify behavior, especially per-platform quirks. Update this doc when the architecture changes.
+
+LobeChat agents can answer inside external chat platforms. Inbound messages flow through the Chat SDK (`chat` npm package), get routed to the right agent by `(platform, applicationId)`, executed via `AiAgentService`, and replied back through a per-platform `PlatformClient`. There are **two execution modes** (in-memory vs queue/QStash) and **three connection modes** (`webhook`, `websocket`, `polling`).
+
+## Supported Platforms
+
+| Platform | id         | Default mode                    | Markdown          | Edit   | Notes                                                                                  |
+| -------- | ---------- | ------------------------------- | ----------------- | ------ | -------------------------------------------------------------------------------------- |
+| Discord  | `discord`  | `websocket`                     | yes               | yes    | Persistent gateway via Chat SDK adapter; reaction-thread quirks; native slash commands |
+| Slack    | `slack`    | `websocket` (Socket Mode)       | yes (mrkdwn)      | yes    | Multi-mode — user can pick `webhook` per provider                                      |
+| Telegram | `telegram` | `webhook`                       | yes (HTML)        | yes    | `setMyCommands` menu via `registerBotCommands`                                         |
+| Feishu   | `feishu`   | `websocket` (Lark SDK WSClient) | **no** (stripped) | yes    | Multi-mode; shared client with Lark                                                    |
+| Lark     | `lark`     | `websocket`                     | **no**            | yes    | Same client/schema as Feishu, different domain                                         |
+| QQ       | `qq`       | `websocket`                     | **no**            | **no** | All replies are final-only                                                             |
+| WeChat   | `wechat`   | `polling` (iLink long-poll)     | **no**            | **no** | 10-minute gateway window                                                               |
+
+`supportsMarkdown=false` ⇒ outbound markdown is stripped to plain text via `stripMarkdown` and the AI is told not to use markdown. `supportsMessageEdit=false` ⇒ no progress edits — only the final reply is sent.
+
+**Multi-mode connection** — Slack/Feishu/Lark/QQ ship as websocket but support `webhook` per-provider via `settings.connectionMode`. The runtime always merges schema defaults into stored settings before resolving the mode (`resolveBotProviderConfig` / `resolveConnectionMode` in `platforms/utils.ts`), so the schema's `field.default` is the source of truth — set it correctly when adding a new multi-mode platform.
+
+## Inbound Flow (one webhook → reply)
+
+```
+Platform server
+   │  POST /api/agent/webhooks/[platform]/[appId]
+   ▼
+route.ts ── catch-all `[[...appId]]` route
+   │
+   ▼
+BotMessageRouter (singleton)
+   │  • lazy-loads bot per `platform:applicationId`
+   │  • merges schema defaults + provider.settings (mergeWithDefaults)
+   │  • builds Chat SDK Chat<any> with createIoRedisState (if Redis available)
+   │  • registerHandlers: onNewMention / onSubscribedMessage / onNewMessage(/.dm)
+   │  • registerCommands: /new (reset topic), /stop (interrupt)
+   │
+   ▼
+chatBot.webhooks[platform](req)   ← Chat SDK parses → fires events
+   │
+   ▼
+AgentBridgeService.handleMention / handleSubscribedMessage
+   │  • activeThreads guard (no duplicate runs per thread)
+   │  • adds 👀 reaction (eyes), startTyping
+   │  • merges debounced/queued skipped messages (mergeSkippedMessages)
+   │  • extractFiles (buffer → fetchData → url)
+   │  • formatPrompt (sanitize mention + speaker tag + referenced_message)
+   │
+   ├── In-memory mode ──► AiAgentService.execAgent({ stepCallbacks })
+   │       → onAfterStep edits progress message live
+   │       → onComplete edits final reply, splits via splitMessage(charLimit)
+   │
+   └── Queue mode (isQueueAgentRuntimeEnabled) ──► execAgent({ stepWebhook, completionWebhook, webhookDelivery: 'qstash' })
+           → returns immediately, callbacks land at /api/agent/webhooks/bot-callback
+```
+
+The router caches loaded bots in memory. Cache is **invalidated** by `BotMessageRouter.invalidateBot(platform, appId)` whenever the TRPC `update`/`delete` mutations run, so new credentials/settings take effect on the next webhook.
+
+## Execution Modes
+
+### In-memory (default)
+
+`AgentBridgeService.executeWithInMemoryCallbacks` wraps `execAgent` with `stepCallbacks`. Lives in one process — Promise-based wait, 30-min timeout, edits the same `progressMessage` after every step. Topic title is summarized inline via `SystemAgentService`.
+
+### Queue (`isQueueAgentRuntimeEnabled`)
+
+`AgentBridgeService.executeWithWebhooks`:
+
+1. Posts the `renderStart` placeholder, captures `progressMessageId`.
+2. Calls `execAgent` with `stepWebhook` and `completionWebhook` pointing at `${INTERNAL_APP_URL ?? APP_URL}/api/agent/webhooks/bot-callback`, plus `webhookDelivery: 'qstash'`.
+3. Returns immediately; the bridge `finally` block keeps the active-thread marker held until the `completion` callback fires.
+
+`/api/agent/webhooks/bot-callback/route.ts` verifies the QStash signature and hands off to `BotCallbackService.handleCallback`:
+
+- `type: 'step'` → `handleStep` re-renders `renderStepProgress`, edits `progressMessageId` (skipped if `displayToolCalls=false` or platform `supportsMessageEdit=false`).
+- `type: 'completion'` → `handleCompletion` writes the final reply (or error/interrupted message), removes the 👀 reaction, clears active-thread tracker, fires async `summarizeTopicTitle`.
+
+`BotCallbackService.createMessenger` reloads provider + credentials from DB and rebuilds a `PlatformClient` per call (no in-memory state).
+
+## Commands
+
+Defined in `BotMessageRouter.buildCommands` and registered via two paths:
+
+- **Native slash commands** (Slack/Discord): `bot.onSlashCommand('/<name>', ...)`
+- **Text-based fallback** (Telegram/Feishu/QQ/Lark/WeChat): `bot.onNewMessage(/^\/(new|stop)(\s|$|@)/, ...)` plus a per-mention `tryDispatch` so commands work even before subscribe.
+
+Built-in commands:
+
+- `/new` — clears `topicId` in thread state, next message starts a fresh topic.
+- `/stop` — interrupts the active execution (calls `AiAgentService.interruptTask` if `operationId` is known; otherwise queues a deferred stop via `requestStop`/`pendingStopThreads`, also aborts the startup phase via `startupControllers`).
+
+To add a command, append to `buildCommands` — it auto-registers everywhere; on Telegram it also surfaces in the `/` menu via `client.registerBotCommands` → `setMyCommands`.
+
+## Active-thread State (statics on `AgentBridgeService`)
+
+- `activeThreads: Set<threadId>` — prevents duplicate runs per thread (must guard before stale-topic check, otherwise concurrent messages can drop).
+- `activeOperations: Map<threadId, operationId>` — needed by `/stop` once `execAgent` returns.
+- `startupControllers: Map<threadId, AbortController>` — cancels pre-`operationId` work (topic/tool prep).
+- `pendingStopThreads: Set<threadId>` — `/stop` arrived before `operationId` existed; consumed once available.
+
+In **queue mode**, the bridge `finally` skips cleanup so the marker persists until `BotCallbackService.handleCompletion` calls `clearActiveThread`.
+
+## Topic Lifecycle in Threads
+
+- `handleMention` always treats the message as the start of a new conversation.
+- `handleSubscribedMessage` reads `topicId` from `thread.state`. If the topic is stale (`> 4 hours` since `updatedAt`), state is cleared and it retries as a fresh mention.
+- If `execAgent` fails with a Postgres FK violation on `topic_id` (cached topic was deleted), the bridge clears state and retries as a mention.
+- `subscribe()` is gated by `client.shouldSubscribe(threadId)` — Discord top-level channels return `false` so we don't follow up there.
+
+## Attachments
+
+`AgentBridgeService.extractFiles` resolves attachments in priority order:
+
+1. `att.buffer` — already downloaded by the adapter (WeChat/Feishu inbound).
+2. `att.fetchData()` — adapter-provided lazy download with auth (Telegram, Slack, Feishu history). **Required** when URLs are token-protected — naive `fetch(url)` later in `ingestAttachment.ts` has no credentials.
+3. `att.url` — public CDN fallback (Discord, public QQ).
+
+`inferMimeType` / `inferName` patch Telegram-style `photo` payloads (no `mimeType`/`name` from Bot API → defaults to `image/jpeg`) so vision models actually see them. Quoted-message attachments are also pulled from `raw.referenced_message.attachments` (Discord).
+
+## Concurrency
+
+`settings.concurrency` is `'queue'` or `'debounce'`:
+
+- `debounce` → Chat SDK debounces inbound messages by `debounceMs`; `mergeSkippedMessages` joins skipped texts/attachments into the current message before handing to the agent.
+- `queue` → Chat SDK serializes per-thread; the bridge's own `activeThreads` set is still required because in queue mode the SDK lock releases before the agent finishes.
+
+## Gateway (persistent platforms)
+
+Webhook platforms run fine in serverless functions. Persistent platforms (`websocket`, `polling`) need a long-running listener — that's the **gateway**.
+
+**`GatewayService.startClient(platform, appId, userId)`** (`src/server/services/gateway/index.ts`):
+
+- On Vercel + persistent mode → `BotConnectQueue.push` (Redis hash) and mark runtime status `queued`. The cron picks it up.
+- On Vercel + webhook mode → start the client inline (one HTTP call).
+- Off-Vercel → `GatewayManager` singleton holds long-lived clients in process.
+
+**`GET /api/agent/gateway/route.ts`** (cron, `Bearer ${CRON_SECRET}`):
+
+- Iterates registered platforms and starts every enabled persistent provider with `durationMs = 10min`, then in `after(...)` polls `BotConnectQueue` every 30s for new connect requests, until the window expires.
+- `getEffectiveConnectionMode(platform, settings)` is the only place that resolves per-provider mode — respect it everywhere.
+
+**`POST /api/agent/gateway/start/route.ts`** is the non-Vercel `ensureRunning` entry point (`Bearer ${KEY_VAULTS_SECRET}`).
+
+**Runtime status** is stored in Redis at `bot:runtime-status:platform:appId` with TTL ≈ `durationMs + 60s`. States: `starting | connected | disconnected | failed | queued`. Updated by each `PlatformClient.start/stop` and by the gateway service.
+
+## Platform Definitions
+
+Each platform exposes a `PlatformDefinition` registered in `platforms/index.ts`:
+
+```ts
+{
+  id: 'discord',
+  name: 'Discord',
+  connectionMode: 'websocket',          // recommended default
+  schema: FieldSchema[],                 // applicationId + credentials + settings
+  clientFactory: new DiscordClientFactory(),
+  supportsMarkdown?: boolean,            // default true
+  supportsMessageEdit?: boolean,         // default true
+  documentation?: { portalUrl, setupGuideUrl },
+}
+```
+
+`schema` drives both server validation (`mergeWithDefaults`, `extractDefaults`) **and** the auto-generated UI form. Top-level keys `applicationId` / `credentials` / `settings` map to DB columns. Common settings fields live in `platforms/const.ts` (`displayToolCallsField`, `serverIdField`, `userIdField`).
+
+Each platform implements `PlatformClient` (see `platforms/types.ts`):
+
+- Lifecycle: `start(opts?)`, `stop()`
+- Inbound: `createAdapter()` → Chat SDK adapter map
+- Outbound: `getMessenger(platformThreadId)` → `{ createMessage, editMessage, removeReaction, triggerTyping, updateThreadName? }`
+- Formatting: `formatMarkdown?`, `formatReply?` (usage-stats footer when `showUsageStats`)
+- Helpers: `extractChatId`, `parseMessageId`, `sanitizeUserInput`, `shouldSubscribe`, `resolveReactionThreadId`
+- Optional patches: `applyChatPatches(chatBot)` (Discord uses this for `forwardedInteractions` + `threadRecovery`)
+- Optional menu: `registerBotCommands(commands)` (Telegram `setMyCommands`)
+
+`ClientFactory.validateCredentials` is called from the TRPC `testConnection` mutation — implement it to hit the platform API and return useful per-field errors.
+
+## Database
+
+**Schema** (`packages/database/src/schemas/agentBotProvider.ts`):
+
+```ts
+agent_bot_providers (
+  id uuid pk,
+  agent_id text fk → agents.id (cascade),
+  user_id text fk → users.id (cascade),
+  platform varchar(50),                  // 'discord' | 'slack' | …
+  application_id varchar(255),
+  credentials text,                      // KeyVaults-encrypted JSON
+  settings jsonb default '{}',
+  enabled boolean default true,
+  …timestamps
+)
+unique (platform, application_id)
+```
+
+**Model** (`packages/database/src/models/agentBotProvider.ts`):
+
+- User-scoped: `create / update / delete / query / findById / findByAgentId / findEnabledByApplicationId`. Credentials are encrypted/decrypted via the injected `KeyVaultsGateKeeper`.
+- Static (system-wide): `findByPlatformAndAppId`, `findEnabledByPlatform` — used by webhook routing & gateway sync, since they don't have a user context yet.
+
+**TRPC router** (`src/server/routers/lambda/agentBotProvider.ts`):
+
+| Procedure                                    | Notes                                                                                       |              |
+| -------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------ |
+| `listPlatforms`                              | Returns `SerializedPlatformDefinition[]` (no `clientFactory`)                               |              |
+| `create` / `update` / `delete`               | Calls `BotMessageRouter.invalidateBot` + `GatewayService.stopClient` so changes take effect |              |
+| `list` / `getByAgentId` / `getRuntimeStatus` | Decorate rows with Redis runtime status                                                     |              |
+| `connectBot`                                 | Returns \`{ status: 'started'                                                               | 'queued' }\` |
+| `testConnection`                             | Calls `clientFactory.validateCredentials`                                                   |              |
+| `wechatGetQrCode` / `wechatPollQrStatus`     | iLink onboarding flow                                                                       |              |
+
+Client service: `src/services/agentBotProvider.ts`. Store actions: `src/store/agent/slices/bot/action.ts`. UI: `src/routes/(main)/agent/channel/{list,detail}` — settings form is auto-generated from each platform's `schema`.
+
+## Reply Templates
+
+`src/server/services/bot/replyTemplate.ts` exports `renderStart`, `renderStepProgress`, `renderFinalReply`, `renderError`, `renderStopped`, `splitMessage`. Step progress carries elapsed time, last LLM content, last tools, totals; final reply uses `client.formatMarkdown` then `client.formatReply` (which optionally appends `formatUsageStats`). `splitMessage(text, charLimit)` chunks at paragraph → line → hard cut.
+
+`src/server/services/bot/ackPhrases/` provides randomized ack phrases.
+
+## Key Files
+
+```plaintext
+Webhook routes:
+  src/app/(backend)/api/agent/webhooks/[platform]/[[...appId]]/route.ts  — inbound catch-all
+  src/app/(backend)/api/agent/webhooks/bot-callback/route.ts             — qstash bot callback
+  src/app/(backend)/api/agent/gateway/route.ts                           — cron gateway (10min window)
+  src/app/(backend)/api/agent/gateway/start/route.ts                     — non-Vercel ensureRunning
+
+Bot service:
+  src/server/services/bot/index.ts                          — barrel
+  src/server/services/bot/BotMessageRouter.ts               — lazy bot loading + handler registration + commands
+  src/server/services/bot/AgentBridgeService.ts             — Chat SDK ↔ AiAgentService bridge, both exec modes
+  src/server/services/bot/BotCallbackService.ts             — qstash callback handler
+  src/server/services/bot/formatPrompt.ts                   — speaker tag + referenced_message + sanitize
+  src/server/services/bot/replyTemplate.ts                  — render*/splitMessage
+  src/server/services/bot/ackPhrases/                       — randomized acks
+  src/server/services/bot/__tests__/                        — unit tests for the above
+
+Platform abstraction:
+  src/server/services/bot/platforms/index.ts                — registry singleton + exports
+  src/server/services/bot/platforms/types.ts                — PlatformClient/Definition/FieldSchema/ClientFactory
+  src/server/services/bot/platforms/registry.ts             — PlatformRegistry class
+  src/server/services/bot/platforms/utils.ts                — mergeWithDefaults, getEffectiveConnectionMode, formatUsageStats, runtimeKey
+  src/server/services/bot/platforms/const.ts                — shared FieldSchema fragments (displayToolCalls, serverId, userId)
+  src/server/services/bot/platforms/stripMarkdown.ts        — used by no-markdown platforms
+
+Per-platform (each ships definition.ts, schema.ts, client.ts, const.ts, protocol-spec.md):
+  src/server/services/bot/platforms/discord/                — websocket gateway + chat patches
+  src/server/services/bot/platforms/slack/                  — multi-mode (Socket Mode / webhook), markdownToMrkdwn
+  src/server/services/bot/platforms/telegram/               — webhook, markdownToHTML, registerBotCommands
+  src/server/services/bot/platforms/feishu/                 — feishu + lark share client/schema (definitions/{feishu,lark,shared}.ts)
+  src/server/services/bot/platforms/qq/                     — websocket, no markdown, no edit
+  src/server/services/bot/platforms/wechat/                 — long-poll, no markdown, no edit
+
+Gateway:
+  src/server/services/gateway/index.ts                      — GatewayService (Vercel-aware startClient/stopClient)
+  src/server/services/gateway/GatewayManager.ts             — long-running client registry (non-Vercel)
+  src/server/services/gateway/botConnectQueue.ts            — Redis hash queue with TTL
+  src/server/services/gateway/runtimeStatus.ts              — Redis bot:runtime-status keys
+
+Database:
+  packages/database/src/schemas/agentBotProvider.ts         — agent_bot_providers table
+  packages/database/src/models/agentBotProvider.ts          — encrypted CRUD + system-wide finders
+
+TRPC + client:
+  src/server/routers/lambda/agentBotProvider.ts             — TRPC router
+  src/services/agentBotProvider.ts                          — client wrapper
+  src/store/agent/slices/bot/action.ts                      — Zustand actions
+
+UI:
+  src/routes/(main)/agent/channel/list.tsx                  — channel list
+  src/routes/(main)/agent/channel/detail/                   — auto-generated form (Header/Body/Footer)
+  src/routes/(main)/agent/channel/const.ts                  — platform icons
+
+Types & runtime status:
+  src/types/botRuntimeStatus.ts                             — BOT_RUNTIME_STATUSES enum + snapshot type
+```
+
+## Adding a New Platform
+
+1. Create `src/server/services/bot/platforms/<id>/`:
+   - `definition.ts` — `PlatformDefinition` registered in `platforms/index.ts`
+   - `schema.ts` — `FieldSchema[]` (`applicationId` + `credentials` + `settings`); reuse fragments from `../const.ts`
+   - `client.ts` — `class XClientFactory extends ClientFactory` returning a `PlatformClient` (lifecycle + adapter + messenger + helpers)
+   - `const.ts` — `DEFAULT_X_CONNECTION_MODE`, history limits, etc.
+   - `protocol-spec.md` — protocol notes (every existing platform has one)
+2. Pick the right `connectionMode` — webhook is much simpler if the platform supports it.
+3. If the platform can't render markdown, set `supportsMarkdown: false` and implement `formatMarkdown` via `stripMarkdown`.
+4. If it can't edit messages, set `supportsMessageEdit: false` — `BotCallbackService` will skip step edits and only send the final reply.
+5. Implement `validateCredentials` so the UI's "Test connection" button gives useful errors.
+6. Add the platform icon in `src/routes/(main)/agent/channel/const.ts` and register the platform in `src/server/services/bot/platforms/index.ts`.
+7. Add i18n keys under `channel.*` in `src/locales/default/setting.ts` (or wherever the channel namespace lives) — the schema's `label`/`description`/`placeholder`/`enumLabels` are i18n keys.
@@ -46,7 +46,7 @@ description: 'Code review checklist for LobeHub. Use when reviewing PRs, diffs,
 - Newly written code duplicates existing utilities in `packages/utils` or shared modules?
 - Copy-pasted blocks with slight variation — extract into shared function
 - `antd` imports replaceable with `@lobehub/ui` wrapped components (`Input`, `Button`, `Modal`, `Avatar`, etc.)
- Use `antd-style` token system, not hardcoded colors
+- Use `antd-style` token system, not hardcoded colors; prefer `createStaticStyles` + `cssVar.*` over `createStyles` + `token` unless runtime computation is required

 ### Database

@@ -0,0 +1,155 @@
+---
+name: docs-changelog
+description: 'Writing guide for website changelog pages under docs/changelog/*.mdx. Use when creating or editing product update posts in EN/ZH. Not for GitHub Release notes.'
+---
+
+# Docs Changelog Writing Guide
+
+## Scope Boundary (Important)
+
+This skill is only for changelog pages in:
+
+- `docs/changelog/*.mdx`
+
+This skill is **not** for GitHub Releases.\
+If the user asks for release PR body / GitHub Release notes, load `../version-release/SKILL.md`.
+
+## Mandatory Companion Skills
+
+For every docs changelog task, you MUST load:
+
+- `../microcopy/SKILL.md`
+- `../i18n/SKILL.md` (when EN/ZH pair is involved)
+
+## File and Naming Convention
+
+Use date-based file names:
+
+- English: `docs/changelog/YYYY-MM-DD-topic.mdx`
+- Chinese: `docs/changelog/YYYY-MM-DD-topic.zh-CN.mdx`
+
+EN and ZH files must exist as a pair and describe the same release facts.
+
+## Frontmatter Requirements
+
+Each file should include:
+
+```md
+---
+title: <Title>
+description: <1 sentence summary>
+tags:
+  - <Tag 1>
+  - <Tag 2>
+---
+```
+
+Rules:
+
+1. `title` should match the H1 title in meaning.
+2. `description` should be concise and user-facing.
+3. `tags` should be feature-oriented, not internal-team labels.
+
+## Content Structure (Recommended)
+
+Use this shape unless the user requests otherwise:
+
+1. `# <Title>`
+2. Opening paragraph (2-4 sentences): user-visible impact
+3. 1-3 capability sections (optional `##` headings)
+4. `## Improvements and fixes` / `## 体验优化与修复` with concise bullets
+
+Keep heading count low and avoid heading-per-bullet structure.
+
+## Writing Rules
+
+1. Keep all claims factual and tied to actual shipped changes.
+2. Explain user value first, implementation second.
+3. Prefer natural narrative paragraphs over pure bullet dumps.
+4. Avoid marketing exaggeration and vague adjectives.
+5. Keep internal terms consistent across EN/ZH files.
+6. Keep EN/ZH section order aligned and scope-aligned.
+
+## EN/ZH Synchronization Rules
+
+When generating bilingual changelogs:
+
+1. Keep the same key facts in the same order.
+2. Localize naturally; do not do literal sentence-by-sentence translation.
+3. If one version has an `Improvements and fixes` bullet list, the other should have equivalent list intent.
+4. Do not introduce capabilities in only one language unless explicitly requested.
+
+## Length Guidance
+
+- Small update: 3-5 short paragraphs total
+- Medium update: 4-7 short paragraphs + concise fix bullets
+- Large update: 6-10 short paragraphs split into 2-4 sections
+
+Do not pad content when changes are limited.
+
+## Authoring Workflow
+
+1. Collect source facts from PRs/commits/issues.
+2. Group changes by user workflow (not by internal module path).
+3. Draft EN and ZH versions with aligned structure.
+4. Verify terminology using `microcopy`/`i18n` guidance.
+5. Final pass: remove AI-like filler and tighten sentences.
+
+## Docs Changelog Template (English)
+
+```md
+---
+title: <Feature title>
+description: <One-sentence summary for users>
+tags:
+  - <Tag A>
+  - <Tag B>
+---
+
+# <Feature title>
+
+<Opening paragraph: what changed for users and why it matters.>
+
+<Optional section paragraph for key capability 1.>
+
+<Optional section paragraph for key capability 2.>
+
+## Improvements and fixes
+
+- <Fix or optimization 1>
+- <Fix or optimization 2>
+```
+
+## Docs Changelog Template (Chinese)
+
+```md
+---
+title: <功能标题>
+description: <一句话说明>
+tags:
+  - <标签 A>
+  - <标签 B>
+---
+
+# <功能标题>
+
+<开场段：这次更新给用户带来的直接变化。>
+
+<可选能力段 1。>
+
+<可选能力段 2。>
+
+## 体验优化与修复
+
+- <优化或修复 1>
+- <优化或修复 2>
+```
+
+## Quick Checklist
+
+- [ ] File path matches `docs/changelog` naming convention
+- [ ] EN and ZH versions both exist and match in facts
+- [ ] Opening paragraph explains user-facing outcome
+- [ ] Main body is narrative-first, not bullet-only
+- [ ] `Improvements and fixes` section is concise and concrete
+- [ ] No fabricated claims or unsupported scope
@@ -5,7 +5,7 @@ description: Internationalization guide using react-i18next. Use when adding tra

 # LobeHub Internationalization Guide

- Default language: Chinese (zh-CN)
+- Default language: English (en-US)
 - Framework: react-i18next
 - **Only edit files in `src/locales/default/`** - Never edit JSON files in `locales/`
 - Run `pnpm i18n` to generate translations (or manually translate zh-CN/en-US for dev preview)
@@ -30,6 +30,63 @@ This is NON-NEGOTIABLE. Skipping Linear comments is a workflow violation.

 When creating issues with `mcp__linear-server__create_issue`, **MUST add the `claude code` label**.

+## 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
+
+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.
+
+**Workaround**: encode execution order in the title itself:
+
+```plaintext
+[1]     [db]       add schema fields
+[2]     [db]       new table + repository
+[3]     [service]  business logic layer
+[4]     [api]      REST endpoints
+[4.1]   [sdk]      client SDK wrapper
+[4.1.1] [app]      consumer integration
+[4.1.2] [app]      UI surface
+[4.2]   [ui]       dashboard page
+```
+
+Even when the panel shuffles, the reader can mentally reconstruct the dependency graph at a glance. Dotted numbering `[n.m.k]` should mirror the parent-child nesting so the index and the tree agree.
+
+### 2. Nest sub-issues by logical parent-child, not flat under the root
+
+Linear supports **unlimited sub-issue depth**. A flat list of 8+ siblings under one root is hard to scan. Group by main-subordinate logic:
+
+- Core service → its SDK → SDK consumers
+- Don't create a sibling when a child is more accurate
+
+Use `parentId: "LOBE-xxxx"` at creation (or `save_issue` to move). Moving an issue's parent does not disturb its `blockedBy` relations.
+
+### 3. Sub-issue creation order is dictated by `blockedBy`
+
+`blockedBy` requires the blocker to exist first (you need its LOBE-id). So:
+
+1. **Topologically sort** the DAG — leaves (no deps) first, roots last
+2. Create issues with zero deps in the first wave
+3. Create dependent issues only after collecting the blocker IDs from prior responses
+4. `blockedBy` is **append-only**; passing it again does not overwrite — safe to re-run
+
+### 4. Don't waste rounds trying to parallelize
+
+MCP tool calls in a single message look parallel but execute sequentially on the server, and you still need blocker IDs from earlier responses. Just issue calls in dependency order; optimizing for parallelism gains nothing here.
+
+### 5. Keep each sub-issue description self-contained
+
+Each sub-issue should state:
+
+- Goal (1–2 lines)
+- Key files to touch
+- Concrete changes / acceptance criteria
+- Dependencies (link to blocker issues by `LOBE-xxxx`)
+- Validation steps
+
+The implementer may open only the sub-issue, not the parent — don't rely on context that lives only in the parent description.
+
 ## Completion Comment Format

 Every completed issue MUST have a comment summarizing work done:
@@ -173,6 +173,10 @@ agent-browser state save auth.json
 agent-browser state load auth.json
 ```

+### LobeHub dev server — inject better-auth cookie
+
+`agent-browser --headed` on macOS can create an off-screen Chromium window, blocking manual login. For a local LobeHub dev server (e.g. `localhost:3011`), copy the `better-auth.session_token` cookie out of a **Network request** in the user's own Chrome DevTools and load it via `state load`. See [references/agent-browser-login.md](./references/agent-browser-login.md) for the full recipe.
+
 ## Semantic Locators (Alternative to Refs)

 ```bash
@@ -379,621 +383,30 @@ agent-browser --auto-connect snapshot -i

 # Part 2: osascript (Native macOS App Bot Testing)

-Use AppleScript via `osascript` to control native macOS desktop apps for bot testing. This works with any app that supports macOS Accessibility, without needing CDP or Chromium.
+Use AppleScript via `osascript` to control native macOS desktop apps for bot testing. Works with any app that supports macOS Accessibility, no CDP or Chromium needed.

-## Core osascript Patterns
+The pattern is the same for every platform:

-### Activate an App
+1. **Activate** the app (`tell application "X" to activate`)
+2. **Navigate** to a channel/chat (Quick Switcher `Cmd+K` or Search `Cmd+F`)
+3. **Send** a message (clipboard paste `Cmd+V` + Enter)
+4. **Wait** for the bot response
+5. **Screenshot** for verification (`screencapture` + `Read` tool)

-```bash
-osascript -e 'tell application "Discord" to activate'
-```
+## Per-Platform References

-### Type Text
+Pick the file for your target platform — each contains activation, navigation, send-message, and verification snippets specific to that app:

-```bash
-# Type character by character (reliable, but slow for long text)
-osascript -e 'tell application "System Events" to keystroke "Hello world"'
+| Platform      | Reference                                          | Quick switcher |
+| ------------- | -------------------------------------------------- | -------------- |
+| Discord       | [references/discord.md](./references/discord.md)   | `Cmd+K`        |
+| Slack         | [references/slack.md](./references/slack.md)       | `Cmd+K`        |
+| Telegram      | [references/telegram.md](./references/telegram.md) | `Cmd+F`        |
+| WeChat / 微信 | [references/wechat.md](./references/wechat.md)     | `Cmd+F`        |
+| Lark / 飞书   | [references/lark.md](./references/lark.md)         | `Cmd+K`        |
+| QQ            | [references/qq.md](./references/qq.md)             | `Cmd+F`        |

-# Press Enter
-osascript -e 'tell application "System Events" to key code 36'
-
-# Press Tab
-osascript -e 'tell application "System Events" to key code 48'
-
-# Press Escape
-osascript -e 'tell application "System Events" to key code 53'
-```
-
-### Paste from Clipboard (fast, for long text)
-
-```bash
-# Set clipboard and paste — much faster than keystroke for long messages
-osascript -e 'set the clipboard to "Your long message here"'
-osascript -e 'tell application "System Events" to keystroke "v" using command down'
-```
-
-Or in one shot:
-
-```bash
-osascript -e '
-set the clipboard to "Your long message here"
-tell application "System Events" to keystroke "v" using command down
-'
-```
-
-### Keyboard Shortcuts
-
-```bash
-# Cmd+K (quick switcher in Discord/Slack)
-osascript -e 'tell application "System Events" to keystroke "k" using command down'
-
-# Cmd+F (search)
-osascript -e 'tell application "System Events" to keystroke "f" using command down'
-
-# Cmd+N (new message/chat)
-osascript -e 'tell application "System Events" to keystroke "n" using command down'
-
-# Cmd+Shift+K (example: multi-modifier)
-osascript -e 'tell application "System Events" to keystroke "k" using {command down, shift down}'
-```
-
-### Click at Position
-
-```bash
-# Click at absolute screen coordinates
-osascript -e '
-tell application "System Events"
-    click at {500, 300}
-end tell
-'
-```
-
-### Get Window Info
-
-```bash
-# Get window position and size
-osascript -e '
-tell application "System Events"
-    tell process "Discord"
-        get {position, size} of window 1
-    end tell
-end tell
-'
-```
-
-### Screenshot
-
-```bash
-# Full screen
-screencapture /tmp/screenshot.png
-
-# Interactive region select
-screencapture -i /tmp/screenshot.png
-
-# Specific window (by window ID from CGWindowList)
-screencapture -l < WINDOW_ID > /tmp/screenshot.png
-```
-
-To get window ID for a specific app:
-
-```bash
-osascript -e '
-tell application "System Events"
-    tell process "Discord"
-        get id of window 1
-    end tell
-end tell
-'
-```
-
-### Read Accessibility Elements
-
-```bash
-# Get all UI elements of the frontmost window (can be slow/large)
-osascript -e '
-tell application "System Events"
-    tell process "Discord"
-        entire contents of window 1
-    end tell
-end tell
-'
-
-# Get a specific element's value
-osascript -e '
-tell application "System Events"
-    tell process "Discord"
-        get value of text field 1 of window 1
-    end tell
-end tell
-'
-```
-
-> **Warning:** `entire contents` can be extremely slow on complex UIs. Prefer screenshots + `Read` tool for visual verification.
-
-### Read Screen Text via Clipboard
-
-For reading the latest message or response from an app:
-
-```bash
-# Select all text in the focused area and copy
-osascript -e '
-tell application "System Events"
-    keystroke "a" using command down
-    keystroke "c" using command down
-end tell
-'
-sleep 0.5
-# Read clipboard
-pbpaste
-```
-
---
-
-## Client: Discord
-
-**App name:** `Discord` | **Process name:** `Discord`
-
-### Activate & Navigate
-
-```bash
-# Activate Discord
-osascript -e 'tell application "Discord" to activate'
-sleep 1
-
-# Open Quick Switcher (Cmd+K) to navigate to a channel
-osascript -e 'tell application "System Events" to keystroke "k" using command down'
-sleep 0.5
-osascript -e 'tell application "System Events" to keystroke "bot-testing"'
-sleep 1
-osascript -e 'tell application "System Events" to key code 36' # Enter
-sleep 2
-```
-
-### Send Message to Bot
-
-```bash
-# The message input is focused after navigating to a channel
-# Type a message
-osascript -e 'tell application "System Events" to keystroke "/hello"'
-sleep 0.5
-osascript -e 'tell application "System Events" to key code 36' # Enter
-```
-
-### Send Long Message (via clipboard)
-
-```bash
-osascript -e '
-tell application "Discord" to activate
-delay 0.5
-set the clipboard to "Write a 3000 word essay about space exploration"
-tell application "System Events"
-    keystroke "v" using command down
-    delay 0.3
-    key code 36  -- Enter
-end tell
-'
-```
-
-### Verify Bot Response
-
-```bash
-# Wait for bot to respond, then screenshot
-sleep 10
-screencapture /tmp/discord-bot-response.png
-# Read with the Read tool for visual verification
-```
-
-### Full Bot Test Example
-
-```bash
-#!/usr/bin/env bash
-# test-discord-bot.sh — Send message and verify bot response
-
-# 1. Activate Discord and navigate to channel
-osascript -e '
-tell application "Discord" to activate
-delay 1
-- Quick Switcher
-tell application "System Events" to keystroke "k" using command down
-delay 0.5
-tell application "System Events" to keystroke "bot-testing"
-delay 1
-tell application "System Events" to key code 36
-delay 2
-'
-
-# 2. Send test message
-osascript -e '
-set the clipboard to "!ping"
-tell application "System Events"
-    keystroke "v" using command down
-    delay 0.3
-    key code 36
-end tell
-'
-
-# 3. Wait for response and capture
-sleep 5
-screencapture /tmp/discord-test-result.png
-echo "Screenshot saved to /tmp/discord-test-result.png"
-```
-
---
-
-## Client: Slack
-
-**App name:** `Slack` | **Process name:** `Slack`
-
-### Activate & Navigate
-
-```bash
-# Activate Slack
-osascript -e 'tell application "Slack" to activate'
-sleep 1
-
-# Quick Switcher (Cmd+K)
-osascript -e 'tell application "System Events" to keystroke "k" using command down'
-sleep 0.5
-osascript -e 'tell application "System Events" to keystroke "bot-testing"'
-sleep 1
-osascript -e 'tell application "System Events" to key code 36' # Enter
-sleep 2
-```
-
-### Send Message to Bot
-
-```bash
-# Direct message input (focused after channel nav)
-osascript -e 'tell application "System Events" to keystroke "@mybot hello"'
-sleep 0.3
-osascript -e 'tell application "System Events" to key code 36'
-```
-
-### Send Long Message
-
-```bash
-osascript -e '
-tell application "Slack" to activate
-delay 0.5
-set the clipboard to "A long test message for the bot..."
-tell application "System Events"
-    keystroke "v" using command down
-    delay 0.3
-    key code 36
-end tell
-'
-```
-
-### Slash Command Test
-
-```bash
-osascript -e '
-tell application "Slack" to activate
-delay 0.5
-tell application "System Events"
-    keystroke "/ask What is the meaning of life?"
-    delay 0.5
-    key code 36
-end tell
-'
-```
-
-### Verify Response
-
-```bash
-sleep 10
-screencapture /tmp/slack-bot-response.png
-```
-
---
-
-## Client: Telegram
-
-**App name:** `Telegram` | **Process name:** `Telegram`
-
-### Activate & Navigate
-
-```bash
-# Activate Telegram
-osascript -e 'tell application "Telegram" to activate'
-sleep 1
-
-# Search for a bot (Cmd+F or click search)
-osascript -e '
-tell application "System Events"
-    keystroke "f" using command down
-    delay 0.5
-    keystroke "MyTestBot"
-    delay 1
-    key code 36  -- Enter to select
-end tell
-'
-sleep 2
-```
-
-### Send Message to Bot
-
-```bash
-# After navigating to bot chat, input is focused
-osascript -e '
-tell application "System Events"
-    keystroke "/start"
-    delay 0.3
-    key code 36
-end tell
-'
-```
-
-### Send Long Message
-
-```bash
-osascript -e '
-tell application "Telegram" to activate
-delay 0.5
-set the clipboard to "Tell me about quantum computing in detail"
-tell application "System Events"
-    keystroke "v" using command down
-    delay 0.3
-    key code 36
-end tell
-'
-```
-
-### Verify Response
-
-```bash
-sleep 10
-screencapture /tmp/telegram-bot-response.png
-```
-
-### Telegram Bot API (programmatic alternative)
-
-For sending messages directly to the bot's chat without UI:
-
-```bash
-# Send message as the bot (for testing webhooks/responses)
-curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
-  -d "chat_id=$CHAT_ID&text=test message"
-
-# Get recent updates
-curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?limit=5" | jq .
-```
-
---
-
-## Client: WeChat / 微信
-
-**App name:** `微信` or `WeChat` | **Process name:** `WeChat`
-
-### Activate & Navigate
-
-```bash
-# Activate WeChat
-osascript -e 'tell application "微信" to activate'
-sleep 1
-
-# Search for a contact/bot (Cmd+F)
-osascript -e '
-tell application "System Events"
-    keystroke "f" using command down
-    delay 0.5
-    keystroke "TestBot"
-    delay 1
-    key code 36  -- Enter to select
-end tell
-'
-sleep 2
-```
-
-### Send Message
-
-```bash
-# After navigating to a chat, the input is focused
-osascript -e '
-tell application "System Events"
-    keystroke "Hello bot!"
-    delay 0.3
-    key code 36
-end tell
-'
-```
-
-### Send Long Message (clipboard)
-
-```bash
-osascript -e '
-tell application "微信" to activate
-delay 0.5
-set the clipboard to "Please help me with this task..."
-tell application "System Events"
-    keystroke "v" using command down
-    delay 0.3
-    key code 36
-end tell
-'
-```
-
-### Verify Response
-
-```bash
-sleep 10
-screencapture /tmp/wechat-bot-response.png
-```
-
-### WeChat-Specific Notes
-
- WeChat macOS app name can be `微信` or `WeChat` depending on system language. Try both:
-  ```bash
-  osascript -e 'tell application "微信" to activate' 2> /dev/null \
-    || osascript -e 'tell application "WeChat" to activate'
-  ```
- WeChat uses **Enter** to send (not Cmd+Enter by default, but configurable)
- For multi-line messages without sending, use **Shift+Enter**:
-  ```bash
-  osascript -e 'tell application "System Events" to key code 36 using shift down'
-  ```
-
---
-
-## Client: Lark / 飞书
-
-**App name:** `Lark` or `飞书` | **Process name:** `Lark` or `飞书`
-
-### Activate & Navigate
-
-```bash
-# Activate Lark (auto-detects Lark or 飞书)
-osascript -e 'tell application "Lark" to activate' 2> /dev/null \
-  || osascript -e 'tell application "飞书" to activate'
-sleep 1
-
-# Quick Switcher / Search (Cmd+K)
-osascript -e 'tell application "System Events" to keystroke "k" using command down'
-sleep 0.5
-osascript -e '
-set the clipboard to "bot-testing"
-tell application "System Events"
-    keystroke "v" using command down
-    delay 1.5
-    key code 36  -- Enter
-end tell
-'
-sleep 2
-```
-
-### Send Message to Bot
-
-```bash
-osascript -e '
-set the clipboard to "@MyBot help me with this task"
-tell application "System Events"
-    keystroke "v" using command down
-    delay 0.3
-    key code 36  -- Enter
-end tell
-'
-```
-
-### Verify Response
-
-```bash
-sleep 10
-screencapture /tmp/lark-bot-response.png
-```
-
-### Lark-Specific Notes
-
- App name varies: `Lark` (international) vs `飞书` (China mainland) — the script auto-detects
- Uses `Cmd+K` for quick search (same as Discord/Slack)
- Enter sends message by default
-
---
-
-## Client: QQ
-
-**App name:** `QQ` | **Process name:** `QQ`
-
-### Activate & Navigate
-
-```bash
-osascript -e 'tell application "QQ" to activate'
-sleep 1
-
-# Search for contact/group (Cmd+F)
-osascript -e '
-tell application "System Events"
-    keystroke "f" using command down
-    delay 0.8
-end tell
-'
-osascript -e '
-set the clipboard to "bot-testing"
-tell application "System Events"
-    keystroke "v" using command down
-    delay 1.5
-    key code 36  -- Enter
-end tell
-'
-sleep 2
-```
-
-### Send Message to Bot
-
-```bash
-osascript -e '
-set the clipboard to "Hello bot!"
-tell application "System Events"
-    keystroke "v" using command down
-    delay 0.3
-    key code 36  -- Enter
-end tell
-'
-```
-
-### Verify Response
-
-```bash
-sleep 10
-screencapture /tmp/qq-bot-response.png
-```
-
-### QQ-Specific Notes
-
- Enter sends message by default; Shift+Enter for newlines
- Uses `Cmd+F` for search
- Always use clipboard paste for CJK characters
-
---
-
-## Common Bot Testing Workflow (osascript)
-
-Regardless of platform, the pattern is:
-
-```bash
-APP_NAME="Discord" # or "Slack", "Telegram", "微信"
-CHANNEL="bot-testing"
-MESSAGE="Hello bot!"
-WAIT_SECONDS=10
-
-# 1. Activate
-osascript -e "tell application \"$APP_NAME\" to activate"
-sleep 1
-
-# 2. Navigate to channel/chat (via Quick Switcher or Search)
-osascript -e 'tell application "System Events" to keystroke "k" using command down'
-sleep 0.5
-osascript -e "tell application \"System Events\" to keystroke \"$CHANNEL\""
-sleep 1
-osascript -e 'tell application "System Events" to key code 36'
-sleep 2
-
-# 3. Send message
-osascript -e "set the clipboard to \"$MESSAGE\""
-osascript -e '
-tell application "System Events"
-    keystroke "v" using command down
-    delay 0.3
-    key code 36
-end tell
-'
-
-# 4. Wait for bot response
-sleep "$WAIT_SECONDS"
-
-# 5. Screenshot for verification
-screencapture /tmp/"${APP_NAME,,}"-bot-test.png
-echo "Result saved to /tmp/${APP_NAME,,}-bot-test.png"
-```
-
-### Tips
-
- **Use clipboard paste** (`Cmd+V`) for messages containing special characters or long text — `keystroke` can mangle non-ASCII
- **Add `delay`** between actions — apps need time to process UI events
- **Screenshot for verification** — use `screencapture` + `Read` tool for visual checks
- **Use a dedicated test channel/chat** — avoid polluting real conversations
- **Check app name** — some apps have different names in different locales (e.g., `微信` vs `WeChat`)
- **Accessibility permissions required** — System Events automation requires granting Accessibility access in System Preferences > Privacy & Security > Accessibility
+For **shared osascript patterns** (activate, type, paste, screenshot, read accessibility, common workflow template, gotchas), see [references/osascript-common.md](./references/osascript-common.md). Read this first if you're new to osascript automation.

 ---

@@ -1006,6 +419,7 @@ Ready-to-use scripts in `.agents/skills/local-testing/scripts/`:
 | `electron-dev.sh`         | Manage Electron dev env (start/stop/status/restart) |
 | `capture-app-window.sh`   | Capture screenshot of a specific app window         |
 | `record-electron-demo.sh` | Record Electron app demo with ffmpeg                |
+| `record-app-screen.sh`    | Record app screen (video + screenshots, start/stop) |
 | `test-discord-bot.sh`     | Send message to Discord bot via osascript           |
 | `test-slack-bot.sh`       | Send message to Slack bot via osascript             |
 | `test-telegram-bot.sh`    | Send message to Telegram bot via osascript          |
@@ -1068,25 +482,16 @@ Each script: activates the app, navigates to the channel/contact, pastes the mes

 # Screen Recording

-Record automated demos by combining `ffmpeg` screen capture with `agent-browser` automation. The script `.agents/skills/local-testing/scripts/record-electron-demo.sh` handles the full lifecycle for Electron.
-
-### Usage
+Record automated demos using `record-app-screen.sh` (start/stop lifecycle, CDP screenshots + ffmpeg assembly). See [references/record-app-screen.md](references/record-app-screen.md) for full documentation.

 ```bash
-# Run the built-in demo (queue-edit feature)
-./.agents/skills/local-testing/scripts/record-electron-demo.sh
-
-# Run a custom automation script
-./.agents/skills/local-testing/scripts/record-electron-demo.sh ./my-demo.sh /tmp/my-demo.mp4
+./.agents/skills/local-testing/scripts/electron-dev.sh start
+./.agents/skills/local-testing/scripts/record-app-screen.sh start my-demo
+# ... run automation ...
+./.agents/skills/local-testing/scripts/record-app-screen.sh stop
 ```

-The script automatically:
-
-1. Starts Electron with CDP and waits for SPA to load
-2. Detects window position, screen, and Retina scale via Swift/CGWindowList
-3. Records only the Electron window region using `ffmpeg -f avfoundation` with crop
-4. Runs the demo (built-in or custom script receiving CDP port as `$1`)
-5. Stops recording and cleans up
+Outputs to `.records/` directory (gitignored): `<name>.mp4` (video) + `<name>/` (screenshots every 3s).

 ---

@@ -1112,14 +517,4 @@ The script automatically:

 ### osascript

- **Accessibility permission required** — first run will prompt for access; grant it in System Preferences > Privacy & Security > Accessibility for Terminal / iTerm / Claude Code
- **`keystroke` is slow for long text** — always use clipboard paste (`Cmd+V`) for messages over \~20 characters
- **`keystroke` can mangle non-ASCII** — use clipboard paste for Chinese, emoji, or special characters
- **`key code 36` is Enter** — this is the hardware key code, works regardless of keyboard layout
- **`entire contents` is extremely slow** — avoid for complex UIs; use screenshots instead
- **App name varies by locale** — `微信` vs `WeChat`, `企业微信` vs `WeCom`; handle both
- **WeChat Enter sends immediately** — use `Shift+Enter` for newlines within a message
- **Rate limiting** — don't send messages too fast; platforms may throttle or flag automated input
- **Lark / 飞书 app name varies** — `Lark` (international) vs `飞书` (China mainland); scripts auto-detect
- **QQ uses `Cmd+F` for search** — not `Cmd+K` like Discord/Slack/Lark
- **Bot response times vary** — AI-powered bots may take 10-60s; use generous sleep values
+See [references/osascript-common.md](./references/osascript-common.md#gotchas) for the full osascript gotchas list (accessibility permissions, `keystroke` non-ASCII issues, locale-specific app names, rate limiting, etc.).
@@ -0,0 +1,110 @@
+# Log `agent-browser` into a local LobeHub dev server
+
+`agent-browser --headed` on macOS often creates the Chromium window off-screen — the user can't see or interact with it, so manual login inside the agent-browser session fails. Instead of sharing the user's real Chrome profile, copy the **better-auth session cookie** out of a request in DevTools and inject it into the agent-browser session as a Playwright-style state file.
+
+## When to use
+
+- You need `agent-browser` to reach an authenticated page on `http://localhost:<port>` (e.g. `localhost:3011`).
+- The user already has a logged-in tab of the same dev server in their own Chrome.
+- Spawning a headed Chromium to let the user log in manually is unreliable (window off-screen, no interaction).
+
+Do **not** use this on production URLs — only local dev. Treat the cookie as a secret: don't paste it into shared logs, PRs, or commit it anywhere.
+
+## Step 1 — Ask the user to copy the cookie from a Network request, NOT `document.cookie`
+
+`document.cookie` will not return HttpOnly cookies, which is exactly where better-auth puts its session. Instruct the user:
+
+1. Open the logged-in tab (`http://localhost:<port>/…`) in their own Chrome.
+2. `Cmd+Option+I` → **Network** tab.
+3. Refresh, click any same-origin request (e.g. the top-level document request).
+4. In the right pane under **Request Headers**, right-click the `Cookie:` line → **Copy value** (or copy the entire header).
+5. Paste the string into chat.
+
+You only need the better-auth pieces. Everything else (Clerk, `LOBE_LOCALE`, HMR hash, theme vars) is noise and can stay. The minimum viable set is:
+
+```
+better-auth.session_token=<value>; better-auth.state=<value>
+```
+
+## Step 2 — Build a Playwright-style state file
+
+`agent-browser state load` expects Playwright's `storageState` format: a JSON with a `cookies` array and an `origins` array.
+
+```bash
+cat > /tmp/mkstate.py << 'PY'
+import json, sys, time
+
+# Read the Cookie header from stdin (allows optional "Cookie: " prefix).
+raw = sys.stdin.read().strip()
+if raw.lower().startswith("cookie:"):
+    raw = raw.split(":", 1)[1].strip()
+
+# Keep only better-auth cookies. Extend this set if the app genuinely needs more.
+WANTED = {"better-auth.session_token", "better-auth.state"}
+
+cookies = []
+exp = int(time.time()) + 30 * 24 * 3600  # 30 days
+for pair in raw.split("; "):
+    if "=" not in pair:
+        continue
+    name, _, value = pair.partition("=")
+    if name not in WANTED:
+        continue
+    cookies.append({
+        "name": name,
+        "value": value,
+        "domain": "localhost",
+        "path": "/",
+        "expires": exp,
+        "httpOnly": False,
+        "secure": False,
+        "sameSite": "Lax",
+    })
+
+if not cookies:
+    sys.stderr.write("no better-auth cookies found in input\n")
+    sys.exit(1)
+
+print(json.dumps({"cookies": cookies, "origins": []}, indent=2))
+PY
+
+# Feed the copied Cookie header in via env var or heredoc.
+printf '%s' "$COOKIE_HEADER" | python3 /tmp/mkstate.py > /tmp/state.json
+```
+
+**Note on `httpOnly`**: the real cookie in the user's browser is HttpOnly, but `storageState` doesn't enforce the flag on load — it just attaches the value. Storing with `httpOnly: false` is fine for local dev and sidesteps a CDP-context quirk where HttpOnly cookies sometimes fail to attach.
+
+## Step 3 — Load state and navigate
+
+```bash
+SESSION="my-test" # any stable session name
+
+agent-browser --session "$SESSION" state load /tmp/state.json
+agent-browser --session "$SESSION" open "http://localhost:3011/"
+agent-browser --session "$SESSION" get url
+# Expect NOT /signin?callbackUrl=… — if you still see signin, cookie didn't apply.
+```
+
+## Step 4 — Verify
+
+```bash
+agent-browser --session "$SESSION" snapshot -i | head -20
+# Look for the user's avatar/name in the sidebar, or absence of the signin form.
+```
+
+## Common failure modes
+
+| Symptom                                         | Cause                                                                   | Fix                                                  |
+| ----------------------------------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------- |
+| Still redirects to `/signin` after `state load` | User pasted from `document.cookie` → missed HttpOnly session            | Re-pull from Network request Headers, not console    |
+| `state load` reports 0 cookies                  | Separator wrong, or user pasted URL-decoded value                       | Keep the raw `Cookie:` header as-is; split on `"; "` |
+| Login works briefly then expires                | `better-auth.session_token` rotated (user logged out / signed in again) | Re-copy and re-load                                  |
+| Domain mismatch                                 | Use `domain: "localhost"` literally, no leading dot for local dev       | —                                                    |
+
+## Scope
+
+Only covers authenticating an **agent-browser** session into a **local** LobeHub dev server. It does not:
+
+- Work for production — production cookies are `Secure; HttpOnly; Domain=.lobehub.com` and must be delivered over HTTPS.
+- Replace real OAuth flows — tests that must exercise the login UI need a real Chromium with `--remote-debugging-port` or a bot account.
+- Flow cookies back to the user's Chrome — injection is one-way (into agent-browser only).
@@ -0,0 +1,97 @@
+# Discord Bot Testing
+
+**App name:** `Discord` | **Process name:** `Discord`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate Discord
+osascript -e 'tell application "Discord" to activate'
+sleep 1
+
+# Open Quick Switcher (Cmd+K) to navigate to a channel
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+sleep 0.5
+osascript -e 'tell application "System Events" to keystroke "bot-testing"'
+sleep 1
+osascript -e 'tell application "System Events" to key code 36' # Enter
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+# The message input is focused after navigating to a channel
+# Type a message
+osascript -e 'tell application "System Events" to keystroke "/hello"'
+sleep 0.5
+osascript -e 'tell application "System Events" to key code 36' # Enter
+```
+
+## Send Long Message (via clipboard)
+
+```bash
+osascript -e '
+tell application "Discord" to activate
+delay 0.5
+set the clipboard to "Write a 3000 word essay about space exploration"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+```
+
+## Verify Bot Response
+
+```bash
+# Wait for bot to respond, then screenshot
+sleep 10
+screencapture /tmp/discord-bot-response.png
+# Read with the Read tool for visual verification
+```
+
+## Full Bot Test Example
+
+```bash
+#!/usr/bin/env bash
+# test-discord-bot.sh — Send message and verify bot response
+
+# 1. Activate Discord and navigate to channel
+osascript -e '
+tell application "Discord" to activate
+delay 1
+-- Quick Switcher
+tell application "System Events" to keystroke "k" using command down
+delay 0.5
+tell application "System Events" to keystroke "bot-testing"
+delay 1
+tell application "System Events" to key code 36
+delay 2
+'
+
+# 2. Send test message
+osascript -e '
+set the clipboard to "!ping"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+
+# 3. Wait for response and capture
+sleep 5
+screencapture /tmp/discord-test-result.png
+echo "Screenshot saved to /tmp/discord-test-result.png"
+```
+
+## Script
+
+```bash
+./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "!ping"
+./.agents/skills/local-testing/scripts/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
+```
@@ -0,0 +1,61 @@
+# Lark / 飞书 Bot Testing
+
+**App name:** `Lark` or `飞书` | **Process name:** `Lark` or `飞书`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate Lark (auto-detects Lark or 飞书)
+osascript -e 'tell application "Lark" to activate' 2> /dev/null \
+  || osascript -e 'tell application "飞书" to activate'
+sleep 1
+
+# Quick Switcher / Search (Cmd+K)
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+sleep 0.5
+osascript -e '
+set the clipboard to "bot-testing"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter
+end tell
+'
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+osascript -e '
+set the clipboard to "@MyBot help me with this task"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/lark-bot-response.png
+```
+
+## Lark-Specific Notes
+
+- App name varies: `Lark` (international) vs `飞书` (China mainland) — the script auto-detects
+- Uses `Cmd+K` for quick search (same as Discord/Slack)
+- Enter sends message by default
+- Always use clipboard paste for CJK characters
+
+## Script
+
+```bash
+./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "@MyBot hello"
+./.agents/skills/local-testing/scripts/test-lark-bot.sh "bot-testing" "Help me with this" 30
+```
@@ -0,0 +1,217 @@
+# osascript Common Patterns
+
+Shared AppleScript / `osascript` patterns used by all platform bot tests. Read this first, then refer to the per-platform file for app-specific quirks.
+
+## Core Patterns
+
+### Activate an App
+
+```bash
+osascript -e 'tell application "Discord" to activate'
+```
+
+### Type Text
+
+```bash
+# Type character by character (reliable, but slow for long text)
+osascript -e 'tell application "System Events" to keystroke "Hello world"'
+
+# Press Enter
+osascript -e 'tell application "System Events" to key code 36'
+
+# Press Tab
+osascript -e 'tell application "System Events" to key code 48'
+
+# Press Escape
+osascript -e 'tell application "System Events" to key code 53'
+```
+
+### Paste from Clipboard (fast, for long text)
+
+```bash
+# Set clipboard and paste — much faster than keystroke for long messages
+osascript -e 'set the clipboard to "Your long message here"'
+osascript -e 'tell application "System Events" to keystroke "v" using command down'
+```
+
+Or in one shot:
+
+```bash
+osascript -e '
+set the clipboard to "Your long message here"
+tell application "System Events" to keystroke "v" using command down
+'
+```
+
+### Keyboard Shortcuts
+
+```bash
+# Cmd+K (quick switcher in Discord/Slack)
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+
+# Cmd+F (search)
+osascript -e 'tell application "System Events" to keystroke "f" using command down'
+
+# Cmd+N (new message/chat)
+osascript -e 'tell application "System Events" to keystroke "n" using command down'
+
+# Cmd+Shift+K (example: multi-modifier)
+osascript -e 'tell application "System Events" to keystroke "k" using {command down, shift down}'
+```
+
+### Click at Position
+
+```bash
+# Click at absolute screen coordinates
+osascript -e '
+tell application "System Events"
+    click at {500, 300}
+end tell
+'
+```
+
+### Get Window Info
+
+```bash
+# Get window position and size
+osascript -e '
+tell application "System Events"
+    tell process "Discord"
+        get {position, size} of window 1
+    end tell
+end tell
+'
+```
+
+### Screenshot
+
+```bash
+# Full screen
+screencapture /tmp/screenshot.png
+
+# Interactive region select
+screencapture -i /tmp/screenshot.png
+
+# Specific window (by window ID from CGWindowList)
+screencapture -l < WINDOW_ID > /tmp/screenshot.png
+```
+
+To get window ID for a specific app:
+
+```bash
+osascript -e '
+tell application "System Events"
+    tell process "Discord"
+        get id of window 1
+    end tell
+end tell
+'
+```
+
+### Read Accessibility Elements
+
+```bash
+# Get all UI elements of the frontmost window (can be slow/large)
+osascript -e '
+tell application "System Events"
+    tell process "Discord"
+        entire contents of window 1
+    end tell
+end tell
+'
+
+# Get a specific element's value
+osascript -e '
+tell application "System Events"
+    tell process "Discord"
+        get value of text field 1 of window 1
+    end tell
+end tell
+'
+```
+
+> **Warning:** `entire contents` can be extremely slow on complex UIs. Prefer screenshots + `Read` tool for visual verification.
+
+### Read Screen Text via Clipboard
+
+For reading the latest message or response from an app:
+
+```bash
+# Select all text in the focused area and copy
+osascript -e '
+tell application "System Events"
+    keystroke "a" using command down
+    keystroke "c" using command down
+end tell
+'
+sleep 0.5
+# Read clipboard
+pbpaste
+```
+
+---
+
+## Common Bot Testing Workflow
+
+Regardless of platform, the pattern is:
+
+```bash
+APP_NAME="Discord" # or "Slack", "Telegram", "微信"
+CHANNEL="bot-testing"
+MESSAGE="Hello bot!"
+WAIT_SECONDS=10
+
+# 1. Activate
+osascript -e "tell application \"$APP_NAME\" to activate"
+sleep 1
+
+# 2. Navigate to channel/chat (via Quick Switcher or Search)
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+sleep 0.5
+osascript -e "tell application \"System Events\" to keystroke \"$CHANNEL\""
+sleep 1
+osascript -e 'tell application "System Events" to key code 36'
+sleep 2
+
+# 3. Send message
+osascript -e "set the clipboard to \"$MESSAGE\""
+osascript -e '
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+
+# 4. Wait for bot response
+sleep "$WAIT_SECONDS"
+
+# 5. Screenshot for verification
+screencapture /tmp/"${APP_NAME,,}"-bot-test.png
+echo "Result saved to /tmp/${APP_NAME,,}-bot-test.png"
+```
+
+### Tips
+
+- **Use clipboard paste** (`Cmd+V`) for messages containing special characters or long text — `keystroke` can mangle non-ASCII
+- **Add `delay`** between actions — apps need time to process UI events
+- **Screenshot for verification** — use `screencapture` + `Read` tool for visual checks
+- **Use a dedicated test channel/chat** — avoid polluting real conversations
+- **Check app name** — some apps have different names in different locales (e.g., `微信` vs `WeChat`)
+- **Accessibility permissions required** — System Events automation requires granting Accessibility access in System Preferences > Privacy & Security > Accessibility
+
+---
+
+## Gotchas
+
+- **Accessibility permission required** — first run will prompt for access; grant it in System Preferences > Privacy & Security > Accessibility for Terminal / iTerm / Claude Code
+- **`keystroke` is slow for long text** — always use clipboard paste (`Cmd+V`) for messages over \~20 characters
+- **`keystroke` can mangle non-ASCII** — use clipboard paste for Chinese, emoji, or special characters
+- **`key code 36` is Enter** — this is the hardware key code, works regardless of keyboard layout
+- **`entire contents` is extremely slow** — avoid for complex UIs; use screenshots instead
+- **App name varies by locale** — `微信` vs `WeChat`, `企业微信` vs `WeCom`; handle both
+- **WeChat Enter sends immediately** — use `Shift+Enter` for newlines within a message
+- **Rate limiting** — don't send messages too fast; platforms may throttle or flag automated input
+- **Lark / 飞书 app name varies** — `Lark` (international) vs `飞书` (China mainland); scripts auto-detect
+- **QQ uses `Cmd+F` for search** — not `Cmd+K` like Discord/Slack/Lark
+- **Bot response times vary** — AI-powered bots may take 10-60s; use generous sleep values
@@ -0,0 +1,62 @@
+# QQ Bot Testing
+
+**App name:** `QQ` | **Process name:** `QQ`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+osascript -e 'tell application "QQ" to activate'
+sleep 1
+
+# Search for contact/group (Cmd+F)
+osascript -e '
+tell application "System Events"
+    keystroke "f" using command down
+    delay 0.8
+end tell
+'
+osascript -e '
+set the clipboard to "bot-testing"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter
+end tell
+'
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+osascript -e '
+set the clipboard to "Hello bot!"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/qq-bot-response.png
+```
+
+## QQ-Specific Notes
+
+- Enter sends message by default; Shift+Enter for newlines
+- Uses `Cmd+F` for search (not `Cmd+K` like Discord/Slack/Lark)
+- Always use clipboard paste for CJK characters
+
+## Script
+
+```bash
+./.agents/skills/local-testing/scripts/test-qq-bot.sh "bot-testing" "Hello bot" 15
+./.agents/skills/local-testing/scripts/test-qq-bot.sh "MyBot" "/help" 10
+```
@@ -0,0 +1,142 @@
+# record-app-screen.sh
+
+General-purpose screen recording tool for the Electron app. Captures CDP screenshots as video frames and gallery snapshots, then assembles into an MP4 on stop.
+
+## Why CDP Screenshots Instead of ffmpeg Screen Capture
+
+- **Works on any screen** — CDP screenshots capture the browser viewport directly, so external monitors, Retina scaling, and window positioning are all handled automatically
+- **No signal handling issues** — ffmpeg-static (npm) produces corrupt MP4 files when killed (missing moov atom). CDP screenshots avoid this entirely
+- **Consistent output** — Screenshots are resolution-independent and don't require crop coordinate calculations
+
+## Commands
+
+```bash
+# Start recording (Electron must be running with CDP)
+.agents/skills/local-testing/scripts/record-app-screen.sh start [output_name]
+
+# Stop recording and assemble video
+.agents/skills/local-testing/scripts/record-app-screen.sh stop
+
+# Check if recording is active
+.agents/skills/local-testing/scripts/record-app-screen.sh status
+```
+
+### Arguments
+
+| Argument      | Default                     | Description                |
+| ------------- | --------------------------- | -------------------------- |
+| `output_name` | `recording-YYYYMMDD-HHMMSS` | Base name for output files |
+
+### Environment Variables
+
+| Variable               | Default | Description                            |
+| ---------------------- | ------- | -------------------------------------- |
+| `CDP_PORT`             | `9222`  | Chrome DevTools Protocol port          |
+| `SCREENSHOT_INTERVAL`  | `3`     | Seconds between gallery screenshots    |
+| `VIDEO_FRAME_INTERVAL` | `0.5`   | Seconds between video frames (\~2 fps) |
+
+## Output Structure
+
+```
+.records/
+  <name>.mp4          # Video assembled from frames (~2 fps)
+  <name>/             # Gallery screenshots (every 3s)
+    0000.png
+    0001.png
+    0002.png
+    ...
+```
+
+The `.records/` directory is at the project root and is gitignored.
+
+## How It Works
+
+### Start
+
+1. Creates two background loops:
+   - **Video frames** — `agent-browser screenshot` every `VIDEO_FRAME_INTERVAL` seconds into a temp directory (`/tmp/record-frames-XXXXXX/`)
+   - **Gallery screenshots** — `agent-browser screenshot` every `SCREENSHOT_INTERVAL` seconds into `.records/<name>/`
+2. Saves PIDs and paths to `/tmp/record-app-screen.pids` and `/tmp/record-app-screen.state`
+
+### Stop
+
+1. Kills both background loops
+2. Assembles video frames into MP4 using ffmpeg:
+   ```
+   ffmpeg -framerate 2 -i frame_%06d.png -c:v libx264 -crf 23 -pix_fmt yuv420p <output>.mp4
+   ```
+3. Cleans up temp frame directory
+4. Reports file sizes and paths
+
+## Usage Examples
+
+### Basic Test Recording
+
+```bash
+# Start Electron
+.agents/skills/local-testing/scripts/electron-dev.sh start
+
+# Start recording
+.agents/skills/local-testing/scripts/record-app-screen.sh start my-test
+
+# Run automation
+agent-browser --cdp 9222 click @e61
+agent-browser --cdp 9222 type @e42 "hello"
+agent-browser --cdp 9222 press Enter
+sleep 10
+
+# Stop and get results
+.agents/skills/local-testing/scripts/record-app-screen.sh stop
+# → .records/my-test.mp4 + .records/my-test/*.png
+```
+
+### Gateway Streaming Demo
+
+```bash
+.agents/skills/local-testing/scripts/electron-dev.sh start
+
+# Inject gateway URL
+agent-browser --cdp 9222 eval --stdin << 'EOF'
+(function() {
+  var store = window.global_serverConfigStore;
+  store.setState({ serverConfig: { ...store.getState().serverConfig,
+    agentGatewayUrl: 'https://agent-gateway.lobehub.com' } });
+  return 'ready';
+})()
+EOF
+
+# Record
+.agents/skills/local-testing/scripts/record-app-screen.sh start gateway-demo
+
+# Navigate to agent, send message, wait for completion...
+# (automation commands here)
+
+.agents/skills/local-testing/scripts/record-app-screen.sh stop
+open .records/gateway-demo.mp4
+```
+
+### Check Active Recording
+
+```bash
+.agents/skills/local-testing/scripts/record-app-screen.sh status
+# [record] Active recording
+#   Frames:      42 captured (running: yes)
+#   Screenshots: 14 captured (running: yes)
+#   Output:      .records/my-test.mp4
+```
+
+## Prerequisites
+
+- **ffmpeg** — For video assembly. Install via `bun add -g ffmpeg-static` or `brew install ffmpeg`
+- **agent-browser** — For CDP screenshots. Install via `npm i -g agent-browser`
+- **Electron app running** — With CDP enabled (use `electron-dev.sh start`)
+
+## Troubleshooting
+
+| Problem                             | Solution                                                                                                     |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| "No active recording found" on stop | PID file was cleaned up. Check if background processes are still running with `ps aux \| grep agent-browser` |
+| "A recording is already active"     | Run `stop` first, or manually clean: `rm /tmp/record-app-screen.pids /tmp/record-app-screen.state`           |
+| Video is 0 bytes                    | No frames were captured. Ensure Electron is running and CDP port is correct                                  |
+| Screenshots are blank/white         | SPA may not have loaded yet. Wait for `electron-dev.sh` to report "Renderer ready"                           |
+| ffmpeg assembly fails               | Check `/tmp/ffmpeg-assemble.log`. Ensure ffmpeg is installed and frames exist                                |
@@ -0,0 +1,73 @@
+# Slack Bot Testing
+
+**App name:** `Slack` | **Process name:** `Slack`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate Slack
+osascript -e 'tell application "Slack" to activate'
+sleep 1
+
+# Quick Switcher (Cmd+K)
+osascript -e 'tell application "System Events" to keystroke "k" using command down'
+sleep 0.5
+osascript -e 'tell application "System Events" to keystroke "bot-testing"'
+sleep 1
+osascript -e 'tell application "System Events" to key code 36' # Enter
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+# Direct message input (focused after channel nav)
+osascript -e 'tell application "System Events" to keystroke "@mybot hello"'
+sleep 0.3
+osascript -e 'tell application "System Events" to key code 36'
+```
+
+## Send Long Message
+
+```bash
+osascript -e '
+tell application "Slack" to activate
+delay 0.5
+set the clipboard to "A long test message for the bot..."
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Slash Command Test
+
+```bash
+osascript -e '
+tell application "Slack" to activate
+delay 0.5
+tell application "System Events"
+    keystroke "/ask What is the meaning of life?"
+    delay 0.5
+    key code 36
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/slack-bot-response.png
+```
+
+## Script
+
+```bash
+./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "@mybot hello"
+./.agents/skills/local-testing/scripts/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
+```
@@ -0,0 +1,80 @@
+# Telegram Bot Testing
+
+**App name:** `Telegram` | **Process name:** `Telegram`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate Telegram
+osascript -e 'tell application "Telegram" to activate'
+sleep 1
+
+# Search for a bot (Cmd+F or click search)
+osascript -e '
+tell application "System Events"
+    keystroke "f" using command down
+    delay 0.5
+    keystroke "MyTestBot"
+    delay 1
+    key code 36  -- Enter to select
+end tell
+'
+sleep 2
+```
+
+## Send Message to Bot
+
+```bash
+# After navigating to bot chat, input is focused
+osascript -e '
+tell application "System Events"
+    keystroke "/start"
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Send Long Message
+
+```bash
+osascript -e '
+tell application "Telegram" to activate
+delay 0.5
+set the clipboard to "Tell me about quantum computing in detail"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/telegram-bot-response.png
+```
+
+## Telegram Bot API (programmatic alternative)
+
+For sending messages directly to the bot's chat without UI:
+
+```bash
+# Send message as the bot (for testing webhooks/responses)
+curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/sendMessage" \
+  -d "chat_id=$CHAT_ID&text=test message"
+
+# Get recent updates
+curl -s "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/getUpdates?limit=5" | jq .
+```
+
+## Script
+
+```bash
+./.agents/skills/local-testing/scripts/test-telegram-bot.sh "MyTestBot" "/start"
+./.agents/skills/local-testing/scripts/test-telegram-bot.sh "GPTBot" "Hello" 60
+```
@@ -0,0 +1,81 @@
+# WeChat / 微信 Bot Testing
+
+**App name:** `微信` or `WeChat` | **Process name:** `WeChat`
+
+See [osascript-common.md](./osascript-common.md) for shared patterns.
+
+## Activate & Navigate
+
+```bash
+# Activate WeChat
+osascript -e 'tell application "微信" to activate'
+sleep 1
+
+# Search for a contact/bot (Cmd+F)
+osascript -e '
+tell application "System Events"
+    keystroke "f" using command down
+    delay 0.5
+    keystroke "TestBot"
+    delay 1
+    key code 36  -- Enter to select
+end tell
+'
+sleep 2
+```
+
+## Send Message
+
+```bash
+# After navigating to a chat, the input is focused
+osascript -e '
+tell application "System Events"
+    keystroke "Hello bot!"
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Send Long Message (clipboard)
+
+```bash
+osascript -e '
+tell application "微信" to activate
+delay 0.5
+set the clipboard to "Please help me with this task..."
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36
+end tell
+'
+```
+
+## Verify Response
+
+```bash
+sleep 10
+screencapture /tmp/wechat-bot-response.png
+```
+
+## WeChat-Specific Notes
+
+- WeChat macOS app name can be `微信` or `WeChat` depending on system language. Try both:
+  ```bash
+  osascript -e 'tell application "微信" to activate' 2> /dev/null \
+    || osascript -e 'tell application "WeChat" to activate'
+  ```
+- WeChat uses **Enter** to send (not Cmd+Enter by default, but configurable)
+- For multi-line messages without sending, use **Shift+Enter**:
+  ```bash
+  osascript -e 'tell application "System Events" to key code 36 using shift down'
+  ```
+- Always use clipboard paste for CJK characters — `keystroke` mangles non-ASCII
+
+## Script
+
+```bash
+./.agents/skills/local-testing/scripts/test-wechat-bot.sh "文件传输助手" "test message" 5
+./.agents/skills/local-testing/scripts/test-wechat-bot.sh "MyBot" "Tell me a joke" 30
+```
@@ -0,0 +1,189 @@
+#!/usr/bin/env bash
+#
+# record-app-screen.sh — Record the Electron app window (video + screenshots)
+#
+# Captures screenshots via agent-browser (CDP), then assembles into video on stop.
+# Works on any screen (including external monitors) since it uses CDP, not screen capture.
+#
+# Usage:
+#   ./record-app-screen.sh start [output_name]   # Begin recording
+#   ./record-app-screen.sh stop                   # Stop and save
+#   ./record-app-screen.sh status                 # Check recording state
+#
+# Outputs to .records/ directory:
+#   .records/<name>.mp4   — Video assembled from screenshots (~2 fps)
+#   .records/<name>/      — Screenshots every SCREENSHOT_INTERVAL seconds
+#
+# Prerequisites:
+#   - ffmpeg installed (bun add -g ffmpeg-static, or brew install ffmpeg)
+#   - agent-browser CLI installed
+#   - Electron app already running with CDP enabled
+#
+# Environment variables:
+#   CDP_PORT              — Chrome DevTools Protocol port (default: 9222)
+#   SCREENSHOT_INTERVAL   — Seconds between gallery screenshots (default: 3)
+#   VIDEO_FRAME_INTERVAL  — Seconds between video frames (default: 0.5)
+#
+# Examples:
+#   ./electron-dev.sh start
+#   ./record-app-screen.sh start gateway-demo
+#   # ... run automation via agent-browser ...
+#   ./record-app-screen.sh stop
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+
+RECORDS_DIR="$PROJECT_DIR/.records"
+PID_FILE="/tmp/record-app-screen.pids"
+STATE_FILE="/tmp/record-app-screen.state"
+
+CDP_PORT="${CDP_PORT:-9222}"
+SCREENSHOT_INTERVAL="${SCREENSHOT_INTERVAL:-3}"
+VIDEO_FRAME_INTERVAL="${VIDEO_FRAME_INTERVAL:-0.5}"
+
+AB="agent-browser --cdp $CDP_PORT"
+
+# ─── Commands ───
+
+cmd_start() {
+  local output_name="${1:-recording-$(date +%Y%m%d-%H%M%S)}"
+  local output_video="$RECORDS_DIR/${output_name}.mp4"
+  local screenshot_dir="$RECORDS_DIR/${output_name}"
+  local frames_dir
+  frames_dir=$(mktemp -d /tmp/record-frames-XXXXXX)
+
+  if [ -f "$PID_FILE" ]; then
+    echo "[record] A recording is already active. Run '$0 stop' first."
+    exit 1
+  fi
+
+  mkdir -p "$RECORDS_DIR" "$screenshot_dir"
+
+  # Video frames loop (~2 fps via agent-browser CDP screenshots)
+  (
+    local idx=0
+    while true; do
+      local fname
+      fname=$(printf "%s/frame_%06d.png" "$frames_dir" "$idx")
+      $AB screenshot "$fname" 2>/dev/null || true
+      idx=$((idx + 1))
+      sleep "$VIDEO_FRAME_INTERVAL"
+    done
+  ) &
+  local frames_pid=$!
+
+  # Gallery screenshots loop (every N seconds for human review)
+  (
+    local idx=0
+    while true; do
+      local fname
+      fname=$(printf "%s/%04d.png" "$screenshot_dir" "$idx")
+      $AB screenshot "$fname" 2>/dev/null || true
+      idx=$((idx + 1))
+      sleep "$SCREENSHOT_INTERVAL"
+    done
+  ) &
+  local screenshot_pid=$!
+
+  # Save state
+  echo "$frames_pid $screenshot_pid" > "$PID_FILE"
+  echo "$output_video $frames_dir $screenshot_dir" > "$STATE_FILE"
+
+  echo "[record] Started!"
+  echo "  Video frames: every ${VIDEO_FRAME_INTERVAL}s (PID $frames_pid)"
+  echo "  Screenshots:  every ${SCREENSHOT_INTERVAL}s → $screenshot_dir/"
+  echo "  Stop with:    $0 stop"
+}
+
+cmd_stop() {
+  if [ ! -f "$PID_FILE" ] || [ ! -f "$STATE_FILE" ]; then
+    echo "[record] No active recording found."
+    return 0
+  fi
+
+  local frames_pid screenshot_pid
+  read -r frames_pid screenshot_pid < "$PID_FILE"
+
+  local output_video frames_dir screenshot_dir
+  read -r output_video frames_dir screenshot_dir < "$STATE_FILE"
+
+  # Stop both capture loops
+  kill "$frames_pid" 2>/dev/null || true
+  kill "$screenshot_pid" 2>/dev/null || true
+  wait "$frames_pid" 2>/dev/null || true
+  wait "$screenshot_pid" 2>/dev/null || true
+
+  # Assemble frames into video
+  local frame_count
+  frame_count=$(ls -1 "$frames_dir"/frame_*.png 2>/dev/null | wc -l | tr -d ' ')
+
+  if [ "$frame_count" -gt 0 ]; then
+    echo "[record] Assembling $frame_count frames into video..."
+    ffmpeg -y -framerate 2 -i "$frames_dir/frame_%06d.png" \
+      -c:v libx264 -crf 23 -pix_fmt yuv420p -an \
+      "$output_video" > /tmp/ffmpeg-assemble.log 2>&1
+
+    if [ ! -s "$output_video" ]; then
+      echo "  [warn] Video assembly failed. Check /tmp/ffmpeg-assemble.log"
+      echo "  Frames preserved in: $frames_dir/"
+    fi
+  else
+    echo "  [warn] No frames captured."
+  fi
+
+  rm -rf "$frames_dir" 2>/dev/null
+  rm -f "$PID_FILE" "$STATE_FILE"
+
+  local video_size screenshot_count
+  video_size=$(ls -lh "$output_video" 2>/dev/null | awk '{print $5}' || echo "?")
+  screenshot_count=$(ls -1 "$screenshot_dir"/*.png 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+
+  echo "[record] Stopped!"
+  echo "  Video:       $output_video ($video_size)"
+  echo "  Screenshots: ${screenshot_count} files in $screenshot_dir/"
+  echo "  Play:        open $output_video"
+}
+
+cmd_status() {
+  if [ ! -f "$PID_FILE" ]; then
+    echo "[record] No active recording."
+    return 0
+  fi
+
+  local frames_pid screenshot_pid
+  read -r frames_pid screenshot_pid < "$PID_FILE"
+
+  local frames_ok="no" screenshot_ok="no"
+  kill -0 "$frames_pid" 2>/dev/null && frames_ok="yes"
+  kill -0 "$screenshot_pid" 2>/dev/null && screenshot_ok="yes"
+
+  if [ -f "$STATE_FILE" ]; then
+    local output_video frames_dir screenshot_dir
+    read -r output_video frames_dir screenshot_dir < "$STATE_FILE"
+    local frame_count ss_count
+    frame_count=$(ls -1 "$frames_dir"/frame_*.png 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+    ss_count=$(ls -1 "$screenshot_dir"/*.png 2>/dev/null | wc -l | tr -d ' ' || echo "0")
+    echo "[record] Active recording"
+    echo "  Frames:      $frame_count captured (running: $frames_ok)"
+    echo "  Screenshots: $ss_count captured (running: $screenshot_ok)"
+    echo "  Output:      $output_video"
+  fi
+}
+
+# ─── Main ───
+
+case "${1:-}" in
+  start)  shift; cmd_start "$@" ;;
+  stop)   cmd_stop ;;
+  status) cmd_status ;;
+  *)
+    echo "Usage: $0 {start [name] | stop | status}"
+    echo ""
+    echo "  start [name]  Start recording (default: recording-YYYYMMDD-HHMMSS)"
+    echo "  stop          Stop recording and save outputs"
+    echo "  status        Check if recording is active"
+    exit 1
+    ;;
+esac
@@ -1,64 +1,76 @@
 ---
 name: modal
-description: Modal imperative API guide. Use when creating modal dialogs using createModal from @lobehub/ui. Triggers on modal component implementation or dialog creation tasks.
+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.
 user-invocable: false
 ---

 # Modal Imperative API Guide

-Use `createModal` from `@lobehub/ui` for imperative modal dialogs.
+## Recommended: `@lobehub/ui/base-ui`

-## Why Imperative?
+New code should use the **base-ui** modal stack (headless primitives, not antd `Modal`):

-| Mode        | Characteristics                       | Recommended |
-| ----------- | ------------------------------------- | ----------- |
-| Declarative | Need `open` state, render `<Modal />` | ❌          |
-| Imperative  | Call function directly, no state      | ✅          |
+- `createModal`, `confirmModal`, `ModalHost` from `@lobehub/ui/base-ui`
+- `useModalContext` from `@lobehub/ui/base-ui` inside modal **content**

-## File Structure
+Body slot: pass **`content`** (or `children`; runtime uses `content ?? children`).
+
+### Global `ModalHost` (required)
+
+Base-ui `createModal` renders through a **separate** host from the root package. The app must mount **`ModalHost`** from `@lobehub/ui/base-ui` once near the root (e.g. next to other global hosts). Without it, `createModal` calls will not appear.
+
+If the project only mounts `ModalHost` from `@lobehub/ui`, add a second lazy `ModalHost` from `@lobehub/ui/base-ui` until all imperative modals are migrated.
+
+### Why imperative?
+
+| Mode        | Characteristics                      | Recommended |
+| ----------- | ------------------------------------ | ----------- |
+| Declarative | `open` state + `<Modal />`           | ❌          |
+| Imperative  | Call `createModal()`, no local state | ✅          |
+
+### File structure

 ```
 features/
 └── MyFeatureModal/
-    ├── index.tsx           # Export createXxxModal
-    └── MyFeatureContent.tsx # Modal content
+    ├── index.tsx            # export createXxxModal
+    └── MyFeatureContent.tsx # modal body
 ```

-## Implementation
-
-### 1. Content Component (`MyFeatureContent.tsx`)
+### 1. Content (`MyFeatureContent.tsx`)

 ```tsx
 'use client';

-import { useModalContext } from '@lobehub/ui';
+import { useModalContext } from '@lobehub/ui/base-ui';
 import { useTranslation } from 'react-i18next';

 export const MyFeatureContent = () => {
  const { t } = useTranslation('namespace');
-  const { close } = useModalContext(); // Optional: get close method
+  const { close } = useModalContext();

-  return <div>{/* Modal content */}</div>;
+  return <div>{/* ... */}</div>;
 };
 ```

-### 2. Export createModal (`index.tsx`)
+### 2. `createModal` (`index.tsx`)

 ```tsx
 'use client';

-import { createModal } from '@lobehub/ui';
-import { t } from 'i18next'; // Note: use i18next, not react-i18next
+import { createModal } from '@lobehub/ui/base-ui';
+import { t } from 'i18next';

 import { MyFeatureContent } from './MyFeatureContent';

 export const createMyFeatureModal = () =>
  createModal({
-    allowFullscreen: true,
-    children: <MyFeatureContent />,
-    destroyOnHidden: false,
+    content: <MyFeatureContent />,
    footer: null,
-    styles: { body: { overflow: 'hidden', padding: 0 } },
+    maskClosable: true,
+    styles: {
+      content: { overflow: 'hidden', padding: 0 },
+    },
    title: t('myFeature.title', { ns: 'setting' }),
    width: 'min(80%, 800px)',
  });
@@ -76,27 +88,52 @@ const handleOpen = useCallback(() => {
 return <Button onClick={handleOpen}>Open</Button>;
 ```

-## i18n Handling
+### i18n

- **Content component**: `useTranslation` hook (React context)
- **createModal params**: `import { t } from 'i18next'` (non-hook, imperative)
+- **Content**: `useTranslation` in components.
+- **`createModal` options**: `import { t } from 'i18next'` where hooks are unavailable.

-## useModalContext Hook
+### `useModalContext`

 ```tsx
 const { close, setCanDismissByClickOutside } = useModalContext();
 ```

-## Common Config
+### Common options (base-ui)

-| Property          | Type                | Description              |
-| ----------------- | ------------------- | ------------------------ |
-| `allowFullscreen` | `boolean`           | Allow fullscreen mode    |
-| `destroyOnHidden` | `boolean`           | Destroy content on close |
-| `footer`          | `ReactNode \| null` | Footer content           |
-| `width`           | `string \| number`  | Modal width              |
+`ImperativeModalProps` builds on `BaseModalProps`: `title`, `width`, `maskClosable`, `open`, `onOpenChange`, `footer`, `styles` / `classNames` (keys: `backdrop`, `popup`, `header`, `title`, `close`, `content`, …).
+
+| Property       | Notes                                    |
+| -------------- | ---------------------------------------- |
+| `content`      | Main body (preferred name vs `children`) |
+| `maskClosable` | Click outside to dismiss                 |
+| `styles.*`     | Semantic regions, not antd `styles.body` |
+
+### Confirm
+
+```tsx
+import { confirmModal } from '@lobehub/ui/base-ui';
+
+confirmModal({
+  title: '…',
+  content: '…',
+  okText: '…',
+  cancelText: '…',
+  onOk: async () => {},
+});
+```
+
+---
+
+## Legacy: `@lobehub/ui` (root)
+
+Older call sites use **`createModal` from `@lobehub/ui`**, which is typed as **antd `Modal` props** (`children`, `allowFullscreen`, `getContainer`, `destroyOnHidden`, `styles.body`, etc.). Prefer migrating new work to **`@lobehub/ui/base-ui`**.
+
+Examples (legacy): `src/features/SkillStore/index.tsx`, `src/features/LibraryModal/CreateNew/index.tsx`.
+
+---

 ## Examples

- `src/features/SkillStore/index.tsx`
- `src/features/LibraryModal/CreateNew/index.tsx`
+- Base-ui (preferred): follow sections above; ensure **base-ui `ModalHost`** is mounted.
+- Legacy: `src/features/SkillStore/index.tsx`, `src/features/LibraryModal/CreateNew/index.tsx`
@@ -1,7 +1,7 @@
 ---
 name: pr
 description: "Create a PR for the current branch. Use when the user asks to create a pull request, submit PR, or says 'pr'."
-user_invocable: true
+user-invocable: true
 ---

 # Create Pull Request
@@ -6,6 +6,9 @@ description: React component development guide. Use when working with React comp
 # 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
@@ -64,7 +67,7 @@ import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';

 element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
 element: redirectElement('/settings/profile');
-errorElement: <ErrorBoundary resetPath="/chat" />;
+errorElement: <ErrorBoundary />;
 ```

 ### Navigation
@@ -1,114 +0,0 @@
---
-name: recent-data
-description: Guide for using Recent Data (topics, resources, pages). Use when working with recently accessed items, implementing recent lists, or accessing session store recent data. Triggers on recent data usage or implementation tasks.
-user-invocable: false
---
-
-# Recent Data Usage Guide
-
-Recent data (recentTopics, recentResources, recentPages) is stored in session store.
-
-## Initialization
-
-In app top-level (e.g., `RecentHydration.tsx`):
-
-```tsx
-import { useInitRecentTopic } from '@/hooks/useInitRecentTopic';
-import { useInitRecentResource } from '@/hooks/useInitRecentResource';
-import { useInitRecentPage } from '@/hooks/useInitRecentPage';
-
-const App = () => {
-  useInitRecentTopic();
-  useInitRecentResource();
-  useInitRecentPage();
-  return <YourComponents />;
-};
-```
-
-## Usage
-
-### Method 1: Read from Store (Recommended)
-
-```tsx
-import { useSessionStore } from '@/store/session';
-import { recentSelectors } from '@/store/session/selectors';
-
-const Component = () => {
-  const recentTopics = useSessionStore(recentSelectors.recentTopics);
-  const isInit = useSessionStore(recentSelectors.isRecentTopicsInit);
-
-  if (!isInit) return <div>Loading...</div>;
-
-  return (
-    <div>
-      {recentTopics.map((topic) => (
-        <div key={topic.id}>{topic.title}</div>
-      ))}
-    </div>
-  );
-};
-```
-
-### Method 2: Use Hook Return (Single component)
-
-```tsx
-const { data: recentTopics, isLoading } = useInitRecentTopic();
-```
-
-## Available Selectors
-
-### Recent Topics
-
-```tsx
-const recentTopics = useSessionStore(recentSelectors.recentTopics);
-// Type: RecentTopic[]
-
-const isInit = useSessionStore(recentSelectors.isRecentTopicsInit);
-// Type: boolean
-```
-
-**RecentTopic type:**
-
-```typescript
-interface RecentTopic {
-  agent: {
-    avatar: string | null;
-    backgroundColor: string | null;
-    id: string;
-    title: string | null;
-  } | null;
-  id: string;
-  title: string | null;
-  updatedAt: Date;
-}
-```
-
-### Recent Resources
-
-```tsx
-const recentResources = useSessionStore(recentSelectors.recentResources);
-// Type: FileListItem[]
-
-const isInit = useSessionStore(recentSelectors.isRecentResourcesInit);
-```
-
-### Recent Pages
-
-```tsx
-const recentPages = useSessionStore(recentSelectors.recentPages);
-const isInit = useSessionStore(recentSelectors.isRecentPagesInit);
-```
-
-## Features
-
-1. **Auto login detection**: Only loads when user is logged in
-2. **Data caching**: Stored in store, no repeated loading
-3. **Auto refresh**: SWR refreshes on focus (5-minute interval)
-4. **Type safe**: Full TypeScript types
-
-## Best Practices
-
-1. Initialize all recent data at app top-level
-2. Use selectors to read from store
-3. For multi-component use, prefer Method 1
-4. Use selectors for render optimization
@@ -1,10 +1,27 @@
 ---
 name: version-release
-description: "Version release workflow. Use when the user mentions 'release', 'hotfix', 'version upgrade', 'weekly release', or '发版'/'发布'/'小班车'. Provides guides for Minor Release and Patch Release workflows."
+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)."
 ---

 # Version Release Workflow

+## Scope Boundary (Important)
+
+This skill is only for:
+
+1. Release branch / PR workflow
+2. CI trigger constraints (`auto-tag-release.yml`)
+3. GitHub Release note writing
+
+This skill is **not** for writing `docs/changelog/*.mdx`.\
+If the user asks for website changelog pages, load `../docs-changelog/SKILL.md`.
+
+## Mandatory Companion Skill
+
+For every `/version-release` execution, you MUST load and apply:
+
+- `../microcopy/SKILL.md`
+
 ## Overview

 The primary development branch is **canary**. All day-to-day development happens on canary. When releasing, canary is merged into main. After merge, `auto-tag-release.yml` automatically handles tagging, version bumping, creating a GitHub Release, and syncing back to the canary branch.
@@ -18,7 +35,7 @@ Only two release types are used in practice (major releases are extremely rare a

 ## Minor Release Workflow

-Used to publish a new minor version (e.g. v2.2.0), roughly every 4 weeks.
+Used to publish a new minor version (e.g. `v2.2.0`), roughly every 4 weeks.

 ### Steps

@@ -31,7 +48,7 @@ git checkout -b release/v{version}
 git push -u origin release/v{version}
 ```

-2. **Determine the version number** — Read the current version from `package.json` and compute the next minor version (e.g. 2.1.x → 2.2.0)
+2. **Determine the version number** — Read the current version from `package.json` and compute the next minor version (e.g. 2.1.x -> 2.2.0)

 3. **Create a PR to main**

@@ -43,9 +60,10 @@ gh pr create \
  --body "## 📦 Release v{version} ..."
 ```

-> \[!IMPORTANT]: The PR title must strictly match the `🚀 release: v{x.y.z}` format. CI uses a regex on this title to determine the exact version number.
+> \[!IMPORTANT]
+> The PR title must strictly match the `🚀 release: v{x.y.z}` format. CI uses a regex on this title to determine the exact version number.

-4. **Automatic trigger after merge**: auto-tag-release detects the title format and uses the version number from the title to complete the release.
+4. **Automatic trigger after merge**: `auto-tag-release` detects the title format and uses the version number from the title to complete the release.

 ### Scripts

@@ -60,7 +78,7 @@ Version number is automatically bumped by patch +1. There are 4 common scenarios

 | Scenario            | Source Branch | Branch Naming                 | Description                                      |
 | ------------------- | ------------- | ----------------------------- | ------------------------------------------------ |
-| Weekly Release      | canary        | `release/weekly-{YYYYMMDD}`   | Weekly release train, canary → main              |
+| Weekly Release      | canary        | `release/weekly-{YYYYMMDD}`   | Weekly release train, canary -> main             |
 | Bug Hotfix          | main          | `hotfix/v{version}-{hash}`    | Emergency bug fix                                |
 | New Model Launch    | canary        | Community PR merged directly  | New model launch, triggered by PR title prefix   |
 | DB Schema Migration | main          | `release/db-migration-{name}` | Database migration, requires dedicated changelog |
@@ -73,19 +91,19 @@ All scenarios auto-bump patch +1. Patch PR titles do not need a version number.
 bun run hotfix:branch # Hotfix scenario
 ```

-## Auto-Release Trigger Rules (auto-tag-release.yml)
+## Auto-Release Trigger Rules (`auto-tag-release.yml`)

 After a PR is merged into main, CI determines whether to release based on the following priority:

 ### 1. Minor Release (Exact Version)

-PR title matches `🚀 release: v{x.y.z}` → uses the version number from the title.
+PR title matches `🚀 release: v{x.y.z}` -> uses the version number from the title.

 ### 2. Patch Release (Auto patch +1)

 Triggered by the following priority:

- **Branch name match**: `hotfix/*` or `release/*` → triggers directly (skips title detection)
+- **Branch name match**: `hotfix/*` or `release/*` -> triggers directly (skips title detection)
 - **Title prefix match**: PRs with the following title prefixes will trigger:
  - `style` / `💄 style`
  - `feat` / `✨ feat`
@@ -96,64 +114,205 @@ Triggered by the following priority:

 ### 3. No Trigger

-PRs that don't match any of the above conditions (e.g. `docs`, `chore`, `ci`, `test` prefixes) will not trigger a release when merged into main.
+PRs that don't match any conditions above (e.g. `docs`, `chore`, `ci`, `test`) will not trigger a release when merged into main.

 ## Post-Release Automated Actions

-1. **Bump package.json** — commits `🔖 chore(release): release version v{x.y.z} [skip ci]`
+1. **Bump `package.json`** — commits `🔖 chore(release): release version v{x.y.z} [skip ci]`
 2. **Create annotated tag** — `v{x.y.z}`
 3. **Create GitHub Release**
-4. **Dispatch sync-main-to-canary** — syncs main back to the canary branch
+4. **Dispatch `sync-main-to-canary`** — syncs main back to canary

-## Claude Action Guide
+## Agent Action Guide

 When the user requests a release:

-### Minor Release
-
-1. Read `package.json` to get the current version and compute the next minor version
-2. Create a `release/v{version}` branch from canary
-3. Push and create a PR — **title must be `🚀 release: v{version}`**
-4. Inform the user that merging the PR will automatically trigger the release
-
 ### Precheck

 Before creating the release branch, verify the source branch:

 - **Weekly Release** (`release/weekly-*`): must branch from `canary`
- **All other release/hotfix branches**: must branch from `main` — run `git merge-base --is-ancestor main <branch> && echo OK` to confirm
- If the branch is based on the wrong source, delete and recreate from the correct base
+- **All other release/hotfix branches**: must branch from `main`; run `git merge-base --is-ancestor main <branch> && echo OK`
+- If the branch is based on the wrong source, recreate from the correct base
+
+### Minor Release
+
+1. Read `package.json` to get the current version and compute the next minor version
+2. Create a `release/v{version}` branch from canary
+3. Push and create PR — **title must be `🚀 release: v{version}`**
+4. Inform the user that merge will auto-trigger release

 ### Patch Release

-Choose the appropriate workflow based on the scenario (see `reference/patch-release-scenarios.md`):
+Choose workflow by scenario (see `reference/patch-release-scenarios.md`):

- **Weekly Release**: Create a `release/weekly-{YYYYMMDD}` branch from canary, scan `git log main..canary` to write the changelog, title like `🚀 release: 20260222`
- **Bug Hotfix**: Create a `hotfix/` branch from main, use a gitmoji prefix title (e.g. `🐛 fix: ...`)
- **New Model Launch**: Community PRs trigger automatically via title prefix (`feat` / `style`), no extra steps needed
- **DB Migration**: Create a `release/db-migration-{name}` branch from main, cherry-pick migration commits, write a dedicated migration changelog
+- **Weekly Release**: create `release/weekly-{YYYYMMDD}` from canary; use `git log main..canary` for release note inputs; title like `🚀 release: 20260222`
+- **Bug Hotfix**: create `hotfix/` from main; use gitmoji prefix title (e.g. `🐛 fix: ...`)
+- **New Model Launch**: community PRs trigger automatically via title prefix (`feat` / `style`)
+- **DB Migration**: create `release/db-migration-{name}` from main; cherry-pick migration commits; include dedicated migration notes

-### Important Notes
+### Hard Rules

- **Do NOT manually modify the version in package.json** — CI will auto-bump it
- **Do NOT manually create tags** — CI will create them automatically
- The Minor Release PR title format is a hard requirement — incorrect format will not use the specified version number
- Patch PRs do not need a version number — CI auto-bumps patch +1
- All release PRs must include a user-facing changelog
+- **Do NOT** manually modify `package.json` version
+- **Do NOT** manually create tags
+- Minor PR title format is strict
+- Patch PRs do not need explicit version number
+- Keep release facts accurate; do not invent metrics or availability statements

-## Changelog Writing Guidelines
+## GitHub Release Changelog Standard (Long-Form Style)

-All release PR bodies (both Minor and Patch) must include a user-facing changelog. Scan changes via `git log main..canary --oneline` or `git diff main...canary --stat`, then write following the format below.
+Use this section for writing **GitHub Release notes** (or release PR body when the PR body is intended to become release notes).\
+Do not use this as `docs/changelog` page guidance.

-### Format Reference
+### Positioning

- Weekly Release: See `reference/changelog-example/weekly-release.md`
- DB Migration: See `reference/changelog-example/db-migration.md`
+This release-note style is:

-### Writing Tips
+1. **Data-backed at the top** (date, range, key metrics)
+2. **Narrative first, then structured detail**
+3. **Deep but scannable** (clear sectioning + compact bullets)
+4. **Contributor-forward** (credits are part of the release story)

- **User-facing**: Describe changes that users can perceive, not internal implementation details
- **Clear categories**: Group by features, models/providers, desktop, stability/fixes, etc.
- **Highlight key items**: Use `**bold**` for important feature names
- **Credit contributors**: Collect all committers via `git log` and list alphabetically
- **Flexible categories**: Choose categories based on actual changes — no need to force-fit all categories
+### Required Inputs Before Writing
+
+Collect these inputs first:
+
+1. Compare range (`<prev_tag>...<current_tag>`)
+2. Release metrics (commits, merged PRs, resolved issues, contributors, optional files/insertions/deletions)
+3. High-impact changes by domain (core loop, platform/gateway, UX, tooling, security, reliability)
+4. Contributor list (with standout contributions if known)
+5. Known risks / migrations / rollout notes (if any)
+
+If metrics cannot be reliably computed, omit unknown numbers instead of guessing.
+
+### Canonical Structure
+
+Follow this section order unless the user asks otherwise:
+
+1. `# 🚀 LobeHub v<x.y.z> (<YYYYMMDD>)`
+2. Metadata lines:
+   - `Release Date`
+   - `Since <Previous Version>` metrics
+3. One quoted release thesis (single paragraph, 1-2 lines)
+4. `## ✨ Highlights` (6-12 bullets for major releases; 3-8 for weekly)
+5. Domain blocks with optional `###` subsections:
+   - `## 🏗️ Core Agent & Architecture` (or equivalent product core)
+   - `## 📱 Platforms / Integrations`
+   - `## 🖥️ CLI & User Experience`
+   - `## 🔧 Tooling`
+   - `## 🔒 Security & Reliability`
+   - `## 📚 Documentation` (optional if meaningful)
+6. `## 👥 Contributors`
+7. `**Full Changelog**: <prev>...<current>`
+
+Use `---` separators between major blocks for long releases.
+
+### Writing Rules (Hard)
+
+1. **No fabricated metrics**: all numbers must be traceable.
+2. **No vague headline bullets**: each bullet must include capability + impact.
+3. **No internal-only framing**: phrase from user/operator perspective.
+4. **Security must be explicit** when security-sensitive fixes are present.
+5. **PR/issue linkage**: use `(#1234)` when IDs are available.
+6. **Terminology consistency**: same feature/provider name across sections.
+7. **Do not bury migration or breaking changes**: elevate to dedicated section or callout.
+
+### Style Rules (Long-Form)
+
+1. Start with an "everyday use" framing, not implementation internals.
+2. Mix narrative sentence + evidence bullets.
+3. Keep bullets compact but informative:
+   - Good: `**Fast Mode (`/fast`)** — Priority routing for OpenAI and Anthropic, reducing latency on supported models. (#6875, #6960)`
+4. Use bold only for capability names, not for whole sentences.
+5. Keep heading depth <= 3 levels.
+
+### Release Size Heuristics
+
+- **Minor / major milestone release**
+  - Include full structure with multiple domain blocks.
+  - `Highlights` usually 8-12 bullets.
+- **Weekly patch release**
+  - Keep full skeleton but reduce subsection count.
+  - `Highlights` usually 4-8 bullets.
+- **DB migration release**
+  - Keep concise.
+  - Must include `Migration overview`, operator impact, and rollback/backup note.
+
+### GitHub Release Changelog Template
+
+```md
+# 🚀 LobeHub v<x.y.z> (<YYYYMMDD>)
+
+**Release Date:** <Month DD, YYYY>  
+**Since <Previous Version>:** <N commits> · <N merged PRs> · <N resolved issues> · <N contributors>
+
+> <One release thesis sentence: what this release unlocks in practice.>
+
+---
+
+## ✨ Highlights
+
+- **<Capability A>** — <What changed and why it matters>. (#1234)
+- **<Capability B>** — <What changed and why it matters>. (#2345)
+- **<Capability C>** — <What changed and why it matters>. (#3456)
+
+---
+
+## 🏗️ Core Product & Architecture
+
+### <Subdomain>
+
+- <Concrete change + impact>. (#...)
+- <Concrete change + impact>. (#...)
+
+---
+
+## 📱 Platforms / Integrations
+
+- <Platform update + impact>. (#...)
+- <Compatibility/reliability fix + impact>. (#...)
+
+---
+
+## 🖥️ CLI & User Experience
+
+- <User-facing workflow improvement>. (#...)
+- <Quality-of-life fix>. (#...)
+
+---
+
+## 🔧 Tooling
+
+- <Tool/runtime improvement>. (#...)
+
+---
+
+## 🔒 Security & Reliability
+
+- **Security:** <hardening or vulnerability fix>. (#...)
+- **Reliability:** <stability/performance behavior improvement>. (#...)
+
+---
+
+## 👥 Contributors
+
+**<N merged PRs>** from **<N contributors>** across **<N commits>**.
+
+### Community Contributors
+
+- @<username> - <notable contribution area>
+- @<username> - <notable contribution area>
+
+---
+
+**Full Changelog**: <previous_tag>...<current_tag>
+```
+
+### Quick Checklist
+
+- [ ] Uses top metadata and a clear release thesis
+- [ ] Includes `Highlights` plus domain-grouped sections
+- [ ] Every major bullet states both change and user/operator impact
+- [ ] Security and reliability updates are explicitly surfaced (when present)
+- [ ] Contributor credits and compare range are included
+- [ ] All numbers and claims are verifiable
@@ -1,20 +1,60 @@
-# DB Schema Migration Changelog Example
+# 🚀 LobeHub v2.1.50 (20260416)

-A changelog reference for database migration release PR bodies.
+**Release Date:** April 20, 2026\
+**Migration Scope:** Agent benchmark data model bootstrap (5 new tables, 2 new indexes)
+
+> This release introduces a schema foundation for benchmark execution and reporting, so agent evaluation data is stored as a complete lifecycle instead of fragmented records.

 ---

-This release includes a **database schema migration** involving **5 new tables** for the Agent Evaluation Benchmark system.
+## ✨ Highlights

-### Migration: Add Agent Evaluation Benchmark Tables
+- **Benchmark Lifecycle Schema** — Added a relational model that tracks benchmark setup, runs, per-topic execution, and record outputs end-to-end.
+- **Queryability Upgrade** — Added indexes for run status and benchmark-topic joins, improving operational queries in dashboard and debugging workflows.
+- **Safer Operator Rollout** — Migration is startup-driven and backward-compatible with existing non-benchmark chat workflows.

- Added 5 new tables: `agent_eval_benchmarks`, `agent_eval_datasets`, `agent_eval_records`, `agent_eval_runs`, `agent_eval_run_topics`
+---

-### Notes for Self-hosted Users
+## 🗄️ Migration Overview

- The migration runs automatically on application startup
- No manual intervention required
+Added tables:

-The migration owner: @{pr-author} — responsible for this database schema change, reach out for any migration-related issues.
+- `agent_eval_benchmarks`
+- `agent_eval_datasets`
+- `agent_eval_runs`
+- `agent_eval_run_topics`
+- `agent_eval_records`

-> **Note for Claude**: Replace `{pr-author}` with the actual PR author. Retrieve via `gh pr view <number> --json author --jq '.author.login'` or `git log` commit author. Do NOT hardcode a username.
+Added indexes:
+
+- `idx_agent_eval_runs_status_created_at`
+- `idx_agent_eval_run_topics_run_id_topic_id`
+
+These additions close a previous gap where benchmark data existed in partial forms but lacked a stable relational backbone for auditing and historical analysis.
+
+---
+
+## ⚙️ Operator Notes
+
+- Migration runs automatically on application startup.
+- No manual SQL is required in standard deployment paths.
+- Schedule rollout in a low-traffic window and take a backup snapshot before deployment.
+- If migration fails, do not retry repeatedly; inspect migration logs and lock state first.
+
+---
+
+## 🔒 Reliability & Risk
+
+- Existing chat/session paths are unaffected unless benchmark features are enabled.
+- Migration is additive (new tables/indexes only), minimizing downgrade risk to existing entities.
+- Rollback should follow your standard DB restore or migration rollback policy if your environment requires strict reversibility.
+
+---
+
+## 👥 Owner
+
+Migration owner: @{pr-author}
+
+The migration owner is responsible for rollout follow-up and incident handling for this schema change.
+
+> **Note for Claude**: Replace `{pr-author}` with the actual PR author. Retrieve via `gh pr view <number> --json author --jq '.author.login'` or from commit metadata. Do not hardcode a username.
@@ -1,46 +1,80 @@
-# Patch Release (Weekly) Changelog Example
+# 🚀 LobeHub v2.1.50 (20260420)

-A real-world changelog reference for weekly patch release PR bodies.
+**Release Date:** April 20, 2026\
+**Since v2026.04.13:** 96 commits · 58 merged PRs · 31 resolved issues · 17 contributors
+
+> This weekly release focuses on reducing friction in everyday agent work: faster model routing, smoother gateway behavior, stronger task continuity, and clearer operator diagnostics when something goes wrong.

 ---

-This release includes **82 commits** , Key updates are below.
+## ✨ Highlights

-### New Features and Enhancements
+- **Gateway Session Recovery** — Agent sessions now recover more reliably after short network interruptions, so long-running tasks continue with less manual retry. (#10121, #10133)
+- **Fast Model Routing** — Expanded low-latency routing for priority model tiers, reducing wait time in high-frequency generation workflows. (#10102, #10117)
+- **Agent Task Workspace** — Running tasks now remain isolated from main chat state, which keeps primary conversations cleaner while background work progresses. (#10088)
+- **Provider Coverage Update** — Added support for new model variants across OpenAI-compatible and regional providers, improving fallback options in production. (#10094, #10109)
+- **Desktop Attachment Flow** — File and screenshot attachment behavior is more predictable in desktop sessions, especially for mixed text + media prompts. (#10073)
+- **Security Hardening Pass** — Closed multiple input validation gaps in webhook and file-path handling paths. (#10141, #10152)

- Added **Agent Benchmark** support for more systematic agent performance evaluation.
- Introduced the **video generation** feature end-to-end, including entry points, sidebar "new" badge support, and skeleton loading for topic switching.
- Expanded memory capabilities: support for memory effort/tool permission configuration and improved timeout calculation for memory analysis tasks.
- Added desktop editor support for image upload via file picker.
+---

-### Models and Provider Expansion
+## 🏗️ Core Agent & Architecture

- Added a new provider: **Straico**.
- Added/updated support for:
-  - Claude Sonnet 4.6
-  - Gemini 3.1 Pro Preview
-  - Qwen3.5 series
-  - Grok Imagine (`grok-imagine-image`)
-  - MiniMax 2.5
- Added related i18n copy and model parameter adaptations.
+### Agent loop and context handling

-### Desktop Improvements
+- Improved context compaction thresholds to reduce mid-task exits under tight token budgets. (#10079)
+- Added better diagnostics for tool-call truncation and recovery behavior during streamed responses. (#10106)
+- Refined delegate task activity propagation to improve parent-child task status consistency. (#10098)

- Integrated `electron-liquid-glass` (macOS Tahoe).
- Improved DMG background assets and desktop release workflow.
+### Provider and model behavior

-### Stability, Security, and UX Fixes
+- Unified provider-side timeout handling in fallback chains to reduce false failure classification. (#10097)
+- Updated reasoning-model defaults and response normalization for better cross-provider consistency. (#10109)

- Fixed multiple video generation pipeline issues: precharge refund handling, webhook token verification, pricing parameter usage, asset cleanup, and type safety.
- Fixed `sanitizeFileName` path traversal risks and added unit tests.
- Fixed MCP media URL generation with duplicated `APP_URL` prefix.
- Fixed Qwen3 embedding failures caused by batch-size limits.
- Fixed multiple UI/interaction issues, including mobile header agent selector/topic count, ChatInput scrolling behavior, and tooltip stacking context.
- Fixed missing `@napi-rs/canvas` native bindings in Docker standalone builds.
- Improved GitHub Copilot authentication retry behavior and response error handling in edge cases.
+---

-### Credits
+## 📱 Gateway & Platform Integrations

-Huge thanks to these contributors (alphabetical):
+- Gateway now drains in-flight events more safely before restart, reducing duplicate notification bursts. (#10125)
+- Discord and Slack adapters received retry/backoff tuning for unstable webhook windows. (#10091, #10119)
+- WeCom callback-mode message state persistence now uses safer atomic updates. (#10114)

-@AmAzing129 @Coooolfan @Innei @ONLY-yours @Zhouguanyang @arvinxx @eaten-cake @hezhijie0327 @nekomeowww @rdmclin2 @rivertwilight @sxjeru @tjx666
+---
+
+## 🖥️ CLI & User Experience
+
+- Improved slash command discoverability in CLI and gateway contexts with clearer hint messages. (#10086)
+- `/model` switching feedback now returns clearer success/failure states in cross-platform chats. (#10108)
+- Setup flow now warns earlier about missing provider credentials in first-run scenarios. (#10115)
+
+---
+
+## 🔧 Tooling
+
+- MCP registration flow now validates duplicate tool names before activation, reducing runtime conflicts. (#10093)
+- Browser tooling improved stale-session cleanup to prevent orphaned local resources. (#10112)
+
+---
+
+## 🔒 Security & Reliability
+
+- **Security:** Hardened path sanitization for uploaded assets and webhook callback validation. (#10141, #10152)
+- **Reliability:** Reduced empty-response retry storms by refining retry-classification conditions. (#10130)
+- **Reliability:** Improved timeout defaults for long-running background processes in constrained environments. (#10122)
+
+---
+
+## 👥 Contributors
+
+**58 merged PRs** from **17 contributors** across **96 commits**.
+
+### Community Contributors
+
+- @alice-example - Gateway recovery and retry improvements
+- @bob-example - Provider fallback normalization
+- @charlie-example - Desktop media attachment flow
+- @dora-example - Webhook validation hardening
+
+---
+
+**Full Changelog**: v2026.04.13...v2026.04.20
@@ -71,15 +71,18 @@ internal_createTopic: async (params) => {
 **Actions:**

 - Public: `createTopic`, `sendMessage`
+
 - Internal: `internal_createTopic`, `internal_updateMessageContent`
+
 - Dispatch: `internal_dispatchTopic`
- Toggle: `internal_toggleMessageLoading`
+  **State:**

-**State:**
+- ID arrays: `topicEditingIds`

- ID arrays: `messageLoadingIds`, `topicEditingIds`
 - Maps: `topicMaps`, `messagesMap`
+
 - Active: `activeTopicId`
+
 - Init flags: `topicsInit`

 ## Detailed Guides
@@ -30,16 +30,13 @@ internal_createMessage: async (message, context) => {
  let tempId = context?.tempMessageId;
  if (!tempId) {
    tempId = internal_createTmpMessage(message);
-    internal_toggleMessageLoading(true, tempId);
  }

  try {
    const id = await messageService.createMessage(message);
    await refreshMessages();
-    internal_toggleMessageLoading(false, tempId);
    return id;
  } catch (e) {
-    internal_toggleMessageLoading(false, tempId);
    internal_dispatchMessage({
      id: tempId,
      type: 'updateMessage',
@@ -136,6 +136,11 @@ OPENAI_API_KEY=sk-xxxxxxxxx

 # MOONSHOT_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

+# ## Kimi Code Plan  ####
+
+# KIMICODINGPLAN_PROXY_URL=https://api.kimi.com/coding
+# KIMICODINGPLAN_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+
 # ## Minimax AI  ####

 # MINIMAX_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -408,3 +413,14 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # IMPORTANT: This key is stored server-side only and NEVER exposed to the client
 # When this key is set, Klavis integration will be automatically enabled
 # KLAVIS_API_KEY=your_klavis_api_key_here
+
+# #######################################
+# #### Message Gateway (IM Integration) ##
+# #######################################
+
+# External message-gateway for unified IM platform connection management.
+# Set ENABLED=1 to activate. To migrate away, remove ENABLED first (keep URL/TOKEN)
+# so LobeHub can automatically disconnect leftover gateway connections.
+# MESSAGE_GATEWAY_ENABLED=1
+# MESSAGE_GATEWAY_URL=https://message-gateway.lobehub.com
+# MESSAGE_GATEWAY_SERVICE_TOKEN=your_service_token_here
@@ -1,7 +1,7 @@
 name: Release ModelBank

 permissions:
-  contents: write
+  contents: read
  id-token: write

 on:
@@ -41,15 +41,12 @@ jobs:

  publish:
    name: Publish ModelBank
-    if: ${{ github.event_name == 'workflow_dispatch' }}
    needs: build
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v6
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Setup Node.js
        uses: actions/setup-node@v6
@@ -63,27 +60,70 @@ jobs:
      - name: Install dependencies
        run: pnpm install

-      - name: Bump patch version
-        id: version
-        run: |
-          npm version patch --no-git-tag-version --prefix packages/model-bank
-          echo "version=$(node -p 'require(\"./packages/model-bank/package.json\").version')" >> "$GITHUB_OUTPUT"
-
      - name: Build package
        run: pnpm --filter model-bank build

+      - name: Prepare publish package
+        id: version
+        run: |
+          BASE_VERSION=$(node -p "require('./packages/model-bank/package.json').version.split('.').slice(0, 2).join('.')")
+          MODEL_BANK_VERSION="${BASE_VERSION}.$(date -u +%Y%m%d%H%M%S)"
+          export MODEL_BANK_VERSION
+
+          node <<'NODE'
+          const fs = require('node:fs');
+
+          const packagePath = 'packages/model-bank/package.json';
+          const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+          const toDistExport = (sourcePath) => sourcePath.replace('./src/', './dist/').replace(/\.ts$/, '.mjs');
+
+          packageJson.version = process.env.MODEL_BANK_VERSION;
+          packageJson.type = 'module';
+          packageJson.main = './dist/index.mjs';
+          packageJson.types = './dist/index.d.mts';
+          packageJson.files = ['dist'];
+          packageJson.repository = {
+            type: 'git',
+            url: 'https://github.com/lobehub/lobehub',
+            directory: 'packages/model-bank',
+          };
+          packageJson.exports = Object.fromEntries(
+            Object.entries(packageJson.exports).map(([key, value]) => {
+              if (typeof value !== 'string') return [key, value];
+
+              const distPath = toDistExport(value);
+
+              return [
+                key,
+                {
+                  types: distPath.replace(/\.mjs$/, '.d.mts'),
+                  import: distPath,
+                  default: distPath,
+                },
+              ];
+            }),
+          );
+
+          delete packageJson.private;
+          delete packageJson.devDependencies;
+          delete packageJson.scripts;
+
+          if (packageJson.dependencies) {
+            delete packageJson.dependencies['@lobechat/business-const'];
+
+            if (Object.keys(packageJson.dependencies).length === 0) {
+              delete packageJson.dependencies;
+            }
+          }
+
+          fs.writeFileSync(packagePath, `${JSON.stringify(packageJson, null, 2)}\n`);
+          NODE
+
+          echo "version=${MODEL_BANK_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Prepared model-bank@${MODEL_BANK_VERSION}"
+
      - name: Publish to npm
-        run: npm publish --provenance
+        run: npm publish --provenance --access public
        working-directory: packages/model-bank
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-      - name: Commit version bump
-        env:
-          MODEL_BANK_VERSION: ${{ steps.version.outputs.version }}
-        run: |
-          git config user.name "lobehubbot"
-          git config user.email "i@lobehub.com"
-          git add packages/model-bank/package.json
-          git commit -m "🔖 chore(model-bank): release v${MODEL_BANK_VERSION}"
-          git push
@@ -97,8 +97,8 @@ jobs:
    if: needs.check-duplicate-run.outputs.should_skip != 'true'
    strategy:
      matrix:
-        shard: [1, 2]
-    name: Test App (shard ${{ matrix.shard }}/2)
+        shard: [1, 2, 3]
+    name: Test App (shard ${{ matrix.shard }}/3)
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
@@ -110,7 +110,7 @@ jobs:
        run: pnpm install

      - name: Run tests
-        run: bunx vitest --coverage --silent='passed-only' --reporter=default --reporter=blob --shard=${{ matrix.shard }}/2
+        run: bunx vitest --coverage --silent='passed-only' --reporter=default --reporter=blob --shard=${{ matrix.shard }}/3

      - name: Upload blob report
        if: ${{ !cancelled() }}
@@ -25,6 +25,9 @@ Desktop.ini
 *.code-workspace
 .vscode/sessions.json
 prd
+# Recordings
+.records/
+
 # Temporary files
 .temp/
 temp/
@@ -137,5 +140,10 @@ pnpm-lock.yaml
 .turbo
 spaHtmlTemplates.ts

+# Embedded CLI bundle (built at pack time)
+apps/desktop/resources/bin/lobe-cli.js
+apps/desktop/resources/cli-package.json
+
+# Superpowers plugin brainstorm/spec outputs (local only; do not commit)
 .superpowers/
-docs/superpowers
+.heerogeneous-tracing
@@ -1,6 +1,6 @@
 const { defineConfig } = require('@lobehub/i18n-cli');
-const fs = require('fs');
-const path = require('path');
+const fs = require('node:fs');
+const path = require('node:path');

 module.exports = defineConfig({
  entry: 'locales/en-US',
@@ -27,14 +27,14 @@ module.exports = defineConfig({
  ],
  temperature: 0,
  saveImmediately: true,
-  modelName: 'chatgpt-4o-latest',
+  modelName: 'gpt-5.1-chat-latest',
  experimental: {
    jsonMode: true,
  },
  markdown: {
    reference:
      'You need to maintain the component format of the mdx file; the output text does not need to be wrapped in any code block syntax on the outermost layer.\n' +
-      fs.readFileSync(path.join(__dirname, 'docs/glossary.md'), 'utf-8'),
+      fs.readFileSync(path.join(__dirname, 'docs/glossary.md'), 'utf8'),
    entry: ['./README.md', './docs/**/*.md', './docs/**/*.mdx'],
    entryLocale: 'en-US',
    outputLocales: ['zh-CN'],
@@ -6,7 +6,11 @@
  },
  "editor.formatOnSave": true,
  // don't show errors, but fix when save and git pre commit
-  "eslint.rules.customizations": [],
+  "eslint.rules.customizations": [
+    { "rule": "simple-import-sort/exports", "severity": "off" },
+    { "rule": "perfectionist/sort-interfaces", "severity": "off" },
+    { "rule": "simple-import-sort/imports", "severity": "off" }
+  ],
  "eslint.validate": [
    "json",
    "javascript",
@@ -16,7 +20,7 @@
    // support mdx
    "mdx"
  ],
-  "mdx.server.enable": false,
+  "js/ts.tsdk.path": "node_modules/typescript/lib",
  "npm.packageManager": "pnpm",
  "search.exclude": {
    "**/node_modules": true,
@@ -44,9 +48,7 @@
    // make stylelint work with tsx antd-style css template string
    "typescriptreact"
  ],
-  "typescript.tsdk": "node_modules/typescript/lib",
  "vitest.disableWorkspaceWarning": true,
-  "vitest.maximumConfigs": 10,
  "workbench.editor.customLabels.patterns": {
    "**/app/**/[[]*[]]/[[]*[]]/page.tsx": "${dirname(2)}/${dirname(1)}/${dirname} • page component",
    "**/app/**/[[]*[]]/page.tsx": "${dirname(1)}/${dirname} • page component",
@@ -2,6 +2,100 @@

 # Changelog

+## [Version 2.1.51](https://github.com/lobehub/lobe-chat/compare/v0.0.0-nightly.pr13850.8503...v2.1.51)
+
+<sup>Released on **2026-04-16**</sup>
+
+#### 👷 Build System
+
+- **database**: add document history schema.
+- **database**: add document history schema.
+
+#### 🐛 Bug Fixes
+
+- **misc**: fix minify cli.
+- **misc**: recent delete.
+- **deps**: pin @react-pdf/image to 3.0.4 to avoid privatized @react-pdf/svg.
+- **database**: enforce document history ownership and pagination.
+
+#### ✨ Features
+
+- **database**: add document history table and update related models.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### Build System
+
+- **database**: add document history schema, closes [#13789](https://github.com/lobehub/lobe-chat/issues/13789) ([c1174d3](https://github.com/lobehub/lobe-chat/commit/c1174d3))
+- **database**: add document history schema ([e3eef04](https://github.com/lobehub/lobe-chat/commit/e3eef04))
+
+#### What's fixed
+
+- **misc**: fix minify cli, closes [#13888](https://github.com/lobehub/lobe-chat/issues/13888) ([cb4ad01](https://github.com/lobehub/lobe-chat/commit/cb4ad01))
+- **misc**: recent delete, closes [#13878](https://github.com/lobehub/lobe-chat/issues/13878) ([85227cf](https://github.com/lobehub/lobe-chat/commit/85227cf))
+- **deps**: pin @react-pdf/image to 3.0.4 to avoid privatized @react-pdf/svg ([d526b40](https://github.com/lobehub/lobe-chat/commit/d526b40))
+- **database**: enforce document history ownership and pagination ([b9c4b87](https://github.com/lobehub/lobe-chat/commit/b9c4b87))
+
+#### What's improved
+
+- **database**: add document history table and update related models ([64fc6d4](https://github.com/lobehub/lobe-chat/commit/64fc6d4))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+## [Version 2.1.50](https://github.com/lobehub/lobe-chat/compare/v2.1.49...v2.1.50)
+
+<sup>Released on **2026-04-16**</sup>
+
+#### 👷 Build System
+
+- **database**: add document history schema.
+- **database**: add document history schema.
+
+#### 🐛 Bug Fixes
+
+- **deps**: pin @react-pdf/image to 3.0.4 to avoid privatized @react-pdf/svg.
+- **database**: enforce document history ownership and pagination.
+
+#### ✨ Features
+
+- **database**: add document history table and update related models.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### Build System
+
+- **database**: add document history schema, closes [#13789](https://github.com/lobehub/lobe-chat/issues/13789) ([c1174d3](https://github.com/lobehub/lobe-chat/commit/c1174d3))
+- **database**: add document history schema ([e3eef04](https://github.com/lobehub/lobe-chat/commit/e3eef04))
+
+#### What's fixed
+
+- **deps**: pin @react-pdf/image to 3.0.4 to avoid privatized @react-pdf/svg ([d526b40](https://github.com/lobehub/lobe-chat/commit/d526b40))
+- **database**: enforce document history ownership and pagination ([b9c4b87](https://github.com/lobehub/lobe-chat/commit/b9c4b87))
+
+#### What's improved
+
+- **database**: add document history table and update related models ([64fc6d4](https://github.com/lobehub/lobe-chat/commit/64fc6d4))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
 ### [Version 2.1.45](https://github.com/lobehub/lobe-chat/compare/v2.1.44...v2.1.45)

 <sup>Released on **2026-03-26**</sup>
@@ -6,7 +6,7 @@ Guidelines for using Claude Code in this LobeHub repository.

 - Next.js 16 + React 19 + TypeScript
 - SPA inside Next.js with `react-router-dom`
- `@lobehub/ui`, antd for components; antd-style for CSS-in-JS
+- `@lobehub/ui`, antd for components; antd-style for CSS-in-JS — **prefer `createStaticStyles` with `cssVar.*`** (zero-runtime); only fall back to `createStyles` + `token` when styles genuinely need runtime computation. See `.cursor/docs/createStaticStyles_migration_guide.md`.
 - react-i18next for i18n; zustand for state management
 - SWR for data fetching; TRPC for type-safe backend
 - Drizzle ORM with PostgreSQL; Vitest for testing
@@ -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.3" "User Commands"
+.TH LH 1 "" "@lobehub/cli 0.0.8" "User Commands"
 .SH NAME
 lh \- LobeHub CLI \- manage and connect to LobeHub services
 .SH SYNOPSIS
@@ -98,6 +98,9 @@ Manage messages
 .B model
 Manage AI models
 .TP
+.B notify
+Send a callback message to a topic and trigger the agent to process it
+.TP
 .B provider
 Manage AI providers
 .TP
@@ -1,6 +1,6 @@
 {
  "name": "@lobehub/cli",
-  "version": "0.0.3",
+  "version": "0.0.8",
  "type": "module",
  "bin": {
    "lh": "./dist/index.js",
@@ -28,6 +28,7 @@
    "type-check": "tsc --noEmit"
  },
  "devDependencies": {
+    "@lobechat/agent-gateway-client": "workspace:*",
    "@lobechat/device-gateway-client": "workspace:*",
    "@lobechat/local-file-shell": "workspace:*",
    "@trpc/client": "^11.8.1",
@@ -1,4 +1,5 @@
 packages:
+  - '../../packages/agent-gateway-client'
  - '../../packages/device-gateway-client'
  - '../../packages/local-file-shell'
  - '../../packages/file-loaders'
@@ -37,7 +37,25 @@ export async function getAuthInfo(): Promise<AuthInfo> {
  };
 }

-export async function getAgentStreamAuthInfo(): Promise<Pick<AuthInfo, 'headers' | 'serverUrl'>> {
+export type AgentStreamTokenType = 'jwt' | 'apiKey';
+
+export interface AgentStreamAuthInfo {
+  headers: Record<string, string>;
+  serverUrl: string;
+  /**
+   * Raw token value (without header prefix). Used for WebSocket auth messages
+   * where header-based auth is not available.
+   */
+  token: string;
+  /**
+   * How the token should be verified by downstream services (agent gateway WS).
+   * jwt  → validate with JWKS
+   * apiKey → validate by calling /api/v1/users/me
+   */
+  tokenType: AgentStreamTokenType;
+}
+
+export async function getAgentStreamAuthInfo(): Promise<AgentStreamAuthInfo> {
  const serverUrl = resolveServerUrl();

  const envJwt = process.env.LOBEHUB_JWT;
@@ -45,6 +63,8 @@ export async function getAgentStreamAuthInfo(): Promise<Pick<AuthInfo, 'headers'
    return {
      headers: { 'Oidc-Auth': envJwt },
      serverUrl,
+      token: envJwt,
+      tokenType: 'jwt',
    };
  }

@@ -53,6 +73,8 @@ export async function getAgentStreamAuthInfo(): Promise<Pick<AuthInfo, 'headers'
    return {
      headers: { 'X-API-Key': envApiKey },
      serverUrl,
+      token: envApiKey,
+      tokenType: 'apiKey',
    };
  }

@@ -64,11 +86,15 @@ export async function getAgentStreamAuthInfo(): Promise<Pick<AuthInfo, 'headers'
    return {
      headers: {},
      serverUrl,
+      token: '',
+      tokenType: 'jwt',
    };
  }

  return {
    headers: { 'Oidc-Auth': result.credentials.accessToken },
    serverUrl,
+    token: result.credentials.accessToken,
+    tokenType: 'jwt',
  };
 }
@@ -258,6 +258,10 @@ export function registerAgentCommand(program: Command) {
      '--device <target>',
      'Target device ID, or use "local" for the current connected device',
    )
+    .option(
+      '--no-headless',
+      "Disable headless mode and wait for human approval on tool calls (default: headless — tools auto-run, matching the CLI's non-interactive nature)",
+    )
    .option('--json', 'Output full JSON event stream')
    .option('-v, --verbose', 'Show detailed tool call info')
    .option('--replay <file>', 'Replay events from a saved JSON file (offline)')
@@ -267,6 +271,7 @@ export function registerAgentCommand(program: Command) {
        agentId?: string;
        autoStart?: boolean;
        device?: string;
+        headless?: boolean;
        json?: boolean;
        prompt?: string;
        replay?: string;
@@ -340,6 +345,11 @@ export function registerAgentCommand(program: Command) {
        if (options.slug) input.slug = options.slug;
        if (options.topicId) input.appContext = { topicId: options.topicId };
        if (options.autoStart === false) input.autoStart = false;
+        // commander's --no-headless sets `headless` to false. Anything else
+        // (undefined, true) → headless mode is on and tool calls auto-execute.
+        if (options.headless !== false) {
+          input.userInterventionConfig = { approvalMode: 'headless' };
+        }

        const result = await client.aiAgent.execAgent.mutate(input as any);
        const r = result as any;
@@ -355,16 +365,17 @@ export function registerAgentCommand(program: Command) {
        }

        // 2. Connect to stream (WebSocket via Gateway, or fallback to SSE)
-        const { serverUrl, headers } = await getAgentStreamAuthInfo();
+        const { serverUrl, headers, token, tokenType } = await getAgentStreamAuthInfo();
        const agentGatewayUrl = options.sse ? undefined : resolveAgentGatewayUrl();

        if (agentGatewayUrl) {
-          const token = headers['Oidc-Auth'] || headers['X-API-Key'] || '';
          await streamAgentEventsViaWebSocket({
            gatewayUrl: agentGatewayUrl,
            json: options.json,
            operationId,
+            serverUrl,
            token,
+            tokenType,
            verbose: options.verbose,
          });
        } else {
@@ -270,6 +270,48 @@ describe('generate command', () => {
      );
      expect(consoleSpy).toHaveBeenCalledWith(expect.stringContaining('Video generation started'));
    });
+
+    it('should pass image-to-video params', async () => {
+      mockTrpcClient.generationTopic.createTopic.mutate.mockResolvedValue('topic-3');
+      mockTrpcClient.video.createVideo.mutate.mockResolvedValue({
+        data: { generationId: 'gen-v2' },
+        success: true,
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'generate',
+        'video',
+        'a cat waving',
+        '--model',
+        'cogvideox',
+        '--provider',
+        'zhipu',
+        '--image',
+        'https://example.com/first.png',
+        '--end-image',
+        'https://example.com/last.png',
+        '--images',
+        'https://example.com/a.png',
+        'https://example.com/b.png',
+      ]);
+
+      expect(mockTrpcClient.video.createVideo.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          generationTopicId: 'topic-3',
+          model: 'cogvideox',
+          params: {
+            endImageUrl: 'https://example.com/last.png',
+            imageUrl: 'https://example.com/first.png',
+            imageUrls: ['https://example.com/a.png', 'https://example.com/b.png'],
+            prompt: 'a cat waving',
+          },
+          provider: 'zhipu',
+        }),
+      );
+    });
  });

  describe('tts', () => {
@@ -6,13 +6,16 @@ import { getTrpcClient } from '../../api/client';
 export function registerVideoCommand(parent: Command) {
  parent
    .command('video <prompt>')
-    .description('Generate a video from text')
+    .description('Generate a video from text or image(s)')
    .requiredOption('-m, --model <model>', 'Model ID')
    .requiredOption('-p, --provider <provider>', 'Provider name')
    .option('--aspect-ratio <ratio>', 'Aspect ratio (e.g. 16:9)')
    .option('--duration <sec>', 'Duration in seconds')
    .option('--resolution <res>', 'Resolution (e.g. 720p, 1080p)')
    .option('--seed <n>', 'Random seed')
+    .option('--image <url>', 'First-frame image URL (image-to-video)')
+    .option('--images <urls...>', 'Multiple reference image URLs')
+    .option('--end-image <url>', 'Last-frame image URL')
    .option('--json', 'Output raw JSON')
    .action(
      async (
@@ -20,6 +23,9 @@ export function registerVideoCommand(parent: Command) {
        options: {
          aspectRatio?: string;
          duration?: string;
+          endImage?: string;
+          image?: string;
+          images?: string[];
          json?: boolean;
          model: string;
          provider: string;
@@ -35,6 +41,9 @@ export function registerVideoCommand(parent: Command) {
        if (options.duration) params.duration = Number.parseInt(options.duration, 10);
        if (options.resolution) params.resolution = options.resolution;
        if (options.seed) params.seed = Number.parseInt(options.seed, 10);
+        if (options.image) params.imageUrl = options.image;
+        if (options.images && options.images.length > 0) params.imageUrls = options.images;
+        if (options.endImage) params.endImageUrl = options.endImage;

        const result = await client.video.createVideo.mutate({
          generationTopicId: topicId as string,
@@ -79,6 +79,57 @@ describe('message command', () => {
      );
      expect(mockTrpcClient.message.listAll.query).not.toHaveBeenCalled();
    });
+
+    it('should keep first page on the backend default offset for filtered queries', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'message',
+        'list',
+        '--topic-id',
+        't1',
+        '-L',
+        '200',
+      ]);
+
+      expect(mockTrpcClient.message.getMessages.query).toHaveBeenCalledWith(
+        expect.objectContaining({ pageSize: 200, topicId: 't1' }),
+      );
+    });
+
+    it('should convert page 2 to current 1 for filtered queries', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'message',
+        'list',
+        '--topic-id',
+        't1',
+        '--page',
+        '2',
+      ]);
+
+      expect(mockTrpcClient.message.getMessages.query).toHaveBeenCalledWith(
+        expect.objectContaining({ current: 1, topicId: 't1' }),
+      );
+    });
+
+    it('should support the short page flag for filtered queries', async () => {
+      mockTrpcClient.message.getMessages.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'message', 'list', '--topic-id', 't1', '-P', '2']);
+
+      expect(mockTrpcClient.message.getMessages.query).toHaveBeenCalledWith(
+        expect.objectContaining({ current: 1, topicId: 't1' }),
+      );
+    });
  });

  describe('search', () => {
@@ -16,7 +16,7 @@ export function registerMessageCommand(program: Command) {
    .option('--topic-id <id>', 'Filter by topic ID')
    .option('--agent-id <id>', 'Filter by agent ID')
    .option('-L, --limit <n>', 'Page size', '30')
-    .option('--page <n>', 'Page number', '1')
+    .option('-P, --page <n>', 'Page number', '1')
    .option('--user', 'Only show user messages')
    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
    .action(
@@ -32,7 +32,9 @@ export function registerMessageCommand(program: Command) {

        const hasFilter = options.topicId || options.agentId;
        const pageSize = options.limit ? Number.parseInt(options.limit, 10) : undefined;
-        const current = options.page ? Number.parseInt(options.page, 10) : undefined;
+        const current = options.page
+          ? Math.max(Number.parseInt(options.page, 10) - 1, 0)
+          : undefined;

        let items: any[];

@@ -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 （待定）, _(待定)_, (TBD), N/A, etc.
+    // Filter out placeholder text like （待定）(Chinese TBD), _(待定)_, (TBD), N/A, etc.
    const isPlaceholder =
      rawAvatar && /^[_*（(].*[)）_*]$|^(?:tbd|todo|n\/?a|none|待定|未定)$/i.test(rawAvatar);
    const avatar = rawAvatar && !isPlaceholder ? rawAvatar : undefined;
@@ -0,0 +1,51 @@
+import type { Command } from 'commander';
+import pc from 'picocolors';
+
+import { getTrpcClient } from '../api/client';
+import { log } from '../utils/logger';
+
+export function registerNotifyCommand(program: Command) {
+  program
+    .command('notify')
+    .description('Send a callback message to a topic and trigger the agent to process it')
+    .requiredOption('--topic <topicId>', 'Target topic ID')
+    .requiredOption('-c, --content <content>', 'Message content')
+    .option('--agent-id <agentId>', 'Agent ID (overrides topic default)')
+    .option('--thread-id <threadId>', 'Thread ID for threaded conversations')
+    .option('--json', 'Output JSON')
+    .action(
+      async (options: {
+        agentId?: string;
+        content: string;
+        json?: boolean;
+        threadId?: string;
+        topic: string;
+      }) => {
+        log.debug('notify: topic=%s, agentId=%s', options.topic, options.agentId);
+
+        const client = await getTrpcClient();
+
+        try {
+          const result = await client.agentNotify.notify.mutate({
+            agentId: options.agentId,
+            content: options.content,
+            threadId: options.threadId,
+            topicId: options.topic,
+          });
+
+          if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+          }
+
+          console.log(`${pc.green('✓')} Message sent to topic ${pc.bold(result.topicId)}`);
+          if (result.operationId) {
+            console.log(`  Operation ID: ${result.operationId}`);
+          }
+        } catch (error: any) {
+          console.error(`${pc.red('✗')} Failed to send notification: ${error.message}`);
+          process.exit(1);
+        }
+      },
+    );
+}
@@ -56,7 +56,7 @@ export function registerTaskCommand(program: Command) {
        const client = await getTrpcClient();

        const input: Record<string, any> = {};
-        if (options.status) input.status = options.status;
+        if (options.status) input.statuses = [options.status];
        if (options.root) input.parentTaskId = null;
        if (options.parent) input.parentTaskId = options.parent;
        if (options.agent) input.assigneeAgentId = options.agent;
@@ -466,7 +466,12 @@ export function registerTaskCommand(program: Command) {
                  : act.priority === 'normal'
                    ? pc.yellow(' [normal]')
                    : '';
-              const resolved = act.resolvedAction ? pc.green(` ✏️ ${act.resolvedAction}`) : '';
+              const resolvedLabel = act.resolvedAction
+                ? act.resolvedComment
+                  ? `${act.resolvedAction}: ${act.resolvedComment}`
+                  : act.resolvedAction
+                : '';
+              const resolved = resolvedLabel ? pc.green(` ✏️ ${resolvedLabel}`) : '';
              const typeLabel = pc.dim(`[${act.briefType}]`);
              console.log(
                `  ${icon} ${pc.dim(ago.padStart(7))} Brief ${typeLabel} ${act.title}${pri}${resolved}${idSuffix}`,
@@ -77,6 +77,48 @@ describe('topic command', () => {
        expect.objectContaining({ agentId: 'a1' }),
      );
    });
+
+    it('should keep first page on the backend default offset', async () => {
+      mockTrpcClient.topic.getTopics.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'list', '--agent-id', 'a1', '-L', '200']);
+
+      expect(mockTrpcClient.topic.getTopics.query).toHaveBeenCalledWith(
+        expect.objectContaining({ agentId: 'a1', pageSize: 200 }),
+      );
+    });
+
+    it('should convert page 2 to current 1', async () => {
+      mockTrpcClient.topic.getTopics.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'topic',
+        'list',
+        '--agent-id',
+        'a1',
+        '--page',
+        '2',
+      ]);
+
+      expect(mockTrpcClient.topic.getTopics.query).toHaveBeenCalledWith(
+        expect.objectContaining({ agentId: 'a1', current: 1 }),
+      );
+    });
+
+    it('should support the short page flag', async () => {
+      mockTrpcClient.topic.getTopics.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'topic', 'list', '--agent-id', 'a1', '-P', '2']);
+
+      expect(mockTrpcClient.topic.getTopics.query).toHaveBeenCalledWith(
+        expect.objectContaining({ agentId: 'a1', current: 1 }),
+      );
+    });
  });

  describe('search', () => {
@@ -17,7 +17,7 @@ export function registerTopicCommand(program: Command) {
    .description('List topics')
    .option('--agent-id <id>', 'Filter by agent ID')
    .option('-L, --limit <n>', 'Page size', '30')
-    .option('--page <n>', 'Page number', '1')
+    .option('-P, --page <n>', 'Page number', '1')
    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
    .action(
      async (options: {
@@ -31,7 +31,8 @@ export function registerTopicCommand(program: Command) {
        const input: Record<string, any> = {};
        if (options.agentId) input.agentId = options.agentId;
        if (options.limit) input.pageSize = Number.parseInt(options.limit, 10);
-        if (options.page) input.current = Number.parseInt(options.page, 10);
+        const page = options.page ? Number.parseInt(options.page, 10) : undefined;
+        if (page !== undefined && page > 1) input.current = page - 1;

        const result = await client.topic.getTopics.query(input as any);
        const items = Array.isArray(result) ? result : ((result as any).items ?? []);
@@ -160,7 +160,7 @@ export function spawnDaemon(args: string[]): number {
  // Re-run the same entry with --daemon-child (internal flag)
  const child = spawn(process.execPath, [...process.execArgv, ...args, '--daemon-child'], {
    detached: true,
-    env: { ...process.env, LOBEHUB_DAEMON: '1' },
+    env: { ...process.env, ELECTRON_RUN_AS_NODE: '1', LOBEHUB_DAEMON: '1' },
    stdio: ['ignore', logFd, logFd],
  });

@@ -1,3 +1,3 @@
 import { createProgram } from './program';

-createProgram().parse();
+createProgram().parse(process.argv, { from: 'node' });
@@ -22,6 +22,7 @@ import { registerMemoryCommand } from './commands/memory';
 import { registerMessageCommand } from './commands/message';
 import { registerMigrateCommand } from './commands/migrate';
 import { registerModelCommand } from './commands/model';
+import { registerNotifyCommand } from './commands/notify';
 import { registerPluginCommand } from './commands/plugin';
 import { registerProviderCommand } from './commands/provider';
 import { registerSearchCommand } from './commands/search';
@@ -68,6 +69,7 @@ export function createProgram() {
  registerTopicCommand(program);
  registerMessageCommand(program);
  registerModelCommand(program);
+  registerNotifyCommand(program);
  registerProviderCommand(program);
  registerPluginCommand(program);
  registerUserCommand(program);
@@ -279,8 +279,10 @@ describe('streamAgentEventsViaWebSocket', () => {
    await flush();

    const ws = capturedWs!;
+    // Note: serverUrl is not set here, and JSON.stringify drops undefined keys,
+    // so the parsed auth message will not contain a `serverUrl` field.
    expect(ws.sent.map((s) => JSON.parse(s))).toEqual([
-      { token: 'test-token', type: 'auth' },
+      { token: 'test-token', tokenType: 'jwt', type: 'auth' },
      { lastEventId: '', type: 'resume' },
    ]);

@@ -288,6 +290,31 @@ describe('streamAgentEventsViaWebSocket', () => {
    await promise;
  });

+  it('should send tokenType=apiKey and serverUrl when the caller uses an API key', async () => {
+    const promise = streamAgentEventsViaWebSocket({
+      gatewayUrl: 'https://gw.test.com',
+      operationId: 'op-1',
+      serverUrl: 'https://app.lobehub.com',
+      token: 'lh_sk_abc',
+      tokenType: 'apiKey',
+    });
+
+    await flush();
+
+    const ws = capturedWs!;
+    // serverUrl is forwarded so the gateway can call back to /api/v1/users/me
+    // to verify the API key.
+    expect(ws.sent.map((s) => JSON.parse(s))[0]).toEqual({
+      serverUrl: 'https://app.lobehub.com',
+      token: 'lh_sk_abc',
+      tokenType: 'apiKey',
+      type: 'auth',
+    });
+
+    ws.simulateMessage({ id: '1', type: 'session_complete' });
+    await promise;
+  });
+
  it('should render agent_event messages using existing renderEvent', async () => {
    const promise = streamAgentEventsViaWebSocket({
      gatewayUrl: 'https://gw.test.com',
@@ -1,16 +1,10 @@
+import type { AgentStreamEvent } from '@lobechat/agent-gateway-client';
 import pc from 'picocolors';
 import urlJoin from 'url-join';

 import { log } from './logger';

-export interface AgentStreamEvent {
-  data: any;
-  id?: string;
-  operationId: string;
-  stepIndex: number;
-  timestamp: number;
-  type: string;
-}
+export type { AgentStreamEvent } from '@lobechat/agent-gateway-client';

 interface StreamOptions {
  json?: boolean;
@@ -20,7 +14,18 @@ interface StreamOptions {
 interface WebSocketStreamOptions extends StreamOptions {
  gatewayUrl: string;
  operationId: string;
+  /**
+   * LobeHub server URL the gateway should call back to when verifying
+   * an apiKey token (via `/api/v1/users/me`). Required when
+   * `tokenType === 'apiKey'`; ignored for JWT.
+   */
+  serverUrl?: string;
  token: string;
+  /**
+   * How the gateway should verify `token`. `jwt` is the default for
+   * backwards compatibility with existing callers.
+   */
+  tokenType?: 'jwt' | 'apiKey';
 }

 /**
@@ -168,13 +173,13 @@ const HEARTBEAT_INTERVAL = 30_000;
 export async function streamAgentEventsViaWebSocket(
  options: WebSocketStreamOptions,
 ): Promise<void> {
-  const { gatewayUrl, operationId, token, ...streamOpts } = options;
+  const { gatewayUrl, operationId, serverUrl, token, tokenType = 'jwt', ...streamOpts } = options;
  const wsUrl = urlJoin(
    gatewayUrl.replace(/^http/, 'ws'),
    `/ws?operationId=${encodeURIComponent(operationId)}`,
  );

-  log.debug(`Connecting to gateway: ${wsUrl}`);
+  log.debug(`Connecting to gateway: ${wsUrl} (auth: ${tokenType})`);

  return new Promise<void>((resolve, reject) => {
    const ws = new WebSocket(wsUrl);
@@ -192,7 +197,10 @@ export async function streamAgentEventsViaWebSocket(
    };

    ws.onopen = () => {
-      ws.send(JSON.stringify({ token, type: 'auth' }));
+      // `serverUrl` is required so the gateway can call back to verify an
+      // apiKey token. Harmless (but unused) for JWT, so we always include it
+      // when available to match the device-gateway-client contract.
+      ws.send(JSON.stringify({ serverUrl, token, tokenType, type: 'auth' }));
    };

    ws.onmessage = (event) => {
@@ -9,6 +9,10 @@ export default defineConfig({
  entry: ['src/index.ts'],
  fixedExtension: false,
  format: ['esm'],
+  minify: !!process.env.MINIFY,
+  outputOptions: {
+    codeSplitting: false,
+  },
  platform: 'node',
  target: 'node18',
 });
@@ -1,3 +1,7 @@
+## 专题文档
+
+- [桌面端全屏 Overlay 截图方案设计与集成说明](./WindowOverlayCapture.md)
+
 ## 核心框架组件目录架构

 ### 主进程核心组件
@@ -0,0 +1,502 @@
+# 桌面端全屏 Overlay 截图方案设计与集成说明
+
+| 字段         | 内容                                                  |
+| ------------ | ----------------------------------------------------- |
+| 状态         | 已完成技术预研与 demo 验证                            |
+| 最后更新     | 2026-04-14                                            |
+| 适用范围     | Electron 桌面端全屏遮罩、窗口高亮、点击截窗、区域截图 |
+| 当前验证载体 | `tmp/electron-window-overlay-demo`                    |
+| 目标读者     | 后续将该能力接入 LobeHub Desktop 主业务的开发者       |
+
+## 1. 文档目标
+
+本文档用于沉淀以下内容：
+
+| 目标                 | 说明                                                          |
+| -------------------- | ------------------------------------------------------------- |
+| 记录方案演进         | 保存从纯 Electron、native、自研、开源库到最终 demo 的决策过程 |
+| 固化关键技术结论     | 明确哪些能力 Electron 可做，哪些能力必须借助额外库            |
+| 提供业务接入蓝图     | 指出应修改的真实仓库文件、模块边界、IPC 设计与 UI 接入点      |
+| 降低后续重复调研成本 | 使后续实现可以直接沿用本文档，不必重新验证底层假设            |
+
+## 2. 需求回顾
+
+| 需求项                              | 结论                                                |
+| ----------------------------------- | --------------------------------------------------- |
+| 新增一个 “全屏” 入口                | 需要，但本质上是一个覆盖整块屏幕的透明 overlay 窗口 |
+| 覆盖用户整个 screen                 | 需要，且在 macOS 上要覆盖菜单栏与 Dock 所在区域     |
+| 获取系统窗口几何信息                | 需要，至少需要 `appName + bounds + windowId`        |
+| 在 overlay 上高亮窗口边框并显示 Tag | 需要                                                |
+| 点击高亮窗口即截图该窗口            | 需要                                                |
+| 拖拽任意区域截图                    | 需要                                                |
+| 输出先写入剪贴板                    | 需要，作为 MVP                                      |
+| 避免自研 native addon               | 明确要求避免                                        |
+| 跨平台预留                          | 需要，至少不能被 macOS-only 自研方案锁死            |
+
+## 3. 关键术语澄清
+
+### 3.1 “压住 macOS 菜单栏与 Dock” 的准确含义
+
+这里的含义不是 “调用系统 fullscreen API”，而是：
+
+| 项目     | 含义                                                         |
+| -------- | ------------------------------------------------------------ |
+| 覆盖范围 | 窗口尺寸必须基于 `display.bounds`，而不是 `display.workArea` |
+| Z 轴层级 | 窗口需要位于普通应用窗口之上，并且进入菜单栏所在区域         |
+| 视觉效果 | 用户看到的是整块屏幕都被半透明遮罩覆盖                       |
+
+必须区分以下两件事：
+
+| 易混概念                            | 实际含义                                             |
+| ----------------------------------- | ---------------------------------------------------- |
+| `app.dock.hide()`                   | 仅隐藏应用在 Dock 中的图标，不会隐藏系统 Dock 栏本身 |
+| `BrowserWindow.setFullScreen(true)` | 更接近原生全屏行为，未必适合作为截图 overlay         |
+
+## 4. 预研结论总览
+
+### 4.1 方案对比
+
+| 方案                                  | 能否覆盖菜单栏 / Dock | 能否拿到系统窗口 bounds |     能否按窗口截图 | 跨平台性 | 结论                       |
+| ------------------------------------- | --------------------: | ----------------------: | -----------------: | -------: | -------------------------- |
+| 纯 Electron `desktopCapturer`         |                    是 |                      否 | 部分可做，但不精确 |       高 | 不足以满足需求             |
+| 自研 native addon                     |                    是 |                      是 |                 是 |       中 | 能做，但被明确拒绝         |
+| 参考 Claude.app 的 native quick entry |                    是 |                      是 |                 是 |   低到中 | 可借鉴思路，不适合直接照搬 |
+| `node-screenshots` 单库               |                    是 |                      是 |                 是 |   中到高 | 核心方案成立               |
+| `node-screenshots + get-windows`      |                    是 |                      是 |                 是 |   中到高 | 当前最终方案               |
+
+### 4.2 最终选型
+
+| 能力                  | 最终实现                   |
+| --------------------- | -------------------------- |
+| 全屏 overlay 窗口     | Electron `BrowserWindow`   |
+| 系统窗口枚举          | `node-screenshots`         |
+| 指定窗口截图          | `node-screenshots`         |
+| 隐藏 / 伪关闭窗口过滤 | `get-windows` 作为白名单   |
+| 区域截图              | Electron `desktopCapturer` |
+| 输出介质              | `clipboard.writeImage()`   |
+
+## 5. 对 Claude.app 的观察结论
+
+本轮曾直接检查过本机解包后的 Claude.app 产物，结论如下：
+
+| 观察对象           | 结论                                                                                             |
+| ------------------ | ------------------------------------------------------------------------------------------------ |
+| `quick_window`     | 不是全屏 overlay；它是小尺寸 `panel` 弹窗                                                        |
+| `nativeQuickEntry` | Claude.app 存在原生 quick entry 能力，说明其真实覆盖式入口并不完全依赖纯 Electron                |
+| `cu-glow`          | 这是最接近本需求的 Electron overlay 实现：使用 `display.bounds`、透明窗、`screen-saver` 置顶层级 |
+
+据此可以得出两个重要判断：
+
+| 判断                                         | 含义 |
+| -------------------------------------------- | ---- |
+| Electron 可以做 “整屏遮罩”                   | 成立 |
+| Claude 的 “整屏入口” 并不等于 `quick_window` | 成立 |
+
+## 6. 当前 demo 的最终方案
+
+### 6.1 架构图
+
+```text
+┌──────────────────────────────┐
+│ Tray / Menu / Future Action  │
+└──────────────┬───────────────┘
+               │ startOverlaySession
+               ▼
+┌────────────────────────────────────────────┐
+│ Main Process                               │
+│                                            │
+│ 1. 选定当前光标所在 display                 │
+│ 2. 枚举窗口：node-screenshots              │
+│ 3. 过滤隐藏窗口：get-windows 白名单        │
+│ 4. 创建整屏 overlay BrowserWindow          │
+└──────────────┬─────────────────────────────┘
+               │ preload / IPC
+               ▼
+┌────────────────────────────────────────────┐
+│ Overlay Renderer                           │
+│                                            │
+│ 1. 渲染窗口高亮框与左上角 tag              │
+│ 2. 点击窗口 => captureWindow(windowId)     │
+│ 3. 拖拽区域 => captureRect(rect)           │
+└──────────────┬─────────────────────────────┘
+               │ IPC
+               ▼
+┌────────────────────────────────────────────┐
+│ Main Process Capture Path                  │
+│                                            │
+│ Window: node-screenshots.captureImage()    │
+│ Region: desktopCapturer + crop             │
+│ Output: clipboard.writeImage()             │
+└────────────────────────────────────────────┘
+```
+
+### 6.2 demo 文件职责
+
+| 文件                                                                                                                 | 作用                                         |
+| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
+| [`tmp/electron-window-overlay-demo/main.mjs`](../../tmp/electron-window-overlay-demo/main.mjs)                       | 主进程入口；创建 overlay，枚举窗口，执行截图 |
+| [`tmp/electron-window-overlay-demo/preload.cjs`](../../tmp/electron-window-overlay-demo/preload.cjs)                 | 为 overlay renderer 暴露 IPC bridge          |
+| [`tmp/electron-window-overlay-demo/renderer/index.html`](../../tmp/electron-window-overlay-demo/renderer/index.html) | overlay 渲染宿主页                           |
+| [`tmp/electron-window-overlay-demo/renderer/app.js`](../../tmp/electron-window-overlay-demo/renderer/app.js)         | 窗口高亮、点击截窗、拖拽截区交互             |
+| [`tmp/electron-window-overlay-demo/renderer/styles.css`](../../tmp/electron-window-overlay-demo/renderer/styles.css) | 遮罩视觉样式                                 |
+| [`tmp/electron-window-overlay-demo/README.md`](../../tmp/electron-window-overlay-demo/README.md)                     | demo 的运行说明                              |
+
+## 7. 全屏 overlay 的关键实现参数
+
+### 7.1 必要窗口参数
+
+| 参数 / 调用                         | 用途                               | 必要性 |
+| ----------------------------------- | ---------------------------------- | ------ |
+| `x/y/width/height = display.bounds` | 覆盖整块屏幕，包括菜单栏区域       | 必需   |
+| `transparent: true`                 | 允许渲染半透明遮罩                 | 必需   |
+| `frame: false`                      | 去除系统边框                       | 必需   |
+| `skipTaskbar: true`                 | 避免出现在任务栏 / Dock 窗口列表中 | 建议   |
+| `hasShadow: false`                  | 避免覆盖层产生自身投影             | 建议   |
+| `focusable: true`                   | 允许接收鼠标交互                   | 必需   |
+| `fullscreenable: false`             | 避免进入原生 fullscreen 流程       | 建议   |
+| `enableLargerThanScreen: true`      | 提升跨平台稳健性                   | 建议   |
+| `type: 'panel'`（macOS）            | 更接近工具层窗口行为               | 建议   |
+
+### 7.2 必要层级调用
+
+| 调用                                                             | 作用                              |
+| ---------------------------------------------------------------- | --------------------------------- |
+| `setAlwaysOnTop(true, 'screen-saver')`                           | 让窗口位于更高层级                |
+| `setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true })` | 避免 Space / 全屏窗口场景下不可见 |
+| `setHiddenInMissionControl(true)`                                | 降低该窗口对系统窗口管理的干扰    |
+
+### 7.3 重要结论
+
+| 结论                      | 说明                                        |
+| ------------------------- | ------------------------------------------- |
+| `display.workArea` 不可用 | 它会排除菜单栏 / Dock 区域                  |
+| `display.bounds` 必须使用 | 只有它能覆盖整个 display                    |
+| `screen-saver` 层级有效   | 这是当前 macOS 上最接近需求的 Electron 方案 |
+
+## 8. 系统窗口枚举与过滤策略
+
+### 8.1 为什么不能只用 Electron
+
+| Electron 能力                                       | 缺口                                                      |
+| --------------------------------------------------- | --------------------------------------------------------- |
+| `desktopCapturer.getSources({ types: ['window'] })` | 能列出可捕获源，但没有稳定的窗口 bounds 用于 overlay 画框 |
+| `DesktopCapturerSource.thumbnail`                   | 可截图缩略图，但不适合 “按原窗口精确高亮 + 点击即截”      |
+
+因此，纯 Electron 不足以完成 “系统窗口高亮 + 点击截窗”。
+
+### 8.2 `node-screenshots` 的职责
+
+| API                               | 用途           |
+| --------------------------------- | -------------- |
+| `Window.all()`                    | 枚举系统窗口   |
+| `window.id()`                     | 稳定识别窗口   |
+| `window.appName()`                | 获取应用名     |
+| `window.title()`                  | 获取标题       |
+| `window.x()/y()/width()/height()` | 获取几何信息   |
+| `window.captureImage()`           | 截取该窗口图像 |
+
+### 8.3 `get-windows` 的职责
+
+`get-windows` 在当前方案中不负责截图，而只负责 “第二层白名单过滤”。
+
+| 问题                                       | 处理方式                                                      |
+| ------------------------------------------ | ------------------------------------------------------------- |
+| 某些应用逻辑上已隐藏，但底层枚举仍可能残留 | 只保留同时出现在 `get-windows` 与 `node-screenshots` 中的窗口 |
+| Electron 自身的假关闭 /hide 行为           | 该白名单对这类情况更稳                                        |
+
+### 8.4 当前过滤规则
+
+| 规则                                             | 目的                         |
+| ------------------------------------------------ | ---------------------------- |
+| `isMinimized() === false`                        | 排除最小化窗口               |
+| 最小尺寸阈值：`80x60`                            | 排除菜单栏控件、过小悬浮面板 |
+| 排除 `Dock` / `Window Server` / `Control Centre` | 排除系统 UI                  |
+| 排除 demo 自身窗口                               | 避免 overlay 自我高亮        |
+| 必须与目标 display 相交                          | 只画当前屏幕可见窗口         |
+| 必须出现在 `get-windows` 白名单中                | 排除隐藏 / 伪关闭残留窗口    |
+
+## 9. 截图路径设计
+
+### 9.1 点击窗口截图
+
+```text
+点击高亮框
+  └───> renderer 发送 windowId
+          └───> main 查找对应 node-screenshots Window
+                  └───> overlay.hide()
+                          └───> captureImage()
+                                  └───> PNG Buffer
+                                          └───> nativeImage
+                                                  └───> clipboard.writeImage()
+```
+
+### 9.2 拖拽区域截图
+
+```text
+拖拽区域
+  └───> renderer 发送全局 rect
+          └───> main 隐藏 overlay
+                  └───> desktopCapturer 获取目标 display 图像
+                          └───> 按 scaleFactor 计算 cropRect
+                                  └───> clipboard.writeImage()
+```
+
+### 9.3 为什么两条路径采用不同技术
+
+| 路径       | 技术               | 原因                              |
+| ---------- | ------------------ | --------------------------------- |
+| 按窗口截图 | `node-screenshots` | 它天然理解 “窗口” 这一对象        |
+| 按区域截图 | `desktopCapturer`  | 区域本质上是 display 上的矩形裁剪 |
+
+## 10. 权限与平台边界
+
+### 10.1 macOS 权限
+
+| 权限             | 是否需要         | 用途                                                  |
+| ---------------- | ---------------- | ----------------------------------------------------- |
+| Screen Recording | 需要             | 窗口截图、区域截图                                    |
+| Accessibility    | 当前方案不强依赖 | `get-windows` 已使用 `accessibilityPermission: false` |
+
+### 10.2 当前已知平台边界
+
+| 平台 / 场景   | 状态     | 说明                                                                  |
+| ------------- | -------- | --------------------------------------------------------------------- |
+| macOS         | 已验证   | 当前主要验证平台                                                      |
+| Windows       | 理论可行 | `node-screenshots` / `get-windows` 均支持，但尚未在本仓库内做实机验证 |
+| Linux X11     | 理论可行 | 需要单独验证打包与权限                                                |
+| Linux Wayland | 风险较高 | 上游库虽宣称支持，但必须做专项验证                                    |
+
+### 10.3 特殊窗口风险
+
+| 风险类型               | 当前处理                                                       |
+| ---------------------- | -------------------------------------------------------------- |
+| 菜单栏状态窗 / 面板    | 通过尺寸阈值与排除名单降低噪音                                 |
+| 系统 UI                | 通过应用名黑名单排除                                           |
+| 某些应用截图结果为黑图 | 已观察到个别状态面板存在此现象，应在业务层继续限制候选窗口类别 |
+
+## 11. 已完成验证
+
+| 验证项                              | 结果 | 产物                                                                                                                                                     |
+| ----------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| overlay 覆盖整屏                    | 通过 | [`tmp/electron-window-overlay-demo/.cache/window-overlay-visual.png`](../../tmp/electron-window-overlay-demo/.cache/window-overlay-visual.png)           |
+| `node-screenshots` 直接截图普通窗口 | 通过 | [`tmp/electron-window-overlay-demo/.cache/cursor-direct.png`](../../tmp/electron-window-overlay-demo/.cache/cursor-direct.png)                           |
+| 点击高亮窗口后写入剪贴板            | 通过 | [`tmp/electron-window-overlay-demo/.cache/window-capture-probe-final.png`](../../tmp/electron-window-overlay-demo/.cache/window-capture-probe-final.png) |
+| 拖拽区域截图                        | 通过 | [`tmp/electron-window-overlay-demo/.cache/self-test-clipboard-final.png`](../../tmp/electron-window-overlay-demo/.cache/self-test-clipboard-final.png)   |
+
+## 12. 推荐的业务接入方式
+
+### 12.1 总体建议
+
+| 维度                 | 建议                                                                               |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| overlay 窗口生命周期 | 不建议直接挂进现有 `BrowserManager` 的常规窗口体系                                 |
+| 原因                 | overlay 是瞬态、全屏、平台特化、不可持久化的工具窗口，与主业务窗口生命周期明显不同 |
+| 推荐做法             | 新增独立主进程模块管理 overlay；渲染内容仍建议走现有 SPA 路由体系                  |
+
+### 12.2 为什么不直接复用 `BrowserManager`
+
+| 观察                                      | 影响                            |
+| ----------------------------------------- | ------------------------------- |
+| `Browser` 默认承担普通业务窗口职责        | overlay 并非普通业务窗口        |
+| `WindowStateManager` 倾向保存窗口状态     | overlay 不应持久化位置与大小    |
+| `BrowserManager` 以 “可复用业务窗口” 建模 | overlay 更接近 “一次性工具会话” |
+
+因此，更合理的做法是：
+
+```text
+┌────────────────────────────┐
+│ BrowserManager             │ 负责常规业务窗口
+└────────────────────────────┘
+
+┌────────────────────────────┐
+│ CaptureOverlayManager      │ 负责全屏截图 overlay 会话
+└────────────────────────────┘
+```
+
+## 13. 建议的生产代码落点
+
+### 13.1 主进程
+
+| 建议文件                                                               | 作用                                                               |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `apps/desktop/src/main/modules/screenCapture/CaptureOverlayManager.ts` | 创建 / 销毁 overlay 窗口；管理一次截图会话                         |
+| `apps/desktop/src/main/modules/screenCapture/WindowSourceService.ts`   | 封装 `node-screenshots + get-windows` 的窗口枚举与过滤             |
+| `apps/desktop/src/main/modules/screenCapture/CaptureService.ts`        | 封装窗口截图、区域截图、剪贴板输出                                 |
+| `apps/desktop/src/main/modules/screenCapture/permission.ts`            | 封装 macOS 屏幕录制权限检查                                        |
+| `apps/desktop/src/main/controllers/ScreenCaptureCtr.ts`                | 对 renderer 暴露 `start / captureRect / captureWindow / close` IPC |
+| `apps/desktop/src/main/controllers/registry.ts`                        | 注册 `ScreenCaptureCtr`                                            |
+
+### 13.2 IPC 类型
+
+| 建议文件                                                  | 作用                                              |
+| --------------------------------------------------------- | ------------------------------------------------- |
+| `packages/electron-client-ipc/src/types/screenCapture.ts` | 定义 overlay 会话、窗口元数据、截图参数与返回结果 |
+| `packages/electron-client-ipc/src/types/index.ts`         | 导出新类型                                        |
+
+建议定义的核心类型：
+
+| 类型名                     | 用途                                                |
+| -------------------------- | --------------------------------------------------- |
+| `ScreenCaptureDisplayInfo` | display id / bounds / scaleFactor                   |
+| `ScreenCaptureWindowInfo`  | `windowId/appName/title/bounds/overlayBounds/order` |
+| `ScreenCaptureSession`     | `display + windows`                                 |
+| `CaptureRectParams`        | 全局屏幕坐标的矩形                                  |
+| `ScreenCaptureStartResult` | 权限状态、会话状态、错误信息                        |
+| `ScreenCaptureOutput`      | `clipboard`、后续可扩展 `file`、`attachment`        |
+
+### 13.3 Preload 与 renderer service
+
+| 建议文件                                  | 作用                                               |
+| ----------------------------------------- | -------------------------------------------------- |
+| `apps/desktop/src/preload/electronApi.ts` | 通常无需特殊改造；沿用统一 `invoke` 即可           |
+| `src/services/electron/screenCapture.ts`  | 前端统一调用 `ensureElectronIpc().screenCapture.*` |
+
+### 13.4 Renderer 路由
+
+生产环境存在两种可选实现：
+
+| 方案               | 优点                             | 缺点                             | 建议             |
+| ------------------ | -------------------------------- | -------------------------------- | ---------------- |
+| 独立静态 HTML 页面 | 轻量、与业务隔离、最接近 demo    | 与现有 React/i18n / 业务状态脱节 | 仅适合 spike     |
+| 独立桌面 SPA 路由  | 可复用现有构建、i18n、业务事件链 | 需要维护 desktop router 双配置   | **推荐生产使用** |
+
+若采用 SPA 路由，建议新增：
+
+| 建议文件                                                | 作用                                 |
+| ------------------------------------------------------- | ------------------------------------ |
+| `src/routes/(desktop)/screen-capture-overlay/index.tsx` | overlay 页面入口；仅负责挂载 UI 组件 |
+| `src/features/DesktopScreenCaptureOverlay/*`            | 业务组件、hooks、样式                |
+| `src/spa/router/desktopRouter.config.tsx`               | 动态路由配置                         |
+| `src/spa/router/desktopRouter.config.desktop.tsx`       | 同步路由配置                         |
+
+必须注意：
+
+| 规则                             | 说明                                 |
+| -------------------------------- | ------------------------------------ |
+| 两份 desktop router 必须同时更新 | 否则 Electron 本地构建可能出现空白页 |
+| overlay route 应保持极薄         | 不在 route 文件中堆叠业务逻辑        |
+
+## 14. 托盘入口的真实接入点
+
+若要从托盘启动 overlay，会涉及以下文件：
+
+| 文件                                            | 作用                 |
+| ----------------------------------------------- | -------------------- |
+| `apps/desktop/src/main/menus/impls/macOS.ts`    | macOS 托盘菜单模板   |
+| `apps/desktop/src/main/menus/impls/windows.ts`  | Windows 托盘菜单模板 |
+| `apps/desktop/src/main/menus/impls/linux.ts`    | Linux 托盘菜单模板   |
+| `apps/desktop/src/main/locales/default/menu.ts` | 托盘菜单文案         |
+
+推荐新增文案键：
+
+| Key                        | 语义                     |
+| -------------------------- | ------------------------ |
+| `tray.captureScreen`       | 启动截图 overlay         |
+| `tray.captureScreenWindow` | 启动窗口截图模式（可选） |
+
+## 15. 业务接入分阶段计划
+
+### 阶段一：桌面主进程能力落地
+
+| 步骤 | 目标                                                                               |
+| ---- | ---------------------------------------------------------------------------------- |
+| 1    | 将 `node-screenshots`、`get-windows` 加入 `apps/desktop/package.json#dependencies` |
+| 2    | 新建 `screenCapture` 主进程模块与 controller                                       |
+| 3    | 跑通托盘菜单触发 overlay                                                           |
+| 4    | 继续以剪贴板为唯一输出                                                             |
+
+### 阶段二：接回现有业务 UI
+
+| 步骤 | 目标                                               |
+| ---- | -------------------------------------------------- |
+| 1    | 新增桌面专用 overlay route /feature                |
+| 2    | 将截图结果从 “仅写剪贴板” 升级为 “回传 attachment” |
+| 3    | 支持从 chat 输入区触发                             |
+| 4    | 支持截图后自动插入当前会话                         |
+
+### 阶段三：体验完善
+
+| 步骤 | 目标                                 |
+| ---- | ------------------------------------ |
+| 1    | 多 display 支持                      |
+| 2    | Hover 高亮 / 文案优化                |
+| 3    | 保存文件、编辑器标注、OCR 等增强能力 |
+| 4    | 平台差异补齐（尤其 Windows / Linux） |
+
+## 16. 依赖落点与版本建议
+
+### 16.1 应加入的位置
+
+| 文件                        | 说明                              |
+| --------------------------- | --------------------------------- |
+| `apps/desktop/package.json` | Electron 桌面运行时的真实依赖落点 |
+
+### 16.2 建议依赖
+
+| 包名               | 用途                        | 当前 demo 使用版本 |
+| ------------------ | --------------------------- | ------------------ |
+| `node-screenshots` | 枚举窗口 + 窗口截图         | `^0.2.8`           |
+| `get-windows`      | 白名单过滤隐藏 / 伪关闭窗口 | `^9.3.0`           |
+
+说明：
+
+| 项目                         | 结论 |
+| ---------------------------- | ---- |
+| 这不是 “纯 Electron” 方案    | 成立 |
+| 这也不是 “自研 native addon” | 成立 |
+| 当前依赖的是开源原生库       | 成立 |
+
+## 17. 测试建议
+
+建议避免写 “窗口列表快照” 这类低信号测试，优先做行为测试。
+
+| 测试层级       | 建议内容                                                   |
+| -------------- | ---------------------------------------------------------- |
+| 单元测试       | 过滤逻辑：尺寸阈值、系统应用排除、自身窗口排除、白名单交集 |
+| 主进程集成测试 | 权限失败、overlay 会话生命周期、错误分支                   |
+| 手工验证       | 菜单栏覆盖、点击截窗、拖拽截区、隐藏窗口过滤               |
+
+建议手工验证清单：
+
+| 检查项                   | 期望                     |
+| ------------------------ | ------------------------ |
+| 当前活动屏幕启动 overlay | 只覆盖当前目标 display   |
+| 已隐藏的 Electron 子窗口 | 不再出现边框             |
+| 点击普通应用窗口         | 剪贴板中得到该窗口图像   |
+| 拖拽区域截图             | 剪贴板中得到对应裁剪区域 |
+| 取消操作                 | `Esc` 可关闭 overlay     |
+
+## 18. 当前已确认的非目标
+
+| 非目标                              | 说明                                                                    |
+| ----------------------------------- | ----------------------------------------------------------------------- |
+| 当前阶段支持全平台一致体验          | 尚未完成                                                                |
+| 当前阶段支持窗口标题绝对准确        | `get-windows` 在无额外权限时标题可为空；当前主要依赖 `node-screenshots` |
+| 当前阶段支持多 display 同时 overlay | 尚未实现                                                                |
+| 当前阶段支持标注编辑器              | 未实现                                                                  |
+
+## 19. 后续实现时的推荐决策
+
+| 决策点                                          | 推荐                     |
+| ----------------------------------------------- | ------------------------ |
+| overlay 窗口是否复用 `BrowserManager`           | 不推荐                   |
+| renderer 是否走 SPA route                       | 推荐                     |
+| 主进程是否继续保留 “剪贴板优先” 输出            | 推荐，先保持最小可用闭环 |
+| 是否继续保留 `desktopCapturer` 作为区域截图路径 | 推荐                     |
+| 是否用 `get-windows` 继续做白名单过滤           | 推荐                     |
+
+## 20. 实施摘要
+
+```text
+┌──────────────────────────────────────────────┐
+│ 已验证的技术事实                             │
+├──────────────────────────────────────────────┤
+│ 1. Electron 可以创建覆盖整块 display 的窗体  │
+│ 2. 纯 Electron 无法独立完成系统窗口高亮      │
+│ 3. node-screenshots 可完成窗口枚举与截窗     │
+│ 4. get-windows 可帮助过滤隐藏 / 残留窗口     │
+│ 5. 最终可形成“点击窗口即截图 + 拖拽截区”闭环 │
+└──────────────────────────────────────────────┘
+```
+
+本文档可视为后续将该能力正式接入 `apps/desktop` 主业务的实施基线。
@@ -109,6 +109,26 @@ const config = {

    console.info('📦 Downloading agent-browser binary...');
    execSync('node scripts/download-agent-browser.mjs', { stdio: 'inherit', cwd: __dirname });
+
+    // Build and copy CLI bundle for embedding
+    console.info('📦 Building CLI for embedding...');
+    execSync('npm run build:cli', { stdio: 'inherit', cwd: __dirname });
+    const cliSrc = path.resolve(__dirname, '../cli/dist/index.js');
+    const cliDest = path.resolve(__dirname, 'resources/bin/lobe-cli.js');
+    await fs.copyFile(cliSrc, cliDest);
+
+    // Write a minimal package.json next to the CLI bundle so that
+    // createRequire('../package.json') resolves correctly in the packaged app.
+    // The CLI script lives at Resources/bin/lobe-cli.js, so '../package.json'
+    // resolves to Resources/package.json.
+    const cliPkg = JSON.parse(
+      await fs.readFile(path.resolve(__dirname, '../cli/package.json'), 'utf8'),
+    );
+    await fs.writeFile(
+      path.resolve(__dirname, 'resources/cli-package.json'),
+      JSON.stringify({ name: cliPkg.name, type: 'module', version: cliPkg.version }),
+    );
+    console.info('✅ CLI bundle copied to resources/bin/lobe-cli.js');
  },
  /**
   * AfterPack hook for post-processing:
@@ -235,6 +255,7 @@ const config = {
  generateUpdatesFilesForAllChannels: true,
  linux: {
    category: 'Utility',
+    icon: 'build/icon.png',
    maintainer: 'electronjs.org',
    target: ['AppImage', 'snap', 'deb', 'rpm', 'tar.gz'],
  },
@@ -296,7 +317,10 @@ const config = {
    releaseNotes: process.env.RELEASE_NOTES || undefined,
  },

-  extraResources: [{ from: 'resources/bin', to: 'bin' }],
+  extraResources: [
+    { from: 'resources/bin', to: 'bin' },
+    { from: 'resources/cli-package.json', to: 'package.json' },
+  ],

  win: {
    executableName: 'LobeHub',
@@ -1,6 +1,7 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';

+import { vanillaExtractPlugin } from '@vanilla-extract/vite-plugin';
 import dotenv from 'dotenv';
 import { defineConfig } from 'electron-vite';
 import type { PluginOption, ViteDevServer } from 'vite';
@@ -15,15 +16,69 @@ import {
 import { getExternalDependencies } from './native-deps.config.mjs';

 /**
- * Rewrite `/` to `/apps/desktop/index.html` so the electron-vite dev server
- * serves the desktop HTML entry when root is the monorepo root.
+ * Force `base: '/'` in renderer config. The `electron-vite` preset
+ * unconditionally rewrites base to `'./'` in production (with `enforce: 'pre'`),
+ * which produces relative asset URLs like `../../assets/...`. Those break in
+ * the popup window because its SPA URL (`/popup/agent/:aid/:tid`) is deep
+ * enough that relative resolution lands at `/popup/assets/...` instead of the
+ * actual `/assets/...`. Our `app://` protocol handler resolves absolute
+ * `/assets/...` correctly regardless of URL depth.
+ */
+function forceAbsoluteBasePlugin(): PluginOption {
+  return {
+    name: 'electron-desktop-force-base',
+    config(config) {
+      config.base = '/';
+    },
+  };
+}
+
+/**
+ * Rewrite SPA routes to their corresponding HTML entry so the electron-vite
+ * dev server serves the right HTML when root is the monorepo root.
+ *
+ * - `/popup/*` → `/apps/desktop/popup.html` (topic popup SPA)
+ * - `/`, `/index.html`, and everything else → `/apps/desktop/index.html`
 */
 function electronDesktopHtmlPlugin(): PluginOption {
  return {
    configureServer(server: ViteDevServer) {
      server.middlewares.use((req, _res, next) => {
-        if (req.url === '/' || req.url === '/index.html') {
+        const rawUrl = req.url ?? '';
+        const pathname = rawUrl.split('?')[0];
+
+        // Explicit document-entry requests — always rewrite.
+        if (pathname === '/' || pathname === '/index.html') {
          req.url = '/apps/desktop/index.html';
+          next();
+          return;
+        }
+        if (pathname === '/overlay' || pathname === '/overlay.html') {
+          req.url = '/apps/desktop/overlay.html';
+          next();
+          return;
+        }
+        if (pathname === '/popup.html') {
+          req.url = '/apps/desktop/popup.html';
+          next();
+          return;
+        }
+
+        // For SPA deep links (e.g. `/popup/agent/A/T`) rewrite to the popup
+        // HTML — but skip asset / module requests that happen to share the
+        // prefix (e.g. `/popup/@vite/client` would have been generated by a
+        // mis-resolved relative import).
+        const lastSegment = pathname.split('/').pop() ?? '';
+        const looksLikeAsset =
+          lastSegment.includes('.') ||
+          pathname.startsWith('/@') ||
+          pathname.startsWith('/src/') ||
+          pathname.startsWith('/node_modules/') ||
+          pathname.startsWith('/apps/') ||
+          pathname.startsWith('/packages/');
+
+        if (!looksLikeAsset && (pathname === '/popup' || pathname.startsWith('/popup/'))) {
+          req.url = '/apps/desktop/popup.html';
        }
        next();
      });
@@ -43,6 +98,8 @@ const updateChannel = process.env.UPDATE_CHANNEL;
 const desktopPackageJson = JSON.parse(
  readFileSync(path.resolve(__dirname, 'package.json'), 'utf8'),
 ) as { version: string };
+const electronRuntimeExternals = ['electron'];
+const mainProcessRuntimeExternals = [...electronRuntimeExternals, 'node-mac-permissions'];

 console.info(`[electron-vite.config.ts] Detected UPDATE_CHANNEL: ${updateChannel}`);

@@ -51,10 +108,15 @@ export default defineConfig({
    build: {
      minify: !isDev,
      outDir: 'dist/main',
-      rollupOptions: {
+      rolldownOptions: {
        // Native modules must be externalized to work correctly.
        // bufferutil and utf-8-validate are optional peer deps of ws that may not be installed.
-        external: [...getExternalDependencies(), 'bufferutil', 'utf-8-validate'],
+        external: [
+          ...mainProcessRuntimeExternals,
+          ...getExternalDependencies(),
+          'bufferutil',
+          'utf-8-validate',
+        ],
        output: {
          // Prevent debug package from being bundled into index.js to avoid side-effect pollution
          manualChunks(id) {
@@ -88,9 +150,11 @@ export default defineConfig({
    build: {
      minify: !isDev,
      outDir: 'dist/preload',
+      rolldownOptions: {
+        external: electronRuntimeExternals,
+      },
      sourcemap: isDev ? 'inline' : false,
    },
-
    resolve: {
      alias: {
        '@': path.resolve(__dirname, 'src/main'),
@@ -102,8 +166,12 @@ export default defineConfig({
    root: ROOT_DIR,
    build: {
      outDir: path.resolve(__dirname, 'dist/renderer'),
-      rollupOptions: {
-        input: path.resolve(__dirname, 'index.html'),
+      rolldownOptions: {
+        input: {
+          main: path.resolve(__dirname, 'index.html'),
+          overlay: path.resolve(__dirname, 'overlay.html'),
+          popup: path.resolve(__dirname, 'popup.html'),
+        },
        output: sharedRollupOutput,
      },
    },
@@ -113,7 +181,9 @@ export default defineConfig({
    },
    optimizeDeps: sharedOptimizeDeps,
    plugins: [
+      forceAbsoluteBasePlugin(),
      electronDesktopHtmlPlugin(),
+      vanillaExtractPlugin(),
      ...(sharedRendererPlugins({ platform: 'desktop' }) as PluginOption[]),
    ],
    resolve: {
@@ -36,7 +36,8 @@ export const nativeModules = [
  // macOS-only native modules
  ...(isDarwin ? ['node-mac-permissions'] : []),
  '@napi-rs/canvas',
-  // Add more native modules here as needed
+  'get-windows',
+  'node-screenshots',
 ];

 /**
@@ -0,0 +1,15 @@
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      * { margin: 0; padding: 0; box-sizing: border-box; }
+      html, body, #root { width: 100%; height: 100%; overflow: hidden; background: transparent; }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/apps/desktop/src/overlay/entry.tsx"></script>
+  </body>
+</html>
@@ -11,6 +11,7 @@
  "author": "LobeHub",
  "main": "./dist/main/index.js",
  "scripts": {
+    "build:cli": "cd ../cli && cross-env MINIFY=1 bun run build",
    "build:main": "cross-env NODE_OPTIONS=--max-old-space-size=8192 electron-vite build",
    "build:run-unpack": "electron .",
    "dev": "electron-vite dev",
@@ -41,7 +42,10 @@
    "update-server": "sh scripts/update-test/run-test.sh"
  },
  "dependencies": {
-    "@napi-rs/canvas": "^0.1.70"
+    "@lobehub/fluent-emoji": "^4.1.0",
+    "@napi-rs/canvas": "^0.1.70",
+    "get-windows": "^9.3.0",
+    "node-screenshots": "^0.2.8"
  },
  "devDependencies": {
    "@electron-toolkit/eslint-config-prettier": "^3.0.0",
@@ -63,6 +67,8 @@
    "@types/semver": "^7.7.1",
    "@types/set-cookie-parser": "^2.4.10",
    "@typescript/native-preview": "7.0.0-dev.20251210.1",
+    "@vanilla-extract/css": "^1.17.4",
+    "@vanilla-extract/vite-plugin": "^5.1.0",
    "async-retry": "^1.3.3",
    "consola": "^3.4.2",
    "cookie": "^1.1.1",
@@ -75,7 +81,7 @@
    "electron-log": "^5.4.3",
    "electron-store": "^8.2.0",
    "electron-updater": "^6.6.2",
-    "electron-vite": "^5.0.0",
+    "electron-vite": "6.0.0-beta.1",
    "electron-window-state": "^5.0.3",
    "es-toolkit": "^1.43.0",
    "eslint": "10.0.0",
@@ -95,13 +101,14 @@
    "resolve": "^1.22.11",
    "semver": "^7.7.3",
    "set-cookie-parser": "^2.7.2",
+    "strip-ansi": "6.0.1",
    "stylelint": "^15.11.0",
    "superjson": "^2.2.6",
    "tsx": "^4.21.0",
    "typescript": "^5.9.3",
    "undici": "^7.16.0",
    "uuid": "^13.0.0",
-    "vite": "^7.3.1",
+    "vite": "^8.0.9",
    "vitest": "^3.2.4",
    "zod": "^3.25.76"
  },
@@ -1,8 +1,13 @@
 packages:
+  - '../cli'
+  - '../../packages/agent-gateway-client'
+  - '../../packages/const'
  - '../../packages/electron-server-ipc'
  - '../../packages/electron-client-ipc'
  - '../../packages/file-loaders'
  - '../../packages/desktop-bridge'
  - '../../packages/device-gateway-client'
  - '../../packages/local-file-shell'
+  - './stubs/business-const'
+  - './stubs/types'
  - '.'
@@ -0,0 +1,114 @@
+<!doctype html>
+<html class="desktop">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+        background: transparent;
+      }
+      html[data-theme='dark'] {
+        background: #141414;
+      }
+      html[data-theme='light'] {
+        background: #fafafa;
+      }
+      #loading-screen {
+        position: fixed;
+        inset: 0;
+        z-index: 99999;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        background: inherit;
+        gap: 12px;
+      }
+      @keyframes loading-draw {
+        0% {
+          stroke-dashoffset: 1000;
+        }
+        100% {
+          stroke-dashoffset: 0;
+        }
+      }
+      @keyframes loading-fill {
+        30% {
+          fill-opacity: 0.05;
+        }
+        100% {
+          fill-opacity: 1;
+        }
+      }
+      #loading-brand {
+        display: flex;
+        align-items: center;
+        gap: 12px;
+        color: #1f1f1f;
+      }
+      #loading-brand svg path {
+        fill: currentcolor;
+        fill-opacity: 0;
+        stroke: currentcolor;
+        stroke-dasharray: 1000;
+        stroke-dashoffset: 1000;
+        stroke-width: 0.25em;
+        animation:
+          loading-draw 2s cubic-bezier(0.4, 0, 0.2, 1) infinite,
+          loading-fill 2s cubic-bezier(0.4, 0, 0.2, 1) infinite;
+      }
+      html[data-theme='dark'] #loading-brand {
+        color: #f0f0f0;
+      }
+    </style>
+  </head>
+  <body>
+    <script>
+      (function () {
+        var theme = 'system';
+        try {
+          theme = localStorage.getItem('theme') || 'system';
+        } catch (_) {}
+        var systemTheme =
+          window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches
+            ? 'dark'
+            : 'light';
+        var resolvedTheme = theme === 'system' ? systemTheme : theme;
+        if (resolvedTheme === 'dark' || resolvedTheme === 'light') {
+          document.documentElement.setAttribute('data-theme', resolvedTheme);
+        }
+        var urlParams = new URLSearchParams(window.location.search);
+        var locale = urlParams.get('lng') || navigator.language || 'en-US';
+        document.documentElement.lang = locale;
+        var rtl = ['ar', 'arc', 'dv', 'fa', 'ha', 'he', 'khw', 'ks', 'ku', 'ps', 'ur', 'yi'];
+        document.documentElement.dir =
+          rtl.indexOf(locale.split('-')[0].toLowerCase()) >= 0 ? 'rtl' : 'ltr';
+      })();
+    </script>
+    <div id="loading-screen">
+      <div id="loading-brand" aria-label="Loading" role="status">
+        <svg
+          fill="currentColor"
+          fill-rule="evenodd"
+          height="40"
+          style="flex: none; line-height: 1"
+          viewBox="0 0 940 320"
+          xmlns="http://www.w3.org/2000/svg"
+        >
+          <title>LobeHub</title>
+          <path
+            d="M15 240.035V87.172h39.24V205.75h66.192v34.285H15zM183.731 242c-11.759 0-22.196-2.621-31.313-7.862-9.116-5.241-16.317-12.447-21.601-21.619-5.153-9.317-7.729-19.945-7.729-31.883 0-11.937 2.576-22.492 7.729-31.664 5.164-8.963 12.159-15.98 20.982-21.05l.619-.351c9.117-5.241 19.554-7.861 31.313-7.861s22.196 2.62 31.313 7.861c9.248 5.096 16.449 12.229 21.601 21.401 5.153 9.172 7.729 19.727 7.729 31.664 0 11.938-2.576 22.566-7.729 31.883-5.152 9.172-12.353 16.378-21.601 21.619-9.117 5.241-19.554 7.862-31.313 7.862zm0-32.975c4.36 0 8.191-1.092 11.494-3.275 3.436-2.184 6.144-5.387 8.126-9.609 1.982-4.367 2.973-9.536 2.973-15.505 0-5.968-.991-10.991-2.973-15.067-1.906-4.06-4.483-7.177-7.733-9.352l-.393-.257c-3.303-2.184-7.134-3.276-11.494-3.276-4.228 0-8.059 1.092-11.495 3.276-3.303 2.184-6.011 5.387-8.125 9.609-1.982 4.076-2.973 9.099-2.973 15.067 0 5.969.991 11.138 2.973 15.505 2.114 4.222 4.822 7.425 8.125 9.609 3.436 2.183 7.267 3.275 11.495 3.275zM295.508 78l-.001 54.042a34.071 34.071 0 016.541-5.781c6.474-4.367 14.269-6.551 23.385-6.551 9.777 0 18.629 2.475 26.557 7.424 7.872 4.835 14.105 11.684 18.7 20.546l.325.637c4.756 9.026 7.135 19.799 7.135 32.319 0 12.666-2.379 23.585-7.135 32.757-4.624 9.026-10.966 16.087-19.025 21.182-7.928 4.95-16.78 7.425-26.557 7.425-9.644 0-17.704-2.184-24.178-6.551-2.825-1.946-5.336-4.355-7.532-7.226l.001 11.812h-35.87V78h37.654zm21.998 74.684c-4.228 0-8.059 1.092-11.494 3.276-3.303 2.184-6.012 5.387-8.126 9.609-1.982 4.076-2.972 9.099-2.972 15.067 0 5.969.99 11.138 2.972 15.505 2.114 4.222 4.823 7.425 8.126 9.609 3.435 2.183 7.266 3.275 11.494 3.275s7.994-1.092 11.297-3.275c3.435-2.184 6.143-5.387 8.125-9.609 2.114-4.367 3.171-9.536 3.171-15.505 0-5.968-1.057-10.991-3.171-15.067-1.906-4.06-4.483-7.177-7.732-9.352l-.393-.257c-3.303-2.184-7.069-3.276-11.297-3.276zm105.335 38.653l.084.337a27.857 27.857 0 002.057 5.559c2.246 4.222 5.417 7.498 9.513 9.827 4.096 2.184 8.984 3.276 14.665 3.276 5.285 0 9.777-.801 13.477-2.403 3.579-1.632 7.1-4.025 10.564-7.182l.732-.679 19.818 22.711c-5.153 6.26-11.494 11.064-19.025 14.413-7.531 3.203-16.449 4.804-26.755 4.804-12.683 0-23.782-2.621-33.294-7.862-9.381-5.386-16.713-12.665-21.998-21.837-5.153-9.317-7.729-19.872-7.729-31.665 0-11.792 2.51-22.274 7.53-31.446 5.036-9.105 11.902-16.195 20.596-21.268l.61-.351c8.984-5.241 19.091-7.861 30.322-7.861 10.311 0 19.743 2.286 28.294 6.859l.64.347c8.72 4.659 15.656 11.574 20.809 20.746 5.153 9.172 7.729 20.309 7.729 33.411 0 1.294-.052 2.761-.156 4.4l-.042.623-.17 2.353c-.075 1.01-.151 1.973-.227 2.888h-78.044zm21.365-42.147c-4.492 0-8.456 1.092-11.891 3.276-3.303 2.184-5.879 5.314-7.729 9.39a26.04 26.04 0 00-1.117 2.79 30.164 30.164 0 00-1.121 4.499l-.058.354h43.96l-.015-.106c-.401-2.638-1.122-5.055-2.163-7.252l-.246-.503c-1.776-3.774-4.282-6.742-7.519-8.906l-.409-.266c-3.303-2.184-7.2-3.276-11.692-3.276zm111.695-62.018l-.001 57.432h53.51V87.172h39.24v152.863h-39.24v-59.617H555.9l.001 59.617h-39.24V87.172h39.24zM715.766 242c-8.72 0-16.581-1.893-23.583-5.678-6.87-3.785-12.287-9.681-16.251-17.688-3.832-8.153-5.747-18.417-5.747-30.791v-66.168h37.654v59.398c0 9.172 1.519 15.723 4.558 19.654 3.171 3.931 7.597 5.896 13.278 5.896 3.7 0 7.069-.946 10.108-2.839 3.038-1.892 5.483-4.877 7.332-8.953 1.85-4.222 2.775-9.609 2.775-16.16v-56.996h37.654v118.36h-35.871l.004-12.38c-2.642 3.197-5.682 5.868-9.12 8.012-7.002 4.222-14.599 6.333-22.791 6.333zM841.489 78l-.001 54.041a34.1 34.1 0 016.541-5.78c6.474-4.367 14.269-6.551 23.385-6.551 9.777 0 18.629 2.475 26.556 7.424 7.873 4.835 14.106 11.684 18.701 20.546l.325.637c4.756 9.026 7.134 19.799 7.134 32.319 0 12.666-2.378 23.585-7.134 32.757-4.624 9.026-10.966 16.087-19.026 21.182-7.927 4.95-16.779 7.425-26.556 7.425-9.645 0-17.704-2.184-24.178-6.551-2.825-1.946-5.336-4.354-7.531-7.224v11.81h-35.87V78h37.654zm21.998 74.684c-4.228 0-8.059 1.092-11.495 3.276-3.303 2.184-6.011 5.387-8.125 9.609-1.982 4.076-2.973 9.099-2.973 15.067 0 5.969.991 11.138 2.973 15.505 2.114 4.222 4.822 7.425 8.125 9.609 3.436 2.183 7.267 3.275 11.495 3.275 4.228 0 7.993-1.092 11.296-3.275 3.435-2.184 6.144-5.387 8.126-9.609 2.114-4.367 3.171-9.536 3.171-15.505 0-5.968-1.057-10.991-3.171-15.067-1.906-4.06-4.484-7.177-7.733-9.352l-.393-.257c-3.303-2.184-7.068-3.276-11.296-3.276z"
+          />
+        </svg>
+      </div>
+    </div>
+    <div id="root" style="height: 100%"></div>
+    <script>
+      window.__SERVER_CONFIG__ = undefined;
+    </script>
+    <script type="module" src="/src/spa/entry.popup.tsx"></script>
+  </body>
+</html>
@@ -86,5 +86,6 @@
  "window.minimize": "تصغير",
  "window.title": "نافذة",
  "window.toggleFullscreen": "تبديل وضع ملء الشاشة",
-  "window.zoom": "تكبير"
+  "window.zoom": "تكبير",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Минимизирай",
  "window.title": "Прозорец",
  "window.toggleFullscreen": "Превключи на цял екран",
-  "window.zoom": "Мащаб"
+  "window.zoom": "Мащаб",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Minimieren",
  "window.title": "Fenster",
  "window.toggleFullscreen": "Vollbild umschalten",
-  "window.zoom": "Zoom"
+  "window.zoom": "Zoom",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -71,6 +71,8 @@
  "macOS.services": "Services",
  "macOS.unhide": "Show All",
  "tray.open": "Open {{appName}}",
+  "tray.openMiniToolbar": "Quick Composer",
+  "tray.quickChat": "Quick Chat",
  "tray.quit": "Quit",
  "tray.show": "Show {{appName}}",
  "view.forceReload": "Force Reload",
@@ -86,5 +86,6 @@
  "window.minimize": "Minimizar",
  "window.title": "Ventana",
  "window.toggleFullscreen": "Alternar pantalla completa",
-  "window.zoom": "Zoom"
+  "window.zoom": "Zoom",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "کوچک کردن",
  "window.title": "پنجره",
  "window.toggleFullscreen": "تغییر به حالت تمام صفحه",
-  "window.zoom": "زوم"
+  "window.zoom": "زوم",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Réduire",
  "window.title": "Fenêtre",
  "window.toggleFullscreen": "Basculer en plein écran",
-  "window.zoom": "Zoom"
+  "window.zoom": "Zoom",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Minimizza",
  "window.title": "Finestra",
  "window.toggleFullscreen": "Attiva/disattiva schermo intero",
-  "window.zoom": "Zoom"
+  "window.zoom": "Zoom",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "最小化",
  "window.title": "ウィンドウ",
  "window.toggleFullscreen": "フルスクリーン切替",
-  "window.zoom": "ズーム"
+  "window.zoom": "ズーム",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "최소화",
  "window.title": "창",
  "window.toggleFullscreen": "전체 화면 전환",
-  "window.zoom": "줌"
+  "window.zoom": "줌",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Minimaliseren",
  "window.title": "Venster",
  "window.toggleFullscreen": "Schakel volledig scherm in/uit",
-  "window.zoom": "Inzoomen"
+  "window.zoom": "Inzoomen",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Zminimalizuj",
  "window.title": "Okno",
  "window.toggleFullscreen": "Przełącz tryb pełnoekranowy",
-  "window.zoom": "Powiększenie"
+  "window.zoom": "Powiększenie",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Minimizar",
  "window.title": "Janela",
  "window.toggleFullscreen": "Alternar Tela Cheia",
-  "window.zoom": "Zoom"
+  "window.zoom": "Zoom",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Свернуть",
  "window.title": "Окно",
  "window.toggleFullscreen": "Переключить полноэкранный режим",
-  "window.zoom": "Масштаб"
+  "window.zoom": "Масштаб",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Küçült",
  "window.title": "Pencere",
  "window.toggleFullscreen": "Tam Ekrana Geç",
-  "window.zoom": "Yakınlaştır"
+  "window.zoom": "Yakınlaştır",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -86,5 +86,6 @@
  "window.minimize": "Thu nhỏ",
  "window.title": "Cửa sổ",
  "window.toggleFullscreen": "Chuyển đổi toàn màn hình",
-  "window.zoom": "Thu phóng"
+  "window.zoom": "Thu phóng",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -48,6 +48,7 @@
  "file.newAgent": "新建助手",
  "file.newAgentGroup": "新建助手组",
  "file.newPage": "新建页面",
+  "file.newTab": "新建标签页",
  "file.newTopic": "新建话题",
  "file.preferences": "设置…",
  "file.quit": "退出",
@@ -71,6 +72,8 @@
  "macOS.services": "服务",
  "macOS.unhide": "全部显示",
  "tray.open": "打开 {{appName}}",
+  "tray.openMiniToolbar": "Quick Composer",
+  "tray.quickChat": "快捷聊天",
  "tray.quit": "退出",
  "tray.show": "显示 {{appName}}",
  "view.forceReload": "强制重新加载",
@@ -86,5 +86,6 @@
  "window.minimize": "最小化",
  "window.title": "視窗",
  "window.toggleFullscreen": "切換全螢幕",
-  "window.zoom": "縮放"
+  "window.zoom": "縮放",
+  "tray.openMiniToolbar": "Quick Composer"
 }
@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * Generate the macOS tray template icon set (black + alpha).
+ *
+ * Template images must contain only black pixels and an alpha channel;
+ * macOS then recolors them automatically based on the menu bar theme.
+ *
+ * Renders two files in apps/desktop/resources:
+ *   - trayTemplate.png       (@1x, 18x18)
+ *   - trayTemplate@2x.png    (@2x, 36x36)
+ *
+ * Run: bun run apps/desktop/scripts/generate-tray-template.mjs
+ */
+import { mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import sharp from 'sharp';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const outDir = path.resolve(__dirname, '..', 'resources');
+
+// Silhouette derived from the LobeHub logo. Eyes and mouth are cut as
+// transparent holes via fill-rule=evenodd so they remain visible when
+// macOS tints the entire shape in a single color.
+const svg = `<?xml version="1.0" encoding="UTF-8"?>
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 320 320">
+  <path fill="#000" d="M172.997 19.016c-14.027 0-19.5-11.5-41-11-23.394 0-34 13-45.5 23-1.958 1.702-11.5 7-16 9-19.683 8.748-34.5 21.5-34.5 40.5 0 20.711 17.461 37.5 39 37.5 3.536 0 6.963-.453 10.22-1.301 8.7 10.539 22.179 16.658 37.28 17.301 23.5 1 31-15.25 44.5-8.5 9.259 4.629 13.83 8.5 28.5 8.5 17.108 0 25.057-5.233 30-11 9-10.5 22.879-4 31.5-4 18.778 0 34-14.551 34-32.5 0-17.95-15.222-32.5-34-32.5-5.15 0-14.856 1.27-17-7-3.5-13.5-20.148-29-44-29-9.318 0-17.691 1-23 1z"/>
+  <path fill="#000" fill-rule="evenodd" d="M294 172.519c0 75.655-59.442 128.5-134 128.5-74.558 0-134-53.845-134-129.5 0-22.5 5-32.141 31.5-35.671 47.5-6.329 72.542-3.829 102.5-3.829 29.959 0 72.556-1.27 102.5 3.829 24.5 4.171 30 8.671 31.5 36.671zM101 221.012c15.464 0 28-12.536 28-28s-12.536-28-28-28-28 12.536-28 28 12.536 28 28 28zM219 221.012c15.464 0 28-12.536 28-28s-12.536-28-28-28-28 12.536-28 28 12.536 28 28 28zM159.75 242.51c-28.25 0-35.75 3.5-35.75 3.5s3.5 27 35.75 27 35.75-27 35.75-27-7.5-3.5-35.75-3.5z"/>
+</svg>
+`;
+
+async function render(size, outFile) {
+  const buf = Buffer.from(svg);
+  await sharp(buf, { density: Math.max(72, size * 12) })
+    .resize(size, size, { fit: 'contain', background: { r: 0, g: 0, b: 0, alpha: 0 } })
+    .png()
+    .toFile(outFile);
+  console.log(`wrote ${path.relative(process.cwd(), outFile)} (${size}x${size})`);
+}
+
+async function main() {
+  await mkdir(outDir, { recursive: true });
+  await render(18, path.join(outDir, 'trayTemplate.png'));
+  await render(36, path.join(outDir, 'trayTemplate@2x.png'));
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});
@@ -66,6 +66,20 @@ export const windowTemplates = {
    titleBarStyle: 'hidden',
    width: 900,
  },
+  // Dedicated single-topic popup window. Loads the popup.html SPA entry
+  // (no sidebar / portal), one window per (scope, id) pair.
+  topicPopup: {
+    allowMultipleInstances: true,
+    autoHideMenuBar: true,
+    baseIdentifier: 'topicPopup',
+    basePath: '/popup',
+    height: 720,
+    keepAlive: false,
+    minWidth: 480,
+    parentIdentifier: 'app',
+    titleBarStyle: 'hidden',
+    width: 900,
+  },
 } satisfies Record<string, WindowTemplate>;

 export type AppBrowsersIdentifiers = keyof typeof appBrowsers;
@@ -1,29 +1,29 @@
-import { join } from 'node:path';
+import path from 'node:path';

 import { app } from 'electron';

-export const mainDir = join(__dirname);
+export const mainDir = path.join(__dirname);

-export const preloadDir = join(mainDir, '../preload');
+export const preloadDir = path.join(mainDir, '../preload');

-export const resourcesDir = join(mainDir, '../../resources');
+export const resourcesDir = path.join(mainDir, '../../resources');

-export const buildDir = join(mainDir, '../../build');
+export const buildDir = path.join(mainDir, '../../build');

 export const binDir = app.isPackaged
-  ? join(process.resourcesPath, 'bin')
-  : join(resourcesDir, 'bin');
+  ? path.join(process.resourcesPath, 'bin')
+  : path.join(resourcesDir, 'bin');

 const appPath = app.getAppPath();

-export const rendererDir = join(appPath, 'dist', 'renderer');
+export const rendererDir = path.join(appPath, 'dist', 'renderer');

 export const userDataDir = app.getPath('userData');

-export const appStorageDir = join(userDataDir, 'lobehub-storage');
+export const appStorageDir = path.join(userDataDir, 'lobehub-storage');

 // Legacy local database directory used in older desktop versions
-export const legacyLocalDbDir = join(appStorageDir, 'lobehub-local-db');
+export const legacyLocalDbDir = path.join(appStorageDir, 'lobehub-local-db');

 // ------  Application storage directory ---- //

@@ -1,16 +1,16 @@
 import os from 'node:os';

-import { dev, linux, macOS, windows } from 'electron-is';
+import * as electronIs from 'electron-is';

 import { getDesktopEnv } from '@/env';

-export const isDev = dev();
+export const isDev = electronIs.dev();

 export const OFFICIAL_CLOUD_SERVER = getDesktopEnv().OFFICIAL_CLOUD_SERVER;

-export const isMac = macOS();
-export const isWindows = windows();
-export const isLinux = linux();
+export const isMac = electronIs.macOS();
+export const isWindows = electronIs.windows();
+export const isLinux = electronIs.linux();

 function getIsMacTahoe(): boolean {
  if (!isMac) return false;
@@ -1,11 +1,11 @@
 /**
 * Application settings storage related constants
 */
+import { DEFAULT_ELECTRON_DESKTOP_SHORTCUTS } from '@lobechat/const/desktopGlobalShortcuts';
 import type { NetworkProxySettings } from '@lobechat/electron-client-ipc';

 import { appStorageDir } from '@/const/dir';
 import { UPDATE_CHANNEL } from '@/modules/updater/configs';
-import { DEFAULT_SHORTCUTS_CONFIG } from '@/shortcuts';
 import type { ElectronMainStore } from '@/types/store';

 /**
@@ -35,7 +35,7 @@ export const STORE_DEFAULTS: ElectronMainStore = {
  gatewayUrl: 'https://device-gateway.lobehub.com',
  locale: 'auto',
  networkProxy: defaultProxySettings,
-  shortcuts: DEFAULT_SHORTCUTS_CONFIG,
+  shortcuts: DEFAULT_ELECTRON_DESKTOP_SHORTCUTS,
  storagePath: appStorageDir,
  themeMode: 'system',
  updateChannel: UPDATE_CHANNEL,
@@ -12,6 +12,7 @@ import { BrowserWindow, shell } from 'electron';
 import GatewayConnectionService from '@/services/gatewayConnectionSrv';
 import { appendVercelCookie } from '@/utils/http-headers';
 import { createLogger } from '@/utils/logger';
+import { netFetch } from '@/utils/net-fetch';

 import { ControllerModule, IpcMethod } from './index';
 import RemoteServerConfigCtr from './RemoteServerConfigCtr';
@@ -360,10 +361,10 @@ export default class AuthCtr extends ControllerModule {

      logger.debug(`Polling for credentials: ${url.toString()}`);

-      // Send HTTP request directly
+      // Use Electron net.fetch to respect system CA store (self-signed/private CA certs)
      const headers: Record<string, string> = { 'Content-Type': 'application/json' };
      appendVercelCookie(headers);
-      const response = await fetch(url.toString(), { headers, method: 'GET' });
+      const response = await netFetch(url.toString(), { headers, method: 'GET' });

      // Check response status
      if (response.status === 404) {
@@ -481,7 +482,7 @@ export default class AuthCtr extends ControllerModule {
        'Content-Type': 'application/x-www-form-urlencoded',
      };
      appendVercelCookie(tokenHeaders);
-      const response = await fetch(tokenUrl.toString(), {
+      const response = await netFetch(tokenUrl.toString(), {
        body,
        headers: tokenHeaders,
        method: 'POST',
@@ -1,4 +1,5 @@
 import type {
+  FocusTopicPopupParams,
  InterceptRouteParams,
  OpenSettingsWindowOptions,
  WindowMinimumSizeParams,
@@ -15,11 +16,21 @@ export default class BrowserWindowsCtr extends ControllerModule {
  static override readonly groupName = 'windows';

  @shortcut('showApp')
-  async toggleMainWindow() {
+  toggleMainWindow() {
    const mainWindow = this.app.browserManager.getMainWindow();
    mainWindow.toggleVisible();
  }

+  @shortcut('quickComposer')
+  async openQuickComposer() {
+    await this.app.screenCaptureManager.startSession();
+  }
+
+  @shortcut('quickChat')
+  openQuickChat() {
+    this.app.browserManager.openQuickChatPopup();
+  }
+
  @IpcMethod()
  async openSettingsWindow(options?: string | OpenSettingsWindowOptions) {
    const normalizedOptions: OpenSettingsWindowOptions =
@@ -80,6 +91,30 @@ export default class BrowserWindowsCtr extends ControllerModule {
    });
  }

+  @IpcMethod()
+  setWindowAlwaysOnTop(flag: boolean) {
+    this.withSenderIdentifier((identifier) => {
+      this.app.browserManager.setWindowAlwaysOnTop(identifier, flag);
+    });
+  }
+
+  @IpcMethod()
+  isWindowAlwaysOnTop() {
+    return this.withSenderIdentifier((identifier) => {
+      return this.app.browserManager.isWindowAlwaysOnTop(identifier);
+    });
+  }
+
+  @IpcMethod()
+  listTopicPopups() {
+    return this.app.browserManager.listTopicPopups();
+  }
+
+  @IpcMethod()
+  focusTopicPopup(params: FocusTopicPopupParams) {
+    return this.app.browserManager.focusTopicPopup(params.identifier);
+  }
+
  @IpcMethod()
  setWindowSize(params: WindowSizeParams) {
    this.withSenderIdentifier((identifier) => {
@@ -0,0 +1,58 @@
+import { exec } from 'node:child_process';
+import path from 'node:path';
+import process from 'node:process';
+import { promisify } from 'node:util';
+
+import { getCliWrapperDir } from '@/modules/cliEmbedding';
+import { createLogger } from '@/utils/logger';
+
+import { ControllerModule, IpcMethod } from './index';
+import RemoteServerConfigCtr from './RemoteServerConfigCtr';
+
+const logger = createLogger('controllers:CliCtr');
+
+function normalizeServerUrl(url: string): string {
+  return url.replace(/\/$/, '');
+}
+
+export default class CliCtr extends ControllerModule {
+  static override readonly groupName = 'cli';
+
+  @IpcMethod()
+  async runCliCommand(args: string): Promise<{ exitCode: number; stderr: string; stdout: string }> {
+    const execAsync = promisify(exec);
+    const wrapperDir = getCliWrapperDir();
+    const cmd = process.platform === 'win32' ? 'lobehub.cmd' : 'lobehub';
+    const wrapperPath = path.join(wrapperDir, cmd);
+
+    const env = { ...process.env };
+
+    const remoteCtr = this.app.getController(RemoteServerConfigCtr);
+    if (remoteCtr) {
+      const [token, serverUrl] = await Promise.all([
+        remoteCtr.getAccessToken(),
+        remoteCtr.getRemoteServerUrl(),
+      ]);
+
+      if (token && serverUrl) {
+        env.LOBEHUB_JWT = token;
+        env.LOBEHUB_SERVER = normalizeServerUrl(serverUrl);
+        logger.debug('Injected LOBEHUB_JWT / LOBEHUB_SERVER for CLI command');
+      }
+    }
+
+    try {
+      const { stdout, stderr } = await execAsync(`"${wrapperPath}" ${args}`, {
+        env,
+        timeout: 15_000,
+      });
+      return { exitCode: 0, stderr, stdout };
+    } catch (error: any) {
+      return {
+        exitCode: error.code ?? 1,
+        stderr: error.stderr ?? '',
+        stdout: error.stdout ?? String(error.message),
+      };
+    }
+  }
+}
@@ -0,0 +1,420 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+import type {
+  GitAheadBehind,
+  GitBranchInfo,
+  GitBranchListItem,
+  GitCheckoutResult,
+  GitLinkedPullRequestResult,
+  GitPullResult,
+  GitPushResult,
+  GitWorkingTreeFiles,
+  GitWorkingTreeStatus,
+} from '@lobechat/electron-client-ipc';
+
+import { detectRepoType, resolveGitDir } from '@/utils/git';
+import { createLogger } from '@/utils/logger';
+
+import { ControllerModule, IpcMethod } from './index';
+
+const logger = createLogger('controllers:GitCtr');
+
+export default class GitController extends ControllerModule {
+  static override readonly groupName = 'git';
+
+  @IpcMethod()
+  async detectRepoType(dirPath: string): Promise<'git' | 'github' | undefined> {
+    return detectRepoType(dirPath);
+  }
+
+  /**
+   * Read current git branch from `.git/HEAD`. Returns short sha on detached HEAD.
+   * Handles both standard `.git` directories and `.git` worktree pointer files.
+   */
+  @IpcMethod()
+  async getGitBranch(dirPath: string): Promise<GitBranchInfo> {
+    try {
+      const gitDir = await resolveGitDir(dirPath);
+      if (!gitDir) return {};
+
+      const head = (await readFile(path.join(gitDir, 'HEAD'), 'utf8')).trim();
+      const refMatch = /^ref:\s*refs\/heads\/(.+)$/.exec(head);
+      if (refMatch) {
+        return { branch: refMatch[1] };
+      }
+      // Detached HEAD — HEAD file contains the full sha
+      if (/^[\da-f]{40}$/i.test(head)) {
+        return { branch: head.slice(0, 7), detached: true };
+      }
+      return {};
+    } catch {
+      return {};
+    }
+  }
+
+  /**
+   * Query `gh` CLI for an open pull request whose head branch matches `branch`.
+   * Returns status = 'gh-missing' when `gh` is not installed / not authenticated,
+   * so the UI can render a helpful tooltip instead of an error.
+   */
+  @IpcMethod()
+  async getLinkedPullRequest(payload: {
+    branch: string;
+    path: string;
+  }): Promise<GitLinkedPullRequestResult> {
+    const { path: dirPath, branch } = payload;
+    if (!branch) {
+      return { pullRequest: null, status: 'ok' };
+    }
+
+    const execFileAsync = promisify(execFile);
+    try {
+      const { stdout } = await execFileAsync(
+        'gh',
+        [
+          'pr',
+          'list',
+          '--head',
+          branch,
+          '--state',
+          'open',
+          '--limit',
+          '5',
+          '--json',
+          'number,url,title,state',
+        ],
+        { cwd: dirPath, timeout: 8000 },
+      );
+      const parsed = JSON.parse(stdout.trim() || '[]') as Array<{
+        number: number;
+        state: string;
+        title: string;
+        url: string;
+      }>;
+      if (parsed.length === 0) {
+        return { pullRequest: null, status: 'ok' };
+      }
+      const [primary, ...rest] = parsed;
+      return {
+        extraCount: rest.length,
+        pullRequest: primary,
+        status: 'ok',
+      };
+    } catch (error: any) {
+      const code = error?.code;
+      const stderr: string = error?.stderr ?? '';
+      // `gh` binary not on PATH
+      if (code === 'ENOENT') {
+        return { pullRequest: null, status: 'gh-missing' };
+      }
+      // gh reports auth issues via stderr; treat as a soft-fail
+      if (/auth\s+login|not\s+logged\s+in|authentication/i.test(stderr)) {
+        return { pullRequest: null, status: 'gh-missing' };
+      }
+      logger.debug('[getLinkedPullRequest] failed', { branch, code, stderr });
+      return { pullRequest: null, status: 'error' };
+    }
+  }
+
+  /**
+   * List local git branches ordered by most recent commit.
+   * `current` is true for the checked-out branch.
+   */
+  @IpcMethod()
+  async listGitBranches(dirPath: string): Promise<GitBranchListItem[]> {
+    const execFileAsync = promisify(execFile);
+    try {
+      const { stdout } = await execFileAsync(
+        'git',
+        [
+          'for-each-ref',
+          '--sort=-committerdate',
+          '--format=%(HEAD)%09%(refname:short)%09%(upstream:short)',
+          'refs/heads',
+        ],
+        { cwd: dirPath, timeout: 5000 },
+      );
+      return stdout
+        .replaceAll('\r', '')
+        .split('\n')
+        .filter((line) => line.length > 0)
+        .map((line) => {
+          // Line format: "<HEAD-marker>\t<branch>\t<upstream>" where HEAD-marker is '*' or ' '
+          const [head, name, upstream] = line.split('\t');
+          return {
+            current: head === '*',
+            name: name ?? '',
+            upstream: upstream || undefined,
+          };
+        })
+        .filter((b) => b.name);
+    } catch (error: any) {
+      logger.warn('[listGitBranches] git command failed', {
+        code: error?.code,
+        cwd: dirPath,
+        message: error?.message,
+        stderr: error?.stderr?.toString?.() ?? error?.stderr,
+      });
+      return [];
+    }
+  }
+
+  /**
+   * Bucket dirty files into added / modified / deleted via `git status --porcelain -z`.
+   * Each file is counted once: untracked (`??`) and staged-add (`A`) → added,
+   * any `D` in index or working tree → deleted, everything else (`M`/`R`/`C`/`T`/`U`) → modified.
+   *
+   * Uses `-z` so paths are NUL-terminated (no C-style quoting, no `\n` splitting bugs).
+   * Rename/copy entries (`R`/`C`) emit two NUL-separated tokens — dest path then source
+   * path — so the source token must be consumed to keep counts correct.
+   */
+  @IpcMethod()
+  async getGitWorkingTreeStatus(dirPath: string): Promise<GitWorkingTreeStatus> {
+    const execFileAsync = promisify(execFile);
+    try {
+      const { stdout } = await execFileAsync('git', ['status', '--porcelain', '-z'], {
+        cwd: dirPath,
+        timeout: 5000,
+      });
+      const tokens = stdout.split('\0');
+      let added = 0;
+      let modified = 0;
+      let deleted = 0;
+      let i = 0;
+      while (i < tokens.length) {
+        const entry = tokens[i];
+        i++;
+        if (entry.length < 2) continue;
+        const x = entry[0];
+        const y = entry[1];
+        // R/C entries carry an extra source-path token we must consume.
+        if (x === 'R' || x === 'C') i++;
+        if (x === '?' && y === '?') {
+          added++;
+        } else if (x === '!' && y === '!') {
+          // ignored — skip
+        } else if (x === 'D' || y === 'D') {
+          deleted++;
+        } else if (x === 'A' || y === 'A') {
+          added++;
+        } else {
+          modified++;
+        }
+      }
+      const total = added + modified + deleted;
+      return { added, clean: total === 0, deleted, modified, total };
+    } catch {
+      return { added: 0, clean: true, deleted: 0, modified: 0, total: 0 };
+    }
+  }
+
+  /**
+   * Return dirty file paths bucketed into added / modified / deleted.
+   * Same classification as getGitWorkingTreeStatus, but with per-file paths.
+   *
+   * Uses `git status --porcelain -z` so paths are NUL-terminated and never C-quoted,
+   * which avoids misparsing filenames that legitimately contain ` -> `, quote chars,
+   * or newlines. For R/C entries the two NUL-separated tokens are `DEST\0SRC`; we
+   * report DEST (the current working-tree path) and discard SRC.
+   */
+  @IpcMethod()
+  async getGitWorkingTreeFiles(dirPath: string): Promise<GitWorkingTreeFiles> {
+    const execFileAsync = promisify(execFile);
+    const added: string[] = [];
+    const modified: string[] = [];
+    const deleted: string[] = [];
+    try {
+      const { stdout } = await execFileAsync('git', ['status', '--porcelain', '-z'], {
+        cwd: dirPath,
+        timeout: 5000,
+      });
+      const tokens = stdout.split('\0');
+      let i = 0;
+      while (i < tokens.length) {
+        const entry = tokens[i];
+        i++;
+        if (entry.length < 3) continue;
+        const x = entry[0];
+        const y = entry[1];
+        const filePath = entry.slice(3);
+        // R/C entries carry an extra source-path token we must consume.
+        if (x === 'R' || x === 'C') i++;
+        if (!filePath) continue;
+        if (x === '?' && y === '?') {
+          added.push(filePath);
+        } else if (x === '!' && y === '!') {
+          // ignored — skip
+        } else if (x === 'D' || y === 'D') {
+          deleted.push(filePath);
+        } else if (x === 'A' || y === 'A') {
+          added.push(filePath);
+        } else {
+          modified.push(filePath);
+        }
+      }
+      return { added, deleted, modified };
+    } catch {
+      return { added: [], deleted: [], modified: [] };
+    }
+  }
+
+  /**
+   * Count commits HEAD is ahead/behind its upstream tracking ref.
+   * Returns `hasUpstream: false` when the branch has no upstream configured
+   * (e.g. local-only branches, or after the remote branch is deleted).
+   *
+   * Does a best-effort `git fetch` first so the result reflects what's
+   * actually on the remote — the renderer calls this via SWR with
+   * `revalidateOnFocus`, so the fetch piggybacks on window re-focus. Fetch
+   * failures (offline, no credentials, no `origin` remote) are swallowed so
+   * we still return whatever can be computed against the cached refs.
+   */
+  @IpcMethod()
+  async getGitAheadBehind(dirPath: string): Promise<GitAheadBehind> {
+    const execFileAsync = promisify(execFile);
+    try {
+      await execFileAsync('git', ['fetch', '--no-tags', '--quiet', 'origin'], {
+        cwd: dirPath,
+        timeout: 10_000,
+      });
+    } catch {
+      // swallow — fall through to compute against cached refs
+    }
+    try {
+      const { stdout: upstreamOut } = await execFileAsync(
+        'git',
+        ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'],
+        { cwd: dirPath, timeout: 5000 },
+      );
+      const upstream = upstreamOut.trim();
+      if (!upstream) return { ahead: 0, behind: 0, hasUpstream: false };
+
+      const { stdout } = await execFileAsync(
+        'git',
+        ['rev-list', '--left-right', '--count', `${upstream}...HEAD`],
+        { cwd: dirPath, timeout: 5000 },
+      );
+      const [behindStr, aheadStr] = stdout.trim().split(/\s+/);
+      const behind = Number.parseInt(behindStr ?? '0', 10) || 0;
+      const ahead = Number.parseInt(aheadStr ?? '0', 10) || 0;
+
+      // `git push -u origin HEAD` always targets origin/<current-branch-name>,
+      // which may differ from upstream (the branched-off-canary case).
+      let pushTarget: string | undefined;
+      let pushTargetExists = false;
+      try {
+        const { stdout: branchOut } = await execFileAsync(
+          'git',
+          ['symbolic-ref', '--short', 'HEAD'],
+          { cwd: dirPath, timeout: 5000 },
+        );
+        const branch = branchOut.trim();
+        if (branch) {
+          pushTarget = `origin/${branch}`;
+          try {
+            await execFileAsync(
+              'git',
+              ['rev-parse', '--verify', '--quiet', `refs/remotes/${pushTarget}`],
+              { cwd: dirPath, timeout: 5000 },
+            );
+            pushTargetExists = true;
+          } catch {
+            pushTargetExists = false;
+          }
+        }
+      } catch {
+        // detached HEAD — leave pushTarget undefined
+      }
+
+      return { ahead, behind, hasUpstream: true, pushTarget, pushTargetExists, upstream };
+    } catch {
+      // No upstream configured, detached HEAD, or git error — all treated as "no upstream"
+      return { ahead: 0, behind: 0, hasUpstream: false };
+    }
+  }
+
+  /**
+   * Check out (or create + check out) a branch.
+   * Relies on git itself to reject unsafe checkouts (dirty tree, non-fast-forward, etc.)
+   * and surfaces git's stderr so the UI can display a meaningful error.
+   */
+  @IpcMethod()
+  async checkoutGitBranch(payload: {
+    branch: string;
+    create?: boolean;
+    path: string;
+  }): Promise<GitCheckoutResult> {
+    const { path: dirPath, branch, create } = payload;
+    if (!branch?.trim()) {
+      return { error: 'Branch name is required', success: false };
+    }
+    // Reject obviously invalid refs early to avoid a confusing git error
+    if (/[\s~^:?*[\\]/.test(branch) || branch.startsWith('-') || branch.includes('..')) {
+      return { error: `Invalid branch name: ${branch}`, success: false };
+    }
+
+    const execFileAsync = promisify(execFile);
+    const args = create ? ['checkout', '-b', branch] : ['checkout', branch];
+    try {
+      await execFileAsync('git', args, { cwd: dirPath, timeout: 10_000 });
+      return { success: true };
+    } catch (error: any) {
+      const stderr: string = (error?.stderr ?? error?.message ?? '').toString().trim();
+      logger.debug('[checkoutGitBranch] failed', { args, stderr });
+      return { error: stderr || 'git checkout failed', success: false };
+    }
+  }
+
+  /**
+   * Pull the current branch's upstream via fast-forward only.
+   *
+   * `--ff-only` avoids creating accidental merge commits when the local branch
+   * has diverged — in that case the user should resolve merge/rebase in their
+   * own terminal. For the common "just behind" case this is a safe one-click.
+   */
+  @IpcMethod()
+  async pullGitBranch(payload: { path: string }): Promise<GitPullResult> {
+    const { path: dirPath } = payload;
+    const execFileAsync = promisify(execFile);
+    try {
+      const { stdout } = await execFileAsync('git', ['pull', '--ff-only'], {
+        cwd: dirPath,
+        timeout: 60_000,
+      });
+      const noop = /Already up to date/i.test(stdout);
+      return { noop, success: true };
+    } catch (error: any) {
+      const stderr: string = (error?.stderr ?? error?.message ?? '').toString().trim();
+      logger.debug('[pullGitBranch] failed', { stderr });
+      return { error: stderr || 'git pull failed', success: false };
+    }
+  }
+
+  /**
+   * Push the current branch to its same-named remote on `origin`.
+   *
+   * Uses `git push -u origin HEAD` instead of plain `git push` so the action
+   * works even when local branch name differs from the configured upstream
+   */
+  @IpcMethod()
+  async pushGitBranch(payload: { path: string }): Promise<GitPushResult> {
+    const { path: dirPath } = payload;
+    const execFileAsync = promisify(execFile);
+    try {
+      const { stderr } = await execFileAsync('git', ['push', '-u', 'origin', 'HEAD'], {
+        cwd: dirPath,
+        timeout: 60_000,
+      });
+      // git push writes progress/status to stderr even on success
+      const noop = /Everything up-to-date/i.test(stderr);
+      return { noop, success: true };
+    } catch (error: any) {
+      const stderr: string = (error?.stderr ?? error?.message ?? '').toString().trim();
+      logger.debug('[pushGitBranch] failed', { stderr });
+      return { error: stderr || 'git push failed', success: false };
+    }
+  }
+}
@@ -0,0 +1,515 @@
+import type { ChildProcess } from 'node:child_process';
+import { spawn } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { Readable, Writable } from 'node:stream';
+
+import { app as electronApp, BrowserWindow } from 'electron';
+
+import { buildProxyEnv } from '@/modules/networkProxy/envBuilder';
+import { createLogger } from '@/utils/logger';
+
+import { ControllerModule, IpcMethod } from './index';
+
+const logger = createLogger('controllers:HeterogeneousAgentCtr');
+
+/** Directory under appStoragePath for caching downloaded files */
+const FILE_CACHE_DIR = 'heteroAgent/files';
+
+// ─── CLI presets per agent type ───
+// Mirrors @lobechat/heterogeneous-agents/registry but runs in main process
+// (can't import from the workspace package in Electron main directly)
+
+interface CLIPreset {
+  baseArgs: string[];
+  promptMode: 'positional' | 'stdin';
+  resumeArgs?: (sessionId: string) => string[];
+}
+
+const CLI_PRESETS: Record<string, CLIPreset> = {
+  'claude-code': {
+    baseArgs: [
+      '-p',
+      '--input-format',
+      'stream-json',
+      '--output-format',
+      'stream-json',
+      '--verbose',
+      '--include-partial-messages',
+      '--permission-mode',
+      'bypassPermissions',
+    ],
+    promptMode: 'stdin',
+    resumeArgs: (sid) => ['--resume', sid],
+  },
+  // Future presets:
+  // 'codex': { baseArgs: [...], promptMode: 'positional' },
+  // 'kimi-cli': { baseArgs: [...], promptMode: 'positional' },
+};
+
+// ─── IPC types ───
+
+interface StartSessionParams {
+  /** Agent type key (e.g., 'claude-code'). Defaults to 'claude-code'. */
+  agentType?: string;
+  /** Additional CLI arguments */
+  args?: string[];
+  /** Command to execute */
+  command: string;
+  /** Working directory */
+  cwd?: string;
+  /** Environment variables */
+  env?: Record<string, string>;
+  /** Session ID to resume (for multi-turn) */
+  resumeSessionId?: string;
+}
+
+interface StartSessionResult {
+  sessionId: string;
+}
+
+interface ImageAttachment {
+  id: string;
+  url: string;
+}
+
+interface SendPromptParams {
+  /** Image attachments to include in the prompt (downloaded from url, cached by id) */
+  imageList?: ImageAttachment[];
+  prompt: string;
+  sessionId: string;
+}
+
+interface CancelSessionParams {
+  sessionId: string;
+}
+
+interface StopSessionParams {
+  sessionId: string;
+}
+
+interface GetSessionInfoParams {
+  sessionId: string;
+}
+
+interface SessionInfo {
+  agentSessionId?: string;
+}
+
+// ─── Internal session tracking ───
+
+interface AgentSession {
+  agentSessionId?: string;
+  agentType: string;
+  args: string[];
+  /**
+   * True when *we* initiated the kill (cancelSession / stopSession / before-quit).
+   * The `exit` handler uses this to route signal-induced non-zero exits through
+   * the `complete` broadcast instead of surfacing them as runtime errors —
+   * SIGINT(130) / SIGTERM(143) / SIGKILL(137) from our own kill paths are
+   * intentional, not agent failures.
+   */
+  cancelledByUs?: boolean;
+  command: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  process?: ChildProcess;
+  sessionId: string;
+}
+
+/**
+ * External Agent Controller — manages external agent CLI processes via Electron IPC.
+ *
+ * Agent-agnostic: uses CLI presets from a registry to support Claude Code,
+ * Codex, Kimi CLI, etc. Only handles process lifecycle and raw stdout line
+ * broadcasting. All event parsing and DB persistence happens on the Renderer side.
+ *
+ * Lifecycle: startSession → sendPrompt → (heteroAgentRawLine broadcasts) → stopSession
+ */
+export default class HeterogeneousAgentCtr extends ControllerModule {
+  static override readonly groupName = 'heterogeneousAgent';
+
+  private sessions = new Map<string, AgentSession>();
+
+  // ─── Broadcast ───
+
+  private broadcast<T>(channel: string, data: T) {
+    for (const win of BrowserWindow.getAllWindows()) {
+      if (!win.isDestroyed()) {
+        win.webContents.send(channel, data);
+      }
+    }
+  }
+
+  // ─── File cache ───
+
+  private get fileCacheDir(): string {
+    return path.join(this.app.appStoragePath, FILE_CACHE_DIR);
+  }
+
+  /**
+   * Derive a filesystem-safe cache key for attachments.
+   *
+   * Never use the raw image id as a path segment — upstream callers can persist
+   * arbitrary ids and path.join would treat traversal sequences as real
+   * directories. A stable hash preserves cache hits without trusting the id as a
+   * filename.
+   */
+  private getImageCacheKey(imageId: string): string {
+    return createHash('sha256').update(imageId).digest('hex');
+  }
+
+  /**
+   * Download an image by URL, with local disk cache keyed by id.
+   */
+  private async resolveImage(
+    image: ImageAttachment,
+  ): Promise<{ buffer: Buffer; mimeType: string }> {
+    const cacheDir = this.fileCacheDir;
+    const cacheKey = this.getImageCacheKey(image.id);
+    const metaPath = path.join(cacheDir, `${cacheKey}.meta`);
+    const dataPath = path.join(cacheDir, cacheKey);
+
+    // Check cache first
+    try {
+      const metaRaw = await readFile(metaPath, 'utf8');
+      const meta = JSON.parse(metaRaw);
+      const buffer = await readFile(dataPath);
+      logger.debug('Image cache hit:', image.id);
+      return { buffer, mimeType: meta.mimeType || 'image/png' };
+    } catch {
+      // Cache miss — download
+    }
+
+    logger.info('Downloading image:', image.id);
+
+    const res = await fetch(image.url);
+    if (!res.ok)
+      throw new Error(`Failed to download image ${image.id}: ${res.status} ${res.statusText}`);
+
+    const arrayBuffer = await res.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+    const mimeType = res.headers.get('content-type') || 'image/png';
+
+    // Write to cache
+    await mkdir(cacheDir, { recursive: true });
+    await writeFile(dataPath, buffer);
+    await writeFile(metaPath, JSON.stringify({ id: image.id, mimeType }));
+    logger.debug('Image cached:', image.id, `${buffer.length} bytes`);
+
+    return { buffer, mimeType };
+  }
+
+  /**
+   * Build a stream-json user message with text + optional image content blocks.
+   */
+  private async buildStreamJsonInput(
+    prompt: string,
+    imageList: ImageAttachment[] = [],
+  ): Promise<string> {
+    const content: any[] = [{ text: prompt, type: 'text' }];
+
+    for (const image of imageList) {
+      try {
+        const { buffer, mimeType } = await this.resolveImage(image);
+        content.push({
+          source: {
+            data: buffer.toString('base64'),
+            media_type: mimeType,
+            type: 'base64',
+          },
+          type: 'image',
+        });
+      } catch (err) {
+        logger.error(`Failed to resolve image ${image.id}:`, err);
+      }
+    }
+
+    return JSON.stringify({
+      message: { content, role: 'user' },
+      type: 'user',
+    });
+  }
+
+  // ─── IPC methods ───
+
+  /**
+   * Create a session (stores config, process spawned on sendPrompt).
+   */
+  @IpcMethod()
+  async startSession(params: StartSessionParams): Promise<StartSessionResult> {
+    const sessionId = randomUUID();
+    const agentType = params.agentType || 'claude-code';
+
+    this.sessions.set(sessionId, {
+      // If resuming, pre-set the agent session ID so sendPrompt adds --resume
+      agentSessionId: params.resumeSessionId,
+      agentType,
+      args: params.args || [],
+      command: params.command,
+      cwd: params.cwd,
+      env: params.env,
+      sessionId,
+    });
+
+    logger.info('Session created:', { agentType, sessionId });
+    return { sessionId };
+  }
+
+  /**
+   * Send a prompt to an agent session.
+   *
+   * Spawns the CLI process with preset flags. Broadcasts each stdout line
+   * as an `heteroAgentRawLine` event — Renderer side parses and adapts.
+   */
+  @IpcMethod()
+  async sendPrompt(params: SendPromptParams): Promise<void> {
+    const session = this.sessions.get(params.sessionId);
+    if (!session) throw new Error(`Session not found: ${params.sessionId}`);
+
+    const preset = CLI_PRESETS[session.agentType];
+    if (!preset) throw new Error(`Unknown agent type: ${session.agentType}`);
+
+    const useStdin = preset.promptMode === 'stdin';
+
+    // Build stream-json payload up-front so any image download errors
+    // surface before the process is spawned.
+    let stdinPayload: string | undefined;
+    if (useStdin) {
+      stdinPayload = await this.buildStreamJsonInput(params.prompt, params.imageList ?? []);
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      // Build CLI args: base preset + resume + user args
+      const cliArgs = [
+        ...preset.baseArgs,
+        ...(session.agentSessionId && preset.resumeArgs
+          ? preset.resumeArgs(session.agentSessionId)
+          : []),
+        ...session.args,
+      ];
+
+      if (!useStdin && preset.promptMode === 'positional') {
+        // Positional mode: append prompt as a CLI arg (legacy / non-CC presets).
+        cliArgs.push(params.prompt);
+      }
+
+      // 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');
+
+      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'],
+      });
+
+      // In stdin mode, write the stream-json message and close stdin.
+      if (useStdin && stdinPayload && proc.stdin) {
+        const stdin = proc.stdin as Writable;
+        stdin.write(stdinPayload + '\n', () => {
+          stdin.end();
+        });
+      }
+
+      session.process = proc;
+      let buffer = '';
+
+      // Stream stdout lines as raw events to Renderer
+      const stdout = proc.stdout as Readable;
+      stdout.on('data', (chunk: Buffer) => {
+        buffer += chunk.toString('utf8');
+        const lines = buffer.split('\n');
+        buffer = lines.pop() || '';
+
+        for (const line of lines) {
+          const trimmed = line.trim();
+          if (!trimmed) continue;
+
+          try {
+            const parsed = JSON.parse(trimmed);
+
+            // Extract agent session ID from init event (for multi-turn)
+            if (parsed.type === 'system' && parsed.subtype === 'init' && parsed.session_id) {
+              session.agentSessionId = parsed.session_id;
+            }
+
+            // Broadcast raw parsed JSON — Renderer handles all adaptation
+            this.broadcast('heteroAgentRawLine', {
+              line: parsed,
+              sessionId: session.sessionId,
+            });
+          } catch {
+            // Not valid JSON, skip
+          }
+        }
+      });
+
+      // Capture stderr
+      const stderrChunks: string[] = [];
+      const stderr = proc.stderr as Readable;
+      stderr.on('data', (chunk: Buffer) => {
+        stderrChunks.push(chunk.toString('utf8'));
+      });
+
+      proc.on('error', (err) => {
+        logger.error('Agent process error:', err);
+        this.broadcast('heteroAgentSessionError', {
+          error: err.message,
+          sessionId: session.sessionId,
+        });
+        reject(err);
+      });
+
+      proc.on('exit', (code, signal) => {
+        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 = stderrOutput || `Agent exited with code ${code}`;
+          this.broadcast('heteroAgentSessionError', {
+            error: errorMsg,
+            sessionId: session.sessionId,
+          });
+          reject(new Error(errorMsg));
+        }
+      });
+    });
+  }
+
+  /**
+   * Get session info (agent's internal session ID for multi-turn resume).
+   */
+  @IpcMethod()
+  async getSessionInfo(params: GetSessionInfoParams): Promise<SessionInfo> {
+    const session = this.sessions.get(params.sessionId);
+    return { agentSessionId: session?.agentSessionId };
+  }
+
+  /**
+   * Signal the whole process tree spawned by this session.
+   *
+   * On Unix the child was spawned with `detached: true`, so negating the pid
+   * signals the process group — reaching tool subprocesses (bash, grep, etc.)
+   * that would otherwise orphan after a parent-only kill. Falls back to the
+   * direct signal if the group kill raises (ESRCH when the leader is already
+   * gone). On Windows we shell out to `taskkill /T /F` which walks the tree.
+   */
+  private killProcessTree(proc: ChildProcess, signal: NodeJS.Signals): void {
+    if (!proc.pid || proc.killed) return;
+
+    if (process.platform === 'win32') {
+      try {
+        spawn('taskkill', ['/pid', String(proc.pid), '/T', '/F'], { stdio: 'ignore' });
+      } catch (err) {
+        logger.warn('taskkill failed:', err);
+      }
+      return;
+    }
+
+    try {
+      process.kill(-proc.pid, signal);
+    } catch {
+      try {
+        proc.kill(signal);
+      } catch {
+        // already exited
+      }
+    }
+  }
+
+  /**
+   * Cancel an ongoing session: SIGINT the CC tree, escalate to SIGKILL after
+   * 2s if the CLI hasn't exited (some tool calls swallow SIGINT). The
+   * `exit` handler on the spawned proc broadcasts completion and clears
+   * `session.process`, so the escalation is a no-op when the graceful path
+   * already landed.
+   */
+  @IpcMethod()
+  async cancelSession(params: CancelSessionParams): Promise<void> {
+    const session = this.sessions.get(params.sessionId);
+    if (!session?.process || session.process.killed) return;
+
+    session.cancelledByUs = true;
+    const proc = session.process;
+    this.killProcessTree(proc, 'SIGINT');
+
+    setTimeout(() => {
+      if (session.process === proc && !proc.killed) {
+        logger.warn('Session did not exit after SIGINT, escalating to SIGKILL:', params.sessionId);
+        this.killProcessTree(proc, 'SIGKILL');
+      }
+    }, 2000);
+  }
+
+  /**
+   * Stop and clean up a session.
+   */
+  @IpcMethod()
+  async stopSession(params: StopSessionParams): Promise<void> {
+    const session = this.sessions.get(params.sessionId);
+    if (!session) return;
+
+    if (session.process && !session.process.killed) {
+      session.cancelledByUs = true;
+      const proc = session.process;
+      this.killProcessTree(proc, 'SIGTERM');
+      setTimeout(() => {
+        if (session.process === proc && !proc.killed) {
+          this.killProcessTree(proc, 'SIGKILL');
+        }
+      }, 3000);
+    }
+
+    this.sessions.delete(params.sessionId);
+  }
+
+  @IpcMethod()
+  async respondPermission(): Promise<void> {
+    // No-op for CLI mode (permissions handled by --permission-mode flag)
+  }
+
+  /**
+   * Cleanup on app quit.
+   */
+  afterAppReady() {
+    electronApp.on('before-quit', () => {
+      for (const [, session] of this.sessions) {
+        if (session.process && !session.process.killed) {
+          session.cancelledByUs = true;
+          this.killProcessTree(session.process, 'SIGTERM');
+        }
+      }
+      this.sessions.clear();
+    });
+  }
+}
@@ -48,6 +48,7 @@ import { type FileResult, type SearchOptions } from '@/modules/fileSearch';
 import ContentSearchService from '@/services/contentSearchSrv';
 import FileSearchService from '@/services/fileSearchSrv';
 import { createLogger } from '@/utils/logger';
+import { netFetch } from '@/utils/net-fetch';

 import { ControllerModule, IpcMethod } from './index';

@@ -341,7 +342,7 @@ export default class LocalFileCtr extends ControllerModule {
    }

    try {
-      const response = await fetch(url);
+      const response = await netFetch(url);
      if (!response.ok) {
        throw new Error(
          `Failed to download skill package: ${response.status} ${response.statusText}`,
@@ -4,12 +4,11 @@ import { isEqual, merge } from 'es-toolkit/compat';
 import { defaultProxySettings } from '@/const/store';
 import { createLogger } from '@/utils/logger';

-import type {
-  ProxyTestResult} from '../modules/networkProxy';
+import type { ProxyTestResult } from '../modules/networkProxy';
 import {
  ProxyConfigValidator,
  ProxyConnectionTester,
-  ProxyDispatcherManager
+  ProxyDispatcherManager,
 } from '../modules/networkProxy';
 import { ControllerModule, IpcMethod } from './index';

@@ -104,7 +103,7 @@ export default class NetworkProxyCtr extends ControllerModule {
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : 'Unknown error';
      logger.error('Proxy connection test failed:', errorMessage);
-      throw new Error(`Connection failed: ${errorMessage}`);
+      throw new Error(`Connection failed: ${errorMessage}`, { cause: error });
    }
  }

@@ -3,7 +3,7 @@ import type {
  ShowDesktopNotificationParams,
 } from '@lobechat/electron-client-ipc';
 import { app, Notification } from 'electron';
-import { macOS, windows } from 'electron-is';
+import * as electronIs from 'electron-is';

 import { getIpcContext } from '@/utils/ipc';
 import { createLogger } from '@/utils/logger';
@@ -20,7 +20,7 @@ export default class NotificationCtr extends ControllerModule {
    if (!Notification.isSupported()) return 'denied';
    // Keep a stable status string for renderer-side UI mapping.
    // Screen3 expects macOS to return 'authorized' when granted.
-    if (!macOS()) return 'authorized';
+    if (!electronIs.macOS()) return 'authorized';

    // Electron 38 no longer exposes `systemPreferences.getNotificationSettings()` in types,
    // and some runtimes don't provide it at all. Use the renderer's Notification.permission
@@ -43,7 +43,7 @@ export default class NotificationCtr extends ControllerModule {

    // On macOS, ask permission via Web Notification API first when possible.
    // This helps keep `Notification.permission` in sync for subsequent status checks.
-    if (macOS()) {
+    if (electronIs.macOS()) {
      try {
        const mainWindow = this.app.browserManager.getMainWindow().browserWindow;
        await mainWindow.webContents.executeJavaScript('Notification.requestPermission()', true);
@@ -83,12 +83,12 @@ export default class NotificationCtr extends ControllerModule {
      }

      // On macOS, we may need to explicitly request notification permissions
-      if (macOS()) {
+      if (electronIs.macOS()) {
        logger.debug('macOS detected, notification permissions should be handled by system');
      }

      // Set app user model ID on Windows
-      if (windows()) {
+      if (electronIs.windows()) {
        app.setAppUserModelId('com.lobehub.chat');
        logger.debug('Set Windows App User Model ID for notifications');
      }
@@ -131,7 +131,12 @@ export default class NotificationCtr extends ControllerModule {
        silent: params.silent || false,
        timeoutType: 'default',
        title: params.title,
-        urgency: 'normal',
+        // On Linux/GNOME Shell, urgency 'normal' causes notifications to appear as banners.
+        // Clicking the dismiss (X) button on such banners can freeze the system for 30-45 seconds
+        // due to heavy gnome-shell processing. Using 'low' urgency routes notifications to the
+        // message tray instead, preventing the banner's X button from being shown.
+        // The urgency option is ignored on macOS and Windows.
+        urgency: electronIs.linux() ? 'low' : 'normal',
      });

      // Add more event listeners for debugging
@@ -173,6 +178,28 @@ export default class NotificationCtr extends ControllerModule {
    }
  }

+  /**
+   * Set the app-level badge count (dock red dot on macOS, Unity counter on Linux,
+   * overlay icon on Windows). Pass 0 to clear.
+   *
+   * On macOS we pair `app.setBadgeCount` with `app.dock.setBadge` — the former
+   * keeps Electron's internal count (cross-platform), the latter is the
+   * reliable Dock repaint trigger. Note: macOS Focus Mode / DND suppresses the
+   * badge visually until the user exits Focus.
+   */
+  @IpcMethod()
+  setBadgeCount(count: number): void {
+    try {
+      const next = Math.max(0, Math.floor(count));
+      app.setBadgeCount(next);
+      if (electronIs.macOS() && app.dock) {
+        app.dock.setBadge(next > 0 ? String(next) : '');
+      }
+    } catch (error) {
+      logger.error('Failed to set badge count:', error);
+    }
+  }
+
  /**
   * Check if the main window is hidden
   */
@@ -9,6 +9,7 @@ import { OFFICIAL_CLOUD_SERVER } from '@/const/env';
 import GatewayConnectionService from '@/services/gatewayConnectionSrv';
 import { appendVercelCookie } from '@/utils/http-headers';
 import { createLogger } from '@/utils/logger';
+import { netFetch } from '@/utils/net-fetch';

 import { ControllerModule, IpcMethod } from './index';

@@ -485,7 +486,7 @@ export default class RemoteServerConfigCtr extends ControllerModule {
        'Content-Type': 'application/x-www-form-urlencoded',
      };
      appendVercelCookie(headers);
-      const response = await fetch(tokenUrl.toString(), { body, headers, method: 'POST' });
+      const response = await netFetch(tokenUrl.toString(), { body, headers, method: 'POST' });

      if (!response.ok) {
        // Try to parse error response
@@ -0,0 +1,72 @@
+import type {
+  CapturePreviewResult,
+  CaptureRectParams,
+  OverlayCaptureUploadStatusPayload,
+  ScreenCaptureSubmitParams,
+} from '@lobechat/electron-client-ipc';
+
+import type { OverlaySnapshotPayload } from '@/modules/screenCapture/ScreenCaptureManager';
+import { createLogger } from '@/utils/logger';
+
+import { ControllerModule, IpcMethod } from './index';
+
+const logger = createLogger('controllers:ScreenCaptureCtr');
+
+export default class ScreenCaptureCtr extends ControllerModule {
+  static override readonly groupName = 'screenCapture';
+
+  @IpcMethod()
+  async traceOverlayEvent(payload: { data?: unknown; event: string }): Promise<void> {
+    console.info('[screenCapture:overlay]', payload.event, payload.data ?? '');
+  }
+
+  @IpcMethod()
+  async previewWindow(windowId: number): Promise<CapturePreviewResult> {
+    logger.debug(`previewWindow request: ${windowId}`);
+    return this.app.screenCaptureManager.handlePreviewWindow(windowId);
+  }
+
+  @IpcMethod()
+  async previewRect(params: CaptureRectParams): Promise<CapturePreviewResult> {
+    logger.debug(`previewRect request: ${JSON.stringify(params)}`);
+    return this.app.screenCaptureManager.handlePreviewRect(params);
+  }
+
+  @IpcMethod()
+  async submit(params: ScreenCaptureSubmitParams): Promise<void> {
+    logger.debug(`submit request: prompt-len=${params.prompt.length}`);
+    await this.app.screenCaptureManager.handleSubmit(params);
+  }
+
+  /**
+   * Status update reported by the main renderer after it finishes (or fails)
+   * uploading a capture's bytes. Forwarded to the overlay to drive the send
+   * button's enabled state.
+   */
+  @IpcMethod()
+  async reportUploadStatus(payload: OverlayCaptureUploadStatusPayload): Promise<void> {
+    logger.debug(
+      `reportUploadStatus captureId=${payload.captureId} status=${payload.status} fileId=${payload.fileId ?? '-'}`,
+    );
+    this.app.screenCaptureManager.reportUploadStatus(payload);
+  }
+
+  @IpcMethod()
+  async close(): Promise<void> {
+    logger.debug('close overlay request');
+    this.app.screenCaptureManager.close();
+  }
+
+  /**
+   * Renderer-driven snapshot of agents/models for the overlay selector. The
+   * main renderer pushes this whenever its data layer (TRPC stores) reports
+   * a change; main process only caches and forwards — it does not fetch.
+   */
+  @IpcMethod()
+  async publishOverlaySnapshot(payload: OverlaySnapshotPayload): Promise<void> {
+    logger.debug(
+      `publishOverlaySnapshot — agents=${payload.agents?.length ?? 0} models=${payload.models?.length ?? 0}`,
+    );
+    this.app.screenCaptureManager.publishOverlaySnapshot(payload);
+  }
+}
@@ -10,17 +10,38 @@ import { runCommand, ShellProcessManager } from '@lobechat/local-file-shell';

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

+import CliCtr from './CliCtr';
 import { ControllerModule, IpcMethod } from './index';

 const logger = createLogger('controllers:ShellCommandCtr');

 const processManager = new ShellProcessManager();

+/** Prefix for a simple `lh`/`lobe`/`lobehub` invocation (keyword + boundary, args via slice). */
+const SIMPLE_LH_PREFIX = /^\s*(?:lh|lobe|lobehub)(?=\s|$)/;
+
 export default class ShellCommandCtr extends ControllerModule {
  static override readonly groupName = 'shellCommand';

  @IpcMethod()
  async handleRunCommand(params: RunCommandParams): Promise<RunCommandResult> {
+    const prefixMatch = SIMPLE_LH_PREFIX.exec(params.command);
+    if (prefixMatch) {
+      const cliCtr = this.app.getController(CliCtr);
+      if (cliCtr) {
+        const args = params.command.slice(prefixMatch[0].length).trim();
+        logger.debug('Routing lh command to CliCtr.runCliCommand:', args);
+        const result = await cliCtr.runCliCommand(args);
+        return {
+          exit_code: result.exitCode,
+          output: result.stdout + result.stderr,
+          stderr: result.stderr,
+          stdout: result.stdout,
+          success: result.exitCode === 0,
+        };
+      }
+    }
+
    return runCommand(params, { logger, processManager });
  }

--- a/Show More
+++ b/Show More