|
| 1 | +# Enhanced Small Model Configuration Plugin - Project Plan |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This project creates an OpenCode plugin that provides comprehensive small_model configuration capabilities through web-based interface and custom tools, addressing the current limitation where small_model cannot be set through the Desktop GUI. |
| 6 | + |
| 7 | +## Project Goals |
| 8 | + |
| 9 | +- [ ] Enable persistent small_model configuration in opencode.jsonc |
| 10 | +- [ ] Provide intuitive web-based settings interface |
| 11 | +- [ ] Offer model discovery and recommendation system |
| 12 | +- [ ] Support model presets for different workflows |
| 13 | +- [ ] Create seamless user experience with multiple access methods |
| 14 | + |
| 15 | +## Technical Architecture |
| 16 | + |
| 17 | +### Core Components |
| 18 | + |
| 19 | +``` |
| 20 | +.more-preferences/ |
| 21 | +├── .opencode/ |
| 22 | +│ ├── plugin/ |
| 23 | +│ │ ├── small-model-config.ts # Main plugin entry point |
| 24 | +│ │ ├── model-discovery.ts # Available model detection |
| 25 | +│ │ ├── config-manager.ts # opencode.jsonc manipulation |
| 26 | +│ │ ├── web-server.ts # Web UI server |
| 27 | +│ │ ├── preset-manager.ts # Model preset management |
| 28 | +│ │ └── recommendation-engine.ts # Smart model suggestions |
| 29 | +│ └── command/ |
| 30 | +│ └── small-model.md # Slash command definition |
| 31 | +├── web-ui/ # Settings interface |
| 32 | +│ ├── index.html # Main settings page |
| 33 | +│ ├── components/ |
| 34 | +│ │ ├── model-selector.js # Model selection component |
| 35 | +│ │ ├── preset-manager.js # Preset management |
| 36 | +│ │ ├── model-info.js # Model details display |
| 37 | +│ │ └── config-validator.js # Input validation |
| 38 | +│ ├── style.css # UI styling |
| 39 | +│ └── assets/ |
| 40 | +│ └── icons/ # UI icons |
| 41 | +├── tests/ # Test suite |
| 42 | +│ ├── config-manager.test.ts |
| 43 | +│ ├── model-discovery.test.ts |
| 44 | +│ └── web-server.test.ts |
| 45 | +├── docs/ # Documentation |
| 46 | +│ ├── API.md # API documentation |
| 47 | +│ ├── INSTALLATION.md # Setup instructions |
| 48 | +│ └── USER_GUIDE.md # Usage guide |
| 49 | +├── package.json # Dependencies |
| 50 | +├── tsconfig.json # TypeScript configuration |
| 51 | +└── README.md # Project overview |
| 52 | +``` |
| 53 | + |
| 54 | +## Implementation Phases |
| 55 | + |
| 56 | +### Phase 1: Core Infrastructure (Week 1) |
| 57 | + |
| 58 | +#### 1.1 Plugin Foundation |
| 59 | +- [ ] Set up plugin structure following OpenCode patterns |
| 60 | +- [ ] Create TypeScript configuration and build pipeline |
| 61 | +- [ ] Implement basic plugin registration and context handling |
| 62 | +- [ ] Set up error handling and logging framework |
| 63 | + |
| 64 | +#### 1.2 Configuration Management |
| 65 | +- [ ] Implement `config-manager.ts` for opencode.jsonc manipulation |
| 66 | +- [ ] Add safe file I/O with backup/restore functionality |
| 67 | +- [ ] Create configuration validation and schema checking |
| 68 | +- [ ] Implement atomic updates to prevent corruption |
| 69 | + |
| 70 | +#### 1.3 Command Interface |
| 71 | +- [ ] Create `.opencode/command/small-model.md` definition |
| 72 | +- [ ] Implement basic slash commands: set, get, list |
| 73 | +- [ ] Add command parsing and validation |
| 74 | +- [ ] Create help system and usage documentation |
| 75 | + |
| 76 | +**Deliverables:** |
| 77 | +- Working plugin with basic small_model set/get functionality |
| 78 | +- Safe configuration file manipulation |
| 79 | +- Command-line interface for basic operations |
| 80 | + |
| 81 | +### Phase 2: Model Discovery & Selection (Week 2) |
| 82 | + |
| 83 | +#### 2.1 Model Discovery System |
| 84 | +- [ ] Implement `model-discovery.ts` for provider enumeration |
| 85 | +- [ ] Add model capability detection (speed, cost, context window) |
| 86 | +- [ ] Create model categorization (fast, balanced, capable) |
| 87 | +- [ ] Implement model availability validation |
| 88 | + |
| 89 | +#### 2.2 Web Server Foundation |
| 90 | +- [ ] Set up Express server in `web-server.ts` |
| 91 | +- [ ] Create REST API endpoints for configuration |
| 92 | +- [ ] Implement CORS and security middleware |
| 93 | +- [ ] Add server status and health checks |
| 94 | + |
| 95 | +#### 2.3 Basic Web UI |
| 96 | +- [ ] Create responsive HTML layout in `index.html` |
| 97 | +- [ ] Implement model selection dropdown with search |
| 98 | +- [ ] Add configuration save/load functionality |
| 99 | +- [ ] Create mobile-friendly responsive design |
| 100 | + |
| 101 | +**Deliverables:** |
| 102 | +- Full model discovery system |
| 103 | +- Working web interface with model selection |
| 104 | +- REST API for configuration management |
| 105 | +- Mobile-responsive UI |
| 106 | + |
| 107 | +### Phase 3: Advanced Features (Week 3) |
| 108 | + |
| 109 | +#### 3.1 Preset Management |
| 110 | +- [ ] Implement `preset-manager.ts` for save/load functionality |
| 111 | +- [ ] Create preset schema and validation |
| 112 | +- [ ] Add built-in presets (fast, balanced, capable) |
| 113 | +- [ ] Implement preset import/export functionality |
| 114 | + |
| 115 | +#### 3.2 Recommendation Engine |
| 116 | +- [ ] Create `recommendation-engine.ts` for smart suggestions |
| 117 | +- [ ] Analyze user's primary model selection |
| 118 | +- [ ] Implement cost/performance trade-off analysis |
| 119 | +- [ ] Add learning from user preferences |
| 120 | + |
| 121 | +#### 3.3 Enhanced Web UI |
| 122 | +- [ ] Add preset management interface |
| 123 | +- [ ] Implement model comparison tool |
| 124 | +- [ ] Create usage analytics dashboard |
| 125 | +- [ ] Add real-time validation feedback |
| 126 | + |
| 127 | +**Deliverables:** |
| 128 | +- Complete preset management system |
| 129 | +- Intelligent model recommendations |
| 130 | +- Advanced web UI with analytics |
| 131 | +- Model comparison tools |
| 132 | + |
| 133 | +### Phase 4: Polish & Integration (Week 4) |
| 134 | + |
| 135 | +#### 4.1 Testing & Validation |
| 136 | +- [ ] Write comprehensive test suite |
| 137 | +- [ ] Add integration tests with various model providers |
| 138 | +- [ ] Perform cross-platform compatibility testing |
| 139 | +- [ ] Conduct security and performance testing |
| 140 | + |
| 141 | +#### 4.2 Documentation & Deployment |
| 142 | +- [ ] Write complete API documentation |
| 143 | +- [ ] Create installation and setup guides |
| 144 | +- [ ] Add user tutorial and FAQ |
| 145 | +- [ ] Prepare for npm/registry distribution |
| 146 | + |
| 147 | +#### 4.3 User Experience Polish |
| 148 | +- [ ] Add keyboard shortcuts and accessibility features |
| 149 | +- [ ] Implement browser notifications for configuration changes |
| 150 | +- [ ] Create quick-access toolbar/pop-up interface |
| 151 | +- [ ] Add session persistence across restarts |
| 152 | + |
| 153 | +**Deliverables:** |
| 154 | +- Production-ready plugin with full test coverage |
| 155 | +- Comprehensive documentation |
| 156 | +- Polished user experience with all features |
| 157 | +- Ready for distribution |
| 158 | + |
| 159 | +## Core Features Specification |
| 160 | + |
| 161 | +### 1. Command-Line Interface |
| 162 | + |
| 163 | +```bash |
| 164 | +/small-model set <model> # Set small_model directly |
| 165 | +/small-model get # Show current setting |
| 166 | +/small-model list # List available models |
| 167 | +/small-model gui # Open web settings interface |
| 168 | +/small-model save <name> # Save current as preset |
| 169 | +/small-model load <name> # Load saved preset |
| 170 | +/small-model presets # List all presets |
| 171 | +/small-model recommend # Get model recommendations |
| 172 | +``` |
| 173 | + |
| 174 | +### 2. Web Interface Features |
| 175 | + |
| 176 | +#### Model Selection |
| 177 | +- Dropdown with search and filtering |
| 178 | +- Model information display (speed, cost, capabilities) |
| 179 | +- Provider grouping and categorization |
| 180 | +- Real-time availability checking |
| 181 | + |
| 182 | +#### Configuration Management |
| 183 | +- Visual small_model setting with validation |
| 184 | +- Live preview of configuration changes |
| 185 | +- Rollback functionality for failed updates |
| 186 | +- Configuration import/export |
| 187 | + |
| 188 | +#### Preset System |
| 189 | +- Create custom presets for different workflows |
| 190 | +- Built-in presets: "Development", "Testing", "Production" |
| 191 | +- Preset sharing via import/export |
| 192 | +- Quick preset switching from web UI |
| 193 | + |
| 194 | +#### Analytics & Insights |
| 195 | +- Model usage statistics and trends |
| 196 | +- Cost analysis and budget tracking |
| 197 | +- Performance metrics and recommendations |
| 198 | +- Visual charts and reports |
| 199 | + |
| 200 | +### 3. Integration Points |
| 201 | + |
| 202 | +#### OpenCode SDK Integration |
| 203 | +- Use `@opencode-ai/plugin` for tool registration |
| 204 | +- Leverage client SDK for model discovery |
| 205 | +- Hook into configuration change events |
| 206 | +- Provide seamless session integration |
| 207 | + |
| 208 | +#### Configuration File Management |
| 209 | +- Safe manipulation of opencode.jsonc |
| 210 | +- Atomic updates with rollback capability |
| 211 | +- Configuration validation and error handling |
| 212 | +- Backup and restore functionality |
| 213 | + |
| 214 | +#### Provider Integration |
| 215 | +- Support for all major OpenCode providers |
| 216 | +- Real-time model availability checking |
| 217 | +- Provider-specific optimization suggestions |
| 218 | +- Automatic model discovery and caching |
| 219 | + |
| 220 | +## Technical Specifications |
| 221 | + |
| 222 | +### Dependencies |
| 223 | + |
| 224 | +```json |
| 225 | +{ |
| 226 | + "dependencies": { |
| 227 | + "@opencode-ai/plugin": "latest", |
| 228 | + "express": "^4.18.2", |
| 229 | + "cors": "^2.8.5", |
| 230 | + "zod": "^3.22.4", |
| 231 | + "js-tiktoken": "^1.0.7" |
| 232 | + }, |
| 233 | + "devDependencies": { |
| 234 | + "typescript": "^5.0.0", |
| 235 | + "@types/node": "^20.0.0", |
| 236 | + "vitest": "^1.0.0", |
| 237 | + "eslint": "^8.0.0" |
| 238 | + } |
| 239 | +} |
| 240 | +``` |
| 241 | + |
| 242 | +### API Endpoints |
| 243 | + |
| 244 | +``` |
| 245 | +GET /api/models # List available models |
| 246 | +GET /api/models/:provider # Models for specific provider |
| 247 | +GET /api/config # Current configuration |
| 248 | +POST /api/config # Update configuration |
| 249 | +GET /api/presets # List saved presets |
| 250 | +POST /api/presets # Create new preset |
| 251 | +PUT /api/presets/:id # Update preset |
| 252 | +DELETE /api/presets/:id # Delete preset |
| 253 | +GET /api/recommendations # Get model recommendations |
| 254 | +``` |
| 255 | + |
| 256 | +### Configuration Schema |
| 257 | + |
| 258 | +```typescript |
| 259 | +interface SmallModelConfig { |
| 260 | + small_model?: string // Currently selected model |
| 261 | + presets?: ModelPreset[] // Saved model presets |
| 262 | + recommendations?: RecommendationConfig |
| 263 | + analytics?: AnalyticsConfig |
| 264 | +} |
| 265 | + |
| 266 | +interface ModelPreset { |
| 267 | + id: string |
| 268 | + name: string |
| 269 | + description: string |
| 270 | + model: string |
| 271 | + created: string |
| 272 | + lastUsed?: string |
| 273 | +} |
| 274 | +``` |
| 275 | + |
| 276 | +## Success Metrics |
| 277 | + |
| 278 | +### Technical Metrics |
| 279 | +- [ ] Plugin loads without errors in all environments |
| 280 | +- [ ] Configuration operations complete in < 500ms |
| 281 | +- [ ] Web UI loads in < 2 seconds |
| 282 | +- [ ] 100% test coverage for core functionality |
| 283 | + |
| 284 | +### User Experience Metrics |
| 285 | +- [ ] Intuitive command interface with clear help text |
| 286 | +- [ ] Responsive web UI that works on mobile and desktop |
| 287 | +- [ ] Zero-configuration setup for new users |
| 288 | +- [ ] Clear error messages and recovery options |
| 289 | + |
| 290 | +### Integration Metrics |
| 291 | +- [ ] Works with all OpenCode Desktop versions |
| 292 | +- [ ] Supports all major model providers |
| 293 | +- [ ] Maintains compatibility with existing opencode.jsonc |
| 294 | +- [ ] Follows OpenCode plugin best practices |
| 295 | + |
| 296 | +## Risks & Mitigations |
| 297 | + |
| 298 | +### Technical Risks |
| 299 | +1. **Configuration file corruption** |
| 300 | + - Risk: Direct file manipulation could break opencode.jsonc |
| 301 | + - Mitigation: Atomic updates with backup/restore functionality |
| 302 | + |
| 303 | +2. **Provider API changes** |
| 304 | + - Risk: Model discovery APIs may change |
| 305 | + - Mitigation: Version-specific adapters and graceful fallbacks |
| 306 | + |
| 307 | +3. **Web server conflicts** |
| 308 | + - Risk: Port conflicts with other plugins |
| 309 | + - Mitigation: Dynamic port allocation and conflict detection |
| 310 | + |
| 311 | +### User Experience Risks |
| 312 | +1. **Complexity overwhelm** |
| 313 | + - Risk: Too many features confuse users |
| 314 | + - Mitigation: Progressive disclosure and simple defaults |
| 315 | + |
| 316 | +2. **Plugin compatibility** |
| 317 | + - Risk: May conflict with other configuration plugins |
| 318 | + - Mitigation: Configuration namespacing and conflict detection |
| 319 | + |
| 320 | +## Future Enhancements |
| 321 | + |
| 322 | +### Post-Release Features |
| 323 | +- [ ] Multi-language support for web UI |
| 324 | +- [ ] Integration with OpenCode Desktop settings (when API allows) |
| 325 | +- [ ] Advanced cost tracking and budgeting |
| 326 | +- [ ] Team/organization preset sharing |
| 327 | +- [ ] Plugin marketplace distribution |
| 328 | + |
| 329 | +### Platform Expansion |
| 330 | +- [ ] Support for OpenCode Web and TUI versions |
| 331 | +- [ ] Docker containerization for easy deployment |
| 332 | +- [ ] CI/CD pipeline for automated updates |
| 333 | +- [ ] Plugin telemetry and analytics |
| 334 | + |
| 335 | +--- |
| 336 | + |
| 337 | +**Project Start Date:** January 31, 2026 |
| 338 | +**Target Completion:** February 28, 2026 |
| 339 | +**Primary Developer:** Plugin Development Team |
| 340 | +**Documentation:** Maintained in `docs/` directory |
| 341 | +**Issues & Tracking:** GitHub Issues (to be created) |
0 commit comments