# x-review **Repository Path**: luodeb/x-review ## Basic Information - **Project Name**: x-review - **Description**: No description available - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 3 - **Forks**: 0 - **Created**: 2026-05-01 - **Last Updated**: 2026-09-12 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # x-review [NO VERSION] 基于 AI 的自动化代码评审工具，专门设计用于集成 Gitee（码云）平台。 ## 项目简介 x-review 是一个用 Rust 编写的 AI 驱动代码评审工具，通过集成人工智能能力来自动化 Pull Request 代码审查流程。该工具支持 Gitee、Gitea 等代码托管平台，可以全自动分析代码变更、识别潜在问题，并生成专业的评审意见。 ### 核心特性 - **多维度代码审查**：支持 Bug 检查、逻辑分析、性能评估、规范审核和模块文档同步审计等多种审查维度 - **复盘式 re-review**：PR 更新后触发，复盘之前的审查意见是否已被修正、核查其他 reviewer 的意见，并在无遗留问题时建议合并 - **AI 智能分析**：集成 OpenAI 和 Trae 大语言模型，提供智能代码审查能力 - **Gitee 深度集成**：无缝对接 Gitee 平台的 PR、Issue、评论等功能 - **灵活的工具系统**：提供文件读取、内容搜索、Man page 获取等丰富的辅助工具 - **可配置的审查流程**：支持自定义审查阶段和提示词模板 ## 功能架构 ### 审查阶段（Stages） 项目实现了模块化的审查管道，支持以下审查维度： | 审查阶段 | 说明 | |---------|------| | BugStage | 代码缺陷和潜在 BUG 检测 | | LogicStage | 业务逻辑正确性分析 | | PerformanceStage | 性能和算法效率评估 | | DescriptionStage | PR 描述和变更说明审核 | | DocumentationStage (Design) | 按内置 `DD-*` 检查点审计 `docs/design.md` 是否与 PR diff 同步 | | DocumentationStage (Security) | 按内置 `SD-*` 检查点审计 `docs/security.md` 是否与 PR diff 同步 | | DocumentationStage (Rustdoc) | 按内置 `RD-*` 检查点审计受影响的公开 rustdoc 对象 | | GuidelinesStage | 编码规范和最佳实践检查 | | PosixStage | POSIX API 使用规范检查 | 首次审查会在管道启动时生成一次带行号的完整 diff，供代码审查阶段共享。文档阶段使用固定快照证据和单文件分页 diff，默认每批最多 3 次独立判断，不再沿用长对话工具循环。其他阶段的工具轮次上限保持不变（POSIX 24 轮、Description 30 轮、其余代码审查阶段 40 轮，配置的 `max_function_call` 更小时以配置为准）。证据不足必须明确报告阻塞。 ### 模块文档审计 Harness 模块文档审计固定支持两个场景，均由 PR 评论中的同一个命令触发： ```text docreview docreview crate=fs/filesystems/kext4 docreview crate=fs/filesystems/kext4 strict=true ``` - 不带 `crate=` 时使用默认的 diff 模式：程序先按固定 base/head 枚举变更文件、所属 crate、代码触发事实和受影响公开 Rust 对象，再把 design、security、rustdoc 资产及候选检查点分别交给三个并行子阶段；即使文档文件没有出现在 diff 中，由代码变化触发的文档同步对象也会进入审查范围； - 带 `crate=` 时使用 crate 全量模式：固定当前 PR HEAD，自动枚举指定 crate 的 `docs/design.md`、`docs/security.md`、crate 说明、公开模块、公开 API、公开类型和数据成员、公开重导出，再分批执行检查； - 普通 diff 和 crate 模式不运行代码，也不纳入依赖 rustdoc/doctest 编译的 RD-009、RD-010、RD-011、RD-012、RD-024。需要显式纳入这些规则时，对 crate 模式添加 `strict=true`。仓库日常 CI 应独立运行自己的文档构建命令；例如 x-kernel 使用 `make doc`，缺文档门禁使用 `make doc_check_missing`，不使用会启动 QEMU 的 `make run` 代替文档验证。 两种模式的 agent 工作流分别位于： - [`src/agents/templates/documentation/diff-review.zh-CN.md`](src/agents/templates/documentation/diff-review.zh-CN.md) - [`src/agents/templates/documentation/crate-review.zh-CN.md`](src/agents/templates/documentation/crate-review.zh-CN.md) 两种模式都只发布一条简短的 PR 汇总评论；完整问题、证据和整改建议会自动上传为 Gitee Markdown 代码片段，并在汇总中提供查看/下载链接。公开仓库使用公开代码片段，私有仓库保持私有，避免审计报告泄露源码。报告上传失败时也不会退化为成百上千条评论，而是用一条汇总明确提示发布阻塞。 检查点的人工维护源文件是 [`module-docs/check.xlsx`](module-docs/check.xlsx)，三个工作表分别对应 design、security 和 rustdoc。程序运行时使用同目录下导出的 TSV；工作簿调整后执行： ```bash python3 module-docs/export_checkpoints.py python3 module-docs/export_checkpoints.py --check ``` 评论 webhook/事件处理层将 PR URL、评论正文和评论 ID 交给： ```bash x-review docreview \ --pr \ --command "$COMMENT_BODY" \ --request-id "$COMMENT_ID" ``` 如果事件处理层只能提供 PR URL，也可以省略 `--command` 和 `--request-id`；x-review 会从 PR 评论中选择最新一条尚未处理的 `docreview` 命令。评论 ID 用作幂等键，重复投递不会重复审查。模型调用失败、结果缺失以及无法解析的源码范围仍会在内部结果台账中标记为 `BLOCKED`，因此不会被误判为通过；面向开发者的汇总和下载报告只展示已确认的文档问题和报告入口，不展示执行故障说明。 #### 文档审计的执行策略 - **默认只做文档审计**：文件/语法事实由程序判定，模型只处理语言、描述正确性、设计/安全语义。普通模式不运行编译器，也不会把编译型规则伪装成 PASS 或 BLOCKED；`strict=true` 才纳入 `rustdoc` lint 和 doctest，并且只采信真实编译器证据。 - **按证据需求创建语义任务**：普通文档、摘要检查只带绑定文档与签名，安全前提、错误条件等复杂检查才带实现。DeepSeek 文档任务关闭 thinking，设计、安全和实现任务保留高强度 thinking。 - **模型输出共享事实**：同一对象中由同一事实证明的多个规则可共享证据，程序仍逐项展开完整台账。漏项、重复项、坏行、证据缺失、超预算或输出截断都不会被算作通过；单个坏项也不会再报废同批其他有效项。 - **diff 使用同一执行器规则**：本地事实不交给模型，默认不纳入编译型规则。删除对象只检查删除相关规则，不再把旧对象的缺文档规则错误地报在 old side。 - **重复审计复用有效结论**：OpenAI-compatible 后端（包括通过该后端配置的 DeepSeek）默认保存完整的 `PASS / FAIL / NOT_APPLICABLE` 模型结果；`BLOCKED` 不缓存。报告标明复用数量，crate 报告还标明来源 commit。其他未提供稳定模型标识的后端（目前包括 Trae）不启用结果缓存。 crate 缓存校验同批使用的源文件、文档、补读文件、搜索目录内容、传递本地 path 依赖及相关 Cargo/构建配置；设计和安全结论还依赖整个被审计 crate。模型配置、规则、审计逻辑或相关内容变化都会使对应缓存失效。采用保守的文件/批次级依赖，不承诺“只改一个函数就只重查一个函数”。diff 缓存只复用**相同 base/head 和审查上下文**的结论。用到快照外的 Linux 源码或无法可靠追踪的证据时，该批不缓存；无法离线解析本地依赖时，crate 缓存停用并记录警告，不跳过审计。 在 `settings/configuration.toml` 的已有 `[documentation_audit]` 下配置： ```toml cache_enabled = true cache_dir = ".x-review-cache/documentation-results" cache_max_age_hours = 168 [documentation_audit.compiler] enabled = false auto_generate = true require_sandbox = true reports_dir = ".x-review-cache/compiler-evidence" toolchain = "nightly" features = [] no_default_features = false timeout_seconds = 900 ``` 首次运行仍需完成所有未能本地判定的检查；后续只有有效命中部分免去模型调用。将 `cache_enabled` 改为 `false` 可强制重新判断（仍保留本地确定性检查）。缓存默认有效期 7 天，过期结果不会复用；同名模型在服务端升级无法仅凭名称识别，必要时主动关闭缓存做一次新审计。缓存是 Git 忽略的本地 JSON，包含审计结论和依赖哈希，不包含 API key，也不会自动上传。计费以模型返回的 usage 为准，批次数及规划 token 估算不是实测账单。 先查看真实分流和冷启动调用数（不需要 API key、不运行构建、不发布评论）： ```bash cargo run --offline -- audit-plan --repo /absolute/path/to/kernel --crate fs/kvfs --revision HEAD ``` 普通 `docreview` 不生成编译器证据。只有 crate 命令显式指定 `strict=true` 时，才会为固定 commit 生成缺失证据后继续审计。严格模式的构建进程使用清空后的环境变量，禁止网络，只能写临时构建目录，并且不能读取用户主目录中除 Rust/Cargo 工具链缓存外的内容：macOS 使用系统 `sandbox-exec`，Linux 使用 `bwrap`。默认 `require_sandbox = true`，没有支持的沙箱时相关规则明确 `BLOCKED`，不会在主进程中降级裸跑，也不会改由模型猜测。 下面的 `audit-compiler` 只用于本地诊断或强制预热缓存，不是正式流程的人工前置步骤： ```bash cargo run --offline -- audit-compiler \ --repo /absolute/path/to/kernel \ --crate fs/kvfs \ --revision HEAD \ --trusted-build ``` 编译器证据只对完全相同的 commit、crate、toolchain、target 和 feature 配置有效。PR HEAD 更新后，下一次评论任务会自动生成新证据；已经存在的匹配证据直接复用。 无需 API key 的测试： ```bash cargo test --lib --bin x-review X_REVIEW_TEST_REPOSITORY=/absolute/path/to/kernel \ X_REVIEW_TEST_CRATE=fs/kvfs \ cargo test --lib offline_audit_plan -- --ignored --nocapture ``` 上面的定向测试避免运行仓库内会调用真实 API 或修改远端评论的集成测试。离线规划使用模拟结论验证检查覆盖和调用预算，不代表真实审计已通过。 为防止模型凭记忆编造 Linux API 和实现细节，系统提示词对所有阶段强制事实查证：凡是要断言内核 API 的存在性、签名、返回值、睡眠/中断上下文约束、锁语义、结构体字段等，必须先用 `search_content`/`read_file` 在配置的 `linux_source_path` 内核源码树中核实（内核相对路径如 `include/linux/xxx.h` 会自动解析到该树），意见正文须引用源码 `文件:行号` 证据；查证不到的断言不得写入 finding，依赖该断言的整条意见会被放弃。发布前的 comment 整理阶段会用搜索工具再次核查每条评论中的内核相关断言，无法核实的句子删除、核心依据不成立的评论整条丢弃。 ### 复盘管道（Re-review Pipeline） PR 更新后可触发 `re-review`，对已有意见做复盘而不是重新审查一遍： | 阶段 | 说明 | |------|------| | FeedbackRecheckStage | 拉取 PR 全部评论（x-review 自己的和其他 reviewer 的），逐条判定 `已修正 / 未修正 / 不再适用`，对仍需作者处理的意见发布 finding | | IncrementalReviewStage | 审查上次 reviewed commit 之后的新增代码；改动较多或风险较高时，从 `docs/ai/review/` 加载首次 Review 对应维度的提示词进行完整检查 | | DocumentationRecheckStage (Design/Security/Rustdoc) | 三个子阶段对同一固定增量分别应用对应检查点，不重复报告增量之前的文档欠账 | | DescriptionRecheckStage | 基于自首次审查以来的新增内容，判断现有 PR 描述是否仍然准确，过期时调用 `update_pull` 更新 | re-review 在程序侧固定上次有效的 `Reviewed commit` 与当前 HEAD，不再让模型从全部历史评论中自行选择范围；没有历史记录时使用目标分支与 HEAD 的 `git merge-base` 作为增量基线。评论输入只保留最近 summary 及其后的新回复，避免重复计数或复活已关闭意见；评论、提交摘要、diff stat 和带行号 diff 会在管道启动时预取并由各阶段共享，避免重复请求和重复生成。各复盘阶段还设有独立的工具轮次上限及收敛提示，最终是否 approve 由 pipeline 根据结构化 finding 和关键阶段完整性确定，模型仅负责生成总结文案。 如果当前 HEAD 与最近一次审查提交相同且审查后没有新的人工回复，re-review 会跳过重复分析，但仍发布一条简短执行回执。如果出现新的反驳或补充证据，即使 HEAD 未变化也会运行意见复核与描述复核；不会重复执行新增代码审查，但如果回复或最终代码表明 PR 描述已经滞后，Description Re-check 会直接调用 `update_pull` 修正，而不是只建议作者更新。 ### 工具系统（Tools） - **ReadFileTool**：读取仓库文件内容 - **SearchContentTool**：正则表达式搜索代码内容，支持传入目录或单个文件 - **SearchFilesTool**：按模式搜索文件 - **ListDirTool**：目录结构浏览 - **FetchManPageTool**：获取 Linux/POSIX API 文档 - **SearchCratesTool**：搜索crates.iocrate 依赖信息 ### Git Provider 工具 `git` 工具优先接受结构化参数数组，避免 `--format` 等包含空格的参数被错误拆分；同时兼容旧的命令字符串输入，并拒绝管道、重定向和命令串联。 - GetPullDetail：获取 PR 详情 - GetPullDescription：获取 PR 描述 - GetDiffFiles：获取变更文件列表 - GetAnnotatedDiff：获取带注释的 Diff - ListPrComments：列出 PR 的全部评论（复盘用） - PostComment：发布普通 PR 评论 - UpdatePull：更新 PR 描述 ## 配置说明 ### 环境变量配置 项目通过 `configuration.toml` 文件进行配置，主要配置项包括： ```toml # AI 模型配置 [ai] model = "gpt-4" temperature = 0.7 max_tokens = 4096 # Gitee 配置 [gitee] owner = "" repo = "" pr_number = 0 token = "" # 可选，用于私有仓库 # Trae 配置（如使用） [trae] enabled = false app_id = "" ``` ## 安装和使用 ### 从源码构建 ```bash # 克隆项目 git clone https://gitee.com/luodeb/x-review.git cd x-review # 构建项目 cargo build --release # 运行评审 ./target/release/x-review review --pr https://gitee.com/openkylin/x-kernel/pulls/268 ``` ### 使用方式 ```bash # 首次审查（PR 创建时触发） x-review review --pr # 复盘审查（PR 更新后触发，复盘之前的意见并判断是否可以合并） x-review re-review --pr # 处理一条 PR 评论触发的文档审查（通常由 webhook runner 调用） x-review docreview --pr --command "$COMMENT_BODY" --request-id "$COMMENT_ID" ``` `` 形如 `https://gitee.com///pulls/`。