# https://github.com/campfirein/byterover-cli 项目说明书

生成时间：2026-05-14 13:16:52 UTC

## 目录

- [项目概述](#project-overview)
- [系统架构](#system-architecture)
- [Agent核心系统](#agent-system)
- [LLM提供商集成](#llm-providers)
- [工具系统](#tools-system)
- [上下文树与知识管理](#context-tree)
- [版本控制系统](#version-control)
- [Swarm多代理协调](#swarm-coordination)
- [TUI交互界面](#tui-interface)
- [WebUI管理面板](#webui-dashboard)

<a id='project-overview'></a>

## 项目概述

### 相关页面

相关主题：[系统架构](#system-architecture), [Agent核心系统](#agent-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)
- [src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts)
- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)
- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)
- [src/tui/components/onboarding/welcome-box.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/onboarding/welcome-box.tsx)
- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)
</details>

# 项目概述

## 项目简介

ByteRover CLI（命令行工具）是一个交互式 REPL（Read-Eval-Print Loop）命令行工具，专为 AI 编程代理提供持久化、结构化的记忆能力。它使开发者能够将项目知识组织成上下文树（Context Tree），同步到云端，并在不同工具和团队成员之间共享。

资料来源：[README.md:1-15]()

该工具通过命令行界面 `brv` 运行，开发者可以在任何项目目录中启动，享受 AI 代理带来的智能编程体验。ByteRover 的核心设计理念是：**让 AI 代理能够理解和记忆项目上下文，从而提供更精准的代码生成和问题诊断**。

## 核心架构

### 系统组件概览

ByteRover CLI 采用模块化架构，主要包含以下核心组件：

| 组件名称 | 功能描述 | 源码位置 |
|---------|---------|---------|
| **Agent 核心** | AI 代理执行引擎，处理工具调用和推理 | `src/agent/` |
| **Sandbox 服务** | 知识策展操作的执行环境 | `src/agent/infra/sandbox/` |
| **TUI 组件** | 终端用户界面渲染 | `src/tui/` |
| **WebUI 组件** | 浏览器图形界面 | `src/webui/` |
| **传输层** | 前后端通信和事件系统 | `src/shared/transport/` |
| **模板系统** | 动态生成代理指令 | `src/server/templates/` |

### 架构流程图

```mermaid
graph TD
    A[用户终端] -->|brv 命令| B[CLI 入口]
    B --> C{交互模式}
    C -->|TUI| D[终端用户界面]
    C -->|WebUI| E[Web 浏览器界面]
    
    D --> F[Agent 执行引擎]
    E --> F
    
    F --> G[上下文树管理]
    F --> H[Sandbox 服务]
    F --> I[版本控制集成]
    
    G --> J[知识策展服务]
    H --> J
    I --> J
    
    J --> K[云端同步]
    K --> L[远程存储]
    
    F --> M[系统提示构建]
    M --> N[上下文树结构贡献者]
    N --> O[Context Tree 结构]
```

## 核心功能模块

### 1. 上下文树（Context Tree）

上下文树是 ByteRover 的核心知识组织结构，采用层次化文件管理方式存储项目知识。

资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:1-60]()

#### 目录结构规范

```
.brv/context-tree/
├── [domain]/              # 顶级域名（动态创建）
│   ├── [topic].md         # 主题文件
│   └── [subtopic]/
│       └── context.md     # 子主题内容
├── _index.md              # 自动生成的目录摘要
└── _archived/             # 归档的低优先级条目
```

#### 动态域名系统

- **域名创建**：根据策展内容的语义动态创建
- **命名规范**：使用 snake_case 格式（如 `architecture`、`market_trends`）
- **组织原则**：在创建新域名之前，应检查现有域名是否可容纳内容

### 2. 知识策展服务（Curate Service）

知识策展服务负责对上下文树中的知识主题进行增删改查操作。

资料来源：[src/agent/infra/sandbox/curate-service.ts:1-80]()

#### 策展操作类型

| 操作类型 | 说明 | 内容要求 |
|---------|------|---------|
| `ADD` | 添加新主题 | 需要 title 和 content |
| `UPDATE` | 更新现有主题 | 需要 title 和/或 content |
| `UPSERT` | 存在则更新，不存在则创建 | 需要 title 和 content |
| `DELETE` | 删除主题 | 只需要 path |

#### 内容存储格式

策展内容支持多种数据类型的存储：

- **事实（Factual）**：个人、项目配置、团队约定等
- **图表（Diagrams）**：Mermaid、PlantUML、ASCII 图表
- **决策（Decisions）**：包含完整理由的决策文本
- **流程（Flow）**：工作流步骤和条件

### 3. 版本控制集成（VC Events）

ByteRover 内置了类似 Git 的版本控制功能，支持分布式团队协作。

资料来源：[src/shared/transport/events/vc-events.ts:1-50]()

#### 差异比较模式

| 模式 | 说明 | Git 对应 |
|-----|------|---------|
| `unstaged` | 工作目录 vs 暂存区 | `git diff` |
| `staged` | 暂存区 vs HEAD | `git diff --staged` |
| `ref-vs-worktree` | 指定引用 vs 工作目录 | `git diff <ref>` |
| `range` | 两个引用之间 | `git diff <ref1>..<ref2>` |

#### 版本控制命令

```bash
brv vc add .                    # 暂存所有文件
brv vc add notes.md docs/       # 暂存指定文件
brv vc commit -m "add patterns" # 提交更改
brv vc log                      # 查看历史
brv vc branch feature/auth      # 创建分支
brv vc merge feature/auth       # 合并分支
```

### 4. 模板系统（Template System）

模板系统用于根据用户选择的 AI 代理动态生成指令规则。

资料来源：[src/server/templates/README.md:1-40]()

#### 模板目录结构

```
src/templates/
├── base.md                      # 主模板结构
├── sections/                    # 可复用内容区块
│   ├── workflow.md              # 工作流指南
│   └── command-reference.md     # 命令参考文档
└── README.md                    # 本说明文件
```

#### 模板变量

| 变量名 | 说明 | 示例 |
|-------|------|------|
| `{{agent_name}}` | 代理名称 | "Claude Code", "Cursor" |
| `{{workflow}}` | 工作流内容 | sections/workflow.md |
| `{{command_reference}}` | 命令参考 | sections/command-reference.md |

### 5. 用户界面

ByteRover 提供两种用户界面选项：

#### 终端用户界面（TUI）

基于终端的交互式界面，支持以下功能：

- 实时执行日志展示
- 文件变更追踪
- 推理内容显示
- 欢迎引导界面

资料来源：[src/tui/components/onboarding/welcome-box.tsx:1-50]()

#### Web 用户界面（WebUI）

浏览器图形界面，提供：

- 上下文历史面板
- Hub 组件展示
- 离线状态处理
- 传输层事件处理

## 数据流与状态管理

### 代理执行流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant TUI as TUI 界面
    participant Agent as Agent 引擎
    participant Sandbox as Sandbox 服务
    participant Tree as 上下文树
    participant Cloud as 云端

    User->>TUI: 输入命令
    TUI->>Agent: 转发请求
    Agent->>Agent: 执行推理
    Agent->>Sandbox: 调用工具
    Sandbox->>Tree: 读写知识
    Tree-->>Sandbox: 返回数据
    Sandbox-->>Agent: 执行结果
    Agent->>Cloud: 同步变更
    Cloud-->>Agent: 确认
    Agent-->>TUI: 返回响应
    TUI-->>User: 展示结果
```

### 知识策展操作流

```mermaid
graph TD
    A[发起策展操作] --> B{操作类型验证}
    B -->|有效| C[验证必需字段]
    B -->|无效| D[返回失败]
    C -->|完整| E[执行文件操作]
    C -->|不完整| F[返回失败]
    E --> G[更新上下文树]
    G --> H[生成摘要]
    H --> I[同步云端]
```

## 命令行接口

### 核心命令

| 命令 | 功能 | 示例 |
|-----|------|------|
| `brv login` | 用户认证 | `brv login` |
| `brv init` | 初始化项目 | `brv init` |
| `brv status` | 查看状态 | `brv status` |
| `brv add` | 添加上下文 | `brv add ./docs` |
| `brv gen-rules` | 生成代理规则 | `brv gen-rules` |
| `brv push` | 推送到云端 | `brv push` |
| `brv watch` | 监听文件变更 | `brv watch` |
| `brv cipher-agent` | 代理加密 | `brv cipher-agent` |

### Space 命令

| 命令 | 功能 |
|-----|------|
| `brv space list` | 列出所有空间 |
| `brv space switch` | 切换当前空间 |

## 技术特点

### 设计原则

1. **持久化记忆**：为 AI 代理提供跨会话的项目上下文记忆
2. **结构化组织**：使用树形结构管理知识，便于检索
3. **云端同步**：支持团队协作和跨设备同步
4. **多代理支持**：兼容多种 AI 编码代理（Claude Code、Cursor 等）
5. **自包含**：WebUI 采用全内联 CSS/JS，无外部依赖

### 安全性

- 支持代理加密功能（`cipher-agent`）
- 版本控制支持分支管理和合并冲突解决
- 敏感操作需要用户确认（如 Approve/Reject）

## 快速入门

```bash
# 安装 CLI
npm install -g byterover-cli

# 登录认证
brv login

# 初始化项目
brv init

# 启动交互式 REPL
brv

# 在 REPL 中策展知识
/curate

# 查询相关记忆
/query <关键词>

# 同步到云端
brv push
```

## 相关文档

- [工作流指南](./workflow.md)
- [命令参考](./command-reference.md)
- [技能模板](./skill/SKILL.md)

---

<a id='system-architecture'></a>

## 系统架构

### 相关页面

相关主题：[项目概述](#project-overview), [Agent核心系统](#agent-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)
- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)
- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)
- [src/server/infra/provider-oauth/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/provider-oauth/callback-server.ts)
- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)
- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)
- [src/tui/features/vc/pull/components/vc-pull-flow.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/vc/pull/components/vc-pull-flow.tsx)
- [README.md](https://github.com/campfirein/byterover-cli/blob/main/README.md)
</details>

# 系统架构

## 概述

ByteRover CLI（命令行工具 `brv`）是一个为 AI 编程代理提供持久化、结构化记忆的交互式 REPL 工具。它允许开发者在上下文树中管理项目知识，与云端同步，并跨工具和团队共享。 资料来源：[README.md]()

该系统采用分层架构设计，核心层负责 AI 代理的上下文管理与操作，传输层处理客户端与服务器之间的实时通信，呈现层同时支持终端界面（TUI）和网页界面（WebUI）两种交互模式。

## 整体架构

```mermaid
graph TD
    subgraph 客户端层
        TUI[TUI 终端界面]
        WebUI[WebUI 网页界面]
    end
    
    subgraph 传输层
        SocketIO[Socket.IO 传输服务器]
        HTTP[HTTP 服务器]
    end
    
    subgraph 核心层
        Agent[Agent 核心]
        Sandbox[沙箱环境]
        CurateService[Curate 服务]
    end
    
    subgraph 基础设施层
        VcEvents[VC 事件系统]
        AbstractGen[抽象生成器]
        OutputGen[输出生成器]
        ReviewUI[审查 UI]
    end
    
    TUI <--> SocketIO
    WebUI <--> HTTP
    SocketIO <--> Agent
    HTTP <--> Agent
    Agent <--> Sandbox
    Sandbox <--> CurateService
    Agent <--> VcEvents
    Agent <--> AbstractGen
    Agent <--> OutputGen
```

## 分层架构详解

### 1. 客户端层

ByteRover CLI 提供两种用户界面，以满足不同使用场景的需求：

| 界面类型 | 技术栈 | 适用场景 |
|---------|--------|----------|
| TUI | React + Ink | 终端重度用户，习惯命令行操作 |
| WebUI | React + TailwindCSS | 偏好图形界面，需要可视化操作 |

#### TUI 组件结构

TUI（终端用户界面）采用组件化设计，主要组件位于 `src/tui/` 目录：

- **执行组件**：`ExecutionProgress`、`ExecutionContent`、`ExecutionChanges` 用于展示代理执行过程
- **VC 组件**：`VcPullFlow` 处理版本控制拉取流程
- **Hub 组件**：`HubDetailStep` 展示技能详情

```tsx
// 执行日志视图 - 展示流式内容
{log.streamingContent && log.status === 'running' && (
  <StreamingText
    content={log.streamingContent}
    isStreaming={Boolean(log.isStreaming)}
    maxLines={0}
    showCursor={Boolean(log.isStreaming)}
  />
)}
```

资料来源：[src/tui/components/execution/expanded-log-view.tsx:36-42]()

### 2. 传输层

传输层负责客户端与服务器之间的通信，采用双协议支持：

#### Socket.IO 传输服务器

基于 Socket.IO 实现实时双向通信，适用于需要即时反馈的场景：

```typescript
// 核心传输服务器职责：
// - 管理客户端连接生命周期
// - 处理实时事件分发
// - 维护连接状态
```

#### HTTP 服务器

HTTP 服务器处理同步请求和回调流程，主要用途包括：

- OAuth 认证回调处理
- 静态资源服务
- HITL（人机回环）审查 UI 服务

```typescript
function errorHtml(message: string): string {
  return `<!DOCTYPE html>
<html>
<head>
  <title>ByteRover - Authorization Failed</title>
  ...
</head>
</html>`
}
```

资料来源：[src/server/infra/provider-oauth/callback-server.ts:42-59]()

### 3. 核心层

核心层是系统的中枢，包含 AI 代理的主要逻辑：

#### Agent 核心模块

代理核心负责：
- 理解代码库结构和语义
- 读取和写入文件
- 管理上下文树状态
- 与 LLM 交互生成响应

#### Curate 服务

`CurateService` 是核心层的重要组成部分，提供知识主题的组织和领域检测功能：

```typescript
export class CurateService implements ICurateService {
  private readonly workingDirectory: string

  constructor(
    workingDirectory?: string,
    private readonly abstractQueue?: AbstractGenerationQueue,
    private readonly runtimeSignalStore?: IRuntimeSignalStore,
  ) {
    this.workingDirectory = workingDirectory ?? process.cwd()
  }
}
```

资料来源：[src/agent/infra/sandbox/curate-service.ts:66-76]()

#### Curate 操作验证

系统对 Curate 操作有严格的验证规则：

| 操作类型 | 必需字段 | 说明 |
|---------|---------|------|
| ADD | title, content | 添加新知识条目 |
| UPDATE | title, content | 更新现有条目 |
| UPSERT | title, content | 存在则更新，不存在则创建 |
| DELETE | path | 删除指定路径的条目 |

```typescript
// 操作验证逻辑
if ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.title) {
  failures.push({
    message: `${op.type} operation requires a title (becomes the .md filename).`,
    path: op.path,
    status: 'failed',
    type: op.type,
  })
}
```

资料来源：[src/agent/infra/sandbox/curate-service.ts:41-49]()

### 4. 基础设施层

基础设施层为上层提供通用能力支持：

#### VC 事件系统

版本控制事件系统定义完整的 Diff 模式和数据模型：

```typescript
export type VcDiffMode =
  | {from: string; kind: 'range'; to: string}
  | {kind: 'ref-vs-worktree'; ref: string}
  | {kind: 'staged'}
  | {kind: 'unstaged'}
```

资料来源：[src/shared/transport/events/vc-events.ts:14-21]()

支持的 Diff 模式：

| 模式 | 说明 | 对应 Git 命令 |
|------|------|---------------|
| unstaged | 工作目录 vs 暂存区 | `git diff` |
| staged | HEAD vs 暂存区 | `git diff --staged` |
| ref-vs-worktree | 指定提交 vs 工作目录 | `git diff <ref>` |
| range | 提交范围对比 | `git diff <ref1>..<ref2>` |

#### 抽象生成器

`AbstractGenerator` 负责从知识文档生成结构化摘要：

```typescript
function parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map<string, string>
```

输出格式采用 XML 结构：
```xml
<file path="<path>"><overview>
- bullet 1
- bullet 2
</overview></file>
```

资料来源：[src/agent/infra/map/abstract-generator.ts:47-67]()

#### 输出生成器

`OutputGenerator` 负责将文件夹打包结果转换为 XML 格式输出：

```typescript
// 生成文件类型分布统计
const typeBreakdown = new Map<string, number>()
for (const file of result.files) {
  const fileType = file.fileType ?? 'unknown'
  typeBreakdown.set(fileType, (typeBreakdown.get(fileType) ?? 0) + 1)
}
```

资料来源：[src/agent/infra/folder-pack/output-generator.ts:37-41]()

#### 审查 UI 生成

HITL 审查 UI 是自包含的 HTML 页面，内嵌所有 CSS 和 JavaScript：

```typescript
export function getReviewPageHtml(): string {
  return `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ByteRover Review</title>
<style>
  :root {
    --bg: #0d1117;
    --bg-secondary: #161b22;
    ...
  }
</style>
</head>
...`
}
```

资料来源：[src/server/infra/http/review-ui.ts:7-28]()

## 命令行入口

系统通过 `oclif` 框架实现命令行入口，主要命令位于 `src/oclif/commands/`：

```bash
brv login           # 用户认证
brv init            # 初始化项目
brv status          # 查看状态
brv add             # 添加文件到上下文
brv gen-rules       # 生成代理规则
brv push            # 推送到云端
brv watch           # 监听文件变化
brv vc              # 版本控制命令
```

资料来源：[src/server/templates/skill/SKILL.md:1-20]()

## 云端同步架构

```mermaid
sequenceDiagram
    participant Client as 客户端 (brv)
    participant Server as ByteRover Cloud
    participant Space as Space 工作区
    
    Client->>Server: brv login
    Server-->>Client: 认证成功
    Client->>Space: brv vc push/pull
    Space-->>Client: 同步完成
```

云端同步功能要求：
- 完成 ByteRover 认证（`brv login`）
- 配置远程仓库地址
- 可通过 Web 应用创建或打开 Space

资料来源：[src/tui/features/vc/pull/components/vc-pull-flow.tsx:1-15]()

## 模板系统

ByteRover 使用模板系统生成代理指令，通过 `brv gen-rules` 命令触发：

```
src/templates/
├── base.md                      # 主模板结构
├── sections/                    # 可复用内容区段
│   ├── workflow.md              # 工作流指南
│   └── command-reference.md     # 命令参考文档
└── README.md
```

模板变量替换：
- `{{agent_name}}` - 代理名称
- `{{workflow}}` - 工作流内容
- `{{command_reference}}` - 命令参考内容

资料来源：[src/server/templates/README.md:1-30]()

## 技术栈总结

| 层级 | 主要技术 | 文件位置 |
|------|---------|----------|
| 客户端 | React, Ink, TailwindCSS | `src/tui/`, `src/webui/` |
| 传输 | Socket.IO, Node.js HTTP | `src/server/infra/transport/` |
| 核心 | TypeScript | `src/agent/core/`, `src/agent/infra/` |
| 基础设施 | XML 生成, 事件系统 | `src/shared/`, `src/agent/infra/` |
| CLI | oclif | `src/oclif/` |

---

<a id='agent-system'></a>

## Agent核心系统

### 相关页面

相关主题：[LLM提供商集成](#llm-providers), [工具系统](#tools-system), [上下文树与知识管理](#context-tree)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)
- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)
- [src/agent/infra/process/command-validator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)
- [src/agent/infra/folder-pack/output-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/folder-pack/output-generator.ts)
</details>

# Agent核心系统

## 概述

ByteRover CLI 的 Agent 核心系统是一个模块化的基础设施架构，负责为 AI Agent 提供运行时环境、命令安全验证、知识管理和输出生成能力。该系统采用分层设计，核心基础设施包括：

- **抽象生成器**（Abstract Generator）：处理知识文档的结构化概览生成
- **策展服务**（Curate Service）：管理知识主题的增删改查操作
- **命令验证器**（Command Validator）：提供命令安全性和权限校验
- **输出生成器**（Output Generator）：生成结构化的文件夹打包输出

## 系统架构

```mermaid
graph TB
    subgraph "Agent 核心基础设施"
        AG[Agent Core]
    end
    
    subgraph "Infra Layer"
        MAP[Map/Abstract Generator<br/>src/agent/infra/map/]
        SBX[Sandbox/Curate Service<br/>src/agent/infra/sandbox/]
        PROC[Process/Command Validator<br/>src/agent/infra/process/]
        OUT[Folder Pack/Output Generator<br/>src/agent/infra/folder-pack/]
    end
    
    AG --> MAP
    AG --> SBX
    AG --> PROC
    AG --> OUT
```

## 抽象生成器（Abstract Generator）

### 功能定位

`abstract-generator.ts` 负责从知识文档集合中生成结构化的概览信息，支持 XML 格式的批量处理和解析。

### 核心能力

| 能力 | 描述 |
|------|------|
| 文档包装 | 将文件路径和内容封装为 XML 格式 |
| 概览生成 | 提示 LLM 生成 markdown 格式的结构化摘要 |
| 批量解析 | 从模型输出中提取 `<file>` 和 `<abstract>/<overview>` 标签 |

### XML 格式规范

系统使用 CDATA 块保护内容，避免 XML 转义问题：

```xml
<file path="${escapeXmlAttr(it.contextPath)}">
  <document><![CDATA[${it.content}]]></document>
</file>
```

### 解析策略

`parseBatchedTags` 函数采用锚定策略进行容错解析：

- 以 `<file path="...">` 开启标签为锚点
- 每个开启标签own对应到下一个开启标签前的响应切片
- 内部正则提取该切片中的 payload
- 此设计避免模型输出中包含 `</file>` 字面量时导致的错误匹配

资料来源：[src/agent/infra/map/abstract-generator.ts:28-35]()

## 策展服务（Curate Service）

### 功能定位

`curate-service.ts` 实现知识主题的策展操作，支持 ADD、UPDATE、UPSERT、DELETE 等原子操作。

### 操作验证规则

| 操作类型 | 必需字段 | 验证条件 |
|----------|----------|----------|
| ADD | title, content | title 为文件名，content 包含 rawConcept 和/或 narrative |
| UPDATE | title, content | 同 ADD |
| UPSERT | title, content | 同 ADD |
| DELETE | path | 仅需 path |

### CurateResult 结构

策展操作返回结果包含：

- `appliedOperations`：已应用的原子操作列表
- `summary`：操作摘要
- `failures`：验证失败的操作详情

```typescript
interface CurateResult {
  appliedOperations: CurateOperation[]
  summary: string
  failures: Array<{
    message: string
    path: string
    status: 'failed'
    type: OperationType
  }>
}
```

资料来源：[src/agent/infra/sandbox/curate-service.ts:1-40]()

## 命令验证器（Command Validator）

### 安全架构

命令验证器是 Agent 系统的安全防线，基于可配置的安全级别和黑白名单机制。

```mermaid
graph LR
    CMD[Command Input] --> VAL{CommandValidator}
    VAL -->|Allowed| EXEC[Execute]
    VAL -->|Blocked| REJECT[Reject + Log]
    VAL -->|Requires Approval| WAIT[Wait for Approval]
    
    style EXEC fill:#90EE90
    style REJECT fill:#FFB6C1
    style WAIT fill:#FFE4B5
```

### 内置只读命令模式

系统预定义了安全的只读命令正则：

```typescript
const READ_ONLY_PATTERNS = [
  /cat\s+.*>/,        // 读取文件内容
  /find\s+.*>/,       // 查找文件
  /git\s+(status|log|diff|show|branch|tag|fetch|pull)(?!\s+-)/i,  // Git 只读操作
]
```

### 验证流程

1. **危险模式检测**：检查是否匹配已知危险命令模式
2. **黑名单检查**：验证命令是否在 blockedCommands 列表中
3. **白名单放行**：若命中 allowedCommands，直接通过
4. **安全级别评估**：根据 securityLevel 判断是否需要审批

### 路径参数提取

`extractPathArguments` 方法专门处理命令中的文件路径参数：

- 过滤掉以 `-` 开头的 flags
- 排除 chmod 等特殊参数模式
- 规范化跨平台路径格式

资料来源：[src/agent/infra/process/command-validator.ts:1-60]()

## 输出生成器（Output Generator）

### 功能定位

`output-generator.ts` 负责将文件夹打包结果转换为 XML 格式的结构化输出，便于 LLM 理解和处理。

### 输出结构

```xml
<folder-pack>
  <config>
    <max_file_size>...</max_file_size>
    <max_lines_per_file>...</max_lines_per_file>
    <custom_ignores>...</custom_ignores>
  </config>
  <directory_structure>
    <![CDATA[...]]>
  </directory_structure>
  <files>
    <file path="..." type="..." size="...">
      <![CDATA[content]]>
    </file>
  </files>
  <skipped_files>
    <file reason="...">...</file>
  </skipped_files>
  <summary>
    <description>...</description>
  </summary>
</folder-pack>
```

### 文件类型统计

系统维护文件类型计数器：

```typescript
const typeBreakdown = new Map<string, number>()
for (const file of result.files) {
  const fileType = file.fileType ?? 'unknown'
  typeBreakdown.set(fileType, (typeBreakdown.get(fileType) ?? 0) + 1)
}
```

### 配置项

| 配置项 | 用途 | 默认行为 |
|--------|------|----------|
| maxFileSize | 单文件大小限制 | 格式化显示 |
| maxLinesPerFile | 单文件行数限制 | 格式化显示 |
| ignore | 忽略模式列表 | 显示模式数量 |

资料来源：[src/agent/infra/folder-pack/output-generator.ts:1-50]()

## 工作流程集成

### Agent 执行上下文

```mermaid
sequenceDiagram
    participant Agent as Agent Core
    participant Validator as Command Validator
    participant Curate as Curate Service
    participant Output as Output Generator
    
    Agent->>Validator: Validate Command
    Validator-->>Agent: Allow/Block/Approval Required
    
    alt Command Allowed
        Agent->>Curate: Curate Operations
        Curate-->>Agent: CurateResult
        Agent->>Output: Generate XML Output
        Output-->>Agent: Structured Response
    end
```

### 知识文档处理流程

1. **输入**：知识文档集合（路径 + 内容）
2. **包装**：转换为 XML 格式，使用 CDATA 保护内容
3. **生成**：提示 LLM 生成结构化概览
4. **解析**：从模型响应中提取 `<file>` 和 `<overview>` 标签对
5. **输出**：返回 Map<path, overview> 结构

## 配置与扩展

### 安全级别配置

`ProcessConfig` 支持的安全配置项：

```typescript
interface ProcessConfig {
  allowedCommands?: string[]    // 白名单命令
  blockedCommands?: string[]   // 黑名单命令
  securityLevel?: 'low' | 'medium' | 'high'
}
```

### 扩展点

| 扩展点 | 文件位置 | 扩展方式 |
|--------|----------|----------|
| 命令验证 | command-validator.ts | 添加新的验证正则或规则 |
| 抽象生成 | abstract-generator.ts | 自定义解析策略或输出格式 |
| 策展操作 | curate-service.ts | 添加新的操作类型 |
| 输出格式 | output-generator.ts | 扩展 XML 结构 |

## 总结

ByteRover CLI 的 Agent 核心系统通过模块化的基础设施设计，实现了：

- **安全性**：命令验证器提供多层安全防护
- **可观测性**：结构化输出便于调试和追踪
- **扩展性**：清晰的接口和配置机制支持定制
- **容错性**：解析器采用锚定策略避免边界情况

这些基础设施组件协同工作，为 AI Agent 提供安全、可靠、可控的运行时环境。

---

<a id='llm-providers'></a>

## LLM提供商集成

### 相关页面

相关主题：[Agent核心系统](#agent-system), [工具系统](#tools-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agent/infra/llm/providers/index.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/index.ts)
- [src/agent/infra/llm/providers/anthropic.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/anthropic.ts)
- [src/agent/infra/llm/providers/openai.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/openai.ts)
- [src/agent/infra/llm/providers/google.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/providers/google.ts)
- [src/agent/infra/llm/agent-llm-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/agent-llm-service.ts)
- [src/agent/infra/llm/retry/retry-with-backoff.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/retry/retry-with-backoff.ts)
- [src/agent/infra/llm/context/context-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/llm/context/context-manager.ts)
</details>

# LLM提供商集成

## 概述

ByteRover CLI 的 LLM（大型语言模型）提供商集成模块位于 `src/agent/infra/llm/` 目录下，负责管理与各种 AI 模型提供商的通信。该模块采用工厂模式和适配器模式，支持多种 LLM 提供商（Anthropic、OpenAI、Google）的无缝切换，使系统能够在不同 AI 服务之间灵活选择和配置。

LLM 提供商集成的核心职责包括：

- **统一抽象接口**：为不同提供商提供一致的调用方式
- **认证管理**：处理各提供商的 API 密钥和环境变量配置
- **请求重试机制**：通过指数退避策略处理临时性网络故障和限流
- **上下文管理**：优化 token 使用，控制对话历史长度

资料来源：[src/agent/infra/llm/providers/index.ts]()

## 架构设计

### 模块结构

```
src/agent/infra/llm/
├── providers/                    # 提供商适配器
│   ├── index.ts                 # 提供商工厂与注册
│   ├── anthropic.ts             # Anthropic (Claude) 适配器
│   ├── openai.ts                # OpenAI (GPT) 适配器
│   └── google.ts                # Google (Gemini) 适配器
├── agent-llm-service.ts         # Agent LLM 服务主类
├── retry/
│   └── retry-with-backoff.ts    # 重试机制实现
└── context/
    └── context-manager.ts       # 上下文管理
```

### 核心类关系

```mermaid
graph TD
    A[Agent LLM Service] --> B[Provider Factory]
    B --> C[Anthropic Provider]
    B --> D[OpenAI Provider]
    B --> E[Google Provider]
    A --> F[Context Manager]
    A --> G[Retry with Backoff]
    
    H[LLM Request] --> A
    A --> I[Provider Response]
    
    C --> C1[Anthropic API]
    D --> D1[OpenAI API]
    E --> E1[Google AI API]
```

## 提供商适配器

### 提供商注册与工厂模式

`providers/index.ts` 实现了一个工厂模式，所有提供商在此注册。系统通过配置选择使用哪个提供商，无需修改调用代码即可切换 AI 模型。

资料来源：[src/agent/infra/llm/providers/index.ts]()

### Anthropic 提供商

Anthropic 提供商适配器负责与 Claude 系列模型的通信。该适配器处理：

- Anthropic 特有的请求格式（messages API）
- `anthropic-version` 头部设置
- `max_tokens` 和 `thinking` 块配置
- 流式响应的解析

资料来源：[src/agent/infra/llm/providers/anthropic.ts]()

### OpenAI 提供商

OpenAI 提供商适配器支持 GPT-4、GPT-4o 等模型系列。特性包括：

- 兼容 OpenAI Chat Completions API 格式
- 支持 `temperature`、`top_p` 等采样参数
- 函数调用（Function Calling）支持
- 多模态输入处理

资料来源：[src/agent/infra/llm/providers/openai.ts]()

### Google 提供商

Google 提供商适配器集成 Gemini 模型：

- Gemini API 格式适配
- 安全过滤配置
- 生成配置（temperature、topP、topK）
- 系统指令处理

资料来源：[src/agent/infra/llm/providers/google.ts]()

## Agent LLM 服务

`agent-llm-service.ts` 是 LLM 集成的核心服务类，封装了所有与 AI 模型交互的逻辑。

### 主要职责

| 职责 | 描述 |
|------|------|
| 提供商初始化 | 根据配置创建相应的提供商实例 |
| 请求发送 | 构建请求并调用提供商 |
| 响应处理 | 解析 AI 响应并转换为统一格式 |
| 错误处理 | 统一管理各类异常情况 |

资料来源：[src/agent/infra/llm/agent-llm-service.ts]()

### 工作流程

```mermaid
sequenceDiagram
    participant Agent as Agent/Worker
    participant LLMService as Agent LLM Service
    participant Provider as Selected Provider
    participant API as External LLM API

    Agent->>LLMService: 发送请求
    LLMService->>LLMService: 应用上下文管理
    LLMService->>Provider: 调用提供商接口
    Provider->>API: 发送 API 请求
    API-->>Provider: 返回响应
    Provider-->>LLMService: 返回标准格式响应
    LLMService-->>Agent: 返回处理结果
```

## 重试机制

### 指数退避策略

`retry-with-backoff.ts` 实现了智能重试机制，用于处理网络临时故障和 API 限流情况。

资料来源：[src/agent/infra/llm/retry/retry-with-backoff.ts]()

### 重试配置参数

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| maxRetries | number | 3 | 最大重试次数 |
| initialDelay | number | 1000 | 初始延迟（毫秒） |
| maxDelay | number | 30000 | 最大延迟上限 |
| backoffMultiplier | number | 2 | 退避系数 |

### 重试条件

系统仅对以下情况触发重试：

- **网络错误**：连接超时、DNS 解析失败
- **5xx 服务器错误**：上游服务暂时不可用
- **429 限流错误**：API 调用频率超限

以下情况不进行重试：

- 认证失败（401、403）
- 客户端请求错误（400）
- 内容安全过滤（根据提供商配置）

## 上下文管理

### Context Manager

`context-manager.ts` 负责管理和优化对话上下文，确保在 token 限制内提供最佳上下文。

资料来源：[src/agent/infra/llm/context/context-manager.ts]()

### 上下文窗口管理

```mermaid
graph LR
    A[用户消息] --> B[Context Manager]
    B --> C{Token 计数}
    C -->|超限| D[压缩历史]
    C -->|正常| E[直接添加]
    D --> F[摘要生成]
    E --> G[上下文列表]
    F --> G
    G --> H[LLM 请求]
```

### 上下文优化策略

| 策略 | 触发条件 | 处理方式 |
|------|----------|----------|
| 滑动窗口 | 对话历史过长 | 保留最近 N 条消息 |
| 摘要压缩 | 单条消息过长 | 生成摘要替代原文 |
| 关键信息保留 | 任何压缩场景 | 保留系统指令和关键配置 |

## 配置与认证

### 环境变量配置

| 变量名 | 提供商 | 说明 |
|--------|--------|------|
| `ANTHROPIC_API_KEY` | Anthropic | Claude API 密钥 |
| `OPENAI_API_KEY` | OpenAI | GPT API 密钥 |
| `GOOGLE_API_KEY` | Google | Gemini API 密钥 |

### 提供商选择

通过配置文件或启动参数指定使用的 LLM 提供商：

```yaml
llm:
  provider: "anthropic"  # anthropic | openai | google
  model: "claude-sonnet-4-20250514"
  maxTokens: 8192
```

## 错误处理

### 错误类型分类

| 错误类型 | HTTP 状态码 | 处理方式 |
|----------|-------------|----------|
| 认证错误 | 401, 403 | 直接抛出，不重试 |
| 限流错误 | 429 | 指数退避重试 |
| 服务器错误 | 500, 502, 503 | 指数退避重试 |
| 网络错误 | - | 指数退避重试 |
| 超时错误 | - | 指数退避重试 |

### 错误响应格式

```typescript
interface LLMError {
  provider: string;        // 提供商名称
  code: string;            // 错误代码
  message: string;         // 错误描述
  retryable: boolean;      // 是否可重试
  originalError?: Error;   // 原始错误对象
}
```

## 扩展新的提供商

如需添加新的 LLM 提供商，需完成以下步骤：

1. **创建提供商文件**：在 `providers/` 下创建 `newprovider.ts`
2. **实现 Provider 接口**：实现统一的调用方法
3. **注册到工厂**：在 `index.ts` 中添加新提供商
4. **添加配置支持**：更新配置解析逻辑
5. **编写测试用例**：确保错误处理和响应解析正确

```typescript
// 实现示例
export class NewProvider implements LLMProvider {
  constructor(config: ProviderConfig) { /* ... */ }
  async complete(request: LLMRequest): Promise<LLMResponse> { /* ... */ }
  async stream(request: LLMRequest): AsyncIterable<StreamChunk> { /* ... */ }
}
```

## 最佳实践

### 生产环境建议

- **使用环境变量**：不要在代码中硬编码 API 密钥
- **配置重试策略**：根据提供商限流调整重试参数
- **监控 token 使用**：避免意外超支
- **设置超时限制**：防止长时间阻塞

### 开发调试建议

- **使用本地模拟**：开发时可用 mock 提供商
- **启用详细日志**：便于追踪请求/响应
- **测试边界情况**：验证 token 限制和错误处理

---

<a id='tools-system'></a>

## 工具系统

### 相关页面

相关主题：[Agent核心系统](#agent-system), [LLM提供商集成](#llm-providers), [版本控制系统](#version-control)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agent/infra/tools/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/types.ts)
- [src/agent/infra/tools/tool-registry.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-registry.ts)
- [src/agent/infra/tools/tool-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-manager.ts)
- [src/agent/infra/tools/core-tool-scheduler.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/core-tool-scheduler.ts)
- [src/agent/infra/tools/implementations/read-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/read-file-tool.ts)
- [src/agent/infra/tools/implementations/write-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/write-file-tool.ts)
- [src/agent/infra/tools/implementations/code-exec-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/code-exec-tool.ts)
- [src/agent/resources/tools](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/tools)
</details>

# 工具系统

## 概述

ByteRover CLI 的工具系统是 AI 代理与代码库交互的核心桥梁。该系统提供了一套标准化的工具接口，使 AI 代理能够执行文件操作、代码执行、知识管理等多种任务。通过统一的工具注册、调度和执行机制，实现了工具的模块化管理和安全验证。资料来源：[src/agent/infra/tools/tool-registry.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-registry.ts)

## 核心架构

工具系统采用分层架构设计，包含以下核心组件：

### 组件层级

```mermaid
graph TD
    A[AI 代理层] --> B[工具管理器 ToolManager]
    B --> C[工具注册表 ToolRegistry]
    C --> D[核心工具调度器 CoreToolScheduler]
    D --> E[具体工具实现]
    
    E --> E1[ReadFileTool]
    E --> E2[WriteFileTool]
    E --> E3[CodeExecTool]
    E --> E4[CurateTool]
    
    F[命令验证器 CommandValidator] --> B
    G[沙箱服务 CurateService] --> E4
```

### 核心组件表

| 组件 | 文件路径 | 职责 |
|------|----------|------|
| ToolRegistry | `src/agent/infra/tools/tool-registry.ts` | 工具注册、查找、生命周期管理 |
| ToolManager | `src/agent/infra/tools/tool-manager.ts` | 工具调度、参数验证、执行协调 |
| CoreToolScheduler | `src/agent/infra/tools/core-tool-scheduler.ts` | 异步任务队列、并发控制 |
| CommandValidator | `src/agent/infra/process/command-validator.ts` | 命令安全验证、危险模式检测 |

资料来源：[src/agent/infra/tools/tool-manager.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/tool-manager.ts)

## 工具类型体系

### 类型定义

工具系统定义了丰富的类型体系来规范工具的结构和行为。工具必须实现标准接口，包含名称、描述、参数模式和执行逻辑。资料来源：[src/agent/infra/tools/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/types.ts)

### 核心工具实现

#### ReadFileTool（读取文件工具）

提供文件系统读取能力，支持以下功能：

- 单文件读取，返回文件内容和元数据
- 支持行数限制和截断检测
- 文件路径验证和访问控制

```typescript
// 读取文件工具的典型调用模式
await tools.readFile('path/to/file.txt')
// 返回: { content: string, lines: number, truncated: boolean }
```

资料来源：[src/agent/infra/tools/implementations/read-file-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/read-file-tool.ts)

#### WriteFileTool（写入文件工具）

提供文件系统写入能力，支持：

- 新建文件内容
- 更新现有文件
- 批量文件操作

#### CodeExecTool（代码执行工具）

在沙箱环境中执行代码，具备以下特性：

- 支持多种编程语言的代码执行
- 内置文件系统操作工具（readFile、grep）
- 与 curate 服务集成进行知识管理
- 批处理模式（每次处理 5-10 个文件）

```typescript
// 代码执行工具中的工具调用
const fileContent = await tools.readFile('path/to/file')
const matches = await tools.grep('<file[^>]*path=".*README.*">', { path: tmpFilePath })
await tools.curate([{ type: 'ADD', path: 'overview', data: { concept: '...' } }])
```

资料来源：[src/agent/infra/tools/implementations/code-exec-tool.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/implementations/code-exec-tool.ts)

## 工具执行流程

### 执行状态机

工具执行过程中会经历多种状态，TUI 组件通过状态渲染不同的视觉效果：

```mermaid
stateDiagram-v2
    [*] --> pending: 任务创建
    pending --> running: 开始执行
    running --> completed: 执行成功
    running --> failed: 执行失败
    completed --> [*]
    failed --> [*]
```

### TUI 状态显示

在执行视图中，不同状态对应不同的显示效果：

| 状态 | 显示样式 | 符号 |
|------|----------|------|
| pending | 默认灰色 | `○` |
| running | 闪烁动画 | `◐` |
| completed | 绿色高亮 | `✓` |
| failed | 红色高亮 | `✗` |

资料来源：[src/tui/components/execution/execution-tool.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/execution-tool.tsx)

### 执行日志视图

执行日志组件（ExpandedLogView）负责渲染工具调用结果：

```mermaid
graph LR
    A[日志数据] --> B{running?}
    B -->|是| C[显示流式内容]
    B -->|否| D{completed?}
    D -->|是| E[显示更改]
    D -->|否| F[显示错误]
```

组件支持以下渲染内容：

- 工具调用参数和名称
- 流式文本内容（带光标动画）
- 完整执行结果
- 文件变更摘要（创建/更新）

资料来源：[src/tui/components/execution/expanded-log-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/expanded-log-view.tsx)

## 命令验证与安全

### 安全验证机制

CommandValidator 组件负责验证命令的安全性，支持多层级的安全控制：

```typescript
// 只读命令白名单
const readOnlyCommands = [
  /git\s+(status|log|diff|show|branch|tag|fetch|pull)(?!\s+-)/i,
  /cat\s+.*>/,
  /find\s+.*>/,
]
```

### 验证规则

| 验证类型 | 说明 | 配置来源 |
|----------|------|----------|
| 危险模式检测 | 检测 rm -rf 等危险命令 | blockedCommands |
| 白名单验证 | 允许的命令列表 | allowedCommands |
| 安全级别 | 控制验证严格程度 | securityLevel |
| 路径提取 | 验证文件路径安全性 | extractPathArguments |

资料来源：[src/agent/infra/process/command-validator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/process/command-validator.ts)

## 工具资源定义

### 工具描述格式

工具通过 Markdown 格式定义，存储在 `src/agent/resources/tools` 目录。标准格式包含：

- 工具名称和描述
- 参数说明（名称、类型、必填、默认值）
- 使用示例
- 返回值格式

### 工具模板结构

```markdown
## 工具名称

描述工具用途和功能

### 参数
| 参数名 | 类型 | 必填 | 默认值 | 说明 |

### 示例
```bash
工具调用示例
```

### 返回值
返回数据格式说明
```

资料来源：[src/agent/resources/tools](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/tools)

## 异步调度机制

### 核心调度器

CoreToolScheduler 负责管理工具执行的异步队列：

- 并发任务数量控制
- 任务优先级管理
- 执行结果回调
- 错误处理和重试机制

### 调度配置

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| maxConcurrency | 最大并发数 | 3 |
| timeout | 单任务超时 | 30000ms |
| retryCount | 失败重试次数 | 2 |

资料来源：[src/agent/infra/tools/core-tool-scheduler.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/tools/core-tool-scheduler.ts)

## 工具管理服务

### CurateService 集成

CurateService 为代码执行工具提供知识管理能力：

- 添加、更新、删除知识条目
- 批量操作支持（最多 5 个文件）
- 域检测和自动分类
- 标题和内容验证

```typescript
// curate 操作类型
type CurateOperation = {
  type: 'ADD' | 'UPDATE' | 'DELETE' | 'UPSERT'
  path: string
  title?: string
  content?: {
    rawConcept?: string
    narrative?: string
  }
}
```

资料来源：[src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)

## 最佳实践

### 工具使用建议

1. **批量处理**：使用 code-exec-tool 时，每次处理 5-10 个文件以控制输出大小
2. **路径验证**：所有文件操作前验证路径在项目目录内
3. **错误处理**：检查 truncated 标志以处理大文件截断
4. **安全优先**：使用命令验证器过滤危险操作

### 性能优化

| 场景 | 优化策略 |
|------|----------|
| 大文件读取 | 使用行数限制和截断检测 |
| 批量搜索 | 使用 grep 替代多次 readFile |
| 并发控制 | 调整 CoreToolScheduler 的 maxConcurrency |

### 调试技巧

- 使用 TUI 的 expanded-log-view 查看详细执行日志
- 检查 toolCalls 数组追踪工具调用链
- 监控 streamingContent 观察实时输出

---

<a id='context-tree'></a>

## 上下文树与知识管理

### 相关页面

相关主题：[Agent核心系统](#agent-system), [版本控制系统](#version-control), [Swarm多代理协调](#swarm-coordination)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)
- [src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts)
- [src/agent/resources/prompts/curate-detail-preservation.yml](https://github.com/campfirein/byterover-cli/blob/main/src/agent/resources/prompts/curate-detail-preservation.yml)
- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)
- [src/server/templates/README.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/README.md)
</details>

# 上下文树与知识管理

## 概述

上下文树（Context Tree）是 ByteRover CLI 中的核心知识管理基础设施，用于组织和持久化 AI Agent 在项目开发过程中积累的结构化知识。通过上下文树，系统能够将分散的代码模式、设计决策、项目约定等内容转化为可查询、可复用的知识资产。

上下文树位于项目根目录的 `.brv/context-tree/` 路径下，采用分层目录结构组织知识内容，支持动态域名创建和自动摘要生成。

## 架构设计

### 核心组件

| 组件 | 职责 | 文件位置 |
|------|------|----------|
| ContextTreeStore | 上下文树数据存储与检索 | `src/agent/infra/map/context-tree-store.ts` |
| AbstractGenerator | 知识摘要生成服务 | `src/agent/infra/map/abstract-generator.ts` |
| CurateService | 知识整理操作执行器 | `src/agent/infra/sandbox/curate-service.ts` |
| ContextTreeContributor | 系统提示词上下文注入 | `src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts` |

### 数据流架构

```mermaid
graph TD
    A[AI Agent 执行任务] --> B[Curate 操作请求]
    B --> C[CurateService 验证]
    C --> D{验证结果}
    D -->|失败| E[返回失败详情]
    D -->|成功| F[写入 ContextTreeStore]
    F --> G[生成摘要 AbstractGenerator]
    G --> H[更新系统提示词]
    H --> I[ContextTreeContributor 注入结构]
    I --> J[Agent 下次交互使用知识]
```

## 目录结构规范

上下文树采用固定的目录层次结构组织知识内容：

```
.brv/context-tree/
├── _index.md                    # 根级自动生成摘要
├── architecture/                # 动态域名：架构相关知识
│   ├── _index.md               # 目录摘要
│   ├── system_design.md
│   └── api_patterns.md
├── patterns/                    # 代码模式与最佳实践
│   ├── _index.md
│   └── authentication.md
├── conventions/                # 团队约定与规范
│   ├── _index.md
│   └── git_workflow.md
└── _archived/                  # 归档的低优先级知识
    └── old_notes.md
```

### 结构规范说明

| 结构元素 | 说明 | 创建规则 |
|----------|------|----------|
| 顶级文件夹 | 代表知识领域（Domain） | 根据内容语义动态创建 |
| `.md` 文件 | 单个知识主题（Topic） | 包含具体知识内容 |
| `context.md` | 目录级知识入口 | 子文件夹可包含此文件定义目录级上下文 |
| `_index.md` | 自动生成的目录摘要 | 系统自动维护 |
| `_archived/` | 归档存储 | 存放低重要性条目 |

资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:27-35]()

## Curate 操作类型

CurateService 实现了四种核心知识操作类型，用于管理系统中的知识条目：

| 操作类型 | 说明 | 必需字段 |
|----------|------|----------|
| ADD | 添加新的知识条目 | title, content |
| UPDATE | 更新现有条目内容 | title, content |
| UPSERT | 存在则更新，不存在则添加 | title, content |
| DELETE | 删除指定条目 | path |
| MOVE | 移动条目到新位置 | from, to |

### 操作验证规则

```typescript
// ADD、UPDATE、UPSERT 必须包含 content
if ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.content) {
  failures.push({
    message: `${op.type} operation requires content with rawConcept and/or narrative.`,
    path: op.path,
    status: 'failed',
    type: op.type,
  })
}

// ADD、UPDATE、UPSERT 必须包含 title（作为 .md 文件名）
if ((op.type === 'ADD' || op.type === 'UPDATE' || op.type === 'UPSERT') && !op.title) {
  failures.push({
    message: `${op.type} operation requires a title (becomes the .md filename).`,
    path: op.path,
    status: 'failed',
    type: op.type,
  })
}
```

资料来源：[src/agent/infra/sandbox/curate-service.ts:14-35]()

## 知识内容结构

### 知识条目数据模型

每个知识条目（Topic）包含以下结构化字段：

```typescript
interface KnowledgeEntry {
  path: string;           // 条目路径
  title: string;         // 标题（决定文件名）
  content: {
    rawConcept: string;   // 原始概念定义
    facts: Fact[];       // 提取的事实清单
  };
  narrative: {
    rules?: string[];           // 规则与约束
    highlights?: string[];      // 重点与亮点
    structure?: string;         // 结构说明
    examples?: string[];        // 示例列表
    flow?: string;              // 工作流程
    diagrams?: Diagram[];       // 图表引用
    dependencies?: string[];    // 依赖关系
  };
  metadata: {
    tags: string[];
    category: string;
    createdAt: string;
    updatedAt: string;
  };
}
```

### 图表类型支持

```typescript
interface Diagram {
  type: 'mermaid' | 'plantuml' | 'ascii' | 'other';
  title?: string;
  content: string;
}
```

资料来源：[src/agent/resources/prompts/curate-detail-preservation.yml:1-40]()

## 摘要生成系统

### AbstractGenerator 工作流程

AbstractGenerator 负责从批量知识文件中生成结构化摘要，使用 XML 格式输出：

```mermaid
graph LR
    A[输入文件列表] --> B[生成 XML 格式]
    B --> C[构建 LLM Prompt]
    C --> D[模型生成概述]
    D --> E[解析 XML 响应]
    E --> F[提取 <abstract> 或 <overview>]
    F --> G[返回 Map<path, content>]
```

### 输出格式规范

```xml
<file path="architecture/system_design.md">
<overview>
- bullet 1
- bullet 2
...
</overview>
</file>
```

### 解析实现要点

解析器采用锚定于 `<file path="...">` 开启标签的策略，避免内容中包含 `</file>` 时导致匹配错误：

```typescript
function parseBatchedTags(response: string, innerTag: 'abstract' | 'overview'): Map<string, string> {
  // 每个 opener 拥有到下一个 opener（或字符串结尾）的响应片段
  // 内部正则表达式从该片段中提取有效载荷
}
```

资料来源：[src/agent/infra/map/abstract-generator.ts:20-60]()

## 知识保存与提取

### 事实提取规范

知识内容中的事实必须按类别精确提取：

| 类别 | 说明 | 示例 |
|------|------|------|
| personal | 用户个人信息 | "我的名字是 Andy" |
| project | 项目配置值 | 端口号、URL、版本号 |
| convention | 团队约定与流程 | Git 工作流规范 |

### 非代码内容保存

| 内容类型 | 保存位置 | 说明 |
|----------|----------|------|
| 会议决策与理由 | `narrative.rules` / `narrative.highlights` | 必须保留完整决策过程 |
| 操作项与截止日期 | `narrative.examples` | 包含负责人和期限 |
| 投票结果与优先级 | `narrative.highlights` | 保留精确数值 |
| 状态更新与阻塞项 | `narrative.dependencies` | 记录当前障碍 |
| 工作流步骤 | `rawConcept.flow` | 包含所有条件判断 |
| 指标与 KPI | `narrative.highlights` | 保留精确值 |

资料来源：[src/agent/resources/prompts/curate-detail-preservation.yml:40-80]()

## 系统提示词集成

ContextTreeContributor 负责将上下文树结构注入到 Agent 的系统提示词中：

```mermaid
graph TD
    A[加载 ContextTreeStore] --> B[获取目录结构]
    B --> C{条目数量}
    C -->|< 阈值| D[显示完整结构]
    C -->|>= 阈值| E[截断并显示计数]
    D --> F[构建结构说明]
    E --> F
    F --> G[注入系统提示词]
```

### 动态域名说明

```typescript
// 构建结构指南
'## Structure Guide',
'- Each top-level folder is a **domain** (dynamically created based on content)',
'- Inside domains are **topics** as `.md` files or subfolders with `context.md`',

// 动态域名规则
'## Dynamic Domains',
'- Domains are created dynamically based on the semantics of curated content',
'- Domain names should be descriptive, use snake_case',
'- Before creating a new domain, check if existing domains could accommodate the content'
```

### 截断机制

当条目数量超过显示阈值时，系统会截断输出并显示剩余数量：

```
.brv/context-tree/
  architecture/
  patterns/
  conventions/
  [5 additional entries not shown]
```

资料来源：[src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts:1-80]()

## 知识查询与使用

### 查询命令

Agent 通过上下文树结构查询相关知识：

| 命令类型 | 说明 | 查询范围 |
|----------|------|----------|
| Query | 检索相关知识条目 | 仅在上下文树结构内搜索 |
| Expand | 展开归档知识 | 可深入 `_archived/` 目录 |

### 使用建议

1. **创建新条目前**：先检查现有域名是否可容纳新内容
2. **域名命名**：使用 snake_case 格式，描述性强（如 `architecture`、`market_trends`）
3. **知识归档**：低优先级条目可移至 `_archived/`，使用 `expand_knowledge` 命令可展开查看

## 最佳实践

### 知识组织原则

1. **单一职责**：每个主题文件专注于一个知识领域
2. **语义化分类**：根据内容语义选择合适的域名，而非机械分类
3. **摘要更新**：修改知识后及时更新相关 `_index.md` 摘要
4. **事实优先**：关键数值、配置、约定应提取为 facts 便于快速引用

### 内容保留优先级

```
高优先级（必须保留）:
├── 决策与理由
├── 精确数值与配置
├── 工作流程条件
└── 团队约定

中优先级（建议保留）:
├── 示例代码
├── 图表说明
└── 优先级排序

低优先级（可归档）:
├── 过时的笔记
└── 低频参考内容
```

## 相关文件索引

| 文件路径 | 功能 |
|----------|------|
| `src/agent/infra/map/context-tree-store.ts` | 上下文树数据存储实现 |
| `src/agent/infra/map/abstract-generator.ts` | 知识摘要生成器 |
| `src/agent/infra/sandbox/curate-service.ts` | Curate 操作服务 |
| `src/agent/infra/system-prompt/contributors/context-tree-structure-contributor.ts` | 系统提示词注入 |
| `src/agent/resources/prompts/curate-detail-preservation.yml` | 内容保存规范 |

---

<a id='version-control'></a>

## 版本控制系统

### 相关页面

相关主题：[上下文树与知识管理](#context-tree)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/shared/transport/events/vc-events.ts](https://github.com/campfirein/byterover-cli/blob/main/src/shared/transport/events/vc-events.ts)
- [src/server/templates/skill/SKILL.md](https://github.com/campfirein/byterover-cli/blob/main/src/server/templates/skill/SKILL.md)
- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)
- [src/agent/infra/map/abstract-generator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/map/abstract-generator.ts)
- [src/agent/infra/sandbox/curate-service.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/sandbox/curate-service.ts)
- [src/tui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/hub/components/hub-detail-step.tsx)
</details>

# 版本控制系统

## 概述

ByteRover CLI 的版本控制系统（Version Control System，简称 VC）是该项目提供的核心功能之一。该系统通过 `brv vc` 命令族为 AI 编码代理提供持久化的上下文记忆能力，支持本地文件变更追踪、云端同步以及团队协作。

版本控制系统的设计目标是让 AI 代理能够在项目目录中追踪和管理文件变更，同时与 ByteRover 云服务协同工作，实现知识的持久化和跨工具共享。

## 核心架构

### 类型定义体系

版本控制系统的类型定义集中于 `src/shared/transport/events/vc-events.ts` 文件中，定义了完整的 diff 操作类型体系：

```typescript
// 资料来源：src/shared/transport/events/vc-events.ts
export type VcDiffMode =
  | {from: string; kind: 'range'; to: string}
  | {kind: 'ref-vs-worktree'; ref: string}
  | {kind: 'staged'}
  | {kind: 'unstaged'}

export type VcDiffFileStatus = 'added' | 'deleted' | 'modified'

export interface IVcDiffFile {
  binary?: boolean
  newContent: string
  newOid: string
  oldContent: string
  oldOid: string
  path: string
  status: VcDiffFileStatus
}
```

### Diff 模式分类

系统支持四种差异模式，与 Git 原生命令保持一致：

| 模式名称 | 描述 | 对应 Git 命令 |
|---------|------|--------------|
| `unstaged` | 工作目录与暂存区对比（仅追踪文件） | `git diff` |
| `staged` | 暂存区与 HEAD 对比 | `git diff --staged` |
| `ref-vs-worktree` | 指定提交/分支与工作目录对比 | `git diff <ref>` |
| `range` | 两个引用之间的差异 | `git diff <ref1>..<ref2>` |

```mermaid
graph TD
    A[版本控制系统] --> B[Diff 操作]
    B --> C{模式选择}
    C -->|unstaged| D[WORKDIR → STAGE]
    C -->|staged| E[HEAD → STAGE]
    C -->|ref-vs-worktree| F[ref → WORKDIR]
    C -->|range| G[ref1 → ref2]
    
    H[IVcDiffFile] --> I[status: added/deleted/modified]
    H --> J[newOid/oldOid]
    H --> K[newContent/oldContent]
    H --> L[binary flag]
```

## 命令体系

### 命令分类总览

`brv vc` 命令提供完整的版本控制操作能力，文档位于 `src/server/templates/skill/SKILL.md`：

| 命令 | 功能描述 |
|------|---------|
| `brv vc add` | 暂存文件变更 |
| `brv vc commit` | 提交暂存区变更 |
| `brv vc log` | 查看提交历史 |
| `brv vc reset` | 取消暂存或撤销提交 |
| `brv vc branch` | 分支管理 |
| `brv vc checkout` | 切换分支 |
| `brv vc merge` | 合并分支 |
| `brv vc remote` | 远程仓库操作 |

### 文件操作命令

#### 暂存文件 (`brv vc add`)

```bash
brv vc add .                     # 暂存所有文件
brv vc add notes.md docs/        # 暂存指定文件
```

暂存操作会将工作目录中的变更移动到暂存区，为提交做准备。

#### 查看历史 (`brv vc log`)

```bash
brv vc log                      # 查看最近提交
brv vc log --limit 20           # 限制显示数量
brv vc log --all                # 查看所有分支历史
```

#### 重置操作 (`brv vc reset`)

| 命令 | 行为 |
|------|------|
| `brv vc reset` | 取消所有文件暂存 |
| `brv vc reset <file>` | 取消指定文件暂存 |
| `brv vc reset --soft HEAD~1` | 撤销上次提交，保留变更在暂存区 |
| `brv vc reset --hard HEAD~1` | 撤销上次提交并丢弃所有变更 |

### 分支管理

#### 分支操作

```bash
brv vc branch                    # 列出本地分支
brv vc branch feature/auth       # 创建新分支
brv vc branch -a                 # 列出所有分支（含远程追踪分支）
brv vc branch -d feature/auth    # 删除分支
```

#### 切换分支

```bash
brv vc checkout feature/auth     # 切换到现有分支
brv vc checkout -b feature/new    # 创建并切换到新分支
```

#### 合并操作

```bash
brv vc merge feature/auth        # 将目标分支合并到当前分支
brv vc merge --continue          # 解决冲突后继续合并
brv vc merge --abort             # 中止合并操作
```

#### 设置上游追踪

```bash
brv vc branch --set-upstream-to origin/main
```

```mermaid
graph LR
    A[brv vc branch] --> B[create]
    A --> C[list]
    A --> D[delete]
    A --> E[set-upstream]
    
    F[brv vc checkout] --> G[switch]
    F --> H[create-and-switch]
    
    I[brv vc merge] --> J[normal]
    I --> K[continue]
    I --> L[abort]
```

### 云端同步

版本控制系统支持与 ByteRover 云服务同步，需要先完成身份认证和远程仓库配置：

```bash
brv login                         # ByteRover 身份认证
brv vc remote                     # 查看当前远程仓库
brv vc remote add origin <url>   # 添加远程仓库
```

云同步功能允许用户将本地版本控制状态与云端保持一致，实现跨设备和团队协作。

## 评审界面集成

ByteRover 提供本地 HITL（Human-in-the-Loop）评审界面，集成于 `src/server/infra/http/review-ui.ts`：

### 评审页面架构

评审界面使用自包含的 HTML/CSS/JS 实现，支持变更的语义化摘要展示：

```typescript
// 资料来源：src/server/infra/http/review-ui.ts
export function getReviewPageHtml(): string {
  return `<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ByteRover Review</title>
<style>
  :root {
    --bg: #0d1117;
    --bg-secondary: #161b22;
    --green: #238636;
    --red: #da3633;
    --blue: #58a6ff;
  }
</style>
</head>
<body>
  <!-- 评审界面内容 -->
</body>
</html>`
}
```

### 文件卡片渲染

评审界面为每个变更文件生成卡片，包含操作类型徽章和操作按钮：

```typescript
// 资料来源：src/server/infra/http/review-ui.ts
function renderFileCard(file, index) {
  const opBadges = file.operations.map(op =>
    '<span class="op-badge ' + op.type + '">' + op.type + '</span>'
  ).join('');
  
  return '<div class="file-card" id="file-' + index + '">'
    + '<div class="file-header">'
    + '  <div><span class="file-path">' + escapeHtml(file.path) + '</span></div>'
    + '  <div class="file-meta">'
    + '    ' + opBadges
    + '    <div class="actions">'
    + '      <button class="btn btn-approve" onclick="decide(event,' + index + ',\'approved\')">Approve</button>'
    + '      <button class="btn btn-reject" onclick="decide(event,' + index + ',\'rejected\')">Reject</button>'
    + '    </div>'
    + '  </div>'
    + '</div>'
    + '</div>';
}
```

### 评审操作按钮

| 按钮 | 功能 |
|------|------|
| Approve | 批准变更 |
| Reject | 拒绝变更 |

## 抽象生成与摘要

版本控制系统与知识管理模块集成，通过抽象生成队列处理文档摘要：

```typescript
// 资料来源：src/agent/infra/sandbox/curate-service.ts
export class CurateService implements ICurateService {
  async curate(operations: CurateOperation[], options?: CurateOptions): Promise<CurateResult> {
    const rawBasePath = options?.basePath ?? DEFAULT_BASE_PATH
    // 处理整理操作...
  }
}
```

### 摘要生成提示词

系统使用专门的提示词模板生成文件摘要，支持单行摘要和结构化概览两种模式：

```typescript
// 资料来源：src/agent/infra/map/abstract-generator.ts
function buildBatchedAbstractPrompt(items) {
  return `For each of the following knowledge documents, produce a ONE-LINE summary (max 80 tokens)
Output format — emit exactly one <file> element per input file:
<file path="<path>"><abstract>One-line summary.</abstract></file>`
}

function buildBatchedOverviewPrompt(items) {
  return `For each of the following knowledge documents, produce a structured overview (markdown, under 1500 tokens) that includes:
- Key points (3-7 bullet points)
- Structure / sections summary
- Any notable entities, patterns, or decisions mentioned`
}
```

### CDATA 封装

为防止 XML 解析冲突，文档内容使用 CDATA 段封装：

```typescript
// 资料来源：src/agent/infra/map/abstract-generator.ts
function wrapCdata(content: string): string {
  return `<![CDATA[${content.replaceAll(']]>', ']]]]><![CDATA[>')}]]>`
}
```

## 数据结构

### 版本控制 Diff 文件结构

```typescript
interface IVcDiffFile {
  /** 二进制文件标志（任一端包含 NUL 字节时为 true） */
  binary?: boolean
  /** 新版本内容 */
  newContent: string
  /** 7 位短 OID，新增文件时省略 */
  newOid: string
  /** 旧版本内容 */
  oldContent: string
  /** 删除文件时省略 */
  oldOid: string
  /** 文件路径 */
  path: string
  /** 变更类型 */
  status: VcDiffFileStatus
}
```

### Diff 端定义

```typescript
// 资料来源：src/shared/transport/events/vc-events.ts
interface VcDiffSide {
  oid: string
  content: string
}
```

## 总结

ByteRover CLI 的版本控制系统是一个完整的功能模块，它：

1. **提供命令行接口**：通过 `brv vc` 命令族提供 Git 风格的操作体验
2. **支持多种 Diff 模式**：兼容 unstaged、staged、ref-vs-worktree、range 四种模式
3. **集成评审流程**：提供内置的 HITL 评审界面
4. **支持云端同步**：与 ByteRover 云服务集成实现协作
5. **与知识管理协同**：与上下文树和知识整理系统深度集成

该系统专为 AI 编码代理设计，使其能够像人类开发者一样有效地管理和追踪项目变更。

---

<a id='swarm-coordination'></a>

## Swarm多代理协调

### 相关页面

相关主题：[上下文树与知识管理](#context-tree), [Agent核心系统](#agent-system)

# Swarm多代理协调

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/agent/core/domain/swarm/types.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/core/domain/swarm/types.ts)
- [src/agent/infra/swarm/swarm-coordinator.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/swarm-coordinator.ts)
- [src/agent/infra/swarm/swarm-router.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/swarm-router.ts)
- [src/agent/infra/swarm/adapters/byterover-adapter.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/adapters/byterover-adapter.ts)
- [src/agent/infra/swarm/wizard/swarm-wizard.ts](https://github.com/campfirein/byterover-cli/blob/main/src/agent/infra/swarm/wizard/swarm-wizard.ts)
- [src/oclif/commands/swarm/query.ts](https://github.com/campfirein/byterover-cli/blob/main/src/oclif/commands/swarm/query.ts)
</details>

## 概述

Swarm（多代理协调系统）是ByteRover CLI中的一个核心模块，旨在实现跨多个记忆提供商的智能协调与信息检索。该系统通过统一的查询和整理接口，将ByteRover上下文树、Obsidian保险库、GBrain、本地Markdown文件夹以及Memory Wiki等多个记忆源进行整合，为用户提供无缝的知识访问体验。

Swarm的核心设计理念是**多提供者并行查询**与**智能结果融合**。当用户配置了多个记忆提供者时，Swarm能够同时向所有可用提供者发起查询请求，并通过RRF（Reciprocal Rank Fusion，倒数排名融合）算法对结果进行排序和去重，最终返回最优的检索结果。资料来源：[src/server/templates/skill/SKILL.md]()

## 核心架构

### 系统组件

Swarm多代理协调系统由以下几个核心组件构成：

| 组件 | 职责 | 文件位置 |
|------|------|----------|
| SwarmCoordinator | 协调多个提供者的查询与整理操作 | `src/agent/infra/swarm/swarm-coordinator.ts` |
| SwarmRouter | 根据内容类型和配置路由请求到合适的提供者 | `src/agent/infra/swarm/swarm-router.ts` |
| ByteoverAdapter | ByteRover上下文树适配器 | `src/agent/infra/swarm/adapters/byterover-adapter.ts` |
| SwarmWizard | 引导用户配置Swarm设置 | `src/agent/infra/swarm/wizard/swarm-wizard.ts` |
| SwarmConfigLoader | 加载和验证Swarm配置文件 | `src/agent/infra/swarm/config/swarm-config-loader.ts` |

### 数据流架构

```mermaid
graph TD
    User[用户请求] --> CLI[brv swarm query/curate]
    CLI --> Coordinator[SwarmCoordinator]
    Coordinator --> Router[SwarmRouter]
    Router --> Providers[多个记忆提供者]
    
    Providers --> ByteRover[ByteRover上下文树]
    Providers --> Obsidian[Obsidian保险库]
    Providers --> GBrain[GBrain实体库]
    Providers --> LocalMD[本地Markdown]
    Providers --> MemWiki[Memory Wiki]
    
    Providers --> RRF[RRF结果融合]
    RRF --> Filter[精确度过滤]
    Filter --> Result[最终结果]
    
    subgraph 配置层
        Config[.brv/swarm/config.yaml]
        ConfigLoader[SwarmConfigLoader]
    end
    
    ConfigLoader --> Config
    Coordinator -.依赖.-> ConfigLoader
```

## 记忆提供者

Swarm支持五种类型的记忆提供者，每种提供者都有其特定的用途和配置方式。

### 提供者类型

| 提供者 | 类型标识 | 用途 | 可写 |
|--------|----------|------|------|
| ByteRover | `byterover` | 上下文树主存储 | 是 |
| Obsidian | `obsidian` | Markdown笔记Vault | 可配置 |
| GBrain | `gbrain` | 实体概念存储 | 可配置 |
| Local Markdown | `local-markdown` | 本地文件夹笔记 | 可配置 |
| Memory Wiki | `memory-wiki` | Wiki格式知识库 | 可配置 |

### 提供者配置

每个提供者在Swarm配置中都有以下可配置属性：

```yaml
providers:
  byterover:
    enabled: true
    type: memory-tree
  obsidian:
    enabled: true
    path: /Users/you/Documents/MyObsidian
    type: vault
  gbrain:
    enabled: true
    path: /Users/you/workspaces/gbrain
    type: entity-store
  memory-wiki:
    enabled: true
    path: /Users/you/.openclaw/wiki/main
    type: wiki
```

资料来源：[src/server/templates/skill/SKILL.md]()

## Swarm配置系统

### 配置文件加载

Swarm配置存储在项目根目录的`.brv/swarm/config.yaml`文件中。配置加载器负责读取、解析和验证配置。

配置加载流程：

1. 读取`.brv/swarm/config.yaml`文件
2. 解析YAML内容
3. 解析环境变量引用（`${VAR}`格式）
4. 通过Zod Schema进行验证
5. 返回类型安全的SwarmConfig对象

```typescript
export async function loadSwarmConfig(
  projectRoot: string,
  env?: Record<string, string | undefined>
): Promise<SwarmConfig>
```

如果配置文件不存在，抛出错误提示用户运行`brv swarm onboard`命令创建配置。资料来源：[src/agent/infra/swarm/config/swarm-config-loader.ts]()

### 配置验证

配置验证确保Swarm设置的完整性和正确性。验证内容包括：

- 提供者路径有效性
- 提供者类型识别
- 环境变量引用解析
- Schema类型检查

## 查询操作

### 查询流程

Swarm查询操作通过以下步骤执行：

```mermaid
graph LR
    A[查询请求] --> B[分类查询类型]
    B --> C[选择提供者]
    C --> D[并行查询所有提供者]
    D --> E[收集结果]
    E --> F[RRF融合排序]
    F --> G[精确度过滤]
    G --> H[返回结果]
```

### 查询分类

Swarm能够自动分类查询类型，以优化提供者选择：

| 查询类型 | 特征 | 适用场景 |
|----------|------|----------|
| `factual` | 事实性问题 | 具体信息检索 |
| `semantic` | 语义理解 | 概念和模式识别 |
| `contextual` | 上下文相关 | 依赖上下文的查询 |

### 查询命令

```bash
# 基本查询
brv swarm query "authentication patterns"

# 显示详细信息
brv swarm query "authentication patterns" --explain

# JSON格式输出
brv swarm query "rate limiting" --format json

# 限制结果数量
brv swarm query "testing strategy" -n 5
```

### 查询输出示例

使用`--explain`标志时，输出包含详细的分类和提供者信息：

```
Classification: factual
Provider selection: 4 of 4 available
  ✓ byterover    (healthy, selected, 0 results, 14ms)
  ✓ obsidian    (healthy, selected, 5 results, 91ms)
  ✓ memory-wiki    (healthy, selected, 2 results, 15ms)
  ✓ gbrain    (healthy, selected, 1 results, 260ms)
Enrichment:
  byterover → obsidian
  byterover → memory-wiki
Results: 8 raw → 7 after RRF fusion + precision filtering
```

资料来源：[src/server/templates/skill/SKILL.md]()

### JSON输出格式

```json
{
  "meta": {
    "queryType": "factual",
    "totalLatencyMs": 340,
    "providers": {
      "byterover": { "selected": true, "resultCount": 0 },
      "obsidian": { "selected": true, "resultCount": 5 },
      "gbrain": { "selected": true, "resultCount": 1 },
      "memory-wiki": { "selected": true, "resultCount": 1 }
    }
  },
  "results": [
    { "provider": "memory-wiki", "providerType": "memory-wiki", "score": 0.015, "content": "# Rate Limiting ..." }
  ]
}
```

## 整理操作

### 整理流程

Swarm整理（Curate）操作用于将知识存储到最合适的外部记忆提供者中。系统自动分类内容类型并路由到对应的提供者。

```mermaid
graph TD
    A[整理请求] --> B[分析内容类型]
    B --> C{内容分类}
    
    C -->|实体/人物| D[GBrain]
    C -->|笔记/TODO| E[本地Markdown]
    C -->|通用内容| F[第一个可写提供者]
    C -->|无可用外部| G[ByteRover上下文树]
    
    D --> H[存储完成]
    E --> H
    F --> H
    G --> H
```

### 路由规则

| 内容类型 | 目标提供者 | 存储格式 |
|----------|------------|----------|
| 人物/组织实体 | GBrain | concept/xxx |
| 会议笔记/TODO | 本地Markdown | note-xxx.md |
| 通用内容 | 第一个可写提供者 | 提供者特定格式 |
| 无外部提供者 | ByteRover | context.md |

### 整理命令

```bash
# 基本整理
brv swarm curate "Jane Smith is the CTO of TechCorp"

# 指定提供者
brv swarm curate "meeting notes: decided on JWT" --provider local-markdown:notes

# 存储到GBrain
brv swarm curate "Architecture uses event sourcing" --provider gbrain

# JSON输出
brv swarm curate "Test content" --format json
```

### 整理输出

```
Stored to gbrain as concept/jane-smith-cto
```

## Swarm状态检查

### 健康检查

在执行查询或整理操作前，建议先检查Swarm状态以验证提供者的可用性。

```bash
brv swarm status
```

### 状态输出示例

```
Memory Swarm Health Check
════════════════════════════════════════
  ✓ ByteRover       context-tree (always on)
  ✓ Obsidian        /Users/you/Documents/MyObsidian
  ✓ Local .md       1 folder(s)
  ✓ GBrain          /Users/you/workspaces/gbrain
  ✓ Memory Wiki     /Users/you/.openclaw/wiki/main

Write Targets:
  gbrain (entity, general)
  local-markdown:project-docs (note, general)

Swarm is operational (5/5 providers configured).
```

资料来源：[src/server/templates/skill/SKILL.md]()

## 命令行接口

### 可用命令

| 命令 | 功能 | 必需参数 |
|------|------|----------|
| `brv swarm query` | 跨提供者搜索 | 查询字符串 |
| `brv swarm curate` | 存储知识到提供者 | 内容字符串 |
| `brv swarm status` | 检查提供者健康状态 | 无 |
| `brv swarm onboard` | 初始化Swarm配置 | 无 |

### 全局参数

| 参数 | 描述 | 默认值 |
|------|------|--------|
| `--explain` | 显示详细路由信息 | false |
| `--format json` | JSON格式输出 | false |
| `-n <数量>` | 限制结果数量 | 全部 |
| `--provider <id>` | 指定目标提供者 | 自动选择 |

## 高级配置

### 提供者选择策略

Swarm支持细粒度的提供者选择控制：

```yaml
swarm:
  query:
    # 查询时使用的提供者
    providers:
      - byterover
      - obsidian
      - gbrain
      - memory-wiki
    # RRF融合参数
    fusion:
      k: 60  # RRF常数，通常为60
  curate:
    # 整理时的默认提供者优先级
    priority:
      - gbrain
      - local-markdown:project-docs
      - memory-wiki
```

### 环境变量引用

配置文件支持使用`${VAR}`语法引用环境变量：

```yaml
providers:
  obsidian:
    path: ${OBSIDIAN_VAULT_PATH}
  gbrain:
    path: ${GBRAIN_WORKSPACE}
```

资料来源：[src/agent/infra/swarm/config/swarm-config-loader.ts]()

## 最佳实践

### 查询优化

1. **结合使用**：运行`brv swarm query`的同时运行`brv query`，可以扩大召回范围
2. **使用explain模式**：调试时使用`--explain`了解提供者选择和融合过程
3. **限制结果数量**：大数据集时使用`-n`参数控制输出

### 整理策略

1. **检查现有结构**：整理前先检查现有域和主题，避免重复创建
2. **使用精确提供者**：当需要存储到特定提供者时使用`--provider`参数
3. **利用自动分类**：信任系统的自动路由逻辑，除非有特殊需求

### 配置建议

1. **定期检查状态**：运行`brv swarm status`确保所有提供者健康
2. **使用onboard初始化**：首次配置使用`brv swarm onboard`引导完成
3. **验证配置文件**：确保`.brv/swarm/config.yaml`格式正确

## 故障排除

### 常见问题

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 查询无结果 | 提供者路径无效 | 检查配置文件，更新路径 |
| 整理失败 | 提供者不可写 | 检查提供者写权限 |
| 配置加载错误 | YAML格式错误 | 验证YAML语法 |
| 提供者不健康 | 路径不存在 | 确认目录存在 |

### 诊断步骤

1. 运行`brv swarm status`检查所有提供者状态
2. 验证`.brv/swarm/config.yaml`配置正确
3. 确认各提供者的存储路径存在且可访问
4. 检查环境变量是否正确设置

## 相关文档

- [上下文树结构说明](./context-tree-structure.md)
- [Curate服务文档](./curate-service.md)
- [命令行参考手册](./command-reference.md)

---

<a id='tui-interface'></a>

## TUI交互界面

### 相关页面

相关主题：[WebUI管理面板](#webui-dashboard), [Agent核心系统](#agent-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/tui/components/execution/execution-tool.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/execution-tool.tsx)
- [src/tui/components/execution/expanded-log-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/components/execution/expanded-log-view.tsx)
- [src/tui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/tui/features/hub/components/hub-detail-step.tsx)
</details>

# TUI交互界面

## 概述

ByteRover CLI 的 TUI（终端用户界面）模块是一个基于文本的交互界面，使用 React 组件和渲染库构建，为开发者在终端环境中提供可视化的工作流程体验。TUI 模块位于 `src/tui/` 目录下，采用组件化架构设计，支持命令行操作、日志展示、技能市场浏览等功能。

TUI 界面通过自包含的渲染管线将复杂的 Agent 工作流状态实时呈现给用户，包括工具调用执行、进度追踪、文件变更展示等核心功能。界面采用深色主题设计，符合现代开发者工具的视觉风格。

## 架构设计

### 组件层级结构

TUI 模块遵循 React 组件树结构，主要分为以下几大功能区域：

```mermaid
graph TD
    A[TUI Root] --> B[布局组件]
    A --> C[命令输入组件]
    A --> D[执行展示组件]
    A --> E[功能面板]
    
    B --> B1[主布局]
    B --> B2[侧边栏]
    
    C --> C1[命令输入框]
    C --> C2[斜杠命令处理器]
    
    D --> D1[工具执行展示]
    D --> D2[日志视图]
    D --> D3[流式内容]
    D --> D4[变更追踪]
    
    E --> E1[Hub 市场]
    E --> E2[上下文历史]
    E --> E3[任务管理]
```

### 执行流程状态机

Agent 执行过程中的状态转换通过 TUI 组件实时反映：

```mermaid
stateDiagram-v2
    [*] --> Running : 开始执行
    Running --> Completed : 成功完成
    Running --> Failed : 执行失败
    Completed --> [*] : 用户确认
    Failed --> [*] : 用户查看后关闭
    
    Running --> Streaming : 流式输出
    Streaming --> Running : 数据更新
```

## 核心组件

### 执行展示组件

#### 工具调用展示 (`execution-tool.tsx`)

该组件负责在执行过程中显示单个工具调用的状态信息。根据工具调用的状态，组件渲染不同的视觉标识：

| 状态值 | 视觉表现 | 颜色配置 |
|--------|----------|----------|
| `success` | ✓ 前缀绿色对勾 | `colors.primary` |
| `running` | 闪烁圆圈动画 | `colors.dimText` |
| `failed` | ✗ 前缀红色叉号 | `colors.errorText` |

组件接收以下属性：

```typescript
interface ExecutionToolProps {
  toolCall: ToolCall;      // 工具调用数据
  toolName?: string;      // 工具显示名称
  toolArguments?: string; // 工具参数字符串
}
```

当工具处于 `running` 状态时，组件渲染 `<BlinkingCircle />` 动画元素，提示用户当前正在处理中。

#### 展开日志视图 (`expanded-log-view.tsx`)

该组件是执行日志的核心展示容器，集成了多种内容类型的渲染能力：

| 内容区域 | 触发条件 | 组件 |
|----------|----------|------|
| 输入信息 | 始终显示 | `<Text>` |
| 进度追踪 | `toolCalls` 或 `reasoningContents` 存在 | `<ExecutionProgress />` |
| 流式内容 | `status === 'running'` 且有 `streamingContent` | `<StreamingText />` |
| 执行结果 | `status === 'failed'` 或 `status === 'completed'` | `<ExecutionContent />` |
| 变更列表 | `status === 'completed'` | `<ExecutionChanges />` |

组件的数据结构定义：

```typescript
interface ExpandedLog {
  input: string;
  files?: string[];
  toolCalls?: ToolCall[];
  reasoningContents?: ReasoningContent[];
  streamingContent?: string;
  isStreaming?: boolean;
  status: 'running' | 'completed' | 'failed';
  content?: string;
  changes: {
    created: string[];
    updated: string[];
  };
}
```

流式文本内容通过 `StreamingText` 组件渲染，支持实时光标显示和动态内容更新。当 `isStreaming` 为 true 时，光标会持续闪烁，提示用户数据仍在传输中。

#### 变更追踪展示

执行完成后的变更内容通过 `ExecutionChanges` 组件展示，该组件接受以下参数：

```typescript
interface ExecutionChangesProps {
  created: string[];     // 创建的文件路径列表
  updated: string[];     // 更新的文件路径列表
  isExpanded: boolean;   // 是否展开显示
  maxChanges: {
    created: number;     // 创建文件的最大显示数量
    updated: number;     // 更新文件的最大显示数量
  };
}
```

文件路径以 `@` 前缀形式展示，如 `@src/main.ts`，便于用户识别文件位置。

### Hub 功能面板

#### 详情展示 (`hub-detail-step.tsx`)

Hub 面板提供技能和 Agent 的详细信息浏览功能。组件展示的数据字段包括：

| 字段 | 显示标签 | 样式说明 |
|------|----------|----------|
| `version` | 版本号 | 卡片式布局 |
| `registry` | 仓库名 | 卡片式布局，默认值 'default' |
| `tags` | 标签列表 | 以 `#` 前缀显示 |
| `dependencies` | 依赖项 | 警告色显示 |
| `category` | 分类 | 标准文本 |
| `author.name` | 作者 | 左对齐标签配右对齐值 |
| `license` | 许可证 | 左对齐标签配右对齐值 |
| `file_tree` | 文件列表 | 缩进显示 |

当条目类型为 `agent-skill` 时，组件额外渲染目标 Agent 选择器：

```typescript
// Agent 选择器配置
const AGENT_VALUES = ['Codex', /* other agents */];

<select
  id={`agent-${entry.id}`}
  value={agentSelections[entry.id] ?? 'Codex'}
  onChange={(event) => setAgentSelections({...current, [entry.id]: event.target.value})}
>
  {AGENT_VALUES.map((agent) => (
    <option key={agent} value={agent}>{agent}</option>
  ))}
</select>
```

#### 快捷键绑定

Hub 详情面板支持以下键盘交互：

| 按键 | 功能 |
|------|------|
| `Enter` | 安装选中的技能/Agent |
| `o` | 在浏览器中打开详情 |
| `Esc` | 返回上一级 |

## 状态管理

### 执行状态流转

TUI 界面的执行状态管理遵循以下流程：

```mermaid
sequenceDiagram
    participant User as 用户
    participant CLI as 命令行
    participant Agent as Agent服务
    participant TUI as TUI组件
    
    User->>CLI: 输入命令
    CLI->>Agent: 发起执行请求
    Agent-->>TUI: 流式返回状态
    TUI->>TUI: 更新running状态
    TUI->>TUI: 渲染流式内容
    
    Agent-->>CLI: 执行完成
    CLI-->>TUI: 发送completed/failed
    TUI->>TUI: 更新最终状态
    TUI->>TUI: 展示变更列表
```

### Hub 选择状态

Agent 选择状态通过 `useState` 管理：

```typescript
const [agentSelections, setAgentSelections] = useState<Record<string, string>>({});

// 更新单个选择
setAgentSelections((current) => ({
  ...current,
  [entry.id]: event.target.value
}));
```

## 视觉设计

### 配色系统

TUI 组件采用终端友好的配色方案：

| 用途 | 颜色变量 | 说明 |
|------|----------|------|
| 主色调 | `colors.primary` | 成功状态、强调元素 |
| 文字色 | `colors.text` | 主要文本内容 |
| 暗淡文字 | `colors.dimText` | 次要信息、标签 |
| 错误色 | `colors.errorText` | 失败状态、警告 |
| 警告色 | `colors.warning` | 依赖项展示 |

### 布局模式

组件采用灵活的布局系统，主要使用以下布局属性：

- `flexDirection: 'row' | 'column'` - 主轴方向
- `gap: number` - 子元素间距
- `marginBottom: number` - 底部外边距
- `paddingX: number` - 水平内边距

## 技术实现要点

### 渲染管线

TUI 采用声明式渲染模式，组件根据状态变化自动重新渲染。关键优化点包括：

1. **条件渲染**：仅在数据存在时渲染对应内容区域
2. **状态隔离**：每个日志条目维护独立的状态副本
3. **流式处理**：支持 `isStreaming` 标志控制实时内容更新

### 组件复用策略

通过抽象公共接口实现组件复用：

- `ExecutionTool` 和 `ExecutionContent` 共享错误状态处理逻辑
- `StreamingText` 组件同时服务于执行日志和普通流式输出
- Hub 面板的布局模式可扩展至其他详情展示场景

## 相关命令

TUI 界面支持通过 `brv` 命令行工具触发：

```bash
brv webui        # 启动 WebUI 界面
brv login        # 用户认证
brv init         # 初始化项目
brv status       # 查看连接状态
```

## 源码引用

| 组件 | 文件路径 | 功能描述 |
|------|----------|----------|
| 工具执行展示 | `src/tui/components/execution/execution-tool.tsx:1-24` | 渲染工具调用状态 |
| 展开日志视图 | `src/tui/components/execution/expanded-log-view.tsx:1-50` | 聚合展示执行详情 |
| Hub详情面板 | `src/tui/features/hub/components/hub-detail-step.tsx:1-80` | 技能市场详情浏览 |

## 扩展说明

### 流式内容处理

`expanded-log-view.tsx` 中的流式内容展示采用以下策略：

1. 监测 `streamingContent` 和 `isStreaming` 属性
2. 处于 `running` 状态时持续渲染 `<StreamingText />`
3. `showCursor` 属性在 `isStreaming` 为 true 时激活闪烁光标
4. `maxLines={0}` 配置允许内容无限延展

### 错误处理可视化

执行失败时的错误信息通过以下流程呈现：

1. 检测 `status === 'failed'`
2. 使用 `isError` 属性高亮错误文本
3. 错误内容从 `content` 字段提取
4. 配合 `colors.errorText` 配色方案突出显示

---

<a id='webui-dashboard'></a>

## WebUI管理面板

### 相关页面

相关主题：[TUI交互界面](#tui-interface)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/webui/index.html](https://github.com/campfirein/byterover-cli/blob/main/src/webui/index.html)
- [src/webui/features/hub/components/hub-panel.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/hub/components/hub-panel.tsx)
- [src/webui/features/hub/components/hub-detail-step.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/hub/components/hub-detail-step.tsx)
- [src/webui/features/transport/components/offline-screen.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/transport/components/offline-screen.tsx)
- [src/webui/features/project/components/project-dropdown.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/project/components/project-dropdown.tsx)
- [src/webui/features/context/components/context-history-panel.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/context/components/context-history-panel.tsx)
- [src/webui/features/tasks/components/task-composer.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/tasks/components/task-composer.tsx)
- [src/webui/features/tasks/components/task-detail-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/tasks/components/task-detail-view.tsx)
- [src/webui/features/vc/components/diff-view.tsx](https://github.com/campfirein/byterover-cli/blob/main/src/webui/features/vc/components/diff-view.tsx)
- [src/server/infra/http/review-ui.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/review-ui.ts)
- [src/server/infra/http/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/http/callback-server.ts)
- [src/server/infra/provider-oauth/callback-server.ts](https://github.com/campfirein/byterover-cli/blob/main/src/server/infra/provider-oauth/callback-server.ts)
</details>

# WebUI管理面板

## 概述

WebUI管理面板是ByteRover CLI的图形化Web界面模块，提供项目上下文管理、技能市场、任务编辑、版本控制等核心功能的可视化操作界面。该模块基于React构建，采用TypeScript开发，通过WebSocket与本地后端服务通信，实现对AI编程助手的持久化记忆管理。

WebUI的核心价值在于将CLI的命令行操作转换为直观的图形界面，使开发者能够更便捷地管理项目知识库、查看上下文历史、浏览技能市场、以及进行版本控制操作。资料来源：[src/webui/index.html:1-13]()

## 系统架构

### 整体架构

WebUI采用前后端分离的架构设计，前端为单页应用(SPA)，后端为Express服务。系统通过WebSocket保持实时通信，同时提供HTTP API用于认证回调和数据同步。

```mermaid
graph TD
    A[用户浏览器] <--> B[WebUI前端<br/>React SPA]
    B <--> C[本地Server<br/>Express + WebSocket]
    C --> D[项目文件系统]
    C --> E[ByteRover Cloud<br/>远程同步]
    C --> F[AI Provider<br/>OAuth认证]
    
    G[CLI终端] <--> C
```

### 目录结构

WebUI模块位于`src/webui/`目录下，采用特性模块组织代码结构：

```
src/webui/
├── index.html              # HTML入口文件
├── index.tsx               # React根组件入口
├── App.tsx                 # 主应用组件
├── router.tsx              # 路由配置
├── layouts/
│   └── main-layout.tsx     # 主布局组件
├── providers/
│   └── app-providers.tsx   # 全局状态提供者
├── features/               # 功能模块
│   ├── hub/               # 技能中心
│   ├── tasks/             # 任务编辑
│   ├── context/           # 上下文管理
│   ├── project/           # 项目选择
│   ├── transport/         # 连接状态
│   └── vc/                # 版本控制
└── components/             # 通用组件
```

资料来源：[src/webui/index.html:1-13]()

## 核心功能模块

### Hub技能中心

Hub模块是WebUI的核心功能区域，提供技能和代理的管理界面。用户可以浏览、安装和管理来自不同注册表的AI技能。

#### Hub面板组件

`hub-panel.tsx`负责渲染技能列表和安装界面，支持以下功能：

| 功能 | 描述 | 源码位置 |
|------|------|----------|
| 技能列表 | 显示所有可用的技能和代理类型 | hub-panel.tsx |
| 安装按钮 | 触发技能安装流程 | hub-panel.tsx |
| 代理选择 | 为技能选择目标AI代理 | hub-panel.tsx |
| 版本显示 | 展示技能当前版本号 | hub-panel.tsx |
| 注册表信息 | 显示技能来源的注册表 | hub-panel.tsx |

组件支持`agent-skill`类型条目的代理选择功能，用户可以通过下拉菜单选择目标代理（如Codex等）。资料来源：[src/webui/features/hub/components/hub-panel.tsx:1-50]()

#### Hub详情步骤组件

`hub-detail-step.tsx`提供技能的详细元数据展示界面，包括：

| 元数据字段 | 说明 |
|-----------|------|
| Tags | 技能标签，用于分类检索 |
| Requires | 技能依赖项 |
| Category | 技能分类 |
| Registry | 技能来源注册表 |
| Author | 作者信息 |
| Version | 版本号 |

资料来源：[src/webui/features/hub/components/hub-detail-step.tsx:1-60]()

### 项目管理

项目下拉组件`project-dropdown.tsx`实现项目选择和管理功能。

```mermaid
graph LR
    A[点击下拉触发] --> B{是否有打开的项目}
    B -->|是| C[显示打开项目列表]
    B -->|否| D[显示最近项目列表]
    C --> E[选择项目]
    D --> E
    E --> F[加载项目上下文]
```

项目选择支持三种来源：

1. **当前打开的项目** - 已激活的项目列表
2. **最近项目** - 历史访问过的项目，最多显示`RECENT_LIMIT`个
3. **所有项目** - 点击"See all"展开完整列表

新项目需要通过CLI命令`brv webui`在项目目录下注册后才能在界面中显示。资料来源：[src/webui/features/project/components/project-dropdown.tsx:1-80]()

### 任务编辑

任务编辑器`task-composer.tsx`是WebUI的核心输入组件，支持多种任务类型的创建和编辑。

#### 支持的任务类型

| 类型 | 描述 | 特殊处理 |
|------|------|----------|
| curate | 知识整理任务 | 显示CurateAttachmentHint提示 |
| default | 默认任务类型 | 标准编辑器 |
| 其他 | 自定义任务类型 | 根据HelpRow配置显示帮助信息 |

#### 编辑器界面元素

- **快捷键提示**：显示键盘快捷键（如`Ctrl+Enter`提交、`Tab`使用示例）
- **字符计数**：实时显示输入内容长度
- **HelpRow帮助**：根据任务类型显示对应的帮助信息
- **ComposerFooter**：底部工具栏，包含提交、取消、详情展开等操作

```tsx
// 提交验证
const canSubmit = content.length > 0 && hasActiveProvider
```

资料来源：[src/webui/features/tasks/components/task-composer.tsx:1-100]()

#### 任务详情视图

`task-detail-view.tsx`提供任务的详细查看界面，用于展示已完成任务的完整信息、变更内容和执行结果。

### 上下文历史

`context-history-panel.tsx`组件负责展示项目的上下文提交历史记录。

| 功能 | 说明 |
|------|------|
| 当前提交 | 高亮显示当前活跃的上下文版本 |
| 历史记录 | 按时间倒序展示旧的提交记录 |
| 时间格式化 | 将时间戳转换为可读格式（如"Jan 15, 14:30"） |

```tsx
function formatCommitDate(timestamp: string): string {
  try {
    return `Updated at ${format(new Date(timestamp), 'MMM d, HH:mm')}`
  } catch {
    return 'Updated'
  }
}
```

资料来源：[src/webui/features/context/components/context-history-panel.tsx:1-80]()

### 版本控制差异视图

`diff-view.tsx`组件提供文件变更的可视化对比功能，支持：

- 创建文件高亮（绿色背景）
- 更新文件差异展示
- 删除文件标记（红色）

### 连接状态管理

`offline-screen.tsx`组件处理网络连接状态的UI展示。

| 状态 | 显示内容 | 指示器颜色 |
|------|----------|-----------|
| 正常连接 | 无特殊显示 | 绿色 |
| 离线 | "Offline"徽章 | 黄色警告 |
| 配置错误 | "Unreachable"徽章 | 红色错误 |
| 重连中 | 重连尝试次数显示 | 脉冲动画 |

```tsx
// 重连状态显示
{isConfigError ? (
  <span>Refresh once the host is back.</span>
) : (
  <>
    <span className="animate-pulse">Reconnecting</span>
    <span>attempt {reconnectCount}</span>
  </>
)}
```

资料来源：[src/webui/features/transport/components/offline-screen.tsx:1-80]()

## 认证与回调系统

### OAuth回调处理

ByteRover支持多种AI Provider的OAuth认证，后端服务提供专用的回调处理。

#### HTTP回调服务器

`src/server/infra/http/callback-server.ts`提供认证回调的HTML响应：

| 函数 | 功能 |
|------|------|
| successHtml | 渲染认证成功页面，2秒后自动关闭 |
| errorHtml | 渲染认证失败页面，显示错误详情 |

成功页面包含：
- 品牌Logo展示
- "Authentication Successful"标题
- 自动关闭提示

错误页面包含：
- 错误图标
- 错误描述文本
- 可选的详细错误信息（使用`escapeHtml`转义）

#### Provider OAuth回调

`src/server/infra/provider-oauth/callback-server.ts`提供Provider特定的OAuth回调页面，包含：
- 品牌Logo和标题
- 成功/失败状态展示
- CSS内联样式确保无依赖运行

资料来源：[src/server/infra/http/callback-server.ts:1-100]()
资料来源：[src/server/infra/provider-oauth/callback-server.ts:1-80]()

## 审查UI模块

`review-ui.ts`提供本地HITL（Human-in-the-Loop）审查界面的HTML生成功能。

### 特性

- **自包含设计**：所有CSS和JavaScript内联，无外部依赖
- **语义化展示**：显示操作的前置版本和当前版本摘要
- **深色主题**：采用GitHub风格的深色配色方案

### 样式变量

```css
:root {
  --bg: #0d1117;
  --bg-secondary: #161b22;
  --bg-tertiary: #21262d;
  --border: #30363d;
  --text: #e6edf3;
  --text-muted: #8b949e;
  --green: #238636;
  --red: #da3633;
  --blue: #58a6ff;
  --yellow: #d29922;
}
```

资料来源：[src/server/infra/http/review-ui.ts:1-50]()

## 执行日志展示

WebUI的执行日志组件负责展示AI代理的执行过程，包括：

| 组件 | 功能 |
|------|------|
| expanded-log-view.tsx | 展开的日志视图，显示输入、工具调用、流式内容、变更 |
| execution-tool.tsx | 单个工具调用展示，包含状态图标和参数 |
| ExecutionProgress | 推理内容和工具调用进度条 |
| ExecutionContent | 任务完成后的输出内容展示 |
| ExecutionChanges | 创建和更新的文件列表展示 |

### 日志状态

| 状态 | 样式 | 显示内容 |
|------|------|----------|
| running | 流式文本+进度条 | 实时输出 |
| completed | 绿色勾选+变更列表 | 最终结果 |
| failed | 红色叉号+错误信息 | 错误详情 |

资料来源：[src/tui/components/execution/expanded-log-view.tsx:1-80]()
资料来源：[src/tui/components/execution/execution-tool.tsx:1-50]()

## 数据流架构

```mermaid
graph TD
    subgraph 前端层
        A[React Components] --> B[Context Providers]
        B --> C[Feature Modules]
    end
    
    subgraph 通信层
        C --> D[WebSocket<br/>实时事件]
        C --> E[HTTP API<br/>REST请求]
    end
    
    subgraph 后端层
        D --> F[Express Server]
        E --> F
        F --> G[项目文件系统]
        F --> H[Cloud Sync]
        F --> I[AI Provider]
    end
    
    subgraph 存储层
        G --> J[本地知识库]
        H --> K[云端上下文]
    end
```

## 状态管理

WebUI使用React Context进行全局状态管理，主要Provider包括：

| Provider | 职责 |
|----------|------|
| AppProviders | 根级别提供者，聚合所有子Provider |
| 任务状态 | 管理当前编辑的任务内容 |
| 项目状态 | 管理选中和最近的项目列表 |
| 连接状态 | 管理WebSocket连接状态和重连逻辑 |
| Hub状态 | 管理技能列表和安装状态 |

## 总结

WebUI管理面板是ByteRover CLI的图形化操作界面，通过模块化的React组件架构提供了完整的项目上下文管理功能。主要模块包括：

- **Hub技能中心**：浏览和安装AI技能
- **项目管理**：项目选择和切换
- **任务编辑**：创建和编辑各类任务
- **上下文历史**：查看和管理知识版本
- **版本控制**：文件变更对比
- **连接状态**：网络状态监控

整个系统采用TypeScript开发，确保类型安全；通过WebSocket实现实时通信；后端Express服务提供API和OAuth认证支持。

---

---

## Doramagic 踩坑日志

项目：campfirein/byterover-cli

摘要：发现 19 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite。

## 1. 安装坑 · 来源证据：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Curator can copy prompt example facts into the context tree when using Gemini Flash-Lite
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_f0927b3fa77c4e7ab29ba04f3c4b7ed7 | https://github.com/campfirein/byterover-cli/issues/647 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 安装坑 · 来源证据：Visual corruption while browsing a long model list

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Visual corruption while browsing a long model list
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3112b1ba6fc54e0a8d973b277ab8d106 | https://github.com/campfirein/byterover-cli/issues/620 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 3. 安装坑 · 来源证据：ByteRover CLI 3.10.1

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.1
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c21085e93cad46a5b79d8ff2353f156c | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.1 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 4. 安装坑 · 来源证据：ByteRover CLI 3.10.3

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.10.3
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5ada5377aa504edeac454b6a66310a47 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.3 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：ByteRover CLI 3.8.1

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_370b6c20f13544c28427013da0519f1f | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.1 | 来源类型 github_release 暴露的待验证使用条件。

## 6. 安装坑 · 来源证据：ByteRover CLI 3.8.2

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.2
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_48b470d455aa406480648e100bc08c94 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 7. 安装坑 · 来源证据：ByteRover CLI 3.8.3

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.8.3
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_70d8761f65864cf2897a70138eabb5b7 | https://github.com/campfirein/byterover-cli/releases/tag/v3.8.3 | 来源类型 github_release 暴露的待验证使用条件。

## 8. 安装坑 · 来源证据：ByteRover CLI 3.9.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ByteRover CLI 3.9.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_955f12701a864106895fc95c8ef7fd05 | https://github.com/campfirein/byterover-cli/releases/tag/v3.9.0 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 9. 安装坑 · 来源证据：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`brv mcp` client stuck in infinite exception loop consuming 75–90% CPU for hours
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_50500a3417394344864f50cf765157ea | https://github.com/campfirein/byterover-cli/issues/660 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 10. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | README/documentation is current enough for a first validation pass.

## 11. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | last_activity_observed missing

## 12. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium

## 13. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | no_demo; severity=medium

## 14. 安全/权限坑 · 来源证据：ByteRover CLI 3.10.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_78241481b8c647e4a05827b06eafdc99 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 15. 安全/权限坑 · 来源证据：ByteRover CLI 3.10.2

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.10.2
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2af62a087710490b8250f23ac6258644 | https://github.com/campfirein/byterover-cli/releases/tag/v3.10.2 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

## 16. 安全/权限坑 · 来源证据：ByteRover CLI 3.11.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.11.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ea3c8b32846b4edfaef28f8aa1cca40f | https://github.com/campfirein/byterover-cli/releases/tag/v3.11.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 17. 安全/权限坑 · 来源证据：ByteRover CLI 3.12.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：ByteRover CLI 3.12.0
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_917109bf273c4c09a26a50f00fd1b6e4 | https://github.com/campfirein/byterover-cli/releases/tag/v3.12.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 18. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | issue_or_pr_quality=unknown

## 19. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1005233473 | https://github.com/campfirein/byterover-cli | release_recency=unknown

<!-- canonical_name: campfirein/byterover-cli; human_manual_source: deepwiki_human_wiki -->