feat: Implement core functionality for werewolf game agents

- Added output_guard.py for text normalization and validation of choices and enums.
- Introduced ruleset.py to define game constants and rules.
- Created sanitizer.py to sanitize player inputs and remove unwanted patterns.
- Developed state.py to manage game state and player information.
- Implemented telemetry.py for logging interactions and telemetry data.
- Added tools for replaying telemetry logs and computing metrics.
- Established a structured plan for upgrading agent code to improve robustness and maintainability.

.gitignore

@@ -1,2 +1,5 @@
 .idea
-.DS_Store
+.DS_Store
+logs/
+__pycache__/
+*.pyc

mission.md

@@ -0,0 +1,171 @@
+# Mission：狼人杀 Agent 工程化改造（以稳定/可评测/可演进为先）
+
+> 本仓库后续所有改造工作以本 `mission.md` 为“唯一入口”。任何代码变更都必须能映射到下面某个里程碑/任务，并满足对应验收标准，确保部署后可正常跑通。
+
+## 1. 项目背景与硬约束（不可破）
+
+### 1.1 运行与部署方式（必须保持可用）
+- 容器入口：`Dockerfile` 使用 `CMD ["python3", "werewolf/app.py"]`
+- 运行依赖：`requirements.txt`（`werewolf-agent-build-sdk==0.0.10`, `openai`, `fastapi`, `uvicorn[standard]`）
+- 环境变量（部署必须提供）：
+  - `API_KEY`：LLM API Key
+  - `BASE_URL`：OpenAI 兼容接口，例如 `https://api.openai.com/v1` 或 `https://dashscope.aliyuncs.com/compatible-mode/v1`
+  - `MODEL_NAME`：模型名（示例代码默认 `gpt4-4o-mini`，实际以 env 为准）
+
+### 1.2 对外 I/O 协议（比赛接口不可变）
+- 每个角色仍实现：
+  - `perceive(req: AgentReq) -> None`
+  - `interact(req: AgentReq) -> AgentResp`
+- `AgentReq` 字段：`status/name/message/role/round`（见 SDK `agent_build_sdk.model.werewolf_model`）
+- `AgentResp` 关键字段：
+  - `result: str`：裁判读取的核心输出
+  - `skillTargetPlayer: Optional[str]`：技能目标（部分 status 需要）
+- **强制原则**：任何 `interact()` 调用必须返回**合规**输出，永不抛异常导致崩线。
+
+## 2. 改造目标与非目标
+
+### 2.1 目标（按优先级）
+1. **稳定性**：投票/技能/警长等结构化输出永远合规（非法则重试一次，再失败必 fallback）。
+2. **可观测性**：把每次决策的输入、候选、prompt、模型输出、解析结果、重试/回退原因落盘，便于回放评测。
+3. **可演进性**：抽取通用底盘（清洗输入、构建上下文、调用 LLM、解析校验、回退），角色代码只保留策略钩子。
+4. **上下文可控**：history 限长 + summary/facts，避免 prompt 爆长导致成本/效果波动。
+5. **安全性**：对玩家自由文本做注入清洗（不误伤裁判结构消息）。
+
+### 2.2 非目标（本阶段不追求）
+- 不追求“更聪明”的策略/更高胜率（先止血，再优化）。
+- 不引入需要新服务/外部数据库的复杂依赖。
+
+## 3. 现状问题清单（来自代码阅读）
+
+- 各角色重复实现“拼 history + 拼 prompt + 直接返回 LLM 输出”，结构化输出缺少强校验，易被裁判判失败。
+- `STATUS_DISCUSS` 的玩家发言未统一清洗，存在指令注入污染 history 的风险（虽然 prompt 里有警告，但未强制执行）。
+- history 无限增长，缺少限长/摘要策略，效果与成本不可控。
+- 可观测性弱：目前主要是 `logger.info("prompt:"+prompt)`，无法系统性回放对比。
+- SDK 的 `SimpleMemory` 使用类变量 `memories`（全局共享 dict），存在多局/多 agent 共享污染风险；底盘需要显式规避。
+
+## 4. 里程碑计划（从“先稳定”到“可重构”）
+
+> 每个里程碑都必须满足“验收标准”才可进入下一阶段；可以分 PR 逐步推进。
+
+### M1：输出合规止血（最优先，低风险高收益）
+**目标**：所有 `vote/skill/sheriff_*` 等结构化输出，保证永远返回裁判可解析的结果。
+
+**交付内容**
+- 新增 `werewolf/core/ruleset.py`：集中定义规则常量（字数上限、候选分隔符、不开枪/撕掉等关键字）。
+- 新增 `werewolf/core/output_guard.py`：
+  - `normalize(text) -> str`：去空白/去多余换行/抽取第一段等
+  - `validate_choice(result, choices) -> bool`
+  - `validate_text_len(text, max_chars) -> text`
+  - `guarded_choice(llm_text, choices, fallback) -> choice`
+- 在每个角色的 `interact()` 的结构化分支接入：
+  - 一次纠错重试（给出“你必须只输出候选名字/不开枪/撕掉”等硬约束）
+  - 仍失败则 fallback（保证返回 choices 内合法值或规则允许的 noop）
+
+**验收标准**
+- 对所有结构化分支：无论 LLM 输出什么，都能返回合规 `AgentResp`（不返回解释、不返回不存在候选）。
+- Docker 启动 `python3 werewolf/app.py` 不报错（无语法/导入错误）。
+
+### M2：Telemetry 落盘 + 最小回放（可评测）
+**目标**：把“输入→prompt→输出→解析→校验→回退”的全链路记录下来，并能离线回放验证合规率。
+
+**交付内容**
+- 新增 `werewolf/core/telemetry.py`
+  - 写入 `logs/<session_id>/<role>/<round>_<status>.jsonl`
+  - 最小字段（建议）：
+    - `ts, session_id, role, name, round, status`
+    - `choices`（若有）
+    - `prompt`（可选：保存 hash + 截断片段，避免泄露/过大）
+    - `llm_raw, llm_normalized`
+    - `parsed`（结构化 action 或最终 choice）
+    - `valid`、`retry_count`、`fallback_used`、`fallback_reason`
+    - `final_result, final_skillTargetPlayer`
+- 新增 `werewolf/tools/replay.py`
+  - 输入：一局事件序列（或直接复用 telemetry）
+  - 输出：合规率/重试率/fallback 率统计
+  - 运行示例：
+    - `python werewolf/tools/replay.py --log-root logs --session <session_id>`
+    - 或省略 `--session` 自动分析最新一局
+
+**验收标准**
+- 随便跑一局（或手动构造若干 `AgentReq`），能在 `logs/` 下生成可读 jsonl。
+- 回放工具能跑通并输出统计（不要求策略强，只要求“可回放可量化”）。
+
+### M3：抽取通用底盘（BaseRoleAgent）
+**目标**：把“清洗/上下文/调用 LLM/解析校验/回退/日志”从每个角色里拿走，角色只保留策略 hook。
+
+**交付内容**
+- 新增 `werewolf/core/base_role_agent.py`：继承 SDK `BasicRoleAgent`，实现统一流程：
+  1. `perceive()`：事件清洗 → 写 memory/state → 追加 facts/raw_log
+  2. `interact()`：根据 status 构建任务 → 决策（优先程序策略）→ 必要时调用 LLM → parse/validate → retry/fallback → 渲染输出
+- 新增 `werewolf/core/sanitizer.py`：
+  - 仅对“玩家自由文本”（典型：`STATUS_DISCUSS` 且 `req.name` 非空）做注入清洗
+  - 裁判结构消息（`*_RESULT`, `night_info` 等）不清洗
+- 新增 `werewolf/core/memory_store.py`（替代/包裹 SDK `SimpleMemory`）
+  - 必须保证 **memory 实例隔离**（避免 SDK 类变量共享污染）
+  - 提供 `raw_log` 限长与摘要接口（摘要可先占位，后续再做）
+
+**验收标准**
+- 至少迁移 1 个简单角色（建议 `villager`）到 `BaseRoleAgent`，功能与接口不变、可运行。
+- 角色迁移不应改变 `werewolf/app.py` 的注册方式（外部入口不动）。
+
+### M4：结构化 Action + 事件解析（进阶稳定）
+**目标**：内部统一用 Action 表达决策；外部统一由 Renderer 生成裁判需要的字符串。
+
+**交付内容**
+- 新增 `werewolf/core/actions.py`：`DiscussAction / VoteAction / SkillAction / PassAction / Sheriff*Action ...`
+- 新增 `werewolf/core/action_parser.py` 与 `werewolf/core/action_renderer.py`
+- 新增 `werewolf/core/event_parser.py` 与 `werewolf/core/state.py`
+  - 将 `STATUS_VOTE`, `STATUS_VOTE_RESULT`, `STATUS_NIGHT_INFO`, `STATUS_SKILL_RESULT` 等转为结构化 facts
+  - 为后续策略模块（嫌疑评分、共识函数）提供稳定输入
+
+**验收标准**
+- 所有角色都能走 Action→Renderer 的统一路径，减少分支散落字符串拼接。
+
+## 5. 关键实现规范（必须遵守）
+
+### 5.1 “结构化输出”强协议（所有角色通用）
+- `vote/sheriff_vote/...`：`result` 必须是候选中的**一个名字**（不带任何额外字符）。
+- `skill`：
+  - 目标型技能：必须是候选名字之一；若允许 noop，则必须是规则约定关键字（如“不开枪”）。
+  - 女巫：输出格式要与当前裁判期望一致（示例代码当前使用“救X/毒X/不使用”，需以线上规则为准）。
+- `discuss`：允许自然语言，但必须做字数裁剪（规则上限：240 汉字）。
+
+### 5.2 Retry / Fallback 统一策略
+- 解析/校验失败：
+  1. 生成“纠错 prompt”重试一次（明确列出 allowed outputs / candidates）
+  2. 再失败立即 fallback（不再调用 LLM）
+- fallback 原则：
+  - `vote`：从候选中选一个（默认第一个/随机，但必须可配置；建议先确定性：第一个）
+  - `skill`：默认 noop（如“不开枪”），除非规则不允许 noop
+  - `wolf kill`：规则通常要求必须给出目标，否则可能“弃刀”；fallback 应返回一个合法候选以避免弃刀
+
+### 5.3 文件与导入约定（避免部署崩）
+- 新增模块统一放在 `werewolf/core/`、`werewolf/tools/`
+- 在 `werewolf/*.py` 中导入时使用脚本目录路径（例如 `from core.telemetry import ...`），不要引入需要包安装的复杂相对导入。
+
+## 6. 部署与冒烟检查（每次发布前必做）
+
+### 6.1 本地（或 CI）冒烟
+```bash
+pip install -r requirements.txt
+python werewolf/app.py
+```
+
+### 6.2 Docker 冒烟
+```bash
+docker build -t werewolf-agent .
+docker run --rm -e API_KEY=xxx -e BASE_URL=xxx -e MODEL_NAME=xxx werewolf-agent
+```
+
+### 6.3 发布前检查清单
+- [ ] 入口仍为 `werewolf/app.py`，无额外启动命令要求
+- [ ] 未新增必须联网下载的大依赖
+- [ ] 所有 `interact()` 分支不会抛异常、不会返回 `None`
+- [ ] `vote/skill` 输出永远合规（即使 LLM 输出乱码）
+- [ ] `logs/` 写入失败不会影响主流程（最多降级为不写日志）
+
+## 7. 风险与决策记录（变更需更新本节）
+
+- **SDK `SimpleMemory` 全局共享风险**：必须在 `M3` 前后完成隔离（自建 MemoryStore 或确保实例独立）。
+- **SDK `llm_caller` 固定 system prompt**：不建议改 SDK；在我们的 prompt 模板中补足协议约束与纠错提示。
+- **并发/异步问题**：当前 agent 代码非线程安全；若后续引入并发回放或多局同进程，必须先完成 memory 隔离与日志锁策略。

werewolf/core/__init__.py

@@ -0,0 +1,2 @@
+# Core utilities for robust agent behavior (validation, fallback, telemetry, etc.).
+

werewolf/core/action_parser.py

@@ -0,0 +1,51 @@
+from typing import Optional
+
+from agent_build_sdk.model.werewolf_model import (
+    STATUS_DISCUSS,
+    STATUS_SHERIFF,
+    STATUS_SHERIFF_ELECTION,
+    STATUS_SHERIFF_SPEECH,
+    STATUS_SHERIFF_PK,
+    STATUS_SHERIFF_SPEECH_ORDER,
+    STATUS_SHERIFF_VOTE,
+    STATUS_VOTE,
+    STATUS_SKILL,
+    STATUS_WOLF_SPEECH,
+)
+
+from core import ruleset
+from core.actions import (
+    DiscussAction,
+    SheriffRunAction,
+    SheriffSpeechOrderAction,
+    SheriffTransferAction,
+    SheriffVoteAction,
+    SkillAction,
+    VoteAction,
+)
+from core.output_guard import normalize_llm_text
+
+
+def parse_action(status: str, text: Optional[str]):
+    s = normalize_llm_text(text)
+    if status in {STATUS_DISCUSS, STATUS_WOLF_SPEECH, STATUS_SHERIFF_SPEECH, STATUS_SHERIFF_PK}:
+        return DiscussAction(text=s)
+    if status == STATUS_VOTE:
+        return VoteAction(target=s)
+    if status == STATUS_SKILL:
+        if s == ruleset.NO_SHOOT or s == ruleset.WITCH_NO_USE:
+            return SkillAction(target=None)
+        return SkillAction(target=s)
+    if status == STATUS_SHERIFF_VOTE:
+        return SheriffVoteAction(target=s)
+    if status == STATUS_SHERIFF:
+        return SheriffTransferAction(target=s)
+    if status == STATUS_SHERIFF_ELECTION:
+        if s == ruleset.SHERIFF_RUN:
+            return SheriffRunAction(join=True)
+        if s == ruleset.SHERIFF_NOT_RUN:
+            return SheriffRunAction(join=False)
+        return None
+    if status == STATUS_SHERIFF_SPEECH_ORDER:
+        return SheriffSpeechOrderAction(order=s)
+    return None

werewolf/core/action_renderer.py

