jfox-cli 1.16.3__tar.gz → 1.17.0__tar.gz

{jfox_cli-1.16.3 → jfox_cli-1.17.0}/.claude-plugin/marketplace.json

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

{jfox_cli-1.16.3 → jfox_cli-1.17.0}/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to jfox-cli will be documented in this file.
 
+## [1.17.0] - 2026-10-27
+
+### Features
+
+- **session**: session 笔记记录 agent 类型与 session 文件路径，pi 接入 auto-summary（#578） (#582)
+- **similarity**: S2 dedup calibration with percentile verdicts (#586) (#587)
+- **skill**: session-to-permanent 高置信度分级闸门（#575） (#581)
+
+### Fixes
+
+- **links**: 标题含 # 的 wiki-link 截断与静默错链修复 (#458) (#574)
+- **moc**: add-member 末尾分组换行丢失/成员行粘连 (#547) (#571)
+
+### Changes
+
+- **claude.md**: batch refresh — fold in 5 pending auto/claude-md PRs (#570)
+
+[1.17.0]: https://github.com/zhuxixi/jfox/compare/v1.16.3...v1.17.0
+
 ## [1.16.3] - 2026-10-10
 
 ### Fixes
@@ -32,16 +51,6 @@ All notable changes to jfox-cli will be documented in this file.
 
 [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)
-
-- **index**: `index rebuild --backlinks` 写回改为「重读→分歧检测→原子写」：检测到并发修改或文件缺失的笔记本轮跳过（计入新 JSON 字段 `backlinks_skipped`，下轮重建自愈），并发 `edit` 的正文不再被旧快照静默覆盖 (#561)
-
 ## [1.16.0] - 2026-09-23
 
 ### Features

{jfox_cli-1.16.3 → jfox_cli-1.17.0}/CLAUDE.md

@@ -69,6 +69,7 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 | `model_downloader.py` | Embedding 模型下载与缓存管理 |
 | `note_index.py` | 笔记索引管理（文件名↔ID 映射） |
 | `indexer.py` | File monitoring (watchdog) + incremental indexing |
+| `index_state.py` | 索引状态持久层（#539）：`.zk/index_state.json` 原子写；`index rebuild`/`rebuild-bm25` 成功后落盘，`index status` 的 `last_rebuild`/`bm25_indexed` 事实来源（watcher 内存计数器已删，status 只报持久化真实状态） |
 | `note.py` | Markdown file CRUD with YAML frontmatter |
 | `models.py` | `Note` data model with frontmatter serialization |
 | `add_dedup.py` | `jfox add` permanent 落库前双通道防重（#383）：标题通道（非 archived 同标题、大小写不敏感、不限类型）+ 正文余弦 ≥0.95 通道（复用顶层 `jfox/dedup.py`，`daemon_only=True` 绝不回退本地模型加载、仅 daemon 在跑时启用）；闸门自身故障一律放行，非路障 |
@@ -82,7 +83,7 @@ Notes are Markdown files with YAML frontmatter stored under `~/.zettelkasten/<kb
 | `prompts/` | Prompt 记录与按需判断（#399，已合 parts 2-6）：记录层全量保存 CC UserPromptSubmit 到 `user_prompts`（与 fragment 共用 fragments.db，`JFOX_FRAGMENTS_DB` 可覆盖；cc-plugin hook 先原子写 spool `~/.zettelkasten/prompt-spool/` 再尽力 POST daemon `/api/prompt`，失败留 spool 待 drain 导入）；判断层 `judge.py` session 批量编排（claim 租约 → `transcript.py` 三模式上下文 → `runner.py` 外部 runner → `grounding.py` strict grounding → 存 candidate 带 `source_prompts` 溯源），成功只写 pending 留人工 disposition；`actions.py`+`cli.py` 人工处置面 `jfox prompts list/show/status/drain/backfill/judge/promote/unresolved/resolve-unresolved/ignore/retry/config`（#508），`lifecycle.py` 订阅 candidate 直接 promote/reject 时同步 judgment；runner 安全边界：argv + shell=False、prompt 只走 stdin、reserved flags 不被 `extra_args` 覆盖；配置在 `~/.zk_config.json` 的 `prompt_capture` 与 `prompt_judge` 两节 |
 | `candidates/` | 候选宝石过审 CLI（#497 从 gem_synth 原样解耦迁移）：`jfox candidates list/show/promote/reject`，命令名/参数/输出不变；gem_synth 自动合成与合成进度命令已整体退役（#498，daemon 只剩 auto-summary/backup loop） |
 | `dedup.py` / `dedup_lifecycle.py` | 顶层 dedup 表（原 `gem_synth/dedup.py`，#498 迁移）：正文余弦查重 SQLite，`jfox add` 防重共查；`dedup_lifecycle.py` 订阅 note delete/archive/promote/reject 同步 dedup 行（删除/归档清行、promote 改类型——残留 embedding 会让 add 误拦重新添加已删内容，#383 语义） |
-| `auto_summary/` | 自动总结子系统：daemon 内扫描 `~/.claude/projects/` 已结束的 Claude Code session，经 `claude -p` 生成摘要写入 `session` 笔记；CLI `jfox auto-summary run/scan/status/enable/disable`，ledger 去重 + schedule time window |
+| `auto_summary/` | 自动总结子系统：daemon 内扫描 Claude Code（`~/.claude/projects/`）、Kimi Code（`~/.kimi-code/sessions/`）与 pi（官方目录 + agent-board 目录）已结束的 session，经 `claude -p` 生成摘要写入 `session` 笔记；CLI `jfox auto-summary run/scan/status/enable/disable`，ledger 去重 + schedule time window |
 | `backup/` | KB 滚动备份/恢复：`manager.py` BackupManager（tar.gz+sha256 清单+滚动轮转+可逆 restore）+ daemon `loop.py` 定时备份（镜像 auto-summary，quiesce 标志让兄弟写类 loop 跳过写 tick）+ `jfox backup run/enable/disable/status/list/verify/restore`；默认关，opt-in |
 | `moc/` | MOC 结构层：`cluster.py` 密度诊断（永久笔记向量余弦相似度多阈值聚类——阈值化加权图 Louvain 社区发现（边权=相似度，`seed=42` 确定性，#463 起替代传递连通分量），默认阈值 0.65→0.75、diagnose 网格 0.70–0.80，#410/#463；链接/语义孤儿检测——向量行三态分类 ghost（磁盘缺失）/archived（已归档，不计孤儿）/live（#499/#510），N×N 稠密矩阵上限 5000）+ `draft.py`/`generate.py` create/update（从诊断簇生成并维护 structure 笔记，落盘带 backlinks 回填与成员磁盘存在性校验，#413）；CLI `jfox moc diagnose/create/update/add-member/remove-member`（add/remove-member 单成员精确增删并维护正文/links/backlinks 一致 + session-time MOC ownership，#484/#505）；重依赖经 `__init__.py` 的 `__getattr__` 按需加载 |
 | `vector_store.py` | ChromaDB vector store for semantic search；批量读 `get_all_embeddings()` 走复制前后清单校验一致的只读快照副本而非活库（Chroma 只读集合也会写 SQLite），失败抛 `VectorStoreReadError`（#407） |
@@ -157,7 +158,7 @@ Four jobs in `.github/workflows/integration-test.yml`:
 
 **Release** workflow in `.github/workflows/publish.yml`: publishes to PyPI on GitHub release publication.
 
-**Local nightly full-test**（#263/#361，非 GitHub Action）：`scripts/nightly_test.sh` 是本机 crontab 定时任务（crontab 行装本机、不进仓库），每周二 09:00 跑 CI `test-fast` 跳过的全量 pytest（performance/bulk/slow/embedding）——成功静默，失败按签名去重复用带 `nightly-test-failure` label 的 issue。前置：今日 #338 备份须成功（读 `~/.jfox-backup/state.json` 的 `last_ok`，否则 `SKIP: 今日备份未确认` 退出）。纯逻辑在 `scripts/nightly_test_helpers.py`（单测 `tests/unit/test_nightly_test_helpers.py`）；`--dry-run` 用人造失败走 issue 流程、不跑真实 pytest。
+**Local nightly full-test**（#263/#361，非 GitHub Action）：`scripts/nightly_test.sh` 是本机 crontab 定时任务（crontab 行装本机、不进仓库），每周二 09:00 跑 CI `test-fast` 跳过的全量 pytest（performance/bulk/slow/embedding）——成功静默，失败按签名去重复用带 `nightly-test-failure` label 的 issue。前置：今日 #338 备份须成功（读 `~/.jfox-backup/state.json` 的 `last_ok`，否则 `SKIP: 今日备份未确认` 退出）。纯逻辑在 `scripts/nightly_test_helpers.py`（单测 `tests/unit/test_nightly_test_helpers.py`）；`--dry-run` 用人造失败走 issue 流程、不跑真实 pytest；`--ref <git-ref>` 调试模式测指定 ref（跳过备份检查、失败不提 issue，#565）。worktree 内 `uv sync --frozen --extra dev --extra embed` 且跑前 `check-embed-env` fail-fast——#519 拆出 `[embed]` 后漏装 extra 则 embedding 测试全降级，缺组件 exit 4 = 环境失败、不提 issue（#559）。
 
 ## Release Tooling
 
@@ -207,7 +208,10 @@ JFox ships as a Claude Code plugin. Two-tier structure:
 - `rich` Console 输出机器解析的 JSON 时须 `soft_wrap=True`：默认按 80 列硬折行，会把长字符串（如 Windows 绝对路径）在 JSON 字符串内部断行，`json.loads` 报 Invalid control character（Ubuntu 路径短不触发，只在 Windows CI 挂，#336）。参考 `bookshelf/cli.py` `_emit_json`
 - JSON 模式（`cli.py` `_json_mode_requested` 兼容 `--json`/`-f json`/`-fjson`/`--format=json`，重复 flag 取后者）下 CLI 入口统一 `logging.disable(CRITICAL)` + `TQDM_DISABLE=1`，保证 `--json 2>&1 | jq` 合流后仍是纯 JSON（#383 根因 A：INFO/tqdm 噪声曾令调用方解析失败、误判后重跑产生重复笔记）；命令内告警并入 JSON 字段（如 add 的 `vector_dimension_warning`）而非 stderr print——stderr 在 2>&1 管道同样污染解析流
 - `delete_note`/`promote_note` 增量同步各 target 的 backlinks（#388 起对称）：写盘前按真实磁盘路径 re-read-and-merge——重读 fresh 再合并写回，文件名发散不产生同 id 双文件、与常驻 daemon 并发写不丢更新（#392/#422）；单 target 写盘失败仅 warning 不中断，悬空/不对称残留用 `jfox index rebuild --backlinks` 全量重算兜底
+- 笔记双写路径契约（#549）：`from_markdown` 加载时钉住真实磁盘路径——加载笔记的 `note.filepath` 即真实路径（legacy 发散名不误算），按当前字段现算的规则路径用 `expected_filepath`；`save_note` 就地写（写回 pin 路径、不随字段改名），`update_note` 规范化写（目标 `expected_filepath`，路径变化删旧文件并重钉 pin，发散名笔记被触碰即自愈为规则名）——改 title/type 必须走 `update_note`，写盘目标误用 `note.filepath` 会让改名判据恒假、edit --title 不再移动文件
+- backlinks 批量写回统一走 `note.apply_backlinks()` 窄写原语（#561/#562）：定位（快照钉住路径优先）→ 重读 fresh → 与快照序列化比对，发现并发分歧即本轮跳过（返回 `"skipped"` 属正常竞态非故障，下轮 rebuild 自愈）→ 零写入守卫 → 原子写；`index rebuild --backlinks` 不得用 `save_note` 从陈旧快照整条覆盖（曾静默吞并发 edit 的正文），调用方也别原地改快照的 `links`/`backlinks`（分歧检测以快照为比对基准）；rebuild JSON 统计含 `backlinks_skipped`
 - `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）
+- Wiki-link 排除区剥离（`note_index.py` `_strip_wiki_link_exclusions`，`resolve_wiki_links()` 链路第一步）必须保持单遍合并正则 `_EXCLUSION_RE`（alternation 顺序即优先级：fenced > HTML 注释 > inline code），勿拆回多次顺序 `re.sub`——顺序剔除会让已删区域拼出新结构再被后续 pass 跨界吞掉（#548：反引号包 HTML 注释，注释先删留空反引号对，inline 分支吞相邻 wiki link，#550 修复）；回归测试 `tests/unit/test_wiki_link_resolution.py`

{jfox_cli-1.16.3 → jfox_cli-1.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: jfox-cli
-Version: 1.16.3
+Version: 1.17.0
 Summary: JFox - Zettelkasten 知识管理 CLI 工具
 Project-URL: Homepage, https://github.com/zhuxixi/jfox
 Project-URL: Repository, https://github.com/zhuxixi/jfox
@@ -84,7 +84,7 @@ JFox is designed to keep its core knowledge-management workflow local rather tha
 - **Knowledge refinement** — Record user prompts verbatim, classify them on demand with a configurable judge, and promote candidates into permanent notes.
 - **Local bookshelf assets** — Keep PDFs, extracted bundles, and book metadata together without mixing them into the note index.
 - **Multiple knowledge bases** — Separate work, personal, research, or project knowledge while keeping the same CLI.
-- **Operational safeguards** — Use an embedding daemon, rolling backups, archive/unarchive, and optional Claude Code session auto-summary when you need them.
+- **Operational safeguards** — Use an embedding daemon, rolling backups, archive/unarchive, and optional coding-agent session auto-summary when you need them.
 
 ## Quick Start
 
@@ -201,7 +201,7 @@ Judge execution is explicit: it runs only when you invoke `jfox prompts judge`.
 
 Use `jfox archive` and `jfox unarchive` when a note should leave or return to the active workflow without being permanently deleted. Use multiple knowledge bases to keep unrelated contexts separate.
 
-The backup system can create, verify, and restore rolling snapshots of your knowledge-base data. Use `jfox backup restore SNAPSHOT` to restore a knowledge-base state from a snapshot. The embedding daemon keeps the local model available between commands, while optional auto-summary can turn finished Claude Code sessions into `session` notes.
+The backup system can create, verify, and restore rolling snapshots of your knowledge-base data. Use `jfox backup restore SNAPSHOT` to restore a knowledge-base state from a snapshot. The embedding daemon keeps the local model available between commands, while optional auto-summary can turn finished Claude Code / Kimi Code / pi sessions into `session` notes.
 
 These operational features are opt-in or explicit actions. Review [Privacy](#privacy) before enabling auto-summary, and review [Installation and Development](#installation-and-development) for troubleshooting and model-download details.
 
@@ -388,7 +388,7 @@ JFox is local-first, but not every optional integration is offline:
 
 - Notes, indexes, and core note, search, and graph operations run locally by default.
 - The embedding model may need to be downloaded the first time it is used. After that, it can be reused from the local cache.
-- The optional auto-summary feature invokes `claude -p` to summarize finished Claude Code sessions.
+- The optional auto-summary feature invokes `claude -p` to summarize finished coding-agent sessions (Claude Code, Kimi Code, pi).
 - Auto-summary sends the selected session text to Anthropic through the Claude Code CLI. Enable it only when that data flow is acceptable to you.
 
 You control which optional services to enable. Services that support knowledge-base selection expose their own target-knowledge-base settings.

{jfox_cli-1.16.3 → jfox_cli-1.17.0}/README.md

@@ -42,7 +42,7 @@ JFox is designed to keep its core knowledge-management workflow local rather tha
 - **Knowledge refinement** — Record user prompts verbatim, classify them on demand with a configurable judge, and promote candidates into permanent notes.
 - **Local bookshelf assets** — Keep PDFs, extracted bundles, and book metadata together without mixing them into the note index.
 - **Multiple knowledge bases** — Separate work, personal, research, or project knowledge while keeping the same CLI.
-- **Operational safeguards** — Use an embedding daemon, rolling backups, archive/unarchive, and optional Claude Code session auto-summary when you need them.
+- **Operational safeguards** — Use an embedding daemon, rolling backups, archive/unarchive, and optional coding-agent session auto-summary when you need them.
 
 ## Quick Start
 
@@ -159,7 +159,7 @@ Judge execution is explicit: it runs only when you invoke `jfox prompts judge`.
 
 Use `jfox archive` and `jfox unarchive` when a note should leave or return to the active workflow without being permanently deleted. Use multiple knowledge bases to keep unrelated contexts separate.
 
-The backup system can create, verify, and restore rolling snapshots of your knowledge-base data. Use `jfox backup restore SNAPSHOT` to restore a knowledge-base state from a snapshot. The embedding daemon keeps the local model available between commands, while optional auto-summary can turn finished Claude Code sessions into `session` notes.
+The backup system can create, verify, and restore rolling snapshots of your knowledge-base data. Use `jfox backup restore SNAPSHOT` to restore a knowledge-base state from a snapshot. The embedding daemon keeps the local model available between commands, while optional auto-summary can turn finished Claude Code / Kimi Code / pi sessions into `session` notes.
 
 These operational features are opt-in or explicit actions. Review [Privacy](#privacy) before enabling auto-summary, and review [Installation and Development](#installation-and-development) for troubleshooting and model-download details.
 
@@ -346,7 +346,7 @@ JFox is local-first, but not every optional integration is offline:
 
 - Notes, indexes, and core note, search, and graph operations run locally by default.
 - The embedding model may need to be downloaded the first time it is used. After that, it can be reused from the local cache.
-- The optional auto-summary feature invokes `claude -p` to summarize finished Claude Code sessions.
+- The optional auto-summary feature invokes `claude -p` to summarize finished coding-agent sessions (Claude Code, Kimi Code, pi).
 - Auto-summary sends the selected session text to Anthropic through the Claude Code CLI. Enable it only when that data flow is acceptable to you.
 
 You control which optional services to enable. Services that support knowledge-base selection expose their own target-knowledge-base settings.

{jfox_cli-1.16.3 → jfox_cli-1.17.0}/docs/cli-descriptions.yaml

@@ -6,7 +6,7 @@ commands:
   "jfox archive":
     description: "Archive a note without permanently deleting its file."
   "jfox auto-summary":
-    description: "Manage automatic summaries of completed Claude Code sessions."
+    description: "Manage automatic summaries of completed coding-agent sessions (Claude Code, Kimi Code, pi)."
   "jfox auto-summary disable":
     description: "Disable the auto-summary background loop without clearing its ledger."
   "jfox auto-summary enable":
@@ -145,6 +145,12 @@ commands:
     description: "Search notes by keyword, semantic meaning, or both."
   "jfox show":
     description: "Show the complete Markdown content of a note."
+  "jfox similarity":
+    description: "Inspect similarity baselines and judge candidate notes against the library."
+  "jfox similarity check":
+    description: "Compare a candidate note against the library and report a percentile verdict."
+  "jfox similarity stats":
+    description: "Show the nearest-neighbor similarity distribution for permanent notes."
   "jfox status":
     description: "Show knowledge-base and index status."
   "jfox suggest-links":

{jfox_cli-1.16.3 → jfox_cli-1.17.0}/docs/cli-reference.md

@@ -47,6 +47,9 @@ jfox add [OPTIONS] [CONTENT]
 | `template` | `--template, -T` | TEXT | no | — | — | no | no |
 | `content_file` | `--content-file` | TEXT | no | — | — | no | no |
 | `topic` | `--topic` | TEXT | no | — | — | no | no |
+| `agent` | `--agent` | TEXT | no | — | — | no | no |
+| `session_path` | `--session-path` | TEXT | no | — | — | no | no |
+| `agent_model` | `--agent-model` | TEXT | no | — | — | no | no |
 | `force` | `--force` | BOOL | no | `false` | — | no | yes |
 | `kb` | `--kb, -k` | TEXT | no | — | — | no | no |
 | `output_format` | `--format, -f` | TEXT | no | `table` | — | no | no |
@@ -71,7 +74,7 @@ jfox archive [OPTIONS] NOTE_ID
 
 ## `jfox auto-summary`
 
-Manage automatic summaries of completed Claude Code sessions.
+Manage automatic summaries of completed coding-agent sessions (Claude Code, Kimi Code, pi).
 
 **Usage**:
 
@@ -1226,6 +1229,57 @@ jfox show [OPTIONS] NOTE_REF
 | `json_output` | `--json` | BOOL | no | `false` | — | no | yes |
 | `kb` | `--kb, -k` | TEXT | no | — | — | no | no |
 
+## `jfox similarity`
+
+Inspect similarity baselines and judge candidate notes against the library.
+
+**Usage**:
+
+```text
+jfox similarity COMMAND [ARGS]...
+```
+
+## `jfox similarity check`
+
+Compare a candidate note against the library and report a percentile verdict.
+
+**Usage**:
+
+```text
+jfox similarity check [OPTIONS]
+```
+
+| Parameter | Syntax | Type | Required | Default | Choices | Multiple | Flag |
+|---|---|---|---|---|---|---|---|
+| `content_file` | `--content-file` | PATH | no | — | — | no | no |
+| `content` | `--content` | TEXT | no | — | — | no | no |
+| `title` | `--title` | TEXT | no | — | — | no | no |
+| `exclude_id` | `--exclude-id` | TEXT | no | — | — | no | no |
+| `top` | `--top` | INTEGER | no | `3` | — | no | no |
+| `pass_below` | `--pass-below` | INTEGER | no | `50` | — | no | no |
+| `gray_below` | `--gray-below` | INTEGER | no | `90` | — | no | no |
+| `kb` | `--kb, -k` | TEXT | no | — | — | no | no |
+| `refresh` | `--refresh` | BOOL | no | `false` | — | no | yes |
+| `output_format` | `--format, -f` | TEXT | no | `table` | — | no | no |
+| `json_output` | `--json` | BOOL | no | `false` | — | no | yes |
+
+## `jfox similarity stats`
+
+Show the nearest-neighbor similarity distribution for permanent notes.
+
+**Usage**:
+
+```text
+jfox similarity stats [OPTIONS]
+```
+
+| Parameter | Syntax | Type | Required | Default | Choices | Multiple | Flag |
+|---|---|---|---|---|---|---|---|
+| `kb` | `--kb, -k` | TEXT | no | — | — | no | no |
+| `refresh` | `--refresh` | BOOL | no | `false` | — | no | yes |
+| `output_format` | `--format, -f` | TEXT | no | `table` | — | no | no |
+| `json_output` | `--json` | BOOL | no | `false` | — | no | yes |
+
 ## `jfox status`
 
 Show knowledge-base and index status.

{jfox_cli-1.16.3 → jfox_cli-1.17.0}/docs/json-schemas.md

@@ -40,11 +40,11 @@ else:
 | 命令 | 成功顶层字段 | 实体位置 | 失败形状 |
 |------|--------------|----------|----------|
 | `init` | `success, message, name` | 平铺 | `{success, error}` |
-| `add` | `success, id, title, note{id,title,type,filepath,links}` + 可选 `warnings, backfill_failures, rollback_failures, backfill_note_save_failed, vector_dimension_warning, semantic_index_warning`（#519 无语义组件时降级提示） | 嵌套 `note`；顶层冗余 `id`/`title` | 重复：`{success, skipped:"duplicate", duplicate{matched_id,matched_title,matched_by,score}}`；其余 `{success, error}` |
+| `add` | `success, id, title, note{id,title,type,filepath,links}` + 可选 `agent,session_file,agent_model`（#578）+ 可选 `warnings, backfill_failures, rollback_failures, backfill_note_save_failed, vector_dimension_warning, semantic_index_warning`（#519 无语义组件时降级提示） | 嵌套 `note`；顶层冗余 `id`/`title` | 重复：`{success, skipped:"duplicate", duplicate{matched_id,matched_title,matched_by,score}}`；其余 `{success, error}` |
 | `search` | `success, query, mode, include_archived, total, results[]` + 可选 `warnings[]`（#519 降级时） | 列表 `results` | `{success, error}`；`--mode semantic` 且无语义服务时拒绝：`{success, code:"embed_dependency_missing", error}`（#519） |
 | `status` | `success, knowledge_base{path,exists}, stats, backend{type,model,dimension}, embedding{local_package,daemon_running,service_available}`（#519 可用性块） | 嵌套三段 | `{success, error}` |
 | `list` | `success, total, notes[]`（项含 `outgoing,incoming`） | 列表 `notes` | `{success, error}` |
-| `show` | `success` + `id,title,type,created,updated,tags,links,backlinks,topic,filepath,content,content_body` + 可选 `source,archived`、candidate 字段（`gem_level` 等）、溯源字段（`source_fragments` 等） | 顶层平铺 | `{success, error}` |
+| `show` | `success` + `id,title,type,created,updated,tags,links,backlinks,topic,filepath,content,content_body` + 可选 `source,archived,agent,session_file,agent_model`、candidate 字段（`gem_level` 等）、溯源字段（`source_fragments` 等） | 顶层平铺 | `{success, error}` |
 | `refs` | 默认：`success, notes[]`；`--search`：`success, query, matches[]`；`--note`：`success, note{id,title,type}, forward_links[], backward_links[]`（悬空项带 `dangling:true`） | 分支各异 | `{success, error}` |
 | `delete` | `success, deleted, title` | 平铺 | 入链守卫：`{success, error, references{frontmatter[],body[],total}}`；其余 `{success, error}` |
 | `archive` / `unarchive` | `success, archived`/`unarchived`, `title` | 平铺 | `{success, error}` |
@@ -140,6 +140,15 @@ else:
 
 `moc` 全部命令（`diagnose / create / update / add-member / remove-member`）本就带 `success`，本轮未改动：成功均为 `success` + 各自业务字段（`diagnose` 含 `coverage{...}, threshold_sweep[], orphans{...}`；`create` 含 `cluster{...}, draft{...}, created`；`update` 含 `updates[], applied`；`add-member/remove-member` 平铺操作结果），失败为 `{success, error}`。
 
+### similarity
+
+| 命令 | 成功顶层字段 | 实体位置 | 失败形状 |
+|------|--------------|----------|----------|
+| `similarity stats --json` | `success, kb, model, dimension, note_count, sampled, baseline{...}\|null, policy{pass_below,gray_below}, cached, computed_at, unavailable_reason` | 平铺 + `baseline` 嵌套 | `{success, error}` + 退出码 1 |
+| `similarity check --json` | `success, kb, candidate{title,chars}, top1{...}\|null, matches[], baseline{...}, policy{pass_below,gray_below}, verdict, unavailable_reason, warnings[]` | 平铺 + `top1`/`matches` | 输入错误 `{success, error}` + 退出码 1 |
+
+`similarity stats` 的 `baseline` 在空库（permanent < 30 或无向量库）时为 `null`，`unavailable_reason` 给出原因；命令本身仍 `success:true`。`similarity check` 的 `verdict` 取值 `new` / `gray` / `covered` / `unavailable`；`unavailable` 表示信号缺失（空库、daemon 不可用、维度不匹配等），命令本身仍 `success:true` 且退出码 0，调用方按 fail-closed 降人工。`baseline` 字段含 `p50,p75,p90,p95,p99,note_count,sampled`；`top1`/`matches` 项含 `id,title,score,percentile`。
+
 ## 特殊语义说明
 
 以下行为是**有意设计**，调用方按此理解：