# GL Robotics AI 一键安装工具设计

## 目标

面向 Windows、Ubuntu、macOS 用户，提供一个类似“鱼香 ROS 一键安装”的原型安装器，降低常用 AI 工具链的安装和配置门槛。

当前功能：

```text
1. Obsidian 接入 DeepSeek
2. 安装 Chrome Ghelper
3. 安装 Clash Verge
```

后续功能继续按菜单扩展。

第一版不做图形界面。Windows 采用 `install.bat + PowerShell`，Ubuntu/macOS 采用 `install.sh + bash`。原因是可维护、易修改、方便定位错误，后续可以在这个脚本基础上封装成图形安装器。

## 项目结构

```text
ai-dev-installer/
  install.bat                         # 用户双击入口
  install.sh                          # Ubuntu/macOS 本地入口
  scripts/
    install.ps1                       # 主安装脚本
    install.sh                        # Ubuntu/macOS 主安装脚本
    prepare-offline-package.ps1       # 维护者用：准备离线包
  bootstrap/
    install.ps1                       # 远程一键安装入口脚本
    install.sh                        # Ubuntu/macOS 远程一键安装入口脚本
  config/
    install-config.example.json       # 配置模板
    install-config.json               # 首次运行自动生成，可填中转地址
  packages/
    node/                             # Node.js MSI 离线包
    claude-code/                      # Claude Code npm tgz 离线包
    chrome/                           # Chrome 安装包，可选
    ghelper/                          # Ghelper zip/crx 离线包
    clash-verge/                      # Clash Verge 安装包
    obsidian-plugins/claudian/        # Claudian 兼容版插件文件
  logs/                               # 安装日志
```

## 当前功能

### Obsidian 接入 DeepSeek

1. 环境检测
   - Windows 检测 PowerShell。
   - Ubuntu/macOS 检测 bash、python3、curl/wget、unzip。
   - 检测 Node.js 和 npm。
   - 检测 Claude Code CLI。
   - 检测 Obsidian vault。

2. Claude Code CLI 安装
   - 优先使用 `packages/claude-code/*.tgz`。
   - 如果缺少离线包，则读取 `config/install-config.json` 的 `claudeCodeMirrorUrl`。
   - 如果没有配置中转地址且不是离线模式，则尝试 npm 官方包安装。

3. Node.js 安装
   - 如果用户电脑没有 Node.js，则优先使用 `packages/node/*.msi`。
   - 如果缺少 MSI，则尝试从 `nodeMirrorUrl` 下载。
   - 安装后刷新当前进程 PATH。

4. DeepSeek 配置
   - 用户交互输入 DeepSeek API Key。
   - 默认写入 Windows 用户环境变量：
     - `ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic`
     - `ANTHROPIC_AUTH_TOKEN=<用户输入的 key>`
     - `ANTHROPIC_MODEL=deepseek-v4-pro[1m]`
   - 默认写入 Claude Code 用户级配置：
     - Windows: `%USERPROFILE%\.claude\settings.json`
     - Ubuntu/macOS: `~/.claude/settings.json`
   - 默认不把 API Key 写入 Obsidian vault，避免知识库同步造成泄漏。
   - 用户明确选择后，才把 API Key 写进 vault 内配置。

5. Obsidian Claudian 插件安装
   - 如果 Obsidian 正在运行，先自动关闭，避免 Obsidian 覆盖安装器写入的配置。
   - 默认使用 Claudian `2.0.0` 兼容版，插件 ID 为 `claudian`。
   - 最新上游版本可能使用 `realclaudian`，但部分旧 Obsidian 桌面外壳会加载失败。
   - 把 `main.js`、`manifest.json`、`styles.css` 复制到：
     - `<vault>/.obsidian/plugins/claudian/`
   - 自动启用插件，更新：
     - `<vault>/.obsidian/community-plugins.json`
   - 写入：
     - `<vault>/.claudian/claudian-settings.json`
     - `<vault>/.claude/settings.local.json`

6. 日志和诊断
   - 所有关键步骤写入 `logs/install-日期.log`。
   - 失败时输出明确原因：
     - Node MSI 缺失
     - Claude Code tgz 缺失
     - Claudian 插件文件缺失
     - vault 路径不存在
     - npm/claude 命令不可用
     - DeepSeek 地址连通性测试失败

### 安装 Chrome Ghelper

1. 先检测 Chrome 是否已安装。
2. 如果没有 Chrome，优先使用 `packages/chrome/` 下的安装包。
3. 没有 Chrome 离线包时，读取 `chromeWindowsUrl`、`chromeMacosUrl`、`chromeLinuxDebUrl` 下载。
4. Chrome 安装完成后，优先使用 `packages/ghelper/` 下的 zip 或 crx。
5. 没有 Ghelper 离线包时，先读取 `ghelperDownloadUrl` 使用官方源下载，失败后读取 `ghelperMirrorDownloadUrl` 使用 GL Robotics 中转。
6. 自动解压到 `downloads/ghelper/`。
7. 自动打开安装目录和 `chrome://extensions/`。
8. 提示用户打开开发者模式并拖入 crx，或从 Chrome 商店安装。

