feat(knowledge): 可跳转 wikilink + 真实相关 note + 一对话多页
- [[wikilink]] 解析器:note id / vault_path / 标题 / vault 元页 / missing
- 前端 MarkdownRenderer 把非数字 [[...]] 渲染成可点链接,元页弹窗查看,缺失置灰
- vault 脚手架补建项目 hub 页,三个结构性链接(index/taxonomy/hub)始终可跳
- capture 时按标题+摘要+区分性标签检索同主题 note,注入真实 [[标题]] 到 Related + 记 related 图谱边
- LLM 提取支持 notes[] 数组,一次对话拆 1~4 页并按标题互链(multi_note_enabled 开关)
- 新增接口 POST /resolve、GET /notes/{id}/wikilinks、GET /vault-page
- 新增配置 related_notes_enabled / related_notes_limit / multi_note_enabled
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
1 parent
92a46003f8
commit
df3fac1032
13 files changed
+668
-72
No files matched your search
@@ -18,7 +18,7 @@ from deerflow.config.runtime_paths import runtime_home
|
||||
from deerflow.knowledge import extractor, llm_extractor
|
||||
from deerflow.knowledge.chunking import chunk_markdown
|
||||
from deerflow.knowledge.embeddings import EmbeddingClient
|
||||
from deerflow.knowledge.markdown_vault import MarkdownVault
|
||||
from deerflow.knowledge.markdown_vault import MarkdownVault, VaultPathError, extract_wikilinks, normalize_wikilink_target
|
||||
from deerflow.knowledge.obsidian_adapter import ObsidianWikiAdapter
|
||||
from deerflow.knowledge.repository import KnowledgeRepository
|
||||
from deerflow.knowledge.schemas import NoteDraft, SourceDraft, normalize_source_type, normalize_status
|
||||
@@ -39,6 +39,24 @@ def _resolve_vault_dir(vault_dir: str) -> Path:
|
||||
return (runtime_home() / vault_dir).resolve()
|
||||
|
||||
|
||||
def _inject_related_notes(body: str, links: list[str]) -> str:
|
||||
"""Insert real related-note ``[[wikilinks]]`` at the top of the Related block.
|
||||
|
||||
Keeps the structural meta-links (index / taxonomy / hub) that the extractor
|
||||
already rendered, but surfaces the content-specific related notes first. When
|
||||
there is no ``## Related`` section, one is appended.
|
||||
"""
|
||||
if not links:
|
||||
return body
|
||||
bullets = "\n".join(f"- {link}" for link in links)
|
||||
marker = "## Related\n"
|
||||
idx = body.find(marker)
|
||||
if idx == -1:
|
||||
return body.rstrip() + "\n\n## Related\n\n" + bullets + "\n"
|
||||
insert_at = idx + len(marker)
|
||||
return body[:insert_at] + "\n" + bullets + "\n" + body[insert_at:]
|
||||
|
||||
|
||||
class KnowledgeService:
|
||||
"""Application-facing knowledge base API."""
|
||||
|
||||
@@ -75,9 +93,56 @@ class KnowledgeService:
|
||||
logger.info("Knowledge redaction applied to note '%s': %s", draft.title, ",".join(sorted(set(body_hits))))
|
||||
return draft
|
||||
|
||||
async def _find_related_notes(self, draft: NoteDraft) -> list[dict[str, Any]]:
|
||||
"""Find existing notes on the same topic to cross-link under ## Related.
|
||||
|
||||
Uses the existing keyword/hybrid search over the title (+ summary). The
|
||||
draft's own note does not exist yet, so we exclude same-title hits to
|
||||
avoid self-links when re-capturing or deduping. Best-effort: any failure
|
||||
yields no links rather than blocking the capture.
|
||||
"""
|
||||
if not self.config.related_notes_enabled:
|
||||
return []
|
||||
# Build a topical query from the title + summary + the note's *distinctive*
|
||||
# tags (the per-note project/knowledge-base defaults are dropped, else
|
||||
# every note would match every other). CJK runs tokenize as a single
|
||||
# token, so shared distinctive tags are what make cross-topic matches work.
|
||||
default_tags = {t.lower() for t in (self.project_name or "", "knowledge-base", "deerflow") if t}
|
||||
distinctive = [t for t in (draft.tags or []) if t and t.lower() not in default_tags]
|
||||
query = " ".join(p for p in [draft.title or "", draft.summary or "", *distinctive] if p).strip()
|
||||
if not query:
|
||||
return []
|
||||
limit = max(1, self.config.related_notes_limit)
|
||||
mode = "hybrid" if self.embedding_client.is_enabled() else "keyword"
|
||||
try:
|
||||
items = await search_notes(self.repo, query, mode=mode, limit=limit + 3, embedding_client=self.embedding_client)
|
||||
except Exception:
|
||||
logger.exception("Failed to find related notes for '%s'", draft.title)
|
||||
return []
|
||||
own_title = (draft.title or "").strip().lower()
|
||||
out: list[dict[str, Any]] = []
|
||||
seen: set[str] = set()
|
||||
for it in items:
|
||||
nid = it.get("note_id")
|
||||
title = (it.get("title") or "").strip()
|
||||
if not nid or nid in seen or not title:
|
||||
continue
|
||||
if title.lower() == own_title: # the draft itself / a duplicate
|
||||
continue
|
||||
seen.add(nid)
|
||||
out.append({"id": nid, "title": title})
|
||||
if len(out) >= limit:
|
||||
break
|
||||
return out
|
||||
|
||||
async def _persist_draft(self, draft: NoteDraft, *, created_by: str | None) -> dict[str, Any]:
|
||||
"""Create a DB row, write the vault file, attach sources, return note."""
|
||||
draft = self._redact_draft(draft)
|
||||
related_notes = await self._find_related_notes(draft)
|
||||
if related_notes:
|
||||
real_links = [f"[[{n['title']}]]" for n in related_notes]
|
||||
draft.content_md = _inject_related_notes(draft.content_md, real_links)
|
||||
draft.related = list(dict.fromkeys([*real_links, *draft.related]))
|
||||
note = await self.repo.create_note(
|
||||
title=draft.title,
|
||||
summary=draft.summary,
|
||||
@@ -100,6 +165,13 @@ class KnowledgeService:
|
||||
await self.repo.add_sources(note_id, draft.sources, created_by=created_by)
|
||||
await self._reindex_embeddings(note_id, draft.content_md)
|
||||
await self._store_entities(note_id, draft)
|
||||
# Record note→note "related" edges (after _store_entities, which clears
|
||||
# this note's relations) so the graph reflects the cross-links too.
|
||||
for rel_note in related_notes:
|
||||
try:
|
||||
await self.repo.add_relation(from_note_id=note_id, to_note_id=rel_note["id"], relation_type="related")
|
||||
except Exception:
|
||||
logger.exception("Failed to link related note %s -> %s", note_id, rel_note["id"])
|
||||
return await self.repo.get_note(note_id) or note
|
||||
|
||||
async def _store_entities(self, note_id: str, draft: NoteDraft) -> None:
|
||||
@@ -173,12 +245,13 @@ class KnowledgeService:
|
||||
if include_sources and reference_batches:
|
||||
sources = from_reference_batches(reference_batches, thread_id=thread_id, max_items=self.config.max_source_items)
|
||||
|
||||
draft: NoteDraft | None = None
|
||||
drafts: list[NoteDraft] = []
|
||||
# Prefer LLM distillation (wiki-capture style) so notes are declarative
|
||||
# knowledge, not raw chat. Falls back to the rule-based extractor when
|
||||
# the LLM is disabled/unavailable or returns something unusable.
|
||||
# knowledge, not raw chat. A single conversation may split into several
|
||||
# cross-linked notes. Falls back to the rule-based extractor (always one
|
||||
# note) when the LLM is disabled/unavailable or returns nothing usable.
|
||||
if self.config.llm_extract_enabled:
|
||||
draft = await llm_extractor.extract_thread_llm(
|
||||
drafts = await llm_extractor.extract_thread_llm_multi(
|
||||
messages,
|
||||
thread_id=thread_id,
|
||||
thread_title=thread_title,
|
||||
@@ -190,9 +263,10 @@ class KnowledgeService:
|
||||
max_messages=self.config.max_thread_messages,
|
||||
model_name=self.config.extract_model_name,
|
||||
max_input_chars=self.config.extract_max_input_chars,
|
||||
allow_multi=self.config.multi_note_enabled,
|
||||
)
|
||||
if draft is None:
|
||||
draft = extractor.extract_thread(
|
||||
if not drafts:
|
||||
single = extractor.extract_thread(
|
||||
messages,
|
||||
thread_id=thread_id,
|
||||
thread_title=thread_title,
|
||||
@@ -203,11 +277,24 @@ class KnowledgeService:
|
||||
sources=sources,
|
||||
max_messages=self.config.max_thread_messages,
|
||||
)
|
||||
if draft is None:
|
||||
drafts = [single] if single else []
|
||||
if not drafts:
|
||||
raise EmptyThreadError(f"Thread {thread_id} has no sediment-able content")
|
||||
draft.status = normalize_status(status)
|
||||
note = await self._persist_draft(draft, created_by=created_by)
|
||||
return {"note": note, "created": True}
|
||||
|
||||
normalized = normalize_status(status)
|
||||
for draft in drafts:
|
||||
draft.status = normalized
|
||||
# Cross-link sibling notes from the same conversation by title, so the
|
||||
# split pages reference each other (resolved once all are persisted).
|
||||
if len(drafts) > 1:
|
||||
for i, draft in enumerate(drafts):
|
||||
siblings = [f"[[{o.title}]]" for j, o in enumerate(drafts) if j != i and o.title]
|
||||
if siblings:
|
||||
draft.content_md = _inject_related_notes(draft.content_md, siblings)
|
||||
draft.related = list(dict.fromkeys([*siblings, *draft.related]))
|
||||
|
||||
notes = [await self._persist_draft(draft, created_by=created_by) for draft in drafts]
|
||||
return {"note": notes[0], "created": True, "notes": notes}
|
||||
|
||||
async def capture_search(
|
||||
self,
|
||||
@@ -357,6 +444,84 @@ class KnowledgeService:
|
||||
logger.exception("Failed to archive knowledge note %s in vault", note_id)
|
||||
return True
|
||||
|
||||
# -- wikilinks --------------------------------------------------------
|
||||
async def resolve_wikilink(self, target: str) -> dict[str, Any]:
|
||||
"""Resolve a single ``[[wikilink]]`` target to a navigable destination.
|
||||
|
||||
Returns one of:
|
||||
- ``{"kind": "note", "note_id", "title", "exists": True}`` — a knowledge note
|
||||
- ``{"kind": "vault", "vault_path", "title", "exists": True}`` — a vault meta/hub page
|
||||
- ``{"kind": "missing", "exists": False}`` — nothing matches
|
||||
|
||||
Resolution order: note id → note vault_path → note title → vault file.
|
||||
"""
|
||||
norm = normalize_wikilink_target(target)
|
||||
base = {"target": target, "normalized": norm}
|
||||
if not norm:
|
||||
return {**base, "kind": "missing", "exists": False}
|
||||
|
||||
# 1) Direct note id (e.g. "kb_abc...").
|
||||
if norm.startswith("kb_"):
|
||||
note = await self.repo.get_note(norm, with_sources=False)
|
||||
if note and note.get("status") != "archived":
|
||||
return {**base, "kind": "note", "note_id": note["id"], "title": note["title"], "exists": True}
|
||||
|
||||
# 2) Note by vault path (links from index.md / hot.md / structural hub).
|
||||
note = await self.repo.find_by_vault_path(norm)
|
||||
if note:
|
||||
return {**base, "kind": "note", "note_id": note["id"], "title": note["title"], "exists": True}
|
||||
|
||||
# 3) Note by title (the real related-note cross-links use [[Title]]).
|
||||
note = await self.repo.find_by_title(norm) or await self.repo.find_by_title(norm.split("/")[-1])
|
||||
if note:
|
||||
return {**base, "kind": "note", "note_id": note["id"], "title": note["title"], "exists": True}
|
||||
|
||||
# 4) A vault meta/hub page that has no DB note (index, _meta/taxonomy, hub…).
|
||||
page = self.read_vault_page(norm)
|
||||
if page is not None:
|
||||
return {**base, "kind": "vault", "vault_path": page["path"], "title": page["title"], "exists": True}
|
||||
|
||||
return {**base, "kind": "missing", "exists": False}
|
||||
|
||||
async def resolve_wikilinks(self, targets: list[str]) -> dict[str, dict[str, Any]]:
|
||||
"""Resolve many targets at once; returns ``{original_target: resolution}``."""
|
||||
out: dict[str, dict[str, Any]] = {}
|
||||
for target in dict.fromkeys(t for t in targets if t and t.strip()):
|
||||
out[target] = await self.resolve_wikilink(target)
|
||||
return out
|
||||
|
||||
async def resolve_note_wikilinks(self, note_id: str) -> dict[str, dict[str, Any]] | None:
|
||||
"""Extract every ``[[wikilink]]`` in a note's body and resolve them.
|
||||
|
||||
Returns ``{target: resolution}`` or ``None`` when the note is missing.
|
||||
Numeric ``[[123]]`` citation badges are skipped (handled by the renderer).
|
||||
"""
|
||||
note = await self.repo.get_note(note_id, with_sources=False)
|
||||
if note is None:
|
||||
return None
|
||||
targets = [t for t in extract_wikilinks(note.get("content_md") or "") if not t.isdigit()]
|
||||
return await self.resolve_wikilinks(targets)
|
||||
|
||||
def read_vault_page(self, path: str) -> dict[str, Any] | None:
|
||||
"""Read a raw vault Markdown page (meta/hub pages without a DB note).
|
||||
|
||||
Returns ``{"path", "title", "content_md"}`` or ``None`` if the page does
|
||||
not exist or the path escapes the vault root.
|
||||
"""
|
||||
norm = normalize_wikilink_target(path)
|
||||
if not norm:
|
||||
return None
|
||||
rel = f"{norm}.md"
|
||||
try:
|
||||
parsed = self.adapter.vault.read_note(rel)
|
||||
except VaultPathError:
|
||||
return None
|
||||
if parsed is None:
|
||||
return None
|
||||
fm, body = parsed
|
||||
title = str(fm.get("title") or "").strip() or norm.split("/")[-1]
|
||||
return {"path": norm, "title": title, "content_md": body}
|
||||
|
||||
# -- search & graph ---------------------------------------------------
|
||||
async def search(self, query: str, *, mode: str = "keyword", limit: int = 8) -> list[dict[str, Any]]:
|
||||
return await search_notes(self.repo, query, mode=mode, limit=limit, embedding_client=self.embedding_client)
|
||||
|
||||
Reference in new issue
Block a user