# 2. 快速开始

本章节将指导您如何快速安装、配置并开始使用 Jarvis，开启您的智能AI助手之旅。

## 2.1 系统要求

- **操作系统**: Jarvis 的许多核心工具依赖于Linux环境，因此目前主要支持在 **Linux** 系统下使用。
- **Windows用户**: 虽然未经原生测试，但 Windows 10/11 用户可以通过
  **WSL (Windows Subsystem for Linux)** 来完整地体验 Jarvis 的所有功能。
- **Python版本**: 需要 Python 3.9 或更高版本（支持 3.9-3.12）。
- **Docker**（可选）: 支持通过 Docker 镜像使用，无需本地安装 Python/Rust 环境。

## 2.2 安装

我们提供了两种安装方式：一键安装脚本（推荐）和手动安装。

### 一键安装 (推荐)

为了简化安装过程，我们提供了一个一键安装脚本，它会自动处理所有依赖和配置。只需在您的终端中执行以下命令：

```bash
# GitHub（推荐）
bash -c "$(curl -fsSL https://raw.githubusercontent.com/skyfireitdiy/Jarvis/main/scripts/install.sh)"

# 或者使用 Gitee 镜像（国内访问更快）
bash -c "$(curl -fsSL https://gitee.com/skyfireitdiy/Jarvis/raw/main/scripts/install.sh)"
```

该脚本会执行以下操作：

1. 检测并验证您的Python环境。
2. 从 GitHub 克隆最新的 Jarvis 项目代码。
3. 安装所有必需的依赖项。
4. 设置好相关的环境变量和路径。

### 手动安装

如果您希望更好地控制安装过程，可以选择手动安装。

#### 1. 从源码安装 (获取最新功能)

```bash
# 1. 克隆仓库
# GitHub（推荐）
git clone https://github.com/skyfireitdiy/Jarvis.git

# 或者使用 Gitee 镜像（国内访问更快）
git clone https://gitee.com/skyfireitdiy/Jarvis.git

# 2. 进入项目目录
cd Jarvis

# 3. 安装项目为可编辑模式
pip3 install -e .
```

> **提示**: 使用 `-e .` (可编辑模式) 安装后，您对源码的任何修改都会立刻生效，非常适合开发者。

#### 2. 通过 PyPI 安装 (版本可能稍旧)

```bash
pip3 install jarvis-ai-assistant
```

#### 3. 通过 uv 安装 (推荐)

```bash
# 1. 安装 uv (如果未安装)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 使用 uv tool 安装 jarvis（推荐）
# 从 GitHub 仓库安装
uv tool install git+https://github.com/skyfireitdiy/Jarvis.git

# 或从 Gitee 镜像安装（国内访问更快）
# uv tool install git+https://gitee.com/skyfireitdiy/Jarvis.git
```

> **提示**: `uv tool` 会自动管理工具的虚拟环境，无需手动创建和激活。安装完成后，jarvis 的所有命令（如 `jvs`、`jca` 等）将立即可用。

#### 4. Docker 镜像安装（推荐用于隔离环境）

使用 Docker 镜像可以避免本地环境配置，所有依赖都已预装。镜像已发布到 GitHub Container Registry (GHCR)，**公开可用，无需登录**。

**从 GitHub Container Registry 拉取镜像：**

```bash
# 拉取最新版本
docker pull ghcr.io/skyfireitdiy/jarvis:latest
```

> **提示**:
>
> - 镜像默认公开，无需登录即可拉取
> - 每次发布新版本时，会自动生成多个标签：`latest`、`v1.0.0`、`1.0`、`1` 等
> - 建议使用 `latest` 标签获取最新版本

**使用 Docker Compose（推荐）：**

Docker Compose 配置默认使用**非 root 用户**（jarvis 用户，UID 1000），避免文件权限问题：

```bash
# 运行容器（使用预构建镜像，无需本地构建）
docker-compose run --rm jarvis
```

