# 2. 快速开始

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

## 2.1 系统要求

- **操作系统**: Linux（主要）、Windows 10/11（WSL 或原生，支持 GUI 自动化）。
- **Python版本**: 需要 Python 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. 优先获取最新 tag 对应的 Jarvis 源码，并使用浅克隆减少下载体积。
2. 将仓库内置依赖目录加入当前会话 `PATH`。
3. 使用仓库内置 `uv` 执行 `uv tool install -e . --python 3.12` 安装 Jarvis。
4. 额外安装 `playwright` 与 `ddgr`。

> **提示**：脚本会优先尝试 Gitee 上的最新 tag；如果无法获取，会回退到 GitHub 或默认分支。
>
> 当前仓库已内置 `x86_64_linux` 平台依赖。一键安装脚本会优先使用仓库内置 `uv`；如果当前平台没有对应内置依赖，脚本会明确提示您手动安装 `uv` 或改用受支持的版本。

### 手动安装

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

#### 从源码安装

```bash
# 1. 克隆最新发布版本源码
# 请将 <latest-tag> 替换为目标 tag
git clone --depth 1 --branch <latest-tag> https://github.com/skyfireitdiy/Jarvis.git

# 2. 进入项目目录
cd Jarvis

# 3. 将仓库内置依赖目录加入 PATH（当前仓库已内置 x86_64_linux）
export PATH="$(pwd)/src/jarvis/jarvis_data/deps/x86_64_linux:$PATH"

# 4. 使用 uv 安装项目与附加工具
uv tool install -e . --python 3.12
uv tool install playwright
uv tool install ddgr
```

> **提示**: 使用 `uv tool install -e . --python 3.12` 安装后，您对源码的任何修改都会立刻生效，非常适合开发者。
>
> 如果当前平台没有对应的仓库内置依赖目录，请先手动安装 `uv`，或切换到包含该平台内置依赖的版本。

#### 其他方式

PyPI、`uv` 直接从 Git 安装、Docker 等方式仍可用于特定场景，但主安装入口已统一为“源码下载 + 仓库内置 `uv` + `uv tool` 安装”。如需容器方式，请参考相关部署文档。

使用 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/` 目录下创建一个默认的配置文件 `config.yaml`。

### 2.3.1 交互式配置向导（推荐）

为了快速完成配置，我们提供了一个交互式配置命令 `jqc` (jarvis-quick-config)，它会一步步指导您完成以下操作：

```bash
# 运行交互式配置向导
jqc
```

该向导会引导您完成：

1. **选择AI平台**: 选择 OpenAI 或 Claude 平台。
2. **输入凭证**: 输入 API 基础 URL 和 API 密钥。
3. **选择模型**: 自动获取可用的模型列表，供您选择。
4. **配置模型组**: 为不同的使用场景（Normal/Smart/Cheap）选择合适的模型。
5. **测试连接**: 测试 API 连接性，确保配置正确。
6. **保存配置**: 自动保存配置到 `~/.jarvis/config.yaml`。

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

**跳过交互式配置**：

如果您在 CI/测试环境中使用 Jarvis，可以通过设置环境变量 `JARVIS_SKIP_INTERACTIVE_CONFIG` 来跳过交互式配置向导：

```bash
export JARVIS_SKIP_INTERACTIVE_CONFIG=1
```

设置此环境变量后，Jarvis 将不会自动启动配置向导，而是直接使用默认配置或已有的配置文件。

### 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-git-commit`            | `jgc`    | 自动化分析代码变更并生成规范的Git提交                |
| `jarvis-git-squash`            | `jgs`    | Git提交历史整理工具                                  |
| `jarvis-platform-manager`      | `jpm`    | 管理和测试不同的大语言模型平台                       |
| `jarvis-quick-config`          | `jqc`    | 快速配置 LLM 平台                                    |
| `jarvis-config`                | `jcfg`   | 配置管理工具，基于 JSON Schema 动态生成配置 Web 页面 |
| `jarvis-tool`                  | `jt`     | 工具管理与调用系统                                   |
| `jarvis-methodology`           | `jm`     | 方法论知识库管理                                     |
| `jarvis-smart-shell`           | `jss`    | 实验性的智能Shell功能                                |
| `jarvis-memory-organizer`      | `jmo`    | 记忆管理工具，支持整理、合并、导入导出               |
| `jarvis-sec`                   | `jsec`   | 安全分析套件，结合启发式扫描和AI深度验证             |
| `jarvis-c2rust`                | `jc2r`   | C→Rust迁移套件，支持渐进式迁移、断点续跑             |
| `jarvis-lsp`                   | `jlsp`   | LSP 语言服务器                                       |
| `jarvis-browser`               | `jb`     | 浏览器自动化                                         |
| `jarvis-windows`               | `jw`     | Windows GUI 自动化                                   |
| `jarvis-web-gateway`           | `jwg`    | Web 网关服务                                         |
| `jarvis-rules-index`           | `jri`    | 规则索引管理                                         |

## 2.6 Web 界面使用

Jarvis 除了命令行界面外，还提供了友好的 Web 界面，支持通过浏览器进行交互。

### 启动 Web 服务

我们提供了便捷的启动脚本 `start.sh`，它会同时启动 Web 网关和前端服务：

```bash
# 在项目根目录下执行
./start.sh
```

该脚本会执行以下操作：

1. 检查 Python 和 npm 环境
2. 启动 Web 网关服务（默认端口 8000）
3. 启动前端开发服务器（默认端口 5173）
4. 首次运行时会自动安装前端依赖

### 访问 Web 界面

启动完成后，您可以通过浏览器访问：

- **前端界面**: `http://127.0.0.1:5173`
- **网关 API**: `http://127.0.0.1:8000`

### 环境变量配置

您可以通过环境变量自定义 Web 服务的配置：

```bash
# 设置网关密码（可选）
export JARVIS_GATEWAY_PASSWORD="your-password"

# 设置网关地址和端口
export JARVIS_GATEWAY_HOST="0.0.0.0"  # 默认 127.0.0.1
export JARVIS_GATEWAY_PORT="8000"   # 默认 8000

# 设置前端地址和端口
export JARVIS_FRONTEND_HOST="0.0.0.0"  # 默认 127.0.0.1
export JARVIS_FRONTEND_PORT="5173"   # 默认 5173

# 然后启动服务
./start.sh
```

### 停止服务

在终端按 `Ctrl+C` 即可停止所有服务。

> **提示**: Web 界面提供了可视化的操作体验，适合图形化交互场景。命令行界面则更适合开发者和自动化场景。

---

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