# pi

**Repository Path**: marcus_3/pi

## Basic Information

- **Project Name**: pi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-06
- **Last Updated**: 2026-11-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# README

## Pi 项目级工作流

Pi 使用项目内 `.pi/mcp.json` 启动 CBM、CRG、Serena、Xerj 和 context-mode；本地二进制仍来自根目录 `.tools/`，不依赖用户级 MCP 注册。Serena 固定使用 classic `tools` 接口，使 Pi 能在 `replace_*`、`insert_*`、`rename_*` 等具体写操作前执行 preflight 门禁。首次运行前确认 Xerj 节点已经监听 `http://localhost:9200`，或用 `XERJ_URL` 指向其它地址。

在仓库根目录执行：

```powershell
pi mcp list
pi
```

授信项目后，Pi 会通过 `.pi/extensions/workflow/package.json` 的显式 manifest 加载三个扩展：

- `workflow-policy.js`：Pi 的 `edit`/`write` 及 Serena 的具体写操作必须先获得本轮 CBM 与 CRG 覆盖目标文件的结果，并且最后一次成功 `read` 必须读取同一文件。源文件仍要求两种图谱共同覆盖；对测试文件，在两种图谱均成功但其中一个未建模测试文件时，允许已覆盖图谱加当前读取作为窄回退。图工具失败或写入成功后，preflight 立即失效。该扩展还会阻止 `xerj_search` 后直接进行 Serena `find_symbol` 或文本搜索，要求先评估结果或读取相关文件。
- `context-mode-xerj-followup.js`：成功的 `context-mode` `ctx_execute`/`ctx_batch_execute` 调用包含 `find`、`grep`、`rg` 或 `cat` 时，最多追加三条本地 Xerj 跟随检索结果；检索失败不会影响原工具结果。
- `code-intelligence.js`：提供 `/index-codebase`，依次刷新 Xerj、CBM、Serena 和 CRG 索引。默认不自动索引；设置 `PI_AUTO_INDEX=startup` 仅在 Pi 进程启动时后台索引，设置 `PI_AUTO_INDEX=always` 则在每个 `session_start` 后台索引。

扩展目录中的 helper 位于 `lib/`，不作为自动发现入口加载。

也可在 PowerShell 中显式刷新索引：

```powershell
node .\scripts\code-intelligence.mjs
```

启动包装器可在不启动服务的情况下检查目标程序解析：

```powershell
$env:MCP_SERVER_DRY_RUN = "1"
node .\scripts\mcp-server.mjs crg
Remove-Item Env:MCP_SERVER_DRY_RUN
```

Pi 集成的纯逻辑测试：

```powershell
node --test .\test\code-intelligence.test.mjs
```

运行时日志和 Serena runtime 写入 `.pi/logs/` 与 `.pi/runtime/`，由 `.gitignore` 排除。

## 克隆后启动（Claude Code）

### 环境要求

- Windows x64、Node.js `>=22.5.0`、npm 和 Claude Code。
- Xerj 节点需在本机运行，默认监听 `http://localhost:9200`。
- MCP 二进制位于项目根目录 `.tools/`：CBM、CRG、Serena、Xerj。当前工作区的 `.tools/` 尚未纳入 Git 跟踪，因此普通 `git clone` 不会下载这些程序。克隆后若 `.tools/` 不存在，需先取得与平台匹配的项目工具包并解压到仓库根目录；仅有 `.mcp.json` 无法启动这些 MCP。

### 启动

在 PowerShell 中从仓库根目录执行：

```powershell
git clone <仓库地址>
Set-Location <仓库目录>
```

确认 `.tools/` 已随发布包提供或已恢复，然后安装项目级 context-mode：

```powershell
npm ci
```

`npm ci` 根据 `package-lock.json` 安装固定版本 `context-mode@1.0.169` 到本地 `node_modules`；无需全局安装。

如果 Xerj 尚未运行，另开一个 PowerShell 窗口启动本地节点并保持运行：

```powershell
& ".\.tools\xerj\xerj.exe" --insecure --data-dir "$env:LOCALAPPDATA\Xerj\data"
```

回到仓库根目录启动 Claude Code：

```powershell
claude
```

首次启动时信任项目，并批准 `.mcp.json` 中的五个项目级 MCP：`cbm`、`crg`、`serena`、`xerj`、`context-mode`。检查连接状态：

```powershell
claude mcp list
```

五个服务都应显示 `Connected`。项目 MCP 使用相对路径；请从仓库根目录启动 Claude Code。

> 当前 `.tools/` 提供 Windows `.exe`。Linux/macOS 需要对应平台的工具包；仅运行 `npm ci` 不会安装这些二进制。

## 项目级 MCP 与工具布局

Claude Code 通过根目录 `.mcp.json` 和 `.claude/mcp-server.mjs` 启动本地 MCP；Codex 通过 `.codex/config.toml` 启动相同的 `.tools/` 程序。`.claude/`、`.codex/` 保存各自平台配置、hooks 和 agents；共享 MCP 工具放在 `.tools/`。

| MCP | 项目内程序 | 启动方式 |
|---|---|---|
| CRG | `.tools/crg/Scripts/code-review-graph.exe` | `mcp --repo <当前项目根目录>` |
| CBM | `.tools/cbm/codebase-memory-mcp.exe` | stdio；项目名与 runtime key 从当前项目根目录生成 |
| Serena | `.tools/serena/Scripts/serena.exe` | `start-mcp-server --project-from-cwd --transport stdio --agent-interface tools` |
| Xerj | `.tools/xerj/xerj.exe` | `mcp`，连接 `XERJ_URL`（默认 `http://localhost:9200`）|
| context-mode | `node_modules/context-mode/cli.bundle.mjs` | 项目本地固定版本 `1.0.169`，由 `npm ci` 安装 |