@@ -0,0 +1,53 @@
+from typing import Optional, Union
+
+from agent_build_sdk.model.werewolf_model import STATUS_SKILL
+from agent_build_sdk.model.roles import ROLE_WITCH
+
+from core import ruleset
+from core.actions import (
+    DiscussAction,
+    PassAction,
+    SheriffRunAction,
+    SheriffSpeechOrderAction,
+    SheriffTransferAction,
+    SheriffVoteAction,
+    SkillAction,
+    VoteAction,
+)
+from core.output_guard import clip_text
+
+
+Action = Union[
+    DiscussAction,
+    VoteAction,
+    SkillAction,
+    PassAction,
+    SheriffRunAction,
+    SheriffVoteAction,
+    SheriffTransferAction,
+    SheriffSpeechOrderAction,
+]
+
+
+def render_action(action: Action, *, status: Optional[str] = None, role: Optional[str] = None) -> str:
+    if isinstance(action, DiscussAction):
+        return clip_text(action.text, ruleset.MAX_DISCUSS_CHARS, fallback=ruleset.DEFAULT_DISCUSS_FALLBACK)
+    if isinstance(action, VoteAction):
+        return action.target
+    if isinstance(action, SkillAction):
+        if action.target is None:
+            if status == STATUS_SKILL and role == ROLE_WITCH:
+                return ruleset.WITCH_NO_USE
+            return ruleset.NO_SHOOT
+        return action.target
+    if isinstance(action, SheriffRunAction):
+        return ruleset.SHERIFF_RUN if action.join else ruleset.SHERIFF_NOT_RUN
+    if isinstance(action, SheriffVoteAction):
+        return action.target
+    if isinstance(action, SheriffTransferAction):
+        return action.target
+    if isinstance(action, SheriffSpeechOrderAction):
+        return action.order
+    if isinstance(action, PassAction):
+        return ""
+    raise ValueError(f"Unsupported action: {type(action)}")

werewolf/core/actions.py

@@ -0,0 +1,43 @@
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class DiscussAction:
+    text: str
+
+
+@dataclass(frozen=True)
+class VoteAction:
+    target: str
+
+
+@dataclass(frozen=True)
+class SkillAction:
+    target: Optional[str]
+
+
+@dataclass(frozen=True)
+class PassAction:
+    pass
+
+
+@dataclass(frozen=True)
+class SheriffRunAction:
+    join: bool
+
+
+@dataclass(frozen=True)
+class SheriffVoteAction:
+    target: str
+
+
+@dataclass(frozen=True)
+class SheriffTransferAction:
+    target: str
+
+
+@dataclass(frozen=True)
+class SheriffSpeechOrderAction:
+    order: str
+

werewolf/core/base_role_agent.py

@@ -0,0 +1,220 @@
+from typing import Callable, Iterable, Optional, Sequence, Tuple
+
+from agent_build_sdk.sdk.role_agent import BasicRoleAgent
+from agent_build_sdk.model.werewolf_model import (
+    STATUS_DISCUSS,
+    STATUS_SHERIFF,
+    STATUS_SHERIFF_ELECTION,
+    STATUS_SHERIFF_PK,
+    STATUS_SHERIFF_SPEECH,
+    STATUS_SHERIFF_SPEECH_ORDER,
+    STATUS_SHERIFF_VOTE,
+    STATUS_SKILL,
+    STATUS_VOTE,
+    STATUS_WOLF_SPEECH,
+)
+
+from core import ruleset, telemetry
+from core.action_parser import parse_action
+from core.action_renderer import render_action
+from core.event_parser import event_to_fact, parse_event
+from core.memory_store import MemoryStore
+from core.output_guard import (
+    clip_text,
+    correction_instruction_for_choices,
+    correction_instruction_for_enum,
+    guard_choice,
+    guard_enum,
+    guarded_meta,
+)
+from core.sanitizer import sanitize_player_text
+
+
+class BaseRoleAgent(BasicRoleAgent):
+    """Shared helpers for guard/telemetry flow and safe memory updates."""
+
+    def __init__(self, role: str, model_name: str, *, memory=None) -> None:
+        super().__init__(role, memory=memory or MemoryStore(), model_name=model_name)
+
+    def append_player_message(self, name: str, message: Optional[str]) -> None:
+        cleaned = sanitize_player_text(message or "")
+        if cleaned:
+            self.memory.append_history(f"{name}: {cleaned}")
+        else:
+            self.memory.append_history(f"{name}: [filtered]")
+
+    def append_discuss_host(self, round_no: Optional[int]) -> None:
+        self.memory.append_history(f"主持人: 现在进入第{round_no}天。")
+        self.memory.append_history("主持人: 每个玩家描述自己的信息。")
+
+    def _get_state(self):
+        try:
+            if self.memory.has_variable("game_state"):
+                return self.memory.load_variable("game_state")
+        except Exception:
+            pass
+        from core.state import GameState
+
+        state = GameState()
+        self.memory.set_variable("game_state", state)
+        return state
+
+    def update_state(self, req) -> None:
+        try:
+            state = self._get_state()
+            if req.round is not None:
+                state.round_no = req.round
+            fact = event_to_fact(req)
+            if fact:
+                state.facts.append(fact)
+                if fact.get("type") == "sheriff" and fact.get("name"):
+                    state.sheriff = fact.get("name")
+            if hasattr(self.memory, "append_raw"):
+                self.memory.append_raw(parse_event(req))
+        except Exception:
+            return
+
+    def _agent_name(self, fallback: str = "") -> str:
+        try:
+            if self.memory.has_variable("name"):
+                return self.memory.load_variable("name")
+        except Exception:
+            return fallback
+        return fallback
+
+    def _render_action_if_possible(self, status: str, result: str) -> str:
+        action_statuses = {
+            STATUS_DISCUSS,
+            STATUS_WOLF_SPEECH,
+            STATUS_SHERIFF_SPEECH,
+            STATUS_SHERIFF_PK,
+            STATUS_VOTE,
+            STATUS_SHERIFF_SPEECH_ORDER,
+            STATUS_SKILL,
+            STATUS_SHERIFF_ELECTION,
+            STATUS_SHERIFF_VOTE,
+            STATUS_SHERIFF,
+        }
+        if status not in action_statuses:
+            return result
+        action = parse_action(status, result)
+        if not action:
+            return result
+        rendered = render_action(action, status=status, role=str(self.role))
+        return rendered if rendered != "" else result
+
+    def decide_speech(self, *, req_status: str, round_no: Optional[int], prompt: str, kind: str) -> str:
+        raw1 = self.llm_caller(prompt)
+        result = clip_text(
+            raw1,
+            ruleset.MAX_DISCUSS_CHARS,
+            fallback=ruleset.DEFAULT_DISCUSS_FALLBACK,
+        )
+        result = self._render_action_if_possible(req_status, result)
+        telemetry.log_interact(
+            memory=self.memory,
+            role=str(self.role),
+            status=req_status,
+            round_no=round_no,
+            agent_name=self._agent_name(),
+            payload=telemetry.decision_payload(
+                prompt=prompt,
+                choices=None,
+                attempt1=(raw1, {"kind": kind, "clipped": len(raw1 or "") > ruleset.MAX_DISCUSS_CHARS}),
+                attempt2=None,
+                final_result=result,
+            ),
+        )
+        return result
+
+    def decide_enum(
+        self,
+        *,
+        req_status: str,
+        round_no: Optional[int],
+        prompt: str,
+        allowed: Sequence[str],
+        fallback: str,
+    ) -> str:
+        raw1 = self.llm_caller(prompt)
+        first = guard_enum(raw1, allowed, fallback=fallback)
+        if not first.valid:
+            retry_prompt = prompt + correction_instruction_for_enum(allowed)
+            raw2 = self.llm_caller(retry_prompt)
+            second = guard_enum(raw2, allowed, fallback=first.value)
+            result = second.value
+        else:
+            raw2 = None
+            second = None
+            result = first.value
+        result = self._render_action_if_possible(req_status, result)
+        telemetry.log_interact(
+            memory=self.memory,
+            role=str(self.role),
+            status=req_status,
+            round_no=round_no,
+            agent_name=self._agent_name(),
+            payload=telemetry.decision_payload(
+                prompt=prompt,
+                choices=list(allowed),
+                attempt1=(raw1, guarded_meta(first)),
+                attempt2=None if raw2 is None else (raw2, guarded_meta(second)),
+                final_result=result,
+            ),
+        )
+        return result
+
+    def decide_choice(
+        self,
+        *,
+        req_status: str,
+        round_no: Optional[int],
+        prompt: str,
+        choices: Sequence[str],
+        allow_extra: Optional[Iterable[str]] = None,
+        fallback: Optional[str] = None,
+        final_skill_target_from_result: Optional[Callable[[str], Optional[str]]] = None,
+    ) -> str:
+        allow_extra_list = list(allow_extra or [])
+        fallback_value = fallback
+        if fallback_value is None:
+            if choices:
+                fallback_value = choices[0]
+            elif allow_extra_list:
+                fallback_value = allow_extra_list[0]
+            else:
+                fallback_value = ""
+
+        raw1 = self.llm_caller(prompt)
+        first = guard_choice(raw1, choices, fallback=fallback_value, allow_extra=allow_extra_list)
+        if not first.valid:
+            retry_prompt = prompt + correction_instruction_for_choices(choices, allow_extra=allow_extra_list)
+            raw2 = self.llm_caller(retry_prompt)
+            second = guard_choice(raw2, choices, fallback=first.value, allow_extra=allow_extra_list)
+            result = second.value
+        else:
+            raw2 = None
+            second = None
+            result = first.value
+
+        final_skill_target = (
+            final_skill_target_from_result(result) if final_skill_target_from_result else None
+        )
+        result = self._render_action_if_possible(req_status, result)
+        log_choices = list(choices) + list(allow_extra_list)
+        telemetry.log_interact(
+            memory=self.memory,
+            role=str(self.role),
+            status=req_status,
+            round_no=round_no,
+            agent_name=self._agent_name(),
+            payload=telemetry.decision_payload(
+                prompt=prompt,
+                choices=log_choices,
+                attempt1=(raw1, guarded_meta(first)),
+                attempt2=None if raw2 is None else (raw2, guarded_meta(second)),
+                final_result=result,
+                final_skillTargetPlayer=final_skill_target,
+            ),
+        )
+        return result

werewolf/core/event_parser.py

@@ -0,0 +1,117 @@
+from typing import Dict, Optional
+
+from agent_build_sdk.model.werewolf_model import (
+    AgentReq,
+    STATUS_DAY,
+    STATUS_HUNTER,
+    STATUS_HUNTER_RESULT,
+    STATUS_NIGHT,
+    STATUS_NIGHT_INFO,
+    STATUS_RESULT,
+    STATUS_SHERIFF_ELECTION,
+    STATUS_SHERIFF_PK,
+    STATUS_SHERIFF_SPEECH,
+    STATUS_SHERIFF_SPEECH_ORDER,
+    STATUS_SHERIFF_VOTE,
+    STATUS_SKILL_RESULT,
+    STATUS_VOTE,
+    STATUS_VOTE_RESULT,
+    STATUS_SHERIFF,
+)
+
+
+def parse_event(req: AgentReq) -> Dict[str, str]:
+    return {
+        "status": req.status or "",
+        "name": req.name or "",
+        "message": req.message or "",
+        "round": str(req.round) if req.round is not None else "",
+        "role": req.role or "",
+    }
+
+
+def event_to_fact(req: AgentReq) -> Optional[Dict[str, str]]:
+    status = req.status or ""
+    if status == STATUS_VOTE:
+        return {
+            "type": "vote",
+            "voter": req.name or "",
+            "target": req.message or "",
+        }
+    if status == STATUS_VOTE_RESULT:
+        return {
+            "type": "vote_result",
+            "out": (req.name or req.message or ""),
+        }
+    if status == STATUS_NIGHT_INFO:
+        return {
+            "type": "night_info",
+            "message": req.message or "",
+        }
+    if status == STATUS_NIGHT:
+        return {
+            "type": "night",
+            "message": req.message or "",
+        }
+    if status == STATUS_DAY:
+        return {
+            "type": "day",
+            "message": req.message or "",
+        }
+    if status == STATUS_SKILL_RESULT:
+        return {
+            "type": "skill_result",
+            "name": req.name or "",
+            "message": req.message or "",
+        }
+    if status == STATUS_HUNTER:
+        return {
+            "type": "hunter",
+            "name": req.name or "",
+            "message": req.message or "",
+        }
+    if status == STATUS_HUNTER_RESULT:
+        return {
+            "type": "hunter_result",
+            "name": req.name or "",
+            "target": req.message or "",
+        }
+    if status == STATUS_RESULT:
+        return {
+            "type": "result",
+            "message": req.message or "",
+        }
+    if status == STATUS_SHERIFF_ELECTION:
+        return {
+            "type": "sheriff_election",
+            "message": req.message or "",
+        }
+    if status == STATUS_SHERIFF_SPEECH:
+        return {
+            "type": "sheriff_speech",
+            "name": req.name or "",
+            "message": req.message or "",
+        }
+    if status == STATUS_SHERIFF_PK:
+        return {
+            "type": "sheriff_pk",
+            "name": req.name or "",
+            "message": req.message or "",
+        }
+    if status == STATUS_SHERIFF_VOTE:
+        return {
+            "type": "sheriff_vote",
+            "name": req.name or "",
+            "target": req.message or "",
+        }
+    if status == STATUS_SHERIFF_SPEECH_ORDER:
+        return {
+            "type": "sheriff_speech_order",
+            "message": req.message or "",
+        }
+    if status == STATUS_SHERIFF and req.name:
+        return {
+            "type": "sheriff",
+            "name": req.name,
+        }
+    return None

werewolf/core/memory_store.py

@@ -0,0 +1,75 @@
+import os
+from typing import Any, Dict, List, Optional
+
+
+_DEFAULT_HISTORY_LIMIT = int(os.getenv("HISTORY_MAX_ITEMS", "200"))
+_DEFAULT_RAW_LOG_LIMIT = int(os.getenv("RAW_LOG_MAX_ITEMS", "1000"))
+
+
+class MemoryStore:
+    """Per-agent memory store to avoid cross-agent pollution."""
+
+    def __init__(
+        self,
+        *,
+        history_limit: Optional[int] = None,
+        raw_log_limit: Optional[int] = None,
+    ) -> None:
+        self._memories: Dict[str, Any] = {}
+        self._history_limit = _DEFAULT_HISTORY_LIMIT if history_limit is None else history_limit
+        self._raw_log_limit = _DEFAULT_RAW_LOG_LIMIT if raw_log_limit is None else raw_log_limit
+
+    def load_variable(self, variable: str) -> Any:
+        return self._memories[variable]
+
+    def set_variable(self, variable: str, value: Any) -> None:
+        self._memories[variable] = value
+
+    def has_variable(self, variable: str) -> bool:
+        return variable in self._memories
+
+    def append_history(self, message: str) -> None:
+        if self.has_variable("history"):
+            history: List[str] = self.load_variable("history")
+        else:
+            history = []
+        if message:
+            history.append(message)
+        if self._history_limit and len(history) > self._history_limit:
+            history = history[-self._history_limit :]
+        self.set_variable("history", history)
+
+    def load_history(self) -> List[str]:
+        if self.has_variable("history"):
+            history: List[str] = self.load_variable("history")
+        else:
+            history = []
+        return history
+
+    def append_raw(self, record: Dict[str, Any]) -> None:
+        if self.has_variable("raw_log"):
+            raw_log: List[Dict[str, Any]] = self.load_variable("raw_log")
+        else:
+            raw_log = []
+        raw_log.append(record)
+        if self._raw_log_limit and len(raw_log) > self._raw_log_limit:
+            raw_log = raw_log[-self._raw_log_limit :]
+        self.set_variable("raw_log", raw_log)
+
+    def load_raw(self) -> List[Dict[str, Any]]:
+        if self.has_variable("raw_log"):
+            raw_log: List[Dict[str, Any]] = self.load_variable("raw_log")
+        else:
+            raw_log = []
+        return raw_log
+
+    def set_summary(self, summary: str) -> None:
+        self.set_variable("summary", summary)
+
+    def load_summary(self) -> str:
+        if self.has_variable("summary"):
+            return self.load_variable("summary")
+        return ""
+
+    def clear(self) -> None:
+        self._memories.clear()

