🔖 chore(release): release version v2.1.56 [skip ci]

👷 build(database): add metadata and trigger to briefs table (#14354 )
* 👷 build(database): add metadata and trigger to briefs table * ✅ test(server): should not use adhoc Date.now() (#14280)
2026-06-14 11:40:07 +00:00 · 2026-05-01 07:49:26 +00:00 · 2026-05-01 15:47:02 +08:00 · 2026-04-29 14:09:35 +00:00 · 2026-04-29 22:06:01 +08:00 · 2026-04-27 15:41:37 +00:00
3762 changed files with 311334 additions and 48013 deletions
@@ -0,0 +1,209 @@
+---
+name: agent-runtime-hooks
+description: "Agent runtime lifecycle hooks for observing and intercepting agent execution. Use when adding hooks to agent operations, mocking tool calls, logging step events, handling human intervention, sub-agent calls, context compression, or building eval/tracing integrations. Triggers on 'hooks', 'beforeToolCall', 'afterToolCall', 'beforeStep', 'afterStep', 'onComplete', 'onError', 'tool mock', 'agent lifecycle', 'human intervention', 'callAgent', 'compact'."
+user-invocable: false
+---
+
+# Agent Runtime Hooks
+
+Lifecycle hooks for observing and intercepting agent execution. Hooks are registered per-operation via `execAgent({ hooks })` and dispatched by `HookDispatcher`.
+
+## Hook Types
+
+16 hook types across 5 categories:
+
+```
+execAgent({ hooks })
+  │
+  ├─ beforeStep ──────────── Before each step executes
+  │     │
+  │     ├─ [call_llm]        LLM inference
+  │     │
+  │     ├─ [call_tool]
+  │     │     ├─ beforeToolCall ── Before tool executes (supports mocking)
+  │     │     ├─ (tool execution)
+  │     │     ├─ afterToolCall ─── After tool completes (observation only)
+  │     │     └─ onToolCallError ─ Tool threw an exception
+  │     │
+  │     ├─ [request_human_approve]
+  │     │     ├─ beforeHumanIntervention ── Before agent pauses
+  │     │     ├─ afterHumanIntervention ─── After approve/reject + resume
+  │     │     └─ onStopByHumanIntervention ── User rejected, agent halted
+  │     │
+  │     ├─ [compress_context]
+  │     │     ├─ beforeCompact ──── Before compression starts
+  │     │     ├─ afterCompact ───── After compression completes
+  │     │     └─ onCompactError ─── Compression failed
+  │     │
+  │     ├─ [callAgent] (via execSubAgentTask)
+  │     │     ├─ beforeCallAgent ── Before sub-agent starts
+  │     │     ├─ afterCallAgent ─── After sub-agent completes
+  │     │     └─ onCallAgentError ── Sub-agent failed
+  │     │
+  │     └─ afterStep ──────────── After step completes
+  │
+  ├─ (next step...)
+  │
+  ├─ onComplete ───────────── Operation reaches terminal state
+  └─ onError ──────────────── Error during execution
+```
+
+## Key Files
+
+| File                                                       | Role                                                   |
+| ---------------------------------------------------------- | ------------------------------------------------------ |
+| `packages/agent-runtime/src/types/hooks.ts`                | Type definitions (AgentHookType, all event interfaces) |
+| `src/server/services/agentRuntime/hooks/types.ts`          | Server-side types (AgentHook, re-exports)              |
+| `src/server/services/agentRuntime/hooks/HookDispatcher.ts` | Registration, dispatch, dispatchBeforeToolCall         |
+| `src/server/modules/AgentRuntime/RuntimeExecutors.ts`      | Tool/Compact/HumanIntervention hook dispatch           |
+| `src/server/services/agentRuntime/AgentRuntimeService.ts`  | Step hooks + HumanIntervention resume/reject           |
+| `src/server/services/aiAgent/index.ts`                     | CallAgent hook dispatch                                |
+
+## Registration Flow
+
+```ts
+const hooks: AgentHook[] = [
+  { id: 'my-hook', type: 'afterStep', handler: async (event) => { ... } },
+];
+await aiAgentService.execAgent({ agentId, prompt, hooks });
+// Internally: hookDispatcher.register(operationId, hooks)
+// Cleanup:    hookDispatcher.unregister(operationId)
+```
+
+## Hook Reference
+
+### Step Level
+
+**`beforeStep`** — Before each step. `event: AgentHookEvent`
+**`afterStep`** — After each step. `event: AgentHookEvent` (content, toolsCalling, totalCost, etc.)
+**`onComplete`** — Terminal state. `event: AgentHookEvent` (reason: done/error/interrupted/max_steps/cost_limit)
+**`onError`** — Error occurred. `event: AgentHookEvent` (errorMessage, errorDetail)
+
+### Tool Call Level
+
+**`beforeToolCall`** — Before tool executes. **Supports mocking** via `event.mock()`.
+
+```ts
+// event: ToolCallHookEvent
+{
+  (identifier, apiName, args, callIndex, stepIndex, operationId, mock);
+}
+// Mock example:
+event.mock({ content: '{"error":"rate limited"}' });
+```
+
+Dispatch method: `hookDispatcher.dispatchBeforeToolCall()` (returns mock result or null).
+
+**`afterToolCall`** — After tool completes. Observation only.
+
+```ts
+// event: AfterToolCallHookEvent
+{
+  (identifier, apiName, args, callIndex, content, success, mocked, executionTimeMs, stepIndex);
+}
+```
+
+**`onToolCallError`** — Tool threw an exception (catch block, not just `success=false`).
+
+```ts
+// event: ToolCallErrorHookEvent
+{
+  (identifier, apiName, args, callIndex, error, stepIndex);
+}
+```
+
+### Human Intervention
+
+**`beforeHumanIntervention`** — Before agent pauses for approval.
+
+```ts
+// event: BeforeHumanInterventionHookEvent
+{ operationId, stepIndex, pendingTools: [{ identifier, apiName }] }
+```
+
+**`afterHumanIntervention`** — After approve/reject, agent resumes.
+
+```ts
+// event: AfterHumanInterventionHookEvent
+{ operationId, action: 'approve' | 'reject' | 'rejectAndContinue', toolCallId?, rejectionReason? }
+```
+
+**`onStopByHumanIntervention`** — User rejected, agent halted.
+
+```ts
+// event: StopByHumanInterventionHookEvent
+{ operationId, toolCallId?, rejectionReason? }
+```
+
+### Context Compression
+
+**`beforeCompact`** — Before compression starts.
+
+```ts
+// event: BeforeCompactHookEvent
+{
+  (operationId, stepIndex, messageCount, tokenCount);
+}
+```
+
+**`afterCompact`** — After compression completes.
+
+```ts
+// event: AfterCompactHookEvent
+{
+  (operationId, stepIndex, groupId, messagesBefore, messagesAfter, summary);
+}
+```
+
+**`onCompactError`** — Compression failed.
+
+```ts
+// event: CompactErrorHookEvent
+{
+  (operationId, stepIndex, tokenCount, error);
+}
+```
+
+### Sub-Agent (CallAgent)
+
+**`beforeCallAgent`** — Before calling sub-agent. Dispatched on **parent** operation.
+
+```ts
+// event: BeforeCallAgentHookEvent
+{
+  (operationId, agentId, instruction);
+}
+```
+
+**`afterCallAgent`** — Sub-agent completed. Dispatched on **parent** operation.
+
+```ts
+// event: AfterCallAgentHookEvent
+{
+  (operationId, agentId, subOperationId, threadId, success);
+}
+```
+
+**`onCallAgentError`** — Sub-agent failed. Dispatched on **parent** operation.
+
+```ts
+// event: CallAgentErrorHookEvent
+{
+  (operationId, agentId, error);
+}
+```
+
+Note: CallAgent hooks require `parentOperationId` in `ExecSubAgentTaskParams`.
+
+## Design Notes
+
+- **Fire-and-forget**: All handlers return `Promise<void>`. Errors are non-fatal.
+- **Exception**: `beforeToolCall` supports mock via `event.mock()` — uses `dispatchBeforeToolCall()` which returns the mock result.
+- **Sequential**: Same-type hooks run in registration order.
+- **Local only**: `beforeToolCall` mock only works in local mode (in-memory hooks). Webhook mode does not support mocking.
+- **Scoped per operation**: Auto-cleaned via `hookDispatcher.unregister()` on completion.
+- **Sandbox/MCP**: No separate hooks — they go through `executeTool`, so `beforeToolCall`/`afterToolCall` cover them. Use `event.identifier` to filter.
+
+## Real-World Example: agent-evals
+
+See `devtools/agent-evals/helpers/runner.ts` — `createEvalHooks()` uses `afterStep`, `onComplete`, `afterToolCall`, and `beforeToolCall` (for mock).
@@ -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.
@@ -0,0 +1,218 @@
+---
+name: cli-backend-testing
+description: >
+  CLI + Backend integration testing workflow. Use when verifying backend API changes
+  (TRPC routers, services, models) via the LobeHub CLI against a local dev server.
+  Triggers on 'cli test', 'test with cli', 'verify with cli', 'local cli test',
+  'backend test with cli', or when needing to validate server-side changes end-to-end.
+---
+
+# CLI + Backend Integration Testing
+
+Standard workflow for verifying backend changes using the LobeHub CLI (`lh`) against a local dev server.
+
+## When to Use
+
+- Verifying TRPC router / service / model changes end-to-end
+- Testing new API fields or response structure changes
+- Validating CLI command output after backend modifications
+- Debugging data flow issues between server and CLI
+
+## Prerequisites
+
+| Requirement  | Details                                                       |
+| ------------ | ------------------------------------------------------------- |
+| Dev server   | `localhost:3011` (Next.js)                                    |
+| CLI source   | `lobehub/apps/cli/`                                           |
+| CLI dev mode | Uses `LOBEHUB_CLI_HOME=.lobehub-dev` for isolated credentials |
+| Auth         | Device Code Flow login to local server                        |
+
+## Quick Reference
+
+All CLI dev commands run from `lobehub/apps/cli/`:
+
+```bash
+# Shorthand for all commands below
+CLI="LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts"
+```
+
+## Workflow
+
+### Step 1: Ensure Dev Server is Running
+
+Check if the dev server is already running:
+
+```bash
+curl -s -o /dev/null -w '%{http_code}' http://localhost:3011/ 2> /dev/null
+```
+
+- **If reachable** (returns any HTTP status): server is running. Skip to Step 2.
+- **If unreachable**: start the server:
+
+```bash
+# From cloud repo root
+pnpm run dev:next
+```
+
+To **restart** (pick up server-side code changes):
+
+```bash
+lsof -ti:3011 | xargs kill
+pnpm run dev:next
+```
+
+**Important:** Server-side code changes in the submodule (`lobehub/src/server/`, `lobehub/packages/`) require a server restart. Next.js hot-reload may not pick up changes in submodule packages.
+
+### Step 2: Check CLI Authentication
+
+Check if dev credentials already exist:
+
+```bash
+cat lobehub/apps/cli/.lobehub-dev/settings.json 2> /dev/null
+```
+
+- **If file exists and contains `"serverUrl": "http://localhost:3011"`**: already authenticated. Skip to Step 3.
+- **If file missing or points to wrong server**: login is needed. Ask the user to run:
+
+```bash
+! cd lobehub/apps/cli && LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts login --server http://localhost:3011
+```
+
+> Login requires interactive browser authorization (OIDC Device Code Flow), so the user must run it themselves via `!` prefix. After login, credentials are saved to `lobehub/apps/cli/.lobehub-dev/` and persist across sessions.
+
+### Step 3: Test with CLI Commands
+
+CLI runs from source (`bun src/index.ts`), so CLI-side code changes take effect immediately without rebuilding.
+
+```bash
+cd lobehub/apps/cli
+LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
+```
+
+### Step 4: Clean Up Test Data
+
+Delete any test data created during verification:
+
+```bash
+LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts task delete < id > -y
+LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts agent delete < id > -y
+```
+
+## Common Testing Patterns
+
+### Task System
+
+```bash
+# List tasks
+$CLI task list
+
+# Create test data with nesting
+$CLI task create -n "Root Task" -i "Test instruction"
+$CLI task create -n "Child Task" -i "Sub instruction" --parent T-1
+
+# View task detail (tests getTaskDetail service)
+$CLI task view T-1
+
+# View task tree
+$CLI task tree T-1
+
+# Test lifecycle
+$CLI task edit T-1 --status running
+$CLI task comment T-1 -m "Test comment"
+
+# Clean up
+$CLI task delete T-1 -y
+```
+
+### Agent System
+
+```bash
+# List agents
+$CLI agent list
+
+# View agent detail
+$CLI agent view <agent-id>
+
+# Run agent (tests agent execution pipeline)
+$CLI agent run <agent-id> -m "Test prompt"
+```
+
+### Document & Knowledge Base
+
+```bash
+# List documents
+$CLI doc list
+
+# Create and view
+$CLI doc create -t "Test Doc" -c "Content here"
+$CLI doc view <doc-id>
+
+# Knowledge base
+$CLI kb list
+$CLI kb tree <kb-id>
+```
+
+### Model & Provider
+
+```bash
+# List models and providers
+$CLI model list
+$CLI provider list
+
+# Test provider connectivity
+$CLI provider test <provider-id>
+```
+
+## Dev-Test Cycle
+
+The standard cycle for backend development:
+
+```
+1. Make code changes (service/model/router/type)
+         |
+2. Run unit tests (fast feedback)
+   bunx vitest run --silent='passed-only' '<test-file>'
+         |
+3. Restart dev server (if server-side changes)
+   lsof -ti:3011 | xargs kill && pnpm run dev:next
+         |
+4. CLI verification (end-to-end)
+   LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts <command>
+         |
+5. Clean up test data
+```
+
+### When Server Restart is Needed
+
+| Change Location                           | Restart? |
+| ----------------------------------------- | -------- |
+| `lobehub/src/server/` (routers, services) | Yes      |
+| `lobehub/packages/database/` (models)     | Yes      |
+| `lobehub/packages/types/`                 | Yes      |
+| `lobehub/packages/prompts/`               | Yes      |
+| `lobehub/apps/cli/` (CLI code)            | No       |
+| `src/` (cloud overrides)                  | Yes      |
+
+### When Server Restart is NOT Needed
+
+CLI runs from source via `bun src/index.ts`, so any changes to `lobehub/apps/cli/src/` take effect immediately on next command invocation.
+
+## Troubleshooting
+
+| Issue                       | Solution                                                              |
+| --------------------------- | --------------------------------------------------------------------- |
+| `No authentication found`   | Run `login --server http://localhost:3011`                            |
+| `UNAUTHORIZED` on API calls | Token expired; re-run login                                           |
+| `ECONNREFUSED`              | Dev server not running; start with `pnpm run dev:next`                |
+| CLI shows old data/behavior | Server needs restart to pick up code changes                          |
+| `EADDRINUSE` on port 3011   | Server already running; kill with `lsof -ti:3011 \| xargs kill`       |
+| Login opens wrong server    | Must use `--server http://localhost:3011` flag (env var doesn't work) |
+
+## Credential Isolation
+
+| Mode       | Credential Dir                   | Server            |
+| ---------- | -------------------------------- | ----------------- |
+| Dev        | `lobehub/apps/cli/.lobehub-dev/` | `localhost:3011`  |
+| Production | `~/.lobehub/`                    | `app.lobehub.com` |
+
+The two environments are completely isolated. Dev mode credentials are gitignored.
@@ -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
@@ -0,0 +1,83 @@
+---
+name: heterogeneous-agent
+description: Guide for implementing and debugging LobeHub heterogeneous agent integrations such as Claude Code, Codex, and future external CLI agents. Use when working on adapter event mapping, Electron IPC transport, renderer persistence, tool-call chaining, subagent threads, resume/session handling, or regressions like mixed multi-tool messages, broken step boundaries, stuck tool loading, and orphan tool messages. Triggers on 'heterogeneous agent', 'hetero agent', '异构 agent', 'claude code adapter', 'codex adapter', 'external agent CLI', '孤立 tool 消息', 'raw Codex trace', or adapter/executor bugs.
+---
+
+# Heterogeneous Agent Development
+
+Use this skill when the bug or feature lives in the external CLI agent pipeline, not the normal server-side agent runtime.
+
+## Use This Skill For
+
+- Adding or changing a driver under `apps/desktop/src/main/modules/heterogeneousAgent/drivers/`
+- Editing an adapter under `packages/heterogeneous-agents/src/adapters/`
+- Debugging `heteroAgentRawLine` transport, `window.__HETERO_AGENT_TRACE`, or `executeHeterogeneousAgent`
+- Fixing Claude Code stream-json bugs such as duplicate partial/full chunks, broken `message.id` boundaries, missing `tool_result`, TodoWrite state drift, or subagent thread routing
+- Fixing Codex JSONL bugs such as mixed multi-tool messages, broken turn boundaries, or missing tool-result mapping
+- Fixing step-boundary, tool persistence, subagent thread, or resume bugs in Claude Code / Codex flows
+- Reproducing multi-tool mixing, orphan tool messages, or stuck tool-result loading
+
+## Pipeline Map
+
+1. CLI raw stdout / JSONL
+2. Electron main spawns the CLI and broadcasts `heteroAgentRawLine`
+3. Adapter maps raw provider events into `HeterogeneousAgentEvent`
+4. `executeHeterogeneousAgent` persists assistant/tool messages and forwards stream events
+5. `createGatewayEventHandler` hydrates the UI
+6. Only after this path looks correct should you move on to `agent-tracing` or context-engine debugging
+
+## Read These Files First
+
+- `apps/desktop/src/main/controllers/HeterogeneousAgentCtr.ts`
+- `apps/desktop/src/main/modules/heterogeneousAgent/drivers/claudeCode.ts`
+- `apps/desktop/src/main/modules/heterogeneousAgent/drivers/codex.ts`
+- `packages/heterogeneous-agents/src/adapters/claudeCode.ts`
+- `packages/heterogeneous-agents/src/adapters/codex.ts`
+- `src/store/chat/slices/aiChat/actions/heterogeneousAgentExecutor.ts`
+- `src/store/chat/slices/aiChat/actions/__tests__/heterogeneousAgentExecutor.test.ts`
+
+## Default Debug Order
+
+1. Prove whether the raw CLI output is correct before touching UI code.
+2. If raw output is correct, compare it with adapter output. In dev, `executeHeterogeneousAgent` exposes `window.__HETERO_AGENT_TRACE`.
+3. If adapted events look correct, inspect `persistToolBatch`, `persistToolResult`, step transitions, and subagent routing.
+4. Turn the repro into a focused test before fixing.
+5. Only after the transport/adapter/executor path looks sound should you debug later-stage message processing.
+
+## Critical Invariants
+
+- One raw tool item must map to one stable `ToolCallPayload.id`.
+- A new main-agent step must emit a boundary signal before events are forwarded to the new assistant.
+- In Claude Code, multiple assistant events with the same `message.id` are one turn, not multiple turns.
+- In Claude Code, `tool_result` lives in `type: 'user'` events, not assistant events.
+- In Claude Code partial mode, `message_delta.usage` is authoritative; do not trust echoed usage on every assistant block.
+- `persistToolBatch` must pre-register assistant `tools[]` before creating tool messages.
+- Every tool message must keep `parentId` equal to the owning assistant and `tool_call_id` equal to the tool id.
+- `tool_result` must resolve an existing `toolMsgIdByCallId`.
+- Subagent chunks must stay in thread scope and must not be forwarded into the main assistant stream.
+- Never clear the global `toolMsgIdByCallId` map at main step boundaries.
+
+## Common Bug Patterns
+
+- Claude Code duplicates text or thinking:
+  check whether partial deltas and the later full assistant block are both being emitted.
+- Claude Code opens too many assistant messages:
+  check whether the adapter is cutting steps on every assistant event instead of only on `message.id` changes.
+- Claude Code tool results never land:
+  check whether `type: 'user'` `tool_result` blocks are being ignored because the code only inspects assistant events.
+- Claude Code TodoWrite cards look stale:
+  check whether synthesized `pluginState.todos` is being attached at tool-result time.
+- Claude Code subagent transcript leaks into the main bubble:
+  check `parent_tool_use_id` handling and whether subagent chunks are being forwarded to the main gateway handler.
+- Multiple Codex tools collapse into one assistant message:
+  first check whether the adapter emits a usable step boundary such as `newStep` or an equivalent turn-change signal.
+- Orphan tool messages:
+  first check step-transition ordering and whether `persistToolBatch` Phase 1 ran before tool message creation.
+- Tool bubble stays loading:
+  look for `tool_result for unknown toolCallId` and missing `result_msg_id` backfill.
+- Subagent tools show up in the main bubble:
+  check for subagent chunks reaching the main gateway handler.
+
+## References
+
+- For commands, trace capture, invariants, and focused test commands, read [references/debug-workflow.md](./references/debug-workflow.md).
@@ -0,0 +1,246 @@
+# Heterogeneous Agent Debug Workflow
+
+## Contents
+
+1. Pipeline map
+2. Capture raw CLI traces first
+3. Compare raw and adapted events
+4. Check step boundaries before persistence
+5. Check tool persistence invariants
+6. Focused tests
+7. Repro-to-fix workflow
+
+## 1. Pipeline Map
+
+```
+CLI raw stdout
+  -> HeterogeneousAgentCtr (Electron main)
+  -> heteroAgentRawLine broadcast
+  -> createAdapter(...)
+  -> executeHeterogeneousAgent(...)
+  -> persistToolBatch / persistToolResult
+  -> createGatewayEventHandler(...)
+  -> UI hydration
+```
+
+Start at the leftmost broken layer. Do not jump straight to UI rendering unless raw and adapted events already look correct.
+
+## 2. Capture Raw CLI Traces First
+
+### Codex raw JSONL
+
+Use a read-only prompt and save traces under the repo-local scratch directory `.heerogeneous-tracing/`.
+
+```bash
+ts=$(date +%Y%m%d-%H%M%S)
+out=".heerogeneous-tracing/codex-${ts}.jsonl"
+last=".heerogeneous-tracing/codex-${ts}.last.txt"
+
+cat << 'EOF' | codex exec --json --skip-git-repo-check --sandbox read-only -C "$PWD" -o "$last" - > "$out"
+You are being run only to collect a raw Codex JSON event trace.
+Do not modify any files.
+Use at least 4 separate shell tool invocations, one invocation per command.
+Run a short sequence of read-only repo checks and then reply with a one-sentence summary.
+EOF
+```
+
+What to look for in the JSONL:
+
+- `thread.started`
+- `turn.started`
+- `item.started` / `item.completed`
+- `item.type === 'command_execution'`
+- `item.type === 'agent_message'`
+- `turn.completed`
+
+If raw Codex already merges tools into one item, the adapter is innocent. If raw Codex emits independent items but UI collapses them, the bug is downstream.
+
+If the repo already contains useful traces under `.heerogeneous-tracing/`, inspect them before reproducing.
+
+### Claude Code raw NDJSON
+
+Mirror the arguments from `apps/desktop/src/main/modules/heterogeneousAgent/drivers/claudeCode.ts`.
+
+- `-p`
+- `--input-format stream-json`
+- `--output-format stream-json`
+- `--verbose`
+- `--include-partial-messages`
+- `--permission-mode bypassPermissions`
+
+You can capture a local raw trace like this:
+
+```bash
+ts=$(date +%Y%m%d-%H%M%S)
+out=".heerogeneous-tracing/claude-${ts}.ndjson"
+
+cat << 'EOF' | claude -p \
+  --input-format stream-json \
+  --output-format stream-json \
+  --verbose \
+  --include-partial-messages \
+  --permission-mode bypassPermissions \
+  > "$out"
+{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Do a few read-only repo checks, use several tool calls, and then summarize briefly."}]}}
+EOF
+```
+
+What to look for in Claude Code raw traces:
+
+- `type: 'system', subtype: 'init'`
+- `type: 'assistant'` blocks for `thinking`, `tool_use`, and `text`
+- `type: 'user'` blocks containing `tool_result`
+- `type: 'stream_event'` with `message_start`, `content_block_delta`, and `message_delta`
+- `type: 'result'`
+- `type: 'rate_limit_event'`
+
+Important Claude Code semantics:
+
+- Each content block often arrives as its own assistant event.
+- Multiple assistant events can share the same `message.id`; that is still one turn.
+- `message.id` change is the main-step boundary.
+- Partial deltas arrive before the later full assistant block.
+- `message_delta.usage` is the authoritative per-turn usage.
+- Subagent events are tagged with `parent_tool_use_id`.
+
+If the repo already contains useful references, inspect these first:
+
+- `.heerogeneous-tracing/cc-monitor-real-trace.jsonl`
+- `.heerogeneous-tracing/cc-stream-chain-reference.md`
+
+If you only need boundary semantics or tool persistence behavior, prefer existing adapter tests under:
+
+- `packages/heterogeneous-agents/src/adapters/claudeCode.test.ts`
+- `packages/heterogeneous-agents/src/adapters/claudeCode.e2e.test.ts`
+
+## 3. Compare Raw And Adapted Events
+
+In dev builds, `executeHeterogeneousAgent` stores raw lines plus adapted events on:
+
+- `window.__HETERO_AGENT_TRACE`
+
+Use that trace to compare:
+
+- raw `item.started` / `item.completed`
+- adapted `stream_chunk { chunkType: 'tools_calling' }`
+- adapted `tool_result`
+- adapted `tool_end`
+
+For Codex, the usual mapping is:
+
+- raw `item.started(command_execution)` -> `tools_calling` + `tool_start`
+- raw `item.completed(command_execution)` -> `tool_result` + `tool_end`
+- raw `item.completed(agent_message)` -> `stream_chunk(text)`
+
+If the raw trace is right but adapted events are wrong, fix the adapter before touching persistence.
+
+## 4. Check Step Boundaries Before Persistence
+
+This is the first thing to verify for "mixed tools in one assistant" bugs.
+
+### Claude Code
+
+Claude Code step boundaries are keyed off assistant `message.id` changes. The adapter should emit:
+
+- `stream_end`
+- `stream_start { newStep: true }`
+
+Also verify these Claude-specific invariants:
+
+- the first assistant after init does not open a new step
+- repeated assistant events with the same `message.id` do not open a new step
+- partial `content_block_delta` text/thinking does not get duplicated by the later full assistant event
+- `tool_result` from `type: 'user'` updates the matching tool row
+- `parent_tool_use_id` creates thread-scoped subagent chunks instead of main-stream chunks
+- TodoWrite `tool_use.input` is converted into synthesized `pluginState.todos` on `tool_result`
+
+Good references:
+
+- `packages/heterogeneous-agents/src/adapters/claudeCode.ts`
+- `packages/heterogeneous-agents/src/adapters/claudeCode.test.ts`
+
+### Codex
+
+Codex raw traces usually provide turn-level boundaries through:
+
+- `turn.started`
+- `turn.completed`
+
+The executor only cuts a new assistant message when it receives a step-boundary signal it understands. If the adapter emits `stream_start` without `newStep`, multiple Codex tools and text chunks can accumulate under the same assistant longer than intended.
+
+Relevant files:
+
+- `packages/heterogeneous-agents/src/adapters/codex.ts`
+- `src/store/chat/slices/aiChat/actions/heterogeneousAgentExecutor.ts`
+
+## 5. Check Tool Persistence Invariants
+
+Read `persistToolBatch` and `persistToolResult` before changing UI code.
+
+### `persistToolBatch`
+
+The expected order is:
+
+1. Pre-register assistant `tools[]`
+2. Create `role: 'tool'` messages
+3. Backfill `result_msg_id` onto assistant `tools[]`
+
+If tool rows are created before assistant `tools[]` are registered, orphan tool messages are likely.
+
+### `persistToolResult`
+
+`tool_result` must resolve the tool row through `toolMsgIdByCallId`.
+
+Warning signs:
+
+- `tool_result for unknown toolCallId`
+- tool rows with empty content forever
+- missing `result_msg_id`
+
+For Claude Code, remember that tool results originate from raw `type: 'user'` events.
+
+### Main vs subagent scope
+
+- Main-agent tool state is per-step.
+- `toolMsgIdByCallId` is global across main and subagent scopes.
+- Subagent chunks must not be forwarded into the main gateway handler.
+
+If subagent events leak to the main handler, the main bubble can inherit the wrong `tools[]` and content.
+
+## 6. Focused Tests
+
+Run the smallest useful test set first.
+
+```bash
+bunx vitest run --silent='passed-only' 'packages/heterogeneous-agents/src/adapters/codex.test.ts'
+bunx vitest run --silent='passed-only' 'packages/heterogeneous-agents/src/adapters/claudeCode.test.ts'
+bunx vitest run --silent='passed-only' 'src/store/chat/slices/aiChat/actions/__tests__/heterogeneousAgentExecutor.test.ts'
+```
+
+Especially useful places:
+
+- `packages/heterogeneous-agents/src/adapters/codex.test.ts`
+- `packages/heterogeneous-agents/src/adapters/claudeCode.test.ts`
+- `src/store/chat/slices/aiChat/actions/__tests__/heterogeneousAgentExecutor.test.ts`
+
+Claude Code-specific assertions worth adding when fixing bugs:
+
+- same `message.id` does not emit `newStep`
+- changed `message.id` does emit `stream_end` plus `stream_start { newStep: true }`
+- partial text/thinking is emitted once
+- `tool_result` from `user` events reaches the right tool row
+- subagent chunks carry `subagent.parentToolCallId`
+- TodoWrite result synthesizes `pluginState.todos`
+
+When the bug comes from a real trace, distill it into the closest existing test file instead of relying on manual UI-only repros.
+
+## 7. Repro-To-Fix Workflow
+
+1. Capture a raw trace and save it under `.heerogeneous-tracing/`.
+2. Confirm whether the bug appears in raw events, adapted events, or persistence.
+3. Add or update the narrowest failing test near the broken layer.
+4. Fix the smallest layer that can explain the symptom.
+5. Re-run focused tests.
+6. Only then do an Electron smoke test with the `local-testing` skill if UI confirmation is still needed.
+
+Do not start with a broad Electron repro if a raw trace or adapter test can prove the fault zone faster.
@@ -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)
@@ -20,14 +20,73 @@ This is NON-NEGOTIABLE. Skipping Linear comments is a workflow violation.
 ## Workflow

 1. **Retrieve issue details** before starting: `mcp__linear-server__get_issue`
-2. **Check for sub-issues**: Use `mcp__linear-server__list_issues` with `parentId` filter
-3. **Update issue status** when completing: `mcp__linear-server__update_issue`
-4. **Add completion comment** (REQUIRED): `mcp__linear-server__create_comment`
+2. **Read images**: If the issue description contains images, MUST use `mcp__linear-server__extract_images` to read image content for full context
+3. **Check for sub-issues**: Use `mcp__linear-server__list_issues` with `parentId` filter
+4. **Mark as In Progress**: When starting to plan or implement an issue, immediately update status to **"In Progress"** via `mcp__linear-server__update_issue`
+5. **Update issue status** when completing: `mcp__linear-server__update_issue`
+6. **Add completion comment** (REQUIRED): `mcp__linear-server__create_comment`

 ## Creating Issues

 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:
@@ -0,0 +1,520 @@
+---
+name: local-testing
+description: >
+  Local app and bot testing. Uses agent-browser CLI for Electron/web app UI testing,
+  and osascript (AppleScript) for controlling native macOS apps (WeChat, Discord, Telegram, Slack, Lark/飞书, QQ)
+  to test bots. Triggers on 'local test', 'test in electron', 'test desktop', 'test bot',
+  'bot test', 'test in discord', 'test in telegram', 'test in slack', 'test in weixin',
+  'test in wechat', 'test in lark', 'test in feishu', 'test in qq',
+  'manual test', 'osascript', or UI/bot verification tasks.
+---
+
+# Local App & Bot Testing
+
+Two approaches for local testing on macOS:
+
+| Approach                    | Tool                | Best For                                             |
+| --------------------------- | ------------------- | ---------------------------------------------------- |
+| **agent-browser + CDP**     | `agent-browser` CLI | Electron apps, web apps (DOM access, JS eval)        |
+| **osascript (AppleScript)** | `osascript -e`      | Native macOS apps (WeChat, Discord, Telegram, Slack) |
+
+---
+
+# Part 1: agent-browser (Electron / Web Apps)
+
+Use `agent-browser` to automate Chromium-based apps via Chrome DevTools Protocol.
+
+Install via `npm i -g agent-browser`, `brew install agent-browser`, or `cargo install agent-browser`. Run `agent-browser install` to download Chrome. Run `agent-browser upgrade` to update.
+
+## Core Workflow
+
+Every browser automation follows this pattern:
+
+1. **Navigate**: `agent-browser open <url>`
+2. **Snapshot**: `agent-browser snapshot -i` (get element refs like `@e1`, `@e2`)
+3. **Interact**: Use refs to click, fill, select
+4. **Re-snapshot**: After navigation or DOM changes, get fresh refs
+
+```bash
+agent-browser open https://example.com/form
+agent-browser snapshot -i
+# Output: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"
+
+agent-browser fill @e1 "user@example.com"
+agent-browser fill @e2 "password123"
+agent-browser click @e3
+agent-browser wait --load networkidle
+agent-browser snapshot -i # Check result
+```
+
+## Command Chaining
+
+```bash
+# Chain open + wait + snapshot in one call
+agent-browser open https://example.com && agent-browser wait --load networkidle && agent-browser snapshot -i
+```
+
+Use `&&` when you don't need to read intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs, then interact).
+
+## Essential Commands
+
+```bash
+# Navigation
+agent-browser open <url>              # Navigate (aliases: goto, navigate)
+agent-browser close                   # Close browser
+agent-browser close --all             # Close all active sessions
+
+# Snapshot
+agent-browser snapshot -i             # Interactive elements with refs (recommended)
+agent-browser snapshot -s "#selector" # Scope to CSS selector
+
+# Interaction (use @refs from snapshot)
+agent-browser click @e1               # Click element
+agent-browser click @e1 --new-tab     # Click and open in new tab
+agent-browser fill @e2 "text"         # Clear and type text
+agent-browser type @e2 "text"         # Type without clearing
+agent-browser select @e1 "option"     # Select dropdown option
+agent-browser check @e1               # Check checkbox
+agent-browser press Enter             # Press key
+agent-browser keyboard type "text"    # Type at current focus (no selector)
+agent-browser keyboard inserttext "text"  # Insert without key events
+agent-browser scroll down 500         # Scroll page
+agent-browser scroll down 500 --selector "div.content"  # Scroll within container
+
+# Get information
+agent-browser get text @e1            # Get element text
+agent-browser get url                 # Get current URL
+agent-browser get title               # Get page title
+agent-browser get cdp-url             # Get CDP WebSocket URL
+
+# Wait
+agent-browser wait @e1                # Wait for element
+agent-browser wait --load networkidle # Wait for network idle
+agent-browser wait --url "**/page"    # Wait for URL pattern
+agent-browser wait 2000               # Wait milliseconds
+agent-browser wait --text "Welcome"   # Wait for text to appear
+agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # Wait for text to disappear
+agent-browser wait "#spinner" --state hidden  # Wait for element to disappear
+
+# Downloads
+agent-browser download @e1 ./file.pdf          # Click element to trigger download
+agent-browser wait --download ./output.zip     # Wait for any download to complete
+
+# Network
+agent-browser network requests                 # Inspect tracked requests
+agent-browser network requests --type xhr,fetch  # Filter by resource type
+agent-browser network requests --method POST   # Filter by HTTP method
+agent-browser network route "**/api/*" --abort # Block matching requests
+agent-browser network har start                # Start HAR recording
+agent-browser network har stop ./capture.har   # Stop and save HAR file
+
+# Viewport & Device Emulation
+agent-browser set viewport 1920 1080          # Set viewport size (default: 1280x720)
+agent-browser set viewport 1920 1080 2        # 2x retina
+agent-browser set device "iPhone 14"          # Emulate device (viewport + user agent)
+
+# Capture
+agent-browser screenshot              # Screenshot to temp dir
+agent-browser screenshot --full       # Full page screenshot
+agent-browser screenshot --annotate   # Annotated screenshot with numbered element labels
+agent-browser pdf output.pdf          # Save as PDF
+
+# Clipboard
+agent-browser clipboard read          # Read text from clipboard
+agent-browser clipboard write "text"  # Write text to clipboard
+agent-browser clipboard copy          # Copy current selection
+agent-browser clipboard paste         # Paste from clipboard
+
+# Dialogs (alert, confirm, prompt, beforeunload)
+agent-browser dialog accept           # Accept dialog
+agent-browser dialog accept "input"   # Accept prompt dialog with text
+agent-browser dialog dismiss          # Dismiss/cancel dialog
+agent-browser dialog status           # Check if dialog is open
+
+# Diff (compare page states)
+agent-browser diff snapshot                        # Compare current vs last snapshot
+agent-browser diff screenshot --baseline before.png  # Visual pixel diff
+agent-browser diff url <url1> <url2>               # Compare two pages
+
+# Streaming
+agent-browser stream enable           # Start WebSocket streaming
+agent-browser stream status           # Inspect streaming state
+agent-browser stream disable          # Stop streaming
+```
+
+## Batch Execution
+
+```bash
+echo '[
+  ["open", "https://example.com"],
+  ["snapshot", "-i"],
+  ["click", "@e1"],
+  ["screenshot", "result.png"]
+]' | agent-browser batch --json
+```
+
+## Authentication
+
+```bash
+# Option 1: Auth vault (credentials stored encrypted)
+echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
+agent-browser auth login myapp
+
+# Option 2: Session name (auto-save/restore cookies + localStorage)
+agent-browser --session-name myapp open https://app.example.com/login
+agent-browser close                                                       # State auto-saved
+agent-browser --session-name myapp open https://app.example.com/dashboard # Auto-restored
+
+# Option 3: Persistent profile
+agent-browser --profile ~/.myapp open https://app.example.com/login
+
+# Option 4: State file
+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
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find role button click --name "Submit"
+agent-browser find placeholder "Search" type "query"
+agent-browser find testid "submit-btn" click
+```
+
+## JavaScript Evaluation (eval)
+
+```bash
+# Simple expressions
+agent-browser eval 'document.title'
+
+# Complex JS: use --stdin with heredoc (RECOMMENDED)
+agent-browser eval --stdin << 'EVALEOF'
+JSON.stringify(
+  Array.from(document.querySelectorAll("img"))
+    .filter(i => !i.alt)
+    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
+)
+EVALEOF
+
+# Base64 encoding (avoids all shell escaping issues)
+agent-browser eval -b "$(echo -n 'document.title' | base64)"
+```
+
+## Ref Lifecycle
+
+Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after clicking links/buttons that navigate, form submissions, or dynamic content loading.
+
+## Annotated Screenshots (Vision Mode)
+
+```bash
+agent-browser screenshot --annotate
+# Output includes the image path and a legend:
+#   [1] @e1 button "Submit"
+#   [2] @e2 link "Home"
+agent-browser click @e2 # Click using ref from annotated screenshot
+```
+
+## Parallel Sessions
+
+```bash
+agent-browser --session site1 open https://site-a.com
+agent-browser --session site2 open https://site-b.com
+agent-browser session list
+```
+
+## Connect to Existing Chrome
+
+```bash
+agent-browser --auto-connect snapshot # Auto-discover running Chrome
+agent-browser --cdp 9222 snapshot     # Explicit CDP port
+```
+
+## iOS Simulator (Mobile Safari)
+
+```bash
+agent-browser device list
+agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
+agent-browser -p ios snapshot -i
+agent-browser -p ios tap @e1
+agent-browser -p ios swipe up
+agent-browser -p ios screenshot mobile.png
+agent-browser -p ios close
+```
+
+## Observability Dashboard
+
+```bash
+agent-browser dashboard install
+agent-browser dashboard start # Background server on port 4848
+agent-browser dashboard stop
+```
+
+## Cloud Providers
+
+Use `-p <provider>` to run against cloud browsers: `agentcore`, `browserbase`, `browserless`, `browseruse`, `kernel`.
+
+## Browser Engine Selection
+
+```bash
+agent-browser --engine lightpanda open example.com # 10x faster, 10x less memory
+```
+
+## Electron (LobeHub Desktop)
+
+### Setup / Teardown
+
+Use the `electron-dev.sh` script to manage the Electron dev environment. It handles process lifecycle, waits for SPA readiness, and reliably kills all child processes (main + helpers + vite).
+
+```bash
+SCRIPT=".agents/skills/local-testing/scripts/electron-dev.sh"
+
+# Start Electron dev with CDP (idempotent — skips if already running)
+$SCRIPT start
+
+# Check if Electron is running and CDP is reachable
+$SCRIPT status
+
+# Kill all Electron-related processes (main + helper + vite)
+$SCRIPT stop
+
+# Force fresh restart
+$SCRIPT restart
+```
+
+After `start` succeeds, connect with: `agent-browser --cdp 9222 snapshot -i`
+
+**Always run `$SCRIPT stop` when done testing** — `pkill -f "Electron"` alone won't catch all helper processes.
+
+#### Environment Variables
+
+| Variable          | Default                 | Description                              |
+| ----------------- | ----------------------- | ---------------------------------------- |
+| `CDP_PORT`        | `9222`                  | Chrome DevTools Protocol port            |
+| `ELECTRON_LOG`    | `/tmp/electron-dev.log` | Electron process log                     |
+| `ELECTRON_WAIT_S` | `60`                    | Max seconds to wait for Electron process |
+| `RENDERER_WAIT_S` | `60`                    | Max seconds to wait for SPA to load      |
+
+### LobeHub-Specific Patterns
+
+#### Access Zustand Store State
+
+```bash
+agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
+(function() {
+  var chat = window.__LOBE_STORES.chat();
+  var ops = Object.values(chat.operations);
+  return JSON.stringify({
+    ops: ops.map(function(o) { return { type: o.type, status: o.status }; }),
+    activeAgent: chat.activeAgentId,
+    activeTopic: chat.activeTopicId,
+  });
+})()
+EVALEOF
+```
+
+#### Find and Use the Chat Input
+
+```bash
+# The chat input is contenteditable — must use -C flag
+agent-browser --cdp 9222 snapshot -i -C 2>&1 | grep "editable"
+
+agent-browser --cdp 9222 click @e48
+agent-browser --cdp 9222 type @e48 "Hello world"
+agent-browser --cdp 9222 press Enter
+```
+
+#### Wait for Agent to Complete
+
+```bash
+agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
+(function() {
+  var chat = window.__LOBE_STORES.chat();
+  var ops = Object.values(chat.operations);
+  var running = ops.filter(function(o) { return o.status === 'running'; });
+  return running.length === 0 ? 'done' : 'running: ' + running.length;
+})()
+EVALEOF
+```
+
+#### Install Error Interceptor
+
+```bash
+agent-browser --cdp 9222 eval --stdin << 'EVALEOF'
+(function() {
+  window.__CAPTURED_ERRORS = [];
+  var orig = console.error;
+  console.error = function() {
+    var msg = Array.from(arguments).map(function(a) {
+      if (a instanceof Error) return a.message;
+      return typeof a === 'object' ? JSON.stringify(a) : String(a);
+    }).join(' ');
+    window.__CAPTURED_ERRORS.push(msg);
+    orig.apply(console, arguments);
+  };
+  return 'installed';
+})()
+EVALEOF
+
+# Later, check captured errors:
+agent-browser --cdp 9222 eval "JSON.stringify(window.__CAPTURED_ERRORS)"
+```
+
+## Chrome / Web Apps
+
+```bash
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-test-profile \
+  "<URL>" &
+sleep 5
+agent-browser --cdp 9222 snapshot -i
+
+# Or auto-discover running Chrome with remote debugging
+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. Works with any app that supports macOS Accessibility, no CDP or Chromium needed.
+
+The pattern is the same for every platform:
+
+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)
+
+## Per-Platform References
+
+Pick the file for your target platform — each contains activation, navigation, send-message, and verification snippets specific to that app:
+
+| 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`        |
+
+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.
+
+---
+
+# Scripts
+
+Ready-to-use scripts in `.agents/skills/local-testing/scripts/`:
+
+| Script                    | Usage                                               |
+| ------------------------- | --------------------------------------------------- |
+| `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          |
+| `test-wechat-bot.sh`      | Send message to WeChat bot via osascript            |
+| `test-lark-bot.sh`        | Send message to Lark / 飞书 bot via osascript       |
+| `test-qq-bot.sh`          | Send message to QQ bot via osascript                |
+
+### Window Screenshot Utility
+
+`capture-app-window.sh` captures a screenshot of a specific app window using `screencapture -l <windowID>`. It uses Swift + CGWindowList to find the window by process name, so screenshots work correctly even when the window is on an external monitor or behind other windows.
+
+```bash
+# Standalone usage
+./.agents/skills/local-testing/scripts/capture-app-window.sh "Discord" /tmp/discord.png
+./.agents/skills/local-testing/scripts/capture-app-window.sh "Slack" /tmp/slack.png
+./.agents/skills/local-testing/scripts/capture-app-window.sh "WeChat" /tmp/wechat.png
+```
+
+All bot test scripts use this utility automatically for their screenshots.
+
+### Bot Test Scripts
+
+All bot test scripts share the same interface:
+
+```bash
+./scripts/test-<platform>-bot.sh <channel_or_contact> <message> [wait_seconds] [screenshot_path]
+```
+
+Examples:
+
+```bash
+# Discord — test a bot in #bot-testing channel
+./.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
+
+# Slack — test a bot in #bot-testing channel
+./.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
+
+# Telegram — test a bot by username
+./.agents/skills/local-testing/scripts/test-telegram-bot.sh "MyTestBot" "/start"
+./.agents/skills/local-testing/scripts/test-telegram-bot.sh "GPTBot" "Hello" 60
+
+# WeChat — test a bot or send to a contact
+./.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
+
+# Lark/飞书 — test a bot in a group chat
+./.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
+
+# QQ — test a bot in a group or direct chat
+./.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
+```
+
+Each script: activates the app, navigates to the channel/contact, pastes the message via clipboard, sends, waits, and takes a screenshot. Use the `Read` tool on the screenshot for visual verification.
+
+---
+
+# Screen Recording
+
+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
+./.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
+```
+
+Outputs to `.records/` directory (gitignored): `<name>.mp4` (video) + `<name>/` (screenshots every 3s).
+
+---
+
+# Gotchas
+
+### agent-browser
+
+- **Daemon can get stuck** — if commands hang, `agent-browser close --all` or `pkill -f agent-browser` to reset
+- **HMR invalidates everything** — after code changes, refs break. Re-snapshot or restart
+- **`snapshot -i` doesn't find contenteditable** — use `snapshot -i -C` for rich text editors
+- **`fill` doesn't work on contenteditable** — use `type` for chat inputs
+- **Screenshots go to `~/.agent-browser/tmp/screenshots/`** — read them with the `Read` tool
+- **Dialogs block all commands** — if commands time out, check `agent-browser dialog status`
+- **Default timeout is 25s** — override with `AGENT_BROWSER_DEFAULT_TIMEOUT` (ms) or use explicit waits
+- **Shell quoting corrupts eval** — use `eval --stdin <<'EVALEOF'` for complex JS
+
+### Electron-specific
+
+- **Always use `electron-dev.sh stop` to clean up** — `pkill -f "Electron"` only kills the main process; helper processes (GPU, renderer, network) survive. The script finds and kills all of them via PID matching against the project's electron binary path.
+- **`npx electron-vite dev` must run from `apps/desktop/`** — running from project root fails silently. The `electron-dev.sh` script handles this automatically.
+- **Don't resize the Electron window after load** — resizing triggers full SPA reload
+- **Store is at `window.__LOBE_STORES`** not `window.__ZUSTAND_STORES__`
+
+### osascript
+
+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,54 @@
+#!/usr/bin/env bash
+#
+# capture-app-window.sh — Capture a screenshot of a specific app window
+#
+# Uses CGWindowList via Swift to find the window by process name, then
+# screencapture -l <windowID> to capture only that window.
+# Falls back to full-screen capture if the window is not found.
+#
+# Usage:
+#   ./capture-app-window.sh <process_name> <output_path>
+#
+# Arguments:
+#   process_name — The process/owner name as shown in Activity Monitor
+#                  (e.g., "Discord", "Slack", "Telegram", "WeChat", "QQ", "Lark")
+#   output_path  — Path to save the screenshot (e.g., /tmp/screenshot.png)
+#
+# Examples:
+#   ./capture-app-window.sh "Discord" /tmp/discord.png
+#   ./capture-app-window.sh "Slack" /tmp/slack.png
+#   ./capture-app-window.sh "微信" /tmp/wechat.png
+#
+set -euo pipefail
+
+PROCESS="${1:?Usage: capture-app-window.sh <process_name> <output_path>}"
+OUTPUT="${2:?Usage: capture-app-window.sh <process_name> <output_path>}"
+
+# Find the CGWindowID for the target process using Swift + CGWindowList
+# Pass process name via environment variable (swift -e doesn't support -- args)
+WINDOW_ID=$(TARGET_PROCESS="$PROCESS" swift -e '
+import Cocoa
+import Foundation
+let target = ProcessInfo.processInfo.environment["TARGET_PROCESS"] ?? ""
+let windowList = CGWindowListCopyWindowInfo([.optionAll], kCGNullWindowID) as! [[String: Any]]
+for w in windowList {
+    let owner = w["kCGWindowOwnerName"] as? String ?? ""
+    let layer = w["kCGWindowLayer"] as? Int ?? -1
+    let bounds = w["kCGWindowBounds"] as? [String: Any] ?? [:]
+    let ww = bounds["Width"] as? Double ?? 0
+    let wh = bounds["Height"] as? Double ?? 0
+    let wid = w["kCGWindowNumber"] as? Int ?? 0
+    // Match process name, normal window layer (0), and reasonable size
+    if owner == target && layer == 0 && ww > 200 && wh > 200 {
+        print(wid)
+        break
+    }
+}
+' 2>/dev/null || true)
+
+if [ -n "$WINDOW_ID" ]; then
+  screencapture -l "$WINDOW_ID" -x "$OUTPUT"
+else
+  echo "[capture] Warning: Could not find window for '$PROCESS', falling back to full screen"
+  screencapture -x "$OUTPUT"
+fi
@@ -0,0 +1,244 @@
+#!/usr/bin/env bash
+#
+# electron-dev.sh — Manage Electron dev environment for testing
+#
+# Usage:
+#   ./electron-dev.sh start   # Kill existing, start fresh, wait until ready
+#   ./electron-dev.sh stop    # Kill all Electron-related processes
+#   ./electron-dev.sh status  # Check if Electron is running and CDP is reachable
+#   ./electron-dev.sh restart # Stop then start
+#
+# Environment variables:
+#   CDP_PORT          — Chrome DevTools Protocol port (default: 9222)
+#   ELECTRON_LOG      — Log file path (default: /tmp/electron-dev.log)
+#   ELECTRON_WAIT_S   — Max seconds to wait for Electron process (default: 60)
+#   RENDERER_WAIT_S   — Max seconds to wait for renderer/SPA (default: 60)
+#
+set -euo pipefail
+
+CDP_PORT="${CDP_PORT:-9222}"
+ELECTRON_LOG="${ELECTRON_LOG:-/tmp/electron-dev.log}"
+ELECTRON_WAIT_S="${ELECTRON_WAIT_S:-60}"
+RENDERER_WAIT_S="${RENDERER_WAIT_S:-60}"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
+PIDFILE="/tmp/electron-dev-cdp-${CDP_PORT}.pid"
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+# Get the Electron binary path used by this project
+electron_bin_pattern() {
+  echo "${PROJECT_ROOT}/apps/desktop/node_modules/.pnpm/electron@*/node_modules/electron/dist/Electron.app"
+}
+
+# Find all PIDs related to the project's Electron dev session
+find_electron_pids() {
+  local pids=""
+
+  # 1. Main Electron process (launched with --remote-debugging-port)
+  local main_pids
+  main_pids=$(pgrep -f "Electron\.app.*--remote-debugging-port=${CDP_PORT}" 2>/dev/null || true)
+  [ -n "$main_pids" ] && pids="$pids $main_pids"
+
+  # 2. Electron Helper processes (gpu, renderer, utility) spawned from the project's electron binary
+  local helper_pids
+  helper_pids=$(pgrep -f "${PROJECT_ROOT}/apps/desktop/node_modules/.*Electron Helper" 2>/dev/null || true)
+  [ -n "$helper_pids" ] && pids="$pids $helper_pids"
+
+  # 3. electron-vite dev server
+  local vite_pids
+  vite_pids=$(pgrep -f "electron-vite.*dev" 2>/dev/null || true)
+  [ -n "$vite_pids" ] && pids="$pids $vite_pids"
+
+  # 4. PID from pidfile (fallback)
+  if [ -f "$PIDFILE" ]; then
+    local saved_pid
+    saved_pid=$(cat "$PIDFILE")
+    if kill -0 "$saved_pid" 2>/dev/null; then
+      pids="$pids $saved_pid"
+    fi
+  fi
+
+  # Deduplicate
+  echo "$pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ' || true
+}
+
+do_stop() {
+  echo "[electron-dev] Stopping Electron dev environment..."
+
+  local pids
+  pids=$(find_electron_pids)
+
+  if [ -z "$pids" ]; then
+    echo "[electron-dev] No Electron processes found."
+  else
+    echo "[electron-dev] Killing PIDs: $pids"
+    for pid in $pids; do
+      kill "$pid" 2>/dev/null || true
+    done
+
+    # Wait up to 5s for graceful exit, then force-kill survivors
+    local waited=0
+    while [ $waited -lt 5 ]; do
+      local alive=""
+      for pid in $pids; do
+        kill -0 "$pid" 2>/dev/null && alive="$alive $pid"
+      done
+      [ -z "$alive" ] && break
+      sleep 1
+      waited=$((waited + 1))
+    done
+
+    # Force-kill any remaining
+    for pid in $pids; do
+      if kill -0 "$pid" 2>/dev/null; then
+        echo "[electron-dev] Force-killing PID $pid"
+        kill -9 "$pid" 2>/dev/null || true
+      fi
+    done
+  fi
+
+  # Also close any agent-browser sessions connected to this port
+  agent-browser --cdp "$CDP_PORT" close --all 2>/dev/null || true
+
+  rm -f "$PIDFILE"
+  echo "[electron-dev] Stopped."
+}
+
+do_status() {
+  local pids
+  pids=$(find_electron_pids)
+
+  if [ -z "$pids" ]; then
+    echo "[electron-dev] Electron is NOT running."
+    return 1
+  fi
+
+  echo "[electron-dev] Electron is running (PIDs: $pids)"
+
+  # Check CDP connectivity
+  if agent-browser --cdp "$CDP_PORT" get url >/dev/null 2>&1; then
+    local url
+    url=$(agent-browser --cdp "$CDP_PORT" get url 2>&1 | tail -1)
+    echo "[electron-dev] CDP port ${CDP_PORT} is reachable. URL: $url"
+    return 0
+  else
+    echo "[electron-dev] CDP port ${CDP_PORT} is NOT reachable (Electron may still be loading)."
+    return 2
+  fi
+}
+
+wait_for_electron() {
+  echo "[electron-dev] Waiting for Electron process (up to ${ELECTRON_WAIT_S}s)..."
+  local elapsed=0
+  local interval=3
+  while [ $elapsed -lt "$ELECTRON_WAIT_S" ]; do
+    if strings "$ELECTRON_LOG" 2>/dev/null | grep -q "starting electron"; then
+      echo "[electron-dev] Electron process started."
+      return 0
+    fi
+    sleep "$interval"
+    elapsed=$((elapsed + interval))
+    echo "[electron-dev] Still waiting... (${elapsed}/${ELECTRON_WAIT_S}s)"
+  done
+  echo "[electron-dev] ERROR: Electron did not start within ${ELECTRON_WAIT_S}s"
+  echo "[electron-dev] Last 20 lines of log:"
+  tail -20 "$ELECTRON_LOG" 2>/dev/null || true
+  return 1
+}
+
+wait_for_renderer() {
+  echo "[electron-dev] Waiting for renderer/SPA to load (up to ${RENDERER_WAIT_S}s)..."
+
+  # Initial delay — renderer needs time to bootstrap
+  sleep 10
+
+  local elapsed=10
+  local interval=5
+  while [ $elapsed -lt "$RENDERER_WAIT_S" ]; do
+    if agent-browser --cdp "$CDP_PORT" wait 2000 >/dev/null 2>&1; then
+      # Check if interactive elements are present (SPA loaded)
+      local snap
+      snap=$(agent-browser --cdp "$CDP_PORT" snapshot -i 2>&1 || true)
+      if echo "$snap" | grep -qE 'link |button '; then
+        echo "[electron-dev] Renderer ready (interactive elements found)."
+        return 0
+      fi
+    fi
+    sleep "$interval"
+    elapsed=$((elapsed + interval))
+    echo "[electron-dev] SPA still loading... (${elapsed}/${RENDERER_WAIT_S}s)"
+  done
+
+  echo "[electron-dev] WARNING: Timed out waiting for renderer, proceeding anyway."
+  return 0
+}
+
+do_start() {
+  # If already running and healthy, skip
+  local status_ok=0
+  do_status >/dev/null 2>&1 || status_ok=$?
+  if [ "$status_ok" -eq 0 ]; then
+    echo "[electron-dev] Electron is already running and CDP is reachable. Skipping start."
+    echo "[electron-dev] Use 'restart' to force a fresh session, or 'stop' to tear down."
+    return 0
+  fi
+
+  # Clean up any stale processes
+  do_stop
+
+  # Start fresh
+  echo "[electron-dev] Starting Electron dev server..."
+  echo "[electron-dev]   Project: $PROJECT_ROOT"
+  echo "[electron-dev]   CDP port: $CDP_PORT"
+  echo "[electron-dev]   Log: $ELECTRON_LOG"
+
+  : > "$ELECTRON_LOG"  # Truncate log
+
+  (
+    cd "$PROJECT_ROOT/apps/desktop" && \
+    ELECTRON_ENABLE_LOGGING=1 npx electron-vite dev -- --remote-debugging-port="$CDP_PORT" \
+      >> "$ELECTRON_LOG" 2>&1
+  ) &
+  local bg_pid=$!
+  echo "$bg_pid" > "$PIDFILE"
+  echo "[electron-dev] Background PID: $bg_pid"
+
+  # Wait for Electron process to start
+  if ! wait_for_electron; then
+    echo "[electron-dev] Failed to start. Cleaning up..."
+    do_stop
+    return 1
+  fi
+
+  # Wait for renderer to be interactive
+  if ! wait_for_renderer; then
+    echo "[electron-dev] Renderer not ready, but Electron is running. You may need to wait more."
+  fi
+
+  echo "[electron-dev] Ready! Use: agent-browser --cdp $CDP_PORT snapshot -i"
+}
+
+do_restart() {
+  do_stop
+  sleep 2
+  do_start
+}
+
+# ── Main ─────────────────────────────────────────────────────────────
+
+case "${1:-help}" in
+  start)   do_start ;;
+  stop)    do_stop ;;
+  status)  do_status ;;
+  restart) do_restart ;;
+  *)
+    echo "Usage: $0 {start|stop|status|restart}"
+    echo ""
+    echo "  start   — Start Electron dev with CDP (idempotent, skips if already running)"
+    echo "  stop    — Kill all Electron dev processes (main + helpers + vite)"
+    echo "  status  — Check if Electron is running and CDP is reachable"
+    echo "  restart — Stop then start"
+    exit 1
+    ;;
+esac
@@ -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
@@ -0,0 +1,353 @@
+#!/usr/bin/env bash
+#
+# record-electron-demo.sh — Record an automated demo of the Electron app
+#
+# Usage:
+#   ./scripts/record-electron-demo.sh [script.sh] [output.mp4]
+#
+#   script.sh  — A shell script containing agent-browser commands to automate.
+#                It receives the CDP port as $1. Defaults to a built-in queue-edit demo.
+#   output.mp4 — Output file path. Defaults to /tmp/electron-demo.mp4
+#
+# Prerequisites:
+#   - agent-browser CLI installed globally
+#   - ffmpeg installed (brew install ffmpeg)
+#   - Electron app NOT already running (script manages lifecycle)
+#
+# Examples:
+#   # Run built-in demo
+#   ./scripts/record-electron-demo.sh
+#
+#   # Run custom automation script
+#   ./scripts/record-electron-demo.sh ./my-demo.sh /tmp/my-demo.mp4
+#
+set -euo pipefail
+
+CDP_PORT=9222
+DEMO_SCRIPT="${1:-}"
+OUTPUT="${2:-/tmp/electron-demo.mp4}"
+ELECTRON_LOG="/tmp/electron-dev.log"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+RECORD_PID=""
+
+# ── Helpers ──────────────────────────────────────────────────────────
+
+cleanup() {
+  echo "[cleanup] Stopping all processes..."
+  [ -n "$RECORD_PID" ] && kill -INT "$RECORD_PID" 2>/dev/null && sleep 2
+  pkill -f "electron-vite" 2>/dev/null || true
+  pkill -f "Electron" 2>/dev/null || true
+  pkill -f "agent-browser" 2>/dev/null || true
+  echo "[cleanup] Done."
+}
+trap cleanup EXIT
+
+wait_for_electron() {
+  echo "[wait] Waiting for Electron to start..."
+  for i in $(seq 1 24); do
+    sleep 5
+    if strings "$ELECTRON_LOG" 2>/dev/null | grep -q "starting electron"; then
+      echo "[wait] Electron process ready."
+      return 0
+    fi
+    echo "[wait] Still waiting... (${i}/24)"
+  done
+  echo "[error] Electron failed to start within 120s"
+  exit 1
+}
+
+wait_for_renderer() {
+  echo "[wait] Waiting for renderer to load..."
+  sleep 15
+  agent-browser --cdp "$CDP_PORT" wait 3000
+
+  # Poll until interactive elements appear (SPA may take extra time)
+  for i in $(seq 1 12); do
+    local snap
+    snap=$(agent-browser --cdp "$CDP_PORT" snapshot -i 2>&1)
+    if echo "$snap" | grep -q 'link "'; then
+      echo "[wait] Renderer ready (interactive elements found)."
+      return 0
+    fi
+    echo "[wait] SPA still loading... (${i}/12)"
+    sleep 5
+  done
+  echo "[warn] Timed out waiting for interactive elements, proceeding anyway."
+}
+
+get_window_and_screen_info() {
+  # Returns: window_x window_y window_w window_h screen_index
+  # Uses Swift to find the Electron window bounds and which screen it's on
+  swift -e '
+    import Cocoa
+    let windowList = CGWindowListCopyWindowInfo([.optionAll], kCGNullWindowID) as! [[String: Any]]
+    for w in windowList {
+      let owner = w["kCGWindowOwnerName"] as? String ?? ""
+      let name = w["kCGWindowName"] as? String ?? ""
+      let layer = w["kCGWindowLayer"] as? Int ?? -1
+      let bounds = w["kCGWindowBounds"] as? [String: Any] ?? [:]
+      let wx = bounds["X"] as? Double ?? 0
+      let wy = bounds["Y"] as? Double ?? 0
+      let ww = bounds["Width"] as? Double ?? 0
+      let wh = bounds["Height"] as? Double ?? 0
+      if (owner == "Electron" || owner == "LobeHub") && layer == 0 && name == "LobeHub" && ww > 200 && wh > 200 {
+        // Find which screen this window is on
+        let screens = NSScreen.screens
+        var screenIdx = 0
+        let windowCenter = NSPoint(x: wx + ww / 2, y: wy + wh / 2)
+        for (i, screen) in screens.enumerated() {
+          let frame = screen.frame
+          // Convert CG coords (top-left origin) to NSScreen coords (bottom-left origin)
+          let mainHeight = screens[0].frame.height
+          let screenTop = mainHeight - frame.origin.y - frame.height
+          let screenBottom = screenTop + frame.height
+          let screenLeft = frame.origin.x
+          let screenRight = screenLeft + frame.width
+          if windowCenter.x >= screenLeft && windowCenter.x <= screenRight &&
+             windowCenter.y >= screenTop && windowCenter.y <= screenBottom {
+            screenIdx = i
+            break
+          }
+        }
+        // Compute window position relative to the screen it is on
+        let screen = screens[screenIdx]
+        let mainHeight = screens[0].frame.height
+        let screenTop = mainHeight - screen.frame.origin.y - screen.frame.height
+        let relX = wx - screen.frame.origin.x
+        let relY = wy - screenTop
+        let scale = Int(screen.backingScaleFactor)
+        print("\(Int(relX)) \(Int(relY)) \(Int(ww)) \(Int(wh)) \(screenIdx) \(scale)")
+        break
+      }
+    }
+  '
+}
+
+start_recording() {
+  local rel_x=$1 rel_y=$2 w=$3 h=$4 screen_idx=$5 scale=$6
+
+  # ffmpeg avfoundation device index for screens
+  # List devices and find the one matching our screen index
+  local device_idx
+  device_idx=$(ffmpeg -f avfoundation -list_devices true -i "" 2>&1 \
+    | grep "Capture screen ${screen_idx}" \
+    | grep -oE '\[[0-9]+\]' | tr -d '[]' || true)
+
+  if [ -z "$device_idx" ]; then
+    echo "[warn] Could not find capture device for screen $screen_idx, trying default (3)"
+    device_idx=3
+  fi
+
+  # Scale coordinates to native resolution
+  local cx=$((rel_x * scale))
+  local cy=$((rel_y * scale))
+  local cw=$((w * scale))
+  local ch=$((h * scale))
+
+  echo "[record] Window: ${rel_x},${rel_y} ${w}x${h} on screen ${screen_idx} (scale=${scale})"
+  echo "[record] Crop: ${cx},${cy} ${cw}x${ch}, device: ${device_idx}"
+  echo "[record] Output: $OUTPUT"
+
+  ffmpeg -y \
+    -f avfoundation -framerate 30 -capture_cursor 1 -i "${device_idx}:" \
+    -vf "crop=${cw}:${ch}:${cx}:${cy},scale=${w}:${h}" \
+    -c:v libx264 -crf 23 -preset fast -an \
+    "$OUTPUT" \
+    > /tmp/ffmpeg-record.log 2>&1 &
+  RECORD_PID=$!
+  sleep 2
+
+  if ! kill -0 "$RECORD_PID" 2>/dev/null; then
+    echo "[error] ffmpeg failed to start. Log:"
+    cat /tmp/ffmpeg-record.log
+    RECORD_PID=""
+    return 1
+  fi
+  echo "[record] Recording started (PID=$RECORD_PID)"
+}
+
+stop_recording() {
+  if [ -n "$RECORD_PID" ]; then
+    echo "[record] Stopping recording..."
+    kill -INT "$RECORD_PID" 2>/dev/null || true
+    wait "$RECORD_PID" 2>/dev/null || true
+    RECORD_PID=""
+    echo "[record] Saved to $OUTPUT"
+    ls -lh "$OUTPUT"
+  fi
+}
+
+# ── Built-in demo: Queue Edit ────────────────────────────────────────
+
+find_input_ref() {
+  local port=$1
+  agent-browser --cdp "$port" snapshot -i -C 2>&1 \
+    | grep "editable" \
+    | grep -oE 'ref=e[0-9]+' \
+    | head -1 \
+    | sed 's/ref=//'
+}
+
+builtin_demo() {
+  local port=$1
+
+  echo "[demo] Step 1: Navigate to first available agent"
+  local snapshot agent_ref
+  snapshot=$(agent-browser --cdp "$port" snapshot -i 2>&1)
+  # Try Lobe AI first, then fall back to any agent link in the sidebar
+  agent_ref=$(echo "$snapshot" | grep -oE 'link "Lobe AI" \[ref=e[0-9]+\]' | grep -oE 'e[0-9]+' || true)
+  if [ -z "$agent_ref" ]; then
+    # Pick the first agent-like link (skip nav links)
+    agent_ref=$(echo "$snapshot" | grep 'link "' | grep -vE '"Home"|"Pages"|"Settings"|"Search"|"Resources"|"Marketplace"' | head -1 | grep -oE 'ref=e[0-9]+' | sed 's/ref=//' || true)
+  fi
+  if [ -z "$agent_ref" ]; then
+    echo "[error] No agent link found in snapshot"
+    echo "$snapshot" | head -30
+    return 1
+  fi
+  echo "[demo] Clicking agent ref: @$agent_ref"
+  agent-browser --cdp "$port" click "@$agent_ref"
+  sleep 3
+
+  echo "[demo] Step 2: Send first message (triggers AI generation)"
+  local input_ref
+  input_ref=$(find_input_ref "$port")
+  agent-browser --cdp "$port" click "@$input_ref"
+  agent-browser --cdp "$port" type "@$input_ref" "Write a 3000 word essay about the complete history of space exploration from Sputnik to the James Webb Space Telescope"
+  sleep 1
+  agent-browser --cdp "$port" press Enter
+  sleep 3
+
+  echo "[demo] Step 3: Queue message 1"
+  input_ref=$(find_input_ref "$port")
+  agent-browser --cdp "$port" click "@$input_ref"
+  agent-browser --cdp "$port" type "@$input_ref" "This message should be edited"
+  sleep 1
+  agent-browser --cdp "$port" press Enter
+  sleep 1
+
+  echo "[demo] Step 4: Queue message 2"
+  input_ref=$(find_input_ref "$port")
+  agent-browser --cdp "$port" click "@$input_ref"
+  agent-browser --cdp "$port" type "@$input_ref" "Another queued message"
+  sleep 1
+  agent-browser --cdp "$port" press Enter
+  sleep 1
+
+  echo "[demo] Step 5: Verify queue has messages"
+  local queue_count
+  queue_count=$(agent-browser --cdp "$port" eval --stdin << 'EVALEOF'
+(function() {
+  var chat = window.__LOBE_STORES.chat();
+  var total = 0;
+  Object.keys(chat.queuedMessages).forEach(function(k) {
+    total += chat.queuedMessages[k].length;
+  });
+  return String(total);
+})()
+EVALEOF
+  )
+  echo "[demo] Queue count: $queue_count"
+
+  if [ "$queue_count" = "0" ] || [ "$queue_count" = '"0"' ]; then
+    echo "[demo] Queue was already drained. Retrying..."
+    input_ref=$(find_input_ref "$port")
+    agent-browser --cdp "$port" click "@$input_ref"
+    agent-browser --cdp "$port" type "@$input_ref" "Now write another 3000 word essay about artificial intelligence from Turing to transformers covering every major breakthrough"
+    sleep 1
+    agent-browser --cdp "$port" press Enter
+    sleep 2
+    input_ref=$(find_input_ref "$port")
+    agent-browser --cdp "$port" click "@$input_ref"
+    agent-browser --cdp "$port" type "@$input_ref" "This message should be edited"
+    sleep 1
+    agent-browser --cdp "$port" press Enter
+    sleep 1
+    input_ref=$(find_input_ref "$port")
+    agent-browser --cdp "$port" click "@$input_ref"
+    agent-browser --cdp "$port" type "@$input_ref" "Another queued message"
+    sleep 1
+    agent-browser --cdp "$port" press Enter
+    sleep 1
+  fi
+
+  echo "[demo] Step 6: Scroll to show queue tray"
+  agent-browser --cdp "$port" scroll down 5000
+  sleep 2
+
+  echo "[demo] Step 7: Click edit button on first queued message"
+  agent-browser --cdp "$port" eval --stdin << 'EVALEOF'
+(function() {
+  var chat = window.__LOBE_STORES.chat();
+  var keys = Object.keys(chat.queuedMessages);
+  for (var k = 0; k < keys.length; k++) {
+    var queue = chat.queuedMessages[keys[k]];
+    if (queue.length > 0) {
+      var targetText = queue[0].content;
+      var walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT, null);
+      while (walker.nextNode()) {
+        var node = walker.currentNode;
+        if (node.textContent.trim() === targetText) {
+          var row = node.parentElement.parentElement;
+          var buttons = row.querySelectorAll('[role="button"]');
+          if (buttons.length >= 1) {
+            buttons[0].click();
+            return 'clicked edit on: ' + targetText;
+          }
+        }
+      }
+    }
+  }
+  return 'edit button not found';
+})()
+EVALEOF
+  sleep 3
+
+  echo "[demo] Step 8: Show result — content restored to input"
+  sleep 3
+
+  echo "[demo] Complete!"
+}
+
+# ── Main ─────────────────────────────────────────────────────────────
+
+echo "=== Electron Demo Recorder ==="
+
+# 1. Kill existing instances
+echo "[setup] Cleaning up existing processes..."
+pkill -f "Electron" 2>/dev/null || true
+pkill -f "electron-vite" 2>/dev/null || true
+pkill -f "agent-browser" 2>/dev/null || true
+sleep 3
+
+# 2. Start Electron
+echo "[setup] Starting Electron..."
+cd "$PROJECT_ROOT/apps/desktop"
+ELECTRON_ENABLE_LOGGING=1 npx electron-vite dev -- --remote-debugging-port="$CDP_PORT" > "$ELECTRON_LOG" 2>&1 &
+
+wait_for_electron
+wait_for_renderer
+
+# 3. Get window position and start recording
+WIN_INFO=$(get_window_and_screen_info)
+if [ -z "$WIN_INFO" ]; then
+  echo "[error] Could not find Electron window"
+  exit 1
+fi
+read -r WIN_X WIN_Y WIN_W WIN_H SCREEN_IDX SCALE <<< "$WIN_INFO"
+start_recording "$WIN_X" "$WIN_Y" "$WIN_W" "$WIN_H" "$SCREEN_IDX" "$SCALE"
+
+# 4. Run demo script
+if [ -n "$DEMO_SCRIPT" ] && [ -f "$DEMO_SCRIPT" ]; then
+  echo "[demo] Running custom script: $DEMO_SCRIPT"
+  bash "$DEMO_SCRIPT" "$CDP_PORT"
+else
+  echo "[demo] Running built-in queue-edit demo"
+  builtin_demo "$CDP_PORT"
+fi
+
+# 5. Stop recording
+stop_recording
+
+echo "=== Done! Output: $OUTPUT ==="
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# test-discord-bot.sh — Send a message to a Discord bot and capture the response
+#
+# Usage:
+#   ./scripts/test-discord-bot.sh <channel> <message> [wait_seconds] [screenshot_path]
+#
+#   channel         — Channel name to navigate to via Quick Switcher (Cmd+K)
+#   message         — Message to send to the bot
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/discord-bot-test.png)
+#
+# Prerequisites:
+#   - Discord desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Examples:
+#   ./scripts/test-discord-bot.sh "bot-testing" "!ping"
+#   ./scripts/test-discord-bot.sh "bot-testing" "/ask Tell me a joke" 30
+#   ./scripts/test-discord-bot.sh "general" "Hello bot" 15 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CHANNEL="${1:?Usage: test-discord-bot.sh <channel> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-discord-bot.sh <channel> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/discord-bot-test.png}"
+
+APP="Discord"
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Navigating to channel: $CHANNEL"
+osascript -e '
+tell application "System Events"
+    -- Quick Switcher
+    keystroke "k" using command down
+    delay 0.8
+    keystroke "'"$CHANNEL"'"
+    delay 1.5
+    key code 36  -- Enter
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing screenshot..."
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+echo "[$APP] Done! Screenshot saved to $SCREENSHOT"
@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# test-lark-bot.sh — Send a message to a Lark/Feishu bot and capture the response
+#
+# Usage:
+#   ./scripts/test-lark-bot.sh <chat> <message> [wait_seconds] [screenshot_path]
+#
+#   chat            — Chat or contact name to search for
+#   message         — Message to send to the bot
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/lark-bot-test.png)
+#
+# Prerequisites:
+#   - Lark (飞书) desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Notes:
+#   - The app name may be "Lark" or "飞书" depending on version/locale
+#   - Uses Cmd+K to open search/quick switcher
+#   - Enter sends message by default
+#
+# Examples:
+#   ./scripts/test-lark-bot.sh "TestBot" "Hello"
+#   ./scripts/test-lark-bot.sh "bot-testing" "/ask Tell me a joke" 30
+#   ./scripts/test-lark-bot.sh "MyBot" "Help me summarize this" 60 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CHAT="${1:?Usage: test-lark-bot.sh <chat> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-lark-bot.sh <chat> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/lark-bot-test.png}"
+
+# Detect app name — "Lark" or "飞书"
+APP=""
+if osascript -e 'tell application "Lark" to name' &>/dev/null; then
+  APP="Lark"
+elif osascript -e 'tell application "飞书" to name' &>/dev/null; then
+  APP="飞书"
+else
+  echo "[error] Lark/飞书 app not found. Install Lark or 飞书."
+  exit 1
+fi
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Searching for chat: $CHAT"
+osascript -e '
+tell application "System Events"
+    -- Quick Switcher / Search (Cmd+K)
+    keystroke "k" using command down
+    delay 0.8
+end tell
+'
+# Use clipboard for chat name (supports CJK characters)
+osascript -e '
+set the clipboard to "'"$CHAT"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter to select first result
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter to send
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing screenshot..."
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+echo "[$APP] Done! Screenshot saved to $SCREENSHOT"
@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+#
+# test-qq-bot.sh — Send a message to a QQ bot and capture the response
+#
+# Usage:
+#   ./scripts/test-qq-bot.sh <contact> <message> [wait_seconds] [screenshot_path]
+#
+#   contact         — Contact, group, or bot name to search for
+#   message         — Message to send
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/qq-bot-test.png)
+#
+# Prerequisites:
+#   - QQ desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Notes:
+#   - The app name is "QQ"
+#   - Uses Cmd+F to open search
+#   - Enter sends message by default; Shift+Enter for newlines
+#   - Uses clipboard paste for CJK character support
+#
+# Examples:
+#   ./scripts/test-qq-bot.sh "TestBot" "Hello"
+#   ./scripts/test-qq-bot.sh "bot-testing" "Hello bot" 30
+#   ./scripts/test-qq-bot.sh "MyBot" "/help" 15 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONTACT="${1:?Usage: test-qq-bot.sh <contact> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-qq-bot.sh <contact> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/qq-bot-test.png}"
+
+APP="QQ"
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Searching for contact: $CONTACT"
+osascript -e '
+tell application "System Events"
+    -- Search (Cmd+F)
+    keystroke "f" using command down
+    delay 0.8
+end tell
+'
+# Use clipboard for contact name (supports CJK characters)
+osascript -e '
+set the clipboard to "'"$CONTACT"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter to select first result
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter to send
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing screenshot..."
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+echo "[$APP] Done! Screenshot saved to $SCREENSHOT"
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+#
+# test-slack-bot.sh — Send a message to a Slack bot and capture the response
+#
+# Usage:
+#   ./scripts/test-slack-bot.sh <channel> <message> [wait_seconds] [screenshot_path]
+#
+#   channel         — Channel name to navigate to via Quick Switcher (Cmd+K)
+#   message         — Message to send (e.g., "@mybot hello" or "/ask question")
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/slack-bot-test.png)
+#
+# Prerequisites:
+#   - Slack desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Examples:
+#   ./scripts/test-slack-bot.sh "bot-testing" "@mybot hello"
+#   ./scripts/test-slack-bot.sh "bot-testing" "/ask What is 2+2?" 20
+#   ./scripts/test-slack-bot.sh "general" "Hey bot" 15 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CHANNEL="${1:?Usage: test-slack-bot.sh <channel> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-slack-bot.sh <channel> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/slack-bot-test.png}"
+
+APP="Slack"
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Navigating to channel: $CHANNEL"
+osascript -e '
+tell application "System Events"
+    -- Quick Switcher
+    keystroke "k" using command down
+    delay 0.8
+    keystroke "'"$CHANNEL"'"
+    delay 1.5
+    key code 36  -- Enter
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing screenshot..."
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+echo "[$APP] Done! Screenshot saved to $SCREENSHOT"
@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+#
+# test-telegram-bot.sh — Send a message to a Telegram bot and capture the response
+#
+# Usage:
+#   ./scripts/test-telegram-bot.sh <bot_or_chat> <message> [wait_seconds] [screenshot_path]
+#
+#   bot_or_chat     — Bot username or chat name to search for
+#   message         — Message to send to the bot
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/telegram-bot-test.png)
+#
+# Prerequisites:
+#   - Telegram desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Notes:
+#   - The app name may be "Telegram" or "Telegram Desktop" depending on installation
+#   - Uses Cmd+F to search for the bot, then Enter to open the chat
+#
+# Examples:
+#   ./scripts/test-telegram-bot.sh "MyTestBot" "/start"
+#   ./scripts/test-telegram-bot.sh "MyTestBot" "Hello bot" 30
+#   ./scripts/test-telegram-bot.sh "GPTBot" "/ask What is AI?" 60 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+BOT="${1:?Usage: test-telegram-bot.sh <bot_or_chat> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-telegram-bot.sh <bot_or_chat> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/telegram-bot-test.png}"
+
+# Detect app name — "Telegram" or "Telegram Desktop"
+APP=""
+if osascript -e 'tell application "Telegram" to name' &>/dev/null; then
+  APP="Telegram"
+elif osascript -e 'tell application "Telegram Desktop" to name' &>/dev/null; then
+  APP="Telegram Desktop"
+else
+  echo "[error] Telegram app not found. Install Telegram or Telegram Desktop."
+  exit 1
+fi
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Searching for: $BOT"
+osascript -e '
+tell application "System Events"
+    -- Search (Escape first to clear any existing state)
+    key code 53  -- Escape
+    delay 0.3
+    keystroke "f" using command down
+    delay 0.8
+    keystroke "'"$BOT"'"
+    delay 2
+    key code 36  -- Enter to select first result
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing screenshot..."
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+echo "[$APP] Done! Screenshot saved to $SCREENSHOT"
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+#
+# test-wechat-bot.sh — Send a message to a WeChat bot and capture the response
+#
+# Usage:
+#   ./scripts/test-wechat-bot.sh <contact> <message> [wait_seconds] [screenshot_path]
+#
+#   contact         — Contact or bot name to search for
+#   message         — Message to send
+#   wait_seconds    — Seconds to wait for bot response (default: 10)
+#   screenshot_path — Output screenshot path (default: /tmp/wechat-bot-test.png)
+#
+# Prerequisites:
+#   - WeChat (微信) desktop app installed and logged in
+#   - Accessibility permission granted (System Preferences > Privacy > Accessibility)
+#
+# Notes:
+#   - The app name may be "微信" or "WeChat" depending on system language
+#   - WeChat sends on Enter by default; use Shift+Enter for newlines
+#   - For Chinese text, always uses clipboard paste (keystroke can't handle CJK)
+#
+# Examples:
+#   ./scripts/test-wechat-bot.sh "TestBot" "Hello"
+#   ./scripts/test-wechat-bot.sh "文件传输助手" "test message" 5
+#   ./scripts/test-wechat-bot.sh "MyBot" "Tell me a joke" 30 /tmp/my-test.png
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+CONTACT="${1:?Usage: test-wechat-bot.sh <contact> <message> [wait_seconds] [screenshot_path]}"
+MESSAGE="${2:?Usage: test-wechat-bot.sh <contact> <message> [wait_seconds] [screenshot_path]}"
+WAIT="${3:-10}"
+SCREENSHOT="${4:-/tmp/wechat-bot-test.png}"
+
+# Detect app name — "微信" or "WeChat"
+APP=""
+if osascript -e 'tell application "微信" to name' &>/dev/null; then
+  APP="微信"
+elif osascript -e 'tell application "WeChat" to name' &>/dev/null; then
+  APP="WeChat"
+else
+  echo "[error] WeChat app not found. Install 微信 (WeChat)."
+  exit 1
+fi
+
+echo "[$APP] Activating..."
+osascript -e "tell application \"$APP\" to activate"
+sleep 1
+
+echo "[$APP] Searching for contact: $CONTACT"
+osascript -e '
+tell application "System Events"
+    -- Search (Cmd+F)
+    keystroke "f" using command down
+    delay 0.8
+end tell
+'
+# Use clipboard for contact name (supports CJK characters)
+osascript -e '
+set the clipboard to "'"$CONTACT"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 1.5
+    key code 36  -- Enter to select first result
+end tell
+'
+sleep 2
+
+echo "[$APP] Sending message: $MESSAGE"
+# Always use clipboard paste — keystroke can't handle CJK or special characters
+osascript -e '
+set the clipboard to "'"$MESSAGE"'"
+tell application "System Events"
+    keystroke "v" using command down
+    delay 0.3
+    key code 36  -- Enter to send
+end tell
+'
+
+echo "[$APP] Waiting ${WAIT}s for bot response..."
+sleep "$WAIT"
+
+echo "[$APP] Capturing screenshot..."
+"$SCRIPT_DIR/capture-app-window.sh" "$APP" "$SCREENSHOT"
+echo "[$APP] Done! Screenshot saved to $SCREENSHOT"
@@ -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,8 +6,14 @@ 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` > installed packages > `@lobehub/ui` > antd
+- Component priority: `src/components` > `@lobehub/ui/base-ui` > `@lobehub/ui` > custom implementation
+  - Always prefer `@lobehub/ui/base-ui` primitives (Select, Modal, DropdownMenu, Popover, Switch, ScrollArea…) over antd equivalents
+  - Fall back to `@lobehub/ui` higher-level components when base-ui has no match
+  - Only implement a custom component as a last resort — never reach for antd directly
 - Use selectors to access zustand store data

 ## @lobehub/ui Components
@@ -29,9 +35,9 @@ Reference: `node_modules/@lobehub/ui/es/index.mjs` for all available components.

 Hybrid routing: Next.js App Router (static pages) + React Router DOM (main SPA).

-| Route Type         | Use Case                          | Implementation               |
-| ------------------ | --------------------------------- | ---------------------------- |
-| Next.js App Router | Auth pages (login, signup, oauth) | `src/app/[variants]/(auth)/` |
+| Route Type         | Use Case                          | Implementation                                                               |
+| ------------------ | --------------------------------- | ---------------------------------------------------------------------------- |
+| Next.js App Router | Auth pages (login, signup, oauth) | `src/app/[variants]/(auth)/`                                                 |
 | React Router DOM   | Main SPA (chat, settings)         | `desktopRouter.config.tsx` + `desktopRouter.config.desktop.tsx` (must match) |

 ### Key Files
@@ -47,9 +53,9 @@ Hybrid routing: Next.js App Router (static pages) + React Router DOM (main SPA).

 Known pairs that must stay in sync:

-| Base file (web, dynamic imports) | Desktop file (Electron, sync imports) |
-| --- | --- |
-| `src/spa/router/desktopRouter.config.tsx` | `src/spa/router/desktopRouter.config.desktop.tsx` |
+| Base file (web, dynamic imports)                      | Desktop file (Electron, sync imports)                         |
+| ----------------------------------------------------- | ------------------------------------------------------------- |
+| `src/spa/router/desktopRouter.config.tsx`             | `src/spa/router/desktopRouter.config.desktop.tsx`             |
 | `src/routes/(main)/settings/features/componentMap.ts` | `src/routes/(main)/settings/features/componentMap.desktop.ts` |

 **How to check**: After editing any `.ts` / `.tsx` file, run `Glob` for `<filename>.desktop.{ts,tsx}` in the same directory. If a match exists, update it with the equivalent sync-import change.
@@ -61,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',
@@ -162,11 +162,15 @@ describe('ModuleName', () => {
 ### 5. Create Pull Request

 - Create a new branch: `automatic/add-tests-[module-name]-[date]`
+
 - Commit changes with message format:
+
  ```
  ✅ test: add unit tests for [module-name]
  ```
+
 - Push the branch
+
 - Create a PR with:

  - Title: `✅ test: add unit tests for [module-name]`
@@ -198,6 +202,7 @@ describe('ModuleName', () => {
  - Test approach: [brief description]

  ---
+
  🤖 Generated with [Claude Code](https://claude.com/claude-code)
  ```

