LiteReview：自托管 PR 审查智能体配置平台

用于配置 PR 审查代理的自托管平台。托管一个共享工作区，配置每个代理的模型、指令、技能和工具，然后从 GitHub PR 评论中调用审查者：

@litereview

LiteReview 用 👀 确认已接受的命令，并为每个代理实例创建一个单独的进度评论。每个实例都在自己的 Modal 沙箱中运行。当每个代理完成时，其评论会显示 ✅ 和完整回复，发现的问题会链接到内联线程，你可以在那里回复。没有可用 diff 行的发现会保留在代理评论中。每个代理完成时，其 👀 反应会被移除；当所有代理都完成时，请求的 👀 会被移除。✅ 表示代理已完成，而不是表示审查没有问题：未完成的工作和跳过的检查仍会保留标记。审查者按命令中指定的顺序排列，组成员和实例按其保存的顺序排列。在 Runs 中，代理报告、发现、检查、截图和活动默认折叠。LiteReview 从不推送修复。

开始使用

• 部署团队工作区：Render、Postgres、Google Workspace 登录，以及你的 GitHub App。
• 本地开发：使用 SQLite 和本地访问密钥运行 UI 和 API。
• 贡献 · 安全 · MIT 许可证 · 第三方声明

审查需要 Modal 账户、模型提供商或网关，以及可公开访问的 HTTPS API URL。GitHub PR 集成需要你创建并安装一个 GitHub App。Modal 和模型使用会产生费用；没有本地沙箱后端。Render 是文档中记录的部署路径；Lens 和 BerriAI 托管服务是可选的。

此测试版每个部署运行一个受信任的工作区。每个被接纳的成员都可以管理工作区并使用其共享连接。运行时间、模型调用和并发限制是可选的；请为你的部署配置它们以及你的提供商的预算。在连接私有仓库或特权工具之前，请参阅安全边界。

跟踪审查支出

管理员可以打开 Spend 查看历史模型成本、PR 运行次数和平均每次运行成本。使用 By user 或 By repository 查看相同的细分。管理员还可以在 Runs 中看到每次审查的模型成本，包括每个融合分支和最终审查环节。其他成员看不到成本；API 强制执行相同的限制。使用 ADMIN_EMAILS 配置支出管理员。

成本在可用时使用网关报告的数量。否则，LiteReview 会根据 token 使用量、缓存 token 和可用的模型费率进行估算；这些金额会标记为 est.。未知成本显示为 Unavailable，+ 表示部分总计。较早的运行没有记录成本。平均成本仅包括具有完整成本数据的已完成运行。代理检查、Modal 费用和托管费用不包括在内。这些总计是使用情况跟踪，不是发票或支出限额。

配置审查者

要从描述创建审查者，请打开 PR agents → Create agent → Create from prompt。描述其关注点并选择 Generate draft。查看生成的名称、指令和能力，选择审查模型，然后 Save agent 和 Test agent。在你执行这些操作之前，不会在 PR 上保存或运行任何内容。如果生成失败，草稿会保留你的提示。

草稿生成默认通过已保存的网关或 Anthropic 连接使用 Haiku 5.5。在 Settings → Agent creation 下更改其连接和模型。这与 agent 的审查模型是分开的。生成使用一次模型请求和提供商额度；其成本与 Spend 上的 PR 审查总计分开计算。

仅评论 @litereview 即可运行工作区的默认审查器。第一个审查器会自动成为默认。在 PR agents 下，随时在某个 agent 的行上选择 Set default；该选择适用于未来的运行。只有一个审查器的现有工作区可以立即使用裸命令。有多个审查器的工作区需选择一次默认。要选择特定的 agent 或组，请在评论中命名它们，例如 @litereview frontend security。调用者和仓库权限对两种形式均适用。

agent 的 Review instructions 定义其任务、范围、工作流、语言和语气。附加技能为这些指令提供支持；当两者冲突时，以 agent 指令为准。Codex 提供 agent 运行时、工具和结果交付。agent 可以生成叙述性回复而不包含 bug 发现。凭据、启用的工具和配置的时间限制仍然适用。

