jfox-cli 0.7.1__tar.gz → 0.8.0__tar.gz

jfox_cli-0.8.0/.claude-plugin/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "jfox-skills",
+  "id": "jfox-skills",
+  "owner": { "name": "zhuxixi" },
+  "metadata": {
+    "description": "JFox Zettelkasten 知识管理工具的 Claude Code 集成",
+    "version": "0.1.0"
+  },
+  "plugins": [
+    {
+      "name": "jfox",
+      "source": "./",
+      "description": "JFox 知识管理 CLI 的 Claude Code 集成——搜索、导入、整理、会话总结",
+      "version": "0.1.0",
+      "author": { "name": "zhuxixi" },
+      "keywords": ["zettelkasten", "knowledge-management"],
+      "category": "workflow"
+    }
+  ]
+}

jfox_cli-0.8.0/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "name": "jfox",
+  "description": "JFox 知识管理 CLI 的 Claude Code 集成——搜索、导入、整理、会话总结",
+  "version": "0.1.0",
+  "author": { "name": "zhuxixi" },
+  "license": "MIT",
+  "keywords": ["zettelkasten", "knowledge-management", "cli"],
+  "skills": [
+    "./skills-recommend/claude-code/jfox-common",
+    "./skills-recommend/claude-code/jfox-ingest",
+    "./skills-recommend/claude-code/jfox-organize",
+    "./skills-recommend/claude-code/jfox-search",
+    "./skills-recommend/claude-code/jfox-session-summary"
+  ],
+  "commands": [
+    "./commands/jfox-common",
+    "./commands/jfox-ingest",
+    "./commands/jfox-organize",
+    "./commands/jfox-search",
+    "./commands/jfox-session-summary"
+  ]
+}

{jfox_cli-0.7.1 → jfox_cli-0.8.0}/AGENTS.md

@@ -38,21 +38,25 @@ jfox/
 ├── jfox/                      # 主包
 │   ├── __init__.py
 │   ├── __main__.py            # 入口点
-│   ├── cli.py                 # CLI 主程序（所有命令）
+│   ├── cli.py                 # CLI 主程序（所有命令，~2900 行）
 │   ├── models.py              # 数据模型（Note, NoteType）
 │   ├── config.py              # 配置管理（ZKConfig, use_kb）
 │   ├── global_config.py       # 全局配置管理（多知识库）
 │   ├── note.py                # 笔记 CRUD 操作
 │   ├── kb_manager.py          # 知识库管理器
-│   ├── embedding_backend.py   # 嵌入模型后端
+│   ├── embedding_backend.py   # 嵌入模型后端（支持 daemon 代理）
+│   ├── daemon/                # Embedding 模型 HTTP 守护进程
 │   ├── vector_store.py        # ChromaDB 向量存储
 │   ├── bm25_index.py          # BM25 关键词索引
 │   ├── search_engine.py       # 混合搜索引擎（RRF 融合）
 │   ├── graph.py               # 知识图谱（NetworkX）
-│   ├── indexer.py             # 文件监控和索引
+│   ├── indexer.py             # 文件监控和增量索引
 │   ├── formatters.py          # 多格式输出（JSON/CSV/YAML/Tree）
 │   ├── template.py            # 模板系统
 │   ├── template_cli.py        # 模板 CLI 子命令
+│   ├── git_extractor.py       # Git 仓库数据提取器（ingest 功能）
+│   ├── model_downloader.py    # 嵌入模型下载与缓存管理
+│   ├── note_index.py          # 笔记索引管理（文件名↔ID 映射）
 │   └── performance.py         # 性能优化工具
 ├── tests/                     # 测试目录
 │   ├── conftest.py            # pytest 配置和 fixtures
