mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-01 15:03:57 +08:00
feat: add comprehensive CCWMCP guide and installation instructions
This commit is contained in:
catlog22
@@ -4,10 +4,6 @@
|
||||
<section class="hero-section">
|
||||
<div class="hero-container">
|
||||
<div class="hero-content">
|
||||
<div class="hero-badge">
|
||||
<span class="pulse-dot"></span>
|
||||
{{ t.badge }}
|
||||
</div>
|
||||
<h1 class="hero-title" v-html="t.heroTitle"></h1>
|
||||
<p class="hero-subtitle">{{ t.heroSubtitle }}</p>
|
||||
|
||||
@@ -154,7 +150,7 @@
|
||||
<svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z"/><polyline points="14 2 14 8 20 8"/></svg>
|
||||
workflow.json
|
||||
</div>
|
||||
<pre class="font-mono"><code>{{ workflowJson }}</code></pre>
|
||||
<pre class="font-mono json-pre"><code v-html="highlightedWorkflowJson"></code></pre>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
@@ -446,19 +442,59 @@ const sequence = [
|
||||
]
|
||||
const currentStep = computed(() => sequence[currentTick.value])
|
||||
|
||||
const workflowJson = `{
|
||||
"project": "next-gen-api",
|
||||
"cadence": "strict-sync",
|
||||
"team": {
|
||||
"arch": { "cli": "gemini" },
|
||||
"coder": { "cli": "qwen" },
|
||||
"audit": { "cli": "codex" }
|
||||
},
|
||||
"stages": [
|
||||
{ "id": "design", "agent": "arch" },
|
||||
{ "id": "impl", "agent": "coder" }
|
||||
// JSON with syntax highlighting and tooltips
|
||||
const jsonTooltips = {
|
||||
'project': '项目名称，用于标识工作流实例',
|
||||
'cadence': '节拍模式：strict-sync(严格同步) | async(异步) | hybrid(混合)',
|
||||
'team': '团队成员配置，每个角色映射到特定 CLI 工具',
|
||||
'arch': '架构师角色：负责系统设计和文档生成',
|
||||
'coder': '开发者角色：负责代码实现',
|
||||
'audit': '审计员角色：负责质量检查和代码审查',
|
||||
'cli': 'CLI 工具：gemini | qwen | codex | claude',
|
||||
'stages': '执行阶段定义，按顺序执行',
|
||||
'id': '阶段唯一标识符',
|
||||
'agent': '执行该阶段的团队成员角色'
|
||||
}
|
||||
|
||||
const highlightedWorkflowJson = computed(() => {
|
||||
const lines = [
|
||||
{ text: '{', type: 'bracket' },
|
||||
{ text: ' "project": "next-gen-api",', key: 'project', type: 'string' },
|
||||
{ text: ' "cadence": "strict-sync",', key: 'cadence', type: 'string' },
|
||||
{ text: ' "team": {', key: 'team', type: 'object' },
|
||||
{ text: ' "arch": { "cli": "gemini" },', key: 'arch', type: 'object' },
|
||||
{ text: ' "coder": { "cli": "qwen" },', key: 'coder', type: 'object' },
|
||||
{ text: ' "audit": { "cli": "codex" }', key: 'audit', type: 'object' },
|
||||
{ text: ' },', type: 'bracket' },
|
||||
{ text: ' "stages": [', key: 'stages', type: 'array' },
|
||||
{ text: ' { "id": "design", "agent": "arch" },', type: 'object' },
|
||||
{ text: ' { "id": "impl", "agent": "coder" }', type: 'object' },
|
||||
{ text: ' ]', type: 'bracket' },
|
||||
{ text: '}', type: 'bracket' }
|
||||
]
|
||||
}`
|
||||
|
||||
return lines.map(line => {
|
||||
if (line.key && jsonTooltips[line.key]) {
|
||||
const tooltip = jsonTooltips[line.key]
|
||||
const highlighted = line.text
|
||||
.replace(/"([^"]+)":/g, '<span class="json-key">"$1"</span>:')
|
||||
.replace(/: "([^"]+)"/g, ': <span class="json-string">"$1"</span>')
|
||||
.replace(/: \[/g, ': <span class="json-bracket">[</span>')
|
||||
.replace(/\]/g, '<span class="json-bracket">]</span>')
|
||||
.replace(/: \{/g, ': <span class="json-bracket">{</span>')
|
||||
.replace(/\}/g, '<span class="json-bracket">}</span>')
|
||||
return `<span class="json-line" title="${tooltip}">${highlighted}</span>`
|
||||
}
|
||||
const highlighted = line.text
|
||||
.replace(/"([^"]+)":/g, '<span class="json-key">"$1"</span>:')
|
||||
.replace(/: "([^"]+)"/g, ': <span class="json-string">"$1"</span>')
|
||||
.replace(/\[/g, '<span class="json-bracket">[</span>')
|
||||
.replace(/\]/g, '<span class="json-bracket">]</span>')
|
||||
.replace(/\{/g, '<span class="json-bracket">{</span>')
|
||||
.replace(/\}/g, '<span class="json-bracket">}</span>')
|
||||
return `<span class="json-line">${highlighted}</span>`
|
||||
}).join('\n')
|
||||
})
|
||||
|
||||
let terminalInterval, pipelineInterval
|
||||
|
||||
@@ -885,7 +921,51 @@ onUnmounted(() => {
|
||||
border-radius: 16px;
|
||||
padding: 1.5rem;
|
||||
border: 1px solid rgba(255,255,255,0.08);
|
||||
overflow: hidden;
|
||||
}
|
||||
.json-pre {
|
||||
margin: 0;
|
||||
color: #e2e8f0;
|
||||
font-size: 0.875rem;
|
||||
line-height: 1.7;
|
||||
white-space: pre;
|
||||
overflow-x: auto;
|
||||
}
|
||||
.json-line {
|
||||
display: block;
|
||||
cursor: default;
|
||||
transition: background 0.2s ease;
|
||||
padding: 2px 8px;
|
||||
margin: 0 -8px;
|
||||
border-radius: 4px;
|
||||
}
|
||||
.json-line[title]:hover {
|
||||
background: rgba(99, 102, 241, 0.15);
|
||||
position: relative;
|
||||
}
|
||||
.json-line[title]:hover::after {
|
||||
content: attr(title);
|
||||
position: absolute;
|
||||
left: calc(100% + 16px);
|
||||
top: 50%;
|
||||
transform: translateY(-50%);
|
||||
background: #1e293b;
|
||||
color: #e2e8f0;
|
||||
padding: 8px 12px;
|
||||
border-radius: 8px;
|
||||
font-size: 0.75rem;
|
||||
white-space: nowrap;
|
||||
max-width: 280px;
|
||||
white-space: normal;
|
||||
box-shadow: 0 4px 12px rgba(0,0,0,0.3);
|
||||
border: 1px solid rgba(255,255,255,0.1);
|
||||
z-index: 10;
|
||||
pointer-events: none;
|
||||
}
|
||||
.json-key { color: #7dd3fc; font-weight: 500; }
|
||||
.json-string { color: #a5f3fc; }
|
||||
.json-bracket { color: #94a3b8; }
|
||||
.json-number { color: #fbbf24; }
|
||||
.code-header {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
|
||||
@@ -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
|
||||
|
||||
163
docs/features/discovery.md
Normal file
163
docs/features/discovery.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# Discovery
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Discovery page tracks multi-perspective discovery sessions, displaying findings from various analysis angles with real-time updates and export capabilities.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Discovery Solution |
|
||||
|------------|---------------|-------------------|
|
||||
| **No insight visibility** | Can't see analysis results | Dedicated page for discovery sessions |
|
||||
| **Stale data** | Manual refresh required | Auto-refresh every 3 seconds |
|
||||
| **Unstructured findings** | Hard to navigate results | Split pane with session list and findings detail |
|
||||
| **No export** | Can't save findings | Export all or selected findings |
|
||||
| **Missing context** | Don't know related issues | Link findings to related issues |
|
||||
|
||||
---
|
||||
|
||||
## Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/DiscoveryPage.tsx`
|
||||
|
||||
**Purpose**: Track discovery sessions and view findings from multiple perspectives (Product, Technical, Quality, Risk, Coverage, etc.).
|
||||
|
||||
**Access**: Navigation → Issues → Discovery tab OR directly via `/discovery` route
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Discovery Title |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Stats Cards |
|
||||
| +-------------+ +-------------+ +-------------+ +-------------+ |
|
||||
| | Total | | Completed | | Running | | Total | |
|
||||
| | Sessions | | Sessions | | Sessions | | Findings | |
|
||||
| +-------------+ +-------------+ +-------------+ +-------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Split Pane (3:1 ratio) |
|
||||
| +-----------------------+ +------------------------------------------+ |
|
||||
| | Session List (1/3) | | Findings Detail (2/3) | |
|
||||
| | | | | |
|
||||
| | - DiscoveryCard | | - Filters | |
|
||||
| | (status, findings) | | - Findings list | |
|
||||
| | | | - Export buttons | |
|
||||
| | - Multiple sessions | | - Related issues links | |
|
||||
| +-----------------------+ +------------------------------------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Stats Cards** | Four metric cards showing total sessions, completed sessions, running sessions, and total findings count |
|
||||
| **Session List** | Left panel with discovery session cards showing status, findings count, and creation time |
|
||||
| **Findings Detail** | Right panel displaying detailed findings for the selected session |
|
||||
| **Auto-Refresh** | Data refreshes every 3 seconds to show real-time progress |
|
||||
| **Findings Filters** | Filter findings by perspective, category, or other attributes |
|
||||
| **Export Findings** | Export all findings or only selected findings to file |
|
||||
| **Related Issues** | Click on findings to navigate to related issues in the Issues panel |
|
||||
| **Status Badges** | Visual indicators for session status (completed, running, pending) |
|
||||
| **Loading Skeletons** | Skeleton placeholders during data fetch |
|
||||
| **Empty States** | Friendly message when no discovery sessions exist |
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
1. **View All Sessions**: Browse all discovery sessions in the left panel
|
||||
2. **Select Session**: Click a session card to view its findings in the right panel
|
||||
3. **Filter Findings**: Use filter controls to narrow down findings by category
|
||||
4. **Export Findings**: Click "Export All" or "Export Selected" to save findings
|
||||
5. **Navigate to Issues**: Click on a finding to view related issues
|
||||
6. **Monitor Progress**: Watch running sessions update in real-time (3s auto-refresh)
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Select session** | Click a discovery card in the left panel to load its findings |
|
||||
| **Filter findings** | Use filter controls in the findings detail panel to narrow results |
|
||||
| **Export all findings** | Click "Export All" to download all findings for current session |
|
||||
| **Export selected findings** | Select specific findings, click "Export Selected" |
|
||||
| **Navigate to issue** | Click on a finding to open related issue in Issues panel |
|
||||
| **Auto-refresh** | Data updates automatically every 3 seconds (no manual action needed) |
|
||||
|
||||
### Session Status
|
||||
|
||||
| Status | Icon | Description |
|
||||
|--------|------|-------------|
|
||||
| **Completed** | Green checkmark | Discovery session finished successfully |
|
||||
| **Running** | Amber spinner | Discovery session is actively running |
|
||||
| **Pending** | Gray clock | Discovery session is queued or not started |
|
||||
| **Failed** | Red X | Discovery session encountered an error |
|
||||
|
||||
### Finding Types
|
||||
|
||||
Findings can include various perspectives:
|
||||
- **Product** - Market fit, user value, business viability
|
||||
- **Technical** - Feasibility, tech debt, performance, security
|
||||
- **Quality** - Completeness, testability, consistency
|
||||
- **Risk** - Risk identification, dependencies, failure modes
|
||||
- **Coverage** - Requirement completeness vs discovery context
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `DiscoveryPage` | `@/pages/DiscoveryPage.tsx` | Main discovery tracking page |
|
||||
| `DiscoveryCard` | `@/components/issue/discovery/DiscoveryCard.tsx` | Session card in list |
|
||||
| `DiscoveryDetail` | `@/components/issue/discovery/DiscoveryDetail.tsx` | Findings detail view with filters and export |
|
||||
|
||||
### State Management
|
||||
|
||||
- **Local state**:
|
||||
- None (all data from hooks)
|
||||
|
||||
- **Custom hooks**:
|
||||
- `useIssueDiscovery` - Discovery sessions and findings data
|
||||
- Returns: `sessions`, `activeSession`, `findings`, `filters`, `isLoadingSessions`, `isLoadingFindings`, `error`
|
||||
- Methods: `setFilters`, `selectSession`, `exportFindings`, `exportSelectedFindings`
|
||||
- `useIssues` - Related issues data for finding navigation
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Auto-Refresh Interval
|
||||
|
||||
The discovery page automatically refreshes every 3 seconds:
|
||||
|
||||
```typescript
|
||||
const { sessions, findings, /* ... */ } = useIssueDiscovery({
|
||||
refetchInterval: 3000 // 3 seconds
|
||||
});
|
||||
```
|
||||
|
||||
### Export Options
|
||||
|
||||
| Export Type | Description |
|
||||
|-------------|-------------|
|
||||
| **Export All** | Export all findings from the selected session |
|
||||
| **Export Selected** | Export only the findings that are currently selected/checked |
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Issue Hub](/features/issue-hub) - Unified issues, queue, and discovery management
|
||||
- [Queue](/features/queue) - Issue execution queue management
|
||||
- [Issues Panel](/features/issue-hub) - Issue list and GitHub sync
|
||||
- [Terminal Dashboard](/features/terminal-dashboard) - Real-time session monitoring
|
||||
216
docs/features/explorer.md
Normal file
216
docs/features/explorer.md
Normal file
@@ -0,0 +1,216 @@
|
||||
# Explorer & Graph Explorer
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Explorer pages provide codebase navigation with file tree browsing, code dependency visualization, and real-time search capabilities.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Explorer Solution |
|
||||
|------------|---------------|-------------------|
|
||||
| **No code overview** | Can't see codebase structure | File tree with hierarchical navigation |
|
||||
| **Hard to find files** | Manual directory traversal | Search and filter with instant results |
|
||||
| **Unknown dependencies** | Can't see relationships | Visual dependency graph with nodes/edges |
|
||||
| **No context preview** | Open files blindly | File preview with syntax highlighting |
|
||||
| **Lost in large codebases** | Can't navigate efficiently | Split view with resizable panes |
|
||||
|
||||
---
|
||||
|
||||
## File Explorer
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/ExplorerPage.tsx`
|
||||
|
||||
**Purpose**: File explorer with tree view and file preview panel.
|
||||
|
||||
**Access**: Navigation → Explorer
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Explorer Title |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Toolbar: [Search...] [Root v] [View v] [Sort v] [Hidden] [Expand][Collapse]|
|
||||
+--------------------------------------------------------------------------+
|
||||
| +----------------+ / +--------------------------------------------------+ |
|
||||
| | Tree View | | File Preview | |
|
||||
| | (resizable) | | - Syntax highlighting | |
|
||||
| | | | - Line numbers | |
|
||||
| | - Folder tree | | - Language detection | |
|
||||
| | - File icons | | | |
|
||||
| | - Expandable | | | |
|
||||
| +----------------+ +--------------------------------------------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Tree View** | Hierarchical file tree with expand/collapse |
|
||||
| **File Preview** | Syntax-highlighted preview with line numbers |
|
||||
| **Resizable Panes** | Drag divider to resize tree width (200-600px) |
|
||||
| **Root Selection** | Change root directory from available options |
|
||||
| **Search/Filter** | Filter files by name |
|
||||
| **View Mode** | Toggle between tree and list view |
|
||||
| **Sort Options** | Name, size, modified date |
|
||||
| **Hidden Files** | Toggle show/hide hidden files |
|
||||
| **Expand/Collapse All** | Bulk expand or collapse all folders |
|
||||
| **Max File Size** | 1MB limit for preview |
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Open file** | Click file in tree to show preview |
|
||||
| **Expand folder** | Click folder arrow to expand/collapse |
|
||||
| **Resize pane** | Drag divider between tree and preview |
|
||||
| **Change root** | Select root directory from dropdown |
|
||||
| **Search files** | Type in search box to filter tree |
|
||||
| **Sort files** | Select sort option from dropdown |
|
||||
|
||||
---
|
||||
|
||||
## Graph Explorer
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/GraphExplorerPage.tsx`
|
||||
|
||||
**Purpose**: Code dependency graph visualization using ReactFlow with filtering and node details.
|
||||
|
||||
**Access**: Navigation → Graph Explorer
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Graph Toolbar: [Filters] [Fit View] [Refresh] [Reset] |
|
||||
+--------------------------------------------------------------------------+
|
||||
| +---------------------------------------------------+ +------------------+ |
|
||||
| | Graph Canvas (ReactFlow) | | Sidebar | |
|
||||
| | | | (conditional) | |
|
||||
| | [Module] --> [Class] --> [Function] | | - Node details | |
|
||||
| | | | - OR legend | |
|
||||
| | Mini map, controls, background | | | |
|
||||
| +---------------------------------------------------+ +------------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **ReactFlow Canvas** | Interactive graph with zoom/pan |
|
||||
| **Node Types** | Component, module, class, function, variable, interface, hook |
|
||||
| **Edge Types** | Imports, exports, extends, implements, uses, calls, depends-on |
|
||||
| **Filters** | Filter by node type, edge type, isolated nodes |
|
||||
| **Sidebar** | Shows selected node details OR legend |
|
||||
| **Mini Map** | Overview of entire graph |
|
||||
| **Status Panel** | Node count, edge count, updating indicator |
|
||||
| **Fit View** | Auto-fit graph in view |
|
||||
| **Custom Node Styles** | Color-coded by node type |
|
||||
|
||||
### Node Types
|
||||
|
||||
| Type | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| **Component** | Blue | React/component |
|
||||
| **Module** | Blue | Code module |
|
||||
| **Class** | Green | Class definition |
|
||||
| **Function** | Orange | Function/method |
|
||||
| **Variable** | Cyan | Variable declaration |
|
||||
| **Interface** | Gray | Interface/type |
|
||||
| **Hook** | Purple | React hook |
|
||||
|
||||
### Edge Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| **Imports** | Module import |
|
||||
| **Exports** | Module export |
|
||||
| **Extends** | Class extension |
|
||||
| **Implements** | Interface implementation |
|
||||
| **Uses** | Usage reference |
|
||||
| **Calls** | Function call |
|
||||
| **Depends-on** | Dependency |
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Select node** | Click node to show details in sidebar |
|
||||
| **Deselect** | Click canvas background |
|
||||
| **Zoom in/out** | Use mouse wheel or zoom controls |
|
||||
| **Pan canvas** | Drag canvas or use pan tool |
|
||||
| **Fit view** | Click Fit View button |
|
||||
| **Filter nodes** | Toggle node type filters in toolbar |
|
||||
| **Filter edges** | Toggle edge type filters in toolbar |
|
||||
| **Reset filters** | Click Reset button |
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### File Explorer Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `ExplorerPage` | `@/pages/ExplorerPage.tsx` | Main file explorer page |
|
||||
| `TreeView` | `@/components/shared/TreeView.tsx` | Hierarchical tree component |
|
||||
| `FilePreview` | `@/components/shared/FilePreview.tsx` | File content preview |
|
||||
| `ExplorerToolbar` | `@/components/shared/ExplorerToolbar.tsx` | Toolbar with controls |
|
||||
|
||||
### Graph Explorer Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `GraphExplorerPage` | `@/pages/GraphExplorerPage.tsx` | Main graph explorer page |
|
||||
| `GraphToolbar` | `@/components/shared/GraphToolbar.tsx` | Toolbar with filters |
|
||||
| `GraphSidebar` | `@/components/shared/GraphSidebar.tsx` | Node details or legend |
|
||||
| `Custom Nodes` | `@/pages/graph-explorer/nodes/*` | Node type components |
|
||||
|
||||
### State Management
|
||||
|
||||
**File Explorer**:
|
||||
- **Local state**: `rootPath`, `treeWidth`, `isResizing`
|
||||
- **Custom hooks**: `useFileExplorer`, `useFileContent`
|
||||
|
||||
**Graph Explorer**:
|
||||
- **Local state**: `selectedNode`, `isSidebarOpen`, `filters`
|
||||
- **Custom hooks**: `useGraphData`
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### File Explorer Settings
|
||||
|
||||
```typescript
|
||||
const DEFAULT_TREE_WIDTH = 300;
|
||||
const MIN_TREE_WIDTH = 200;
|
||||
const MAX_TREE_WIDTH = 600;
|
||||
const MAX_FILE_SIZE = 1024 * 1024; // 1MB
|
||||
```
|
||||
|
||||
### Graph Explorer Settings
|
||||
|
||||
```typescript
|
||||
const defaultFilters: GraphFilters = {
|
||||
nodeTypes: ['component', 'module', 'class', 'function', 'variable', 'interface', 'hook'],
|
||||
edgeTypes: ['imports', 'exports', 'extends', 'implements', 'uses', 'calls', 'depends-on'],
|
||||
showIsolatedNodes: false,
|
||||
};
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Memory](/features/memory) - Persistent codebase knowledge
|
||||
- [Terminal Dashboard](/features/terminal) - Terminal workspace with file sidebar
|
||||
- [Orchestrator](/features/orchestrator) - Visual workflow editor
|
||||
244
docs/features/extensions.md
Normal file
244
docs/features/extensions.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Extensions
|
||||
|
||||
## One-Liner
|
||||
|
||||
**Extensions management provides unified interfaces for configuring and managing skills, commands, rules, MCP servers, and hooks across project and user scopes.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Extensions Solution |
|
||||
|------------|---------------|---------------------|
|
||||
| **Scattered management** | Edit config files manually | Dedicated pages for each extension type |
|
||||
| **Scope confusion** | Global vs project unclear | Location tabs (project/user/hub) |
|
||||
| **No templates** | Create from scratch | Quick templates and wizards |
|
||||
| **Hard to discover** | Unknown extensions | Skill Hub, recommended MCPs |
|
||||
| **No cross-CLI sync** | Separate configs | Cross-CLI sync panel |
|
||||
|
||||
---
|
||||
|
||||
## Skills Manager
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/SkillsManagerPage.tsx`
|
||||
|
||||
**Purpose**: Browse, enable/disable, and manage skill packages with CLI mode toggle.
|
||||
|
||||
**Access**: Navigation → Skills
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Location Tabs** | Project, User, Hub tabs |
|
||||
| **CLI Mode Toggle** | Switch between Claude and Codex CLI modes |
|
||||
| **Stats Cards** | Total, Enabled, Disabled, Categories count |
|
||||
| **Filters** | Search, category, source, enabled status |
|
||||
| **Skill Grid** | Visual card grid with toggle, click details, delete |
|
||||
| **Skill Hub** | Remote/Local/Installed skills with install/uninstall |
|
||||
| **Detail Panel** | Slide-over panel with full skill details |
|
||||
| **Create Dialog** | Install new skills from source |
|
||||
|
||||
### Skill Sources
|
||||
|
||||
| Source | Description |
|
||||
|--------|-------------|
|
||||
| **Builtin** | Built-in skills provided by CCW |
|
||||
| **Custom** | User-created custom skills |
|
||||
| **Community** | Community-contributed skills |
|
||||
|
||||
---
|
||||
|
||||
## Commands Manager
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/CommandsManagerPage.tsx`
|
||||
|
||||
**Purpose**: Manage slash commands with group-based organization.
|
||||
|
||||
**Access**: Navigation → Commands
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Location Tabs** | Project, User tabs |
|
||||
| **Stats Cards** | Total, Enabled, Disabled counts |
|
||||
| **Search** | Filter by command name |
|
||||
| **Group Accordion** | Commands organized by group (cli, workflow, etc.) |
|
||||
| **Toggle Commands** | Enable/disable individual commands |
|
||||
| **Toggle Groups** | Enable/disable all commands in a group |
|
||||
| **Expand/Collapse All** | Bulk expand or collapse all groups |
|
||||
| **Show Disabled** | Toggle visibility of disabled commands |
|
||||
| **Create Dialog** | Create new custom commands |
|
||||
|
||||
### Command Groups
|
||||
|
||||
| Group | Description |
|
||||
|-------|-------------|
|
||||
| **cli** | CLI-related commands |
|
||||
| **workflow** | Workflow and session commands |
|
||||
| **terminal** | Terminal management commands |
|
||||
|
||||
---
|
||||
|
||||
## Rules Manager
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/RulesManagerPage.tsx`
|
||||
|
||||
**Purpose**: Manage rules with full CRUD operations and category filtering.
|
||||
|
||||
**Access**: Navigation → Rules
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Location Tabs** | All, Project, User tabs |
|
||||
| **Status Filter** | All, Enabled, Disabled |
|
||||
| **Category Filter** | Filter by rule category |
|
||||
| **Search** | Filter by name, description, category |
|
||||
| **Active Filters Display** | Visual filter badges with remove |
|
||||
| **Rules Grid** | Card grid with edit, delete, toggle actions |
|
||||
| **CRUD Dialogs** | Create, edit, delete rule with confirmation |
|
||||
| **Empty States** | Context-sensitive empty states |
|
||||
|
||||
### Rule Categories
|
||||
|
||||
Common rule categories include:
|
||||
- **Validation** - Input and data validation
|
||||
- **Transformation** - Data transformation rules
|
||||
- **Routing** - Request routing logic
|
||||
- **Security** - Security and access control
|
||||
- **Custom** - User-defined categories
|
||||
|
||||
---
|
||||
|
||||
## MCP Manager
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/McpManagerPage.tsx`
|
||||
|
||||
**Purpose**: Manage MCP (Model Context Protocol) servers with template library and cross-CLI sync.
|
||||
|
||||
**Access**: Navigation → MCP
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Main Tabs** | Templates, Servers, Cross-CLI tabs |
|
||||
| **CLI Mode Toggle** | Switch between Claude and Codex modes |
|
||||
| **Stats Cards** | Total, Enabled, Global, Project counts |
|
||||
| **Server Cards** | Expandable cards with toggle, edit, delete, save as template |
|
||||
| **CCW Tools MCP** | Special card for CCW Tools configuration |
|
||||
| **Templates** | Recommended MCPs and custom templates |
|
||||
| **Cross-CLI Sync** | Sync MCP servers between Claude and Codex |
|
||||
| **Scope Filter** | All, Global, Project filter |
|
||||
| **Conflict Detection** | Warn about scope conflicts |
|
||||
|
||||
### MCP Server Configuration
|
||||
|
||||
Each MCP server has:
|
||||
- **Name** - Server identifier
|
||||
- **Command** - Executable command
|
||||
- **Args** - Command arguments array
|
||||
- **Env** - Environment variables object
|
||||
- **Scope** - Global or Project
|
||||
- **Enabled** - Enable/disable toggle
|
||||
|
||||
### MCP Scopes
|
||||
|
||||
| Scope | Description |
|
||||
|-------|-------------|
|
||||
| **Global** | Available across all projects |
|
||||
| **Project** | Available only for current project |
|
||||
|
||||
---
|
||||
|
||||
## Hook Manager
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/HookManagerPage.tsx`
|
||||
|
||||
**Purpose**: Manage CLI hooks with trigger type organization and wizard creation.
|
||||
|
||||
**Access**: Navigation → Hooks
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Trigger Filters** | Filter by hook trigger type |
|
||||
| **Stats Badges** | Enabled/Total count per trigger |
|
||||
| **Search** | Filter by name, description, command |
|
||||
| **Hook Cards** | Expandable cards with toggle, edit, delete |
|
||||
| **Quick Templates** | Pre-built hook templates for quick install |
|
||||
| **Wizard Launchers** | Guided creation for common hook patterns |
|
||||
| **Create Dialog** | Manual hook creation form |
|
||||
|
||||
### Hook Trigger Types
|
||||
|
||||
| Trigger | Description |
|
||||
|---------|-------------|
|
||||
| **SessionStart** | When a session starts |
|
||||
| **UserPromptSubmit** | When user submits a prompt |
|
||||
| **PreToolUse** | Before tool execution |
|
||||
| **PostToolUse** | After tool execution |
|
||||
| **PostToolUseFailure** | After tool execution failure |
|
||||
| **Stop** | When session stops |
|
||||
| **Notification** | On notifications |
|
||||
| **SubagentStart** | When subagent starts |
|
||||
| **SubagentStop** | When subagent stops |
|
||||
| **PreCompact** | Before context compaction |
|
||||
| **SessionEnd** | When session ends |
|
||||
| **PermissionRequest** | On permission requests |
|
||||
|
||||
### Hook Wizards
|
||||
|
||||
| Wizard | Description |
|
||||
|--------|-------------|
|
||||
| **Memory Update** | Auto-update memory after sessions |
|
||||
| **Danger Protection** | Prevent dangerous operations |
|
||||
| **Skill Context** | Auto-inject skill context |
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `SkillsManagerPage` | `@/pages/SkillsManagerPage.tsx` | Skills management |
|
||||
| `CommandsManagerPage` | `@/pages/CommandsManagerPage.tsx` | Commands management |
|
||||
| `RulesManagerPage` | `@/pages/RulesManagerPage.tsx` | Rules management |
|
||||
| `McpManagerPage` | `@/pages/McpManagerPage.tsx` | MCP servers management |
|
||||
| `HookManagerPage` | `@/pages/HookManagerPage.tsx` | Hooks management |
|
||||
|
||||
### Shared Components
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| `SkillCard` / `SkillHubCard` | Skill display with actions |
|
||||
| `CommandGroupAccordion` | Command group with accordion |
|
||||
| `RuleCard` | Rule display with actions |
|
||||
| `McpServerCard` / `CodexMcpEditableCard` | MCP server display |
|
||||
| `HookCard` | Hook display with expand/collapse |
|
||||
| `TabsNavigation` | Tab switcher |
|
||||
| `CliModeToggle` | CLI mode badge switcher |
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Settings](/features/settings) - Application configuration
|
||||
- [System Settings](/features/system-settings) - Global system settings
|
||||
- [CLI Tools](/features/cli) - CLI tool configuration
|
||||
172
docs/features/issue-hub.md
Normal file
172
docs/features/issue-hub.md
Normal file
@@ -0,0 +1,172 @@
|
||||
# Issue Hub
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Issue Hub is a unified management interface for issues, execution queues, and discovery sessions with tabbed navigation and shared actions.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Issue Hub Solution |
|
||||
|------------|---------------|-------------------|
|
||||
| **Scattered views** | Separate pages for issues/queue/discovery | Single unified page with tab navigation |
|
||||
| **Context switching** | Hard to move between related features | Tab-based navigation persists in URL |
|
||||
| **Duplicate actions** | Different actions per view | Context-aware action buttons per tab |
|
||||
| **No issue creation** | Can't create new issues from UI | New issue dialog with attachments |
|
||||
| **Missing sync** | No GitHub integration | GitHub sync button on Issues tab |
|
||||
|
||||
---
|
||||
|
||||
## Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/IssueHubPage.tsx`
|
||||
|
||||
**Purpose**: Unified page for managing issues, queue, and discovery with tab navigation and context-aware actions.
|
||||
|
||||
**Access**: Navigation → Issues OR direct routes `/issues?tab=issues|queue|discovery`
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Issue Hub Header (dynamic based on active tab) |
|
||||
| [Refresh] [GitHub Sync] [Create Issue] [Fullscreen] |
|
||||
+--------------------------------------------------------------------------+
|
||||
| [Issues] [Queue] [Discovery] |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Tab Content (switches based on active tab) |
|
||||
| +--------------------------------------------------------------------+ |
|
||||
| | | |
|
||||
| | Issues Panel OR Queue Panel OR Discovery Panel | |
|
||||
| | | |
|
||||
| | Each panel has its own layout and controls | |
|
||||
| | | |
|
||||
| +--------------------------------------------------------------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Tab Navigation** | Three tabs: Issues, Queue, Discovery. Tab state persists in URL (`?tab=issues`) |
|
||||
| **Dynamic Header** | Header title changes based on active tab |
|
||||
| **Context-Aware Actions** | Action buttons change based on current tab |
|
||||
| **GitHub Sync** | Pull issues from GitHub (Issues tab only) |
|
||||
| **Create Issue** | Modal dialog for creating new issues with attachments |
|
||||
| **Immersive Mode** | Fullscreen toggle to hide app chrome |
|
||||
| **Auto-Refresh** | Per-tab refresh buttons with loading states |
|
||||
|
||||
### Tab-Specific Features
|
||||
|
||||
| Tab | Features |
|
||||
|-----|----------|
|
||||
| **Issues** | Refresh, GitHub Sync, Create Issue buttons |
|
||||
| **Queue** | Refresh button only |
|
||||
| **Discovery** | Internal controls (no header actions) |
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
1. **Navigate to Issue Hub**: Click "Issues" in the navigation
|
||||
2. **Switch Tabs**: Click tab buttons or modify URL (`?tab=queue`)
|
||||
3. **Issues Tab**: View issues, sync from GitHub, create new issues
|
||||
4. **Queue Tab**: View and manage execution queue
|
||||
5. **Discovery Tab**: Track discovery sessions
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Switch tabs** | Click tab buttons OR use URL parameter `?tab=issues|queue|discovery` |
|
||||
| **Refresh current tab** | Click the refresh button (actions update per tab) |
|
||||
| **Sync from GitHub** | Click the GitHub sync button on Issues tab |
|
||||
| **Create new issue** | Click "Create Issue" button, fill in the form |
|
||||
| **Toggle fullscreen** | Click the fullscreen button to enter/exit immersive mode |
|
||||
|
||||
### New Issue Dialog
|
||||
|
||||
| Field | Description | Required |
|
||||
|-------|-------------|----------|
|
||||
| **Title** | Issue title (max 200 chars) | Yes |
|
||||
| **Description** | Detailed context (max 10000 chars) | No |
|
||||
| **Type** | Bug, Feature, Improvement, Other | No (default: Other) |
|
||||
| **Priority** | Low, Medium, High, Critical | No (default: Medium) |
|
||||
| **Attachments** | Images, Markdown, text, PDF files | No |
|
||||
|
||||
**Attachment Support**:
|
||||
- Drag and drop files onto the upload area
|
||||
- Click to open file picker
|
||||
- Supported types: Images, Markdown (.md), text (.txt), JSON (.json), PDF (.pdf)
|
||||
- Remove attachments before creating issue
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `IssueHubPage` | `@/pages/IssueHubPage.tsx` | Main issue hub with tabs |
|
||||
| `IssueHubHeader` | `@/components/issue/hub/IssueHubHeader.tsx` | Dynamic header based on tab |
|
||||
| `IssueHubTabs` | `@/components/issue/hub/IssueHubTabs.tsx` | Tab switcher |
|
||||
| `IssuesPanel` | `@/components/issue/hub/IssuesPanel.tsx` | Issues list and management |
|
||||
| `QueuePanel` | `@/components/issue/hub/QueuePanel.tsx` | Queue management |
|
||||
| `DiscoveryPanel` | `@/components/issue/hub/DiscoveryPanel.tsx` | Discovery tracking |
|
||||
| `NewIssueDialog` | (internal to IssueHubPage) | Create issue modal |
|
||||
|
||||
### State Management
|
||||
|
||||
- **Local state**:
|
||||
- `currentTab`: IssueTab ('issues' | 'queue' | 'discovery')
|
||||
- `isNewIssueOpen`: boolean
|
||||
- `isGithubSyncing`: boolean
|
||||
|
||||
- **URL state**:
|
||||
- Tab persists in URL search param: `?tab=issues`
|
||||
|
||||
- **Custom hooks**:
|
||||
- `useIssues` - Issues data and refresh
|
||||
- `useIssueQueue` - Queue data and refresh
|
||||
- `useIssueMutations` - Create issue mutation
|
||||
- `pullIssuesFromGitHub` - GitHub sync API call
|
||||
- `uploadAttachments` - Attachment upload for new issues
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Tab Navigation
|
||||
|
||||
Tabs are validated against allowed values:
|
||||
|
||||
```typescript
|
||||
const VALID_TABS: IssueTab[] = ['issues', 'queue', 'discovery'];
|
||||
```
|
||||
|
||||
Invalid tab values automatically redirect to 'issues'.
|
||||
|
||||
### Issue Types
|
||||
|
||||
| Type | Color | Description |
|
||||
|------|-------|-------------|
|
||||
| **Bug** | Red | Functional errors or problems |
|
||||
| **Feature** | Green | New feature requests |
|
||||
| **Improvement** | Blue | Enhancements to existing features |
|
||||
| **Other** | Gray | Other types |
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Issues Panel](/features/issue-hub) - Detailed issue management
|
||||
- [Queue](/features/queue) - Queue management details
|
||||
- [Discovery](/features/discovery) - Discovery session details
|
||||
- [Sessions](/features/sessions) - Workflow session management
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Memory System is a cross-session knowledge persistence mechanism** — Stores project context, decisions, and learnings so AI remembers across sessions without re-explanation.
|
||||
**The Memory System provides a unified interface for managing persistent knowledge across sessions, including core memory, workflow context, CLI history, vector search, and V2 pipeline operations.**
|
||||
|
||||
---
|
||||
|
||||
@@ -14,62 +14,178 @@
|
||||
| **Lost decisions** | Architecture decisions forgotten | Decision log persists |
|
||||
| **Repeated explanations** | Same context explained multiple times | Memory auto-injection |
|
||||
| **Knowledge silos** | Each developer maintains own context | Shared team memory |
|
||||
| **Scattered data sources** | Core/workflow/CLI history separate | Unified search across all categories |
|
||||
|
||||
---
|
||||
|
||||
## vs Traditional Methods
|
||||
## Page Overview
|
||||
|
||||
| Dimension | CLAUDE.md | Notes | **Memory System** |
|
||||
|-----------|-----------|-------|-------------------|
|
||||
| Persistence | Static file | Manual | **Auto-extracted from sessions** |
|
||||
| Search | Text search | Folder search | **Semantic vector search** |
|
||||
| Updates | Manual edit | Manual note | **Auto-capture from conversations** |
|
||||
| Sharing | Git | Manual | **Auto-sync via workflow** |
|
||||
**Location**: `ccw/frontend/src/pages/MemoryPage.tsx`
|
||||
|
||||
---
|
||||
**Purpose**: View and manage core memory with CRUD operations and unified vector search.
|
||||
|
||||
## Core Concepts
|
||||
**Access**: Navigation → Memory
|
||||
|
||||
| Concept | Description | Location |
|
||||
|---------|-------------|----------|
|
||||
| **Core Memory** | Persistent project knowledge | `~/.claude/memory/` |
|
||||
| **Session Memory** | Current session context | `.workflow/.memory/` |
|
||||
| **Memory Entry** | Individual knowledge item | JSONL format |
|
||||
| **Memory Index** | Searchable index | Embedding-based |
|
||||
### Layout
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
### Viewing Memory
|
||||
|
||||
```bash
|
||||
ccw memory list
|
||||
ccw memory search "authentication"
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Memory Title [Refresh] [Fullscreen]|
|
||||
+--------------------------------------------------------------------------+
|
||||
| [Core] [Workflow] [CLI History] [Search] [V2 Pipeline] |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Tab Content (varies by active tab) |
|
||||
| +--------------------------------------------------------------------+ |
|
||||
| | | |
|
||||
| | - Memory list with CRUD operations | |
|
||||
| | - Search interface with filters | |
|
||||
| | - Source type badges and tags | |
|
||||
| | - V2 pipeline job monitoring (V2 tab) | |
|
||||
| | | |
|
||||
| +--------------------------------------------------------------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
### Memory Categories
|
||||
---
|
||||
|
||||
- **Project Context**: Architecture, tech stack, patterns
|
||||
- **Decisions**: ADRs, design choices
|
||||
- **Learnings**: What worked, what didn't
|
||||
- **Conventions**: Coding standards, naming
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Tabbed Interface** | Five tabs: Core, Workflow, CLI History, Search, V2 Pipeline |
|
||||
| **CRUD Operations** | Create, edit, delete memories with confirmation dialogs |
|
||||
| **Unified Search** | Vector search across all memory categories |
|
||||
| **Source Type Filtering** | Filter by core_memory, workflow, cli_history |
|
||||
| **Tag Filtering** | Filter memories by custom tags |
|
||||
| **Batch Operations** | Select all, delete selected |
|
||||
| **Recommendations** | View memory recommendations from AI |
|
||||
| **Re-index** | Rebuild memory index |
|
||||
| **Export** | Export search results to file |
|
||||
| **V2 Pipeline** | Monitor extraction and consolidation jobs |
|
||||
| **Immersive Mode** | Fullscreen toggle for focused work |
|
||||
|
||||
---
|
||||
|
||||
## Memory Categories
|
||||
|
||||
| Tab | Source Type | Description |
|
||||
|-----|-------------|-------------|
|
||||
| **Core** | `core_memory` | Persistent project knowledge stored in `~/.claude/memory/` |
|
||||
| **Workflow** | `workflow` | Session context from `.workflow/.memory/` |
|
||||
| **CLI History** | `cli_history` | Command execution history |
|
||||
| **Search** | All | Unified vector search across all categories |
|
||||
| **V2 Pipeline** | - | Extraction and consolidation job monitoring |
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
1. **Browse Memories**: Switch between Core/Workflow/CLI History tabs
|
||||
2. **Create Memory**: Click "New Memory" button, fill in the form
|
||||
3. **Edit Memory**: Click edit button on memory card, modify content
|
||||
4. **Delete Memory**: Click delete button, confirm in dialog
|
||||
5. **Search**: Switch to Search tab, enter query to find memories
|
||||
6. **Filter Results**: Use source type and tag filters to narrow results
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Create memory** | Click "New Memory" button, fill form, submit |
|
||||
| **Edit memory** | Click edit (pencil) button on memory card |
|
||||
| **Delete memory** | Click delete (trash) button, confirm |
|
||||
| **Search memories** | Switch to Search tab, type query, filter results |
|
||||
| **Export results** | Select memories, click "Export Selected" |
|
||||
| **Re-index memory** | Click "Re-index" to rebuild search index |
|
||||
| **Select all** | Click "Select All" checkbox to select all visible memories |
|
||||
| **Delete selected** | Click "Delete Selected" to batch delete |
|
||||
|
||||
### Source Type Badges
|
||||
|
||||
| Source Type | Color | Description |
|
||||
|-------------|-------|-------------|
|
||||
| **core_memory** | Blue | Persistent project knowledge |
|
||||
| **workflow** | Green | Workflow session context |
|
||||
| **cli_history** | Amber | CLI command history |
|
||||
|
||||
### Memory Metadata
|
||||
|
||||
Each memory entry contains:
|
||||
- **ID**: Unique identifier (format: `CMEM-YYYYMMDD-HHMMSS`)
|
||||
- **Content**: Markdown-formatted text
|
||||
- **Tags**: Array of tag strings for categorization
|
||||
- **Created/Updated**: Timestamps
|
||||
- **Source Type**: Category identifier
|
||||
|
||||
---
|
||||
|
||||
## V2 Pipeline
|
||||
|
||||
The V2 Pipeline tab monitors background jobs for:
|
||||
|
||||
| Job Type | Description |
|
||||
|----------|-------------|
|
||||
| **Extraction** | Extract knowledge from sessions |
|
||||
| **Consolidation** | Consolidate and summarize memories |
|
||||
| **Embedding** | Generate vector embeddings for search |
|
||||
|
||||
### Job Status
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| **Pending** | Job queued, not started |
|
||||
| **Running** | Job in progress |
|
||||
| **Done** | Job completed successfully |
|
||||
| **Error** | Job failed with error message |
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `MemoryPage` | `@/pages/MemoryPage.tsx` | Main memory management page |
|
||||
| `V2PipelineTab` | `@/components/memory/V2PipelineTab.tsx` | V2 pipeline job monitoring |
|
||||
| `MemoryCard` | (internal to MemoryPage) | Individual memory display |
|
||||
|
||||
### State Management
|
||||
|
||||
- **Local state**:
|
||||
- `activeTab`: TabValue
|
||||
- `searchQuery`: string
|
||||
- `selectedMemories`: Set<string>
|
||||
- `filters`: { sourceType?: string; tags?: string[] }
|
||||
- `dialogStates`: create, edit, delete
|
||||
|
||||
- **Custom hooks**:
|
||||
- `useMemory` - Core memory CRUD operations
|
||||
- `useMemoryMutations` - Memory mutations (create, update, delete)
|
||||
- `useUnifiedSearch` - Vector search across categories
|
||||
- `useUnifiedStats` - Memory statistics
|
||||
- `useRecommendations` - AI-generated recommendations
|
||||
- `useReindex` - Rebuild search index
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
```json
|
||||
// ~/.claude/settings.json
|
||||
{
|
||||
"memory": {
|
||||
"enabled": true,
|
||||
"maxEntries": 1000,
|
||||
"autoCapture": true,
|
||||
"embeddingModel": "text-embedding-3-small"
|
||||
}
|
||||
}
|
||||
```
|
||||
No configuration required. The memory system automatically fetches data from the backend.
|
||||
|
||||
### Memory API Endpoints
|
||||
|
||||
| Operation | Endpoint |
|
||||
|-----------|----------|
|
||||
| List memories | `GET /api/memory` |
|
||||
| Create memory | `POST /api/memory` |
|
||||
| Update memory | `PUT /api/memory/:id` |
|
||||
| Delete memory | `DELETE /api/memory/:id` |
|
||||
| Search | `POST /api/memory/search` |
|
||||
| Re-index | `POST /api/memory/reindex` |
|
||||
| V2 Jobs | `GET /api/memory/v2/jobs` |
|
||||
|
||||
---
|
||||
|
||||
@@ -77,4 +193,5 @@ ccw memory search "authentication"
|
||||
|
||||
- [Spec System](/features/spec) - Constraint injection
|
||||
- [CLI Call](/features/cli) - Command line invocation
|
||||
- [CodexLens](/features/codexlens) - Code indexing
|
||||
- [Explorer](/features/explorer) - Codebase navigation
|
||||
- [Dashboard](/features/dashboard) - Project overview
|
||||
|
||||
209
docs/features/orchestrator.md
Normal file
209
docs/features/orchestrator.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# Orchestrator
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Orchestrator is a visual workflow template editor with React Flow, featuring drag-drop node palette, property panel, and template library for designing automation flows.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Orchestrator Solution |
|
||||
|------------|---------------|-----------------------|
|
||||
| **No visual workflow design** | Manual configuration file editing | Drag-and-drop canvas interface |
|
||||
| **Hard to understand flows** | Text-based configuration | Visual node graphs with connections |
|
||||
| **No template reuse** | Recreate flows from scratch | Template library for quick start |
|
||||
| **Complex node configuration** | Remember all options | Contextual property panel |
|
||||
| **Accidental edits during execution** | Can modify while running | Canvas lock during execution |
|
||||
|
||||
---
|
||||
|
||||
## Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/orchestrator/OrchestratorPage.tsx`
|
||||
|
||||
**Purpose**: Visual workflow template editor for creating, editing, and managing automation flows.
|
||||
|
||||
**Access**: Navigation → Orchestrator
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Flow Toolbar (save, load, template library, execution controls) |
|
||||
+--------------------------------------------------------------------------+
|
||||
| +-------+------------------------------------------------------+-------+ |
|
||||
| | Node | Flow Canvas (React Flow) | Prop | |
|
||||
| | Palet | +----+ +----+ +----+ | Panel | |
|
||||
| | (coll)| | N1 | -->| N2 | -->| N3 | | (cond)| |
|
||||
| | | +----+ +----+ +----+ | | |
|
||||
| | | | | |
|
||||
| +-------+------------------------------------------------------+-------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Node Palette (Left Sidebar)** | Collapsible panel with categorized nodes (templates, nodes tabs) |
|
||||
| **Flow Canvas (Center)** | ReactFlow graph with zoom/pan, minimap, controls, grid background |
|
||||
| **Property Panel (Right Overlay)** | Contextual property editor that appears when node is selected |
|
||||
| **Template Library** | Dialog for browsing and loading saved templates |
|
||||
| **Drag-and-Drop** | Drag nodes from palette to canvas to add them |
|
||||
| **Connection Handles** | Connect nodes by dragging from output to input handles |
|
||||
| **Interaction Modes** | Toggle between pan and selection modes (Ctrl to temporarily reverse) |
|
||||
| **Execution Lock** | Canvas is read-only during flow execution |
|
||||
| **Layout Persistence** | Sidebar width persists in local storage |
|
||||
| **Snap to Grid** | Nodes align to 15px grid for neat layouts |
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
1. **Open Orchestrator**: Navigate to Orchestrator page (flows auto-load)
|
||||
2. **Add Nodes**: Drag nodes from palette OR double-click palette items
|
||||
3. **Connect Nodes**: Drag from output handle to input handle
|
||||
4. **Configure Nodes**: Click node to open property panel, edit properties
|
||||
5. **Save Flow**: Click save button in toolbar
|
||||
6. **Use Templates**: Open template library to browse/load templates
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Add node (drag)** | Drag node from palette to canvas |
|
||||
| **Add node (double-click)** | Double-click palette item |
|
||||
| **Connect nodes** | Drag from source output handle to target input handle |
|
||||
| **Select node** | Click node (opens property panel) |
|
||||
| **Deselect** | Click canvas background |
|
||||
| **Move node** | Drag node (when not executing) |
|
||||
| **Delete node/edge** | Select and press Backspace/Delete (when not executing) |
|
||||
| **Zoom in/out** | Use zoom controls or mouse wheel |
|
||||
| **Fit view** | Click fit view button |
|
||||
| **Pan canvas** | Drag canvas (pan mode) or use middle mouse button |
|
||||
| **Toggle interaction mode** | Click mode toggle button or hold Ctrl (temporarily reverse) |
|
||||
| **Collapse palette** | Click collapse button (or click expand button when collapsed) |
|
||||
| **Open template library** | Click template library button in toolbar |
|
||||
|
||||
### Node Categories
|
||||
|
||||
The node palette organizes nodes into categories:
|
||||
- **Prompt Templates** - Pre-built prompt templates with variables
|
||||
- **Commands** - Slash command invocations
|
||||
- **Tools** - External tool integrations
|
||||
- **Custom** - User-defined nodes
|
||||
|
||||
### Canvas Controls
|
||||
|
||||
| Control | Location | Function |
|
||||
|---------|----------|----------|
|
||||
| **Zoom In/Out** | Controls (bottom-right) | Zoom canvas in/out |
|
||||
| **Fit View** | Controls (bottom-right) | Fit all nodes in view |
|
||||
| **Interactive Mode** | Controls (bottom-right) | Toggle pan/selection mode |
|
||||
| **Mini Map** | Bottom-right | Overview of entire flow |
|
||||
| **Grid Background** | Canvas | Visual reference for alignment |
|
||||
|
||||
---
|
||||
|
||||
## Property Panel
|
||||
|
||||
The property panel appears as an overlay when a node is selected. It provides:
|
||||
|
||||
### Common Properties
|
||||
|
||||
| Property | Description |
|
||||
|----------|-------------|
|
||||
| **Node Name** | Display name for the node |
|
||||
| **Node ID** | Unique identifier (auto-generated) |
|
||||
| **Execution Mode** | How node executes (sync/async/etc.) |
|
||||
| **Instructions** | Prompt instructions with template support |
|
||||
| **Variables** | Input/output variable definitions |
|
||||
| **Tags** | Custom tags for organization |
|
||||
| **Commands** | Associated slash commands |
|
||||
|
||||
### Template Editor Features
|
||||
|
||||
- **Built-in Templates**: Pre-defined instruction templates
|
||||
- **Custom Tags**: Tag-based instruction system (e.g., `{{$INPUT}}`)
|
||||
- **Variable Inputs**: Template variables with custom values
|
||||
- **Preview**: Live preview of rendered instructions
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `OrchestratorPage` | `@/pages/orchestrator/OrchestratorPage.tsx` | Main orchestrator page |
|
||||
| `FlowToolbar` | `@/pages/orchestrator/FlowToolbar.tsx` | Top toolbar with actions |
|
||||
| `LeftSidebar` | `@/pages/orchestrator/LeftSidebar.tsx` | Collapsible node palette |
|
||||
| `FlowCanvas` | `@/pages/orchestrator/FlowCanvas.tsx` | ReactFlow graph canvas |
|
||||
| `PropertyPanel` | `@/pages/orchestrator/PropertyPanel.tsx` | Node property editor overlay |
|
||||
| `TemplateLibrary` | `@/pages/orchestrator/TemplateLibrary.tsx` | Template browser dialog |
|
||||
| `NodeLibrary` | `@/pages/orchestrator/NodeLibrary.tsx` | Node palette content |
|
||||
| `InlineTemplatePanel` | `@/pages/orchestrator/InlineTemplatePanel.tsx` | Template palette content |
|
||||
| `InteractionModeToggle` | `@/pages/orchestrator/InteractionModeToggle.tsx` | Pan/selection mode toggle |
|
||||
|
||||
### Node Types
|
||||
|
||||
| Node Type | Purpose |
|
||||
|-----------|---------|
|
||||
| `PromptTemplateNode` | Unified prompt template node with instructions |
|
||||
| Custom nodes | Extended from base node types |
|
||||
|
||||
### State Management
|
||||
|
||||
- **Local state** (OrchestratorPage):
|
||||
- `isTemplateLibraryOpen`: boolean
|
||||
|
||||
- **Zustand stores** (`useFlowStore`):
|
||||
- `nodes` - Flow nodes array
|
||||
- `edges` - Flow edges array
|
||||
- `selectedNodeId` - Currently selected node
|
||||
- `isPaletteOpen` - Palette expanded state
|
||||
- `isPropertyPanelOpen` - Property panel visibility
|
||||
- `leftPanelTab` - Active palette tab ('templates' | 'nodes')
|
||||
- `interactionMode` - Pan or selection mode
|
||||
|
||||
- **Execution store** (`useExecutionStore`):
|
||||
- `isExecuting` - Whether flow is currently executing (locks canvas)
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
| Key | Action |
|
||||
|-----|--------|
|
||||
| **Backspace/Delete** | Delete selected node/edge (when not executing) |
|
||||
| **Ctrl/Cmd (hold)** | Temporarily reverse interaction mode |
|
||||
| **Mouse wheel** | Zoom in/out |
|
||||
| **Middle mouse drag** | Pan canvas |
|
||||
|
||||
### Canvas Settings
|
||||
|
||||
```typescript
|
||||
{
|
||||
snapToGrid: true,
|
||||
snapGrid: [15, 15], // 15px grid alignment
|
||||
nodesDraggable: !isExecuting,
|
||||
nodesConnectable: !isExecuting,
|
||||
elementsSelectable: !isExecuting
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Terminal Dashboard](/features/terminal) - Terminal-first execution monitoring
|
||||
- [Sessions](/features/sessions) - Workflow session management
|
||||
- [Commands Management](/features/extensions) - Slash command configuration
|
||||
163
docs/features/queue.md
Normal file
163
docs/features/queue.md
Normal file
@@ -0,0 +1,163 @@
|
||||
# Queue
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Queue page manages issue execution queues, displaying grouped tasks and solutions with conflict detection and merge capabilities.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Queue Solution |
|
||||
|------------|---------------|----------------|
|
||||
| **Disorganized execution** | No unified task queue | Centralized queue with grouped items |
|
||||
| **Unknown queue status** | Can't tell if queue is ready | Status indicator with conflicts warning |
|
||||
| **Manual queue management** | No way to control execution | Activate/deactivate/delete with actions |
|
||||
| **Duplicate handling** | Confusing duplicate items | Merge queues functionality |
|
||||
| **No visibility** | Don't know what's queued | Stats cards with items/groups/tasks/solutions counts |
|
||||
|
||||
---
|
||||
|
||||
## Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/QueuePage.tsx`
|
||||
|
||||
**Purpose**: View and manage issue execution queues with stats, conflict detection, and queue operations.
|
||||
|
||||
**Access**: Navigation → Issues → Queue tab OR directly via `/queue` route
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Queue Title [Refresh] |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Stats Cards |
|
||||
| +-------------+ +-------------+ +-------------+ +-------------+ |
|
||||
| | Total Items | | Groups | | Tasks | | Solutions | |
|
||||
| +-------------+ +-------------+ +-------------+ +-------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Conflicts Warning (when conflicts exist) |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Queue Cards (1-2 columns) |
|
||||
| +---------------------------------------------------------------------+ |
|
||||
| | QueueCard | |
|
||||
| | - Queue info | |
|
||||
| | - Grouped items preview | |
|
||||
| | - Action buttons (Activate/Deactivate/Delete/Merge) | |
|
||||
| +---------------------------------------------------------------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Status Footer (Ready/Pending indicator) |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Stats Cards** | Four metric cards showing total items, groups, tasks, and solutions counts |
|
||||
| **Conflicts Warning** | Banner alert when conflicts exist, showing count and description |
|
||||
| **Queue Card** | Displays queue information with grouped items preview and action buttons |
|
||||
| **Activate/Deactivate** | Toggle queue active state for execution control |
|
||||
| **Delete Queue** | Remove queue with confirmation dialog |
|
||||
| **Merge Queues** | Combine multiple queues (if multiple exist) |
|
||||
| **Status Footer** | Visual indicator showing if queue is ready (active) or pending (inactive/conflicts) |
|
||||
| **Loading State** | Skeleton placeholders during data fetch |
|
||||
| **Empty State** | Friendly message when no queue exists |
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
1. **Check Queue Status**: Review stats cards and status footer to understand queue state
|
||||
2. **Review Conflicts**: If conflicts warning is shown, resolve conflicts before activation
|
||||
3. **Activate Queue**: Click "Activate" to enable queue for execution (only if no conflicts)
|
||||
4. **Deactivate Queue**: Click "Deactivate" to pause execution
|
||||
5. **Delete Queue**: Click "Delete" to remove the queue (requires confirmation)
|
||||
6. **Merge Queues**: Use merge action to combine multiple queues when applicable
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Refresh queue** | Click the refresh button to reload queue data |
|
||||
| **Activate queue** | Click the Activate button on the queue card |
|
||||
| **Deactivate queue** | Click the Deactivate button to pause the queue |
|
||||
| **Delete queue** | Click the Delete button, confirm in the dialog |
|
||||
| **Merge queues** | Select source and target queues, click merge |
|
||||
| **View status** | Check the status footer for ready/pending indication |
|
||||
|
||||
### Queue Status
|
||||
|
||||
| Status | Condition | Appearance |
|
||||
|--------|-----------|------------|
|
||||
| **Ready/Active** | Total items > 0 AND no conflicts | Green badge with checkmark |
|
||||
| **Pending/Inactive** | No items OR conflicts exist | Gray/amber badge with clock icon |
|
||||
|
||||
### Conflict Resolution
|
||||
|
||||
When conflicts are detected:
|
||||
1. A warning banner appears showing conflict count
|
||||
2. Queue cannot be activated until conflicts are resolved
|
||||
3. Status footer shows "Pending" state
|
||||
4. Resolve conflicts through the Issues panel or related workflows
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `QueuePage` | `@/pages/QueuePage.tsx` | Main queue management page |
|
||||
| `QueueCard` | `@/components/issue/queue/QueueCard.tsx` | Queue display with actions |
|
||||
| `QueuePageSkeleton` | (internal to QueuePage) | Loading placeholder |
|
||||
| `QueueEmptyState` | (internal to QueuePage) | Empty state display |
|
||||
|
||||
### State Management
|
||||
|
||||
- **Local state**:
|
||||
- None (all data from hooks)
|
||||
|
||||
- **Custom hooks**:
|
||||
- `useIssueQueue` - Queue data fetching
|
||||
- `useQueueMutations` - Queue operations (activate, deactivate, delete, merge)
|
||||
|
||||
### Mutation States
|
||||
|
||||
| State | Loading Indicator |
|
||||
|-------|------------------|
|
||||
| `isActivating` | Disable activate button during activation |
|
||||
| `isDeactivating` | Disable deactivate button during deactivation |
|
||||
| `isDeleting` | Disable delete button during deletion |
|
||||
| `isMerging` | Disable merge button during merge operation |
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
No configuration required. Queue data is automatically fetched from the backend.
|
||||
|
||||
### Queue Data Structure
|
||||
|
||||
```typescript
|
||||
interface QueueData {
|
||||
tasks: Task[];
|
||||
solutions: Solution[];
|
||||
conflicts: Conflict[];
|
||||
grouped_items: Record<string, GroupedItem>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Issue Hub](/features/issue-hub) - Unified issues, queue, and discovery management
|
||||
- [Discovery](/features/discovery) - Discovery session tracking
|
||||
- [Issues Panel](/features/issue-hub) - Issue list and GitHub sync
|
||||
187
docs/features/sessions.md
Normal file
187
docs/features/sessions.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Sessions
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Sessions page provides a centralized hub for viewing, filtering, and managing all workflow sessions with CRUD operations and status tracking.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Sessions Solution |
|
||||
|------------|---------------|-------------------|
|
||||
| **Lost sessions** | Can't find past work | Unified list of all sessions with search |
|
||||
| **Unknown session status** | No progress visibility | Color-coded status badges with filters |
|
||||
| **Cluttered view** | Active and archived mixed | Location tabs (active/archived/all) |
|
||||
| **Hard to navigate** | No way to access details | Click to navigate to detail or review page |
|
||||
| **No bulk actions** | Manual cleanup | Archive and delete with confirmation dialogs |
|
||||
|
||||
---
|
||||
|
||||
## Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/SessionsPage.tsx`
|
||||
|
||||
**Purpose**: Sessions list page with filtering, search, and CRUD operations for managing workflow sessions.
|
||||
|
||||
**Access**: Navigation → Sessions
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Sessions Title [Refresh] [Fullscreen]|
|
||||
+--------------------------------------------------------------------------+
|
||||
| [Active] [Archived] [All] [Search...] [Filter v] |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Active filters display (when applied) |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Session Grid (1/2/3 columns responsive) |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
| | SessionCard | | SessionCard | | SessionCard | |
|
||||
| | - Status | | - Status | | - Status | |
|
||||
| | - Title | | - Title | | - Title | |
|
||||
| | - Progress | | - Progress | | - Progress | |
|
||||
| | - Actions | | - Actions | | - Actions | |
|
||||
| +-------------+ +-------------+ +-------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
| Empty State (when no sessions) |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Location Tabs** | Filter sessions by location: Active, Archived, or All |
|
||||
| **Search** | Full-text search across session titles and descriptions |
|
||||
| **Status Filter** | Multi-select dropdown to filter by status (planning, in_progress, completed, paused) |
|
||||
| **Active Filters Display** | Visual badges showing applied filters with remove buttons |
|
||||
| **Session Cards** | Responsive grid (1/2/3 columns) with status badge, title, description, progress bar, and action buttons |
|
||||
| **Immersive Mode** | Fullscreen toggle to hide app chrome for focused work |
|
||||
| **Loading Skeletons** | Skeleton placeholders during data fetch |
|
||||
| **Empty States** | Friendly message with call-to-action when no sessions match filters |
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
1. **Browse Sessions**: Use location tabs to switch between Active, Archived, and All sessions
|
||||
2. **Search**: Type in the search box to filter by title or description
|
||||
3. **Filter by Status**: Click the filter button to select one or more statuses
|
||||
4. **Clear Filters**: Click individual filter badges or "Clear All" button
|
||||
5. **View Details**: Click a session card to navigate to session detail page
|
||||
6. **Manage Sessions**: Use action buttons to archive or delete sessions
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Navigate to detail** | Click anywhere on the session card to open detail page |
|
||||
| **Navigate to review** | Review-type sessions automatically route to the review page |
|
||||
| **Archive session** | Click the archive button on the card (no confirmation required) |
|
||||
| **Delete session** | Click the delete button, confirm in the dialog |
|
||||
| **Toggle fullscreen** | Click the fullscreen button to enter/exit immersive mode |
|
||||
| **Clear search** | Click the X button in the search input |
|
||||
| **Clear status filter** | Click the X on individual filter badges or use "Clear All" |
|
||||
|
||||
### Status Types
|
||||
|
||||
| Status | Color | Description |
|
||||
|--------|-------|-------------|
|
||||
| **Planning** | Violet | Session is in planning phase |
|
||||
| **In Progress** | Amber | Session is actively being worked on |
|
||||
| **Completed** | Green | Session has been completed |
|
||||
| **Paused** | Slate | Session is paused |
|
||||
| **Archived** | Gray | Session is archived |
|
||||
|
||||
---
|
||||
|
||||
## Session Detail Page
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/SessionDetailPage.tsx`
|
||||
|
||||
The session detail page provides a comprehensive view of a single session with tabbed content.
|
||||
|
||||
### Tabs
|
||||
|
||||
| Tab | Content | Always Shown |
|
||||
|-----|---------|--------------|
|
||||
| **Tasks** | List of all tasks with status | Yes (with badge count) |
|
||||
| **Context** | Session context data | Conditional |
|
||||
| **Summary** | Session summary | Conditional |
|
||||
| **Impl Plan** | Implementation plan | Conditional |
|
||||
| **Conflict** | Conflict resolution | Conditional |
|
||||
| **Review** | Review content | Only if `has_review` or `review` exists |
|
||||
|
||||
### Info Bar
|
||||
|
||||
Displays created/updated dates and task progress (completed/total tasks).
|
||||
|
||||
### Task Drawer
|
||||
|
||||
Click any task to open a slide-over drawer with full task details.
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `SessionsPage` | `@/pages/SessionsPage.tsx` | Main sessions list page |
|
||||
| `SessionDetailPage` | `@/pages/SessionDetailPage.tsx` | Session detail with tabs |
|
||||
| `SessionCard` | `@/components/shared/SessionCard.tsx` | Individual session display with actions |
|
||||
| `SessionCardSkeleton` | `@/components/shared/SessionCard.tsx` | Loading placeholder |
|
||||
| `TabsNavigation` | `@/components/ui/TabsNavigation.tsx` | Tab switcher component |
|
||||
| `TaskListTab` | `@/pages/session-detail/TaskListTab.tsx` | Tasks list tab content |
|
||||
| `TaskDrawer` | `@/components/shared/TaskDrawer.tsx` | Task detail slide-over |
|
||||
|
||||
### State Management
|
||||
|
||||
- **Local state** (SessionsPage):
|
||||
- `locationFilter`: 'all' | 'active' | 'archived'
|
||||
- `searchQuery`: string
|
||||
- `statusFilter`: SessionMetadata['status'][]
|
||||
- `deleteDialogOpen`: boolean
|
||||
- `isImmersiveMode`: boolean (from global store)
|
||||
|
||||
- **Local state** (SessionDetailPage):
|
||||
- `activeTab`: TabValue
|
||||
- `selectedTask`: TaskData | null
|
||||
|
||||
- **Custom hooks**:
|
||||
- `useSessions` - Sessions CRUD with filtering
|
||||
- `useArchiveSession` - Archive session mutation
|
||||
- `useDeleteSession` - Delete session mutation
|
||||
- `useSessionDetail` - Session detail data fetch
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
No configuration required. Sessions are automatically fetched from the backend.
|
||||
|
||||
### Filter Object Structure
|
||||
|
||||
```typescript
|
||||
interface SessionsFilter {
|
||||
location?: 'all' | 'active' | 'archived';
|
||||
search?: string;
|
||||
status?: SessionMetadata['status'][];
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Dashboard](/features/dashboard) - Overview of all sessions with statistics
|
||||
- [Lite Tasks](/features/tasks-history) - Lite-plan and lite-fix task management
|
||||
- [Terminal Dashboard](/features/terminal-dashboard) - Terminal-first session monitoring
|
||||
- [Orchestrator](/features/orchestrator) - Workflow template editor
|
||||
187
docs/features/settings.md
Normal file
187
docs/features/settings.md
Normal file
@@ -0,0 +1,187 @@
|
||||
# Settings
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Settings page provides a unified interface for managing application preferences, CLI tools, feature flags, and data management.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Settings Solution |
|
||||
|------------|---------------|-------------------|
|
||||
| **Scattered configuration** | Settings in multiple files | Centralized UI for all settings |
|
||||
| **No tool management** | Edit config files manually | Enable/disable tools from UI |
|
||||
| **Feature flags hidden** | Need to know config keys | Visual toggle switches |
|
||||
| **No export/import** | Manual backup/restore | One-click export/import |
|
||||
| **Unclear CCW status** | Can't tell if installed | Installation status indicator |
|
||||
|
||||
---
|
||||
|
||||
## Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/SettingsPage.tsx`
|
||||
|
||||
**Purpose**: Application settings and configuration with CLI tools management.
|
||||
|
||||
**Access**: Navigation → Settings
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Settings Title |
|
||||
+--------------------------------------------------------------------------+
|
||||
| [Theme & Appearance v] |
|
||||
| [Language v] |
|
||||
| [Notifications v] |
|
||||
| [Advanced v] |
|
||||
| [CLI Tools v] |
|
||||
| [Data Management v] |
|
||||
+--------------------------------------------------------------------------+
|
||||
| (Each section expands/capses to show settings) |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Collapsible Sections** | Expand/collapse setting categories |
|
||||
| **Theme Selection** | Choose light/dark theme |
|
||||
| **Language Switcher** | Select UI language |
|
||||
| **Notification Preferences** | Configure notification settings |
|
||||
| **Feature Flags** | Toggle experimental features |
|
||||
| **CLI Tools Management** | Enable/disable tools, select default |
|
||||
| **Data Management** | Export/import settings, reset to defaults |
|
||||
| **CCW Installation Status** | View and manage CCW installation |
|
||||
|
||||
---
|
||||
|
||||
## Settings Categories
|
||||
|
||||
### Theme & Appearance
|
||||
|
||||
| Setting | Options | Description |
|
||||
|---------|---------|-------------|
|
||||
| **Theme** | Light, Dark, Auto | Select color theme |
|
||||
| **Font Size** | Small, Medium, Large | Adjust UI text size |
|
||||
|
||||
### Language
|
||||
|
||||
| Setting | Options | Description |
|
||||
|---------|---------|-------------|
|
||||
| **Interface Language** | English, Chinese | Select UI language |
|
||||
|
||||
### Notifications
|
||||
|
||||
| Setting | Options | Description |
|
||||
|---------|---------|-------------|
|
||||
| **Enable Notifications** | Toggle | Show desktop notifications |
|
||||
| **Sound Effects** | Toggle | Play sounds for actions |
|
||||
|
||||
### Advanced
|
||||
|
||||
| Setting | Options | Description |
|
||||
|---------|---------|-------------|
|
||||
| **Chinese Response** | Toggle | Enable Chinese language responses |
|
||||
| **Windows Platform** | Toggle | Enable Windows-specific features |
|
||||
| **Codex CLI Enhancement** | Toggle | Enhanced Codex CLI integration |
|
||||
|
||||
### CLI Tools
|
||||
|
||||
| Tool | Status | Models | Tags |
|
||||
|------|--------|--------|------|
|
||||
| **Gemini** | Toggle | gemini-2.5-flash, gemini-2.5-pro | analysis, debug |
|
||||
| **Qwen** | Toggle | coder-model | - |
|
||||
| **Codex** | Toggle | gpt-5.2 | - |
|
||||
| **Claude** | Toggle | sonnet, haiku | - |
|
||||
| **OpenCode** | Toggle | opencode/glm-4.7-free | - |
|
||||
|
||||
### Default Tool Selection
|
||||
|
||||
Choose which CLI tool to use by default for operations.
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
1. **Browse Settings**: Click section headers to expand/collapse
|
||||
2. **Modify Settings**: Change values using toggles, dropdowns, or inputs
|
||||
3. **Enable/Disable Tools**: Use toggle switches in CLI Tools section
|
||||
4. **Set Default Tool**: Select from dropdown
|
||||
5. **Export Settings**: Click Export to download settings file
|
||||
6. **Import Settings**: Click Import to upload settings file
|
||||
7. **Reset**: Click Reset to Defaults to restore defaults
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Expand section** | Click section header to expand/collapse |
|
||||
| **Toggle setting** | Click toggle switch to enable/disable |
|
||||
| **Select option** | Use dropdown to select from options |
|
||||
| **Export settings** | Click Export button, saves to file |
|
||||
| **Import settings** | Click Import button, select file to upload |
|
||||
| **Reset defaults** | Click Reset to Defaults, confirm in dialog |
|
||||
|
||||
### CCW Installation
|
||||
|
||||
The CCW (Code Canvas Workflow) installation status is displayed with:
|
||||
- **Status Indicator**: Shows if CCW is installed
|
||||
- **Version**: Current CCW version
|
||||
- **Install Button**: Click to install or upgrade CCW
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Settings Persistence
|
||||
|
||||
Settings are stored in:
|
||||
- **Global**: `~/.claude/settings.json`
|
||||
- **Project**: `.claude/settings.json`
|
||||
- **Local**: `.claude/settings.local.json` (highest priority)
|
||||
|
||||
### Feature Flags
|
||||
|
||||
```json
|
||||
{
|
||||
"featureFlags": {
|
||||
"chineseResponse": true,
|
||||
"windowsPlatform": false,
|
||||
"codexCliEnhancement": true,
|
||||
"dashboardQueuePanelEnabled": true,
|
||||
"dashboardInspectorEnabled": true,
|
||||
"dashboardExecutionMonitorEnabled": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### CLI Tools Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"cliTools": {
|
||||
"gemini": { "enabled": true },
|
||||
"qwen": { "enabled": true },
|
||||
"codex": { "enabled": true },
|
||||
"claude": { "enabled": true },
|
||||
"opencode": { "enabled": true }
|
||||
},
|
||||
"defaultCliTool": "gemini"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [API Settings](/features/api-settings) - API endpoint configuration
|
||||
- [CLI Call](/features/cli) - Command line invocation
|
||||
- [Extensions](/features/extensions) - Skills, commands, rules management
|
||||
- [System Settings](/features/system-settings) - Hooks, agents, MCP configuration
|
||||
214
docs/features/tasks-history.md
Normal file
214
docs/features/tasks-history.md
Normal file
@@ -0,0 +1,214 @@
|
||||
# Tasks & History
|
||||
|
||||
## One-Liner
|
||||
|
||||
**Tasks & History pages provide comprehensive views of lite tasks, analysis sessions, prompt history, and review sessions with filtering, search, and detail inspection capabilities.**
|
||||
|
||||
---
|
||||
|
||||
## Lite Tasks
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/LiteTasksPage.tsx`
|
||||
|
||||
**Purpose**: Lite-plan and lite-fix task list page with TaskDrawer for details.
|
||||
|
||||
**Access**: Navigation → Lite Tasks
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Type Tabs** | Switch between lite-plan, lite-fix, multi-cli-plan types |
|
||||
| **Task Cards** | Display task title, description, status, tags, progress |
|
||||
| **TaskDrawer** | Slide-over panel with full task context and synthesis |
|
||||
| **Round Synthesis** | Multi-perspective analysis results |
|
||||
| **Context Content** | Full context view with expandable sections |
|
||||
| **Status Indicators** | Visual badges for task status (planning, in_progress, completed, failed) |
|
||||
| **Progress Bars** | Visual progress for running tasks |
|
||||
| **Tag System** | Category tags for organization |
|
||||
|
||||
### Task Types
|
||||
|
||||
| Type | Description |
|
||||
|------|-------------|
|
||||
| **lite-plan** | Quick planning tasks |
|
||||
| **lite-fix** | Quick bug fix tasks |
|
||||
| **multi-cli-plan** | Multi-perspective planning with multiple tools |
|
||||
|
||||
### Task Status Flow
|
||||
|
||||
```
|
||||
planning → in_progress → completed
|
||||
↓
|
||||
failed
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Analysis Page
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/AnalysisPage.tsx`
|
||||
|
||||
**Purpose**: View analysis sessions from `/workflow:analyze-with-file` command.
|
||||
|
||||
**Access**: Navigation → Analysis
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Session Cards** | Grid view with topic, session ID, status, date |
|
||||
| **Status Filter** | Filter by all, in_progress, completed |
|
||||
| **Date Filter** | Filter by all, today, week, month |
|
||||
| **Date Quick Filter** | Quick select by specific dates with counts |
|
||||
| **Search** | Filter by topic or session ID |
|
||||
| **Pagination** | 16 items per page (4x4 grid) |
|
||||
| **Detail Drawer** | Slide-over panel with tabs |
|
||||
| **Detail Tabs** | Discussion, Conclusions, Explorations, Perspectives |
|
||||
| **Fullscreen Mode** | Immersive view toggle |
|
||||
|
||||
### Analysis Session Structure
|
||||
|
||||
Each session contains:
|
||||
- **Discussion** - Markdown formatted discussion log
|
||||
- **Conclusions** - Structured conclusion data
|
||||
- **Explorations** - Code exploration findings
|
||||
- **Perspectives** - Multi-perspective analysis results
|
||||
|
||||
---
|
||||
|
||||
## Prompt History
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/PromptHistoryPage.tsx`
|
||||
|
||||
**Purpose**: View and manage prompt history with AI insights and timeline view.
|
||||
|
||||
**Access**: Navigation → Prompt History
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Stats Dashboard** | Total prompts, unique intents, session groups |
|
||||
| **Timeline View** | Grouped by session or date |
|
||||
| **Intent Filter** | Filter by bug-fix, feature, refactor, document, analyze |
|
||||
| **Project Filter** | Filter by project path |
|
||||
| **Search** | Filter by prompt content |
|
||||
| **AI Insights** | Pattern analysis and suggestions |
|
||||
| **Insights History** | Historical insight list |
|
||||
| **Batch Operations** | Select all, batch delete |
|
||||
| **Insight Detail** | Click to view full insight |
|
||||
|
||||
### Prompt Card Details
|
||||
|
||||
Each prompt card shows:
|
||||
- **Prompt Text** - Truncated preview
|
||||
- **Intent Badge** - Category classification
|
||||
- **Timestamp** - When prompt was created
|
||||
- **Session Info** - Associated session
|
||||
- **Delete Action** - Remove from history
|
||||
- **Select Checkbox** - Batch selection mode
|
||||
|
||||
---
|
||||
|
||||
## Review Session
|
||||
|
||||
### Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/ReviewSessionPage.tsx`
|
||||
|
||||
**Purpose**: Review session detail page with findings display, multi-select, and fix progress tracking.
|
||||
|
||||
**Access**: Click review link from session detail OR direct route
|
||||
|
||||
### Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Findings Grid** | Card-based findings display |
|
||||
| **Dimension Tabs** | Filter by analysis dimension |
|
||||
| **Severity Filter** | Critical, High, Medium, Low |
|
||||
| **Sort Controls** | Sort by severity, dimension, file |
|
||||
| **Multi-Select** | Select multiple findings |
|
||||
| **Fix Progress** | Track fix stages with carousel |
|
||||
| **Export Selected** | Export selected findings |
|
||||
| **Findings Drawer** | Detail panel for selected finding |
|
||||
|
||||
### Finding Structure
|
||||
|
||||
Each finding contains:
|
||||
- **Title** - Finding summary
|
||||
- **Description** - Detailed explanation
|
||||
- **Severity** - Critical, High, Medium, Low
|
||||
- **Dimension** - Analysis dimension (e.g., security, performance)
|
||||
- **Category** - Finding category
|
||||
- **File/Line** - Source location
|
||||
- **Code Context** - Relevant code snippet
|
||||
- **Recommendations** - Fix suggestions
|
||||
- **Root Cause** - Analysis of root cause
|
||||
- **Impact** - Potential impact
|
||||
|
||||
### Fix Progress Tracking
|
||||
|
||||
| Stage | Description |
|
||||
|-------|-------------|
|
||||
| **Planning** | Fix planning stage |
|
||||
| **Execution** | Fix execution stage |
|
||||
| **Completion** | Fix completion stage |
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `LiteTasksPage` | `@/pages/LiteTasksPage.tsx` | Lite tasks list with drawer |
|
||||
| `AnalysisPage` | `@/pages/AnalysisPage.tsx` | Analysis sessions viewer |
|
||||
| `PromptHistoryPage` | `@/pages/PromptHistoryPage.tsx` | Prompt history with insights |
|
||||
| `ReviewSessionPage` | `@/pages/ReviewSessionPage.tsx` | Review session details |
|
||||
|
||||
### Shared Components
|
||||
|
||||
| Component | Purpose |
|
||||
|-----------|---------|
|
||||
| `TaskDrawer` | Task detail slide-over panel |
|
||||
| `PromptCard` | Prompt display with actions |
|
||||
| `InsightsPanel` | AI insights display |
|
||||
| `InsightDetailPanel` | Insight detail overlay |
|
||||
| `BatchOperationToolbar` | Batch operations controls |
|
||||
|
||||
### State Management
|
||||
|
||||
**Lite Tasks**:
|
||||
- `useLiteTasks` - Task data and context
|
||||
- Fetching: `fetchLiteSessionContext`
|
||||
|
||||
**Analysis**:
|
||||
- `fetchAnalysisSessions` - Session list
|
||||
- `fetchAnalysisDetail` - Session detail
|
||||
|
||||
**Prompt History**:
|
||||
- `usePromptHistory` - Prompt data and stats
|
||||
- `usePromptInsights` - AI insights
|
||||
- `useInsightsHistory` - Historical insights
|
||||
- Mutations: `analyzePrompts`, `deletePrompt`, `batchDeletePrompts`
|
||||
|
||||
**Review Session**:
|
||||
- `useReviewSession` - Review data and fix progress
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Sessions](/features/sessions) - Workflow session management
|
||||
- [Dashboard](/features/dashboard) - Recent tasks widget
|
||||
- [Memory](/features/memory) - Persistent knowledge storage
|
||||
- [Extensions](/features/extensions) - Skills and commands management
|
||||
170
docs/features/terminal.md
Normal file
170
docs/features/terminal.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Terminal Dashboard
|
||||
|
||||
## One-Liner
|
||||
|
||||
**The Terminal Dashboard provides a terminal-first workspace with resizable panes, floating panels, and integrated tools for session monitoring and orchestration.**
|
||||
|
||||
---
|
||||
|
||||
## Pain Points Solved
|
||||
|
||||
| Pain Point | Current State | Terminal Dashboard Solution |
|
||||
|------------|---------------|-----------------------------|
|
||||
| **Scattered terminals** | Multiple terminal windows | Unified tmux-style grid layout |
|
||||
| **No context linkage** | Can't associate terminal output with issues | Association highlight provider |
|
||||
| **Panel overload** | Fixed layout wastes space | Floating panels (mutually exclusive) |
|
||||
| **Missing tools** | Switch between apps | Integrated issues, queue, inspector, scheduler |
|
||||
| **Limited workspace** | Can't see code and terminals together | Resizable three-column layout |
|
||||
|
||||
---
|
||||
|
||||
## Page Overview
|
||||
|
||||
**Location**: `ccw/frontend/src/pages/TerminalDashboardPage.tsx`
|
||||
|
||||
**Purpose**: Terminal-first layout for multi-terminal session management with integrated tools and resizable panels.
|
||||
|
||||
**Access**: Navigation → Terminal Dashboard
|
||||
|
||||
### Layout
|
||||
|
||||
```
|
||||
+--------------------------------------------------------------------------+
|
||||
| Dashboard Toolbar (panel toggles, layout presets, fullscreen) |
|
||||
+--------------------------------------------------------------------------+
|
||||
| +----------------+-------------------------------------------+------------+ |
|
||||
| | Session | Terminal Grid (tmux-style) | File | |
|
||||
| | Group Tree | +----------+ +----------+ | Sidebar | |
|
||||
| | (resizable) | | Term 1 | | Term 2 | | (resizable)| |
|
||||
| | | +----------+ +----------+ | | |
|
||||
| | | +----------+ +----------+ | | |
|
||||
| | | | Term 3 | | Term 4 | | | |
|
||||
| | | +----------+ +----------+ | | |
|
||||
| +----------------+-------------------------------------------+------------+ |
|
||||
+--------------------------------------------------------------------------+
|
||||
| [Floating Panel: Issues+Queue OR Inspector OR Execution OR Scheduler] |
|
||||
+--------------------------------------------------------------------------+
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Features
|
||||
|
||||
| Feature | Description |
|
||||
|---------|-------------|
|
||||
| **Three-Column Layout** | Resizable panes using Allotment: Session tree (left), Terminal grid (center), File sidebar (right) |
|
||||
| **Terminal Grid** | Tmux-style split panes with layout presets (single, split-h, split-v, grid-2x2) |
|
||||
| **Session Group Tree** | Hierarchical view of CLI sessions with grouping by tags |
|
||||
| **Floating Panels** | Mutually exclusive overlay panels (Issues+Queue, Inspector, Execution Monitor, Scheduler) |
|
||||
| **Association Highlight** | Cross-panel linking between terminals, issues, and queue items |
|
||||
| **Layout Presets** | Quick layout buttons: single pane, horizontal split, vertical split, 2x2 grid |
|
||||
| **Launch CLI** | Config modal for creating new CLI sessions with tool, model, and settings |
|
||||
| **Fullscreen Mode** | Immersive mode hides app chrome (header + sidebar) |
|
||||
| **Feature Flags** | Panel visibility controlled by feature flags (queue, inspector, execution monitor) |
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### Basic Workflow
|
||||
|
||||
1. **Launch CLI Session**: Click "Launch CLI" button, configure options (tool, model, shell, working directory)
|
||||
2. **Arrange Terminals**: Use layout presets or manually split panes
|
||||
3. **Navigate Sessions**: Browse session groups in the left tree
|
||||
4. **Toggle Panels**: Click toolbar buttons to show/hide floating panels
|
||||
5. **Inspect Issues**: Open Issues panel to view associated issues
|
||||
6. **Monitor Execution**: Use Execution Monitor panel for real-time tracking
|
||||
|
||||
### Key Interactions
|
||||
|
||||
| Interaction | How to Use |
|
||||
|-------------|------------|
|
||||
| **Launch CLI** | Click "Launch CLI" button, configure session in modal |
|
||||
| **Toggle sidebar** | Click Sessions/Files button in toolbar |
|
||||
| **Open floating panel** | Click Issues/Queue/Inspector/Execution/Scheduler button |
|
||||
| **Close floating panel** | Click X on panel or toggle button again |
|
||||
| **Resize panes** | Drag the divider between panes |
|
||||
| **Change layout** | Click layout preset buttons (single/split/grid) |
|
||||
| **Fullscreen mode** | Click fullscreen button to hide app chrome |
|
||||
|
||||
### Panel Types
|
||||
|
||||
| Panel | Content | Position |
|
||||
|-------|---------|----------|
|
||||
| **Issues+Queue** | Combined Issues panel + Queue list column | Left (overlay) |
|
||||
| **Queue** | Full queue management panel | Right (overlay, feature flag) |
|
||||
| **Inspector** | Association chain inspector | Right (overlay, feature flag) |
|
||||
| **Execution Monitor** | Real-time execution tracking | Right (overlay, feature flag) |
|
||||
| **Scheduler** | Queue scheduler controls | Right (overlay) |
|
||||
|
||||
### Layout Presets
|
||||
|
||||
| Preset | Layout |
|
||||
|--------|--------|
|
||||
| **Single** | One terminal pane |
|
||||
| **Split-H** | Two panes side by side |
|
||||
| **Split-V** | Two panes stacked vertically |
|
||||
| **Grid-2x2** | Four panes in 2x2 grid |
|
||||
|
||||
---
|
||||
|
||||
## Components Reference
|
||||
|
||||
### Main Components
|
||||
|
||||
| Component | Location | Purpose |
|
||||
|-----------|----------|---------|
|
||||
| `TerminalDashboardPage` | `@/pages/TerminalDashboardPage.tsx` | Main terminal dashboard page |
|
||||
| `DashboardToolbar` | `@/components/terminal-dashboard/DashboardToolbar.tsx` | Top toolbar with panel toggles |
|
||||
| `SessionGroupTree` | `@/components/terminal-dashboard/SessionGroupTree.tsx` | Session tree navigation |
|
||||
| `TerminalGrid` | `@/components/terminal-dashboard/TerminalGrid.tsx` | Tmux-style terminal panes |
|
||||
| `FileSidebarPanel` | `@/components/terminal-dashboard/FileSidebarPanel.tsx` | File explorer sidebar |
|
||||
| `FloatingPanel` | `@/components/terminal-dashboard/FloatingPanel.tsx` | Overlay panel wrapper |
|
||||
| `IssuePanel` | `@/components/terminal-dashboard/IssuePanel.tsx` | Issues list panel |
|
||||
| `QueuePanel` | `@/components/terminal-dashboard/QueuePanel.tsx` | Queue management panel |
|
||||
| `QueueListColumn` | `@/components/terminal-dashboard/QueueListColumn.tsx` | Queue list (compact) |
|
||||
| `SchedulerPanel` | `@/components/terminal-dashboard/SchedulerPanel.tsx` | Queue scheduler controls |
|
||||
| `InspectorContent` | `@/components/terminal-dashboard/BottomInspector.tsx` | Association inspector |
|
||||
| `ExecutionMonitorPanel` | `@/components/terminal-dashboard/ExecutionMonitorPanel.tsx` | Execution tracking |
|
||||
|
||||
### State Management
|
||||
|
||||
- **Local state** (TerminalDashboardPage):
|
||||
- `activePanel`: PanelId | null
|
||||
- `isFileSidebarOpen`: boolean
|
||||
- `isSessionSidebarOpen`: boolean
|
||||
|
||||
- **Zustand stores**:
|
||||
- `useWorkflowStore` - Project path
|
||||
- `useAppStore` - Immersive mode state
|
||||
- `useConfigStore` - Feature flags
|
||||
- `useTerminalGridStore` - Terminal grid layout and focused pane
|
||||
- `useExecutionMonitorStore` - Active execution count
|
||||
- `useQueueSchedulerStore` - Scheduler status
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Panel IDs
|
||||
|
||||
```typescript
|
||||
type PanelId = 'issues' | 'queue' | 'inspector' | 'execution' | 'scheduler';
|
||||
```
|
||||
|
||||
### Feature Flags
|
||||
|
||||
| Flag | Controls |
|
||||
|------|----------|
|
||||
| `dashboardQueuePanelEnabled` | Queue panel visibility |
|
||||
| `dashboardInspectorEnabled` | Inspector panel visibility |
|
||||
| `dashboardExecutionMonitorEnabled` | Execution Monitor panel visibility |
|
||||
|
||||
---
|
||||
|
||||
## Related Links
|
||||
|
||||
- [Orchestrator](/features/orchestrator) - Visual workflow editor
|
||||
- [Sessions](/features/sessions) - Session management
|
||||
- [Issue Hub](/features/issue-hub) - Issues, queue, discovery
|
||||
- [Explorer](/features/explorer) - File explorer
|
||||
Reference in New Issue
Block a user