1. 这是什么
zvex-trade 是一个 MCP 数据连接器：把真实贸易数据（企业记录、海关线索、企业档案）以受控查询的方式接入你的 AI 客户端。连接器解决"能不能查到"，你的 AI 解决"怎么用"——各司其职。
数据诚实性是本连接器的核心设计：每次查询随附数据盲区声明（meta.coverage_gaps），告诉你这条数据哪里薄、结论该打多少折扣——我们不掩盖短板。
2. 能查什么
| 能力 | 说明 | 状态 |
|---|---|---|
| search_company | 按国家/行业/产品/企业名筛选候选企业（分页 + 签名游标） | ✓ |
| profile_company | 单家企业研究卡：事实、匹配证据、反向证据、核实问题 | ✓ |
| describe_coverage | 一句话报某市场能查什么（免费） | ✓ |
| account_status | 当前层级、当日用量与剩余额度 | ✓ |
| research tasks | 研究任务的读取 / 取消 | ✓ |
| hs_filter / time_filter / trade_amount_trend / trade_history / verified_contact | HS 筛选、时间窗过滤、金额趋势、交易史、已验证联系人——数据不支持，如实关闭 | ✗（如实声明） |
数据规模与盲区以 describe_coverage 的实时返回为准，不要凭印象假设。
3. 接入
WorkBuddy（推荐）
- WorkBuddy → 连接器市场 → 搜索「声桥」/「zvex-trade」→ 安装。
- 授权后对 AI 说一句：「巴西市场能查到什么？」——返回带盲区声明的数据边界即接通。
Claude Code / Cursor（手动配置）
{ "mcpServers": { "zvex-trade": {
"url": "https://zvex.cn/trade/mcp",
"headers": { "Authorization": "Bearer <你的API密钥>" }
} } }
自建 Agent
直连 POST https://zvex.cn/trade/mcp（Streamable HTTP：initialize → mcp-session-id → notifications/initialized → tools/call）。服务端 initialize 会下发使用纪律（instructions）——自建 Agent 必须把它放进 system prompt；HTTP 超时建议 ≥60 秒；API 密钥只保存在你自己的服务端，不要下发到客户端或前端。
4. 授权与账号
- 两种形态：账号登录（WorkBuddy OAuth）或 API 密钥（Bearer）。不要同时配——同一端点两条连接，鉴权迟早过时，表现为"时好时坏"。
- 密钥只保存在你自己的服务端 / 客户端配置里；不要提交进代码仓库或发给他人。
- 新账号自带免费体验期（每日 10 次查询）；到期后升级个人版即恢复。
5. 自检与连不上自查
自检脚本（trade_check.sh，随安装包附带）只探测不改动：
bash trade_check.sh # 无密钥：验证端点在线 + 鉴权开启 ZVEX_TRADE_KEY=sk-xxx bash trade_check.sh # 带密钥：验证密钥有效 + 工具可用
六态输出：✓ N 个工具可用（就绪）／✗ 密钥无效（401）（去控制台重发）／✗ 无法连接（网络/DNS）／✗ 预期外状态码，请反馈／✓ 账号形态：本机无密钥属正常／密钥被客户端加密存储读不到时，带 --key 重跑验证。
装后你会看到什么：连接列表出现「声桥连接器 · 已连接」；对 AI 说「美国市场能查到什么」返回带盲区声明的数据边界。
6. 工具搜不到？先怀疑客户端
典型现象（按顺序排查）：
- 客户端截断了能力清单——部分客户端只展示前 N 个工具或按名字过滤；
- AI 凭印象猜工具名——模型编造了不存在的工具/参数，查询退化成空跑；
- 配置写错端点 / 密钥形态混用——见第 4 章双形态冲突。
硬判据：让 AI 报出它准备调用的参数名清单，对照第 2 章能力表核存在性。报不出来或对不上 = 客户端截断 / 模型幻觉，不是连接器问题。
反馈请带四样：哪个客户端 / 哪个能力 / AI 报的参数名 / 对话原话截图。contact@zvex.cn
7. 怎么问（12 个真实场景例）
以下例子的返回均为实测节选（2026-11-05 生产环境）。
你得到：
{"has_records": true, "volume_bucket": "medium", "coverage_gaps": [hs_code_missing, …]}——有记录、量级中等、附盲区声明与中英文写法提示。你得到：candidates 数组（display_name / company_handle / country / supplier / source_segment…）+ next_cursor 分页游标 + meta.coverage_gaps 盲区声明。
你得到：研究卡（facts / matching_evidence / counterevidence / verification_questions）+ 双名核对（海关登记名 vs 企业档案名，不一致会提示"先核实再跟进"）。不含联系方式。
你得到：
result_state: "not_collected"，warnings[0] =「未采集：本库没有该市场的记录——这不是风险信号，是数据源尚未覆盖该市场（本次不计入查询次数）」。你得到：
{"tier": "personal", "daily_used": 3, "daily_limit": 500, "balance_remaining": 497}。X-Idempotency-Key 24h 内重放：返回首次缓存结果 + warnings「幂等键命中，本次未重复扣费」+ meta.idempotent_replay = true。8. 计费
- 什么算一次：有结果的 search_company 调用计 1 次；翻页每页各计 1 次。
- 什么不算：零结果 / 未采集 / 故障 / 幂等重放 / describe_coverage / profile / account_status——均不计费。
- 每次响应的
billing键携带本次是否计数与当日剩余；额度数字与明细见控制台（体验期与个人版额度以控制台为准）。
9. 提示含义
| 提示/编码 | 含义 | 结论怎么打折扣 |
|---|---|---|
| hs_code_missing | 未收录 HS 编码字段 | 品类匹配靠文本，存在品类误判可能 |
| amount_missing | 未收录金额字段 | 「大买家」类结论不可证实 |
| date_sparse | 无可用贸易日期字段 | 无法做时间窗 / 频次 / 趋势判断 |
| country_partial | 约四成海关记录缺国家标注 | 按国家筛选会漏掉这些记录，「某国没有此产品」不可靠 |
| data_lag | 时间为入库时间非交易时间 | 时效性结论不可靠，以 meta.data_as_of 为准 |
| zero_result | 真没有：市场有记录但筛选无匹配 | 可换行业 / 品名关键词再试 |
| not_collected | 未采集：数据源未覆盖该市场 | 不是风险信号，别误读成"该市场干净" |
| 双名不一致 | 海关登记名 ≠ 企业档案名 | 以此为信号先核实再跟进，系统不掩盖 |
10. FAQ 与版本
- 查出来是空的，是不是数据不行？先看 warnings[0]：区分「真没有」与「未采集」；再用 describe_coverage 确认边界。
- AI 回答里没有数据，全是它自己编的？第 6 章硬判据：让它报参数名对照能力表。
- 能导出吗？单查询页面上限见 account_status；更大批量属企业版，联系 contact@zvex.cn。
- 数据多久更新？以 meta.data_as_of（活动快照时间）为准。
版本：本手册对应连接器 v0.5.0（initialize 的 serverInfo.version 可查）。