Skip to main content
Glama
BizDig Trade

BizDig Trade

by alonexun
README.md
# BizDig Trade

[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/Python-3.11+-3776AB.svg)](https://www.python.org/)
[![Tests](https://img.shields.io/badge/Tests-passing-brightgreen.svg)](#六本地开发)

Deterministic MCP tool service for China export analysis / 外贸出口分析的 MCP 工具服务。

**定位**:6 个确定性数据工具(`bt_*`,MCP Server)+ 3 份方法论技能文档(`skills/`),为宿主 AI(如 WorkBuddy)提供外贸出口分析的数据底座与分析方法。所有工具均为纯确定性计算(本地字典 + UN Comtrade 官方数据),**不含 LLM**;推理、行业知识与联网信息收集由宿主 AI 承担。

```
bizdig-trade/
├── server/            # MCP Server(Streamable HTTP)+ 6 个 bt_ 工具注册
├── tools/             # 确定性计算核心(Comtrade 客户端/HS 匹配/市场筛选/生命周期)
├── data/export/       # 本地数据字典快照(HS2022/宏观指标/产业集群/区域表,随版本发布)
├── data/cache/        # 运行时缓存 + 每日配额计数(gitignore,仅存在于部署机)
├── skills/            # 3 份方法论 SKILL.md(供宿主 Agent 加载)
├── metering/          # API Key 生成、用量统计、免费额度限额
├── connector/         # WorkBuddy Connector 市场发布包
├── deploy/            # systemd + nginx 部署工件与手册
└── tests/             # pytest 测试套件(103 passed / 2 skipped)
```

---

## 一、WorkBuddy 个人用户接入指引

### 1. 添加 MCP Server

1. 自行部署本服务(见 [deploy/DEPLOY.md](deploy/DEPLOY.md)),或使用实例提供方提供的两个信息:服务地址(形如 `https://<你的域名>/mcp`)与 API Key(`X-API-Key` 请求头的值,服务方通过 `python -m metering.gen_key "标签"` 生成);
2. 在 WorkBuddy 的 MCP 连接设置中新增连接,类型选择 **Streamable HTTP**;
3. 地址填写 `https://<你的域名>/mcp`;
4. 请求头添加 `X-API-Key: <你的key>`;
5. 保存并启用连接,确认工具列表中出现 6 个 `bt_` 开头的工具。

也可以直接在 WorkBuddy Connector 市场搜索并安装 **BizDig Trade** 连接器(Connector 包见 [`connector/`](connector/README.md)),按表单填入服务地址与 API Key 即可,无需手工配置请求头。

### 2. 把 SKILL.md 提供给 Agent

MCP 只负责"给数据","怎么分析"由 3 份方法论文档规定。任选一种方式把 `skills/` 下的 SKILL.md 内容交给 WorkBuddy 的 Agent:

- **粘贴**:对话开始时把对应主题的 SKILL.md 全文粘贴进对话;
- **附件**:把 SKILL.md 文件作为附件上传到当前对话;
- **知识库**:把 3 份文件加入 WorkBuddy 知识/知识库,Agent 按需检索。

三份文档各有"触发条件"一节,说明什么问题该用哪份方法:
- 问题偏"出口去哪个市场、趋势如何" → `SKILL_出口市场调研.md`
- 问题偏"货源、产业集群、内外贸" → `SKILL_货源与供应链.md`
- 问题偏"客户类型、开发渠道、地缘风险" → `SKILL_客户开发与地缘风险.md`

### 3. 首次验证

接入完成后问一句:**"燃料电池出口东南亚怎么样?"**

正常表现:Agent 先调用 `bt_hs_match` 匹配 HS 编码,再调用 `bt_market_screen` 粗筛东南亚候选市场,然后对重点国家调用 `bt_trade_curves` / `bt_bilateral`,最终给出带 HS 编码、国家列表、六维评分与数据来源说明的分析。若收到 401,检查 `X-API-Key` 是否正确;若工具不可见,检查地址是否以 `/mcp` 结尾。

---

## 二、工具一览

| 工具 | 用途 | 关键参数 |
|---|---|---|
| `bt_hs_match` | 产品关键词 → HS 编码列表(字面/语义双通道匹配),无匹配时给出改写建议 | `keyword`:产品关键词(中文/英文)或 4/6 位 HS 编码 |
| `bt_market_screen` | 基于 WDI 宏观指标(GDP/人均 GDP/增长率)预筛选候选出口市场,附生命周期阶段与确定性评分 | `hs_code`:HS 编码;`region`:可选区域(中文名如"东南亚"或区域代码);`min_gdp`:可选最低 GDP 门槛(美元) |
| `bt_trade_curves` | 贸易双曲线:目标国自华进口 + 中国全球出口的季度趋势、CAGR 与生命周期阶段 | `hs_code`:HS 编码;`country`:目标国 ISO alpha-2 代码(如 VN/US/JP) |
| `bt_bilateral` | 目标国自华年度进口额(镜像口径,比中国自报出口更完整可靠),年份自动回退 | `hs_code`:HS 编码;`country`:目标国 ISO alpha-2 代码 |
| `bt_industry_map` | 产品关键词 → 行业分类 + 国内产业集群城市列表与集聚统计 | `keyword`:产品关键词(也可传 HS 编码) |
| `bt_validate` | 对 Agent 生成的结论(集群城市/商家名单)做本地交叉验证,输出综合置信度评分 | `hs_code`:HS 编码;`country`:目标国 ISO alpha-2 代码;`metrics`:待验证指标字典(`industry_clusters`/`merchants`) |

所有工具不抛异常:数据不可得、触发 UN Comtrade 每日配额软限(450 次)或超出免费额度时,返回 `degraded: true` 与中文说明,由宿主 Agent 降级处理。

---

## 三、SKILL.md 使用说明

`skills/` 下 3 份方法论文档(中文)规定了宿主 Agent 的分析框架,每份均包含:触发条件(含例句)、角色与目标、方法论步骤(每步的 bt_ 工具、参数与返回解读)、工具组合建议(典型调用链)、输出结构(结论先行/六维评分/数据表格/置信度标注)、置信度标注要求(高=官方统计直接命中、中=推导/缓存、低=估算且必须明示)、边界与降级(degraded 措辞与联网分工)。

要点:
- **工具是数据、技能是方法**:Agent 应先按 SKILL.md 的步骤调用工具取数,再按其模板组织输出;
- **置信度铁律**:官方数据(data_source=comtrade)、缓存/推导(cache)、估算三类数字必须区分标注,低置信必须明示;
- **联网分工**:MCP 工具不联网收集情报;最新关税政策、地缘动态等实时信息由宿主 Agent 用其原生搜索能力补充(《SKILL_客户开发与地缘风险》内附逐国搜索 checklist);
- 用户要"一份完整出口报告"时,按 7 段式(货品概览/货源集聚/内外贸对比/目标市场推荐/营销策略建议/场景策略/行动建议)联合三份技能完成。

---

## 四、权限声明与用量计量

- 本服务仅访问**部署机上的本地数据文件**与 **UN Comtrade 公共 API**(comtradeplus.un.org);
- 不读写用户本地文件,不访问其他任何网络资源;
- `X-API-Key` 仅用于服务端请求鉴权与**免费额度计量**(每 Key 每日默认 20 次,超出当日降级);
- 服务端在 SQLite 中记录调用日志(key 后 6 位、工具名、耗时、缓存命中、Comtrade 消耗),仅用于配额管理与用量统计,不含对话内容。

---

## 五、卸载说明

个人用户在 WorkBuddy 中**移除 MCP 连接即完成卸载**,客户端无本地残留。服务端不向用户设备写入任何文件;如需彻底停用某用户,服务方删除(或从 `BIZDIG_API_KEYS` 中移除)对应 API Key 即可。

---

## 六、本地开发

### 环境要求

Python 3.11+(仅需标准库 + 下方依赖;无数据库、无其他服务)。

### 安装与配置

```powershell
pip install -r requirements.txt   # requests / pytest / mcp[cli]
```

在项目根目录创建 `.env`(参考 `.env.example`):

```
COMTRADE_API_KEY=<你的 UN Comtrade API Key,不配则实时拉取类工具降级>
BIZDIG_PORT=<监听端口,默认 8800>
BIZDIG_API_KEYS=<逗号分隔的 X-API-Key 白名单,不配则全放行>
BIZDIG_DAILY_LIMIT_PER_KEY=<每 Key 每日工具调用上限,默认 20;<=0 不限制>
BIZDIG_CACHE_DIR=<运行时缓存目录,默认 data/cache/(已 gitignore)>
```

> **免费额度**:每个 API Key 每日默认 20 次工具调用(超出当日返回 `degraded` 降级结果,UTC 0 点重置)。额度说明注入在每个工具的描述中,Agent 会在首次调用时向用户转述。公共实例务必保持限额——服务端共享单个 Comtrade key(每日 450 次软限)。私有部署可设 `<=0` 放开。

### 启动与测试

```powershell
python -m server.main        # 启动 MCP Server(Streamable HTTP,0.0.0.0:BIZDIG_PORT,路径 /mcp)
python -m pytest tests -v    # 运行测试套件(mock 网络,不消耗 Comtrade 配额)
```

### API Key 管理

```powershell
python -m metering.gen_key "用户标签"   # 生成新的 X-API-Key
python -m metering.stats                # 查看各 key 的调用统计
```

Linux 服务器部署(systemd + nginx + HTTPS)参见 [deploy/DEPLOY.md](deploy/DEPLOY.md)。

---

## 七、数据来源与更新频率

| 数据 | 来源 | 更新方式与频率 |
|---|---|---|
| 双边贸易额/贸易双曲线 | UN Comtrade Plus API(官方统计) | 查询时实时拉取并写入 `data/cache/` 运行时缓存(30 天 TTL,配额耗尽时作降级数据源);每日配额软限 450 次(计数持久化,重启不归零)。年度数据有 12–18 个月发布滞后,工具按候选年份链(近 4 年)自动回退 |
| 宏观指标(GDP/人均 GDP/增长率) | 世界银行 WDI | 随 `data/export/market_profiles.json` 静态发布,版本化更新 |
| HS 编码字典/行业关键词/产业集群分布 | 本地 `data/export/*.json`(HS2022 章节 + 产业园分布) | 随版本发布更新 |

---

## License & Data Attribution

代码以 [Apache License 2.0](LICENSE) 开源发布。

第三方数据归属(数据本身遵循各自提供方的条款,不随本仓库的代码许可证重新授权):

- 宏观指标(GDP/人均 GDP/增长率)编译自世界银行 **World Development Indicators (WDI)**,数据文件按 **CC BY 4.0** 使用(© World Bank,worldbank.org);
- 双边贸易数据运行时经 **UN Comtrade Plus API**(comtradeplus.un.org,联合国统计司)获取,使用时请遵守 UN Comtrade 使用条款;
- HS2022 编码字典、行业关键词与产业集群数据由本项目维护。