@@ -81,30 +85,32 @@ jfox/
 ### 安装开发环境
 
 ```bash
-# 创建虚拟环境（推荐）
-python -m venv .venv
-source .venv/bin/activate  # Linux/Mac
-.venv\Scripts\activate     # Windows
-
-# 开发模式安装
+# 安装（使用 uv，推荐）
 uv sync --extra dev
+
+# 安装（legacy pip fallback）
+pip install -e ".[dev]"
 ```
 
 ### 运行测试
 
 ```bash
 # 运行所有测试
-pytest tests/ -v
+uv run pytest tests/ -v
 
 # 运行特定测试文件
-pytest tests/test_core_workflow.py -v
+uv run pytest tests/test_core_workflow.py -v
 
 # 运行带标记的测试
-pytest tests/ -m "not slow"      # 排除慢测试
-pytest tests/ -m "integration"   # 仅运行集成测试
+uv run pytest tests/ -m "not slow"                     # 排除慢测试
+uv run pytest tests/ -m "not embedding and not slow"   # 快速测试（不加载模型）
+uv run pytest tests/ -m "integration"                  # 仅运行集成测试
 
 # 保留测试数据（用于调试）
-pytest tests/ --keep-data
+uv run pytest tests/ --keep-data
+
+# 覆盖率
+uv run pytest tests/ --cov=jfox --cov-report=html
 
 # Windows 全量测试（清理 + 测试）
 .\run_full_test.ps1
@@ -117,21 +123,21 @@ pytest tests/ --keep-data
 
 ```bash
 # 使用 black 格式化
-black jfox/ tests/
+uv run black jfox/ tests/
 
 # 使用 ruff 检查
-ruff check jfox/ tests/
+uv run ruff check jfox/ tests/
 ```
 
-### 本地安装和验证
+### 构建和验证
 
 ```bash
-# 安装到本地
-pip install -e .
+# 构建
+uv build
 
-# 验证安装
-jfox --help
-jfox --version
+# 验证 CLI
+uv run jfox --help
+uv run jfox --version
 ```
 
 ## 代码组织
@@ -140,16 +146,21 @@ jfox --version
 
 | 模块 | 职责 |
 |------|------|
-| `cli.py` | 所有 CLI 命令定义和实现（~1000 行） |
+| `cli.py` | 所有 CLI 命令定义和实现（~2900 行） |
 | `models.py` | Note 数据类、NoteType 枚举、Markdown 序列化/反序列化 |
 | `config.py` | ZKConfig 配置类、use_kb 上下文管理器（多知识库切换） |
 | `global_config.py` | GlobalConfigManager，管理 ~/.zk_config.json |
 | `note.py` | 笔记 CRUD：create_note, save_note, load_note, delete_note |
 | `kb_manager.py` | KnowledgeBaseManager，知识库生命周期管理 |
-| `search_engine.py` | HybridSearchEngine，支持 HYBRID/SEMANTIC/KEYWORD 模式 |
+| `search_engine.py` | HybridSearchEngine，支持 HYBRID/SEMANTIC/KEYWORD 模式，RRF 融合 |
 | `bm25_index.py` | BM25Index，本地文件存储的关键词索引 |
 | `vector_store.py` | VectorStore，ChromaDB 封装 |
 | `graph.py` | KnowledgeGraph，NetworkX 图分析和可视化 |
+| `git_extractor.py` | Git 仓库数据提取器（ingest 功能） |
+| `model_downloader.py` | 嵌入模型下载与缓存管理 |
+| `note_index.py` | 笔记索引管理（文件名↔ID 映射） |
+| `indexer.py` | 文件监控（watchdog）+ 增量索引 |
+| `daemon/` | Embedding 模型 HTTP 守护进程（server/client/process） |
 
 ### 笔记类型
 
@@ -158,8 +169,14 @@ class NoteType(Enum):
     FLEETING = "fleeting"       # 闪念笔记 - 快速捕捉
     LITERATURE = "literature"   # 文献笔记 - 读书笔记
     PERMANENT = "permanent"     # 永久笔记 - 整理后的知识
+    SESSION = "session"         # AI Agent 会话记录
 ```
 
+各类型文件名格式：
+- `fleeting`: `YYYYMMDD-HHMMSS.md`
+- `literature`: `YYYYMMDDHHMMSS-{slug}.md`
+- `permanent`: `YYYYMMDDHHMMSS-{slug}.md`
+
 ### 笔记文件格式
 
 每个笔记是一个 Markdown 文件，包含 YAML frontmatter：
@@ -174,6 +191,7 @@ updated: '2026-03-21T01:15:28'
 tags: [tag1, tag2]
 links: ['20260321011546']      # 正向链接
 backlinks: ['20260321011550']  # 反向链接（自动生成）
