Ckb Code Knowledge Backend

CKB — 代码知识后端

了解你的代码。安全地修改它。自信地交付。

CKB 将你的代码库转变为可查询的知识库。通过命令行、API 或 AI 助手提问、了解影响、查找负责人、检测无用代码。

可以把它想象成一位资深工程师，了解每一行代码、每个决策和每位负责人，全天候为你解答问题。

即时解答棘手问题

你可以做什么

🔍 了解 — 语义搜索、调用图、使用情况追踪、架构图

⚡ 分析 — 影响分析、风险评分、热点检测、耦合分析

🛡️ 保护 — 检测受影响的测试、破坏性变更警告、PR 风险评估

🔐 保障安全 — 机密信息检测、凭证扫描、安全敏感代码识别

👥 协作 — 负责人查询、评审者推荐、架构决策记录（ADR）

📊 改进 — 无用代码检测、技术债务追踪、文档覆盖率

🚀 组合操作 — 单次调用工具（explore、understand、prepareChange）可将 AI 工具调用减少 60-70%

🔗 集成 — 命令行、HTTP API、面向 AI 工具的 MCP、CI/CD 管道、自定义脚本

立即试用

# See what's risky in your codebase
ckb hotspots --format=human

# Check what changed and what might break
ckb diff-summary --format=human

# Scan for exposed secrets
ckb audit --format=human

# Check architecture at a glance
ckb arch --format=human

# Check system status
ckb status

随处可用

使用智能预设可减少 83% 的令牌用量——只加载所需的工具。

# One command to connect to Claude Code
ckb setup

正在构建自己的工具？ 通过命令行、HTTP API 或 MCP 将 CKB 用作后端。示例请参阅 集成指南，其中涵盖 Node.js、Python、Go 和 shell 脚本。

了解更多

快速开始

选项 1：npm（推荐）

# Install globally
npm install -g @tastehub/ckb

# Or run directly with npx (no install needed)
npx @tastehub/ckb init

选项 2：Homebrew（macOS/Linux）

brew install simplyliz/ckb/ckb

请使用完全限定名称。Homebrew 6.0 要求先信任第三方 tap，才会加载其中的内容；通过这种方式安装，即表示仅对这一个 formula 授予信任。先添加 tap，再使用短名称安装会失败，并显示 Refusing to load formula ... from untrusted tap。

选项 3：从源代码构建

git clone https://github.com/SimplyLiz/CodeMCP.git
cd CodeMCP
go build -o ckb ./cmd/ckb

设置

# 1. Initialize in your project
cd /path/to/your/project
ckb init   # or: npx @tastehub/ckb init

# 2. Generate SCIP index (optional but recommended)
ckb index  # auto-detects language and runs appropriate indexer

# 3. Connect to Claude Code
ckb setup  # creates .mcp.json automatically

# Or manually:
claude mcp add --transport stdio ckb -- npx @tastehub/ckb mcp

启动时显示的令牌效率：

CKB MCP Server v9.3.1
  Active tools: 25 / 110 (22%)
  Estimated context: ~4k tokens
  Preset: core

现在，Claude 可以回答以下问题：

• “什么会调用 HandleRequest 函数？”
• “如何从 API 调用到 ProcessPayment？”
• “如果我更改 UserService，影响范围有多大？”
• “谁负责维护 internal/api 模块？”
• “这段旧代码仍在使用吗？”

为什么选择 CKB？

三种使用方式

索引的工作方式

CKB 使用 SCIP 索引来理解代码。可以把它想象成一个数据库，它知道每个函数的定义位置、调用者以及代码之间的关联。

基础知识

# 1. Generate an index (auto-detects language)
ckb index

# 2. Check if your index is fresh
ckb status

没有索引时，CKB 仍可通过 tree-sitter 解析工作（基本模式）；但有了索引，你就能获得：

• 跨文件引用（“谁调用了这个函数？”）
• 精确的影响分析
• 调用图导航

语言支持

并非所有语言都相同。CKB 根据索引器的成熟度，将语言划分为不同的质量级别：

主要限制：

• 增量索引仅支持 Go。其他语言需要完整重新索引。
• TypeScript 单体仓库可能需要 --infer-tsconfig 标志
• C/C++ 需要 compile_commands.json
• Python 在已激活的虚拟环境中效果最佳

运行 ckb doctor --tier standard，检查是否已正确安装语言工具。

有关索引器安装、已知问题和完整功能矩阵，请参阅 语言支持。

保持索引最新

提交代码后，索引会变旧。CKB 提供多种方式来保持索引最新：

AI 会话快速入门：

ckb mcp --watch  # Auto-reindexes every 30s when stale

检查索引是否过时：

ckb status
# Shows: "5 commits behind HEAD" or "Up to date"

对于 Go 项目，CKB 使用增量索引——只处理有更改的文件，因此更新速度很快。

