基于 Wagtail CMS 的企业资料智能管理与问答系统 [![Python](https://img.shields.io/badge/Python-3.14-blue.svg)](https://www.python.org/) [![Django](https://img.shields.io/badge/Django-5.2-green.svg)](https://www.djangoproject.com/) [![Wagtail](https://img.shields.io/badge/Wagtail-8.1a0-teal.svg)](https://wagtail.org/) [![Docker](https://img.shields.io/badge/Docker-Compose-blue.svg)](https://docs.docker.com/compose/) ## 项目简介 CMS 企业资料问答系统是一个基于 Wagtail CMS 二次开发的企业级文档管理与智能问答平台。系统提供资料上传、解析、分类、关联、审核、发布的全流程管理能力，并结合 AI 智能体实现自动化资料处理与智能问答服务。 ### 核心特性 - **资料全生命周期管理**：支持 PDF、Office 等多种格式资料的上传、解析、分类与归档 - **AI 智能处理**：集成大语言模型实现资料自动分类、关键信息提取、智能关联推荐 - **产品资料包管理**：按产品/SKU 维度组织资料，支持地区化内容配置 - **法规库管理**：法规版本控制、条款管理、合规性校验 - **工作流引擎**：可配置的多级审核流程，支持草稿、审核、发布状态管理 - **智能问答**：基于向量检索的语义搜索，支持多轮对话式问答 - **权限控制**：基于角色的细粒度权限管理，支持数据范围授权 - **多地区支持**：支持多语言、多地区的内容管理与发布 ## 系统架构 ### 技术栈 | 层级 | 技术 | |------|------| | 后端框架 | Django 5.2 + Wagtail 8.1a0 | | 数据库 | PostgreSQL 16 + pgvector | | 对象存储 | MinIO (S3 兼容) | | 前端 | React + TypeScript + Tailwind CSS | | 任务队列 | Django Celery | | 容器化 | Docker + Docker Compose | | 包管理 | uv (Python) + npm (Node.js) | ### 模块架构 ``` cms-agent-wagtail-dev/ ├── cms/ # 二开业务模块 │ ├── core/ # 核心模块：资源、地区、品类、权限 │ ├── agents/ # 智能体模块：模型配置、任务编排、运行管理 │ ├── materials/ # 资料模块：原件管理、解析、分类、确认 │ ├── catalog/ # 产品目录：产品、SKU、事实集、资料包 │ ├── regulations/ # 法规模块：法规、版本、条款 │ ├── governance/ # 治理模块：内容审核、规则校验、发布 │ ├── retrieval/ # 检索模块：分块、索引、向量检索 │ ├── workbench/ # 工作台：待办、通知、偏好 │ └── api/ # API 层：DTO、端点、校验 ├── client/ # 前端应用 │ ── src/ │ ├── components/ # React 组件 │ ├── api/ # API 客户端 │ └── entrypoints/ # 入口文件 ── wagtail/ # Wagtail 核心 └── docker-compose.cms.yml # Docker 编排配置 ``` ## 快速开始 ### 环境要求 - Docker 24+ 与 Docker Compose v2 - 8GB+ 内存（推荐 16GB） - 50GB+ 磁盘空间 ### 部署步骤 #### 1. 克隆项目 ```bash git clone cd cms-agent-wagtail-dev ``` #### 2. 配置环境变量 ```bash # 复制环境配置模板 cp .env.cms.example .env.cms.local cp .env.cms.example .env # 编辑配置文件，填入实际凭证 # .env.cms.local - 运行时环境变量 # .env - Docker Compose 变量插值 ``` 关键配置项： ```bash # 数据库配置 CMS_DATABASE_NAME=cms_agent_backend_dev CMS_DATABASE_USER=cms_agent_dev CMS_DATABASE_PASSWORD= CMS_DATABASE_HOST=127.0.0.1 CMS_DATABASE_PORT=5432 # S3 存储配置（MinIO） CMS_USE_S3=1 CMS_S3_ENDPOINT=http://127.0.0.1:9002 CMS_S3_ACCESS_KEY= CMS_S3_SECRET_KEY= CMS_S3_BUCKET=cms-materials # 管理员账号 CMS_BOOTSTRAP_USERNAME=admin CMS_BOOTSTRAP_PASSWORD= CMS_BOOTSTRAP_EMAIL=admin@example.test # 模型加密密钥（使用 Fernet.generate_key() 生成） CMS_MODEL_ENCRYPTION_KEY= ``` #### 3. 构建并启动服务 ```bash # 构建镜像 docker compose -f docker-compose.cms.yml build # 启动服务 docker compose -f docker-compose.cms.yml up -d # 查看服务状态 docker compose -f docker-compose.cms.yml ps ``` #### 4. 初始化数据库 ```bash # 执行数据库迁移 docker exec -it cms-agent-wagtail-dev-web-1 python wagtail/test/manage.py migrate # 创建缓存表 docker exec -it cms-agent-wagtail-dev-web-1 python wagtail/test/manage.py createcachetable # 创建超级用户（如未自动创建） docker exec -it cms-agent-wagtail-dev-web-1 python wagtail/test/manage.py shell -c " from django.contrib.auth import get_user_model User = get_user_model() if not User.objects.filter(username='admin').exists(): User.objects.create_superuser('admin', 'admin@example.test', 'admin123456') " ``` #### 5. 创建 MinIO 存储桶 ```bash # 安装 MinIO 客户端 # macOS: brew install minio/stable/mc # Linux: wget https://dl.min.io/client/mc/release/linux-amd64/mc && chmod +x mc # 配置 MinIO 客户端 mc alias set local http://127.0.0.1:9002 # 创建存储桶 mc mb local/cms-materials --ignore-existing ``` #### 6. 访问系统 - **管理后台**: http://127.0.0.1:8001/admin/ - **API 文档**: http://127.0.0.1:8001/admin/workspace/api/v1/health/ 默认管理员账号：`admin` / `admin123456`（请在首次登录后修改密码） ## 模块界面预览 > 以下截图来自生产环境实际运行界面。系统采用自定义工作空间 UI，顶部 Tab 导航覆盖五大功能模块。 ### 登录页面系统登录界面，使用账号密码认证登录后进入工作空间。 ![登录页面](docs/screenshots/01-login.png) ### 工作台登录后的默认页面，展示系统运行概览和关键指标统计，包括资料处理状态、Agent 运行情况、待办事项数量等核心数据。 ![工作台概览](docs/screenshots/02-dashboard.png) #### 待办中心工作台内置待办中心，汇总展示当前用户需要处理的待办事项，支持按类型筛选和快速跳转。 ![待办中心](docs/screenshots/13-todo-center.png) ### 资料中心企业资料管理核心页面，支持资料上传、解析状态跟踪、分类确认和全文检索。每条资料展示解析状态、分类结果、关联产品和确认进度。 ![资料中心](docs/screenshots/03-materials-center.png) ### 地区内容工作台按地区维度管理产品内容的工作台。支持按地区、品类和内容类型（产品详情 / 平台 Listing / FAQ）筛选，展示内容生成状态、审核进度和发布状态。 ![地区内容工作台](docs/screenshots/04-regional-content.png) ### Agent 运行记录展示 AI 智能体的所有运行任务记录，包括运行状态（运行中 / 已完成 / 失败 / 已取消）、任务类型、触发时间和耗时。支持查看详情、暂停、恢复、取消和重试操作。 ![Agent 运行记录](docs/screenshots/05-agent-runs.png) ### 设置系统设置页面整合了账号权限、AI 配置和内容规则管理，包含以下七个子模块： #### 账号管理管理系统用户账号，支持创建账号、分配身份、设置负责地区范围和启用/禁用状态。同一账号可兼任多个身份。 ![账号管理](docs/screenshots/06-settings-account-management.png) #### 身份管理定义系统角色身份（内容人员、查看人员、法务、资料人员、超级管理员），每个身份配置可查看的内容范围和权限。支持自定义身份和细粒度权限控制。 ![身份管理](docs/screenshots/06-settings-identity-management.png) #### 模型配置配置 AI 模型供应商和参数，支持对话模型、视觉模型和向量模型的 API 密钥、模型名称和调用参数设置。密钥采用 Fernet 加密存储。 ![模型配置](docs/screenshots/07-model-configuration.png) #### 提示词管理管理 AI 智能体使用的系统提示词、任务提示词和评估提示词模板，支持版本控制和提示词调优。 ![提示词管理](docs/screenshots/08-prompt-configuration.png) #### 字段确认规则配置资料解析过程中需要人工确认的字段规则，定义哪些提取字段需要人工复核以及确认条件。 ![字段确认规则](docs/screenshots/09-field-confirmation-rules.png) #### 评测报告查看 AI 模型和内容生成的质量评测报告，支持按模型、任务类型和时间范围筛选分析结果。 ![评测报告](docs/screenshots/10-evaluation-reports.png) #### 规则集管理为地区、品类和内容类型配置内容生成与发布前的确定性检查条件。当前已配置 108 个规则集，覆盖 18 个地区 × 2 个品类 × 3 种内容类型。每条规则支持设置严重级别（阻断 / 警告 / 提示）。 ![规则集管理](docs/screenshots/11-rule-set-management.png) ## API 接口预览系统提供 RESTful API 接口，位于 `/admin/workspace/api/v1/` 路径下。 ### 健康检查 ```bash GET /admin/workspace/api/v1/health/ ``` ![健康检查 API](docs/screenshots/25-health-api.png) ### 运行概览 ```bash GET /admin/workspace/api/v1/runtime-overview/ ``` ![运行概览 API](docs/screenshots/24-runtime-overview-api.png) ### 资料管理 ```bash GET /admin/workspace/api/v1/materials/ # 资料列表 POST /admin/workspace/api/v1/materials/ # 创建资料 GET /admin/workspace/api/v1/materials// # 资料详情 GET /admin/workspace/api/v1/materials//original/ # 原始文件 GET /admin/workspace/api/v1/materials//preview-page/# 预览页 POST /admin/workspace/api/v1/materials//reparse/ # 重新解析 ``` ![资料管理 API](docs/screenshots/13-materials-api.png) ### 产品目录 ```bash GET /admin/workspace/api/v1/products/ # 产品列表 POST /admin/workspace/api/v1/products/ # 创建产品 GET /admin/workspace/api/v1/products// # 产品详情 POST /admin/workspace/api/v1/products//structures//activate/ # 激活版本 ``` ![产品目录 API](docs/screenshots/14-products-api.png) ### 法规库 ```bash GET /admin/workspace/api/v1/regulations/ # 法规列表 POST /admin/workspace/api/v1/regulations/ # 创建法规 GET /admin/workspace/api/v1/regulations// # 法规详情 GET /admin/workspace/api/v1/regulations/options/ # 法规选项 POST /admin/workspace/api/v1/regulations//versions//confirm/ # 确认版本 ``` ![法规库 API](docs/screenshots/15-regulations-api.png) ### 智能体运行 ```bash GET /admin/workspace/api/v1/agent-runs/ # 运行列表 POST /admin/workspace/api/v1/agent-runs/ # 创建运行 GET /admin/workspace/api/v1/agent-runs// # 运行详情 GET /admin/workspace/api/v1/agent-runs//events/ # 运行事件 POST /admin/workspace/api/v1/agent-runs//cancel/ # 取消运行 POST /admin/workspace/api/v1/agent-runs//pause/ # 暂停运行 POST /admin/workspace/api/v1/agent-runs//resume/ # 恢复运行 POST /admin/workspace/api/v1/agent-runs//retry/ # 重试运行 ``` ![智能体运行 API](docs/screenshots/16-agent-runs-api.png) ### 工作台 ```bash GET /admin/workspace/api/v1/work-items/ # 待办事项 POST /admin/workspace/api/v1/work-items//complete/ # 完成待办 ``` ![工作台 API](docs/screenshots/17-work-items-api.png) ### 语义搜索 ```bash GET /admin/workspace/api/v1/search/?q= # 语义搜索 ``` ![语义搜索 API](docs/screenshots/18-search-api.png) ### 区域内容 ```bash GET /admin/workspace/api/v1/regional-contents/ # 区域内容列表 POST /admin/workspace/api/v1/regional-contents/ # 创建区域内容 GET /admin/workspace/api/v1/regional-contents// # 区域内容详情 POST /admin/workspace/api/v1/regional-contents//validate/ # 校验内容 POST /admin/workspace/api/v1/regional-contents//draft/ # 保存草稿 POST /admin/workspace/api/v1/regional-contents//submit-review/ # 提交审核 POST /admin/workspace/api/v1/regional-contents//approve-review/ # 通过审核 POST /admin/workspace/api/v1/regional-contents//reject-review/ # 拒绝审核 POST /admin/workspace/api/v1/regional-contents//publish/ # 发布内容 ``` ![区域内容 API](docs/screenshots/19-regional-contents-api.png) ### 规则集 ```bash GET /admin/workspace/api/v1/rules/ # 规则集列表 POST /admin/workspace/api/v1/rules/ # 创建规则集 POST /admin/workspace/api/v1/rules/

/versions//activate/ # 激活版本
```

![规则集 API](docs/screenshots/20-rules-api.png)

### 账户管理

```bash
GET    /admin/workspace/api/v1/account/management/           # 账户管理
GET    /admin/workspace/api/v1/account/scope/                # 当前范围
```

![账户管理 API](docs/screenshots/21-account-management-api.png)

### 智能体配置

```bash
GET    /admin/workspace/api/v1/agent-configuration/          # 智能体配置
```

![智能体配置 API](docs/screenshots/22-agent-configuration-api.png)

### 审核工作流

```bash
GET    /admin/workspace/api/v1/review-workflows/             # 审核工作流
```

![审核工作流 API](docs/screenshots/23-review-workflows-api.png)

## 核心模块说明

### core - 核心模块

负责基础资源管理、地区配置、品类定义和范围授权。

- **Resource**: 资源基础模型，所有业务实体的父类
- **Region**: 地区配置，支持多地区内容管理
- **Category**: 品类分类，用于资料和产品的分类体系
- **Scope**: 范围授权，控制用户可访问的数据范围

### agents - 智能体模块

管理 AI 智能体的配置、任务编排和运行生命周期。

- **ModelConfiguration**: 模型配置，管理对话、视觉、向量模型的供应商和参数
- **PromptConfiguration**: 提示词配置，管理系统提示词和任务提示词
- **AgentRun**: 智能体运行记录，跟踪每次任务执行
- **AgentEvent**: 运行事件，记录执行过程中的关键节点

### materials - 资料模块

管理企业资料的完整生命周期，从上传到归档。

- **SourceDocument**: 资料原件，继承 Wagtail Document
- **UploadBatch**: 上传批次，支持批量上传和幂等确认
- **Material**: 资料主体，记录分类、标签和确认状态
- **EvidenceSpan**: 证据片段，记录 AI 提取的关键信息
- **ExtractionCandidate**: 提取候选，待人工确认的 AI 提取结果

### catalog - 产品目录模块

管理产品信息和资料关联。

- **Product**: 产品主体，支持多版本结构
- **SKU**: 产品变体，管理具体规格
- **FactSet**: 事实集，记录产品关键属性
- **Dossier**: 资料包，按地区组织的产品资料集合

### regulations - 法规模块

管理法规文档和版本控制。

- **Regulation**: 法规主体，支持多版本管理
- **RegulationVersion**: 法规版本，记录版本变更历史
- **Clause**: 法规条款，支持条款级别的引用和关联

### governance - 治理模块

负责内容审核、规则校验和发布管理。

- **RegionalContent**: 区域内容，支持多地区内容版本
- **ReviewWorkflow**: 审核工作流，定义多级审核流程
- **ValidationRule**: 校验规则，定义内容合规性检查
- **Publication**: 发布记录，跟踪内容发布状态

### retrieval - 检索模块

提供语义搜索和向量检索能力。

- **SearchChunk**: 搜索分块，文档的语义分块
- **IndexJob**: 索引任务，管理向量索引的构建和更新

### workbench - 工作台模块

提供用户工作台和通知管理。

- **WorkItem**: 待办事项，跟踪用户待处理任务
- **Notification**: 系统通知，推送重要事件通知
- **Preference**: 用户偏好，保存个性化设置

## 开发指南

### 本地开发环境

```bash
# 安装 Python 依赖
uv sync --extra cms

# 安装 Node.js 依赖
npm ci

# 运行数据库迁移
python wagtail/test/manage.py migrate

# 创建缓存表
python wagtail/test/manage.py createcachetable

# 启动开发服务器
python wagtail/test/manage.py runserver

# 启动前端开发服务器（热重载）
npm run dev
```

### 运行测试

```bash
# 运行所有测试
python runtests.py

# 运行特定模块测试
python runtests.py cms.materials
python runtests.py cms.agents

# 运行前端测试
npm test
```

### 代码规范

- Python: 使用 Ruff 进行代码检查和格式化
- TypeScript: 使用 ESLint + Prettier
- CSS: 使用 Stylelint

```bash
# Python 代码检查
ruff check cms/
ruff format cms/

# TypeScript 代码检查
npm run lint
npm run format
```

### 数据库迁移

```bash
# 创建迁移文件
python wagtail/test/manage.py makemigrations cms.materials

# 应用迁移
python wagtail/test/manage.py migrate

# 查看迁移状态
python wagtail/test/manage.py showmigrations
```

## 配置说明

### 环境变量

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `CMS_DATABASE_NAME` | 数据库名称 | `cms_agent_backend_dev` |
| `CMS_DATABASE_USER` | 数据库用户 | `cms_agent_dev` |
| `CMS_DATABASE_PASSWORD` | 数据库密码 | - |
| `CMS_DATABASE_HOST` | 数据库主机 | `127.0.0.1` |
| `CMS_DATABASE_PORT` | 数据库端口 | `5432` |
| `CMS_USE_S3` | 是否启用 S3 存储 | `0` |
| `CMS_S3_ENDPOINT` | S3 端点 | - |
| `CMS_S3_ACCESS_KEY` | S3 访问密钥 | - |
| `CMS_S3_SECRET_KEY` | S3 密钥 | - |
| `CMS_S3_BUCKET` | S3 存储桶 | `cms-materials` |
| `CMS_AGENT_LOCAL_MODE` | 本地开发模式 | `1` |
| `CMS_MODEL_ENCRYPTION_KEY` | 模型密钥加密主密钥 | - |
| `CMS_VISION_OCR_MAX_PAGES` | OCR 最大页数 | `20` |
| `CMS_WEB_PORT` | Web 服务端口 | `8001` |

### Django 设置

主要配置文件位于 `wagtail/test/settings_cms.py`：

- 数据库配置：PostgreSQL + pgvector
- 缓存配置：数据库缓存
- 存储配置：本地存储或 S3
- 应用配置：CMS 业务模块 + Wagtail 核心模块

## 部署说明

### 生产环境部署

```bash
# 构建生产镜像
docker compose -f docker-compose.cms.yml build

# 启动生产服务
docker compose -f docker-compose.cms.yml up -d

# 执行数据库迁移
docker exec -it cms-agent-wagtail-dev-web-1 python wagtail/test/manage.py migrate

# 收集静态文件
docker exec -it cms-agent-wagtail-dev-web-1 python wagtail/test/manage.py collectstatic --noinput

# 创建缓存表
docker exec -it cms-agent-wagtail-dev-web-1 python wagtail/test/manage.py createcachetable
```

### 服务组件

| 服务 | 说明 | 端口 |
|------|------|------|
| postgres | PostgreSQL 16 + pgvector | 5432 |
| minio | MinIO 对象存储 | 9002 (API), 9001 (Console) |
| web | Web 应用服务器 | 8001 |
| worker | Celery 任务队列 worker | - |
| embeddings-worker | 向量嵌入 worker | - |

### 备份策略

```bash
# 数据库备份
docker exec cms-agent-wagtail-dev-postgres-1 pg_dump -U cms_agent_dev cms_agent_backend_dev > backup.sql

# 恢复数据库
docker exec -i cms-agent-wagtail-dev-postgres-1 psql -U cms_agent_dev cms_agent_backend_dev < backup.sql

# MinIO 存储桶备份
mc mirror local/cms-materials ./backup/minio/
```

## 常见问题

### Q: 如何重置管理员密码？

```bash
docker exec -it cms-agent-wagtail-dev-web-1 python wagtail/test/manage.py shell -c "
from django.contrib.auth import get_user_model
User = get_user_model()
user = User.objects.get(username='admin')
user.set_password('new_password')
user.save()
"
```

### Q: 如何添加新的 API 端点？

1. 在 `cms/api/views.py` 中添加视图函数
2. 在 `cms/api/urls.py` 中注册 URL 路由
3. 编写对应的测试用例

### Q: 如何配置新的 AI 模型供应商？

1. 访问管理后台的"模型配置"页面
2. 添加新的模型配置，选择供应商类型
3. 填入 API 密钥和模型参数
4. 保存并测试连接

### Q: 数据库缓存表缺失怎么办？

```bash
docker exec -it cms-agent-wagtail-dev-web-1 python wagtail/test/manage.py createcachetable
```

### Q: MinIO 存储桶不存在怎么办？

```bash
mc mb local/cms-materials --ignore-existing
```

## 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码规范

- 遵循 PEP 8 (Python) 和 ESLint 配置 (TypeScript)
- 编写单元测试覆盖新功能
- 更新相关文档
- 提交信息遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范

## 许可证

本项目基于 BSD 3-Clause 许可证开源。详见 [LICENSE](LICENSE) 文件。

## 联系方式

- 项目维护者：[维护者邮箱]
- 问题反馈：[Issues 页面]
- 功能建议：[Discussions 页面]

## 致谢

- [Wagtail CMS](https://wagtail.org/) - 内容管理框架
- [Django](https://www.djangoproject.com/) - Web 框架
- [pgvector](https://github.com/pgvector/pgvector) - 向量数据库扩展
- [MinIO](https://min.io/) - 对象存储