SupplyChainOS — 跨境供应链AI指挥塔

1人 + 5个AI Agent = 一个完整的跨境供应链部门

🎯 项目定位

SupplyChainOS 是面向跨境OPC卖家的AI供应链指挥系统，覆盖采购→质检→清关→物流→仓储→履约全链路。通过5个AI Agent、15个专业Skill和可视化指挥塔仪表盘，让1个人拥有6人供应链团队的管控能力。

🏗️ 架构

用户 → 指挥塔仪表盘 → Agent编排层 → Skill执行层 → 数据+AI推理层
         │                  │              │              │
    Vue 3 + ECharts     5 Agents       15 Skills      GLM-5.1 深度思考
    全自定义CSS         Orchestrator    Python async   + Smart Mock 降级
    WebSocket Chat     _route_to_skills   data/        三级降级策略

5 个 Agent

Agent	职责	串联Skills
🏭 采购Agent	供应商搜索→比价→风险评估→合同审查	sourcing-search → sourcing-compare → risk-assess → sourcing-contract
🔬 质检Agent	验厂SOP→质检报告解读→风险标注	qa-sop → qa-inspect → risk-assess
🛃 清关Agent	HS编码→单据提取→清关预检→申诉	customs-hscode → customs-extract → customs-precheck → customs-dispute
🚢 物流Agent	路线规划→物流追踪→库存预测→补货	logistics-route → logistics-track → warehouse-forecast → warehouse-restock
🏗️ 指挥塔Agent	全链路诊断→瓶颈识别→调度方案	supplychain-diagnose + 协调其他4个Agent

15 个 Skills

分类	Skills
🏭 采购	供应商搜索 / 供应商比价 / 合同审查
🔬 质检	验厂SOP生成 / 质检报告解读
🛃 清关	HS编码查询 / 单据提取 / 清关预检 / 清关申诉
🚢 物流	路线规划 / 物流追踪
📦 仓储	库存预测 / 补货建议
🔧 全局	风险评估 / 供应链诊断

🖥️ 界面总览

📊 指挥塔总览（仪表盘）

区域	内容	说明
流程图	采购→质检→清关→物流→仓储→履约	彩色状态标识，点击跳转Agent
统计卡片	本月营收 / 本月成本 / 净利润 / 供应链健康度	⭐四个核心KPI
数据面板(6个)	库存概览 / 仓库状态 / 在途货物 / 实时预警 / 供应商TOP3 / 财务明细	点击自动跳转Agent分析
趋势图	库存趋势(近3月) / 营收&利润趋势(近3月)	ECharts折线+柱状图
数据轮换	3组数据每10秒自动切换	观察不同运营状态

🤖 Agent工作台

功能	说明
Agent标签切换	5个标签，选中后显示对应快捷指令
快捷指令	每个Agent 2-3个，一键触发AI分析
左侧面板	Agent描述 + KPI指标(4个) + 串联Skills + 执行流程
左侧表格	核心结构化数据表格
右侧饼图	Agent专项图表（采购分布/质检合格率/关税率/运输方式/瓶颈类型）
右侧结果	AI分析结果文本

⚡ Skill工具箱

• 15个Skill网格展示（图标+名称+分类+描述）
• 点击运行，右侧显示文字结果+图表
• 每个Skill对应独立图表和结构化表格

💬 指挥塔对话

• 右侧对话面板，WebSocket实时通信
• LLM推理模式 或 Smart Mock演示模式
• 支持多轮对话记忆（最近3轮上下文）
• LLM质量检查：回复少于5个中文时自动降级到Smart Mock

🗺️ 智能路由

Agent	触发关键词
🏭 采购Agent	采购、供应商、找货、比价、合同、sourc
🔬 质检Agent	质检、验厂、sop、检测、品控、qa、quality
🛃 清关Agent	清关、报关、hs、关税、custom
🚢 物流Agent	物流、运输、发货、运费、库存、预测、仓储、补货、路线、追踪、logist
🏗️ 指挥塔Agent	诊断、瓶颈、问题、状态、全景、财务、营收、利润、diagnos、其他

🚀 新手引导

• 首次加载自动弹出5步引导教程
• 顶栏「🚀 新手引导」按钮可随时查看
• 5步覆盖：欢迎介绍→指挥塔总览→Agent工作台→对话面板→完成

🤖 AI 推理

三层架构：规则先行 + LLM增强 + 优雅降级

请求 → Skill._run()
         ├─ 1. 规则引擎快速匹配（确定性、低延迟、零外部依赖）
         └─ 2. LLM推理增强（低置信度/复杂场景自动触发）
              ├─ 构建结构化Prompt（数据上下文+任务指令）
              ├─ 调用GLM-5.1深度推理
              └─ 结果融合：LLM分析文本 + 规则结构化数据
         └─ 3. 优雅降级：LLM不可用 → 规则数据+Mock分析 → 无Key → 纯Mock

