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

{jfox_cli-0.1.2 → 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.2 → jfox_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jfox-cli
-Version: 0.1.2
+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.2 → jfox_cli-0.1.4}/jfox/__init__.py

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

{jfox_cli-0.1.2 → 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.2 → 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.2 → jfox_cli-0.1.4}/jfox/global_config.py

@@ -115,22 +115,53 @@ class GlobalConfigManager:
         try:
             current_resolved = Path(default_kb.path).expanduser().resolve()
             if current_resolved == old_path.resolve():
-                # 迁移：将旧目录内容移到新路径
                 if old_path.exists() and not new_path.exists():
                     import shutil
                     new_path.mkdir(parents=True, exist_ok=True)
-                    # 移动 notes/ 和 .zk/ 目录
-                    for subdir in ["notes", ".zk"]:
-                        src = old_path / subdir
-                        if src.exists():
-                            shutil.move(str(src), str(new_path / subdir))
+                    try:
+                        # 移动 notes/ 和 .zk/ 目录
+                        for subdir in ["notes", ".zk"]:
+                            src = old_path / subdir
+                            if src.exists():
+                                shutil.move(str(src), str(new_path / subdir))
+                    except Exception as move_error:
+                        # 回滚：移回已迁移的子目录
+                        rollback_errors = []
+                        for subdir in ["notes", ".zk"]:
+                            moved = new_path / subdir
+                            if moved.exists():
+                                try:
+                                    shutil.move(str(moved), str(old_path / subdir))
+                                except Exception as rb_err:
+                                    rollback_errors.append(
+                                        f"Failed to roll back {subdir}: {rb_err}"
+                                    )
+                        # 清理空的 new_path 目录
+                        try:
+                            new_path.rmdir()
+                        except OSError:
+                            logger.debug(
+                                f"Could not remove {new_path} during rollback"
+                            )
+                        if rollback_errors:
+                            logger.error(
+                                f"Migration failed ({move_error}) AND rollback had "
+                                f"errors: {'; '.join(rollback_errors)}"
+                            )
+                        raise
                     logger.info(f"Migrated default KB from {old_path} to {new_path}")
-                # 更新配置中的路径
-                default_kb.path = str(new_path)
-                self._save()
-                logger.info(f"Updated default KB path to {new_path}")
+                    # 仅在文件迁移成功后才更新 config
+                    default_kb.path = str(new_path)
+                    self._save()
+                else:
+                    # 旧路径已不存在或新路径已存在，仅更新 config 指向
+                    default_kb.path = str(new_path)
+                    self._save()
         except Exception as e:
-            logger.warning(f"Failed to migrate default KB path: {e}")
+            logger.error(
+                f"Failed to migrate default KB path from {old_path} to "
+                f"{new_path}: {e}", exc_info=True
+            )
 
     def _save(self) -> bool:
         """保存配置到文件"""