docs(claude): add project-level CLAUDE.md cognitive anchor

.claude/CLAUDE.md

@@ -0,0 +1,93 @@
+# devbase — Cognitive Anchor
+
+> **Purpose**: This file is designed to survive context compression. It contains
+> immutable facts and current state that every AI session must know before
+> working on this project. If you are reading this after a context reset,
+> treat this as your primary source of truth.
+
+---
+
+## Immutable Facts（不可变事实）
+
+| ID | Fact | Source | Status |
+|----|------|--------|--------|
+| F-001 | Version | `Cargo.toml` | **v0.20.1** |
+| F-002 | Edition | `Cargo.toml` | **Rust 2024** |
+| F-003 | Test Coverage | CI | **491+ passed, 0 failed, 5 ignored** |
+| F-004 | Production Unwrap | Architecture Invariants | **0** (G5 rule enforced) |
+| F-005 | MCP Tools | `src/mcp/mod.rs` | **69** (5 Stable / 60 Beta / 4 Experimental) |
+| F-006 | Schema Version | `registry/migrate.rs` | **v34** |
+| F-007 | Entities Table | Schema v21+ | **唯一真相源** (`repos` 表已删除) |
+| F-008 | SQLite Mode | `storage.rs` | **WAL mode** |
+| F-009 | Clippy | CI | **`-D warnings` 全绿** |
+| F-010 | Release Assets | GitHub Releases | **Linux + Windows x64** 预编译二进制 |
+
+## 架构红线（Architecture Guardrails）
+
+- **RF-1**: 无裸 `init_db()` 调用，全部使用 `StorageBackend` 注入
+- **RF-2**: `TempStorageBackend` 用于测试隔离（禁止 `DEVBASE_DATA_DIR` 竞态）
+- **RF-3**: `entities` 表是唯一真相源
+- **RF-4**: 二进制上下文 ≤ 1MB
+- **RF-5**: 模块间无循环依赖
+- **RF-6**: 生产代码零 `unwrap`/`expect`/`panic`（测试除外）
+- **RF-7**: 路径输出必须脱敏（`sanitize_path()` 掩码 home 目录）
+
+## 当前上下文（Current Context）
+
+| 属性 | 值 |
+|------|-----|
+| 默认分支 | `main` |
+| 最新 Release | `v0.20.1` (2026-05-17) |
+| 当前 Phase | Phase 1 Production Hardening ✅ 完成 |
+| 下一 Phase | Phase 12 — v0.21.0 "External Capability Grafting" |
+| 活跃 PR | 无（PR #55 已合并） |
+
+## 已知架构 Gaps（不可与 Immutable Facts 混淆）
+
+这些是**待实现**的能力，不是 bug：
+
+| Gap | 影响 | 计划版本 | 状态 |
+|-----|------|----------|------|
+| ~~`relations` 表零生产读取路径~~ | ~~统一实体模型的图遍历能力未暴露~~ | ~~v0.21.0~~ | **已完成** — `devkit_relation_store/query/delete` 已存在，`project_context` 已读取 |
+| ~~Workflow 引擎零 MCP 暴露~~ | ~~AI 无法发现/触发工作流~~ | ~~v0.21.0~~ | **已完成** — `devkit_workflow_list/run/status` 已存在 |
+| ~~`project_context` 不完整~~ | ~~缺少 relations/limits/skills/workflows~~ | ~~v0.21.0~~ | **已完成** — 已补充 `known_limits` + `skills` |
+| 31/68 MCP 工具缺少调用测试 | 回归风险 | v0.21.0 | 待评估 |
+| ~~`mcp/tools/repo.rs` 2376 行~~ | ~~维护负担~~ | ~~v0.21.0~~ | **已完成** — 已拆分为 `tools/` 目录，`repo.rs` 现 730 行 |
+| ~~`init_db_at` 1214 行~~ | ~~迁移函数过大~~ | ~~v0.21.0~~ | **已完成** — 已拆分为 `registry/migrate.rs`（503 行）+ `repo.rs` + `vault.rs` + `links.rs` |
+
+## 防失忆校验清单（每次会话启动）
+
+- [ ] 已读取本文件（`devbase/.claude/CLAUDE.md`）
+- [ ] 已确认 `Cargo.toml` 版本与上表 F-001 一致
+- [ ] 如果 handoff 文档说"未完成"，确认是新环境问题还是全局阻塞
+- [ ] 如果修改 Schema，已更新 `registry/migrate.rs` 和 `SCHEMA_DDL`
+
+## 快速入口
+
+| 你想做什么 | 命令 |
+|-----------|------|
+| 运行测试 | `cargo test --all-targets` |
+| 检查 clippy | `cargo clippy --all-targets -D warnings` |
+| 检查格式化 | `cargo fmt --check` |
+| 运行 invariant checks | `scripts/invariant-checks/run-checks.ps1` |
+| 启动 MCP Server | `cargo run -- mcp` |
+| 启动 TUI | `cargo run -- tui` |
+| 扫描当前目录 | `devbase scan . --register` |
+| 索引仓库 | `devbase index` |
+
+## 关键文件映射
+
+| 概念 | 文件 |
+|------|------|
+| 架构决策 | `docs/architecture/` |
+| 稳定工具文档 | `docs/reference/stable-tools/` |
+| 快速开始 | `docs/guides/quickstart.md` |
+| MCP 集成指南 | `docs/guides/mcp-integration.md` |
+| 变更日志 | `CHANGELOG.md` |
+| Agent 简报 | `AGENTS.md` |
+| 贡献指南 | `CONTRIBUTING.md` |
+
+---
+
+**Last Updated**: 2026-05-20 by Claude Opus 4.7
+**Version**: v0.20.1