agent 会使用项目的清单文件和文档化命令尝试相关的依赖设置，然后再报告环境阻塞。构建工具、Python、Node 和 uv 均可用；项目特定的包和工具链可以在一次性沙箱中安装。未运行的可选测试会出现在 Checks 下，但不会使审查不完整。无法运行的必需检查，或配置任务要求的其他未完成工作，会被报告为不完整。已执行但失败的测试是证据，不会自动使审查不完整。

在创建审查器时，或在 PR agents → reviewer → Review instructions 下设置 Minimum review time (minutes)。例如，为 frontend 保存 5，为 security 保存 10，然后评论：

@litereview frontend security

每个实例都使用其审查器保存的最小值，包括通过组调用时。计时在仓库/工具设置完成后开始。0 表示无最小值，并保留现有审查器的正常行为。使用整数分钟；LiteReview 不施加工作区上限。更改设置会影响未来的审查；已接受的任务保留其保存的时长。评论中的时间选项会被拒绝，并提示使用 UI 设置。此最小值不运行私有 harness 检查。

该测试框架会检查单调时钟，要求智能体持续调查和验证，并拒绝提前完成。API 独立检查已用时间。如果 Codex 在未提交的情况下于最短时间之前返回，它会继续同一线程。这不会调用交互式 /goal 斜杠命令。默认情况下，运行没有 LiteReview 时间或模型调用限制。要设置限制，请在智能体编辑器中展开 Optional limits，然后输入 Maximum run time (minutes)、Maximum model calls，或两者都填。将字段留空可移除其限制。最长运行时间包含设置时间，且必须超过最短时间；最短时间永远不会产生最长时间。组使用每个智能体保存的限制，已接受的作业保留其快照。提供方故障和达到限制会产生不完整的审查，绝不会成功提前完成。Modal 强制实施 24 小时沙箱生命周期；当未选择最大值时，LiteReview 会使用该完整生命周期。运行尚不能跨沙箱替换恢复。现有的 MCP 选择、技能、可视化工具、模型和指令都会保留。

部署到 Render

按照部署指南获取凭据、进行部署并验证登录。完成首次审查的完整路径是：

1. 复刻此仓库，然后在 Render 中基于你的复刻创建一个 Blueprint。render.yaml 会预置一个付费 Docker Web 服务和 Postgres。组织所有者可能需要批准 Render 访问你的仓库。
2. 将 MODAL_TOKEN_ID / MODAL_TOKEN_SECRET、你的 Google OAuth 客户端和 GOOGLE_ALLOWED_DOMAINS 设置为你控制的域名。该 Blueprint 要求使用 Google SSO。应用使用 Render 分配的 HTTPS URL；为自定义域名设置 PUBLIC_URL。保持生成的 SECRET_KEY 稳定。将 GITHUB_ORGANIZATION 设置为你的 GitHub 组织，或留空以便在设置期间选择账户。
3. 使用 Google 登录。关联 GitHub 以请求审查，或选择 Workspace 先配置智能体和连接。每位成员都可以管理工作区；支出仅对已配置的管理员可见。
4. 打开 Repositories → Connect GitHub（配置后，该按钮会显示你的组织名称）。使用由拥有你仓库的账户所拥有的 App。在同一标签页中继续前往 GitHub；引导流程会注册该 App、加密存储其凭据，并打开安装页面。组织所有者或组织范围的 App Manager 可以创建该 App；安装可能需要所有者批准。私人的个人 App 无法安装到组织中。
5. 在 GitHub 上选择仓库，然后返回 Repositories。LiteReview 会自动导入所选内容；无需安装 ID 和第二个仓库选择器。支持公共和私有仓库。新的选择允许现有已批准的人员调用其获准的审查者。打开仓库的 Review permissions 可缩小该访问范围。
6. 如果不存在模型连接，请在 Models 下添加一个。尽可能复用现有的兼容 Responses 的网关或 OpenAI 连接。Configure reviewer 会要求提供其名称和模型，然后 Save and check reviewer 会使用 Modal 和模型额度运行一次私有测试框架检查。每个审查者都使用 Codex；Anthropic 模型需要兼容 Responses 的网关。完整说明、能力、技能和 MCP 工具仍保留在智能体编辑器中。
7. 每位队友选择 Sign in with Google → Connect GitHub。他们会自动出现在 People 中，并默认可以使用所有审查者。使用 Edit access 进行可选限制；无需重复的允许列表。在验证当前 GitHub 访问权限后，起始页面仅显示允许的仓库和已勾选的审查者对应的命令。在 PR 中发布该命令；成功设置后会以实际的审查结果结束。提供方同意可能需要额外点击。

