# ShopSimulator 环境实现说明

## 当前版本的边界

当前环境版本是 `shopsimulator-paper-aligned-v8`。目标是恢复论文中的任务、奖励和终止思路，并修复公开代码中影响运行和复现的问题；它不包含 Reward v3 的替代商品分档、主动放弃奖励、Gold 购买跃迁、候选资格或无进展终止设计。v2 将 API 顶层主奖励从 `r_loose` 切换为 `r_strict`；v3 收紧 Agent 动作协议，搜索栏只对应 `search[...]`，并移除当前冻结商品数据无法提供有效新信息的 Description、Features 和 Reviews 入口；v4 删除数据中不存在的 WebShop `query` 标签及其类型匹配分支，移除 WebShop 英文颜色归一化，并调整预算解析优先级；v5 要求完成全部规格轴后才能购买，为无效动作提供显式反馈，并使用原始轴名区分规格动作；v6 将搜索升级为 `shopsimulator-multifield-bm25-v3`，修复 FTS5 列权重错位，并移除规格索引中的爬取元数据；v7 弃用 HTML 展平后的 `instruction` 页面路线，以 `observation_state` 作为唯一公开页面状态，并由确定性 renderer 生成 Agent 可见的 `observation`；v8 增加显式 runner 终止原因，区分 `action_limit` 与模型生成达到长度上限的 `generation_length`，二者均由环境返回标准零分 reward。

保留的工程改进有三类：用 SQLite FTS5 多字段 BM25 替代不可直接运行的 Java/Lucene 链路；从用户指令和所选 SKU 解析价格；用结构化 observation、环境槽 lease 和稳定切分支持训练与并发评测。这些改进不改变论文奖励公式。

## 运行闭环

环境不访问真实电商网站。商品、任务、搜索结果和页面内容都来自本地商品快照。

```mermaid
flowchart LR
    A["Agent / rollout"] -->|"标准 function tool call"| B["runtime adapter"]
    B -->|"canonical search[...] / click[...]"| C["HTTP API + lease"]
    C --> D["WebAgentTextEnv"]
    D -->|search| E["SQLite FTS5 BM25"]
    D -->|click| F["SimServer session 状态机"]
    E --> F
    F --> G["Jinja HTML（仅内部页面机制）"]
    F --> H["canonical observation_state"]
    H --> I["协议中立文本 renderer"]
    I --> J["Agent observation"]
    J --> A
    F -->|"click[buy now]"| K["论文奖励 r_loose / r_strict / r_success"]
```

所谓“页面跳转”是内存中的 URL、HTML 和 session 状态转换，不依赖 Selenium、Chrome 或网络。搜索从完整商品 JSON 构建的 SQLite 索引取回 ASIN；详情页、规格、翻页、返回搜索和购买都由 session 状态机处理后重新渲染 HTML。HTML 只服务于现有状态机和模板，不再被展平后交给 Agent。Agent 唯一看到的页面内容是公开 `observation_state` 的确定性文本投影，不能任意读取或修改底层商品 JSON。

`observation_state` 是页面事实和可执行动作的唯一公开来源。API 同时返回 `observation_state` 及其规范文本 `observation`；后者只能由 `render_observation_state()` 生成，不允许调用方再从 HTML 或其他私有字段拼接第二套页面。当前 schema 是 `shopping-observation-v7`；版本只保存在结构化状态和轨迹元数据中，不再写入模型可见正文。文本 observation 只描述页面能力、可点击元素和交互结果，不呈现 `search[...]` / `click[...]` 调用语法。旧的 `instruction` 页面字段、`[SEP]` 展平格式和手工追加调用协议的路线已从 API、采样器与参考评测器删除。

模型侧使用标准 function tool calling，runtime 每轮根据 `observation_state` 动态提供：

- `search(query: string)`
- `click(value: enum)`，其中 enum 只包含当前页面可点击值