AGENTS.md

@@ -5,7 +5,7 @@
 > 它将本地数字资产的原始数据（代码库、笔记、Skill、工作流）编译为 AI 可决策的结构化情境，不负责思考，不负责执行，只负责感知、编码、持久化、检索。
 
 - **当前阶段**：阶段十一 — v0.20.0 已发布（知识完备性）
-- **当前版本**：v0.20.0（Schema 34，68 MCP tools，451 tests）
+- **当前版本**：v0.20.1（Schema 34，69 MCP tools，494 tests）
 - **已完成里程碑**：Registry God Object 完全拆解（10 子模块提取）+ 18 workspace crates 提取 + MCP Python SDK 1.16.0 兼容修复 + repo.rs trait 化 + flaky 测试根治（RF-2.1/2.2/2.3）+ 许可证迁移 + health 性能优化（-44%）+ index skip-embeddings + batch encoding 实验 + RF-6 清零 + 架构治理文档（ADR/不变量清单）+ Tantivy BM25 代码符号搜索（P1）+ AppContext 职责拆分 Phase 1/2（storage.rs 860→430 行）+ 架构不变量 CI（G5/T11/T12）+ Embedding 多后端（Candle/Ollama 配置切换, P3）+ EnvVersionCache 扩展（9 工具链检测, P4）+ **v0.16.0 Agent Contexts（P1/P2/P3）**：`agent_contexts`/`agent_memories`/`context_entity_links` Schema + 9 个 Session MCP tools + Context-aware Skill Runtime（`DEVBASE_ACTIVE_CONTEXT` 注入）+ **v0.16.1 Workflow-Session Binding**：`workflow_executions.context_id` + 执行自动绑定 Active Context + **v0.17.0 Embedding Externalization**：`embedding` 从 default features 移除（Candle/Ollama 降级为 opt-in `llm-backend`）+ Schema 34 向量存储 + `cosine_similarity` SQLite UDF + `devkit_session_recall` / `devkit_session_index`（60 tools）+ **v0.18.0 ClaudeCode Integration**：`devkit_project_brief`（Markdown 项目简报）+ `devkit_impact_analysis`（修改影响范围分析）+ `devkit_session_export` / `devkit_session_import` + `scripts/devbase-claude.ps1` 启动器（自动注入 `.claude/CLAUDE.md`）+ RFC `docs/RFC/claudecode-workflow-integration.md`（64 tools）+ **v0.18.0 发布收尾**：PR 合并 + 双平台二进制构建 + GitHub Release + 根目录治理 + 世界模型战略认知沉淀（Vault + AGENTS 双向联动）+ NotebookLM 生态消化（5 项目注册）+ GreptimeDB 互补分析 + **v0.19.0 知识基础设施硬化**：SQLite WAL 默认启用 + `devkit_index_health`（Beta）+ Vault 导出（`devkit_vault_export`）+ Redis ADR 决策（放弃引入）+ **v0.20.0 知识完备性**：Vault 双向链接 BFS 图遍历（`devkit_vault_graph` 扩展）+ Vault Git-based 历史追踪（`devkit_vault_history`，第 67 个 tool）+ 混合检索质量监控（`devkit_search_quality`，第 68 个 tool，`HybridSearchMetrics`）+ Block 引用支持（`WikiLink.anchor`：`[[note#heading]]` / `[[note#^block-id]]`）+ 性能回归基线（`#[ignore]` 1k/10k 阈值测试）+ 客户端无关原则（Client-Agnostic Principle）落地 + `skill sync` 泛化接口（零硬编码客户端路径）
 - **核心方向**：让 Kimi CLI 在调用文件工具之前，先通过 devbase 获得"该读哪些文件、为什么读、它们之间的关系"
 - **本质分析**：见 `vault/99-Meta/devbase-essence-analysis-20260430.md` 与 `docs/architecture/redefinition.md`
