ClawHub

Knot Agent Eval

MCP Tools

针对 Knot AG-UI 协议的 RAG 智能体进行全流程金标准评测。覆盖： 题目生成（MCP知识库检索→拉文档切片→LLM出题 2-3 题）→ 批量提问 → 关键词/文献双路评分 → AI 逐题语义复审（对 PARTIAL/FAIL）→ 10 类归因（A1/A2/A3/B1/B2/B3/C1/C2/C3/C4）→ Jinja2 报告渲染 → Markdown/HTML 一键导出。 当用户需要评测 Knot 上的智能体（如 IEG 服采、艺库 Agent）、生成金标准评测报告、 分析 FAIL 题归因、对 PARTIAL/FAIL 题做 AI 语义复审时使用。 零硬编码：所有接入信息（Knot URL / agent_id / api_token / kb_mcp / llm） 必须由用户在 eval_config.yaml 中填写。 触发词：Knot评测、金标准评测、知识库评测、Agent评测、归因分析、文献命中率、 关键词命中率、AI语义复审、IEG服采、艺库Agent、RAG评测。

Install

openclaw skills install knot-agent-eval

knot-agent-eval

When to use

当用户请求满足以下任意条件时调用本 Skill：

  • 想评测 Knot 平台上的某个 Agent（IEG 服采、艺库 Agent、其他 RAG 助手等）
  • 需要从知识库文档批量生成评测题目
  • 需要做关键词命中率 + 文献命中率 + 归因的金标准评测
  • 需要对 PARTIAL/FAIL 题做 AI 逐题语义复审
  • 需要生成符合 IEG 标准模板的 Markdown / HTML 评测报告

Don't use when

  • 评测对象不是 Knot 协议（用通用的 agent-eval Skill）
  • 仅需要单题手工 review（直接 read_file 即可）

Steps

阶段 0：配置（用户必做）

  1. 把 config/eval_config.example.yaml 复制到工作目录改名为 eval_config.yaml
  2. 用户必须填写所有 # REQUIRED 字段：
    • agent.knot_url（如 https://knot.woa.com）
    • agent.agent_id
    • agent.username
    • agent.api_token 或 agent.api_token_env（指向环境变量）
    • agent.model（如 deepseek-v4-flash，必须小写）
    • agent.temperature（建议 0.3）
    • agent.agent_name（出现在报告标题）
    • report.question_source（题库来源说明）
    • agent.kb_mcp.url（MCP 端点，如 http://mcp.knot.woa.com/open/mcp）
    • agent.kb_mcp.api_token_env（MCP Token 环境变量名，启动前需 export）
    • agent.kb_mcp.knowledge_uuid（知识库 UUID）
    • agent.kb_mcp.search_domain（检索域，指定后可提升检索准确度）
    • agent.llm.base_url（出题 LLM API 地址，如 https://api.openai.com/v1）
    • agent.llm.api_key_env（LLM API Key 环境变量名，启动前需 export）
    • agent.llm.model（出题模型，如 gpt-4o-mini）
  3. 文档目录（可选）：
    • 方式 A（推荐，默认）：手动填写 qa_gen.doc_names 文档名列表——最完整可控
    • 方式 B：设置 qa_gen.auto_discover_docs: true，Skill 通过 MCP 多轮检索推断知识库文档目录
    • ⚠️ MCP检索推断可能不完整，建议核对并补充遗漏
    • 两种方式可互补：doc_names 中手动列出的文档 + 自动发现的文档会合并

阶段 1：题目生成（可选，已有题库可跳过）

python scripts/run_pipeline.py --config eval_config.yaml --stage gen

执行流程（v3：MCP 直查 + LLM 出题）：

  1. 文档目录获取：
    • 优先使用 qa_gen.doc_names / doc_list_file 中用户手动指定的文档名
    • 若列表为空且 auto_discover_docs=true，通过 MCP 多轮检索推断文档目录（可能不完整）
    • 若列表为空且未开启自动发现，报错退出并提示两种解决方案
  2. 按 doc_names 列出的文档名，直接调 MCP knowledgebase_search 检索知识库切片
  3. 从 MCP 返回结果提取 KB 原始切片（chunk_title / chunk_content / doc_id / chunk_index），按 chunk_index 排序拼接全文
  4. 内容质量检查：仅有链接/目录索引的文档自动跳过，不出无意义的题目
  5. 用 prompts/qa_gen_prompt.md 让 OpenAI 兼容 API（LLMClient） 为每篇有实质内容的文档生成 2-3 题
  6. 自动反查：每题的关键词必须能在原文档中找到，否则丢弃
  7. 输出 eval_questions.json

