---
title: 新询盘分级 AW 脚本调用说明（v3）
created: 2026-05-25
updated: 2026-05-26
type: delivery-script
audience: merchant-operator
tags: [Accio Work, 国际站运营, 询盘分级, 脚本调用]
status: active
---

# 新询盘分级 AW 脚本调用说明（v3）

> ⚠️ **先看本目录的 `SCRIPTS_MANIFEST.md`**——那是导航总图。本文档是详细使用手册。

本目录是给 Accio Work / 国际站生意助手调用的脚本入口。现场部署时，不只复制提示词，还要让 AW 明确调用本目录脚本完成评分、分配校验和失败兜底。

## 🟢 推荐用法：统一入口 `run_scrape.py`

**99% 场景只需调这一个脚本**：

```bash
# 链路自检（不联网，用真实样本验证）
python3 scripts/run_scrape.py --mode dry-run-pipeline

# 首次试跑（采 10 条 + 评分，不推送）
python3 scripts/run_scrape.py --mode trial-sample --sample-size 10

# cron 常驻（增量采 → 评分 → 自动推送 S/A）
python3 scripts/run_scrape.py --mode new-only

# cron 安全档（仅评分不推送）
python3 scripts/run_scrape.py --mode new-only --no-notify
```

这个入口已经把"采集 → normalize → score_v3 → writeback → poll → notify"全链路串好，按真实接口契约调用各子脚本，并处理了 Windows 编码兼容。

## 🟡 单脚本手动调用（高级用法 / 调试）

### 脚本清单

| 脚本 | 作用 | 何时调用 |
| --- | --- | --- |
| `normalize_aw_inquiries.py` | AW 授权读取的 `inquiries.json` 字段标准化 | AW 已能抓取后台询盘，但字段名与评分脚本不一致时 |
| `score_inquiry_v3.py` | v3 评分引擎（167 分制 + chat_signals 30 分），输出 S/A/B/C/无效 | 第一轮批量评分、客户回复后二次复评、7 天复盘 |
| `build_platform_writeback.py` | 将评分结果生成飞书/钉钉表格写入行、内部提醒消息和 CLI 执行计划 | 客户已确认飞书/钉钉 CLI 授权时 |
| `poll_new_inquiries.py` | 增量扫描 `outputs/score_*.json` 找新询盘，写 `outputs/push_payloads/` | cron 主入口（已被 `run_scrape.py --mode new-only` 内部调用） |
| `notify_dispatcher.py` | 按 `config/notify_channels.json` 推送一条 payload | 单条手动推送 / 通道测试 |
| `alibaba_assign.py` | 对客户明确授权的后台分配动作做本地校验和调用封装 | **只有你确认要做后台分配时调用** |

### Accio Work 手动调用顺序

1. 先用 Accio Work / 国际站生意助手抓取当前账号可见的新询盘和买家信息。
2. 标准化：

```bash
python3 scripts/normalize_aw_inquiries.py templates/aw_inquiries_sample.json --output /tmp/normalized_inquiries.json
```

3. v3 评分（⚠️ JSON 走 stdout，必须重定向）：

```bash
python3 scripts/score_inquiry_v3.py /tmp/normalized_inquiries.json --json > /tmp/inquiry_score.json
```

4. 客户已确认飞书/钉钉 CLI 授权时，生成平台写回 payload：

```bash
python3 scripts/build_platform_writeback.py /tmp/inquiry_score.json --config templates/platform_writeback_config.sample.json --output /tmp/platform_writeback_payload.json
```

5. 将评分输出和平台写回预览交给负责人抽样确认，至少确认 10 条。
6. 你确认后，Accio Work 再按 `command_plan` 调用你已授权的飞书/钉钉 CLI 创建或更新跟进表，并发送内部 S/A 类提醒。
7. 若你确认要后台分配，再基于本地授权 config 调用 `scripts/alibaba_assign.py`；没有你明确授权时，不调用真实分配。
8. 现场记录必须写清：AW 抓到了哪些字段、哪些字段 missing、脚本是否返回成功、飞书/钉钉写回是否启用、失败原因是什么。

## 输入要求

每条询盘至少尽量包含：

- `inquiry_id`
- `buyer_name`
- `buyer_country`
- `buyer_l_level`
- `account_registered_months`
- `product`
- `product_match`
- `quantity`（⚠️ 必须 int，见 Windows 兼容性第 2 节）
- `demand`
- `company`
- `customs_data`
- `conversation_excerpt`（v3 chat_signals 扫描）
- `risk_signals`

