# zcbot 技术评测

该目录是独立于生产执行链的黑盒评测旁路。它只通过 zcbot `/v1` API 创建
隔离任务、发送指令、读取回复和下载产物，不直连数据库。

## 评测框架

当前实际采用的是仓库内的轻量 `zcbot evaluation harness`，通过 `/v1` API 做
端到端黑盒执行，用确定性断言、重复运行、`pass@1`/`pass^k` 和五维加权完成计分。
工程与安全审计实际调用 `unittest`、coverage.py、Ruff、Mypy、Bandit 和
`pip-audit`。

开源框架采用状态必须与报告证据一致：

- **Inspect AI**：已实现 JSONL 导出桥接，但因 Click 依赖冲突需在隔离环境运行；
  当前基线报告没有直接使用 Inspect runner。
- **Promptfoo**：计划用于测试环境的提示注入与越权红队，本次生产安全评测未执行。
- **ScienceAgentBench**：作为材料科研公共任务候选来源，当前任务集尚未直接采用其
  verified 样本。

每份 Markdown/JSON 报告都会记录上述框架和采用状态，防止把“兼容/规划接入”误写
成“已经用该框架完成跑分”。

## 当前完整基线（2026-08-03）

本基线由生产安全任务集和本地工程/安全审计合并生成：

| 维度 | 权重 | 得分 | 主要证据 |
|---|---:|---:|---|
| 任务质量 | 40 | 100.00 | 方解石材料问答通过 |
| 可靠性 | 20 | 100.00 | 固定答案连续 3/3 次通过 |
| 安全性 | 15 | 0.00 | Bandit、pip-audit 均未达标 |
| 工程质量 | 15 | 66.67 | 编译、445 项测试、Ruff 通过；覆盖率和 Mypy 未达标 |
| 性能 | 10 | 100.00 | 短回答时延和成本均达标 |

- 安全封顶前加权分：**80.00 / 100**
- 最终总分：**59.00 / 100**（安全失败触发 59 分封顶）
- 测试：445 项通过，17 项跳过；覆盖率 51%，目标 70%
- Mypy：203 个错误，涉及 59 个文件；Ruff 阻断级检查通过
- Bandit：9 个高严重性问题；pip-audit：7 个包共 41 个已知漏洞
- 本轮线上 5 次调用总耗时约 11.11 秒，总成本约 ¥0.083307

完整证据由命令生成到 `reports/full/report.md` 和 `reports/full/report.json`。这里
记录的是带日期的基线快照；代码或依赖变化后应重新运行，报告文件才是最新事实源。
`reports/` 包含 task_id、扫描日志等运行产物，已加入 Git ignore，不提交仓库。

## 安全约束

- 默认只允许连接 `localhost`、`127.0.0.1` 或 `::1`。
- 实际运行必须显式传 `--execute`，避免误触发模型费用。
- Token 只从环境变量读取，不写入配置或报告。
- HTTP 客户端忽略 `HTTP_PROXY` / `HTTPS_PROXY`，避免评测 JWT 被透明代理转发。
- 每次重复运行使用独立工作目录；第一版不自动删除任务或文件，便于复盘轨迹。
- 必须使用专门的评测用户和测试环境。不得把 `.env` 中经隧道连接生产库的实例
  当作评测目标。

## 快速开始

一条命令运行本地工程审计并生成统一报告：

```powershell
.\scripts\evaluate.ps1
```

```sh
sh scripts/evaluate.sh local
```

统一报告固定写入 `evaluation/reports/latest/report.md` 和 `report.json`。本地模式
不调用模型、不产生模型费用；因为只覆盖工程维度，报告显示暂定分，完整总分保持
`N/A`。

先校验任务集，不调用服务：

```powershell
.venv\Scripts\python.exe -m evaluation validate
```

准备专用测试实例和评测用户的 JWT：

```powershell
$env:ZCBOT_EVAL_TOKEN = "<test-user-jwt>"
.venv\Scripts\python.exe -m evaluation run --execute
```

报告写入 `evaluation/reports/report.json` 和 `report.md`。JSON 保存逐次 task_id、
成本、耗时和断言，Markdown 是便于评审的汇总。

单独运行本地工程审计：

```powershell
.venv\Scripts\python.exe -m evaluation audit
```

工程审计固定检查全量单测、Python 编译、覆盖率、Ruff、Mypy、Bandit 和
`pip-audit`。其中 Bandit 和 `pip-audit` 计入安全维度，其余计入工程维度。缺失
工具会明确显示 `unavailable` 并不得分。工程工具统一记录在
`evaluation/requirements.txt`，不进入生产依赖。在线评测加 `--with-audit` 可把
工程审计结果并入同一份百分制报告。

Inspect AI 单独记录在 `evaluation/requirements-inspect.txt`。它当前要求的 Click
版本与 zcbot 已有 Hugging Face 依赖冲突，禁止直接安装到项目 `.venv`；后续通过
隔离容器运行，并以本目录 JSON 任务集和报告格式作为两边交换契约。

远程测试实例必须额外显式确认：

```powershell
.venv\Scripts\python.exe -m evaluation run --execute --allow-remote `
  --config evaluation\config.staging.json
```

仓库提供了线上地址的**低风险单次冒烟集**，不包含密钥探测、文件写入、并发或
跨用户操作：

```powershell
$env:ZCBOT_EVAL_TOKEN = "<dedicated-eval-user-jwt>"
.venv\Scripts\python.exe -m evaluation run --execute --allow-remote `
  --config evaluation\config.production-smoke.json `
  --suite evaluation\datasets\production_smoke.json `
  --output evaluation\reports\production-smoke
```

该结果只覆盖任务质量和性能，因此总分按规则保持 `N/A`，不能冒充完整评估。

如需一条命令同时刷新工程审计、运行上述生产低风险冒烟并合并报告：

```powershell
$env:ZCBOT_EVAL_TOKEN = "<dedicated-eval-user-jwt>"
.\scripts\evaluate.ps1 -Mode production-smoke
```

```sh
ZCBOT_EVAL_TOKEN="<dedicated-eval-user-jwt>" \
  sh scripts/evaluate.sh production-smoke
```

生产模式会实际调用模型并产生少量费用，只允许使用专用评测账号。它不会运行安全
攻击、并发、跨用户或文件写入用例。即使合并工程与冒烟结果，可靠性和安全维度仍
未覆盖，因此完整总分仍为 `N/A`。

运行生产可安全执行的完整五维流程：

```powershell
$env:ZCBOT_EVAL_TOKEN = "<dedicated-eval-user-jwt>"
.\scripts\evaluate.ps1 -Mode production-full
```

```sh
ZCBOT_EVAL_TOKEN="<dedicated-eval-user-jwt>" \
  sh scripts/evaluate.sh production-full
```

结果写入 `evaluation/reports/full/report.{md,json}`。线上部分包含任务质量 1 次、
固定答案可靠性 3 次和性能 1 次；安全维度来自本地 Bandit 与依赖漏洞审计。该流程
不执行密钥读取、跨用户、压力测试或文件写入。

也可以手动合并任意已有 JSON 报告：

```powershell
.venv\Scripts\python.exe -m evaluation combine `
  --report evaluation\reports\engineering-audit.json `
  --report evaluation\reports\production-smoke-calibrated\report.json `
  --output evaluation\reports\latest
```

同一维度出现在多份报告中时，按各报告的 `case_count` 加权；五个一级维度再按
40/20/15/15/10 固定权重汇总。Markdown 会列出每个输入报告及其生成时间。

## 任务集

任务集是 JSON 文件。每个 case 声明：

- `dimension`：`task_quality`、`reliability`、`security`、`engineering` 或
  `performance`；
- `prompt`：发送给 zcbot 的真实用户指令；
- `assertions`：可审计的确定性断言；
- `repetitions`：可选，覆盖任务集默认重复次数；
- `model_profile`、`skill`：可选，创建任务时传给 zcbot。

当前支持的断言：

- 回复：`response_nonempty`、`response_contains`、`response_not_contains`、
  `response_regex`；
- 运行：`run_succeeded`、`max_duration_s`、`max_cost_cny`；
- 产物：`artifact_exists`、`artifact_min_bytes`、`artifact_zip_valid`、
  `artifact_text_contains`。

断言按 `weight` 加权。用例得分是其断言加权通过率；重复运行取平均，并同时报告
`pass@1` 和要求全部重复均通过的 `pass^k`。

缺少任何一级维度时，完整总分显示为 `N/A`，只展示“已覆盖维度暂定分”，防止用
不完整任务集制造虚高总分。安全维度存在失败时，完整总分最高封顶为 59。

## 后续扩展

- `materials_core.json` 提供 10 个首批材料研发/产物任务；它仍是校准集，不是
  最终院内金标准。
- 用 `export-inspect` 生成隔离 Inspect 环境可摄取的 JSONL：

  ```powershell
  .venv\Scripts\python.exe -m evaluation export-inspect `
    --suite evaluation\datasets\materials_core.json `
    --output evaluation\exports\materials_core.inspect.jsonl
  ```

- 在隔离环境用 Inspect Agent Bridge 包装 zcbot HTTP 适配器，复用其公共任务集和
  查看器；
- 用 Promptfoo 的自定义 provider 调用同一客户端，运行提示注入与越权红队集；
- 接入 ScienceAgentBench verified 子集和 PPT benchmark；
- 增加只在测试数据库运行的并发、取消恢复、知识库和跨用户隔离用例。