跨境电商智能运营辅助 Agent

一个面向跨境电商场景的后端 MVP，围绕 RAG + Agent 架构提供平台规则问答、商品知识检索、客服回复建议、运营文案生成等能力。项目目标是把分散的知识、规则和运营经验统一到一个可部署、可扩展、可评估的智能运营辅助服务中。

当前版本已经支持本地启动、Docker 部署、知识入库、检索问答、客服回复建议、运营文案生成，以及通过 FastMCP 暴露工具接口。

项目简介

系统基于 Python + FastAPI + LangChain + ChromaDB + OpenAI API + FastMCP + RAGAS 设计，核心思路是：

1. 通过 RAG 检索平台规则、商品资料、客服 FAQ、运营 SOP 等知识。
2. 使用 Agent 进行任务拆解与工具调度，生成更贴近业务场景的答案。
3. 结合记忆机制记录店铺信息、商品属性和用户偏好，提升多轮对话质量。
4. 使用 RAGAS 和 Bad Case 追踪机制持续迭代检索与提示词策略。

核心能力

1. 平台规则问答：针对退款、宣传合规、发货承诺等规则场景给出可执行回答。
2. 商品知识检索：围绕商品属性、FAQ、卖点信息进行召回与回答生成。
3. 客服回复建议：结合 SOP、规则和会话上下文生成更稳妥的客户回复。
4. 运营文案生成：根据目标、商品信息和卖点输出标题、卖点和正文。
5. 混合检索链路：支持 BM25 + 向量检索 + RRF，并可选启用 reranker。
6. 记忆机制：支持短期会话缓存与长期业务记忆召回。
7. MCP 工具化：支持将规则检索、回复建议、文案生成通过 FastMCP 暴露。

架构概览

flowchart LR
  U[用户请求] --> API[FastAPI / app.main:app]
  API --> AGENT[ReAct Agent]
  AGENT --> RET[混合检索<br/>BM25 + 向量检索 + RRF]
  RET --> RERANK[BGE Reranker]
  RERANK --> LLM[OpenAI API]
  AGENT --> MCP[FastMCP 工具层]
  AGENT --> MEM[短期缓存 + 长期记忆]
  RET --> VDB[ChromaDB]
  LLM --> RESP[答案 / 文案 / 建议]

目录结构

.
├── app/
│   ├── main.py
│   ├── ...
├── scripts/
│   └── start_local.ps1
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── README.md

启动步骤

1. 准备环境变量

复制 .env.example 为 .env，并填写 OPENAI_API_KEY，或直接复用现有的 AI_API_KEY / AI_API_URL、IKUN_API_KEY / IKUN_API_URL。

推荐最小配置：

AI_API_KEY=你的key
AI_API_URL=https://api.ikuncode.cc/v1/messages
OPENAI_CHAT_MODEL=gpt-5

2. 本地启动

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\start_local.ps1

脚本会优先使用 Python 3.12 创建虚拟环境，然后安装项目依赖并启动 API。

3. Docker 启动

docker compose up --build

默认会暴露：

1. HTTP API: 8000
2. MCP: 9000

如需修改端口，可通过环境变量 APP_PORT、MCP_PORT 调整。

使用示例

1. 健康检查

curl http://127.0.0.1:8000/api/v1/health

2. 规则问答

curl -X POST http://127.0.0.1:8000/api/v1/qa/ask \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "demo-1",
    "question": "客户催退款，我能直接承诺马上退款吗？",
    "task_type": "rule_qa",
    "store_context": {
      "store": "us-main"
    }
  }'

3. 客服回复建议

curl -X POST http://127.0.0.1:8000/api/v1/customer-reply \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "demo-2",
    "question": "客户催退款，我应该怎么回复？",
    "task_type": "customer_reply",
    "store_context": {
      "store": "us-main",
      "product": "tumbler"
    }
  }'

4. 运营文案生成

curl -X POST http://127.0.0.1:8000/api/v1/operations/copy \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "copy-1",
    "objective": "listing优化",
    "product_name": "900ml 保温杯",
    "selling_points": ["防漏杯盖", "24小时保冷", "适配车载杯架"],
    "tone": "professional",
    "target_platform": "amazon"
  }'

环境变量说明

OpenAI 与模型

1. OPENAI_API_KEY：OpenAI API Key
2. OPENAI_BASE_URL：兼容代理或私有网关时使用
3. OPENAI_CHAT_MODEL：对话模型
4. AI_API_KEY / IKUN_API_KEY：现有 ikunapi 密钥别名
5. AI_API_URL / IKUN_API_URL：现有 ikunapi 的 messages 接口地址
6. OPENAI_EMBEDDING_MODEL：向量模型
7. OPENAI_RERANK_MODEL：重排模型

