💄 style: add Qwen3.7 Max locale (#15150 )

💄 style(workflow): normalize block spacing (#15169 )
✨ feat(chat): consume gateway uiMessages snapshot as SoT at step boundaries (#15153 )
2026-06-14 19:50:09 +00:00 · 2026-05-24 21:49:34 +08:00 · 2026-05-24 20:17:30 +08:00 · 2026-05-24 20:05:58 +08:00 · 2026-05-24 18:39:05 +08:00 · 2026-05-24 16:29:22 +08:00
4046 changed files with 397072 additions and 56017 deletions
@@ -1,6 +1,8 @@
 ---
 name: add-provider-doc
-description: Guide for adding new AI provider documentation. Use when adding documentation for a new AI provider (like OpenAI, Anthropic, etc.), including usage docs, environment variables, Docker config, and image resources. Triggers on provider documentation tasks.
+description: Add documentation for a new AI provider — usage docs, env vars, Docker config, image resources.
+disable-model-invocation: true
+argument-hint: '[provider-name]'
 ---

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

 # Adding Environment Variable for User Settings
@@ -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,95 @@
+---
+name: agent-signal
+description: Build or extend LobeHub Agent Signal pipelines for background or quiet agent work driven by event sources, semantic signals, and action handlers. Use when adding a new Agent Signal source, signal or action type, policy, middleware handler, workflow handoff, dedupe or scope behavior, or observability around `src/server/services/agentSignal/**`, `packages/agent-signal`, or `packages/observability-otel/src/modules/agent-signal`.
+---
+
+# Agent Signal
+
+Use this skill to implement event-driven background work for agents without coupling the work to the foreground chat request.
+
+Agent Signal has one consistent shape:
+
+`source event` -> `signal interpretation` -> `action execution` -> built-in result signals
+
+## Start Here
+
+1. Read `references/architecture.md` to map the package boundary, runtime queue, scope model, and async workflow handoff.
+2. Read `references/handlers.md` before writing any new policy, source handler, signal handler, or action handler.
+3. Read `references/observability.md` when you need tracing, metrics, debugging, or workflow snapshot visibility.
+
+## Use The Right Entry Point
+
+- Use `emitAgentSignalSourceEvent(...)` when a server-owned producer should execute the pipeline immediately.
+- Use `executeAgentSignalSourceEvent(...)` when a worker or controlled backend path already owns execution timing and may inject a runtime guard backend.
+- Use `enqueueAgentSignalSourceEvent(...)` when the caller should return quickly and let Upstash Workflow process the event out-of-band.
+- Use `emitAgentSignalSourceEventWithStore(...)` for isolated tests or evals that should avoid ambient Redis state.
+
+Read:
+
+- `src/server/services/agentSignal/index.ts`
+- `src/server/workflows/agentSignal/index.ts`
+- `src/server/workflows/agentSignal/run.ts`
+
+## Core Model
+
+- `source`: A normalized fact that happened. Sources come from producers such as runtime lifecycle events, user messages, or bot ingress.
+- `signal`: A semantic interpretation derived from one source or from another signal. Signals express meaning, routing, or policy state.
+- `action`: A concrete side effect planned from one signal. Actions do the work.
+- `policy`: An installable middleware bundle that registers source, signal, and action handlers.
+- `procedure`: Not a distinct runtime node. Treat "procedure" as the end-to-end flow for one use case: ingress source, matching handlers, planned actions, execution result, and observability.
+
+Keep the boundaries strict:
+
+- Add a new `source` when the outside world produced a new event.
+- Add a new `signal` when the system needs a reusable semantic interpretation.
+- Add a new `action` when the runtime needs a concrete side effect.
+- Add or update a `policy` when you are wiring those pieces together.
+
+## Implementation Workflow
+
+1. Decide whether the use case is synchronous or quiet background work.
+2. Define or reuse a source type in `src/server/services/agentSignal/sourceTypes.ts`.
+3. Define or reuse signal and action types in `src/server/services/agentSignal/policies/types.ts`.
+4. Implement handlers with `defineSourceHandler`, `defineSignalHandler`, or `defineActionHandler`.
+5. Bundle handlers with `defineAgentSignalHandlers(...)`.
+6. Register the policy in `src/server/services/agentSignal/policies/index.ts` and pass it into the runtime factory if needed.
+7. Add or update ingress code that emits or enqueues the source event.
+8. Add observability and tests before considering the flow complete.
+
+## Default Reading Set
+
+- Shared semantic core:
+  `packages/agent-signal/src/index.ts`
+  `packages/agent-signal/src/base/builders.ts`
+  `packages/agent-signal/src/base/types.ts`
+- Server-owned runtime and middleware:
+  `src/server/services/agentSignal/runtime/AgentSignalRuntime.ts`
+  `src/server/services/agentSignal/runtime/AgentSignalScheduler.ts`
+  `src/server/services/agentSignal/runtime/middleware.ts`
+  `src/server/services/agentSignal/runtime/context.ts`
+- Existing policy example:
+  `src/server/services/agentSignal/policies/analyzeIntent/index.ts`
+  `src/server/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.ts`
+  `src/server/services/agentSignal/policies/analyzeIntent/feedbackDomain.ts`
+  `src/server/services/agentSignal/policies/analyzeIntent/feedbackAction.ts`
+  `src/server/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts`
+- Observability:
+  `src/server/services/agentSignal/observability/projector.ts`
+  `src/server/services/agentSignal/observability/traceEvents.ts`
+  `packages/observability-otel/src/modules/agent-signal/index.ts`
+
+## Implementation Rules
+
+- Reuse existing source, signal, and action types before adding new ones.
+- Keep source handlers focused on interpretation and fan-out, not heavy side effects.
+- Keep action handlers responsible for side effects, idempotency, and executor-style result reporting.
+- Use stable ids and idempotency keys when the same source can arrive more than once.
+- Preserve scope discipline. The runtime uses `scopeKey` to serialize related background work.
+- Prefer the dedicated shared package types and builders from `@lobechat/agent-signal` for normalized nodes and result contracts.
+- Add focused tests near the touched runtime, policy, or store module. Existing tests under `src/server/services/agentSignal/**/__tests__` are the reference pattern.
+
+## References
+
+- Architecture and boundaries: `references/architecture.md`
+- Writing handlers and policies: `references/handlers.md`
+- Observability, metrics, and debugging: `references/observability.md`
@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Agent Signal'
+  short_description: 'Build AgentSignal sources, signals, actions, and policies.'
+  default_prompt: 'Use $agent-signal to add a new Agent Signal source, policy, handler, or observability flow.'
@@ -0,0 +1,199 @@
+# Agent Signal Architecture
+
+## Pipeline
+
+Use this mental model first:
+
+```text
+producer
+  -> emitAgentSignalSourceEvent(...) or enqueueAgentSignalSourceEvent(...)
+    -> emitSourceEvent(...)
+      -> dedupe + scope lock + source normalization
+        -> runtime.emitNormalized(source)
+          -> source handlers
+            -> signal handlers
+              -> action handlers
+                -> built-in result signals
+                  -> observability projection + persistence
+```
+
+The scheduler is queue-driven, not hard-coded for one policy:
+
+```text
+source node
+  -> matching source handlers
+    -> dispatch signals/actions
+      -> matching signal handlers
+        -> dispatch more signals/actions
+          -> matching action handlers
+            -> ExecutorResult
+              -> signal.action.applied | signal.action.skipped | signal.action.failed
+```
+
+Read:
+
+- `src/server/services/agentSignal/index.ts`
+- `src/server/services/agentSignal/sources/index.ts`
+- `src/server/services/agentSignal/runtime/AgentSignalScheduler.ts`
+
+## Package Boundaries
+
+### `packages/agent-signal`
+
+Treat this as the shared semantic core.
+
+It provides:
+
+- base node types: source, signal, action
+- builders: `createSource`, `createSignal`, `createAction`
+- built-in result signal types
+- runtime result contracts such as `RuntimeProcessorResult` and `ExecutorResult`
+
+Read:
+
+- `packages/agent-signal/src/base/types.ts`
+- `packages/agent-signal/src/base/builders.ts`
+- `packages/agent-signal/src/types/events.ts`
+- `packages/agent-signal/src/types/builtin.ts`
+
+### `src/server/services/agentSignal`
+
+Treat this as the server-owned implementation layer.
+
+It owns:
+
+- source catalogs and payload maps
+- policy-specific signal and action catalogs
+- middleware registration
+- runtime scheduling and guard backends
+- Redis-backed dedupe, waypoint, and policy state
+- service entrypoints for synchronous and async execution
+
+### `packages/observability-otel/src/modules/agent-signal`
+
+Treat this as shared OTEL ownership for Agent Signal metrics and tracer instances.
+
+## Core Vocabulary
+
+### Source
+
+A source is the normalized external fact that started the chain.
+
+Examples:
+
+- `agent.user.message`
+- `runtime.before_step`
+- `runtime.after_step`
+- `client.runtime.start`
+- `bot.message.merged`
+
+Define source payloads in:
+
+- `src/server/services/agentSignal/sourceTypes.ts`
+
+Build normalized sources in:
+
+- `src/server/services/agentSignal/sources/buildSource.ts`
+- `packages/agent-signal/src/base/builders.ts`
+
+### Signal
+
+A signal is a semantic interpretation. Signals should be reusable and meaning-oriented.
+
+Examples from `analyzeIntent`:
+
+- `signal.feedback.satisfaction`
+- `signal.feedback.domain.memory`
+- `signal.feedback.domain.prompt`
+- `signal.feedback.domain.skill`
+
+Define server-owned signal types in:
+
+- `src/server/services/agentSignal/policies/types.ts`
+
+### Action
+
+An action is a concrete side effect the runtime should execute.
+
+Example:
+
+- `action.user-memory.handle`
+
+Action handlers usually:
+
+- check idempotency
+- call tools, models, or services
+- return `ExecutorResult`
+
+### Policy
+
+A policy is an installable bundle of handlers. It is the composition unit that turns the generic runtime into a feature.
+
+Example:
+
+- `createAnalyzeIntentPolicy(...)`
+
+### Procedure
+
+"Procedure" is not a first-class type in this runtime. Use the word to describe one end-to-end use case:
+
+1. define ingress source
+2. emit or enqueue the source
+3. interpret source into signals
+4. plan actions from signals
+5. execute actions
+6. persist trace and metrics
+
+When a user asks for "the procedure", document the flow above and point to the exact producer, handlers, and execution entrypoint.
+
+## Scope, Deduping, And Quiet Background Work
+
+`scopeKey` is the serialization boundary for related work. It is used for:
+
+- source dedupe windows
+- scope locks during source generation
+- runtime guard state
+- waypoint persistence for queued processing
+
+Read:
+
+- `src/server/services/agentSignal/sources/index.ts`
+- `src/server/services/agentSignal/runtime/context.ts`
+- `src/server/services/agentSignal/constants.ts`
+
+Use `enqueueAgentSignalSourceEvent(...)` when the work should stay quiet and out-of-band. That path:
+
+1. normalizes the source envelope
+2. derives or reuses `scopeKey`
+3. triggers `AgentSignalWorkflow`
+4. executes later in `runAgentSignalWorkflow`
+
+This is the preferred path when the UI request should finish immediately and the policy can run in the background.
+
+Read:
+
+- `src/server/workflows/agentSignal/index.ts`
+- `src/server/workflows/agentSignal/run.ts`
+
+## Existing Example: `analyzeIntent`
+
+Use `analyzeIntent` as the reference chain:
+
+```text
+agent.user.message
+  -> feedback satisfaction source handler
+    -> signal.feedback.satisfaction
+      -> feedback domain signal handler
+        -> signal.feedback.domain.*
+          -> feedback action planner
+            -> action.user-memory.handle
+              -> signal.action.applied | skipped | failed
+```
+
+Read:
+
+- `src/server/services/agentSignal/policies/analyzeIntent/index.ts`
+- `src/server/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.ts`
+- `src/server/services/agentSignal/policies/analyzeIntent/feedbackDomain.ts`
+- `src/server/services/agentSignal/policies/analyzeIntent/feedbackAction.ts`
+- `src/server/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts`
@@ -0,0 +1,228 @@
+# Writing Handlers And Policies
+
+## Fluent Registration API
+
+Use the middleware helpers in `src/server/services/agentSignal/runtime/middleware.ts`.
+
+They provide:
+
+- `defineSourceHandler(...)`
+- `defineSignalHandler(...)`
+- `defineActionHandler(...)`
+- `defineAgentSignalHandlers(...)`
+
+These helpers do two jobs:
+
+1. keep handler registration terse
+2. preserve strong typing when `listen` points at concrete source, signal, or action types
+
+## Handler Shape
+
+Each handler receives:
+
+- the current runtime node
+- `RuntimeProcessorContext`
+
+The context gives you:
+
+- `scopeKey`
+- `now()`
+- `runtimeState.getGuardState(lane)`
+- `runtimeState.touchGuardState(lane, now?)`
+
+Read:
+
+- `src/server/services/agentSignal/runtime/context.ts`
+
+## Return Contracts
+
+Return one of these shapes:
+
+- `void`: no fan-out, stop at this handler
+- `{ status: 'dispatch', signals?, actions? }`: continue the chain
+- `{ status: 'wait', pending? }`: pause for later host coordination
+- `{ status: 'schedule', nextHop }`: schedule another hop
+- `{ status: 'conclude', concluded? }`: stop with a terminal runtime result
+- `ExecutorResult`: only for action handlers that performed a concrete side effect
+
+Read:
+
+- `packages/agent-signal/src/base/types.ts`
+- `src/server/services/agentSignal/runtime/AgentSignalScheduler.ts`
+
+## Policy Composition Pattern
+
+Use `defineAgentSignalHandlers([...])` to bundle related handlers into one policy.
+
+Example from `analyzeIntent`:
+
+```ts
+return defineAgentSignalHandlers([
+  createFeedbackSatisfactionJudgeProcessor(...),
+  createFeedbackDomainJudgeSignalHandler(...),
+  createFeedbackActionPlannerSignalHandler(),
+  defineUserMemoryActionHandler(...),
+]);
+```
+
+That bundle is later passed into the runtime via:
+
+- `createDefaultAgentSignalPolicies(...)`
+- `createAgentSignalRuntime({ policies })`
+
+Read:
+
+- `src/server/services/agentSignal/policies/index.ts`
+- `src/server/services/agentSignal/policies/analyzeIntent/index.ts`
+
+## Source Handler Pattern
+
+Use a source handler when you are interpreting a producer event into semantic signals.
+
+Reference:
+
+- `src/server/services/agentSignal/policies/analyzeIntent/feedbackSatisfaction.ts`
+
+Pattern:
+
+```ts
+return defineSourceHandler(
+  AGENT_SIGNAL_SOURCE_TYPES.agentUserMessage,
+  'agent.user.message:my-handler',
+  async (source, ctx): Promise<RuntimeProcessorResult | void> => {
+    // interpret source payload
+    // optionally use ctx.runtimeState
+
+    return {
+      signals: [
+        /* one or more semantic signals */
+      ],
+      status: 'dispatch',
+    };
+  },
+);
+```
+
+Write source handlers when:
+
+- a raw message, lifecycle event, or bot ingress needs interpretation
+- the work is still semantic, not side-effectful
+
+## Signal Handler Pattern
+
+Use a signal handler when one semantic state should branch into more semantic states or planned actions.
+
+References:
+
+- `src/server/services/agentSignal/policies/analyzeIntent/feedbackDomain.ts`
+- `src/server/services/agentSignal/policies/analyzeIntent/feedbackAction.ts`
+
+Pattern:
+
+```ts
+return defineSignalHandler(
+  MY_SIGNAL_TYPE,
+  'signal.my-policy-router',
+  async (signal): Promise<RuntimeProcessorResult | void> => {
+    return {
+      actions: [
+        /* planned work */
+      ],
+      status: 'dispatch',
+    };
+  },
+);
+```
+
+Use signal handlers for:
+
+- routing
+- fan-out
+- filtering
+- conflict resolution
+- converting interpretation into planned actions
+
+## Action Handler Pattern
+
+Use an action handler when the runtime should do actual work.
+
+Reference:
+
+- `src/server/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts`
+
+Pattern:
+
+```ts
+return defineActionHandler(
+  MY_ACTION_TYPE,
+  'action.my-policy-executor',
+  async (action, ctx): Promise<ExecutorResult> => {
+    // run service/tool/model side effect
+    // check idempotency if needed
+
+    return {
+      actionId: action.actionId,
+      attempt: {
+        completedAt: ctx.now(),
+        current: 1,
+        startedAt,
+        status: 'succeeded',
+      },
+      status: 'applied',
+    };
+  },
+);
+```
+
+Keep these rules:
+
+- perform idempotency checks here or immediately before side effects
+- return stable `actionId`
+- include failure detail in `error`
+- let the scheduler turn the `ExecutorResult` into built-in result signals
+
+## Source, Signal, And Action Type Placement
+
+Use this split:
+
+- external event payloads:
+  `src/server/services/agentSignal/sourceTypes.ts`
+- policy-owned signal and action payloads:
+  `src/server/services/agentSignal/policies/types.ts`
+- normalized shared node contracts:
+  `packages/agent-signal/src/base/types.ts`
+
+Do not put app-specific signal catalogs into `packages/agent-signal`. That package should stay generic and reusable.
+
+## Choosing The Right Node
+
+Choose `source` when:
+
+- the outside world emitted a new fact
+
+Choose `signal` when:
+
+- the system needs semantic meaning that downstream handlers can reuse
+
+Choose `action` when:
+
+- the runtime is ready for a concrete side effect
+
+If a handler both interprets meaning and performs side effects, split it. That keeps chains inspectable and testable.
+
+## Testing Strategy
+
+Prefer focused tests near the touched code.
+
+Useful references:
+
+- `src/server/services/agentSignal/runtime/__tests__/AgentSignalRuntime.test.ts`
+- `src/server/services/agentSignal/__tests__/index.integration.test.ts`
+- `src/server/services/agentSignal/policies/analyzeIntent/__tests__/*`
+- `src/server/services/agentSignal/policies/analyzeIntent/actions/__tests__/*`
+
+Test at the smallest level that proves the behavior:
+
+- handler unit test for one routing rule
+- runtime test for queue fan-out
+- integration test for service ingress and observability persistence
@@ -0,0 +1,118 @@
+# Observability And Debugging
+
+## OTEL Ownership
+
+Use `packages/observability-otel/src/modules/agent-signal/index.ts` for the shared tracer and metrics.
+
+Available instruments:
+
+- `tracer`
+- `sourceCounter`
+- `signalCounter`
+- `actionCounter`
+- `actionResultCounter`
+- `chainCounter`
+- `signalActionTransitionCounter`
+- `chainDurationHistogram`
+- `actionDurationHistogram`
+
+Use this module when you need shared telemetry ownership instead of creating feature-local meters or tracers.
+
+## Projection Pipeline
+
+After runtime execution, the service projects one compact observability model from the full chain.
+
+Read:
+
+- `src/server/services/agentSignal/observability/projector.ts`
+- `src/server/services/agentSignal/observability/traceEvents.ts`
+- `src/server/services/agentSignal/observability/store.ts`
+
+Projection outputs:
+
+- a trace envelope with source, signals, actions, results, edges, and handler runs
+- a compact telemetry record with dominant path, status breakdown, and chain metadata
+
+This projection is built from:
+
+- source node
+- emitted signals
+- planned actions
+- executor results
+
+## How To Inspect A Chain
+
+Use this order:
+
+1. Inspect the source type and payload.
+2. Inspect emitted signals.
+3. Inspect planned actions.
+4. Inspect executor results.
+5. Inspect projected edges and dominant path.
+
+The helper `toAgentSignalTraceEvents(...)` flattens a chain into compact event records suitable for tracing snapshots.
+
+## Workflow Snapshot Bridge
+
+Workflow-triggered runs do not naturally pass through the normal foreground runtime snapshot path, so `runAgentSignalWorkflow` adds a development-only bridge into `.agent-tracing/`.
+
+Read:
+
+- `src/server/workflows/agentSignal/run.ts`
+
+Use that path when:
+
+- the source was enqueued with `enqueueAgentSignalSourceEvent(...)`
+- you need local trace visibility for quiet background work
+
+## Common Debug Questions
+
+### The source emits but nothing happens
+
+Check:
+
+- feature gate enabled for the user
+- source type matches a registered source handler
+- dedupe or scope lock did not short-circuit generation
+
+Read:
+
+- `src/server/services/agentSignal/index.ts`
+- `src/server/services/agentSignal/sources/index.ts`
+
+### The signal exists but no action runs
+
+Check:
+
+- the signal type has a registered signal handler
+- the signal handler returns `status: 'dispatch'`
+- the handler actually returned actions
+
+### The action runs twice
+
+Check:
+
+- source dedupe key stability
+- action idempotency strategy
+- scope key stability across retries and workflow handoff
+
+Reference:
+
+- `src/server/services/agentSignal/policies/actionIdempotency.ts`
+- `src/server/services/agentSignal/policies/analyzeIntent/actions/userMemory.ts`
+
+### Background runs are hard to discover
+
+Check:
+
+- workflow snapshot bridge in development
+- projected telemetry record contents
+- OTEL counters and histograms in the shared module
+
+## Minimal Completion Checklist
+
+- source ingress is testable
+- handler registration is discoverable from the policy factory
+- action executor returns structured results
+- projection includes the new path cleanly
+- tests cover at least one happy path and one no-op or failure path
@@ -14,7 +14,7 @@ In `NODE_ENV=development`, `AgentRuntimeService.executeStep()` automatically rec

 **Data flow**: executeStep loop -> build `StepPresentationData` -> write partial snapshot to disk -> on completion, finalize to `.agent-tracing/{timestamp}_{traceId}.json`

-**Context engine capture**: In `RuntimeExecutors.ts`, the `call_llm` executor emits a `context_engine_result` event after `serverMessagesEngine()` processes messages. This event carries the full `contextEngineInput` (DB messages, systemRole, model, knowledge, tools, userMemory, etc.) and the processed `output` messages (the final LLM payload).
+**Context engine capture**: In `RuntimeExecutors.ts`, the `call_llm` executor calls `ctx.tracingContextEngine(input, output)` after `serverMessagesEngine()` processes messages. `AgentRuntimeService.executeStep` buffers the call per step and forwards it to `OperationTraceRecorder.appendStep` as the typed `contextEngine` field. CE flows through this side channel rather than the `events` array so its heavy payload (agentDocuments, systemRole, …) never enters the Redis state pipeline (LOBE-9110).

 ## Package Location

@@ -199,9 +199,10 @@ interface StepSnapshot {
  messages?: any[]; // DB messages before step
  context?: { phase: string; payload?: unknown; stepContext?: unknown };
  events?: Array<{ type: string; [key: string]: unknown }>;
-  // context_engine_result event contains:
-  //   input: full contextEngineInput (messages, systemRole, model, knowledge, tools, userMemory, ...)
-  //   output: processed messages array (final LLM payload)
+  contextEngine?: {
+    input?: unknown; // contextEngineInput minus messages + toolsConfig (reconstructible from baseline)
+    output?: unknown; // processed messages array (final LLM payload)
+  };
 }
 ```

@@ -216,5 +217,5 @@ When using `--messages`, the output shows three sections (if context engine data
 ## Integration Points

 - **Recording**: `src/server/services/agentRuntime/AgentRuntimeService.ts` — in the `executeStep()` method, after building `stepPresentationData`, writes partial snapshot in dev mode
- **Context engine event**: `src/server/modules/AgentRuntime/RuntimeExecutors.ts` — in `call_llm` executor, after `serverMessagesEngine()` returns, emits `context_engine_result` event
+- **Context engine capture**: `src/server/modules/AgentRuntime/RuntimeExecutors.ts` — in `call_llm` executor, after `serverMessagesEngine()` returns, calls `ctx.tracingContextEngine(input, output)`. `AgentRuntimeService.executeStep` buffers it per step and passes it to `traceRecorder.appendStep` as the typed `contextEngine` field (kept off the `events` array to stay out of Redis state).
 - **Store**: `FileSnapshotStore` reads/writes to `.agent-tracing/` relative to `process.cwd()`
@@ -1,298 +0,0 @@
---
-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,130 @@
+---
+name: builtin-tool
+description: Build a new builtin tool package under `packages/builtin-tool-<name>/`. Use when adding a new agent-callable toolset, designing its API surface (manifest / ApiName / Params / State), implementing the Executor + ExecutionRuntime, building the Inspector / Render / Placeholder / Streaming / Intervention / Portal UI, or wiring a tool into the central registries (`packages/builtin-tools/src/{index,identifiers,inspectors,renders,placeholders,streamings,interventions,portals}.ts` and `src/store/tool/slices/builtin/executors/index.ts`). Triggers on "new builtin tool", "add a tool", "tool inspector", "tool render", "tool placeholder", "tool streaming", "tool intervention", "BuiltinToolManifest", "BaseExecutor", "ExecutionRuntime".
+---
+
+# Builtin Tool Authoring Guide
+
+A builtin tool is a package the agent runtime can call. It ships **five faces**:
+
+| Face                 | Lives in                                                                               | Audience                              |
+| -------------------- | -------------------------------------------------------------------------------------- | ------------------------------------- |
+| **Manifest + types** | `src/{manifest,types,systemRole}.ts`                                                   | The LLM (tool spec + system prompt)   |
+| **ExecutionRuntime** | `src/ExecutionRuntime/`                                                                | Server / desktop / any runtime caller |
+| **Executor**         | `src/client/executor/`                                                                 | Frontend (wraps stores/services)      |
+| **Client UI**        | `src/client/{Inspector,Render,…}/`                                                     | Chat UI                               |
+| **Registry wiring**  | `packages/builtin-tools/src/*.ts` + `src/store/tool/slices/builtin/executors/index.ts` | Framework                             |
+
+---
+
+## Read These First
+
+| Question                                                                             | Doc                                           |
+| ------------------------------------------------------------------------------------ | --------------------------------------------- |
+| Where do files live? What does each face do? Wiring?                                 | [architecture.md](references/architecture.md) |
+| How do I name the tool, design APIs, write the manifest, executor, ExecutionRuntime? | [tool-design.md](references/tool-design.md)   |
+| How do I build Inspector / Render / Placeholder / Streaming / Intervention / Portal? | [ui.md](references/ui.md)                     |
+
+---
+
+## When to Use This Skill
+
+- Creating a new `packages/builtin-tool-<name>/` package
+- Adding a new API method to an existing builtin tool
+- Building or restyling any of the 6 client surfaces for a tool
+- Wiring a tool into the central registries
+- Debugging "tool not found / API not found / render not showing / placeholder stuck" errors
+
+---
+
+## Top-Level Design Principles
+
+1. **`lobe-<domain>` identifier is permanent.** It's stored in message history. Renames need `@deprecated` aliases (see `packages/builtin-tools/src/inspectors.ts:88-89`). Get it right the first time.
+2. **ApiName is an `as const` object**, not a TS enum. It doubles as the runtime list `BaseExecutor` iterates over.
+3. **Three result fields, three audiences:**
+   - `content: string` → the LLM reads it
+   - `state: Record<…>` → the UI's `pluginState`; **result-domain only**, never echo all params back
+   - `error: { type, message, body? }` → both LLM and UI; `type` is a stable code
+4. **Split execution from frontend wiring.**
+   - `src/ExecutionRuntime/` — pure runtime, no React, no Zustand, accepts services via constructor. **The default place for new logic.**
+   - `src/client/executor/` — `BaseExecutor` subclass that calls `ExecutionRuntime` (or stores/services directly when frontend-only).
+5. **UI defaults to "do nothing".** Inspector is required (the header strip). Render/Placeholder/Streaming/Intervention/Portal are added **only when there's something specific to show** — empty registries are fine.
+6. **Style with `createStaticStyles + cssVar.*`** (zero-runtime). Fall back to `createStyles + token` only when you genuinely need runtime values. Use `@lobehub/ui` components, not raw antd.
+7. **i18n keys live in `src/locales/default/plugin.ts`.** Inspector titles must come from `t('builtins.<identifier>.apiName.<api>')` so something renders while args stream.
+
+---
+
+## Package Layout (preferred, post-2026 convention)
+
+```
+packages/builtin-tool-<name>/
+├── package.json
+└── src/
+    ├── index.ts              # exports manifest + types + systemRole + Identifier (no React, no stores)
+    ├── manifest.ts           # BuiltinToolManifest with JSON Schema for every API
+    ├── types.ts              # ApiName const + Params/State interfaces per API
+    ├── systemRole.ts         # System prompt teaching the model when/how to use the APIs
+    ├── ExecutionRuntime/     # ✅ Default home for runtime logic (server- or anywhere-callable)
+    │   └── index.ts
+    └── client/
+        ├── index.ts          # Re-exports for the registries
+        ├── executor/         # ✅ Frontend executor — extends BaseExecutor, often delegates to ExecutionRuntime
+        │   └── index.ts
+        ├── Inspector/        # required — header chip per API
+        ├── Render/           # optional — rich result card
+        ├── Placeholder/      # optional — skeleton during streaming/execution
+        ├── Streaming/        # optional — live output renderer (e.g. RunCommand, WriteFile)
+        ├── Intervention/     # optional — approval / edit-before-run UI
+        ├── Portal/           # optional — full-screen detail view
+        └── components/       # shared subcomponents used by the surfaces above
+```
+
+**Older packages** (`builtin-tool-task`, `builtin-tool-calculator`, etc.) still have `src/executor/` as a sibling of `src/client/`. That's grandfathered; **don't relocate without a deliberate refactor**. New packages and new APIs added to existing packages should follow the layout above.
+
+`package.json` exports map:
+
+```json
+"exports": {
+  ".":                  "./src/index.ts",
+  "./client":           "./src/client/index.ts",
+  "./executor":         "./src/client/executor/index.ts",
+  "./executionRuntime": "./src/ExecutionRuntime/index.ts"
+}
+```
+
+---
+
+## Authoring Checklist
+
+Before opening the PR:
+
+- [ ] Identifier follows `lobe-<domain>` and is **stable** (lives in message history).
+- [ ] Every `<Name>ApiName` value has: a manifest `api[]` entry, an executor method, an Inspector, an i18n `apiName.*` key.
+- [ ] `Params` interfaces match the JSON Schema; `State` interfaces match what the executor returns and what the UI surfaces read.
+- [ ] System prompt disambiguates confusable APIs and points to batch variants.
+- [ ] Runtime logic lives in `ExecutionRuntime/`; the `client/executor/` only wires stores/services and delegates.
+- [ ] Executor returns `{ success, content, state, error? }` via a single `toResult()` funnel — `content` always non-empty (default to `error.message`).
+- [ ] Inspector handles `isArgumentsStreaming`, `isLoading`, `partialArgs`, missing `pluginState`.
+- [ ] Render returns `null` until it has data; only created for APIs with rich results.
+- [ ] Placeholder added if the API has a perceivable execution lag (search, list, crawl).
+- [ ] Streaming added for APIs that emit incremental output (run command, write file, code execution).
+- [ ] Intervention added if `humanIntervention` is set in the manifest.
+- [ ] All registry files updated (see [architecture.md → Registry wiring](references/architecture.md#registry-wiring)).
+- [ ] i18n keys in `src/locales/default/plugin.ts` plus dev seeds in `en-US`/`zh-CN`.
+- [ ] `bunx vitest run --silent='passed-only' 'packages/builtin-tool-<name>'` passes.
+- [ ] `bun run type-check` passes.
+
+---
+
+## Reference Tools
+
+Pick the closest neighbor and copy:
+
+| If your tool is…                                                        | Read first                                                                                                     |
+| ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Pure-compute, no UI state                                               | `packages/builtin-tool-calculator/` — `ExecutionRuntime` reuses executor (mathjs/nerdamer work everywhere)     |
+| CRUD over a domain entity                                               | `packages/builtin-tool-task/` — full Inspector + Render set, batch variants                                    |
+| Heavy UI (Inspector/Render/Placeholder/Portal)                          | `packages/builtin-tool-web-browsing/` — search-style result UI, Portal for detail view                         |
+| Desktop / filesystem with all surfaces (incl. Streaming + Intervention) | `packages/builtin-tool-local-system/` — `ExecutionRuntime` injects an `ILocalSystemService`, executor calls it |
+| Server-side pure (no client executor)                                   | `packages/builtin-tool-web-browsing/` — only `ExecutionRuntime` is exported; the chat client doesn't run it    |
+| Needs human approval before running                                     | `packages/builtin-tool-local-system/src/client/Intervention/` — per-API approval components                    |
@@ -0,0 +1,315 @@
+# Builtin Tool Architecture
+
+## The Five Faces
+
+A builtin tool ships five distinct faces, each compiled into a different bundle:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ ./                                                              │
+│   Manifest + Types + systemRole                                 │
+│   ─ Pure data, no React, no Node-only deps.                     │
+│   ─ Imported by: server (LLM tool spec), client (registries),   │
+│     anyone who needs to know "what tools exist".                │
+└─────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ ./executionRuntime                                              │
+│   src/ExecutionRuntime/index.ts                                 │
+│   ─ Pure runtime logic. Accepts services via constructor —      │
+│     never imports concrete services or stores directly.         │
+│   ─ Imported by: server (BuiltinServerRuntimeOutput), tests,    │
+│     and the client executor as a delegate.                      │
+│   ─ Returns: BuiltinServerRuntimeOutput { content, state, … }   │
+└─────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ ./executor                                                      │
+│   src/client/executor/index.ts                                  │
+│   ─ BaseExecutor subclass. Wires Zustand stores and frontend    │
+│     services into ExecutionRuntime, then funnels through        │
+│     toResult() into BuiltinToolResult { content, state, error,  │
+│     success }.                                                  │
+│   ─ Imported by: src/store/tool/slices/builtin/executors/       │
+│     index.ts (registered as a singleton).                       │
+└─────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ ./client                                                        │
+│   src/client/{Inspector,Render,Placeholder,Streaming,           │
+│              Intervention,Portal,components}/                   │
+│   ─ React 'use client' surfaces. Read args + pluginState.       │
+│   ─ Imported by: packages/builtin-tools/src/{inspectors,        │
+│     renders,placeholders,streamings,interventions,portals}.ts.  │
+└─────────────────────────────────────────────────────────────────┘
+                          │
+                          ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Registry wiring                                                 │
+│   packages/builtin-tools/src/*.ts                               │
+│   src/store/tool/slices/builtin/executors/index.ts              │
+│   ─ Aggregator maps: identifier → { apiName → component }.      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+The split exists so:
+
+- Server bundles import only `./` and `./executionRuntime` and never touch React.
+- Frontend bundles import `./client` and never touch Node-only services.
+- The runtime is testable without React or Electron present.
+
+---
+
+## Why ExecutionRuntime is the Default Home for Logic
+
+**Old pattern (grandfathered):** business logic in `src/executor/` directly. Examples: `builtin-tool-task`, older tools. Works, but the executor mixes runtime logic with frontend service plumbing — hard to reuse on the server.
+
+**New pattern (preferred):** business logic in `src/ExecutionRuntime/`, frontend wiring in `src/client/executor/`. Examples: `builtin-tool-local-system`, `builtin-tool-web-browsing`, `builtin-tool-calculator`.
+
+```
+ExecutionRuntime
+  ├─ accepts services via constructor (or `static create(opts)`)
+  ├─ returns BuiltinServerRuntimeOutput (content + state + success)
+  └─ no React, no Zustand, no `@/services/...` direct imports
+
+client/executor
+  ├─ extends BaseExecutor<typeof <Name>ApiName>
+  ├─ holds a `runtime = new <Name>ExecutionRuntime(realService)` instance
+  ├─ each ApiName method:
+  │     1. resolve scope / pull defaults from BuiltinToolContext
+  │     2. call runtime.<method>(args)
+  │     3. funnel through toResult() → BuiltinToolResult
+  └─ exported singleton: export const <name>Executor = new <Name>Executor()
+```
+
+### Service injection
+
+`ExecutionRuntime` should declare a TypeScript interface for the services it needs and accept the implementation via constructor. Server callers wire in real implementations; tests wire in mocks. Example from `local-system`:
+
+```ts
+export interface ILocalSystemService {
+  readLocalFile: (params: any) => Promise<any>;
+  writeFile: (params: any) => Promise<any>;
+  /* … */
+}
+
+export class LocalSystemExecutionRuntime extends ComputerRuntime {
+  constructor(private service: ILocalSystemService) {
+    super();
+  }
+  /* methods delegate to this.service.* */
+}
+```
+
+The `client/executor` instantiates it once with the real service:
+
+```ts
+import { localFileService } from '@/services/electron/localFileService';
+import { LocalSystemExecutionRuntime } from '../../ExecutionRuntime';
+
+class LocalSystemExecutor extends BaseExecutor<typeof LocalSystemApiEnum> {
+  private runtime = new LocalSystemExecutionRuntime(localFileService);
+  /* … */
+}
+```
+
+### When ExecutionRuntime is the only thing you ship
+
+Some tools are server-only — there's no frontend executor. `builtin-tool-web-browsing` is the canonical example: only `./` and `./executionRuntime` are exported, no `./executor`, and the runtime is constructed by the server-side `ToolExecutionService`. Skip `client/executor/` entirely for those.
+
+### When the executor reuses the runtime as-is
+
+Pure-compute tools (`builtin-tool-calculator`) often have an executor whose ApiName methods call `executor.calculate(args)` and an `ExecutionRuntime` whose methods call `calculatorExecutor.calculate(args)` — same logic, two thin wrappers. That's fine; the duplication buys you the bundle split.
+
+---
+
+## The Result Contract
+
+### `BuiltinServerRuntimeOutput` (what ExecutionRuntime returns)
+
+```ts
+{
+  content: string;        // the LLM-facing text — never undefined; default to error message
+  state?: any;            // result-domain object the UI reads as pluginState
+  success: boolean;       // mandatory
+  error?: any;            // raw error; the executor will repackage
+}
+```
+
+### `BuiltinToolResult` (what the executor returns to the runtime)
+
+```ts
+{
+  success: boolean;
+  content?: string;
+  state?: any;
+  error?: { type: string; message: string; body?: any };
+  metadata?: Record<string, any>;   // rare; e.g. { agentCouncil: true }
+  stop?: boolean;                   // rare; halt the orchestration step
+}
+```
+
+### The `toResult` funnel (mandatory)
+
+Every executor method returns through a single `toResult()` to enforce two invariants:
+
+1. **`content` is never undefined.** A missing content collapses downstream into `''`, leaving the Debug pane blank while `pluginState` was already saved. See the `globLocalFiles` regression in `local-system/src/client/executor/index.ts:60-84`.
+2. **`state` survives failures.** Renderers can keep showing partial output even when `success: false`.
+
+```ts
+private toResult(output: BuiltinServerRuntimeOutput): BuiltinToolResult {
+  const errorMessage = typeof output.error?.message === 'string' ? output.error.message : undefined;
+  const safeContent  = output.content || errorMessage || 'Tool execution failed';
+
+  if (!output.success) {
+    return {
+      success: false,
+      content: safeContent,
+      state:   output.state,
+      error:   output.error
+        ? { type: 'PluginServerError', message: errorMessage ?? safeContent, body: output.error }
+        : undefined,
+    };
+  }
+  return { success: true, content: safeContent, state: output.state };
+}
+```
+
+---
+
+## `BaseExecutor` — How Method Dispatch Works
+
+`BaseExecutor.invoke(apiName, params, ctx)` does:
+
+```ts
+if (!this.hasApi(apiName)) return { error: { type: 'ApiNotFound', … }, success: false };
+return (this as any)[apiName](params, ctx);   // method name MUST equal apiName value
+```
+
+So:
+
+- **Method names must equal `<Name>ApiName` values, exactly.** A typo silently routes to "ApiNotFound".
+- **Methods must be class fields, not class methods**, because `this` is lost when registry calls `executor.invoke(apiName, params, ctx)`. Always declare as `methodName = async (…) => { … }`.
+- **Always destructure `apiEnum` and `identifier` as `readonly` instance fields**, not getters — `BaseExecutor.hasApi/getApiNames` reads them synchronously.
+
+---
+
+## `BuiltinToolContext` — What the Executor Receives
+
+The runtime hands every executor method an optional `BuiltinToolContext` as the second argument:
+
+| Field                         | Use                                                            |
+| ----------------------------- | -------------------------------------------------------------- |
+| `agentId`                     | Default agent for "current agent" semantics (e.g. `listTasks`) |
+| `groupId`                     | Group chat scope                                               |
+| `topicId`                     | Current topic — needed when creating messages/operations       |
+| `taskId`                      | Current task identifier — fallback for "implicit" param        |
+| `documentId`                  | Current page/document scope                                    |
+| `messageId`                   | The tool message being created (for state attachments)         |
+| `sourceMessageId`             | The user message that triggered this tool turn                 |
+| `operationId`                 | Operation lineage (use for cancellation, tracing)              |
+| `scope`                       | `'task' \| 'agent' \| …` — toggles default behaviors           |
+| `signal: AbortSignal`         | Honor for long-running ops                                     |
+| `stepContext`                 | Cross-message runtime state (lobe-agent todos, etc.)           |
+| `registerAfterCompletion(cb)` | Defer side-effects past message-update race                    |
+| `groupOrchestration`          | Group orchestration callbacks                                  |
+
+**Use rule:** read with `?.`, fall back to explicit params, **never silently override** an explicit param with a context value.
+
+---
+
+## i18n Integration
+
+Source of truth: `src/locales/default/plugin.ts`. Keys follow `builtins.<identifier>.<topic>.<…>`:
+
+| Key                                   | Use                                                          |
+| ------------------------------------- | ------------------------------------------------------------ |
+| `builtins.<identifier>.title`         | Display title (overrides `manifest.meta.title` when present) |
+| `builtins.<identifier>.apiName.<api>` | Inspector header label (one per ApiName)                     |
+| `builtins.<identifier>.inspector.<…>` | Extra Inspector strings ("no results", chips, counters)      |
+| `builtins.<identifier>.<feature>.<…>` | Render / Intervention strings, free-form per tool            |
+
+For dev preview, also seed `locales/zh-CN/plugin.json` and `locales/en-US/plugin.json`. Run `pnpm i18n` before opening a PR — it's slow, so do it once at the end. (See the **i18n** skill for the full workflow.)
+
+---
+
+## Registry Wiring
+
+Five core files plus optional ones. Miss any and you'll see "tool not found", a missing chip, a blank result card, a stuck spinner, or an approval dialog that never appears.
+
+| File                                               | Add what                                                                                  |
+| -------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| **Required**                                       |                                                                                           |
+| `packages/builtin-tools/src/index.ts`              | Import `<Name>Manifest`; push entry to `builtinTools`. Set `hidden`/`discoverable` flags. |
+| `packages/builtin-tools/src/identifiers.ts`        | Add `<Name>Manifest.identifier` to `builtinToolIdentifiers`.                              |
+| `packages/builtin-tools/src/inspectors.ts`         | Import `<Name>Inspectors, <Name>Manifest`; add to `BuiltinToolInspectors`.                |
+| `src/store/tool/slices/builtin/executors/index.ts` | Import `<name>Executor`; add to `registerExecutors([…])`.                                 |
+| **Conditional — add only if the surface exists**   |                                                                                           |
+| `packages/builtin-tools/src/renders.ts`            | Add to `BuiltinToolsRenders` if any API has a Render.                                     |
+| `packages/builtin-tools/src/placeholders.ts`       | Add to `BuiltinToolPlaceholders` if any API has a Placeholder.                            |
+| `packages/builtin-tools/src/streamings.ts`         | Add to `BuiltinToolStreamings` if any API has a Streaming renderer.                       |
+| `packages/builtin-tools/src/interventions.ts`      | Add to `BuiltinToolInterventions` if any API has an Intervention component.               |
+| `packages/builtin-tools/src/portals.ts`            | Add to `BuiltinToolsPortals` if the tool has a Portal.                                    |
+| `packages/builtin-tools/src/displayControls.ts`    | Add if Render must show/hide based on result content (rare; see ClaudeCode/Codex).        |
+
+### Optional flags in `packages/builtin-tools/src/index.ts`
+
+```ts
+{
+  identifier: TaskManifest.identifier,
+  manifest:   TaskManifest,
+  type:       'builtin',
+  hidden:        true,   // hide from chat-input Tools popover
+  discoverable:  false,  // exclude from agent builder / skill discovery
+}
+```
+
+Lists in the same file you may need to touch:
+
+- `defaultToolIds` — added to the agent's tool list by default
+- `alwaysOnToolIds` — forced on regardless of user selection (use sparingly)
+- `runtimeManagedToolIds` — enable state controlled by runtime, not user UI; **must mirror the rules map** in `src/server/modules/Mecha/AgentToolsEngine/index.ts` and `src/helpers/toolEngineering/index.ts`
+
+---
+
+## File-Map at a Glance
+
+```
+packages/builtin-tool-<name>/
+├── package.json                          # exports: ., ./client, ./executor, ./executionRuntime
+└── src/
+    ├── index.ts                          # export Manifest, Identifier, types, systemPrompt
+    ├── manifest.ts                       # BuiltinToolManifest + Identifier const
+    ├── types.ts                          # ApiName + Params/State per API
+    ├── systemRole.ts                     # System prompt (multiple variants OK: systemRole.desktop.ts)
+    ├── ExecutionRuntime/
+    │   └── index.ts                      # <Name>ExecutionRuntime — pure runtime, service injection
+    └── client/
+        ├── index.ts                      # exports for the registries
+        ├── executor/
+        │   └── index.ts                  # <Name>Executor extends BaseExecutor; export <name>Executor
+        ├── Inspector/
+        │   ├── index.ts                  # <Name>Inspectors record
+        │   └── <ApiName>/index.tsx       # one folder per API (or .tsx file when trivial)
+        ├── Render/
+        │   ├── index.ts                  # <Name>Renders record
+        │   └── <ApiName>/                # rich renders → folder with subcomponents
+        ├── Placeholder/
+        │   ├── index.ts
+        │   └── <ApiName>.tsx             # usually a single skeleton file
+        ├── Streaming/
+        │   ├── index.ts
+        │   └── <ApiName>/                # live-output renderer
+        ├── Intervention/
+        │   ├── index.ts
+        │   └── <ApiName>/                # approval / edit-before-run UI
+        ├── Portal/
+        │   ├── index.tsx                 # routing component (switch on apiName)
+        │   └── <ApiName>/                # full-screen detail view
+        └── components/                   # FileItem, EngineAvatar, etc. — shared subcomponents
+```
+
+Skip every `client/<surface>/` directory you don't need — empty registries are fine.
@@ -0,0 +1,478 @@
+# Tool Design (Naming, Manifest, Executor, Runtime)
+
+This doc covers everything that **isn't UI**: the tool's identifier, API surface, manifest, types, system prompt, ExecutionRuntime, and the executor that wires it into the frontend.
+
+For UI surfaces (Inspector / Render / Placeholder / Streaming / Intervention / Portal), see [ui.md](ui.md).
+For where files live and how registries work, see [architecture.md](architecture.md).
+
+---
+
+## 1. Naming
+
+| Thing                   | Convention                                                     | Example                                                      |
+| ----------------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
+| Package directory       | `packages/builtin-tool-<kebab>/`                               | `builtin-tool-task`                                          |
+| npm name                | `@lobechat/builtin-tool-<kebab>`                               | `@lobechat/builtin-tool-task`                                |
+| Tool `identifier`       | `lobe-<kebab-domain>` — **persisted in message history**       | `lobe-task`, `lobe-calculator`, `lobe-knowledge-base`        |
+| Identifier const        | `<Name>Identifier` exported from `manifest.ts` (or `types.ts`) | `export const TaskIdentifier = 'lobe-task'`                  |
+| API name const          | `<Name>ApiName` — `as const` object, **camelCase verbs**       | `createTask`, `listTasks`, `runTask`                         |
+| Executor class          | `<Name>Executor extends BaseExecutor<typeof <Name>ApiName>`    | `TaskExecutor`                                               |
+| Executor singleton      | `<name>Executor` (camelCase)                                   | `export const taskExecutor = new TaskExecutor()`             |
+| ExecutionRuntime class  | `<Name>ExecutionRuntime`                                       | `LocalSystemExecutionRuntime`, `WebBrowsingExecutionRuntime` |
+| Inspector / Render etc. | `<ApiName>Inspector` / `<ApiName>Render`                       | `CreateTaskInspector`, `SearchInspector`                     |
+
+### Identifier rules
+
+- **`lobe-` prefix is mandatory** — many switches in the codebase key off it.
+- Pick a **domain noun**, not a verb (`lobe-task`, not `lobe-task-manager`).
+- The identifier is **persisted in message history** — renaming after release means the `@deprecated` alias trick (register the legacy identifier as a second key in `inspectors.ts` / `renders.ts` pointing at the new module). Get it right the first time.
+
+### ApiName rules
+
+- Verb + noun, camelCase: `createTask`, `viewTask`, `runTasks`.
+- **Plural variant for batch** (`createTasks`, `runTasks`) — describe in the manifest description that it's preferred over multiple single calls. The system prompt should also push the batch form.
+- Reserve **clear separation between mutating verbs** (`updateTaskStatus`, `editTask`) and **execution verbs** (`runTask`). The system prompt must warn the model when these are confusable — see `task` for the canonical "do NOT use updateTaskStatus(running) to start a task" warning.
+- Read-only verbs: `list*`, `view*`, `get*`, `search*`. Mutating: `create*`, `edit*`, `update*`, `delete*`. Triggers/effects: `run*`, `execute*`, `submit*`.
+
+---
+
+## 2. `types.ts` — ApiName + Params/State
+
+Define `<Name>ApiName` as `as const` so it doubles as a runtime enum (used by `BaseExecutor`) and a literal type. Then declare `Params` and `State` per API.
+
+```ts
+export const TaskIdentifier = 'lobe-task';
+
+export const TaskApiName = {
+  createTask: 'createTask',
+  createTasks: 'createTasks',
+  listTasks: 'listTasks',
+  /* …one entry per API, group logically (CRUD then run-style) */
+} as const;
+
+export type TaskApiNameType = (typeof TaskApiName)[keyof typeof TaskApiName];
+
+// One block per API
+export interface CreateTaskParams {
+  name: string;
+  instruction: string; /* … */
+}
+export interface CreateTaskState {
+  identifier?: string;
+  success: boolean;
+}
+
+export interface CreateTasksParams {
+  tasks: CreateTaskParams[];
+}
+export interface CreateTasksItemResult {
+  error?: string;
+  identifier?: string;
+  name: string;
+  success: boolean;
+}
+export interface CreateTasksState {
+  failed: number;
+  results: CreateTasksItemResult[];
+  succeeded: number;
+}
+```
+
+**The result-domain rule for `State`** (memory: "pluginState is result-domain, not call-domain"):
+
+- Include only fields the UI **renders after the call returns** — ids the LLM didn't have when calling, counts, summary numbers, server-assigned status.
+- **Don't echo all params.** The Inspector/Render gets `args` for free.
+- Keep batch results as `{ succeeded, failed, results }` so the Render can show a one-line summary plus a detail list.
+
+---
+
+## 3. `manifest.ts` — JSON Schema for the LLM
+
+```ts
+import type { BuiltinToolManifest } from '@lobechat/types';
+
+import { systemPrompt } from './systemRole';
+import { TaskApiName, TaskIdentifier } from './types';
+
+export const TaskManifest: BuiltinToolManifest = {
+  identifier: TaskIdentifier,
+  type: 'builtin',
+  systemRole: systemPrompt,
+  meta: {
+    avatar: '📋',
+    title: 'Task Tools',
+    description: 'Create, list, edit, delete tasks with dependencies',
+    readme: 'Optional long description shown in tool detail pages',
+  },
+  api: [
+    {
+      name: TaskApiName.createTask,
+      description:
+        'Create a new task. Optionally attach as a subtask via parentIdentifier. ' +
+        'Prefer createTasks when planning a batch.',
+      parameters: {
+        type: 'object',
+        required: ['name', 'instruction'],
+        properties: {
+          name: { type: 'string', description: 'Short, descriptive name.' },
+          instruction: {
+            type: 'string',
+            description: 'Detailed instruction for what the task should accomplish.',
+          },
+          parentIdentifier: {
+            type: 'string',
+            description:
+              'Identifier of the parent task (e.g. "TASK-1"). If provided, the new task becomes a subtask.',
+          },
+          priority: {
+            type: 'number',
+            description: 'Priority level: 0=none, 1=urgent, 2=high, 3=normal, 4=low. Default is 0.',
+          },
+        },
+      },
+    },
+    /* …one entry per ApiName */
+  ],
+};
+```
+
+### Manifest writing checklist
+
+- **Every API in `<Name>ApiName` has exactly one entry in `api[]`.** Easy to drift after a refactor.
+- **`description` on each API is the model's only docs.** Make it long enough for the LLM to pick the right tool. Mention edge cases ("If you provide any filter, omitted filters are not applied implicitly"), defaults, and the relationship to sibling APIs ("To START a task, use runTask — updateTaskStatus only flips a flag").
+- **`parameters` is JSON Schema** (`LobeChatPluginApi`). Use `enum`, `required`, `items`, `oneOf`, `additionalProperties: false` etc. — these survive into the LLM's tool spec.
+- **Use `additionalProperties: false`** on parameter objects so the model can't sneak unknown fields past validation.
+- **Number parameters with semantic values** (`priority: 0=none, 1=urgent, …`) should describe the mapping in the description. Don't rely on `enum` alone for numbers — the model often fills the wrong one.
+- **`enum` arrays for known string sets** (statuses, categories, engines). Spread from a constants module (`enum: [...TASK_STATUSES]`) so the manifest stays in sync.
+
+### Optional manifest fields
+
+```ts
+{
+  /* Where this tool can run.
+     'client'  → Agent Gateway dispatches to the desktop client (filesystem, Electron only)
+     'server'  → ToolExecutionService runs it on the server
+     omitted   → server only */
+  executors: ['client', 'server'],
+
+  /* Default human intervention policy for all APIs that don't specify one.
+     Pair with an Intervention component (see ui.md). */
+  humanIntervention: 'never' | 'always' | { /* extended config */ },
+}
+```
+
+Per-API `humanIntervention` and `renderDisplayControl` go inside each `api[]` entry.
+
+---
+
+## 4. `systemRole.ts` — Operator Instructions for the Model
+
+This is appended to the agent system prompt whenever the tool is enabled. Treat it as a **how-to-use guide for the LLM**, not marketing copy.
+
+```ts
+export const systemPrompt = `You have access to Task management tools. Use them to:
+
+- **createTask**: Create a new task. Use parentIdentifier to make it a subtask.
+- **createTasks**: Prefer this over multiple createTask calls when planning a batch
+  (e.g. all subtasks under one parent, or all chapters of an outline).
+- **runTask**: Actually START a task — kicks off the agent in a new (or continued)
+  topic. Do NOT use updateTaskStatus(running) to start a task; that only flips a
+  flag without executing. The task must have an assigneeAgentId.
+- **updateTaskStatus**: Change a task's status (completed/cancelled/paused/failed).
+  If you mark a task as failed, include an error message explaining why.
+- ...
+
+When planning work:
+1. Create tasks for each major piece (use parentIdentifier to organize as subtasks).
+2. Use editTask with addDependencies to control execution order.
+3. Use updateTaskStatus to mark the current task completed when done.`;
+```
+
+### Patterns that work well
+
+- **Bulleted list, bold the API name, one line per API.** The model picks tools by skimming.
+- **Disambiguate confusable APIs explicitly** (`runTask` vs `updateTaskStatus`).
+- **Push toward batched APIs** ("Prefer this when…").
+- **End with a numbered workflow** if the tool has a typical sequence.
+- **For tools with multiple environments** (e.g. desktop vs cloud), keep variants in `systemRole.ts` and `systemRole.desktop.ts` and pick at the manifest level. See `builtin-tool-local-system`.
+
+### Dynamic system prompts
+
+If the prompt depends on runtime state (current date, available models), export a function and call it in the manifest:
+
+```ts
+// systemRole.ts
+export const systemPrompt = (today: string) => `Today is ${today}. You have web search tools…`;
+
+// manifest.ts
+import dayjs from 'dayjs';
+systemRole: systemPrompt(dayjs(new Date()).format('YYYY-MM-DD')),
+```
+
+---
+
+## 5. `ExecutionRuntime/index.ts` — Pure Runtime
+
+This is **the default home for new tool logic** going forward. The runtime is a class that:
+
+- Has no React, no Zustand, no `@/services/...` direct imports.
+- Receives services as **constructor injection** (or as method args).
+- Returns `BuiltinServerRuntimeOutput` from each method.
+- Is unit-testable by passing in mocks.
+
+### Pattern A: Inject a service interface
+
+Use when the runtime calls out to IPC, network, or DB.
+
+```ts
+// ExecutionRuntime/index.ts
+import type { BuiltinServerRuntimeOutput } from '@lobechat/types';
+
+export interface IWebBrowsingService {
+  search: (q: SearchQuery) => Promise<UniformSearchResponse>;
+  crawlPages: (urls: string[]) => Promise<CrawlResults>;
+}
+
+export interface WebBrowsingRuntimeOptions {
+  searchService: IWebBrowsingService;
+  documentService?: WebBrowsingDocumentService;
+  agentId?: string;
+  topicId?: string;
+}
+
+export class WebBrowsingExecutionRuntime {
+  constructor(private opts: WebBrowsingRuntimeOptions) {}
+
+  async search(
+    args: SearchQuery,
+    options?: { signal?: AbortSignal },
+  ): Promise<BuiltinServerRuntimeOutput> {
+    try {
+      const data = await this.opts.searchService.search(args, options);
+      if (data.errorDetail) {
+        return {
+          success: false,
+          content: data.errorDetail,
+          error: { message: data.errorDetail },
+          state: data,
+        };
+      }
+      return {
+        success: true,
+        content: searchResultsPrompt(data.results.slice(0, 10)),
+        state: data,
+      };
+    } catch (e) {
+      return { success: false, content: (e as Error).message, error: e };
+    }
+  }
+}
+```
+
+### Pattern B: Reuse the executor
+
+Use when the same logic runs in browser and Node (e.g. mathjs, nerdamer). The runtime is a thin wrapper that imports the executor and re-types the state per API. See `builtin-tool-calculator/src/ExecutionRuntime/index.ts` for the canonical example.
+
+### Pattern C: Extend a shared base
+
+When you're implementing a domain that already has a base runtime (file ops via `ComputerRuntime`), extend and only override `callService` + result normalization. See `builtin-tool-local-system/src/ExecutionRuntime/index.ts`.
+
+### Runtime contract
+
+Every method returns:
+
+```ts
+{
+  content: string;       // LLM-facing — never undefined; default to error message
+  state?: any;           // result-domain — what the UI's pluginState becomes
+  success: boolean;      // mandatory
+  error?: any;           // raw error object; the executor will repackage
+}
+```
+
+Use `@lobechat/prompts` formatters (`searchResultsPrompt`, `crawlResultsPrompt`, `formatTaskCreated`, etc.) to produce structured `content`. They emit XML/markdown that's already tuned for token efficiency.
+
+---
+
+## 6. `client/executor/index.ts` — Frontend Wiring
+
+The executor's job is to **resolve frontend defaults** (current agent, current task, scope) and **call the runtime**. It then funnels through `toResult()` into the `BuiltinToolResult` shape.
+
+```ts
+import { BaseExecutor, type BuiltinToolContext, type BuiltinToolResult } from '@lobechat/types';
+import debug from 'debug';
+
+import { taskService } from '@/services/task';
+import { getTaskStoreState } from '@/store/task';
+
+import { TaskIdentifier } from '../../manifest';
+import { TaskApiName, type CreateTaskParams } from '../../types';
+
+const log = debug('lobe-task:executor');
+
+class TaskExecutor extends BaseExecutor<typeof TaskApiName> {
+  readonly identifier = TaskIdentifier;
+  protected readonly apiEnum = TaskApiName;
+
+  // ⚠ class FIELD, not a method — preserves `this` when invoked via registry
+  createTask = async (
+    params: CreateTaskParams,
+    ctx?: BuiltinToolContext,
+  ): Promise<BuiltinToolResult> => {
+    try {
+      log('createTask params=%o', params);
+      const task = await getTaskStoreState().createTask({
+        name: params.name,
+        instruction: params.instruction,
+        // Default assignee from context — never silently override an explicit value
+        assigneeAgentId:
+          params.assigneeAgentId ?? (ctx?.scope === 'task' ? undefined : ctx?.agentId),
+        parentTaskId: params.parentIdentifier?.trim() || undefined,
+        priority: params.priority,
+      });
+
+      if (!task) return this.errorResult('Failed to create task', 'CreateFailed');
+
+      return {
+        success: true,
+        content: formatTaskCreated({ identifier: task.identifier, name: task.name /* … */ }),
+        state: { identifier: task.identifier, success: true },
+      };
+    } catch (error) {
+      return this.errorResult(error, 'CreateTaskFailed');
+    }
+  };
+
+  private errorResult(err: unknown, type: string): BuiltinToolResult {
+    const message = err instanceof Error ? err.message : String(err) || 'Unknown error';
+    return { success: false, content: `Failed: ${message}`, error: { type, message } };
+  }
+}
+
+export const taskExecutor = new TaskExecutor();
+```
+
+### Hard rules
+
+1. **Methods are class fields** (`name = async (…) => {…}`), not class methods. The registry calls `(executor as any)[apiName](params, ctx)`; arrow-function fields keep `this` bound.
+2. **`identifier` and `apiEnum` are `readonly` instance fields**, not getters — `BaseExecutor.hasApi/getApiNames` reads them synchronously at registration time.
+3. **Default missing params from `ctx`**, but never silently override explicit values. Use `params.foo ?? ctx?.foo`, not `ctx?.foo ?? params.foo`.
+4. **One funnel for all returns.** Either always return through `toResult(runtime.x())` (when delegating) or through `errorResult(…)` for the catch arm. Never inline `{ success: false, content: '' }` — `content: ''` collapses the Debug pane to blank.
+5. **`debug('lobe-<name>:executor')`.** Match the namespace to the identifier minus `lobe-` when convenient.
+6. **Singleton export.** `export const <name>Executor = new <Name>Executor()` — the registry imports the instance, not the class.
+
+### When the executor delegates to ExecutionRuntime
+
+```ts
+class LocalSystemExecutor extends BaseExecutor<typeof LocalSystemApiEnum> {
+  readonly identifier = LocalSystemIdentifier;
+  protected readonly apiEnum = LocalSystemApiEnum;
+  private runtime = new LocalSystemExecutionRuntime(localFileService);
+
+  readLocalFile = async (params: LocalReadFileParams): Promise<BuiltinToolResult> => {
+    try {
+      const result = await this.runtime.readFile({
+        path: params.path,
+        startLine: params.loc?.[0],
+        endLine: params.loc?.[1],
+      });
+      return this.toResult(result);
+    } catch (error) {
+      return this.errorResult(error);
+    }
+  };
+
+  private toResult(out: BuiltinServerRuntimeOutput): BuiltinToolResult {
+    const errMsg = typeof out.error?.message === 'string' ? out.error.message : undefined;
+    const safe = out.content || errMsg || 'Tool execution failed';
+    if (!out.success) {
+      return {
+        success: false,
+        content: safe,
+        state: out.state, // ← preserve partial state on failure
+        error: out.error
+          ? { type: 'PluginServerError', message: errMsg ?? safe, body: out.error }
+          : undefined,
+      };
+    }
+    return { success: true, content: safe, state: out.state };
+  }
+}
+```
+
+The `toResult` funnel is **mandatory**: it enforces never-undefined `content` and partial-state preservation. Both invariants caught real production bugs (`globLocalFiles` Response empty, `editLocalFile` partial state lost).
+
+---
+
+## 7. `index.ts` — Package Entry Point
+
+Keep it pure data + the manifest. **No React, no stores, no Node-only imports.**
+
+```ts
+export { TaskIdentifier, TaskManifest } from './manifest';
+export { systemPrompt } from './systemRole';
+export {
+  TaskApiName,
+  type TaskApiNameType,
+  type CreateTaskParams,
+  type CreateTaskState,
+  /* …all Params/State types */
+} from './types';
+
+// Optional helpers used by both the runtime and the UI
+export { TASK_STATUSES, UNFINISHED_TASK_STATUSES } from './constants';
+```
+
+This entry is what `packages/builtin-tools/src/index.ts` and `identifiers.ts` import — it must be importable from server bundles.
+
+---
+
+## 8. `package.json`
+
+```json
+{
+  "dependencies": {
+    "@lobechat/prompts": "workspace:*"
+  },
+  "devDependencies": {
+    "@lobechat/types": "workspace:*"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client/index.ts",
+    "./executor": "./src/client/executor/index.ts",
+    "./executionRuntime": "./src/ExecutionRuntime/index.ts"
+  },
+  "main": "./src/index.ts",
+  "name": "@lobechat/builtin-tool-<name>",
+  "peerDependencies": {
+    "@lobehub/ui": "^5",
+    "antd": "^6",
+    "antd-style": "*",
+    "lucide-react": "*",
+    "react": "*",
+    "react-i18next": "*"
+  },
+  "private": true,
+  "version": "1.0.0"
+}
+```
+
+**Why peer not direct deps for client libs:** the `./` and `./executionRuntime` entry points must be importable from server code. Listing React etc. as peer deps prevents bundlers from following them when only the runtime is consumed.
+
+**Skip `./executor`** if the package has no frontend executor (server-only tools like `builtin-tool-web-browsing`).
+
+---
+
+## 9. Common Pitfalls
+
+| Symptom                                                 | Likely cause                                                                                            |
+| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| "ApiNotFound" at runtime                                | Method name in executor doesn't match `ApiName` value (typo, wrong case)                                |
+| Method works once, then "this is undefined"             | Method declared as `async fn() {}` instead of `fn = async () => {}` — `this` lost when registry invokes |
+| Debug "Response" pane blank but `pluginState` populated | Returning `content: ''` or letting `output.content` be undefined — use the `toResult` funnel            |
+| Partial result vanishes on failure                      | `toResult` discarded `state` when `success: false`; preserve it                                         |
+| Tool shows up but doesn't run on desktop                | `executors` in manifest doesn't include `'client'` (or vice versa for server-only)                      |
+| Same tool registered twice / legacy identifier ghost    | Identifier collision; check `@deprecated` aliases in `inspectors.ts`/`renders.ts`                       |
+| Manifest test fails after adding API                    | Forgot to add the corresponding i18n `apiName.<api>` key                                                |
+| TypeScript error on `BaseExecutor<typeof X>`            | `X` declared with `enum` instead of `as const` object — must be the const-object form                   |
@@ -0,0 +1,744 @@
+# Tool UI Surfaces
+
+A builtin tool can ship up to **six client-side surfaces**, each with a different role in the chat UI. Only `Inspector` is required; the other five are added on demand and registered in their own central files.
+
+| Surface      | Required? | When the chat shows it                                                | Registered in                                 |
+| ------------ | --------- | --------------------------------------------------------------------- | --------------------------------------------- |
+| Inspector    | ✅ Always | Header strip of every tool call (one-line chip)                       | `packages/builtin-tools/src/inspectors.ts`    |
+| Render       | Optional  | Rich result card below the header, after the call returns             | `packages/builtin-tools/src/renders.ts`       |
+| Placeholder  | Optional  | Skeleton between "args streaming complete" and "result arrives"       | `packages/builtin-tools/src/placeholders.ts`  |
+| Streaming    | Optional  | Live output during execution (e.g. command stdout)                    | `packages/builtin-tools/src/streamings.ts`    |
+| Intervention | Optional  | Approval / edit-before-run dialog (when `humanIntervention` triggers) | `packages/builtin-tools/src/interventions.ts` |
+| Portal       | Optional  | Full-screen detail view (right-side or modal)                         | `packages/builtin-tools/src/portals.ts`       |
+
+The two reference tools to read end-to-end:
+
+- **`builtin-tool-web-browsing/src/client/`** — Inspector + Render + Placeholder + Portal (no Intervention/Streaming).
+- **`builtin-tool-local-system/src/client/`** — all six surfaces, including `components/` for shared building blocks.
+
+---
+
+## Tool Render 设计原则（中文草案）
+
+这些原则用于判断一个 builtin tool 的 Inspector / Render / Placeholder / Streaming / Intervention / Portal 应该做什么，以及做到什么程度。
+
+1. **先保证折叠态可读。** 每个 API 都必须有 Inspector；用户不展开也应该能看懂 “正在做什么 / 对什么做 / 当前结果是什么”。Inspector 不应该只展示函数名和原始参数。
+2. **Inspector 是一句话，不是详情页。** 优先表达动作、关键对象、数量、状态，例如 “分析图片 3 张”“搜索 12 个结果”“读取 config.json”。长文本、列表和结构化结果放到 Render 或 Portal。
+3. **Inspector 要覆盖执行生命周期。** `args` 还在 streaming、工具执行中、执行完成、执行失败时都应该有稳定展示；必要时同时读取 `args`、`partialArgs` 和 `pluginState`，避免出现空白、跳变或只显示半截参数。
+4. **文案要随状态切换时态。** 同一个动作在 loading 与 completed 两个阶段必须用不同的措辞：执行中用现在进行时（“正在创建任务 / Creating task / 正在搜索”），执行完成后切到完成态（“已创建任务 / Task created / 已找到 N 条”）。Inspector chip 会一直留在聊天记录里 —— 如果一直挂着 “正在 xxx”，几小时后回看历史时会读起来像还在跑。约定的 i18n 形式是 `<api>.loading` / `<api>.completed` 一对键（见 `lobe-agent.apiName.callSubAgent.{loading,completed}` 与 `lobe-claude-code.task.{create,list,update,get}.{loading,completed}`），渲染时按 `isArgumentsStreaming || isLoading` 决定取哪一个。只读 / 查询类（“查看任务” 这种本来就是名词性的）可以共用一个键。
+5. **只有结构化结果才需要 Render。** 如果工具结果只是自然语言总结，通常不需要 Render；如果结果包含列表、媒体、文件、表格、代码、diff、地图、时间线、权限请求等结构，就应该提供 Render。
+6. **Render 要帮助用户检查结果，而不是复述参数。** Render 的主体应该围绕工具产物组织：可预览、可比较、可筛选、可定位。参数只作为上下文辅助出现，不要把 Render 做成一块更大的 args dump。
+7. **参数和结果要一起参与渲染。** 好的 Tool UI 通常同时用 `args` 解释意图，用 `pluginState` 展示真实执行结果；但 `pluginState` 只放结果域数据，不要反向塞入可以从 `args` 推导出的内容。
+8. **慢操作要有 Placeholder。** 如果工具通常需要等待网络、文件系统、模型或外部进程，Placeholder 应该先占住最终 Render 的版式，让用户知道即将看到什么，而不是只显示一个泛化 loading。
+9. **Streaming 只用于连续产物。** 搜索列表、日志、长文本、文件分析、分阶段计划适合 Streaming；一次性小结果不需要强行做 Streaming。Streaming UI 要能渐进追加，并且完成后自然过渡到最终 Render。
+10. **有风险的动作必须 Intervention。** 写文件、删除、发送、安装、执行命令、外部可见操作、权限敏感操作，都应该在执行前给出可理解的确认界面；确认文案要说明影响范围，而不是只问 “是否继续”。
+11. **错误、空态和截断都是正式状态。** Render 不能在失败、无结果、超长结果时退化成空白。错误要说明发生在哪一步；空态要告诉用户没有产物；超长内容要明确 “展示前 N 项 / 还有 N 项”。
+12. **信息密度要克制。** 默认展示最有判断价值的部分：标题、来源、状态、摘要、少量关键字段。大对象、长列表、原文、调试数据放进可展开区域或 Portal，避免把聊天流撑成后台管理页。
+13. **视觉上融入聊天流。** Tool UI 应该使用 `@lobehub/ui` / base-ui、`Flexbox`、`createStaticStyles` 和 `cssVar.*`，遵循现有间距、圆角、颜色、字号；不要为单个工具发明一套独立视觉语言。
+14. **Devtools fixture 是验收入口。** 新增或修改 Tool UI 时，应在 `/devtools` 里准备覆盖典型态、loading/streaming、空态、错误态、长内容态的 fixture；一个 API 如果在真实聊天里会出现，就不应该在 devtools 中缺席。
+15. **先做用户会看的 UI，再做调试 UI。** Raw JSON、trace、schema、内部 id 可以存在，但应默认收起或放到调试区；主界面先回答用户最关心的问题：工具做了什么，结果值不值得信任，下一步能做什么。
+
+---
+
+## 0. Shared Style Rules
+
+These apply across every surface.
+
+### 0.1 Use `'use client'` at the top of every component file
+
+Tool surfaces are leaves in the chat tree and must not block server rendering.
+
+### 0.2 Prefer `createStaticStyles + cssVar.*`
+
+Zero-runtime CSS-in-JS — the styles compile once and read CSS variables at runtime.
+
+```tsx
+import { createStaticStyles, cssVar } from 'antd-style';
+
+const styles = createStaticStyles(({ css, cssVar }) => ({
+  chip: css`
+    padding-block: 2px;
+    padding-inline: 8px;
+    border-radius: 999px;
+    color: ${cssVar.colorText};
+    background: ${cssVar.colorFillTertiary};
+  `,
+}));
+```
+
+Fall back to `createStyles + token` only when you need runtime token computation (rare). Inline `style={{ color: cssVar.colorTextSecondary }}` is fine for one-off dynamic values.
+
+### 0.3 Use `@lobehub/ui`, not raw `antd`
+
+`Block`, `Text`, `Flexbox`, `Highlighter`, `Alert`, `Tooltip`, `Skeleton` all come from `@lobehub/ui`. Modals come from `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
+
+Memory note: `@lobehub/ui`'s `<Text type='secondary'>` is a lighter shade than `colorTextSecondary`. If you need that exact token color, write `<Text style={{ color: cssVar.colorTextSecondary }}>`.
+
+### 0.4 Always `memo` and set `displayName`
+
+```tsx
+export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
+  ({ args /* … */ }) => {
+    /* … */
+  },
+);
+SearchInspector.displayName = 'SearchInspector';
+export default SearchInspector;
+```
+
+### 0.5 Always type with `BuiltinXProps<Args, State>` generics
+
+Don't widen to `any`. The Args generic is the JSON Schema params, the State generic is the executor's `state` field. The two should match `<Name>Params` and `<Name>State` from `types.ts`.
+
+### 0.6 Pull strings from `t('plugin')`
+
+```tsx
+const { t } = useTranslation('plugin');
+t('builtins.<identifier>.apiName.<api>');
+```
+
+Every Inspector should default to `t('builtins.<identifier>.apiName.<api>')` so it shows something while args stream in.
+
+### 0.7 Read store state from `@/store/chat`, not props
+
+Tool surfaces sometimes need cross-cutting state (loading, streaming buffer). Read it inside the component via Zustand selectors, not from props — props only carry args/state/messageId.
+
+---
+
+## 1. Inspector — Header Chip (required)
+
+**Lifecycle:** Inspector renders for **every phase** of a tool call: while args are streaming in, while the executor is running, and after results come back. It's the only surface that's always visible.
+
+**Goal:** keep it to a single line. Show what's happening with as much context as is currently available.
+
+### Props (`BuiltinInspectorProps<Args, State>`)
+
+```ts
+interface BuiltinInspectorProps<Arguments = any, State = any> {
+  apiName: string;
+  args: Arguments; // final args (only after the assistant stops streaming)
+  identifier: string;
+  isArgumentsStreaming?: boolean; // args still arriving
+  isLoading?: boolean; // args complete, executor running
+  partialArgs?: Arguments; // partial JSON during streaming
+  pluginState?: State; // executor's `state` after success
+  result?: { content: string | null; error?: any };
+}
+```
+
+### State machine
+
+| Phase                               | What's available                                           | What to show                                               |
+| ----------------------------------- | ---------------------------------------------------------- | ---------------------------------------------------------- |
+| Args streaming, no useful field yet | `isArgumentsStreaming === true`, `partialArgs.X` undefined | Just the API title with `shinyTextStyles.shinyText`        |
+| Args streaming, key field arrived   | `partialArgs.X` populated                                  | Title + key field chip, still pulse-animated               |
+| Args complete, executor running     | `args` populated, `isLoading === true`                     | Same as above, still pulse-animated                        |
+| Result arrived                      | `pluginState` populated, `isLoading === false`             | Title + chips + result summary (count, identifier, status) |
+
+### Canonical example — Search
+
+`packages/builtin-tool-web-browsing/src/client/Inspector/Search/index.tsx`:
+
+```tsx
+'use client';
+
+import type { BuiltinInspectorProps, SearchQuery, UniformSearchResponse } from '@lobechat/types';
+import { Text } from '@lobehub/ui';
+import { cssVar, cx } from 'antd-style';
+import { memo } from 'react';
+import { useTranslation } from 'react-i18next';
+
+import { highlightTextStyles, inspectorTextStyles, shinyTextStyles } from '@/styles';
+
+export const SearchInspector = memo<BuiltinInspectorProps<SearchQuery, UniformSearchResponse>>(
+  ({ args, partialArgs, isArgumentsStreaming, isLoading, pluginState }) => {
+    const { t } = useTranslation('plugin');
+
+    const query = args?.query || partialArgs?.query || '';
+    const resultCount = pluginState?.results?.length ?? 0;
+    const hasResults = resultCount > 0;
+
+    if (isArgumentsStreaming && !query) {
+      return (
+        <div className={cx(inspectorTextStyles.root, shinyTextStyles.shinyText)}>
+          <span>{t('builtins.lobe-web-browsing.apiName.search')}</span>
+        </div>
+      );
+    }
+
+    return (
+      <div
+        className={cx(
+          inspectorTextStyles.root,
+          (isArgumentsStreaming || isLoading) && shinyTextStyles.shinyText,
+        )}
+      >
+        <span>{t('builtins.lobe-web-browsing.apiName.search')}:&nbsp;</span>
+        {query && <span className={highlightTextStyles.primary}>{query}</span>}
+        {!isLoading &&
+          !isArgumentsStreaming &&
+          pluginState?.results &&
+          (hasResults ? (
+            <span style={{ marginInlineStart: 4 }}>({resultCount})</span>
+          ) : (
+            <Text as="span" color={cssVar.colorTextDescription} fontSize={12}>
+              ({t('builtins.lobe-web-browsing.inspector.noResults')})
+            </Text>
+          ))}
+      </div>
+    );
+  },
+);
+SearchInspector.displayName = 'SearchInspector';
+export default SearchInspector;
+```
+
+### Inspector rules
+
+- Wrap the whole row with `inspectorTextStyles.root` (provides correct flex / line-height baseline).
+- Pulse with `shinyTextStyles.shinyText` whenever `isArgumentsStreaming || isLoading`.
+- Show the i18n title first so the row is non-empty during the earliest streaming phase.
+- Read both `args?.X` and `partialArgs?.X` together — `args` is final, `partialArgs` is in-stream.
+- Use chips/tags for distinct facets (identifier, name, parent, status, count). Each chip should clip with `text-overflow: ellipsis` and have a `max-width` so long values don't blow out the chat bubble.
+- Append `pluginState`-derived suffixes only **after** loading finishes — count or "(no results)" should not appear while still searching.
+- **Switch copy by phase.** If the verb implies an ongoing action ("Creating", "Searching", "Listing"), define `<api>.loading` and `<api>.completed` keys and select via `isArgumentsStreaming || isLoading ? loadingKey : completedKey`. Inspector chips persist in chat history — leaving "Creating task" frozen on a finished call reads as if the tool is still running. Read-only labels that are already noun-form ("View task") can keep a single key. See `CallSubAgentInspector` for the canonical two-key pattern.
+
+### Inspector registry — `client/Inspector/index.ts`
+
+```ts
+import type { BuiltinInspector } from '@lobechat/types';
+
+import { TaskApiName } from '../../types';
+import { CreateTaskInspector } from './CreateTask';
+import { ListTasksInspector } from './ListTasks';
+/* … */
+
+export const TaskInspectors: Record<string, BuiltinInspector> = {
+  [TaskApiName.createTask]: CreateTaskInspector as BuiltinInspector,
+  [TaskApiName.listTasks]: ListTasksInspector as BuiltinInspector,
+  /* one entry per ApiName */
+};
+
+export { CreateTaskInspector } from './CreateTask';
+export { ListTasksInspector } from './ListTasks';
+/* re-export each */
+```
+
+---
+
+## 2. Render — Rich Result Card (optional)
+
+**Lifecycle:** rendered **once the result arrives** (after Placeholder/Streaming hand off). Sits below the Inspector header.
+
+**Skip if** the API is read-only or the result is just text — the framework already shows the executor's `content` string. Add a Render only when there's a structured artifact worth seeing: a card, a chart, a diff, a list of files.
+
+### Props (`BuiltinRenderProps<Args, State, Content>`)
+
+```ts
+interface BuiltinRenderProps<Arguments = any, State = any, Content = any> {
+  apiName?: string;
+  args: Arguments; // final params from the LLM
+  content: Content; // executor's content string (or parsed)
+  identifier?: string;
+  messageId: string; // for store lookups
+  pluginError?: any; // from BuiltinToolResult.error
+  pluginState?: State; // executor's state
+  toolCallId?: string;
+}
+```
+
+### Two patterns
+
+**Pattern A — Single-file Render** (web-browsing CrawlSinglePage):
+
+```tsx
+// client/Render/CrawlSinglePage.tsx
+import type { BuiltinRenderProps, CrawlPluginState, CrawlSinglePageQuery } from '@lobechat/types';
+import { memo } from 'react';
+
+import PageContent from './PageContent';
+
+const CrawlSinglePage = memo<BuiltinRenderProps<CrawlSinglePageQuery, CrawlPluginState>>(
+  ({ messageId, pluginState, args }) => (
+    <PageContent messageId={messageId} results={pluginState?.results} urls={[args?.url]} />
+  ),
+);
+export default CrawlSinglePage;
+```
+
+**Pattern B — Folder with subcomponents** (web-browsing Search):
+
+```
+client/Render/Search/
+├── index.tsx           # composes the subcomponents, handles error states
+├── ConfigForm.tsx      # appears when pluginError.type === 'PluginSettingsInvalid'
+├── SearchQuery.tsx     # editable query header
+└── SearchResult.tsx    # result list
+```
+
+Use Pattern B when the Render has internal state (editing mode, expanded items), error variants, or is large enough to benefit from splitting.
+
+### Error handling in Render
+
+Renders are the canonical place to surface `pluginError` because the chat doesn't auto-render typed errors:
+
+```tsx
+if (pluginError) {
+  if (pluginError?.type === 'PluginSettingsInvalid') {
+    return <ConfigForm id={messageId} provider={pluginError.body?.provider} />;
+  }
+  return (
+    <Alert
+      title={pluginError?.message}
+      type="error"
+      extra={<Highlighter language="json">{JSON.stringify(pluginError.body, null, 2)}</Highlighter>}
+    />
+  );
+}
+```
+
+### Render rules
+
+- **Return `null`** if there's nothing useful to draw yet (avoids empty cards during stream).
+- Use `pluginState` for server-truth (ids, counts, server-assigned status) and `args` for what the LLM asked. **Combine — neither alone is enough.**
+- For lists, summarize with a header line and show top N items with a "+N more" tail rather than rendering everything.
+- For modals from a Render, use `@lobehub/ui/base-ui` (`createModal`, `useModalContext`, `confirmModal`) — see the **modal** skill.
+
+### Render registry — `client/Render/index.ts`
+
+```ts
+import type { BuiltinRender } from '@lobechat/types';
+
+import { TaskApiName } from '../../types';
+import CreateTaskRender from './CreateTask';
+import RunTasksRender from './RunTasks';
+
+export const TaskRenders: Record<string, BuiltinRender> = {
+  [TaskApiName.createTask]: CreateTaskRender as BuiltinRender,
+  [TaskApiName.runTasks]: RunTasksRender as BuiltinRender,
+  /* only the APIs with rich result UI — others fall back to text content */
+};
+
+export { default as CreateTaskRender } from './CreateTask';
+export { default as RunTasksRender } from './RunTasks';
+```
+
+### Render display control (rare)
+
+If the Render should hide for certain results (e.g. ClaudeCode's TodoWrite hides when the agent is mid-stream), add a `RenderDisplayControl` to `packages/builtin-tools/src/displayControls.ts`. See `ClaudeCodeRenderDisplayControls` for the pattern.
+
+---
+
+## 3. Placeholder — Skeleton Between Args and Result (optional)
+
+**Lifecycle:** rendered when the args have finished streaming but the executor hasn't returned yet. Disappears when `pluginState` arrives. Bridges the moment of perceived lag.
+
+**Add for** APIs with noticeable execution time: web search, network crawl, file list, large grep. **Skip for** instant ops (status flips, calculator).
+
+### Props (`BuiltinPlaceholderProps<Args>`)
+
+```ts
+interface BuiltinPlaceholderProps<T extends Record<string, any> = any> {
+  apiName: string;
+  args?: T;
+  identifier: string;
+}
+```
+
+No `pluginState` — Placeholder lives entirely in the "executing" gap.
+
+### Canonical example — Search Placeholder
+
+`packages/builtin-tool-web-browsing/src/client/Placeholder/Search.tsx`:
+
+```tsx
+import type { BuiltinPlaceholderProps, SearchQuery } from '@lobechat/types';
+import { Flexbox, Icon, Skeleton } from '@lobehub/ui';
+import { createStaticStyles, cx } from 'antd-style';
+import { SearchIcon } from 'lucide-react';
+import { memo } from 'react';
+
+import { useIsMobile } from '@/hooks/useIsMobile';
+import { shinyTextStyles } from '@/styles';
+
+const styles = createStaticStyles(({ css, cssVar }) => ({
+  query: cx(
+    css`
+      padding: 4px 8px;
+      border-radius: 8px;
+      font-size: 12px;
+      color: ${cssVar.colorTextSecondary};
+      &:hover {
+        background: ${cssVar.colorFillTertiary};
+      }
+    `,
+    shinyTextStyles.shinyText,
+  ),
+}));
+
+export const Search = memo<BuiltinPlaceholderProps<SearchQuery>>(({ args }) => {
+  const { query } = args || {};
+  const isMobile = useIsMobile();
+
+  return (
+    <Flexbox gap={8}>
+      <Flexbox horizontal={!isMobile} gap={isMobile ? 8 : 40}>
+        <Flexbox horizontal align="center" className={styles.query} gap={8}>
+          <Icon icon={SearchIcon} />
+          {query ? query : <Skeleton.Block active style={{ height: 20, width: 40 }} />}
+        </Flexbox>
+        <Skeleton.Block active style={{ height: 20, width: 40 }} />
+      </Flexbox>
+      <Flexbox horizontal gap={12}>
+        {[1, 2, 3, 4, 5].map((id) => (
+          <Skeleton.Button active key={id} style={{ borderRadius: 8, height: 80, width: 160 }} />
+        ))}
+      </Flexbox>
+    </Flexbox>
+  );
+});
+```
+
+### Placeholder rules
+
+- **Mirror the eventual Render's layout.** When the result arrives the Placeholder unmounts and the Render mounts; if they share dimensions, the chat doesn't jump.
+- Use `Skeleton.Block` / `Skeleton.Button` from `@lobehub/ui` for placeholder shapes.
+- Embed any args you have (e.g. the query text) — context helps the user know what's loading.
+- Pulse with `shinyTextStyles.shinyText` if the Placeholder includes literal text.
+
+### Placeholder registry — `client/Placeholder/index.ts`
+
+```ts
+import { WebBrowsingApiName } from '../../types';
+import CrawlMultiPages from './CrawlMultiPages';
+import CrawlSinglePage from './CrawlSinglePage';
+import { Search } from './Search';
+
+export const WebBrowsingPlaceholders = {
+  [WebBrowsingApiName.crawlMultiPages]: CrawlMultiPages,
+  [WebBrowsingApiName.crawlSinglePage]: CrawlSinglePage,
+  [WebBrowsingApiName.search]: Search,
+};
+
+export { CrawlMultiPages, CrawlSinglePage, Search };
+```
+
+---
+
+## 4. Streaming — Live Output During Execution (optional)
+
+**Lifecycle:** rendered **while the executor is still running** for APIs that emit incremental output. The component is responsible for fetching the in-flight stream from the chat store and rendering it.
+
+**Add for** long-running ops with continuous output: shell command execution (stdout/stderr), file write progress, code interpreter cells.
+
+### Props (`BuiltinStreamingProps<Args>`)
+
+```ts
+interface BuiltinStreamingProps<Arguments = any> {
+  apiName: string;
+  args: Arguments;
+  identifier: string;
+  messageId: string; // use to fetch the streaming buffer from store
+  toolCallId: string;
+}
+```
+
+Note there's **no `state` or `result` prop** — the Streaming component is for the in-flight phase. It pulls the live buffer from the store itself (typically via `chatToolSelectors.streamingContent(messageId)` or similar).
+
+### Canonical example — RunCommandStreaming
+
+`packages/builtin-tool-local-system/src/client/Streaming/RunCommand/index.tsx`:
+
+```tsx
+'use client';
+
+import type { BuiltinStreamingProps } from '@lobechat/types';
+import { Highlighter } from '@lobehub/ui';
+import { memo } from 'react';
+
+interface RunCommandParams {
+  command?: string;
+  description?: string;
+  timeout?: number;
+}
+
+export const RunCommandStreaming = memo<BuiltinStreamingProps<RunCommandParams>>(({ args }) => {
+  const { command } = args || {};
+  if (!command) return null;
+
+  return (
+    <Highlighter
+      animated
+      wrap
+      language="sh"
+      showLanguage={false}
+      style={{ padding: '4px 8px' }}
+      variant="outlined"
+    >
+      {command}
+    </Highlighter>
+  );
+});
+RunCommandStreaming.displayName = 'RunCommandStreaming';
+```
+
+For real-time output beyond just the command (stderr/stdout streaming), pull from the chat store:
+
+```tsx
+const buffer = useChatStore((state) =>
+  chatToolSelectors.streamingBuffer(messageId, toolCallId)(state),
+);
+```
+
+### Streaming rules
+
+- Render `null` until you have something to display (avoids flash).
+- For terminal-style output, use `Highlighter` with `animated` to show typing-like effect.
+- The Streaming component must **unmount cleanly** when execution ends — typically the framework swaps it out for the Render automatically.
+
+### Streaming registry — `client/Streaming/index.ts`
+
+```ts
+import { LocalSystemApiName } from '../..';
+import { RunCommandStreaming } from './RunCommand';
+import { WriteFileStreaming } from './WriteFile';
+
+export const LocalSystemStreamings = {
+  [LocalSystemApiName.runCommand]: RunCommandStreaming,
+  [LocalSystemApiName.writeLocalFile]: WriteFileStreaming,
+};
+```
+
+---
+
+## 5. Intervention — Approval / Edit-Before-Run (optional)
+
+**Lifecycle:** rendered **before the executor runs** for APIs whose manifest sets `humanIntervention`. The user sees a preview of the args, can edit them, then approves or skips/cancels.
+
+**Add for** destructive or sensitive ops: shell commands, file writes, file moves, payments, message broadcasts.
+
+### Props (`BuiltinInterventionProps<Args>`)
+
+```ts
+interface BuiltinInterventionProps<Arguments = any> {
+  apiName?: string;
+  args: Arguments;
+  identifier?: string;
+  interactionMode?: 'approval' | 'custom';
+  messageId: string;
+
+  /** Called when the user edits the args; the approve action awaits this. */
+  onArgsChange?: (args: Arguments) => void | Promise<void>;
+
+  /** Called on approve / skip / cancel. */
+  onInteractionAction?: (
+    action:
+      | { type: 'submit'; payload: Record<string, unknown> }
+      | { type: 'skip'; payload?: Record<string, unknown>; reason?: string }
+      | { type: 'cancel'; payload?: Record<string, unknown> },
+  ) => Promise<void>;
+
+  /** Register a callback to flush pending saves before approval. Returns cleanup. */
+  registerBeforeApprove?: (id: string, callback: () => void | Promise<void>) => () => void;
+}
+```
+
+### Canonical example — RunCommand Intervention
+
+`packages/builtin-tool-local-system/src/client/Intervention/RunCommand/index.tsx`:
+
+```tsx
+import type { RunCommandParams } from '@lobechat/electron-client-ipc';
+import type { BuiltinInterventionProps } from '@lobechat/types';
+import { Flexbox, Highlighter, Text } from '@lobehub/ui';
+import { memo } from 'react';
+
+const RunCommand = memo<BuiltinInterventionProps<RunCommandParams>>(({ args }) => {
+  const { description, command, timeout } = args;
+  return (
+    <Flexbox gap={8}>
+      <Flexbox horizontal justify="space-between">
+        {description && <Text>{description}</Text>}
+        {timeout && (
+          <Text style={{ fontSize: 12 }} type="secondary">
+            timeout: {formatTimeout(timeout)}
+          </Text>
+        )}
+      </Flexbox>
+      {command && (
+        <Highlighter wrap language="sh" showLanguage={false} variant="outlined">
+          {command}
+        </Highlighter>
+      )}
+    </Flexbox>
+  );
+});
+export default RunCommand;
+```
+
+### Intervention rules
+
+- **Show a preview, not a form by default.** Editing UI is opt-in via `onArgsChange` and is usually inline (click to edit a code block, etc.).
+- For args with debounced edit state (text fields), use `registerBeforeApprove(id, flushFn)` so the approve action waits for the debounce to flush. Always return the cleanup function.
+- Call `onInteractionAction({ type: 'submit', payload })` when the user approves; `'skip'` if they skip with a reason; `'cancel'` if they cancel the whole turn.
+- Add a corresponding `interventionAudit.ts` in the package root if the tool needs scope/path validation before approval (see `local-system/src/interventionAudit.ts`).
+
+### Intervention registry — `client/Intervention/index.ts`
+
+```ts
+import { LocalSystemApiName } from '../..';
+import EditLocalFile from './EditLocalFile';
+import RunCommand from './RunCommand';
+import WriteFile from './WriteFile';
+/* … */
+
+export const LocalSystemInterventions = {
+  [LocalSystemApiName.editLocalFile]: EditLocalFile,
+  [LocalSystemApiName.runCommand]: RunCommand,
+  [LocalSystemApiName.writeLocalFile]: WriteFile,
+  /* one entry per API that needs approval */
+};
+```
+
+---
+
+## 6. Portal — Full-Screen Detail View (optional)
+
+**Lifecycle:** rendered when the user opens the tool message in a side panel or full-screen modal. One Portal per **tool**, not per API — the Portal switches on `apiName` internally.
+
+**Add for** tools whose results deserve a deep-dive view: search results with editable filters, page content with reader mode, code interpreter sessions.
+
+### Props (`BuiltinPortalProps<Args, State>`)
+
+```ts
+interface BuiltinPortalProps<Arguments = Record<string, any>, State = any> {
+  apiName?: string;
+  arguments: Arguments;
+  identifier: string;
+  messageId: string;
+  state: State;
+}
+```
+
+### Canonical example — Web-Browsing Portal
+
+`packages/builtin-tool-web-browsing/src/client/Portal/index.tsx`:
+
+```tsx
+import type { BuiltinPortalProps, CrawlPluginState, SearchQuery } from '@lobechat/types';
+import { memo } from 'react';
+
+import { WebBrowsingApiName } from '../../types';
+import PageContent from './PageContent';
+import PageContents from './PageContents';
+import Search from './Search';
+
+const Portal = memo<BuiltinPortalProps>(({ arguments: args, messageId, state, apiName }) => {
+  switch (apiName) {
+    case WebBrowsingApiName.search:
+      return <Search messageId={messageId} query={args as SearchQuery} response={state} />;
+
+    case WebBrowsingApiName.crawlSinglePage: {
+      const result = (state as CrawlPluginState).results.find((r) => r.originalUrl === args.url);
+      return <PageContent messageId={messageId} result={result} />;
+    }
+
+    case WebBrowsingApiName.crawlMultiPages:
+      return (
+        <PageContents
+          messageId={messageId}
+          results={(state as CrawlPluginState).results}
+          urls={args.urls}
+        />
+      );
+  }
+  return null;
+});
+export default Portal;
+```
+
+### Portal rules
+
+- One Portal per tool — the file is the routing layer, subcomponents implement each API's view.
+- Portals can read the chat store directly to detect "still streaming" and render a Skeleton internally (see `Search/index.tsx:20-46`).
+- Layout assumes more space than the Render — use `Flexbox` with `height={'100%'}` and structure for a side panel viewport.
+
+### Portal registry — `packages/builtin-tools/src/portals.ts`
+
+```ts
+import { WebBrowsingManifest, WebBrowsingPortal } from '@lobechat/builtin-tool-web-browsing/client';
+import { type BuiltinPortal } from '@lobechat/types';
+
+export const BuiltinToolsPortals: Record<string, BuiltinPortal> = {
+  [WebBrowsingManifest.identifier]: WebBrowsingPortal as BuiltinPortal,
+};
+```
+
+---
+
+## 7. `client/components/` — Shared Subcomponents
+
+Cross-cutting building blocks used by multiple surfaces live here, not duplicated in each surface folder.
+
+Examples from `web-browsing/src/client/components/`:
+
+- `CategoryAvatar.tsx` — search category icon
+- `EngineAvatar.tsx` — search engine logo (used in Inspector chip + Render list + Portal header)
+- `SearchBar.tsx` — editable query bar (used in Render and Portal)
+
+Examples from `local-system/src/client/components/`:
+
+- `FileItem.tsx` — single file row (used in ListFiles Render, SearchFiles Render, MoveLocalFiles Render)
+- `FilePathDisplay.tsx` — path with truncation (used everywhere)
+
+### Rules
+
+- Live under `client/components/`, exported via `client/components/index.ts`.
+- Re-export from `client/index.ts` only if other packages need them; otherwise keep internal.
+- Keep them dumb — props in, JSX out, no store reads. The store reads belong in the surface that composes them.
+
+---
+
+## 8. `client/index.ts` — Package Public API
+
+Re-exports everything the registries need plus useful types/manifest:
+
+```ts
+// Inspector — required
+export { TaskInspectors } from './Inspector';
+
+// Render — only if any API has one
+export { TaskRenders, CreateTaskRender, RunTasksRender } from './Render';
+
+// Placeholder / Streaming / Intervention — only if used
+export { LocalSystemListFilesPlaceholder, LocalSystemSearchFilesPlaceholder } from './Placeholder';
+export { LocalSystemStreamings } from './Streaming';
+export { LocalSystemInterventions } from './Intervention';
+
+// Portal — single export per tool
+export { default as WebBrowsingPortal } from './Portal';
+
+// Reusable components if other packages need them
+export { CategoryAvatar, EngineAvatar, SearchBar } from './components';
+
+// Re-export manifest, identifier, types for convenience
+export { TaskManifest, TaskIdentifier } from '../manifest';
+export * from '../types';
+```
+
+---
+
+## 9. Diagnostic Quick-Lookup
+
+| Symptom                                         | Surface to check                                                                                                  |     |                           |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | --- | ------------------------- |
+| No header at all on the tool call               | Inspector missing from `client/Inspector/index.ts` registry                                                       |     |                           |
+| Header shows the API name but no chips          | Inspector missing \`args?.X                                                                                       |     | partialArgs?.X\` fallback |
+| Header doesn't pulse during loading             | Missing `shinyTextStyles.shinyText` on `isArgumentsStreaming \|\| isLoading`                                      |     |                           |
+| Empty result card under header                  | Render returned `<div />` instead of `null` when no data                                                          |     |                           |
+| Layout jump when result arrives                 | Placeholder dimensions don't match Render dimensions                                                              |     |                           |
+| Approval dialog never appears                   | Manifest missing `humanIntervention`, or Intervention not in registry                                             |     |                           |
+| Approval click doesn't wait for inline edit     | Missing `registerBeforeApprove(id, flushFn)`                                                                      |     |                           |
+| Portal opens but blank                          | Switch in `Portal/index.tsx` doesn't cover the apiName                                                            |     |                           |
+| Strings show as `builtins.lobe-foo.apiName.bar` | Missing i18n key in `src/locales/default/plugin.ts` (or not seeded in dev locale files)                           |     |                           |
+| Wrong color shade on `<Text type="secondary">`  | `type='secondary'` is lighter than `colorTextSecondary` — pass via `style={{ color: cssVar.colorTextSecondary }}` |     |                           |
@@ -8,6 +8,7 @@ description: >
  (4) Send interactive cards or stream AI responses to chat platforms.
  Triggers on "chat sdk", "chat bot", "slack bot", "teams bot", "discord bot", "@chat-adapter",
  building bots that work across multiple chat platforms.
+user-invocable: false
 ---

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

@@ -8,16 +8,20 @@ Generate text, images, videos, speech, and transcriptions.

 ```
 lh generate (alias: gen)
-├── text <prompt>                    # Text generation
-├── image <prompt>                   # Image generation
-├── video <prompt>                   # Video generation
-├── tts <text>                       # Text-to-speech
-├── asr <audioFile>                  # Audio-to-text (speech recognition)
-├── download <genId> <taskId>        # Wait & download generation result
-├── status <genId> <taskId>          # Check async task status
-└── list                             # List generation topics
+├── text <prompt>                          # Text generation
+├── image <prompt>                         # Image generation
+├── video <prompt>                         # Video generation
+├── tts <text>                             # Text-to-speech
+├── asr <audioFile>                        # Audio-to-text (speech recognition)
+├── download <generationId> <asyncTaskId>  # Wait & download generation result
+├── status <generationId> <asyncTaskId>    # Check async task status
+└── list                                   # List generation topics
 ```

+> ⚠️ **Important**: `status` and `download` require an `asyncTaskId` (UUID format, e.g.
+> `7ad0eb13-e9a5-4403-8070-1f7fe95b2f95`), **not** the generation ID (`gen_xxx`).
+> The asyncTaskId is printed after "→ Task" in the `video` / `image` command output.
+
 ---

 ## `lh generate text <prompt>` / `lh gen text <prompt>`
@@ -54,7 +58,7 @@ cat README.md | lh gen text "summarize this" --pipe

 ## `lh generate image <prompt>` / `lh gen image <prompt>`

-Generate images from text prompt. This is an async operation — the command submits the task and returns a generation ID + task ID for tracking.
+Generate images from text prompt. This is an async operation — the command submits the task and returns a generation ID + async task ID for tracking.

 **Source**: `apps/cli/src/commands/generate/image.ts`

@@ -80,17 +84,22 @@ lh gen image "A cute cat" --model dall-e-3 --provider openai --json
 ✓ Image generation started
  Batch ID: gb_xxx
  1 image(s) queued
-  Generation gen_xxx → Task <taskId>
+  Generation gen_xxx → Task 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                            This is the asyncTaskId — use this for status/download

-Use "lh generate status <generationId> <taskId>" to check progress.
+Use "lh generate status <generationId> <asyncTaskId>" to check progress.
 ```

 **Typical workflow**:

 ```bash
-# Generate image, then wait & download
+# 1. Submit generation — note down BOTH IDs from the output
 lh gen image "A cute cat"
-lh gen download <generationId> <taskId> -o cat.png
+#   Generation gen_abc123 → Task 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95
+
+# 2. Wait & download using generationId + asyncTaskId (the UUID)
+lh gen download gen_abc123 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95 -o cat.png
 ```

 ---
@@ -102,7 +111,7 @@ Generate video from text prompt. This is an async operation.
 **Source**: `apps/cli/src/commands/generate/video.ts`

 ```bash
-lh gen video "A cat playing piano" -m < model > -p < provider > [options]
+lh gen video "A cat playing piano" -m <model> -p <provider> [options]
 ```

 | Option                      | Description              | Required |
@@ -122,9 +131,26 @@ lh gen video "A cat playing piano" -m < model > -p < provider > [options]
 ```
 ✓ Video generation started
  Batch ID: gb_xxx
-  Generation gen_xxx → Task <taskId>
+  Generation gen_xxx → Task 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+                            This is the asyncTaskId — use this for status/download

-Use "lh generate status <generationId> <taskId>" to check progress.
+Use "lh generate status <generationId> <asyncTaskId>" to check progress.
+```
+
+**Typical workflow**:
+
+```bash
+# 1. Find available video models for a provider
+lh model list volcengine --json | grep -i seedance
+
+# 2. Submit generation — note down BOTH IDs from the output
+lh gen video "A cat on a runway" -m doubao-seedance-2-0-260128 -p volcengine \
+  --aspect-ratio 9:16 --duration 5 --resolution 1080p
+#   Generation gen_abc123 → Task 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95
+
+# 3. Wait & download using generationId + asyncTaskId (the UUID)
+lh gen download gen_abc123 7ad0eb13-e9a5-4403-8070-1f7fe95b2f95 -o result.mp4 --timeout 600
 ```

 ---
@@ -153,15 +179,18 @@ lh gen asr recording.wav [options]

 ---

-## `lh generate download <generationId> <taskId>`
+## `lh generate download <generationId> <asyncTaskId>`

 Wait for an async generation task to complete and download the result file.

 **Source**: `apps/cli/src/commands/generate/index.ts`

+> ⚠️ `<asyncTaskId>` is the UUID printed after "→ Task" in the video/image output.
+> Do **not** pass the generation ID (`gen_xxx`) here — that will cause a server error.
+
 ```bash
-lh gen download <generationId> <taskId> [-o output.png]
-lh gen download gen_xxx task_xxx -o ~/Desktop/result.mp4 --timeout 600
+lh gen download <generationId> <asyncTaskId> [-o output.png]
+lh gen download gen_xxx 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx -o ~/Desktop/result.mp4 --timeout 600
 ```

 | Option                | Description                              | Default                |
@@ -175,30 +204,21 @@ lh gen download gen_xxx task_xxx -o ~/Desktop/result.mp4 --timeout 600
 1. Polls `generation.getGenerationStatus` at the specified interval
 2. Shows live progress: `⋯ Status: processing... (42s)`
 3. On success: downloads asset URL to local file
-4. On error: displays error message and exits
+4. On error / wrong ID: displays a clear message pointing to the correct ID format
 5. On timeout: suggests using `lh gen status` to check later

-**Typical workflow**:
-
-```bash
-# One-shot: generate and download
-lh gen image "A sunset"
-# Copy the generation ID and task ID from output
-lh gen download gen_xxx taskId_xxx -o sunset.png
-
-# Video (longer timeout)
-lh gen video "A cat running" -m model -p provider
-lh gen download gen_xxx taskId_xxx -o cat.mp4 --timeout 600
-```
-
 ---

-## `lh generate status <generationId> <taskId>`
+## `lh generate status <generationId> <asyncTaskId>`

 Check the status of an async generation task.

+> ⚠️ `<asyncTaskId>` is the UUID printed after "→ Task" in the video/image output.
+> Do **not** pass the generation ID (`gen_xxx`) here — that will cause a server error.
+
 ```bash
-lh gen status <generationId> <taskId> [--json]
+lh gen status <generationId> <asyncTaskId> [--json]
+lh gen status gen_xxx 7ad0eb13-xxxx-xxxx-xxxx-xxxxxxxxxxxx
 ```

 | Option   | Description              |
@@ -235,12 +255,17 @@ Image and video generation use an async task pattern:
   - Triggers async background task (image via `createAsyncCaller`, video via `initModelRuntimeFromDB`)
   - Returns `{ data: { batch, generations }, success }` with `asyncTaskId` in each generation
 3. **Poll status** → `generation.getGenerationStatus`
+   - Input: `{ generationId, asyncTaskId }` — both are required, and `asyncTaskId` must be the
+     UUID from the `async_tasks` table, not `gen_xxx`
   - Returns `{ status, error, generation }` (generation includes asset URLs on success)
+   - Before querying, calls `checkTimeoutTasks` which marks tasks as `error` if they have been
+     `pending` or `processing` for more than ~5 minutes (`ASYNC_TASK_TIMEOUT = 298s`)

 **Server routes**:

 - `src/server/routers/lambda/image/index.ts` — image creation (uses `authedProcedure` + `serverDatabase`)
 - `src/server/routers/lambda/video/index.ts` — video creation (uses `authedProcedure` + `serverDatabase`)
 - `src/server/routers/lambda/generation.ts` — status checking
+- `packages/database/src/models/asyncTask.ts` — `AsyncTaskModel` including `checkTimeoutTasks`

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

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

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

@@ -1,6 +1,7 @@
 ---
 name: drizzle
-description: Drizzle ORM schema and database guide. Use when working with database schemas (src/database/schemas/*), defining tables, creating migrations, or database model code. Triggers on Drizzle schema definition, database migrations, or ORM usage questions.
+description: "Drizzle ORM schema authoring and query style for LobeHub (postgres, strict mode). Use when editing anything under `src/database/schemas/`, defining `pgTable` columns/indexes/junction tables, spreading `...timestamps`, generating `createInsertSchema`/`$inferSelect`/`$inferInsert` types, writing `db.select().from(...).leftJoin(...)` queries, or deciding when to split a relational `with:` into two queries. Triggers on `pgTable`, `db.select`, `db.query`, `eq()`/`and()`/`inArray()`, `uniqueIndex`, `primaryKey`, `references({ onDelete })`, 'add a column', 'new table', 'foreign key', 'junction table', 'schema field'. For migration files specifically, see the `db-migrations` skill."
+user-invocable: false
 ---

 # Drizzle ORM Schema Style Guide
@@ -125,11 +126,7 @@ The relational API generates complex lateral joins with `json_build_array` that

 ```typescript
 // ✅ Good
-const [result] = await this.db
-  .select()
-  .from(agents)
-  .where(eq(agents.id, id))
-  .limit(1);
+const [result] = await this.db.select().from(agents).where(eq(agents.id, id)).limit(1);
 return result;

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

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

 # LobeHub Internationalization Guide
@@ -1,44 +1,55 @@
 ---
 name: linear
-description: "Linear issue management. MUST USE when: (1) user mentions LOBE-xxx issue IDs (e.g. LOBE-4540), (2) user says 'linear', 'linear issue', 'link linear', (3) creating PRs that reference Linear issues. Provides workflows for retrieving issues, updating status, and adding comments."
+description: "Linear issue management. Use when the user mentions LOBE-xxx issue IDs (e.g. LOBE-4540), says 'linear' / 'linear issue' / 'link linear', or when creating PRs that reference Linear issues. Covers retrieving issues, updating status, adding completion comments, and creating sub-issue trees."
+user-invocable: false
 ---

 # Linear Issue Management

 Before using Linear workflows, search for `linear` MCP tools. If not found, treat as not installed.

-## ⚠️ CRITICAL: PR Creation with Linear Issues
+## PR Creation with Linear Issues

-**When creating a PR that references Linear issues (LOBE-xxx), you MUST:**
+A PR that fixes a Linear issue has **two separate jobs to do**, and both matter:

-1. Create the PR with magic keywords (`Fixes LOBE-xxx`)
-2. **IMMEDIATELY after PR creation**, add completion comments to ALL referenced Linear issues
-3. Do NOT consider the task complete until Linear comments are added
+1. **`Fixes LOBE-xxx` in the PR body** — Linear watches GitHub for these magic keywords and auto-links the PR and auto-closes the issue on merge. This is the machine-readable side.
+2. **A completion comment on the Linear issue** — gives the reviewer/PM/teammate landing in Linear a human-readable summary of what changed and why, without forcing them to click through to GitHub and read a diff.

-This is NON-NEGOTIABLE. Skipping Linear comments is a workflow violation.
+If you only do step 1, Linear watchers (often non-engineers) hit the issue and see no context. So pair PR creation with the Linear comment as part of the same task — finish both before considering the work done.

 ## Workflow

 1. **Retrieve issue details** before starting: `mcp__linear-server__get_issue`
-2. **Read images**: If the issue description contains images, MUST use `mcp__linear-server__extract_images` to read image content for full context
-3. **Check for sub-issues**: Use `mcp__linear-server__list_issues` with `parentId` filter
-4. **Mark as In Progress**: When starting to plan or implement an issue, immediately update status to **"In Progress"** via `mcp__linear-server__update_issue`
+2. **Read images** — issue descriptions often contain screenshots with critical context (mockups, error states, before/after). Use `mcp__linear-server__extract_images` so you actually see them; reading raw markdown alone misses what the reporter was looking at.
+3. **Check for sub-issues**: `mcp__linear-server__list_issues` with `parentId` filter
+4. **Mark as In Progress** at the moment you start planning or implementing — this signals to teammates the issue is owned, so they don't double-pick it up.
 5. **Update issue status** when completing: `mcp__linear-server__update_issue`
-6. **Add completion comment** (REQUIRED): `mcp__linear-server__create_comment`
+6. **Add completion comment** (see [format below](#completion-comment-format))

 ## Creating Issues

-When creating issues with `mcp__linear-server__create_issue`, **MUST add the `claude code` label**.
+When creating issues with `mcp__linear-server__create_issue`, add the `claude code` label. Reason: the label is how the team filters/audits AI-generated issues; without it those issues vanish into the general backlog and the team loses visibility into AI contribution patterns.
+
+## Language
+
+Match the issue language to the conversation that produced it — if you're discussing in 中文，write the issue in 中文；if discussing in English, write it in English. Reason: the issue is a continuation of the conversation, and forcing a language switch creates translation friction for the collaborator who started the thread.
+
+Specifics:
+
+- 中文 conversation → 中文 body; technical terms (file paths, identifiers, library names, commands, error messages) stay in English.
+- English conversation → English body.
+- Code blocks, file paths, and quoted strings always stay in their original form regardless of surrounding language.
+- This applies equally to **updates** — when editing an existing issue (description **and titles**), preserve the language of the conversation that triggered the edit; don't switch the issue language mid-refactor.

 ## Creating Sub-issue Trees

 When breaking a parent issue into a tree of sub-issues (e.g., task decomposition for LOBE-xxx), follow these rules — they work around real limitations of the Linear MCP tools.

-### 1. ALWAYS prefix titles with an ordering index
+### 1. Prefix titles with an ordering index

-The Linear Sub-issues panel displays children by `sortOrder`, which **defaults to newest-first** (most recently created appears on top). Neither parallel nor serial creation will produce the intended top-to-bottom reading order, and the MCP `save_issue` tool does **not expose a `sortOrder` parameter** — you cannot set order at create time.
+The Linear Sub-issues panel orders children by `sortOrder`, which **defaults to newest-first** (most recently created appears on top). Neither parallel nor serial creation produces the intended top-to-bottom reading order, and the MCP `save_issue` tool does **not expose a `sortOrder` parameter** — you can't set order at create time.

-**Workaround**: encode execution order in the title itself:
+Workaround: encode execution order in the title itself:

 ```plaintext
 [1]     [db]       add schema fields
@@ -89,7 +100,7 @@ The implementer may open only the sub-issue, not the parent — don't rely on co

 ## Completion Comment Format

-Every completed issue MUST have a comment summarizing work done:
+Each completed issue gets a comment summarizing the work, so reviewers and future readers don't have to reconstruct it from the PR diff:

 ```markdown
 ## Changes Summary
@@ -105,34 +116,28 @@ Every completed issue MUST have a comment summarizing work done:
 - ...
 ```

-This is critical for:
+This gives team visibility, code-review context, and a paper trail for future reference.

- Team visibility
- Code review context
- Future reference
+## PR Association

-## PR Association (REQUIRED)
-
-When creating PRs for Linear issues, include magic keywords in PR body:
+When creating PRs for Linear issues, include magic keywords in the PR body:

 - `Fixes LOBE-123`
 - `Closes LOBE-123`
 - `Resolves LOBE-123`

+These trigger Linear's auto-link + auto-close on merge.
+
 ## Per-Issue Completion Rule

-When working on multiple issues, update EACH issue IMMEDIATELY after completing it:
+When working on multiple issues, close out **each one before starting the next** — don't batch all the Linear updates to the end. Batching is where comments get forgotten and issues stay stuck in "In Progress" days after the PR shipped.
+
+For each issue:

 1. Complete implementation
 2. Run `bun run type-check`
 3. Run related tests
 4. Create PR if needed
-5. Update status to **"In Review"** (NOT "Done")
-6. **Add completion comment immediately**
-7. Move to next issue
-
-**Note:** Status → "In Review" when PR created. "Done" only after PR merged.
-
-**❌ Wrong:** Complete all → Create PR → Forget Linear comments
-
-**✅ Correct:** Complete → Create PR → Add Linear comments → Task done
+5. Update status to **"In Review"** (not "Done" — "Done" is for after the PR merges)
+6. Add the completion comment
+7. Move to the next issue
@@ -0,0 +1,93 @@
+# LobeHub gateway streaming + tab-switch test harness
+
+Captures store + DOM state at 200ms intervals so we can prove or disprove
+claims like "切回 tab 后消息回到了很早以前". Built for gateway-mode chat but
+works for any LobeHub streaming session.
+
+## Files
+
+`scripts/agent-gateway/`
+
+| File            | Role                                                             |
+| --------------- | ---------------------------------------------------------------- |
+| `probe.js`      | Injects a 200ms sampler + `__PROBE_EVENT` marker + `__switchTab` |
+| `probe-dump.js` | Stops the sampler and returns `{events, samples}` as JSON string |
+| `tab-switch.js` | Runs N round-trip switches between two tabs, marks each step     |
+| `analyze.mjs`   | Node post-processor: timeline + regression detection             |
+
+## Standard workflow
+
+```bash
+# 1. Start Electron with CDP
+./.agents/skills/local-testing/scripts/electron-dev.sh start
+
+# 2. Navigate to a chat, switch runtime to Cloud Sandbox (gateway mode)
+
+# 3. Install the probe + helpers
+agent-browser --cdp 9222 eval --stdin \
+  < .agents/skills/local-testing/scripts/agent-gateway/probe.js
+
+# 4. Send a tool-call message — manually or via type+press
+agent-browser --cdp 9222 eval "window.__PROBE_EVENT('SENT')"
+
+# 5. Run the multi-switch driver (auto-picks active tab as BACK and the
+#    rightmost inactive tab as AWAY — edit ROUND_TRIPS / DWELL_MS in the
+#    file if you want different timing)
+agent-browser --cdp 9222 eval --stdin \
+  < .agents/skills/local-testing/scripts/agent-gateway/tab-switch.js
+
+# 6. Wait for streaming to finish, then dump
+agent-browser --cdp 9222 eval --stdin \
+  < .agents/skills/local-testing/scripts/agent-gateway/probe-dump.js \
+  > /tmp/probe.json
+
+# 7. Analyze
+node .agents/skills/local-testing/scripts/agent-gateway/analyze.mjs /tmp/probe.json
+```
+
+The analyzer prints three sections: EVENTS, TIMELINE, REGRESSIONS. If
+REGRESSIONS is non-empty it means content/reasoning/childN dropped on the
+same topic — the symptom users describe.
+
+## What the probe tracks (and why)
+
+`chat.messagesMap` only stores the top-level `assistantGroup` shell. The
+actual streamed content, reasoning, and tool calls live in
+`assistantGroup.children: AssistantContentBlock[]`. Any probe that only
+reads `m.content` / `m.reasoning` will see zeros throughout streaming and
+miss everything that matters. probe.js walks both levels and sums:
+
+- `cT` total content length
+- `rT` total reasoning length
+- `toolT` total tool-call count
+- `childN` number of content blocks
+
+Plus DOM-side signals (`domLen`, search/crawl indicator counts) so you can
+tell store-side regressions apart from render-side regressions.
+
+## Gotchas
+
+- **Optimistic new-topic state.** Before the first chunk lands, messages
+  live under the `<scope>_new` key with `tmp_*` ids and no `topicId` field.
+  probe.js falls back to those when `activeTopicId` is null.
+- **Reasoning resets to 0 are not bugs.** When the assistant finishes
+  thinking and starts tool-use or text, the streaming reasoning buffer
+  empties and the finalised reasoning gets sealed into a completed block.
+  Filter these out manually if needed.
+- **DOM length jitters by a handful of chars** because counters like "(10)"
+  in tool-call labels change as results arrive. analyze.mjs only flags
+  `domLen` drops greater than 100 chars to ignore that noise.
+- **Never identify tabs by innerText.** The active tab's text embeds a
+  ` · <agent name>` suffix, so a search like `'LobeHub Growth'` matches the
+  active tab when the active agent happens to be LobeHub Growth — and you
+  end up clicking the tab you're already on. probe.js uses the stable
+  `data-contextmenu-trigger` attribute (a React `useId()` value that's set
+  per-tab and survives focus changes) plus `data-active="true"` to mark
+  the active one. Helpers exposed:
+  `__listTabs()` / `__clickTabByKey(key)` / `__clickTabByIndex(i)` /
+  `__activeTabKey()`.
+- **`tab-switch.js` fires-and-forgets.** The IIFE kicks off an async loop
+  and returns immediately so the agent-browser CLI eval doesn't blow past
+  its default 25 s timeout. Wait on the `SWITCH_LOOP_DONE` event marker
+  before dumping. Re-running while a loop is in flight is refused — the
+  chaotic data from overlapping runs is not worth debugging.
@@ -0,0 +1,243 @@
+// Analyzer for probe-events dumps. Reads a JSON file produced by `run.ts dump`
+// and prints a layered breakdown:
+//
+//   1. STREAM EVENTS — every non-chunk WS/SSE event in receipt order
+//   2. CHUNKS SUMMARY — collapsed per-step chunk counts (otherwise floods)
+//   3. ACTION CALLS — replaceMessages / refreshMessages / MARK:* with stack
+//   4. CORRELATION — calls ↔ nearest stream event within ±300ms
+//   5. PER-KEY ASSISTANT GROWTH — for each messagesMap key, when the leading
+//      assistant message's cLen / rLen actually moves (this is what reveals
+//      "chunks arrived but the message never grew" regressions)
+//   6. ROLLBACKS — msgN / childN / role drops in the active-topic timeline
+//
+// Usage:
+//   bun run .agents/skills/local-testing/scripts/agent-gateway/analyze-events.ts <dump.json>
+
+import { readFileSync } from 'node:fs';
+
+import type {
+  ProbeActionCall,
+  ProbeDump,
+  ProbeMessageSummary,
+  ProbeStreamEvent,
+  ProbeTimelineSample,
+} from './types';
+
+const file = process.argv[2];
+if (!file) {
+  console.error('usage: bun run analyze-events.ts <dump.json>');
+  process.exit(1);
+}
+
+const raw = readFileSync(file, 'utf8');
+// agent-browser eval --stdin wraps return values in quotes when the value is
+// a string — so the JSON file may be double-encoded depending on how it was
+// captured. Handle both.
+const parsedOnce = JSON.parse(raw) as ProbeDump | string;
+const dump: ProbeDump = typeof parsedOnce === 'string' ? JSON.parse(parsedOnce) : parsedOnce;
+
+const { streamEvents = [], actionCalls = [], timeline = [] } = dump;
+
+const pad = (v: unknown, n: number) => String(v).padStart(n);
+
+// ── META ───────────────────────────────────────────────────────────
+console.log('=== META ===');
+console.log(`  events:    ${streamEvents.length}`);
+console.log(`  calls:     ${actionCalls.length}`);
+console.log(`  timeline:  ${timeline.length}`);
+
+// ── 1. STREAM EVENTS (non-chunk) ───────────────────────────────────
+const nonChunkEvents = streamEvents.filter((e) => e.type !== 'stream_chunk');
+const chunkEvents = streamEvents.filter((e) => e.type === 'stream_chunk');
+
+console.log(
+  `\n=== STREAM EVENTS (${nonChunkEvents.length} non-chunk + ${chunkEvents.length} chunks elided) ===`,
+);
+for (const e of nonChunkEvents) {
+  const dataStr = e.dataKeys?.length ? ` [${e.dataKeys.join(',')}]` : '';
+  const data = e.data as Record<string, unknown> | undefined;
+  const uiHint = data?.uiMessagesPreview
+    ? ` uiPreview=${JSON.stringify(data.uiMessagesPreview)}`
+    : data?.uiMessagesTotal
+      ? ` uiTotal=${data.uiMessagesTotal}`
+      : '';
+  const phaseHint = data?.phase ? ` phase=${data.phase}` : '';
+  const extra = e.serverType ? ` serverType=${e.serverType}` : '';
+  console.log(
+    `  t=${pad(e.t, 7)}  [${(e.transport ?? '?').padEnd(3)}]  step=${pad(e.stepIndex ?? '-', 2)}  ` +
+      `type=${(e.type ?? '').padEnd(22)}  op=${e.opIdTail ?? '-'}${phaseHint}${uiHint}${extra}${dataStr}`,
+  );
+}
+
+// ── 2. CHUNK SUMMARY ───────────────────────────────────────────────
+console.log('\n=== CHUNKS SUMMARY (per step / chunkType) ===');
+const chunkBuckets = new Map<string, { count: number; firstT: number; lastT: number }>();
+for (const c of chunkEvents) {
+  const data = c.data as Record<string, unknown> | undefined;
+  const ct = (data?.chunkType as string | undefined) ?? '?';
+  const key = `step=${c.stepIndex ?? '-'}  chunkType=${ct.padEnd(8)}  op=${c.opIdTail}`;
+  const slot = chunkBuckets.get(key);
+  if (slot) {
+    slot.count += 1;
+    slot.lastT = c.t;
+  } else {
+    chunkBuckets.set(key, { count: 1, firstT: c.t, lastT: c.t });
+  }
+}
+for (const [k, v] of chunkBuckets) {
+  console.log(`  ${k}  count=${pad(v.count, 4)}  t=${pad(v.firstT, 7)}..${pad(v.lastT, 7)}`);
+}
+
+// ── 3. ACTION CALLS ───────────────────────────────────────────────
+console.log('\n=== ACTION CALLS (replace/refresh/MARK) ===');
+for (const c of actionCalls) {
+  if (c.name?.startsWith('MARK:')) {
+    console.log(`  t=${pad(c.t, 7)}  ${c.name}`);
+    continue;
+  }
+  const snapshot = (c.args as any)?.snapshot as
+    | Array<{ id: string; role: string; cLen: number; rLen: number }>
+    | undefined;
+  const snapStr = snapshot?.length
+    ? '  snapshot=' + snapshot.map((m) => `${m.id}:${m.role}/c${m.cLen}/r${m.rLen}`).join(' | ')
+    : '';
+  const summary =
+    c.name === 'replaceMessages'
+      ? `count=${c.args?.count} action=${(c.args?.params as any)?.action ?? '-'}${snapStr}`
+      : c.name === 'refreshMessages'
+        ? `ctx=${JSON.stringify(c.args?.context)}`
+        : c.error
+          ? `error=${c.error}`
+          : '';
+  console.log(`  t=${pad(c.t, 7)}  ${c.name.padEnd(20)} ${summary}`);
+  if (c.stack) {
+    const frames = c.stack
+      .split(' ← ')
+      .filter((f) => !!f && !f.includes('Object.<anonymous>'))
+      .slice(0, 3);
+    for (const f of frames) console.log(`             ↳ ${f}`);
+  }
+}
+
+// ── 4. CORRELATION ────────────────────────────────────────────────
+function nearestEventForCall(
+  call: ProbeActionCall,
+  windowMs = 300,
+): { event: ProbeStreamEvent; delta: number } | null {
+  let best: ProbeStreamEvent | null = null;
+  let bestDelta = Infinity;
+  for (const e of streamEvents) {
+    const d = Math.abs(e.t - call.t);
+    if (d < bestDelta && d <= windowMs) {
+      bestDelta = d;
+      best = e;
+    }
+  }
+  return best ? { event: best, delta: bestDelta } : null;
+}
+
+console.log('\n=== CORRELATION (replace/refresh ↔ nearest event within ±300ms) ===');
+for (const c of actionCalls) {
+  if (c.name !== 'refreshMessages' && c.name !== 'replaceMessages') continue;
+  const hit = nearestEventForCall(c);
+  if (hit) {
+    const phase = (hit.event.data as Record<string, unknown> | undefined)?.phase;
+    console.log(
+      `  t=${pad(c.t, 7)}  ${c.name.padEnd(16)} ← Δ${pad(hit.delta, 4)}ms ${hit.event.type}` +
+        (phase ? ` phase=${phase}` : ''),
+    );
+  } else {
+    console.log(`  t=${pad(c.t, 7)}  ${c.name.padEnd(16)} ← (no event nearby — external trigger)`);
+  }
+}
+
+// ── 5. PER-KEY ASSISTANT GROWTH ───────────────────────────────────
+// For each messagesMap key, find the trailing assistant message and report
+// the points in time where its cLen / rLen actually changed. If the timeline
+// shows chunks arriving but the assistant cLen never moves, that's the
+// signature of "dispatch queue blocked / messageId mismatch".
+console.log('\n=== PER-KEY ASSISTANT GROWTH ===');
+const keysEverSeen = new Set<string>();
+for (const s of timeline) for (const k of Object.keys(s.byKey ?? {})) keysEverSeen.add(k);
+
+for (const key of keysEverSeen) {
+  console.log(`\n  key=${key}`);
+  let lastSig: string | null = null;
+  for (const s of timeline) {
+    const slot = s.byKey?.[key];
+    if (!slot) continue;
+    const last = slot.msgs.at(-1) as ProbeMessageSummary | undefined;
+    if (!last) continue;
+    const sig = `${last.id}|c${last.cLen}|r${last.rLen}|n${slot.n}`;
+    if (sig === lastSig) continue;
+    lastSig = sig;
+    console.log(
+      `    t=${pad(s.t, 7)}  msgN=${pad(slot.n, 3)}  ` +
+        `lastAssistant=${last.id}  cLen=${pad(last.cLen, 5)}  rLen=${pad(last.rLen, 5)}` +
+        `  runOps=${s.runOps}`,
+    );
+  }
+}
+
+// ── 6. ROLLBACKS (active-topic msgN / childN / role drops) ─────────
+console.log('\n=== ROLLBACKS (active-topic msgN / childN / role drops) ===');
+let prev: ProbeTimelineSample | null = null;
+const rollbacks: Array<{ t: number; topic: string | null; drops: string[] }> = [];
+
+const flatten = (s: ProbeTimelineSample) => {
+  if (!s.activeTopic) return [];
+  return Object.entries(s.byKey ?? {})
+    .filter(([k]) => k.includes(s.activeTopic!))
+    .flatMap(([, v]) => v.msgs);
+};
+
+for (const s of timeline) {
+  if (s.err) {
+    prev = null;
+    continue;
+  }
+  if (!prev || prev.activeTopic !== s.activeTopic) {
+    prev = s;
+    continue;
+  }
+  const prevMsgs = flatten(prev);
+  const curMsgs = flatten(s);
+  const drops: string[] = [];
+
+  if (curMsgs.length < prevMsgs.length) drops.push(`msgN ${prevMsgs.length}→${curMsgs.length}`);
+
+  let prevChild = 0;
+  let curChild = 0;
+  for (const m of prevMsgs) prevChild += m.chN ?? 0;
+  for (const m of curMsgs) curChild += m.chN ?? 0;
+  if (curChild < prevChild) drops.push(`childN ${prevChild}→${curChild}`);
+
+  const prevById = new Map(prevMsgs.map((m) => [m.id, m]));
+  for (const m of curMsgs) {
+    const pr = prevById.get(m.id);
+    if (!pr) continue;
+    if (m.cLen < pr.cLen) drops.push(`cLen[${m.id}] ${pr.cLen}→${m.cLen}`);
+    if (m.rLen < pr.rLen) drops.push(`rLen[${m.id}] ${pr.rLen}→${m.rLen}`);
+  }
+
+  if (drops.length) rollbacks.push({ t: s.t, topic: s.activeTopic, drops });
+  prev = s;
+}
+
+if (rollbacks.length === 0) {
+  console.log('  (none)');
+} else {
+  for (const r of rollbacks) {
+    const nearEvent = streamEvents
+      .filter((e) => Math.abs(e.t - r.t) <= 300)
+      .map((e) => `${e.type}${(e.data as any)?.phase ? ':' + (e.data as any).phase : ''}`);
+    const nearCall = actionCalls
+      .filter((c) => Math.abs(c.t - r.t) <= 300 && !c.name?.startsWith('MARK:'))
+      .map((c) => c.name);
+    console.log(
+      `  t=${pad(r.t, 7)}  topic=${r.topic}  ${r.drops.join(' | ')}` +
+        (nearEvent.length ? `  near-event:[${nearEvent.join(',')}]` : '') +
+        (nearCall.length ? `  near-call:[${nearCall.join(',')}]` : ''),
+    );
+  }
+}
@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+// Analyze a probe dump captured by probe.js + probe-dump.js.
+//
+//   node analyze.mjs /tmp/probe.json
+//
+// Prints:
+//   1. EVENTS — user-action markers with their relative timestamps
+//   2. TIMELINE — periodic samples (~1 per second + event-adjacent samples)
+//      showing every interesting field; columns:
+//        t(ms) | runOps | msgN | childN | content | reasoning | tools | domLen | search | crawl | topic | event
+//   3. REGRESSIONS — every place a tracked counter *dropped* on the same
+//      topic between adjacent samples. A "true" UI rollback shows up as a
+//      drop in content/reasoning/tools/childN/domLen without a topic change.
+//
+// Whitelisted transitions (not flagged):
+//   - topic change → all drops expected (focus moved away)
+//   - reasoning length 0 after content starts → reasoning gets sealed into a
+//     completed sub-block; the parent's running reasoning resets to ''.
+//   - msgN drop when topic transitions from `_new` placeholder to a real id.
+
+import fs from 'node:fs';
+
+const file = process.argv[2];
+if (!file) {
+  console.error('usage: node analyze.mjs <probe.json>');
+  process.exit(1);
+}
+
+const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+// probe-dump.js wraps the payload in JSON.stringify so agent-browser returns
+// it as a single quoted string. Unwrap.
+const data = typeof raw === 'string' ? JSON.parse(raw) : raw;
+const { events, samples } = data;
+
+const fmt = {
+  pad(v, n) {
+    return String(v).padStart(n);
+  },
+};
+
+console.log('=== EVENTS ===');
+for (const e of events) console.log(`  t=${fmt.pad(e.t, 7)}  ${e.name}`);
+
+console.log(
+  '\n=== TIMELINE (~1s cadence, plus event-adjacent samples) ===\n' +
+    '  t(ms)   runOps  msgN childN  content reasoning tools  domLen  search crawl  topic     event',
+);
+
+let lastSampledAt = -1e9;
+const eventBuckets = events.map((e) => e.t);
+for (let i = 0; i < samples.length; i++) {
+  const s = samples[i];
+  const nearEvent = eventBuckets.some((et) => Math.abs(et - s.t) < 110);
+  if (!nearEvent && s.t - lastSampledAt < 1000) continue;
+  lastSampledAt = s.t;
+
+  const ev = events.find((e) => Math.abs(e.t - s.t) < 110);
+  const evMarker = ev ? `  ◀ ${ev.name}` : '';
+  const topicSuffix = s.topicId ? s.topicId.slice(-6) : '(none)';
+  const search = s.ind?.search ?? 0;
+  const crawl = s.ind?.crawl ?? 0;
+  console.log(
+    `  ${fmt.pad(s.t, 6)} ` +
+      `${fmt.pad(s.runOps, 6)}  ` +
+      `${fmt.pad(s.msgN, 4)}  ` +
+      `${fmt.pad(s.childN ?? 0, 5)} ` +
+      `${fmt.pad(s.cT ?? 0, 8)} ` +
+      `${fmt.pad(s.rT ?? 0, 9)} ` +
+      `${fmt.pad(s.toolT ?? 0, 5)} ` +
+      `${fmt.pad(s.domLen ?? 0, 7)} ` +
+      `${fmt.pad(search, 6)} ` +
+      `${fmt.pad(crawl, 5)}  ` +
+      `${topicSuffix.padEnd(8)}${evMarker}`,
+  );
+}
+
+console.log('\n=== REGRESSIONS (same topic, value dropped) ===');
+const regressions = [];
+for (let i = 1; i < samples.length; i++) {
+  const prev = samples[i - 1];
+  const cur = samples[i];
+  if (!cur.topicId || prev.topicId !== cur.topicId) continue;
+
+  const drops = [];
+  if (cur.msgN < prev.msgN) drops.push(`msgN: ${prev.msgN}→${cur.msgN}`);
+  if ((cur.childN ?? 0) < (prev.childN ?? 0)) drops.push(`childN: ${prev.childN}→${cur.childN}`);
+  if ((cur.cT ?? 0) < (prev.cT ?? 0)) drops.push(`content: ${prev.cT}→${cur.cT}`);
+  if ((cur.rT ?? 0) < (prev.rT ?? 0)) drops.push(`reasoning: ${prev.rT}→${cur.rT}`);
+  if ((cur.toolT ?? 0) < (prev.toolT ?? 0)) drops.push(`tools: ${prev.toolT}→${cur.toolT}`);
+  // domLen jitters by a few chars from counter labels — only flag big drops.
+  if ((cur.domLen ?? 0) < (prev.domLen ?? 0) - 100) {
+    drops.push(`domLen: ${prev.domLen}→${cur.domLen}`);
+  }
+  if (drops.length === 0) continue;
+
+  const nearbyEv = events.filter((e) => Math.abs(e.t - cur.t) < 600).map((e) => e.name);
+  regressions.push({ t: cur.t, topic: cur.topicId.slice(-6), drops, nearbyEv });
+}
+
+if (regressions.length === 0) {
+  console.log('  (none)');
+} else {
+  for (const r of regressions) {
+    const evStr = r.nearbyEv.length ? `  near:[${r.nearbyEv.join(',')}]` : '';
+    console.log(`  t=${fmt.pad(r.t, 7)}  topic=${r.topic}  ${r.drops.join(' | ')}${evStr}`);
+  }
+}
+
+console.log(`\n=== SUMMARY ===`);
+console.log(`  samples: ${samples.length}`);
+console.log(`  events:  ${events.length}`);
+console.log(`  regressions: ${regressions.length}`);
+if (samples.length) {
+  const last = samples.at(-1);
+  console.log(
+    `  final: msgN=${last.msgN} childN=${last.childN ?? 0} content=${last.cT ?? 0} ` +
+      `reasoning=${last.rT ?? 0} tools=${last.toolT ?? 0} runOps=${last.runOps}`,
+  );
+}
@@ -0,0 +1,17 @@
+// Stop the probe and serialize collected data.
+//
+//   agent-browser --cdp 9222 eval --stdin < probe-dump.js > /tmp/probe.json
+//
+// The whole thing is wrapped in a JSON.stringify so agent-browser returns it
+// as a single quoted string — the analyzer double-parses to handle that.
+
+(function () {
+  if (window.__PROBE_TIMER) {
+    clearInterval(window.__PROBE_TIMER);
+    window.__PROBE_TIMER = null;
+  }
+  return JSON.stringify({
+    events: window.__PROBE_EVENTS || [],
+    samples: window.__PROBE_SAMPLES || [],
+  });
+})();
@@ -0,0 +1,37 @@
+// Stops the events-probe timeline timer and stashes the full capture as a
+// JSON string on `window.__PROBE_LAST_DUMP_JSON`. `run.ts` wraps the bundle
+// in an IIFE that returns that global, which `agent-browser eval` prints to
+// stdout — the runner then persists it under `.agent-gateway/`.
+
+import type { ProbeDump } from './types';
+
+declare global {
+  interface Window {
+    __PROBE_LAST_DUMP_JSON?: string;
+  }
+}
+
+const w = window;
+
+if (w.__PROBE_TIMELINE_TIMER) {
+  clearInterval(w.__PROBE_TIMELINE_TIMER);
+  w.__PROBE_TIMELINE_TIMER = null;
+}
+
+const mutations = w.__PROBE_MUTATIONS ?? [];
+
+const dump: ProbeDump & { mutations: typeof mutations } = {
+  meta: {
+    t0: w.__PROBE_T0 ?? 0,
+    collectedAt: Date.now(),
+    sampleCount: (w.__PROBE_MSG_TIMELINE ?? []).length,
+    eventCount: (w.__PROBE_STREAM_EVENTS ?? []).length,
+    callCount: (w.__PROBE_ACTION_CALLS ?? []).length,
+  },
+  streamEvents: w.__PROBE_STREAM_EVENTS ?? [],
+  actionCalls: w.__PROBE_ACTION_CALLS ?? [],
+  timeline: w.__PROBE_MSG_TIMELINE ?? [],
+  mutations,
+};
+
+w.__PROBE_LAST_DUMP_JSON = JSON.stringify(dump);
@@ -0,0 +1,637 @@
+// LobeHub gateway raw-event-stream probe.
+//
+// Gateway-mode chats subscribe via WebSocket — NOT via the `/api/agent/stream`
+// SSE endpoint (that one belongs to the direct/client durable-agent runtime).
+// `AgentStreamClient` (`packages/agent-gateway-client/src/client.ts`) opens
+// `new WebSocket('wss://.../ws?operationId=...')`, then parses JSON frames in
+// its `onmessage` handler and re-emits `agent_event.event` objects to the
+// chat store.
+//
+// To capture the RAW gateway events before the store touches them, we wrap
+// `window.WebSocket` so that for any socket whose URL contains `operationId=`
+// we intercept the `onmessage` handler / `addEventListener('message')` and
+// log every `agent_event` frame.
+//
+// We *also* keep the `window.fetch` hook for `/api/agent/stream` so this
+// probe still works for direct-mode runs — but gateway-mode events come
+// through the WebSocket path.
+//
+// Buffers (read via `dump`):
+//   __PROBE_STREAM_EVENTS  — raw events parsed off the wire
+//   __PROBE_ACTION_CALLS   — replaceMessages / refreshMessages calls (best-effort)
+//   __PROBE_MSG_TIMELINE   — 200ms snapshots of every messagesMap key
+
+import type {
+  ProbeActionCall,
+  ProbeMessageSummary,
+  ProbeStreamEvent,
+  ProbeTimelineSample,
+} from './types';
+
+// Bundled by esbuild as an IIFE. Top-level code runs once on injection.
+
+const w = window;
+
+// ── Buffers ─────────────────────────────────────────────────────────
+
+declare global {
+  interface Window {
+    __PROBE_MUTATIONS?: Array<{
+      t: number;
+      key: string;
+      n: number;
+      last?: { id: string; role: string; cLen: number; rLen: number; updatedAt?: unknown };
+      prevLast?: { id: string; role: string; cLen: number; rLen: number };
+      delta?: string;
+    }>;
+    __PROBE_STORE_UNSUB?: () => void;
+  }
+}
+
+const events: ProbeStreamEvent[] = (w.__PROBE_STREAM_EVENTS ??= []);
+const calls: ProbeActionCall[] = (w.__PROBE_ACTION_CALLS ??= []);
+const timeline: ProbeTimelineSample[] = (w.__PROBE_MSG_TIMELINE ??= []);
+const mutations = (w.__PROBE_MUTATIONS ??= []);
+events.length = 0;
+calls.length = 0;
+timeline.length = 0;
+mutations.length = 0;
+
+const t0 = Date.now();
+w.__PROBE_T0 = t0;
+const now = (): number => Date.now() - t0;
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+function summarizeData(data: unknown): Record<string, unknown> | unknown {
+  if (!data || typeof data !== 'object') return data;
+  const src = data as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const k of Object.keys(src)) {
+    const v = src[k];
+    if (v == null) {
+      out[k] = v;
+    } else if (Array.isArray(v)) {
+      out[k] = `Array(${v.length})`;
+      if (k === 'uiMessages') {
+        out.uiMessagesPreview = v.slice(0, 5).map((m: any) => ({
+          id: (m.id ?? '').slice(-8),
+          role: m.role,
+          cLen: (m.content ?? '').length,
+          children: (m.children ?? []).length,
+          tools: (m.tools ?? []).length,
+          reasoning: (m.reasoning?.content ?? '').length,
+        }));
+        out.uiMessagesTotal = v.length;
+      }
+    } else if (typeof v === 'object') {
+      const obj = v as Record<string, unknown>;
+      out[k] =
+        'Object{' +
+        Object.keys(obj)
+          .slice(0, 6)
+          .map((kk) => kk + (typeof obj[kk] === 'string' ? `=${(obj[kk] as string).length}ch` : ''))
+          .join(',') +
+        '}';
+    } else if (typeof v === 'string') {
+      out[k] = v.length > 100 ? v.slice(0, 100) + `…(${v.length})` : v;
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+function summarizeMessages(msgs: any[]): ProbeMessageSummary[] {
+  return (msgs ?? []).slice(0, 80).map((m) => ({
+    id: (m.id ?? '').slice(-8),
+    role: m.role,
+    cLen: (m.content ?? '').length,
+    rLen: (m.reasoning?.content ?? '').length,
+    tools: (m.tools ?? []).length,
+    chN: (m.children ?? []).length,
+  }));
+}
+
+function shortStack(): string {
+  const raw = new Error('probe-stack').stack ?? '';
+  return raw
+    .split('\n')
+    .slice(3)
+    .filter((l) => !l.includes('probe-events') && !l.includes('node_modules'))
+    .map((l) => l.trim().replace(/^at\s+/, ''))
+    .slice(0, 6)
+    .join(' ← ');
+}
+
+function recordAgentEvent(args: {
+  transport: 'ws' | 'sse';
+  opId: string | null;
+  agentEvent: any;
+  eventId?: string | null;
+  rawLen?: number;
+}): void {
+  const { transport, opId, agentEvent, eventId, rawLen } = args;
+  if (!agentEvent || typeof agentEvent !== 'object') return;
+  events.push({
+    t: now(),
+    transport,
+    opIdTail: (opId ?? '').slice(-10),
+    eventId: eventId ?? null,
+    type: agentEvent.type,
+    stepIndex: agentEvent.stepIndex,
+    dataKeys: agentEvent.data ? Object.keys(agentEvent.data) : [],
+    data: summarizeData(agentEvent.data) as Record<string, unknown>,
+    rawLen,
+  });
+}
+
+// ── 1. Patch window.WebSocket for gateway WS events ────────────────
+
+if (!w.__PROBE_ORIG_WEBSOCKET) w.__PROBE_ORIG_WEBSOCKET = w.WebSocket;
+const OrigWS = w.__PROBE_ORIG_WEBSOCKET;
+
+function extractOpIdFromWsUrl(url: string | URL): string | null {
+  const m = String(url ?? '').match(/operationId=([^&]+)/);
+  return m ? decodeURIComponent(m[1]) : null;
+}
+
+function isGatewayWs(url: string | URL): boolean {
+  return String(url ?? '').includes('operationId=');
+}
+
+function handleWsFrame(rawData: unknown, opId: string | null): void {
+  const rawLen = typeof rawData === 'string' ? rawData.length : -1;
+  let parsed: any;
+  try {
+    parsed = typeof rawData === 'string' ? JSON.parse(rawData) : null;
+  } catch {
+    events.push({
+      t: now(),
+      transport: 'ws',
+      opIdTail: (opId ?? '').slice(-10),
+      type: '_PARSE_ERROR_',
+      raw: typeof rawData === 'string' && rawData.length < 400 ? rawData : '(non-string or large)',
+    });
+    return;
+  }
+  if (!parsed) return;
+
+  if (parsed.type === 'agent_event') {
+    recordAgentEvent({
+      transport: 'ws',
+      opId,
+      agentEvent: parsed.event,
+      eventId: parsed.id,
+      rawLen,
+    });
+  } else {
+    events.push({
+      t: now(),
+      transport: 'ws',
+      opIdTail: (opId ?? '').slice(-10),
+      type: '_SERVER_MSG_',
+      serverType: parsed.type,
+      rawLen,
+    });
+  }
+}
+
+// Wrap the constructor. Instance `constructor` will still reflect OrigWS
+// (we share prototypes), so use the `_WS_OPEN_` sentinel events to confirm
+// the patch is firing.
+function PatchedWebSocket(this: WebSocket, url: string | URL, protocols?: string | string[]) {
+  const ws: WebSocket = protocols == null ? new OrigWS(url) : new OrigWS(url, protocols);
+  const opId = extractOpIdFromWsUrl(url);
+  if (!isGatewayWs(url)) return ws;
+
+  events.push({
+    t: now(),
+    transport: 'ws',
+    opIdTail: (opId ?? '').slice(-10),
+    type: '_WS_OPEN_',
+    url: String(url),
+  });
+
+  // One observer listener that always fires, regardless of how the consumer
+  // (AgentStreamClient uses `ws.onmessage = …`) subscribes.
+  ws.addEventListener('message', (e) => {
+    try {
+      handleWsFrame((e as MessageEvent).data, opId);
+    } catch {
+      /* swallow */
+    }
+  });
+
+  ws.addEventListener('close', () => {
+    events.push({
+      t: now(),
+      transport: 'ws',
+      opIdTail: (opId ?? '').slice(-10),
+      type: '_WS_CLOSE_',
+    });
+  });
+
+  return ws;
+}
+
+// Preserve prototype + static fields so `instanceof WebSocket` and
+// `WebSocket.OPEN` constants still work.
+(PatchedWebSocket as unknown as { prototype: WebSocket }).prototype = OrigWS.prototype;
+for (const k of Object.keys(OrigWS) as Array<keyof typeof OrigWS>) {
+  try {
+    (PatchedWebSocket as any)[k] = (OrigWS as any)[k];
+  } catch {
+    /* readonly */
+  }
+}
+(['CONNECTING', 'OPEN', 'CLOSING', 'CLOSED'] as const).forEach((k) => {
+  (PatchedWebSocket as any)[k] = (OrigWS as any)[k];
+});
+w.WebSocket = PatchedWebSocket as unknown as typeof WebSocket;
+
+// ── 2. Patch window.fetch for `/api/agent/stream` (direct-mode SSE) ─
+
+if (!w.__PROBE_ORIG_FETCH) w.__PROBE_ORIG_FETCH = w.fetch.bind(w);
+const origFetch = w.__PROBE_ORIG_FETCH;
+
+function isAgentStreamUrl(input: RequestInfo | URL): boolean {
+  let url = '';
+  if (typeof input === 'string') url = input;
+  else if (input instanceof URL) url = input.toString();
+  else if (input && typeof (input as Request).url === 'string') url = (input as Request).url;
+  return url.includes('/api/agent/stream');
+}
+
+function extractOpIdFromHttpUrl(input: RequestInfo | URL): string | null {
+  const url = typeof input === 'string' ? input : (input as Request | URL).toString();
+  const m = url.match(/operationId=([^&]+)/);
+  return m ? decodeURIComponent(m[1]) : null;
+}
+
+function pushFromSSEFrame(rawFrame: string, opId: string | null): void {
+  const lines = rawFrame.split('\n');
+  let dataJson = '';
+  let evtName = 'message';
+  for (const line of lines) {
+    if (line.startsWith('event:')) evtName = line.slice(6).trim();
+    else if (line.startsWith('data:')) dataJson += line.slice(5).trim();
+  }
+  if (!dataJson) return;
+  let parsed: any;
+  try {
+    parsed = JSON.parse(dataJson);
+  } catch {
+    events.push({
+      t: now(),
+      transport: 'sse',
+      opIdTail: (opId ?? '').slice(-10),
+      type: '_PARSE_ERROR_',
+      sseEvent: evtName,
+      raw: dataJson.length > 400 ? dataJson.slice(0, 400) + '…' : dataJson,
+    });
+    return;
+  }
+  recordAgentEvent({
+    transport: 'sse',
+    opId,
+    agentEvent: parsed,
+    eventId: null,
+    rawLen: dataJson.length,
+  });
+}
+
+async function teeAndDrain(response: Response, opId: string | null): Promise<Response> {
+  if (!response.body) return response;
+  const [a, b] = response.body.tee();
+
+  void (async () => {
+    const reader = b.getReader();
+    const decoder = new TextDecoder();
+    let buf = '';
+    try {
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        let idx: number;
+
+        while ((idx = buf.indexOf('\n\n')) !== -1) {
+          const frame = buf.slice(0, idx);
+          buf = buf.slice(idx + 2);
+          if (frame.trim()) pushFromSSEFrame(frame, opId);
+        }
+      }
+      if (buf.trim()) pushFromSSEFrame(buf, opId);
+    } catch (e: any) {
+      events.push({
+        t: now(),
+        transport: 'sse',
+        opIdTail: (opId ?? '').slice(-10),
+        type: '_TEE_ERROR_',
+        message: String(e?.message ?? e),
+      });
+    }
+  })();
+
+  return new Response(a, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText,
+  });
+}
+
+w.fetch = async function patchedFetch(input: RequestInfo | URL, init?: RequestInit) {
+  const response = await origFetch(input as any, init);
+  if (!isAgentStreamUrl(input)) return response;
+  const opId = extractOpIdFromHttpUrl(input);
+  const url =
+    typeof input === 'string'
+      ? input.split('?')[0]
+      : (input as Request | URL).toString().split('?')[0];
+  events.push({
+    t: now(),
+    transport: 'sse',
+    opIdTail: (opId ?? '').slice(-10),
+    type: '_CONNECTED_',
+    url,
+    status: response.status,
+  });
+  return teeAndDrain(response, opId);
+} as typeof fetch;
+
+// ── 3. Wrap store actions (best-effort for "who called replace") ────
+
+// Side-global stash for the original chat-store actions. Re-installs ALWAYS
+// rewrap from the originals so updates to the probe body take effect
+// without a page reload — using only a `__probeWrapped` flag on the chat
+// state object would freeze the first-installed wrapper across re-installs.
+declare global {
+  interface Window {
+    __PROBE_ORIG_REFRESH_MESSAGES?: any;
+    __PROBE_ORIG_REPLACE_MESSAGES?: any;
+  }
+}
+
+try {
+  const chat = w.__LOBE_STORES?.chat?.();
+  if (chat) {
+    // First-time install: cache the originals. Re-install: restore from
+    // the cached originals before wrapping again.
+    if (!w.__PROBE_ORIG_REFRESH_MESSAGES) w.__PROBE_ORIG_REFRESH_MESSAGES = chat.refreshMessages;
+    if (!w.__PROBE_ORIG_REPLACE_MESSAGES) w.__PROBE_ORIG_REPLACE_MESSAGES = chat.replaceMessages;
+    const origRefresh = w.__PROBE_ORIG_REFRESH_MESSAGES;
+    const origReplace = w.__PROBE_ORIG_REPLACE_MESSAGES;
+    chat.refreshMessages = origRefresh;
+    chat.replaceMessages = origReplace;
+
+    chat.refreshMessages = async function probeRefresh(this: unknown, ...args: any[]) {
+      calls.push({
+        t: now(),
+        name: 'refreshMessages',
+        args: { context: args[0] ?? null },
+        stack: shortStack(),
+      });
+      return origRefresh.apply(this, args);
+    };
+    chat.replaceMessages = function probeReplace(this: unknown, ...args: any[]) {
+      const msgs = (args[0] as any[]) ?? [];
+      const snapshot = msgs.slice(-2).map((m) => ({
+        id: (m.id ?? '').slice(-8),
+        role: m.role,
+        cLen: (m.content ?? '').length,
+        rLen: (m.reasoning?.content ?? '').length,
+        updatedAt: m.updatedAt,
+      }));
+      calls.push({
+        t: now(),
+        name: 'replaceMessages',
+        args: { count: msgs.length, params: args[1] ?? null, snapshot } as any,
+        stack: shortStack(),
+      });
+
+      // Pair the call with a mutation row so the analyzer can build a
+      // single ordered timeline across replaceMessages + dispatchMessage.
+      const stackTop = shortStack().split(' ← ')[0]?.slice(0, 80);
+      const last = msgs.at(-1);
+      const lastSum = last
+        ? {
+            id: (last.id ?? '').slice(-8),
+            role: last.role,
+            cLen: (last.content ?? '').length,
+            rLen: (last.reasoning?.content ?? '').length,
+            updatedAt: last.updatedAt,
+          }
+        : undefined;
+      const params: any = args[1] ?? {};
+      const ctxKey = params.context
+        ? `main_${params.context.agentId ?? '?'}_${
+            params.context.topicId ? 'tpc_' + params.context.topicId : 'new'
+          }`.replace('main_tpc_', 'main_') // crude key inference
+        : '(no-ctx)';
+      mutations.push({
+        t: now(),
+        key: ctxKey,
+        n: msgs.length,
+        last: lastSum,
+        delta: `replaceMessages(action=${params.action ?? '-'})  src=${stackTop ?? '-'}`,
+      });
+
+      return origReplace.apply(this, args);
+    };
+  }
+} catch (e: any) {
+  calls.push({ t: now(), name: '_WRAP_ERROR_', error: String(e?.message ?? e) });
+}
+
+// ── 3.5. Mutation log — wrap the TWO ChatStore writers (replaceMessages,
+// internal_dispatchMessage) to record EVERY dbMessagesMap[key] reference
+// change with a one-line "before/after last assistant message" delta. This
+// reveals dispatchMessage-driven collapses that the replaceMessages wrap
+// alone cannot see.
+
+declare global {
+  interface Window {
+    __PROBE_ORIG_DISPATCH_MESSAGE?: any;
+  }
+}
+
+try {
+  const chat = w.__LOBE_STORES?.chat?.();
+  if (chat?.internal_dispatchMessage) {
+    if (!w.__PROBE_ORIG_DISPATCH_MESSAGE)
+      w.__PROBE_ORIG_DISPATCH_MESSAGE = chat.internal_dispatchMessage;
+    const origDispatch = w.__PROBE_ORIG_DISPATCH_MESSAGE;
+    chat.internal_dispatchMessage = origDispatch;
+
+    chat.internal_dispatchMessage = function probeDispatch(this: unknown, payload: any, ctx?: any) {
+      // Snapshot BEFORE — read the would-be target key + last message.
+      const before = (() => {
+        try {
+          const state = w.__LOBE_STORES?.chat?.();
+          if (!state) return null;
+          // Replicate state.internal_getConversationContext logic enough to
+          // resolve a key — but most callers pass operationId on ctx, and
+          // operationId-keyed lookup needs store internals. Easiest: snapshot
+          // ALL keys' last-assistant cLen and compare BEFORE vs AFTER below.
+          const map = state.dbMessagesMap ?? {};
+          const out: Record<string, any> = {};
+          for (const k of Object.keys(map)) {
+            const last = (map[k] ?? []).at(-1);
+            out[k] = last
+              ? {
+                  id: (last.id ?? '').slice(-8),
+                  cLen: (last.content ?? '').length,
+                  rLen: (last.reasoning?.content ?? '').length,
+                  n: map[k].length,
+                }
+              : { n: 0 };
+          }
+          return out;
+        } catch {
+          return null;
+        }
+      })();
+
+      const result = origDispatch.apply(this, [payload, ctx]);
+
+      // Snapshot AFTER — find which key(s) actually changed.
+      try {
+        const state = w.__LOBE_STORES?.chat?.();
+        if (state && before) {
+          const map = state.dbMessagesMap ?? {};
+          for (const k of Object.keys(map)) {
+            const last = (map[k] ?? []).at(-1);
+            const beforeSnap = before[k];
+            const afterSnap = last
+              ? {
+                  id: (last.id ?? '').slice(-8),
+                  cLen: (last.content ?? '').length,
+                  rLen: (last.reasoning?.content ?? '').length,
+                  n: map[k].length,
+                }
+              : { n: 0 };
+            const changed =
+              !beforeSnap ||
+              beforeSnap.n !== afterSnap.n ||
+              beforeSnap.id !== (afterSnap as any).id ||
+              beforeSnap.cLen !== (afterSnap as any).cLen ||
+              beforeSnap.rLen !== (afterSnap as any).rLen;
+            if (!changed) continue;
+            let delta = '';
+            if (beforeSnap?.id !== undefined && beforeSnap.id !== (afterSnap as any).id)
+              delta += `id:${beforeSnap.id}→${(afterSnap as any).id};`;
+            if (
+              beforeSnap?.cLen !== undefined &&
+              (afterSnap as any).cLen !== undefined &&
+              (afterSnap as any).cLen < beforeSnap.cLen
+            )
+              delta += `cLen↓${beforeSnap.cLen}→${(afterSnap as any).cLen};`;
+            if (
+              beforeSnap?.rLen !== undefined &&
+              (afterSnap as any).rLen !== undefined &&
+              (afterSnap as any).rLen < beforeSnap.rLen
+            )
+              delta += `rLen↓${beforeSnap.rLen}→${(afterSnap as any).rLen};`;
+            if (beforeSnap?.n !== undefined && afterSnap.n < beforeSnap.n)
+              delta += `n↓${beforeSnap.n}→${afterSnap.n};`;
+            mutations.push({
+              t: now(),
+              key: k,
+              n: afterSnap.n,
+              last: (afterSnap as any).id ? (afterSnap as any) : undefined,
+              prevLast: beforeSnap?.id ? beforeSnap : undefined,
+              delta: delta || `dispatch:${payload?.type}`,
+            });
+          }
+        }
+      } catch (e: any) {
+        mutations.push({
+          t: now(),
+          key: '_DISPATCH_PROBE_ERROR_',
+          n: -1,
+          delta: String(e?.message ?? e),
+        });
+      }
+      return result;
+    };
+  }
+} catch (e: any) {
+  calls.push({ t: now(), name: '_DISPATCH_WRAP_ERROR_', error: String(e?.message ?? e) });
+}
+
+// ── 4. Periodic per-key timeline snapshots ─────────────────────────
+
+function captureTimeline(): void {
+  try {
+    const c = w.__LOBE_STORES?.chat?.();
+    if (!c) return;
+    const msgsMap = (c.messagesMap ?? {}) as Record<string, any[]>;
+    const dbMap = (c.dbMessagesMap ?? {}) as Record<string, any[]>;
+    const byKey: ProbeTimelineSample['byKey'] = {};
+    for (const k of Object.keys(msgsMap)) {
+      const display = msgsMap[k] ?? [];
+      const db = dbMap[k] ?? [];
+      if (display.length === 0 && db.length === 0) continue;
+      byKey[k] = {
+        n: display.length,
+        dbN: db.length,
+        msgs: summarizeMessages(display),
+      };
+    }
+    const ops = Object.values((c.operations ?? {}) as Record<string, any>);
+    timeline.push({
+      t: now(),
+      activeTopic: ((c.activeTopicId as string | null) ?? '').slice(-10) || null,
+      keys: Object.keys(byKey),
+      byKey,
+      runOps: ops.filter((o: any) => o.status === 'running').length,
+    });
+  } catch (e: any) {
+    timeline.push({
+      t: now(),
+      activeTopic: null,
+      keys: [],
+      byKey: {},
+      runOps: 0,
+      err: e?.message ?? String(e),
+    });
+  }
+}
+captureTimeline();
+if (w.__PROBE_TIMELINE_TIMER) clearInterval(w.__PROBE_TIMELINE_TIMER);
+w.__PROBE_TIMELINE_TIMER = setInterval(captureTimeline, 200);
+
+// ── 5. Tab-switch helpers ──────────────────────────────────────────
+
+function listTopBarTabs(): HTMLElement[] {
+  return Array.from(
+    document.querySelectorAll<HTMLElement>(
+      '[data-insp-path*="TabItem.tsx"][data-contextmenu-trigger]',
+    ),
+  ).filter((t) => t.getBoundingClientRect().top < 30);
+}
+
+w.__listTabs = () =>
+  listTopBarTabs().map((t, i) => ({
+    i,
+    key: t.getAttribute('data-contextmenu-trigger'),
+    active: t.getAttribute('data-active') === 'true',
+    title: (t.innerText ?? '').slice(0, 60),
+  }));
+
+w.__clickTabByKey = (key: string) => {
+  const tab = listTopBarTabs().find((t) => t.getAttribute('data-contextmenu-trigger') === key);
+  if (!tab) return 'not found: ' + key;
+  if (tab.getAttribute('data-active') === 'true') return 'already active: ' + key;
+  tab.click();
+  return 'clicked key=' + key;
+};
+
+w.__PROBE_EVENT = (name: string) => {
+  calls.push({ t: now(), name: 'MARK:' + name });
+};
+
+// `run.ts` wraps the bundle in an IIFE and appends a `return <confirmation>`
+// after the bundle body — agent-browser then prints the confirmation back to
+// the operator. Nothing to do here at the end of the module body.
@@ -0,0 +1,204 @@
+// LobeHub chat streaming time-series probe.
+//
+// Inject into the renderer (via agent-browser eval) to record store + DOM
+// snapshots every 200ms during a streaming session. Designed to surface
+// "UI rolled back to an earlier state" symptoms — especially around
+// gateway-mode tab switches that happen while the assistant is still writing.
+//
+// Usage:
+//   agent-browser --cdp 9222 eval --stdin < probe.js
+//   # ...do test interactions, call window.__PROBE_EVENT('LABEL') to mark moments...
+//   agent-browser --cdp 9222 eval --stdin < probe-dump.js > /tmp/probe.json
+//   node analyze.mjs /tmp/probe.json
+//
+// What it captures per sample:
+//   - activeTopicId
+//   - msgN: top-level messages in chat.messagesMap for this topic
+//   - childN: total assistantGroup.children blocks across all msgs (THIS is
+//     where streaming content actually lives — top-level assistantGroup stays empty)
+//   - cT / rT / toolT: totals across messages AND their children
+//                       (content, reasoning, tool-call count)
+//   - perMsg: per-message breakdown so regressions can be located precisely
+//   - runOps: number of running operations (execServerAgentRuntime etc.)
+//   - domLen: total innerText length of the rendered chat list area
+//   - ind: visible UI indicators (Search pages, Crawled pages, Deeply Thought, Sending)
+//
+// Event markers: window.__PROBE_EVENT('NAME') records {t, name} into
+// __PROBE_EVENTS, used by the analyzer to align state changes with
+// user-driven actions (SENT, AWAY_1, BACK_1, ...).
+
+(function () {
+  if (window.__PROBE_TIMER) clearInterval(window.__PROBE_TIMER);
+  window.__PROBE_SAMPLES = [];
+  window.__PROBE_EVENTS = [];
+  const t0 = Date.now();
+
+  function snapshot() {
+    try {
+      const chat = window.__LOBE_STORES.chat();
+      const topicId = chat.activeTopicId;
+      const idTail = topicId ? topicId.replace('tpc_', '') : null;
+      const keys = Object.keys(chat.messagesMap || {});
+
+      // Collect messages for the active topic. Before a topic is committed,
+      // optimistic messages live under the `<agentScope>_new` key — fall
+      // back to those when no topic is active yet.
+      let msgs = [];
+      if (idTail) {
+        keys.forEach((k) => {
+          if (k.includes(idTail)) msgs = msgs.concat(chat.messagesMap[k] || []);
+        });
+      } else {
+        keys
+          .filter((k) => k.endsWith('_new'))
+          .forEach((k) => {
+            msgs = msgs.concat(chat.messagesMap[k] || []);
+          });
+      }
+
+      // Walk top-level + assistantGroup.children. children carry the actual
+      // streamed content / reasoning / tool calls; the parent assistantGroup
+      // remains a placeholder (cLen=0, rLen=0) for its whole lifetime.
+      let totalContent = 0;
+      let totalReason = 0;
+      let totalTools = 0;
+      let childCount = 0;
+      const perMsg = msgs.map((m) => {
+        const cLen = (m.content || '').length;
+        const rLen = ((m.reasoning && m.reasoning.content) || '').length;
+        const tools = (m.tools || []).length;
+        totalContent += cLen;
+        totalReason += rLen;
+        totalTools += tools;
+
+        const children = m.children || [];
+        let chC = 0;
+        let chR = 0;
+        let chT = 0;
+        children.forEach((c) => {
+          chC += (c.content || '').length;
+          chR += ((c.reasoning && c.reasoning.content) || '').length;
+          chT += (c.tools || []).length;
+        });
+        totalContent += chC;
+        totalReason += chR;
+        totalTools += chT;
+        childCount += children.length;
+
+        return {
+          id: (m.id || '').slice(-8),
+          role: m.role,
+          cLen,
+          rLen,
+          tools,
+          chCount: children.length,
+          chC,
+          chR,
+          chT,
+        };
+      });
+
+      const ops = Object.values(chat.operations || {});
+      const runningOps = ops.filter((o) => o.status === 'running');
+
+      // DOM probe: total rendered text in the chat scroll area (proxy for
+      // "how much is actually visible to the user").
+      const convScroll =
+        document.querySelector(
+          '[data-chat-list], [class*="ChatList"], [class*="ConversationList"]',
+        ) ||
+        document.querySelector('main [class*="scroll"]') ||
+        document.querySelector('main');
+      const domTxt = convScroll ? convScroll.innerText || '' : '';
+
+      const bodyTxt = document.body.innerText || '';
+      const searchMatches = (bodyTxt.match(/Search pages?:|Searched the web/g) || []).length;
+      const crawlMatches = (bodyTxt.match(/Crawl(ed|ing) pages?/g) || []).length;
+
+      window.__PROBE_SAMPLES.push({
+        t: Date.now() - t0,
+        topicId,
+        msgN: msgs.length,
+        childN: childCount,
+        cT: totalContent,
+        rT: totalReason,
+        toolT: totalTools,
+        perMsg,
+        runOps: runningOps.length,
+        runOpTypes: runningOps.map((o) => o.type),
+        domLen: domTxt.length,
+        ind: {
+          search: searchMatches,
+          crawl: crawlMatches,
+          sending: bodyTxt.includes('Sending message'),
+          deeplyThinking: bodyTxt.includes('Deeply Thinking'),
+          deeplyThought: bodyTxt.includes('Deeply Thought'),
+        },
+      });
+    } catch (e) {
+      window.__PROBE_SAMPLES.push({ t: Date.now() - t0, err: e.message });
+    }
+  }
+
+  snapshot();
+  window.__PROBE_TIMER = setInterval(snapshot, 200);
+  window.__PROBE_EVENT = function (name) {
+    window.__PROBE_EVENTS.push({ t: Date.now() - t0, name });
+  };
+
+  // Tab-switch helpers installed alongside the probe.
+  //
+  // The Electron tab bar mounts each tab as a div with data-insp-path
+  // ending in `TabItem.tsx:...`. The active tab is marked with
+  // data-active="true". DO NOT search by innerText — the active tab's text
+  // includes a ` · <agent name>` suffix that produces false matches when
+  // your search string happens to overlap with the agent name.
+  function listTabs() {
+    return Array.from(
+      document.querySelectorAll('[data-insp-path*="TabItem.tsx"][data-contextmenu-trigger]'),
+    ).filter((t) => t.getBoundingClientRect().top < 30);
+  }
+  function tabKey(el) {
+    // Stable for the tab's lifetime; survives focus changes.
+    return el.getAttribute('data-contextmenu-trigger');
+  }
+  function findActiveTab() {
+    return listTabs().find((t) => t.getAttribute('data-active') === 'true') || null;
+  }
+
+  // Click by stable key captured earlier (preferred for round-trips).
+  window.__clickTabByKey = function (key) {
+    const tab = listTabs().find((t) => tabKey(t) === key);
+    if (!tab) return 'not found: key=' + key;
+    if (tab.getAttribute('data-active') === 'true') return 'already active: ' + key;
+    tab.click();
+    return 'clicked key=' + key;
+  };
+
+  // Click by index in the tab strip (0-based, left-to-right).
+  window.__clickTabByIndex = function (i) {
+    const tabs = listTabs();
+    if (i < 0 || i >= tabs.length) return 'index out of range: ' + i + '/' + tabs.length;
+    const t = tabs[i];
+    if (t.getAttribute('data-active') === 'true') return 'already active: i=' + i;
+    t.click();
+    return 'clicked i=' + i + ' key=' + tabKey(t);
+  };
+
+  // Snapshot all tabs in order: [{key, active, title (first 60 chars of innerText)}]
+  window.__listTabs = function () {
+    return listTabs().map((t, i) => ({
+      i,
+      key: tabKey(t),
+      active: t.getAttribute('data-active') === 'true',
+      title: (t.innerText || '').slice(0, 60),
+    }));
+  };
+
+  window.__activeTabKey = function () {
+    const a = findActiveTab();
+    return a ? tabKey(a) : null;
+  };
+
+  return 'probe installed';
+})();
@@ -0,0 +1,211 @@
+// CLI for the agent-gateway probe.
+//
+// Bundles the TS probes with esbuild, pipes them into `agent-browser eval`,
+// and persists dumps under `.agent-gateway/` (gitignored) for later use as
+// streaming-replay test fixtures.
+//
+// Commands:
+//   bun run .agents/skills/local-testing/scripts/agent-gateway/run.ts install
+//       Bundle probe-events.ts and inject into the CDP-attached browser.
+//       Re-installing clears all buffers and re-patches WebSocket / fetch.
+//
+//   bun run .agents/skills/local-testing/scripts/agent-gateway/run.ts dump [name]
+//       Stop the timeline timer, fetch the capture as JSON, write it to
+//       `.agent-gateway/<name>-<YYYYMMDD-HHmmss>.json`. `name` defaults to
+//       `dump`. Prints the absolute path written.
+//
+//   bun run .agents/skills/local-testing/scripts/agent-gateway/run.ts analyze [path]
+//       Run analyze-events.ts on the dump. `path` defaults to the most
+//       recently modified file in `.agent-gateway/`.
+//
+// Optional flags:
+//   --cdp <port>     CDP port (default 9222)
+//   --browser <bin>  agent-browser binary (default 'agent-browser')
+
+import { spawn } from 'node:child_process';
+import { mkdirSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+// .agents/skills/local-testing/scripts/agent-gateway/ → 5 levels up
+const PROJECT_ROOT = path.resolve(SCRIPT_DIR, '../../../../..');
+const DUMP_DIR = path.join(PROJECT_ROOT, '.agent-gateway');
+
+interface Flags {
+  browser: string;
+  cdp: string;
+  positional: string[];
+}
+
+function parseFlags(argv: string[]): Flags {
+  const out: Flags = { cdp: '9222', browser: 'agent-browser', positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--cdp') out.cdp = argv[++i] ?? out.cdp;
+    else if (a === '--browser') out.browser = argv[++i] ?? out.browser;
+    else out.positional.push(a);
+  }
+  return out;
+}
+
+async function bundle(entry: string): Promise<string> {
+  // Bun.build is built into the Bun runtime — no external dep needed.
+  const r = await Bun.build({
+    entrypoints: [path.join(SCRIPT_DIR, entry)],
+    target: 'browser',
+    format: 'esm',
+    minify: false,
+  });
+  if (!r.success) {
+    const msgs = r.logs.map((l) => `${l.level}: ${l.message}`).join('\n');
+    throw new Error(`bundle failed for ${entry}:\n${msgs}`);
+  }
+  return await r.outputs[0].text();
+}
+
+function wrapIife(body: string, returnExpr: string): string {
+  // Wrap as an IIFE that swallows the bundled top-level (top-level `const`
+  // declarations get scoped to the IIFE, so re-injection doesn't conflict)
+  // and returns the configured expression — which `agent-browser eval`
+  // captures and prints to stdout.
+  return `(() => {\n${body}\n;return ${returnExpr};\n})()`;
+}
+
+function runAgentBrowserEval(flags: Flags, script: string): Promise<string> {
+  return new Promise((resolveP, rejectP) => {
+    const child = spawn(flags.browser, ['--cdp', flags.cdp, 'eval', '--stdin'], {
+      stdio: ['pipe', 'pipe', 'inherit'],
+    });
+    let stdout = '';
+    child.stdout.on('data', (chunk: Buffer) => {
+      stdout += chunk.toString('utf8');
+    });
+    child.on('error', rejectP);
+    child.on('close', (code) => {
+      if (code === 0) resolveP(stdout);
+      else rejectP(new Error(`agent-browser exited ${code}`));
+    });
+    child.stdin.write(script);
+    child.stdin.end();
+  });
+}
+
+// agent-browser prints eval results as JSON (string values are quoted).
+function unquoteAgentBrowserResult(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) {
+    try {
+      return JSON.parse(trimmed) as string;
+    } catch {
+      /* fall through */
+    }
+  }
+  return trimmed;
+}
+
+function isoStamp(): string {
+  const d = new Date();
+  const yyyy = d.getFullYear();
+  const mm = String(d.getMonth() + 1).padStart(2, '0');
+  const dd = String(d.getDate()).padStart(2, '0');
+  const hh = String(d.getHours()).padStart(2, '0');
+  const mi = String(d.getMinutes()).padStart(2, '0');
+  const ss = String(d.getSeconds()).padStart(2, '0');
+  return `${yyyy}${mm}${dd}-${hh}${mi}${ss}`;
+}
+
+function ensureDumpDir(): void {
+  mkdirSync(DUMP_DIR, { recursive: true });
+}
+
+function latestDump(): string | null {
+  ensureDumpDir();
+  const entries = readdirSync(DUMP_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => ({ f, mtime: statSync(path.join(DUMP_DIR, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime);
+  return entries[0] ? path.join(DUMP_DIR, entries[0].f) : null;
+}
+
+// ── Commands ────────────────────────────────────────────────────────
+
+async function cmdInstall(flags: Flags): Promise<void> {
+  const body = await bundle('probe-events.ts');
+  const installMsg = JSON.stringify(
+    'events probe installed: WebSocket+fetch interception. ' +
+      'WS captures operationId= sockets (gateway), fetch captures /api/agent/stream (direct).',
+  );
+  const script = wrapIife(body, installMsg);
+  const out = await runAgentBrowserEval(flags, script);
+  console.log(unquoteAgentBrowserResult(out));
+}
+
+async function cmdDump(flags: Flags): Promise<void> {
+  const name = flags.positional[1] ?? 'dump';
+  const body = await bundle('probe-dump.ts');
+  const script = wrapIife(body, 'window.__PROBE_LAST_DUMP_JSON');
+  const raw = await runAgentBrowserEval(flags, script);
+  const json = unquoteAgentBrowserResult(raw);
+  ensureDumpDir();
+  const filename = `${name}-${isoStamp()}.json`;
+  const dumpPath = path.join(DUMP_DIR, filename);
+  writeFileSync(dumpPath, json, 'utf8');
+  // Validate by parsing the meta header so we error early on bad capture
+  try {
+    const parsed = JSON.parse(json) as {
+      meta?: { eventCount?: number; callCount?: number; sampleCount?: number };
+    };
+    const meta = parsed.meta ?? {};
+    console.log(
+      `wrote ${dumpPath}  (${json.length} bytes  events=${meta.eventCount ?? '?'}  ` +
+        `calls=${meta.callCount ?? '?'}  samples=${meta.sampleCount ?? '?'})`,
+    );
+  } catch {
+    console.log(`wrote ${dumpPath}  (${json.length} bytes — JSON.parse failed; see file)`);
+  }
+}
+
+async function cmdAnalyze(flags: Flags): Promise<void> {
+  const target = flags.positional[1] ?? latestDump();
+  if (!target) {
+    console.error('no dump file found. run `dump` first or pass a path.');
+    process.exit(1);
+  }
+  const child = spawn('bun', ['run', path.join(SCRIPT_DIR, 'analyze-events.ts'), target], {
+    stdio: 'inherit',
+  });
+  await new Promise<void>((resolveP, rejectP) => {
+    child.on('error', rejectP);
+    child.on('close', (code) => (code === 0 ? resolveP() : rejectP(new Error(`exit ${code}`))));
+  });
+}
+
+// ── Entry point ─────────────────────────────────────────────────────
+
+const flags = parseFlags(process.argv.slice(2));
+const cmd = flags.positional[0];
+
+const usage = `usage:
+  bun run run.ts install [--cdp 9222]
+  bun run run.ts dump [name] [--cdp 9222]
+  bun run run.ts analyze [path]
+`;
+
+if (!cmd) {
+  console.error(usage);
+  process.exit(1);
+}
+
+try {
+  if (cmd === 'install') await cmdInstall(flags);
+  else if (cmd === 'dump') await cmdDump(flags);
+  else if (cmd === 'analyze') await cmdAnalyze(flags);
+  else {
+    console.error(`unknown command: ${cmd}\n\n${usage}`);
+    process.exit(1);
+  }
+} catch (e: any) {
+  console.error(e?.stack ?? e);
+  process.exit(1);
+}
@@ -0,0 +1,72 @@
+// Run N round-trip tab switches with event markers timed against the probe.
+//
+//   agent-browser --cdp 9222 eval --stdin < tab-switch.js
+//
+// Captures the currently-active tab as the BACK target and the rightmost
+// inactive tab as the AWAY target. Both are addressed by their stable
+// data-contextmenu-trigger key (NOT by visible title — the active tab's
+// innerText embeds a ` · <agent name>` suffix that breaks text matching).
+//
+// Fires the loop in the background and returns immediately so the
+// agent-browser eval doesn't have to await the full ROUND_TRIPS × DWELL_MS
+// duration. Wait on the `SWITCH_LOOP_DONE` event before dumping.
+//
+// Refuses to launch if a previous loop is still in flight.
+//
+// Requires probe.js to have been installed first (provides
+// window.__PROBE_EVENT / __listTabs / __clickTabByKey / __activeTabKey).
+
+(function () {
+  const ROUND_TRIPS = 4;
+  const DWELL_MS = 10_000;
+
+  if (!window.__PROBE_EVENT || !window.__listTabs || !window.__clickTabByKey) {
+    return 'probe not installed — eval probe.js first';
+  }
+  if (window.__SWITCH_LOOP_RUNNING) {
+    return 'switch loop already running — wait for SWITCH_LOOP_DONE first';
+  }
+
+  const tabs = window.__listTabs();
+  const activeTab = tabs.find((t) => t.active);
+  if (!activeTab) return 'no active tab — abort';
+
+  // Pick the first inactive tab as AWAY target. With multiple inactive tabs
+  // you'll usually want the one that's stable across the test — feel free
+  // to swap to tabs[tabs.length-1] if you want the rightmost.
+  const inactives = tabs.filter((t) => !t.active);
+  if (inactives.length === 0) return 'no inactive tab to switch to — abort';
+  const awayTab = inactives.at(-1); // rightmost inactive
+
+  const BACK_KEY = activeTab.key;
+  const AWAY_KEY = awayTab.key;
+
+  window.__SWITCH_LOOP_RUNNING = true;
+  window.__PROBE_EVENT('SWITCH_LOOP_CONFIG:back=' + BACK_KEY + ',away=' + AWAY_KEY);
+
+  (async function () {
+    function sleep(ms) {
+      return new Promise((r) => setTimeout(r, ms));
+    }
+
+    try {
+      window.__PROBE_EVENT('SWITCH_LOOP_START');
+      for (let i = 1; i <= ROUND_TRIPS; i++) {
+        window.__PROBE_EVENT('AWAY_' + i);
+        const awayResult = window.__clickTabByKey(AWAY_KEY);
+        window.__PROBE_EVENT('AWAY_' + i + '_RES:' + awayResult.slice(0, 50));
+        await sleep(DWELL_MS);
+
+        window.__PROBE_EVENT('BACK_' + i);
+        const backResult = window.__clickTabByKey(BACK_KEY);
+        window.__PROBE_EVENT('BACK_' + i + '_RES:' + backResult.slice(0, 50));
+        await sleep(DWELL_MS);
+      }
+      window.__PROBE_EVENT('SWITCH_LOOP_DONE');
+    } finally {
+      window.__SWITCH_LOOP_RUNNING = false;
+    }
+  })();
+
+  return 'switch loop kicked off (BACK=' + BACK_KEY + ', AWAY=' + AWAY_KEY + ')';
+})();
@@ -0,0 +1,113 @@
+// Shared types between the in-browser probe and the Node-side analyzer.
+// Kept tiny on purpose — anything the analyzer can re-derive is left off.
+
+export interface ProbeStreamEvent {
+  /** Summarized payload — long strings truncated, arrays printed as Array(N) */
+  data?: Record<string, unknown>;
+  /** Keys present on the event's `data` payload — useful at a glance */
+  dataKeys?: string[];
+  /** ServerMessage.id — gateway WS frames carry an event-id we may resume from */
+  eventId?: string | null;
+  message?: string;
+  /** Last 10 chars of the operationId (full id is excessively long) */
+  opIdTail: string;
+  raw?: string;
+  /** Raw frame byte length, when applicable */
+  rawLen?: number;
+  /** For non-agent_event server frames (auth_success, heartbeat_ack, …) */
+  serverType?: string;
+  sseEvent?: string;
+  status?: number;
+  stepIndex?: number;
+  /** Milliseconds since the probe's t0 (install time). */
+  t: number;
+  /** 'ws' for gateway WebSocket frames, 'sse' for direct /api/agent/stream */
+  transport: 'ws' | 'sse';
+  /** Either the AgentStreamEvent.type, or a probe sentinel like `_WS_OPEN_` */
+  type: string;
+  url?: string;
+}
+
+export interface ProbeActionCall {
+  args?: {
+    count?: number;
+    context?: unknown;
+    params?: unknown;
+  };
+  error?: string;
+  /** `replaceMessages` / `refreshMessages` / `MARK:<label>` / `_WRAP_ERROR_` */
+  name: string;
+  stack?: string;
+  t: number;
+}
+
+export interface ProbeMessageSummary {
+  /** children.length */
+  chN: number;
+  /** content.length */
+  cLen: number;
+  /** Last 8 chars of the message id */
+  id: string;
+  /** reasoning.content.length */
+  rLen: number;
+  role: string;
+  /** tools.length */
+  tools: number;
+}
+
+export interface ProbeTimelineSample {
+  /** Last 10 chars of activeTopicId, or null */
+  activeTopic: string | null;
+  /** Per-key breakdown: display count, db count, message summaries */
+  byKey: Record<
+    string,
+    {
+      n: number;
+      dbN: number;
+      msgs: ProbeMessageSummary[];
+    }
+  >;
+  err?: string;
+  /** All messagesMap keys that have content at this moment */
+  keys: string[];
+  /** Number of operations in 'running' status */
+  runOps: number;
+  t: number;
+}
+
+export interface ProbeDumpMeta {
+  callCount: number;
+  /** Date.now() at dump call */
+  collectedAt: number;
+  eventCount: number;
+  sampleCount: number;
+  /** Date.now() at probe install */
+  t0: number;
+}
+
+export interface ProbeDump {
+  actionCalls: ProbeActionCall[];
+  meta: ProbeDumpMeta;
+  streamEvents: ProbeStreamEvent[];
+  timeline: ProbeTimelineSample[];
+}
+
+/**
+ * Globals the probe attaches to `window`. Keeps `as any` casts at the boundary
+ * instead of sprinkling them through the probe body.
+ */
+declare global {
+  interface Window {
+    __clickTabByKey?: (key: string) => string;
+    __listTabs?: () => Array<{ i: number; key: string | null; active: boolean; title: string }>;
+    __LOBE_STORES?: Record<string, () => any>;
+    __PROBE_ACTION_CALLS?: ProbeActionCall[];
+    __PROBE_EVENT?: (label: string) => void;
+    __PROBE_MSG_TIMELINE?: ProbeTimelineSample[];
+    __PROBE_ORIG_FETCH?: typeof fetch;
+    __PROBE_ORIG_WEBSOCKET?: typeof WebSocket;
+    __PROBE_STREAM_EVENTS?: ProbeStreamEvent[];
+    __PROBE_T0?: number;
+    __PROBE_TIMELINE_TIMER?: ReturnType<typeof setInterval> | null;
+  }
+}
@@ -11,86 +11,169 @@
 # 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)
+#   ELECTRON_WAIT_S   — Max seconds to wait for CDP to become reachable (default: 90)
+#   RENDERER_WAIT_S   — Max seconds to wait for SPA after CDP is up (default: 60)
+#   FORCE_KILL_USER   — When set to 1, silently kill the user's `bun run dev`
+#                       Electron without confirmation (default: always confirm-by-action)
 #
 set -euo pipefail

 CDP_PORT="${CDP_PORT:-9222}"
 ELECTRON_LOG="${ELECTRON_LOG:-/tmp/electron-dev.log}"
-ELECTRON_WAIT_S="${ELECTRON_WAIT_S:-60}"
+ELECTRON_WAIT_S="${ELECTRON_WAIT_S:-90}"
 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"

+# Project-scoped electron path prefix used for pgrep matching. Any Electron
+# binary from this project (main + helpers, with or without --remote-debugging-port)
+# starts with this string in its argv[0], so a single substring match catches all.
+PROJECT_ELECTRON_PATH="${PROJECT_ROOT}/apps/desktop/node_modules/.pnpm/electron@"
+
 # ── 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"
+# Print pid + every descendant pid (DFS via pgrep -P).
+expand_descendants() {
+  local pid="$1"
+  echo "$pid"
+  local children
+  children=$(pgrep -P "$pid" 2>/dev/null || true)
+  for c in $children; do
+    expand_descendants "$c"
+  done
 }

-# Find all PIDs related to the project's Electron dev session
-find_electron_pids() {
+# Find seed PIDs related to this project's Electron dev session.
+# Matches REGARDLESS of whether --remote-debugging-port was passed, so it also
+# catches a plain `bun run dev` session the user started outside this script.
+find_project_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"
+  # 1. Any process whose command line mentions this project's electron path
+  #    (covers the main Electron binary AND every Helper subprocess)
+  local electron_pids
+  electron_pids=$(pgrep -f "$PROJECT_ELECTRON_PATH" 2>/dev/null || true)
+  pids="$pids $electron_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
+  # 2. electron-vite dev server (narrow match to avoid catching unrelated Vite invocations)
  local vite_pids
-  vite_pids=$(pgrep -f "electron-vite.*dev" 2>/dev/null || true)
-  [ -n "$vite_pids" ] && pids="$pids $vite_pids"
+  vite_pids=$(pgrep -f "electron-vite[/.].*\\bdev\\b" 2>/dev/null || true)
+  pids="$pids $vite_pids"

-  # 4. PID from pidfile (fallback)
+  # 3. The launcher subshell from a previous `start` (saved to pidfile)
  if [ -f "$PIDFILE" ]; then
    local saved_pid
-    saved_pid=$(cat "$PIDFILE")
-    if kill -0 "$saved_pid" 2>/dev/null; then
+    saved_pid=$(cat "$PIDFILE" 2>/dev/null || true)
+    if [ -n "$saved_pid" ] && kill -0 "$saved_pid" 2>/dev/null; then
      pids="$pids $saved_pid"
    fi
  fi

-  # Deduplicate
+  # 4. Whatever is currently bound to the CDP port — catches strays whose
+  #    binary path doesn't match (e.g. orphaned from a crashed restart)
+  local port_pid
+  port_pid=$(lsof -ti tcp:"$CDP_PORT" -sTCP:LISTEN 2>/dev/null || true)
+  pids="$pids $port_pid"
+
+  # `|| true` because `grep -v '^$'` exits 1 when input has no non-empty
+  # lines, which (with pipefail + set -e) silently kills the caller.
  echo "$pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ' || true
 }

+# Wait for the CDP HTTP endpoint to respond, with a deadline + early bail-out
+# if the launcher process died (no point waiting if Electron crashed).
+wait_for_cdp() {
+  local deadline=$(( $(date +%s) + ELECTRON_WAIT_S ))
+  echo "[electron-dev] Waiting for CDP on port ${CDP_PORT} (up to ${ELECTRON_WAIT_S}s)..."
+
+  while [ "$(date +%s)" -lt "$deadline" ]; do
+    if curl -sf --max-time 2 "http://localhost:${CDP_PORT}/json/version" >/dev/null 2>&1; then
+      echo "[electron-dev] CDP is reachable."
+      return 0
+    fi
+
+    # If our launcher subshell died, abort early so we don't hang the full timeout
+    if [ -f "$PIDFILE" ]; then
+      local saved_pid
+      saved_pid=$(cat "$PIDFILE" 2>/dev/null || true)
+      if [ -n "$saved_pid" ] && ! kill -0 "$saved_pid" 2>/dev/null; then
+        echo "[electron-dev] Launcher PID $saved_pid is gone before CDP came up."
+        echo "[electron-dev] Last 30 lines of $ELECTRON_LOG:"
+        tail -30 "$ELECTRON_LOG" 2>/dev/null || true
+        return 1
+      fi
+    fi
+
+    sleep 2
+  done
+
+  echo "[electron-dev] ERROR: CDP did not respond within ${ELECTRON_WAIT_S}s"
+  echo "[electron-dev] Last 30 lines of $ELECTRON_LOG:"
+  tail -30 "$ELECTRON_LOG" 2>/dev/null || true
+  return 1
+}
+
+# After CDP is up, wait until the SPA renders interactive elements.
+wait_for_renderer() {
+  local deadline=$(( $(date +%s) + RENDERER_WAIT_S ))
+  echo "[electron-dev] Waiting for SPA to load (up to ${RENDERER_WAIT_S}s)..."
+
+  while [ "$(date +%s)" -lt "$deadline" ]; do
+    local snap
+    snap=$(agent-browser --cdp "$CDP_PORT" snapshot -i 2>&1 || true)
+    if echo "$snap" | grep -qE '\b(link|button)\b'; then
+      echo "[electron-dev] Renderer ready."
+      return 0
+    fi
+    sleep 2
+  done
+
+  echo "[electron-dev] WARNING: Renderer not interactive within ${RENDERER_WAIT_S}s — proceeding anyway."
+  return 0
+}
+
+# ── Commands ─────────────────────────────────────────────────────────
+
 do_stop() {
  echo "[electron-dev] Stopping Electron dev environment..."

-  local pids
-  pids=$(find_electron_pids)
+  local seed_pids
+  seed_pids=$(find_project_pids)

-  if [ -z "$pids" ]; then
-    echo "[electron-dev] No Electron processes found."
+  # Expand to include all descendants — catches helpers spawned by the main
+  # process AFTER our pgrep snapshot, and the launcher's child node/electron-vite
+  # process tree.
+  local all_pids=""
+  for pid in $seed_pids; do
+    all_pids="$all_pids $(expand_descendants "$pid")"
+  done
+  all_pids=$(echo "$all_pids" | tr ' ' '\n' | sort -u | grep -v '^$' | tr '\n' ' ' || true)
+
+  if [ -z "$all_pids" ]; then
+    echo "[electron-dev] No project Electron/vite processes found."
  else
-    echo "[electron-dev] Killing PIDs: $pids"
-    for pid in $pids; do
+    local count
+    count=$(echo "$all_pids" | tr ' ' '\n' | grep -c .)
+    echo "[electron-dev] Sending SIGTERM to $count process(es): $all_pids"
+    for pid in $all_pids; do
      kill "$pid" 2>/dev/null || true
    done

-    # Wait up to 5s for graceful exit, then force-kill survivors
+    # Wait up to 5s for graceful exit
    local waited=0
    while [ $waited -lt 5 ]; do
-      local alive=""
-      for pid in $pids; do
-        kill -0 "$pid" 2>/dev/null && alive="$alive $pid"
+      local any_alive=0
+      for pid in $all_pids; do
+        if kill -0 "$pid" 2>/dev/null; then any_alive=1; break; fi
      done
-      [ -z "$alive" ] && break
+      [ "$any_alive" = "0" ] && break
      sleep 1
      waited=$((waited + 1))
    done

-    # Force-kill any remaining
-    for pid in $pids; do
+    # SIGKILL anyone still alive
+    for pid in $all_pids; do
      if kill -0 "$pid" 2>/dev/null; then
        echo "[electron-dev] Force-killing PID $pid"
        kill -9 "$pid" 2>/dev/null || true
@@ -98,7 +181,27 @@ do_stop() {
    done
  fi

-  # Also close any agent-browser sessions connected to this port
+  # Belt-and-suspenders: anything still bound to the CDP port goes away
+  local port_pid
+  port_pid=$(lsof -ti tcp:"$CDP_PORT" -sTCP:LISTEN 2>/dev/null || true)
+  if [ -n "$port_pid" ]; then
+    echo "[electron-dev] Port $CDP_PORT still bound by PID $port_pid; force-killing"
+    # shellcheck disable=SC2086
+    kill -9 $port_pid 2>/dev/null || true
+  fi
+
+  # Also re-sweep the project's electron processes — sometimes the OS spawns
+  # new helpers during shutdown that didn't exist when we first enumerated.
+  local stragglers
+  stragglers=$(pgrep -f "$PROJECT_ELECTRON_PATH" 2>/dev/null || true)
+  if [ -n "$stragglers" ]; then
+    echo "[electron-dev] Cleaning up stragglers: $stragglers"
+    for pid in $stragglers; do
+      kill -9 "$pid" 2>/dev/null || true
+    done
+  fi
+
+  # Close any agent-browser sessions connected to this port
  agent-browser --cdp "$CDP_PORT" close --all 2>/dev/null || true

  rm -f "$PIDFILE"
@@ -107,113 +210,91 @@ do_stop() {

 do_status() {
  local pids
-  pids=$(find_electron_pids)
+  pids=$(find_project_pids)

  if [ -z "$pids" ]; then
-    echo "[electron-dev] Electron is NOT running."
+    echo "[electron-dev] No project Electron processes found."
    return 1
  fi

-  echo "[electron-dev] Electron is running (PIDs: $pids)"
+  echo "[electron-dev] Project processes: $pids"

-  # Check CDP connectivity
-  if agent-browser --cdp "$CDP_PORT" get url >/dev/null 2>&1; then
+  if curl -sf --max-time 2 "http://localhost:${CDP_PORT}/json/version" >/dev/null 2>&1; then
    local url
-    url=$(agent-browser --cdp "$CDP_PORT" get url 2>&1 | tail -1)
+    url=$(agent-browser --cdp "$CDP_PORT" get url 2>&1 | tail -1 || echo "?")
    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)."
+    echo "[electron-dev] CDP port ${CDP_PORT} is NOT reachable (no --remote-debugging-port, or still 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."
+  # Already up and CDP is reachable → nothing to do
+  if curl -sf --max-time 2 "http://localhost:${CDP_PORT}/json/version" >/dev/null 2>&1; then
+    echo "[electron-dev] CDP already reachable on port $CDP_PORT. Skipping start."
+    echo "[electron-dev] Use 'restart' to force a fresh session."
    return 0
  fi

-  # Clean up any stale processes
+  # Detect the user's existing dev session (or stale processes) BEFORE killing
+  local existing
+  existing=$(find_project_pids)
+  if [ -n "$existing" ]; then
+    echo "[electron-dev] Existing project Electron/vite processes detected:"
+    echo "$existing" | tr ' ' '\n' | sed 's/^/[electron-dev]   PID /'
+    echo "[electron-dev] Tearing them down so we can start a CDP-enabled session..."
+  fi
+
  do_stop

-  # Start fresh
+  # Wait for port + user-data-dir locks to release. Without this, the new
+  # Electron may fail with "user data directory in use" or fail to bind CDP.
+  local waited=0
+  while [ $waited -lt 10 ]; do
+    if ! lsof -i tcp:"$CDP_PORT" >/dev/null 2>&1 \
+       && ! pgrep -f "$PROJECT_ELECTRON_PATH" >/dev/null 2>&1; then
+      break
+    fi
+    [ $waited -eq 0 ] && echo "[electron-dev] Waiting for port + Electron locks to release..."
+    sleep 1
+    waited=$((waited + 1))
+  done
+
  echo "[electron-dev] Starting Electron dev server..."
-  echo "[electron-dev]   Project: $PROJECT_ROOT"
+  echo "[electron-dev]   Project:  $PROJECT_ROOT"
  echo "[electron-dev]   CDP port: $CDP_PORT"
-  echo "[electron-dev]   Log: $ELECTRON_LOG"
+  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"
+  # Launch in a new session (setsid) so the whole process tree shares a PGID
+  # we can later signal in one shot. `setsid bash -c '... exec ...' &` keeps
+  # the bash shell as the session leader; its PID is what we save.
+  # macOS doesn't ship setsid by default — fall back to plain bash; cleanup
+  # still works via `expand_descendants` walking the process tree.
+  local launch_cmd="
+    cd '$PROJECT_ROOT/apps/desktop'
+    exec npx electron-vite dev -- --remote-debugging-port=$CDP_PORT
+  "
+  if command -v setsid >/dev/null 2>&1; then
+    setsid bash -c "$launch_cmd" >> "$ELECTRON_LOG" 2>&1 < /dev/null &
+  else
+    bash -c "$launch_cmd" >> "$ELECTRON_LOG" 2>&1 < /dev/null &
+  fi
+  local launcher_pid=$!
+  echo "$launcher_pid" > "$PIDFILE"
+  echo "[electron-dev] Launcher PID (session leader): $launcher_pid"

-  # Wait for Electron process to start
-  if ! wait_for_electron; then
-    echo "[electron-dev] Failed to start. Cleaning up..."
+  if ! wait_for_cdp; then
+    echo "[electron-dev] Failed to bring up CDP. 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."
+    echo "[electron-dev] Renderer not interactive — you may need to wait more."
  fi

  echo "[electron-dev] Ready! Use: agent-browser --cdp $CDP_PORT snapshot -i"
@@ -221,7 +302,7 @@ do_start() {

 do_restart() {
  do_stop
-  sleep 2
+  sleep 1
  do_start
 }

@@ -235,10 +316,12 @@ case "${1:-help}" in
  *)
    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"
+    echo "  start   — Start Electron dev with CDP. Detects + tears down any"
+    echo "            existing project Electron (e.g. \`bun run dev\`) first."
+    echo "  stop    — Kill all project Electron/vite processes (main + helpers"
+    echo "            + descendants), with SIGTERM → 5s wait → SIGKILL fallback."
+    echo "  status  — Check if Electron is running and CDP is reachable."
+    echo "  restart — Stop then start."
    exit 1
    ;;
 esac
@@ -1,10 +1,16 @@
 ---
 name: microcopy
 description: UI copy and microcopy guidelines. Use when writing UI text, buttons, error messages, empty states, onboarding, or any user-facing copy. Triggers on i18n translation, UI text writing, or copy improvement tasks. Supports both Chinese and English.
+user-invocable: false
 ---

 # LobeHub UI Microcopy Guidelines

+This file is the quick-reference summary. For full prompt-style guidelines with extensive examples (anti-patterns, tone matrices, scenario walk-throughs), load the language-specific reference:
+
+- **中文文案** — [`references/zh.md`](./references/zh.md)
+- **English copy** — [`references/en.md`](./references/en.md)
+
 Brand: **Where Agents Collaborate** - Focus on collaborative agent system, not just "generation".

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

@@ -1,10 +1,15 @@
 ---
 name: project-overview
 description: Complete project architecture and structure guide. Use when exploring the codebase, understanding project organization, finding files, or needing comprehensive architectural context. Triggers on architecture questions, directory navigation, or project overview needs.
+user-invocable: false
 ---

 # LobeHub Project Overview

+> The directory listings below are a **curated map of key locations**, not an
+> exhaustive tree. `packages/`, `src/store/`, route groups etc. grow over time —
+> run `ls` against the real directory for the current set.
+
 ## Project Description

 Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat).
@@ -13,7 +18,7 @@ Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat)

 - Web desktop/mobile
 - Desktop (Electron)
- Mobile app (React Native) - coming soon
+- Mobile app (React Native) — **separate repo, already launched** (not in this monorepo)

 **Logo emoji:** 🤯

@@ -38,147 +43,92 @@ Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat)
 | Database      | Neon PostgreSQL + Drizzle ORM              |
 | Testing       | Vitest                                     |

-## Complete Project Structure
+> Exact versions live in the root `package.json` — check there, not here.

-Monorepo using `@lobechat/` namespace for workspace packages.
+## Monorepo Layout
+
+This is a monorepo extending the open-source `lobehub` submodule. Two repos:
+
+- **cloud repo root** — `src/` and `packages/business/` (`config`, `const`, `model-runtime`) hold cloud-only SaaS code that overrides/extends the submodule. See `AGENTS.md` for the override mechanism.
+- **`lobehub/` submodule** — the open-source product core.
+
+### `lobehub/` submodule — key directories

 ```
 lobehub/
 ├── apps/
-│   └── desktop/                 # Electron desktop app
-├── docs/
-│   ├── changelog/
-│   ├── development/
-│   ├── self-hosting/
-│   └── usage/
-├── locales/
-│   ├── en-US/
-│   └── zh-CN/
-├── packages/
-│   ├── agent-runtime/           # Agent runtime
-│   ├── builtin-agents/
-│   ├── builtin-tool-*/          # Builtin tool packages
-│   ├── business/                # Cloud-only business logic
-│   │   ├── config/
-│   │   ├── const/
-│   │   └── model-runtime/
-│   ├── config/
-│   ├── const/
+│   ├── cli/                 # LobeHub CLI
+│   ├── desktop/             # Electron desktop app
+│   └── device-gateway/      # Device gateway service
+├── docs/                    # changelog, development, self-hosting, usage
+├── locales/                 # en-US, zh-CN, ...
+├── packages/                # ~80 @lobechat/* workspace packages — `ls` for the full set. Key ones:
+│   ├── agent-runtime/        # Agent runtime
+│   ├── agent-signal/         # Agent Signal pipeline
+│   ├── builtin-tool-*/       # Builtin tool packages
+│   ├── builtin-tools/        # Builtin tool registries
 │   ├── context-engine/
-│   ├── conversation-flow/
-│   ├── database/
-│   │   └── src/
-│   │       ├── models/
-│   │       ├── schemas/
-│   │       └── repositories/
-│   ├── desktop-bridge/
-│   ├── edge-config/
-│   ├── editor-runtime/
-│   ├── electron-client-ipc/
-│   ├── electron-server-ipc/
-│   ├── fetch-sse/
-│   ├── file-loaders/
-│   ├── memory-user-memory/
-│   ├── model-bank/
-│   ├── model-runtime/
-│   │   └── src/
-│   │       ├── core/
-│   │       └── providers/
-│   ├── observability-otel/
-│   ├── prompts/
-│   ├── python-interpreter/
-│   ├── ssrf-safe-fetch/
-│   ├── types/
-│   ├── utils/
-│   └── web-crawler/
-├── src/
-│   ├── app/
-│   │   ├── (backend)/
-│   │   │   ├── api/
-│   │   │   ├── f/
-│   │   │   ├── market/
-│   │   │   ├── middleware/
-│   │   │   ├── oidc/
-│   │   │   ├── trpc/
-│   │   │   └── webapi/
-│   │   ├── spa/                  # SPA HTML template service
-│   │   └── [variants]/
-│   │       └── (auth)/           # Auth pages (SSR required)
-│   ├── routes/                  # SPA page components (Vite)
-│   │   ├── (main)/
-│   │   ├── (mobile)/
-│   │   ├── (desktop)/
-│   │   ├── onboarding/
-│   │   └── share/
-│   ├── spa/                     # SPA entry points and router config
-│   │   ├── entry.web.tsx
-│   │   ├── entry.mobile.tsx
-│   │   ├── entry.desktop.tsx
-│   │   └── router/
-│   ├── business/                # Cloud-only (client/server)
-│   │   ├── client/
-│   │   ├── locales/
-│   │   └── server/
-│   ├── components/
-│   ├── config/
-│   ├── const/
-│   ├── envs/
-│   ├── features/
-│   ├── helpers/
-│   ├── hooks/
-│   ├── layout/
-│   │   ├── AuthProvider/
-│   │   └── GlobalProvider/
-│   ├── libs/
-│   │   ├── better-auth/
-│   │   ├── oidc-provider/
-│   │   └── trpc/
-│   ├── locales/
-│   │   └── default/
-│   ├── server/
-│   │   ├── featureFlags/
-│   │   ├── globalConfig/
-│   │   ├── modules/
-│   │   ├── routers/
-│   │   │   ├── async/
-│   │   │   ├── lambda/
-│   │   │   ├── mobile/
-│   │   │   └── tools/
-│   │   └── services/
-│   ├── services/
-│   ├── store/
-│   │   ├── agent/
-│   │   ├── chat/
-│   │   └── user/
-│   ├── styles/
-│   ├── tools/
+│   ├── database/             # src/{models,schemas,repositories}
+│   ├── model-bank/           # Model definitions & provider cards
+│   ├── model-runtime/        # src/{core,providers}
 │   ├── types/
 │   └── utils/
-└── e2e/                         # E2E tests (Cucumber + Playwright)
+└── src/
+    ├── app/
+    │   ├── (backend)/        # api, f, market, middleware, oidc, trpc, webapi
+    │   ├── spa/              # SPA HTML template service
+    │   └── [variants]/(auth)/ # Auth pages (SSR required)
+    ├── routes/               # SPA page segments (thin — delegate to features/)
+    │   └── (main)/ (mobile)/ (desktop)/ (popup)/ onboarding/ share/
+    ├── spa/                  # SPA entries + router config
+    │   ├── entry.{web,mobile,desktop,popup}.tsx
+    │   └── router/
+    ├── business/             # Open-source stubs (~50) overridden by cloud src/business/
+    ├── features/             # Domain business components
+    ├── store/                # ~28 zustand stores — `ls` for the full set
+    ├── server/               # featureFlags, globalConfig, modules, routers, services
+    └── ...                   # components, hooks, layout, libs, locales, services, types, utils
 ```

+### cloud repo — key directories
+
+```
+(cloud root)
+├── packages/business/        # Cloud overrides: config, const, model-runtime
+├── src/
+│   ├── business/             # Cloud impls of submodule stubs (client/server/locales)
+│   ├── routes/               # Cloud-only route groups: (cloud)/, embed/
+│   ├── store/                # Cloud-only stores (e.g. subscription/)
+│   ├── server/               # Cloud routers & services (billing, budget, risk control...)
+│   └── app/(backend)/cron/   # Vercel cron routes (schedules declared in root vercel.ts)
+└── vercel.ts                 # Cron schedule declarations
+```
+
+> File search rule: a path like `@/store/x` resolves cloud `src/store/x` first, then
+> `lobehub/packages/store/src/x`, then `lobehub/src/store/x`. Cloud override wins.
+
 ## Architecture Map

-| Layer            | Location                                            |
-| ---------------- | --------------------------------------------------- |
-| UI Components    | `src/components`, `src/features`                    |
-| SPA Pages        | `src/routes/`                                       |
-| React Router     | `src/spa/router/`                                   |
-| Global Providers | `src/layout`                                        |
-| Zustand Stores   | `src/store`                                         |
-| Client Services  | `src/services/`                                     |
-| REST API         | `src/app/(backend)/webapi`                          |
-| tRPC Routers     | `src/server/routers/{async\|lambda\|mobile\|tools}` |
-| Server Services  | `src/server/services` (can access DB)               |
-| Server Modules   | `src/server/modules` (no DB access)                 |
-| Feature Flags    | `src/server/featureFlags`                           |
-| Global Config    | `src/server/globalConfig`                           |
-| DB Schema        | `packages/database/src/schemas`                     |
-| DB Model         | `packages/database/src/models`                      |
-| DB Repository    | `packages/database/src/repositories`                |
-| Third-party      | `src/libs` (analytics, oidc, etc.)                  |
-| Builtin Tools    | `src/tools`, `packages/builtin-tool-*`              |
-| Cloud-only       | `src/business/*`, `packages/business/*`             |
+| Layer            | Location                                             |
+| ---------------- | ---------------------------------------------------- |
+| UI Components    | `src/components`, `src/features`                     |
+| SPA Pages        | `src/routes/`                                        |
+| React Router     | `src/spa/router/`                                    |
+| Global Providers | `src/layout`                                         |
+| Zustand Stores   | `src/store`                                          |
+| Client Services  | `src/services/`                                      |
+| REST API         | `src/app/(backend)/webapi`                           |
+| tRPC Routers     | `src/server/routers/{async\|lambda\|mobile\|tools}`  |
+| Server Services  | `src/server/services` (can access DB)                |
+| Server Modules   | `src/server/modules` (no DB access)                  |
+| Feature Flags    | `src/server/featureFlags`                            |
+| Global Config    | `src/server/globalConfig`                            |
+| DB Schema        | `packages/database/src/schemas`                      |
+| DB Model         | `packages/database/src/models`                       |
+| DB Repository    | `packages/database/src/repositories`                 |
+| Third-party      | `src/libs` (analytics, oidc, etc.)                   |
+| Builtin Tools    | `src/tools`, `packages/builtin-tool-*`               |
+| Cloud-only       | `src/business/*`, `packages/business/*` (cloud repo) |

 ## Data Flow

@@ -1,94 +1,96 @@
 ---
 name: react
-description: React component development guide. Use when working with React components (.tsx files), creating UI, using @lobehub/ui components, implementing routing, or building frontend features. Triggers on React component creation, modification, layout implementation, or navigation tasks.
+description: 'Use when writing or editing any `.tsx` under `src/**`. Triggers: createStaticStyles, createStyles, cssVar, antd-style, Flexbox, Center, Select, Modal, Drawer, Button, Tooltip, DropdownMenu, Popover, Switch, ScrollArea, Link, useNavigate, react-router-dom, next/link, desktopRouter, componentMap.desktop, .desktop.tsx, new component, new page, edit layout, add styles, zustand selector, @lobehub/ui, antd import.'
+user-invocable: false
 ---

 # React Component Writing Guide

- Use antd-style for complex styles; for simple cases, use inline `style` attribute
-  - **Prefer `createStaticStyles` with `cssVar.*`** (zero-runtime) — module-level, no hook call required
-  - Only fall back to `createStyles` + `token` when styles genuinely need runtime computation (dynamic props, JS color fns like `readableColor`/`chroma`)
-  - See `.cursor/docs/createStaticStyles_migration_guide.md` for full pattern
- Use `Flexbox` and `Center` from `@lobehub/ui` for layouts (see `references/layout-kit.md`)
- Component priority: `src/components` > `@lobehub/ui/base-ui` > `@lobehub/ui` > custom implementation
-  - Always prefer `@lobehub/ui/base-ui` primitives (Select, Modal, DropdownMenu, Popover, Switch, ScrollArea…) over antd equivalents
-  - Fall back to `@lobehub/ui` higher-level components when base-ui has no match
-  - Only implement a custom component as a last resort — never reach for antd directly
- Use selectors to access zustand store data
+## Styling

-## @lobehub/ui Components
+| Scenario                                                   | Approach                                                       |
+| ---------------------------------------------------------- | -------------------------------------------------------------- |
+| Most cases                                                 | `createStaticStyles` + `cssVar.*` (zero-runtime, module-level) |
+| Simple one-off                                             | Inline `style` attribute                                       |
+| Truly dynamic (JS color fns like `readableColor`/`chroma`) | `createStyles` + `token` — **last resort**                     |

-If unsure about component usage, search existing code in this project. Most components extend antd with additional props.
+## Component Priority

-Reference: `node_modules/@lobehub/ui/es/index.mjs` for all available components.
+1. **`src/components`** — project-specific reusable components
+2. **`@lobehub/ui/base-ui`** — headless primitives (Select, Modal, DropdownMenu, Popover, Switch, ScrollArea…)
+3. **`@lobehub/ui`** — higher-level components (ActionIcon, Markdown, DragPage…)
+4. **Custom implementation** — last resort; never reach for antd directly

-**Common Components:**
+If unsure about available components, search existing code or check `node_modules/@lobehub/ui/es/index.mjs`.

- General: ActionIcon, ActionIconGroup, Block, Button, Icon
- Data Display: Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip
- Data Entry: CodeEditor, CopyButton, EditableText, Form, FormModal, Input, SearchBar, Select
- Feedback: Alert, Drawer, Modal
- Layout: Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow
- Navigation: Burger, Dropdown, Menu, SideNav, Tabs
+### Common @lobehub/ui Components
+
+| Category     | Components                                                                      |
+| ------------ | ------------------------------------------------------------------------------- |
+| General      | ActionIcon, ActionIconGroup, Block, Button, Icon                                |
+| Data Display | Avatar, Collapse, Empty, Highlighter, Markdown, Tag, Tooltip                    |
+| Data Entry   | CodeEditor, CopyButton, EditableText, Form, FormModal, Input, SearchBar, Select |
+| Feedback     | Alert, Drawer, Modal                                                            |
+| Layout       | Center, DraggablePanel, Flexbox, Grid, Header, MaskShadow                       |
+| Navigation   | Burger, Dropdown, Menu, SideNav, Tabs                                           |
+
+## Layout
+
+Use `Flexbox` and `Center` from `@lobehub/ui`. See `references/layout-kit.md` for full props and examples.
+
+- Use `gap` instead of `margin` for spacing between flex children
+- Use `flex={1}` to fill available space
+- Nest Flexbox for complex layouts; set `overflow: 'auto'` for scrollable regions
+
+## Navigation
+
+**For SPA pages, use `react-router-dom`, NOT `next/link`.**
+
+```tsx
+// ❌ Wrong
+import Link from 'next/link';
+
+// ✅ Correct
+import { Link, useNavigate } from 'react-router-dom';
+```
+
+Access navigate from stores: `useGlobalStore.getState().navigate?.('/settings');`
+
+## Desktop File Sync Rule
+
+Files with a `.desktop.ts(x)` variant must be edited **in sync**. Drift causes blank pages in Electron.
+
+| Base file (web)            | Desktop file (Electron)            |
+| -------------------------- | ---------------------------------- |
+| `desktopRouter.config.tsx` | `desktopRouter.config.desktop.tsx` |
+| `componentMap.ts`          | `componentMap.desktop.ts`          |
+
+**After editing any `.ts`/`.tsx`:** glob for `<filename>.desktop.{ts,tsx}` in the same directory. If found, apply the equivalent sync-import change.

 ## Routing Architecture

-Hybrid routing: Next.js App Router (static pages) + React Router DOM (main SPA).
+| Route Type         | Use Case   | Implementation                                     |
+| ------------------ | ---------- | -------------------------------------------------- |
+| Next.js App Router | Auth pages | `src/app/[variants]/(auth)/`                       |
+| React Router DOM   | Main SPA   | `desktopRouter.config.tsx` + `.desktop.tsx` (pair) |

-| Route Type         | Use Case                          | Implementation                                                               |
-| ------------------ | --------------------------------- | ---------------------------------------------------------------------------- |
-| Next.js App Router | Auth pages (login, signup, oauth) | `src/app/[variants]/(auth)/`                                                 |
-| React Router DOM   | Main SPA (chat, settings)         | `desktopRouter.config.tsx` + `desktopRouter.config.desktop.tsx` (must match) |
-
-### Key Files
-
- Entry: `src/spa/entry.web.tsx` (web), `src/spa/entry.mobile.tsx`, `src/spa/entry.desktop.tsx`
- Desktop router (pair — **always edit both** when changing routes): `src/spa/router/desktopRouter.config.tsx` (dynamic imports) and `src/spa/router/desktopRouter.config.desktop.tsx` (sync imports). Drift can cause unregistered routes / blank screen.
- Mobile router: `src/spa/router/mobileRouter.config.tsx`
- Router utilities: `src/utils/router.tsx`
-
-### `.desktop.{ts,tsx}` File Sync Rule
-
-**CRITICAL**: Some files have a `.desktop.ts(x)` variant that Electron uses instead of the base file. When editing a base file, **always check** if a `.desktop` counterpart exists and update it in sync. Drift causes blank pages or missing features in Electron.
-
-Known pairs that must stay in sync:
-
-| Base file (web, dynamic imports)                      | Desktop file (Electron, sync imports)                         |
-| ----------------------------------------------------- | ------------------------------------------------------------- |
-| `src/spa/router/desktopRouter.config.tsx`             | `src/spa/router/desktopRouter.config.desktop.tsx`             |
-| `src/routes/(main)/settings/features/componentMap.ts` | `src/routes/(main)/settings/features/componentMap.desktop.ts` |
-
-**How to check**: After editing any `.ts` / `.tsx` file, run `Glob` for `<filename>.desktop.{ts,tsx}` in the same directory. If a match exists, update it with the equivalent sync-import change.
-
-### Router Utilities
+Router utilities:

 ```tsx
 import { dynamicElement, redirectElement, ErrorBoundary } from '@/utils/router';
-
 element: dynamicElement(() => import('./chat'), 'Desktop > Chat');
 element: redirectElement('/settings/profile');
 errorElement: <ErrorBoundary />;
 ```

-### Navigation
+## Common Mistakes

-**Important**: For SPA pages, use `Link` from `react-router-dom`, NOT `next/link`.
-
-```tsx
-// ❌ Wrong
-import Link from 'next/link';
-<Link href="/">Home</Link>;
-
-// ✅ Correct
-import { Link } from 'react-router-dom';
-<Link to="/">Home</Link>;
-
-// In components
-import { useNavigate } from 'react-router-dom';
-const navigate = useNavigate();
-navigate('/chat');
-
-// From stores
-const navigate = useGlobalStore.getState().navigate;
-navigate?.('/settings');
-```
+| Mistake                                                           | Fix                                                               |
+| ----------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Using `next/link` in SPA                                          | Use `react-router-dom` `Link`                                     |
+| Using antd directly                                               | Use `@lobehub/ui/base-ui` first, then `@lobehub/ui`               |
+| `createStyles` for static styles                                  | Use `createStaticStyles` + `cssVar`                               |
+| Editing only `desktopRouter.config.tsx`                           | Must edit both `.tsx` and `.desktop.tsx`                          |
+| Using `margin` for flex spacing                                   | Use `gap` prop on Flexbox                                         |
+| Accessing zustand store without selector                          | Use selectors to access store data (see zustand skill)            |
+| Text or icon-text actions built with `Flexbox`/`Text` + `onClick` | Use `Button type={'text'} size={'small'}` with `icon` when needed |
@@ -1,58 +1,52 @@
 ---
-name: code-review
-description: 'Code review checklist for LobeHub. Use when reviewing PRs, diffs, or code changes. Covers correctness, security, quality, and project-specific patterns.'
+name: review-checklist
+description: 'Common recurring mistakes in LobeHub code review — console leftovers, missing return await, hardcoded secrets, hardcoded i18n strings, desktop router pair drift, antd vs @lobehub/ui, non-idempotent migrations, cloud impact red flags. Use as a quick checklist when reviewing PRs, diffs, or branch changes.'
+user-invocable: false
 ---

-# Code Review Guide
+# Review Checklist

-## Before You Start
-
-1. Read `/typescript` and `/testing` skills for code style and test conventions
-2. Get the diff (skip if already in context, e.g., injected by GitHub review app): `git diff` or `git diff origin/canary..HEAD`
-
-## Checklist
-
-### Correctness
+## Correctness

 - Leftover `console.log` / `console.debug` — should use `debug` package or remove
 - Missing `return await` in try/catch — see <https://typescript-eslint.io/rules/return-await/> (not in our ESLint config yet, requires type info)
 - Can the fix/implementation be more concise, efficient, or have better compatibility?

-### Security
+## Security

 - No sensitive data (API keys, tokens, credentials) in `console.*` or `debug()` output
 - No base64 output to terminal — extremely long, freezes output
 - No hardcoded secrets — use environment variables

-### Testing
+## Testing

 - Bug fixes must include tests covering the fixed scenario
 - New logic (services, store actions, utilities) should have test coverage
 - Existing tests still cover the changed behavior?
 - Prefer `vi.spyOn` over `vi.mock` (see `/testing` skill)

-### i18n
+## i18n

 - New user-facing strings use i18n keys, not hardcoded text
 - Keys added to `src/locales/default/{namespace}.ts` with `{feature}.{context}.{action|status}` naming
 - For PRs: `locales/` translations for all languages updated (`pnpm i18n`)

-### SPA / routing
+## SPA / routing

 - **`desktopRouter` pair:** If the diff touches `src/spa/router/desktopRouter.config.tsx`, does it also update `src/spa/router/desktopRouter.config.desktop.tsx` with the same route paths and nesting? Single-file edits often cause drift and blank screens.

-### Reuse
+## Reuse

 - 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; prefer `createStaticStyles` + `cssVar.*` over `createStyles` + `token` unless runtime computation is required

-### Database
+## Database

 - Migration scripts must be idempotent (`IF NOT EXISTS`, `IF EXISTS` guards)

-### Cloud Impact
+## Cloud Impact

 A downstream cloud deployment depends on this repo. Flag changes that may require cloud-side updates:

@@ -61,13 +55,3 @@ A downstream cloud deployment depends on this repo. Flag changes that may requir
 - **Dependency versions bumped** — e.g., upgrading `next` or `drizzle-orm` in `package.json`
 - **`@lobechat/business-*` exports changed** — e.g., renaming a function in `src/business/` or changing type signatures in `packages/business/`
 - `src/business/` and `packages/business/` must not expose cloud commercial logic in comments or code
-
-## Output Format
-
-For local CLI review only (GitHub review app posts inline PR comments instead):
-
- Number all findings sequentially
- Indicate priority: `[high]` / `[medium]` / `[low]`
- Include file path and line number for each finding
- Only list problems — no summary, no praise
- Re-read full source for each finding to verify it's real, then output "All findings verified."
@@ -0,0 +1,44 @@
+---
+name: 'source-command-dedupe'
+description: 'Find duplicate GitHub issues'
+---
+
+# source-command-dedupe
+
+Use this skill when the user asks to run the migrated source command `dedupe`.
+
+## Command Template
+
+Find up to 3 likely duplicate issues for a given GitHub issue.
+
+To do this, follow these steps precisely:
+
+1. Use an agent to check if the Github issue (a) is closed, (b) does not need to be deduped (eg. because it is broad product feedback without a specific solution, or positive feedback), or (c) already has a duplicates comment that you made earlier. If so, do not proceed.
+2. Use an agent to view a Github issue, and ask the agent to return a summary of the issue
+3. Then, launch 5 parallel agents to search Github for duplicates of this issue, using diverse keywords and search approaches, using the summary from #1
+4. Next, feed the results from #1 and #2 into another agent, so that it can filter out false positives, that are likely not actually duplicates of the original issue. If there are no duplicates remaining, do not proceed.
+5. Finally, comment back on the issue with a list of up to three duplicate issues (or zero, if there are no likely duplicates)
+
+Notes (be sure to tell this to your agents, too):
+
+- Use `gh` to interact with Github, rather than web fetch
+- Do not use other tools, beyond `gh` (eg. don't use other MCP servers, file edit, etc.)
+- Make a todo list first
+- For your comment, follow the following format precisely (assuming for this example that you found 3 suspected duplicates):
+
+---
+
+Found 3 possible duplicate issues:
+
+1. <link to issue>
+2. <link to issue>
+3. <link to issue>
+
+This issue will be automatically closed as a duplicate in 3 days.
+
+- If your issue is a duplicate, please close it and 👍 the existing issue instead
+- To prevent auto-closure, add a comment or 👎 this comment
+
+> 🤖 Generated with Codex
+
+---
@@ -1,6 +1,7 @@
 ---
 name: spa-routes
 description: MUST use when editing src/routes/ segments, src/spa/router/desktopRouter.config.tsx or desktopRouter.config.desktop.tsx (always change both together), mobileRouter.config.tsx, or when moving UI/logic between routes and src/features/.
+user-invocable: false
 ---

 # SPA Routes and Features Guide
@@ -84,10 +85,10 @@ Each feature should:

 ## 3a. Desktop router pair (`desktopRouter.config` × 2)

-| File | Role |
-|------|------|
-| `desktopRouter.config.tsx` | Dynamic imports via `dynamicElement` / `dynamicLayout` — code-splitting; used by `entry.web.tsx` and `entry.desktop.tsx`. |
-| `desktopRouter.config.desktop.tsx` | Same route tree with **synchronous** imports — kept for Electron / local parity and predictable bundling. |
+| File                               | Role                                                                                                                      |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `desktopRouter.config.tsx`         | Dynamic imports via `dynamicElement` / `dynamicLayout` — code-splitting; used by `entry.web.tsx` and `entry.desktop.tsx`. |
+| `desktopRouter.config.desktop.tsx` | Same route tree with **synchronous** imports — kept for Electron / local parity and predictable bundling.                 |

 Anything that changes the tree (new segment, renamed `path`, moved layout, new child route) must be reflected in **both** files in one PR or commit. Remove routes from both when deleting.

@@ -1,257 +1,91 @@
 ---
 name: store-data-structures
 description: Zustand store data structure patterns for LobeHub. Covers List vs Detail data structures, Map + Reducer patterns, type definitions, and when to use each pattern. Use when designing store state, choosing data structures, or implementing list/detail pages.
+user-invocable: false
 ---

 # LobeHub Store Data Structures

-This guide covers how to structure data in Zustand stores for optimal performance and user experience.
+How to structure data in Zustand stores for fast list rendering, multi-detail caching, and ergonomic optimistic updates.

 ## Core Principles

 ### ✅ DO

-1. **Separate List and Detail** - Use different structures for list pages and detail pages
-2. **Use Map for Details** - Cache multiple detail pages with `Record<string, Detail>`
-3. **Use Array for Lists** - Simple arrays for list display
-4. **Types from @lobechat/types** - Never use `@lobechat/database` types in stores
-5. **Distinguish List and Detail types** - List types may have computed UI fields
+1. **Separate List and Detail** — different structures for list pages and detail pages
+2. **Use Map for Details** — cache multiple detail pages with `Record<string, Detail>`
+3. **Use Array for Lists** — simple arrays for list display
+4. **Types from `@lobechat/types`** — never use `@lobechat/database` types in stores
+5. **Distinguish List and Detail types** — List types may have computed UI fields

 ### ❌ DON'T

-1. **Don't use single detail object** - Can't cache multiple pages
-2. **Don't mix List and Detail types** - They have different purposes
-3. **Don't use database types** - Use types from `@lobechat/types`
-4. **Don't use Map for lists** - Simple arrays are sufficient
+1. **Don't use a single detail object** — can't cache multiple pages
+2. **Don't mix List and Detail types** — they have different purposes
+3. **Don't use database types** — use types from `@lobechat/types`
+4. **Don't use Map for lists** — simple arrays are sufficient

 ---

 ## Type Definitions

-Types should be organized by entity in separate files:
+Each entity gets its own file under `@lobechat/types/`. Each file exports two types:

-```
-@lobechat/types/src/eval/
-├── benchmark.ts        # Benchmark types
-├── agentEvalDataset.ts # Dataset types
-├── agentEvalRun.ts     # Run types
-└── index.ts           # Re-exports
-```
+- **Detail type** — full entity, including heavy fields (rubrics, content, editor state, …)
+- **List item type** — a **subset** that excludes heavy fields, may add computed UI fields (counts, timestamps formatted for display)

-### Example: Benchmark Types
+**Important:** the List type is a **subset**, not an `extends` of Detail. Extending pulls the heavy fields right back in.

-```typescript
-// packages/types/src/eval/benchmark.ts
-import type { EvalBenchmarkRubric } from './rubric';
-
-// ============================================
-// Detail Type - Full entity (for detail pages)
-// ============================================
-
-/**
- * Full benchmark entity with all fields including heavy data
- */
-export interface AgentEvalBenchmark {
-  createdAt: Date;
-  description?: string | null;
-  id: string;
-  identifier: string;
-  isSystem: boolean;
-  metadata?: Record<string, unknown> | null;
-  name: string;
-  referenceUrl?: string | null;
-  rubrics: EvalBenchmarkRubric[]; // Heavy field
-  updatedAt: Date;
-}
-
-// ============================================
-// List Type - Lightweight (for list display)
-// ============================================
-
-/**
- * Lightweight benchmark item - excludes heavy fields
- * May include computed statistics for UI
- */
-export interface AgentEvalBenchmarkListItem {
-  createdAt: Date;
-  description?: string | null;
-  id: string;
-  identifier: string;
-  isSystem: boolean;
-  name: string;
-  // Note: rubrics NOT included (heavy field)
-
-  // Computed statistics for UI display
-  datasetCount?: number;
-  runCount?: number;
-  testCaseCount?: number;
-}
-```
-
-### Example: Document Types (with heavy content)
-
-```typescript
-// packages/types/src/document.ts
-
-/**
- * Full document entity - includes heavy content fields
- */
-export interface Document {
-  id: string;
-  title: string;
-  description?: string;
-  content: string; // Heavy field - full markdown content
-  editorData: any; // Heavy field - editor state
-  metadata?: Record<string, unknown>;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-/**
- * Lightweight document item - excludes heavy content
- */
-export interface DocumentListItem {
-  id: string;
-  title: string;
-  description?: string;
-  // Note: content and editorData NOT included
-  createdAt: Date;
-  updatedAt: Date;
-
-  // Computed statistics
-  wordCount?: number;
-  lastEditedBy?: string;
-}
-```
-
-**Key Points:**
-
- **Detail types** include ALL fields from database (full entity)
- **List types** are **subsets** that exclude heavy/large fields
- List types may add computed statistics for UI (e.g., `testCaseCount`)
- **Each entity gets its own file** (not mixed together)
- **All types** exported from `@lobechat/types`, NOT `@lobechat/database`
-
-**Heavy fields to exclude from List:**
-
- Large text content (`content`, `editorData`, `fullDescription`)
- Complex objects (`rubrics`, `config`, `metrics`)
- Binary data (`image`, `file`)
- Large arrays (`messages`, `items`)
+> See [`references/types.md`](./references/types.md) for full worked examples (Benchmark, Document) and the heavy-field exclusion checklist.

 ---

 ## When to Use Map vs Array

-### Use Map + Reducer (for Detail Data)
+### Use Map + Reducer — for Detail Data

-✅ **Detail page data caching** - Cache multiple detail pages simultaneously
-✅ **Optimistic updates** - Update UI before API responds
-✅ **Per-item loading states** - Track which items are being updated
-✅ **Multiple pages open** - User can navigate between details without refetching
-
-**Structure:**
+✅ Detail page data caching — multiple detail pages cached simultaneously
+✅ Optimistic updates — update UI before API responds
+✅ Per-item loading states — track which items are being updated
+✅ Multi-page navigation — user can switch between details without refetching

 ```typescript
 benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
 ```

-**Example:** Benchmark detail pages, Dataset detail pages, User profiles
+Examples: benchmark detail pages, dataset detail pages, user profiles.

-### Use Simple Array (for List Data)
+### Use Simple Array — for List Data

-✅ **List display** - Lists, tables, cards
-✅ **Read-only or refresh-as-whole** - Entire list refreshes together
-✅ **No per-item updates** - No need to update individual items
-✅ **Simple data flow** - Easier to understand and maintain
-
-**Structure:**
+✅ List display — lists, tables, cards
+✅ Refresh as a whole — entire list refreshes together
+✅ No per-item updates — no need to mutate individual rows in place
+✅ Simple data flow — fewer moving parts

 ```typescript
-benchmarkList: AgentEvalBenchmarkListItem[]
+benchmarkList: AgentEvalBenchmarkListItem[];
 ```

-**Example:** Benchmark list, Dataset list, User list
+Examples: benchmark list, dataset list, user list.

 ---

 ## State Structure Pattern

-### Complete Example
-
-```typescript
-// packages/types/src/eval/benchmark.ts
-import type { EvalBenchmarkRubric } from './rubric';
-
-/**
- * Full benchmark entity (for detail pages)
- */
-export interface AgentEvalBenchmark {
-  id: string;
-  name: string;
-  description?: string | null;
-  identifier: string;
-  rubrics: EvalBenchmarkRubric[]; // Heavy field
-  metadata?: Record<string, unknown> | null;
-  isSystem: boolean;
-  createdAt: Date;
-  updatedAt: Date;
-}
-
-/**
- * Lightweight benchmark (for list display)
- * Excludes heavy fields like rubrics
- */
-export interface AgentEvalBenchmarkListItem {
-  id: string;
-  name: string;
-  description?: string | null;
-  identifier: string;
-  isSystem: boolean;
-  createdAt: Date;
-  // Note: rubrics excluded
-
-  // Computed statistics
-  testCaseCount?: number;
-  datasetCount?: number;
-  runCount?: number;
-}
-```
-
 ```typescript
 // src/store/eval/slices/benchmark/initialState.ts
 import type { AgentEvalBenchmark, AgentEvalBenchmarkListItem } from '@lobechat/types';

 export interface BenchmarkSliceState {
-  // ============================================
-  // List Data - Simple Array
-  // ============================================
-  /**
-   * List of benchmarks for list page display
-   * May include computed fields like testCaseCount
-   */
+  // List — simple array
  benchmarkList: AgentEvalBenchmarkListItem[];
  benchmarkListInit: boolean;

-  // ============================================
-  // Detail Data - Map for Caching
-  // ============================================
-  /**
-   * Map of benchmark details keyed by ID
-   * Caches detail page data for multiple benchmarks
-   * Enables optimistic updates and per-item loading
-   */
+  // Detail — map for multi-entity caching
  benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
+  loadingBenchmarkDetailIds: string[]; // per-item loading

-  /**
-   * Track which benchmark details are being loaded/updated
-   * For showing spinners on specific items
-   */
-  loadingBenchmarkDetailIds: string[];
-
-  // ============================================
-  // Mutation States
-  // ============================================
+  // Mutation states (drive form-level UI)
  isCreatingBenchmark: boolean;
  isUpdatingBenchmark: boolean;
  isDeletingBenchmark: boolean;
@@ -272,180 +106,51 @@ export const benchmarkInitialState: BenchmarkSliceState = {

 ## Reducer Pattern (for Detail Map)

-### Why Use Reducer?
+When the Detail Map needs optimistic updates (i.e. the user edits a row and the UI should reflect it before the server confirms), wire a typed reducer instead of inlining `set` calls. This keeps mutations testable and the dispatch surface small.

- **Immutable updates** - Immer ensures immutability
- **Type-safe actions** - TypeScript discriminated unions
- **Testable** - Pure functions easy to test
- **Reusable** - Same reducer for optimistic updates and server data
-
-### Reducer Structure
-
-```typescript
-// src/store/eval/slices/benchmark/reducer.ts
-import { produce } from 'immer';
-import type { AgentEvalBenchmark } from '@lobechat/types';
-
-// ============================================
-// Action Types
-// ============================================
-
-type SetBenchmarkDetailAction = {
-  id: string;
-  type: 'setBenchmarkDetail';
-  value: AgentEvalBenchmark;
-};
-
-type UpdateBenchmarkDetailAction = {
-  id: string;
-  type: 'updateBenchmarkDetail';
-  value: Partial<AgentEvalBenchmark>;
-};
-
-type DeleteBenchmarkDetailAction = {
-  id: string;
-  type: 'deleteBenchmarkDetail';
-};
-
-export type BenchmarkDetailDispatch =
-  | SetBenchmarkDetailAction
-  | UpdateBenchmarkDetailAction
-  | DeleteBenchmarkDetailAction;
-
-// ============================================
-// Reducer Function
-// ============================================
-
-export const benchmarkDetailReducer = (
-  state: Record<string, AgentEvalBenchmark> = {},
-  payload: BenchmarkDetailDispatch,
-): Record<string, AgentEvalBenchmark> => {
-  switch (payload.type) {
-    case 'setBenchmarkDetail': {
-      return produce(state, (draft) => {
-        draft[payload.id] = payload.value;
-      });
-    }
-
-    case 'updateBenchmarkDetail': {
-      return produce(state, (draft) => {
-        if (draft[payload.id]) {
-          draft[payload.id] = { ...draft[payload.id], ...payload.value };
-        }
-      });
-    }
-
-    case 'deleteBenchmarkDetail': {
-      return produce(state, (draft) => {
-        delete draft[payload.id];
-      });
-    }
-
-    default:
-      return state;
-  }
-};
-```
-
-### Internal Dispatch Methods
-
-```typescript
-// In action.ts
-export interface BenchmarkAction {
-  // ... other methods ...
-
-  // Internal methods - not for direct UI use
-  internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
-  internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
-}
-
-export const createBenchmarkSlice: StateCreator<...> = (set, get) => ({
-  // ... other methods ...
-
-  // Internal - Dispatch to reducer
-  internal_dispatchBenchmarkDetail: (payload) => {
-    const currentMap = get().benchmarkDetailMap;
-    const nextMap = benchmarkDetailReducer(currentMap, payload);
-
-    // Only update if changed
-    if (isEqual(nextMap, currentMap)) return;
-
-    set(
-      { benchmarkDetailMap: nextMap },
-      false,
-      `dispatchBenchmarkDetail/${payload.type}`,
-    );
-  },
-
-  // Internal - Update loading state
-  internal_updateBenchmarkDetailLoading: (id, loading) => {
-    set(
-      (state) => {
-        if (loading) {
-          return { loadingBenchmarkDetailIds: [...state.loadingBenchmarkDetailIds, id] };
-        }
-        return {
-          loadingBenchmarkDetailIds: state.loadingBenchmarkDetailIds.filter((i) => i !== id),
-        };
-      },
-      false,
-      'updateBenchmarkDetailLoading',
-    );
-  },
-});
-```
+> See [`references/reducer.md`](./references/reducer.md) for the full discriminated-union action types, the `produce`-based reducer, and the `internal_dispatch*` slice methods that connect them to Zustand.

 ---

 ## Data Structure Comparison

-### ❌ WRONG - Single Detail Object
+### ❌ WRONG — Single Detail Object

 ```typescript
 interface BenchmarkSliceState {
-  // ❌ Can only cache one detail
  benchmarkDetail: AgentEvalBenchmark | null;
-
-  // ❌ Global loading state
  isLoadingBenchmarkDetail: boolean;
 }
 ```

-**Problems:**
+Problems:

 - Can only cache one detail page at a time
- Switching between details causes unnecessary refetches
+- Switching between details forces refetch
 - No optimistic updates
 - No per-item loading states

-### ✅ CORRECT - Separate List and Detail
+### ✅ CORRECT — Separate List and Detail

 ```typescript
-import type { AgentEvalBenchmark, AgentEvalBenchmarkListItem } from '@lobechat/types';
-
 interface BenchmarkSliceState {
-  // ✅ List data - simple array
  benchmarkList: AgentEvalBenchmarkListItem[];
  benchmarkListInit: boolean;

-  // ✅ Detail data - map for caching
  benchmarkDetailMap: Record<string, AgentEvalBenchmark>;
-
-  // ✅ Per-item loading
  loadingBenchmarkDetailIds: string[];

-  // ✅ Mutation states
  isCreatingBenchmark: boolean;
  isUpdatingBenchmark: boolean;
  isDeletingBenchmark: boolean;
 }
 ```

-**Benefits:**
+Benefits:

 - Cache multiple detail pages
 - Fast navigation between cached details
- Optimistic updates with reducer
+- Optimistic updates via reducer
 - Per-item loading states
 - Clear separation of concerns

@@ -455,22 +160,16 @@ interface BenchmarkSliceState {

 ### Accessing List Data

-```typescript
+```tsx
 const BenchmarkList = () => {
-  // Simple array access
  const benchmarks = useEvalStore((s) => s.benchmarkList);
  const isInit = useEvalStore((s) => s.benchmarkListInit);

  if (!isInit) return <Loading />;
-
  return (
    <div>
-      {benchmarks.map(b => (
-        <BenchmarkCard
-          key={b.id}
-          name={b.name}
-          testCaseCount={b.testCaseCount} // Computed field
-        />
+      {benchmarks.map((b) => (
+        <BenchmarkCard key={b.id} name={b.name} testCaseCount={b.testCaseCount} />
      ))}
    </div>
  );
@@ -479,22 +178,18 @@ const BenchmarkList = () => {

 ### Accessing Detail Data

-```typescript
+```tsx
 const BenchmarkDetail = () => {
  const { benchmarkId } = useParams<{ benchmarkId: string }>();

-  // Get from map
  const benchmark = useEvalStore((s) =>
    benchmarkId ? s.benchmarkDetailMap[benchmarkId] : undefined,
  );
-
-  // Check loading
  const isLoading = useEvalStore((s) =>
    benchmarkId ? s.loadingBenchmarkDetailIds.includes(benchmarkId) : false,
  );

  if (!benchmark) return <Loading />;
-
  return (
    <div>
      <h1>{benchmark.name}</h1>
@@ -510,7 +205,6 @@ const BenchmarkDetail = () => {
 // src/store/eval/slices/benchmark/selectors.ts
 export const benchmarkSelectors = {
  getBenchmarkDetail: (id: string) => (s: EvalStore) => s.benchmarkDetailMap[id],
-
  isLoadingBenchmarkDetail: (id: string) => (s: EvalStore) =>
    s.loadingBenchmarkDetailIds.includes(id),
 };
@@ -524,7 +218,7 @@ const isLoading = useEvalStore(benchmarkSelectors.isLoadingBenchmarkDetail(bench

 ## Decision Tree

-```
+```text
 Need to store data?
 │
 ├─ Is it a LIST for display?
@@ -547,43 +241,40 @@ Need to store data?

 When designing store state structure:

- [ ] **Organize types by entity** in separate files (e.g., `benchmark.ts`, `agentEvalDataset.ts`)
+- [ ] **Organize types by entity** in separate files (e.g. `benchmark.ts`, `agentEvalDataset.ts`)
 - [ ] Create **Detail** type (full entity with all fields including heavy ones)
 - [ ] Create **ListItem** type:
-  - [ ] Subset of Detail type (exclude heavy fields)
+  - [ ] Subset of Detail (exclude heavy fields)
  - [ ] May include computed statistics for UI
-  - [ ] **NOT** extending Detail type (it's a subset, not extension)
+  - [ ] **NOT** `extends` Detail
 - [ ] Use **array** for list data: `xxxList: XxxListItem[]`
 - [ ] Use **Map** for detail data: `xxxDetailMap: Record<string, Xxx>`
- [ ] Add per-item loading: `loadingXxxDetailIds: string[]`
- [ ] Create **reducer** for detail map if optimistic updates needed
- [ ] Add **internal dispatch** and **loading** methods
- [ ] Create **selectors** for clean access (optional but recommended)
- [ ] Document in comments:
-  - [ ] What fields are excluded from List and why
-  - [ ] What computed fields mean
-  - [ ] What each Map is for
+- [ ] Per-item loading: `loadingXxxDetailIds: string[]`
+- [ ] **Reducer** for detail map if optimistic updates needed (see [`references/reducer.md`](./references/reducer.md))
+- [ ] **Internal dispatch** and **loading** methods
+- [ ] **Selectors** for clean access (optional but recommended)
+- [ ] Document in comments which fields are excluded from List and why

 ---

 ## Best Practices

-1. **File organization** - One entity per file, not mixed together
-2. **List is subset** - ListItem excludes heavy fields, not extends Detail
-3. **Clear naming** - `xxxList` for arrays, `xxxDetailMap` for maps
-4. **Consistent patterns** - All detail maps follow same structure
-5. **Type safety** - Never use `any`, always use proper types
-6. **Document exclusions** - Comment which fields are excluded from List and why
-7. **Selectors** - Encapsulate access patterns
-8. **Loading states** - Per-item for details, global for lists
-9. **Immutability** - Use Immer in reducers
+1. **File organization** — one entity per file, not mixed
+2. **List is a subset** — ListItem excludes heavy fields, does not `extends` Detail
+3. **Clear naming** — `xxxList` for arrays, `xxxDetailMap` for maps
+4. **Consistent patterns** — all detail maps follow the same shape
+5. **Type safety** — never use `any`, always use proper types
+6. **Document exclusions** — comment which fields are excluded and why
+7. **Selectors** — encapsulate access patterns
+8. **Loading states** — per-item for details, global for mutations
+9. **Immutability** — use Immer in reducers

 ### Common Mistakes to Avoid

 ❌ **DON'T extend Detail in List:**

 ```typescript
-// Wrong - List should not extend Detail
+// Wrong — pulls heavy fields back in
 export interface BenchmarkListItem extends Benchmark {
  testCaseCount?: number;
 }
@@ -592,7 +283,6 @@ export interface BenchmarkListItem extends Benchmark {
 ✅ **DO create separate subset:**

 ```typescript
-// Correct - List is a subset with computed fields
 export interface BenchmarkListItem {
  id: string;
  name: string;
@@ -603,14 +293,14 @@ export interface BenchmarkListItem {

 ❌ **DON'T mix entities in one file:**

-```typescript
-// Wrong - all entities in agentEvalEntities.ts
+```text
+// Wrong — all entities in agentEvalEntities.ts
 ```

 ✅ **DO separate by entity:**

-```typescript
-// Correct - separate files
+```text
+// Correct — separate files
 // benchmark.ts
 // agentEvalDataset.ts
 // agentEvalRun.ts
@@ -620,5 +310,5 @@ export interface BenchmarkListItem {

 ## Related Skills

- `data-fetching` - How to fetch and update this data
- `zustand` - General Zustand patterns
+- `data-fetching` — how to fetch and update this data
+- `zustand` — general Zustand patterns
@@ -0,0 +1,118 @@
+# Reducer Pattern (for Detail Map)
+
+## Why Use a Reducer?
+
+- **Immutable updates** — Immer makes immutability easy
+- **Type-safe actions** — discriminated union of action types prevents typos
+- **Testable** — pure function, easy to unit test
+- **Reusable** — same reducer powers optimistic updates and server-data writes
+
+## Reducer Structure
+
+```typescript
+// src/store/eval/slices/benchmark/reducer.ts
+import { produce } from 'immer';
+import type { AgentEvalBenchmark } from '@lobechat/types';
+
+// Action types — discriminated union
+type SetBenchmarkDetailAction = {
+  id: string;
+  type: 'setBenchmarkDetail';
+  value: AgentEvalBenchmark;
+};
+
+type UpdateBenchmarkDetailAction = {
+  id: string;
+  type: 'updateBenchmarkDetail';
+  value: Partial<AgentEvalBenchmark>;
+};
+
+type DeleteBenchmarkDetailAction = {
+  id: string;
+  type: 'deleteBenchmarkDetail';
+};
+
+export type BenchmarkDetailDispatch =
+  | SetBenchmarkDetailAction
+  | UpdateBenchmarkDetailAction
+  | DeleteBenchmarkDetailAction;
+
+export const benchmarkDetailReducer = (
+  state: Record<string, AgentEvalBenchmark> = {},
+  payload: BenchmarkDetailDispatch,
+): Record<string, AgentEvalBenchmark> => {
+  switch (payload.type) {
+    case 'setBenchmarkDetail': {
+      return produce(state, (draft) => {
+        draft[payload.id] = payload.value;
+      });
+    }
+
+    case 'updateBenchmarkDetail': {
+      return produce(state, (draft) => {
+        if (draft[payload.id]) {
+          draft[payload.id] = { ...draft[payload.id], ...payload.value };
+        }
+      });
+    }
+
+    case 'deleteBenchmarkDetail': {
+      return produce(state, (draft) => {
+        delete draft[payload.id];
+      });
+    }
+
+    default:
+      return state;
+  }
+};
+```
+
+## Internal Dispatch Methods
+
+The slice exposes two `internal_*` methods so the reducer and the loading state stay encapsulated behind a stable contract:
+
+```typescript
+// In action.ts
+export interface BenchmarkAction {
+  // ... other methods ...
+
+  // Internal — not for direct UI use
+  internal_dispatchBenchmarkDetail: (payload: BenchmarkDetailDispatch) => void;
+  internal_updateBenchmarkDetailLoading: (id: string, loading: boolean) => void;
+}
+
+export const createBenchmarkSlice: StateCreator<...> = (set, get) => ({
+  // ... other methods ...
+
+  // Dispatch to reducer
+  internal_dispatchBenchmarkDetail: (payload) => {
+    const currentMap = get().benchmarkDetailMap;
+    const nextMap = benchmarkDetailReducer(currentMap, payload);
+
+    // Skip set when nothing changed — avoids unnecessary re-renders
+    if (isEqual(nextMap, currentMap)) return;
+
+    set(
+      { benchmarkDetailMap: nextMap },
+      false,
+      `dispatchBenchmarkDetail/${payload.type}`,
+    );
+  },
+
+  // Update loading state for a specific id
+  internal_updateBenchmarkDetailLoading: (id, loading) => {
+    set(
+      (state) => ({
+        loadingBenchmarkDetailIds: loading
+          ? [...state.loadingBenchmarkDetailIds, id]
+          : state.loadingBenchmarkDetailIds.filter((i) => i !== id),
+      }),
+      false,
+      'updateBenchmarkDetailLoading',
+    );
+  },
+});
+```
+
+The `internal_` prefix is a convention — UI components should call the public mutation methods (e.g. `updateBenchmark`), which in turn call `internal_dispatch*`. This keeps reducer dispatch shapes out of the component layer.
@@ -0,0 +1,101 @@
+# Type Definitions in Detail
+
+The skill body's Type Definitions section covers the rules; this file holds the full worked examples to keep SKILL.md lean.
+
+## Organization
+
+Types should be organized by entity in separate files (not mixed):
+
+```text
+@lobechat/types/src/eval/
+├── benchmark.ts        # Benchmark types
+├── agentEvalDataset.ts # Dataset types
+├── agentEvalRun.ts     # Run types
+└── index.ts            # Re-exports
+```
+
+## Example: Benchmark Types
+
+```typescript
+// packages/types/src/eval/benchmark.ts
+import type { EvalBenchmarkRubric } from './rubric';
+
+/**
+ * Full benchmark entity with all fields including heavy data.
+ */
+export interface AgentEvalBenchmark {
+  createdAt: Date;
+  description?: string | null;
+  id: string;
+  identifier: string;
+  isSystem: boolean;
+  metadata?: Record<string, unknown> | null;
+  name: string;
+  referenceUrl?: string | null;
+  rubrics: EvalBenchmarkRubric[]; // Heavy field
+  updatedAt: Date;
+}
+
+/**
+ * Lightweight benchmark item — excludes heavy fields, may add computed stats.
+ */
+export interface AgentEvalBenchmarkListItem {
+  createdAt: Date;
+  description?: string | null;
+  id: string;
+  identifier: string;
+  isSystem: boolean;
+  name: string;
+  // Note: rubrics NOT included (heavy field)
+
+  // Computed statistics for UI display
+  datasetCount?: number;
+  runCount?: number;
+  testCaseCount?: number;
+}
+```
+
+## Example: Document Types (with heavy content)
+
+```typescript
+// packages/types/src/document.ts
+
+/**
+ * Full document entity — includes heavy content fields.
+ */
+export interface Document {
+  id: string;
+  title: string;
+  description?: string;
+  content: string; // Heavy field — full markdown content
+  editorData: any; // Heavy field — editor state
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Lightweight document item — excludes heavy content.
+ */
+export interface DocumentListItem {
+  id: string;
+  title: string;
+  description?: string;
+  // Note: content and editorData NOT included
+  createdAt: Date;
+  updatedAt: Date;
+
+  // Computed statistics
+  wordCount?: number;
+  lastEditedBy?: string;
+}
+```
+
+## Heavy Fields to Exclude from List
+
+- Large text content (`content`, `editorData`, `fullDescription`)
+- Complex objects (`rubrics`, `config`, `metrics`)
+- Binary data (`image`, `file`)
+- Large arrays (`messages`, `items`)
+
+The reason these belong only on Detail: list pages render many rows, so pulling heavy fields blows up payload size and slows render. Detail pages render one entity, so the full payload is fine.
@@ -1,6 +1,7 @@
 ---
 name: testing
 description: Testing guide using Vitest. Use when writing tests (.test.ts, .test.tsx), fixing failing tests, improving test coverage, or debugging test issues. Triggers on test creation, test debugging, mock setup, or test-related questions.
+user-invocable: false
 ---

 # LobeHub Testing Guide
@@ -117,7 +117,7 @@ it('should handle tool calls', async () => {
      toolCalls: [
        {
          id: 'call_123',
-          name: 'lobe-web-browsing____search____builtin',
+          name: 'lobe-web-browsing____search',
          arguments: JSON.stringify({ query: 'weather' }),
        },
      ],
@@ -1,6 +1,7 @@
 ---
 name: trpc-router
 description: TRPC router development guide. Use when creating or modifying TRPC routers (src/server/routers/**), adding procedures, or working with server-side API endpoints. Triggers on TRPC router creation, procedure implementation, or API endpoint tasks.
+user-invocable: false
 ---

 # TRPC Router Guide
@@ -1,6 +1,7 @@
 ---
 name: typescript
-description: TypeScript code style and optimization guidelines. MUST READ before writing or modifying any TypeScript code (.ts, .tsx, .mts files). Also use when reviewing code quality or implementing type-safe patterns. Triggers on any TypeScript file edit, code style discussions, or type safety questions.
+description: "TypeScript code style and type-safety guide for LobeHub. Read before writing or editing any `.ts` / `.tsx` / `.mts` — covers `interface` vs `type`, `Record<PropertyKey, unknown>` over `any`/`object`, `as const satisfies`, `@ts-expect-error` over `@ts-ignore`, `import type` (`separate-type-imports`), `async`/`await` + `Promise.all`, `for…of` over indexed `for`, and the no-silent-`.catch(() => fallback)` rule. Also use when reviewing type quality, deciding module augmentation (`declare module`) over `namespace`, or designing extensible types (e.g. `PipelineContext.metadata`). Triggers on any TypeScript file edit, 'fix the type', 'why is this `any`', 'should this be interface or type', 'eslint type-import', 'ts-expect-error'."
+user-invocable: false
 ---

 # TypeScript Code Style Guide
@@ -28,12 +29,16 @@ description: TypeScript code style and optimization guidelines. MUST READ before
 ## Imports

 - This project uses `simple-import-sort/imports` and `consistent-type-imports` (`fixStyle: 'separate-type-imports'`)
+
 - **Separate type imports**: always use `import type { ... }` for type-only imports, NOT `import { type ... }` inline syntax
+
 - When a file already has `import type { ... }` from a package and you need to add a value import, keep them as **two separate statements**:
+
  ```ts
  import type { ChatTopicBotContext } from '@lobechat/types';
  import { RequestTrigger } from '@lobechat/types';
  ```
+
 - Within each import statement, specifiers are sorted **alphabetically by name**

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

 ## UI and Theming

@@ -51,7 +58,6 @@ description: TypeScript code style and optimization guidelines. MUST READ before

 ## Performance

- Prefer `for…of` loops over index-based `for` loops
 - Reuse existing utils in `packages/utils` or installed npm packages
 - Query only required columns from database

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

-This document covers cloud-specific workflow configurations and patterns for the lobehub-cloud project.
+Cloud-specific workflow configurations and patterns for the lobehub-cloud project.
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Directory Structure](#directory-structure) — submodule + cloud layout
+3. [Cloud-Specific Patterns](#cloud-specific-patterns) — cloud-only workflows + re-export pattern
+4. [TypeScript Path Mappings](#typescript-path-mappings)
+5. [Workflow Class Location](#workflow-class-location) — cloud-only vs shared
+6. [Environment Variables](#environment-variables)
+7. [Best Practices](#best-practices) — decide cloud vs OSS, re-export rules, naming
+8. [Migration Guide](#migration-guide) — moving workflows from cloud to lobehub
+9. [Examples](#examples) — `welcome-placeholder`, `agent-eval-run`
+10. [Troubleshooting](#troubleshooting) — circular imports, 404s, type errors
+11. [Related Documentation](#related-documentation)

 ## Overview

@@ -15,7 +29,7 @@ The lobehub-cloud project extends the open-source lobehub codebase with cloud-sp

 ### Lobehub Submodule (Open-source)

-```
+```text
 lobehub/
 └── src/
    ├── app/(backend)/api/workflows/
@@ -28,7 +42,7 @@ lobehub/

 ### Lobehub-cloud (Proprietary)

-```
+```text
 lobehub-cloud/
 └── src/
    ├── app/(backend)/api/workflows/
@@ -60,7 +74,7 @@ lobehub-cloud/

 **Structure**:

-```
+```text
 lobehub-cloud/src/
 ├── app/(backend)/api/workflows/
 │   └── feature-name/
@@ -162,7 +176,7 @@ This allows cloud to override specific modules while using lobehub defaults.

 Place workflow class in cloud:

-```
+```text
 lobehub-cloud/src/server/workflows/featureName/index.ts
 ```

@@ -170,7 +184,7 @@ lobehub-cloud/src/server/workflows/featureName/index.ts

 Place workflow class in lobehub, re-export in cloud if needed:

-```
+```text
 lobehub/src/server/workflows/featureName/index.ts
 ```

@@ -245,7 +259,7 @@ For shared features:

 Follow consistent naming across lobehub and cloud:

-```
+```text
 # Both should use same structure
 lobehub/src/app/(backend)/api/workflows/feature-name/
 lobehub-cloud/src/app/(backend)/api/workflows/feature-name/
@@ -306,7 +320,7 @@ import { Workflow } from 'lobehub/src/server/workflows/feature';

 **Structure**:

-```
+```text
 lobehub-cloud/
 ├── src/app/(backend)/api/workflows/welcome-placeholder/
 │   ├── process-users/route.ts
@@ -0,0 +1,91 @@
+# Worked Examples
+
+Two real workflows already in the codebase that follow this skill's pattern verbatim. Skim them when you want to see the pattern applied to concrete entities.
+
+## Example 1: Welcome Placeholder
+
+**Use case:** Generate AI-powered welcome placeholders for users.
+
+**Structure:**
+
+- Layer 1: `process-users` — entry point, checks eligible users
+- Layer 2: `paginate-users` — paginates through active users
+- Layer 3: `generate-user` — generates placeholders for ONE user
+
+**Key features:**
+
+- Filters users who already have cached placeholders in Redis
+- `paidOnly` flag to scope to subscribed users
+- `dryRun` mode for statistics
+- Fan-out for large user batches (`CHUNK_SIZE=20`)
+
+**Layer 3 shape:**
+
+```typescript
+export const { POST } = serve<GenerateUserPlaceholderPayload>(async (context) => {
+  const { userId } = context.requestPayload ?? {};
+
+  const workflow = new WelcomePlaceholderWorkflow(db, userId);
+  const placeholders = await context.run('generate', () => workflow.generate());
+
+  return { success: true, userId, placeholdersCount: placeholders.length };
+});
+```
+
+**Files:**
+
+- `/api/workflows/welcome-placeholder/process-users/route.ts`
+- `/api/workflows/welcome-placeholder/paginate-users/route.ts`
+- `/api/workflows/welcome-placeholder/generate-user/route.ts`
+- `/server/workflows/welcomePlaceholder/index.ts`
+
+---
+
+## Example 2: Agent Welcome
+
+**Use case:** Generate welcome messages and open questions for AI agents.
+
+**Structure:**
+
+- Layer 1: `process-agents` — entry point, checks eligible agents
+- Layer 2: `paginate-agents` — paginates through active agents
+- Layer 3: `generate-agent` — generates welcome data for ONE agent
+
+**Key features:**
+
+- Filters agents who already have cached data in Redis
+- `paidOnly` flag for subscribed users' agents only
+- `dryRun` mode for statistics
+- Fan-out for large agent batches (`CHUNK_SIZE=20`)
+
+**Layer 3 shape:**
+
+```typescript
+export const { POST } = serve<GenerateAgentWelcomePayload>(async (context) => {
+  const { agentId } = context.requestPayload ?? {};
+
+  const workflow = new AgentWelcomeWorkflow(db, agentId);
+  const data = await context.run('generate', () => workflow.generate());
+
+  return { success: true, agentId, data };
+});
+```
+
+**Files:**
+
+- `/api/workflows/agent-welcome/process-agents/route.ts`
+- `/api/workflows/agent-welcome/paginate-agents/route.ts`
+- `/api/workflows/agent-welcome/generate-agent/route.ts`
+- `/server/workflows/agentWelcome/index.ts`
+
+---
+
+## What's identical, what differs
+
+Both workflows are the **same pattern** — they only differ in:
+
+- Entity type (users vs agents)
+- Business logic (placeholder generation vs welcome generation)
+- Data source (different database queries)
+
+Everything else — the 3-layer split, dry-run handling, fan-out, filter-existing, flowControl tuning — is identical. That's the whole point: once you internalize the pattern, adding a new workflow is mostly entity-substitution.
@@ -0,0 +1,333 @@
+# Implementation Patterns
+
+Full code templates for the 3-layer architecture. Read this when actually writing workflow files.
+
+## Table of Contents
+
+1. [Workflow Class](#workflow-class) — `src/server/workflows/{workflowName}/index.ts`
+2. [Layer 1: Entry Point](#layer-1-entry-point-process-) — `process-*` route
+3. [Layer 2: Pagination](#layer-2-pagination-paginate-) — `paginate-*` route
+4. [Layer 3: Execution](#layer-3-execution-execute--generate-) — `execute-*` / `generate-*` route
+
+---
+
+## Workflow Class
+
+**Location:** `src/server/workflows/{workflowName}/index.ts`
+
+```typescript
+import { Client } from '@upstash/workflow';
+import debug from 'debug';
+
+const log = debug('lobe-server:workflows:{workflow-name}');
+
+// Workflow paths
+const WORKFLOW_PATHS = {
+  processItems: '/api/workflows/{workflow-name}/process-items',
+  paginateItems: '/api/workflows/{workflow-name}/paginate-items',
+  executeItem: '/api/workflows/{workflow-name}/execute-item',
+} as const;
+
+// Payload types
+export interface ProcessItemsPayload {
+  dryRun?: boolean;
+  force?: boolean;
+}
+
+export interface PaginateItemsPayload {
+  cursor?: string;
+  itemIds?: string[]; // For fanout chunks
+}
+
+export interface ExecuteItemPayload {
+  itemId: string;
+}
+
+const getWorkflowUrl = (path: string): string => {
+  const baseUrl = process.env.APP_URL;
+  if (!baseUrl) throw new Error('APP_URL is required to trigger workflows');
+  return new URL(path, baseUrl).toString();
+};
+
+const getWorkflowClient = (): Client => {
+  const token = process.env.QSTASH_TOKEN;
+  if (!token) throw new Error('QSTASH_TOKEN is required to trigger workflows');
+
+  const config: ConstructorParameters<typeof Client>[0] = { token };
+  if (process.env.QSTASH_URL) {
+    (config as Record<string, unknown>).url = process.env.QSTASH_URL;
+  }
+  return new Client(config);
+};
+
+export class {WorkflowName}Workflow {
+  private static client: Client;
+
+  private static getClient(): Client {
+    if (!this.client) this.client = getWorkflowClient();
+    return this.client;
+  }
+
+  static triggerProcessItems(payload: ProcessItemsPayload) {
+    const url = getWorkflowUrl(WORKFLOW_PATHS.processItems);
+    log('Triggering process-items workflow');
+    return this.getClient().trigger({ body: payload, url });
+  }
+
+  static triggerPaginateItems(payload: PaginateItemsPayload) {
+    const url = getWorkflowUrl(WORKFLOW_PATHS.paginateItems);
+    log('Triggering paginate-items workflow');
+    return this.getClient().trigger({ body: payload, url });
+  }
+
+  static triggerExecuteItem(payload: ExecuteItemPayload) {
+    const url = getWorkflowUrl(WORKFLOW_PATHS.executeItem);
+    log('Triggering execute-item workflow: %s', payload.itemId);
+    return this.getClient().trigger({ body: payload, url });
+  }
+
+  /**
+   * Filter items that need processing (e.g. check Redis cache, database state).
+   * Return only the ones that actually need work — keeps the pipeline idempotent.
+   */
+  static async filterItemsNeedingProcessing(itemIds: string[]): Promise<string[]> {
+    if (itemIds.length === 0) return [];
+    // Check existing state and return items that need processing
+    return itemIds;
+  }
+}
+```
+
+---
+
+## Layer 1: Entry Point (process-\*)
+
+**Purpose:** Validates prerequisites, calculates statistics, supports dry-run mode.
+
+```typescript
+import { serve } from '@upstash/workflow/nextjs';
+import { getServerDB } from '@/database/server';
+import { WorkflowClass, type ProcessPayload } from '@/server/workflows/{workflowName}';
+
+export const { POST } = serve<ProcessPayload>(
+  async (context) => {
+    const { dryRun, force } = context.requestPayload ?? {};
+
+    console.log('[{workflow}:process] Starting with payload:', { dryRun, force });
+
+    const allItemIds = await context.run('{workflow}:get-all-items', async () => {
+      const db = await getServerDB();
+      // Query database for eligible items
+      return items.map((item) => item.id);
+    });
+
+    console.log('[{workflow}:process] Total eligible items:', allItemIds.length);
+
+    if (allItemIds.length === 0) {
+      return { success: true, totalEligible: 0, message: 'No eligible items found' };
+    }
+
+    const itemsNeedingProcessing = await context.run('{workflow}:filter-existing', () =>
+      WorkflowClass.filterItemsNeedingProcessing(allItemIds),
+    );
+
+    const result = {
+      success: true,
+      totalEligible: allItemIds.length,
+      toProcess: itemsNeedingProcessing.length,
+      alreadyProcessed: allItemIds.length - itemsNeedingProcessing.length,
+    };
+
+    // Dry-run short-circuits before any side effects
+    if (dryRun) {
+      console.log('[{workflow}:process] Dry run mode, returning statistics only');
+      return {
+        ...result,
+        dryRun: true,
+        message: `[DryRun] Would process ${itemsNeedingProcessing.length} items`,
+      };
+    }
+
+    if (itemsNeedingProcessing.length === 0) {
+      return { ...result, message: 'All items already processed' };
+    }
+
+    await context.run('{workflow}:trigger-paginate', () => WorkflowClass.triggerPaginateItems({}));
+
+    return {
+      ...result,
+      message: `Triggered pagination for ${itemsNeedingProcessing.length} items`,
+    };
+  },
+  {
+    flowControl: {
+      key: '{workflow}.process',
+      parallelism: 1, // single instance — avoids duplicate processing
+      ratePerSecond: 1,
+    },
+  },
+);
+```
+
+---
+
+## Layer 2: Pagination (paginate-\*)
+
+**Purpose:** Handles cursor-based pagination, implements fan-out for large batches.
+
+```typescript
+import { serve } from '@upstash/workflow/nextjs';
+import { chunk } from 'es-toolkit/compat';
+import { getServerDB } from '@/database/server';
+import { WorkflowClass, type PaginatePayload } from '@/server/workflows/{workflowName}';
+
+const PAGE_SIZE = 50;
+const CHUNK_SIZE = 20;
+
+export const { POST } = serve<PaginatePayload>(
+  async (context) => {
+    const { cursor, itemIds: payloadItemIds } = context.requestPayload ?? {};
+
+    console.log('[{workflow}:paginate] Starting:', {
+      cursor,
+      itemIdsCount: payloadItemIds?.length ?? 0,
+    });
+
+    // If specific itemIds were passed in (from a fanout chunk), process them directly
+    if (payloadItemIds && payloadItemIds.length > 0) {
+      await Promise.all(
+        payloadItemIds.map((itemId) =>
+          context.run(`{workflow}:execute:${itemId}`, () =>
+            WorkflowClass.triggerExecuteItem({ itemId }),
+          ),
+        ),
+      );
+      return { success: true, processedItems: payloadItemIds.length };
+    }
+
+    // Paginate through all items
+    const itemBatch = await context.run('{workflow}:get-batch', async () => {
+      const db = await getServerDB();
+      const items = await db.query(...);
+      if (!items.length) return { ids: [] };
+      const last = items.at(-1);
+      return {
+        ids: items.map((item) => item.id),
+        cursor: last ? last.id : undefined,
+      };
+    });
+
+    const batchItemIds = itemBatch.ids;
+    const nextCursor = 'cursor' in itemBatch ? itemBatch.cursor : undefined;
+
+    if (batchItemIds.length === 0) {
+      return { success: true, message: 'Pagination complete' };
+    }
+
+    const itemIds = await context.run('{workflow}:filter-existing', () =>
+      WorkflowClass.filterItemsNeedingProcessing(batchItemIds),
+    );
+
+    if (itemIds.length > 0) {
+      if (itemIds.length > CHUNK_SIZE) {
+        // Fan out — recursively re-enter pagination with each chunk
+        const chunks = chunk(itemIds, CHUNK_SIZE);
+        console.log('[{workflow}:paginate] Fanout mode:', {
+          chunks: chunks.length,
+          chunkSize: CHUNK_SIZE,
+        });
+
+        await Promise.all(
+          chunks.map((ids, idx) =>
+            context.run(`{workflow}:fanout:${idx + 1}/${chunks.length}`, () =>
+              WorkflowClass.triggerPaginateItems({ itemIds: ids }),
+            ),
+          ),
+        );
+      } else {
+        // Process this page directly
+        await Promise.all(
+          itemIds.map((itemId) =>
+            context.run(`{workflow}:execute:${itemId}`, () =>
+              WorkflowClass.triggerExecuteItem({ itemId }),
+            ),
+          ),
+        );
+      }
+    }
+
+    // Tail-call into the next page
+    if (nextCursor) {
+      await context.run('{workflow}:next-page', () =>
+        WorkflowClass.triggerPaginateItems({ cursor: nextCursor }),
+      );
+    }
+
+    return {
+      success: true,
+      processedItems: itemIds.length,
+      skippedItems: batchItemIds.length - itemIds.length,
+      nextCursor: nextCursor ?? null,
+    };
+  },
+  {
+    flowControl: {
+      key: '{workflow}.paginate',
+      parallelism: 20,
+      ratePerSecond: 5,
+    },
+  },
+);
+```
+
+---
+
+## Layer 3: Execution (execute-\* / generate-\*)
+
+**Purpose:** Performs the actual business logic for exactly ONE item.
+
+```typescript
+import { serve } from '@upstash/workflow/nextjs';
+import { getServerDB } from '@/database/server';
+import { WorkflowClass, type ExecutePayload } from '@/server/workflows/{workflowName}';
+
+export const { POST } = serve<ExecutePayload>(
+  async (context) => {
+    const { itemId } = context.requestPayload ?? {};
+
+    if (!itemId) {
+      return { success: false, error: 'Missing itemId' };
+    }
+
+    const db = await getServerDB();
+
+    const item = await context.run('{workflow}:get-item', async () => {
+      // Query database for item
+      return item;
+    });
+
+    if (!item) {
+      return { success: false, error: 'Item not found' };
+    }
+
+    const result = await context.run('{workflow}:process-item', async () => {
+      const workflow = new WorkflowClass(db, itemId);
+      return workflow.generate(); // or process(), execute(), etc.
+    });
+
+    await context.run('{workflow}:save-result', async () => {
+      const workflow = new WorkflowClass(db, itemId);
+      return workflow.saveToRedis(result); // or saveToDatabase(), etc.
+    });
+
+    return { success: true, itemId, result };
+  },
+  {
+    flowControl: {
+      key: '{workflow}.execute',
+      parallelism: 10,
+      ratePerSecond: 5,
+    },
+  },
+);
+```
@@ -1,10 +1,14 @@
 ---
 name: version-release
-description: "Version release workflow. Use when the user mentions 'release', 'hotfix', 'version upgrade', 'weekly release', or '发版'/'发布'/'小班车'. This skill is for release process and GitHub Release notes (not docs/changelog page writing)."
+description: 'Version release workflow — release process and GitHub Release notes (not docs/changelog pages).'
+disable-model-invocation: true
+argument-hint: '[minor|patch] [version?]'
 ---

 # Version Release Workflow

+This skill is a router. The detailed steps live in `references/`.
+
 ## Scope Boundary (Important)

 This skill is only for:
@@ -28,68 +32,12 @@ The primary development branch is **canary**. All day-to-day development happens

 Only two release types are used in practice (major releases are extremely rare and can be ignored):

-| Type  | Use Case                                       | Frequency             | Source Branch  | PR Title Format                      | Version       |
-| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- |
-| Minor | Feature iteration release                      | \~Every 4 weeks       | canary         | `🚀 release: v{x.y.0}`               | Manually set  |
-| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 |
+| Type  | Use Case                                       | Frequency             | Source Branch  | PR Title Format                      | Version       | Reference                               |
+| ----- | ---------------------------------------------- | --------------------- | -------------- | ------------------------------------ | ------------- | --------------------------------------- |
+| Minor | Feature iteration release                      | \~Every 4 weeks       | canary         | `🚀 release: v{x.y.0}`               | Manually set  | `references/minor-release.md`           |
+| Patch | Weekly release / hotfix / model / DB migration | \~Weekly or as needed | canary or main | Custom (e.g. `🚀 release: 20260222`) | Auto patch +1 | `references/patch-release-scenarios.md` |

-## Minor Release Workflow
-
-Used to publish a new minor version (e.g. `v2.2.0`), roughly every 4 weeks.
-
-### Steps
-
-1. **Create a release branch from canary**
-
-```bash
-git checkout canary
-git pull origin canary
-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)
-
-3. **Create a PR to main**
-
-```bash
-gh pr create \
-  --title "🚀 release: v{version}" \
-  --base main \
-  --head release/v{version} \
-  --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.
-
-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
-
-```bash
-bun run release:branch         # Interactive
-bun run release:branch --minor # Directly specify minor
-```
-
-## Patch Release Workflow
-
-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             |
-| 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 |
-
-All scenarios auto-bump patch +1. Patch PR titles do not need a version number. See `reference/patch-release-scenarios.md` for detailed steps per scenario.
-
-### Scripts
-
-```bash
-bun run hotfix:branch # Hotfix scenario
-```
+For writing the release-note body (any release type), see `references/release-notes-style.md`.

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

@@ -127,7 +75,7 @@ PRs that don't match any conditions above (e.g. `docs`, `chore`, `ci`, `test`) w

 When the user requests a release:

-### Precheck
+### Precheck (applies to all release types)

 Before creating the release branch, verify the source branch:

@@ -135,184 +83,18 @@ Before creating the release branch, verify the source branch:
 - **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
+### Routing

-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
+Pick the right reference and follow it end-to-end:

-### Patch Release
+- **Minor release** → `references/minor-release.md`
+- **Patch release** (weekly / hotfix / model launch / DB migration) → `references/patch-release-scenarios.md`
+- **Writing the PR body / release notes** (any release type) → `references/release-notes-style.md`

-Choose workflow by scenario (see `reference/patch-release-scenarios.md`):
+### Hard Rules (apply to every release type)

- **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
-
-### Hard Rules
-
- **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
-
-## GitHub Release Changelog Standard (Long-Form Style)
-
-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.
-
-### Positioning
-
-This release-note style is:
-
-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)
-
-### 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
+- **Do NOT** manually modify `package.json` version — CI handles it.
+- **Do NOT** manually create tags — CI handles them.
+- Minor PR title format is strict (`🚀 release: v{x.y.z}`).
+- Patch PRs do not need an explicit version number.
+- Keep release facts accurate; do not invent metrics or availability statements. Release-note inputs (compare base, PR refs, contributor list) **must be derived from `git`** per `references/release-notes-style.md` § Computing Inputs — never from memory or descriptions.
@@ -1,4 +1,4 @@
-# 🚀 LobeHub v2.1.50 (20260416)
+# 🚀 LobeHub Release (20260416)

 **Release Date:** April 20, 2026\
 **Migration Scope:** Agent benchmark data model bootstrap (5 new tables, 2 new indexes)
@@ -7,14 +7,6 @@

 ---

-## ✨ Highlights
-
- **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.
-
---
-
 ## 🗄️ Migration Overview

 Added tables:
@@ -0,0 +1,21 @@
+# 🚀 LobeHub Release (20260427)
+
+**Hotfix Scope:** Agent topic-switching regression — stale chat state on agent change
+
+> Clears residual topic state when navigating between agents and restores blank-canvas behavior on agent switch.
+
+## 🐛 What's Fixed
+
+- **Stale topic on agent switch** — Switching from `/agent/agt_A/tpc_X` to `/agent/agt_B` no longer leaves the previous topic's messages on screen, and _Start new topic_ responds again. (#14231)
+- **Header & sidebar consistency** — Conversation header now shows the active subtopic's title, and the sidebar keeps the parent topic's thread list expanded while a thread is open.
+
+## ⚙️ Upgrade
+
+- Self-hosted: pull the new image and restart. No schema or env changes.
+- Cloud: applied automatically.
+
+## 👥 Owner
+
+@{pr-author}
+
+> **Note for Claude**: Replace `{pr-author}` with the actual PR author. Retrieve via `gh pr view <number> --json author --jq '.author.login'`. Do not hardcode a username.
@@ -1,7 +1,7 @@
-# 🚀 LobeHub v2.1.50 (20260420)
+# 🚀 LobeHub Release (20260420)

 **Release Date:** April 20, 2026\
-**Since v2026.04.13:** 96 commits · 58 merged PRs · 31 resolved issues · 17 contributors
+**Since previous release:** 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.

@@ -77,4 +77,4 @@

 ---

-**Full Changelog**: v2026.04.13...v2026.04.20
+**Full Changelog**: <previous-tag>...<current-tag>
@@ -0,0 +1,47 @@
+# Minor Release Workflow
+
+Used to publish a new minor version (e.g. `v2.2.0`), roughly every 4 weeks. The PR title carries the exact version number; CI parses it to drive the rest of the release.
+
+## Steps
+
+1. **Create a release branch from canary**
+
+   ```bash
+   git checkout canary
+   git pull origin canary
+   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`).
+
+3. **Create a PR to main**
+
+   ```bash
+   gh pr create \
+     --title "🚀 release: v{version}" \
+     --base main \
+     --head release/v{version} \
+     --body-file release_body.md
+   ```
+
+   > \[!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. **Write the PR body as release notes** — Follow `release-notes-style.md`. Compare base is the latest semver tag on main (`git describe --tags --abbrev=0 origin/main`).
+
+5. **Automatic trigger after merge** — `auto-tag-release` detects the title format, uses the version number from the title, bumps `package.json`, tags `v{x.y.z}`, creates the GitHub Release, and dispatches `sync-main-to-canary`.
+
+## Scripts
+
+```bash
+bun run release:branch         # Interactive
+bun run release:branch --minor # Directly specify minor
+```
+
+## Hard Rules (specific to Minor)
+
+- PR title format is **strict**: `🚀 release: v{x.y.z}`. Any deviation falls through to patch detection.
+- Do **NOT** manually modify `package.json` version — CI will bump it.
+- Do **NOT** manually create the tag — CI will tag.
+- Highlights bullet count is usually 8–12 (see `release-notes-style.md` size heuristics).
@@ -21,12 +21,16 @@ git push -u origin release/weekly-{YYYYMMDD}

 2. **Scan changes and write changelog**

+Compute the previous tag from main first — never reuse the last weekly's tag, since hotfixes published in between will be missed:
+
 ```bash
-git log main..canary --oneline
-git diff main...canary --stat
+git fetch origin main canary --tags
+PREV_TAG=$(git describe --tags --abbrev=0 origin/main --match 'v*.*.*' --exclude '*-canary*' --exclude '*-nightly*')
+git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" --oneline --no-merges
+git diff "$PREV_TAG...origin/release/weekly-{YYYYMMDD}" --stat
 ```

-Write a user-facing changelog following the format in `patch-release-changelog-example.md`.
+Then follow `./release-notes-style.md` § **Computing Inputs (Hard Rules)** to derive PR refs, metrics, and contributors. Every `(#XXXX)` in the body must come from actual commit subjects in this range — never inferred from descriptions.

 3. **Create PR to main** with the changelog as the PR body

@@ -59,7 +63,10 @@ git push -u origin hotfix/v{version}-{short-hash}

 2. **Create PR to main** with a gitmoji prefix title (e.g. `🐛 fix: description`)

-3. **After merge**: auto-tag-release detects `hotfix/*` branch → auto patch +1.
+3. **Write a short hotfix changelog** — See `changelog-example/hotfix.md`. Keep it minimal: scope line, 1-3 fix bullets (symptom + fix in one sentence), upgrade note, owner. No long root-cause section — that lives in the commit message.
+   - **Hotfix owner**: Use the actual PR author (retrieve via `gh pr view <number> --json author --jq '.author.login'`), never hardcode a username.
+
+4. **After merge**: auto-tag-release detects `hotfix/*` branch → auto patch +1.

 ### Script

@@ -0,0 +1,330 @@
+# GitHub Release Changelog Standard (Long-Form Style)
+
+Use this guide for **GitHub Release notes** — the body of a release PR that becomes the GitHub Release after merge. Do **not** use it for `docs/changelog/*.mdx` website pages (load `../../docs-changelog/SKILL.md` instead).
+
+## Table of Contents
+
+1. [Positioning](#positioning) — what this style optimizes for
+2. [Required Inputs Before Writing](#required-inputs-before-writing)
+3. [Computing Inputs (Hard Rules — Verify, Never Guess)](#computing-inputs-hard-rules--verify-never-guess) — base ref, PR refs, metrics, authors, pre-publish verification
+4. [Canonical Structure (Long-Form: Minor / Weekly)](#canonical-structure-long-form-minor--weekly)
+5. [Variants for Shorter Releases](#variants-for-shorter-releases) — hotfix, DB migration
+6. [Writing Rules (Hard)](#writing-rules-hard)
+7. [Style Rules (Long-Form)](#style-rules-long-form)
+8. [Release Size Heuristics](#release-size-heuristics) — when to use which variant
+9. [Contributor Ordering](#contributor-ordering)
+10. [Template](#template) — copy-paste skeleton
+11. [Quick Checklist](#quick-checklist) — long-form + hotfix
+
+## Positioning
+
+This release-note style is:
+
+1. **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)
+
+## 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.
+
+## Computing Inputs (Hard Rules — Verify, Never Guess)
+
+> Hallucinated PR numbers and wrong "Since v..." bases are the #1 failure mode of this skill. Every number and every `(#XXXX)` must come from `git`, never from memory or inference.
+
+### 1. Compare base = latest semver tag on `main`
+
+Do **not** eyeball the tag list or pick the "last weekly" PR. Compute it:
+
+```bash
+git fetch origin main canary --tags
+PREV_TAG=$(git describe --tags --abbrev=0 origin/main --match 'v*.*.*' --exclude '*-canary*' --exclude '*-nightly*')
+echo "$PREV_TAG"
+```
+
+Sanity check that the tag is reachable from the release branch:
+
+```bash
+git merge-base --is-ancestor "$PREV_TAG" origin/release/weekly-{YYYYMMDD} && echo OK
+```
+
+If the check fails, stop and ask the user — the release branch is based on the wrong source.
+
+> **Why not "the last weekly release PR"?** Hotfixes (`v2.1.54`, `v2.1.55`, …) merge directly into main between weeklies. They get back-merged via `sync-main-to-canary`, so the latest semver tag on main _is_ the correct previous release for both weekly and minor flows. Picking the previous weekly's tag will silently undercount and put a stale version in "Since v…".
+
+### 2. PR refs must come from commit subjects — never from descriptions
+
+Compute the canonical set:
+
+```bash
+git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" \
+  --pretty=format:'%s' --no-merges \
+  | grep -oE '\(#[0-9]+\)$' \
+  | sort -u > /tmp/release_prs.txt
+```
+
+Hard rules:
+
+- Every `(#XXXX)` you write in the body **must** appear in `/tmp/release_prs.txt`. No exceptions.
+- Never infer a PR number from a feature description. If you remember "the KB BM25 PR was around #14501", that memory is wrong about half the time. Look up the commit hash by feature keyword and read its actual subject.
+- If your terminal truncates long subjects (any wrapper that compresses output, e.g. `rtk`), bypass it. With `rtk` use `rtk proxy git log …`. Verify with `wc -l /tmp/release_prs.txt` — the count must match `git log $PREV_TAG..HEAD --no-merges --pretty=format:'%h' | wc -l` minus the few commits without a PR ref. A mismatch of >5% means subjects are being silently truncated.
+
+### 3. Metrics must come from git counts
+
+```bash
+PR_COUNT=$(wc -l < /tmp/release_prs.txt | tr -d ' ')
+
+COMMIT_COUNT=$(git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" --no-merges --pretty=format:'%h' | wc -l | tr -d ' ')
+
+CONTRIBUTOR_COUNT=$(git log "$PREV_TAG..origin/release/weekly-{YYYYMMDD}" --no-merges --pretty=format:'%an' \
+  | sort -u \
+  | grep -viE '^(lobehubbot|LobeHub Bot|renovate\[bot\])$' \
+  | wc -l | tr -d ' ')
+```
+
+If a number cannot be confidently derived, omit it — never guess.
+
+### 4. Author-to-handle resolution
+
+Git `%an` is the commit author display name, not the GitHub handle. For each author you mention, confirm the handle:
+
+```bash
+gh pr view "$PR_NUMBER" --repo lobehub/lobe-chat --json author --jq '.author.login'
+```
+
+Use the result for `@handle`. Then classify each author per the `LobeHub team roster` below; community first, team after.
+
+### 5. Pre-publish verification (mandatory)
+
+Before `gh pr create` / `gh pr edit --body-file`, diff body PR refs against the canonical set:
+
+```bash
+grep -oE '#[0-9]+' release_body.md | sort -u > /tmp/body_prs.txt
+sed 's/[()]//g' /tmp/release_prs.txt > /tmp/release_prs_clean.txt
+
+echo "=== In body but NOT in actual range (must be EMPTY) ==="
+comm -23 /tmp/body_prs.txt /tmp/release_prs_clean.txt
+```
+
+Empty diff = OK. Any output = the body cites a PR that wasn't merged in this range. Stop and fix before publishing.
+
+Also verify the metrics line in the body matches the computed values (`PR_COUNT`, `CONTRIBUTOR_COUNT`) and that `**Full Changelog**` uses `$PREV_TAG`, not some older tag.
+
+## Canonical Structure (Long-Form: Minor / Weekly)
+
+Follow this section order for **Minor** and **Weekly** releases unless the user asks otherwise. For **Hotfix** and **DB Migration**, see § Variants for Shorter Releases below — the canonical structure does not apply.
+
+1. `# 🚀 LobeHub Release (<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.
+
+## Variants for Shorter Releases
+
+The Canonical Structure above is for **long-form** (Minor / Weekly). Two short-form variants override it.
+
+### Hotfix Variant
+
+A hotfix targets one regression and ships fast. The body is short and operator-focused — no Highlights, no domain blocks, no Contributors line.
+
+Required sections, in order:
+
+1. `# 🚀 LobeHub Release (<YYYYMMDD>)`
+2. `**Hotfix Scope:**` — one line summarizing the regression scope (e.g. `Agent topic-switching regression — stale chat state on agent change`). Replaces the long-form `Release Date` / `Since vX.Y.Z` metrics.
+3. One quoted thesis (single paragraph, 1-2 lines) describing what is now restored.
+4. `## 🐛 What's Fixed` — 1-3 bullets, each `**<symptom>** — <fix in one sentence>. (#PR)`. No root-cause prose; that lives in the commit message.
+5. `## ⚙️ Upgrade` — short notes for self-hosted (pull image / restart, schema or env changes) and cloud (usually "applied automatically").
+6. `## 👥 Owner` — single `@handle` for the PR author, resolved via `gh pr view "$PR" --json author --jq '.author.login'`. Never hardcoded.
+
+Hard rules specific to hotfix:
+
+- **No Highlights / domain blocks / Contributors / Full Changelog** — these add noise to a one-shot fix.
+- **No metric line** — `Since vX.Y.Z` doesn't apply; the body cites the single PR (or 1-3 PRs) directly.
+- **Owner ≠ Contributors** — one author, listed under § Owner. Not a flat handle list.
+- See `changelog-example/hotfix.md` for the canonical template.
+
+### DB Migration Variant
+
+Database schema changes that need to be released independently. Operator impact is the headline.
+
+Required sections, in order:
+
+1. `# 🚀 LobeHub Release (<YYYYMMDD>)` + scope line
+2. **Migration overview** — what tables / columns are added, modified, or removed
+3. **Operator impact** — backwards-compatible? required actions for self-hosted?
+4. **Rollback / backup note** — how to recover
+5. `## 👥 Owner` — single PR author, resolved via `gh pr view`
+
+See `changelog-example/db-migration.md` for the canonical template.
+
+## 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**
+  - Long-form structure with multiple domain blocks.
+  - `Highlights` usually 8-12 bullets.
+- **Weekly patch release**
+  - Long-form skeleton with reduced subsection count.
+  - `Highlights` usually 4-8 bullets.
+- **Hotfix release**
+  - Short-form (see § Variants → Hotfix). No Highlights, no domain blocks, no Contributors.
+  - 1-3 fix bullets. Body should fit on one screen.
+- **DB migration release**
+  - Short-form (see § Variants → DB Migration).
+  - Must include `Migration overview`, operator impact, and rollback/backup note.
+
+## Contributor Ordering
+
+Render contributors as a **single flat list** (no separate "Community" / "Core Team" subsections). Order: **community contributors first, team members after**. Within each group, sort by PR count desc. Bots (`@lobehubbot`, `renovate[bot]`) go on a separate "maintenance" line.
+
+**LobeHub team roster** — anyone in this list is a team member; anyone not in this list is a community contributor:
+
+- @arvinxx
+- @Innei
+- @tjx666 (commit author name: YuTengjing)
+- @LiJian
+- @Neko
+- @Rdmclin2
+- @AmAzing129
+- @sudongyuer (commit author name: Tsuki)
+- @rivertwilight (commit author name: René Wang)
+- @CanisMinor
+- @cy948 (commit author name: Rylan Cai)
+
+> **Resolving handles** — git author names (e.g. `YuTengjing`) are not always the GitHub handle. Verify via `gh pr view "$PR" --json author` or `gh api search/users -f q='<email>'` before listing.
+
+If a new contributor appears who is not on this list, treat them as community by default and ask the user whether to add them to the roster.
+
+## Template
+
+```md
+# 🚀 LobeHub Release (<YYYYMMDD>)
+
+**Release Date:** <Month DD, YYYY>  
+**Since <Previous Version>:** <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
+
+Huge thanks to **<N contributors>** who shipped **<N merged PRs>** this cycle.
+
+@<community-handle> · @<community-handle> · @<team-handle> · @<team-handle>
+
+Plus @lobehubbot and renovate[bot] for maintenance.
+
+---
+
+**Full Changelog**: <previous_tag>...<current_tag>
+```
+
+## Quick Checklist
+
+### Long-Form (Minor / Weekly)
+
+- [ ] `PREV_TAG` is `git describe --tags --abbrev=0 origin/main` (latest semver), not the last weekly's tag
+- [ ] Every `(#XXXX)` in the body appears in `/tmp/release_prs.txt` (verified via `comm -23`)
+- [ ] `Since v…` line uses `$PREV_TAG`; PR / contributor counts match `wc -l` on the computed sets
+- [ ] `**Full Changelog**` uses `$PREV_TAG...release/weekly-<YYYYMMDD>` (or `…v{x.y.z}` for minor)
+- [ ] Author handles resolved via `gh pr view --json author`, not assumed from `%an`
+- [ ] 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
+
+### Hotfix
+
+- [ ] `**Hotfix Scope:**` line replaces metrics line
+- [ ] Single quoted thesis describes what is restored (operator-facing, not internal)
+- [ ] `## 🐛 What's Fixed` has 1-3 bullets, each `**<symptom>** — <fix>. (#PR)` with PR ref verified to exist and be merged
+- [ ] `## ⚙️ Upgrade` notes self-hosted action and cloud auto-apply
+- [ ] `## 👥 Owner` is a single `@handle` resolved via `gh pr view "$PR" --json author`
+- [ ] No Highlights / domain blocks / Contributors / Full Changelog included
@@ -1,6 +1,7 @@
 ---
 name: zustand
-description: Zustand state management guide. Use when working with store code (src/store/**), implementing actions, managing state, or creating slices. Triggers on Zustand store development, state management questions, or action implementation.
+description: "LobeHub Zustand store conventions: public/internal/dispatch action layers, optimistic update pattern, slice composition via `flattenActions`, and class-based action migration. Use whenever working under `src/store/**`, adding a `createXxxSlice`, writing `internal_*` or `internal_dispatch*` actions, designing `messagesMap`/`topicsMap` reducers, refactoring a `StateCreator` object slice into a `XxxActionImpl` class, or debugging stale store reads. Triggers on `useChatStore`/`useUserStore`/`useGlobalStore`, `createStore`, `flattenActions`, `StoreSetter`, `internal_dispatch`, 'add an action', 'zustand selector', 'store slice', 'class action', 'optimistic update'."
+user-invocable: false
 ---

 # LobeHub Zustand State Management
@@ -174,9 +175,64 @@ export const chatGroupAction: StateCreator<
  - `ChatGroupStoreWithRefresh` for member refresh
  - `ChatGroupStoreWithInternal` for curd `internal_dispatchChatGroup`

+### Slices That Don't Currently Need `set`
+
+When a slice doesn't write local state at the moment — e.g. it reads context
+from `#get()` and forwards calls to another store, or just runs hooks — drop
+the `#set` field. Otherwise ESLint's `no-unused-vars` flags the unused private
+field.
+
+Mark the constructor's `set` param as `_set` and `void _set` it to keep the
+`(set, get, api)` shape aligned with `StateCreator`. This is **a snapshot of
+the current need, not a permanent contract** — if a later change needs `set`,
+restore the `#set` field and use it; do not invent a workaround to keep the
+"unused" form.
+
+```ts
+type Setter = StoreSetter<ConversationStore>;
+
+export const toolSlice = (set: Setter, get: () => ConversationStore, _api?: unknown) =>
+  new ToolActionImpl(set, get, _api);
+
+export class ToolActionImpl {
+  readonly #get: () => ConversationStore;
+
+  // Mark unused params with `_` prefix and `void _x` so the constructor still
+  // matches StateCreator's `(set, get, api)` shape without triggering unused
+  // diagnostics.
+  constructor(_set: Setter, get: () => ConversationStore, _api?: unknown) {
+    void _set;
+    void _api;
+    this.#get = get;
+  }
+
+  approveToolCall = async (id: string) => {
+    const { context, hooks } = this.#get();
+    await useChatStore.getState().approveToolCalling(id, '', context);
+    hooks.onToolCallComplete?.(id, undefined);
+  };
+}
+
+export type ToolAction = Pick<ToolActionImpl, keyof ToolActionImpl>;
+```
+
+Rules of thumb:
+
+- If a slice doesn't currently call `set`, drop `#set` (use `_set` + `void _set`
+  in the constructor). When a later edit needs `set`, restore `#set` and use it.
+- Don't add `setNamespace` for slices that don't write state. Add it when the
+  slice starts writing state.
+- Never leave `#set` declared but unused "for future use" — lint will fail and
+  re-adding it later costs nothing.
+
 ### Do / Don't

 - **Do**: keep constructor signature aligned with `StateCreator` params `(set, get, api)`.
 - **Do**: use `#private` to avoid `set/get` being exposed.
 - **Do**: use `flattenActions` instead of spreading class instances.
+- **Do**: drop `#set` (and use `_set` + `void _set` in the constructor) for
+  delegate-only slices that never write state — keeps lint green without
+  breaking the `(set, get, api)` shape.
 - **Don't**: keep both old slice objects and class actions active at the same time.
+- **Don't**: keep an unused `#set` field "for future use" — it fails ESLint and
+  re-adding it later costs nothing.
@@ -1,6 +1,10 @@
 # Issue Triage Guide

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

 ## Workflow

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

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

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

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

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

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

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

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

 - `openai`, `gpt` → `provider:openai`
 - `gemini` → `provider:gemini`
@@ -57,197 +114,100 @@ Extract information from the issue template and content:
 **Third-party Aggregation Providers**:

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

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

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

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

 ### Step 4: Apply Labels

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

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

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

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

 ## Important Rules

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

 ## Quick Reference by Name

- **@arvinxx**: Last resort only, mention for priority:high issues, tool calling, mcp, database
+- **@arvinxx**: General/uncategorized issues (default assignee), 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, database
- **@ONLY-yours**: Performance, streaming, settings, general bugs, web platform, marketplace, agent builder, schedule task
+- **@tjx666**: Model providers and configuration, new model additions, image/video generation, vision, cloud version, documentation, TTS, auth, login/register, database
+- **@ONLY-yours**: Performance, streaming, settings, 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, IM and bot integration
 - **@tcmonster**: Subscription, refund, recharge, business cooperation

@@ -21,7 +20,7 @@ Quick reference for assigning issues based on labels.

 | Label            | Owner   | Notes                                        |
 | ---------------- | ------- | -------------------------------------------- |
-| All `provider:*` | @sxjeru | Model configuration and provider integration |
+| All `provider:*` | @tjx666 | Model configuration and provider integration |

 ### Platform Labels (platform:\*)

@@ -100,11 +99,10 @@ Quick reference for assigning issues based on labels.

 1. **Specific feature owner** - e.g., `feature:knowledge-base` → @RiverTwilight
 2. **Platform owner** - e.g., `platform:mobile` → @sudongyuer
-3. **Provider owner** - e.g., `provider:*` → @sxjeru
+3. **Provider owner** - e.g., `provider:*` → @tjx666
 4. **Component owner** - e.g., 💄 Design → @canisminor1990
 5. **Infrastructure owner** - e.g., `deployment:*` → @nekomeowww
-6. **General maintainer** - @ONLY-yours for general bugs/issues
-7. **Last resort** - @arvinxx (only if no clear owner)
+6. **Default assignee** - @arvinxx for general/uncategorized issues

 ### Special Cases

@@ -121,8 +119,7 @@ Quick reference for assigning issues based on labels.

 **No clear owner:**

- Assign to @ONLY-yours for general issues
- Only mention @arvinxx if critical and truly unclear
+- Assign to @arvinxx for general issues

 ## Comment Templates

@@ -56,7 +56,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # add your custom model name, multi model separate by comma. for example gpt-3.5-1106,gpt-4-1106
 # OPENAI_MODEL_LIST=gpt-3.5-turbo

-
 # ## Azure OpenAI ###

 # you can learn azure OpenAI Service on https://learn.microsoft.com/en-us/azure/ai-services/openai/overview
@@ -71,7 +70,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # Azure's API version, follows the YYYY-MM-DD format
 # AZURE_API_VERSION=2024-10-21

-
 # ## Anthropic Service ####

 # ANTHROPIC_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -79,19 +77,19 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # use a proxy to connect to the Anthropic API
 # ANTHROPIC_PROXY_URL=https://api.anthropic.com

+# Anthropic SDK client timeout in milliseconds
+# ANTHROPIC_CLIENT_TIMEOUT=295000

 # ## Google AI  ####

 # GOOGLE_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

-
 # ## AWS Bedrock  ###

 # AWS_REGION=us-east-1
 # AWS_ACCESS_KEY_ID=xxxxxxxxxxxxxxxxxxx
 # AWS_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

-
 # ## Ollama AI ####

 # You can use ollama to get and run LLM locally, learn more about it via https://github.com/ollama/ollama
@@ -101,13 +99,11 @@ OPENAI_API_KEY=sk-xxxxxxxxx

 # OLLAMA_MODEL_LIST=your_ollama_model_names

-
 # ## OpenRouter Service ###

 # OPENROUTER_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 # OPENROUTER_MODEL_LIST=model1,model2,model3

-
 # ## Mistral AI ###

 # MISTRAL_API_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -168,7 +164,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx

 # SILICONCLOUD_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

-
 # ## TencentCloud AI  ####

 # TENCENT_CLOUD_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -181,7 +176,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx

 # INFINIAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

-
 # ## 302.AI ###

 # AI302_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@@ -222,7 +216,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx

 # VERCELAIGATEWAY_API_KEY=your_vercel_ai_gateway_api_key

-
 # #######################################
 # ########### Market Service ############
 # #######################################
@@ -283,7 +276,6 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # but some service providers may require configuration
 # S3_REGION=us-west-1

-
 # #######################################
 # ########### Auth Service ##############
 # #######################################
@@ -424,3 +416,23 @@ OPENAI_API_KEY=sk-xxxxxxxxx
 # MESSAGE_GATEWAY_ENABLED=1
 # MESSAGE_GATEWAY_URL=https://message-gateway.lobehub.com
 # MESSAGE_GATEWAY_SERVICE_TOKEN=your_service_token_here
+
+# #######################################
+# ########### Messenger Bot #############
+# #######################################
+
+# LobeHub-operated bots that users link their account to once and then chat
+# with any of their agents from. Credentials (Telegram / Slack / Discord) are
+# now managed in dc-center → Agent → System Bots and stored in the
+# `system_bot_providers` table. See docs/development/messenger/managed-by-dc-center.md.
+#
+# Webhook URLs are registered against APP_URL:
+#   Telegram: <APP_URL>/api/agent/messenger/webhooks/telegram
+#   Slack:    <APP_URL>/api/agent/messenger/webhooks/slack
+#   Discord:  <APP_URL>/api/agent/messenger/webhooks/discord
+#
+# For local dev with bot platforms, point APP_URL at your tunnel
+# (ngrok / cloudflared) so platforms can reach your machine.
+
+# Verify-im link token TTL in seconds (default 1800 = 30 min)
+# LOBE_LINK_TOKEN_TTL_SECONDS=1800
@@ -1,5 +1,13 @@
+#!/usr/bin/env sh
+set -e
+
+[ "${HUSKY-}" = "0" ] && exit 0
+
+export PATH="node_modules/.bin:$PATH"
+
 BRANCH=$(git branch --show-current)
 if [ "$BRANCH" = "dev" ] || [ "$BRANCH" = "main" ]; then
  npm run type-check
 fi
-npx --no-install lint-staged
+
+lint-staged
@@ -10,6 +10,10 @@ inputs:
    description: Pass-through to actions/setup-node package-manager-cache
    required: false
    default: 'false'
+  bun-version:
+    description: Bun version
+    required: false
+    default: '1.3.2'

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

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

    - name: Setup Node.js
      uses: actions/setup-node@v6
@@ -21,6 +21,46 @@ jobs:
      - name: Checkout repository
        uses: actions/checkout@v6

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

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

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

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

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

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

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

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

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

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

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

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

      - name: Setup environment
        uses: ./.github/actions/setup-env
@@ -28,6 +28,9 @@ prd
 # Recordings
 .records/

+# Agent-gateway probe captures (local debugging dumps)
+.agent-gateway/
+
 # Temporary files
 .temp/
 temp/
@@ -96,7 +99,7 @@ sitemap*.xml
 robots.txt

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

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

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

 # AI coding tools
 .local/
@@ -146,4 +150,8 @@ apps/desktop/resources/cli-package.json

 # Superpowers plugin brainstorm/spec outputs (local only; do not commit)
 .superpowers/
+docs/superpowers/
 .heerogeneous-tracing
+
+# Kagura agent runtime
+.kagura/
@@ -27,7 +27,7 @@ module.exports = defineConfig({
  ],
  temperature: 0,
  saveImmediately: true,
-  modelName: 'gpt-5.1-chat-latest',
+  modelName: 'gpt-4o',
  experimental: {
    jsonMode: true,
  },
@@ -8,7 +8,7 @@
 .history
 .temp
 .env.local
-.husky
+.githooks
 .npmrc
 .gitkeep
 venv
@@ -59,4 +59,4 @@ Dockerfile*

 # misc
 # add other ignore file below
-.next
+.next
@@ -1,100 +1,128 @@
 # 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
- **Protection of local changes**: Never use `git restore`, `git checkout --`, `git reset --hard`, or any other command or workflow that can forcibly overwrite, discard, or silently replace user-owned uncommitted changes. Before any revert or restoration affecting existing files, inspect the working tree carefully and obtain explicit user confirmation.
+- 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
+- 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/`
+- `pnpm i18n` is slow; run it manually when locale keys need updating (e.g. before opening a PR).

-## SPA Routes and Features
+### Code Review

- **`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.
- **Desktop router parity:** When changing the main SPA route tree, update **both** `src/spa/router/desktopRouter.config.tsx` (dynamic imports) and `src/spa/router/desktopRouter.config.desktop.tsx` (sync imports) so paths and nesting match. Changing only one can leave routes unregistered and cause **blank screens**.
- See the **spa-routes** skill (`.agents/skills/spa-routes/SKILL.md`) 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.
+Before reviewing a PR / diff / branch change, read the **review-checklist** skill (`.agents/skills/review-checklist/SKILL.md`) — it lists the recurring mistakes specific to this codebase.
@@ -2,6 +2,379 @@

 # Changelog

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

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

 # LobeHub

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

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

@@ -25,7 +27,6 @@ We’re building the world’s largest human–agent co-evolving network.
 [![][github-stars-shield]][github-stars-link]
 [![][github-issues-shield]][github-issues-link]
 [![][github-license-shield]][github-license-link]<br>
-[![][sponsor-shield]][sponsor-link]

 **Share LobeHub Repository**

@@ -37,9 +38,9 @@ We’re building the world’s largest human–agent co-evolving network.
 [![][share-mastodon-shield]][share-mastodon-link]
 [![][share-linkedin-shield]][share-linkedin-link]

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

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

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

@@ -52,30 +53,10 @@ We’re building the world’s largest human–agent co-evolving network.

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

 <br/>

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

 ## 👋🏻 Getting Started & Join Our Community

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

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

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

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

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

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

 ### Create: Agents as the Unit of Work

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

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

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

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

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

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

 <div align="right">

@@ -289,277 +187,6 @@ LobeHub supports file upload and knowledge base functionality. You can upload va

 </div>

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

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

 # LobeHub

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

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

@@ -24,7 +27,6 @@ LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您
 [![][github-stars-shield]][github-stars-link]
 [![][github-issues-shield]][github-issues-link]
 [![][github-license-shield]][github-license-link]<br>
-[![][sponsor-shield]][sponsor-link]

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

@@ -35,9 +37,9 @@ LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您
 [![][share-weibo-shield]][share-weibo-link]
 [![][share-mastodon-shield]][share-mastodon-link]

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

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

 </div>
@@ -49,30 +51,10 @@ LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您

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

 <br/>

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

 ## 👋🏻 开始使用 & 交流

@@ -102,9 +84,9 @@ LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您

 不论普通用户与专业开发者，LobeHub 旨在成为所有人的 AI Agent 实验场。LobeHub 目前正在积极开发中，有任何需求或者问题，欢迎提交 [issues][issues-link]

-| [![](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1065874&theme=light&t=1769347414733)](https://www.producthunt.com/products/lobehub?embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-lobehub) | 我们已在 Product Hunt 上线！我们很高兴将 LobeHub 推向世界。如果您相信人类与 Agent 共同进化的未来，请支持我们的旅程。 |
-| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------- |
-| [![][discord-shield-badge]][discord-link]                                                                                                                                                                                                         | 加入我们的 Discord 社区！这是你可以与开发者和其他 LobeHub 热衷用户交流的地方                                         |
+| [![](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=1065874&theme=light&t=1769347414733)](https://www.producthunt.com/products/lobehub?launch=lobehub-2&embed=true&utm_source=badge-featured&utm_medium=badge&utm_campaign=badge-lobehub) | 我们已在 Product Hunt 上线！我们很高兴将 LobeHub 推向世界。如果您相信人类与 Agent 共同进化的未来，请支持我们的旅程。 |
+| :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------- |
+| [![][discord-shield-badge]][discord-link]                                                                                                                                                                                                                          | 加入我们的 Discord 社区！这是你可以与开发者和其他 LobeHub 热衷用户交流的地方                                         |

 > \[!IMPORTANT]
 >
@@ -127,7 +109,26 @@ LobeHub 是一个工作与生活空间，用于发现、构建并与会随着您

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

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

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

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

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

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

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

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

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

 <div align="right">

@@ -278,262 +185,6 @@ LobeHub 支持文件上传与知识库功能，你可以上传文件、图片、

 </div>

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

 <div align="right">
@@ -867,28 +518,10 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [docs-dev-guide]: https://lobehub.com/docs/development/start
 [docs-docker]: https://lobehub.com/zh/docs/self-hosting/server-database/docker-compose
 [docs-env-var]: https://lobehub.com/docs/self-hosting/environment-variables
-[docs-feat-agent]: https://lobehub.com/docs/usage/features/agent-market
-[docs-feat-artifacts]: https://lobehub.com/docs/usage/features/artifacts
-[docs-feat-auth]: https://lobehub.com/docs/usage/features/auth
-[docs-feat-branch]: https://lobehub.com/docs/usage/features/branching-conversations
-[docs-feat-cot]: https://lobehub.com/docs/usage/features/cot
-[docs-feat-database]: https://lobehub.com/docs/usage/features/database
-[docs-feat-knowledgebase]: https://lobehub.com/blog/knowledge-base
-[docs-feat-local]: https://lobehub.com/docs/usage/features/local-llm
-[docs-feat-mobile]: https://lobehub.com/docs/usage/features/mobile
-[docs-feat-plugin]: https://lobehub.com/docs/usage/features/plugin-system
-[docs-feat-provider]: https://lobehub.com/docs/usage/features/multi-ai-providers
-[docs-feat-pwa]: https://lobehub.com/docs/usage/features/pwa
-[docs-feat-t2i]: https://lobehub.com/docs/usage/features/text-to-image
-[docs-feat-theme]: https://lobehub.com/docs/usage/features/theme
-[docs-feat-tts]: https://lobehub.com/docs/usage/features/tts
-[docs-feat-vision]: https://lobehub.com/docs/usage/features/vision
 [docs-function-call]: https://lobehub.com/zh/blog/openai-function-call
 [docs-plugin-dev]: https://lobehub.com/docs/usage/plugins/development
 [docs-self-hosting]: https://lobehub.com/docs/self-hosting/start
 [docs-upstream-sync]: https://lobehub.com/docs/self-hosting/advanced/upstream-sync
-[docs-usage-ollama]: https://lobehub.com/docs/usage/providers/ollama
-[docs-usage-plugin]: https://lobehub.com/docs/usage/plugins/basic
 [fossa-license-link]: https://app.fossa.com/projects/git%2Bgithub.com%2Flobehub%2Flobehub
 [fossa-license-shield]: https://app.fossa.com/api/projects/git%2Bgithub.com%2Flobehub%2Flobehub.svg?type=large
 [github-action-release-link]: https://github.com/lobehub/lobehub/actions/workflows/release.yml
@@ -911,29 +544,8 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [github-releasedate-link]: https://github.com/lobehub/lobehub/releases
 [github-releasedate-shield]: https://img.shields.io/github/release-date/lobehub/lobehub?labelColor=black&style=flat-square
 [github-stars-link]: https://github.com/lobehub/lobehub/stargazers
-[github-stars-shield]: https://github.com/user-attachments/assets/3216e25b-186f-4a54-9cb4-2f124aec0471
-[github-trending-shield]: https://trendshift.io/api/badge/repositories/2256
-[github-trending-url]: https://trendshift.io/repositories/2256
-[image-banner]: https://github.com/user-attachments/assets/0fe626a3-0ddc-4f67-b595-3c5b3f1701e0
-[image-feat-agent]: https://github.com/user-attachments/assets/b3ab6e35-4fbc-468d-af10-e3e0c687350f
-[image-feat-artifacts]: https://github.com/user-attachments/assets/7f95fad6-b210-4e6e-84a0-7f39e96f3a00
-[image-feat-auth]: https://github.com/user-attachments/assets/80bb232e-19d1-4f97-98d6-e291f3585e6d
-[image-feat-branch]: https://github.com/user-attachments/assets/92f72082-02bd-4835-9c54-b089aad7fd41
-[image-feat-cot]: https://github.com/user-attachments/assets/f74f1139-d115-4e9c-8c43-040a53797a5e
-[image-feat-database]: https://github.com/user-attachments/assets/f1697c8b-d1fb-4dac-ba05-153c6295d91d
-[image-feat-desktop]: https://github.com/user-attachments/assets/a7bac8d3-ea96-4000-bb39-fadc9b610f96
-[image-feat-knowledgebase]: https://github.com/user-attachments/assets/7da7a3b2-92fd-4630-9f4e-8560c74955ae
-[image-feat-local]: https://github.com/user-attachments/assets/1239da50-d832-4632-a7ef-bd754c0f3850
-[image-feat-mcp-market]: https://github.com/user-attachments/assets/bb114f9f-24c5-4000-a984-c10d187da5a0
-[image-feat-mobile]: https://github.com/user-attachments/assets/32cf43c4-96bd-4a4c-bfb6-59acde6fe380
-[image-feat-plugin]: https://github.com/user-attachments/assets/66a891ac-01b6-4e3f-b978-2eb07b489b1b
-[image-feat-privoder]: https://github.com/user-attachments/assets/e553e407-42de-4919-977d-7dbfcf44a821
-[image-feat-pwa]: https://github.com/user-attachments/assets/9647f70f-b71b-43b6-9564-7cdd12d1c24d
-[image-feat-t2i]: https://github.com/user-attachments/assets/708274a7-2458-494b-a6ec-b73dfa1fa7c2
-[image-feat-theme]: https://github.com/user-attachments/assets/b47c39f1-806f-492b-8fcb-b0fa973937c1
-[image-feat-tts]: https://github.com/user-attachments/assets/50189597-2cc3-4002-b4c8-756a52ad5c0a
-[image-feat-vision]: https://github.com/user-attachments/assets/18574a1f-46c2-4cbc-af2c-35a86e128a07
-[image-feat-web-search]: https://github.com/user-attachments/assets/cfdc48ac-b5f8-4a00-acee-db8f2eba09ad
+[github-stars-shield]: https://img.shields.io/github/stars/lobehub/lobehub?color=ffcb47&labelColor=black&style=flat-square
+[image-banner]: https://github.com/user-attachments/assets/5f78ae58-ed4f-4d38-8037-96109fbba58c
 [image-star]: https://github.com/user-attachments/assets/c3b482e7-cef5-4e94-bef9-226900ecfaab
 [issues-link]: https://img.shields.io/github/issues/lobehub/lobehub.svg?style=flat
 [lobe-chat-plugins]: https://github.com/lobehub/lobe-chat-plugins
@@ -969,8 +581,6 @@ This project is [LobeHub Community License](./LICENSE) licensed.
 [share-whatsapp-shield]: https://img.shields.io/badge/-share%20on%20whatsapp-black?labelColor=black&logo=whatsapp&logoColor=white&style=flat-square
 [share-x-link]: https://x.com/intent/tweet?hashtags=chatbot%2CchatGPT%2CopenAI&text=%E6%8E%A8%E8%8D%90%E4%B8%80%E4%B8%AA%20GitHub%20%E5%BC%80%E6%BA%90%E9%A1%B9%E7%9B%AE%20%F0%9F%A4%AF%20LobeHub%20-%20%E5%BC%80%E6%BA%90%E7%9A%84%E3%80%81%E5%8F%AF%E6%89%A9%E5%B1%95%E7%9A%84%EF%BC%88Function%20Calling%EF%BC%89%E9%AB%98%E6%80%A7%E8%83%BD%E8%81%8A%E5%A4%A9%E6%9C%BA%E5%99%A8%E4%BA%BA%E6%A1%86%E6%9E%B6%E3%80%82%0A%E5%AE%83%E6%94%AF%E6%8C%81%E4%B8%80%E9%94%AE%E5%85%8D%E8%B4%B9%E9%83%A8%E7%BD%B2%E7%A7%81%E4%BA%BA%20ChatGPT%2FLLM%20%E7%BD%91%E9%A1%B5%E5%BA%94%E7%94%A8%E7%A8%8B%E5%BA%8F&url=https%3A%2F%2Fgithub.com%2Flobehub%2Flobehub
 [share-x-shield]: https://img.shields.io/badge/-share%20on%20x-black?labelColor=black&logo=x&logoColor=white&style=flat-square
-[sponsor-link]: https://opencollective.com/lobehub 'Become ❤ LobeHub Sponsor'
-[sponsor-shield]: https://img.shields.io/badge/-Sponsor%20LobeHub-f04f88?logo=opencollective&logoColor=white&style=flat-square
 [submit-agents-link]: https://github.com/lobehub/lobe-chat-agents
 [submit-agents-shield]: https://img.shields.io/badge/🤖/🏪_submit_agent-%E2%86%92-c4f042?labelColor=black&style=for-the-badge
 [submit-plugin-link]: https://github.com/lobehub/lobe-chat-plugins
@@ -0,0 +1,80 @@
+import { execSync } from 'node:child_process';
+
+import { describe, expect, it } from 'vitest';
+
+/**
+ * Manual E2E coverage for `lh agent space fs` against a real backend.
+ *
+ * Run when:
+ * - A local or remote LobeHub backend is reachable by the CLI
+ * - `AGENT_FS_E2E_AGENT_ID` points at an agent with document access
+ *
+ * Expects:
+ * - The command creates and cleans up a temporary VFS directory
+ * - This suite is skipped unless `AGENT_FS_E2E_AGENT_ID` is set
+ */
+const AGENT_ID = process.env.AGENT_FS_E2E_AGENT_ID;
+const CLI = process.env.LH_CLI_PATH || 'LOBEHUB_CLI_HOME=.lobehub-dev bun src/index.ts';
+const TIMEOUT = 30_000;
+
+function run(args: string): string {
+  return execSync(`${CLI} ${args}`, {
+    encoding: 'utf8',
+    env: { ...process.env, PATH: `${process.env.HOME}/.bun/bin:${process.env.PATH}` },
+    timeout: TIMEOUT,
+  }).trim();
+}
+
+describe.skipIf(!AGENT_ID)('lh agent space fs unified VFS - manual E2E', () => {
+  const testRoot = `agent:/vfs-cli-e2e-${Date.now()}`;
+
+  it('exercises root, mounted namespaces, writes, copy, move, trash, and cleanup', () => {
+    const root = run(`agent space fs ls --agent-id ${AGENT_ID} agent:/`);
+    expect(root).toContain('lobe/');
+
+    const mountedRoot = run(`agent space fs ls --agent-id ${AGENT_ID} agent:/lobe/skills`);
+    expect(mountedRoot).toContain('builtin/');
+    expect(mountedRoot).toContain('agent/');
+
+    try {
+      expect(run(`agent space fs mkdir --agent-id ${AGENT_ID} --parents ${testRoot}`)).toContain(
+        'created',
+      );
+      expect(
+        run(
+          `agent space fs write --agent-id ${AGENT_ID} --content "# VFS E2E" ${testRoot}/source.md`,
+        ),
+      ).toContain('created');
+      expect(run(`agent space fs cat --agent-id ${AGENT_ID} ${testRoot}/source.md`)).toContain(
+        '# VFS E2E',
+      );
+      expect(
+        run(`agent space fs cp --agent-id ${AGENT_ID} ${testRoot}/source.md ${testRoot}/copied.md`),
+      ).toContain('copied');
+      expect(
+        run(`agent space fs mv --agent-id ${AGENT_ID} ${testRoot}/copied.md ${testRoot}/moved.md`),
+      ).toContain('moved');
+      expect(run(`agent space fs rm --agent-id ${AGENT_ID} --yes ${testRoot}/moved.md`)).toContain(
+        'deleted',
+      );
+      expect(run(`agent space fs trash ls --agent-id ${AGENT_ID} ${testRoot}`)).toContain(
+        `${testRoot}/moved.md`,
+      );
+      expect(
+        run(`agent space fs trash restore --agent-id ${AGENT_ID} ${testRoot}/moved.md`),
+      ).toContain('restored');
+    } finally {
+      try {
+        run(`agent space fs rm --agent-id ${AGENT_ID} --yes --recursive ${testRoot}`);
+      } catch {
+        // Cleanup is best-effort because earlier assertions may fail before creation.
+      }
+
+      try {
+        run(`agent space fs trash rm --agent-id ${AGENT_ID} --yes --recursive --force ${testRoot}`);
+      } catch {
+        // Cleanup is best-effort because the trash entry may not exist.
+      }
+    }
+  }, 60_000);
+});
@@ -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.8" "User Commands"
+.TH LH 1 "" "@lobehub/cli 0.0.20" "User Commands"
 .SH NAME
 lh \- LobeHub CLI \- manage and connect to LobeHub services
 .SH SYNOPSIS
@@ -68,15 +68,15 @@ Manage agent groups
 .B bot
 Manage bot integrations
 .TP
-.B cron
-Manage agent cron jobs
-.TP
 .B generate
 Generate content (text, image, video, speech) Alias: gen.
 .TP
 .B file
 Manage files
 .TP
+.B hetero
+Run heterogeneous agent CLIs (Claude Code / Codex) and stream their output
+.TP
 .B skill
 Manage agent skills
 .TP
@@ -1,6 +1,6 @@
 {
  "name": "@lobehub/cli",
-  "version": "0.0.8",
+  "version": "0.0.20",
  "type": "module",
  "bin": {
    "lh": "./dist/index.js",
@@ -30,11 +30,13 @@
  "devDependencies": {
    "@lobechat/agent-gateway-client": "workspace:*",
    "@lobechat/device-gateway-client": "workspace:*",
+    "@lobechat/heterogeneous-agents": "workspace:*",
    "@lobechat/local-file-shell": "workspace:*",
    "@trpc/client": "^11.8.1",
    "@types/node": "^22.13.5",
    "@types/ws": "^8.18.1",
    "commander": "^13.1.0",
+    "dayjs": "^1.11.19",
    "debug": "^4.4.0",
    "diff": "^8.0.3",
    "fast-glob": "^3.3.3",
@@ -1,6 +1,10 @@
 packages:
  - '../../packages/agent-gateway-client'
  - '../../packages/device-gateway-client'
+  - '../../packages/heterogeneous-agents'
  - '../../packages/local-file-shell'
+  - '../../packages/types'
+  - '../../packages/model-bank'
+  - '../../packages/business/const'
  - '../../packages/file-loaders'
  - '.'
@@ -7,12 +7,14 @@ const CLIENT_ID = 'lobehub-cli';
 * Get a valid access token, refreshing if expired.
 * Returns null if no credentials or refresh fails.
 */
-export async function getValidToken(): Promise<{ credentials: StoredCredentials } | null> {
+export async function getValidToken(
+  bufferSeconds = 60,
+): Promise<{ credentials: StoredCredentials } | null> {
  const credentials = loadCredentials();
  if (!credentials) return null;

-  // Check if token is still valid (with 60s buffer)
-  if (credentials.expiresAt && Date.now() / 1000 < credentials.expiresAt - 60) {
+  // Check if token is still valid (with configurable buffer)
+  if (credentials.expiresAt && Date.now() / 1000 < credentials.expiresAt - bufferSeconds) {
    return { credentials };
  }

@@ -23,6 +23,24 @@ const { mockTrpcClient } = vi.hoisted(() => ({
      updateAgentConfig: { mutate: vi.fn() },
      updateAgentPinned: { mutate: vi.fn() },
    },
+    agentDocument: {
+      copyDocumentByPath: { mutate: vi.fn() },
+      deleteDocumentByPath: { mutate: vi.fn() },
+      deleteDocumentPermanentlyByPath: { mutate: vi.fn() },
+      statDocumentByPath: { query: vi.fn() },
+      listDocumentsByPath: { query: vi.fn() },
+      listTrashDocumentsByPath: { query: vi.fn() },
+      mkdirDocumentByPath: { mutate: vi.fn() },
+      readDocumentByPath: { query: vi.fn() },
+      renameDocumentByPath: { mutate: vi.fn() },
+      restoreDocumentFromTrashByPath: { mutate: vi.fn() },
+      writeDocumentByPath: { mutate: vi.fn() },
+    },
+    agentSkills: {
+      createSkill: { mutate: vi.fn() },
+      deleteSkill: { mutate: vi.fn() },
+      updateSkill: { mutate: vi.fn() },
+    },
    aiAgent: {
      execAgent: { mutate: vi.fn() },
      getOperationStatus: { query: vi.fn() },
@@ -41,6 +59,11 @@ const { mockStreamAgentEvents } = vi.hoisted(() => ({
  mockStreamAgentEvents: vi.fn(),
 }));

+const { mockReplayAgentEvents, mockStreamAgentEventsViaWebSocket } = vi.hoisted(() => ({
+  mockReplayAgentEvents: vi.fn(),
+  mockStreamAgentEventsViaWebSocket: vi.fn(),
+}));
+
 const { mockGetAgentStreamAuthInfo } = vi.hoisted(() => ({
  mockGetAgentStreamAuthInfo: vi.fn(),
 }));
@@ -49,9 +72,18 @@ const { mockResolveLocalDeviceId } = vi.hoisted(() => ({
  mockResolveLocalDeviceId: vi.fn(),
 }));

+const { mockReadStdinText } = vi.hoisted(() => ({
+  mockReadStdinText: vi.fn(),
+}));
+
+vi.mock('node:stream/consumers', () => ({ text: mockReadStdinText }));
 vi.mock('../api/client', () => ({ getTrpcClient: mockGetTrpcClient }));
 vi.mock('../api/http', () => ({ getAgentStreamAuthInfo: mockGetAgentStreamAuthInfo }));
-vi.mock('../utils/agentStream', () => ({ streamAgentEvents: mockStreamAgentEvents }));
+vi.mock('../utils/agentStream', () => ({
+  replayAgentEvents: mockReplayAgentEvents,
+  streamAgentEvents: mockStreamAgentEvents,
+  streamAgentEventsViaWebSocket: mockStreamAgentEventsViaWebSocket,
+}));
 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() },
@@ -71,12 +103,26 @@ describe('agent command', () => {
      serverUrl: 'https://example.com',
    });
    mockStreamAgentEvents.mockResolvedValue(undefined);
+    mockReplayAgentEvents.mockReset();
+    mockStreamAgentEventsViaWebSocket.mockReset();
+    mockStreamAgentEventsViaWebSocket.mockResolvedValue(undefined);
    mockResolveLocalDeviceId.mockReset();
+    mockReadStdinText.mockReset();
    for (const method of Object.values(mockTrpcClient.agent)) {
      for (const fn of Object.values(method)) {
        (fn as ReturnType<typeof vi.fn>).mockReset();
      }
    }
+    for (const method of Object.values(mockTrpcClient.agentDocument)) {
+      for (const fn of Object.values(method)) {
+        (fn as ReturnType<typeof vi.fn>).mockReset();
+      }
+    }
+    for (const method of Object.values(mockTrpcClient.agentSkills)) {
+      for (const fn of Object.values(method)) {
+        (fn as ReturnType<typeof vi.fn>).mockReset();
+      }
+    }
    for (const method of Object.values(mockTrpcClient.aiAgent)) {
      for (const fn of Object.values(method)) {
        (fn as ReturnType<typeof vi.fn>).mockReset();
@@ -282,7 +328,7 @@ describe('agent command', () => {
  });

  describe('run', () => {
-    it('should exec agent and connect to SSE stream', async () => {
+    it('should exec agent and connect to the gateway WebSocket stream by default', async () => {
      mockTrpcClient.aiAgent.execAgent.mutate.mockResolvedValue({
        operationId: 'op-123',
        success: true,
@@ -304,11 +350,45 @@ describe('agent command', () => {
      expect(mockTrpcClient.aiAgent.execAgent.mutate).toHaveBeenCalledWith(
        expect.objectContaining({ agentId: 'a1', prompt: 'Hello' }),
      );
+      expect(mockStreamAgentEventsViaWebSocket).toHaveBeenCalledWith(
+        expect.objectContaining({
+          gatewayUrl: expect.any(String),
+          json: undefined,
+          operationId: 'op-123',
+          serverUrl: 'https://example.com',
+          token: undefined,
+          tokenType: undefined,
+          verbose: undefined,
+        }),
+      );
+      expect(mockStreamAgentEvents).not.toHaveBeenCalled();
+    });
+
+    it('should fall back to SSE when --sse is provided', async () => {
+      mockTrpcClient.aiAgent.execAgent.mutate.mockResolvedValue({
+        operationId: 'op-sse',
+        success: true,
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'run',
+        '--agent-id',
+        'a1',
+        '--prompt',
+        'Hello',
+        '--sse',
+      ]);
+
      expect(mockStreamAgentEvents).toHaveBeenCalledWith(
-        'https://example.com/api/agent/stream?operationId=op-123',
+        'https://example.com/api/agent/stream?operationId=op-sse',
        expect.objectContaining({ 'Oidc-Auth': 'test-token' }),
        expect.objectContaining({ json: undefined, verbose: undefined }),
      );
+      expect(mockStreamAgentEventsViaWebSocket).not.toHaveBeenCalled();
    });
    it('should support --slug option', async () => {
      mockTrpcClient.aiAgent.execAgent.mutate.mockResolvedValue({
@@ -595,10 +675,8 @@ describe('agent command', () => {
        '--json',
      ]);

-      expect(mockStreamAgentEvents).toHaveBeenCalledWith(
-        expect.any(String),
-        expect.any(Object),
-        expect.objectContaining({ json: true }),
+      expect(mockStreamAgentEventsViaWebSocket).toHaveBeenCalledWith(
+        expect.objectContaining({ json: true, operationId: 'op-j' }),
      );
    });
  });
@@ -794,4 +872,540 @@ describe('agent command', () => {
      );
    });
  });
+
+  describe('fs', () => {
+    it('should list VFS entries from the unified agent root alias', async () => {
+      mockTrpcClient.agentDocument.listDocumentsByPath.query.mockResolvedValue([
+        {
+          mode: 8,
+          mount: { driver: 'synthetic', source: 'virtual' },
+          name: 'writer',
+          path: './lobe',
+          type: 'directory',
+        },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'ls',
+        '--agent-id',
+        'a1',
+        'agent:/',
+        '--json',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.listDocumentsByPath.query).toHaveBeenCalledWith({
+        agentId: 'a1',
+        cursor: undefined,
+        limit: undefined,
+        path: './',
+        topicId: undefined,
+      });
+      expect(consoleSpy).toHaveBeenCalledWith(
+        JSON.stringify(
+          [
+            {
+              mode: 8,
+              mount: { driver: 'synthetic', source: 'virtual' },
+              name: 'writer',
+              path: './lobe',
+              type: 'directory',
+            },
+          ],
+          null,
+          2,
+        ),
+      );
+    });
+
+    it('should pass pagination options to VFS ls', async () => {
+      mockTrpcClient.agentDocument.listDocumentsByPath.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'ls',
+        '--agent-id',
+        'a1',
+        '--cursor',
+        '100',
+        '--limit',
+        '25',
+        'agent:/notes',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.listDocumentsByPath.query).toHaveBeenCalledWith({
+        agentId: 'a1',
+        cursor: '100',
+        limit: 25,
+        path: './notes',
+        topicId: undefined,
+      });
+    });
+
+    it('should print unix-like long listings with ls -la', async () => {
+      mockTrpcClient.agentDocument.listDocumentsByPath.query.mockResolvedValue([
+        {
+          mode: 14,
+          name: '.config',
+          path: './notes/.config',
+          size: 0,
+          type: 'directory',
+          updatedAt: '2026-04-27T07:18:00',
+        },
+        {
+          mode: 6,
+          name: 'SOUL.md',
+          path: './notes/SOUL.md',
+          size: 399,
+          type: 'file',
+          updatedAt: '2026-04-27T07:19:00',
+        },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'ls',
+        '-la',
+        '--agent-id',
+        'a1',
+        'agent:/notes',
+      ]);
+
+      expect(consoleSpy).toHaveBeenNthCalledWith(1, 'total 1');
+      expect(consoleSpy).toHaveBeenNthCalledWith(
+        2,
+        expect.stringMatching(/^dr-x------ {2}1 agent {2}agent {4}0 --- -- --:-- \.$/),
+      );
+      expect(consoleSpy).toHaveBeenNthCalledWith(
+        3,
+        expect.stringMatching(/^dr-x------ {2}1 agent {2}agent {4}0 --- -- --:-- \.\.$/),
+      );
+      expect(consoleSpy).toHaveBeenNthCalledWith(
+        4,
+        expect.stringMatching(/^drwx------ {2}1 agent {2}agent {4}0 Apr 27 07:18 \.config\/$/),
+      );
+      expect(consoleSpy).toHaveBeenNthCalledWith(
+        5,
+        expect.stringMatching(/^-rw------- {2}1 agent {2}agent {2}399 Apr 27 07:19 SOUL\.md$/),
+      );
+    });
+
+    it('should expose VFS commands through agent space fs', async () => {
+      mockTrpcClient.agentDocument.listDocumentsByPath.query.mockResolvedValue([]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'ls',
+        '--agent-id',
+        'a1',
+        'agent:/notes',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.listDocumentsByPath.query).toHaveBeenCalledWith({
+        agentId: 'a1',
+        cursor: undefined,
+        limit: undefined,
+        path: './notes',
+        topicId: undefined,
+      });
+    });
+
+    it('should collect tree traversal warnings instead of failing the whole tree', async () => {
+      mockTrpcClient.agentDocument.listDocumentsByPath.query
+        .mockResolvedValueOnce([
+          {
+            mode: 8,
+            name: 'builtin',
+            path: './lobe/skills/builtin',
+            type: 'directory',
+          },
+        ])
+        .mockRejectedValueOnce(new Error('Failed to list builtin skills'));
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'tree',
+        '--agent-id',
+        'a1',
+        'agent:/lobe/skills',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.listDocumentsByPath.query).toHaveBeenNthCalledWith(1, {
+        agentId: 'a1',
+        path: './lobe/skills',
+        topicId: undefined,
+      });
+      expect(mockTrpcClient.agentDocument.listDocumentsByPath.query).toHaveBeenNthCalledWith(2, {
+        agentId: 'a1',
+        path: './lobe/skills/builtin',
+        topicId: undefined,
+      });
+      expect(log.warn).toHaveBeenCalledWith('./lobe/skills/builtin: Failed to list builtin skills');
+    });
+
+    it('should read SKILL.md when cat targets a skill directory alias', async () => {
+      const stdoutSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+      mockTrpcClient.agentDocument.statDocumentByPath.query.mockResolvedValue({
+        content: '# Writer',
+        mode: 2,
+        mount: { driver: 'skills', namespace: 'builtin', source: 'builtin' },
+        name: 'SKILL.md',
+        path: './lobe/skills/builtin/skills/writer/SKILL.md',
+        type: 'file',
+      });
+      mockTrpcClient.agentDocument.readDocumentByPath.query.mockResolvedValue({
+        content: '# Writer',
+        contentType: 'text/markdown',
+        path: './lobe/skills/builtin/skills/writer/SKILL.md',
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'cat',
+        '--agent-id',
+        'a1',
+        'builtin:/writer',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.statDocumentByPath.query).toHaveBeenCalledWith({
+        agentId: 'a1',
+        path: './lobe/skills/builtin/skills/writer/SKILL.md',
+        topicId: undefined,
+      });
+      expect(mockTrpcClient.agentDocument.readDocumentByPath.query).toHaveBeenCalledWith({
+        agentId: 'a1',
+        path: './lobe/skills/builtin/skills/writer/SKILL.md',
+        topicId: undefined,
+      });
+      expect(stdoutSpy).toHaveBeenCalledWith('# Writer');
+      stdoutSpy.mockRestore();
+    });
+
+    it('should create a writable skill through touch when the path does not exist', async () => {
+      mockTrpcClient.agentDocument.statDocumentByPath.query.mockRejectedValue({
+        data: { code: 'NOT_FOUND' },
+      });
+      mockTrpcClient.agentDocument.writeDocumentByPath.mutate.mockResolvedValue({
+        path: './lobe/skills/agent/skills/writer/SKILL.md',
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'touch',
+        '--agent-id',
+        'a1',
+        'skills:/writer',
+        '--content',
+        '# Writer',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.writeDocumentByPath.mutate).toHaveBeenCalledWith({
+        agentId: 'a1',
+        content: '# Writer',
+        createMode: 'if-missing',
+        path: './lobe/skills/agent/skills/writer',
+        topicId: undefined,
+      });
+    });
+
+    it('should read write content from stdin when no content option is provided', async () => {
+      const stdinDescriptor = Object.getOwnPropertyDescriptor(process.stdin, 'isTTY');
+      Object.defineProperty(process.stdin, 'isTTY', { configurable: true, value: false });
+      mockReadStdinText.mockResolvedValue('# Piped Content');
+      mockTrpcClient.agentDocument.statDocumentByPath.query.mockRejectedValue({
+        data: { code: 'NOT_FOUND' },
+      });
+      mockTrpcClient.agentDocument.writeDocumentByPath.mutate.mockResolvedValue({
+        path: './notes/piped.md',
+      });
+
+      try {
+        const program = createProgram();
+        await program.parseAsync([
+          'node',
+          'test',
+          'agent',
+          'space',
+          'fs',
+          'write',
+          '--agent-id',
+          'a1',
+          'agent:/notes/piped.md',
+        ]);
+
+        expect(mockReadStdinText).toHaveBeenCalledWith(process.stdin);
+        expect(mockTrpcClient.agentDocument.writeDocumentByPath.mutate).toHaveBeenCalledWith({
+          agentId: 'a1',
+          content: '# Piped Content',
+          createMode: 'if-missing',
+          path: './notes/piped.md',
+          topicId: undefined,
+        });
+      } finally {
+        if (stdinDescriptor) {
+          Object.defineProperty(process.stdin, 'isTTY', stdinDescriptor);
+        }
+      }
+    });
+
+    it('should create directories through the generic mkdir path API', async () => {
+      mockTrpcClient.agentDocument.mkdirDocumentByPath.mutate.mockResolvedValue({
+        path: './notes/archive',
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'mkdir',
+        '--agent-id',
+        'a1',
+        '--parents',
+        'agent:/notes/archive',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.mkdirDocumentByPath.mutate).toHaveBeenCalledWith({
+        agentId: 'a1',
+        path: './notes/archive',
+        recursive: true,
+        topicId: undefined,
+      });
+    });
+
+    it('should stat unified root paths', async () => {
+      mockTrpcClient.agentDocument.statDocumentByPath.query.mockResolvedValue({
+        mode: 8,
+        name: 'lobe',
+        path: './lobe',
+        type: 'directory',
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'stat',
+        '--agent-id',
+        'a1',
+        'agent:/lobe',
+        '--json',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.statDocumentByPath.query).toHaveBeenCalledWith({
+        agentId: 'a1',
+        path: './lobe',
+        topicId: undefined,
+      });
+    });
+
+    it('should copy paths through the generic copyDocumentByPath API', async () => {
+      mockTrpcClient.agentDocument.copyDocumentByPath.mutate.mockResolvedValue({
+        path: './notes/published.md',
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'cp',
+        '--agent-id',
+        'a1',
+        '--force',
+        'agent:/notes/draft.md',
+        'agent:/notes/published.md',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.copyDocumentByPath.mutate).toHaveBeenCalledWith({
+        agentId: 'a1',
+        force: true,
+        fromPath: './notes/draft.md',
+        toPath: './notes/published.md',
+        topicId: undefined,
+      });
+    });
+
+    it('should rename paths through the generic renameDocumentByPath API', async () => {
+      mockTrpcClient.agentDocument.renameDocumentByPath.mutate.mockResolvedValue({
+        path: './notes/final.md',
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'mv',
+        '--agent-id',
+        'a1',
+        'agent:/notes/draft.md',
+        'agent:/notes/final.md',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.renameDocumentByPath.mutate).toHaveBeenCalledWith({
+        agentId: 'a1',
+        force: undefined,
+        fromPath: './notes/draft.md',
+        toPath: './notes/final.md',
+        topicId: undefined,
+      });
+    });
+
+    it('should soft-delete paths through the generic deleteDocumentByPath API', async () => {
+      mockTrpcClient.agentDocument.deleteDocumentByPath.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'rm',
+        '--agent-id',
+        'a1',
+        '--yes',
+        '--recursive',
+        'agent:/notes',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.deleteDocumentByPath.mutate).toHaveBeenCalledWith({
+        agentId: 'a1',
+        force: undefined,
+        path: './notes',
+        recursive: true,
+        topicId: undefined,
+      });
+    });
+
+    it('should list trash through the generic trash path API', async () => {
+      mockTrpcClient.agentDocument.listTrashDocumentsByPath.query.mockResolvedValue([
+        { path: './notes/deleted.md' },
+      ]);
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'trash',
+        'ls',
+        '--agent-id',
+        'a1',
+        'agent:/notes',
+      ]);
+
+      expect(mockTrpcClient.agentDocument.listTrashDocumentsByPath.query).toHaveBeenCalledWith({
+        agentId: 'a1',
+        path: './notes',
+        topicId: undefined,
+      });
+      expect(consoleSpy).toHaveBeenCalledWith('agent:/notes/deleted.md');
+    });
+
+    it('should restore trash entries through the generic trash restore API', async () => {
+      mockTrpcClient.agentDocument.restoreDocumentFromTrashByPath.mutate.mockResolvedValue({
+        path: './notes/deleted.md',
+      });
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'trash',
+        'restore',
+        '--agent-id',
+        'a1',
+        'agent:/notes/deleted.md',
+      ]);
+
+      expect(
+        mockTrpcClient.agentDocument.restoreDocumentFromTrashByPath.mutate,
+      ).toHaveBeenCalledWith({
+        agentId: 'a1',
+        path: './notes/deleted.md',
+        topicId: undefined,
+      });
+    });
+
+    it('should permanently delete trash entries through the generic trash rm API', async () => {
+      mockTrpcClient.agentDocument.deleteDocumentPermanentlyByPath.mutate.mockResolvedValue({});
+
+      const program = createProgram();
+      await program.parseAsync([
+        'node',
+        'test',
+        'agent',
+        'space',
+        'fs',
+        'trash',
+        'rm',
+        '--agent-id',
+        'a1',
+        '--yes',
+        '--force',
+        'agent:/notes/deleted.md',
+      ]);
+
+      expect(
+        mockTrpcClient.agentDocument.deleteDocumentPermanentlyByPath.mutate,
+      ).toHaveBeenCalledWith({
+        agentId: 'a1',
+        force: true,
+        path: './notes/deleted.md',
+        recursive: undefined,
+        topicId: undefined,
+      });
+    });
+  });
 });
@@ -14,33 +14,12 @@ import {
 import { resolveLocalDeviceId } from '../utils/device';
 import { confirm, outputJson, printTable, truncate } from '../utils/format';
 import { log, setVerbose } from '../utils/logger';
-
-/**
- * Resolve an agent identifier (agentId or slug) to a concrete agentId.
- * When a slug is provided, uses getBuiltinAgent to look up the agent.
- */
-async function resolveAgentId(
-  client: any,
-  opts: { agentId?: string; slug?: string },
-): 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 as any).id || (agent as any).agentId;
-  }
-
-  log.error('Either <agentId> or --slug is required.');
-  process.exit(1);
-  return ''; // unreachable
-}
+import { resolveAgentId } from './agent/resolveAgentId';
+import { registerAgentSpaceFsCommand } from './agent/spaceFs';

 export function registerAgentCommand(program: Command) {
  const agent = program.command('agent').description('Manage agents');
+  registerAgentSpaceFsCommand(agent);

  // ── list ──────────────────────────────────────────────

@@ -339,7 +318,7 @@ export function registerAgentCommand(program: Command) {
        }

        // 1. Exec agent to get operationId
-        const input: Record<string, any> = { prompt: options.prompt };
+        const input: Record<string, any> = { prompt: options.prompt, trigger: 'cli' };
        if (options.agentId) input.agentId = options.agentId;
        if (deviceId) input.deviceId = deviceId;
        if (options.slug) input.slug = options.slug;
@@ -0,0 +1,44 @@
+import { log } from '../../utils/logger';
+
+interface AgentLookupClient {
+  agent: {
+    getBuiltinAgent: {
+      query: (input: { slug: string }) => Promise<{ agentId?: string; id?: string } | null>;
+    };
+  };
+}
+
+/**
+ * Resolve an agent identifier into a concrete agent id.
+ *
+ * Use when:
+ * - A command accepts either a positional agent id or `--slug`.
+ * - Downstream tRPC calls require the concrete agent id.
+ *
+ * Expects:
+ * - `opts.agentId` to win over `opts.slug`.
+ * - `client.agent.getBuiltinAgent` to resolve slugs when needed.
+ *
+ * Returns:
+ * - The resolved agent id, or exits the process after logging a CLI-facing error.
+ */
+export async function resolveAgentId(
+  client: AgentLookupClient,
+  opts: { agentId?: string; slug?: string },
+): 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 || agent.agentId || '';
+  }
+
+  log.error('Either <agentId> or --slug is required.');
+  process.exit(1);
+  return '';
+}
@@ -0,0 +1,908 @@
+import { readFileSync } from 'node:fs';
+import { text } from 'node:stream/consumers';
+
+import type { Command } from 'commander';
+import dayjs from 'dayjs';
+import pc from 'picocolors';
+
+import { getTrpcClient } from '../../api/client';
+import { confirm, outputJson } from '../../utils/format';
+import { log } from '../../utils/logger';
+import { resolveAgentId } from './resolveAgentId';
+
+const SKILL_FILE_NAME = 'SKILL.md';
+
+const SKILL_NAMESPACE_PREFIXES = {
+  'agent': './lobe/skills/agent/skills',
+  'builtin': './lobe/skills/builtin/skills',
+  'installed-active': './lobe/skills/installed/active/skills',
+  'installed-all': './lobe/skills/installed/all/skills',
+} as const;
+
+const FS_PATH_ALIASES = {
+  'agent': './',
+  'builtin': 'builtin',
+  'skills': 'agent',
+  'installed-active': 'installed-active',
+  'installed-all': 'installed-all',
+} as const;
+
+type SkillFsNamespace = keyof typeof SKILL_NAMESPACE_PREFIXES;
+type AgentFsClient = Awaited<ReturnType<typeof getTrpcClient>>;
+
+interface AgentFsContext {
+  agentId: string;
+  topicId?: string;
+}
+
+interface AgentFsNode {
+  content?: string;
+  createdAt?: Date | string;
+  mode?: number;
+  mount?: {
+    driver?: string;
+    namespace?: string;
+  };
+  name: string;
+  path: string;
+  size?: number;
+  type: 'directory' | 'file';
+  updatedAt?: Date | string;
+}
+
+interface AgentFsResolvedPath {
+  filePath?: string;
+  namespace?: SkillFsNamespace;
+  path: string;
+  skillName?: string;
+}
+
+interface AgentFsOptions {
+  agentId?: string;
+  slug?: string;
+  topicId?: string;
+}
+
+function getTrpcErrorCode(error: unknown): string | undefined {
+  if (!error || typeof error !== 'object') return undefined;
+
+  const value = error as {
+    data?: { code?: string };
+    shape?: { data?: { code?: string } };
+  };
+
+  return value.data?.code ?? value.shape?.data?.code;
+}
+
+function exitWithError(message: string): never {
+  log.error(message);
+  process.exit(1);
+  throw new Error(message);
+}
+
+function resolveAgentFsPath(input = 'agent:/'): AgentFsResolvedPath {
+  const raw = input.trim();
+
+  const aliasMatch = raw.match(/^([a-z-]+):(\/.*)?$/);
+
+  if (aliasMatch) {
+    const alias = aliasMatch[1] as keyof typeof FS_PATH_ALIASES;
+    const target = FS_PATH_ALIASES[alias];
+
+    if (!target) {
+      exitWithError(
+        `Unknown fs namespace "${aliasMatch[1]}". Use agent, skills, builtin, installed-all, or installed-active.`,
+      );
+    }
+
+    const suffix = aliasMatch[2]?.replace(/^\/+/, '').replace(/\/+$/, '') ?? '';
+    const prefix = target === './' ? './' : SKILL_NAMESPACE_PREFIXES[target as SkillFsNamespace];
+
+    return resolveAgentFsPath(suffix ? `${prefix}/${suffix}` : prefix);
+  }
+
+  if (raw === './' || raw === '.' || raw === '/') {
+    return { path: './' };
+  }
+
+  const match = Object.entries(SKILL_NAMESPACE_PREFIXES).find(([, prefix]) => {
+    return raw === prefix || raw.startsWith(`${prefix}/`);
+  });
+
+  if (!match) {
+    if (!raw.startsWith('./')) {
+      exitWithError(`Invalid fs path "${input}". Use aliases like "agent:/" or a full VFS path.`);
+    }
+
+    const normalizedPath = raw.replaceAll(/\/+/g, '/').replace(/\/+$/, '') || './';
+    return { path: normalizedPath };
+  }
+
+  const [namespace, prefix] = match as [
+    SkillFsNamespace,
+    (typeof SKILL_NAMESPACE_PREFIXES)[SkillFsNamespace],
+  ];
+  const relativePath = raw.slice(prefix.length).replace(/^\/+/, '').replace(/\/+$/, '');
+
+  if (
+    relativePath.includes('//') ||
+    relativePath.split('/').some((segment) => segment === '.' || segment === '..')
+  ) {
+    exitWithError(`Invalid fs path "${input}"`);
+  }
+
+  if (!relativePath) {
+    return { namespace, path: prefix };
+  }
+
+  const separatorIndex = relativePath.indexOf('/');
+
+  if (separatorIndex < 0) {
+    return {
+      namespace,
+      path: `${prefix}/${relativePath}`,
+      skillName: relativePath,
+    };
+  }
+
+  return {
+    filePath: relativePath.slice(separatorIndex + 1),
+    namespace,
+    path: `${prefix}/${relativePath}`,
+    skillName: relativePath.slice(0, separatorIndex),
+  };
+}
+
+function requireSkillNamespace(resolved: AgentFsResolvedPath): SkillFsNamespace {
+  if (!resolved.namespace) {
+    exitWithError(`Expected a skill namespace path, but received "${resolved.path}".`);
+  }
+
+  return resolved.namespace;
+}
+
+function canonicalSkillFilePath(resolved: AgentFsResolvedPath) {
+  if (!resolved.skillName) {
+    exitWithError('Expected a skill path, but received a namespace root.');
+  }
+
+  if (resolved.filePath && resolved.filePath !== SKILL_FILE_NAME) {
+    exitWithError(`Unsupported writable path "${resolved.path}". Only SKILL.md is mutable.`);
+  }
+
+  return `${SKILL_NAMESPACE_PREFIXES[requireSkillNamespace(resolved)]}/${resolved.skillName}/${SKILL_FILE_NAME}`;
+}
+
+function toDisplayPath(path: string) {
+  if (path === './') return 'agent:/';
+  if (path.startsWith('./') && path !== './lobe' && !path.startsWith('./lobe/')) {
+    return `agent:/${path.slice(2)}`;
+  }
+
+  for (const [namespace, prefix] of Object.entries(SKILL_NAMESPACE_PREFIXES) as Array<
+    [SkillFsNamespace, string]
+  >) {
+    const alias = namespace === 'agent' ? 'skills' : namespace;
+    if (path === prefix) return `${alias}:/`;
+    if (path.startsWith(`${prefix}/`)) return `${alias}:/${path.slice(prefix.length + 1)}`;
+  }
+
+  return path;
+}
+
+function isWritableNode(node: { mode?: number }) {
+  return ((node.mode ?? 0) & 4) !== 0;
+}
+
+function parseOptionalPositiveInteger(value?: string) {
+  if (value === undefined) return undefined;
+
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    exitWithError(`Expected a positive integer, received "${value}".`);
+  }
+
+  return parsed;
+}
+
+function formatFsNodeName(node: { mode?: number; name: string; type: 'directory' | 'file' }) {
+  const suffix = node.type === 'directory' ? '/' : '';
+  return isWritableNode(node) ? `${node.name}${suffix}` : pc.dim(`${node.name}${suffix}`);
+}
+
+function getFsNodeDisplayName(node: Pick<AgentFsNode, 'name' | 'type'>) {
+  if (node.name === '.' || node.name === '..') return node.name;
+
+  return `${node.name}${node.type === 'directory' ? '/' : ''}`;
+}
+
+function getParentFsPath(path: string) {
+  if (path === './') return './';
+
+  const segments = path.replace(/^\.\//, '').split('/').filter(Boolean);
+  if (segments.length <= 1) return './';
+
+  return `./${segments.slice(0, -1).join('/')}`;
+}
+
+function createSyntheticListingNode(name: '.' | '..', path: string): AgentFsNode {
+  return {
+    mode: 10,
+    name,
+    path,
+    size: 0,
+    type: 'directory',
+  };
+}
+
+function formatFsPermissions(node: Pick<AgentFsNode, 'mode' | 'type'>) {
+  const mode = node.mode ?? 0;
+  const canRead = (mode & 2) !== 0 || (mode & 8) !== 0;
+  const canWrite = (mode & 4) !== 0;
+  const canExecute = (mode & 1) !== 0 || (node.type === 'directory' && (mode & 8) !== 0);
+  const owner = `${canRead ? 'r' : '-'}${canWrite ? 'w' : '-'}${canExecute ? 'x' : '-'}`;
+
+  return `${node.type === 'directory' ? 'd' : '-'}${owner}------`;
+}
+
+function formatFsLongDate(value?: Date | string) {
+  if (!value) return '--- -- --:--';
+
+  const date = dayjs(value);
+  if (!date.isValid()) return '--- -- --:--';
+
+  return date.format('MMM DD HH:mm');
+}
+
+function formatFsLongListing(nodes: AgentFsNode[]) {
+  const sizeWidth = Math.max(1, ...nodes.map((node) => String(node.size ?? 0).length));
+  const totalBlocks = nodes.reduce((total, node) => total + Math.ceil((node.size ?? 0) / 512), 0);
+  const lines = [`total ${totalBlocks}`];
+
+  for (const node of nodes) {
+    const size = String(node.size ?? 0).padStart(sizeWidth, ' ');
+    const mtime = formatFsLongDate(node.updatedAt ?? node.createdAt);
+    lines.push(
+      `${formatFsPermissions(node)}  1 agent  agent  ${size} ${mtime} ${getFsNodeDisplayName(node)}`,
+    );
+  }
+
+  return lines;
+}
+
+async function readFsContentInput(options: { content?: string; contentFile?: string }) {
+  if (options.contentFile) {
+    return readFileSync(options.contentFile, 'utf8');
+  }
+
+  if (options.content !== undefined) return options.content;
+
+  // NOTICE:
+  // CLI write commands should compose with shell pipelines without blocking interactive runs.
+  // Node marks piped stdin with `isTTY === false`, while normal terminals are `true` or undefined in tests.
+  // Remove this branch only if Commander gains first-class stdin option support for these commands.
+  if (process.stdin.isTTY === false) return text(process.stdin);
+
+  return '';
+}
+
+async function resolveAgentFsContext(client: AgentFsClient, options: AgentFsOptions) {
+  const agentId = await resolveAgentId(client, options);
+  return { agentId, topicId: options.topicId };
+}
+
+async function getFsNode(client: AgentFsClient, context: AgentFsContext, path: string) {
+  try {
+    return (await client.agentDocument.statDocumentByPath.query({
+      agentId: context.agentId,
+      path,
+      topicId: context.topicId,
+    })) as AgentFsNode;
+  } catch (error) {
+    if (getTrpcErrorCode(error) === 'NOT_FOUND') return undefined;
+    throw error;
+  }
+}
+
+async function readFsFile(client: AgentFsClient, context: AgentFsContext, inputPath: string) {
+  const resolved = resolveAgentFsPath(inputPath);
+
+  const readPath =
+    resolved.skillName && !resolved.filePath
+      ? `${SKILL_NAMESPACE_PREFIXES[requireSkillNamespace(resolved)]}/${resolved.skillName}/${SKILL_FILE_NAME}`
+      : resolved.path;
+
+  const stat = await getFsNode(client, context, readPath);
+
+  if (!stat) {
+    exitWithError(`Path not found: ${inputPath}`);
+  }
+
+  if (stat.type !== 'file') {
+    exitWithError(`Cannot read directory path: ${inputPath}`);
+  }
+
+  const node = (await client.agentDocument.readDocumentByPath.query({
+    agentId: context.agentId,
+    path: readPath,
+    topicId: context.topicId,
+  })) as AgentFsNode;
+
+  return { node, resolved: resolveAgentFsPath(readPath) };
+}
+
+async function writeFsFile(
+  client: AgentFsClient,
+  context: AgentFsContext,
+  inputPath: string,
+  content: string,
+) {
+  const resolved = resolveAgentFsPath(inputPath);
+  const existing = await getFsNode(
+    client,
+    context,
+    resolved.skillName && !resolved.filePath ? canonicalSkillFilePath(resolved) : resolved.path,
+  );
+  const result = await client.agentDocument.writeDocumentByPath.mutate({
+    agentId: context.agentId,
+    content,
+    createMode: existing ? 'must-exist' : 'if-missing',
+    path: resolved.path,
+    topicId: context.topicId,
+  });
+
+  return {
+    action: existing ? ('updated' as const) : ('created' as const),
+    path: result?.path ?? resolved.path,
+  };
+}
+
+async function mkdirFsPath(
+  client: AgentFsClient,
+  context: AgentFsContext,
+  inputPath: string,
+  options?: { recursive?: boolean },
+) {
+  const resolved = resolveAgentFsPath(inputPath);
+
+  return client.agentDocument.mkdirDocumentByPath.mutate({
+    agentId: context.agentId,
+    path: resolved.path,
+    recursive: options?.recursive,
+    topicId: context.topicId,
+  });
+}
+
+async function deleteFsPath(
+  client: AgentFsClient,
+  context: AgentFsContext,
+  inputPath: string,
+  options?: { force?: boolean; recursive?: boolean },
+) {
+  const resolved = resolveAgentFsPath(inputPath);
+
+  return client.agentDocument.deleteDocumentByPath.mutate({
+    agentId: context.agentId,
+    force: options?.force,
+    path: resolved.path,
+    recursive: options?.recursive,
+    topicId: context.topicId,
+  });
+}
+
+async function copyFsPath(
+  client: AgentFsClient,
+  context: AgentFsContext,
+  source: string,
+  destination: string,
+  force?: boolean,
+) {
+  const sourceResolved = resolveAgentFsPath(source);
+  const destinationResolved = resolveAgentFsPath(destination);
+
+  return client.agentDocument.copyDocumentByPath.mutate({
+    agentId: context.agentId,
+    force,
+    fromPath: sourceResolved.path,
+    toPath: destinationResolved.path,
+    topicId: context.topicId,
+  });
+}
+
+async function renameFsPath(
+  client: AgentFsClient,
+  context: AgentFsContext,
+  source: string,
+  destination: string,
+  force?: boolean,
+) {
+  const sourceResolved = resolveAgentFsPath(source);
+  const destinationResolved = resolveAgentFsPath(destination);
+
+  return client.agentDocument.renameDocumentByPath.mutate({
+    agentId: context.agentId,
+    force,
+    fromPath: sourceResolved.path,
+    toPath: destinationResolved.path,
+    topicId: context.topicId,
+  });
+}
+
+async function listTrashFsPath(client: AgentFsClient, context: AgentFsContext, inputPath?: string) {
+  const resolved = resolveAgentFsPath(inputPath || 'agent:/');
+
+  return (await client.agentDocument.listTrashDocumentsByPath.query({
+    agentId: context.agentId,
+    path: resolved.path,
+    topicId: context.topicId,
+  })) as Array<Pick<AgentFsNode, 'path'>>;
+}
+
+async function restoreTrashFsPath(
+  client: AgentFsClient,
+  context: AgentFsContext,
+  inputPath: string,
+) {
+  const resolved = resolveAgentFsPath(inputPath);
+
+  return client.agentDocument.restoreDocumentFromTrashByPath.mutate({
+    agentId: context.agentId,
+    path: resolved.path,
+    topicId: context.topicId,
+  });
+}
+
+async function deleteTrashFsPath(
+  client: AgentFsClient,
+  context: AgentFsContext,
+  inputPath: string,
+  options?: { force?: boolean; recursive?: boolean },
+) {
+  const resolved = resolveAgentFsPath(inputPath);
+
+  return client.agentDocument.deleteDocumentPermanentlyByPath.mutate({
+    agentId: context.agentId,
+    force: options?.force,
+    path: resolved.path,
+    recursive: options?.recursive,
+    topicId: context.topicId,
+  });
+}
+
+async function printFsTree(
+  client: AgentFsClient,
+  context: AgentFsContext,
+  path: string,
+  prefix = '',
+  warnings: string[] = [],
+) {
+  let nodes: AgentFsNode[];
+
+  try {
+    nodes = (await client.agentDocument.listDocumentsByPath.query({
+      agentId: context.agentId,
+      path,
+      topicId: context.topicId,
+    })) as AgentFsNode[];
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'failed to list path';
+    warnings.push(`${toDisplayPath(path)}: ${message}`);
+    return;
+  }
+
+  for (const [index, node] of nodes.entries()) {
+    const last = index === nodes.length - 1;
+    console.log(`${prefix}${last ? '└── ' : '├── '}${formatFsNodeName(node)}`);
+
+    if (node.type === 'directory') {
+      await printFsTree(client, context, node.path, `${prefix}${last ? '    ' : '│   '}`, warnings);
+    }
+  }
+}
+
+function registerFsCommands(fsCommand: Command) {
+  fsCommand
+    .command('ls [path]')
+    .description('List VFS entries')
+    .option('-a, --all', 'Include hidden entries')
+    .option('-l, --long', 'Use long listing format')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('--cursor <cursor>', 'Directory pagination cursor')
+    .option('-L, --limit <n>', 'Maximum number of entries')
+    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
+    .action(
+      async (
+        inputPath: string | undefined,
+        options: {
+          agentId?: string;
+          all?: boolean;
+          cursor?: string;
+          json?: string | boolean;
+          limit?: string;
+          long?: boolean;
+          slug?: string;
+          topicId?: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const resolved = resolveAgentFsPath(inputPath || 'agent:/');
+
+        const nodes = ((await client.agentDocument.listDocumentsByPath.query({
+          agentId: context.agentId,
+          cursor: options.cursor,
+          limit: parseOptionalPositiveInteger(options.limit),
+          path: resolved.path,
+          topicId: context.topicId,
+        })) ?? []) as AgentFsNode[];
+        const filtered = options.all ? nodes : nodes.filter((node) => !node.name.startsWith('.'));
+
+        if (options.json !== undefined) {
+          const fields = typeof options.json === 'string' ? options.json : undefined;
+          outputJson(filtered, fields);
+          return;
+        }
+
+        if (options.long) {
+          const longNodes = options.all
+            ? [
+                createSyntheticListingNode('.', resolved.path),
+                createSyntheticListingNode('..', getParentFsPath(resolved.path)),
+                ...filtered,
+              ]
+            : filtered;
+          formatFsLongListing(longNodes).forEach((line) => console.log(line));
+          return;
+        }
+
+        filtered.forEach((node) => console.log(formatFsNodeName(node)));
+      },
+    );
+
+  fsCommand
+    .command('tree [path]')
+    .description('Print a tree view of the VFS')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .action(
+      async (
+        inputPath: string | undefined,
+        options: { agentId?: string; slug?: string; topicId?: string },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const resolved = resolveAgentFsPath(inputPath || 'agent:/');
+
+        console.log(pc.bold(toDisplayPath(resolved.path)));
+        const warnings: string[] = [];
+        await printFsTree(client, context, resolved.path, '', warnings);
+
+        for (const warning of warnings) {
+          log.warn(warning);
+        }
+      },
+    );
+
+  fsCommand
+    .command('cat <path>')
+    .description('Read a VFS file')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .action(
+      async (inputPath: string, options: { agentId?: string; slug?: string; topicId?: string }) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const { node } = await readFsFile(client, context, inputPath);
+        process.stdout.write(node.content ?? '');
+      },
+    );
+
+  fsCommand
+    .command('stat <path>')
+    .description('Show VFS node metadata')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
+    .action(
+      async (
+        inputPath: string,
+        options: {
+          agentId?: string;
+          json?: string | boolean;
+          slug?: string;
+          topicId?: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const resolved = resolveAgentFsPath(inputPath);
+
+        const node = await getFsNode(client, context, resolved.path);
+
+        if (!node) {
+          exitWithError(`Path not found: ${inputPath}`);
+        }
+
+        if (options.json !== undefined) {
+          const fields = typeof options.json === 'string' ? options.json : undefined;
+          outputJson(node, fields);
+          return;
+        }
+
+        console.log(JSON.stringify(node, null, 2));
+      },
+    );
+
+  fsCommand
+    .command('touch <path>')
+    .description('Create or update a VFS file')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('-c, --content <content>', 'File content')
+    .option('-F, --content-file <path>', 'Read content from a local file')
+    .action(
+      async (
+        inputPath: string,
+        options: {
+          agentId?: string;
+          content?: string;
+          contentFile?: string;
+          slug?: string;
+          topicId?: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const content = await readFsContentInput(options);
+        const result = await writeFsFile(client, context, inputPath, content);
+        console.log(`${pc.green('✓')} ${result.action} ${pc.bold(toDisplayPath(result.path))}`);
+      },
+    );
+
+  fsCommand
+    .command('write <path>')
+    .description('Write content to a VFS file')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('-c, --content <content>', 'File content')
+    .option('-F, --content-file <path>', 'Read content from a local file')
+    .action(
+      async (
+        inputPath: string,
+        options: {
+          agentId?: string;
+          content?: string;
+          contentFile?: string;
+          slug?: string;
+          topicId?: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const content = await readFsContentInput(options);
+        const result = await writeFsFile(client, context, inputPath, content);
+        console.log(`${pc.green('✓')} ${result.action} ${pc.bold(toDisplayPath(result.path))}`);
+      },
+    );
+
+  fsCommand
+    .command('mkdir <path>')
+    .description('Create a VFS directory')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('-p, --parents', 'Create parent directories as needed')
+    .action(
+      async (
+        inputPath: string,
+        options: { agentId?: string; parents?: boolean; slug?: string; topicId?: string },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const result = await mkdirFsPath(client, context, inputPath, {
+          recursive: options.parents,
+        });
+        console.log(
+          `${pc.green('✓')} created ${pc.bold(toDisplayPath(result?.path ?? inputPath))}`,
+        );
+      },
+    );
+
+  fsCommand
+    .command('rm <path>')
+    .description('Delete a VFS node into trash')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('-r, --recursive', 'Recursively delete a directory subtree')
+    .option('-f, --force', 'Forward force semantics to the VFS delete primitive')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(
+      async (
+        inputPath: string,
+        options: {
+          agentId?: string;
+          force?: boolean;
+          recursive?: boolean;
+          slug?: string;
+          topicId?: string;
+          yes?: boolean;
+        },
+      ) => {
+        if (!options.yes) {
+          const confirmed = await confirm(`Delete ${inputPath}?`);
+          if (!confirmed) {
+            console.log('Cancelled.');
+            return;
+          }
+        }
+
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        await deleteFsPath(client, context, inputPath, {
+          force: options.force,
+          recursive: options.recursive,
+        });
+        console.log(`${pc.green('✓')} deleted ${pc.bold(inputPath)}`);
+      },
+    );
+
+  fsCommand
+    .command('cp <source> <destination>')
+    .description('Copy a VFS node')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('-f, --force', 'Overwrite the destination if it exists')
+    .action(
+      async (
+        source: string,
+        destination: string,
+        options: { agentId?: string; force?: boolean; slug?: string; topicId?: string },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const result = await copyFsPath(client, context, source, destination, options.force);
+        console.log(
+          `${pc.green('✓')} copied ${pc.bold(source)} → ${pc.bold(toDisplayPath(result?.path ?? destination))}`,
+        );
+      },
+    );
+
+  fsCommand
+    .command('mv <source> <destination>')
+    .description('Move or rename a VFS node')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('-f, --force', 'Overwrite the destination if it exists')
+    .action(
+      async (
+        source: string,
+        destination: string,
+        options: { agentId?: string; force?: boolean; slug?: string; topicId?: string },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const sourceResolved = resolveAgentFsPath(source);
+        const destinationResolved = resolveAgentFsPath(destination);
+
+        if (sourceResolved.path === destinationResolved.path) {
+          console.log(`${pc.yellow('!')} source and destination are the same.`);
+          return;
+        }
+
+        const result = await renameFsPath(client, context, source, destination, options.force);
+        console.log(
+          `${pc.green('✓')} moved ${pc.bold(source)} → ${pc.bold(toDisplayPath(result?.path ?? destination))}`,
+        );
+      },
+    );
+
+  const trashCommand = fsCommand.command('trash').description('Operate on soft-deleted VFS nodes');
+
+  trashCommand
+    .command('ls [path]')
+    .description('List trashed VFS nodes')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('--json [fields]', 'Output JSON, optionally specify fields (comma-separated)')
+    .action(
+      async (
+        inputPath: string | undefined,
+        options: {
+          agentId?: string;
+          json?: string | boolean;
+          slug?: string;
+          topicId?: string;
+        },
+      ) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const nodes = await listTrashFsPath(client, context, inputPath);
+
+        if (options.json !== undefined) {
+          const fields = typeof options.json === 'string' ? options.json : undefined;
+          outputJson(nodes, fields);
+          return;
+        }
+
+        if (nodes.length === 0) {
+          console.log('Trash is empty.');
+          return;
+        }
+
+        nodes.forEach((node) => console.log(toDisplayPath(node.path)));
+      },
+    );
+
+  trashCommand
+    .command('restore <path>')
+    .description('Restore a soft-deleted VFS node')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .action(
+      async (inputPath: string, options: { agentId?: string; slug?: string; topicId?: string }) => {
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        const result = await restoreTrashFsPath(client, context, inputPath);
+        console.log(
+          `${pc.green('✓')} restored ${pc.bold(toDisplayPath(result?.path ?? inputPath))}`,
+        );
+      },
+    );
+
+  trashCommand
+    .command('rm <path>')
+    .description('Permanently delete a trashed VFS node')
+    .option('-A, --agent-id <id>', 'Agent ID')
+    .option('-s, --slug <slug>', 'Agent slug')
+    .option('-r, --recursive', 'Recursively delete a directory subtree')
+    .option('-f, --force', 'Forward force semantics to the permanent delete primitive')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(
+      async (
+        inputPath: string,
+        options: {
+          agentId?: string;
+          force?: boolean;
+          recursive?: boolean;
+          slug?: string;
+          topicId?: string;
+          yes?: boolean;
+        },
+      ) => {
+        if (!options.yes) {
+          const confirmed = await confirm(`Permanently delete ${inputPath}?`);
+          if (!confirmed) {
+            console.log('Cancelled.');
+            return;
+          }
+        }
+
+        const client = await getTrpcClient();
+        const context = await resolveAgentFsContext(client, options);
+        await deleteTrashFsPath(client, context, inputPath, {
+          force: options.force,
+          recursive: options.recursive,
+        });
+        console.log(`${pc.green('✓')} permanently deleted ${pc.bold(inputPath)}`);
+      },
+    );
+}
+
+/**
+ * Register agent document VFS commands under `agent space fs`.
+ *
+ * Use when:
+ * - The CLI should expose filesystem-like operations for an agent document space.
+ * - Command registration should stay outside the core `agent` command file.
+ *
+ * Expects:
+ * - `agentCommand` to be the existing `agent` command group.
+ *
+ * Returns:
+ * - Registered Commander subcommands.
+ */
+export function registerAgentSpaceFsCommand(agentCommand: Command) {
+  const spaceCommand = agentCommand.command('space').description('Manage agent document space');
+  const fsCommand = spaceCommand.command('fs').description('Operate on the agent document VFS');
+  registerFsCommands(fsCommand);
+}
@@ -6,8 +6,56 @@ import { getTrpcClient } from '../api/client';
 import { confirm, outputJson, printBoxTable, printTable, timeAgo } from '../utils/format';
 import { log } from '../utils/logger';
 import { registerBotMessageCommands } from './botMessage';
+import { registerBotMessengersCommands } from './botMessengers';

-// ── Helpers ──────────────────────────────────────────────
+// ── Access policy helpers ──────────────────────────────
+
+const DM_POLICIES = ['open', 'allowlist', 'pairing', 'disabled'] as const;
+const GROUP_POLICIES = ['open', 'allowlist', 'disabled'] as const;
+type DmPolicy = (typeof DM_POLICIES)[number];
+type GroupPolicy = (typeof GROUP_POLICIES)[number];
+
+interface AllowEntry {
+  id: string;
+  name?: string;
+}
+
+/**
+ * Normalize an allow-list value into `{id, name?}[]`. Mirrors the server-side
+ * back-compat parser — `settings.allowFrom` may be on disk as a comma-separated
+ * string, a bare `string[]`, or the current `{id, name?}[]` shape. The CLI
+ * needs the canonical form before push/filter operations and before sending
+ * back to the server.
+ */
+function normalizeAllowList(raw: unknown): AllowEntry[] {
+  if (typeof raw === 'string') {
+    return raw
+      .split(/[\s,]+/)
+      .map((id) => id.trim())
+      .filter(Boolean)
+      .map((id) => ({ id }));
+  }
+  if (!Array.isArray(raw)) return [];
+  const out: AllowEntry[] = [];
+  for (const entry of raw) {
+    if (typeof entry === 'string') {
+      const id = entry.trim();
+      if (id) out.push({ id });
+      continue;
+    }
+    if (entry && typeof entry === 'object' && 'id' in entry) {
+      const id = (entry as { id?: unknown }).id;
+      if (typeof id !== 'string' || !id.trim()) continue;
+      const name = (entry as { name?: unknown }).name;
+      out.push(
+        typeof name === 'string' && name.trim()
+          ? { id: id.trim(), name: name.trim() }
+          : { id: id.trim() },
+      );
+    }
+  }
+  return out;
+}

 function maskValue(val: string): string {
  if (val.length > 8) return val.slice(0, 4) + '****' + val.slice(-4);
@@ -78,6 +126,348 @@ async function resolvePlatform(client: TrpcClient, platformId: string) {
  return def;
 }

+// ── Allowlist subcommand factory ────────────────────────
+
+interface AllowlistGroupOptions {
+  /** Description shown by `lh bot <name> --help`. */
+  description: string;
+  /** Settings field to mutate — `allowFrom` (user IDs) or `groupAllowFrom` (channel IDs). */
+  fieldKey: 'allowFrom' | 'groupAllowFrom';
+  /** Human-friendly description of what the `<id>` arg represents. */
+  idLabel: string;
+  /** Subcommand group name (`allowlist` or `group-allowlist`). */
+  name: string;
+}
+
+/**
+ * Build a `list / add / remove / clear` subcommand group around an
+ * array-typed settings field (`allowFrom` or `groupAllowFrom`). All write
+ * paths read existing settings first and merge — passing only a partial
+ * `settings` object to the TRPC `update` would replace the whole JSONB
+ * column and silently drop unrelated fields.
+ */
+function registerAllowlistCommand(bot: Command, opts: AllowlistGroupOptions) {
+  const group = bot.command(opts.name).description(opts.description);
+
+  // Read the current entries off a freshly-fetched bot row.
+  const readEntries = (bot: any): AllowEntry[] =>
+    normalizeAllowList((bot.settings as Record<string, unknown> | null)?.[opts.fieldKey]);
+
+  // Build the next settings payload from existing settings + the new entries.
+  const buildPayload = (bot: any, nextEntries: AllowEntry[]) => ({
+    id: bot.id,
+    settings: {
+      ...(bot.settings as Record<string, unknown>),
+      [opts.fieldKey]: nextEntries,
+    },
+  });
+
+  group
+    .command('list <botId>')
+    .description(`List ${opts.fieldKey} entries`)
+    .option('--json', 'Output JSON')
+    .action(async (botId: string, options: { json?: boolean }) => {
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      if (options.json) {
+        outputJson(entries);
+        return;
+      }
+
+      if (entries.length === 0) {
+        console.log(`${pc.dim(`No ${opts.fieldKey} entries.`)}`);
+        return;
+      }
+
+      printTable(
+        entries.map((e) => [e.id, e.name ?? pc.dim('-')]),
+        ['ID', 'NAME'],
+      );
+    });
+
+  group
+    .command('add <botId> <id>')
+    .description(`Add a ${opts.idLabel} to ${opts.fieldKey}`)
+    .option('--name <name>', 'Optional human-friendly label so you can recognise the entry later')
+    .action(async (botId: string, id: string, options: { name?: string }) => {
+      const trimmedId = id.trim();
+      if (!trimmedId) {
+        log.error('ID cannot be empty.');
+        process.exit(1);
+        return;
+      }
+
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      if (entries.some((e) => e.id === trimmedId)) {
+        log.info(`${trimmedId} is already on the ${opts.fieldKey} list — nothing to do.`);
+        return;
+      }
+
+      const trimmedName = options.name?.trim();
+      const next = [
+        ...entries,
+        trimmedName ? { id: trimmedId, name: trimmedName } : { id: trimmedId },
+      ];
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, next) as any);
+      console.log(
+        `${pc.green('✓')} Added ${pc.bold(trimmedId)}${trimmedName ? ` (${trimmedName})` : ''} to ${opts.fieldKey} (now ${next.length} entr${next.length === 1 ? 'y' : 'ies'})`,
+      );
+    });
+
+  group
+    .command('remove <botId> <id>')
+    .description(`Remove a ${opts.idLabel} from ${opts.fieldKey}`)
+    .action(async (botId: string, id: string) => {
+      const trimmedId = id.trim();
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+      const next = entries.filter((e) => e.id !== trimmedId);
+
+      if (next.length === entries.length) {
+        log.info(`${trimmedId} is not on the ${opts.fieldKey} list — nothing to do.`);
+        return;
+      }
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, next) as any);
+      console.log(
+        `${pc.green('✓')} Removed ${pc.bold(trimmedId)} from ${opts.fieldKey} (${next.length} entr${next.length === 1 ? 'y' : 'ies'} left)`,
+      );
+    });
+
+  group
+    .command('clear <botId>')
+    .description(`Clear all entries from ${opts.fieldKey}`)
+    .option('--yes', 'Skip confirmation prompt')
+    .action(async (botId: string, options: { yes?: boolean }) => {
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      if (entries.length === 0) {
+        log.info(`${opts.fieldKey} is already empty — nothing to do.`);
+        return;
+      }
+
+      if (!options.yes) {
+        const confirmed = await confirm(
+          `Clear all ${entries.length} ${opts.fieldKey} entr${entries.length === 1 ? 'y' : 'ies'} from this bot?`,
+        );
+        if (!confirmed) {
+          console.log('Cancelled.');
+          return;
+        }
+      }
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, []) as any);
+      console.log(`${pc.green('✓')} Cleared ${opts.fieldKey} on bot ${pc.bold(botId)}`);
+    });
+}
+
+// ── Watch keywords subcommand factory ──────────────────
+
+interface WatchKeywordEntry {
+  instruction?: string;
+  keyword: string;
+}
+
+/**
+ * Normalise `settings.watchKeywords` into the canonical
+ * `{keyword, instruction?}[]` shape. Mirrors `extractWatchKeywordEntries`
+ * in `src/server/services/bot/platforms/const.ts` so the CLI accepts the
+ * same legacy on-disk shapes (`string`, `string[]`, `{keyword, …}[]`)
+ * the runtime is forgiving about — including the rare comma/whitespace
+ * separated string from a hand-pasted upgrade.
+ */
+function normalizeWatchKeywords(raw: unknown): WatchKeywordEntry[] {
+  const push = (out: Map<string, WatchKeywordEntry>, keyword: unknown, instruction?: unknown) => {
+    if (typeof keyword !== 'string') return;
+    const normalised = keyword.trim().toLowerCase();
+    if (!normalised) return;
+    const trimmedInstruction =
+      typeof instruction === 'string' && instruction.trim() ? instruction.trim() : undefined;
+    const existing = out.get(normalised);
+    if (!existing) {
+      out.set(normalised, { instruction: trimmedInstruction, keyword: normalised });
+      return;
+    }
+    if (!existing.instruction && trimmedInstruction) existing.instruction = trimmedInstruction;
+  };
+  const collected = new Map<string, WatchKeywordEntry>();
+  if (typeof raw === 'string') {
+    for (const piece of raw.split(/[\s,]+/)) push(collected, piece);
+  } else if (Array.isArray(raw)) {
+    for (const entry of raw) {
+      if (typeof entry === 'string') {
+        push(collected, entry);
+        continue;
+      }
+      if (entry && typeof entry === 'object' && 'keyword' in entry) {
+        const obj = entry as { instruction?: unknown; keyword?: unknown };
+        push(collected, obj.keyword, obj.instruction);
+      }
+    }
+  }
+  return [...collected.values()];
+}
+
+/**
+ * Build a `list / add / remove / clear` subcommand group around
+ * `settings.watchKeywords`. Shape differs from the user/channel allowlists
+ * (`{keyword, instruction?}` vs `{id, name?}`), so we duplicate the
+ * scaffolding instead of squeezing both shapes through one factory — the
+ * help text, column headers, and `--instruction` flag are all keyword-
+ * specific and would just bloat the unified version.
+ */
+function registerWatchKeywordsCommand(bot: Command) {
+  const group = bot
+    .command('watch-keywords')
+    .description(
+      'Manage watch keywords (non-mention channel triggers; the optional instruction is prepended to the user message before being sent to the AI)',
+    );
+
+  const readEntries = (bot: any): WatchKeywordEntry[] =>
+    normalizeWatchKeywords((bot.settings as Record<string, unknown> | null)?.watchKeywords);
+
+  const buildPayload = (bot: any, nextEntries: WatchKeywordEntry[]) => ({
+    id: bot.id,
+    settings: {
+      ...(bot.settings as Record<string, unknown>),
+      watchKeywords: nextEntries,
+    },
+  });
+
+  group
+    .command('list <botId>')
+    .description('List watch-keyword entries')
+    .option('--json', 'Output JSON')
+    .action(async (botId: string, options: { json?: boolean }) => {
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      if (options.json) {
+        outputJson(entries);
+        return;
+      }
+
+      if (entries.length === 0) {
+        console.log(`${pc.dim('No watch-keyword entries.')}`);
+        return;
+      }
+
+      printTable(
+        entries.map((e) => [e.keyword, e.instruction ?? pc.dim('-')]),
+        ['KEYWORD', 'INSTRUCTION'],
+      );
+    });
+
+  group
+    .command('add <botId> <keyword>')
+    .description('Add a watch keyword (with optional instruction prefix)')
+    .option(
+      '--instruction <text>',
+      'Prompt prepended to the user message when this keyword fires (omit for "just wake the bot")',
+    )
+    .action(async (botId: string, keyword: string, options: { instruction?: string }) => {
+      const trimmedKeyword = keyword.trim().toLowerCase();
+      if (!trimmedKeyword) {
+        log.error('Keyword cannot be empty.');
+        process.exit(1);
+        return;
+      }
+
+      const trimmedInstruction = options.instruction?.trim();
+
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      const existing = entries.find((e) => e.keyword === trimmedKeyword);
+      if (existing) {
+        // Upsert instruction on duplicate keyword — operators commonly
+        // re-run `add` to tweak the prompt without remembering to remove first.
+        if (trimmedInstruction && existing.instruction !== trimmedInstruction) {
+          existing.instruction = trimmedInstruction;
+          await client.agentBotProvider.update.mutate(buildPayload(b, entries) as any);
+          console.log(
+            `${pc.green('✓')} Updated instruction for ${pc.bold(trimmedKeyword)} (${entries.length} entr${entries.length === 1 ? 'y' : 'ies'})`,
+          );
+          return;
+        }
+        log.info(`${trimmedKeyword} is already on watchKeywords — nothing to do.`);
+        return;
+      }
+
+      const next = [
+        ...entries,
+        trimmedInstruction
+          ? { instruction: trimmedInstruction, keyword: trimmedKeyword }
+          : { keyword: trimmedKeyword },
+      ];
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, next) as any);
+      console.log(
+        `${pc.green('✓')} Added ${pc.bold(trimmedKeyword)}${trimmedInstruction ? ' (with instruction)' : ''} to watchKeywords (now ${next.length} entr${next.length === 1 ? 'y' : 'ies'})`,
+      );
+    });
+
+  group
+    .command('remove <botId> <keyword>')
+    .description('Remove a watch keyword')
+    .action(async (botId: string, keyword: string) => {
+      const trimmedKeyword = keyword.trim().toLowerCase();
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+      const next = entries.filter((e) => e.keyword !== trimmedKeyword);
+
+      if (next.length === entries.length) {
+        log.info(`${trimmedKeyword} is not on watchKeywords — nothing to do.`);
+        return;
+      }
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, next) as any);
+      console.log(
+        `${pc.green('✓')} Removed ${pc.bold(trimmedKeyword)} from watchKeywords (${next.length} entr${next.length === 1 ? 'y' : 'ies'} left)`,
+      );
+    });
+
+  group
+    .command('clear <botId>')
+    .description('Clear all watch keywords')
+    .option('--yes', 'Skip confirmation prompt')
+    .action(async (botId: string, options: { yes?: boolean }) => {
+      const client = await getTrpcClient();
+      const b = await findBot(client, botId);
+      const entries = readEntries(b);
+
+      if (entries.length === 0) {
+        log.info('watchKeywords is already empty — nothing to do.');
+        return;
+      }
+
+      if (!options.yes) {
+        const confirmed = await confirm(
+          `Clear all ${entries.length} watch-keyword entr${entries.length === 1 ? 'y' : 'ies'} from this bot?`,
+        );
+        if (!confirmed) {
+          console.log('Cancelled.');
+          return;
+        }
+      }
+
+      await client.agentBotProvider.update.mutate(buildPayload(b, []) as any);
+      console.log(`${pc.green('✓')} Cleared watchKeywords on bot ${pc.bold(botId)}`);
+    });
+}
+
 // ── Command Registration ─────────────────────────────────

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

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

  bot
@@ -313,6 +706,16 @@ export function registerBotCommand(program: Command) {
    .option('--verification-token <token>', 'New verification token')
    .option('--app-id <appId>', 'New application ID')
    .option('--platform <platform>', 'New platform')
+    .option(
+      '--dm-policy <policy>',
+      `DM access policy (${DM_POLICIES.join('|')}). 'pairing' requires --user-id.`,
+    )
+    .option('--group-policy <policy>', `Group/channel access policy (${GROUP_POLICIES.join('|')})`)
+    .option(
+      '--user-id <id>',
+      "Owner's platform user ID (required for --dm-policy=pairing; auto-trusts the operator in the global allowlist)",
+    )
+    .option('--server-id <id>', 'Default server / guild / workspace ID for AI tool calls')
    .action(
      async (
        botId: string,
@@ -321,11 +724,15 @@ export function registerBotCommand(program: Command) {
          appSecret?: string;
          botId?: string;
          botToken?: string;
+          dmPolicy?: string;
          encryptKey?: string;
+          groupPolicy?: string;
          platform?: string;
          publicKey?: string;
          secretToken?: string;
+          serverId?: string;
          signingSecret?: string;
+          userId?: string;
          verificationToken?: string;
          webhookProxyUrl?: string;
        },
@@ -342,6 +749,40 @@ export function registerBotCommand(program: Command) {
        if (options.appId) input.applicationId = options.appId;
        if (options.platform) input.platform = options.platform;

+        // ── Settings (DM / group policy + identity fields) ────────────
+        // Read-modify-write so we don't wipe `allowFrom`, `groupAllowFrom`,
+        // or any other settings field the operator already configured.
+        const settingsPatch: Record<string, unknown> = {};
+        if (options.dmPolicy !== undefined) {
+          if (!(DM_POLICIES as readonly string[]).includes(options.dmPolicy)) {
+            log.error(
+              `Invalid --dm-policy "${options.dmPolicy}". Must be one of: ${DM_POLICIES.join(', ')}`,
+            );
+            process.exit(1);
+            return;
+          }
+          settingsPatch.dmPolicy = options.dmPolicy as DmPolicy;
+        }
+        if (options.groupPolicy !== undefined) {
+          if (!(GROUP_POLICIES as readonly string[]).includes(options.groupPolicy)) {
+            log.error(
+              `Invalid --group-policy "${options.groupPolicy}". Must be one of: ${GROUP_POLICIES.join(', ')}`,
+            );
+            process.exit(1);
+            return;
+          }
+          settingsPatch.groupPolicy = options.groupPolicy as GroupPolicy;
+        }
+        if (options.userId !== undefined) settingsPatch.userId = options.userId;
+        if (options.serverId !== undefined) settingsPatch.serverId = options.serverId;
+
+        if (Object.keys(settingsPatch).length > 0) {
+          input.settings = {
+            ...(existing.settings as Record<string, unknown>),
+            ...settingsPatch,
+          };
+        }
+
        if (Object.keys(input).length <= 1) {
          log.error('No changes specified.');
          process.exit(1);
@@ -353,6 +794,26 @@ export function registerBotCommand(program: Command) {
      },
    );

+  // ── allowlist (DM / group user gate) ──────────────────
+
+  registerAllowlistCommand(bot, {
+    description: 'Manage the global user allowlist (gates DMs and group @mentions)',
+    fieldKey: 'allowFrom',
+    idLabel: 'platform user ID',
+    name: 'allowlist',
+  });
+
+  registerAllowlistCommand(bot, {
+    description: 'Manage the group/channel allowlist (used when groupPolicy=allowlist)',
+    fieldKey: 'groupAllowFrom',
+    idLabel: 'channel / group / thread ID',
+    name: 'group-allowlist',
+  });
+
+  // ── watch-keywords () ────────────────────────
+
+  registerWatchKeywordsCommand(bot);
+
  // ── remove ────────────────────────────────────────────

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

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

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

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

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

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

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

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