# CommLab Agent

**让 Agent 用通信实验检查证据，而不只是解释一条 BER 曲线。**

CommLab 接收 BPSK/QPSK + AWGN 链路配置、误码计数与实验者的结论，提供受控探针、统计区间、白名单修正和独立验证。候选需要选择工具、观察反馈并提交带证据的诊断。当前是 Linux / WSL2 上运行的本机实验应用，默认演示无需模型密钥。

## 能做什么

- **实验驱动诊断：** 用 Sionna 实测能量、噪声及 SER/BER，区分归一化、标签映射和统计结论问题；允许不改配置的正确诊断。
- **受控执行：** 类型化工具、参数限额、补丁白名单、配置版本绑定的验证；新补丁使旧验证失效。真实 intake 模型请求受 20 次调用帽与本地费用预留约束。
- **证据与可靠性：** 工具轨迹、产物引用、统计判断和停止原因进入本机报告；长工具使用进程组取消。旧 P1 执行器支持恢复，新 intake 暂不支持恢复。
- **Agent 实验：** 单 Agent 为默认，执行者主导的多角色脚本为可选；另有 MCP 实验服务和单／多 Agent 的历史对照。多 Agent 没有被证明更好。

核心链路：Python · Sionna / PyTorch · NumPy / SciPy · 原生工具调用循环 · FastAPI。MCP 是另一个工具服务入口；网页 live 走宿主工具 RPC，不把它描述成经 MCP 完成的 live。

## 快速开始：无需密钥

已验证环境为 Ubuntu 24.04 / WSL2、Python 3.12、CPU。请在 WSL 的 Linux 主目录克隆（例如 `~/projects`），不要放在 `/mnt/c`：本机曾在 Windows 挂载盘遇到 Python 构建权限错误。原生 Windows、GPU和异构硬件复现未验证。先安装 `uv`；如需隔离测试或真实模型运行，系统还需 Bubblewrap，并允许非特权用户命名空间。

```bash
git clone https://github.com/Conchlikewater/commlab-agent.git
cd commlab-agent
uv venv --python 3.12
uv pip install --python .venv/bin/python \
  --index-strategy unsafe-best-match \
  --extra-index-url https://download.pytorch.org/whl/cpu \
  -r requirements.lock.txt -e '.[dev]'
bash scripts/demo.sh
```

打开 **http://127.0.0.1:43127/**，载入示例并选择无付费脚本演示：

1. 输入 10,000 比特、零错误、目标 BER 为 `1e-6`。
2. 查看工具记录、当前配置的验证及证据报告。
3. 单侧 95% 上界约 `2.995e-4`，因此零错误不足以支持该目标，更不等于真实 BER 为零。

启动脚本清除模型密钥并暂停付费。默认演示使用脚本策略和本机仿真，**不是本次真实模型推理**。历史成绩页提供冻结摘要；本仓库不附私有评分材料及完整历史回放数据，旧 P3 逐格接口在缺少数据时明确不可用。

## 实际验证过什么

| 证据 | 结果 | 适用范围 |
|---|---|---|
| 历史单／多 Agent 冻结对照 | 单 Agent 25/27；多 Agent 10/27 | 9 个合成任务族 × 3 次，相同可见信息、工具及共享 20 次 HTTP / $0.25 预算；失败均计入 |
| 本机新 intake 真实模型冒烟 | 10 次模型请求后自行提交；统计判断与独立验证一致 | 一次 `deepseek-flash` 运行，未修改链路；没有私有密封评分，不计为密封 T3 通过 |
| 本机默认演示 | 无密钥启动、脚本提交、报告与付费拒绝 | 无付费接线验证，不是 Agent 成功率 |

历史对照的多角色轨迹暴露出证据交接丢失、未执行补丁与预算消耗问题，因此默认保留单 Agent。后来执行者主导的 6 格开发筛查为 4/6；任务集合不同，不能据此宣称相对旧表提升。

本机冒烟按返回 usage 和当时峰值单价计算约 **$0.0276**，不是平台账单。此前一次 API 错误也保留在记录中。历史成绩属于各自冻结版本，**不是此公开快照重新跑出的成绩**。详见 [评测与证据](docs/evaluation.md)。

## 结构与边界

```mermaid
flowchart LR
    A[配置 + 误码计数 + 声称] --> B[本机 intake]
    B --> C[脚本策略 / 显式启用的单 Agent]
    C --> D[类型化宿主工具]
    D --> E[Sionna 探针与白名单修正]
    E --> C
    D --> F[统计审查 + 当前配置验证]
    F --> C
    C --> G[候选提交与证据报告]
    H[MCP 客户端] --> I[MCP 实验服务]
    I --> D
```

- 范围是未编码 BPSK/QPSK + AWGN，不是通用无线网络仿真器，也不接受 OFDM、衰落或任意外部代码执行。
- 公开的任务生成器包含合成故障定义，适合开发与演示；不能让可读仓库的候选把这些固定任务当成盲测集。
- 候选文件工具可使用 Bubblewrap 隔离；这不是对整个 Python 宿主、所有 MCP 入口或不可信管理员的安全证明。
- 正式模型运行需要主动配置密钥、解除暂停并确认费用。默认不启用；本地费用帽不替代服务商账单控制。操作见 [运行说明](docs/running.md)。
- DSH 保留为历史试接入，不是默认执行器，没有 DSH UI 或可靠性优于 native 的结论。

## 无付费检查

```bash
bash scripts/check.sh
```

该检查运行公开快照的核心回归；真实命名空间检查需 Bubblewrap。依赖旧云端素材、私有密封文件或旧主机账号的测试保留为历史测试，不承诺直接运行全库 `pytest` 全绿。

## 许可

源码遵循 [Apache-2.0](LICENSE)。依赖库遵循各自许可。本仓库由既有消毒交付包和本机后续接线整理为公开快照，历史私有仓库及密钥未导入。