chore: make vX.Y.Z the stable release channel (docs, Helm, reward tags)

.github/scripts/count-reward.ts

@@ -1,6 +1,7 @@
 import { changeMonth, formatDate, makeDateRange } from "npm:web-utility";
 import { $, YAML } from "npm:zx";
 
+import { createDetachedCommit } from "./git.ts";
 import { Reward } from "./type.ts";
 
 $.verbose = true;
@@ -61,10 +62,12 @@ const tagName = `statistic-${new Date().toJSON().slice(0, 7)}`;
 await $`git config user.name "github-actions[bot]"`;
 await $`git config user.email "github-actions[bot]@users.noreply.github.com"`;
 
-await $`git tag -a ${tagName} $(git rev-parse HEAD) -m ${summaryText}`;
+const tagTarget = await createDetachedCommit(tagName);
+await $`git tag -a ${tagName} ${tagTarget} -m ${summaryText}`;
 await $`git push origin ${tagName} --no-verify`;
 
 await $`git config unset user.name`;
 await $`git config unset user.email`;
 
-await $`gh release create ${tagName} --notes ${summaryText}`;
+// Keep "Latest" pointing at the newest vX.Y.Z product release
+await $`gh release create ${tagName} --latest=false --notes ${summaryText}`;

.github/scripts/git.ts

@@ -0,0 +1,15 @@
+import { $ } from "npm:zx";
+
+/**
+ * Create a parentless commit with an empty tree to carry reward/statistic tags.
+ *
+ * Tags pointing at product commits become the nearest tag in `git describe`,
+ * so downstream builds would report versions like `reward-1575-3-gabc1234`
+ * instead of `v1.1.2-3-gabc1234`. Tags on a detached commit are never
+ * reachable from any branch and keep the vX.Y.Z tags authoritative.
+ */
+export async function createDetachedCommit(message: string) {
+  const emptyTree = (await $`git hash-object -w -t tree /dev/null`).stdout.trim();
+
+  return (await $`git commit-tree ${emptyTree} -m ${message}`).stdout.trim();
+}

.github/scripts/share-reward.ts

@@ -3,6 +3,7 @@ import "npm:array-unique-proposal";
 import { components } from "npm:@octokit/openapi-types";
 import { $, argv, YAML } from "npm:zx";
 
+import { createDetachedCommit } from "./git.ts";
 import { Reward } from "./type.ts";
 
 $.verbose = true;
@@ -114,7 +115,10 @@ const tagName = `reward-${issueNumber}`;
 await $`git config user.name "github-actions[bot]"`;
 await $`git config user.email "github-actions[bot]@users.noreply.github.com"`;
 
-await $`git tag -a ${tagName} ${mergeCommitSha} -m ${listText}`;
+const tagTarget = await createDetachedCommit(
+  `${tagName}: merged in ${mergeCommitSha}`,
+);
+await $`git tag -a ${tagName} ${tagTarget} -m ${listText}`;
 await $`git push origin ${tagName} --no-verify`;
 
 await $`git config unset user.name`;

.github/workflows/statistic-member-reward.yml

@@ -14,30 +14,12 @@ jobs:
           fetch-depth: 0
           fetch-tags: true
 
-      - name: Check for new commits since last statistic
-        run: |
-          last_tag=$(git describe --tags --abbrev=0 --match "statistic-*" || echo "")
-
-          if [ -z "$last_tag" ]; then
-            echo "No previous statistic tags found."
-            echo "NEW_COMMITS=true" >> $GITHUB_ENV
-          else
-            new_commits=$(git log $last_tag..HEAD --oneline)
-            if [ -z "$new_commits" ]; then
-              echo "No new commits since last statistic tag."
-              echo "NEW_COMMITS=false" >> $GITHUB_ENV
-            else
-              echo "New commits found."
-              echo "NEW_COMMITS=true" >> $GITHUB_ENV
-            fi
-          fi
+      # count-reward.ts exits early when no reward tags were created last month
       - uses: denoland/setup-deno@667a34cdef165d8d2b2e98dde39547c9daac7282 # v2.0.4
-        if: env.NEW_COMMITS == 'true'
         with:
           deno-version: v2.x
 
       - name: Statistic rewards
-        if: env.NEW_COMMITS == 'true'
         env:
           GH_TOKEN: ${{ github.token }}
         run: deno --allow-run --allow-sys --allow-env --allow-read --allow-net=api.github.com .github/scripts/count-reward.ts

docker/astronAgent/.env.example

@@ -6,6 +6,12 @@
 # ============================================================================
 
 # astron-agent image version tag (default: latest)
+#   latest   - rebuilt on every push to main; may include unreleased or breaking changes
+#   vX.Y.Z   - an exact release, e.g. v1.1.2 (also published as 1.1.2); recommended for stable deployments
+#   X.Y / X  - follows the newest patch / minor release of that line, e.g. 1.1 or 1
+# When pinning a release, check out the same git tag so the compose files match the images:
+#   git checkout vX.Y.Z
+# Available releases: https://github.com/iflytek/astron-agent/releases
 ASTRON_AGENT_VERSION=latest
 
 # ============================================================================

