release: v0.15.0 — BM25符号搜索 / AppContext拆分 / Embedding多后端 / Health扩展 / 不变量CI

.github/workflows/ci.yml

@@ -102,3 +102,16 @@ jobs:
       - name: Install cargo-audit
         run: cargo install cargo-audit --locked
       - run: cargo audit
+
+  invariant:
+    name: Architecture Invariants
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Run invariant checks
+        shell: pwsh
+        run: |
+          git fetch origin main
+          tools/invariant-checks/run-checks.ps1

AGENTS.md

@@ -4,9 +4,9 @@
 
 > 它将本地数字资产的原始数据（代码库、笔记、Skill、工作流）编译为 AI 可决策的结构化情境，不负责思考，不负责执行，只负责感知、编码、持久化、检索。
 
-- **当前阶段**：阶段六 — v0.14.3 / MCP Python SDK 兼容修复 + repo.rs trait 化收尾
-- **当前版本**：v0.14.3 (`main@2867811`)
-- **已完成里程碑**：Registry God Object 完全拆解（10 子模块提取）+ 18 workspace crates 提取 + MCP Python SDK 1.16.0 兼容修复（NDJSON + null-id workaround）+ repo.rs crate:: 引用 13→9 + flaky 测试根治（RF-2.1/2.2/2.3）+ 许可证迁移（MIT → AGPL-3.0-or-later 双许可）
+- **当前阶段**：阶段六 → v0.15.0 已发布（CHANGELOG 已记录）；v0.16.0 进行中（Workspace 扩展 Phase 2）
+- **当前版本**：v0.15.0（CHANGELOG 已记录，`fix/project-health-cleanup@4e8d882`，**待合入 `main` 并打 tag**）
+- **已完成里程碑**：Registry God Object 完全拆解（10 子模块提取）+ 18 workspace crates 提取 + MCP Python SDK 1.16.0 兼容修复 + repo.rs trait 化 + flaky 测试根治（RF-2.1/2.2/2.3）+ 许可证迁移 + health 性能优化（-44%）+ index skip-embeddings + batch encoding 实验 + RF-6 清零 + 架构治理文档（ADR/不变量清单）+ Tantivy BM25 代码符号搜索（P1）+ AppContext 职责拆分 Phase 1/2（storage.rs 860→430 行）+ 架构不变量 CI（G5/T11/T12）+ Embedding 多后端（Candle/Ollama 配置切换, P3）+ EnvVersionCache 扩展（9 工具链检测, P4）
 - **核心方向**：让 Kimi CLI 在调用文件工具之前，先通过 devbase 获得"该读哪些文件、为什么读、它们之间的关系"
 - **本质分析**：见 `vault/99-Meta/devbase-essence-analysis-20260430.md` 与 `docs/architecture/redefinition.md`
 - **设计文档**：
