电商售后智能体Artlatte/industry-aftersales-ai-agent

电商售后客服智能体

E-commerce After-sales Service Agent — 面向电商售后场景的行业专属轻量级智能体。

对话交互 · 知识库上传/检索 · 业务插件（订单/退款/物流/工单）· 支持插件迭代 · 配套完整测试方案。

✨ 特性

| 能力 | 说明 |
| --- | --- |
| 💬 对话交互 | 意图识别、多轮追问、SOP 话术、来源引用、转人工兜底 |
| 📚 知识库上传 | 上传 → 分块 → 索引 → 检索（带来源溯源），支持标签过滤与删除 |
| 🔌 业务插件 | 订单 / 退款 / 物流 / 投诉工单，接口契约化，错误不编造 |
| 🔄 插件迭代 | 插件即能力单元，版本化上线 / 回滚，互不影响 |
| 🪶 轻量级 | 检索不依赖向量库（词元重叠 + 标签打分），可解释、可离线、零重依赖 |
| 🧪 测试闭环 | 测试策略 / 用例 / 执行 / 报告 / 缺陷闭环，质量可度量 |

🧰 能力一览（8 个工具）

| 模块 | 工具 | 功能 |
| --- | --- | --- |
| 知识库 | kb_upload | 上传知识（标题 + 正文 + 标签），自动分块建索引 |
| 知识库 | kb_search | 关键词 + 标签检索，返回 top-k 片段与来源 |
| 知识库 | kb_list | 列出全部知识条目 |
| 知识库 | kb_delete | 按 id 删除知识 |
| 业务 | order_lookup | 按订单号 / 手机号查订单状态 |
| 业务 | refund_status | 按退款单 / 订单号查退款进度 |
| 业务 | shipping_query | 按订单号查物流轨迹 |
| 业务 | complaint_escalate | 生成投诉工单并升级人工 |

可靠性约束：业务数据只来自工具，查不到即返回 NOT_FOUND，绝不编造；不做资金变更；政策回答必须标注来源。

🏗 总体架构

┌────────────────────────────────────────────────────────────┐
│                      对话交互层 (Chat)                       │
│   意图识别 · 多轮追问 · SOP 话术 · 转人工兜底 · 来源引用       │
└──────────────┬───────────────────────────┬─────────────────┘
│                           │
┌───────▼───────┐           ┌───────▼───────┐
│ 知识库检索层    │           │ 工具/插件编排层 │
│ 分块·索引·打分  │           │ 订单·退款·物流  │
│ (轻量 RAG)     │           │ ·工单          │
└───────┬───────┘           └───────┬───────┘
│                           │
┌───────▼───────────────────────────▼───────────────┐
│            LLM 编排层（模型路由 + 提示词组装）        │
└───────┬───────────────────────────┬───────────────┘
│                           │
┌───────▼───────┐           ┌───────▼───────┐
│  知识库数据     │           │  业务数据       │
│ (政策/FAQ)     │           │ (订单/退款/物流)│
└───────────────┘           └───────────────┘

测试层（贯穿全程）：用例库 · 功能测试 · 报告 · 缺陷闭环

📁 目录结构

.
├── README.md                          # 本文件
├── LICENSE                            # MIT
├── preset/                            # DeepSeek Harness 预设（可直接部署）
│   ├── agent.cordis.yml               # 组合：人设 + 工具行 + ask_user_question
│   ├── aftersales.mjs                 # 8 个工具实现（零依赖 ESM 模块）
│   └── preset.yml                     # 预设元数据
├── demo-data/
│   └── kb.json                        # 知识库种子数据（6 条售后政策）
└── docs/                              # 方案文档
├── 01-项目方案与总体架构.md
├── 02-功能与产品设计.md
├── 03-知识库与插件技术设计.md
└── 04-测试方案与工具优化.md

🚀 快速开始

方式一：DeepSeek Harness 预设部署（推荐，约 1 分钟）

1. 把 preset/ 整个目录复制到 DSH 的用户预设根：

Copy-Item -Recurse .\preset "$env:DSH_HOME\.agent-presets\ecommerce-aftersales"

2. 打开 DeepSeek Harness Web GUI，新建会话，预设选择「电商售后客服」。

3. 直接开聊（演示话术）：

| 演示什么 | 说什么 |
| --- | --- |
| 政策检索（带来源） | 「退货有什么要求？」 |
| 标签过滤 | 「查查运费相关的退货规定」 |
| 查订单 | 「订单 SO20260601001 现在什么状态」 |
| 查退款 | 「我的退款到哪了？订单 SO20260601001」 |
| 查物流 | 「SO20260605002 物流到哪了」 |
| 上传知识 | 「把《保价赔付规则》上传到知识库：商品运输途中丢失的，已保价按保价金额赔付…」 |
| 投诉升级 | 「我要投诉 SO20260605002，发货延迟好几次」 |
| 异常兜底 | 「查一下单号 SO9999999999」→ 返回未查到，绝不编造 |

方式二：仅作方案参考

不部署也可直接阅读 docs/ 四篇文档，按「项目背景与架构 → 功能设计 → 技术设计 → 测试方案」的顺序即可完整了解整个项目。

🔍 知识库与检索

- 上传管线：格式校验 → 按段落分块（≤512 字/块）→ 归一化 → 词元化（中文 bigram + 英文词）→ 建索引。
- 检索算法（轻量级，无向量库）：score = 词元重叠分 + 标签匹配，按分降序取 top-k，返回片段 + 来源标题。
- 演进路线：知识规模增长后可平滑升级为「embeddings 向量检索 + 关键词混合召回 + LLM 重排」，上层接口不变。
- 种子数据：demo-data/kb.json 含 6 条售后政策（无理由退货 / 换货 / 退款时效 / 运费 / 发票 / 联系方式）。

🔌 插件与错误处理

每个业务能力一个插件，接口契约化，统一错误码：

| 错误码 | 含义 | 处理 |
| --- | --- | --- |
| NOT_FOUND | 数据不存在 | 返回「未查到 + 请核实单号」，不编造 |
| INVALID_ARGS | 参数缺失/非法 | 返回校验提示 |
| SYSTEM_ERROR | 外部系统异常 | 「系统繁忙，请稍后或转人工」 |

演示内置 Mock 订单数据；生产将 aftersales.mjs 中的模拟数据替换为真实订单系统 API 即可。

🧪 测试

- 分层策略：单元/接口层、功能层、回归层、端到端层、提示词评测。
- 断言方式：确定性能力（检索打分、工具返回、参数校验）做强断言可自动化；生成性能力做规则断言 + 人工抽检。
- 缺陷闭环：登记 → 修复 → 回归 → 关闭，未闭环缺陷不视为完成。
- 环境与工具：隔离测试环境 + Mock 数据一键重置 + 用例库 + 度量指标。

详见 docs/04-测试方案与工具优化.md。

📚 文档

| 文档 | 内容 |
| --- | --- |
| 01-项目方案与总体架构 | 背景 / 场景 / 分层架构 / 选型 |
| 02-功能与产品设计 | 对话 / 知识库 / 插件 三大功能与优先级 |
| 03-知识库与插件技术设计 | 检索算法 / 插件契约 / 数据模型 / 演进路线 |
| 04-测试方案与工具优化 | 测试策略 / 用例 / 执行 / 报告 / 闭环 / 环境与工具 |

📄 License

MIT