v1.3.13 - 修复已知问题

修复 / 硬化

跨端契约对齐（Win 侧翻回 Mac 语义）

• warmup 超时保活 handle：warmup timeout 不再 terminate 子进程，保留活 handle + warming_up=True，让 self-heal 后续探测 /health 200 消化 warming 状态（原先 120s+ warmup 慢机会被误杀）
• install → start chaining flag pattern：Win tray 复刻 Mac Swift startAfterInstallRequested 语义，install 成功后走 reconcile tick dispatch，避免 tray header-only install 后立即 CAS POST /start 导致抢跑
• Stop max_retries=3：hard failure 不再永远重试，达到上限抛 CRITICAL 保 pid/port 供人工介入
• cmdline adopt 归属判定：--model-id 支持 resolved 绝对路径（含空格 quoted / equals / space 三态匹配），修"自家进程被判为外人"
• _verify_kb_api_exe wmic → Get-CimInstance fallback：兼容 Windows 11 22H2+ wmic deprecated 默认关闭
• /v1/system/restart PS 5.1 ParseFile 预检：无 BOM UTF-8 脚本被 PS 5.1 按 ANSI 读会 parse fail 但 fire-and-forget Popen 拿不到 exit code → 现在启动前 ParseFile 预检，失败返 500 不假绿
• local-restart-direct.ps1 加 UTF-8 BOM：PS 5.1 硬要求

Bug fixes

• rebuild-vector-index 撞 "Qdrant 客户端不可用"：resume() 补 eager _ensure_client_and_collection
• LLM output token 截断
• 配置保存 + embedding 服务重启多轮修复

其他

• VERSION 文件加入 git 追踪，dev / build / installer 三处版本一致 CI 兜底（test_release_contract.py）
• 补齐 26 条 tray client 契约测试 + 契约类回归 pin

支持平台

macOS 13.0+ (Apple Silicon / Intel) · Windows 10+ · Linux (CLI)

安装

• macOS: 下载 KnowledgeBase-mac-direct-1.3.13.dmg，双击挂载，再双击里面的 Install.command —— 脚本自动装到 /Applications/KnowledgeBase 并打开菜单栏 App
• Windows: 下载 KnowledgeBase-Setup-1.3.13.exe 双击安装

Full changelog

v1.3.12...v1.3.13

v1.3.12 — Embedding 装完即用 + 读写稳定性

v1.3.12 — Embedding 装完即用 + 读写稳定性

主要更新

装机体验

• Mac / Windows 装完后自动拉起 Embedding 服务，无需手动干预
• Mac 菜单栏新增「启动 Embedding 服务」按钮，异常场景可一键恢复
• 修复长时间运行后 Web UI 打不开的问题

知识库读写

• 修复清空知识库（clear）后立刻搜索报 500 的问题
• 修复重建向量索引撞「Qdrant 客户端不可用」的问题
• Windows 通过 agent 集成清理知识库不再报错

兼容性

• 完整支持 Python 3.13
• 用户手册和文档同步更新

装机

macOS：下载 KnowledgeBase-mac-direct-1.3.12.dmg，双击后运行 Install.command。首次运行需在「系统设置 → 隐私与安全性」放行。

Windows：下载 KnowledgeBase-Setup-1.3.12.exe，双击安装。

升级

从旧版升级会自动 backup 现有 venv 和模型（保留使用），知识库数据（data/ 目录）完全保留。

校验

Mac dmg SHA-256: edfbc6243562f188b062474210fdcce3e5fd50b7805ef085ea53e0c3e1ac16d4
Win exe SHA-256: 9d6255d252eeeee780f1da0d036dede1dd40d87ac317fa7d2799ff62eeaae174

v1.3.11 — infinity ready 探针 + 单例池 lock 释放

---

bug 修复

bug A — infinity warmup 期间用户点重建被阻断

装机后 infinity 子进程 warmup 需要 30-60 秒才 LISTEN，期间用户立刻点托盘"重建向量索引"，会因 strict 模式第一条 chunk embedding connection refused 而立即终止，旧索引备份同时被抹掉。

修复：

• rebuild_runner.start 前置 embedding 就绪探针（默认 HTTP /health 2s 超时）
• 探针失败抛 EmbeddingNotReady，runner 不进 RUNNING / 不备份 / 不置 maintenance
• 接口 catch 转 503 + Retry-After: 5，菜单栏 App case 503 弹「请等 banner ready」明确提示

bug B — PUT /v1/system/config 后旧 VectorIndex 不释放 qdrant 锁

mode / model 切换触发 _invalidate_repo_singletons 后，旧 VectorIndex 仍持有 qdrant_local 的 portalocker 文件锁，新 VectorIndex 在同进程内 QdrantClient(path=...) 拿锁失败 → 静默 enabled=False 退化为关键词检索，用户感知不到向量索引已坏。

修复：

• repo 单例池从 lru_cache 改成 dict + Lock，invalidate 时遍历旧实例 vector_index.pause() 释放锁
• _repo_singleton_*.cache_clear 保留作为指向 invalidate 的 shim，既有测试无需改

测试覆盖

• 新增单测 8 个（rebuild_runner probe + 单例池 invalidate），全过
• 全套测试 412/413（唯一 fail 是与本次无关的预存 skill_sync drift）
• 装机端到端验证：1.3.11 dmg 装机后立刻点重建 → 503 友好提示；等 ready 再点 → 408 chunk rebuild 完成 + 完成通知；问答 query 真走 infinity /embeddings 200

下载

• macOS: KnowledgeBase-mac-direct-1.3.11.dmg（53MB，Apple Silicon / Intel 通用）

---

v1.3.10 — 首次开源

首次开源 / Initial Open Source Release

面向工程研发的本地知识记忆系统，让 Claude Code / Codex 在编码时检索历史决策、排障记录和工程规范。

包含

• ✅ FastAPI + SQLite + Qdrant 本地存储
• ✅ BM25 + 向量混合检索 + heading-aware Markdown 分块
• ✅ 嵌入服务三选一（内置 infinity 子进程 / 外部 OpenAI 兼容 / 关键词降级）
• ✅ MCP server + skill 接入 Claude Code / Codex
• ✅ macOS 直装版（DMG 双击即用）
• ✅ 数据备份恢复 + 升级保护

下载

• macOS：KnowledgeBase-mac-direct-1.3.10.dmg（见下方 Assets）
• Windows：签名安装包构建中，详见 README.md

快速接入 Claude Code / Codex

装好后让 AI 读 agent-integration/安装说明.md 自助接入 MCP + Skill，零手工配置。