Code Project Brain (CPB)

一个随代码仓库同步增长的项目级第二大脑。 开发指南（Development Guide，一等上下文）位于 CodeGraph（事实） 和 Project KB（消化后的知识）之上，编译为针对特定任务的上下文 供 Claude Code 使用——并通过受治理的 变更 → 提案 循环保持知识正确， 绝不允许 AI 静默改写。

CPB 实现了 v3.0 设计：开发指南是第一公民——Agent 首先加载的项目心智模型。上下文编译器（Context Compiler）按固定顺序 指南 → KB → CodeGraph 组装 ContextPlan；概念中心（Concept hub）通过 canonical_id 连接三个领域；代码锚点（Code Anchor）层让指南与代码保持一致。

Development Guide (context / first-class)
        │  describes / governs (via Concept hub)
        ▼
CodeGraph (facts)  ·  Project KB (digested knowledge)
        └──────────────► Context Compiler ► Claude Code
Change → Impact → (Guide stale?) → Guide Proposal → Validate → Approve → Apply

新来的？ 阅读 docs/OVERVIEW.md——架构、实现、设计选择和路线图的一站式导览。v2.0 历史见 UpdateGuide2.0.md。

三层架构（v3.0，update3.0 §1）

固定加载顺序为 指南 → KB → CodeGraph，绝不反向（§3）：

• 开发指南 = 上下文 — 项目是什么、为何如此设计、以及需要遵循的规则。Agent 首先加载的心智模型。位于 guide/，为骨架结构 00-overview → 06-decisions（§14）。

• CodeGraph = 事实 — 由 tree-sitter 解析代码为 SQLite 符号图及调用/引用边（WAL + FTS5）。作为 Ground Truth 适配器，验证指南的代码锚点（§9）。是什么（WHAT IS）。

• Project KB = 知识 — 消化后的需求 / 缺陷 / 决策（ADR）/ 外部来源 / 经验教训。仅在指南之后到达的详细历史层。学到了什么（WHAT WAS LEARNED）。

概念中心（§21/§22）通过 canonical_id 连接指南章节、KB 文档和 CodeGraph 符号，使代码变更可以追溯 符号 → 概念 → 指南章节 并标记指南过期。

受治理的循环（§11/§13/§24）

代码或 KB 变更绝不会静默编辑指南。而是：

Change → Impact → Concept impact → Guide stale? → Guide Proposal (draft)
      → Validate → Approve → Apply

引擎提议；人类（或作为审查者的 Claude）在应用前验证并批准。KB 知识可以通过相同的受治理提案提升（promoted）到指南中（§13 知识提升）。cpb sync 起草待处理的提案；cpb proposals <id> --approve|… 处理它们。

功能

• 开发指南 — 索引 guide/ Markdown（骨架 frontmatter + 代码锚点），对照 CodeGraph 验证锚点，标记过期的锚点。

• CodeGraph — 按文件增量同步符号和边。

• Project KB — 索引带类型化 frontmatter 的 project-kb/ Markdown；消化为 kb_digests；重复摘要的去重/合并（§13）。

• 上下文编译器 — cpb context "<task>" → 一个 ContextPlan（指南 → KB → 代码，渐进式披露级别 0-6，token 预算）（§18）。

• 影响引擎 — 爆炸半径 + 受影响的约束/决策以及受影响的概念 / 指南章节（§22）。

• 概念中心 — 连接指南 / KB / CodeGraph 的 canonical_id（§21）。

• Claude Code 技能 — 八个工作流：/project-init、/project-context、/project-feature、/project-impact、/project-update-docs、/project-review、/project-knowledge、/project-sync。

技术

Node/TypeScript，node:sqlite（内置，WAL+FTS5，Node ≥ 22），web-tree-sitter（C/C++/TS/JS/Python/Rust/Go/Java 的 WASM 语法）。无原生构建，无向量数据库（设计如此，§19）。引擎 v3.0.0 / 协议 2。

快速开始