恢复 GitHub 设置

Repositories 会检查该 App，并在打开时或从 GitHub 返回时同步仓库选择。已签名的安装 webhook 也会同步选择。使用 GitHub connection options → Sync repositories 重试。检查失败会保留配置。如果 GitHub 审批待处理，请复制设置请求给组织所有者，并在之后恢复。

关联的 GitHub 账户让 LiteReview 能够识别你的 PR 评论。它不会建立仓库访问权限。Account 和 Repositories 分别显示身份和仓库访问权限。当没有连接任何仓库时，工作区页面会显示 Connect GitHub，起始页面会直接链接到设置。

已保存的 App 同样不会建立仓库访问权限。如果它属于错误的账户，Repositories 会识别出该所有者，并提供相应的组织设置。Copy setup request 包含供组织所有者在支持的 GitHub 计划上分配组织级 App Manager 角色，或自行创建 App 的说明。App 管理和安装是分开的权限。目标组织来自已保存的设置或 GITHUB_ORGANIZATION；绝不会从 Google 邮箱域名推断。

要自行安装 LiteReview，你需要对目标仓库拥有 Admin 访问权限，并且组织的 Settings → Member privileges → GitHub Apps → Allow repository admins to install GitHub Apps for their repositories 设置已启用。此策略适用于所有仓库管理员。所有者也可以保持安装受限，并为你选择仓库。安装后，使用 Add repositories 更新现有 App 的访问权限；无需新建 App。LiteReview 的 People 和仓库授权仍会限制谁可以请求审查。

Settings → GitHub App 包含凭据恢复和 Reset setup。重置会暂停 GitHub 审查，同时保留代理、模型、MCP 连接、技能、仓库环境和密钥、访问规则以及审查历史。该 App 仍保留在 GitHub 上。Undo reset 会恢复先前的连接；保存新 App 会替换该备份。重置前必须完成正在进行的审查。

同步会保留现有环境和权限。在 LiteReview 中移除仓库会将其排除在未来的自动导入之外；可在 Previously removed repositories 下显式恢复。移除或限制访问授权绝不会被同步撤销。移除 GitHub 访问权限后，已保存的环境会显示为不可用。替换 App 后，同步会更新已验证的安装 ID，而不会更改授权。

每个浏览器独立保持登录状态。在另一个浏览器中登录或退出不会关闭你的会话。当会话过期时，Sign in to continue 会把你带回你打开的页面，包括特定的运行。GitHub 身份保持关联。GitHub 检查失败时会提供重试，而不是要求你重新进行设置。

Google Workspace SSO

为你的 Google Workspace 组织使用内部 Google OAuth Web 客户端。注册 https://YOUR-LITEREVIEW-HOST/api/auth/google/callback 为授权重定向 URI，将源替换为你部署的实际 PUBLIC_URL。如果复用客户端，请保留其其他重定向 URI。参见凭据设置步骤。

在 Render 的 LiteReview 环境设置中，将 GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_ALLOWED_DOMAINS 设为你的域名（例如 example.com），以及 GOOGLE_SSO_REQUIRED=true，然后部署。在现有工作区上启用 SSO 之前先注册回调：redirect_uri_mismatch 表示该 URI 在该 Google 客户端中缺失。切勿提交客户端密钥。

验证工作区账户可以登录、外部账户被拒绝，且旧的工作区访问密钥不再有效。启用 SSO 还会使现有的访问密钥/仅 GitHub 会话失效。每个被允许的 Google 成员都可以管理代理、组、技能、共享模型/MCP 连接、仓库、审查访问设置和运行历史。只有 ADMIN_EMAILS 中列出的已验证 Google 邮箱可以查看支出；此管理员区分不会改变其他管理权限。共享连接使用其已连接账户的权限和共享模型额度。GOOGLE_ADMIN_EMAILS 不再使用；ADMIN_USERS 仅在 SSO 禁用时控制旧版仅 GitHub 登录。GitHub 仍控制 App 安装权限。已批准的 Google 用户会自动出现在People中。已关联的用户可以调用所有审查者，除非有明确的个人限制或仓库权限不允许。现有受限保持不变。

