# rovodev-install

**Repository Path**: optichub/rovodev-install

## Basic Information

- **Project Name**: rovodev-install
- **Description**: Rovo Dev CLI 一键安装脚本 - 支持 Windows 和 Linux
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 0
- **Created**: 2026-03-02
- **Last Updated**: 2026-03-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Rovo Dev CLI 一键安装 / 配置 / 卸载脚本

自动完成 [Atlassian Rovo Dev CLI](https://support.atlassian.com/rovo/docs/use-rovo-dev-cli/) 的下载、安装、交互式配置引导与卸载，支持 Windows、Linux、macOS。

> **说明**：本脚本仅处理 `acli rovodev auth login` 认证（邮箱 + API Token），不涉及 `acli auth` OAuth 全局认证，两者完全独立。  
> 二进制文件直接从 **Atlassian 官方服务器**（`acli.atlassian.com`）下载，无需第三方镜像。

---

## 前提条件

- Atlassian 账户（[注册](https://www.atlassian.com)）
- 已开通 Rovo Dev 权限的 Atlassian 站点
- 网络可访问 `acli.atlassian.com` 和 `raw.githubusercontent.com`
- Rovo Dev 专用 API Token（[点此生成](https://id.atlassian.com/manage-profile/security/api-tokens)）

---

## 脚本一览

| 脚本 | 功能 | Windows | Linux / macOS |
|------|------|---------|---------------|
| 安装 | 下载、安装、认证 | `install-windows.ps1` | `install-linux.sh` |
| 配置 | 交互式配置向导 | `setup-windows.ps1` | `setup-linux.sh` |
| 卸载 | 完整清理 | `uninstall-windows.ps1` | `uninstall-linux.sh` |

---

## 一键安装

### Windows（PowerShell）

```powershell
irm https://gitee.com/optichub/rovodev-install/raw/master/install-windows.ps1 | iex
```

> 若提示执行策略限制，先运行：
> ```powershell
> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
> ```

### Linux / macOS（Bash）

```bash
curl -fsSL https://gitee.com/optichub/rovodev-install/raw/master/install-linux.sh | bash
```

> macOS 也可使用 Homebrew：
> ```bash
> brew install atlassian/acli/acli && acli rovodev auth login
> ```

---

## 交互式配置向导

安装完成后，运行配置向导进行个性化设置（中英文双语引导）：

### Windows

```powershell
irm https://gitee.com/optichub/rovodev-install/raw/master/setup-windows.ps1 | iex
```

### Linux / macOS

```bash
curl -fsSL https://gitee.com/optichub/rovodev-install/raw/master/setup-linux.sh | bash
```

### 配置向导包含以下 6 个步骤

| 步骤 | 配置项 | 说明 |
|------|--------|------|
| 1 | **AI 模型** | 选择 AI 品牌（Claude / GPT / Gemini / Auto / Custom），按品牌引导配置 effort 推理力度 + thinking 模式，自动写入 `agent.modelVariant`。`modelId` 统一为 `auto`。AI 温度、深度规划工具。 |
| 2 | **控制台与界面** | 颜色主题、输出格式、编辑模式、最大宽度、启动动画。 |
| 3 | **权限预设** | 快速选择权限模式：**ask**（安全确认，推荐）或 **allow**（快速执行）；影子模式开关。 |
| 4 | **Atlassian 集成** | 启用 Jira/Confluence 集成、配置 Jira 项目键（可多选）。 |
| 5 | **MCP 服务器** | 查看/编辑 MCP 配置（扩展外部工具能力）。 |
| 6 | **会话与高级** | 会话持久化目录、工作区状态同步、附加系统提示词。 |

#### Step 1 详解：分品牌模型配置向导

向导会先让你选品牌，再按该品牌的参数引导配置，最终自动组合写入 `agent.modelVariant`。`agent.modelId` 统一为 `auto`，由 Rovo Dev 自动选择该品牌下的最佳模型。

**Claude (Anthropic)**
- `modelId` 统一为 `auto`（自动选最佳 Claude 模型）
- effort：`low` / `medium`（推荐）/ `high` / `max`（最慢最贵）
- thinking：`none`（标准）/ `extended-thinking`（扩展思考链，建议配合 high/max effort）
- 写入示例：`effort:high,thinking:extended-thinking`

**GPT (OpenAI)**
- `modelId` 统一为 `auto`（自动选最佳 GPT 模型）
- effort（o 系列 reasoning 专属）：`none`（普通 GPT 跳过）/ `low` / `medium`（推荐）/ `high` / `xhigh`（OpenAI 专属最高级）
- thinking：GPT/o 系列不用 `modelVariant` 开启思考，直接用 o3/o3-mini 等 modelId 即可
- 写入示例：`effort:xhigh`（o 系列）或 `null`（普通 GPT）

**Gemini (Google)**
- `modelId` 统一为 `auto`（自动选最佳 Gemini 模型）
- thinking：`none`（标准，不需要 effort）/ `thinking`（需配合 thinking 系列模型）
- effort（thinking 模式专属 token 预算）：`low` / `medium`（推荐）/ `high`
- 写入示例：`thinking:thinking,effort:medium`

**Auto** — `modelId=auto`，`modelVariant=null`，让 Rovo Dev 完全自主决策

**Custom** — 自定义 `modelVariant`（`modelId` 始终为 `auto`）

**会话内切换模型：**
- 输入 `/models` 查看所有可用模型
- 输入 `/model <model-id>` 切换到指定模型（如 `/model claude-opus-4-5`）
- 说明：理论上可以在会话内切换，但**部分环境下切换模型可能导致日志文件句柄异常（无法写入日志/报错）**。为稳妥起见：
  - 尽量在新会话切换（退出后重新运行 `acli rovodev run`）
  - 或切换后重启 CLI，并用 `acli rovodev run --restore` 续接上次会话

---

## VS Code（独立 Rovo Dev 插件，无 Atlascode 捆绑）

本仓库额外提供一个 **独立 VS Code 扩展**（`.vsix`），用于在 VS Code 内直接使用 Rovo Dev：
- ✅ VS Code 启动后自动拉起 `acli rovodev serve`（server mode）
- ✅ 侧边栏直接嵌入 server UI
- ✅ 插件内置 Settings 页面：更新 token、检查认证/检查 server 状态、端口配置（0=自动）
- ✅ **兼容用户已安装 CLI**：扩展优先使用 PATH 中已有的 `acli`，不会覆盖/卸载现有安装；仅当系统没有 `acli` 时才在扩展自身目录下载一份。

### 一键安装 VS Code 扩展（默认：下载预构建 VSIX，无需 Node）

> 维护者发布新版本时：请把最新的 `.vsix` 放到 `vscode-rovo-dev/releases/`，并更新 `vscode-rovo-dev/releases/latest.txt` 为最新文件名。

#### Windows（PowerShell）

```powershell
irm https://gitee.com/optichub/rovodev-install/raw/master/install-vscode-rovodev.ps1 | iex
```

如需在本机构建（需要 Node.js + npm）：
```powershell
# 将 -Build 设为 true
irm https://gitee.com/optichub/rovodev-install/raw/master/install-vscode-rovodev-windows.ps1 | iex
# 或下载后执行： .\install-vscode-rovodev-windows.ps1 -Build
```

#### Linux / macOS（Bash）

```bash
curl -fsSL https://gitee.com/optichub/rovodev-install/raw/master/install-vscode-rovodev.sh | bash
```

如需在本机构建（需要 Node.js + npm）：
```bash
BUILD=1 curl -fsSL https://gitee.com/optichub/rovodev-install/raw/master/install-vscode-rovodev-linux.sh | bash
```

### 离线安装（手动 .vsix）

在 `rovodev-install/vscode-rovo-dev/` 目录下执行：

```bash
npm install
npm run package
```

会生成 `rovo-dev-standalone-*.vsix`，然后在 VS Code：
- Extensions → “Install from VSIX...” 选择该文件

### 首次初始化（邮箱 + Token）

安装后首次打开 VS Code，会弹窗提示初始化：
1. 选择 “Start Setup”
2. 输入 Atlassian 邮箱 + API Token
3. 认证成功后，状态栏会显示 server 状态（Running/Stopped/Error）
4. 通过 Activity Bar → Rovo Dev 打开侧边栏即可直接使用

### 端口说明

- 设置项 `rovoDev.serverPort`：
  - `0` = 自动选择未占用端口（默认）
  - 非 0 = 使用固定端口

---

## 一键更新

更新到最新版本，同时保留配置和认证：

### Windows

```powershell
irm https://gitee.com/optichub/rovodev-install/raw/master/update-windows.ps1 | iex
```

### Linux / macOS

```bash
curl -fsSL https://gitee.com/optichub/rovodev-install/raw/master/update-linux.sh | bash
```

更新脚本会：
- ✅ 自动备份当前配置和认证信息
- ✅ 下载并安装最新版本 acli
- ✅ 验证认证状态
- ✅ 可选运行配置向导或快速编辑配置

---
## 一键卸载

### Windows

```powershell
irm https://gitee.com/optichub/rovodev-install/raw/master/uninstall-windows.ps1 | iex
```

### Linux / macOS

```bash
curl -fsSL https://gitee.com/optichub/rovodev-install/raw/master/uninstall-linux.sh | bash
```

---

## 安装路径与 PATH 写入

### Windows

| 运行权限 | 安装路径 | PATH 写入范围 |
|----------|----------|--------------|
| 管理员 | `C:\Program Files\acli\acli.exe` | 系统级 Machine（所有用户） |
| 普通用户 | `%LOCALAPPDATA%\Programs\acli\acli.exe` | 用户级 User（当前用户） |

### Linux

| 权限 | 安装路径 | PATH 写入方式 |
|------|----------|--------------|
| root / sudo | `/usr/local/bin/acli` | `/etc/profile.d/acli.sh`（所有用户） |
| 普通用户 | `~/.local/bin/acli`（XDG 标准） | `~/.bashrc` / `~/.zshrc` |

### macOS

| 权限 | 安装路径 | PATH 写入方式 |
|------|----------|--------------|
| sudo | `/usr/local/bin/acli` | `/etc/paths.d/acli`（path_helper 标准） |
| 普通用户 | `~/.local/bin/acli` | `~/.zshrc` / `~/.profile` |

---

## 支持平台

| 平台 | 架构 |
|------|------|
| Windows 10/11 | x86_64 (amd64)、arm64 |
| Linux（主流发行版） | x86_64 (amd64)、arm64 |
| macOS（Intel / Apple Silicon） | x86_64、arm64 |

---

## 常用命令速查

### 启动 Rovo Dev

```bash
acli rovodev run                    # 交互模式 / Interactive mode
acli rovodev run "fix the bug"      # 单条指令 / Single instruction
acli rovodev run --restore          # 恢复上次会话 / Resume last session
acli rovodev run --shadow           # 影子模式（安全）/ Shadow mode (safe)
acli rovodev run --yolo             # 全部自动批准 / Auto-approve all tools（谨慎：建议仅在可信项目里短暂使用）
acli rovodev serve 8080             # 服务器模式 / Server mode
```

### 会话内斜杠命令

```
/help                   显示所有命令 / Show all commands
/models                 列出 AI 模型 / List AI models
/model <name>           切换模型 / Switch model
/sessions               管理会话 / Manage sessions
/mcp                    MCP 服务器状态 / MCP server status
/tools                  列出可用工具 / List available tools
/permissions            查看工具权限 / View tool permissions
/yolo                   YOLO 模式（自动批准所有工具操作，谨慎使用）
/cost                   Token 用量与费用 / Token usage and cost
/hooks                  事件钩子 / Event hooks
/bug                    报告问题 / Report a bug
```

### 配置与认证

```bash
acli rovodev config             # 在编辑器中打开配置文件
acli rovodev auth status        # 查看认证状态
acli rovodev auth login         # 重新认证
acli rovodev auth logout        # 退出认证
acli rovodev log                # 查看日志
acli --version                  # 查看版本
```

---

## 配置文件说明

配置文件路径：
- Windows: `%USERPROFILE%\.rovodev\config.yml`
- Linux/macOS: `~/.rovodev/config.yml`

主要配置项：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `agent.modelId` | AI 模型 ID（推荐保持 `auto`） | `auto` |
| `agent.modelVariant` | 模型变体：effort + thinking 组合 | `null` |
| `agent.temperature` | 创意温度（0.0~1.0）| `0.3` |
| `agent.enableDeepPlanTool` | 深度规划工具 | `true` |
| `sessions.persistenceDir` | 会话数据存放目录（用于会话恢复/历史） | `~/.rovodev/sessions` |
| `sessions.enableWorkspaceStateSync` | （实验）会话恢复时同步/提示切换工作区 git 状态 | `false` |
| `agent.experimental.enableShadowMode` | 影子模式 | `false` |
| `console.theme` | 颜色主题 | `dark` |
| `console.outputFormat` | 输出格式 | `markdown` |
| `console.editingMode` | 编辑模式 | `EMACS` |
| `console.maxOutputWidth` | 最大输出宽度 | `120` |
| `toolPermissions.default` | 默认工具权限 | `ask` |
| `atlassianConnections.enabled` | Atlassian 集成 | `true` |
| `agent.additionalSystemPrompt` | 附加系统提示词 | `null` |

### modelId 与 modelVariant 说明

#### modelId — 统一使用 `auto`

配置向导统一将 `agent.modelId` 设为 `auto`，由 Rovo Dev 根据当前环境自动选择最佳可用模型，避免因模型 ID 拼写/版本不对导致请求失败。

> 进入会话后可随时用 `/models` 查看可用模型列表，用 `/model <id>` 临时切换。
> 但若你遇到切换后报“无法写入日志”等异常，建议**重启 CLI 后用 `acli rovodev run --restore` 续接会话**（见下方常见问题）。

#### modelVariant — 按品牌组合 effort + thinking

`agent.modelVariant` 用于向 LLM 传递推理参数，格式为 `key:value` 或 `key1:value1,key2:value2` 的组合（区分大小写）。

**Claude (Anthropic)**

| 参数 | 可选值 | 说明 |
|------|--------|------|
| `effort` | `low` / `medium` / `high` / `max` | 推理力度：low=快速省 token；medium=均衡（推荐）；high=深度；max=最强最慢最贵 |
| `thinking` | `none` / `extended-thinking` | 是否开启扩展思考链（CoT）。建议配合 `high` 或 `max` effort 使用 |

示例：`effort:high,thinking:extended-thinking`

**GPT / o系列 (OpenAI)**

| 参数 | 可选值 | 说明 |
|------|--------|------|
| `effort` | `none` / `low` / `medium` / `high` / `xhigh` | o 系列 reasoning 模型专属；普通 GPT 选 `none`（写入 `null`）。`xhigh` 为 OpenAI 专属最高级 |

示例（o3/o3-mini）：`effort:xhigh`；普通 GPT：`null`

> GPT/o 系列不通过 `modelVariant` 开启思考，直接在 `/model` 里切换到 o3/o3-mini 等 reasoning 模型即可。

**Gemini (Google)**

| 参数 | 可选值 | 说明 |
|------|--------|------|
| `thinking` | `none` / `thinking` | 是否开启 Gemini 思考模式（需配合 thinking 系列模型） |
| `effort` | `low` / `medium` / `high` | thinking token 预算，仅在 `thinking=thinking` 时有效 |

示例：`thinking:thinking,effort:medium`；标准模式：`null`

---

## 卸载说明

卸载脚本清理内容：

| 内容 | 说明 |
|------|------|
| acli 二进制 | 所有已知安装路径下的 `acli` / `acli.exe` |
| 配置与数据 | `~/.rovodev/`（认证 token、日志、会话） |
| PATH 条目 | 系统/用户 PATH 中的 acli 相关条目 |
| Shell profile | `.bashrc` / `.zshrc` 中的 PATH 行 |
| 系统文件 | `/etc/paths.d/acli`、`/etc/profile.d/acli.sh` |
| Homebrew | 若通过 brew 安装，自动 `brew uninstall acli` |

---

## 最佳实践与建议

**运行环境建议 (Workspace Tip)**
- **在可写项目目录下运行**：启动 `acli rovodev run` 前，请先 `cd` 到你有写权限的项目目录（如 `~/projects/my-app` 或 `D:\code\my-app`）。
- **避免系统目录**：在 `C:\Windows`、`/usr/bin`、`/System` 等目录下运行会导致文件写入失败或工具执行被拦截。
- Windows 示例：`cd $env:USERPROFILE\source\myproj`
- Linux/macOS 示例：`cd ~/projects/myproj`

**权限模式选择 (Permissions)**
- **ask（推荐）**：最安全，每次工具动作前都会询问确认。适合新用户和生产环境。
- **allow（快速）**：自动批准所有工具动作（相当于长期“全放行”）。适合你非常熟悉工具行为、且始终在受信任项目中工作的人。

**新手如何正确使用 YOLO（建议路线）**
很多新手看到 `allow` 会觉得“要不要一直开着”。建议按下面的方式用：
1) **默认保持 `ask`**：先熟悉 Rovo Dev 会做什么（改哪些文件、跑哪些命令）。
2) **只在需要“提速”且项目完全可信时短暂开启 YOLO**：
   - 启动时加 `--yolo`：`acli rovodev run --yolo`
   - 或在会话中输入 `/yolo`（如果你的版本支持该命令）
3) **YOLO 适合的任务**：批量格式化/重命名、补测试、机械性替换、你能预期影响范围的改动。
4) **YOLO 不建议的场景**：首次接触的陌生代码库、生产环境仓库、删除/迁移大量文件、执行不确定脚本、涉及密钥/账号/权限变更。
5) **用完就关**：最稳妥做法是**退出会话并重新运行不带 `--yolo` 的命令**回到 `ask`；或用 `/permissions` 把默认权限改回 `ask`。