@@ -77,20 +77,24 @@ Create `e2e/src/features/{module-name}/README.md` with:
 # {Module} 模块 E2E 测试覆盖

 ## 模块概述
+
 **路由**: `/module`, `/module/[id]`

 ## 功能清单与测试覆盖

 ### 1. 功能分组名称

-| 功能点 | 描述 | 优先级 | 状态 | 测试文件 |
-| ------ | ---- | ------ | ---- | -------- |
+| 功能点 | 描述 | 优先级 | 状态 | 测试文件      |
+| ------ | ---- | ------ | ---- | ------------- |
 | 功能A  | xxx  | P0     | ✅   | `xxx.feature` |
-| 功能B  | xxx  | P1     | ⏳   |          |
+| 功能B  | xxx  | P1     | ⏳   |               |

 ## 测试文件结构
+
 ## 测试执行
+
 ## 已知问题
+
 ## 更新记录
 ```

@@ -228,7 +232,7 @@ const testId = pickle.tags.find(
    tag.name.startsWith('@COMMUNITY-') ||
    tag.name.startsWith('@AGENT-') ||
    tag.name.startsWith('@HOME-') ||
-    tag.name.startsWith('@PAGE-') ||    // Add new prefix
+    tag.name.startsWith('@PAGE-') || // Add new prefix
    tag.name.startsWith('@ROUTES-'),
 );
 ```