服务器验证 Google 令牌签名、签发者、受众、有效期、nonce、已验证邮箱和托管域声明。PKCE 和一次性、绑定浏览器的 state 保护登录。关联通过 OAuth 验证 GitHub 的稳定用户 ID；手动输入的 GitHub 用户名无法建立成员身份。一旦关联，该 GitHub 账户无需再次登录即可请求审查。浏览器会话在 SSO_SESSION_SECONDS 后过期（默认 12 小时）；过期和退出不会撤销 GitHub 关联。每个请求仍会根据配置的 Google 客户端和允许的域、GitHub 仓库权限以及任何明确的个人限制检查关联身份。要阻止某人请求审查，请使用People → Edit access并保持选择为空。取消关联 GitHub 也会阻止来自该账户的请求。没有 Google Directory 同步：暂停 Google 账户会阻止未来的 Google 登录，但不会自动撤销其现有的 GitHub 审查访问权限。已签名的 GitHub webhook 和按作业过期的 worker 令牌仍是机器入口点。

本地开发仅在未配置 Google 客户端且 GOOGLE_SSO_REQUIRED=false 时可以使用 ADMIN_TOKEN。必需但不完整的 SSO 配置会拒绝访问，而不是回退到工作区密钥。

Modal 镜像和沙箱使用你的凭据按需创建。首次审查会构建镜像，可能需要几分钟；后续审查会复用它。无需单独的 Modal 应用部署、工作流服务、Redis 或存储桶。

Codex 运行时

每个审查器都在自己的 Modal 沙箱中运行 Codex 0.158.0。选择模型、指令、技能和工具；LiteReview 会自动安装并配置 Codex。

使用 OpenAI 连接或支持 Responses API 的网关。网关可以将兼容请求路由到其他提供商，包括 Anthropic。直接连接 Anthropic 无法运行审查器。浏览器和桌面检查需要支持图像的模型。在 PR agents 下，选择你的审查器，然后选择 Test agent，以在示例项目上检查 Codex、模型、示例技能加载以及启用的终端/浏览器/桌面工具。此私有检查会消耗 Modal 和模型额度；它不会访问 GitHub 仓库、发表评论、执行你的审查指令或调用附加的 MCP 工具。

每个审查器都包含终端访问权限，可在其一次性检出中检查文件、安装依赖、运行测试并创建复现器。指令和技能可以请求 Codex 子代理；主审查器会将它们的证据合并为一个结果。浏览器、计算机使用、附加技能和选定的 MCP 工具仍可配置。检出内容包含所提供的 PR 提交的源代码归档，不含 Git 历史。LiteReview 从不推送更改。

在 PR agents → reviewer → Model 下，展开 Reasoning effort 以使用模型默认值，或请求 Low、Medium、High 或 Extra high。支持的级别取决于你的模型和网关。更高的 effort 可能会增加审查时间和成本。更改后运行 Test agent；该检查会使用所选的 effort。现有审查器会保持其模型默认值，直到你选择某个级别。

使用 Fusion 合并独立审查

打开 PR agents → reviewer → Model 并选择 Add model。选择另一个模型以自动启用 fusion，最多支持 16 个模型。每个模型都使用相同的审查指令、技能和启用的工具。Add model 旁边的问号解释了它们如何协同工作。移除额外模型即可恢复为单个审查器。

在所选模型下方选择 Final review model，然后保存并运行 Test agent。该测试会在一个私有示例项目上演练每个阶段。对于 PR 审查，各分支在单独的检出中运行；聚合器会获得一个全新的检出及其报告，验证各项声明，并发布一份最终审查。在 Runs 中，展开 Fusion 以检查每个分支的结果和活动。分支结果默认折叠。如果某个分支失败，其不完整的覆盖范围仍会保留在最终结果中。如果所有分支都失败，则不会运行聚合。

一次 fusion 审查的成本是每个分支与聚合器的总和。最大运行时间和模型调用限制分别适用于每个阶段；最短审查时间适用于每个分支。当容量已满时，工作区并发设置可以将分支排队。在此审查器所在行选择 Set default，即可通过 @litereview 调用整个 fusion。

