# https://github.com/reviewboard/rbtools 项目说明书

生成时间：2026-06-14 14:23:01 UTC

## 目录

- [项目概述与安装](#page-overview)
- [命令行工具 rbt 与子命令](#page-commands)
- [SCM 客户端架构与支持矩阵](#page-scm-clients)
- [Python API、配置系统与扩展机制](#page-api-extensibility)

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

## 项目概述与安装

### 相关页面

相关主题：[命令行工具 rbt 与子命令](#page-commands), [Python API、配置系统与扩展机制](#page-api-extensibility)

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

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

- [README.md](https://github.com/reviewboard/rbtools/blob/main/README.md)
- [rbtools/commands/post.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/post.py)
- [rbtools/commands/review.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/review.py)
- [rbtools/commands/setup_completion.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/setup_completion.py)
- [rbtools/commands/setup_repo.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/setup_repo.py)
- [rbtools/utils/commands.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/commands.py)
- [rbtools/utils/review_request.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/review_request.py)
- [rbtools/utils/source_tree.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/source_tree.py)
</details>

# 项目概述与安装

## 一、项目定位与功能范围

RBTools 是 Review Board 项目官方发布的命令行工具与 Python API 集合，旨在让开发者通过终端即可完成与 Review Board 服务器的交互。资料来源：[README.md]() 中明确指出，RBTools 提供的主要能力包括：

- 提交变更以供评审（post）
- 维护已发布评审请求的更新（diff / update）
- 将已通过评审的变更合入分支（land）
- 应用他人提交的补丁进行本地验证（patch）
- 查询当前待办评审请求的工作量（status / list）

该工具同时提供 Python API，使第三方集成（如 CI、IDE 插件）能够复用 RBTools 的 SCM 检测、差异生成与 API 客户端逻辑。资料来源：[README.md]() 中提到 "rich Python API for use with Review Board"。

RBTools 的最新稳定版本为 5.2，重点强化了对各 SCM 系统的兼容性，并修复了一系列 Bug（例如：Subversion 跨分支应用补丁的场景）。更早的 4.1 版本则主要面向即将发布的 Review Board 6 做适配，并改善了 Windows 与 Perforce 集成的体验。

## 二、安装与初始化

### 2.1 包分发与安装渠道

RBTools 通过 [PyPI](https://pypi.org/project/RBTools) 发布，README 中的徽章显示包名为 `RBTools`，遵循 MIT 开源协议，支持多个 Python 版本。资料来源：[README.md]() 中标识的 PyPI 与 License 徽章。

典型的安装方式为：

```bash
pip install RBTools
```

安装完成后即可使用统一的入口命令 `rbt`，所有子命令（如 `rbt post`、`rbt diff`、`rbt land`、`rbt patch`）都通过该入口分发。资料来源：[README.md]() 指出 "you'll do most everything through the `rbt` command"。

### 2.2 仓库配置初始化

初次使用时，需要让 RBTools 知道本地工作区对应的 Review Board 仓库，这由 `rbt setup-repo` 命令承担。资料来源：[rbtools/commands/setup_repo.py]() 中实现了交互式流程：提示用户输入 Review Board 服务地址，调用 `self.get_api(server)` 验证连通性，然后通过 `initialize_scm_tool()` 与 `get_repository_resource()` 探测本地 SCM 类型并匹配远端仓库，最终生成 `.reviewboardrc` 配置文件。

### 2.3 Shell 自动补全

为提升日常使用体验，RBTools 提供 `rbt setup-completion` 子命令。资料来源：[rbtools/commands/setup_completion.py]() 显示该命令通过 `importlib_resources.files('rbtools')` 读取 `rbtools/commands/conf/completions/<shell>` 下的补全脚本，并将其输出到终端；自 5.0 起不再写入系统目录，而是交由用户自行 source 使用。当前支持 `bash` 与 `zsh`。

## 三、整体架构与执行流程

RBTools 在运行时按"命令注册 → SCM 探测 → API 客户端 → 业务执行"的分层方式工作：

```mermaid
flowchart LR
    A[rbt 入口] --> B[BaseCommand 子类]
    B --> C[SCMClient 扫描]
    C --> D[生成 diff/修订信息]
    B --> E[Review Board API 客户端]
    D --> E
    E --> F[Review Board 服务器]
```

资料来源：命令体系在 [rbtools/commands/post.py]()、`rbtools/commands/review.py` 中通过继承 `BaseCommand` 实现；SCM 扫描逻辑位于 [rbtools/utils/source_tree.py]()，使用 `scmclient_registry` 注册表匹配 SCM 类型；API 调用则借助 `rbtools.api` 模块封装。

关键模块职责划分如下：

| 模块 | 职责 |
| --- | --- |
| `rbtools/commands/` | 各 `rbt` 子命令实现，继承 `BaseCommand` |
| `rbtools/clients/` | 各 SCM 客户端（Git、SVN、Perforce 等），通过 `scmclient_registry` 注册 |
| `rbtools/api/` | Review Board Web API 的 Python 封装 |
| `rbtools/utils/` | 通用工具：控制台、命令工具、评审请求匹配、源码树扫描等 |
| `rbtools/commands/base/output.py` | 命令输出管理（含 `--json` 支持） |

## 四、核心工具与常用命令

### 4.1 评审请求匹配

`rbt post` 在更新已有评审请求时，需要根据当前 SCM 修订号匹配已有请求。资料来源：[rbtools/utils/review_request.py]() 中的 `guess_existing_review_requests` 函数通过 `api_root.get_review_requests(... commit_id=change_id ...)` 查找匹配项，并支持按 `changenum` 兼容老版本 API。`STAMP_STRING_FORMAT` 工具常量定义于 [rbtools/utils/commands.py]()，格式为 `Reviewed at %s`，供 `rbt stamp`、`rbt patch`、`rbt land` 写入提交信息以便服务器端识别。

### 4.2 通用命令行工具

`rbtools/utils/commands.py` 集中维护了 `DEFAULT_OPTIONS_MAP`，将通用选项（如 `--server`、`--username`、`--api-token`、`--repository`）映射到对应 CLI 标志，便于各子命令复用。

### 4.3 输出能力

命令的输出统一由 [rbtools/commands/base/output.py]() 中的 `JSONOutput` 类管理，使所有命令支持 `--json` 参数以便脚本化调用。资料来源：[rbtools/commands/base/output.py]() 中描述 "Commands should add any structured output to this object"。

## 五、获取支持与社区资源

README 列出了三类支持渠道：购买专属支持合约、加入社区邮件列表 [groups.google.com/group/reviewboard](http://groups.google.com/group/reviewboard/)，以及在 [Review Board Bug Tracker](https://www.reviewboard.org/bugs/) 提交缺陷。贡献者可以通过 [reviews.reviewboard.org](https://reviews.reviewboard.org) 提交补丁。资料来源：[README.md]()。

## See Also

- 命令参考：`rbt post`、`rbt diff`、`rbt land`、`rbt patch`、`rbt setup-repo`、`rbt setup-completion`
- 相关项目：[Review Board](https://www.reviewboard.org)、[Djblets](https://github.com/djblets/djblets/)、[Review Bot](https://www.reviewboard.org/downloads/reviewbot/)、[RB Gateway](https://www.reviewboard.org/downloads/rbgateway/)

---

<a id='page-commands'></a>

## 命令行工具 rbt 与子命令

### 相关页面

相关主题：[项目概述与安装](#page-overview), [SCM 客户端架构与支持矩阵](#page-scm-clients), [Python API、配置系统与扩展机制](#page-api-extensibility)

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

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

- 资料来源： [rbtools/commands/main.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/main.py)
- 资料来源： [rbtools/commands/post.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/post.py)
- 资料来源： [rbtools/commands/diff.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/diff.py)
- 资料来源： [rbtools/commands/land.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/land.py)
- 资料来源： [rbtools/commands/patch.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/patch.py)
- 资料来源： [rbtools/commands/setup_repo.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/setup_repo.py)
</details>

# 命令行工具 rbt 与子命令

## 概述与定位

`rbt` 是 RBTools 项目对外提供的命令行入口，提供与 Review Board 服务器交互的能力，包括创建和更新 review request、应用补丁、合并已批准的变更、添加评论、生成项目仓库配置等。该工具与同名的 Python API 一起构成 RBTools 的完整能力集合。

资料来源：[README.md](https://github.com/reviewboard/rbtools/blob/main/README.md)

## 命令发现机制

`rbt` 通过 Python 标准的 `importlib.metadata` 入口点机制来发现并加载所有子命令。`find_entry_point_for_command()` 函数首先在 `rbtools` 包内查找 `rbtools_commands` 入口点组中的命令，若未命中则回退到第三方命令；这一设计使得扩展或插件可以无侵入地添加新命令。

资料来源：[rbtools/commands/__init__.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/__init__.py)

入口点加载完成后，主类 `_RB_MAIN`（重导出为 `RB_MAIN`）会按需解析用户输入的子命令名，查找命令类、收集其选项并执行。

## 核心子命令一览

下表列出了 `rbt` 工具内置的核心子命令及其职责：

| 子命令 | 模块 | 主要职责 |
| --- | --- | --- |
| `post` | `rbtools/commands/post.py` | 创建新的 review request 或更新已有草稿 |
| `patch` | `rbtools/commands/patch.py` | 从服务器下载指定 review request 的补丁并本地应用 |
| `land` | `rbtools/commands/land.py` | 将已批准的变更合并到目标分支并推送 |
| `review` | `rbtools/commands/review.py` | 在草稿上添加评论、编辑/发布评论 |
| `setup-repo` | `rbtools/commands/setup_repo.py` | 生成或更新 `.reviewboardrc` 配置文件 |
| `setup-completion` | `rbtools/commands/setup_completion.py` | 输出 bash 或 zsh 的自动补全脚本 |

其中 `rbt post` 是最常用的入口：它会检测 SCM 工具、生成 diff 并通过 Review Board API 创建或更新 review request（资料来源：[rbtools/commands/post.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/post.py)）。`rbt land` 在执行时要求 review request 已经过审批，并通过 SCM 客户端完成合并与推送（资料来源：[rbtools/commands/land.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/land.py)）。

## 通用命令模式

### 选项与参数

每个子命令均继承自 `BaseCommand`，通过 `Option` 与 `OptionGroup` 声明参数；许多选项带 `config_key`，允许从 `.reviewboardrc` 中读取默认值。例如 `rbt land` 的 `--dest` 选项通过 `config_key='LAND_DEST_BRANCH'` 与配置文件联动（资料来源：[rbtools/commands/land.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/land.py)）。

### 输出管理

`rbt` 提供统一的输出抽象：`JSONOutput` 类用于在 `--json` 模式下收集结构化输出，`OutputWrapper` 用于常规文本输出并自动处理编码（资料来源：[rbtools/commands/base/output.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/base/output.py)）。`rbtools/utils/commands.py` 中维护了常用命令行选项到 `rbt` 参数的映射 `DEFAULT_OPTIONS_MAP`，方便子命令复用（资料来源：[rbtools/utils/commands.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/commands.py)）。

### Review request 工具

`rbtools/utils/review_request.py` 提供了若干被多个子命令共享的工具函数，例如 `guess_existing_review_request` 用于在创建新 review request 之前猜测是否已有匹配的请求（资料来源：[rbtools/utils/review_request.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/review_request.py)）。`STAMP_STRING

---

<a id='page-scm-clients'></a>

## SCM 客户端架构与支持矩阵

### 相关页面

相关主题：[命令行工具 rbt 与子命令](#page-commands), [Python API、配置系统与扩展机制](#page-api-extensibility)

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

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

- [rbtools/utils/source_tree.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/source_tree.py)
- [rbtools/commands/base/commands.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/base/commands.py)
- [rbtools/utils/repository.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/repository.py)
- [rbtools/commands/setup_repo.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/setup_repo.py)
- [rbtools/commands/post.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/post.py)
- [rbtools/utils/review_request.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/review_request.py)
- [README.md](https://github.com/reviewboard/rbtools/blob/main/README.md)
</details>

# SCM 客户端架构与支持矩阵

## 概述与设计目标

RBTools 是 [Review Board](https://www.reviewboard.org) 的命令行与 Python API 工具集，SCM 客户端子系统承担**本地源码仓库检测、差异生成、与服务器通信**三项工作。该子系统采用注册表（registry）模式管理多个 SCM 客户端，并通过能力协商（capabilities）适配不同版本的 Review Board 服务器（[README.md]()）。

设计上，SCM 客户端的关键职责包括：

- 在当前工作目录或父目录中识别用户使用的源码管理工具；
- 将本地路径与服务器端仓库记录匹配，避免手工配置；
- 根据服务器能力启用或禁用特定行为（例如 `commit_ids` 字段）；
- 在差异生成时携带 SCM 特有的元数据（如 commit ID、changenum），用于 `post` 命令的更新流程（[rbtools/commands/post.py]()）。

## 源码扫描与客户端发现

核心数据结构定义在 [rbtools/utils/source_tree.py]()：

- `SCMClientScanCandidate`：扫描过程中匹配到的候选 SCM 客户端及其本地路径；
- `SCMClientScanResult`：扫描最终结果，包含一个或零个匹配的 `BaseSCMClient`。

模块通过 `from rbtools.clients import (BaseSCMClient, RepositoryInfo, scmclient_registry)` 引入全局注册表，并在 `chdir` 辅助下在不同目录间切换探测（[rbtools/utils/source_tree.py]()）。`BaseCommand.initialize_scm_tool` 调用 `scan_usable_client` 完成实际探测；若未找到工具但 `tool_required=False`，则返回 `(None, None)` 供后续 TREES 逻辑使用（[rbtools/commands/base/commands.py]()）。

```mermaid
flowchart LR
    A[当前工作目录] --> B[scan_usable_client]
    B --> C{注册表匹配?}
    C -- 是 --> D[BaseSCMClient 实例]
    C -- 否 --> E[回退或报错]
    D --> F[check_options]
    F --> G[get_diff_tool]
```

## 仓库匹配与能力协商

`get_repository_resource` 负责把本地仓库路径翻译成服务器端仓库对象（[rbtools/utils/repository.py]()）。查询字段被严格限制为 `id,name,mirror_path,path`，仅展开 `info,diff_file_attachments` 链接，以减少负载。

当传入本地工具时，函数首先调用 `tool.get_server_tool_names(capabilities)` 获取服务器识别的工具名，并写入查询 `tool` 参数。若用户提供明确的 `repository_name`，则使用 `name` 查询；否则把 `repository_paths` 拼接为 `path` 列表（[rbtools/utils/repository.py]()）。`setup_repo` 命令复用该函数，让用户从服务器返回的 `closest_paths` 中选择，从而生成 `.reviewboardrc` 配置文件（[rbtools/commands/setup_repo.py]()）。

能力协商影响具体字段的启用。例如 `supports_posting_commit_ids = self.capabilities.has_capability('review_requests', 'commit_ids')` 控制是否在 update 阶段写入 `commit_id`（[rbtools/commands/post.py]()）；当 `squashed_diff.commit_id` 与现有草稿不同时，会被加入 `update_fields`。

## 配置集成与 TREES 命名空间

[rbtools/commands/base/commands.py]() 中展示了 TREES 配置的处理流程：当用户在 `.reviewboardrc` 设置 `TREES` 字典时，基命令会先尝试初始化 SCM 工具，再把所有可能的路径（`local_path`、`path` 列表或 `os.getcwd()`）作为命名空间键查找对应的子树配置。该机制支持多仓库并存场景，使每个子仓库可以拥有独立的 `REVIEWBOARD_URL`、`BRANCH` 等配置。

`post` 命令最终根据匹配的 `tool`、服务器能力以及现有草稿，计算更新字段并通过 `extra_data` 持久化 SCM 状态（[rbtools/commands/post.py]()）；`review_request` 工具则依据 `commit_id` 或 `changenum` 在用户历史评审请求中查找匹配项，避免重复创建（[rbtools/utils/review_request.py]()）。

## 兼容性说明

社区讨论中提到 RBTools 5.2 改善了 Subversion 补丁跨分支应用能力，RBTools 4.1 强化了 Windows 与 Perforce 集成（[README.md]()）。这些增强都依赖于上述 SCM 客户端扫描与能力协商层：当用户切换 SCM 或服务器版本时，注册表和能力检查会自动选择合适的代码路径，无需人工干预。

## See Also

- [Review Board API 文档](https://www.reviewboard.org/docs/manual/latest/webapi/)
- RBTools Python API 参考（项目内 `docs/` 目录）

---

<a id='page-api-extensibility'></a>

## Python API、配置系统与扩展机制

### 相关页面

相关主题：[项目概述与安装](#page-overview), [命令行工具 rbt 与子命令](#page-commands), [SCM 客户端架构与支持矩阵](#page-scm-clients)

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

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

- [rbtools/testing/api/payloads.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/testing/api/payloads.py)
- [rbtools/testing/api/transport.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/testing/api/transport.py)
- [rbtools/utils/review_request.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/review_request.py)
- [rbtools/utils/repository.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/repository.py)
- [rbtools/utils/commands.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/commands.py)
- [rbtools/utils/filesystem.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/utils/filesystem.py)
- [rbtools/commands/base/commands.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/base/commands.py)
- [rbtools/commands/base/output.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/base/output.py)
- [rbtools/commands/post.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/post.py)
- [rbtools/commands/setup_repo.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/setup_repo.py)
- [rbtools/commands/status.py](https://github.com/reviewboard/rbtools/blob/main/rbtools/commands/status.py)
- [README.md](https://github.com/reviewboard/rbtools/blob/main/README.md)
</details>

# Python API、配置系统与扩展机制

RBTools 是 Review Board 官方提供的命令行工具集与 Python API 库，定位为"在终端与脚本中操作 Review Board 服务"的入口层 资料来源：[README.md:1-40]()。除了 `rbt` CLI 工具之外，RBTools 也对外暴露了 Python 包 `rbtools`，允许第三方脚本和插件以编程方式访问 Review Board 资源、处理差异、匹配已有 review request。本页聚焦 RBTools 在 5.x 版本（基于 RBTools 4.1/5.2 发布说明）下所提供的三类核心扩展面：Python API 客户端、配置系统、命令与传输层扩展机制。

## 1. Python API 与传输层

### 1.1 传输抽象与测试桩

RBTools 把 HTTP 通信抽象为 `Transport`，并提供可在单元测试中直接构造响应的 `URLMapTransport`。该传输通过 URL → 响应映射，让单元测试在不连接真实 Review Board 服务的情况下模拟 API 调用 资料来源：[rbtools/testing/api/transport.py:1-60]()。配合 `ResourcePayloadFactory`，可以批量生成 list / item / error 三类响应负载，以及 review request、draft、repository、info 等对象的数据字典 资料来源：[rbtools/testing/api/payloads.py:1-120]()。

```python
# 测试示例：注册一个 review request item URL
transport.add_item_url(
    'review-requests/123/',
    payload_func=transport.payload_generator.make_review_request_object_data,
    method='GET',
)
```

### 1.2 Review Request 匹配工具

`rbtools.utils.review_request` 模块提供了 `guess_existing_review_request` 与 `get_review_request_by_change_id` 等函数，使用 change id、commit id、changenum 等字段在服务端定位已经存在的 review request。它会根据服务端能力（`commit_ids`）自动选择查询字段，并在必要时回退到 `changenum` 以兼容老版本 API 资料来源：[rbtools/utils/review_request.py:1-80]()。

### 1.3 仓库匹配

`rbtools.utils.repository.get_repository_resource` 负责把本地仓库信息映射到服务端 `Repository` 资源：先按 path/name 过滤，匹配失败时去掉 path 过滤并调用 SCM 工具的 `find_matching_server_repository()` 兜底匹配 资料来源：[rbtools/utils/repository.py:1-60]()。

## 2. 配置系统

RBTools 使用层级化的 `RBToolsConfig` 与 `ConfigData` 来合并多处来源的配置：

| 配置来源 | 作用 | 说明 |
| --- | --- | --- |
| 全局 `~/.reviewboardrc` | 用户级默认 | 通过 `get_home_path()` 定位 资料来源：[rbtools/utils/filesystem.py:1-60]() |
| 仓库 `.reviewboardrc` | 项目级覆盖 | `setup_repo` 命令自动生成 资料来源：[rbtools/commands/setup_repo.py:1-100]() |
| 环境变量 | CI / 临时覆盖 | `RBTOOLS_*` 系列 |
| CLI 选项 | 最高优先级 | 通过 `BaseCommand` 解析 资料来源：[rbtools/commands/base/commands.py:1-80]() |

`rbt setup-repo` 会反复提示用户输入 Review Board 服务端 URL，校验成功后写入 `CONFIG_FILENAME`（即 `.reviewboardrc`）。其输出格式遵循 `_get_output()`，将每个键渲染成 `"key = "value""` 的 INI-like 行 资料来源：[rbtools/commands/setup_repo.py:1-120]()。

## 3. 命令扩展机制

### 3.1 命令基类

所有命令继承自 `BaseCommand`（位于 `rbtools/commands/base/commands.py`）。它封装了 API 客户端初始化、能力探测、SCM 工具扫描、JSON 输出与控制台交互等通用流程。`Option` / `OptionGroup` 提供声明式参数定义 资料来源：[rbtools/commands/base/commands.py:1-80]()。

### 3.2 核心命令实现示例

`rbt post` 通过 `SquashedDiff` 命名元组聚合多次提交的差异，并使用 `_set_review_request_extra_data()` 把 SCM 状态写入 review request 的 `extra_data` 字段 资料来源：[rbtools/commands/post.py:1-120]()。`rbt status` 则把当前仓库关联的 review request 列表渲染成表格，并在启用 `--json` 时通过 `JSONOutput.append()` 输出结构化结果 资料来源：[rbtools/commands/status.py:1-80]()。

### 3.3 命令行参数复用

`build_rbtools_cmd_argv()` 把 `argparse` 解析后的 `options` 对象转回命令行字符串，方便在子命令中递归调用另一个 RBTools 命令（例如 `rbt post` 内部调用 `rbt status`） 资料来源：[rbtools/utils/commands.py:1-80]()。`stamp_commit_with_review_url()` 配合常量 `STAMP_STRING_FORMAT = 'Reviewed at %s'`，把 review request URL 写回提交信息 资料来源：[rbtools/utils/commands.py:1-100]()。

## 4. 扩展流程总览

```mermaid
flowchart LR
    A[用户/脚本] --> B[rbt CLI]
    A --> C[Python API 直接调用]
    B --> D[BaseCommand]
    C --> E[RBClient + Transport]
    D --> E
    E --> F[Review Board API]
    D --> G[SCM Client]
    G --> F
    D --> H[RBToolsConfig]
    H --> D
    F --> I[Resource Tree]
    I --> J[URLMapTransport<br/>测试桩]
```

第三方开发者既可以通过"继承 `BaseCommand` 注册新命令"的方式扩展 CLI，也可以跳过 CLI 层，直接复用 `rbtools.api.client.RBClient` 加上自定义 `Transport` 与单元测试工具（`URLMapTransport` + `ResourcePayloadFactory`）来构建自动化工作流。

## 5. 常见失败模式

- **认证失败**：使用 `get_user(api_client, api_root, auth_required=True)` 强制鉴权时，若服务端返回匿名用户将抛出 `AssertionError` 资料来源：[rbtools/utils/review_request.py:1-80]()。
- **仓库匹配失败**：当 `total_results == 0` 且 `tool.find_matching_server_repository()` 也未命中，`get_repository_resource()` 会返回 `None, None`，调用方必须处理"未找到仓库"的情况 资料来源：[rbtools/utils/repository.py:1-60]()。
- **已 stamp 的提交**：`AlreadyStampedError` 用于阻止重复写入 review request URL 到同一提交 资料来源：[rbtools/utils/commands.py:1-60]()。
- **JSON 输出格式错误**：`JSONOutput.append()` 接收非可序列化对象时会触发 `TypeError`，开发自定义命令时需确保仅放入基本类型 资料来源：[rbtools/commands/base/output.py:1-80]()。

## See Also

- [RBTools 4.1 发布说明（Review Board 6 适配）](https://github.com/reviewboard/rbtools/releases/tag/release-4.1)
- [RBTools 5.2 发布说明（兼容性更新）](https://github.com/reviewboard/rbtools/releases/tag/release-5.2)
- [Review Board 项目主页](https://www.reviewboard.org)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：reviewboard/rbtools

摘要：发现 6 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

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

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | github_repo:285969 | https://github.com/reviewboard/rbtools | README/documentation is current enough for a first validation pass.

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

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | github_repo:285969 | https://github.com/reviewboard/rbtools | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | github_repo:285969 | https://github.com/reviewboard/rbtools | no_demo; severity=medium

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

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | github_repo:285969 | https://github.com/reviewboard/rbtools | no_demo; severity=medium

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

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | github_repo:285969 | https://github.com/reviewboard/rbtools | issue_or_pr_quality=unknown

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

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | github_repo:285969 | https://github.com/reviewboard/rbtools | release_recency=unknown

<!-- canonical_name: reviewboard/rbtools; human_manual_source: deepwiki_human_wiki -->