@@ -300,11 +304,15 @@ HEADLESS=true BASE_URL=http://localhost:3006 \
 ### 10. Create Pull Request

 - Branch name: `test/e2e-{module-name}`
+
 - Commit message format:
+
  ```
  ✅ test: add E2E tests for {module-name}
  ```
+
 - PR title: `✅ test: add E2E tests for {module-name}`
+
 - PR body template:

  ````markdown
@@ -36,6 +36,7 @@ If you detect any leaked secrets, respond IMMEDIATELY with:
 ⚠️ **Security Warning**: Your comment appears to contain sensitive information (API keys, secrets, or credentials).

 **Please delete your comment immediately** to protect your account security, then:
+
 1. Rotate/regenerate any exposed credentials
 2. Re-post your question with secrets redacted (e.g., `AUTH_SECRET=***`)

@@ -73,12 +74,17 @@ Look for the "Troubleshooting" or "FAQ" section in the migration docs and match
 ## Response Guidelines

 1. **Be helpful and friendly** - Users are often frustrated when migration doesn't work
+
 2. **Be specific** - Provide exact commands or configuration examples
+
 3. **Reference documentation** - Point users to relevant docs sections
+
 4. **Ask for logs** - If the issue is unclear, ask for Docker logs:
+
   ```bash
   docker logs <container_name> 2>&1 | tail -100
   ```
+
 5. **One issue at a time** - Focus on solving one problem before moving to the next

 ## Response Format
@@ -90,6 +96,7 @@ Use this format for your responses:

 [If missing information]
 To help you effectively, please provide:
+
 - [List missing items]

 [If you can help]
@@ -102,6 +109,7 @@ Based on your description, here's what I suggest:

 [If the issue is complex or unknown]
 This issue needs further investigation. I've notified the team. In the meantime, please:
+
 1. [Any immediate steps they can try]
 2. Share your Docker logs if you haven't already
 ```
@@ -2,15 +2,15 @@

 ## Quick Reference by Name

- **@arvinxx**: Last resort only, mention for priority:high issues, tool calling , mcp
+- **@arvinxx**: Last resort only, mention for priority:high issues, tool calling, mcp, database
 - **@canisminor1990**: Design, UI components, editor, markdown rendering
- **@tjx666**: Image/video generation, vision, cloud version, documentation, TTS, auth, login/register
- **@ONLY-yours**: Performance, streaming, settings, general bugs, web platform, marketplace
- **@RiverTwilight**: Knowledge base, files (KB-related), group chat
- **@nekomeowww**: Memory, backend, deployment, DevOps
+- **@tjx666**: Image/video generation, vision, cloud version, documentation, TTS, auth, login/register, database
+- **@ONLY-yours**: Performance, streaming, settings, general bugs, web platform, marketplace, agent builder, schedule task
+- **@Innei**: Knowledge base, files (KB-related), group chat, Electron, desktop client, build system
+- **@nekomeowww**: Memory, backend, deployment, DevOps, database
 - **@sudongyuer**: Mobile app (React Native)
 - **@sxjeru**: Model providers and configuration
- **@rdmclin2**: Team workspace
+- **@rdmclin2**: Team workspace, IM and bot integration
 - **@tcmonster**: Subscription, refund, recharge, business cooperation

 Quick reference for assigning issues based on labels.
@@ -28,7 +28,7 @@ Quick reference for assigning issues based on labels.
 | Label              | Owner       | Notes                                  |
 | ------------------ | ----------- | -------------------------------------- |
 | `platform:mobile`  | @sudongyuer | React Native mobile app                |
-| `platform:desktop` | @ONLY-yours | Electron desktop client (general)      |
+| `platform:desktop` | @Innei      | Electron desktop client, build system  |
 | `platform:web`     | @ONLY-yours | Web platform (unless specific feature) |

 ### Feature Labels (feature:\*)
@@ -38,8 +38,8 @@ Quick reference for assigning issues based on labels.
 | `feature:image`          | @tjx666         | AI image generation                                                     |
 | `feature:dalle`          | @tjx666         | DALL-E related                                                          |
 | `feature:vision`         | @tjx666         | Vision/multimodal generation                                            |
-| `feature:knowledge-base` | @RiverTwilight  | Knowledge base and RAG                                                  |
-| `feature:files`          | @RiverTwilight  | File upload/management (when KB-related)<br>@ONLY-yours (general files) |
+| `feature:knowledge-base` | @Innei          | Knowledge base and RAG                                                  |
+| `feature:files`          | @Innei          | File upload/management (when KB-related)<br>@ONLY-yours (general files) |
 | `feature:editor`         | @canisminor1990 | Lobe Editor                                                             |
 | `feature:markdown`       | @canisminor1990 | Markdown rendering                                                      |
 | `feature:auth`           | @tjx666         | Authentication/authorization                                            |
@@ -57,9 +57,12 @@ Quick reference for assigning issues based on labels.
 | `feature:search`         | @ONLY-yours     | Search functionality                                                    |
 | `feature:tts`            | @tjx666         | Text-to-speech                                                          |
 | `feature:export`         | @ONLY-yours     | Export functionality                                                    |
-| `feature:group-chat`     | @RiverTwilight  | Group chat functionality                                                |
+| `feature:group-chat`     | @arvinxx        | Group chat functionality                                                |
 | `feature:memory`         | @nekomeowww     | Memory feature                                                          |
 | `feature:team-workspace` | @rdmclin2       | Team workspace application                                              |
+| `feature:im-integration` | @rdmclin2       | IM and bot integration (Slack, Discord, etc.)                           |
+| `feature:agent-builder`  | @ONLY-yours     | Agent builder                                                           |
+| `feature:schedule-task`  | @ONLY-yours     | Schedule task                                                           |
 | `feature:subscription`   | @tcmonster      | Subscription and billing                                                |
 | `feature:refund`         | @tcmonster      | Refund requests                                                         |
 | `feature:recharge`       | @tcmonster      | Recharge and payment                                                    |
@@ -125,18 +128,18 @@ Quick reference for assigning issues based on labels.

 **Single owner:**

-```
+```plaintext
@username - This is a [feature/component] issue. Please take a look.
 ```

 **Multiple owners:**

-```
+```plaintext
@primary @secondary - This involves [features]. Please coordinate.
 ```

 **High priority:**

-```
+```plaintext
@owner @arvinxx - High priority [feature] issue.
 ```
@@ -72,11 +72,15 @@ Module granularity examples:
 ### 5. Create Pull Request

 - Create a new branch: `automatic/translate-comments-[module-name]-[date]`
+
 - Commit changes with message format:
+
  ```
  🌐 chore: translate non-English comments to English in [module-name]
  ```
+
 - Push the branch
+
 - Create a PR with:

  - Title: `🌐 chore: translate non-English comments to English in [module-name]`
@@ -100,6 +104,7 @@ Module granularity examples:
  `[module-path]`

  ---