werewolf/core/output_guard.py

@@ -0,0 +1,302 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import re
+from typing import Iterable, Optional, Sequence
+
+from core import ruleset
+
+
+@dataclass(frozen=True)
+class Guarded:
+    value: str
+    valid: bool
+    used_fallback: bool
+    reason: str
+    normalized: str
+
+
+def guarded_meta(g: Guarded) -> dict:
+    return {
+        "value": g.value,
+        "valid": g.valid,
+        "used_fallback": g.used_fallback,
+        "reason": g.reason,
+        "normalized": g.normalized,
+    }
+
+
+def normalize_llm_text(text: Optional[str]) -> str:
+    if not text:
+        return ""
+
+    s = str(text).strip()
+
+    s = re.sub(r"^\s*```(?:\w+)?\s*", "", s)
+    s = re.sub(r"\s*```\s*$", "", s)
+
+    s = s.strip()
+    if not s:
+        return ""
+
+    first_line = s.splitlines()[0].strip()
+    first_line = first_line.strip(" \t\r\n\"'“”‘’`")
+    return first_line
+
+
+def normalize(text: Optional[str]) -> str:
+    return normalize_llm_text(text)
+
+
+def clip_text(text: Optional[str], max_chars: int, *, fallback: str) -> str:
+    s = (text or "").strip()
+    if not s:
+        return fallback
+    if len(s) <= max_chars:
+        return s
+    return s[:max_chars]
+
+
+def validate_text_len(text: Optional[str], max_chars: int) -> str:
+    return clip_text(text, max_chars, fallback="")
+
+
+def _first_token(s: str) -> str:
+    if not s:
+        return ""
+    parts = re.split(r"[,，\s]+", s.strip())
+    return (parts[0] if parts else "").strip()
+
+
+def extract_choice(text: Optional[str], choices: Sequence[str]) -> Optional[str]:
+    if not choices:
+        return None
+
+    normalized = normalize_llm_text(text)
+    if normalized in choices:
+        return normalized
+
+    token = _first_token(normalized)
+    if token in choices:
+        return token
+
+    raw = text or ""
+    if raw:
+        for c in choices:
+            if c and c in raw:
+                return c
+
+    m = re.search(r"(\d+)", normalized)
+    if m:
+        num = m.group(1)
+        for c in choices:
+            if c == num:
+                return c
+            m2 = re.search(r"(\d+)", c)
+            if m2 and m2.group(1) == num:
+                return c
+
+    return None
+
+
+def validate_choice(result: Optional[str], choices: Sequence[str]) -> bool:
+    return extract_choice(result, choices) is not None
+
+
+def guard_choice(
+    text: Optional[str],
+    choices: Sequence[str],
+    *,
+    fallback: Optional[str] = None,
+    allow_extra: Optional[Iterable[str]] = None,
+) -> Guarded:
+    normalized = normalize_llm_text(text)
+    allow = set(allow_extra or [])
+
+    extracted = extract_choice(text, choices)
+    if extracted is not None:
+        return Guarded(
+            value=extracted,
+            valid=True,
+            used_fallback=False,
+            reason="ok",
+            normalized=normalized,
+        )
+
+    if normalized in allow:
+        return Guarded(
+            value=normalized,
+            valid=True,
+            used_fallback=False,
+            reason="ok_allow_extra",
+            normalized=normalized,
+        )
+
+    fb = fallback or (choices[0] if choices else "")
+    return Guarded(
+        value=fb,
+        valid=False,
+        used_fallback=True,
+        reason="invalid_choice",
+        normalized=normalized,
+    )
+
+
+def guarded_choice(
+    text: Optional[str],
+    choices: Sequence[str],
+    *,
+    fallback: Optional[str] = None,
+    allow_extra: Optional[Iterable[str]] = None,
+) -> Guarded:
+    return guard_choice(text, choices, fallback=fallback, allow_extra=allow_extra)
+
+
+def normalize_enum(text: Optional[str]) -> str:
+    s = normalize_llm_text(text)
+    s = s.replace("撕毁", ruleset.SHERIFF_TEAR).replace("撕掉警徽", ruleset.SHERIFF_TEAR)
+
+    if s in {"不上", "不参加", "不參加"}:
+        return ruleset.SHERIFF_NOT_RUN
+    if s in {"上", "参加", "參加"}:
+        return ruleset.SHERIFF_RUN
+
+    return s
+
+
+def guard_enum(text: Optional[str], allowed: Sequence[str], *, fallback: str) -> Guarded:
+    normalized = normalize_enum(text)
+    if normalized in allowed:
+        return Guarded(
+            value=normalized,
+            valid=True,
+            used_fallback=False,
+            reason="ok",
+            normalized=normalized,
+        )
+
+    for a in allowed:
+        if a and a in (text or ""):
+            return Guarded(
+                value=a,
+                valid=True,
+                used_fallback=False,
+                reason="ok_substring",
+                normalized=normalized,
+            )
+
+    return Guarded(
+        value=fallback,
+        valid=False,
+        used_fallback=True,
+        reason="invalid_enum",
+        normalized=normalized,
+    )
+
+
+def guard_witch_skill(
+    text: Optional[str],
+    *,
+    self_name: str,
+    tonight_killed: str,
+    has_antidote: bool,
+    has_poison: bool,
+) -> Guarded:
+    normalized = normalize_llm_text(text)
+    normalized = normalized.replace(" ", "")
+
+    if normalized == ruleset.WITCH_NO_USE:
+        return Guarded(
+            value=ruleset.WITCH_NO_USE,
+            valid=True,
+            used_fallback=False,
+            reason="ok_no_use",
+            normalized=normalized,
+        )
+
+    if normalized.startswith("救"):
+        if not has_antidote:
+            return Guarded(
+                value=ruleset.WITCH_NO_USE,
+                valid=False,
+                used_fallback=True,
+                reason="no_antidote",
+                normalized=normalized,
+            )
+        if tonight_killed and normalized == f"救{tonight_killed}":
+            return Guarded(
+                value=normalized,
+                valid=True,
+                used_fallback=False,
+                reason="ok_save",
+                normalized=normalized,
+            )
+        return Guarded(
+            value=ruleset.WITCH_NO_USE,
+            valid=False,
+            used_fallback=True,
+            reason="invalid_save_target",
+            normalized=normalized,
+        )
+
+    if normalized.startswith("毒"):
+        if not has_poison:
+            return Guarded(
+                value=ruleset.WITCH_NO_USE,
+                valid=False,
+                used_fallback=True,
+                reason="no_poison",
+                normalized=normalized,
+            )
+        target = normalized[1:].strip("[]【】()（）")
+        if not target:
+            return Guarded(
+                value=ruleset.WITCH_NO_USE,
+                valid=False,
+                used_fallback=True,
+                reason="empty_poison_target",
+                normalized=normalized,
+            )
+        if target == self_name:
+            return Guarded(
+                value=ruleset.WITCH_NO_USE,
+                valid=False,
+                used_fallback=True,
+                reason="poison_self",
+                normalized=normalized,
+            )
+        return Guarded(
+            value=f"毒{target}",
+            valid=True,
+            used_fallback=False,
+            reason="ok_poison",
+            normalized=normalized,
+        )
+
+    return Guarded(
+        value=ruleset.WITCH_NO_USE,
+        valid=False,
+        used_fallback=True,
+        reason="invalid_witch_skill",
+        normalized=normalized,
+    )
+
+
+def correction_instruction_for_choices(choices: Sequence[str], *, allow_extra: Optional[Iterable[str]] = None) -> str:
+    allow = list(allow_extra or [])
+    all_allowed = list(choices) + allow
+    allowed_text = ",".join(all_allowed)
+    return (
+        "\n\n【纠错】你的上一条输出不符合格式。"
+        f"你必须且只能输出以下之一：{allowed_text}。"
+        "不要输出任何解释、标点或多余字符，只输出最终答案。"
+    )
+
+
+def correction_instruction_for_enum(allowed: Sequence[str]) -> str:
+    allowed_text = " / ".join(allowed)
+    return (
+        "\n\n【纠错】你的上一条输出不符合格式。"
+        f"你必须且只能输出：{allowed_text}。"
+        "不要输出任何解释或多余字符，只输出最终答案。"
+    )

werewolf/core/ruleset.py

@@ -0,0 +1,14 @@
+MAX_DISCUSS_CHARS = 240
+
+DEFAULT_DISCUSS_FALLBACK = "我暂时没有更多信息。"
+
+NO_SHOOT = "不开枪"
+WITCH_NO_USE = "不使用"
+SHERIFF_TEAR = "撕掉"
+
+SHERIFF_RUN = "上警"
+SHERIFF_NOT_RUN = "不上警"
+
+SPEECH_ORDER_CW = "顺时针"
+SPEECH_ORDER_CCW = "逆时针"
+

werewolf/core/sanitizer.py

@@ -0,0 +1,34 @@
+import re
+from typing import Iterable
+
+
+_INJECTION_PATTERNS: Iterable[re.Pattern] = [
+    re.compile(r"^\s*(system|assistant|developer|user)\s*[:：]", re.IGNORECASE),
+    re.compile(r"^\s*(主持人提示|系统提示|裁判提示)\s*[:：]?"),
+    re.compile(r"^\s*游戏规则更新\s*[:：]?"),
+]
+
+_INLINE_MARKERS = re.compile(
+    r"(system|assistant|developer|user)\s*[:：]|主持人提示|系统提示|裁判提示|游戏规则更新",
+    re.IGNORECASE,
+)
+
+
+def sanitize_player_text(text: str) -> str:
+    if not text:
+        return ""
+
+    lines = str(text).splitlines()
+    kept = []
+    for line in lines:
+        if any(p.search(line) for p in _INJECTION_PATTERNS):
+            continue
+        kept.append(line)
+
+    if kept:
+        return "\n".join(kept).strip()
+
+    # Fallback: remove inline markers but keep the rest of the message.
+    cleaned = _INLINE_MARKERS.sub("", str(text))
+    return cleaned.strip()
+

werewolf/core/state.py

@@ -0,0 +1,11 @@
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class GameState:
+    round_no: Optional[int] = None
+    alive_players: List[str] = field(default_factory=list)
+    sheriff: Optional[str] = None
+    facts: List[Dict[str, str]] = field(default_factory=list)
+

werewolf/core/telemetry.py

