wdb/tests/test_d_wiki.py
2026-05-28 19:02:16 +08:00

510 lines
19 KiB
Python
Raw Blame History

This file contains ambiguous Unicode characters

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.

from __future__ import annotations
import json
import tempfile
import unittest
from pathlib import Path
from d_wiki.cli import main
from d_wiki.metadata import QueryEntry, query_matches_entry
class DWikiTest(unittest.TestCase):
def test_query_entry_matches_rewritten_alias_by_token_overlap(self) -> None:
entry = QueryEntry(
path=Path("camera.md"),
title="camera bring up",
aliases=("如何在X5平台上点亮camera",),
intent="procedure",
primary_sources=("multimedia_development/7-camsys_debug",),
supporting_sources=(),
answer_requirements=(),
)
self.assertTrue(query_matches_entry("X5平台 点亮 camera 使能", entry))
def test_bm25_metadata_context_pack_for_camera_bring_up(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = self._fixture(Path(tmp))
config = root / "d-wiki.yml"
output = self._run_json(
[
"--config",
str(config),
"search",
"--kb",
"x5",
"--query",
"如何在X5平台上点亮camera",
"--format",
"json",
]
)
self.assertEqual(output["status"], "found")
self.assertEqual(output["context_pack"]["answer_intent"], "procedure")
self.assertEqual(output["context_pack"]["coverage"], "partial_procedure")
first = output["context_pack"]["primary_sources"][0]
self.assertEqual(first["wikilink"], "multimedia_development/7-camsys_debug")
self.assertGreaterEqual(len(first["blocks"]), 2)
self.assertIn("点亮 camera", json.dumps(first, ensure_ascii=False))
def test_rewritten_camera_query_still_uses_query_entry_primary_source(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = self._fixture(Path(tmp))
output = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"search",
"--kb",
"x5",
"--query",
"X5平台 点亮 camera 使能",
"--format",
"json",
]
)
self.assertEqual(output["status"], "found")
first = output["context_pack"]["primary_sources"][0]
self.assertEqual(first["wikilink"], "multimedia_development/7-camsys_debug")
def test_fact_query_for_compute(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = self._fixture(Path(tmp))
output = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"search",
"--kb",
"x5",
"--query",
"x5的算力是多少",
"--format",
"json",
]
)
self.assertEqual(output["status"], "found")
self.assertEqual(output["context_pack"]["answer_intent"], "fact")
self.assertIn("10 TOPS", json.dumps(output["context_pack"], ensure_ascii=False))
def test_unrelated_query_is_insufficient(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = self._fixture(Path(tmp))
output = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"search",
"--kb",
"x5",
"--query",
"火星咖啡机怎么维修",
"--format",
"json",
]
)
self.assertEqual(output["status"], "no_match")
self.assertEqual(output["context_pack"]["coverage"], "insufficient")
def test_page_frontmatter_metadata_participates_in_retrieval(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = self._fixture(Path(tmp))
output = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"search",
"--kb",
"x5",
"--query",
"x5 coredump breadcrumbs",
"--format",
"json",
]
)
self.assertEqual(output["status"], "found")
self.assertEqual(output["sources"][0]["wikilink"], "misc/pstore")
def test_markdown_cleaning_filters_thematic_breaks_and_screenshot_only_blocks(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
docs = root / "docs"
docs.mkdir()
(docs / "dev-machine.md").write_text(
"# 开发机\n\n"
"> 📷 截图:开发机列表页\n\n"
"---\n\n"
"开发机支持 SSH 登录和 Web 应用访问。\n",
encoding="utf-8",
)
(root / "d-wiki.yml").write_text(
"knowledge_bases:\n"
" robogo:\n"
f" root: {docs}\n"
" source_type: markdown\n",
encoding="utf-8",
)
output = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"search",
"--kb",
"robogo",
"--query",
"开发机怎么用",
"--format",
"json",
]
)
snippets = [str(source["snippet"]) for source in output["sources"]]
self.assertNotIn("---", snippets)
self.assertFalse(any("📷" in snippet for snippet in snippets))
self.assertIn("开发机支持 SSH 登录", snippets[0])
def test_compile_builds_wiki_pages_and_search_prefers_compiled_wiki(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = self._fixture(Path(tmp))
config = root / "d-wiki.yml"
compiled = self._run_json(
[
"--config",
str(config),
"compile",
"--kb",
"x5",
"--force",
"--format",
"json",
]
)
indexed = self._run_json(
[
"--config",
str(config),
"index",
"--kb",
"x5",
"--format",
"json",
]
)
output = self._run_json(
[
"--config",
str(config),
"search",
"--kb",
"x5",
"--query",
"x5的算力是多少",
"--format",
"json",
]
)
wiki_root = Path(str(compiled["wiki_root"]))
self.assertEqual(compiled["status"], "compiled")
self.assertTrue((wiki_root / "SCHEMA.md").exists())
self.assertTrue((wiki_root / "index.md").exists())
self.assertTrue((wiki_root / "concepts" / "preface-overview.md").exists())
self.assertEqual(indexed["compiled_wiki"], str(wiki_root))
self.assertEqual(output["status"], "found")
self.assertIn(".d_wiki/wiki/concepts", output["sources"][0]["source_path"])
self.assertIn("10 TOPS", json.dumps(output["context_pack"], ensure_ascii=False))
def test_compile_emits_llm_wiki_structure_without_breaking_retrieval(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = self._fixture(Path(tmp))
config = root / "d-wiki.yml"
compiled = self._run_json(
[
"--config",
str(config),
"compile",
"--kb",
"x5",
"--force",
"--format",
"json",
]
)
self._run_json(
[
"--config",
str(config),
"index",
"--kb",
"x5",
"--format",
"json",
]
)
compute = self._run_json(
[
"--config",
str(config),
"search",
"--kb",
"x5",
"--query",
"x5的算力是多少",
"--format",
"json",
]
)
camera = self._run_json(
[
"--config",
str(config),
"search",
"--kb",
"x5",
"--query",
"如何在X5平台上点亮camera",
"--format",
"json",
]
)
wiki_root = Path(str(compiled["wiki_root"]))
compute_page = (wiki_root / "concepts" / "preface-overview.md").read_text(encoding="utf-8")
camera_page = (
wiki_root / "concepts" / "multimedia-development-7-camsys-debug.md"
).read_text(encoding="utf-8")
self.assertIn("llmWikiVersion: \"1\"", compute_page)
self.assertIn("## Intent Model", compute_page)
self.assertIn("## Retrieval Hints", compute_page)
self.assertIn("## Answer Blueprint", compute_page)
self.assertIn("## Evidence Graph", compute_page)
self.assertIn("## Key Evidence", compute_page)
self.assertIn("X5 算力", compute_page)
self.assertIn("10 TOPS", compute_page)
self.assertIn("- intent: fact", compute_page)
self.assertIn("- intent: procedure", camera_page)
self.assertIn("按步骤回答", camera_page)
self.assertEqual(compute["status"], "found")
self.assertIn("10 TOPS", json.dumps(compute["context_pack"], ensure_ascii=False))
self.assertIn(
"Key Evidence",
[block["heading"] for block in compute["context_pack"]["primary_sources"][0]["blocks"]],
)
self.assertEqual(camera["context_pack"]["answer_intent"], "procedure")
self.assertEqual(
camera["context_pack"]["primary_sources"][0]["wikilink"],
"concepts/multimedia-development-7-camsys-debug",
)
self.assertNotEqual(camera["sources"][0]["heading"], "Retrieval Hints")
def test_dream_queries_route_without_manual_query_entry(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = Path(tmp)
docs = root / "docs"
docs.mkdir()
(docs / "11-mirror-center.md").write_text(
"# 镜像资产使用\n\n"
"镜像资产是 RoboGo 的容器环境仓库,用于保存和复用开发环境。\n",
encoding="utf-8",
)
(docs / "40-3d-generation.md").write_text(
"# 40 · 3D 生成\n\n"
"3D 生成是平台提供的 AI 图生 3D 工具,基于 EmbodyGen,用一张参考图片生成 3D 模型,默认 glb。\n\n"
"生成结果可以保存到 3D 资产继续使用。\n",
encoding="utf-8",
)
(root / "knowledge" / "robogo").mkdir(parents=True)
(root / "knowledge" / "robogo" / "aliases.yml").write_text(
"aliases:\n"
" mirror:\n"
" terms: [镜像, 镜像资产, 创建镜像]\n"
" intent: procedure\n"
" related: [11-mirror-center]\n",
encoding="utf-8",
)
(root / "d-wiki.yml").write_text(
"knowledge_bases:\n"
" robogo:\n"
f" root: {docs}\n"
" source_type: markdown\n"
" aliases: knowledge/robogo/aliases.yml\n",
encoding="utf-8",
)
compiled = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"compile",
"--kb",
"robogo",
"--force",
"--format",
"json",
]
)
dreamed = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"dream",
"--kb",
"robogo",
"--force",
"--format",
"json",
]
)
self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"index",
"--kb",
"robogo",
"--format",
"json",
]
)
output = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"search",
"--kb",
"robogo",
"--query",
"我想知道如何使用3d资产生成功能",
"--format",
"json",
]
)
page = Path(str(compiled["wiki_root"])) / "concepts" / "40-3d-generation.md"
page_content = page.read_text(encoding="utf-8")
dreamed_query = Path(str(dreamed["output_store"])) / "queries" / "40-3d-generation.md"
dreamed_content = dreamed_query.read_text(encoding="utf-8")
self.assertNotIn("dream_queries:", page_content)
self.assertIn("3D资产生成怎么用", dreamed_content)
self.assertIn("provenance: dreamed", dreamed_content)
self.assertEqual(output["status"], "found")
self.assertEqual(output["context_pack"]["primary_sources"][0]["wikilink"], "concepts/40-3d-generation")
self.assertNotIn("镜像资产使用", json.dumps(output["context_pack"]["answer_requirements"], ensure_ascii=False))
def test_compile_llm_auto_falls_back_without_llm_config(self) -> None:
with tempfile.TemporaryDirectory() as tmp:
root = self._fixture(Path(tmp))
compiled = self._run_json(
[
"--config",
str(root / "d-wiki.yml"),
"compile",
"--kb",
"x5",
"--force",
"--llm",
"auto",
"--format",
"json",
]
)
page = Path(str(compiled["wiki_root"])) / "concepts" / "preface-overview.md"
page_content = page.read_text(encoding="utf-8")
self.assertEqual(compiled["status"], "compiled")
self.assertEqual(compiled["llm_mode"], "auto")
self.assertEqual(compiled["llm_scope"], "queries")
self.assertFalse(compiled["llm_enabled"])
self.assertIn("provenanceState: compiled", page_content)
def _run_json(self, argv: list[str]) -> dict[str, object]:
from contextlib import redirect_stdout
from io import StringIO
out = StringIO()
with redirect_stdout(out):
code = main(argv)
self.assertEqual(code, 0, out.getvalue())
return json.loads(out.getvalue())
def _fixture(self, root: Path) -> Path:
sources = root / "manual" / "_sources"
(sources / "multimedia_development").mkdir(parents=True)
(sources / "preface").mkdir(parents=True)
(sources / "misc").mkdir(parents=True)
(sources / "multimedia_development" / "7-camsys_debug.md.txt").write_text(
"# Camera调试指南\n\n"
"## 一 范围\n\n"
"本章节概述了 camera bring up 的过程,用于帮助读者快速了解并掌握 X5 camera 框架,"
"如何快速的新增camera 配置,并点亮 camera。\n\n"
"## 1.1 sensor gpio 配置\n\n"
"vcon 是 X5 camera 用于管理 sensor 硬件相关的 dts 节点。\n\n"
"## 2 sensor 驱动文件添加\n\n"
"需要将原厂 sensor 驱动转换成 X5 camera 驱动代码,并编译生成 so 库。\n",
encoding="utf-8",
)
(sources / "preface" / "overview.md.txt").write_text(
"# 前言\n\n## 关键特性\n\n- 贝叶斯架构BPU,提供最高 10 TOPS 算力。\n",
encoding="utf-8",
)
(sources / "misc" / "pstore.md.txt").write_text(
"---\n"
"title: pstore\n"
"aliases: [coredump breadcrumbs]\n"
"tags: [debug, reboot]\n"
"---\n"
"# pstore\n\n在X5平台上,当系统异常重启时会保存日志。\n",
encoding="utf-8",
)
(root / "knowledge" / "x5" / "queries").mkdir(parents=True)
(root / "knowledge" / "x5" / "aliases.yml").write_text(
"aliases:\n"
" camera:\n"
" terms: [camera, 摄像头, sensor, mipi, csi, vin, isp, 点亮, bring up, 调试, 配置]\n"
" intent: procedure\n"
" related: [multimedia_development/7-camsys_debug]\n"
" compute:\n"
" terms: [算力, tops, bpu]\n"
" intent: fact\n"
" related: [preface/overview]\n",
encoding="utf-8",
)
(root / "knowledge" / "x5" / "queries" / "camera.md").write_text(
"---\n"
"title: camera bring up\n"
"aliases: [如何在X5平台上点亮camera]\n"
"intent: procedure\n"
"primary_sources: [multimedia_development/7-camsys_debug]\n"
"answer_requirements: [按步骤回答]\n"
"---\n",
encoding="utf-8",
)
(root / "knowledge" / "x5" / "queries" / "compute.md").write_text(
"---\n"
"title: X5 算力\n"
"aliases: [x5的算力是多少]\n"
"intent: fact\n"
"primary_sources: [preface/overview]\n"
"---\n",
encoding="utf-8",
)
(root / "d-wiki.yml").write_text(
"knowledge_bases:\n"
" x5:\n"
f" root: {root / 'manual'}\n"
" source_type: sphinx\n"
" aliases: knowledge/x5/aliases.yml\n"
" queries: knowledge/x5/queries\n",
encoding="utf-8",
)
return root
if __name__ == "__main__":
unittest.main()