检索与知识库

1. CHROMA_PERSIST_DIR：ChromaDB 持久化目录
2. CHROMA_COLLECTION_NAME：知识库集合名
3. KNOWLEDGE_DIR：原始知识文件目录
4. DATA_DIR：统一数据目录
5. RETRIEVAL_TOP_K：最终返回条数
6. RETRIEVAL_CANDIDATE_K：初始召回条数
7. RRF_K：RRF 融合参数
8. ENABLE_RERANKER：是否启用 reranker

服务与日志

1. APP_HOST：HTTP 监听地址
2. APP_PORT：HTTP 监听端口
3. MCP_HOST：MCP 监听地址
4. MCP_PORT：MCP 监听端口
5. LOG_LEVEL：日志级别
6. LOG_FORMAT：日志格式
7. LOG_DIR：日志目录

常见接口

当前 MVP 已实现以下接口：

1. GET /api/v1/health：健康检查
2. GET /api/v1/healthz：兼容健康检查别名
3. POST /api/v1/knowledge/ingest：知识入库
4. POST /api/v1/qa/ask：规则问答 / 商品问答
5. POST /api/v1/customer-reply：客服回复建议
6. POST /api/v1/operations/copy：运营文案生成

设计约定

1. 主服务入口约定为 app.main:app
2. MCP 服务入口约定为 python -m app.mcp.server
3. HTTP 服务默认监听 8000
4. MCP 服务默认监听 9000
5. 检索层优先采用 BM25 + 向量检索 + RRF
6. 精排层可按配置启用 BGE Reranker
7. 记忆层采用“短期缓存 + 长期向量记忆”

项目结构

app/
  api/           HTTP 接口
  core/          配置与日志
  evaluation/    RAGAS 评估辅助
  mcp/           FastMCP 服务入口
  models/        Pydantic 数据模型
  services/      检索、生成、记忆、Agent 编排
data/
  sample_docs/   示例知识库文档
scripts/
  start_local.ps1
  seed_demo_data.py
tests/
  test_retrieval.py

开发说明

1. 当前仓库默认使用 Python 3.12 本地开发。
2. Windows 本地如果没有 C++ 编译环境，向量存储会回退为 JSON 持久化实现。
3. Docker 镜像安装 .[vector]，容器内优先使用 ChromaDB。
4. ENABLE_RERANKER=true 时需要额外安装 sentence-transformers。
5. 如需启用 RAGAS，可安装 pip install -e .[eval]。

后续扩展建议

1. 为知识入库增加定时任务和增量更新。
2. 增加评估数据集与自动回归测试，稳定 RAG 效果。
3. 把客服回复、文案生成、规则问答拆成独立工具节点，便于 Agent 编排。
4. 增加权限控制、审计日志和多租户隔离。
5. 引入观测体系，记录召回命中率、重排效果和回答采纳率。

部署说明

当前默认行为：

1. 本地 start_local.ps1 安装基础依赖并启动 API，适合 Windows 开发环境。
2. Docker 镜像安装 .[vector] 额外依赖，在容器内优先启用 ChromaDB 持久化检索。
3. 本地如果没有安装 Chroma 依赖，代码会回退到 JSON 持久化存储，保证 MVP 仍可启动和测试。

当前实现说明

1. Docker 构建默认安装 .[vector]，优先使用 ChromaDB 持久化检索。
2. 如果存在 AI_API_URL / IKUN_API_URL，服务会优先直连该 messages 接口；不存在时再走标准 OpenAI 兼容调用。
3. Windows 本地启动默认安装基础依赖；如果本机缺少 C++ 编译环境，服务会自动退回到 JSON 持久化向量存储以保证可运行。
4. ENABLE_RERANKER 默认关闭，安装 sentence-transformers 后可再开启。

当前限制

1. 当前示例知识库仍是演示数据，真实业务效果取决于后续导入的规则、FAQ、商品资料与 SOP 质量。
2. 目前未集成前端页面，主要以 API 和 MCP 服务形式提供能力。
3. 当前还没有接入数据库级多租户隔离、权限控制和审计体系。

使用约束

1. 本项目当前主要用于学习、作品展示和原型验证。
2. 生成内容仅作为运营辅助建议，涉及平台处罚、退款争议、合规判断时仍应由人工复核。
3. 请勿将真实密钥、隐私订单信息和敏感客户数据直接提交到仓库。