jfox-cli 0.1.3__tar.gz → 0.1.4__tar.gz

{jfox_cli-0.1.3 → jfox_cli-0.1.4}/CLAUDE.md

@@ -91,6 +91,7 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 
 ## Conventions
 
+- **Version bump**: 发版时必须同时修改 `pyproject.toml` 和 `jfox/__init__.py` 两处版本号（曾有 #88 遗漏 `__init__.py` 的教训）
 - **Line length**: 100 chars (black + ruff configured in `pyproject.toml`)
 - **Comments/docs**: Chinese (中文)
 - **Adding a CLI command**: Add `@app.command()` in `cli.py`, implement `_xxx_impl()` helper, add `--kb` and `--format json` support

{jfox_cli-0.1.3 → jfox_cli-0.1.4}/PKG-INFO

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

{jfox_cli-0.1.3 → jfox_cli-0.1.4}/jfox/__init__.py

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

{jfox_cli-0.1.3 → jfox_cli-0.1.4}/jfox/bm25_index.py

@@ -249,6 +249,78 @@ class BM25Index:
             logger.error(f"Failed to remove document {note_id}: {e}")
             return False
     
+    def add_documents_batch(self, documents: List[Tuple[str, str]]) -> bool:
+        """
+        批量添加文档到索引（高效版本）
+
+        与逐条调用 add_document() 不同，此方法收集所有文档后只执行一次索引重建和保存。
+        适用于批量导入场景。
+
+        Args:
+            documents: [(note_id, content), ...] 列表
+
+        Returns:
+            是否成功添加
+        """
+        if not documents:
+            return True
+
+        # 快照当前状态，失败时恢复
+        saved_docs = list(self.documents)
+        saved_ids = list(self.doc_ids)
+        saved_mapping = dict(self.doc_mapping)
+        saved_bm25 = self.bm25
+
+        try:
+            for note_id, content in documents:
+                # 如果已存在，先移除
+                if note_id in self.doc_mapping:
+                    # 内联移除逻辑，避免触发 rebuild/save
+                    idx = self.doc_mapping[note_id]
+                    self.documents.pop(idx)
+                    self.doc_ids.pop(idx)
+                    del self.doc_mapping[note_id]
+                    # 更新后续索引
+                    self.doc_mapping = {}
+                    for i, doc_id in enumerate(self.doc_ids):
+                        self.doc_mapping[doc_id] = i
+
+                # 分词并添加
+                tokens = self._tokenize(content)
+                if not tokens:
+                    continue  # 跳过分词结果为空的文档
+                idx = len(self.documents)
+                self.documents.append(tokens)
+                self.doc_ids.append(note_id)
+                self.doc_mapping[note_id] = idx
+
+            # 一次性重建索引
+            self._rebuild_index()
+
+            # 一次性保存，失败时回滚
+            if not self._save():
+                self.documents = saved_docs
+                self.doc_ids = saved_ids
+                self.doc_mapping = saved_mapping
+                self.bm25 = saved_bm25
+                logger.error("Failed to persist BM25 index after batch add, rolled back")
+                return False
+
+            logger.info(f"Batch added {len(documents)} documents to BM25 index")
+            return True
+
+        except Exception as e:
+            # 恢复到批次前的状态
+            self.documents = saved_docs
+            self.doc_ids = saved_ids
+            self.doc_mapping = saved_mapping
+            self.bm25 = saved_bm25
+            logger.error(
+                f"Failed to batch add {len(documents)} documents to BM25 index",
+                exc_info=True,
+            )
+            return False
+
     def search(self, query: str, top_k: int = 5) -> List[Dict]:
         """
         搜索文档

{jfox_cli-0.1.3 → jfox_cli-0.1.4}/jfox/cli.py

@@ -90,7 +90,8 @@ def init(
     path: Optional[str] = typer.Option(None, "--path", "-p", help="知识库路径（默认: ~/.zettelkasten/<name>/）"),
     description: Optional[str] = typer.Option(None, "--desc", "-d", help="知识库描述"),
     set_default: bool = typer.Option(True, "--default/--no-default", help="设为默认知识库"),
-    json_output: bool = typer.Option(True, "--json/--no-json", help="JSON 输出"),
+    output_format: str = typer.Option("table", "--format", "-f", help="输出格式: json, table"),
+    json_output: bool = typer.Option(False, "--json", help="JSON 输出（快捷方式，等同于 --format json）"),
 ):
     """
     初始化知识库