+
  🤖 Generated with [Claude Code](https://claude.com/claude-code)
  ```

@@ -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
@@ -9,16 +9,10 @@ inputs:
 runs:
  using: composite
  steps:
-    - name: Install pnpm
-      uses: pnpm/action-setup@v4
-      with:
-        run_install: false
-
-    - name: Setup Node.js
-      uses: actions/setup-node@v6
+    - name: Setup environment
+      uses: ./.github/actions/setup-env
      with:
        node-version: ${{ inputs.node-version }}
-        package-manager-cache: false

    - name: Install dependencies
      shell: bash
@@ -0,0 +1,29 @@
+name: Setup Environment
+description: Setup Node.js, pnpm (install) and Bun (script runner) for workflows
+
+inputs:
+  node-version:
+    description: Node.js version
+    required: false
+    default: '24.11.1'
+  package-manager-cache:
+    description: Pass-through to actions/setup-node package-manager-cache
+    required: false
+    default: 'false'
+
+runs:
+  using: composite
+  steps:
+    - name: Install pnpm
+      uses: pnpm/action-setup@v4
+      with:
+        run_install: false
+
+    - name: Install bun
+      uses: oven-sh/setup-bun@v2
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v6
+      with:
+        node-version: ${{ inputs.node-version }}
+        package-manager-cache: ${{ inputs.package-manager-cache }}
@@ -0,0 +1,13 @@
+AmAzing129
+arvinxx
+canisminor1990
+ilimei
+Innei
+lobehubbot
+nekomeowww
+ONLY-yours
+rdmclin2
+rivertwilight
+sudongyuer
+tcmonster
+tjx666
@@ -3,7 +3,7 @@ name: Daily i18n Update
 on:
  schedule:
    - cron: '0 0 * * *'
-  workflow_dispatch:
+  workflow_dispatch: {}

 # Add permissions configuration
 permissions:
@@ -25,13 +25,11 @@ jobs:
        with:
          ref: ${{ github.event.pull_request.head.ref }}

-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ secrets.BUN_VERSION }}
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
-        run: bun i
+        run: pnpm install

      - name: Update i18n
        run: bun run i18n
@@ -26,8 +26,9 @@ jobs:

      - name: Detect release PR (version from title)
        id: release
+        env:
+          PR_TITLE: ${{ github.event.pull_request.title }}
        run: |
-          PR_TITLE="${{ github.event.pull_request.title }}"
          echo "PR Title: $PR_TITLE"

          # Match "🚀 release: v{x.x.x}" format (strict semver: x.y.z with optional -prerelease or +build)
@@ -44,9 +45,10 @@ jobs:
      - name: Detect patch PR (branch first, title fallback)
        id: patch
        if: steps.release.outputs.should_tag != 'true'
+        env:
+          HEAD_REF: ${{ github.event.pull_request.head.ref }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
        run: |
-          HEAD_REF="${{ github.event.pull_request.head.ref }}"
-          PR_TITLE="${{ github.event.pull_request.title }}"
          echo "Head ref: $HEAD_REF"
          echo "PR Title: $PR_TITLE"

@@ -72,22 +74,13 @@ jobs:
          git checkout main
          git pull --rebase origin main

-      - name: Setup Node.js
+      - name: Setup environment
        if: steps.release.outputs.should_tag == 'true' || steps.patch.outputs.should_tag == 'true'
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24.11.1
-          package-manager-cache: false
-
-      - name: Install bun
-        if: steps.release.outputs.should_tag == 'true' || steps.patch.outputs.should_tag == 'true'
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
+        uses: ./.github/actions/setup-env

      - name: Install deps
        if: steps.release.outputs.should_tag == 'true' || steps.patch.outputs.should_tag == 'true'
-        run: bun i
+        run: pnpm install

      - name: Resolve patch version (patch bump)
        id: patch-version
@@ -1,7 +1,7 @@
 name: Bundle Analyzer

 on:
-  workflow_dispatch:
+  workflow_dispatch: {}

 permissions:
  contents: read
@@ -9,7 +9,6 @@ permissions:

 env:
  NODE_VERSION: 24.11.1
-  BUN_VERSION: 1.2.23

 jobs:
  bundle-analyzer:
@@ -20,19 +19,11 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
        with:
          node-version: ${{ env.NODE_VERSION }}

-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ env.BUN_VERSION }}
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-
      - name: Install dependencies
        run: pnpm i

@@ -51,11 +51,11 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: pnpm install --frozen-lockfile

      - name: Install Playwright browsers (with system deps)
        run: bunx playwright install --with-deps chromium
@@ -29,11 +29,11 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install dependencies
-        run: bun install --frozen-lockfile
+        run: pnpm install --frozen-lockfile

      - name: Configure Git
        run: |
@@ -18,6 +18,16 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

+      - name: Check if author is a team member
+        id: check-team
+        run: |
+          ISSUE_AUTHOR="${{ github.event.issue.user.login }}"
+          if grep -iq "^${ISSUE_AUTHOR}$" .github/maintainers.txt; then
+            echo "is_team=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_team=false" >> "$GITHUB_OUTPUT"
+          fi
+
      - name: Copy triage prompts
        run: |
          mkdir -p /tmp/claude-prompts
@@ -62,7 +72,7 @@ jobs:
            **IMPORTANT**:
            - Follow ALL steps in the issue-triage.md guide
            - Apply labels according to the guide's rules
-            - Post a mention comment to the appropriate team member(s) based on team-assignment.md
+            - ${{ steps.check-team.outputs.is_team == 'true' && 'The issue author is a team member. Do NOT post any @mention comment.' || 'Post a mention comment to the appropriate team member(s) based on team-assignment.md' }}
            - Replace [ISSUE_NUMBER] with: ${{ github.event.issue.number }}

            **Start the triage process now.**
@@ -21,7 +21,18 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

+      - name: Check if author is a team member
+        id: check-team
+        run: |
+          PR_AUTHOR="${{ github.event.pull_request.user.login }}"
+          if grep -iq "^${PR_AUTHOR}$" .github/maintainers.txt; then
+            echo "is_team=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "is_team=false" >> "$GITHUB_OUTPUT"
+          fi
+
      - name: Copy prompts
+        if: steps.check-team.outputs.is_team == 'false'
        run: |
          mkdir -p /tmp/claude-prompts
          cp .claude/prompts/pr-assign.md /tmp/claude-prompts/
@@ -29,6 +40,7 @@ jobs:
          cp .claude/prompts/security-rules.md /tmp/claude-prompts/

      - name: Run Claude Code for PR Reviewer Assignment
+        if: steps.check-team.outputs.is_team == 'false'
        uses: anthropics/claude-code-action@v1
        with:
          github_token: ${{ secrets.GH_TOKEN }}
@@ -55,5 +55,5 @@ jobs:
          # Security: Allow only specific safe commands - no gh commands to prevent token exfiltration
          # These tools are restricted to code analysis and build operations only
          claude_args: |
-            --allowedTools "Bash(git:*),Bash(gh:*),Bash(bun run:*),Bash(pnpm run:*),Bash(npm run:*),Bash(npx:*),Bash(bunx:*),Bash(vitest:*),Bash(rg:*),Bash(find:*),Bash(sed:*),Bash(grep:*),Bash(awk:*),Bash(wc:*),Bash(xargs:*)"
+            --allowedTools "Bash(git:*),Bash(gh:*),Bash(bun run:*),Bash(bunx:*),Bash(pnpm:*),Bash(npm run:*),Bash(npx:*),Bash(vitest:*),Bash(rg:*),Bash(find:*),Bash(sed:*),Bash(grep:*),Bash(awk:*),Bash(wc:*),Bash(xargs:*)"
            --append-system-prompt "$(cat /tmp/claude-prompts/security-rules.md)"
@@ -61,13 +61,11 @@ jobs:
      - name: Checkout
        uses: actions/checkout@v6

-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

-      - name: Install dependencies (bun)
-        run: bun install
+      - name: Install dependencies
+        run: pnpm install

      - name: Install Playwright browsers (with system deps)
        run: bunx playwright install --with-deps chromium
@@ -3,7 +3,7 @@ description: Auto-closes issues that are duplicates of existing issues
 on:
  schedule:
    - cron: '0 2 * * *'
-  workflow_dispatch:
+  workflow_dispatch: {}

 jobs:
  auto-close-duplicates:
@@ -17,10 +17,11 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
+
+      - name: Install dependencies
+        run: pnpm install

      - name: Auto-close duplicate issues
        run: bun run .github/scripts/auto-close-duplicates.ts
@@ -28,9 +28,21 @@ jobs:
            ✅ @{{ author }}

            This issue is closed, If you have any questions, you can comment and reply.
+      - name: Checkout repository
+        if: github.event_name == 'pull_request_target' && github.event.pull_request.merged == true
+        uses: actions/checkout@v4
+
+      - name: Check if PR author is maintainer
+        if: github.event.pull_request.merged == true
+        id: maintainer-check
+        run: |
+          if [ -f .github/maintainers.txt ] && grep -qx "${{ github.event.pull_request.user.login }}" .github/maintainers.txt; then
+            echo "skip=true" >> $GITHUB_OUTPUT
+          fi
+
      - name: Auto Comment on Pull Request Merged
        uses: actions-cool/pr-welcome@main
-        if: github.event.pull_request.merged == true
+        if: github.event.pull_request.merged == true && steps.maintainer-check.outputs.skip != 'true'
        with:
          token: ${{ secrets.GH_TOKEN }}
          comment: |
@@ -6,10 +6,10 @@ on:
      channel:
        description: 'Release channel for desktop build (affects version suffix and workflow:set-desktop-version)'
        required: true
-        default: nightly
+        default: canary
        type: choice
        options:
-          - nightly
+          - canary
          - beta
          - stable
      build_macos:
@@ -41,7 +41,6 @@ permissions:

 env:
  NODE_VERSION: 24.11.1
-  BUN_VERSION: 1.2.23

 jobs:
  version:
@@ -102,18 +101,10 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - name: Setup Node & pnpm
-        uses: ./.github/actions/setup-node-pnpm
+      - name: Setup build environment
+        uses: ./.github/actions/desktop-build-setup
        with:
          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: 'false'
-
-      # node-linker=hoisted 模式将可以确保 asar 压缩可用
-      - name: Install dependencies
-        run: |
-          pnpm install --node-linker=hoisted &
-          npm run install-isolated --prefix=./apps/desktop &
-          wait

      - name: Set package version
        run: npm run workflow:set-desktop-version ${{ needs.version.outputs.version }} ${{ inputs.channel }}
@@ -127,8 +118,8 @@ jobs:
          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
          CSC_LINK: ${{ secrets.APPLE_CERTIFICATE_BASE64 }}
          CSC_KEY_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
-          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ inputs.channel == 'beta' && secrets.UMAMI_BETA_DESKTOP_PROJECT_ID || secrets.UMAMI_NIGHTLY_DESKTOP_PROJECT_ID }}
-          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ inputs.channel == 'beta' && secrets.UMAMI_BETA_DESKTOP_BASE_URL || secrets.UMAMI_NIGHTLY_DESKTOP_BASE_URL }}
+          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ inputs.channel == 'stable' && secrets.UMAMI_STABLE_DESKTOP_PROJECT_ID || secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
+          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ inputs.channel == 'stable' && secrets.UMAMI_STABLE_DESKTOP_BASE_URL || secrets.UMAMI_BETA_DESKTOP_BASE_URL }}
          CSC_FOR_PULL_REQUEST: true
          APPLE_ID: ${{ secrets.APPLE_ID }}
          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
@@ -193,8 +184,8 @@ jobs:
          APP_URL: http://localhost:3015
          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
-          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ inputs.channel == 'beta' && secrets.UMAMI_BETA_DESKTOP_PROJECT_ID || secrets.UMAMI_NIGHTLY_DESKTOP_PROJECT_ID }}
-          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ inputs.channel == 'beta' && secrets.UMAMI_BETA_DESKTOP_BASE_URL || secrets.UMAMI_NIGHTLY_DESKTOP_BASE_URL }}
+          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ inputs.channel == 'stable' && secrets.UMAMI_STABLE_DESKTOP_PROJECT_ID || secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
+          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ inputs.channel == 'stable' && secrets.UMAMI_STABLE_DESKTOP_BASE_URL || secrets.UMAMI_BETA_DESKTOP_BASE_URL }}
          TEMP: C:\temp
          TMP: C:\temp

@@ -222,17 +213,10 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - name: Setup Node & pnpm
-        uses: ./.github/actions/setup-node-pnpm
+      - name: Setup build environment
+        uses: ./.github/actions/desktop-build-setup
        with:
          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: 'false'
-
-      - name: Install dependencies
-        run: |
-          pnpm install --node-linker=hoisted &
-          npm run install-isolated --prefix=./apps/desktop &
-          wait

      - name: Set package version
        run: npm run workflow:set-desktop-version ${{ needs.version.outputs.version }} ${{ inputs.channel }}
@@ -244,8 +228,8 @@ jobs:
          APP_URL: http://localhost:3015
          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
-          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ inputs.channel == 'beta' && secrets.UMAMI_BETA_DESKTOP_PROJECT_ID || secrets.UMAMI_NIGHTLY_DESKTOP_PROJECT_ID }}
-          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ inputs.channel == 'beta' && secrets.UMAMI_BETA_DESKTOP_BASE_URL || secrets.UMAMI_NIGHTLY_DESKTOP_BASE_URL }}
+          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ inputs.channel == 'stable' && secrets.UMAMI_STABLE_DESKTOP_PROJECT_ID || secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
+          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ inputs.channel == 'stable' && secrets.UMAMI_STABLE_DESKTOP_BASE_URL || secrets.UMAMI_BETA_DESKTOP_BASE_URL }}

      - name: Upload artifact
        uses: actions/upload-artifact@v6
@@ -274,12 +258,10 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Node & Bun
-        uses: ./.github/actions/setup-node-bun
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
        with:
          node-version: ${{ env.NODE_VERSION }}
-          bun-version: ${{ env.BUN_VERSION }}
-          package-manager-cache: 'false'

      - name: Download artifacts
        uses: actions/download-artifact@v7
@@ -27,15 +27,11 @@ jobs:
      - name: Checkout base
        uses: actions/checkout@v6

-      - name: Setup Node & Bun
-        uses: ./.github/actions/setup-node-bun
-        with:
-          node-version: 24.11.1
-          bun-version: latest
-          package-manager-cache: 'false'
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
-        run: bun i
+        run: pnpm install
        env:
          NODE_OPTIONS: --max-old-space-size=8192

@@ -93,29 +89,10 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - name: Setup Node & pnpm
-        uses: ./.github/actions/setup-node-pnpm
+      - name: Setup build environment
+        uses: ./.github/actions/desktop-build-setup
        with:
          node-version: 24.11.1
-          package-manager-cache: 'false'
-
-      # node-linker=hoisted 模式将可以确保 asar 压缩可用
-      - name: Install dependencies
-        run: pnpm install --node-linker=hoisted
-
-      # 移除国内 electron 镜像配置，GitHub Actions 使用官方源更快
-      - name: Remove China electron mirror from .npmrc
-        shell: bash
-        run: |
-          NPMRC_FILE="./apps/desktop/.npmrc"
-          if [ -f "$NPMRC_FILE" ]; then
-            sed -i.bak '/^electron_mirror=/d; /^electron_builder_binaries_mirror=/d' "$NPMRC_FILE"
-            rm -f "${NPMRC_FILE}.bak"
-            echo "✅ Removed electron mirror config from .npmrc"
-          fi
-
-      - name: Install deps on Desktop
-        run: npm run install-isolated --prefix=./apps/desktop

      # 设置 package.json 的版本号
      - name: Set package version
@@ -228,12 +205,8 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Node & Bun
-        uses: ./.github/actions/setup-node-bun
-        with:
-          node-version: 24.11.1
-          bun-version: latest
-          package-manager-cache: 'false'
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      # 下载所有平台的构建产物
      - name: Download artifacts
@@ -251,13 +224,11 @@ jobs:
      - name: Install yaml only for merge step
        run: |
          cd scripts/electronWorkflow
-          # 在脚本目录创建最小 package.json，防止 bun 向上寻找根 package.json
          if [ ! -f package.json ]; then
            echo '{"name":"merge-mac-release","private":true}' > package.json
          fi
          bun add --no-save yaml@2.8.1

-      # 合并 macOS YAML 文件 (使用 bun 运行 JavaScript)
      - name: Merge latest-mac.yml files
        run: bun run scripts/electronWorkflow/mergeMacReleaseFiles.js

@@ -7,7 +7,7 @@ name: Release Desktop Beta
 # 如: v2.0.0-beta.1, v2.0.0-alpha.1, v2.0.0-rc.1
 #
 # 注意: Stable 版本 (如 v2.0.0) 由 release-desktop-stable.yml 处理
-# 注意: Nightly 版本 (如 v2.1.0-nightly.xxx) 由 release-desktop-nightly.yml 处理
+# 注意: Nightly 版本已停用，不再参与 Desktop 发布流程
 # ============================================

 on:
@@ -41,10 +41,10 @@ jobs:
          version="${version#v}"
          echo "version=${version}" >> $GITHUB_OUTPUT

-          # Beta 版本包含 beta/alpha/rc (nightly 由 release-desktop-nightly.yml 处理)
+          # Beta 版本包含 beta/alpha/rc；nightly 标签已停用
          if [[ "$version" == *"nightly"* ]]; then
            echo "is_beta=false" >> $GITHUB_OUTPUT
-            echo "⏭️ Skipping: $version is a nightly release (handled by release-desktop-nightly.yml)"
+            echo "⏭️ Skipping: $version is a disabled nightly release tag"
          elif [[ "$version" == *"beta"* ]] || [[ "$version" == *"alpha"* ]] || [[ "$version" == *"rc"* ]]; then
            echo "is_beta=true" >> $GITHUB_OUTPUT
            echo "✅ Beta release detected: $version"
@@ -62,19 +62,13 @@ jobs:
      - name: Checkout base
        uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
        with:
          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest

      - name: Install deps
-        run: bun i
+        run: pnpm install

      - name: Lint
        run: bun run lint
@@ -168,16 +162,10 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
        with:
          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest

      # 下载所有平台的构建产物
      - name: Download artifacts
@@ -195,13 +183,11 @@ jobs:
      - name: Install yaml only for merge step
        run: |
          cd scripts/electronWorkflow
-          # 在脚本目录创建最小 package.json，防止 bun 向上寻找根 package.json
          if [ ! -f package.json ]; then
            echo '{"name":"merge-mac-release","private":true}' > package.json
          fi
          bun add --no-save yaml@2.8.1

-      # 合并 macOS YAML 文件 (使用 bun 运行 JavaScript)
      - name: Merge latest-mac.yml files
        run: bun run scripts/electronWorkflow/mergeMacReleaseFiles.js

@@ -45,6 +45,7 @@ jobs:
    name: Calculate Canary Version
    runs-on: ubuntu-latest
    outputs:
+      release_notes: ${{ steps.release-notes.outputs.release_notes }}
      version: ${{ steps.version.outputs.version }}
      tag: ${{ steps.version.outputs.tag }}
      should_build: ${{ steps.check.outputs.should_build }}
@@ -121,6 +122,66 @@ jobs:
          echo "✅ Canary version: ${version}"
          echo "🏷️ Tag: ${tag}"

+      - name: Generate canary release notes
+        if: steps.check.outputs.should_build == 'true'
+        id: release-notes
+        env:
+          TAG: ${{ steps.version.outputs.tag }}
+        run: |
+          previous_canary=$(git tag --sort=-creatordate | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-canary\.[0-9]+$' | head -n 1)
+          latest_stable=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)
+
+          if [ -n "$previous_canary" ]; then
+            compare_from="$previous_canary"
+            compare_range="${previous_canary}..HEAD"
+          elif [ -n "$latest_stable" ]; then
+            compare_from="$latest_stable"
+            compare_range="${latest_stable}..HEAD"
+          else
+            compare_from="initial commit"
+            compare_range="HEAD"
+          fi
+
+          commit_count=$(git rev-list --count "$compare_range")
+          commits=$(git log --no-merges --pretty='- `%h` %s (%an)' "$compare_range")
+
+          if [ -z "$commits" ]; then
+            commits='- No new commits recorded.'
+          fi
+
+          {
+            echo "release_notes<<EOF"
+            echo "## 🐤 Canary Build — ${TAG}"
+            echo
+            echo "> Automated canary build from \`canary\` branch."
+            echo
+            echo "### Commit Information"
+            echo
+            echo "- Based on changes since \`${compare_from}\`"
+            echo "- Commit count: ${commit_count}"
+            echo
+            printf '%s\n' "$commits"
+            echo
+            echo "### ⚠️ Important Notes"
+            echo
+            echo "- **This is an automated canary build and is NOT intended for production use.**"
+            echo "- Canary builds are triggered by \`build\`/\`fix\`/\`style\` commits on the \`canary\` branch."
+            echo "- May contain **unstable or incomplete changes**. **Use at your own risk.**"
+            echo "- It is strongly recommended to **back up your data** before using a canary build."
+            echo
+            echo "### 📦 Installation"
+            echo
+            echo "Download the appropriate installer for your platform from the assets below."
+            echo
+            echo "| Platform | File |"
+            echo "|----------|------|"
+            echo "| macOS (Apple Silicon) | \`.dmg\` (arm64) |"
+            echo "| macOS (Intel) | \`.dmg\` (x64) |"
+            echo "| Windows | \`.exe\` |"
+            echo "| Linux | \`.AppImage\` / \`.deb\` |"
+            echo "EOF"
+          } >> $GITHUB_OUTPUT
+
  # ============================================
  # 代码质量检查
  # ============================================
@@ -133,19 +194,13 @@ jobs:
      - name: Checkout base
        uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
        with:
          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest

      - name: Install deps
-        run: bun i
+        run: pnpm install

      - name: Lint
        run: bun run lint
@@ -188,6 +243,7 @@ jobs:
        env:
          UPDATE_CHANNEL: canary
          UPDATE_SERVER_URL: ${{ secrets.UPDATE_SERVER_URL }}
+          RELEASE_NOTES: ${{ needs.calculate-version.outputs.release_notes }}
          APP_URL: http://localhost:3015
          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
@@ -207,6 +263,7 @@ jobs:
        env:
          UPDATE_CHANNEL: canary
          UPDATE_SERVER_URL: ${{ secrets.UPDATE_SERVER_URL }}
+          RELEASE_NOTES: ${{ needs.calculate-version.outputs.release_notes }}
          APP_URL: http://localhost:3015
          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
@@ -222,6 +279,7 @@ jobs:
        env:
          UPDATE_CHANNEL: canary
          UPDATE_SERVER_URL: ${{ secrets.UPDATE_SERVER_URL }}
+          RELEASE_NOTES: ${{ needs.calculate-version.outputs.release_notes }}
          APP_URL: http://localhost:3015
          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
@@ -247,16 +305,10 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
        with:
          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest

      - name: Download artifacts
        uses: actions/download-artifact@v7
@@ -311,28 +363,7 @@ jobs:
          tag_name: ${{ needs.calculate-version.outputs.tag }}
          name: 'Desktop Canary ${{ needs.calculate-version.outputs.tag }}'
          prerelease: true
-          body: |
-            ## 🐤 Canary Build — ${{ needs.calculate-version.outputs.tag }}
-
-            > Automated canary build from `canary` branch.
-
-            ### ⚠️ Important Notes
-
-            - **This is an automated canary build and is NOT intended for production use.**
-            - Canary builds are triggered by `build`/`fix`/`style` commits on the `canary` branch.
-            - May contain **unstable or incomplete changes**. **Use at your own risk.**
-            - It is strongly recommended to **back up your data** before using a canary build.
-
-            ### 📦 Installation
-
-            Download the appropriate installer for your platform from the assets below.
-
-            | Platform | File |
-            |----------|------|
-            | macOS (Apple Silicon) | `.dmg` (arm64) |
-            | macOS (Intel) | `.dmg` (x64) |
-            | Windows | `.exe` |
-            | Linux | `.AppImage` / `.deb` |
+          body: ${{ needs.calculate-version.outputs.release_notes }}
          files: |
            release/latest*
            release/*.dmg*
@@ -1,427 +0,0 @@
-name: Release Desktop Nightly
-
-# ============================================
-# Nightly 自动发版工作流
-# ============================================
-# 触发条件:
-#   1. 定时: 每天 UTC+8 14:00 (UTC 06:00)
-#   2. 手动触发 (workflow_dispatch)
-#
-# 版本策略:
-#   基于最新 tag 的 minor+1, 格式: X.(Y+1).0-nightly.YYYYMMDDHHMM
-#   例: 当前 tag v2.0.12 → v2.1.0-nightly.202502091400
-#   使用精确到分钟的时间戳避免同一天多次触发时 tag 冲突
-# ============================================
-
-on:
-  schedule:
-    - cron: '0 6 * * *'
-  workflow_dispatch:
-    inputs:
-      force:
-        description: 'Force build (skip diff check)'
-        required: false
-        type: boolean
-        default: false
-
-concurrency:
-  group: ${{ github.workflow }}
-  cancel-in-progress: true
-
-permissions: read-all
-
-env:
-  NODE_VERSION: '24.11.1'
-
-jobs:
-  # ============================================
-  # 计算 Nightly 版本号
-  # ============================================
-  calculate-version:
-    name: Calculate Nightly Version
-    runs-on: ubuntu-latest
-    outputs:
-      version: ${{ steps.version.outputs.version }}
-      tag: ${{ steps.version.outputs.tag }}
-      has_changes: ${{ steps.changes.outputs.has_changes }}
-    steps:
-      - uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Check for code changes since last nightly
-        id: changes
-        run: |
-          # 手动触发 + force 时跳过 diff 检查
-          if [ "${{ inputs.force }}" == "true" ]; then
-            echo "has_changes=true" >> $GITHUB_OUTPUT
-            echo "🔧 Force build requested, skipping diff check"
-            exit 0
-          fi
-
-          # 查找上一个 nightly tag
-          last_nightly=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+-nightly\.' | head -n 1)
-
-          if [ -z "$last_nightly" ]; then
-            echo "has_changes=true" >> $GITHUB_OUTPUT
-            echo "📦 No previous nightly tag found, proceeding with first nightly build"
-            exit 0
-          fi
-
-          echo "📌 Last nightly tag: $last_nightly"
-
-          # 对比指定目录是否有变更
-          changes=$(git diff --name-only "$last_nightly"..HEAD -- package.json src/ packages/ apps/desktop/)
-
-          if [ -z "$changes" ]; then
-            echo "has_changes=false" >> $GITHUB_OUTPUT
-            echo "⏭️ No code changes since $last_nightly, skipping nightly build"
-          else
-            echo "has_changes=true" >> $GITHUB_OUTPUT
-            change_count=$(echo "$changes" | wc -l | tr -d ' ')
-            echo "✅ ${change_count} file(s) changed since $last_nightly:"
-            echo "$changes" | head -20
-            [ "$change_count" -gt 20 ] && echo "  ... and $((change_count - 20)) more"
-          fi
-
-      - name: Calculate nightly version
-        if: steps.changes.outputs.has_changes == 'true'
-        id: version
-        run: |
-          # 获取最新的 tag (排除 nightly tag)
-          latest_tag=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+$' | head -n 1)
-
-          if [ -z "$latest_tag" ]; then
-            echo "❌ No stable tag found"
-            exit 1
-          fi
-
-          echo "📌 Latest stable tag: $latest_tag"
-
-          # 去掉 v 前缀
-          base_version="${latest_tag#v}"
-
-          # 解析 major.minor.patch
-          IFS='.' read -r major minor patch <<< "$base_version"
-
-          # minor + 1, patch 归零
-          new_minor=$((minor + 1))
-          timestamp=$(date -u +"%Y%m%d%H%M")
-
-          version="${major}.${new_minor}.0-nightly.${timestamp}"
-          tag="v${version}"
-
-          echo "version=${version}" >> $GITHUB_OUTPUT
-          echo "tag=${tag}" >> $GITHUB_OUTPUT
-          echo "✅ Nightly version: ${version}"
-          echo "🏷️ Tag: ${tag}"
-
-  # ============================================
-  # 代码质量检查
-  # ============================================
-  test:
-    name: Code quality check
-    needs: [calculate-version]
-    if: needs.calculate-version.outputs.has_changes == 'true'
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout base
-        uses: actions/checkout@v6
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Install deps
-        run: bun i
-
-      - name: Lint
-        run: bun run lint
-
-  # ============================================
-  # 多平台构建
-  # ============================================
-  build:
-    needs: [calculate-version, test]
-    if: needs.calculate-version.outputs.has_changes == 'true'
-    name: Build Desktop App
-    runs-on: ${{ matrix.os }}
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [macos-15, macos-15-intel, windows-2025, ubuntu-latest]
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Setup build environment
-        uses: ./.github/actions/desktop-build-setup
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-
-      - name: Set package version
-        run: npm run workflow:set-desktop-version ${{ needs.calculate-version.outputs.version }} nightly
-
-      # macOS 构建前清理 (修复 hdiutil 问题 https://github.com/electron-userland/electron-builder/issues/8415)
-      - name: Clean previous build artifacts (macOS)
-        if: runner.os == 'macOS'
-        run: |
-          sudo rm -rf apps/desktop/release || true
-          sudo rm -rf apps/desktop/dist || true
-          sudo rm -rf /tmp/electron-builder* || true
-
-      # macOS 构建
-      - name: Build artifact on macOS
-        if: runner.os == 'macOS'
-        run: npm run desktop:package:app
-        env:
-          UPDATE_CHANNEL: nightly
-          UPDATE_SERVER_URL: ${{ secrets.UPDATE_SERVER_URL }}
-          APP_URL: http://localhost:3015
-          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
-          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
-          CSC_LINK: ${{ secrets.APPLE_CERTIFICATE_BASE64 }}
-          CSC_KEY_PASSWORD: ${{ secrets.APPLE_CERTIFICATE_PASSWORD }}
-          CSC_FOR_PULL_REQUEST: true
-          APPLE_ID: ${{ secrets.APPLE_ID }}
-          APPLE_APP_SPECIFIC_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
-          APPLE_TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
-          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
-          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ secrets.UMAMI_BETA_DESKTOP_BASE_URL }}
-
-      # Windows 构建
-      - name: Build artifact on Windows
-        if: runner.os == 'Windows'
-        run: npm run desktop:package:app
-        env:
-          UPDATE_CHANNEL: nightly
-          UPDATE_SERVER_URL: ${{ secrets.UPDATE_SERVER_URL }}
-          APP_URL: http://localhost:3015
-          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
-          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
-          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
-          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ secrets.UMAMI_BETA_DESKTOP_BASE_URL }}
-          TEMP: C:\temp
-          TMP: C:\temp
-
-      # Linux 构建
-      - name: Build artifact on Linux
-        if: runner.os == 'Linux'
-        run: npm run desktop:package:app
-        env:
-          UPDATE_CHANNEL: nightly
-          UPDATE_SERVER_URL: ${{ secrets.UPDATE_SERVER_URL }}
-          APP_URL: http://localhost:3015
-          DATABASE_URL: 'postgresql://postgres@localhost:5432/postgres'
-          KEY_VAULTS_SECRET: 'oLXWIiR/AKF+rWaqy9lHkrYgzpATbW3CtJp3UfkVgpE='
-          NEXT_PUBLIC_DESKTOP_PROJECT_ID: ${{ secrets.UMAMI_BETA_DESKTOP_PROJECT_ID }}
-          NEXT_PUBLIC_DESKTOP_UMAMI_BASE_URL: ${{ secrets.UMAMI_BETA_DESKTOP_BASE_URL }}
-
-      - name: Upload artifacts
-        uses: ./.github/actions/desktop-upload-artifacts
-        with:
-          artifact-name: release-${{ matrix.os }}
-          retention-days: 3
-
-  # ============================================
-  # 合并 macOS 多架构 latest-mac.yml 文件
-  # ============================================
-  merge-mac-files:
-    needs: [build]
-    name: Merge macOS Release Files
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v6
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
-
-      - name: Download artifacts
-        uses: actions/download-artifact@v7
-        with:
-          path: release
-          pattern: release-*
-          merge-multiple: true
-
-      - name: List downloaded artifacts
-        run: ls -R release
-
-      - name: Install yaml only for merge step
-        run: |
-          cd scripts/electronWorkflow
-          if [ ! -f package.json ]; then
-            echo '{"name":"merge-mac-release","private":true}' > package.json
-          fi
-          bun add --no-save yaml@2.8.1
-
-      - name: Merge latest-mac.yml files
-        run: bun run scripts/electronWorkflow/mergeMacReleaseFiles.js
-
-      - name: Upload artifacts with merged macOS files
-        uses: actions/upload-artifact@v6
-        with:
-          name: merged-release
-          path: release/
-          retention-days: 1
-
-  # ============================================
-  # 创建 Nightly Release
-  # ============================================
-  publish-release:
-    needs: [merge-mac-files, calculate-version]
-    name: Publish Nightly Release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - name: Download merged artifacts
-        uses: actions/download-artifact@v7
-        with:
-          name: merged-release
-          path: release
-
-      - name: List final artifacts
-        run: ls -R release
-
-      - name: Create Nightly Release
-        uses: softprops/action-gh-release@v1
-        with:
-          tag_name: ${{ needs.calculate-version.outputs.tag }}
-          name: 'Desktop Nightly ${{ needs.calculate-version.outputs.tag }}'
-          prerelease: true
-          body: |
-            ## 🌙 Nightly Build — ${{ needs.calculate-version.outputs.tag }}
-
-            > Automated nightly build from `main` branch.
-
-            ### ⚠️ Important Notes
-
-            - **This is an automated nightly build and is NOT intended for production use.**
-            - Nightly builds are generated from the latest `main` branch and may contain **unstable, untested, or incomplete features**.
-            - **No guarantees** are made regarding stability, data integrity, or backward compatibility.
-            - Bugs, crashes, and breaking changes are expected. **Use at your own risk.**
-            - **Do NOT report bugs** from nightly builds unless you can reproduce them on the latest beta or stable release.
-            - Nightly builds may have **different update channels** — they will not auto-update to/from stable or beta versions.
-            - It is strongly recommended to **back up your data** before using a nightly build.
-
-            ### 📦 Installation
-
-            Download the appropriate installer for your platform from the assets below.
-
-            | Platform | File |
-            |----------|------|
-            | macOS (Apple Silicon) | `.dmg` (arm64) |
-            | macOS (Intel) | `.dmg` (x64) |
-            | Windows | `.exe` |
-            | Linux | `.AppImage` / `.deb` |
-          files: |
-            release/latest*
-            release/*.dmg*
-            release/*.zip*
-            release/*.exe*
-            release/*.AppImage
-            release/*.deb*
-            release/*.snap*
-            release/*.rpm*
-            release/*.tar.gz*
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-  # ============================================
-  # 发布到 S3 更新服务器
-  # ============================================
-  publish-s3:
-    needs: [merge-mac-files, calculate-version]
-    name: Publish to S3
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: ./.github/actions/desktop-publish-s3
-        with:
-          channel: nightly
-          version: ${{ needs.calculate-version.outputs.version }}
-          aws-access-key-id: ${{ secrets.UPDATE_AWS_ACCESS_KEY_ID }}
-          aws-secret-access-key: ${{ secrets.UPDATE_AWS_SECRET_ACCESS_KEY }}
-          s3-bucket: ${{ secrets.UPDATE_S3_BUCKET }}
-          s3-region: ${{ secrets.UPDATE_S3_REGION }}
-          s3-endpoint: ${{ secrets.UPDATE_S3_ENDPOINT }}
-
-  # ============================================
-  # 清理旧的 Nightly Releases (保留最近 7 个)
-  # ============================================
-  cleanup-old-nightlies:
-    needs: [publish-release, publish-s3]
-    name: Cleanup Old Nightly Releases
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-    steps:
-      - uses: actions/checkout@v6
-
-      - name: Delete old nightly GitHub releases
-        uses: actions/github-script@v7
-        with:
-          script: |
-            const { data: releases } = await github.rest.repos.listReleases({
-              owner: context.repo.owner,
-              repo: context.repo.repo,
-              per_page: 100,
-            });
-
-            const nightlyReleases = releases
-              .filter(r => r.tag_name.includes('-nightly.'))
-              .sort((a, b) => new Date(b.created_at) - new Date(a.created_at));
-
-            const toDelete = nightlyReleases.slice(7);
-
-            for (const release of toDelete) {
-              console.log(`🗑️ Deleting old nightly release: ${release.tag_name}`);
-
-              // Delete the release
-              await github.rest.repos.deleteRelease({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                release_id: release.id,
-              });
-
-              // Delete the tag
-              try {
-                await github.rest.git.deleteRef({
-                  owner: context.repo.owner,
-                  repo: context.repo.repo,
-                  ref: `tags/${release.tag_name}`,
-                });
-              } catch (e) {
-                console.log(`⚠️ Could not delete tag ${release.tag_name}: ${e.message}`);
-              }
-            }
-
-            console.log(`✅ Cleanup complete. Kept ${Math.min(nightlyReleases.length, 7)} nightly releases, deleted ${toDelete.length}.`);
-
-      - name: Cleanup old S3 versions
-        uses: ./.github/actions/desktop-cleanup-s3
-        with:
-          channel: nightly
-          keep-count: '15'
-          aws-access-key-id: ${{ secrets.UPDATE_AWS_ACCESS_KEY_ID }}
-          aws-secret-access-key: ${{ secrets.UPDATE_AWS_SECRET_ACCESS_KEY }}
-          s3-bucket: ${{ secrets.UPDATE_S3_BUCKET }}
-          s3-region: ${{ secrets.UPDATE_S3_REGION }}
-          s3-endpoint: ${{ secrets.UPDATE_S3_ENDPOINT }}
@@ -266,16 +266,10 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
+      - name: Setup environment
+        uses: ./.github/actions/setup-env
        with:
          node-version: ${{ env.NODE_VERSION }}
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest

      - name: Download artifacts
        uses: actions/download-artifact@v7
@@ -0,0 +1,129 @@
+name: Release ModelBank
+
+permissions:
+  contents: read
+  id-token: write
+
+on:
+  push:
+    branches:
+      - canary
+    paths:
+      - packages/model-bank/**
+  workflow_dispatch: {}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    name: Build ModelBank
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24.11.1
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build package
+        run: pnpm --filter model-bank build
+
+  publish:
+    name: Publish ModelBank
+    needs: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24.11.1
+          registry-url: https://registry.npmjs.org
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - 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 --access public
+        working-directory: packages/model-bank
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
@@ -37,19 +37,11 @@ jobs:
        with:
          token: ${{ secrets.GH_TOKEN }}

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24.11.1
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
-        run: bun i
+        run: pnpm install

      - name: Lint
        run: bun run lint
@@ -15,15 +15,13 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ secrets.BUN_VERSION }}
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
-        run: bun i
+        run: pnpm install

      - name: sync database schema to dbdocs
        env:
          DBDOCS_TOKEN: ${{ secrets.DBDOCS_TOKEN }}
-        run: npm run db:visualize
+        run: bun run db:visualize
@@ -37,19 +37,11 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24.11.1
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: ${{ secrets.BUN_VERSION }}
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
-        run: bun i
+        run: pnpm install

      - name: Test packages with coverage
        run: |
@@ -105,28 +97,20 @@ 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

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24.11.1
-          package-manager-cache: false
-
-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
-        run: bun i
+        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() }}
@@ -146,13 +130,11 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - name: Install bun
-        uses: oven-sh/setup-bun@v2
-        with:
-          bun-version: latest
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
-        run: bun i
+        run: pnpm install

      - name: Download blob reports
        uses: actions/download-artifact@v7
@@ -181,16 +163,8 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24.11.1
-          package-manager-cache: false
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v2
-        with:
-          version: 10
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
        run: pnpm install
@@ -235,20 +209,14 @@ jobs:
    steps:
      - uses: actions/checkout@v6

-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24.11.1
-          package-manager-cache: false
-
-      - name: Install pnpm
-        uses: pnpm/action-setup@v4
+      - name: Setup environment
+        uses: ./.github/actions/setup-env

      - name: Install deps
        run: pnpm i

      - name: Lint
-        run: npm run lint
+        run: bun run lint

      - name: Test Coverage
        run: pnpm --filter @lobechat/database test:coverage
@@ -25,6 +25,9 @@ Desktop.ini
 *.code-workspace
 .vscode/sessions.json
 prd
+# Recordings
+.records/
+
 # Temporary files
 .temp/
 temp/
@@ -52,6 +55,7 @@ bun.lockb

 # Build outputs
 dist/
+public/_spa/
 public/spa/
 es/
 lib/
@@ -134,4 +138,13 @@ i18n-unused-keys-report.json

 pnpm-lock.yaml
 .turbo
-spaHtmlTemplates.ts
+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",
@@ -1,98 +1,124 @@
 # LobeHub Development Guidelines

-This document serves as a comprehensive guide for all team members when developing LobeHub.
-
-## Project Description
-
-You are developing an open-source, modern-design AI Agent Workspace: LobeHub (previously LobeChat).
+Guidelines for using AI coding agents in this LobeHub repository.

 ## Tech Stack

- **Frontend**: Next.js 16, React 19, TypeScript
- **UI Components**: Ant Design, @lobehub/ui, antd-style
- **State Management**: Zustand, SWR
- **Database**: PostgreSQL, PGLite, Drizzle ORM
- **Testing**: Vitest, Testing Library
- **Package Manager**: pnpm (monorepo structure)
+- 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 — **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

-## Directory Structure
+## Project Structure

 ```plaintext
 lobehub/
-├── apps/desktop/           # Electron desktop app
+├── apps/
+│   ├── desktop/            # Electron desktop app
+│   ├── cli/                # LobeHub CLI
+│   └── device-gateway/     # Device gateway service
 ├── packages/               # Shared packages (@lobechat/*)
 │   ├── database/           # Database schemas, models, repositories
 │   ├── agent-runtime/      # Agent runtime
 │   └── ...
 ├── src/
-│   ├── app/                # Next.js app router
-│   ├── spa/                # SPA entry points (entry.*.tsx) and router config
-│   ├── routes/             # SPA page components (roots)
-│   ├── features/           # Business components by domain
+│   ├── app/                # Next.js App Router (backend API + auth)
+│   │   ├── (backend)/     # API routes (trpc, webapi, etc.)
+│   │   ├── spa/            # SPA HTML template service
+│   │   └── [variants]/(auth)/  # Auth pages (SSR required)
+│   ├── routes/             # SPA page components (Vite)
+│   │   ├── (main)/         # Desktop pages
+│   │   ├── (mobile)/       # Mobile pages
+│   │   ├── (desktop)/      # Desktop-specific pages
+│   │   ├── (popup)/        # Popup window pages
+│   │   ├── onboarding/     # Onboarding pages
+│   │   └── share/          # Share pages
+│   ├── spa/                # SPA entry points and router config
+│   │   ├── entry.web.tsx   # Web entry
+│   │   ├── entry.mobile.tsx
+│   │   ├── entry.desktop.tsx
+│   │   ├── entry.popup.tsx
+│   │   └── router/         # React Router configuration
 │   ├── store/              # Zustand stores
 │   ├── services/           # Client services
 │   ├── server/             # Server services and routers
 │   └── ...
-├── .agents/skills/         # AI development skills
 └── e2e/                    # E2E tests (Cucumber + Playwright)
 ```

-## Development Workflow
+## SPA Routes and Features
+
+SPA-related code is grouped under `src/spa/` (entries + router) and `src/routes/` (page segments). We use a **roots vs features** split: route trees only hold page segments; business logic and UI live in features.
+
+- **`src/spa/`** – SPA entry points (`entry.web.tsx`, `entry.mobile.tsx`, `entry.desktop.tsx`, `entry.popup.tsx`) and React Router config (`router/`, with `desktopRouter.config.*`, `mobileRouter.config.tsx`, `popupRouter.config.tsx`). Keeps router config next to entries to avoid confusion with `src/routes/`.
+
+- **`src/routes/` (roots)**\
+  Only page-segment files: `_layout/index.tsx`, `index.tsx` (or `page.tsx`), and dynamic segments like `[id]/index.tsx`. Keep these **thin**: they should only import from `@/features/*` and compose layout/page, with no business logic or heavy UI.
+
+- **`src/features/`**\
+  Business components by **domain** (e.g. `Pages`, `PageEditor`, `Home`). Put layout chunks (sidebar, header, body), hooks, and domain-specific UI here. Each feature exposes an `index.ts` (or `index.tsx`) with clear exports.
+
+When adding or changing SPA routes:
+
+1. In `src/routes/`, add only the route segment files (layout + page) that delegate to features.
+2. Implement layout and page content under `src/features/<Domain>/` and export from there.
+3. In route files, use `import { X } from '@/features/<Domain>'` (or `import Y from '@/features/<Domain>/...'`). Do not add new `features/` folders inside `src/routes/`.
+4. **Register the desktop route tree in both configs:** `src/spa/router/desktopRouter.config.tsx` and `src/spa/router/desktopRouter.config.desktop.tsx` must stay in sync (same paths and nesting). Updating only one can cause **blank screens** if the other build path expects the route. `desktopRouter.sync.test.tsx` guards this invariant — keep it passing.
+
+See the **spa-routes** skill (`.agents/skills/spa-routes/SKILL.md`) for the full convention and file-division rules.
+
+## Development
+
+### Starting the Dev Environment
+
+```bash
+# SPA dev mode (frontend only, proxies API to localhost:3010)
+bun run dev:spa
+
+# Full-stack dev (Next.js + Vite SPA concurrently)
+bun run dev
+```
+
+After `dev:spa` starts, the terminal prints a **Debug Proxy** URL:
+
+```plaintext
+Debug Proxy: https://app.lobehub.com/_dangerous_local_dev_proxy?debug-host=http%3A%2F%2Flocalhost%3A9876
+```
+
+Open this URL to develop locally against the production backend (app.lobehub.com). The proxy page loads your local Vite dev server's SPA into the online environment, enabling HMR with real server config.

 ### Git Workflow

 - **Branch strategy**: `canary` is the development branch (cloud production); `main` is the release branch (periodically cherry-picks from canary)
 - New branches should be created from `canary`; PRs should target `canary`
- Use rebase for git pull
- Git commit messages should prefix with gitmoji
- Git branch name format: `feat/feature-name`
- Use `.github/PULL_REQUEST_TEMPLATE.md` for PR descriptions
+- Use rebase for `git pull`
+- Commit messages: prefix with gitmoji
+- Branch format: `<type>/<feature-name>`

 ### Package Management

- Use `pnpm` as the primary package manager
- Use `bun` to run npm scripts
- Use `bunx` to run executable npm packages
+- `pnpm` for dependency management
+- `bun` to run npm scripts
+- `bunx` for executable npm packages

-### Code Style Guidelines
-
-#### TypeScript
-
- Prefer interfaces over types for object shapes
-
-### Testing Strategy
+### Testing

 ```bash
-# Web tests
-bunx vitest run --silent='passed-only' '[file-path-pattern]'
+# Run specific test (NEVER run `bun run test` - takes ~10 minutes)
+bunx vitest run --silent='passed-only' '[file-path]'

-# Package tests (e.g., database)
-cd packages/[package-name] && bunx vitest run --silent='passed-only' '[file-path-pattern]'
+# Database package
+cd packages/database && bunx vitest run --silent='passed-only' '[file]'
 ```

-**Important Notes**:
-
- Wrap file paths in single quotes to avoid shell expansion
- Never run `bun run test` - this runs all tests and takes \~10 minutes
-
-### Type Checking
-
- Use `bun run type-check` to check for type errors
+- Prefer `vi.spyOn` over `vi.mock`
+- Tests must pass type check: `bun run type-check`
+- After 2 failed fix attempts, stop and ask for help

 ### i18n

- **Keys**: Add to `src/locales/default/namespace.ts`
- **Dev**: Translate `locales/zh-CN/namespace.json` locale file only for preview
- DON'T run `pnpm i18n`, let CI auto handle it
-
-## SPA Routes and Features
-
- **`src/routes/`** holds only page segments (`_layout/index.tsx`, `index.tsx`, `[id]/index.tsx`). Keep route files **thin** — import from `@/features/*` and compose, no business logic.
- **`src/features/`** holds business components by **domain** (e.g. `Pages`, `PageEditor`, `Home`). Layout pieces, hooks, and domain UI go here.
- See the **spa-routes** skill for the full convention and file-division rules.
-
-## Skills (Auto-loaded)
-
-All AI development skills are available in `.agents/skills/` directory and auto-loaded by Claude Code when relevant.
-
-**IMPORTANT**: When reviewing PRs or code diffs, ALWAYS read `.agents/skills/code-review/SKILL.md` first.
+- Add keys to a namespace file under `src/locales/default/` (e.g. `agent.ts`, `auth.ts`)
+- For dev preview: translate `locales/zh-CN/` and `locales/en-US/`
+- Don't run `pnpm i18n` - CI handles it
@@ -2,6 +2,200 @@

 # Changelog

+### [Version 2.1.56](https://github.com/lobehub/lobe-chat/compare/v2.1.55...v2.1.56)
+
+<sup>Released on **2026-05-01**</sup>
+
+#### 👷 Build System
+
+- **database**: add `metadata` and `trigger` to `briefs` table.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### Build System
+
+- **database**: add `metadata` and `trigger` to `briefs` table, closes [#14354](https://github.com/lobehub/lobe-chat/issues/14354) ([86a23b5](https://github.com/lobehub/lobe-chat/commit/86a23b5))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.55](https://github.com/lobehub/lobe-chat/compare/v2.1.54...v2.1.55)
+
+<sup>Released on **2026-04-29**</sup>
+
+#### 🐛 Bug Fixes
+
+- **chat**: preserve topics across cold route sends.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **chat**: preserve topics across cold route sends, closes [#14284](https://github.com/lobehub/lobe-chat/issues/14284) ([b8fe675](https://github.com/lobehub/lobe-chat/commit/b8fe675))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.54](https://github.com/lobehub/lobe-chat/compare/v2.1.53...v2.1.54)
+
+<sup>Released on **2026-04-27**</sup>
+
+#### 🐛 Bug Fixes
+
+- **misc**: clear stale topic when switching agents from a topic route.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### What's fixed
+
+- **misc**: clear stale topic when switching agents from a topic route, closes [#14231](https://github.com/lobehub/lobe-chat/issues/14231) ([deeb97a](https://github.com/lobehub/lobe-chat/commit/deeb97a))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+### [Version 2.1.52](https://github.com/lobehub/lobe-chat/compare/v2.1.51...v2.1.52)
+
+<sup>Released on **2026-04-20**</sup>
+
+#### 👷 Build System
+
+- **database**: add topic status and tasks automation mode.
+
+<br/>
+
+<details>
+<summary><kbd>Improvements and Fixes</kbd></summary>
+
+#### Build System
+
+- **database**: add topic status and tasks automation mode, closes [#13994](https://github.com/lobehub/lobe-chat/issues/13994) ([3bcd581](https://github.com/lobehub/lobe-chat/commit/3bcd581))
+
+</details>
+
+<div align="right">
+
+[![](https://img.shields.io/badge/-BACK_TO_TOP-151515?style=flat-square)](#readme-top)
+
+</div>
+
+## [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>
@@ -1,122 +1 @@
-# CLAUDE.md
-
-Guidelines for using Claude Code in this LobeHub repository.
-
-## Tech Stack
-
- 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
- react-i18next for i18n; zustand for state management
- SWR for data fetching; TRPC for type-safe backend
- Drizzle ORM with PostgreSQL; Vitest for testing
-
-## Project Structure
-
-```plaintext
-lobehub/
-├── apps/desktop/           # Electron desktop app
-├── packages/               # Shared packages (@lobechat/*)
-│   ├── database/           # Database schemas, models, repositories
-│   ├── agent-runtime/      # Agent runtime
-│   └── ...
-├── src/
-│   ├── app/                # Next.js App Router (backend API + auth)
-│   │   ├── (backend)/     # API routes (trpc, webapi, etc.)
-│   │   ├── spa/            # SPA HTML template service
-│   │   └── [variants]/(auth)/  # Auth pages (SSR required)
-│   ├── routes/             # SPA page components (Vite)
-│   │   ├── (main)/         # Desktop pages
-│   │   ├── (mobile)/       # Mobile pages
-│   │   ├── (desktop)/      # Desktop-specific pages
-│   │   ├── onboarding/     # Onboarding pages
-│   │   └── share/          # Share pages
-│   ├── spa/                # SPA entry points and router config
-│   │   ├── entry.web.tsx   # Web entry
-│   │   ├── entry.mobile.tsx
-│   │   ├── entry.desktop.tsx
-│   │   └── router/         # React Router configuration
-│   ├── store/              # Zustand stores
-│   ├── services/           # Client services
-│   ├── server/             # Server services and routers
-│   └── ...
-└── e2e/                    # E2E tests (Cucumber + Playwright)
-```
-
-## SPA Routes and Features
-
-SPA-related code is grouped under `src/spa/` (entries + router) and `src/routes/` (page segments). We use a **roots vs features** split: route trees only hold page segments; business logic and UI live in features.
-
- **`src/spa/`** – SPA entry points (`entry.web.tsx`, `entry.mobile.tsx`, `entry.desktop.tsx`) and React Router config (`router/`). Keeps router config next to entries to avoid confusion with `src/routes/`.
-
- **`src/routes/` (roots)**\
-  Only page-segment files: `_layout/index.tsx`, `index.tsx` (or `page.tsx`), and dynamic segments like `[id]/index.tsx`. Keep these **thin**: they should only import from `@/features/*` and compose layout/page, with no business logic or heavy UI.
-
- **`src/features/`**\
-  Business components by **domain** (e.g. `Pages`, `PageEditor`, `Home`). Put layout chunks (sidebar, header, body), hooks, and domain-specific UI here. Each feature exposes an `index.ts` (or `index.tsx`) with clear exports.
-
-When adding or changing SPA routes:
-
-1. In `src/routes/`, add only the route segment files (layout + page) that delegate to features.
-2. Implement layout and page content under `src/features/<Domain>/` and export from there.
-3. In route files, use `import { X } from '@/features/<Domain>'` (or `import Y from '@/features/<Domain>/...'`). Do not add new `features/` folders inside `src/routes/`.
-
-See the **spa-routes** skill (`.agents/skills/spa-routes/SKILL.md`) for the full convention and file-division rules.
-
-## Development
-
-### Starting the Dev Environment
-
-```bash
-# SPA dev mode (frontend only, proxies API to localhost:3010)
-bun run dev:spa
-
-# Full-stack dev (Next.js + Vite SPA concurrently)
-bun run dev
-```
-
-After `dev:spa` starts, the terminal prints a **Debug Proxy** URL:
-
-```plaintext
-Debug Proxy: https://app.lobehub.com/_dangerous_local_dev_proxy?debug-host=http%3A%2F%2Flocalhost%3A9876
-```
-
-Open this URL to develop locally against the production backend (app.lobehub.com). The proxy page loads your local Vite dev server's SPA into the online environment, enabling HMR with real server config.
-
-### Git Workflow
-
- **Branch strategy**: `canary` is the development branch (cloud production); `main` is the release branch (periodically cherry-picks from canary)
- New branches should be created from `canary`; PRs should target `canary`
- Use rebase for `git pull`
- Commit messages: prefix with gitmoji
- Branch format: `<type>/<feature-name>`
-
-### Package Management
-
- `pnpm` for dependency management
- `bun` to run npm scripts
- `bunx` for executable npm packages
-
-### Testing
-
-```bash
-# Run specific test (NEVER run `bun run test` - takes ~10 minutes)
-bunx vitest run --silent='passed-only' '[file-path]'
-
-# Database package
-cd packages/database && bunx vitest run --silent='passed-only' '[file]'
-```
-
- Prefer `vi.spyOn` over `vi.mock`
- Tests must pass type check: `bun run type-check`
- After 2 failed fix attempts, stop and ask for help
-
-### i18n
-
- Add keys to `src/locales/default/namespace.ts`
- For dev preview: translate `locales/zh-CN/` and `locales/en-US/`
- Don't run `pnpm i18n` - CI handles it
-
-## Skills (Auto-loaded by Claude)
-
-Claude Code automatically loads relevant skills from `.agents/skills/`.
+@AGENTS.md
@@ -1,8 +1,8 @@
-# Lobe Chat - Contributing Guide 🌟
+# LobeHub - Contributing Guide 🌟

-We're thrilled that you want to contribute to Lobe Chat, the future of communication! 😄
+We're thrilled that you want to contribute to LobeHub, the future of communication! 😄

-Lobe Chat is an open-source project, and we welcome your collaboration. Before you jump in, let's make sure you're all set to contribute effectively and have loads of fun along the way!
+LobeHub is an open-source project, and we welcome your collaboration. Before you jump in, let's make sure you're all set to contribute effectively and have loads of fun along the way!

 ## Table of Contents

@@ -69,11 +69,11 @@ git fetch upstream
 git merge upstream/main
 ```

-This ensures you're working on the most current version of Lobe Chat. Stay fresh! 💨
+This ensures you're working on the most current version of LobeHub. Stay fresh! 💨

 ## Open a Pull Request

-🚀 Time to share your contribution! Head over to the original Lobe Chat repository and open a Pull Request (PR). Our maintainers will review your work.
+🚀 Time to share your contribution! Head over to the original LobeHub repository and open a Pull Request (PR). Our maintainers will review your work.

 ## Review and Collaboration

@@ -81,8 +81,8 @@ This ensures you're working on the most current version of Lobe Chat. Stay fresh

 ## Celebrate 🎉

-🎈 Congratulations! Your contribution is now part of Lobe Chat. 🥳
+🎈 Congratulations! Your contribution is now part of LobeHub. 🥳

-Thank you for making Lobe Chat even more magical. We can't wait to see what you create! 🌠
+Thank you for making LobeHub even more magical. We can't wait to see what you create! 🌠

 Happy Coding! 🚀🦄
@@ -111,7 +111,7 @@ COPY --from=base /distroless/ /
 COPY --from=builder /app/.next/standalone /app/
 COPY --from=builder /app/.next/static /app/.next/static
 # Copy SPA assets (Vite build output)
-COPY --from=builder /app/public/spa /app/public/spa
+COPY --from=builder /app/public/_spa /app/public/_spa
 # Copy database migrations
 COPY --from=builder /app/packages/database/migrations /app/migrations
 COPY --from=builder /app/scripts/migrateServerDB/docker.cjs /app/docker.cjs
@@ -0,0 +1,81 @@
+# Security Policy
+
+## Supported Versions
+
+We only provide security fixes for the **latest 2.x release**. Older versions (including all 1.x releases) are end-of-life and will not receive patches.
+
+| Version      | Supported |
+| ------------ | --------- |
+| 2.x (latest) | ✅        |
+| 1.x          | ❌        |
+| 0.x          | ❌        |
+
+If you are running a 1.x deployment, we strongly recommend upgrading to the latest 2.x release.
+
+## Reporting a Vulnerability
+
+Please report security vulnerabilities through the GitHub Security Advisory ["Report a Vulnerability"](https://github.com/lobehub/lobehub/security/advisories/new) tab.
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+### Response Timeline
+
+- **Acknowledgement**: We aim to respond to all reports within **7 days**.
+- **Fix**: Confirmed vulnerabilities will be addressed within **30 days**.
+- **Urgent issues**: If you believe the vulnerability is critical and actively exploitable, you can reach out directly on Discord (`arvinxu`) for faster coordination.
+
+### What to Include
+
+A good vulnerability report should include:
+
+- A clear description of the issue and its potential impact
+- The affected version (must be the latest 2.x release)
+- Step-by-step reproduction instructions or a working PoC
+- Any relevant logs, screenshots, or code references
+
+## Scope
+
+### In Scope
+
+- Security issues affecting the **latest 2.x release** of LobeHub
+- Vulnerabilities in the **server-side deployment** (LobeHub Cloud or self-hosted server mode)
+- Issues that can be exploited **without requiring admin/owner access** to the deployment
+
+### Out of Scope (Not a Vulnerability)
+
+The following are considered **by design** or **out of scope** and will not be accepted as vulnerability reports:
+
+#### 1. End-of-Life Versions
+
+Any issue that only affects 1.x or earlier versions. This includes but is not limited to the `X-lobe-chat-auth` header mechanism, `webapi` route authentication, and other 1.x-specific architectures that have been completely removed in 2.x.
+
+#### 2. File Proxy Public Access (`/f/:id`)
+
+The file proxy endpoint `/f/:id` uses randomly generated, non-enumerable IDs as [capability URLs](https://www.w3.org/TR/capability-urls/). This is a deliberate design choice, similar to how S3 presigned URLs or Google Docs sharing links work. Knowing the URL grants access — this is by design, not an authorization bypass.
+
+#### 3. User Enumeration on Login Flows
+
+Endpoints such as `check-user` that indicate whether an account exists are part of the standard login UX. This is a common and intentional pattern used by most modern authentication flows.
+
+#### 4. Self-Hosted Client-Side API Key Storage
+
+In self-hosted client-side mode, users configure their own API keys which are stored in the browser's local storage. This is the expected behavior for client-side deployments where the user is both the operator and the consumer.
+
+#### 5. Issues Requiring Admin or Owner Privileges
+
+Actions that require administrative access to the deployment (e.g., environment variable configuration, server-side settings) are not considered security vulnerabilities, as the admin is already a trusted party.
+
+#### 6. Theoretical Attacks Without Practical Impact
+
+Reports based on theoretical attack scenarios without a working proof of concept against a realistic deployment, or issues that require unlikely preconditions (e.g., physical access to the server, pre-existing compromise of the host system).
+
+## Disclosure Policy
+
+- We follow [coordinated vulnerability disclosure](https://en.wikipedia.org/wiki/Coordinated_vulnerability_disclosure).
+- We will credit reporters in the security advisory unless they prefer to remain anonymous.
+- Please allow us reasonable time to address the issue before any public disclosure.
+
+## Contact
+
+- **Primary**: [GitHub Security Advisories](https://github.com/lobehub/lobehub/security/advisories/new)
+- **Urgent**: Discord — `arvinxu`
@@ -15,6 +15,17 @@ LobeHub command-line interface.
 - To make `lh` available in your shell, run `bun run cli:link`.
 - After linking, if your shell still cannot find `lh`, run `rehash` in `zsh`.

+## Custom Server URL
+
+By default the CLI connects to `https://app.lobehub.com`. To point it at a different server (e.g. a local instance):
+
+| Method               | Command                                                         | Persistence                         |
+| -------------------- | --------------------------------------------------------------- | ----------------------------------- |
+| Environment variable | `LOBEHUB_SERVER=http://localhost:4000 bun run dev -- <command>` | Current command only                |
+| Login flag           | `lh login --server http://localhost:4000`                       | Saved to `~/.lobehub/settings.json` |
+
+Priority: `LOBEHUB_SERVER` env var > `settings.json` > default official URL.
+
 ## Shell Completion

 ### Install completion for a linked CLI
@@ -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.1\-canary.12" "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
@@ -27,7 +27,7 @@ For command-specific manuals, use the built-in manual command:
 .SH COMMANDS
 .TP
 .B login
-Log in to LobeHub via browser (Device Code Flow)
+Log in to LobeHub via browser (Device Code Flow) or configure API key server
 .TP
 .B logout
 Log out and remove stored credentials
@@ -83,6 +83,9 @@ Manage agent skills
 .B session\-group
 Manage agent session groups
 .TP
+.B task
+Manage agent tasks
+.TP
 .B thread
 Manage message threads
 .TP
@@ -95,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
@@ -112,6 +118,9 @@ View usage statistics
 .TP
 .B eval
 Manage evaluation workflows
+.TP
+.B migrate
+Migrate data from external tools (OpenClaw, ChatGPT, Claude, etc.)
 .SH OPTIONS
 .TP
 .B \-V, \-\-version
@@ -1,6 +1,6 @@
 {
  "name": "@lobehub/cli",
-  "version": "0.0.1-canary.14",
+  "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",
@@ -37,6 +38,7 @@
    "debug": "^4.4.0",
    "diff": "^8.0.3",
    "fast-glob": "^3.3.3",
+    "ignore": "^7.0.5",
    "picocolors": "^1.1.1",
    "superjson": "^2.2.6",
    "tsdown": "^0.21.4",
@@ -1,4 +1,5 @@
 packages:
+  - '../../packages/agent-gateway-client'
  - '../../packages/device-gateway-client'
  - '../../packages/local-file-shell'
  - '../../packages/file-loaders'
@@ -39,7 +39,9 @@ async function getAuthAndServer() {

  const result = await getValidToken();
  if (!result) {
-    log.error(`No authentication found. Run 'lh login' first, or set ${CLI_API_KEY_ENV}.`);
+    log.error(
+      `No authentication found. Run 'lh login' (or 'npx -y @lobehub/cli login') first, or set ${CLI_API_KEY_ENV}.`,
+    );
    process.exit(1);
  }

@@ -3,29 +3,9 @@ import { CLI_API_KEY_ENV } from '../constants/auth';
 import { resolveServerUrl } from '../settings';
 import { log } from '../utils/logger';

-// Must match the server's SECRET_XOR_KEY (src/envs/auth.ts)
-const SECRET_XOR_KEY = 'LobeHub · LobeHub';
-
-/**
- * XOR-obfuscate a payload and encode as Base64.
- * The /webapi/* routes require `X-lobe-chat-auth` with this encoding.
- */
-function obfuscatePayloadWithXOR(payload: Record<string, any>): string {
-  const jsonString = JSON.stringify(payload);
-  const dataBytes = new TextEncoder().encode(jsonString);
-  const keyBytes = new TextEncoder().encode(SECRET_XOR_KEY);
-
-  const result = new Uint8Array(dataBytes.length);
-  for (let i = 0; i < dataBytes.length; i++) {
-    result[i] = dataBytes[i] ^ keyBytes[i % keyBytes.length];
-  }
-
-  return btoa(String.fromCharCode(...result));
-}
-
 export interface AuthInfo {
  accessToken: string;
-  /** Headers required for /webapi/* endpoints (includes both X-lobe-chat-auth and Oidc-Auth) */
+  /** Headers required for /webapi/* endpoints (Oidc-Auth for authentication) */
  headers: Record<string, string>;
  serverUrl: string;
 }
@@ -52,8 +32,69 @@ export async function getAuthInfo(): Promise<AuthInfo> {
    headers: {
      'Content-Type': 'application/json',
      'Oidc-Auth': accessToken,
-      'X-lobe-chat-auth': obfuscatePayloadWithXOR({}),
    },
    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;
+  if (envJwt) {
+    return {
+      headers: { 'Oidc-Auth': envJwt },
+      serverUrl,
+      token: envJwt,
+      tokenType: 'jwt',
+    };
+  }
+
+  const envApiKey = process.env[CLI_API_KEY_ENV];
+  if (envApiKey) {
+    return {
+      headers: { 'X-API-Key': envApiKey },
+      serverUrl,
+      token: envApiKey,
+      tokenType: 'apiKey',
+    };
+  }
+
+  const result = await getValidToken();
+  if (!result) {
+    log.error(`No authentication found. Run 'lh login' first, or set ${CLI_API_KEY_ENV}.`);
+    process.exit(1);
+
+    return {
+      headers: {},
+      serverUrl,
+      token: '',
+      tokenType: 'jwt',
+    };
+  }
+
+  return {
+    headers: { 'Oidc-Auth': result.credentials.accessToken },
+    serverUrl,
+    token: result.credentials.accessToken,
+    tokenType: 'jwt',
+  };
+}
@@ -27,6 +27,9 @@ const { mockTrpcClient } = vi.hoisted(() => ({
      execAgent: { mutate: vi.fn() },
      getOperationStatus: { query: vi.fn() },
    },
+    device: {
+      listDevices: { query: vi.fn() },
+    },
  },
 }));