要进行独立的 bug 审查，请将示例审查指令复制到审查器的指令中。该示例会追踪调用方和使用方，检查边界情况和重复操作，并验证测试是否覆盖了其预期行为。在将其与另一个审查器进行对比评估时，请勿选择外部审查服务 MCP 工具。在将其设为必需检查之前，请先在你自己的 PR 上衡量质量和成本。

完整的 PR 上下文存储在沙箱文件中，diff 仍可通过审查工具获取。大型 diff 不会作为命令行参数或过大的初始提示传递。后续轮次和定时续期保持相同的 Codex 会话和缓存键。缓存命中和节省取决于所选的网关和提供商；独立审查者拥有单独的会话。

运行时版本固定在 runner/catalog.py 中，并随每个作业记录。有关证据，请参阅 运行时验证；有关 Codex 的 Apache-2.0 许可证，请参阅 第三方声明。

现有审查者

启动时，LiteReview 会将已保存的审查者迁移到 Codex，同时保留模型、指令、技能、工具和限制。如果审查者使用直接的 Anthropic 连接，请在 Models 中添加一个兼容 Responses 的网关，在 PR agents → reviewer → Model 中选择它，然后运行 Test agent。如果您的网关公开了该模型 ID，请保留它；否则使用其等效的模型 ID。在请求下一次 PR 审查之前，请先运行一次私有检查。

正在运行的沙箱和审查历史保留其原始配置。使用已停用 harness 的排队作业会以启动新审查的指令结束；LiteReview 不会重新解释已接受作业的设置。

能力

• Repository：始终可用。读取/搜索不可变的检出内容和 PR diff。
• Terminal：始终可用。在一次性检出中运行测试和命令。
• Browser：Playwright 操作、无障碍结构，以及发送给模型的真实截图。
• Computer use：私有 1280×900 Linux 桌面的截图，鼠标和键盘输入。当两者都启用时，它与 Browser 共享 Chromium。每个操作都会返回视觉反馈。
• MCP：可复用的远程 Streamable HTTP 连接，支持按代理选择工具。
• Skills：包含 SKILL.md 和支持文件的 Markdown 或 ZIP。可将同一技能附加到多个代理。技能不会授予工具。

代理和组命令名称共享一个不区分大小写的唯一命名空间。People 和每个仓库的 Review permissions 集中控制调用。启用 SSO 后，成员资格来自已批准的 Google 登录和已验证的 GitHub 链接。People 默认包含所有当前/未来的代理和组。Edit access 可以将某人限制为特定选择；空选择会阻止审查。Reset access 恢复默认设置。仓库权限和任何人员限制必须允许命令中的每个名称，并且调用者还必须拥有 GitHub 仓库访问权限。未启用 SSO 时，People 仍为手动允许列表。组授权允许通过该组运行其成员。已连接的仓库以 All access 开始。限制会跟随 Google 身份，跨越 GitHub 重命名和重新链接，并在重启后持续存在。关联用户的浏览器会话过期后，他们仍保持与 People 的连接。People 会显示何时仍需要 Google 登录或 GitHub 链接；已保存的授权本身永远不会建立成员资格。组是对共享代理的可选引用。实例计数属于组成员资格。两次选择同一名称会去重；选择两个共享同一代理的组会分别运行每个成员资格。直接调用代理和通过组调用代理会分别运行两种选择。已接受的运行会快照其配置和提交 SHA。

自动运行审查

打开 Repositories → repository options → Automatic reviews，然后：

1. 选择 Add rule 并选择一个 agent 或 group。
2. 将 PR authors 留空表示所有人，或输入一个或多个用逗号分隔的 GitHub 用户名。这匹配的是 PR 作者，包括 dependabot[bot] 等机器人账号，而不是推送提交的人。该列表会随规则一起保存。
3. 选择 Run when：PR opened、Ready for review、New commits pushed、PR reopened 或 Label added。若使用标签触发，请输入所需的 Trigger label。
4. 保存该仓库。已启用的规则会启动付费审查并在 GitHub 上发布结果。它们适用于外部贡献者和机器人，无需作者登录 LiteReview；仓库的 Review permissions 仍会限制哪些审查者可以运行。