> 关键区别：`allow` 是“长期默认全放行”（写进 config），`--yolo` 更像“这一次运行临时全放行”。对新手来说：**不要把 allow 当成默认**，而是把 yolo 当成“短时间加速档”。

**模型选择建议**
- `modelId` 保持 `auto`，让 Rovo Dev 自动选择最佳可用模型，避免因版本 ID 过期导致失败。
- 需要深度推理时，在配置向导里选 Claude + `effort:high` 或 `effort:max` + `thinking:extended-thinking`。
- 进入会话后可随时用 `/models` 查看完整模型列表，用 `/model <id>` 临时切换。

**附加系统提示词 (Additional System Prompt)**
- 可在向导里填入长期偏好，例如：`Always respond in Chinese. Prefer concise bullet points.`
- 不要填入敏感信息（密码/token），可随时在 `config.yml` 里修改或清空。

## 常见问题

**Q: 为什么向导里选了品牌/effort，但 modelId 写的是 `auto`？**
A: `auto` 让 Rovo Dev 自动匹配当前环境该品牌下的最佳模型，避免因 ID 拼写/版本更新失效。`modelVariant` 才是传递 effort/thinking 能力的关键参数，两者配合使用效果最好。

**Q: 进入会话后怎么切换模型？**
A: 使用 `/models` 查看可用列表，再用 `/model <id>` 切换。

