Merge pull request #3 from weiyong1024/dev/polish

feat: unified version management — lock CLI and Docker image versions

Author: weiyong1024

.github/workflows/release.yml

@@ -7,6 +7,7 @@ on:
 
 permissions:
   contents: write
+  packages: write
 
 jobs:
   release:
@@ -26,3 +27,30 @@ jobs:
           args: release --clean
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  docker:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: meta
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/setup-buildx-action@v3
+
+      - uses: docker/build-push-action@v6
+        with:
+          context: internal/assets/docker
+          push: true
+          tags: |
+            ghcr.io/weiyong1024/clawsandbox:${{ steps.meta.outputs.version }}
+            ghcr.io/weiyong1024/clawsandbox:latest
+          cache-from: type=gha
+          cache-to: type=gha,mode=max

.goreleaser.yml

@@ -14,9 +14,9 @@ builds:
       - CGO_ENABLED=0
     ldflags:
       - -s -w
-      - -X github.com/weiyong1024/clawsandbox/internal/cli.Version={{.Version}}
-      - -X github.com/weiyong1024/clawsandbox/internal/cli.GitCommit={{.ShortCommit}}
-      - -X github.com/weiyong1024/clawsandbox/internal/cli.BuildDate={{.Date}}
+      - -X github.com/weiyong1024/clawsandbox/internal/version.Version={{.Version}}
+      - -X github.com/weiyong1024/clawsandbox/internal/version.GitCommit={{.ShortCommit}}
+      - -X github.com/weiyong1024/clawsandbox/internal/version.BuildDate={{.Date}}
     goos:
       - darwin
       - linux

Makefile

@@ -8,9 +8,9 @@ GIT_COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
 BUILD_DATE ?= $(shell date -u '+%Y-%m-%dT%H:%M:%SZ')
 
 LDFLAGS    = -s -w \
-  -X '$(MODULE)/internal/cli.Version=$(VERSION)' \
-  -X '$(MODULE)/internal/cli.GitCommit=$(GIT_COMMIT)' \
-  -X '$(MODULE)/internal/cli.BuildDate=$(BUILD_DATE)'
+  -X '$(MODULE)/internal/version.Version=$(VERSION)' \
+  -X '$(MODULE)/internal/version.GitCommit=$(GIT_COMMIT)' \
+  -X '$(MODULE)/internal/version.BuildDate=$(BUILD_DATE)'
 
 .PHONY: build build-all docker-build install clean tidy
 

README.md

@@ -51,15 +51,7 @@ make build
 sudo make install
 ```
 
-### 2. Build the Docker image
-
-Required once. Downloads ~1.4 GB and takes a few minutes.
-
-```bash
-clawsandbox build
-```
-
-### 3. Deploy your fleet
+### 2. Deploy your fleet
 
 **Option A: Web Dashboard (recommended)**
 
@@ -89,7 +81,7 @@ clawsandbox create 3
 clawsandbox list
 ```
 
-### 4. Set up each claw
+### 3. Set up each claw
 
 Each claw needs a one-time configuration via its desktop. Open it from the Dashboard (click **"Desktop"** on an instance card) or via CLI:
 
@@ -121,8 +113,7 @@ clawsandbox dashboard --help    # Show dashboard subcommands
 Quick reference:
 
 ```bash
-clawsandbox build                       # Build the OpenClaw sandbox image
-clawsandbox create <N>                  # Create N claw instances
+clawsandbox create <N>                  # Create N claw instances (auto-pulls image)
 clawsandbox list                        # List all instances and their status
 clawsandbox desktop <name>              # Open an instance's desktop in the browser
 clawsandbox start <name|all>            # Start a stopped instance
@@ -132,9 +123,12 @@ clawsandbox logs <name> [-f]            # View instance logs
 clawsandbox destroy <name|all>          # Destroy instance (data kept by default)
 clawsandbox destroy --purge <name|all>  # Destroy instance and delete its data
 clawsandbox dashboard serve              # Start the Web Dashboard
+clawsandbox dashboard stop               # Stop the Web Dashboard
+clawsandbox dashboard restart            # Restart the Web Dashboard
 clawsandbox dashboard open               # Open the Dashboard in your browser
-clawsandbox config                      # Show current configuration
-clawsandbox version                     # Print version info
+clawsandbox build                        # Build image locally (offline/custom use)
+clawsandbox config                       # Show current configuration
+clawsandbox version                      # Print version info
 ```
 
 ## Resource Usage