Codex 的 hooks 和角色分别位于 `.codex/hooks`、`.codex/agents`。Serena runtime 位于 `.codex/runtime/serena`（Codex）或 `.claude/runtime/serena`（Claude Code）；npm 与 uv 缓存位于 `.codex/cache`。

Codex MCP 可在仓库根目录重新启动并信任项目。`.codex/config.toml` 中的工具程序路径相对项目根；CBM cache/runtime 路径目前按本机 Windows 配置，换机器时需检查 `.codex/config.toml` 中对应路径与 ACL。

CBM 和 Xerj 的索引名/prefix 默认由当前项目根目录名规范化生成；可通过 `XERJ_PREFIX` 显式覆盖 Xerj prefix。CBM cache 使用主机私有目录 `%LOCALAPPDATA%\codebase-memory-mcp`，runtime 子目录以完整项目路径 slug 隔离，避免项目间 daemon 状态冲突。

hook 行为验证：

```powershell
node --test .claude/hooks/hooks.test.mjs
node --test .codex/hooks/hooks.test.mjs
```

Claude 索引日志见 `.claude/logs/index-hooks.log`，Codex 索引日志见 `.codex/logs/index-hooks.log`。协同规则分别见 `CLAUDE.md` 和 `AGENTS.md`。

## 安装与部署

### Hindsight

#### 拉取镜像

可通过 [渡渡鸟镜像](https://docker.aityp.com/) 获取镜像。

```bash
docker pull swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/vectorize-io/hindsight:latest
docker tag swr.cn-north-4.myhuaweicloud.com/ddn-k8s/ghcr.io/vectorize-io/hindsight:latest ghcr.io/vectorize-io/hindsight:latest
```

以下示例适用于 Windows PowerShell。请将 `<HINDSIGHT_DATA_PATH>` 替换为实际持久化目录，并通过安全的环境变量或密钥管理方式提供模型 API Key；不要把真实密钥写进 README、命令历史或版本库。

```powershell
docker run -d `
  --name hindsight `
  --restart unless-stopped `
  --user hindsight `
  -p 8888:8888 `
  -p 9999:9999 `
  -e HINDSIGHT_ENABLE_API=true `
  -e HINDSIGHT_ENABLE_CP=true `
  -e HINDSIGHT_API_HOST=0.0.0.0 `
  -e HINDSIGHT_API_PORT=8888 `
  -e HINDSIGHT_CP_DATAPLANE_API_URL=http://localhost:8888 `
  -e HINDSIGHT_API_LOG_LEVEL=info `
  -e NODE_ENV=production `
  -e PYTHONUNBUFFERED=1 `
  -e HINDSIGHT_API_LLM_PROVIDER=openai `
  -e HINDSIGHT_API_LLM_BASE_URL=https://api.deepseek.com `
  -e HINDSIGHT_API_LLM_API_KEY=$env:HINDSIGHT_API_LLM_API_KEY `
  -e HINDSIGHT_API_LLM_MODEL=deepseek-flash `
  -e HINDSIGHT_API_EMBEDDINGS_PROVIDER=local `
  -e HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-small-en-v1.5 `
  -e HINDSIGHT_API_RERANKER_PROVIDER=local `
  -e HINDSIGHT_API_RERANKER_LOCAL_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2 `
  -e HINDSIGHT_API_MODEL_INIT_TIMEOUT=900 `
  -e HF_ENDPOINT=https://hf-mirror.com `
  -e HF_HUB_DOWNLOAD_TIMEOUT=600 `
  -e TOKENIZERS_PARALLELISM=false `
  -e TRANSFORMERS_VERBOSITY=error `
  -e HF_HUB_VERBOSITY=error `
  -v hindsight-cache:/home/hindsight/.cache `
  -v <HINDSIGHT_DATA_PATH>:/home/hindsight/.pg0 `
  ghcr.io/vectorize-io/hindsight:0.5.2
```

### Xerj

Windows PowerShell 安装示例：

```powershell
irm https://xerj.org/get.ps1 | iex
```

运行远程安装脚本前，建议先查看脚本内容并确认来源可信。

### Context Mode

```bash
npm install -g context-mode
```

### Code Review Graph

```bash
pip install code-review-graph          # 或：pipx install code-review-graph
code-review-graph install              # 检测已安装的 AI 编程工具并配置

# 指定平台
code-review-graph install --platform cursor
code-review-graph install --platform codebuddy
```

### Codebase Memory MCP

```powershell
# 1. 下载安装脚本
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. （可选但建议）先检查脚本内容
notepad install.ps1

# 3. 解除下载文件的阻止标记
Unblock-File .\install.ps1

# 4. 执行安装脚本
.\install.ps1
```

### Serena

```bash
uv tool install -p 3.13 serena-agent
```

### GSD

由于 Oh My Pi（OMP）不是 GSD 的一等执行平台，可使用独立维护的 `gsd-for-omp`：

```bash
npm install -g gsd-for-omp
gsd-for-omp install
```

其他平台可按 GSD 官方安装说明操作，例如：

```bash
npx @opengsd/gsd-core@latest
```

请以目标平台当前的官方文档为准。

## 使用

### Xerj

```bash
xerj --insecure --data-dir <XERJ_DATA_DIRECTORY>
```

启动后，终端会输出一个包含访问令牌的 UI 链接。通过该链接登录界面；不要公开分享此链接或令牌。

### Serena

```bash
serena init
```

### Code Review Graph

```bash
code-review-graph build  # 分析当前代码库
```