@@ -23,7 +23,7 @@ Skill Runtime 全生命周期已落地（含依赖管理 Schema v15），Schema
 - **Workspace**：`%LOCALAPPDATA%\devbase\workspace/` —— 文件系统 = source of truth
   - `vault/` —— PARA 结构：00-Inbox, 01-Projects, 02-Areas, 03-Resources, 04-Archives, 99-Meta
   - `assets/` —— 二进制资源
-- **MCP Server**：stdio only，**68 个 tools**（含 7 个 vault tools + 8 个代码分析工具 + 5 个 embedding/搜索工具 + 4 个 Skill Runtime tools + 3 个 Workflow/评分 tools + 1 个报告工具 + 1 个 arXiv 工具 + 2 个 KnownLimit tools + 3 个 Relation tools + 11 个 Agent Context tools + 2 个 ClaudeCode 集成工具 + 1 个 streaming index 工具 + 1 个 oplog 工具 + 1 个 Index Health 工具 + 1 个 Search Quality 工具 + 1 个 Evaluate 工具）；配置见 `mcp.json`
+- **MCP Server**：stdio only，**69 个 tools**（含 7 个 vault tools + 8 个代码分析工具 + 5 个 embedding/搜索工具 + 4 个 Skill Runtime tools + 3 个 Workflow/评分 tools + 1 个报告工具 + 1 个 arXiv 工具 + 2 个 KnownLimit tools + 3 个 Relation tools + 11 个 Agent Context tools + 2 个 ClaudeCode 集成工具 + 1 个 streaming index 工具 + 1 个 oplog 工具 + 1 个 Index Health 工具 + 1 个 Search Quality 工具 + 1 个 Evaluate 工具 + 1 个 DocumentConvert 工具）；配置见 `mcp.json`
 - **Kimi CLI 集成**：MCP server 已通过 `kimi mcp add` 注册，端到端验证通过（`kimi --print` 成功调用 `devkit_health`）；项目级 skill 位于 `.kimi/skills/devbase-project/SKILL.md`
 - **统一节点模型**：`core::node::{Node, NodeType, Edge}` —— GitRepo / VaultNote / Asset / ExternalLink
 - **当前测试**：451+ lib passed / 0 failed / 5 ignored + 11/11 integration passed（`tests/cli.rs`）

CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- `devkit_document_convert` — Experimental tier MCP tool，PDF/PPTX → Markdown 转换（`pdftotext` / `python-pptx` 流水线），含 frontmatter 质量标注
+- Stable 工具 invocation 测试补全：`devkit_query_repos`、`devkit_vault_search`、`devkit_vault_read`、`devkit_status`、`devkit_workflow_list`、`devkit_index`
+- `seed_repo()` 轻量测试 helper（仅插入 `entities` 表，无副作用）
+
+### Fixed
+
+- `mcp/tools/document_convert.rs` 原始字符串定界符修复（`r###"` 避免与 Python f-string `"##` 冲突）
+- `cleanup_extracted_text` 单元测试期望值与实现语义对齐（保留最多 2 个连续空行）
+
+### Changed
+
+- `KNOWN_ISSUES.md` 更新：document_convert 从 P3 债务移至已解决归档；测试计数 485→494
+- `docs/reference/mcp-tools.md` 修正为 69 个工具，补充 Index / Workflow / Relation / KnownLimit / Session 分类
+- `docs/reference/stable-tools/README.md` 修正为 5 个 Stable 工具（删除过时的 `project_brief.md` / `hybrid_search.md` / `session_recall.md`）
+
 ## [0.20.1] - 2026-05-17
 
 ### Added