@@ -103,6 +104,10 @@ def init(
         jfox init --name personal --desc "个人笔记"
     """
     try:
+        # 向后兼容：--json 快捷方式
+        if json_output:
+            output_format = "json"
+
         kb_name = name or "default"
         manager = get_kb_manager()
         
@@ -112,7 +117,7 @@ def init(
                 "success": False,
                 "error": f"Knowledge base '{kb_name}' already exists. Use 'jfox kb list' to see all knowledge bases.",
             }
-            if json_output:
+            if output_format == "json":
                 print(output_json(result))
             else:
                 console.print(f"[red]✗[/red] Knowledge base '{kb_name}' already exists")
@@ -137,7 +142,7 @@ def init(
                         f"'{kb_root}'. All knowledge bases must be under {kb_root}/"
                     ),
                 }
-                if json_output:
+                if output_format == "json":
                     print(output_json(result))
                 else:
                     console.print(f"[red]✗[/red] {result['error']}")
@@ -157,36 +162,50 @@ def init(
                 "message": message,
                 "name": kb_name,
             }
-            
-            if json_output:
+
+            if output_format == "json":
                 print(output_json(result))
             else:
-                console.print(f"[green]✓[/green] {message}")
+                _print_action_table("init", {
+                    "KB": kb_name,
+                })
                 if set_default:
-                    console.print(f"[dim]This is now your default knowledge base[/dim]")
+                    console.print(f"[dim]  This is now your default knowledge base[/dim]")
         else:
             result = {
                 "success": False,
                 "error": message,
             }
-            if json_output:
+            if output_format == "json":
                 print(output_json(result))
             else:
                 console.print(f"[red]✗[/red] {message}")
             raise typer.Exit(1)
         
+    except typer.Exit:
+        raise
     except Exception as e:
         result = {
             "success": False,
             "error": str(e),
         }
-        if json_output:
+        if output_format == "json":
             print(output_json(result))
         else:
             console.print(f"[red]✗[/red] Error: {e}")
         raise typer.Exit(1)
 
 
+def _print_action_table(action: str, fields: dict):
+    """打印紧凑的操作结果表格（单行）"""
+    table = Table(show_header=True, box=None, padding=(0, 2))
+    table.add_column("Action", style="green")
+    for key in fields:
+        table.add_column(key)
+    table.add_row(action, *[str(v) for v in fields.values()])
+    console.print(table)
+
+
 def extract_wiki_links(content: str) -> List[str]:
     """从内容中提取 [[...]] 格式的维基链接"""
     import re
@@ -226,7 +245,7 @@ def _add_note_impl(
     note_type: str,
     tags: Optional[List[str]],
     source: Optional[str],
-    json_output: bool,
+    output_format: str,
     template: Optional[str] = None,
 ):
     """添加笔记的内部实现"""
@@ -318,20 +337,21 @@ def _add_note_impl(
                 "links": resolved_links,
             },
         }
-        
+
         if unresolved:
             result["warnings"] = f"Unresolved links: {', '.join(unresolved)}"
-        
-        if json_output:
+
+        if output_format == "json":
             print(output_json(result))
         else:
-            console.print(f"[green]✓[/green] Note created: {new_note.title}")
-            console.print(f"  ID: {new_note.id}")
-            console.print(f"  Path: {new_note.filepath}")
-            if resolved_links:
-                console.print(f"  Links: {len(resolved_links)} connection(s)")
+            _print_action_table("created", {
+                "ID": new_note.id,
+                "Title": new_note.title,
+                "Type": new_note.type.value,
+                "Links": str(len(resolved_links)),
+            })
             if backlink_updated > 0:
-                console.print(f"  Backlinks updated: {backlink_updated} note(s)")
+                console.print(f"[dim]  Backlinks updated: {backlink_updated} note(s)[/dim]")
             if unresolved:
                 console.print(f"  [yellow]Warning: Unresolved links - {', '.join(unresolved)}[/yellow]")
     else:
@@ -347,24 +367,31 @@ def add(
     source: Optional[str] = typer.Option(None, "--source", "-s", help="来源（文献笔记）"),
     template: Optional[str] = typer.Option(None, "--template", "-T", help="使用模板创建笔记 (quick/meeting/literature)"),
     kb: Optional[str] = typer.Option(None, "--kb", "-k", help="目标知识库名称"),
-    json_output: bool = typer.Option(True, "--json/--no-json", help="JSON 输出"),
+    output_format: str = typer.Option("table", "--format", "-f", help="输出格式: json, table"),
+    json_output: bool = typer.Option(False, "--json", help="JSON 输出（快捷方式，等同于 --format json）"),
 ):
     """添加新笔记（内容中可用 [[笔记标题]] 引用其他笔记）"""
     try:
+        # 向后兼容：--json 快捷方式
+        if json_output:
+            output_format = "json"
+
         # 如果指定了知识库，临时切换
         if kb:
             from .config import use_kb
             with use_kb(kb):
-                _add_note_impl(content, title, note_type, tags, source, json_output, template)
+                _add_note_impl(content, title, note_type, tags, source, output_format, template)
         else:
-            _add_note_impl(content, title, note_type, tags, source, json_output, template)
-            
+            _add_note_impl(content, title, note_type, tags, source, output_format, template)
+
+    except typer.Exit:
+        raise
     except Exception as e:
         result = {
             "success": False,
             "error": str(e),
         }
-        if json_output:
+        if output_format == "json":
             print(output_json(result))
         else:
             console.print(f"[red]✗[/red] Error: {e}")
@@ -824,18 +851,17 @@ def refs(
 def _delete_impl(
     note_id: str,
     force: bool,
-    json_output: bool,
+    output_format: str,
 ):
     """删除笔记的内部实现"""
     # 先查找笔记
     n = note.load_note_by_id(note_id)
     if not n:
-        console.print(f"[red]Note not found: {note_id}[/red]")
-        raise typer.Exit(1)
-    
+        raise ValueError(f"Note not found: {note_id}")
+
     # 确认删除
     if not force:
-        if json_output:
+        if output_format == "json":
             console.print(f"Use --force to delete: {n.title}")
             raise typer.Exit(1)
         else:
@@ -844,7 +870,7 @@ def _delete_impl(
             if confirm.lower() != "y":
                 console.print("Cancelled")
                 raise typer.Exit(0)
-    
+
     # 执行删除
     if note.delete_note(note_id):
         result = {
@@ -852,11 +878,14 @@ def _delete_impl(
             "deleted": note_id,
             "title": n.title,
         }
-        
-        if json_output:
+
+        if output_format == "json":
             print(output_json(result))
         else:
-            console.print(f"[green]✓[/green] Deleted: {n.title}")
+            _print_action_table("deleted", {
+                "ID": note_id,
+                "Title": n.title,
+            })
     else:
         raise Exception("Failed to delete note")
 
@@ -866,24 +895,195 @@ def delete(
     note_id: str = typer.Argument(..., help="笔记 ID"),
     force: bool = typer.Option(False, "--force", "-f", help="强制删除不确认"),
     kb: Optional[str] = typer.Option(None, "--kb", "-k", help="目标知识库名称"),
-    json_output: bool = typer.Option(True, "--json/--no-json", help="JSON 输出"),
+    output_format: str = typer.Option("table", "--format", help="输出格式: json, table"),
+    json_output: bool = typer.Option(False, "--json", help="JSON 输出（快捷方式，等同于 --format json）"),
 ):
     """删除笔记"""
     try:
+        # 向后兼容：--json 快捷方式
+        if json_output:
+            output_format = "json"
+
         # 如果指定了知识库，临时切换
         if kb:
             from .config import use_kb
             with use_kb(kb):
-                _delete_impl(note_id, force, json_output)
+                _delete_impl(note_id, force, output_format)
         else:
-            _delete_impl(note_id, force, json_output)
-            
+            _delete_impl(note_id, force, output_format)
+
+    except typer.Exit:
+        raise
     except Exception as e:
         result = {
             "success": False,
             "error": str(e),
         }
+        if output_format == "json":
+            print(output_json(result))
+        else:
+            console.print(f"[red]✗[/red] Error: {e}")
+        raise typer.Exit(1)
+
+
+def _edit_impl(
+    note_id: str,
+    content: Optional[str],
+    title: Optional[str],
+    tags: Optional[List[str]],
+    note_type: Optional[str],
+    source: Optional[str],
+    output_format: str,
+):
+    """编辑笔记的内部实现"""
+    # 验证：至少指定一个编辑字段
+    if all(v is None for v in [content, title, tags, note_type, source]):
+        raise ValueError("至少指定一个要编辑的字段 (--content, --title, --tags, --type, --source)")
+
+    # 加载笔记
+    n = note.load_note_by_id(note_id)
+    if not n:
+        raise ValueError(f"笔记不存在: {note_id}")
+
+    old_title = n.title
+    old_links = set(n.links)
+
+    # 更新字段
+    if content is not None:
+        n.content = content
+    if title is not None:
+        n.title = title
+    if tags is not None:
+        n.tags = tags
+    if source is not None:
+        n.source = source if source else None  # 空字符串清除 source
+    if note_type is not None:
+        try:
+            new_type = NoteType(note_type.lower())
+        except ValueError:
+            raise ValueError(
+                f"Invalid note type: {note_type}. Use: fleeting, literature, permanent"
+            )
+        n.type = new_type
+
+    # 如果内容被更新，解析 wiki links
+    if content is not None:
+        wiki_links = extract_wiki_links(content)
+        resolved_links = []
+        unresolved = []
+
+        all_notes = note.list_notes() if wiki_links else []
+        for link_text in wiki_links:
+            target_id = find_note_id_by_title_or_id(link_text, all_notes=all_notes)
+            if target_id:
+                resolved_links.append(target_id)
+            else:
+                unresolved.append(link_text)
+
+        n.links = resolved_links
+    else:
+        unresolved = []
+
+    # 保存更新
+    if note.update_note(n):
+        # 更新反向链接
+        new_links = set(n.links)
+
+        # 新增的链接 → 添加反向链接
+        added_links = new_links - old_links
+        for target_id in added_links:
+            target_note = note.load_note_by_id(target_id)
+            if target_note and n.id not in target_note.backlinks:
+                target_note.backlinks.append(n.id)
+                note.save_note(target_note, add_to_index=False)
+
+        # 移除的链接 → 删除反向链接
+        removed_links = old_links - new_links
+        for target_id in removed_links:
+            target_note = note.load_note_by_id(target_id)
+            if target_note and n.id in target_note.backlinks:
+                target_note.backlinks.remove(n.id)
+                note.save_note(target_note, add_to_index=False)
+
+        result = {
+            "success": True,
+            "note": {
+                "id": n.id,
+                "title": n.title,
+                "type": n.type.value,
+                "filepath": str(n.filepath),
+            },
+        }
+        if old_title != n.title:
+            result["title_changed"] = {"old": old_title, "new": n.title}
+        if unresolved:
+            result["warnings"] = f"Unresolved links: {', '.join(unresolved)}"
+
+        if output_format == "json":
+            print(output_json(result))
+        else:
+            # 收集修改的字段名
+            changed = []
+            if content is not None:
+                changed.append("content")
+            if title is not None:
+                changed.append("title")
+            if tags is not None:
+                changed.append("tags")
+            if note_type is not None:
+                changed.append("type")
+            if source is not None:
+                changed.append("source")
+            _print_action_table("updated", {
+                "ID": n.id,
+                "Title": n.title,
+                "Fields": ", ".join(changed),
+            })
+            if old_title != n.title:
+                console.print(f"  [dim]Title: {old_title} → {n.title}[/dim]")
+            if unresolved:
+                console.print(
+                    f"  [yellow]Warning: Unresolved links - {', '.join(unresolved)}[/yellow]"
+                )
+    else:
+        raise Exception("Failed to update note")
+
+
+@app.command()
+def edit(
+    note_id: str = typer.Argument(..., help="笔记 ID"),
+    content: Optional[str] = typer.Option(None, "--content", "-c", help="新内容"),
+    title: Optional[str] = typer.Option(None, "--title", "-t", help="新标题"),
+    tags: Optional[List[str]] = typer.Option(None, "--tag", help="新标签（替换全部）"),
+    note_type: Optional[str] = typer.Option(
+        None, "--type", help="新类型 (fleeting/literature/permanent)"
+    ),
+    source: Optional[str] = typer.Option(None, "--source", "-s", help="新来源"),
+    kb: Optional[str] = typer.Option(None, "--kb", "-k", help="目标知识库名称"),
+    output_format: str = typer.Option("table", "--format", "-f", help="输出格式: json, table"),
+    json_output: bool = typer.Option(False, "--json", help="JSON 输出（快捷方式，等同于 --format json）"),
+):
+    """编辑已有笔记（保留 ID 和创建时间）"""
+    try:
+        # 向后兼容：--json 快捷方式
         if json_output:
+            output_format = "json"
+
+        if kb:
+            from .config import use_kb
+
+            with use_kb(kb):
+                _edit_impl(note_id, content, title, tags, note_type, source, output_format)
+        else:
+            _edit_impl(note_id, content, title, tags, note_type, source, output_format)
+    except typer.Exit:
+        raise
+    except Exception as e:
+        result = {
+            "success": False,
+            "error": str(e),
+        }
+        if output_format == "json":
             print(output_json(result))
         else:
             console.print(f"[red]✗[/red] Error: {e}")

{jfox_cli-0.1.3 → jfox_cli-0.1.4}/jfox/note.py

@@ -116,15 +116,22 @@ def load_note_by_id(note_id: str, cfg: Optional[ZKConfig] = None) -> Optional[No
         Note 对象或 None
     """
     use_config = cfg or config
-    
+
     # 在所有类型目录中搜索
     for note_type in NoteType:
         dir_path = use_config.notes_dir / note_type.value
         if not dir_path.exists():
             continue
-        
+
+        # 尝试两种文件名模式：
+        # 1. {id}*.md — literature/permanent 笔记（{id}-{slug}.md）
+        # 2. {id[:8]}-{id[8:]}*.md — fleeting 笔记（YYYYMMDD-HHMMSSNNNN.md）
         for filepath in dir_path.glob(f"{note_id}*.md"):
             return load_note(filepath)
+        # fleeting 笔记文件名格式：YYYYMMDD-HHMMSSNNNN.md
+        if len(note_id) > 8:
+            for filepath in dir_path.glob(f"{note_id[:8]}-{note_id[8:]}*.md"):
+                return load_note(filepath)
     
     return None
 
@@ -200,6 +207,67 @@ def delete_note(note_id: str) -> bool:
         return False
 
 
+def update_note(note_obj: Note, add_to_index: bool = True) -> bool:
+    """
+    更新已有笔记
+
+    处理：查找旧文件 → 更新 updated 时间戳 → 写入新文件 → 删除旧文件（如路径变化）→ 更新索引
+
+    Args:
+        note_obj: 已修改的 Note 对象（必须已有 id）
+        add_to_index: 是否更新搜索索引
+
+    Returns:
+        是否更新成功
+    """
+    # 查找当前文件路径（可能标题改了，按 ID 查）
+    old_filepath = find_note_file(config, note_obj.id)
+    if not old_filepath:
+        logger.warning(f"Note {note_obj.id} file not found on disk")
+        return False
+
+    try:
+        # 更新时间戳
+        note_obj.updated = datetime.now()
+
+        # 写入新文件（filepath 属性根据当前字段生成）
+        note_obj.filepath.parent.mkdir(parents=True, exist_ok=True)
+        with open(note_obj.filepath, 'w', encoding='utf-8') as f:
+            f.write(note_obj.to_markdown())
+
+        # 如果文件路径变了（标题修改导致重命名），删除旧文件
+        if old_filepath != note_obj.filepath and old_filepath.exists():
+            old_filepath.unlink()
+            logger.info(f"Renamed note file: {old_filepath} -> {note_obj.filepath}")
+
+        logger.info(f"Updated note {note_obj.id}")
+
+        # 更新索引
+        if add_to_index:
+            # 先删除旧索引，再添加新索引
+            try:
+                vector_store = get_vector_store()
+                vector_store.delete_note(note_obj.id)
+                vector_store.add_note(note_obj)
+            except Exception as e:
+                logger.warning(f"Failed to update vector store index: {e}")
+
+            try:
+                from .bm25_index import get_bm25_index
+                bm25_index = get_bm25_index()
+                bm25_index.remove_document(note_obj.id)
+                content = f"{note_obj.title} {note_obj.content}"
+                bm25_index.add_document(note_obj.id, content)
+            except Exception as e:
+                logger.warning(f"Failed to update BM25 index: {e}")
+
+        return True
+
+    except Exception as e:
+        logger.error(f"Failed to update note {note_obj.id}: {e}")
+        return False
+
+
 def get_stats(cfg: Optional[ZKConfig] = None) -> Dict[str, Any]:
     """
     获取知识库统计
@@ -430,10 +498,16 @@ def find_note_file(config_obj, note_id: str) -> Optional[Path]:
         dir_path = config_obj.notes_dir / note_type.value
         if not dir_path.exists():
             continue
-        
+
+        # 尝试两种文件名模式：
+        # 1. {id}*.md — literature/permanent 笔记（{id}-{slug}.md）
+        # 2. {id[:8]}-{id[8:]}*.md — fleeting 笔记（YYYYMMDD-HHMMSSNNNN.md）
         for filepath in dir_path.glob(f"{note_id}*.md"):
             return filepath
-    
+        if len(note_id) > 8:
+            for filepath in dir_path.glob(f"{note_id[:8]}-{note_id[8:]}*.md"):
+                return filepath
+
     return None
 
 

{jfox_cli-0.1.3 → jfox_cli-0.1.4}/jfox/performance.py

@@ -188,6 +188,7 @@ def bulk_import_notes(
     from . import note as note_module
     from .embedding_backend import get_backend
     from .vector_store import get_vector_store
+    from .bm25_index import get_bm25_index
     
     nt = NoteType(note_type.lower())
     backend = get_backend()
@@ -264,6 +265,12 @@ def bulk_import_notes(
                     embeddings=embeddings,
                     metadatas=metadatas
                 )
+
+                # 批量添加到 BM25 索引
+                bm25 = get_bm25_index()
+                bm25_docs = [(n.id, f"{n.title} {n.content}") for n in notes]
+                bm25.add_documents_batch(bm25_docs)
+
             except Exception as e:
                 logger.warning(f"Failed to index batch: {e}")
             

{jfox_cli-0.1.3 → jfox_cli-0.1.4}/pyproject.toml

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