此版本创建的 App 会订阅 Pull request 事件。对于已有的 App，打开其 GitHub Permissions & events，启用 Pull request，然后保存。保持 Issue comment 启用以便支持提及。返回 Repositories 刷新连接检查。

在一个打开的、非草稿的 PR 上触发匹配事件。Runs 中生成的条目会显示自动触发和已审查的提交。费用归属于 PR 作者。如果没有任何启动，请检查 App 事件订阅、已启用的规则、作者/标签过滤条件以及仓库权限。保存规则不会追溯审查已有的 PR。

草稿、已关闭的 PR 和过期的 webhook 投递会被跳过。重叠的规则会让每个 agent 实例在每个 PR 提交上最多运行一次；group 保留其请求的实例数量。失败的尝试不会在同一提交上自动重试。使用显式的 @litereview agent-name 评论来请求另一次审查。禁用规则会停止未来的触发；已接受的运行会保留其配置并继续。

PR agents 按使用次数从多到少列出。Times used 统计 PR 运行次数，包括 group 使用和未完成的运行，每个 agent 每次运行计一次。私有模型检查和融合分支不会增加计数。次数相同时按名称排序。

连接 MCP 工具

在左侧边栏打开 MCP servers，然后选择 Add MCP server。输入名称和 Streamable HTTP 端点 URL，保留 OAuth，然后选择 Save & connect。通过提供商批准访问。随后 LiteReview 会运行一次真实的连接测试并显示发现的工具。打开一个 PR agent 并选择它可以使用的工具。该账户选定的工具会与使用该连接的 agent 共享。

对于基于令牌或公开的服务器，选择 Bearer token 或 No authentication，然后选择 Save & test。Test connection 会重复发现过程，并在出现任何失败时显示重试路径。仅保存服务器或批准 OAuth 并不算作成功的连接测试。

OAuth 支持发现、PKCE、在提供时自动客户端注册以及刷新令牌。如果提供商要求预先注册的应用，请打开 Advanced OAuth settings，将显示的 redirect URI 复制到该应用中，并输入其 client ID 和可选的 secret。授权令牌和刷新令牌在静态存储时加密，并保留在 review 服务中。Disconnect 会移除 LiteReview 的本地授权；如有需要，请在提供商的账户设置中撤销上游授权。Reconnect 会续订它。取消登录会保留服务器以及任何之前可用的授权。

在编辑 agents 时，MCP servers、Skills 和 Models 在侧边栏中一键即可访问。agent 草稿在同一浏览器标签页中经过资源导航、OAuth 重定向和重新加载后仍会保留。选择 Resume editing 以带着新可用的工具或技能返回，或丢弃草稿。连接凭据绝不会保存在浏览器草稿存储中。

本地开发

安装 Python 3.12、Node 22 和 uv 0.10.9。克隆仓库并安装依赖：

git clone https://github.com/BerriAI/litereview.git
cd litereview
uv sync --frozen --python 3.12
npm ci --prefix frontend
npm run build --prefix frontend

在新的检出中，使用独立的随机密钥创建本地配置。此命令拒绝覆盖现有的 .env：

uv run python - <<'PY'
from pathlib import Path
import secrets

text = Path('.env.example').read_text()
for name in ('SECRET_KEY', 'ADMIN_TOKEN'):
    text = text.replace(f'{name}=\n', f'{name}={secrets.token_urlsafe(32)}\n')
with Path('.env').open('x') as output:
    output.write(text)
Path('.env').chmod(0o600)
PY
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --no-access-log

打开 http://localhost:8000，并在 Workspace access key 中使用从 .env 生成的 ADMIN_TOKEN 登录。在另一个终端中，curl --fail http://localhost:8000/health 应返回 {"status":"ok"}。这会启动工作区；实时 review 仍需要上面列出的外部账户。

本地开发支持 SQLite。部署时使用 Postgres。创建 .env 后，docker compose up --build 会在本地运行两个服务。在 v1 中使用一个 API worker 和一个服务实例。

Modal 必须通过 HTTPS 访问 API。对于本地实时测试，请通过临时 HTTPS 隧道暴露端口 8000，并在启动应用前将 PUBLIC_URL 设置为其地址。所有配置、结果和截图都需要登录；job relay 端点需要按 job 过期的令牌。PUBLIC_URL 还必须与你在浏览器中使用的 origin 匹配。