完整文档请参阅 索引管理指南。

功能

📖 完整功能指南 — 包含示例的详细文档

📋 更新日志 — 版本历史

PR 审查

CKB 审查可在 5 秒内运行 21 项质量检查，包括密钥、破坏性变更、死代码、复杂度、测试缺口、错误模式等。零令牌，零 API 调用。

当你的 AI 助手（Claude Code、Cursor、Windsurf）审查 PR 时，它会先调用 CKB，并获取约 1k 令牌的结构化分析。然后它只读取重要文件——在大型 PR 中节省 50-80% 的令牌。

ckb review --base=main              # Human-readable review
ckb review --base=main --ci         # CI mode (exit codes)
ckb review --base=main --post=123   # Post as PR comment

无需任何 LLM 即可在 CI 中运行：

- run: npx @tastehub/ckb review --base=main --ci --format=sarif > review.sarif

📖 它如何帮助 AI 审查 · 基准测试 · CI 集成 · 快速入门

CLI

ckb status           # System health (with remediation suggestions)
ckb search Handler   # Find symbols
ckb diff-summary     # Analyze what changed
ckb hotspots         # Risky areas
ckb arch             # Architecture overview
ckb ownership        # File/path ownership
ckb mcp              # Start MCP server

组合操作（通过 MCP）：

# These tools combine multiple queries into single calls
explore      # Area exploration: symbols, dependencies, hotspots
understand   # Symbol deep-dive: refs, callers, explanation
prepareChange # Pre-change analysis: impact, tests, risk
batchGet     # Fetch up to 50 symbols at once
batchSearch  # Run up to 10 searches at once

📖 用户指南 — 所有 CLI 命令和选项

HTTP API

# Start the HTTP server
ckb serve --port 8080

# Example calls
curl http://localhost:8080/health
curl http://localhost:8080/status
curl "http://localhost:8080/search?q=NewServer"
curl http://localhost:8080/architecture
curl "http://localhost:8080/ownership?path=internal/api"
curl http://localhost:8080/hotspots

# Index Server Mode (v7.3) - serve indexes to remote clients
ckb serve --port 8080 --index-server --index-config config.toml

# Index server endpoints
curl http://localhost:8080/index/repos
curl http://localhost:8080/index/repos/company%2Fcore-lib/meta
curl "http://localhost:8080/index/repos/company%2Fcore-lib/symbols?limit=100"
curl "http://localhost:8080/index/repos/company%2Fcore-lib/search/symbols?q=Handler"

# Upload endpoints (with compression + auth)
curl -X POST http://localhost:8080/index/repos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ckb_xxx" \
  -d '{"id":"my-org/my-repo","name":"My Repo"}'

gzip -c index.scip | curl -X POST http://localhost:8080/index/repos/my-org%2Fmy-repo/upload \
  -H "Content-Encoding: gzip" \
  -H "Authorization: Bearer ckb_xxx" \
  --data-binary @-

# Token management (index server admin)
ckb token create --name "ci-upload" --scope upload    # Create API key
ckb token list                                         # List all tokens
ckb token revoke ckb_xxx                              # Revoke a token
ckb token rotate ckb_xxx                              # Rotate (new secret, same ID)

MCP 集成

CKB 兼容所有支持 MCP 的 AI 编码工具。

# Auto-configure for current project
npx @tastehub/ckb setup

# Or add globally for all projects
npx @tastehub/ckb setup --global

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

{
  "mcp": {
    "servers": {
      "ckb": {
        "type": "stdio",
        "command": "npx",
        "args": ["@tastehub/ckb", "mcp"]
      }
    }
  }
}

{
  "mcp": {
    "ckb": {
      "type": "local",
      "command": ["npx", "@tastehub/ckb", "mcp"],
      "enabled": true
    }
  }
}

# Auto-configure for current project
npx @tastehub/ckb setup --tool=grok

# Or add globally
npx @tastehub/ckb setup --tool=grok --global

{
  "mcpServers": {
    "ckb": {
      "name": "ckb",
      "transport": "stdio",
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp"]
    }
  }
}

cd /path/to/your/repo
ckb setup --tool=claude-desktop

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["-y", "@tastehub/ckb", "mcp"],
      "env": {
        "CKB_REPO": "/path/to/your/repo"
      }
    }
  }
}

{
  "mcpServers": {
    "ckb": {
      "command": "cmd",
      "args": ["/c", "npx", "@tastehub/ckb", "mcp"]
    }
  }
}

# List all available presets with tool counts and token estimates
ckb mcp --list-presets

# Default: core preset (25 essential tools)
ckb mcp

