jfox-cli 1.2.1__tar.gz → 1.2.2__tar.gz

{jfox_cli-1.2.1 → jfox_cli-1.2.2}/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [1.2.2] - 2026-06-28
+
+### Fixes
+- **gem-synth**: 剥 claude markdown 代码围栏，修合成全失败 (#283) (#288)
+- **add**: 创建目标笔记后回填引用方的正向 links (#276)
+
+[1.2.2]: https://github.com/zhuxixi/jfox/compare/v1.2.1...v1.2.2
+
 ## [1.2.1] - 2026-06-26
 
 ### Features

{jfox_cli-1.2.1 → jfox_cli-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jfox-cli
-Version: 1.2.1
+Version: 1.2.2
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox

{jfox_cli-1.2.1 → jfox_cli-1.2.2}/jfox/__init__.py

@@ -1,5 +1,5 @@
 """JFox - Zettelkasten 知识管理工具"""
 
-__version__ = "1.2.1"
+__version__ = "1.2.2"
 __author__ = "User"
 __email__ = "user@example.com"

{jfox_cli-1.2.1 → jfox_cli-1.2.2}/jfox/cli.py

@@ -255,11 +255,9 @@ def _print_action_table(action: str, fields: dict):
 
 def extract_wiki_links(content: str) -> List[str]:
     """从内容中提取 [[...]] 格式的维基链接"""
-    import re
+    from .note_index import extract_wiki_links_from_text
 
-    pattern = r"\[\[(.*?)\]\]"
-    matches = re.findall(pattern, content)
-    return [m.strip() for m in matches]
+    return extract_wiki_links_from_text(content)
 
 
 def find_note_id_by_title_or_id(
@@ -380,8 +378,8 @@ def _rebuild_backlinks_impl(output_format: str = "table") -> Dict[str, Any]:
     changed_note_ids: List[str] = []
 
     for n in notes:
-        # 注意：cli.py 模块级存在名为 list 的命令函数，会遮蔽 built-in list()，
-        # 因此这里使用切片复制列表。
+        # list 命令函数已重命名为 list_notes，不再遮蔽 built-in list()。
+        # 保留切片复制以避免原地修改遍历中的列表。
         old_links = n.links[:]
         old_backlinks = n.backlinks[:]
         new_links_sorted = merged_links[n.id]
@@ -528,6 +526,74 @@ def _add_note_impl(
                     note.save_note(target_note, add_to_index=False)
                     backlink_updated += 1
 
+        # Backward 回填：正文中引用了新笔记标题但 links 未包含新笔记 ID 的笔记
+        # 把新笔记 ID 回填进它们的 links，并同步更新新笔记的 backlinks
+        from .note_index import get_note_index
+
+        idx = get_note_index()
+        idx.update_note_meta(new_note)
+
+        original_backlinks_count = len(new_note.backlinks)
+        forward_backfilled = 0
+        failed_refs: List[str] = []
+        rollback_failures: List[str] = []
+        backfilled_ref_ids: List[str] = []
+        for ref_meta in idx.find_notes_referencing_title(new_note.title):
+            if ref_meta.id == new_note.id:
+                continue
+            ref_note = note.load_note_by_id(ref_meta.id)
+            if not ref_note:
+                continue
+
+            ref_changed = new_note.id not in ref_note.links
+            backlink_changed = ref_note.id not in new_note.backlinks
+
+            if ref_changed:
+                ref_note.links.append(new_note.id)
+            if backlink_changed:
+                new_note.backlinks.append(ref_note.id)
+
+            if not ref_changed:
+                # ref_note.links 已包含新笔记，只需补齐 new_note.backlinks
+                continue
+
+            if note.save_note(ref_note, add_to_index=False):
+                forward_backfilled += 1
+                idx.update_note_meta(ref_note)
+                backfilled_ref_ids.append(ref_note.id)
+            else:
+                # save_note 内部已吞掉所有异常并返回 False；回滚内存修改保持双向一致
+                if new_note.id in ref_note.links:
+                    ref_note.links.remove(new_note.id)
+                if backlink_changed and ref_note.id in new_note.backlinks:
+                    new_note.backlinks.remove(ref_note.id)
+                failed_refs.append(ref_note.id)
+                logger.warning(f"回填正向链接时保存笔记 {ref_note.id} 失败")
+
+        new_note_backfill_save_failed = False
+        if len(new_note.backlinks) != original_backlinks_count:
+            if note.save_note(new_note, add_to_index=False):
+                idx.update_note_meta(new_note)
+            else:
+                new_note_backfill_save_failed = True
+                logger.warning("回填后保存新笔记 backlinks 失败")
+                # 回滚已持久化的 ref_note 正向链接，避免 links/backlinks 不一致
+                for ref_id in backfilled_ref_ids:
+                    rb_note = note.load_note_by_id(ref_id)
+                    if not rb_note:
+                        rollback_failures.append(ref_id)
+                        logger.warning(f"回滚时无法加载 ref_note {ref_id}")
+                        continue
+                    if new_note.id in rb_note.links:
+                        rb_note.links.remove(new_note.id)
+                        if note.save_note(rb_note, add_to_index=False):
+                            idx.update_note_meta(rb_note)
+                        else:
+                            rollback_failures.append(ref_id)
+                            logger.warning(f"回滚 ref_note {ref_id} 正向链接失败")
+                # 回滚内存中的 new_note.backlinks
+                new_note.backlinks = new_note.backlinks[:original_backlinks_count]
+
         result = {
             "success": True,
             "note": {
@@ -541,6 +607,12 @@ def _add_note_impl(
 
         if unresolved:
             result["warnings"] = f"Unresolved links: {', '.join(unresolved)}"
+        if failed_refs:
+            result["backfill_failures"] = failed_refs
+        if rollback_failures:
+            result["rollback_failures"] = rollback_failures
+        if new_note_backfill_save_failed:
+            result["backfill_note_save_failed"] = True
 
         if output_format == "json":
             print(output_json(result))
@@ -556,6 +628,26 @@ def _add_note_impl(
             )
             if backlink_updated > 0:
                 console.print(f"[dim]  Backlinks updated: {backlink_updated} note(s)[/dim]")
+            if forward_backfilled > 0:
+                console.print(
+                    f"[dim]  Forward links backfilled: {forward_backfilled} note(s)[/dim]"
+                )
+            if new_note_backfill_save_failed:
+                console.print(
+                    "  [yellow]Warning: Failed to save new note backlinks; "
+                    "forward backfill has been rolled back[/yellow]"
+                )
+            if failed_refs:
+                console.print(
+                    f"  [yellow]Warning: Forward link backfill failed for "
+                    f"{len(failed_refs)} note(s): {', '.join(failed_refs)}[/yellow]"
+                )
+            if rollback_failures:
+                console.print(
+                    f"  [red]Warning: Forward link rollback failed for "
+                    f"{len(rollback_failures)} note(s): {', '.join(rollback_failures)}. "
+                    f"Run 'jfox index rebuild --backlinks' to repair.[/red]"
+                )
             if unresolved:
                 console.print(
                     f"  [yellow]Warning: Unresolved links - {', '.join(unresolved)}[/yellow]"
@@ -1028,8 +1120,8 @@ def _list_impl(
         raise ValueError(f"Unsupported format: {output_format}")
 
 
-@app.command()
-def list(
+@app.command(name="list")
+def list_notes(
     note_type: Optional[str] = typer.Option(None, "--type", "-t", help="筛选笔记类型"),
     tags: Optional[List[str]] = typer.Option(
         None, "--tag", help="按标签筛选（可多次使用，AND 逻辑）"

{jfox_cli-1.2.1 → jfox_cli-1.2.2}/jfox/gem_synth/llm.py

@@ -28,7 +28,8 @@ SYSTEM_PROMPT = """你是知识合成器。给定一段对话上下文和若干
   "knowledge_type": "factual|procedural|preference|constraint",
   "grounded_by": ["引用的永久笔记标题列表"]
 }
-若上下文不足以合成有效知识，confidence 给低分（<0.3）并简述原因。不要编造基准里没有的事实。"""
+若上下文不足以合成有效知识，confidence 给低分（<0.3）并简述原因。不要编造基准里没有的事实。
+直接输出 JSON 对象本身，不要用 markdown 代码围栏包裹（不要 ```json ... ```）。"""
 
 
 def _resolve_claude_binary(cfg: GemSynthesisConfig) -> str:
@@ -204,6 +205,46 @@ def _invoke_claude(
                 pass
 
 
+def _parse_json_lenient(inner: Any) -> Optional[Dict[str, Any]]:
+    """从模型输出解析 JSON 对象，容忍 markdown 围栏 / 前导解释文本 / 前置代码块 / 尾部噪声。
+
+    模型常把 JSON 包在 ```json ... ``` 里，或前后加解释文本/代码示例。早期用 fence-strip
+    正则提取，但当 JSON 的 content 字段内部含 ``` 代码示例（代码宝石常见）时，正则会把
+    内部 ``` 当外层围栏终点、截断 JSON（kimi R3/R4 issue-4/5）。正则路径本质脆弱。
+
+    改解析式（JSON 解析器尊重字符串字面量，content 内的 ``` / { 干扰不了它）：
+    1. 直接 json.loads（裸 JSON：含 content 内代码围栏也安全，因 ``` 在字符串字面量内）
+    2. 失败则扫描所有 { 位置，各自 raw_decode，取**跨度最大**的有效 JSON 对象——目标 gem
+       比前导文本/代码块里的零散小对象（如 python 字典示例）更长，故胜出；schema 无关，
+       且 content 内的 { 其片段跨度也小于整个 gem（kimi R5 issue-6）
+    3. 都失败返回 None（调用方 mark_failed）
+    """
+    if isinstance(inner, dict):
+        return inner
+    if not isinstance(inner, str):
+        return None
+    s = inner.strip()
+    try:
+        obj = json.loads(s)
+        return obj if isinstance(obj, dict) else None
+    except json.JSONDecodeError:
+        pass
+    # 扫描所有 {，raw_decode 各自尝试，取跨度最大（字符最多）的有效 JSON 对象
+    decoder = json.JSONDecoder()
+    best: Optional[Dict[str, Any]] = None
+    best_end = -1
+    for i, ch in enumerate(s):
+        if ch != "{":
+            continue
+        try:
+            obj, end = decoder.raw_decode(s[i:])
+        except json.JSONDecodeError:
+            continue
+        if isinstance(obj, dict) and end > best_end:
+            best, best_end = obj, end
+    return best
+
+
 def synthesize_with_llm(
     turn_context: str,
     grounding: List[Dict[str, Any]],
@@ -223,7 +264,8 @@ def synthesize_with_llm(
         raw = _invoke_claude(prompt, cfg, stop_event)
         wrapper = json.loads(raw)
         inner = wrapper.get("result", raw) if isinstance(wrapper, dict) else raw
-        parsed = json.loads(inner) if isinstance(inner, str) else inner
+        # 容忍 markdown 围栏/前导文本：解析式提取 JSON（content 内代码围栏也安全）
+        parsed = _parse_json_lenient(inner)
         if not isinstance(parsed, dict) or "title" not in parsed:
             logger.warning("LLM 输出缺 title: %r", parsed)
             logger.debug("LLM raw output: %r", raw)

{jfox_cli-1.2.1 → jfox_cli-1.2.2}/jfox/graph.py

@@ -7,7 +7,6 @@ Provides:
 - Hub and authority analysis
 """
 
-import re
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Dict, List, Optional, Set, Tuple
@@ -17,6 +16,7 @@ from rich.console import Console
 
 from .config import ZKConfig
 from .models import Note
+from .note_index import extract_wiki_links_from_text
 
 console = Console()
 
@@ -94,7 +94,7 @@ class KnowledgeGraph:
 
         # Third pass: extract and add wiki links from content [[...]]
         for note_id, note in self._note_cache.items():
-            wiki_links = self._extract_wiki_links(note.content)
+            wiki_links = extract_wiki_links_from_text(note.content)
             for link_text in wiki_links:
                 linked_id = self._resolve_link(link_text)
                 if linked_id and linked_id in self._note_cache:
@@ -104,12 +104,6 @@ class KnowledgeGraph:
 
         return self
 
-    def _extract_wiki_links(self, content: str) -> List[str]:
-        """Extract [[...]] wiki links from content."""
-        pattern = r"\[\[(.*?)\]\]"
-        matches = re.findall(pattern, content)
-        return [m.strip() for m in matches]
-
     def _resolve_link(self, link_text: str) -> Optional[str]:
         """Resolve a link text to a note ID."""
         # First try exact ID match

{jfox_cli-1.2.1 → jfox_cli-1.2.2}/jfox/note_index.py

@@ -1,6 +1,7 @@
 """轻量级元数据索引，只解析 frontmatter 不读正文"""
 
 import logging
+import re
 import time
 from dataclasses import dataclass, field
 from datetime import datetime
@@ -14,6 +15,41 @@ from .models import Note, NoteType, _to_bool
 
 logger = logging.getLogger(__name__)
 
+# 维基链接正则：匹配 [[标题]] 语法（非贪婪，不支持跨行）
+_WIKI_LINK_RE = re.compile(r"\[\[(.*?)\]\]")
+
+
+def extract_wiki_links_from_text(text: str) -> List[str]:
+    """从文本中提取 [[...]] 格式的维基链接。
+
+    支持常见变体：
+    - [[标题]]
+    - [[标题|别名]] -> 取标题部分
+    - [[标题#锚点]] -> 取标题部分
+    """
+    raw_links = [m.group(1).strip() for m in _WIKI_LINK_RE.finditer(text)]
+    return [_normalize_wiki_link_title(link) for link in raw_links]
+
+
+def _normalize_wiki_link_title(link_text: str) -> str:
+    """把 [[标题|别名]] / [[标题#锚点]] 归一化为纯标题。"""
+    # 先取管道符左侧的显示标题/目标
+    target = link_text.split("|", 1)[0]
+    # 再取锚点左侧的标题主体
+    return target.split("#", 1)[0].strip()
+
+
+def _strip_wiki_link_exclusions(text: str) -> str:
+    """移除不应参与 wiki-link 匹配的 Markdown 区域（fenced code block、HTML 注释）。
+
+    这是轻量级处理，覆盖最常见的误匹配场景；不保证解析所有 Markdown 边界情况。
+    """
+    # fenced code block（支持可选语言标识）
+    text = re.sub(r"```[\s\S]*?```", "", text)
+    # HTML 注释
+    text = re.sub(r"<!--[\s\S]*?-->", "", text)
+    return text
+
 
 @dataclass
 class NoteMeta:
@@ -68,6 +104,29 @@ def _parse_frontmatter_only(filepath: Path) -> Optional[dict]:
         return None
 
 
+def _read_body_after_frontmatter(filepath: Path) -> str:
+    """读取文件正文部分（跳过 frontmatter）。
+
+    若文件没有 frontmatter，则返回全文。
+    读取失败时返回空字符串。
+    """
+    try:
+        with open(filepath, "r", encoding="utf-8-sig") as f:
+            first_line = f.readline()
+            if first_line.strip() != "---":
+                # 没有 frontmatter，返回剩余全部内容
+                return first_line + f.read()
+
+            for line in f:
+                if line.strip() == "---":
+                    return f.read()
+
+            # 有开始标记但没有结束标记，视为无效 frontmatter
+            return ""
+    except (OSError, UnicodeDecodeError):
+        return ""
+
+
 class NoteIndex:
     """轻量级元数据索引，CLI 模式每次启动时重建"""
 
@@ -164,6 +223,39 @@ class NoteIndex:
         prefix_lower = prefix.lower()
         return [m for m in self._by_id.values() if m.title.lower().startswith(prefix_lower)]
 
+    def find_notes_referencing_title(self, title: str) -> List[NoteMeta]:
+        """查找正文中引用了指定标题的笔记（[[标题]] 语法）。
+
+        基于索引中已缓存的文件路径直接读取正文，避免全量加载 Note 对象。
+        匹配规则为大小写不敏感的精确标题匹配；frontmatter、 fenced code block、
+        HTML 注释中的 [[...]] 不参与匹配。支持 [[标题|别名]] / [[标题#锚点]] 变体。
+
+        注意：与正向解析 find_note_id_by_title_or_id 的“标题包含”子串 fallback 不同，
+        反向回填只回填精确标题引用，避免把 [[Foo]] 错误回填到标题为 "Foo Bar" 的笔记。
+
+        Args:
+            title: 被引用的笔记标题
+
+        Returns:
+            引用了该标题的 NoteMeta 列表
+        """
+        title_lower = title.lower()
+        results: List[NoteMeta] = []
+
+        for meta in self._by_id.values():
+            filepath = Path(meta.filepath)
+            if not filepath.exists():
+                continue
+
+            body = _read_body_after_frontmatter(filepath)
+            body = _strip_wiki_link_exclusions(body)
+            for link_text in extract_wiki_links_from_text(body):
+                if link_text.lower() == title_lower:
+                    results.append(meta)
+                    break
+
+        return results
+
     def list_meta(
         self,
         note_type: Optional[NoteType] = None,

{jfox_cli-1.2.1 → jfox_cli-1.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jfox-cli"
-version = "1.2.1"
+version = "1.2.2"
 description = "JFox - Zettelkasten 知识管理 CLI 工具"
 readme = "README.md"
 license = {text = "MIT"}