一次调用只允许一个工具。runtime 将标准 tool call 转换为环境内部的 canonical `search[keywords]` / `click[value]` 字符串。搜索首页通过 `search_available=true` 表示可以提供 `search` 工具，搜索提交按钮不会进入 `click` 的 enum。商品页通过 `selected_options`、`missing_option_axes` 和 `options_complete` 公开规格状态；只有 `options_complete=true` 时，`buy now` 才会进入 `click` 的 enum。无效动作不改变页面但照常计步，并通过 `action_feedback` 和 observation 的交互结果返回 `invalid_format`、`search_unavailable`、`already_selected`、`incomplete_options` 等原因。

规格轴使用商品数据中的原始名称，不做 `颜色分类 → color` 一类轴名归一化。轴限定动作避免不同轴具有相同选项文本时发生覆盖。当前冻结商品数据的 `full_description` 与标题完全重复，且没有 `small_description` 或评论数据，因此商品页不提供 Description、Features、Reviews 动作；这三项 WebShop 遗留入口不会消耗 Agent 的动作预算。

`reset`、槽位释放和评测器截断是 rollout 控制接口，不是 Agent 工具。环境没有 `finish` 动作。并发 rollout 多于环境槽位时，额外的 `reset` 请求在槽池条件变量上排队，并在已有 episode 释放槽位后继续；槽位暂时耗尽不是轨迹失败。

## 关键目录和脚本

- `shop_env/shop_env/pack_api.py`：Flask 服务、环境槽池、lease 校验和健康检查。
- `shop_env/shop_env/debug_ui/`：直接复用同一服务的 Agent 视角调试界面与实验回放盘面；启动服务后分别访问 `/debug-ui`、`/replay-ui`。
- `shop_env/shop_env/replay.py`：只读解析根目录 `runs/` 中的 manifest、summary 和 JSONL trace，以轻量索引支撑实验总览和单 episode 回放。
- `shop_env/shop_env/client.py`：训练 rollout 可复用的有状态 HTTP 客户端。
- `shop_env/shop_env/shop_agent.py`：接收 runtime 转换后的 canonical `search[...]` / `click[...]` 动作并组装 API 结果；模型侧使用标准 function tool calling。
- `shop_env/web_agent_site/envs/web_agent_text_env.py`：页面状态机、session、动作计数和内部 HTML 机制。
- `shop_env/web_agent_site/engine/observation.py`：构造 canonical `observation_state` 并渲染唯一的 Agent 文本 observation。
- `shop_env/web_agent_site/engine/search.py`：确定性的多字段 BM25/SQLite FTS5 搜索。
- `shop_env/web_agent_site/engine/goal.py`：任务目标构造和论文奖励。
- `shop_env/web_agent_site/engine/budget.py`：只从用户指令提取价格上限。
- `shop_env/web_agent_site/engine/variant_price.py`：根据已选规格解析实际购买价。
- `shop_env/scripts/build_clean_dataset.py`：过滤、价格标注和 cleaned v2 构建入口。
- `shop_env/scripts/build_project_splits.py`：从 cleaned v2 生成项目冻结的 persona train/val/test manifest。
- `shop_env/scripts/prepare_data.py`：校验商品库 SHA-256 并构建搜索索引。
- `shop_env/scripts/evaluate_search.py`：在稳定任务切分上计算 Gold-ASIN 检索代理指标。
- `shop_env/scripts/smoke_test.py`：不调用 LLM 的 reset/search/click/purchase 全链路测试。
- `shop_env/configs/environment.json`：冻结运行协议版本。
- `shop_env/configs/task_splits.cleaned.v2.json`：清洗后官方来源分组，仅用于来源追踪和构建项目 split。
- `shop_env/configs/persona_splits.v1.json`：项目冻结的 train/val/test task ID。
- `shop_env/configs/catalog_exclusions.v2.json`：695 个被过滤商品的可审计清单。

## 搜索索引契约与质量检查

当前搜索版本是 `shopsimulator-multifield-bm25-v3`。索引使用 SQLite FTS5、固定的中文二元组及拉丁字母/数字 token、多字段 BM25 和 ASIN 升序 tie-break，不依赖机器本地的分词服务。FTS5 列顺序固定为：

```text
asin UNINDEXED, title, brand, category, model, attributes, options, bullets
```