如果检测到 Chrome 已安装，就不重装 Chrome。如果检测到 Ghelper 扩展目录已经存在，就跳过 Ghelper 安装。

Chrome 对第三方扩展有安全限制，普通脚本不应该绕过用户确认直接强制启用扩展。后续如果要做企业/实验室统一部署，可以单独增加“Chrome 企业策略安装”模式。

### 安装 Clash Verge

1. 优先使用 `packages/clash-verge/` 下的安装包。
2. 没有离线包时，通过 Clash Verge Rev 官方 GitHub Release API 获取最新版安装包。
3. 官方源下载失败时，读取配置中的 GL Robotics 中转地址兜底。
4. Windows 选择 `x64-setup.exe` 或 `arm64-setup.exe`。
5. macOS 选择 `x64.dmg` 或 `aarch64.dmg`。
6. Ubuntu/Linux 优先选择 `amd64.deb` 或 `arm64.deb`。

该功能只安装 Clash Verge 客户端，不自动导入订阅、不改系统代理，避免误改用户网络环境。

如果检测到 Clash Verge 已安装，就直接跳过，不覆盖当前版本和用户配置。

## 安装流程

```text
用户双击 install.bat
  |
  v
创建/读取 config/install-config.json
  |
  v
输入 DeepSeek API Key
  |
  v
检测/安装 Node.js
  |
  v
检测/安装 Claude Code CLI
  |
  v
设置 DeepSeek 环境变量
  |
  v
写入 Claude Code 用户级配置
  |
  v
选择 Obsidian vault
  |
  v
安装并启用 Claudian
  |
  v
写入配置和诊断日志
  |
  v
提示用户重启 Obsidian
```

## 类鱼香 ROS 的远程入口

Windows 不使用 Linux 的 `. fishros` 语法。对应的一键命令是：

```powershell
irm https://gl-robotics.com/ai-dev/install.ps1 | iex
```

Ubuntu/macOS 对应的一键命令是：

```bash
curl -fsSL https://gl-robotics.com/ai-dev/install.sh | bash
```

或者：

```bash
wget -O- https://gl-robotics.com/ai-dev/install.sh | bash
```

这里的 `install.ps1` 是一个很小的 bootstrap 脚本，负责：

1. 下载完整 `ai-dev-installer-mvp.zip`。
2. 解压到 `%LOCALAPPDATA%\AI-Dev-Installer\current`。
3. 执行完整包里的 `scripts/install.ps1`。

完整发布说明见 `PUBLISH.zh-CN.md`。

## 离线包和中转下载策略

维护者在可访问外网的电脑上运行：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\prepare-offline-package.ps1
```

该脚本会下载：

- Claude Code npm tgz 包。
- Node.js x64 MSI。
- Claudian 最新 release 的 `main.js`、`manifest.json`、`styles.css`。
- Ghelper zip 包。
- Clash Verge Windows/macOS/Linux 常用安装包。

然后可以把整个目录上传到网盘、对象存储、GitHub Release 或内网服务器。

如果不想完整打包，也可以只配置中转地址：

```json
{
  "claudeCodeMirrorUrl": "https://your-mirror/claude-code.tgz",
  "nodeMirrorUrl": "https://your-mirror/node-v22-x64.msi",
  "claudianMirrorBaseUrl": "https://your-mirror/claudian-compatible",
  "chromeWindowsUrl": "https://your-mirror/chrome/chrome_installer.exe",
  "ghelperDownloadUrl": "https://ghelper.app/download/Ghelper-v2.8.18.zip",
  "ghelperMirrorDownloadUrl": "https://your-mirror/ghelper/Ghelper-v2.8.18.zip",
  "clashVergeWindowsX64Url": "https://your-mirror/clash-verge/Clash.Verge_2.5.2_x64-setup.exe"
}
```

其中 `claudianMirrorBaseUrl` 目录下应包含：

```text
main.js
manifest.json
styles.css
```

## 安全边界

离线安装包只能解决“安装阶段下载困难”，不能解决“运行阶段模型访问”。运行阶段需要 DeepSeek API Key 或其他 Anthropic 兼容服务。

API Key 默认写入 Windows 用户环境变量，不默认写入 vault。原因是 Obsidian vault 经常会通过 iCloud、OneDrive、坚果云、Git 等工具同步，直接写入 API Key 有泄漏风险。

如果检测到用户已经配置过与 DeepSeek 冲突的 Claude Code 或 Anthropic 相关环境变量，安装器会先询问是否切换到 DeepSeek。用户选择否时，不修改全局 Claude Code 配置。已经是 DeepSeek 的配置会静默更新，不重复询问。

安装器写入 JSON 配置前会创建带时间戳的备份，并尽量只合并必要字段，避免覆盖用户原有的无关配置。

## 下一版建议

1. 增加图形界面。
2. 支持 Obsidian 本体安装。
3. 支持多模型后端：DeepSeek、Kimi、OpenRouter、自建代理。
4. 支持卸载和修复模式。
5. 支持校验包 hash，防止中转包被篡改。
6. 支持生成完整离线 zip 和版本清单。
