WolfLens 是一个本地优先的 Human-in-the-loop Werewolf Review Agent，面向狼人杀对局复盘、阶段化证据校准和下一步策略建议。

English: WolfLens is a local-first replay analysis tool for social deduction games. Paste a game log, and it will structure events, detect missing information, estimate role beliefs, and generate an interpretable review report.

WolfLens 不是自动狼人杀玩家，也不是普通文本总结器，而是一个证据约束、人类可修正、偏好可记忆的狼人杀复盘 Agent 原型。

自然语言对局文本
  -> 阶段化事件解析
  -> visible_events 防偷看未来
  -> 可视化人工修正
  -> 玩家 Evidence Bundle
  -> DeepSeek 双 Agent 复盘建议
  -> 用户直接修改建议
  -> ERPM 偏好反思记忆

WolfLens 不是完整在线狼人杀平台，也不是只给开发者看的 YAML 分析器。它的 v0.3 目标是：

• 普通用户直接粘贴自然语言对局文本。
• 系统自动整理玩家、角色、发言、投票、死亡和关键冲突。
• 信息缺失时继续分析，但明确告诉你缺什么。
• 区分事实、假设和推测。
• 先输出一屏关键结论，再允许展开证据链和高级结构化数据。

很多项目关注“让 AI 参与狼人杀”或“让多个 LLM 自动对战”。WolfLens 不试图替代游戏本身，而是分析人类或 AI 对局日志：

• 赛后复盘：主播、玩家和社群管理员可以快速定位关键冲突。
• 局中辅助分析：只基于公开信息，不读取隐藏身份。
• AI bot 调试：把对局日志转成 evidence cards、缺失信息和风险速览。

• compact-first：默认先展示“一眼结论”，避免用户被完整报告淹没。
• missing-info-aware：缺信息不阻断分析，而是进入假设和可信度提示。
• evidence-drilldown：用户可以展开查看证据链、事件引用和 Agent 摘要。
• task-aware routing：先识别当前局面，再选择查杀表水、对跳、女巫用药、投票压力、夜死预言家等对应分析器。
• coach-first UI：默认只看“一眼复盘、场上玩家状态、选择玩家查看建议、复盘详情”四块。
• Theory-of-Mind layer：不假设所有玩家同等理性；可以为每位玩家设置理解层级，再评估候选策略会如何被误解或接受。
• no raw evidence IDs by default：默认界面显示“P2 强推 P1”这类自然语言标签，内部编号只在证据详情和高级结构化数据中出现。
• local-first：默认本地运行，不上传、不保存用户输入。
• not chain-of-thought UI：详细区展示结构化证据，不展示模型隐藏思维链。
• ERPM preference memory：用户直接改写建议后，可 opt-in 提炼为证据约束的偏好反思卡；后续相似建议只适配表达，不污染身份判断。

后续展示材料建议放 4 张截图：

1. 输入页：粘贴自然语言对局文本和板子配置。
2. 可视化修正页：阶段导航、圆环牌桌、发言流、投票区和右侧编辑面板。
3. 输出页：个人建议、阵营建议、复盘总结和 ReviewAgent Trace。
4. 记忆库：历史对局、玩家游戏风格画像、表达偏好 / ERPM。

截图可放在 docs/assets/ 或 README 同级资源目录；当前 README 先保留文字占位，避免引用不存在图片。

社交推理游戏复盘很容易变成“我感觉 P2 很狼”。WolfLens 希望把感觉拆成证据链：

• P1 什么时候跳身份？
• P4 是否形成对跳？
• P2 强推发生在什么信息条件下？
• 投票是否形成 P1/P4 对立票型？
• 夜间死亡如何影响前一天的身份声明？
• 如果第一轮出局另一个人，讨论可能如何变化？

1. 阶段可见信息约束：按阶段展示 visible_events，避免用未来死亡、后续发言或最终身份评价过去判断。
2. 玩家证据包 + 双 Agent 建议：每个玩家先形成独立 Evidence Bundle，再由 ReasoningAgent / AlignmentAgent 生成证据约束且更自然的复盘建议。
3. ERPM 偏好反思记忆：用户可直接改写建议，opt-in 后转成可检索、可撤回、带 evidence guard 的表达偏好。

