|
| 1 | +# 前置依赖文件： [requirements.md](./requirements.md) |
| 2 | + |
| 3 | +# Design Document |
| 4 | + |
| 5 | +## Overview |
| 6 | + |
| 7 | +This feature implements comprehensive support for .coworkflow directory Markdown files by adding file monitoring, CodeLens operations, and visual decorations. The implementation follows VS Code extension patterns and integrates with the existing extension architecture. |
| 8 | + |
| 9 | +## Architecture |
| 10 | + |
| 11 | +The feature consists of three main components: |
| 12 | + |
| 13 | +1. **CoworkflowFileWatcher**: Monitors .coworkflow directory files and coordinates updates |
| 14 | +2. **CoworkflowCodeLensProvider**: Provides contextual actions via CodeLens for different document types |
| 15 | +3. **CoworkflowDecorationProvider**: Manages visual decorations for task status indicators |
| 16 | + |
| 17 | +### Component Interaction Flow |
| 18 | + |
| 19 | +```mermaid |
| 20 | +graph TD |
| 21 | + A[Extension Activation] --> B[CoworkflowFileWatcher] |
| 22 | + B --> C[File System Watchers] |
| 23 | + B --> D[CoworkflowCodeLensProvider] |
| 24 | + B --> E[CoworkflowDecorationProvider] |
| 25 | +
|
| 26 | + C --> F[File Change Events] |
| 27 | + F --> D |
| 28 | + F --> E |
| 29 | +
|
| 30 | + D --> G[CodeLens Actions] |
| 31 | + G --> H[Command Execution] |
| 32 | +
|
| 33 | + E --> I[Text Editor Decorations] |
| 34 | + I --> J[Visual Status Indicators] |
| 35 | +``` |
| 36 | + |
| 37 | +## Components and Interfaces |
| 38 | + |
| 39 | +### 1. CoworkflowFileWatcher |
| 40 | + |
| 41 | +**Purpose**: Central coordinator for file monitoring and provider management |
| 42 | + |
| 43 | +**Key Responsibilities**: |
| 44 | + |
| 45 | +- Monitor .coworkflow directory for requirements.md, design.md, tasks.md |
| 46 | +- Coordinate updates between CodeLens and decoration providers |
| 47 | +- Handle workspace changes and re-establish watchers |
| 48 | + |
| 49 | +**Interface**: |
| 50 | + |
| 51 | +```typescript |
| 52 | +interface CoworkflowFileWatcher { |
| 53 | + initialize(): void |
| 54 | + dispose(): void |
| 55 | + onFileChanged(uri: vscode.Uri): void |
| 56 | + getCoworkflowPath(): string | undefined |
| 57 | +} |
| 58 | +``` |
| 59 | + |
| 60 | +### 2. CoworkflowCodeLensProvider |
| 61 | + |
| 62 | +**Purpose**: Provide contextual actions for different document types |
| 63 | + |
| 64 | +**Key Responsibilities**: |
| 65 | + |
| 66 | +- Parse document structure to identify action locations |
| 67 | +- Provide document-specific actions (Update, Run, Retry) |
| 68 | +- Handle CodeLens command execution |
| 69 | + |
| 70 | +**Interface**: |
| 71 | + |
| 72 | +```typescript |
| 73 | +interface CoworkflowCodeLensProvider extends vscode.CodeLensProvider { |
| 74 | + provideCodeLenses(document: vscode.TextDocument): vscode.CodeLens[] |
| 75 | + resolveCodeLens(codeLens: vscode.CodeLens): vscode.CodeLens |
| 76 | +} |
| 77 | +``` |
| 78 | + |
| 79 | +**Document-Specific Actions**: |
| 80 | + |
| 81 | +- **requirements.md**: "Update" actions at requirement section headers |
| 82 | +- **design.md**: "Update" actions at major section headers |
| 83 | +- **tasks.md**: "Run" and "Retry" actions at individual task items |
| 84 | + |
| 85 | +### 3. CoworkflowDecorationProvider |
| 86 | + |
| 87 | +**Purpose**: Manage visual status indicators for tasks |
| 88 | + |
| 89 | +**Key Responsibilities**: |
| 90 | + |
| 91 | +- Parse task status indicators: `[ ]`, `[-]`, `[x]` |
| 92 | +- Apply appropriate background decorations |
| 93 | +- Update decorations when task status changes |
| 94 | + |
| 95 | +**Interface**: |
| 96 | + |
| 97 | +```typescript |
| 98 | +interface CoworkflowDecorationProvider { |
| 99 | + updateDecorations(document: vscode.TextDocument): void |
| 100 | + dispose(): void |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +**Decoration Types**: |
| 105 | + |
| 106 | +- `[ ]` (未开始): No background decoration |
| 107 | +- `[-]` (进行中): Light yellow background (`rgba(255, 255, 0, 0.2)`) |
| 108 | +- `[x]` (已完成): Light green background (`rgba(0, 255, 0, 0.2)`) |
| 109 | + |
| 110 | +## Data Models |
| 111 | + |
| 112 | +### Task Status Model |
| 113 | + |
| 114 | +```typescript |
| 115 | +interface TaskStatus { |
| 116 | + line: number |
| 117 | + range: vscode.Range |
| 118 | + status: "not_started" | "in_progress" | "completed" |
| 119 | + text: string |
| 120 | +} |
| 121 | +``` |
| 122 | + |
| 123 | +### CodeLens Action Model |
| 124 | + |
| 125 | +```typescript |
| 126 | +interface CoworkflowCodeLens extends vscode.CodeLens { |
| 127 | + documentType: "requirements" | "design" | "tasks" |
| 128 | + actionType: "update" | "run" | "retry" |
| 129 | + context?: { |
| 130 | + taskId?: string |
| 131 | + sectionTitle?: string |
| 132 | + } |
| 133 | +} |
| 134 | +``` |
| 135 | + |
| 136 | +### File Context Model |
| 137 | + |
| 138 | +```typescript |
| 139 | +interface CoworkflowFileContext { |
| 140 | + uri: vscode.Uri |
| 141 | + type: "requirements" | "design" | "tasks" |
| 142 | + lastModified: Date |
| 143 | + isActive: boolean |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +## Error Handling |
| 148 | + |
| 149 | +### File System Errors |
| 150 | + |
| 151 | +- **Missing .coworkflow directory**: Gracefully disable watchers without errors |
| 152 | +- **Missing target files**: Handle file absence without crashing providers |
| 153 | +- **File permission errors**: Log warnings and continue with available functionality |
| 154 | + |
| 155 | +### Parsing Errors |
| 156 | + |
| 157 | +- **Malformed Markdown**: Provide basic functionality, skip problematic sections |
| 158 | +- **Invalid task status**: Default to 'not_started' status for unknown formats |
| 159 | +- **Corrupted file content**: Use fallback parsing with error logging |
| 160 | + |
| 161 | +### Provider Errors |
| 162 | + |
| 163 | +- **CodeLens resolution failures**: Return empty CodeLens array |
| 164 | +- **Decoration application failures**: Log errors and continue |
| 165 | +- **Command execution errors**: Show user-friendly error messages |
| 166 | + |
| 167 | +## Testing Strategy |
| 168 | + |
| 169 | +### Unit Tests |
| 170 | + |
| 171 | +- **CoworkflowFileWatcher**: Test file monitoring, workspace changes, disposal |
| 172 | +- **CoworkflowCodeLensProvider**: Test document parsing, CodeLens generation, command resolution |
| 173 | +- **CoworkflowDecorationProvider**: Test task status parsing, decoration application |
| 174 | + |
| 175 | +### Integration Tests |
| 176 | + |
| 177 | +- **File System Integration**: Test actual file watching with temporary files |
| 178 | +- **VS Code API Integration**: Test CodeLens and decoration providers with mock documents |
| 179 | +- **Command Integration**: Test command execution and error handling |
| 180 | + |
| 181 | +### Edge Case Tests |
| 182 | + |
| 183 | +- **Empty files**: Ensure providers handle empty documents |
| 184 | +- **Large files**: Test performance with documents containing many tasks |
| 185 | +- **Concurrent changes**: Test behavior when multiple files change simultaneously |
| 186 | +- **Workspace switching**: Test proper cleanup and re-initialization |
| 187 | + |
| 188 | +## Implementation Phases |
| 189 | + |
| 190 | +### Phase 1: Core Infrastructure |
| 191 | + |
| 192 | +- Implement CoworkflowFileWatcher with basic file monitoring |
| 193 | +- Set up provider registration and disposal patterns |
| 194 | +- Create basic command structure |
| 195 | + |
| 196 | +### Phase 2: CodeLens Implementation |
| 197 | + |
| 198 | +- Implement CoworkflowCodeLensProvider with document parsing |
| 199 | +- Add document-specific action detection |
| 200 | +- Implement command handlers for Update, Run, Retry actions |
| 201 | + |
| 202 | +### Phase 3: Decoration Implementation |
| 203 | + |
| 204 | +- Implement CoworkflowDecorationProvider with task status parsing |
| 205 | +- Create decoration types for different task statuses |
| 206 | +- Add real-time decoration updates |
| 207 | + |
| 208 | +### Phase 4: Integration and Polish |
| 209 | + |
| 210 | +- Integrate all components with extension activation |
| 211 | +- Add comprehensive error handling |
| 212 | +- Implement performance optimizations |
| 213 | +- Add configuration options if needed |
![roomote[bot]](https://avatars.githubusercontent.com/in/1546624?v=4&size=40){kind=avatar}
0 commit comments