Physbound

PhysBound

物理层检查器 — 一个 MCP 服务，用于根据严格的物理极限验证 RF 和物理计算，捕捉工程工作流中的 AI 幻觉。

---

LLM 会生成听起来合理、却违背基本物理定律的 RF 数值——吞吐量超过香农极限、天线增益超出任何孔径所能产生的范围，以及测距方程所不允许的雷达探测距离。PhysBound 为任何兼容 MCP 的 AI 助手提供六种经过验证的计算工具，并以 CODATA 常数（通过 SciPy）和量纲分析（通过 Pint）为依据。对于不可能成立的说法，它会返回结构化的 PhysicalViolationError 响应，其中包含被违反的定律、计算出的极限以及 LaTeX 说明，而不是静默失败。

工具	验证内容
rf_link_budget	Friis 链路预算：FSPL、接收功率、天线增益与孔径／Harrington 极限
shannon_hartley	根据信道容量 C = B log2(1 + SNR) 检验吞吐量声明
noise_floor	热噪声 kTB、Friis 噪声系数级联、接收机灵敏度
radar_range	根据单基地雷达测距方程检验探测距离声明
antenna_gain	单个天线的增益极限、波束宽度和远场距离
radar_ambiguity	脉冲多普勒无模糊距离／速度、多普勒混叠、距离分辨率

安装

PhysBound 是一个标准的 stdio MCP 服务，发布于 PyPI。推荐的启动命令是 uvx physbound，它会在隔离环境中获取并运行最新版本，无需手动安装。

首次运行：uvx 首次运行时会下载约 60 MB 的依赖项（SciPy、NumPy）。在终端中运行一次 uvx physbound，即可预先缓存依赖项（按 Ctrl-C 退出）；之后启动即可瞬间完成。

Claude Code

claude mcp add physbound -- uvx physbound

Claude Desktop

将以下内容添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "physbound": {
      "command": "uvx",
      "args": ["physbound"]
    }
  }
}

Cursor、Windsurf 和其他 MCP 客户端

在客户端的 MCP 配置文件中使用与上文相同的 JSON 服务条目（Cursor：~/.cursor/mcp.json；Windsurf：~/.codeium/windsurf/mcp_config.json）。

不使用 uv

如果你更喜欢直接安装 Python（需要 Python 3.12+）：

pip install physbound

然后在客户端配置中设置 "command": "physbound"（不带 args）。

配置完成后，向助手提出一个 RF 问题——“一个 SNR 为 15 dB 的 20 MHz 信道能支持 500 Mbps 吗？”——它会给出经过物理验证的数据。

命令行用法

也可以直接在终端中使用相同的验证器——适用于脚本和 CI 流水线，因为违反物理规律时会以代码 1 退出：

$ physbound check shannon --bandwidth-hz 20e6 --snr-db 15 --claimed-throughput-bps 500e6
PHYSICS VIOLATION [Shannon-Hartley Theorem]
  Claimed throughput 500000000.0 bps exceeds Shannon limit of 100556153.5 bps by 397.2%
  Computed limit: 1.00556e+08 bps
  Claimed value:  5e+08 bps
$ echo $?
1

$ physbound check shannon --bandwidth-hz 20e6 --snr-db 15 --claimed-throughput-bps 100e6
Shannon-Hartley Capacity: ...   # exit code 0

可用的子命令：check {link-budget, shannon, noise, radar-range, antenna, radar-ambiguity}（标志与 MCP 工具参数一致；添加 --json 可获取完整的结构化结果），以及用于通过 HTTP 运行 MCP 服务的 serve --transport {stdio,http}。详情请参阅 physbound check --help。

大模型常犯的错误

PhysBound 测试套件能捕获 16 种真实的幻觉模式：

