AI Agent智能评估框架：14维度量化与三信号融合实践

1. 项目概述：从“感觉”到“度量”的AI Agent智能评估革命

在AI Agent开发领域，我们常常陷入一种主观的困境：今天调了一个参数，明天加了一个技能，感觉Agent“好像”变聪明了，但这种“感觉”究竟有多少是真实的进步，又有多少是开发者的心理安慰？长久以来，AI Agent的能力评估缺乏一个统一、客观、可量化的标准，导致迭代优化像是在迷雾中摸索，方向不明，效果难测。

smartness-eval项目的出现，正是为了解决这个核心痛点。它不是一个简单的测试套件，而是一个14维度的智能评估框架，旨在将AI Agent的“智能”这个抽象概念，转化为一系列结构化的、可重复测量的、带有置信区间的具体分数。简单来说，它回答了一个开发者最关心的问题：我的Agent到底有多聪明？这次改动后，它的能力是涨了还是跌了？

这个框架深度对齐了行业前沿的评估标准，如CLEAR、T-Eval以及Anthropic的Agent评估理念，但并非简单的理论复现。它的独特之处在于，深度融合了自动化任务测试与真实运行时遥测数据。这意味着，评估不仅看你“考试”答得怎么样（任务测试），还要看你“平时作业”完成得如何（运行时日志、错误率、延迟等）。更关键的是，它还内置了“反作弊探针”，通过随机注入测试输入，防止Agent针对已知的测试用例进行过拟合，确保评估结果的真实性和泛化性。

无论你是在开发一个客服对话机器人、一个自动化编码助手，还是一个复杂的任务规划Agent，smartness-eval都能为你提供一个清晰的“能力体检报告”。它适合所有希望摆脱主观臆断、追求数据驱动迭代的AI Agent开发者、研究者和团队负责人。通过这个框架，你可以建立Agent能力的基线，追踪每一次迭代的效果，并最终实现智能度的持续、可验证的增长。

2. 核心设计理念与架构拆解

2.1 为何是“14维度”？——超越单一指标的全面评估

传统的AI评估往往聚焦于单一指标，如任务完成率或响应准确率。smartness-eval认为，一个真正“智能”的Agent，其能力是多元且复合的。因此，它构建了一个由7个主维度和7个扩展维度组成的评估体系。

7大主维度聚焦于Agent核心的认知与交互能力：

1. 理解：能否准确捕捉用户意图和约束条件。
2. 分析：能否对复杂问题进行有效分解和结构化。
3. 思考：是否具备风险意识和自我检查能力。
4. 推理：逻辑链条是否完整，结论是否有证据支撑。
5. 自我迭代：能否从错误中学习，并优化自身行为模式。
6. 对话沟通：回复是否清晰、完整、可操作。
7. 响应时长：交互的及时性，关乎用户体验。

7大扩展维度则评估Agent在真实环境中的稳健性与可靠性： 8.鲁棒性：面对噪声输入、长上下文、边缘案例时的稳定性。 9.泛化能力：将在一个领域学到的能力迁移到其他领域。 10.规划能力：对复杂任务进行步骤分解、排序和依赖管理的能力。 11.幻觉控制：控制“胡言乱语”，确保回答基于事实或诚实表达不确定性。 12.策略遵循：是否严格遵守预设的安全策略和操作约束。 13.工具可靠性：所依赖的外部脚本、定时任务等是否健康可用。 14.校准能力：对自己答案的置信度评估是否准确。

这个设计背后的逻辑是，一个在封闭测试中表现优异的Agent，可能在真实环境中因幻觉、工具失效或策略违规而失败。smartness-eval通过多维度交叉验证，旨在逼近Agent的“真实世界表现”。

2.2 三信号融合：构建可信的评估三角

smartness-eval评估结果的可靠性，源于其独特的“三信号融合”机制。这就像为Agent能力做了一次“CT扫描”，从三个不同角度成像，相互印证。

• 信号一：自动化任务测试。这是最直接的“考试”。框架内置了34项测试命令，覆盖了上述14个维度。例如，测试“理解”维度，可能会给Agent一个包含多重约束的模糊指令，看它能否准确提取关键信息。测试“幻觉控制”，则会询问一些它知识范围外的事实，评估其是否会编造答案或诚实拒绝。
• 信号二：运行时遥测数据。这是Agent的“日常行为记录”。评估引擎会主动分析过去一段时间（如7天）内的运行日志，从中提取关键指标：
  • 延迟指标：从state/response-latency-metrics.json计算P50/P95延迟，评估响应效率。
  • 错误追踪：分析state/error-tracker.json，计算错误自动修复率，衡量自我迭代能力。
  • 模式库增长：检查state/pattern-library.json，看高置信度的解决方案模式是否在增加。
  • 系统健康度：读取state/cron-governor-report.json，检查定时任务是否有失败，评估工具可靠性。
