JARVIS/frontend/orchestration_panel_plan.md

# AI Control Orchestration Panel Plan

## Goal
Add a minimal viable right-side `JARVIS CONTROL` panel to the chat page that visualizes real-time agent orchestration from existing stream progress events while keeping the main conversation as the primary reading surface.

## Scope
- Frontend-only V1
- Reuse existing stream payload fields: `stage`, `agent`, `tool_name`, `step`, `steps`
- No persistence into conversation history
- Auto-open on send, auto-close shortly after success or error

## Recommended implementation

### 1. Add a dedicated orchestration panel component
Create a presentational component, e.g. `frontend/src/components/chat/OrchestrationPanel.vue`, responsible only for rendering:
- Header: `JARVIS CONTROL`, current phase, status chip (`ACTIVE`, `COMPLETE`, `ERROR`)
- Vertical agent bus:
  - `JARVIS`
  - `planner`
  - `executor`
  - `analyst`
  - `librarian`
- Recent event feed limited to the latest 3-5 items

Keep rendering logic out of `index.vue` as much as possible so the page stays manageable.

### 2. Expand transient chat-view state in `useChatView.ts`
Replace the single `thinkingState`-only UX with a richer transient orchestration session owned by the composable. Suggested state shape:
- `thinkingState`: preserve current raw progress snapshot for compatibility
- `orchestrationPanelVisible: boolean`
- `orchestrationStatus: 'idle' | 'active' | 'complete' | 'error'`
- `activeAgent: string | null`
- `visitedAgents: string[]`
- `eventFeed: Array<{ id: string; label: string; kind: 'info' | 'tool' | 'success' | 'error' }>`
- `panelPhaseLabel: string`
- `closeTimer` handle for delayed auto-close

This state should be reset at the start of each `sendMessage()` call and never written into the conversation store.

### 3. Map existing stream events into panel state
Inside `conversationApi.chatStream(...).onProgress`:
- Open the panel on the first progress event if not already visible
- Update `thinkingState` as today
- Derive a display phase from `payload.stage`
- Set `activeAgent` from `payload.agent`
- Add `payload.agent` to `visitedAgents` if new
- Push short event-feed items using priority:
  1. `payload.step`
  2. `payload.tool_name` -> `调用工具 · {tool}`
  3. `payload.label`
- If `payload.steps` exists, only surface the first meaningful item as an event instead of dumping the whole list into the panel
- Trim event feed to latest 5 entries

### 4. Change completion behavior
Current code clears `thinkingState` immediately after stream completion or error. For the new experience:
- On success:
  - set panel status to `complete`
  - add a final event like `响应已生成`
  - append assistant message to store as today
  - keep panel visible for ~1000-1500ms, then hide and reset transient panel state
- On error:
  - set panel status to `error`
  - add error event using the error message
  - keep panel visible slightly longer (e.g. ~1600ms), then hide and reset

This preserves the cinematic finish while keeping the panel ephemeral.

### 5. Update page layout in `src/pages/chat/index.vue`
Restructure the main chat area so the central chat surface and right-side orchestration panel can coexist:
- Keep existing left session sidebar unchanged
- Wrap the current chat section and new panel in a horizontal content shell
- Mount `<OrchestrationPanel ... />` to the right of the message/input area
- Only show the panel when `orchestrationPanelVisible` is true
- Keep the inline thinking bubble minimal or remove most of its detail once the side panel is active, so the UI does not duplicate orchestration information in two places

### 6. Styling direction
V1 styling should match the approved “AI control center” concept:
- narrow right panel (`~340px`)
- dark glass background, subtle cyan edge glow
- vertical bus with one large `JARVIS` node and four smaller agent nodes
- active node: bright border + pulse
- visited node: low residual glow
- event feed: compact short system phrases
- entrance/exit: slide + fade

## File-level change plan

### `frontend/src/pages/chat/composables/useChatView.ts`
- Add orchestration session state and reset helpers
- Add progress-to-panel mapping helper
- Add delayed close helper
- Preserve existing send/stream logic while extending transient UI state

### `frontend/src/pages/chat/index.vue`
- Import panel component
- Bind panel props from `useChatView()`
- Adjust layout to support central chat + right panel
- Reduce duplication between inline thinking bubble and right-side orchestration UI

### `frontend/src/components/chat/OrchestrationPanel.vue`
- New component for header, agent bus, event feed, and status visualization

## Suggested event text mapping
- `thinking` -> `请求接入`, `语义解析中`
- `planning` -> `任务拆解中`, `生成执行路径`
- `tool` + tool name -> `调用工具 · {tool_name}`
- `responding` -> `正在汇总响应`
- success -> `响应已生成`
- error -> `任务执行中断`

## Risks and mitigations
- **Duplicate cognition with inline thinking bubble**: keep the bubble lightweight once panel exists
- **Too many events**: cap the feed to 5 and dedupe consecutive identical labels
- **Panel state leaking across conversation switches**: reset on `newConversation()` and `selectConversation()` when appropriate
- **Abrupt close**: use short delayed close timers and clear any existing timer before starting a new request

## Verification checklist
1. Send a message and confirm the right panel slides in before the final assistant bubble appears.
2. Confirm active agent highlighting changes as stream progress changes.
3. Confirm event feed shows short orchestration phrases, not raw backend payload dumps.
4. Confirm the panel auto-closes shortly after success.
5. Confirm the panel shows error state briefly, then closes on failure.
6. Confirm switching conversations or starting a new one does not preserve the previous request's orchestration state.
7. Confirm the main chat remains the dominant reading surface and the panel does not push message content into unreadable widths.