> 注意：如果切换模型后出现“日志无法写入/报错/卡住”等异常，建议退出并重启 CLI，然后用 `acli rovodev run --restore` 继续上次会话（避免丢上下文）。

**Q: 配置向导里能选择具体的模型 ID 吗？**
A: 向导统一使用 `auto` + `modelVariant` 的方式配置，避免 ID 过期导致失败。如需指定具体 ID，进入会话后用 `/model <id>` 切换，或在 `config.yml` 里手动修改 `agent.modelId`。

**Q: 下载速度慢或超时？**  
A: `acli.atlassian.com` 为 Atlassian 官方 CDN，如访问慢可使用代理后重试。

**Q: `acli: command not found`（Linux/macOS）？**  
A: 运行 `source ~/.bashrc`（或 `~/.zshrc`）或重新开终端。

**Q: PowerShell 提示禁止运行脚本？**  
A: 执行 `Set-ExecutionPolicy RemoteSigned -Scope CurrentUser` 后重试。

**Q: `acli auth status` 报未授权，但 `acli rovodev auth status` 正常？**  
A: 正常现象，两者使用独立认证体系，本脚本只配置 Rovo Dev 专用认证。

**Q: 如何更新 acli？**  
A: 重新运行安装脚本，会自动下载最新版并覆盖旧版。

