[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-83974":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":8,"htmlUrl":8,"language":9,"languages":8,"totalLinesOfCode":8,"stars":10,"forks":11,"watchers":11,"openIssues":12,"contributorsCount":12,"subscribersCount":12,"size":12,"stars1d":12,"stars7d":13,"stars30d":13,"stars90d":12,"forks30d":12,"starsTrendScore":13,"compositeScore":14,"rankGlobal":8,"rankLanguage":8,"license":15,"archived":16,"fork":16,"defaultBranch":17,"hasWiki":18,"hasPages":16,"topics":19,"createdAt":8,"pushedAt":8,"updatedAt":20,"readmeContent":21,"aiSummary":8,"trendingCount":12,"starSnapshotCount":12,"syncStatus":22,"lastSyncTime":23,"discoverSource":24},83974,"Wolflens","Oven320\u002FWolflens","Oven320",null,"Python",131,1,0,41,62,"MIT License",false,"main",true,[],"2026-06-12 04:01:42","# WolfLens\n\nWolfLens 是一个本地优先的 **Human-in-the-loop Werewolf Review Agent**，面向狼人杀对局复盘、阶段化证据校准和下一步策略建议。\n\nEnglish: 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.\n\n## 一句话介绍\n\nWolfLens 不是自动狼人杀玩家，也不是普通文本总结器，而是一个证据约束、人类可修正、偏好可记忆的狼人杀复盘 Agent 原型。\n\n```text\n自然语言对局文本\n  -> 阶段化事件解析\n  -> visible_events 防偷看未来\n  -> 可视化人工修正\n  -> 玩家 Evidence Bundle\n  -> DeepSeek 双 Agent 复盘建议\n  -> 用户直接修改建议\n  -> ERPM 偏好反思记忆\n```\n\n## WolfLens 是什么\n\nWolfLens 不是完整在线狼人杀平台，也不是只给开发者看的 YAML 分析器。它的 v0.3 目标是：\n\n- 普通用户直接粘贴自然语言对局文本。\n- 系统自动整理玩家、角色、发言、投票、死亡和关键冲突。\n- 信息缺失时继续分析，但明确告诉你缺什么。\n- 区分事实、假设和推测。\n- 先输出一屏关键结论，再允许展开证据链和高级结构化数据。\n\n## Why not another AI Werewolf game?\n\n很多项目关注“让 AI 参与狼人杀”或“让多个 LLM 自动对战”。WolfLens 不试图替代游戏本身，而是分析人类或 AI 对局日志：\n\n- 赛后复盘：主播、玩家和社群管理员可以快速定位关键冲突。\n- 局中辅助分析：只基于公开信息，不读取隐藏身份。\n- AI bot 调试：把对局日志转成 evidence cards、缺失信息和风险速览。\n\n## What makes WolfLens different?\n\n- **compact-first**：默认先展示“一眼结论”，避免用户被完整报告淹没。\n- **missing-info-aware**：缺信息不阻断分析，而是进入假设和可信度提示。\n- **evidence-drilldown**：用户可以展开查看证据链、事件引用和 Agent 摘要。\n- **task-aware routing**：先识别当前局面，再选择查杀表水、对跳、女巫用药、投票压力、夜死预言家等对应分析器。\n- **coach-first UI**：默认只看“一眼复盘、场上玩家状态、选择玩家查看建议、复盘详情”四块。\n- **Theory-of-Mind layer**：不假设所有玩家同等理性；可以为每位玩家设置理解层级，再评估候选策略会如何被误解或接受。\n- **no raw evidence IDs by default**：默认界面显示“P2 强推 P1”这类自然语言标签，内部编号只在证据详情和高级结构化数据中出现。\n- **local-first**：默认本地运行，不上传、不保存用户输入。\n- **not chain-of-thought UI**：详细区展示结构化证据，不展示模型隐藏思维链。\n- **ERPM preference memory**：用户直接改写建议后，可 opt-in 提炼为证据约束的偏好反思卡；后续相似建议只适配表达，不污染身份判断。\n\n## 功能截图占位说明\n\n后续展示材料建议放 4 张截图：\n\n1. 输入页：粘贴自然语言对局文本和板子配置。\n2. 可视化修正页：阶段导航、圆环牌桌、发言流、投票区和右侧编辑面板。\n3. 输出页：个人建议、阵营建议、复盘总结和 ReviewAgent Trace。\n4. 记忆库：历史对局、玩家游戏风格画像、表达偏好 \u002F ERPM。\n\n截图可放在 `docs\u002Fassets\u002F` 或 README 同级资源目录；当前 README 先保留文字占位，避免引用不存在图片。\n\n## 为什么做这个项目\n\n社交推理游戏复盘很容易变成“我感觉 P2 很狼”。WolfLens 希望把感觉拆成证据链：\n\n- P1 什么时候跳身份？\n- P4 是否形成对跳？\n- P2 强推发生在什么信息条件下？\n- 投票是否形成 P1\u002FP4 对立票型？\n- 夜间死亡如何影响前一天的身份声明？\n- 如果第一轮出局另一个人，讨论可能如何变化？\n\n## 三个核心亮点\n\n1. **阶段可见信息约束**：按阶段展示 `visible_events`，避免用未来死亡、后续发言或最终身份评价过去判断。\n2. **玩家证据包 + 双 Agent 建议**：每个玩家先形成独立 Evidence Bundle，再由 ReasoningAgent \u002F AlignmentAgent 生成证据约束且更自然的复盘建议。\n3. **ERPM 偏好反思记忆**：用户可直接改写建议，opt-in 后转成可检索、可撤回、带 evidence guard 的表达偏好。\n\n## 核心功能\n\n- 自然语言输入，支持中文和英文样例。\n- YAML \u002F JSON 高级输入，供开发者复现和调试。\n- 缺失信息检测：blocking \u002F important \u002F optional。\n- Assumption Manager：把缺失信息转成明确分析假设。\n- 规则校验与公共状态追踪。\n- 发言信号分析：对跳、强推、过度防御、视角泄露等。\n- 身份倾向表：狼人嫌疑、好人倾向、神职可能性、置信度。\n- 局面识别：查杀表水、预言家对跳、自己被集火、平票压力、夜死预言家、女巫用药未知等。\n- 冲突框架：把 P1\u002FP4 对跳、票型冲突拆成两侧、中立摇摆和待复查玩家。\n- 玩家状态：展示生存状态、当前立场、动作标签、关注原因和具体追问。\n- 用户视角：支持填写自己的玩家编号、阵营、身份、已知队友\u002F已知身份。\n- ToM 策略评估：为玩家设置 Level 0-3 思考层级，比较候选策略的说服力、暴露风险和误解风险。\n- 好人阵营、狼人阵营和中立复盘视角建议。\n- 定性反事实推演，不伪造精确胜率。\n- ReviewAgent 双 Agent：ReasoningAgent 只做证据约束推理，AlignmentAgent 只做自然狼人杀复盘口吻改写。\n- 用户直接编辑建议：当前局立即显示修正版，opt-in 后写入本地反馈记忆。\n- ERPM：PreferenceDistiller \u002F Retriever \u002F EffectTracker 将建议改写转成可检索、可禁用、可删除的偏好反思卡。\n- 记忆库：历史对局、玩家游戏风格\u002F策略画像、表达偏好 \u002F ERPM。\n- 中英文界面和报告切换。\n- 无 API key 时使用本地 rule-based fallback。\n\n## 快速开始\n\n```bash\npip install -r requirements.txt\nstreamlit run app.py\n```\n\n运行测试：\n\n```bash\npytest\n```\n\n可选 LLM 配置（推荐 DeepSeek OpenAI-compatible endpoint）：\n\n```powershell\n$env:DEEPSEEK_API_KEY=\"你的key\"\n$env:WOLFLENS_LLM_MODEL=\"deepseek-v4-flash\"\n# 可选：推理和改写分开配\n$env:WOLFLENS_REASONING_MODEL=\"deepseek-v4-flash\"\n$env:WOLFLENS_ALIGNMENT_MODEL=\"deepseek-v4-flash\"\n$env:WOLFLENS_ENABLE_REASONING_AGENT=\"0\"  # 默认只启用 Alignment + StyleCritic\n```\n\n没有 API key 也可以使用中文自然语言样例跑出报告。\n\n`DEEPSEEK_API_KEY` 未配置时，WolfLens 会继续使用本地规则与 `StyleRealizer` 输出，不会崩溃。仍保留 OpenAI-compatible 通用配置：`OPENAI_API_KEY` \u002F `OPENAI_BASE_URL` \u002F `OPENAI_MODEL`。\n\nDeepSeek live smoke：\n\n```powershell\npython scripts\u002Fsmoke_deepseek_live.py\n```\n\n脚本会打印 provider、base_url、model、status、latency、response preview 和 usage tokens，不会打印 API key。若未配置 key，会明确显示 `status: no_api_key`。\n\n本地 verified30 LoRA 历史试跑（已暂停训练）：\n\n```powershell\npython tools\u002Ftrain_wolflens_sft.py\n$env:WOLFLENS_MODEL_MODE=\"sft_verified30\"\n$env:WOLFLENS_MODEL_ADAPTER_PATH=\"models\u002Fwolflens_sft_verified30_lora\"\nstreamlit run app.py\n```\n\n`verified30` 已降级为 `legacy_sft_experiment`。训练脚本默认只做校验，`--train` 不会自动启动微调，除非配置显式开启并额外传入 `--force-train`。`base` 模式继续使用现有 OpenAI-compatible 配置。`sft_verified30` 模式只保留为历史 adapter 预览；adapter 缺失或输出 schema 不完整时不会覆盖稳定 pipeline 报告。\n\n## 输入示例：自然语言文本\n\n```text\n6人局，2狼1预言家1女巫2村民。\nP1跳预言家说查杀P4，P4反跳说P1是狼。\nP2强推P1，P5觉得两个预言家都要听。\n第一轮P2和P6投P1，P3和P5投P4，最后P4出局。\n第二晚P1死亡。\n第二天P2说P1死了也不能说明P4一定是狼。\n```\n\n更多示例见：\n\n- `examples\u002Fsample_game_6p_cn.txt`\n- `examples\u002Fsample_game_6p_en.txt`\n- `examples\u002Fsample_game_6p.yaml`\n- `data\u002Fexamples\u002F*.json`：Streamlit“输入样例”的默认来源，只包含用户可见公共对局文本。\n\n## 输出示例：复盘报告摘要\n\n```text\n当前主要冲突：P1、P4 之间的身份对跳。\n当前存活玩家：P2、P3、P5、P6。\n当前死亡玩家：P4、P1。\n\n结论摘要：\n- 本局最大冲突是预言家对跳。\n- P2 的强推行为值得优先复查，但不能直接定罪。\n- P4 出局和 P1 夜间死亡是关键转折。\n- 缺少夜晚行动、最终身份和平票规则，因此结论应保持倾向性。\n```\n\n## v0.3 架构\n\nWolfLens v0.3 使用 **Compact-first Evidence-drilldown Multi-Agent Architecture**：\n\n```text\nUser Text\n  -> Input Normalizer\n  -> GameParserAgent\n  -> MissingInfoAgent\n  -> AssumptionManager\n  -> RuleAgent + StateTracker\n  -> EvidenceBuilder\n  -> SpeechSignalAgent + BeliefTrackerAgent\n  -> StrategistAgents\n  -> CounterfactualSimulator\n  -> CompactReportWriter\n  -> DetailedReportWriter\n  -> MetaReviewerAgent\n  -> UI Renderer\n```\n\n详细说明见 `docs\u002Farchitecture.md`。\n\n## v0.3.3 \u002F v0.4-alpha 架构补充\n\nv0.3.3 把固定 pipeline 升级为 **Task-aware Routing + Theory-of-Mind Evaluation Layer**：\n\n```text\nGame State \u002F Events\n  -> Situation Router\n  -> Analyzer Pool\n  -> Candidate Strategy Generator\n  -> ToM Evaluator\n  -> Risk-Benefit Ranker\n  -> Replay \u002F Next Move Report\n```\n\n这不是多个 LLM 玩家互相模拟辩论。WolfLens 仍以对局任务拆解为主，ToM 作为每位玩家的心智画像评估层，用来回答：\n\n- 这个发言会不会被新手误解成划水？\n- 这个站边会不会被高阶玩家理解为倒钩或冲锋？\n- 当前策略对谁更有说服力，对谁暴露风险更高？\n- 下一次怎么表达更稳？\n\n详细说明见：\n\n- `docs\u002Farchitecture_v0_3_3.md`\n- `docs\u002Ftom_design.md`\n\n## 隐私说明\n\nWolfLens 是 local-first。默认不上传、不保存用户输入。没有 `OPENAI_API_KEY` 时，发言分析和文本解析使用本地规则 fallback。\n\n如果你配置了 OpenAI-compatible endpoint，相关 LLM parser \u002F speech analysis 请求会发送到你配置的服务端点。请根据你的隐私要求决定是否启用。\n\nLLM 使用范围很克制：WolfLens 默认 local-first，无 API key 也可运行；LLM 主要用于自然语言解析和发言信号分析的可选增强。当前 ReportWriter、Strategist、MetaReviewer 仍是规则\u002F模板实现。详细说明见 `docs\u002Fagent_llm_usage.md`。\n\n用户反馈和记忆同样默认本地：只有用户主动保存对局或勾选“记住这种改法”时，才会写入 `data\u002F` 下的本地 JSON。Preference Memory 只影响表达风格，不改变证据、身份判断或玩家画像事实。\n\n## ERPM 亮点\n\nERPM 全称为 **Evidence-grounded Reflective Preference Memory**。它不是 RLHF、DPO 或 fine-tuning，而是一种推理时的人类反馈记忆：\n\n```text\n用户改写建议\n  -> Feedback Log\n  -> Preference Reflection Card\n  -> 后续相似 focus_type 检索\n  -> AlignmentAgent style hints\n  -> StyleCritic \u002F DiversityCritic 检查\n```\n\nERPM 记录 `source_feedback_ids`、`focus_type`、`edit_delta`、`prefer\u002Favoid` 和 `evidence_guard`。偏好只能影响表达、追问方式和断言强度，不能改变 `evidence_ids`、`risk_level`、身份判断或 `visible_events`。\n\n详细设计见：\n\n- `docs\u002FMEMORY_ALIGNMENT_DESIGN.md`\n- `docs\u002FHUMAN_FEEDBACK_ALIGNMENT.md`\n- `docs\u002FEVALUATION_PLAN.md`\n\n## 当前项目材料\n\n- `docs\u002FSTAGE_SUMMARY.md`：阶段性成果和后续路线。\n- `docs\u002FMODULE_HIGHLIGHTS.md`：逐模块亮点。\n- `docs\u002FINNOVATION_AND_LIMITATIONS.md`：已有方法迁移、场景适配和论文边界。\n- `docs\u002FRESUME_AND_INTERVIEW_MATERIALS.md`：简历与面试材料。\n- `docs\u002Fdemo_cases\u002F`：可展示 demo case。\n\n## Roadmap\n\n### v0.1\n\n- 文本\u002FYAML 输入\n- 规则校验\n- 状态追踪\n- 启发式身份概率\n- LLM\u002Ffallback 发言分析\n- 复盘报告生成\n\n### v0.2\n\n- 自然语言输入优先\n- 缺失信息检测\n- 推理假设管理\n- 中英文 UI 和报告\n- 人类可读复盘报告\n- 高级结构化数据折叠展示\n\n### v0.3\n\n- compact-first UI\n- evidence drilldown\n- EvidenceBuilder\n- 修正身份倾向启发式\n- 修正反事实方向\n- 竞品分析和数据集评估调研\n\n### v0.3.1\n\n- Evidence Drilldown UI\n- 默认不暴露 `B-E1-1` \u002F `S-E3-claim` 等内部证据编号\n- 每个结论可展开查看来源事件、原文、解释、影响玩家和不确定性\n- 证据详情是面向用户的可审计证据链，不是模型思维链\n\n### v0.3.2\n\n- 修复 Streamlit nested expander 报错\n- 增加 Agent \u002F LLM 使用说明\n- 增加 WolfLens Textual Parameter Graph\n- 增加架构短板与改进路线分析\n- 增加本地 eval runner 和 v0.3.2 自动评测结果\n\n### v0.3.3 \u002F v0.4-alpha\n\n- 增加 Situation Router，按局面选择分析器\n- 增加 PlayerMindState \u002F ToMEvaluation \u002F RoutingDecision \u002F CandidateStrategy\n- 增加 Candidate Strategy Generator\n- 增加 ToM Engine，支持用户手动设置玩家 reasoning level 0-3\n- UI 展示局面识别、玩家心智画像和候选策略 ToM 评估\n- eval cases 扩展到 10 个，新增局面路由和 ToM 检查\n\n### v0.4-beta\n\n- 主界面改为复盘教练式四区块：一眼复盘、场上玩家状态、选择玩家查看建议、复盘详情\n- 新增 `UserPerspective`，支持用户填写自己的阵营、身份和已知队友\u002F已知身份\n- 新增 `ConflictFrameAgent`、`StanceInterpreterAgent`、`QuestionGeneratorAgent`、`AdviceWriterAgent`、`ConsistencyCriticAgent`\n- 新增 `PlayerPublicState` 和 `PlayerAdvice`\n- 诊断信息降级到底部折叠区\n- eval cases 扩展到 15 个，新增 ConflictFrame、具体追问和用户视角建议检查\n\n### v0.4\n\n- 反事实模拟增强\n- 引入 Monte Carlo rollout\n- 支持 Avalon \u002F Mafia \u002F Blood on the Clocktower 简化规则\n\n### v0.5\n\n- memory reuse\n- strategy library\n- self-play reflection\n- player style modeling\n\n### v0.6\n\n- performance-cost-aware agent routing\n- 小模型\u002F大模型动态选择\n- 多模型聚合与 reviewer consistency check\n\n## Evaluation Plan\n\nWolfLens 后续会结合人工评估和数据集评估：\n\n- Werewolf Among Us：persuasion strategy、vote prediction、evidence extraction。\n- Mafiascum Dataset：deception detection、长论坛局压缩、wolf role ranking。\n- AIWolf logs：规则合法性、对话-行动一致性、agent 行为评估。\n- Idiap WOLF \u002F C2W2D：未来多模态和中文欺骗检测扩展。\n- 自建小评测集：`examples\u002Feval_cases\u002F` 维护短局文本和期望行为，用 pytest 锁住 parser、missing info、compact report 和 counterfactual direction。\n\n当前 v0.3.2 已提供第一版本地自动评测：\n\n```bash\npython scripts\u002Fevaluate_cases.py\n```\n\nv0.4-beta 当前 seed benchmark：\n\n- 15 cases\n- 183 checks\n- 176 passed\n- accuracy 0.962\n- 结果见 `docs\u002Fevaluation_results_v0_4_beta.md` 和 `results\u002Feval_v0_4_beta.json`\n\n结果见 `docs\u002Fevaluation_results_v0_3_2.md`。\n\nERPM 轻量评估指标见 `wolflens\u002Fevaluation_metrics.py`：\n\n- `template_score`\n- `diversity_score`\n- `evidence_preservation_rate`\n- `preference_hit_rate`\n- `overfit_warning_count`\n\n## Agent \u002F LLM Status\n\nWolfLens 默认 local-first。当前 LLM 增强分成两类：\n\n- 解析\u002F发言信号：GameParserAgent、SpeechSignalAgent 等可选调用 OpenAI-compatible endpoint，失败回退规则实现。\n- 输出复盘：ReviewAgent 使用轻量双 Agent。Reasoning Agent 只做证据约束推理，Alignment Agent 只做人类狼人杀话术改写和偏好对齐。\n\n默认推荐 `deepseek-v4-flash`：成本和延迟更适合互动复盘；如果需要更强推理，可把 `WOLFLENS_REASONING_MODEL` 切到高质量模型，同时让 Alignment 继续使用 flash。无 API key 时自动 fallback，不影响主流程。详细矩阵见 `docs\u002Fagent_llm_usage.md`。\n模型比选和官方参数摘要见 `docs\u002Fllm_selection.md`。\n\n### 为什么不是一个大模型直接写报告？\n\nWolfLens 把推理和表达分开：Reasoning Agent 必须引用 evidence_ids、保留不确定性、不得新增事实；Alignment Agent 只能改写表达，不能改变证据和结论强度。这样比“一次性让大模型写完整复盘”更容易校验，也更容易接入用户反馈。\n\n## 当前限制\n\n- WolfLens 不能自动保证“谁一定是狼”，也不应被当作裁判。\n- 自然语言 parser 仍以规则 fallback 为主，复杂局需要人工修正。\n- UI 层已有 visible_events 防线，但完整报告层若要生成严格“当时视角建议”，还需显式阶段化分析入口。\n- ERPM 当前是规则检索，不是向量检索，也不是模型训练。\n- 玩家画像只表示游戏内可观察风格，不能推断现实人格。\n- React 前端仍是原型，Streamlit 是当前真实 pipeline 入口。\n\n## Textual Parameter Graph\n\nWolfLens v0.3.2 增加了 Textual Parameter Graph 文档，用来描述哪些 prompt、规则、模板、schema 和 UI 策略是可优化节点。见 `docs\u002Ftextual_parameter_graph.md`。\n\n## v0.3 Screenshot Guide\n\n适合展示的截图顺序：\n\n1. 输入区：自然语言短局文本。\n2. 一眼结论：3-5 条关键 takeaways。\n3. 玩家风险速览：低 \u002F 中 \u002F 较高 \u002F 信息不足。\n4. 关键证据：只显示最重要 3 条。\n5. 展开证据链：完整时间线、发言信号和高级结构化数据。\n\n## Evidence Drilldown\n\nWolfLens v0.3.1 默认不把内部证据编号暴露给普通用户。你会先看到自然语言标签，例如：\n\n- P1 跳预言家\n- P1 查杀 P4\n- P2 强推 P1\n- P5 建议暂缓站边\n- P4 出局\n\n点击“查看依据”后，才能看到证据详情：内部编号、来源事件、原文、系统解释、影响玩家、支持\u002F削弱的判断、不确定性和相关模块。\n\n这不是模型 chain-of-thought，而是面向用户的可审计证据链。这样既保证默认界面简洁，也保证每个结论可追溯。\n\n## Research Inspiration\n\nWolfLens 受到 Werewolf Arena、AvalonBench、Language Agents with RL for Werewolf、STRATEGIST、ReAct、Reflexion、Generative Agents、AutoGen、CAMEL、AgentVerse、LLM routing 和 explainable AI \u002F human-centered AI 的启发。\n\n这些研究说明社交推理游戏适合研究部分可观测、隐藏身份、欺骗识别、信念更新和战略沟通。WolfLens 的应用重点是把这些研究思想转成普通用户能读懂的复盘工具。\n\n## License\n\nMIT. See `LICENSE`.\n",2,"2026-06-11 04:11:57","CREATED_QUERY"]