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

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

@@ -2,6 +2,14 @@
 
 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
@@ -18,6 +26,8 @@ All notable changes to jfox-cli will be documented in this file.
 
 ### 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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jfox-cli
-Version: 1.16.1
+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-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 模式。

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

@@ -0,0 +1,121 @@
+# #549 spec：加载笔记按真实磁盘路径读写（消除同 ID 双文件）
+
+- 状态：**confirmed v2（用户已批准并实现完成；整分支终审 Ready to merge: Yes）**
+- v2 变更（review 修订）：① U1 重设计为受控演练（v1 的「incident 复刻」在笔记已规范化后验证不了任何东西）；② 补 `update_note` 成功后重钉 pin 契约；③ 补 `save_note` 就地写边界（改 title/topic/type 须走 update_note）；④ A7 补无入链前置；⑤ A3 定为 integration；⑥ 防回归注释列为交付物。
+- issue：zhuxixi/jfox#549
+- 调研依据：`research/root-cause-and-fix-verification.md`（含原型实验 E1–E3）
+
+## 1. 背景与现状
+
+一个 bug 类：**「笔记磁盘文件名 ≠ 按当前字段现算的规则名」时，jfox 的读写路径会指向错误位置**。写面产生同 ID 双文件，读/删面直接失败。
+
+- 触发预置条件：磁盘名 ≠ 规则派生名（外部改标题未同步改名 / legacy slug 漂移 / KB 迁移）。
+- 当前知识库实测：**0 条**处于触发态（issue 里的双文件已被清理，`index verify` duplicate_ids 为空）。真实库今天实弹命中过一条永久笔记（incident）。
+- 根因链（HEAD 核实）：`models.py` `filename` 三分支 → `from_markdown` 丢弃 filepath（`_filepath` 恒 None）→ `filepath` property 现算 → `save_note` 无旧文件比对。
+- 站点图（8 处，见调研文件 §4）：写面 4 处（`add` 回填、`edit` 回填、`rebuild --backlinks`、MOC 成员回填），读/删面 4 处（`show`、`delete`、MOC ghost 检查、`list --paths`）。
+- 站点图复核（v2，已逐个读码）：`prompts/judge.py:130`、`prompts/actions.py:252`、`auto_summary/runner.py:651`、`moc/generate.py:79` 四个 `save_note` 站点均构造全新对象（无加载路径），不属本类。
+- 仓库已有同类修复范式（#392 A2/A3 → #422）：delete/promote 的 target 清理用「`find_note_file` 真实路径 + 重读 fresh + `_atomic_write(actual_path)`」。
+
+## 2. 目标与非目标
+
+**目标（三个症状一次消掉）**
+
+1. 写面：对 stale 名笔记的任何写入**就地落在真实文件**，不再产生双文件。
+2. 读面：`show` 能读 stale 名笔记；`list --paths` 输出真实路径；MOC 成员检查不再误判 ghost。
+3. 删面：`delete` 能删掉 stale 名笔记的真实文件。
+4. 行为不变：`edit --title` 改名、改 type 跨目录移动等既有「规范化写」语义**原样保留**。
+
+**非目标**
+
+- 存量双文件修复（当前 0 条；如需另行处理）。
+- 对已有 stale 名笔记做批量规范化改名（无必要，就地读写即可；update_note 触碰时会自然自愈）。
+- 清理 `moc/cli.py:589`、`redirect.py:420` 的既有绕法（保留，注释已记录根因；本次不动以缩小 diff）。
+- 并发丢更新（#392 A3 范畴，本修复只解决路径正确性，不改变各站点的并发语义）。
+- legacy 文件名的自动迁移（#407/#408 已按读面对账解决）。
+
+## 3. 设计
+
+### 3.1 核心决策：路径语义两分法
+
+| 语义 | 方法 | 写盘目标 | 用途 |
+|------|------|----------|------|
+| **就地写** | `save_note` | `note.filepath`（加载时钉住的真实路径） | backlink 回填、rebuild、MOC 成员回填 |
+| **规范化写** | `update_note` | **规则派生路径**（按当前 type+title/topic 现算）+ 删旧文件 | `edit`、promote/archive/reject、MOC 保存 |
+
+### 3.2 决策表
+
+| 场景 | 期望行为 | 机制 |
+|------|----------|------|
+| `from_markdown(content, filepath)` | `filepath` 属性 === 传入的真实路径 | 构造后钉 `_filepath` |
+| `from_markdown(content)`（无 filepath） | `filepath` = 规则派生（现状） | pin 保持 None |
+| `save_note`（回填/重建） | 就地写真实文件，无新文件 | filepath 已钉 |
+| `update_note`（edit/promote/archive/moc save） | 写规则派生名；旧文件不存在则不动；不同则删旧 | 目标路径改用 `expected_filepath` |
+| stale 名笔记被 `update_note` 触碰 | 规范化为规则名（自愈，单文件） | 同上 |
+| `delete_note` | 删真实文件 | filepath 已钉（**无需改代码**） |
+| `show` / `list --paths` | 读/输出真实路径 | filepath 已钉（**无需改代码**） |
+| MOC 成员回填（`moc/generate.py:109/140`） | 就地写真实文件 | filepath 已钉（**无需改代码**） |
+| MOC ghost 检查（`moc/generate.py:51`） | stale 名成员不再误判 ghost | filepath 已钉（**无需改代码**） |
+
+### 3.3 组件契约
+
+- `Note.filename -> str`（既有，纯函数）：三分支规则名。
+- `Note.expected_filepath -> Path`（**新增，纯**）：`config.notes_dir / type.value / filename`——规则派生路径，永不看 pin。
+- `Note.filepath -> Path`（调整 docstring）：pin 优先，否则 `expected_filepath`。
+- `Note.from_markdown(content, filepath=None) -> Note`（调整）：filepath 非 None 时钉 `_filepath`（coerce 为 `Path`）。
+- `note.save_note(note, add_to_index=True) -> bool`（docstring 明确就地写语义，逻辑不变）。**契约边界**：就地写不保证文件名随字段变——**改 title/topic/type 的意图必须走 `update_note`**；对加载的笔记 `save_note` 只会写回加载路径。
+- `note.update_note(note_obj, add_to_index=True) -> bool`（调整）：写盘与改名判据改用 `note_obj.expected_filepath`；`find_note_file` 找旧路径与删旧逻辑不变；docstring 补「规范化写」语义。**写盘成功后必须把 `note_obj._filepath` 重钉为刚写入的路径**——否则同对象随后的 `save_note` 会按陈旧 pin 写回旧路径、复活双文件（v1 遗漏；原型用 finally 恢复旧 pin 掩盖了此点）。
+
+### 3.4 数据流
+
+```
+磁盘文件 --load_note--> from_markdown(content, path)
+                          └─ 钉 _filepath = path
+save_note(note)  →  _atomic_write(note.filepath)            # 就地
+update_note(note) → _atomic_write(note.expected_filepath)   # 规范化
+                    + unlink(find_note_file(id)) if 不同且存在
+```
+
+## 4. 可测性拆分设计
+
+- **纯函数层（unit，无需 IO/KB）**：`Note.expected_filepath` 三分支（fleeting / session(topic 优先，空 topic 回退 title) / 其余）；`Note.filepath` 的 pin/非 pin 两态；`from_markdown` 有/无 filepath 的钉与不钉。测试文件 `tests/unit/test_note_path_rules.py`。
+- **IO 层（integration，temp KB + mock embedding）**：CLI 级复现矩阵（下表 A4–A8）。夹具手法复用 `tests/unit/test_delete_backlink_cleanup.py:655-695`（`os.rename` 到 `{id}-renamed.md` 制造发散名），不新增抽象层。
+- **护栏（回归）**：既有 `tests/unit/test_edit.py:72-82`（改标题→改名）、`:373-390`（改 type→跨目录）必须保持绿。
+- 命名约束：测试文件/用例名避开子串 `search|semantic|embedding|vector|query|suggest`（`-m "not embedding"` 过滤口径）；用例标题全局唯一（#483 闸门）。
+- 副作用隔离：不改 `models.py` 的 IO 面（models 保持无 IO）；`note.py` 保持「IO + 路径语义」，不引入新模块。
+
+## 5. 验收矩阵
+
+| ID | 功能点 | 验收方式 | 具体验证 | 通过标准 |
+|----|--------|----------|----------|----------|
+| A1 | `expected_filepath`/`filename` 三分支与 pin 两态 | 自动化（unit） | `uv run pytest tests/unit/test_note_path_rules.py -m "not embedding"` | 全绿 |
+| A2 | `from_markdown` 钉/不钉 | 自动化（unit） | 同上 | 全绿 |
+| A3 | `update_note` 写规则名 + 删旧（stale 名自愈，单文件）+ 成功后重钉 pin | 自动化（integration） | `uv run pytest tests/integration/test_stale_name_single_file.py`（含自愈用例与「同对象 update 后再 save_note 不复活旧文件」用例） | 全绿，单文件 |
+| A4 | `add` 回填 stale 名笔记：无新文件、backlinks 落真实文件 | 自动化（integration） | `uv run pytest tests/integration/test_stale_name_single_file.py` | 断言 `glob(id*)` 唯一 + backlinks 含链接者 |
+| A5 | `edit` 增删链接（incident 场景） | 自动化（integration） | 同文件 | 单文件 + backlinks 正确 |
+| A6 | `index rebuild --backlinks` 触及 stale 名笔记 | 自动化（integration） | 同文件 | 单文件（逐条） |
+| A7 | `show` 可读 + `delete --force` 删真实文件 | 自动化（integration） | 同文件 | `success=true`；文件消失且无残留。**前置：被删笔记必须无入链**（否则触发引用保护 `1 note(s) reference this note`，E3c 实测） |
+| A8 | MOC 成员回填/ghost 检查 | 自动化（integration） | 同文件或 `tests/unit/test_moc_member_cli.py` 增补 | 单文件；成员被接受 |
+| A9 | 护栏：改标题改名 / 改 type 跨目录 | 自动化（integration） | `uv run pytest tests/unit/test_edit.py` | 全绿 |
+| U1 | 真实库受控演练（v2 重设计） | 用户实测（须用户点头后由 agent 用仓库版代码执行） | ① `jfox add` 在真实库建牺牲笔记 S；② `mv` 其文件制造发散名；③ `jfox add` 一条链接 S 的笔记触发回填；④ 断言 `glob(S.id + "*")` 单文件且 backlinks 落位；⑤ `jfox delete` 清理 S 与链接者；⑥ `jfox index verify --json` 的 `duplicate_ids` 为空 | 六步全部符合，现场无残留 |
+
+U1 说明（v2）：v1 的「incident 复刻」无效——incident 笔记已被清理成规范名，普通回填测不到 stale 路径；真实库当前 0 条 stale 笔记，要验证只能受控制造。上列六步全程可逆（牺牲笔记 + 完整清理），执行前需用户确认；若倾向零触碰，可降级为只读核验（仅⑥）。未执行前不允许宣称全部验收完成。
+
+## 6. 风险与缓解
+
+| 风险 | 缓解 |
+|------|------|
+| 钉路径让 `update_note` 改名失效（E2b 已实证） | 本 spec 的 A3/A9 覆盖：update_note 改 `expected_filepath` 后必须同时过 stale 自愈与新改名两测 |
+| MOC 标题编辑后文件随 update_note 改名（行为变化） | 现库 0 条 stale MOC，且属规范化收敛；A8 覆盖成员侧，MOC 自身由 A9 同族语义覆盖 |
+| `from_markdown` 公共面被误用 | 调用方仅 `note.py` 内部 2 处 + 测试（已 grep 核实） |
+| 其他隐藏站点 | 钉路径是「根因级」修复，未来新站点天然免疫；新增测试锁定三个症状 |
+| load 之后文件被外部改名（微竞态） | save 会按陈旧 pin 在旧路径复活文件。与现状同窗口（现状更糟：直接写规则名），非本次范围；`update_note` 重钉 pin 已收窄此窗口 |
+
+## 7. 实现文件清单（预期）
+
+- `jfox/models.py`：`from_markdown` 钉路径；新增 `expected_filepath` property；`filepath` docstring。
+- `jfox/note.py`：`update_note` 写盘/改名判据改用 `expected_filepath`（+docstring）；`save_note` docstring 明确就地写。
+- **防回归注释（交付物，#548 教训）**：`filepath` property、`from_markdown`、`update_note` 三处必须留注释，说明「就地写 / 规范化写」两分法、update_note 为何不能用 `note_obj.filepath`（E2b：钉路径后改名判据恒假，`test_edit.py:72-82` 必挂）、以及写盘成功后重钉 pin 的原因——防止未来被「简化」回 `note_obj.filepath`。
+- `tests/unit/test_note_path_rules.py`（新）。
+- `tests/integration/test_stale_name_single_file.py`（新，含 A4–A8）。
+- `CHANGELOG.md`：`## [Unreleased]` 加 Fixes 条目。
+- 视情况：`tests/unit/test_edit.py` 增补 stale 自愈用例。

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

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

