跳到主要内容

更新与卸载

更新​

Git 安装方式​

使用单条命令更新至最新版本：

aigenlabs update

此命令会从 main 拉取最新代码、更新依赖项，并提示你配置自上次更新以来新增的选项。

pip 安装方式​

PyPI 发布版本跟踪带标签的版本（主版本和次版本发布），而非 main 上的每次提交。检查更新并升级：

aigenlabs update --check    # 查看 PyPI 上是否有更新的版本
aigenlabs update            # 执行 pip install --upgrade aigenlabs-agent

或手动执行：

pip install --upgrade aigenlabs-agent    # 或：uv pip install --upgrade aigenlabs-agent
提示

aigenlabs update 会自动检测新的配置选项并提示你添加。如果跳过了该提示，可手动运行 aigenlabs config check 查看缺失的选项，再运行 aigenlabs config migrate 以交互方式添加。

更新过程（Git 安装方式）​

运行 aigenlabs update 时，将依次执行以下步骤：

  1. 配对数据快照 — 保存一份轻量级的更新前状态快照（涵盖 ~/.aigenlabs/pairing/、飞书评论规则及其他运行时修改的状态文件）。可通过 快照与回滚 中描述的快照恢复流程进行恢复，或从 AigenLabs 写入 ~/.aigenlabs/ 目录旁的最新快速快照 zip 文件中提取。
  2. Git pull — 从 main 分支拉取最新代码并更新子模块
  3. 依赖安装 — 运行 uv pip install -e ".[all]" 以获取新增或变更的依赖项
  4. 配置迁移 — 检测自当前版本以来新增的配置选项并提示设置
  5. Gateway 自动重启 — 更新完成后刷新正在运行的 gateway，使新代码立即生效。由服务管理的 gateway（Linux 上的 systemd、macOS 上的 launchd）通过服务管理器重启；手动启动的 gateway 在 AigenLabs 能将运行中的 PID 映射回某个 profile 时会自动重新启动。

仅预览：aigenlabs update --check​

想在拉取前确认是否有更新？运行 aigenlabs update --check — 对于 Git 安装方式，它会获取并与 origin/main 比较提交；对于 pip 安装方式，它会查询 PyPI 上的最新版本。不修改任何文件，不重启 gateway。适合在以"是否有更新"为条件的脚本和 cron 任务中使用。

完整更新前备份：--backup​

对于高价值 profile（生产环境 gateway、团队共享安装），可选择在拉取前对 AIGENLABS_HOME（配置、认证、会话、技能、配对数据）进行完整备份：

aigenlabs update --backup

或将其设为每次运行的默认行为：

# ~/.aigenlabs/config.yaml
updates:
  pre_update_backup: true

--backup 在早期版本中是始终开启的行为，但在大型 home 目录上会给每次更新增加数分钟时间，因此现已改为按需启用。上述轻量级配对数据快照仍会无条件执行。

Windows：另一个 aigenlabs.exe 正在运行​

在 Windows 上，如果 aigenlabs update 检测到另一个 aigenlabs.exe 进程持有 venv 入口点可执行文件的句柄，它将拒绝运行 — 最常见的情况是 AigenLabs Desktop 应用启动的后端进程、另一个终端中打开的 aigenlabs REPL，或正在运行的 gateway：

$ aigenlabs update
✗ Another aigenlabs.exe is running:
    PID 12345  aigenlabs.exe

  Updating now would fail to overwrite ...\venv\Scripts\aigenlabs.exe because
  Windows blocks REPLACE on a running executable.

  Close AigenLabs Desktop, exit any open `aigenlabs` REPLs, and
  stop the gateway (`aigenlabs gateway stop`) before retrying.
  Override with `aigenlabs update --force` if you've already
  confirmed those processes will not write to the venv.

关闭列出的进程后重试。如果你确定并发进程不会造成干扰（极少见 — 通常仅在杀毒软件 shim 被误判时有用），可传入 --force 跳过检查。此时更新程序仍会以指数退避方式重试 .exe 重命名操作，对于顽固的文件锁，会通过 MoveFileEx(MOVEFILE_DELAY_UNTIL_REBOOT) 将替换操作安排在下次重启时执行，以确保更新能够完成。

预期输出如下：