**Q: 配置向导修改后如何生效？**  
A: 配置立即写入 `config.yml`，重新启动 `acli rovodev run` 即可生效。

**Q: 新手到底选 ask 还是 allow？什么时候用 yolo？**
A: 推荐：默认 `ask`。当你在**可信项目**里做**可预期的批量改动**需要提速时，用 `acli rovodev run --yolo`（或会话内 `/yolo`）短暂开启；完成后退出重开回到非 yolo。

**Q: 切换模型后出现日志无法写入/写日志报错怎么办？**
A: 这是目前部分环境下的已知不稳定现象，常见触发方式是会话内使用 `/model` 切换后，日志文件句柄异常。
- **缓解 1（推荐）**：尽量不要在同一个会话里频繁切模型；需要切模型时，退出后重开。
- **缓解 2**：切换后**重启 CLI**，并用：`acli rovodev run --restore` 续接会话。
- **缓解 3**：确认日志目录可写（Windows 默认：`%USERPROFILE%\.rovodev\logs\rovodev.log`）。

**Q: 如何让重启后尽量不断档（恢复上次会话/工作区状态）？**
A:
- 启动时加：`acli rovodev run --restore`
- 如需启用（实验）工作区状态同步，在 `config.yml` 里设置：
  - `sessions.enableWorkspaceStateSync: true`