@@ -0,0 +1,180 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+import uuid
+from dataclasses import asdict, is_dataclass
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+
+def _env_flag(name: str, default: str = "1") -> bool:
+    v = os.getenv(name, default).strip().lower()
+    return v not in {"0", "false", "no", "off", ""}
+
+
+def _safe_str(v: Any) -> str:
+    if v is None:
+        return ""
+    return str(v)
+
+
+def _hash_text(s: str) -> str:
+    h = hashlib.sha256()
+    h.update(s.encode("utf-8", errors="replace"))
+    return h.hexdigest()
+
+
+def _prompt_payload(prompt: Optional[str]) -> Dict[str, Any]:
+    if not prompt:
+        return {}
+
+    mode = os.getenv("TELEMETRY_PROMPT_MODE", "hash").strip().lower()
+    if mode == "none":
+        return {"prompt_hash": _hash_text(prompt)}
+    if mode == "full":
+        return {"prompt_hash": _hash_text(prompt), "prompt": prompt}
+
+    preview_len = int(os.getenv("TELEMETRY_PROMPT_PREVIEW", "256"))
+    return {
+        "prompt_hash": _hash_text(prompt),
+        "prompt_preview": prompt[: max(0, preview_len)],
+    }
+
+
+def _jsonable(v: Any) -> Any:
+    if v is None:
+        return None
+    if is_dataclass(v):
+        return {k: _jsonable(val) for k, val in asdict(v).items()}
+    if isinstance(v, dict):
+        return {str(k): _jsonable(val) for k, val in v.items()}
+    if isinstance(v, (list, tuple)):
+        return [_jsonable(x) for x in v]
+    if isinstance(v, (str, int, float, bool)):
+        return v
+    return _safe_str(v)
+
+
+def _safe_mkdir(path: str) -> None:
+    os.makedirs(path, exist_ok=True)
+
+
+def _safe_append_jsonl(path: str, record: Dict[str, Any]) -> None:
+    _safe_mkdir(os.path.dirname(path))
+    line = json.dumps(record, ensure_ascii=False)
+    with open(path, "a", encoding="utf-8") as f:
+        f.write(line + "\n")
+
+
+def _memory_get(memory: Any, key: str, default: Any = None) -> Any:
+    try:
+        if hasattr(memory, "has_variable") and memory.has_variable(key):
+            return memory.load_variable(key)
+    except Exception:
+        return default
+    return default
+
+
+def _memory_set(memory: Any, key: str, value: Any) -> None:
+    try:
+        if hasattr(memory, "set_variable"):
+            memory.set_variable(key, value)
+    except Exception:
+        return
+
+
+def decision_payload(
+    *,
+    prompt: Optional[str],
+    choices: Optional[Sequence[str]],
+    attempt1: Tuple[Optional[str], Dict[str, Any]],
+    attempt2: Optional[Tuple[Optional[str], Dict[str, Any]]],
+    final_result: str,
+    final_skillTargetPlayer: Optional[str] = None,
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {
+        "choices": list(choices) if choices is not None else None,
+        "attempt1": {"raw": attempt1[0], "meta": attempt1[1]},
+        "attempt2": None if attempt2 is None else {"raw": attempt2[0], "meta": attempt2[1]},
+        "final_result": final_result,
+        "final_skillTargetPlayer": final_skillTargetPlayer,
+    }
+    payload.update(_prompt_payload(prompt))
+    return _jsonable(payload)
+
+
+def _derive_from_attempts(payload: Dict[str, Any]) -> Dict[str, Any]:
+    a1 = (payload.get("attempt1") or {})
+    a2 = payload.get("attempt2")
+    last = a2 or a1
+    meta = (last.get("meta") or {}) if isinstance(last, dict) else {}
+
+    parse_valid = meta.get("valid") if isinstance(meta, dict) else None
+    fallback_used = meta.get("used_fallback") if isinstance(meta, dict) else None
+    fallback_reason = meta.get("reason") if isinstance(meta, dict) else None
+    llm_normalized = meta.get("normalized") if isinstance(meta, dict) else None
+
+    return {
+        "llm_raw": (a1.get("raw") if isinstance(a1, dict) else None),
+        "llm_retry_raw": (a2.get("raw") if isinstance(a2, dict) else None) if isinstance(a2, dict) else None,
+        "llm_normalized": llm_normalized,
+        "parse_valid": parse_valid,
+        "retry_count": 1 if a2 is not None else 0,
+        "fallback_used": fallback_used,
+        "fallback_reason": fallback_reason,
+    }
+
+
+def log_interact(
+    *,
+    memory: Any,
+    role: str,
+    status: str,
+    round_no: Optional[int],
+    agent_name: str,
+    payload: Dict[str, Any],
+) -> None:
+    if not _env_flag("TELEMETRY_ENABLED", "1"):
+        return
+
+    try:
+        base_dir = os.getenv("TELEMETRY_DIR", "logs")
+        sid = _memory_get(memory, "session_id")
+        if not sid:
+            ts = int(time.time())
+            sid = f"{ts}_{role}_{agent_name}_{uuid.uuid4().hex[:8]}"
+            _memory_set(memory, "session_id", sid)
+
+        derived = _derive_from_attempts(payload)
+
+        attempt1 = payload.get("attempt1") if isinstance(payload, dict) else None
+        attempt2 = payload.get("attempt2") if isinstance(payload, dict) else None
+        attempt1_raw = attempt1.get("raw") if isinstance(attempt1, dict) else None
+        attempt1_meta = attempt1.get("meta") if isinstance(attempt1, dict) else None
+        attempt2_raw = attempt2.get("raw") if isinstance(attempt2, dict) else None
+        attempt2_meta = attempt2.get("meta") if isinstance(attempt2, dict) else None
+        record: Dict[str, Any] = {
+            "ts": time.time(),
+            "session_id": _safe_str(sid),
+            "role": role,
+            "name": agent_name,
+            "round": round_no,
+            "status": status,
+            "final_result": payload.get("final_result"),
+            "final_skillTargetPlayer": payload.get("final_skillTargetPlayer"),
+            "choices": payload.get("choices"),
+            "attempt1_raw": attempt1_raw,
+            "attempt1_meta": attempt1_meta,
+            "attempt2_raw": attempt2_raw,
+            "attempt2_meta": attempt2_meta,
+            **derived,
+            "payload": payload,
+        }
+
+        filename = f"{round_no}_{status}.jsonl" if round_no is not None else f"na_{status}.jsonl"
+        path = os.path.join(base_dir, _safe_str(sid), role, filename)
+        _safe_append_jsonl(path, _jsonable(record))
+    except Exception:
+        return

werewolf/guard/guard_agent.py

@@ -1,17 +1,18 @@
-from agent_build_sdk.model.roles import ROLE_GUARD
+from agent_build_sdk.model.roles import ROLE_GUARD
 from agent_build_sdk.model.werewolf_model import AgentResp, AgentReq, STATUS_START, STATUS_WOLF_SPEECH, \
     STATUS_VOTE_RESULT, STATUS_SKILL, STATUS_SKILL_RESULT, STATUS_NIGHT_INFO, STATUS_DAY, STATUS_DISCUSS, STATUS_VOTE, \
     STATUS_RESULT, STATUS_NIGHT, STATUS_SHERIFF_ELECTION, STATUS_SHERIFF_SPEECH, STATUS_SHERIFF_VOTE, STATUS_SHERIFF, \
     STATUS_SHERIFF_SPEECH_ORDER, STATUS_SHERIFF_PK, STATUS_HUNTER, STATUS_HUNTER_RESULT
 from agent_build_sdk.utils.logger import logger
-from agent_build_sdk.sdk.role_agent import BasicRoleAgent
 from agent_build_sdk.sdk.agent import format_prompt
+from core import ruleset
+from core.base_role_agent import BaseRoleAgent
 from guard.prompt import DESC_PROMPT, VOTE_PROMPT, SKILL_PROMPT, GAME_RULE_PROMPT, CLEAN_USER_PROMPT, \
     SHERIFF_ELECTION_PROMPT, SHERIFF_SPEECH_PROMPT, SHERIFF_VOTE_PROMPT, SHERIFF_SPEECH_ORDER_PROMPT, \
     SHERIFF_TRANSFER_PROMPT
 
 
-class GuardAgent(BasicRoleAgent):
+class GuardAgent(BaseRoleAgent):
     """守卫角色Agent"""
 
     def __init__(self, model_name):
@@ -38,15 +39,10 @@ class GuardAgent(BasicRoleAgent):
             self.memory.append_history(f"主持人：天亮了！昨天晚上的信息是: {req.message}")
         elif req.status == STATUS_DISCUSS:  # 发言环节
             if req.name:
-                # 其他玩家发言
-                # 可以使用模型来过滤掉玩家的注入消息，也可以换一个小模型，实际使用需要考虑对memory加锁，避免interact的时候丢失消息
-                # clean_user_message_prompt = format_prompt(CLEAN_USER_PROMPT, {"user_message": req.message})
-                # req.message = self.llm_caller(clean_user_message_prompt)
-                self.memory.append_history(req.name + ': ' + req.message)
+                self.append_player_message(req.name, req.message)
             else:
                 # 主持人发言
-                self.memory.append_history('主持人: 现在进入第{}天。'.format(str(req.round)))
-                self.memory.append_history('主持人: 每个玩家描述自己的信息。')
+                self.append_discuss_host(req.round)
             self.memory.append_history("---------------------------------------------")
         elif req.status == STATUS_VOTE:  # 投票环节
             self.memory.append_history(f'第{req.round}天。投票信息:{req.name}投了{req.message}')
@@ -86,6 +82,8 @@ class GuardAgent(BasicRoleAgent):
         else:
             raise NotImplementedError
 
+        self.update_state(req)
+
     def interact(self, req=AgentReq) -> AgentResp:
         logger.info("guard interact: {}".format(req))
         if req.status == STATUS_DISCUSS:
@@ -99,27 +97,43 @@ class GuardAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="discuss",
+            )
             logger.info("guard interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_VOTE:
             self.memory.append_history('主持人: 到了投票的时候了。每个人，请指向你认为可能是狼人的人。')
-            choices = [name for name in req.message.split(",") if name != self.memory.load_variable("name")]
+            raw_choices = [name for name in (req.message or "").split(",") if name]
+            choices = [name for name in raw_choices if name != self.memory.load_variable("name")]
+            if not choices:
+                choices = raw_choices
             self.memory.set_variable("choices", choices)
             prompt = format_prompt(VOTE_PROMPT, {"name": self.memory.load_variable("name"),
                                                "choices": choices,
                                                "history": "\n".join(self.memory.load_history())
                                               })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             logger.info("guard interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SKILL:
             # 守卫技能：守护一名玩家
             last_guarded = self.memory.load_variable("last_guarded")
-            choices = [name for name in req.message.split(",") if name != last_guarded]
+            raw_choices = [name for name in (req.message or "").split(",") if name]
+            choices = [name for name in raw_choices if name != last_guarded]
+            if not choices:
+                choices = raw_choices
             prompt = format_prompt(SKILL_PROMPT, {
                 "name": self.memory.load_variable("name"),
                 "last_guarded": last_guarded if last_guarded else "无",
@@ -127,7 +141,13 @@ class GuardAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                final_skill_target_from_result=lambda r: r,
+            )
             logger.info("guard skill result: {}".format(result))
 
             # 更新守护记录
@@ -144,7 +164,13 @@ class GuardAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SHERIFF_RUN, ruleset.SHERIFF_NOT_RUN],
+                fallback=ruleset.SHERIFF_NOT_RUN,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_SPEECH or req.status == STATUS_SHERIFF_PK:
@@ -156,7 +182,13 @@ class GuardAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            kind = "sheriff_pk" if req.status == STATUS_SHERIFF_PK else "sheriff_speech"
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind=kind,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_VOTE:
@@ -167,7 +199,12 @@ class GuardAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_SPEECH_ORDER:
@@ -176,7 +213,13 @@ class GuardAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SPEECH_ORDER_CW, ruleset.SPEECH_ORDER_CCW],
+                fallback=ruleset.SPEECH_ORDER_CW,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF:
@@ -188,7 +231,14 @@ class GuardAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                allow_extra=[ruleset.SHERIFF_TEAR],
+                fallback=ruleset.SHERIFF_TEAR,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
         else:
             raise NotImplementedError

werewolf/hunter/hunter_agent.py

@@ -1,17 +1,18 @@
-from agent_build_sdk.model.roles import ROLE_HUNTER
+from agent_build_sdk.model.roles import ROLE_HUNTER
 from agent_build_sdk.model.werewolf_model import AgentResp, AgentReq, STATUS_START, STATUS_WOLF_SPEECH, \
     STATUS_VOTE_RESULT, STATUS_SKILL, STATUS_SKILL_RESULT, STATUS_NIGHT_INFO, STATUS_DAY, STATUS_DISCUSS, STATUS_VOTE, \
     STATUS_RESULT, STATUS_NIGHT, STATUS_SHERIFF_ELECTION, STATUS_SHERIFF_SPEECH, STATUS_SHERIFF_VOTE, STATUS_SHERIFF, \
     STATUS_SHERIFF_SPEECH_ORDER, STATUS_SHERIFF_PK
 from agent_build_sdk.utils.logger import logger
-from agent_build_sdk.sdk.role_agent import BasicRoleAgent
 from agent_build_sdk.sdk.agent import format_prompt
+from core import ruleset
+from core.base_role_agent import BaseRoleAgent
 from hunter.prompt import DESC_PROMPT, VOTE_PROMPT, SKILL_PROMPT, GAME_RULE_PROMPT, CLEAN_USER_PROMPT, \
     SHERIFF_ELECTION_PROMPT, SHERIFF_SPEECH_PROMPT, SHERIFF_VOTE_PROMPT, SHERIFF_SPEECH_ORDER_PROMPT, \
     SHERIFF_TRANSFER_PROMPT
 
 
-class HunterAgent(BasicRoleAgent):
+class HunterAgent(BaseRoleAgent):
     """猎人角色Agent"""
 
     def __init__(self, model_name):
@@ -38,15 +39,10 @@ class HunterAgent(BasicRoleAgent):
             self.memory.append_history(f"主持人：天亮了！昨天晚上的信息是: {req.message}")
         elif req.status == STATUS_DISCUSS:  # 发言环节
             if req.name:
-                # 其他玩家发言
-                # 可以使用模型来过滤掉玩家的注入消息，也可以换一个小模型，实际使用需要考虑对memory加锁，避免interact的时候丢失消息
-                # clean_user_message_prompt = format_prompt(CLEAN_USER_PROMPT, {"user_message": req.message})
-                # req.message = self.llm_caller(clean_user_message_prompt)
-                self.memory.append_history(req.name + ': ' + req.message)
+                self.append_player_message(req.name, req.message)
             else:
                 # 主持人发言
-                self.memory.append_history('主持人: 现在进入第{}天。'.format(str(req.round)))
-                self.memory.append_history('主持人: 每个玩家描述自己的信息。')
+                self.append_discuss_host(req.round)
             self.memory.append_history("---------------------------------------------")
         elif req.status == STATUS_VOTE:  # 投票环节
             self.memory.append_history(f'第{req.round}天。投票信息:{req.name}投了{req.message}')
@@ -79,6 +75,8 @@ class HunterAgent(BasicRoleAgent):
         else:
             raise NotImplementedError
 
+        self.update_state(req)
+
     def interact(self, req=AgentReq) -> AgentResp:
         logger.info("hunter interact: {}".format(req))
         if req.status == STATUS_DISCUSS:
@@ -92,20 +90,33 @@ class HunterAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="discuss",
+            )
             logger.info("hunter interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_VOTE:
             self.memory.append_history('主持人: 到了投票的时候了。每个人，请指向你认为可能是狼人的人。')
-            choices = [name for name in req.message.split(",") if name != self.memory.load_variable("name")]
+            raw_choices = [name for name in (req.message or "").split(",") if name]
+            choices = [name for name in raw_choices if name != self.memory.load_variable("name")]
+            if not choices:
+                choices = raw_choices
             self.memory.set_variable("choices", choices)
             prompt = format_prompt(VOTE_PROMPT, {"name": self.memory.load_variable("name"),
                                                "choices": choices,
                                                "history": "\n".join(self.memory.load_history())
                                               })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             logger.info("hunter interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -113,22 +124,33 @@ class HunterAgent(BasicRoleAgent):
             # 猎人技能：开枪射杀一名玩家（遗言阶段）
             can_shoot = self.memory.load_variable("can_shoot")
             if not can_shoot:
-                return AgentResp(success=True, result="不开枪", errMsg=None)
+                return AgentResp(success=True, result=ruleset.NO_SHOOT, errMsg=None)
 
-            choices = [name for name in req.message.split(",") if name != self.memory.load_variable("name")]
+            raw_choices = [name for name in (req.message or "").split(",") if name]
+            choices = [name for name in raw_choices if name != self.memory.load_variable("name")]
+            if not choices:
+                choices = raw_choices
             prompt = format_prompt(SKILL_PROMPT, {
                 "name": self.memory.load_variable("name"),
                 "choices": choices,
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                allow_extra=[ruleset.NO_SHOOT],
+                fallback=ruleset.NO_SHOOT,
+                final_skill_target_from_result=lambda r: None if r == ruleset.NO_SHOOT else r,
+            )
             logger.info("hunter skill result: {}".format(result))
 
-            if result != "不开枪":
+            if result != ruleset.NO_SHOOT:
                 self.memory.set_variable("can_shoot", False)
 
-            return AgentResp(success=True, result=result, skillTargetPlayer=None if result == "不开枪" else result, errMsg=None)
+            return AgentResp(success=True, result=result, skillTargetPlayer=None if result == ruleset.NO_SHOOT else result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_ELECTION:
             can_shoot = self.memory.load_variable("can_shoot")
@@ -139,7 +161,13 @@ class HunterAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SHERIFF_RUN, ruleset.SHERIFF_NOT_RUN],
+                fallback=ruleset.SHERIFF_NOT_RUN,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_SPEECH or req.status == STATUS_SHERIFF_PK:
@@ -151,7 +179,13 @@ class HunterAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            kind = "sheriff_pk" if req.status == STATUS_SHERIFF_PK else "sheriff_speech"
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind=kind,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_VOTE:
@@ -162,7 +196,12 @@ class HunterAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_SPEECH_ORDER:
@@ -171,7 +210,13 @@ class HunterAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SPEECH_ORDER_CW, ruleset.SPEECH_ORDER_CCW],
+                fallback=ruleset.SPEECH_ORDER_CW,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF:
@@ -186,7 +231,14 @@ class HunterAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                allow_extra=[ruleset.SHERIFF_TEAR],
+                fallback=ruleset.SHERIFF_TEAR,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
         else:
             raise NotImplementedError

werewolf/seer/seer_agent.py

@@ -1,17 +1,18 @@
-from agent_build_sdk.model.roles import ROLE_SEER
+from agent_build_sdk.model.roles import ROLE_SEER
 from agent_build_sdk.model.werewolf_model import AgentResp, AgentReq, STATUS_START, STATUS_WOLF_SPEECH, \
     STATUS_VOTE_RESULT, STATUS_SKILL, STATUS_SKILL_RESULT, STATUS_NIGHT_INFO, STATUS_DAY, STATUS_DISCUSS, STATUS_VOTE, \
     STATUS_RESULT, STATUS_NIGHT, STATUS_SHERIFF_SPEECH, STATUS_SHERIFF, STATUS_SHERIFF_VOTE, STATUS_SHERIFF_ELECTION, \
     STATUS_SHERIFF_PK, STATUS_SHERIFF_SPEECH_ORDER, STATUS_HUNTER, STATUS_HUNTER_RESULT
 from agent_build_sdk.utils.logger import logger
-from agent_build_sdk.sdk.role_agent import BasicRoleAgent
 from agent_build_sdk.sdk.agent import format_prompt
+from core import ruleset
+from core.base_role_agent import BaseRoleAgent
 from seer.prompt import DESC_PROMPT, VOTE_PROMPT, SKILL_PROMPT, GAME_RULE_PROMPT, CLEAN_USER_PROMPT, \
     SHERIFF_ELECTION_PROMPT, SHERIFF_SPEECH_PROMPT, SHERIFF_VOTE_PROMPT, SHERIFF_SPEECH_ORDER_PROMPT, \
     SHERIFF_TRANSFER_PROMPT
 
 
-class SeerAgent(BasicRoleAgent):
+class SeerAgent(BaseRoleAgent):
     """预言家角色Agent"""
 
     def __init__(self, model_name):
@@ -37,15 +38,10 @@ class SeerAgent(BasicRoleAgent):
             self.memory.append_history(f"主持人：天亮了！昨天晚上的信息是: {req.message}")
         elif req.status == STATUS_DISCUSS:  # 发言环节
             if req.name:
-                # 其他玩家发言
-                # 可以使用模型来过滤掉玩家的注入消息，也可以换一个小模型，实际使用需要考虑对memory加锁，避免interact的时候丢失消息
-                # clean_user_message_prompt = format_prompt(CLEAN_USER_PROMPT, {"user_message": req.message})
-                # req.message = self.llm_caller(clean_user_message_prompt)
-                self.memory.append_history(req.name + ': ' + req.message)
+                self.append_player_message(req.name, req.message)
             else:
                 # 主持人发言
-                self.memory.append_history('主持人: 现在进入第{}天。'.format(str(req.round)))
-                self.memory.append_history('主持人: 每个玩家描述自己的信息。')
+                self.append_discuss_host(req.round)
         elif req.status == STATUS_VOTE:  # 投票环节
             self.memory.append_history(f'第{req.round}天的投票环节,{req.name} 投了 {req.message}')
         elif req.status == STATUS_VOTE_RESULT:  # 投票结果
@@ -85,6 +81,8 @@ class SeerAgent(BasicRoleAgent):
         else:
             raise NotImplementedError
 
+        self.update_state(req)
+
     def interact(self, req=AgentReq) -> AgentResp:
         logger.info("seer interact: {}".format(req))
         if req.status == STATUS_DISCUSS:
@@ -97,14 +95,22 @@ class SeerAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="discuss",
+            )
             logger.info("seer interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_VOTE:
             self.memory.append_history('主持人: 到了投票的时候了。每个人，请指向你认为可能是狼人的人。')
             checked_players = self.memory.load_variable("checked_players")
-            choices = [name for name in req.message.split(",") if name != self.memory.load_variable("name")]  # 排除自己
+            raw_choices = [name for name in (req.message or "").split(",") if name]
+            choices = [name for name in raw_choices if name != self.memory.load_variable("name")]  # 排除自己
+            if not choices:
+                choices = raw_choices
             self.memory.set_variable("choices", choices)
             prompt = format_prompt(VOTE_PROMPT, {"name": self.memory.load_variable("name"),
                                                "checked_players": checked_players,
@@ -112,13 +118,18 @@ class SeerAgent(BasicRoleAgent):
                                                "history": "\n".join(self.memory.load_history())
                                               })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             logger.info("seer interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SKILL:
             checked_players = self.memory.load_variable("checked_players")
-            choices = [name for name in req.message.split(",")
+            choices = [name for name in (req.message or "").split(",")
                       if name != self.memory.load_variable("name") and name not in checked_players]  # 排除自己和已查验的
             self.memory.set_variable("choices", choices)
             prompt = format_prompt(SKILL_PROMPT, {
@@ -128,7 +139,13 @@ class SeerAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                final_skill_target_from_result=lambda r: r,
+            )
             logger.info("seer skill result: {}".format(result))
             return AgentResp(success=True, result=result, skillTargetPlayer=result, errMsg=None)
 
@@ -138,7 +155,13 @@ class SeerAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("seer agent sheriff election prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SHERIFF_RUN, ruleset.SHERIFF_NOT_RUN],
+                fallback=ruleset.SHERIFF_NOT_RUN,
+            )
             logger.info("seer agent sheriff election result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -150,7 +173,12 @@ class SeerAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("seer agent sheriff speech prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="sheriff_speech",
+            )
             logger.info("seer agent sheriff speech result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -162,7 +190,12 @@ class SeerAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("seer agent sheriff pk prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="sheriff_pk",
+            )
             logger.info("seer agent sheriff pk result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -174,7 +207,12 @@ class SeerAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("seer agent sheriff vote prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             logger.info("seer agent sheriff vote result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -184,7 +222,13 @@ class SeerAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("seer agent sheriff speech order prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SPEECH_ORDER_CW, ruleset.SPEECH_ORDER_CCW],
+                fallback=ruleset.SPEECH_ORDER_CW,
+            )
             logger.info("seer agent sheriff speech order result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -199,8 +243,15 @@ class SeerAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("seer agent sheriff transfer prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                allow_extra=[ruleset.SHERIFF_TEAR],
+                fallback=ruleset.SHERIFF_TEAR,
+            )
             logger.info("seer agent sheriff transfer result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
         else:
-            raise NotImplementedError
+            raise NotImplementedError

werewolf/tools/__init__.py

@@ -0,0 +1,2 @@
+# Utility CLI tools (telemetry replay, etc.).
+

werewolf/tools/replay.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import argparse
+import glob
+import json
+import os
+from collections import Counter, defaultdict
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+
+def _iter_jsonl_files(root: str) -> Iterable[str]:
+    pattern = os.path.join(root, "**", "*.jsonl")
+    yield from glob.iglob(pattern, recursive=True)
+
+
+def _read_records(paths: Iterable[str]) -> Iterable[Dict[str, Any]]:
+    for path in paths:
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        yield json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+        except OSError:
+            continue
+
+
+def _pick_latest_session(log_root: str) -> Optional[str]:
+    try:
+        sessions = [
+            os.path.join(log_root, d)
+            for d in os.listdir(log_root)
+            if os.path.isdir(os.path.join(log_root, d))
+        ]
+    except OSError:
+        return None
+    if not sessions:
+        return None
+    sessions.sort(key=lambda p: os.path.getmtime(p), reverse=True)
+    return os.path.basename(sessions[0])
+
+
+def _bool(x: Any) -> Optional[bool]:
+    if isinstance(x, bool):
+        return x
+    return None
+
+
+def compute_metrics(records: List[Dict[str, Any]]) -> Dict[str, Any]:
+    by_status = Counter()
+    by_role = Counter()
+
+    with_choices = 0
+    final_in_choices = 0
+    retry_count = 0
+    fallback_used = 0
+    valid_final = 0
+    has_valid_flag = 0
+
+    per_status = defaultdict(lambda: {"count": 0, "with_choices": 0, "final_in_choices": 0, "retry": 0, "fallback": 0})
+
+    for r in records:
+        status = r.get("status") or "unknown"
+        role = r.get("role") or "unknown"
+        by_status[status] += 1
+        by_role[role] += 1
+        per_status[status]["count"] += 1
+
+        choices = r.get("choices") or []
+        if isinstance(choices, list) and len(choices) > 0:
+            with_choices += 1
+            per_status[status]["with_choices"] += 1
+            if r.get("final_result") in choices:
+                final_in_choices += 1
+                per_status[status]["final_in_choices"] += 1
+
+        retried = bool(r.get("retry_count") or 0)
+        if retried:
+            retry_count += 1
+            per_status[status]["retry"] += 1
+
+        fb = _bool(r.get("fallback_used"))
+        if fb is True:
+            fallback_used += 1
+            per_status[status]["fallback"] += 1
+
+        v = _bool(r.get("parse_valid"))
+        if v is not None:
+            has_valid_flag += 1
+            if v is True:
+                valid_final += 1
+
+    return {
+        "total": len(records),
+        "by_status": by_status,
+        "by_role": by_role,
+        "with_choices": with_choices,
+        "final_in_choices": final_in_choices,
+        "retry_count": retry_count,
+        "fallback_used": fallback_used,
+        "valid_final": valid_final,
+        "has_valid_flag": has_valid_flag,
+        "per_status": per_status,
+    }
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="Replay telemetry logs and report compliance metrics.")
+    ap.add_argument("--log-root", default="logs", help="Telemetry log root (default: logs)")
+    ap.add_argument("--session", default=None, help="Session id to analyze (default: latest)")
+    args = ap.parse_args()
+
+    session = args.session or _pick_latest_session(args.log_root)
+    if not session:
+        print(f"No sessions found under {args.log_root!r}.")
+        return 1
+
+    root = os.path.join(args.log_root, session)
+    paths = list(_iter_jsonl_files(root))
+    records = list(_read_records(paths))
+    m = compute_metrics(records)
+
+    print(f"Session: {session}")
+    print(f"Records: {m['total']}")
+    print(f"Roles: {dict(m['by_role'])}")
+    print(f"Status: {dict(m['by_status'])}")
+
+    if m["with_choices"] > 0:
+        rate = m["final_in_choices"] / m["with_choices"]
+        print(f"Final-in-choices: {m['final_in_choices']}/{m['with_choices']} = {rate:.3f}")
+        print(f"Retry-rate: {m['retry_count']}/{m['with_choices']} = {m['retry_count']/m['with_choices']:.3f}")
+        print(f"Fallback-rate: {m['fallback_used']}/{m['with_choices']} = {m['fallback_used']/m['with_choices']:.3f}")
+
+    if m["has_valid_flag"] > 0:
+        print(f"Final-valid: {m['valid_final']}/{m['has_valid_flag']} = {m['valid_final']/m['has_valid_flag']:.3f}")
+
+    print("\nPer-status:")
+    for status, s in sorted(m["per_status"].items(), key=lambda kv: kv[0]):
+        if s["count"] == 0:
+            continue
+        parts = [f"{status}: count={s['count']}"]
+        if s["with_choices"]:
+            parts.append(f"in_choices={s['final_in_choices']}/{s['with_choices']}")
+            parts.append(f"retry={s['retry']}/{s['with_choices']}")
+            parts.append(f"fallback={s['fallback']}/{s['with_choices']}")
+        print("  " + ", ".join(parts))
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

werewolf/villager/villager_agent.py

@@ -1,4 +1,4 @@
-from villager.prompt import DESC_PROMPT, VOTE_PROMPT, GAME_RULE_PROMPT, CLEAN_USER_PROMPT, SHERIFF_ELECTION_PROMPT, \
+from villager.prompt import DESC_PROMPT, VOTE_PROMPT, GAME_RULE_PROMPT, CLEAN_USER_PROMPT, SHERIFF_ELECTION_PROMPT, \
     SHERIFF_SPEECH_PROMPT, SHERIFF_VOTE_PROMPT, SHERIFF_SPEECH_ORDER_PROMPT, SHERIFF_TRANSFER_PROMPT
 from agent_build_sdk.model.roles import ROLE_VILLAGER
 from agent_build_sdk.model.werewolf_model import AgentResp, AgentReq, STATUS_START, STATUS_WOLF_SPEECH, \
@@ -6,11 +6,12 @@ from agent_build_sdk.model.werewolf_model import AgentResp, AgentReq, STATUS_STA
     STATUS_RESULT, STATUS_NIGHT, STATUS_SHERIFF_SPEECH, STATUS_SHERIFF, STATUS_SHERIFF_VOTE, STATUS_SHERIFF_ELECTION, \
     STATUS_SHERIFF_PK, STATUS_SHERIFF_SPEECH_ORDER, STATUS_HUNTER, STATUS_HUNTER_RESULT
 from agent_build_sdk.utils.logger import logger
-from agent_build_sdk.sdk.role_agent import BasicRoleAgent
 from agent_build_sdk.sdk.agent import format_prompt
+from core import ruleset
+from core.base_role_agent import BaseRoleAgent
 
 
-class VillagerAgent(BasicRoleAgent):
+class VillagerAgent(BaseRoleAgent):
     """平民角色Agent"""
 
     def __init__(self, model_name):
@@ -28,14 +29,10 @@ class VillagerAgent(BasicRoleAgent):
             self.memory.append_history(f"主持人：天亮了！昨天晚上的信息是: {req.message}")
         elif req.status == STATUS_DISCUSS:  # 发言环节
             if req.name:
-                # 可以使用模型来过滤掉玩家的注入消息，也可以换一个小模型，实际使用需要考虑对memory加锁，避免interact的时候丢失消息
-                # clean_user_message_prompt = format_prompt(CLEAN_USER_PROMPT, {"user_message": req.message})
-                # req.message = self.llm_caller(clean_user_message_prompt)
-                self.memory.append_history(req.name + ': ' + req.message)
+                self.append_player_message(req.name, req.message)
             else:
                 # 主持人发言
-                self.memory.append_history('主持人: 现在进入第{}天。'.format(str(req.round)))
-                self.memory.append_history('主持人: 每个玩家描述自己的信息。')
+                self.append_discuss_host(req.round)
             self.memory.append_history("---------------------------------------------")
         elif req.status == STATUS_VOTE:  # 投票环节
             self.memory.append_history(f'第{req.round}天的投票环节,{req.name} 投了 {req.message}')
@@ -75,7 +72,8 @@ class VillagerAgent(BasicRoleAgent):
             self.memory.append_history(f"警长PK发言: {req.name}: {req.message}")
         else:
             raise NotImplementedError
-        pass
+
+        self.update_state(req)
 
     def interact(self, req=AgentReq) -> AgentResp:
         logger.info("VillagerAgent interact: {}".format(req))
@@ -87,20 +85,33 @@ class VillagerAgent(BasicRoleAgent):
                                     "history": "\n".join(self.memory.load_history())
                                     })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="discuss",
+            )
             logger.info("VillagerAgent interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_VOTE:
             self.memory.append_history('主持人: 到了投票的时候了。每个人，请指向你认为可能是狼人的人。')
-            choices = [name for name in req.message.split(",") if name != self.memory.load_variable("name")]  # 排除自己
+            raw_choices = [name for name in (req.message or "").split(",") if name]
+            choices = [name for name in raw_choices if name != self.memory.load_variable("name")]  # 排除自己
+            if not choices:
+                choices = raw_choices
             self.memory.set_variable("choices", choices)
             prompt = format_prompt(VOTE_PROMPT, {"name": self.memory.load_variable("name"),
                                                  "choices": choices,
                                                  "history": "\n".join(self.memory.load_history())
                                                  })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             logger.info("interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -108,7 +119,14 @@ class VillagerAgent(BasicRoleAgent):
             prompt = format_prompt(SHERIFF_ELECTION_PROMPT, {"name": self.memory.load_variable("name"),
                                                              "history": "\n".join(self.memory.load_history())})
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            allowed = [ruleset.SHERIFF_RUN, ruleset.SHERIFF_NOT_RUN]
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=allowed,
+                fallback=ruleset.SHERIFF_NOT_RUN,
+            )
             logger.info("VillagerAgent sheriff election result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -116,7 +134,12 @@ class VillagerAgent(BasicRoleAgent):
             prompt = format_prompt(SHERIFF_SPEECH_PROMPT, {"name": self.memory.load_variable("name"),
                                                            "history": "\n".join(self.memory.load_history())})
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="sheriff_speech",
+            )
             logger.info("VillagerAgent sheriff speech result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -124,7 +147,12 @@ class VillagerAgent(BasicRoleAgent):
             prompt = format_prompt(SHERIFF_SPEECH_PROMPT, {"name": self.memory.load_variable("name"),
                                                            "history": "\n".join(self.memory.load_history())})
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="sheriff_pk",
+            )
             logger.info("VillagerAgent sheriff pk result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -134,7 +162,12 @@ class VillagerAgent(BasicRoleAgent):
                                                          "choices": choices,
                                                          "history": "\n".join(self.memory.load_history())})
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             logger.info("VillagerAgent sheriff vote result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -142,7 +175,14 @@ class VillagerAgent(BasicRoleAgent):
             prompt = format_prompt(SHERIFF_SPEECH_ORDER_PROMPT, {"name": self.memory.load_variable("name"),
                                                                  "history": "\n".join(self.memory.load_history())})
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            allowed = [ruleset.SPEECH_ORDER_CW, ruleset.SPEECH_ORDER_CCW]
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=allowed,
+                fallback=ruleset.SPEECH_ORDER_CW,
+            )
             logger.info("VillagerAgent sheriff speech order result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -153,9 +193,15 @@ class VillagerAgent(BasicRoleAgent):
                                                              "choices": choices,
                                                              "history": "\n".join(self.memory.load_history())})
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                allow_extra=[ruleset.SHERIFF_TEAR],
+                fallback=ruleset.SHERIFF_TEAR,
+            )
             logger.info("VillagerAgent sheriff transfer result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
         else:
             raise NotImplementedError
-        pass

werewolf/witch/witch_agent.py

@@ -1,16 +1,20 @@
-from agent_build_sdk.model.roles import ROLE_WITCH
+from agent_build_sdk.model.roles import ROLE_WITCH
 from agent_build_sdk.model.werewolf_model import AgentResp, AgentReq, STATUS_START, STATUS_WOLF_SPEECH, \
     STATUS_VOTE_RESULT, STATUS_SKILL, STATUS_SKILL_RESULT, STATUS_NIGHT_INFO, STATUS_DAY, STATUS_DISCUSS, STATUS_VOTE, \
     STATUS_RESULT, STATUS_NIGHT, STATUS_SHERIFF_ELECTION, STATUS_SHERIFF_SPEECH, STATUS_SHERIFF_VOTE, STATUS_SHERIFF, \
     STATUS_SHERIFF_SPEECH_ORDER, STATUS_SHERIFF_PK, STATUS_HUNTER, STATUS_HUNTER_RESULT
 from agent_build_sdk.utils.logger import logger
-from agent_build_sdk.sdk.role_agent import BasicRoleAgent
 from agent_build_sdk.sdk.agent import format_prompt
+from core import ruleset
+from core import telemetry
+from core.base_role_agent import BaseRoleAgent
+from core.output_guard import guard_witch_skill, guarded_meta
 from witch.prompt import DESC_PROMPT, VOTE_PROMPT, SKILL_PROMPT, GAME_RULE_PROMPT, CLEAN_USER_PROMPT, \
     SHERIFF_ELECTION_PROMPT, SHERIFF_SPEECH_PROMPT, SHERIFF_VOTE_PROMPT, SHERIFF_SPEECH_ORDER_PROMPT, \
     SHERIFF_TRANSFER_PROMPT
 
-class WitchAgent(BasicRoleAgent):
+
+class WitchAgent(BaseRoleAgent):
     """女巫角色Agent"""
 
     def __init__(self, model_name):
@@ -36,15 +40,10 @@ class WitchAgent(BasicRoleAgent):
             self.memory.append_history(f"主持人：天亮了！昨天晚上的信息是: {req.message}")
         elif req.status == STATUS_DISCUSS:  # 发言环节
             if req.name:
-                # 其他玩家发言
-                # 可以使用模型来过滤掉玩家的注入消息，也可以换一个小模型，实际使用需要考虑对memory加锁，避免interact的时候丢失消息
-                # clean_user_message_prompt = format_prompt(CLEAN_USER_PROMPT, {"user_message": req.message})
-                # req.message = self.llm_caller(clean_user_message_prompt)
-                self.memory.append_history(req.name + ': ' + req.message)
+                self.append_player_message(req.name, req.message)
             else:
                 # 主持人发言
-                self.memory.append_history('主持人: 现在进入第{}天。'.format(str(req.round)))
-                self.memory.append_history('主持人: 每个玩家描述自己的信息。')
+                self.append_discuss_host(req.round)
         elif req.status == STATUS_VOTE:  # 投票环节
             self.memory.append_history(f'第{req.round}天的投票环节,{req.name} 投了 {req.message}')
         elif req.status == STATUS_VOTE_RESULT:  # 投票结果
@@ -84,6 +83,8 @@ class WitchAgent(BasicRoleAgent):
         else:
             raise NotImplementedError
 
+        self.update_state(req)
+
     def interact(self, req=AgentReq) -> AgentResp:
         logger.info("witch interact: {}".format(req))
         if req.status == STATUS_DISCUSS:
@@ -99,20 +100,33 @@ class WitchAgent(BasicRoleAgent):
                                     "history": "\n".join(self.memory.load_history())
                                     })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="discuss",