对于 UI 迭代，npm run dev --prefix frontend 会将 API 调用代理到端口 8000。在进行仅本地 UI 工作时设置 PUBLIC_URL=http://localhost:5173。

运行检查：

uv run ruff check app runner tests
uv run pytest -q
npm run build --prefix frontend

uv run python -m scripts.modal_smoke 在真实的 Modal 沙箱中演练浏览器和桌面工具，并消耗 Modal 额度。实时 review 测试还会消耗模型额度。

对于完整的 LiteReview 应用检查，请在你的 LiteReview fork 中针对某个 PR 运行 uv run python -m scripts.modal_app_smoke --repo YOUR-OWNER/YOUR-LITEREVIEW-FORK --pr YOUR-PR-NUMBER。将两个占位符替换为你控制的仓库和受信任的 PR。这会下载其固定版本的源代码，验证每个提取的文件，安装依赖，构建并启动应用，演练浏览器/桌面工具和互联网访问，并要求配置的 gateway 模型读取截图。它需要已认证的 gh 以及本地 Modal/gateway 凭据；证据保留在被忽略的 .test-artifacts/ 文件中。它会执行所选 PR 的代码并消耗 Modal/模型额度。

现有 GitHub App

配置 Repositories → Use existing App（如果已保存 App，则为 Settings → GitHub App → App credentials），或设置：

• GITHUB_APP_ID、GITHUB_PRIVATE_KEY（PEM，支持转义换行符）和 GITHUB_WEBHOOK_SECRET。
• GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET 用于 GitHub 登录。
• Callback URL：PUBLIC_URL/api/auth/github/callback。
• Webhook URL：PUBLIC_URL/api/webhook/github；订阅 Issue comment 和 Pull request 事件。
• 仓库权限：Contents read、Metadata read、Pull requests write、Issues write。Issues write 允许顶级 PR 对话评论。

启用 Google SSO 后，GitHub OAuth 会在 Google 登录后关联调用者的账户，无法单独登录。在本地访问密钥模式下，只有 ADMIN_USERS 可以使用 GitHub 登录，ADMIN_TOKEN 仍然可用。

运行时与边界

使用 Lens 进行可选追踪

LiteReview 可以将审查追踪发送到 Lens 或 OTLP/HTTP 收集器。 追踪默认关闭。你可以在没有 Lens 或任何 Berri 托管服务的情况下运行 LiteReview。

1. 部署 Lens 并登录。打开 Tracing key 并为 LiteReview 生成一个密钥。

2. 在 LiteReview API 环境中设置这些变量，然后重启或重新部署它：

   LITEREVIEW_TRACE_ENDPOINT=https://YOUR-LENS-HOST/v1/traces
   LITEREVIEW_TRACE_API_KEY=YOUR-LENS-TRACING-KEY
   LITEREVIEW_TRACE_CONTENT=false

   使用完整的 OTLP/HTTP 端点，包括 /v1/traces。API 服务器必须能够访问它。 使用追踪密钥，而不是 Lens 管理员令牌。对于无需身份验证的收集器，将密钥留空。

3. 运行一次审查，或在代理编辑器中使用 Test agent。在 Lens 中，打开该审查者的 Traces。 每个代理的审查显示为一次运行。打开它并选择 Thread 以阅读其消息、 工具调用、工具结果，以及在启用内容捕获时的最终审查。Steps 显示 该审查下的各个模型调用。同一组中的代理有各自独立的运行。

追踪包含审查者、harness、模型、作业和运行 ID、持续时间、状态，以及提供商提供时的 token 计数。要捕获对话，请设置 LITEREVIEW_TRACE_CONTENT=true。 这会导出完整的提示词、响应、工具参数、发送回模型的工具结果，以及 提交的审查。它可能包含私有源代码和命令输出。图像、加密推理、 请求头和存储的凭据不会被捕获。对话文本或工具参数和结果中的机密信息不会被脱敏。

Codex 模型请求通过 API 导出。收集器密钥永远不会进入 Modal 沙箱。 导出在后台运行，没有队列大小上限。失败的导出会被记录；审查继续进行。 API 重启可能会丢失待处理的导出；后续调用仍会加入同一审查。父 span 和 最终审查在运行完成时出现。未完成的必需检查会将审查标记为不完整。 之前记录的追踪保留其原始结构；旧导出中省略的内容无法恢复。

