MIT · v0.1.0 · macOS / Linux / Windows

cbm-projects

统一管理多个代码仓库的 codebase-memory 索引，并把 MCP 配置交给你使用的编程 Agent。

Manage codebase-memory indexes across repositories and connect the MCP to the coding agents you already use.

一个双语 CLI、一个可移植项目注册表、一套独立进程插件协议。Codex 是推荐体验，但核心不绑定任何 Agent。

One bilingual CLI, one portable project registry, and one process-based plugin protocol. Codex is recommended, but the core is agent-independent.

开始安装 Install now 开发插件 Build a plugin

cbm-projects setup

30 秒理解

In 30 seconds

它负责管理，不替代 MCP

It manages the MCP; it does not replace it

注册项目

Register projects

用稳定名称保存仓库路径，移动后只需更新一次注册表。

Give repositories stable names and update the registry once after a move.

cbm-projects set api ./api

维护索引

Maintain indexes

ensure 只在缺失时创建；refresh 刷新；rebuild 明确执行完整重建。

ensure creates only when missing; refresh updates; rebuild explicitly recreates.

cbm-projects ensure api

配置 Agent

Configure agents

调用上游官方安装器检测并配置 Codex、Claude Code、Cursor 等客户端。

Delegate detection and setup for Codex, Claude Code, Cursor, and others to the upstream installer.

cbm-projects agents check

架构

Architecture

一条清晰的调用链，两类扩展点

One clear call chain, two extension surfaces

索引命令必须经过唯一的 MCP Provider；普通插件只能增加命令和生命周期 Hook。这样既能扩展，又不会出现两个服务同时管理同一份索引。

Index commands must pass through one MCP provider. Ordinary plugins add commands and lifecycle hooks, preventing two services from managing the same index.

Agents and users call the cbm-projects core. The core routes index operations to one MCP provider and sends lifecycle events to extension plugins. The provider calls codebase-memory-mcp. — 实线表示必须成功的索引路径；虚线表示失败时记录诊断并继续的普通 Hook。

设计边界

Design boundaries

谁拥有哪一部分能力

Who owns each responsibility

组件	负责	明确不负责
Component	Owns	Does not own
Core CLI	双语界面、配置、项目注册、插件发现/启停、命令路由	不解析代码，不直接实现索引，不写 Agent 私有配置	Bilingual UI, config, project registry, plugin lifecycle, command routing	Does not parse code, index repositories, or write agent-specific config
MCP Provider	检测/安装 MCP，执行 status、ensure、refresh、rebuild	不实现知识图谱，不绕开上游命令	Detects/installs MCP; runs status, ensure, refresh, and rebuild	Does not implement the graph or bypass upstream commands
agents-official	调用上游 `install --dry-run` 与 `install -y`	不自行猜测各 Agent 的配置格式	Calls upstream `install --dry-run` and `install -y`	Does not guess each agent's configuration format
Codex Plugin	注入 Skill，让 Codex 知道何时使用项目与索引命令	不声明第二个 MCP，不复制 Provider 能力	Injects a Skill so Codex knows when to manage projects and indexes	Does not declare a second MCP or duplicate provider behavior
第三方插件	Third-party plugin	增加自定义命令和 Hook；可用任意语言实现	未经启用不能运行；manifest 权限声明不是系统沙箱	Adds custom commands and hooks in any implementation language	Cannot run before enablement; manifest permissions are not an OS sandbox

插件注入

Plugin injection

把一个可执行程序注入宿主，只需要四步

Inject an executable into the host in four steps

插件不是 Go .so。宿主启动独立进程，通过 stdin/stdout 交换一次 JSON 请求和响应，因此插件可以跨语言、跨编译器发布。

A plugin is not a Go .so. The host starts an independent process and exchanges one JSON request and response over stdin/stdout.

创建目录与入口

Create a directory and entrypoint

my-plugin/
├── plugin.json
└── cbm-plugin-my-plugin(.exe)

声明协议、命令、Hook 与权限

Declare protocol, commands, hooks, and permissions

{
  "apiVersion": "cbm-projects.plugin/v1",
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My extension",
  "entrypoint": "cbm-plugin-my-plugin",
  "platforms": ["*"],
  "commands": ["hello"],
  "hooks": ["project.added", "doctor.check"],
  "permissions": ["process:execute"],
  "source": "https://github.com/example/my-plugin",
  "license": "MIT"
}

3
安装并检查权限
Install and review permissions
```
cbm-projects plugin install ./my-plugin

# Remote ZIPs must include an archive checksum
cbm-projects plugin install https://example.com/my-plugin.zip \
  --sha256 <64-hex-value>
```
安装不等于启用。第三方插件安装后默认禁用，宿主会先展示其权限。

Installed does not mean enabled. Third-party plugins start disabled so permissions can be reviewed first.