+            )
             logger.info("witch interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_VOTE:
             self.memory.append_history('主持人: 到了投票的时候了。每个人，请指向你认为可能是狼人的人。')
-            choices = [name for name in req.message.split(",") if name != self.memory.load_variable("name")]  # 排除自己
+            raw_choices = [name for name in (req.message or "").split(",") if name]
+            choices = [name for name in raw_choices if name != self.memory.load_variable("name")]  # 排除自己
+            if not choices:
+                choices = raw_choices
             self.memory.set_variable("choices", choices)
             prompt = format_prompt(VOTE_PROMPT, {"name": self.memory.load_variable("name"),
                                                  "choices": choices,
                                                  "history": "\n".join(self.memory.load_history())
                                                  })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             logger.info("witch interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -130,20 +144,72 @@ class WitchAgent(BasicRoleAgent):
             })
 
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            raw1 = self.llm_caller(prompt)
+            first = guard_witch_skill(
+                raw1,
+                self_name=self.memory.load_variable("name"),
+                tonight_killed=tonight_killed,
+                has_antidote=has_antidote,
+                has_poison=has_poison,
+            )
+            if not first.valid:
+                allowed_lines = []
+                if has_antidote and tonight_killed:
+                    allowed_lines.append(f"- 救{tonight_killed}")
+                if has_poison:
+                    allowed_lines.append("- 毒玩家名")
+                allowed_lines.append(f"- {ruleset.WITCH_NO_USE}")
+                retry_prompt = (
+                    prompt
+                    + "\n\n【纠错】你的上一条输出不符合格式。你必须只输出以下三种之一：\n"
+                    + "\n".join(allowed_lines)
+                    + "\n不要输出任何解释，只输出最终答案。"
+                )
+                raw2 = self.llm_caller(retry_prompt)
+                second = guard_witch_skill(
+                    raw2,
+                    self_name=self.memory.load_variable("name"),
+                    tonight_killed=tonight_killed,
+                    has_antidote=has_antidote,
+                    has_poison=has_poison,
+                )
+                result = second.value
+            else:
+                raw2 = None
+                second = None
+                result = first.value
+
             logger.info("witch skill result: {}".format(result))
