Magic Cloud 文档

主题

安装 ​

整套工具以 magic-skills 合集一行装到位：一条命令装好 magic-stack 引擎与 magic-bugfix 技能；开发工作台（magic-console） 在 magic-stack 装好后再装。

平台主推 Windows + Git Bash / MSYS2；同样支持 Linux / macOS。所有命令在 bash（Git Bash）里执行，不要用 CMD / PowerShell。

一行装（装整套技能） ​

合集从内网 Nexus 发布，安装器会自动探测「内网优先、外网兜底」。

外网（任意机器）

bash
curl -fsSL http://maven.vv.yunku.live/repository/raw-releases/magic-skills/latest/install-bootstrap.sh | bash

内网（能直连 172.16.2.100，更快）

bash
curl -fsSL --noproxy '*' http://172.16.2.100:8081/repository/raw-releases/magic-skills/latest/install-bootstrap.sh | bash

--noproxy '*' 用于绕开本机 socks 代理（all_proxy），否则裸 curl 会被代理劫持、连不上内网。

拉取的永远是 latest（当前 0.2.12，始终以 latest 指针为准），无需写死版本号。

常用变体 ​

bash
# 指定版本
curl -fsSL <base>/magic-skills/latest/install-bootstrap.sh | bash -s -- 0.2.6

# 不装 Codex 适配层（参数透传给各技能的 install.sh）
curl -fsSL <base>/magic-skills/latest/install-bootstrap.sh | bash -s -- --no-codex

# 显式锁定 Nexus 基址（跳过内/外网探测，确保全程走内网）
MAGIC_STACK_NEXUS_RAW=http://172.16.2.100:8081/repository/raw-releases \
  curl -fsSL --noproxy '*' http://172.16.2.100:8081/repository/raw-releases/magic-skills/latest/install-bootstrap.sh | bash

# 私有仓需要凭据时
NEXUS_USER=… NEXUS_PASS=… curl -fsSL <base>/magic-skills/latest/install-bootstrap.sh | bash

前置依赖（自动补齐或拦死） ​

安装器开跑前会做依赖体检。能自动装的会自动补齐；装不了的必备会停止安装并给出手动指引—— 不会带着残缺环境硬装。

依赖是否必备缺失时的行为
docker（CLI + Docker Desktop）必备无法自动安装 → 拦死，提示装 Docker Desktop
docker daemon（Desktop 运行中）安装不强制没起则默认自动启动 Docker Desktop 并等就绪
jq必备自动下载（Nexus 内网优先 → 官网 GitHub 兜底）到 ~/.local/bin
yaml 解析（yq 或 python + pyyaml）必备自动：先 pip install pyyaml，再回退下载 yq
curl / tar / flock必备Git Bash 自带；缺失则拦死提示
cygpath（仅 Windows）必备随 Git Bash / MSYS2 自带；缺失则拦死（请在 Git Bash 内运行）
unzip可选缺失仅影响桌面端自动解压，不挡安装

关闭 docker 自启动：设 MAGIC_STACK_NO_DOCKER_AUTOSTART=1。

Docker daemon 配置（内网仓 + 镜像加速） ​

工作台镜像与业务镜像走公司内网 Docker 仓（172.16.2.100 上的 Nexus，HTTP 明文），且拉取公网基础 镜像（postgres / redis 等）需要镜像加速。推荐直接套用下面这份 daemon.json（按需增删镜像源）：

json
{
  "builder": {
    "gc": {
      "defaultKeepStorage": "20GB",
      "enabled": true
    }
  },
  "experimental": false,
  "insecure-registries": [
    "172.16.2.100:8088",
    "172.16.2.100:8082"
  ],
  "registry-mirrors": [
    "https://docker.vv.yunku.live",
    "https://docker.1ms.run",
    "https://docker.m.ixdev.cn",
    "https://dockerproxy.net",
    "https://xdark.top",
    "https://hub.rat.dev",
    "https://docker.m.daocloud.io",
    "https://hub-mirror.c.163.com"
  ]
}

