ByteRover - Headless

# ByteRover Knowledge Management

使用 `brv` CLI 管理您自己的知识库。ByteRover 维护一个上下文树，用于存储关于项目的模式、决策和实现细节。

**重要提示**：对于无头/自动化用途，请务必添加 `--headless --format json` 标志以获取可被机器解析的 JSON 输出。

## 设置（无头模式）

- ByteRover 可以在无头模式下完全设置。如果用户未登录或在当前工作目录中未初始化 `.brv/`（通过 `brv status --headless --format json ` 响应中的 `projectInitialized` 和 `authStatus` 检查），请用户提供： 1. **API 密钥** - 用于身份验证（从 https://app.byterover.dev/settings/keys 获取） 2. **团队和空间** - 用于项目初始化的名称或 ID

### 使用 API 密钥登录

使用 API 密钥进行身份验证：

```bash brv login --api-key <key> ```

成功时输出文本：`Logged in as <email>`。

### 初始化项目

为项目初始化 ByteRover（无头模式需要团队和空间——可以使用 ID 或名称）：

```bash # Using names brv init --headless --team my-team --space my-space --format json

# Using IDs brv init --headless --team team-abc123 --space space-xyz789 --format json ```

强制重新初始化： ```bash brv init --headless --team my-team --space my-space --force --format json ```

响应示例： ```json { "success": true, "command": "init", "data": { "status": "success", "teamName": "MyTeam", "spaceName": "MySpace", "configPath": "/path/to/project/.brv/config.json" } } ```

**注意**：您可以使用团队/空间的名称或 ID。名称匹配不区分大小写。

### 检查状态

检查 ByteRover 和项目的当前状态：

```bash brv status --headless --format json ```

响应示例： ```json { "success": true, "command": "status", "data": { "cliVersion": "1.0.0", "authStatus": "logged_in", "userEmail": "[email protected]", "projectInitialized": true, "teamName": "MyTeam", "spaceName": "MySpace", "mcpStatus": "connected", "contextTreeStatus": "has_changes" } } ```

## 查询知识

提出问题以检索相关知识：

```bash brv query "How is authentication implemented?" --headless --format json ```

响应示例： ```json { "success": true, "command": "query", "data": { "status": "completed", "result": "Authentication uses JWT tokens...", "toolCalls": [{"tool": "search_knowledge", "status": "success", "summary": "5 matches"}] } } ```

## 整理上下文

向项目的上下文树添加新知识或上下文：

```bash brv curate "Auth uses JWT with 24h expiry. Tokens stored in httpOnly cookies via authMiddleware.ts" --headless --format json ```

包含特定文件以获取全面的上下文（最多 5 个文件）： ```bash brv curate "Authentication middleware validates JWT tokens" --files src/middleware/auth.ts --headless --format json ```

响应示例： ```json { "success": true, "command": "curate", "data": { "status": "queued", "taskId": "abc123", "message": "Context queued for processing" } } ```

## 推送上下文树

将本地上下文树的更改推送到 ByteRover 云存储：

```bash brv push --headless --format json -y ```

`-y` 标志跳过确认提示（无头模式必需）。

推送到特定分支： ```bash brv push --branch feature-branch --headless --format json -y ```

响应示例： ```json { "success": true, "command": "push", "data": { "status": "success", "added": 3, "edited": 1, "deleted": 0, "branch": "main", "url": "https://app.byterover.com/team/space" } } ```

可能的状态：

- `success` - 推送完成 - `no_changes` - 没有上下文更改可推送 - `cancelled` - 推送已取消 - `error` - 推送失败

## 拉取上下文树

从 ByteRover 云存储拉取上下文树：

```bash brv pull --headless --format json ```

从特定分支拉取： ```bash brv pull --branch feature-branch --headless --format json ```

响应示例： ```json { "success": true, "command": "pull", "data": { "status": "success", "added": 5, "edited": 2, "deleted": 1, "branch": "main", "commitSha": "abc123def" } } ```

可能的状态：

- `success` - 拉取完成 - `local_changes` - 存在本地更改，请先推送 - `error` - 拉取失败

## 错误处理

始终检查 JSON 响应中的 `success` 字段：

- `success: true` - 操作成功完成 - `success: false` - 操作失败，请检查 `data.error` 或 `data.message` 了解详情

常见错误场景： - **未认证**：运行 `brv login --api-key <key>` - **项目未初始化**：运行 `brv init --headless --team <team> --space <space> --format json` - **存在本地更改**：拉取前先推送本地更改

## 提示 1. 对于拉取和推送操作，您应该先征求用户许可。 2. 自动化操作始终使用 `--headless --format json`（`brv login` 除外，它输出文本）。 3. 首先检查 `brv status --headless --format json` 以验证身份验证和项目状态。 4. 对于整理操作，请使用 `--files` 包含相关文件以获得更好的上下文。 5. 查询响应可能包含工具调用详情，显示搜索了哪些知识。 6. 对于推送操作，始终使用 `-y` 在无头模式下跳过确认。对于重新初始化，请使用 `-f` 强制重新初始化。 7. 如果存在未推送的本地更改，拉取将失败——请先推送。