阶段 2-4：批量评测

python scripts/run_pipeline.py --config eval_config.yaml --stage eval

读 eval_questions.json → 逐题调 Knot API → 关键词命中率（5 层匹配：精确/去标点/去停用词/片段/同义短语 + 等价映射） → 文献命中率（3 路匹配） → 自动归因初判 → 写 eval_results.json（每题写盘，断点续跑）

阶段 5：AI 逐题语义复审（核心特色，不生成代码）

python scripts/run_pipeline.py --config eval_config.yaml --stage ai_review

脚本 dump 出 pending_ai_review.json（含所有 PARTIAL/FAIL 题），然后退出。 若配置了 ai_review.audit_pass.enabled=true，还会按比例抽样 PASS 题一起送审（兜底评分虚高）。 接下来由你（当前对话 AI）逐题做语义复审，按以下规则：

  1. 启动前先询问用户：「即将对 X 道 PARTIAL/FAIL 题做 AI 复审，是否继续？(Y/n/skip)」
  2. 用户确认后，逐题读取 pending_ai_review.json 的 items，对每一题独立调用 prompts/ai_review_prompt.md 给出 13 字段的 JSON 复审结论
  3. 不要写新的 Python 脚本去自动判分；这一阶段必须由 AI 实时推理，每题给出推理过程
  4. 把所有题的复审 JSON 汇总写入 ai_review_results.json

阶段 6：合并复审 + 渲染报告 + 导出

python scripts/run_pipeline.py --config eval_config.yaml --stage merge_review,render,export
  • merge_review：把 ai_review_results.json 字段合并到 eval_results.json（含 A3 自动修正：翻转为PASS且原归因为C4时自动修正为A3）
  • render：用 templates/report_template.j2 渲染 eval_report.md
  • export：用 scripts/md2html.py 把 md 转成 eval_report.html

一键全流程

python scripts/run_pipeline.py --config eval_config.yaml --stage all

当跑到 ai_review 时，脚本停下，等待你完成 AI 复审，再手动续跑 --stage merge_review,render,export。

