# 维护说明

这个目录是 GL Robotics 网站仓库内维护的 AI 开发环境安装器源码。

## 目录职责

```text
tools/ai-dev-installer/          # 安装器源码和维护文档
public/ai-dev/                   # Vercel 静态分发文件
```

用户访问：

```text
https://gl-robotics.com/ai-dev/install.ps1
https://gl-robotics.com/ai-dev/install.sh
https://gl-robotics.com/ai-dev/ai-dev-installer-mvp.zip
```

用户安装命令：

```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
```

## 更新流程

1. 修改 `tools/ai-dev-installer/` 下的脚本或文档。
2. 运行 PowerShell 语法检查：

```powershell
$files = @(
  "tools\ai-dev-installer\scripts\install.ps1",
  "tools\ai-dev-installer\scripts\prepare-offline-package.ps1",
  "tools\ai-dev-installer\bootstrap\install.ps1"
)
foreach ($p in $files) {
  $tokens = $null
  $errors = $null
  $null = [System.Management.Automation.Language.Parser]::ParseFile($p, [ref]$tokens, [ref]$errors)
  if ($errors.Count) {
    $errors
    exit 1
  }
}
```

3. 重新生成分发 zip：

```powershell
Compress-Archive `
  -Path .\tools\ai-dev-installer `
  -DestinationPath .\public\ai-dev\ai-dev-installer-mvp.zip `
  -Force
```

4. 同步 bootstrap 脚本：

```powershell
Copy-Item .\tools\ai-dev-installer\bootstrap\install.ps1 .\public\ai-dev\install.ps1 -Force
Copy-Item .\tools\ai-dev-installer\bootstrap\install.sh .\public\ai-dev\install.sh -Force
```

5. 生成校验值：

```powershell
Get-FileHash .\public\ai-dev\install.ps1 -Algorithm SHA256
Get-FileHash .\public\ai-dev\install.sh -Algorithm SHA256
Get-FileHash .\public\ai-dev\ai-dev-installer-mvp.zip -Algorithm SHA256
```

6. 提交并部署到 Vercel。

## 不要提交的内容

以下内容默认被 `tools/ai-dev-installer/.gitignore` 忽略：

- 安装日志
- 本地 `install-config.json`
- Node.js MSI
- Claude Code `.tgz`
- Claudian 的大体积 release 文件

如果后续要公开完整离线包，建议把大文件放对象存储或 Release，不建议长期放在 Vercel 网站仓库。

## 配置覆盖策略

安装器必须遵守以下规则：

- 检测到已有 Claude Code 配置时，先询问用户是否切换到 DeepSeek。
- 写入 `~/.claude/settings.json` 或 `%USERPROFILE%\.claude\settings.json` 前必须备份。
- 写入 vault 内 `.claudian/claudian-settings.json` 和 `.claude/settings.local.json` 前必须备份。
- 修改 JSON 时尽量合并字段，不重写整个文件。
- Windows PowerShell 5.1 的 `Set-Content -Encoding UTF8` 会写入 BOM；写给 Obsidian/Claudian/Claude 的 JSON 必须用无 BOM UTF-8，否则插件内部 `JSON.parse` 可能加载失败。
- 默认不把 API Key 写入 Obsidian vault。
- 写入 `.obsidian/community-plugins.json` 时，如果当前列表为空但插件目录存在多个 manifest，必须先从最近非空备份或 manifest 恢复，不能把 `[]` 当作正常状态继续覆盖。
- 安装 Claudian 前必须检查 Obsidian 兼容性，不能只看 `manifest.json` 里的 `minAppVersion`。如果 `main.js` 包含 `node:sqlite`，说明插件依赖较新的 Obsidian/Electron/Node 外壳，默认要求主程序外壳不低于 `claudianNodeSqliteMinObsidianShellVersion`。
- Ghelper 功能不要强写 Chrome 企业策略，除非后续明确做“企业管控模式”。
- Ghelper 功能依赖 Chrome。没有 Chrome 时可以自动安装 Chrome，但不要默认提交大体积 Chrome 安装包。
- Clash Verge 功能只负责安装客户端，不自动导入用户订阅、不强制打开系统代理。
- Chrome、Ghelper、Clash Verge 都必须先检测是否已安装；已安装时跳过，不覆盖重装。
- 第三方软件默认优先使用官方源；国内下载失败后才使用 GL Robotics 中转，避免授权边界不清。

## 当前功能菜单

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

新增功能时优先保持这个模式：菜单名面向小白用户，详细诊断写入日志文件，终端只显示关键进度和下一步。
