编写Skill生成AI落地项目系统架构

小帅热爱难回头2026-06-15 22:29

一、VOC场景代码框架搭建助手

代码框架搭建助手

prompt

你是一个AI Agent开发与代码生成方案专家，擅长将用户输入的业务需求转化为可落地的代码框架和自动化脚本。你能够帮助用户构建基于AI工具的代码生成方案模板，并输出清晰、结构化的技术文档，包含：文档概述、系统概述、项目目录结构、数据库表结构设计、Agent可插拔架构设计、Skill功能设计、工作流设计等，不需要包括具体的代码，主要输出架构设计。

整体框架包括：

  1. API层：使用 FastAPI 开发。
  2. 配置层：支持多环境配置（生产/测试），包含数据库配置、知识库配置（如分类数据表等）。
  3. Agent层：实现主工作流和多个功能Agent，支持后续灵活扩展并接入主工作流；推荐使用 LangChain 或 LangGraph 等技术。
  4. Skill功能：包括上下文记忆、反思机制（可从错误的埋点数据中学习，并在后续流程中持续优化）。

功能流程（业务请求处理链路）：

VOC原声输入 → 功能Agent处理 → 频次计算 → 数据存储到数据库。

功能需求详情：

  1. VOC问题分类识别：自动对客户反馈进行工单类型、业务类型、四级分类的归类。
  2. 情感预警：自动判断客户反馈的情感倾向（红色预警 / 橙色预警 / 黄色关注 / 无预警），并按等级预警。
  3. 问题风险等级预判：自动评估客户反馈的风险等级（高 / 中 / 低）。
  4. VOC关键字提炼：从客户反馈中提炼不超过20字的摘要。
  5. 舆情与法律风险监控：判断客户反馈是否存在舆情或法律风险，输出"是 / 否"。
  6. 同类型频次识别：投诉咨询规则------按「车系 + 工单类型 + 分类集合（二级+三级）+ 配置天数（7天/30天/90天/365天/自定义）」进行分组聚合计算数量。

已知数据结构：

  • 工单分类表：字段包括序号、一级分类、二级分类（更新后）、三级分类（更新后）、四级分类（更新后）。
  • 业务类别表：字段包括序号、工单类型、业务类别。
  • 风险等级表 ：
    • 低风险：问题单一、影响小、无升级/扩散/索赔/威胁，不影响舆情。
    • 中风险：问题重复出现、有升级倾向、涉及索赔/退换车诉求、可能引发社交平台吐槽，轻度口碑风险。
    • 高风险：安全隐患/重大质量问题，威胁向媒体/12315/监管部门投诉、网络曝光、拉横幅、聚众维权、诉讼，已引发舆情人多群诉。
  • 关键字识别表 ：
    • 中风险关键词：频繁发生、多次维修、修不好、要求赔偿、要求补偿、误工费、交通费、要说法、必须解决、再不解决、发朋友圈、吐槽、退车、换车等。
    • 高风险关键词：刹车失灵、失控、自燃、生命安全、安全隐患、威胁、12315、市民热线、市场监管局、市监所、质监局、消协、电视台、媒体、车友群、发帖、抖音曝光、小红书曝光、网络曝光、起诉、法院、拉横幅、堵门、维权、集体投诉、记者、直播维权、曝光、消费者权益保护法、国家质检总局、合格证未交付、欺诈等。
  • 典型案例判定示例 ：
    • 中风险：车机黑屏三次了，修了多次未解决，要求赔偿。
    • 高风险：高速刹车失灵，太危险了！不彻底解决我就投诉到12315并找媒体曝光！

VOC智能分析系统 - 完整构建方案

📋 文档概述

本文档为VOC（客户之声）智能分析系统提供完整的构建方案。系统基于FastAPI + LangGraph架构，实现客户反馈的自动化分析、分类、预警和频次统计功能。

文档版本 更新日期 说明
v1.0 2026-01-15 初始版本，不含记忆模块和反思学习

🎯 系统概述

核心功能模块

序号 模块 功能描述 输出结果
1 问题分类识别 自动对客户反馈进行工单类型、业务类型、四级分类归类 完整分类路径
2 情感预警 判断情感倾向并按等级预警 红/橙/黄/无预警
3 风险等级预判 评估客户反馈的风险等级 高/中/低风险
4 关键词提炼 从反馈中提炼不超过20字摘要 精简摘要
5 舆情法律监控 判断是否存在舆情或法律风险 是/否
6 频次统计 按车系+工单类型+分类+天数聚合统计 频次数据

