货代行业智能 Agent 平台文档

项目愿景

一句话愿景：建设货代行业的 AI 业务操作系统，让每一次咨询、单证处理和异常处置都能被执行、记忆和复用。

这不是单点聊天机器人项目，而是一个货代行业通用智能 Agent 平台。平台以 ai_service 为业务真相源，面向海运、空运、陆运、多式联运等场景，解决三类核心问题：

流程割裂：客服、单证、执行、回写分散在多个系统，协同成本高。
经验流失：历史处理过程沉淀不足，AI 无法跨会话持续学习与建议。
交付低效：每家客户都重复定制，新增功能周期长、质量不稳定。

平台的目标价值是把业务能力标准化为可编排模块，统一承载：

智能客服与人工协同
单证识别与结构化抽取
OCR 与规则核验
定时任务与事件驱动任务
用户业务记忆与历史回溯
工具接入与系统联动
管理员可配置的低代码治理能力

v1 边界说明：

不追求终端用户直接编写复杂插件代码。
不允许 AI 生成代码绕过评测和审批直接上线。
不把演示前端或网关作为业务主状态存储层。

项目目标

业务目标

把货代企业常见流程沉淀成标准能力，减少重复开发。
把 AI 能力从“问答工具”升级为“可执行业务动作”的运行平台。
把交付方式从“定制项目制”升级为“配置加插件制”。

产品目标

支持 API 优先集成，也支持用户自定义页面承载业务流程。
支持管理员通过代码和低代码双轨定制业务能力。
支持在新增功能时快速扩展，核心依赖 AI 生成代码加速交付。

工程目标

保证全链路可观测、可审计、可回放。
保证插件可插拔、可版本化、可灰度发布。
保证前端替换不影响业务主状态完整性。

核心能力矩阵

能力域	平台能力	典型货代场景
会话协同	AI 主答、人工接管、协作建议	客服咨询、异常单处理
文档智能	OCR、单证分类、字段抽取、结构化输出	提单、装箱单、发票、报关单
知识检索	文档入库、切分、向量检索、引用返回	航线政策、报价规则、SOP
业务记忆	历史事实沉淀、跨会话回溯、经验建议	历史异常复盘、同类单据建议
工具执行	MCP 工具挂载、参数校验、调用审计	运价查询、轨迹查询、系统回写
自动任务	定时触发、重试补偿、执行审计	日报生成、对账巡检、异常提醒
平台治理	多租户、权限、发布门禁、回滚	集团与分公司统一管控

快速开始

uv venv
uv sync --all-groups
uv run python main.py

文档本地预览：

just mkdocs-serve

平台总体架构

flowchart LR
  subgraph UseLayer[使用层]
    EndUser[业务用户]
    Operator[管理员与实施]
  end

  subgraph ExperienceLayer[体验层]
    OpenAPI[开放接口]
    CustomUI[自定义页面]
    AdminUI[管理控制台]
  end

  subgraph RuntimeLayer[运行时]
    ApiService[AI Service API]
    AgentKernel[Agent Kernel]
    MultiAgentRouter[多 Agent 路由]
    HilStateMachine[人机协同状态机]
    MemoryEngine[业务记忆引擎]
    PluginRuntime[插件运行时]
  end

  subgraph DataLayer[数据层]
    Postgres[PostgreSQL]
    Qdrant[Qdrant]
    Minio[MinIO]
    MemoryStore[Memory Store]
    AuditTrace[审计与追踪]
  end

  EndUser --> OpenAPI
  EndUser --> CustomUI
  Operator --> AdminUI

  OpenAPI --> ApiService
  CustomUI --> ApiService
  AdminUI --> ApiService

  ApiService --> AgentKernel
  AgentKernel --> MultiAgentRouter
  AgentKernel --> HilStateMachine
  AgentKernel --> MemoryEngine
  AgentKernel --> PluginRuntime

  MemoryEngine --> MemoryStore
  PluginRuntime --> Postgres
  PluginRuntime --> Qdrant
  PluginRuntime --> Minio
  AgentKernel --> AuditTrace

定制与扩展模式

平台采用三层扩展模型：

代码优先：开发团队实现插件、策略和复杂业务逻辑。
低代码治理：管理员通过 UI 完成挂载、编排、权限、发布。
AI 辅助开发：基于需求描述生成插件初稿与测试用例，经评测后上线。

该模型确保“新增功能简单快捷”，同时保持生产可控。

当前阶段与路线

近期主线聚焦四个方向：

Runtime 协议稳定化：统一 Agent 请求响应、工具调用和追踪字段。
行业能力产品化：OCR 与单证解析插件化，沉淀可复用模板。
业务记忆落地：跨会话记忆写入、检索、回溯与建议链路打通。
治理闭环上线：评测门禁、灰度发布、回滚与审计链路打通。

文档阅读顺序

建议按以下顺序阅读：

getting-started.md - 环境搭建与快速启动
core/agent-runtime-v1.md - 货代 Agent 平台高层设计
core/agent-runtime-implementation.md - 架构实现指南（含代码）
core/architecture.md - 系统架构详细说明
guides/rag-knowledge-management.md - RAG 知识库管理
api/endpoints.md - API 端点参考
dev/evaluation.md - 评测与基准