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

jfox_cli-0.4.3/.claude/skills/release/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: release
+description: Release a new version of jfox. Bumps version, generates CHANGELOG, creates PR and GitHub Release. Triggers on "发版", "release", "bump version", "发布版本".
+---
+
+# Release Skill
+
+将 jfox 发版流程从多步手动操作简化为一条命令。覆盖版本号 bump → CHANGELOG → commit → PR → GitHub Release 全流程。
+
+## 用法
+
+```
+/release 0.5.0          # 指定具体版本号
+/release patch          # bump patch: 0.4.1 → 0.4.2
+/release minor          # bump minor: 0.4.1 → 0.5.0
+/release major          # bump major: 0.4.1 → 1.0.0
+```
+
+## 执行流程
+
+严格按照以下步骤执行。每一步必须完成后再进入下一步。
+
+### Step 1: 前置校验
+
+运行以下检查，任何一项失败则立即停止并告知用户原因：
+
+```bash
+# 1. 当前分支必须是 main
+git branch --show-current
+# 期望输出: main
+
+# 2. 工作区必须干净
+git status --porcelain
+# 期望输出: 空
+
+# 3. 不存在未合并的 bump 分支
+git branch --list 'chore/bump-*'
+# 期望输出: 空
+
+# 4. 没有未合并的 bump PR
+gh pr list --state open --head "chore/bump-*"
+# 期望输出: 空
+```
+
+### Step 2: 运行辅助脚本（预览模式）
+
+用 `--dry-run` 先预览计算结果：
+
+```bash
+uv run python .claude/skills/release/release_helper.py <version> --dry-run
+```
+
+解析 JSON 输出，提取 `current_version`、`new_version`、`changelog_preview`、`changelog_summary`。
+
+### Step 3: 展示变更摘要并等待确认
+
+向用户展示：
+
+```
+📦 Release 预览:
+  当前版本: {current_version}
+  新版本号: {new_version}
+  变更摘要: {changelog_summary}
+
+CHANGELOG 预览:
+{changelog_preview}
+
+将修改的文件:
+  - pyproject.toml
+  - jfox/__init__.py
+  - uv.lock
+  - CHANGELOG.md
+```
+
+**必须等待用户明确确认后才继续。** 如果用户拒绝或要求修改，停止流程。
+
+### Step 4: 运行辅助脚本（正式模式）
+
+```bash
+uv run python .claude/skills/release/release_helper.py <version>
+```
+
+确认脚本退出码为 0。如果非 0，读取错误信息并告知用户，停止流程。
+
+### Step 5: Git 操作
+
+```bash
+# 创建分支
+git checkout -b chore/bump-version-{new_version}
+
+# 暂存文件
+git add pyproject.toml jfox/__init__.py uv.lock CHANGELOG.md
+
+# 提交
+git commit -m "chore: bump version to {new_version}"
+
+# 推送
+git push -u origin chore/bump-version-{new_version}
+```
+
+### Step 6: 创建 PR
+
+使用 CHANGELOG 内容作为 PR body：
+
+```bash
+gh pr create \
+  --title "chore: bump version to {new_version}" \
+  --body "$(cat <<'EOF'
+## Summary
+Bump version from {current_version} to {new_version}
+
+{changelog_preview}
+
+🤖 Generated with [Claude Code](https://claude.com/claude-code)
+EOF
+)"
+```
+
+记录返回的 PR URL。
+
+### Step 7: 等待合并
+
+告知用户：
+
+```
+PR 已创建: {PR_URL}
+请合并此 PR 后告知我，我将继续创建 GitHub Release。
+```
+
+等待用户确认 PR 已合并。
+
+### Step 8: 切回 main 并拉取最新代码
+
+```bash
+git checkout main
+git pull origin main
+```
+
+### Step 9: 创建 GitHub Release
+
+```bash
+gh release create v{new_version} \
+  --title "v{new_version}" \
+  --notes "$(cat <<'EOF'
+{changelog_preview}
+EOF
+)"
+```
+
+告知用户：
+
+```
+Release v{new_version} 已创建！
+GitHub Actions 将自动发布到 PyPI。
+可在 https://github.com/zhuxixi/jfox/actions 监控发布状态。
+```
+
+## 错误处理
+
+- 脚本返回非零退出码 → 读取错误 JSON，展示给用户，停止流程
+- git 操作失败 → 展示错误信息，建议用户手动修复
+- PR 创建失败 → 检查是否已有同名 PR，或提示权限问题
+- Release 创建失败 → 检查 tag 是否已存在，或提示权限问题
+
+## 注意事项
+
+- **不使用 `--no-verify`**，保持 pre-commit hook 正常运行
+- **始终在新分支操作**，不直接修改 main
+- **每个确认点都必须等待**，不自动跳过

