通信基站建设项目全流程进度管理多智能体系统

一、项目背景

1.0 技术栈

技术	版本	说明
Python	3.12+	编程语言
uv	0.10+	Python 包管理器（虚拟环境）
openai-agents	0.12.5	OpenAI Agents SDK，多智能体框架
openai	-	OpenAI API 客户端（兼容 DeepSeek）
pydantic	-	数据验证和设置管理
python-dotenv	1.2.2	环境变量管理
DeepSeek API	-	LLM 提供商（R1 推理模型、V3 对话模型）

虚拟环境管理（uv）：

bash 复制代码

# 创建虚拟环境
uv venv

# 安装依赖
uv pip install openai-agents python-dotenv pydantic

# 运行脚本
uv run python xxx.py

# 运行模块
uv run python -m module_name

API 配置（.env）：

bash 复制代码

API_KEY=your-api-key
BASE_URL=https://api.qnaigc.com/v1  # 或其他兼容 API 地址

1.1 企业已有系统

本系统实现通信基站建设项目全生命周期管理，涵盖需求承接、立项采购、项目实施、交付验收、结算关闭五大阶段，共4.6个关键步骤。

核心功能：

流程协同：支持多角色分步跟进，每个步骤完成后自动流转至下一责任人
时间管控：自动计算各环节完成时长，内置超时校验规则，实时预警滞后节点
权限分层：区县可填写进度，管理员可调整时间并记录修改原因
智能计算：自动生成交付最晚时间、各环节超时状态及总体扣分
凭证管理：支持上传交付凭证等附件

1.2 项目全流程阶段步骤

阶段	说明	步骤	需填写时间字段
需求承接	接收并确认客户需求	1.1 需求获取导入	订单导入时间
		1.2 选址协调	选址完成时间（改造）、地勘/检测完成时间
		1.3 订单编制及确认	订单编制完成时间
立项采购	项目立项与设备采购	2.1 立项设计	立项完成时间
		2.2 订单采购及物资领取	施工派单时间
项目实施	基站建设实施过程	3.1 开工准备	开工时间
		3.2 施工工序	塔基浇筑时间、杆塔安装时间、配套完成时间、电力完成时间
交付验收	交付并通过验收	4.1 交付	交付运营商时间
		4.2 开通	运营商开通时间
		4.3 区县签单	交付单区县提交时间
		4.4 市级	交付单市级完成签署时间
		4.5 线上内验	内部验收时间（线上）
		4.6 起租	起租时间
结算关闭	项目结算并关闭	5.1 项目结算	无需填写（系统自动计算扣分）

1.3 角色权限

角色	权限说明
设计	可更新 2.2 步骤之前的阶段（需求承接、立项采购）
监理	可更新 2.2 及之后的阶段（项目实施、交付验收）
管理员	可对整个阶段步骤更新调整用户填写的错误

1.4 项目基本信息字段

字段名称	是否可填写	说明
运营商标名称	必填	移动/电信/联通/广电
区县名称	必填	下拉选择本地区县
建设方式	必填	新建/改造/扩容/迁改
需求站址名称	必填	运营商提交的原始名称
打标	必填	存量改造/新建/其他
需求承接时间	可填	日期格式 YYYY-MM-DD
订单编号	有订单时填	运营商提供的正式订单号
年份	可填	如 2025
项目归属	必填	如 700M5.3期、DM5.3期
立项方式	可填	常规类塔/微站/室分
建设类型	可填	地面站/楼面站/室内分布
建设方案	可填	主要描述本次改造内容
铁塔站址编码	尽量不改	系统自动带出

二、系统工作流程

复制代码

