# Foreign Trade Assistant — 使用说明书

外贸 AI 销售助手，覆盖从找客户到拿订单的全链路。

---

## 一、安装

### macOS / Linux

```bash
curl -fsSL https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.sh | bash
```

### Windows

```powershell
powershell -ExecutionPolicy Bypass -Command "Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/chefroger/smart-trade-ai/main/scripts/install.ps1' -OutFile install.ps1; .\install.ps1"
```

### 启动

```bash
python server.py
# 浏览器打开 http://127.0.0.1:9119/trade
```

首次启动时需要配置 LLM API Key（在 Hermes 设置中完成）。

---

## 二、界面概览

界面分为左右两部分：

```
┌─────────────────┬──────────────────────────────────────────┐
│   侧边栏        │          主内容区                         │
│  （深色背景）    │    （浅色背景，动态切换）                  │
│                 │                                          │
│  🏢 公司选择器   │   聊天对话 / 客户表格 / 任务面板 / 历史    │
│  ═══════════    │                                          │
│  📊 工作台      │                                          │
│  🔍 获客引流    │                                          │
│  👤 销售转化    │                                          │
│  🛠️ 工具        │                                          │
│  💬 历史        │                                          │
└─────────────────┴──────────────────────────────────────────┘
```

---

## 三、首次使用

### 1. 创建公司

点击侧边栏顶部公司选择器旁边的 **+** 按钮 → 填写公司信息 → 点击「创建公司」。

创建公司时系统会自动在桌面生成工作目录：

```
~/Desktop/{公司名}/
├── 报价单/
├── 合同/
├── 客户资料/
├── 产品规格/
├── 发票/
├── 物流单据/
├── 认证资质/
├── 营销素材/
└── 海关数据/
```

将对应的文件放入这些文件夹，AI 即可读取分析。

### 2. 配置 Agent 身份

创建公司后，在弹出窗口的「Agent 身份」标签中配置：
- 公司产品和优势
- 目标市场
- 沟通风格偏好

---

## 四、功能详解

### 📊 工作台 — 今日简报

每次打开 Trade 或点击「今日简报」，系统会：
- 显示今日定时任务清单（已完成 / 待处理 / 已过时）
- 显示最近的对话历史
- 输入"早安简报"让 AI 生成完整日报

### 🔍 获客引流

#### 客户开发
粘贴 LinkedIn 链接或客户信息，AI 会：
1. 分析客户背景
2. 生成定制化开发信
3. 给出跟进计划（Day 1 / Day 3 / Day 7）

#### 网站诊断
粘贴任何网站链接（阿里国际站、公司官网、独立站），AI 会用浏览器访问页面，分析：
- SEO 质量（标题、关键词、描述）
- 技术栈检测
- 页面设计评估
- 给出具体优化建议

#### 社媒营销
描述需求，AI 会生成：
- Facebook / Instagram / TikTok / YouTube 内容日历
- 具体帖子文案（可直接复制粘贴）
- 配图建议和标签

#### LinkedIn
- 个人 Profile 优化建议
- 公司主页内容策略
- 年度营销方案
- InMail 开发信模板

#### 海关数据
将海关数据文件（CSV/Excel）放入桌面「海关数据」文件夹，AI 会自动：
- 筛选目标采购商
- 分析采购规律
- 按优先级排序输出开发清单

### 👤 销售转化

#### 客户管理
- **表格视图**：查看所有客户（名称/等级/国家/联系方式/关联文档库/最近跟进）
- **等级系统**：A 级（高价值）/ B 级（中等）/ C 级（潜力）
- **批量操作**：多选 → 批量删除
- **排序切换**：按名称 / 按最近跟进时间
- **详情面板**：点击任意客户行 → 右侧滑出完整信息面板
  - 编辑基本信息（名称/职位/国家/邮箱/电话/WhatsApp/LinkedIn/网站等）
  - 管理关联文档库
  - 查看最近对话

#### 文档库
- 自动关联桌面工作目录的 9 个文件夹
- 选择文档库后提问，AI 自动读取文件内容回答
- 支持 PDF/Word/Excel/PPT/图片/CSV 等 16 种格式
- 点击 **+** 可手动添加其他本地目录

#### 文档生成
描述需求，AI 会生成：
- PPT 演示文稿（品牌配色、多种布局）
- Word 合同/协议
- Excel 报价单（完整数据、交替行色）

### 🛠️ 工具

#### 客户背调
输入邮箱/域名/公司名，AI 执行 6 层验证：
1. 邮箱平台注册检测（120+ 平台）
2. WHOIS 域名查询（注册时间/注册商/年龄）
3. 企业邮箱验证（@公司域名 vs 个人邮箱）
4. 制裁名单筛查（OFAC/UN/EU）
5. 技术栈检测（建站平台/支付/分析工具）
6. LinkedIn 验证（浏览器直接访问）

输出：综合风险评级（低/中/高）+ 行动建议

#### 定时任务

页面分为上下两部分：

**上半部分 — 模板库**：
- 9 个任务模板（基于外贸业务标准工作流）
- 钩选需要的任务 → 编辑时间 → 编辑 Prompt → 点击「批量生成」
- 可以添加自定义模板
- 早安简报为必选任务

**下半部分 — 已激活任务**：
- 显示所有运行中的定时任务
- 每个任务可点击「立即执行」
- 「清空全部任务」按钮

### 💬 历史 — 对话记录

- 按时间倒序显示所有对话
- 搜索过滤
- 点击任意对话 → 跳转到聊天窗口查看完整上下文
- 每条对话可单独删除

---

## 五、常用操作

### 提问技巧

- **直接提问**：AI 会自动识别你的意图，加载对应的技能
- **上传文件**：把文件放入桌面工作目录，AI 自动读取
- **指定技能**：说"用 b2b-osint 查一下这个公司"

### 查看工作清单

在聊天框输入"显示工作清单"或"工作清单"或"今日任务"，系统会显示所有定时任务的完成状态。

### 切换公司

侧边栏顶部下拉框选择公司。所有数据（客户/文档库/对话）按公司隔离。

---

## 六、数据存储

所有数据存储在本地，不上传任何服务器（除了调用 LLM API）：

| 数据 | 位置 |
|------|------|
| 数据库 | `~/.trade/data/trade.db` |
| 公司档案 | `~/.trade/companies/{公司名}/` |
| 桌面工作目录 | `~/Desktop/{公司名}/` |
| LLM 配置 | `~/.hermes/config.yaml` |
| API Key | `~/.hermes/.env` |

---

## 七、常见问题

**Q: 如何更换 AI 模型？**
运行 `hermes setup` 重新配置。

**Q: 如何备份数据？**
复制 `~/.trade/` 目录和桌面工作目录即可。

**Q: AI 分析的文档支持哪些格式？**
PDF、Word (.docx/.doc)、Excel (.xlsx/.xls)、PPT (.pptx/.ppt)、CSV、图片 (.jpg/.png)、Markdown、HTML、纯文本。

**Q: 定时任务不执行？**
确保 Gateway 已启动（Trade 启动时会自动拉起）。

---

## 八、安全说明

本工具运行在 `YOLO` 模式下（AI 工具调用无需人工审批），因为目标用户是外贸业务员，不具备技术判断能力。

请务必：
1. 仅在内网或本机使用
2. 不要暴露到公网
3. API Key 妥善保管
4. 定期备份数据