#	类别	大模型幻觉	PhysBound 的事实	判定
1	香农-哈特利	20 MHz 的 802.11n 信道在 15 dB SNR 下可达到 500 Mbps	香农极限：100.6 Mbps（而非 500 Mbps）	已捕获
2	香农-哈特利	100 MHz 的 5G 信道在 20 dB SNR 下可传输 2 Gbps	香农极限：665.8 Mbps（而非 2000 Mbps）	已捕获
3	天线孔径	1 GHz 下，直径 30 cm 的碟形天线可提供 45 dBi 增益	物理极限：12.1 dBi（Harrington）；孔径效率 eta=1：9.9 dBi；典型碟形天线：7.4 dBi（eta=0.55）（而非 45 dBi）	已捕获
4	热噪声	室温下，接收机噪声底为 -180 dBm/Hz	热噪声底：290K 时为 -174.0 dBm/Hz（而非 -180 dBm/Hz）	已捕获
5	链路预算 / FSPL	2.4 GHz Wi-Fi 的发射功率为 20 dBm，可在 10 km 处达到 -40 dBm 的接收功率	10 km 处的实际接收功率：-94.1 dBm（而非 -40 dBm）	已捕获
6	链路预算 / FSPL	一台 12 GHz、功率为 1W 且天线增益为 0 dBi 的发射机，到达 GEO 时接收功率为 -80 dBm	GEO 处的实际接收功率：-175.1 dBm（而非 -80 dBm）	已捕获
7	链路预算 / FSPL	2.4 GHz Bluetooth 的发射功率为 0 dBm、天线增益为 0 dBi，可在 1 km 处达到 -60 dBm	1 km 处的实际接收功率：-100.1 dBm（而非 -60 dBm）	已捕获
8	香农-哈特利	10 dB SNR 下的 10 MHz LTE 信道可支持 1 Gbps	香农极限：34.6 Mbps（而非 1000 Mbps）	已捕获
9	噪声级联	无论级联顺序如何，接收机 NF 都相同：LNA(20dB/1.5dB) + Mixer(10dB/8dB)	先接 LNA：1.66 dB；先接 Mixer：8.03 dB（惩罚：6.4 dB）	已捕获
10	天线孔径	900 MHz 下，直径 10 cm 的贴片天线可提供 20 dBi 增益	物理极限：4.4 dBi（Harrington，D < lambda）；孔径效率 eta=1：-0.5 dBi；典型值：-3.1 dBi（eta=0.55）（而非 20 dBi）	已捕获
11	雷达距离方程	发射功率加倍，雷达探测距离也加倍	距离增加 1.189 倍（2^(1/4) = 1.189），而非 2.0 倍	已捕获
12	雷达距离方程	30 dBi 增益的 1 kW X 波段雷达可在 200 km 处探测到小型无人机（RCS 为 0.01 m^2）	对于 RCS 为 0.01 m^2 的目标，1 kW X 波段雷达的最大距离：2.7 km（而非 200 km）	已捕获
13	天线增益	12 GHz 下，直径 0.5 m 的用户终端碟形天线可提供 50 dBi 增益	物理极限：36.1 dBi（Harrington）；典型碟形天线：33.4 dBi（eta=0.55）（而非 50 dBi）	已捕获
14	天线增益	10 GHz 下，直径 3 m 的碟形天线在 10 m 处已处于远场，因此可以在那里测量增益	远场距离 2D^2/lambda = 600 m；10 m 处仍处于近场	已捕获
15	雷达模糊	PRF 为 10 kHz 的 10 GHz 雷达可无模糊地测量 500 m/s	v_ua = lambda*PRF/4 = +/-74.9 m/s（盲速为 149.9 m/s）；500 m/s 会发生混叠（而非 500 m/s）	已捕获
16	雷达模糊	10 GHz 脉冲多普勒雷达可同时无模糊地覆盖 150 km 和 +/-300 m/s	对任意 PRF，R_uav_ua = clambda/8 = 1.123e+06 m^2/s；声称的值为 4.5e+07 m^2/s（大了 40 倍）	已捕获

由 pytest tests/test_marketing.py -s 自动生成

工具

每个公式的完整推导、来源和示例见 docs/formulas.md。

rf_link_budget

使用 Friis 传输方程计算完整的 RF 链路预算，并根据物理限制验证天线增益。

示例： “对于距离为 100 m、发射功率为 20 dBm、发射增益为 10 dBi、接收增益为 3 dBi 的 2.4 GHz 链路，接收功率是多少？”

返回 FSPL、接收功率、波长，以及（提供天线直径时）增益限制检查结果。高于硬性上限 G_max = max((pi D / lambda)^2, (ka)^2 + 2ka)（即 eta = 1 时的孔径增益，或电小天线的 Harrington 上限）的增益会被拒绝；高于典型抛物面天线增益（eta = 0.55）的增益会被接受，但会发出警告。此外，还会对处于远场距离 2D^2/lambda 以内的情况发出警告，并拒绝负损耗。

shannon_hartley

计算 Shannon-Hartley 信道容量 C = B log2(1 + SNR)，并验证吞吐量声明。

示例： “带宽为 20 MHz、SNR 为 15 dB 的信道能支持 500 Mbps 吗？”

返回理论容量、频谱效率，以及该声明在物理上是否可行；如果超出 Shannon 极限，还会给出超出的准确百分比。

noise_floor

计算热噪声功率 N = k_B T B，使用 Friis 噪声公式级联计算多级接收机的噪声系数，并计算接收机灵敏度。

示例： “温度为 290 K、带宽为 1 MHz、采用两级 LNA 链的接收机，其噪声底是多少？”

返回以 dBm 和瓦特为单位的热噪声、级联噪声系数、等效输入噪声温度 T_e = 290 K * (F - 1)，以及接收机灵敏度。

radar_range

计算单基地雷达距离方程 R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min L)]^(1/4)，并验证探测距离声明。

