Agent-System/.doc/archive/reference/branch-and-environment-rules.md

研发分支与多套独立环境运行规范 (Branch & Environment Rules)

HISTORICAL：日常开发分支策略已由 AGENTS.md §6.2、PROJECT.md §4 与 .cursor/rules/git-workflow-and-environments.mdc 取代为「一律从 dev 开 feature/* 或 fix/*，禁止在三大主干直接 commit」。本文档保留作环境矩阵与历史流程参考。

本规范为本系统代码仓库的强制性规范，涵盖 Git 3 分支流转模型、任务功能拆分与渐进式提交、三套环境独立运行（知识库共享 + 对话与数据库隔离） 以及 运维操作指引。

---

一、 Git 固定三分支体系与流转规范

本仓库严格固定维护 3 个常驻分支：

       (Feature/Fix 子分支)
        ┌─────────────┐
        │ feature/*** │
        └──────┬──────┘
  (创建/自测)  │  (合回)
        ▼      ▼
┌─────────────────────────────────┐
│ 开发分支: dev                   │  <-- 所有日常开发在此进行，功能逐步提交
└────────────────┬────────────────┘
                 │ (积累一定阶段功能，准备长期部署实测)
                 ▼
┌─────────────────────────────────┐
│ 测试分支: test                  │  <-- 部署到测试环境，进行真实环境长期运维与测试
└────────────────┬────────────────┘
                 │ (测试分支经过实际运维和测试验证，达到发布标准)
                 ▼
┌─────────────────────────────────┐
│ 主分支: main (Release)          │  <-- 生产发布基线，对应线上生产环境
└─────────────────────────────────┘

1. 开发分支 (dev)

• 定位：日常开发核心集成分支。
• 职责：所有新功能（Features）、常规缺陷修复（Bugfixes）、日常重构均在 dev 分支推进。
• 子分支策略：
  • 简单任务：可直接在 dev 分支上按功能拆分进行渐进式提交。
  • 中大型或独立功能：必须从 dev 检出子分支，命名格式为：
    • feature/<功能简述> （如 feature/session-isolation）
    • fix/<缺陷简述> （如 fix/llm-streaming-timeout）
  • 合回机制：子分支在开发者本地或容器中完成自测、通过单元测试和代码审查后，合并回 dev 分支（推荐保留提交历史或使用半快进合并）。合并完成后应及时删除临时子分支。

2. 测试分支 (test)

• 定位：长期实测与准生产验证分支（Staging / Pre-Release）。
• 职责：当 dev 分支积累了一定的业务功能或阶段里程碑，需要进行较长时间的真实环境部署、冒烟测试、压力测试、全链路联调以及运维验证时，将 dev 的对应阶段节点合并至 test 分支。
• 节点打标：
  • 在 test 分支部署实测时，建议在该节点上打上候选版本 Tag（如 rc-v1.1.0-beta.1）。
  • 测试期间发现的缺陷，若属于该候选版本的严重阻断问题，可在 test 分支修复并验证，验证完毕后必须同步回合（Cherry-pick 或 Merge）至 dev 分支；非阻断问题统一在 dev 中继续排期推进。

3. 主分支 (main)

• 定位：生产发布分支（Production / Release）。
• 职责：主分支的代码代表经过实际运维与测试检验、已达到生产可用标准的系统版本。
• 发布准入标准：
  • 严禁任何未经 test 分支充分测试验证的代码直接提交或合入 main。
  • 必须由 test 分支上的验证通过节点，以合并的方式提交至 main。
• 发布打标：
  • 每次合入 main 后，必须打上正式发布 Tag（语义化版本，如 v1.0.0, v1.1.0）。
• 紧急热修复 (Hotfix)：
  • 遇到线上紧急故障且 test 分支已有新开发代码时，从 main 检出 hotfix/<issue> 分支。
  • 修复完成并在专门隔离环境测试后，先合回 main 打补丁 Tag（如 v1.0.1），同时合并回 test 和 dev 分支。

---

二、 任务拆分与渐进式提交规范 (Progressive Commits)

为保证代码可追溯性、降低 Code Review 成本并利于排查回滚，禁止将一个大任务的所有变更揉合成一个巨大的提交。

1. 拆分原则

一个完整的业务任务必须按功能层次、逻辑职责进行横向或纵向切分，并在开发过程中逐步提交：

1. 数据模型与存储层提交：定义数据库 Schema、ORM 映射、迁移脚本或接口实体。
2. 核心业务逻辑与 Agent 算法层提交：实现核心业务处理、Agent 工具、会话逻辑。
3. API / 适配层提交：暴露 HTTP/gRPC 端点、集成外部组件或中间件。
4. 单元与集成测试提交：补充对应模块的自动化测试用例。
5. 文档与配置更新提交：同步更新环境参数配置、README 或设计文档。

2. 提交信息规范 (Conventional Commits)

采用统一的 Git Commit 消息规范：

<type>(<scope>): <subject>

[optional body]

• Type 类型：
  • feat: 新增功能（按功能拆分逐步提交）
  • fix: 修复缺陷
  • refactor: 代码重构（无功能改变与 Bug 修复）
  • test: 增加或修改测试用例
  • docs: 文档变动
  • chore: 构建工具、依赖库更新、脚手架配置等
  • ci: CI/CD 流程调整
• 示例：
  • feat(db): 增加会话与多租户数据库模型迁移脚本
  • feat(agent): 实现知识库问答工具的多环境路由调用
  • test(agent): 增加知识库共享与对话隔离测试用例
  • chore(deploy): 配置 test 环境独立端口与 docker-compose

---

三、 三套环境独立运行架构规范

每个分支在部署时对应一套完整的启动服务。必须严格遵循 “知识库共享，对话数据与数据库隔离” 的核心原则。

                     ┌──────────────────────────────────────────┐
                     │          共享基础设施: 知识库服务         │
                     │  - pgvector / 向量检索 / 统一知识索引库    │
                     │  - 共享数据卷: shared-kb-data             │
                     │  - 共享服务端口: 5432 (Internal)          │
                     └─────────────────────┬────────────────────┘
                                           │ (只读检索或统一管理通道)
        ┌──────────────────────────────────┼──────────────────────────────────┐
        │                                  │                                  │
        ▼                                  ▼                                  ▼
┌─────────────────────────┐    ┌─────────────────────────┐    ┌─────────────────────────┐
│     开发环境 (dev)      │    │     测试环境 (test)     │    │     主干环境 (main)     │
│ 容器组: agent-dev-*     │    │ 容器组: agent-test-*    │    │ 容器组: agent-main-*    │
├─────────────────────────┤    ├─────────────────────────┤    ├─────────────────────────┤
│ • 专属数据库:           │    │ • 专属数据库:           │    │ • 专属数据库:           │
│   agent_dev (Port 5433) │    │   agent_test (Port 5434)│    │   agent_main (Port 5435)│
│ • 专属会话与存储卷:     │    │ • 专属会话与存储卷:     │    │ • 专属会话与存储卷:     │
│   data/dev/workspace    │    │   data/test/workspace   │    │   data/main/workspace   │
│   data/dev/conversations│    │   data/test/conversations    data/main/conversations│
│   dev-system-pgdata     │    │   test-system-pgdata    │    │   main-system-pgdata    │
│ • 应用服务端口:         │    │ • 应用服务端口:         │    │ • 应用服务端口:         │
│   HTTP: 8080            │    │   HTTP: 8081            │    │   HTTP: 8000 (生产)     │
│   Agent-Runner: 18765   │    │   Agent-Runner: 18766   │    │   Agent-Runner: 18767   │
│ • 独立日志/SQLite:      │    │ • 独立日志/SQLite:      │    │ • 独立日志/SQLite:      │
│   dev-aux-data          │    │   test-aux-data         │    │   main-aux-data         │
└─────────────────────────┘    └─────────────────────────┘    └─────────────────────────┘

1. 知识库共享规则 (Shared Knowledge Base)

• 共享内容：法规条文、行业政策、静态向量索引、规章库、系统公共知识文档。
• 访问控制：
  • 所有分支服务通过专用的 POSTGRES_SHARED_KB_DSN 连接同一个共享知识库容器（如 shuimu-kb-shared）。
  • 开发、测试与主分支服务在检索知识时，只读访问公共条目。
  • 知识库的结构升级或新增全量知识，统一由知识库迁移脚本维护，并提前通过版本兼容性测试。

2. 对话数据与业务数据库隔离规则 (Strict Data Isolation)

• 隔离内容：
  1. 对话上下文与历史记录 (Chat History & Sessions)：包括用户聊天记录、Agent 规划轨迹、思考日志等。
  2. 业务数据库 (System DB)：系统用户表、权限、配置状态、任务状态、审计表。
  3. 外发信箱与日志 (Outbox & SQLite & Temp Logs)。
  4. 工作区目录 (Workspaces & Cache)。
• 隔离实现机制：
  • Docker 容器名隔离：通过 COMPOSE_PROJECT_NAME 前缀 (agent-dev, agent-test, agent-main)，服务容器互不覆盖。
  • 网络与端口隔离：每个环境占用独立的宿主机端口映射（详见下表），互不冲突，支持在同一台机器或多台机器并存启动。
  • 存储卷隔离：Docker Named Volume 或宿主机本地目录均以环境后缀命名，严禁多环境挂载同一会话或 DB 目录。

3. 环境配置矩阵表

配置项	共享知识库 (Shared)	开发环境 (Dev)	测试环境 (Test)	主分支生产环境 (Main)
Compose 项目名	agent-infra	agent-dev	agent-test	agent-main
配置文件	configs/.env.shared	configs/.env.dev	configs/.env.test	configs/.env.main
系统 DB 名称	regulations (KB)	agent_system_dev	agent_system_test	agent_system_main
系统 DB 宿主端口	5432	5433	5434	5435
App 业务 HTTP 端口	-	8080	8081	8000
Agent Runner 端口	-	18765	18766	18767
持久化数据目录	data/shared/kb	data/dev/	data/test/	data/main/
系统 DB 数据卷	kb-shared-pgdata	dev-system-pgdata	test-system-pgdata	main-system-pgdata
审计/会话 SQLite	-	dev-aux-data	test-aux-data	main-aux-data

---

四、 常用运维操作与脚本使用

项目在 scripts/ 目录下提供了标准运维与管理脚本：

1. 服务启停操作

# 1. 启动共享知识库基础服务 (首次运行前必须启动)
./scripts/env-service.sh shared start

# 2. 启动开发环境服务
./scripts/env-service.sh dev start

# 3. 启动测试环境服务
./scripts/env-service.sh test start

# 4. 启动主分支生产环境服务
./scripts/env-service.sh main start

# 5. 查看所有环境运行状态
./scripts/env-service.sh all status

# 6. 停止指定环境服务 (如停止 dev)
./scripts/env-service.sh dev stop

2. 分支流转标准流程示范

流程 A：日常功能开发与逐步提交

# 切换并同步开发分支
git checkout dev
git pull origin dev

# 若功能较独立，创建功能子分支
git checkout -b feature/auth-multi-tenant

# 功能拆分阶段 1：数据表与存储层
git add internal/db/migrations/
git commit -m "feat(db): 增加多租户隔离与字段迁移"

# 功能拆分阶段 2：服务实现与路由
git add internal/services/
git commit -m "feat(auth): 实现多租户鉴权中间件与上下文传递"

# 功能拆分阶段 3：测试用例
git add internal/auth/auth_test.go
git commit -m "test(auth): 补充多租户鉴权单元与集成测试"

# 自测通过后，合并回 dev
git checkout dev
git merge --no-ff feature/auth-multi-tenant -m "merge: 合并功能 feature/auth-multi-tenant 到开发分支"
git branch -d feature/auth-multi-tenant

流程 B：功能阶段积累完成，进入测试分支实测

# 切换到测试分支
git checkout test
git pull origin test

# 将 dev 分支当前稳定节点合并到 test
git merge --no-ff dev -m "release-candidate: 合并 dev 阶段功能至 test 分支进行长期实测"

# 打上实测候选版本 Tag
git tag -a rc-v1.2.0-beta.1 -m "构建 1.2.0 测试候选版本 1，启动长期实测"

# 启动或重启 test 环境服务进行运维实测
./scripts/env-service.sh test restart

流程 C：测试分支验证完成，发布到主分支

# 切换到主分支
git checkout main
git pull origin main

# 将测试验证完毕的节点合并到 main
git merge --no-ff test -m "release: 经长期测试与运维验证，发布版本 1.2.0"

# 打正式版本 Tag
git tag -a v1.2.0 -m "Release v1.2.0"

# 部署/更新主分支生产服务
./scripts/env-service.sh main restart