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。
二、 三套服务环境架构（知识库共享 + 对话与数据隔离）
本系统为 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 中提供了统一的环境管理工具：
# 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
四、 开发任务拆分与逐步提交规范
进行功能研发时，遵循**“按功能层次拆分，过程逐步提交”**原则：
- 数据模型层 (
feat(db): ...)：数据表迁移、字段变更、实体定义。 - 业务逻辑层 (
feat(agent): ...)：核心 Agent 能力、工作流处理。 - 接口服务层 (
feat(api): ...)：HTTP/Web 路由及交互。 - 自动化测试 (
test(...): ...)：单元测试与联调集成测试。 - 文档与配置 (
docs(...): .../chore(...): ...)：环境配置与说明文档。