npm package: @nick848/fe-agent-cli
Description: 专为前端开发设计的多模态 Agent CLI，基于 BDD + TDD + OpenSpec 方法论
Author: fe-agent
Latest version: 0.2.2

# @nick848/fe-agent-cli

专为前端开发设计的多模态 Agent CLI 工具，基于 BDD + TDD + OpenSpec 方法论，实现从需求到代码的全流程自动化。

## 特性

- **REPL 交互模式**：类似 iFlow 的持续交互体验，状态实时显示
- **多模型支持**：支持智谱 AI、OpenAI、Claude、DeepSeek 等多种 LLM
- **多模态输入**：支持文本、图片（设计稿）输入，自动理解设计意图
- **BDD 场景分层**：自动将需求拆分为 Given-When-Then 场景
- **OpenSpec 规格拆分**：将场景拆分为可独立实现的技术规格
- **TDD 测试驱动**：自动生成单元测试，保证代码质量
- **自适应交互**：根据项目成熟度自动调整交互频率
- **自学习能力**：记录开发者习惯，持续优化输出

## 安装

```bash
# 全局安装
npm install -g @nick848/fe-agent-cli
```

## 快速开始

### 启动 CLI

```bash
fe-agent
```

进入 REPL 交互模式：

```
╔════════════════════════════════════════════════════╗
║  fe-agent - 前端开发多模态 Agent CLI              ║
║  基于 BDD + TDD + OpenSpec 方法论                  ║
╚════════════════════════════════════════════════════╝

输入 /help 查看可用命令，/exit 退出

✓ 已加载项目: my-project

> _
```

### 配置模型

```bash
# 交互式选择模型
> /config model

# 直接指定模型
> /config model glm-5
> /config model claude-3.5-sonnet
> /config model deepseek-v3

# 查看所有可用模型
> /config models
```

### 初始化项目

```bash
> /init
```

创建 `.fe-agent` 目录，包含配置文件和项目上下文。

### 开始新需求

```bash
> /new 实现用户登录功能
```

### 其他命令

```bash
> /status        # 显示当前状态
> /stop          # 停止所有服务
> /resume <id>   # 恢复中断的任务
> /help          # 显示帮助
> /exit          # 退出 CLI
```

## 状态栏

CLI 底部实时显示服务状态：

```
──主服务:5173 | storybook:6006 | 工作流: 代码编写
```

## 支持的模型

| 提供商 | 模型 | 特点 |
|--------|------|------|
| 智谱 AI | GLM-5, GLM-4-Plus, GLM-4V | 默认，代码能力强 |
| OpenAI | GPT-4o, GPT-4-Turbo, GPT-3.5-Turbo | 通用性强 |
| Anthropic | Claude 3.5 Sonnet, Claude 3 Opus | 代码能力顶尖 |
| DeepSeek | DeepSeek V3, DeepSeek Coder | 性价比高 |
| Moonshot | Moonshot V1 128K | 长文本支持 |
| 通义千问 | Qwen Max, Qwen Coder | 中文优化 |
| Ollama | Code Llama, DeepSeek Coder | 本地运行 |

## 环境变量

根据使用的模型设置对应的 API Key：

```bash
# 智谱 AI（默认）
export ZHIPU_API_KEY=your_api_key

# OpenAI
export OPENAI_API_KEY=your_api_key

# Anthropic
export ANTHROPIC_API_KEY=your_api_key

# DeepSeek
export DEEPSEEK_API_KEY=your_api_key

# 其他...
```

## 工作流程

`/new` 命令执行完整的开发工作流：

```
需求输入 → 需求分析 → 复杂度判断 → [架构师评审] → Mock生成 → BDD分层 → OpenSpec拆分 → TDD测试 → 代码编写 → [Storybook] → 代码审核 → 自动提交
    │         │            │              │            │          │           │           │          │           │          │
  多模态    类型/优先级   分数/级别     高复杂度时    接口数据   场景分层    规格项      测试用例    生成代码   UI组件时   质量检查
```

### 工作流步骤详解

