版本升级

Kestrel 还在 1.0 之前。这意味着：

• Schema 迁移在启动时自动执行。Atlas 在 _kestrel_migrations 表里追踪已应用的迁移；乱序或被手改过的迁移会触发 drift 检查，服务直接拒绝启动。（我们从不发布手改的迁移。）
• 大版本内（v0.x.y）任何 patch / minor 升级都安全。HTTP API、MCP 工具集、SDK envelope schema 都保持只增不减 —— 新字段可能出现，旧字段不会无声消失。
• 大版本跨越（v1.0.0 → v2.0.0）的 break change 都会列在 CHANGELOG.md 对应版本下。升级前读一下。

标准流程

# 1. 先备份。永远先备份。（见"备份"页面。）
kestrel backup /var/backups/before-upgrade-$(date +%F).tar.gz

# 2. 拉新镜像 / 替换二进制。
docker pull ghcr.io/wearzdk/kestrel:latest

# 3. 重建容器。迁移在启动时执行。
docker stop kestrel && docker rm kestrel
docker run -d --name kestrel \
  -p 8080:8080 \
  -v kestrel-data:/data \
  ghcr.io/wearzdk/kestrel:latest

如果启动时迁移报错，别慌、也别去删 _kestrel_migrations —— 用第 1 步的备份恢复，把服务端日志贴到 issue，先回退到上一个 tag。

锁定版本

生产环境建议固定到具体 tag（ghcr.io/wearzdk/kestrel:v0.1.0），不要用 :latest。:edge 是滚动跟随 main 分支的镜像 —— 适合试用未发布的修复，不适合生产。

SDK 升级

SDK 与服务端独立版本：

• JS SDK —— npm update kestrel-sdk（或在 package.json 里固定版本）。
• Python SDK —— pip install --upgrade kestrel-sdk。
• Go SDK —— go get -u github.com/wearzdk/kestrel/sdks/go。

服务端 0.x 接受任何 0.x SDK 的 envelope，反之亦然。Envelope 通过显式的 schema_version: 1 字段做版本协商；服务端遇到未知版本会拒绝，而不是当成 v1 强行解析。

静态二进制怎么升？

# 备份。
./kestrel backup /var/backups/before-upgrade-$(date +%F).tar.gz

# 替换二进制。
curl -sSL -o kestrel.tar.gz https://github.com/wearzdk/kestrel/releases/latest/download/kestrel_LATEST_linux_amd64.tar.gz
tar -xzf kestrel.tar.gz
mv kestrel /usr/local/bin/kestrel

# 重启服务。
systemctl restart kestrel

迁移逻辑一致 —— 新二进制启动时把迁移跑完。