weichenandCursor
f30886e442
Align AGENTS, Cursor rule, PROJECT, README, templates, and CURRENT with strategy A: no direct commits on dev/test/main; all work branches from dev. Co-authored-by: Cursor <cursoragent@cursor.com>
77 lines
4.2 KiB
Markdown
77 lines
4.2 KiB
Markdown
# Chat-Agent-System (项目工作流与对话智能体系统)
|
||
|
||
本项目是一个面向企业与团队的高可用对话智能体（Chat Agent）系统，结合了知识库检索增强（RAG）、自动化 Agent 执行能力与安全审计机制。
|
||
|
||
> **Agent / 协作者必读**：[AGENTS.md](./AGENTS.md) → [PROJECT.md](./PROJECT.md) → [.doc/README.md](./.doc/README.md) → [.doc/ops/CURRENT.md](./.doc/ops/CURRENT.md)
|
||
|
||
---
|
||
|
||
## 一、 仓库三分支结构说明
|
||
|
||
根据系统架构与运维稳定性规范，本仓库固定维护三个分支：
|
||
|
||
| 分支名 | 定位 | 职责与准入规则 |
|
||
| :--- | :--- | :--- |
|
||
| **`dev`** | **开发合入基线** | 禁止直接 commit。从最新 `dev` 开 `feature/*` 或 `fix/*` 开发，自测后占集成槽位 `--no-ff` 合回 `dev`。 |
|
||
| **`test`** | **测试分支** | 准生产实测；`dev` 阶段合并 + rc tag。**严禁**在此分支开发或 commit。 |
|
||
| **`main`** | **主分支** | 生产发布；仅 `test` 验证通过后合并。**严禁**直接开发或 commit。 |
|
||
|
||
完整的分支流转模型、热修复流程与提交规范请参阅：[PROJECT.md](./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` 中提供了统一的环境管理工具：
|
||
|
||
```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(...): ...`)：环境配置与说明文档。
|