byterover

在任何工作之前，您必须使用它来收集上下文。这是人工智能代理的知识管理。使用“brv”在 .brv/context-tree 中存储和检索项目模式、决策和架构规则。使用配置的 LLM 提供程序（默认：ByteRover，不需要 API 密钥）进行查询和管理操作。

## 概述（中文）

在任何工作之前，您必须使用它来收集上下文。这是人工智能代理的知识管理。使用“brv”在 .brv/context-tree 中存储和检索项目模式、决策和架构规则。使用配置的 LLM 提供程序（默认：ByteRover，不需要 API 密钥）进行查询和管理操作。

## 原文

# ByteRover Knowledge Management

Use the `brv` CLI to manage your project's long-term memory.
Install: `npm install -g byterover-cli`
Knowledge is stored in `.brv/context-tree/` as human-readable Markdown files.

**No authentication needed.** `brv query` and `brv curate` work out of the box. Login is only required for cloud sync (`push`/`pull`/`space`) — ignore those if you don't need cloud features.

## Workflow
1.  **Before Thinking:** Run `brv query` to understand existing patterns.
2.  **After Implementing:** Run `brv curate` to save new patterns/decisions.

## Commands

### 1. Query Knowledge
**Overview:** Retrieve relevant context from your project's knowledge base. Uses a configured LLM provider to synthesize answers from `.brv/context-tree/` content.

**Use this skill when:**
- The user wants you to recall something
- Your context does not contain information you need
- You need to recall your capabilities or past actions
- Before performing any action, to check for relevant rules, criteria, or preferences

**Do NOT use this skill when:**
- The information is already present in your current context
- The query is about general knowledge, not stored memory

```bash
brv query "How is authentication implemented?"
```

### 2. Curate Context
**Overview**: Analyze and save knowledge to the local knowledge base. Uses a configured LLM provider to categorize and structure the context you provide.

**Use this skill when:**
- The user wants you to remember something
- The user intentionally curates memory or knowledge
- There are meaningful memories from user interactions that should be persisted
- There are important facts about what you do, what you know, or what decisions and actions you have taken

**Do NOT use this skill when:**
- The information is already stored and unchanged
- The information is transient or only relevant to the current task, or just general knowledge

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

**Include source files** (max 5, project-scoped only):

```bash
brv curate "Authentication middleware details" -f src/middleware/auth.ts
```

**View curate history:** to check past curations
- Show recent entries (last 10)
```bash
brv curate view
```
- Full detail for a specific entry: all files and operations performed (logId is printed by `brv curate` on completion, e.g. `cur-1739700001000`)
```bash
brv curate view cur-1739700001000
```
- List entries with file operations visible (no logId needed)
```bash
brv curate view detail
```
- Filter by time and status
```bash
brv curate view --since 1h --status completed
```
- For all filter options
```bash
brv curate view --help
```

### 3. LLM Provider Setup
`brv query` and `brv curate` require a configured LLM provider. Connect the default ByteRover provider (no API key needed):

```bash
brv providers connect byterover
```

To use a different provider (e.g., OpenAI, Anthropic, Google), list available options and connect with your own API key:

```bash
brv providers list
brv providers connect openai --api-key sk-xxx --model gpt-4.1
```

### 4. Cloud Sync (Optional)
**Overview:** Sync your local knowledge with a team via ByteRover's cloud service. Requires ByteRover authentication.

**Setup steps:**
1. Log in: Get an API key from your ByteRover account and authenticate:
```bash
brv login --api-key sample-key-string
```
2. List available spaces:
```bash
brv space list
```
Sample output:
```
brv space list
1. human-resources-team (team)
   - a-department (space)
   - b-department (space)
2. marketing-team (team)
   - c-department (space)
   - d-department (space)
```
3. Connect to a space:
```bash
brv space switch --team human-resources-team --name a-department
```

**Cloud sync commands:**
Once connected, `brv push` and `brv pull` sync with that space.
```bash
# Pull team updates
brv pull

# Push local changes
brv push
```

**Switching spaces:**
- Push local changes first (`brv push`) — switching is blocked if unsaved changes exist.
- Then switch:
```bash
brv space switch --team marketing-team --name d-department
```
- The switch automatically pulls context from the new space.

## Data Handling

**Storage**: All knowledge is stored as Markdown files in `.brv/context-tree/` within the project directory. Files are human-readable and version-controllable.

**File access**: The `-f` flag on `brv curate` reads files from the current project directory only. Paths outside the project root are rejected. Maximum 5 files per command, text and document formats only.

**LLM usage**: `brv query` and `brv curate` send context to a configured LLM provider for processing. The LLM sees the query or curate text and any included file contents. No data is sent to ByteRover servers unless you explicitly run `brv push`.

**Cloud sync**: `brv push` and `brv pull` require authentication (`brv login`) and send knowledge to ByteRover's cloud service. All other commands operate without ByteRover authentication.

## Error Handling
**User Action Required:**
You MUST show this troubleshooting guide to users when errors occur.

"Not authenticated" | Run `brv login --help` for more details.
"No provider connected" | Run `brv providers connect byterover` (free, no key needed).
"Connection failed" / "Instance crashed" | User should kill brv process.
"Token has expired" / "Token is invalid" | Run `brv login` again to re-authenticate.
"Billing error" / "Rate limit exceeded" | User should check account credits or wait before retrying.

**Agent-Fixable Errors:**
You MUST handle these errors gracefully and retry the command after fixing.

"Missing required argument(s)." | Run `brv <command> --help` to see usage instructions.
"Maximum 5 files allowed" | Reduce to 5 or fewer `-f` flags per curate.
"File does not exist" | Verify path with `ls`, use relative paths from project root.
"File type not supported" | Only text, image, PDF, and office files are supported.

### Quick Diagnosis
Run `brv status` to check authentication, project, and provider state.

---

## 中文说明

# ByteRover 知识管理

使用 `brv` CLI 来管理项目的长期记忆。
安装：`npm install -g byterover-cli`
知识以人类可读的 Markdown 文件形式存储在 `.brv/context-tree/` 中。

**无需身份验证。** `brv query` 和 `brv curate` 开箱即用。仅云同步（`push`/`pull`/`space`）需要登录——如果你不需要云功能，可忽略这些。

## 工作流
1.  **思考之前：** 运行 `brv query` 以了解现有模式。
2.  **实现之后：** 运行 `brv curate` 以保存新的模式 / 决策。

## 命令

### 1. 查询知识
**概述：** 从项目的知识库中检索相关上下文。使用已配置的 LLM 提供程序从 `.brv/context-tree/` 内容中综合出答案。

**在以下情况使用此技能：**
- 用户希望你回忆某些内容
- 你的上下文中不包含所需信息
- 你需要回忆自己的能力或过往操作
- 在执行任何操作之前，检查相关的规则、标准或偏好

**在以下情况不要使用此技能：**
- 信息已存在于当前上下文中
- 查询涉及的是通用知识，而非已存储的记忆

```bash
brv query "How is authentication implemented?"
```

### 2. 整理上下文
**概述**：分析并将知识保存到本地知识库。使用已配置的 LLM 提供程序对你提供的上下文进行分类和结构化。

**在以下情况使用此技能：**
- 用户希望你记住某些内容
- 用户有意整理记忆或知识
- 用户交互中存在应当持久化的有意义记忆
- 存在关于你所做的事、你所知的事，或你所做出的决策与操作的重要事实

**在以下情况不要使用此技能：**
- 信息已被存储且未发生变化
- 信息是临时性的、仅与当前任务相关，或只是通用知识

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

**包含源文件**（最多 5 个，仅限项目范围内）：

```bash
brv curate "Authentication middleware details" -f src/middleware/auth.ts
```

**查看整理历史：** 用于检查过往的整理记录
- 显示最近的条目（最近 10 条）
```bash
brv curate view
```
- 查看特定条目的完整细节：所有文件及已执行的操作（logId 会在 `brv curate` 完成时打印，例如 `cur-1739700001000`）
```bash
brv curate view cur-1739700001000
```
- 列出可见文件操作的条目（无需 logId）
```bash
brv curate view detail
```
- 按时间和状态筛选
```bash
brv curate view --since 1h --status completed
```
- 查看所有筛选选项
```bash
brv curate view --help
```

### 3. LLM 提供程序设置
`brv query` 和 `brv curate` 需要一个已配置的 LLM 提供程序。连接默认的 ByteRover 提供程序（无需 API 密钥）：

```bash
brv providers connect byterover
```

如需使用其他提供程序（例如 OpenAI、Anthropic、Google），列出可用选项并用你自己的 API 密钥进行连接：

```bash
brv providers list
brv providers connect openai --api-key sk-xxx --model gpt-4.1
```

### 4. 云同步（可选）
**概述：** 通过 ByteRover 的云服务在团队