jfox-cli 1.15.0__tar.gz → 1.16.0__tar.gz

{jfox_cli-1.15.0 → jfox_cli-1.16.0}/.github/workflows/integration-test.yml

@@ -206,12 +206,12 @@ jobs:
         key: ${{ runner.os }}-sentence-transformers-bge-small-zh-v1.5
 
     - name: Install dependencies
-      run: uv sync --extra dev
+      run: uv sync --extra dev --extra embed
 
     - name: Run core tests
       run: |
         # 只跑核心工作流测试，单进程避免模型加载冲突
-        uv run pytest tests/test_core_workflow.py tests/test_integration.py -v --timeout=400 --tb=short
+        uv run --extra dev --extra embed pytest tests/test_core_workflow.py tests/test_integration.py -v --timeout=400 --tb=short
       timeout-minutes: ${{ matrix.os == 'windows-latest' && 50 || 25 }}
       env:
         PYTHONIOENCODING: utf-8
@@ -264,12 +264,12 @@ jobs:
         key: ${{ runner.os }}-sentence-transformers-bge-small-zh-v1.5
 
     - name: Install dependencies
-      run: uv sync --extra dev
+      run: uv sync --extra dev --extra embed
 
     - name: Run full test suite
       run: |
         # 全量测试，单进程（避免模型加载问题）
-        uv run pytest tests/ -v --timeout=600 --tb=short
+        uv run --extra dev --extra embed pytest tests/ -v --timeout=600 --tb=short
       timeout-minutes: 60
       env:
         PYTHONIOENCODING: utf-8

{jfox_cli-1.15.0 → jfox_cli-1.16.0}/.gitignore

@@ -55,3 +55,4 @@ review_body*.md
 .pr_monitor_state.json
 .tmp_issue_body.md
 .worktrees/
+.venv-noembed/

{jfox_cli-1.15.0 → jfox_cli-1.16.0}/AGENTS.md

@@ -22,7 +22,7 @@
 | 语言 | Python >= 3.10 |
 | CLI 框架 | Typer >= 0.12.0 |
 | 终端美化 | Rich >= 13.0.0 |