用户输入： "帮我查询需求站址名称长沙星沙路口大谷二站点现在处于什么进度"
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│  规划智能体【系统管理器】（DeepSeek-R1，擅长推理规划）        │
│  分析用户输入并确定调用策略：                                │
│  - 意图识别：进度查询 / 进度更新 / 规则问答                   │
│  - 参数提取：站点名称/阶段名称/时间字段                       │
│  - 输出调用指令                                             │
└─────────────────────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│  分配智能体【服务管理器】（DeepSeek-V3，支持 Function Call）  │
│  接收指令并执行：                                           │
│  -> 根据指令类型调用对应工具函数                              │
│  -> 项目进度查询 / 项目进度更新 / 规则问答                    │
└─────────────────────────────────────────────────────────────┘
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│  处理智能体【多语言适配器】                                  │
│  根据处理模块返回结果：                                      │
│  - 项目进度查询 → 格式化输出进度信息                         │
│  - 项目进度更新 → 二次确认后更新                             │
│  - 规则问答 → 返回考核规则说明                               │
└─────────────────────────────────────────────────────────────┘
       │
       ▼
  返回处理结果（如需更新字段，提示用户确认）
       │
       ▼
  向用户返回处理结果

三、验收标准

3.1 功能边界

3.1.1 支持的用户操作

功能	输入示例	输出
项目进度查询	"CBN-长沙星沙路口大谷二-H5H 现在到什么进度了"	返回当前阶段、已完成步骤、下一步操作
项目进度更新	"帮我填写交付运营商的时间为 2025-03-15"	返回更新结果，需用户二次确认
基础信息更新	"更新建设类型为地面站"	返回更新结果，需用户二次确认
规则问答	"运营商开通时间考核是多少天"	返回考核规则说明

3.1.2 角色权限校验

操作	设计角色	监理角色	管理员
更新 2.2 之前阶段	✓	✗	✓
更新 2.2 及之后阶段	✗	✓	✓
更新基础信息	✗	✗	✓
查询所有项目	✓	✓	✓

3.1.3 异常输入处理

场景	处理方式
站点名称模糊匹配	返回匹配列表供用户选择
字段名称不识别	返回可填写字段清单
时间格式错误	提示正确格式（如 YYYY-MM-DD）
越权操作	返回权限不足提示

3.2 异常处理

3.2.1 数据异常

站点不存在：返回"未找到该项目，请检查站址名称"
字段不存在：返回"不支持的字段，可更新字段列表：xxx"
时间填写错误：返回具体错误原因和正确格式

3.2.2 权限异常

越权操作：返回"您无权操作此阶段，请联系对应角色"
角色未知：返回"无法识别您的角色，请联系管理员"

3.2.3 系统异常

API 调用失败：返回"系统繁忙，请稍后重试"
超时：返回"请求超时，请检查网络后重试"

3.3 日志要求

3.3.1 必记录日志

日志类型	记录内容	示例
用户输入日志	用户原始输入、时间、session_id	`[INFO] 2025-03-21 15:30:00 用户输入: "查询进度" session: xxx`
意图识别日志	识别的意图、提取的参数	`[INFO] 意图: 进度查询, 参数: {站点: "xxx"}`
工具调用日志	调用的函数、参数、返回值	`[INFO] 调用: query_progress, 参数: {站点: "xxx"}`
更新操作日志	更新字段、旧值、新值、操作人	`[INFO] 更新: 建设类型, 旧值: "楼面站", 新值: "地面站", 操作人: "admin"`
错误日志	错误类型、错误信息、堆栈	`[ERROR] 异常: KeyError, 消息: 站点不存在`

3.3.2 日志格式

python 复制代码

import logging
import json
from datetime import datetime

def log_user_input(user_input: str, session_id: str):
    """记录用户输入"""
    log_data = {
        "timestamp": datetime.now().isoformat(),
        "type": "user_input",
        "session_id": session_id,
        "content": user_input
    }
    logging.info(json.dumps(log_data))

def log_tool_call(tool_name: str, params: dict, result: str):
    """记录工具调用"""
    log_data = {
        "timestamp": datetime.now().isoformat(),
        "type": "tool_call",
        "tool": tool_name,
        "params": params,
        "result": result
    }
    logging.info(json.dumps(log_data))

四、最小闭环执行顺序

4.1 第一阶段：主流程跑通

步骤1：项目进度查询

复制代码

用户输入： "CBN-长沙星沙路口大谷二-H5H 现在到什么进度了"
       │
       ▼
[规划智能体] 分析意图 → 进度查询
       │
       ▼