$ aigenlabs update
Updating AigenLabs Agent...
📥 Pulling latest code...
Already up to date.  (or: Updating abc1234..def5678)
📦 Updating dependencies...
✅ Dependencies updated
🔍 Checking for new config options...
✅ Config is up to date  (or: Found 2 new options — running migration...)
🔄 Restarting gateways...
✅ Gateway restarted
✅ AigenLabs Agent updated successfully!

更新后建议的验证步骤​

aigenlabs update 处理主要的更新流程，但快速验证可确认一切正常落地：

  1. git status --short — 若工作树出现意外的脏状态，请在继续前检查
  2. aigenlabs doctor — 检查配置、依赖项和服务健康状态
  3. aigenlabs --version — 确认版本已按预期更新
  4. 如果使用 gateway：aigenlabs gateway status
  5. 如果 doctor 报告 npm audit 问题：在标记的目录中运行 npm audit fix
更新后工作树出现脏状态

如果 aigenlabs update 后 git status --short 显示意外变更，请在继续前停下来检查。这通常意味着本地修改被重新应用到了更新后的代码之上，或依赖步骤刷新了锁文件。

终端在更新中途断开连接​

aigenlabs update 针对意外终端断开进行了保护：

  • 更新会忽略 SIGHUP，因此关闭 SSH 会话或终端窗口不再会在安装中途终止它。pip 和 git 子进程继承此保护，因此 Python 环境不会因连接断开而处于半安装状态。
  • 更新运行期间，所有输出会同步镜像到 ~/.aigenlabs/logs/update.log。如果终端消失，重新连接后检查日志，确认更新是否完成以及 gateway 重启是否成功：
tail -f ~/.aigenlabs/logs/update.log
  • Ctrl-C（SIGINT）和系统关机（SIGTERM）仍会被响应 — 这些是主动取消操作，而非意外中断。

你不再需要将 aigenlabs update 包裹在 screen 或 tmux 中来应对终端断开。

查看当前版本​

aigenlabs version

与 GitHub releases 页面 上的最新版本进行比较。

从消息平台更新​

你也可以直接从 Telegram、Discord、Slack、WhatsApp 或 Teams 发送以下命令进行更新：

/update

此命令会拉取最新代码、更新依赖项并重启正在运行的 gateway。Bot 在重启期间会短暂下线（通常为 5–15 秒），之后恢复服务。

手动更新​

如果你是手动安装的（未使用快速安装脚本）：

cd /path/to/aigenlabs-agent
export VIRTUAL_ENV="$(pwd)/venv"

# Pull latest code
git pull origin main

# Reinstall (picks up new dependencies)
uv pip install -e ".[all]"

# Check for new config options
aigenlabs config check
aigenlabs config migrate   # Interactively add any missing options

回滚说明​

如果更新引入了问题，可以回滚到之前的版本：

cd /path/to/aigenlabs-agent

# List recent versions
git log --oneline -10

# Roll back to a specific commit
git checkout <commit-hash>
uv pip install -e ".[all]"

# Restart the gateway if running
aigenlabs gateway restart

回滚到特定发布标签：

git checkout v0.6.0
uv pip install -e ".[all]"
注意

如果新增了配置选项，回滚可能导致配置不兼容。回滚后运行 aigenlabs config check，如果遇到错误，请从 config.yaml 中删除无法识别的选项。

Nix 用户注意事项​

如果你通过 Nix flake 安装，更新由 Nix 包管理器负责：

# Update the flake input
nix flake update aigenlabs-agent

# Or rebuild with the latest
nix profile upgrade aigenlabs-agent

Nix 安装是不可变的 — 回滚由 Nix 的 generation 系统处理：

nix profile rollback

详情参见 Nix 安装。

卸载​

Git 安装方式​

aigenlabs uninstall

卸载程序会提供选项，让你保留配置文件（~/.aigenlabs/）以便将来重新安装。

pip 安装方式​

pip uninstall aigenlabs-agent
rm -rf ~/.aigenlabs            # 可选 — 如计划重新安装则保留

手动卸载​

rm -f ~/.local/bin/aigenlabs
rm -rf /path/to/aigenlabs-agent
rm -rf ~/.aigenlabs            # 可选 — 如计划重新安装则保留
信息

如果你将 gateway 安装为系统服务，请先停止并禁用它：

aigenlabs gateway stop
# Linux: systemctl --user disable aigenlabs-gateway
# macOS: launchctl remove ai.aigenlabs.gateway