逐项说明：

  • insecure-registries（必须）：公司内网 Docker 仓 172.16.2.100:8088 / 8082 走 HTTP 明文， Docker 默认拒绝非 HTTPS 镜像仓。不配则 magic-stack up 拉取工作台/业务镜像会报 http: server gave HTTP response to HTTPS client。
  • registry-mirrors（强烈建议）：拉取 Docker Hub 公网镜像时的加速/兜底源，按列表顺序尝试。 内网环境把公司镜像 docker.vv.yunku.live 放第一（最快、最稳）；其余为公网公共加速源， 某个失效时自动落下一个。不配则直连 Docker Hub，常因超时导致 magic-stack up 卡在拉基础镜像。
  • builder.gc（建议）：构建缓存自动回收，缓存超过 defaultKeepStorage（20GB）时清理， 避免热更新/反复构建把磁盘占满。

应用方式：

  • Windows / macOS（Docker Desktop）：Settings → Docker Engine，把上面的 JSON 整体替换/合并进 右侧编辑框（已有其它键则只追加缺的字段，注意逗号），点 Apply & Restart。
  • Linux：写入 /etc/docker/daemon.json 后 sudo systemctl restart docker。

改完用 docker info 确认 Insecure Registries 与 Registry Mirrors 两段都已生效。

装了什么 ​

  • magic-stack 引擎 → ~/.magic-stack/engine，全局命令 magic-stack（经 ~/.local/bin）。
  • magic-bugfix 技能 → ~/.claude/skills/magic-bugfix/。
  • Claude / Codex 适配层：技能、hooks、CLAUDE.md 受管块。
  • Windows env 注入：把 ~/.claude/settings.json 的 TMPDIR/TMP/TEMP 设为 Windows-mixed 形 （C:/…/Temp/claude），让 native .exe（curl/python 等）能读临时文件。下个会话生效。

开发工作台 ​

magic-stack 装好后，桌面端以绿色版 zip 分发、解压即用：

bash
magic-stack desktop install     # 从 Nexus 下载并解压到 ~/.magic-stack/desktop/app/
magic-stack desktop launch      # 启动

详见 开发工作台。

升级 ​

升级与安装同源——都从 Nexus 的 latest 指针取版本，无需先卸载。下载后会做 sha256 完整性校验 （校验和不匹配直接中止；老产物若无校验和则告警放行）。按粒度选其一：

升级整套技能（推荐） ​

重跑一行安装器即可：它是幂等的，拉 latest 覆盖安装，引擎、magic-bugfix 技能与 Claude / Codex 适配层一并更新到最新。引擎采用原子替换（先解包到暂存目录、就绪后才切换， 失败自动回滚），中途中断也不会把已装好的引擎弄坏。

bash
curl -fsSL http://maven.vv.yunku.live/repository/raw-releases/magic-skills/latest/install-bootstrap.sh | bash

内网命令、私有仓凭据、锁定版本等变体与上面「一行装（装整套技能）」一节完全一致 （如末尾加 -s -- 0.2.12 升到指定版本）。

只升级 magic-stack 引擎（快） ​

只想更新引擎、不动其它技能时，用内置自更新——从 Nexus 拉最新引擎包就地重装（同样原子替换 + sha256 校验）：

bash
magic-stack self-update            # 比对版本，有新才更新（已最新则跳过）
magic-stack self-update --force    # 无视版本，强制重装最新
magic-stack self-update 0.2.12     # 升到指定版本

⚠️ self-update 只更新引擎，不会升级 magic-bugfix 等其它技能。要把整套技能一起升到最新， 请用上面的「升级整套技能」重跑一行安装器。 升级后建议在各项目执行一次 magic-stack sync，让已生成的引擎产物跟上新模板。

升级开发工作台 ​

桌面端独立发版，重新下载解压最新绿色版即可（update 是 install 的语义别名）：

bash
magic-stack desktop update         # 下载并解压 latest 到 ~/.magic-stack/desktop/app/
magic-stack desktop update --run   # 升级后立即启动
  • 升级前会自动关闭正在运行的桌面端（否则运行进程锁住文件导致解压失败）；若它原本在运行， 升级完成后会自动重启加载新版本，无需手动重开。
  • 若桌面端被锁住无法关闭，按提示彻底关闭 “Magic Console” 窗口后重跑即可。

自检 ​

bash
magic-stack version     # 查看引擎版本（当前最新 0.2.12）
magic-stack doctor      # 体检安装与环境

卸载 ​

bash
bash ~/.magic-stack/engine/uninstall.sh            # 停服务 + 删适配/引擎/wrapper，保留全局状态
bash ~/.magic-stack/engine/uninstall.sh --purge    # 连 ~/.magic-stack 全局状态（registry / 凭据）一并删

--purge 会删除项目登记与本机凭据，不可恢复，慎用。