内容
# 代码智能系统
代码智能系统（CIS）是一个用Rust编写的守护进程，它在您的代码仓库上构建一个**版本化的代码图谱**，并通过[模型上下文协议（MCP）](https://modelcontextprotocol.io/)将其暴露给AI代理。代理可以导航符号，进行语义搜索，应用推测性编辑并确认/恢复，以及合并分支 — 所有操作都具有崩溃安全性和后台维护功能。
## 功能概述
| 功能 | 描述 |
| --- | --- |
| **符号导航** | 查找符号，转到定义，列出调用者/被调用者，展开节点周围的上下文 |
| **语义和混合搜索** | 对索引符号进行向量搜索；可选的HTTP嵌入API |
| **推测性写入** | `write_file` / `apply_patch`创建草稿图谱修订；`confirm_patch`或`revert_patch`促进或回滚（包括磁盘内容） |
| **分支和合并** | 显式CIS分支（`create_branch`，`switch_branch`）；三阶段合并，带有Saga恢复 |
| **文件系统同步** | 监视代码仓库并重新索引更改的文件；检测外部编辑与代理写入 |
| **崩溃恢复** | WAL支持的协调器；图谱/KV快照在重启后存活 |
| **后台工作线程** | WAL压缩，墓碑GC，审计周期，嵌入队列，磁盘压力，一致性检查 |
CIS设计用于**本地代理辅助开发**：一位开发人员在MCP标准输入输出（例如，从Cursor）上运行`cisd`以对抗单个代码仓库。它不是一个多租户托管服务。
## 架构
此工作空间中有三个crate：
| Crate | 角色 |
| --- | --- |
| **`cis-wal`** | 预写日志和突变阶段机 |
| **`cis-core`** | 图谱，KV存储，摄入，查询，合并引擎，MCP运行时 |
| **`cis-mcp`** | MCP JSON-RPC服务器和二进制文件（`cisd`，`cis-mcp`，`cis`） |
状态存储在代码仓库根目录下的`.cis/`中（图谱，KV，WAL，正文，审计日志，合并指标）。
## 二进制文件
| 二进制文件 | 用途 |
| --- | --- |
| **`cisd`** | 主要守护进程 — 后台工作线程；添加`--mcp`以启用标准输入输出MCP服务器 |
| **`cis-mcp`** | MCP入口点；当可用时执行`cisd --mcp`（`CIS_STANDALONE_MCP=1`以在进程内运行） |
| **`cis`** | 维护CLI — 将正文/KV/图谱迁移到SQLite（`body-sqlite`功能） |
| **`cis-embed-smoke`** | 外部嵌入API的烟雾测试（`api-embeddings`功能） |
## 快速入门
### 先决条件
- Rust稳定版（2021版）
- Linux或macOS（FS通知使用inotify/kqueue）
### 构建
```bash
cargo build --release -p cis-mcp --features python-ast,body-sqlite,api-embeddings
```
二进制文件：`target/release/cisd`，`target/release/cis-mcp`，`target/release/cis`。
### 使用MCP运行守护进程
从您的项目根目录（CIS应索引的代码仓库）：
```bash
export CIS_REPO_ROOT="$(pwd)"
/path/to/cisd --mcp
```
首次运行时，CIS会遍历目录树，构建图谱，并写入`.cis/`。后续启动将加载已持久化的状态。
### Cursor MCP配置（示例）
```json
{
"mcpServers": {
"cis": {
"command": "/path/to/cis/target/release/cis-mcp",
"env": {
"CIS_REPO_ROOT": "/path/to/your/repo"
}
}
}
}
```
列出工具名称而不启动服务器：
```bash
cis-mcp --tools
```
## 本地嵌入服务器（语义搜索）
CIS可以使用外部的OpenAI兼容的`/v1/embeddings`端点进行`semantic_search`和`hybrid_search`。对于离线开发，一个小型Python服务器在`scripts/`中使用[fastembed](https://github.com/qdrant/fastembed)（ONNX，无GPU）。
### 1. 创建Python虚拟环境
从**cis代码仓库根目录**：
```bash
./scripts/setup_embed_venv.sh
```
这会创建`.venv-embed/`（gitignored）并安装`scripts/requirements-embed.txt`。需要**Python 3.10+**。
如果需要，可以使用`CIS_EMBED_VENV`覆盖虚拟环境路径。
### 2. 启动嵌入服务器
终端1：
```bash
./scripts/run_embed_server.sh
```
监听`http://127.0.0.1:8080`。首次启动会下载`all-MiniLM-L6-v2`模型（约90 MB）到Hugging Face缓存。
健康检查：
```bash
curl http://127.0.0.1:8080/healthz
```
### 3. 将CIS指向服务器
复制示例环境文件并使用`api-embeddings`构建：
```bash
cp .env.example .env
cargo build -p cis-mcp --features python-ast,body-sqlite,api-embeddings
```
`cisd`在启动时从代码仓库根目录加载`.env`。最小设置：
| 变量 | 值 |
| --- | --- |
| `CIS_EMBED_API_URL` | `http://127.0.0.1:8080/v1` |
| `CIS_EMBED_MODEL` | `all-MiniLM-L6-v2` |
| `CIS_EMBED_DIM` | `384` |
### 4. 验证端到端
嵌入服务器运行时：
```bash
cargo run -p cis-mcp --features api-embeddings --bin cis-embed-smoke
```
手动curl测试：
```bash
curl -X POST http://127.0.0.1:8080/v1/embeddings \
-H 'Content-Type: application/json' \
-d '{"model":"all-MiniLM-L6-v2","input":"Hello world"}'
```
如果没有嵌入服务器，CIS会回退到确定性的**stub嵌入器**（仅限离线测试；不是有意义的语义搜索）。
## MCP工具
### 读取（22）
`find_symbol`，`find_symbol_at`，`go_to_definition`，`find_references`，`get_callers`，`get_dependencies`，`file_imports`，`expand_context`，`semantic_search`，`hybrid_search`，`build_context`，`build_context_at`，`get_symbol_body`，`explain_context`，`index_status`，`embedding_status`，`system_status`，`why_no_definition`，`list_branches`，`list_merge_metrics`，`verify_audit_chain`，`check_graph_consistency`
### 写入（15）
`write_file`，`apply_patch`，`reindex_paths`，`confirm_patch`，`revert_patch`，`sweep_confirm_sidecars`，`purge_branch`，`save_workspace`，`cancel_merge`，`merge_ttl_sweep`，`merge_branch`，`ingest_cis_config`，`create_branch`，`switch_branch`
## 配置
CIS读取代码仓库根目录下的可选`.env`文件（不会覆盖环境中已设置的变量）。
| 变量 | 默认值 | 含义 |
| --- | --- | --- |
| `CIS_REPO_ROOT` | `.` | 要索引的代码仓库根目录 |
| `CIS_FS_SYNC` | 开启 | 将`0`设置为禁用文件系统监视器 |
| `CIS_FS_POLL_ONLY` | 关闭 | 强制使用mtime轮询而不是本地通知 |
| `CIS_INDEX_DEBOUNCE_MS` | - | 文件系统事件后重新索引的防抖延迟 |
| `CIS_MCP_SKIP_INDEX` | 关闭 | 跳过启动Python遍历 |
| `CIS_GIT_BRANCH_SYNC` | 关闭 | 将`1`设置为将git `HEAD`镜像到CIS分支 |
| `CIS_POLICY_PATH` | `.cis/ranking_policy.yaml` | 搜索排名策略文件 |
| `CIS_EMBED_API_URL` | - | OpenAI兼容的`/v1/embeddings`端点 |
| `CIS_EMBED_API_KEY` | - | 嵌入的API密钥（本地服务器不需要） |
| `CIS_EMBED_MODEL` | - | 嵌入模型名称 |
| `CIS_EMBED_DIM` | - | 向量维度（`all-MiniLM-L6-v2`为384） |
| `CIS_WAL_MEMORY` | 关闭 | 内存WAL（仅限测试） |
参见`cis-core`源代码和`cis-mcp/src/lib.rs`模块文档以获取完整的调整旋钮集。
## Cargo功能
| 功能 | Crate | 效果 |
| --- | --- | --- |
| `python-ast` | cis-mcp → cis-core | Tree-sitter Python摄入（类，方法，调用） |
| `body-sqlite` | cis-mcp → cis-core | SQLite正文/元数据后端；启用`cis`迁移命令 |
| `api-embeddings` | cis-mcp → cis-core | 用于语义搜索的HTTP嵌入提供程序 |
| `fs-notify` | cis-mcp → cis-core | 本机文件系统通知（默认开启） |
## 测试
```bash
# 核心库 + 集成测试
cargo test -p cis-core --features tree-sitter,body-sqlite
# 快速并发压力套件
cargo test -p cis-core --features tree-sitter,body-sqlite --test stress_fast
# WAL crate
cargo test -p cis-wal
```
CI在`main`分支上运行推送/PR（参见`.github/workflows/`）。国际象棋pygame夹具在CI中克隆；本地：
```bash
git clone --depth 1 https://github.com/abdissa-png/A-chess-game-using-Pygame.git fixtures/chess_pygame
```
## 项目布局
```
cis/
├── cis-core/ # 引擎（图谱，摄入，合并，查询，MCP运行时）
├── cis-wal/ # 预写日志
├── cis-mcp/ # MCP服务器 + 二进制文件
├── scripts/ # 演示/评估助手；嵌入服务器设置（参见README）
│ ├── setup_embed_venv.sh
│ ├── run_embed_server.sh
│ ├── requirements-embed.txt
│ └── local_embed_server.py
├── fixtures/ # 本地测试代码仓库（gitignored；克隆用于测试）
└── .github/workflows/ # CI
```
## 状态
**版本0.1.0** — 适用于中等大小代码仓库的本地代理工作流。已知限制：
- 完整的内存图谱；用于语义搜索的平面ANN（大型单体仓库需要扩展工作）
- 通过标准输入输出的MCP，具有受信任的本地会话（无网络身份验证）
- 可观察性主要是`eprintln!`加上`system_status` / 合并指标JSONL
## 许可证
MIT
