更新守护者

更新守护者

自动更新Agent平台与所有已安装技能包，但更新前先预检、先快照，更新后跑健康检查，失败自动回滚。核心信条：更新可以自动，但回滚必须一键。

四大痛点与对策

---

三段式安全更新流程

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  预检干跑    │ ──→ │  快照+应用   │ ──→ │  健康检查    │
│ dry-run     │     │ snapshot    │     │ health      │
│ 兼容性检查   │     │ apply       │     │ fail→rollback│
└─────────────┘     └─────────────┘     └─────────────┘

第一段：预检干跑

# 1. 检查有哪些更新可用（不应用）
update-manager check --all --dry-run

# 2. 输出示例
# Platform: v2026.1.9 → v2026.1.10 (minor, safe)
# Skill prd: 2.0.3 → 2.0.4 (patch, safe)
# Skill browser: 1.2.0 → 2.0.0 (MAJOR, breaking changes detected!)
#   - Breaking: API renamed fetch() to request()
#   - Affected: 3 other skills depend on browser
# Skill nano: 3.1.0 → 3.1.2 (patch, safe)

# 3. 兼容性矩阵检查
update-manager check-conflicts
# Conflict: skill-A requires lib-x>=2.0, skill-B requires lib-x<2.0
# Recommendation: skip skill-A update or pin lib-x to 1.9

第二段：快照+应用

# 1. 快照当前状态
update-manager snapshot --output ~/.update-snapshots/$(date +%Y%m%d)

# 2. 快照内容
# - platform版本号
# - 所有技能版本号
# - 配置文件备份（~/.config/agent/）
# - 依赖锁文件（package-lock.json / requirements.txt）

# 3. 应用安全更新（跳过breaking change）
update-manager apply --safe-only  # 只应用patch/minor
# 或指定强制
update-manager apply --include browser --force

第三段：健康检查

# 1. 更新后跑健康检查
update-manager health-check

# 2. 检查项
# - 平台启动正常？
# - 所有技能可加载？
# - 关键工作流能跑？
# - 配置文件无diff异常？

# 3. 失败则自动回滚
update-manager health-check --auto-rollback

---

版本快照与回滚

快照结构

snapshot:
  date: "2026-07-18"
  timestamp: "2026-07-18T04:00:00Z"
  platform:
    name: agent-platform
    version: "2026.1.9"
    install_method: npm  # npm|pnpm|bun|source
  skills:
    - name: prd
      version: "2.0.3"
      path: ~/.skills/prd/
    - name: browser
      version: "1.2.0"
      path: ~/.skills/browser/
  config_files:
    - path: ~/.config/agent/config.json
      hash: sha256:abc123...
    - path: ~/.config/agent/cron.json
      hash: sha256:def456...
  dependencies:
    - name: lib-x
      version: "1.9.0"
      required_by: [skill-A, skill-B]

一键回滚

# 回滚到最近快照
update-manager rollback --latest

# 回滚到指定快照
update-manager rollback --snapshot ~/.update-snapshots/20260718

# 仅回滚指定技能
update-manager rollback --skill browser --to 1.2.0

回滚流程

1. 停止平台服务
2. 恢复平台二进制/包到快照版本
3. 恢复所有技能到快照版本
4. 恢复配置文件（用hash校验完整性）
5. 恢复依赖锁文件
6. 重启平台服务
7. 跑健康检查确认恢复

---

兼容性矩阵

依赖冲突检测

# 检测规则
conflict_detection:
  - type: version_range
    # 技能A要lib-x>=2.0，技能B要lib-x<2.0 → 冲突
    check: "any two skills require non-overlapping version range of same dep"
    action: skip_update + alert

  - type: breaking_change
    # 技能升级到MAJOR版本，检查其他技能是否依赖旧API
    check: "new major version has breaking API changes"
    action: check_dependents + alert

  - type: peer_dependency
    # 技能声明peerDep，检查宿主版本是否匹配
    check: "skill peerDep range vs platform version"
    action: skip + alert

兼容性矩阵示例

冲突解决：skill-A与skill-B不能共存于同一lib-x版本。方案：二选一保留，或隔离运行环境。

---

智能调度

业务低峰期检测

schedule:
  strategy: off_peak
  detection:
    - 检查历史工作流执行日志，找运行最少的时段
    - 默认低峰：凌晨2:00-5:00（按业务调整）
  fallback:
    # 找不到低峰则用固定时间
    cron: "0 4 * * *"
    tz: "Asia/Shanghai"
  blackout:
    # 业务高峰期禁止更新
    periods:
      - "每周一9:00-12:00"  # 周报高峰
      - "每月1日0:00-6:00"  # 月结高峰
      - "节假日全天"

调度示例

# 自动找低峰期
update-manager schedule --auto

