customer-work · 基于 AgentScope Java 的生产级智能客服系统

🚀 新人从这里开始：docs/新人必读.md（15 分钟跑起来 + 看懂结构 + 知道改哪里） 📚 功能 / 配置 / 接口的全部细节：docs/功能与配置全量参考.md（本 README 只讲"是什么、长什么样"，"怎么用"都在那里）

一、这个项目是做什么的

把一张典型的客服业务流程图，落成一套可上生产的代码：从接入与流量治理、会话恢复、意图识别与路由、 七域业务工具执行，到人工审批 / 转人工工单的人机协作闭环，再到质检反馈驱动的数据飞轮——全链路可运行、可测试、可部署。

• 技术底座：io.agentscope:agentscope-harness:2.0.0（GA 正式版），模型默认对接阿里云百炼（DashScope / 通义千问）， 完整用上 2.0 新能力（Permission / Plan Mode / Compaction / Sandbox / Subagent / 五段 Middleware）。
• 设计原则：每个能力 = 一个配置开关 + 一个可替换实现。默认内置实现保证离线开箱即用、单测全绿； 改一行配置或声明一个 Bean，即可切到 Redis / MySQL / 百炼 / Nacos 等真实后端，业务代码零改动。
• 可改造为你自己的业务 Agent：业务工具壳只暴露 Schema，真正逻辑委托给 tool.backend.* SPI 接口 （Order / AfterSales / Knowledge / Product / Member / Complaint），实现接口或覆盖 Bean 即可接入自有订单 / 售后 / 知识系统， 无需改框架代码（用法见 全量参考 §6.9）。
• 两套完整系统：智能客服系统（AI 对话 + 用户工单 + 坐席协作）+ 后台管理系统（模型 / 提示词 / MCP / 渠道 / 定时任务 / 工单工作台，改配置经 Nacos 热更新到运行中的客服应用，免重启）。
• 多租户 SaaS 就绪（默认关闭）：共享库 + tenant_id 行级隔离（MyBatis-Plus 拦截器全局改写，缺上下文 fail-closed）， 配套租户配额与 T+1 计费账单、配置版本化与按租户灰度发布、多副本水平扩展（Redis 窗口计数 / 会话锁 + deploy/k8s/ 清单）。 不开启时单租户部署行为与升级前完全一致，设计见 多租户架构设计。

二、模块结构

模块间的依赖与数据边界（三个后端服务都只依赖 starter，两个库彻底分离）：

flowchart LR
    APPFE["customer-work-app · 5175<br/>用户 H5"] --> APPSRV
    ADMINFE["customer-admin-web · 5174<br/>后台前端"] --> ADMSRV
    GW["customer-work-gateway · 8888<br/>SCG 统一入口（可选）"] -.->|Nacos 服务发现| APPSRV & ADMSRV
    APPSRV["customer-work-app-server · 8080<br/>客服应用"] --> ST
    CH["customer-channel · 8081<br/>多渠道接入（钉钉 / 微信公众号）"] --> ST
    ADMSRV["customer-admin-server · 8082<br/>后台管理"] --> ST
    ST["customer-work-starter<br/>可复用智能体基础设施"]
    APPSRV --- DBA[("agent_scope_customer_work<br/>cw_* 业务表")]
    ADMSRV --- DBB[("customer_admin<br/>Flyway 管理")]
    ADMSRV -.->|"Nacos 配置热更新：改模型 / 提示词，8080 免重启生效"| APPSRV

附属目录：mysql/ 建库脚本（业务库 / admin 库 / XXL-JOB 库）、docker/ 中间件编排（MinIO / PaddleOCR / observability 一键监控栈：Prometheus + Grafana + Alertmanager + Tempo + 钉钉告警）、 deploy/k8s/ 多副本 K8s 清单（Deployment / HPA / PDB / 探针 / 优雅停机）、 Dockerfile + docker-compose.yml 一键起应用与依赖、.github/workflows/ci.yml CI。 starter 的代码分层与"作为依赖引入"的方式见 全量参考 §九。

可观测性：应用侧默认暴露 Prometheus 指标；开启 customer-work.observability.otel.enabled（starter）/ admin.observability.otel.enabled（admin）后接入 OpenTelemetry，按 agent/model/tool（starter 另加 HTTP 入口） 三段出 span 并经 OTLP 导出。配套的一键监控栈见 docker/observability/README.md， 预置 Prometheus + Grafana（4 张仪表盘）+ Alertmanager（13 条告警规则 + 钉钉转发）+ Tempo 链路追踪后端； 详细配置项见 全量参考 §6.13c， 生产部署步骤见 部署手册 §九。

三、架构图与核心流程

3.1 全景架构

一次用户消息从渠道进来，到 AI 回复 / 人工接管 / 数据沉淀的完整链路（①~⑥ 对应客服业务流程图的六个阶段）：