Pitfalls

  • 零硬编码原则：所有 Knot 接入信息必须从用户配置读取，禁止在代码中写入任何项目特定值（agent_id / token / Knot URL / MCP URL / LLM key 等）。run_pipeline.py 启动时强校验所有 REQUIRED 字段，缺失立即报错退出。
  • API Token 安全：强烈推荐使用 api_token_env / api_key_env 指向环境变量，而非在 yaml 中明文填写。明文凭据会随配置文件一起被 git 追踪或截图泄露。
  • MCP 与 Knot Agent 是两套独立认证：MCP 用 x-knot-api-token header，Knot Agent 用 x-knot-api-token + x-knot-api-user header。两者 token 可能相同也可能不同，取决于配置。
  • MCP 只有切片检索能力：knowledgebase_search 是唯一可用的工具，resources/list 和 prompts/list 均返回空。无法通过 MCP 直接列举文档目录或获取完整文档原文，只能通过多轮检索推断。
  • MCP 会话需要初始化：每次 search() 调用需要先 initialize → 获取 Mcp-Session-Id → notifications/initialized → tools/call，完成后会话结束。不支持在同一会话中连续多次 tools/call。
  • Knot API 字段易错：AG-UI 协议中文本片段字段是 delta 不是 content；事件类型是 TEXT_MESSAGE_CONTENT 不是 content；THINKING_TEXT_MESSAGE_* 不能进入正文（会污染答案）。
  • 编码 bug：requests.iter_lines(decode_unicode=True) 偶尔把 utf-8 当 latin-1 解读 → 直接 chunk.decode("utf-8") 即可（requests.iter_lines() 默认不做 unicode 解码）。
  • 题目生成必须反查：用 AI 生成的题必须验证关键词能在原文档中找到，否则会出现"知识库不存在"的题目（IEG 项目早期最大坑）。
  • AI 复审稳定性：每题独立 prompt，不要批量塞进同一上下文（避免互相干扰）；输出 JSON 解析失败时要求 AI 重答而非脚本兜底。
  • AI 复审不生成代码：阶段 5 必须由 AI 实时推理，禁止写脚本调 LLM API 自动判分；这是与 agent-eval 通用 Skill 的关键差异。
  • 手动修正归因必须同步三个字段：如果需要手动修正某题的归因（如 B1→C1），必须同时更新 auto_attribution、ai_review.recommended_attribution 和 final_attribution 三个字段。渲染器优先读取 final_attribution，漏改会导致报告仍显示旧归因。
  • 文档目录 MCP 推断不完整：auto_discover_docs=true 通过 MCP 多轮检索推断文档目录，但只有被 query 命中的文档才会被发现。建议开启后仍核对并补充遗漏文档到 doc_names。
  • LLM 出题格式解析：LLM 返回的 JSON 可能被 Markdown 代码块包裹（json ... ），_parse_qa_response 已处理此情况。若 LLM 返回格式不稳定，可调整 prompt 或换更稳定的模型。
  • 关键词匹配引擎局限：含特殊符号（≤、%、#）、URL 片段、数学运算符（* vs ×）、中英文术语变体（"预构建AI Agent" vs "prebuilt AI Agents"）的关键词容易匹配失败，AI 复审时需重点关注此类误判。v1.1 新增 A3 归因（评分方法局限）和 synonym_phrases 第5层匹配来缓解此问题。
  • A3 归因（v1.1新增）：当 doc_hit=True + keyword_rate<0.15 + Agent有实质回答时，自动归因为 A3（评分方法局限）而非 C4。AI 复审翻转为 PASS 且原归因为 C4 时，merge_review 会自动修正为 A3。A3 为独占归因，不与 C2/C4 并存。
  • synonym_phrases 配置：grading.synonym_phrases 字典可配置标准关键词到同义短语的映射，作为第5层匹配兜底。当 synonym 命中数 > 精确命中数时，标记 scoring_method_limited=True，自动触发 A3 归因。
  • search_domain 可以为空：部分知识库的 search_domain 值可能不存在或与用户预期不同（如 chutiansun-fucai 在新 UUID 下返回"知识库中暂无内容"），不传 search_domain 反而能正常检索。已将 search_domain 从 REQUIRED 移至 OPTIONAL。
  • MCP 初始化必须带 x-knot-knowledge-uuids 请求头：_headers() 方法中设置了 x-knot-knowledge-uuids，如果不带此头初始化 MCP，tools/list 会返回 0 个工具（即使 UUID 正确）。手动测试 MCP 时务必带上此头。
  • knowledge_uuid 必须确认指向正确知识库：Knot 平台可能有多个知识库共用同一 MCP 端点，用户提供的 UUID 可能指向错误的知识库。建议先用一个已知 query 做冒烟测试，确认返回内容与目标知识库一致后再正式评测。

Verification

完成 Skill 建设后，按以下步骤验证：

  1. 启动校验：用空 eval_config.yaml 启动，必须报错列出所有缺失的 REQUIRED 字段
  2. 题目生成：随便给 5 个 iWiki 文档名，能产出 10-15 道格式合格的题，自动反查全部通过
  3. 关键词评分：用工作目录 eval_results_v2_fixed.json 跑 --stage render，章节结构与 IEG服采智能小助手_金标准评测报告_v2_final.md 一致
  4. AI 复审格式：每道题的复审 JSON 必须含全部 13 个字段（q_id / final_grade / flipped_from_auto / flip_reason / semantic_match_summary / missing_facts / extra_facts / hallucination / hallucination_evidence / recommended_attribution / attribution_evidence / confidence / reviewer_notes）
  5. 端到端：全新 Knot Agent 跑 10 题，5 分钟内出 Markdown + HTML 报告

References

  • @references/attribution_taxonomy.md — 10 类归因详细定义 + 决策树（v1.1 新增 A3）
  • @references/equivalent_map.json — 通用 + 项目级语义等价词典
  • @references/question_schema.md — 题库 JSON 格式规范
  • @references/result_schema.md — 评测结果 JSON 格式规范
  • @references/benchmark_thresholds.md — 业界基准阈值
  • @prompts/qa_gen_prompt.md — 题目生成 prompt 模板
  • @prompts/ai_review_prompt.md — AI 复审 prompt 模板（13 字段）
  • @templates/report_template.j2 — Jinja2 报告模板
  • @config/eval_config.example.yaml — 配置文件模板
More in MCP Tools