KNOWN_ISSUES.md

@@ -0,0 +1,99 @@
+# Known Issues & Technical Debt
+
+> 本文件记录 devbase 的已知问题、技术债务和架构 blockers。
+> 不是 bug 列表 — 这些问题是设计层面的权衡或待完成的工作。
+
+---
+
+## P0 — 阻塞发布
+
+无当前 P0 blocker。v0.20.1 已发布，所有 P0 架构 gaps 已关闭。
+
+---
+
+## P1 — 测试覆盖
+
+### 28 个 MCP 工具缺少 invocation tests
+
+**现状**：68 个工具中，40 个有 dedicated `invoke()` 测试（+3 本批次新增），28 个仅有 name/schema smoke tests 或零覆盖。
+
+**影响**：Beta → Stable 的 promote 需要测试背书；无测试的工具在重构时存在回归风险。
+
+**缺失测试的工具清单**：
+
+| 工具 | Tier | 已有覆盖 |
+|------|------|----------|
+| `devkit_index` | Beta | 间接（scenario） |
+| `devkit_index_health` | Beta | 无 |
+| `devkit_index_stream` | Beta | 无 |
+| `devkit_status` | Beta | 无 |
+| `devkit_note` | Beta | 无 |
+| `devkit_digest` | Experimental | 无 |
+| `devkit_paper_index` | Experimental | 无 |
+| `devkit_semantic_search` | Beta | 间接（scenario） |
+| `devkit_embedding_store` | Beta | 无 |
+| `devkit_embedding_search` | Beta | 无 |
+| `devkit_cross_repo_search` | Beta | 间接（scenario） |
+| `devkit_related_symbols` | Experimental | 无 |
+| `devkit_search_quality` | Beta | 无 |
+| `devkit_impact_analysis` | Beta | 无 |
+| `devkit_project_brief` | Beta | 间接（scenario） |
+| `devkit_knowledge_report` | Beta | 间接（scenario） |
+| `devkit_session_*` × 13 | Beta/Exp | 部分 smoke |
+| `devkit_workflow_*` × 3 | Beta | 部分（workflow.rs 单元测试） |
+| `devkit_evaluate` | Beta | 无 |
+
+**建议**：按调用频率排序，优先为 Index、Status、Workflow、Session save/list 添加测试。
+
+---
+
+## P2 — 架构债务
+
+### `mcp/tools/repo.rs` 730 行
+
+**现状**：已从 2376 行拆至 730 行，但仍超过理想阈值（~300 行/模块）。
+
+**计划**：按 domain 拆分为 `repo_health.rs` + `repo_query.rs` + `repo_index.rs`。已有 `docs/architecture/split-plan.md`。
+
+### `src/mcp/mod.rs` 工具枚举集中化
+
+**现状**：`McpToolEnum` 是包含 68 个变体的 giant enum，`tier()` 方法是 200+ 行的 match 表达式。
+
+**影响**：新增工具需要修改 3 处（enum 定义、match arm、tier match），容易遗漏。
+
+**建议**：考虑使用宏或 derive 自动生成 `McpToolEnum` 和 `tier()`，减少 boilerplate。
+
+### Vault 笔记全文搜索性能
+
+**现状**：`devkit_vault_search` 在内存中对所有笔记做线性扫描 + 字符串匹配。
+
+**影响**：Vault 笔记数量 >1000 时，搜索延迟可能超过 1s。
+
+**建议**：为 Vault 内容建立 Tantivy 索引（复用现有 symbol_index 基础设施），或至少增加关键词索引表。
+
+---
+
+## P3 — 文档与可观测性
+
+### 性能基准缺失
+
+**现状**：Criterion 已列为 dev-dependency，但无实际 benchmark 套件。
+
+**建议**：为 Index、Query、VaultSearch 建立 Criterion benchmarks，记录基线到 CI 产物。
+
+## 已解决（归档）
+
+| 问题 | 解决版本 | Commit |
+|------|----------|--------|
+| `relations` 表零生产读取路径 | v0.20.1 | `devkit_relation_store/query/delete` + `project_context` 读取 |
+| Workflow 引擎零 MCP 暴露 | v0.20.1 | `devkit_workflow_list/run/status` |
+| `project_context` 不完整 | v0.20.1 | 补充 `known_limits` + `skills` |
+| `mcp/tools/repo.rs` 2376 行 | v0.20.1 | 拆分为 `tools/` 目录，repo.rs 730 行 |
+| `init_db_at` 1214 行 | v0.20.1 | 拆分为 `registry/migrate.rs`（503 行）+ 子模块 |
+| 工具数量文档不一致 | v0.20.1 | `mcp-tools.md` 全面更新至 68 个 |
+| 3 Stable 工具缺 invocation tests | v0.20.1 | `query_repos`, `vault_search`, `vault_read` 测试 added |
+| `devkit_document_convert` 工具缺失 | v0.21.0 | `src/mcp/tools/document_convert.rs` + MCP 注册 |
+
+---
+
+*Last updated: 2026-05-20*