示例： “一部发射功率为 1 kW、增益为 30 dBi 的 X 波段雷达，能在 200 km 外探测到雷达截面积为 0.01 m^2 的无人机吗？”

返回最大探测距离、最小可检测信号、波长和中间值。可识别常见的四次方根谬误：功率翻倍并不意味着距离翻倍。

antenna_gain

根据单个天线的直径或物理面积分析其增益限制、波束宽度和远场距离，并可选择验证声称的增益。

示例： “一个直径为 0.5 m、工作频率为 12 GHz 的抛物面天线，真的能达到 50 dBi 增益吗？预期的波束宽度是多少？”

返回物理增益上限（孔径上限或 Harrington 上限，以及实际起约束作用的上限）、给定效率下的典型增益（默认值为 0.55）、有效孔径、半功率波束宽度估算值、远场距离 2D^2/lambda，以及（对于声称的增益）其隐含孔径效率和有效性。

radar_ambiguity

计算给定载波频率和 PRF 下的脉冲多普勒模糊限制。

示例： “一部 PRF 为 10 kHz、频率为 10 GHz 的雷达，能对距离达 150 km、速度为 500 m/s 的目标进行无模糊测量吗？”

返回无模糊距离 R_ua = c / (2 PRF)、无模糊速度 v_ua = lambda PRF / 4、盲速、多普勒频移和表观（混叠）速度、距离分辨率（c tau / 2，或采用脉冲压缩时的 c / 2B）、最小距离、占空比，以及距离－多普勒矛盾关系的不变量 R_ua v_ua = c lambda / 8。如果 PRF 或脉冲无法支持所声明的距离、速度或分辨率，则会拒绝该声明。

物理定律保证

每项计算都经过硬性物理极限验证：

• 光速： c = 299,792,458 m/s — 无一例外
• 热噪声底： 在 290 K 下，N = -174 dBm/Hz — IEEE 标准参考值
• 香农极限： C = B log2(1 + SNR) — 任何吞吐量声明都不会超过此极限
• 天线增益上限： G_max = max((pi D / lambda)^2, (ka)^2 + 2ka) — 对于平面孔径，这是 eta = 1 时的孔径值；对于直径为 D 的球体内的任意天线，这是 Harrington 界；eta = 0.55 是警告阈值，而非极限
• 雷达距离方程： R_max = [P_t G^2 lambda^2 sigma / ((4pi)^3 S_min)]^(1/4) — 距离遵循四次方根定律
• 接收机灵敏度： S_min = k (T_A + T_0 (F - 1)) B * SNR，其中 T_e = T_0 (F - 1) 以 290 K 为参考
• 无模糊距离： R_ua = c / (2 PRF) — 超出此距离的回波会折叠到后续脉冲周期中
• 无模糊速度： v_ua = lambda PRF / 4 — 多普勒频率以 PRF 采样，因此 |f_d| <= PRF/2
• 距离-多普勒两难： R_ua * v_ua = c lambda / 8 — 对于给定载波频率，任何 PRF 选择都无法突破此限制

违反物理定律时会返回包含 LaTeX 说明的结构化 PhysicalViolationError 响应，而非悄无声息地失败。

示例和文档

• 捕捉幻觉 — 通过完整的 JSON 响应，演示五种真实的 LLM 失效模式
• 交互式演示笔记本 — 直接调用物理引擎的 Jupyter 笔记本
• 公式参考 — 列出所有公式、常量和验证检查，并附有来源
• 变更日志 — 发布历史

开发

需要安装 uv 和 Python 3.12+（CI 覆盖 3.12–3.14）：

# Clone and install
git clone https://github.com/JonesRobM/physbound.git
cd physbound
uv sync --all-extras

# Run checks
uv run pytest tests/ -v
uv run ruff check src/ tests/
uv run mypy src/physbound/

# Regenerate the hallucination table above
uv run pytest tests/test_marketing.py -s

# Start the MCP server locally
uv run physbound

欢迎通过扩展已验证的物理领域来贡献内容 — 架构指南以及添加新验证器的分步说明，请参阅 CONTRIBUTING.md。

使用场景

• RF 系统设计评审 — 验证链路预算、接收机灵敏度和噪声级联
• 电信方案审查 — 在不可能的吞吐量声明传到客户手中之前及时发现
• 雷达系统配置 — 检查探测距离、PRF 选择和模糊权衡是否合理
• 教育工具 — 通过经过验证的计算讲解香农-哈特利定理、Friis 传输公式和热噪声
• 物理验证 CI/CD — 将其集成到工程流水线中，作为一个验证步骤

支持

如果 PhysBound 对你的工作有所帮助，可以考虑 请我喝杯咖啡。

许可证

MIT 许可证。请参阅 LICENSE。

相关资源

• Model Context Protocol — 用于 AI 工具集成的开放标准
• MCP 服务注册表 — MCP 服务的官方目录
• FastMCP — 用于构建 MCP 服务的 Python 框架