feat: add comprehensive CCWMCP guide and installation instructions

2026-03-01 15:03:57 +08:00 · 2026-02-28 23:40:51 +08:00
parent 096fc1c380
commit 0a49dc0675
13 changed files with 2298 additions and 103 deletions
--- a/docs/features/dashboard.md
+++ b/docs/features/dashboard.md
@@ -1,8 +1,8 @@
-# Dashboard Panel
+# Dashboard

 ## One-Liner

-**The Dashboard is a VS Code webview-based management interface** — Provides visual access to project configuration, specs, memory, and settings through an intuitive GUI.
+**The Dashboard provides an at-a-glance overview of your project's workflow status, statistics, and recent activity through an intuitive widget-based interface.**

 ---

@@ -10,10 +10,48 @@

 | Pain Point | Current State | Dashboard Solution |
 |------------|---------------|-------------------|
-| **Config complexity** | JSON files hard to edit | Visual form-based editing |
-| **No overview** | Can't see project state at a glance | Unified dashboard view |
-| **Scattered settings** | Settings in multiple files | Centralized management |
-| **No visual feedback** | CLI only, no UI | Interactive webview |
+| **No project visibility** | Can't see overall project health | Project info banner with tech stack and development index |
+| **Scattered metrics** | Stats across multiple locations | Centralized statistics with sparklines |
+| **Unknown workflow status** | Hard to track session progress | Pie chart with status breakdown |
+| **Lost in recent work** | No quick access to active sessions | Session carousel with task details |
+| **Indexing status unclear** | Don't know if code is indexed | Real-time index status indicator |
+
+---
+
+## Page Overview
+
+**Location**: `ccw/frontend/src/pages/HomePage.tsx`
+
+**Purpose**: Dashboard home page providing project overview, statistics, workflow status, and recent activity monitoring.
+
+**Access**: Navigation → Dashboard (default home page)
+
+### Layout
+
+```
+--------------------------------------------------------------------------+
+|  Dashboard Header (title + refresh)                                      |
+--------------------------------------------------------------------------+
+|  WorkflowTaskWidget (Combined Card)                                      |
+|  +--------------------------------------------------------------------+  |
+|  | Project Info Banner (expandable)                                   |  |
+|  | - Project name, description, tech stack badges                      |  |
+|  | - Quick stats (features, bugfixes, enhancements)                    |  |
+|  | - Index status indicator                                           |  |
+|  +----------------------------------+---------------------------------+  |
+|  | Stats Section | Workflow Status |  Task Details (Carousel)     |  |
+|  | - 6 mini cards | - Pie chart     | - Session nav                 |  |
+|  | - Sparklines   | - Legend       | - Task list (2 columns)       |  |
+|  +----------------+-----------------+-------------------------------+  |
+--------------------------------------------------------------------------+
+|  RecentSessionsWidget                                                     |
+|  +--------------------------------------------------------------------+  |
+|  | Tabs: All Tasks | Workflow | Lite Tasks                           |  |
+|  | +---------------+---------------+-------------------------------+ |  |
+|  | | Task cards with status, progress, tags, time                     | |  |
+|  | +---------------------------------------------------------------+ |  |
+--------------------------------------------------------------------------+
+```

 ---

@@ -21,59 +59,94 @@

 | Feature | Description |
 |---------|-------------|
-| **Project Overview** | Tech stack, dependencies, status |
-| **Spec Manager** | View and edit specification files |
-| **Memory Viewer** | Browse persistent memories |
-| **API Settings** | Configure AI model endpoints |
-| **System Settings** | Global and project settings |
+| **Project Info Banner** | Expandable banner showing project name, description, tech stack (languages, frameworks, architecture), development index (features/bugfixes/enhancements), and real-time index status |
+| **Statistics Section** | 6 mini stat cards (Active Sessions, Total Tasks, Completed Tasks, Pending Tasks, Failed Tasks, Today Activity) with 7-day sparkline trends |
+| **Workflow Status Pie Chart** | Donut chart showing session status breakdown (completed, in progress, planning, paused, archived) with percentages |
+| **Session Carousel** | Auto-rotating (5s) session cards with task list, progress bar, and manual navigation arrows |
+| **Recent Sessions Widget** | Tabbed view of recent tasks across all task types with filtering, status badges, and progress indicators |
+| **Real-time Updates** | Auto-refresh every 60 seconds for stats and 30 seconds for index status |

 ---