README.zh-CN.md

@@ -51,15 +51,7 @@ make build
 sudo make install
 ```
 
-### 2. 构建 Docker 镜像
-
-首次使用需要执行一次，下载约 1.4 GB，需要几分钟：
-
-```bash
-clawsandbox build
-```
-
-### 3. 部署龙虾军团
+### 2. 部署龙虾军团
 
 **方式 A：Web 仪表盘（推荐）**
 
@@ -89,7 +81,7 @@ clawsandbox create 3
 clawsandbox list
 ```
 
-### 4. 配置每只龙虾
+### 3. 配置每只龙虾
 
 每只龙虾需要通过其桌面完成一次初始化。可以在仪表盘点击 **「桌面」** 打开，也可以用 CLI：
 
@@ -121,8 +113,7 @@ clawsandbox dashboard --help    # 查看 dashboard 子命令组
 常用命令速查：
 
 ```bash
-clawsandbox build                       # 构建 OpenClaw 龙虾沙箱镜像
-clawsandbox create <N>                  # 创建 N 个龙虾实例
+clawsandbox create <N>                  # 创建 N 个龙虾实例（自动拉取镜像）
 clawsandbox list                        # 列出所有实例及状态
 clawsandbox desktop <name>              # 在浏览器中打开实例桌面
 clawsandbox start <name|all>            # 启动已停止的实例
@@ -132,9 +123,12 @@ clawsandbox logs <name> [-f]            # 查看实例日志
 clawsandbox destroy <name|all>          # 销毁实例（默认保留数据）
 clawsandbox destroy --purge <name|all>  # 销毁实例并删除数据
 clawsandbox dashboard serve              # 启动 Web 仪表盘
+clawsandbox dashboard stop               # 停止 Web 仪表盘
+clawsandbox dashboard restart            # 重启 Web 仪表盘
 clawsandbox dashboard open               # 在浏览器中打开仪表盘
-clawsandbox config                      # 显示当前配置
-clawsandbox version                     # 查看版本信息
+clawsandbox build                        # 本地构建镜像（离线或自定义场景）
+clawsandbox config                       # 显示当前配置
+clawsandbox version                      # 查看版本信息
 ```
 
 ## 资源占用参考

docs/SYSTEM_DESIGN.md

@@ -457,3 +457,69 @@ clawsandbox list
 docker stats claw-1 claw-2
 # → Confirm memory stays within memory_limit
 ```
+
+## 11. Version Management
+
+A single `git tag` locks both the CLI binary and Docker image to the same version, with automated publishing to GitHub Release and GHCR.
+
+### Architecture
+
+```
+git tag v0.1.0 && git push origin v0.1.0
+        │
+        ▼
+   GitHub Actions
+   ┌──────────────────┬──────────────────────┐
+   │  GoReleaser       │  Docker Build+Push    │
+   │  CLI binaries x4  │  ghcr.io image        │
+   │  (darwin/linux    │  :0.1.0 + :latest     │
+   │   x amd64/arm64) │                        │
+   └────────┬─────────┴──────────┬─────────────┘
+            ▼                    ▼
+     GitHub Release         ghcr.io/weiyong1024/clawsandbox
+```
+
+### Shared version package (`internal/version/`)
+
+Version metadata (`Version`, `GitCommit`, `BuildDate`) is injected at build time via ldflags into `internal/version`. Both `internal/cli/version.go` and `internal/config/config.go` import from this shared package.
+
+The `ImageTag()` helper derives the Docker image tag from the CLI version:
+- Release build (e.g. `v0.1.0`): returns `0.1.0`
+- Dev build (no tag): returns `latest`
+
+### Image naming and tagging
+
+- **Registry**: `ghcr.io/weiyong1024/clawsandbox`
+- **Default tag**: determined at runtime via `version.ImageTag()`
+- `clawsandbox build` tags the image with both `:<version>` and `:latest`
+- `clawsandbox create` uses `:<version>` to ensure CLI-image version consistency
+
+### Auto-pull on create
+
+When `clawsandbox create` (or the Dashboard's create action) finds the image missing locally, it automatically attempts `docker pull` from GHCR before failing. Users with internet access never need to run `clawsandbox build`.
+
+```
+image not found locally
+  → docker pull ghcr.io/weiyong1024/clawsandbox:0.1.0
+  → success? proceed with create
+  → fail? suggest `clawsandbox build`
+```
+
+### CI pipeline (`.github/workflows/release.yml`)
+
+Triggered on `v*` tag push. Two parallel jobs:
+
+| Job | Tool | Output |
+|-----|------|--------|
+| `release` | GoReleaser | 4 CLI binaries → GitHub Release |
+| `docker` | docker/build-push-action | Image → `ghcr.io/weiyong1024/clawsandbox:<version>` + `:latest` |
+
+### Release workflow (for maintainers)
+
+```bash
+git checkout main
+git pull origin main
+git tag v0.1.0
+git push origin v0.1.0
+# CI handles the rest
+```

docs/SYSTEM_DESIGN.zh-CN.md

@@ -469,3 +469,69 @@ clawsandbox list
 docker stats lobster-1 lobster-2
 # → 确认内存在 memory_limit 之内
 ```