+topic: null                    # 会话主题（仅 session 类型）
 ---
 
 # 笔记标题
@@ -184,8 +202,8 @@ backlinks: ['20260321011550']  # 反向链接（自动生成）
 ### 多知识库支持
 
 - 全局配置存储在 `~/.zk_config.json`
-- 默认知识库路径：`~/.zettelkasten`
-- 命名知识库路径：`~/.zettelkasten-{name}`
+- 默认知识库路径：`~/.zettelkasten/default/`
+- 命名知识库路径：`~/.zettelkasten/<name>/`
 - 使用 `use_kb()` 上下文管理器临时切换知识库
 
 ## 代码风格指南
@@ -224,6 +242,13 @@ backlinks: ['20260321011550']  # 反向链接（自动生成）
 2. **集成测试**: 测试完整工作流
 3. **性能测试**: 标记为 `@pytest.mark.performance`
 
+### 测试目录结构
+
+- `tests/unit/` — 纯逻辑单元测试（约 25 个文件）
+- `tests/integration/` — 跨模块集成测试
+- `tests/performance/` — 性能基准测试
+- 根级遗留：`test_config_unit.py`、`test_config_set_unit.py`（与 unit 目录中测试内容不同）
+
 ### 测试工具
 
 - **临时知识库**: `tests/utils/temp_kb.py`
@@ -235,34 +260,49 @@ backlinks: ['20260321011550']  # 反向链接（自动生成）
 ```python
 # conftest.py 中定义的主要 fixtures
 
-def test_example(temp_kb, cli, generator):
+def test_example(temp_kb, cli, cli_fast, generator, mock_embedding_backend):
     """
     temp_kb: 临时知识库路径
     cli: 已初始化的 ZKCLI 实例
+    cli_fast: ZKCLI with mocked embeddings（快速，不加载模型）
     generator: NoteGenerator 数据生成器
+    mock_embedding_backend: mock 嵌入后端
     """
     pass
 ```
 
+### 测试标记（Markers）
+
+| 标记 | 含义 |
+|------|------|
+| `slow` | 慢测试 |
+| `performance` | 性能基准 |
+| `integration` | 集成测试 |
+| `embedding` | 涉及模型加载 |
+| `workflow` | 工作流测试 |
+| `bulk` | 批量操作测试 |
+
+### 测试运行规则
+
+- **全量/集成测试（~50min）不要自主运行**，提供命令让用户手动执行
+- **快速单元测试（几秒内）可以自主运行**，如单个模块的纯逻辑测试，不涉及 embedding 或 ChromaDB
+- `pytest.ini` 配置：`timeout=120`、`--strict-markers`、`-ra`
+- 测试以单进程运行，避免 ChromaDB/模型加载冲突
+
 ### 编写新测试的模板
 
 ```python
 # tests/test_feature.py
 
 import pytest
-from tests.utils.temp_kb import temp_knowledge_base
-from tests.utils.jfox_cli import ZKCLI
 
 
 class TestFeatureName:
     """测试功能名称"""
     
-    def test_basic_functionality(self, temp_kb):
+    def test_basic_functionality(self, temp_kb, cli):
         """测试基本功能"""
-        cli = ZKCLI(temp_kb)
-        cli.init()
-        
-        # 测试代码
+        # 使用 fixture 自动初始化的临时知识库和 CLI 实例
         result = cli.add("测试内容", title="测试笔记")
         
         assert result.success
@@ -343,6 +383,37 @@ def new_command(
 | 图谱构建 | <1s (1000笔记) |
 | 文件监控 | 实时 (<1s 延迟) |
 
+## CI（GitHub Actions）
+
+`.github/workflows/integration-test.yml` 包含四个 job：
+
+- **Fast**（PR/push 触发）：`not embedding and not slow`，Python 3.11，Ubuntu + Windows
+- **Core**（main 分支推送）：Core workflow 测试，使用真实 embedding，Python 3.10 + 3.12
+- **Full**（手动触发）：所有测试、所有 OS、所有 Python 版本
+- **Coverage**（Fast 完成后）：运行覆盖率，上传 HTML/XML 产物
+
+**Release** 工作流（`.github/workflows/publish.yml`）：在 GitHub Release 发布时自动推送到 PyPI。
+
+## Windows 注意事项
+
+- `robocopy` 参数会被 bash 误解析，应使用 `cmd.exe /c "robocopy source dest /E"`
+- 设置 `PYTHONUTF8=1` 和 `chcp 65001` 避免编码问题
+- HuggingFace 国内镜像：`export HF_ENDPOINT=https://hf-mirror.com`
+
+## 分支规则
+
+- **main 是保护分支**，不能直接 commit 或 push
+- 所有改动必须通过**新分支 + PR** 合入
+
+## 发版规则
+
+- 发版时必须同时修改三处版本号：
+  1. `pyproject.toml`
+  2. `jfox/__init__.py`
+  3. `uv.lock`
+- 操作顺序：先改 `pyproject.toml` 和 `__init__.py`，再跑 `uv lock` 更新 lock 文件
+- （曾有 #88 遗漏 `__init__.py` 的教训）
+
 ## 相关资源
 
 - **详细 CLI 文档**: `README.md`
