前端工程AI助手

Require OpenViking only and disable Git fallback

fa run "Where is FrontAgent RAG implemented?" \ --rag-source openviking \ --open-viking-endpoint https://openviking.example.com/query \ --disable-open-viking-fallback

Dependency State

Required Configuration

1. Install globally via npm

npm install -g frontagent

Use the installed CLI

fa mcp serve

Or run from a source checkout after pnpm build

node /absolute/path/to/FrontAgent-app/apps/cli/dist/index.js \ mcp serve

By default, FrontAgent resolves the project root from the MCP host's workspace roots when the host exposes exactly one file root. If host roots are unavailable, it falls back to the MCP server process current working directory.

Use `--project-root` only when you want to pin the server to a specific project, or when the host exposes multiple workspace roots and FrontAgent cannot choose safely:

One MCP server process is bound to one resolved project root.

Useful server options:

Installed Packages:

react-router-dom, axios

Build

pnpm build

CLI Quick Start

```bash

Usage Examples

Example 1: Create New Project

cd examples
fa run "Create an e-commerce frontend project using React + TypeScript + Vite + Tailwind CSS"

Agent will automatically: 1. Analyze project requirements 2. Generate execution plan 3. Create package.json and config files 4. Request to execute npm install (requires user approval) 5. Generate page components and style files

Example 2: Modify Existing Files

fa run "Modify vite.config.ts to add path alias configuration"

Agent will: 1. Read existing vite.config.ts 2. Understand current configuration 3. Generate new config code 4. Apply minimal patches

Example 3: Add New Features

fa run "Add user authentication feature, including login, registration, and token management"

Agent will: 1. Analyze existing project structure 2. Plan files to create 3. Generate auth-related components 4. Create API integration code 5. Update route configuration

Example 4: Performance Optimization

fa run "Analyze and optimize homepage loading performance"

Agent will: 1. Read relevant component code 2. Analyze performance issues 3. Propose optimization solutions 4. Implement code-level optimizations (lazy loading, code splitting, etc.)

Example 5: Auto Error Recovery

fa run "Add route configuration in App.tsx"

Execution process shows self-healing:

Phase 1: Analysis Phase
  ✓ Step 1: Read package.json

Phase 2: Creation Phase
  ✗ Step 2: Modify App.tsx
     Error: Cannot apply patch: file not found in context

  🔄 Error recovery in progress...
     Analysis: App.tsx not read into context

  ✓ Recovery Step 1: Read src/App.tsx into context
  ✓ Recovery Step 2: Reapply patch to App.tsx

Phase 3: Validation Phase
  ✓ Step 3: Run type check

✅ Task complete! Auto-fixed 1 error

Key Features: - 🎯 Phase-Based Execution - Clear execution phases (Analysis, Creation, Validation) - 🔄 Auto-Fix - Detected file not read, auto-insert read step - 📊 Facts Tracking - System knows which files are read/unread - ⚡ No Retry Needed - One-shot completion, no manual re-runs needed

Example 6: Enable LangGraph Engine

fa run "Implement user profile page and open PR" \
  --type create \
  --engine langgraph \
  --langgraph-checkpoint \
  --max-recovery-attempts 5

Notes: - --engine langgraph enables graph-based phase orchestration - --langgraph-checkpoint enables in-memory checkpointing for the run - After acceptance passes, repository management phase can run git/gh actions

OpenAI Configuration Example

export PROVIDER="openai"
export BASE_URL="https://api.openai.com/v1"
export MODEL="gpt-4"
export API_KEY="sk-..."

Anthropic Configuration Example

export PROVIDER="anthropic"
export BASE_URL="https://api.anthropic.com"
export MODEL="claude-sonnet-4-20250514"
export API_KEY="sk-ant-..."

2. Configure LLM (supports OpenAI and Anthropic)

OpenAI config

export PROVIDER="openai" export BASE_URL="https://api.openai.com/v1" export MODEL="gpt-4" export API_KEY="sk-..."

Or Anthropic config

export PROVIDER="anthropic" export BASE_URL="https://api.anthropic.com" export MODEL="claude-sonnet-4-20250514" export API_KEY="sk-ant-..."

Use LangGraph engine + checkpoint (optional)

fa run "Add route guards and open a PR" --engine langgraph --langgraph-checkpoint ```

Host Configuration

Most MCP hosts use the same mcpServers shape. Start with the simple config:

{
  "mcpServers": {
    "frontagent": {
      "command": "fa",
      "args": [
        "mcp",
        "serve"
      ]
    }
  }
}

If your host UI has separate fields, use:

• Command: fa
• Args: mcp, serve

Do not put fa mcp serve into the command field as one string.

If the host reports command "fa" not found or env: node: No such file or directory, the GUI host probably does not inherit your terminal shell PATH. Then use absolute paths:

which node
which fa

{
  "mcpServers": {
    "frontagent": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/opt/homebrew/bin/fa",
        "mcp",
        "serve"
      ]
    }
  }
}

If you are using a source checkout instead of a globally linked package, point node at the built CLI file after pnpm build:

{
  "mcpServers": {
    "frontagent": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/absolute/path/to/FrontAgent-app/apps/cli/dist/index.js",
        "mcp",
        "serve"
      ]
    }
  }
}

For direct LLM fallback, pass environment variables through the host config:

{
  "mcpServers": {
    "frontagent": {
      "command": "fa",
      "args": [
        "mcp",
        "serve"
      ],
      "env": {
        "PROVIDER": "openai",
        "BASE_URL": "https://api.openai.com/v1",
        "MODEL": "gpt-4",
        "API_KEY": "sk-..."
      }
    }
  }
}

Examples of where to put the config:

• Claude Desktop: add the server under mcpServers in claude_desktop_config.json.
• Cursor: add the server under mcpServers in your Cursor MCP config, for example .cursor/mcp.json.
• Codex or other MCP hosts: use the same command, args, and env values in the host's MCP server configuration surface.

Use OpenViking Wiki as the primary knowledge provider, with Git RAG fallback

fa run "Where is FrontAgent RAG implemented?" \ --rag-source composite \ --open-viking-endpoint https://openviking.example.com/query \ --open-viking-corpus wiki \ --open-viking-namespace docs/openviking \ --open-viking-l1-entry docs/openviking/frontagent-l1.md

Environment Variables

When provider=openai, RAG embeddings inherit the same base-url/api-key by default.

Override them only if your embedding endpoint is different.

fa run "Explain React setState behavior" \ --provider openai \ --base-url https://yunwu.ai/v1 \ --api-key YOUR_TOKEN \ --rag-embedding-model text-embedding-3-small

⚠️ Missing Module References:

• src/pages/HomePage.tsx references non-existent module: ../components/ui/Spinner

Missing Packages:

@types/node

Created Modules

component (3 modules):

• src/components/ui/Button.tsx (default export: Button)
• src/components/ui/Card.tsx (default export: Card)
• src/components/layout/Header.tsx (exports: Header, Navigation)

page (2 modules):

• src/pages/HomePage.tsx (default export: HomePage)
• src/pages/LoginPage.tsx (default export: LoginPage)

Core Modules

Generate a candidate revision and compare it against baseline

fa skill improve frontend-design