名称： byterover-headless
描述： "使用 ByteRover CLI 查询和管理知识库。使用 brv query 进行知识检索，brv curate 添加上下文，brv push/pull 进行同步。"
元数据： {"moltbot":{"emoji":"🧠","requires":{"bins":["brv"]},"install":[{"id":"npm","kind":"node","package":"@byterover/cli","bins":["brv"],"label":"安装 ByteRover CLI (npm)"}]}}

ByteRover 知识管理

使用 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 密钥进行身份验证：

brv login --api-key <密钥>

成功时输出文本：Logged in as <邮箱>。

初始化项目

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

# 使用名称
brv init --headless --team 我的团队 --space 我的空间 --format json

# 使用 ID
brv init --headless --team team-abc123 --space space-xyz789 --format json

强制重新初始化：

brv init --headless --team 我的团队 --space 我的空间 --force --format json

示例响应：

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

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

检查状态

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

brv status --headless --format json

示例响应：

{
  "success": true,
  "command": "status",
  "data": {
    "cliVersion": "1.0.0",
    "authStatus": "logged_in",
    "userEmail": "user@example.com",
    "projectInitialized": true,
    "teamName": "MyTeam",
    "spaceName": "MySpace",
    "mcpStatus": "connected",
    "contextTreeStatus": "has_changes"
  }
}

查询知识

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

brv query "身份验证是如何实现的？" --headless --format json

示例响应：

{
  "success": true,
  "command": "query",
  "data": {
    "status": "completed",
    "result": "身份验证使用 JWT 令牌...",
    "toolCalls": [{"tool": "search_knowledge", "status": "success", "summary": "5 个匹配项"}]
  }
}

添加上下文

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

brv curate "身份验证使用 JWT，有效期 24 小时。令牌通过 authMiddleware.ts 存储在 httpOnly cookie 中。" --headless --format json

包含特定文件以获取更全面的上下文（最多 5 个文件）：

brv curate "身份验证中间件验证 JWT 令牌" --files src/middleware/auth.ts --headless --format json

示例响应：

{
  "success": true,
  "command": "curate",
  "data": {
    "status": "queued",
    "taskId": "abc123",
    "message": "上下文已排队等待处理"
  }
}

推送上下文树

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

brv push --headless --format json -y

-y 参数跳过确认提示（无头模式必需）。

推送到特定分支：

brv push --branch feature-branch --headless --format json -y

示例响应：

{
  "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 云存储拉取上下文树：

brv pull --headless --format json

从特定分支拉取：

brv pull --branch feature-branch --headless --format 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 <密钥>
- 项目未初始化：运行 brv init --headless --team <团队> --space <空间> --format json
- 存在本地更改：拉取前先推送本地更改

提示

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