业务流程

text

复制代码 
原始VOC输入 → 功能Agent处理 → 频次计算 → 数据库存储

技术架构图

text

复制代码 
┌─────────────────────────────────────────────────────────────────┐
│                         客户端请求                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      FastAPI API Gateway                        │
│                    (路由 + 请求验证 + 响应)                       │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      LangGraph 工作流引擎                        │
├───────────┬───────────┬───────────┬───────────┬────────────────┤
│ 分类Agent │ 情感Agent │ 风险Agent │ 关键词Agent│ 法律Agent │
└───────────┴───────────┴───────────┴───────────┴────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                      频次统计引擎                                │
│              (按车系+类型+分类+天数聚合计算)                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        PostgreSQL                               │
│              (VOC记录 + 分类表 + 频次统计表)                      │
└─────────────────────────────────────────────────────────────────┘

🏗️ 项目目录结构

text

复制代码 
voc_agent_system/
│
├── app/                               # 主应用目录
│   ├── __init__.py
│   ├── main.py                        # FastAPI主入口
│   │
│   ├── api/                           # API接口层
│   │   └── v1/
│   │       ├── __init__.py
│   │       ├── routes.py              # 路由注册中心
│   │       ├── voc.py                 # VOC分析接口
│   │       └── analytics.py           # 统计分析接口
│   │
│   ├── config/                        # 配置层
│   │   ├── __init__.py
│   │   ├── settings.py                # 全局配置管理
│   │   ├── database.py                # 数据库连接配置
│   │   └── knowledge/                 # 知识配置目录
│   │       ├── category_config.yaml   # 工单分类配置
│   │       ├── business_type.yaml     # 业务类别配置
│   │       ├── risk_keywords.yaml     # 风险关键词库
│   │       └── sentiment_config.yaml  # 情感等级配置
│   │
│   ├── models/                        # 数据模型层
│   │   ├── __init__.py
│   │   ├── database/                  # SQLAlchemy ORM模型
│   │   │   ├── __init__.py
│   │   │   ├── voc_record.py          # VOC记录表
│   │   │   ├── category.py            # 分类字典表
│   │   │   ├── business_type.py       # 业务类别表
│   │   │   └── frequency_stat.py      # 频次统计表
│   │   └── schemas/                   # Pydantic验证模型
│   │       ├── __init__.py
│   │       ├── request.py             # 请求模型
│   │       ├── response.py            # 响应模型
│   │       └── internal.py            # 内部传输模型
│   │
│   ├── agents/                        # Agent模块（可插拔架构）
│   │   ├── __init__.py
│   │   ├── base.py                    # Agent基类定义
│   │   ├── registry.py                # Agent注册中心
│   │   │
│   │   ├── classification/            # 分类Agent
│   │   │   ├── __init__.py
│   │   │   ├── agent.py               # 分类逻辑实现
│   │   │   └── prompts.py             # LLM提示词模板
│   │   │
│   │   ├── sentiment/                 # 情感分析Agent
│   │   │   ├── __init__.py
│   │   │   ├── agent.py               # 情感分析逻辑
│   │   │   └── prompts.py             # LLM提示词模板
│   │   │
│   │   ├── risk/                      # 风险判断Agent
│   │   │   ├── __init__.py
│   │   │   ├── agent.py               # 风险等级判断
│   │   │   └── prompts.py             # LLM提示词模板
│   │   │
│   │   ├── keyword/                   # 关键词提取Agent
│   │   │   ├── __init__.py
│   │   │   ├── agent.py               # 摘要提取逻辑
│   │   │   └── prompts.py             # LLM提示词模板
│   │   │
│   │   ├── legal/                     # 舆情法律Agent
│   │   │   ├── __init__.py
│   │   │   ├── agent.py               # 风险监控逻辑
│   │   │   └── prompts.py             # LLM提示词模板
│   │   │
│   │   └── frequency/                 # 频次统计Agent
│   │       ├── __init__.py
│   │       ├── agent.py               # 频次计算逻辑
│   │       └── calculator.py          # 聚合计算引擎
│   │
│   ├── workflow/                      # LangGraph工作流
│   │   ├── __init__.py
│   │   ├── graph.py                   # 工作流图定义
│   │   ├── state.py                   # 工作流状态定义
│   │   └── nodes.py                   # 工作流节点函数
│   │
│   └── utils/                         # 工具函数
│       ├── __init__.py
│       ├── logger.py                  # 日志配置
│       ├── db_helper.py               # 数据库辅助函数
│       └── llm_client.py              # LLM客户端封装
│
├── scripts/                           # 脚本目录
│   ├── init_database.py               # 数据库初始化脚本
│   ├── seed_categories.py             # 分类数据导入
│   └── seed_keywords.py               # 关键词库导入
│
├── prompts/                           # AI提示词模板（备份）
│   ├── classification.txt
│   ├── sentiment.txt
│   ├── risk.txt
│   ├── keyword.txt
│   └── legal.txt
│
├── tests/                             # 测试目录
│   ├── __init__.py
│   ├── test_api.py
│   ├── test_agents.py
│   └── test_workflow.py
│
├── requirements.txt                   # Python依赖
├── docker-compose.yml                 # Docker编排文件
├── .env.example                       # 环境变量示例
└── README.md                          # 项目说明文档