# Workflow-specific presets
ckb mcp --preset=core        # 25 tools - search, explain, impact (default)
ckb mcp --preset=review      # 42 tools - core + diff, ownership, PR review
ckb mcp --preset=refactor    # 42 tools - core + coupling, dead code
ckb mcp --preset=federation  # 46 tools - core + cross-repo
ckb mcp --preset=docs        # 34 tools - core + doc-symbol linking
ckb mcp --preset=ops         # 43 tools - core + jobs, webhooks, metrics
ckb mcp --preset=full        # 110 tools - complete feature set

{
  "mcpServers": {
    "ckb": {
      "command": "npx",
      "args": ["@tastehub/ckb", "mcp", "--preset=review"]
    }
  }
}

底层原理

CKB 会编排多个代码智能后端，使用可用的后端并结合各自优势——运行的后端越多，答案就越丰富：

• Cartographer — 快速结构分析（架构、依赖关系、影响范围、耦合关系、目录汇总），无需索引，安装 CKB 后即可使用。它已编译到二进制文件中，因此默认包含在 npm 和 Homebrew 构建版本中。
• SCIP — 精确的预索引符号数据，用于查找定义、引用和调用图（运行 ckb index）
• LSP — 实时语言服务查询
• Git — 责任归属、历史记录、变更频率分析、所有权
• LIP — 用于近邻搜索和重新排序的语义嵌入守护进程。它作为独立的可选守护进程运行——请与 CKB 一起安装并启动。

结果会经过智能合并，并压缩以适应大模型的上下文限制。除 Git 外，所有后端均为可选；CKB 会根据可用后端灵活调整。

LIP 可增强语义搜索、PR 新颖性检测、测试发现、文件边界分析和架构耦合信号。 当 LIP 与 CKB 同时运行时，搜索质量会显著提升，尤其是对于与符号名称不完全匹配的自然语言查询。详情请参阅混合检索，或查看 LIP 文档。

持久化知识可跨会话保留：

• 模块注册表 — 边界、职责、标签
• 所有权注册表 — CODEOWNERS + 带时间衰减的 git-blame
• 热点跟踪器 — 带趋势分析的历史快照
• 决策日志 — 支持全文搜索的 ADR

谁适合使用 CKB？

• 使用 AI 助手的开发者 — 为 AI 工具赋予超能力
• 拥有大型代码库的团队 — 高效应对复杂性
• 进行重构的任何人 — 修改前了解影响
• 代码审查者 — 全面了解变更
• 技术负责人 — 持续跟踪架构健康状况

局限性（坦诚说明）

CKB 擅长：

• 静态代码导航——查找定义、引用和调用图
• 影响分析，帮助安全重构
• 所有权查询（CODEOWNERS + git blame）
• 理解架构和模块

CKB 无法帮助：

• 动态分派／运行时行为（请使用调试器）
• 未编入索引的生成代码
• 代码生成、lint 或格式化
• 跨仓库调用（请使用联邦功能）

CKB 是静态分析工具，并非万能。对于关键决策，请务必阅读实际代码进行验证。

📖 实用局限性 — 关于准确性、盲点以及何时可以信任结果的完整指南

文档

请参阅**完整文档 Wiki**，了解：

• 快速入门 — 分步安装指南
• 提示词手册 — 针对实际问题的实用提示词
• 语言支持 — SCIP 索引器和支持级别
• 实用局限性 — 准确性说明和盲点
• 用户指南 — CLI 命令和最佳实践
• 索引管理 — 索引工作原理和自动刷新方法
• 增量索引 — Go 项目的快速索引更新
• 文档与符号链接 — 文档中的符号检测和过时检查
• 身份验证 — API 令牌、作用域和速率限制
• MCP 集成 — Claude Code 设置和 110+ 个工具
• API 参考 — HTTP API 文档
• 守护进程模式 — 配备调度器和 Webhook 的常驻服务
• 配置 — 所有选项，包括 MODULES.toml
• 架构 — 系统设计和组件
• 安全 — 密钥检测和凭据扫描
• 遥测 — 运行时可观测性和死代码检测
• 联邦功能 — 跨仓库查询
• CI/CD 集成 — GitHub Actions 和 PR 分析

要求

使用 npm（推荐）：

• Node.js 16+
• Git

从源代码构建：

• Go 1.21+
• Git

可选（用于增强分析）：

• 适用于相应语言的 SCIP 索引器（scip-go、scip-typescript 等）——运行 ckb index 即可自动安装
• LIP v2.3+ 语义嵌入守护进程（需要 Rust/cargo）——强烈建议安装，以获得最佳搜索质量（文档，crates.io）：

  cargo install lip-cli
  lip daemon --socket ~/.local/share/lip/lip.sock
  

许可证

以下用途免费：

• 个人使用
• 开源项目
• 年收入低于 $25k 的初创公司和小型企业

年收入达到 $25k+ 的组织需要商业许可证。请参阅定价了解 Team 和 Enterprise 计划，或查看LICENSE了解完整条款。