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

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

@@ -2,6 +2,24 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [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_index**: 剥离改单遍合并正则——反引号包 HTML 注释不再吞后续 wiki link (#548) (#550)
+
 ## [1.16.0] - 2026-09-23
 
 ### Features

{jfox_cli-1.16.0 → jfox_cli-1.16.1}/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.1}/PKG-INFO

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

jfox_cli-1.16.1/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.1/docs/superpowers/specs/2026-09-24-adjacent-backticks-swallow-wiki-links-design.md

@@ -0,0 +1,119 @@
+# Issue #548 Spec：修复 `_strip_wiki_link_exclusions` 吞掉后续 wiki link
+
+> 日期：2026-09-24 · 类型：bug · issue：#548 · 调研存档：`~/.claude/github-issue-driven/zhuxixi/jfox/issue-548/research/`
+> 修订：2026-09-24 v2 —— 按 spec review 发现 R1–R6 修订（见文末修订记录）
+
+## 一句话设计
+
+把 `_strip_wiki_link_exclusions`（`jfox/note_index.py:42`）的**三次顺序 `re.sub`** 改成**单次遍历的合并正则（alternation）**，让三类剔除区域在同一次扫描里原子匹配，已删除区域不再参与后续匹配。
+
+## 根因（systematic-debugging Phase 1-3 已完成）
+
+现状顺序剔除：
+
+1. `re.sub(r"```[\s\S]*?```", "", text)` —— fenced code block
+2. `re.sub(r"<!--[\s\S]*?-->", "", text)` —— HTML 注释
+3. `re.sub(r"`[^`]+`", "", text)` —— inline code
+
+第 2 步删掉被反引号包住的 HTML 注释（`` `<!-- -->` ``）后，两个反引号塌缩成**相邻空对** `` `` ``；第 3 步`` `[^`]+` `` 在第一个反引号处匹配失败（下一字符是反引号），转而从**第二个**反引号起匹配，一路吃到文中再下一个反引号，把中间整段（含 wiki link）当行内代码删除。
+
+已复现：输入 `页首标记 \`<!-- print p.X -->\` 说明\n\n见 [[笔记A]] 和 \`code\``，当前提取链接`[]`，修法提取`['笔记A']`。
+
+## 设计
+
+```python
+# note_index.py 模块级
+
+# 单次遍历剔除：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）
+)
+
+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)
+```
+
+**为什么有效**：单次遍历在每个位置按 alternation 顺序（fenced → HTML → inline）尝试。在 `` `<!-- -->` `` 的第一个反引号处，fenced 与 HTML 分支都因当前字符是反引号而失败，inline 分支把整段当行内代码**原子吃掉**——根本不产生空反引号对，后续文字不受影响。alternation 顺序同时保留了原代码「fenced 先于 inline」的意图（原注释「须最后处理，避免吃掉 fenced 边界」）。
+
+**为什么不选备选方案**（issue 里也提了）：保留顺序剔除、第 2 步后折叠相邻空反引号对（`re.sub(r"``+", "", text)`）。它只堵住这一种塌缩形态，后续新增剔除规则时同类交接问题会复发；合并正则更彻底，且行为与现状在所有非 bug 用例上一致（已用对照用例验证，见「回归用例清单」）。
+
+**注释是交付物的一部分（review R4）**：`_EXCLUSION_RE` 上方的注释解释了 alternation 顺序即优先级、以及为什么禁止拆回顺序剔除。没有这段注释，后续维护者很可能按直觉「简化」回多次 `re.sub`，复发同类 bug。
+
+## 影响面（review R3 修订：准确版）
+
+**fenced+HTML+inline 三合一剔除的实现只有 `note_index.py:42` 一处**，三个调用方都 import 它：
+
+| 调用方 | 用途 |
+|--------|------|
+| `cli.py:373` | `resolve_wiki_links`（#511/#530 收敛的 add/edit/rebuild 三路径，含 frontmatter links 写入） |
+| `note_index.py:262` | `find_notes_referencing_title`（backlinks 反查） |
+| `note.py:507` | 笔记链接提取 |
+
+**两处相邻实现，不受本 bug 影响、也不在本次改动范围**（review 时 grep 发现，修正调研阶段「全仓唯一实现」的过强表述——那只对函数成立，不对剔除逻辑成立）：
+
+- `redirect.py:33-34,125-126`：自己的 `_FENCED_CODE_RE`/`_HTML_COMMENT_RE`，顺序 **blank（占位替换，非删除）**，且无 inline-code 步骤——不产生相邻塌缩，不受 #548 影响，无需改动。其注释「与 note_index 扫描口径保持一致」本就不完全成立（redirect 不剔 inline code），改完 note_index 后该口径差依旧存在，属独立话题。
+- `graph.py:97`：第三 pass 对 **raw content** 提取链接、完全不剥离——口径与 note_index 相反，code fence 里的链接在图谱中会计成边。#548 触发的笔记在 graph 里其实**有**边，issue 里「图谱少边」的说法只对 backlinks/stored links 成立。
+
+## 非目标
+
+- **不捎带 #458**（含 `#` 标题被 `_normalize_wiki_link_title` 截断）、**#470**（edit 去重 + 同名歧义）——不同函数的独立 bug。
+- **不处理 redirect.py / graph.py 的口径分歧**（见影响面；如需统一扫描口径，另开 issue）。
+- **不引入完整 Markdown 解析器**——函数 docstring 声明的轻量口径不变，合并正则仍在该哲学内。
+- **不做批量存量重存工具**——存量补救走 U1 的人工重存路径（见验收矩阵），不为此加 CLI 命令。
+
+## 可测性拆分设计
+
+`_strip_wiki_link_exclusions` 本来就是**纯函数**（`text -> str`，无副作用、无外部依赖），无需拆分。测试边界：
+
+- **unit（A1/A2，主证明）**：直接对纯函数断言输出，无 mock、无 fixture，秒级。
+- **integration（A3，症状层）**：经 `ZKCLI` 走 `add` 落库 → `show --json` 读 `links`，证明用户可观察症状（落库后 links 缺失、且不进 Unresolved 警告）消失。接线本身（#511）已有测试，此处只钉症状。
+- **用户实测（U1，存量补救）**：`edit` 仅在 `content is not None` 时重算 links（`cli.py:1997-1999`），已污染的 frontmatter links **不会自愈**，需对受影响笔记重存一次。
+
+## 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | 反引号包 HTML 注释后，紧随的 wiki link 被保留 | 自动化验证（unit） | `uv run pytest tests/unit/test_wiki_link_resolution.py -k strip` | 「回归用例清单」① 触发用例通过 |
+| A2 | 既有剥离行为不回归 | 自动化验证（unit） | `uv run pytest tests/unit/test_wiki_link_resolution.py` | 该文件既有用例 + 清单②–⑥对照用例全部通过 |
+| A3 | 端到端：`add` 含触发内容的笔记后，`show --json` 的 `links` 含目标 | 自动化验证（integration） | 新增集成测试（ZKCLI add → show，复用既有 fixtures） | `links` 包含目标笔记 id；触发内容里的链接不静默丢失 |
+| U1 | 存量受污染笔记的 links 恢复 | 用户实测 | 修复合入后，对 issue 中命中的那条笔记执行 `jfox edit <id> --content-file <原文件>`（或 `--content` 原文重存），再 `jfox show <id> --json` 核对 | `links` 条数恢复（该笔记应为 3），缺失的那条 backlink 重新出现 |
+
+A3 为必做（review R1：验收矩阵与改动清单不允许「可选」矛盾）。U1 是操作项：修复本身无法自动定位哪条笔记被污染（依赖 issue 记录），故归用户实测。
+
+## 回归用例清单（A1/A2 落到 `TestStripWikiLinkExclusions`）
+
+| # | 用例 | 期望（修复后） | 防什么 |
+|---|------|----------------|--------|
+| ① | 触发用例：`页首标记 \`<!-- p -->\` 说明\n\n见 [[笔记A]] 和 \`code\`` | `[[笔记A]]` 存活 | #548 本体（A1） |
+| ② | 触发变体·后文无更多反引号 | `[[笔记A]]` 存活（修复前也存活） | 防过修/行为漂移 |
+| ③ | 两个「反引号包注释」夹住一个链接 | 链接存活 | 双塌缩形态（顺序版此形态也丢链） |
+| ④ | fenced block 内含 HTML 注释与链接 | 块内链接不提取，块外链接提取 | fenced 优先级不变 |
+| ⑤ | inline code 内的 `[[...]]` | 不提取 | inline 剥离不变 |
+| ⑥ | HTML 注释内含反引号 | 注释整体剔除、注释外链接存活 | 分支优先级不变 |
+
+复现脚本已验证 ①–⑥ 在修复版下全部正确、在现状版下仅 ①③ 有差异（即仅 bug 形态被修）。
+
+## 改动文件
+
+- `jfox/note_index.py`：`_strip_wiki_link_exclusions` 改为合并正则；新增模块级 `_EXCLUSION_RE`（含解释性注释，见设计节）。
+- `tests/unit/test_wiki_link_resolution.py`：`TestStripWikiLinkExclusions` 增用例①–⑥（A1/A2）。
+- `tests/integration/`（A3 必做）：新增或扩展一个 add→show 集成用例。
+
+## 修订记录
+
+- v2（2026-09-24，spec review 后）：
+  - R1：A3 从「（可选）」改为必做，矩阵与改动清单一致。
+  - R2：新增 U1 存量补救（`edit` 重存触发 links 重算）。
+  - R3：影响面改写——「唯一实现」收窄为「三合一剔除唯一实现」，补 redirect.py（顺序 blank，不受影响）与 graph.py（不剥离，口径相反）两处事实。
+  - R4：设计节明确注释为交付物，给出注释内容。
+  - R5：钉死回归用例清单①–⑥。
+  - R6：非目标补三条（redirect/graph 口径分歧、不引 Markdown 解析器、不做批量重存工具）。

{jfox_cli-1.16.0 → jfox_cli-1.16.1}/jfox/__init__.py

@@ -1,6 +1,6 @@
 """JFox - Zettelkasten 知识管理工具"""
 
-__version__ = "1.16.0"
+__version__ = "1.16.1"
 __author__ = "User"
 __email__ = "user@example.com"
 

{jfox_cli-1.16.0 → jfox_cli-1.16.1}/jfox/note_index.py

@@ -18,6 +18,18 @@ logger = logging.getLogger(__name__)
 # 维基链接正则：匹配 [[标题]] 语法（非贪婪，不支持跨行）
 _WIKI_LINK_RE = re.compile(r"\[\[(.*?)\]\]")
 
+# 单次遍历剔除：alternation 顺序即优先级（fenced > HTML 注释 > inline code），
+# 保证 `<!-- -->` 这类「反引号包注释」在首个反引号处被 inline 分支原子吃掉，
+# 不产生相邻空反引号对。禁止拆回多次顺序 re.sub——顺序剔除会让已删除区域
+# 造出新结构（#548：注释删除→空反引号对→inline 跨界吞链接）。
+# 注意：当前三分支在同一扫描位置互斥（fenced 的 ``` 处 inline 必不匹配、HTML 以 `<` 起始），
+# 故今日顺序不改变输出；声明的顺序是防御性文档，约束未来可能在同一位置竞争的分支（如四反引号 fence 变体）。
+_EXCLUSION_RE = re.compile(
+    r"```[\s\S]*?```"  # fenced code block
+    r"|<!--[\s\S]*?-->"  # HTML 注释
+    r"|`[^`]+`",  # inline code（反引号 span）
+)
+
 
 def extract_wiki_links_from_text(text: str) -> List[str]:
     """从文本中提取 [[...]] 格式的维基链接。
@@ -42,15 +54,9 @@ def _normalize_wiki_link_title(link_text: str) -> str:
 def _strip_wiki_link_exclusions(text: str) -> str:
     """移除不应参与 wiki-link 匹配的 Markdown 区域（fenced code block、HTML 注释、inline code）。
 
-    这是轻量级处理，覆盖最常见的误匹配场景；不保证解析所有 Markdown 边界情况。
+    单次遍历（见 _EXCLUSION_RE 注释）；轻量级处理，不保证解析所有 Markdown 边界情况。
     """
-    # fenced code block（支持可选语言标识）
-    text = re.sub(r"```[\s\S]*?```", "", text)
-    # HTML 注释
-    text = re.sub(r"<!--[\s\S]*?-->", "", text)
-    # inline code（反引号 span；须最后处理，避免吃掉 fenced 边界）
-    text = re.sub(r"`[^`]+`", "", text)
-    return text
+    return _EXCLUSION_RE.sub("", text)
 
 
 @dataclass

{jfox_cli-1.16.0 → jfox_cli-1.16.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "jfox-cli"
-version = "1.16.0"
+version = "1.16.1"
 description = "JFox - Zettelkasten 知识管理 CLI 工具"
 readme = "README.md"
 license = {text = "MIT"}

{jfox_cli-1.16.0 → jfox_cli-1.16.1}/tests/integration/test_backlinks.py

@@ -136,3 +136,31 @@ class TestBacklinksAutoMaintenance:
 
         # 验证 A 没有来自 C 的直接反向链接（只有间接通过 B）
         assert id_c not in backlink_ids_a
+
+
+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", [])

{jfox_cli-1.16.0 → jfox_cli-1.16.1}/tests/unit/test_wiki_link_resolution.py

@@ -62,6 +62,56 @@ class TestStripWikiLinkExclusions:
         out = _strip_wiki_link_exclusions("普通 [[链接]] 内容")
         assert "[[链接]]" in out
 
+    # ---- #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 内含 HTML 注释与链接——块内不提取、块外存活（顺序由⑦钉住）"""
+        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
+
+    def test_fenced_block_with_inner_backtick_and_link_pins_ordering(self):
+        """⑦/A2 对照：fence 内含反引号与链接——fenced 分支须原子吃掉整块，
+        块内链接不得因 fence 被行内反引号破坏而泄漏；块外链接存活。
+        该用例区分 alternation 顺序（inline 先于 fenced 时会失败）。"""
+        text = "```\ncode `t` [[不应解析]]\n```\n\n见 [[笔记A]] 和 `d`"
+        out = _strip_wiki_link_exclusions(text)
+        assert "[[不应解析]]" not in out
+        assert "[[笔记A]]" in out
+
 
 class TestResolveWikiLinks:
     """resolve_wiki_links 统一解析规则（issue #511）"""

{jfox_cli-1.16.0 → jfox_cli-1.16.1}/uv.lock

@@ -867,7 +867,7 @@ wheels = [
 
 [[package]]
 name = "jfox-cli"
-version = "1.16.0"
+version = "1.16.1"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },