jfox-cli 1.4.0__tar.gz → 1.5.0__tar.gz

jfox_cli-1.5.0/.claude/skills/release-cc-plugin/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: release-cc-plugin
+description: Release a new version of the cc-plugin (Claude Code marketplace). Bumps the three version fields in lockstep, opens a PR. Triggers on "发 cc-plugin", "plugin 发版", "release cc plugin", "bump plugin version", "发布 cc 插件".
+---
+
+# Release cc-plugin Skill
+
+把 cc-plugin 发版流程固化：三处版本号同步 bump → PR 合 main。**不打 tag、不发 PyPI**
+（`.claude-plugin/marketplace.json` 的 `source` 指向仓库内 `./packages/cc-plugin`，合 main 后用户 `/plugin update` 自动拉新）。
+
+⚠️ 这是 **cc-plugin** 发版（marketplace，0.5.x）。CLI/PyPI 发版（1.x.x）用 `/release`。
+kimi-plugin 是另一条轨道，本 skill 不管。
+
+## 用法
+
+```
+/release-cc-plugin patch     # bump patch: 0.5.1 → 0.5.2
+/release-cc-plugin minor     # bump minor: 0.5.1 → 0.6.0
+/release-cc-plugin major     # bump major: 0.5.1 → 1.0.0
+/release-cc-plugin 0.7.0     # 指定版本
+```
+
+默认建议 patch（无新 skill/command → semver patch）。
+
+## 执行流程
+
+严格按步，每步完成才进下一步。
+
+### Step 1: 前置校验
+
+任一不符即停并告知原因。
+
+```bash
+git branch --show-current                                # 期望 main
+git status --porcelain                                   # 期望 空
+git branch --list 'chore/bump-cc-plugin-*'               # 期望 空
+gh pr list --state open --head "chore/bump-cc-plugin-*"  # 期望 空
+```
+
+### Step 2: dry-run 预览
+
+```bash
+uv run python .claude/skills/release-cc-plugin/release_cc_plugin_helper.py <version> --dry-run
+```
+
+解析 JSON：`current_version` / `new_version` / `files_to_change` / `changelog_summary`。
+
+### Step 3: 展示并等确认
+
+向用户展示：
+
+```
+📦 cc-plugin Release 预览:
+  当前版本: {current_version}
+  新版本号: {new_version}
+  changelog:
+  {changelog_summary 逐行}
+
+将修改（三处同步，由 helper 原子 bump）:
+  - packages/cc-plugin/.claude-plugin/plugin.json
+  - .claude-plugin/marketplace.json（metadata.version + plugins[0].version）
+```
+
+**必须等用户明确确认。** 拒绝或要改则停。
+
+### Step 4: 正式 bump
+
+```bash
+uv run python .claude/skills/release-cc-plugin/release_cc_plugin_helper.py <version>
+```
+
+退出码非 0 → 读 error JSON，告知用户，停。
+
+### Step 5: 分支 / commit / push
+
+```bash
+git checkout -b chore/bump-cc-plugin-{new_version}
+git add packages/cc-plugin/.claude-plugin/plugin.json .claude-plugin/marketplace.json
+git commit -m "chore(cc-plugin): bump version {current_version} → {new_version}"
+git push -u origin chore/bump-cc-plugin-{new_version}
+```
+
+### Step 6: 开 PR
+
+```bash
+gh pr create --title "chore(cc-plugin): bump version {current_version} → {new_version}" --body "<changelog>"
+```
+
+PR body 用 `changelog_summary` 作 release notes，并注明「合 main 后 `/plugin update` 自动拉新，无需 tag/PyPI」。
+
+### Step 7: 告知用户合并
+
+```
+PR 已创建: {URL}
+合并即生效（用户 /plugin update 拉新）。不打 tag、不发 Release。
+```
+
+等用户手动合并。**不自动创建 tag / GitHub Release。**
+
+## 注意
+
+- 三处版本号由 helper 原子 bump（命中数不符报错不写），堵 CLAUDE.md 点名的「漏改任一处」坑。
+- 不要用 `/release`（那是 CLI/PyPI）。
+- 合 main 即发布；如需追溯可手动 `gh release create cc-plugin-v<x>`，但非默认。