[分配智能体] 调用 query_project_progress(站点名称)
       │
       ▼
[处理智能体] 格式化输出：
- 当前阶段：交付验收
- 已完成：4.1交付、4.2开通、4.3区县签单
- 待完成：4.4市级签署、4.5线上内验、4.6起租
- 累计时长：45天
- 是否超时：否
       │
       ▼
向用户返回结果

步骤2：规则问答

复制代码

用户输入： "运营商开通时间考核是多少天"
       │
       ▼
[规划智能体] 分析意图 → 规则问答
       │
       ▼
[分配智能体] 调用 get_rule_config(规则名称="开通时间考核")
       │
       ▼
[处理智能体] 返回：
- 考核天数：30天（从交付运营商时间起算）
- 超时扣分：每天扣0.5分
- 相关文件：见《项目考核管理办法》第5.2条
       │
       ▼
向用户返回结果

4.2 第二阶段：进度更新（需二次确认）

步骤3：进度更新-用户确认

复制代码

用户输入： "帮我填写交付运营商的时间为 2025-03-15"
       │
       ▼
[规划智能体] 分析意图 → 进度更新
       │
       ▼
[分配智能体] 调用 update_progress(站点名称, 阶段="4.1交付", 时间="2025-03-15")
       │
       ▼
[处理智能体] 生成确认信息：
══════════════════════════════
确认更新以下信息：
- 站点：CBN-长沙星沙路口大谷二-H5H
- 阶段：4.1 交付
- 字段：交付运营商时间
- 新值：2025-03-15
══════════════════════════════
请回复"确认"或"取消"
       │
       ▼
向用户返回确认信息（暂停，等待用户确认）

步骤4：进度更新-确认执行

复制代码

用户回复： "确认"
       │
       ▼
[分配智能体] 执行 update_progress
       │
       ▼
[处理智能体] 返回更新结果：
✓ 更新成功
- 站点：CBN-长沙星沙路口大谷二-H5H
- 阶段：4.1 交付 → 交付运营商时间: 2025-03-15
- 下一步：等待 4.2 开通
       │
       ▼
向用户返回结果

五、技术实现要求

5.1 项目结构

参考 multi_agent_coordinator（文件docs/multi_agent_coordinator.md）和 knowledge_agent（文件docs/knowledge_agent.md）的结构：

复制代码

project_coordinator/
├── __init__.py
├── config.py              # Agent 配置和初始化
├── models.py              # Pydantic 数据模型
├── workflow.py             # 工作流编排器（支持流式输出）
├── demo.py                # 演示脚本
├── claude.md              # 开发经验总结
├── agents/
│   ├── __init__.py
│   ├── planner.py         # 规划智能体 (deepseek-r1)
│   ├── dispatcher.py      # 分配智能体 (deepseek-v3)
│   └── handlers.py        # 处理智能体（查询/更新/问答）
└── tools/
    ├── __init__.py
    └── project_tools.py   # 项目进度查询/更新工具

5.2 核心实现

5.2.1 数据模型

python 复制代码

from pydantic import BaseModel, Field
from typing import Optional, List
from datetime import datetime
from enum import Enum

class UserRole(str, Enum):
    DESIGN = "design"      # 设计
    SUPERVISOR = "supervisor"  # 监理
    ADMIN = "admin"        # 管理员

class ProjectStage(str, Enum):
    DEMAND = "1"           # 需求承接
    PROCUREMENT = "2"     # 立项采购
    IMPLEMENTATION = "3"   # 项目实施
    ACCEPTANCE = "4"       # 交付验收
    SETTLEMENT = "5"       # 结算关闭

class ProgressQuery(BaseModel):
    """项目进度查询"""
    station_name: str = Field(..., description="需求站址名称")
    station_code: Optional[str] = Field(None, description="铁塔站址编码")

class ProgressUpdate(BaseModel):
    """项目进度更新"""
    station_name: str = Field(..., description="需求站址名称")
    stage: str = Field(..., description="阶段编号，如 4.1")
    field_name: str = Field(..., description="字段名称")
    field_value: str = Field(..., description="字段值")
    operator_role: UserRole = Field(..., description="操作人角色")