📊 数据库设计

表结构详细说明

1. voc_records（VOC记录主表）
字段名 类型 约束 说明
id BIGSERIAL PRIMARY KEY 唯一标识
original_text TEXT NOT NULL 原始VOC内容
vehicle_series VARCHAR(100) 车系信息
ticket_type VARCHAR(50) 工单类型（咨询/投诉）
category_level1 VARCHAR(100) 一级分类
category_level2 VARCHAR(100) 二级分类
category_level3 VARCHAR(100) 三级分类
category_level4 VARCHAR(100) 四级分类
business_category VARCHAR(100) 业务类别
sentiment_level VARCHAR(20) 情感等级
risk_level VARCHAR(20) 风险等级
risk_keyword_matched TEXT 匹配的风险关键词
keyword_summary VARCHAR(100) 提炼的关键词摘要
legal_risk_flag BOOLEAN DEFAULT FALSE 舆情法律风险标识
processing_time_ms INTEGER 处理耗时（毫秒）
created_at TIMESTAMP DEFAULT NOW() 创建时间
2. categories（分类字典表）
字段名 类型 约束 说明
id BIGSERIAL PRIMARY KEY 唯一标识
level1 VARCHAR(100) NOT NULL 一级分类
level2 VARCHAR(100) NOT NULL 二级分类
level3 VARCHAR(100) NOT NULL 三级分类
level4 VARCHAR(100) NOT NULL 四级分类
is_active BOOLEAN DEFAULT TRUE 是否启用
3. business_types（业务类别表）
字段名 类型 约束 说明
id BIGSERIAL PRIMARY KEY 唯一标识
ticket_type VARCHAR(50) NOT NULL 工单类型
business_category VARCHAR(100) NOT NULL 业务类别
4. frequency_stats（频次统计表）
字段名 类型 约束 说明
id BIGSERIAL PRIMARY KEY 唯一标识
vehicle_series VARCHAR(100) NOT NULL 车系
ticket_type VARCHAR(50) NOT NULL 工单类型
category_level2 VARCHAR(100) 二级分类
category_level3 VARCHAR(100) 三级分类
date_range_days INTEGER NOT NULL 统计天数（7/30/90/365）
count INTEGER DEFAULT 0 频次数量
stat_date DATE NOT NULL 统计日期
created_at TIMESTAMP DEFAULT NOW() 创建时间

表关系图

text

复制代码 
┌─────────────────┐     ┌─────────────────┐
│   categories    │     │ business_types  │
├─────────────────┤     ├─────────────────┤
│ id (PK)         │     │ id (PK)         │
│ level1          │     │ ticket_type     │
│ level2          │     │ business_category│
│ level3          │     └─────────────────┘
│ level4          │              │
└─────────────────┘              │
         │                       │
         │ 关联查询               │ 关联查询
         ▼                       ▼
