jfox-cli 1.7.0__tar.gz → 1.7.2__tar.gz

{jfox_cli-1.7.0 → jfox_cli-1.7.2}/.claude-plugin/marketplace.json

@@ -7,14 +7,14 @@
   },
   "metadata": {
     "description": "JFox Zettelkasten 知识管理工具的 Claude Code 集成",
-    "version": "0.7.2"
+    "version": "0.7.3"
   },
   "plugins": [
     {
       "name": "jfox",
       "source": "./packages/cc-plugin",
       "description": "JFox 知识管理 CLI 的 Claude Code 集成——搜索、写入工作流（导入/整理/会话总结）与知识库管理",
-      "version": "0.7.2",
+      "version": "0.7.3",
       "author": { "name": "zhuxixi" },
       "keywords": ["zettelkasten", "knowledge-management"],
       "category": "workflow"

{jfox_cli-1.7.0 → jfox_cli-1.7.2}/.gitignore

@@ -44,6 +44,9 @@ cache/
 .claude/worktrees/
 .claude/settings.local.json
 
+# Pi (coding agent) local session config
+.pi/
+
 # Temporary analysis files
 analysis_report.md
 kimi-export-*.md

{jfox_cli-1.7.0 → jfox_cli-1.7.2}/CHANGELOG.md

@@ -2,6 +2,33 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [1.7.2] - 2026-08-21
+
+### Fixes
+- **bm25**: 孤儿 tmp 无效时覆盖分支版本撞号，clear 数据复活（#403） (#404)
+- **bm25**: PR #396 cc round-4 遗留修复——clear 快照化/单边态自愈/tmp 消费闭环（#401） (#402)
+- **bm25**: 索引并发写乐观并发控制，根治 daemon 旧快照覆盖回滚（#391） (#396)
+- **update**: 升级期间显示进度提示，stdin 指向 DEVNULL 防挂住 (#394) (#395)
+
+### Changes
+- style(bm25): collapse multi-line condition to single line (pi-lens format)
+- **claude.md**: 记 delete_note backlinks 增量清理语义 (#388) (#397)
+- **claude.md**: 记 CI paths 触发限制（#382） (#384)
+
+[1.7.2]: https://github.com/zhuxixi/jfox/compare/v1.7.1...v1.7.2
+
+## [1.7.1] - 2026-08-16
+
+### Fixes
+- **note**: delete_note 清理目标笔记 backlinks，消除悬空 id (#386) (#388)
+- **note_index**: 抬高 frontmatter 行数上限并消除静默丢弃 (#380) (#382)
+
+### Changes
+- ignore pi local session config (#381)
+- **skill**: session-to-permanent 模板改三层结构（#375） (#377)
+
+[1.7.1]: https://github.com/zhuxixi/jfox/compare/v1.7.0...v1.7.1
+
 ## [1.7.0] - 2026-08-07
 
 ### Features

{jfox_cli-1.7.0 → jfox_cli-1.7.2}/CLAUDE.md

@@ -132,6 +132,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
 
+**CI 触发受 `paths` 限制**：`integration-test.yml` 的 `paths` 只含 `jfox/**`/`tests/**`/`pyproject.toml`/自身——`packages/`（cc/kimi-plugin 发版 bump）、`docs/`、`.claude/` 改动**不触发 CI**。后果：`packages/` 下版本 bump 不跑测试，release-helper 测试须按当前版本动态算「下一版」（勿硬编码），否则只在后续触达 `tests/` 的 PR 才暴露（#382 踩过）。
+
 **Release** workflow in `.github/workflows/publish.yml`: publishes to PyPI on GitHub release publication.
 
 **Local nightly full-test**（#263/#361，非 GitHub Action）：`scripts/nightly_test.sh` 是本机 crontab 定时任务（crontab 行装本机、不进仓库），每周二 09:00 跑 CI `test-fast` 跳过的全量 pytest（performance/bulk/slow/embedding）——成功静默，失败按签名去重复用带 `nightly-test-failure` label 的 issue。前置：今日 #338 备份须成功（读 `~/.jfox-backup/state.json` 的 `last_ok`，否则 `SKIP: 今日备份未确认` 退出）。纯逻辑在 `scripts/nightly_test_helpers.py`（单测 `tests/unit/test_nightly_test_helpers.py`）；`--dry-run` 用人造失败走 issue 流程、不跑真实 pytest。
@@ -177,3 +179,4 @@ JFox ships as a Claude Code plugin. Two-tier structure:
 - 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`
 - `rich` Console 输出机器解析的 JSON 时须 `soft_wrap=True`：默认按 80 列硬折行，会把长字符串（如 Windows 绝对路径）在 JSON 字符串内部断行，`json.loads` 报 Invalid control character（Ubuntu 路径短不触发，只在 Windows CI 挂，#336）。参考 `bookshelf/cli.py` `_emit_json`
+- `delete_note`/`promote_note` 增量同步各 target 的 backlinks（#388 起对称）：单 target 写盘失败仅 warning 不中断；悬空/不对称残留用 `jfox index rebuild --backlinks` 全量重算兜底

{jfox_cli-1.7.0 → jfox_cli-1.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: jfox-cli
-Version: 1.7.0
+Version: 1.7.2
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox
@@ -18,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Requires-Dist: chromadb>=0.5.0
 Requires-Dist: fastapi>=0.110.0
+Requires-Dist: filelock>=3.12
 Requires-Dist: jinja2>=3.0
 Requires-Dist: networkx>=3.0
 Requires-Dist: pydantic>=2.0

jfox_cli-1.7.2/docs/superpowers/plans/2026-08-11-permanent-note-template.md

@@ -0,0 +1,263 @@
+# Permanent 笔记模板重构 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-session-to-permanent` Step 3 的固定三段式模板（事实/Why/How to apply）替换为三层结构（稳定核 + 类型段 + 易变细节），三平台 skill body 逐字一致。
+
+**Architecture:** 单骨架 + 可选类型段。替换三个 skill 文件（pi / cc / kimi）Step 3 里同一段「内容结构」code block，并在其后、写作规范段之前插入「类型段目录 + 选标题原则 + 自检」。替换文字在三个文件中**逐字一致**（靠 Task 4 三方 diff 兜底）。不碰任何 `.py`、不碰 `jfox-promote`、不碰 Step 1/2/4/5、不碰写作规范与 wiki links 段。
+
+**Tech Stack:** Markdown（skill 散文层）。无代码、无测试套件——验证靠 grep 锚点 + 三方 diff。
+
+## Global Constraints
+
+（摘自 spec `docs/superpowers/specs/2026-08-11-permanent-note-template-design.md`，每个任务隐式遵守）
+
+- 纯文档改动：不碰任何 `.py`、不碰 `pyproject.toml`/版本号；`packages/**/*.md` 不触发 CI（memory: docs-pr-no-ci-admin-merge）。
+- 三文件 body（内容结构块 + 类型段目录 + 选标题原则 + 自检）**逐字一致**；各文件其余本平台特性不动（审阅交互 question vs AskUserQuestion、`--kb` 默认、交叉引用 `/skill:jfox-common` vs `/jfox:manage` vs `/skill:jfox-manage`）。
+- 「写作规范（遵循 clear-reports 段落写作法）」5 条与「嵌入 wiki links」段**逐字保留不动**。
+- 不改 `jfox-promote`（调研确认它不引用本模板）。
+- 不回填历史永久笔记（仅对新沉淀生效）。
+- commit 前 `git branch --show-current` 守卫（memory: concurrent-git-branch-hijack），须在 `issue-375-permanent-note-template` 分支。
+
+## File Structure
+
+| 文件 | 改动 | 责任 |
+|---|---|---|
+| `skills-recommend/pi/jfox-session-to-permanent/SKILL.md` | Step 3 替换 + 插入 | pi 平台 skill |
+| `packages/cc-plugin/skills/session-to-permanent/SKILL.md` | 同上（逐字一致） | cc-plugin skill |
+| `packages/kimi-plugin/skills/jfox-session-to-permanent/SKILL.md` | 同上（逐字一致） | kimi-plugin skill |
+
+三文件改的是**同一段**，替换文字完全相同——这是设计要求，不是省事。
+
+---
+
+## Canonical 替换文本（三个 Task 共用，逐字一致）
+
+**要被替换的旧文本**（三个文件里逐字相同，grep 锚点 `**内容结构**（事实 → Why → How to apply）：`）：
+
+````
+**内容结构**（事实 → Why → How to apply）：
+
+```markdown
+<一句话核心事实。开门见山，把这条笔记最重要的结论放第一句。>
+
+## Why
+<这个事实为什么成立、背景是什么。每段只讲一个子主题，段首给概要句。>
+
+## How to apply
+<什么场景下用、具体怎么操作。结合示例或命令。>
+```
+````
+
+**替换为下面这段新文本**（三个文件逐字一致，注意内层是 3 个反引号的 code block）：
+
+````
+**内容结构**（稳定核 + 类型段 + 易变细节）：
+
+```markdown
+<一句话结论。这条笔记最稳定、最值得未来记住的那句话，开门见山放第一句。>
+
+## 为什么（背景与依据）
+<这条知识回答的是什么问题；成立的前提/约束/假设。
+ 若是决策类：写当时的背景、选它的主要原因、以及认真考虑过但没选的替代方案——依据很大程度上在于"被丢弃的选项"。
+ 没东西可写就整段省略，别硬凑。>
+
+## <类型段，选 0–1 个，标题写实>
+<按笔记内容从下方"类型段目录"选一个标题，或整段省略。>
+
+## 怎么用
+<什么场景下用、具体步骤或命令。结合示例或命令。>
+```
+
+> **易变细节处理（写作指导，不是每条笔记的固定段）**：路径、版本号、端口、文件位置归到「## 怎么用」，它们是易变的"实现决策"，核（结论 + 为什么）不写具体值、保持常青。只有当「## 怎么用」里确实出现了这类易变值时，才在该段末尾加一句具体的核对提醒（如「端口以 docker-compose.yml 为准」）；没出现就不加——固定的模板话重复进每条笔记会掩盖该条的重点。
+
+**选标题的原则**：标题要写实、具体——写这条笔记实际在讲的主题，不套抽象类别名；一段一个主题，不用「A与B」复合标题（如不要「运行速度与耗电量」，要拆成两段或选其一）。
+
+**类型段目录**：按笔记内容选 0–1 个标题；方法/调试类通常省略，直接并进「## 怎么用」。
+
+| 笔记内容 | 类型段标题 | 这一段写什么 |
+|---|---|---|
+| 机制 / 原理 | `## 它怎么工作` | 系统/工具的运作机制、各部分如何配合 |
+| 现状快照 | `## 当前现状` | 脚本/文件/端口/配置的当前位置与状态 |
+| 自动化链路 | `## 链路与组件` | 多组件串联的链路与各组件职责 |
+| 纯概念 | `## 概念` | 可复用的概念、原理、术语解释 |
+| 方法 / 调试 | （省略） | 直接写进「## 怎么用」 |
+
+> **链路类的提醒**：一条笔记若在画多个组件的关系，本质是「迷你 structure note」——组件多了应考虑拆成一个 MOC（见 #376）+ 各组件独立笔记，而不是把所有组件塞进一条 fat note。
+
+**自检**：把「## 怎么用」整段遮住，剩下的「结论 + 为什么 + 类型段」是否还独立成立、还有价值？是→分层成功；否→核里写进了易变细节，把具体路径/版本挪到「## 怎么用」。
+````
+
+> 替换范围说明：旧文本从 `**内容结构**（事实 → Why → How to apply）：` 起，到内层 code block 结束的 ` ``` ` 止（不含其后的空行和「写作规范」段）。新文本替换到「**自检**：……挪到「## 怎么用」。」止。替换后紧跟原有的「**写作规范（遵循 clear-reports 段落写作法）**」段——**写作规范段及其后内容一律不动**。
+
+---
+
+### Task 1: 替换 pi 平台 skill 的 Step 3 模板
+
+**Files:**
+- Modify: `skills-recommend/pi/jfox-session-to-permanent/SKILL.md`（Step 3「内容结构」块，约 L103–113）
+
+**Interfaces:** 本任务建立 canonical 替换结果，Task 2/3 必须与其逐字一致（Task 4 diff 验证）。
+
+- [ ] **Step 1: 守卫 + 定位旧块**
+
+```bash
+cd /home/elling/git-repo/github/jfox
+git branch --show-current   # 必须: issue-375-permanent-note-template
+grep -n "内容结构" skills-recommend/pi/jfox-session-to-permanent/SKILL.md
+```
+Expected: 命中 `**内容结构**（事实 → Why → How to apply）：`
+
+- [ ] **Step 2: 替换**
+
+用 Edit 工具，把本 plan「Canonical 替换文本」里的**旧文本**整段替换为**新文本**。`old_string` = 旧文本（从 `**内容结构**（事实 → Why → How to apply）：` 到内层 ``` 止），`new_string` = 新文本（到「**自检**」段止）。
+
+- [ ] **Step 3: 验证替换正确**
+
+```bash
+# 旧锚点 0 命中
+grep -c "事实 → Why → How to apply\|## How to apply" skills-recommend/pi/jfox-session-to-permanent/SKILL.md
+# 新锚点命中
+grep -c "稳定核 + 类型段 + 易变细节\|类型段目录\|选标题的原则\|自检：把" skills-recommend/pi/jfox-session-to-permanent/SKILL.md
+# 写作规范段仍在
+grep -c "写作规范（遵循 clear-reports" skills-recommend/pi/jfox-session-to-permanent/SKILL.md
+```
+Expected: 第 1 条 = 0；第 2 条 ≥ 4；第 3 条 = 1。
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add skills-recommend/pi/jfox-session-to-permanent/SKILL.md
+git commit -m "refactor(skill): session-to-permanent 模板改三层结构（pi, #375）"
+```
+
+---
+
+### Task 2: 替换 cc-plugin skill 的 Step 3 模板（与 pi 逐字一致）
+
+**Files:**
+- Modify: `packages/cc-plugin/skills/session-to-permanent/SKILL.md`（Step 3，约 L97–107）
+
+**Interfaces:** 替换文字必须与 Task 1 结果逐字一致。
+
+- [ ] **Step 1: 守卫 + 定位**
+
+```bash
+git branch --show-current   # issue-375-permanent-note-template
+grep -n "内容结构" packages/cc-plugin/skills/session-to-permanent/SKILL.md
+```
+Expected: 命中旧锚点 `**内容结构**（事实 → Why → How to apply）：`
+
+- [ ] **Step 2: 替换**
+
+同 Task 1 Step 2——用本 plan「Canonical 替换文本」的旧/新文本做 Edit（同一份文字）。
+
+- [ ] **Step 3: 验证**
+
+```bash
+grep -c "事实 → Why → How to apply\|## How to apply" packages/cc-plugin/skills/session-to-permanent/SKILL.md   # =0
+grep -c "稳定核 + 类型段 + 易变细节\|类型段目录\|选标题的原则\|自检：把" packages/cc-plugin/skills/session-to-permanent/SKILL.md  # ≥4
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/cc-plugin/skills/session-to-permanent/SKILL.md
+git commit -m "refactor(skill): session-to-permanent 模板改三层结构（cc, #375）"
+```
+
+---
+
+### Task 3: 替换 kimi-plugin skill 的 Step 3 模板（与 pi 逐字一致）
+
+**Files:**
+- Modify: `packages/kimi-plugin/skills/jfox-session-to-permanent/SKILL.md`（Step 3，约 L97–107）
+
+**Interfaces:** 替换文字必须与 Task 1 结果逐字一致。
+
+- [ ] **Step 1: 守卫 + 定位**
+
+```bash
+git branch --show-current   # issue-375-permanent-note-template
+grep -n "内容结构" packages/kimi-plugin/skills/jfox-session-to-permanent/SKILL.md
+```
+Expected: 命中旧锚点。
+
+- [ ] **Step 2: 替换**
+
+同 Task 1 Step 2。
+
+- [ ] **Step 3: 验证**
+
+```bash
+grep -c "事实 → Why → How to apply\|## How to apply" packages/kimi-plugin/skills/jfox-session-to-permanent/SKILL.md   # =0
+grep -c "稳定核 + 类型段 + 易变细节\|类型段目录\|选标题的原则\|自检：把" packages/kimi-plugin/skills/jfox-session-to-permanent/SKILL.md  # ≥4
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/kimi-plugin/skills/jfox-session-to-permanent/SKILL.md
+git commit -m "refactor(skill): session-to-permanent 模板改三层结构（kimi, #375）"
+```
+
+---
+
+### Task 4: 三方 diff + 全局验证
+
+**Files:** 无新改动；只读验证，必要时回修。
+
+**Interfaces:** 消费 Task 1/2/3 的产物。
+
+- [ ] **Step 1: 三方 body 逐字一致性**
+
+抽取三文件「内容结构 → 写作规范」之间的区段，两两 diff：
+
+```bash
+cd /home/elling/git-repo/github/jfox
+A=skills-recommend/pi/jfox-session-to-permanent/SKILL.md
+B=packages/cc-plugin/skills/session-to-permanent/SKILL.md
+C=packages/kimi-plugin/skills/jfox-session-to-permanent/SKILL.md
+extract() { sed -n '/\*\*内容结构\*\*/,/\*\*写作规范（遵循/p' "$1"; }
+diff <(extract "$A") <(extract "$B")
+diff <(extract "$A") <(extract "$C")
+```
+Expected: 两个 diff 均**无输出**（区段逐字一致）。若有差异，回对应 Task 修正到一致。
+
+- [ ] **Step 2: 全局旧锚点 0 命中（排除 worktrees）**
+
+```bash
+grep -rn "事实 → Why → How to apply" --include="*.md" . | grep -v "/.worktrees/"
+grep -rn "## How to apply" --include="*.md" . | grep -v "/.worktrees/"
+```
+Expected: 均无命中（session-to-permanent 三处已改；其它文件本就没有）。
+
+- [ ] **Step 3: 写作规范 5 条 + wiki links 段仍在（抽查一处即可，三处一致）**
+
+```bash
+grep -c "写作规范（遵循 clear-reports" skills-recommend/pi/jfox-session-to-permanent/SKILL.md  # =1
+grep -c "嵌入 wiki links" skills-recommend/pi/jfox-session-to-permanent/SKILL.md               # =1
+grep -c "先给结论，再展开" skills-recommend/pi/jfox-session-to-permanent/SKILL.md              # =1（5条之1）
+```
+
+- [ ] **Step 4: jfox-promote 未受影响**
+
+```bash
+grep -rn "稳定核 + 类型段\|类型段目录" packages/cc-plugin/skills/promote packages/kimi-plugin/skills/jfox-promote skills-recommend/pi/jfox-promote 2>/dev/null
+```
+Expected: 无命中（promote 没被碰）。
+
+- [ ] **Step 5: 若 Step 1–4 全过则无需 commit；若有回修则 commit 修正**
+
+```bash
+git status   # 应 clean（除非有回修）
+```
+
+---
+
+## Self-Review（writing-plans 自检，已完成）
+
+- **Spec coverage**：spec §3.1（新模板块）→ Task 1/2/3 Step 2；§3.2（类型段目录 + 选标题原则）→ 同一 canonical 新文本；§3.3（自检）→ 同一；§3.4（写作规范/wiki 不动）→ Task 1/3/4 Step 3 验证；§4（三平台一致 + 各保留特性）→ Task 4 Step 1 diff + Global Constraints；§6 验收→ Task 4。无遗漏。
+- **Placeholder scan**：canonical 文本是最终稿，无 TBD/TODO。grep 期望值都给了具体数字。
+- **Type consistency**：三个文件 grep 锚点字符串统一（`稳定核 + 类型段 + 易变细节` / `类型段目录` / `选标题的原则` / `自检：把`），Task 4 diff 兜底。
+- **docs-only 适配**：原 TDD 模板的「写失败测试/跑测试」对纯 markdown 不适用，替换为「grep 锚点 + diff」机械验证，每步都给了可执行命令与期望值。

jfox_cli-1.7.2/docs/superpowers/plans/2026-08-12-noteindex-frontmatter-limit-drop.md

@@ -0,0 +1,49 @@
+# Plan: NoteIndex frontmatter 行数上限静默丢弃（#380）
+
+对应 spec：`specs/2026-08-12-noteindex-frontmatter-limit-drop-design.md`
+
+## Task 1 — 回归测试（先红）
+
+文件：`tests/unit/test_note_index.py`，新增 class `TestNoteIndexLargeFrontmatter`（或并入
+`TestNoteIndexInvalidFiles`）。
+
+- fixture/inline：构造一条 frontmatter 行数 > 旧上限 200（取 245：240 条 backlinks + 5 行其它字段）
+  的 permanent 笔记，写入 `cfg.notes_dir/permanent/`。
+- 断言：
+  - `find_by_title(...)` 命中（非 None），`id` 正确 —— 直接回归 #380。
+  - `_parse_frontmatter_only(filepath)` 非 None。
+- 另加一条：超限（构造远超 50000 行的病理 frontmatter 不现实，改为直接 monkeypatch
+  `_MAX_FRONTMATTER_LINES` 到小值如 5，构造 >5 行 frontmatter，断言返回 None 且
+  `caplog` 捕获到 `WARNING` 级日志、日志含文件名 —— 锁定「超限不再静默」）。
+
+验证：`uv run pytest tests/unit/test_note_index.py -v`（新测试红，旧测试绿）。
+
+## Task 2 — 修复（转绿）
+
+文件：`jfox/note_index.py`
+
+- `_MAX_FRONTMATTER_LINES = 200` → `50000`，注释更新为「防御性 guard：frontmatter 不闭合时
+  避免读全文件；远超现实 backlinks 上限，正常笔记读到闭合 `---` 即 break，无性能影响」。
+- 超限分支：`return None` 前加 `logger.warning(f"frontmatter 超过 {_MAX_FRONTMATTER_LINES} 行上限，
+  已跳过：{filepath}")`。
+
+验证：Task 1 测试转绿；`uv run pytest tests/unit/test_note_index.py -v` 全绿。
+
+## Task 3 — 全量校验 + lint
+
+- `uv run pytest tests/unit/ -q`（快速单测全过，不触发 embedding/slow）。
+- `uv run ruff check jfox/note_index.py tests/unit/test_note_index.py`。
+- `uv run black --check jfox/note_index.py tests/unit/test_note_index.py`
+  （用 `uv run --with black==26.3.1 black --check ...` 若缺，见 memory `run-black-not-just-ruff`）。
+
+## Task 4 — 提交 + CR + PR
+
+- `git add` 按文件 stage（note_index.py、test_note_index.py、spec、plan）。
+- 本地 CR（`feature-dev:code-reviewer` 或 `/code-review`，深度自定）。
+- push + `gh pr create --head`，PR body 含根因/修复/测试/复现链接，关 #380。
+- 打 `zima:needs-review`，走 zima-pr-monitor babysit。
+
+## 非任务（确认不做）
+
+- index verify 接入 NoteIndex invalid files。
+- backlinks 截断策略。