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

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

@@ -2,6 +2,34 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [1.16.2] - 2026-09-25
+
+### Fixes
+
+- **note**: 加载笔记钉住真实磁盘路径，update_note 规范化写——消除同 ID 双文件 (#549) (#553)
+
+[1.16.2]: https://github.com/zhuxixi/jfox/compare/v1.16.1...v1.16.2
+
+## [1.16.1] - 2026-09-24
+
+### Fixes
+
+- **note_index**: 剥离改单遍合并正则——反引号包 HTML 注释不再吞后续 wiki link (#548) (#550)
+
+### Changes
+
+- **claude.md**: batch refresh — fold in 6 pending auto/claude-md PRs (#520/#524/#527/#532/#540/#545) (#546)
+
+[1.16.1]: https://github.com/zhuxixi/jfox/compare/v1.16.0...v1.16.1
+
+## [Unreleased]
+
+### Fixes
+
+- **note**: 加载的笔记钉住真实磁盘路径——文件名与当前字段分家时，补 backlink / rebuild --backlinks / MOC 成员回填不再写出同 ID 双文件，`show`/`delete` 也能正确读写该笔记；`update_note` 改为显式规范化写并在成功后重钉路径 (#549)
+
+- **note_index**: 剥离改单遍合并正则——反引号包 HTML 注释不再吞后续 wiki link (#548) (#550)
+
 ## [1.16.0] - 2026-09-23
 
 ### Features

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

@@ -62,7 +62,7 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 |--------|------|
 | `cli.py` | All CLI commands (~4200 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` |
+| `global_config.py` | `GlobalConfigManager` managing `~/.zk_config.json`；损坏恢复契约（#481/#526）：`from_dict` 各级非 dict 守卫回默认，文件级加载失败先字节级备份 `.corrupt-*` 快照再恢复默认，备份失败则不落盘覆盖原文件 |
 | `kb_manager.py` | Knowledge base lifecycle (create, rename, remove) |
 | `formatters.py` | Output formats: JSON, CSV, YAML, Table, Paths |
 | `git_extractor.py` | Git 仓库数据提取器（ingest 功能） |
@@ -74,7 +74,7 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 | `add_dedup.py` | `jfox add` permanent 落库前双通道防重（#383）：标题通道（非 archived 同标题、大小写不敏感、不限类型）+ 正文余弦 ≥0.95 通道（复用顶层 `jfox/dedup.py`，`daemon_only=True` 绝不回退本地模型加载、仅 daemon 在跑时启用）；闸门自身故障一律放行，非路障 |
 | `search_engine.py` | `HybridSearchEngine` with `SearchMode` enum, RRF fusion |
 | `bm25_index.py` | BM25 keyword search index；写路径 filelock + 原子写 + `write_version` 乐观并发控制，多进程并发写安全（#391/#396） |
-| `embedding_backend.py` | Sentence-transformers embedding backend（支持 daemon 代理）；CPU 默认模型 `BAAI/bge-small-zh-v1.5`（512 维，#442），本地模型目录未命中时先走 ModelDownloader 下载链再兜底加载（#374） |
+| `embedding_backend.py` | Sentence-transformers embedding backend（支持 daemon 代理）；CPU 默认模型 `BAAI/bge-small-zh-v1.5`（512 维，#442），本地模型目录未命中时先走 ModelDownloader 下载链再兜底加载（#374）；#519 起该包拆入 `[embed]` extra 可选——`is_embedding_service_available()` 探测（本地 `find_spec` 模块级缓存 + daemon 实时检查），缺失时 `load()` 抛 `EmbedDependencyMissingError`（message 含安装提示），`reset_embed_availability_cache()` 为测试后门 |
 | `daemon/` | Embedding 模型 HTTP 守护进程 (`server.py`/`client.py`/`process.py`)，`jfox daemon start/stop/status` |
 | `embedding_migration.py` | 全 KB 向量维度不匹配检测（#442）：daemon start/restart 时比对各 KB Chroma 集合维度与 daemon 服务维度，发现旧模型建库则交互式逐 KB 提示 rebuild，单 KB 失败不阻断其余 |
 | `fragment/` | 碎片子系统（采集已退役，#498）：detector 分类与 `ingest_event` 采集链删除，仅留 store SQLite(WAL) 与历史回溯 CLI `jfox fragments list/show`；旧 `session_fragments` 表保留供 prompts `backfill` 回填 |
@@ -116,6 +116,8 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 - **Comments/docs**: Chinese (中文)
 - **README**: 英文 baseline（#461 起重写），改 README 保持英文；其余项目文档/注释仍中文
 - **Adding a CLI command**: Add `@app.command()` in `cli.py`, implement `_xxx_impl()` helper, add `--kb` and `--format json` support（`--json` 简写等价于 `--format json`，全 CLI 统一约定，moc create/update 曾漏补，#425）；命令面有任何增删改还须补 `docs/cli-descriptions.yaml` 英文描述并跑 `uv run python scripts/generate_docs.py` 重新生成 `docs/cli-reference.md`，否则 CI lint drift gate 挂（#474/#476）
+- **`--json` 输出 schema 合同**（#502/#531）: 全部命令 JSON 输出顶层必有 `success: bool`，失败必有非空 `error` + exit 1，裸数组包成 `{success, items}`（如 prompts/backup list）。权威 schema 参考 `docs/json-schemas.md`（改 JSON 字段须同步更新），合同由 `tests/test_json_schema_contract.py` 锁定
+- **Wiki-link 解析收敛**: edit/add/rebuild 三路径统一走 `cli.py` 的 `resolve_wiki_links()`（剥离 code fence/inline code/HTML 注释 → 三级匹配解析 → 自链过滤 → 去重，找不到的进 unresolved），改链接解析规则只改这一处（#511/#530）
 - **Adding a search mode**: Add to `SearchMode` enum in `search_engine.py`, implement in `HybridSearchEngine.search()`, update CLI `--mode` help text
 - **Adding a daemon-scheduled loop**: 镜像 `auto_summary/`（与 backup 同构）——`loop.py`（`_tick_once` + async `X_loop(stop_event)`）+ `daemon/server.py` lifespan 内 `_maybe_start/stop_X` 接线 + `GlobalConfigManager` opt-in（每 tick `reload()` 即时生效）；任何写类 loop 的 `_tick_once` 开头须 check `BackupCoordinator.is_running()` 跳过写，避免备份期间 ChromaDB 并发写
 - **Modifying data models**: Update `Note` class in `models.py`, update `to_markdown()`/`from_markdown()`, consider backward compat
@@ -123,14 +125,17 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 - **笔记生命周期事件**: `note.py` 只广播 `post_delete`/`post_archive`/`post_promote`/`post_reject`（`register_lifecycle_hook` + `_dispatch`），绝不 import 特性层；特性层订阅做副作用（如 `dedup_lifecycle.py` 同步 dedup 表、`prompts/lifecycle.py` 同步 judgment）。`register` 在 `jfox/__init__.py` 接线，任何 `import jfox.*` 即订阅就位，库式调用方零成本
 - **源笔记清理统一 archive**: skill 整理/提炼后清理源笔记用 `jfox archive`（软删除，`jfox unarchive` 可回滚误判），不用 `delete --force` 硬删（#436）
 - **`jfox add` permanent 防重**（#383/#483）: 默认开启，标题或正文余弦 ≥0.95 命中即拒绝创建（exit 1，JSON 输出 `skipped: "duplicate"`），`--force` 跳过（迁移/回填用）；开关与阈值在 `~/.zk_config.json` 的 `note_add` 节（`NoteAddConfig`）；embedding 通道仅 daemon 在跑时生效，落库后回灌 dedup 表供后续 add 查重
+- **`--content-file` 输入规范化**（#541/#542）: `jfox add`/`edit` 的 `--content-file`（文件路径与 stdin `-` 同一语义）统一剥 BOM/frontmatter 后**无条件剥首个 H1**（与读盘侧 `from_markdown` 对称——标题走 `--title`，内容文件里别再带 H1 行）；连续双 H1 或剥后为空会报错；要让正文以 `#` 行开头须用 `--content` 直传（不做任何剥离）
 
 ## Test Infrastructure
 
 - **Fixtures** (`conftest.py`): `temp_kb` (temp KB path), `cli` (ZKCLI instance), `cli_fast` (ZKCLI with mocked embeddings), `generator` (NoteGenerator), `mock_embedding_backend`
 - **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）
+- **全局配置隔离**: 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）；`JFOX_FRAGMENTS_DB`/`JFOX_BACKUP_ROOT`/`JFOX_CLAUDE_PROJECTS_DIR` 同理，防子进程合同测试读写真实 fragments.db、`~/.jfox-backup` 与 `~/.claude/projects`（#531）
+- **测试生成笔记标题须全局唯一**: #483 add 防重闸门会拒绝重复标题，曾致 nightly flaky（#523）；`tests/utils/note_generator.py` 已做无放回抽取 + 跨调用标题去重，自写测试生成器同理
 - **Model caching**: Session-level model cache in conftest.py to avoid 30-60s reload per test
 - **Test markers**: `slow`, `performance`, `integration`, `embedding`, `workflow`, `bulk`, `no_embed`（#519：需在无 sentence-transformers 环境执行的降级测试，CI Fast 天然满足）
+- **无 embed 环境测试三坑**（#519 实测）：① 测 post-gate 流程（daemon start/restart、ingest、index rebuild 后半段）的单测须 monkeypatch `is_local_embed_available` 为 True，否则无 embed 环境 gate short-circuit、目标流程 0 调用；② mock VectorStore 的单测须设 `mock_vs.last_embed_warning = None`（同 #383 dim-warning 先例），否则残留告警断言失败；③ 用例/类命名避开 "search"/"semantic"/"embedding"/"vector"/"query"/"suggest" 子串——conftest collection 过滤先 nodeid lower() 再子串匹配，命中即整组 deselect（类名也算，`TestSearchModes` 因含 "search" 被整类 slow）；pin 零语义场景用 autouse fixture 设 `JFOX_DAEMON_PROCESS=1`（隔离开发机真实 daemon），勿模块级 `os.environ`（collection 阶段写入毒化同进程其他测试文件）
 - **Run single-process** to avoid ChromaDB/model loading conflicts
 - **Test directory reorganization mostly complete**:
   - `tests/unit/` — Pure logic unit tests (25 files)
@@ -143,7 +148,7 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 
 Four jobs in `.github/workflows/integration-test.yml`:
 
-- **Fast** (PR/push): `not embedding and not slow`, Python 3.11, Ubuntu + Windows
+- **Fast** (PR/push): `not embedding and not slow`, Python 3.11, Ubuntu + Windows；另跑 pi-plugin node 测试（setup-node 22，#462）
 - **Core** (main branch): Core workflow tests with real embeddings, Python 3.10 + 3.12
 - **Full** (manual): All tests, all OS, all Python versions
 - **Coverage** (after fast): Runs coverage on fast tests, uploads HTML/XML artifacts
@@ -184,9 +189,10 @@ JFox ships as a Claude Code plugin. Two-tier structure:
 - `packages/cc-plugin/.claude-plugin/plugin.json` — plugin source metadata
 - `packages/cc-plugin/skills/` — 9 skills: `search`, `ingest`, `manage`, `organize`, `promote`, `session-summary`, `session-to-permanent`, `using-jfox`, `bookshelf`
 
-**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.7.5.
+**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.7.6.
 **Skill rename history**: `kb` → `manage` (v0.2.0) — "manage" is the canonical KB lifecycle + CRUD skill.
 **Non-Claude-Code platforms**: `skills-recommend/`（`pi/` + `kimi-cli/`）是 pi / Kimi CLI 适配版 SKILL.md 集（如 `pi/jfox-moc`，#419）——CLI 语义或命令面变更时须与 cc-plugin skills 同步更新。
+**pi prompt 采集扩展**（#462）：`packages/pi-plugin/extensions/jfox-prompt-capture.ts`（TypeScript 单文件、零 npm 依赖、node ≥ 22.6 直跑）监听 pi input 事件→合成 CC 兼容事件→原子写 spool 再尽力 POST daemon `/api/prompt`，与 cc-plugin hook 同链路、复用 `jfox prompts drain` 兜底；`user_prompts.source` 由 `prompts/service.py` 透传顶层 source（pi → `pi-coding-agent`，CC 默认 `claude-code`）；本地测试 `node --experimental-strip-types packages/pi-plugin/test/run-tests.ts`
 **Skill 多副本同步**: skill 文案/行为改动须同步所有镜像副本——`packages/cc-plugin/skills/`、`packages/kimi-plugin/skills/`、`skills-recommend/kimi-cli/`、`skills-recommend/pi/`，只改一处会各端行为分叉（#440 踩过同步模式）
 
 ## Branch Rules
@@ -204,3 +210,4 @@ JFox ships as a Claude Code plugin. Two-tier structure:
 - `HybridSearchEngine` 构造时仅对自取的 BM25 单例做一次 stale 检查并 reload（磁盘被其他进程写过则刷新快照）；显式传入的 `bm25_index` 实例归调用方所有、不隐式 reload——长驻进程须自行周期重建引擎或调 `check_stale_and_reload`（#391）
 - `jfox index verify` 以 frontmatter 真实 `id` 对账向量库，文件名格式无关——legacy `14位时间戳-6位微秒-slug` 文件名不再误报 orphan；frontmatter 缺 id/解析失败的文件计入 `unreadable_files` 不参与对账，同 id 多文件报 `duplicate_ids`（#407/#408）
 - CPU 默认 embedding 模型已从 `all-MiniLM-L6-v2`（384 维）切到 `BAAI/bge-small-zh-v1.5`（512 维，#442）：旧 KB 向量库维度不匹配时 search/add 显式告警不静默失败（`vector_store.last_dimension_warning`），按提示 `jfox index rebuild` 重建该 KB；CI 模型缓存 key 也随模型名（#453）
+- 语义组件缺失降级（#519）：无本地 sentence-transformers 且无 daemon 时，写路径降级继续——`save_note`/`update_note` typed catch `EmbedDependencyMissingError`（文件+BM25 照写、跳过向量索引），`update_note` 改走 `add_or_update_note` 守卫原语（服务不可用不删既有行），`index rebuild` 降级 BM25-only 不重置向量库，add/edit JSON 出 `semantic_index_warning`；读路径显式拒绝——search/query/suggest-links 的 semantic/hybrid 模式 exit 1 + 安装提示；`jfox status` JSON 含 `embedding` 探测节（local_package/daemon_running/service_available）

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

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

jfox_cli-1.16.2/docs/superpowers/plans/2026-09-24-adjacent-backticks-swallow-wiki-links.md

@@ -0,0 +1,224 @@
+# Issue #548：相邻空反引号对吞 wiki link 修复 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:** 把 `_strip_wiki_link_exclusions` 的三次顺序 `re.sub` 改为单次遍历合并正则，修复「反引号包 HTML 注释」塌缩出相邻空反引号对、吞掉后续 wiki link 的 bug（issue #548）。
+
+**Architecture:** 纯函数内部实现替换（签名不变），模块级预编译 `_EXCLUSION_RE`，alternation 顺序 fenced > HTML 注释 > inline code 即优先级。三个调用方（`resolve_wiki_links` / `find_notes_referencing_title` / `note.py` 链接提取）自动受益，无需改动。spec 见 `docs/superpowers/specs/2026-09-24-adjacent-backticks-swallow-wiki-links-design.md`。
+
+**Tech Stack:** Python 3.10+，`re`（标准库），pytest。
+
+## Global Constraints
+
+- Work from: `/home/elling/git-repo/github/jfox/.pi/worktrees/issue-548-adjacent-backticks-swallow-wiki-links`（所有路径以它为根；禁止碰主 checkout 的 main）
+- 注释用中文；commit message 用英文 Conventional Commits（`fix:`/`test:`/`docs:`）
+- 验收矩阵（spec）：A1/A2=unit，A3=integration，U1=用户实测（post-merge）
+- 测试命名避开子串 `search`/`semantic`/`embedding`/`vector`/`query`/`suggest`（conftest collection 过滤会整组 deselect）
+- 测试生成笔记标题须全局唯一（#483 防重闸门）：本 plan 所有标题带 `548` 前缀
+- 范围纪律：不碰 #458（`_normalize_wiki_link_title`）、#470（edit 去重）、`redirect.py`、`graph.py`
+- 改完跑 `uv run ruff check jfox/note_index.py tests/` 与 `uv run black --check jfox/note_index.py tests/unit/test_wiki_link_resolution.py tests/integration/test_backlinks.py`
+- `git add` 按文件 stage，禁止 `git add -A`
+
+---
+
+### Task 1: 合并正则修复 + unit 回归用例①–⑥（A1/A2）
+
+**Files:**
+
+- Modify: `jfox/note_index.py`（`_WIKI_LINK_RE` 定义之后加 `_EXCLUSION_RE`；替换 `_strip_wiki_link_exclusions` 函数体，约 42–53 行）
+- Test: `tests/unit/test_wiki_link_resolution.py`（`TestStripWikiLinkExclusions` 类追加 6 个用例）
+
+**Interfaces:**
+
+- Consumes: 无（首任务）
+- Produces: `_strip_wiki_link_exclusions(text: str) -> str`（签名不变，行为修复）；模块级 `_EXCLUSION_RE`。Task 2 的集成测试经 CLI 间接消费此行为。
+
+- [ ] **Step 1: 写失败测试（用例①–⑥）**
+
+在 `tests/unit/test_wiki_link_resolution.py` 的 `TestStripWikiLinkExclusions` 类内、`test_plain_text_untouched` 之后追加：
+
+```python
+    # ---- #548 回归：反引号包 HTML 注释塌缩成相邻空反引号对 ----
+
+    def test_backtick_wrapped_html_comment_keeps_following_wiki_link(self):
+        """①/A1：反引号包注释删除后空反引号对不吞后续 wiki link"""
+        text = "页首标记 `<!-- print p.X -->` 说明\n\n见 [[笔记A]] 和 `code`"
+        out = _strip_wiki_link_exclusions(text)
+        assert "[[笔记A]]" in out
+
+    def test_double_backtick_comment_pair_bracketing_wiki_link(self):
+        """③/A1：两个「反引号包注释」夹住的链接存活（双塌缩形态）"""
+        text = "`<!-- a -->` [[笔记A]] `<!-- b -->`"
+        out = _strip_wiki_link_exclusions(text)
+        assert "[[笔记A]]" in out
+
+    def test_backtick_comment_without_trailing_backtick(self):
+        """②/A2 对照：触发形态但后文无更多反引号（修复前后均正确，防过修）"""
+        text = "页首标记 `<!-- print p.X -->` 见 [[笔记A]]"
+        out = _strip_wiki_link_exclusions(text)
+        assert "[[笔记A]]" in out
+
+    def test_fenced_block_with_comment_inside_priority_unchanged(self):
+        """④/A2 对照：fenced 优先级不变——块内链接不提取、块外存活"""
+        text = "```\n<!-- c --> [[不应解析]]\n```\n\n见 [[笔记A]]"
+        out = _strip_wiki_link_exclusions(text)
+        assert "[[不应解析]]" not in out
+        assert "[[笔记A]]" in out
+
+    def test_inline_code_link_still_not_extracted(self):
+        """⑤/A2 对照：inline code 内的链接仍不提取"""
+        text = "见 `[[不应解析]]` 和 [[笔记A]]"
+        out = _strip_wiki_link_exclusions(text)
+        assert "[[不应解析]]" not in out
+        assert "[[笔记A]]" in out
+
+    def test_html_comment_containing_backticks_removed_whole(self):
+        """⑥/A2 对照：注释内含反引号——注释整体剔除、注释外链接存活"""
+        text = "<!-- `code` --> 见 [[笔记A]]"
+        out = _strip_wiki_link_exclusions(text)
+        assert "`code`" not in out
+        assert "[[笔记A]]" in out
+```
+
+- [ ] **Step 2: 跑测试确认按预期失败**
+
+Run: `uv run pytest tests/unit/test_wiki_link_resolution.py -k "backtick or fenced_block_with_comment or inline_code_link or html_comment_containing" -v`
+Expected: **仅 ① `test_backtick_wrapped_html_comment_keeps_following_wiki_link` 与 ③ `test_double_backtick_comment_pair_bracketing_wiki_link` FAIL**（断言 `[[笔记A]]` 不在输出），②④⑤⑥ PASS。若失败面大于此，先停下核对环境。
+
+- [ ] **Step 3: 实现——合并正则**
+
+3a. 在 `jfox/note_index.py` 模块级 `_WIKI_LINK_RE = re.compile(r"\[\[(.*?)\]\]")` 之后空一行插入：
+
+```python
+# 单次遍历剔除：alternation 顺序即优先级（fenced > HTML 注释 > inline code），
+# 保证 `<!-- -->` 这类「反引号包注释」在首个反引号处被 inline 分支原子吃掉，
+# 不产生相邻空反引号对。禁止拆回多次顺序 re.sub——顺序剔除会让已删除区域
+# 造出新结构（#548：注释删除→空反引号对→inline 跨界吞链接）。
+_EXCLUSION_RE = re.compile(
+    r"```[\s\S]*?```"      # fenced code block
+    r"|<!--[\s\S]*?-->"    # HTML 注释
+    r"|`[^`]+`",           # inline code（反引号 span）
+)
+```
+
+3b. 把 `_strip_wiki_link_exclusions` 整个函数（含 docstring 与三行 `re.sub`）替换为：
+
+```python
+def _strip_wiki_link_exclusions(text: str) -> str:
+    """移除不应参与 wiki-link 匹配的 Markdown 区域（fenced code block、HTML 注释、inline code）。
+
+    单次遍历（见 _EXCLUSION_RE 注释）；轻量级处理，不保证解析所有 Markdown 边界情况。
+    """
+    return _EXCLUSION_RE.sub("", text)
+```
+
+- [ ] **Step 4: 跑测试确认全过**
+
+Run: `uv run pytest tests/unit/test_wiki_link_resolution.py -v`
+Expected: 全部 PASS（既有 3 个用例 + 新增 6 个）。
+
+- [ ] **Step 5: lint**
+
+Run: `uv run ruff check jfox/note_index.py tests/unit/test_wiki_link_resolution.py && uv run black --check jfox/note_index.py tests/unit/test_wiki_link_resolution.py`
+Expected: 无告警；black 若报格式，跑 `uv run black jfox/note_index.py tests/unit/test_wiki_link_resolution.py` 后复检。
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add jfox/note_index.py tests/unit/test_wiki_link_resolution.py
+git commit -m "fix(note_index): merge exclusion regexes into single pass to stop adjacent-backtick link loss (#548)"
+```
+
+---
+
+### Task 2: 集成用例——add 落库后 links/backlink 不丢（A3）
+
+**Files:**
+
+- Modify: `tests/integration/test_backlinks.py`（文件末尾追加测试类）
+- Test: 即本文件
+
+**Interfaces:**
+
+- Consumes: Task 1 修复后的 `_strip_wiki_link_exclusions` 行为（经 `jfox add` → `resolve_wiki_links` 间接消费）；`ZKCLI.add(content, title=, note_type=)`、`ZKCLI.refs(note_id=)`、`ZKCLI._run("show", <id>)`（JSON 输出）。
+- Produces: 无（叶子任务）。
+
+- [ ] **Step 1: 写集成测试**
+
+在 `tests/integration/test_backlinks.py` 末尾追加（该文件已有 `pytestmark = [pytest.mark.integration, pytest.mark.slow]` 与 `cli` fixture 用法）：
+
+```python
+class TestWikiLinkExclusionOnAdd:
+    """#548：反引号包 HTML 注释不吞落库链接（add → backlink/links 全链路）"""
+
+    def test_add_keeps_link_after_backtick_wrapped_html_comment(self, cli):
+        """A3：add 含触发内容的笔记后，目标收到 backlink、源笔记 links 含目标 id"""
+        # 1. 创建目标笔记
+        target = cli.add("Target content", title="548 Target Note", note_type="permanent")
+        assert target.success
+        target_id = target.data["note"]["id"]
+
+        # 2. 创建源笔记：反引号包 HTML 注释 + 紧随的 wiki link + 后文反引码（触发形态）
+        content = (
+            "页首标记 `<!-- print p.X -->` 说明\n\n"
+            "见 [[548 Target Note]] 和 `code`"
+        )
+        source = cli.add(content, title="548 Source Note", note_type="permanent")
+        assert source.success
+        source_id = source.data["note"]["id"]
+
+        # 3. 目标笔记必须收到反向链接（issue 症状：backlinks 缺失）
+        refs_result = cli.refs(note_id=target_id)
+        assert refs_result.success
+        backlink_ids = [link["id"] for link in refs_result.data.get("backward_links", [])]
+        assert source_id in backlink_ids, f"backlink 缺失：{backlink_ids}"
+
+        # 4. 源笔记存储的 links 含目标 id（issue 复现口径：show --json 的 links）
+        show_result = cli._run("show", source_id)
+        assert show_result.success
+        assert target_id in (show_result.json or {}).get("links", [])
+```
+
+- [ ] **Step 2: 跑集成测试确认通过**
+
+Run: `uv run pytest tests/integration/test_backlinks.py::TestWikiLinkExclusionOnAdd -v`
+Expected: PASS。（若在 Task 1 之前先跑本步骤应 FAIL——实现顺序上 Task 1 已合入本 worktree 分支，故直接 PASS；如需复核 bug 形态，可 `git stash` Task 1 的 note_index.py 改动后重跑，应 FAIL。）
+
+- [ ] **Step 3: 全量回归本 issue 触及的测试面**
+
+Run: `uv run pytest tests/unit/test_wiki_link_resolution.py tests/integration/test_backlinks.py -v`
+Expected: 全部 PASS。
+
+- [ ] **Step 4: lint**
+
+Run: `uv run ruff check tests/integration/test_backlinks.py && uv run black --check tests/integration/test_backlinks.py`
+Expected: 无告警。
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add tests/integration/test_backlinks.py
+git commit -m "test(backlinks): add #548 regression — link survives backtick-wrapped HTML comment"
+```
+
+---
+
+## Post-merge：U1 手动验证（不在本 plan 的代码任务内）
+
+修复合入 main 后，由用户对 issue 中命中的那条笔记执行（spec U1）：
+
+```bash
+jfox edit <受影响笔记id> --content-file <该笔记原文件>   # 重存触发 links 重算
+jfox show <受影响笔记id> --json | jq '.links | length'   # 应恢复为 3
+```
+
+通过标准：links 条数恢复、缺失的那条 backlink 重新出现。完成后在 issue #548 评论核对结果并关闭 issue。
+
+## 验收对账表
+
+| 验收 ID | 承载 | 验证命令 |
+|---------|------|----------|
+| A1 | Task 1 用例①③ + 实现 | `uv run pytest tests/unit/test_wiki_link_resolution.py -k backtick` |
+| A2 | Task 1 用例②④⑤⑥ + 既有用例 | `uv run pytest tests/unit/test_wiki_link_resolution.py` |
+| A3 | Task 2 集成用例 | `uv run pytest tests/integration/test_backlinks.py::TestWikiLinkExclusionOnAdd` |
+| U1 | Post-merge 手动步骤 | 见上节，用户执行后在 issue 留痕 |

jfox_cli-1.16.2/docs/superpowers/plans/2026-09-24-issue-549-twin-files.md

@@ -0,0 +1,305 @@
+# #549 同 ID 双文件修复 实现计划
+
+> **For agentic workers:** Steps use checkbox (`- [ ]`) syntax to track progress. Follow instructions exactly.
+
+**Spec:** `docs/superpowers/specs/2026-09-24-issue-549-twin-files-design.md`（commit 47b236c）
+
+**Work from:** `/home/elling/git-repo/github/jfox/.pi/worktrees/issue-549-stale-name-twin-files`（所有路径以此为根；禁止碰主 checkout）
+
+**技术摘要：** 路径语义两分法——`from_markdown` 钉住真实路径（`save_note` 就地写）+ `update_note` 写盘目标改用 `expected_filepath`（规范化写 + 成功后重钉 pin）。
+
+## 验收归属（spec 矩阵 → 任务）
+
+| 验收 ID | 归属 |
+|---------|------|
+| A1/A2（路径纯函数 + 钉路径） | Task 1 |
+| A3（update_note 自愈 + 重钉 pin） | Task 1 |
+| A9（护栏：改名/移目录保持绿） | Task 1 |
+| A4–A8（CLI 症状层） | Task 2 |
+| CHANGELOG/注释交付物 | Task 3 |
+| U1（真实库受控演练） | 合并后单独人工项，非代码任务 |
+
+## 前置事实（实现者必读，违反即返工）
+
+1. **原子性约束**：`models.py` 的钉路径与 `note.py` 的 `update_note` 调整**必须同任务同 commit 落地**。中间态（只钉路径）会让 `tests/unit/test_edit.py:72-82`（改标题→改名）与 `:373-390`（改 type→跨目录）挂掉（E2b 已实证）。
+2. **契约边界**：改 title/topic/type 的意图只走 `update_note`；`save_note` 是就地写。不要给 `save_note` 加任何「找旧文件/改名」逻辑——本修复不靠它。
+3. **改动面**：只允许碰 `jfox/models.py`、`jfox/note.py`、两个测试文件、`CHANGELOG.md`。不碰 `moc/`、`redirect.py`、其余 save_note 站点（钉路径后它们自动受益）。
+4. **测试命名**：文件/用例名避开子串 `search|semantic|embedding|vector|query|suggest`；用例标题全局唯一（#483 闸门）。本计划的文件名已满足：`test_note_path_rules.py`、`test_stale_name_single_file.py`。
+5. **夹具手法**：发散名 = 只 rename 文件（保留 id 前缀），不改 frontmatter——`cli_fast` 每条命令独立子进程，索引按盘重建，发散笔记可被正常发现/解析。
+6. **#483 之后 add permanent 有 dedup 闸门**：测试标题彼此差异要大，别用近似标题。
+
+---
+
+## Task 1: 路径语义核心（models.py + note.py + A1/A2/A3/A9）
+
+**Files:**
+
+- Create: `tests/unit/test_note_path_rules.py`
+- Create: `tests/integration/test_stale_name_single_file.py`（先只放 A3 两个用例）
+- Modify: `jfox/models.py`
+- Modify: `jfox/note.py`
+
+- [ ] **Step 1: 写失败测试**
+
+`tests/unit/test_note_path_rules.py`（A1/A2，纯函数层，无需 KB 写入）：
+
+```python
+class TestExpectedFilepath:
+    def test_permanent_uses_title_slug(self)                    # A1：expected == config.notes_dir/"permanent"/filename
+    def test_session_uses_topic(self)                           # A1
+    def test_session_without_topic_falls_back_to_title(self)    # A1
+    def test_fleeting_uses_dash_form(self)                      # A1：{id[:8]}-{id[8:]}.md
+    def test_expected_filepath_ignores_pin(self)                # A1：set_filepath 后 expected 不变、filepath 变
+
+class TestFromMarkdownPin:
+    def test_with_filepath_pins_it(self)                        # A2：note.filepath == 传入路径
+    def test_without_filepath_stays_unpinned(self)              # A2：note.filepath == expected_filepath
+```
+
+`tests/integration/test_stale_name_single_file.py`（A3，先行两个用例；发散名 helper 共用）：
+
+```python
+def _diverge(filepath: str) -> Path:
+    """只 rename 文件制造发散名（保留 id 前缀），模拟外部改标题未同步改名"""
+    p = Path(filepath)
+    d = p.with_name(f"{p.stem}-diverged.md")
+    p.rename(d)
+    return d
+
+
+def _files_for(dir_path: Path, nid: str) -> list:
+    return sorted(dir_path.glob(f"{nid}*.md"))
+
+
+class TestUpdateSelfHeal:
+    def test_edit_title_on_diverged_name_canonicalizes(self, cli_fast):
+        """A3：发散名笔记经 edit --title 后规范化为规则名，全程单文件"""
+        # add permanent → 从 add 的 JSON 取 note.filepath → _diverge →
+        # cli_fast.edit(id, title="全新标题X") →
+        # 断言 _files_for 单文件、文件名含新标题 slug、旧发散名不存在
+
+    def test_second_save_after_update_no_resurrect(self, temp_kb_registered):
+        """A3：同对象 update_note 后再 save_note，不复活旧路径（重钉 pin 契约）"""
+        # 复用 test_delete_backlink_cleanup.py 的 temp_kb_registered + use_kb 模式：
+        # load → note.update_note（改标题）→ 对同对象 note.save_note →
+        # 断言旧路径文件未被重新创建，且规则名文件唯一
+```
+
+（`temp_kb_registered` 参照 `tests/unit/test_delete_backlink_cleanup.py` 的用法；若该 fixture 名不匹配，用 conftest 中已有的等价临时 KB 上下文。）
+
+- [ ] **Step 2: 运行确认失败**
+
+```bash
+uv run pytest tests/unit/test_note_path_rules.py tests/integration/test_stale_name_single_file.py -x -q
+```
+
+预期：`expected_filepath` 不存在（AttributeError）/ 钉路径未生效 → FAIL。只确认 RED，不修。
+
+- [ ] **Step 3: 实现 `jfox/models.py`**
+
+① 新增 property（放 `filepath` 旁，注释为交付物）：
+
+```python
+    @property
+    def expected_filepath(self) -> Path:
+        """按当前字段现算的规则路径（type 目录 + filename），不看 _filepath pin。
+
+        #549 两分法的另一半：update_note（规范化写）以本属性为写盘目标；
+        filepath 在笔记从磁盘加载时被钉住为真实路径（就地写）。
+        用 note_obj.filepath 代替本属性的已知后果：钉路径后改名判据
+        `old != note.filepath` 恒假，edit --title / 改 type 不再改名移动
+        （tests/unit/test_edit.py:72-82、:373-390 必挂）。
+        """
+        from .config import config
+
+        return config.notes_dir / self.type.value / self.filename
+```
+
+② `from_markdown`：把 `return cls(...)` 改为先存变量再钉路径（注释为交付物）：
+
+```python
+        note = cls(
+            ...  # 现有参数不动
+        )
+        # #549：钉住加载来源的真实磁盘路径。此后 note.filepath 返回真实路径，
+        # save_note（就地写）写回原文件——文件名与当前字段分家时也不会在规则名上
+        # 另写同 id 双文件。需要「按当前字段重新定址」的操作（改标题/改 type）
+        # 请走 note.update_note，其写盘目标用 expected_filepath。
+        if filepath is not None:
+            note._filepath = Path(filepath)
+        return note
+```
+
+③ `filepath` property 的 docstring 补一句「加载的笔记此处返回真实磁盘路径；规则路径请用 expected_filepath」。
+
+- [ ] **Step 4: 实现 `jfox/note.py`**
+
+① `update_note` 写盘段（原 `_atomic_write(note_obj.filepath, ...)` 处）：
+
+```python
+        # 规范化写（#549）：目标路径按当前字段现算，不看加载 pin。
+        target = note_obj.expected_filepath
+        _atomic_write(target, note_obj.to_markdown())
+
+        if old_filepath != target and old_filepath.exists():
+            old_filepath.unlink()
+            logger.info(f"Renamed note file: {old_filepath} -> {target}")
+
+        # #549：写盘成功后把 pin 重钉到刚写入的路径——否则同一对象随后的
+        # save_note（就地写）会按陈旧 pin 写回旧路径、复活同 id 双文件。
+        note_obj.set_filepath(target)
+```
+
+② `save_note` docstring 补契约边界（交付物）：
+
+```
+    注意（#549）：写盘目标是 note.filepath——对从磁盘加载的笔记即「就地写回
+    加载路径」；就地写不保证文件名随字段变化。改 title/topic/type 的意图请用
+    update_note（规范化写：按当前字段现算目标并删除旧文件）。
+```
+
+- [ ] **Step 5: 运行确认通过**
+
+```bash
+uv run pytest tests/unit/test_note_path_rules.py tests/integration/test_stale_name_single_file.py -q
+```
+
+预期全绿。
+
+- [ ] **Step 6: 护栏回归（A9）**
+
+```bash
+uv run pytest tests/unit/test_edit.py -q
+```
+
+预期全绿（改标题改名、改 type 跨目录不受影响）。
+
+- [ ] **Step 7: 快速回归**
+
+```bash
+uv run pytest tests/unit -m "not embedding and not slow" -q
+```
+
+- [ ] **Step 8: commit**
+
+```bash
+git add jfox/models.py jfox/note.py tests/unit/test_note_path_rules.py tests/integration/test_stale_name_single_file.py
+git commit -m "fix(note): 加载笔记钉住真实路径，update_note 规范化写+重钉 pin——消除同 ID 双文件（#549 A1-A3/A9）"
+```
+
+---
+
+## Task 2: CLI 症状层集成测试（A4–A8）
+
+**Files:**
+
+- Modify: `tests/integration/test_stale_name_single_file.py`
+
+- [ ] **Step 1: 补五个测试类（TDD：先写先跑，应在 Task 1 的实现上直接转绿——若红说明 Task 1 有漏）**
+
+```python
+class TestAddBackfill:
+    def test_add_link_to_diverged_target_keeps_single_file(self, cli_fast):
+        """A4：add 链接发散名目标 → 单文件 + backlinks 落真实文件"""
+        # A = add permanent（标题「回填目标甲」）→ _diverge →
+        # B = add「链向 [[回填目标甲]]」→
+        # 断言 _files_for(A) 单文件（发散名那份）、A 文件 backlinks 含 B.id
+
+class TestEditBackfill:
+    def test_edit_add_link_diverged_target_keeps_single_file(self, cli_fast):
+        """A5：edit 新增链接 → 单文件 + backlinks 落位"""
+    def test_edit_remove_link_diverged_target_keeps_single_file(self, cli_fast):
+        """A5：edit 移除链接 → backlinks 移除 + 仍单文件"""
+
+class TestRebuildBacklinks:
+    def test_rebuild_touches_diverged_note_in_place(self, cli_fast):
+        """A6：rebuild --backlinks 触及发散名笔记时单文件"""
+        # 造 links/backlinks 必变化：直接改发散文件 frontmatter，给 backlinks 加一个假 id
+        # cli_fast.index_rebuild(backlinks=True) →
+        # 断言单文件、backlinks 被重算（假 id 消失）
+
+class TestShowDelete:
+    def test_show_reads_diverged_note(self, cli_fast):
+        """A7：show 发散名笔记 success=true（此前报 Errno 2）"""
+    def test_delete_removes_real_file(self, cli_fast):
+        """A7：delete --force 删真实文件（无入链前置）→ glob 为空"""
+
+class TestMocMemberBackfill:
+    def test_moc_backfill_diverged_member_keeps_single_file(self, temp_kb_registered):
+        """A8：moc 成员回填（python 级 backfill_moc_backlinks）→ 单文件"""
+        # 构造 structure Note（或 CLI add --type structure）+ 发散名成员
+        # 调 jfox.moc.generate.backfill_moc_backlinks(moc_note, [member_id], cfg)
+        # 断言单文件 + backlinks 含 moc.id
+```
+
+- [ ] **Step 2: 运行该文件全量**
+
+```bash
+uv run pytest tests/integration/test_stale_name_single_file.py -q
+```
+
+- [ ] **Step 3: 相关既有集成测试回归**
+
+```bash
+uv run pytest tests/integration/test_links_edit_add.py tests/integration/test_index_rebuild_backlinks.py tests/integration/test_edit_roundtrip.py tests/unit/test_delete_backlink_cleanup.py tests/unit/test_note_promote.py -q
+```
+
+预期全绿（同族回填/晋升链路未受影响）。
+
+- [ ] **Step 4: commit**
+
+```bash
+git add tests/integration/test_stale_name_single_file.py
+git commit -m "test(links): 发散名笔记 CLI 症状层集成测试——add/edit/rebuild/show+delete/moc 均单文件（#549 A4-A8）"
+```
+
+---
+
+## Task 3: CHANGELOG + 注释交付物复核 + 全量回归
+
+**Files:**
+
+- Modify: `CHANGELOG.md`
+
+- [ ] **Step 1: `## [Unreleased]` 的 `### Fixed` 下加条目**
+
+```markdown
+- links: 加载的笔记钉住真实磁盘路径——文件名与当前字段分家时，补 backlink / rebuild --backlinks / MOC 成员回填不再写出同 ID 双文件，`show`/`delete` 也能正确读写该笔记；`update_note` 改为显式规范化写并在成功后重钉路径（#549）
+```
+
+- [ ] **Step 2: 注释交付物复核（对照 spec §7）**：`filepath` property、`from_markdown`、`update_note` 三处注释齐（两分法、E2b 后果、重钉原因）；不齐则补。
+
+- [ ] **Step 3: markdownlint**
+
+```bash
+npx --yes markdownlint-cli2@0.23.2 "CHANGELOG.md"
+```
+
+- [ ] **Step 4: 全量快速回归（本地 CR 前置）**
+
+```bash
+uv run pytest tests/ -m "not embedding and not slow" -q
+```
+
+- [ ] **Step 5: commit**
+
+```bash
+git add CHANGELOG.md
+git commit -m "docs(changelog): #549 同 ID 双文件修复条目"
+```
+
+---
+
+## 完成标准
+
+- A1–A9 全部有对应测试且全绿；U1 留待合并后用户点头执行（spec §5）。
+- 快速套件 `tests/ -m "not embedding and not slow"` 全绿。
+- 分支只含 4 个 commit（spec / 核心修复 / 症状层测试 / changelog），主 checkout 零改动。
+
+---
+
+## 执行偏差记录（终审补记）
+
+1. **测试文件名更名**：spec 中的 `tests/unit/test_note_path_semantics.py` 实际落地为 `test_note_path_rules.py`——#483 命名约束要求避开子串 `semantic`（spec 已同步修订）。
+2. **分支为 6 个 commit 而非 4 个**：Task 1 的 lint fix wave（ruff/black）amend 进核心 commit；第 5 个 commit `a5ed229` 为终审挂账的注释债清理（`redirect.py`、`moc/cli.py`、`test_moc_member_commands.py` 纯注释/docstring——reviewer 指出「from_markdown 不回填 `_filepath`」在修复后已成假命题），第 6 个为本修订。前置事实 3 的「不碰 moc/、redirect.py」原指行为代码，注释债清理经 reviewer 建议纳入。
+3. **plan 的用例骨架微调**：`temp_kb_registered` 实为 `tests/utils/temp_kb.py` 的 context manager（非 fixture），A3-2/A8 按计划备注改用 `use_kb(kb_name)` + python 级 note API 模式。