显式启用并调用

Explicitly enable and invoke

cbm-projects plugin info my-plugin
cbm-projects plugin enable my-plugin
cbm-projects plugin run my-plugin hello world

无需安装命令的注入

Injection without install

也可以放入发现目录

Place plugins in a discovery directory

适合包管理器、企业镜像和本地开发。相同名称只采用优先级最高的第一个 manifest。

Useful for package managers, enterprise images, and local development. The first manifest wins for duplicate names.

$CBM_PROJECTS_PLUGIN_DIR ~/Library/Application Support/cbm-projects/plugins /usr/local/share/cbm-projects/plugins

$CBM_PROJECTS_PLUGIN_DIR ~/.config/cbm-projects/plugins /usr/local/lib/cbm-projects/plugins /usr/share/cbm-projects/plugins

%CBM_PROJECTS_PLUGIN_DIR% %AppData%\cbm-projects\plugins %ProgramData%\cbm-projects\plugins

进程协议

Process protocol

一次调用，一次请求，一次响应

One invocation, one request, one response

stdout 只能输出协议 JSON；日志写 stderr。宿主负责 API 版本、平台、启用状态、超时和 SHA-256 检查。

stdout is reserved for protocol JSON; logs go to stderr. The host checks API version, platform, enabled state, timeout, and SHA-256.

stdinRequest

{
  "apiVersion": "cbm-projects.plugin/v1",
  "action": "command",
  "command": "hello",
  "args": ["world"],
  "locale": "zh-CN",
  "configDir": "/user/config/cbm-projects",
  "project": {
    "name": "api",
    "path": "/code/api"
  }
}

stdoutResponse

{
  "status": "ok",
  "message": "optional message",
  "data": {
    "output": "hello world"
  },
  "diagnostics": []
}

FAIL-OPEN

普通生命周期 Hook

Ordinary lifecycle hooks

15 秒超时。失败会记录诊断，但项目新增、删除或索引主流程继续。

15-second timeout. Failures are diagnosed while the main project or index flow continues.

FAIL-CLOSED

MCP Provider 索引命令

MCP provider index commands

Provider 失败会停止操作，避免把未完成的索引误报为成功。

Provider failures stop the operation so incomplete indexes are never reported as successful.

可订阅的生命周期

Available lifecycle events

setup.detectsetup.configureproject.addedproject.removedindex.beforeindex.afterdoctor.check

Agent 集成

Agent integration

Codex 是插件；其他 Agent 走上游官方配置

Codex uses a plugin; other agents use upstream configuration

这条边界避免 cbm-projects 复制并维护每个客户端不断变化的配置格式。

This boundary avoids copying and maintaining every client's changing configuration format.

Codex

Marketplace Plugin 注入管理 Skill。MCP 服务条目仍由 codebase-memory-mcp 官方安装器拥有。

A Marketplace plugin injects the management Skill. The upstream installer still owns the MCP server entry.

codex plugin marketplace add \
  pikachuprogrammer01/cbm-projects --ref v0.1.0
codex plugin add cbm-projects@cbm-projects

Claude Code · Cursor · Gemini CLI · OpenCode

先 dry-run 展示检测结果，再由上游安装器统一写入所有检测到的 Agent。

Preview detected clients with a dry-run, then let the upstream installer configure all of them.

cbm-projects agents check
cbm-projects agents install

# Or print manual stdio configuration
cbm-projects agents manual

安装

Install

一个命令安装，先校验再写入

One command, checksummed before install

安装器根据系统和架构下载 GitHub Release，并使用 checksums.txt 校验。已有 MCP 会被保留；缺失时只在确认后调用官方安装器。

The installer selects the GitHub Release for your OS and architecture and verifies it with checksums.txt. Existing MCP installs are preserved.

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/pikachuprogrammer01/cbm-projects/main/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/pikachuprogrammer01/cbm-projects/main/install.ps1 | iex

cbm-projects setup cbm-projects set my-project /path/to/repository cbm-projects ensure my-project cbm-projects doctor

安全边界

Security boundary

插件权限是披露，不是沙箱

Plugin permissions disclose; they do not sandbox

独立进程拥有当前用户的操作系统权限。只安装可信来源，并在启用前检查 manifest 中的网络、进程执行、配置读写和项目读取权限。

Plugin processes have the current user's OS permissions. Install trusted sources only and review network, process, config, and project permissions before enabling.

远程 ZIP 必须提供 SHA-256；入口文件可在每次调用前校验。
Remote ZIPs require SHA-256; entrypoints can be verified before every invocation.
第三方插件必须显式安装、显式启用。
Third-party plugins require explicit installation and enablement.
项目路径与索引默认留在本机。
Project paths and indexes remain local by default.

阅读安全策略 → Read the security policy →