+
+## 11. 版本管理
+
+一次 `git tag` 同时锁定 CLI 和 Docker 镜像的版本，自动发布到 GitHub Release 和 GHCR。
+
+### 架构
+
+```
+git tag v0.1.0 && git push origin v0.1.0
+        │
+        ▼
+   GitHub Actions
+   ┌──────────────────┬──────────────────────┐
+   │  GoReleaser       │  Docker Build+Push    │
+   │  CLI 二进制 x4    │  ghcr.io 镜像         │
+   │  (darwin/linux    │  :0.1.0 + :latest     │
+   │   x amd64/arm64) │                        │
+   └────────┬─────────┴──────────┬─────────────┘
+            ▼                    ▼
+     GitHub Release         ghcr.io/weiyong1024/clawsandbox
+```
+
+### 共享版本包 (`internal/version/`)
+
+版本元数据（`Version`、`GitCommit`、`BuildDate`）在构建时通过 ldflags 注入到 `internal/version`。`internal/cli/version.go` 和 `internal/config/config.go` 均从此包导入。
+
+`ImageTag()` 函数根据 CLI 版本推导 Docker 镜像标签：
+- release 版本（如 `v0.1.0`）：返回 `0.1.0`
+- dev 版本（无标签）：返回 `latest`
+
+### 镜像命名与标签
+
+- **仓库地址**：`ghcr.io/weiyong1024/clawsandbox`
+- **默认标签**：运行时通过 `version.ImageTag()` 动态确定
+- `clawsandbox build` 同时打 `:<version>` 和 `:latest` 两个标签
+- `clawsandbox create` 使用 `:<version>` 确保 CLI 与镜像版本一致
+
+### 自动拉取镜像
+
+当 `clawsandbox create`（或仪表盘的创建接口）发现本地没有镜像时，自动尝试从 GHCR 拉取。联网用户无需执行 `clawsandbox build`。
+
+```
+本地未找到镜像
+  → docker pull ghcr.io/weiyong1024/clawsandbox:0.1.0
+  → 成功？继续创建
+  → 失败？提示用户执行 clawsandbox build
+```
+
+### CI 流水线 (`.github/workflows/release.yml`)
+
+触发条件：`v*` 标签推送。两个并行任务：
+
+| 任务 | 工具 | 产出 |
+|------|------|------|
+| `release` | GoReleaser | 4 个平台的 CLI 二进制 → GitHub Release |
+| `docker` | docker/build-push-action | 镜像 → `ghcr.io/weiyong1024/clawsandbox:<version>` + `:latest` |
+
+### 发版流程（维护者操作）
+
+```bash
+git checkout main
+git pull origin main
+git tag v0.1.0
+git push origin v0.1.0
+# CI 自动完成剩余工作
+```

