MUNagent 是一个使用 Python 开发的模拟联合国历史委员会推演 Agent。它从声明式场景包加载历史背景、会场、角色与剧情，为每名代表创建独立 Agent，并由主席 Agent、全局 DM 与通用引擎共同推进会议。
当前版本聚焦单进程内的多会场闭环：会场分别维护议程和事件表，代表可以安全换场，跨会场通信受声明线路约束，全知全局 DM 统一裁定行动并推动总体局势。
- 独立代表 Agent：每名代表拥有自己的角色目标、私有信息、记忆与行动循环；
- 多会场推演：各会场拥有独立主席、议程、阶段、命令队列和
EventList； - 全局 DM：依据权限、资源、时距等因素裁定行动，并用显式种子生成可复盘结果；
- 决议成熟度门槛：代表必须审阅精确版本，harness 持续督办主席按条款清单退修或确认， 完成前不能表决，连续无动作会留下审计并显式失败；
- 程序化信息边界：公开、私密及跨会场信息由引擎过滤，而非只依赖提示词约束；
- 声明式场景包：历史内容与通用引擎分离，支持单会场
0.1与多会场0.2schema； - 本地观察面板：查看会场事件、代表位置、私有记忆和 Agent Loop 记录，无需构建前端；
- 完整运行存档：保存配置、随机种子、终局原因和权威事件审计，便于复盘。
- Python 3.11+
- 一个支持 OpenAI
chat/completions接口的模型服务
建议在虚拟环境中安装：
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .默认 provider 为 DeepSeek。可以直接设置环境变量：
export MUNAGENT_API_KEY="你的 API Key"也可以创建 ~/.munagent/config.yaml：
providers:
deepseek:
base_url: https://api.deepseek.com
api_key: sk-你的密钥
default_provider: deepseek
default_model: deepseek-v4-flash配置优先级为环境变量、指定配置文件、默认配置。自定义 provider 时，可在启动命令中通过 --provider 和 --model 选择。
运行单会场模板：
munagent serve scenario-template运行多会场示例并固定 DM 随机种子：
munagent serve scenario-multivenue-example --seed demo-001未安装项目时，也可以使用等价命令：
python src/main.py serve scenario-template启动后访问 http://127.0.0.1:8765/ 打开观察面板。该面板包含角色秘密和完整模型轨迹，仅供本机管理员查看，不应公开部署。
只检查场景加载、服务和存档而不调用模型：
munagent serve scenario-multivenue-example --no-llm若要重点试跑 DM 的外交、议会与联合政府推演，可使用 1940 英国战时内阁会议包：
python src/main.py serve scenario-british-cabinet-1940 --seed cabinet-1940-001该包包含 16 名代表，采用五人内阁同版本共识确认政策，约运行 24 分钟。 外交和议会等场外反应由全局 DM 推演；程序适配与测试观察点见包内说明。
# 查看运行状态
munagent status
# 查看公开事件；可用 --venue 指定会场
munagent events
# 持续观察新增公开事件
munagent watch
# 停止推演，但保留查询服务
munagent stop
# 停止推演并关闭服务
munagent shutdown服务使用非默认端口时，为客户端命令添加 --url http://127.0.0.1:<port>。完整参数可通过 munagent --help 和 munagent <command> --help 查看。
一个典型场景包如下：
<scenario>/
├── AGENTS.md
├── index.yaml
├── background.md
├── communications.yaml # schema 0.2 必需
├── venues/
│ └── main.yaml
├── reps/
│ └── representative.yaml
├── storyline.yaml
├── mechanism.py # 空占位文件，当前不参与加载
└── simulation/ # 运行时自动生成
仓库包含两个可直接加载的例子：
scenario-template/：向后兼容的0.1单会场场景；scenario-multivenue-example/：包含声明式通信线路的0.2多会场场景。
角色卡必须将内容分为 public 和 private。代表 ID 由 reps/*.yaml 文件名派生，会场 ID 由 venues/*.yaml 文件名派生；外部剧情只写入 storyline.yaml，代表的发言、提案、签署和指令由运行时产生。
详细字段与跨文件约束见 场景包 schema。创建或修改场景前，请同时阅读对应目录中的 AGENTS.md。
每次推演都会在场景目录的 simulation/<run_id>/ 中生成：
<run_id>/
├── run.json
├── events.jsonl
├── _manifest.yaml
├── reps/
└── submissions/
其中 events.jsonl 是管理员级审计记录，可能包含私密事件正文和可见范围。运行目录默认不应提交或分享。
安装开发依赖并运行测试：
python -m pip install -e '.[dev]'
pytest项目面向 Python 3.11+，公开接口应提供完整类型标注。LLM 测试必须使用 mock，不应消耗真实 API。
src/ 通用推演引擎、Agent、LLM 与本地服务
tests/ 单元与集成测试
docs/ schema、运行服务和 Agent Loop 设计文档
scenario-template/ 单会场标准模板
scenario-multivenue-example/ 多会场示例
introduction.md 项目边界与详细设计概览
- 多会场运行在单一进程内，尚未实现跨进程调度或远程消息总线；
- 长期记忆尚不能跨进程恢复；
- 主席支持单次点名，尚未实现完整的定时发言队列；
- 观察面板是包含秘密信息的本机管理界面，不是公开直播页。
许可证条款见 LICENSE。