# JA Local KB

本目录是跨平台产品实现，和上一级 `40_code` 中的 Windows/Ollama 历史原型分开。

## 当前状态

`0.1.2` 修复了长驻 MCP 在 watcher 完成外部索引更新后仍持有旧 LanceDB
进程内视图的问题：查询会在现有跨进程锁内比较已提交索引版本，必要时重开
LanceDB 并清空向量快照；旧版本证据不再能伪装成 fresh。该修复不改变
Embedding、Reranker、Chunk、来源 ID、客户过滤或三个 MCP 工具，也不要求
未变化来源重新向量化。

`0.1.1` 在首个稳定版基础上增加客户知识原生登记与统一过滤，并将
Apple Silicon 安装、插件、STDIO MCP 和重复安装纳入自动化分发门禁。
支持范围必须分开理解：Windows 已验收；macOS 只支持 Apple Silicon
（M 系列芯片），自动化门禁已通过但真实 Mac 端到端验收仍待完成；Intel Mac
不受支持；Claude 真实客户端也尚未验收。Intel 边界来自 LanceDB 当前 macOS
发行包只提供 arm64 轮子：<https://pypi.org/project/lancedb/#files>。
其中 `0.1.2` 必须在 Release 发布后完成 Windows 日常设备原地更新与长驻 MCP
真实更新/撤销验收；Apple Silicon Mac 仍需在老板真实设备完成端到端验收。

- 已实现显式来源注册、结构化 Chunk、差异 Embedding、SQLite 状态、
  LanceDB 全文/向量/混合检索和失效拒答。
- 已实现且只公开三个本地 STDIO MCP 工具。
- 已在同一来源注册表和三个 MCP 工具内原生兼容客户知识：六种检索模式
  统一支持 `client_ids`，与 `project_ids` 同时提供时使用 AND；Obsidian
  默认识别客户 00—06 并排除归档。
- `recall` 是默认 Agent 模式：8B Embedding 生成最多 80 条可追溯证据，
  直接交给 Claude/Codex 二次筛选、分析和回答，不调用 Reranker。
- `quality` 保留为可选紧凑模式：独立 API Reranker 将同一候选池压缩到
  24-40 条；它不是默认主链路。
- 已构建 Obsidian 来源与状态控制插件：右键显式入库后释放弹窗，
  watcher 后台串行切片和向量化，状态页显示进度，文件树与原生图谱同步标记；
  无变化轮询不再重建侧栏，真实更新会保留滚动与全部折叠状态。
- 已加入默认收起的 Codex、Claude 紧凑连接入口：复制完整提示词后由目标 Agent 检查环境、
  备份并合并 MCP 配置，再以真实工具发现和状态/检索/证据回读验证连接。
- “检索诊断”只展示本次候选证据，不宣称找全；“召回质量报告”只对冻结
  题目和人工标注证据给出正式结论，并在语料、索引、模型或配置变化后标旧。
- 已提供 Windows 与 Apple Silicon macOS 的预检、安装、诊断、更新和回滚脚本；
  macOS 预检会在写入前拒绝 Intel 架构。版本快照不保存 `sources.json`，旧快照
  恢复也不能覆盖设备当前来源。
- 已使用 42 份冻结基准来源、783 个 Chunk 和 12 道冻结交叉项目题完成 4B/8B
  同条件 API 验收。
- 历史冻结基准的主链路为 `Qwen/Qwen3-Embedding-8B + recall Top80`：证据覆盖
  `47/47（100%）`、项目覆盖 `27/27（100%）`、可追溯 `100%`。
- 上述结果对应 42 份来源和索引版本 131；当前来源范围变化后，系统会将
  它标为历史/过期，不能作为当前语料已经完整召回的证明。
- 本次正式单轮复杂题延迟中位数 `3.112 秒`、P95 `35.914 秒`，召回质量
  通过，但 API 长尾速度门槛未通过，必须与质量指标分开呈现。
- 8B Reranker Top40 为 `42/47（89.36%）`，说明紧凑压缩会丢证据；
  仅在上下文预算不足时按需启用。
- 真实 Obsidian、Codex MCP、来源保护与 Windows 相邻版本回滚已经通过；
  Apple Silicon macOS 与 Claude 客户端仍需分别完成真实端到端验证。

## 产品边界

- Obsidian Markdown 是唯一真源。
- 每台设备独立保存来源清单、SQLite 状态与 LanceDB。
- 建库与查询统一使用 API Embedding。
- v1 对 Agent 只公开本地 STDIO MCP。
- Obsidian 插件是来源、状态、操作和连接控制面，不提供聊天回答。
- 首版通过公开 GitHub 稳定 Release 与本地 Agent 辅助部署；正式设备只安装
  已审核 tag/Release，不自动追踪 `main`。

开发与发布只允许使用无真实业务数据的测试夹具。Vault、LanceDB、日志、
API Key、来源注册表和机器配置不得进入 GitHub 或 Release。

## 获取与授权边界

- 代码仓库：<https://github.com/jefferyadventure519-byte/ja-local-kb>
- 稳定版本：<https://github.com/jefferyadventure519-byte/ja-local-kb/releases>
- 本仓库公开是为了简化设备安装和更新，不等于开源；当前没有附加开源许可证。
  复制、修改或二次分发前，应先取得仓库所有者许可。

## 目录入口

- `docs/architecture.md`
- `docs/state-machine.md`
- `docs/mcp-contract.md`
- `contracts/source-registry.schema.json`
- `INSTALL_AGENT.md`
- `UPDATE_AGENT.md`

## 本地开发验证

Python 3.11+、`uv` 和 Node.js 20+ 可用后：

```powershell
$runtimeRoot = 'D:\JA-Local-KB'
$vaultRoot = 'D:\path\to\your-vault'
$env:UV_CACHE_DIR = Join-Path $runtimeRoot 'runtime\uv-cache'
uv sync --all-extras --no-editable
uv run --no-sync ruff check .
pwsh -File scripts\test-windows.ps1 `
  -RuntimeRoot $runtimeRoot `
  -VaultRoot $vaultRoot
npm.cmd --prefix obsidian-plugin run build
uv build
```

Windows 中文路径下使用 `--no-editable`，避免某些 `.pth` 加载器按系统编码读取
UTF-8 路径。修改 Python 源码后需重新执行 `uv sync ... --reinstall-package
ja-local-kb` 再测试。Windows 测试必须通过 `scripts/test-windows.ps1` 运行；
脚本会先同步当前源码，把 pytest 临时目录固定到所选运行根目录的
`tmp\pytest\`，复用 Vault 外的运行时 uv 缓存，并拒绝调用方覆盖
`--basetemp`。不得在任何 Obsidian Vault 内创建 pytest 缓存、临时目录或
隔离目录。

## 官方兼容依据

- OpenAI Embeddings API：
  <https://developers.openai.com/api/reference/resources/embeddings/methods/create>
- Qwen3 Embedding：<https://qwenlm.github.io/blog/qwen3-embedding/>
- SiliconFlow Embeddings API：
  <https://docs.siliconflow.cn/en/api-reference/embeddings/create-embeddings>
- SiliconFlow Rerank API：
  <https://docs.siliconflow.cn/cn/api-reference/rerank/create-rerank>
- Qwen3-Reranker-8B：
  <https://huggingface.co/Qwen/Qwen3-Reranker-8B>
- MCP Python SDK：<https://github.com/modelcontextprotocol/python-sdk>
- Obsidian 插件开发：<https://docs.obsidian.md/Plugins/Getting%20started/Build%20a%20plugin>