┌─────────────────────────────────────────────────┐
│                   voc_records                    │
├─────────────────────────────────────────────────┤
│ id (PK)                                          │
│ original_text                                    │
│ vehicle_series                                   │
│ ticket_type ─────────────────────────────────────┘
│ category_level1 ────────────────────────────────┐
│ category_level2 ────────────────────────────────┤
│ category_level3 ────────────────────────────────┤
│ category_level4 ────────────────────────────────┤
│ business_category ──────────────────────────────┘
│ sentiment_level                                  │
│ risk_level                                       │
│ keyword_summary                                  │
│ legal_risk_flag                                  │
│ created_at                                       │
└─────────────────────────────────────────────────┘
         │
         │ 聚合统计
         ▼
┌─────────────────┐
│ frequency_stats │
├─────────────────┤
│ id (PK)         │
│ vehicle_series  │
│ ticket_type     │
│ category_level2 │
│ category_level3 │
│ date_range_days │
│ count           │
│ stat_date       │
└─────────────────┘

🔌 Agent可插拔架构设计

Agent基类定义

属性/方法 类型 说明
name 属性 Agent唯一标识名称
version 属性 Agent版本号
description 属性 Agent功能描述
dependencies 属性 依赖的其他Agent（可选）
initialize() 方法 初始化钩子
process() 方法 核心处理逻辑（必须实现）
validate_output() 方法 输出结果验证

Agent注册中心

方法 参数 返回值 说明
register agent_class, config bool 注册新Agent
get agent_name Agent实例 获取指定Agent
list 无 Liststr 列出所有Agent
unregister agent_name bool 移除Agent
is_registered agent_name bool 检查是否已注册

五大Agent规范

Agent名称 输入字段 输出字段 依赖知识库
ClassificationAgent original_text category_path, ticket_type, business_category categories, business_types
SentimentAgent original_text sentiment_level sentiment_config
RiskAgent original_text risk_level, matched_keywords risk_keywords
KeywordAgent original_text summary (≤20字) 无
LegalAgent original_text legal_risk_flag risk_keywords（舆情类）

🔄 LangGraph工作流设计

工作流状态定义（WorkflowState）

字段 类型 说明
original_text str 原始VOC文本
vehicle_series str 车系信息
ticket_type str 工单类型结果
category_level1~4 str 四级分类结果
business_category str 业务类别结果
sentiment_level str 情感等级结果
risk_level str 风险等级结果
matched_keywords list 匹配的关键词
summary str 关键词摘要
legal_risk_flag bool 舆情风险标识
errors list 错误记录

工作流节点定义

节点名称 功能 输入 输出
node_classify 问题分类 text 分类结果
node_sentiment 情感分析 text 情感等级
node_risk 风险评估 text 风险等级+关键词
node_keyword 关键词提取 text 摘要
node_legal 舆情监控 text 是/否
node_aggregate 结果聚合 全部结果 整合数据
node_save 数据存储 整合数据 存储确认

工作流路由图

text

复制代码 
        ┌─────────────────────────────────────────────────────────┐
        │                      START                              │
        └─────────────────────────────────────────────────────────┘
                                   │
                                   ▼
        ┌─────────────────────────────────────────────────────────┐
        │              node_classify (分类Agent)                  │
        └─────────────────────────────────────────────────────────┘
                                   │
        ┌──────────────┬───────────┼───────────┬──────────────────┐
        ▼              ▼           ▼           ▼                  ▼
┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐
│node_senti- │ │ node_risk  │ │node_key-   │ │ node_legal │ │ (并行执行) │
│ment        │ │            │ │word        │ │            │ │            │
└────────────┘ └────────────┘ └────────────┘ └────────────┘ └────────────┘
        │              │           │           │                  │
        └──────────────┴───────────┼───────────┴──────────────────┘
                                   ▼
        ┌─────────────────────────────────────────────────────────┐
        │             node_aggregate (结果聚合)                   │
        └─────────────────────────────────────────────────────────┘
                                   │
                                   ▼
        ┌─────────────────────────────────────────────────────────┐
        │               node_save (数据存储)                      │
        └─────────────────────────────────────────────────────────┘
                                   │
                                   ▼
        ┌─────────────────────────────────────────────────────────┐
        │                        END                              │
        └─────────────────────────────────────────────────────────┘

📁 配置文件详细设计

settings.py 配置项

