2e50366cd8
All checks were successful
Beta Release / beta (push) Successful in 2m24s
Major changes: - Refactor CLI entry point to Cobra commands (root, setup, scan, doctor, install, update, lsp, mcp, skills, config, version) - Add LSP registry with health checks, auto-install, and editor config generation - Add MCP registry with editor detection, status tracking, and per-editor configuration - Add workflow engine with planner and step execution for automated task chains - Add conversation search, export (Markdown/JSON), and detailed token counting - Add streaming shell chat handler with tool call/result events - Add skill validation, dry-run testing, and export endpoints - Enrich dashboard with Tools/Activity/Status tabs and tool cards grid - Add PRD documentation - Complete i18n for both EN and FR 💘 Generated with Crush Assisted-by: GLM-5.1 via Crush <crush@charm.land>
915 lines
44 KiB
Markdown
915 lines
44 KiB
Markdown
# Muyue PRD v1.0
|
||
|
||
> **Author**: Product Architect
|
||
> **Date**: 2026-04-22
|
||
> **Status**: Definitive
|
||
|
||
---
|
||
|
||
## 1. Product Vision & Positioning
|
||
|
||
### What is Muyue?
|
||
|
||
Muyue is a local-first, single-binary development environment assistant that combines an AI orchestration layer, a tool manager, and a cyberpunk-themed desktop UI into one cohesive experience. It scans your system, installs missing tools, configures AI agent environments (MCP servers, LSPs, skills), and provides a Studio for AI-assisted workflows — all without requiring cloud infrastructure.
|
||
|
||
### What problem does it solve?
|
||
|
||
Developers spend significant time setting up and maintaining their dev environments: installing tools, configuring MCP servers for AI agents, managing API keys, and switching between CLI tools. Muyue eliminates this friction by providing a single interface that unifies environment management, AI orchestration, and terminal access. It is the "home base" for developers who use AI coding agents (Crush, Claude Code) daily.
|
||
|
||
### Who is it for?
|
||
|
||
- **Primary**: Solo developers and small teams who use AI coding agents (Crush, Claude Code) and want a unified control panel.
|
||
- **Secondary**: Developers setting up new machines who want a "one-click" environment bootstrap.
|
||
- **Not for**: Enterprise teams needing sandboxed environments (Daytona), container orchestration (DevPod), or MCP server registries (MCPM).
|
||
|
||
### How is Muyue different?
|
||
|
||
| Competitor | What they do | What Muyue does differently |
|
||
|---|---|---|
|
||
| **Daytona** | Cloud sandbox infrastructure for AI agents (sandboxes, snapshots, multi-tenant) | Muyue is local-first, lightweight, no infra required. Daytona is "cloud VMs for AI"; Muyue is "desktop control panel for your local AI agents". |
|
||
| **kasetto** | Declarative AI agent environment manager (Rust, CLI-only) | Muyue adds a desktop GUI, interactive workflows, and a terminal. kasetto is "Nix for AI tools"; Muyue is "a cockpit". |
|
||
| **OpenCode** | Terminal-based AI coding agent (Go, TUI, LSP+MCP client) | OpenCode is an AI coding agent itself. Muyue orchestrates agents (Crush, Claude) rather than being one. Muyue provides a desktop UI, tool management, and MCP config generation that OpenCode doesn't. |
|
||
| **DevPod** | Dev environment manager using devcontainers (Go, CLI+Desktop) | DevPod manages remote/container environments. Muyue manages your local machine's tools and AI agent configs. No container overlap. |
|
||
| **MCPM** | MCP server package manager (Python, CLI, registry) | Muyue generates MCP configs for Crush + Claude Code directly. Delegates server discovery to MCPM where needed. |
|
||
| **McpMux** | Desktop MCP gateway/router (Rust) | Muyue manages MCP configs per-tool rather than routing through a gateway. Simpler, no encryption layer needed for local use. |
|
||
|
||
### What Muyue should NOT do (anti-scope)
|
||
|
||
1. **Not a coding agent** — Muyue orchestrates agents (Crush, Claude Code); it does not edit files, run tests, or write code autonomously. The `crush_run` tool delegates to Crush.
|
||
2. **Not a sandbox/container manager** — No Docker orchestration, no VM provisioning. Use DevPod or Daytona for that.
|
||
3. **Not an MCP registry** — No server discovery marketplace. Delegate to MCPM for that.
|
||
4. **Not a CI/CD tool** — No build pipelines, no deployment workflows.
|
||
5. **Not a multi-tenant platform** — Single-user, local machine only. No org management, no billing.
|
||
6. **Not an IDE** — No file tree editor, no debugging, no syntax highlighting. Use VS Code, Zed, or Neovim.
|
||
7. **Not an LSP client** — Muyue installs and manages LSP servers; it does not connect to them as a client. The IDE handles that.
|
||
8. **Not a proxy/gateway** — No AI proxy agents, no request routing. The orchestrator talks directly to providers.
|
||
|
||
---
|
||
|
||
## 2. Feature Matrix
|
||
|
||
### P0 — Must Have for Launch
|
||
|
||
| # | Feature | Priority | Status | Decision | Description |
|
||
|---|---------|----------|--------|----------|-------------|
|
||
| 1 | System scanning (tools, runtimes, editors, shell, git) | P0 | **EXISTS** | KEEP | Scanner checks 14 tools, 8 runtimes, 8 editors, shell setup, git config. Has 5-min cache, JSON output. |
|
||
| 2 | Tool installation (crush, claude, bmad, starship, go, node, python, git, pnpm, uv, docker, gh) | P0 | **EXISTS** | KEEP | Installer handles 12 tools with platform-specific install methods (apt/brew/winget). API endpoint wired. |
|
||
| 3 | CLI subcommands (scan, install, update, setup, config, doctor, version, lsp, mcp, skills) | P0 | **EXISTS** | KEEP | Cobra-based CLI with all documented subcommands. Each has appropriate flags and output. |
|
||
| 4 | Desktop mode (HTTP server + embedded SPA) | P0 | **EXISTS** | KEEP | `desktop.go` serves frontend via `go:embed`, auto-opens browser, handles `--port` and `--no-open`. |
|
||
| 5 | AI orchestration (OpenAI-compatible, multi-provider) | P0 | **EXISTS** | KEEP | Orchestrator supports MiniMax, ZAI, Anthropic, OpenAI, Ollama. History management, tool calling loop. |
|
||
| 6 | Agent tools (10 tools: terminal, crush_run, read_file, list_files, search_files, grep_content, get_config, set_provider, manage_ssh, web_fetch) | P0 | **EXISTS** | KEEP | All 10 tools implemented with proper parameter validation, timeouts, and output truncation. |
|
||
| 7 | Tool execution endpoint | P0 | **EXISTS** | KEEP | `/api/tool/call` dispatches to agent registry for any registered tool. `/api/tools/list` returns all tools. |
|
||
| 8 | MCP server management (scan, configure, generate configs) | P0 | **EXISTS** | KEEP | Scans 12 known MCP servers, generates configs for Crush (`crush.json`) and Claude Code (`.claude.json`). |
|
||
| 9 | LSP server management (scan, install) | P0 | **EXISTS** | KEEP | 16 known LSP servers with install commands. `InstallForLanguages()` for batch installs. |
|
||
| 10 | Skills management (CRUD, deploy, built-in skills) | P0 | **EXISTS** | KEEP | 5 built-in skills (env-setup, git-workflow, api-design, debug-assist, code-review). YAML frontmatter format. Deploy to Crush + Claude Code. |
|
||
| 11 | Conversation persistence (JSON file store) | P0 | **EXISTS** | KEEP | `ConversationStore` with JSON persistence, auto-summarization at 80K tokens. |
|
||
| 12 | API key encryption (AES-256-GCM) | P0 | **EXISTS** | KEEP | `internal/secret/` with encrypt/decrypt. Keys encrypted at rest in config.yaml. |
|
||
| 13 | Config management (YAML, XDG paths, defaults) | P0 | **EXISTS** | KEEP | Full config schema with profile, AI providers, terminal, tools, SSH. Legacy migration from `~/.muyue`. |
|
||
| 14 | Studio tab (AI chat, SSE streaming, tool calls) | P0 | **EXISTS** | KEEP | Full chat UI with SSE streaming, tool call visualization, thinking blocks, markdown rendering. |
|
||
| 15 | Shell tab (PTY terminal, tabs, SSH connections) | P0 | **EXISTS** | KEEP | xterm.js with WebSocket PTY, tab management (max 7), SSH connection support, 6 terminal themes. |
|
||
| 16 | Config tab (profile, providers, theme, language, skills) | P0 | **EXISTS** | KEEP | Two-column layout with profile editing, provider management, key validation, terminal settings. |
|
||
| 17 | First-run profiling wizard (TUI) | P0 | **EXISTS** | KEEP | Charmbracelet/huh TUI wizard: name, pseudo, email, languages, editor, AI provider. Scored suggestions. |
|
||
| 18 | Onboarding wizard (web) | P0 | **EXISTS** | KEEP | React-based web wizard for desktop mode. |
|
||
| 19 | i18n (FR/EN, keyboard layout awareness) | P0 | **EXISTS** | KEEP | Full FR/EN translations, AZERTY/QWERTY/QWERTZ layouts affecting shortcut display. |
|
||
| 20 | Theming (4 cyberpunk themes, CSS custom properties) | P0 | **EXISTS** | KEEP | 4 themes (Red, Pink, Blue, Green) with 30+ CSS variables. Runtime injection. |
|
||
| 21 | Workflow engine (Plan→Execute) | P0 | **EXISTS** | KEEP | State machine with steps (tool_call, condition, approval). JSON persistence. SSE streaming execution. |
|
||
|
||
### P0 — Needs Implementation/Completion
|
||
|
||
| # | Feature | Priority | Status | Decision | Description |
|
||
|---|---------|----------|--------|----------|-------------|
|
||
| 22 | Dashboard tab (tools grid, notifications, quick actions) | P0 | **PARTIAL** | KEEP, BUILD | Currently shows empty workflow/activity placeholders. Needs: tools grid with status badges, update notifications, quick actions (install missing, check updates, rescan, configure MCP). |
|
||
| 23 | Shell AI panel (real AI backend) | P0 | **EXISTS** | KEEP | Was fake, now uses `/api/shell/chat` with real AI backend + tool calling. Functional. |
|
||
| 24 | Tool updates (check + auto-update) | P0 | **EXISTS** | KEEP | `internal/updater/` checks versions and runs auto-updates. API + CLI endpoints wired. |
|
||
|
||
### P1 — Post-Launch
|
||
|
||
| # | Feature | Priority | Status | Decision | Description |
|
||
|---|---------|----------|--------|----------|-------------|
|
||
| 25 | AI-generated skills (via Studio chat) | P1 | **STUBBED** | KEEP | `BuildAIGeneratePrompt()` exists but CLI `skills generate` is a stub. Need to wire to orchestrator. |
|
||
| 26 | SSH test connectivity | P1 | **STUBBED** | KEEP | `handleSSHTest()` returns "not implemented". Add `net.DialTimeout` check. |
|
||
| 27 | Conversation list/switch (multiple conversations) | P1 | **PARTIAL** | KEEP | `/api/conversations` list + delete exist. No create/switch/load. Need multi-conversation support in Studio. |
|
||
| 28 | Dashboard activity log with real events | P1 | **MISSING** | KEEP | Wire install/scan/update events to a notification system that Dashboard renders. |
|
||
| 29 | Starship prompt integration (multi-theme) | P1 | **EXISTS** | KEEP | 3 theme configs (charm, zerotwo, default). `handleApplyStarshipTheme` writes TOML + patches RC files. |
|
||
| 30 | Terminal settings persistence (font, theme) | P1 | **EXISTS** | KEEP | Settings saved to config, loaded on startup. |
|
||
|
||
### P2 — Nice-to-Have
|
||
|
||
| # | Feature | Priority | Status | Decision | Description |
|
||
|---|---------|----------|--------|----------|-------------|
|
||
| 31 | Background daemon (`internal/daemon/`) | P2 | **MISSING** | DEFER | README mentions it. Not needed for launch. Tools can run on-demand. |
|
||
| 32 | HTML preview server (`internal/preview/`) | P2 | **MISSING** | DROP | Use browser or IDE instead. Not Muyue's job. |
|
||
| 33 | AI proxy agents (`internal/proxy/`) | P2 | **MISSING** | DROP | Direct provider communication is sufficient. No proxy layer needed. |
|
||
|
||
### DROPPED
|
||
|
||
| # | Feature | Reason | Replacement |
|
||
|---|---------|--------|-------------|
|
||
| 34 | HTML preview server | Not core value. IDEs handle this. | Browser / VS Code Live Preview |
|
||
| 35 | AI proxy agents | Adds complexity without benefit for local-first tool. | Direct provider API calls |
|
||
| 36 | MCP server registry / marketplace | Out of scope. | MCPM (`mcpm install <server>`) |
|
||
| 37 | Sandboxed code execution | Out of scope. Requires infra. | Daytona sandboxes |
|
||
| 38 | Dev container management | Out of scope. | DevPod |
|
||
| 39 | Full IDE features (file tree, debugger) | Out of scope. | VS Code / Zed / Neovim |
|
||
| 40 | LSP client mode (connecting to LSPs) | Out of scope. Muyue installs LSPs, doesn't consume them. | IDE handles LSP client |
|
||
|
||
---
|
||
|
||
## 3. User Flows
|
||
|
||
### 3.1 First-Time User Opens `muyue`
|
||
|
||
```
|
||
1. User runs `muyue` (or downloaded binary)
|
||
2. No config exists → loadOrSetupConfig() detects first run
|
||
3. Profiler TUI wizard launches:
|
||
a. Asks: name, pseudo, email
|
||
b. Scans system → detects languages → shows scored language options
|
||
c. Detects editors → shows scored editor options
|
||
d. Shows AI provider options → user picks one
|
||
4. If selected provider has no API key → asks for key (masked input)
|
||
5. Config saved to ~/.config/muyue/config.yaml (API key encrypted)
|
||
6. Built-in skills installed to ~/.muyue/skills/
|
||
7. MCP configs generated for Crush + Claude Code
|
||
8. Desktop server starts on port 8080
|
||
9. Browser opens to http://127.0.0.1:8080
|
||
10. Onboarding wizard checks if profile is empty → shows web wizard as fallback
|
||
11. Dashboard tab loads → shows tools grid (some installed, some missing)
|
||
```
|
||
|
||
**Edge cases:**
|
||
- Config file exists but is corrupted → show error, offer `muyue setup` to recreate
|
||
- No internet → profiler still works (local scan only), AI features unavailable
|
||
- API key invalid → doctor command detects, Config tab shows "Invalid key" badge
|
||
|
||
### 3.2 Returning User Opens `muyue`
|
||
|
||
```
|
||
1. User runs `muyue`
|
||
2. Config exists → loads from ~/.config/muyue/config.yaml
|
||
3. Desktop server starts → browser opens (or reconnects)
|
||
4. Previous conversation loaded from conversation.json
|
||
5. Dashboard shows current tool status (cached, 5-min TTL)
|
||
6. If checkOnStart=true → background update check runs
|
||
7. User picks up where they left off
|
||
```
|
||
|
||
### 3.3 User Installs a Missing Tool from Dashboard
|
||
|
||
```
|
||
1. Dashboard shows tools grid with status badges:
|
||
- Green ✓ = installed
|
||
- Red ✗ = missing
|
||
- Yellow ⟳ = update available
|
||
2. User clicks "Install" on a missing tool (e.g., "pnpm")
|
||
3. Frontend calls POST /api/install {"tools": ["pnpm"]}
|
||
4. Backend spawns installer.InstallTool("pnpm") in goroutine
|
||
5. Installer checks if already installed → if yes, returns success
|
||
6. Installer runs `npm install -g pnpm`
|
||
7. Result returned: {"status": "done", "tools": ["pnpm"], "results": [{...}]}
|
||
8. Frontend updates tool status badge to green ✓
|
||
9. Activity log entry added: "Installed pnpm"
|
||
10. System scan cache invalidated
|
||
```
|
||
|
||
**Edge cases:**
|
||
- Install fails (permission denied) → show error in results, suggest `sudo` or manual install
|
||
- Tool requires Node.js but Node isn't installed → installer returns "npx not found, install node first"
|
||
- Multiple tools installed in parallel → `sync.WaitGroup` handles concurrent installs
|
||
|
||
### 3.4 User Starts a Chat in Studio
|
||
|
||
```
|
||
1. User clicks Studio tab (Ctrl+2)
|
||
2. Chat history loaded from /api/chat/history
|
||
3. If no history → welcome message shown
|
||
4. User types message in textarea, presses Enter
|
||
5. Frontend calls POST /api/chat {"message": "...", "stream": true}
|
||
6. SSE connection opens
|
||
7. Backend:
|
||
a. Adds message to conversation store
|
||
b. Checks if summarization needed (>80K tokens)
|
||
c. Creates orchestrator with active provider
|
||
d. Sets system prompt (Studio prompt with agent context)
|
||
e. Sets tools (all 10 agent tools as OpenAI function specs)
|
||
f. Sends to AI provider API
|
||
8. Streaming begins:
|
||
a. Content chunks → SSE {"content": "char"} events
|
||
b. Tool calls → SSE {"tool_call": {...}} events
|
||
c. Tool results → SSE {"tool_result": {...}} events
|
||
d. Max 15 tool iterations
|
||
9. Frontend renders:
|
||
a. Text content streamed character-by-character
|
||
b. Tool calls shown as expandable blocks with icon + status
|
||
c. Thinking blocks (if any) shown with spinner
|
||
10. Final response stored in conversation
|
||
11. SSE {"done": "true"} closes stream
|
||
```
|
||
|
||
**Edge cases:**
|
||
- AI provider returns error → SSE error event, shown as red message
|
||
- Tool execution times out → error result returned to AI, may retry
|
||
- No active provider configured → 503 error, redirect to Config tab
|
||
- API key invalid → 401 error, show "Configure your API key" prompt
|
||
|
||
### 3.5 User Runs a Plan→Execute Workflow
|
||
|
||
```
|
||
1. User types `/plan Set up a Go project with Docker` in Studio
|
||
2. Frontend calls POST /api/workflow/plan {"goal": "Set up a Go project..."}
|
||
3. Backend:
|
||
a. Creates Planner with AI orchestrator
|
||
b. Sends goal to AI with planning prompt
|
||
c. AI generates JSON array of steps
|
||
d. Planner parses response into []Step
|
||
e. Workflow Engine creates workflow with steps
|
||
4. Workflow returned to frontend with ID and steps
|
||
5. Frontend shows workflow panel:
|
||
- Step 1: "Check Go installation" → tool: terminal, args: {command: "go version"}
|
||
- Step 2: "Create project directory" → tool: terminal, args: {command: "mkdir -p ..."}
|
||
- Step 3: "Initialize Go module" → tool: terminal, args: {command: "go mod init ..."}
|
||
- etc.
|
||
6. User clicks "Execute"
|
||
7. Frontend calls POST /api/workflow/execute/{id}?stream=true
|
||
8. SSE stream:
|
||
a. Each step: {"event": "started", "step": {...}}
|
||
b. On completion: {"event": "done", "step": {...}}
|
||
c. On failure: {"event": "failed", "step": {...}}
|
||
d. If approval step: {"event": "awaiting_approval", "step": {...}}
|
||
9. User can approve/skip steps via POST /api/workflow/approve/{id}
|
||
10. Final event: {"event": "workflow_done", "status": "done|failed"}
|
||
```
|
||
|
||
**Edge cases:**
|
||
- AI generates invalid JSON → planner returns error, shown in chat
|
||
- Step fails mid-workflow → remaining steps skipped, workflow marked "failed"
|
||
- Approval step → execution pauses until user approves
|
||
- Workflow exceeds 10 steps → planner prompt limits to 10
|
||
|
||
### 3.6 User Opens Shell, Connects via SSH
|
||
|
||
```
|
||
1. User clicks Shell tab (Ctrl+3)
|
||
2. Default "Local Shell" tab created with xterm.js terminal
|
||
3. WebSocket connects to /api/ws/terminal with {type: "shell", data: ""}
|
||
4. Backend creates PTY via creack/pty, pipes I/O through WebSocket
|
||
5. User sees their shell prompt (starship if configured)
|
||
6. To add SSH tab:
|
||
a. User clicks "+" → dropdown shows:
|
||
- System terminals (zsh, bash, fish)
|
||
- Saved SSH connections (from config)
|
||
- "Add SSH connection" button
|
||
b. User selects saved connection or adds new one
|
||
c. New tab created with {type: "ssh", data: JSON.stringify({host, port, user, key_path})}
|
||
d. Backend establishes SSH connection, creates PTY
|
||
e. Tab shows connected indicator (green dot)
|
||
7. User can rename tabs (double-click), close tabs (×), switch with Alt+1-7
|
||
8. AI assistant panel on right:
|
||
a. User types question
|
||
b. Frontend calls POST /api/shell/chat with message + terminal context
|
||
c. AI responds with shell-aware answers (commands, explanations)
|
||
d. Can execute tools (terminal, read_file, etc.) to help user
|
||
```
|
||
|
||
**Edge cases:**
|
||
- SSH connection fails → tab shows "Connection error" in terminal
|
||
- WebSocket disconnects → terminal shows "Connection closed" message
|
||
- Tab limit (7) reached → "+" button disabled
|
||
- SSH key not found → connection fails, suggest key path
|
||
|
||
### 3.7 User Changes AI Provider
|
||
|
||
```
|
||
1. User clicks Config tab (Ctrl+4)
|
||
2. "AI Providers" panel shows list of providers:
|
||
- MiniMax (active) — Key configured ✓
|
||
- Z.AI — No key
|
||
- Anthropic — No key
|
||
- OpenAI — No key
|
||
- Ollama — No key (local)
|
||
3. User clicks "Configure" on Anthropic
|
||
4. Modal opens with fields: API Key, Model, Base URL
|
||
5. User enters API key
|
||
6. User clicks "Validate" → POST /api/providers/validate
|
||
7. Backend sends test request to Anthropic API with key
|
||
8. Response: {"status": "valid"} or error
|
||
9. User clicks "Activate" → provider set active, others deactivated
|
||
10. Config saved → new orchestrator instances use Anthropic
|
||
```
|
||
|
||
**Edge cases:**
|
||
- Key validation fails → show "Invalid key" badge, don't save
|
||
- No internet → validation times out, show "Connection failed"
|
||
- Ollama selected but not running → user sees local URL, no validation needed
|
||
- Switching provider mid-conversation → new messages use new provider, old messages preserved
|
||
|
||
### 3.8 User Manages MCP Servers
|
||
|
||
```
|
||
1. User opens Config tab → MCP section
|
||
OR: User runs `muyue mcp scan` from CLI
|
||
2. System scans 12 known MCP servers (filesystem, github, git, fetch, memory, etc.)
|
||
3. Each server shows: name, category, installed status (npx available)
|
||
4. User clicks "Configure MCP" → POST /api/mcp/configure
|
||
5. Backend:
|
||
a. Generates MCP config for Crush: ~/.config/crush/crush.json → {"mcps": {...}}
|
||
b. Generates MCP config for Claude Code: ~/.claude.json → {"mcpServers": {...}}
|
||
c. Core servers: filesystem, fetch, memory
|
||
d. Provider-specific: minimax-web-search, minimax-image (if API key set)
|
||
e. Claude-specific: sequential-thinking
|
||
6. Configs written with 0600 permissions
|
||
```
|
||
|
||
**Edge cases:**
|
||
- Existing configs not overwritten (merged) — `writeMCPConfig` merges into existing JSON
|
||
- No API key for provider-specific servers → those servers omitted
|
||
- Crush or Claude Code not installed → configs still generated (for when they are installed)
|
||
|
||
### 3.9 User Manages LSP Servers
|
||
|
||
```
|
||
1. User runs `muyue lsp scan` from CLI
|
||
OR: views LSP section in Config tab
|
||
2. System checks 16 known LSP servers
|
||
3. Each shows: name, language, command path, installed status
|
||
4. User installs specific LSP:
|
||
- CLI: `muyue lsp install gopls`
|
||
- API: POST /api/lsp/install {"name": "gopls"}
|
||
5. Backend runs install command (e.g., `go install golang.org/x/tools/gopls@latest`)
|
||
6. Result: success or error
|
||
```
|
||
|
||
**Edge cases:**
|
||
- LSP has no auto-install command (e.g., clangd) → return "install manually" message
|
||
- Install fails (network error) → show error, suggest retry
|
||
- Language mapping: TypeScript installs 4 servers (TS, JSON, HTML, CSS)
|
||
|
||
### 3.10 User Creates/Deploys a Skill
|
||
|
||
```
|
||
1. User runs `muyue skills init` → installs 5 built-in skills to ~/.muyue/skills/
|
||
2. User creates custom skill:
|
||
- Manually: create ~/.muyue/skills/my-skill/SKILL.md with YAML frontmatter
|
||
- CLI: `muyue skills generate my-skill "Does X for Y" crush`
|
||
- API: POST /api/skills (via Config tab or Studio chat)
|
||
3. SKILL.md format:
|
||
```yaml
|
||
---
|
||
name: my-skill
|
||
description: What it does
|
||
author: username
|
||
version: 1.0.0
|
||
target: crush|claude|both
|
||
tags: [tag1, tag2]
|
||
---
|
||
# Skill instructions in markdown
|
||
```
|
||
4. Deploy: `muyue skills deploy`
|
||
5. Skill copied to:
|
||
- Crush: ~/.config/crush/skills/my-skill/SKILL.md
|
||
- Claude Code: ~/.claude/skills/my-skill/SKILL.md
|
||
```
|
||
|
||
**Edge cases:**
|
||
- Skill already exists at target → overwritten
|
||
- Target is "both" → deployed to both Crush and Claude
|
||
- Delete removes from all locations (source + targets)
|
||
|
||
### 3.11 User Runs `muyue scan` from CLI
|
||
|
||
```
|
||
1. User runs `muyue scan`
|
||
2. Scanner runs full system scan (tools, runtimes, shell, git)
|
||
3. Output: formatted table with columns: Tool, Version, Status, Path
|
||
4. Summary line: "Installed: 8/14"
|
||
5. With --json flag: full JSON output
|
||
```
|
||
|
||
### 3.12 User Runs `muyue doctor` from CLI
|
||
|
||
```
|
||
1. User runs `muyue doctor`
|
||
2. Three checks run:
|
||
a. System scan → shows installed/missing tools
|
||
b. Config check → loads config, validates profile
|
||
c. Connectivity check → HEAD requests to AI provider endpoints
|
||
3. Output: diagnostic report with ✓/✗ indicators
|
||
4. User sees what's broken and can take action
|
||
```
|
||
|
||
---
|
||
|
||
## 4. API Contract
|
||
|
||
### Existing Endpoints (37 routes)
|
||
|
||
| Method | Path | Request Body | Response Body | Status |
|
||
|--------|------|-------------|---------------|--------|
|
||
| GET | `/api/info` | — | `{name, version, author}` | EXISTS |
|
||
| GET | `/api/system` | — | `{system: {os, arch, platform, shell, ...}}` | EXISTS |
|
||
| GET | `/api/tools` | — | `{tools: [{name, installed, version, path}], total}` | EXISTS |
|
||
| GET | `/api/config` | — | `{profile, terminal, bmad}` | EXISTS |
|
||
| GET | `/api/providers` | — | `{providers: [{name, model, active, ...}]}` | EXISTS |
|
||
| GET | `/api/skills` | — | `{skills: [...], count}` | EXISTS |
|
||
| GET | `/api/lsp` | — | `{servers: [{name, language, command, installed}]}` | EXISTS |
|
||
| GET | `/api/mcp` | — | `{servers: [...], configured}` | EXISTS |
|
||
| GET | `/api/updates` | — | `{updates: [{tool, current, latest, needsUpdate}]}` | EXISTS |
|
||
| GET | `/api/editors` | — | `{editors: [{name, installed, version, path}]}` | EXISTS |
|
||
| GET | `/api/terminal/sessions` | — | `{ssh: [...], system: [...]}` | EXISTS |
|
||
| GET | `/api/terminal/themes` | — | `{themes: [{id, name}]}` | EXISTS |
|
||
| GET | `/api/chat/history` | — | `{messages: [...], tokens}` | EXISTS |
|
||
| GET | `/api/tools/list` | — | `{tools: [...], count}` | EXISTS |
|
||
| GET | `/api/workflow/list` | — | `{workflows: [...], count}` | EXISTS |
|
||
| GET | `/api/workflow/{id}` | — | `{id, name, steps, status, ...}` | EXISTS |
|
||
| GET | `/api/conversations` | — | `{conversations: [...]}` | EXISTS |
|
||
| GET | `/api/ssh/connections` | — | `{connections: [...]}` | EXISTS |
|
||
| POST | `/api/scan` | — | `{status: "ok"}` | EXISTS |
|
||
| POST | `/api/install` | `{tools: [string]}` | `{status, tools, results: [{tool, success, message}]}` | EXISTS |
|
||
| POST | `/api/mcp/configure` | — | `{status: "ok"}` | EXISTS |
|
||
| POST | `/api/terminal` | `{command, cwd}` | `{output, error}` | EXISTS |
|
||
| POST | `/api/chat` | `{message, stream}` | SSE stream or `{content}` | EXISTS |
|
||
| POST | `/api/chat/clear` | — | `{status: "ok"}` | EXISTS |
|
||
| POST | `/api/tool/call` | `{tool, args}` | `{success, tool, result, error}` | EXISTS |
|
||
| POST | `/api/shell/chat` | `{message, context, history, cwd, platform, stream}` | SSE stream or `{content, tool_calls}` | EXISTS |
|
||
| POST | `/api/workflow` | `{name, description, type}` | `{id, name, steps, status, ...}` | EXISTS |
|
||
| POST | `/api/workflow/plan` | `{goal}` | `{id, name, steps, status, ...}` | EXISTS |
|
||
| POST | `/api/workflow/execute/{id}` | `?stream=true` optional | SSE stream or workflow object | EXISTS |
|
||
| POST | `/api/workflow/approve/{id}` | `{step_id}` | `{status: "approved"}` | EXISTS |
|
||
| POST | `/api/lsp/install` | `{name}` | `{success, server}` or `{success, error}` | EXISTS |
|
||
| POST | `/api/skills/deploy` | `{name}` optional | `{status, skill}` | EXISTS |
|
||
| POST | `/api/config/reset` | — | `{status: "ok"}` | EXISTS |
|
||
| POST | `/api/providers/validate` | `{name, api_key, model, base_url}` | `{status: "valid"}` or error | EXISTS |
|
||
| POST | `/api/update/run` | `{tool}` optional | `{status, updated}` or `{status, tool}` | EXISTS |
|
||
| POST | `/api/ssh/test` | `{host, port, user}` | `{success, message}` (stubbed) | PARTIAL |
|
||
| POST | `/api/starship/apply-theme` | `{theme}` | `{status, config}` | EXISTS |
|
||
| PUT | `/api/preferences` | `{language, keyboard_layout}` | `{status: "ok"}` | EXISTS |
|
||
| PUT | `/api/config/profile` | `{name, pseudo, email, editor, shell}` | `{status: "ok"}` | EXISTS |
|
||
| PUT | `/api/config/provider` | `{name, api_key, model, base_url, active}` | `{status: "ok"}` | EXISTS |
|
||
| PUT | `/api/terminal/settings` | `{font_size, font_family, theme}` | `{status, theme}` | EXISTS |
|
||
| DELETE | `/api/conversations/{id}` | — | `{status: "deleted"}` | EXISTS |
|
||
| DELETE | `/api/terminal/sessions/{name}` | — | (removes SSH connection) | EXISTS |
|
||
| WS | `/api/ws/terminal` | `{type, data}` | `{type, data}` | EXISTS |
|
||
|
||
### Error Response Format (all endpoints)
|
||
|
||
```json
|
||
{"error": "Human-readable error message"}
|
||
```
|
||
|
||
HTTP status codes: 400 (bad request), 401 (unauthorized), 404 (not found), 405 (method not allowed), 500 (internal), 503 (service unavailable — AI provider not configured).
|
||
|
||
### SSE Event Format
|
||
|
||
```
|
||
data: {"content": "character"}
|
||
data: {"tool_call": {"tool_call_id": "...", "name": "...", "args": "..."}}
|
||
data: {"tool_result": {"tool_call_id": "...", "content": "...", "is_error": false}}
|
||
data: {"done": "true"}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. CLI Contract
|
||
|
||
### Root Command
|
||
|
||
```
|
||
muyue Launch desktop app (opens browser)
|
||
muyue --port=8080 Launch on specific port
|
||
muyue --no-open Launch without opening browser
|
||
```
|
||
|
||
### Subcommands
|
||
|
||
| Command | Flags | Output | Status |
|
||
|---------|-------|--------|--------|
|
||
| `muyue scan` | `--json` | Table or JSON of tools/runtimes | EXISTS |
|
||
| `muyue install [tool]` | `--yes` | Install progress per tool | EXISTS |
|
||
| `muyue update [tool]` | `--check` | Table of versions + status | EXISTS |
|
||
| `muyue setup` | — | Interactive TUI wizard | EXISTS |
|
||
| `muyue config` | — | (subcommand stub) | PARTIAL |
|
||
| `muyue doctor` | — | Diagnostic report | EXISTS |
|
||
| `muyue version` | — | `Muyue version X.Y.Z` | EXISTS |
|
||
| `muyue lsp scan` | — | Table of LSP servers | EXISTS |
|
||
| `muyue lsp install <name>` | — | Install progress | EXISTS |
|
||
| `muyue mcp config` | — | Confirmation message | EXISTS |
|
||
| `muyue mcp scan` | — | Table of MCP servers | EXISTS |
|
||
| `muyue skills list` | — | Table of skills | EXISTS |
|
||
| `muyue skills init` | — | Confirmation | STUBBED |
|
||
| `muyue skills show <name>` | — | Skill details | EXISTS |
|
||
| `muyue skills generate <name> <desc>` | — | (stub) | STUBBED |
|
||
| `muyue skills deploy` | — | Confirmation | EXISTS |
|
||
| `muyue skills delete <name>` | — | Confirmation | EXISTS |
|
||
|
||
### CLI Commands Needing Work
|
||
|
||
| Command | Issue | Fix |
|
||
|---------|-------|-----|
|
||
| `muyue config` | No subcommands (get/set are defined but not registered) | Register `config get <key>` and `config set <key> <value>` as subcommands |
|
||
| `muyue skills init` | Just prints message, doesn't call `skills.InstallBuiltinSkills()` | Wire to actual function |
|
||
| `muyue skills generate` | Just prints message, doesn't call AI | Wire to orchestrator |
|
||
| `muyue install` | Passes `nil` config to installer | Pass loaded config |
|
||
|
||
---
|
||
|
||
## 6. Data Model
|
||
|
||
### 6.1 Config YAML Schema (`~/.config/muyue/config.yaml`)
|
||
|
||
```yaml
|
||
version: "0.2.1"
|
||
|
||
profile:
|
||
name: "Augustin"
|
||
pseudo: "muyue"
|
||
email: "augustin@example.com"
|
||
languages: ["go", "typescript", "python"]
|
||
preferences:
|
||
editor: "nvim"
|
||
shell: "zsh"
|
||
theme: "cyberpunk-red" # cyberpunk-red | cyberpunk-pink | midnight-blue | matrix-green
|
||
default_ai: "minimax"
|
||
auto_update: true
|
||
check_on_start: true
|
||
language: "fr" # fr | en
|
||
keyboard_layout: "azerty" # azerty | qwerty | qwertz
|
||
|
||
ai:
|
||
providers:
|
||
- name: "minimax"
|
||
api_key: "enc:AES256GCM..." # encrypted at rest
|
||
base_url: "https://api.minimax.io/v1"
|
||
model: "MiniMax-M2.7"
|
||
active: true
|
||
- name: "zai"
|
||
model: "glm"
|
||
active: false
|
||
- name: "anthropic"
|
||
api_key: "enc:AES256GCM..."
|
||
model: "claude-sonnet-4-20250514"
|
||
active: false
|
||
- name: "openai"
|
||
api_key: "enc:AES256GCM..."
|
||
base_url: "https://api.openai.com/v1"
|
||
model: "gpt-4o"
|
||
active: false
|
||
- name: "ollama"
|
||
model: "llama3"
|
||
base_url: "http://localhost:11434/api"
|
||
active: false
|
||
|
||
tools:
|
||
- name: "crush"
|
||
installed: true
|
||
version: "v1.2.3"
|
||
auto_update: true
|
||
|
||
bmad:
|
||
installed: true
|
||
version: "latest"
|
||
global: true
|
||
|
||
terminal:
|
||
custom_prompt: true
|
||
prompt_theme: "zerotwo" # charm | zerotwo | default
|
||
ssh:
|
||
- name: "prod-server"
|
||
host: "192.168.1.100"
|
||
port: 22
|
||
user: "deploy"
|
||
key_path: "~/.ssh/id_rsa"
|
||
font_size: 14
|
||
font_family: "'JetBrains Mono', monospace"
|
||
theme: "default" # default | monokai | gruvbox | nord | solarized-dark | dracula
|
||
```
|
||
|
||
### 6.2 Conversation JSON Schema (`~/.config/muyue/conversation.json`)
|
||
|
||
```json
|
||
{
|
||
"messages": [
|
||
{
|
||
"id": "20260422150000.000-1234567890",
|
||
"role": "user|assistant|system",
|
||
"content": "message text or JSON-encoded {content, tool_calls}",
|
||
"time": "2026-04-22T15:00:00Z"
|
||
}
|
||
],
|
||
"summary": "Auto-generated conversation summary when >80K tokens",
|
||
"created_at": "2026-04-22T15:00:00Z",
|
||
"updated_at": "2026-04-22T15:30:00Z"
|
||
}
|
||
```
|
||
|
||
### 6.3 Skill SKILL.md Format
|
||
|
||
```markdown
|
||
---
|
||
name: skill-name
|
||
description: What this skill does
|
||
author: muyue
|
||
version: 1.0.0
|
||
target: both # crush | claude | both
|
||
tags: [tag1, tag2]
|
||
---
|
||
|
||
# Skill Title
|
||
|
||
Instructions for the AI agent in markdown.
|
||
Includes: when to activate, step-by-step instructions, examples, error handling.
|
||
```
|
||
|
||
### 6.4 MCP Config JSON Format
|
||
|
||
**For Crush** (`~/.config/crush/crush.json`):
|
||
```json
|
||
{
|
||
"mcps": {
|
||
"filesystem": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
||
},
|
||
"fetch": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-fetch"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**For Claude Code** (`~/.claude.json`):
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"filesystem": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/projects"]
|
||
},
|
||
"sequential-thinking": {
|
||
"command": "npx",
|
||
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.5 Workflow JSON Schema (`~/.config/muyue/workflows.json`)
|
||
|
||
```json
|
||
[
|
||
{
|
||
"id": "wf-1234567890",
|
||
"name": "Plan: Set up Go project",
|
||
"description": "Full goal description",
|
||
"type": "plan_execute",
|
||
"steps": [
|
||
{
|
||
"id": "step-0",
|
||
"name": "Check Go installation",
|
||
"type": "tool_call",
|
||
"tool": "terminal",
|
||
"args": {"command": "go version"},
|
||
"status": "pending|running|done|failed|awaiting_approval|skipped",
|
||
"result": "",
|
||
"error": "",
|
||
"depends_on": [],
|
||
"started_at": null,
|
||
"ended_at": null
|
||
}
|
||
],
|
||
"status": "pending|running|done|failed",
|
||
"created_at": "2026-04-22T15:00:00Z",
|
||
"updated_at": "2026-04-22T15:00:00Z"
|
||
}
|
||
]
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Technical Decisions
|
||
|
||
### 7.1 CLI Framework: **Keep Cobra** ✓
|
||
|
||
**Decision**: Keep `spf13/cobra` (already in `go.mod`, already used for all 11 subcommands).
|
||
|
||
**Rationale**: Cobra is the de-facto standard for Go CLIs. All commands are already implemented. No benefit to switching to `urfave/cli`.
|
||
|
||
### 7.2 HTTP Router: **Keep stdlib `http.ServeMux`** ✓
|
||
|
||
**Decision**: Keep `net/http.ServeMux`. Do NOT add chi, echo, or gin.
|
||
|
||
**Rationale**:
|
||
- 37 routes registered. Stdlib handles this fine.
|
||
- Go 1.22+ `ServeMux` supports method-based routing (`GET /api/foo`).
|
||
- Adding a framework adds a dependency and learning curve for no benefit.
|
||
- Performance is irrelevant at localhost scale.
|
||
|
||
**One improvement**: Use Go 1.22 method-based patterns to clean up manual method checks:
|
||
```go
|
||
mux.HandleFunc("GET /api/tools", s.handleTools)
|
||
mux.HandleFunc("POST /api/install", s.handleInstall)
|
||
```
|
||
|
||
### 7.3 WebSocket: **Keep gorilla/websocket** ✓
|
||
|
||
**Decision**: Keep `gorilla/websocket` for terminal PTY.
|
||
|
||
**Rationale**: Already working for terminal WebSocket. Only used for one endpoint (`/api/ws/terminal`). No need for a framework.
|
||
|
||
### 7.4 Frontend Framework: **Keep vanilla React** ✓
|
||
|
||
**Decision**: Keep React 19 + vanilla state management. Do NOT add zustand or react-query.
|
||
|
||
**Rationale**:
|
||
- 4 components, ~1200 lines total. State is simple (tab switching, form inputs, chat messages).
|
||
- Adding zustand/redux would be over-engineering for this scale.
|
||
- `useState` + `useCallback` + `useRef` is sufficient.
|
||
- SSE handling is custom and wouldn't benefit from react-query.
|
||
|
||
**One consideration**: If Dashboard grows complex (many sub-components), extract a `useApi` custom hook pattern for data fetching.
|
||
|
||
### 7.5 Async Operations: **SSE for everything** ✓
|
||
|
||
**Decision**: Use SSE (Server-Sent Events) for all streaming operations (chat, workflow execution). Use synchronous JSON for non-streaming operations (install, scan).
|
||
|
||
**Rationale**:
|
||
- SSE is already implemented for chat and workflow execution.
|
||
- Install operations are fast enough to be synchronous (wait for all goroutines, return results).
|
||
- No polling needed.
|
||
- WebSocket only for terminal PTY (bidirectional needed).
|
||
|
||
### 7.6 Workflow Engine: **State machine** ✓
|
||
|
||
**Decision**: Keep the current state machine approach. Do NOT convert to a DAG.
|
||
|
||
**Rationale**:
|
||
- Plans are linear sequences (step 1 → step 2 → step 3).
|
||
- Dependencies are simple (wait for previous step).
|
||
- DAG adds complexity (topological sort, parallel execution) for no benefit.
|
||
- The current `depends_on` field supports basic ordering. Parallel execution can be added later if needed via `TypeParallel` step type (already defined but not implemented).
|
||
|
||
### 7.7 Styling: **Keep CSS custom properties** ✓
|
||
|
||
**Decision**: Keep CSS custom properties + 4 theme objects. Do NOT add Tailwind or CSS-in-JS.
|
||
|
||
**Rationale**:
|
||
- 30+ CSS variables already define the full theme system.
|
||
- Theme switching works by setting `document.documentElement.style.setProperty()`.
|
||
- Adding Tailwind would conflict with the existing CSS architecture.
|
||
- Current CSS is ~1000 lines and well-structured.
|
||
|
||
---
|
||
|
||
## 8. Delegation Strategy
|
||
|
||
### What Muyue delegates to existing tools
|
||
|
||
| Feature | Delegated To | Integration Method | UI |
|
||
|---------|-------------|-------------------|-----|
|
||
| **Code editing / AI coding** | Crush (`crush run`) | `crush_run` agent tool → spawns `crush run <task>` | Studio chat invokes tool, Shell AI panel invokes tool |
|
||
| **Code editing / AI coding** | Claude Code | Skills deployed to `~/.claude/skills/` | Config tab shows deployment status |
|
||
| **MCP server discovery** | MCPM (`mcpm`) | CLI passthrough suggestion | Doctor command suggests `mcpm install <server>` if server missing |
|
||
| **MCP server routing** | McpMux | Not needed | Muyue generates per-tool configs directly |
|
||
| **Dev environments / containers** | DevPod | CLI passthrough suggestion | Doctor suggests DevPod if container needed |
|
||
| **IDE features** | VS Code / Zed / Neovim | Config integration (editor preference) | Config tab sets editor, LSPs installed for editor |
|
||
| **Terminal prompt** | Starship | Config generation (`starship.toml` + RC file patching) | Config tab applies themes |
|
||
| **Git operations** | `git` CLI | Agent `terminal` tool runs git commands | Studio / Shell AI can execute git commands |
|
||
|
||
### Integration Patterns
|
||
|
||
1. **Config Generation** (primary pattern): Muyue generates config files for external tools (Crush `crush.json`, Claude `.claude.json`, Starship `starship.toml`). This is the cleanest integration — no API coupling, no version lock-in.
|
||
|
||
2. **CLI Wrapping**: Muyue invokes external CLIs (`crush run`, `git`, `go install`) through the agent `terminal` tool. Stdout/stderr captured and returned to AI.
|
||
|
||
3. **Suggestion**: Muyue suggests tools the user should install separately (MCPM, DevPod) but doesn't wrap them. `muyue doctor` output includes recommendations.
|
||
|
||
4. **Skills Deployment**: Muyue's skills system deploys SKILL.md files to both Crush and Claude Code directories. Both tools natively understand this format.
|
||
|
||
---
|
||
|
||
## 9. Implementation Priority
|
||
|
||
### Phase 1: Dashboard Completion (P0 gap)
|
||
|
||
The only significant P0 gap is the Dashboard. Current state: empty placeholders.
|
||
|
||
**Dashboard must have:**
|
||
1. **Tools Grid** — Cards for each scanned tool showing name, status badge (installed/missing/update), version, install button
|
||
2. **Quick Actions** — Buttons: "Install missing tools", "Check for updates", "Rescan system", "Configure MCP"
|
||
3. **Update Notifications** — List of tools with available updates, with "Update" buttons
|
||
4. **Activity Log** — Scrollable list of recent events (installs, scans, config changes) with timestamps
|
||
|
||
**Implementation approach:**
|
||
- Fetch from `/api/tools`, `/api/updates`, `/api/editors` on mount
|
||
- Quick actions call existing API endpoints (`POST /api/install`, `POST /api/scan`, `POST /api/mcp/configure`)
|
||
- Activity log: client-side event accumulation (no backend change needed for MVP)
|
||
|
||
### Phase 2: CLI Polish (P0 gaps)
|
||
|
||
1. Wire `muyue skills init` to `skills.InstallBuiltinSkills()`
|
||
2. Wire `muyue skills generate` to orchestrator
|
||
3. Register `muyue config get` and `muyue config set` subcommands
|
||
4. Pass loaded config to installer in `muyue install`
|
||
|
||
### Phase 3: P1 Features
|
||
|
||
1. AI-generated skills via Studio chat
|
||
2. SSH connectivity test
|
||
3. Multi-conversation support in Studio
|
||
4. Real event-based activity log
|
||
|
||
---
|
||
|
||
## 10. Architecture Summary
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Browser (React SPA) │
|
||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │Dashboard │ │ Studio │ │ Shell │ │ Config │ │
|
||
│ │(tools, │ │(AI chat, │ │(xterm.js,│ │(profile, │ │
|
||
│ │ updates, │ │ tool │ │ WS PTY, │ │provider, │ │
|
||
│ │ actions) │ │ calls) │ │ AI panel)│ │ theme) │ │
|
||
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
|
||
└──────────────────────┬──────────────────────────────────┘
|
||
│ HTTP/SSE/WS
|
||
┌──────────────────────┴──────────────────────────────────┐
|
||
│ Go HTTP Server │
|
||
│ ┌────────────────────────────────────────────────────┐ │
|
||
│ │ api.Server (37 routes) │ │
|
||
│ │ /api/chat → SSE stream + tool calling loop │ │
|
||
│ │ /api/shell/chat → SSE stream + tool calling loop │ │
|
||
│ │ /api/ws/terminal → WebSocket PTY │ │
|
||
│ │ /api/install → parallel tool installation │ │
|
||
│ │ /api/workflow/* → CRUD + plan + execute │ │
|
||
│ └────────────────────────────────────────────────────┘ │
|
||
│ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │Scanner │ │ Installer │ │ Updater │ │ MCP │ │
|
||
│ │(14 tools,│ │(12 tools, │ │(version │ │(12 known │ │
|
||
│ │ 8 runts, │ │ platform- │ │ check + │ │ servers, │ │
|
||
│ │ 8 edtrs) │ │ specific) │ │ auto-upd)│ │ config │ │
|
||
│ └──────────┘ └────────────┘ └──────────┘ │ gen) │ │
|
||
│ ┌──────────┐ ┌────────────┐ ┌──────────┐ └──────────┘ │
|
||
│ │ LSP │ │ Skills │ │ Workflow │ │
|
||
│ │(16 known │ │(CRUD + │ │(Plan→ │ │
|
||
│ │ servers) │ │ deploy + │ │ Execute │ │
|
||
│ │ │ │ builtins) │ │ engine) │ │
|
||
│ └──────────┘ └────────────┘ └──────────┘ │
|
||
│ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌──────────┐ │
|
||
│ │Orchestrtr│ │ Agent │ │ Secret │ │ Config │ │
|
||
│ │(OpenAI- │ │ Registry │ │(AES-256- │ │(YAML, │ │
|
||
│ │ compat, │ │(10 tools: │ │ GCM key │ │ XDG, │ │
|
||
│ │ multi- │ │ terminal, │ │ encrypt) │ │ encrypted│ │
|
||
│ │ provider)│ │ files, │ │ │ │ API keys)│ │
|
||
│ │ │ │ grep, etc)│ │ │ │ │ │
|
||
│ └──────────┘ └────────────┘ └──────────┘ └──────────┘ │
|
||
└──────────────────────────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────┐
|
||
│ External Tools/Agents │
|
||
│ Crush, Claude Code, │
|
||
│ Starship, MCP servers │
|
||
└─────────────────────────┘
|
||
```
|
||
|
||
### Key Dependencies
|
||
|
||
| Dependency | Version | Purpose |
|
||
|-----------|---------|---------|
|
||
| `spf13/cobra` | v1.10.2 | CLI framework |
|
||
| `charmbracelet/huh` | v1.0.0 | TUI forms (profiler, API key input) |
|
||
| `charmbracelet/bubbletea` | v1.3.10 | TUI framework (indirect) |
|
||
| `gorilla/websocket` | v1.5.3 | Terminal WebSocket |
|
||
| `creack/pty/v2` | v2.0.1 | PTY for terminal |
|
||
| `gopkg.in/yaml.v3` | v3.0.1 | Config serialization |
|
||
| React 19 | — | Frontend UI |
|
||
| Vite 8 | — | Frontend build |
|
||
| xterm.js | — | Terminal emulator component |
|
||
|
||
### File Count Summary
|
||
|
||
| Layer | Files | Lines (approx) |
|
||
|-------|-------|---------------|
|
||
| Go backend (`internal/`) | 41 `.go` files | ~8,000 |
|
||
| CLI commands (`cmd/`) | 12 `.go` files | ~600 |
|
||
| Frontend (`web/src/`) | ~20 files | ~3,500 |
|
||
| CSS (`web/src/styles/`) | 1 file | ~1,500 |
|
||
| **Total** | ~75 files | ~13,600 |
|
||
|
||
---
|
||
|
||
## 11. Risks & Mitigations
|
||
|
||
| Risk | Impact | Mitigation |
|
||
|------|--------|-----------|
|
||
| AI provider API changes break orchestrator | Studio/Shell chat stops working | Orchestrator uses OpenAI-compatible format (widely supported). Fallback: user switches provider. |
|
||
| Tool install commands change (brew, apt) | Installer fails | Installer returns clear error messages. Doctor command diagnoses. User can install manually. |
|
||
| Frontend grows beyond vanilla React manageability | Hard to maintain | At current scale (4 components), this is not a risk. Re-evaluate if components exceed 20. |
|
||
| Security: API keys in config file | Key exposure | AES-256-GCM encryption at rest. Config file permissions 0600. |
|
||
| Terminal WebSocket security | Remote command execution | Server binds to 127.0.0.1 only. No remote access possible. |
|
||
|
||
---
|
||
|
||
*End of Muyue PRD v1.0*
|