sandeep-alluru/balancelab

# balancelab **对抗性游戏经济红队 — 在玩家之前发现套利漏洞。**  [](https://github.com/sandeep-alluru/balancelab/actions/workflows/ci.yml) [](https://pypi.org/project/balancelab/) [](https://pypi.org/project/balancelab/) [](https://pypi.org/project/balancelab/) [](LICENSE) [](https://codecov.io/gh/sandeep-alluru/balancelab) [](https://mypy-lang.org/) [快速开始](#quick-start) · [工作原理](#how-it-works) · [CLI 参考](#cli-reference) · [MCP / Claude](#mcp--claude) · [对比其他方案](#vs-alternatives) · [贡献](CONTRIBUTING.md) ## 为什么需要 游戏经济会以可预见的方式崩溃。一个将 gold → silver → gems → gold 以 24 倍净收益转换的合成循环，在发布后几小时内就会被玩家发现——而不是被 QA 发现。手动平衡表格无法扩展。游戏测试无法枚举所有循环。你需要一个自动化的红队，将你的经济视为有向图，并在数学上证明是否可能存在套利。 balancelab 正是为此而生：编写你的兑换规则，运行 `balancelab scan`，并在发布前获得一份漏洞报告，其中显示了每个有利可图的循环及其确切的收益倍率。 ``` balancelab scan --format json # CI-friendly, fails on exploits ``` ## 工作原理 ``` flowchart LR A[Define EconomyRule\nsource_item → target_item\nat source_qty:target_qty] --> B[Build EconomyGraph\ndirected exchange graph] B --> C[ExploitFinder\nBellman-Ford on\nlog-weight edges] C --> D{Negative cycle\ndetected?} D -->|Yes| E[ExploitPath\ngain_ratio > 1.0] D -->|No| F[Economy balanced\ntotal_found = 0] E --> G[ExploitReport\nall cycles ranked\nby gain_ratio] ``` **核心原语：** - **EconomyRule** — 一个不可变的、内容寻址的交换：给出 `source_qty` 个 `source_item`，获得 `target_qty` 个 `target_item`。ID = 规则参数的 SHA-256[:16]。相同的规则始终生成相同的 ID。 - **EconomyGraph** — 一个由 EconomyRules 组成的有向图。支持邻居遍历和序列化。 - **ExploitFinder** — 将汇率转换为对数权重（`weight = -log(rate)`）。对数权重图中的负环对应经济中的正收益环。使用 Bellman-Ford 算法进行 O(V·E) 复杂度的检测。 - **ExploitPath** — 一个带有收益倍率（例如 24.0x）的单一循环交易路径。 - **ExploitReport** — 完整的扫描结果：物品数量、规则数量、所有漏洞路径、时间戳。 事实存储在本地 SQLite 数据库中。无需服务器。 ## 功能 | 功能 | 详情 | |---------|---------| | 基于图的漏洞检测 | 在对数权重图上使用 Bellman-Ford 算法查找所有有利可图的循环 | | 内容寻址规则 | 相同的交换始终生成相同的 ID — 无重复 | | 收益倍率排序 | 每个漏洞路径显示精确的乘数（例如 24.0x） | | 离线 / 本地优先 | 单个 SQLite 文件，无需服务器 | | CI 退出码 | 如果发现漏洞，`balancelab scan` 将返回非零值 | | JSON 输出 | 面向下游自动化的机器可读输出 | | Markdown 输出 | 可直接粘贴到 GitHub PR 的评论 | | FastAPI REST 服务器 | `/rule`、`/rules`、`/scan`、`/reports`、`/health` 接口 | | MCP 服务器 | 为 Claude 和其他 agent 提供 Model Context Protocol 集成 | | OpenAI 工具规范 | 用于 GPT function calling 的 `tools/openai-tools.json` | | 45 个测试 | 覆盖所有层的全面测试套件 | ## 快速开始 ``` pip install balancelab ``` ``` from balancelab.economy import EconomyRule, EconomyGraph, ExploitFinder from balancelab.report import print_report # 定义你的经济体交易规则 graph = EconomyGraph() graph.add_rule(EconomyRule("gold", "silver", 1.0, 3.0, rule_id="mint")) graph.add_rule(EconomyRule("silver", "gems", 1.0, 2.0, rule_id="jeweler")) graph.add_rule(EconomyRule("gems", "gold", 1.0, 4.0, rule_id="trader")) # 查找 exploits finder = ExploitFinder() report = finder.find_exploits(graph) # 显示结果 print_report(report) # Exploit Report (id: a3f8b2c1d4e5f6a7) # 物品: 3 规则: 3 # 找到的 exploits: 1 # ┌──────────────────┬─────────────────────────────────┬────────────┐ # │ ID │ Path │ Gain Ratio │ # ├──────────────────┼─────────────────────────────────┼────────────┤ # │ 4d7e9c2a1b8f3e6a │ gold → silver → gems → gold │ 24.00x │ # └──────────────────┴─────────────────────────────────┴────────────┘ ``` ## CLI 参考 ``` balancelab [--db PATH] COMMAND [OPTIONS] ``` | 命令 | 描述 | 主要选项 | |---------|-------------|-------------| | `add SOURCE TARGET SRC_QTY TGT_QTY` | 添加一条兑换规则 | `--rule-id LABEL`, `--db PATH` | | `scan` | 在已存储的规则中查找漏洞 | `--format {rich,json}`, `--db PATH` | | `report REPORT_ID` | 显示特定的漏洞报告 | `--format {rich,json}`, `--db PATH` | | `log` | 列出所有漏洞报告 | `--db PATH` | | `status` | 显示规则数量和上一次扫描 | `--db PATH` | **全局选项：** | 选项 | 默认值 | |--------|---------| | `--db PATH` | `.balancelab/economy.db` | **示例：** ``` # 添加交易规则 balancelab add gold silver 1.0 3.0 --rule-id mint balancelab add silver gems 1.0 2.0 --rule-id jeweler balancelab add gems gold 1.0 4.0 --rule-id trader # 扫描 exploits balancelab scan # 机器可读输出 (用于 CI) balancelab scan --format json # 查看之前的扫描 balancelab log ``` ## MCP / Claude balancelab 内置了一个 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器。将其添加到 Claude Desktop： ``` { "mcpServers": { "balancelab": { "command": "balancelab-mcp" } } } ``` 可用的 MCP 工具：`add_rule`、`scan_economy`、`list_reports`。 安装带有 MCP 支持的版本：`pip install "balancelab[mcp]"` 你还可以在 [Smithery](https://smithery.ai/) 上找到 balancelab，实现一键安装 MCP。 ## OpenAI 使用 `tools/openai-tools.json` 进行 OpenAI function calling： ``` import json, openai tools = json.load(open("tools/openai-tools.json")) response = openai.chat.completions.create( model="gpt-4o", tools=tools, messages=[{"role": "user", "content": "Scan my economy for exploits"}], ) ``` ## 对比其他方案 | 方法 | 可扩展性 | 自动化程度 | 准确性 | 成本 | |----------|-------------|------------|----------|------| | **balancelab** | 图 (O·V·E) | 完全 CI 集成 | 数学证明 | 免费 | | 手动表格 | 差 | 无 | 容易出错 | 低 | | 游戏测试 | 差 | 无 | 不完整 | 高 | | 自定义脚本 | 不定 | 手动 | 不定 | 中 | | 纯 LLM 分析 | 不适用 | 部分 | 存在幻觉风险 | 高 | ## 仓库目录树 ``` balancelab/ ├── src/balancelab/ │ ├── __init__.py # Public API │ ├── economy.py # EconomyRule, EconomyGraph, ExploitFinder │ ├── store.py # SQLite persistence │ ├── report.py # Rich/JSON/Markdown formatters │ ├── cli.py # Click CLI │ ├── api.py # FastAPI server │ └── mcp_server.py # MCP server ├── tests/ │ ├── test_economy.py # Data model tests │ ├── test_exploit.py # Bellman-Ford exploit detection │ ├── test_store.py # SQLite CRUD │ ├── test_report.py # Formatters │ ├── test_cli_runner.py # CLI integration │ └── test_api.py # FastAPI endpoints ├── tools/openai-tools.json # OpenAI function calling spec ├── openapi.yaml # Full OpenAPI 3.1 spec ├── examples/demo.py # Standalone demo └── smoke_test.py # End-to-end smoke test ``` ## GitHub Topics 建议添加以下 topic 以提高可见性：`#game-economy` `#arbitrage` `#balance-testing` `#agents` `#mcp` `#llmops` `#python` `#cli` `#exploit-detection` `#graph-algorithms` ## Star 历史 [](https://star-history.com/#sandeep-alluru/balancelab&Date)

标签：Python, 图算法, 套利检测, 数值平衡, 无后门, 游戏开发, 经济系统, 网络测绘, 逆向工具