FTS5 的 `bm25()` 权重按包括 `UNINDEXED` 列在内的声明位置逐列映射。v2 只传入七个业务字段权重，导致 `title=3.0` 落到最左侧的 `asin`，后续权重整体错位，最后的 `bullets` 使用默认权重。v3 为 `asin` 显式传入 `0.0` 占位，再依次传入七个业务字段权重；索引 manifest 同时保存 `fts_columns` 与 `bm25_column_weights`，加载时检查列顺序，避免配置看似正确而运行时错配。

`options` 文档只索引 Agent 可观察和可选择的规格轴名与规格值。原始 `customization_options` 中的图片 URL、价格字符串、可用状态、变体 ASIN 等爬取或运行元数据不再进入检索。价格仍由独立的规格价格模块核验，不通过全文搜索匹配。

权重、字段提取规则或搜索版本变化后必须重建索引；旧版本 manifest 会被加载器拒绝：

```bash
cd shop_env
python scripts/prepare_data.py --force-index
```

可用固定切分运行不依赖 LLM 的离线检索检查：

```bash
cd shop_env
python scripts/evaluate_search.py --split persona_eval --workers 4
```

该脚本分别使用 `instruction_simple` 和完整 `instruction` 作为 oracle 查询，报告 Gold 商品的 `Recall@1/20/150` 与 `MRR@150`。这是用于检测索引退化的代理指标；论文奖励允许满足全部要求的非 Gold 商品成功，因此它不能替代 Agent 端到端奖励评测。

在商品 SHA-256 为 `00d5285b6aca5ade54465e1522821c869c1d5ff5cae6385cea3889a46bb26975`、来源分组 `persona_eval` 共 1274 条任务的 cleaned v2 语料上，v3 基线为：

| oracle 查询 | Recall@1 | Recall@20 | Recall@150 | MRR@150 |
|---|---:|---:|---:|---:|
| `instruction_simple` | 24.10% | 69.07% | 95.68% | 0.3536 |
| 完整 `instruction` | 49.84% | 85.71% | 95.29% | 0.6098 |

对比修复前的 v2，简化指令的 Recall@20 从 64.99% 提升到 69.07%，完整指令的 Recall@20 从 83.05% 提升到 85.71%。后续修改权重、分词或字段文档时，应至少重跑这一固定基线；是否引入稠密检索或混合召回，则应由真实 Agent 查询日志中的失败样本和端到端收益决定，而不是仅凭 Gold-ASIN 指标。

## 商品和任务数据结构

商品顶层常用字段：

- `asin`：本地稳定商品 ID，也是搜索结果中的点击值。
- `title`、`shop_name`、`category`：检索、展示和类型评分字段。冻结数据没有商品 `query` 标签；`observation_state.search_text` 仅表示 Agent 本轮输入的实时搜索文本，不是商品标注。
- `pricing`：爬取时的挂牌价或价格区间，不一定是某个可购买 SKU 的精确价格。
- `customization_options`：规格轴；每个选项通常包含 `value` 和可能的 `price`。
- `attribute`、`full_description`、`small_description`：属性和描述。
- `instructions`：由该商品生成的一个或多个购买任务。
- `user_persona`：个性化任务的用户档案，普通任务可能没有。

`instructions[*]` 的关键字段：

- `instruction`：完整目标；标准模式展示，所有模式都用它构造私有评分目标。
- `instruction_simple`：persona 模式给 Agent 的简化需求。
- `attributes`：论文属性奖励的目标属性列表。
- `instruction_options`：论文规格奖励的目标规格值。

旧的 Reward v3 会把任务标注继续“编译”为品牌、型号、数值规格等约束；当前版本已删除该约束编译层。未被论文奖励消费的标注不会偷偷成为评分门槛。

reset 返回 `task_instruction`、`observation`、可公开的 `user_persona`、无隐藏答案的 `observation_state`、`env_idx`、`lease_id`、`task_mode`、`interaction_mode` 和 `environment_version`。`task_instruction` 是本轮给 Agent 的购物需求；`observation` 是当前搜索首页的页面状态，两者不再复用同一个字段。后续 step 只返回新的 `observation` 和 `observation_state`。默认不返回完整私有目标或 `goal_options`；多轮 Shopper 模拟器可显式请求 `private_task_instruction` 和私有目标，但这些内容不应进入 Agent observation。