模式	触发条件	行为
LLM 推理	配置 LLM_API_KEY + .env.local	GLM-5.1 深度思考 (reasoning_content + content)
规则+LLM增强	Skill层	规则匹配先行，低置信度场景LLM二次推理
Smart Mock	无 API Key 或 LLM 失败	根据消息内容生成专业供应链回复

已实现LLM增强的Skill

Skill	AI增强方式	效果
供应商搜索	LLM生成推荐理由+注意事项	语义理解替代纯评分排序
HS编码匹配	LLM对低置信度/复杂描述二次推理	编码准确度提升15-30%
库存预测	LLM生成补货策略建议	数值报告→可执行方案
供应链诊断	LLM全链路深度诊断+跨瓶颈联动	单点修复→全局战略
物流路线	LLM综合策略建议	评分排序→场景化推荐

三级降级策略

GLM-5.1 推理 → reasoning_content 提取 → Smart Mock 专业模板

算力平台配置

# .env.local（已gitignore，不上传至仓库）
LLM_API_KEY=sk-your-key
LLM_BASE_URL=https://ai.synnovator.com/v1
LLM_MODEL=glm-5.1

遵循《算力使用指南》

• §1: messages 规范校验（system仅首位、user/assistant交替、末位user）
• §1: response_format: {"type": "json_object"} JSON 模式
• §4: 流式(chat_stream) / 非流式(chat) 双模式
• §5: reasoning_content 深度思考双通道解析
• §6: 429限流指数退避+抖动+3次重试

🚀 快速开始

# 安装依赖
pip install -r backend/requirements.txt

# 启动服务
python -m uvicorn backend.main:app --host 0.0.0.0 --port 7860

# 运行测试
python tests/test_all.py

打开浏览器访问 http://localhost:7860

📊 测试结果

Skill 增强测试: 50+ checks ✅
Agent 集成测试: 5/5 ✅
鉴权中间件测试: ✅
LLM 模式: Smart Mock (配置API Key后自动升级为GLM-5.1)

📁 项目结构

s2/
├── README.md               # 本文档
├── SPECS.md                # 产品规格
├── DEMO.md                 # 演示指南
├── .env.local              # LLM配置（gitignore）
├── .gitignore
├── backend/
│   ├── main.py             # FastAPI入口 + 安全中间件 + API Key鉴权
│   ├── llm_client.py       # GLM-5.1统一接口 + Smart Mock + Skill层LLM增强
│   ├── requirements.txt
│   ├── skills/             # 15个Skill实现
│   │   ├── __init__.py
│   │   ├── registry.py     # Skill注册表（v2优先+v1兼容）
│   │   ├── base.py         # BaseSkill基类
│   │   ├── sourcing_search_v2.py    # ✅ LLM增强
│   │   ├── sourcing_compare_v2.py
│   │   ├── sourcing_contract_v2.py
│   │   ├── qa_sop_v2.py
│   │   ├── qa_inspect_v2.py
│   │   ├── customs_hscode_v2.py     # ✅ LLM增强
│   │   ├── customs_extract_v2.py
│   │   ├── customs_precheck_v2.py
│   │   ├── customs_dispute_v2.py
│   │   ├── logistics_route_v2.py    # ✅ LLM增强
│   │   ├── logistics_track_v2.py
│   │   ├── warehouse_forecast_v2.py # ✅ LLM增强
│   │   ├── warehouse_restock_v2.py
│   │   ├── risk_assess_v2.py
│   │   └── supplychain_diagnose_v2.py # ✅ LLM增强
│   ├── agents/
│   │   └── orchestrator.py # Agent编排器 + _smart_reply + _route_to_skills
│   └── data/
│       ├── inventory.json  # 93天趋势 + 3组轮换数据
│       ├── suppliers.json
│       ├── routes.json
│       ├── hs_codes.json
│       └── cases.json
├── frontend/
│   └── index.html          # Vue 3 + 全自定义CSS + ECharts 指挥塔仪表盘
├── docs/
│   └── ADR-001-mock-first-mvp.md
├── tests/
│   └── test_all.py
└── deploy/
    ├── Dockerfile
    ├── docker-compose.yml
    └── nginx.conf

🛠️ 技术栈

层级	技术
前端	Vue 3 (Prod CDN) + 全自定义CSS + ECharts 5
后端	Python 3.12 + FastAPI + WebSocket
编排	Orchestrator（路由→执行Skill→LLM/Smart Mock解读）
AI	GLM-5.1（Synnovator）+ 规则先行LLM增强 + Smart Mock三级降级
鉴权	API Key（X-API-Key / Bearer），空Key=开发模式
数据	JSON（93天趋势模拟）+ 3组运营场景轮换
部署	Docker + Nginx + uvicorn
测试	增强测试（结构+质量双重校验 + 鉴权测试），100%通过