| 步骤 | 模块 | 说明 |
|------|------|------|
| 需求分析 | RequirementAnalyzer | 分析类型、优先级、关键点、复杂度评分 |
| 复杂度判断 | ComplexityAnalyzer | 计算 8 维度复杂度，判断是否需要架构师 |
| 架构师评审 | ArchitectAgent | 高复杂度需求时介入，生成架构方案 |
| Mock 生成 | MockGenerator | 根据需求生成接口 Mock 数据 |
| BDD 分层 | BDDGenerator | 生成 Given-When-Then 场景（需确认） |
| OpenSpec 拆分 | OpenSpecSplitter | 拆分为独立可实现的规格项（需确认） |
| TDD 生成 | TDDGenerator | 根据规格生成测试用例 |
| 代码编写 | CoderAgent | 根据规格和测试生成代码 |
| Storybook 更新 | (可选) | UI 组件时自动更新 |
| 代码审核 | ReviewerAgent | 代码质量检查（需确认） |
| 自动提交 | GitManager | 提交代码到 Git |

### 交互式确认

关键步骤需要开发者确认：

```
── BDD 场景分层 ─────────────────────────────
  生成 1 个 Feature:
  ## Feature: 用户登录
     As a 用户
     I want 安全地登录系统
     So that 访问个人数据
     场景数: 3

? 请确认 BDD 场景分层是否正确？ (Y/n)
```

## API 使用

### 作为 SDK 使用

```typescript
import { createLLM, BDDGenerator, getAvailableModels } from '@nick848/fe-agent-cli';

// 查看可用模型
const models = getAvailableModels();
console.log(models.map(m => m.name));

// 创建 LLM 客户端
const llm = createLLM({
  model: 'glm-5',
  provider: 'zhipu',
});

// 创建 BDD 生成器
const bddGenerator = new BDDGenerator(llm);

// 生成 BDD 场景
const result = await bddGenerator.generate('实现用户登录功能');
console.log(result.features);
```

### 核心 Agent

```typescript
import { ArchitectAgent, CoderAgent, TesterAgent, ReviewerAgent } from '@nick848/fe-agent-cli';

// 架构师 Agent - 复杂度判断和架构方案
const architect = new ArchitectAgent(llm);

// 编码 Agent - 代码生成
const coder = new CoderAgent(llm);

// 测试 Agent - 测试生成
const tester = new TesterAgent(llm);

// 审核 Agent - 代码审核
const reviewer = new ReviewerAgent(llm);
```

### REPL 集成

```typescript
import { createREPL, CommandRegistry } from '@nick848/fe-agent-cli';

// 创建 REPL
const repl = createREPL();

// 注册自定义命令
const commands = repl.getCommands();
commands.register('/custom', {
  description: '自定义命令',
  handler: async (args, options, context) => {
    // 你的逻辑
    return { success: true };
  },
});

// 启动
await repl.start();
```

## 模块说明

### 核心模块

| 模块 | 说明 |
|------|------|
| `repl/` | REPL 交互核心 |
| `core/llm` | 多模型 LLM 客户端 |
| `core/session` | 会话管理 |
| `core/workflow` | 工作流引擎 |

### Agent 模块

| Agent | 说明 |
|-------|------|
| `ArchitectAgent` | 架构师 - 复杂度判断、架构方案生成 |
| `CoderAgent` | 编码 - 代码生成 |
| `TesterAgent` | 测试 - 单元测试生成 |
| `ReviewerAgent` | 审核 - 代码审核、截图对比 |
| `LearnerAgent` | 学习 - 自学习系统 |

### 功能模块

| 模块 | 说明 |
|------|------|
| `bdd/` | BDD 场景生成（Given-When-Then） |
| `openspec/` | OpenSpec 规格拆分 |
| `tdd/` | TDD 测试生成 |
| `requirement/` | 需求分析 |
| `complexity/` | 复杂度分析 |
| `mock/` | Mock 数据生成 |
| `services/` | 服务管理（Node、Storybook） |
| `visualization/` | 可视化（关系图、健康报告） |
| `learning/` | 自学习系统 |

## 开发

```bash
# 安装依赖
npm install

# 构建
npm run build

# 测试
npm test
```

## 发布

详细的发布流程请参阅 [docs/publish.md](docs/publish.md)。

## 技术栈

- **运行时**: Node.js >= 18
- **语言**: TypeScript 5.x
- **CLI**: 自定义 REPL（readline）
- **LLM**: 多模型支持
- **构建**: tsup
- **测试**: Vitest

## License

MIT