-| 文本嵌入 | sentence-transformers >= 3.0 (bge-small-zh-v1.5 / bge-m3) |
+| 文本嵌入 | sentence-transformers >= 3.0 (bge-small-zh-v1.5 / bge-m3)，现为可选 `[embed]` extra (#519) |
 | 向量数据库 | ChromaDB >= 0.5.0 |
 | 知识图谱 | NetworkX >= 3.0 |
 | 文件监控 | Watchdog >= 3.0 |
@@ -89,11 +89,11 @@ jfox/
 ### 安装开发环境
 
 ```bash
-# 安装（使用 uv，推荐）
-uv sync --extra dev
+# 安装（使用 uv，推荐；embed 为语义组件，开发环境需要）
+uv sync --extra dev --extra embed
 
 # 安装（legacy pip fallback）
-pip install -e ".[dev]"
+pip install -e ".[dev,embed]"
 ```
 
 ### 运行测试

{jfox_cli-1.15.0 → jfox_cli-1.16.0}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [1.16.0] - 2026-09-23
+
+### Features
+
+- **install**: split sentence-transformers into [embed] extra with graceful degradation (#519) (#537)
+
+### Fixes
+
+- **cli**: normalize --content-file input - strip leading H1 unconditionally, unify stdin (#541) (#542)
+
+[1.16.0]: https://github.com/zhuxixi/jfox/compare/v1.15.0...v1.16.0
+
 ## [1.15.0] - 2026-09-20
 
 ### Features

{jfox_cli-1.15.0 → jfox_cli-1.16.0}/CLAUDE.md

@@ -13,11 +13,11 @@ JFox is a local-first personal knowledge management CLI tool based on the Zettel
 ## Development Commands
 
 ```bash
-# Install (using uv, recommended)
-uv sync --extra dev
+# Install (using uv, recommended; embed = semantic component, needed for dev)
+uv sync --extra dev --extra embed
 
 # Install (legacy pip fallback)
-pip install -e ".[dev]"
+pip install -e ".[dev,embed]"
 
 # Run tests
 uv run pytest tests/ -v                                # All tests
@@ -130,7 +130,7 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 - **Test utils** (`tests/utils/`): `temp_kb.py`, `jfox_cli.py` (CLI wrapper), `note_generator.py`
 - **全局配置隔离**: conftest 设 `ZK_CONFIG_PATH`（配合既有 `ZK_KB_ROOT`）指向临时目录，pytest 及其拉起的 CLI 子进程不读写真实 `~/.zk_config.json`（#469，`global_config.py` 的 `DEFAULT_CONFIG_PATH` 支持该 env 覆盖）；`JFOX_SYNTHESIS_DB` 同样无条件指临时路径，防 DedupStore 单例写真实 `~/.zettelkasten/synthesis_log.db`（#483）
 - **Model caching**: Session-level model cache in conftest.py to avoid 30-60s reload per test
-- **Test markers**: `slow`, `performance`, `integration`, `embedding`, `workflow`, `bulk`
+- **Test markers**: `slow`, `performance`, `integration`, `embedding`, `workflow`, `bulk`, `no_embed`（#519：需在无 sentence-transformers 环境执行的降级测试，CI Fast 天然满足）
 - **Run single-process** to avoid ChromaDB/model loading conflicts
 - **Test directory reorganization mostly complete**:
   - `tests/unit/` — Pure logic unit tests (25 files)

{jfox_cli-1.15.0 → jfox_cli-1.16.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jfox-cli
-Version: 1.15.0
+Version: 1.16.0
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox
@@ -25,7 +25,6 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: rank-bm25>=0.2.2
 Requires-Dist: rich>=13.0.0
-Requires-Dist: sentence-transformers>=3.0
 Requires-Dist: typer>=0.12.0
 Requires-Dist: tzdata; sys_platform == 'win32'
 Requires-Dist: uvicorn[standard]>=0.27.0
@@ -37,6 +36,8 @@ Requires-Dist: pytest-timeout>=2.0; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: embed
+Requires-Dist: sentence-transformers>=3.0; extra == 'embed'
 Description-Content-Type: text/markdown
 
 # JFox
@@ -95,12 +96,32 @@ install → initialize → create a note → create a link → search
 
 ### Install
 
-For a quick user installation with `uv`:
+The default install is lightweight and CPU-friendly:
 
 ```bash
-uv tool install "git+https://github.com/zhuxixi/jfox.git"
+uv tool install "jfox-cli"
+# or from source: uv tool install "git+https://github.com/zhuxixi/jfox.git"
 ```
 
+It includes note CRUD, BM25 keyword search, and the knowledge graph. It does **not** include semantic vector search (no torch/CUDA download; zero nvidia dependencies on CPU-only machines).
+
+#### Semantic search component (optional)
+
+```bash
+# GPU machines
+uv tool install "jfox-cli[embed]"
+
+# CPU-only machines (UV_TORCH_BACKEND=cpu makes uv resolve the CPU torch build, no CUDA)
+UV_TORCH_BACKEND=cpu uv tool install "jfox-cli[embed]"
+
+# pip users (on CPU machines run first: pip install torch --index-url https://download.pytorch.org/whl/cpu)
+pip install "jfox-cli[embed]"
+```
+
+#### Upgrading from 1.x
+
+Starting with 2.0, the default install no longer bundles the semantic search component. An in-place upgrade (pip/uv do not uninstall existing packages) usually keeps working unchanged; after rebuilding an environment, jfox prints the same install hint the first time a semantic feature is used. After installing the component, run `jfox index rebuild` to backfill the semantic index.
+
 For local development, see [Installation and Development](#installation-and-development).
 
 ### Initialize a knowledge base
@@ -322,7 +343,7 @@ For the current per-skill directory inventory, see the [generated plugin skill i
 ```bash
 git clone https://github.com/zhuxixi/jfox.git
 cd jfox
-uv sync --extra dev
+uv sync --extra dev --extra embed
 ```
 
 Verify the installation:

{jfox_cli-1.15.0 → jfox_cli-1.16.0}/README.md

@@ -54,12 +54,32 @@ install → initialize → create a note → create a link → search
 
 ### Install
 
-For a quick user installation with `uv`:
+The default install is lightweight and CPU-friendly:
 
 ```bash
-uv tool install "git+https://github.com/zhuxixi/jfox.git"
+uv tool install "jfox-cli"
+# or from source: uv tool install "git+https://github.com/zhuxixi/jfox.git"
 ```
 
+It includes note CRUD, BM25 keyword search, and the knowledge graph. It does **not** include semantic vector search (no torch/CUDA download; zero nvidia dependencies on CPU-only machines).
+
+#### Semantic search component (optional)
+
+```bash
+# GPU machines
+uv tool install "jfox-cli[embed]"
+
+# CPU-only machines (UV_TORCH_BACKEND=cpu makes uv resolve the CPU torch build, no CUDA)
+UV_TORCH_BACKEND=cpu uv tool install "jfox-cli[embed]"
+
+# pip users (on CPU machines run first: pip install torch --index-url https://download.pytorch.org/whl/cpu)
+pip install "jfox-cli[embed]"
+```
+
+#### Upgrading from 1.x
+
+Starting with 2.0, the default install no longer bundles the semantic search component. An in-place upgrade (pip/uv do not uninstall existing packages) usually keeps working unchanged; after rebuilding an environment, jfox prints the same install hint the first time a semantic feature is used. After installing the component, run `jfox index rebuild` to backfill the semantic index.
+
 For local development, see [Installation and Development](#installation-and-development).
 
 ### Initialize a knowledge base
@@ -281,7 +301,7 @@ For the current per-skill directory inventory, see the [generated plugin skill i
 ```bash
 git clone https://github.com/zhuxixi/jfox.git
 cd jfox
-uv sync --extra dev
+uv sync --extra dev --extra embed
 ```
 
 Verify the installation:

jfox_cli-1.16.0/docs/installation.md

@@ -0,0 +1,129 @@
+# Installation
+
+## Recommended: uv
+
+### Default install (lightweight, CPU-friendly)
+
+```bash
+# Install as a global tool: note CRUD, BM25 keyword search, and the knowledge
+# graph. No semantic vector search — no torch/CUDA download, zero nvidia
+# dependencies on CPU-only machines.
+uv tool install "jfox-cli"
+
+# Or install from source
+uv tool install "git+https://github.com/zhuxixi/jfox.git"
+
+# Try without installing
+uvx --from "git+https://github.com/zhuxixi/jfox.git" jfox --help
+```
+
+### Semantic search component (optional)
+
+```bash
+# GPU machines
+uv tool install "jfox-cli[embed]"
+
+# CPU-only machines (UV_TORCH_BACKEND=cpu makes uv resolve the CPU torch
+# build, no CUDA)
+UV_TORCH_BACKEND=cpu uv tool install "jfox-cli[embed]"
+
+# pip users (on CPU machines run first: pip install torch --index-url
+# https://download.pytorch.org/whl/cpu)
+pip install "jfox-cli[embed]"
+```
+
+### For local development
+
+```bash
+# Clone and install for local development
+git clone https://github.com/zhuxixi/jfox.git
+cd jfox
+uv sync --extra dev --extra embed
+```
+
+Verify:
+
+```bash
+jfox --help
+jfox --version
+```
+
+## Legacy: pip
+
+```bash
+pip install -e ".[dev,embed]"
+```
+
+## Upgrade
+
+```bash
+# Auto-detect installation method and upgrade
+jfox update
+
+# JSON output with version info
+jfox update --json
+```
+
+If `jfox update` fails (e.g. behind a proxy or on an unsupported install method), use the manual command for your install method:
+
+```bash
+# uv tool users
+uv tool upgrade jfox-cli
+
+# pipx users
+pipx upgrade jfox-cli
+
+# pip users
+pip install --upgrade jfox-cli
+
+# Development mode (git clone + uv sync --extra dev --extra embed)
+git pull && uv sync --extra dev --extra embed
+```
+
+### Upgrading from 1.x
+
+Starting with 2.0, the default install no longer bundles the semantic search component. An in-place upgrade (pip/uv do not uninstall existing packages) usually keeps working unchanged; after rebuilding an environment, jfox prints the same install hint the first time a semantic feature is used. After installing the `[embed]` component, run `jfox index rebuild` to backfill the semantic index.
+
+## Uninstall
+
+```bash
+# uv users
+uv tool uninstall jfox-cli
+
+# pip users
+pip uninstall jfox-cli
+```
+
+## Requirements
+
+- Python >= 3.10
+- Core dependencies: typer, rich, chromadb, networkx, watchdog, pyyaml, fastapi, uvicorn
+- Optional `[embed]` extra: sentence-transformers (+ torch) — required only for semantic vector search
+
+## Windows PATH
+
+If `jfox` command is not found after installation:
+
+**uv users:**
+
+```powershell
+# Check uv tool install path
+uv tool dir
+# Add the corresponding bin directory to PATH
+```
+
+**pip users:**
+
+```powershell
+# Check install location
+pip show jfox-cli | findstr Location
+# Add the Scripts directory to PATH, e.g.:
+# C:\Users\<user>\AppData\Local\Packages\PythonSoftwareFoundation.Python3.13_qbz5n2kfra8p0\LocalCache\local-packages\Python313\Scripts
+```
+
+## HuggingFace Mirror (China)
+
+```bash
+export HF_ENDPOINT=https://hf-mirror.com
+jfox init
+```

{jfox_cli-1.15.0 → jfox_cli-1.16.0}/docs/json-schemas.md

@@ -35,27 +35,29 @@ else:
 
 命令均支持 `--json` 或 `--format json`；`--kb <name>` 选择目标知识库。
 
+其中 #519 新增的降级警告 `warnings[]` 元素统一形状：`{"code": "embedding_unavailable", "message": "<安装提示>", "fallback": "keyword" | "bm25_only"}`；缺语义组件的拒绝错误统一携带 `code: "embed_dependency_missing"`（`error` 含 GPU/CPU/pip 三路安装指引）。
+
 | 命令 | 成功顶层字段 | 实体位置 | 失败形状 |
 |------|--------------|----------|----------|
 | `init` | `success, message, name` | 平铺 | `{success, error}` |
-| `add` | `success, id, title, note{id,title,type,filepath,links}` + 可选 `warnings, backfill_failures, rollback_failures, backfill_note_save_failed, vector_dimension_warning` | 嵌套 `note`；顶层冗余 `id`/`title` | 重复：`{success, skipped:"duplicate", duplicate{matched_id,matched_title,matched_by,score}}`；其余 `{success, error}` |
-| `search` | `success, query, mode, include_archived, total, results[]` | 列表 `results` | `{success, error}` |
-| `status` | `success, knowledge_base{path,exists}, stats, backend{type,model,dimension}` | 嵌套三段 | `{success, error}` |
+| `add` | `success, id, title, note{id,title,type,filepath,links}` + 可选 `warnings, backfill_failures, rollback_failures, backfill_note_save_failed, vector_dimension_warning, semantic_index_warning`（#519 无语义组件时降级提示） | 嵌套 `note`；顶层冗余 `id`/`title` | 重复：`{success, skipped:"duplicate", duplicate{matched_id,matched_title,matched_by,score}}`；其余 `{success, error}` |
+| `search` | `success, query, mode, include_archived, total, results[]` + 可选 `warnings[]`（#519 降级时） | 列表 `results` | `{success, error}`；`--mode semantic` 且无语义服务时拒绝：`{success, code:"embed_dependency_missing", error}`（#519） |
+| `status` | `success, knowledge_base{path,exists}, stats, backend{type,model,dimension}, embedding{local_package,daemon_running,service_available}`（#519 可用性块） | 嵌套三段 | `{success, error}` |
 | `list` | `success, total, notes[]`（项含 `outgoing,incoming`） | 列表 `notes` | `{success, error}` |
 | `show` | `success` + `id,title,type,created,updated,tags,links,backlinks,topic,filepath,content,content_body` + 可选 `source,archived`、candidate 字段（`gem_level` 等）、溯源字段（`source_fragments` 等） | 顶层平铺 | `{success, error}` |
 | `refs` | 默认：`success, notes[]`；`--search`：`success, query, matches[]`；`--note`：`success, note{id,title,type}, forward_links[], backward_links[]`（悬空项带 `dangling:true`） | 分支各异 | `{success, error}` |
 | `delete` | `success, deleted, title` | 平铺 | 入链守卫：`{success, error, references{frontmatter[],body[],total}}`；其余 `{success, error}` |
 | `archive` / `unarchive` | `success, archived`/`unarchived`, `title` | 平铺 | `{success, error}` |
-| `edit` | `success, note{id,title,type,filepath}` + 可选 `title_changed{old,new}, warnings` | 嵌套 `note` | `{success, error}` |
-| `query` | `success, query, semantic_results, results[]` | 列表 `results` | `{success, error}` |
+| `edit` | `success, note{id,title,type,filepath}` + 可选 `title_changed{old,new}, warnings, semantic_index_warning`（#519 无语义组件时） | 嵌套 `note` | `{success, error}` |
+| `query` | `success, query, semantic_results, effective_mode, results[]` + 可选 `warnings[]`（#519 降级时 `effective_mode:"keyword"`） | 列表 `results` | `{success, error}` |
 | `graph` | `--stats`：`success, total_nodes, total_edges, avg_degree, isolated_nodes, clusters, top_hubs[]`；`--orphans`：`success, orphans[]`；`--note`：`success, note_id, title, related[]` | 分支各异 | `{success, error}` |
 | `daily` | `success, date, total, notes[]` | 列表 `notes` | `{success, error}` |
 | `inbox` | `success, total, notes[]` | 列表 `notes` | `{success, error}` |
-| `suggest-links` | `success, content, total_suggestions, threshold, suggestions[]` | 列表 `suggestions` | `{success, error}` |
-| `index <action>` | `rebuild`：`success, indexed, bm25_rebuilt, bm25_indexed[, backlinks_*]`；`rebuild-bm25`：`success, indexed`；`status`：`success, total_indexed, last_indexed, pending_changes, vector_store`；`bm25-status`：`success, bm25_index{...}`；`verify`：`success`（语义见特殊语义说明）+ 透传字段 | 平铺 | `{success, error}`（错误分支需显式 `--json` 开启，见特殊语义说明） |
+| `suggest-links` | `success, content, total_suggestions, threshold, suggestions[]` + 可选 `warnings[]`（#519 降级为关键词匹配时） | 列表 `suggestions` | `{success, error}` |
+| `index <action>` | `rebuild`：`success, indexed, semantic_skipped, bm25_rebuilt, bm25_indexed[, backlinks_*]` + 可选 `warnings[]`（#519 无语义服务时 `semantic_skipped:true`、仅重建 BM25）；`rebuild-bm25`：`success, indexed`；`status`：`success, total_indexed, last_indexed, pending_changes, vector_store`；`bm25-status`：`success, bm25_index{...}`；`verify`：`success`（语义见特殊语义说明）+ 透传字段 | 平铺 | `{success, error}`（错误分支需显式 `--json` 开启，见特殊语义说明） |
 | `kb <action>` | `list`：`success, current, knowledge_bases[]`；`create/switch/use/remove/delete/rename`：`success, message`；`current/info`：`success, name, path, total_notes, by_type, created, last_used, description, is_current` | 平铺实体 | `{success, error}`（错误分支需显式 `--json` 开启，见特殊语义说明） |
-| `ingest-log` | `success, repo_path, commits_extracted, imported, failed, total`（空仓库带 `message`） | 平铺计数 | `{success, error}` |
-| `bulk-import` | `success, imported, failed, total`（`--json` 默认开启） | 平铺计数 | `{success, error}` |
+| `ingest-log` | `success, repo_path, commits_extracted, imported, failed, total`（空仓库带 `message`） | 平铺计数 | `{success, error}`；缺语义组件拒绝：`{success, code:"embed_dependency_missing", error}`（#519） |
+| `bulk-import` | `success, imported, failed, total`（`--json` 默认开启） | 平铺计数 | `{success, error}`；缺语义组件拒绝：`{success, code:"embed_dependency_missing", error}`（#519） |
 | `check` | `success, total, issues[{file,issue,size}]`（发现 issue 时退出码 1，见特殊语义说明） | 列表 `issues` | `{success, error}` |
 | `update` | `success, method, previous_version, current_version, already_latest, command, output, stderr, error`（成功时 `error` 为空串）+ dev 分支 `message` | 平铺 | 同形状 `success:false` |
 | `redirect` | `success, old_id, keep_id, files_changed, frontmatter_links_updated, body_links_updated, backlinks_updated, conflicts[], unreadable_files[], errors[], verification_passed[, dry_run]` | 平铺计数 + 列表 | `{success, error, errors[], conflicts[], unreadable_files[], verification_passed}`（`error` 为首条错误 / 冲突或不可读文件计数摘要 / 验证未通过提示） |