feat(scripts): 增加多环境一键启停管理与分支工作流辅助脚本

Co-authored-by: Cursor <cursoragent@cursor.com>

scripts/env-service.sh

@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Chat-Agent-System 多环境与服务管理脚本 (env-service.sh)
+#
+# 支持环境:
+#   shared : 共享知识库基础设施 (pgvector / regulations-db)
+#   dev    : 开发环境服务 (端口 8080, DB 5433, 数据隔离 ./data/dev)
+#   test   : 测试环境服务 (端口 8081, DB 5434, 数据隔离 ./data/test)
+#   main   : 生产环境服务 (端口 8000, DB 5435, 数据隔离 ./data/main)
+#   all    : 所有环境
+#
+# 支持命令: start | stop | restart | status | logs | down
+# =============================================================================
+
+set -eo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+cd "${ROOT_DIR}"
+
+ENV_TARGET="$1"
+ACTION="$2"
+
+show_usage() {
+    cat <<EOF
+用法:
+    $0 <shared|dev|test|main|all> <start|stop|restart|status|logs|down>
+
+示例:
+    $0 shared start    # 启动共享知识库基础服务
+    $0 dev start       # 启动开发分支环境
+    $0 test start      # 启动测试分支环境
+    $0 main start      # 启动主分支生产环境
+    $0 all status      # 查看所有环境服务状态
+    $0 dev logs        # 查看开发环境日志
+    $0 dev stop        # 停止开发环境
+EOF
+    exit 1
+}
+
+if [[ -z "${ENV_TARGET}" || -z "${ACTION}" ]]; then
+    show_usage
+fi
+
+# 确保环境变量配置文件与存储目录存在
+prepare_env_file() {
+    local target="$1"
+    local env_file="configs/.env.${target}"
+    local env_example="configs/.env.${target}.example"
+
+    if [[ ! -f "${env_file}" ]]; then
+        if [[ -f "${env_example}" ]]; then
+            echo "[提示] 配置文件 ${env_file} 不存在，正在从 ${env_example} 自动初始化..."
+            cp "${env_example}" "${env_file}"
+        fi
+    fi
+
+    # 确保隔离数据目录存在
+    if [[ "${target}" == "shared" ]]; then
+        mkdir -p "data/shared/kb"
+    else
+        mkdir -p "data/${target}/workspaces"
+    fi
+}
+
+# 确保 Docker 共享网络已创建
+ensure_shared_network() {
+    if ! docker network ls --format '{{.Name}}' | grep -q '^chat-agent-shared-net$'; then
+        echo "[网络] 创建共享基础设施 Docker 网络: chat-agent-shared-net..."
+        docker network create chat-agent-shared-net >/dev/null 2>&1 || true
+    fi
+}
+
+run_compose() {
+    local target="$1"
+    local act="$2"
+    local compose_file="docker-compose.${target}.yml"
+    local env_file="configs/.env.${target}"
+
+    if [[ ! -f "${compose_file}" ]]; then
+        echo "[错误] 找不到编排文件: ${compose_file}"
+        exit 1
+    fi
+
+    prepare_env_file "${target}"
+
+    local env_arg=""
+    if [[ -f "${env_file}" ]]; then
+        env_arg="--env-file ${env_file}"
+    fi
+
+    case "${act}" in
+        start)
+            if [[ "${target}" != "shared" ]]; then
+                ensure_shared_network
+            fi
+            echo "==> [${target}] 启动服务 (${compose_file})..."
+            docker compose -f "${compose_file}" ${env_arg} up -d
+            echo "==> [${target}] 服务已启动"
+            ;;
+        stop)
+            echo "==> [${target}] 停止服务..."
+            docker compose -f "${compose_file}" ${env_arg} stop
+            ;;
+        restart)
+            if [[ "${target}" != "shared" ]]; then
+                ensure_shared_network
+            fi
+            echo "==> [${target}] 重启服务..."
+            docker compose -f "${compose_file}" ${env_arg} restart
+            ;;
+        status|ps)
+            echo "------------------------------------------------------------"
+            echo "环境: [${target}] (编排: ${compose_file})"
+            echo "------------------------------------------------------------"
+            docker compose -f "${compose_file}" ${env_arg} ps
+            echo ""
+            ;;
+        logs)
+            docker compose -f "${compose_file}" ${env_arg} logs -f --tail=100
+            ;;
+        down)
+            echo "==> [${target}] 清理并下线容器..."
+            docker compose -f "${compose_file}" ${env_arg} down
+            ;;
+        *)
+            echo "[错误] 未知操作: ${act}"
+            show_usage
+            ;;
+    esac
+}
+
+case "${ENV_TARGET}" in
+    shared|dev|test|main)
+        run_compose "${ENV_TARGET}" "${ACTION}"
+        ;;
+    all)
+        case "${ACTION}" in
+            start)
+                run_compose "shared" "start"
+                run_compose "dev" "start"
+                run_compose "test" "start"
+                run_compose "main" "start"
+                ;;
+            stop|down)
+                run_compose "dev" "${ACTION}"
+                run_compose "test" "${ACTION}"
+                run_compose "main" "${ACTION}"
+                run_compose "shared" "${ACTION}"
+                ;;
+            status|ps)
+                run_compose "shared" "status"
+                run_compose "dev" "status"
+                run_compose "test" "status"
+                run_compose "main" "status"
+                ;;
+            *)
+                echo "[错误] 'all' 仅支持 start | stop | down | status 操作"
+                exit 1
+                ;;
+        esac
+        ;;
+    *)
+        echo "[错误] 未知环境目标: ${ENV_TARGET}"
+        show_usage
+        ;;
+esac