flowchart TB
    subgraph CLIENT["渠道与客户端"]
        H5["用户端 H5<br/>customer-work-app · 5175"]
        IM["IM 渠道<br/>钉钉 / 飞书 / 企业微信"]
        OPEN["OpenAPI 调用方<br/>chat / SSE / AG-UI / chat-completions"]
        ADMINWEB["后台管理前端<br/>customer-admin-web · 5174"]
    end

    subgraph EDGE["① 接入与流量治理"]
        GW["Spring Cloud Gateway 统一路由<br/>+ Nacos 服务注册发现"]
        SEC["API Key 鉴权 · 滑动窗口限流<br/>防注入围栏 · RequestId / MDC 全链路"]
    end

    subgraph CORE["customer-work-app-server · 8080（能力由 customer-work-starter 自动装配）"]
        SVC["CustomerServiceService<br/>② 会话恢复 + 状态持久化"]
        AGENT["ReActAgent / HarnessAgent<br/>③ 意图识别 → 工具路由 → 观察-再推理"]
        MAS["MultiAgentOrchestrator<br/>快慢车道路由 → 专家并行 → reduce 归纳"]
        MW["五段 Middleware<br/>可观测 / 审计 / 脱敏 / 工具护栏 / 人工审批 / 对话阶段"]
    end

    subgraph BRAIN["记忆 · 知识 · 技能"]
        MEM["三层记忆：L1 短期 + L2 长期多租户 + L3 FactLog"]
        RAG["RAG 检索：memory / simple / 百炼 / Dify"]
        SKILL["Skill 技能库 + 自进化"]
    end

    MODEL["模型层：百炼默认 / OpenAI / Ollama …<br/>重试 + 私有化兜底 + 成本熔断"]

    subgraph TOOLS["④ 七域业务工具（tool.backend SPI 可替换）"]
        T["知识库 · 订单 · 售后 · 售前导购 · 会员 · 投诉 · 转人工"]
        DB[("MySQL 业务库 cw_*<br/>或你自己的订单 / 售后系统")]
    end

    subgraph HITL["⑤ 人机协作闭环"]
        AP["人工审批：退款挂起 → 放行 / 拒绝<br/>+ 超时巡检"]
        HO["转人工 / 用户工单<br/>7 态状态机 + SLA 升级"]
        SEAT["坐席工作台 + 后台管理<br/>customer-admin-server · 8082"]
    end

    subgraph WHEEL["⑥ 数据飞轮"]
        QC["会话质检 · 坐席辅助"]
        FB["消息级反馈：点赞 / 点踩"]
        FACT["FactLog 事实流水 → 离线复盘 / 评测集"]
    end

    subgraph OPS["配置与运维面"]
        NACOS["Nacos 配置热更新<br/>后台改模型 / 提示词 / MCP → 8080 免重启生效"]
        OBS["Prometheus 指标 · Tracing · Grafana"]
        XXL["XXL-JOB 定时调度"]
    end

    H5 --> GW
    IM --> GW
    OPEN --> GW
    GW --> SEC --> SVC --> AGENT
    ADMINWEB --> SEAT
    AGENT <--> MODEL
    AGENT --- MW
    AGENT --> MAS
    AGENT <--> BRAIN
    AGENT --> T
    T --> DB
    T -->|submitRefund 挂起| AP
    T -->|transferToHuman| HO
    HO <--> SEAT
    AP --> SEAT
    AGENT --> QC
    H5 -. 点赞 / 点踩 .-> FB
    QC --> FACT
    FB --> FACT
    NACOS -. 热更新 .-> MODEL
    OPS -.-> CORE

3.2 退款人工审批闭环（挂起 → 人工决策 → 生效）

高风险工具不直接生效：submitRefund 只登记待审单，人工放行后才执行退款回调（详见 全量参考 §6.11）：

sequenceDiagram
    autonumber
    participant U as 用户
    participant A as ReActAgent
    participant P as ApprovalStore（SPI：内存 / JDBC）
    participant S as 坐席 / 管理员

    U->>A: 我要退款 500 元
    A->>P: submitRefund 不直接打款，登记待审单（挂起）
    A-->>U: 已提交人工审批（返回审批单号）
    S->>P: 查看待审列表 GET /api/customer/approvals
    alt 放行 approve
        P->>P: 执行退款回调，终态 APPROVED
    else 拒绝 deny
        P->>P: 终态 DENIED（决策幂等，重复决策返回 409）
    else 审批超时
        P->>P: 超时巡检按配置处置：升级转人工 / 自动拒绝
    end

3.3 用户工单 7 态状态机（AI 自助 ↔ 人工坐席全生命周期）

状态名与代码 TicketStatus 枚举一一对应，非法流转 fast-fail：

stateDiagram-v2
    [*] --> AI_SERVING : 创建工单
    AI_SERVING --> WAITING_AGENT : transferToHuman 转人工排队
    WAITING_AGENT --> AI_SERVING : 取消转人工
    WAITING_AGENT --> PROCESSING : 坐席接单 claim
    PROCESSING --> ON_HOLD : 挂起（等用户补材料）
    ON_HOLD --> PROCESSING : 恢复处理
    PROCESSING --> WAITING_AGENT : 转回工单池
    PROCESSING --> WAITING_CONFIRM : 处理完毕待确认
    WAITING_CONFIRM --> RESOLVED : 用户确认解决
    WAITING_CONFIRM --> PROCESSING : 用户不认可，退回
    RESOLVED --> CLOSED : 结案
    AI_SERVING --> CLOSED : AI 已解决，直接关闭
    CLOSED --> WAITING_AGENT : reopen 重开回流
    CLOSED --> [*]

    note right of CLOSED
        RESOLVED / CLOSED 均可 reopen，
        回人工队列或回 AI 自助；
        forceClose 可从任意非终态强制关闭
    end note