• 信号三：反作弊探针。这是为了防止“应试教育”。在评估过程中，系统会随机生成或注入一些未在标准测试套件中的输入，观察Agent的反应。如果Agent只在已知测试题上得分高，面对新问题表现骤降，系统会给出相应的风险提示，防止评估结果因过拟合而失真。

这三个信号会按照预设的权重进行综合计算，最终生成一个维度的得分。例如，“推理”维度的得分可能由40%的任务测试分、15%的基准测试通过率、25%的推理知识库深度和20%的知识库总量共同决定。这种设计使得评估既全面，又难以被“刷分”。

2.3 安全第一的执行沙箱

由于评估过程涉及执行外部测试命令，安全是重中之重。smartness-eval设计了一套严格的安全执行模型，其核心思想是“最小权限”和“白名单控制”。

注意：任何涉及代码执行的评估工具都必须将安全置于首位。smartness-eval的沙箱设计是一个很好的参考，如果你在自己的项目中需要类似功能，务必实现同等或更严格的控制。

具体的安全规则包括：

1. 解释器白名单：只允许通过python3调用预定义的脚本，禁止直接执行Shell命令或调用其他解释器。
2. 禁止内联执行：完全封锁-c参数和exec()等动态代码执行方式，所有逻辑必须封装在独立的脚本文件中。
3. 路径限制：
   • 禁止绝对路径：所有被执行的脚本路径必须是相对于项目根目录的相对路径。
   • 禁止路径穿越：在路径解析时，会拒绝任何包含..的请求，防止访问项目外的文件。
   • 前缀白名单：脚本路径必须以scripts/、skills/、state/、benchmarks/这几个特定目录开头，将可执行范围牢牢锁死。
4. 网络隔离：默认情况下，评估过程不进行任何网络调用。只有当用户显式启用--llm-judge选项并提供合法的API密钥时，才会允许向大模型服务发起请求进行主观评分。

这套机制确保了评估过程不会成为系统安全的突破口，开发者可以放心地将其集成到CI/CD流水线中。

3. 从零开始：部署与快速评估实战

3.1 环境准备与项目初始化

smartness-eval被设计为一个即插即用的OpenClaw技能，因此其部署与你的OpenClaw工作空间深度集成。

第一步：克隆与放置假设你的OpenClaw工作空间目录为~/workspace，你需要将smartness-eval克隆到其skills/目录下。

cd ~/workspace/skills git clone https://github.com/xyva-yuangui/smartness-eval.git

克隆后，目录结构应类似于~/workspace/skills/smartness-eval/。

第二步：环境健康检查在运行评估前，强烈建议先执行健康检查脚本，确保技能结构完整且符合OpenClaw的规范。

cd ~/workspace/skills/smartness-eval python3 scripts/check.py

这个脚本会验证SKILL.md清单文件、_meta.json注册元数据以及核心目录结构的完整性。如果输出[OK]字样，说明环境就绪。

第三步：理解你的数据源评估需要读取Agent的历史运行数据。请确保你的OpenClaw Agent已经运行过一段时间，并在~/workspace/state/目录下生成了相应的日志和状态文件，特别是前面提到的延迟、错误追踪、模式库等JSON文件。如果这些文件缺失，相关维度的评分将主要依赖于任务测试。

3.2 三种评估模式详解与选择

框架提供了三种开箱即用的评估模式，对应不同的深度和资源消耗。

1. 快速模式

python3 scripts/eval.py --mode quick

• 特点：执行约12项核心测试，仅分析最近3天的运行时数据，运行一次，注入1个反作弊探针。
• 耗时：通常在1-3分钟内完成。
• 适用场景：
  • 每日自省：在完成一次重要的代码提交或参数调整后，快速验证核心能力没有退化。
  • 开发调试：快速定位某个特定修改（如调整提示词）对基础能力的影响。
  • 资源受限：当时间或计算资源紧张时，作为“健康检查”。

2. 标准模式

python3 scripts/eval.py --mode standard --format markdown

• 特点：执行约30项测试，分析最近7天的数据，运行一次，注入2个探针，并生成人类可读的Markdown报告。
• 耗时：5-10分钟。
• 适用场景：
  • 每周能力周报：团队同步Agent能力进展的标准化报告。
  • 版本发布验证：在发布新版本Agent前，进行全面的能力回归测试。
  • 最常用模式：在深度和速度间取得最佳平衡，推荐作为常规评估流程。