# inside a code repository
cpb init        # create .project-brain/ + guide/ + project-kb/
cpb index       # build codegraph + knowledge + guide + concepts + git
cpb status      # summary: engine/protocol/guide sections/stale anchors
cpb context FrameQueue        # ContextPlan (Guide → KB → CodeGraph)
cpb concept camera/capture-pipeline   # the Concept hub: 3-domain graph
cpb guide list               # the Guide skeleton (Level 0)
cpb guide validate           # Guide well-formedness (§17 validator)
cpb impact FrameQueue         # blast radius + affected concepts/guide
cpb kb dedup                  # find duplicate KB digests (§13); --apply to merge
cpb sync                      # detect changes → draft Guide/Update proposals
cpb proposals                 # list / validate / approve / apply proposals

自托管

CPB 索引自身源码以及附带的 guide/ + project-kb/：

git init && cpb init && cpb index && cpb status

MCP（AI 接口）

CPB 暴露命名空间的 MCP 工具——唯一的 AI 接口：

• code.* — code.search code.symbol code.callers code.callees code.dependencies code.impact

• docs.* — docs.get docs.search docs.related docs.constraints docs.validate docs.apply

• kb.* — kb.search kb.requirement kb.bug kb.decision kb.reference kb.ingest kb.promote kb.digest kb.promote-guide kb.dedup

• guide.* — guide.index guide.section guide.stale guide.validate

• concept.* — concept.graph concept.forSymbol

• project.* — project.context project.impact project.changes project.sync project.proposals project.status

安装配置和完整工具参考见 USAGE.md。

作为 Claude Code 插件

CPB 以 Claude Code 插件（cpb-claude-plugin/）形式发布，作为引擎之上的适配层。引擎（本仓库，cpb/cpb-mcp CLI）保持独立运行时；插件通过 MCP 协议绑定，而非 npm 导入——因此引擎可以独立演进。理由见 docs/plans/archi.md，完整安装步骤见 cpb-claude-plugin/README.md。

# 1. Engine on PATH (once)
npm install -g @cpb/engine        # or: npm link  (from this repo)

# 2. In Claude Code
/plugin marketplace add /path/to/CPB
/plugin install cpb@cpb

然后使用 /cpb:status、/cpb:context、/cpb:sync、……——或者直接描述任务，技能会自动激活。

演示项目

demo-src/camera/ 是一个小型 C++ 相机流水线（CameraDevice → FrameQueue → VideoEncoder），带有完整的 v3.0 文档集——guide/（概述 + 架构 + 一个约束 + 一个 ADR）和 project-kb/（ADR、需求、缺陷、经验教训、外部 V4L2/FFmpeg 笔记、测试证据）。它是自举的：CPB 在其上执行索引、探索、漂移检查和变更→提案循环。

布局

src/
  core/        types (domain model: Guide/Concept/ContextPlan + structured objects)
  db/          sqlite adapter + schema.sql + migrate.ts (versioned migrations)
  engine/
    codegraph/  tree-sitter extractor, grammars, parser, orchestrator, queries
    guide/      Development Guide: indexer, anchor, query, validator (§17)
    concept/    Concept hub: index + query (§21)
    knowledge/  KB: frontmatter, indexer, recall, freshness, entities, external, ingestion, promotion, dedup
    docs/       structured reads: constraints, decisions (Guide-seeded)
    git/        commit index + ADR mining + gitDiff
    impact/     blast radius + affected knowledge/concepts/guide (§22)
    context/    Context Compiler (§18) + builder (v2, cpb explain) + explain/explore
    sync/       semantic-diff, changeset, proposal, pipeline (change→proposal loop)
  mcp/         namespaced MCP tools (code.*/docs.*/kb.*/guide.*/concept.*/project.*) + stdio server
bin/cpb.ts      CLI
guide/          CPB's own Development Guide (self-hosted, v3.0 skeleton)
cpb-claude-plugin/  the Claude Code adapter (skills + commands + MCP declaration)

设计边界（按 §19/§23/§25）

不构建：自动改写所有文档、自动生成所有知识、向量/嵌入搜索（§19——本地优先，SQLite+FTS5）、完整 IDE 或企业知识图谱。引擎从不嵌入 LLM（§29）——Claude 通过 MCP 思考；引擎持有事实和状态机。知识保持人工控制（§11/§14）；指南是受治理的资产——每次编辑都经过提案。代码是最高真相来源（§9）。

许可证

MIT。