如果追踪未出现，请检查端点和追踪密钥，然后检查 API 日志中的导出错误。 在端点中保留 /v1/traces。要关闭追踪，请清除 LITEREVIEW_TRACE_ENDPOINT 并重新部署。

审查执行

FastAPI 服务提供构建后的 React UI，并运行由 Postgres 支持的持久调度器。每个作业在单独的 Modal 沙箱中运行 Codex，沙箱包含 Python 3.12、Node 22、Chromium、Playwright 和 Linux 桌面。LLM 推理在配置的提供商处进行。

检出内容是 PR 不可变头部 SHA 处的 GitHub 源代码归档，而不是完整的 Git 克隆。它不包含 .git 历史记录，不会实体化子模块或 Git LFS 对象，也不会保留符号链接。依赖这些功能的仓库需要额外支持。可执行审查使用仓库配置的设置命令、启动命令和就绪 URL；外部服务、私有包注册表和测试账户仍需要各自配置。Modal 沙箱默认具有出站互联网访问权限，包括包安装和浏览器导航。这不会授予对私有网络或凭据的访问权限。

长期有效的模型和 MCP 密钥在数据库中使用 SECRET_KEY 加密。它们保留在 API 服务中。沙箱使用作业范围的令牌来调用配置的模型/MCP 中继。令牌仅在作业活跃期间有效；显式选择的超时也会在短暂的结果报告宽限期后使访问过期。GitHub 凭据从不进入检出。可选的仓库测试密钥被有意提供给沙箱；请仅使用测试凭据。

仓库下载和解压没有 LiteReview 大小或文件数量限制。下载通过 API 流式传输到沙箱中的临时文件，解压以块为单位复制文件内容。可用的沙箱磁盘空间和上游服务限制仍然适用。LiteReview 也接受没有变更文件或 diff 大小上限的 PR；完整 diff 会被存储并可供审查工具使用，可选范围由 agent 选择。

截图和活动日志是私有的 Postgres 记录，没有 LiteReview 大小或数量上限。技能上传、指令、工具结果、审查发现和摘要也会被保留，没有应用大小上限或截断。

文件、搜索、shell、浏览器和 MCP 工具返回完整结果，除非 agent 请求范围。模型、MCP、下载、设置和工具请求没有 LiteReview 截止时间，除非为运行或命令显式选择了一个。Codex、模型和上游服务仍然执行它们自己的上下文容量限制。

默认情况下，沙箱按需跨审查启动。将 CONCURRENCY 设置为正数可启用可选的工作区范围上限；0 将并发留给 Modal 账户配额和提供商速率限制。每个沙箱请求 2 个 CPU 核心和 4 GiB 内存。时间和模型调用预算是每个 agent 的可选设置。旧版 JOB_TIMEOUT、MAX_ROUNDS 和 MAX_REVIEW_MINUTES 环境值不再施加默认值。现有审查者默认没有最小值。保持 Postgres 备份启用；删除数据库会丢失设置和运行历史。

GitHub 重试按投递 ID 去重。待处理作业在 API 重启后仍然存在；已完成的作业永远不会自动重新运行。沙箱在完成时终止。调度器在 API 重启后重新连接到记录的活动沙箱，如果沙箱在没有结果的情况下退出，则报告不完整结果。Modal 的 24 小时生命周期仍然适用。发布重试在响应丢失后恢复每个 agent 标记的评论和发现线程。共享锁在部署重叠期间只允许每次运行一个发布者。现有的聚合进度评论在其运行完成时链接到 agent 结果；已发布的运行保持不变。结果始终指明被审查的 SHA；后续推送会被指出。

超过 GitHub 65,536 字符评论限制的审查会跨多条评论发布，而不会截断审查。重试会恢复每个已发布的部分。在存在可用 diff 行的情况下，每个 agent 评论都会链接到其内联发现线程。它没有自动修复、推送触发器、融合/评判 agent、持久聊天、本地 stdio MCP 服务器或插件市场。请参阅 SPEC.md 了解产品决策，参阅 docs/VALIDATION.md 了解实际测试证据和外部设置边界。