更新

介绍将 MoAI-ADK 保持在最新版本的方法。仅用 moai update 一条命令即可一并更新二进制与模板,而用户创建的自定义资产会自动保留。

不带标志运行时会同时更新二进制与模板 —— 这是默认行为。

moai update

flowchart TD
    A["执行 moai update"] --> B["Stage 1: 检查包版本"]
    B --> C{"最新版本?"}
    C -->|"是"| D["Stage 2: 比较配置版本"]
    C -->|"否"| E["已是最新状态"]
    D --> F{"配置格式变更?"}
    F -->|"是"| G["配置迁移(备份后)"]
    F -->|"否"| H["保留配置"]
    G --> I["Stage 3: 同步模板"]
    H --> I
    I --> J["完成报告"]

比较当前安装的版本与 GitHub Releases 上的最新版本。

# 确认当前版本
moai --version

# 仅确认可用更新(不实际更新)
moai update --check

moai update 的二进制下载 无法绕过校验和验证。若 release 的 checksums.txt 下载失败或解析失败,则会 中止(abort) 更新流程 —— 不会尝试下载二进制。

checksums.txt 下载以指数退避尝试 3 次 retry:

所有 retry 都失败时,会输出如下消息:

error: checksum unavailable: persistent retry failure after 3 attempts

不存在 --skip-checksum 之类的绕过选项 (CWE-345 有意的策略)。

1. 确认网络连接:
   bash 复制

   curl -I https://github.com/modu-ai/moai-adk/releases/latest

2. 确认 Proxy / firewall —— 是否允许 GitHub release asset 域名(github.com, objects.githubusercontent.com)
3. 可能是临时性 GitHub CDN 故障 —— 稍后重试
4. 手动安装二进制 (永久阻断时):
   bash 复制

   curl -fsSL https://adk.mo.ai.kr/install.sh | bash

   手动安装时建议另行确认 GitHub Release 的 checksums.txt。

详细的威胁模型请参阅安全笔记 — CWE-345。

检查配置文件的格式与兼容性。格式发生变更时会自动备份后迁移。

检查文件:

• .moai/config/sections/ 下的 YAML 文件

信息

配置迁移前始终会备份 .moai/config/ 目录。

将项目模板与默认文件同步到最新版本。用户修改过的文件会被保留,与新版本冲突时会备份后合并。

graph TD
    A["同步模板"] --> B["SKILL.md 模板"]
    A --> C["智能体模板"]
    A --> D["规则文件"]
    A --> E["配置默认值"]

    B --> F{"用户变更?"}
    C --> F
    D --> F
    E --> F

    F -->|"否"| G["自动更新"]
    F -->|"是"| H["备份后 3-way 合并"]

    G --> I["同步完成"]
    H --> I

只更新二进制而不同步模板:

moai update --binary

moai update --version <tag> 通过与默认更新相同的校验和验证下载路径,安装特定的 GitHub 发布标签(stable、rc 或旧版本)。一个标志覆盖三种用途:固定到稳定的 stable 版本、切换到 rc 进行测试,或在回归后回滚到旧版本。

# 固定到 stable 发布
moai update --version v3.0.0

# 前导 "v" 可省略
moai update --version 3.0.0

# 试用 rc
moai update --version v3.1.0-rc1

# 回滚到旧版本
moai update --version v2.14.0

信息

该标志仅使用 api.github.com 主机的 https,并按发布的公开校验和验证下载的二进制文件 —— 没有 --skip-checksum / --insecure 旁路。当没有匹配平台的二进制资产或校验和不一致时,以非零退出码结束且不改动文件系统。

--version 与部分标志互斥,与其余标志可并用:

当所请求标签比运行版本旧时,在交互式终端会弹出确认提示。传入 --yes(或使用非 TTY stdin,如 CI 中)可跳过提示直接进行。

默认的 moai update(不带 –version)获取 GitHub 的 /releases/latest,它会自动排除预发布版本 —— 因此 rc 和预发布标签在默认流程中从不暴露。--version <tag> 是显式安装 rc 或特定旧标签的唯一途径。

只同步模板而不更新二进制:

moai update --templates-only

重新运行设置向导来更改项目配置(不执行模板同步):

moai update -c
# 或
moai update --config

不做实际变更,预先确认计划的归档与安装操作:

moai update --dry-run

自动批准所有确认:

moai update --yes

moai --version

moai doctor

moai --help

MoAI-ADK 更新时,CLAUDE.md 与 settings.json 会同步到新版本。请将个人的修改内容保存到单独的文件。

信息

设置优先级: Local > Project > User > Enterprise
settings.local.json 会覆盖项目设置。

MoAI-ADK 仅在以下文件夹中管理文件:

.claude/
├── agents/
│   ├── moai/                # MoAI-ADK 智能体(更新对象)
│   └── harness/             # 用户 harness 智能体(排除更新,保留)
│
├── hooks/
│   └── moai/                # MoAI-ADK 钩子脚本(更新对象)
│
├── skills/
│   ├── moai-*               # MoAI-ADK 技能(moai- 前缀,更新对象)
│   └── hns-*                # 用户生成的技能(排除更新,保留)
│
└── rules/
    └── moai/                # 规则文件(moai 管理)

注意

重要: 带 moai- 前缀的技能由 MoAI-ADK 管理,更新时会被覆盖。自己创建的技能请使用 hns- 前缀(用户所有的命名空间),智能体请使用 .claude/agents/harness/ 目录。

更新后出现问题时,可回滚到之前的版本:

# 进程内回滚到特定版本(推荐)
moai update --version <release-tag>

# 引导路径(moai 安装前):使用安装脚本
curl -fsSL https://adk.mo.ai.kr/install.sh | bash -s -- --version <release-tag>

# 从备份恢复配置
cp -r .moai/config.bak .moai/config

注意

回滚前请提交当前工作。

# 确认网络
curl -I https://github.com/modu-ai/moai-adk/releases/latest

# 手动重新安装
curl -fsSL https://adk.mo.ai.kr/install.sh | bash

# 从备份恢复
cp -r .moai/config.bak .moai/config

# 验证配置
moai doctor

用户修改过的模板文件会自动备份后 3-way 合并。发生冲突时,请用 --verbose 确认详细警告:

moai update --verbose

要强制覆盖请使用 --force(既有的用户变更会备份到 .moai/archive/):

moai update --force

1. 确认变更日志 —— 学习新功能
2. 核心概念 —— 掌握新的智能体与功能
3. 快速开始 —— 将新功能应用到项目