OpenViking 狼人杀多 Agent 演示完整指南一条命令拉起裁判与 6 名 AI 玩家【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking想在本地用一条命令拉起「1 个裁判 6 个 AI 玩家」看它们在共享群聊里按固定顺序轮流行动、各自记着私密小本子的狼人杀对局吗OpenViking 的狼人杀 Demobot/demo/werewolf/把多 Agent 群聊协作做成了一个可观察的最小闭环god 裁判和 6 个玩家都是独立的 channel bot各自拥有工作目录与GAME.md私有状态文件整局游戏靠消息路由循环驱动、靠文件系统传递私密状态。读完这篇指南你将能够用一条命令在本地跑通完整对局并用浏览器按钮驱动开局、连跑、停止说清楚每条消息如何在 god 与玩家之间串行流转、最终如何落到结算切换到真人混局模式顶替一个玩家席位参与游戏对局结束后核对会话归档、回放状态与排行榜并让 Agent 通过/remember逐局积累经验对照自救手册排掉常见故障并把「裁判 Agent 文件状态总线 路由循环」范式迁移到别的多角色协作场景。先建立心智模型三层服务与六个文件这一节解决「这个 Demo 到底由什么组成」的问题帮你把后面的启动与排障都挂在同一张地图上。整套服务分三层从下到上依次是层默认地址职责OpenViking 服务127.0.0.1:1933记忆存取与 Agent 能力底座Vikingbot 网关内嵌于 OpenViking 进程--with-bot --bot-port 18790暴露 HTTP API把消息投递给不同的bot_api类型 channel Agent狼人杀 UI 服务127.0.0.1:1995由 werewolf_server.py 提供消费网关接口并驱动整个对局路由Vikingbot 的所有对外接口统一挂在/bot/v1前缀下见 openapi.pyDemo 真正依赖的只有两个{vikingbot_url}/bot/v1/health健康检查和{vikingbot_url}/bot/v1/chat/channel向指定 channel 发消息并等待回复后者由 werewolf_server.py 中的send_to_channel封装调用。目录内六个核心文件的分工如下文件职责start_werewolf_demo.py一键启动补全配置、准备工作目录、拉起并守护两个服务werewolf_server.py对局服务端消息路由循环 FastAPI Web UI 后端werewolfUI.html前端单页游戏控制、记忆浏览、排行榜、回放SOUL-god.md裁判god角色规则约 300 行完整对局规则SOUL-player.md玩家角色规则与分身份行动指南Cubic_11_1.010_R.ttf/GeistPixel-Square.woff2页面使用的中文 / 像素风格字体一条消息的主链路可以压缩成一句话你在页面上点按钮 → UI 服务经/bot/v1/chat/channel把消息发给 god → god 的回复按座位号广播给玩家 → 玩家回复被汇总结论再送回 god → 游戏进度写进GAME.md/GAME_RECORD.md整个对局就靠这个循环推进。一键启动命令本地跑起来之前先查三件事这一节解决「怎么最省事地把它跑起来」同时把两个最容易翻车的配置坑提前说清。启动前你只需要三样东西python建议 3.10依赖httpx、fastapi、typer、uvicorn、loguruopenviking-server命令可用一份JSON 格式的配置文件README 示例为~/.openviking/ov.conf。⚠️ 配置文件必须是 JSON一键脚本里的load_json_config直接json.loadYAML 会当场报错werewolf_server.py 的load_config同样只认 JSON。⚠️ README 示例命令总是显式传--config ~/.openviking/ov.conf但两个脚本源码里的默认路径都是~/.openviking/ov-multi.conf。要么显式指定路径要么把配置放到默认位置别两边都猜。在bot/demo/werewolf/目录下执行python start_werewolf_demo.py --config ~/.openviking/ov.conf不传任何参数时脚本使用的默认值如下其中bot与storage是配置文件里最少要有的两级结构缺storage.workspace时脚本会自动补默认值并回写参数默认值含义UI 端口1995狼人杀 Web UI 端口OpenViking host127.0.0.1OpenViking 服务监听地址OpenViking port1933OpenViking 服务端口Vikingbot URLhttp://localhost:18790Vikingbot 网关地址game modeall_agents全 AI 模式game iddefault对局 IDconfig~/.openviking/ov-multi.conf配置路径示例命令会显式覆盖startup timeout30.0秒网关健康检查超时时间常用的可选参数组合python start_werewolf_demo.py \ --config ~/.openviking/ov.conf \ --ui-port 1995 \ --game-mode all_agents \ --smart-buttons--game-modeall_agents全 AI或human_player保留一个真人席位human--smart-buttons开启前端「智能按钮显示」按钮按游戏状态动态显隐--server-host、--server-port、--vikingbot-url、--game-id、--startup-timeout微调运行环境。一键脚本在背后做了什么这一节解决「那条命令背后到底替你干了什么」共五个动作每步都先说做了什么、再说为什么。校验资源validate_assets确认SOUL-god.md、SOUL-player.md、werewolf_server.py都在。先检查再动手避免文件缺失时出现「半启动」状态。注入并回写 channel 配置ensure_werewolf_channels清掉旧的 demo channel再注入god、player_1~player_6共 7 个bot_apichannel随后json.dump回写配置文件缩进 2、ensure_asciiFalse。先清后注是为了防止重复启动时配置里攒出重复 channel。设置沙箱边界ensure_sandbox把bot.sandbox.mode设为per-channel并将 god 的工作目录限制到{workspace}/bot。裁判只需要读写自己的对局记录收紧权限后它碰不到其他玩家的文件。补齐存储路径resolve_workspace缺storage.workspace时自动填默认值~/.openviking/data并回写保证后续所有 Agent 工作目录、对局档案落在同一棵树下。准备 Agent 工作目录prepare_workspace在{workspace}/bot/workspace/下创建bot_api__god、bot_api__player_1…bot_api__player_6七个目录god 拷入改名为SOUL.md的SOUL-god.md每个玩家拷入SOUL-player.md——每个 Agent 启动时从自己的工作目录读取「我是谁」。之后脚本启动openviking-server --with-bot以 1 秒间隔轮询{vikingbot_url}/bot/v1/healthwait_for_health默认 30 秒超时健康检查通过后才启动 UI 服务——这避免了 UI 服务调用网关时网关还没就绪。最后它守护两个子进程任一退出则终止另一个CtrlC 时先发SIGTERM5 秒未退再SIGKILL不留孤儿进程。启动后打开配置文件可以直接核对注入结果关键片段长这样player_2/player_3与player_1同构player_4/5/6只有ov_tools_enable: false{ bot: { channels: [ { type: bot_api, id: god, enabled: true, ov_tools_enable: false }, { type: bot_api, id: player_1, enabled: true, profile_user_list: [player_2, player_3, player_4, player_5, player_6], memory_user: player_1 } ], sandbox: { mode: per-channel, restrictWorkspaces: { bot_api__god: {workspace}/bot } } } }设计意图写在配置里player_1/2/3互相开放画像互看profile_user_list并各持独立记忆memory_user用来演示 Agent 基于「对其他玩家的画像记忆」做推理god与player_4/5/6关闭ov_tools_enable不接触不必要的工具。手动挡调试把两个服务拆开跑这一节解决「我想单独调其中一个服务」的问题。先记住一个前提手动方式要求配置里已经包含全部 7 个 demo channel——这正是建议你先跑一次一键脚本的原因channel 注入与回写都是它代劳的。先起 OpenViking内嵌 Vikingbot 网关openviking-server \ --config ~/.openviking/ov.conf \ --host 127.0.0.1 \ --port 1933 \ --with-bot \ --bot-port 18790--with-bot让 OpenViking 进程同时挂载 Vikingbot 网关--bot-port决定网关端口。用http://localhost:18790/bot/v1/health确认网关就绪。再起狼人杀 UI 服务python werewolf_server.py \ --config ~/.openviking/ov.conf \ --port 1995 \ --game-mode all_agents基于 Typer 定义参数还支持短参-p/--port、-c/--config、-m/--game-mode、-s/--smart-buttons以及--vikingbot-url、--game-id。⚠️ 手动启动时它还会读运行时状态文件RUNTIME_STATE.json位于 storage 的bot/workspace/werewolf/下如果之前以human_player模式跑过即使命令行写的是all_agents服务也会自动恢复为human_player。此外服务启动时会加载最近一次会话并复用其 session id保证重启后历史可衔接。与一键启动的差异一句话总结channel 注入、沙箱设置、工作目录准备、健康检查等待、进程守护这五件事手动模式下全在你自己身上。页面操作手册每个按钮背后都是哪个接口这一节解决「页面上看到的东西分别对应后端什么」让你排障和二次开发时有据可查。启动后访问地址说明http://localhost:1995/主页面由 werewolfUI.html 渲染http://localhost:1995/test测试页服务端加载同目录可选的test_server.htmlhttp://localhost:1995/debug调试页加载可选的debug.html/test与/debug在对应 HTML 不存在时返回空页面——当前仓库只随附了主页面文件实战以/为准。顶部四个导航页各自的数据来源导航对应接口作用游戏—主对局页记忆GET /api/openviking/tree、GET /api/openviking/file读取 storage 下viking/default/agent与viking/default/user两棵目录树并查看文件内容排行榜GET /api/leaderboard累计战绩与胜率曲线回放/api/conversations、/api/conversation/{session_id}、/api/replay-state/{session_id}、/api/bot-sessions按历史会话回放对局游戏页顶部控制按钮与后端 API 的完整映射页面元素对应接口作用开始游戏POST /api/start发送「开始」指令进入当前局流程继续POST /api/continue暂停态下催促 god 继续本局自动N局旁边输入框填局数POST /api/auto-run开启/关闭连续跑局前端以enabledtrue, modefixed, target_gamesN提交后端另支持modeinfinite无限连跑停止游戏POST /api/stop停止当前路由流程并关闭自动连跑初始化游戏 / 重新开始POST /api/restart强制新建 session 并重新初始化新局前端刷新的三个状态接口GET /api/status返回running、game_mode、waiting_for_human、auto_run_*、completed_games等字段是智能按钮与连跑展示的数据源GET /api/messages完整聊天历史GET /api/players逐个读取各玩家GAME.md的「身份」字段生成座位信息。顶部「模式」下拉框会写入start/restart请求的game_mode字段all_agents即全 AIhuman_player时后端会从玩家列表末尾去掉最后一个 botplayer_6追加专用 channelhumanbuild_channels_for_game_mode并自动创建{storage}/bot/workspace/human/GAME.md。⚠️模式只在「开始」或「重启」动作里生效apply_game_mode_to_state只在这两个入口被调用光切下拉框不会改变正在跑的局。⚠️human_player模式的对局不计入排行榜save_game_to_leaderboard_from_record对该模式直接返回skipped理由是真人操作不具备可复现性。切换为human_player并执行开始/重启后页面会出现「真实玩家」区域按钮是否可点取决于后端状态waiting_for_humangod 是否正等待human的回合页面元素对应接口作用只发给 godPOST /api/human/sendtargetgod真人回复作为私密回执单独送回 god不广播给其他玩家发给全员POST /api/human/sendtargetall内容公开广播给所有其他玩家含 bot同时写入公开消息历史查看 GAME.mdGET /api/human/game-mdPOST /api/human/game-md可改写读取/修改真人玩家的私有GAME.md这套「私密操作走GAME.md、公开内容才发群」的约定贯穿整个 SOUL 规则human是正常玩家位必须像其他玩家一样纳入固定顺序与昼夜流程但查验结果、用药、刀人目标这类敏感信息只能写入human/GAME.md。以--smart-buttons启动时前端轮询GET /api/status并按状态调整按钮runningtrue时隐藏「开始/继续」game_endedtrue时显示「重新开始」waiting_for_humantrue时启用真人输入区。该功能默认关闭不开不影响任何对局逻辑只是按钮恒定显示。黑盒拆解一条消息如何被路由成一整局这一节解决「按钮点下去之后后端到底怎么把一局游戏跑完」先看状态再看循环最后看容错。GameState是全局共享状态 dataclass核心字段分组如下running/router_task路由循环是否在跑及其 asyncio 任务句柄channels当前局参与名单随模式变化messages/human_messages公开消息流与真人私聊流session_id每局唯一的会话标识game_ended、completed_games结束标记与累计完成局数供 auto-run 判定pending_replies、waiting_for_human、human_player_message真人回合的等待与投递auto_run_*系列自动连跑配置与计数。对局推进遵循「单飞」原则POST /api/start、/api/continue、/api/restart都会先stop_router_task取消旧循环再以不同的初始消息启动新循环避免并发导致流程混乱。三条入口的核心差异只有初始消息开始开始继续继续本局游戏用于 god 上次回复停留在「等待指令/初始化完成」等状态重新开始先生成新 session、归档旧会话与回放状态再由build_restart_message拼一段带完整玩家名单与各GAME.md路径的建局消息发给 god要求它初始化新局后等待「开始」指令。路由主循环message_router_loop是整场对局的引擎单轮流程发消息给当前说话者通常是 god调用send_to_channel且need_replyTrue同步等待 Agent 回复记录回复追加进messages并落盘为会话文件解析 提及parse_mentions用正则\s*(\w)提取 god 回复中所有被点名的玩家 id「一次只能 一个玩家」由 SOUL 规则约束按座位号广播broadcast_to_players把 god 的发言并发发给所有玩家——被的玩家need_replyTrue必须回复其余玩家need_replyFalse只接收且发送者前缀带座位号如3号广播玩家回复每个有回复的玩家其发言再以need_replyFalse广播给除自己外的所有玩家让全员听到本轮发言汇总结论回传 godbuild_message_for_god把各玩家回复拼成「座位号内容」格式送回 god进入下一轮由 god 再决定 谁、是否进入下一阶段保护上限循环最多 1000 轮max_loops到达即强制停止。容错机制有三处专治「LLM 不按剧本走」无有效 的回推游戏未结束但 god 没 任何玩家时系统以admin_fallback_no_mention身份回推提示「你上个回复没有任何玩家……继续一个玩家进行」最多重试 2 次god_no_mention_retry_count后终止循环等待态识别god 回复命中「初始化完成/等待开始/等待指令/等待继续」等标记is_waiting_like_reply时判定建局完毕主动 break 等待下一次开始指令非法提及直接收车god 到不在名单里的 channel 时循环直接结束不再空转。公开域与私密域保密信息为什么不会泄漏这一节解决「多 Agent 同局时私密信息怎么隔离」并把安全设计与测试佐证一并交代。Agent 之间靠两条通道协作边界划得很死通道载体允许出现的内容公开域群聊消息messages公开的日夜发言、表态、投票私密域各自工作目录里的状态文件查验结果、用药、刀人目标等一切需保密信息各角色的状态文件与写入约束角色文件内容god{storage}/bot/workspace/bot_api__god/GAME_RECORD.md全局进度表游戏状态、轮次、玩家身份表、胜负「游戏状态/游戏结果/游戏时间/玩家状态」均有约定格式player_Nbot_api__player_N/GAME.md身份、夜间技能目标、查验/用药结果等私有信息human{storage}/bot/workspace/human/GAME.md真人席位状态模式启用时自动创建页面可直接编辑硬约束写在两份 SOUL 文件里SOUL-god.md 要求黑夜与白天所有环节按开局固定的玩家顺序逐个点名、串行推进第一晚的死亡结果在警长竞选结束前不写入任何玩家文件的「存活状态」防止提前泄密并给出 6/9/12 人局身份配置与胜负判定狼人胜利所有神职或所有平民出局。SOUL-player.md 则约束玩家只能基于「群内公开信息 裁判明确告知 自己GAME.md」行动严禁上帝视角。服务端还暴露/data/{path}文件浏览与/api/game-file/{channel_id}/{filename}接口可在页面直接查看 god/玩家的GAME.md、GAME_RECORD.md原始文件其中/data/werewolf/GAME_RECORD.md会被特殊映射到 god 的记录文件方便统一路径查看。所有文件访问都做了路径越界校验读不到 storage 根目录之外的内容。因为 UI 服务对公网0.0.0.0:1995开放错误信息与路径也做了收敛仓库自带的 test_werewolf_server_security.py 佐证了三点POST /api/start内部抛ValueError时接口只返回Failed to start game文件系统细节不进响应读会话文件抛内部异常时/api/conversation/{session_id}返回通用的Failed to read conversationHTTP 500堆栈被隐藏/api/openviking/file收到../../../路径穿越请求时被拒绝404越界文件内容不会返回。对局结算后的三件套归档、排行榜、记忆沉淀这一节解决「一局跑完之后系统留下了什么、为什么值得留」。结束判定发生在每轮 god 回复之后is_game_ended_from_record解析GAME_RECORD.md确认结束必须同时满足——记录显示「游戏结束」、god 已产出最终结论、且 god 不再 任何玩家追问后续。三条都成立后依次执行归档god 的最终结算先广播给所有玩家然后保存会话文件CONVERSATION_{session_id}.md再把回放状态归档到REPLAY_STATE_{session_id}.json快照GAME_RECORD.md文本、解析结果与玩家信息使回放不依赖仍在变动的 live 文件。意义在于对局从此可审计、可回放排行榜按 god 工作区的GAME_RECORD.md解析胜方与玩家状态计算积分胜利 2 分 存活 1 分累计进bot/workspace/werewolf/LEADERBOARD.json重复 session 自动去重跳过避免同一局重复计分记忆沉淀向 god 与每个玩家发送/remember指令让各 Agent 把本局经验写进自己的 OpenViking memory。这是与 OpenViking 记忆能力衔接的关键一步也是跨局水平提升的基础。三件套全部完成后才依据 auto-run 配置决定下一步满足连跑条件则 1.5 秒后自动 restart start 调度下一局否则关闭连跑。若开启 auto-run 时当前没有对局在跑会以 0.1 秒延迟调度第一局每局真正跑完后completed_games自增达到目标局数即自动停。狼人杀 Demo 故障点自救手册这一节解决「跑起来之后坏了怎么办」按「现象 → 排查顺序 → 常见根因」组织。 现象 1点击「开始/继续」没反应访问GET /api/status确认 UI 后端在线浏览器打开{vikingbot_url}/bot/v1/health确认 Vikingbot 网关就绪看返回里running是否为true。常见根因OpenViking 没带--with-bot启动网关不存在所有对局消息超时或上一轮路由循环尚未结束需要先「停止游戏」再操作。现象 2真人模式看不到输入区确认顶部模式已选human_player确认是用该模式执行了开始或重启。常见根因模式只在 start/restart 动作里生效apply_game_mode_to_state纯切换下拉框不会改变正在跑的局。现象 3回放内容不完整检查CONVERSATION_{session_id}.md与REPLAY_STATE_{session_id}.json是否存在且完整回忆该局是否中途强制停止过。常见根因回放依赖会话记录与归档状态文件中途被停的局缺少权威GAME_RECORD.md快照建议让一局正常走到结算后再看回放。现象 4一局跑太久或疑似卡死随时点「停止游戏」中断路由取消 router task 并关闭自动连跑观察 god 是否连续两次没 到有效玩家。常见根因god 连续 2 次无效 时循环会自动停止不会无限循环max_loops的 1000 轮是硬顶超过即收车。现象 5UI 起来了但对局消息全部超时确认openviking-server进程存活、端口1933在监听确认 Vikingbot 端口18790在监听核对 UI 服务的--vikingbot-url指向与网关实际地址一致。常见根因手动启动时--bot-port与 UI 端--vikingbot-url不匹配消息发往了不存在的网关。现象 6想连续压测对局在「自动N局」输入框填局数后点击开启 fixed 模式连跑观察GET /api/status中auto_run_remaining_games递减到 0。根因提示对局之间会自动完成 restart 建局 start 的完整衔接且每局的/remember让 Agent 记忆逐局累积跨局表现会随之变化——这是特性不是随机波动。超越 Demo四个可迁移的工程范式这一节解决「不玩狼人杀这套东西对我还有什么用」。双通道信息隔离夜间行动只写GAME.md群里只回「操作完成」天然规避了 LLM 上下文里「谁都能看到所有人记忆」的常见泄漏问题。可迁移到多角色客服质检、合规审查等要求敏感信息不跨角色流动的场景。串行协作的双重约束路由循环的「一次只 一个 等回复再广播 汇总回传」与 SOUL 的固定顺序规则互为备份任何一层失守另一层兜底。可迁移到多方谈判模拟、仲裁流程、剧本杀等按轮次推进的多角色协作。文件即状态总线GAME_RECORD.md/GAME.md承载对局进度CONVERSATION_*、REPLAY_STATE_*、LEADERBOARD.json构成可审计的对局档案任何时刻打开文件就能知道局面。可迁移到需要审计与回放的裁判型多 Agent 流程。跨局经验累积每局结算后全员/remember经验沉淀进 OpenViking memory排行榜与回放为策略分析提供数据基础Agent 越打越强。可迁移到需要随使用次数自我改进的长期运行 Agent。参考路径速查Demo 说明文档bot/demo/werewolf/README.md一键启动脚本bot/demo/werewolf/start_werewolf_demo.py对局服务与路由引擎bot/demo/werewolf/werewolf_server.py前端页面bot/demo/werewolf/werewolfUI.html裁判角色规则bot/demo/werewolf/SOUL-god.md玩家角色规则bot/demo/werewolf/SOUL-player.md服务安全测试bot/tests/test_werewolf_server_security.pyVikingbot/bot/v1路由挂载点bot/vikingbot/channels/openapi.py【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考