@@ -38,13 +41,18 @@ const { mockStreamAgentEvents } = vi.hoisted(() => ({
  mockStreamAgentEvents: vi.fn(),
 }));

-const { mockGetAuthInfo } = vi.hoisted(() => ({
-  mockGetAuthInfo: vi.fn(),
+const { mockGetAgentStreamAuthInfo } = vi.hoisted(() => ({
+  mockGetAgentStreamAuthInfo: vi.fn(),
+}));
+
+const { mockResolveLocalDeviceId } = vi.hoisted(() => ({
+  mockResolveLocalDeviceId: vi.fn(),
 }));

 vi.mock('../api/client', () => ({ getTrpcClient: mockGetTrpcClient }));
-vi.mock('../api/http', () => ({ getAuthInfo: mockGetAuthInfo }));
+vi.mock('../api/http', () => ({ getAgentStreamAuthInfo: mockGetAgentStreamAuthInfo }));
 vi.mock('../utils/agentStream', () => ({ streamAgentEvents: mockStreamAgentEvents }));
+vi.mock('../utils/device', () => ({ resolveLocalDeviceId: mockResolveLocalDeviceId }));
 vi.mock('../utils/logger', () => ({
  log: { debug: vi.fn(), error: vi.fn(), heartbeat: vi.fn(), info: vi.fn(), warn: vi.fn() },
  setVerbose: vi.fn(),
@@ -58,12 +66,12 @@ describe('agent command', () => {
    exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
    mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
-    mockGetAuthInfo.mockResolvedValue({
-      accessToken: 'test-token',
-      headers: { 'Content-Type': 'application/json', 'Oidc-Auth': 'test-token' },
+    mockGetAgentStreamAuthInfo.mockResolvedValue({
+      headers: { 'Oidc-Auth': 'test-token' },
      serverUrl: 'https://example.com',
    });
    mockStreamAgentEvents.mockResolvedValue(undefined);
+    mockResolveLocalDeviceId.mockReset();
    for (const method of Object.values(mockTrpcClient.agent)) {
      for (const fn of Object.values(method)) {
        (fn as ReturnType<typeof vi.fn>).mockReset();
@@ -74,6 +82,11 @@ describe('agent command', () => {
        (fn as ReturnType<typeof vi.fn>).mockReset();
      }
    }
+    for (const method of Object.values(mockTrpcClient.device)) {
+      for (const fn of Object.values(method)) {
+        (fn as ReturnType<typeof vi.fn>).mockReset();
+      }
+    }
  });

  afterEach(() => {
@@ -297,7 +310,6 @@ describe('agent command', () => {
        expect.objectContaining({ json: undefined, verbose: undefined }),
      );
    });
-
    it('should support --slug option', async () => {
      mockTrpcClient.aiAgent.execAgent.mutate.mockResolvedValue({
        operationId: 'op-456',
@@ -384,6 +396,186 @@ describe('agent command', () => {
      );
    });

+    it('should pass --device local as deviceId', async () => {
+      mockResolveLocalDeviceId.mockReturnValue('local-device-1');
+      mockTrpcClient.device.listDevices.query.mockResolvedValue([
+        { deviceId: 'local-device-1', online: true },
+      ]);
+      mockTrpcClient.aiAgent.execAgent.mutate.mockResolvedValue({
+        operationId: 'op-device',
+        success: true,
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'run',
+        '--agent-id',
+        'a1',
+        '--prompt',
+        'Hi',
+        '--device',
+        'local',
+      ]);
+
+      expect(mockTrpcClient.aiAgent.execAgent.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ agentId: 'a1', deviceId: 'local-device-1', prompt: 'Hi' }),
+      );
+    });
+
+    it('should pass --topic-id and --device local together', async () => {
+      mockResolveLocalDeviceId.mockReturnValue('local-device-1');
+      mockTrpcClient.device.listDevices.query.mockResolvedValue([
+        { deviceId: 'local-device-1', online: true },
+      ]);
+      mockTrpcClient.aiAgent.execAgent.mutate.mockResolvedValue({
+        operationId: 'op-topic-device',
+        success: true,
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'run',
+        '--agent-id',
+        'a1',
+        '--prompt',
+        'Hi',
+        '--topic-id',
+        't1',
+        '--device',
+        'local',
+      ]);
+
+      expect(mockTrpcClient.aiAgent.execAgent.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ appContext: { topicId: 't1' }, deviceId: 'local-device-1' }),
+      );
+    });
+
+    it('should pass explicit --device id as deviceId', async () => {
+      mockTrpcClient.device.listDevices.query.mockResolvedValue([
+        { deviceId: 'device-remote-1', online: true },
+      ]);
+      mockTrpcClient.aiAgent.execAgent.mutate.mockResolvedValue({
+        operationId: 'op-explicit-device',
+        success: true,
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'run',
+        '--agent-id',
+        'a1',
+        '--prompt',
+        'Hi',
+        '--device',
+        'device-remote-1',
+      ]);
+
+      expect(mockResolveLocalDeviceId).not.toHaveBeenCalled();
+      expect(mockTrpcClient.aiAgent.execAgent.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ agentId: 'a1', deviceId: 'device-remote-1', prompt: 'Hi' }),
+      );
+    });
+
+    it('should exit when explicit device is not found', async () => {
+      mockTrpcClient.device.listDevices.query.mockResolvedValue([
+        { deviceId: 'other-device', online: true },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'run',
+        '--agent-id',
+        'a1',
+        '--prompt',
+        'Hi',
+        '--device',
+        'device-remote-1',
+      ]);
+
+      expect(log.error).toHaveBeenCalledWith(expect.stringContaining('was not found'));
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('should exit when local device cannot be resolved', async () => {
+      mockResolveLocalDeviceId.mockReturnValue(undefined);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'run',
+        '--agent-id',
+        'a1',
+        '--prompt',
+        'Hi',
+        '--device',
+        'local',
+      ]);
+
+      expect(log.error).toHaveBeenCalledWith(expect.stringContaining("Run 'lh connect' first"));
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('should exit when local device is offline', async () => {
+      mockResolveLocalDeviceId.mockReturnValue('local-device-1');
+      mockTrpcClient.device.listDevices.query.mockResolvedValue([
+        { deviceId: 'local-device-1', online: false },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'run',
+        '--agent-id',
+        'a1',
+        '--prompt',
+        'Hi',
+        '--device',
+        'local',
+      ]);
+
+      expect(log.error).toHaveBeenCalledWith(expect.stringContaining('is not online'));
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('should exit when explicit device is offline', async () => {
+      mockTrpcClient.device.listDevices.query.mockResolvedValue([
+        { deviceId: 'device-remote-1', online: false },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'run',
+        '--agent-id',
+        'a1',
+        '--prompt',
+        'Hi',
+        '--device',
+        'device-remote-1',
+      ]);
+
+      expect(log.error).toHaveBeenCalledWith(expect.stringContaining('Bring it online'));
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
    it('should pass --json to stream options', async () => {
      mockTrpcClient.aiAgent.execAgent.mutate.mockResolvedValue({
        operationId: 'op-j',
@@ -4,8 +4,14 @@ import type { Command } from 'commander';
 import pc from 'picocolors';

 import { getTrpcClient } from '../api/client';
-import { getAuthInfo } from '../api/http';
-import { replayAgentEvents, streamAgentEvents } from '../utils/agentStream';
+import { getAgentStreamAuthInfo } from '../api/http';
+import { resolveAgentGatewayUrl } from '../settings';
+import {
+  replayAgentEvents,
+  streamAgentEvents,
+  streamAgentEventsViaWebSocket,
+} from '../utils/agentStream';
+import { resolveLocalDeviceId } from '../utils/device';
 import { confirm, outputJson, printTable, truncate } from '../utils/format';
 import { log, setVerbose } from '../utils/logger';

@@ -248,17 +254,29 @@ export function registerAgentCommand(program: Command) {
    .option('-p, --prompt <text>', 'User prompt')
    .option('-t, --topic-id <id>', 'Reuse an existing topic')
    .option('--no-auto-start', 'Do not auto-start the agent')
+    .option(
+      '--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)')
+    .option('--sse', 'Force SSE stream instead of WebSocket gateway')
    .action(
      async (options: {
        agentId?: string;
        autoStart?: boolean;
+        device?: string;
+        headless?: boolean;
        json?: boolean;
        prompt?: string;
        replay?: string;
        slug?: string;
+        sse?: boolean;
        topicId?: string;
        verbose?: boolean;
      }) => {
@@ -285,12 +303,53 @@ export function registerAgentCommand(program: Command) {

        const client = await getTrpcClient();

+        let deviceId: string | undefined;
+        if (options.device !== undefined) {
+          if (options.device === 'local') {
+            deviceId = resolveLocalDeviceId();
+            if (!deviceId) {
+              log.error(
+                "No local device found. Run 'lh connect' first, then retry with --device local.",
+              );
+              process.exit(1);
+              return;
+            }
+          } else {
+            deviceId = options.device;
+          }
+
+          const devices = await client.device.listDevices.query();
+          const matchedDevice = devices.find(
+            (device: { deviceId?: string; online?: boolean }) => device.deviceId === deviceId,
+          );
+          if (!matchedDevice) {
+            log.error(`Device "${deviceId}" was not found. Check 'lh device list' and try again.`);
+            process.exit(1);
+            return;
+          }
+          if (!matchedDevice.online) {
+            log.error(
+              options.device === 'local'
+                ? `Local device "${deviceId}" is not online. Reconnect with 'lh connect' and try again.`
+                : `Device "${deviceId}" is not online. Bring it online and try again.`,
+            );
+            process.exit(1);
+            return;
+          }
+        }
+
        // 1. Exec agent to get operationId
        const input: Record<string, any> = { prompt: options.prompt };
        if (options.agentId) input.agentId = options.agentId;
+        if (deviceId) input.deviceId = deviceId;
        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;
@@ -305,14 +364,27 @@ export function registerAgentCommand(program: Command) {
          log.info(`Operation: ${pc.dim(operationId)} · Topic: ${pc.dim(r.topicId || 'n/a')}`);
        }

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

-        await streamAgentEvents(streamUrl, headers, {
-          json: options.json,
-          verbose: options.verbose,
-        });
+        if (agentGatewayUrl) {
+          await streamAgentEventsViaWebSocket({
+            gatewayUrl: agentGatewayUrl,
+            json: options.json,
+            operationId,
+            serverUrl,
+            token,
+            tokenType,
+            verbose: options.verbose,
+          });
+        } else {
+          const streamUrl = `${serverUrl}/api/agent/stream?operationId=${encodeURIComponent(operationId)}`;
+          await streamAgentEvents(streamUrl, headers, {
+            json: options.json,
+            verbose: options.verbose,
+          });
+        }
      },
    );

@@ -1,39 +1,130 @@
 import type { Command } from 'commander';
 import pc from 'picocolors';

+import type { TrpcClient } from '../api/client';
 import { getTrpcClient } from '../api/client';
-import { confirm, outputJson, printTable } from '../utils/format';
+import { confirm, outputJson, printBoxTable, printTable, timeAgo } from '../utils/format';
 import { log } from '../utils/logger';
+import { registerBotMessageCommands } from './botMessage';

-const SUPPORTED_PLATFORMS = ['discord', 'slack', 'telegram', 'lark', 'feishu', 'wechat'];
+// ── Helpers ──────────────────────────────────────────────

-const PLATFORM_CREDENTIAL_FIELDS: Record<string, string[]> = {
-  discord: ['botToken', 'publicKey'],
-  feishu: ['appSecret'],
-  lark: ['appSecret'],
-  slack: ['botToken', 'signingSecret'],
-  telegram: ['botToken'],
-  wechat: ['botToken', 'botId'],
+function maskValue(val: string): string {
+  if (val.length > 8) return val.slice(0, 4) + '****' + val.slice(-4);
+  return '****';
+}
+
+function camelToFlag(name: string): string {
+  return '--' + name.replaceAll(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+/** Extract credential field definitions from a platform schema. */
+function getCredentialFields(platformDef: any): any[] {
+  const credSchema = (platformDef.schema ?? []).find(
+    (f: any) => f.key === 'credentials' && f.properties,
+  );
+  return credSchema?.properties ?? [];
+}
+
+/** Extract credential values from CLI options based on platform schema. */
+function extractCredentials(
+  platformDef: any,
+  options: Record<string, any>,
+): { credentials: Record<string, string>; missing: any[] } {
+  const fields = getCredentialFields(platformDef);
+  const credentials: Record<string, string> = {};
+
+  for (const field of fields) {
+    const value = options[field.key];
+    if (typeof value === 'string') {
+      credentials[field.key] = value;
+    }
+  }
+
+  const missing = fields.filter((f: any) => f.required && !credentials[f.key]);
+  return { credentials, missing };
+}
+
+/** Find a bot by ID from the user's bot list. */
+async function findBot(client: TrpcClient, botId: string) {
+  const bots = await client.agentBotProvider.list.query();
+  const bot = (bots as any[]).find((b: any) => b.id === botId);
+  if (!bot) {
+    log.error(`Bot integration not found: ${botId}`);
+    process.exit(1);
+  }
+  return bot;
+}
+
+const STATUS_COLORS: Record<string, (s: string) => string> = {
+  connected: pc.green,
+  disconnected: pc.dim,
+  failed: pc.red,
+  queued: pc.yellow,
+  starting: pc.yellow,
+  unknown: pc.dim,
 };

-function parseCredentials(
-  platform: string,
-  options: Record<string, string | undefined>,
-): Record<string, string> {
-  const creds: Record<string, string> = {};
-
-  if (options.botToken) creds.botToken = options.botToken;
-  if (options.botId) creds.botId = options.botId;
-  if (options.publicKey) creds.publicKey = options.publicKey;
-  if (options.signingSecret) creds.signingSecret = options.signingSecret;
-  if (options.appSecret) creds.appSecret = options.appSecret;
-
-  return creds;
+/** Validate a platform ID and return its definition. */
+async function resolvePlatform(client: TrpcClient, platformId: string) {
+  const platforms = await client.agentBotProvider.listPlatforms.query();
+  const def = (platforms as any[]).find((p: any) => p.id === platformId);
+  if (!def) {
+    const ids = (platforms as any[]).map((p: any) => p.id).join(', ');
+    log.error(`Invalid platform "${platformId}". Must be one of: ${ids}`);
+    log.info('Run `lh bot platforms` to see required credentials for each platform.');
+    process.exit(1);
+  }
+  return def;
 }

+// ── Command Registration ─────────────────────────────────
+
 export function registerBotCommand(program: Command) {
  const bot = program.command('bot').description('Manage bot integrations');

+  // Register message subcommand group
+  registerBotMessageCommands(bot);
+
+  // ── platforms ───────────────────────────────────────────
+
+  bot
+    .command('platforms')
+    .description('List supported platforms and their required credentials')
+    .option('--json', 'Output JSON')
+    .action(async (options: { json?: boolean }) => {
+      const client = await getTrpcClient();
+      const platforms = await client.agentBotProvider.listPlatforms.query();
+
+      if (options.json) {
+        outputJson(platforms);
+        return;
+      }
+
+      console.log(pc.bold('Supported platforms:\n'));
+
+      for (const p of platforms as any[]) {
+        console.log(`  ${pc.bold(pc.cyan(p.id))}`);
+        if (p.name) console.log(`    Name: ${p.name}`);
+
+        const fields = getCredentialFields(p);
+        const required = fields.filter((f: any) => f.required);
+        const optional = fields.filter((f: any) => !f.required);
+
+        if (required.length > 0) {
+          console.log(
+            `    Required: ${required.map((f: any) => pc.yellow(camelToFlag(f.key))).join(', ')}`,
+          );
+        }
+        if (optional.length > 0) {
+          console.log(
+            `    Optional: ${optional.map((f: any) => pc.dim(camelToFlag(f.key))).join(', ')}`,
+          );
+        }
+        console.log();
+      }
+    });
+
  // ── list ──────────────────────────────────────────────

  bot
@@ -63,15 +154,20 @@ export function registerBotCommand(program: Command) {
        return;
      }

-      const rows = items.map((b: any) => [
-        b.id || '',
-        b.platform || '',
-        b.applicationId || '',
-        b.agentId || '',
-        b.enabled ? pc.green('enabled') : pc.dim('disabled'),
-      ]);
+      const rows = items.map((b: any) => {
+        const status = b.enabled ? (b.runtimeStatus ?? 'disconnected') : 'disabled';
+        const colorFn = STATUS_COLORS[status] ?? pc.dim;
+        return [
+          b.id || '',
+          b.platform || '',
+          b.applicationId || '',
+          b.agentId || '',
+          colorFn(status),
+          b.updatedAt ? timeAgo(b.updatedAt) : pc.dim('-'),
+        ];
+      });

-      printTable(rows, ['ID', 'PLATFORM', 'APP ID', 'AGENT', 'STATUS']);
+      printTable(rows, ['ID', 'PLATFORM', 'APP ID', 'AGENT', 'STATUS', 'UPDATED']);
    });

  // ── view ──────────────────────────────────────────────
@@ -79,44 +175,62 @@ export function registerBotCommand(program: Command) {
  bot
    .command('view <botId>')
    .description('View bot integration details')
-    .requiredOption('-a, --agent <agentId>', 'Agent ID')
    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
-    .action(async (botId: string, options: { agent: string; json?: string | boolean }) => {
-      const client = await getTrpcClient();
-      const result = await client.agentBotProvider.getByAgentId.query({
-        agentId: options.agent,
-      });
-      const items = Array.isArray(result) ? result : [];
-      const item = items.find((b: any) => b.id === botId);
+    .option('--show-credentials', 'Show full credential values (unmasked)')
+    .action(
+      async (botId: string, options: { json?: string | boolean; showCredentials?: boolean }) => {
+        const client = await getTrpcClient();
+        const b = await findBot(client, botId);

-      if (!item) {
-        log.error(`Bot integration not found: ${botId}`);
-        process.exit(1);
-        return;
-      }
-
-      if (options.json !== undefined) {
-        const fields = typeof options.json === 'string' ? options.json : undefined;
-        outputJson(item, fields);
-        return;
-      }
-
-      const b = item as any;
-      console.log(pc.bold(`${b.platform} bot`));
-      console.log(pc.dim(`ID: ${b.id}`));
-      console.log(`Application ID: ${b.applicationId}`);
-      console.log(`Status: ${b.enabled ? pc.green('enabled') : pc.dim('disabled')}`);
-
-      if (b.credentials && typeof b.credentials === 'object') {
-        console.log();
-        console.log(pc.bold('Credentials:'));
-        for (const [key, value] of Object.entries(b.credentials)) {
-          const val = String(value);
-          const masked = val.length > 8 ? val.slice(0, 4) + '****' + val.slice(-4) : '****';
-          console.log(`  ${key}: ${masked}`);
+        if (options.json !== undefined) {
+          const fields = typeof options.json === 'string' ? options.json : undefined;
+          outputJson(b, fields);
+          return;
        }
-      }
-    });
+
+        const status = b.enabled ? (b.runtimeStatus ?? 'disconnected') : 'disabled';
+        const statusColorFn = STATUS_COLORS[status] ?? pc.dim;
+
+        const credentialLines: string[] = [];
+        if (b.credentials && typeof b.credentials === 'object') {
+          for (const [key, value] of Object.entries(b.credentials)) {
+            const val = String(value);
+            const display = options.showCredentials ? val : maskValue(val);
+            credentialLines.push(`${pc.dim(key)}: ${display}`);
+          }
+        }
+
+        const settingsLines: string[] = [];
+        if (b.settings && typeof b.settings === 'object') {
+          for (const [key, value] of Object.entries(b.settings)) {
+            settingsLines.push(`${pc.dim(key)}: ${JSON.stringify(value)}`);
+          }
+        }
+
+        printBoxTable(
+          [
+            { header: 'Field', key: 'field' },
+            { header: 'Value', key: 'value' },
+          ],
+          [
+            { field: 'ID', value: b.id || '' },
+            { field: 'Platform', value: pc.cyan(b.platform || '') },
+            { field: 'Application ID', value: b.applicationId || '' },
+            { field: 'Agent ID', value: b.agentId || '' },
+            { field: 'Status', value: statusColorFn(status) },
+            ...(credentialLines.length > 0
+              ? [{ field: 'Credentials', value: credentialLines }]
+              : []),
+            ...(settingsLines.length > 0 ? [{ field: 'Settings', value: settingsLines }] : []),
+            ...(b.createdAt
+              ? [{ field: 'Created', value: new Date(b.createdAt).toLocaleString() }]
+              : []),
+            ...(b.updatedAt ? [{ field: 'Updated', value: timeAgo(b.updatedAt) }] : []),
+          ],
+          `${b.platform} bot`,
+        );
+      },
+    );

  // ── add ───────────────────────────────────────────────

@@ -124,13 +238,18 @@ export function registerBotCommand(program: Command) {
    .command('add')
    .description('Add a bot integration to an agent')
    .requiredOption('-a, --agent <agentId>', 'Agent ID')
-    .requiredOption('--platform <platform>', `Platform: ${SUPPORTED_PLATFORMS.join(', ')}`)
+    .requiredOption('--platform <platform>', 'Platform (run `lh bot platforms` to see options)')
    .requiredOption('--app-id <appId>', 'Application ID for webhook routing')
-    .option('--bot-token <token>', 'Bot token')
+    .option('--bot-token <token>', 'Bot token (Discord, Slack, Telegram)')
    .option('--bot-id <id>', 'Bot ID (WeChat)')
    .option('--public-key <key>', 'Public key (Discord)')
    .option('--signing-secret <secret>', 'Signing secret (Slack)')
-    .option('--app-secret <secret>', 'App secret (Lark/Feishu)')
+    .option('--app-secret <secret>', 'App secret (Lark, Feishu, QQ)')
+    .option('--secret-token <token>', 'Secret token (Telegram)')
+    .option('--webhook-proxy-url <url>', 'Webhook proxy URL (Telegram)')
+    .option('--encrypt-key <key>', 'Encrypt key (Feishu)')
+    .option('--verification-token <token>', 'Verification token (Feishu)')
+    .option('--json', 'Output created bot as JSON')
    .action(
      async (options: {
        agent: string;
@@ -138,34 +257,39 @@ export function registerBotCommand(program: Command) {
        appSecret?: string;
        botId?: string;
        botToken?: string;
+        encryptKey?: string;
+        json?: boolean;
        platform: string;
        publicKey?: string;
+        secretToken?: string;
        signingSecret?: string;
+        verificationToken?: string;
+        webhookProxyUrl?: string;
      }) => {
-        if (!SUPPORTED_PLATFORMS.includes(options.platform)) {
-          log.error(`Invalid platform. Must be one of: ${SUPPORTED_PLATFORMS.join(', ')}`);
-          process.exit(1);
-          return;
-        }
+        const client = await getTrpcClient();
+        const platformDef = await resolvePlatform(client, options.platform);

-        const credentials = parseCredentials(options.platform, options);
-        const requiredFields = PLATFORM_CREDENTIAL_FIELDS[options.platform] || [];
-        const missing = requiredFields.filter((f) => !credentials[f]);
+        const { credentials, missing } = extractCredentials(platformDef, options);
        if (missing.length > 0) {
          log.error(
-            `Missing required credentials for ${options.platform}: ${missing.map((f) => '--' + f.replaceAll(/([A-Z])/g, '-$1').toLowerCase()).join(', ')}`,
+            `Missing required credentials for ${options.platform}: ${missing.map((f: any) => camelToFlag(f.key)).join(', ')}`,
          );
          process.exit(1);
          return;
        }

-        const client = await getTrpcClient();
        const result = await client.agentBotProvider.create.mutate({
          agentId: options.agent,
          applicationId: options.appId,
          credentials,
          platform: options.platform,
        });
+
+        if (options.json) {
+          outputJson(result);
+          return;
+        }
+
        const r = result as any;
        console.log(
          `${pc.green('✓')} Added ${pc.bold(options.platform)} bot ${pc.bold(r.id || '')}`,
@@ -183,6 +307,10 @@ export function registerBotCommand(program: Command) {
    .option('--public-key <key>', 'New public key')
    .option('--signing-secret <secret>', 'New signing secret')
    .option('--app-secret <secret>', 'New app secret')
+    .option('--secret-token <token>', 'New secret token')
+    .option('--webhook-proxy-url <url>', 'New webhook proxy URL')
+    .option('--encrypt-key <key>', 'New encrypt key')
+    .option('--verification-token <token>', 'New verification token')
    .option('--app-id <appId>', 'New application ID')
    .option('--platform <platform>', 'New platform')
    .action(
@@ -193,20 +321,23 @@ export function registerBotCommand(program: Command) {
          appSecret?: string;
          botId?: string;
          botToken?: string;
+          encryptKey?: string;
          platform?: string;
          publicKey?: string;
+          secretToken?: string;
          signingSecret?: string;
+          verificationToken?: string;
+          webhookProxyUrl?: string;
        },
      ) => {
+        const client = await getTrpcClient();
        const input: Record<string, any> = { id: botId };

-        const credentials: Record<string, string> = {};
-        if (options.botToken) credentials.botToken = options.botToken;
-        if (options.botId) credentials.botId = options.botId;
-        if (options.publicKey) credentials.publicKey = options.publicKey;
-        if (options.signingSecret) credentials.signingSecret = options.signingSecret;
-        if (options.appSecret) credentials.appSecret = options.appSecret;
+        const existing = await findBot(client, botId);
+        const platform = options.platform ?? existing.platform;
+        const platformDef = await resolvePlatform(client, platform);

+        const { credentials } = extractCredentials(platformDef, options);
        if (Object.keys(credentials).length > 0) input.credentials = credentials;
        if (options.appId) input.applicationId = options.appId;
        if (options.platform) input.platform = options.platform;
@@ -217,7 +348,6 @@ export function registerBotCommand(program: Command) {
          return;
        }

-        const client = await getTrpcClient();
        await client.agentBotProvider.update.mutate(input as any);
        console.log(`${pc.green('✓')} Updated bot ${pc.bold(botId)}`);
      },
@@ -263,28 +393,41 @@ export function registerBotCommand(program: Command) {
      console.log(`${pc.green('✓')} Disabled bot ${pc.bold(botId)}`);
    });

+  // ── test ───────────────────────────────────────────────
+
+  bot
+    .command('test <botId>')
+    .description('Test bot credentials against the platform API')
+    .action(async (botId: string) => {
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+
+      log.status(`Testing ${b.platform} credentials for ${b.applicationId}...`);
+
+      try {
+        await client.agentBotProvider.testConnection.mutate({
+          applicationId: b.applicationId,
+          platform: b.platform,
+        });
+        console.log(`${pc.green('✓')} Credentials are valid for ${pc.bold(b.platform)} bot`);
+      } catch (err: any) {
+        const message = err?.message || 'Connection test failed';
+        log.error(`Credential test failed: ${message}`);
+        process.exit(1);
+      }
+    });
+
  // ── connect ───────────────────────────────────────────

  bot
    .command('connect <botId>')
    .description('Connect and start a bot')
-    .requiredOption('-a, --agent <agentId>', 'Agent ID')
-    .action(async (botId: string, options: { agent: string }) => {
-      // First fetch the bot to get platform and applicationId
+    .action(async (botId: string) => {
      const client = await getTrpcClient();
-      const result = await client.agentBotProvider.getByAgentId.query({
-        agentId: options.agent,
-      });
-      const items = Array.isArray(result) ? result : [];
-      const item = items.find((b: any) => b.id === botId);
+      const b = await findBot(client, botId);

-      if (!item) {
-        log.error(`Bot integration not found: ${botId}`);
-        process.exit(1);
-        return;
-      }
+      log.status(`Connecting ${b.platform} bot ${b.applicationId}...`);

-      const b = item as any;
      const connectResult = await client.agentBotProvider.connectBot.mutate({
        applicationId: b.applicationId,
        platform: b.platform,
@@ -0,0 +1,564 @@
+import { DEFAULT_BOT_HISTORY_LIMIT } from '@lobechat/const';
+import type { Command } from 'commander';
+import pc from 'picocolors';
+
+import { getTrpcClient } from '../api/client';
+import { confirm, outputJson, printTable, truncate } from '../utils/format';
+import { log } from '../utils/logger';
+
+export function registerBotMessageCommands(bot: Command) {
+  const message = bot
+    .command('message')
+    .description('Send and manage messages on connected platforms');
+
+  // ── send ────────────────────────────────────────────────
+
+  message
+    .command('send <botId>')
+    .description('Send a message to a channel')
+    .requiredOption('--target <channelId>', 'Target channel / conversation ID')
+    .requiredOption('--message <text>', 'Message content')
+    .option('--reply-to <messageId>', 'Reply to a specific message')
+    .option('--json', 'Output JSON')
+    .action(
+      async (
+        botId: string,
+        options: { json?: boolean; message: string; replyTo?: string; target: string },
+      ) => {
+        const client = await getTrpcClient();
+        const result = await client.botMessage.sendMessage.mutate({
+          botId,
+          channelId: options.target,
+          content: options.message,
+          replyTo: options.replyTo,
+        });
+
+        if (options.json) {
+          outputJson(result);
+          return;
+        }
+
+        const r = result as any;
+        console.log(
+          `${pc.green('✓')} Message sent${r.messageId ? ` (${pc.dim(r.messageId)})` : ''}`,
+        );
+      },
+    );
+
+  // ── read ────────────────────────────────────────────────
+
+  message
+    .command('read <botId>')
+    .description('Read messages from a channel')
+    .requiredOption('--target <channelId>', 'Target channel / conversation ID')
+    .option('--limit <n>', 'Max messages to fetch', String(DEFAULT_BOT_HISTORY_LIMIT))
+    .option('--before <messageId>', 'Read messages before this ID')
+    .option('--after <messageId>', 'Read messages after this ID')
+    .option('--start-time <timestamp>', 'Start time as Unix seconds (Feishu/Lark)')
+    .option('--end-time <timestamp>', 'End time as Unix seconds (Feishu/Lark)')
+    .option('--cursor <token>', 'Pagination cursor from a previous response (Feishu/Lark)')
+    .option('--json', 'Output JSON')
+    .action(
+      async (
+        botId: string,
+        options: {
+          after?: string;
+          before?: string;
+          cursor?: string;
+          endTime?: string;
+          json?: boolean;
+          limit?: string;
+          startTime?: string;
+          target: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+        const result = await client.botMessage.readMessages.query({
+          after: options.after,
+          before: options.before,
+          botId,
+          channelId: options.target,
+          cursor: options.cursor,
+          endTime: options.endTime,
+          limit: options.limit ? Number.parseInt(options.limit, 10) : undefined,
+          startTime: options.startTime,
+        });
+
+        if (options.json) {
+          outputJson(result);
+          return;
+        }
+
+        const messages = (result as any).messages ?? [];
+        if (messages.length === 0) {
+          console.log('No messages found.');
+          return;
+        }
+
+        const rows = messages.map((m: any) => [
+          m.id || '',
+          m.author?.name || '',
+          truncate(m.content || '', 60),
+          m.timestamp || '',
+        ]);
+
+        printTable(rows, ['ID', 'AUTHOR', 'CONTENT', 'TIME']);
+
+        const r = result as any;
+        if (r.hasMore && r.nextCursor) {
+          console.log(
+            `\nMore messages available. Use ${pc.dim(`--cursor ${r.nextCursor}`)} to fetch next page.`,
+          );
+        }
+      },
+    );
+
+  // ── edit ────────────────────────────────────────────────
+
+  message
+    .command('edit <botId>')
+    .description('Edit a message')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .requiredOption('--message-id <id>', 'Message ID to edit')
+    .requiredOption('--message <text>', 'New message content')
+    .action(
+      async (botId: string, options: { message: string; messageId: string; target: string }) => {
+        const client = await getTrpcClient();
+        await client.botMessage.editMessage.mutate({
+          botId,
+          channelId: options.target,
+          content: options.message,
+          messageId: options.messageId,
+        });
+
+        console.log(`${pc.green('✓')} Message ${pc.bold(options.messageId)} edited`);
+      },
+    );
+
+  // ── delete ──────────────────────────────────────────────
+
+  message
+    .command('delete <botId>')
+    .description('Delete a message')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .requiredOption('--message-id <id>', 'Message ID to delete')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(
+      async (botId: string, options: { messageId: string; target: string; yes?: boolean }) => {
+        if (!options.yes) {
+          const confirmed = await confirm('Are you sure you want to delete this message?');
+          if (!confirmed) {
+            console.log('Cancelled.');
+            return;
+          }
+        }
+
+        const client = await getTrpcClient();
+        await client.botMessage.deleteMessage.mutate({
+          botId,
+          channelId: options.target,
+          messageId: options.messageId,
+        });
+
+        console.log(`${pc.green('✓')} Message ${pc.bold(options.messageId)} deleted`);
+      },
+    );
+
+  // ── search ──────────────────────────────────────────────
+
+  message
+    .command('search <botId>')
+    .description('Search messages in a channel')
+    .requiredOption('--target <channelId>', 'Channel ID to search in')
+    .requiredOption('--query <text>', 'Search query')
+    .option('--author-id <id>', 'Filter by author ID')
+    .option('--limit <n>', 'Max results')
+    .option('--json', 'Output JSON')
+    .action(
+      async (
+        botId: string,
+        options: {
+          authorId?: string;
+          json?: boolean;
+          limit?: string;
+          query: string;
+          target: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+        const result = await client.botMessage.searchMessages.query({
+          authorId: options.authorId,
+          botId,
+          channelId: options.target,
+          limit: options.limit ? Number.parseInt(options.limit, 10) : undefined,
+          query: options.query,
+        });
+
+        if (options.json) {
+          outputJson(result);
+          return;
+        }
+
+        const messages = (result as any).messages ?? [];
+        if (messages.length === 0) {
+          console.log('No messages found.');
+          return;
+        }
+
+        const rows = messages.map((m: any) => [
+          m.id || '',
+          m.author?.name || '',
+          truncate(m.content || '', 60),
+        ]);
+
+        printTable(rows, ['ID', 'AUTHOR', 'CONTENT']);
+      },
+    );
+
+  // ── react ───────────────────────────────────────────────
+
+  message
+    .command('react <botId>')
+    .description('Add an emoji reaction to a message')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .requiredOption('--message-id <id>', 'Message ID to react to')
+    .requiredOption('--emoji <emoji>', 'Emoji to react with')
+    .action(
+      async (botId: string, options: { emoji: string; messageId: string; target: string }) => {
+        const client = await getTrpcClient();
+        await client.botMessage.reactToMessage.mutate({
+          botId,
+          channelId: options.target,
+          emoji: options.emoji,
+          messageId: options.messageId,
+        });
+
+        console.log(
+          `${pc.green('✓')} Reacted with ${options.emoji} to message ${pc.bold(options.messageId)}`,
+        );
+      },
+    );
+
+  // ── reactions ───────────────────────────────────────────
+
+  message
+    .command('reactions <botId>')
+    .description('List reactions on a message')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .requiredOption('--message-id <id>', 'Message ID')
+    .option('--json', 'Output JSON')
+    .action(
+      async (botId: string, options: { json?: boolean; messageId: string; target: string }) => {
+        const client = await getTrpcClient();
+        const result = await client.botMessage.getReactions.query({
+          botId,
+          channelId: options.target,
+          messageId: options.messageId,
+        });
+
+        if (options.json) {
+          outputJson(result);
+          return;
+        }
+
+        const reactions = (result as any).reactions ?? [];
+        if (reactions.length === 0) {
+          console.log('No reactions found.');
+          return;
+        }
+
+        const rows = reactions.map((r: any) => [r.emoji || '', String(r.count || 0)]);
+        printTable(rows, ['EMOJI', 'COUNT']);
+      },
+    );
+
+  // ── pin ─────────────────────────────────────────────────
+
+  message
+    .command('pin <botId>')
+    .description('Pin a message')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .requiredOption('--message-id <id>', 'Message ID to pin')
+    .action(async (botId: string, options: { messageId: string; target: string }) => {
+      const client = await getTrpcClient();
+      await client.botMessage.pinMessage.mutate({
+        botId,
+        channelId: options.target,
+        messageId: options.messageId,
+      });
+
+      console.log(`${pc.green('✓')} Pinned message ${pc.bold(options.messageId)}`);
+    });
+
+  // ── unpin ───────────────────────────────────────────────
+
+  message
+    .command('unpin <botId>')
+    .description('Unpin a message')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .requiredOption('--message-id <id>', 'Message ID to unpin')
+    .action(async (botId: string, options: { messageId: string; target: string }) => {
+      const client = await getTrpcClient();
+      await client.botMessage.unpinMessage.mutate({
+        botId,
+        channelId: options.target,
+        messageId: options.messageId,
+      });
+
+      console.log(`${pc.green('✓')} Unpinned message ${pc.bold(options.messageId)}`);
+    });
+
+  // ── pins ────────────────────────────────────────────────
+
+  message
+    .command('pins <botId>')
+    .description('List pinned messages')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .option('--json', 'Output JSON')
+    .action(async (botId: string, options: { json?: boolean; target: string }) => {
+      const client = await getTrpcClient();
+      const result = await client.botMessage.listPins.query({
+        botId,
+        channelId: options.target,
+      });
+
+      if (options.json) {
+        outputJson(result);
+        return;
+      }
+
+      const messages = (result as any).messages ?? [];
+      if (messages.length === 0) {
+        console.log('No pinned messages.');
+        return;
+      }
+
+      const rows = messages.map((m: any) => [
+        m.id || '',
+        m.author?.name || '',
+        truncate(m.content || '', 60),
+      ]);
+
+      printTable(rows, ['ID', 'AUTHOR', 'CONTENT']);
+    });
+
+  // ── poll ────────────────────────────────────────────────
+
+  message
+    .command('poll <botId>')
+    .description('Create a poll')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .requiredOption('--poll-question <text>', 'Poll question')
+    .requiredOption('--poll-option <option>', 'Poll option (repeatable)', collectOptions, [])
+    .option('--poll-multi', 'Allow multiple answers')
+    .option('--poll-duration-hours <n>', 'Poll duration in hours')
+    .action(
+      async (
+        botId: string,
+        options: {
+          pollDurationHours?: string;
+          pollMulti?: boolean;
+          pollOption: string[];
+          pollQuestion: string;
+          target: string;
+        },
+      ) => {
+        if (options.pollOption.length < 2) {
+          log.error('At least 2 poll options are required.');
+          process.exit(1);
+        }
+
+        const client = await getTrpcClient();
+        const result = await client.botMessage.createPoll.mutate({
+          botId,
+          channelId: options.target,
+          duration: options.pollDurationHours
+            ? Number.parseInt(options.pollDurationHours, 10)
+            : undefined,
+          multipleAnswers: options.pollMulti,
+          options: options.pollOption,
+          question: options.pollQuestion,
+        });
+
+        const r = result as any;
+        console.log(`${pc.green('✓')} Poll created${r.pollId ? ` (${pc.dim(r.pollId)})` : ''}`);
+      },
+    );
+
+  // ── thread (subcommand group) ───────────────────────────
+
+  const thread = message.command('thread').description('Manage threads');
+
+  thread
+    .command('create <botId>')
+    .description('Create a new thread')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .requiredOption('--thread-name <name>', 'Thread name')
+    .option('--message <text>', 'Initial message content')
+    .option('--message-id <id>', 'Create thread from a message')
+    .action(
+      async (
+        botId: string,
+        options: { message?: string; messageId?: string; target: string; threadName: string },
+      ) => {
+        const client = await getTrpcClient();
+        const result = await client.botMessage.createThread.mutate({
+          botId,
+          channelId: options.target,
+          content: options.message,
+          messageId: options.messageId,
+          name: options.threadName,
+        });
+
+        const r = result as any;
+        console.log(
+          `${pc.green('✓')} Thread created${r.threadId ? ` (${pc.dim(r.threadId)})` : ''}`,
+        );
+      },
+    );
+
+  thread
+    .command('list <botId>')
+    .description('List threads in a channel')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .option('--json', 'Output JSON')
+    .action(async (botId: string, options: { json?: boolean; target: string }) => {
+      const client = await getTrpcClient();
+      const result = await client.botMessage.listThreads.query({
+        botId,
+        channelId: options.target,
+      });
+
+      if (options.json) {
+        outputJson(result);
+        return;
+      }
+
+      const threads = (result as any).threads ?? [];
+      if (threads.length === 0) {
+        console.log('No threads found.');
+        return;
+      }
+
+      const rows = threads.map((t: any) => [
+        t.id || '',
+        t.name || '',
+        String(t.messageCount ?? ''),
+      ]);
+
+      printTable(rows, ['ID', 'NAME', 'MESSAGES']);
+    });
+
+  thread
+    .command('reply <botId>')
+    .description('Reply to a thread')
+    .requiredOption('--thread-id <id>', 'Thread ID')
+    .requiredOption('--message <text>', 'Reply content')
+    .action(async (botId: string, options: { message: string; threadId: string }) => {
+      const client = await getTrpcClient();
+      const result = await client.botMessage.replyToThread.mutate({
+        botId,
+        content: options.message,
+        threadId: options.threadId,
+      });
+
+      const r = result as any;
+      console.log(`${pc.green('✓')} Reply sent${r.messageId ? ` (${pc.dim(r.messageId)})` : ''}`);
+    });
+
+  // ── channel (subcommand group) ──────────────────────────
+
+  const channel = message.command('channel').description('Manage channels');
+
+  channel
+    .command('list <botId>')
+    .description('List channels')
+    .option('--server-id <id>', 'Server / workspace ID')
+    .option('--filter <type>', 'Filter by type')
+    .option('--json', 'Output JSON')
+    .action(
+      async (botId: string, options: { filter?: string; json?: boolean; serverId?: string }) => {
+        const client = await getTrpcClient();
+        const result = await client.botMessage.listChannels.query({
+          botId,
+          filter: options.filter,
+          serverId: options.serverId,
+        });
+
+        if (options.json) {
+          outputJson(result);
+          return;
+        }
+
+        const channels = (result as any).channels ?? [];
+        if (channels.length === 0) {
+          console.log('No channels found.');
+          return;
+        }
+
+        const rows = channels.map((c: any) => [c.id || '', c.name || '', c.type || '']);
+        printTable(rows, ['ID', 'NAME', 'TYPE']);
+      },
+    );
+
+  channel
+    .command('info <botId>')
+    .description('Get channel details')
+    .requiredOption('--target <channelId>', 'Channel ID')
+    .option('--json', 'Output JSON')
+    .action(async (botId: string, options: { json?: boolean; target: string }) => {
+      const client = await getTrpcClient();
+      const result = await client.botMessage.getChannelInfo.query({
+        botId,
+        channelId: options.target,
+      });
+
+      if (options.json) {
+        outputJson(result);
+        return;
+      }
+
+      const r = result as any;
+      console.log(`Channel: ${pc.bold(r.name || options.target)}`);
+      if (r.type) console.log(`  Type: ${r.type}`);
+      if (r.memberCount != null) console.log(`  Members: ${r.memberCount}`);
+      if (r.description) console.log(`  Description: ${r.description}`);
+    });
+
+  // ── member ──────────────────────────────────────────────
+
+  const member = message.command('member').description('Member information');
+
+  member
+    .command('info <botId>')
+    .description('Get member details')
+    .requiredOption('--member-id <id>', 'Member / user ID')
+    .option('--server-id <id>', 'Server / workspace ID')
+    .option('--json', 'Output JSON')
+    .action(
+      async (botId: string, options: { json?: boolean; memberId: string; serverId?: string }) => {
+        const client = await getTrpcClient();
+        const result = await client.botMessage.getMemberInfo.query({
+          botId,
+          memberId: options.memberId,
+          serverId: options.serverId,
+        });
+
+        if (options.json) {
+          outputJson(result);
+          return;
+        }
+
+        const r = result as any;
+        console.log(`Member: ${pc.bold(r.displayName || r.username || options.memberId)}`);
+        if (r.status) console.log(`  Status: ${r.status}`);
+        if (r.roles?.length) console.log(`  Roles: ${r.roles.join(', ')}`);
+      },
+    );
+}
+
+// ── Helpers ──────────────────────────────────────────────
+
+function collectOptions(value: string, previous: string[]): string[] {
+  return [...previous, value];
+}
@@ -96,7 +96,7 @@ vi.mock('@lobechat/device-gateway-client', () => ({
 // eslint-disable-next-line import-x/first
 import { resolveToken } from '../auth/resolveToken';
 // eslint-disable-next-line import-x/first
-import { spawnDaemon, stopDaemon } from '../daemon/manager';
+import { removeStatus, spawnDaemon, stopDaemon, writeStatus } from '../daemon/manager';
 // eslint-disable-next-line import-x/first
 import { loadSettings, saveSettings } from '../settings';
 // eslint-disable-next-line import-x/first
@@ -130,6 +130,36 @@ describe('connect command', () => {
    return program;
  }

+  it('should persist deviceId in status for foreground connections', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'test', 'connect']);
+
+    expect(writeStatus).toHaveBeenCalledWith(
+      expect.objectContaining({ connectionStatus: 'connecting', deviceId: 'mock-device-id' }),
+    );
+
+    clientEventHandlers.connected?.();
+
+    expect(writeStatus).toHaveBeenLastCalledWith(
+      expect.objectContaining({ connectionStatus: 'connected', deviceId: 'mock-device-id' }),
+    );
+  });
+
+  it('should persist deviceId in status for daemon child connections', async () => {
+    const program = createProgram();
+    await program.parseAsync(['node', 'test', 'connect', '--daemon-child']);
+
+    expect(writeStatus).toHaveBeenCalledWith(
+      expect.objectContaining({ connectionStatus: 'connecting', deviceId: 'mock-device-id' }),
+    );
+
+    clientEventHandlers.connected?.();
+
+    expect(writeStatus).toHaveBeenLastCalledWith(
+      expect.objectContaining({ connectionStatus: 'connected', deviceId: 'mock-device-id' }),
+    );
+  });
+
  it('should connect to gateway', async () => {
    const program = createProgram();
    await program.parseAsync(['node', 'test', 'connect']);
@@ -288,6 +318,7 @@ describe('connect command', () => {
    }

    expect(cleanupAllProcesses).toHaveBeenCalled();
+    expect(removeStatus).toHaveBeenCalled();
  });

  it('should handle auth_expired when refresh fails', async () => {
@@ -173,7 +173,7 @@ function buildDaemonArgs(options: ConnectOptions): string[] {
 }

 async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
-  const auth = await resolveToken(options);
+  let auth = await resolveToken(options);
  const settings = loadSettings();
  const gatewayUrl = normalizeUrl(options.gateway) || settings?.gatewayUrl;

@@ -221,16 +221,15 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
  info(`  Mode      : ${isDaemonChild ? 'daemon' : 'foreground'}`);
  info('───────────────────');

-  // Update status file for daemon mode
+  // Update local connection status so other CLI commands can resolve the current device
  const updateStatus = (connectionStatus: string) => {
-    if (isDaemonChild) {
-      writeStatus({
-        connectionStatus,
-        gatewayUrl: resolvedGatewayUrl,
-        pid: process.pid,
-        startedAt: startedAt.toISOString(),
-      });
-    }
+    writeStatus({
+      connectionStatus,
+      deviceId: client.currentDeviceId,
+      gatewayUrl: resolvedGatewayUrl,
+      pid: process.pid,
+      startedAt: startedAt.toISOString(),
+    });
  };

  const startedAt = new Date();
@@ -295,19 +294,30 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
    process.exit(1);
  });

-  // Handle auth expired
+  // Handle auth expired — refresh token and reconnect automatically
  client.on('auth_expired', async () => {
    if (auth.tokenType === 'apiKey') {
+      // API keys don't expire; ignore stale auth_expired signals
      return;
    }

-    error('Authentication expired. Attempting to refresh...');
-    const refreshed = await resolveToken({});
-    if (refreshed) {
-      info('Token refreshed. Please reconnect.');
-    } else {
-      error("Could not refresh token. Run 'lh login' to re-authenticate.");
+    info('Authentication expired. Attempting to refresh token...');
+
+    try {
+      const refreshed = await resolveToken({});
+      if (refreshed) {
+        info('Token refreshed successfully. Reconnecting...');
+        client.updateToken(refreshed.token);
+        // Update cached auth so subsequent refreshes use the latest token
+        auth = refreshed;
+        await client.reconnect();
+        return;
+      }
+    } catch {
+      // refresh failed — fall through
    }
+
+    error("Could not refresh token. Run 'lh login' to re-authenticate.");
    cleanup();
    process.exit(1);
  });
@@ -322,8 +332,8 @@ async function runConnect(options: ConnectOptions, isDaemonChild: boolean) {
    info('Shutting down...');
    cleanupAllProcesses();
    client.disconnect();
+    removeStatus();
    if (isDaemonChild) {
-      removeStatus();
      removePid();
    }
  };
@@ -111,7 +111,7 @@ describe('cron command', () => {
      ]);

      expect(mockTrpcClient.agentCronJob.create.mutate).toHaveBeenCalledWith(
-        expect.objectContaining({ agentId: 'a1', name: 'My Job', schedule: '* * * * *' }),
+        expect.objectContaining({ agentId: 'a1', cronPattern: '* * * * *', name: 'My Job' }),
      );
    });
  });
@@ -125,10 +125,10 @@ export function registerCronCommand(program: Command) {

        const input: Record<string, any> = {
          agentId: options.agentId,
-          schedule: options.schedule,
+          cronPattern: options.schedule,
        };
        if (options.name) input.name = options.name;
-        if (options.prompt) input.prompt = options.prompt;
+        if (options.prompt) input.content = options.prompt;
        if (options.maxExecutions) input.maxExecutions = Number.parseInt(options.maxExecutions, 10);

        const result = await client.agentCronJob.create.mutate(input as any);
@@ -168,8 +168,8 @@ export function registerCronCommand(program: Command) {
      ) => {
        const data: Record<string, any> = {};
        if (options.name) data.name = options.name;
-        if (options.schedule) data.schedule = options.schedule;
-        if (options.prompt) data.prompt = options.prompt;
+        if (options.schedule) data.cronPattern = options.schedule;
+        if (options.prompt) data.content = options.prompt;
        if (options.maxExecutions) data.maxExecutions = Number.parseInt(options.maxExecutions, 10);
        if (options.enable) data.enabled = true;
        if (options.disable) data.enabled = false;
@@ -61,7 +61,6 @@ describe('generate command', () => {
      headers: {
        'Content-Type': 'application/json',
        'Oidc-Auth': 'test-token',
-        'X-lobe-chat-auth': 'test-xor-token',
      },
      serverUrl: 'https://app.lobehub.com',
    });
@@ -271,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[];

@@ -0,0 +1,11 @@
+import type { Command } from 'commander';
+
+import { registerOpenClawMigration } from './openclaw';
+
+export function registerMigrateCommand(program: Command) {
+  const migrate = program
+    .command('migrate')
+    .description('Migrate data from external tools (OpenClaw, ChatGPT, Claude, etc.)');
+
+  registerOpenClawMigration(migrate);
+}
@@ -0,0 +1,588 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import { Command } from 'commander';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+// ── Mocks ──────────────────────────────────────────────
+
+const { mockTrpcClient } = vi.hoisted(() => ({
+  mockTrpcClient: {
+    agent: {
+      createAgent: { mutate: vi.fn() },
+      getBuiltinAgent: { query: vi.fn() },
+    },
+    agentDocument: {
+      upsertDocument: { mutate: vi.fn() },
+    },
+  },
+}));
+
+const { getTrpcClient: mockGetTrpcClient } = vi.hoisted(() => ({
+  getTrpcClient: vi.fn(),
+}));
+
+const { mockConfirm } = vi.hoisted(() => ({
+  mockConfirm: vi.fn(),
+}));
+
+vi.mock('../../api/client', () => ({
+  getTrpcClient: mockGetTrpcClient,
+}));
+
+vi.mock('../../settings', () => ({
+  resolveServerUrl: () => 'https://app.lobehub.com',
+}));
+
+vi.mock('../../utils/format', async (importOriginal) => {
+  const actual = await importOriginal<Record<string, unknown>>();
+  return { ...actual, confirm: mockConfirm };
+});
+
+vi.mock('../../utils/logger', () => ({
+  log: {
+    debug: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+    warn: vi.fn(),
+  },
+  setVerbose: vi.fn(),
+}));
+
+// eslint-disable-next-line import-x/first
+import { log } from '../../utils/logger';
+// eslint-disable-next-line import-x/first
+import { registerOpenClawMigration } from './openclaw';
+
+// ── Helpers ────────────────────────────────────────────
+
+let tmpDir: string;
+
+function createProgram() {
+  const program = new Command();
+  program.exitOverride();
+  const migrate = program.command('migrate');
+  registerOpenClawMigration(migrate);
+  return program;
+}
+
+function writeFile(relativePath: string, content: string) {
+  const fullPath = path.join(tmpDir, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content);
+}
+
+// ── Setup / teardown ───────────────────────────────────
+
+let exitSpy: ReturnType<typeof vi.spyOn>;
+let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'openclaw-test-'));
+  exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {
+    throw new Error('process.exit');
+  }) as any);
+  consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+  mockGetTrpcClient.mockResolvedValue(mockTrpcClient);
+  mockConfirm.mockResolvedValue(true);
+});
+
+afterEach(() => {
+  exitSpy.mockRestore();
+  consoleSpy.mockRestore();
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+});
+
+// ── Tests ──────────────────────────────────────────────
+
+describe('migrate openclaw', () => {
+  // ── Profile parsing ────────────────────────────────
+
+  describe('agent profile from workspace', () => {
+    it('should read name, description, and emoji from IDENTITY.md', async () => {
+      writeFile(
+        'IDENTITY.md',
+        ['# IDENTITY.md', '- **Name:** 龙虾', '- **Creature:** AI 助手', '- **Emoji:** 🦞'].join(
+          '\n',
+        ),
+      );
+      writeFile('hello.md', 'hello');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agent.createAgent.mutate).toHaveBeenCalledWith({
+        config: {
+          avatar: '🦞',
+          description: 'AI 助手',
+          title: '龙虾',
+        },
+      });
+    });
+
+    it('should filter out placeholder emoji like （待定）', async () => {
+      writeFile(
+        'IDENTITY.md',
+        ['# IDENTITY.md', '- **Name:** TestBot', '- **Emoji:**', '  _(待定)_'].join('\n'),
+      );
+      writeFile('hello.md', 'hello');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agent.createAgent.mutate).toHaveBeenCalledWith({
+        config: {
+          avatar: undefined,
+          description: undefined,
+          title: 'TestBot',
+        },
+      });
+    });
+
+    it('should fall back to "OpenClaw" when no identity files exist', async () => {
+      writeFile('doc.md', 'content');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agent.createAgent.mutate).toHaveBeenCalledWith({
+        config: {
+          avatar: undefined,
+          description: undefined,
+          title: 'OpenClaw',
+        },
+      });
+    });
+  });
+
+  // ── File filtering ─────────────────────────────────
+
+  describe('file collection and filtering', () => {
+    it('should exclude common directories like node_modules and .git', async () => {
+      writeFile('README.md', 'readme');
+      writeFile('node_modules/pkg/index.js', 'module');
+      writeFile('.git/config', 'git');
+      writeFile('.idea/workspace.xml', 'ide');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledTimes(1);
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ filename: 'README.md' }),
+      );
+    });
+
+    it('should exclude files matching glob patterns like *.pyc and *.log', async () => {
+      writeFile('main.py', 'print("hi")');
+      writeFile('main.pyc', 'bytecode');
+      writeFile('app.log', 'log data');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledTimes(1);
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ filename: 'main.py' }),
+      );
+    });
+
+    it('should respect workspace .gitignore', async () => {
+      writeFile('.gitignore', 'secret.txt\ndata/\n');
+      writeFile('README.md', 'readme');
+      writeFile('secret.txt', 'password');
+      writeFile('data/dump.sql', 'sql');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      const filenames = mockTrpcClient.agentDocument.upsertDocument.mutate.mock.calls.map(
+        (c: any[]) => c[0].filename,
+      );
+      expect(filenames).toContain('README.md');
+      expect(filenames).not.toContain('secret.txt');
+      expect(filenames).not.toContain('data/dump.sql');
+    });
+
+    it('should skip binary files during import', async () => {
+      writeFile('readme.md', 'text content');
+      // Write a file with null bytes (binary)
+      const binPath = path.join(tmpDir, 'image.dat');
+      fs.writeFileSync(binPath, Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x00, 0x00, 0x01]));
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      // Only the text file should be upserted
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledTimes(1);
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ filename: 'readme.md' }),
+      );
+      // Binary file should show as skipped in output
+      const allOutput = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+      expect(allOutput).toContain('skipped');
+    });
+
+    it('should exclude database files by extension', async () => {
+      writeFile('data.md', 'notes');
+      writeFile('local.sqlite', 'fake-sqlite');
+      writeFile('app.db', 'fake-db');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledTimes(1);
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ filename: 'data.md' }),
+      );
+    });
+
+    it('should collect files in subdirectories', async () => {
+      writeFile('docs/guide.md', 'guide');
+      writeFile('docs/api.md', 'api');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      const filenames = mockTrpcClient.agentDocument.upsertDocument.mutate.mock.calls
+        .map((c: any[]) => c[0].filename)
+        .sort();
+      expect(filenames).toEqual(['docs/api.md', 'docs/guide.md']);
+    });
+  });
+
+  // ── Dry run ────────────────────────────────────────
+
+  describe('--dry-run', () => {
+    it('should list files without calling API', async () => {
+      writeFile('file.md', 'content');
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--dry-run',
+      ]);
+
+      expect(mockGetTrpcClient).not.toHaveBeenCalled();
+      expect(mockTrpcClient.agent.createAgent.mutate).not.toHaveBeenCalled();
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).not.toHaveBeenCalled();
+      expect(log.info).toHaveBeenCalledWith(expect.stringContaining('Dry run'));
+    });
+  });
+
+  // ── Agent resolution ───────────────────────────────
+
+  describe('agent resolution', () => {
+    it('should use --agent-id directly when provided', async () => {
+      writeFile('file.md', 'content');
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--agent-id',
+        'agt_existing',
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agent.createAgent.mutate).not.toHaveBeenCalled();
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ agentId: 'agt_existing' }),
+      );
+    });
+
+    it('should resolve agent by --slug', async () => {
+      writeFile('file.md', 'content');
+      mockTrpcClient.agent.getBuiltinAgent.query.mockResolvedValue({ id: 'agt_inbox' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--slug',
+        'inbox',
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agent.getBuiltinAgent.query).toHaveBeenCalledWith({ slug: 'inbox' });
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ agentId: 'agt_inbox' }),
+      );
+    });
+
+    it('should create a new agent by default', async () => {
+      writeFile('file.md', 'content');
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_new' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agent.createAgent.mutate).toHaveBeenCalledTimes(1);
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledWith(
+        expect.objectContaining({ agentId: 'agt_new' }),
+      );
+    });
+  });
+
+  // ── Confirmation ───────────────────────────────────
+
+  describe('confirmation', () => {
+    it('should cancel when user declines', async () => {
+      writeFile('file.md', 'content');
+      mockConfirm.mockResolvedValue(false);
+
+      const program = createProgram();
+      await program.parseAsync(['node', 'test', 'migrate', 'openclaw', '--source', tmpDir]);
+
+      expect(mockTrpcClient.agent.createAgent.mutate).not.toHaveBeenCalled();
+      expect(consoleSpy).toHaveBeenCalledWith('Cancelled.');
+    });
+
+    it('should skip confirmation with --yes', async () => {
+      writeFile('file.md', 'content');
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockConfirm).not.toHaveBeenCalled();
+    });
+  });
+
+  // ── Error handling ─────────────────────────────────
+
+  describe('error handling', () => {
+    it('should exit when source path does not exist', async () => {
+      const program = createProgram();
+      await program
+        .parseAsync(['node', 'test', 'migrate', 'openclaw', '--source', '/nonexistent/path'])
+        .catch(() => {}); // process.exit throws
+
+      expect(exitSpy).toHaveBeenCalledWith(1);
+      expect(log.error).toHaveBeenCalledWith(expect.stringContaining('not found'));
+    });
+
+    it('should report failed files without aborting', async () => {
+      writeFile('a.md', 'ok');
+      writeFile('b.md', 'fail');
+
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      // Files are iterated in readdir order; mock first success then failure
+      mockTrpcClient.agentDocument.upsertDocument.mutate
+        .mockResolvedValueOnce({})
+        .mockRejectedValueOnce(new Error('upload error'));
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.upsertDocument.mutate).toHaveBeenCalledTimes(2);
+      const allOutput = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+      expect(allOutput).toContain('1 imported');
+      expect(allOutput).toContain('1 failed');
+    });
+
+    it('should show no files message for empty workspace', async () => {
+      // Only excluded items
+      writeFile('.git/config', 'git');
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--dry-run',
+      ]);
+
+      expect(log.info).toHaveBeenCalledWith('No files found in workspace.');
+    });
+  });
+
+  // ── Output ─────────────────────────────────────────
+
+  describe('output', () => {
+    it('should print agent URL on completion', async () => {
+      writeFile('file.md', 'content');
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_abc123' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      const allOutput = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+      expect(allOutput).toContain('https://app.lobehub.com/agent/agt_abc123');
+    });
+
+    it('should show friendly completion message on success', async () => {
+      writeFile('file.md', 'content');
+      mockTrpcClient.agent.createAgent.mutate.mockResolvedValue({ agentId: 'agt_test' });
+      mockTrpcClient.agentDocument.upsertDocument.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'migrate',
+        'openclaw',
+        '--source',
+        tmpDir,
+        '--yes',
+      ]);
+
+      const allOutput = consoleSpy.mock.calls.map((c: any[]) => c[0]).join('\n');
+      expect(allOutput).toContain('Migration complete');
+    });
+  });
+});
@@ -0,0 +1,466 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+import type { Command } from 'commander';
+import ignore from 'ignore';
+import pc from 'picocolors';
+
+import type { TrpcClient } from '../../api/client';
+import { getTrpcClient } from '../../api/client';
+import { resolveServerUrl } from '../../settings';
+import { confirm } from '../../utils/format';
+import { log } from '../../utils/logger';
+
+const DEFAULT_AGENT_NAME = 'OpenClaw';
+
+// Files to look for agent identity (tried in order)
+const IDENTITY_FILES = ['IDENTITY.md', 'SOUL.md'];
+
+// Default ignore rules (gitignore syntax) applied when no .gitignore is found
+const DEFAULT_IGNORE_RULES = [
+  // VCS
+  '.git',
+  '.svn',
+  '.hg',
+
+  // OpenClaw internal
+  '.openclaw',
+
+  // OS artifacts
+  '.DS_Store',
+  'Thumbs.db',
+  'desktop.ini',
+
+  // IDE / editor
+  '.idea',
+  '.vscode',
+  '.fleet',
+  '.cursor',
+  '.zed',
+  '*.swp',
+  '*.swo',
+  '*~',
+
+  // Dependencies
+  'node_modules',
+  '.pnp',
+  '.yarn',
+  'bower_components',
+  'vendor',
+  'jspm_packages',
+
+  // Python
+  '.venv',
+  'venv',
+  'env',
+  '__pycache__',
+  '*.pyc',
+  '*.pyo',
+  '.mypy_cache',
+  '.ruff_cache',
+  '.pytest_cache',
+  '.tox',
+  '.eggs',
+  '*.egg-info',
+
+  // Ruby
+  '.bundle',
+
+  // Rust
+  'target',
+
+  // Go
+  'go.sum',
+
+  // Java / JVM
+  '.gradle',
+  '.m2',
+
+  // .NET
+  'bin',
+  'obj',
+  'packages',
+
+  // Build / cache / output
+  '.cache',
+  '.parcel-cache',
+  '.next',
+  '.nuxt',
+  '.turbo',
+  '.output',
+  'dist',
+  'build',
+  'out',
+  '.sass-cache',
+
+  // Env / secrets
+  '.env',
+  '.env.*',
+
+  // Test / coverage
+  'coverage',
+  '.nyc_output',
+
+  // Infra
+  '.terraform',
+
+  // Temp
+  'tmp',
+  '.tmp',
+
+  // Logs
+  '*.log',
+  'logs',
+
+  // Databases
+  '*.sqlite',
+  '*.sqlite3',
+  '*.db',
+  '*.db-shm',
+  '*.db-wal',
+  '*.ldb',
+  '*.mdb',
+  '*.accdb',
+
+  // Archives / binaries
+  '*.zip',
+  '*.tar',
+  '*.tar.gz',
+  '*.tgz',
+  '*.gz',
+  '*.bz2',
+  '*.xz',
+  '*.rar',
+  '*.7z',
+  '*.jar',
+  '*.war',
+  '*.dll',
+  '*.so',
+  '*.dylib',
+  '*.exe',
+  '*.bin',
+  '*.o',
+  '*.a',
+  '*.lib',
+  '*.class',
+
+  // Images / media / fonts
+  '*.png',
+  '*.jpg',
+  '*.jpeg',
+  '*.gif',
+  '*.bmp',
+  '*.ico',
+  '*.webp',
+  '*.svg',
+  '*.mp3',
+  '*.mp4',
+  '*.wav',
+  '*.avi',
+  '*.mov',
+  '*.mkv',
+  '*.flac',
+  '*.ogg',
+  '*.pdf',
+  '*.woff',
+  '*.woff2',
+  '*.ttf',
+  '*.otf',
+  '*.eot',
+
+  // Lock files
+  'package-lock.json',
+  'yarn.lock',
+  'pnpm-lock.yaml',
+  'Gemfile.lock',
+  'Cargo.lock',
+  'poetry.lock',
+  'composer.lock',
+];
+
+interface AgentProfile {
+  avatar?: string;
+  description?: string;
+  title: string;
+}
+
+/**
+ * Try to extract the agent name, description, and avatar emoji from
+ * IDENTITY.md or SOUL.md. Falls back to "OpenClaw" if neither file
+ * exists or parsing fails.
+ */
+function readAgentProfile(workspacePath: string): AgentProfile {
+  for (const filename of IDENTITY_FILES) {
+    const filePath = path.join(workspacePath, filename);
+    if (!fs.existsSync(filePath)) continue;
+
+    const content = fs.readFileSync(filePath, 'utf8');
+
+    // Try to extract **Name:** value
+    const nameMatch = content.match(/\*{0,2}Name:?\*{0,2}\s*(.+)/i);
+    const title = nameMatch ? nameMatch[1].trim() : DEFAULT_AGENT_NAME;
+
+    // Try to extract **Creature:** or **Vibe:** or **Description:** as description
+    const descMatch = content.match(/\*{0,2}(?:Creature|Vibe|Description):?\*{0,2}\s*(.+)/i);
+    const description = descMatch ? descMatch[1].trim() : undefined;
+
+    // Try to extract **Emoji:** value (single emoji)
+    const emojiMatch = content.match(/\*{0,2}Emoji:?\*{0,2}\s*(.+)/i);
+    const rawAvatar = emojiMatch ? emojiMatch[1].trim() : undefined;
+    // Filter out placeholder text like （待定）(Chinese TBD), _(待定)_, (TBD), N/A, etc.
+    const isPlaceholder =
+      rawAvatar && /^[_*（(].*[)）_*]$|^(?:tbd|todo|n\/?a|none|待定|未定)$/i.test(rawAvatar);
+    const avatar = rawAvatar && !isPlaceholder ? rawAvatar : undefined;
+
+    return { avatar, description, title };
+  }
+
+  return { title: DEFAULT_AGENT_NAME };
+}
+
+/**
+ * Build an ignore filter for the workspace. Uses .gitignore if present,
+ * otherwise falls back to a comprehensive default rule set.
+ */
+function buildIgnoreFilter(workspacePath: string) {
+  const ig = ignore();
+
+  const gitignorePath = path.join(workspacePath, '.gitignore');
+  if (fs.existsSync(gitignorePath)) {
+    ig.add(fs.readFileSync(gitignorePath, 'utf8'));
+  }
+
+  // Always apply default rules on top
+  ig.add(DEFAULT_IGNORE_RULES);
+
+  return ig;
+}
+
+/**
+ * Recursively collect all files under `dir`, filtered by ignore rules.
+ * Returns paths relative to `baseDir`.
+ */
+function collectFiles(dir: string, baseDir: string, ig: ReturnType<typeof ignore>): string[] {
+  const results: string[] = [];
+
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const relativePath = path.relative(baseDir, path.join(dir, entry.name));
+
+    // Directories need a trailing slash for ignore to match correctly
+    const testPath = entry.isDirectory() ? `${relativePath}/` : relativePath;
+    if (ig.ignores(testPath)) continue;
+
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      results.push(...collectFiles(fullPath, baseDir, ig));
+    } else if (entry.isFile()) {
+      results.push(relativePath);
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Quick check: read the first 8KB and look for null bytes.
+ * If found, the file is likely binary and should be skipped.
+ */
+function isBinaryFile(filePath: string): boolean {
+  const fd = fs.openSync(filePath, 'r');
+  try {
+    const buf = Buffer.alloc(8192);
+    const bytesRead = fs.readSync(fd, buf, 0, 8192, 0);
+    for (let i = 0; i < bytesRead; i++) {
+      if (buf[i] === 0) return true;
+    }
+    return false;
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function formatAgentLabel(profile: AgentProfile): string {
+  return profile.avatar ? `${profile.avatar} ${profile.title}` : profile.title;
+}
+
+/**
+ * Resolve the target agent ID.
+ * Priority: --agent-id > --slug > create new agent from workspace profile.
+ */
+async function resolveAgentId(
+  client: TrpcClient,
+  opts: { agentId?: string; slug?: string },
+  profile: AgentProfile,
+): Promise<string> {
+  if (opts.agentId) return opts.agentId;
+
+  if (opts.slug) {
+    const agent = await client.agent.getBuiltinAgent.query({ slug: opts.slug });
+    if (!agent) {
+      log.error(`Agent not found for slug: ${opts.slug}`);
+      process.exit(1);
+    }
+    return agent.id;
+  }
+
+  const label = formatAgentLabel(profile);
+  log.info(`Creating new agent ${pc.bold(label)}...`);
+  const result = await client.agent.createAgent.mutate({
+    config: {
+      avatar: profile.avatar,
+      description: profile.description,
+      title: profile.title,
+    },
+  });
+
+  const id = result.agentId;
+  if (!id) {
+    log.error('Failed to create agent — no agentId returned.');
+    process.exit(1);
+  }
+
+  console.log(`${pc.green('✓')} Agent created: ${pc.bold(label)}`);
+  return id;
+}
+
+export function registerOpenClawMigration(migrate: Command) {
+  migrate
+    .command('openclaw')
+    .description('Import OpenClaw workspace files as agent documents')
+    .option(
+      '--source <path>',
+      'Path to OpenClaw workspace',
+      path.join(os.homedir(), '.openclaw', 'workspace'),
+    )
+    .option('--agent-id <id>', 'Import into an existing agent by ID')
+    .option('--slug <slug>', 'Import into an existing agent by slug (e.g. "inbox")')
+    .option('--dry-run', 'Preview files without importing')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(
+      async (options: {
+        agentId?: string;
+        dryRun?: boolean;
+        slug?: string;
+        source: string;
+        yes?: boolean;
+      }) => {
+        // Check auth early so users don't scan files only to find out they're not logged in
+        if (!options.dryRun) {
+          await getTrpcClient();
+        }
+
+        const workspacePath = path.resolve(options.source);
+
+        // Validate source directory
+        if (!fs.existsSync(workspacePath)) {
+          log.error(`OpenClaw workspace not found: ${workspacePath}`);
+          process.exit(1);
+        }
+
+        if (!fs.statSync(workspacePath).isDirectory()) {
+          log.error(`Not a directory: ${workspacePath}`);
+          process.exit(1);
+        }
+
+        // Read agent profile from workspace identity files
+        const profile = readAgentProfile(workspacePath);
+        const label = formatAgentLabel(profile);
+
+        // Collect files (respects .gitignore + default rules)
+        const ig = buildIgnoreFilter(workspacePath);
+        const files = collectFiles(workspacePath, workspacePath, ig);
+
+        if (files.length === 0) {
+          log.info('No files found in workspace.');
+          return;
+        }
+
+        console.log(
+          `Found ${pc.bold(String(files.length))} file(s) in ${pc.dim(workspacePath)}:\n`,
+        );
+        for (const f of files) {
+          console.log(`  ${pc.dim('•')} ${f}`);
+        }
+        console.log();
+
+        if (options.dryRun) {
+          log.info('Dry run — no changes made.');
+          return;
+        }
+
+        // Confirm
+        if (!options.yes) {
+          const target = options.agentId
+            ? `agent ${pc.bold(options.agentId)}`
+            : options.slug
+              ? `agent slug "${pc.bold(options.slug)}"`
+              : `a new ${pc.bold(label)} agent`;
+          const confirmed = await confirm(
+            `Import ${files.length} file(s) as agent documents into ${target}?`,
+          );
+          if (!confirmed) {
+            console.log('Cancelled.');
+            return;
+          }
+        }
+
+        const client = await getTrpcClient();
+
+        // Create or reuse agent
+        const agentId = await resolveAgentId(client, options, profile);
+
+        console.log(`\nImporting to ${pc.bold(label)}...\n`);
+
+        let success = 0;
+        let failed = 0;
+
+        let skipped = 0;
+
+        for (const relativePath of files) {
+          const fullPath = path.join(workspacePath, relativePath);
+
+          try {
+            // Skip binary files that slipped through the extension filter
+            if (isBinaryFile(fullPath)) {
+              console.log(`  ${pc.dim('○')} ${relativePath} ${pc.dim('(binary, skipped)')}`);
+              skipped++;
+              continue;
+            }
+
+            const content = fs.readFileSync(fullPath, 'utf8');
+            const stat = fs.statSync(fullPath);
+
+            await client.agentDocument.upsertDocument.mutate({
+              agentId,
+              content,
+              createdAt: stat.birthtime,
+              filename: relativePath,
+              updatedAt: stat.mtime,
+            });
+            console.log(`  ${pc.green('✓')} ${relativePath}`);
+            success++;
+          } catch (err: any) {
+            console.log(`  ${pc.red('✗')} ${relativePath} — ${err.message || err}`);
+            failed++;
+          }
+        }
+
+        const agentUrl = `${resolveServerUrl()}/agent/${agentId}`;
+        const skippedInfo = skipped > 0 ? `, ${skipped} skipped` : '';
+        console.log();
+        if (failed === 0) {
+          console.log(
+            `${pc.green('✓')} Migration complete! ${pc.bold(String(success))} file(s) imported to ${pc.bold(label)}.${skippedInfo}`,
+          );
+        } else {
+          console.log(
+            `${pc.yellow('⚠')} Migration finished with issues: ${pc.bold(String(success))} imported, ${pc.red(String(failed))} failed${skippedInfo}.`,
+          );
+        }
+        console.log(`\n  ${pc.dim('→')} ${pc.underline(agentUrl)}`);
+        console.log();
+      },
+    );
+}
@@ -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);
+        }
+      },
+    );
+}
@@ -2,10 +2,12 @@ import type { Command } from 'commander';
 import pc from 'picocolors';

 import { getTrpcClient } from '../../api/client';