{jfox_cli-1.16.1 → jfox_cli-1.16.2}/jfox/moc/cli.py

@@ -583,9 +583,9 @@ def _exact_load(idx: "NoteIndex", note_id: str) -> Optional[Note]:
     note = load_note(Path(meta.filepath))
     if note is None or note.id != note_id:
         return None
-    # from_markdown 不回填 _filepath，filepath 属性按当前标题现算；对 legacy 文件名
-    # （#407/#408 时间戳-微秒-slug 等与标题派生名不一致的文件）会算出不存在的路径，
-    # 把真实笔记误判成 ghost。钉住索引命中的真实磁盘路径后再校验存在性。
+    # #549 起 from_markdown 已钉住加载路径，此 set_filepath 冗余但保留：
+    # 它同时是「索引命中的路径必须真实存在」的防御（防 #407/#408 幽灵误判回归，
+    # 见 tests/integration/test_moc_member_commands.py 的 legacy 用例）。
     note.set_filepath(Path(meta.filepath))
     if not note.filepath.exists():
         return None

{jfox_cli-1.16.1 → jfox_cli-1.16.2}/jfox/models.py

@@ -90,10 +90,14 @@ class Note:
     embedding: Optional[List[float]] = None  # 向量
     score: Optional[float] = None  # 检索得分
     hop: Optional[int] = None  # 图谱距离