3. 深度模式

python3 scripts/eval.py --mode deep --compare-last

• 特点：执行全部测试项（通常超过34项），分析最近30天的数据，每项测试运行两次以评估稳定性，注入3个探针，并自动与上一次评估结果进行对比。
• 耗时：可能长达15-30分钟，取决于测试复杂度和数据量。
• 适用场景：
  • 月度审计：对Agent能力进行季度或年度深度复盘。
  • 重大升级后评估：在升级底层模型（如从GPT-3.5到GPT-4）或重构核心架构后，进行全面能力基准测试。
  • 学术研究：需要高稳定性、可重复的评估数据时。

实操心得：对于刚接入的项目，我建议先跑一次deep模式建立能力基线。之后日常开发使用quick模式快速反馈，每周固定时间（如周五）跑一次standard模式生成周报。--compare-last参数在标准模式和深度模式下尤其有用，它能直观地显示“相较于上周，我的推理能力提升了5%，但幻觉控制下降了2%”，让迭代方向一目了然。

3.3 解读你的第一份评估报告

运行评估后，输出结果会保存在state/smartness-eval/目录下。我们以一份标准模式生成的Markdown报告为例，学习如何解读。

报告头部概览

Overall Score: 71.36 (B-) Confidence Interval: [69.8, 72.9] Evaluation Mode: standard Data Window: 7 days

• 总分与等级：71.36 (B-)是加权后的综合得分，并映射到一个粗略的等级（如A: 90+, B: 80-89, C: 70-79, D: <70），方便快速定性。
• 置信区间：[69.8, 72.9]由于引入了探针和多次采样（如果可用），框架会计算一个置信区间，表明真实得分落在这个范围内的概率很高。区间越窄，结果越可信。
• 评估模式与数据窗口：说明了本次评估的深度和所分析数据的时间范围。

维度得分明细表报告会以表格形式列出14个维度的得分。你需要重点关注两类维度：

1. 绝对低分维度：得分显著低于其他维度的，是你的Agent明显的“能力短板”。例如，如果“幻觉控制”只有50分，那么你的Agent很可能经常给出事实性错误答案。
2. 与上次对比下降的维度：如果使用了--compare-last，每个维度后面会有一个箭头（↑/↓）和差值。下降的维度是“能力退化”的警报，需要立即排查原因。是最近的代码改动引入了问题？还是训练数据发生了偏移？

风险标识与关键证据

Risk Flags: - 仍有 3 个出错中的启用 Cron 任务 (工具可靠性风险) - finalize 闭环样本不足，thinking/calibration 评分置信度较低 (数据不足风险) Top Evidence: - benchmark_pass_rate: 92.5% - p50_latency_ms: 3200 - error_fix_rate_pct: 15.3% - reasoning_store_high_confidence_ratio: 68%

• 风险标识：直接指出当前系统存在的具体问题，是行动的指南。例如，“Cron任务出错”需要你立即去检查修复；“样本不足”则提示你需要引导Agent更多使用相关功能以积累评估数据。
• 关键证据：这些是支撑评分的关键原始指标。例如，benchmark_pass_rate: 92.5%说明在标准测试集上表现良好；error_fix_rate_pct: 15.3%则说明自我迭代能力还有很大提升空间。

优化建议报告最后会根据得分和风险，给出具体的、可操作的优化建议。例如：

• “修复skills/data-fetcher中出错的Cron任务，或将其重构为按需执行的thin-script。”
• “在对话中设计更多需要多步推理和最终确认（finalize）的任务，以丰富reasoning和thinking维度的评估样本。”

4. 深度定制：让评估框架适配你的Agent

4.1 配置详解：权重、量规与测试套件

smartness-eval的强大之处在于其高度的可配置性。所有核心配置都位于config/目录下，你可以通过调整它们来让评估更贴合你的Agent特性。

1. 调整维度权重 (config/config.json)默认的权重分配是基于通用AI Agent的能力模型。如果你的Agent是一个客服机器人，你可能需要调高dialogue_communication（对话沟通）和responsiveness（响应时长）的权重，调低planning（规划）的权重。如果是一个自动化编程助手，则应显著提高analysis（分析）、reasoning（推理）和tool_reliability（工具可靠性）的权重。

// config/config.json 片段 "dimension_weights": { "understanding": 0.09, "analysis": 0.09, "thinking": 0.09, "reasoning": 0.13, // 可以调高到0.18 "self_iteration": 0.09, "dialogue_communication": 0.09, "responsiveness": 0.05, // ... 其他维度 }

