# 配置指南

本文档详细说明如何配置 NSFC Spider 的环境变量和 LLM API。

## 快速配置

### 方式一：使用 CLI 交互式配置（推荐）

安装后首次运行时，可以使用交互式配置：

```bash
nsfc-spider
```

在 CLI 中输入：

```bash
nsfc> /config
```

按提示输入：
- LLM 提供商（openai/anthropic/deepseek/ollama）
- 模型名称
- API Key
- Base URL（可选）

配置会自动保存。

### 方式二：创建配置文件

#### 1. 找到配置文件位置

配置文件可以放在以下任一位置（按优先级）：

1. **当前工作目录**：`./config/.env` 或 `./.env`
2. **用户主目录**：`~/.nsfc_spider/.env`
3. **系统环境变量**

#### 2. 创建配置文件

**Windows 用户**：

```cmd
# 在当前目录创建配置
mkdir config
notepad config\.env
```

**macOS/Linux 用户**：

```bash
# 在当前目录创建配置
mkdir -p config
nano config/.env
```

#### 3. 编辑配置文件

复制以下内容到 `.env` 文件：

```env
# LLM 配置
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=your-api-key-here
LLM_BASE_URL=https://api.openai.com/v1

# 浏览器配置
HEADLESS=false

# 输出目录
OUTPUT_DIR=./output
```

## 详细配置说明

### LLM 配置参数

#### LLM_PROVIDER
LLM 提供商，支持以下选项：
- `openai` - OpenAI（默认）
- `anthropic` - Anthropic Claude
- `deepseek` - DeepSeek
- `ollama` - Ollama 本地模型

#### LLM_MODEL
使用的模型名称，根据提供商不同：
- OpenAI: `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`
- Anthropic: `claude-sonnet-4`, `claude-opus-4`
- DeepSeek: `deepseek-chat`
- Ollama: `llama2`, `mistral`, 等

#### LLM_API_KEY
API 密钥，从对应平台获取：
- OpenAI: https://platform.openai.com/api-keys
- Anthropic: https://console.anthropic.com/
- DeepSeek: https://platform.deepseek.com/

#### LLM_BASE_URL（可选）
API 基础 URL，用于：
- 使用代理服务
- 使用兼容 OpenAI 的第三方服务
- 本地部署的模型

### 浏览器配置

#### HEADLESS
是否使用无头模式：
- `false` - 显示浏览器窗口（默认，推荐调试时使用）
- `true` - 隐藏浏览器窗口（适合生产环境）

### 输出配置

#### OUTPUT_DIR
数据输出目录，默认为 `./output`

## 不同 LLM 提供商的配置示例

### OpenAI

```env
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=sk-proj-xxxxxxxxxxxxx
LLM_BASE_URL=https://api.openai.com/v1
```

### Anthropic Claude

```env
LLM_PROVIDER=anthropic
LLM_MODEL=claude-sonnet-4
LLM_API_KEY=sk-ant-xxxxxxxxxxxxx
```

### DeepSeek

```env
LLM_PROVIDER=openai
LLM_MODEL=deepseek-chat
LLM_API_KEY=sk-xxxxxxxxxxxxx
LLM_BASE_URL=https://api.deepseek.com/v1
```

### Ollama（本地）

```env
LLM_PROVIDER=ollama
LLM_MODEL=llama2
LLM_BASE_URL=http://localhost:11434
```

注意：使用 Ollama 前需要先安装并启动 Ollama 服务。

### 使用代理

如果需要通过代理访问 API：

```env
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
LLM_API_KEY=sk-xxxxxxxxxxxxx
LLM_BASE_URL=https://your-proxy.com/v1
```

## 配置验证

配置完成后，运行以下命令验证：

```bash
nsfc-spider
```

在 CLI 中输入：

```bash
nsfc> /status
```

你应该看到类似输出：

```
【当前状态】
  LLM: gpt-4o ✓
  API: https://api.openai.com/v1
  数据: 无（请先搜索或加载）
```

## 常见问题

### 1. 配置文件不生效

**检查顺序**：
1. 确认文件名是 `.env`（注意前面的点）
2. 确认文件位置正确
3. 确认文件编码为 UTF-8
4. 重启 CLI

### 2. API Key 无效

**解决方法**：
- 检查 API Key 是否正确复制（无多余空格）
- 确认 API Key 未过期
- 检查账户余额是否充足
- 验证 API Key 权限

### 3. 网络连接失败

**可能原因**：
- 网络问题
- 防火墙拦截
- 需要使用代理

**解决方法**：
- 检查网络连接
- 配置代理（设置 `LLM_BASE_URL`）
- 使用 VPN

### 4. 找不到配置文件

**Windows 用户**：
```cmd
# 查看当前目录
cd
# 创建配置目录
mkdir config
```

**macOS/Linux 用户**：
```bash
# 查看当前目录
pwd
# 创建配置目录
mkdir -p config
```

## 安全建议

1. **不要提交 API Key 到版本控制**
   - 将 `.env` 添加到 `.gitignore`
   - 使用环境变量或密钥管理服务

2. **定期轮换 API Key**
   - 定期更新 API Key
   - 删除不再使用的 Key

3. **限制 API Key 权限**
   - 只授予必要的权限
   - 设置使用限额

4. **保护配置文件**
   - 设置适当的文件权限
   - 不要分享包含 API Key 的配置文件

## 高级配置

### 使用环境变量

除了配置文件，也可以直接设置环境变量：

**Windows (PowerShell)**：
```powershell
$env:LLM_PROVIDER="openai"
$env:LLM_MODEL="gpt-4o"
$env:LLM_API_KEY="sk-xxxxx"
```

**macOS/Linux (Bash)**：
```bash
export LLM_PROVIDER="openai"
export LLM_MODEL="gpt-4o"
export LLM_API_KEY="sk-xxxxx"
```

### 多配置管理

如果需要在不同项目中使用不同配置：

1. 在每个项目目录创建独立的 `config/.env`
2. 或使用不同的环境变量前缀

## 下一步

配置完成后，查看 [使用指南](USAGE.md) 开始使用 NSFC Spider。