class ProjectProgress(BaseModel):
    """项目进度信息"""
    station_name: str
    station_code: str
    current_stage: str
    completed_steps: List[str]
    pending_steps: List[str]
    total_days: int
    is_timeout: bool
    timeout_details: Optional[dict]

5.2.2 工具函数

python 复制代码

from agents import function_tool

@function_tool
def query_project_progress(station_name: str) -> dict:
    """查询项目进度

    Args:
        station_name: 需求站址名称（支持模糊匹配）

    Returns:
        项目进度信息
    """
    # 实现项目进度查询逻辑
    pass

@function_tool
def update_project_progress(
    station_name: str,
    stage: str,
    field_name: str,
    field_value: str,
    operator_role: str
) -> dict:
    """更新项目进度

    Args:
        station_name: 需求站址名称
        stage: 阶段编号（如 "4.1"）
        field_name: 字段名称
        field_value: 字段值
        operator_role: 操作人角色

    Returns:
        更新结果
    """
    # 实现进度更新逻辑（含权限校验）
    pass

@function_tool
def query_rule_config(rule_name: str) -> dict:
    """查询考核规则配置

    Args:
        rule_name: 规则名称

    Returns:
        规则配置信息
    """
    # 实现规则查询逻辑
    pass

@function_tool
def validate_field_update(
    station_name: str,
    field_name: str,
    operator_role: str
) -> dict:
    """校验字段更新权限

    Args:
        station_name: 需求站址名称
        field_name: 字段名称
        operator_role: 操作人角色

    Returns:
        校验结果
    """
    # 实现权限校验逻辑
    pass

5.3 二次确认机制

python 复制代码

class ConfirmState:
    """确认状态管理"""
    def __init__(self):
        self.pending_confirms = {}  # session_id -> ConfirmInfo

    def create_confirm(self, session_id: str, update_info: dict) -> str:
        """创建确认信息"""
        confirm_key = f"{session_id}_{datetime.now().timestamp()}"
        self.pending_confirms[confirm_key] = update_info
        return confirm_key

    def confirm(self, confirm_key: str) -> dict:
        """执行确认"""
        if confirm_key in self.pending_confirms:
            info = self.pending_confirms.pop(confirm_key)
            # 执行实际更新
            return update_project_progress(**info)
        return {"status": "error", "message": "确认信息已过期"}

    def cancel(self, confirm_key: str) -> dict:
        """取消确认"""
        if confirm_key in self.pending_confirms:
            self.pending_confirms.pop(confirm_key)
            return {"status": "success", "message": "已取消"}
        return {"status": "error", "message": "确认信息已过期"}

六、测试用例

6.1 进度查询测试

输入	预期输出
"CBN-长沙星沙路口大谷二-H5H 现在到什么进度了"	显示当前阶段、已完成/待完成步骤
"星沙路口大谷二进度"	返回匹配列表供选择

6.2 进度更新测试

输入	预期输出
"帮我填写交付运营商的时间为 2025-03-15"	返回确认信息，等待用户回复"确认"
用户回复"确认"	执行更新，返回成功结果
用户回复"取消"	取消操作，返回取消提示

6.3 规则问答测试

输入	预期输出
"运营商开通时间考核是多少天"	返回考核天数、超时扣分规则
"超时扣分标准是什么"	返回扣分标准说明

6.4 权限校验测试

场景	输入	预期输出
设计角色更新 2.2 之前	"更新建设类型为地面站"	权限不足提示
监理角色更新 2.2 之前	"更新订单编制完成时间"	权限不足提示
管理员更新任意字段	"更新建设类型为地面站"	正常更新确认

七、运行命令

bash 复制代码

# 运行演示
python -m project_coordinator.demo

八、参考资料

docs/multi_agent_coordinator.mdmulti_agent_coordinator/ - 多智能体协作系统参考实现
docs/knowledge_agent.md - 知识问答 Agent 参考实现
.env - API 配置（API_KEY、BASE_URL）
scripts/test_models.py - 可用模型查询工具