smart-trade-ai
AI assistant for international trade — 39 B2B skills (lead gen, OSINT, email, docs, compliance). End-to-end customer development pipeline. Runs locally. 外贸业务员 AI 助手。
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/chefroger/smart-trade-ai with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/chefroger/smart-trade-ai'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/chefroger--smart-trade-ai)HTML
<a href="/listings/chefroger--smart-trade-ai"><img src="/api/listings/chefroger--smart-trade-ai/badge.svg" alt="findsafeskills safety rating" /></a>Install
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 649 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # Smart Trade AI
- [](https://github.com/chefroger/smart-trade-ai/actions/workflows/test.yml)
- [](LICENSE)
- [](https://www.python.org/)
- [中文](README.md) | [English](README.en.md)
- > 本地运行 · 数据不出电脑。安装需稳定访问 GitHub;AI 生成内容仅供参考,关键决策请自行核实(详见[安装前须知](#安装前须知))。
- <div align="center">
- <h3>外贸业务员的 AI 助手</h3>
- <p>在本地运行,数据留在自己电脑里</p>
- </div>
- **写开发信、查客户背景、维护 B2B 平台——这些重复劳动,这个工具帮你 10 分钟搞定。界面支持中英双语切换,也适合外籍同事或海外团队使用。**
- ---
- <p align="center">
- <img src="docs/screenshot-1.png" alt="AI Chat Interface" width="75%">
- <br>
- <em>AI 对话界面 — 自动调用 web_search / read_file / database 工具</em>
- </p>
- ---
- ## 3 分钟上手
- **macOS / Linux**
- ```bash
- curl -fsSL https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.sh | bash
- ```
- **Windows(PowerShell)**
- ```powershell
- irm https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.ps1 | iex
- ```
- 脚本会自动检查 Python 3.14 环境、安装 Trade 本体和 44 个技能。**Hermes Agent 需要你先用官方安装器装好**(脚本会检查,缺了就提示你去装)。装完在终端输入 `trade`,浏览器自动打开聊天界面。
- > 首次使用需要一个大模型 API Key(推荐 DeepSeek)。想手动安装、让 Hermes 代装,或先看注意事项:
- > [安装步骤](#安装步骤三种方式) · [安装前须知](#安装前须知)
- ---
- ## 为什么外贸人需要这个?
- | 痛点 | 不用这个工具 | 用了之后 |
- |------|-------------|---------|
- | 早安简报 | 每天打开 5 个网站查汇率/金价/新闻 | 自动生成,含实时汇率+大宗商品行情+客户跟进提醒 |
- | 客户背调 | 手动 Google → LinkedIn → WHOIS | 一键 6 层验证:邮箱注册检测→WHOIS→制裁名单→邮箱验证→技术栈→LinkedIn |
- | 开发信 | 每封手动写,客户多了记不清 | 根据客户画像自动生成,带具体痛点引用 |
- | B2B 平台 | 每天登录阿里国际站/中国制造网看数据 | 定时自动检查,新询盘/待跟进报价一目了然 |
- | LinkedIn | 不知道发什么内容 | AI 按周生成内容日历,轮换行业洞察/产品案例/互动提问 |
- | 客户资料 | 散落在 Excel/微信/邮件里 | 统一管理,A/B/C 分级,关联文档库 |
- ---
- <p align="center">
- <img src="docs/screenshot-2.png" alt="Customer & Cron Panel" width="75%">
- <br>
- <em>客户管理 + 定时任务面板</em>
- </p>
- ---
- ## 安装前须知
- ### 大模型 API Key(必需)
- > Smart Trade AI 使用 Hermes Agent 作为底层 AI 驱动。你需要去模型厂商那里注册并获取 API Key。
- | 方案 | 模型 | 适合场景 | 注册地址 |
- |------|------|---------|---------|
- | **推荐** | `deepseek-flash` | 日常对话、文档分析、开发信 | [platform.deepseek.com](https://platform.deepseek.com) → 充值 → API Keys |
- > 本项目全部测试均在 DeepSeek 上完成,因此只推荐 DeepSeek。工具本身兼容其它 OpenAI 接口的模型(见下方技术栈),但未在其它模型上验证过。
- 获取 API Key 后在终端运行 `hermes setup`,选择对应的 provider 并填入 Key 即可。
- ### 网络环境要求
- 安装过程中需要从 GitHub 克隆仓库并下载 Python 依赖,**请确保你的网络能稳定访问 GitHub**。如果安装 Hermes 时反复失败,大概率是网络问题:
- - **境内用户建议全程开启 VPN(全局模式)**,否则 `git clone` 和 `pip install` 容易超时或中断
- - 如果 VPN 不稳定,可以多次重试安装命令,脚本支持断点续装
- - Windows 用户如果 VPN 代理未生效,尝试在 PowerShell 中先设置代理:
- ```powershell
- $env:HTTPS_PROXY = "http://127.0.0.1:你的代理端口"
- ```
- ### Tavily Search API(强烈建议注册)
- Trade 的搜索和客户尽职调查功能依赖 Tavily 的 AI 搜索引擎。注册免费账号即可获得每月 1000 次免费搜索额度,对个人使用完全够用:
- 1. 访问 [tavily.com](https://tavily.com) 注册账号
- 2. 在 Dashboard → API Keys 中复制你的 API Key
- 3. 在终端执行 `hermes setup`,找到 Tavily 选项并填入 Key
- > 不注册不影响对话功能,但搜索和客户背调质量会受到明显影响。
- ### AI 输出仅供参考
- Smart Trade AI 基于大语言模型(LLM)生成回复。受限于当前技术,大模型可能出现幻觉(hallucination),**所有输出内容仅供参考,不构成任何商业建议或法律依据**。涉及合同条款、报价金额、合规判断、客户背调等关键业务决策时,请务必自行核实。使用本工具所产生的任何风险由用户自行承担。
- ### 🚫 不要用 workbuddy 等国产 AI 助手安装 Trade
- **已有多位用户这样装,结果都是同一个:助手回报「安装成功」,实际完全不能用。** 更麻烦的是它还会**生成错误的公司文件夹**,残留下来后很难清理干净。
- 原因:这类助手不了解本项目的安装依赖(Hermes 必须是指定来源的可编辑检出、Trade 必须用 `--no-deps` 安装、装完还要同步 skills 与初始化数据库),步骤做错了却照样报告成功,所以表面看不出问题。
- **要 AI 代装,建议用 Hermes**(见下方「方式 1」)。换其它 AI 助手前,请先确认它愿意严格按本页的步骤执行 —— 上面那类问题,都是助手自己发挥了、做错了还照样报成功造成的。若不想让 AI 装,请用方式 2 的一键脚本或方式 3 手动安装。
- ### 如果 Trade 安装失败
- 手动安装 Trade 涉及 `git clone` + `pip install` + `install-trade-skills` 三个步骤,网络波动可能导致某一步失败。如果你已经成功安装了 **Hermes Agent 并配置好了 LLM**,但 Trade 安装遇到困难,可以直接把 Trade 的仓库地址告诉 Hermes,让它帮你完成安装:
- > 在 Hermes 对话中直接说:
- > 「帮我安装 Trade,仓库地址是 https://github.com/chefroger/smart-trade-ai.git」
- Hermes 会自动完成 clone、安装依赖、注册 skills 等全部步骤,成功率远高于手动操作。
- ## 许可证与试用
- - 首次使用有 **30 天体验期**,状态保存在本机、不联网登记,重在体验,不防破解。
- - **付费激活码绑定当前电脑**。换电脑、重装系统后,请把新机器上的申请码发给作者 **Roger Lau** 重新签发。
- - 试用期内界面只保留免费能力,以下入口**不会出现**,激活后自动显示:
- - 左侧「👤 销售转化」(客户管理 / 文档库 / 文档生成)
- - 左侧「🛠️ 工具」(客户背调 / 定时任务)
- - 左侧「💬 历史」(对话记录)
- - 公司名右侧的「➕ 添加公司」按钮(没有公司时,空状态页的「创建公司」仍然可见)
- - 左下角的「⬆️ 更新系统」与「ℹ️ 升级说明」
- - **公司数据导出 / 导入是付费功能**:在「公司设置」里选中公司 → 导出得到一个 `.zip`,在另一台电脑导入即可迁移客户、对话、订单、记忆与 Agent 身份。
- - 同名公司不会重复创建,默认合并;确实只是重名时可选「强制新建」。
- - 包内**不含许可证**,也不含桌面资料库文件(桌面可能有几百 GB,需自行拷贝);导出提示里会列出要拷贝的目录。
- - **包未加密**,含客户资料与记忆,请妥善保管。
- ---
- ## 安装步骤(三种方式)
- 提供三种安装方式,按你的场景挑一种即可:
- | # | 方式 | 适合场景 |
- |---|------|---------|
- | 1 | **Hermes 代装** | 已装好 Hermes 并配置好 LLM,让 AI 帮你装 Trade |
- | 2 | **一键脚本** | macOS / Linux / Windows 都有一键脚本 |
- | 3 | **手动一步步装** | 想完全控制每一步 |
- ---
- ### 方式 1:让 Hermes 帮你装 Trade(推荐给 AI 用户)
- 如果你已经装好 Hermes Agent 并配置好 LLM + Tavily 搜索,最省心的方式是让 AI 自己装 Trade——它能根据你的环境动态调整命令,成功率比固定脚本更高。
- **前置条件**:已通过 `hermes setup` 配置好 LLM provider 和 API Key,**强烈建议同时配置 [Tavily](https://tavily.com) 搜索**(免费),否则 AI 无法访问 GitHub 仓库信息。
- **操作步骤:**
- 1. 启动 Hermes:
- ```bash
- hermes
- ```
- 2. 在 Hermes 对话框中直接粘贴下面这句话(中文即可):
- > 请分析 https://github.com/chefroger/smart-trade-ai 这个 GitHub 仓库,并帮我安装
- 3. Hermes 会自动:访问仓库 README → 识别安装步骤 → `git clone` → `pip install` → `install-trade-skills` → 初始化数据库
- 4. 安装完成后,**新开一个 PowerShell**(让 PATH 生效),启动 Trade:
- ```powershell
- trade
- # → 浏览器自动打开 http://127.0.0.1:9119/trade
- ```
- > 如果 `trade` 命令找不到,说明 PATH 没生效,可以改用:
- > ```powershell
- > cd $env:LOCALAPPDATA\trade\foreign-trade-assistant
- > $env:LOCALAPPDATA\trade\venv\Scripts\python.exe server.py
- > ```
- > 然后浏览器手动打开 http://127.0.0.1:9119/trade
- > AI 会根据你当前的环境(Python 版本、操作系统、已有依赖)动态调整命令,遇到报错也能自行排查重试,比固定脚本更鲁棒。
- ---
- ### 方式 2:一键脚本
- **macOS / Linux:**
- ```bash
- curl -fsSL https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.sh | bash
- ```
- **Windows(PowerShell):**
- ```powershell
- irm https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.ps1 | iex
- ```
- 脚本自动完成:Python 3.14 环境检查 → Hermes Agent 检查 → Trade 安装 → 44 个 skills → 数据库初始化 → 开机自启(macOS 用 launchd、Linux 用 systemd、Windows 用计划任务 + 桌面快捷方式)。
- > **如果你希望安装前先审查脚本**:
- > ```bash
- > curl -fsSLO https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.sh
- > less install.sh # 审查后
- > bash install.sh
- > ```
- > ```powershell
- > # install.ps1 只是纯 ASCII 引导器;真正的安装逻辑在同目录的 install-core.ps1
- > irm https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install-core.ps1 -OutFile install-core.ps1
- > notepad install-core.ps1 # 审查后
- > irm https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.ps1 -OutFile install.ps1
- > .\install.ps1
- > ```
- ### 方式 3:手动一步步装
- **前置条件**:**Python 3.14** · Git · LLM API Key(推荐 DeepSeek;也兼容 OpenAI / Anthropic 等)
- > ⚠️ **Python 必须是 3.14,不能是 3.11~3.13。** Trade 是**进程内**嵌 Hermes 运行的,
- > 两者必须用同一个 Python 大版本。Hermes 从 v0.21.6 起只提供 3.14 的依赖集
- > (它声明的 `>=3.11` 只是留给旧安装跑升级步骤的过渡桥),在 3.11~3.13 上会出现
- > 「装得上、起不来」。上面的方式 1 / 方式 2 会自动用 Hermes 自带的 3.14,无需操心。
- ```bash
- # 1. 安装 Hermes Agent(AI 引擎)—— 用官方安装器,它会自带 Python 3.14
- # 注意:不要把某个 tag 克隆到 ~/.hermes/hermes-agent 覆盖掉已装的那份
- curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
- # 2. 配置 LLM
- hermes setup # 按提示选择 provider、填入 API Key
- # 3. 安装 Smart Trade AI(用上一步 Hermes 自带的 3.14 建 venv)
- git clone --branch main https://github.com/chefroger/smart-trade-ai.git ~/.trade/foreign-trade-assistant
- cd ~/.trade/foreign-trade-assistant
- python3.14 -m venv ~/.trade/venv
- ~/.trade/venv/bin/pip install -r requirements.txt
- ~/.trade/venv/bin/pip install -e "." --no-deps
- # 4. 安装 skills 并启动
- ~/.trade/venv/bin/python -c "from trade.post_install import install_skills; install_skills()"
- ~/.trade/venv/bin/python server.py
- # → 浏览器打开 http://127.0.0.1:9119/trade
- ```
- > 如果启动后 Trade 界面提示「Hermes 版本过旧」,说明你的 Hermes 低于 0.21.6。
- > **不需要手动处理** —— Trade 会在后台自动升级它,界面上会显示进度。
- ### Windows
- **安装前需手动安装 Python 和 Git:**
- 1. **Python** — 从 [python.org](https://www.python.org/downloads/) 下载 **Python 3.14 Windows installer (64-bit)**,安装时勾选「Add Python to PATH」。
- > ⚠️ 必须是 **3.14**,不能用 3.11~3.13:Trade 进程内嵌 Hermes,两者必须同一个 Python 大版本(详见「方式 3」的说明)。
- 2. **Git** — 从 [git-scm.com](https://git-scm.com/download/win) 下载 Windows installer,默认选项一路下一步即可。或在 PowerShell 中执行 `winget install --id Git.Git -e --silent`。
- > Node.js 无需手动安装 — Hermes 的一键安装脚本会自动处理。
- 安装好 Python 和 Git 后,**重新打开 PowerShell**(让 PATH 生效),执行:
- ```powershell
- # 0. 启用 Windows 长路径支持(以管理员身份运行 PowerShell,仅需一次)
- New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
- # 执行后需重启电脑
- # 1. 安装 Hermes Agent(自动处理 Node.js + Git + 依赖)
- irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
- # 2. 配置 LLM
- hermes setup
- # 3. 安装 Smart Trade AI(用 3.14 建独立虚拟环境)
- $TradeHome = "$env:LOCALAPPDATA\trade"
- python -V # 必须是 Python 3.14.x,是 3.11~3.13 就先回去重装
- git clone --branch main https://github.com/chefroger/smart-trade-ai.git $TradeHome\foreign-trade-assistant
- cd $TradeHome\foreign-trade-assistant
- python -m venv $TradeHome\venv
- $TradeHome\venv\Scripts\pip.exe install -r requirements.txt
- $TradeHome\venv\Scripts\pip.exe install -e "." --no-deps
- # 4. 安装 skills、初始化数据库并启动
- $TradeHome\venv\Scripts\python.exe -c "from trade.post_install import install_skills; install_skills()"
- $TradeHome\venv\Scripts\python.exe -c "from trade.database import init_db; init_db()"
- $TradeHome\venv\Scripts\python.exe server.py
- # → 浏览器打开 http://127.0.0.1:9119/trade
- ```
- > **为什么必须建 venv、并且分两条 pip 命令**:
- > Trade 是**进程内**嵌 Hermes 运行的,解释器必须与 Hermes 同为 Python 3.14;
- > `pip install -r requirements.txt` 装文档解析依赖(openpyxl / python-docx / pymupdf),
- > `pip install -e "." --no-deps` 装 Trade 本体 —— `--no-deps` 是必须的,
- > 否则 pip 会去解析 `hermes-agent`,而它不支持被 pip 安装。
- > 如果第 3 步 `pip install` 报 `Filename too long` 错误,说明长路径未生效,请确认已完成第 0 步并重启电脑。
- > 想让 `trade` 命令在任意目录可用(并开机自启 + 桌面快捷方式),直接改用
- > [方式 2 的一键脚本](#方式-2一键脚本) —— 它会一并生成 `trade.cmd`、写好 PATH、建好开机自启。
- ---
- ## 专业能力
- | 场景 | 能力 |
- |------|------|
- | 平台诊断 | 分析阿里国际站/中国制造网产品页面,输出优化建议 |
- | 社媒营销 | 生成 Facebook/Instagram/TikTok/YouTube 内容日历 |
- | LinkedIn 运营 | Profile 优化 + 内容策略 + InMail 模板 |
- | 海关数据 | 分析进出口数据,筛选高价值采购商 |
- | 客户开发 | 多通道搜索(Google Maps/LinkedIn/Facebook)+ 开发信生成 + 询盘回复 + 报价谈判 |
- | 冷 Outreach 邮件 | 个性化开发信/推广信/跟进信,语言匹配+反垃圾规则+产品参数速查 |
- | 开发信仿写 | 分析优秀邮件样本的 AIDA 结构和语气,应用到自家产品生成新邮件 |
- | 客户管理 | 多维度分级(等级/买家类型/主营品类/匹配度)+ 详情面板+文档库关联+CSV 批量导入+去重 |
- | 客户背调 | 6 层验证:邮箱平台检测→WHOIS→企业邮箱验证→制裁名单→技术栈→LinkedIn |
- | 客户画像 | 单一客户 15 维深度画像:决策链/采购偏好/社交风格/送礼建议等 |
- | 客户开发向导 | 三问启动 + 自动搜索 + 开发信生成,零门槛找客户 |
- | 国内线索挖掘 | 找货源厂家(主)/ 挖竞品国内厂家(重点)/ 找国内客户,免费公开渠道(产业带+搜索引擎+海关记录+人工核对) |
- | 买家画像 | 按决策角色(采购/技术/老板)分层定制 FAB 价值主张和沟通策略 |
- | 销售管线 | 客户旅程 5 阶段映射 + 30 天跟进表 + KPI 追踪 + 管线健康度看板 |
- | 邮箱情报 | 120+ 平台邮箱注册检测,识别企业 vs 个人邮箱 |
- | 文档分析 | 读取本地 PDF/Word/Excel/PPT,AI 逐个文件完整解析,不跳过不截断 |
- | 商务文档生成 | 一键生成报价单、PI、合同(DOCX/XLSX/PPTX)+ 可下载单证模板 |
- | 市场分析 | 目标国认证要求/关税政策/关键词武器库/3 秒 Hook 等系统化市场进入策略 |
- | 数据目录 | 结构化知识库管理:产品/客户/报价/合同/认证/物流 |
- | 每日简报 | 实时汇率+大宗商品+市场新闻+客户跟进提醒 |
- | 定时任务 | 工作日自动化:早报/开发信/社媒/每日总结 |
- | 新客引导 | 首次使用两步引导:创建公司→粘贴客户网址体验 OSINT+开发信自动生成 |
- | 对话记录 | 按公司隔离的聊天记忆,支持搜索/回溯+AI回复评分反馈 |
- | 询盘回复训练 | 双AI对抗训练法(模拟买家 vs 生成回复),迭代打磨至 9.5 分 |
- | 履约运营 | 催款/索赔/展会/验厂/物流/售后/满意度/年度总结等 11 个场景 |
- | 贸易合规 | 文化禁忌检查/缩写规范/ICC术语/翻译二审/投标/电商上架 |
- | 自动客户开发 | 定时扫描目标市场,自动识别潜在客户并分析匹配度 |
- | KOL 风格模仿 | 分析行业 LinkedIn 大V 的内容风格(语气/结构/Hook)并应用到自家品牌 |
- | Reddit 互动 | 在 Reddit 专业社区通过评论建立行业信任、引流 B2B 客户 |
- | SEO+AEO 文章 | 针对 Google 搜索和 AI 搜索引擎(Perplexity/Gemini/ChatGPT)优化内容 |
- | 短视频脚本 | B2B 产品/工厂短视频脚本(TikTok/YouTube Shorts/Reels)含分镜表 |
- | 展会管理 | 展会全流程:展前邀约+展中记录+展后 48h 跟进+客户分级 |
- | 产品描述 | FAB 方法生成产品卖点与销售资料(Sales Kit/官网/开发信嵌入段落) |
- | 决策教练 | 六顶思考帽方法辅助外贸决策分析(选供应商/参展/付款条件变更等) |
- | 询盘分析会 | 周度询盘复盘,逐人点评,重点询盘分析,输出跟进行动表 |
- | 销冠经验库 | 将资深销售的隐性经验转化为SOP/话术库/新人培训体系 |
- | 商业提案生成 | 三档方案对比 + ROI分析 + 实施路线图,支持客户提案 |
- | 工程图纸分析 | 分析客户发来的 PDF 工程图纸,提取零件名/材料/尺寸/公差(实验性,结果需人工核实) |
- | 招标信息监控 | 按关键词定时抓取招标公告,生成可筛选的线索表 |
- | 招标邮件归档 | 从邮箱拉取招标邮件与附件并按项目归档,全程不置已读 |
- | 询价单生成 | 把招标文件整理成固定 11 列的 Excel 询价单 |
- | 招标包下载 | 批量下载招标附件:分块续传、大小与校验双验、失败可重试 |
- | 解压与归档 | 7z/rar/zip/gz 批量解压、嵌套包多轮展开,原包进回收站 |
- | 清单匹配归档 | 按招标清单的编号与名称匹配文件,成套打包归档 |
- | Skill 生成器 | 用自然语言描述需求,自动生成新 skill 并注册到系统 |
- | 公司数据迁移 | 把一个公司的客户/对话/订单/记忆/Agent 身份打包导出,在另一台电脑导入合并(付费功能) |
- ---
- ## 数据安全
- - **业务数据默认存储在本地**(`~/.trade/`),不上传任何服务器
- - 如使用 **Ollama 等本地模型**,可实现完整本地运行,数据完全不出电脑
- - 如使用 **DeepSeek 等云端 LLM**,用户输入和必要上下文会发送至所选服务商——不包含客户身份信息
- - 多公司数据隔离(`X-Company-ID` header)
- - 绑定 `127.0.0.1`,仅本机浏览器可访问;即使改用 `--host 0.0.0.0`,会话凭据也只下发给本机(见下方网络暴露警告)
- - **升级前自动备份数据库**到 `~/.trade/backups/`
- ### 多公司记忆共享说明
- 长期记忆摘要会追加写入 Hermes 的全局 `~/.hermes/memories/MEMORY.md`,通过条目内 `[公司: XXX]` 标记做软隔离。Hermes 原生检索依赖该标记过滤——正常使用时不会跨公司命中,但这是"共享文件 + 标记隔离"而非"物理隔离"。若你使用多家公司且对隔离要求极高,请注意这一设计边界。
- ### 网络暴露警告
- 默认仅绑定 `127.0.0.1`。会话凭据(session token)**只下发给本机(回环地址)浏览器**:即使你用 `--host 0.0.0.0` 把端口暴露出去,来自其它设备的访问也只会得到一页说明(HTTP 403),不会拿到 token,因此无法调用 API。
- 确需从其它设备访问界面时,可在启动前设置环境变量 `TRADE_ALLOW_REMOTE_UI=1` 显式放行 —— **这会降低安全性**:任何能访问该端口的设备都能取得 token 并冒充操作。更稳妥的远程方案仍是 SSH 隧道或反向代理 + 额外认证层,而不是直接改 bind 地址。
- > **免责声明**:文档中提及的 Alibaba、LinkedIn、Facebook、Instagram、TikTok、YouTube、WhatsApp 等均为其各自所有者的商标。本工具仅提供对这些平台数据的分析辅助,与上述平台无关联。制裁名单数据来源于 OFAC/UN/EU 公开数据,结果仅供参考,不构成法律意见。详见 [SECURITY.md](SECURITY.md)。
- ---
- ## 技术栈
- - **AI 引擎**: [Hermes Agent](https://github.com/NousResearch/hermes-agent)(MIT 开源)
- - **后端**: FastAPI + SQLite + uvicorn
- - **前端**: 原生 JavaScript SPA(HTML/CSS/JS 三文件,零构建工具依赖)
- - **LLM**: 推荐 `deepseek-flash`;兼容 OpenAI / Anthropic / GLM / Kimi / Ollama 等
- - **文档解析**: 硬依赖 `firecrawl-anydoc` + `pypdfium2`;PyMuPDF / python-docx / openpyxl / python-pptx 为可选 `[docs]` extra
- ---
- ## 项目结构
- ```
- trade/ B2B 业务层
- ├── api/ FastAPI 路由(12 个业务域 + license/system)
- ├── osint/ 客户背调模块(6 层检测)
- ├── company/transfer/ 单公司数据打包导出/导入(跨电脑迁移)
- ├── skill_router.py Skill 自动匹配引擎
- ├── skill_registry.py 45 个 skill 注册表(纯数据)
- ├── bootstrap.py 启动引导(Hermes 版本检查、env 加载、Skills 同步)
- ├── app.py FastAPI app factory
- └── ... + 40 个业务模块
- skills/ 45 个 skill(42 个 b2b-* + 2 个 auto-* + 1 个 chat-memory)
- tests/ Python 测试(87 个文件)+ 文档读取规则端到端实测
- tests_js/ 前端工具函数测试(node:test,零依赖;CI 会执行)
- server.py FastAPI 入口
- ```
- ---
- ## 开发
- ```bash
- pip install -e ".[dev,docs]"
- python -m pytest tests/ -v # Python 测试
- node --test "tests_js/**/*.test.js" # 前端工具函数测试(零依赖,需 Node)
- ruff check trade/ server.py # 代码检查
- ```
- > 前端测试与 Python 测试都由 CI 执行(`.github/workflows/test.yml`)。
- ## 文档
- - [使用说明书](TRADE-GUIDE.md) — 从零上手:界面认知、技能速查、日常用法、常见问题
- - [Windows 安装教程](docs/index.md) — 零基础用户 20 分钟快速安装指南
- - [LinkedIn 获客功能使用说明](docs/linkedin-guide.md) — 免费 / Premium / Sales Navigator(Core·Advanced·Advanced Plus)功能分级与使用示例
- - [COMPATIBILITY.md](COMPATIBILITY.md) — Hermes 版本兼容性记录
- ---
- ## 故障排除
- ### 先跑自检:`trade doctor`
- 任何功能不对劲,先跑它再看别的:
- ```bash
- trade doctor
- ```
- 它会**端到端验活**七项,并指出是哪一项坏了:
- | 检查项 | 怎么验的 |
- |---|---|
- | Hermes 运行环境 | 真的构造一个 agent(能抓到"版本对但起不来"这类问题) |
- | 急停状态(ESTOP) | 确认 Hermes 没有被 `hermes pause` 停掉(否则定时任务会静默不跑) |
- | 技能一致性 | 比对项目内置技能与 Hermes 已安装技能,列出缺失项 |
- | 安装脚本状态 | 检查 skills/模板是否已同步到用户目录 |
- | 图片识别(原生 vision) | 生成一张随机验证码图发给模型,看它能否读出来 |
- | Tavily 搜索 | 真的发一次搜索请求(不是只看 key 存不存在) |
- | Trade 自身 | 数据库可读写 + 真的走一次对话回合 |
- **首次启动会自动跑一次**;没通过则每次启动重试,直到修好(改完配置重启即自动恢复)。
- 结果也会出现在 `http://127.0.0.1:9119/api/status` 的 `doctor` 字段里。
- 输出里 `✗` 分两种:标「无法正常使用」的是致命项(必须先修),标「功能不可用」的
- 不影响基本使用。加 `--quick` 可跳过所有真实请求(零 token,安装脚本用的就是它)。
- ### 用 Hermes 更新 Trade(推荐)
- 最快的方式是让 AI 帮你更新。打开终端,启动 Hermes,在对话框里输入:
- ```
- 帮我更新trade,并重启trade,地址是https://github.com/chefroger/smart-trade-ai
- ```
- Hermes 会自动执行 `git pull` → `pip install` → `install-trade-skills` → 数据库检查 → 重启 Trade。遇到报错它会自行排查重试,比手动操作更省心。
- ### 更新系统按钮点了没反应
- 点击左下角「⬆️ 更新系统」按钮后,系统会自动执行 `git pull` + `pip install` + skills 更新。**更新完成后不会自动重启**——你会在界面上看到「✅ 更新完成。请点击"🔄 重启"以应用新版本。」,这时再点左下角「♻️ 重启」按钮生效。
- 重启时新进程先启动并等待旧进程释放端口(最多 10 秒),避免端口冲突。整个过程中页面会短暂不可用,之后自动恢复。
- 如果更新后页面没有自动刷新,或出现异常,请手动按 `Ctrl+Shift+R`(Windows)/ `Cmd+Shift+R`(macOS)强制刷新浏览器。
- 如果更新按钮完全无响应(常见于从极旧版本升级),请按以下步骤手动操作:
- **macOS:**
- 1. 关闭 Trade 页面(浏览器标签页)
- 2. 打开「终端」(在 Launchpad 或 Spotlight 搜索"终端")
- 3. 逐行复制粘贴以下命令,每行按回车:
- ```bash
- cd ~/.trade/foreign-trade-assistant
- git pull origin main
- ~/.trade/venv/bin/pip install -r requirements.txt
- ~/.trade/venv/bin/pip install -e "." --no-deps
- ~/.trade/venv/bin/python -c "from trade.post_install import install_skills; install_skills()"
- ```
- > `--no-deps` 不能去掉:Hermes 的 setup.py 会拒绝构建 wheel,不加这个参数 pip 会去解析 hermes-agent 依赖并失败。
- 4. 所有命令执行完后,关闭终端
- 5. 重新运行 `~/.trade/venv/bin/python server.py` 启动
- **Windows:**
- 1. 关闭 Trade 页面
- 2. 按键盘 `Win + R`,输入 `powershell`,回车
- 3. 逐行复制粘贴以下命令,每行按回车:
- ```powershell
- cd $env:LOCALAPPDATA\trade\foreign-trade-assistant
- git pull origin main
- $env:LOCALAPPDATA\trade\venv\Scripts\pip.exe install -r requirements.txt
- $env:LOCALAPPDATA\trade\venv\Scripts\pip.exe install -e "." --no-deps
- $env:LOCALAPPDATA\trade\venv\Scripts\python.exe -c "from trade.post_install import install_skills; install_skills()"
- ```
- 4. 所有命令执行完后,关闭 PowerShell
- 5. 双击桌面上的 Trade 图标启动,或在终端重新运行 `$env:LOCALAPPDATA\trade\venv\Scripts\python.exe server.py`
- **Linux:**
- 1. 关闭 Trade 页面
- 2. 打开终端
- 3. 逐行复制粘贴以下命令,每行按回车:
- ```bash
- cd ~/.trade/foreign-trade-assistant
- git pull origin main
- ~/.trade/venv/bin/pip install -r requirements.txt
- ~/.trade/venv/bin/pip install -e "." --no-deps
- ~/.trade/venv/bin/python -c "from trade.post_install import install_skills; install_skills()"
- ```
- 4. 重新运行 `~/.trade/venv/bin/python server.py` 启动
- > 如果执行 `git pull` 时报错找不到 `git`,说明 Git 未安装。请先打开终端输入 `hermes` 确认 Hermes 正常,或从 [git-scm.com](https://git-scm.com) 下载安装 Git 后再试。
- ### 升级时报错「更新结果未知」「更新失败」「请求超时」等
- 前端升级失败的错误提示各不相同,但**根本原因几乎都是网络问题**——`git pull` 或 `pip install` 无法稳定连接 GitHub/PyPI。**所有此类错误的解决方法完全相同**:跳过前端,直接在终端里手动执行更新命令。
- **macOS / Linux:**
- 1. 关闭 Trade 页面,打开终端
- 2. 逐行执行(确保 VPN 全局模式已开启):
- ```bash
- cd ~/.trade/foreign-trade-assistant
- git pull origin main
- ~/.trade/venv/bin/pip install -r requirements.txt
- ~/.trade/venv/bin/pip install -e "." --no-deps
- ~/.trade/venv/bin/python -c "from trade.post_install import install_skills; install_skills()"
- ~/.trade/venv/bin/python server.py
- ```
- **Windows:**
- 1. 关闭 Trade 页面,按 `Win + R`,输入 `powershell`,回车
- 2. 逐行执行(确保 VPN 全局模式已开启):
- ```powershell
- cd $env:LOCALAPPDATA\trade\foreign-trade-assistant
- git pull origin main
- $env:LOCALAPPDATA\trade\venv\Scripts\pip.exe install -r requirements.txt
- $env:LOCALAPPDATA\trade\venv\Scripts\pip.exe install -e "." --no-deps
- $env:LOCALAPPDATA\trade\venv\Scripts\python.exe -c "from trade.post_install import install_skills; install_skills()"
- $env:LOCALAPPDATA\trade\venv\Scripts\python.exe server.py
- ```
- **常见错误对照:**
- | 前端提示 | 实际原因 | 手动执行哪步 |
- |---------|---------|------------|
- | ⚠️ 更新结果未知,请检查网络 | `git pull` 超时(120s)或 HTTP 错误 | 全部步骤 |
- | ⚠️ 请求超时 | `fetch()` 120s AbortController 触发 | 全部步骤 |
- | ⚠️ 升级完成,但有 N 项警告 | skills 同步等**非关键步骤**失败(网络波动)——不影响升级 | 无需处理:代码与依赖已更新,**再点一次「♻️ 重启」即可生效**,仅技能清单可能未更新,可稍后手动执行 `install_skills()` |
- | ❌ 更新失败: Git 未安装或不在 PATH 中 | 系统找不到 `git` 命令 | [安装 Git](https://git-scm.com/download/win) 后重跑全部步骤 |
- | ❌ 更新失败: pip install failed | 依赖包下载失败(PyPI 不通) | `pip install -r requirements.txt` 重试 |
- | ❌ 更新失败: git pull / clone failed | GitHub 连不上 | 开 VPN 全局模式后重试 `git pull` |
- > 升级流程只有 **git pull / pip install / 数据库检查**三步属于关键步骤,失败才会中止升级并提示 `❌`;
- > skills 同步、模板同步、开机自启设置失败一律降级为警告(`⚠️`)**不会阻止你点重启**——避免因一次网络抖动把你锁在旧版本上。
- > 如果 VPN 已开启但仍失败,尝试在终端中先设置代理再执行更新:
- > ```bash
- > # macOS / Linux
- > export https_proxy=http://127.0.0.1:你的代理端口
- >
- > # Windows PowerShell
- > $env:HTTPS_PROXY = "http://127.0.0.1:你的代理端口"
- > ```
- ### 拖拽文件 / 上传报错「拒绝访问」
- 如果你在聊天框拖入 Excel 等文件时看到类似 `[WinError 5] 拒绝访问: 'C:\\Windows\\System32\\.hermes'` 的错误,说明程序找不到正确的数据目录。
- **macOS:**
- 1. 关闭 Trade 页面,打开「终端」
- 2. 执行以下命令再启动:
- ```bash
- export HERMES_HOME="$HOME/.hermes"
- python server.py
- ```
- **Windows:**
- 1. 关闭 Trade 页面,按 `Win + R`,输入 `powershell`,回车
- 2. 执行以下命令再启动:
- ```powershell
- $env:HERMES_HOME = "$env:LOCALAPPDATA\hermes"
- cd $env:LOCALAPPDATA\trade\foreign-trade-assistant
- $env:LOCALAPPDATA\trade\venv\Scripts\python.exe server.py
- ```
- **Linux:**
- 1. 关闭 Trade 页面,打开终端
- 2. 执行以下命令再启动:
- ```bash
- export HERMES_HOME="$HOME/.hermes"
- python server.py
- ```
- ### 升级后页面样式异常
- 浏览器缓存了旧版 CSS/JS,按 `Cmd+Shift+R` (macOS) 或 `Ctrl+Shift+R` (Windows) 强制刷新即可。
- ---
- ## 联系作者
- <div style="display:flex;gap:40px;align-items:flex-start;">
- <div>
- <img src="docs/wechat-contact.jpeg" alt="WeChat" width="200"><br>
- <small>微信扫码 · 备注「Trade」</small>
- </div>
- <div>
- <img src="docs/whatsapp-contact.png" alt="WhatsApp" width="200"><br>
- <small>WhatsApp</small>
- </div>
- </div>
- 商务合作或技术支持请发邮件至 lauroge@gmail.com。
- ---
- Smart Trade AI — 外贸业务员的本地 AI 助手。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.