+import type { KanbanColumn } from '../../utils/format';
 import {
  confirm,
  displayWidth,
  outputJson,
+  printKanban,
  printTable,
  timeAgo,
  truncate,
@@ -37,10 +39,12 @@ export function registerTaskCommand(program: Command) {
    .option('-L, --limit <n>', 'Page size', '50')
    .option('--offset <n>', 'Offset', '0')
    .option('--tree', 'Display as tree structure')
+    .option('--board', 'Display as kanban board grouped by status')
    .option('--json [fields]', 'Output JSON')
    .action(
      async (options: {
        agent?: string;
+        board?: boolean;
        json?: string | boolean;
        limit?: string;
        offset?: string;
@@ -52,15 +56,15 @@ 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;
        if (options.limit) input.limit = Number.parseInt(options.limit, 10);
        if (options.offset) input.offset = Number.parseInt(options.offset, 10);

-        // For tree mode, fetch all tasks (no pagination limit)
-        if (options.tree) {
+        // For tree/board mode, fetch all tasks (no pagination limit)
+        if (options.tree || options.board) {
          input.limit = 100;
          delete input.offset;
        }
@@ -77,6 +81,58 @@ export function registerTaskCommand(program: Command) {
          return;
        }

+        if (options.board) {
+          // Kanban board grouped by status
+          const statusOrder = [
+            'backlog',
+            'blocked',
+            'running',
+            'paused',
+            'completed',
+            'failed',
+            'timeout',
+            'canceled',
+          ];
+
+          const statusColors: Record<string, (s: string) => string> = {
+            backlog: pc.dim,
+            blocked: pc.red,
+            canceled: pc.dim,
+            completed: pc.green,
+            failed: pc.red,
+            paused: pc.yellow,
+            running: pc.blue,
+            timeout: pc.red,
+          };
+
+          // Group tasks by status
+          const grouped = new Map<string, any[]>();
+          for (const t of result.data) {
+            const status = t.status || 'backlog';
+            const list = grouped.get(status) || [];
+            list.push(t);
+            grouped.set(status, list);
+          }
+
+          const kanbanColumns: KanbanColumn[] = statusOrder
+            .filter((s) => grouped.has(s))
+            .map((status) => ({
+              color: statusColors[status],
+              items: grouped.get(status)!.map((t: any) => ({
+                badge: pc.dim(t.identifier),
+                meta: t.assigneeAgentId ? `agent: ${t.assigneeAgentId}` : undefined,
+                title: t.name || t.instruction,
+              })),
+              title: status.toUpperCase(),
+            }));
+
+          console.log();
+          printKanban(kanbanColumns);
+          console.log();
+          log.info(`Total: ${result.total}`);
+          return;
+        }
+
        if (options.tree) {
          // Build tree display
          const taskMap = new Map<string, any>();
@@ -240,23 +296,34 @@ export function registerTaskCommand(program: Command) {
      }
      if (t.error) console.log(`${pc.red('Error:')} ${t.error}`);

-      // ── Subtasks ──
+      // ── Subtasks (nested tree) ──
      if (t.subtasks && t.subtasks.length > 0) {
-        // Build lookup: which subtasks are completed
-        const completedIdentifiers = new Set(
-          t.subtasks.filter((s) => s.status === 'completed').map((s) => s.identifier),
-        );
+        // Build lookup: which subtasks are completed (flatten tree)
+        const collectCompleted = (nodes: typeof t.subtasks, set: Set<string>): Set<string> => {
+          for (const s of nodes!) {
+            if (s.status === 'completed') set.add(s.identifier);
+            if (s.children) collectCompleted(s.children, set);
+          }
+          return set;
+        };
+        const completedIdentifiers = collectCompleted(t.subtasks, new Set());
+
+        const renderSubtasks = (nodes: typeof t.subtasks, indent: string) => {
+          for (const s of nodes!) {
+            const depInfo = s.blockedBy ? pc.dim(` ← blocks: ${s.blockedBy}`) : '';
+            const isBlocked = s.blockedBy && !completedIdentifiers.has(s.blockedBy);
+            const displayStatus = s.status === 'backlog' && isBlocked ? 'blocked' : s.status;
+            console.log(
+              `${indent}${pc.dim(s.identifier)} ${statusBadge(displayStatus)} ${s.name || '(unnamed)'}${depInfo}`,
+            );
+            if (s.children && s.children.length > 0) {
+              renderSubtasks(s.children, indent + '  ');
+            }
+          }
+        };

        console.log(`\n${pc.bold('Subtasks:')}`);
-        for (const s of t.subtasks) {
-          const depInfo = s.blockedBy ? pc.dim(` ← blocks: ${s.blockedBy}`) : '';
-          // Show 'blocked' instead of 'backlog' if task has unresolved dependencies
-          const isBlocked = s.blockedBy && !completedIdentifiers.has(s.blockedBy);
-          const displayStatus = s.status === 'backlog' && isBlocked ? 'blocked' : s.status;
-          console.log(
-            `  ${pc.dim(s.identifier)} ${statusBadge(displayStatus)} ${s.name || '(unnamed)'}${depInfo}`,
-          );
-        }
+        renderSubtasks(t.subtasks, '  ');
      }

      // ── Dependencies ──
@@ -399,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}`,
--- a/Show More
+++ b/Show More