jfox-cli 1.0.0__tar.gz → 1.1.0__tar.gz

{jfox_cli-1.0.0 → jfox_cli-1.1.0}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [1.1.0] - 2026-06-21
+
+### Features
+- **cli**: add self-update command (#258)
+- 笔记归档/软删除功能（archive/unarchive） (#260)
+
+### Fixes
+- **cli**: jfox index rebuild --backlinks recalculates wiki links and backlinks
+
+[1.1.0]: https://github.com/zhuxixi/jfox/compare/v1.0.0...v1.1.0
+
 ## [1.0.0] - 2026-06-18
 
 ### Features

{jfox_cli-1.0.0 → jfox_cli-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: jfox-cli
-Version: 1.0.0
+Version: 1.1.0
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox
@@ -392,6 +392,13 @@ A session is considered "finished" when its file has not been modified for `idle
 
 > **Privacy note:** Auto-summary sends session text to Anthropic API via `claude -p` to generate summaries. Only session content is transmitted.
 
+### Self-Update
+
+| Command | Description |
+|---------|-------------|
+| `jfox update` | Upgrade jfox to the latest version (auto-detects pip/pipx/uv) |
+| `jfox update --json` | JSON output with before/after version info |
+
 ### Global Options
 
 | Option | Description |

{jfox_cli-1.0.0 → jfox_cli-1.1.0}/README.md

@@ -353,6 +353,13 @@ A session is considered "finished" when its file has not been modified for `idle
 
 > **Privacy note:** Auto-summary sends session text to Anthropic API via `claude -p` to generate summaries. Only session content is transmitted.
 
+### Self-Update
+
+| Command | Description |
+|---------|-------------|
+| `jfox update` | Upgrade jfox to the latest version (auto-detects pip/pipx/uv) |
+| `jfox update --json` | JSON output with before/after version info |
+
 ### Global Options
 
 | Option | Description |

{jfox_cli-1.0.0 → jfox_cli-1.1.0}/docs/installation.md

@@ -28,6 +28,32 @@ jfox --version
 pip install -e ".[dev]"
 ```
 
+## Upgrade
+
+```bash
+# Auto-detect installation method and upgrade
+jfox update
+
+# JSON output with version info
+jfox update --json
+```
+
+If `jfox update` fails (e.g. behind a proxy or on an unsupported install method), use the manual command for your install method:
+
+```bash
+# uv tool users
+uv tool upgrade jfox-cli
+
+# pipx users
+pipx upgrade jfox-cli
+
+# pip users
+pip install --upgrade jfox-cli
+
+# Development mode (git clone + uv sync --extra dev)
+git pull && uv sync --extra dev
+```
+
 ## Uninstall
 
 ```bash

jfox_cli-1.1.0/docs/superpowers/plans/2026-06-17-index-rebuild-backlinks.md

@@ -0,0 +1,166 @@
+# Issue #252: `jfox index rebuild` 重新计算 backlinks 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 index rebuild` 支持 `--backlinks` 选项，在重建索引时重新解析 wiki links 并计算 backlinks。
+
+**Architecture:** 在 `jfox/cli.py` 中新增 `_rebuild_backlinks_impl()` 内部函数，在 `index rebuild` action 中按用户传入的 `--backlinks` 标志调用；函数全量加载笔记、解析 `[[...]]` 链接、解析目标 ID、重新计算并写回变化的笔记。
+
+**Tech Stack:** Python, Typer, pytest
+
+---
+
+### Task 1: 实现 `_rebuild_backlinks_impl()` 内部函数
+
+**Files:**
+- Modify: `jfox/cli.py`（在 `extract_wiki_links` / `find_note_id_by_title_or_id` 附近或 `_add_note_impl` 之后新增函数）
+
+- [ ] **Step 1: 编写核心函数**
+
+  新增函数签名：
+  ```python
+  def _rebuild_backlinks_impl(output_format: str = "table") -> Dict[str, Any]:
+      ...
+  ```
+
+  功能：
+  1. 调用 `note.list_notes(limit=10000)` 加载所有笔记
+  2. 遍历笔记，调用 `extract_wiki_links(note.content)` 提取链接
+  3. 调用 `find_note_id_by_title_or_id(link_text)` 解析目标 ID
+  4. 构建 `new_links: Dict[str, List[str]]` 和 `new_backlinks: Dict[str, List[str]]`
+  5. 对每个笔记，比较现有 `links`/`backlinks` 与新计算结果
+  6. 如有变化，更新 Note 对象并调用 `note.save_note(note, add_to_index=False)`
+  7. 返回统计信息：`backlinks_rebuilt`, `backlinks_updated`, `backlinks_total`, `unresolved_links`
+
+- [ ] **Step 2: 处理边界情况**
+
+  - 空知识库：返回 `backlinks_total=0`, `backlinks_updated=0`
+  - 未解析链接：收集到 `unresolved_links` 列表中用于警告输出
+  - 保存失败：记录 warning，不中断流程
+
+---
+
+### Task 2: 在 `index rebuild` action 中集成 `--backlinks` 选项
+
+**Files:**
+- Modify: `jfox/cli.py:index()` 命令参数
+- Modify: `jfox/cli.py` 中 `action == "rebuild"` 分支
+
+- [ ] **Step 1: 添加 Typer 选项**
+
+  在 `index()` 命令中新增：
+  ```python
+  backlinks: bool = typer.Option(False, "--backlinks", "-b", help="重建时重新计算 backlinks"),
+  ```
+
+- [ ] **Step 2: 在 rebuild action 中调用**
+
+  在 `action == "rebuild"` 分支中，BM25 重建完成后：
+  ```python
+  if backlinks:
+      bl_result = _rebuild_backlinks_impl(output_format)
+      result.update(bl_result)
+  ```
+
+- [ ] **Step 3: 更新输出**
+
+  JSON 输出：合并 `backlinks_rebuilt`, `backlinks_updated`, `backlinks_total`, `unresolved_links`
+  Table 输出：增加对应行，显示 `Backlinks rebuilt: X / Y`，以及未解析链接警告
+
+---
+
+### Task 3: 编写测试
+
+**Files:**
+- New: `tests/integration/test_index_rebuild_backlinks.py`
+- New: `tests/unit/test_rebuild_backlinks_impl.py`
+
+- [ ] **Step 1: 编写集成测试**
+
+  `tests/integration/test_index_rebuild_backlinks.py`：
+  - 使用 `cli` fixture 初始化临时知识库
+  - 创建目标笔记 A 和源笔记 B（B 引用 A）
+  - 手动修改 A 的 frontmatter，移除其 `backlinks`
+  - 执行 `cli.index("rebuild", "--backlinks")`
+  - 验证 `refs A` 的 `backward_links` 包含 B
+  - 验证 JSON 输出中的 `backlinks_updated > 0`
+
+- [ ] **Step 2: 编写单元测试**
+
+  `tests/unit/test_rebuild_backlinks_impl.py`：
+  - Mock `note.list_notes()` 返回若干笔记对象
+  - 调用 `_rebuild_backlinks_impl()`
+  - 验证统计信息正确
+  - 验证 `save_note` 只在变化时调用
+
+- [ ] **Step 3: 验证默认行为不变**
+
+  集成测试增加：
+  - 默认 `jfox index rebuild`（无 `--backlinks`）不应修改任何笔记的 backlinks
+
+---
+
+### Task 4: 运行测试与代码检查
+
+- [ ] **Step 1: 运行新增单元测试**
+
+  ```bash
+  uv run pytest tests/unit/test_rebuild_backlinks_impl.py -v
+  ```
+
+- [ ] **Step 2: 运行新增集成测试**
+
+  ```bash
+  uv run pytest tests/integration/test_index_rebuild_backlinks.py -v
+  ```
+
+- [ ] **Step 3: 运行快速测试集**
+
+  ```bash
+  uv run pytest tests/ -m "not embedding and not slow" -q
+  ```
+
+- [ ] **Step 4: 代码风格检查**
+
+  ```bash
+  uv run ruff check jfox/cli.py tests/unit/test_rebuild_backlinks_impl.py tests/integration/test_index_rebuild_backlinks.py
+  uv run black --check jfox/cli.py tests/unit/test_rebuild_backlinks_impl.py tests/integration/test_index_rebuild_backlinks.py
+  ```
+
+---
+
+### Task 5: 提交与 PR
+
+- [ ] **Step 1: 整理提交**
+
+  使用 Conventional Commits：
+  ```bash
+  git add jfox/cli.py tests/unit/test_rebuild_backlinks_impl.py tests/integration/test_index_rebuild_backlinks.py docs/superpowers/specs/2026-06-17-index-rebuild-backlinks-design.md docs/superpowers/plans/2026-06-17-index-rebuild-backlinks.md
+  git commit -m "fix(cli): jfox index rebuild --backlinks recalculates wiki links and backlinks
+
+  - Add --backlinks/-b option to jfox index rebuild
+  - Add _rebuild_backlinks_impl() to parse [[...]] links and recompute backlinks
+  - Update output JSON/table with backlinks rebuild stats
+  - Add unit and integration tests
+
+  Closes #252"
+  ```
+
+- [ ] **Step 2: 推送分支**
+
+  ```bash
+  git push origin fix/252-index-rebuild-backlinks
+  ```
+
+- [ ] **Step 3: 创建 PR**
+
+  PR 标题：`fix(cli): jfox index rebuild --backlinks recalculates wiki links and backlinks`
+  PR 描述包含：
+  - 问题描述
+  - 修改内容
+  - 测试说明
+  - `Closes #252`
+
+- [ ] **Step 4: 等待 CI 通过**
+
+  在 PR 页面确认 Fast / Core workflow 通过。

jfox_cli-1.1.0/docs/superpowers/plans/2026-06-18-self-update-command.md

@@ -0,0 +1,175 @@
+# jfox self-update 命令 Implementation Plan
+
+> **For agentic workers:** implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `jfox update` command that detects the current installation method (dev / uv / pipx / pip) and invokes the appropriate upgrade command, showing before/after version info and providing manual fallback guidance on failure.
+
+**Architecture:** A new `update` Typer command in `jfox/cli.py` plus helper functions for install-method detection and upgrade command execution. Detection is path-based with command fallbacks. A unit test file `tests/unit/test_update.py` mocks filesystem paths and subprocess calls.
+
+**Tech Stack:** Python 3.10+, Typer, Rich, pytest, unittest.mock.
+
+**Spec:** `docs/superpowers/specs/2026-06-18-self-update-command-design.md`
+
+**Work context:** Work in the isolated worktree `/home/elling/git-repo/github/jfox-wt-238` on branch `feat/issue-238-self-update` (based off `main`). All paths below are relative to that worktree root.
+
+---
+
+## File Structure
+
+| File | Action | Responsibility |
+|------|--------|----------------|
+| `jfox/cli.py` | **Modify** | Add `_detect_install_method`, `_build_upgrade_command`, `_run_upgrade`, `_update_impl`, and `update` Typer command. |
+| `tests/unit/test_update.py` | **Create** | Unit tests for detection, command selection, JSON output, dev-mode prompt, and failure handling. |
+| `README.md` | **Modify** | Add `jfox update` to the command reference table. |
+| `docs/installation.md` | **Modify** | Add an "Upgrade" section with `jfox update` and manual fallbacks. |
+
+---
+
+## Task 1: Implement install-method detection helpers
+
+**Files:** `jfox/cli.py`
+
+- [ ] **Step 1: Add `_is_dev_installation` helper**
+
+  Determine development mode by checking whether `jfox.__file__` resolves to a source tree containing `pyproject.toml` with `project.name == "jfox-cli"` and a `.git` directory, or whether the path indicates an editable install (`.egg-link`).
+
+- [ ] **Step 2: Add `_is_uv_tool_installation` helper**
+
+  Run `uv tool dir` to obtain the uv tools root. Return `True` if `jfox.__file__` is relative to `<uv-tool-dir>/jfox-cli/`. If `uv` is unavailable, fall back to path-segment matching (`uv/tools/jfox-cli/`).
+
+- [ ] **Step 3: Add `_is_pipx_installation` helper**
+
+  Run `pipx environment --value PIPX_HOME` to obtain pipx home. Return `True` if `jfox.__file__` is relative to `<pipx-home>/venvs/jfox-cli/`. If `pipx` is unavailable, fall back to path-segment matching (`pipx/venvs/jfox-cli/`).
+
+- [ ] **Step 4: Add `_detect_install_method` helper**
+
+  Apply the detection order: dev → uv → pipx → pip. Return a string identifier (`"dev"`, `"uv"`, `"pipx"`, `"pip"`).
+
+---
+
+## Task 2: Implement upgrade execution and version comparison
+
+**Files:** `jfox/cli.py`
+
+- [ ] **Step 1: Add `_build_upgrade_command` helper**
+
+  Map the detected install method to the concrete command list:
+  - `"uv"` → `["uv", "tool", "upgrade", "jfox-cli"]`
+  - `"pipx"` → `["pipx", "upgrade", "jfox-cli"]`
+  - `"pip"` → `[sys.executable, "-m", "pip", "install", "--upgrade", "jfox-cli"]`
+  - `"dev"` → return `None`
+
+- [ ] **Step 2: Add `_run_upgrade` helper**
+
+  Use `subprocess.run(..., check=True, capture_output=True, text=True)` to execute the command. On success return stdout; on `CalledProcessError` raise a custom exception or return an error dict. Surface stderr to the user.
+
+- [ ] **Step 3: Add `_get_installed_version` helper**
+
+  Run `jfox --version` via subprocess and parse the version string. Return `"unknown"` if the call fails.
+
+---
+
+## Task 3: Wire up the `update` Typer command
+
+**Files:** `jfox/cli.py`
+
+- [ ] **Step 1: Add `_update_impl` internal function**
+
+  1. Read current `__version__`.
+  2. Detect install method.
+  3. If dev, return a result dict with `success=True`, `method="dev"`, and an instruction string.
+  4. Build and run the upgrade command.
+  5. Call `_get_installed_version` for the after version.
+  6. Return a result dict: `success`, `method`, `previous_version`, `current_version`, `command`, `output`.
+
+- [ ] **Step 2: Add `update` Typer command**
+
+  Support `--format json/table` and `--json` shortcut. Wrap the implementation in a try/except, print table or JSON output, and exit with code 1 on failure.
+
+---
+
+## Task 4: Add unit tests
+
+**Files:** `tests/unit/test_update.py`
+
+- [ ] **Step 1: Test dev-mode detection**
+
+  Mock `jfox.__file__` to a source tree path with `pyproject.toml` and `.git/`. Assert `jfox update` prints the dev-mode instruction and does not invoke subprocess.
+
+- [ ] **Step 2: Test uv / pipx / pip command selection**
+
+  Mock `jfox.__file__` to each tool's typical site-packages path and assert the correct subprocess command is invoked.
+
+- [ ] **Step 3: Test JSON output**
+
+  Run `jfox update --json` and verify the parsed JSON contains expected keys.
+
+- [ ] **Step 4: Test upgrade failure handling**
+
+  Make `subprocess.run` raise `CalledProcessError`. Assert exit code 1 and manual command guidance appears in output/JSON.
+
+- [ ] **Step 5: Test version before/after display**
+
+  Mock `jfox.__version__` and the post-upgrade `jfox --version` subprocess to verify both versions appear.
+
+---
+
+## Task 5: Update documentation
+
+**Files:** `README.md`, `docs/installation.md`
+
+- [ ] **Step 1: Add `jfox update` to README command table**
+
+  Place it under a new "Self-update" row or in the most appropriate existing section.
+
+- [ ] **Step 2: Add upgrade section to `docs/installation.md`**
+
+  Document `jfox update` and the manual fallbacks for each install method.
+
+---
+
+## Task 6: Run tests and static checks
+
+- [ ] **Step 1: Run the new unit tests**
+
+  ```bash
+  uv run pytest tests/unit/test_update.py -v
+  ```
+
+- [ ] **Step 2: Run fast unit tests**
+
+  ```bash
+  uv run pytest tests/unit/ -m "not embedding and not slow" -q
+  ```
+
+- [ ] **Step 3: Run ruff lint**
+
+  ```bash
+  uv run ruff check jfox/cli.py tests/unit/test_update.py
+  ```
+
+---
+
+## Task 7: Commit and create PR
+
+- [ ] **Step 1: Stage and commit changes**
+
+  Use Conventional Commits:
+
+  ```bash
+  git add jfox/cli.py tests/unit/test_update.py README.md docs/installation.md docs/superpowers/
+  git commit -m "feat(cli): add self-update command (jfox update)"
+  git commit -m "docs(readme): document jfox update command" -- README.md docs/installation.md
+  git commit -m "docs(superpowers): add self-update design and plan"
+  ```
+
+- [ ] **Step 2: Push branch and create PR**
+
+  ```bash
+  git push -u origin feat/issue-238-self-update
+  gh pr create --title "feat(cli): add self-update command" --body "Closes #238" --base main
+  ```
+
+- [ ] **Step 3: Wait for CI**
+
+  Monitor the PR checks and address any failures.

jfox_cli-1.1.0/docs/superpowers/specs/2026-06-17-index-rebuild-backlinks-design.md

@@ -0,0 +1,99 @@
+# Issue #252: `jfox index rebuild` 重新计算 backlinks 设计文档
+
+> **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.
+
+## 背景
+
+`jfox index rebuild` 当前只重建：
+1. ChromaDB 向量索引（`Indexer.index_all()` → `vector_store.reset_collection()` + 全量 add）
+2. BM25 关键词索引（`bm25_index.rebuild_from_notes()`）
+
+但它**没有**重新解析笔记正文中的 `[[笔记标题]]` 维基链接，也没有根据解析结果更新笔记 frontmatter 中的 `links` 和 `backlinks` 字段。
+
+这会导致以下问题：
+- 手动修改笔记文件后，即使执行 `jfox index rebuild`，backlinks 关系也不会恢复
+- 知识库迁移/整理后，链接网络丢失
+- 必须通过 `jfox add` 重新创建笔记才能建立链接
+
+## 目标
+
+让 `jfox index rebuild` 支持可选的 `--backlinks` 参数，在重建索引的同时：
+1. 全量加载所有笔记
+2. 解析每篇笔记正文中的 `[[...]]` 维基链接
+3. 按标题/ID 解析链接目标
+4. 更新每篇笔记的 `links` 字段（按当前内容重新生成）
+5. 根据所有笔记的 `links` 重新计算每篇笔记的 `backlinks`
+6. 只写入确实有变化的笔记文件，避免无意义的 I/O
+
+## 非目标
+
+- 不修改 `jfox add` / `jfox edit` 的现有 backlinks 维护逻辑
+- 不改变 `jfox index rebuild` 的默认行为（默认不重建 backlinks，避免意外覆盖用户手动写入的 frontmatter）
+- 不引入新的持久化存储格式
+
+## 方案
+
+### 1. 新增 `jfox index rebuild --backlinks`
+
+在 `jfox/cli.py` 的 `index()` 命令中：
+- 为 `rebuild` action 增加 `--backlinks` / `-b` 选项
+- 当用户传入 `--backlinks` 时，在 `indexer.index_all()` 和 BM25 重建完成后调用 backlinks 重建逻辑
+
+### 2. 独立函数 `_rebuild_backlinks_impl()`
+
+在 `jfox/cli.py` 中新增内部实现函数，职责单一：
+- 通过 `note.list_notes()` 加载所有笔记
+- 构建 `标题/ID → note_id` 的解析映射
+- 遍历每篇笔记，调用现有 `extract_wiki_links()` 提取链接
+- 对每个链接调用 `find_note_id_by_title_or_id()` 解析
+- 汇总得到新的 `links` 和 `backlinks`
+- 与现有值比较，仅当变化时才调用 `note.save_note(note, add_to_index=False)` 写回文件
+
+### 3. 输出与结果
+
+JSON 输出增加字段：
+- `backlinks_rebuilt`: bool
+- `backlinks_updated`: int（实际写入文件的笔记数量）
+- `backlinks_total`: int（扫描的笔记总数）
+- `unresolved_links`: List[str]（无法解析的链接文本，去重）
+
+Table 输出增加对应行：
+- `✓ Backlinks rebuilt: X notes updated / Y scanned`
+- 如有未解析链接，显示警告
+
+### 4. 错误处理
+
+- 加载失败的笔记跳过，记录 warning
+- 保存失败不中断整个流程，记录 warning，但 `backlinks_rebuilt` 仍为 True（部分成功）
+- 无任何笔记时返回成功
+
+## 关键代码位置
+
+- `jfox/cli.py:1935-1959`：`rebuild` action 的现有实现
+- `jfox/cli.py:237-243`：现有 `extract_wiki_links()`
+- `jfox/cli.py:246-290`：现有 `find_note_id_by_title_or_id()`
+- `jfox/note.py:97-125`：`save_note()` 支持 `add_to_index=False`
+
+## 测试策略
+
+1. **集成测试**：在临时知识库中创建笔记 A、B，B 引用 A，手动清空 A 的 `backlinks` 字段，执行 `jfox index rebuild --backlinks`，验证 A 的 backlinks 恢复
+2. **单元测试**：测试 `_rebuild_backlinks_impl()` 的链接解析与 backlinks 计算逻辑（使用 mock 笔记）
+3. **边界测试**：
+   - 空知识库
+   - 链接到不存在的笔记
+   - 多个笔记链接到同一目标
+   - 没有 `--backlinks` 时不应修改任何笔记
+
+## 兼容性
+
+- 默认行为不变，不影响现有用户
+- 新增的 `--backlinks` 选项是可选的
+- 输出 JSON 新增字段，不会破坏现有解析（新增字段是兼容的）
+
+## 验收标准
+
+- [ ] `jfox index rebuild --backlinks` 成功重新计算并写入所有 backlinks
+- [ ] 默认 `jfox index rebuild` 行为与修改前一致
+- [ ] 新增集成测试通过
+- [ ] ruff / black 检查通过
+- [ ] PR 描述关联 issue #252

jfox_cli-1.1.0/docs/superpowers/specs/2026-06-18-archive-soft-delete-design.md

@@ -0,0 +1,160 @@
+# Issue #259 设计文档：笔记归档/软删除
+
+## 背景与目标
+
+用户在把 session 笔记提炼为 permanent 笔记后，希望这些源 session 笔记不再出现在默认列表和搜索结果中，但又不想被永久删除。因此需要引入类似邮箱"归档"的软删除机制。
+
+目标：
+- 不真正删除文件，仅通过 frontmatter 标记 `archived: true`。
+- 默认的 `jfox list` / `jfox search` 隐藏已归档笔记。
+- 提供显式命令查看/恢复归档笔记。
+- `jfox show` 和 `jfox delete` 行为不受影响。
+
+## 需求拆解
+
+| 用户命令 | 行为 |
+|---------|------|
+| `jfox archive <note_id>` | 将笔记标记为 `archived: true`，更新 `updated` 时间戳 |
+| `jfox unarchive <note_id>` | 将笔记标记为 `archived: false`（frontmatter 中移除该字段），更新 `updated` 时间戳 |
+| `jfox list` | 默认只列出未归档笔记 |
+| `jfox list --archived` | 只列出已归档笔记 |
+| `jfox list --include-archived` | 列出全部笔记（包含归档） |
+| `jfox search "关键词"` | 默认排除已归档笔记 |
+| `jfox search "关键词" --include-archived` | 搜索时包含已归档笔记 |
+| `jfox show <id>` | 不受归档状态影响，始终可查看 |
+| `jfox delete <id>` | 真删除，不受归档状态影响 |
+
+## 方案设计
+
+### 1. 数据模型（`jfox/models.py`）
+
+在 `Note` 数据类中新增字段：
+
+```python
+archived: bool = False
+```
+
+- `to_markdown()`：仅在 `archived=True` 时把 `archived: true` 写入 frontmatter，保持未归档笔记 frontmatter 干净。
+- `from_markdown()`：读取 `archived` 字段，缺失时默认 `False`。
+- `to_dict()`：增加 `"archived"` 字段，便于 JSON 输出。
+
+### 2. 元数据索引（`jfox/note_index.py`）
+
+在 `NoteMeta` 中新增 `archived: bool = False`。
+
+索引构建时从 frontmatter 读取 `archived`，缺失默认 `False`。`list_meta()` 增加过滤参数：
+
+```python
+def list_meta(
+    self,
+    note_type: Optional[NoteType] = None,
+    tags: Optional[List[str]] = None,
+    limit: Optional[int] = None,
+    archived_only: bool = False,
+    include_archived: bool = False,
+) -> List[NoteMeta]:
+```
+
+过滤规则：
+- `archived_only=True`：只返回 `archived=True`。
+- `include_archived=True`：返回全部。
+- 默认：只返回 `archived=False`。
+
+### 3. 笔记 CRUD（`jfox/note.py`）
+
+新增：
+
+```python
+def archive_note(note_id: str) -> bool
+def unarchive_note(note_id: str) -> bool
+```
+
+实现：
+1. 通过 `load_note_by_id(note_id)` 加载笔记。
+2. 设置 `note.archived = True/False`。
+3. 调用 `update_note(note)` 持久化并同步索引（向量 + BM25）。
+
+复用 `update_note` 可以自动处理：
+- 原子写入；
+- 文件名变化（归档不会改变文件名，但保留路径）；
+- 索引更新（先删除旧向量/BM25，再添加新内容）。
+
+`list_notes()` 增加参数 `archived_only` 和 `include_archived`，透传给 `NoteIndex.list_meta()`。
+
+`search_notes()` 增加参数 `include_archived`，透传给搜索引擎。
+
+### 4. 搜索引擎（`jfox/search_engine.py`）
+
+`HybridSearchEngine.search()` 增加 `include_archived: bool = False`。
+
+由于现有 ChromaDB 集合里的笔记元数据不一定包含 `archived` 字段，直接在 ChromaDB 层过滤会导致旧数据被误排除。因此采用**后过滤**策略：
+
+1. 搜索时先按原逻辑获取结果，但 `exclude archived` 时多取一些结果（over-fetch）。
+2. 使用 `NoteIndex` 判断每个结果是否归档（`meta.archived`）。
+3. 过滤后取前 `top_k` 条。
+
+over-fetch 策略：
+- `_semantic_search` / `_keyword_search`：当 `not include_archived` 时，`search_k = max(top_k * 5, 20)`。
+- `_hybrid_search`：同样 over-fetch，融合后再过滤。
+
+这样可以在绝大多数场景下保证返回数量，同时避免旧索引数据兼容性问题。
+
+### 5. CLI（`jfox/cli.py`）
+
+新增命令：
+
+```python
+@app.command()
+def archive(
+    note_id: str = typer.Argument(..., help="笔记 ID"),
+    kb: Optional[str] = typer.Option(None, "--kb", "-k", help="目标知识库名称"),
+    output_format: str = typer.Option("table", "--format", "-f", help="输出格式: json, table"),
+    json_output: bool = typer.Option(False, "--json", help="JSON 输出"),
+):
+    ...
+
+@app.command()
+def unarchive(...):
+    ...
+```
+
+`list` 命令增加选项：
+
+```python
+archived_only: bool = typer.Option(False, "--archived", help="仅显示已归档笔记"),
+include_archived: bool = typer.Option(False, "--include-archived", help="包含已归档笔记"),
+```
+
+`--archived` 与 `--include-archived` 互斥，同时指定时报错。
+
+`search` 命令增加选项：
+
+```python
+include_archived: bool = typer.Option(False, "--include-archived", help="包含已归档笔记"),
+```
+
+`_list_impl` / `_search_impl` 相应增加参数透传。
+
+### 6. 测试策略
+
+新增 `tests/unit/test_archive.py`，覆盖：
+
+- `Note.to_markdown()` / `from_markdown()` 正确读写 `archived`。
+- `NoteIndex.list_meta()` 默认排除归档、支持 `archived_only` / `include_archived`。
+- `archive_note()` / `unarchive_note()` 更新文件与索引。
+- `list` CLI 默认排除归档、`--archived`、`--include-archived`。
+- `search` CLI 默认排除归档、`--include-archived`。
+- `show` / `delete` 对归档笔记行为不变。
+
+使用现有 fixture（`temp_kb`、`cli_fast`）避免加载 embedding 模型。
+
+## 兼容性
+
+- 旧笔记没有 `archived` 字段，解析时默认视为未归档，行为不变。
+- 已写入的 ChromaDB/BM25 索引不需要重建即可工作（后过滤）。
+- 归档/取消归档会触发 `update_note()`，自动更新索引内容。
+
+## 风险与回滚
+
+- 风险：后过滤可能导致 `top_k` 返回数量不足（如果前 N 条中归档笔记很多）。通过 over-fetch（`*5` 且至少 20）缓解。
+- 回滚：取消归档会移除 frontmatter 中的 `archived` 字段，恢复为未归档状态。