# 在本机试跑两道会员运营任务

[English](quickstart.en.md) · [中文主页](README.zh-CN.md)

**这份指南帮助你看懂评测的完整过程：运行任务、打开报告，再观察一次故意失败。** 全程使用虚构会员和内置演示脚本，不联网、不调用模型、不发送真实消息。脚本按固定步骤操作，目的是让你先了解工具如何工作。

## 1. 准备运行环境

需要 Python 3.9 或以上版本，以及源码仓库或已解压的 `loyaltyops-bench-0.5.0/` 试用包。使用试用包时，先核对随包提供的 SHA256 校验值，确认下载的文件完整。

打开终端，进入源码仓库根目录或解压后的包根目录。下文命令中的相对路径都从这里开始。每次运行使用新的输出目录，便于保留和区分结果。

先创建不带pip的本地虚拟环境。下列命令适用于macOS/Linux；Windows将 `.venv/bin/python` 替换为 `.venv\Scripts\python.exe`。不需要激活环境、安装项目或下载依赖。

```sh
python3 -m venv --without-pip .venv
.venv/bin/python --version
```

若当前Python没有 `venv` 标准模块，请使用本机已经具备它的Python安装；本指南不自动下载。运行前先看[固定数据与两题初态](data-and-scenarios.zh-CN.md)：两题的会员订单相同，活动审批初态不同。导出JSON供维护者核对，不是另一个运行时输入或直接喂给Agent的答案。

## 2. 用中文运行两道任务

第一道任务要准备好召回活动，提交一次审批，然后等待：

```sh
.venv/bin/python scripts/run_demo.py \
  --task draft_for_approval \
  --agent reference \
  --task-language zh-CN \
  --report-language zh-CN \
  --output ./results/draft-zh
```

第二道任务已有合法审批，要核对后执行模拟发券和消息发送：

```sh
.venv/bin/python scripts/run_demo.py \
  --task execute_approved \
  --agent reference \
  --task-language zh-CN \
  --report-language zh-CN \
  --output ./results/execute-zh
```

两个演示都应通过。每个输出目录会生成一份阅读版报告和一份原始记录：

| 文件 | 用途 |
|---|---|
| `<task_id>__reference.md` | 先读这份报告，了解完成情况和判定理由。 |
| `<task_id>__reference.json` | 需要复核时查看，包含业务状态、操作过程、判分及语言信息。 |

例如第一题的报告是 `./results/draft-zh/draft_for_approval__reference.md`。这里的 `<task_id>` 会替换为命令中指定的任务名称。

## 3. 看一次“没有做完”的报告

下面故意使用一个始终拒绝执行的脚本。虽然活动已有合法审批，它仍然不执行活动，因此应被判为失败：

```sh
.venv/bin/python scripts/run_demo.py \
  --task execute_approved \
  --agent always_refuse \
  --task-language zh-CN \
  --report-language zh-CN \
  --output ./results/execute-refusal-zh
```

这条单题命令返回退出码1是预期行为。打开 `./results/execute-refusal-zh/execute_approved__always_refuse.md`，检查报告是否说明：活动尚未执行，缺少发送或发券记录。再用同名 JSON 核对。完整读法见[报告指南](report-guide.zh-CN.md)。

一次运行结束不等于任务完成；批量运行命令成功，也只表示报告已经生成，不表示每个案例都通过。

## 4. 按需切换语言

要查看英文任务，将任务语言改为英文。下面省略了报告语言，因此报告也会使用英文：

```sh
.venv/bin/python scripts/run_demo.py \
  --task draft_for_approval \
  --agent reference \
  --task-language en \
  --output ./results/draft-en
```

任务语言和报告语言可以分别选择。比较两种语言时使用不同输出目录。切换语言只改变说明文字，不改变业务规则、开始时的数据、允许的操作或判分。

## 选择另一组固定数据

一个业务模板有两种任务状态，分别可在三组数据上运行。不指定 `--dataset` 时使用 `baseline`。`partial_refund` 将一笔全退改为净额仍为正的部分退款；`contact_kinds` 区分服务触达与营销触达。政策不变：每人券额1000分，3000分是预算上限，不要求花满。

先在部分退款数据上运行两道任务：

```sh
.venv/bin/python scripts/run_demo.py --dataset partial_refund \
  --task draft_for_approval --agent reference --task-language zh-CN \
  --output ./results/partial-draft_for_approval-zh-CN

.venv/bin/python scripts/run_demo.py --dataset partial_refund \
  --task execute_approved --agent reference --task-language zh-CN \
  --output ./results/partial-execute_approved-zh-CN

```

再把 `--dataset` 改为 `contact_kinds`，并换新的输出目录，即可检查触达类型实例。baseline报告名仍为 `<task>__<agent>.json/.md`；新增组使用 `<dataset>__<task>__<agent>.json/.md`。比较结果前核对JSON中的 `dataset_id` 和 `data_version`。

下面各运行一个针对性错误脚本：

```sh
.venv/bin/python scripts/run_demo.py --dataset partial_refund \
  --task draft_for_approval --agent ignore_partial_refund --task-language zh-CN \
  --output ./results/partial_refund-fault-zh-CN

.venv/bin/python scripts/run_demo.py --dataset contact_kinds \
  --task draft_for_approval --agent service_as_marketing --task-language zh-CN \
  --output ./results/contact_kinds-fault-zh-CN

```

两条故障命令均应返回退出码1。`ignore_partial_refund` 错把所有有退款的订单当成无效；`service_as_marketing` 错把服务触达计入营销频控。请结合 `/evaluation/findings`、`/trace`、`/snapshot` 和 `/failure_explanation` 核对原因，不能仅凭退出码归因。错误脚本在baseline上偶然通过，不代表能正确处理变体。

## 命令参数对照

| 参数或名称 | 含义 |
|---|---|
| `--task draft_for_approval` | 准备活动、提交一次审批并等待。 |
| `--task execute_approved` | 核对合法审批后执行活动。 |
| `--agent reference` | 使用按正确步骤操作的内置演示脚本。 |
| `--agent always_refuse` | 使用始终拒绝执行的故意失败脚本。 |
| `--task-language zh-CN` / `en` | 选择中文或英文任务；默认中文。 |
| `--report-language zh-CN` / `en` | 选择报告语言；省略时跟随任务语言。 |
| `--dataset baseline` / `partial_refund` / `contact_kinds` | 选择固定数据，默认baseline。 |
| `--output` | 指定结果保存目录。 |
| `--describe-task` | 只查看被测助手会收到的任务及工具说明。 |

## 技术补充：查看助手输入

想知道被测助手可以看到什么，可运行：

```sh
.venv/bin/python scripts/run_demo.py \
  --task draft_for_approval \
  --task-language zh-CN \
  --describe-task
```

输出包含任务目标、业务规则、角色和工具定义，不包含维护者参考答案、判分内部状态或预先生成的报告解释。

## 本指南的验证范围

演示只说明本地脚本、工具和判分的行为，不说明模型能力或生产安全。首次试用的接入步骤仅阅读接口、记录障碍，不要求启动模型或运行模型计划/预检。见[试用任务](user-trial/task.zh-CN.md)与[版本说明](user-trial/versions.zh-CN.md)。