## 论文奖励 pipeline

只有 `click[buy now]` 会对所购商品计算正向任务奖励。设属性目标数为 $N_{att}$，规格目标数为 $N_{opt}$，命中数分别为 $M_{att}$、$M_{opt}$：

$$
R_{loose}=R_{type}\frac{M_{att}+M_{opt}+R_{price}}{N_{att}+N_{opt}+1}
$$

$$
R_{strict}=R_{type}R_{attribute}R_{option}R_{price}
$$

$$
R_{success}=\mathbf{1}[R_{type}=R_{attribute}=R_{option}=R_{price}=1]
$$

API 顶层标量 `reward` 返回 `r_strict`，供训练和主要评测直接使用；`reward_detail` 仍同时报告 `r_loose`、`r_strict`、`r_success` 和各分量，便于诊断与论文指标对照。该改动只调整主奖励选择，不改变论文奖励公式，也不引入 v3 映射。

各分量如下：

- `R_type`：类别路径至少两个节点相交或标题词重合率大于 0.2 时为 1.0；否则，标题完全无重合为 0，重合率小于 0.1 为 0.1，其余为 0.5。数据中不存在的 WebShop `query` 字段不参与评分。
- `R_attribute`：目标属性中被商品属性或标题/卖点/描述匹配的比例；`M_att` 是命中个数。
- `R_option`：Agent 已选规格值与目标规格值的匹配比例；`M_opt` 是命中个数。
- `R_price`：未声明预算时为 1；声明预算时，只有可核验的所选 SKU 价格不超过上限才为 1，否则为 0。

`target_asin_match` 仅是诊断指标，不参与三个奖励公式。因此，满足全部要求的非 Gold 商品可以获得 `R_success=1`；反之，买到 Gold ASIN 但选错规格或超预算不能成功。

标题类型匹配优先使用公开代码要求的 `zh_core_web_sm` 名词词性；模型不可用时采用确定性的字面词回退，避免整个环境无法启动。正式对比实验应在所有 worker 上固定相同依赖环境。

## 价格机制和商品过滤

商品价格是爬取快照中的既有数据，不由环境随机生成。但 `pricing=[最低价, 最高价]` 常是展示区间，不能直接说明 Agent 所选组合的成交价。当前流程是：

1. 新数据构建流程只为 persona 任务离线写入 LLM 解析的 `instructions[*].price_upper`；standard 任务显式写入 `null`。运行时仅在该字段为有效数值时直接采用，否则从 `instruction_simple` 解析并在没有结果时回退完整 `instruction`。所有路径都绝不从 Gold 商品价格反推。
2. 若没有价格变化规格轴，使用唯一的选项价或唯一挂牌价。
3. 若恰有一个价格变化轴，必须由 Agent 选择该轴的具体值，再采用该值记录的价格。
4. 原始快照没有可靠的多轴笛卡尔 SKU 价格表；有两个或更多价格变化轴时无法恢复组合价，因此整件商品在数据准备阶段删除。

原始 23,421 个商品中删除 695 个，过滤后为 22,726 个。运行时仍保留多价格轴的 fail-closed 防线，防止错误数据集悄悄使用猜测价格。预算已声明但价格不可核验时 `R_price=0`，并在 `reward_detail.price_verifiable=false` 中显式标记。

### 离线数据清洗流水线

`shop_env/scripts/build_clean_dataset.py` 是薄 CLI，核心实现位于独立的 `shop_env/data_pipeline/`。流水线先为原始任务分配稳定 `task_id`，再过滤多价格轴商品，只把仍有效的 persona 任务发送给 SiliconFlow `Qwen/Qwen3.5-27B`。原始23,421条任务过滤后共有22,726条，其中4,526条 persona 使用LLM标注，18,200条 standard 保留空值并使用运行时正则。它不会覆盖任何输入文件：