jfox_cli-1.5.0/.claude/skills/release-cc-plugin/release_cc_plugin_helper.py

@@ -0,0 +1,238 @@
+#!/usr/bin/env python3
+"""
+cc-plugin release 辅助脚本
+
+处理版本号计算、三处版本号同步 bump、changelog 生成。
+输出 JSON 供 Claude 解析。
+
+用法:
+    python release_cc_plugin_helper.py patch          # bump patch
+    python release_cc_plugin_helper.py minor          # bump minor
+    python release_cc_plugin_helper.py major          # bump major
+    python release_cc_plugin_helper.py 0.6.0          # 指定版本
+    python release_cc_plugin_helper.py ... --dry-run  # 只计算不修改文件
+"""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+# 项目根目录（脚本位于 .claude/skills/release-cc-plugin/，向上 3 级）
+PROJECT_ROOT = Path(__file__).resolve().parents[3]
+PLUGIN_JSON_REL = "packages/cc-plugin/.claude-plugin/plugin.json"
+MARKETPLACE_JSON_REL = ".claude-plugin/marketplace.json"
+VERSION_RE = re.compile(r"^\d+\.\d+\.\d+$")
+
+
+def output_json(data: dict) -> None:
+    print(json.dumps(data, ensure_ascii=False))
+
+
+def output_error(msg: str) -> None:
+    output_json({"error": msg})
+    sys.exit(1)
+
+
+def _version_tuple(v: str) -> tuple[int, ...]:
+    return tuple(int(x) for x in v.split("."))
+
+
+def read_current_version(root: Path) -> str:
+    """从 plugin.json 读当前版本号（单一真相源）。"""
+    data = json.loads((root / PLUGIN_JSON_REL).read_text(encoding="utf-8"))
+    return data["version"]
+
+
+def compute_new_version(current: str, spec: str) -> str:
+    """patch/minor/major 递增或 explicit x.y.z；结果必须 > current，否则 raise ValueError。"""
+    if not VERSION_RE.match(current):
+        raise ValueError(f"非法当前版本号: {current!r}")
+    if spec in ("patch", "minor", "major"):
+        major, minor, patch = _version_tuple(current)
+        if spec == "patch":
+            new = f"{major}.{minor}.{patch + 1}"
+        elif spec == "minor":
+            new = f"{major}.{minor + 1}.0"
+        else:
+            new = f"{major + 1}.0.0"
+    elif VERSION_RE.match(spec):
+        new = spec
+    else:
+        raise ValueError(f"非法版本号规格: {spec!r}（需 patch/minor/major 或 x.y.z）")
+    if _version_tuple(new) <= _version_tuple(current):
+        raise ValueError(f"新版本 {new} 须大于当前 {current}（不允许降级/同号）")
+    return new
+
+
+def find_last_bump_commit(root: Path, current_version: str) -> str | None:
+    """定位上次发版提交：引入 current_version 的提交；降级为最近改 marketplace.json 的提交。"""
+    rel = MARKETPLACE_JSON_REL
+    for args in (
+        ["git", "log", "-S", f'"version": "{current_version}"', "--format=%H", "--", rel],
+        ["git", "log", "--format=%H", "-1", "--", rel],
+    ):
+        try:
+            out = subprocess.run(
+                args,
+                cwd=root,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                check=True,
+            )
+        except subprocess.CalledProcessError:
+            continue
+        hits = [ln for ln in out.stdout.splitlines() if ln.strip()]
+        if hits:
+            return hits[0]
+    return None
+
+
+def get_changelog(root: Path, current_version: str) -> list[str]:
+    """自上次发版以来 packages/cc-plugin/ 的 oneline 提交摘要；无基线时取最近 30 条。"""
+    last = find_last_bump_commit(root, current_version)
+    if last:
+        args = ["git", "log", "--oneline", f"{last}..HEAD", "--", "packages/cc-plugin/"]
+    else:
+        # 无基线：用 --max-count 避免 HEAD~30 在浅克隆/小仓报 bad revision
+        args = ["git", "log", "--oneline", "--max-count=30", "--", "packages/cc-plugin/"]
+    try:
+        out = subprocess.run(
+            args,
+            cwd=root,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            check=True,
+        )
+    except subprocess.CalledProcessError:
+        return []
+    return [ln for ln in out.stdout.splitlines() if ln.strip()]
+
+
+def assert_versions(root: Path, expected: str) -> None:
+    """断言三处版本号都 == expected，否则 raise AssertionError。"""
+    plugin = json.loads((root / PLUGIN_JSON_REL).read_text(encoding="utf-8"))
+    market = json.loads((root / MARKETPLACE_JSON_REL).read_text(encoding="utf-8"))
+    actuals = [
+        plugin["version"],
+        market["metadata"]["version"],
+        market["plugins"][0]["version"],
+    ]
+    if any(a != expected for a in actuals):
+        raise AssertionError(f"写后版本号校验失败: 期望 {expected}，实际 {actuals}")
+
+
+def _read_raw(path: Path) -> str:
+    """读原始文本（不做换行转换），保留文件原换行。"""
+    return path.read_bytes().decode("utf-8")
+
+
+def _write_raw(path: Path, text: str) -> None:
+    """写文本，newline='' 避免 Windows 把 LF 转 CRLF 污染 diff。"""
+    path.write_text(text, encoding="utf-8", newline="")
+
+
+def bump_version_files(root: Path, old: str, new: str) -> list[str]:
+    """原子 bump 三处版本号：计数预校验 + 落盘失败回滚已写文件 + 写后断言。"""
+    targets = [
+        (root / PLUGIN_JSON_REL, 1),
+        (root / MARKETPLACE_JSON_REL, 2),
+    ]
+    needle = f'"version": "{old}"'
+    replacement = f'"version": "{new}"'
+    # 预校验：读原文 + 计数，全过才准备落盘
+    pending = []  # (path, original_text, new_text, rel)
+    for path, expected_count in targets:
+        original = _read_raw(path)
+        count = original.count(needle)
+        if count != expected_count:
+            raise ValueError(
+                f"{path.relative_to(root)} 命中 {count} 次（期望 {expected_count}），"
+                f"版本号 {old}。中止，未写任何文件。"
+            )
+        pending.append(
+            (path, original, original.replace(needle, replacement), path.relative_to(root))
+        )
+    # 落盘：先记账再写，任一写/断言失败则回滚已写文件（尽力，堵 CLAUDE.md 版本不一致坑）
+    written: list[tuple[Path, str]] = []
+    try:
+        for path, original, new_text, _ in pending:
+            written.append((path, original))  # 先记账：写中途失败也回滚此文件
+            _write_raw(path, new_text)
+        assert_versions(root, new)  # 写后兜底断言；失败也走回滚
+    except Exception:
+        for path, original in written:
+            try:
+                _write_raw(path, original)
+            except OSError:
+                pass  # 回滚失败只能尽力而为
+        raise
+    return [str(rel) for _, _, _, rel in pending]
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="cc-plugin release helper")
+    parser.add_argument("version", help="patch | minor | major | x.y.z")
+    parser.add_argument("--dry-run", action="store_true", help="只计算不修改文件")
+    args = parser.parse_args()
+
+    try:
+        current = read_current_version(PROJECT_ROOT)
+    except (
+        json.JSONDecodeError,
+        UnicodeDecodeError,
+        KeyError,
+        FileNotFoundError,
+        PermissionError,
+        OSError,
+    ) as e:
+        output_error(f"读取当前版本失败: {e}")  # output_error 会 sys.exit(1)
+
+    try:
+        new = compute_new_version(current, args.version)
+    except ValueError as e:
+        output_error(str(e))
+
+    changelog = get_changelog(PROJECT_ROOT, current)
+
+    if args.dry_run:
+        output_json(
+            {
+                "current_version": current,
+                "new_version": new,
+                "files_to_change": [PLUGIN_JSON_REL, MARKETPLACE_JSON_REL],
+                "changelog_summary": changelog,
+            }
+        )
+        return
+
+    try:
+        changed = bump_version_files(PROJECT_ROOT, current, new)
+    except (
+        ValueError,
+        AssertionError,
+        KeyError,
+        IndexError,
+        OSError,
+        json.JSONDecodeError,
+    ) as e:
+        output_error(str(e))
+
+    output_json(
+        {
+            "current_version": current,
+            "new_version": new,
+            "changed_files": changed,
+            "changelog_summary": changelog,
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

{jfox_cli-1.4.0 → jfox_cli-1.5.0}/AGENTS.md

@@ -476,7 +476,7 @@ class OutputFormatter:
 
 - `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
+- `jfox show <id_or_title>` 复用 `find_note_id_by_title_or_id` 定位笔记，默认输出完整 Markdown（`--json` / `--format json` 输出结构化字段）
 
 ---
 

{jfox_cli-1.4.0 → jfox_cli-1.5.0}/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [1.5.0] - 2026-07-25
+
+### Features
+- **promote-skill**: #319 三模式过审重写（cc+kimi） (#324)
+- **release-cc-plugin**: 新增 cc-plugin 发版 skill (#316)
+- **cli**: jfox show 支持 --json 输出 (#278) (#315)
+
+### Fixes
+- **gem-synth**: candidate 双 H1 标题，strip content 开头冗余 H1 (#320)
+
+### Changes
+- **gem-synth**: dedup 生命周期解耦——消除核心层反向依赖 (#310) (#322)
+- **claude.md**: 补 auto_summary 模块、gem_synth dedup，修正 cc-plugin 版本 (#323)
+- **claude.md**: 补 note 生命周期事件 + numpy lazy-import gotcha (#322) (#326)
+
+[1.5.0]: https://github.com/zhuxixi/jfox/compare/v1.4.0...v1.5.0
+
 ## [1.4.0] - 2026-07-12
 
 ### Features

{jfox_cli-1.4.0 → jfox_cli-1.5.0}/CLAUDE.md

@@ -72,7 +72,8 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 | `embedding_backend.py` | Sentence-transformers embedding backend（支持 daemon 代理） |
 | `daemon/` | Embedding 模型 HTTP 守护进程 (`server.py`/`client.py`/`process.py`)，`jfox daemon start/stop/status` |
 | `fragment/` | 碎片采集：detector 分类 + store SQLite(WAL) + service 编排 |
-| `gem_synth/` | L3 宝石合成：daemon 循环围绕锚点用 transcript + 永久笔记基准合成 candidate 笔记 |
+| `gem_synth/` | L3 宝石合成：daemon 循环围绕锚点用 transcript + 永久笔记基准合成 candidate 笔记；存盘前 `dedup.py` 正文余弦查重；`lifecycle.py` 订阅 note 的 delete/archive/promote/reject 事件同步 dedup 表 |
+| `auto_summary/` | 自动总结子系统：daemon 内扫描 `~/.claude/projects/` 已结束的 Claude Code session，经 `claude -p` 生成摘要写入 `session` 笔记；CLI `jfox auto-summary run/scan/status/enable/disable`，ledger 去重 + schedule time window |
 | `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 |
@@ -103,7 +104,8 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 - **Adding a CLI command**: Add `@app.command()` in `cli.py`, implement `_xxx_impl()` helper, add `--kb` and `--format json` support
 - **Adding a search mode**: Add to `SearchMode` enum in `search_engine.py`, implement in `HybridSearchEngine.search()`, update CLI `--mode` help text
 - **Modifying data models**: Update `Note` class in `models.py`, update `to_markdown()`/`from_markdown()`, consider backward compat
-- **Viewing note content**: `jfox show <id_or_title>` 复用 `find_note_id_by_title_or_id` 定位笔记，只读输出完整 Markdown
+- **Viewing note content**: `jfox show <id_or_title>` 复用 `find_note_id_by_title_or_id` 定位笔记，默认输出完整 Markdown（`--json` / `--format json` 输出结构化字段）
+- **笔记生命周期事件**: `note.py` 只广播 `post_delete`/`post_archive`/`post_promote`/`post_reject`（`register_lifecycle_hook` + `_dispatch`），绝不 import 特性层；特性层订阅做副作用（如 `gem_synth/lifecycle.py` 同步 dedup 表）。`register` 在 `jfox/__init__.py` 接线，任何 `import jfox.*` 即订阅就位，库式调用方零成本
 
 ## Test Infrastructure
 
@@ -142,7 +144,7 @@ JFox ships as a Claude Code plugin. Two-tier structure:
 - `packages/cc-plugin/.claude-plugin/plugin.json` — plugin source metadata
 - `packages/cc-plugin/skills/` — 7 skills: `search`, `ingest`, `manage`, `organize`, `promote`, `session-summary`, `using-jfox`
 
-**Plugin versioning**: bump version in **three** places together — `packages/cc-plugin/.claude-plugin/plugin.json` (`version`) and both version fields in `.claude-plugin/marketplace.json` (`metadata.version` + `plugins[0].version`). 漏改任一处都会导致 marketplace 与 plugin 版本不一致。Current: 0.5.0.
+**Plugin versioning**: bump version in **three** places together — `packages/cc-plugin/.claude-plugin/plugin.json` (`version`) and both version fields in `.claude-plugin/marketplace.json` (`metadata.version` + `plugins[0].version`). 漏改任一处都会导致 marketplace 与 plugin 版本不一致。Current: 0.5.1.
 **Skill rename history**: `kb` → `manage` (v0.2.0) — "manage" is the canonical KB lifecycle + CRUD skill.
 
 ## Branch Rules
@@ -153,3 +155,4 @@ JFox ships as a Claude Code plugin. Two-tier structure:
 
 - `pytest.ini` `addopts` includes `-v`, so `pytest tests/` already runs verbose — adding `-v` manually is redundant
 - 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/`
+- 生命周期订阅模块的重依赖（numpy 等）必须 lazy import 进回调体，不能顶层 import——`jfox/__init__.py` 每次启动都 import 订阅模块，顶层会令 `--version`/`search` 等不相关命令多付 ~70-100ms eager 加载。参考 `gem_synth/lifecycle.py`

{jfox_cli-1.4.0 → jfox_cli-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jfox-cli
-Version: 1.4.0
+Version: 1.5.0
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox
@@ -314,7 +314,7 @@ jfox query "Luhmann's methodology" --depth 2
 | `jfox suggest-links "content"` | Suggest notes to link from content |
 | `jfox bulk-import notes.json` | Bulk import from JSON (optimized) |
 | `jfox ingest-log` | Import git commit history as notes |
-| `jfox show NOTE_ID` | View full note content in terminal |
+| `jfox show NOTE_ID` | View full note content (`--json` for structured fields) |
 
 ### Search & Analysis
 

{jfox_cli-1.4.0 → jfox_cli-1.5.0}/README.md

@@ -274,7 +274,7 @@ jfox query "Luhmann's methodology" --depth 2
 | `jfox suggest-links "content"` | Suggest notes to link from content |
 | `jfox bulk-import notes.json` | Bulk import from JSON (optimized) |
 | `jfox ingest-log` | Import git commit history as notes |
-| `jfox show NOTE_ID` | View full note content in terminal |
+| `jfox show NOTE_ID` | View full note content (`--json` for structured fields) |
 
 ### Search & Analysis