-    _filepath: Optional[Path] = None  # 自定义文件路径（覆盖默认）
+    _filepath: Optional[Path] = None  # 真实磁盘路径 pin（#549：加载时钉住；update_note 成功后重钉）
 
     def set_filepath(self, path: Path):
-        """设置自定义文件路径（用于测试）"""
+        """钉住笔记的真实文件路径。
+
+        #549 起承担生产职责：from_markdown 加载时钉住来源路径（save_note 就地写）；
+        update_note 规范化写成功后重钉到新路径（防陈旧 pin 复活同 ID 双文件）。
+        """
         self._filepath = path
 
     @property
@@ -112,11 +116,27 @@ class Note:
 
     @property
     def filepath(self) -> Path:
-        """完整文件路径"""
+        """完整文件路径。
+
+        #549：从磁盘加载的笔记此处返回钉住的真实磁盘路径（可能偏离规则名）；
+        按当前字段现算的规则路径请用 expected_filepath。
+        """
         # 如果设置了自定义路径，优先使用
         if self._filepath is not None:
             return self._filepath
 
+        return self.expected_filepath
+
+    @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
 
         base = config.notes_dir / self.type.value
@@ -196,7 +216,8 @@ class Note:
         else:
             updated = datetime.fromisoformat(updated_str)
 