README.md

@@ -1,7 +1,7 @@
 # devbase
 
 [![Version](https://img.shields.io/badge/version-v0.20.1-blue)](https://github.com/juice094/devbase/releases)
-[![Tests](https://img.shields.io/badge/tests-485%2B%20passed-brightgreen)](./AGENTS.md)
+[![Tests](https://img.shields.io/badge/tests-494%2B%20passed-brightgreen)](./AGENTS.md)
 [![Clippy](https://img.shields.io/badge/clippy-0%20warnings-green)](./AGENTS.md)
 [![License](https://img.shields.io/badge/license-AGPL--3.0-orange)](./LICENSE)
 [![Rust](https://img.shields.io/badge/rust-1.95%2B-9cf)](https://www.rust-lang.org)
@@ -28,7 +28,7 @@ devbase 是开发者的**世界模型编译器**。它将代码库、笔记、
 │  Interaction Layer  (人类与 AI 的接口)                          │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
 │  │  TUI 仪表盘   │  │ MCP Server   │  │ Workflow Engine      │  │
-│  │  (ratatui)    │  │ 68 Tools     │  │ YAML + 拓扑调度      │  │
+│  │  (ratatui)    │  │ 69 Tools     │  │ YAML + 拓扑调度      │  │
 │  └──────────────┘  └──────────────┘  └──────────────────────┘  │
 ├─────────────────────────────────────────────────────────────────┤
 │  Compilation Layer  (World Model Compiler Core)                 │
@@ -120,7 +120,7 @@ cd devbase && cargo install --path .
 - **VaultList**：Vault 笔记列表，支持 PARA 方法笔记的快速检索与阅读
 - **Session**：Agent 会话列表（● active / ◌ archived），选中后右侧面板展示该上下文的语义记忆（◆ decision ▪ constraint ★ discovery ✗ error）
 
-### AI Layer — 68 个 MCP Tools
+### AI Layer — 69 个 MCP Tools
 
 基于 [Model Context Protocol](https://modelcontextprotocol.io) 标准化接口，stdio 本地进程通信。
 
@@ -382,6 +382,7 @@ TUI `[:]` 触发 embedding 语义搜索，失败自动降级为文本搜索。AI
 | **v0.18.0** | **✅ 已发布** | **ClaudeCode 工作流集成：`project_brief` + `impact_analysis` MCP Tools + Session 导出/导入 + `devbase-claude.ps1` 一键启动器；64 Tools 完整矩阵** |
 | v0.19.0 | ✅ 已发布 | **知识基础设施硬化**：SQLite WAL + Tantivy 健康评分 + Vault 导出 + Redis ADR 决策 |
 | v0.20.0 | ✅ 已发布 | 知识完备性：双向链接图遍历 + 笔记历史追踪 + 混合检索质量监控 + block 引用 + 性能回归基线 + 客户端无关原则；68 Tools |
+| v0.20.1 | ✅ 已发布 | Phase 1 Production Hardening：Workflow E2E 测试 + RF-7 路径脱敏 + Tantivy 一致性修复 + TempStorageBackend + 架构不变量 CI；Stable 工具 invocation 测试补全；69 Tools |
 | **v0.20.1** | **✅ 当前** | **Phase 1 生产硬化**：workflow E2E 测试、RF-7 路径隐私脱敏、Tantivy 一致性修复、性能回归基线、Architecture Invariants CI |
 
 ---