jfox-cli 0.4.3__tar.gz → 0.6.0__tar.gz

{jfox_cli-0.4.3 → jfox_cli-0.6.0}/.github/workflows/integration-test.yml

@@ -245,7 +245,7 @@ jobs:
       run: |
         echo "lint: ${{ needs.lint.result }}"
         echo "test-fast: ${{ needs.test-fast.result }}"
-        if [[ "${{ needs.lint.result }}" == "success" && "${{ needs.test-fast.result }}" == "success" ]]; then
+        if [[ "${{ needs.lint.result }}" == "success" && ("${{ needs.test-fast.result }}" == "success" || "${{ needs.test-fast.result }}" == "skipped") ]]; then
           echo "Quality gate passed!"
           exit 0
         else

{jfox_cli-0.4.3 → jfox_cli-0.6.0}/.gitignore

@@ -37,3 +37,13 @@ Thumbs.db
 chroma_db/
 *.sqlite3
 cache/
+
+# Claude Code runtime files
+.claude/scheduled_tasks.json
+.claude/scheduled_tasks.lock
+.claude/worktrees/
+
+# Temporary analysis files
+analysis_report.md
+kimi-export-*.md
+review_body*.md

{jfox_cli-0.4.3 → jfox_cli-0.6.0}/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [0.5.0] - 2026-04-29
+
+### Features
+- 支持通过标签召回笔记 (#170) (#177)
+- **cli**: show tags column in list table output
+- **note**: add tags parameter to list_notes() and search_notes()
+- **vector_store**: add tags parameter to search() for ChromaDB filtering
+
+### Fixes
+- **test**: resolve CI test-full failures (#175)
+
+### Changes
+- add superpowers plans and specs docs, update .gitignore (#178)
+- add tag filtering implementation plan for #170
+- add tag filtering design spec for #170
+
+[0.5.0]: https://github.com/zhuxixi/jfox/compare/v0.4.3...v0.5.0
+
 ## [0.4.3] - 2026-04-28
 
 ### Features

{jfox_cli-0.4.3 → jfox_cli-0.6.0}/PKG-INFO

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

jfox_cli-0.6.0/docs/superpowers/plans/2026-04-13-add-content-file.md

@@ -0,0 +1,301 @@
+# add --content-file Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** `jfox add` 支持 `--content-file` 选项，从文件或 stdin 读取笔记内容。
+
+**Architecture:** 在 `add` 命令中将 `content` 从必需位置参数改为可选参数，新增 `--content-file` 选项。文件读取逻辑复用 `edit` 命令已有的模式（`cli.py` L975-986），两者互斥校验。stdin 支持通过 `--content-file -` 实现。`_add_note_impl` 签名不变。
+
+**Tech Stack:** Python, Typer, pathlib
+
+---
+
+### Task 1: 文件读取逻辑提取为公共函数
+
+**Files:**
+- Modify: `jfox/cli.py` (在 `_edit_impl` 之前添加公共函数)
+- Modify: `jfox/cli.py:970-986` (`_edit_impl` 调用改为使用公共函数)
+
+**为什么先做：** `add` 和 `edit` 都需要读取 `--content-file`，提取公共函数避免重复代码，也方便单独测试。
+
+- [ ] **Step 1: 在 `_edit_impl` 之前添加 `_read_content_file()` 函数**
+
+在 `jfox/cli.py` 约第 958 行（`_edit_impl` 定义之前）插入：
+
+```python
+def _read_content_file(content_file: str) -> str:
+    """从文件或 stdin 读取内容（--content-file 共用逻辑）"""
+    if content_file == "-":
+        import sys
+
+        return sys.stdin.read()
+
+    p = Path(content_file)
+    if not p.exists():
+        raise ValueError(f"文件不存在: {content_file}")
+    if not p.is_file():
+        raise ValueError(f"路径不是文件: {content_file}")
+    try:
+        return p.read_text(encoding="utf-8")
+    except PermissionError:
+        raise ValueError(f"无权限读取文件: {content_file}")
+    except UnicodeDecodeError:
+        raise ValueError(f"文件编码错误（需要 UTF-8）: {content_file}")
+```
+
+- [ ] **Step 2: 重构 `_edit_impl` 使用公共函数**
+
+将 `jfox/cli.py` L974-986（`_edit_impl` 中的文件读取代码）：
+
+```python
+    # 从文件读取内容
+    if content_file is not None:
+        p = Path(content_file)
+        if not p.exists():
+            raise ValueError(f"文件不存在: {content_file}")
+        if not p.is_file():
+            raise ValueError(f"路径不是文件: {content_file}")
+        try:
+            content = p.read_text(encoding="utf-8")
+        except PermissionError:
+            raise ValueError(f"无权限读取文件: {content_file}")
+        except UnicodeDecodeError:
+            raise ValueError(f"文件编码错误（需要 UTF-8）: {content_file}")
+```
+
+替换为：
+
+```python
+    # 从文件读取内容
+    if content_file is not None:
+        content = _read_content_file(content_file)
+```
+
+- [ ] **Step 3: 运行快速回归测试，确认 edit 功能不变**
+
+Run: `uv run pytest tests/test_cli_format.py::TestAddAndDeleteFormat -v`
+Expected: 全部 PASS
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add jfox/cli.py
+git commit -m "refactor: extract _read_content_file() for shared --content-file logic"
+```
+
+---
+
+### Task 2: add 命令支持 --content-file 选项
+
+**Files:**
+- Modify: `jfox/cli.py:366-383` (`add` 函数签名和调用)
+
+- [ ] **Step 1: 修改 `add()` 函数签名**
+
+将 `jfox/cli.py` L367-368：
+
+```python
+@app.command()
+def add(
+    content: str = typer.Argument(..., help="笔记内容（支持 [[笔记标题]] 格式链接）"),
+```
+
+改为：
+
+```python
+@app.command()
+def add(
+    content: Optional[str] = typer.Argument(None, help="笔记内容（支持 [[笔记标题]] 格式链接）"),
+```
+
+- [ ] **Step 2: 在 `--template` 选项之后添加 `--content-file` 参数**
+
+在 `jfox/cli.py` L375-377（`template` 参数定义之后）插入：
+
+```python
+    content_file: Optional[str] = typer.Option(
+        None, "--content-file", help="从文件读取内容（用 - 表示 stdin）"
+    ),
+```
+
+- [ ] **Step 3: 在 `add()` 函数体中添加互斥校验和文件读取逻辑**
+
+将 `jfox/cli.py` L384-397：
+
+```python
+    """添加新笔记（内容中可用 [[笔记标题]] 引用其他笔记）"""
+    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, output_format, template)
+        else:
+            _add_note_impl(content, title, note_type, tags, source, output_format, template)
+```
+
+改为：
+
+```python
+    """添加新笔记（内容中可用 [[笔记标题]] 引用其他笔记）"""
+    try:
+        # 向后兼容：--json 快捷方式
+        if json_output:
+            output_format = "json"
+
+        # content 和 --content-file 互斥
+        if content is not None and content_file is not None:
+            raise ValueError("不能同时指定内容参数和 --content-file，请选择其一")
+
+        # 从文件读取内容
+        if content_file is not None:
+            content = _read_content_file(content_file)
+
+        # 至少提供一种内容来源
+        if not content:
+            raise ValueError("请提供笔记内容（位置参数或 --content-file）")
+
+        # 如果指定了知识库，临时切换
+        if kb:
+            from .config import use_kb
+
+            with use_kb(kb):
+                _add_note_impl(content, title, note_type, tags, source, output_format, template)
+        else:
+            _add_note_impl(content, title, note_type, tags, source, output_format, template)
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add jfox/cli.py
+git commit -m "feat: add --content-file option to jfox add command"
+```
+
+---
+
+### Task 3: 测试 --content-file 功能
+
+**Files:**
+- Modify: `tests/test_cli_format.py` (在 `TestAddAndDeleteFormat` 类中添加测试)
+
+- [ ] **Step 1: 在 `test_add_format_json` 之前添加 --content-file 测试**
+
+在 `tests/test_cli_format.py` 的 `TestAddAndDeleteFormat` 类中，`test_add_format_json` (L327) 之前插入：
+
+```python
+    def test_add_content_file(self, cli, tmp_path):
+        """测试 add 命令 --content-file 从文件读取内容"""
+        content_file = tmp_path / "note.md"
+        content_file.write_text("从文件读取的笔记内容", encoding="utf-8")
+
+        result = cli.run("add", "--content-file", str(content_file), "--title", "FileContent")
+
+        assert result.success
+        data = result.data
+        assert data["success"] is True
+        assert data["note"]["title"] == "FileContent"
+
+    def test_add_content_file_mutual_exclusive(self, cli, tmp_path):
+        """测试 add 命令 content 参数和 --content-file 不能同时指定"""
+        content_file = tmp_path / "note.md"
+        content_file.write_text("file content", encoding="utf-8")
+
+        result = cli.run("add", "直接内容", "--content-file", str(content_file))
+
+        assert not result.success
+        assert "不能同时指定" in result.stderr or "不能同时指定" in result.stdout
+
+    def test_add_content_file_not_found(self, cli):
+        """测试 add 命令 --content-file 文件不存在时报错"""
+        result = cli.run("add", "--content-file", "/nonexistent/file.md")
+
+        assert not result.success
+        assert "文件不存在" in result.stderr or "文件不存在" in result.stdout
+
+    def test_add_content_file_empty(self, cli, tmp_path):
+        """测试 add 命令不提供内容时报错"""
+        result = cli.run("add")
+
+        assert not result.success
+
+    def test_add_content_file_with_wiki_links(self, cli, tmp_path):
+        """测试 add 命令 --content-file 内容中的 [[wiki链接]] 正常解析"""
+        # 先创建一个目标笔记
+        cli.add("目标笔记内容", title="目标笔记")
+
+        content_file = tmp_path / "linked.md"
+        content_file.write_text("引用 [[目标笔记]] 的内容", encoding="utf-8")
+
+        result = cli.run("add", "--content-file", str(content_file), "--title", "带链接的笔记")
+
+        assert result.success
+        data = result.data
+        assert data["note"]["links"]
+```
+
+- [ ] **Step 2: 运行测试确认全部通过**
+
+Run: `uv run pytest tests/test_cli_format.py::TestAddAndDeleteFormat -v`
+Expected: 全部 PASS（包括新增的 5 个测试）
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/test_cli_format.py
+git commit -m "test: add --content-file tests for jfox add command"
+```
+
+---
+
+### Task 4: 验证 edit --content-file 回归
+
+**Files:** 无修改
+
+- [ ] **Step 1: 确认 edit 的 --content-file 仍然正常工作**
+
+检查现有 edit 测试是否覆盖 --content-file：
+
+```bash
+uv run pytest tests/test_cli_format.py -v -k "edit"
+```
+
+如果 edit 的 --content-file 没有现有测试，手动验证：
+
+```bash
+uv run jfox add "原始内容" --title "编辑测试" --json
+# 记录返回的 note_id
+echo "新内容" > /tmp/test_edit.md
+uv run jfox edit <note_id> --content-file /tmp/test_edit.md --json
+```
+
+Expected: edit 成功，内容更新为 "新内容"
+
+- [ ] **Step 2: 确认 add 的原有行为不受影响**
+
+```bash
+uv run jfox add "直接输入的内容" --title "位置参数测试" --json
+```
+
+Expected: add 成功，内容为 "直接输入的内容"
+
+---
+
+## Self-Review Checklist
+
+| 检查项 | 状态 |
+|--------|------|
+| `_read_content_file` 覆盖文件不存在/非文件/权限/编码错误 | Done (Task 1) |
+| stdin 支持 (`--content-file -`) | Done (Task 1, `content_file == "-"` 分支) |
+| `content` 和 `--content-file` 互斥校验 | Done (Task 2) |
+| 都不指定时报错提示 | Done (Task 2) |
+| `--content-file` 与 `--template` 交互正确（内容作为 `{{content}}` 变量） | Done (Task 2, `_add_note_impl` 未修改，`content` 变量直接传入) |
+| `-f` 短选项不被占用 | Done (Task 2, `--content-file` 无短选项) |
+| `wiki_links` 提取仍正常工作 | Done (Task 3 测试覆盖) |
+| `edit` 命令回归安全 | Done (Task 1 提取公共函数，Task 4 验证) |
+| `_add_note_impl` 签名未修改 | Done (Task 2 只在 `add()` 中读取文件后传入 `content: str`) |

jfox_cli-0.6.0/docs/superpowers/plans/2026-04-13-bulk-import-vectorstore-init.md

@@ -0,0 +1,270 @@
+# Bulk-Import VectorStore 初始化修复 实现计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 修复 `bulk_import_notes()` 中 VectorStore.collection 未初始化导致批量索引静默失败的问题，同时让 `index rebuild` 命令同时重建 BM25 索引。
+
+**Architecture:** 两处独立修复：(1) `performance.py` 在批量索引前确保 VectorStore 已初始化；(2) `cli.py` 的 `index rebuild` 命令增加 BM25 重建步骤。两处修复互不依赖。
+
+**Tech Stack:** Python 3.10+, pytest, unittest.mock
+
+---
+
+## Task 1: 修复 bulk_import_notes 中 VectorStore 未初始化的 bug
+
+**Files:**
+- Modify: `jfox/performance.py:266`
+- Test: `tests/unit/test_bm25_batch.py`
+
+- [ ] **Step 1: 写一个能复现 bug 的失败测试**
+
+在 `tests/unit/test_bm25_batch.py` 的 `TestBulkImportBM25Integration` 类中，添加一个测试：模拟 `VectorStore` 的 `collection` 为 `None`（即真实场景），验证 `bulk_import_notes` 不会抛异常。
+
+```python
+@patch("jfox.bm25_index.get_bm25_index")
+@patch("jfox.embedding_backend.get_backend")
+@patch("jfox.note.create_note")
+def test_bulk_import_with_uninitialized_vectorstore(
+    self, mock_create_note, mock_get_backend, mock_get_bm25, tmp_path
+):
+    """bulk_import_notes 应在 collection.add() 前自动初始化 VectorStore"""
+    import numpy as np
+
+    from jfox.models import Note, NoteType
+    from jfox.performance import bulk_import_notes
+
+    # 准备 mock note
+    mock_note = MagicMock(spec=Note)
+    mock_note.id = "20260413120000"
+    mock_note.title = "测试初始化"
+    mock_note.content = "内容"
+    mock_note.type = NoteType.PERMANENT
+    mock_note.tags = []
+    mock_note.filepath = tmp_path / "notes" / "permanent" / "test.md"
+    mock_note.to_markdown.return_value = "# 测试初始化\n内容"
+    mock_create_note.return_value = mock_note
+
+    # mock embedding backend
+    mock_backend = MagicMock()
+    mock_backend.model = MagicMock()
+    mock_backend.encode.return_value = np.array([[0.1] * 384])
+    mock_get_backend.return_value = mock_backend
+
+    # mock BM25
+    mock_bm25 = MagicMock()
+    mock_bm25.add_documents_batch.return_value = True
+    mock_get_bm25.return_value = mock_bm25
+
+    # 不 mock get_vector_store，让真实的 VectorStore 被创建
+    # 但 patch 掉 VectorStore.init 来验证它被调用了
+    with patch("jfox.performance.get_vector_store") as mock_get_vs:
+        mock_vs = MagicMock()
+        # 关键：collection 初始为 None，模拟真实场景
+        mock_vs.collection = None
+
+        # init() 会设置 collection
+        def fake_init():
+            mock_vs.collection = MagicMock()
+
+        mock_vs.init.side_effect = fake_init
+        mock_get_vs.return_value = mock_vs
+
+        notes_data = [{"title": "测试初始化", "content": "内容"}]
+        result = bulk_import_notes(notes_data, show_progress=False)
+
+        # 验证 init 被调用了
+        mock_vs.init.assert_called()
+        # 导入成功
+        assert result["imported"] == 1
+```
+
+- [ ] **Step 2: 运行测试确认它失败**
+
+Run: `uv run pytest tests/unit/test_bm25_batch.py::TestBulkImportBM25Integration::test_bulk_import_with_uninitialized_vectorstore -v`
+Expected: FAIL — 当前代码直接访问 `vector_store.collection.add()`，不会调用 `init()`，mock 的 `collection` 仍为 None，会抛 `AttributeError`。
+
+- [ ] **Step 3: 修复 performance.py — 在 collection.add() 前添加初始化**
+
+在 `jfox/performance.py` 第 266 行之前，添加初始化检查。修改 `# 批量添加到 ChromaDB` 注释后的代码块：
+
+```python
+                # 确保 VectorStore 已初始化
+                if vector_store.collection is None:
+                    vector_store.init()
+
+                # 批量添加到 ChromaDB
+                vector_store.collection.add(
+                    ids=ids, documents=documents, embeddings=embeddings, metadatas=metadatas
+                )
+```
+
+完整上下文（`performance.py` 约第 254-268 行）修改后为：
+
+```python
+                # 批量添加到 ChromaDB
+                ids = [n.id for n in notes]
+                metadatas = [
+                    {
+                        "title": n.title,
+                        "type": n.type.value,
+                        "filepath": str(n.filepath),
+                        "tags": ",".join(n.tags),
+                    }
+                    for n in notes
+                ]
+
+                # 确保 VectorStore 已初始化
+                if vector_store.collection is None:
+                    vector_store.init()
+
+                vector_store.collection.add(
+                    ids=ids, documents=documents, embeddings=embeddings, metadatas=metadatas
+                )
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `uv run pytest tests/unit/test_bm25_batch.py -v`
+Expected: ALL PASS（包括新测试和原有测试）
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add jfox/performance.py tests/unit/test_bm25_batch.py
+git commit -m "fix: bulk_import_notes 中 VectorStore.collection 未初始化导致索引失败
+
+performance.py 的 bulk_import_notes() 直接访问 vector_store.collection.add()，
+绕过了 add_note() 中的 init() 保护。在新会话中直接执行 bulk-import 时，
+collection 为 None 导致 'NoneType' object has no attribute 'add' 错误。
+
+在 collection.add() 前添加 if vector_store.collection is None: vector_store.init()。
+
+Closes #126 (修复 1/2)"
+```
+
+---
+
+## Task 2: 让 index rebuild 同时重建 BM25 索引
+
+**Files:**
+- Modify: `jfox/cli.py:1701-1713`
+- Test: `tests/unit/test_index_kb_param.py`（在已有文件中添加测试）
+
+- [ ] **Step 1: 写失败测试 — 验证 rebuild 时也调用了 BM25 重建**
+
+在 `tests/unit/test_index_kb_param.py` 中添加测试：
+
+```python
+class TestIndexRebuildIncludesBM25:
+    """验证 index rebuild 同时重建 BM25 索引"""
+
+@patch("jfox.cli.note")
+@patch("jfox.cli.get_bm25_index")
+@patch("jfox.cli.Indexer")
+@patch("jfox.cli.get_vector_store")
+def test_rebuild_calls_bm25_rebuild(
+    self, mock_get_vs, mock_indexer_cls, mock_get_bm25, mock_note, tmp_path
+):
+    """index rebuild 应在 ChromaDB 重建后调用 BM25 rebuild_from_notes"""
+    from jfox.cli import _index_impl
+
+    # mock vector store
+    mock_vs = MagicMock()
+    mock_get_vs.return_value = mock_vs
+
+    # mock indexer
+    mock_indexer = MagicMock()
+    mock_indexer.index_all.return_value = 10
+    mock_indexer_cls.return_value = mock_indexer
+
+    # mock note.list_notes
+    mock_notes = [MagicMock() for _ in range(3)]
+    mock_note.list_notes.return_value = mock_notes
+
+    # mock BM25
+    mock_bm25 = MagicMock()
+    mock_bm25.rebuild_from_notes.return_value = True
+    mock_get_bm25.return_value = mock_bm25
+
+    _index_impl("rebuild", "text")
+
+    # 验证 ChromaDB 重建被调用
+    mock_indexer.index_all.assert_called_once()
+    # 验证 BM25 重建也被调用
+    mock_get_bm25.assert_called_once()
+    mock_bm25.rebuild_from_notes.assert_called_once_with(mock_notes)
+```
+
+- [ ] **Step 2: 运行测试确认它失败**
+
+Run: `uv run pytest tests/unit/test_index_kb_param.py::TestIndexRebuildIncludesBM25 -v`
+Expected: FAIL — 当前 `rebuild` 分支不调用 BM25 重建。
+
+- [ ] **Step 3: 修改 cli.py 的 rebuild 分支，增加 BM25 重建**
+
+修改 `jfox/cli.py` 第 1701-1713 行的 `rebuild` 分支。修改后：
+
+```python
+        elif action == "rebuild":
+            console.print("[yellow]Rebuilding index...[/yellow]")
+            count = indexer.index_all()
+
+            # 同时重建 BM25 索引
+            from . import note as note_module
+            from .bm25_index import get_bm25_index
+
+            bm25_index = get_bm25_index()
+            notes = note_module.list_notes(limit=10000)
+            bm25_success = bm25_index.rebuild_from_notes(notes)
+
+            result = {
+                "success": True,
+                "indexed": count,
+                "bm25_rebuilt": bm25_success,
+                "bm25_indexed": len(notes),
+            }
+
+            if output_format == "json":
+                print(output_json(result))
+            else:
+                console.print(f"[green]✓[/green] Indexed {count} notes")
+                if bm25_success:
+                    console.print(f"[green]✓[/green] BM25 index rebuilt: {len(notes)} notes")
+                else:
+                    console.print("[yellow]⚠[/yellow] ChromaDB rebuilt, but BM25 rebuild failed")
+```
+
+- [ ] **Step 4: 运行测试确认通过**
+
+Run: `uv run pytest tests/unit/test_index_kb_param.py -v`
+Expected: ALL PASS
+
+- [ ] **Step 5: 验证现有 rebuild-bm25 单独命令仍正常**
+
+Run: `uv run pytest tests/unit/test_index_kb_param.py -v -k "not RebuildIncludesBM25"`
+Expected: ALL PASS（原有测试不受影响）
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add jfox/cli.py tests/unit/test_index_kb_param.py
+git commit -m "fix: index rebuild 同时重建 BM25 索引
+
+之前 index rebuild 只重建 ChromaDB，用户需额外手动执行 rebuild-bm25。
+现在 rebuild 操作自动同时重建两个索引，输出中显示各自的重建状态。
+
+Refs #126 (修复 2/2)"
+```
+
+---
+
+## 自查清单
+
+| 检查项 | 状态 |
+|--------|------|
+| 修复 1: performance.py VectorStore 初始化 | Task 1 覆盖 |
+| 修复 2: cli.py rebuild 含 BM25 | Task 2 覆盖 |
+| 现有测试不受影响 | Task 1/2 的 Step 4 验证 |
+| 无 placeholder / TBD | 已检查，每步都有完整代码 |
+| 类型/方法签名一致 | `rebuild_from_notes(notes)` 在 bm25_index.py:369 和 cli.py 一致 |
+| `rebuild-bm25` 独立命令仍可用 | Task 2 Step 5 验证，独立命令逻辑未被修改 |