-        return cls(
+        # 先构造再钉路径（见函数尾部 #549 注释）
+        note = cls(
             id=fm.get("id", ""),
             title=fm.get("title", title),
             content=content_text.strip(),
@@ -222,6 +243,13 @@ class Note:
             knowledge_type=fm.get("knowledge_type"),
             status=fm.get("status"),
         )
+        # #549：钉住加载来源的真实磁盘路径。此后 note.filepath 返回真实路径，
+        # save_note（就地写）写回原文件——文件名与当前字段分家时也不会在规则名上
+        # 另写同 id 双文件。需要「按当前字段重新定址」的操作（改标题/改 type）
+        # 请走 note.update_note，其写盘目标用 expected_filepath。
+        if filepath is not None:
+            note._filepath = Path(filepath)
+        return note
 
     def to_dict(self) -> Dict[str, Any]:
         """转换为字典（用于 JSON 输出）"""

{jfox_cli-1.16.1 → jfox_cli-1.16.2}/jfox/note.py

@@ -149,7 +149,12 @@ def _atomic_write(filepath: Path, content: str) -> None:
 
 
 def save_note(note: Note, add_to_index: bool = True) -> bool:
-    """保存笔记到文件"""
+    """保存笔记到文件（就地写）。
+
+    注意（#549）：写盘目标是 note.filepath——对从磁盘加载的笔记即「就地写回
+    加载路径」；就地写不保证文件名随字段变化。改 title/topic/type 的意图请用
+    update_note（规范化写：按当前字段现算目标并删除旧文件）。
+    """
     try:
         _atomic_write(note.filepath, note.to_markdown())
 
@@ -590,9 +595,15 @@ def reject_note(note_id: str, reason: Optional[str] = None) -> bool:
 
 def update_note(note_obj: Note, add_to_index: bool = True) -> bool:
     """
-    更新已有笔记
+    更新已有笔记（规范化写，#549）。
 
-    处理：查找旧文件 → 更新 updated 时间戳 → 写入新文件 → 删除旧文件（如路径变化）→ 更新索引
+    处理：查找旧文件 → 更新 updated 时间戳 → 写入规则派生路径（expected_filepath）
+    → 删除旧文件（如路径变化）→ 重钉 pin → 更新索引。
+
+    规范化写语义：写盘目标始终按当前字段（type/title/topic）现算，不用加载时
+    钉住的 filepath——否则钉路径后改名判据恒假，改标题/改 type 不再改名移动
+    （E2b 回归，tests/unit/test_edit.py:72-82、:373-390）。发散名笔记被触碰时
+    由此自然自愈为规则名（单文件）。
 
     Args:
         note_obj: 已修改的 Note 对象（必须已有 id）
@@ -611,13 +622,18 @@ def update_note(note_obj: Note, add_to_index: bool = True) -> bool:
         # 更新时间戳
         note_obj.updated = datetime.now()
 
-        # 写入新文件（filepath 属性根据当前字段生成）
-        _atomic_write(note_obj.filepath, note_obj.to_markdown())
+        # 规范化写（#549）：目标路径按当前字段现算，不看加载 pin。
+        target = note_obj.expected_filepath
+        _atomic_write(target, note_obj.to_markdown())
 
         # 如果文件路径变了（标题修改导致重命名），删除旧文件
-        if old_filepath != note_obj.filepath and old_filepath.exists():
+        if old_filepath != target and old_filepath.exists():
             old_filepath.unlink()
-            logger.info(f"Renamed note file: {old_filepath} -> {note_obj.filepath}")
+            logger.info(f"Renamed note file: {old_filepath} -> {target}")
+
+        # #549：写盘成功后把 pin 重钉到刚写入的路径——否则同一对象随后的
+        # save_note（就地写）会按陈旧 pin 写回旧路径、复活同 id 双文件。
+        note_obj.set_filepath(target)
 
         logger.info(f"Updated note {note_obj.id}")
 

{jfox_cli-1.16.1 → jfox_cli-1.16.2}/jfox/redirect.py

@@ -417,8 +417,9 @@ def _sync_keep_backlinks(
     """把迁移来的来源写入保留笔记的 backlinks，并移除旧笔记残留。
 
     采用 re-read-and-merge：只改 backlinks 字段，避免覆盖并发修改。
-    文件定位用 find_note_file（按 cfg 搜索）；不能依赖 Note.filepath
-    property —— from_markdown 不回填 _filepath，它会退回全局 config 推算路径。
+    文件定位用 find_note_file（按 cfg 搜索）；不依赖 Note.filepath property
+    —— #549 起 from_markdown 已钉住加载路径（Note.filepath 对加载笔记可信），
+    本函数直接操作路径、不加载 Note 对象，保留 find_note_file 定位仍最稳妥。
     """
     from .config import config
     from .note import find_note_file

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

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

{jfox_cli-1.16.1 → jfox_cli-1.16.2}/tests/integration/test_moc_member_commands.py

@@ -193,9 +193,10 @@ def test_add_member_non_permanent_warns_but_applies(seeded_kb):
 def test_add_member_loads_note_with_legacy_filename(seeded_kb):
     """#407/#408 legacy 文件名（与标题派生名不一致）：不得误判 ghost（#505 CR issue-1）。
 
-    from_markdown 不回填 _filepath，filepath 属性按标题现算
+    #549 前 from_markdown 不钉路径，filepath 属性按标题现算
     `20260820000003-zima-three.md`；真实文件用 legacy 名落盘时现算路径不存在，
-    修复前 add-member 会误报 "Member note not found"。
+    当时 add-member 会误报 "Member note not found"。#549 后由 from_markdown 钉路径
+    根治，本用例保留作回归护栏。
     """
     member_three = Note(
         id="20260820000003",