zcbot/evaluation

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 中经隧道连接生产库的实例 当作评测目标。

快速开始

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

.\scripts\evaluate.ps1

sh scripts/evaluate.sh local

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

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

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

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

$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 是便于评审的汇总。

单独运行本地工程审计：

.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 任务集和报告格式作为两边交换契约。

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

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

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

$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，不能冒充完整评估。

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

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

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

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

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

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

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

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

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

.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：

  .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；

• 增加只在测试数据库运行的并发、取消恢复、知识库和跨用户隔离用例。