jfox_cli-0.4.3/.claude/skills/release/release_helper.py

@@ -0,0 +1,337 @@
+#!/usr/bin/env python3
+"""
+jfox release 辅助脚本
+
+处理版本号计算、文件更新、CHANGELOG 生成。
+输出 JSON 供 Claude 解析。
+
+用法:
+    python release_helper.py patch          # bump patch
+    python release_helper.py minor          # bump minor
+    python release_helper.py major          # bump major
+    python release_helper.py 0.5.0          # 指定版本
+    python release_helper.py ... --dry-run  # 只计算不修改文件
+"""
+import json
+import re
+import subprocess
+import sys
+from datetime import date
+from pathlib import Path
+
+# 项目根目录（脚本位于 .claude/skills/release/，向上 3 级）
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+PYPROJECT_TOML = PROJECT_ROOT / "pyproject.toml"
+INIT_PY = PROJECT_ROOT / "jfox" / "__init__.py"
+CHANGELOG_MD = PROJECT_ROOT / "CHANGELOG.md"
+
+
+def output_json(data: dict):
+    """输出 JSON 到 stdout"""
+    print(json.dumps(data, ensure_ascii=False))
+
+
+def output_error(msg: str):
+    """输出错误 JSON 并退出"""
+    output_json({"error": msg})
+    sys.exit(1)
+
+
+def read_current_version() -> str:
+    """从 pyproject.toml 读取当前版本号"""
+    if not PYPROJECT_TOML.exists():
+        output_error(f"未找到 {PYPROJECT_TOML}")
+    content = PYPROJECT_TOML.read_text(encoding="utf-8")
+    match = re.search(r'^version\s*=\s*"(\d+\.\d+\.\d+)"', content, re.MULTILINE)
+    if not match:
+        output_error(f"未在 {PYPROJECT_TOML} 中找到 version 字段")
+    return match.group(1)
+
+
+def parse_bump(arg: str, current: str) -> str:
+    """解析版本参数，返回新版本号"""
+    # 尝试作为 bump 类型
+    if arg in ("patch", "minor", "major"):
+        parts = [int(x) for x in current.split(".")]
+        if arg == "patch":
+            parts[2] += 1
+        elif arg == "minor":
+            parts[1] += 1
+            parts[2] = 0
+        elif arg == "major":
+            parts[0] += 1
+            parts[1] = 0
+            parts[2] = 0
+        return f"{parts[0]}.{parts[1]}.{parts[2]}"
+
+    # 尝试作为 semver
+    if not re.match(r"^\d+\.\d+\.\d+$", arg):
+        output_error(f"无效的版本号或 bump 类型: {arg}（期望 patch/minor/major 或 X.Y.Z）")
+
+    # 确保新版本 > 当前版本
+    new_parts = [int(x) for x in arg.split(".")]
+    cur_parts = [int(x) for x in current.split(".")]
+    if new_parts <= cur_parts:
+        output_error(f"新版本 {arg} 不大于当前版本 {current}")
+
+    return arg
+
+
+def update_files(new_version: str, current_version: str):
+    """更新 pyproject.toml、__init__.py、uv.lock"""
+    if not PYPROJECT_TOML.exists():
+        output_error(f"未找到 {PYPROJECT_TOML}")
+    if not INIT_PY.exists():
+        output_error(f"未找到 {INIT_PY}")
+
+    # 先读取备份
+    toml_content = PYPROJECT_TOML.read_text(encoding="utf-8")
+    init_content = INIT_PY.read_text(encoding="utf-8")
+
+    # 更新 pyproject.toml
+    new_toml = re.sub(
+        r'^version\s*=\s*"\d+\.\d+\.\d+"',
+        f'version = "{new_version}"',
+        toml_content,
+        flags=re.MULTILINE,
+    )
+    PYPROJECT_TOML.write_text(new_toml, encoding="utf-8")
+
+    # 更新 __init__.py
+    new_init = re.sub(
+        r'__version__\s*=\s*"\d+\.\d+\.\d+"',
+        f'__version__ = "{new_version}"',
+        init_content,
+    )
+    INIT_PY.write_text(new_init, encoding="utf-8")
+
+    # uv.lock — 如果失败则回滚
+    result = subprocess.run(
+        ["uv", "lock"],
+        cwd=str(PROJECT_ROOT),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        # 回滚
+        PYPROJECT_TOML.write_text(toml_content, encoding="utf-8")
+        INIT_PY.write_text(init_content, encoding="utf-8")
+        output_error(f"uv lock 失败，已回滚文件变更: {result.stderr}")
+
+
+def get_last_tag() -> str:
+    """获取最新的 git tag"""
+    result = subprocess.run(
+        ["git", "describe", "--tags", "--abbrev=0"],
+        cwd=str(PROJECT_ROOT),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0:
+        return ""  # 没有 tag
+    return result.stdout.strip()
+
+
+def parse_commits(last_tag: str) -> list[dict]:
+    """解析 last_tag..HEAD 之间的 commit，返回分类后的条目列表"""
+    if last_tag:
+        range_spec = f"{last_tag}..HEAD"
+    else:
+        range_spec = "HEAD"
+
+    # -c core.quotepath=false 确保 git 输出中文不被转义
+    result = subprocess.run(
+        ["git", "-c", "core.quotepath=false", "-c", "i18n.logoutputencoding=utf-8",
+         "log", range_spec, "--format=%s"],
+        cwd=str(PROJECT_ROOT),
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    if result.returncode != 0 or not result.stdout:
+        return []
+
+    entries = []
+    seen = set()  # 去重（merge commit 和 squash 可能重复）
+
+    for line in result.stdout.strip().split("\n"):
+        if not line.strip():
+            continue
+
+        # 跳过 bump version 的 commit
+        if "bump version" in line.lower():
+            continue
+
+        # 跳过纯 merge commit
+        if line.startswith("Merge ") and not any(
+            x in line for x in ["feat", "fix", "refactor", "docs", "chore", "perf"]
+        ):
+            continue
+
+        # 解析 conventional commit: type(scope): message (#PR)
+        match = re.match(
+            r"^(feat|fix|refactor|docs|chore|perf)(?:\(([^)]+)\))?:\s*(.+?)(?:\s*\(#(\d+)\))?$",
+            line,
+        )
+        if match:
+            entry = {
+                "type": match.group(1),
+                "scope": match.group(2) or "",
+                "message": match.group(3).strip(),
+                "pr": int(match.group(4)) if match.group(4) else None,
+            }
+        else:
+            # 非 conventional commit 格式
+            pr_match = re.search(r"\(#(\d+)\)", line)
+            entry = {
+                "type": "other",
+                "scope": "",
+                "message": line.strip(),
+                "pr": int(pr_match.group(1)) if pr_match else None,
+            }
+
+        # 去重 key
+        key = (entry["type"], entry["scope"], entry["message"])
+        if key not in seen:
+            seen.add(key)
+            entries.append(entry)
+
+    return entries
+
+
+def generate_changelog(new_version: str, current_version: str, entries: list[dict], last_tag: str = "") -> str:
+    """生成 CHANGELOG Markdown 内容"""
+    today = date.today().isoformat()
+
+    # 按 type 分类
+    features = [e for e in entries if e["type"] == "feat"]
+    fixes = [e for e in entries if e["type"] == "fix"]
+    perfs = [e for e in entries if e["type"] == "perf"]
+    changes = [e for e in entries if e["type"] not in ("feat", "fix", "perf")]
+
+    lines = [f"## [{new_version}] - {today}", ""]
+
+    def format_entry(e: dict) -> str:
+        scope = f"**{e['scope']}**: " if e["scope"] else ""
+        pr = f" (#{e['pr']})" if e["pr"] else ""
+        return f"- {scope}{e['message']}{pr}"
+
+    if features:
+        lines.append("### Features")
+        lines.extend(format_entry(e) for e in features)
+        lines.append("")
+
+    if fixes:
+        lines.append("### Fixes")
+        lines.extend(format_entry(e) for e in fixes)
+        lines.append("")
+
+    if perfs:
+        lines.append("### Performance")
+        lines.extend(format_entry(e) for e in perfs)
+        lines.append("")
+
+    if changes:
+        lines.append("### Changes")
+        lines.extend(format_entry(e) for e in changes)
+        lines.append("")
+
+    # 底部比较链接
+    tag_prev = last_tag.lstrip("v") if last_tag else current_version
+    lines.append(
+        f"[{new_version}]: https://github.com/zhuxixi/jfox/compare/"
+        f"v{tag_prev}...v{new_version}"
+    )
+
+    return "\n".join(lines)
+
+
+def update_changelog_file(new_changelog: str):
+    """将新条目插入 CHANGELOG.md 头部"""
+    if not CHANGELOG_MD.exists():
+        content = "# Changelog\n\n"
+    else:
+        content = CHANGELOG_MD.read_text(encoding="utf-8")
+
+    # 在第一个 ## 之前插入
+    insert_pos = content.find("\n## ")
+    if insert_pos == -1:
+        content = content.rstrip("\n") + "\n\n" + new_changelog + "\n"
+    else:
+        content = content[: insert_pos + 1] + new_changelog + "\n\n" + content[insert_pos + 1 :]
+
+    CHANGELOG_MD.write_text(content, encoding="utf-8")
+
+
+def summarize_entries(entries: list[dict]) -> str:
+    """生成条目摘要"""
+    counts = {}
+    for e in entries:
+        t = e["type"]
+        if t == "feat":
+            counts["feature"] = counts.get("feature", 0) + 1
+        elif t == "fix":
+            counts["fix"] = counts.get("fix", 0) + 1
+        else:
+            counts["change"] = counts.get("change", 0) + 1
+
+    parts = []
+    for label in ("feature", "fix", "change"):
+        if label in counts:
+            plural = {"feature": "features", "fix": "fixes", "change": "changes"}
+            name = plural[label] if counts[label] > 1 else label
+            parts.append(f"{counts[label]} {name}")
+    return ", ".join(parts) if parts else "0 changes"
+
+
+def main():
+    if len(sys.argv) < 2:
+        output_error("用法: release_helper.py <version|patch|minor|major> [--dry-run]")
+
+    version_arg = sys.argv[1]
+    dry_run = "--dry-run" in sys.argv
+
+    # 1. 读取当前版本
+    current_version = read_current_version()
+
+    # 2. 计算新版本
+    new_version = parse_bump(version_arg, current_version)
+
+    # 3. 解析 commits
+    last_tag = get_last_tag()
+    entries = parse_commits(last_tag)
+
+    # 4. 生成 CHANGELOG
+    changelog = generate_changelog(new_version, current_version, entries, last_tag)
+
+    result = {
+        "current_version": current_version,
+        "new_version": new_version,
+        "last_tag": last_tag,
+        "changelog_preview": changelog,
+        "changelog_entries": entries,
+        "changelog_summary": summarize_entries(entries),
+        "files_modified": ["pyproject.toml", "jfox/__init__.py", "uv.lock", "CHANGELOG.md"],
+    }
+
+    if dry_run:
+        output_json(result)
+        return
+
+    # 5. 更新文件
+    update_files(new_version, current_version)
+
+    # 6. 更新 CHANGELOG
+    update_changelog_file(changelog)
+
+    # 7. 输出结果
+    output_json(result)
+
+
+if __name__ == "__main__":
+    main()

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

@@ -2,6 +2,36 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [0.4.3] - 2026-04-28
+
+### Features
+- 内网模型自动下载（3步降级重试链） (#173)
+
+### Fixes
+- **daemon**: eliminate deprecation warnings in daemon log (#171)
+
+[0.4.3]: https://github.com/zhuxixi/jfox/compare/v0.4.2...v0.4.3
+
+## [0.4.2] - 2026-04-22
+
+### Features
+- add Kimi CLI skill collection (#166)
+- **skills**: add release skill with full workflow instructions
+- **skills**: add release helper script with version bump and CHANGELOG generation
+
+### Fixes
+- **lint**: remove unused pytest import
+- **skills**: improve git Chinese encoding and fix pluralization in release helper
+- **skills**: address code review issues in release helper
+- **cli**: list 命令 table 输出显示完整 18 位笔记 ID
+
+### Changes
+- style(lint): format test_release_helper.py with black
+- Merge pull request #167 from zhuxixi/feat/kimi-cli-skills
+- Merge pull request #165 from zhuxixi/fix-list-id-truncation
+
+[0.4.2]: https://github.com/zhuxixi/jfox/compare/v0.4.1...v0.4.2
+
 ## [0.2.0] - 2026-04-13
 
 ### Features

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

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

{jfox_cli-0.4.1 → jfox_cli-0.4.3}/jfox/__init__.py

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

{jfox_cli-0.4.1 → jfox_cli-0.4.3}/jfox/cli.py

@@ -88,6 +88,10 @@ def _main(
 # 添加子命令
 app.add_typer(template_app, name="template", help="Manage note templates")
 
+# Model 下载子命令
+model_app = typer.Typer(name="model", help="模型管理")
+app.add_typer(model_app, name="model", help="模型管理")
+
 console = Console(legacy_windows=False)
 
 
@@ -787,7 +791,7 @@ def _list_impl(
 
         for n in notes:
             created_str = n.created.strftime("%Y-%m-%d") if n.created else ""
-            table.add_row(n.id[:14], n.title[:40], n.type.value, created_str)
+            table.add_row(n.id, n.title[:40], n.type.value, created_str)
 
         console.print(table)
     elif output_format == "tree":
@@ -2674,6 +2678,84 @@ def daemon(
         raise typer.Exit(1)
 
 
+def _download_impl(
+    model: Optional[str],
+    force: bool = False,
+) -> dict:
+    """下载模型实现（可复用）"""
+    from .embedding_backend import EmbeddingBackend
+    from .model_downloader import ModelDownloader
+
+    # 解析模型名
+    if model is None or model == "auto":
+        backend = EmbeddingBackend()
+        device = backend._resolve_device()
+        model = backend._resolve_model_name(device)
+
+    downloader = ModelDownloader(model)
+
+    if force and downloader._check_cached():
+        import shutil
+
+        shutil.rmtree(downloader._model_cache, ignore_errors=True)
+
+    ok = downloader.ensure_cached()
+    return {
+        "model": model,
+        "success": ok,
+        "cache_dir": str(downloader._model_cache),
+        "instructions": downloader.get_manual_instructions() if not ok else "",
+    }
+
+
+@model_app.command("download")
+def download(
+    model: Optional[str] = typer.Option(
+        None, "--model", "-m", help="模型名（默认从配置读取，auto 则按设备自动选择）"
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="强制重新下载（覆盖已有缓存）"),
+    kb: Optional[str] = typer.Option(
+        None, "--kb", "-k", help="目标知识库名称（模型下载不依赖知识库）"
+    ),
+    output_format: str = typer.Option("table", "--format", help="输出格式: json, table"),
+    json_output: bool = typer.Option(False, "--json", help="JSON 输出快捷方式"),
+):
+    """
+    手动下载 embedding 模型
+
+    自动尝试 3 种下载方式（huggingface_hub → 镜像站 → curl）。
+    通常不需要手动调用，daemon start 会自动执行。
+
+    示例:
+
+        jfox model download                    # 下载默认模型
+        jfox model download --model bge-m3     # 下载指定模型
+        jfox model download --force            # 强制重新下载
+        jfox model download --json             # JSON 输出
+    """
+    # kb 参数保持 CLI 一致性（模型下载不依赖知识库）
+    _ = kb
+
+    if json_output:
+        output_format = "json"
+
+    console.print(f"[yellow]准备下载模型: {model or 'auto'}[/yellow]")
+
+    result = _download_impl(model=model, force=force)
+
+    if output_format == "json":
+        console.print(output_json(result))
+    else:
+        if result["success"]:
+            console.print(f"[green]✓ 模型下载完成: {result['model']}[/green]")
+        else:
+            console.print("[red]✗ 模型下载失败[/red]")
+            console.print(Panel(result["instructions"], title="手动下载"))
+
+    if not result["success"]:
+        raise typer.Exit(1)
+
+
 # 入口点
 def main():
     """CLI 入口点"""