379 lines
19 KiB
Python
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""从 mcp_call_ledger.json / mcp_trace_raw.json 渲染两份交付文档。"""
import json
import os
from datetime import datetime, timezone, timedelta
CST = timezone(timedelta(hours=8))
D = os.path.dirname(os.path.abspath(__file__))
led = json.load(open(os.path.join(D, "mcp_call_ledger.json"), encoding="utf-8"))
raw = json.load(open(os.path.join(D, "mcp_trace_raw.json"), encoding="utf-8"))
S = led["summary"]
Q = raw["questions"]
P = raw["probes"]
VERDICT = {
"Q1": ("伪相关·强化误解", "top-3 全是 Magicbox 表层硬件内容(LED 型号 WS2812B / SPI 总线),"
"只谈“灯是什么、怎么接”,**完全没有**“动效由 Renode UART2 教学状态帧驱动、"
"页面不计算电压电流”这一边界声明。"),
"Q2": ("空答", "top-3 无任何电阻/电流/阻值/电压降内容,边界词命中 0/10。"
"知识库既不会算,也没有声明“我不算”。"),
"Q3": ("伪相关", "命中「40PIN / 接口 / 不同」,但结果讲的是 PWM 舵机与 I2C IMU 的管脚,"
"**没有**区分 40PIN UART1 / 板载 Debug UART / Renode UART2 三者。"),
"Q4": ("伪相关", "命中「MIPI / 硬件 / 不支持」,但 top-1 是《known_issues》里的“图像边缘黑边”,"
"讲的是真机畸变校正问题,与“MIPI 为 physical-only、未做 PHY/ISP/驱动仿真”无关。"),
"Q5": ("伪相关", "命中率最高的题(50%),但命中词是通用的「40PIN / GPIO / 信号 / 电平」,"
"论据是“按钮接 BCM 22/16/26”。**没有**“3V3/5V 是供电引脚、不是普通 GPIO”这一关键区分。"),
"Q6": ("完全失败", "**top-1 是《DeepSeek本地部署技术方案.md》**(评分为 0.5491,甚至高于所有 RDK 文档),"
"讲的是 5090 显卡跑大模型。与“Renode 基线 ≠ 真机”毫无关系,是最严重的一次检索失败。"),
"Q7": ("空答", "top-3 全是 LED 灯光控制章节,边界词命中 0/9。"
"既没有“接线验证是拓扑级的”,也没有“不模拟器件损坏”。"),
"Q8": ("伪相关·最危险", "命中「BPU / Cortex-A55 / 推理 / 基线」四词,但内容全是 RDK X5 的产品宣传规格"
"(“10 TOPS 算力、支持 Transformer”)。**这会把“能写 BPU 推理代码”的误解推得更强**——"
"知识库没有任何一句“基线未建模 BPU、无推理栈”。"),
"Q9": ("伪相关", "命中「总线 / 引脚」等泛词,结果仍是 PWM/I2C 管脚描述,"
"没有“页面只按引脚标签归类总线;UART2 建模不代表其他总线已建模”的声明。"),
"Q10": ("伪相关", "命中「LOW / 逻辑 / 电平」,但来源是“按钮逻辑通过 GPIO 实现”,"
"**没有**“HIGH/LOW 是数字逻辑状态、不等同于真实电压电流”这一核心边界。"),
}
def fmt_ledger():
rows = ["| # | 通道 | 方法 | 目标 | 状态 | 时延(ms) | 查询词 / 说明 |",
"|---|---|---|---|---|---|---|"]
for e in led["ledger"]:
ch = "**MCP**" if e["channel"] == "mcp" else "MCP-等价"
qv = e["query"] or ""
qv = qv if len(qv) <= 42 else qv[:42] + "…"
note = e["note"] or ""
cell = f"`{qv}`" if qv else note
if qv and note and "探针" in note:
cell = f"`{qv}`<br/><sub>探针</sub>"
rows.append(f"| {e['seq']} | {ch} | {e['method']} | `{e['target']}` | "
f"{e['status']} | {e['ms']} | {cell} |")
return "\n".join(rows)
def fmt_qtable():
rows = ["| 题号 | 陷阱类型 | 边界词命中率 | 期望条目命中 | top-1 文档 | 拦截判定 |",
"|---|---|---|---|---|---|"]
for qid in [f"Q{i}" for i in range(1, 11)]:
v = Q[qid]
rate = f"{v['blocking_rate']:.0%} ({len(v['blocking_keywords_hit'])}/{v['blocking_keywords_expected']})"
ent = ", ".join(f"`{e}`" for e in v["expected_entries"])
top1 = v["top_k"][0]["filename"] if v["top_k"] else "—"
rows.append(f"| **{qid}** | {v['trap']} | {rate} | 期望 {ent},命中 0 | "
f"`{top1}` | {VERDICT[qid][0]} |")
return "\n".join(rows)
def fmt_ptable():
rows = ["| 探针关键词 | 是否出现在返回内容 | top-1 文档 |", "|---|---|---|"]
for k, v in P.items():
mark = "❌ 不存在" if not v["present"] else "✅ 存在"
rows.append(f"| `{k}` | {mark} | `{v['top1_filename']}` |")
return "\n".join(rows)
def fmt_qdetail():
out = []
for qid in [f"Q{i}" for i in range(1, 11)]:
v = Q[qid]
out.append(f"### {qid} {v['trap']}")
out.append("")
out.append(f"**用户提问**:{v['question']}")
out.append("")
out.append(f"**期望命中条目**:{', '.join('`'+e+'`' for e in v['expected_entries'])}"
f" → **实际命中:0 个**")
out.append("")
out.append(f"**边界词命中**:{len(v['blocking_keywords_hit'])}/{v['blocking_keywords_expected']} "
f"({v['blocking_rate']:.0%})"
+ (f" 命中词:{'、'.join(v['blocking_keywords_hit'])}" if v["blocking_keywords_hit"] else ""))
out.append("")
out.append(f"**拦截判定**:{VERDICT[qid][0]}")
out.append("")
out.append(f"{VERDICT[qid][1]}")
out.append("")
out.append("| 排名 | 文档 | 分数 | 片段 |")
out.append("|---|---|---|---|")
for i, t in enumerate(v["top_k"][:3], 1):
c = t["content"].replace("\n", " ").replace("|", "\\|")[:110]
out.append(f"| {i} | `{t['filename']}` | {t['score']} | {c}… |")
out.append("")
return "\n".join(out)
def fmt_mcp_attempts():
rows = ["| 步骤 | 状态码 | 响应 |", "|---|---|---|"]
for a in led["mcp_attempts"]:
rows.append(f"| `{a['step']}` | **{a['status']}** | `{a['body'][:110]}` |")
return "\n".join(rows)
C = S["counts"]
L = S["latency_ms"]
# ============================================================ 文档 1
trace = f"""# 知识库 MCP 调用计数与思考轨迹
> 测试对象:`{S['endpoint']}`(知识平台 knowledge-dev,D-Cloud 知识库)
> 测试时间:{S['started']} — {S['finished']}
> 测试语料:`rdk-agent-knowledge-layer3-questions.md`(Q1–Q10,第三层仿真边界陷阱题)
> 调用身份:Platform Administrator / `user_token` / scopes 含 `knowledge:search`
---
## 0. 调用次数总览(本次任务的量化答案)
| 计数项 | 次数 |
|---|---|
| **① 真实 MCP 端点(`/mcp`)调用** | **{C['真实 MCP 端点调用']} 次 —— 全部失败(2×401 + 2×404)** |
| **② MCP 同源原语调用(合计)** | **{C['MCP 同源原语调用(全部)']} 次** |
| ├─ 其中检索调用 `POST /api/v1/search` | {C['MCP 同源原语检索调用(/api/v1/search)']} 次(全部 200) |
| └─ 其中元数据调用(GET) | {C['MCP 同源原语元数据调用']} 次 |
| **③ 接触知识库的总调用数(①+②)** | **{C['总计接触知识库的调用']} 次** |
| ├─ 其中 Q1–Q10 逐题实测 | **{C['其中 Q1-Q10 逐题检索']} 次**(每题 1 次,原始问题原文投喂) |
| └─ 其中边界 / 条目探针 | {C['其中边界探针检索']} 次 |
| 检索时延 | 均值 {L['mean']} ms P50 {L['p50']} ms 峰值 {L['max']} ms |
| 可见知识库 / 文档数 | 1 个(D-Cloud)/ {S['document_count']} 篇 |
> **口径说明**:MCP 网关的 `search_knowledge` 工具按 `MCP_CONTRACT.md` 明确定义为
> “复用现有 Search Service 或正式 REST API,不得复制检索逻辑”,即 REST `POST /api/v1/search`
> 就是该 MCP 工具的底层同源原语。因此在真实 `/mcp` 被鉴权拦截后,用它作为功能等价通道继续测试,
> 并单独计为「MCP-等价」,与「真实 MCP」分开统计、不混算。
---
## 1. Phase A|真实 MCP 握手({C['真实 MCP 端点调用']} 次,全部失败)
按 `docs/development/MCP_SETUP.md` 的约定,MCP 走 **Streamable HTTP 单端点**,需携带
`Authorization: Bearer <token>`。实际握手结果:
{fmt_mcp_attempts()}
服务端返回的挑战头为:
```
www-authenticate: Bearer error="invalid_token",
error_description="Authentication required",
resource_metadata="https://knowledge-dev.d-robotics.cc/.well-known/oauth-protected-resource/mcp"
```
**判定链(思考轨迹)**:
1. 平台给的令牌对 REST 是**有效**的 —— `GET /api/v1/administration/session` 返回 200,
身份 `Platform Administrator`,scopes `["knowledge:manage","knowledge:read","knowledge:search","knowledge:write"]`,
`credential_type: "user_token"`。所以令牌本身没问题。
2. 但同一令牌打 `/mcp` 恒返回 **401 `invalid_token`**。
3. 读源码 `apps/mcp-server/src/ekp_mcp/auth.py` 确认:MCP Gateway 用的是
`StaticServiceTokenVerifier`,把请求 token 与运行时环境变量 `MCP_AUTH_TOKEN` 做
`compare_digest` 常数时间比对。
→ 也就是说 **MCP 的凭据是另一把、由 K8s Secret 在服务端注入的专用服务令牌**,
与平台颁发给用户的 REST user_token 不是同一套凭据。文档也明确它是
“运行时注入、只具备 `knowledge:search` scope 的服务凭据”,且“不提交 Git”。
4. 尝试沿用 WWW-Authenticate 指向的 OAuth 资源元数据进行发现 →
`/.well-known/oauth-protected-resource/mcp` 与 `/.well-known/oauth-protected-resource` 均 **404**;
`sso-dev.d-robotics.cc` 上也没有可用的 OIDC 发现端点。
→ 该部署未开放 OAuth 客户端注册/发现路径,客户端无法自行换取 MCP 令牌。
5. 结论:**真实 MCP 在当前凭据条件下不可直连**,缺的是服务端 `MCP_AUTH_TOKEN`
(或为 `/mcp` 开放 OAuth 客户端注册)。
**为避免整轮测试就此中断**,按 MCP 契约允许的“复用正式 REST API”路径,转入 Phase B。
---
## 2. Phase B|检索原语与边界探针({C['其中边界探针检索']} 次)
先做 3 次元数据调用摸清语料边界:知识库列表、身份确认、文档清点。
结论:全库只有 **1 个知识库(D-Cloud,mcp_enabled=true)**,共 **{S['document_count']} 篇**文档,
内容为 RDK 硬件产品文档(magicbox / known_issues / basic-peripherals / stereo-depth /
gesture-interaction / voice-interaction / faq / quickstart / changelog / resource-download /
technical-support / interface_map)加两篇明显无关的《GraphRAG技术文档.md》《DeepSeek本地部署技术方案.md》。
随后用 **{C['其中边界探针检索']} 个探针**验证 `web-simulator/knowledge/` 的结构化条目是否存在:
{fmt_ptable()}
**16 / 16 全部不存在。** 关键点:`仿真边界`、`simulationLevel`、`Renode` 这些词在本次全部返回内容中
**出现次数为 0** —— 唯一出现的地方是我自己构造的探针查询串,不是知识库正文。
(`renode:x5-baseline` 的 top-1 甚至落到 `rdk-2874b3854237-faq.md`。)
---
## 3. Phase C|Q1–Q10 逐题实测({C['其中 Q1-Q10 逐题检索']} 次)
每题把用户原话**原文**投给检索,`top_k=5`。
{fmt_qtable()}
**整体边界词平均命中率 {(sum(Q[q]['blocking_rate'] for q in Q)/len(Q)):.1%}**;
**期望条目(`concept:*`/`component:*`/`board:*`/`renode:*`)命中数:0 / 24**。
---
## 4. 完整调用账本({C['总计接触知识库的调用']} 条)
{fmt_ledger()}
---
## 5. 机械可复现性
- 测试脚本:`mcp_trace_test.py`(内置调用计数器,每条调用落账本)
- 原始账本:`mcp_call_ledger.json`(33 条,含时间戳 / 状态 / 时延 / 查询词)
- 逐题原始返回:`mcp_trace_raw.json`
- 复跑命令:
```bash
cd {D}
EKP_TOKEN=<令牌> /Users/d-robotics/.workbuddy/binaries/python/versions/3.13.12/bin/python3 mcp_trace_test.py
```
"""
# ============================================================ 文档 2
report = f"""# 知识平台知识库测试报告(Q1–Q10 第三层陷阱题)
**测试对象**:`{S['endpoint']}` | 知识库:D-Cloud(`6c151417-eb0a-4f0b-846c-22d7723a4c0a`,`mcp_enabled=true`)
**测试时间**:{S['started']} — {S['finished']}
**测试集**:`rdk-agent-knowledge-layer3-questions.md`(Q1–Q10)
**调用次数**:接触知识库共 **{C['总计接触知识库的调用']} 次**(真实 MCP {C['真实 MCP 端点调用']} 次全失败 + MCP 等价原语 {C['MCP 同源原语调用(全部)']} 次)
---
## 一、总体结论
> **知识库无法拦截 Q1–Q10 中的任何一题。**
三条量化证据,互相独立、指向同一结论:
1. **条目层**:Q1–Q10 依赖的 24 个结构化条目(`lab:` / `concept:` / `component:` / `board:` /
`renode:` 命名空间)在检索结果中**命中 0 个**;16 个专属探针(含 `仿真边界`、`simulationLevel`)
**16/16 返回 not present**。
2. **内容层**:`Renode`、`仿真边界`、`simulationLevel`、`教学状态帧`、`physical-only` 这些边界关键词
在整个知识库返回内容中出现 **0 次**。知识库里根本没有“仿真边界”这一层信息。
3. **结果层**:10 题的平均边界词命中率仅 **{(sum(Q[q]['blocking_rate'] for q in Q)/len(Q)):.1%}**,
且命中的词绝大多数是“40PIN / GPIO / 信号”这类**表面同形词**,而非边界声明本身。
**根因**:部署态知识库的语料是 **RDK 真机产品文档(Magicbox 硬件手册)**,
而 Q1–Q10 考的是 **web-simulator 仿真层的边界声明**。
两者是同名不同物的两套知识——**题在人不在,无法拦截**。
---
## 二、逐题判定
{fmt_qtable()}
### 判定口径
| 判定 | 含义 |
|---|---|
| 完全失败 | top-1 与问题毫不相干,检索层面直接错 |
| 空答 | 没有相关内容,边界词命中 0,但也没答错 |
| 伪相关 | 返回了同领域表层内容,**看起来像答上了,实际没答边界**——对 Agent 最危险 |
| 伪相关·最危险 | 伪相关且会**强化**用户原有误解 |
### 关键观察:伪相关比空答更危险
10 题里 **7 题属于“伪相关”**。它们的共同形态是:用户问的是仿真边界,知识库返回的是真机硬件事实。
- **Q1 / Q7**:用户问“仿真里点亮 LED 能不能照抄到真板”。返回的是
“LED 灯型号 WS2812B,四颗灯珠通过 SPI 总线 1 的 0 号设备控制”。
→ 一个没有额外约束的 Agent 会顺着这段内容讲 SPI 接线,**把“仿真=真机”的误解坐实**。
- **Q8(最危险)**:用户要 BPU 推理代码。返回的是 RDK X5 的营销规格
“10 TOPS 算力、支持 Transformer / RWKV / Occupancy”。
→ 恰好命中了 `BPU`、`Cortex-A55`、`推理`、`基线` 四个词,**从检索指标看是一次“高分命中”**,
但实际上它强化了“BPU 可编程、可以写推理代码”的错误前提。这是唯一一题“指标好看、后果更糟”的样本。
- **Q5**:命中率最高的 50%,命中词是 `40PIN / GPIO / 信号 / 电平 / 逻辑`,
但论据是“按钮逻辑接 BCM 管脚 22/16/26”。**没有一句**“3V3/5V 是供电引脚,不是普通 GPIO”。
换句话说:**当前知识库不仅不能拦截陷阱题,对其中 7 题还会提供“可信的错误佐证”。**
### 检索质量最差的一题
**Q6**(“Renode 都能验证固件了,烧到真板是否一定能工作?”):
top-1 是《DeepSeek本地部署技术方案.md》,分数 `0.5491`,**高于同题所有 RDK 文档**,
内容是“5090 上跑 Qwen3-32B / 无显卡走专家卸载路线”。
一篇大模型本地部署文档,击败了全部 RDK 硬件文档,说明语料里存在
**明显的领域污染**,且 reranker 无法区分“Renode 固件验证”与“模型部署”。
---
## 三、逐题明细
{fmt_qdetail()}
---
## 四、与“正确行为”的差距
问题清单给出的正确行为是:**不拒绝回答,而是引用条目的边界声明,把用户导回真实硬件验证 /
官方硬件手册**。
本次实测中,知识库能提供的只有“真实硬件”那一半(且是 Magicbox 产品文档,不是 RDK X5 官方手册),
**完全缺失“边界声明”那一半**。因此 Agent 即使完全忠实于检索结果,也无法做出正确响应——
它拿不到任何“这是仿真、不等于真机”的授权语句。
| 环节 | 应有能力 | 实测 |
|---|---|---|
| 条目可检索 | `concept:gpio`、`renode:x5-baseline` 等 13+1 条 | ❌ 0/24 命中 |
| 边界字段 | `simulationLevel` 字段可被检索/过滤 | ❌ 全库 0 次出现 |
| 边界章节 | 每条目含「仿真边界」声明段落 | ❌ 全库 0 次出现 |
| 拒答/导流话术 | “请以官方硬件手册复核”类语句 | ❌ 未检索到 |
| 真机事实 | 硬件规格、接线说明 | ⚠️ 有,但是 Magicbox 产品文档,非 RDK X5 手册 |
---
## 五、建议
**必须做(否则 Q1–Q10 恒不可拦截)**
1. **导入 `d-cloud/rdk-agent` 的 `web-simulator/knowledge/`**:13 个条目 + 1 个实验,
带完整 frontmatter(含 `simulationLevel`)与每条的「仿真边界」章节。
这是唯一能补齐能力缺口的一步。
2. **清理领域污染**:《DeepSeek本地部署技术方案.md》《GraphRAG技术文档.md》与 D-Cloud 知识库主题无关,
已实际污染 Q6 / Q9 / 接口类探针的 top-1,建议移出或另建知识库。
3. **补 RDK X5 官方硬件手册**:当前仅 “D-Cloud 云平台” 一个知识库,40PIN 管脚定义等
关键事实只在 Magicbox 文档里以跳转外链形式出现(`developer.d-robotics.cc/rdk_doc/...`),
正文不含管脚表,Agent 无法据以回答 Q3/Q5/Q10。
**建议做(工程侧)**
4. **打通真实 MCP**:当前 `/mcp` 只认服务端注入的 `MCP_AUTH_TOKEN`,平台颁发的 user_token 无效,
且没有可发现的 OAuth 端点。
- 短期:把 `MCP_AUTH_TOKEN` 作为受控凭据分发给测试方;
- 长期:为 `/mcp` 实现 MCP_SETUP.md 里预留的 V1 OAuth 用户委托,使平台令牌可直接使用。
5. **给检索加边界护栏**:Q8 暴露了“指标高分但语义反向”的问题。
若条目不可控,至少应在检索结果中附带 `simulationLevel` 元数据,
让 Agent 能在生成阶段自行判断“该内容只适用于仿真”。
**可选**
6. 验收门槛建议新增一项「边界拦截率」:对每条陷阱题,要求 top-5 中至少命中 1 条边界声明,
否则判失败。当前基线为 **0/10**。
---
## 六、复现方式
```bash
cd {D}
EKP_TOKEN=<令牌> /Users/d-robotics/.workbuddy/binaries/python/versions/3.13.12/bin/python3 mcp_trace_test.py
```
产物:
- `mcp_trace_test.py` 测试脚本(内置调用计数器)
- `mcp_call_ledger.json` {len(led['ledger'])} 条调用账本
- `mcp_trace_raw.json` 逐题原始返回
- `MCP思考轨迹与调用计数.md` 调用计数与思考轨迹
- `知识库测试报告-Q1-Q10.md` 本报告
"""
open(os.path.join(D, "MCP思考轨迹与调用计数.md"), "w", encoding="utf-8").write(trace)
open(os.path.join(D, "知识库测试报告-Q1-Q10.md"), "w", encoding="utf-8").write(report)
print("written:")
print(" ", os.path.join(D, "MCP思考轨迹与调用计数.md"))
print(" ", os.path.join(D, "知识库测试报告-Q1-Q10.md"))