From e59930bb6fd7946f4d3b9995437fe69b7e51563f Mon Sep 17 00:00:00 2001 From: juice094 Date: Tue, 16 Jun 2026 10:55:13 +0800 Subject: [PATCH 1/3] feat(eval): add vault search pilot evaluation example - Add examples/vault_search_eval.rs using agri-paper/main.md as corpus - Split paper into 14 vault notes, build Tantivy index, run 8 labeled queries - Compare Tantivy BM25, linear substring scan, and filename/title matching - Output Precision@k, Recall@k, MRR, and latency - Set Tantivy query parser to conjunction-by-default so multi-keyword vault search uses AND semantics, matching the fallback behavior --- examples/vault_search_eval.rs | 421 ++++++++++++++++++++++++++++++++++ src/search.rs | 3 +- 2 files changed, 423 insertions(+), 1 deletion(-) create mode 100644 examples/vault_search_eval.rs diff --git a/examples/vault_search_eval.rs b/examples/vault_search_eval.rs new file mode 100644 index 0000000..e5d0af9 --- /dev/null +++ b/examples/vault_search_eval.rs @@ -0,0 +1,421 @@ +// SPDX-License-Identifier: AGPL-3.0-or-later +// Copyright (c) 2026 juice094 +//! +//! Pilot evaluation of `devkit_vault_search` on the agri-paper dataset. +//! +//! Splits `C:\Users\22414\dev\agri-paper\paper\main.md` into vault notes, +//! indexes them with Tantivy, and compares three retrieval paths: +//! +//! 1. Tantivy BM25 (`search_vault_at`) +//! 2. Linear substring scan over note title/content/tags +//! 3. Filename/title keyword matching +//! +//! Metrics: Precision@k, Recall@k, MRR, latency. + +use std::path::{Path, PathBuf}; +use std::time::Instant; + +use devbase::registry::WorkspaceRegistry; +use devbase::storage::StorageBackend; + +const PAPER_PATH: &str = r"C:\Users\22414\dev\agri-paper\paper\main.md"; + +/// Isolated storage backend for the evaluation example. +struct EvalStorageBackend { + dir: tempfile::TempDir, +} + +impl EvalStorageBackend { + fn new() -> anyhow::Result { + Ok(Self { dir: tempfile::tempdir()? }) + } +} + +impl StorageBackend for EvalStorageBackend { + fn db_path(&self) -> anyhow::Result { + Ok(self.dir.path().join("registry.db")) + } + + fn workspace_dir(&self) -> anyhow::Result { + let ws = self.dir.path().join("workspace"); + std::fs::create_dir_all(ws.join("vault"))?; + std::fs::create_dir_all(ws.join("assets"))?; + Ok(ws) + } + + fn index_path(&self) -> anyhow::Result { + Ok(self.dir.path().join("search_index")) + } + + fn symbol_index_path(&self) -> anyhow::Result { + Ok(self.dir.path().join("symbol_index")) + } + + fn backup_dir(&self) -> anyhow::Result { + let backup = self.dir.path().join("backups"); + std::fs::create_dir_all(&backup)?; + Ok(backup) + } +} + +#[derive(Debug, Clone)] +struct Note { + id: String, + title: String, + content: String, +} + +fn slugify(s: &str) -> String { + s.to_lowercase() + .replace(|c: char| !c.is_alphanumeric() && c != ' ', " ") + .split_whitespace() + .collect::>() + .join("-") +} + +/// Split a Markdown document into top-level sections by `# Heading`. +fn split_markdown(source: &str) -> Vec<(String, String)> { + let mut sections = Vec::new(); + let mut current_title = String::from("frontmatter"); + let mut current_body = String::new(); + + for line in source.lines() { + if let Some(title) = line.strip_prefix("# ") { + if !current_body.trim().is_empty() { + sections.push((current_title.clone(), current_body.clone())); + } + current_title = title.split("{#").next().unwrap_or(title).trim().to_string(); + current_body = line.to_string(); + } else { + current_body.push('\n'); + current_body.push_str(line); + } + } + + if !current_body.trim().is_empty() { + sections.push((current_title, current_body)); + } + + sections +} + +fn prepare_notes(vault_dir: &Path) -> anyhow::Result> { + let source = std::fs::read_to_string(PAPER_PATH)?; + let sections = split_markdown(&source); + + let mut notes = Vec::new(); + for (raw_title, body) in sections { + let slug = slugify(&raw_title); + let id = format!("{}.md", slug); + let path = vault_dir.join(&id); + + let tags = extract_tags(&raw_title); + let frontmatter = + format!("---\ntitle: {}\ntags: [{}]\n---\n\n", raw_title, tags.join(", ")); + std::fs::write(&path, format!("{}{}", frontmatter, body))?; + + notes.push(Note { + id, + title: raw_title, + content: body, + }); + } + + Ok(notes) +} + +fn extract_tags(title: &str) -> Vec { + let lower = title.to_lowercase(); + let mut tags = Vec::new(); + for (keyword, tag) in [ + ("introduction", "intro"), + ("related work", "related-work"), + ("theoretical", "theory"), + ("algorithm", "algorithm"), + ("experiments", "experiments"), + ("results", "results"), + ("discussion", "discussion"), + ("conclusion", "conclusion"), + ("rag", "rag"), + ("retrieval", "retrieval"), + ("cognitive load", "cognitive-load"), + ] { + if lower.contains(keyword) { + tags.push(tag.to_string()); + } + } + tags +} + +#[derive(Debug, Clone)] +struct Query { + id: String, + text: String, + relevant: Vec, +} + +fn queries() -> Vec { + vec![ + Query { + id: "q1".into(), + text: "retrieval depth capacity".into(), + relevant: vec![ + "introduction.md".into(), + "theoretical-framework.md".into(), + "experimental-results.md".into(), + "intermediate-k-probing-results.md".into(), + "detailed-delta-k-breakdown.md".into(), + ], + }, + Query { + id: "q2".into(), + text: "ACR-Select".into(), + relevant: vec![ + "acr-select-adaptive-context-retrieval.md".into(), + "theoretical-framework.md".into(), + ], + }, + Query { + id: "q3".into(), + text: "cognitive load".into(), + relevant: vec![ + "theoretical-framework.md".into(), + "related-work.md".into(), + "discussion.md".into(), + ], + }, + Query { + id: "q4".into(), + text: "agricultural benchmark".into(), + relevant: vec![ + "experimental-setup.md".into(), + "experimental-results.md".into(), + "introduction.md".into(), + ], + }, + Query { + id: "q5".into(), + text: "Adaptive-RAG".into(), + relevant: vec![ + "related-work.md".into(), + "acr-select-adaptive-context-retrieval.md".into(), + ], + }, + Query { + id: "q6".into(), + text: "format collapse".into(), + relevant: vec!["theoretical-framework.md".into(), "experimental-results.md".into()], + }, + Query { + id: "q7".into(), + text: "marginal gain".into(), + relevant: vec![ + "acr-select-adaptive-context-retrieval.md".into(), + "theoretical-framework.md".into(), + ], + }, + Query { + id: "q8".into(), + text: "limitations".into(), + relevant: vec!["discussion.md".into(), "conclusion.md".into()], + }, + ] +} + +fn rank_tantivy( + index_path: &Path, + query: &str, + limit: usize, +) -> anyhow::Result> { + Ok(devbase::search::search_vault_at(index_path, query, limit)?) +} + +fn rank_linear_scan(notes: &[Note], query: &str, limit: usize) -> Vec<(String, f32)> { + let keywords: Vec = query.split_whitespace().map(|s| s.to_lowercase()).collect(); + + let mut scored: Vec<(String, f32)> = notes + .iter() + .filter_map(|n| { + let hay = format!( + "{} {} {}", + n.title.to_lowercase(), + n.id.to_lowercase(), + n.content.to_lowercase() + ); + let matches = keywords.iter().filter(|kw| hay.contains(kw.as_str())).count(); + if matches == keywords.len() { + Some((n.id.clone(), matches as f32)) + } else { + None + } + }) + .collect(); + + // Tie-break by id for stability. + scored.sort_by(|a, b| { + b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal).then(a.0.cmp(&b.0)) + }); + scored.truncate(limit); + scored +} + +fn rank_filename_match(notes: &[Note], query: &str, limit: usize) -> Vec<(String, f32)> { + let keywords: Vec = query.split_whitespace().map(|s| s.to_lowercase()).collect(); + + let mut scored: Vec<(String, f32)> = notes + .iter() + .filter_map(|n| { + let hay = format!("{} {}", n.title.to_lowercase(), n.id.to_lowercase()); + let matches = keywords.iter().filter(|kw| hay.contains(kw.as_str())).count(); + if matches > 0 { + Some((n.id.clone(), matches as f32)) + } else { + None + } + }) + .collect(); + + scored.sort_by(|a, b| { + b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal).then(a.0.cmp(&b.0)) + }); + scored.truncate(limit); + scored +} + +#[derive(Default, Debug)] +struct Metrics { + precision_at_5: f64, + precision_at_10: f64, + recall_at_5: f64, + recall_at_10: f64, + mrr: f64, + latency_ms: f64, +} + +fn evaluate( + name: &str, + queries: &[Query], + _note_ids: &[String], + rank_fn: &mut dyn FnMut(&Query) -> anyhow::Result>, +) -> Metrics { + let mut total = Metrics::default(); + let count = queries.len() as f64; + + for q in queries { + let start = Instant::now(); + let ranked = match rank_fn(q) { + Ok(r) => r, + Err(e) => { + eprintln!("[{}] query {} failed: {}", name, q.id, e); + continue; + } + }; + total.latency_ms += start.elapsed().as_secs_f64() * 1000.0; + + let relevant: std::collections::HashSet = q.relevant.iter().cloned().collect(); + + for k in [5usize, 10usize] { + let top_k: std::collections::HashSet = ranked.iter().take(k).cloned().collect(); + let hits = relevant.intersection(&top_k).count(); + let p = hits as f64 / k as f64; + let r = if relevant.is_empty() { + 0.0 + } else { + hits as f64 / relevant.len() as f64 + }; + if k == 5 { + total.precision_at_5 += p; + total.recall_at_5 += r; + } else { + total.precision_at_10 += p; + total.recall_at_10 += r; + } + } + + let rr = ranked + .iter() + .position(|id| relevant.contains(id)) + .map(|pos| 1.0 / (pos + 1) as f64) + .unwrap_or(0.0); + total.mrr += rr; + } + + total.precision_at_5 /= count; + total.precision_at_10 /= count; + total.recall_at_5 /= count; + total.recall_at_10 /= count; + total.mrr /= count; + total.latency_ms /= count; + + total +} + +fn main() -> anyhow::Result<()> { + println!("=== devbase vault search pilot evaluation ==="); + println!("dataset: {}", PAPER_PATH); + + let storage = EvalStorageBackend::new()?; + let workspace_dir = storage.workspace_dir()?; + let vault_dir = workspace_dir.join("vault"); + let index_path = storage.index_path()?; + + println!("\n[1/4] Preparing vault notes..."); + let notes = prepare_notes(&vault_dir)?; + let note_ids: Vec = notes.iter().map(|n| n.id.clone()).collect(); + println!(" {} notes written to {}", notes.len(), vault_dir.display()); + + println!("\n[2/4] Initializing registry and scanning vault..."); + let mut conn = WorkspaceRegistry::init_db_with(&storage)?; + devbase::vault::scanner::scan_vault(&mut conn, Some(&vault_dir))?; + println!(" scan complete"); + + println!("\n[3/4] Building Tantivy index..."); + devbase::search::index_vault_notes_at(&conn, &index_path)?; + // Allow Windows to release handles. + std::thread::sleep(std::time::Duration::from_millis(500)); + println!(" index built at {}", index_path.display()); + + println!("\n[4/4] Evaluating retrieval methods..."); + let queries = queries(); + println!(" {} queries defined\n", queries.len()); + + let tantivy = evaluate("Tantivy", &queries, ¬e_ids, &mut |q: &Query| { + Ok(rank_tantivy(&index_path, &q.text, 10)?.into_iter().map(|(id, _)| id).collect()) + }); + + let notes_for_linear = notes.clone(); + let linear = evaluate("Linear", &queries, ¬e_ids, &mut |q: &Query| { + Ok(rank_linear_scan(¬es_for_linear, &q.text, 10) + .into_iter() + .map(|(id, _)| id) + .collect()) + }); + + let notes_for_filename = notes.clone(); + let filename = evaluate("Filename", &queries, ¬e_ids, &mut |q: &Query| { + Ok(rank_filename_match(¬es_for_filename, &q.text, 10) + .into_iter() + .map(|(id, _)| id) + .collect()) + }); + + println!( + "{:<12} {:>8} {:>8} {:>8} {:>8} {:>8} {:>10}", + "Method", "P@5", "P@10", "R@5", "R@10", "MRR", "Latency(ms)" + ); + println!("{}", "-".repeat(72)); + for (name, m) in [("Tantivy", tantivy), ("Linear", linear), ("Filename", filename)] { + println!( + "{:<12} {:>8.3} {:>8.3} {:>8.3} {:>8.3} {:>8.3} {:>10.3}", + name, + m.precision_at_5, + m.precision_at_10, + m.recall_at_5, + m.recall_at_10, + m.mrr, + m.latency_ms + ); + } + + Ok(()) +} diff --git a/src/search.rs b/src/search.rs index 5d11e25..eed86e2 100644 --- a/src/search.rs +++ b/src/search.rs @@ -299,7 +299,8 @@ fn search_with_reader( let tags = schema.get_field("tags")?; let doc_type_f = schema.get_field("doc_type")?; - let query_parser = QueryParser::for_index(index, vec![title, content, tags]); + let mut query_parser = QueryParser::for_index(index, vec![title, content, tags]); + query_parser.set_conjunction_by_default(); let text_query = query_parser.parse_query(query_str)?; // Build combined query: text_query AND doc_type:filter (if specified) From 443c71050de628b257bbe4609e19db4344f03d8a Mon Sep 17 00:00:00 2001 From: juice094 Date: Thu, 25 Jun 2026 10:48:59 +0800 Subject: [PATCH 2/3] feat: cross-client skill sync with --target flag - Add sync_adapter module with SkillSyncAdapter trait + 5 adapters (ClarityJson, KimiCli, ClaudeCode, Codex, Claw) - skill sync now supports --target ... (all|clarity|claude-code|codex|kimi|claw) - Refactor sync_skills_to_plans into DB-fetch + plugin-friendly sync_skills_to_plans_with_skills - Fix skill import nested tokio runtime panic: use std::thread::spawn + new Runtime instead of block_on - Make SkillSource trait Send + Sync for cross-thread safety - Add skillopt-sleep-kimi skill + skillopt-devbase-integration vault doc Co-Authored-By: Claude --- AGENTS.md | 1 + CHANGELOG.md | 3 + CLAUDE.md | 222 +++++++++++++++++++ skills/skillopt-sleep-kimi/SKILL.md | 109 ++++++++++ src/commands/skill.rs | 81 +++++-- src/main.rs | 3 + src/skill_runtime/clarity_sync.rs | 53 ++++- src/skill_runtime/mod.rs | 1 + src/skill_runtime/sync_adapter.rs | 317 ++++++++++++++++++++++++++++ 9 files changed, 770 insertions(+), 20 deletions(-) create mode 100644 CLAUDE.md create mode 100644 skills/skillopt-sleep-kimi/SKILL.md create mode 100644 src/skill_runtime/sync_adapter.rs diff --git a/AGENTS.md b/AGENTS.md index cf50fa7..5798991 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -472,6 +472,7 @@ CI 通过 `scripts/invariant-checks/run-checks.ps1` 检测 G5 / T11 / T12 / READ - 入口脚本支持 `py`、`sh`、`ps1`、`js` 或二进制。 - 命令：`skill discover`、`skill run`、`skill install`、`skill publish`、`skill sync`。 - 评分：`success_rate`、`usage_count`、`rating`（0-5）。 +- 跨客户端 sync：`skill sync --target ...`，支持 `all` / `clarity` / `kimicli` / `claude-code` / `codex` / `claw`。详见 `vault/99-Meta/skillopt-devbase-integration.md`。 ### Workflow diff --git a/CHANGELOG.md b/CHANGELOG.md index 14d1ae5..4d56014 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,13 +17,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `devkit_document_convert` — Experimental tier MCP tool，PDF/PPTX → Markdown 转换（`pdftotext` / `python-pptx` 流水线），含 frontmatter 质量标注 - **Vault Tantivy 全文搜索** — `devkit_vault_search` 优先使用 BM25（`search_vault_at`），空结果/失败时回退到内存扫描；`run_index_with_progress` 在索引仓库时同步 `reindex_vault_with_writer` 写入同一 Tantivy 段 - **Criterion vault benchmark 基线** — 新增 `benches/vault_bench.rs`（`reindex_vault` 50/200 笔记，`search_vault` 单/多关键词 50/200 笔记），保存 baseline `v0.20.1` +- **跨客户端 Skill Sync 基础设施** — `SkillSyncAdapter` trait + `ClarityJsonAdapter` / `KimiCliAdapter` / `ClaudeCodeAdapter` / `CodexAdapter` / `ClawAdapter`；`devbase skill sync --target ...` 支持 `all` 同时输出 clarity/kimicli/claude-code/codex/claw 格式 - Stable 工具 invocation 测试补全：`devkit_query_repos`、`devkit_vault_search`（覆盖 Tantivy 路径）、`devkit_vault_read`、`devkit_status`、`devkit_workflow_list`、`devkit_index` - `seed_repo()` 轻量测试 helper（仅插入 `entities` 表，无副作用） +- 新增 Vault 集成记录：`workspace/vault/99-Meta/skillopt-devbase-integration.md` ### Fixed - `mcp/tools/document_convert.rs` 原始字符串定界符修复（`r###"` 避免与 Python f-string `"##` 冲突） - `cleanup_extracted_text` 单元测试期望值与实现语义对齐（保留最多 2 个连续空行） +- `skill import` 在 async runtime 中调用 `tokio::block_on` 导致的嵌套 runtime panic：改为 `std::thread::spawn` + 新建 `tokio::runtime::Runtime` 执行 `SkillSource::fetch()` ### Changed diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f6d5851 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,222 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +devbase is a Rust workspace (edition 2024, Rust 1.95+) that compiles a developer's local workspace (Git repos, notes, skills, workflows) into structured context consumable by AI agents. It exposes 71 MCP tools over stdio, provides a ratatui terminal dashboard, and maintains a local SQLite registry with Tantivy BM25 + vector search. + +**Primary dev platform**: Windows 11 (CI runs on `windows-latest`). Linux/macOS are community-supported. + +**License**: AGPL-3.0-or-later / dual-licensed commercial. New source files must include the SPDX header. + +--- + +## Build, Test, and Lint + +### Core commands +```bash +# Full build (release) +cargo build --release + +# Run all tests (lib + integration + examples + bins) +cargo test --all-targets + +# Run a specific test (note: .cargo/config.toml pins RUST_TEST_THREADS=1 locally) +cargo test -- --test-threads=1 --nocapture + +# Lint (zero warnings enforced in CI) +cargo clippy --all-targets -D warnings + +# Format check +cargo fmt --check +``` + +### Feature flags +- **Default**: `tui`, `mcp`, `lang-rust`, `lang-python`, `lang-js-ts`, `lang-go` +- **Optional**: `embedding` (Candle/Ollama backends), `greptimedb`, `watch` +- Build without TUI/MCP: `cargo build --no-default-features` + +### Workspace crates +The `crates/` directory holds 12 extracted sub-crates (e.g., `devbase-registry`, `devbase-vault-wikilink`, `devbase-workflow-model`). Test or build a single crate: +```bash +cargo test -p devbase-registry +cargo build -p devbase-core-types +``` + +### Local CI shortcut +```powershell +scripts/ci-local.ps1 # Windows +scripts/ci-local.sh # Linux/macOS +``` + +--- + +## High-Level Architecture + +### Three layers +1. **Application/Protocol** — CLI (`commands/`), TUI (`tui/`), MCP Server (`mcp/`) +2. **Semantic/Knowledge** — Registry (`registry/`), Search (`search/`), Knowledge Engine (`knowledge_engine/`), Vault (`vault/`), Workflow (`workflow/`), Skill Runtime (`skill_runtime/`) +3. **Physical/Storage** — SQLite WAL (`registry.db`), Tantivy index, Git (git2), filesystem + +### Entry points +- **`src/main.rs`** — CLI only; delegates to `commands/` submodules. Hard ceiling: <1000 lines (RF-4). +- **`src/lib.rs`** — Exports all 30+ modules; the binary is a thin wrapper. + +### Key architectural patterns + +#### MCP Tool trait +All 71 tools implement `McpTool` in `src/mcp/mod.rs`: +```rust +pub trait McpTool: Send + Sync + Clone { + fn name(&self) -> &'static str; + fn schema(&self) -> serde_json::Value; + async fn invoke(&self, args: serde_json::Value, ctx: &mut AppContext) -> anyhow::Result; + async fn invoke_stream(...) -> anyhow::Result>; +} +``` +Tools are registered in two places: +- `src/mcp/tools/mod.rs` — module declarations and `pub use` +- `src/mcp/mod.rs` — `McpToolEnum` variant + `handle_request` routing + +#### Storage abstraction +`StorageBackend` trait (`src/storage.rs`) abstracts DB path, workspace dir, and index path. `AppContext` holds a `dyn StorageBackend` and provides `connection() -> rusqlite::Connection`. This enables hermetic testing with injected temp paths. + +#### Registry & Schema migrations +- SQLite WAL mode, `PRAGMA user_version` drives migrations. +- `src/registry/migrate.rs` — `CURRENT_SCHEMA_VERSION = 36`; sequential migration functions. +- `src/registry/test_helpers.rs` — `SCHEMA_DDL` defines the in-memory schema for tests. +- **Critical**: any schema change must update **both** `migrate.rs` **and** `test_helpers.rs` `SCHEMA_DDL` (RF-3). +- Migrations must call `backup::auto_backup_before_migration()` before altering schema. + +#### Hybrid search +- **BM25**: Tantivy (`src/search/`) for full-text over code symbols and vault notes. +- **Vector**: SQLite BLOB + custom `cosine_similarity` UDF (`src/registry/migrate.rs`); zero ML runtime dependency in default build. +- Orchestrated in `src/search/hybrid.rs`. + +#### Workflow engine +YAML-based DAG executor (`src/workflow/`). 5 step types: `skill`, `subworkflow`, `parallel`, `condition`, `loop`. Parsed into `workflow-model` crate, scheduled topologically, variables interpolated via `workflow-interpolate` crate. + +#### Vault / PARA notes +Markdown notes with YAML frontmatter, wikilinks (`[[note]]`, `[[note#heading]]`, `[[note#^block-id]]`). Stored in workspace `vault/` under PARA folders (`00-Inbox`, `01-Projects`, `02-Areas`, `03-Resources`, `04-Archives`, `99-Meta`). BFS graph traversal for backlinks (`src/vault/backlinks.rs`). + +#### Skill runtime lifecycle +Discovery (`skill_runtime/discover.rs`) → Install → Execute (`executor.rs`) → Score (`scoring.rs`) → Publish (`publish.rs`). `SKILL.md` frontmatter parsed by `devbase-skill-runtime-parser`. Context-aware execution injects `DEVBASE_ACTIVE_CONTEXT` env var. + +#### Sync engine +`src/sync/orchestrator.rs` coordinates batch sync operations. `sync_protocol.rs` and `devbase-sync-protocol` crate define version-vector directory sync. Syncthing integration lives in `devbase-syncthing-client`. + +--- + +## Architecture Guardrails (RF Rules) + +These are enforced in CI via `scripts/invariant-checks/run-checks.ps1`. A violation is a blocking failure. + +| Rule | Summary | +|------|---------| +| **RF-1** | Dependency injection over global state. No new `dirs::data_local_dir()` / `std::env::var_os` hard-coding. | +| **RF-2** | Hermetic testing. No `std::env::set_var` in tests. Use `tempfile` + injected `StorageBackend`. Tantivy/SQLite FS tests must be serialized. | +| **RF-3** | `SCHEMA_DDL` and `migrate.rs` must stay atomically in sync. | +| **RF-4** | `main.rs` ≤ 1000 lines; CLI commands live in `commands/`. | +| **RF-5** | No cyclic `crate::` dependencies between modules. | +| **RF-6** | **Zero** `unwrap()` / `expect()` / `panic!()` in production code (outside `#[cfg(test)]`). | +| **RF-7** | New modules with >5 internal `crate::` refs cannot be extracted to workspace crates. Re-export files (`src/symbol_links.rs`, etc.) are `RE-EXPORT ONLY`. | + +**Additional tiered checks** (from `run-checks.ps1`): +- **T11**: `mcp/tools/*.rs` must not use `rusqlite::Connection` directly. Known exceptions: `repo.rs`, `brief.rs`, `impact.rs`. +- **T12**: `tui/render/` must be pure consumer — no `.execute(`, `.prepare(`, `registry::save/insert/update/delete`. + +--- + +## Testing Conventions + +### Test helpers +`src/test_utils.rs` provides: +- `temp_db()` — in-memory SQLite connection with full schema +- `fixture_repo(id, path)` / `fixture_repo_with_tags(...)` — minimal `RepoEntry` + +### `git2` testing requirements (RF-2.3) +- Always use `git2::Signature::now("Test", "test@example.com")` instead of `repo.signature()` (CI has no global git identity). +- Always `repo.set_head("refs/heads/main")` and commit to `"refs/heads/main"`; default branch varies by platform. + +### Path comparison (RF-2.2) +`TempDir` may return short filenames (`TEMP~1`) while `dunce::canonicalize` returns long filenames. Normalize **both** sides before comparing paths in tests. + +### Running tests +Current test count: **605** passed / 7 ignored (from `cargo test --workspace -- --list`). + +Local `.cargo/config.toml` sets `RUST_TEST_THREADS = "1"`. CI uses `--test-threads=4`. If you encounter flaky SQLite/Tantivy tests locally, reduce threads: +```bash +cargo test -- --test-threads=1 +``` + +--- + +## Adding an MCP Tool (Standard Path) + +1. Create `src/mcp/tools/.rs` +2. Implement `McpTool` trait +3. Register in `src/mcp/tools/mod.rs` (`pub mod` + `pub use`) +4. Add variant to `McpToolEnum` in `src/mcp/mod.rs` +5. Add routing arm in `src/mcp/mod.rs` `handle_request` +6. Add unit tests in `src/mcp/tests.rs` +7. Update README Tool matrix and `AGENTS.md` tool count + +**All state-changing tools must be idempotent** — use `ON CONFLICT ... DO UPDATE` or equivalent upsert logic. + +--- + +## Adding a Schema Migration + +1. Add migration function in `src/registry/migrate.rs` (sequential version block) +2. Use `ALTER TABLE ... ADD COLUMN` (SQLite limitation) +3. Call `backup::auto_backup_before_migration()` at the start +4. Update `CURRENT_SCHEMA_VERSION` +5. Mirror changes into `src/registry/test_helpers.rs` `SCHEMA_DDL` +6. Update `AGENTS.md` schema version number + +--- + +## Commit Convention + +Conventional Commits: `feat(mcp):`, `fix(registry):`, `refactor(search):`, `docs:`, `perf:`, `test:`. + +Pre-commit gate (enforced by CI): +```bash +cargo test --all-targets +cargo clippy --all-targets -D warnings +cargo fmt --check +``` + +--- + +## Important Files and Directories + +| Path | Purpose | +|------|---------| +| `src/main.rs` | CLI entry (thin wrapper) | +| `src/lib.rs` | Public module exports | +| `src/commands/` | CLI subcommand implementations | +| `src/mcp/mod.rs` | MCP server, `McpTool` trait, tool routing | +| `src/mcp/tools/mod.rs` | Tool module registry | +| `src/registry/migrate.rs` | Schema migrations, `CURRENT_SCHEMA_VERSION` | +| `src/registry/test_helpers.rs` | `SCHEMA_DDL`, in-memory test fixtures | +| `src/storage.rs` | `StorageBackend` trait, `AppContext` | +| `src/search/hybrid.rs` | BM25 + vector hybrid search orchestration | +| `src/workflow/executor.rs` | YAML workflow DAG executor | +| `src/vault/backlinks.rs` | Wikilink BFS graph traversal | +| `crates/` | 12 workspace sub-crates (zero internal coupling) | +| `scripts/invariant-checks/run-checks.ps1` | CI architecture invariant checks | +| `.cargo/config.toml` | Local cargo config (`RUST_TEST_THREADS=1`) | +| `rustfmt.toml` | `edition = "2024"`, `max_width = 100` | + +--- + +## Data Locations (Runtime) + +- **Registry DB**: `%LOCALAPPDATA%/devbase/registry.db` (SQLite, WAL mode) +- **Workspace**: `%LOCALAPPDATA%/devbase/workspace/` (vault notes, assets, repo manifests) +- **Config**: `~/.config/devbase/config.toml` (credentials, preferences) +- **Index**: Tantivy indices under workspace dir + +These paths are never committed; `.gitignore` covers `*.db`, `.devbase/`, `.env*`, `*.local.toml`. diff --git a/skills/skillopt-sleep-kimi/SKILL.md b/skills/skillopt-sleep-kimi/SKILL.md new file mode 100644 index 0000000..43fa936 --- /dev/null +++ b/skills/skillopt-sleep-kimi/SKILL.md @@ -0,0 +1,109 @@ +--- +name: skillopt-sleep-kimi +version: "1.0.0" +description: > + Use when the user wants their Kimi CLI agent to self-improve from past usage, + asks about a nightly/offline "sleep" or "dream" cycle, memory/skill consolidation, + or says things like "make my agent better the more I use it", "review my past sessions", + "learn my preferences", "consolidate what you learned", "run the sleep cycle", + or wants to schedule offline self-optimization. +author: devbase-team +tags: [skillopt, self-improvement, memory, kimicli, sleep-cycle] +skill_type: custom +inputs: + - name: scope + type: string + description: Scope of the sleep cycle (current-project | all) + default: "current-project" + required: false + - name: backend + type: string + description: Backend for offline replay (mock | local | remote) + default: "mock" + required: false +outputs: + - name: report + type: markdown + description: Summary of harvested sessions, mined tasks, and staged proposals +--- + +# SkillOpt-Sleep for Kimi CLI: offline self-evolution + +This skill gives the user's Kimi CLI agent a **sleep cycle**. While the user is +offline (or on demand), it reviews real past sessions, re-runs recurring tasks, +and consolidates what it learns into **memory** and **skills** — but only keeps +changes that pass a held-out validation gate, and only after the user adopts them. + +## When to activate + +Trigger when the user wants any of: + +- "make my agent learn from how I use it" / "get better the more I use it" +- a nightly/scheduled or on-demand **offline self-improvement / dream / sleep** run +- to **review past sessions/trajectories** and distill recurring tasks +- to **consolidate** feedback into devbase Vault notes or managed skills +- to run `status`, `harvest`, `dry-run`, `run`, or `adopt` for SkillOpt-Sleep + +## The cycle + +1. **Harvest** — use `devkit_session_recall` and `devkit_vault_history` to gather + recent sessions and note changes (read-only). +2. **Mine** — turn session digests into recurring `TaskRecord`s with outcomes and + checkable references where possible. +3. **Replay** — re-run mined tasks offline under the current skill and memory. +4. **Consolidate** — reflect on failures and propose bounded edits to Vault notes + or skills. +5. **Gate** — accept edits only when a held-out validation score improves. +6. **Stage** — write the proposal under + `/.skillopt-sleep/staging//`; nothing live changes. +7. **Adopt** — only after explicit user approval, copy staged files over live + files with backups. + +## How to drive it + +Because Kimi CLI does not have a plugin script model like Claude Code, the cycle +is driven through devbase MCP tools and shell commands: + +```bash +# 1. Check current status +python -m skillopt_sleep status --project "$(pwd)" + +# 2. Safe deterministic preview (no API spend) +python -m skillopt_sleep dry-run --project "$(pwd)" --backend mock + +# 3. Run full cycle and stage a proposal +python -m skillopt_sleep run --project "$(pwd)" --backend local + +# 4. Adopt staged proposal after review +python -m skillopt_sleep adopt --project "$(pwd)" +``` + +For context gathering, also use: + +- `devkit_session_recall` — find relevant past sessions. +- `devkit_vault_search` — locate existing memory/skills related to the mined tasks. +- `devkit_knowledge_report` — summarize the current project state before proposing edits. + +## Hard rules + +- **Never** hand-edit the user's `AGENTS.md`, Vault notes, or skills as part of this skill. + Only the `adopt` action changes live files, and it backs them up first. +- Harvest is read-only. `mock` replay has no side effects. +- Always show the user the **held-out baseline → candidate** score and the + exact proposed edits before suggesting adoption. Evidence before adoption. +- If asked whether it really helps, run the deterministic demo: + ```bash + python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves + ``` + +## Validate / demo + +```bash +# deterministic proof (no API): held-out score rises, gate blocks regressions +python -m skillopt_sleep.experiments.run_experiment --persona researcher --assert-improves +python -m skillopt_sleep.experiments.run_experiment --persona programmer --assert-improves +``` + +See the SkillOpt-Sleep guide for recorded output and +`docs/superpowers/specs/2026-06-07-skillopt-sleep-claude-code-plugin-design.md` +for the full design. diff --git a/src/commands/skill.rs b/src/commands/skill.rs index 2b26b4b..633174d 100644 --- a/src/commands/skill.rs +++ b/src/commands/skill.rs @@ -225,17 +225,58 @@ pub fn run_skill( } } } - crate::SkillCommands::Sync { output_dir } => { + crate::SkillCommands::Sync { output_dir, targets } => { let out = std::path::PathBuf::from(&output_dir); if !out.exists() { std::fs::create_dir_all(&out)?; } - match skill_runtime::clarity_sync::sync_skills_to_plans(&conn, &out) { - Ok(count) => println!("Synced {} skill(s) to {}.", count, out.display()), - Err(e) => { - return Err(anyhow::anyhow!("Skill sync failed: {}", e)); + + let targets = if targets.iter().any(|t| t.eq_ignore_ascii_case("all")) { + skill_runtime::sync_adapter::supported_adapters() + .into_iter() + .map(String::from) + .collect::>() + } else { + targets + }; + + let adapters = skill_runtime::sync_adapter::resolve_adapters(&targets)?; + let rows = registry::list_skills(&conn, None, None)?; + let mut skills = Vec::new(); + for row in rows { + let skill_md = std::path::PathBuf::from(&row.local_path).join("SKILL.md"); + if !skill_md.exists() { + continue; + } + match parser::parse_skill_md(&skill_md) { + Ok(skill) => skills.push(skill), + Err(e) => eprintln!("Warning: failed to parse {}: {}", skill_md.display(), e), } } + let mut total = 0usize; + for adapter in adapters { + let adapter_out = out.join(adapter.name()); + std::fs::create_dir_all(&adapter_out)?; + match adapter.sync(&skills, &adapter_out) { + Ok(count) => { + println!( + "Synced {} skill(s) to {} ({}).", + count, + adapter_out.display(), + adapter.name() + ); + total += count; + } + Err(e) => { + return Err(anyhow::anyhow!( + "Skill sync failed for target '{}': {}", + adapter.name(), + e + )); + } + } + } + println!("Total synced: {} skill instance(s).", total); } crate::SkillCommands::Discover { path, skill_id, dry_run, json } => { let is_git_url = path.starts_with("http://") @@ -335,7 +376,8 @@ pub fn run_skill( json, } => { use crate::skill_runtime::sources::{GitHubSource, LocalFileSource, SkillSource}; - let source_impl: Box = if source.starts_with("https://github.com/") + let source_impl: Box = if source + .starts_with("https://github.com/") || source.starts_with("http://github.com/") || (source.contains('/') && !source.starts_with('/') && !source.contains("://")) { @@ -347,9 +389,14 @@ pub fn run_skill( let name = source_path.as_deref().unwrap_or(path); Box::new(LocalFileSource::new(name, std::path::Path::new(path))) }; - let skills = tokio::runtime::Runtime::new() - .context("failed to create tokio runtime for skill fetch")? - .block_on(source_impl.fetch())?; + let source_name = source_impl.name().to_string(); + let skills = std::thread::spawn(move || { + tokio::runtime::Runtime::new() + .context("failed to create tokio runtime for skill fetch")? + .block_on(source_impl.fetch()) + }) + .join() + .map_err(|e| anyhow::anyhow!("skill fetch thread panicked: {:?}", e))??; if dry_run { if json { let names: Vec<&str> = skills.iter().map(|s| s.name.as_str()).collect(); @@ -357,17 +404,13 @@ pub fn run_skill( "{}", serde_json::to_string_pretty(&serde_json::json!({ "dry_run": true, - "source": source_impl.name(), + "source": source_name, "skills_found": skills.len(), "skill_names": names, }))? ); } else { - println!( - "Dry-run: found {} skill(s) from '{}':", - skills.len(), - source_impl.name() - ); + println!("Dry-run: found {} skill(s) from '{}':", skills.len(), source_name); for s in &skills { println!(" - {} ({})", s.name, s.id); } @@ -389,7 +432,7 @@ pub fn run_skill( "INSERT INTO sync_log (source_name, status, skills_added, skills_updated, finished_at) VALUES (?1, ?2, ?3, ?4, datetime('now'))", rusqlite::params![ - source_impl.name(), + source_name, "success", added as i64, updated as i64 @@ -399,13 +442,13 @@ pub fn run_skill( "INSERT INTO sync_sources (name, url, source_type) VALUES (?1, ?2, ?3) ON CONFLICT(name) DO UPDATE SET last_sync_at = datetime('now')", - rusqlite::params![source_impl.name(), &source, source_impl.name()], + rusqlite::params![source_name, &source, source_name], ); if json { println!( "{}", serde_json::to_string_pretty(&serde_json::json!({ - "source": source_impl.name(), + "source": source_name, "skills_found": skills.len(), "skills_added": added, "skills_updated": updated, @@ -415,7 +458,7 @@ pub fn run_skill( println!( "Imported {} skill(s) from '{}' ({} added, {} updated).", skills.len(), - source_impl.name(), + source_name, added, updated ); diff --git a/src/main.rs b/src/main.rs index 66a118a..eecd85c 100644 --- a/src/main.rs +++ b/src/main.rs @@ -429,6 +429,9 @@ pub(crate) enum SkillCommands { Sync { /// Output directory for generated plan JSON files output_dir: String, + /// Target client format(s) to generate. Use 'all' for every adapter. + #[arg(long = "target", value_name = "TARGET", num_args = 1.., default_value = "clarity")] + targets: Vec, }, /// Discover and auto-package a project as a Skill Discover { diff --git a/src/skill_runtime/clarity_sync.rs b/src/skill_runtime/clarity_sync.rs index dd3bbd3..9060fdc 100644 --- a/src/skill_runtime/clarity_sync.rs +++ b/src/skill_runtime/clarity_sync.rs @@ -42,13 +42,25 @@ struct SkillWithInputs { /// Sync all skills from devbase to a plans directory (generic JSON output). pub fn sync_skills_to_plans(conn: &Connection, plans_dir: &Path) -> Result { + let rows = fetch_skills_with_inputs(conn)?; + let skills: Vec = rows.iter().map(skill_row_to_meta).collect(); + sync_skills_to_plans_with_skills(plans_dir, &skills) +} + +/// Sync the provided skills to a plans directory (generic JSON output). +/// +/// This is the implementation used by [`crate::skill_runtime::sync_adapter::ClarityJsonAdapter`]. +pub fn sync_skills_to_plans_with_skills( + plans_dir: &Path, + skills: &[crate::skill_runtime::SkillMeta], +) -> Result { std::fs::create_dir_all(plans_dir) .with_context(|| format!("Failed to create plans dir: {}", plans_dir.display()))?; - let skills = fetch_skills_with_inputs(conn)?; let mut synced = 0; for skill in skills { + let skill = skill_meta_to_row(skill); let plan_path = plans_dir.join(format!("{}.json", skill.id)); let devbase_updated = skill.updated_at; @@ -92,6 +104,45 @@ pub fn sync_skills_to_plans(conn: &Connection, plans_dir: &Path) -> Result crate::skill_runtime::SkillMeta { + let inputs: Vec = + serde_json::from_str(&row.inputs_schema).unwrap_or_default(); + let tags = parse_tags_from_skill(&row.tags); + crate::skill_runtime::SkillMeta { + id: row.id.clone(), + name: row.name.clone(), + version: "1.0.0".to_string(), + description: row.description.clone(), + author: None, + tags, + entry_script: None, + skill_type: crate::skill_runtime::SkillType::Custom, + local_path: std::path::PathBuf::new(), + inputs, + outputs: vec![], + dependencies: vec![], + embedding: None, + installed_at: row.updated_at, + updated_at: row.updated_at, + last_used_at: None, + body: String::new(), + category: None, + } +} + +fn skill_meta_to_row(skill: &crate::skill_runtime::SkillMeta) -> SkillWithInputs { + let inputs_schema = serde_json::to_string(&skill.inputs).unwrap_or_default(); + let tags = skill.tags.join(","); + SkillWithInputs { + id: skill.id.clone(), + name: skill.name.clone(), + description: skill.description.clone(), + tags, + inputs_schema, + updated_at: skill.updated_at, + } +} + fn fetch_skills_with_inputs(conn: &Connection) -> Result> { let mut stmt = conn.prepare( "SELECT id, name, description, tags, inputs_schema, updated_at FROM skills ORDER BY name", diff --git a/src/skill_runtime/mod.rs b/src/skill_runtime/mod.rs index 442808c..d1d343d 100644 --- a/src/skill_runtime/mod.rs +++ b/src/skill_runtime/mod.rs @@ -9,6 +9,7 @@ pub mod publish; pub mod registry; pub mod scoring; pub mod sources; +pub mod sync_adapter; // Types migrated to devbase-skill-runtime-types crate. pub use devbase_skill_runtime_types::*; diff --git a/src/skill_runtime/sync_adapter.rs b/src/skill_runtime/sync_adapter.rs new file mode 100644 index 0000000..729fcfa --- /dev/null +++ b/src/skill_runtime/sync_adapter.rs @@ -0,0 +1,317 @@ +// SPDX-License-Identifier: AGPL-3.0-or-later +// Copyright (c) 2026 juice094 +//! Adapters for syncing devbase skills to multiple client-specific formats. + +use std::collections::HashSet; +use std::path::Path; + +use anyhow::{Context, Result}; + +use crate::skill_runtime::SkillMeta; + +/// Sync a list of devbase skills to a client-specific output directory. +pub trait SkillSyncAdapter { + fn name(&self) -> &'static str; + fn sync(&self, skills: &[SkillMeta], output_dir: &Path) -> Result; +} + +/// Resolve an adapter by its short name. +pub fn resolve_adapter(name: &str) -> Option> { + match name.to_lowercase().as_str() { + "clarity" | "clarity-json" | "json" => Some(Box::new(ClarityJsonAdapter)), + "kimi" | "kimicli" => Some(Box::new(KimiCliAdapter)), + "claude" | "claude-code" | "claudecode" => Some(Box::new(ClaudeCodeAdapter)), + "codex" => Some(Box::new(CodexAdapter)), + "claw" => Some(Box::new(ClawAdapter)), + _ => None, + } +} + +/// List all supported adapter short names. +pub fn supported_adapters() -> Vec<&'static str> { + vec!["clarity", "kimicli", "claude-code", "codex", "claw"] +} + +/// Resolve multiple adapter names. Returns an error if any name is unknown. +pub fn resolve_adapters(names: &[String]) -> Result>> { + let mut adapters: Vec> = Vec::new(); + let mut seen = HashSet::new(); + for name in names { + let adapter = resolve_adapter(name) + .with_context(|| format!("Unknown skill sync target: '{}'", name))?; + if seen.insert(adapter.name()) { + adapters.push(adapter); + } + } + Ok(adapters) +} + +// --------------------------------------------------------------------------- +// Clarity JSON adapter (legacy / default) +// --------------------------------------------------------------------------- + +pub struct ClarityJsonAdapter; + +impl SkillSyncAdapter for ClarityJsonAdapter { + fn name(&self) -> &'static str { + "clarity" + } + + fn sync(&self, skills: &[SkillMeta], output_dir: &Path) -> Result { + crate::skill_runtime::clarity_sync::sync_skills_to_plans_with_skills(output_dir, skills) + } +} + +// --------------------------------------------------------------------------- +// Markdown skill adapter base (Kimi CLI / Claude Code / Codex / claw) +// --------------------------------------------------------------------------- + +/// Output layout for a Markdown-based skill adapter. +pub struct MarkdownLayout { + /// Root output directory. + pub output_dir: &'static str, + /// Whether to nest skills under `.client/skills//SKILL.md`. + pub nested_under_dotdir: bool, + /// Optional extra frontmatter fields rendered as a raw YAML string. + pub extra_frontmatter: Option<&'static str>, +} + +pub struct MarkdownSkillAdapter { + pub name: &'static str, + pub layout: MarkdownLayout, +} + +impl MarkdownSkillAdapter { + fn write_skill(&self, skill: &SkillMeta, output_dir: &Path) -> Result<()> { + let skill_dir = if self.layout.nested_under_dotdir { + output_dir.join(self.layout.output_dir).join("skills").join(&skill.id) + } else { + output_dir.join(self.layout.output_dir).join(&skill.id) + }; + std::fs::create_dir_all(&skill_dir) + .with_context(|| format!("Failed to create skill dir: {}", skill_dir.display()))?; + + let skill_md = skill_dir.join("SKILL.md"); + let content = render_skill_md(skill, self.layout.extra_frontmatter); + std::fs::write(&skill_md, content) + .with_context(|| format!("Failed to write skill: {}", skill_md.display()))?; + Ok(()) + } +} + +impl SkillSyncAdapter for MarkdownSkillAdapter { + fn name(&self) -> &'static str { + self.name + } + + fn sync(&self, skills: &[SkillMeta], output_dir: &Path) -> Result { + std::fs::create_dir_all(output_dir) + .with_context(|| format!("Failed to create output dir: {}", output_dir.display()))?; + for skill in skills { + self.write_skill(skill, output_dir)?; + } + Ok(skills.len()) + } +} + +fn render_skill_md(skill: &SkillMeta, extra_frontmatter: Option<&str>) -> String { + let mut fm = String::new(); + fm.push_str(&format!("name: {}\n", skill.name)); + fm.push_str(&format!( + "description: {}\n", + serde_yaml::to_string(&skill.description) + .unwrap_or_default() + .trim_start_matches("---\n") + .trim() + )); + fm.push_str(&format!("version: {}\n", skill.version)); + if !skill.tags.is_empty() { + fm.push_str(&format!( + "tags: {}\n", + serde_yaml::to_string(&skill.tags) + .unwrap_or_default() + .trim_start_matches("---\n") + .trim() + )); + } + if let Some(author) = &skill.author { + fm.push_str(&format!("author: {}\n", author)); + } + if let Some(category) = &skill.category { + fm.push_str(&format!("category: {}\n", category)); + } + if let Some(extra) = extra_frontmatter { + fm.push_str(extra); + } + + let mut output = String::new(); + output.push_str("---\n"); + output.push_str(&fm); + output.push_str("---\n\n"); + output.push_str(&skill.body); + output.push('\n'); + output +} + +// --------------------------------------------------------------------------- +// Client-specific Markdown adapters +// --------------------------------------------------------------------------- + +pub struct KimiCliAdapter; + +impl SkillSyncAdapter for KimiCliAdapter { + fn name(&self) -> &'static str { + "kimicli" + } + + fn sync(&self, skills: &[SkillMeta], output_dir: &Path) -> Result { + MarkdownSkillAdapter { + name: "kimicli", + layout: MarkdownLayout { + output_dir: "", + nested_under_dotdir: false, + extra_frontmatter: None, + }, + } + .sync(skills, output_dir) + } +} + +pub struct ClaudeCodeAdapter; + +impl SkillSyncAdapter for ClaudeCodeAdapter { + fn name(&self) -> &'static str { + "claude-code" + } + + fn sync(&self, skills: &[SkillMeta], output_dir: &Path) -> Result { + MarkdownSkillAdapter { + name: "claude-code", + layout: MarkdownLayout { + output_dir: ".claude", + nested_under_dotdir: true, + extra_frontmatter: None, + }, + } + .sync(skills, output_dir) + } +} + +pub struct CodexAdapter; + +impl SkillSyncAdapter for CodexAdapter { + fn name(&self) -> &'static str { + "codex" + } + + fn sync(&self, skills: &[SkillMeta], output_dir: &Path) -> Result { + MarkdownSkillAdapter { + name: "codex", + layout: MarkdownLayout { + output_dir: ".codex", + nested_under_dotdir: true, + extra_frontmatter: None, + }, + } + .sync(skills, output_dir) + } +} + +pub struct ClawAdapter; + +impl SkillSyncAdapter for ClawAdapter { + fn name(&self) -> &'static str { + "claw" + } + + fn sync(&self, skills: &[SkillMeta], output_dir: &Path) -> Result { + // claw currently consumes Kimi CLI format from .kimi/skills/ + MarkdownSkillAdapter { + name: "claw", + layout: MarkdownLayout { + output_dir: ".kimi", + nested_under_dotdir: true, + extra_frontmatter: None, + }, + } + .sync(skills, output_dir) + } +} + +#[cfg(test)] +mod tests { + use super::*; + use chrono::Utc; + use devbase_skill_runtime_types::{SkillMeta, SkillType}; + + fn dummy_skill(id: &str, body: &str) -> SkillMeta { + SkillMeta { + id: id.to_string(), + name: id.to_string(), + version: "1.0.0".to_string(), + description: format!("Description for {}", id), + author: Some("devbase".to_string()), + tags: vec!["rust".to_string()], + entry_script: None, + skill_type: SkillType::Custom, + local_path: std::path::PathBuf::from(format!("/tmp/{}", id)), + inputs: vec![], + outputs: vec![], + dependencies: vec![], + embedding: None, + installed_at: Utc::now(), + updated_at: Utc::now(), + last_used_at: None, + body: body.to_string(), + category: Some("dev".to_string()), + } + } + + #[test] + fn test_resolve_adapter_known() { + assert!(resolve_adapter("kimicli").is_some()); + assert!(resolve_adapter("claude-code").is_some()); + assert!(resolve_adapter("codex").is_some()); + assert!(resolve_adapter("claw").is_some()); + assert!(resolve_adapter("clarity").is_some()); + } + + #[test] + fn test_resolve_adapter_unknown() { + assert!(resolve_adapter("vscode").is_none()); + } + + #[test] + fn test_kimi_adapter_writes_skill_md() { + let tmp = tempfile::tempdir().unwrap(); + let skill = dummy_skill("test-skill", "# Test\n\nBody."); + let adapter = KimiCliAdapter; + let count = adapter.sync(&[skill], tmp.path()).unwrap(); + assert_eq!(count, 1); + let path = tmp.path().join("test-skill").join("SKILL.md"); + assert!(path.exists()); + let content = std::fs::read_to_string(path).unwrap(); + assert!(content.contains("name: test-skill")); + assert!(content.contains("# Test")); + } + + #[test] + fn test_claude_adapter_writes_under_dotdir() { + let tmp = tempfile::tempdir().unwrap(); + let skill = dummy_skill("claude-skill", "Body"); + let adapter = ClaudeCodeAdapter; + adapter.sync(&[skill], tmp.path()).unwrap(); + let path = tmp.path().join(".claude").join("skills").join("claude-skill").join("SKILL.md"); + assert!(path.exists()); + } + + #[test] + fn test_claw_adapter_writes_under_kimi_dir() { + let tmp = tempfile::tempdir().unwrap(); + let skill = dummy_skill("claw-skill", "Body"); + let adapter = ClawAdapter; + adapter.sync(&[skill], tmp.path()).unwrap(); + let path = tmp.path().join(".kimi").join("skills").join("claw-skill").join("SKILL.md"); + assert!(path.exists()); + } +} From 44fad01d7691549d6dcd80948ca21ed8334b14d2 Mon Sep 17 00:00:00 2001 From: juice094 Date: Thu, 25 Jun 2026 19:52:02 +0800 Subject: [PATCH 3/3] docs: align AGENTS.md/CLAUDE.md with OKF bundle and archive legacy architecture docs --- .../architecture/dependency-topology.md | 278 ++++++ .knowledge/architecture/index.md | 29 + .knowledge/architecture/invariants.md | 78 ++ .knowledge/architecture/project-worktree.md | 261 +++++ .knowledge/architecture/three-layer-model.md | 108 +++ .knowledge/development/build-and-test.md | 65 ++ .knowledge/development/code-style.md | 69 ++ .knowledge/development/index.md | 26 + .knowledge/index.md | 65 ++ .knowledge/log.md | 97 ++ .knowledge/mcp/index.md | 45 + .knowledge/mcp/tool-adding-guide.md | 56 ++ .knowledge/registry/index.md | 33 + .knowledge/registry/migration-policy.md | 44 + .knowledge/registry/schema.md | 91 ++ AGENTS.md | 706 +++++--------- CLAUDE.md | 52 +- CONTRIBUTING.md | 7 +- README.md | 2 +- SUPPORT.md | 4 +- docs/README.md | 15 +- .../context-compiler.md | 340 +++---- .../dependency-topology.md | 650 ++++++------- docs/{architecture => _archive}/invariants.md | 152 +-- docs/{architecture => _archive}/overview.md | 515 +++++----- .../six-dimension-gap-analysis-20260430.md | 892 +++++++++--------- docs/guides/ai-instance-handoff.md | 405 ++++---- docs/reference/entities-model.md | 315 ++++--- 28 files changed, 3291 insertions(+), 2109 deletions(-) create mode 100644 .knowledge/architecture/dependency-topology.md create mode 100644 .knowledge/architecture/index.md create mode 100644 .knowledge/architecture/invariants.md create mode 100644 .knowledge/architecture/project-worktree.md create mode 100644 .knowledge/architecture/three-layer-model.md create mode 100644 .knowledge/development/build-and-test.md create mode 100644 .knowledge/development/code-style.md create mode 100644 .knowledge/development/index.md create mode 100644 .knowledge/index.md create mode 100644 .knowledge/log.md create mode 100644 .knowledge/mcp/index.md create mode 100644 .knowledge/mcp/tool-adding-guide.md create mode 100644 .knowledge/registry/index.md create mode 100644 .knowledge/registry/migration-policy.md create mode 100644 .knowledge/registry/schema.md rename docs/{architecture => _archive}/context-compiler.md (93%) rename docs/{architecture => _archive}/dependency-topology.md (96%) rename docs/{architecture => _archive}/invariants.md (88%) rename docs/{architecture => _archive}/overview.md (94%) diff --git a/.knowledge/architecture/dependency-topology.md b/.knowledge/architecture/dependency-topology.md new file mode 100644 index 0000000..273a01f --- /dev/null +++ b/.knowledge/architecture/dependency-topology.md @@ -0,0 +1,278 @@ +--- +type: ArchitectureTopology +title: devbase 模块依赖拓扑 +description: 按模块间依赖关系组织的功能分层（11-Tier），包含枢纽分析与迭代策略。 +timestamp: 2026-06-25T11:15:50Z +tags: [architecture, topology, dependency, tiers] +--- + +# devbase 模块依赖拓扑 + +> 原则：**下层为上层提供契约，上层为下层提供场景验证。** 改动下层（高扇入枢纽）影响面大，需更严格测试；叶节点可独立迭代实验。 + +--- + +## 拓扑总览 + +```text +Tier 11 ┌────────────────────────────────────────┐ + │ main.rs / daemon.rs │ ← CLI 入口、守护进程 +Tier 10 ├────────────────────────────────────────┤ + │ tui/ (theme/layout/state/event/render)│ ← 终端交互层 +Tier 9 ├────────────────────────────────────────┤ + │ mcp/ (mod + tools/*) │ ← MCP 协议适配层，71 tools +Tier 8 ├────────────────────────────────────────┤ + │ knowledge_engine, skill_sync, vault │ ← 高级聚合、跨层桥接 +Tier 7 ├────────────────────────────────────────┤ + │ workflow/ (model/parser/validator/ │ ← Workflow 编排引擎 + │ interpolate/scheduler/ │ + │ state/executor) │ +Tier 6 ├────────────────────────────────────────┤ + │ skill_runtime/ (parser/registry/ │ ← Skill 全生命周期 + │ discover/dependency/ │ + │ executor/scoring/ │ + │ publish/clarity_sync) │ +Tier 5 ├────────────────────────────────────────┤ + │ sync/ (policy/tasks/orchestrator) │ ← 同步编排 + │ watch │ ← 文件系统监控 +Tier 4 ├────────────────────────────────────────┤ + │ query, health, oplog_analytics │ ← 查询与报告 + │ search/hybrid │ ← 混合检索 +Tier 3 ├────────────────────────────────────────┤ + │ dependency_graph, symbol_links │ ← 代码分析关联 + │ vault/indexer, vault/backlinks │ ← Vault 索引与链接 +Tier 2 ├────────────────────────────────────────┤ + │ scan, vault/scanner, discovery_engine │ ← 扫描与发现 + │ backup, test_utils │ ← 备份与测试辅助 +Tier 1 ├────────────────────────────────────────┤ + │ registry/ (类型定义 + CRUD impl) │ ← 数据契约中心 + │ vault/{fs_io,frontmatter,wikilink} │ ← Vault 原子操作 + │ semantic_index, embedding, search │ ← 索引原子能力 + │ arxiv │ ← 外部论文 API +Tier 0 ├────────────────────────────────────────┤ + │ core, i18n, config, asyncgit │ ← 类型根与配置根 + │ sync_protocol │ ← 同步协议基础类型 + └────────────────────────────────────────┘ +``` + +--- + +## 逐层规划 + +### Tier 0 — 原子基础层 + +**目的**：为整个系统提供**无业务语义**的底层能力，任何改动都不应破坏上层编译。 + +| 模块 | 功能 | 依赖数 | 被依赖数 | +|:---|:---|:---:|:---:| +| `core` | `NodeType` / `Node` / `Edge` 统一实体枚举 | 0 | 中 | +| `i18n` | 静态字符串表（en/zh_cn） | 0 | 高 | +| `config` | 配置结构体：LLM、Embedding、Sync、Daemon | 0 | 高 | +| `asyncgit` | 异步 Git 状态通知通道（crossbeam） | 0 | 中 | +| `sync_protocol` | `FileInfo` / `SyncIndex` / scan_directory | 0 | 低 | + +**迭代策略**：极度稳定，变更需全量回归。`i18n` 新增字段需同步所有语言文件。 + +### Tier 1 — 数据契约与原子能力层 + +**目的**：定义**领域模型**和**可独立工作的原子能力**。`registry` 是整个系统的"心脏"，所有业务数据最终落盘于此。 + +| 模块/子模块 | 功能 | 依赖 | 被依赖 | +|:---|:---|:---|:---| +| `registry/` | SQLite Schema v36 + CRUD：repos/repo_tags/code_symbols/code_embeddings/code_call_graph/code_symbol_links/oplog/vault_notes/papers/experiments/skills/skill_executions/entities/entity_types/relations/workflows/workflow_executions | Tier 0 (dirs) | 几乎所有上层 | +| `vault/fs_io` | Vault 文件读写原子操作 | 无 | vault/* | +| `vault/frontmatter` | YAML frontmatter 解析 | 无 | vault/scanner, skill_sync | +| `vault/wikilink` | `[[wikilink]]` 提取 | 无 | vault/scanner | +| `semantic_index` | tree-sitter 多语言符号提取（Rust/Python/TS/Go） | 无 | scan, mcp tools, search/hybrid | +| `embedding` | cosine_similarity、BLOB 序列化、query embedding 生成 | 无 | search/hybrid, mcp tools | +| `search` | Tantivy 索引初始化（id/title/content/tags/doc_type） | 无 | vault/indexer, search/hybrid, mcp tools | +| `arxiv` | arXiv API 元数据抓取 | 无 | mcp tools | + +**关键决策**：registry 的 Schema 变更是**全局阻塞点**。任何新增表/字段必须： +1. 更新 `registry/migrate.rs` 的 `PRAGMA user_version` +2. 触发 `backup::auto_backup_before_migration()` +3. 同步修改 `test_helpers.rs` 的 `SCHEMA_DDL` +4. 检查 `oplog_analytics.rs` 的表存在性检查 + +### Tier 2 — 扫描与发现层 + +**目的**：将**无结构的外部世界**（文件系统、Git 仓库）转化为 registry 中的结构化数据。 + +| 模块 | 功能 | 上游依赖 | 下游产出 | +|:---|:---|:---|:---| +| `scan` | Git 仓库发现、语言检测、代码统计（tokei）、blake3 快照、自动注册 | registry, config | registry 各表 | +| `vault/scanner` | Vault 目录遍历、frontmatter/wikilink 提取、注册到 vault_notes | registry, vault/* | registry.vault_notes | +| `discovery_engine` | 跨仓库 Cargo.toml 依赖关联发现 | registry::RepoEntry | registry（待扩展） | +| `backup` | Schema 迁移前自动快照（保留 10 个） | registry | registry（文件系统） | +| `test_utils` | 测试辅助：临时 registry、mock repo | registry | 测试代码 | + +**迭代策略**：scan 是数据入口，新增语言支持或检测规则在此层实验，不影响查询层。 + +### Tier 3 — 分析与关联层 + +**目的**：在已结构化数据上建立**语义关联**，为查询层提供"图"能力。 + +| 模块 | 功能 | 输入数据 | 产出 | +|:---|:---|:---|:---| +| `dependency_graph` | 跨仓库依赖图构建 | scan 发现的 Cargo.toml/package.json | 图结构 | +| `symbol_links` | Jaccard 签名相似度 + 同文件聚类 → code_symbol_links | registry.code_symbols | registry.code_symbol_links | +| `vault/indexer` | Vault 笔记入 Tantivy 全文索引 | vault_notes, search | Tantivy 索引文档 | +| `vault/backlinks` | Vault 反向链接图谱 | vault_notes.outgoing_links | 关联查询结果 | + +**迭代策略**：`symbol_links` 的阈值（默认 0.3）和算法可在此层独立调优，不破坏下游 API。 + +### Tier 4 — 查询与报告层 + +**目的**：为上层（MCP/TUI）提供**只读查询接口**，是"知识库"的对外窗口。 + +| 模块 | 功能 | 依赖 | +|:---|:---|:---| +| `query` | 结构化表达式解析：`lang:rust stale:>30 behind:>10 tag:x` | registry | +| `health` | dirty/ahead/behind/diverged 计算、workspace 快照哈希 | registry, git2 | +| `oplog_analytics` | 知识覆盖报告：symbol/embedding/call 覆盖率、健康汇总、最近活动 | registry（多表聚合） | +| `search/hybrid` | RRF 归并：向量语义搜索 + Tantivy BM25 关键词 + 自动降级 | semantic_index, search, embedding | + +**关键约束**：查询层必须保持**向后兼容**。MCP tool schema 的 breaking change 只能通过新增 tool（如 `_v2`）而非修改现有 tool。 + +### Tier 5 — 同步编排层 + +**目的**：将 registry 中的**期望状态**（upstream_url、tags、policy）与文件系统的**实际状态**对齐。 + +| 模块 | 功能 | 依赖关系 | +|:---|:---|:---| +| `sync/policy` | SyncPolicy / SyncMode / RepoSyncTask 定义、错误分类 | 独立（git2） | +| `sync/tasks` | 单仓库 fetch/pull/rebase/merge 执行、OpLog 写入 | registry::WorkspaceRegistry, policy | +| `sync/orchestrator` | 并发信号量控制、批量执行、超时处理、进度回调 | policy, tasks | +| `watch` | notify 文件系统监控、事件聚合 | sync_protocol | + +**迭代策略**：sync 是**危险操作层**。新增 sync 策略需先在 policy 层定义，再在 tasks 层实现，最后由 orchestrator 编排。 + +### Tier 6 — Skill Runtime 层 + +**目的**：实现 Skill 的**全生命周期管理**。 + +| 子模块 | 功能 | 依赖 | +|:---|:---|:---| +| `parser` | SKILL.md YAML frontmatter → SkillMeta | 独立 | +| `registry` | skills/skill_executions 表 CRUD、skill 安装/卸载 | registry::WorkspaceRegistry | +| `discover` | 项目类型检测（Rust/Node/Python/Go/Docker/Generic）→ SKILL.md 自动生成 + entry_script 包装 | parser | +| `dependency` | Skill 依赖图拓扑排序（Kahn）、DFS 环检测 | skill_runtime::registry | +| `executor` | Process-based 执行、interpreter 自动探测、timeout、stdout/stderr 捕获 | skill_runtime types | +| `scoring` | success_rate / usage_count / rating 计算（0–5 分公式） | registry + skill_runtime::registry | +| `publish` | validate → git tag → push remote | git2 + registry | +| `clarity_sync` | Skill 导出为 Clarity plan JSON | registry + skill_runtime types | + +**依赖关系**： +```text +parser → discover +registry → dependency → executor +registry + executor → scoring +``` + +### Tier 7 — Workflow 引擎层 + +**目的**：将多个 Skill/子工作流编排为**可复用的自动化流程**。 + +| 子模块 | 功能 | 依赖 | +|:---|:---|:---| +| `model` | WorkflowDefinition / StepDefinition / StepType / ErrorPolicy | 独立 | +| `parser` | YAML → model（untagged 反序列化） | model | +| `validator` | 步骤 ID 唯一性、依赖存在性检查 | model | +| `interpolate` | `${inputs.x}` / `${steps.y.outputs.z}` 变量插值 | 独立 | +| `scheduler` | Kahn 拓扑排序 → ExecutionBatch（可并行步骤组） | model | +| `state` | workflow_executions 表 CRUD、状态机转换 | model + registry | +| `executor` | batch 并行执行（`std::thread::scope`）、错误策略（Fail/Continue/Retry/Fallback）、子工作流递归 | scheduler + model + skill_runtime::executor + registry | + +**依赖关系**： +```text +model ← parser / validator / scheduler +scheduler → executor +skill_runtime::executor → executor +``` + +### Tier 8 — 高级聚合与跨层桥接 + +**目的**：连接原本正交的子系统，产生**涌现能力**。 + +| 模块 | 功能 | 跨层连接 | +|:---|:---|:---| +| `knowledge_engine` | block_on_async 安全封装、README 摘要提取、模块信息探测 | registry ↔ 外部进程 | +| `skill_sync` | Vault 笔记（ai_context=true）→ Clarity SKILL.md 格式导出 | vault ↔ skill_runtime | +| `vault/mod` | Vault 子系统统一出口 | 聚合 vault/* | + +### Tier 9 — MCP 协议层 + +**目的**：将所有下层能力**封装为标准协议接口**，供 AI Agent 调用。 + +| 子模块 | 对应 Tools | 依赖的下层模块 | +|:---|:---|:---| +| `tools/repo` | scan, health, sync, query_repos | scan, health, sync, query | +| `tools/query` | query, index, code_metrics, module_graph | query, scan, semantic_index | +| `tools/vault` | vault_search, vault_read, vault_write, vault_backlinks, vault_daily, vault_graph, vault_export, vault_history | vault/*, search | +| `tools/skill` | skill_list, skill_search, skill_run, skill_discover, skill_sync | skill_runtime/* | +| `tools/context` | project_context, project_brief, impact_analysis, hybrid_search, cross_repo_search, related_symbols, knowledge_report, embedding_store, embedding_search | search/hybrid, embedding, oplog_analytics, query | +| `tools/session` | session_save, session_list, session_resume, session_attach, session_detach, session_activate, session_search, session_capture, session_workflows, session_recall, session_index, session_export, session_import | registry, workflow | +| `tools/relations` | relation_store, relation_query, relation_delete | registry::relation | +| `mcp/mod` | 框架：McpTool trait、invoke_stream、ToolStreamEvent | 聚合上述所有 tools | + +**关键契约**： +- 所有状态变更操作必须**幂等**（`ON CONFLICT ... DO UPDATE/NOTHING`）。 +- 所有批量操作包裹在 SQLite transaction 中。 +- Breaking change 通过新增 tool 实现，不修改现有 tool schema。 + +### Tier 10 — TUI 交互层 + +**目的**：为人类开发者提供**终端仪表盘**。 + +| 子模块 | 功能 | 依赖 | +|:---|:---|:---| +| `theme` | Design Token（primary/secondary/error 等色彩语义） | 独立 | +| `layout` | 响应式布局计算（35/65 分栏、compact 模式、居中弹窗） | 独立 | +| `state` | App 状态机：仓库列表、Skill 面板、Workflow 弹窗、NLQ 输入、同步进度 | asyncgit, registry, sync::SyncOrchestrator, config | +| `event` | 键盘事件路由、异步通知消费（AsyncNotification） | state, render::ui | +| `render/detail` | 右侧详情页（Overview/Health/Insights） | state, theme, layout | +| `render/list` | 左侧仓库列表（状态图标、排序、过滤） | state, theme, layout | +| `render/popups` | 搜索/同步/Skill/Workflow/NLQ 弹窗 | state, theme, layout | +| `render/help` | 快捷键帮助覆盖层 | state, theme, layout | +| `render/logs` | 底部日志面板 | state, theme, layout | + +**迭代策略**：TUI 是纯消费者层，新增面板不改动任何下层逻辑。 + +### Tier 11 — 系统入口 + +| 模块 | 功能 | 依赖 | +|:---|:---|:---| +| `main.rs` | CLI 子命令解析（clap）、模块路由 | 所有上层 | +| `daemon.rs` | 定时 tick：stale repo health check、自动 sync | config, health, sync | + +--- + +## 枢纽分析 + +### 高扇入模块（改动影响大，需谨慎） + +| 模块 | 扇入来源 | 风险等级 | +|:---|:---|:---:| +| `registry::WorkspaceRegistry` | scan, health, backup, query, oplog_analytics, sync, skill_runtime, workflow, vault, mcp tools, tui | 🔴 | +| `i18n` | sync, digest, tui/render/* | 🟡 | +| `config` | scan, tui/state, sync, daemon | 🟡 | +| `skill_runtime::executor` | workflow/executor, mcp tools, tui | 🟡 | + +### 叶节点模块（可独立迭代，影响面小） + +| 模块 | 说明 | 实验优先级 | +|:---|:---|:---:| +| `arxiv` | 仅被 1 个 MCP tool 使用 | ⭐⭐⭐ | +| `semantic_index` | 仅被 scan 和 search/hybrid 使用，接口稳定 | ⭐⭐⭐ | +| `embedding` | 纯函数工具包，无副作用 | ⭐⭐⭐ | +| `vault/wikilink` | 解析规则可独立调优 | ⭐⭐ | +| `workflow/model` | 模型字段扩展不影响下层 | ⭐⭐ | + +--- + +## 基于依赖的迭代策略 + +1. **根节点加固（Tier 0–1）**：registry Schema 变更需经过 migration → 备份 → 兼容性检查。 +2. **数据管道扩展（Tier 2–3）**：新增语言支持在 `semantic_index` 扩展 → `scan` 触发索引 → `symbol_links` 自动关联 → `search/hybrid` 无需改动。 +3. **查询能力叠加（Tier 4）**：`search/hybrid` RRF 权重、`oplog_analytics` 新报表可独立调优。 +4. **编排能力实验（Tier 5–7）**：sync 策略、Skill Runtime、Workflow StepType 在此层迭代。 diff --git a/.knowledge/architecture/index.md b/.knowledge/architecture/index.md new file mode 100644 index 0000000..f7a6755 --- /dev/null +++ b/.knowledge/architecture/index.md @@ -0,0 +1,29 @@ +--- +type: ConceptIndex +title: devbase 架构概念索引 +description: 架构相关概念文档的入口，包含分层模型、依赖拓扑、不变量。 +timestamp: 2026-06-25T11:15:50Z +tags: [architecture, index] +--- + +# devbase 架构概念索引 + +## 项目定位 + +devbase 是**本地优先的开发者工作空间数据库与知识库管理器**。它把代码仓库、PARA 笔记、Skill 与工作流编译成 AI 可推理的结构化情境。 + +## 架构文档 + +| 概念 | 文档 | 一句话说明 | +|------|------|------------| +| 三层架构 | [three-layer-model.md](./three-layer-model.md) | 交互层 → 编译层 → 可靠层 | +| 依赖拓扑 | [dependency-topology.md](./dependency-topology.md) | 11 个 Tier 的模块依赖关系与迭代策略 | +| 架构不变量 | [invariants.md](./invariants.md) | 不可打破的架构红线（G/T 体系） | +| 项目工作树 | [project-worktree.md](./project-worktree.md) | 按实际文件系统整理的模块与文件速查 | + +## 关键设计原则 + +1. **依赖注入优于全局状态**：所有 IO 边界路径通过参数、`StorageBackend` 或 `AppContext` 注入。 +2. **本地优先**：Registry DB 只存在用户本地配置目录，不向远程传输。 +3. **客户端无关**：核心能力不硬编码特定客户端路径或 API。 +4. **所有状态变更操作必须幂等**。 diff --git a/.knowledge/architecture/invariants.md b/.knowledge/architecture/invariants.md new file mode 100644 index 0000000..3854024 --- /dev/null +++ b/.knowledge/architecture/invariants.md @@ -0,0 +1,78 @@ +--- +type: Invariants +title: devbase 架构不变量清单 +description: 不可打破的架构规则。违反任意一条必须 halt，转交人类裁决或回滚。 +timestamp: 2026-06-25T11:15:50Z +tags: [architecture, invariants, guardrails] +--- + +# devbase 架构不变量清单 + +> 原则：不可打破的规则列表，每次代码审查对照检查。 + +--- + +## 全局不变量（G1–G7） + +| # | 规则 | 违反后果 | 检测方式 | +|---|------|---------|---------| +| G1 | 依赖注入优于全局状态：禁止新增 `dirs::data_local_dir()` / `std::env::var_os` 硬编码路径 | 数据层被查询层污染，路径逻辑散落 | `grep -rn "dirs::data_local_dir\|std::env::var_os" src/` | +| G2 | 测试密封性：测试禁止修改全局进程状态，文件系统测试用 `tempfile` + `StorageBackend` | 测试间互相污染， flaky | `cargo test --test-threads=16` | +| G3 | Schema 单一事实来源：`SCHEMA_DDL` 与 `migrate.rs` 必须原子同步 | 测试与生产 schema 不一致 | `test_in_memory_schema_version` | +| G4 | 二进制入口限界：`main.rs` 不得超过 1000 行 | CLI 逻辑膨胀，难以维护 | 行数检查 | +| G5 | 生产代码无 panic：禁止 `unwrap()` / `expect()` / `panic!()` | 运行时崩溃 | `cargo clippy` + 人工审查 | +| G6 | 无循环依赖：禁止模块间双向 `use crate::` 引用 | 编译/理解复杂度爆炸 | `cargo check` + 依赖图审查 | +| G7 | Workspace 拆分约束：新增模块若对 devbase 内部其他模块的 `crate::` 引用超过 5 个，禁止提取为 workspace crate | 子 crate 反向耦合主 crate | 代码审查 | + +--- + +## 分层不变量（T01–T12） + +### Tier 0–1（原子基础层） + +| # | 规则 | 说明 | +|---|------|------| +| T01 | `core` 只定义无业务语义的枚举和结构体 | `NodeType` / `Node` / `Edge` 不得出现 devbase 专属逻辑 | +| T02 | `registry` Schema 变更必须经过三步：migration → 备份 → 兼容性检查 | 见 [registry/migration-policy.md](../registry/migration-policy.md) | +| T03 | `embedding` 必须是纯函数工具包，无副作用 | 禁止在 `encode` 中写文件、改全局状态 | + +### Tier 2–3（扫描与分析层） + +| # | 规则 | 说明 | +|---|------|------| +| T04 | `scan` 新增语言支持不得改动 `semantic_index` 公共 API | 语言检测规则可独立实验 | +| T05 | `symbol_links` 的阈值和算法可独立调优，不破坏下游 | Jaccard 阈值默认 0.3，可调 | + +### Tier 4（查询层） + +| # | 规则 | 说明 | +|---|------|------| +| T06 | `query` 表达式解析必须向后兼容 | `lang:rust` 语法不得删除，只能扩展 | +| T07 | `search/hybrid` RRF 权重可独立调优，不影响 tool schema | 向量/BM25 融合策略是内部实现细节 | + +### Tier 5（同步层） + +| # | 规则 | 说明 | +|---|------|------| +| T08 | 新增 sync 策略必须先定义于 `sync/policy`，再实现于 `sync/tasks` | 禁止直接在 orchestrator 中硬编码策略逻辑 | + +### Tier 6–7（Skill / Workflow 层） + +| # | 规则 | 说明 | +|---|------|------| +| T09 | `skill_runtime::executor` 必须自包含副作用描述 | 每个 Skill 的 entry_script 必须声明读写范围 | +| T10 | Workflow 新增 `StepType` 只需改动 `workflow/model` → `parser` → `executor`，不影响 Skill Runtime | 见 [dependency-topology.md](./dependency-topology.md) §Tier 7 | + +### Tier 9–10（MCP / TUI 层） + +| # | 规则 | 说明 | +|---|------|------| +| T11 | `mcp/tools/*` 不得直接调用 `rusqlite::Connection`，必须通过 `registry` 封装 | 已知例外：`repo.rs`、`repo/nl_query.rs`、`brief.rs`、`impact.rs` | +| T12 | `tui/render/*` 是纯消费者层，禁止写入 registry | TUI 状态机只读取，不写入 | + +--- + +## 历史说明 + +- 本文件继承并统一了原 `AGENTS.md` 中的 RF-1 ~ RF-7 与 `docs/architecture/invariants.md` 的 G/T 表。 +- 为减少 Agent 认知负担，统一采用 **G/T 编号体系**：G 表示全局（Global），T 表示分层（Tier）。 diff --git a/.knowledge/architecture/project-worktree.md b/.knowledge/architecture/project-worktree.md new file mode 100644 index 0000000..256ed31 --- /dev/null +++ b/.knowledge/architecture/project-worktree.md @@ -0,0 +1,261 @@ +--- +type: ArchitectureTopology +title: devbase 项目工作树（Project Worktree） +description: 按实际文件系统整理的 devbase 项目结构，用于 Agent 快速定位模块与文件。与 AGENTS.md 末尾的“完整项目结构参考”保持同步。 +version: 0.20.1 +schema_version: 36 +mcp_tools: 71 +crates: 12 +tests: 616+ +timestamp: 2026-06-25T11:28:04Z +tags: [architecture, worktree, project-structure, topology] +--- + +# devbase 项目工作树 + +> 本文件按实际目录列出 devbase 的关键文件与模块职责。它是 AGENTS.md 中“完整项目结构参考”的 OKF 归档版本。若目录结构发生变更，请同步更新两者。 + +--- + +## 顶层布局 + +```text +devbase/ +├── .cargo/ # 本地 Cargo 配置（RUST_TEST_THREADS=1） +├── .github/ # CI / Release workflows +├── .knowledge/ # OKF Knowledge Bundle（架构、Registry、MCP、开发规范） +│ ├── index.md # Bundle 总入口 +│ ├── architecture/ # 架构概念文档 +│ ├── registry/ # Registry Schema / 迁移策略 +│ ├── mcp/ # MCP 工具规范 +│ ├── development/ # 构建、测试、代码风格 +│ └── log.md # Bundle 变更日志 +├── benches/ # Criterion 基准测试 +├── crates/ # 12 个独立 workspace crate（零内部耦合） +├── docs/ # 人类可读文档导航 +├── examples/ # 可运行示例与集成演示 +├── scripts/ # 安装脚本与 CI 辅助 +├── skills/ # 示例 Skill +├── src/ # 主应用程序（30+ 模块） +├── tests/ # 集成测试 +├── AGENTS.md # Agent 入口指引（本项目门面文件） +├── CLAUDE.md # Claude Code 专用指引 +├── Cargo.toml # Workspace 配置 +├── README.md # 项目首页 +└── ... # 许可证、贡献指南、CHANGELOG 等 +``` + +--- + +## `src/` 主应用程序 + +### 交互层（Application / Protocol） + +```text +src/ +├── main.rs # CLI 入口：命令解析与分发（RF-4 ≤ 1000 行） +├── lib.rs # 导出 30+ 模块 +├── commands/ # 9 类 CLI 子命令 +│ ├── mod.rs +│ ├── analysis.rs +│ ├── knowledge.rs +│ ├── limit.rs +│ ├── ontology.rs +│ ├── repo.rs +│ ├── simple.rs +│ ├── skill.rs +│ ├── system.rs +│ └── workflow.rs +├── tui/ # ratatui 终端仪表盘 +│ ├── mod.rs +│ ├── event.rs # 键盘/异步事件路由 +│ ├── layout.rs # 响应式布局 +│ ├── theme.rs # Design Token 与色彩语义 +│ ├── render/ # 渲染组件（list/detail/popups/help/logs） +│ └── state/ # TUI 状态机 +└── mcp/ # MCP Server（stdio，71 个工具） + ├── mod.rs # McpTool trait、McpToolEnum、请求路由 + ├── clients.rs # MCP 客户端适配 + ├── tests.rs # MCP 单元测试 + └── tools/ # 71 个工具实现 + ├── mod.rs + ├── repo.rs + ├── query.rs + ├── vault.rs + ├── skill.rs + ├── context.rs + └── ... # 其他工具分组 +``` + +### 编译层（Compilation / Knowledge） + +```text +src/ +├── registry/ # SQLite Registry：schema、迁移、实体、关系 +│ ├── migrate.rs # CURRENT_SCHEMA_VERSION = 36 +│ ├── test_helpers.rs # SCHEMA_DDL（内存测试 schema） +│ ├── entity.rs +│ ├── relation.rs +│ ├── repo.rs +│ ├── workspace.rs +│ ├── knowledge.rs +│ ├── knowledge_meta.rs +│ ├── vault.rs +│ ├── code_symbols.rs +│ ├── call_graph.rs +│ ├── dead_code.rs +│ ├── links.rs +│ ├── metrics.rs +│ ├── known_limits.rs +│ ├── import_ontology.rs +│ ├── agent_context.rs +│ ├── health.rs +│ └── tests.rs +├── repository/ # 仓库抽象（对 registry 的业务封装） +│ ├── mod.rs +│ ├── repo.rs +│ ├── workspace.rs +│ ├── dependency.rs +│ ├── health.rs +│ ├── knowledge.rs +│ ├── search.rs +│ └── symbol.rs +├── search/ # Tantivy BM25 + 向量混合检索 +│ ├── mod.rs +│ ├── hybrid.rs # 混合检索编排 +│ └── symbol_index.rs # 符号索引 +├── semantic_index/ # tree-sitter 代码符号提取 +│ ├── mod.rs +│ ├── symbol.rs +│ ├── call_graph.rs +│ ├── git_diff.rs +│ └── persist.rs +├── vault/ # PARA 笔记系统 +│ ├── mod.rs +│ ├── scanner.rs # Vault 目录扫描 +│ ├── indexer.rs # Tantivy 索引 +│ ├── frontmatter.rs # YAML frontmatter 解析 +│ ├── wikilink.rs # [[wikilink]] 解析 +│ ├── backlinks.rs # 反向链接 + BFS 图遍历 +│ ├── fs_io.rs # Vault 文件原子操作 +│ ├── history.rs # 历史追踪 +│ └── export.rs # 导出功能 +├── skill_runtime/ # Skill 生命周期 +│ ├── mod.rs +│ ├── parser.rs # SKILL.md 解析 +│ ├── registry.rs # Skill 注册表 CRUD +│ ├── discover.rs # Skill 发现 +│ ├── dependency.rs # Skill 依赖拓扑 +│ ├── executor.rs # Skill 执行器 +│ ├── scoring.rs # Skill 评分 +│ ├── publish.rs # Skill 发布 +│ ├── sources.rs # Skill 源管理 +│ ├── clarity_sync.rs # Clarity 同步 +│ └── sync_adapter.rs +├── skill_sync.rs # Vault → Skill 导出桥接 +├── workflow/ # YAML 工作流引擎 +│ ├── mod.rs +│ ├── model.rs # 数据模型 +│ ├── parser.rs # YAML 解析 +│ ├── validator.rs # 工作流验证 +│ ├── scheduler.rs # 拓扑调度 +│ ├── executor.rs # DAG 执行器 +│ ├── interpolate.rs # 变量插值 +│ └── state.rs # 执行状态 +├── knowledge_engine/ # README 摘要、关键词、模块信息探测 +│ ├── mod.rs +│ ├── readme.rs +│ ├── module.rs +│ ├── index.rs +│ ├── index_state.rs +│ ├── llm.rs +│ └── fallback.rs +└── sync/ # 仓库同步编排 + ├── mod.rs + ├── orchestrator.rs + ├── policy.rs + ├── tasks.rs + └── tests.rs +``` + +### 可靠层与基础能力（Reliability / Storage / Utilities） + +```text +src/ +├── storage.rs # StorageBackend trait + AppContext（依赖注入容器） +├── config.rs # 配置结构体 +├── i18n/ # 国际化 +│ ├── mod.rs +│ ├── en.rs +│ └── zh_cn.rs +├── core/ # 原子类型（Node / Edge / NodeType） +│ ├── mod.rs +│ └── node.rs +├── asyncgit.rs # 异步 Git 通知通道 +├── scan.rs # 仓库扫描入口 +├── query.rs # 结构化查询表达式 +├── health.rs # 健康状态计算 +│ └── env_cache.rs +├── oplog_analytics.rs # 操作日志与覆盖率分析 +├── backup.rs # Schema 迁移前自动快照 +├── watch.rs # 目录监控 +├── dependency_graph.rs # 跨仓库依赖图 +├── symbol_links.rs # 符号链接（RE-EXPORT ONLY） +├── discovery_engine.rs # 跨仓库发现 +├── embedding.rs # 向量嵌入封装 +├── digest.rs # 摘要/哈希工具 +├── arxiv.rs # arXiv 元数据抓取 +├── greptime.rs # GreptimeDB 可选集成 +├── syncthing_client.rs # Syncthing 客户端 +├── sync_protocol.rs # 同步协议基础类型 +├── clients.rs # 通用客户端 +├── daemon.rs # 守护进程入口 +├── test_utils.rs # 测试辅助 +└── lib.rs / main.rs +``` + +--- + +## `crates/` — 12 个 Workspace Crate + +```text +crates/ +├── devbase-core-types # 最底层：Node / Edge / NodeType 核心类型 +├── devbase-registry # Registry 核心逻辑 +├── devbase-embedding # 本地文本嵌入（Candle + Ollama） +├── devbase-vault-wikilink # WikiLink 解析器 +├── devbase-vault-frontmatter # Vault Frontmatter 解析 +├── devbase-skill-runtime-parser # Skill 运行时解析器 +├── devbase-skill-runtime-types # Skill 运行时类型 +├── devbase-symbol-links # 符号链接 +├── devbase-sync-protocol # 同步协议 +├── devbase-syncthing-client # Syncthing 客户端 +├── devbase-workflow-model # Workflow 数据模型 +└── devbase-workflow-interpolate # Workflow 变量插值 +``` + +--- + +## 依赖方向 + +```text +devbase-core-types （零内部耦合） + ↓ +{ devbase-registry, devbase-embedding, devbase-vault-*, devbase-skill-runtime-*, + devbase-symbol-links, devbase-sync-protocol, devbase-syncthing-client, + devbase-workflow-* } + ↓ +src/ 各模块（commands, tui, mcp, registry, search, vault, skill_runtime, workflow, ...） +``` + +- `devbase-core-types` 为最底层基础 crate，禁止依赖任何 devbase 内部 crate。 +- `crates/` 内各 crate 禁止直接调用主 crate (`src/`) 的 `crate::` 路径。 +- `src/` 各模块可聚合所有 crate 与内部模块能力，`main.rs` 为唯一二进制入口。 + +--- + +## 维护提示 + +- 新增/删除 `src/` 顶层模块时，同步更新 `src/lib.rs` 的导出。 +- 新增/删除 `crates/` 成员时，同步更新 `Cargo.toml` workspace members 与本文档。 +- 工具数、Schema 版本、测试数等关键数字变更时，同步更新 `README.md`、`AGENTS.md`、`CLAUDE.md`、`.knowledge/index.md` 与本文件 frontmatter。 diff --git a/.knowledge/architecture/three-layer-model.md b/.knowledge/architecture/three-layer-model.md new file mode 100644 index 0000000..7daa930 --- /dev/null +++ b/.knowledge/architecture/three-layer-model.md @@ -0,0 +1,108 @@ +--- +type: ArchitectureModel +title: devbase 三层架构模型 +description: 交互层、编译层、可靠层的职责划分与数据流转。 +timestamp: 2026-06-25T11:15:50Z +tags: [architecture, three-layer-model, data-flow] +--- + +# devbase 三层架构模型 + +```text +┌─────────────────────────────────────────┐ +│ 交互层（Application / Protocol Layer） │ +│ • TUI 仪表盘（ratatui） │ +│ • CLI 子命令（clap） │ +│ • MCP Server（stdio，71 tools） │ +│ • Workflow 引擎（YAML 编排） │ +├─────────────────────────────────────────┤ +│ 编译层（Compilation / Knowledge Layer） │ +│ 感知 → 知识 → 策略 │ +│ • scan / vault/scanner / discovery │ +│ • entities / relations / embeddings │ +│ • query / health / search/hybrid │ +│ • sync / skill_runtime / workflow │ +├─────────────────────────────────────────┤ +│ 可靠层（Reliability / Storage Layer） │ +│ • SQLite（WAL 模式） │ +│ • Tantivy 全文/符号索引 │ +│ • OpLog 操作审计 │ +│ • 迁移前自动备份 │ +└─────────────────────────────────────────┘ +``` + +## 交互层 + +**职责**：为人类开发者和 AI Agent 提供接口。 + +| 接口 | 实现 | 关键模块 | +|------|------|----------| +| CLI | `clap` derive | `src/main.rs`, `src/commands/` | +| TUI | `ratatui` + `crossterm` | `src/tui/` | +| MCP Server | stdio JSON-RPC 2.0 | `src/mcp/` | +| Workflow | YAML DSL | `src/workflow/` | + +**约束**： +- TUI 是纯消费者层，禁止写入 registry（T12）。 +- MCP Tool 不得直接调用 `rusqlite::Connection`，必须通过 `registry` 封装（T11）。 +- 所有状态变更 MCP tool 必须幂等（G3）。 + +## 编译层 + +**职责**：把无结构的本地资产转化为结构化情境。 + +### 感知 + +| 模块 | 输入 | 输出 | +|------|------|------| +| `scan` | 文件系统 | Git 仓库、语言检测、代码统计 | +| `vault/scanner` | Markdown 笔记 | frontmatter、wikilink | +| `discovery_engine` | Cargo.toml / package.json | 跨仓库依赖关联 | + +### 知识 + +| 模块 | 输入 | 输出 | +|------|------|------| +| `registry` | 感知层数据 | SQLite 中的 entities / relations / repos / vault_notes | +| `semantic_index` | 源码文件 | tree-sitter 符号、调用图 | +| `embedding` | 文本 | f32 向量、cosine_similarity | +| `symbol_links` | code_symbols | 相似签名、同文件聚类关系 | + +### 策略 + +| 模块 | 职责 | +|------|------| +| `query` | 结构化查询：`lang:rust stale:>30` | +| `health` | dirty / ahead / behind / diverged | +| `search/hybrid` | BM25 + 向量 RRF 融合 | +| `sync` | 批量同步编排 | +| `skill_runtime` | Skill 发现/安装/执行/评分/发布 | +| `workflow` | YAML 工作流调度与执行 | + +## 可靠层 + +**职责**：保证数据安全、可审计、可恢复。 + +| 组件 | 技术 | 说明 | +|------|------|------| +| Registry DB | SQLite + WAL | `registry.db`，bundled 模式 | +| 全文索引 | Tantivy | `search_index/` | +| 符号索引 | Tantivy | `symbol_index/` | +| 审计 | OpLog | 所有 scan/sync/health 自动记录 | +| 备份 | 自动快照 | Schema 迁移前生成 `backup-YYYYMMDD-HHMMSS.db` | + +## 数据流转示例 + +```text +1. scan 发现本地仓库 + └─ index 提取模块结构（cargo metadata） + └─ semantic_index 提取符号 + 调用图 + +2. registry 存储 repo 元数据、符号、调用边 + +3. query / search/hybrid / project_context 聚合查询 + +4. MCP Server 将 JSON 传给 AI Agent + +5. TUI 为人类展示仓库健康状态 +``` diff --git a/.knowledge/development/build-and-test.md b/.knowledge/development/build-and-test.md new file mode 100644 index 0000000..21f8cce --- /dev/null +++ b/.knowledge/development/build-and-test.md @@ -0,0 +1,65 @@ +--- +type: HowToGuide +title: devbase 构建、运行与测试指南 +description: 环境要求、常用命令、测试策略。 +timestamp: 2026-06-25T11:15:50Z +tags: [development, build, test, howto] +--- + +# devbase 构建、运行与测试指南 + +## 环境要求 + +- **Rust 1.95.0+** +- 主要开发/CI 平台：**Windows**（Linux/macOS 社区支持） +- 可选：`sccache` 可显著加速 tree-sitter grammar 的 C 编译 + +## 常用命令 + +```powershell +# 构建 +cargo build --release + +# 本地快速体验 +cargo run -- scan . --register +cargo run -- tui +cargo run -- mcp + +# 测试（与 CI 一致） +cargo test --all-targets +cargo test --workspace -- --test-threads=4 + +# 静态检查 +cargo clippy --all-targets -D warnings +cargo fmt --check + +# 审计 +cargo audit + +# 架构不变量检查（CI 的 invariant job） +scripts/invariant-checks/run-checks.ps1 +``` + +## 测试策略 + +- **单元测试**：分布在 `src/**/tests.rs` 与 `#[cfg(test)]` 块中。 +- **集成测试**：`tests/cli.rs`，使用 `assert_cmd` + `tempfile`。 +- **Crate 测试**：每个 `crates/*/src/*.rs` 自带测试。 +- **Bench**：`criterion` 驱动的 `benches/`。 +- **测试隔离**： + - 所有 IO 测试使用 `TempDir` 与 `StorageBackend` 注入。 + - `.cargo/config.toml` 默认 `RUST_TEST_THREADS=1`；CI 使用 `--test-threads=4`。 + - `git2` 测试必须显式 `Signature::now("Test", "test@example.com")` 与 `repo.set_head("refs/heads/main")`。 + +## Feature 说明 + +```toml +default = ["tui", "mcp", "lang-rust", "lang-python", "lang-js-ts", "lang-go"] +``` + +- `tui`：终端仪表盘 +- `mcp`：MCP Server +- `lang-*`：tree-sitter 语言支持 +- `embedding`：本地 embedding（默认不包含） +- `greptimedb`：可选 GreptimeDB 写入 +- `watch`：目录监控 diff --git a/.knowledge/development/code-style.md b/.knowledge/development/code-style.md new file mode 100644 index 0000000..83a2367 --- /dev/null +++ b/.knowledge/development/code-style.md @@ -0,0 +1,69 @@ +--- +type: StyleGuide +title: devbase 代码风格与提交规范 +description: rustfmt 配置、Conventional Commits、源文件头、架构红线。 +timestamp: 2026-06-25T11:15:50Z +tags: [development, style, commits, guidelines] +--- + +# devbase 代码风格与提交规范 + +## 格式化 + +`rustfmt.toml`： + +```toml +edition = "2024" +max_width = 100 +chain_width = 80 +fn_call_width = 80 +struct_lit_width = 30 +array_width = 80 +reorder_imports = true +``` + +## 提交规范（Conventional Commits） + +``` +feat: 新功能 +fix: Bug 修复 +docs: 文档更新 +refactor: 重构（无行为变更） +test: 测试相关 +chore: 构建/工具链 +perf: 性能优化 +``` + +示例： + +``` +feat(mcp): add devkit_skill_validate tool +``` + +## 源文件头 + +新增源文件应在顶部包含 SPDX 许可证头： + +```rust +// SPDX-License-Identifier: AGPL-3.0-or-later +// Copyright (c) 2026 juice094 +``` + +> 历史文件可能仍使用 `MIT` SPDX 头，新文件统一使用 AGPL。 + +## 工具使用约定 + +- **读文件**：优先使用 `Read` 工具；不要直接用 `cat`/`head`。 +- **搜索**：优先使用 `Grep`/`Glob`；不要直接用 shell `grep`/`find`。 +- **小修改**：使用 `Edit`。 +- **整文件/新建**：使用 `Write`。 +- **多文件操作/构建/测试**：使用 `Bash`。 + +## 架构红线速查 + +完整清单见 [.knowledge/architecture/invariants.md](../architecture/invariants.md)。 + +- G5：生产代码禁止 `unwrap()` / `expect()` / `panic!()`。 +- G1：禁止新增全局硬编码路径，走 `StorageBackend` / `AppContext`。 +- G4：`main.rs` 不得超过 1000 行。 +- G3：`SCHEMA_DDL` 与 `migrate.rs` 必须同步。 diff --git a/.knowledge/development/index.md b/.knowledge/development/index.md new file mode 100644 index 0000000..5acd453 --- /dev/null +++ b/.knowledge/development/index.md @@ -0,0 +1,26 @@ +--- +type: ConceptIndex +title: devbase 开发规范索引 +description: 构建、测试、代码风格、提交规范等开发约定。 +timestamp: 2026-06-25T11:15:50Z +tags: [development, guidelines, index] +--- + +# devbase 开发规范索引 + +## 快速链接 + +| 主题 | 文档 | +|------|------| +| 构建与测试 | [build-and-test.md](./build-and-test.md) | +| 代码风格与提交规范 | [code-style.md](./code-style.md) | + +## 提交前必须通过 + +```powershell +cargo test --all-targets +cargo clippy --all-targets -D warnings +cargo fmt --check +``` + +仓库已配置 `.githooks/pre-commit` 执行 `cargo fmt --check` 与 `cargo clippy --all-targets -- -D warnings`。 diff --git a/.knowledge/index.md b/.knowledge/index.md new file mode 100644 index 0000000..528c9ae --- /dev/null +++ b/.knowledge/index.md @@ -0,0 +1,65 @@ +--- +type: KnowledgeBundleIndex +title: devbase Knowledge Bundle +description: AI Agent 的 devbase 项目认知入口，包含架构、Registry、MCP、开发规范等概念文档。 +version: 0.20.1 +schema_version: 36 +mcp_tools: 71 +crates: 12 +tests: 616+ +timestamp: 2026-06-25T11:15:50Z +tags: [agent-instruction, devbase, architecture, onboarding] +--- + +# devbase Knowledge Bundle + +> **面向 AI Agent 的项目认知包**。本 bundle 用 [Open Knowledge Format (OKF)](https://www.gitbook.com/blog/what-is-okf-open-knowledge-format) 组织：每个 `.md` 文件描述一个概念，文件之间用 Markdown 链接关联。 + +## 项目速览 + +- **名称**：devbase +- **版本**：0.20.1 +- **定位**：开发者工作空间的世界模型编译器 +- **核心能力**：把本地代码库、PARA 笔记、Skill 脚本编译为 AI 可推理的结构化情境 +- **交互接口**：CLI / TUI / MCP Server（stdio，71 个 tools） + +## 快速入口 + +| 我想了解 | 读这个 | +|----------|--------| +| 项目整体架构 | [architecture/index.md](./architecture/index.md) | +| 三层架构（交互/编译/可靠） | [architecture/three-layer-model.md](./architecture/three-layer-model.md) | +| 模块依赖拓扑（11-Tier） | [architecture/dependency-topology.md](./architecture/dependency-topology.md) | +| 架构红线与不变量 | [architecture/invariants.md](./architecture/invariants.md) | +| Registry Schema 与迁移 | [registry/index.md](./registry/index.md) | +| MCP Tool 添加路径 | [mcp/tool-adding-guide.md](./mcp/tool-adding-guide.md) | +| 构建、测试、提交规范 | [development/index.md](./development/index.md) | +| 本 bundle 的变更历史 | [log.md](./log.md) | + +## 关键数字（由代码实际状态维护） + +| 指标 | 数值 | 验证来源 | +|------|------|----------| +| MCP Tools | 71 | `src/mcp/mod.rs` `McpToolEnum` | +| Workspace Crates | 12 | `crates/` 目录 | +| 测试函数 | 616+ | `cargo test --workspace -- --list` | +| Schema 版本 | v36 | `src/registry/migrate.rs` `CURRENT_SCHEMA_VERSION` | +| 主入口行数 | 836 行 | `src/main.rs` | +| 生产 unwrap | 0 | 架构红线 G5 | + +## 核心红线（违反任何一条 → 必须 halt） + +1. **依赖注入优于全局状态**（G1 / RF-1）：禁止新增 `dirs::data_local_dir()` / `std::env::var_os` 硬编码路径。 +2. **测试密封性**（G2 / RF-2）：测试禁止修改全局进程状态，文件系统测试用 `tempfile` + `StorageBackend`。 +3. **Schema 单一事实来源**（G3 / RF-3）：`SCHEMA_DDL` 与 `migrate.rs` 必须同步。 +4. **二进制入口限界**（G4 / RF-4）：`main.rs` 不得超过 1000 行。 +5. **生产代码无 panic**（G5 / RF-6）：禁止 `unwrap()` / `expect()` / `panic!()`。 +6. **无循环依赖**（G6 / RF-5）：禁止模块间双向 `use crate::` 引用。 +7. **Workspace 拆分约束**（G7 / RF-7）：新增模块若对 devbase 内部其他模块的 `crate::` 引用超过 5 个，禁止提取为 workspace crate。 + +## 给 Agent 的使用建议 + +1. **先读本 bundle，再查代码**：复杂任务先通过 [dependency-topology.md](./architecture/dependency-topology.md) 定位层级，再深入具体模块。 +2. **改 Schema 前先读 Registry 文档**：任何 `registry.db` 表结构变更必须遵循 [migration-policy.md](./registry/migration-policy.md)。 +3. **添加 MCP Tool 走标准路径**：见 [tool-adding-guide.md](./mcp/tool-adding-guide.md)。 +4. **保持 AGENTS.md 入口简短**：人类/Agent 首次进入项目时，`AGENTS.md` 会指向本 bundle。 diff --git a/.knowledge/log.md b/.knowledge/log.md new file mode 100644 index 0000000..4553f14 --- /dev/null +++ b/.knowledge/log.md @@ -0,0 +1,97 @@ +--- +type: ChangeLog +title: devbase Knowledge Bundle 变更日志 +description: 记录 .knowledge/ OKF bundle 的结构变更与数据更新。 +timestamp: 2026-06-25T11:15:50Z +tags: [meta, okf, changelog] +--- + +# devbase Knowledge Bundle 变更日志 + +## 2026-06-25 — OKF Bundle 初始化 + +- 类型：`refactor` +- 范围：`.knowledge/`、`AGENTS.md`、`docs/architecture/` + +### 变更内容 + +1. 在项目根创建 `.knowledge/` OKF bundle，将原本散落在 `AGENTS.md`、`docs/architecture/overview.md`、`docs/architecture/dependency-topology.md`、`docs/architecture/invariants.md` 中的架构/拓扑/规范知识拆分为独立概念文档。 +2. 重写 `AGENTS.md` 为 OKF 入口索引，顶部添加 YAML frontmatter，正文仅保留核心红线和指向本 bundle 的链接。 +3. 修复多处数据不一致： + - MCP Tools：统一为 **71** 个（以 `src/mcp/mod.rs` `McpToolEnum` 为准） + - Registry Schema：统一为 **v36**（以 `src/registry/migrate.rs` 为准） + - 项目版本：统一为 **v0.20.1** + - `main.rs` 行数：统一为 **836** 行 +4. 统一架构红线编号为 **G/T 体系**（全局不变量 G1–G7 + 分层不变量 T01–T12），替代原 AGENTS.md 的 RF-1–RF-7。 + +### 新增概念文档 + +- `.knowledge/index.md` +- `.knowledge/architecture/index.md` +- `.knowledge/architecture/three-layer-model.md` +- `.knowledge/architecture/dependency-topology.md` +- `.knowledge/architecture/invariants.md` +- `.knowledge/registry/index.md` +- `.knowledge/registry/schema.md` +- `.knowledge/registry/migration-policy.md` +- `.knowledge/mcp/index.md` +- `.knowledge/mcp/tool-adding-guide.md` +- `.knowledge/development/index.md` +- `.knowledge/development/build-and-test.md` +- `.knowledge/development/code-style.md` +- `.knowledge/log.md` + +### 向后兼容说明 + +- `AGENTS.md` 仍保留在项目根，Kimi / Claude 等 Agent 的既有读取路径不受影响。 +- `docs/architecture/` 中的原始文档保留，但关键数据已更新；未来逐步将深度内容迁移至 `.knowledge/`。 + +## 2026-06-25 — AGENTS.md 与 OKF bundle 进一步整理 + +- 类型：`docs` +- 范围：`AGENTS.md`、`.knowledge/architecture/project-worktree.md`、`docs/README.md`、`docs/architecture/invariants.md` + +### 变更内容 + +1. 在 `AGENTS.md` 末尾新增“完整项目结构参考”，将项目 worktree 直接放入 Agent 入口文件，降低新 Agent 探索成本。 +2. 按 OKF 标准新增 `.knowledge/architecture/project-worktree.md`，作为项目工作树的权威归档版本，frontmatter 类型为 `ArchitectureTopology`。 +3. 同步更新 `AGENTS.md` 的“模块地图”，增加“关键文件”列。 +4. 修复 `docs/architecture/invariants.md` 顶部缺失的迁移提示，指向 `.knowledge/architecture/invariants.md`。 +5. 更新 `docs/README.md`： + - `main.rs` 行数：833 → 836 + - Agent 架构/不变量/拓扑链接：从 `docs/architecture/*` 指向 `.knowledge/architecture/*` + - 文档目录中明确标注历史架构文档已迁移，并新增 OKF 权威入口链接。 +6. 统一 AGENTS.md / CLAUDE.md / `.knowledge/index.md` 的红线编号映射（G1–G7 ↔ RF-1–RF-7）。 + +## 2026-06-25 — 归档历史架构文档 + +- 类型：`docs` +- 范围：`docs/architecture/` → `docs/_archive/`，`docs/README.md`、`SUPPORT.md`、`CONTRIBUTING.md`、`README.md`、`docs/guides/ai-instance-handoff.md`、`docs/reference/entities-model.md`、`docs/_audit/six-dimension-gap-analysis-20260430.md` + +### 变更内容 + +1. 将以下 4 份历史架构/拓扑/不变量文档从 `docs/architecture/` 归档至 `docs/_archive/`： + - `overview.md` → `_archive/overview.md` + - `context-compiler.md` → `_archive/context-compiler.md` + - `dependency-topology.md` → `_archive/dependency-topology.md` + - `invariants.md` → `_archive/invariants.md` +2. 更新 `docs/README.md`： + - 从“架构设计”表格移除上述 4 份历史文档。 + - 在“归档”表格注册上述 4 份文档，并标注迁移目标。 +3. 更新所有指向旧路径的活跃链接： + - `SUPPORT.md`：Architecture / Architecture Guardrails → `.knowledge/architecture/` + - `CONTRIBUTING.md`：架构参考 → `.knowledge/architecture/` + - `README.md`：可靠性红线 → `.knowledge/architecture/invariants.md` + - `docs/guides/ai-instance-handoff.md`：架构图/拓扑 → `.knowledge/architecture/` + - `docs/reference/entities-model.md`：情境编译器 → `.knowledge/architecture/` + - `docs/_audit/six-dimension-gap-analysis-20260430.md`：标注 context-compiler.md 已归档 +4. `docs/architecture/` 下保留继续维护的技术性文档：ADR、Workspace 拆分计划、Workflow DSL 规范等。 + +### 关键数字 + +- MCP Tools：**71** +- Registry Schema：**v36** +- 项目版本：**v0.20.1** +- `main.rs` 行数：**836** +- 测试函数：**616+** +- Workspace Crates：**12** diff --git a/.knowledge/mcp/index.md b/.knowledge/mcp/index.md new file mode 100644 index 0000000..38858ca --- /dev/null +++ b/.knowledge/mcp/index.md @@ -0,0 +1,45 @@ +--- +type: ConceptIndex +title: devbase MCP 概念索引 +description: MCP Server 架构、工具分类、添加路径。 +timestamp: 2026-06-25T11:15:50Z +tags: [mcp, tools, protocol, index] +--- + +# devbase MCP 概念索引 + +## 概述 + +devbase 通过 **Model Context Protocol (MCP)** 向 AI Agent 暴露能力。传输层为 **stdio only**，不暴露网络端口。 + +## 关键数字 + +- **MCP Tools**：71 个（见 `src/mcp/mod.rs` `McpToolEnum`） +- **传输**：stdio JSON-RPC 2.0 +- **启动命令**：`devbase mcp [--tools stable,beta,experimental]` + +## 工具分类 + +| 域 | 代表 Tools | 说明 | +|----|-----------|------| +| 仓库管理 | `devkit_scan`, `devkit_health`, `devkit_sync`, `devkit_status` | 核心高频 | +| 查询检索 | `devkit_query`, `devkit_query_repos`, `devkit_natural_language_query` | DSL + 自然语言 | +| 索引分析 | `devkit_index`, `devkit_index_stream`, `devkit_index_health` | 代码语义索引 | +| 代码分析 | `devkit_code_metrics`, `devkit_module_graph`, `devkit_call_graph`, `devkit_dead_code`, `devkit_code_symbols` | 静态分析 | +| Vault 笔记 | `devkit_vault_search/read/write/backlinks/daily/graph/history/export` | PARA 知识系统 | +| Skill | `devkit_skill_list/search/run/discover/sync` | Skill 生命周期 | +| 工作流 | `devkit_workflow_list/run/status` | YAML 编排 | +| Session | `devkit_session_save/list/resume/attach/detach/...` | Agent 会话记忆 | +| 关系/本体 | `devkit_relation_store/query/delete`, `devkit_ontology_import` | 知识图谱 | +| 搜索质量 | `devkit_hybrid_search`, `devkit_search_quality`, `devkit_cross_repo_search` | BM25 + 向量混合 | + +## 快速定位 + +- Tool trait 定义：`src/mcp/mod.rs` `McpTool` +- Tool 实现目录：`src/mcp/tools/` +- Tool 路由枚举：`src/mcp/mod.rs` `McpToolEnum` +- 稳定性分级：`ToolTier`（Stable / Beta / Experimental） + +## 相关文档 + +- [tool-adding-guide.md](./tool-adding-guide.md) — 添加新 Tool 的标准路径 diff --git a/.knowledge/mcp/tool-adding-guide.md b/.knowledge/mcp/tool-adding-guide.md new file mode 100644 index 0000000..707b01a --- /dev/null +++ b/.knowledge/mcp/tool-adding-guide.md @@ -0,0 +1,56 @@ +--- +type: HowToGuide +title: 添加 MCP Tool 的标准路径 +description: 在 devbase 中新增一个 MCP Tool 必须遵循的 6 步流程。 +timestamp: 2026-06-25T11:15:50Z +tags: [mcp, tools, howto, onboarding] +--- + +# 添加 MCP Tool 的标准路径 + +## 6 步流程 + +1. **新建模块** + - 在 `src/mcp/tools/` 新建模块（如 `my_feature.rs`）。 + +2. **实现 `McpTool` trait** + ```rust + pub trait McpTool: Send + Sync + Clone { + fn name(&self) -> &'static str; + fn schema(&self) -> serde_json::Value; + async fn invoke(&self, args: Value, ctx: &mut AppContext) -> Result; + async fn invoke_stream(...) -> Result> { ... } + } + ``` + +3. **注册并 `pub use`** + - 在 `src/mcp/tools/mod.rs` 注册模块并 `pub use`。 + +4. **加入路由枚举** + - 在 `src/mcp/mod.rs` 的 `McpToolEnum` 中加入该工具。 + +5. **添加单元测试** + - 在 `src/mcp/tests.rs` 或工具模块的 `#[cfg(test)]` 块中添加测试。 + +6. **更新文档** + - 更新 `README.md` Tool 矩阵。 + - 更新 `.knowledge/index.md` 的 `mcp_tools` 数字。 + +## 核心原则 + +- **所有状态变更操作必须幂等**（`ON CONFLICT ... DO UPDATE/NOTHING`）。 +- **批量操作包裹在 SQLite transaction 中**。 +- **不得直接调用 `rusqlite::Connection`**，必须通过 `registry` 封装（T11，已知例外除外）。 +- **Breaking change 只能新增 tool，不能修改现有 schema**（G4）。 + +## 稳定性分级 + +添加新 tool 时选择初始 tier： + +| Tier | 含义 | 测试要求 | +|------|------|----------| +| `Stable` | 已长期验证，schema 冻结 | 完整单元测试 + 集成测试 | +| `Beta` | 已验证但可能微调 | 核心路径测试 | +| `Experimental` | 新功能，行为可能变化 | 至少 smoke test | + +新 tool 默认从 `Beta` 或 `Experimental` 开始，不要直接标记 `Stable`。 diff --git a/.knowledge/registry/index.md b/.knowledge/registry/index.md new file mode 100644 index 0000000..e11d3bf --- /dev/null +++ b/.knowledge/registry/index.md @@ -0,0 +1,33 @@ +--- +type: ConceptIndex +title: devbase Registry 概念索引 +description: SQLite Registry 相关概念：Schema、迁移、实体关系、操作规范。 +timestamp: 2026-06-25T11:15:50Z +tags: [registry, sqlite, schema, index] +--- + +# devbase Registry 概念索引 + +## 概述 + +Registry 是 devbase 的核心数据结构，使用 SQLite（WAL 模式）持久化所有被管理仓库、笔记、Skill、工作流、代码符号等元数据。 + +## 关键概念 + +| 概念 | 文档 | 说明 | +|------|------|------| +| Schema 总览 | [schema.md](./schema.md) | 当前 Schema v36 的核心表与职责 | +| 迁移策略 | [migration-policy.md](./migration-policy.md) | 如何安全地修改 Schema | + +## 快速定位 + +- Schema 定义：`src/registry/migrate.rs` +- 迁移脚本：`src/registry/migrations/v*.rs` +- 测试同步：`src/registry/test_helpers.rs` 的 `SCHEMA_DDL` +- 当前版本常量：`src/registry/migrate.rs` `CURRENT_SCHEMA_VERSION = 36` + +## 核心约定 + +1. 所有 Registry 写入必须留下 OpLog 审计痕迹。 +2. Schema 迁移前必须自动生成快照 `backup-YYYYMMDD-HHMMSS.db`。 +3. 禁止直接修改现有表的列定义；必须通过迁移脚本。 diff --git a/.knowledge/registry/migration-policy.md b/.knowledge/registry/migration-policy.md new file mode 100644 index 0000000..6b2b9db --- /dev/null +++ b/.knowledge/registry/migration-policy.md @@ -0,0 +1,44 @@ +--- +type: Policy +title: devbase Registry Schema 迁移策略 +description: 修改 SQLite Schema 必须遵循的安全流程与检查清单。 +timestamp: 2026-06-25T11:15:50Z +tags: [registry, schema, migration, policy] +--- + +# devbase Registry Schema 迁移策略 + +> 违反本策略的 Schema 变更必须回滚。 + +## 变更流程 + +```text +1. 在 migrate.rs 新增版本判断块 + ↓ +2. 使用 ALTER TABLE ... ADD COLUMN（SQLite 限制） + ↓ +3. 升级前调用 backup::auto_backup_before_migration() + ↓ +4. 同步更新 test_helpers.rs 的 SCHEMA_DDL + ↓ +5. 同步更新 AGENTS.md / .knowledge/ 中的 schema_version + ↓ +6. 跑 cargo test --all-targets +``` + +## 检查清单 + +- [ ] `CURRENT_SCHEMA_VERSION` 已递增。 +- [ ] 新增/修改的表在 `migrate.rs` 的 `CREATE TABLE IF NOT EXISTS` 中同步。 +- [ ] 新增字段通过 `ALTER TABLE ... ADD COLUMN` 或表重建实现。 +- [ ] `backup::auto_backup_before_migration()` 在迁移开始前调用。 +- [ ] `test_helpers.rs` 的 `SCHEMA_DDL` 与 `migrate.rs` 一致。 +- [ ] `oplog_analytics.rs` 中相关的表存在性检查已更新。 +- [ ] MCP tool schema 兼容性已审查（G4）。 +- [ ] `.knowledge/index.md` 和 `AGENTS.md` 的 `schema_version` 已更新。 + +## 禁止事项 + +- 禁止直接修改现有表的列定义。 +- 禁止在无迁移逻辑的情况下修改 registry schema。 +- 禁止 breaking change 通过修改现有 MCP tool schema 实现（必须新增 tool）。 diff --git a/.knowledge/registry/schema.md b/.knowledge/registry/schema.md new file mode 100644 index 0000000..a8611e3 --- /dev/null +++ b/.knowledge/registry/schema.md @@ -0,0 +1,91 @@ +--- +type: SchemaDefinition +title: devbase Registry Schema 总览 +description: SQLite Registry 当前 Schema v36 的核心表与职责说明。 +timestamp: 2026-06-25T11:15:50Z +tags: [registry, schema, sqlite] +--- + +# devbase Registry Schema 总览 + +> **当前版本**：v36（见 `src/registry/migrate.rs` `CURRENT_SCHEMA_VERSION`） +> **单一事实来源**：`src/registry/migrate.rs` +> **测试同步**：`src/registry/test_helpers.rs` 的 `SCHEMA_DDL` + +## 核心表 + +| 表名 | 职责 | 主要模块 | +|------|------|----------| +| `repos` | Git/非 Git 工作区元数据 | `scan`, `registry::repo` | +| `repo_tags` | 仓库标签多对多关系 | `registry::repo` | +| `repo_remotes` | 仓库远程地址 | `scan`, `registry::repo` | +| `code_symbols` | 代码符号（函数/结构体/枚举等） | `semantic_index`, `registry::code_symbols` | +| `code_embeddings` | 符号/文本的 embedding BLOB | `embedding`, `search/hybrid` | +| `code_call_graph` | 符号间调用关系 | `semantic_index`, `registry::call_graph` | +| `code_symbol_links` | 符号相似性/共位关系 | `symbol_links`, `registry::links` | +| `vault_notes` | Vault Markdown 笔记 | `vault/scanner`, `registry::vault` | +| `oplog` | 操作审计日志 | 所有 scan/sync/health 操作 | +| `papers` | 学术文献元数据 | `arxiv`, `mcp/tools/repo` | +| `experiments` | 实验记录 | `mcp/tools/repo` | +| `skills` | Skill 元数据 | `skill_runtime::registry` | +| `skill_executions` | Skill 执行历史 | `skill_runtime::executor`, `scoring` | +| `entities` | 统一实体模型实例 | `registry::entity` | +| `entity_types` | 可扩展的实体类型定义 | `registry::entity` | +| `relations` | 实体间有向关系 | `registry::relation` | +| `workflows` | 工作流定义 | `workflow::state` | +| `workflow_executions` | 工作流执行记录 | `workflow::state` | + +## 统一实体模型（Schema v16+） + +```sql +CREATE TABLE entity_types ( + name TEXT PRIMARY KEY, + schema_json TEXT NOT NULL, + description TEXT, + created_at TEXT NOT NULL +); + +CREATE TABLE entities ( + id TEXT PRIMARY KEY, + entity_type TEXT NOT NULL REFERENCES entity_types(name), + name TEXT NOT NULL, + source_url TEXT, + local_path TEXT, + metadata TEXT, + content_hash TEXT, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL +); + +CREATE TABLE relations ( + id TEXT PRIMARY KEY, + from_entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE, + to_entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE, + relation_type TEXT NOT NULL, + metadata TEXT, + confidence REAL NOT NULL DEFAULT 1.0, + created_at TEXT NOT NULL +); +``` + +## 存储位置 + +默认使用用户本地数据目录（可通过 `DEVBASE_DATA_DIR` 覆盖）： + +- Windows：`%LOCALAPPDATA%/devbase/` +- Linux：`~/.local/share/devbase/` +- macOS：`~/Library/Application Support/devbase/` + +目录内容： + +```text +devbase/ +├── registry.db # SQLite Registry（WAL 模式） +├── registry.db-wal +├── search_index/ # Tantivy 全文索引 +├── symbol_index/ # Tantivy 代码符号索引 +├── backups/ # 自动备份 +└── workspace/ + ├── vault/ # PARA 笔记 + └── assets/ # 二进制资源 +``` diff --git a/AGENTS.md b/AGENTS.md index 5798991..c887ffd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,508 +1,302 @@ -# Agent 环境指引 - -> 本文件面向不了解项目的 AI coding agent。它汇总了 `devbase` 的架构、构建、测试、安全与开发约定。请在修改代码前先阅读本文件，并遵循其中的红线与检查清单。 +--- +type: AgentInstruction +title: devbase Agent 环境指引 +description: devbase 项目入口指引。完整架构、规范与开发约定见 .knowledge/ OKF bundle。 +version: 0.20.1 +schema_version: 36 +mcp_tools: 71 +crates: 12 +tests: 616+ +timestamp: 2026-06-25T11:15:50Z +tags: [agent-instruction, devbase, rust, onboarding] +--- -## 1. 项目概览 +# devbase Agent 环境指引 -**devbase**（v0.20.1）是一个本地优先的开发者工作空间数据库与知识库管理器。它把代码仓库、笔记（Vault）、Skill 与工作流编译成 AI 可推理的结构化情境，核心职责是： +> **本文件是入口索引**。详细的项目架构、拓扑、Registry 规范、MCP 路径、开发规范见 [`.knowledge/index.md`](./.knowledge/index.md)。 -- **感知**：扫描 Git 仓库、分析代码结构、解析 Vault 笔记。 -- **编码**：把原始资产转化为统一实体模型（`Node`/`Edge`）、图谱关系、向量索引。 -- **持久化**：本地 SQLite Registry + Tantivy 全文/符号索引 + 文件系统 Workspace。 -- **检索**：通过 MCP（Model Context Protocol）向 AI 客户端暴露 71 个工具。 +## 项目速览 -项目主页：`https://github.com/juice094/devbase` -许可证：AGPL-3.0-or-later（双许可，商业使用需联系作者）。 +**devbase**（v0.20.1）是一个本地优先的开发者工作空间数据库与知识库管理器。它把代码仓库、PARA 笔记、Skill 与工作流编译为 AI 可推理的结构化情境。 -### 当前关键指标（基于仓库实际内容） +**一句话定位（适合简历/演讲）**：devbase 是“开发者工作空间的世界模型编译器”——用 Rust 将本地 Git 仓库、Markdown 笔记、Skill 脚本和工作流编译成 AI 可直接推理的结构化上下文，并通过 71 个 MCP 工具与 TUI 仪表盘对外提供服务。 | 指标 | 数值 | |------|------| -| 版本 | `0.20.1` | -| Rust Edition | `2024`（要求 rustc 1.95+） | -| Registry Schema | `v36`（`src/registry/migrate.rs`） | -| MCP Tools | **71** 个（`src/mcp/tools/*.rs` 中 `pub struct Devkit*Tool`） | -| 测试函数 | **616** 个（`cargo test --workspace -- --list`） | -| Ignored 测试 | 6 个（`#[ignore]` 在 `src/`） | -| Workspace Crates | **12** 个（`crates/` 目录） | -| `src/main.rs` 行数 | 833 行（RF-4 限界 1000 行内） | -| Clippy | `-D warnings` / CI `-W warnings` | -| 生产代码 `unwrap` | 0（架构红线 RF-6） | - -> 注意：仓库内原有文档可能写到“18/19 个 crate”“495 tests”“main.rs 515 行”，那是历史快照；本文件以当前文件系统与 `cargo test --workspace -- --list` 的实际输出为准。 - -## 2. 技术栈与依赖 - -| 用途 | 技术/库 | -|------|---------| -| CLI / 子命令 | `clap` derive | -| 异步运行时 | `tokio`（rt-multi-thread, macros, process, io-util, io-std, sync） | -| 数据库 | `rusqlite` + `r2d2`/`r2d2_sqlite`（WAL 模式，bundled） | -| 全文/符号检索 | `tantivy` | -| Git 操作 | `git2` | -| 代码解析 | `tree-sitter` + 可选 grammar（rust/python/typescript/go） | -| 终端 UI | `ratatui` + `crossterm`（feature `tui`） | -| 文件监控 | `notify`（feature `watch`） | -| HTTP | `reqwest` / `ureq`（embedding crate） | -| 序列化 | `serde`/`serde_json`/`serde_yaml` + `toml` | -| 日志 | `tracing`/`tracing-subscriber` | -| 哈希/并行 | `blake3`、`rayon`、`crossbeam-channel` | -| 构建/测试辅助 | `tempfile`、`assert_cmd`、`predicates`、`criterion`（bench） | - -### Cargo Features - -```toml -default = ["tui", "mcp", "lang-rust", "lang-python", "lang-js-ts", "lang-go"] -``` +| 版本 | 0.20.1 | +| Rust Edition | 2024（rustc 1.95+） | +| Registry Schema | v36 | +| MCP Tools | 71 | +| Workspace Crates | 12 | +| 测试 | 616+ | +| 主入口 `main.rs` | 836 行 | +| 生产 `unwrap` | 0 | + +## 知识包导航 + +| 想了解 | 去读 | +|--------|------| +| 完整项目地图 | [`.knowledge/index.md`](./.knowledge/index.md) | +| 三层架构与数据流 | [`.knowledge/architecture/three-layer-model.md`](./.knowledge/architecture/three-layer-model.md) | +| 11-Tier 模块依赖拓扑 | [`.knowledge/architecture/dependency-topology.md`](./.knowledge/architecture/dependency-topology.md) | +| 架构红线与不变量 | [`.knowledge/architecture/invariants.md`](./.knowledge/architecture/invariants.md) | +| Registry Schema 与迁移 | [`.knowledge/registry/`](./.knowledge/registry/index.md) | +| MCP Tool 添加路径 | [`.knowledge/mcp/tool-adding-guide.md`](./.knowledge/mcp/tool-adding-guide.md) | +| 构建、测试、风格规范 | [`.knowledge/development/`](./.knowledge/development/index.md) | +| 本 bundle 变更历史 | [`.knowledge/log.md`](./.knowledge/log.md) | + +## 模块地图（按三层架构） + +本项目采用 `src/` + `crates/` 的经典 Rust workspace 布局。`src/` 聚合所有功能模块，`crates/` 放置零内部耦合的可复用子 crate。 + +### 交互层（Application / Protocol） +人类与 AI 的入口： + +| 模块 | 文件/目录 | 关键文件 | 职责 | +|------|----------|----------|------| +| CLI 入口 | `src/main.rs` | `main.rs` | 命令解析与分发，硬限界 ≤ 1000 行 | +| 模块导出 | `src/lib.rs` | `lib.rs` | 导出 30+ 模块 | +| 子命令 | `src/commands/` | `repo.rs` / `skill.rs` / `workflow.rs` / `knowledge.rs` / `analysis.rs` / `ontology.rs` / `limit.rs` / `system.rs` / `simple.rs` | 9 类 CLI 子命令实现 | +| TUI 仪表盘 | `src/tui/` | `mod.rs` / `event.rs` / `layout.rs` / `theme.rs` / `render/` / `state/` | ratatui 终端界面：事件、布局、主题、渲染、状态 | +| MCP Server | `src/mcp/` | `mod.rs` / `tools/mod.rs` / `tests.rs` / `tools/*.rs` | stdio 通信，`McpTool` trait，71 个工具实现 | + +### 编译层（Semantic / Knowledge） +把原始输入编译为可推理知识： + +| 模块 | 文件/目录 | 关键文件 | 职责 | +|------|----------|----------|------| +| Registry | `src/registry/` | `migrate.rs` / `test_helpers.rs` / `entity.rs` / `knowledge.rs` / `knowledge_meta.rs` / `call_graph.rs` / `dead_code.rs` / `health.rs` / `import_ontology.rs` / `agent_context.rs` | SQLite schema、迁移、实体、关系、调用图、死代码检测 | +| 搜索 | `src/search/` | `hybrid.rs` / `symbol_index.rs` | Tantivy BM25 + 向量混合检索 | +| Vault / PARA 笔记 | `src/vault/` | `mod.rs` / `scanner.rs` / `indexer.rs` / `frontmatter.rs` / `wikilink.rs` / `backlinks.rs` / `fs_io.rs` / `history.rs` / `export.rs` | Markdown + YAML frontmatter、wikilink、backlinks、BFS 图遍历 | +| Skill 运行时 | `src/skill_runtime/` | `mod.rs` / `discover.rs` / `executor.rs` / `parser.rs` / `scoring.rs` / `publish.rs` / `registry.rs` / `sources.rs` / `dependency.rs` / `clarity_sync.rs` | 发现 → 安装 → 执行 → 评分 → 发布 | +| 工作流引擎 | `src/workflow/` | `mod.rs` / `model.rs` / `parser.rs` / `validator.rs` / `scheduler.rs` / `executor.rs` / `interpolate.rs` / `state.rs` | YAML DAG 编排：5 种 step 类型 + 插值 + 调度 + 验证 | +| 知识引擎 | `src/knowledge_engine/` | 各提取器模块 | 代码符号提取、README 摘要与关键词生成 | +| 同步 | `src/sync/` | `orchestrator.rs` / `policy.rs` / `tasks.rs` / `tests.rs` | 仓库同步编排、策略与任务 | + +### 可靠层（Physical / Storage） +本地优先的数据与索引底座： + +| 组件 | 技术/位置 | 说明 | +|------|----------|------| +| 关系存储 | SQLite WAL (`registry.db`) | `PRAGMA user_version` 驱动迁移 | +| 全文索引 | Tantivy | 代码符号与 Vault 笔记的 BM25 | +| 语义向量 | SQLite BLOB + `cosine_similarity` UDF | 零 ML 运行时依赖 | +| 代码解析 | tree-sitter | Rust / Python / TypeScript / Go | +| 版本控制 | git2 | Git 仓库状态与操作 | + +### 独立 Workspace Crates + +`crates/` 目录包含 12 个零内部耦合的子 crate： -- `tui`：终端仪表盘。 -- `mcp`：MCP Server。 -- `lang-*`：tree-sitter 语言支持。 -- `embedding`：启用 `devbase-embedding` crate（Candle/Ollama），**不在 default**，需显式 `--features embedding`。 -- `greptimedb`：可选 GreptimeDB 写入。 -- `watch`：目录监控（由 `tui` 间接启用）。 +``` +devbase-core-types # 最底层：Node / Edge / NodeType 等核心类型 +devbase-registry # Registry 核心逻辑 +devbase-embedding # 本地文本嵌入：Candle + Ollama 后端 +devbase-vault-wikilink # WikiLink 解析器 +devbase-vault-frontmatter # Vault Frontmatter 解析 +devbase-skill-runtime-parser# Skill 运行时解析器 +devbase-skill-runtime-types # Skill 运行时类型 +devbase-symbol-links # 符号链接 +devbase-sync-protocol # 同步协议 +devbase-syncthing-client # Syncthing 集成客户端 +... # 其余未在此穷举 +``` -## 3. 仓库布局 +## Crate 依赖方向 ``` -devbase/ -├── Cargo.toml # 主包 + workspace 定义（members = ["crates/*"]） -├── rustfmt.toml # 格式化配置 -├── mcp.json # MCP 客户端配置示例 -├── .github/workflows/ # CI（check/test/fmt/clippy/audit/invariant）+ Release -├── .githooks/pre-commit # 提交前 fmt + clippy -├── .cargo/config.toml # RUST_TEST_THREADS=1 -├── src/ -│ ├── main.rs # CLI 入口，仅做命令分发（833 行） -│ ├── lib.rs # 导出 30+ 模块，条件编译 mcp/tui/watch -│ ├── commands/ # CLI 子命令实现 -│ ├── core/ # 原子类型：Node / Edge / NodeType -│ ├── registry/ # SQLite Registry：schema、迁移、实体、关系、健康 -│ ├── repository/ # Git 仓库实体抽象 -│ ├── search/ # Tantivy 索引、混合检索（BM25 + 向量） -│ ├── semantic_index/ # 语义索引持久化 -│ ├── skill_runtime/ # Skill 发现、安装、执行、评分、发布 -│ ├── workflow/ # YAML 工作流：解析、校验、调度、执行 -│ ├── vault/ # PARA 笔记系统、双向链接、BFS 图、历史 -│ ├── mcp/ # MCP Server + 71 个 tools -│ ├── tui/ # ratatui 仪表盘（render/ + state/） -│ ├── sync/ # 仓库同步编排与策略 -│ ├── storage.rs # StorageBackend trait + AppContext（依赖注入容器） -│ ├── config.rs # 配置与凭证模板 -│ ├── i18n/ # 国际化（zh_cn / en） -│ └── ... -├── crates/ # 12 个独立 workspace crate -│ ├── devbase-core-types -│ ├── devbase-registry -│ ├── devbase-embedding -│ ├── devbase-skill-runtime-types -│ ├── devbase-skill-runtime-parser -│ ├── devbase-symbol-links -│ ├── devbase-sync-protocol -│ ├── devbase-syncthing-client -│ ├── devbase-vault-frontmatter -│ ├── devbase-vault-wikilink -│ ├── devbase-workflow-interpolate -│ └── devbase-workflow-model -├── tests/ -│ └── cli.rs # 11 个集成测试 -├── benches/ -│ ├── registry_bench.rs -│ ├── semantic_index.rs -│ └── vault_bench.rs -├── skills/ # 示例 Skill（embed-repo / knowledge-report / search-workspace） -├── scripts/ -│ ├── install.ps1 / install.sh -│ ├── devbase-claude.ps1 -│ └── invariant-checks/run-checks.ps1 -└── docs/ # 架构文档、ADR、RFC、指南 +devbase-core-types （零内部耦合） + ↓ +{ devbase-registry, devbase-embedding, devbase-vault-*, devbase-skill-runtime-* } + ↓ +src/ 各模块（commands, tui, mcp, registry, search, vault, skill_runtime, workflow, ...） ``` -### Workspace Crates 职责 +- `devbase-core-types` 为最底层基础 crate，禁止依赖任何 devbase 内部 crate。 +- `crates/` 内各 crate 禁止直接调用主 crate (`src/`) 的 `crate::` 路径。 +- `src/` 各模块可聚合所有 crate 与内部模块能力，`main.rs` 为唯一二进制入口。 -| Crate | 说明 | -|-------|------| -| `devbase-core-types` | 统一实体模型 `Node`/`Edge`/`NodeType`，零内部耦合 | -| `devbase-registry` | SQLite Registry 操作；内部子模块：entity/health/metrics/call_graph/code_symbols/dead_code/relation/workspace | -| `devbase-embedding` | Embedding 生成协议；Candle/Ollama backend、`cosine_similarity` | -| `devbase-skill-runtime-types` | Skill Runtime 类型与枚举 | -| `devbase-skill-runtime-parser` | `SKILL.md` frontmatter 解析 | -| `devbase-symbol-links` | 代码符号链接生成（相似签名、共位关系） | -| `devbase-sync-protocol` | 目录同步协议与版本向量 | -| `devbase-syncthing-client` | Syncthing REST API 客户端 | -| `devbase-vault-frontmatter` | Vault 笔记 frontmatter 解析 | -| `devbase-vault-wikilink` | `[[wiki-link]]` / `[[note#anchor]]` 解析与解析 | -| `devbase-workflow-interpolate` | 工作流变量插值 | -| `devbase-workflow-model` | YAML Workflow 定义类型 | +## 核心红线（违反任意一条 → HALT） -## 4. 构建、运行与测试 +红线 `G1–G7` 与 `CLAUDE.md` 中的 `RF-1–RF-7` 一一对应： -### 环境要求 +1. **G1 依赖注入**（RF-1）：禁止新增 `dirs::data_local_dir()` / `std::env::var_os` 硬编码路径，所有 IO 边界通过 `StorageBackend` / `AppContext` 注入。 +2. **G2 测试密封性**（RF-2）：测试禁止修改全局进程状态，文件系统测试用 `tempfile` + `StorageBackend`。 +3. **G3 Schema 单一事实来源**（RF-3）：`SCHEMA_DDL` 与 `migrate.rs` 必须原子同步。 +4. **G4 二进制入口限界**（RF-4）：`main.rs` 不得超过 1000 行。 +5. **G5 生产代码无 panic**（RF-6）：禁止 `unwrap()` / `expect()` / `panic!()`。 +6. **G6 无循环依赖**（RF-5）：禁止模块间双向 `use crate::` 引用。 +7. **G7 Workspace 拆分约束**（RF-7）：新增模块若对 devbase 内部 `crate::` 引用超过 5 个，禁止提取为 workspace crate。 -- **Rust 1.95.0+** -- 主要开发/CI 平台：**Windows**（Linux/macOS 社区支持） -- 可选：`sccache` 可显著加速 tree-sitter grammar 的 C 编译（见 `CONTRIBUTING.md`） - -### 常用命令 +## 常用命令 ```powershell # 构建 cargo build --release -# 本地快速体验 +# 本地体验 cargo run -- scan . --register cargo run -- tui cargo run -- mcp -# 测试（与 CI 一致） +# 测试与检查（提交前必须） cargo test --all-targets -cargo test --workspace -- --test-threads=4 - -# 静态检查 cargo clippy --all-targets -D warnings cargo fmt --check -# 审计 -cargo audit - -# 架构不变量检查（CI 的 invariant job） +# 架构不变量检查 scripts/invariant-checks/run-checks.ps1 ``` -### 测试策略 - -- **单元测试**：分布在 `src/**/tests.rs` 与 `#[cfg(test)]` 块中。 -- **集成测试**：`tests/cli.rs`，使用 `assert_cmd` + `tempfile`，通过 `DEVBASE_DATA_DIR` 隔离数据目录。 -- **Crate 测试**：每个 `crates/*/src/*.rs` 自带测试。 -- **Bench**：`criterion` 驱动的 `benches/registry_bench.rs`、`benches/semantic_index.rs`、`benches/vault_bench.rs`。 -- **测试隔离**： - - 所有 IO 测试使用 `TempDir` 与 `StorageBackend` 注入，禁止直接写 `%LOCALAPPDATA%`。 - - `.cargo/config.toml` 默认 `RUST_TEST_THREADS=1`；CI 使用 `--test-threads=4`。 - - `git2` 测试必须显式 `Signature::now("Test", "test@example.com")` 与 `repo.set_head("refs/heads/main")`。 -- **网络相关测试**：`crates/devbase-embedding` 中 Candle 测试会下载模型，离线环境会失败；CI/在线环境需保证网络可达。 - -### 提交前必须通过 - -```powershell -cargo test --all-targets -cargo clippy --all-targets -D warnings -cargo fmt --check -``` - -仓库已配置 `.githooks/pre-commit` 执行 `cargo fmt --check` 与 `cargo clippy --all-targets -- -D warnings`。 - -## 5. 代码风格与约定 - -### 格式化 - -`rustfmt.toml`： - -```toml -edition = "2024" -max_width = 100 -chain_width = 80 -fn_call_width = 80 -struct_lit_width = 30 -array_width = 80 -reorder_imports = true -``` - -### 提交规范（Conventional Commits） - -``` -feat: 新功能 -fix: Bug 修复 -docs: 文档更新 -refactor: 重构（无行为变更） -test: 测试相关 -chore: 构建/工具链 -perf: 性能优化 -``` - -示例： - -``` -feat(mcp): add devkit_skill_validate tool -``` - -### 源文件头 - -新增源文件应在顶部包含 SPDX 许可证头（项目主许可证为 AGPL-3.0-or-later）： - -```rust -// SPDX-License-Identifier: AGPL-3.0-or-later -// Copyright (c) 2026 juice094 -``` - -> 注意：仓库内部分历史文件仍使用 `MIT` SPDX 头，新文件统一使用 AGPL。 - -### 工具使用约定 - -- **读文件**：优先使用 `Read` 工具；不要直接用 `cat`/`head`。 -- **搜索**：优先使用 `Grep`/`Glob`；不要直接用 shell `grep`/`find`。 -- **小修改**：使用 `Edit`（按原文件内容精确替换）。 -- **整文件/新建**：使用 `Write`。 -- **多文件操作/构建/测试**：使用 `Bash`。 - -### 添加 MCP Tool 的标准路径 - -1. 在 `src/mcp/tools/` 新建模块。 -2. 实现 `McpTool` trait（`name()`、`schema()`、`invoke()`，可选 `invoke_stream()`）。 -3. 在 `src/mcp/tools/mod.rs` 注册并 `pub use`。 -4. 在 `src/mcp/mod.rs` 的 `McpToolEnum` / 路由中加入该工具。 -5. 在 `src/mcp/tests.rs` 添加单元测试。 -6. 更新 `README.md` Tool 矩阵与 `AGENTS.md` 工具计数。 +## 给 Agent 的默认指令 -**核心原则**：所有状态变更操作必须幂等（`ON CONFLICT ... DO UPDATE`）。 +1. **修改前先读知识包**：复杂任务先浏览 [`.knowledge/architecture/dependency-topology.md`](./.knowledge/architecture/dependency-topology.md) 定位模块层级。 +2. **改 Schema 先读迁移策略**：任何 `registry.db` 表结构变更遵循 [`.knowledge/registry/migration-policy.md`](./.knowledge/registry/migration-policy.md)。 +3. **添加 MCP Tool 走标准路径**：见 [`.knowledge/mcp/tool-adding-guide.md`](./.knowledge/mcp/tool-adding-guide.md)。 +4. **优先使用项目内工具**：读文件用 `Read`，搜索用 `Grep`/`Glob`，小修改用 `Edit`，新建/整文件用 `Write`，构建测试用 `Bash`。 +5. **不要修改 `.gitignore` 覆盖范围之外的敏感文件**：禁止在源码/注释/测试数据中硬编码真实 token、api_key 或密码。 +6. **保持门面文件一致**：若修改了 MCP 工具数、Schema 版本、测试数、红线规则，同步更新 `README.md`、`AGENTS.md`、`CLAUDE.md`、`.knowledge/index.md` 与 `.knowledge/architecture/project-worktree.md` 中的对应数字。 -## 6. 数据存储、Schema 与迁移 - -### 存储位置 +--- -默认使用用户本地数据目录（可通过 `DEVBASE_DATA_DIR` 覆盖）： +## 完整项目结构参考 -``` -%LOCALAPPDATA%/devbase/ # Windows -~/.local/share/devbase/ # Linux -~/Library/Application Support/devbase/ # macOS -``` +> 本节按实际文件系统整理，便于新 Agent 快速建立全局认知。OKF 归档版本见 [`.knowledge/architecture/project-worktree.md`](./.knowledge/architecture/project-worktree.md)。 -目录内容： +### 顶层布局 -``` +```text devbase/ -├── registry.db # SQLite Registry（WAL 模式） -├── registry.db-wal -├── search_index/ # Tantivy 全文索引 -├── symbol_index/ # Tantivy 代码符号索引 -├── backups/ # 自动备份 -└── workspace/ - ├── vault/ # PARA 笔记（00-Inbox, 01-Projects, ...） - └── assets/ # 二进制资源 +├── .cargo/ # 本地 Cargo 配置 +├── .github/ # CI / Release workflows +├── .knowledge/ # OKF Knowledge Bundle +├── benches/ # Criterion 基准测试 +├── crates/ # 12 个独立 workspace crate +├── docs/ # 人类可读文档导航 +├── examples/ # 可运行示例 +├── scripts/ # 安装脚本与 CI 辅助 +├── skills/ # 示例 Skill +├── src/ # 主应用程序（30+ 模块） +├── tests/ # 集成测试 +├── AGENTS.md # Agent 入口指引 +├── CLAUDE.md # Claude Code 专用指引 +├── Cargo.toml # Workspace 配置 +└── README.md # 项目首页 ``` -### Schema 单一事实来源 - -- `src/registry/migrate.rs`：当前 Schema DDL + 迁移逻辑。 -- `src/registry/migrations/v*.rs`：v01 到 v36 的增量迁移脚本。 -- `src/registry/test_helpers.rs`：`SCHEMA_DDL` 必须与 `migrate.rs` 保持原子同步。 -- `CURRENT_SCHEMA_VERSION = 36`。 - -### Schema 迁移规范 - -1. 在 `migrate.rs` 新增版本判断块，使用 `ALTER TABLE ... ADD COLUMN`（SQLite 限制）。 -2. 升级前必须调用 `backup::auto_backup_before_migration()` 生成 `backup-YYYYMMDD-HHMMSS.db`。 -3. 同步更新 `test_helpers.rs` 的 `SCHEMA_DDL`。 -4. 更新 `AGENTS.md` 的 Schema 版本号与 `CURRENT_SCHEMA_VERSION`。 - -**禁止**：直接修改现有表的列定义；不得在无迁移逻辑的情况下修改 registry schema。 - -## 7. 架构红线（Architecture Guardrails） - -违反任意一条 = **HALT**，转交人类裁决或回滚。完整清单与检测脚本见 `docs/architecture/invariants.md`。 - -### RF-1：依赖注入优于全局状态 - -- 禁止新增 `dirs::data_local_dir()` / `std::env::var_os` 硬编码路径。 -- 所有 IO 边界路径通过参数、构造函数或 `StorageBackend` trait 注入。 -- 例外（Grandfathered）：`backup_dir`、`db_path`、`index_path` 在重构前不得新增第 4 处。 - -Fitness function： - -```bash -grep -rn "dirs::data_local_dir\|std::env::var_os\|std::env::var(\"LOCALAPPDATA\"" src/ \ - | grep -v "backup.rs\|migrate.rs\|search.rs" -# 预期输出：空 +### `src/` 主应用程序 + +#### 交互层 + +```text +src/ +├── main.rs # CLI 入口（RF-4 ≤ 1000 行） +├── lib.rs # 导出 30+ 模块 +├── commands/ # 9 类 CLI 子命令 +│ ├── mod.rs / repo.rs / skill.rs / workflow.rs / knowledge.rs +│ ├── analysis.rs / ontology.rs / limit.rs / system.rs / simple.rs +├── tui/ # ratatui 终端仪表盘 +│ ├── mod.rs / event.rs / layout.rs / theme.rs +│ ├── render/ # 渲染组件 +│ └── state/ # 状态机 +└── mcp/ # MCP Server（stdio，71 个工具） + ├── mod.rs # McpTool trait、路由 + ├── clients.rs / tests.rs + └── tools/ # 71 个工具实现 ``` -### RF-2：测试密封性（Hermetic Testing） - -- 测试禁止修改全局进程状态（`std::env::set_var`、`static mut`、全局文件系统句柄）。 -- 文件系统测试使用 `tempfile` + `StorageBackend` 注入。 -- Tantivy / SQLite 文件系统测试必须串行化。 -- R2.1 禁止 `DEVBASE_DATA_DIR` 全局注入；R2.2 Windows 路径双端 `dunce::canonicalize`；R2.3 `git2` 测试显式身份与分支。 - -Fitness function： - -```bash -cargo test --test-threads=16 +#### 编译层 + +```text +src/ +├── registry/ # SQLite Registry：schema、迁移、实体、关系 +│ ├── migrate.rs / test_helpers.rs +│ ├── entity.rs / relation.rs / repo.rs / workspace.rs +│ ├── knowledge.rs / knowledge_meta.rs / vault.rs +│ ├── code_symbols.rs / call_graph.rs / dead_code.rs / links.rs +│ ├── metrics.rs / known_limits.rs / import_ontology.rs +│ ├── agent_context.rs / health.rs / tests.rs +├── repository/ # 仓库业务抽象 +│ ├── mod.rs / repo.rs / workspace.rs / dependency.rs +│ ├── health.rs / knowledge.rs / search.rs / symbol.rs +├── search/ # Tantivy BM25 + 向量混合检索 +│ ├── mod.rs / hybrid.rs / symbol_index.rs +├── semantic_index/ # tree-sitter 代码符号提取 +│ ├── mod.rs / symbol.rs / call_graph.rs / git_diff.rs / persist.rs +├── vault/ # PARA 笔记系统 +│ ├── mod.rs / scanner.rs / indexer.rs +│ ├── frontmatter.rs / wikilink.rs / backlinks.rs +│ ├── fs_io.rs / history.rs / export.rs +├── skill_runtime/ # Skill 生命周期 +│ ├── mod.rs / parser.rs / registry.rs / discover.rs +│ ├── dependency.rs / executor.rs / scoring.rs / publish.rs +│ ├── sources.rs / clarity_sync.rs / sync_adapter.rs +├── skill_sync.rs # Vault → Skill 桥接 +├── workflow/ # YAML 工作流引擎 +│ ├── mod.rs / model.rs / parser.rs / validator.rs +│ ├── scheduler.rs / executor.rs / interpolate.rs / state.rs +├── knowledge_engine/ # README 摘要、关键词、模块探测 +│ ├── mod.rs / readme.rs / module.rs / index.rs +│ ├── index_state.rs / llm.rs / fallback.rs +└── sync/ # 仓库同步编排 + ├── mod.rs / orchestrator.rs / policy.rs / tasks.rs / tests.rs ``` -### RF-3：Schema 单一事实来源 - -- `SCHEMA_DDL` 与 `migrate.rs` 必须原子同步。 -- CI 运行 `test_in_memory_schema_version` + schema 结构比对。 - -### RF-4：二进制入口限界 - -- `main.rs` 不得超过 1000 行；当前 833 行。 -- 新增 CLI 命令必须拆分到 `src/commands/` 子模块。 - -### RF-5：无循环依赖 - -- 禁止模块间双向 `use crate::` 引用。 - -### RF-6：生产代码无 panic - -- 生产代码禁止 `unwrap()` / `expect()` / `panic!()`（测试代码除外）。 -- 状态：当前生产代码 unwrap 计数为 0。 - -Fitness function： - -```bash -for f in $(find src -name "*.rs"); do - test_line=$(grep -n "#\[cfg(test)\]" "$f" | head -1 | cut -d: -f1) - if echo "$f" | grep -qE "tests?\.rs$|_test\.rs$|/tests/"; then continue; fi - if [ -n "$test_line" ]; then - head -n "$((test_line - 1))" "$f" | grep -n "\.unwrap()" - else - grep -n "\.unwrap()" "$f" - fi -done -# 预期输出：空 +#### 可靠层与基础能力 + +```text +src/ +├── storage.rs # StorageBackend + AppContext（依赖注入容器） +├── config.rs # 配置结构体 +├── i18n/ # 国际化（en / zh_cn） +├── core/ # 原子类型（Node / Edge / NodeType） +├── asyncgit.rs # 异步 Git 通知通道 +├── scan.rs # 仓库扫描入口 +├── query.rs # 结构化查询表达式 +├── health.rs / health/env_cache.rs +├── oplog_analytics.rs # 操作日志与覆盖率分析 +├── backup.rs # Schema 迁移前自动快照 +├── watch.rs # 目录监控 +├── dependency_graph.rs # 跨仓库依赖图 +├── symbol_links.rs # 符号链接（RE-EXPORT ONLY） +├── discovery_engine.rs # 跨仓库发现 +├── embedding.rs # 向量嵌入封装 +├── digest.rs # 摘要/哈希工具 +├── arxiv.rs # arXiv 元数据抓取 +├── greptime.rs # GreptimeDB 可选集成 +├── syncthing_client.rs # Syncthing 客户端 +├── sync_protocol.rs # 同步协议基础类型 +├── clients.rs # 通用客户端 +├── daemon.rs # 守护进程入口 +└── test_utils.rs # 测试辅助 ``` -### RF-7：Workspace 拆分约束 - -- 新增模块若对 devbase 内部其他模块的 `crate::` 引用超过 5 个，禁止提取为 workspace crate。 -- 已提取 crate 的重新导出文件（如 `src/symbol_links.rs`）顶部标有 `RE-EXPORT ONLY`，禁止添加新代码。 -- 子 crate 依赖版本必须与 workspace 统一。 - -### 关键分层不变量（G/T） - -| 编号 | 规则 | -|------|------| -| G1 | `registry::WorkspaceRegistry` 不得依赖 Tier 4+ 模块 | -| G3 | 所有状态变更 MCP tool 必须幂等 | -| G4 | Breaking change 只能通过新增 tool 实现，不修改现有 schema | -| G5 | 生产代码不得新增 `unwrap`/`expect`（RF-6） | -| T11 | `mcp/tools/*` 不得直接调用 `rusqlite::Connection`，必须通过 registry 封装（已知例外：`repo.rs`、`repo/nl_query.rs`、`brief.rs`、`impact.rs`） | -| T12 | `tui/render/*` 是纯消费者层，禁止写入 registry | - -CI 通过 `scripts/invariant-checks/run-checks.ps1` 检测 G5 / T11 / T12 / README+Cargo.toml 完整性。 - -## 8. 安全与隐私原则 - -### 本地优先（Local-First） - -- Registry DB 只存在用户本地配置目录，**不向远程传输**。 -- 代码内容默认不上云（除非用户显式配置 GitHub token 用于 stars 查询）。 -- MCP Server 仅通过 **stdio** 本地进程通信，不暴露网络端口。 - -### 客户端无关（Client-Agnostic） - -- 允许：向通用目录输出数据；实现标准协议（MCP）。 -- 禁止：核心能力硬编码特定客户端路径/API/配置；核心能力可用性依赖某个客户端是否安装。 -- `scripts/claude/`、`docs/clients/` 属于适配示例，不归入核心版本控制。 - -### 凭证管理 - -- GitHub token、LLM API key 存储在本地 `config.toml`（用户配置目录，**不在项目工作目录**）。 -- 模板使用占位符 ``，禁止在源码/注释/测试数据中硬编码真实凭证。 -- `.gitignore` 已覆盖 `*.db`、`.devbase/`、`.env*`、`*.local.toml`。 - -### 审计与备份 - -- 所有 `scan`/`sync`/`health` 操作自动写入 OpLog（SQLite `oplog` 表）。 -- Schema 迁移前自动生成 `backup-YYYYMMDD-HHMMSS.db` 快照。 -- Registry 支持 `export`/`import` 用于用户自主备份。 - -## 9. CLI / MCP / TUI 能力速览 - -### 顶层 CLI 命令 - -| 分组 | 命令 | -|------|------| -| 仓库管理 | `scan`、`health`、`status`、`sync`、`query`、`index`、`tag`、`meta`、`repo` | -| 代码分析 | `metrics`、`module-graph`、`call-graph`、`dependency-graph`、`code-symbols`、`dead-code`、`github-info` | -| 知识/Vault | `digest`、`knowledge-report`、`oplog`、`vault`、`ontology` | -| Skill / Workflow | `skill`、`workflow` | -| 系统 | `tui`（feature `tui`）、`mcp`（feature `mcp`）、`daemon`、`watch`（feature `watch`）、`syncthing-push`、`skill-sync`、`limit`、`registry`、`clean`、`version` | - -### MCP Server - -- 启动：`devbase mcp` -- 传输：**stdio only** -- 工具示例：`devkit_scan`、`devkit_health`、`devkit_sync`、`devkit_query`、`devkit_index`、`devkit_vault_search`、`devkit_skill_run`、`devkit_workflow_run`、`devkit_session_recall`、`devkit_project_brief` 等共 71 个。 -- 客户端配置示例见 `mcp.json`： - -```json -{ - "mcpServers": { - "devbase": { "command": "devbase", "args": ["mcp"] } - } -} +### `crates/` — 12 个 Workspace Crate + +```text +crates/ +├── devbase-core-types # Node / Edge / NodeType 核心类型 +├── devbase-registry # Registry 核心逻辑 +├── devbase-embedding # 本地文本嵌入（Candle + Ollama） +├── devbase-vault-wikilink # WikiLink 解析器 +├── devbase-vault-frontmatter # Vault Frontmatter 解析 +├── devbase-skill-runtime-parser # Skill 运行时解析器 +├── devbase-skill-runtime-types # Skill 运行时类型 +├── devbase-symbol-links # 符号链接 +├── devbase-sync-protocol # 同步协议 +├── devbase-syncthing-client # Syncthing 客户端 +├── devbase-workflow-model # Workflow 数据模型 +└── devbase-workflow-interpolate # Workflow 变量插值 ``` -### TUI - -- 启动：`devbase tui` -- 基于 `ratatui` 的异步事件循环，支持跨仓库导航、安全同步预览、标签聚类、搜索。 - -## 10. CI/CD 与发布 - -### CI（`.github/workflows/ci.yml`） - -在 Windows runner 上执行： - -1. `cargo check --all-targets` -2. `cargo test --lib --tests --bins --examples -- --test-threads=4 --nocapture` -3. `cargo fmt --check` -4. `cargo clippy --all-targets --verbose -- -W warnings` -5. `cargo audit` -6. `scripts/invariant-checks/run-checks.ps1` - -### Release（`.github/workflows/release.yml`） - -- 触发：推送 `v*` tag。 -- 构建 Windows x64 zip 与 Linux x64 tar.gz，附带 `README.md`、`LICENSE`、`CHANGELOG.md`。 -- 上传至 GitHub Release。 - -### 安装脚本 - -- Windows：`scripts/install.ps1` -- Linux/macOS：`scripts/install.sh` -- Claude Code 启动器：`scripts/devbase-claude.ps1` +### Crate 依赖方向 -## 11. Skill 与工作流 - -### Skill - -- 元数据：目录下的 `SKILL.md`，frontmatter 必须包含 `id`、`name`、`version`、`description`，可选 `dependencies`。 -- 入口脚本支持 `py`、`sh`、`ps1`、`js` 或二进制。 -- 命令：`skill discover`、`skill run`、`skill install`、`skill publish`、`skill sync`。 -- 评分：`success_rate`、`usage_count`、`rating`（0-5）。 -- 跨客户端 sync：`skill sync --target ...`，支持 `all` / `clarity` / `kimicli` / `claude-code` / `codex` / `claw`。详见 `vault/99-Meta/skillopt-devbase-integration.md`。 - -### Workflow - -- YAML 定义，5 种 step 类型：`skill`、`subworkflow`、`parallel`、`condition`、`loop`。 -- 拓扑调度 + batch 并行执行。 -- 规范见 `docs/architecture/workflow-dsl.md`。 - -## 12. 禁止事项 - -- 不得修改 `dev/third_party/*` 外部仓库。 -- 不得在没有迁移逻辑的情况下修改 registry schema。 -- 不得引入已 deprecated 的协议。 -- **不得在主仓库引入 Spark/Flink 依赖**（研究性质代码必须置于独立仓库）。 -- **不得在任何源码文件中硬编码真实 token、api_key 或密码**（包括注释和测试数据）。 - -## 13. 参考文档 - -| 文档 | 内容 | -|------|------| -| `README.md` | 项目简介、快速开始、技术栈 | -| `CONTRIBUTING.md` | 贡献指南、构建加速、代码规范、Skill/MCP 添加路径 | -| `docs/architecture/overview.md` | 三层架构、技术决策记录 | -| `docs/architecture/invariants.md` | 完整不变量清单（G/T） | -| `docs/architecture/workflow-dsl.md` | Workflow DSL 规范 | -| `docs/architecture/workspace-as-schema.md` | 统一实体模型 | -| `docs/guides/mcp-integration-guide.md` | MCP 集成指南 | -| `docs/README.md` | 完整文档导航 | -| `docs/ROADMAP.md` | 历史 Waves、功能路线图与讨论 | -| `CHANGELOG.md` | 版本变更日志 | - ---- - -*本文件应随项目结构、Schema 版本、工具数量、测试数量等变更同步更新。* +```text +devbase-core-types （零内部耦合） + ↓ +{ devbase-registry, devbase-embedding, devbase-vault-*, devbase-skill-runtime-*, + devbase-symbol-links, devbase-sync-protocol, devbase-syncthing-client, + devbase-workflow-* } + ↓ +src/ 各模块（commands, tui, mcp, registry, search, vault, skill_runtime, workflow, ...） +``` diff --git a/CLAUDE.md b/CLAUDE.md index f6d5851..42f0f29 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -10,6 +10,8 @@ devbase is a Rust workspace (edition 2024, Rust 1.95+) that compiles a developer **License**: AGPL-3.0-or-later / dual-licensed commercial. New source files must include the SPDX header. +**Project knowledge bundle**: The canonical AI-agent documentation lives in `.knowledge/` as an Open Knowledge Format (OKF) bundle. Start with [`.knowledge/index.md`](./.knowledge/index.md) for the full architecture map, registry migration policy, MCP tool-adding guide, and development conventions. + --- ## Build, Test, and Lint @@ -63,6 +65,28 @@ scripts/ci-local.sh # Linux/macOS - **`src/main.rs`** — CLI only; delegates to `commands/` submodules. Hard ceiling: <1000 lines (RF-4). - **`src/lib.rs`** — Exports all 30+ modules; the binary is a thin wrapper. +### Project map by layer + +| Layer | Modules | Responsibility | +|-------|---------|----------------| +| **Interaction** | `commands/`, `tui/`, `mcp/` | Human CLI, ratatui dashboard, 71 MCP tools over stdio | +| **Compilation** | `registry/`, `search/`, `vault/`, `skill_runtime/`, `workflow/`, `knowledge_engine/`, `sync/` | Compile repos/notes/skills/workflows into queryable knowledge | +| **Reliability** | SQLite WAL, Tantivy, git2, `storage.rs` | Local-first durable storage, indexing, and audit trail | + +### Crate dependency direction + +``` +devbase-core-types (zero internal coupling) + ↓ +{ devbase-registry, devbase-embedding, devbase-vault-*, devbase-skill-runtime-*, ... } + ↓ +src/ modules (commands, tui, mcp, registry, search, vault, ...) +``` + +- `devbase-core-types` is the bottom-most crate; it must not depend on any other devbase crate. +- Workspace crates in `crates/` must not import from the main `src/` binary/library via `crate::`. +- `src/` modules aggregate all workspace crates and internal modules; `main.rs` is the only binary entry point. + ### Key architectural patterns #### MCP Tool trait @@ -110,17 +134,17 @@ Discovery (`skill_runtime/discover.rs`) → Install → Execute (`executor.rs`) ## Architecture Guardrails (RF Rules) -These are enforced in CI via `scripts/invariant-checks/run-checks.ps1`. A violation is a blocking failure. +These are enforced in CI via `scripts/invariant-checks/run-checks.ps1`. A violation is a blocking failure. `RF-*` map to `AGENTS.md` red-lines `G1–G7`. -| Rule | Summary | -|------|---------| -| **RF-1** | Dependency injection over global state. No new `dirs::data_local_dir()` / `std::env::var_os` hard-coding. | -| **RF-2** | Hermetic testing. No `std::env::set_var` in tests. Use `tempfile` + injected `StorageBackend`. Tantivy/SQLite FS tests must be serialized. | -| **RF-3** | `SCHEMA_DDL` and `migrate.rs` must stay atomically in sync. | -| **RF-4** | `main.rs` ≤ 1000 lines; CLI commands live in `commands/`. | -| **RF-5** | No cyclic `crate::` dependencies between modules. | -| **RF-6** | **Zero** `unwrap()` / `expect()` / `panic!()` in production code (outside `#[cfg(test)]`). | -| **RF-7** | New modules with >5 internal `crate::` refs cannot be extracted to workspace crates. Re-export files (`src/symbol_links.rs`, etc.) are `RE-EXPORT ONLY`. | +| Rule | Maps | Summary | +|------|------|---------| +| **RF-1** | G1 | Dependency injection over global state. No new `dirs::data_local_dir()` / `std::env::var_os` hard-coding. | +| **RF-2** | G2 | Hermetic testing. No `std::env::set_var` in tests. Use `tempfile` + injected `StorageBackend`. Tantivy/SQLite FS tests must be serialized. | +| **RF-3** | G3 | `SCHEMA_DDL` and `migrate.rs` must stay atomically in sync. | +| **RF-4** | G4 | `main.rs` ≤ 1000 lines; CLI commands live in `commands/`. | +| **RF-5** | G6 | No cyclic `crate::` dependencies between modules. | +| **RF-6** | G5 | **Zero** `unwrap()` / `expect()` / `panic!()` in production code (outside `#[cfg(test)]`). | +| **RF-7** | G7 | New modules with >5 internal `crate::` refs cannot be extracted to workspace crates. Re-export files (`src/symbol_links.rs`, etc.) are `RE-EXPORT ONLY`. | **Additional tiered checks** (from `run-checks.ps1`): - **T11**: `mcp/tools/*.rs` must not use `rusqlite::Connection` directly. Known exceptions: `repo.rs`, `brief.rs`, `impact.rs`. @@ -143,7 +167,7 @@ These are enforced in CI via `scripts/invariant-checks/run-checks.ps1`. A violat `TempDir` may return short filenames (`TEMP~1`) while `dunce::canonicalize` returns long filenames. Normalize **both** sides before comparing paths in tests. ### Running tests -Current test count: **605** passed / 7 ignored (from `cargo test --workspace -- --list`). +Current test count: **616+** passed (a small subset ignored) from `cargo test --workspace -- --list`. Local `.cargo/config.toml` sets `RUST_TEST_THREADS = "1"`. CI uses `--test-threads=4`. If you encounter flaky SQLite/Tantivy tests locally, reduce threads: ```bash @@ -160,7 +184,7 @@ cargo test -- --test-threads=1 4. Add variant to `McpToolEnum` in `src/mcp/mod.rs` 5. Add routing arm in `src/mcp/mod.rs` `handle_request` 6. Add unit tests in `src/mcp/tests.rs` -7. Update README Tool matrix and `AGENTS.md` tool count +7. Update README Tool matrix, `AGENTS.md`, and `CLAUDE.md` tool counts **All state-changing tools must be idempotent** — use `ON CONFLICT ... DO UPDATE` or equivalent upsert logic. @@ -173,7 +197,7 @@ cargo test -- --test-threads=1 3. Call `backup::auto_backup_before_migration()` at the start 4. Update `CURRENT_SCHEMA_VERSION` 5. Mirror changes into `src/registry/test_helpers.rs` `SCHEMA_DDL` -6. Update `AGENTS.md` schema version number +6. Update `AGENTS.md`, `CLAUDE.md`, and `.knowledge/index.md` schema version numbers --- @@ -206,6 +230,8 @@ cargo fmt --check | `src/workflow/executor.rs` | YAML workflow DAG executor | | `src/vault/backlinks.rs` | Wikilink BFS graph traversal | | `crates/` | 12 workspace sub-crates (zero internal coupling) | +| `.knowledge/index.md` | Canonical OKF knowledge bundle entry point | +| `.knowledge/architecture/project-worktree.md` | Complete project worktree for module/file lookup | | `scripts/invariant-checks/run-checks.ps1` | CI architecture invariant checks | | `.cargo/config.toml` | Local cargo config (`RUST_TEST_THREADS=1`) | | `rustfmt.toml` | `edition = "2024"`, `max_width = 100` | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c7bdb1d..46fa182 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -140,7 +140,7 @@ cargo run -- mcp | **添加 MCP Tool** | `src/mcp/tools/` 新建模块 | `src/mcp/tools/mod.rs`, `src/mcp/mod.rs` | [AGENTS.md](AGENTS.md) "MCP 工具幂等性" | | **添加 Skill** | `skills/` 或外部 git 仓库 | `SKILL.md` 规范 | [AGENTS.md](AGENTS.md) "Skill 规范" | | **改进文档** | 直接编辑 `.md` 文件 | `README.md`, `AGENTS.md` | — | -| **重构 / 性能优化** | 先开 Issue 讨论 | — | [`docs/architecture/invariants.md`](docs/architecture/invariants.md) | +| **重构 / 性能优化** | 先开 Issue 讨论 | — | [`.knowledge/architecture/invariants.md`](../.knowledge/architecture/invariants.md) | ### 添加 MCP Tool 的标准路径 @@ -233,8 +233,9 @@ existence before registration. Returns structured validation report. | 文档 | 内容 | |:---|:---| -| [`docs/architecture/overview.md`](docs/architecture/overview.md) | 三层架构、技术决策记录、模块边界 | -| [`docs/architecture/invariants.md`](docs/architecture/invariants.md) | 架构红线 RF-1~RF-7 + 分层约束 | +| [`.knowledge/architecture/three-layer-model.md`](../.knowledge/architecture/three-layer-model.md) | 三层架构：交互层 → 编译层 → 可靠层 | +| [`.knowledge/architecture/dependency-topology.md`](../.knowledge/architecture/dependency-topology.md) | 11-Tier 模块依赖拓扑 | +| [`.knowledge/architecture/invariants.md`](../.knowledge/architecture/invariants.md) | 架构红线 G1–G7 + 分层不变量 T01–T12 | | [`AGENTS.md`](AGENTS.md) | Agent 环境指引、安全原则、Schema 迁移规范 | | [`docs/architecture/`](docs/architecture/) | 预拆分评估、Workflow DSL 规范、统一实体模型 | | [`docs/research/`](docs/research/) | 竞品分析、Embedding 策略 | diff --git a/README.md b/README.md index 9a35c6b..cfd4390 100644 --- a/README.md +++ b/README.md @@ -91,7 +91,7 @@ devbase/ 2. **编译层** — 感知（tree-sitter/Tantivy/Git）→ 知识（图谱/向量/关系）→ 策略（同步/工作流/健康守卫） 3. **可靠层** — SQLite WAL 并发安全 + 索引健康检测 + OpLog 全操作审计 -> 可靠性红线：所有 Registry 写入必须留下不可变审计痕迹（OpLog）；Schema 迁移前自动生成快照。详见 [docs/architecture/overview.md](docs/architecture/overview.md)。 +> 可靠性红线：所有 Registry 写入必须留下不可变审计痕迹（OpLog）；Schema 迁移前自动生成快照。详见 [`.knowledge/architecture/invariants.md`](.knowledge/architecture/invariants.md)。 --- diff --git a/SUPPORT.md b/SUPPORT.md index 0926d7a..3fd98be 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -4,8 +4,8 @@ - **User Guide**: See [`README.md`](./README.md) for installation, quick start, and feature overview - **Documentation Index**: See [`docs/README.md`](./docs/README.md) for the full documentation map -- **Architecture**: See [`docs/architecture/overview.md`](./docs/architecture/overview.md) for technical design and module boundaries -- **Architecture Guardrails**: See [`docs/architecture/invariants.md`](./docs/architecture/invariants.md) for RF rules and tiered checks +- **Architecture**: See [`.knowledge/architecture/three-layer-model.md`](./.knowledge/architecture/three-layer-model.md) for technical design and module boundaries +- **Architecture Guardrails**: See [`.knowledge/architecture/invariants.md`](./.knowledge/architecture/invariants.md) for G/T rules and tiered checks - **Agent Guidelines**: See [`AGENTS.md`](./AGENTS.md) for MCP tool conventions and schema migration rules - **Contributing**: See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for build instructions and PR checklist - **Changelog**: See [`CHANGELOG.md`](./CHANGELOG.md) for version history diff --git a/docs/README.md b/docs/README.md index ee5202d..5d03d68 100644 --- a/docs/README.md +++ b/docs/README.md @@ -17,7 +17,7 @@ | Schema | v36 | `src/registry/migrate.rs` | | MCP Tools | **71**（5 Stable / 62 Beta / 4 Experimental） | `src/mcp/mod.rs` | | Workspace Crates | 12 | `crates/` | -| `main.rs` | 833 行（RF-4 ≤ 1000） | `wc -l` | +| `main.rs` | 836 行（RF-4 ≤ 1000） | `wc -l` | | RF-6 | ✅ 生产代码 unwrap/expect/panic 清零 | invariant checks | --- @@ -34,8 +34,8 @@ | 开发者 | 数据库 Schema 完整定义 | [`reference/schema-v36.md`](reference/schema-v36.md) | | 开发者 | 统一实体模型（entities/relations） | [`reference/entities-model.md`](reference/entities-model.md) | | 开发者 | 71 个 MCP 工具速查 | [`reference/mcp-tools.md`](reference/mcp-tools.md) | -| Agent | 项目架构定义 | [`architecture/context-compiler.md`](architecture/context-compiler.md) | -| Agent | 架构红线与不变量 | [`architecture/invariants.md`](architecture/invariants.md) | +| Agent | 项目架构定义 | [`../.knowledge/architecture/index.md`](../.knowledge/architecture/index.md) | +| Agent | 架构红线与不变量 | [`../.knowledge/architecture/invariants.md`](../.knowledge/architecture/invariants.md) | | 维护者 | 功能路线图 | [`ROADMAP.md`](ROADMAP.md) | | 维护者 | 已知问题与技术债务 | [`../KNOWN_ISSUES.md`](../KNOWN_ISSUES.md) | @@ -49,11 +49,8 @@ | 文档 | 说明 | |------|------| -| [`architecture/overview.md`](architecture/overview.md) | 三层架构：字节 → 语义 → 行动 | -| [`architecture/context-compiler.md`](architecture/context-compiler.md) | **核心定义**：本地情境编译器 — 五层架构、六维信息模型 | +| [`../.knowledge/architecture/index.md`](../.knowledge/architecture/index.md) | **OKF 权威架构概念索引**（Agent 优先阅读） | | [`architecture/workflow-dsl.md`](architecture/workflow-dsl.md) | Workflow DSL 规范（YAML 多步骤编排） | -| [`architecture/dependency-topology.md`](architecture/dependency-topology.md) | 模块依赖拓扑（Tier 1–11） | -| [`architecture/invariants.md`](architecture/invariants.md) | **架构红线** RF-1~RF-7 + 分层约束 G/T | | [`architecture/split-plan.md`](architecture/split-plan.md) | Workspace crate 拆分计划 | | [`architecture/pre-split-evaluation.md`](architecture/pre-split-evaluation.md) | 单 crate vs 多 crate 评估 | | [`architecture/adr-template.md`](architecture/adr-template.md) | ADR 模板与已完成决策索引 | @@ -132,6 +129,10 @@ | [`_archive/roadmap-2026.md`](_archive/roadmap-2026.md) | 严重过时（v0.2.3） | | [`_archive/skill-runtime.md`](_archive/skill-runtime.md) | 已完全实现 | | [`_archive/tui-skill-integration.md`](_archive/tui-skill-integration.md) | 已完全实现 | +| [`_archive/overview.md`](_archive/overview.md) | 历史三层架构讨论，已迁移至 `.knowledge/architecture/three-layer-model.md` | +| [`_archive/context-compiler.md`](_archive/context-compiler.md) | v0.13.0 历史架构定义，已迁移至 `.knowledge/architecture/` | +| [`_archive/dependency-topology.md`](_archive/dependency-topology.md) | 历史 11-Tier 拓扑，已迁移至 `.knowledge/architecture/dependency-topology.md` | +| [`_archive/invariants.md`](_archive/invariants.md) | 历史不变量清单，已迁移至 `.knowledge/architecture/invariants.md` | | `_archive/*` | 其余见目录内文件 | ### 📊 运维与进度（Ops & Progress） diff --git a/docs/architecture/context-compiler.md b/docs/_archive/context-compiler.md similarity index 93% rename from docs/architecture/context-compiler.md rename to docs/_archive/context-compiler.md index 086473b..ca333fa 100644 --- a/docs/architecture/context-compiler.md +++ b/docs/_archive/context-compiler.md @@ -1,169 +1,171 @@ -# devbase 架构定义：本地情境编译器 - -> **版本**：v0.13.0 -> **定位**：devbase 是 AI Agent 在本地数字世界中的海马体——情境编译器（Local Context Compiler）。 -> **核心功能**：将本地数字资产的原始数据（代码库、笔记、Skill、工作流）编译为 AI 可决策的结构化情境。 -> **明确不做**：不替代文件读取、不替代版本控制、不替代包管理。 - ---- - -## 一、为什么需要情境编译器 - -LLM 在本地开发环境中的核心困境： - -1. **看不见**：不知道本地有哪些项目、笔记、Skill -2. **读不完**：面对数万行代码，无法判断"该读哪些、为什么读" -3. **记不住**：跨会话丢失上下文，每次从零开始 -4. **关系盲**：知道有 A 和 B，不知道 A 调用 B、B 依赖 C - -devbase 解决的是**前两个问题**（感知 + 编码），让 LLM 在调用文件工具之前，先获得"该读哪些文件、为什么读、它们之间的关系"。后两个问题（持久化 + 关系）在 v0.13.0 中部分落地。 - ---- - -## 二、五层架构 - -``` -┌─────────────────────────────────────────┐ -│ 认知层：Kimi CLI / Claude / 其他 AI │ ← 决策与执行（devbase 不介入） -├─────────────────────────────────────────┤ -│ 协议层：MCP (JSON-RPC 2.0 / stdio) │ ← 神经突触，38 个 tools -├─────────────────────────────────────────┤ -│ 编译层：project_context / relations │ ← 按目标过滤、生成相关结构 -│ 编码层：entities / entity_types │ ← 统一模型、类型定义 -│ 感知层：scan / index / health │ ← 扫描文件系统、感知存在性 -├─────────────────────────────────────────┤ -│ 持久层：SQLite + Vault + OpLog │ ← 跨会话记忆 -│ 资源层：本地文件系统 │ ← 原始数据，唯一真相源 -└─────────────────────────────────────────┘ -``` - -### 各层职责 - -| 层级 | 模块 | 职责 | -|------|------|------| -| 感知层 | `scan`, `index`, `health` | 发现本地有哪些代码库、笔记、Skill；提取模块结构、代码符号、调用图 | -| 编码层 | `entities`, `entity_types`, `relations` | 统一实体模型：所有对象（repo/skill/paper/vault_note/workflow）以同一套 schema 存储 | -| 编译层 | `project_context`, `dependency_graph`, `symbol_links` | 将原始数据按目标过滤、组装为 AI 可消费的上下文切片 | -| 协议层 | `mcp` | MCP Server，stdio 传输，38 个工具，tier 分级（Stable/Beta/Experimental） | -| 持久层 | `registry` (SQLite), `vault`, `oplog` | 结构化索引 + 文件系统笔记 + 操作审计 | - ---- - -## 三、统一实体模型（Schema v16+） - -devbase 不再内置固定概念（repos、skills、vault_notes、papers...），而是通过**三张核心表**定义 workspace 结构： - -```sql --- 实体类型定义（可扩展） -CREATE TABLE entity_types ( - name TEXT PRIMARY KEY, - schema_json TEXT NOT NULL, -- 该类型允许的字段、校验规则 - description TEXT, - created_at TEXT NOT NULL -); - --- 实体实例（所有对象的统一存储） -CREATE TABLE entities ( - id TEXT PRIMARY KEY, - entity_type TEXT NOT NULL REFERENCES entity_types(name), - name TEXT NOT NULL, - source_url TEXT, - local_path TEXT, - metadata TEXT, -- JSON，动态字段 - content_hash TEXT, - created_at TEXT NOT NULL, - updated_at TEXT NOT NULL -); - --- 实体间关系（有向图） -CREATE TABLE relations ( - id TEXT PRIMARY KEY, - from_entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE, - to_entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE, - relation_type TEXT NOT NULL, - metadata TEXT, - confidence REAL NOT NULL DEFAULT 1.0, - created_at TEXT NOT NULL -); -``` - -### 内置实体类型 - -| 类型 | 说明 | 典型 metadata 字段 | -|------|------|-------------------| -| `repo` | Git 代码库 | language, workspace_type, data_tier, stars | -| `skill` | 可执行 Skill | author, version, tags, entry_script, skill_type | -| `paper` | 学术文献 | authors, venue, year, bibtex, tags | -| `vault_note` | Vault Markdown 笔记 | tags, outgoing_links, linked_repo, frontmatter | -| `workflow` | 工作流定义 | steps_json, inputs_schema, outputs_schema | - -### 优势 - -- **新增概念无需改表**：新增 `entity_type` 记录即可，无需 `ALTER TABLE` -- **统一查询语言**：所有对象通过 `entities` + `entity_type` 过滤，JOIN `relations` 获取关联 -- **关系即数据**：代码依赖、论文引用、笔记反链都以 `relations` 存储，支持图遍历 - ---- - -## 四、六维信息模型与当前供给 - -LLM 决策需要六维结构化情境： - -| 维度 | 人类等效 | v0.13.0 供给状态 | -|------|---------|-----------------| -| **Situation** | "我房间里有什么书？" | ✅ `scan` + `query_repos` + `vault_search` 提供全景 | -| **State** | "哪些书还没读完？" | ✅ `health` + `index` 状态 + Git dirty/behind/ahead | -| **Relations** | "这本书引用了哪本？" | 🟡 `relations` 表已激活（v24 迁移），`project_context` 包含 `related_symbols` | -| **Capability** | "我可以用笔划线、用书签标记" | ✅ 38 个 MCP tools，`project_context` 聚合 | -| **History** | "上次读这本书到哪一章？" | 🟡 `project_context` 包含 `activity`（最近 10 条 oplog）；`agent_symbol_reads` 表已激活（v25），用于行为信号 boosting | -| **Relevance** | "我现在要写论文，哪些书相关？" | 🟡 `project_context` 支持 `goal` 参数，通过 `hybrid_search_symbols` 关联排序 | - ---- - -## 五、与 AI Agent 的契约 - -### devbase 的承诺 - -- **协议稳定**：MCP 消息格式符合规范（Content-Length 头，无尾随字节），notification 静默处理 -- **默认安全**：destructive 工具（sync/skill_run）需 `DEVBASE_MCP_ENABLE_DESTRUCTIVE=1` 显式启用；vault 路径锁定 workspace 根目录；skill 环境白名单隔离 -- **结构可消费**：返回 JSON，含 `success` / `error` 统一字段，schema 自描述 - -### AI Agent 的最佳实践 - -1. **先问 devbase，再读文件**：复杂任务先调用 `project_context` 获取模块树 + 符号 + 调用关系，再按需读文件 -2. **利用 Vault 做跨会话记忆**：关键决策写入 Vault（`vault_write`），下次会话通过 `vault_search` 召回 -3. **通过 OpLog 审计**：重要操作后查询 `devkit_oplog_query` 确认执行记录 - ---- - -## 六、数据流示例："分析 sync 模块" - -``` -1. 感知层：scan 发现 devbase 项目 - └─ index 提取模块结构（cargo metadata） - └─ semantic_index 提取符号 + 调用图 - -2. 编码层：entities 存储 repo 元数据 - └─ repo_modules 表存储 cargo targets - └─ code_symbols 表存储函数/结构体/枚举 - └─ code_call_graph 表存储调用边 - -3. 编译层：project_context("devbase", goal="sync policy") - └─ 返回 repo 元数据 + vault 笔记 + assets - └─ 返回 modules（cargo targets） - └─ 返回 symbols（ relevance-ranked Top 50）+ calls（filtered Top 50） - └─ 返回 activity（最近 10 条 oplog）+ related_symbols（概念关联符号） - -4. 协议层：MCP 将 JSON 传给 Kimi CLI - -5. 认知层：Kimi CLI 决定读取 src/sync/policy.rs -``` - ---- - -## 七、相关文档 - -- [`reference/schema-v23.md`](../reference/schema-v23.md) — 数据库 Schema 完整定义 -- [`reference/entities-model.md`](../reference/entities-model.md) — 统一实体模型查询模式 -- [`reference/mcp-tools.md`](../reference/mcp-tools.md) — 38 个 MCP 工具速查 -- [`guides/quickstart.md`](../guides/quickstart.md) — 5 分钟上手指南 +> **⚠️ 文档迁移提示**：本文件为 v0.13.0 历史架构定义。最新架构总览与五层/三层模型已按 OKF 整理至 `.knowledge/architecture/`。本文件保留历史设计思想，但其中的工具数量（38 tools）、schema 版本（v16）、项目版本（v0.13.0）均已过时。最新数据：v0.20.1 / Schema v36 / 71 MCP tools / 12 workspace crates。 + +# devbase 架构定义：本地情境编译器 + +> **版本**：v0.13.0 +> **定位**：devbase 是 AI Agent 在本地数字世界中的海马体——情境编译器（Local Context Compiler）。 +> **核心功能**：将本地数字资产的原始数据（代码库、笔记、Skill、工作流）编译为 AI 可决策的结构化情境。 +> **明确不做**：不替代文件读取、不替代版本控制、不替代包管理。 + +--- + +## 一、为什么需要情境编译器 + +LLM 在本地开发环境中的核心困境： + +1. **看不见**：不知道本地有哪些项目、笔记、Skill +2. **读不完**：面对数万行代码，无法判断"该读哪些、为什么读" +3. **记不住**：跨会话丢失上下文，每次从零开始 +4. **关系盲**：知道有 A 和 B，不知道 A 调用 B、B 依赖 C + +devbase 解决的是**前两个问题**（感知 + 编码），让 LLM 在调用文件工具之前，先获得"该读哪些文件、为什么读、它们之间的关系"。后两个问题（持久化 + 关系）在 v0.13.0 中部分落地。 + +--- + +## 二、五层架构 + +``` +┌─────────────────────────────────────────┐ +│ 认知层：Kimi CLI / Claude / 其他 AI │ ← 决策与执行（devbase 不介入） +├─────────────────────────────────────────┤ +│ 协议层：MCP (JSON-RPC 2.0 / stdio) │ ← 神经突触，38 个 tools +├─────────────────────────────────────────┤ +│ 编译层：project_context / relations │ ← 按目标过滤、生成相关结构 +│ 编码层：entities / entity_types │ ← 统一模型、类型定义 +│ 感知层：scan / index / health │ ← 扫描文件系统、感知存在性 +├─────────────────────────────────────────┤ +│ 持久层：SQLite + Vault + OpLog │ ← 跨会话记忆 +│ 资源层：本地文件系统 │ ← 原始数据，唯一真相源 +└─────────────────────────────────────────┘ +``` + +### 各层职责 + +| 层级 | 模块 | 职责 | +|------|------|------| +| 感知层 | `scan`, `index`, `health` | 发现本地有哪些代码库、笔记、Skill；提取模块结构、代码符号、调用图 | +| 编码层 | `entities`, `entity_types`, `relations` | 统一实体模型：所有对象（repo/skill/paper/vault_note/workflow）以同一套 schema 存储 | +| 编译层 | `project_context`, `dependency_graph`, `symbol_links` | 将原始数据按目标过滤、组装为 AI 可消费的上下文切片 | +| 协议层 | `mcp` | MCP Server，stdio 传输，38 个工具，tier 分级（Stable/Beta/Experimental） | +| 持久层 | `registry` (SQLite), `vault`, `oplog` | 结构化索引 + 文件系统笔记 + 操作审计 | + +--- + +## 三、统一实体模型（Schema v16+） + +devbase 不再内置固定概念（repos、skills、vault_notes、papers...），而是通过**三张核心表**定义 workspace 结构： + +```sql +-- 实体类型定义（可扩展） +CREATE TABLE entity_types ( + name TEXT PRIMARY KEY, + schema_json TEXT NOT NULL, -- 该类型允许的字段、校验规则 + description TEXT, + created_at TEXT NOT NULL +); + +-- 实体实例（所有对象的统一存储） +CREATE TABLE entities ( + id TEXT PRIMARY KEY, + entity_type TEXT NOT NULL REFERENCES entity_types(name), + name TEXT NOT NULL, + source_url TEXT, + local_path TEXT, + metadata TEXT, -- JSON，动态字段 + content_hash TEXT, + created_at TEXT NOT NULL, + updated_at TEXT NOT NULL +); + +-- 实体间关系（有向图） +CREATE TABLE relations ( + id TEXT PRIMARY KEY, + from_entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE, + to_entity_id TEXT NOT NULL REFERENCES entities(id) ON DELETE CASCADE, + relation_type TEXT NOT NULL, + metadata TEXT, + confidence REAL NOT NULL DEFAULT 1.0, + created_at TEXT NOT NULL +); +``` + +### 内置实体类型 + +| 类型 | 说明 | 典型 metadata 字段 | +|------|------|-------------------| +| `repo` | Git 代码库 | language, workspace_type, data_tier, stars | +| `skill` | 可执行 Skill | author, version, tags, entry_script, skill_type | +| `paper` | 学术文献 | authors, venue, year, bibtex, tags | +| `vault_note` | Vault Markdown 笔记 | tags, outgoing_links, linked_repo, frontmatter | +| `workflow` | 工作流定义 | steps_json, inputs_schema, outputs_schema | + +### 优势 + +- **新增概念无需改表**：新增 `entity_type` 记录即可，无需 `ALTER TABLE` +- **统一查询语言**：所有对象通过 `entities` + `entity_type` 过滤，JOIN `relations` 获取关联 +- **关系即数据**：代码依赖、论文引用、笔记反链都以 `relations` 存储，支持图遍历 + +--- + +## 四、六维信息模型与当前供给 + +LLM 决策需要六维结构化情境： + +| 维度 | 人类等效 | v0.13.0 供给状态 | +|------|---------|-----------------| +| **Situation** | "我房间里有什么书？" | ✅ `scan` + `query_repos` + `vault_search` 提供全景 | +| **State** | "哪些书还没读完？" | ✅ `health` + `index` 状态 + Git dirty/behind/ahead | +| **Relations** | "这本书引用了哪本？" | 🟡 `relations` 表已激活（v24 迁移），`project_context` 包含 `related_symbols` | +| **Capability** | "我可以用笔划线、用书签标记" | ✅ 38 个 MCP tools，`project_context` 聚合 | +| **History** | "上次读这本书到哪一章？" | 🟡 `project_context` 包含 `activity`（最近 10 条 oplog）；`agent_symbol_reads` 表已激活（v25），用于行为信号 boosting | +| **Relevance** | "我现在要写论文，哪些书相关？" | 🟡 `project_context` 支持 `goal` 参数，通过 `hybrid_search_symbols` 关联排序 | + +--- + +## 五、与 AI Agent 的契约 + +### devbase 的承诺 + +- **协议稳定**：MCP 消息格式符合规范（Content-Length 头，无尾随字节），notification 静默处理 +- **默认安全**：destructive 工具（sync/skill_run）需 `DEVBASE_MCP_ENABLE_DESTRUCTIVE=1` 显式启用；vault 路径锁定 workspace 根目录；skill 环境白名单隔离 +- **结构可消费**：返回 JSON，含 `success` / `error` 统一字段，schema 自描述 + +### AI Agent 的最佳实践 + +1. **先问 devbase，再读文件**：复杂任务先调用 `project_context` 获取模块树 + 符号 + 调用关系，再按需读文件 +2. **利用 Vault 做跨会话记忆**：关键决策写入 Vault（`vault_write`），下次会话通过 `vault_search` 召回 +3. **通过 OpLog 审计**：重要操作后查询 `devkit_oplog_query` 确认执行记录 + +--- + +## 六、数据流示例："分析 sync 模块" + +``` +1. 感知层：scan 发现 devbase 项目 + └─ index 提取模块结构（cargo metadata） + └─ semantic_index 提取符号 + 调用图 + +2. 编码层：entities 存储 repo 元数据 + └─ repo_modules 表存储 cargo targets + └─ code_symbols 表存储函数/结构体/枚举 + └─ code_call_graph 表存储调用边 + +3. 编译层：project_context("devbase", goal="sync policy") + └─ 返回 repo 元数据 + vault 笔记 + assets + └─ 返回 modules（cargo targets） + └─ 返回 symbols（ relevance-ranked Top 50）+ calls（filtered Top 50） + └─ 返回 activity（最近 10 条 oplog）+ related_symbols（概念关联符号） + +4. 协议层：MCP 将 JSON 传给 Kimi CLI + +5. 认知层：Kimi CLI 决定读取 src/sync/policy.rs +``` + +--- + +## 七、相关文档 + +- [`reference/schema-v23.md`](../reference/schema-v23.md) — 数据库 Schema 完整定义 +- [`reference/entities-model.md`](../reference/entities-model.md) — 统一实体模型查询模式 +- [`reference/mcp-tools.md`](../reference/mcp-tools.md) — 38 个 MCP 工具速查 +- [`guides/quickstart.md`](../guides/quickstart.md) — 5 分钟上手指南 diff --git a/docs/architecture/dependency-topology.md b/docs/_archive/dependency-topology.md similarity index 96% rename from docs/architecture/dependency-topology.md rename to docs/_archive/dependency-topology.md index 0b4c287..2caae49 100644 --- a/docs/architecture/dependency-topology.md +++ b/docs/_archive/dependency-topology.md @@ -1,324 +1,326 @@ -# devbase 依赖拓扑规划 - -> 本文件按**模块间依赖关系**（而非时间排期）重新组织 devbase 的功能演进顺序。 -> -> 原则：**下层为上层提供契约，上层为下层提供场景验证。** 改动下层（高扇入枢纽）影响面大，需更严格测试；叶节点可独立迭代实验。 - ---- - -## 一、拓扑总览 - -```text -Tier 11 ┌────────────────────────────────────────┐ - │ main.rs / daemon.rs │ ← CLI 入口、守护进程 -Tier 10 ├────────────────────────────────────────┤ - │ tui/ (theme/layout/state/event/render)│ ← 终端交互层 -Tier 9 ├────────────────────────────────────────┤ - │ mcp/ (mod + tools/*) │ ← MCP 协议适配层，35 tools -Tier 8 ├────────────────────────────────────────┤ - │ knowledge_engine, skill_sync, vault │ ← 高级聚合、跨层桥接 -Tier 7 ├────────────────────────────────────────┤ - │ workflow/ (model/parser/validator/ │ ← Workflow 编排引擎 - │ interpolate/scheduler/ │ - │ state/executor) │ -Tier 6 ├────────────────────────────────────────┤ - │ skill_runtime/ (parser/registry/ │ ← Skill 全生命周期 - │ discover/dependency/ │ - │ executor/scoring/ │ - │ publish/clarity_sync) │ -Tier 5 ├────────────────────────────────────────┤ - │ sync/ (policy/tasks/orchestrator) │ ← 同步编排 - │ watch │ ← 文件系统监控 -Tier 4 ├────────────────────────────────────────┤ - │ query, health, oplog_analytics │ ← 查询与报告 - │ search/hybrid │ ← 混合检索 -Tier 3 ├────────────────────────────────────────┤ - │ dependency_graph, symbol_links │ ← 代码分析关联 - │ vault/indexer, vault/backlinks │ ← Vault 索引与链接 -Tier 2 ├────────────────────────────────────────┤ - │ scan, vault/scanner, discovery_engine │ ← 扫描与发现 - │ backup, test_utils │ ← 备份与测试辅助 -Tier 1 ├────────────────────────────────────────┤ - │ registry/ (类型定义 + CRUD impl) │ ← 数据契约中心 - │ vault/{fs_io,frontmatter,wikilink} │ ← Vault 原子操作 - │ semantic_index, embedding, search │ ← 索引原子能力 - │ arxiv │ ← 外部论文 API -Tier 0 ├────────────────────────────────────────┤ - │ core, i18n, config, asyncgit │ ← 类型根与配置根 - │ sync_protocol │ ← 同步协议基础类型 - └────────────────────────────────────────┘ -``` - ---- - -## 二、逐层规划 - -### Tier 0 — 原子基础层 - -**目的**：为整个系统提供**无业务语义**的底层能力，任何改动都不应破坏上层编译。 - -| 模块 | 功能 | 依赖数 | 被依赖数 | -|:---|:---|:---:|:---:| -| `core` | NodeType / Node / Edge 统一实体枚举 | 0 | 中 | -| `i18n` | 静态字符串表（en/zh_cn） | 0 | **高** | -| `config` | 配置结构体：LLM、Embedding、Sync、Daemon | 0 | **高** | -| `asyncgit` | 异步 Git 状态通知通道（crossbeam） | 0 | 中 | -| `sync_protocol` | FileInfo / SyncIndex / scan_directory | 0 | 低 | - -**迭代策略**：极度稳定，变更需全量回归。`i18n` 新增字段需同步所有语言文件。 - ---- - -### Tier 1 — 数据契约与原子能力层 - -**目的**：定义**领域模型**和**可独立工作的原子能力**。registry 是整个系统的"心脏"，所有业务数据最终落盘于此。 - -| 模块/子模块 | 功能 | 依赖 | 被依赖 | -|:---|:---|:---|:---| -| `registry/` | SQLite Schema v17 + CRUD：repos/repo_tags/code_symbols/code_embeddings/code_call_graph/code_symbol_links/oplog/vault_notes/papers/experiments/skills/skill_executions/entities/entity_types/relations/workflows/workflow_executions | Tier 0 (dirs) | **几乎所有上层** | -| `vault/fs_io` | Vault 文件读写原子操作 | 无 | vault/* | -| `vault/frontmatter` | YAML frontmatter 解析 | 无 | vault/scanner, skill_sync | -| `vault/wikilink` | `[[wikilink]]` 提取 | 无 | vault/scanner | -| `semantic_index` | tree-sitter 多语言符号提取（Rust/Python/TS/Go） | 无 | scan, mcp tools, search/hybrid | -| `embedding` | cosine_similarity、BLOB 序列化、query embedding 生成 | 无 | search/hybrid, mcp tools | -| `search` | Tantivy 索引初始化（id/title/content/tags/doc_type） | 无 | vault/indexer, search/hybrid, mcp tools | -| `arxiv` | arXiv API 元数据抓取 | 无 | mcp tools | - -**关键决策**：registry 的 Schema 变更是**全局阻塞点**。任何新增表/字段必须： -1. 更新 `registry/migrate.rs` 的 `PRAGMA user_version` -2. 触发 `backup::auto_backup_before_migration()` -3. 同步修改 `oplog_analytics.rs` 的表存在性检查 - ---- - -### Tier 2 — 扫描与发现层 - -**目的**：将**无结构的外部世界**（文件系统、Git 仓库）转化为 registry 中的结构化数据。 - -| 模块 | 功能 | 上游依赖 | 下游产出 | -|:---|:---|:---|:---| -| `scan` | Git 仓库发现、语言检测、代码统计（tokei）、blake3 快照、自动注册 | registry, config | registry 各表 | -| `vault/scanner` | Vault 目录遍历、frontmatter/wikilink 提取、注册到 vault_notes | registry, vault/* | registry.vault_notes | -| `discovery_engine` | 跨仓库 Cargo.toml 依赖关联发现 | registry::RepoEntry | registry（待扩展） | -| `backup` | Schema 迁移前自动快照（保留 10 个） | registry | registry（文件系统） | -| `test_utils` | 测试辅助：临时 registry、mock repo | registry | 测试代码 | - -**迭代策略**：scan 是数据入口，新增语言支持或检测规则在此层实验，不影响查询层。 - ---- - -### Tier 3 — 分析与关联层 - -**目的**：在已结构化数据上建立**语义关联**，为查询层提供"图"能力。 - -| 模块 | 功能 | 输入数据 | 产出 | -|:---|:---|:---|:---| -| `dependency_graph` | 跨仓库依赖图构建 | scan 发现的 Cargo.toml/package.json | 图结构（待深化） | -| `symbol_links` | Jaccard 签名相似度 + 同文件聚类 → code_symbol_links | registry.code_symbols | registry.code_symbol_links | -| `vault/indexer` | Vault 笔记入 Tantivy 全文索引 | vault_notes, search | Tantivy 索引文档 | -| `vault/backlinks` | Vault 反向链接图谱 | vault_notes.outgoing_links | 关联查询结果 | - -**迭代策略**：symbol_links 的阈值（默认 0.3）和算法可在此层独立调优，不破坏下游 API。 - ---- - -### Tier 4 — 查询与报告层 - -**目的**：为上层（MCP/TUI）提供**只读查询接口**，是"知识库"的对外窗口。 - -| 模块 | 功能 | 依赖 | -|:---|:---|:---| -| `query` | 结构化表达式解析：`lang:rust stale:>30 behind:>10 tag:x` | registry | -| `health` | dirty/ahead/behind/diverged 计算、workspace 快照哈希 | registry, git2 | -| `oplog_analytics` | 知识覆盖报告：symbol/embedding/call 覆盖率、健康汇总、最近活动 | registry（多表聚合） | -| `search/hybrid` | RRF 归并：向量语义搜索 + Tantivy BM25 关键词 + 自动降级 | semantic_index, search, embedding | - -**关键约束**：查询层必须保持**向后兼容**。MCP tool schema 的 breaking change 只能通过新增 tool（如 `_v2`）而非修改现有 tool。 - ---- - -### Tier 5 — 同步编排层 - -**目的**：将 registry 中的**期望状态**（upstream_url、tags、policy）与文件系统的**实际状态**对齐。 - -| 模块 | 功能 | 依赖关系 | -|:---|:---|:---| -| `sync/policy` | SyncPolicy / SyncMode / RepoSyncTask 定义、错误分类 | 独立（git2） | -| `sync/tasks` | 单仓库 fetch/pull/rebase/merge 执行、OpLog 写入 | registry::WorkspaceRegistry, policy | -| `sync/orchestrator` | 并发信号量控制、批量执行、超时处理、进度回调 | policy, tasks | -| `watch` | notify 文件系统监控、事件聚合 | sync_protocol | - -**迭代策略**：sync 是**危险操作层**。新增 sync 策略（如 `SyncPolicy::StashThenRebase`）需先在 policy 层定义，再在 tasks 层实现，最后由 orchestrator 编排。 - ---- - -### Tier 6 — Skill Runtime 层 - -**目的**：实现 Skill 的**全生命周期管理**，是阶段二的核心交付物。 - -| 子模块 | 功能 | 依赖 | -|:---|:---|:---| -| `parser` | SKILL.md YAML frontmatter → SkillMeta | 独立 | -| `registry` | skills/skill_executions 表 CRUD、skill 安装/卸载 | registry::WorkspaceRegistry | -| `discover` | 项目类型检测（Rust/Node/Python/Go/Docker/Generic）→ SKILL.md 自动生成 + entry_script 包装 | parser | -| `dependency` | Skill 依赖图拓扑排序（Kahn）、DFS 环检测 | skill_runtime::registry | -| `executor` | Process-based 执行、interpreter 自动探测、timeout、stdout/stderr 捕获 | skill_runtime types | -| `scoring` | success_rate / usage_count / rating 计算（0–5 分公式） | registry + skill_runtime::registry | -| `publish` | validate → git tag → push remote | git2 + registry | -| `clarity_sync` | Skill 导出为 Clarity plan JSON | registry + skill_runtime types | - -**依赖关系**： -```text -parser → discover -registry → dependency → executor -registry + executor → scoring -``` - ---- - -### Tier 7 — Workflow 引擎层 - -**目的**：将多个 Skill/子工作流编排为**可复用的自动化流程**。 - -| 子模块 | 功能 | 依赖 | -|:---|:---|:---| -| `model` | WorkflowDefinition / StepDefinition / StepType / ErrorPolicy | 独立 | -| `parser` | YAML → model（untagged 反序列化） | model | -| `validator` | 步骤 ID 唯一性、依赖存在性检查 | model | -| `interpolate` | `${inputs.x}` / `${steps.y.outputs.z}` 变量插值 | 独立 | -| `scheduler` | Kahn 拓扑排序 → ExecutionBatch（可并行步骤组） | model | -| `state` | workflow_executions 表 CRUD、状态机转换 | model + registry | -| `executor` | batch 并行执行（`std::thread::scope`）、错误策略（Fail/Continue/Retry/Fallback）、子工作流递归 | scheduler + model + skill_runtime::executor + registry | - -**依赖关系**： -```text -model ← parser / validator / scheduler -scheduler → executor -skill_runtime::executor → executor -``` - ---- - -### Tier 8 — 高级聚合与跨层桥接 - -**目的**：连接原本正交的子系统，产生**涌现能力**。 - -| 模块 | 功能 | 跨层连接 | -|:---|:---|:---| -| `knowledge_engine` | block_on_async 安全封装、README 摘要提取、模块信息探测 | registry ↔ 外部进程 | -| `skill_sync` | Vault 笔记（ai_context=true）→ Clarity SKILL.md 格式导出 | vault ↔ skill_runtime | -| `vault/mod` | Vault 子系统统一出口 | 聚合 vault/* | - ---- - -### Tier 9 — MCP 协议层 - -**目的**：将所有下层能力**封装为标准协议接口**，供 Clarity 等 AI Agent 调用。 - -| 子模块 | 对应 Tools | 依赖的下层模块 | -|:---|:---|:---| -| `tools/repo` | scan, health, sync, query_repos | scan, health, sync, query | -| `tools/query` | query, index, code_metrics, module_graph | query, scan, semantic_index | -| `tools/vault` | vault_search, vault_read, vault_write, vault_backlinks | vault/*, search | -| `tools/skill` | skill_list, skill_search, skill_run, skill_top | skill_runtime/* | -| `tools/context` | project_context, natural_language_query, hybrid_search, cross_repo_search, related_symbols, knowledge_report, embedding_store, embedding_search | search/hybrid, embedding, oplog_analytics, query | -| `mcp/mod` | 框架：McpTool trait、invoke_stream、ToolStreamEvent | 聚合上述所有 tools | - -**关键契约**： -- 所有状态变更操作必须**幂等**（`ON CONFLICT ... DO UPDATE/NOTHING`） -- 所有批量操作包裹在 SQLite transaction 中 -- Breaking change 通过新增 tool 实现，不修改现有 tool schema - ---- - -### Tier 10 — TUI 交互层 - -**目的**：为人类开发者提供**终端仪表盘**。 - -| 子模块 | 功能 | 依赖 | -|:---|:---|:---| -| `theme` | Design Token（primary/secondary/error 等色彩语义） | 独立 | -| `layout` | 响应式布局计算（35/65 分栏、compact 模式、居中弹窗） | 独立 | -| `state` | App 状态机：仓库列表、Skill 面板、Workflow 弹窗、NLQ 输入、同步进度 | asyncgit, registry, sync::SyncOrchestrator, config | -| `event` | 键盘事件路由、异步通知消费（AsyncNotification） | state, render::ui | -| `render/detail` | 右侧详情页（Overview/Health/Insights） | state, theme, layout | -| `render/list` | 左侧仓库列表（状态图标、排序、过滤） | state, theme, layout | -| `render/popups` | 搜索/同步/Skill/Workflow/NLQ 弹窗 | state, theme, layout | -| `render/help` | 快捷键帮助覆盖层 | state, theme, layout | -| `render/logs` | 底部日志面板 | state, theme, layout | - -**迭代策略**：TUI 是纯消费者层，新增面板（如 `render/loop_step.rs`）不改动任何下层逻辑。 - ---- - -### Tier 11 — 系统入口 - -| 模块 | 功能 | 依赖 | -|:---|:---|:---| -| `main.rs` | CLI 子命令解析（clap）、模块路由 | **所有上层** | -| `daemon.rs` | 定时 tick：stale repo health check、自动 sync | config, health, sync | - ---- - -## 三、枢纽分析 - -### 高扇入模块（改动影响大，需谨慎） - -| 模块 | 扇入来源 | 风险等级 | -|:---|:---|:---:| -| `registry::WorkspaceRegistry` | scan, health, backup, query, oplog_analytics, sync, skill_runtime, workflow, vault, mcp tools, tui | 🔴 | -| `i18n` | sync, digest, tui/render/* | 🟡 | -| `config` | scan, tui/state, sync, daemon | 🟡 | -| `skill_runtime::executor` | workflow/executor, mcp tools, tui | 🟡 | - -### 叶节点模块（可独立迭代，影响面小） - -| 模块 | 说明 | 实验优先级 | -|:---|:---|:---:| -| `arxiv` | 仅被 1 个 MCP tool 使用 | ⭐⭐⭐ | -| `semantic_index` | 仅被 scan 和 search/hybrid 使用，接口稳定 | ⭐⭐⭐ | -| `embedding` | 纯函数工具包，无副作用 | ⭐⭐⭐ | -| `vault/wikilink` | 解析规则可独立调优 | ⭐⭐ | -| `workflow/model` | 模型字段扩展不影响下层 | ⭐⭐ | - ---- - -## 四、基于依赖的迭代策略 - -### 1. 根节点加固（Tier 0–1） -- **registry Schema** 的任何变更需经过：migration 脚本 → 备份逻辑 → oplog_analytics 表存在性检查 → MCP tool schema 兼容性审查 -- **i18n** 新增字段需全语言覆盖，否则 TUI 会出现空字符串 - -### 2. 数据管道扩展（Tier 2–3） -- 新增语言支持（如 `tree-sitter-zig`）：在 `semantic_index` 扩展 → `scan` 触发索引 → `symbol_links` 自动关联 → `search/hybrid` 无需改动即可搜索 -- 新增 Vault 笔记格式：在 `vault/frontmatter` 或 `vault/wikilink` 实验 → `vault/scanner` 消费 → `vault/indexer` 入 Tantivy - -### 3. 查询能力叠加（Tier 4） -- `search/hybrid` 的 RRF 权重、Tantivy 与 embedding 的融合策略可独立调优 -- `oplog_analytics` 的新报表类型只需读取 registry，不改动写入路径 - -### 4. 编排能力实验（Tier 5–7） -- **Skill Runtime** 和 **Workflow** 是相对独立的"应用层"，可并行开发 -- Workflow 的 `StepType::Loop` 新增：只需在 `workflow/model` 加枚举 → `workflow/parser` 反序列化 → `workflow/executor` 实现循环逻辑 → 不影响 Skill Runtime - -### 5. 协议与界面适配（Tier 9–10） -- 新增 MCP tool：在对应 `tools/*` 子模块实现，注册到 `mcp/mod.rs` 的 `McpToolEnum`，零改动下层业务逻辑 -- 新增 TUI 面板：在 `render/` 新增子模块，由 `event.rs` 路由按键，零改动下层 - ---- - -## 五、与排期路线的对比 - -| 排期路线（时间线） | 拓扑路线（依赖线） | 差异说明 | -|:---|:---|:---| -| Wave 1–15b：数据层与索引 | Tier 0 → Tier 1 → Tier 2 → Tier 3 | 一致 | -| Wave 16–21：Skill Runtime | Tier 6（parser → registry → discover → dependency → executor → scoring） | 拓扑更细粒度展示子模块依赖 | -| Wave 22–25：Workflow Engine | Tier 7（model → parser → scheduler → executor） | 明确 Workflow 依赖 Skill Runtime executor | -| Wave 26–27：NLQ + Mind Market | Tier 4（search/hybrid）+ Tier 6（scoring） | NLQ 是查询层增强，Mind Market 是 Skill 层增强，二者**无依赖关系**，可并行 | -| Wave 28–33：风险修复与硬化 | 跨 Tier（unwrap 清零涉及 Tier 6–7） | 质量工作横向穿透所有层 | -| Future：L0–L4 知识模型 | 可能新增 Tier 3.5（知识图谱层）或扩展 Tier 1 Schema | 需先定义模型与 registry 的映射 | -| Future：跨设备同步 | Tier 5（sync）+ Tier 11（daemon）扩展 | 依赖 syncthing-rust 的 REST API | - ---- - -*本文档作为架构决策参考，应与 `overview.md` 和 `AGENTS.md` 同步维护。* +> **⚠️ 文档迁移提示**：本文件为历史拓扑规划。最新、已维护的 11-Tier 模块依赖拓扑已按 OKF 整理至 `.knowledge/architecture/dependency-topology.md`，关键数据已更新为 v0.20.1 / Schema v36 / 71 MCP tools / 12 workspace crates。本文件保留历史上下文，但其中的工具数量、schema 版本等数字可能已过时。 + +# devbase 依赖拓扑规划 + +> 本文件按**模块间依赖关系**（而非时间排期）重新组织 devbase 的功能演进顺序。 +> +> 原则：**下层为上层提供契约，上层为下层提供场景验证。** 改动下层（高扇入枢纽）影响面大，需更严格测试；叶节点可独立迭代实验。 + +--- + +## 一、拓扑总览 + +```text +Tier 11 ┌────────────────────────────────────────┐ + │ main.rs / daemon.rs │ ← CLI 入口、守护进程 +Tier 10 ├────────────────────────────────────────┤ + │ tui/ (theme/layout/state/event/render)│ ← 终端交互层 +Tier 9 ├────────────────────────────────────────┤ + │ mcp/ (mod + tools/*) │ ← MCP 协议适配层，35 tools +Tier 8 ├────────────────────────────────────────┤ + │ knowledge_engine, skill_sync, vault │ ← 高级聚合、跨层桥接 +Tier 7 ├────────────────────────────────────────┤ + │ workflow/ (model/parser/validator/ │ ← Workflow 编排引擎 + │ interpolate/scheduler/ │ + │ state/executor) │ +Tier 6 ├────────────────────────────────────────┤ + │ skill_runtime/ (parser/registry/ │ ← Skill 全生命周期 + │ discover/dependency/ │ + │ executor/scoring/ │ + │ publish/clarity_sync) │ +Tier 5 ├────────────────────────────────────────┤ + │ sync/ (policy/tasks/orchestrator) │ ← 同步编排 + │ watch │ ← 文件系统监控 +Tier 4 ├────────────────────────────────────────┤ + │ query, health, oplog_analytics │ ← 查询与报告 + │ search/hybrid │ ← 混合检索 +Tier 3 ├────────────────────────────────────────┤ + │ dependency_graph, symbol_links │ ← 代码分析关联 + │ vault/indexer, vault/backlinks │ ← Vault 索引与链接 +Tier 2 ├────────────────────────────────────────┤ + │ scan, vault/scanner, discovery_engine │ ← 扫描与发现 + │ backup, test_utils │ ← 备份与测试辅助 +Tier 1 ├────────────────────────────────────────┤ + │ registry/ (类型定义 + CRUD impl) │ ← 数据契约中心 + │ vault/{fs_io,frontmatter,wikilink} │ ← Vault 原子操作 + │ semantic_index, embedding, search │ ← 索引原子能力 + │ arxiv │ ← 外部论文 API +Tier 0 ├────────────────────────────────────────┤ + │ core, i18n, config, asyncgit │ ← 类型根与配置根 + │ sync_protocol │ ← 同步协议基础类型 + └────────────────────────────────────────┘ +``` + +--- + +## 二、逐层规划 + +### Tier 0 — 原子基础层 + +**目的**：为整个系统提供**无业务语义**的底层能力，任何改动都不应破坏上层编译。 + +| 模块 | 功能 | 依赖数 | 被依赖数 | +|:---|:---|:---:|:---:| +| `core` | NodeType / Node / Edge 统一实体枚举 | 0 | 中 | +| `i18n` | 静态字符串表（en/zh_cn） | 0 | **高** | +| `config` | 配置结构体：LLM、Embedding、Sync、Daemon | 0 | **高** | +| `asyncgit` | 异步 Git 状态通知通道（crossbeam） | 0 | 中 | +| `sync_protocol` | FileInfo / SyncIndex / scan_directory | 0 | 低 | + +**迭代策略**：极度稳定，变更需全量回归。`i18n` 新增字段需同步所有语言文件。 + +--- + +### Tier 1 — 数据契约与原子能力层 + +**目的**：定义**领域模型**和**可独立工作的原子能力**。registry 是整个系统的"心脏"，所有业务数据最终落盘于此。 + +| 模块/子模块 | 功能 | 依赖 | 被依赖 | +|:---|:---|:---|:---| +| `registry/` | SQLite Schema v17 + CRUD：repos/repo_tags/code_symbols/code_embeddings/code_call_graph/code_symbol_links/oplog/vault_notes/papers/experiments/skills/skill_executions/entities/entity_types/relations/workflows/workflow_executions | Tier 0 (dirs) | **几乎所有上层** | +| `vault/fs_io` | Vault 文件读写原子操作 | 无 | vault/* | +| `vault/frontmatter` | YAML frontmatter 解析 | 无 | vault/scanner, skill_sync | +| `vault/wikilink` | `[[wikilink]]` 提取 | 无 | vault/scanner | +| `semantic_index` | tree-sitter 多语言符号提取（Rust/Python/TS/Go） | 无 | scan, mcp tools, search/hybrid | +| `embedding` | cosine_similarity、BLOB 序列化、query embedding 生成 | 无 | search/hybrid, mcp tools | +| `search` | Tantivy 索引初始化（id/title/content/tags/doc_type） | 无 | vault/indexer, search/hybrid, mcp tools | +| `arxiv` | arXiv API 元数据抓取 | 无 | mcp tools | + +**关键决策**：registry 的 Schema 变更是**全局阻塞点**。任何新增表/字段必须： +1. 更新 `registry/migrate.rs` 的 `PRAGMA user_version` +2. 触发 `backup::auto_backup_before_migration()` +3. 同步修改 `oplog_analytics.rs` 的表存在性检查 + +--- + +### Tier 2 — 扫描与发现层 + +**目的**：将**无结构的外部世界**（文件系统、Git 仓库）转化为 registry 中的结构化数据。 + +| 模块 | 功能 | 上游依赖 | 下游产出 | +|:---|:---|:---|:---| +| `scan` | Git 仓库发现、语言检测、代码统计（tokei）、blake3 快照、自动注册 | registry, config | registry 各表 | +| `vault/scanner` | Vault 目录遍历、frontmatter/wikilink 提取、注册到 vault_notes | registry, vault/* | registry.vault_notes | +| `discovery_engine` | 跨仓库 Cargo.toml 依赖关联发现 | registry::RepoEntry | registry（待扩展） | +| `backup` | Schema 迁移前自动快照（保留 10 个） | registry | registry（文件系统） | +| `test_utils` | 测试辅助：临时 registry、mock repo | registry | 测试代码 | + +**迭代策略**：scan 是数据入口，新增语言支持或检测规则在此层实验，不影响查询层。 + +--- + +### Tier 3 — 分析与关联层 + +**目的**：在已结构化数据上建立**语义关联**，为查询层提供"图"能力。 + +| 模块 | 功能 | 输入数据 | 产出 | +|:---|:---|:---|:---| +| `dependency_graph` | 跨仓库依赖图构建 | scan 发现的 Cargo.toml/package.json | 图结构（待深化） | +| `symbol_links` | Jaccard 签名相似度 + 同文件聚类 → code_symbol_links | registry.code_symbols | registry.code_symbol_links | +| `vault/indexer` | Vault 笔记入 Tantivy 全文索引 | vault_notes, search | Tantivy 索引文档 | +| `vault/backlinks` | Vault 反向链接图谱 | vault_notes.outgoing_links | 关联查询结果 | + +**迭代策略**：symbol_links 的阈值（默认 0.3）和算法可在此层独立调优，不破坏下游 API。 + +--- + +### Tier 4 — 查询与报告层 + +**目的**：为上层（MCP/TUI）提供**只读查询接口**，是"知识库"的对外窗口。 + +| 模块 | 功能 | 依赖 | +|:---|:---|:---| +| `query` | 结构化表达式解析：`lang:rust stale:>30 behind:>10 tag:x` | registry | +| `health` | dirty/ahead/behind/diverged 计算、workspace 快照哈希 | registry, git2 | +| `oplog_analytics` | 知识覆盖报告：symbol/embedding/call 覆盖率、健康汇总、最近活动 | registry（多表聚合） | +| `search/hybrid` | RRF 归并：向量语义搜索 + Tantivy BM25 关键词 + 自动降级 | semantic_index, search, embedding | + +**关键约束**：查询层必须保持**向后兼容**。MCP tool schema 的 breaking change 只能通过新增 tool（如 `_v2`）而非修改现有 tool。 + +--- + +### Tier 5 — 同步编排层 + +**目的**：将 registry 中的**期望状态**（upstream_url、tags、policy）与文件系统的**实际状态**对齐。 + +| 模块 | 功能 | 依赖关系 | +|:---|:---|:---| +| `sync/policy` | SyncPolicy / SyncMode / RepoSyncTask 定义、错误分类 | 独立（git2） | +| `sync/tasks` | 单仓库 fetch/pull/rebase/merge 执行、OpLog 写入 | registry::WorkspaceRegistry, policy | +| `sync/orchestrator` | 并发信号量控制、批量执行、超时处理、进度回调 | policy, tasks | +| `watch` | notify 文件系统监控、事件聚合 | sync_protocol | + +**迭代策略**：sync 是**危险操作层**。新增 sync 策略（如 `SyncPolicy::StashThenRebase`）需先在 policy 层定义，再在 tasks 层实现，最后由 orchestrator 编排。 + +--- + +### Tier 6 — Skill Runtime 层 + +**目的**：实现 Skill 的**全生命周期管理**，是阶段二的核心交付物。 + +| 子模块 | 功能 | 依赖 | +|:---|:---|:---| +| `parser` | SKILL.md YAML frontmatter → SkillMeta | 独立 | +| `registry` | skills/skill_executions 表 CRUD、skill 安装/卸载 | registry::WorkspaceRegistry | +| `discover` | 项目类型检测（Rust/Node/Python/Go/Docker/Generic）→ SKILL.md 自动生成 + entry_script 包装 | parser | +| `dependency` | Skill 依赖图拓扑排序（Kahn）、DFS 环检测 | skill_runtime::registry | +| `executor` | Process-based 执行、interpreter 自动探测、timeout、stdout/stderr 捕获 | skill_runtime types | +| `scoring` | success_rate / usage_count / rating 计算（0–5 分公式） | registry + skill_runtime::registry | +| `publish` | validate → git tag → push remote | git2 + registry | +| `clarity_sync` | Skill 导出为 Clarity plan JSON | registry + skill_runtime types | + +**依赖关系**： +```text +parser → discover +registry → dependency → executor +registry + executor → scoring +``` + +--- + +### Tier 7 — Workflow 引擎层 + +**目的**：将多个 Skill/子工作流编排为**可复用的自动化流程**。 + +| 子模块 | 功能 | 依赖 | +|:---|:---|:---| +| `model` | WorkflowDefinition / StepDefinition / StepType / ErrorPolicy | 独立 | +| `parser` | YAML → model（untagged 反序列化） | model | +| `validator` | 步骤 ID 唯一性、依赖存在性检查 | model | +| `interpolate` | `${inputs.x}` / `${steps.y.outputs.z}` 变量插值 | 独立 | +| `scheduler` | Kahn 拓扑排序 → ExecutionBatch（可并行步骤组） | model | +| `state` | workflow_executions 表 CRUD、状态机转换 | model + registry | +| `executor` | batch 并行执行（`std::thread::scope`）、错误策略（Fail/Continue/Retry/Fallback）、子工作流递归 | scheduler + model + skill_runtime::executor + registry | + +**依赖关系**： +```text +model ← parser / validator / scheduler +scheduler → executor +skill_runtime::executor → executor +``` + +--- + +### Tier 8 — 高级聚合与跨层桥接 + +**目的**：连接原本正交的子系统，产生**涌现能力**。 + +| 模块 | 功能 | 跨层连接 | +|:---|:---|:---| +| `knowledge_engine` | block_on_async 安全封装、README 摘要提取、模块信息探测 | registry ↔ 外部进程 | +| `skill_sync` | Vault 笔记（ai_context=true）→ Clarity SKILL.md 格式导出 | vault ↔ skill_runtime | +| `vault/mod` | Vault 子系统统一出口 | 聚合 vault/* | + +--- + +### Tier 9 — MCP 协议层 + +**目的**：将所有下层能力**封装为标准协议接口**，供 Clarity 等 AI Agent 调用。 + +| 子模块 | 对应 Tools | 依赖的下层模块 | +|:---|:---|:---| +| `tools/repo` | scan, health, sync, query_repos | scan, health, sync, query | +| `tools/query` | query, index, code_metrics, module_graph | query, scan, semantic_index | +| `tools/vault` | vault_search, vault_read, vault_write, vault_backlinks | vault/*, search | +| `tools/skill` | skill_list, skill_search, skill_run, skill_top | skill_runtime/* | +| `tools/context` | project_context, natural_language_query, hybrid_search, cross_repo_search, related_symbols, knowledge_report, embedding_store, embedding_search | search/hybrid, embedding, oplog_analytics, query | +| `mcp/mod` | 框架：McpTool trait、invoke_stream、ToolStreamEvent | 聚合上述所有 tools | + +**关键契约**： +- 所有状态变更操作必须**幂等**（`ON CONFLICT ... DO UPDATE/NOTHING`） +- 所有批量操作包裹在 SQLite transaction 中 +- Breaking change 通过新增 tool 实现，不修改现有 tool schema + +--- + +### Tier 10 — TUI 交互层 + +**目的**：为人类开发者提供**终端仪表盘**。 + +| 子模块 | 功能 | 依赖 | +|:---|:---|:---| +| `theme` | Design Token（primary/secondary/error 等色彩语义） | 独立 | +| `layout` | 响应式布局计算（35/65 分栏、compact 模式、居中弹窗） | 独立 | +| `state` | App 状态机：仓库列表、Skill 面板、Workflow 弹窗、NLQ 输入、同步进度 | asyncgit, registry, sync::SyncOrchestrator, config | +| `event` | 键盘事件路由、异步通知消费（AsyncNotification） | state, render::ui | +| `render/detail` | 右侧详情页（Overview/Health/Insights） | state, theme, layout | +| `render/list` | 左侧仓库列表（状态图标、排序、过滤） | state, theme, layout | +| `render/popups` | 搜索/同步/Skill/Workflow/NLQ 弹窗 | state, theme, layout | +| `render/help` | 快捷键帮助覆盖层 | state, theme, layout | +| `render/logs` | 底部日志面板 | state, theme, layout | + +**迭代策略**：TUI 是纯消费者层，新增面板（如 `render/loop_step.rs`）不改动任何下层逻辑。 + +--- + +### Tier 11 — 系统入口 + +| 模块 | 功能 | 依赖 | +|:---|:---|:---| +| `main.rs` | CLI 子命令解析（clap）、模块路由 | **所有上层** | +| `daemon.rs` | 定时 tick：stale repo health check、自动 sync | config, health, sync | + +--- + +## 三、枢纽分析 + +### 高扇入模块（改动影响大，需谨慎） + +| 模块 | 扇入来源 | 风险等级 | +|:---|:---|:---:| +| `registry::WorkspaceRegistry` | scan, health, backup, query, oplog_analytics, sync, skill_runtime, workflow, vault, mcp tools, tui | 🔴 | +| `i18n` | sync, digest, tui/render/* | 🟡 | +| `config` | scan, tui/state, sync, daemon | 🟡 | +| `skill_runtime::executor` | workflow/executor, mcp tools, tui | 🟡 | + +### 叶节点模块（可独立迭代，影响面小） + +| 模块 | 说明 | 实验优先级 | +|:---|:---|:---:| +| `arxiv` | 仅被 1 个 MCP tool 使用 | ⭐⭐⭐ | +| `semantic_index` | 仅被 scan 和 search/hybrid 使用，接口稳定 | ⭐⭐⭐ | +| `embedding` | 纯函数工具包，无副作用 | ⭐⭐⭐ | +| `vault/wikilink` | 解析规则可独立调优 | ⭐⭐ | +| `workflow/model` | 模型字段扩展不影响下层 | ⭐⭐ | + +--- + +## 四、基于依赖的迭代策略 + +### 1. 根节点加固（Tier 0–1） +- **registry Schema** 的任何变更需经过：migration 脚本 → 备份逻辑 → oplog_analytics 表存在性检查 → MCP tool schema 兼容性审查 +- **i18n** 新增字段需全语言覆盖，否则 TUI 会出现空字符串 + +### 2. 数据管道扩展（Tier 2–3） +- 新增语言支持（如 `tree-sitter-zig`）：在 `semantic_index` 扩展 → `scan` 触发索引 → `symbol_links` 自动关联 → `search/hybrid` 无需改动即可搜索 +- 新增 Vault 笔记格式：在 `vault/frontmatter` 或 `vault/wikilink` 实验 → `vault/scanner` 消费 → `vault/indexer` 入 Tantivy + +### 3. 查询能力叠加（Tier 4） +- `search/hybrid` 的 RRF 权重、Tantivy 与 embedding 的融合策略可独立调优 +- `oplog_analytics` 的新报表类型只需读取 registry，不改动写入路径 + +### 4. 编排能力实验（Tier 5–7） +- **Skill Runtime** 和 **Workflow** 是相对独立的"应用层"，可并行开发 +- Workflow 的 `StepType::Loop` 新增：只需在 `workflow/model` 加枚举 → `workflow/parser` 反序列化 → `workflow/executor` 实现循环逻辑 → 不影响 Skill Runtime + +### 5. 协议与界面适配（Tier 9–10） +- 新增 MCP tool：在对应 `tools/*` 子模块实现，注册到 `mcp/mod.rs` 的 `McpToolEnum`，零改动下层业务逻辑 +- 新增 TUI 面板：在 `render/` 新增子模块，由 `event.rs` 路由按键，零改动下层 + +--- + +## 五、与排期路线的对比 + +| 排期路线（时间线） | 拓扑路线（依赖线） | 差异说明 | +|:---|:---|:---| +| Wave 1–15b：数据层与索引 | Tier 0 → Tier 1 → Tier 2 → Tier 3 | 一致 | +| Wave 16–21：Skill Runtime | Tier 6（parser → registry → discover → dependency → executor → scoring） | 拓扑更细粒度展示子模块依赖 | +| Wave 22–25：Workflow Engine | Tier 7（model → parser → scheduler → executor） | 明确 Workflow 依赖 Skill Runtime executor | +| Wave 26–27：NLQ + Mind Market | Tier 4（search/hybrid）+ Tier 6（scoring） | NLQ 是查询层增强，Mind Market 是 Skill 层增强，二者**无依赖关系**，可并行 | +| Wave 28–33：风险修复与硬化 | 跨 Tier（unwrap 清零涉及 Tier 6–7） | 质量工作横向穿透所有层 | +| Future：L0–L4 知识模型 | 可能新增 Tier 3.5（知识图谱层）或扩展 Tier 1 Schema | 需先定义模型与 registry 的映射 | +| Future：跨设备同步 | Tier 5（sync）+ Tier 11（daemon）扩展 | 依赖 syncthing-rust 的 REST API | + +--- + +*本文档作为架构决策参考，应与 `overview.md` 和 `AGENTS.md` 同步维护。* diff --git a/docs/architecture/invariants.md b/docs/_archive/invariants.md similarity index 88% rename from docs/architecture/invariants.md rename to docs/_archive/invariants.md index 6803f9c..a97393b 100644 --- a/docs/architecture/invariants.md +++ b/docs/_archive/invariants.md @@ -1,75 +1,77 @@ -# 架构不变量清单（Invariants） - -> 来源：架构治理方法论参考（Kimi 会话 `e9f2965f-b949-46a5-9d7c-afd6d4d9232c`） -> 原则：不可打破的规则列表，每次代码审查对照检查。 - ---- - -## 全局不变量 - -| # | 规则 | 违反后果 | 检测方式 | -|---|------|---------|---------| -| G1 | `registry::WorkspaceRegistry` 不得依赖任何 Tier 4+ 模块 | 数据层被查询层污染，Schema 变更引发级联修改 | `cargo check` + 依赖拓扑审查 | -| G2 | `i18n` / `config` 不得包含业务逻辑 | 基础配置层膨胀，语言文件与业务耦合 | 代码审查：只含静态字符串和结构体定义 | -| G3 | 所有状态变更 MCP tool 必须幂等 | 重复调用导致数据损坏 | 单元测试：同一参数调用两次结果一致 | -| G4 | Breaking change 只能通过新增 tool 实现，不修改现有 schema | 下游 Agent 契约破裂 | Schema 版本对比 + MCP tool 清单审计 | -| G5 | 生产代码不得新增 `unwrap()` / `expect()`（RF-6） | 运行时 panic | `cargo clippy` + 人工审查 | - -## 分层不变量 - -### Tier 0–1（原子基础层） - -| # | 规则 | 说明 | -|---|------|------| -| T01 | `core` 只定义无业务语义的枚举和结构体 | NodeType / Node / Edge 不得出现 devbase 专属逻辑 | -| T02 | `registry` Schema 变更必须经过三步：migration → 备份 → oplog_analytics 兼容性检查 | 见 `dependency-topology.md` §二、Tier 1 | -| T03 | `embedding` 必须是纯函数工具包，无副作用 | 禁止在 encode 中写文件、改全局状态 | - -### Tier 2–3（扫描与分析层） - -| # | 规则 | 说明 | -|---|------|------| -| T04 | `scan` 新增语言支持不得改动 `semantic_index` 公共 API | 语言检测规则可独立实验 | -| T05 | `symbol_links` 的阈值和算法可独立调优，不破坏下游 | Jaccard 阈值默认 0.3，可调 | - -### Tier 4（查询层） - -| # | 规则 | 说明 | -|---|------|------| -| T06 | `query` 表达式解析必须向后兼容 | `lang:rust` 语法不得删除，只能扩展 | -| T07 | `search/hybrid` RRF 权重可独立调优，不影响工具 schema | 向量/BM25 融合策略是内部实现细节 | - -### Tier 5（同步层） - -| # | 规则 | 说明 | -|---|------|------| -| T08 | 新增 sync 策略必须先定义于 `sync/policy`，再实现于 `sync/tasks` | 禁止直接在 orchestrator 中硬编码策略逻辑 | - -### Tier 6–7（Skill / Workflow 层） - -| # | 规则 | 说明 | -|---|------|------| -| T09 | `skill_runtime::executor` 必须自包含副作用描述 | 每个 Skill 的 entry_script 必须声明读写范围 | -| T10 | Workflow 新增 `StepType` 只需改动 `workflow/model` → `parser` → `executor`，不影响 Skill Runtime | 见 `dependency-topology.md` §二、Tier 7 | - -### Tier 9–10（MCP / TUI 层） - -| # | 规则 | 说明 | -|---|------|------| -| T11 | `mcp/tools/*` 不得直接调用 `rusqlite::Connection`，必须通过 `registry` 封装 | 防止 SQL 注入和 Schema 漂移 | -| T12 | `tui/render/*` 是纯消费者层，新增面板不改动任何下层逻辑 | TUI 状态机只读取，不写入 registry | - -## 模块提取演习检查表 - -> 每季度执行一次。任何模块若无法在半天内提取为独立包并写出 50 字 README，说明耦合过重。 - -| 模块 | 上次检查 | 能否提取 | README 50 字验证 | -|------|---------|---------|-----------------| -| `devbase-embedding` | 2026-04 | ✅ 已提取 | 本地 BERT embedding 生成，零外部依赖 | -| `devbase-registry-health` | 2026-04 | ✅ 已提取 | 批量健康查询，消除 N+1 | -| `skill_runtime` | 2026-04 | ⚠️ 待验证 | parser/registry/executor 边界清晰，但 clarity_sync 耦合待审 | -| `workflow` | 2026-04 | ⚠️ 待验证 | model/parser/scheduler 可拆，executor 依赖 skill_runtime::executor | - ---- - -*违反任何不变量 → 必须在 ADR 中记录例外理由，否则回滚。* +> **⚠️ 文档迁移提示**：本文件为历史不变量清单。最新、已维护的架构红线与不变量已按 OKF（Open Knowledge Format）整理至 `.knowledge/architecture/invariants.md`，采用全局不变量 G1–G7 + 分层不变量 T01–T12 体系。本文件保留历史上下文，但规则编号、范围与检测方式可能已过时。最新数据：v0.20.1 / Schema v36 / 71 MCP tools / 12 workspace crates。 + +# 架构不变量清单（Invariants） + +> 来源：架构治理方法论参考（Kimi 会话 `e9f2965f-b949-46a5-9d7c-afd6d4d9232c`） +> 原则：不可打破的规则列表，每次代码审查对照检查。 + +--- + +## 全局不变量 + +| # | 规则 | 违反后果 | 检测方式 | +|---|------|---------|---------| +| G1 | `registry::WorkspaceRegistry` 不得依赖任何 Tier 4+ 模块 | 数据层被查询层污染，Schema 变更引发级联修改 | `cargo check` + 依赖拓扑审查 | +| G2 | `i18n` / `config` 不得包含业务逻辑 | 基础配置层膨胀，语言文件与业务耦合 | 代码审查：只含静态字符串和结构体定义 | +| G3 | 所有状态变更 MCP tool 必须幂等 | 重复调用导致数据损坏 | 单元测试：同一参数调用两次结果一致 | +| G4 | Breaking change 只能通过新增 tool 实现，不修改现有 schema | 下游 Agent 契约破裂 | Schema 版本对比 + MCP tool 清单审计 | +| G5 | 生产代码不得新增 `unwrap()` / `expect()`（RF-6） | 运行时 panic | `cargo clippy` + 人工审查 | + +## 分层不变量 + +### Tier 0–1（原子基础层） + +| # | 规则 | 说明 | +|---|------|------| +| T01 | `core` 只定义无业务语义的枚举和结构体 | NodeType / Node / Edge 不得出现 devbase 专属逻辑 | +| T02 | `registry` Schema 变更必须经过三步：migration → 备份 → oplog_analytics 兼容性检查 | 见 `dependency-topology.md` §二、Tier 1 | +| T03 | `embedding` 必须是纯函数工具包，无副作用 | 禁止在 encode 中写文件、改全局状态 | + +### Tier 2–3（扫描与分析层） + +| # | 规则 | 说明 | +|---|------|------| +| T04 | `scan` 新增语言支持不得改动 `semantic_index` 公共 API | 语言检测规则可独立实验 | +| T05 | `symbol_links` 的阈值和算法可独立调优，不破坏下游 | Jaccard 阈值默认 0.3，可调 | + +### Tier 4（查询层） + +| # | 规则 | 说明 | +|---|------|------| +| T06 | `query` 表达式解析必须向后兼容 | `lang:rust` 语法不得删除，只能扩展 | +| T07 | `search/hybrid` RRF 权重可独立调优，不影响工具 schema | 向量/BM25 融合策略是内部实现细节 | + +### Tier 5（同步层） + +| # | 规则 | 说明 | +|---|------|------| +| T08 | 新增 sync 策略必须先定义于 `sync/policy`，再实现于 `sync/tasks` | 禁止直接在 orchestrator 中硬编码策略逻辑 | + +### Tier 6–7（Skill / Workflow 层） + +| # | 规则 | 说明 | +|---|------|------| +| T09 | `skill_runtime::executor` 必须自包含副作用描述 | 每个 Skill 的 entry_script 必须声明读写范围 | +| T10 | Workflow 新增 `StepType` 只需改动 `workflow/model` → `parser` → `executor`，不影响 Skill Runtime | 见 `dependency-topology.md` §二、Tier 7 | + +### Tier 9–10（MCP / TUI 层） + +| # | 规则 | 说明 | +|---|------|------| +| T11 | `mcp/tools/*` 不得直接调用 `rusqlite::Connection`，必须通过 `registry` 封装 | 防止 SQL 注入和 Schema 漂移 | +| T12 | `tui/render/*` 是纯消费者层，新增面板不改动任何下层逻辑 | TUI 状态机只读取，不写入 registry | + +## 模块提取演习检查表 + +> 每季度执行一次。任何模块若无法在半天内提取为独立包并写出 50 字 README，说明耦合过重。 + +| 模块 | 上次检查 | 能否提取 | README 50 字验证 | +|------|---------|---------|-----------------| +| `devbase-embedding` | 2026-04 | ✅ 已提取 | 本地 BERT embedding 生成，零外部依赖 | +| `devbase-registry-health` | 2026-04 | ✅ 已提取 | 批量健康查询，消除 N+1 | +| `skill_runtime` | 2026-04 | ⚠️ 待验证 | parser/registry/executor 边界清晰，但 clarity_sync 耦合待审 | +| `workflow` | 2026-04 | ⚠️ 待验证 | model/parser/scheduler 可拆，executor 依赖 skill_runtime::executor | + +--- + +*违反任何不变量 → 必须在 ADR 中记录例外理由，否则回滚。* diff --git a/docs/architecture/overview.md b/docs/_archive/overview.md similarity index 94% rename from docs/architecture/overview.md rename to docs/_archive/overview.md index 9349a11..fda8034 100644 --- a/docs/architecture/overview.md +++ b/docs/_archive/overview.md @@ -1,254 +1,261 @@ -# devbase 架构讨论与技术决策记录 - -> 本文件记录了 devbase 项目从概念诞生到 MVP 实现过程中的关键技术讨论与架构决策。 -> -> **当前版本**：2026-04-17（Sprint 1 完成，Sprint 2 规划中） - ---- - -## 一、项目缘起：从桌面 ZIP 灾难到知识库管理 - -### 1.1 原始问题 - -用户桌面上有约 20+ 个项目文件夹（`openclaw-main`、`lazygit-master`、`ollama-main` 等），它们全部是 **GitHub ZIP 下载包**（文件夹名带 `-main`/`-master` 后缀）。这导致： - -- ❌ 无法 `git pull` 获取上游更新 -- ❌ 无法查看提交历史、对比变更 -- ❌ 无法追踪自己的本地修改 -- ❌ 长期管理沦为"僵尸代码" - -### 1.2 核心洞察 - -> "把源码从桌面移到统一目录"只是表面动作；更深层的价值在于，**开发者的本地环境本身就是一个未被结构化的数据库**。把这个数据库管好，让它可被查询、可被保鲜、可被策略化地同步，这就是一个**面向开发者的知识管理框架**。 - ---- - -## 二、三层架构模型：字节 → 语义 → 行动 - -### 2.1 模型总览 - -```text -┌─────────────────────────────────────────────────────────────┐ -│ 应用层（Application / Protocol Layer） │ -│ ───────────────────────────────────── │ -│ • MCP 工具（devkit_scan, devkit_sync, devkit_query） │ -│ • Agent Skill（Clarity 的 reasoning + action 接口） │ -│ • CLI / TUI（devbase scan, sync, health） │ -├─────────────────────────────────────────────────────────────┤ -│ 抽象层（Semantic / Knowledge Layer） │ -│ ───────────────────────────────────── │ -│ • Registry（仓库节点、标签、依赖关系） │ -│ • 知识图谱（项目 A 参考项目 B，语言 Rust，策略 fetch-only）│ -│ • 健康状态抽象（dirty、stale: 30d、behind: 12） │ -│ • 同步策略（what should be synced, when, how） │ -├─────────────────────────────────────────────────────────────┤ -│ 实体层（Physical / Storage Layer） │ -│ ───────────────────────────────────── │ -│ • 文件系统（NTFS / ext4 / APFS） │ -│ - Git 对象数据库（.git/objects/） │ -│ - 源码文件树（src/, Cargo.toml） │ -│ • 本地数据库（SQLite：devbase registry.db） │ -│ • Syncthing 的块索引与本地版本向量 │ -└─────────────────────────────────────────────────────────────┘ -``` - -### 2.2 转化点 1：实体层 → 抽象层 - -`devbase scan` 把无结构的文件系统转化为有语义的知识库： - -| 实体层原始信号 | 抽象层提取结果 | -|---------------|---------------| -| `lazygit-master/.git/config` | `RepoEntry { upstream: "github.com/jesseduffield/lazygit", tags: "third-party,reference" }` | -| `cargo build` 失败 | `HealthReport { rustc: "1.94.1", status: "编译失败" }` | -| 目录名带 `-main`/`-master` | `RepoEntry { source_type: "zip-snapshot", needs_migration: true }` | -| `.gitmodules` 存在 | `DependencyEdge { from: "openclaw", to: "submodule-x", type: "git-submodule" }` | -| `SOUL.md` / `.devbase` 标记 | `RepoEntry { workspace_type: "openclaw" | "generic", data_tier: "private" }` | - -### 2.3 转化点 2：抽象层 → 应用层 - -通过 MCP（Model Context Protocol）接口，`devbase` 成为 Clarity Agent 的"环境感知器官"。LLM 不再"盲人摸象"，而是能直接查询： - -- "用户本地有哪些 Rust 项目？" -- "系统 CMake 版本是多少？" -- "哪些第三方库超过 30 天未同步？" -- "我的农业知识库中水稻病害的最新记录是什么？" - ---- - -## 三、关键架构决策 - -### 3.1 Git vs Syncthing 的粒度差异 - -| 维度 | **Git** | **Syncthing** | -|------|---------|---------------| -| **基本单位** | 整个文件（Blob） | 固定大小的块（Block，~128KB） | -| **核心目的** | 保存完整历史与版本树 | 最小化网络同步流量 | -| **主要维度** | **时间**（历史） | **空间**（分布） | -| **核心问题** | "这个文件**过去**长什么样？" | "这个文件在**另一台机器**上长什么样？" | -| **环境假设** | 数据量小、本地磁盘充足、完整性优先 | 数据量大、带宽昂贵、网络不可靠 | -| **去重粒度** | 文件级 | 块级 | -| **历史语义** | 强（Commit → Tree → Blob 的不可变快照） | 弱（只关心当前一致性） | - -### 3.2 数据主权（Memory Sovereignty） - -Registry Schema v2 引入了三层数据分级： - -- `private`：默认状态。原始对话、私有代码、个人笔记。不同步到任何外部节点。 -- `cooperative`：经授权后可参与模式聚合。例如去标识化的工具调用序列、农业诊断案例统计。 -- `public`：完全开放的知识。例如开源文档、去标识化的通用百科。 - -CLI 已支持通过 `devbase meta --tier ` 动态调整分级。 - ---- - -## 四、与 Clarity / syncthing-rust-rearch 的协同定位 - -### 4.1 三个项目的独立价值 - -| 项目 | 核心事务 | 占据的层次 | -|------|---------|-----------| -| **syncthing-rust-rearch** | 解决"数据怎么在机器之间搬运" | 实体层 + 部分抽象层 | -| **devbase** | 解决"搬运的数据有什么语义、值不值得更新" | 抽象层 + 部分应用层 | -| **Clarity** | 解决"Agent 如何基于这些语义做出决策并执行" | 应用层 | - -### 4.2 垂直协同关系 - -```text -Clarity (应用层) - │ - │ 调用 MCP Tool: devkit_sync / devkit_agri_query - ▼ -devbase (抽象层) - │ - │ 查询 Registry / 生成 SyncPlan / 农业知识图谱 - ▼ -syncthing-rust-rearch (实体层) - │ - │ 决定哪些目录需要被块级同步到远端 - ▼ -Peer Device (另一台机器的实体层) -``` - -### 4.3 当前阶段声明（2026-04-17） - -> **三者已通过 MCP 协议完成初步融合。** -> -> - `devbase`：Sprint 1 完成 CLI/TUI/Registry/OpLog，Registry 规模 39 个工作区；MCP 仅 stdio，SSE 开发中 -> - `Clarity`：通过 MCP stdio 调用 devbase 工具，SSE transport 待 Daemon 常驻模式 -> - `syncthing-rust-rearch`：BEP 协议栈就绪，`.syncdone` 标记格式已对齐，REST API 集成待 Sprint 2 -> -> 成熟期通过明确的层间协议（MCP / REST / 配置契约 / `.syncdone` 文件标记）进行对接，避免过早耦合。 - ---- - -## 五、Registry Schema 演进 - -| 版本 | 日期 | 变更 | -|------|------|------| -| v1 | 初始 | `repos` 表含 `upstream_url`（扁平） | -| v2 | 2026-04-15 | 新增 `workspace_type`、`data_tier`、`last_synced_at`；`repo_tags`/`repo_remotes` 规范化 | -| v3 | 2026-04-15 | 新增 `workspace_snapshots` 表（非 Git 工作区 blake3 快照） | -| v4 | 2026-04-17 | 新增 `oplog` 表（操作日志）；迁移前自动备份 | - ---- - -## 六、三仓库架构视角（横向分层） - -> 本文档的"二、三层架构模型"是**纵向分层**（物理 → 语义 → 应用）。 -> 与之互补的是**横向分层**：把 AI 基础设施拆分为三个正交的"仓库"——代码仓库、Skill 仓库、MCP 仓库。 -> -> 详见独立文档：[`docs/theory/three-repositories.md`](./theory/three-repositories.md) - -### 6.1 为什么需要横向分层 - -纵向分层回答的是"数据在系统中如何流转"；横向分层回答的是"能力在生态中如何被复用"。 - -| 纵向层 | 横向仓库 | 核心问题 | -|--------|---------|---------| -| 实体层 | **GitHub 仓库** | 代码资产存在哪里？ | -| 抽象层 | **Skill 仓库** | AI 能做什么？怎么做？ | -| 应用层 | **MCP 仓库** | AI 通过什么协议调用能力？ | - -### 6.2 devbase 横跨三层 - -devbase 的当前模块已经天然分布在三仓库中： - -- **Layer 1（GitHub 仓库）**：`registry` 模块管理代码资产的元数据、符号、调用图 -- **Layer 2（Skill 仓库）**：`vault/` + `skill-sync-prototype` 探索 Vault → Skill 同步 -- **Layer 3（MCP 仓库）**：`src/mcp/` 实现 31 个 MCP tools，作为协议适配器 - -三仓库之间的**正交性**意味着：改变 Skill 的业务逻辑不应影响 MCP 的协议格式，替换 GitHub 数据源不应破坏 Skill 的执行语义。 - ---- - -## 七、当前实现状态（2026-04-17） - -### 6.1 CLI 功能清单 - -| 命令 | 状态 | 说明 | -|------|------|------| -| `devbase scan --register` | ✅ 已实现 | Git + 非 Git（`SOUL.md`/`.devbase`）工作区；语言自动检测；ZIP 快照标记 | -| `devbase health --detail` | ✅ 已实现 | Git: dirty/ahead/behind；非 Git: blake3 快照变更检测 | -| `devbase sync --strategy=auto-pull` | ✅ 已实现 | Safe Sync 预检：dirty/diverged/protected 自动跳过；并发编排；可配置超时 | -| `devbase sync --dry-run` | ✅ 已实现 | 只预览不执行 | -| `devbase query ` | ✅ 已实现 | `lang:rust`、`stale:>30`、`behind:>10`、`tag:third-party` | -| `devbase tag ` | ✅ 已实现 | 分类标签；支持 `agri:crop:rice` 分层命名空间 | -| `devbase meta --tier ` | ✅ 已实现 | `workspace_type` / `data_tier` 动态更新 | -| `devbase tui` | ✅ 已实现 | ratatui 异步事件循环；Safe Sync Preview 弹窗；commit 对比；标签聚类 | -| `devbase mcp --transport stdio` | ✅ 已实现 | 10 个 MCP 工具 | -| `devbase mcp --transport sse --port` | ✅ 已实现 | Axum SSE Server；端到端验证通过 | -| `devbase registry export/import/backups` | ✅ 已实现 | SQLite + JSON 双格式；自动保留 10 个快照 | -| `devbase oplog --limit N` | ✅ 已实现 | scan/sync/health 自动记录；按 repo 过滤 | -| `devbase watch --duration` | ✅ 已实现 | 目录监控 + 事件聚合 + 变更调度 | -| `devbase clean` | ✅ 已实现 | 清理备份目录记录 | - -### 6.2 测试状态 - -``` -42 passed / 0 failed / 2 ignored -``` - -### 6.3 Registry 规模 - -**总计 39 个工作区**： -- **自有项目（4 个）**：`clarity`、`syncthing-rust-rearch`、`devbase`、`agri-paper` -- **第三方参考库（35 个）**：包括 `gws`（Google Workspace CLI）、`5ire`（MCP Client）、`workspace-tools`（changeset 管理）等竞品 - ---- - -## 八、后续规划 - -### Sprint 2（Phase 2，2026-04-18 ~ 2026-05-01） - -| 周 | 任务 | 产出 | 阻塞依赖 | -|----|------|------|---------| -| W1 | `McpTool::invoke_stream()` trait 扩展 | 支持 `progress` → `partial` → `done` 三段式 event | 无 | -| W1 | `agri_observations` schema migration | 农业领域表 + `devkit_agri_query` MCP tool | **等 agri-paper DDL PR** | -| W2 | SSE handler 流式适配 | `messages_handler` 支持分段推送；stdio 向后兼容 | W1 完成 | -| W2 | CLI/TUI pagination | `--limit` / `--page` 参数 | 无 | -| W3–W4 | `devkit_health`/`devkit_query` 流式集成 | TUI 进度条；Agent 不再阻塞 2–5s | W2 完成 | -| W5–W8 | Daemon 内置 SSE Server + clarity 长连接 | `devbase daemon` 常驻运行 MCP SSE；clarity URL 配置 | clarity-core MCP Client SSE 配置 | - -### Sprint 3（Phase 2 后半，2026-05-01 ~ 2026-05-15） - -1. **`devbase-core` crate 剥离**：将 Registry/HealthEngine/SyncOrchestrator/QueryEngine 抽象为可复用库，解除 `clarity-core` path dependency -2. **`.syncdone` 文件标记落地**：集成 syncthing-rust `FolderStatus::Idle` REST endpoint -3. **农业 Persona TOML 集成**：`PersonalityConfig` 模板变量插值 + `agri_expert.toml` 校验 - -### Phase 3（2026-05-15 ~ 2026-07-15） - -1. **依赖图谱可视化**：项目间引用关系图 -2. **语义检索层**：本地嵌入模型（bge-m3 或 kalosm）替代规则模式 fallback -3. **MCP 协议版本协商**：保持与旧版 Clarity 兼容 - ---- - -## 九、术语表 - -- **Blob**：Git 中文件内容的不可变对象，以内容哈希命名。 -- **Packfile**：Git 的后台存储优化格式，对同一文件的不同版本做 delta 压缩。 -- **MCP**：Model Context Protocol，LLM 与外部工具交互的标准协议。 -- **Registry**：devbase 的核心数据结构，记录所有被管理仓库的元数据。 -- **SyncOrchestrator**：devbase 的同步编排器，负责按标签和策略批量更新仓库。 -- **OpLog**：操作日志，记录 scan/sync/health 等关键操作的审计追踪。 -- **Data Tier**：数据分级（`public`/`cooperative`/`private`），控制同步边界。 +> **⚠️ 文档迁移提示**：本文件为历史架构讨论记录。最新的项目架构、拓扑、不变量已按 OKF（Open Knowledge Format）整理至 `.knowledge/architecture/`。建议 Agent 优先阅读： +> - `.knowledge/architecture/three-layer-model.md` +> - `.knowledge/architecture/dependency-topology.md` +> - `.knowledge/architecture/invariants.md` +> +> 最新数据：v0.20.1 / Schema v36 / 71 MCP tools / 12 workspace crates。 + +# devbase 架构讨论与技术决策记录 + +> 本文件记录了 devbase 项目从概念诞生到 MVP 实现过程中的关键技术讨论与架构决策。 +> +> **当前版本**：2026-04-17（Sprint 1 完成，Sprint 2 规划中） + +--- + +## 一、项目缘起：从桌面 ZIP 灾难到知识库管理 + +### 1.1 原始问题 + +用户桌面上有约 20+ 个项目文件夹（`openclaw-main`、`lazygit-master`、`ollama-main` 等），它们全部是 **GitHub ZIP 下载包**（文件夹名带 `-main`/`-master` 后缀）。这导致： + +- ❌ 无法 `git pull` 获取上游更新 +- ❌ 无法查看提交历史、对比变更 +- ❌ 无法追踪自己的本地修改 +- ❌ 长期管理沦为"僵尸代码" + +### 1.2 核心洞察 + +> "把源码从桌面移到统一目录"只是表面动作；更深层的价值在于，**开发者的本地环境本身就是一个未被结构化的数据库**。把这个数据库管好，让它可被查询、可被保鲜、可被策略化地同步，这就是一个**面向开发者的知识管理框架**。 + +--- + +## 二、三层架构模型：字节 → 语义 → 行动 + +### 2.1 模型总览 + +```text +┌─────────────────────────────────────────────────────────────┐ +│ 应用层（Application / Protocol Layer） │ +│ ───────────────────────────────────── │ +│ • MCP 工具（devkit_scan, devkit_sync, devkit_query） │ +│ • Agent Skill（Clarity 的 reasoning + action 接口） │ +│ • CLI / TUI（devbase scan, sync, health） │ +├─────────────────────────────────────────────────────────────┤ +│ 抽象层（Semantic / Knowledge Layer） │ +│ ───────────────────────────────────── │ +│ • Registry（仓库节点、标签、依赖关系） │ +│ • 知识图谱（项目 A 参考项目 B，语言 Rust，策略 fetch-only）│ +│ • 健康状态抽象（dirty、stale: 30d、behind: 12） │ +│ • 同步策略（what should be synced, when, how） │ +├─────────────────────────────────────────────────────────────┤ +│ 实体层（Physical / Storage Layer） │ +│ ───────────────────────────────────── │ +│ • 文件系统（NTFS / ext4 / APFS） │ +│ - Git 对象数据库（.git/objects/） │ +│ - 源码文件树（src/, Cargo.toml） │ +│ • 本地数据库（SQLite：devbase registry.db） │ +│ • Syncthing 的块索引与本地版本向量 │ +└─────────────────────────────────────────────────────────────┘ +``` + +### 2.2 转化点 1：实体层 → 抽象层 + +`devbase scan` 把无结构的文件系统转化为有语义的知识库： + +| 实体层原始信号 | 抽象层提取结果 | +|---------------|---------------| +| `lazygit-master/.git/config` | `RepoEntry { upstream: "github.com/jesseduffield/lazygit", tags: "third-party,reference" }` | +| `cargo build` 失败 | `HealthReport { rustc: "1.94.1", status: "编译失败" }` | +| 目录名带 `-main`/`-master` | `RepoEntry { source_type: "zip-snapshot", needs_migration: true }` | +| `.gitmodules` 存在 | `DependencyEdge { from: "openclaw", to: "submodule-x", type: "git-submodule" }` | +| `SOUL.md` / `.devbase` 标记 | `RepoEntry { workspace_type: "openclaw" | "generic", data_tier: "private" }` | + +### 2.3 转化点 2：抽象层 → 应用层 + +通过 MCP（Model Context Protocol）接口，`devbase` 成为 Clarity Agent 的"环境感知器官"。LLM 不再"盲人摸象"，而是能直接查询： + +- "用户本地有哪些 Rust 项目？" +- "系统 CMake 版本是多少？" +- "哪些第三方库超过 30 天未同步？" +- "我的农业知识库中水稻病害的最新记录是什么？" + +--- + +## 三、关键架构决策 + +### 3.1 Git vs Syncthing 的粒度差异 + +| 维度 | **Git** | **Syncthing** | +|------|---------|---------------| +| **基本单位** | 整个文件（Blob） | 固定大小的块（Block，~128KB） | +| **核心目的** | 保存完整历史与版本树 | 最小化网络同步流量 | +| **主要维度** | **时间**（历史） | **空间**（分布） | +| **核心问题** | "这个文件**过去**长什么样？" | "这个文件在**另一台机器**上长什么样？" | +| **环境假设** | 数据量小、本地磁盘充足、完整性优先 | 数据量大、带宽昂贵、网络不可靠 | +| **去重粒度** | 文件级 | 块级 | +| **历史语义** | 强（Commit → Tree → Blob 的不可变快照） | 弱（只关心当前一致性） | + +### 3.2 数据主权（Memory Sovereignty） + +Registry Schema v2 引入了三层数据分级： + +- `private`：默认状态。原始对话、私有代码、个人笔记。不同步到任何外部节点。 +- `cooperative`：经授权后可参与模式聚合。例如去标识化的工具调用序列、农业诊断案例统计。 +- `public`：完全开放的知识。例如开源文档、去标识化的通用百科。 + +CLI 已支持通过 `devbase meta --tier ` 动态调整分级。 + +--- + +## 四、与 Clarity / syncthing-rust-rearch 的协同定位 + +### 4.1 三个项目的独立价值 + +| 项目 | 核心事务 | 占据的层次 | +|------|---------|-----------| +| **syncthing-rust-rearch** | 解决"数据怎么在机器之间搬运" | 实体层 + 部分抽象层 | +| **devbase** | 解决"搬运的数据有什么语义、值不值得更新" | 抽象层 + 部分应用层 | +| **Clarity** | 解决"Agent 如何基于这些语义做出决策并执行" | 应用层 | + +### 4.2 垂直协同关系 + +```text +Clarity (应用层) + │ + │ 调用 MCP Tool: devkit_sync / devkit_agri_query + ▼ +devbase (抽象层) + │ + │ 查询 Registry / 生成 SyncPlan / 农业知识图谱 + ▼ +syncthing-rust-rearch (实体层) + │ + │ 决定哪些目录需要被块级同步到远端 + ▼ +Peer Device (另一台机器的实体层) +``` + +### 4.3 当前阶段声明（2026-04-17） + +> **三者已通过 MCP 协议完成初步融合。** +> +> - `devbase`：Sprint 1 完成 CLI/TUI/Registry/OpLog，Registry 规模 39 个工作区；MCP 仅 stdio，SSE 开发中 +> - `Clarity`：通过 MCP stdio 调用 devbase 工具，SSE transport 待 Daemon 常驻模式 +> - `syncthing-rust-rearch`：BEP 协议栈就绪，`.syncdone` 标记格式已对齐，REST API 集成待 Sprint 2 +> +> 成熟期通过明确的层间协议（MCP / REST / 配置契约 / `.syncdone` 文件标记）进行对接，避免过早耦合。 + +--- + +## 五、Registry Schema 演进 + +| 版本 | 日期 | 变更 | +|------|------|------| +| v1 | 初始 | `repos` 表含 `upstream_url`（扁平） | +| v2 | 2026-04-15 | 新增 `workspace_type`、`data_tier`、`last_synced_at`；`repo_tags`/`repo_remotes` 规范化 | +| v3 | 2026-04-15 | 新增 `workspace_snapshots` 表（非 Git 工作区 blake3 快照） | +| v4 | 2026-04-17 | 新增 `oplog` 表（操作日志）；迁移前自动备份 | + +--- + +## 六、三仓库架构视角（横向分层） + +> 本文档的"二、三层架构模型"是**纵向分层**（物理 → 语义 → 应用）。 +> 与之互补的是**横向分层**：把 AI 基础设施拆分为三个正交的"仓库"——代码仓库、Skill 仓库、MCP 仓库。 +> +> 详见独立文档：[`docs/theory/three-repositories.md`](./theory/three-repositories.md) + +### 6.1 为什么需要横向分层 + +纵向分层回答的是"数据在系统中如何流转"；横向分层回答的是"能力在生态中如何被复用"。 + +| 纵向层 | 横向仓库 | 核心问题 | +|--------|---------|---------| +| 实体层 | **GitHub 仓库** | 代码资产存在哪里？ | +| 抽象层 | **Skill 仓库** | AI 能做什么？怎么做？ | +| 应用层 | **MCP 仓库** | AI 通过什么协议调用能力？ | + +### 6.2 devbase 横跨三层 + +devbase 的当前模块已经天然分布在三仓库中： + +- **Layer 1（GitHub 仓库）**：`registry` 模块管理代码资产的元数据、符号、调用图 +- **Layer 2（Skill 仓库）**：`vault/` + `skill-sync-prototype` 探索 Vault → Skill 同步 +- **Layer 3（MCP 仓库）**：`src/mcp/` 实现 31 个 MCP tools，作为协议适配器 + +三仓库之间的**正交性**意味着：改变 Skill 的业务逻辑不应影响 MCP 的协议格式，替换 GitHub 数据源不应破坏 Skill 的执行语义。 + +--- + +## 七、当前实现状态（2026-04-17） + +### 6.1 CLI 功能清单 + +| 命令 | 状态 | 说明 | +|------|------|------| +| `devbase scan --register` | ✅ 已实现 | Git + 非 Git（`SOUL.md`/`.devbase`）工作区；语言自动检测；ZIP 快照标记 | +| `devbase health --detail` | ✅ 已实现 | Git: dirty/ahead/behind；非 Git: blake3 快照变更检测 | +| `devbase sync --strategy=auto-pull` | ✅ 已实现 | Safe Sync 预检：dirty/diverged/protected 自动跳过；并发编排；可配置超时 | +| `devbase sync --dry-run` | ✅ 已实现 | 只预览不执行 | +| `devbase query ` | ✅ 已实现 | `lang:rust`、`stale:>30`、`behind:>10`、`tag:third-party` | +| `devbase tag ` | ✅ 已实现 | 分类标签；支持 `agri:crop:rice` 分层命名空间 | +| `devbase meta --tier ` | ✅ 已实现 | `workspace_type` / `data_tier` 动态更新 | +| `devbase tui` | ✅ 已实现 | ratatui 异步事件循环；Safe Sync Preview 弹窗；commit 对比；标签聚类 | +| `devbase mcp --transport stdio` | ✅ 已实现 | 10 个 MCP 工具 | +| `devbase mcp --transport sse --port` | ✅ 已实现 | Axum SSE Server；端到端验证通过 | +| `devbase registry export/import/backups` | ✅ 已实现 | SQLite + JSON 双格式；自动保留 10 个快照 | +| `devbase oplog --limit N` | ✅ 已实现 | scan/sync/health 自动记录；按 repo 过滤 | +| `devbase watch --duration` | ✅ 已实现 | 目录监控 + 事件聚合 + 变更调度 | +| `devbase clean` | ✅ 已实现 | 清理备份目录记录 | + +### 6.2 测试状态 + +``` +42 passed / 0 failed / 2 ignored +``` + +### 6.3 Registry 规模 + +**总计 39 个工作区**： +- **自有项目（4 个）**：`clarity`、`syncthing-rust-rearch`、`devbase`、`agri-paper` +- **第三方参考库（35 个）**：包括 `gws`（Google Workspace CLI）、`5ire`（MCP Client）、`workspace-tools`（changeset 管理）等竞品 + +--- + +## 八、后续规划 + +### Sprint 2（Phase 2，2026-04-18 ~ 2026-05-01） + +| 周 | 任务 | 产出 | 阻塞依赖 | +|----|------|------|---------| +| W1 | `McpTool::invoke_stream()` trait 扩展 | 支持 `progress` → `partial` → `done` 三段式 event | 无 | +| W1 | `agri_observations` schema migration | 农业领域表 + `devkit_agri_query` MCP tool | **等 agri-paper DDL PR** | +| W2 | SSE handler 流式适配 | `messages_handler` 支持分段推送；stdio 向后兼容 | W1 完成 | +| W2 | CLI/TUI pagination | `--limit` / `--page` 参数 | 无 | +| W3–W4 | `devkit_health`/`devkit_query` 流式集成 | TUI 进度条；Agent 不再阻塞 2–5s | W2 完成 | +| W5–W8 | Daemon 内置 SSE Server + clarity 长连接 | `devbase daemon` 常驻运行 MCP SSE；clarity URL 配置 | clarity-core MCP Client SSE 配置 | + +### Sprint 3（Phase 2 后半，2026-05-01 ~ 2026-05-15） + +1. **`devbase-core` crate 剥离**：将 Registry/HealthEngine/SyncOrchestrator/QueryEngine 抽象为可复用库，解除 `clarity-core` path dependency +2. **`.syncdone` 文件标记落地**：集成 syncthing-rust `FolderStatus::Idle` REST endpoint +3. **农业 Persona TOML 集成**：`PersonalityConfig` 模板变量插值 + `agri_expert.toml` 校验 + +### Phase 3（2026-05-15 ~ 2026-07-15） + +1. **依赖图谱可视化**：项目间引用关系图 +2. **语义检索层**：本地嵌入模型（bge-m3 或 kalosm）替代规则模式 fallback +3. **MCP 协议版本协商**：保持与旧版 Clarity 兼容 + +--- + +## 九、术语表 + +- **Blob**：Git 中文件内容的不可变对象，以内容哈希命名。 +- **Packfile**：Git 的后台存储优化格式，对同一文件的不同版本做 delta 压缩。 +- **MCP**：Model Context Protocol，LLM 与外部工具交互的标准协议。 +- **Registry**：devbase 的核心数据结构，记录所有被管理仓库的元数据。 +- **SyncOrchestrator**：devbase 的同步编排器，负责按标签和策略批量更新仓库。 +- **OpLog**：操作日志，记录 scan/sync/health 等关键操作的审计追踪。 +- **Data Tier**：数据分级（`public`/`cooperative`/`private`），控制同步边界。 diff --git a/docs/_audit/six-dimension-gap-analysis-20260430.md b/docs/_audit/six-dimension-gap-analysis-20260430.md index 24763f7..22281e6 100644 --- a/docs/_audit/six-dimension-gap-analysis-20260430.md +++ b/docs/_audit/six-dimension-gap-analysis-20260430.md @@ -1,446 +1,446 @@ -# devbase 六维信息模型 Gap Analysis - -> **审计日期**：2026-04-30 -> **审计对象**：devbase v0.13.0（Local Context Compiler） -> **审计范围**：MCP 工具层（38 tools）、CLI 路由层、数据库 Schema（v23/v25）、架构文档 -> **审计方法**：源码静态分析 + 测试覆盖检查 + CLI/MCP 对称性比对 - ---- - -## Executive Summary - -devbase 的六维信息模型在**纸面架构**（`docs/architecture/context-compiler.md`）与**实际实现**之间存在显著落差。核心问题： - -1. **`project_context` 并非真正的“编译端点”** — 它聚合了 7 类数据，但未触及 `relations` 统一关系表、`known_limits` 风险层、`experiments` 历史层，也无法跨项目工作。 -2. **38 个 MCP tools 中仅 7 个有实际 invocation 测试**，其余 31 个仅为 schema 注册测试（`test_tools_list`）。 -3. **CLI 与 MCP 严重不对称** — CLI 有 20+ 条独占命令，MCP 有 15+ 个独占工具，双向能力缺口大。 -4. **`relations` 表已激活（v24）但无人使用** — 没有任何 MCP 工具或 CLI 命令查询该表，统一实体模型的图遍历能力为零。 - ---- - -## 维度一：Situation — “我房间里有什么书？” - -### 1.1 现存数据源 - -| 数据源 | 表/文件 | 说明 | -|--------|---------|------| -| 仓库清单 | `entities` (`entity_type='repo'`) + `repo_tags` + `repo_remotes` | 统一实体模型存储 | -| Skill 清单 | `skills` 表（独立于 `entities`） | 运行时注册表 | -| Vault 笔记 | `entities` (`entity_type='vault_note'`) + `vault_repo_links` | Markdown 文件系统 + SQLite 索引 | -| 论文 | `entities` (`entity_type='paper'`) | PDF 元数据 | -| 工作流 | `entities` (`entity_type='workflow'`) | YAML 定义 | -| 模块结构 | `repo_modules` | Cargo target / 模块树 | -| 代码符号 | `code_symbols` | AST 提取的函数/结构体/枚举 | - -### 1.2 MCP 工具暴露 - -- `devkit_scan` — 扫描目录并注册仓库 -- `devkit_query_repos` — 按 language/tag/status 过滤仓库 -- `devkit_query` — 通用结构化查询（lang:rust stale:>30） -- `devkit_natural_language_query` — NL 过滤仓库 -- `devkit_vault_search` — 笔记关键词搜索（AND 逻辑，全文件读取） -- `devkit_skill_list` — Skill 列表 -- `devkit_module_graph` — Rust 模块结构 -- `devkit_code_symbols` — 符号索引查询 -- `devkit_project_context` — 单项目聚合（见后文批判） - -### 1.3 CLI 命令暴露 - -- `scan`, `query`, `vault list`, `skill list`, `workflow list`, `discover` - -### 1.4 闭环能力 - -**部分闭环，但无统一 Workspace Snapshot。** - -- 仓库维度：`devkit_query_repos` + `devkit_scan` 可闭环发现 + 列举。 -- Vault 维度：`devkit_vault_search` 可闭环搜索。 -- Skill 维度：`devkit_skill_list` 可闭环列举。 -- **跨维度断层**：没有一个工具返回“当前 workspace 所有实体类型全景”。例如：Agent 无法通过一次调用得知“我有 4 个 repo、3 个 skill、12 篇笔记、2 个 workflow”。 - -### 1.5 缺失与破损 - -| 缺口 | 严重度 | 描述 | -|------|--------|------| -| **无 `devkit_workspace_snapshot`** | 🔴 高 | `entities` 表设计为统一存储，但没有工具能按 `entity_type` 聚合返回全 workspace 目录。 | -| **Skill 不在 `entities` 中** | 🟡 中 | `skills` 表是独立表，未纳入统一实体模型，导致 `relations` 表无法关联 skill→repo。 | -| **`devkit_vault_search` 性能隐患** | 🟡 中 | 实现为逐文件 `read_note_body` + 字符串 `contains`，无 Tantivy/BM25 加速，大 vault 下 O(n) 遍历。 | -| **无工作流 MCP 工具** | 🟡 中 | `workflow` 实体有 CLI 命令（`workflow list/run/register`），但无任何 MCP 工具暴露。 | - ---- - -## 维度二：State — “哪些书还没读完？” - -### 2.1 现存数据源 - -| 数据源 | 表/文件 | 说明 | -|--------|---------|------| -| Git 健康状态 | `repo_health` + `entities.metadata` | dirty/ahead/behind/diverged | -| 代码指标 | `repo_code_metrics` | 行数/语言分布/文件数 | -| 索引覆盖度 | `code_symbols` 计数 + `code_embeddings` 存在性 | 符号是否被索引、是否有 embedding | -| 调用图密度 | `code_call_graph` 边数 | 可计算 but 未暴露 | -| 操作审计 | `oplog` | 最近 scan/index/sync 事件 | -| 已知限制 | `known_limits` | Hard Veto / Known Bug | -| 环境状态 | `health::analyze_repo` 运行时检测 | Rust/Go/Node 版本 | - -### 2.2 MCP 工具暴露 - -- `devkit_health` — 返回仓库 Git 状态 + 环境检查 -- `devkit_code_metrics` — 返回代码统计 -- `devkit_knowledge_report` — 返回符号数/embedding 数/调用边数/activity -- `devkit_oplog_query` — 返回操作日志 -- `devkit_known_limit_list` — 返回已知限制 - -### 2.3 CLI 命令暴露 - -- `health`, `oplog`, `digest`, `limit list` - -### 2.4 闭环能力 - -**半闭环 — 数据分散在多个工具中，无统一仪表盘。** - -- `devkit_health` 仅覆盖 Git 状态，不报告索引新鲜度（“上次索引是何时？”）。 -- `devkit_knowledge_report` 覆盖索引统计，但不报告 Git 健康。 -- `devkit_oplog_query` 覆盖事件历史，但默认仅返回原始日志，无状态推导（“哪些 repo 超过 7 天未索引？”）。 - -### 2.5 缺失与破损 - -| 缺口 | 严重度 | 描述 | -|------|--------|------| -| **无 Index Freshness 检查** | 🔴 高 | `devkit_health` 不检查 `repo_modules`/`code_symbols`/`code_call_graph` 的生成时间。Agent 无法判断“这个 repo 的符号索引是否过期”。 | -| **`devkit_knowledge_report` 未测** | 🟡 中 | 38 tools 中唯一在 `test_tools_list` 里被断言存在，但无任何 invocation 测试的 Experimental 级工具。 | -| **无统一状态仪表盘** | 🟡 中 | 没有“Workspace State Compiler”将 Git 健康 + 索引覆盖 + 已知限制 + oplog 聚合成一张快照。 | -| **`repo_health` 与 `entities` 不同步风险** | 🟡 中 | `repo_health` 是独立表，`entities.metadata` 也含 `last_synced_at`，双源存储可能导致不一致。 | - ---- - -## 维度三：Relations — “这本书引用了哪本？” - -### 3.1 现存数据源 - -| 数据源 | 表/文件 | 说明 | -|--------|---------|------| -| 统一关系图 | `relations` (v24 激活) | `from_entity_id` → `to_entity_id`，有向图 | -| 代码调用图 | `code_call_graph` | 函数级调用边 | -| 概念符号链接 | `code_symbol_links` | 相似签名 / 同文件关联 | -| 跨仓库依赖 | `dependency_graph` 模块 + `repo_relations` (legacy) | Cargo.toml/package.json/go.mod 解析 | -| Vault 反链 | `vault` 文件系统 wikilink | `[[note-id]]` 语法 | -| 仓库-笔记链接 | `vault_repo_links` | 显式双向链接 | - -### 3.2 MCP 工具暴露 - -- `devkit_dependency_graph` — 跨仓库依赖（outgoing/incoming） -- `devkit_call_graph` — 函数调用图（caller/callee） -- `devkit_related_symbols` — 概念关联符号 -- `devkit_vault_backlinks` — Vault 笔记反链 -- `devkit_project_context` — 包含 `related_symbols`（对 top symbols 的有限关联） - -### 3.3 CLI 命令暴露 - -- `discover` — 自动发现 repo 间依赖和相似性，写入 `relations`（legacy `repo_relations`） - -### 3.4 闭环能力 - -**严重断裂 — `relations` 表存在但完全不可访问。** - -- `devkit_dependency_graph` 查询的是 `dependency_graph` 模块（manifest 解析），**不查询 `relations` 表**。 -- `devkit_project_context` 的 `related_symbols` 来自 `code_symbol_links` + `find_related_symbols`，**不查询 `relations` 表**。 -- `devkit_call_graph` 查询 `code_call_graph`，**不查询 `relations` 表**。 -- **没有任何工具可以执行：`SELECT * FROM relations WHERE from_entity_id = ?`**。 - -### 3.5 缺失与破损 - -| 缺口 | 严重度 | 描述 | -|------|--------|------| -| **`relations` 表零暴露** | 🔴 高 | 架构文档声称 v24 已激活并迁移 `repo_relations` → `relations`，但 38 个 tools 中没有任何一个查询 `relations`。统一实体模型的核心优势（“新增概念无需改表”）因缺乏查询端点而被架空。 | -| **无通用图遍历工具** | 🔴 高 | 没有 `devkit_relations_query` 或 `devkit_entity_neighbors` 工具。Agent 无法问“与这个 skill 相关的 repo 有哪些？” | -| **`devkit_project_context` 关系不完整** | 🟡 中 | 仅返回 `related_symbols`（代码级），不返回 `relations` 表中的 repo→repo、repo→paper、repo→workflow 关系。 | -| **Vault 反链非实时** | 🟡 中 | `devkit_vault_backlinks` 每次调用都重新 `build_backlink_index`，无缓存，大 vault 性能差。 | -| **CLI `discover` 无 MCP 镜像** | 🟡 中 | `discover` 命令能自动推断并保存关系，但 MCP 侧没有对应工具，Agent 无法触发关系发现。 | - ---- - -## 维度四：Capability — “我可以用笔划线、用书签标记” - -### 4.1 现存数据源 - -| 数据源 | 表/文件 | 说明 | -|--------|---------|------| -| Skill 目录 | `skills` 表 | 已安装 skill 元数据 | -| Skill 执行历史 | `skill_executions` | 运行时记录 | -| Skill 评分 | `skill_scores` | 成功率/评分 | -| Workflow 定义 | `workflows` 表 + `entities` | 多步骤编排 | -| MCP 工具注册表 | `mcp::McpServer` 运行时 | 38 个 tools | - -### 4.2 MCP 工具暴露 - -- `devkit_skill_list` — 列举 skill -- `devkit_skill_search` — 文本搜索 skill -- `devkit_skill_run` — 执行 skill（destructive gate） -- `devkit_skill_discover` — 将项目封装为 skill（destructive gate） -- **38 个 tools 本身** — 即 capability 的具象化 - -### 4.3 CLI 命令暴露 - -- `skill list`, `skill search`, `skill run`, `skill discover`, `skill info`, `skill install`, `skill uninstall`, `skill validate`, `skill publish`, `skill sync`, `skill recalc-scores`, `skill top`, `skill recommend` -- `workflow list`, `workflow show`, `workflow run`, `workflow register`, `workflow delete` - -### 4.4 闭环能力 - -**Skill 维度闭环，Workflow 维度完全缺失。** - -- Skill 发现 → 搜索 → 执行：`devkit_skill_list` → `devkit_skill_search` → `devkit_skill_run` 形成完整闭环。 -- **Workflow 零暴露**：Agent 无法通过 MCP 知道有哪些 workflow、无法触发 workflow 执行。 - -### 4.5 缺失与破损 - -| 缺口 | 严重度 | 描述 | -|------|--------|------| -| **无 Workflow MCP 工具集** | 🔴 高 | `workflow` 是 `entities` 中定义的内置类型，有完整 CLI 命令集，但 MCP 侧没有任何 workflow 工具（list/show/run/register/delete）。 | -| **无 Skill 安装/卸载 MCP 工具** | 🟡 中 | CLI 有 `skill install `、`skill uninstall `，MCP 侧没有。Agent 无法通过对话安装新 skill。 | -| **无 Skill 评分/推荐 MCP 工具** | 🟡 中 | CLI 有 `skill top`、`skill recommend`、`skill recalc-scores`，MCP 侧没有。Agent 无法获取“最适合当前任务的 skill”。 | -| **无 Skill 详情 MCP 工具** | 🟡 中 | CLI 有 `skill info` 返回完整元数据（author/inputs/outputs/dependencies），MCP 仅有 `skill_list` 返回基础字段。 | -| **Capability 未在 `project_context` 中体现** | 🟡 中 | `project_context` 返回 repo + vault + symbols，但不返回“该项目可用的 skill 或 workflow 有哪些”。 | - ---- - -## 维度五：History — “上次读这本书到哪一章？” - -### 5.1 现存数据源 - -| 数据源 | 表/文件 | 说明 | -|--------|---------|------| -| 操作日志 | `oplog` | scan/index/sync/health 等事件 | -| Agent 符号读取历史 | `agent_symbol_reads` (v25 激活) | 行为信号，用于 relevance boosting | -| Skill 执行历史 | `skill_executions` | stdout/stderr/exit_code/duration | -| 实验记录 | `experiments` 表 | 实验配置与结果 | -| 已知限制历史 | `known_limits` | first_seen_at / last_checked_at / mitigated | - -### 5.2 MCP 工具暴露 - -- `devkit_oplog_query` — 查询操作日志（全局或按 repo） -- `devkit_project_context` — 包含最近 10 条 oplog（activity 字段） -- `devkit_experiment_log` — 记录实验（write-only） -- `devkit_known_limit_list` — 查询已知限制 - -### 5.3 CLI 命令暴露 - -- `oplog`, `digest`, `limit list` - -### 5.4 闭环能力 - -**半闭环 — 写得多，读得少。** - -- `devkit_oplog_query` 提供全局/按 repo 的日志读取，是完整闭环。 -- `agent_symbol_reads` 被 `project_context` **写入**（记录 symbol 读取），但**没有任何工具可以读取该历史**。Agent 无法问“我最近常看哪些函数？”。 -- `devkit_experiment_log` 是 write-only；没有 `devkit_experiment_list` 或 `devkit_experiment_query`。 -- `skill_executions` 表有数据，但 MCP 侧无查询工具。 - -### 5.5 缺失与破损 - -| 缺口 | 严重度 | 描述 | -|------|--------|------| -| **`agent_symbol_reads` 只写不读** | 🔴 高 | v25 引入的行为信号表，仅用于 `hybrid_search_symbols` 的内部 boosting，未向 Agent 暴露。丧失了“记忆我看过什么”的核心价值。 | -| **无 `devkit_experiment_list` 工具** | 🟡 中 | `devkit_experiment_log` 可写，但无对应读取工具。Agent 无法审计实验历史。 | -| **无 Skill 执行历史 MCP 工具** | 🟡 中 | `skill_executions` 有详细记录，但 MCP 侧无查询接口。 | -| **`devkit_digest` 未测试** | 🟡 中 | 生成每日摘要，但无 invocation 测试，且其输出未与 `project_context` 集成。 | -| **`project_context` 的 activity 只有 10 条** | 🟢 低 | 硬编码 limit=10，无参数可调整，对于高频操作 repo 可能丢失关键上下文。 | - ---- - -## 维度六：Relevance — “我现在要写论文，哪些书相关？” - -### 6.1 现存数据源 - -| 数据源 | 表/文件 | 说明 | -|--------|---------|------| -| 代码 Embedding | `code_embeddings` | 符号级向量 | -| 混合搜索索引 | `hybrid_search_symbols` (RRF 合并) | 向量相似度 + 关键词 BM25 | -| 符号读取计数 | `agent_symbol_reads` | 行为 boosting | -| Vault 内容 | Markdown 文件系统 | 全文但无向量索引 | -| Tantivy 索引 | `search::index` | repo 摘要/关键词/模块结构 | - -### 6.2 MCP 工具暴露 - -- `devkit_project_context` (with `goal`) — 按 goal 对 symbols 做 hybrid search relevance ranking -- `devkit_hybrid_search` — 符号级混合搜索（向量+关键词 RRF） -- `devkit_semantic_search` / `devkit_embedding_search` — 纯向量搜索 -- `devkit_related_symbols` — 概念关联符号 -- `devkit_cross_repo_search` — 跨仓库混合搜索 -- `devkit_natural_language_query` — NL 过滤仓库（非 relevance rank） - -### 6.3 CLI 命令暴露 - -- 无直接对应命令（Relevance 是 MCP 层独有概念） - -### 6.4 闭环能力 - -**代码符号维度闭环，Vault/跨实体维度断裂。** - -- 代码搜索：`devkit_hybrid_search` → `devkit_related_symbols` → `devkit_cross_repo_search` 形成符号发现闭环。 -- **Vault 无 Relevance**：`devkit_vault_search` 是纯关键词 AND 匹配，无 embedding、无 goal-based ranking。Agent 无法问“与我的目标相关的笔记有哪些？”。 -- **跨实体无 Relevance**：没有工具能回答“给定 goal，哪些 repo + 哪些 vault notes + 哪些 skills 最相关？”。 - -### 6.5 缺失与破损 - -| 缺口 | 严重度 | 描述 | -|------|--------|------| -| **无 Vault Embedding/Relevance** | 🔴 高 | Vault 笔记是跨会话记忆的核心载体，但搜索仍停留在字符串 contains 阶段，无法与代码符号的 hybrid search 对齐。 | -| **`project_context` 的 `goal` 仅影响 symbols** | 🟡 中 | 传入 `goal` 后，仅 `symbols` 和 `calls` 被 relevance 过滤/排序，`vault_notes` 和 `assets` 不受影响。 | -| **无 Workspace-wide Goal Match** | 🟡 中 | `devkit_project_context` 要求传入 `project` 参数，无法做 workspace 级别的“给定 goal，返回最相关的实体（任意类型）”。 | -| **`agent_symbol_reads` boosting 不透明** | 🟡 中 | `project_context` 在无 `goal` 时使用 `agent_symbol_reads` 做 behavioral boosting，但 boost 值（0.05×count, max 0.5）未向 Agent 披露，形成黑盒排序。 | -| **`devkit_natural_language_query` 非真正语义** | 🟢 低 | 实现为硬编码 regex 过滤（language keywords + stars parse + status keywords），无 LLM/embedding 参与，名称具有误导性。 | - ---- - -## 横向审计 A：MCP 工具测试覆盖 - -### 实际有 Invocation 测试的工具（7 / 38） - -| 工具名 | 测试函数 | 备注 | -|--------|----------|------| -| `devkit_health` | `test_tools_call_devkit_health` | ✅ | -| `devkit_query` | `test_tools_call_devkit_query` | ✅ | -| `devkit_project_context` | `test_tools_call_devkit_project_context` | 仅测空项目 case | -| `devkit_arxiv_fetch` | `test_tools_call_devkit_arxiv_fetch` | 测空 ID error case | -| `devkit_skill_list` | `test_tools_call_devkit_skill_list` | ✅ | -| `devkit_skill_search` | `test_tools_call_devkit_skill_search` | ✅ | -| `devkit_skill_discover` | `test_tools_call_devkit_skill_discover` | dry_run 模式 | -| `devkit_skill_run` | `test_tools_call_devkit_skill_run` | ⚠️ `#[ignore]` | - -### 无任何 Invocation 测试的工具（31 / 38） - -``` -devkit_scan, devkit_sync, devkit_index, devkit_note, devkit_digest, -devkit_paper_index, devkit_experiment_log, devkit_github_info, -devkit_code_metrics, devkit_module_graph, devkit_query_repos, -devkit_natural_language_query, devkit_code_symbols, devkit_dependency_graph, -devkit_call_graph, devkit_dead_code, devkit_semantic_search, -devkit_embedding_store, devkit_embedding_search, devkit_vault_search, -devkit_vault_read, devkit_vault_write, devkit_vault_backlinks, -devkit_cross_repo_search, devkit_knowledge_report, devkit_related_symbols, -devkit_hybrid_search, devkit_known_limit_store, devkit_known_limit_list, -devkit_oplog_query -``` - -> **风险**：这些工具的 schema 与实际实现可能已发生漂移（schema 承诺了字段，但 `invoke` 可能未返回），且运行时 panic 无测试捕获。 - ---- - -## 横向审计 B：CLI ↔ MCP 对称性 - -### CLI 独占命令（无 MCP 等价工具） - -| CLI 命令 | 功能 | 缺口影响 | -|----------|------|----------| -| `clean` | 删除备份实体 | Agent 无法清理注册表垃圾 | -| `tag ` | 为仓库打标签 | Agent 无法动态标签分类 | -| `meta --tier/--workspace-type` | 更新元数据 | Agent 无法修改数据分级 | -| `discover` | 自动发现 repo 关系 | Agent 无法触发关系发现 | -| `skill install/uninstall/info/validate/publish/sync/recalc-scores/top/recommend` | Skill 生命周期管理 | Agent 无法完整管理 skill | -| `workflow list/show/run/register/delete` | 工作流引擎 | **Agent 完全无法使用 workflow** | -| `limit add/resolve/delete/seed` | 已知限制管理 | Agent 无法 resolve/delete limit | -| `registry export/import/backups/clean` | 备份恢复 | Agent 无法备份 | -| `vault scan/reindex` | Vault 索引维护 | Agent 无法重建 vault 索引 | -| `syncthing-push` | P2P 同步 | Agent 无法触发 | -| `skill-sync` | 同步到 Clarity | Agent 无法触发 | - -### MCP 独占工具（无 CLI 等价命令） - -| MCP 工具 | 功能 | 缺口影响 | -|----------|------|----------| -| `devkit_cross_repo_search` | 跨仓库符号搜索 | 人类用户无法从命令行使用 | -| `devkit_related_symbols` | 概念关联符号 | 人类用户无法从命令行使用 | -| `devkit_hybrid_search` | 混合搜索 | 人类用户无法从命令行使用 | -| `devkit_semantic_search` / `devkit_embedding_search` | 向量搜索 | 人类用户无法从命令行使用（CLI skill search 有语义模式，但仅针对 skill） | -| `devkit_call_graph` | 函数调用图 | 人类用户无法从命令行使用 | -| `devkit_dead_code` | 死代码检测 | 人类用户无法从命令行使用 | -| `devkit_code_symbols` | 符号查询 | 人类用户无法从命令行使用 | -| `devkit_dependency_graph` | 依赖图 | 人类用户无法从命令行使用 | -| `devkit_knowledge_report` | 知识覆盖报告 | 人类用户无法从命令行使用 | -| `devkit_note` | 为 repo 添加短笔记 | 人类用户无法从命令行使用 | -| `devkit_github_info` | GitHub API 查询 | 人类用户无法从命令行使用 | -| `devkit_experiment_log` | 记录实验 | 人类用户无法从命令行使用 | -| `devkit_paper_index` | 索引论文 | 人类用户无法从命令行使用 | -| `devkit_module_graph` | 模块图 | 人类用户无法从命令行使用 | -| `devkit_code_metrics` | 代码指标 | 人类用户无法从命令行使用 | - ---- - -## 横向审计 C：`project_context` 是否是真·编译端点？ - -### 它聚合了什么（✅） - -| 维度 | 数据来源 | 字段 | -|------|----------|------| -| Repo 元数据 | `entities` + `repo_tags` | `repo` | -| Vault 笔记 | `vault_repo_links` + 关键词匹配 | `vault_notes` | -| 模块结构 | `repo_modules` | `modules` | -| 代码符号 | `code_symbols` (LIMIT 50) / `hybrid_search_symbols` | `symbols` | -| 调用边 | `code_call_graph` (LIMIT 50) | `calls` | -| 操作历史 | `oplog` (LIMIT 10) | `activity` | -| 概念关联 | `code_symbol_links` | `related_symbols` | -| 资产文件 | 文件系统 `assets/` 目录 | `assets` | - -### 它没有聚合什么（❌） - -| 维度 | 缺失数据 | 影响 | -|------|----------|------| -| **Relations 表** | 不查询 `relations` | 无法展示 repo→repo、repo→skill、skill→workflow 关系 | -| **Known Limits** | 不查询 `known_limits` | Agent 不知道该项目是否有 Hard Veto | -| **Experiments** | 不查询 `experiments` | Agent 不知道该项目是否有正在进行的实验 | -| **Skills** | 不查询 `skills` | Agent 不知道有哪些 skill 可用 | -| **Workflows** | 不查询 `workflows` | Agent 不知道有哪些 workflow 可用 | -| **State/Health** | 不查询 `repo_health` | 不返回 dirty/ahead/behind 状态 | -| **Index Coverage** | 不查询 `code_embeddings` | 不返回“有多少符号已 embedding” | -| **Agent Symbol Reads** | 写入但不读取 | 不向 Agent 暴露“你之前看过这些符号” | -| **Vault Relevance** | 关键词匹配 only | `goal` 参数不影响 vault_notes 排序 | - -### verdict - -`project_context` 是一个**局部编译器**（Partial Compiler），而非架构文档宣称的“统一情境编译端点”。它编译了代码层 + 笔记层 + 活动层的子集，但： - -1. **漏掉了统一实体模型的核心——`relations` 图**。 -2. **漏掉了 Capability 层**（skill/workflow）。 -3. **漏掉了 Risk 层**（known limits）。 -4. **漏掉了 History 层的可读面**（agent_symbol_reads）。 -5. **仅支持单项目模式**，无法做 workspace 级编译。 - ---- - -## 关键发现汇总 - -| # | 发现 | 严重度 | 建议修复 | -|---|------|--------|----------| -| 1 | `relations` 表零暴露 — 统一实体模型的图遍历能力未实现 | 🔴 | 新增 `devkit_relations_query` 工具；CLI `discover` 增加 MCP 镜像 | -| 2 | `project_context` 不是真·编译端点 — 缺 Relations/Capability/Risk/History | 🔴 | 扩展 `project_context` 或新增 `devkit_workspace_context`；纳入 `relations`、`known_limits`、`skills`、`workflows` | -| 3 | Workflow 引擎零 MCP 暴露 | 🔴 | 新增 `devkit_workflow_list/run/register/delete` 工具集 | -| 4 | 38 tools 中 31 个无任何 invocation 测试 | 🔴 | 为核心 tools 补充集成测试（至少 Stable + Beta tier） | -| 5 | `agent_symbol_reads` 只写不读 | 🔴 | 新增 `devkit_symbol_read_history` 工具；或在 `project_context` 中暴露读取历史 | -| 6 | Vault 搜索无 relevance/embedding | 🟡 | 为 Vault 笔记建立 Tantivy/embedding 索引；`devkit_vault_search` 支持 `goal` 参数 | -| 7 | CLI 与 MCP 严重不对称 | 🟡 | 对双向独占功能做对称补全；优先补全 Workflow MCP 和 Skill 生命周期 MCP | -| 8 | `devkit_natural_language_query` 名不副实 | 🟡 | 重命名或接入真正的 LLM/embedding 语义解析 | -| 9 | `devkit_health` 无索引新鲜度 | 🟡 | 增加 `last_indexed_at`、`symbol_count`、`embedding_coverage` 字段 | -| 10 | `devkit_vault_search` 全文件 O(n) 扫描 | 🟡 | 使用 Tantivy reader 替代逐文件读取 | - ---- - -## 附录：数据源 ↔ 工具映射矩阵 - -| 数据源 | Situation | State | Relations | Capability | History | Relevance | -|--------|-----------|-------|-----------|------------|---------|-----------| -| `entities` (repos) | ✅ scan/query/query_repos/nlq | ✅ health | ❌ 无工具 | ❌ 无工具 | ❌ 无工具 | ⚠️ nlq 仅过滤 | -| `entities` (vault) | ✅ vault_search | ❌ 无 | ⚠️ backlinks | ❌ 无 | ❌ 无 | ⚠️ 关键词 only | -| `entities` (workflow) | ❌ 无 MCP | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | -| `skills` | ✅ skill_list | ❌ 无 | ❌ 无 | ✅ skill_list/search/run | ⚠️ 执行历史无暴露 | ❌ 无 | -| `relations` | ❌ **零暴露** | ❌ 无 | ❌ **零暴露** | ❌ 无 | ❌ 无 | ❌ 无 | -| `code_symbols` | ✅ code_symbols | ✅ knowledge_report | ⚠️ related_symbols | ❌ 无 | ❌ 无 | ✅ hybrid_search | -| `code_call_graph` | ❌ 无直接暴露 | ✅ knowledge_report | ✅ call_graph | ❌ 无 | ❌ 无 | ❌ 无 | -| `code_embeddings` | ❌ 无 | ✅ knowledge_report | ❌ 无 | ❌ 无 | ❌ 无 | ✅ semantic_search | -| `agent_symbol_reads` | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | ❌ **只写不读** | ⚠️ 内部 boosting | -| `oplog` | ❌ 无 | ✅ health/summary | ❌ 无 | ❌ 无 | ✅ oplog_query | ❌ 无 | -| `known_limits` | ❌ 无 | ✅ known_limit_list | ❌ 无 | ❌ 无 | ✅ known_limit_list | ❌ 无 | -| `experiments` | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | ❌ **只写不读** | ❌ 无 | - ---- - -*Report generated by codebase exploration agent. All table names, tool names, and file paths verified against `src/` at commit `d0eb774`.* +# devbase 六维信息模型 Gap Analysis + +> **审计日期**：2026-04-30 +> **审计对象**：devbase v0.13.0（Local Context Compiler） +> **审计范围**：MCP 工具层（38 tools）、CLI 路由层、数据库 Schema（v23/v25）、架构文档 +> **审计方法**：源码静态分析 + 测试覆盖检查 + CLI/MCP 对称性比对 + +--- + +## Executive Summary + +devbase 的六维信息模型在**纸面架构**（`docs/_archive/context-compiler.md`，历史文档，已归档）与**实际实现**之间存在显著落差。核心问题： + +1. **`project_context` 并非真正的“编译端点”** — 它聚合了 7 类数据，但未触及 `relations` 统一关系表、`known_limits` 风险层、`experiments` 历史层，也无法跨项目工作。 +2. **38 个 MCP tools 中仅 7 个有实际 invocation 测试**，其余 31 个仅为 schema 注册测试（`test_tools_list`）。 +3. **CLI 与 MCP 严重不对称** — CLI 有 20+ 条独占命令，MCP 有 15+ 个独占工具，双向能力缺口大。 +4. **`relations` 表已激活（v24）但无人使用** — 没有任何 MCP 工具或 CLI 命令查询该表，统一实体模型的图遍历能力为零。 + +--- + +## 维度一：Situation — “我房间里有什么书？” + +### 1.1 现存数据源 + +| 数据源 | 表/文件 | 说明 | +|--------|---------|------| +| 仓库清单 | `entities` (`entity_type='repo'`) + `repo_tags` + `repo_remotes` | 统一实体模型存储 | +| Skill 清单 | `skills` 表（独立于 `entities`） | 运行时注册表 | +| Vault 笔记 | `entities` (`entity_type='vault_note'`) + `vault_repo_links` | Markdown 文件系统 + SQLite 索引 | +| 论文 | `entities` (`entity_type='paper'`) | PDF 元数据 | +| 工作流 | `entities` (`entity_type='workflow'`) | YAML 定义 | +| 模块结构 | `repo_modules` | Cargo target / 模块树 | +| 代码符号 | `code_symbols` | AST 提取的函数/结构体/枚举 | + +### 1.2 MCP 工具暴露 + +- `devkit_scan` — 扫描目录并注册仓库 +- `devkit_query_repos` — 按 language/tag/status 过滤仓库 +- `devkit_query` — 通用结构化查询（lang:rust stale:>30） +- `devkit_natural_language_query` — NL 过滤仓库 +- `devkit_vault_search` — 笔记关键词搜索（AND 逻辑，全文件读取） +- `devkit_skill_list` — Skill 列表 +- `devkit_module_graph` — Rust 模块结构 +- `devkit_code_symbols` — 符号索引查询 +- `devkit_project_context` — 单项目聚合（见后文批判） + +### 1.3 CLI 命令暴露 + +- `scan`, `query`, `vault list`, `skill list`, `workflow list`, `discover` + +### 1.4 闭环能力 + +**部分闭环，但无统一 Workspace Snapshot。** + +- 仓库维度：`devkit_query_repos` + `devkit_scan` 可闭环发现 + 列举。 +- Vault 维度：`devkit_vault_search` 可闭环搜索。 +- Skill 维度：`devkit_skill_list` 可闭环列举。 +- **跨维度断层**：没有一个工具返回“当前 workspace 所有实体类型全景”。例如：Agent 无法通过一次调用得知“我有 4 个 repo、3 个 skill、12 篇笔记、2 个 workflow”。 + +### 1.5 缺失与破损 + +| 缺口 | 严重度 | 描述 | +|------|--------|------| +| **无 `devkit_workspace_snapshot`** | 🔴 高 | `entities` 表设计为统一存储，但没有工具能按 `entity_type` 聚合返回全 workspace 目录。 | +| **Skill 不在 `entities` 中** | 🟡 中 | `skills` 表是独立表，未纳入统一实体模型，导致 `relations` 表无法关联 skill→repo。 | +| **`devkit_vault_search` 性能隐患** | 🟡 中 | 实现为逐文件 `read_note_body` + 字符串 `contains`，无 Tantivy/BM25 加速，大 vault 下 O(n) 遍历。 | +| **无工作流 MCP 工具** | 🟡 中 | `workflow` 实体有 CLI 命令（`workflow list/run/register`），但无任何 MCP 工具暴露。 | + +--- + +## 维度二：State — “哪些书还没读完？” + +### 2.1 现存数据源 + +| 数据源 | 表/文件 | 说明 | +|--------|---------|------| +| Git 健康状态 | `repo_health` + `entities.metadata` | dirty/ahead/behind/diverged | +| 代码指标 | `repo_code_metrics` | 行数/语言分布/文件数 | +| 索引覆盖度 | `code_symbols` 计数 + `code_embeddings` 存在性 | 符号是否被索引、是否有 embedding | +| 调用图密度 | `code_call_graph` 边数 | 可计算 but 未暴露 | +| 操作审计 | `oplog` | 最近 scan/index/sync 事件 | +| 已知限制 | `known_limits` | Hard Veto / Known Bug | +| 环境状态 | `health::analyze_repo` 运行时检测 | Rust/Go/Node 版本 | + +### 2.2 MCP 工具暴露 + +- `devkit_health` — 返回仓库 Git 状态 + 环境检查 +- `devkit_code_metrics` — 返回代码统计 +- `devkit_knowledge_report` — 返回符号数/embedding 数/调用边数/activity +- `devkit_oplog_query` — 返回操作日志 +- `devkit_known_limit_list` — 返回已知限制 + +### 2.3 CLI 命令暴露 + +- `health`, `oplog`, `digest`, `limit list` + +### 2.4 闭环能力 + +**半闭环 — 数据分散在多个工具中，无统一仪表盘。** + +- `devkit_health` 仅覆盖 Git 状态，不报告索引新鲜度（“上次索引是何时？”）。 +- `devkit_knowledge_report` 覆盖索引统计，但不报告 Git 健康。 +- `devkit_oplog_query` 覆盖事件历史，但默认仅返回原始日志，无状态推导（“哪些 repo 超过 7 天未索引？”）。 + +### 2.5 缺失与破损 + +| 缺口 | 严重度 | 描述 | +|------|--------|------| +| **无 Index Freshness 检查** | 🔴 高 | `devkit_health` 不检查 `repo_modules`/`code_symbols`/`code_call_graph` 的生成时间。Agent 无法判断“这个 repo 的符号索引是否过期”。 | +| **`devkit_knowledge_report` 未测** | 🟡 中 | 38 tools 中唯一在 `test_tools_list` 里被断言存在，但无任何 invocation 测试的 Experimental 级工具。 | +| **无统一状态仪表盘** | 🟡 中 | 没有“Workspace State Compiler”将 Git 健康 + 索引覆盖 + 已知限制 + oplog 聚合成一张快照。 | +| **`repo_health` 与 `entities` 不同步风险** | 🟡 中 | `repo_health` 是独立表，`entities.metadata` 也含 `last_synced_at`，双源存储可能导致不一致。 | + +--- + +## 维度三：Relations — “这本书引用了哪本？” + +### 3.1 现存数据源 + +| 数据源 | 表/文件 | 说明 | +|--------|---------|------| +| 统一关系图 | `relations` (v24 激活) | `from_entity_id` → `to_entity_id`，有向图 | +| 代码调用图 | `code_call_graph` | 函数级调用边 | +| 概念符号链接 | `code_symbol_links` | 相似签名 / 同文件关联 | +| 跨仓库依赖 | `dependency_graph` 模块 + `repo_relations` (legacy) | Cargo.toml/package.json/go.mod 解析 | +| Vault 反链 | `vault` 文件系统 wikilink | `[[note-id]]` 语法 | +| 仓库-笔记链接 | `vault_repo_links` | 显式双向链接 | + +### 3.2 MCP 工具暴露 + +- `devkit_dependency_graph` — 跨仓库依赖（outgoing/incoming） +- `devkit_call_graph` — 函数调用图（caller/callee） +- `devkit_related_symbols` — 概念关联符号 +- `devkit_vault_backlinks` — Vault 笔记反链 +- `devkit_project_context` — 包含 `related_symbols`（对 top symbols 的有限关联） + +### 3.3 CLI 命令暴露 + +- `discover` — 自动发现 repo 间依赖和相似性，写入 `relations`（legacy `repo_relations`） + +### 3.4 闭环能力 + +**严重断裂 — `relations` 表存在但完全不可访问。** + +- `devkit_dependency_graph` 查询的是 `dependency_graph` 模块（manifest 解析），**不查询 `relations` 表**。 +- `devkit_project_context` 的 `related_symbols` 来自 `code_symbol_links` + `find_related_symbols`，**不查询 `relations` 表**。 +- `devkit_call_graph` 查询 `code_call_graph`，**不查询 `relations` 表**。 +- **没有任何工具可以执行：`SELECT * FROM relations WHERE from_entity_id = ?`**。 + +### 3.5 缺失与破损 + +| 缺口 | 严重度 | 描述 | +|------|--------|------| +| **`relations` 表零暴露** | 🔴 高 | 架构文档声称 v24 已激活并迁移 `repo_relations` → `relations`，但 38 个 tools 中没有任何一个查询 `relations`。统一实体模型的核心优势（“新增概念无需改表”）因缺乏查询端点而被架空。 | +| **无通用图遍历工具** | 🔴 高 | 没有 `devkit_relations_query` 或 `devkit_entity_neighbors` 工具。Agent 无法问“与这个 skill 相关的 repo 有哪些？” | +| **`devkit_project_context` 关系不完整** | 🟡 中 | 仅返回 `related_symbols`（代码级），不返回 `relations` 表中的 repo→repo、repo→paper、repo→workflow 关系。 | +| **Vault 反链非实时** | 🟡 中 | `devkit_vault_backlinks` 每次调用都重新 `build_backlink_index`，无缓存，大 vault 性能差。 | +| **CLI `discover` 无 MCP 镜像** | 🟡 中 | `discover` 命令能自动推断并保存关系，但 MCP 侧没有对应工具，Agent 无法触发关系发现。 | + +--- + +## 维度四：Capability — “我可以用笔划线、用书签标记” + +### 4.1 现存数据源 + +| 数据源 | 表/文件 | 说明 | +|--------|---------|------| +| Skill 目录 | `skills` 表 | 已安装 skill 元数据 | +| Skill 执行历史 | `skill_executions` | 运行时记录 | +| Skill 评分 | `skill_scores` | 成功率/评分 | +| Workflow 定义 | `workflows` 表 + `entities` | 多步骤编排 | +| MCP 工具注册表 | `mcp::McpServer` 运行时 | 38 个 tools | + +### 4.2 MCP 工具暴露 + +- `devkit_skill_list` — 列举 skill +- `devkit_skill_search` — 文本搜索 skill +- `devkit_skill_run` — 执行 skill（destructive gate） +- `devkit_skill_discover` — 将项目封装为 skill（destructive gate） +- **38 个 tools 本身** — 即 capability 的具象化 + +### 4.3 CLI 命令暴露 + +- `skill list`, `skill search`, `skill run`, `skill discover`, `skill info`, `skill install`, `skill uninstall`, `skill validate`, `skill publish`, `skill sync`, `skill recalc-scores`, `skill top`, `skill recommend` +- `workflow list`, `workflow show`, `workflow run`, `workflow register`, `workflow delete` + +### 4.4 闭环能力 + +**Skill 维度闭环，Workflow 维度完全缺失。** + +- Skill 发现 → 搜索 → 执行：`devkit_skill_list` → `devkit_skill_search` → `devkit_skill_run` 形成完整闭环。 +- **Workflow 零暴露**：Agent 无法通过 MCP 知道有哪些 workflow、无法触发 workflow 执行。 + +### 4.5 缺失与破损 + +| 缺口 | 严重度 | 描述 | +|------|--------|------| +| **无 Workflow MCP 工具集** | 🔴 高 | `workflow` 是 `entities` 中定义的内置类型，有完整 CLI 命令集，但 MCP 侧没有任何 workflow 工具（list/show/run/register/delete）。 | +| **无 Skill 安装/卸载 MCP 工具** | 🟡 中 | CLI 有 `skill install `、`skill uninstall `，MCP 侧没有。Agent 无法通过对话安装新 skill。 | +| **无 Skill 评分/推荐 MCP 工具** | 🟡 中 | CLI 有 `skill top`、`skill recommend`、`skill recalc-scores`，MCP 侧没有。Agent 无法获取“最适合当前任务的 skill”。 | +| **无 Skill 详情 MCP 工具** | 🟡 中 | CLI 有 `skill info` 返回完整元数据（author/inputs/outputs/dependencies），MCP 仅有 `skill_list` 返回基础字段。 | +| **Capability 未在 `project_context` 中体现** | 🟡 中 | `project_context` 返回 repo + vault + symbols，但不返回“该项目可用的 skill 或 workflow 有哪些”。 | + +--- + +## 维度五：History — “上次读这本书到哪一章？” + +### 5.1 现存数据源 + +| 数据源 | 表/文件 | 说明 | +|--------|---------|------| +| 操作日志 | `oplog` | scan/index/sync/health 等事件 | +| Agent 符号读取历史 | `agent_symbol_reads` (v25 激活) | 行为信号，用于 relevance boosting | +| Skill 执行历史 | `skill_executions` | stdout/stderr/exit_code/duration | +| 实验记录 | `experiments` 表 | 实验配置与结果 | +| 已知限制历史 | `known_limits` | first_seen_at / last_checked_at / mitigated | + +### 5.2 MCP 工具暴露 + +- `devkit_oplog_query` — 查询操作日志（全局或按 repo） +- `devkit_project_context` — 包含最近 10 条 oplog（activity 字段） +- `devkit_experiment_log` — 记录实验（write-only） +- `devkit_known_limit_list` — 查询已知限制 + +### 5.3 CLI 命令暴露 + +- `oplog`, `digest`, `limit list` + +### 5.4 闭环能力 + +**半闭环 — 写得多，读得少。** + +- `devkit_oplog_query` 提供全局/按 repo 的日志读取，是完整闭环。 +- `agent_symbol_reads` 被 `project_context` **写入**（记录 symbol 读取），但**没有任何工具可以读取该历史**。Agent 无法问“我最近常看哪些函数？”。 +- `devkit_experiment_log` 是 write-only；没有 `devkit_experiment_list` 或 `devkit_experiment_query`。 +- `skill_executions` 表有数据，但 MCP 侧无查询工具。 + +### 5.5 缺失与破损 + +| 缺口 | 严重度 | 描述 | +|------|--------|------| +| **`agent_symbol_reads` 只写不读** | 🔴 高 | v25 引入的行为信号表，仅用于 `hybrid_search_symbols` 的内部 boosting，未向 Agent 暴露。丧失了“记忆我看过什么”的核心价值。 | +| **无 `devkit_experiment_list` 工具** | 🟡 中 | `devkit_experiment_log` 可写，但无对应读取工具。Agent 无法审计实验历史。 | +| **无 Skill 执行历史 MCP 工具** | 🟡 中 | `skill_executions` 有详细记录，但 MCP 侧无查询接口。 | +| **`devkit_digest` 未测试** | 🟡 中 | 生成每日摘要，但无 invocation 测试，且其输出未与 `project_context` 集成。 | +| **`project_context` 的 activity 只有 10 条** | 🟢 低 | 硬编码 limit=10，无参数可调整，对于高频操作 repo 可能丢失关键上下文。 | + +--- + +## 维度六：Relevance — “我现在要写论文，哪些书相关？” + +### 6.1 现存数据源 + +| 数据源 | 表/文件 | 说明 | +|--------|---------|------| +| 代码 Embedding | `code_embeddings` | 符号级向量 | +| 混合搜索索引 | `hybrid_search_symbols` (RRF 合并) | 向量相似度 + 关键词 BM25 | +| 符号读取计数 | `agent_symbol_reads` | 行为 boosting | +| Vault 内容 | Markdown 文件系统 | 全文但无向量索引 | +| Tantivy 索引 | `search::index` | repo 摘要/关键词/模块结构 | + +### 6.2 MCP 工具暴露 + +- `devkit_project_context` (with `goal`) — 按 goal 对 symbols 做 hybrid search relevance ranking +- `devkit_hybrid_search` — 符号级混合搜索（向量+关键词 RRF） +- `devkit_semantic_search` / `devkit_embedding_search` — 纯向量搜索 +- `devkit_related_symbols` — 概念关联符号 +- `devkit_cross_repo_search` — 跨仓库混合搜索 +- `devkit_natural_language_query` — NL 过滤仓库（非 relevance rank） + +### 6.3 CLI 命令暴露 + +- 无直接对应命令（Relevance 是 MCP 层独有概念） + +### 6.4 闭环能力 + +**代码符号维度闭环，Vault/跨实体维度断裂。** + +- 代码搜索：`devkit_hybrid_search` → `devkit_related_symbols` → `devkit_cross_repo_search` 形成符号发现闭环。 +- **Vault 无 Relevance**：`devkit_vault_search` 是纯关键词 AND 匹配，无 embedding、无 goal-based ranking。Agent 无法问“与我的目标相关的笔记有哪些？”。 +- **跨实体无 Relevance**：没有工具能回答“给定 goal，哪些 repo + 哪些 vault notes + 哪些 skills 最相关？”。 + +### 6.5 缺失与破损 + +| 缺口 | 严重度 | 描述 | +|------|--------|------| +| **无 Vault Embedding/Relevance** | 🔴 高 | Vault 笔记是跨会话记忆的核心载体，但搜索仍停留在字符串 contains 阶段，无法与代码符号的 hybrid search 对齐。 | +| **`project_context` 的 `goal` 仅影响 symbols** | 🟡 中 | 传入 `goal` 后，仅 `symbols` 和 `calls` 被 relevance 过滤/排序，`vault_notes` 和 `assets` 不受影响。 | +| **无 Workspace-wide Goal Match** | 🟡 中 | `devkit_project_context` 要求传入 `project` 参数，无法做 workspace 级别的“给定 goal，返回最相关的实体（任意类型）”。 | +| **`agent_symbol_reads` boosting 不透明** | 🟡 中 | `project_context` 在无 `goal` 时使用 `agent_symbol_reads` 做 behavioral boosting，但 boost 值（0.05×count, max 0.5）未向 Agent 披露，形成黑盒排序。 | +| **`devkit_natural_language_query` 非真正语义** | 🟢 低 | 实现为硬编码 regex 过滤（language keywords + stars parse + status keywords），无 LLM/embedding 参与，名称具有误导性。 | + +--- + +## 横向审计 A：MCP 工具测试覆盖 + +### 实际有 Invocation 测试的工具（7 / 38） + +| 工具名 | 测试函数 | 备注 | +|--------|----------|------| +| `devkit_health` | `test_tools_call_devkit_health` | ✅ | +| `devkit_query` | `test_tools_call_devkit_query` | ✅ | +| `devkit_project_context` | `test_tools_call_devkit_project_context` | 仅测空项目 case | +| `devkit_arxiv_fetch` | `test_tools_call_devkit_arxiv_fetch` | 测空 ID error case | +| `devkit_skill_list` | `test_tools_call_devkit_skill_list` | ✅ | +| `devkit_skill_search` | `test_tools_call_devkit_skill_search` | ✅ | +| `devkit_skill_discover` | `test_tools_call_devkit_skill_discover` | dry_run 模式 | +| `devkit_skill_run` | `test_tools_call_devkit_skill_run` | ⚠️ `#[ignore]` | + +### 无任何 Invocation 测试的工具（31 / 38） + +``` +devkit_scan, devkit_sync, devkit_index, devkit_note, devkit_digest, +devkit_paper_index, devkit_experiment_log, devkit_github_info, +devkit_code_metrics, devkit_module_graph, devkit_query_repos, +devkit_natural_language_query, devkit_code_symbols, devkit_dependency_graph, +devkit_call_graph, devkit_dead_code, devkit_semantic_search, +devkit_embedding_store, devkit_embedding_search, devkit_vault_search, +devkit_vault_read, devkit_vault_write, devkit_vault_backlinks, +devkit_cross_repo_search, devkit_knowledge_report, devkit_related_symbols, +devkit_hybrid_search, devkit_known_limit_store, devkit_known_limit_list, +devkit_oplog_query +``` + +> **风险**：这些工具的 schema 与实际实现可能已发生漂移（schema 承诺了字段，但 `invoke` 可能未返回），且运行时 panic 无测试捕获。 + +--- + +## 横向审计 B：CLI ↔ MCP 对称性 + +### CLI 独占命令（无 MCP 等价工具） + +| CLI 命令 | 功能 | 缺口影响 | +|----------|------|----------| +| `clean` | 删除备份实体 | Agent 无法清理注册表垃圾 | +| `tag ` | 为仓库打标签 | Agent 无法动态标签分类 | +| `meta --tier/--workspace-type` | 更新元数据 | Agent 无法修改数据分级 | +| `discover` | 自动发现 repo 关系 | Agent 无法触发关系发现 | +| `skill install/uninstall/info/validate/publish/sync/recalc-scores/top/recommend` | Skill 生命周期管理 | Agent 无法完整管理 skill | +| `workflow list/show/run/register/delete` | 工作流引擎 | **Agent 完全无法使用 workflow** | +| `limit add/resolve/delete/seed` | 已知限制管理 | Agent 无法 resolve/delete limit | +| `registry export/import/backups/clean` | 备份恢复 | Agent 无法备份 | +| `vault scan/reindex` | Vault 索引维护 | Agent 无法重建 vault 索引 | +| `syncthing-push` | P2P 同步 | Agent 无法触发 | +| `skill-sync` | 同步到 Clarity | Agent 无法触发 | + +### MCP 独占工具（无 CLI 等价命令） + +| MCP 工具 | 功能 | 缺口影响 | +|----------|------|----------| +| `devkit_cross_repo_search` | 跨仓库符号搜索 | 人类用户无法从命令行使用 | +| `devkit_related_symbols` | 概念关联符号 | 人类用户无法从命令行使用 | +| `devkit_hybrid_search` | 混合搜索 | 人类用户无法从命令行使用 | +| `devkit_semantic_search` / `devkit_embedding_search` | 向量搜索 | 人类用户无法从命令行使用（CLI skill search 有语义模式，但仅针对 skill） | +| `devkit_call_graph` | 函数调用图 | 人类用户无法从命令行使用 | +| `devkit_dead_code` | 死代码检测 | 人类用户无法从命令行使用 | +| `devkit_code_symbols` | 符号查询 | 人类用户无法从命令行使用 | +| `devkit_dependency_graph` | 依赖图 | 人类用户无法从命令行使用 | +| `devkit_knowledge_report` | 知识覆盖报告 | 人类用户无法从命令行使用 | +| `devkit_note` | 为 repo 添加短笔记 | 人类用户无法从命令行使用 | +| `devkit_github_info` | GitHub API 查询 | 人类用户无法从命令行使用 | +| `devkit_experiment_log` | 记录实验 | 人类用户无法从命令行使用 | +| `devkit_paper_index` | 索引论文 | 人类用户无法从命令行使用 | +| `devkit_module_graph` | 模块图 | 人类用户无法从命令行使用 | +| `devkit_code_metrics` | 代码指标 | 人类用户无法从命令行使用 | + +--- + +## 横向审计 C：`project_context` 是否是真·编译端点？ + +### 它聚合了什么（✅） + +| 维度 | 数据来源 | 字段 | +|------|----------|------| +| Repo 元数据 | `entities` + `repo_tags` | `repo` | +| Vault 笔记 | `vault_repo_links` + 关键词匹配 | `vault_notes` | +| 模块结构 | `repo_modules` | `modules` | +| 代码符号 | `code_symbols` (LIMIT 50) / `hybrid_search_symbols` | `symbols` | +| 调用边 | `code_call_graph` (LIMIT 50) | `calls` | +| 操作历史 | `oplog` (LIMIT 10) | `activity` | +| 概念关联 | `code_symbol_links` | `related_symbols` | +| 资产文件 | 文件系统 `assets/` 目录 | `assets` | + +### 它没有聚合什么（❌） + +| 维度 | 缺失数据 | 影响 | +|------|----------|------| +| **Relations 表** | 不查询 `relations` | 无法展示 repo→repo、repo→skill、skill→workflow 关系 | +| **Known Limits** | 不查询 `known_limits` | Agent 不知道该项目是否有 Hard Veto | +| **Experiments** | 不查询 `experiments` | Agent 不知道该项目是否有正在进行的实验 | +| **Skills** | 不查询 `skills` | Agent 不知道有哪些 skill 可用 | +| **Workflows** | 不查询 `workflows` | Agent 不知道有哪些 workflow 可用 | +| **State/Health** | 不查询 `repo_health` | 不返回 dirty/ahead/behind 状态 | +| **Index Coverage** | 不查询 `code_embeddings` | 不返回“有多少符号已 embedding” | +| **Agent Symbol Reads** | 写入但不读取 | 不向 Agent 暴露“你之前看过这些符号” | +| **Vault Relevance** | 关键词匹配 only | `goal` 参数不影响 vault_notes 排序 | + +### verdict + +`project_context` 是一个**局部编译器**（Partial Compiler），而非架构文档宣称的“统一情境编译端点”。它编译了代码层 + 笔记层 + 活动层的子集，但： + +1. **漏掉了统一实体模型的核心——`relations` 图**。 +2. **漏掉了 Capability 层**（skill/workflow）。 +3. **漏掉了 Risk 层**（known limits）。 +4. **漏掉了 History 层的可读面**（agent_symbol_reads）。 +5. **仅支持单项目模式**，无法做 workspace 级编译。 + +--- + +## 关键发现汇总 + +| # | 发现 | 严重度 | 建议修复 | +|---|------|--------|----------| +| 1 | `relations` 表零暴露 — 统一实体模型的图遍历能力未实现 | 🔴 | 新增 `devkit_relations_query` 工具；CLI `discover` 增加 MCP 镜像 | +| 2 | `project_context` 不是真·编译端点 — 缺 Relations/Capability/Risk/History | 🔴 | 扩展 `project_context` 或新增 `devkit_workspace_context`；纳入 `relations`、`known_limits`、`skills`、`workflows` | +| 3 | Workflow 引擎零 MCP 暴露 | 🔴 | 新增 `devkit_workflow_list/run/register/delete` 工具集 | +| 4 | 38 tools 中 31 个无任何 invocation 测试 | 🔴 | 为核心 tools 补充集成测试（至少 Stable + Beta tier） | +| 5 | `agent_symbol_reads` 只写不读 | 🔴 | 新增 `devkit_symbol_read_history` 工具；或在 `project_context` 中暴露读取历史 | +| 6 | Vault 搜索无 relevance/embedding | 🟡 | 为 Vault 笔记建立 Tantivy/embedding 索引；`devkit_vault_search` 支持 `goal` 参数 | +| 7 | CLI 与 MCP 严重不对称 | 🟡 | 对双向独占功能做对称补全；优先补全 Workflow MCP 和 Skill 生命周期 MCP | +| 8 | `devkit_natural_language_query` 名不副实 | 🟡 | 重命名或接入真正的 LLM/embedding 语义解析 | +| 9 | `devkit_health` 无索引新鲜度 | 🟡 | 增加 `last_indexed_at`、`symbol_count`、`embedding_coverage` 字段 | +| 10 | `devkit_vault_search` 全文件 O(n) 扫描 | 🟡 | 使用 Tantivy reader 替代逐文件读取 | + +--- + +## 附录：数据源 ↔ 工具映射矩阵 + +| 数据源 | Situation | State | Relations | Capability | History | Relevance | +|--------|-----------|-------|-----------|------------|---------|-----------| +| `entities` (repos) | ✅ scan/query/query_repos/nlq | ✅ health | ❌ 无工具 | ❌ 无工具 | ❌ 无工具 | ⚠️ nlq 仅过滤 | +| `entities` (vault) | ✅ vault_search | ❌ 无 | ⚠️ backlinks | ❌ 无 | ❌ 无 | ⚠️ 关键词 only | +| `entities` (workflow) | ❌ 无 MCP | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | +| `skills` | ✅ skill_list | ❌ 无 | ❌ 无 | ✅ skill_list/search/run | ⚠️ 执行历史无暴露 | ❌ 无 | +| `relations` | ❌ **零暴露** | ❌ 无 | ❌ **零暴露** | ❌ 无 | ❌ 无 | ❌ 无 | +| `code_symbols` | ✅ code_symbols | ✅ knowledge_report | ⚠️ related_symbols | ❌ 无 | ❌ 无 | ✅ hybrid_search | +| `code_call_graph` | ❌ 无直接暴露 | ✅ knowledge_report | ✅ call_graph | ❌ 无 | ❌ 无 | ❌ 无 | +| `code_embeddings` | ❌ 无 | ✅ knowledge_report | ❌ 无 | ❌ 无 | ❌ 无 | ✅ semantic_search | +| `agent_symbol_reads` | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | ❌ **只写不读** | ⚠️ 内部 boosting | +| `oplog` | ❌ 无 | ✅ health/summary | ❌ 无 | ❌ 无 | ✅ oplog_query | ❌ 无 | +| `known_limits` | ❌ 无 | ✅ known_limit_list | ❌ 无 | ❌ 无 | ✅ known_limit_list | ❌ 无 | +| `experiments` | ❌ 无 | ❌ 无 | ❌ 无 | ❌ 无 | ❌ **只写不读** | ❌ 无 | + +--- + +*Report generated by codebase exploration agent. All table names, tool names, and file paths verified against `src/` at commit `d0eb774`.* diff --git a/docs/guides/ai-instance-handoff.md b/docs/guides/ai-instance-handoff.md index 4c17b0f..ccd6e1c 100644 --- a/docs/guides/ai-instance-handoff.md +++ b/docs/guides/ai-instance-handoff.md @@ -1,202 +1,203 @@ -# AI 实例上下文交接指南 - -> 本文档面向**后续接入 devbase 项目的 AI Agent 实例**（Claw / CLI / Web 架构）。 -> 目标：在上下文压缩或会话切换后，新 AI 实例能在 60 秒内恢复有效工作上下文。 - ---- - -## 一、项目速览（30 秒） - -| 属性 | 值 | -|------|-----| -| **名称** | devbase — 本地优先的 AI Skill 编排基础设施 | -| **技术栈** | Rust 2024, SQLite, tokio, ratatui, git2, tantivy, tree-sitter | -| **当前版本** | v0.16.0-dev (`main@93b0860`) | -| **测试** | 450 passed / 0 failed / 5 ignored（`cargo test --workspace --lib`） | -| **编译** | `cargo check --workspace` 0 errors；clippy 0 warnings | -| **仓库** | `https://github.com/juice094/devbase` | - -### 快速自检（每次恢复上下文后执行） - -```powershell -# 1. 确认编译健康 -cd C:\Users\22414\dev\third_party\devbase -cargo check --workspace 2>&1 | Select-Object -Last 3 - -# 2. 确认测试全绿 -cargo test --workspace --lib 2>&1 | Select-String "test result" - -# 3. 确认 workspace 成员 -cargo metadata --format-version 1 --no-deps 2>$null | ConvertFrom-Json | Select-Object -ExpandProperty workspace_members - -# 4. 快速耦合扫描（Windows PowerShell） -Get-ChildItem src\*.rs | ForEach-Object { $count = (Select-String -Path $_.FullName -Pattern "crate::" -NoEmphasis).Count; "$($_.Name): $count refs" } | Sort-Object { [int]($_ -replace '.*: ', '' -replace ' refs', '') } | Select-Object -Last 10 -``` - ---- - -## 二、Workspace 结构 - -### 已提取的独立 Crate（13 个） - -| Crate | 路径 | 来源 | 测试 | 零耦合 | -|-------|------|------|------|--------| -| `devbase-core-types` | `crates/devbase-core-types` | `src/core/node.rs` | 3 | ✅ | -| `devbase-symbol-links` | `crates/devbase-symbol-links` | `src/symbol_links.rs` | 4 | ✅ | -| `devbase-sync-protocol` | `crates/devbase-sync-protocol` | `src/sync_protocol.rs` | 12 | ✅ | -| `devbase-syncthing-client` | `crates/devbase-syncthing-client` | `src/syncthing_client.rs` | 2 | ✅ | -| `devbase-vault-frontmatter` | `crates/devbase-vault-frontmatter` | `src/vault/frontmatter.rs` | 5 | ✅ | -| `devbase-vault-wikilink` | `crates/devbase-vault-wikilink` | `src/vault/wikilink.rs` | 5 | ✅ | -| `devbase-workflow-interpolate` | `crates/devbase-workflow-interpolate` | `src/workflow/interpolate.rs` | 9 | ✅ | -| `devbase-workflow-model` | `crates/devbase-workflow-model` | `src/workflow/model.rs` | 2 | ✅ | -| `devbase-registry-health` | `crates/devbase-registry-health` | `src/registry/health.rs` | 3 | ✅ | -| `devbase-registry-metrics` | `crates/devbase-registry-metrics` | `src/registry/metrics.rs` | 4 | ✅ | -| `devbase-registry-workspace` | `crates/devbase-registry-workspace` | `src/registry/workspace.rs` | 5 | ✅ | -| `devbase-embedding` | `crates/devbase-embedding` | `src/embedding.rs` | 5 | ✅ | -| `devbase-skill-runtime-types` | `crates/devbase-skill-runtime-types` | `src/skill_runtime/mod.rs` | 7 | ✅ | -| `devbase-skill-runtime-parser` | `crates/devbase-skill-runtime-parser` | `src/skill_runtime/parser.rs` | 3 | ✅ | -| `devbase-registry-entity` | `crates/devbase-registry-entity` | `src/registry/entity.rs` | 3 | ✅ | -| `devbase-registry-relation` | `crates/devbase-registry-relation` | `src/registry/relation.rs` | 1 | ✅ | -| `devbase-registry-call-graph` | `crates/devbase-registry-call-graph` | `src/registry/call_graph.rs` | 0 | ✅ | -| `devbase-registry-dead-code` | `crates/devbase-registry-dead-code` | `src/registry/dead_code.rs` | 0 | ✅ | -| `devbase-registry-code-symbols` | `crates/devbase-registry-code-symbols` | `src/registry/code_symbols.rs` | 0 | ✅ | - -### 向后兼容机制 - -每个已提取模块的原文件保持为 **纯 re-export 桥接**： - -```rust -// src/workflow/interpolate.rs — RE-EXPORT ONLY -pub use devbase_workflow_interpolate::*; -``` - -> **禁止**在这些 re-export 文件中添加任何新代码。如需修改，直接编辑 `crates/*/src/lib.rs`。 - ---- - -## 三、关键调试备忘 - -### Windows Debug Build 栈溢出（已知问题，已缓解） - -**症状**：`cargo run` 或 `cargo test` 在 debug profile 下崩溃，`STATUS_STACK_OVERFLOW` (`0xc00000fd`)。 - -**根因**：clap v4 `Subcommand` derive 宏为大型枚举（变体≥7）生成深层递归展开代码，Windows 默认 1MB 栈空间不足。release build 正常。 - -**缓解**：`Cargo.toml` 中已配置 `[profile.dev] opt-level = 1`，使 LLVM 内联/优化掉部分栈帧。 - -**诊断**： -```powershell -# 二分法定位：逐次在 main.rs 中删减 SkillCommands/VaultCommands 变体 -# 确认阈值在 6→7 变体之间 -cargo run -- # 若仍溢出，尝试 cargo run --release -``` - -### Windows Tantivy Flaky（已根治） - -**症状**：测试偶发 `PermissionDenied`（Tantivy mmap 文件句柄未释放）。 - -**根因**：Windows 下 `Index` / `IndexWriter` drop 后 OS 未立即释放文件句柄。 - -**修复**：测试代码中显式 `drop(index)` + `drop(writer)` + `Start-Sleep -Milliseconds 50`。 - -### Integration Test 残余失败（预先存在，与提取无关） - -``` -test_sync_skips_unmanaged_repo # 预期"没有处理任何仓库"，实际有输出 -test_tag_enables_sync # 同上 -``` - -**处理**：单独运行通过；不影响 crate 提取验收标准。 - ---- - -## 四、Crate 提取标准作业程序（SOP） - -若任务涉及提取新 workspace crate，按以下流程执行： - -### 前置检查 - -```powershell -# 1. 确认目标模块零耦合（≤3 个 crate:: refs） -Select-String -Path "src/.rs" -Pattern "crate::" -NoEmphasis - -# 2. 确认无外部 devbase 路径引用 -grep "devbase" src/.rs # 应为空（除 re-export 文件） -``` - -### 提取步骤 - -1. **创建 crate 目录**：`crates/devbase-/` -2. **编写 `Cargo.toml`**： - - `version = "0.15.0"`（与现有 workspace crate 一致） - - `edition = "2024"` - - 仅声明**直接使用的**外部依赖（serde, regex, anyhow 等） - - **禁止**引用 `devbase` 主 crate 或任何 `path = "../..."` 的内部路径 -3. **迁移实现**：将 `src/.rs` 内容完整复制到 `crates/devbase-/src/lib.rs` -4. **修正导入**：所有 `use crate::` 改为 `use crate::`（lib.rs 内部）或删除未使用的导入 -5. **迁移测试**：将 `#[cfg(test)] mod tests { ... }` 一并迁移 -6. **注册 workspace**： - - 根 `Cargo.toml` `[dependencies]` 添加 `devbase- = { path = "crates/devbase-" }` - - 根 `Cargo.toml` `[workspace] members = ["crates/*"]` 已通配，无需手动添加 -7. **创建 re-export 桥接**：原文件替换为 `pub use devbase_::*;` -8. **验证**： - ```powershell - cargo check --workspace - cargo test --workspace --lib - ``` - -### 验收标准 - -- [ ] `cargo check --workspace` 0 errors -- [ ] `cargo test --workspace --lib` 全绿 -- [ ] 新 crate 内部 0 个 `crate::` 引用（指向 devbase 主库） -- [ ] 原 `src/` 文件仅含 re-export，无业务逻辑 -- [ ] 新 crate 不依赖 `devbase` 主 crate - ---- - -## 五、核心文档导航 - -| 文档 | 用途 | 何时读取 | -|------|------|---------| -| [`AGENTS.md`](../../AGENTS.md) | 架构红线、安全原则、历史决策 | 每次会话启动 | -| [`docs/ai-protocol.md`](../ai-protocol.md) | 架构快照、待办、耦合地图 | 每次架构变更后 | -| [`docs/ROADMAP.md`](../ROADMAP.md) | 路线图、版本规划、技术债 | 需要了解长期计划时 | -| [`docs/architecture/overview.md`](../architecture/overview.md) | 系统架构图、模块关系 | 新功能设计时 | -| [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | 开发规范、Schema 迁移指南 | 提交 PR 前 | -| [`Cargo.toml`](../../Cargo.toml) | 依赖、workspace 成员、features | 依赖变更时 | - ---- - -## 六、当前活跃任务（v0.16.0 P2） - -**目标**：继续提取剩余 🟢 健康模块为独立 crate。 - -| 候选模块 | 行数 | 测试 | 内部耦合 | 状态 | -|----------|------|------|----------|------| -| ~~`registry/health`~~ | ~~156~~ | ~~3~~ | ~~0~~ | ~~✅ 已完成~~ | -| ~~`registry/metrics`~~ | ~~153~~ | ~~4~~ | ~~0~~ | ~~✅ 已完成~~ | -| ~~`registry/workspace`~~ | ~~215~~ | ~~5~~ | ~~0~~ | ~~✅ 已完成~~ | -| ~~`workflow/model`~~ | ~~330~~ | ~~2~~ | ~~0~~ | ~~✅ 已完成~~ | -| ~~`embedding`~~ | ~~299~~ | ~~5~~ | ~~0~~ | ~~✅ 已完成~~ | -| ~~`skill_runtime/parser`~~ | ~~417~~ | ~~3~~ | ~~0~~ | ~~✅ 已完成~~ | - -> P2 全部候选提取完成。下一步：v0.16.0 P1 MCP trait 化收尾，或 v0.17 `migrate.rs` 拆分。 - -**阻塞项**： -- ~~`migrate.rs` 拆分~~ → ✅ 已完成（实际 487 行，迁移已拆分至 `migrations/` 29 个独立文件） -- MCP trait 化 → `mcp/tools/repo.rs` 仍有 13 个 `crate::` 引用（从 41 降下，ai-protocol 数据已过时） - ---- - -## 七、环境特定信息（Windows） - -- **Shell**：Windows PowerShell（`C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe`） -- **Rust**：1.94.1 -- **工作目录**：`C:\Users\22414\dev\third_party\devbase` -- **Git 用户**：`juice094 <160722440+juice094@users.noreply.github.com>` -- **编译优化**：debug profile 强制 `opt-level = 1`（缓解 Windows clap derive 栈溢出） - ---- - -*本文档应与 `AGENTS.md`、`docs/ai-protocol.md` 一并阅读。如有冲突，以 `AGENTS.md` 为准。* +# AI 实例上下文交接指南 + +> 本文档面向**后续接入 devbase 项目的 AI Agent 实例**（Claw / CLI / Web 架构）。 +> 目标：在上下文压缩或会话切换后，新 AI 实例能在 60 秒内恢复有效工作上下文。 + +--- + +## 一、项目速览（30 秒） + +| 属性 | 值 | +|------|-----| +| **名称** | devbase — 本地优先的 AI Skill 编排基础设施 | +| **技术栈** | Rust 2024, SQLite, tokio, ratatui, git2, tantivy, tree-sitter | +| **当前版本** | v0.16.0-dev (`main@93b0860`) | +| **测试** | 450 passed / 0 failed / 5 ignored（`cargo test --workspace --lib`） | +| **编译** | `cargo check --workspace` 0 errors；clippy 0 warnings | +| **仓库** | `https://github.com/juice094/devbase` | + +### 快速自检（每次恢复上下文后执行） + +```powershell +# 1. 确认编译健康 +cd C:\Users\22414\dev\third_party\devbase +cargo check --workspace 2>&1 | Select-Object -Last 3 + +# 2. 确认测试全绿 +cargo test --workspace --lib 2>&1 | Select-String "test result" + +# 3. 确认 workspace 成员 +cargo metadata --format-version 1 --no-deps 2>$null | ConvertFrom-Json | Select-Object -ExpandProperty workspace_members + +# 4. 快速耦合扫描（Windows PowerShell） +Get-ChildItem src\*.rs | ForEach-Object { $count = (Select-String -Path $_.FullName -Pattern "crate::" -NoEmphasis).Count; "$($_.Name): $count refs" } | Sort-Object { [int]($_ -replace '.*: ', '' -replace ' refs', '') } | Select-Object -Last 10 +``` + +--- + +## 二、Workspace 结构 + +### 已提取的独立 Crate（13 个） + +| Crate | 路径 | 来源 | 测试 | 零耦合 | +|-------|------|------|------|--------| +| `devbase-core-types` | `crates/devbase-core-types` | `src/core/node.rs` | 3 | ✅ | +| `devbase-symbol-links` | `crates/devbase-symbol-links` | `src/symbol_links.rs` | 4 | ✅ | +| `devbase-sync-protocol` | `crates/devbase-sync-protocol` | `src/sync_protocol.rs` | 12 | ✅ | +| `devbase-syncthing-client` | `crates/devbase-syncthing-client` | `src/syncthing_client.rs` | 2 | ✅ | +| `devbase-vault-frontmatter` | `crates/devbase-vault-frontmatter` | `src/vault/frontmatter.rs` | 5 | ✅ | +| `devbase-vault-wikilink` | `crates/devbase-vault-wikilink` | `src/vault/wikilink.rs` | 5 | ✅ | +| `devbase-workflow-interpolate` | `crates/devbase-workflow-interpolate` | `src/workflow/interpolate.rs` | 9 | ✅ | +| `devbase-workflow-model` | `crates/devbase-workflow-model` | `src/workflow/model.rs` | 2 | ✅ | +| `devbase-registry-health` | `crates/devbase-registry-health` | `src/registry/health.rs` | 3 | ✅ | +| `devbase-registry-metrics` | `crates/devbase-registry-metrics` | `src/registry/metrics.rs` | 4 | ✅ | +| `devbase-registry-workspace` | `crates/devbase-registry-workspace` | `src/registry/workspace.rs` | 5 | ✅ | +| `devbase-embedding` | `crates/devbase-embedding` | `src/embedding.rs` | 5 | ✅ | +| `devbase-skill-runtime-types` | `crates/devbase-skill-runtime-types` | `src/skill_runtime/mod.rs` | 7 | ✅ | +| `devbase-skill-runtime-parser` | `crates/devbase-skill-runtime-parser` | `src/skill_runtime/parser.rs` | 3 | ✅ | +| `devbase-registry-entity` | `crates/devbase-registry-entity` | `src/registry/entity.rs` | 3 | ✅ | +| `devbase-registry-relation` | `crates/devbase-registry-relation` | `src/registry/relation.rs` | 1 | ✅ | +| `devbase-registry-call-graph` | `crates/devbase-registry-call-graph` | `src/registry/call_graph.rs` | 0 | ✅ | +| `devbase-registry-dead-code` | `crates/devbase-registry-dead-code` | `src/registry/dead_code.rs` | 0 | ✅ | +| `devbase-registry-code-symbols` | `crates/devbase-registry-code-symbols` | `src/registry/code_symbols.rs` | 0 | ✅ | + +### 向后兼容机制 + +每个已提取模块的原文件保持为 **纯 re-export 桥接**： + +```rust +// src/workflow/interpolate.rs — RE-EXPORT ONLY +pub use devbase_workflow_interpolate::*; +``` + +> **禁止**在这些 re-export 文件中添加任何新代码。如需修改，直接编辑 `crates/*/src/lib.rs`。 + +--- + +## 三、关键调试备忘 + +### Windows Debug Build 栈溢出（已知问题，已缓解） + +**症状**：`cargo run` 或 `cargo test` 在 debug profile 下崩溃，`STATUS_STACK_OVERFLOW` (`0xc00000fd`)。 + +**根因**：clap v4 `Subcommand` derive 宏为大型枚举（变体≥7）生成深层递归展开代码，Windows 默认 1MB 栈空间不足。release build 正常。 + +**缓解**：`Cargo.toml` 中已配置 `[profile.dev] opt-level = 1`，使 LLVM 内联/优化掉部分栈帧。 + +**诊断**： +```powershell +# 二分法定位：逐次在 main.rs 中删减 SkillCommands/VaultCommands 变体 +# 确认阈值在 6→7 变体之间 +cargo run -- # 若仍溢出，尝试 cargo run --release +``` + +### Windows Tantivy Flaky（已根治） + +**症状**：测试偶发 `PermissionDenied`（Tantivy mmap 文件句柄未释放）。 + +**根因**：Windows 下 `Index` / `IndexWriter` drop 后 OS 未立即释放文件句柄。 + +**修复**：测试代码中显式 `drop(index)` + `drop(writer)` + `Start-Sleep -Milliseconds 50`。 + +### Integration Test 残余失败（预先存在，与提取无关） + +``` +test_sync_skips_unmanaged_repo # 预期"没有处理任何仓库"，实际有输出 +test_tag_enables_sync # 同上 +``` + +**处理**：单独运行通过；不影响 crate 提取验收标准。 + +--- + +## 四、Crate 提取标准作业程序（SOP） + +若任务涉及提取新 workspace crate，按以下流程执行： + +### 前置检查 + +```powershell +# 1. 确认目标模块零耦合（≤3 个 crate:: refs） +Select-String -Path "src/.rs" -Pattern "crate::" -NoEmphasis + +# 2. 确认无外部 devbase 路径引用 +grep "devbase" src/.rs # 应为空（除 re-export 文件） +``` + +### 提取步骤 + +1. **创建 crate 目录**：`crates/devbase-/` +2. **编写 `Cargo.toml`**： + - `version = "0.15.0"`（与现有 workspace crate 一致） + - `edition = "2024"` + - 仅声明**直接使用的**外部依赖（serde, regex, anyhow 等） + - **禁止**引用 `devbase` 主 crate 或任何 `path = "../..."` 的内部路径 +3. **迁移实现**：将 `src/.rs` 内容完整复制到 `crates/devbase-/src/lib.rs` +4. **修正导入**：所有 `use crate::` 改为 `use crate::`（lib.rs 内部）或删除未使用的导入 +5. **迁移测试**：将 `#[cfg(test)] mod tests { ... }` 一并迁移 +6. **注册 workspace**： + - 根 `Cargo.toml` `[dependencies]` 添加 `devbase- = { path = "crates/devbase-" }` + - 根 `Cargo.toml` `[workspace] members = ["crates/*"]` 已通配，无需手动添加 +7. **创建 re-export 桥接**：原文件替换为 `pub use devbase_::*;` +8. **验证**： + ```powershell + cargo check --workspace + cargo test --workspace --lib + ``` + +### 验收标准 + +- [ ] `cargo check --workspace` 0 errors +- [ ] `cargo test --workspace --lib` 全绿 +- [ ] 新 crate 内部 0 个 `crate::` 引用（指向 devbase 主库） +- [ ] 原 `src/` 文件仅含 re-export，无业务逻辑 +- [ ] 新 crate 不依赖 `devbase` 主 crate + +--- + +## 五、核心文档导航 + +| 文档 | 用途 | 何时读取 | +|------|------|---------| +| [`AGENTS.md`](../../AGENTS.md) | 架构红线、安全原则、历史决策 | 每次会话启动 | +| [`docs/ai-protocol.md`](../ai-protocol.md) | 架构快照、待办、耦合地图 | 每次架构变更后 | +| [`docs/ROADMAP.md`](../ROADMAP.md) | 路线图、版本规划、技术债 | 需要了解长期计划时 | +| [`.knowledge/architecture/three-layer-model.md`](../../.knowledge/architecture/three-layer-model.md) | 三层架构与数据流 | 新功能设计时 | +| [`.knowledge/architecture/dependency-topology.md`](../../.knowledge/architecture/dependency-topology.md) | 11-Tier 模块依赖拓扑 | 模块分层变更时 | +| [`CONTRIBUTING.md`](../../CONTRIBUTING.md) | 开发规范、Schema 迁移指南 | 提交 PR 前 | +| [`Cargo.toml`](../../Cargo.toml) | 依赖、workspace 成员、features | 依赖变更时 | + +--- + +## 六、当前活跃任务（v0.16.0 P2） + +**目标**：继续提取剩余 🟢 健康模块为独立 crate。 + +| 候选模块 | 行数 | 测试 | 内部耦合 | 状态 | +|----------|------|------|----------|------| +| ~~`registry/health`~~ | ~~156~~ | ~~3~~ | ~~0~~ | ~~✅ 已完成~~ | +| ~~`registry/metrics`~~ | ~~153~~ | ~~4~~ | ~~0~~ | ~~✅ 已完成~~ | +| ~~`registry/workspace`~~ | ~~215~~ | ~~5~~ | ~~0~~ | ~~✅ 已完成~~ | +| ~~`workflow/model`~~ | ~~330~~ | ~~2~~ | ~~0~~ | ~~✅ 已完成~~ | +| ~~`embedding`~~ | ~~299~~ | ~~5~~ | ~~0~~ | ~~✅ 已完成~~ | +| ~~`skill_runtime/parser`~~ | ~~417~~ | ~~3~~ | ~~0~~ | ~~✅ 已完成~~ | + +> P2 全部候选提取完成。下一步：v0.16.0 P1 MCP trait 化收尾，或 v0.17 `migrate.rs` 拆分。 + +**阻塞项**： +- ~~`migrate.rs` 拆分~~ → ✅ 已完成（实际 487 行，迁移已拆分至 `migrations/` 29 个独立文件） +- MCP trait 化 → `mcp/tools/repo.rs` 仍有 13 个 `crate::` 引用（从 41 降下，ai-protocol 数据已过时） + +--- + +## 七、环境特定信息（Windows） + +- **Shell**：Windows PowerShell（`C:\WINDOWS\System32\WindowsPowerShell\v1.0\powershell.exe`） +- **Rust**：1.94.1 +- **工作目录**：`C:\Users\22414\dev\third_party\devbase` +- **Git 用户**：`juice094 <160722440+juice094@users.noreply.github.com>` +- **编译优化**：debug profile 强制 `opt-level = 1`（缓解 Windows clap derive 栈溢出） + +--- + +*本文档应与 `AGENTS.md`、`docs/ai-protocol.md` 一并阅读。如有冲突，以 `AGENTS.md` 为准。* diff --git a/docs/reference/entities-model.md b/docs/reference/entities-model.md index 465ad34..c4e94bb 100644 --- a/docs/reference/entities-model.md +++ b/docs/reference/entities-model.md @@ -1,157 +1,158 @@ -# 统一实体模型 - -> **引入版本**：Schema v16 -> **核心表**：`entity_types` + `entities` + `relations` -> **目标**：用三张表替代此前分散的 `repos`/`vault_notes`/`papers`/`workflows` 等独立表，实现概念统一、查询统一、扩展统一。 - ---- - -## 设计动机 - -旧 schema 中每新增一个概念就要新增一张表： - -```sql --- 旧方式（v15 及之前） -CREATE TABLE repos (...); -CREATE TABLE vault_notes (...); -CREATE TABLE papers (...); -CREATE TABLE workflows (...); --- 新增 Memory？→ 再加 CREATE TABLE memories (...) -``` - -问题： -- **查询碎片化**：查 repo 用 `SELECT * FROM repos`，查 paper 用 `SELECT * FROM papers`，无法统一过滤 -- **关系无法通用**：repo 依赖 repo、paper 引用 paper、note 链接 repo —— 每种关系都要单独建表 -- **扩展成本高**：新增概念需要改 schema + 写 migration + 改 DAO 层 - -新方式（v16+）： - -```sql --- 所有对象统一存储 -CREATE TABLE entities ( - id TEXT PRIMARY KEY, - entity_type TEXT NOT NULL, -- 'repo' | 'skill' | 'paper' | 'vault_note' | 'workflow' | 自定义 - name TEXT NOT NULL, - source_url TEXT, - local_path TEXT, - metadata TEXT, -- JSON，动态字段由 entity_type.schema_json 定义 - ... -); - --- 所有关系统一存储 -CREATE TABLE relations ( - from_entity_id TEXT NOT NULL, - to_entity_id TEXT NOT NULL, - relation_type TEXT NOT NULL, -- 'depends_on' | 'inspired_by' | 'links_to' | 自定义 - confidence REAL DEFAULT 1.0, - ... -); -``` - ---- - -## 核心查询模式 - -### 1. 按类型列出实体 - -```sql -SELECT e.id, e.name, e.local_path, json_extract(e.metadata, '$.language') -FROM entities e -WHERE e.entity_type = 'repo' -ORDER BY e.name; -``` - -### 2. 获取实体的完整元数据 - -```sql -SELECT e.id, e.name, e.metadata -FROM entities e -WHERE e.id = 'devbase'; --- metadata: {"language":"Rust","workspace_type":"git","stars":42,...} -``` - -### 3. 获取实体的关联对象 - -```sql --- 获取与 devbase 相关的所有 vault notes -SELECT e.id, e.name -FROM entities e -JOIN relations r ON e.id = r.to_entity_id -WHERE r.from_entity_id = 'devbase' - AND r.relation_type = 'has_note' - AND e.entity_type = 'vault_note'; -``` - -### 4. 反向链接（谁引用了我） - -```sql --- 哪些 repo 依赖 devbase？ -SELECT e.id, e.name -FROM entities e -JOIN relations r ON e.id = r.from_entity_id -WHERE r.to_entity_id = 'devbase' - AND r.relation_type = 'depends_on'; -``` - -### 5. 标签过滤 + 全文搜索 - -```sql --- 查找 tag 含 "rust" 的 repo -SELECT e.id, e.name -FROM entities e -JOIN repo_tags t ON e.id = t.repo_id -WHERE e.entity_type = 'repo' - AND t.tag = 'rust'; -``` - ---- - -## 双轨制过渡期（v16–v22） - -v16 引入 `entities` 表后，`repos` 表仍存在了一段时间（dual-write → read-switch → drop）： - -| 阶段 | 写入 | 读取 | 时间 | -|------|------|------|------| -| Dual-write | `repos` + `entities` | `repos` | v16–v20 | -| Read-switch | `entities` | `entities` | v20–v21 | -| Drop legacy | `entities` only | `entities` | v21+ | - -v21 正式 `DROP TABLE repos`，所有关联表的 FK 约束也一并移除。 - ---- - -## 扩展自定义实体类型 - -```sql --- 1. 定义新类型 -INSERT INTO entity_types (name, schema_json, description, created_at) -VALUES ( - 'dataset', - '{"fields":[{"name":"format","type":"string"},{"name":"size_bytes","type":"integer"}]}', - 'Machine learning dataset', - '2026-04-30T00:00:00Z' -); - --- 2. 插入实例 -INSERT INTO entities (id, entity_type, name, local_path, metadata, created_at, updated_at) -VALUES ( - 'imagenet-1k', - 'dataset', - 'ImageNet 1K', - '/data/imagenet', - '{"format":"folder","size_bytes":150000000000}', - '2026-04-30T00:00:00Z', - '2026-04-30T00:00:00Z' -); - --- 3. 建立关系（dataset 被 paper 引用） -INSERT INTO relations (id, from_entity_id, to_entity_id, relation_type, created_at) -VALUES ('r1', 'paper-resnet', 'imagenet-1k', 'uses', '2026-04-30T00:00:00Z'); -``` - ---- - -## 相关文档 - -- [`schema-v23.md`](schema-v23.md) — 完整数据库表结构 -- [`context-compiler.md`](../architecture/context-compiler.md) — 情境编译器架构定义 +# 统一实体模型 + +> **引入版本**：Schema v16 +> **核心表**：`entity_types` + `entities` + `relations` +> **目标**：用三张表替代此前分散的 `repos`/`vault_notes`/`papers`/`workflows` 等独立表，实现概念统一、查询统一、扩展统一。 + +--- + +## 设计动机 + +旧 schema 中每新增一个概念就要新增一张表： + +```sql +-- 旧方式（v15 及之前） +CREATE TABLE repos (...); +CREATE TABLE vault_notes (...); +CREATE TABLE papers (...); +CREATE TABLE workflows (...); +-- 新增 Memory？→ 再加 CREATE TABLE memories (...) +``` + +问题： +- **查询碎片化**：查 repo 用 `SELECT * FROM repos`，查 paper 用 `SELECT * FROM papers`，无法统一过滤 +- **关系无法通用**：repo 依赖 repo、paper 引用 paper、note 链接 repo —— 每种关系都要单独建表 +- **扩展成本高**：新增概念需要改 schema + 写 migration + 改 DAO 层 + +新方式（v16+）： + +```sql +-- 所有对象统一存储 +CREATE TABLE entities ( + id TEXT PRIMARY KEY, + entity_type TEXT NOT NULL, -- 'repo' | 'skill' | 'paper' | 'vault_note' | 'workflow' | 自定义 + name TEXT NOT NULL, + source_url TEXT, + local_path TEXT, + metadata TEXT, -- JSON，动态字段由 entity_type.schema_json 定义 + ... +); + +-- 所有关系统一存储 +CREATE TABLE relations ( + from_entity_id TEXT NOT NULL, + to_entity_id TEXT NOT NULL, + relation_type TEXT NOT NULL, -- 'depends_on' | 'inspired_by' | 'links_to' | 自定义 + confidence REAL DEFAULT 1.0, + ... +); +``` + +--- + +## 核心查询模式 + +### 1. 按类型列出实体 + +```sql +SELECT e.id, e.name, e.local_path, json_extract(e.metadata, '$.language') +FROM entities e +WHERE e.entity_type = 'repo' +ORDER BY e.name; +``` + +### 2. 获取实体的完整元数据 + +```sql +SELECT e.id, e.name, e.metadata +FROM entities e +WHERE e.id = 'devbase'; +-- metadata: {"language":"Rust","workspace_type":"git","stars":42,...} +``` + +### 3. 获取实体的关联对象 + +```sql +-- 获取与 devbase 相关的所有 vault notes +SELECT e.id, e.name +FROM entities e +JOIN relations r ON e.id = r.to_entity_id +WHERE r.from_entity_id = 'devbase' + AND r.relation_type = 'has_note' + AND e.entity_type = 'vault_note'; +``` + +### 4. 反向链接（谁引用了我） + +```sql +-- 哪些 repo 依赖 devbase？ +SELECT e.id, e.name +FROM entities e +JOIN relations r ON e.id = r.from_entity_id +WHERE r.to_entity_id = 'devbase' + AND r.relation_type = 'depends_on'; +``` + +### 5. 标签过滤 + 全文搜索 + +```sql +-- 查找 tag 含 "rust" 的 repo +SELECT e.id, e.name +FROM entities e +JOIN repo_tags t ON e.id = t.repo_id +WHERE e.entity_type = 'repo' + AND t.tag = 'rust'; +``` + +--- + +## 双轨制过渡期（v16–v22） + +v16 引入 `entities` 表后，`repos` 表仍存在了一段时间（dual-write → read-switch → drop）： + +| 阶段 | 写入 | 读取 | 时间 | +|------|------|------|------| +| Dual-write | `repos` + `entities` | `repos` | v16–v20 | +| Read-switch | `entities` | `entities` | v20–v21 | +| Drop legacy | `entities` only | `entities` | v21+ | + +v21 正式 `DROP TABLE repos`，所有关联表的 FK 约束也一并移除。 + +--- + +## 扩展自定义实体类型 + +```sql +-- 1. 定义新类型 +INSERT INTO entity_types (name, schema_json, description, created_at) +VALUES ( + 'dataset', + '{"fields":[{"name":"format","type":"string"},{"name":"size_bytes","type":"integer"}]}', + 'Machine learning dataset', + '2026-04-30T00:00:00Z' +); + +-- 2. 插入实例 +INSERT INTO entities (id, entity_type, name, local_path, metadata, created_at, updated_at) +VALUES ( + 'imagenet-1k', + 'dataset', + 'ImageNet 1K', + '/data/imagenet', + '{"format":"folder","size_bytes":150000000000}', + '2026-04-30T00:00:00Z', + '2026-04-30T00:00:00Z' +); + +-- 3. 建立关系（dataset 被 paper 引用） +INSERT INTO relations (id, from_entity_id, to_entity_id, relation_type, created_at) +VALUES ('r1', 'paper-resnet', 'imagenet-1k', 'uses', '2026-04-30T00:00:00Z'); +``` + +--- + +## 相关文档 + +- [`schema-v23.md`](schema-v23.md) — 完整数据库表结构 +- [`.knowledge/architecture/three-layer-model.md`](../../.knowledge/architecture/three-layer-model.md) — 三层架构模型 +- [`.knowledge/architecture/project-worktree.md`](../../.knowledge/architecture/project-worktree.md) — 项目模块与工作树速查