• 自然语言输入，支持中文和英文样例。
• YAML / JSON 高级输入，供开发者复现和调试。
• 缺失信息检测：blocking / important / optional。
• Assumption Manager：把缺失信息转成明确分析假设。
• 规则校验与公共状态追踪。
• 发言信号分析：对跳、强推、过度防御、视角泄露等。
• 身份倾向表：狼人嫌疑、好人倾向、神职可能性、置信度。
• 局面识别：查杀表水、预言家对跳、自己被集火、平票压力、夜死预言家、女巫用药未知等。
• 冲突框架：把 P1/P4 对跳、票型冲突拆成两侧、中立摇摆和待复查玩家。
• 玩家状态：展示生存状态、当前立场、动作标签、关注原因和具体追问。
• 用户视角：支持填写自己的玩家编号、阵营、身份、已知队友/已知身份。
• ToM 策略评估：为玩家设置 Level 0-3 思考层级，比较候选策略的说服力、暴露风险和误解风险。
• 好人阵营、狼人阵营和中立复盘视角建议。
• 定性反事实推演，不伪造精确胜率。
• ReviewAgent 双 Agent：ReasoningAgent 只做证据约束推理，AlignmentAgent 只做自然狼人杀复盘口吻改写。
• 用户直接编辑建议：当前局立即显示修正版，opt-in 后写入本地反馈记忆。
• ERPM：PreferenceDistiller / Retriever / EffectTracker 将建议改写转成可检索、可禁用、可删除的偏好反思卡。
• 记忆库：历史对局、玩家游戏风格/策略画像、表达偏好 / ERPM。
• 中英文界面和报告切换。
• 无 API key 时使用本地 rule-based fallback。

pip install -r requirements.txt
streamlit run app.py

运行测试：

pytest

可选 LLM 配置（推荐 DeepSeek OpenAI-compatible endpoint）：

$env:DEEPSEEK_API_KEY="你的key"
$env:WOLFLENS_LLM_MODEL="deepseek-v4-flash"
# 可选：推理和改写分开配
$env:WOLFLENS_REASONING_MODEL="deepseek-v4-flash"
$env:WOLFLENS_ALIGNMENT_MODEL="deepseek-v4-flash"
$env:WOLFLENS_ENABLE_REASONING_AGENT="0"  # 默认只启用 Alignment + StyleCritic

没有 API key 也可以使用中文自然语言样例跑出报告。

DEEPSEEK_API_KEY 未配置时，WolfLens 会继续使用本地规则与 StyleRealizer 输出，不会崩溃。仍保留 OpenAI-compatible 通用配置：OPENAI_API_KEY / OPENAI_BASE_URL / OPENAI_MODEL。

DeepSeek live smoke：

python scripts/smoke_deepseek_live.py

脚本会打印 provider、base_url、model、status、latency、response preview 和 usage tokens，不会打印 API key。若未配置 key，会明确显示 status: no_api_key。

本地 verified30 LoRA 历史试跑（已暂停训练）：

python tools/train_wolflens_sft.py
$env:WOLFLENS_MODEL_MODE="sft_verified30"
$env:WOLFLENS_MODEL_ADAPTER_PATH="models/wolflens_sft_verified30_lora"
streamlit run app.py

verified30 已降级为 legacy_sft_experiment。训练脚本默认只做校验，--train 不会自动启动微调，除非配置显式开启并额外传入 --force-train。base 模式继续使用现有 OpenAI-compatible 配置。sft_verified30 模式只保留为历史 adapter 预览；adapter 缺失或输出 schema 不完整时不会覆盖稳定 pipeline 报告。

6人局，2狼1预言家1女巫2村民。
P1跳预言家说查杀P4，P4反跳说P1是狼。
P2强推P1，P5觉得两个预言家都要听。
第一轮P2和P6投P1，P3和P5投P4，最后P4出局。
第二晚P1死亡。
第二天P2说P1死了也不能说明P4一定是狼。

更多示例见：

