OpenClaw Skills 知识管理（ByteRover）技能使用参考手册

本文档为ByteRover官方工具的中文使用指南，涵盖安装、核心功能、配置及故障排查全流程，适配中文开发者使用习惯。

一、工具概述

ByteRover（简称brv）是面向AI智能体的知识库管理工具，用于存储和检索项目开发中的设计模式、决策记录、架构规则等核心信息。所有知识均以易读的Markdown格式存储在项目目录的.brv/context-tree/路径下，无需API密钥即可使用基础功能（默认LLM提供商为ByteRover），仅云端同步功能需身份验证。

核心价值：

• 开发前：通过brv query检索已有项目规则，避免重复决策；
• 开发后：通过brv curate固化新的开发经验，沉淀项目记忆。

👤 作者：maximeprades
🦞 官方地址：https://clawhub.ai/byteroverinc/byterover
👉 Skills 下载地址：byterover-2.0.0.zip

二、安装步骤

通过npm全局安装ByteRover CLI工具，执行以下命令（需提前安装Node.js环境）：

## 全局安装byterover-cli工具（中文注释：安装后可在任意项目目录执行brv命令）
npm install -g byterover-cli

三、核心工作流程

ByteRover的核心使用流程分为两步，贯穿项目开发全周期：

1. 开发前置动作：执行brv query查询已有知识库，明确项目既有规范；
2. 开发后置动作：执行brv curate将新的开发决策/规则存入知识库。

四、详细命令说明

1. 知识库查询（brv query）

功能说明

从项目知识库中检索相关上下文信息，底层通过配置的LLM提供商从.brv/context-tree/目录的内容中合成答案。

使用场景

✅ 适用场景：

• 需要回忆项目已有的开发规则/决策；
• 当前上下文未包含所需信息；
• 执行任何操作前，确认相关规则、标准或偏好；
• 回忆工具自身能力或过往操作记录。

❌ 不适用场景：

• 所需信息已在当前上下文内；
• 查询通用知识（非项目存储的专属记忆）。

代码示例（带中文注释）

## 查询认证功能的实现方式（中文注释：替换为实际想要查询的项目问题）
brv query "认证功能是如何实现的？"

2. 知识库固化（brv curate）

功能说明

分析并将项目知识保存到本地知识库，LLM提供商会自动对内容进行分类和结构化处理。

使用场景

✅ 适用场景：

• 用户要求记录某条项目规则/决策；
• 存在需要持久化的交互记忆（如关键开发结论）；
• 需保存工具的核心能力、已知事实或操作决策。

❌ 不适用场景：

• 信息已存储且无变更；
• 信息仅对当前任务有效（临时信息）；
• 通用知识（非项目专属）。

代码示例（带中文注释）

## 基础用法：固化认证相关规则（中文注释：建议描述精准，便于后续检索）
brv curate "认证使用JWT令牌，有效期24小时，令牌通过authMiddleware.ts存储在httpOnly Cookie中"


## 关联源文件：固化时绑定相关代码文件（中文注释：最多绑定5个项目内文件，路径为项目根目录相对路径）
brv curate "认证中间件详细逻辑" -f src/middleware/auth.ts


## 查看固化历史：查看最近10条固化记录（中文注释：快速核对已存储的知识）
brv curate view


## 查看单条记录详情：根据logId查询（中文注释：logId由curate命令执行后输出，如cur-1739700001000）
brv curate view cur-1739700001000


## 查看带文件操作的记录列表（中文注释：无需logId，直接展示所有含文件关联的记录）
brv curate view detail


## 按时间/状态筛选记录（中文注释：--since支持1h/1d/7d等，--status支持completed/failed）
brv curate view --since 1h --status completed


## 查看所有筛选参数（中文注释：获取view命令的完整用法）
brv curate view --help

3. LLM提供商配置

brv query和brv curate依赖LLM提供商完成内容处理，支持默认提供商（免API密钥）和第三方提供商（需配置密钥）。

代码示例（带中文注释）

## 连接默认ByteRover提供商（中文注释：无需API密钥，直接使用）
brv providers connect byterover


## 查看所有可用的LLM提供商（中文注释：确认支持的第三方提供商列表）
brv providers list


## 连接第三方提供商（以OpenAI为例，中文注释：替换为自己的API密钥和模型）
brv providers connect openai --api-key sk-xxx --model gpt-4.1

4. 云端同步（可选）

功能说明

将本地知识库与团队共享的ByteRover云端空间同步，需完成身份验证后使用。

操作步骤（带中文注释）

## 1. 登录认证（中文注释：API密钥需从ByteRover账号获取）
brv login --api-key 你的API密钥字符串


## 2. 查看可用的团队/空间（中文注释：确认可同步的云端空间）
brv space list
## 示例输出：
## 1. human-resources-team (团队)
##    - a-department (空间)
##    - b-department (空间)
## 2. marketing-team (团队)
##    - c-department (空间)
##    - d-department (空间)


## 3. 切换到指定团队/空间（中文注释：替换为实际的团队和空间名称）
brv space switch --team human-resources-team --name a-department


## 4. 拉取团队最新知识库（中文注释：同步云端更新到本地）
brv pull


## 5. 推送本地变更到云端（中文注释：本地修改后同步到团队空间）
brv push


## 6. 切换其他空间（中文注释：切换前需先推送本地未保存的变更）
brv push
brv space switch --team marketing-team --name d-department
## 注：切换后会自动拉取新空间的内容

五、数据处理规则

1. 存储方式

所有知识库内容以Markdown文件存储在项目目录的.brv/context-tree/下，文件支持版本控制（如Git），可直接编辑。

2. 文件访问限制

• 使用brv curate -f绑定文件时，仅支持项目根目录内的文件，拒绝外部路径；
• 单次最多绑定5个文件，仅支持文本、图片、PDF、办公文档格式。

3. LLM数据传输规则

• brv query/brv curate仅将内容发送给已配置的LLM提供商，未执行brv push时，数据不会发送到ByteRover服务器；
• 仅云端同步功能（push/pull/space）需ByteRover身份验证，基础功能无需认证。

六、错误处理

1. 需用户手动处理的错误

2. 工具可自动修复的错误

3. 快速诊断

执行以下命令查看工具的认证状态、项目信息、LLM提供商配置：

## 查看ByteRover整体状态（中文注释：快速定位认证/配置问题）
brv status