---
title: 脚本清单-Accio Work 必读
created: 2026-05-25
updated: 2026-05-28
type: delivery-script
audience: merchant-operator
tags: [国际站运营, 询盘分级, 脚本清单, Accio Work]
---

# 脚本清单 — Accio Work 必读

> ⚠️ **这是冷启动的导航总图。** 任何关于"用哪个脚本"、"怎么调用"的问题，请只信本文件。其它 *.md 是设计文档，CLI 接口以本文为准。

## 唯一统一入口

**推荐通过 `run_scrape.py` 调用，它已经把全链路串好了**：

```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

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

# 全量回溯（不推送）
python3 scripts/run_scrape.py --mode full-backfill --backfill-days 90 --force
```

---

## 真实数据流（已端到端验证）

```
[采集] scripts_engine/scrape_inquiries.py  →  outputs/<raw>.json
   ↓
[标准化] normalize_aw_inquiries.py <input> --output normalized.json
   ↓
[评分 v3] score_inquiry_v3.py <normalized> --json   ※ JSON 走 stdout
   ↓                                              ※ 文件必须命名 score_*.json
[写盘 outputs/score_<ts>.json]
   ↓
   ├─→ [飞书钉钉] build_platform_writeback.py <score> --config <cfg> --output payload.json
   │       ↓ command_plan（交给 Accio Work 执行 lark-cli / dws）
   │
   └─→ [增量推送] poll_new_inquiries.py
           ↓ 自扫 outputs/score_*.json + 比对 seen_inquiry_ids.json
           ↓ 生成 outputs/push_payloads/<new>.json
       [兜底通道] notify_dispatcher.py --payload <push_payload.json>
           ↓ 微信 ClawBot 或 lark_cli / dws_cli（按 config/notify_channels.json）
```

---

## 脚本清单（按职责分组）

### 🟢 统一入口（你只用调这个）

| 脚本 | 真实 CLI | 何时用 |
|---|---|---|
| `run_scrape.py` | `--mode {trial-sample,new-only,full-backfill,dry-run-pipeline}` | 所有场景 |

### 🟡 数据处理（被 run_scrape 调用，也可手动跑）

| 脚本 | 真实 CLI（已 grep 源码验证） | 说明 |
|---|---|---|
| `normalize_aw_inquiries.py` | `<input.json> [--rules rules.json] --output normalized.json` | 字段标准化，缺失字段留空（评分阶段决定缺省值） |
| `score_inquiry_v3.py` | `<normalized.json> [--config cfg.json] [--history-scores hist.json] --json` ⚠️ JSON 输出**走 stdout**，需重定向 | v3 评分引擎 167 分，含 chat_signals 30 分 |
| `build_platform_writeback.py` | `<score.json> [--config cfg.json] --output payload.json` | 生成飞书/钉钉的 command_plan（给 AW 执行） |

### 🔵 推送链路（cron 必用）

| 脚本 | 真实 CLI | 说明 |
|---|---|---|
| `poll_new_inquiries.py` | `[--dry-run] [--test-push]` | **自扫** `outputs/score_*.json` 做增量 diff，写 `outputs/push_payloads/*.json`。**跳过** `score_30.json` 和含 `compare` 的文件 |
| `notify_dispatcher.py` | `--payload <file>` / `--message <文本>` / `--channels lark_cli,wechat_clawbot` / `--test-all` / `--show-config` | 按通道推送一条 payload。首次跑会生成 `config/notify_channels.json` |

### 🟣 辅助（按需手动调用）

| 脚本 | 真实 CLI | 说明 |
|---|---|---|
| `fetch_merchant_profile.py` | 见脚本 `--help` | 拉取商家画像（评分阶段如启用 industry_match 权重需用到） |
| `alibaba_assign.py` | 见脚本 `--help` | 国际站后台分配询盘，**需客户额外授权** |
| `_path_helper.py` | （工具模块） | 跨平台路径解析；其他脚本 import 它 |

### 🔴 引擎层（讲师版核心，scripts_engine/）

| 脚本 | 说明 |
|---|---|
| `scripts_engine/scrape_inquiries.py` | Playwright 抓取器（被 run_scrape 调用，见下方真实 CLI） |
| `scripts_engine/accio_scrape_manager.py` | Lock 状态机 2400+ 行，支持长任务断点续传（full-backfill 用） |
| `scripts_engine/ENGINE_SKILL_REF.md` | 引擎层 CLI 文档，详见此文件 |

**`scrape_inquiries.py` 真实 CLI（已 grep 源码 2026-05-26）：**

| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| `--mode new` | str | new | 运行模式（new = 今日新建询盘） |
| `--depth {quick,normal,full}` | choice | (依模式自动) | quick=不翻详情；normal=翻3次；full=翻到底 |
| `--max N` | int | 内置默认 | **最多抓取询盘条数**（⚠️ 不是 `--limit`） |
| `--max-detail N` | int | — | 最多抓详情条数，0=只抓列表 |
| `--start-time` / `--end-time` | str | "" | 显式时间窗（YYYY-MM-DD 或时间戳） |
| `--batch-root <dir>` | str | `outputs/inquiries/` | 分片落盘根目录 |
| `--chunk-days N` | int | 1 | 批处理分片天数 |
| `--resume` | flag | False | 批处理跳过已存在分片 |
| `--category` / `--assignee` / `--buyer-name` | str | "" | 过滤条件 |
| `--stdout-json` | flag | False | **JSON 走 stdout**（不写默认 `inquiries.json`） |
| `--clear-login-state` | flag | False | 删除登录 cookie 后退出 |
| `--list-assignees` | flag | False | 只列出业务员名单 |