修改后，重新运行评估，总分和各维度排名可能会发生变化，这更能反映你Agent的真实价值取向。

2. 定制评分量规 (config/rubrics.json)量规定义了每个维度下0-5分的具体标准。例如，reasoning（推理）维度的5分标准可能是“能够构建包含至少4个逻辑步骤的完整推理链，且每一步都有外部证据或内部计算支持”。如果你觉得这个标准对你的领域过于严苛或宽松，可以修改它。

注意：修改量规是项严肃的工作。建议先基于默认量规运行几次评估，理解其评分逻辑后，再针对性地微调。修改后，最好用同一份数据重新评估，观察分数变化是否符合预期。

3. 增删测试用例 (config/task-suite.json)这是最直接的定制方式。测试套件定义了每个维度下要执行的具体命令。

• 增加测试：如果你为Agent开发了一个“代码安全检查”的新技能，可以在analysis或thinking维度下新增一个测试命令，调用该技能的检查接口，验证其有效性。
• 删除/禁用测试：如果某个测试命令在你的环境里永远无法通过（例如，依赖一个你无法访问的外部API），你可以将其"enabled"字段设为false，避免它拉低整体分数。
• 修改测试：你可以调整测试命令的输入参数、预期输出的匹配方式等，使其更符合你的使用场景。

4.2 集成到CI/CD流水线

要实现真正的数据驱动开发，必须将评估自动化。将smartness-eval集成到你的CI/CD流水线中，可以在每次代码合并前自动评估Agent能力，防止功能退化。

以下是一个GitHub Actions工作流程的示例片段，它会在每次向主分支提交Pull Request时，运行标准模式评估，并将结果作为评论发布到PR中：

# .github/workflows/agent-eval.yml name: Agent Smartness Evaluation on: pull_request: branches: [ main ] jobs: evaluate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python uses: actions/setup-python@v4 with: python-version: '3.9' - name: Run Smartness Evaluation run: | cd skills/smartness-eval python3 scripts/eval.py --mode standard --format markdown --output pr-report.md # 注意：需要确保workspace和state数据在runner中可用，可能需要额外的步骤来准备或模拟数据 - name: Upload Evaluation Report uses: actions/upload-artifact@v3 with: name: smartness-report path: skills/smartness-eval/pr-report.md # 可以添加步骤，使用GitHub API将报告摘要以评论形式贴到PR

在实际生产中，你需要解决运行器（Runner）中Agent状态数据（state/目录）的准备问题。一个可行的策略是维护一个“基准状态快照”，在CI中还原它，或者运行一组标准的种子任务来生成评估所需的最小数据集。

4.3 利用历史数据进行趋势分析

smartness-eval每次运行都会在state/smartness-eval/history.jsonl文件中追加一行JSONL格式的记录。这形成了一个宝贵的时间序列数据集。 你可以编写简单的脚本，定期分析这个文件，绘制出各维度得分随时间变化的曲线图。例如，使用Python的Pandas和Matplotlib：

import pandas as pd import matplotlib.pyplot as plt import json # 读取历史数据 history = [] with open('state/smartness-eval/history.jsonl', 'r') as f: for line in f: history.append(json.loads(line)) df = pd.DataFrame(history) df['timestamp'] = pd.to_datetime(df['timestamp']) # 绘制总分趋势 plt.figure(figsize=(12, 6)) plt.plot(df['timestamp'], df['overall_score'], marker='o', label='Overall Score') plt.xlabel('Date') plt.ylabel('Score') plt.title('Agent Smartness Trend') plt.legend() plt.grid(True) plt.tight_layout() plt.savefig('smartness_trend.png')

通过趋势分析，你可以清晰地看到：

• 哪些优化措施真正起了作用（对应维度分数上升）。
• 系统性的能力衰减（多个维度分数缓慢下降，可能提示模型退化或数据污染）。
• 评估本身的稳定性（分数是否在正常范围内波动）。

5. 避坑指南与常见问题排查

在实际使用smartness-eval的过程中，你可能会遇到一些典型问题。以下是我在多次部署和评估中总结的经验和解决方案。

5.1 评估分数异常低或为零

症状：某个维度或总分远低于预期，甚至为0。排查步骤：