scripts/git-workflow-helper.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# =============================================================================
+# Git 分支工作流辅助检查工具 (git-workflow-helper.sh)
+# 作用：校验分支合规性、协助功能子分支检出与阶段发布节点标记
+# =============================================================================
+
+set -eo pipefail
+
+COMMAND="$1"
+ARG="$2"
+
+CURRENT_BRANCH="$(git branch --show-current 2>/dev/null || echo '')"
+
+show_help() {
+    cat <<EOF
+Git 3 分支工作流辅助工具:
+
+用法:
+    $0 check                     # 检查当前分支状态及工作流提示
+    $0 feature <name>            # 基于 dev 检出 feature/<name> 子分支
+    $0 fix <name>                # 基于 dev 检出 fix/<name> 子分支
+    $0 merge-to-dev              # 将当前功能子分支测试后合回 dev
+    $0 promote-to-test <tag>     # 将 dev 合并到 test 并打候选版本 tag (如 rc-v1.1.0-beta.1)
+    $0 release-to-main <tag>     # 将 test 合并到 main 并打正式版本 tag (如 v1.1.0)
+EOF
+    exit 1
+}
+
+case "${COMMAND}" in
+    check)
+        echo "=== 当前 Git 分支与工作流检查 ==="
+        echo "当前分支: [${CURRENT_BRANCH}]"
+        echo ""
+        case "${CURRENT_BRANCH}" in
+            dev)
+                echo "状态: 正处于【开发分支】。"
+                echo "提示: 可直接在此分支进行小功能渐进式提交，或创建 feature/<name> 进行复杂功能开发。"
+                ;;
+            test)
+                echo "状态: 正处于【测试分支】。"
+                echo "提示: 仅用于长期实际部署和运维测试。新功能开发请切换至 dev。"
+                ;;
+            main)
+                echo "状态: 正处于【主分支 (Release)】。"
+                echo "警告: 严禁直接在 main 上开发代码！只有经过 test 验证的稳定节点才能合入 main。"
+                ;;
+            feature/*|fix/*)
+                echo "状态: 正处于功能子分支 [${CURRENT_BRANCH}]。"
+                echo "提示: 自测完成后，使用 '$0 merge-to-dev' 合回 dev 分支。"
+                ;;
+            *)
+                echo "提示: 当前处于非常规分支 [${CURRENT_BRANCH}]。"
+                ;;
+        esac
+        echo ""
+        git status --short
+        ;;
+
+    feature)
+        if [[ -z "${ARG}" ]]; then
+            echo "错误: 请提供 feature 名称，例如: $0 feature session-cache"
+            exit 1
+        fi
+        echo "==> 从 dev 切换并创建 feature/${ARG}..."
+        git checkout dev
+        git pull --rebase origin dev 2>/dev/null || true
+        git checkout -b "feature/${ARG}"
+        echo "成功切换至 feature/${ARG}"
+        ;;
+
+    fix)
+        if [[ -z "${ARG}" ]]; then
+            echo "错误: 请提供 fix 名称，例如: $0 fix db-pool-leak"
+            exit 1
+        fi
+        echo "==> 从 dev 切换并创建 fix/${ARG}..."
+        git checkout dev
+        git pull --rebase origin dev 2>/dev/null || true
+        git checkout -b "fix/${ARG}"
+        echo "成功切换至 fix/${ARG}"
+        ;;
+
+    merge-to-dev)
+        if [[ "${CURRENT_BRANCH}" != feature/* && "${CURRENT_BRANCH}" != fix/* ]]; then
+            echo "错误: 当前分支为 ${CURRENT_BRANCH}，不是 feature/* 或 fix/* 分支！"
+            exit 1
+        fi
+        SRC_BRANCH="${CURRENT_BRANCH}"
+        echo "==> 准备将 ${SRC_BRANCH} 合并回 dev 分支..."
+        git checkout dev
+        git pull --rebase origin dev 2>/dev/null || true
+        git merge --no-ff "${SRC_BRANCH}" -m "merge: 合并 ${SRC_BRANCH} 到开发分支 dev"
+        echo "合并成功！可运行 'git branch -d ${SRC_BRANCH}' 删除已合入的本地临时分支。"
+        ;;
+
+    promote-to-test)
+        TAG="${ARG}"
+        if [[ -z "${TAG}" ]]; then
+            echo "错误: 请提供测试候选 Tag 名称，例如: $0 promote-to-test rc-v1.0.0-beta.1"
+            exit 1
+        fi
+        echo "==> 切换至 test 分支并合并 dev 当前稳定节点..."
+        git checkout test
+        git pull --rebase origin test 2>/dev/null || true
+        git merge --no-ff dev -m "release-candidate: 汇集 dev 功能至 test 分支，准备长期实测 [Tag: ${TAG}]"
+        git tag -a "${TAG}" -m "实测候选版本: ${TAG}"
+        echo "已成功合并至 test 并打上标签: ${TAG}！请启动 test 环境进行运维与功能测试。"
+        ;;
+
+    release-to-main)
+        TAG="${ARG}"
+        if [[ -z "${TAG}" ]]; then
+            echo "错误: 请提供正式发布 Tag 名称，例如: $0 release-to-main v1.0.0"
+            exit 1
+        fi
+        echo "==> 切换至 main 分支并合并 test 验证节点..."
+        git checkout main
+        git pull --rebase origin main 2>/dev/null || true
+        git merge --no-ff test -m "release: 经长期测试与运维验证通过，正式发布 ${TAG}"
+        git tag -a "${TAG}" -m "正式发布版本: ${TAG}"
+        echo "已成功合并至 main 并打上正式发布标签: ${TAG}！"
+        ;;
+
+    *)
+        show_help
+        ;;
+esac