读不到的字段保留为空，由脚本输出 `missing_fields`。**不要为了得分补造字段**。

## 现场可跑验收（v3）

**一键验收（推荐）**：

```bash
python3 scripts/run_scrape.py --mode dry-run-pipeline
```

这会用 `outputs/pilot_inquiries_30.json` 真实样本走完整链路，4 个阶段（normalize→score→writeback→poll）全 ✅ 即视为健康。

**手动验收（深度排查用）**：

```bash
python3 scripts/normalize_aw_inquiries.py templates/aw_inquiries_sample.json --output /tmp/normalized_aw_sample.json
python3 scripts/score_inquiry_v3.py /tmp/normalized_aw_sample.json --json > /tmp/inquiry_score.json
python3 scripts/build_platform_writeback.py /tmp/inquiry_score.json --config templates/platform_writeback_config.sample.json --output /tmp/platform_writeback_payload.json
python3 -m py_compile scripts/score_inquiry_v3.py scripts/normalize_aw_inquiries.py scripts/build_platform_writeback.py scripts/poll_new_inquiries.py scripts/notify_dispatcher.py scripts/run_scrape.py
```

脚本能输出 `summary`、`results` 和 `platform_writeback_payload.json`，且 `py_compile` 通过，说明交付包内"AW 授权读取结果 → 标准化 → 评分 → 可选飞书/钉钉写回预览"入口可运行。你的账号是否能进入正式 `客户账号已验收`，看现场 AW 授权可见字段、你授权、人审、平台 CLI 授权和 7 天复盘。


---

## Windows 兼容性补丁（2026-05-26 现场补充）

在 Windows + 简体中文系统下，下列问题会复现，需要按本节配置规避，否则脚本不可用：

### 1. 控制台编码：必须用 UTF-8 跑 Python

Windows 控制台默认 GBK，会让 `python xxx.py --json > out.json` 写出 GBK 文件，下游脚本以 UTF-8 读会立刻报 `UnicodeDecodeError`。

**正确做法（每次开新 cmd 都要设）：**
```cmd
set PYTHONUTF8=1
python -X utf8 scripts\normalize_aw_inquiries.py outputs\raw.json --output outputs\normalized.json
```

**重定向 JSON 必须走二进制管道（不要用 `> out.json` 重定向）：**
```cmd
python -X utf8 -c "import sys, subprocess; r=subprocess.run([sys.executable,'-X','utf8','scripts/score_inquiry_v3.py','outputs/normalized.json','--json'],capture_output=True); open('outputs/score.json','wb').write(r.stdout); sys.stderr.write(r.stderr.decode('utf-8','replace'))"
```

> ✅ `run_scrape.py` 已用 `subprocess.run(..., capture_output=True)` + 二进制写盘内部处理，Windows 直接可用，不需要再套这层。

### 2. quantity 字段：必须传 int

`normalize_aw_inquiries.py` 的 quantity 处理只在字段为空时才回退用正则抽数字；若上游传 `"10 units"` / `"7 pcs"` 这类字符串，会直接原样塞下去，导致 `score_inquiry_v3.py` 报
```
TypeError: '>=' not supported between instances of 'str' and 'int'
```

**两种修法（任选其一）：**

A. **上游侧预处理（推荐，不动包内脚本）**：在写入 normalize 输入前把所有 quantity 强转为 int，抽不到数字置 None：
```python
import re
for inq in data["inquiries"]:
    q = inq.get("quantity")
    if isinstance(q, str):
        m = re.search(r"(\d+(?:[\.,]\d+)?)", q)
        inq["quantity"] = int(float(m.group(1).replace(",",""))) if m else None
```

B. **改 normalize 脚本**：把 `normalize_record` 里 `quantity = record.get("quantity")` 那段改成"先用 `extract_quantity(str(quantity))` 抽数字再回退到文本"。

### 3. browser 截图：截图只上传 CDN，本地不落

`browser` sub-agent 的 `browser_screenshot` 默认只把截图上传 CDN 并返回 URL，**不会真正保存到本地**。若需要本地证据文件，必须显式传 `savePath` 参数；否则报告里的本地路径都是不准确的。

---

## 历史版本（不要再用）

- ❌ **`score_inquiry.py` (v2)** 已删除（搬到 `~/.Trash/`）。任何调用 `score_inquiry.py` 的命令都会报 No such file。改用 `score_inquiry_v3.py`，CLI 完全兼容。
- ❌ **`templates/score_inquiry.py`** 也已删除（v2 副本）。