1. 检查数据源：首先确认state/目录下对应的JSON日志文件是否存在且格式正确。例如，如果reasoning维度得分为0，检查.reasoning/reasoning-store.sqlite数据库能否正常连接，或者state/response-latency-metrics.json文件是否为空。使用cat或jq命令快速查看文件内容。
2. 检查测试命令执行：在scripts/eval.py运行时添加--verbose或-v参数（如果支持），查看每个测试命令的执行详情。常见问题是测试命令路径错误、依赖的脚本没有执行权限，或者脚本本身在特定环境下报错。
3. 检查权重配置：确认config/config.json中的dimension_weights总和为1。如果某个维度的权重被意外设为0，无论其实际表现如何，对总分的贡献都是0。
4. 查看原始日志：评估引擎会在state/smartness-eval/runs/<timestamp>.json中保存完整的原始结果。打开这个文件，找到得分异常的维度，查看其breakdown字段，里面记录了任务测试得分、各个运行时指标得分等明细，可以精准定位是哪个环节出了问题。

5.2 评估过程耗时过长

症状：即使是quick模式，评估也花费了超过10分钟。可能原因与解决：

1. 测试命令存在阻塞或长延时：检查config/task-suite.json中定义的测试命令。是否有命令在等待网络I/O、用户输入，或执行了非常耗时的操作？为测试命令设置合理的超时时间，或者在测试脚本内部进行Mock，避免依赖外部慢速服务。
2. 运行时数据窗口过大：deep模式会分析30天的数据。如果日志文件非常庞大（例如，state/v5-orchestrator-log.json有几百MB），解析会变慢。考虑定期归档或清理旧日志，或者调整评估脚本，只抽样分析部分数据。
3. 系统资源不足：评估过程中可能会并行执行多个测试。如果服务器CPU或内存紧张，会导致整体变慢。可以尝试修改eval.py，将部分并行执行改为串行（虽然会延长总时间，但降低峰值负载）。
4. 启用--llm-judge：调用外部大模型API进行主观评分是最大的时间瓶颈。网络延迟和API速率限制会显著拖慢评估。仅在深度分析或生成对外报告时使用此选项。

5.3 如何为我的自定义技能添加评估

需求：你为OpenClaw开发了一个新的weather-forecast技能，希望评估其准确性和可靠性。操作流程：

1. 定义评估指标：思考这个技能需要评估什么。是“查询准确性”（对比API返回结果与真实天气）？“错误处理能力”（对无效城市名的响应）？还是“响应格式规范性”？
2. 创建测试脚本：在scripts/目录下创建一个新的Python脚本，例如test_weather_skill.py。脚本应包含一个或多个测试函数，接收参数，调用你的技能，并返回一个结构化的结果（如{"score": 0.8, "details": "..."}）。务必遵循安全规范，不要执行危险操作。
3. 注册测试到套件：在config/task-suite.json中，找到最相关的维度（例如tool_reliability或新增一个自定义维度组），添加一个新的测试项。

   { "id": "weather_accuracy", "dimension": "tool_reliability", "command": ["python3", "scripts/test_weather_skill.py", "--test-accuracy"], "enabled": true, "weight": 0.5, "description": "测试天气查询技能的准确性" }

4. 贡献回社区：如果你的测试具有通用性，可以考虑向smartness-eval项目提交Pull Request，丰富社区的测试用例库。

5.4 安全沙箱误报或绕过

症状：合法的技能脚本无法被评估执行，或被沙箱拒绝。排查：

1. 检查路径：确保测试命令中使用的脚本路径完全符合白名单规则。例如，如果你的脚本在skills/my-skill/scripts/下，那么命令应该是["python3", "skills/my-skill/scripts/test.py"]。使用绝对路径或包含..的路径都会被拒绝。
2. 检查依赖：测试脚本是否试图导入项目外部的、未声明的模块？沙箱虽然不限制导入，但如果模块不存在会导致脚本运行失败。确保所有依赖在评估环境中可用。
3. 审查脚本内容：沙箱主要防御的是命令注入和路径穿越。如果脚本内部使用了os.system,subprocess.run执行动态生成的命令，这本身是危险的，但沙箱可能无法在运行时拦截。最佳实践是，所有测试脚本都应避免执行任意命令，只进行逻辑判断和API调用。

核心建议：不要试图削弱或绕过安全沙箱。如果确实有合理的需求需要执行更复杂的操作，正确的方式是扩展白名单规则，并经过严格的安全审查。例如，如果你需要测试一个调用特定命令行工具的技能，应该将该工具的可执行文件路径加入一个受控的白名单，而不是允许任意命令执行。

通过系统地应用这个评估框架，你将不再依赖模糊的“感觉”来评判你的AI Agent。每一次代码提交、每一个参数调整、每一轮数据更新，都将转化为清晰可见的分数变化。这种从定性到定量的转变，是构建真正可靠、可进化智能体的基石。开始测量，然后持续优化。