> **说明**:
>
> - 容器使用 jarvis 用户（UID 1000）运行，GID 可通过环境变量 `GID` 设置（默认 1000），建议设置为当前用户的组 ID 以避免文件权限问题
> - 容器内创建的文件将属于 jarvis 用户，如果 GID 匹配宿主机组，外部可以直接访问，无需调整权限
> - 配置文件（`.jarvis` 和 `.gitconfig`）会自动挂载到容器内用户的主目录

**直接使用 Docker 命令：**

```bash
# 使用当前用户运行（推荐，避免权限问题）
docker run -it --rm \
  --user "$(id -u):$(id -g)" \
  -v $(pwd):/workspace \
  -v $HOME/.jarvis:/home/jarvis/.jarvis \
  -v $HOME/.gitconfig:/home/jarvis/.gitconfig:ro \
  -w /workspace \
  ghcr.io/skyfireitdiy/jarvis:latest
```

> **提示**:
>
> - Docker 镜像已预装所有工具（Python 3.12、Rust、Clang、Fish shell 等），开箱即用
> - 容器启动后会自动进入 fish shell，虚拟环境已激活
> - 使用 `-v` 挂载目录可以方便地在容器内处理本地代码
> - **推荐使用非 root 用户**，避免文件权限问题，容器内创建的文件可直接在宿主机访问
> - 挂载 `.gitconfig` 可以保留 Git 用户信息，方便在容器内使用 Git
> - 使用 Docker Compose 是最简单的方式，自动处理用户权限配置和文件挂载
> - 推荐直接使用 GHCR 上的预构建镜像，无需本地构建

## 2.3 首次运行与配置

安装完成后，首次运行任何 `jarvis` 命令（如 `jvs`），系统会检测是否缺少配置文件。如果未找到配置，Jarvis 将自动启动一个交互式的配置向导，引导您完成所有必要设置。

### 2.3.1 交互式配置向导

这个向导是配置 Jarvis 的**推荐方式**，它会一步步指导您完成以下操作：

1. **选择AI平台**: 向导会列出所有支持的AI平台（如 OpenAI、Claude 等），让您选择一个希望使用的平台。
2. **输入凭证**: 根据您的选择，向导会提示您输入该平台所需的凭证（例如 API Key 或 Cookies）。
3. **选择模型**: 凭证输入后，向导会自动获取该平台下可用的模型列表，供您选择。
4. **测试配置**: 选定模型后，向导会发送一条测试消息以验证您的配置是否正确。
5. **生成配置文件**: 测试通过后，向导会自动在 `~/.jarvis/` 目录下为您生成 `config.yaml` 配置文件。

整个过程无需手动创建或编辑文件，大大简化了初始设置。

### 2.3.2 手动配置 (可选)

如果您偏好手动管理配置文件，或者需要进行更复杂的设置，也可以跳过交互式向导。

#### 1. 生成默认配置文件

首次运行任何 `jarvis` 命令（例如 `jvs` 或 `jpm info`），如果
`~/.jarvis/config.yaml` 不存在，系统会先尝试启动交互式向导。您可以直接
按 `Ctrl+C` 退出向导，然后一个默认的配置文件将会被创建。

#### 2. 获取平台凭证

您需要手动获取所选平台的凭证。具体方法如下：

- **OpenAI**: 获取您的 `OPENAI_API_KEY` 和 `OPENAI_API_BASE`
  (如果使用代理)。