配置分类 配置项 类型 默认值 说明
环境 ENVIRONMENT str development 运行环境
环境 DEBUG bool True 调试模式
数据库 DATABASE_URL str - 数据库连接串
数据库 DATABASE_POOL_SIZE int 10 连接池大小
数据库 DATABASE_ECHO bool False SQL日志
LLM LLM_MODEL str gpt-4 模型名称
LLM LLM_API_KEY str - API密钥
LLM LLM_TEMPERATURE float 0.1 温度参数
LLM LLM_MAX_TOKENS int 2000 最大token
频次 FREQUENCY_DAYS list 7,30,90,365 统计天数
API API_PREFIX str /api/v1 API前缀
API CORS_ORIGINS list "\*" 跨域配置

knowledge配置文件说明

文件 作用 更新方式
category_config.yaml 四级分类数据 人工维护
business_type.yaml 工单类型-业务类别映射 人工维护
risk_keywords.yaml 风险关键词库 人工维护+定期更新
sentiment_config.yaml 情感等级判定规则 人工维护

📝 提示词模板设计

各Agent提示词架构

Agent 提示词结构 核心要求
分类Agent 角色定义 + 分类体系 + 输出格式 + 示例 严格按照分类表输出
情感Agent 角色定义 + 等级定义 + 关键词参考 + 示例 输出标准化等级
风险Agent 角色定义 + 等级定义 + 关键词表 + 匹配规则 关键词匹配+语义理解
关键词Agent 角色定义 + 提取规则 + 长度限制 + 示例 不超过20字
法律Agent 角色定义 + 风险定义 + 判定逻辑 + 示例 输出布尔值

🚀 部署配置

Docker Compose服务

服务名称 镜像 端口 数据卷 用途
postgres postgres:15 5432 postgres_data 主数据库
redis redis:7-alpine 6379 redis_data 缓存（可选）
app 自定义 8000 ./app 应用服务

环境配置

环境 配置文件 数据库 日志级别
开发 .env.dev 本地 DEBUG
测试 .env.test 测试库 INFO
生产 .env.prod 生产库 WARNING

📦 依赖清单

核心依赖

包名 版本 用途
fastapi 0.104.1 Web框架
uvicorn 0.24.0 ASGI服务器
sqlalchemy 2.0.23 ORM框架
asyncpg 0.29.0 PostgreSQL驱动
pydantic 2.5.0 数据验证
pydantic-settings 2.1.0 配置管理
langchain 0.1.0 LLM框架
langgraph 0.0.20 工作流编排
langchain-openai 0.0.5 OpenAI集成
pyyaml 6.0.1 YAML解析
loguru 0.7.2 日志管理
alembic 1.12.1 数据库迁移

测试依赖

包名 版本 用途
pytest 7.4.3 测试框架
pytest-asyncio 0.21.1 异步测试
httpx 0.25.1 API测试
相关推荐
diving deep2 小时前
脚本速览-python
开发语言·python
2601_951643774 小时前
Python第一，Java跌出前三，C语言杀回来了
java·c语言·python·编程语言排行·技术趋势
AC赳赳老秦6 小时前
OpenClaw+Power Apps 实战：自动生成 Power Apps 应用、连接 Excel 数据源
大数据·开发语言·python·serverless·excel·deepseek·openclaw
茉莉玫瑰花茶7 小时前
综合案例 - AI 智能租房助手 [ 5 ]
服务器·数据库·人工智能·python·ai
文艺倾年7 小时前
【强化学习】强化学习基本概念，20W字总结（一）
人工智能·python·语言模型·自然语言处理·面试·职场和发展·大模型
宸丶一7 小时前
Day 13：持久化记忆 - 让 Agent 拥有长期记忆
jvm·python·ai
码云骑士8 小时前
13-列表append的底层真相（上）-listobject源码中的预分配策略
开发语言·python
浦信仿真大讲堂8 小时前
达索系统SIMULIA Abaqus 2026接触和约束的增强新功能介绍
人工智能·python·算法·仿真软件·达索软件
xufengzhu8 小时前
第三方 Python 库 Loguru 的进阶实战
python·loguru
热门推荐
01HTTP 与 HTTPS 的区别：从原理到实战详解022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？04【AI】2026 年具身智能模型和世界模型总结05GitHub 镜像站点062026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf07AI科技热点日报 | 2026年6月1日08Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析09《置身钉内》原文-可播放阅读10上线仅72小时被强制下架：Claude Fable 5 的短命