• examples/sample_game_6p_cn.txt
• examples/sample_game_6p_en.txt
• examples/sample_game_6p.yaml
• data/examples/*.json：Streamlit“输入样例”的默认来源，只包含用户可见公共对局文本。

当前主要冲突：P1、P4 之间的身份对跳。
当前存活玩家：P2、P3、P5、P6。
当前死亡玩家：P4、P1。

结论摘要：
- 本局最大冲突是预言家对跳。
- P2 的强推行为值得优先复查，但不能直接定罪。
- P4 出局和 P1 夜间死亡是关键转折。
- 缺少夜晚行动、最终身份和平票规则，因此结论应保持倾向性。

WolfLens v0.3 使用 Compact-first Evidence-drilldown Multi-Agent Architecture：

User Text
  -> Input Normalizer
  -> GameParserAgent
  -> MissingInfoAgent
  -> AssumptionManager
  -> RuleAgent + StateTracker
  -> EvidenceBuilder
  -> SpeechSignalAgent + BeliefTrackerAgent
  -> StrategistAgents
  -> CounterfactualSimulator
  -> CompactReportWriter
  -> DetailedReportWriter
  -> MetaReviewerAgent
  -> UI Renderer

详细说明见 docs/architecture.md。

v0.3.3 把固定 pipeline 升级为 Task-aware Routing + Theory-of-Mind Evaluation Layer：

Game State / Events
  -> Situation Router
  -> Analyzer Pool
  -> Candidate Strategy Generator
  -> ToM Evaluator
  -> Risk-Benefit Ranker
  -> Replay / Next Move Report

这不是多个 LLM 玩家互相模拟辩论。WolfLens 仍以对局任务拆解为主，ToM 作为每位玩家的心智画像评估层，用来回答：

• 这个发言会不会被新手误解成划水？
• 这个站边会不会被高阶玩家理解为倒钩或冲锋？
• 当前策略对谁更有说服力，对谁暴露风险更高？
• 下一次怎么表达更稳？

详细说明见：

• docs/architecture_v0_3_3.md
• docs/tom_design.md

WolfLens 是 local-first。默认不上传、不保存用户输入。没有 OPENAI_API_KEY 时，发言分析和文本解析使用本地规则 fallback。

如果你配置了 OpenAI-compatible endpoint，相关 LLM parser / speech analysis 请求会发送到你配置的服务端点。请根据你的隐私要求决定是否启用。

LLM 使用范围很克制：WolfLens 默认 local-first，无 API key 也可运行；LLM 主要用于自然语言解析和发言信号分析的可选增强。当前 ReportWriter、Strategist、MetaReviewer 仍是规则/模板实现。详细说明见 docs/agent_llm_usage.md。

用户反馈和记忆同样默认本地：只有用户主动保存对局或勾选“记住这种改法”时，才会写入 data/ 下的本地 JSON。Preference Memory 只影响表达风格，不改变证据、身份判断或玩家画像事实。

ERPM 全称为 Evidence-grounded Reflective Preference Memory。它不是 RLHF、DPO 或 fine-tuning，而是一种推理时的人类反馈记忆：

用户改写建议
  -> Feedback Log
  -> Preference Reflection Card
  -> 后续相似 focus_type 检索
  -> AlignmentAgent style hints
  -> StyleCritic / DiversityCritic 检查

ERPM 记录 source_feedback_ids、focus_type、edit_delta、prefer/avoid 和 evidence_guard。偏好只能影响表达、追问方式和断言强度，不能改变 evidence_ids、risk_level、身份判断或 visible_events。

详细设计见：

• docs/MEMORY_ALIGNMENT_DESIGN.md
• docs/HUMAN_FEEDBACK_ALIGNMENT.md
• docs/EVALUATION_PLAN.md

• docs/STAGE_SUMMARY.md：阶段性成果和后续路线。
• docs/MODULE_HIGHLIGHTS.md：逐模块亮点。
• docs/INNOVATION_AND_LIMITATIONS.md：已有方法迁移、场景适配和论文边界。
• docs/RESUME_AND_INTERVIEW_MATERIALS.md：简历与面试材料。
• docs/demo_cases/：可展示 demo case。

• 文本/YAML 输入
• 规则校验
• 状态追踪
• 启发式身份概率
• LLM/fallback 发言分析
• 复盘报告生成

• 自然语言输入优先
• 缺失信息检测
• 推理假设管理
• 中英文 UI 和报告
• 人类可读复盘报告
• 高级结构化数据折叠展示

• compact-first UI
• evidence drilldown
• EvidenceBuilder
• 修正身份倾向启发式
• 修正反事实方向
• 竞品分析和数据集评估调研

• Evidence Drilldown UI
• 默认不暴露 B-E1-1 / S-E3-claim 等内部证据编号
• 每个结论可展开查看来源事件、原文、解释、影响玩家和不确定性
• 证据详情是面向用户的可审计证据链，不是模型思维链

• 修复 Streamlit nested expander 报错
• 增加 Agent / LLM 使用说明
• 增加 WolfLens Textual Parameter Graph
• 增加架构短板与改进路线分析
• 增加本地 eval runner 和 v0.3.2 自动评测结果

• 增加 Situation Router，按局面选择分析器
• 增加 PlayerMindState / ToMEvaluation / RoutingDecision / CandidateStrategy
• 增加 Candidate Strategy Generator
• 增加 ToM Engine，支持用户手动设置玩家 reasoning level 0-3
• UI 展示局面识别、玩家心智画像和候选策略 ToM 评估
• eval cases 扩展到 10 个，新增局面路由和 ToM 检查

• 主界面改为复盘教练式四区块：一眼复盘、场上玩家状态、选择玩家查看建议、复盘详情
• 新增 UserPerspective，支持用户填写自己的阵营、身份和已知队友/已知身份
• 新增 ConflictFrameAgent、StanceInterpreterAgent、QuestionGeneratorAgent、AdviceWriterAgent、ConsistencyCriticAgent
• 新增 PlayerPublicState 和 PlayerAdvice
• 诊断信息降级到底部折叠区
• eval cases 扩展到 15 个，新增 ConflictFrame、具体追问和用户视角建议检查

• 反事实模拟增强
• 引入 Monte Carlo rollout
• 支持 Avalon / Mafia / Blood on the Clocktower 简化规则

• memory reuse
• strategy library
• self-play reflection
• player style modeling

• performance-cost-aware agent routing
• 小模型/大模型动态选择
• 多模型聚合与 reviewer consistency check

WolfLens 后续会结合人工评估和数据集评估：

• Werewolf Among Us：persuasion strategy、vote prediction、evidence extraction。
• Mafiascum Dataset：deception detection、长论坛局压缩、wolf role ranking。
• AIWolf logs：规则合法性、对话-行动一致性、agent 行为评估。
• Idiap WOLF / C2W2D：未来多模态和中文欺骗检测扩展。
• 自建小评测集：examples/eval_cases/ 维护短局文本和期望行为，用 pytest 锁住 parser、missing info、compact report 和 counterfactual direction。

当前 v0.3.2 已提供第一版本地自动评测：

python scripts/evaluate_cases.py

v0.4-beta 当前 seed benchmark：

• 15 cases
• 183 checks
• 176 passed
• accuracy 0.962
• 结果见 docs/evaluation_results_v0_4_beta.md 和 results/eval_v0_4_beta.json

结果见 docs/evaluation_results_v0_3_2.md。

ERPM 轻量评估指标见 wolflens/evaluation_metrics.py：

• template_score
• diversity_score
• evidence_preservation_rate
• preference_hit_rate
• overfit_warning_count

WolfLens 默认 local-first。当前 LLM 增强分成两类：

• 解析/发言信号：GameParserAgent、SpeechSignalAgent 等可选调用 OpenAI-compatible endpoint，失败回退规则实现。
• 输出复盘：ReviewAgent 使用轻量双 Agent。Reasoning Agent 只做证据约束推理，Alignment Agent 只做人类狼人杀话术改写和偏好对齐。

默认推荐 deepseek-v4-flash：成本和延迟更适合互动复盘；如果需要更强推理，可把 WOLFLENS_REASONING_MODEL 切到高质量模型，同时让 Alignment 继续使用 flash。无 API key 时自动 fallback，不影响主流程。详细矩阵见 docs/agent_llm_usage.md。 模型比选和官方参数摘要见 docs/llm_selection.md。

WolfLens 把推理和表达分开：Reasoning Agent 必须引用 evidence_ids、保留不确定性、不得新增事实；Alignment Agent 只能改写表达，不能改变证据和结论强度。这样比“一次性让大模型写完整复盘”更容易校验，也更容易接入用户反馈。

• WolfLens 不能自动保证“谁一定是狼”，也不应被当作裁判。
• 自然语言 parser 仍以规则 fallback 为主，复杂局需要人工修正。
• UI 层已有 visible_events 防线，但完整报告层若要生成严格“当时视角建议”，还需显式阶段化分析入口。
• ERPM 当前是规则检索，不是向量检索，也不是模型训练。
• 玩家画像只表示游戏内可观察风格，不能推断现实人格。
• React 前端仍是原型，Streamlit 是当前真实 pipeline 入口。

WolfLens v0.3.2 增加了 Textual Parameter Graph 文档，用来描述哪些 prompt、规则、模板、schema 和 UI 策略是可优化节点。见 docs/textual_parameter_graph.md。

适合展示的截图顺序：

1. 输入区：自然语言短局文本。
2. 一眼结论：3-5 条关键 takeaways。
3. 玩家风险速览：低 / 中 / 较高 / 信息不足。
4. 关键证据：只显示最重要 3 条。
5. 展开证据链：完整时间线、发言信号和高级结构化数据。

WolfLens v0.3.1 默认不把内部证据编号暴露给普通用户。你会先看到自然语言标签，例如：

• P1 跳预言家
• P1 查杀 P4
• P2 强推 P1
• P5 建议暂缓站边
• P4 出局

点击“查看依据”后，才能看到证据详情：内部编号、来源事件、原文、系统解释、影响玩家、支持/削弱的判断、不确定性和相关模块。

这不是模型 chain-of-thought，而是面向用户的可审计证据链。这样既保证默认界面简洁，也保证每个结论可追溯。

WolfLens 受到 Werewolf Arena、AvalonBench、Language Agents with RL for Werewolf、STRATEGIST、ReAct、Reflexion、Generative Agents、AutoGen、CAMEL、AgentVerse、LLM routing 和 explainable AI / human-centered AI 的启发。

这些研究说明社交推理游戏适合研究部分可观测、隐藏身份、欺骗识别、信念更新和战略沟通。WolfLens 的应用重点是把这些研究思想转成普通用户能读懂的复盘工具。

MIT. See LICENSE.