docs/DEPLOYMENT_FAQ.md

@@ -33,6 +33,7 @@ docker compose -f docker-compose-with-auth.yaml pull
 - Back up important data before upgrading
 - If you use the deployment without authentication, replace `docker-compose-with-auth.yaml` with `docker-compose.yaml`
 - Review whether configuration files need updates after the upgrade
+- If you pinned a release (`ASTRON_AGENT_VERSION=vX.Y.Z`), use `git fetch --tags && git checkout <new-version>` instead of `git pull`, update `ASTRON_AGENT_VERSION` in `.env` to match, and read the release notes before upgrading
 - Start the services only after confirming all environment variables are correct
 
 ---
@@ -43,7 +44,7 @@ Use the following checklist step by step. Back up important data before performi
 
 1. Run `docker compose -f docker-compose-with-auth.yaml down -v` to clear containers and volumes. This removes all persisted data.
 2. Run `git restore docker` to discard local changes under the `docker` directory and return to the repository version.
-3. Set the `ASTRON_AGENT_VERSION` environment variable to a stable release such as `v1.0.0-rc.x`.
+3. Set `ASTRON_AGENT_VERSION` to the newest stable release from [Releases](https://github.com/iflytek/astron-agent/releases) (for example `v1.1.2`), and `git checkout` the same tag so the compose files match the images.
 4. Reconfigure the remaining environment variables according to the deployment guide and verify the values carefully.
 5. Run `docker compose -f docker-compose-with-auth.yaml up -d` to start all services again.
 6. Clear the browser cache or open the page in an incognito window.

docs/guide/quick-start.md

@@ -20,6 +20,18 @@ cp .env.example .env
 
 After copying the file, fill in model, database, object storage, and authentication settings as required.
 
+### Optional: Pin A Stable Release
+
+The default `ASTRON_AGENT_VERSION=latest` tracks rolling builds from `main` and may include unreleased changes. For long-running deployments, CI, or downstream integrations, pick a `vX.Y.Z` from [Releases](https://github.com/iflytek/astron-agent/releases) and keep the code and images on the same version (switch before copying `.env.example`):
+
+```bash
+git checkout vX.Y.Z
+cp .env.example .env
+# then set ASTRON_AGENT_VERSION=vX.Y.Z in .env
+```
+
+Images are also published with floating `X.Y` and `X` tags if you want to follow patch or minor updates within one release line.
+
 ### 2. Start The Services
 
 ```bash

docs/zh/DEPLOYMENT_FAQ.md

@@ -33,6 +33,7 @@ docker compose -f docker-compose-with-auth.yaml pull
 - 升级前建议备份重要数据
 - 如果您使用的是不带认证的版本，请将 `docker-compose-with-auth.yaml` 替换为 `docker-compose.yaml`
 - 升级后请检查配置文件是否需要更新
+- 如果锁定了版本（`ASTRON_AGENT_VERSION=vX.Y.Z`），请用 `git fetch --tags && git checkout <新版本>` 代替 `git pull`，并同步修改 `.env` 中的 `ASTRON_AGENT_VERSION`；跨版本前先阅读对应 Release 说明
 - 确保所有环境变量配置正确后再启动服务
 
 ---
@@ -43,7 +44,7 @@ docker compose -f docker-compose-with-auth.yaml pull
 
 1. 执行 `docker compose -f docker-compose-with-auth.yaml down -v` 清理容器和数据卷，该步骤会删除所有数据。
 2. 运行 `git restore docker` 清理 `docker` 目录下的改动，恢复为仓库版本。
-3. 将 `ASTRON_AGENT_VERSION` 环境变量设置为稳定版 `v1.0.0-rc.x`。
+3. 将 `ASTRON_AGENT_VERSION` 设置为 [Releases](https://github.com/iflytek/astron-agent/releases) 中最新的稳定版（如 `v1.1.2`），并用 `git checkout` 切换到同名标签，保证编排文件与镜像版本一致。
 4. 按照部署文档重新配置其余环境变量，确保取值正确。
 5. 执行 `docker compose -f docker-compose-with-auth.yaml up -d` 重新启动所有服务。
 6. 清理浏览器缓存，或直接使用无痕模式访问页面。

docs/zh/guide/quick-start.md

@@ -20,6 +20,18 @@ cp .env.example .env
 
 完成复制后，按需补充模型、数据库、对象存储和鉴权相关配置。
 
+### 可选：锁定稳定版本
+
+默认的 `ASTRON_AGENT_VERSION=latest` 对应 `main` 分支的滚动构建，可能包含尚未发布的改动。用于长期运行、CI 或下游集成时，建议从 [Releases](https://github.com/iflytek/astron-agent/releases) 选一个 `vX.Y.Z`，让代码和镜像保持同一版本（在复制 `.env.example` 之前切换）：
+
+```bash
+git checkout vX.Y.Z
+cp .env.example .env
+# 然后在 .env 中设置 ASTRON_AGENT_VERSION=vX.Y.Z
+```
+
+镜像同时发布 `X.Y` 和 `X` 浮动标签，可用于自动跟进同一版本线的补丁或小版本。
+
 ### 2. 启动服务
 
 ```bash

helm/README.md

@@ -14,17 +14,23 @@
 # 克隆仓库
 git clone https://github.com/iflytek/astron-agent.git
 cd astron-agent/helm/astron-agent
+
+# 生产环境建议切换到发布版本，使 Chart 与镜像版本一致
+git checkout vX.Y.Z
 ```
 
+`global.astronAgentVersion` 留空时，镜像标签默认取 Chart 的 `appVersion`（即对应的发布版本）。v1.1.2 及更早版本的 Chart 中 `appVersion` 仍为 `latest`，切换到这些版本时请显式指定镜像版本，例如 `--set-string global.astronAgentVersion=v1.1.2`。
+
 ### 2. 修改配置
 
 编辑 `astron-agent/values.yaml`，修改关键配置：
 
 ```yaml
 # 全局配置 - 主机访问地址
 global:
-  # 镜像版本
-  astronAgentVersion: latest
+  # 镜像版本：留空使用 Chart appVersion（如 v1.1.2）；
+  # 设为 latest 跟随 main 分支滚动构建；也可用 1.1 / 1 跟随版本线
+  astronAgentVersion: ""
 
   # 主机地址，用于 MinIO、Casdoor 等服务的外部访问
   # 例如: http://your-domain.com

helm/astron-agent/Chart.yaml

@@ -2,8 +2,9 @@ apiVersion: v2
 name: astron-agent
 description: A Helm chart for Astron Agent - AI Agent Builder Platform with Authentication
 type: application
-version: 1.0.0
-appVersion: "latest"
+version: 1.1.2
+# Default image tag for all Astron Agent services; bump together with each vX.Y.Z release
+appVersion: "v1.1.2"
 keywords:
   - astron-agent
   - ai-agent

helm/astron-agent/templates/_helpers.tpl

@@ -40,6 +40,13 @@ app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
 app.kubernetes.io/managed-by: {{ .Release.Service }}
 {{- end }}
 
+{{/*
+Image tag for Astron Agent services, defaulting to the chart appVersion
+*/}}
+{{- define "astron-agent.imageTag" -}}
+{{- .Values.global.astronAgentVersion | default .Chart.AppVersion }}
+{{- end }}
+
 {{/*
 Selector labels
 */}}

helm/astron-agent/templates/console/console-frontend-deployment.yaml

@@ -24,7 +24,7 @@ spec:
       {{- end }}
       containers:
       - name: console-frontend
-        image: "{{ .Values.global.imageRegistry }}/{{ .Values.consoleFrontend.image }}:{{ .Values.global.astronAgentVersion }}"
+        image: "{{ .Values.global.imageRegistry }}/{{ .Values.consoleFrontend.image }}:{{ include "astron-agent.imageTag" . }}"
         imagePullPolicy: {{ .Values.global.imagePullPolicy }}
         env:
         - name: CONSOLE_CASDOOR_URL

helm/astron-agent/templates/console/console-hub-deployment.yaml

@@ -89,7 +89,7 @@ spec:
           echo "Object-storage credential policy check passed."
       containers:
       - name: console-hub
-        image: "{{ .Values.global.imageRegistry }}/{{ .Values.consoleHub.image }}:{{ .Values.global.astronAgentVersion }}"
+        image: "{{ .Values.global.imageRegistry }}/{{ .Values.consoleHub.image }}:{{ include "astron-agent.imageTag" . }}"
         imagePullPolicy: {{ .Values.global.imagePullPolicy }}
         env:
         {{- range $key, $value := .Values.consoleHub.env }}

helm/astron-agent/templates/core/core-services.yaml

@@ -121,7 +121,7 @@ spec:
       {{- end }}
       containers:
       - name: {{ kebabcase $serviceName }}
-        image: "{{ $.Values.global.imageRegistry }}/{{ $serviceConfig.image }}:{{ $.Values.global.astronAgentVersion }}"
+        image: "{{ $.Values.global.imageRegistry }}/{{ $serviceConfig.image }}:{{ include "astron-agent.imageTag" $ }}"
         imagePullPolicy: {{ $.Values.global.imagePullPolicy }}
         env:
         {{- range $key, $value := $serviceConfig.env }}

helm/astron-agent/values.yaml

@@ -3,7 +3,9 @@ global:
   imageRegistry: ghcr.io/iflytek/astron-agent
   imagePullPolicy: IfNotPresent
   storageClass: ""
-  astronAgentVersion: latest
+  # Image tag for Astron Agent services. Empty uses the chart appVersion (a
+  # vX.Y.Z release); set "latest" to track rolling builds from main.
+  astronAgentVersion: ""
   # Host base address for application access (e.g., https://your-domain.com).
   # MinIO endpoints are configured independently under minio so enabling an
   # application ingress never exposes object storage by accident.