Chat-Agent-System (项目工作流与对话智能体系统)

本项目是一个面向企业与团队的高可用对话智能体（Chat Agent）系统，结合了知识库检索增强（RAG）、自动化 Agent 执行能力与安全审计机制。

Agent / 协作者必读：AGENTS.md → PROJECT.md → .doc/README.md → .doc/ops/CURRENT.md

---

一、 仓库三分支结构说明

根据系统架构与运维稳定性规范，本仓库固定维护三个分支：

分支名	定位	职责与准入规则
dev	开发合入基线	禁止直接 commit。从最新 dev 开 feature/* 或 fix/* 开发，自测后占集成槽位 --no-ff 合回 dev。
test	测试分支	准生产实测；dev 阶段合并 + rc tag。严禁在此分支开发或 commit。
main	主分支	生产发布；仅 test 验证通过后合并。严禁直接开发或 commit。

完整的分支流转模型、热修复流程与提交规范请参阅：PROJECT.md §4（SSOT）。

---

二、 三套服务环境架构（知识库共享 + 对话与数据隔离）

本系统为 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

---

四、 开发任务拆分与逐步提交规范

进行功能研发时，遵循**“按功能层次拆分，过程逐步提交”**原则：

1. 数据模型层 (feat(db): ...)：数据表迁移、字段变更、实体定义。
2. 业务逻辑层 (feat(agent): ...)：核心 Agent 能力、工作流处理。
3. 接口服务层 (feat(api): ...)：HTTP/Web 路由及交互。
4. 自动化测试 (test(...): ...)：单元测试与联调集成测试。
5. 文档与配置 (docs(...): ... / chore(...): ...)：环境配置与说明文档。