customer-work · 基于 AgentScope Java 的企业级智能客服与 Agent 平台

🚀 第一次使用：快速开始 → 新人必读
📚 查功能、配置和接口：功能与配置全量参考 · 生产接口使用手册 · 部署手册
🛡️ 评估生产边界：企业级 AI 智能体能力与运维边界

作品演示

开源贡献

我也是 AgentScope Java 的 PR 贡献者：PR #2546 已于 2026 年 9 月 21 日合并到 main，修复 HITL 人工拒绝工具调用时缺失工具结果事件的问题，并支持自定义拒绝原因。

导航

• 项目定位
• 模块与运行边界
• 架构图与核心流程
• 能力地图
• 快速开始
• Roadmap
• 文档地图
• 重要边界

一、项目定位

customer-work 把典型客服流程落成一套可运行的 Java Agent 系统：从接入与身份校验、会话恢复、知识与工具调用， 到退款审批、转人工工单、CSAT，再到模型发布、评测门禁、FinOps、SLO 与多租户治理。它既能作为可运行的 客服产品参考实现，也能只引入 customer-work-starter，把 Agent 基础设施嵌入已有 Spring Boot 应用； 默认启动成功不等于已经完成真实业务、身份、数据主权与生产环境集成。

• 技术基线：项目版本 2.4.0，JDK 17、Spring Boot 3.2.5、AgentScope Java 2.0.3；默认模型为 阿里云百炼，同时已接入 OpenAI、Anthropic、Gemini 与 Ollama 模型扩展。
• 两套产品面：用户侧客服系统（H5 / HTTP / SSE / WebSocket / 工单）与运营控制台（模型、Agent、MCP、 渠道、评测、发布、账单、工单与 AI 编码助手）。
• 可替换业务后端：工具 Schema 与业务实现分离，订单、售后、知识、商品、会员、投诉等能力通过 tool.backend.* SPI 接入真实系统；用法见全量参考 §6.9。
• SaaS 与治理：共享库 tenant_id 行级隔离、角色数据范围、主体/租户配额、配置版本、灰度发布、 访问 epoch 撤权、ModelOps / EvalOps / FinOps 与审计链路均已有代码和自动化测试。
• 默认值有明确边界：客服端租户隔离默认关闭，后台租户隔离与数据范围默认开启；starter 的语义缓存默认关闭， 示例 app 已显式开启；Nacos 热更新、OTel、合成健康巡检仍需显式配置。默认关闭不等于未实现。

1.1 成熟度口径

“企业级 / 生产级”描述的是代码中的治理目标与交付能力，不代表任意部署已经自动通过生产验收。 真实 Nacos 往返、多 Pod ACK、生产模型凭据、网络出站策略和浏览器端到端验证仍需在目标环境留证。

1.2 核心术语

二、模块与运行边界

flowchart LR
    subgraph CLIENT["客户端与渠道"]
        H5["用户 H5 · 5175"]
        OPEN["HTTP / SSE 调用方"]
        IM["IM 渠道"]
        ADMINWEB["运营后台 · 5174"]
    end

    subgraph RUNTIME["运行面"]
        GW["可选网关 · 8888"]
        APP["app-server · 8080"]
        CHANNEL["channel · 8081"]
        STARTER["starter<br/>Agent 基础设施"]
    end

    subgraph CONTROL["控制面"]
        ADMIN["admin-server · 8082"]
    end

    subgraph STATE["状态与配置"]
        CWDB[("agent_scope_customer_work<br/>业务表")]
        ADMINDB[("customer_admin<br/>管理表")]
        REDIS[("Redis")]
        MINIO[("MinIO")]
        NACOS[("Nacos")]
    end

    H5 --> APP
    OPEN --> GW --> APP
    IM --> CHANNEL
    ADMINWEB --> ADMIN
    APP --> STARTER
    CHANNEL --> STARTER
    ADMIN --> STARTER
    APP --> CWDB & REDIS & MINIO
    GW -. "可选 admin 路由" .-> ADMIN
    ADMIN --> ADMINDB
    ADMIN -. "CustomerWorkFacade 受控访问" .-> CWDB
    ADMIN --> NACOS
    NACOS -. "租户专属运行时配置" .-> APP

