docs: align AGENTS.md/CLAUDE.md with OKF bundle and archive legacy architecture docs

.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. **所有状态变更操作必须幂等**。

.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）。

.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。