**默认输出**：不传 `--stdout-json` 时，结果写入 `<项目根>/inquiries.json`（每次覆盖）。`run_scrape.py` 内部统一用 `--stdout-json` + 重定向到带时间戳的文件，避免覆盖和工作目录污染。

**典型调用（run_scrape.py 内部使用）：**
```bash
# trial-sample 模式
python3 scripts_engine/scrape_inquiries.py --max 10 --depth quick --stdout-json > outputs/trial_sample_<ts>.json

# new-only 模式（cron）
python3 scripts_engine/scrape_inquiries.py --mode new --stdout-json > outputs/new_only_<ts>.json
```

---

## 输出命名约定（被 poll 依赖，不要乱改）

| 文件名 pattern | 谁生成 | 谁读取 | 备注 |
|---|---|---|---|
| `outputs/normalized_*.json` | normalize | score_v3 | 时间戳防覆盖 |
| `outputs/score_*.json` | score_v3 | poll, writeback | **必须 `score_` 前缀**，poll 才会扫到 |
| `outputs/score_30.json` | （基线） | — | poll **自动跳过**，保留作基线对比 |
| `outputs/*compare*.json` | （人工对比） | — | poll **自动跳过** |
| `outputs/push_payloads/*.json` | poll | notify_dispatcher | poll 写，notify 读 |
| `outputs/seen_inquiry_ids.json` | poll | poll | poll 自己维护去重表 |
| `outputs/writeback_*.json` | build_platform_writeback | Accio Work 主 Agent | 包含 command_plan 给 AW 调 lark-cli/dws |

---

## Windows 兼容性（⚠️ 必读）

1. **强制 UTF-8**：所有调用前 `set PYTHONUTF8=1`，Python 用 `python -X utf8`
2. **stdout 重定向陷阱**：Windows GBK 默认编码会破坏 JSON。`score_inquiry_v3.py --json` 在 Windows 不能用 `> out.json`，必须 `subprocess.run(..., capture_output=True)` + `open(path, "wb")` 写二进制
3. **quantity 字段**：`normalize` **不会**自动把 `"10 units"` 转成 int，评分前要保证 `quantity` 是 int
4. **路径**：所有脚本用 `pathlib.Path` 和 `_path_helper.py`，不要硬编码 `/`

`run_scrape.py` 已经按以上规则用 `subprocess.run(capture_output=True)` 重定向 score 的 stdout，Windows 直接可用。

---

## 配置文件

| 配置 | 路径 | 谁生成 | 内容 |
|---|---|---|---|
| 推送通道 | `config/notify_channels.json` | 首次跑 `notify_dispatcher.py` 自动生成 | 启用哪些通道、chat_id |
| 评分配置 | `config/score_config_v3.json` | 可选，无则用脚本内默认 | 权重、阈值、grade 切分 |
| writeback 模板 | `templates/platform_writeback_config.sample.json` | 内置 | 飞书/钉钉 chat_id、表格 schema |
| 标准化规则 | `templates/normalize_rules.sample.json`（可选） | 内置 | 字段映射规则 |
| 去重表 | `outputs/seen_inquiry_ids.json` | `poll_new_inquiries.py` 维护 | 已推送 inquiry_id 集合 |

---

## 常见问题速查

**Q: 评分跑出来 S/A 全是 0？**
A: 检查 `pilot_inquiries_30.json` 这种试跑样本的字段完整度。S 需要 ≥80 分，A 需要 ≥65 分。如果原始数据普遍缺 `business_type`、`account_registered_months`、`company.name_or_website` 等高权重字段，正常会全集中在 B/C/无效。这不是 bug，是数据本身就低质量。

**Q: poll 显示"新增 0 条"但我刚跑完 score？**
A: 看一下 `outputs/seen_inquiry_ids.json` 是不是已经记录过这批 ID。如果想重推，删除该文件即可。

**Q: notify 推送没反应？**
A: 跑 `python3 scripts/notify_dispatcher.py --show-config` 看启用了哪些通道。微信 ClawBot 走 `notify_user tool`（由 Accio Work 主 Agent 触发，不是脚本直推）。

**Q: 我想跳过推送只看评分？**
A: `python3 scripts/run_scrape.py --mode new-only --no-notify`

**Q: 怎么验证整个工具包没问题？**
A: 直接跑 `python3 scripts/run_scrape.py --mode dry-run-pipeline`。这会用 `outputs/pilot_inquiries_30.json` 真实样本走完 normalize→score→writeback 三阶段，不联网。三阶段全 ✅ 就是健康。

---

## 历史版本说明

- ❌ **`score_inquiry.py` (v2)** 已删除，搬到 `~/.Trash/`。不要再引用
- ✅ **`score_inquiry_v3.py`** 是唯一现役评分器（167 分制，含 chat_signals）
- v3.0.4 起，历史填表模板（`询盘样本模板.md`、`业务规则待填写.md` 等）和 `飞书钉钉CLI表格与消息写回模块.md` 等已从交付包移除；规则配置改走 `业务规则配置-对话方式.md`

---

## 验证日志

最近一次端到端 dry-run：**2026-05-26 17:37** ✅
- `pilot_inquiries_30.json` (30 条) → normalize → score (B=3 C=19 无效=8) → writeback (58 KB)
- 所有阶段产物在 `outputs/`，阶段日志在 `run_logs/`
