From d27b0ad5ad19648d8e997182cd3320cc5bc6b4b7 Mon Sep 17 00:00:00 2001 From: WeiCHEN Date: Mon, 7 Sep 2026 15:56:53 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=BB=BA=E7=AB=8B=E4=BB=93=E5=BA=93?= =?UTF-8?q?=E5=9F=BA=E7=A1=80=E6=9E=B6=E6=9E=84=E3=80=81=E4=B8=89=E5=88=86?= =?UTF-8?q?=E6=94=AF=E8=A7=84=E8=8C=83=E4=B8=8E=E7=8E=AF=E5=A2=83=E8=BF=90?= =?UTF-8?q?=E8=A1=8C=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Cursor --- .gitignore | 53 ++++ README.md | 74 ++++++ docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md | 250 ++++++++++++++++++ 3 files changed, 377 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..40d8e464 --- /dev/null +++ b/.gitignore @@ -0,0 +1,53 @@ +# Operating System Files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# Reference materials & heavy upstream copies (3GB+) +.refs/ + +# Environment Variables & Local Overrides (Keep examples tracked) +*.env +*.env.* +!*.env.example +!configs/*.env.*.example +!configs/*.env.example + +# Runtime Data, Logs, and Databases +data/ +logs/ +*.log +*.sqlite +*.sqlite3 +*.db +*.db-journal +*.db-wal + +# Workspaces & Cache +workspaces/ +.cache/ +tmp/ +temp/ + +# IDE / Editor Files +.idea/ +.vscode/ +*.swp +*.swo +*~ +# Note: Keep .cursor/rules tracked for team/project rules +.cursor/* +!.cursor/rules/ +!.cursor/rules/** + +# Build artifacts & Binaries +dist/ +build/ +bin/ +*.exe +*.o +*.a diff --git a/README.md b/README.md new file mode 100644 index 00000000..b3965c3d --- /dev/null +++ b/README.md @@ -0,0 +1,74 @@ +# Chat-Agent-System (项目工作流与对话智能体系统) + +本项目是一个面向企业与团队的高可用对话智能体（Chat Agent）系统，结合了知识库检索增强（RAG）、自动化 Agent 执行能力与安全审计机制。 + +--- + +## 一、 仓库三分支结构说明 + +根据系统架构与运维稳定性规范，本仓库固定维护三个分支： + +| 分支名 | 定位 | 职责与准入规则 | +| :--- | :--- | :--- | +| **`dev`** | **开发分支** | **日常开发基线**。所有代码开发均在此分支或其衍生子分支（`feature/*`, `fix/*`）进行，子分支自测后合并回 `dev`。支持一个任务按功能拆解并逐步渐进式提交。 | +| **`test`** | **测试分支** | **准生产实测分支**。当 `dev` 积累了一定功能阶段后合并至此，建立发布候选节点（`rc-vX.Y.Z`），进行真实环境部署与长期集成测试与运维检验。 | +| **`main`** | **主分支** | **生产发布分支**。严禁直接提交。仅在 `test` 分支经过真实运维和测试验证达到发布标准后，将对应节点合并回 `main` 并打正式版本 Tag（`vX.Y.Z`）。 | + +完整的分支流转模型、热修复流程与提交规范请参阅：[docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md](docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md)。 + +--- + +## 二、 三套服务环境架构（知识库共享 + 对话与数据隔离） + +本系统为 `dev`、`test`、`main` 三个分支各提供了一套独立运行的服务环境： + +``` + [ 共享基础设施: 知识库服务 (pgvector / regulations-db) ] + │ (共享知识库索引) + ┌──────────────────────┼──────────────────────┐ + ▼ ▼ ▼ +┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ +│ 开发环境 (dev) │ │ 测试环境 (test) │ │ 生产环境 (main) │ +├──────────────────┤ ├──────────────────┤ ├──────────────────┤ +│ 容器组:agent-dev │ │ 容器组:agent-test│ │ 容器组:agent-main│ +│ HTTP: 8080 │ │ HTTP: 8081 │ │ HTTP: 8000 │ +│ DB: 5433 (独占) │ │ DB: 5434 (独占) │ │ DB: 5435 (独占) │ +│ 独占对话记录/卷 │ │ 独占对话记录/卷 │ │ 独占对话记录/卷 │ +└──────────────────┘ └──────────────────┘ └──────────────────┘ +``` + +- **知识库共享**：三套环境均可连接同一个知识库向量检索服务，确保专业法规与企业标准数据集中维护、保持一致。 +- **对话与数据库严格隔离**：各环境拥有独立的数据库实例/库、独立的会话记录、独立的审计日志与工作区持久化卷，互不污染。 + +--- + +## 三、 快速启动与运维指南 + +项目在 `scripts/env-service.sh` 中提供了统一的环境管理工具： + +```bash +# 1. 启动共享知识库服务 (首次使用前启动) +./scripts/env-service.sh shared start + +# 2. 启动对应环境服务 +./scripts/env-service.sh dev start # 启动开发环境 (端口: 8080, DB: 5433) +./scripts/env-service.sh test start # 启动测试环境 (端口: 8081, DB: 5434) +./scripts/env-service.sh main start # 启动主分支生产环境 (端口: 8000, DB: 5435) + +# 3. 检查环境状态 +./scripts/env-service.sh all status + +# 4. 停止指定环境服务 +./scripts/env-service.sh dev stop +``` + +--- + +## 四、 开发任务拆分与逐步提交规范 + +进行功能研发时，遵循**“按功能层次拆分，过程逐步提交”**原则： +1. **数据模型层** (`feat(db): ...`)：数据表迁移、字段变更、实体定义。 +2. **业务逻辑层** (`feat(agent): ...`)：核心 Agent 能力、工作流处理。 +3. **接口服务层** (`feat(api): ...`)：HTTP/Web 路由及交互。 +4. **自动化测试** (`test(...): ...`)：单元测试与联调集成测试。 +5. **文档与配置** (`docs(...): ...` / `chore(...): ...`)：环境配置与说明文档。 diff --git a/docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md b/docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md new file mode 100644 index 00000000..1bca88e0 --- /dev/null +++ b/docs/workflow/BRANCH_AND_ENVIRONMENT_RULES.md @@ -0,0 +1,250 @@ +# 研发分支与多套独立环境运行规范 (Branch & Environment Rules) + +本规范为本系统代码仓库的强制性规范，涵盖 **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/` 分支。 + - 修复完成并在专门隔离环境测试后，先合回 `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 消息规范： +```text +(): + +[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. 服务启停操作 +```bash +# 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：日常功能开发与逐步提交 +```bash +# 切换并同步开发分支 +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：功能阶段积累完成，进入测试分支实测 +```bash +# 切换到测试分支 +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：测试分支验证完成，发布到主分支 +```bash +# 切换到主分支 +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 +```