**Q: 模型选择上有什么稳定性建议？**
A: 经验建议（上游状态可能变化，仅供参考）：
- Gemini 通常相对稳定。
- Claude 偶发上游波动时，多数情况下可自动恢复/重试。
- GPT 偶发“上游拉闸/熔断”时，可能会出现几分钟不可用；建议稍等后重试，必要时重启 CLI 并 `--restore`。

**Q: 运行过程中出现 ripgrep/文件扫描超时（例如日志里看到 `ripgrep ... timed out`）怎么办？**
A: 这通常发生在把工作区放在非常大的目录（如用户主目录根、包含大量缓存/依赖的目录）时。
- 进入一个更小、更干净的项目目录再运行（例如只包含当前项目代码的目录）。
- 避免把整个 home 目录当作 workspace；必要时把大文件/依赖目录移出或加入忽略（如 `node_modules/`、大型构建输出）。

---

## 参考链接

- [Rovo Dev CLI 官方文档](https://support.atlassian.com/rovo/docs/use-rovo-dev-cli/)
- [CLI 命令参考](https://support.atlassian.com/rovo/docs/rovo-dev-cli-commands/)
- [配置项说明](https://support.atlassian.com/rovo/docs/manage-rovo-dev-cli-settings/)
- [Atlassian Homebrew Tap](https://github.com/atlassian/homebrew-acli)
- [API Token 管理](https://id.atlassian.com/manage-profile/security/api-tokens)