pip install universal-game-framework

ugf-install --list                 # 看能装到哪些客户端
ugf-install --target workbuddy     # 装进 WorkBuddy
ugf-mcp                            # 起服务（stdio）
ugf-check                          # 装不上时先体检

cd Universal-Game-Framework
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

python tools/install_mcp.py --list                 # 看能装到哪些客户端
python tools/install_mcp.py --target workbuddy     # WorkBuddy
python tools/install_mcp.py --target opencode      # OpenCode
python tools/install_mcp.py --target custom --path /绝对路径/mcp.json

┌────────────────────────────────────────────────────────────┐
│                   agent_cli.py 对话 / 命令行指挥             │
│   detect → brief → research → ensure → play → report        │
└──────────────┬──────────────────────────────┬─────────────┘
               ▼                              ▼
        ┌──────────────┐             ┌──────────────────┐
        │  MCP Server  │             │   MCP Client     │
        │  对外暴露工具  │             │  主动接外部服务    │
        └──────┬───────┘             └────────┬─────────┘
               │                              │
        ┌──────▼────────┐            ┌────────▼─────────┐
        │ game_profiles │◄──热加载──►│  核心引擎（通用）   │
        │ 游戏档案(YAML) │            │ 感知/预判/评估/执行 │
        └───────────────┘            └──────────────────┘

python admin_panel.py          # 或 python launcher.py --ui auto
# 打开 http://127.0.0.1:5002  →  ⚙ 设置  →  🎮 打开游戏模式

{
  "mcpServers": {
    "ugf": {
      "command": "<你的 venv>/bin/python",
      "args": ["/绝对路径/Universal-Game-Framework/mcp_server.py"],
      "env": { "UGF_DRY_RUN": "1" }
    }
  }
}

# 1. 安装依赖
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt

# 2. 配置 API
cp .env.example .env   # 填入 LLM / VLM 密钥

# 3. 启动感知服务（需 florr_powerful_tools 的 YOLO）
python perception_server.py

# 4. 进入对话 CLI（另一终端）
python agent_cli.py            # 交互式；help 看全部命令
python agent_cli.py -c report  # 或跑单条命令

python launcher.py                      # 自动挑一个能跑的 UI（大盘 > Tk > CLI）
python launcher.py --ui panel           # 强制用监控大盘（主 UI）
python launcher.py --ui tk              # 强制用 Tk 离线备选
python launcher.py --ui cli             # 直接进命令行（永可用）
python launcher.py --dry-run --mock     # 离线演示：不碰键鼠 + 合成感知
python launcher.py --ui auto --selftest # 只探测并打印选择结果（CI 用）

bash start_all.sh    # 感知 + MCP + Agent 主循环 + 面板
bash stop_all.sh     # 优雅停止

UGF_DRY_RUN=1 python agent_main.py --rounds 5   # 主循环离线跑 5 轮
python perception_server.py --selftest          # 感知自检（无 YOLO 自动降级 mock）
python launcher.py --ui auto --selftest         # UI 可用性探测 + 选择结果
python tools/cli_smoke.py --strict              # CLI 31 条命令矩阵
python tools/mcp_tools_check.py --strict        # MCP 15 工具注册 / 调用 / 知识库往返

bash scripts/check.sh          # 全量 7 环节（约 4 分钟）
bash scripts/check.sh --fast   # 秒级：语法 + 启动自检 + 档案校验

python agent_cli.py -c mode     # 模式 / 感知后端 / LLM / VLM / 激活游戏

python tools/build_dist.py all      # Linux .deb + 便携版

Universal-Game-Framework/
├── agent_cli.py             # 对话指挥入口（交互 + -c 单命令）
├── agent_main.py            # MCP Client 主循环
├── mcp_server.py            # MCP 服务端
├── mcp_connector.py         # 外部 MCP 连接
├── predictor.py             # 全实体运动预判
├── combat_judge.py          # 战斗评估 / 套装 / 组队 / 心态
├── perception_server.py     # YOLO 感知 HTTP 服务
├── video_learner.py         # 视频学习
├── video_sources.py         # 视频来源
├── session.py               # 会话记忆
├── report_notifier.py       # 自动汇报
├── kb_maintainer.py         # 知识库压缩 / 归档 / 导入导出
├── auto_tuner.py            # 自动调参
├── game_profile_check.py    # 档案自检
├── boot_check.py / watchdog.sh / Dockerfile / florr-agent.service.example  # 稳定性
├── launcher.py              # 统一启动入口（v2.0：自动选 UI + 离线开关透传）
├── admin_panel.py           # 监控大盘（主 UI，纯标准库）
├── ui_tkinter.py            # 离线备选 UI
├── ui/legacy/               # 已归档：ui_pyqt.py / ui_streamlit.py（DEPRECATED）
├── cli_ui.py                # 终端界面
├── config.py / config.yaml  # 参数 + 热加载
├── ui_tkinter.py            # 离线备选 UI
├── ui/legacy/               # 已归档：ui_pyqt.py / ui_streamlit.py（DEPRECATED）
├── cli_ui.py                # 终端界面
├── game_profiles/           # 游戏档案：florr.yaml / space_invaders.yaml
├── skills/                  # 技能包
├── tools/                   # add_game.py / build_dist.py / cli_smoke.py / mcp_tools_check.py / static_audit.py
├── tests/                   # 30 个测试文件（987 用例，离线可跑）
├── scripts/check.sh         # 一条命令门禁
├── devplan/                 # PLAN / PROGRESS / AUDIT / OPS / TOOLS / PROFILE_SPEC / DIRECTION
├── packaging/               # Windows EXE / Android APK 构建
├── start_all.sh / stop_all.sh / watchdog.sh  # 一键启停 + 看门狗
├── knowledge_md/            # 自动创建，MD 知识库
├── knowledge_archive/       # 自动创建，超限归档区
└── run_logs/                # 自动创建，回合日志 / 汇报 / dry-run 动作明细