-## Access
+## Usage Guide

-Open via VS Code command palette:
-```
-CCW: Open Dashboard
-```
+### Basic Workflow

-Or via CLI:
-```bash
-ccw view
-```
+1. **View Project Overview**: Check the project info banner for tech stack and development index
+2. **Monitor Statistics**: Review mini stat cards for current project metrics and trends
+3. **Track Workflow Status**: View pie chart for session status distribution
+4. **Browse Active Sessions**: Use session carousel to see task details and progress
+5. **Access Recent Work**: Switch between All Tasks/Workflow/Lite Tasks tabs to find specific sessions
+
+### Key Interactions
+
+| Interaction | How to Use |
+|-------------|------------|
+| **Expand Project Details** | Click the chevron button in the project banner to show architecture, components, patterns |
+| **Navigate Sessions** | Click arrow buttons or wait for auto-rotation (5s interval) in the carousel |
+| **View Session Details** | Click on any session card to navigate to session detail page |
+| **Filter Recent Tasks** | Click tab buttons to filter by task type (All/Workflow/Lite) |
+| **Refresh Dashboard** | Click the refresh button in the header to reload all data |
+
+### Index Status Indicator
+
+| Status | Icon | Meaning |
+|--------|------|---------|
+| **Building** | Pulsing blue dot | Code index is being built/updated |
+| **Completed** | Green dot | Index is up-to-date |
+| **Idle** | Gray dot | Index status is unknown/idle |
+| **Failed** | Red dot | Index build failed |

 ---

-## Dashboard Sections
+## Components Reference

-### 1. Project Overview
- Technology stack detection
- Dependency status
- Workflow session status
+### Main Components

-### 2. Spec Manager
- List all specs
- Edit spec content
- Enable/disable specs
+| Component | Location | Purpose |
+|-----------|----------|---------|
+| `DashboardHeader` | `@/components/dashboard/DashboardHeader.tsx` | Page header with title and refresh action |
+| `WorkflowTaskWidget` | `@/components/dashboard/widgets/WorkflowTaskWidget.tsx` | Combined widget with project info, stats, workflow status, and session carousel |
+| `RecentSessionsWidget` | `@/components/dashboard/widgets/RecentSessionsWidget.tsx` | Recent sessions across workflow and lite tasks |
+| `MiniStatCard` | (internal to WorkflowTaskWidget) | Individual stat card with optional sparkline |
+| `HomeEmptyState` | (internal to WorkflowTaskWidget) | Empty state display when no sessions exist |

-### 3. Memory Viewer
- Browse memory entries
- Search memories
- Export/import
+### State Management

-### 4. API Settings
- Configure API keys
- Set model endpoints
- Manage rate limits
+- **Local state**:
+  - `hasError` - Error tracking for critical failures
+  - `projectExpanded` - Project info banner expansion state
+  - `currentSessionIndex` - Active session in carousel
+  - `activeTab` - Recent sessions widget filter tab

-### 5. System Settings
- Global configuration
- Project overrides
- Hook management
+- **Custom hooks**:
+  - `useWorkflowStatusCounts` - Session status distribution data
+  - `useDashboardStats` - Statistics with auto-refresh (60s)
+  - `useProjectOverview` - Project information and tech stack
+  - `useIndexStatus` - Real-time index status (30s refresh)
+  - `useSessions` - Active sessions data
+  - `useLiteTasks` - Lite tasks data for recent widget
+
+---
+
+## Configuration
+
+No configuration required. The dashboard automatically fetches data from the backend.
+
+### Auto-Refresh Intervals
+
+| Data Type | Interval |
+|-----------|----------|
+| Dashboard stats | 60 seconds |
+| Index status | 30 seconds |
+| Discovery sessions | 3 seconds (on discovery page) |

 ---

 ## Related Links

- [API Settings](/features/api-settings) - API configuration
- [System Settings](/features/system-settings) - System configuration
- [Spec System](/features/spec) - Specification management
+- [Sessions](/features/sessions) - View and manage all sessions
+- [Queue](/features/queue) - Issue execution queue management
+- [Discovery](/features/discovery) - Discovery session tracking
+- [Memory](/features/memory) - Persistent memory management
+- [System Settings](/features/system-settings) - Global application settings