# 输出
# Detected off-peak window: 03:00-05:00 daily
# Scheduling updates at 03:30 Asia/Shanghai
# Blackout periods: Mon 9-12, month-start 0-6

# 手动指定
update-manager schedule --cron "0 3 * * *" --tz Asia/Shanghai

---

配置备份与校验

更新前备份

# 备份配置目录
update-manager backup-config --output ~/.config-backups/$(date +%Y%m%d)

# 备份内容
# - ~/.config/agent/*.json
# - ~/.config/agent/*.yaml
# - ~/.skills/*/config.*
# - 环境变量快照（仅key名，不含value）

更新后校验

# diff配置文件，发现意外变更
update-manager diff-config --before ~/.config-backups/20260718 --after ~/.config/agent/

# 输出
# config.json: 2 keys changed
#   - cron.enabled: true → false  (WARNING: unexpected)
#   - log.level: info → debug
# cron.json: no changes

规则：任何配置项意外变更（非更新日志声明的）都告警。

---

健康检查

检查项

health_check:
  - id: platform_start
    name: "平台启动"
    check: "agent --version 能正常输出"
    on_fail: rollback

  - id: skills_loadable
    name: "技能可加载"
    check: "遍历~/.skills/，每个技能能正常加载"
    on_fail: rollback_affected

  - id: critical_workflow
    name: "关键工作流可跑"
    check: "跑dry-run测试3个最关键工作流"
    on_fail: rollback

  - id: config_valid
    name: "配置文件有效"
    check: "JSON/YAML语法校验 + schema校验"
    on_fail: restore_config

  - id: deps_consistent
    name: "依赖一致性"
    check: "无版本冲突"
    on_fail: alert

失败自动回滚

update-manager health-check --auto-rollback --notify slack

---

更新摘要格式

更新完成后收到消息：

更新守护者报告 2026-07-18

平台: v2026.1.9 → v2026.1.10 (minor, 安全)

技能已更新 (3):
- prd: 2.0.3 → 2.0.4
- browser: 1.2.0 → 1.2.1
- nano: 3.1.0 → 3.1.2

技能跳过 (1):
- browser-major: 1.2.0 → 2.0.0 (MAJOR, 检测到breaking change, 需人工确认)

技能已最新 (5):
gemini, sag, things, himalaya, peekaboo

健康检查: 全部通过
快照: ~/.update-snapshots/20260718 (可回滚)

---

手动命令

# 检查更新不应用
update-manager check --all --dry-run

# 查看当前版本
update-manager list

# 查看平台版本
agent --version

# 手动应用指定技能更新
update-manager apply --skill prd

# 强制应用MAJOR更新（需确认）
update-manager apply --skill browser --force --confirm-breaking

# 回滚
update-manager rollback --latest

# 查看快照列表
update-manager snapshots --list

---

边界情况与陷阱

• 更新中途断网：可能半更新状态。用事务式更新（要么全成功要么全回滚）。
• 配置文件被改：更新可能覆盖用户自定义配置。更新前必备份，更新后diff校验。
• 依赖锁文件丢失：导致依赖版本漂移。锁文件纳入快照。
• 磁盘空间不足：更新前检查可用空间。
• 权限问题：确保更新用户对技能目录有写权限。
• MAJOR版本跳变：从v1直接跳v3可能漏掉v2的迁移步骤。逐版本升级。

---

FAQ

Q：更新后平台起不来了怎么办？ A：自动健康检查会检测到并触发回滚。手动回滚：update-manager rollback --latest，恢复到更新前快照。

Q：怎么知道哪个技能有breaking change？ A：预检干跑阶段会输出。MAJOR版本号变更默认跳过，需手动--force --confirm-breaking。

Q：两个技能依赖同一库的不同版本怎么办？ A：兼容性矩阵会检测到冲突。方案：二选一保留，或为冲突技能隔离运行环境（容器/虚拟环境）。

Q：更新撞上业务高峰怎么办？ A：智能调度会自动检测低峰期（默认凌晨2-5点）。可配blackout时段禁止更新。

Q：配置文件被更新覆盖了怎么办？ A：更新前自动备份到~/.config-backups/。更新后diff校验，意外变更会告警。可手动恢复。

---

故障排查

---

依赖说明

运行环境

• Agent平台：支持SKILL.md的任意AI Agent（Claude Code / Cursor / Codex / Gemini CLI等）
• 操作系统：Windows / macOS / Linux
• 技能包管理器：update-manager CLI（或平台自带等价命令）

第三方依赖

API Key 配置

• 本skill基于Markdown指令，无需额外API Key
• 涉及外部技能源（如私有registry）时，通过环境变量配置访问Token

可用性分类

• 分类：MD+EXEC（Markdown指令 + CLI执行）
• 说明：通过自然语言指令驱动Agent调用update-manager完成三段式安全更新