-            # 根据结果更新药水状态
+
+            result = self._render_action_if_possible(req.status, result)
+
             skill_target_person = None
-            if result.startswith("救") and has_antidote:
+            if result.startswith("救"):
                 self.memory.set_variable("has_antidote", False)
                 self.memory.append_history(f"女巫使用解药救活了{tonight_killed}")
                 skill_target_person = tonight_killed
-            elif result.startswith("毒") and has_poison:
+            elif result.startswith("毒"):
                 poisoned_player = result[1:].strip()
                 self.memory.set_variable("has_poison", False)
                 self.memory.append_history(f"女巫使用毒药杀死了{poisoned_player}")
                 skill_target_person = poisoned_player
 
+            telemetry.log_interact(
+                memory=self.memory,
+                role=str(self.role),
+                status=req.status,
+                round_no=req.round,
+                agent_name=self.memory.load_variable("name"),
+                payload=telemetry.decision_payload(
+                    prompt=prompt,
+                    choices=None,
+                    attempt1=(raw1, guarded_meta(first)),
+                    attempt2=None if raw2 is None else (raw2, guarded_meta(second)),
+                    final_result=result,
+                    final_skillTargetPlayer=skill_target_person,
+                ),
+            )
+
             return AgentResp(success=True, result=result, skillTargetPlayer=skill_target_person, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_ELECTION:
@@ -156,7 +222,13 @@ class WitchAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SHERIFF_RUN, ruleset.SHERIFF_NOT_RUN],
+                fallback=ruleset.SHERIFF_NOT_RUN,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_SPEECH or req.status == STATUS_SHERIFF_PK:
@@ -169,7 +241,13 @@ class WitchAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            kind = "sheriff_pk" if req.status == STATUS_SHERIFF_PK else "sheriff_speech"
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind=kind,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_VOTE:
@@ -180,7 +258,12 @@ class WitchAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_SPEECH_ORDER:
@@ -189,7 +272,13 @@ class WitchAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SPEECH_ORDER_CW, ruleset.SPEECH_ORDER_CCW],
+                fallback=ruleset.SPEECH_ORDER_CW,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF:
@@ -201,7 +290,14 @@ class WitchAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                allow_extra=[ruleset.SHERIFF_TEAR],
+                fallback=ruleset.SHERIFF_TEAR,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
         else:
             raise NotImplementedError

werewolf/wolf/wolf_agent.py

@@ -1,4 +1,4 @@
-from agent_build_sdk.model.roles import ROLE_WOLF
+from agent_build_sdk.model.roles import ROLE_WOLF
 from agent_build_sdk.model.werewolf_model import (
     AgentResp, AgentReq, STATUS_START, STATUS_WOLF_SPEECH,
     STATUS_VOTE_RESULT, STATUS_SKILL, STATUS_SKILL_RESULT, STATUS_NIGHT_INFO,
@@ -7,8 +7,9 @@ from agent_build_sdk.model.werewolf_model import (
     STATUS_SHERIFF_VOTE, STATUS_SHERIFF_SPEECH_ORDER, STATUS_SHERIFF, STATUS_HUNTER, STATUS_HUNTER_RESULT
 )
 from agent_build_sdk.utils.logger import logger
-from agent_build_sdk.sdk.role_agent import BasicRoleAgent
 from agent_build_sdk.sdk.agent import format_prompt
+from core import ruleset
+from core.base_role_agent import BaseRoleAgent
 from wolf.prompt import (
     DESC_PROMPT, VOTE_PROMPT, KILL_PROMPT, WOLF_SPEECH_PROMPT, GAME_RULE_PROMPT,
     CLEAN_USER_PROMPT, SHERIFF_ELECTION_PROMPT, SHERIFF_SPEECH_PROMPT,
@@ -16,7 +17,7 @@ from wolf.prompt import (
 )
 
 
-class WolfAgent(BasicRoleAgent):
+class WolfAgent(BaseRoleAgent):
     """狼人角色Agent"""
 
     def __init__(self, model_name):
@@ -52,11 +53,10 @@ class WolfAgent(BasicRoleAgent):
                 # 可以使用模型来过滤掉玩家的注入消息，也可以换一个小模型，实际使用需要考虑对memory加锁，避免interact的时候丢失消息
                 # clean_user_message_prompt = format_prompt(CLEAN_USER_PROMPT, {"user_message": req.message})
                 # req.message = self.llm_caller(clean_user_message_prompt)
-                self.memory.append_history(req.name + ': ' + req.message)
+                self.append_player_message(req.name, req.message)
             else:
                 # 主持人发言
-                self.memory.append_history('主持人: 现在进入第{}天。'.format(str(req.round)))
-                self.memory.append_history('主持人: 每个玩家描述自己的信息。')
+                self.append_discuss_host(req.round)
             self.memory.append_history("---------------------------------------------")
         elif req.status == STATUS_VOTE:  # 投票环节
             self.memory.append_history(f'第{req.round}天。投票信息:{req.name}投了{req.message}')
@@ -96,6 +96,8 @@ class WolfAgent(BasicRoleAgent):
         else:
             raise NotImplementedError
 
+        self.update_state(req)
+
     def interact(self, req=AgentReq) -> AgentResp:
         logger.info("wolf interact: {}".format(req))
         try:
@@ -109,15 +111,23 @@ class WolfAgent(BasicRoleAgent):
                                        "history": "\n".join(self.memory.load_history())
                                       })
                 logger.info("prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_speech(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    kind="discuss",
+                )
                 logger.info("wolf interact result: {}".format(result))
                 return AgentResp(success=True, result=result, errMsg=None)
 
             elif req.status == STATUS_VOTE:
                 self.memory.append_history('主持人: 到了投票的时候了。每个人，请指向你认为可能是狼人的人。')
                 teammates = self.memory.load_variable("teammates")