@@ -207,6 +207,24 @@ grep -rn "unwrap()\|expect()\|panic!(" src/ \
 # 预期输出：空
 ```
 
+### 架构治理框架（Architecture Governance）
+
+> 参考：外部架构治理方法论（Kimi 会话 `e9f2965f-b949-46a5-9d7c-afd6d4d9232c`）
+
+**已制度化实践**：
+
+| 实践 | devbase 落地形式 | 文档位置 |
+|------|-----------------|---------|
+| ADR（架构决策记录） | ADR-001（单 crate defer）、ADR-002（batch encoding 回滚） | [`docs/architecture/adr-template.md`](docs/architecture/adr-template.md) |
+| 不变量清单（Invariants） | RF-1~RF-7 + 分层模块约束（T01–T12） | [`docs/architecture/invariants.md`](docs/architecture/invariants.md) |
+| 模块提取演习 | RF-7 的 5 个 `crate::` 引用阈值 + 已提取 18 workspace crates | 本文件 §RF-7 |
+| 三层摘要 | `crates/*/README.md` 要求：一句话 + 一页纸 + 深度链接 | 各 crate README |
+| 定期架构回顾 | 每次 Wave 结束时的架构审计（见 `docs/_audit/`） | `docs/_audit/2026-04-26-*.md` |
+
+**待增强**：
+- 三层摘要：部分已提取 crate 的 README 尚未达到"一页纸"标准
+- 定期架构回顾：当前按 Wave（功能迭代周期）触发，建议每 2–4 周增加一次纯架构 review（不看 feature 进度，只看不变量违反和隐式依赖）
+
 ---
 
 ## 技术债登记簿（Technical Debt Ledger）
@@ -216,13 +234,13 @@ grep -rn "unwrap()\|expect()\|panic!(" src/ \
 | 债项 | 严重 | 当前值 | 目标阈值 | 清理路径 | 引入 Wave |
 |---|---|---|---|---|---|
 | `main.rs` 上帝文件 | 🟢 | 548 行 | ≤1000 行 | 拆分为 `commands/simple.rs` + `commands/skill.rs` + `commands/workflow.rs` + `commands/limit.rs`；全部 22 个命令/子命令树已迁移 | ≤15 |
-| `init_db()` 全局路径 | 🟡 | `AppContext` 已集成到全部 commands/ 模块（22 个函数）；`main()` 通过 `AppContext` 分发配置 | 0 新增 | `StorageBackend` trait + `AppContext` 已奠基；`db_path`/`workspace_dir`/`index_path`/`backup_dir` 已统一；`init_db()` 调用点 grandfathered 待迁移 | ≤15 |
-| Tantivy+SQLite 双写一致性 | 🟡 | 无事务协调 | 补偿机制 | 设计 `sync_index_to_db()` 回滚或两阶段提交；或改为 SQLite FTS5 替代 Tantivy | 7 |
+| `init_db()` 全局路径 | 🟢 | `AppContext` 已集成到全部 commands/ 模块；`main()` 通过 `AppContext` 分发配置；`init_db()` 无外部调用 | 0 | 已完成：`StorageBackend` trait + `AppContext` 全面替代；`db_path`/`workspace_dir`/`index_path`/`backup_dir` 已统一 | ≤15 |
+| Tantivy+SQLite 双写一致性 | 🟡 | 无事务协调；**已添加反向检测**（`repair_tantivy_consistency` 现在检测 SQLite→Tantivy 缺失） | 补偿机制 | 长期：事务协调或 SQLite FTS5 替代；短期：反向检测 + 日志已落地（`fe14c81`） | 7 |
 | 主从表切换 | 🟢 | Phase 1 全部完成：`repos` 表已删除，entities 为唯一数据源 | `entities` 为第一公民 | Phase 2 类型系统开放（新增 entity_type 无需改表结构） | v0.12.0 |
 | vault/paper/workflow entities 缺口 | 🟢 | Stage C+D+E 全部完成：`vault_notes`/`papers`/`workflows` 表已删除，`skills` 保留（embedding BLOB） | 0 缺口 | — | v0.12.0 |
 | scan 路径排除 | 🟢 | `discover_repos` + `collect_tasks` 均支持 `scan.exclude_paths`；scan 和 sync 双阶段过滤 | 0 缺口 | 排除路径使用 `Path::starts_with` 组件级匹配，避免字符串前缀误杀；相对路径在 sync 场景（无 root）下被忽略 | v0.12.0 |
-| tree-sitter 编译成本 | 🟡 | ~15-20s | 可控 | 评估 `ccache` 或 grammar 预编译；或按需 feature-gate | 8 |
-| Feature flags 缺失 | 🟡 | 2 个可选 feature (tui, watch) | ≥3 (tui, watch, mcp) | `Cargo.toml` 已添加 `tui` + `watch` feature；ratatui/crossterm/notify 均为 optional；`--no-default-features` 编译通过 | ≤15 |
+| tree-sitter 编译成本 | 🟢 | ~15-20s grammar C compilation | 可控 | 已完成 feature-gate：`lang-rust`/`lang-python`/`lang-js-ts`/`lang-go` 四个 feature，默认全启，可选关闭减少编译；`--no-default-features` 编译通过 | 8 |
+| Feature flags 缺失 | 🟢 | 4 个可选 feature (tui, watch, mcp, embedding) | ≥3 | 已完成：`tui`/`watch`/`mcp`/`embedding` 均为 optional；`--no-default-features` 编译通过 | ≤15 |
 | `LOCALAPPDATA` 测试模式残留 | 🟢 | 0 处 | 0 | 全面废弃 `LOCALAPPDATA` 环境变量覆盖，统一为 `DEVBASE_DATA_DIR`；mcp/tests.rs 修复 cleanup 逻辑（remove_var 目标从 LOCALAPPDATA 修正为 DEVBASE_DATA_DIR） | 47 |
 
 **清偿原则**：
@@ -329,7 +347,7 @@ devbase 承载外部资源调度的抽象接口：
 - **短期**：devbase MCP 接口可封装外部 TEE 服务（如 Azure Confidential Computing）
 - **长期**：如需自建，新建 `clarity-tee` 或 `devbase-secure` 子项目
 
-## 当前阶段待办（v0.12.0 发布冲刺）
+## 当前阶段待办（v0.15.0 推进中）
 
 v0.11.3 已交付（tagged）。v0.12.0-alpha 全部功能已完成，进入发布治理阶段。
 
@@ -414,6 +432,15 @@ v0.11.3 已交付（tagged）。v0.12.0-alpha 全部功能已完成，进入发
 - 生成工具：`tools/embedding-provider/skills.py`（sentence-transformers `all-MiniLM-L6-v2`）
 - 激活路径：启动 Ollama + `devbase index <repo>` 生成 embedding，或配置远程 provider 于 `config.toml [embedding]` 段
 
+### 2026-05-04 索引性能实验记录
+
+**发现**：Candle CPU BERT `batch_size=32` forward 比 `rayon` 并行单条慢 **5.2×**（88s vs 16s）。
+- 根因：Candle CPU matmul 对大 padded batch 不友好；batch 内序列长度差异导致大量无效 padding token 计算。
+- **决策**：`generate_and_save_embeddings` 回滚到 `rayon::par_iter()` 单条编码；保留 `EmbeddingProvider::encode_batch` trait 方法供未来 GPU/ONNX provider。
+- **新增**：`devbase index <path> --skip-embeddings` 跳过 embedding 生成，纯符号/调用图索引从 ~16s 降至 ~250ms。
+
+**外部参考**：知识蒸馏 Pipeline 设计规格（六阶段：噪声过滤→语义分割→主题聚类→层级展开→可信度标注→结构化输出），来源见 `docs/_audit/2026-04-26-embedding-research.md` §2026-05-04 补充。该规格提出通过 devbase MCP 暴露 `devkit_knowledge_distill` 工具，与 Vault 系统形成输入-处理-输出闭环。状态：设计规格级，待验证后评估集成优先级。
+
 ## 上下文安全机制（Context Safety Mechanism）
 
 > 长期架构原则：在多 Agent / 子代理协作场景下，保证工作区状态的一致性与可恢复性。

CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.15.0] - 2026-05-04
+
+### Added
+
+- **P1: Tantivy BM25 代码符号搜索** — `search/symbol_index.rs`
+  - 独立 Schema (`repo_id`, `name`, `signature`, `file_path`, `line_start`)
+  - `keyword_search_symbols` 主路径走 Tantivy BM25，SQLite LIKE 回退
+  - 索引流程 `index.rs` 自动同步写入 symbol_index
+  - `StorageBackend` 扩展 `symbol_index_path()`（6 实现）
+- **P3: Embedding 多后端** — Candle (默认) + Ollama (配置切换)
+  - 新增 `OllamaProvider` (`ureq` HTTP `/api/embed`)
+  - `create_provider(backend, model, base_url, timeout)` 配置化创建
+  - `generate_query_embedding` 通过 `OnceLock` 懒加载配置化 provider
+  - 默认模型改为 `all-minilm` (384-dim，与 Candle 维度兼容)
+- **P4: Health 环境检测扩展** — `EnvVersionCache` 从 5 工具 → 9 工具
+  - 新增: `python`, `bun`, `zig`, `java`
+  - `get_tool_version` 支持 stderr fallback (Java 输出到 stderr)
+  - `fmt_version` 改进: Java 引号提取、Docker/Python 格式处理
+- **P5: 架构不变量自动化 CI** — `tools/invariant-checks/run-checks.ps1`
+  - G5: diff-only 检测新增生产代码 unwrap/expect/panic（排除 `#[cfg(test)]`）
+  - T11: 检测 `mcp/tools/*` 直接调用 `rusqlite::Connection`
+  - T12: 检测 `tui/render/*` 写入操作
+  - CI job `invariant-check` 加入 `.github/workflows/ci.yml`
+- **P2 Phase 1: AppContext 职责拆分** — 6 个 Client trait impl 迁出 `storage.rs`
+  - `scan.rs` / `health.rs` / `sync.rs` / `digest.rs` / `knowledge_engine/mod.rs` / `registry.rs`
+  - `storage.rs` 860 → 430 行 (-50%)
+  - 删除冗余 `conn_mut()`
+- **P2 Phase 2: 内联 SQL 下沉** — 新增 `registry/code_symbols.rs` + `registry/dead_code.rs`
+  - `CodeSymbolRow` / `DeadCodeRow` + 纯函数查询 (12 个单元测试)
+  - `RegistryClient` 退化为纯代理层
+
+### Changed
+
+- `EmbeddingConfig` 默认模型 `nomic-embed-text` → `all-minilm` (384-dim)
+- AGENTS.md 阶段描述更新: v0.14.3 → v0.15.0 推进中 → v0.15.0 全部完成
+
+### Fixed
+
+- **TTL 缓存负值 bug** (`97172ec`): `elapsed < ttl_seconds` → `elapsed >= 0 && elapsed < ttl_seconds`
+  - 防止系统时间回溯导致缓存永不过期
+- `crates/devbase-embedding/src/lib.rs` 遗留 unwrap 清零 (`encode_with_candle` → `ok_or`)
+
 ## [0.14.3] - 2026-05-05
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "devbase"
-version = "0.14.3"
+version = "0.15.0"
 edition = "2024"
 description = "Developer workspace database and knowledge-base manager"
 authors = ["juice094 <160722440+juice094@users.noreply.github.com>"]
@@ -14,11 +14,15 @@ name = "registry_bench"
 harness = false
 
 [features]
-default = ["tui", "mcp", "embedding"]
+default = ["tui", "mcp", "embedding", "lang-rust", "lang-python", "lang-js-ts", "lang-go"]
 tui = ["ratatui", "crossterm", "watch"]
 watch = ["notify"]
 mcp = []
 embedding = ["dep:devbase-embedding"]
+lang-rust = ["dep:tree-sitter-rust"]
+lang-python = ["dep:tree-sitter-python"]
+lang-js-ts = ["dep:tree-sitter-typescript"]
+lang-go = ["dep:tree-sitter-go"]
 
 [dependencies]
 clap = { version = "4", features = ["derive"] }
@@ -48,10 +52,10 @@ which = "7"
 dunce = "1"
 tokei = "14.0.0"
 tree-sitter = "0.26"
-tree-sitter-rust = "0.24"
-tree-sitter-python = "0.23"
-tree-sitter-typescript = "0.23"
-tree-sitter-go = "0.23"
+tree-sitter-rust = { version = "0.24", optional = true }
+tree-sitter-python = { version = "0.23", optional = true }
+tree-sitter-typescript = { version = "0.23", optional = true }
+tree-sitter-go = { version = "0.23", optional = true }
 serde_yaml = "0.9"
 regex = "1"
 # Extracted crates (zero internal coupling)
@@ -89,7 +93,7 @@ members = ["crates/*"]
 resolver = "2"
 
 [workspace.package]
-version = "0.14.3"
+version = "0.15.0"
 authors = ["juice094 <160722440+juice094@users.noreply.github.com>"]
 edition = "2024"
 license = "AGPL-3.0-or-later"

README.md

@@ -1,7 +1,7 @@
 # devbase
 
-[![Version](https://img.shields.io/badge/version-v0.14.3-blue)](https://github.com/juice094/devbase/releases)
-[![Tests](https://img.shields.io/badge/tests-390%20passed-brightgreen)](./AGENTS.md)
+[![Version](https://img.shields.io/badge/version-v0.15.0-blue)](https://github.com/juice094/devbase/releases)
+[![Tests](https://img.shields.io/badge/tests-490%2B%20passed-brightgreen)](./AGENTS.md)
 [![Clippy](https://img.shields.io/badge/clippy-0%20warnings-green)](./AGENTS.md)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-orange)](./LICENSE)
 [![Rust](https://img.shields.io/badge/rust-1.94%2B-9cf)](https://www.rust-lang.org)
@@ -283,19 +283,19 @@ TUI `[:]` 触发 embedding 语义搜索，失败自动降级为文本搜索。AI
 | v0.7.0 | ✅ 已发布 | NLQ 自然语言查询 + 智能同步建议 |
 | v0.8.0 | ✅ 已发布 | Workflow 子类型：Subworkflow / Parallel / Condition / Loop |
 | v0.9.0 | ✅ 已发布 | Loop Step 硬化 + 发布闭环 |
-| **v0.10.0** | **✅ 已发布** | **L3-L4 知识模型 + 工程健康维护（main.rs 拆分 / StorageBackend / feature flags）** |
-| **v0.11.0** | **✅ 已发布** | **AppContext Pool 化 + MCP 测试隔离 + CI 多线程** |
-| **v0.11.1** | **✅ 已发布** | **Flat ID 命名空间 + entities-first 写入反转** |
-| **v0.11.2** | **✅ 已发布** | **读路径全量迁移：所有 SELECT 切到 `entities`** |
-| **v0.11.3** | **✅ 已发布** | **`repos` 表删除，`entities` 成为唯一数据源（Phase 1 完成）** |
-| **v0.12.0-alpha** | **✅ 已发布** | **Phase 2 完成 (Stage A-E): entities 统一重构 + `.devbase-ignore` + managed-gate fail-safe 同步** |
-| **v0.13.0** | **✅ 已发布** | **Registry God Object 拆解：10 子模块提取为 free function；WorkspaceRegistry 退化为纯 facade** |
-| **v0.14.0** | **✅ 已发布** | **Workspace 拆分：6 个零耦合 crate 提取；MCP trait 化：`mcp/tools/repo.rs` `crate::` 引用 68→41** |
-| **v0.15.0** | **✅ 已发布** | **Sprint A/B/C：三维 embedding + Saga 一致性 + Agent 状态接口 + MCP Streaming（45 tools）** |
-| **v0.16.0** | **✅ 已发布** | **Workspace crate 第二批提取 + Windows debug 栈溢出修复** |
-| **v0.14.1** | **✅ 已发布** | **CLI JSON 输出补全 (`--json`/`--recalc`) + relations MCP 工具加固 + License headers + Vault Daily/Graph** |
-| **v0.14.2** | **✅ 已发布** | **health dirty 检测修复（排除 ignored 文件）+ scan 路径规范化 + syncthing-rust 识别修复 + experiment_log/CodeMetrics/ModuleGraph/CallGraph/DeadCode 提升为 Beta（48 tools: Stable 5 / Beta 40 / Experimental 3）** |
-| **v0.14.3** | **✅ 当前** | **Schema v30 code symbol attributes + dead-code 过滤增强 + init_db() 注入式改造（RF-1）+ Tantivy/SQLite 补偿扫描 + Feature flags（mcp / embedding）+ sccache 构建加速文档** |
+| v0.10.0 | ✅ 已发布 | L3-L4 知识模型 + 工程健康维护（main.rs 拆分 / StorageBackend / feature flags） |
+| v0.11.0 | ✅ 已发布 | AppContext Pool 化 + MCP 测试隔离 + CI 多线程 |
+| v0.11.1 | ✅ 已发布 | Flat ID 命名空间 + entities-first 写入反转 |
+| v0.11.2 | ✅ 已发布 | 读路径全量迁移：所有 SELECT 切到 `entities` |
+| v0.11.3 | ✅ 已发布 | `repos` 表删除，`entities` 成为唯一数据源（Phase 1 完成） |
+| v0.12.0 | ✅ 已发布 | Phase 2 完成（Stage A-E）：entities 统一重构 + `.devbase-ignore` + managed-gate fail-safe 同步 |
+| v0.13.0 | ✅ 已发布 | Registry God Object 拆解：10 子模块提取为 free function；WorkspaceRegistry 退化为纯 facade |
+| v0.14.0 | ✅ 已发布 | Workspace 拆分：6 个零耦合 crate 提取；MCP trait 化：`mcp/tools/repo.rs` `crate::` 引用 68→41 |
+| v0.14.1 | ✅ 已发布 | CLI JSON 输出补全 (`--json`/`--recalc`) + relations MCP 工具加固 + License headers + Vault Daily/Graph |
+| v0.14.2 | ✅ 已发布 | health dirty 检测修复（排除 ignored 文件）+ scan 路径规范化 + syncthing-rust 识别修复 + experiment_log/CodeMetrics/ModuleGraph/CallGraph/DeadCode 提升为 Beta（48 tools: Stable 5 / Beta 40 / Experimental 3） |
+| v0.14.3 | ✅ 已发布 | Schema v30 code symbol attributes + dead-code 过滤增强 + init_db() 注入式改造（RF-1）+ Tantivy/SQLite 补偿扫描 + Feature flags（mcp / embedding）+ sccache 构建加速文档 |
+| **v0.15.0** | **✅ 当前** | **P1 Tantivy BM25 代码符号搜索 + P2 AppContext 职责拆分（storage.rs 860→430 行）+ P3 Embedding 多后端（Candle + Ollama）+ P4 EnvVersionCache 扩展（9 工具链：含 python/bun/zig/java）+ P5 架构不变量自动化 CI（G5/T11/T12）** |
+| v0.16.0 | 📋 进行中 | Workspace 扩展 Phase 2：成员目标 8-10 个；以 `docs/ROADMAP.md` 阶段六规划为准 |
 
 ---