Knot Agent Eval

SKILL.md

---
name: knot-agent-eval
slug: knot-agent-eval
version: 1.0.0
description: |
  针对 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评测。
author: chutiansun
license: MIT-0
description_zh: Knot 智能体金标准评测
description_en: Knot Agent Golden-Set Evaluation
disable: false
agent_created: true
---

# 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：题目生成（可选，已有题库可跳过）
```bash
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：批量评测
```bash
python scripts/run_pipeline.py --config eval_config.yaml --stage eval
```
读 `eval_questions.json` → 逐题调 Knot API → 关键词命中率（5 层匹配：精确/去标点/去停用词/片段/同义短语 + 等价映射） → 文献命中率（3 路匹配） → 自动归因初判 → 写 `eval_results.json`（每题写盘，断点续跑）

### 阶段 5：AI 逐题语义复审（核心特色，**不生成代码**）
```bash
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：合并复审 + 渲染报告 + 导出
```bash
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`

### 一键全流程
```bash
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 — 配置文件模板