@@ -384,6 +455,12 @@ class OutputFormatter:
 # 4. 添加测试
 ```
 
+## 常见陷阱（Gotchas）
+
+- `pytest.ini` 的 `addopts` 已包含 `-v`，手动再加 `-v` 是冗余的
+- 测试目录重组已基本完成，根级 `test_config_unit.py` 和 `test_config_set_unit.py` 与 `tests/unit/` 中对应文件测试内容不同，不是重复
+- `jfox show <id_or_title>` 复用 `find_note_id_by_title_or_id` 定位笔记，只读输出完整 Markdown
+
 ---
 
 ## Session History

{jfox_cli-0.7.1 → jfox_cli-0.8.0}/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [0.8.0] - 2026-05-10
+
+### Features
+- add Claude Code plugin packaging for jfox skills (#209) (#210)
+- 新增 session 笔记类型，专存 AI Agent 会话记录 (#202)
+
+### Changes
+- sync AGENTS.md with CLAUDE.md and current codebase (#208)
+
+[0.8.0]: https://github.com/zhuxixi/jfox/compare/v0.7.2...v0.8.0
+
+## [0.7.2] - 2026-05-07
+
+### Fixes
+- **note**: atomic write to prevent 0-byte note files (#201)
+- strip frontmatter from --content-file input to prevent duplication (#200)
+
+### Changes
+- update CLAUDE.md to reflect current codebase state (#203)
+
+[0.7.2]: https://github.com/zhuxixi/jfox/compare/v0.7.1...v0.7.2
+
 ## [0.7.1] - 2026-05-05
 
 ### Fixes

{jfox_cli-0.7.1 → jfox_cli-0.8.0}/CLAUDE.md

@@ -56,18 +56,21 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 
 | Module | Role |
 |--------|------|
-| `cli.py` | All CLI commands (~2500 lines). Commands follow pattern: `@app.command()` → `_xxx_impl()` helper for reuse |
+| `cli.py` | All CLI commands (~2900 lines). Commands follow pattern: `@app.command()` → `_xxx_impl()` helper for reuse |
 | `config.py` | `ZKConfig` + `use_kb()` context manager for multi-KB switching |
 | `global_config.py` | `GlobalConfigManager` managing `~/.zk_config.json` |
 | `kb_manager.py` | Knowledge base lifecycle (create, rename, remove) |
 | `formatters.py` | Output formats: JSON, CSV, YAML, Table, Paths |
+| `git_extractor.py` | Git 仓库数据提取器（ingest 功能） |
+| `model_downloader.py` | Embedding 模型下载与缓存管理 |
+| `note_index.py` | 笔记索引管理（文件名↔ID 映射） |
 | `indexer.py` | File monitoring (watchdog) + incremental indexing |
 | `note.py` | Markdown file CRUD with YAML frontmatter |
 | `models.py` | `Note` data model with frontmatter serialization |
 | `search_engine.py` | `HybridSearchEngine` with `SearchMode` enum, RRF fusion |
 | `bm25_index.py` | BM25 keyword search index |
 | `embedding_backend.py` | Sentence-transformers embedding backend（支持 daemon 代理） |
-| `daemon/` | Embedding 模型 HTTP 守护进程，`jfox daemon start/stop/status` |
+| `daemon/` | Embedding 模型 HTTP 守护进程 (`server.py`/`client.py`/`process.py`)，`jfox daemon start/stop/status` |
 | `vector_store.py` | ChromaDB vector store for semantic search |
 | `graph.py` | NetworkX knowledge graph from links/backlinks |
 | `template.py` / `template_cli.py` | Jinja2 template system for structured note creation |
@@ -107,11 +110,11 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 - **Model caching**: Session-level model cache in conftest.py to avoid 30-60s reload per test
 - **Test markers**: `slow`, `performance`, `integration`, `embedding`, `workflow`, `bulk`
 - **Run single-process** to avoid ChromaDB/model loading conflicts
-- **Test directory reorganization in progress**:
-  - `tests/unit/` — Pure logic unit tests (formatters, config, kb_manager, template)
-  - `tests/integration/` — Cross-module integration tests (backlinks)
+- **Test directory reorganization mostly complete**:
+  - `tests/unit/` — Pure logic unit tests (25 files)
+  - `tests/integration/` — Cross-module integration tests (backlinks, tag filter, model download)
   - `tests/performance/` — Performance benchmarks
-  - Root-level `test_*_unit.py` files also exist (partial migration)
+  - Root-level `test_config_unit.py` and `test_config_set_unit.py` remain (no longer duplicated, test different things)
 - **pytest.ini**: `timeout=120`, `--strict-markers`, `-ra` (show all test summary)
 
 ## CI (GitHub Actions)
@@ -122,6 +125,8 @@ Four jobs in `.github/workflows/integration-test.yml`:
 - **Full** (manual): All tests, all OS, all Python versions
 - **Coverage** (after fast): Runs coverage on fast tests, uploads HTML/XML artifacts
 
+**Release** workflow in `.github/workflows/publish.yml`: publishes to PyPI on GitHub release publication.
+
 ## Windows Notes
 
 - `robocopy` flags get misinterpreted by bash — use `cmd.exe /c "robocopy source dest /E"`
@@ -135,4 +140,4 @@ Four jobs in `.github/workflows/integration-test.yml`:
 ## Gotchas
 
 - `pytest.ini` `addopts` includes `-v`, so `pytest tests/` already runs verbose — adding `-v` manually is redundant
-- Test directory migration is partial: root-level `test_*_unit.py` files duplicate `tests/unit/` tests
+- Test directory migration mostly complete; root-level `test_config_unit.py` and `test_config_set_unit.py` remain but test different things from `tests/unit/`

{jfox_cli-0.7.1 → jfox_cli-0.8.0}/PKG-INFO

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

jfox_cli-0.8.0/commands/jfox-common.md

@@ -0,0 +1,6 @@
+---
+name: jfox-common
+description: 管理知识库（创建、切换、健康检查）和笔记 CRUD
+---
+
+请调用 jfox-common skill 来完成用户的请求。传递用户提供的参数。

jfox_cli-0.8.0/commands/jfox-ingest.md

@@ -0,0 +1,6 @@
+---
+name: jfox-ingest
+description: 从 Git 仓库导入数据（git log、PR、Issues）为 fleeting 笔记
+---
+
+请调用 jfox-ingest skill 来完成用户的请求。传递用户提供的参数。

jfox_cli-0.8.0/commands/jfox-organize.md

@@ -0,0 +1,6 @@
+---
+name: jfox-organize
+description: 整理知识库、提炼 fleeting 笔记为 permanent、生成 wiki links
+---
+
+请调用 jfox-organize skill 来完成用户的请求。传递用户提供的参数。

jfox_cli-0.8.0/commands/jfox-search.md

@@ -0,0 +1,6 @@
+---
+name: jfox-search
+description: 搜索笔记、图谱查询、链接推荐
+---
+
+请调用 jfox-search skill 来完成用户的请求。传递用户提供的参数。

jfox_cli-0.8.0/commands/jfox-session-summary.md

@@ -0,0 +1,6 @@
+---
+name: jfox-session-summary
+description: 保存会话总结到知识库作为 fleeting 笔记
+---
+
+请调用 jfox-session-summary skill 来完成用户的请求。传递用户提供的参数。

{jfox_cli-0.7.1 → jfox_cli-0.8.0}/jfox/__init__.py

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