- **Claude**: 获取您的 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_API_BASE`
  (如果使用代理)。

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

打开 `~/.jarvis/config.yaml`，填入您的凭证信息。

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/skyfireitdiy/Jarvis/main/docs/schema/config.schema.json

# ====== 基础配置 ======
# 设置默认使用的模型组
llm_group: default

# ====== 模型组配置 ======
# 可以定义多个模型组，通过llm_group切换
llm_groups:
  default: # 默认模型组
    normal_llm: gpt-5 # 引用下面llms中定义的模型
    # 可选配置廉价模型和智能模型
    # cheap_llm: gpt-3.5-turbo
    # smart_llm: gpt-5

# ====== 模型定义 ======
llms:
  gpt-5:
    platform: openai # 平台类型
    model: gpt-5 # 模型名称
    max_input_token_count: 128000 # 模型最大输入token数

    # 模型特定配置 (llm_config)
    llm_config:
      openai_api_key: "your-api-key-here" # 替换为你的API密钥
      openai_api_base: "https://api.openai.com/v1" # API基础地址，可用于代理
      openai_extra_headers: '{"X-Source": "jarvis"}' # 额外的HTTP头（可选）
```

> **注意**: 新版本推荐使用 `llm_groups` 和 `llms` 配置方式，它提供了更灵活的模型管理能力。`ENV` 配置方式仍然支持，但建议迁移到新的配置方式。

保存文件后，您的 Jarvis 就配置完成了！

您也可以通过 `jvs -e` 打开并编辑配置文件来变更这些选项。

> **注意**：当在 Git 仓库中运行时，Jarvis 会自动检测并切换到代码开发模式（jca）。

## 2.4 验证安装

配置完成后，您可以运行以下命令来验证 Jarvis 是否已成功连接到 AI 平台：

```bash
jpm info
```

如果配置正确，它将尝试连接所有您已在 `ENV` 中提供凭证的AI平台，  
 并列出每个平台下所有可用的模型。这是一个验证所有凭证是否正确的绝佳方式。  
 如果某个或多个平台未能成功列出模型，  
 请返回检查 `config.yaml` 中对应的凭证。

> **注意**: 有的平台即使没有正确配置凭证，也可能会列出可用的模型，但这并不代表配置一定成功。  
> 要最终确认配置是否正确，最好的方式是尝试直接与模型进行对话，  
> 例如使用 `jpm chat -p <platform> -m <model>` 命令。  
> 如果能够成功对话，则说明配置无误。

## 2.5 命令概览

Jarvis 安装后会向系统注册一系列命令。每个命令都对应一个特定的功能代理，并提供了一个长命令和一个短的快捷方式。

| 命令                           | 快捷方式 | 功能描述                                 |
| ------------------------------ | -------- | ---------------------------------------- |
| `jarvis`                       | `jvs`    | 通用AI代理，适用于多种任务               |
| `jarvis-agent`                 | `ja`     | AI代理基础功能，处理会话和任务           |
| `jarvis-agent-dispatcher`      | `jvsd`   | jvs便捷封装，支持任务派发和交互模式      |
| `jarvis-code-agent`            | `jca`    | 代码分析、修改和生成代理                 |
| `jarvis-code-agent-dispatcher` | `jcad`   | jca便捷封装，支持任务派发和交互模式      |
| `jarvis-code-review`           | `jcr`    | 智能代码审查工具                         |
| `jarvis-git-commit`            | `jgc`    | 自动化分析代码变更并生成规范的Git提交    |
| `jarvis-git-squash`            | `jgs`    | Git提交历史整理工具                      |
| `jarvis-platform-manager`      | `jpm`    | 管理和测试不同的大语言模型平台           |
| `jarvis-tool`                  | `jt`     | 工具管理与调用系统                       |
| `jarvis-methodology`           | `jm`     | 方法论知识库管理                         |
| `jarvis-smart-shell`           | `jss`    | 实验性的智能Shell功能                    |
| `jarvis-memory-organizer`      | `jmo`    | 记忆管理工具，支持整理、合并、导入导出   |
| `jarvis-sec`                   | `jsec`   | 安全分析套件，结合启发式扫描和AI深度验证 |
| `jarvis-c2rust`                | `jc2r`   | C→Rust迁移套件，支持渐进式迁移、断点续跑 |

现在您已经完成了所有设置，可以尝试运行 `jvs` 或 `jca` 来开始您的第一次 Jarvis 之旅了！
