REFACTOR_HANDBOOK.md

# 交易系统重构手册（Refactor Handbook）

> **定位**：这不是一次性重构方案，而是**长期操作手册**。任何未来的代码改动（bug 修复 / 加新策略 / 调参 / 换模型 / 新对手模式）都应该沿本手册操作，产出符合规范的代码 + 自测 + 部署 + 观察闭环。
>
> **读者**：你自己、本地 agent、任何未来接手的人。
>
> **配套文档**：
> - `20260713_strategy_inventory.md` — 现存 136 条策略的资产台账
> - `谁是卧底-大厂操盘手竞赛规则.md` — 游戏规则（唯一权威）
> - `config/strategy_<profile>.yaml` — 所有可调参数（本手册产出的目录）
>
> **版本约定**：本手册自身也用 semver：本次为 `v1.0.0`。修改架构规则算 major，加分类/规范算 minor，勘误算 patch。改本手册必须同时改 `CHANGELOG` 段。

---

## 目录

- [第 1 章 — 使用方式](#第-1-章--使用方式)
- [第 2 章 — 目标架构：五层与数据流](#第-2-章--目标架构五层与数据流)
- [第 3 章 — 每层职责边界（Rules of Layer）](#第-3-章--每层职责边界rules-of-layer)
- [第 4 章 — 变更分类决策树](#第-4-章--变更分类决策树)
- [第 5 章 — 各类变更的操作规范](#第-5-章--各类变更的操作规范)
  - [5.1 加一条新策略](#51-加一条新策略)
  - [5.2 修改已有策略](#52-修改已有策略)
  - [5.3 调整数值参数](#53-调整数值参数)
  - [5.4 修 bug（正确性问题）](#54-修-bug正确性问题)
  - [5.5 加一个 Feature（衍生指标）](#55-加一个-feature衍生指标)
  - [5.6 加一个新的 Event 类型](#56-加一个新的-event-类型)
  - [5.7 修改 LLM 参与方式](#57-修改-llm-参与方式)
  - [5.8 修改基建 / 状态层](#58-修改基建--状态层)
- [第 6 章 — 通用编码规范](#第-6-章--通用编码规范)
- [第 7 章 — 自测规范](#第-7-章--自测规范)
- [第 8 章 — 部署规范](#第-8-章--部署规范)
- [第 9 章 — 观察规范](#第-9-章--观察规范)
- [第 10 章 — 常见坑与冲突协议](#第-10-章--常见坑与冲突协议)
- [第 11 章 — 术语与命名约定](#第-11-章--术语与命名约定)
- [第 12 章 — PR 变更 Checklist（贴在每次 PR 里）](#第-12-章--pr-变更-checklist贴在每次-pr-里)
- [CHANGELOG](#changelog)

---

## 第 1 章 — 使用方式

### 1.1 什么时候读本手册

**必读**：
- 拿到"加一个策略""改一个策略""改一个参数""修一个 bug"的任何需求时
- 部署一版新代码之前
- 部署之后要看"改动到底生效了没"时
- 出现线上事故要回滚时

**建议读**：
- 加入项目后，第 2、3 章一次读通
- 每次改本手册后（跟随 CHANGELOG）

### 1.2 怎么用

**标准流程（黄金四步）**：

```
需求 ──► 第 4 章分类决策树，判定属于 5.1–5.8 哪一类
     ──► 打开对应小节，照规范改
     ──► 走第 7 章自测（unit + feature + replay 三层）
     ──► 走第 8 章部署（canary → 观察 → 全量或回滚）
```

**不要跳步**：手册里每一条规范都是有历史事故垫底的（大部分能追溯到 `STRATEGY_V*.md` 里一次具体的翻车）。跳步 = 重复历史事故。

### 1.3 手册与代码的关系

- **代码是执行体，手册是契约**。冲突时以手册为准，代码要改
- 除非改的是 bug 修正，否则不允许"代码这么写因为历史原因"这类理由
- 手册规定"必须"的事情，本地 agent 必须做；"建议"的事情可以延后但要 TODO 标注

### 1.4 兼容原则（重要）

> 本地代码持续被 agent 修改，本手册可能落后于代码状态。**手册规定的是"结构和流程"，不是"具体行数"**。

- 手册里的目录结构和文件名是**契约**，代码里必须存在
- 手册里的**行号从不精确引用**——只用"某函数""某模块"等语义定位
- 新加的策略不需要改手册；**新的策略类型**（比如"元策略"）才需要
- 遇到手册说的东西代码里找不到，第一动作：向用户/上游确认是"代码欠改"还是"手册需更新"

---

## 第 2 章 — 目标架构：五层与数据流

### 2.1 五层总图

```
┌─────────────────────────────────────────────────────────────────┐
│  L5. Transport 层  (app.py + agent_shell.py)                     │
│      HTTP 入口 / 竞速网关 / FastAPI 端点                          │
├─────────────────────────────────────────────────────────────────┤
│  L4. State 层  (state/)                                          │
│      唯一 Source of Truth (SoT)                                  │
│      - GameState: dataclass, 不可变                              │
│      - Reducer: (state, event) → new_state  纯函数, event sourcing│
│      - PendingLedger / Replay 持久化                             │
├─────────────────────────────────────────────────────────────────┤
│  L3. Feature 层  (features/)                                     │
│      唯一负责"数值计算"的地方                                     │
│      - cluster_gain, opp_needs, card_value, pool_left…           │
│      - 全是纯函数, 输入 GameState, 输出 dataclass, 100% 可测试   │
├─────────────────────────────────────────────────────────────────┤
│  L2. Strategy 层  (strategies/)                                  │
│      唯一负责"决策"的地方                                        │
│      - class Strategy: match(ctx)/act(ctx) 协议                  │
│      - 每个策略一个文件, ≤120 行, 单一职责                       │
│      - StrategyRouter 按 priority 串起来                         │
├─────────────────────────────────────────────────────────────────┤
│  L1. LLM Adapter 层  (llm/)                                      │
│      唯一调用外部模型的地方                                       │
│      - LLMArbitrator.pick(): 从多个 HIT/UNSURE 里选一个策略      │
│      - SpeechGen.render(): 生成话术 message                      │
│      - VisionParser.parse(): 解析图片棋盘                        │
└─────────────────────────────────────────────────────────────────┘
```

**核心不变量（Invariants）**：
1. **上层依赖下层，下层永远不知道上层**。L2 引用 L3、L4；L3 引用 L4；L4 不引用任何上层
2. **L5 只做 IO**；L4 只做状态管理；L3 只做计算；L2 只做决策；L1 只做外部调用
3. **State 只在 perceive 时变更**；interact 期间 State 冻结（快照）
4. **每一层可独立替换**：换 LLM provider 只改 L1；换定价公式只改 L3；加策略只加 L2

### 2.2 目录结构（契约）

```
werewolftown/
├── __init__.py
├── agent.py                     # WerewolfTownLLMAgent 主类 (L5)
├── transport/                   # L5
│   ├── endpoints.py             # FastAPI 端点定义
│   ├── race_gate.py             # 并发竞速网关（async 版）
│   └── debug_views.py           # /debug/* HTML 视图
├── state/                       # L4
│   ├── game_state.py            # GameState dataclass
│   ├── events.py                # Event 类型 + 枚举
│   ├── reducer.py               # 纯函数 (state, event) → state
│   ├── pending_ledger.py        # pending/sold/cancelled 统一账本
│   └── persistence.py           # replay 落盘 + 恢复
├── features/                    # L3
│   ├── clusters.py              # 集群 / 边际增益 / 满额分析
│   ├── card_value.py            # card_value(state, card, purpose)
│   ├── plot_value.py            # plot_value(state, plot, viewer)
│   ├── opponents.py             # opp_needs / leader / afk / strong
│   ├── pool.py                  # pool_left / scarcity
│   └── pricing.py               # snap_price / dead_zone / lambda
├── strategies/                  # L2
│   ├── base.py                  # Strategy Protocol + DecisionContext + MatchResult
│   ├── router.py                # StrategyRouter
│   ├── select_plots/            # 选地策略族
│   │   ├── enumerate_combos.py
│   │   └── ...
│   ├── plan_build/              # 建设策略族
│   │   └── greedy_plus_local_search.py
│   ├── propose_trade/           # 12+ 个发起策略
│   │   ├── _order.py            # priority 声明
│   │   ├── r4_leader_skip.py
│   │   ├── buy_card_for_full_cluster.py
│   │   ├── buy_adjacent_plot.py
│   │   ├── buy_plot_combo.py
│   │   ├── ...
│   │   └── skip.py
│   └── evaluate_trade/          # 7+ 个评估策略
│       ├── _order.py
│       ├── multi_deal_pick_best.py
│       ├── reject_no_empty.py
│       └── ...
├── llm/                         # L1
│   ├── client.py                # OpenAI 兼容客户端
│   ├── arbitrator.py            # 从多候选选一个
│   ├── speech.py                # 话术生成
│   └── vision.py                # 视觉解析
├── constants/                   # 静态数据
│   ├── board_grid.py            # 52 工位邻接表（不可变）
│   ├── shop_rules.py            # FULL_COUNTS / CARD_POOL / REVENUE_TABLE
│   └── phases.py                # GamePhase 枚举
├── sanitize.py                  # 玩家名/message/JSON 过滤
config/
├── strategy_stable.yaml         # 生产参数（默认）
├── strategy_canary.yaml         # 灰度参数
└── strategy_dev.yaml            # 本地实验
replays/
└── <game_id>/
    ├── events.jsonl             # perceive 事件流
    ├── decisions.jsonl          # interact 决策日志
    └── meta.json                # 对局元信息
tests/
├── unit/                        # 纯函数单元测试
├── features/                    # Feature 层测试
├── strategies/                  # 策略层测试
└── replay/                      # 完整对局回放测试
```

### 2.3 数据流总图

```
                perceive(req)                              interact(req)
                     │                                          │
                     ▼                                          ▼
              ┌─────────────┐                          ┌───────────────┐
              │  L5 shell   │                          │  L5 shell     │
              │ - dedupe    │                          │ - race_gate   │
              │ - persist   │                          │ - snapshot    │
              └──────┬──────┘                          └───────┬───────┘
                     │ Event                                   │ ctx
                     ▼                                         │
              ┌─────────────┐                                  │
              │  L4 reducer │                                  │
              │  纯函数     │                                  │
              │  state <    │◄─── (state, event) → new_state ──┤
              │   append    │                                  │
              └──────┬──────┘                                  │
                     │ new_state                               │
                     ▼                                         ▼
              ┌────────────────────────────────────────────────┐
              │  L3 features (纯函数, on demand)               │
              │  从 state 派生 cluster / opp_needs / pricing…  │
              └────────────────────┬───────────────────────────┘
                                   │  DecisionContext (frozen)
                                   ▼
                              ┌─────────────┐
                              │ L2 router   │  按 priority 遍历策略
                              │             │  ┌── all MISS → default
                              │  strategy   │──┤── 1 HIT     → strategy.act()
                              │  match/act  │  └── multi UNSURE → LLM 仲裁
                              └──────┬──────┘
                                     │ Action
                                     ▼
                                ┌────────────┐
                                │ L1 speech  │  只填 message
                                │ (可选)     │
                                └──────┬─────┘
                                       │ AgentResp
                                       ▼
                                   HTTP response
```

**关键性质**：
- perceive 路径**只写 state**，不做决策
- interact 路径**只读 state**，state 保持冻结
- Feature 层是**惰性计算**——DecisionContext 只暴露 property/method，策略用到才算
- 一次 interact 内，同一个 ctx 被所有策略共享，保证一致性视图

---

## 第 3 章 — 每层职责边界（Rules of Layer）

> 每层都有 **DO / DON'T / 判断标准**。违反标准的 PR 直接打回。

---

### 3.1 L5 Transport 层

**DO**：
- 处理 HTTP 请求解析、响应封装
- 并发竞速（同一 cache_key 只跑一次真实逻辑，其它请求 await future）
- Replay 事件流落盘（perceive 事件一到就 append）
- 装配子系统：从 config 装载 State/Feature/Strategy/LLM，注入依赖
- 提供 `/debug/*` HTML 视图

**DON'T**：
- 做任何决策计算（去 L2）
- 直接读写 memory 变量（去 L4）
- 调 LLM（去 L1）

**判断标准**：
- 如果这个文件里出现"if round == X" 或 "if my_cash > Y" → 违规
- 如果这个文件里 import 了 L2/L1，是合法的（装配）；但不能反过来
- 单文件应 ≤ 200 行

---

### 3.2 L4 State 层

**DO**：
- 定义 `GameState` dataclass（不可变，`frozen=True` 或用 pyrsistent）
- 定义 `Event` 类型枚举 + 每个事件的字段
- 实现 `reduce(state: GameState, event: Event) -> GameState` **纯函数**
- 实现 `PendingLedger`（合并旧 `pending_proposals` / `recent_sold_plots` / `sold_this_round` / `ft_cancel_*`）
- 实现 `persistence.py`：`save_event(game_id, event)` / `load_events(game_id) -> list[Event]` / `rebuild_state(events) -> GameState`
- 提供 `apply(event)` 便捷方法：包装 reducer + 落盘

**DON'T**：
- 引用任何 L3/L2/L1 模块
- 有任何"策略""建议""定价"字样的函数
- 直接调用 `random`、`time.time()`、`os.getenv()`（这些是副作用）
- 允许"允许 memory 被外部改写"的接口（如 `set_variable`）

**判断标准**：
- 每个函数必须能这样测试：`assert reduce(state_before, event) == state_after`
- state 一定是 dataclass，字段命名明确（`cash: int`、`plots: frozenset[int]`）
- 不允许 `int` 和 `str` 混用作为 key
- 服务器重启后 `rebuild_state(load_events(game_id))` 必须能 100% 还原

**关键契约**：
- `GameState` 必须包含：`player_id`、`round`、`cash`、`plots`、`shops`、`built_on: dict[int, str]`、`other_players: dict[str, PlayerView]`、`pending: PendingLedger`、`initial_cash`
- `GameState.replace(**kwargs)` 返回新实例，不改原实例
- 所有集合用 `frozenset` / `tuple`，杜绝共享可变引用

---

### 3.3 L3 Feature 层

**DO**：
- 纯函数：输入 `GameState` + 参数，输出 dataclass 或原始类型
- 计算集群 / 满额进度 / 边际增益 / 稀缺度 / 领先者 / opp_needs
- 提供缓存装饰器 `@feature_cache`（同一 GameState 实例内缓存）
- 命名规范：动词 + 名词，明确返回值语义
  - ✅ `calc_cluster_revenue(...)`, `card_value_for_selfuse(...)`, `pool_remaining(...)`
  - ❌ `analyze()`, `get_stuff()`, `compute()`

**DON'T**：
- 有任何 if/else 输出"接受""拒绝""跳过"（决策去 L2）
- 引用 L2/L1
- 调用 `random`（策略层需要随机化就让 ctx 传入 rng）
- 修改传入的 state（必须返回新对象）

**判断标准**：
- 每个函数写完先想：**能不能一句话说清"输入 X 输出 Y"**？说不清就是没抽象好
- 每个函数必须能这样测试：`assert calc_cluster_gain(state1, plot=5, shop="Happy") == 30000`
- 大部分函数应 ≤ 30 行；≥ 50 行说明需要拆

**关键契约**：
- `card_value(state, card, purpose: Literal["selfuse","sell","combo"]) -> int` 是统一入口，杜绝多头维护
- `plot_value(state, plot, viewer: str) -> int` 从 `viewer` 的视角算价值
- `Offer` dataclass 用 `to_me` / `from_me` 命名字段，禁止传 `offer_*/demand_*` 4 元组

---

### 3.4 L2 Strategy 层

**DO**：
- 每个策略一个文件，实现 `Strategy` 协议
- 通过 `match(ctx) -> MatchResult` 声明"我要不要处理这个局面"
- 通过 `act(ctx) -> Action` 产出决策
- `_order.py` 里显式声明本 phase 下所有策略的优先级
- 复杂策略可拆多个 `_helper.py`，但 helper 必须在同一策略目录下、且不跨策略引用

**DON'T**：
- 引用其他策略模块（跨策略共享逻辑 → 提到 L3 features 或 helper）
- 直接调用 LLM（走 `ctx.request_llm_arbitration(...)`）
- 修改 ctx / state
- 有 `import random`（用 `ctx.rng`）
- 单文件 > 120 行（超了就拆）

**判断标准**：
- 一个策略的 `match()` 应能一句话说清"什么时候触发"
- 一个策略的 `act()` 应能一句话说清"触发后返回什么"
- 如果你在一个策略里写"如果 round==4 走 A、否则走 B"——那是**两个策略**，拆开
- 策略之间不允许知道彼此的存在（除了 `_order.py` 声明优先级）

**关键契约**：
- `match()` 返回 `MatchResult.HIT` / `MatchResult.MISS` / `MatchResult.UNSURE`
- `act()` 只返回 `Action` dataclass；`Action` → `AgentResp` 的转换在 L5
- 每个策略必须暴露 `NAME: str`、`PRIORITY: int`、`PHASE: GamePhase`

---

### 3.5 L1 LLM Adapter 层

**DO**：
- 唯一的 OpenAI 客户端封装（文本 + 视觉分开）
- `LLMArbitrator.pick(ctx, candidates: list[Strategy]) -> Strategy`
- `SpeechGen.render(action: Action) -> str` （生成 message，禁止改 action 其它字段）
- `VisionParser.parse(snapshot) -> BoardView`
- Prompt 模板集中在 `llm/prompts/` 目录，一个用途一个文件

**DON'T**：
- 做任何数值计算 / 决策 / 定价
- 直接输出 `AgentResp`
- Prompt 里塞对手 message（永远走 sanitize 层，且 L1 不主动读 message）
- 有超过 10 个 Prompt 模板（Prompt 爆炸 = 抽象没做好）

**判断标准**：
- LLM 的输出永远是 **枚举**（策略名 / 话术字符串 / JSON dict），不是自由文本
- LLM 输出必须走 pydantic 校验；失败 fallback 到确定性策略
- 单次 LLM 调用 ≤ 4s；超时兜底

**关键契约**：
- `LLMArbitrator.pick()` 返回值必须是 `candidates` 里的一员，否则 raise
- LLM 失败不能让决策失败——所有调用点都有代码兜底

---

### 3.6 依赖方向速查表

| 层 | 可以 import 的 | 不可以 import 的 |
|---|---|---|
| L5 | 所有下层 | — |
| L4 | 只有 `constants/` + `sanitize.py` | L5, L3, L2, L1 |
| L3 | L4 + `constants/` | L5, L2, L1 |
| L2 | L3 + L4 + `constants/` | L5, L1（除 `ctx.request_llm_*`） |
| L1 | 只有 `sanitize.py` + `constants/` | L5, L4, L3, L2 |

**跨层通信只能通过 DecisionContext / Action / Event 三种数据契约。**

---

## 第 4 章 — 变更分类决策树

> 拿到一个需求（对局观察、bug 报告、想加的新策略），先走这棵树，落到 5.1–5.8 的一个小节。

```
需求进来
  │
  ├─ 是"决策错了"（agent 做了/没做某件事，我觉得应该反过来）
  │     │
  │     ├─ 触发条件本身就没有对应策略  ────► 5.1 加一条新策略
  │     ├─ 策略触发了但产出错  ─────────────► 5.2 修改已有策略
  │     ├─ 策略逻辑对，但阈值/价格不对  ────► 5.3 调整数值参数
  │     └─ 策略逻辑对，但传入的数值就是错的
  │           │
  │           ├─ 状态错（cash/plots/built_on 不对）─► 5.8 修改基建 / 状态层
  │           └─ 派生指标错（cluster/lead/opp_needs）─► 5.5 加/修 Feature
  │
  ├─ 是"代码崩了 / 超时 / 数据丢失"  ─────────► 5.4 修 bug
  │
  ├─ 是"游戏规则变了 / 后端消息类型变了"  ────► 5.6 加一个新的 Event 类型
  │
  ├─ 是"想让 LLM 参与更多 / 更少"  ───────────► 5.7 修改 LLM 参与方式
  │
  └─ 是"想改架构本身 / 加新的一层"  ──────────► 走本手册的第 2、3 章升级流程
```

### 4.1 分类判断口诀

- **加什么** → 5.1（策略）/ 5.5（Feature）/ 5.6（Event）
- **改什么** → 5.2（策略行为）/ 5.3（参数）/ 5.7（LLM 用法）
- **修什么** → 5.4（bug）/ 5.8（基建）

### 4.2 何时需要跨类

一次改动可能跨类：

| 场景 | 落地路径 |
|---|---|
| 新策略需要一个之前没算过的指标 | **先** 5.5 加 Feature，**再** 5.1 加策略 |
| 修策略时发现下面的估值有 bug | **拆两个 PR**：先 5.4 修 bug（含回归测试），再 5.2 改策略 |
| 加 Event 后要让某策略响应它 | **先** 5.6 加 Event + reducer，**再** 5.5/5.1 更新 Feature/策略 |

**原则：一个 PR 只做一件事**。跨类改动分多个 PR，每个 PR 都过 checklist。

---

## 第 5 章 — 各类变更的操作规范

### 5.1 加一条新策略

#### 5.1.1 什么时候用这条

- 观察到某个局面 agent 应该做 X 但代码里没有对应逻辑
- 想尝试一种全新的博弈套路（如"卡领先者""废卡换地"）
- 冠军对局分析出的新战术

**不适用**：现有策略触发但产出错 → 走 5.2；现有策略触发条件太宽/太窄 → 走 5.2 而不是 5.1

#### 5.1.2 判断放哪层

新策略永远在 **L2 strategies/** 下。判断哪个子目录：

| Phase | 目录 | 触发时机 |
|---|---|---|
| SELECT_PLOTS | `strategies/select_plots/` | 每回合选地 |
| PLAN_BUILD | `strategies/plan_build/` | 每回合建设 |
| PROPOSE_TRADE | `strategies/propose_trade/` | 每次 agent 主动发起交易 |
| EVALUATE_TRADE | `strategies/evaluate_trade/` | 每次收到别人交易要约 |

#### 5.1.3 代码规范

**文件模板** `strategies/propose_trade/buy_adjacent_plot.py`：

```python
"""BuyAdjacentPlot — R1-R3 无 R4 领先者时，主动买邻接工位扩集群。

来源：L4-11, L4-12, L4-14, L4-18, L4-20（inventory 里的编号，方便追溯）
"""
from __future__ import annotations
from ..base import Strategy, MatchResult, Action
from ...features.plot_value import find_best_buy_candidate
from ...features.opponents import is_me_leader
from ...features.pricing import buy_discount, max_buy, snap_price

NAME = "buy_adjacent_plot"
PHASE = "propose_trade"
PRIORITY = 30   # 见 _order.py 中的编号规则


def match(ctx) -> MatchResult:
    if ctx.round == 4 and is_me_leader(ctx.state):
        return MatchResult.MISS
    if not ctx.is_directed:
        return MatchResult.MISS
    cand = find_best_buy_candidate(ctx.state)
    if cand is None:
        return MatchResult.MISS
    if cand.net < 0:
        return MatchResult.MISS
    return MatchResult.HIT


def act(ctx) -> Action:
    cand = find_best_buy_candidate(ctx.state)  # feature 层缓存, 不重算
    price = snap_price(min(
        int(cand.gain * ctx.cfg.buy_discount[ctx.round]),
        ctx.cfg.max_buy[ctx.round],
    ))
    return Action.initiate(
        target=cand.owner,
        offer_cash=price,
        demand_plots=[cand.plot_id],
        speech_hint="buy_plot",  # SpeechGen 会用此 hint 生成 message
    )
```

**必须**：
- `NAME` / `PHASE` / `PRIORITY` 三个模块级常量
- `match(ctx)` 只读 ctx，不改
- `act(ctx)` 只调 features 和 config，不直接算复杂数值
- 所有随机化用 `ctx.rng`
- 所有数值参数从 `ctx.cfg.<name>` 读，禁止硬编码
- 顶部注释写清"来源"（inventory 编号或者对局出处），便于追溯

**禁止**：
- 在策略里 import 其它策略
- 在策略里 `time.time()` / `random.random()` / `os.getenv()`
- 单文件超过 120 行（拆 helper 到同目录）

#### 5.1.4 注册到 Router

打开 `strategies/propose_trade/_order.py`：

```python
from . import (
    r4_leader_skip,
    buy_card_for_full_cluster,
    buy_adjacent_plot,        # ← 新加的
    buy_plot_combo,
    ...
)

# 优先级从小到大，第一个 HIT 就返回
STRATEGIES_IN_ORDER = [
    r4_leader_skip,              # priority 10
    buy_card_for_full_cluster,   # priority 20
    buy_adjacent_plot,           # priority 30  ← 插到这里
    buy_plot_combo,              # priority 40
    ...
]
```

**优先级编号规则**：
- 每个策略的 `PRIORITY` 是它在 `_order.py` 里的相对位置 × 10
- 插入新策略时，`PRIORITY` 也要更新
- 优先级冲突（同 phase 两个策略 PRIORITY 相同）→ CI 会报错

#### 5.1.5 必配的三件套

**必须**同时提交：

1. **策略代码**（本节主内容）
2. **参数**（如果引入了新数字，配到 `config/strategy_stable.yaml`）
3. **测试**：
   - `tests/strategies/test_buy_adjacent_plot.py`：至少 3 个用例（HIT / MISS 边界 / act 输出）
   - `tests/replay/test_buy_adjacent_plot_replay.py`：至少 1 个真实对局回放证明这条策略被走到

#### 5.1.6 自测

```bash
# unit
pytest tests/strategies/test_buy_adjacent_plot.py -v

# 全策略层
pytest tests/strategies/ -v

# 从一场历史 replay 回放，检查这条策略被触发过
python -m werewolftown.tools.replay replays/<game_id> \
    --assert-strategy buy_adjacent_plot
```

#### 5.1.7 PR checklist（本节专属，通用见第 12 章）

- [ ] 单文件 ≤ 120 行
- [ ] `NAME/PHASE/PRIORITY` 三常量齐全
- [ ] `_order.py` 已注册
- [ ] 硬编码数字全部挪到 `strategy_stable.yaml`
- [ ] `tests/strategies/` 新增了针对性单测（HIT/MISS/act）
- [ ] `tests/replay/` 至少一个真实对局回放证明触发过
- [ ] 顶部注释写清"来源"（inventory 编号或对局 game_id）

### 5.2 修改已有策略

#### 5.2.1 什么时候用这条

- 策略被触发了，但产出的 Action 不对（价格错、目标错、方向错）
- 策略触发条件太宽（不该触发时触发）或太窄（该触发时没触发）
- 策略里某段逻辑与 Feature 层重复，可以下沉

#### 5.2.2 判断影响面

**第一步：读该策略的顶部注释**。找到"来源"里的 inventory 编号，看历史上这条策略是为什么加进来的。

**第二步：查 `_order.py`，看这条策略的邻居**（前一个和后一个 priority）。改这条策略可能影响：
- 更高优先级的策略 → **通常不影响**（更高优先级的先 return 了）
- 更低优先级的策略 → **可能影响**（本策略从 MISS 改 HIT 会抢走它们的机会；反之亦然）

**第三步：如果条件收紧**（HIT → MISS 变多），下一个策略要能接住；**如果条件放宽**（MISS → HIT 变多），要确认没抢占后续更合适的策略。

#### 5.2.3 代码规范

**只允许 3 种改动**：

| 改动 | 允许 | 判断 |
|---|---|---|
| A. 收紧/放宽 `match()` 条件 | ✅ | 只改 match，不改 act |
| B. 改 `act()` 产出 | ✅ | 只改 act，不改 match |
| C. 拆分/合并策略 | ✅ | **必须**新加/删文件，不允许原地扩容 |

**禁止**：
- 在原有策略里加"如果 X 走 A、否则走 B" → 拆成两个策略
- 让 match 有副作用（改 state、调 LLM、动 rng）
- 把参数从 config 挪回硬编码

#### 5.2.4 兼容性检查

改一条策略前必须做：

```bash
# 1. 找出所有回放里被这条策略处理过的局面
python -m werewolftown.tools.replay_scan \
    --strategy buy_adjacent_plot \
    --output before.csv

# 2. 改完策略后再跑一次
python -m werewolftown.tools.replay_scan \
    --strategy buy_adjacent_plot \
    --output after.csv

# 3. diff 两份结果
python -m werewolftown.tools.replay_diff before.csv after.csv
```

Diff 里会显示：
- **仍然 HIT 的局面**（占多数是好事，说明改动没颠覆本策略）
- **HIT → MISS**（本次改动让哪些局面不再触发）
- **MISS → HIT**（哪些新增局面被这条策略接管）
- **HIT 后 Action 变化**（价格从 X 变 Y）

diff 结果需要作为 PR 描述的一部分，并解释每类变化是否符合预期。

#### 5.2.5 参数与逻辑的边界（关键）

改策略前先问：**这个改动真的是逻辑变化，还是只是参数变化？**

- "R1 买地折扣从 0.5 改到 0.55" → 是 **5.3 调整数值参数**，不是 5.2
- "R1 除了买邻接地还要考虑跨街区候选" → 是 5.2（改 match/act 逻辑）
- "把 R4 领先者不买地改成也可以买地" → 拆策略，走 5.1（新加一个 `R4LeaderConservativeBuy`）

**如果 60% 以上的改动是数字，先走 5.3**。

#### 5.2.6 自测

```bash
# 该策略单测
pytest tests/strategies/test_<strategy_name>.py -v

# 若改动可能影响相邻策略，跑该 phase 全套
pytest tests/strategies/propose_trade/ -v

# 回放差异分析
python -m werewolftown.tools.replay_diff before.csv after.csv --min-diff 5%
```

#### 5.2.7 PR checklist

- [ ] 顶部注释里补一条"改动记录：`<date> - <理由>`"
- [ ] 若加了新 `match` 分支，`_order.py` 里检查过邻居
- [ ] 若引入新数字，参数已配到 `strategy_stable.yaml`
- [ ] 回放差异分析（before.csv vs after.csv）附在 PR 描述中
- [ ] 单测覆盖新增分支
- [ ] 单文件仍 ≤ 120 行



### 5.3 调整数值参数

#### 5.3.1 什么时候用这条

- 策略逻辑对，但阈值/价格偏高偏低
- 想微调"更保守"或"更激进"
- 冠军对局分析出的具体数字更合理

**不适用**：如果调数字会导致策略"是否触发"发生变化（例如把 accept_threshold 从 5000 改到 -5000）——这算逻辑变化，走 5.2

#### 5.3.2 参数目录结构

所有可调数字都在 `config/` 下：

```yaml
# config/strategy_stable.yaml — 生产环境
version: "20260713"
description: "V18-Fix5 之后的稳定版"

pricing:
  buy_discount:
    R1: 0.50
    R2: 0.45
    R3: 0.35
    R4: 0.35
  max_buy:
    R1: 25000
    R2: 20000
    R3: 15000
    R4: 10000
  price_snap_step: 500

card_value:
  base_price_by_fc:
    2: 30000
    3: 20000
    4: 12000
    5: 8000
  market_val_by_fc:
    2: 15000
    3: 15000
    4: 12000
    5: 10000
  scarcity_lambda:
    pool_le_1: 0.55
    pool_le_2: 0.40
    R4: 0.50
    fc_le_2: 0.35
    default: 0.25

threshold:
  accept:
    R1: [12000, 18000]   # uniform range
    R2: [12000, 18000]
    R3: [8000, 12000]
    R4: 0                # 定值
  reject:
    R1: [-10000, -6000]
    R2: [-10000, -6000]
    R3: [-8000, -4000]
    R4: 0

# ... 见附录 A 数值参数索引
```

**必须**：
- 每个参数都要有语义化名字，不能是 `param1` `x`
- 分组按功能：`pricing/` / `card_value/` / `threshold/` / `build/` / `select/`
- 每个大分组顶部一句话说明用途

#### 5.3.3 修改流程

**先改 canary，不改 stable**：

```bash
# 1. copy stable → canary（如果 canary 落后了）
cp config/strategy_stable.yaml config/strategy_canary.yaml

# 2. 只改 canary 的对应参数
vim config/strategy_canary.yaml

# 3. 加一条 CHANGELOG 到 canary 顶部
```

**参数改动的 CHANGELOG 格式**：

```yaml
changelog:
  - date: "20260714"
    field: "pricing.buy_discount.R1"
    from: 0.50
    to: 0.55
    reason: "对局 358890 中 R1 买地净值 20k 但我们只出 15k 被拒，测试 0.55 提升成交率"
    author: "user"
```

改完 canary，走部署（见第 8 章）灰度 → 观察 → 全量。

#### 5.3.4 判断能不能只改参数

**试探：把新参数值填进现有测试**：

```python
def test_accept_threshold_r1():
    ctx = build_ctx(round=1, cash=50000, offer_net=10000)
    # 用 canary 参数
    with load_config("strategy_canary.yaml"):
        assert evaluate(ctx).action == "ACCEPT"
    # 用 stable 参数
    with load_config("strategy_stable.yaml"):
        assert evaluate(ctx).action == "REJECT"
```

如果这样的对照测试写得出来 → 说明确实只是参数变化，走 5.3；
如果对照测试要求"新代码分支"才能通过 → 说明是逻辑变化，走 5.2

#### 5.3.5 自测

```bash
# 用 canary 参数跑一遍策略层测试
STRATEGY_PROFILE=canary pytest tests/strategies/ -v

# 用 canary 跑历史回放，看总收益趋势
python -m werewolftown.tools.replay_batch \
    --profile canary \
    --games replays/last_20/ \
    --report canary_vs_stable.md
```

`canary_vs_stable.md` 会输出：
- 每局改动前后 agent 总现金差
- 平均差值
- 分位数（P25 / P50 / P75）

只有平均差 > 0 且 P25 也不劣化，才能走灰度部署。

#### 5.3.6 PR checklist

- [ ] 只改了 `config/strategy_canary.yaml`，没动代码
- [ ] `changelog:` 段有条目：字段/from/to/reason/author
- [ ] 20 场历史 replay 的 canary vs stable 报告附在 PR 描述里
- [ ] 平均总现金差 > 0，且 P25 分位数不劣化



### 5.4 修 bug（正确性问题）

#### 5.4.1 什么时候用这条

- 代码抛异常 / 超时
- 数据错（state 里的 cash/plots/built_on 与实际不符）
- 策略应该 HIT 但没 HIT（match 里有笔误、import 错）
- 明显的算术错（净值 -245000 那种量级偏差）

#### 5.4.2 修 bug 的黄金流程

**第一步：先复现，不要先改**

```bash
# 1. 找到出问题的 game_id（HF 日志、用户报告、监控告警都能给）
GAME_ID=358890

# 2. 从 replays/<game_id>/ 拉出事件流和决策日志
python -m werewolftown.tools.replay replays/$GAME_ID --verbose

# 3. 定位到出错的那次 interact 决策
# 输出会打印: [round=2 phase=propose_trade] strategy=buy_adjacent_plot
#             elapsed=45s, action=SKIP, exception=NameError('remaining')
```

**如果 replay 无法复现，先补 replay 采集**：这是基建 bug（去 5.8），不是策略 bug。

**第二步：写失败测试**

```python
# tests/strategies/test_buy_adjacent_plot.py
def test_bug_20260713_undefined_remaining():
    """Bug: 2026-07-13 room-358890 R2 propose_trade 抛 NameError('remaining')."""
    ctx = load_from_replay("replays/358890/", round=2, phase="propose_trade")
    # 期望：至少不能崩，返回 SKIP 或有效 Action
    result = strategy.act(ctx)
    assert result is not None
    assert result.action in {"initiate", "skip"}
```

**这条测试必须先失败，才能证明 bug 存在**。

**第三步：修复**

修复只做**最小改动**——只让上面那条测试通过，不做重构、不做优化。

**第四步：证明修复不引入回归**

```bash
pytest tests/strategies/ tests/features/ tests/unit/ -v
python -m werewolftown.tools.replay_batch replays/last_20/ --profile stable_with_fix
```

replay batch 里所有 game 的最终 agent 现金都应 >= 修前值（允许微调）。

#### 5.4.3 常见 bug 分类与定位

| 症状 | 常见原因 | 定位起点 |
|---|---|---|
| NameError / UnboundLocalError | 函数内 import 或变量未定义 | 该函数模块级 import |
| 数据源不对 | State 层重放丢事件 | `state/reducer.py`, `state/persistence.py` |
| 决策超时 | LLM 兜底 + LLM 超时 | 检查是否走到了 L1；策略 match 是否覆盖到该场景 |
| 视角反转（net 反了号） | Offer dataclass 用错方向 | 该策略的 `act()` 里的 Offer 构造 |
| 循环 import / lazy import 藏 bug | 函数体内 import | 移到模块级；跑 mypy/ruff 应能扫出 |
| int/str key 不一致 | State 里 built_on 序列化问题 | `state/game_state.py` 的类型注解 |

#### 5.4.4 修 bug 的红线

- **禁止**通过 `try/except: return SKIP` 掩盖 bug（旧代码的巨坑，见 inventory 第 2.2 节 P1-5）
- **禁止**通过"再加一个 if"打补丁到多层——如果某个 bug 需要跨层修，先谈重构（见 5.8）
- **必须**在 PR 描述里写清"这个 bug 是被隐藏了多久（前一次涉及此代码的改动日期到发现日期）"，帮助我们判断监控是否有盲区

#### 5.4.5 PR checklist

- [ ] `tests/` 有一条以 game_id 命名的回归测试（`test_bug_YYYYMMDD_<short_desc>`）
- [ ] 该测试在修前失败、修后通过
- [ ] 修改范围最小化（不夹带重构）
- [ ] 全量测试通过 + last 20 replay batch 无回归
- [ ] PR 描述里包含："bug 首次可能出现时间 / 被发现时间 / 潜伏原因"



### 5.5 加一个 Feature（衍生指标）

#### 5.5.1 什么时候用这条

- 你正要写的一个策略需要一个之前没算过的指标
- 有两个以上策略都要用到同一个数字，且这个数字目前散落在各处（临时算或复制粘贴）
- L2 策略层里出现"import 另一个策略的 helper"（禁止 → 抽 L3）

**不适用**：如果这个指标已经在 features/ 里存在，不要重写；如果只在一处用到，也可以先留在 helper 里，等第二次用到再抽

#### 5.5.2 判断放哪个模块

现有六个功能包：

| 模块 | 职责 | 示例 |
|---|---|---|
| `features/clusters.py` | 集群相关 | `calc_cluster_gain`, `find_typed_clusters`, `achievable_size` |
| `features/card_value.py` | 卡估值 | `card_value(state, card, purpose)`, `card_market_val` |
| `features/plot_value.py` | 工位估值 | `plot_value(state, plot, viewer)`, `find_best_buy_candidate` |
| `features/opponents.py` | 对手分析 | `opp_needs`, `is_leader`, `detect_afk`, `detect_strong` |
| `features/pool.py` | 牌池 | `pool_remaining`, `scarcity_lambda` |
| `features/pricing.py` | 定价工具 | `snap_price`, `dead_zone_adjust`, `buy_discount`, `max_buy` |

**判断口诀**：新 feature 的输入主体是什么？
- 输入是 (state, plot) → `plot_value.py`
- 输入是 (state, card) → `card_value.py`
- 输入是 (state, opponent_pid) → `opponents.py`
- 输入是 (state,) 且返回集群统计 → `clusters.py`
- 输入是 (state,) 且返回稀缺度 → `pool.py`
- 是数值变换工具 → `pricing.py`

不满足以上，可新开模块，但必须在本手册第 2.2 节目录树里追加。

#### 5.5.3 代码规范

```python
# features/plot_value.py

from dataclasses import dataclass
from typing import Literal
from ..state.game_state import GameState
from ..constants.shop_rules import FULL_COUNTS

Viewer = Literal["me", "opponent"]


@dataclass(frozen=True)
class BuyCandidate:
    """一个可买入的工位候选，附带估值细节。"""
    plot_id: int
    owner: str
    gain: int          # 净收益(未减价)
    best_shop: str     # 若买入应该建哪种业务
    is_adjacent: bool  # 是否邻接我方工位
    net: int           # gain - suggested_price


def plot_value(state: GameState, plot_id: int, viewer: Viewer = "me") -> int:
    """从 viewer 视角计算一个工位的估值。

    - viewer="me": 我方买入该地能获得的最大边际增益
    - viewer="opponent": 对手买入该地能获得的最大边际增益 (卖地时用)
    """
    ...
```

**必须**：
- 每个函数第一行 docstring 说清"输入 / 输出 / 语义"
- 返回值是 dataclass（`frozen=True`）或原始类型，不返回 dict
- 输入 state 不能被修改（拿 frozen dataclass 就免这条）
- 加类型注解，`mypy --strict` 能过
- 遵循命名规范：`calc_*` 计算类，`find_*` 查找类，`is_*/has_*` 布尔，`<name>_value` 估值

**禁止**：
- 有 `if round == 4: skip_this()` 之类的决策逻辑（决策去 L2）
- 依赖 `random`
- 修改全局变量
- 单函数 > 50 行

#### 5.5.4 缓存

大量 feature 会被同一个决策周期里多次调用，避免重算：

```python
from ..features._cache import feature_cache

@feature_cache
def find_best_buy_candidate(state: GameState) -> BuyCandidate | None:
    """在 (state, {}) 上缓存: 同一 state 实例内不重算。"""
    ...
```

`feature_cache` 用 `id(state)` 做 key，state 一变缓存失效（state 不可变，一旦有事件到达就产生新 state 实例）。

#### 5.5.5 自测

```bash
pytest tests/features/test_plot_value.py -v
```

**测试规范**：
- 每个 feature 至少 3 个 case（正常 / 边界 / 空输入）
- 用 `tests/features/fixtures.py` 里的 `make_state(...)` 便捷构造 state
- 断言必须给具体数字（不是 `> 0` 这种模糊断言），因为策略层依赖具体值

```python
def test_plot_value_adjacent_full_cluster():
    state = make_state(
        my_plots=[4, 5], built_on={4: "Happy", 5: "Happy"}, shops=["Happy"],
    )
    # plot=6 邻接 4,5 (Happy 2 连) + 手牌 Happy → 满额 3 连
    v = plot_value(state, 6, viewer="me")
    assert v == 70000 - 30000  # 3 连满额 70k - 之前 2 连 30k
```

#### 5.5.6 PR checklist

- [ ] Feature 放在合适的模块（按 5.5.2 判断）
- [ ] 输入 state，输出 dataclass/原始类型，无副作用
- [ ] docstring 说清输入输出语义
- [ ] 类型注解完整
- [ ] `tests/features/test_<module>.py` 覆盖 ≥ 3 个 case
- [ ] 若加了 `@feature_cache`，验证过 state 变更后缓存失效



### 5.6 加一个新的 Event 类型

#### 5.6.1 什么时候用这条

- 游戏引擎新增了 perceive 消息类型（如新的 phase 事件）
- 某种局面 State 层需要新的字段来追踪（如新增 opp_needs 缓存）
- 后端字段格式变化（比如 `offer_shops` 从字符串改成数组）

**不适用**：如果只是把已有事件更完整地记录到 state，这是 5.8 的活；如果只是让某策略响应已有事件，这是 5.1/5.2

#### 5.6.2 五步走

**Step 1: 在 `state/events.py` 定义事件类型**

```python
from dataclasses import dataclass
from typing import Literal

@dataclass(frozen=True)
class DealCountered:
    """引擎推送的还价事件。"""
    kind: Literal["deal_countered"] = "deal_countered"
    game_id: str
    round: int
    deal_id: str
    source: str           # 还价方
    target: str           # 被还价方
    offer_cash: int
    offer_plots: tuple[int, ...]
    offer_shops: tuple[str, ...]
    demand_cash: int
    demand_plots: tuple[int, ...]
    demand_shops: tuple[str, ...]
    ts: float             # 事件到达时间戳
```

**Step 2: 在 `state/reducer.py` 加 case**

```python
def reduce(state: GameState, event: Event) -> GameState:
    match event:
        case DealProposed(...): return _reduce_deal_proposed(state, event)
        case DealCountered(...): return _reduce_deal_countered(state, event)  # ← 新加
        ...
```

**Step 3: 在 `transport/endpoints.py` 加解析**

```python
def _req_to_event(req: AgentReq) -> Event:
    match req.status.value:
        case "deal_proposed":  return _parse_deal_proposed(req)
        case "deal_countered": return _parse_deal_countered(req)  # ← 新加
        ...
```

**Step 4: 加 replay 兼容**

Replay 落盘的 JSON 里加新事件类型，`load_events` 要能反序列化：

```python
# state/persistence.py
_EVENT_TYPES = {
    "deal_proposed": DealProposed,
    "deal_countered": DealCountered,  # ← 新加
    ...
}
```

**Step 5: 更新受影响的 features**

如果新事件带来的 state 变化会影响某些 feature 的计算，那些 feature 的缓存要考虑到（通常 state 变化自动使缓存失效，但要显式测试）。

#### 5.6.3 事件的兼容性红线

- **旧 replay 必须能加载**：新加事件类型不能让旧的 events.jsonl 里的记录反序列化失败
- **事件字段只加不删**：如果要重命名字段，通过 property 别名兼容
- **event schema 版本化**：`state/events.py` 顶部维护 `SCHEMA_VERSION`，改动时递增
- **replay 里的事件带 schema_version**：`load_events` 遇到高版本要提示升级

#### 5.6.4 自测

```bash
# 1. 单测 reducer
pytest tests/state/test_reducer_deal_countered.py -v

# 2. 用带新事件的模拟 replay 验证 rebuild_state 无回归
pytest tests/state/test_persistence.py -v

# 3. 用旧的 replay 验证兼容性
pytest tests/state/test_replay_backward_compat.py -v
```

#### 5.6.5 PR checklist

- [ ] `state/events.py` 定义了新事件类
- [ ] `state/reducer.py` 加了对应 case，纯函数
- [ ] `transport/endpoints.py` 加了 req → event 解析
- [ ] `state/persistence.py` 的 `_EVENT_TYPES` 注册了新类型
- [ ] `tests/state/` 有新事件的 reducer 测试 + replay 序列化/反序列化测试
- [ ] 旧 replay 数据仍能正常加载（backward-compat 测试）
- [ ] 若字段命名有变，写了别名保持兼容



### 5.7 修改 LLM 参与方式

#### 5.7.1 什么时候用这条

- 想让某个策略的某个参数由 LLM 填（"模式 3：LLM 填参数"）
- 想让 LLM 在多个候选策略间仲裁（"模式 2：LLM 仲裁"）
- 想把某个已经稳定的 LLM 调用点固化为纯代码（"从模式 2/3 降到模式 1"）
- 想改话术生成规则

#### 5.7.2 四种 LLM 参与模式（关键概念）

| 模式 | 描述 | 用途 | 代码入口 |
|---|---|---|---|
| M1 纯代码 | LLM 完全不参与决策 | 成熟策略 | 策略 `act()` 直接返回 Action |
| M2 LLM 仲裁 | 多个策略 HIT/UNSURE，LLM 从候选里挑一个 | 策略打架时 | `ctx.request_llm_arbitration(candidates)` |
| M3 LLM 填参 | 策略返回 partial Action，LLM 填空 | 参数不好定 | `Action.partial(price=None, ...)` + `SpeechGen.fill()` |
| M4 LLM 全接管 | 所有策略 MISS，LLM 自由决策 | 未知场景兜底 | `LLMFullDecide.decide(ctx)` |

**演化方向：M4 → M3 → M2 → M1**，越往右越确定，越可控。

#### 5.7.3 何时升/降模式

**从 M4 降到 M3**（LLM 全接管 → LLM 只填参数）：

- 观察到某场景 LLM 决策大方向稳定，但价格上下 30%
- 加一条策略：`match` 就是 M4 的触发条件，`act` 返回 `Action.partial(price=None)`
- LLM 只填 price，逻辑固化在策略里

**从 M3 降到 M2**（LLM 填参 → LLM 只仲裁）：

- 观察到某参数在两三个离散值之间跳（比如 "10k 或 15k"）
- 拆成 2-3 个子策略（分别对应不同参数值），全部 UNSURE
- LLM 从这几个里挑一个

**从 M2 降到 M1**（LLM 仲裁 → 纯代码）：

- 观察到 LLM 仲裁结果稳定倾向某一策略
- 把仲裁改为硬性优先级
- 或者把两个候选策略合并为一个，删掉冲突

**M1 → M2/M3 升级**（新场景无法完全代码化时）：

- 加一个策略，match 返回 UNSURE 而不是 HIT
- 让 LLM 仲裁参与

#### 5.7.4 加/改 LLM 调用点的规范

**只有 3 个合法调用点**（全部在 L1）：

1. `LLMArbitrator.pick(ctx, candidates)` — 从多候选选一个策略名
2. `SpeechGen.render(action, hint)` — 生成 message
3. `VisionParser.parse(snapshot)` — 解析图片

**新增第 4 个调用点必须先改本手册第 3.5 节**。

**调用点必须满足**：

```python
# llm/arbitrator.py
class LLMArbitrator:
    def pick(self, ctx: DecisionContext, candidates: list[Strategy]) -> Strategy:
        # 1. 输出必须是候选之一
        # 2. 输出用 pydantic 模型强约束
        # 3. 超时/失败必须有代码 fallback
        try:
            resp = self._call_with_timeout(...)
            picked = self._parse(resp, candidates)
            return picked
        except (TimeoutError, ValidationError):
            # fallback: 用 priority 最高的候选
            return sorted(candidates, key=lambda s: s.PRIORITY)[0]
```

**Prompt 必须**：
- 不含对手 message（sanitize 层已经过滤，但 L1 也不主动读）
- 用结构化格式（system 是稳定契约，user 是当前局面）
- 用 pydantic 定义输出 schema：`class ArbitrationResp(BaseModel): picked: str`

#### 5.7.5 话术（SpeechGen）规范

话术是当前 LLM 最重要的用途。规则：

- 每个 Action 携带 `speech_hint`（枚举：`"buy_plot"`, `"sell_card"`, `"counter_up"`, `"counter_down"`, `"reject"`, `"skip"`, ...）
- `SpeechGen.render(action, hint)` 根据 hint 选 prompt 模板生成 message
- 生成失败 fallback 到固定短话术（见 inventory L4-33, L6-09）
- 话术生成不影响 Action 的其它字段——**只填 `message` 字段**

#### 5.7.6 自测

```bash
# LLM 层单测（用 mocked client）
pytest tests/llm/ -v

# 端到端：某场景应该走 M3
pytest tests/replay/test_llm_participation.py::test_M3_price_filled -v
```

**关键测试**：LLM 超时 / 返回 gibberish / 返回不在候选里的值 → 都要能兜底不崩

#### 5.7.7 PR checklist

- [ ] 明确本次改动是模式升级还是降级（M2↔M3 等），写在 PR 描述里
- [ ] 若新增调用点，本手册第 3.5 节同步更新
- [ ] Prompt 通过 pydantic schema 约束输出
- [ ] LLM 失败 fallback 是纯代码
- [ ] 每次 LLM 调用有超时保护（≤ 4s）
- [ ] 单测覆盖：正常返回、超时、格式错误、无效值 四种



### 5.8 修改基建 / 状态层

#### 5.8.1 什么时候用这条

- Reducer 有 bug（应用某个事件后 state 与实际不符）
- Replay 无法完整恢复（服务器重启后状态残缺）
- 并发竞速网关行为异常
- 想改 State 的数据结构（比如把 `plots: list` 改成 `frozenset`）

**警告**：**这层改动风险最大**。任何 L4 的改动都可能牵一发动全身——上面所有 L3 features 都依赖 State 的字段名和语义。**动 L4 前必须先谈**（本手册也算"上级"，需要更新第 3.2 节和第 2.2 节）。

#### 5.8.2 判断改动范围

三个层次，越往下越危险：

| 层次 | 例子 | 危险度 |
|---|---|---|
| A. 只改 reducer 里某个 case 的实现 | 修 `deal_accepted` 的资产转移 bug | 中 |
| B. 加/删 State 字段 | 加一个 `pending: PendingLedger` | 高 |
| C. 改 State 序列化格式 | `built_on` 从 dict 改成 tuple | 极高 |

**A 直接走本节流程；B 要更新第 3.2 节；C 要更新第 2.2 节 + backward-compat 迁移**

#### 5.8.3 A 类改动流程（修 reducer bug）

1. **找到那个 case**（比如 `_reduce_deal_accepted`）
2. **写失败测试**：用 replay 里的一段 `(state_before, event, expected_state_after)`
3. **改 reducer**，只让这个测试通过
4. **跑所有 reducer 单测 + 全 replay 重放**：任何一场 replay 重放出来的 state 与录制时不一致 → 回滚

#### 5.8.4 B 类改动流程（加/删 State 字段）

**加字段是安全的**（默认值兼容旧数据）：

```python
@dataclass(frozen=True)
class GameState:
    # ... 现有字段
    afk_scores: dict[str, int] = field(default_factory=dict)  # 新加
```

Reducer 里在相应事件更新这个字段。旧 replay 加载后该字段是空 dict，不影响策略——策略应该能处理"空字段"作为初始状态。

**删字段绝对禁止**：改为标注 `@deprecated`，保留字段但不再写入。等所有依赖它的 feature/策略都不用了，才能真正删。**删除的 PR 单独提**。

#### 5.8.5 C 类改动流程（改序列化格式）

这是最麻烦的场景。必须走：

1. **加新字段并双写**：新旧格式同时保留（比如 `built_on_dict` 和 `built_on_tuple`）
2. **等一个上线周期**：观察新格式所有 case 都正常
3. **切换 features/策略到新字段**：一个 PR 切一个消费方
4. **观察一个上线周期**：老字段没人读了
5. **删老字段**：单独 PR

**旧 replay 的兼容**：`persistence.py` 的 `load_events` 需要探测 schema_version，用旧解析器读，然后 reducer 无缝升级为新 state。

#### 5.8.6 竞速网关（`transport/race_gate.py`）改动

因为你的补充说明第 5 点：**后端不发显式重发标记**，我们只能靠 `cache_key` 推断。任何这方面改动必须：

- 保留 cache_key 计算逻辑（`message` 字段仍要排除，以防对手在附言里做小改动）
- 竞速用 async future（不再 threading.Event）
- 保留兜底：如果 2 个请求都超时了怎么办（返回上一次 known-good decision 或 SKIP）

**测试用例必须包含**：
- 同一 key 的两个请求并发到达
- 第一个请求超时、第二个请求正常返回
- 两个请求都异常
- 请求 key 相同但 message 字段不同 → 仍然合并（因为 cache_key 排除了 message）

#### 5.8.7 自测

```bash
# 单测 reducer
pytest tests/state/ -v

# 完整回放：所有 replays/ 里的对局都能无损重放
python -m werewolftown.tools.replay_all_check --strict

# 并发压测（如果改了 race_gate）
python -m werewolftown.tools.race_stress --n 100 --key-dup-rate 0.3
```

#### 5.8.8 PR checklist

- [ ] 明确改动是 A/B/C 哪类（PR 描述前置声明）
- [ ] A 类：新增回归测试，全 replay 通过
- [ ] B 类：新字段有默认值，本手册第 3.2 节同步更新
- [ ] C 类：分成"加字段"→"切消费方"→"删旧字段"三个 PR
- [ ] 若涉及 race_gate：并发压测通过
- [ ] 若涉及 persistence：backward-compat 测试通过



---

## 第 6 章 — 通用编码规范

> 跨层、跨变更类型的共同底线。任何 PR 都要过。

### 6.1 Python 版本 & 依赖

- Python **3.11+**（`Dockerfile` 已升级；`list[int]`/`str | None` 等语法可用）
- 全 `from __future__ import annotations`
- 类型注解 100%（`mypy --strict` 能过）；不放任 `# type: ignore` 通过 CI

### 6.2 命名规范

| 类型 | 规则 | 例 |
|---|---|---|
| 模块 | snake_case | `plot_value.py` |
| 类 | PascalCase | `BuyCandidate`, `Strategy` |
| 函数 | snake_case，动词开头 | `calc_cluster_gain`, `find_best_buy_candidate` |
| 常量 | UPPER_SNAKE_CASE | `FULL_COUNTS`, `CARD_POOL` |
| 私有函数 | `_snake_case` | `_reduce_deal_proposed` |
| 类型别名 | PascalCase | `Viewer = Literal["me", "opponent"]` |

**语义前缀**：
- `calc_*` → 计算数值
- `find_*` → 查找候选
- `is_*` / `has_*` → 返回 bool
- `apply_*` → 有副作用（只允许在 L4 L5）
- `render_*` → 生成字符串

### 6.3 import 规范

**必须**：
- 所有 import 放模块顶部，**不允许函数内 import**（历史巨坑，见第 10 章 P10-3）
- 顺序：标准库 → 第三方 → 本项目
- 一行一个 import

**唯一例外**：
- `if TYPE_CHECKING:` 块内的循环 import 破解
- 明确的性能优化（罕见，且必须有注释解释）

**禁止**：
- `from ..foo import *`
- 循环 import（用 `if TYPE_CHECKING:` 破除）

### 6.4 数据类规范

- 用 `@dataclass(frozen=True)` 除非明确要求可变
- 用 `frozenset` / `tuple` 代替 `set` / `list` 作为字段类型（避免共享可变引用）
- 用 `Enum` / `Literal` 代替字符串字面量

### 6.5 副作用管理

**禁止在 L2/L3 出现**：
- `import random` / `random.random()` → 用 `ctx.rng`
- `time.time()` → 用 `ctx.now`
- `os.getenv(...)` → 用 `ctx.cfg.<field>`
- `logger.info(...)` 用于记录决策 → 用 `ctx.decision_log`

原因：这些副作用让代码无法用同一 state 稳定重放。

### 6.6 日志规范

**必须结构化**：

```python
ctx.decision_log.emit(
    strategy_name=NAME,
    stage="match",
    result="HIT",
    features={"gain": cand.gain, "net": cand.net},
)
```

不再用 `logger.warning("[eval] 代码兜底 ACCEPT: net=X")` 这种字符串日志。观察平台需要结构化数据。

### 6.7 错误处理

**只允许两种 except**：

1. **业务边界处**（L5 endpoints）：捕获所有异常，落成结构化 error_log，返回 SKIP
2. **明确的可恢复异常**（LLM 超时、JSON 解析失败）：catch 指定异常类型，fallback 到确定性代码

**禁止**：
- `except Exception: pass` / `except Exception: return None`（历史巨坑）
- 在业务函数里裸 `try/except`（应该让异常冒泡到 L5）

### 6.8 单文件行数上限

| 层 | 单文件建议 | 硬上限 |
|---|---|---|
| L2 策略 | ≤ 80 | 120 |
| L3 features 单模块 | ≤ 200 | 300 |
| L4 reducer | ≤ 300 | 400 |
| L5 endpoints | ≤ 150 | 200 |
| L1 LLM 模块 | ≤ 150 | 200 |

**超硬上限**：CI 报错，PR 打回。

### 6.9 注释规范

- 每个策略 / feature / event 类型的顶部必须有 docstring 说明 "做什么、什么时候用、来源"
- 复杂算法段前加一行注释说明"为什么这样算"
- **禁止**用注释残留旧代码（"# 老版本本来是这样的..."）——直接删

### 6.10 config / 参数使用

- 所有可调数字**必须**通过 `ctx.cfg` 访问
- 禁止 hardcode magic number
- 参数默认值放在 `config/strategy_stable.yaml`，代码里只做 `ctx.cfg.foo` 消费

### 6.11 时区 / 时间戳

- 事件时间戳一律 UTC（`time.time()`）
- 展示时才转本地时区
- 不用 `datetime.now()`（无时区意识）

### 6.12 前置检查工具

**必装**：
- `ruff`（linter + formatter，替代 flake8 + black）
- `mypy`（类型检查，`--strict`）
- `pytest`（测试）
- `pytest-cov`（覆盖率，目标 ≥ 80%）

CI 里跑：
```bash
ruff check .
ruff format --check .
mypy --strict werewolftown/
pytest --cov=werewolftown --cov-fail-under=80
```

---

## 第 7 章 — 自测规范

> 三层测试金字塔：unit（快、多）→ features（中、覆盖数值正确性）→ replay（慢、覆盖真实场景）

### 7.1 测试目录结构

```
tests/
├── conftest.py              # 通用 fixture：make_state, make_ctx, load_config
├── unit/                    # 纯函数单测
│   ├── test_board_grid.py       # 邻接表
│   ├── test_shop_rules.py       # 收益表
│   ├── test_sanitize.py         # 消毒
│   └── test_race_gate.py        # 并发网关
├── features/                # Feature 层
│   ├── test_clusters.py
│   ├── test_card_value.py
│   ├── test_plot_value.py
│   ├── test_opponents.py
│   ├── test_pool.py
│   └── test_pricing.py
├── strategies/              # 策略层
│   ├── test_select_plots/
│   ├── test_plan_build/
│   ├── test_propose_trade/
│   │   ├── test_r4_leader_skip.py
│   │   ├── test_buy_adjacent_plot.py
│   │   └── ...
│   └── test_evaluate_trade/
├── state/                   # State 层
│   ├── test_reducer.py
│   ├── test_persistence.py
│   └── test_replay_backward_compat.py
├── llm/                     # LLM 层（用 mock client）
│   ├── test_arbitrator.py
│   ├── test_speech.py
│   └── test_vision.py
└── replay/                  # 完整对局回放
    ├── fixtures/            # game_id 命名的 replay 数据
    ├── test_replay_smoke.py         # 20 场 replay smoke test
    ├── test_replay_regression.py    # 特定 game_id 的历史 bug 回归
    └── test_strategy_coverage.py    # 每条 KEEP 策略至少一场触发
```

### 7.2 三层测试的目的

| 层 | 目的 | 频率 | 时间目标 |
|---|---|---|---|
| unit | 验证纯函数正确性 | 每次改 L4/L1 | < 1s |
| features | 验证数值计算与游戏规则一致 | 每次改 L3 | < 10s |
| strategies | 验证策略触发条件与产出 | 每次改 L2 | < 30s |
| state | 验证 reducer 与 replay 兼容性 | 每次改 L4 | < 20s |
| llm | 验证 LLM 兜底与超时 | 每次改 L1 | < 15s |
| replay | 验证端到端 + 无回归 | 每次 PR 合入前 | < 5min |

**红线**：所有 pytest 加起来 < 6 分钟；超过就要抽样跑或并行化

### 7.3 关键 fixture

`tests/conftest.py` 提供 4 个核心 fixture：

```python
@pytest.fixture
def make_state():
    """构造 GameState 的便捷函数：make_state(my_plots=[1,2], round=2, ...)."""
    ...

@pytest.fixture
def make_ctx(make_state):
    """构造 DecisionContext：make_ctx(state=..., phase=..., rng_seed=42)."""
    ...

@pytest.fixture
def load_config():
    """context manager：with load_config('canary') as cfg: ctx = make_ctx(cfg=cfg)."""
    ...

@pytest.fixture
def replay_at():
    """从 replay 拉出某局某回合某 phase 的 ctx：replay_at('358890', round=2, phase='propose_trade')."""
    ...
```

**必须用 fixture，禁止在测试里手工构造 state**——保持一致性。

### 7.4 unit 测试规范

```python
def test_calc_cluster_revenue_full():
    """Happy(fc=4) 4 连满额 = 10 万。"""
    assert calc_cluster_revenue(cluster_size=4, full_count=4) == 100_000

def test_calc_cluster_revenue_multi_full():
    """8 个连通 fc=2 卡 = 4 个满额 = 16 万。"""
    assert calc_cluster_revenue(cluster_size=8, full_count=2) == 160_000
```

**规范**：
- 一个测试测一个断言
- 用具体数字，不用 `> 0` 这种模糊断言
- 名字说明测的什么条件（`test_<函数>_<场景>`）

### 7.5 features 测试规范

```python
def test_plot_value_adjacent_full_cluster(make_state):
    """邻接现有 Happy 2 连的 plot，我方买入可扩到满额 3 连。"""
    state = make_state(
        my_plots=[4, 5],
        built_on={4: "Happy", 5: "Happy"},
        shops=["Happy"],
        round=2,
    )
    # plot 6 邻接 4,5，手牌有 Happy
    v = plot_value(state, plot_id=6, viewer="me")
    # 3 连满额 70k - 之前 2 连 30k = 40k，× 剩余 3 轮
    assert v == 40_000 * 3
```

**规范**：
- fixture 构造 state，一行一场景
- 断言写明"预期收益如何算出来的"（注释）
- 覆盖：正常 / 边界 / 空输入 / 极端值

### 7.6 strategies 测试规范

每个策略至少 4 类测试：

```python
class TestBuyAdjacentPlot:

    def test_hit_normal(self, make_ctx):
        """R2 有邻接可买候选 → HIT。"""
        ctx = make_ctx(round=2, my_plots=[4,5], has_adjacent_buy=True)
        assert buy_adjacent_plot.match(ctx) == MatchResult.HIT

    def test_miss_r4_leader(self, make_ctx):
        """R4 我方是领先者 → MISS，让给 R4LeaderSkip。"""
        ctx = make_ctx(round=4, is_me_leader=True)
        assert buy_adjacent_plot.match(ctx) == MatchResult.MISS

    def test_miss_no_candidate(self, make_ctx):
        """没有邻接候选 → MISS。"""
        ctx = make_ctx(round=2, my_plots=[])
        assert buy_adjacent_plot.match(ctx) == MatchResult.MISS

    def test_act_price_snap(self, make_ctx):
        """价格取整到 500。"""
        ctx = make_ctx(round=2, buy_candidate_gain=20_100)
        act = buy_adjacent_plot.act(ctx)
        assert act.offer_cash % 500 == 0
```

### 7.7 replay 测试规范

**Replay smoke**：

```python
@pytest.mark.parametrize("game_id", RECENT_20_GAMES)
def test_replay_no_crash(game_id):
    """任意场 replay 完整跑一遍不能崩。"""
    events = load_events(f"replays/{game_id}/events.jsonl")
    state = GameState.initial(player_id="子涵")
    for event in events:
        state = reduce(state, event)
    # 最后一个 event 是 phase_result，state 里应有 4 个玩家现金记录
    assert len(state.other_players) + 1 == 4
```

**Strategy coverage**：

```python
@pytest.mark.parametrize("strategy_name", KEEP_STRATEGIES_LIST)
def test_strategy_touched_in_history(strategy_name):
    """每条 KEEP 策略在最近 50 场里至少被触发过 1 次。"""
    hits = replay_scan(strategies=[strategy_name], games=recent_50_games())
    assert hits > 0, f"{strategy_name} 从未被触发，可能是死代码"
```

**Regression**：

```python
def test_bug_20260713_undefined_remaining():
    """Bug: 2026-07-13 room-358890 R2 抛 NameError('remaining')."""
    ctx = replay_at("358890", round=2, phase="propose_trade")
    resp = decide(ctx)
    assert resp is not None
    assert resp.action in {"initiate", "skip"}
```

### 7.8 覆盖率要求

- unit + features + state + llm 加权覆盖率 ≥ 80%（`pytest --cov-fail-under=80`）
- 每条 KEEP 策略必须有至少 1 个专属测试
- 每次修 bug 必须有对应回归测试
- 覆盖率降低的 PR 打回

### 7.9 测试环境隔离

- 测试**永远**用 `strategy_dev.yaml`（不影响 stable/canary）
- LLM 用 mock：`tests/llm/mocks.py` 提供 `MockLLMClient`，返回预设 response
- 视觉：所有测试 `DISABLE_VISION=true`
- 每个测试独立 rng：`ctx = make_ctx(rng_seed=42)`

### 7.10 自测流程速查

改动后本地跑：

```bash
# 快速验证（约 30 秒）
pytest tests/unit tests/features tests/strategies -x --ff

# 完整验证（约 5 分钟）
pytest --cov=werewolftown --cov-fail-under=80

# 若改了策略/参数，加跑 replay
pytest tests/replay/ -v
```

PR 前**必须** 通过完整验证。

---

## 第 8 章 — 部署规范

> HF Space 单进程环境 + 后端 60s 超时约束下的最小可行 canary。

### 8.1 部署环境认知

- **平台**：Hugging Face Space (Docker)
- **限制**：
  - 单容器单进程；HF Space 一般给 2G 内存/2 CPU
  - 重启会清空 `/tmp` 和进程内存（**因此 replay 必须持久化**）
  - HF 提供 `/data` 目录（挂载持久磁盘），重启不丢
- **能力**：
  - Space 有 API 秘钥（`API_KEY` / `VISION_API_KEY`）
  - 通过 `Dockerfile` 环境变量控制模型
  - HF Space 每次 push 会自动 rebuild → 存在 build 期间旧版本仍在服务的窗口
- **不能**：
  - 多实例并行（想 A/B 只能进程内路由）
  - 蓝绿部署（HF Space 单实例）

### 8.2 三档配置

```yaml
# config/strategy_stable.yaml   — 生产
# config/strategy_canary.yaml   — 灰度（1 场里概率路由 X%）
# config/strategy_dev.yaml      — 本地实验
```

**运行时选择**：

```python
# transport/endpoints.py
def _pick_profile(game_id: str) -> str:
    canary_ratio = float(os.getenv("CANARY_RATIO", "0.0"))
    if canary_ratio == 0.0:
        return "stable"
    # 用 game_id 哈希决定本局用哪个 profile；同一局全程一致
    h = int(hashlib.md5(game_id.encode()).hexdigest(), 16) / 2**128
    return "canary" if h < canary_ratio else "stable"
```

**关键性质**：**canary 路由按 game_id 粒度**，一局内绝不换 profile（否则 State 层参数中途改变，行为诡异）。

### 8.3 部署流程

**步骤**：

1. **代码合入主分支** → git push → HF Space 自动 rebuild
2. **rebuild 期间**（约 3-5 分钟）：老版本仍在服务
3. **rebuild 完成后**：新代码上线，`CANARY_RATIO` 默认 `0.0`（所有对局走 stable）
4. **打开灰度**：在 HF Space Settings 里改环境变量 `CANARY_RATIO=0.1`（10% 对局走 canary）
5. **观察 24 小时**：看 canary_vs_stable 报告
6. **决策**：
   - 若 canary 有正收益 → 提升 `CANARY_RATIO` 到 0.5、1.0
   - 若 canary 有负收益 → 关闭 `CANARY_RATIO=0.0`，回滚代码

### 8.4 灰度策略

**参数改动**（走 5.3）：
- 只改 `strategy_canary.yaml`，不动代码
- `CANARY_RATIO=0.1` 起步
- 观察 20+ 场对局
- 平均总现金差 > 0 且 P25 不劣化 → 参数从 canary 提升到 stable（改 stable.yaml）

**代码改动**（走 5.1/5.2/5.4/5.5/5.6/5.7/5.8）：
- 用 `PROFILE_STRATEGIES` 环境变量分流：
  ```python
  # transport/endpoints.py
  def _register_strategies(profile: str):
      if profile == "canary":
          return canary_strategies  # 含新策略
      return stable_strategies      # 老策略
  ```
- 参数与代码分流独立控制
- 观察窗口至少 20 场

### 8.5 回滚

**参数回滚**（分钟级）：
- 直接把 canary.yaml 里的字段还原
- 或 `CANARY_RATIO=0.0`

**代码回滚**（半小时级）：
- Git revert 到上一个 stable commit
- Push → HF rebuild
- rebuild 期间 canary 仍在跑（**这是隐患**，必要时同时 `CANARY_RATIO=0.0`）

**紧急回滚**（若 canary 引发系统性错误）：
- 立即 `CANARY_RATIO=0.0`
- 观察 stable 是否恢复正常
- 排查 canary 问题
- 修好后重新灰度

### 8.6 部署前 checklist

- [ ] 所有测试通过（含 replay batch）
- [ ] canary_vs_stable 报告：平均总现金差 > 0 且 P25 不劣化
- [ ] 已在本地 `STRATEGY_PROFILE=canary` 跑过 10+ 场 replay
- [ ] PR 描述里有"预期胜率变化"和"关键观察指标"
- [ ] 老 replay 兼容性测试通过（如果动过 L4）
- [ ] Git tag 加一版号（如 `v2026.07.14.canary1`），便于回滚

### 8.7 部署后 checklist

- [ ] HF Space rebuild 成功（看构建日志）
- [ ] 前 5 局对局无 crash（看第 9 章观察规范）
- [ ] canary_vs_stable 数据在观测面板可看
- [ ] 若 24h 内出现严重问题 → 走"紧急回滚"

### 8.8 特殊场景

**Push 完发现有 bug 想快速回滚**：
- 立即 `CANARY_RATIO=0.0`
- 若 stable 也受影响（比如状态层 bug）：立即 git revert push

**HF Space 冷启动**：
- 第一场对局会因 pip install 或 Docker 拉取慢
- 冷启动期出错的对局记录清晰，不算 canary 事故

**Space 反复重启**：
- 检查 `/data/replays/` 有没有累计过多（每局约 200KB）
- 定期清理 `/data/replays/` 中 30 天前的对局


---

## 第 9 章 — 观察规范

> 你之前的 pain point：改了策略但不知道有没有生效。这一章的目标是**任何改动上线后 24 小时内可以拿到量化答案**。

### 9.1 观察的三个层次

| 层 | 目的 | 输出 |
|---|---|---|
| L9.1 事件流原始记录 | 复现 / 回放 | `replays/<game_id>/events.jsonl` + `decisions.jsonl` |
| L9.2 结构化指标 | 快速判断"有没有生效"、"有没有坏" | `metrics/<date>/*.jsonl` |
| L9.3 对局报告 | 一局结束的自动复盘 | `reports/<game_id>.md` |

### 9.2 事件流持久化（L9.1）

**目录结构**：

```
/data/
└── replays/
    └── <game_id>/
        ├── meta.json              # 局 meta：player_id, players, start_ts, end_ts, profile
        ├── events.jsonl           # perceive 事件流（一行一 event）
        ├── decisions.jsonl        # interact 决策日志（一行一决策）
        └── llm_calls.jsonl        # LLM 调用记录（可选，脱敏后）
```

**写入时机**：
- `events.jsonl`：每次 perceive 事件到达，L4 reducer apply 前 append
- `decisions.jsonl`：每次 interact 返回前 append
- `meta.json`：`phase_start` 时创建，`phase_result` 时补 end_ts

**格式**：

```json
// events.jsonl 一行
{"kind":"deal_countered","ts":1720839200.12,"round":2,"deal_id":"deal_x1","source":"心怡",...}

// decisions.jsonl 一行
{"ts":1720839200.5,"round":2,"phase":"propose_trade","game_id":"358890",
 "profile":"canary","strategy":"buy_adjacent_plot",
 "match_result":"HIT","action":{"kind":"initiate","target":"心怡","offer_cash":15000,"demand_plots":[6]},
 "features":{"gain":40000,"net":25000,"is_leader":false},
 "elapsed_ms":250,"llm_used":false}
```

**必须**：
- `strategy` 字段是选中策略的 `NAME`
- `features` 是决策依据的关键数字（够重构复现）
- `profile` 记录了本局走 stable 还是 canary
- `llm_used` 记录了本次决策是否用到 LLM

### 9.3 结构化指标（L9.2）

每小时 cron 从 `replays/` 里聚合出：

```
/data/metrics/
└── 20260714/
    ├── strategy_hits.jsonl     # 每策略每小时命中次数
    ├── strategy_action.jsonl   # 每策略每小时产出的 Action 汇总（价格分布）
    ├── llm_calls.jsonl         # LLM 调用次数 / 成功率 / 延迟
    ├── errors.jsonl            # 错误 / 超时统计
    └── canary_vs_stable.jsonl  # canary/stable 分组的收益对比
```

`canary_vs_stable.jsonl` 是最重要的一份：

```json
{"hour":"2026-07-14T10","profile":"stable","games":5,"avg_cash":425000,"p25":380000,"p50":420000,"p75":465000}
{"hour":"2026-07-14T10","profile":"canary","games":3,"avg_cash":448000,"p25":410000,"p50":445000,"p75":490000}
```

### 9.4 对局报告（L9.3）

每局 `phase_result` 后自动生成 markdown 报告：

```markdown
# Game 358890 报告

- 玩家: 子涵 (第 2 名, $445k)
- Profile: canary
- 时长: 12min
- 最大集群: Happy 3 连（工位 4-5-6）

## 每回合决策
| R | Phase | 策略 | 结果 | 关键指标 |
|---|---|---|---|---|
| 1 | select_plots | enumerate_combos | 选 [4,5,7] | score=95000 |
| 1 | propose_trade | buy_adjacent_plot | 出 15k 买浩宇 6 号 | net=25000 |
| 1 | evaluate_trade | accept_on_net | ACCEPT 心怡卖 5 号 | net=8000 |
| ... |

## 异常
- R2 propose_trade: LLM 兜底触发 (2.3s)
- R3 evaluate_trade: 卡估值 net=-245000 (可能 bug)
```

**报告用来做什么**：
- 复盘本局所有决策
- 一眼看出策略是否被触发
- 异常段自动醒目
- 可以对着 PR 描述里的"预期决策"逐条验证

### 9.5 观察面板（/debug/*）

Web 面板（HF Space 上通过 `https://<space>/debug/` 访问）提供：

```
/debug/games                  # 最近 50 局列表
/debug/games/<game_id>        # 单局报告（自动生成的 markdown）
/debug/strategies             # 每策略近 7 日命中数柱状图
/debug/canary_report          # 最近 24h canary vs stable 汇总
/debug/errors                 # 最近 100 条错误 + 超时
/debug/prompts                # 最近 100 次 LLM 调用（现有的，增强分组）
```

### 9.6 一次改动的观察路径

**你改了什么** → **打开哪个视图 → 期望看到什么**：

| 改动类型 | 看这个视图 | 期望信号 |
|---|---|---|
| 5.1 加新策略 | `/debug/strategies` | 新策略 24h 内命中次数 > 0 |
| 5.2 改策略 | `/debug/strategies/<name>` | 命中次数变化 + Action 分布变化，符合 PR 预期 |
| 5.3 调参数 | `/debug/canary_report` | canary 平均现金 > stable |
| 5.4 修 bug | `/debug/errors` | 相关错误从计数消失 |
| 5.5 加 Feature | `/debug/games/<game_id>` | 相关策略的 `features` 字段里出现新指标 |
| 5.6 加 Event | `/debug/games/<game_id>` | events.jsonl 里出现新事件类型 |
| 5.7 改 LLM 参与 | `/debug/prompts` + `llm_calls.jsonl` | 调用次数 / 成功率符合预期 |
| 5.8 改基建 | `/debug/errors` + replay all check | 无新增 error；全 replay 无损重放 |

### 9.7 SLO（服务质量目标）

**这些红线，一旦触碰立即回滚**：

| 指标 | 阈值 | 数据源 |
|---|---|---|
| 决策异常率 | ≤ 1% | `errors.jsonl` |
| 决策超时率（>50s） | ≤ 0.5% | `decisions.jsonl` |
| LLM 兜底率 | ≤ 5% | `decisions.jsonl` 里 `llm_used=true` |
| 单局决策失败次数 | ≤ 5（后端会下线） | `decisions.jsonl` |
| 死代码策略（0 hit / 24h） | 0 | `strategy_hits.jsonl` |
| 上线 canary 后胜率下降 | ≤ 5% | `canary_vs_stable.jsonl` |

### 9.8 长时间趋势观察

**周报**：`reports/weekly/YYYY-Www.md`

```markdown
# 2026-W28 周报

- 总局数: 87
- 胜率: 34% (stable) / 41% (canary)
- ELO 变化: +23
- 触发最多的策略: buy_adjacent_plot (156 次)
- 从未触发的策略: sell_cheap_non_adjacent (0 次) → 需要考虑删除
- LLM 兜底次数: 12 / 87*7 = 2% 决策
- 新增 bug: 2 (已修)
- 最大遗憾: R2 358950 - 应该买卡但走了 SKIP
```

**从周报判断**：
- 死代码策略（0 触发）应该删或改条件
- 高 LLM 兜底率的场景应该抽取为策略
- 胜率没提升的策略应该重新审视

### 9.9 观察工具的实现

**不需要重写监控平台**——用最简单的方式：

- `metrics/*.jsonl` 用 cron/scheduled_tasks 每小时聚合
- `reports/*.md` 由 `phase_result` 事件触发生成
- `/debug/*` 用 FastAPI + Jinja 模板生成静态 HTML
- 数据不入数据库，都是 jsonl 文件

**保留手段**：老的 `hf_monitor_log.txt` cron 依然跑，但用途从"tail HF log"变成"tail decision_log 并跑异常检测"



---

## 第 10 章 — 常见坑与冲突协议

> 这一章是"历史事故档案"，每一条都能追溯到 STRATEGY_V*.md 里一次具体翻车。**每次改动前**扫一眼，避免踩同样的坑。

### P10-1 状态多源头（agent 拿不到最新数据的根源）

**症状**：agent 决策时依据的 cash/plots/built_on 与实际不符
**历史事故**：V16-Fix7、V18-Fix4#1、Fix4#3、V17 §D6 全部在打补丁
**根因**：memory 变量、事件流重放、req 覆盖、纠正函数四个地方都能改状态
**规范**：**只 L4 State 层管状态**；L2/L3 只读；perceive 事件是唯一写入源
**判断**：如果你在策略里想写 `agent.memory.set_variable(...)` → 停下来，改本手册

### P10-2 视角混淆（净值反号）

**症状**：`_evaluate_deal_value` 算出 net = -245000（应为 +30000 之类的合理值）
**历史事故**：V18 §2 全部
**根因**：`_evaluate_deal_value` 期望"我方视角"，但 Path A/B/C/F20 传参视角不一致
**规范**：**Offer dataclass 用 `to_me` / `from_me` 命名**，禁止再传 `offer_*/demand_*` 4 元组
**判断**：写策略时如果需要 "swap"，说明抽象有问题

### P10-3 函数内 lazy import 隐藏 bug

**症状**：模块级 import 错了 3 周没人发现（`from ..tools.counter_deal import _validate_offer_against_assets` — 实际在 initiate_trade.py）
**历史事故**：V17 §D1
**根因**：`_try_code_only_eval` 函数体内 import 才会执行，import 错误被 `except Exception: return None` 静默吞
**规范**：**所有 import 放模块顶部**；ruff 应能扫出未使用 import；CI 强制 `mypy --strict`
**判断**：任何函数体内 `from ... import ...` → PR 打回，除非明确 comment 解释

### P10-4 `except Exception` 掩盖 bug

**症状**：某个策略实际从未生效，但日志只有 `WARNING [xxx] 代码兜底异常,降级LLM`
**历史事故**：V17 §D3（Fix4/Fix5/Fix6 定价改动从未执行过）
**规范**：**除 L5 边界 + 明确可恢复异常，禁止 catch Exception**
**判断**：`try/except: return None` 是重大 code smell

### P10-5 状态"降级模式"（黑天鹅制造机）

**症状**：某场对局 agent 从头到尾 SKIP 所有交易，全 REJECT 所有要约
**历史事故**：V14-Fix F6 引入 → V17 §D4 阉割 → 待修改文档要求彻底删
**根因**：一次误判（比如 R1 事件断层）触发 `degraded_mode=True`，整局静默失败
**规范**：**任何"整局静默改行为"的开关都禁止**；数据不全时应该明确暴露，让上层决定
**判断**：不设 kill switch；能算就算，算不了报错

### P10-6 事件去重键太宽

**症状**：某场 `deal_accepted` 事件到达两次但 settle_assets 只跑一次，第一次 crash 时资产未落账
**历史事故**：V14-Fix F7 引入的 `_seen_perceive_events`
**规范**：**用幂等 settle**（每个事件带唯一 id，reducer 里做幂等判断），不用去重集合
**判断**：如果需要"跳过已见事件"，说明 reducer 不幂等

### P10-7 R4 决策清仓打架

**症状**：R4 一次决策同时被两个"清仓策略"处理
**历史事故**：V16-Fix2 F10 + V16 R12 步骤 4 未清理老代码
**规范**：**每个 phase 里同一 return path 只允许一个策略 HIT**；重叠策略必须合并
**判断**：定期扫 `_order.py`，寻找"逻辑重叠但没显式互斥"的策略对

### P10-8 fc>=5 卡的估值坑

**症状**：花 45k 买 3 张 Happy 卡，最后建了 1 张
**历史事故**：V18-Fix2 (`_compute_card_cluster_gain` 里没考虑 fc>=5)
**规范**：**所有卡估值路径统一走 `card_value(state, card, purpose)`**，一处判断 fc>=5
**判断**：如果代码里出现"if fc>=5"，检查 6 处买卡路径是否都判了

### P10-9 built_on int/str key

**症状**：`state["built_on"][6]` KeyError，实际存的是 `"6"`
**历史事故**：JSON 序列化后 str key，运算需要 int key
**规范**：**State 层字段用 `dict[int, str]`**，所有输入立即转 int
**判断**：`get_built_on()` 这种"每次都转"的模式 = state 层没做对

### P10-10 阻塞的 asyncio + threading 混用

**症状**：`interact()` 在 uvicorn worker 里被阻塞
**历史事故**：`_async_interact` 里的 `loop.is_running()` 分支
**规范**：**全 async；用 async future 做竞速**，不用 threading.Event
**判断**：`import threading` 出现在 L5 之外的地方 → 打回

### P10-11 参数散落 200+ 处

**症状**：改一个 `buy_discount` 要 grep 全项目
**历史事故**：全项目通病
**规范**：**所有 magic number 挪到 `config/strategy_*.yaml`**；代码里只有 `ctx.cfg.xxx`
**判断**：`if round == 4: xxx = 12000` 出现在策略里 → 参数化

### P10-12 死代码策略

**症状**：某条策略从未被走到，但仍占用维护成本
**历史事故**：L4-31 F22 倒卖（已被 Fix3#5 移除但代码可能残留）
**规范**：**周报会自动扫出"0 hit / 7 天"的策略，必须删除或明确废弃**
**判断**：`test_strategy_touched_in_history` 会强制这条

### 冲突协议：两个改动同时命中

**场景**：本地 agent 正在写策略 A，PR 未合入；你要修 bug B，B 影响 A 依赖的 feature
**协议**：
1. **B 优先**：bug 修复不等策略
2. A 的 PR 需要 rebase 到 B 之后
3. A 的作者（本地 agent）需要重新跑 canary vs stable，并附新的报告到 PR

**场景**：你要加新 Feature X，本地 agent 已经在另一 PR 加了功能重叠的 Feature Y
**协议**：
1. 先合入其中一个
2. 另一个 rebase 后，把重叠部分改为直接调用已合入的 Feature
3. **禁止 X 和 Y 都保留**——两个 feature 做同一件事必然会漂移



---

## 第 11 章 — 术语与命名约定

### 11.1 领域术语

| 术语 | 定义 | 备注 |
|---|---|---|
| **State** | 一局对局的完整数据快照 | L4 内的 `GameState` |
| **Event** | perceive 收到的一条消息 | 引擎推送 → 落到 events.jsonl |
| **Action** | interact 要返回的一次决策 | L2 策略的输出 |
| **Reducer** | `(state, event) → new_state` 纯函数 | 唯一改状态的地方 |
| **Feature** | 从 state 派生的数值指标 | L3 纯函数 |
| **Strategy** | 决策单元 | L2 一个文件 |
| **DecisionContext** | interact 一次决策的只读上下文 | 含 state + features + rng + cfg |
| **MatchResult** | 策略是否要接管本次决策 | HIT / MISS / UNSURE |
| **Profile** | 一份完整参数配置 | stable / canary / dev |
| **Offer** | 一次交易报价的双方视角 | `to_me` / `from_me` |
| **PendingLedger** | 追踪本回合已卖/挂起/取消 | 合并旧 pending_proposals 等 |
| **Speech Hint** | 话术生成模板名 | `"buy_plot"`, `"sell_card"`, ... |

### 11.2 游戏规则术语（不改，直接沿用引擎）

- `plot` = 工位（1-52）
- `shop` = 业务（"淘小宝"/"猫天天"等 8 种）
- `built_on` = {plot_id: shop_type}，物理事实
- `cluster` = 同类连通集群
- `full_count` (`fc`) = 满额数 (2/3/4/5)
- `round` = 回合 (1-4)
- `quota` = 配额（选地保留数 / 交易次数 / 还价次数）
- `deal_id` = 交易 ID (`deal_xxx` 或 `free_xxx`)
- `phase` = 阶段（SELECT_PLOTS / PROPOSE_TRADE 等）

### 11.3 视角约定

**在代码里**永远：
- `me` / `opponent` 而不是 `self` / `other` / `owner`
- `to_me` / `from_me` 而不是 `offer_*` / `demand_*`
- `viewer=me` 或 `viewer=opponent` 参数化

**在 Prompt 里**（跟引擎对齐）：
- 保留 `offer_*` / `demand_*`，但只在 L1 内使用；L2/L3 一律 to_me/from_me

### 11.4 文件命名约定

| 类型 | 规则 |
|---|---|
| 策略文件 | `snake_case.py`，动词/结果描述 (`buy_adjacent_plot.py`, `reject_bad_swap.py`) |
| Feature 模块 | `snake_case.py`，主体名词 (`plot_value.py`, `opponents.py`) |
| Reducer case | `_reduce_<event_name>()` |
| Test 文件 | `test_<被测模块>.py` |
| Bug 回归测试 | `test_bug_YYYYMMDD_<short_desc>()` |
| Config 文件 | `strategy_<profile_name>.yaml` |
| Replay 目录 | `replays/<game_id>/` |
| Report 文件 | `reports/games/<game_id>.md`, `reports/weekly/YYYY-Www.md` |


---

## 第 12 章 — PR 变更 Checklist（贴在每次 PR 里）

**贴到 PR 描述最上方，逐项打勾。未打勾的项必须解释理由。**

### 12.1 通用（所有 PR 必过）

- [ ] 明确变更类型（对应 5.1–5.8 哪一节）
- [ ] 顶部 docstring 说清"这次改了什么，为什么"
- [ ] `ruff check .` 通过
- [ ] `ruff format --check .` 通过
- [ ] `mypy --strict werewolftown/` 通过
- [ ] `pytest --cov=werewolftown --cov-fail-under=80` 通过
- [ ] 无函数内 `import`（P10-3）
- [ ] 无 `except Exception: pass/return None`（P10-4）
- [ ] 无硬编码 magic number（P10-11）
- [ ] 单文件行数在硬上限之内（第 6.8 节）
- [ ] Git commit 有清晰 message + Signed-off-by

### 12.2 加/改策略专用（5.1、5.2）

- [ ] 策略文件 ≤ 120 行
- [ ] `NAME` / `PHASE` / `PRIORITY` 三常量齐全
- [ ] `_order.py` 已注册 + priority 与邻居不冲突
- [ ] 顶部注释写清"来源"（inventory 编号或 game_id）
- [ ] `tests/strategies/` 有针对性单测（HIT/MISS/act 覆盖）
- [ ] `tests/replay/` 至少 1 场真实对局证明触发
- [ ] （改策略时）`replay_diff` 报告附在 PR 描述
- [ ] （改策略时）"改动记录" 更新到顶部注释

### 12.3 参数调整专用（5.3）

- [ ] 只改 `config/strategy_canary.yaml`（不动 stable，不动代码）
- [ ] `changelog:` 段有条目（字段/from/to/reason/author）
- [ ] 20 场 replay 的 canary vs stable 报告附 PR
- [ ] 平均总现金差 > 0 且 P25 不劣化
- [ ] 有对照单测证明"仅参数变化，非逻辑变化"

### 12.4 修 bug 专用（5.4）

- [ ] `tests/` 有以 game_id 命名的回归测试 `test_bug_YYYYMMDD_...`
- [ ] 测试在修前 fail、修后 pass
- [ ] 修改范围最小（无夹带重构）
- [ ] Last 20 replay batch 无回归
- [ ] PR 描述："bug 潜伏时间 / 发现时间 / 潜伏原因"

### 12.5 加 Feature 专用（5.5）

- [ ] Feature 放在合适的模块（按 5.5.2 判断）
- [ ] 输入 state，输出 dataclass/原始类型，无副作用
- [ ] docstring 说清输入输出语义
- [ ] 类型注解完整
- [ ] `tests/features/test_<module>.py` 覆盖 ≥ 3 case
- [ ] 若用 `@feature_cache`，验证过缓存失效

### 12.6 加 Event 专用（5.6）

- [ ] `state/events.py` 定义新事件类，`frozen=True`
- [ ] `state/reducer.py` 加对应 case
- [ ] `transport/endpoints.py` 加 req → event 解析
- [ ] `state/persistence.py:_EVENT_TYPES` 注册新类型
- [ ] `tests/state/` 有 reducer 测试 + backward-compat 测试
- [ ] 旧 replay 仍能加载

### 12.7 LLM 参与改动专用（5.7）

- [ ] 明确模式升降（M2↔M3 等）
- [ ] Prompt 通过 pydantic schema 约束输出
- [ ] LLM 失败 fallback 是纯代码
- [ ] 超时保护 ≤ 4s
- [ ] 单测：正常返回、超时、格式错误、无效值 四种

### 12.8 基建 / 状态层改动专用（5.8）

- [ ] 明确 A/B/C 类
- [ ] A 类：回归测试 + 全 replay 通过
- [ ] B 类：新字段有默认值 + 本手册 3.2 节更新
- [ ] C 类：分三个 PR（加字段 / 切消费方 / 删旧字段）
- [ ] race_gate 改动：并发压测通过
- [ ] persistence 改动：backward-compat 通过

### 12.9 部署前必查

- [ ] canary_vs_stable 报告：均值 > 0，P25 不劣化
- [ ] 本地 STRATEGY_PROFILE=canary 跑过 10+ 场 replay
- [ ] Git tag 加版号
- [ ] PR 描述："预期胜率变化" + "关键观察指标"

### 12.10 部署后必看（24h 内）

- [ ] `/debug/errors` 无新增错误
- [ ] `/debug/strategies` 新策略命中 > 0
- [ ] `/debug/canary_report` 数据符合预期
- [ ] SLO 未触碰（第 9.7 节）


---

## CHANGELOG

### v1.0.0 — 2026-07-13

- 首版发布
- 建立五层架构（L1–L5）与 8 类变更规范（5.1–5.8）
- 覆盖：编码规范 / 自测 / 部署 / 观察 / 常见坑 / PR checklist
- 配套文档：`20260713_strategy_inventory.md`（136 条策略台账）

### 未来版本规则

- **patch**（1.0.x）：勘误、示例更新、trivia
- **minor**（1.x.0）：新增变更类型、新观察规范、新工具集成
- **major**（x.0.0）：架构变化（如加新层）、契约破坏性变更

### 加条 CHANGELOG 的格式

```markdown
### v1.1.0 — 2026-08-01

- 加入第 5.9 节：多语言 message 支持
- 更新 6.11 节：时区处理示例
- 修正 5.3.2 里参数结构示意的错别字（fc4 → fc_4）
```