internal/cli/build.go

@@ -8,14 +8,16 @@ import (
 
 	"github.com/weiyong1024/clawsandbox/internal/config"
 	"github.com/weiyong1024/clawsandbox/internal/container"
+	"github.com/weiyong1024/clawsandbox/internal/version"
 )
 
 var buildCmd = &cobra.Command{
 	Use:   "build",
 	Short: "Build the OpenClaw sandbox Docker image",
-	Long: `Build the clawsandbox/openclaw Docker image locally.
-This is required once before running 'clawsandbox create'.
-The build downloads ~1.4 GB and may take several minutes.`,
+	Long: `Build the OpenClaw sandbox Docker image locally.
+This is only needed for offline use or customization.
+When connected to the internet, 'clawsandbox create' auto-pulls the
+pre-built image from GHCR.`,
 	Example: "  clawsandbox build",
 	RunE:    runBuild,
 }
@@ -38,6 +40,16 @@ func runBuild(cmd *cobra.Command, args []string) error {
 		return fmt.Errorf("build failed: %w", err)
 	}
 
+	// Also tag as :latest when building a versioned image
+	if version.ImageTag() != "latest" {
+		latestRef := fmt.Sprintf("%s:latest", cfg.Image.Name)
+		if err := container.TagImage(cli, imageRef, cfg.Image.Name, "latest"); err != nil {
+			fmt.Fprintf(os.Stderr, "Warning: failed to tag as %s: %v\n", latestRef, err)
+		} else {
+			fmt.Printf("Also tagged as %s\n", latestRef)
+		}
+	}
+
 	fmt.Printf("\nImage %s built successfully.\n", imageRef)
 	fmt.Println("Run 'clawsandbox create <N>' to deploy your fleet.")
 	return nil

internal/cli/create.go

@@ -39,13 +39,17 @@ func runCreate(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	// Check image exists
+	// Check image exists; attempt auto-pull from GHCR if missing
 	exists, err := container.ImageExists(cli, cfg.ImageRef())
 	if err != nil {
 		return err
 	}
 	if !exists {
-		return fmt.Errorf("image %s not found\nRun 'clawsandbox build' first", cfg.ImageRef())
+		fmt.Printf("Image %s not found locally, pulling from registry...\n", cfg.ImageRef())
+		if pullErr := container.PullImage(cli, cfg.Image.Name, cfg.Image.Tag, os.Stdout); pullErr != nil {
+			return fmt.Errorf("image %s not found locally and pull failed: %v\nRun 'clawsandbox build' to build it manually", cfg.ImageRef(), pullErr)
+		}
+		fmt.Println("Image pulled successfully.")
 	}
 
 	// Ensure network

internal/cli/version.go

@@ -5,13 +5,8 @@ import (
 	"runtime"
 
 	"github.com/spf13/cobra"
-)
 
-var (
-	// Injected at build time via ldflags. See Makefile / .goreleaser.yml.
-	Version   = "dev"
-	GitCommit = "unknown"
-	BuildDate = "unknown"
+	"github.com/weiyong1024/clawsandbox/internal/version"
 )
 
 var versionShort bool
@@ -21,12 +16,12 @@ var versionCmd = &cobra.Command{
 	Short: "Print the version of ClawSandbox",
 	Run: func(cmd *cobra.Command, args []string) {
 		if versionShort {
-			fmt.Println(Version)
+			fmt.Println(version.Version)
 			return
 		}
-		fmt.Printf("clawsandbox %s\n", Version)
-		fmt.Printf("  commit:    %s\n", GitCommit)
-		fmt.Printf("  built:     %s\n", BuildDate)
+		fmt.Printf("clawsandbox %s\n", version.Version)
+		fmt.Printf("  commit:    %s\n", version.GitCommit)
+		fmt.Printf("  built:     %s\n", version.BuildDate)
 		fmt.Printf("  go:        %s\n", runtime.Version())
 		fmt.Printf("  platform:  %s/%s\n", runtime.GOOS, runtime.GOARCH)
 	},