- `data/fine_items_eval_train_all.raw.json.gz`：23,421 条不可变源档案；
- `data/fine_items_eval_train_all.cleaned.v2.json.gz`：完成标注后新生成的清洗数据；
- `data/price_annotations.persona.qwen3_5_27b.v3.jsonl`：可断点续跑的 persona 标注缓存，默认不纳入 Git；
- `configs/persona_price_annotations.v2.json`：persona 预算证据的可审计副本；
- `configs/clean_dataset_manifest.v2.json`、`catalog_exclusions.v2.json` 和 `task_splits.cleaned.v2.json`：哈希、排除原因和官方来源分组的显式稳定任务 ID 清单；
- `configs/persona_splits.v1.json`：在全部4,526条cleaned persona上冻结的项目划分，train/val/test为3726/400/400。

默认命令只展示计划，不调用付费 API：

```powershell
cd ShopSimulator\shop_env
python scripts\build_clean_dataset.py
```

Windows PowerShell 中可先用隐藏输入设置临时环境变量，再请求一条数据验证账号、模型与结构化输出：

```powershell
$secret = Read-Host "SiliconFlow API key" -AsSecureString
$env:SILICONFLOW_API_KEY = [Net.NetworkCredential]::new("", $secret).Password
python scripts\build_clean_dataset.py --stage annotate --max-requests 1 --confirm-paid-api
```

单条确认无误后，去掉 `--max-requests` 完成剩余标注，再单独构建产物：

```powershell
python scripts\build_clean_dataset.py --stage annotate --confirm-paid-api
python scripts\build_clean_dataset.py --stage build
python scripts\build_project_splits.py
Remove-Item Env:SILICONFLOW_API_KEY
```

persona 的 `instruction_simple` 与完整 `instruction` 分两阶段处理：程序先只发送简化指令；只有它没有得到有效价格上限时，才发送完整指令。优先级不由模型自行决定。模型每项只返回 `task_id`、`kind`、数值型 `amount` 和原文 `evidence`；代码统一给近似预算增加10%容差。之前 v1 缓存中能按新协议严格验证的有效上限会自动导入，其他记录不会混入新缓存。

每次 HTTP 请求只包含一条 instruction，并只接收一个标注对象；不是在一个请求中塞入多条数据。`--workers` 控制最大在途并发数，默认32；另由全局 `--requests-per-minute` 控制请求启动速率，默认32条/分钟。程序先同步完成并落盘第一条健康检查，然后才放开并发。此后每条请求一完成就立即向 JSONL 追加一行，失败或中断后重跑会自动跳过已缓存的 `(task_id, source_field)`。`--max-batches` 仅作为旧命令的兼容别名保留，但现在与 `--max-requests` 一样表示最多调用多少条数据。单条请求会为每条 instruction 重复发送系统提示词，因此相较批量请求更便于隔离失败和实时保存，但输入 token 总量会更高。

SiliconFlow 的限流按账户和模型统计，可能先触发 RPM 或 TPM。所有 worker 共享同一个限速器；遇到分钟级 429 时，默认整体冷却65秒，同一波429只触发一次冷却，随后继续按全局速率发送。如果冷却后再次触发新一波429，发送速率自动减半。每条 instruction 最多允许20次分钟级限流重试，和 `--retries` 所控制的网络、5xx、结构错误重试分开计数；RPH、RPD、TPD 等长周期限额不会盲目等待。可在确认账户对应模型的限额后调高 `--requests-per-minute`，但 `--workers 32` 本身不代表平台允许持续每秒发出32条请求。

若某个 persona 标注确定不再重试，可显式传入 `--runtime-regex-task-id TASK_ID`（可重复）。该任务不会伪造 LLM 输出：清洗数据写入 `price_upper=null`，审计文件记录 `kind=runtime_regex_fallback`、缺失阶段和原因，运行时按既有的 `instruction_simple` 优先、完整 `instruction` 回退规则使用正则。未显式列出的缺失标注仍会令构建失败，避免无意间大范围降级。

构建完成并审核 manifest、预算统计和排除清单后，可显式激活新商品库并重建索引：

```powershell
python scripts\prepare_data.py `
  --archive data\fine_items_eval_train_all.cleaned.v2.json.gz `
  --dataset-manifest configs\clean_dataset_manifest.v2.json `
  --force-products --force-index
