feat: v0.18.0 ClaudeCode workflow integration

AGENTS.md

@@ -4,9 +4,9 @@
 
 > 它将本地数字资产的原始数据（代码库、笔记、Skill、工作流）编译为 AI 可决策的结构化情境，不负责思考，不负责执行，只负责感知、编码、持久化、检索。
 
-- **当前阶段**：阶段八 → v0.17.0-dev 进行中（Agent Memory 向量存储 / Embedding 职责外迁）
-- **当前版本**：v0.17.0-dev（Schema 34，60 MCP tools，442 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-dev 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 工作流深度集成）
+- **当前版本**：v0.18.0-dev（Schema 34，64 MCP tools，446 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-dev 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）
 - **核心方向**：让 Kimi CLI 在调用文件工具之前，先通过 devbase 获得"该读哪些文件、为什么读、它们之间的关系"
 - **本质分析**：见 `vault/99-Meta/devbase-essence-analysis-20260430.md` 与 `docs/architecture/redefinition.md`
 - **设计文档**：
@@ -23,10 +23,10 @@ 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，**60 个 tools**（含 5 个 vault tools + 8 个代码分析工具 + 4 个 embedding/搜索工具 + 4 个 Skill Runtime tools + 3 个 Workflow/评分 tools + 1 个报告工具 + 1 个 arXiv 工具 + 2 个 KnownLimit tools + 3 个 Relation tools + 9 个 Agent Context tools + 2 个 Agent Memory 向量工具 + 1 个 streaming index 工具 + 1 个 oplog 工具）；配置见 `mcp.json`
+- **MCP Server**：stdio only，**64 个 tools**（含 5 个 vault tools + 8 个代码分析工具 + 4 个 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 工具）；配置见 `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
-- **当前测试**：442+ lib passed / 0 failed / 3 ignored + 11/11 integration passed（`tests/cli.rs`）
+- **当前测试**：446+ lib passed / 0 failed / 3 ignored + 11/11 integration passed（`tests/cli.rs`）
 - **编译状态**：0 warning / 0 vulnerabilities（`cargo audit` 干净，除上游 `tokei` 的 `RUSTSEC-2020-0163`）
 - **Workspace 结构**：`crates/` 目录已启用，18 个零耦合模块已提取为独立 crate（`devbase-symbol-links`, `devbase-sync-protocol`, `devbase-core-types`, `devbase-syncthing-client`, `devbase-vault-frontmatter`, `devbase-vault-wikilink`, `devbase-workflow-interpolate`, `devbase-workflow-model`, `devbase-registry-health`, `devbase-registry-metrics`, `devbase-registry-workspace`, `devbase-embedding`, `devbase-skill-runtime-types`, `devbase-skill-runtime-parser`, `devbase-registry-entity`, `devbase-registry-relation`, `devbase-registry-call-graph`, `devbase-registry-dead-code`, `devbase-registry-code-symbols`）
 - **Workflow Engine**：YAML 解析 + 拓扑调度 + batch 并行执行 + 5 种 step 类型（skill/subworkflow/parallel/condition/loop）

docs/RFC/claudecode-workflow-integration.md

@@ -0,0 +1,247 @@
+# RFC: ClaudeCode 工作流深度集成 — v0.18.0
+
+**Status**: Draft  
+**Target Version**: v0.18.0  
+**Author**: juice094  
+**Date**: 2026-05-13
+
+## 1. 用例分析
+
+ClaudeCode 是 Anthropic 推出的终端 AI 编程助手。其典型工作流：
+
+```
+1. 启动      → Claude 扫描项目目录，建立初步理解（往往耗时且片面）
+2. 需求理解  → 用户用自然语言描述需求
+3. 文件探索  → Claude 用 grep/find 暴力搜索相关代码
+4. 编辑执行  → 读文件 → 改文件 → 验证（循环）
+5. 提交      → git add/commit/push
+6. 会话结束  → 对话历史丢失，下次从零开始
+```
+
+**痛点**：
+- P1: 启动扫描慢，对大型仓库（如 devbase 本身）需要数十秒才能建立上下文
+- P2: 代码搜索依赖关键词匹配，无法基于语义（"找认证相关的代码" → grep "auth" 漏掉 "login"）
+- P3: 修改前无影响分析，经常漏改调用点或测试
+- P4: 会话不持久，跨会话知识丢失（昨天的决策今天不记得）
+- P5: 无法自动执行标准化工作流（如：修改 → clippy → test → commit message生成）
+
+## 2. 设计目标
+
+让 devbase 成为 ClaudeCode 的"外接海马体"：
+
+| 环节 | devbase 能力 | ClaudeCode 收益 |
+|------|-------------|----------------|
+| 启动 | `devkit_project_brief` | 秒级获得项目全景，替代暴力扫描 |
+| 探索 | `devkit_hybrid_search` | 语义搜索找代码，减少 50% 文件读取 |
+| 编辑前 | `devkit_impact_analysis` | 修改前预知影响范围，降低回归风险 |
+| 验证 | `devkit_evaluate` | 一键运行 clippy/test/fmt，保障质量 |
+| 会话中 | `devkit_session_save/capture` | 关键决策实时沉淀为项目记忆 |
+| 跨会话 | `devkit_session_recall` | 启动时自动注入相关历史决策 |
+| 复杂任务 | Workflow Engine | 标准化重构/发布/审查流程 |
+
+## 3. 核心功能设计
+
+### 3.1 Project Brief Generator (`devkit_project_brief`)
+
+**问题**：Claude 启动时需要快速理解项目结构、关键模块、技术约束。
+
+**设计**：
+```json
+{
+  "repo_id": "devbase",
+  "format": "markdown" // markdown | json
+}
+```
+
+**输出结构**：
+```markdown
+# Project Brief: devbase
+
+## Overview
+本地优先的 AI 情境编译器。Rust CLI，SQLite + Tantivy 索引。
+
+## Key Modules
+- src/mcp/ — MCP Server（60 tools）
+- src/registry/ — SQLite schema + migrations
+- src/workflow/ — YAML workflow engine
+- crates/ — 18 个零耦合 workspace crates
+
+## Dependency Graph（高内聚模块）
+- mcp → registry → storage
+- workflow → skill_runtime → registry
+
+## Active Contexts
+- feat/claudecode-integration（当前分支关联的 context）
+
+## Known Limits
+- [L3-001] Windows 路径长名问题（已缓解）
+- [L3-002] Candle 编译时间（v0.17.0 已外迁）
+
+## Recent Changes（最近 7 天）
+- v0.17.0: Agent Memory 向量存储
+- v0.16.1: Workflow-Session 绑定
+```
+
+**实现**：聚合 `repo_modules` + `code_symbols` + `known_limits` + `oplog` + `agent_contexts` 数据，生成 LLM-optimized Markdown。
+
+### 3.2 Impact Analysis (`devkit_impact_analysis`)
+
+**问题**：Claude 说"我要重构 `run_skill`"，但不知道谁调用了它、哪些测试覆盖它。
+
+**设计**：
+```json
+{
+  "repo_id": "devbase",
+  "symbol_name": "run_skill",
+  "depth": 2 // 调用链深度
+}
+```
+
+**输出**：
+```json
+{
+  "symbol": "run_skill",
+  "file": "src/skill_runtime/executor.rs:12",
+  "callers": [
+    {"symbol": "execute_skill_step", "file": "src/workflow/executor.rs:45"},
+    {"symbol": "test_run_skill_success", "file": "src/skill_runtime/executor.rs:502"}
+  ],
+  "callees": [
+    {"symbol": "resolve_interpreter", "file": "src/skill_runtime/executor.rs:257"},
+    {"symbol": "recall_context_memories", "file": "src/skill_runtime/executor.rs:231"}
+  ],
+  "related": [
+    {"symbol": "ExecutionResult", "file": "src/skill_runtime/mod.rs:45", "link_type": "return_type"}
+  ],
+  "tests": [
+    "test_run_skill_success",
+    "test_run_skill_not_found",
+    "test_hard_veto_guard"
+  ],
+  "history": [
+    {"date": "2026-05-13", "change": "添加 auto-recall 逻辑", "commit": "b1fff28"}
+  ]
+}
+```
+
+**实现**：复用现有的 `call_graph` + `related_symbols` + `dead_code` + `code_symbols` 数据，通过统一的 `impact_analysis` API 聚合。
+
+### 3.3 Session-Aware Claude Wrapper
+
+**问题**：ClaudeCode 会话结束即丢失，无法跨会话保持上下文。
+
+**设计**（无需修改 ClaudeCode 本身）：
+
+提供一个 wrapper 脚本 `devbase-claude`：
+
+```bash
+#!/bin/bash
+# devbase-claude wrapper
+
+# 1. 读取 active context
+CONTEXT_ID=$(devbase context resolve)
+
+# 2. 如果有 context，导出 memories 为 Claude system prompt 补充
+if [ -n "$CONTEXT_ID" ]; then
+  MEMORIES=$(devbase session recall --context-id "$CONTEXT_ID" --limit 10)
+  export CLAUDE_SYSTEM_PROMPT_EXTRA="$MEMORIES"
+fi
+
+# 3. 生成 project brief
+BRIEF=$(devbase project brief --repo-id "$(basename $(pwd))")
+export CLAUDE_PROJECT_BRIEF="$BRIEF"
+
+# 4. 启动 ClaudeCode
+claude "$@"
+
+# 5. 会话结束后，自动捕获对话摘要（需要用户确认）
+echo "Capture this session to devbase? [y/N]"
+read -r CAPTURE
+if [ "$CAPTURE" = "y" ]; then
+  devbase session capture "$CONTEXT_ID" "decision" "$(cat /tmp/claude-summary.txt)"
+fi
+```
+
+**长期**：向 Anthropic 提议官方 MCP integration，让 ClaudeCode 原生支持 devbase tools。
+
+### 3.4 Standardized Development Workflow
+
+**设计**：预置 workflow YAML，Claude 可通过 `devkit_workflow_run` 触发。
+
+**`workflows/refactor.yml`**：
+```yaml
+id: safe-refactor
+name: Safe Refactor Pipeline
+inputs:
+  - name: repo_id
+  - name: symbol_name
+  - name: description
+steps:
+  - id: analyze
+    step_type: skill
+    skill: devbase-impact-analysis
+    inputs:
+      repo_id: "{{ inputs.repo_id }}"
+      symbol_name: "{{ inputs.symbol_name }}"
+
+  - id: edit
+    step_type: skill
+    skill: claude-code-edit
+    inputs:
+      description: "{{ inputs.description }}"
+      affected_files: "{{ steps.analyze.outputs.affected_files }}"
+    depends_on: [analyze]
+
+  - id: evaluate
+    step_type: skill
+    skill: devbase-evaluate
+    inputs:
+      repo_id: "{{ inputs.repo_id }}"
+    depends_on: [edit]
+
+  - id: capture
+    step_type: skill
+    skill: devbase-session-capture
+    inputs:
+      context_id: "{{ env.DEVBASE_ACTIVE_CONTEXT }}"
+      memory_type: "decision"
+      content: "Refactored {{ inputs.symbol_name }}: {{ inputs.description }}"
+    depends_on: [evaluate]
+```
+
+## 4. 实施路线
+
+### P1: Project Brief + Impact Analysis（2 周）
+
+- [ ] `devkit_project_brief` MCP tool + CLI command
+- [ ] `devkit_impact_analysis` MCP tool（聚合 call_graph + related_symbols + tests）
+- [ ] 更新 `docs/guides/claudecode-integration.md`
+
+### P2: Session Wrapper + Auto-Capture（1 周）
+
+- [ ] `devbase-claude` wrapper 脚本（POSIX + PowerShell）
+- [ ] 会话结束后自动摘要提取（基于 git diff + oplog）
+- [ ] `devkit_session_export` / `devkit_session_import`（Markdown 格式）
+
+### P3: Workflow Templates（1 周）
+
+- [ ] 预置 workflow YAML: `safe-refactor`, `code-review`, `release-prep`
+- [ ] Workflow 模板注册到 devbase skill registry
+- [ ] TUI workflow 模板选择器
+
+## 5. 成功指标
+
+| 指标 | 基线 | 目标 |
+|------|------|------|
+| Claude 启动理解时间 | 30-60s（大型仓库） | < 5s（Project Brief 注入） |
+| 代码搜索轮次 | 5-10 次 grep | 2-3 次 hybrid search |
+| 修改后回归 Bug | 频繁 | 降低 50%（Impact Analysis） |
+| 跨会话知识保留 | 0% | 80%（Session Memory） |
+
+## 6. 风险评估
+
+| 风险 | 缓解 |
+|------|------|
+| ClaudeCode API 封闭，无法深度集成 | 先通过 wrapper 脚本 + MCP tools 外围集成；长期推动官方支持 |
+| Project Brief 过大导致 token 爆炸 | 支持 `max_tokens` 限制 + 分层摘要（overview → modules → limits） |
+| Impact Analysis 误报 | 结合 test coverage + manual review flag |

scripts/devbase-claude.ps1

@@ -0,0 +1,63 @@
+#Requires -Version 7
+# devbase-claude.ps1 — ClaudeCode launcher with devbase Project Brief injection
+# v0.18.0
+
+param(
+    [string]$RepoId = "",
+    [switch]$SkipBrief,
+    [switch]$CaptureOnExit
+)
+
+$ErrorActionPreference = "Stop"
+
+# 1. Resolve repo_id from current directory if not provided
+if (-not $RepoId) {
+    $cwd = (Get-Location).Path
+    # Try to get repo_id from devbase registry by matching local_path
+    $repoJson = devbase query repos --json 2>$null | ConvertFrom-Json -ErrorAction SilentlyContinue
+    if ($repoJson) {
+        $match = $repoJson | Where-Object { $cwd -like "*$($_.local_path)*" -or $cwd -like "*$($_.id)*" } | Select-Object -First 1
+        if ($match) {
+            $RepoId = $match.id
+            Write-Host "[devbase] Detected repo: $RepoId" -ForegroundColor Cyan
+        }
+    }
+}
+
+# 2. Generate Project Brief and inject into .claude/CLAUDE.md
+if ($RepoId -and -not $SkipBrief) {
+    Write-Host "[devbase] Generating project brief for $RepoId ..." -ForegroundColor Cyan
+    $brief = devbase project brief --repo-id $RepoId --max-tokens 3000 2>$null | ConvertFrom-Json -ErrorAction SilentlyContinue
+    if ($brief -and $brief.brief) {
+        $claudeDir = Join-Path (Get-Location) ".claude"
+        if (-not (Test-Path $claudeDir)) {
+            New-Item -ItemType Directory -Path $claudeDir | Out-Null
+        }
+        $claudeMd = Join-Path $claudeDir "CLAUDE.md"
+        $header = "# Devbase Project Brief (auto-generated)\n\n> This file is automatically generated by devbase-claude.ps1.\n> Do not edit manually — run `devbase-claude.ps1 -SkipBrief` to skip regeneration.\n\n"
+        $content = $header + $brief.brief
+        Set-Content -Path $claudeMd -Value $content -Encoding UTF8
+        Write-Host "[devbase] Injected brief into .claude/CLAUDE.md ($($content.Length) chars)" -ForegroundColor Green
+    } else {
+        Write-Warning "[devbase] Failed to generate brief. Proceeding without injection."
+    }
+}
+
+# 3. Launch ClaudeCode
+Write-Host "[devbase] Starting ClaudeCode ..." -ForegroundColor Cyan
+& claude @args
+
+# 4. Post-session capture (optional)
+if ($CaptureOnExit -and $RepoId) {
+    Write-Host "`n[devbase] Capturing session summary ..." -ForegroundColor Cyan
+    $diff = git diff --stat HEAD 2>$null
+    if ($diff) {
+        $summary = "Session changes:`n$diff"
+        $activeCtx = $env:DEVBASE_ACTIVE_CONTEXT
+        if (-not $activeCtx) { $activeCtx = $RepoId }
+        devbase session capture $activeCtx "decision" $summary 2>$null | Out-Null
+        Write-Host "[devbase] Captured to context '$activeCtx'" -ForegroundColor Green
+    } else {
+        Write-Host "[devbase] No git changes detected — nothing to capture." -ForegroundColor DarkGray
+    }
+}