feat(cli): add release update checks

.github/workflows/docker.yml

@@ -47,13 +47,18 @@ jobs:
             exit 1
           fi
           echo "IMAGE_VERSION=${RELEASE_VERSION#v}" >> "${GITHUB_ENV}"
+          echo "BUILD_DATE=$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "${GITHUB_ENV}"
 
       - name: Build and push
         uses: docker/build-push-action@v7
         with:
           context: .
           push: true
           platforms: linux/amd64,linux/arm64
+          build-args: |
+            VERSION=${{ env.RELEASE_VERSION }}
+            COMMIT=${{ github.sha }}
+            DATE=${{ env.BUILD_DATE }}
           tags: |
             ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.RELEASE_VERSION }}
             ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ env.IMAGE_VERSION }}

.github/workflows/release.yml

@@ -36,6 +36,9 @@ jobs:
         run: |
           set -euo pipefail
           mkdir -p dist
+          BUILDINFO_PACKAGE="github.com/Colvin-Y/kubernetes-ontology/internal/buildinfo"
+          COMMIT="${GITHUB_SHA:-unknown}"
+          BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
           targets=(
             "linux amd64 tar.gz"
             "linux arm64 tar.gz"
@@ -52,7 +55,7 @@ jobs:
             for cmd in kubernetes-ontology kubernetes-ontologyd kubernetes-ontology-viewer; do
               CGO_ENABLED=0 GOOS="${goos}" GOARCH="${goarch}" go build \
                 -trimpath \
-                -ldflags="-s -w" \
+                -ldflags="-s -w -X ${BUILDINFO_PACKAGE}.Version=${VERSION} -X ${BUILDINFO_PACKAGE}.Commit=${COMMIT} -X ${BUILDINFO_PACKAGE}.Date=${BUILD_DATE}" \
                 -o "${work}/${cmd}${ext}" "./cmd/${cmd}"
             done
             cp README.md README.zh-CN.md QUICKSTART.md CHANGELOG.md AI_CONTRACT.md LICENSE NOTICE SECURITY.md "${work}/"

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## v0.1.7 - 2026-05-06
+
+### Added
+
+- Added CLI version metadata, best-effort release update checks, and an
+  embedded `kubernetes-ontology --update` self-update path for release binaries.
+
+### Changed
+
+- Updated release, installation, and access skill examples for `v0.1.7`.
+
 ## v0.1.6 - 2026-04-30
 
 ### Added

Dockerfile

@@ -11,12 +11,15 @@ COPY . .
 
 ARG TARGETOS
 ARG TARGETARCH
+ARG VERSION=dev
+ARG COMMIT=unknown
+ARG DATE=unknown
 
 RUN --mount=type=cache,target=/go/pkg/mod \
     --mount=type=cache,target=/root/.cache/go-build \
     CGO_ENABLED=0 GOOS=${TARGETOS:-linux} GOARCH=${TARGETARCH} go build \
       -trimpath \
-      -ldflags="-s -w" \
+      -ldflags="-s -w -X github.com/Colvin-Y/kubernetes-ontology/internal/buildinfo.Version=${VERSION} -X github.com/Colvin-Y/kubernetes-ontology/internal/buildinfo.Commit=${COMMIT} -X github.com/Colvin-Y/kubernetes-ontology/internal/buildinfo.Date=${DATE}" \
       -o /out/ \
       ./cmd/kubernetes-ontology \
       ./cmd/kubernetes-ontologyd \

Makefile

@@ -2,6 +2,11 @@ BINARY := bin/kubernetes-ontology
 DAEMON_BINARY := bin/kubernetes-ontologyd
 VIEWER_BINARY := bin/kubernetes-ontology-viewer
 OWL_FILE ?= docs/ontology/kubernetes-ontology.owl
+VERSION ?= $(shell git describe --tags --dirty --always 2>/dev/null || echo dev)
+COMMIT ?= $(shell git rev-parse --short HEAD 2>/dev/null || echo unknown)
+DATE ?= $(shell date -u +%Y-%m-%dT%H:%M:%SZ)
+BUILDINFO_PACKAGE := github.com/Colvin-Y/kubernetes-ontology/internal/buildinfo
+BUILDINFO_LDFLAGS := -X $(BUILDINFO_PACKAGE).Version=$(VERSION) -X $(BUILDINFO_PACKAGE).Commit=$(COMMIT) -X $(BUILDINFO_PACKAGE).Date=$(DATE)
 
 DEFAULT_CONFIG := local/kubernetes-ontology.yaml
 CONFIG ?= $(if $(wildcard $(DEFAULT_CONFIG)),$(DEFAULT_CONFIG),)
@@ -50,18 +55,18 @@ DAEMON_CONFIG_ARGS = $(if $(CONFIG),--config "$(CONFIG)" $(DAEMON_CONFIG_OVERRID
 
 build:
 	mkdir -p bin
-	go build -o $(BINARY) ./cmd/kubernetes-ontology
+	go build -ldflags "$(BUILDINFO_LDFLAGS)" -o $(BINARY) ./cmd/kubernetes-ontology
 
 build-daemon:
 	mkdir -p bin
-	go build -o $(DAEMON_BINARY) ./cmd/kubernetes-ontologyd
+	go build -ldflags "$(BUILDINFO_LDFLAGS)" -o $(DAEMON_BINARY) ./cmd/kubernetes-ontologyd
 
 build-viewer:
 	mkdir -p bin
-	go build -o $(VIEWER_BINARY) ./cmd/kubernetes-ontology-viewer
+	go build -ldflags "$(BUILDINFO_LDFLAGS)" -o $(VIEWER_BINARY) ./cmd/kubernetes-ontology-viewer
 
 docker-build:
-	docker build -t kubernetes-ontology:dev .
+	docker build --build-arg VERSION="$(VERSION)" --build-arg COMMIT="$(COMMIT)" --build-arg DATE="$(DATE)" -t kubernetes-ontology:dev .
 
 owl:
 	go run ./cmd/kubernetes-ontology-owl --output "$(OWL_FILE)"

QUICKSTART.md

@@ -62,7 +62,7 @@ the CLI at that local server.
 Set the version and choose the release archive for your machine:
 
 ```bash
-export KO_VERSION=v0.1.6
+export KO_VERSION=v0.1.7
 curl -LO "https://github.com/Colvin-Y/kubernetes-ontology/releases/download/${KO_VERSION}/kubernetes-ontology_${KO_VERSION}_linux_amd64.tar.gz"
 tar -xzf "kubernetes-ontology_${KO_VERSION}_linux_amd64.tar.gz"
 cd "kubernetes-ontology_${KO_VERSION}_linux_amd64"
@@ -73,6 +73,19 @@ Use `linux_amd64`, `linux_arm64`, `darwin_amd64`, `darwin_arm64`, or
 GitHub, download the archive from a connected network and transfer it through
 your approved internal channel.
 
+Release builds include version metadata. The CLI automatically performs a
+short, best-effort GitHub Release check during normal use, and you can run the
+same flow explicitly:
+
+```bash
+./kubernetes-ontology --version
+./kubernetes-ontology --check-update
+./kubernetes-ontology --update
+```
+
+Set `KUBERNETES_ONTOLOGY_SKIP_UPDATE_CHECK=1` or pass `--no-update-check` for
+offline scripts that should not attempt outbound network calls.
+
 Create a local config file. The release archive includes
 `local/kubernetes-ontology.yaml.example`:
 
@@ -145,7 +158,7 @@ path above.
 Set the version and image namespace you want to use:
 
 ```bash
-export KO_VERSION=v0.1.6
+export KO_VERSION=v0.1.7
 export KO_IMAGE=ghcr.io/colvin-y/kubernetes-ontology
 ```
 

README.md

@@ -241,12 +241,24 @@ the published GHCR image. The release archive includes the server
 viewer `kubernetes-ontology-viewer`.
 
 ```bash
-export KO_VERSION=v0.1.6
+export KO_VERSION=v0.1.7
 curl -LO "https://github.com/Colvin-Y/kubernetes-ontology/releases/download/${KO_VERSION}/kubernetes-ontology_${KO_VERSION}_linux_amd64.tar.gz"
 tar -xzf "kubernetes-ontology_${KO_VERSION}_linux_amd64.tar.gz"
 cd "kubernetes-ontology_${KO_VERSION}_linux_amd64"
 ```
 
+The CLI checks GitHub Releases with a short timeout during normal use when the
+current binary has release version metadata. To check or update explicitly:
+
+```bash
+./kubernetes-ontology --version
+./kubernetes-ontology --check-update
+./kubernetes-ontology --update
+```
+
+Use `--no-update-check` or `KUBERNETES_ONTOLOGY_SKIP_UPDATE_CHECK=1` when a
+script must avoid any outbound release check.
+
 Create `kubernetes-ontology.yaml` with a kubeconfig path and collection scope:
 
 ```yaml
@@ -285,7 +297,7 @@ clusters, mirror `ghcr.io/colvin-y/kubernetes-ontology` to an internal registry
 and set `KO_IMAGE` to that mirror, or use the release binary path above.
 
 ```bash
-export KO_VERSION=v0.1.6
+export KO_VERSION=v0.1.7
 export KO_IMAGE=ghcr.io/colvin-y/kubernetes-ontology
 
 helm upgrade --install kubernetes-ontology ./charts/kubernetes-ontology \
@@ -598,7 +610,7 @@ Tagged releases publish:
   `kubernetes-ontology-viewer`, Quickstart docs, release notes, and a local
   config example
 - a packaged Helm chart archive, for example
-  `kubernetes-ontology-0.1.6.tgz`
+  `kubernetes-ontology-0.1.7.tgz`
 - a multi-architecture image at
   `ghcr.io/colvin-y/kubernetes-ontology:<tag>`
 - SemVer aliases without the leading `v`, plus `latest`

README.zh-CN.md

@@ -143,12 +143,24 @@ Skill marketplace 对外链接故意指向默认分支，这样 Agent 会拿到
 `kubernetes-ontology-viewer`。
 
 ```bash
-export KO_VERSION=v0.1.6
+export KO_VERSION=v0.1.7
 curl -LO "https://github.com/Colvin-Y/kubernetes-ontology/releases/download/${KO_VERSION}/kubernetes-ontology_${KO_VERSION}_linux_amd64.tar.gz"
 tar -xzf "kubernetes-ontology_${KO_VERSION}_linux_amd64.tar.gz"
 cd "kubernetes-ontology_${KO_VERSION}_linux_amd64"
 ```
 
+Release 构建会写入版本信息。CLI 在正常使用时会用短超时尽力检查 GitHub
+Release；如果发现新版本，会在 stderr 提示。也可以显式检查或更新：
+
+```bash
+./kubernetes-ontology --version
+./kubernetes-ontology --check-update
+./kubernetes-ontology --update
+```
+
+离线脚本可以使用 `--no-update-check` 或
+`KUBERNETES_ONTOLOGY_SKIP_UPDATE_CHECK=1` 禁用这次联网检查。
+
 Release 归档里带有 `local/kubernetes-ontology.yaml.example`。可以复制一份：
 
 ```bash
@@ -193,7 +205,7 @@ streamMode: informer
 `KO_IMAGE` 改成内部地址，或者使用上面的二进制方式。
 
 ```bash
-export KO_VERSION=v0.1.6
+export KO_VERSION=v0.1.7
 export KO_IMAGE=ghcr.io/colvin-y/kubernetes-ontology
 
 helm upgrade --install kubernetes-ontology ./charts/kubernetes-ontology \

charts/kubernetes-ontology/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: kubernetes-ontology
 description: Read-only Kubernetes ontology server with an optional dependency-free viewer.
 type: application
-version: 0.1.6
-appVersion: "0.1.6"
+version: 0.1.7
+appVersion: "0.1.7"
 keywords:
   - kubernetes
   - ontology

cmd/kubernetes-ontology-viewer/main.go

@@ -18,6 +18,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/Colvin-Y/kubernetes-ontology/internal/buildinfo"
 	"github.com/Colvin-Y/kubernetes-ontology/tools/visualize"
 )
 
@@ -34,19 +35,26 @@ func (e upstreamError) Error() string {
 }
 
 func main() {
+	var showVersion bool
 	var host string
 	var port int
 	var addr string
 	var server string
 	var timeout time.Duration
 
+	flag.BoolVar(&showVersion, "version", false, "Print version and exit")
 	flag.StringVar(&host, "host", "127.0.0.1", "HTTP host for the viewer")
 	flag.IntVar(&port, "port", 8765, "HTTP port for the viewer")
 	flag.StringVar(&addr, "addr", "", "HTTP listen address. Overrides --host and --port when set.")
 	flag.StringVar(&server, "server", envDefault("ONTOLOGY_SERVER", defaultOntologyServer), "Default kubernetes-ontologyd server URL")
 	flag.DurationVar(&timeout, "upstream-timeout", envDuration("VIEWER_UPSTREAM_TIMEOUT_SECONDS", 30*time.Second), "Timeout for kubernetes-ontologyd requests")
 	flag.Parse()
 
+	if showVersion {
+		fmt.Fprintln(os.Stdout, buildinfo.Summary("kubernetes-ontology-viewer"))
+		return
+	}
+
 	if addr == "" {
 		addr = net.JoinHostPort(host, strconv.Itoa(port))
 	}

cmd/kubernetes-ontology/main.go

@@ -20,15 +20,21 @@ import (
 
 	"github.com/Colvin-Y/kubernetes-ontology/internal/api"
 	"github.com/Colvin-Y/kubernetes-ontology/internal/appconfig"
+	"github.com/Colvin-Y/kubernetes-ontology/internal/buildinfo"
 	collectk8s "github.com/Colvin-Y/kubernetes-ontology/internal/collect/k8s"
 	"github.com/Colvin-Y/kubernetes-ontology/internal/model"
 	"github.com/Colvin-Y/kubernetes-ontology/internal/ontology"
 	"github.com/Colvin-Y/kubernetes-ontology/internal/query"
 	"github.com/Colvin-Y/kubernetes-ontology/internal/resolve/infer"
 	"github.com/Colvin-Y/kubernetes-ontology/internal/runtime"
+	"github.com/Colvin-Y/kubernetes-ontology/internal/updatecheck"
 )
 
 func main() {
+	var showVersion bool
+	var checkUpdate bool
+	var applyUpdate bool
+	var noUpdateCheck bool
 	var configPath string
 	var kubeconfig string
 	var cluster string
@@ -72,6 +78,10 @@ func main() {
 	var direction string
 	var limit int
 
+	flag.BoolVar(&showVersion, "version", false, "Print version and exit")
+	flag.BoolVar(&checkUpdate, "check-update", false, "Check GitHub Releases for a newer version and exit")
+	flag.BoolVar(&applyUpdate, "update", false, "Download and install the latest release for this platform")
+	flag.BoolVar(&noUpdateCheck, "no-update-check", false, "Skip the automatic latest release check for this run")
 	flag.StringVar(&configPath, "config", "", "Path to YAML config file")
 	flag.StringVar(&kubeconfig, "kubeconfig", "", "Path to kubeconfig file")
 	flag.StringVar(&cluster, "cluster", "default-cluster", "Logical cluster name for canonical IDs")
@@ -121,6 +131,32 @@ func main() {
 	flag.IntVar(&limit, "limit", 0, "Maximum entities or relations returned by server-side ontology queries")
 	flag.Parse()
 
+	updateOptions := updatecheck.Options{
+		CurrentVersion: buildinfo.VersionString(),
+		BinaryName:     "kubernetes-ontology",
+	}
+	if showVersion {
+		fmt.Fprintln(os.Stdout, buildinfo.Summary("kubernetes-ontology"))
+		return
+	}
+	if checkUpdate {
+		if err := printUpdateCheck(updateOptions); err != nil {
+			fmt.Fprintf(os.Stderr, "check update: %v\n", err)
+			os.Exit(1)
+		}
+		return
+	}
+	if applyUpdate {
+		if err := runSelfUpdate(updateOptions); err != nil {
+			fmt.Fprintf(os.Stderr, "update: %v\n", err)
+			os.Exit(1)
+		}
+		return
+	}
+	if !noUpdateCheck {
+		updatecheck.MaybeNotify(context.Background(), os.Stderr, updateOptions)
+	}
+
 	setFlags := explicitFlags()
 	cfg, err := appconfig.Load(configPath)
 	if err != nil {
@@ -366,6 +402,50 @@ func explicitFlags() map[string]bool {
 	return out
 }
 
+func printUpdateCheck(options updatecheck.Options) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	result, err := updatecheck.CheckLatest(ctx, options)
+	if err != nil {
+		return err
+	}
+	if result.Comparable {
+		if result.UpdateAvailable {
+			fmt.Fprintf(os.Stdout, "Update available: kubernetes-ontology %s -> %s\n", result.CurrentVersion, result.LatestVersion)
+			fmt.Fprintf(os.Stdout, "Run `kubernetes-ontology --update` or open %s\n", result.ReleasePage())
+			return nil
+		}
+		fmt.Fprintf(os.Stdout, "kubernetes-ontology is up to date (%s)\n", result.CurrentVersion)
+		return nil
+	}
+	fmt.Fprintf(os.Stdout, "Latest release: %s\n", result.LatestVersion)
+	fmt.Fprintf(os.Stdout, "Current build: %s (cannot compare non-release builds automatically)\n", result.CurrentVersion)
+	fmt.Fprintf(os.Stdout, "Run `kubernetes-ontology --update` to install the latest release for this platform.\n")
+	return nil
+}
+
+func runSelfUpdate(options updatecheck.Options) error {
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
+	defer cancel()
+
+	result, err := updatecheck.SelfUpdate(ctx, "", options)
+	if err != nil {
+		return err
+	}
+	if result.Comparable && !result.UpdateAvailable {
+		fmt.Fprintf(os.Stdout, "kubernetes-ontology is already up to date (%s)\n", result.CurrentVersion)
+		return nil
+	}
+	if result.Staged {
+		fmt.Fprintf(os.Stdout, "Downloaded kubernetes-ontology %s to %s\n", result.LatestVersion, result.UpdatedPath)
+		fmt.Fprintf(os.Stdout, "Replace the current executable with that file after this process exits.\n")
+		return nil
+	}
+	fmt.Fprintf(os.Stdout, "Updated kubernetes-ontology to %s at %s\n", result.LatestVersion, result.UpdatedPath)
+	return nil
+}
+
 func applyConfigDefaults(cfg appconfig.Config, setFlags map[string]bool, kubeconfig, cluster, namespace, contextNamespaces, streamMode *string, bootstrapTimeout, observeDuration, pollInterval *time.Duration, maxDepth, storageMaxDepth *int) error {
 	if cfg.Kubeconfig != "" && !setFlags["kubeconfig"] {
 		*kubeconfig = cfg.Kubeconfig