```

`prepare_data.py` 会同时核验压缩包哈希和解压后 JSON 哈希。激活命令只替换可重建的 `items_eval_train.json` 与搜索索引，不修改 raw 或 cleaned v2 压缩包。

无参数运行 `python scripts/prepare_data.py` 只接受 cleaned v2 与对应 manifest，并自动核验二者；不再静默回退旧压缩包。环境启动不选择数据 split，训练和评测代码读取 `persona_splits.v1.json` 后按 task ID 调用环境。

缓存只接受相同源档案 SHA-256、API endpoint、模型、标注协议和 prompt 哈希的记录。模型输出中的 `evidence` 必须是当前输入指令的逐字子串；“左右”等近似预算由代码统一乘以 1.10，LLM 不能自行决定奖励容差。过滤后的稳定 ID 允许出现空洞，环境通过 `goals_by_task_id` 查找目标，split 文件保存明确 ID 列表而不是重新编号后的连续区间。

## 终止和轨迹

- 购买：选完当前商品的全部规格轴后，`click[buy now]` 才可用；执行后环境立即计算奖励并令 `done=true`，终止原因为 `purchase`。
- 动作上限：当前 `shopsimrl` single-turn runtime 默认最多 30 个 Agent→环境动作；达到上限时调用环境终止接口统一生成零分终局，所有论文奖励指标为 0，终止原因为技术性的 `action_limit`。环境协议仍保留 40 步的 `multi_turn` 模式上限，但项目当前没有多轮 Shopper runner。

不存在 `finish`、`graceful_stop`、`early_abstain`、`repeat_loop`、`wrong_purchase` 等 Reward v3 终局/奖励类别。Agent runner 以环境返回的 `done` 为准，终止后不会继续调用该 session；对已终止 session 再调用 `step` 会报错。

环境在内存 session 中记录当前页面、搜索结果、所选规格、动作计数和终局明细；项目根目录的 `shopsimrl` runtime 负责把完整 step、模型元数据和终局结果逐条追加到 JSONL trace。环境服务本身不把轨迹永久写盘。

## Persona 与 `instruction_sample`

公开数据全集没有 `instruction_sample` 字段，原代码访问它会崩溃。当前契约使用 `instruction_simple + user_persona` 作为 persona 模式的可见输入，完整 `instruction` 只保留在环境内部用于评分；缺少 `instruction_simple` 时回退到完整指令。

## 项目 Persona 切分

`task_splits.cleaned.v2.json` 保存清洗后任务原本来自官方 train 还是 eval，只作为来源追踪。`build_project_splits.py` 合并全部4,526条 persona，以固定种子按 ASIN、完整/简化指令、persona 指纹和用户 ID 构造连通组，再将整组分配到 `train=3726`、`val=400`、`test=400`。大型复用 persona 组留在 train，避免单一用户主导 held-out 集。最终训练和评测只读取 `persona_splits.v1.json`，不得再使用官方 `persona_train/persona_eval` 作为项目实验划分。

## Agent、工具与后续 Skill

环境只规定动作、页面状态和评分，不绑定特定 Agent。采样和评测统一由项目根目录的 `shopsimrl` package 与 `scripts/run_shopsimrl.py` 驱动；旧 runner 已删除。

后续增加检索规划、对话、记忆或商品比较 Skill，只要仍调用现有 `search` / `click` function tools，无需修改环境和奖励。只有 Skill 确实需要新环境动作或新可观察状态时，才应另起协议版本；不要把策略偏好编译进奖励。

## 仍无法从公开资料恢复的内容

- 部分 persona 档案、目标规格和商品选项存在语义关联异常，无法从同一快照无损推回原始正确标注，只能过滤、人工复核或重新标注。
- 少数指令写的是“单价/每平方米价格”，商品选项记录的却是整包或整件总价；公开快照没有结构化数量、计价单位和换算关系，不能可靠地自动统一，相关样本仍需人工标注或维护排除清单。
- 论文口径中的 persona 训练数量与公开语料不完全一致，缺失样本无法凭代码恢复。
- `reason_key` / `__reasoning__` 在当前全集没有足够有效标注，无法重建数据生成过程中的隐式解释链；运行和评分不依赖它们。

这些问题不阻塞训练和评测。若项目后续维护人工排除清单，应把商品库清单版本、环境版本和模型 checkpoint 一起记录。