• 根目录 docker-compose.yml 只编排 app-server 与 Redis、MySQL、MinIO、Nacos、XXL-JOB、PaddleOCR， 不包含 admin-server、channel、gateway、两个前端和监控栈。
• app 业务表与 admin 管理表分库治理；admin 对业务库的跨边界访问必须经 CustomerWorkFacade，不能直接复用管理库 Mapper。
• Nacos 热更新默认关闭，且是“控制面发布、运行面消费”的单向配置链；租户配置缺失时保留最后安全值，不跨租户回退。
• deploy/k8s/ 只提供 app / admin 的工作负载、Service、HPA、PDB 和探针，基础设施、Ingress、 网关与前端需由部署环境另行提供。

应用默认暴露 Prometheus 指标；显式开启 OTel 后可导出 agent / model / tool / HTTP span。 独立监控栈 提供 Prometheus、Grafana、Alertmanager、Tempo 与钉钉告警， 启动前需先运行业务服务并配置监控栈自己的 .env。详细配置见 全量参考 §6.13c。

三、架构图与核心流程

3.1 企业智能客服与 Agent 平台全景架构

查看可编辑 SVG · 查看高清 PNG（4096 × 3072）

图示按 2026-09-16 的 efc2f159 源码快照绘制。蓝色箭头表示请求与调用，橙色表示运行配置，绿色表示 结果与反馈；虚线框表示可选能力或独立入口。五栏按职责组织，具体入口之间的依赖关系见上一节模块图。

• 运行面：H5 / HTTP / SSE 对话通过 ChatTurnService 复用单一客服 ReActAgent；/consult 多 Agent、 Harness、渠道和网关分别按入口或配置启用。
• 受控执行：Agent 经 Toolkit、业务后端 SPI 或 MCP 调用工具；退款申请先经人工决策，再交已配置的执行器。 审批状态与执行状态分别记录，真实支付仍需对接业务系统。
• 控制与反馈：控制面管理模型、Agent、知识和工具资产，经发布门禁与 Nacos 下发运行配置，实例 ACK 汇总生效状态； 消息证据、工单事件、CSAT、Badcase 与知识候选进入运营改进流程。
• 数据与部署：MySQL 业务库 / 管理库、Redis、MinIO、Nacos 与 XXL-JOB 各负其责；根 Compose、独立监控栈和 Kubernetes 清单的覆盖范围见上节，生产启用条件见部署手册。

图中关键实现：ChatTurnService、 CustomerServiceAgentFactory、 AgentGovernanceAssembler、 PendingApprovalService、 RuntimePublishWorker。

rsvg-convert --width 4096 --height 3072 \
  --output docs/assets/architecture-overview.png docs/assets/architecture-overview.svg

3.2 H5 对话、转人工与 CSAT 闭环

H5 的逐消息主链路是单一客服 ReActAgent。多 Agent 编排是独立能力，不在 WebSocket 每条消息中隐式执行。

```mermaid flowchart TD H5["H5 Chat.vue"] -->|"创建会话"| SESSION["POST /api/customer/user/sessions
创建 AI_SERVING 工单"] H5 -->|"WS /ws/user?token=JWT"| UWS["UserChatWebSocketHandler
JWT、租户、accessEpoch 校验"] UWS -->|"chat 帧"| DISPATCH["ChatDispatchService
归属校验、主体配额、用户消息落库"]

DISPATCH --> KEYWORD{"命中转人工关键词？"}
KEYWORD -->|是| HANDOFF["TicketService.requestHandoff<br/>AI_SERVING → WAITING_AGENT"]
KEYWORD -->|否| STATUS{"工单状态"}
STATUS -->|AI_SERVING| TURN["ChatTurnService.stream<br/>统一对话编排"]
TURN --> CHAT["CustomerServiceService.chatStream"]
STATUS -->|PROCESSING / ON_HOLD| AGENTWS["转发给已受理坐席 /ws/agent"]
STATUS -->|WAITING_AGENT / WAITING_CONFIRM| NOTICE["返回排队或待确认提示"]

CHAT --> CACHE{"语义缓存命中？<br/>安全意图 + 租户分区 + 配置代际"}
CACHE -->|命中| REFILTER["缓存答案切片<br/>重新执行出站敏感词过滤"]
CACHE -->|未命中| FACTORY["CustomerServiceAgentFactory<br/>构建主 ReActAgent"]
FACTORY --> GOV["AgentGovernanceA