谁是卧底（LangChain + LangGraph + Streamlit）

谁是卧底（LangChain + LangGraph + Streamlit）

Datawhale《easy-langent》第八章综合实践。在原有功能的基础上做了一些增强：多智能体「谁是卧底」引擎，带 LangGraph checkpoint + interrupt / Command 人机恢复，以及 Streamlit 本机 Web 界面。

玩法说明

• 人数：4～10 人；界面默认常用规模为 5 人（可自行改为 4～6 人 + 1 名卧底）。
• 卧底数量：
  • 人数 ≤ 6：固定 1 名卧底（与教材一致）。
  • 人数 > 6：可选择 1 或 2 名卧底（双卧底互不知身份，词均为卧底词）。
• 角色：仅 平民 / 卧底，不包含白板。
• 流程：系统出题 → 随机分配角色与词语 → 存活玩家依次发言 → 投票 → 得票最高者淘汰；若平票，在得票最高者中 随机淘汰一名（与教材一致）。
• 胜负：
  • 平民胜：任意时刻 所有卧底均已出局。
  • 卧底胜：场上剩余 恰好 1 名平民且仍有至少 1 名卧底。
• 最大轮次：超过配置的上限仍未结束时，判定 平民方胜利（超时），防止死循环。
• 模式：
  • 观战：人类玩家选「无」，所有发言与投票由 LLM 完成。
  • 入局：在侧栏选择 P1…Pn 之一作为人类；轮到该玩家时，Web 会弹出发言/投票表单，通过 Command(resume=...) 从 checkpoint 恢复执行。

环境变量（标准命名）

复制 .env.example 为 .env按需填写：

Python 与依赖

• Python：3.10+
• 安装：

cd WhoIsTheSpy
pip install -r requirements.txt
​

运行方式

1）Streamlit（推荐，含配置、可视化、人机）

默认在本机启动，浏览器访问终端中提示的地址，一般为：

http://localhost:8501

cd WhoIsTheSpy
streamlit run app.py
​

侧栏可配置：大模型参数、人数与卧底数、人类座位、最大轮次。主界面包含：

• 对局：观战或人类提交发言/投票（checkpoint 恢复）。
• LangGraph 可视化：将拓扑导出为 PNG（get_graph().draw_mermaid_png()，默认写入 .cache/langgraph_topology.png 并在页面加载）+ 本局 节点执行顺序（trace）。
• 日志与状态：文本日志与 checkpoint values 快照。

2）控制台（全 AI 一局）

cd WhoIsTheSpy
python who_is_undercover.py
​

LangGraph 结构说明

节点大致为：

generate_words → assign_roles → begin_speech_round →（循环）speech_turn → finalize_speeches → vote_begin →（循环）vote_turn → judge_result → 条件回到 begin_speech_round 或 show_final_result。

• checkpoint：MemorySaver，按 thread_id 区分对局。
• 人机：在 speech_turn / vote_turn 中对人类玩家调用 interrupt(...)；前端用 Command(resume=...) 恢复。

与课程章节对应关系

• 状态与图：第六章 / 第七章 — TypedDict、StateGraph、START / END、条件边、循环。
• 模型与链：第二章 — ChatPromptTemplate、LCEL prompt | llm | parser。
• 环境变量：第一章 — python-dotenv 与 ChatOpenAI 兼容网关。

目录结构

WhoIsTheSpy/
├── app.py                 # Streamlit 入口
├── who_is_undercover.py   # 控制台全 AI 一局
├── readme.md
├── requirements.txt
├── .env.example
├── .cache/                # 运行后：langgraph_topology.png
└── spy_game/
    ├── config.py
    ├── state_types.py
    ├── llm_factory.py
    ├── utils.py
    ├── engine_nodes.py
    ├── graph_build.py
    └── runner.py
​

文件功能说明