-                choices = [name for name in req.message.split(",")
+                raw_choices = [name for name in (req.message or "").split(",") if name]
+                choices = [name for name in raw_choices
                           if name != self.memory.load_variable("name") and name not in teammates]  # 排除自己和队友
+                if not choices:
+                    choices = raw_choices
                 self.memory.set_variable("choices", choices)
                 prompt = format_prompt(VOTE_PROMPT, {"name": self.memory.load_variable("name"),
                                                    "teammates": teammates,
@@ -125,7 +135,12 @@ class WolfAgent(BasicRoleAgent):
                                                    "history": "\n".join(self.memory.load_history())
                                                   })
                 logger.info("prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_choice(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    choices=choices,
+                )
                 logger.info("wolf interact result: {}".format(result))
                 return AgentResp(success=True, result=result, errMsg=None)
 
@@ -137,13 +152,18 @@ class WolfAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_speech(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    kind="wolf_speech",
+                )
                 logger.info("wolf speech result: {}".format(result))
                 return AgentResp(success=True, result=result, errMsg=None)
 
             elif req.status == STATUS_SKILL:
                 teammates = self.memory.load_variable("teammates")
-                choices = [name for name in req.message.split(",")
+                choices = [name for name in (req.message or "").split(",")
                           if name != self.memory.load_variable("name") and name not in teammates]  # 排除自己和队友
                 self.memory.set_variable("choices", choices)
                 prompt = format_prompt(KILL_PROMPT, {
@@ -152,7 +172,13 @@ class WolfAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_choice(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    choices=choices,
+                    final_skill_target_from_result=lambda r: r,
+                )
                 logger.info("wolf kill result: {}".format(result))
                 return AgentResp(success=True, result=result, skillTargetPlayer=result, errMsg=None)
 
@@ -164,7 +190,13 @@ class WolfAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("wolf agent sheriff election prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_enum(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    allowed=[ruleset.SHERIFF_RUN, ruleset.SHERIFF_NOT_RUN],
+                    fallback=ruleset.SHERIFF_NOT_RUN,
+                )
                 return AgentResp(success=True, result=result, errMsg=None)
 
             elif req.status == STATUS_SHERIFF_SPEECH:
@@ -175,7 +207,12 @@ class WolfAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("wolf agent sheriff speech prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_speech(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    kind="sheriff_speech",
+                )
                 return AgentResp(success=True, result=result, errMsg=None)
 
             elif req.status == STATUS_SHERIFF_PK:
@@ -186,7 +223,12 @@ class WolfAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("wolf agent sheriff pk prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_speech(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    kind="sheriff_pk",
+                )
                 return AgentResp(success=True, result=result, errMsg=None)
 
             elif req.status == STATUS_SHERIFF_VOTE:
@@ -199,7 +241,12 @@ class WolfAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("wolf agent sheriff vote prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_choice(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    choices=choices,
+                )
                 return AgentResp(success=True, result=result, errMsg=None)
 
             elif req.status == STATUS_SHERIFF_SPEECH_ORDER:
@@ -208,7 +255,13 @@ class WolfAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("wolf agent sheriff speech order prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_enum(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    allowed=[ruleset.SPEECH_ORDER_CW, ruleset.SPEECH_ORDER_CCW],
+                    fallback=ruleset.SPEECH_ORDER_CW,
+                )
                 return AgentResp(success=True, result=result, errMsg=None)
 
             elif req.status == STATUS_SHERIFF:
@@ -223,10 +276,17 @@ class WolfAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("wolf agent sheriff transfer prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_choice(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    choices=choices,
+                    allow_extra=[ruleset.SHERIFF_TEAR],
+                    fallback=ruleset.SHERIFF_TEAR,
+                )
                 return AgentResp(success=True, result=result, errMsg=None)
 
             return AgentResp(success=True, result=None, errMsg=None)
         except Exception as e:
             logger.error("WolfAgent interact failed", exc_info=True)
-            return AgentResp(success=False, result=None, errMsg=str(e))
+            return AgentResp(success=False, result=None, errMsg=str(e))

werewolf/wolf_king/wolf_king_agent.py

@@ -1,17 +1,18 @@
-from agent_build_sdk.model.roles import ROLE_WOLF_KING
+from agent_build_sdk.model.roles import ROLE_WOLF_KING
 from agent_build_sdk.model.werewolf_model import AgentResp, AgentReq, STATUS_START, STATUS_WOLF_SPEECH, \
     STATUS_VOTE_RESULT, STATUS_SKILL, STATUS_SKILL_RESULT, STATUS_NIGHT_INFO, STATUS_DAY, STATUS_DISCUSS, STATUS_VOTE, \
     STATUS_RESULT, STATUS_NIGHT, STATUS_SHERIFF_ELECTION, STATUS_SHERIFF_SPEECH, STATUS_SHERIFF_VOTE, STATUS_SHERIFF, \
     STATUS_SHERIFF_SPEECH_ORDER, STATUS_SHERIFF_PK, STATUS_HUNTER, STATUS_HUNTER_RESULT
 from agent_build_sdk.utils.logger import logger
-from agent_build_sdk.sdk.role_agent import BasicRoleAgent
 from agent_build_sdk.sdk.agent import format_prompt
+from core import ruleset
+from core.base_role_agent import BaseRoleAgent
 from wolf_king.prompt import DESC_PROMPT, VOTE_PROMPT, WOLF_SPEECH_PROMPT, KILL_PROMPT, SHOOT_SKILL_PROMPT, \
     GAME_RULE_PROMPT, CLEAN_USER_PROMPT, SHERIFF_ELECTION_PROMPT, SHERIFF_SPEECH_PROMPT, SHERIFF_VOTE_PROMPT, \
     SHERIFF_SPEECH_ORDER_PROMPT, SHERIFF_TRANSFER_PROMPT
 
 
-class WolfKingAgent(BasicRoleAgent):
+class WolfKingAgent(BaseRoleAgent):
     """狼王角色Agent"""
 
     def __init__(self, model_name):
@@ -54,15 +55,10 @@ class WolfKingAgent(BasicRoleAgent):
             self.memory.append_history(f"主持人：天亮了！昨天晚上的信息是: {req.message}")
         elif req.status == STATUS_DISCUSS:  # 发言环节
             if req.name:
-                # 其他玩家发言
-                # 可以使用模型来过滤掉玩家的注入消息，也可以换一个小模型，实际使用需要考虑对memory加锁，避免interact的时候丢失消息
-                # clean_user_message_prompt = format_prompt(CLEAN_USER_PROMPT, {"user_message": req.message})
-                # req.message = self.llm_caller(clean_user_message_prompt)
-                self.memory.append_history(req.name + ': ' + req.message)
+                self.append_player_message(req.name, req.message)
             else:
                 # 主持人发言
-                self.memory.append_history('主持人: 现在进入第{}天。'.format(str(req.round)))
-                self.memory.append_history('主持人: 每个玩家描述自己的信息。')
+                self.append_discuss_host(req.round)
             self.memory.append_history("---------------------------------------------")
         elif req.status == STATUS_VOTE:  # 投票环节
             self.memory.append_history(f'第{req.round}天。投票信息:{req.name}投了{req.message}')
@@ -102,6 +98,8 @@ class WolfKingAgent(BasicRoleAgent):
         else:
             raise NotImplementedError
 
+        self.update_state(req)
+
     def interact(self, req=AgentReq) -> AgentResp:
         logger.info("wolf king interact: {}".format(req))
         if req.status == STATUS_DISCUSS:
@@ -117,14 +115,19 @@ class WolfKingAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="discuss",
+            )
             logger.info("wolf king interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_VOTE:
             self.memory.append_history('主持人: 到了投票的时候了。每个人，请指向你认为可能是狼人的人。')
             teammates = self.memory.load_variable("teammates")
-            choices = [name for name in req.message.split(",")
+            choices = [name for name in (req.message or "").split(",")
                       if name != self.memory.load_variable("name") and name not in teammates]  # 排除自己和队友
             self.memory.set_variable("choices", choices)
             prompt = format_prompt(VOTE_PROMPT, {"name": self.memory.load_variable("name"),
@@ -133,7 +136,12 @@ class WolfKingAgent(BasicRoleAgent):
                                                "history": "\n".join(self.memory.load_history())
                                               })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             logger.info("wolf king interact result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -145,7 +153,12 @@ class WolfKingAgent(BasicRoleAgent):
                 "history": "\n".join(self.memory.load_history())
             })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind="wolf_speech",
+            )
             logger.info("wolf king speech result: {}".format(result))
             return AgentResp(success=True, result=result, errMsg=None)
 
@@ -156,7 +169,7 @@ class WolfKingAgent(BasicRoleAgent):
                 # 开枪技能：狼王被淘汰时的开枪
                 can_shoot = self.memory.load_variable("can_shoot")
                 if not can_shoot:
-                    return AgentResp(success=True, result="不开枪", errMsg=None)
+                    return AgentResp(success=True, result=ruleset.NO_SHOOT, errMsg=None)
 
                 teammates = self.memory.load_variable("teammates")
                 choices = [name for name in message.replace("请发表最后的遗言", "").split(",")
@@ -169,17 +182,25 @@ class WolfKingAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_choice(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    choices=choices,
+                    allow_extra=[ruleset.NO_SHOOT],
+                    fallback=ruleset.NO_SHOOT,
+                    final_skill_target_from_result=lambda r: None if r == ruleset.NO_SHOOT else r,
+                )
                 logger.info("wolf king shoot skill result: {}".format(result))
 
-                if result != "不开枪":
+                if result != ruleset.NO_SHOOT:
                     self.memory.set_variable("can_shoot", False)
 
-                return AgentResp(success=True, result=result, skillTargetPlayer=None if result == "不开枪" else result, errMsg=None)
+                return AgentResp(success=True, result=result, skillTargetPlayer=None if result == ruleset.NO_SHOOT else result, errMsg=None)
             else:
                 # 击杀技能：狼人夜晚击杀
                 teammates = self.memory.load_variable("teammates")
-                choices = [name for name in message.split(",")
+                choices = [name for name in (message or "").split(",")
                           if name != self.memory.load_variable("name") and name not in teammates]
                 self.memory.set_variable("choices", choices)
 
@@ -190,7 +211,13 @@ class WolfKingAgent(BasicRoleAgent):
                     "history": "\n".join(self.memory.load_history())
                 })
                 logger.info("prompt:" + prompt)
-                result = self.llm_caller(prompt)
+                result = self.decide_choice(
+                    req_status=req.status,
+                    round_no=req.round,
+                    prompt=prompt,
+                    choices=choices,
+                    final_skill_target_from_result=lambda r: r,
+                )
                 logger.info("wolf king kill result: {}".format(result))
                 return AgentResp(success=True, result=result, skillTargetPlayer=result, errMsg=None)
 
@@ -205,7 +232,13 @@ class WolfKingAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SHERIFF_RUN, ruleset.SHERIFF_NOT_RUN],
+                fallback=ruleset.SHERIFF_NOT_RUN,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_SPEECH or req.status == STATUS_SHERIFF_PK:
@@ -219,7 +252,13 @@ class WolfKingAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            kind = "sheriff_pk" if req.status == STATUS_SHERIFF_PK else "sheriff_speech"
+            result = self.decide_speech(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                kind=kind,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_VOTE:
@@ -232,7 +271,12 @@ class WolfKingAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF_SPEECH_ORDER:
@@ -241,7 +285,13 @@ class WolfKingAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_enum(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                allowed=[ruleset.SPEECH_ORDER_CW, ruleset.SPEECH_ORDER_CCW],
+                fallback=ruleset.SPEECH_ORDER_CW,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
 
         elif req.status == STATUS_SHERIFF:
@@ -259,7 +309,14 @@ class WolfKingAgent(BasicRoleAgent):
                                    "history": "\n".join(self.memory.load_history())
                                   })
             logger.info("prompt:" + prompt)
-            result = self.llm_caller(prompt)
+            result = self.decide_choice(
+                req_status=req.status,
+                round_no=req.round,
+                prompt=prompt,
+                choices=choices,
+                allow_extra=[ruleset.SHERIFF_TEAR],
+                fallback=ruleset.SHERIFF_TEAR,
+            )
             return AgentResp(success=True, result=result, errMsg=None)
         else:
             raise NotImplementedError

改造plan.md

@@ -0,0 +1,441 @@
+下面给你一份**“Agent 代码层面升级的具体规划”**，目标是：在不改变比赛要求的输入/输出接口前提下，把你现在的“每个角色各自拼 history + 各自解析文本 + 各自调用 LLM”的方式，升级成**可复用底盘 + 结构化状态 + 强校验输出**。你用 Codex 逐条落地会非常顺手。
+
+---
+
+## 总体原则（确保不影响比赛 IO）
+
+* **对外接口不变**：每个角色仍然实现 `perceive(req) -> None` 和 `interact(req) -> str`，输出仍是比赛要求的“名字/不开枪/…”。
+* **对内全结构化**：内部统一用 `Action` 对象表达决策，再由一个 `ActionRenderer` 生成比赛要求的字符串。
+* **强鲁棒性**：所有 LLM 输出必须“解析 + 校验”；失败则“纠错重试一次”，再失败就“回退策略”，保证永不崩线。
+
+---
+
+## Phase 0：先做“可观测性”和回放（1 天内能落地）
+
+**目的**：你要能量化每次改动的收益，避免“看起来更像人但胜率下降”。
+
+### 0.1 增加统一日志
+
+新增 `werewolf/core/telemetry.py`：
+
+* 记录每次 `interact()`：
+
+  * status、round、候选列表、构建后的 prompt（或 hash）、LLM 原始输出、解析后的 action、是否重试、最终输出
+* 落盘到 `logs/<game_id>/<role>/<round>_<status>.jsonl`
+
+### 0.2 增加 replay runner（离线回放）
+
+新增 `werewolf/tools/replay.py`：
+
+* 输入：一局对战的裁判事件日志（你们自己采集）
+* 逐条喂给 agent（perceive/interact），对比输出合法性与一致性
+* 输出：指标统计（合法率、重试率、fallback 率）
+
+> 这一步会让你后面每次重构都“可控”。
+
+---
+
+## Phase 1：抽象共用底盘（最关键，收益最大）
+
+**目的**：把“清洗输入、拼上下文、调用 LLM、解析输出、校验候选、重试回退”从每个角色里拿走，角色代码只剩策略钩子。
+
+### 1.1 新增核心目录结构
+
+建议新增：
+
+```
+werewolf/core/
+  base_agent.py
+  memory.py
+  sanitizer.py
+  context_builder.py
+  llm_client.py
+  action_schema.py
+  action_parser.py
+  validators.py
+  fallback.py
+  telemetry.py
+```
+
+### 1.2 统一 BaseRoleAgent（替代各角色重复逻辑）
+
+在 `base_agent.py` 中定义：
+
+* `BaseRoleAgent(perceive, interact)` 的通用实现框架
+* 角色只需要实现少量 hook（下面给你最小集）
+
+核心 hook 设计（建议）：
+
+```python
+class BaseRoleAgent(RoleAgent):
+    def on_event(self, event: GameEvent): ...
+    def build_task(self, status, req) -> TaskSpec: ...
+    def decide(self, task: TaskSpec, state: GameState) -> Action: ...
+```
+
+其中：
+
+* `on_event()`：把裁判/玩家消息转成结构化更新（写入 memory + 更新 state）
+* `build_task()`：针对当前 status 生成“任务规格”（候选、约束、输出类型）
+* `decide()`：优先走“程序策略/评分器”，必要时才调用 LLM
+
+### 1.3 Memory 升级：raw_log + summary + facts
+
+`memory.py` 建议定义三层：
+
+* `raw_log`: 原始发言（可限长）
+* `facts`: 结构化事实（投票、死亡、身份声明、查验结果、用药等）
+* `summary`: 每轮自动生成的短摘要（给 LLM 用）
+
+角色间共用同一套结构，区别只是“哪些 facts 对我可见”（例如狼人夜间共谋、女巫夜间信息等）。
+
+### 1.4 Sanitizer 强制启用
+
+`sanitizer.py` 做两件事：
+
+* 对“玩家自由文本”做注入清洗（剥离伪系统指令/规则修改）
+* 对“裁判结构消息”不做清洗（避免误伤）
+
+**落地点**：BaseRoleAgent 在 `perceive()` 里统一清洗后再写 raw_log。
+
+### 1.5 Action Schema：内部结构化动作
+
+`action_schema.py` 统一定义：
+
+* `DiscussAction(text)`
+* `VoteAction(target)`
+* `SkillAction(target | None)`（None = 不开技能）
+* `SheriffRunAction(join: bool)`
+* `SheriffVoteAction(target)`
+* `PassAction()`
+
+以及一个 `render(action, status) -> str`：
+
+* vote/skill 类强制只输出名字或“不开枪”
+* discuss 类输出文本（并做字数限制）
+
+### 1.6 输出解析 + 校验 + 重试 + 回退
+
+`action_parser.py`：把 LLM 输出解析成 Action
+`validators.py`：校验：
+
+* 候选合法性（必须在 choices 内）
+* 格式合法性（只允许一个名字/“不开枪”）
+* 字数限制（发言阶段）
+
+`fallback.py`：兜底策略：
+
+* 投票：选嫌疑分最高或“最近冲票位”
+* 技能：默认不开（除非高置信阈值命中）
+* 上警：默认不上（或按角色策略）
+
+BaseRoleAgent 的决策流程建议统一为：
+
+1. 调用 `decide()` 得到 Action（可先走非 LLM）
+2. 若需要 LLM：构建 prompt → LLM 输出 → parse → validate
+3. 不通过：触发一次“纠错 prompt”重试
+4. 再失败：fallback（永不返回非法输出）
+
+---
+
+## Phase 2：统一“事件解析器”与结构化 GameState（把推理从文本搬到代码）
+
+**目的**：把“谁投谁/谁死了/谁跳身份/谁给了什么查验”这些高价值信息从聊天记录里抽出来，变成可以计算的状态。
+
+### 2.1 定义 GameEvent & EventParser
+
+新增 `werewolf/core/events.py`：
+
+* `GameEvent(type, actor, payload, round, day_night, raw_text)`
+
+写一个 `EventParser`：
+
+* 输入：`req.status + req.name + req.message`
+* 输出：0..n 个 `GameEvent`
+
+事件类型建议最少覆盖：
+
+* `PLAYER_SPEAK`
+* `JUDGE_ANNOUNCE`（天亮/天黑/死亡/进入投票等）
+* `VOTE_RESULT`
+* `SHERIFF_RESULT`
+* `SKILL_RESULT`（对各神职）
+
+你现在很多逻辑靠“字符串包含”，这一步做完就可以逐步替换成结构化字段。
+
+### 2.2 GameState：玩家模型 + 投票矩阵 + 声明跟踪
+
+新增 `werewolf/core/state.py`：
+
+* `players: Dict[name, PlayerModel]`
+
+  * `alive: bool`
+  * `suspicion: float`
+  * `claims: List[Claim]`
+  * `last_votes: List[VoteRecord]`
+* `day: int`, `phase`, `sheriff`
+* `vote_matrix[day][voter] = target`
+* `death_log`
+
+并在 `on_event()` 中做增量更新。
+
+> 到这里，你的 agent 就不再依赖“把所有 history 塞给模型记住”，推理稳定性会立刻上一个台阶。
+
+---
+
+## Phase 3：角色策略层（每个角色只写“差异化”，不写通用 plumbing）
+
+**目的**：每个角色的 `*_agent.py` 变薄，主要是“策略”。
+
+建议每个角色实现：
+
+* `role_policy.py`（纯策略/评分器/阈值）
+* `*_agent.py`（继承 BaseRoleAgent，注册策略与可见信息）
+
+### 3.1 统一评分器接口（强烈建议）
+
+例如：
+
+```python
+class TargetScorer:
+    def score_vote_targets(state, choices) -> List[(name, score, reasons)]
+    def score_skill_targets(state, choices) -> ...
+```
+
+LLM 的作用变成：
+
+* 在 top2/top3 里做选择
+* 生成自然语言发言解释
+  而不是让 LLM 在全候选空间“自由发挥”。
+
+### 3.2 狼人阵营增加“团队共享内存”
+
+你说得对：**跨容器/跨选手的“共享内存”在赛制下不可依赖**。正确的工程思路是把“狼人阵营协同”完全建立在**系统提供的狼人夜间商讨对话**之上：每个狼人 Agent 在各自隔离环境中独立运行，但通过“狼人私聊频道的发言内容”实现一致性。
+
+下面是我给你的**代码层面兼容规划**（专门针对你列出的 i–iv 规则），重点解决两件事：
+
+1. **如何让狼人之间的交流可被可靠解析**（机器可读）
+2. **如何让每个狼人独立地算出同一个刀人目标**（提高一致性，减少平票/随机）
+
+---
+
+## 1) 关键设计：把“狼人商讨”变成可解析的协议
+
+### 1.1 协议目标
+
+狼人夜间商讨阶段，系统会向所有狼人同时发言请求。此时每个狼人需要输出“策略建议”。我们要让这段建议 **既像人类交流**，又包含一个**严格可解析的投票字段**，让其他狼人（以及自己在确认阶段）能从聊天记录中提取结构化信息。
+
+### 1.2 建议的输出格式（强烈建议固定一行）
+
+在狼人商讨发言末尾固定追加一行，例如：
+
+* `WOLF_VOTE=3;ALT=5;CONF=0.72`
+
+含义：
+
+* `WOLF_VOTE`: 我建议刀的首选目标（必填）
+* `ALT`: 备选（可选）
+* `CONF`: 置信度（可选，用于平票时加权）
+
+这行必须满足：
+
+* **唯一出现一次**
+* **严格半角符号**
+* **数字为玩家编号/名字映射后的标准格式**
+
+> 这就是“共享内存”的替代品：**共享对话 + 可解析协议**。
+
+---
+
+## 2) 两阶段一致性策略：建议阶段投票 + 确认阶段复算
+
+赛制是：商讨完后每个狼人还要各自确认刀人目标，若不一致按得票最高；平票随机。
+
+我们要尽量让“各自确认”变得高度一致。方法是让所有狼人使用同一个**确定性共识函数**：
+
+### 2.1 共识函数（每个狼人本地独立计算，但结果尽量一致）
+
+输入：狼人商讨聊天记录中解析出的所有 `WOLF_VOTE`
+输出：本狼人最终确认目标
+
+建议规则（确定性强、容易实现）：
+
+1. 统计每个候选人的票数（从所有狼人发言里解析 `WOLF_VOTE`）
+2. 取票数最高者
+3. 若平票：按以下顺序打破平局（保证每个狼人都做同样选择）
+
+   * 优先选择“自己也投过”的那个（降低分裂概率）
+   * 否则选择**编号最小**（或最大，但必须固定一种）
+4. 最终结果必须在系统给的候选列表内；不在则回退到“候选列表编号最小”
+
+这样即便有人没按协议输出，你也能依赖剩余票形成稳定共识，最大化避免系统“平票随机”。
+
+---
+
+## 3) 你需要落地的代码改造点（wolf / wolf_king）
+
+下面按文件与功能拆分，直接给你可执行的开发任务清单。
+
+---
+
+### 3.1 新增通用解析器：`werewolf/core/wolf_protocol.py`
+
+提供两个核心函数：
+
+1. `extract_wolf_votes(messages) -> List[WolfVote]`
+
+* 从狼人夜间商讨的聊天记录中，解析每条发言末尾的 `WOLF_VOTE=...`
+* 输出结构例如：
+
+  * `WolfVote(sender="2号", vote=3, alt=5, conf=0.72, raw="...")`
+
+2. `choose_kill_target(votes, my_vote, candidates) -> int`
+
+* 实现上面共识函数（票数统计 + 确定性平票规则 + 候选校验回退）
+
+> 这个模块可复用于 wolf 与 wolf_king，保证两者共识逻辑完全一致。
+
+---
+
+### 3.2 狼人 Agent 状态机：显式支持“商讨-确认”两步
+
+在 `werewolf/wolf/wolf_agent.py`（以及狼王 `wolf_king_agent.py`）里做两件事：
+
+#### A) perceive：记录狼人夜聊对话（仅夜间商讨频道）
+
+* 在商讨阶段，把所有狼队可见发言写入 `wolf_chat_log`（独立于全局 history）
+* 注意：你不能依赖跨进程共享，所以必须本地完整记录
+
+#### B) interact：针对两个请求分别输出
+
+你需要识别系统的两个夜间动作请求（名字可能不同，取决于比赛模板 status）：
+
+1. **商讨发言请求（proposal）**：输出策略建议 + 协议行
+
+* 输出内容包括：
+
+  * 简短理由（像真人）
+  * 协议行 `WOLF_VOTE=...;ALT=...;CONF=...`
+
+2. **刀人确认请求（confirm）**：只输出最终目标编号
+
+* 从 `wolf_chat_log` 解析所有狼的投票
+* 用 `choose_kill_target()` 得到目标
+* 输出必须是系统要求的“编号/名字”之一（严格合规）
+
+---
+
+## 4) Prompt 层配合（让 LLM 自然地遵守协议）
+
+你需要在 `werewolf/wolf/prompt.py` 和 `werewolf/wolf_king/prompt.py` 做两类 prompt：
+
+### 4.1 商讨发言 Prompt（重点：协议强制）
+
+核心要求写清楚：
+
+* 发言末尾必须追加协议行（唯一一行）
+* 协议行格式严格，不能多余字符
+* `WOLF_VOTE` 必须来自候选列表（若系统未给候选，则来自存活玩家编号列表）
+
+### 4.2 确认刀人 Prompt（建议尽量不让 LLM 决策）
+
+确认阶段不建议让 LLM “自由选”，而是：
+
+* 代码算出 `final_target`
+* 直接返回字符串（避免模型输出不合规导致系统弃刀）
+
+也就是说：**确认阶段尽量不用 LLM**，这是稳定性最关键的一点。
+
+---
+
+## 5) 容错与赛制对齐（避免“默认放弃刀人”）
+
+赛制 iv 说：若最终没有合规刀人目标则默认放弃。
+
+你的目标应该是：**几乎永远返回合规目标**，只在极端情况下才弃刀。
+
+建议容错链路：
+
+1. `wolf_chat_log` 中能解析到 ≥1 条有效票：按共识函数选
+2. 解析不到票：按本地评分器（嫌疑分最高）选一个候选
+3. 候选列表为空或解析失败：输出一个明显不合规值（触发系统弃刀）——但这应极少发生
+
+> 重点：不要把“弃刀”当常规策略；更多是兜底。
+
+---
+
+## 6) 你可以直接按这个顺序用 Codex 开发（最低风险最高收益）
+
+1. 新增 `core/wolf_protocol.py`（解析 + 共识函数）
+2. 修改 `wolf_agent.py`：增加 `wolf_chat_log`，并在“商讨/确认”两步分别处理
+3. 修改 `wolf/prompt.py`：商讨发言追加协议行
+4. 修改 `wolf_king_agent.py` 同步接入同一协议与共识函数
+5. 做一个离线回放：喂一段狼人夜聊，检查三只狼是否会算出同一 `final_target`
+
+---
+
+## 7) 关键提醒：一致性比“聪明”更重要
+
+在你这个赛制里，狼人阵营胜率很大程度取决于：
+
+* **商讨阶段能否达成一致刀人**
+* **确认阶段是否输出一致目标（减少平票随机）**
+  所以工程上应优先确保“共识函数确定性强 + 输出永远合规”，再去追求更复杂的策略（例如分票、假跳等）。
+
+---
+
+如果你愿意，我可以基于你们现有模板里 wolf 的实际 `status` 名称（例如是否存在 `STATUS_WOLF_DISCUSS`、`STATUS_WOLF_KILL` 等），把上述规划进一步落成**更贴合你代码的改造点位清单**（具体到“在哪个 if 分支里记录哪些字段、在哪个分支里返回什么”），这样你用 Codex 改起来基本是按步骤粘贴调整即可。
+
+
+---
+
+## Phase 4：硬约束与稳定性工程（把“比赛规则”编码进系统）
+
+**目的**：任何时候都保证输出符合裁判期望。
+
+建议做成“规则插件”：
+
+* `werewolf/core/ruleset.py`
+
+  * `max_discuss_chars`
+  * `vote_output_mode: name_only`
+  * `skill_output_mode: name_or_noop`
+  * `candidate_delimiter` 等
+
+所有 agent 共享读取这个 ruleset；以后规则变了，你只改一处。
+
+---
+
+## 交付拆解（你用 Codex 可以按 Ticket 做）
+
+我建议你直接按下面顺序开工，每一条都是可独立 PR 的粒度：
+
+1. **Telemetry + replay runner**（先把可评测跑起来）
+2. **BaseRoleAgent + render/validate/fallback**（先保证“不会输出非法”）
+3. **Sanitizer 强制启用**（对抗鲁棒性）
+4. **Action schema + parser（JSON/模板）**（稳定性）
+5. **EventParser + GameState（先覆盖死亡/投票/警长）**
+6. **Claim/VoteMatrix 模块**
+7. **逐角色迁移：Villager → Hunter → Seer → Witch → Guard → Wolf → WolfKing**
+8. **狼人共享内存（协同）**
+9. **策略评分器：投票/技能统一 top-k + LLM 解释**
+
+---
+
+## 你立刻就能开始改的“最低风险改造”
+
+如果你希望“今天就能把系统变稳”，优先做这三件事（几乎不动策略）：
+
+1. **投票/技能输出强校验 + 不合法重试 + fallback**（避免裁判解析失败）
+2. **启用输入清洗（只清洗玩家发言）**（避免 history 被注入污染）
+3. **raw_log 限长 + summary 替代全量 history**（上下文稳定、成本下降）
+
+---
+
+如果你希望我把这份规划进一步“落到代码骨架级别”，我可以按你们现有的 `RoleAgent/AgentReq/AgentResp` 实际类定义，给你一套可直接粘贴的：
+
+* `BaseRoleAgent` 初始实现
+* `ActionSchema/Parser/Validator/Renderer`
+* 一个角色（比如 villager 或 hunter）的迁移示例（before/after 结构）
+
+你用 Codex 按这个骨架扩展到其他角色，会非常快。