# -*- coding: utf-8 -*-
"""玩家 Agent:每个玩家 = 一个独立的 LLM Agent,拥有**严格隔离的私有上下文**。
信息隔离的实现要点:
- 每个 PlayerAgent 只维护自己的 `memory`(一串它「观察到 / 被告知」的事件)。
- 法官(judge.py)决定把哪条信息推给哪个 Agent 的 memory——狼人才会收到「队友
身份」,预言家才会收到「查验结果」,公开发言才会推给所有人。
- Agent 每次思考(发言 / 投票 / 用技能)时,只能看到自己 memory 里的内容,
因此不可能「偷看」到本不该看到的信息。这就是信息权限控制的落点。
离线(--offline / --mock)策略:当没有 OpenAI Key、或想零成本可复现地跑完整一局时,
Agent 用一套**规则驱动**的决策代替 LLM。关键在于:离线策略同样**只读自己的 memory**
(不碰其他 Agent 的私有上下文),因此信息权限控制这一教学要点在离线模式下依然成立、
依然可被审计校验。
"""
import json
import os
import re
from typing import List, Optional
from .roles import Role, ROLE_STRATEGY, faction_of
# 全局唯一的 LLM 客户端。模型默认当前便宜旗舰 gpt-5.6-luna。
# 通用回退:优先 OPENAI_API_KEY 直连 OpenAI;没有则用 OPENROUTER_API_KEY 走 OpenRouter。
_MODEL = os.environ.get("OPENAI_MODEL", "gpt-5.6-luna")
_client = None
def _to_openrouter_model(model: str) -> str:
"""把模型名映射到 OpenRouter 命名空间(用于无 OPENAI_API_KEY 的回退路径)。"""
if "/" in model:
return model # 已是 OpenRouter 命名空间,原样使用
if model.startswith("gpt-"):
return "openai/" + model # gpt-* -> openai/gpt-*
if model.startswith("claude-"):
return "anthropic/claude-opus-4.8"
return "openai/gpt-5.6-luna" # 兜底:当前便宜旗舰
def _safe_create(client, **kwargs):
"""调用 Chat Completions;对推理型模型(如 gpt-5.x)的参数限制做自动降级重试:
- 不支持 max_tokens 时改用 max_completion_tokens;
- 不支持非默认 temperature 时移除该参数(回退到模型默认 1)。
这样同一份代码既能跑传统对话模型(接受 temperature=0.8),也能跑推理模型。"""
for _ in range(3):
try:
return client.chat.completions.create(**kwargs)
except Exception as e:
msg = str(e)
if "max_completion_tokens" in msg and "max_tokens" in kwargs:
kwargs["max_completion_tokens"] = kwargs.pop("max_tokens")
continue
if "temperature" in msg and "temperature" in kwargs:
kwargs.pop("temperature", None)
continue
raise
return client.chat.completions.create(**kwargs)
def get_client():
"""返回全局共享的 LLM 客户端(懒加载,进程内单例)。
仅在线模式(真实调用 LLM)才会用到;离线模式不导入 openai、不构造客户端。
1) 有 OPENAI_API_KEY -> 直连 OpenAI;
2) 否则有 OPENROUTER_API_KEY -> 走 OpenRouter,并把 _MODEL 映射到其命名空间;
3) 都没有则报清晰错误。
"""
global _client, _MODEL
if _client is None:
from openai import OpenAI # 懒导入:离线模式无需安装 openai
if os.environ.get("OPENAI_API_KEY"):
_client = OpenAI() # 自动读取环境变量 OPENAI_API_KEY
elif os.environ.get("OPENROUTER_API_KEY"):
_MODEL = _to_openrouter_model(_MODEL)
_client = OpenAI(
api_key=os.environ["OPENROUTER_API_KEY"],
base_url="https://openrouter.ai/api/v1",
)
else:
raise RuntimeError(
"未设置 OPENAI_API_KEY 或 OPENROUTER_API_KEY,请参考 env.example 配置,"
"或改用离线模式:python demo.py --offline"
)
return _client
class PlayerAgent:
"""一个玩家 Agent,封装其身份、私有上下文与决策(LLM 或离线规则)。"""
def __init__(self, name: str, role: Role, offline: bool = False, rng=None):
self.name = name # 玩家名,如 "P3"
self.role = role # 真实身份(只有本人和法官知道)
self.faction = faction_of(role)
self.alive = True
self.offline = offline # True 时用规则策略代替 LLM(零成本、可复现)
# 离线策略的私有随机源(按玩家名种子化,保证可复现且各玩家独立)
import random as _random
self._rng = rng or _random.Random(hash(name) & 0xFFFF)
# 私有上下文:这个 Agent「看得到」的全部信息。别的 Agent 无法访问。
self.memory: List[str] = []
# ---- 上下文注入:只有法官会调用,用来把信息投递进这个 Agent 的私有上下文 ----
def observe(self, event: str):
"""把一条信息写入本 Agent 的私有上下文。"""
self.memory.append(event)
# ---- system prompt:角色设定 + 策略。狼人的队友身份不写在这里,而是由法官
# 在游戏开始时通过 observe() 投递,以便审计能记录「谁看到了队友身份」。 ----
def _system_prompt(self, players: List[str]) -> str:
return (
f"你正在玩一局狼人杀。你是玩家 {self.name}。\n"
f"你的真实身份是【{self.role.value}】,属于【{self.faction.value}】。\n"
f"本局玩家共 {len(players)} 人:{'、'.join(players)}。\n\n"
f"{ROLE_STRATEGY[self.role]}\n\n"
"重要:只能依据你已知的信息推理,不要臆造你无从得知的身份。发言要像真人,"
"简洁自然,有理有据。"
)
def _context_block(self) -> str:
"""把私有上下文拼成给 LLM 的一段文字。"""
if not self.memory:
return "(暂无信息)"
return "\n".join(f"- {m}" for m in self.memory)
def _chat(self, instruction: str, players: List[str], max_tokens: int,
json_mode: bool = False) -> str:
"""组装 system + user 消息并调用 LLM;user 消息里只拼接本 Agent 自己的
私有上下文(`_context_block`),绝不包含其他玩家的私密信息。"""
messages = [
{"role": "system", "content": self._system_prompt(players)},
{"role": "user", "content":
f"【你目前掌握的信息(仅你可见)】\n{self._context_block()}\n\n"
f"【当前任务】\n{instruction}"},
]
# 给推理型模型(如 gpt-5.6 系列)留足输出预算:其内部推理 token 也计入
# max_tokens,预算过小会导致 content 被截断为空。设一个下限兜底。
kwargs = dict(model=_MODEL, messages=messages, temperature=0.8,
max_tokens=max(max_tokens, 512))
if json_mode:
kwargs["response_format"] = {"type": "json_object"}
resp = _safe_create(get_client(), **kwargs)
# content 可能为 None(如被截断);用空串兜底,交由上层解析做降级处理。
return (resp.choices[0].message.content or "").strip()
# ---------- 三种对外能力:发言 / 决策(选目标)/ 投票 ----------
def speak(self, players: List[str]) -> str:
"""白天公开发言。返回一段发言文本(公开信息)。"""
if self.offline:
return self._offline_speak(candidates=[p for p in players if p != self.name])
instruction = (
"现在轮到你在白天公开发言。请结合你掌握的信息,发表一段简短的发言"
"(2~4 句话,60 字以内)。符合你的身份与策略。直接输出发言内容,不要加引号。"
)
return self._chat(instruction, players, max_tokens=180)
def choose_target(self, prompt: str, candidates: List[str],
players: List[str], allow_none: bool = False) -> Optional[str]:
"""让 Agent 从候选人中选一个目标(夜间刀人 / 查验 / 用毒 / 救人判断等)。
用 JSON 模式返回,鲁棒地解析出目标玩家名。
"""
if self.offline:
return self._offline_choose_target(candidates, allow_none)
opt = ",也可以选择放弃(target 填 \"none\")" if allow_none else ""
instruction = (
f"{prompt}\n候选玩家:{'、'.join(candidates)}{opt}。\n"
"请只返回 JSON:{\"target\": \"玩家名或none\", \"reason\": \"一句话理由\"}"
)
raw = self._chat(instruction, players, max_tokens=120, json_mode=True)
target = self._parse_target(raw, candidates, allow_none)
return target
def vote(self, candidates: List[str], players: List[str]) -> Optional[str]:
"""投票放逐。返回票投给谁(或弃票 none)。"""
if self.offline:
return self._offline_vote(candidates)
instruction = (
"现在是白天投票放逐环节。请根据全场发言与你的推理,投出你认为最可能是"
"狼人的玩家。\n候选玩家:" + "、".join(candidates) + "。\n"
"请只返回 JSON:{\"target\": \"玩家名\", \"reason\": \"一句话理由\"}"
)
raw = self._chat(instruction, players, max_tokens=120, json_mode=True)
return self._parse_target(raw, candidates, allow_none=True)
# ---------- 离线(规则)策略:只读自己的 memory,绝不访问他人上下文 ----------
def _known_teammates(self) -> set:
"""狼人从自己的私有上下文里解析出队友名单(好人解析不到,返回空)。"""
mates = set()
for m in self.memory:
hit = re.search(r"狼人阵营的玩家是:([^((]+)", m)
if hit:
mates |= set(re.findall(r"P\d+", hit.group(1)))
return mates
def _known_wolves(self) -> set:
"""从自己的私有上下文里收集『已知是狼人』的玩家:预言家的查验结果 + 狼人的队友。
好人平民无从得知任何人身份 → 返回空集合,只能随机投票。这正是信息不对称。
"""
known = set(self._known_teammates())
for m in self.memory:
hit = re.search(r"你查验了\s*(P\d+),结果为【狼人】", m)
if hit:
known.add(hit.group(1))
return known
def _offline_vote(self, candidates: List[str]) -> Optional[str]:
"""离线投票:优先投自己『确知的狼人』(预言家验人 / 狼人不投队友),否则随机。"""
if not candidates:
return None
if self.role == Role.WEREWOLF:
# 狼人:投一个非队友的好人,尽量隐藏自己
mates = self._known_teammates()
targets = [c for c in candidates if c not in mates] or candidates
return self._rng.choice(targets)
# 好人:预言家有验人结果就投确认的狼;其余平民只能随机(信息不对称的代价)
wolves = [c for c in candidates if c in self._known_wolves()]
if wolves:
return self._rng.choice(wolves)
return self._rng.choice(candidates)
def _offline_choose_target(self, candidates: List[str],
allow_none: bool) -> Optional[str]:
"""离线夜间选目标:狼人/预言家等必选场景优先选『已知狼人之外』的目标;
女巫解药/毒药等可放弃场景按概率决定。"""
if not candidates:
return None
if allow_none:
# 女巫用药:约一半概率行动(救/毒),使对局有变化又能收敛
if self._rng.random() < 0.5:
return None
return self._rng.choice(candidates)
if self.role == Role.SEER:
# 预言家:优先查验尚未确认身份的玩家(避免重复查验已知狼人)
unknown = [c for c in candidates if c not in self._known_wolves()]
return self._rng.choice(unknown or candidates)
if self.role == Role.WEREWOLF:
mates = self._known_teammates()
targets = [c for c in candidates if c not in mates] or candidates
return self._rng.choice(targets)
return self._rng.choice(candidates)
def _offline_speak(self, candidates: List[str]) -> str:
"""离线发言:按角色生成一句符合身份、且不泄露私密信息的模板发言。"""
wolves = [c for c in candidates if c in self._known_wolves()]
suspect = self._rng.choice(candidates) if candidates else "大家"
if self.role == Role.SEER and wolves:
return f"我是预言家,昨晚查验到 {wolves[0]} 是狼人,请大家把票投给他。"
if self.role == Role.WEREWOLF:
return f"我是好人,从发言看 {suspect} 有点可疑,建议重点关注他。"
if self.role == Role.WITCH:
return f"我暂时观望,觉得 {suspect} 的发言站不住脚,先留意一下。"
if self.role == Role.SEER:
return "我还没有决定性的信息,先听大家发言,谨慎投票。"
return f"我是村民,没有夜间信息,只能靠推理,感觉 {suspect} 稍微可疑。"
# ---------- 解析工具 ----------
@staticmethod
def _parse_target(raw: str, candidates: List[str], allow_none: bool) -> Optional[str]:
target = None
try:
data = json.loads(raw)
target = str(data.get("target", "")).strip()
except Exception:
# 兜底:直接从文本里正则找候选玩家名
target = raw
if allow_none and target.lower() in ("none", "", "弃票", "放弃"):
return None
# 归一化:精确匹配优先,否则模糊匹配(找出现的候选名)
if target in candidates:
return target
for c in candidates:
if c in (target or ""):
return c
# 最后兜底:从原始串里搜 Pn
m = re.search(r"P\d+", target or "")
if m and m.group(0) in candidates:
return m.group(0)
# 实在解析不出:好人默认弃票,狼人/必须选的场景由调用方兜底
return None if allow_none else (candidates[0] if candidates else None)