四、能力地图

细节（配置项、curl 示例、对应测试类）全部在 功能与配置全量参考，此处只给地图：

五、快速开始

# 方式一：本地运行（示例应用默认使用本机 MySQL；纯内存宿主可按需关闭 JDBC 域与迁移）
export DASHSCOPE_API_KEY=你的百炼密钥      # 必填，密钥仅从环境变量读取
mvn -pl customer-work-app-server -am spring-boot:run

# 方式二：Docker Compose 一键起（app + Redis + MySQL + Nacos）
docker compose up -d

# 发一条消息试试
curl -X POST http://localhost:8080/api/customer/chat \
  -H "Content-Type: application/json" \
  -d '{"sessionId":"u1001","message":"帮我查一下订单 20260613001 的状态和物流"}'

• 启动后打开 http://localhost:8080/swagger-ui.html 在线调试全部接口。
• 跑测试（无需 API Key，任何环境全绿）：mvn test ——当前基线 2222 个（starter 1323 + admin-server 753 + app 80 + customer-channel 65 + gateway 1），外部依赖（Redis/MySQL/Nacos/百炼/OCR/MinIO）不可达的用例自动跳过。
• 环境要求、前端启动、构建坑位速查见 新人必读。

六、Roadmap

timeline
    title customer-work 演进路线
    已完成 · 1.x 基线 : AgentScope 1.0.12 核心客服链路 : 存档于 legacy-main-1.0.12 标签
    已完成 · 2.0 迁移 : RC4 首轮迁移（rc2.0 分支存档） : 2.0.0 GA 全量迁移 + Harness 新能力补齐
    已完成 · 生产化 : HITL 审批闭环 + 人机切换工单 : 用户工单系统（JWT + WS 双通道 + 7 态状态机） : 后台管理系统 + Nacos 配置热更新 : 真实业务后端 jdbc + 附件解析 OCR : Nacos 注册发现 + SCG 网关 + XXL-JOB
    已完成 · 平台化 : 内容风控（敏感词 + 限流）+ 数据字典 + 开发者工具箱 : 十项通用能力薄壳化下沉 starter : OTel 链路追踪 + 一键 Grafana / Tempo 监控栈 : 登录态 Redis 持久化 + streamEvents 流式重构
    已完成 · SaaS 化 : 多租户行级隔离 + 租户管理双视角 : 水平扩展（Redis 计数 / 会话锁 + K8s 清单） : 租户配额 + T+1 计费账单 : 配置版本化 + 按租户灰度 : starter 按域拆分治理
    已完成 · 运营闭环 : 评测中心 + badcase 回流 : 语义缓存 + 模型分级路由 : 提示词版本归因 + CSAT : 知识盲区 + 死信队列
    规划中 · 扩展点 : 租户安全合规（审计归档 / 退租数据导出） : A2A Agent Card 注册发现 : RocketMQ 异步消息 : Training 数据飞轮（RM Gallery / Trinity-RFT） : 后台 AI 编码助手 P1~P3 演进

规划中的能力框架均已提供扩展点（保留为"配置即用"，不硬编入以保证开箱即用）：

七、文档地图

八、重要说明

• 分支策略：main 有分支保护、禁止直接 push，开发从 main 切分支走 PR；legacy-main-1.0.12 标签与 rc2.0 分支为历史存档，不再更新。
• 基于官方 GA 坐标 io.agentscope:agentscope-harness:2.0.0（agentscope-bom 统一管理版本）；框架高速迭代， 升级遇 API 不匹配请对照该版本源码微调。
• API Key 支持配置项与环境变量两种来源，生产请用环境变量注入，勿把密钥留在仓库。
• 客服业务库由 starter 的 Flyway 管理；存量非空库以版本 0 接管后顺序执行增量迁移，迁移失败会阻断启动。
• 工单状态、事件轨迹和 Outbox 在同一本地事务中提交；消费语义为至少一次，处理器必须按稳定事件 ID 幂等。
• CI 会扫描当前提交中的常见密钥格式。若密钥曾进入 Git 历史，删除文件内容不足以止损，仍须立即吊销并轮换。
• 业务链路全异步（Mono/Flux，无 .block()）；所有外部后端均为配置开关，默认实现保证离线开箱即用与单测全绿。
• 包名按模块划分，根均为 com.richard.fyoung：starter …customerwork、app-server …customerworkapp、 channel …customerchannel、admin-server …customeradmin、gateway …customerworkgateway。

关注作者

如果你对 AI 及本项目感兴趣，欢迎关注我的微信公众号 AI赛博炼丹炉，将带来更多高质量文章和干货。