Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(parse): rewrite markdown relative links on directory ingest (#2452)

Kchen960d04ed0b21
diff --git a/openviking/parse/parsers/directory.py b/openviking/parse/parsers/directory.py
index e7d083e8e..7044d46ce 100644
--- a/openviking/parse/parsers/directory.py
+++ b/openviking/parse/parsers/directory.py
@@ -197,6 +197,7 @@ class DirectoryParser(BaseParser):
viking_fs,
warnings,
preserve_structure=preserve_structure,
+ import_root=str(source_path),
)
if ok:
@@ -350,6 +351,7 @@ class DirectoryParser(BaseParser):
viking_fs: Any,
warnings: List[str],
preserve_structure: bool = True,
+ import_root: Optional[str] = None,
) -> bool:
"""Process one file into the VikingFS directory temp.
@@ -370,7 +372,13 @@ class DirectoryParser(BaseParser):
if parser:
try:
- sub_result = await parser.parse(str(src_file))
+ sub_result = await parser.parse(
+ str(src_file),
+ # Rewrite only makes sense when relative structure is preserved;
+ # in flat mode link targets don't exist at their original paths.
+ enable_link_rewrite=preserve_structure,
+ link_rewrite_root=import_root,
+ )
if sub_result.temp_dir_path:
if preserve_structure:
parent = str(PurePosixPath(rel_path).parent)
diff --git a/openviking/parse/parsers/markdown.py b/openviking/parse/parsers/markdown.py
index a59c28a68..f0d1539c4 100644
--- a/openviking/parse/parsers/markdown.py
+++ b/openviking/parse/parsers/markdown.py
@@ -18,6 +18,7 @@ The parser handles scenarios:
"""
import hashlib
+import os
import re
import time
from pathlib import Path
@@ -42,6 +43,19 @@ KNOWN_EXTENSIONS.update(CODE_EXTENSIONS)
KNOWN_EXTENSIONS.update(DOCUMENTATION_EXTENSIONS)
KNOWN_EXTENSIONS.update(IGNORE_EXTENSIONS)
+# Markdown link/image in one pass: optional leading "!" marks images.
+# Scope (per spec, YAGNI): only inline [..](..)/![..](..) are handled. Reference-style
+# links, HTML, and links inside fenced/indented code blocks are NOT excluded — a
+# code-block link to an existing relative .md could be rewritten. Acceptable for now.
+# NOTE: `[^)]+` stops at the first ")", so a target whose filename literally
+# contains ")" is captured truncated; it then fails the on-disk existence check
+# and is left unchanged (conservative). Such filenames are unsupported.
+_MD_LINK_RE = re.compile(r"(!?)\[([^\]]*)\]\(([^)]+)\)")
+# Splits a link target into its path part and optional "#fragment"/"?query" suffix.
+_MD_FRAGMENT_RE = re.compile(r"^([^#?]*)([#?].*)?$")
+# Extensions whose targets become directories on ingest (see _rewrite_single_link).
+_MD_DIR_EXTS = {".md", ".markdown", ".mdown", ".mkd"}
+
def _smart_stem(path_or_name: str | Path) -> str:
"""Get the stem of a filename, but only strip known valid extensions.
@@ -67,6 +81,34 @@ def _smart_stem(path_or_name: str | Path) -> str:
logger = get_logger(__name__)
+
+def _gh_slug(text: str) -> str:
+ """GitHub-style heading slug: lowercase, strip punctuation, spaces→'-', keep CJK."""
+ s = text.strip().lower()
+ s = re.sub(r"[^\w\s-]", "", s)
+ s = re.sub(r"\s+", "-", s)
+ return s
+
+
+class _InMemoryFS:
+ """Minimal write-only VikingFS stand-in to capture a parser's split layout
+ without touching the real store (used for in-memory anchor location)."""
+
+ def __init__(self) -> None:
+ self.files: Dict[str, Any] = {}
+ self._n = 0
+
+ def create_temp_uri(self) -> str:
+ self._n += 1
+ return f"mem://t{self._n}"
+
+ async def mkdir(self, uri: str, exist_ok: bool = False, **kw) -> None:
+ return None
+
+ async def write_file(self, uri: str, content: Any) -> None:
+ self.files[uri] = content
+
+
if TYPE_CHECKING:
pass
@@ -120,6 +162,9 @@ class MarkdownParser(BaseParser):
# Cache for VikingFS instance
self._viking_fs = None
+ # Relative-link rewrite context, set per parse_content() call.
+ self._rewrite_ctx = None
+
@property
def supported_extensions(self) -> List[str]:
"""Return list of supported file extensions."""
@@ -174,7 +219,8 @@ class MarkdownParser(BaseParser):
source_path: Optional source file path
instruction: Processing instruction (unused in v5.0)
base_dir: Base directory for relative paths
- **kwargs: Additional runtime options
+ **kwargs: Additional runtime options, incl. resource_name/source_name and
+ enable_link_rewrite/link_rewrite_root (the latter set by DirectoryParser)
Returns:
ParseResult with temp_dir_path (Viking URI)
@@ -229,6 +275,20 @@ class MarkdownParser(BaseParser):
# Create root directory
root_dir = f"{temp_uri}/{self._sanitize_for_path(doc_title)}"
+ # Set up relative-link rewrite context consumed by _write_section.
+ # Link rewriting is opt-in via kwargs (DirectoryParser sets these);
+ # parse_content keeps the base **kwargs signature rather than adding
+ # dedicated parameters, so read them from kwargs here.
+ self._rewrite_ctx = {
+ "enabled": bool(kwargs.get("enable_link_rewrite", False)),
+ "source_path": source_path,
+ "doc_name": self._sanitize_for_path(doc_title),
+ "root_dir": root_dir,
+ # Rewrite is driven only by DirectoryParser, which passes the ingest
+ # root. Single-file ingestion never sets this, so it never rewrites.
+ "import_root": kwargs.get("link_rewrite_root"),
+ }
+
# Find all headings
headings = self._find_headings(content)
logger.info(f"[MarkdownParser] Found {len(headings)} headings")
@@ -270,6 +330,9 @@ class MarkdownParser(BaseParser):
except Exception as e:
logger.error(f"[MarkdownParser] Parse failed: {e}", exc_info=True)
raise
+ finally:
+ # Rewrite context lives exactly one parse_content call.
+ self._rewrite_ctx = None
# ========== Helper Methods ==========
@@ -422,6 +485,191 @@ class MarkdownParser(BaseParser):
return f"{safe[: max_length - 9]}_{hash_suffix}"
return safe
+ @staticmethod
+ def _doc_landing(layout: Dict[str, str]) -> Tuple[str, bool]:
+ """目标 .md 入库后的落点(相对其磁盘父目录),完全由真实 layout 推断,不对
+ parser 是否目录化做任何假设:
+
+ - 所有 section 收拢在同一公共目录下 → (该目录, True),链接指向目录;
+ - 否则即单个裸文件(如未来小 .md 不再拆成目录)→ (该文件, False),指向文件。
+
+ 落点是文件还是目录、叫什么,全部由 in-memory parse 出来的 layout 结构决定;
+ parse_content 怎么改,这里自动跟随。
+ """
+ keys = list(layout)
+ first_segs = {k.split("/", 1)[0] for k in keys}
+ if len(first_segs) == 1 and all("/" in k for k in keys):
+ return first_segs.pop(), True
+ return keys[0], False
+
+ async def _rewrite_single_link(
+ self, link: str, src_dir: str, import_root_abs: str, source_new_dir: str
+ ) -> str:
+ """Rewrite one link target; return original `link` if it must not change."""
+ raw = link.strip()
+ if (
+ not raw
+ or raw.startswith("#")
+ or raw.startswith("/")
+ or raw.startswith("mailto:")
+ or "://" in raw
+ ):
+ return link
+
+ m = _MD_FRAGMENT_RE.match(raw)
+ path_part = m.group(1)
+ suffix = m.group(2) or ""
+ if not path_part:
+ return link # pure fragment/query
+
+ target_disk = os.path.normpath(os.path.join(src_dir, path_part))
+ if not os.path.exists(target_disk):
+ return link
+ try:
+ if os.path.commonpath([import_root_abs, target_disk]) != import_root_abs:
+ return link
+ except ValueError:
+ return link # different drives, etc.
+
+ def _to_rel(new_disk: str, keep_suffix: bool) -> str:
+ r = os.path.relpath(new_disk, source_new_dir).replace(os.sep, "/")
+ return (r + suffix) if keep_suffix else (r if r.endswith("/") else r + "/")
+
+ ext = os.path.splitext(target_disk)[1].lower()
+ if ext not in _MD_DIR_EXTS:
+ # Non-.md target (image, sibling directory, ...): keep its path; only the
+ # source's added depth shifts the relative prefix.
+ return _to_rel(target_disk, keep_suffix=True)
+
+ # .md target → on ingest MarkdownParser turns it into some layout (a directory
+ # of section files, or — in future variants — a single file). Resolve against
+ # that REAL layout from an in-memory parse with the SAME parser: the landing
+ # (file vs directory), its name and the section files all come straight from
+ # the parser, so NOTHING about ingest is assumed here. Whatever parse_content
+ # does, running it in-memory tells us the final result.
+ layout = await self._target_split_files(target_disk)
+ if not layout:
+ return link # target unparsable → leave the link untouched
+
+ target_parent = os.path.dirname(target_disk)
+ landing, landing_is_dir = self._doc_landing(layout)
+
+ if suffix:
+ # A) #anchor uniquely located in a real section → point at that section file.
+ if suffix.startswith("#"):
+ anchor = suffix[1:]
+ hits = [
+ rel
+ for rel, text in layout.items()
+ if any(
+ _gh_slug(h) == anchor
+ for h in re.findall(r"^#{1,6}\s+(.+)$", text, re.M)
+ )
+ ]
+ if len(hits) == 1:
+ return _to_rel(
+ os.path.join(target_parent, hits[0]), keep_suffix=True
+ )
+ # B) Single-file document (a bare file, or a directory holding exactly one
+ # file) → the anchor/query lives in that one file; keep the suffix.
+ if len(layout) == 1:
+ return _to_rel(
+ os.path.join(target_parent, next(iter(layout))), keep_suffix=True
+ )
+
+ # C) Single bare file with no suffix to place (e.g. a future small .md kept as
+ # a file) → point at the file itself (empty suffix ⇒ no trailing slash).
+ if not landing_is_dir:
+ return _to_rel(os.path.join(target_parent, landing), keep_suffix=True)
+ # D) Directory landing → point at the directory and drop any suffix.
+ return _to_rel(os.path.join(target_parent, landing), keep_suffix=False)
+
+ async def _rewrite_relative_links(
+ self,
+ content: str,
+ *,
+ source_path: str,
+ doc_name: str,
+ section_subpath: str,
+ import_root: str,
+ ) -> str:
+ """Rewrite all relative markdown links/images in `content` (disk-coordinate)."""
+ src_dir = os.path.dirname(os.path.abspath(source_path))
+ import_root_abs = os.path.abspath(import_root)
+ source_new_dir = os.path.join(src_dir, doc_name, section_subpath)
+
+ out: List[str] = []
+ last = 0
+ for match in _MD_LINK_RE.finditer(content):
+ out.append(content[last : match.start()])
+ bang, text, link = match.group(1), match.group(2), match.group(3)
+ new_link = await self._rewrite_single_link(
+ link, src_dir, import_root_abs, source_new_dir
+ )
+ out.append(f"{bang}[{text}]({new_link})")
+ last = match.end()
+ out.append(content[last:])
+ return "".join(out)
+
+ async def _target_split_files(self, target_path: str) -> Optional[Dict[str, str]]:
+ """The target's real ingest layout {"<doc_dir>/<section...>": text} via an
+ in-memory parse, cached per parse_content() call. None on parse failure."""
+ ctx = self._rewrite_ctx or {}
+ cache = ctx.setdefault("_split_cache", {})
+ key = os.path.abspath(target_path)
+ if key not in cache:
+ cache[key] = await self._inmemory_split_files(target_path)
+ return cache[key]
+
+ async def _inmemory_split_files(self, target_path: str) -> Optional[Dict[str, str]]:
+ """Parse target into an in-memory FS; return {"<doc_dir>/<section...>": text}
+ keyed by path relative to the temp root, i.e. INCLUDING the doc-root dir
+ segment so callers can map each key straight onto the target's parent dir."""
+ try:
+ fs = _InMemoryFS()
+ sub_parser = MarkdownParser(self.extract_frontmatter, self.config)
+ # _get_viking_fs() ignores self._viking_fs and returns the global
+ # singleton, so override it on the instance to use our in-memory FS.
+ sub_parser._get_viking_fs = lambda: fs # type: ignore[method-assign]
+ result = await sub_parser.parse(target_path)
+ root = (result.temp_dir_path or "").rstrip("/")
+ out: Dict[str, str] = {}
+ for uri, content in fs.files.items():
+ if not isinstance(content, str):
+ continue
+ # rel = "<doc_dir>/<section...>" kept whole (temp_dir_path is the temp
+ # root, WITHOUT the doc-root dir), so it maps directly onto the
+ # target's parent directory on disk.
+ rel = uri[len(root) :].lstrip("/") if uri.startswith(root) else uri
+ out[rel] = content
+ return out
+ except Exception as exc:
+ logger.debug(f"[_inmemory_split_files] failed for {target_path}: {exc}")
+ return None
+
+ def _section_subpath(self, uri: str, root_dir: str) -> str:
+ """Return the section file's directory path relative to root_dir (POSIX)."""
+ section_dir = uri.rsplit("/", 1)[0]
+ root = root_dir.rstrip("/")
+ if section_dir == root:
+ return ""
+ if section_dir.startswith(root + "/"):
+ return section_dir[len(root) + 1 :]
+ return ""
+
+ async def _write_section(self, uri: str, content: str) -> None:
+ """Write a markdown section file, rewriting relative links when enabled."""
+ ctx = self._rewrite_ctx
+ if ctx and ctx.get("enabled") and ctx.get("source_path") and ctx.get("import_root"):
+ content = await self._rewrite_relative_links(
+ content,
+ source_path=ctx["source_path"],
+ doc_name=ctx["doc_name"],
+ section_subpath=self._section_subpath(uri, ctx["root_dir"]),
+ import_root=ctx["import_root"],
+ )
+ await self._get_viking_fs().write_file(uri, content)
+
# ========== New Parsing Logic (v5.0) ==========
async def _parse_and_create_structure(
@@ -468,7 +716,7 @@ class MarkdownParser(BaseParser):
# Small document: save as single file (check both token and char limits)
if estimated_tokens <= max_size and len(content) <= max_chars:
file_path = f"{root_dir}/{doc_name}.md"
- await viking_fs.write_file(file_path, content)
+ await self._write_section(file_path, content)
logger.debug(f"[MarkdownParser] Small document saved as: {file_path}")
return
@@ -477,7 +725,7 @@ class MarkdownParser(BaseParser):
logger.info("[MarkdownParser] No headings, splitting by paragraphs")
parts = self._smart_split_content(content, max_size)
for part_idx, part in enumerate(parts, 1):
- await viking_fs.write_file(f"{root_dir}/{doc_name}_{part_idx}.md", part)
+ await self._write_section(f"{root_dir}/{doc_name}_{part_idx}.md", part)
logger.debug(f"[MarkdownParser] Split into {len(parts)} parts")
return
@@ -681,7 +929,7 @@ class MarkdownParser(BaseParser):
# Fits in one file (check both token and char limits)
if tokens <= max_size and len(content_text) <= self.config.max_section_chars:
- await viking_fs.write_file(f"{parent_dir}/{name}.md", content_text)
+ await self._write_section(f"{parent_dir}/{name}.md", content_text)
logger.debug(f"[MarkdownParser] Saved: {name}.md")
return
@@ -732,7 +980,7 @@ class MarkdownParser(BaseParser):
logger.info(f"[MarkdownParser] Splitting: {name}")
parts = self._smart_split_content(content, max_size)
for i, part in enumerate(parts, 1):
- await viking_fs.write_file(f"{section_dir}/{name}_{i}.md", part)
+ await self._write_section(f"{section_dir}/{name}_{i}.md", part)
def _generate_merged_filename(self, sections: List[Tuple[str, str, int]]) -> str:
"""
@@ -788,12 +1036,12 @@ class MarkdownParser(BaseParser):
max_size = self.config.max_section_size or self.DEFAULT_MAX_SECTION_SIZE
parts = self._smart_split_content(content, max_size)
for i, part in enumerate(parts, 1):
- await viking_fs.write_file(f"{parent_dir}/{name}_{i}.md", part)
+ await self._write_section(f"{parent_dir}/{name}_{i}.md", part)
logger.debug(
f"[MarkdownParser] Merged then split: {name} ({len(sections)} sections → {len(parts)} parts)"
)
else:
- await viking_fs.write_file(f"{parent_dir}/{name}.md", content)
+ await self._write_section(f"{parent_dir}/{name}.md", content)
logger.debug(f"[MarkdownParser] Merged: {name}.md ({len(sections)} sections)")
def _get_section_info(
diff --git a/tests/parse/test_markdown_link_rewrite.py b/tests/parse/test_markdown_link_rewrite.py
new file mode 100644
index 000000000..06bd2da54
--- /dev/null
+++ b/tests/parse/test_markdown_link_rewrite.py
@@ -0,0 +1,351 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Tests for MarkdownParser relative-link rewriting on ingest."""
+
+from pathlib import Path
+from unittest.mock import patch
+
+from openviking.parse.parsers.base_parser import BaseParser
+from openviking.parse.parsers.directory import DirectoryParser
+from openviking.parse.parsers.markdown import MarkdownParser
+
+
+class TestRewriteRelativeLinks:
+ def _parser(self) -> MarkdownParser:
+ return MarkdownParser()
+
+ def _make_tree(self, tmp_path: Path) -> Path:
+ """构造与真实 knowledge 同形的小目录,返回入库根 (knowledge/)。"""
+ kb = tmp_path / "knowledge"
+ tgt = kb / "目录甲" / "目录乙" / "目录丙"
+ tgt.mkdir(parents=True)
+ (tgt / "文档.md").write_text("# 目标\n\n内容", encoding="utf-8")
+ (kb / "img").mkdir()
+ (kb / "img" / "a.png").write_bytes(b"\x89PNG\r\n\x1a\n")
+ (kb / "文档.md").write_text("placeholder", encoding="utf-8")
+ return kb
+
+ async def _rewrite(self, parser, kb, content, section_subpath=""):
+ return await parser._rewrite_relative_links(
+ content,
+ source_path=str(kb / "文档.md"),
+ doc_name="文档",
+ section_subpath=section_subpath,
+ import_root=str(kb),
+ )
+
+ async def test_md_target_becomes_directory(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(
+ self._parser(), kb,
+ "见 [x](./目录甲/目录乙/目录丙/文档.md)",
+ )
+ assert out == "见 [x](../目录甲/目录乙/目录丙/文档/)"
+
+ async def test_nonempty_subpath_adds_one_more_parent(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(
+ self._parser(), kb,
+ "[x](./目录甲/目录乙/目录丙/文档.md)",
+ section_subpath="二、示例小节",
+ )
+ assert out == "[x](../../目录甲/目录乙/目录丙/文档/)"
+
+ async def test_image_keeps_filename_only_adjusts_depth(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(self._parser(), kb, "![p](./img/a.png)")
+ assert out == "![p](../img/a.png)"
+
+ async def test_external_anchor_absolute_unchanged(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ p = self._parser()
+ for link in ("https://x.com/a", "viking://resources/x", "#sec", "/abs/p.md", "mailto:[email protected]"):
+ content = f"[t]({link})"
+ assert await self._rewrite(p, kb, content) == content
+
+ async def test_missing_target_unchanged(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(self._parser(), kb, "[t](./nope.md)")
+ assert out == "[t](./nope.md)"
+
+ async def test_directory_target_depth_adjusted(self, tmp_path: Path):
+ # A link to a sibling directory keeps its path, but the source's added depth
+ # shifts the prefix (the directory itself is translated on ingest).
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(self._parser(), kb, "[d](./img)")
+ assert out == "[d](../img)"
+
+ async def test_sibling_md_without_dot_prefix(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(
+ self._parser(), kb,
+ "[x](目录甲/目录乙/目录丙/文档.md)",
+ )
+ assert out == "[x](../目录甲/目录乙/目录丙/文档/)"
+
+ async def test_target_outside_import_root_unchanged(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ (tmp_path / "outside.md").write_text("# o", encoding="utf-8")
+ out = await self._rewrite(self._parser(), kb, "[t](../outside.md)")
+ assert out == "[t](../outside.md)"
+
+ async def test_fragment_kept_for_small_file(self, tmp_path: Path):
+ # Small target stays a single file <dir>/<dir>.md, so its in-file #anchor
+ # still resolves: point at the file and keep the fragment.
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(
+ self._parser(), kb,
+ "[x](./目录甲/目录乙/目录丙/文档.md#流程)",
+ )
+ assert out == "[x](../目录甲/目录乙/目录丙/文档/文档.md#流程)"
+
+ async def test_query_suffix_kept_for_small_file(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(
+ self._parser(), kb,
+ "[x](./目录甲/目录乙/目录丙/文档.md?v=1)",
+ )
+ assert out == "[x](../目录甲/目录乙/目录丙/文档/文档.md?v=1)"
+
+ async def test_large_file_anchor_located(self, tmp_path: Path):
+ # Large target is split into section files; the anchor is located via an
+ # in-memory parse → link points at the specific section file + keeps anchor.
+ kb = self._make_tree(tmp_path)
+ big = kb / "目录甲" / "目录乙" / "目录丙" / "big.md"
+ body = "".join(
+ f"## 第{i}章 {name}\n\n" + ("正文内容。" * 400) + "\n\n"
+ for i, name in [(1, "部署"), (2, "监控"), (3, "排查")]
+ )
+ big.write_text(body, encoding="utf-8")
+ out = await self._rewrite(
+ self._parser(), kb,
+ "[x](./目录甲/目录乙/目录丙/big.md#第3章-排查)",
+ )
+ assert out.startswith("[x](../目录甲/目录乙/目录丙/big/")
+ assert out.endswith(".md#第3章-排查)") # points at a file, anchor kept
+
+ async def test_large_file_unlocatable_anchor_falls_back_to_dir(self, tmp_path: Path):
+ # Anchor matches no heading in the (large) target → drop suffix, point at dir.
+ kb = self._make_tree(tmp_path)
+ big = kb / "目录甲" / "目录乙" / "目录丙" / "big.md"
+ big.write_text("# 大文档\n\n" + ("这是一段较长的正文内容。" * 1200), encoding="utf-8")
+ out = await self._rewrite(
+ self._parser(), kb,
+ "[x](./目录甲/目录乙/目录丙/big.md#不存在的章节)",
+ )
+ assert out == "[x](../目录甲/目录乙/目录丙/big/)"
+
+ async def test_multiple_links_on_one_line(self, tmp_path: Path):
+ kb = self._make_tree(tmp_path)
+ out = await self._rewrite(
+ self._parser(), kb,
+ "a [1](./目录甲/目录乙/目录丙/文档.md) b ![p](./img/a.png)",
+ )
+ assert out == (
+ "a [1](../目录甲/目录乙/目录丙/文档/) "
+ "b ![p](../img/a.png)"
+ )
+
+ async def test_future_bare_file_layout_points_at_file(self, tmp_path: Path):
+ """前瞻:若 MarkdownParser 改为小 .md 不再拆成目录(in-memory parse 得到裸
+ 文件 layout),重写自动指向文件而非目录——落点完全由 layout 决定、无目录化假设。
+ 无需改 _rewrite_single_link,只要 parse_content 的产物变了就自动跟随。"""
+ kb = self._make_tree(tmp_path)
+ p = self._parser()
+
+ async def fake_bare_layout(_path): # 模拟未来:目标入库为单个裸文件,无 <dir>/ 包裹
+ return {"文档.md": "# 目标\n\n内容"}
+
+ p._target_split_files = fake_bare_layout # type: ignore[method-assign]
+ base = "./目录甲/目录乙/目录丙/文档.md"
+ # 无 suffix → 文件本身(无尾斜杠),而非 文档/ 目录
+ assert await self._rewrite(p, kb, f"[x]({base})") == "[x](../目录甲/目录乙/目录丙/文档.md)"
+ # ?query → 文件 + 保留查询串
+ assert await self._rewrite(p, kb, f"[x]({base}?v=1)") == "[x](../目录甲/目录乙/目录丙/文档.md?v=1)"
+ # #anchor → 文件 + 保留锚点(裸单文件内任意锚点仍有效)
+ assert await self._rewrite(p, kb, f"[x]({base}#任意)") == "[x](../目录甲/目录乙/目录丙/文档.md#任意)"
+
+
+class TestSectionSubpath:
+ def _parser(self) -> MarkdownParser:
+ return MarkdownParser()
+
+ def test_file_directly_under_root_is_empty(self):
+ root = "viking://temp/x/文档"
+ assert self._parser()._section_subpath(f"{root}/文档.md", root) == ""
+
+ def test_file_in_subdir(self):
+ root = "viking://temp/x/文档"
+ uri = f"{root}/二、示例小节/sec_1.md"
+ assert self._parser()._section_subpath(uri, root) == "二、示例小节"
+
+ def test_file_in_nested_subdir(self):
+ root = "viking://temp/x/文档"
+ uri = f"{root}/a/b/sec.md"
+ assert self._parser()._section_subpath(uri, root) == "a/b"
+
+
+class FakeVikingFS:
+ """Minimal VikingFS mock that records calls and supports merge ops."""
+
+ def __init__(self):
+ self.dirs = []
+ self.files = {}
+ self._temp_counter = 0
+
+ async def mkdir(self, uri, exist_ok=False, **kw):
+ if uri not in self.dirs:
+ self.dirs.append(uri)
+
+ async def write(self, uri, data):
+ if isinstance(data, str):
+ data = data.encode("utf-8")
+ self.files[uri] = data
+ return uri
+
+ async def write_file(self, uri, content):
+ if isinstance(content, str):
+ content = content.encode("utf-8")
+ self.files[uri] = content
+
+ async def write_file_bytes(self, uri, content):
+ self.files[uri] = content
+
+ async def read(self, uri, offset=0, size=-1):
+ return self.files.get(uri, b"")
+
+ async def ls(self, uri, node_limit=None):
+ prefix = uri.rstrip("/") + "/"
+ children = {}
+ for key in list(self.files.keys()) + self.dirs:
+ if key.startswith(prefix):
+ rest = key[len(prefix):]
+ if rest:
+ child_name = rest.split("/")[0]
+ is_deeper = "/" in rest[len(child_name):]
+ child_full = f"{prefix}{child_name}"
+ is_dir = children.get(child_name, False) or is_deeper or child_full in self.dirs
+ children[child_name] = is_dir
+ result = []
+ for name in sorted(children):
+ child_uri = f"{uri.rstrip('/')}/{name}"
+ result.append({
+ "name": name, "uri": child_uri,
+ "isDir": children[name],
+ "type": "directory" if children[name] else "file",
+ })
+ return result
+
+ async def move_file(self, from_uri, to_uri):
+ if from_uri in self.files:
+ self.files[to_uri] = self.files.pop(from_uri)
+
+ async def delete_temp(self, temp_uri):
+ prefix = temp_uri.rstrip("/") + "/"
+ to_del = [k for k in self.files if k == temp_uri or k.startswith(prefix)]
+ for k in to_del:
+ del self.files[k]
+ self.dirs = [d for d in self.dirs if d != temp_uri and not d.startswith(prefix)]
+
+ def create_temp_uri(self):
+ self._temp_counter += 1
+ return f"viking://temp/md_{self._temp_counter}"
+
+
+def _decode(v):
+ return v.decode("utf-8") if isinstance(v, bytes) else v
+
+
+class TestParseContentRewiring:
+ async def test_parse_content_rewrites_link_when_enabled(self, tmp_path: Path):
+ kb = tmp_path / "knowledge"
+ tgt = kb / "目录甲" / "目录乙" / "目录丙"
+ tgt.mkdir(parents=True)
+ (tgt / "文档.md").write_text("# 目标\n\n内容", encoding="utf-8")
+ src = kb / "文档.md"
+ src.write_text(
+ "见 [x](./目录甲/目录乙/目录丙/文档.md)", encoding="utf-8"
+ )
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ await MarkdownParser().parse(
+ str(src), enable_link_rewrite=True, link_rewrite_root=str(kb)
+ )
+
+ written = [_decode(c) for u, c in fake.files.items() if "见" in _decode(c)]
+ assert written, fake.files
+ assert "../目录甲/目录乙/目录丙/文档/" in written[0]
+
+ async def test_parse_content_no_rewrite_when_disabled(self, tmp_path: Path):
+ kb = tmp_path / "knowledge"
+ tgt = kb / "目录甲" / "目录乙" / "目录丙"
+ tgt.mkdir(parents=True)
+ (tgt / "文档.md").write_text("# 目标\n\n内容", encoding="utf-8")
+ src = kb / "文档.md"
+ src.write_text(
+ "见 [x](./目录甲/目录乙/目录丙/文档.md)", encoding="utf-8"
+ )
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ await MarkdownParser().parse(str(src)) # rewrite disabled by default
+
+ written = [_decode(c) for u, c in fake.files.items() if "见" in _decode(c)]
+ assert written, fake.files
+ assert "./目录甲/目录乙/目录丙/文档.md" in written[0]
+
+ async def test_no_rewrite_without_import_root(self, tmp_path: Path):
+ # enable_link_rewrite=True but no link_rewrite_root (the single-file path):
+ # without an ingest root there is nothing to bound against, so do NOT rewrite.
+ kb = tmp_path / "knowledge"
+ tgt = kb / "目录甲" / "目录乙" / "目录丙"
+ tgt.mkdir(parents=True)
+ (tgt / "文档.md").write_text("# 目标\n\n内容", encoding="utf-8")
+ src = kb / "文档.md"
+ src.write_text(
+ "见 [x](./目录甲/目录乙/目录丙/文档.md)", encoding="utf-8"
+ )
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ await MarkdownParser().parse(str(src), enable_link_rewrite=True)
+
+ written = [_decode(c) for u, c in fake.files.items() if "见" in _decode(c)]
+ assert written, fake.files
+ assert "./目录甲/目录乙/目录丙/文档.md" in written[0]
+
+
+class TestDirectoryEndToEnd:
+ async def test_directory_ingest_rewrites_cross_file_link(self, tmp_path: Path):
+ kb = tmp_path / "knowledge"
+ tgt = kb / "目录甲" / "目录乙" / "目录丙"
+ tgt.mkdir(parents=True)
+ (tgt / "文档.md").write_text("# 目标\n\n内容", encoding="utf-8")
+ (kb / "文档.md").write_text(
+ "见 [x](./目录甲/目录乙/目录丙/文档.md)", encoding="utf-8"
+ )
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ await DirectoryParser().parse(str(kb))
+
+ written = [_decode(c) for c in fake.files.values() if "见" in _decode(c)]
+ assert written, fake.files
+ assert "../目录甲/目录乙/目录丙/文档/" in written[0]
+
+ async def test_directory_flat_mode_does_not_rewrite(self, tmp_path: Path):
+ # preserve_structure=False -> rewrite disabled -> links left untouched.
+ kb = tmp_path / "knowledge"
+ sub = kb / "sub"
+ sub.mkdir(parents=True)
+ (sub / "target.md").write_text("# 目标\n\n内容", encoding="utf-8")
+ (kb / "root.md").write_text("见 [x](./sub/target.md)", encoding="utf-8")
+
+ fake = FakeVikingFS()
+ with patch.object(BaseParser, "_get_viking_fs", return_value=fake):
+ await DirectoryParser().parse(str(kb), preserve_structure=False)
+
+ written = [_decode(c) for c in fake.files.values() if "见" in _decode(c)]
+ assert written, fake.files
+ assert "./sub/target.md" in written[0]