feat(review): remove legacy mode and harden agent/codex pipeline

Drop legacy runtime paths and role assignments across backend/frontend, and add upgrade-safe DB migration for existing installs. This aligns config, docs, tests, and UI to the agent-first architecture with codex as the only alternate engine.
2026-03-27 10:05:50 +00:00 · 2026-03-19 14:50:21 +08:00
parent 5bb1c3a2d1
commit 1c0c9afd17
35 changed files with 1595 additions and 1102 deletions
--- a/docs/README.zh-CN.md
+++ b/docs/README.zh-CN.md
@@ -10,7 +10,7 @@

 - 🤖 **AI 代码审查** - 使用可插拔的 LLM 提供商自动审查 PR 和提交
 - 📝 **行级评论** - 针对具体代码变更的精确反馈
- 🔄 **双引擎模式** - Legacy（简单）或 Agent（多代理）审查模式
+- 🔄 **任务化审查引擎** - Agent 分级审查（skip/light/full）+ 可选 Codex CLI 审查模式
 - 🔔 **飞书通知** - PR 事件通知集成
 - 🎛️ **管理后台** - 用于管理仓库 Webhook 和 LLM 提供商配置的 Web 界面
 - 🔐 **安全验证** - HMAC-SHA256 签名验证
@@ -34,8 +34,8 @@

 | 引擎 | 描述 | 适用场景 |
 |------|------|----------|
-| `legacy` | 单次 AI 审查，生成总结和行级评论 | 简单、快速的审查 |
-| `agent` | 多代理编排，支持专家、反思和辩论 | 深度、全面的分析 |
+| `agent` | 任务化分级审查（`skip` / `light` / `full`），按路径范围派发 specialist，并按需升级到反思/辩论 | 在控制 token 成本的前提下做深度审查 |
+| `codex` | 通过 Codex CLI 执行审查，独立配置 | 对接外部 Codex 审查流程 |

 ## 快速开始

@@ -136,7 +136,7 @@ LLM 提供商和模型通过**管理后台** Web 界面进行配置：

 1. 导航到 **LLM 配置** 页面
 2. 添加 LLM 提供商（OpenAI 兼容、OpenAI Responses API、Anthropic、Google Gemini）
-3. 为审查角色分配模型（legacy、planner、specialist、judge、embedding）
+3. 为审查角色分配模型（planner、specialist、judge、embedding）

 > API 密钥使用 AES-256-GCM 加密存储在本地 SQLite 数据库中。

@@ -151,13 +151,28 @@ LLM 提供商和模型通过**管理后台** Web 界面进行配置：

 | 配置项 | 描述 | 默认值 |
 |--------|------|--------|
-| 审查引擎 | 引擎模式（`legacy` 或 `agent`） | `legacy` |
+| 审查引擎 | 引擎模式（`agent` 或 `codex`） | `agent` |
+| 启用分流（Enable Triage） | 启用 planner 分流并输出任务化审查计划 | `true` |
+| Small 文件上限 | 判定 `small` 规模审查的文件数上限 | `3` |
+| Small 变更行上限 | 判定 `small` 规模审查的变更行数上限 | `80` |
+| Medium 文件上限 | 判定 `medium` 规模审查的文件数上限 | `10` |
+| Medium 变更行上限 | 判定 `medium` 规模审查的变更行数上限 | `400` |
+| Small Token 预算 | `small` 任务的 token 预算上限 | `12000` |
+| Medium Token 预算 | `medium` 任务的 token 预算上限 | `45000` |
+| Large Token 预算 | `large` 任务的 token 预算上限 | `120000` |
 | 工作目录 | 仓库克隆工作目录 | `/tmp/gitea-assistant` |
 | 最大并发数 | 最大并发审查任务数 | `2` |
 | 最大文件数 | 单次审查最大文件数 | `200` |
 | 自动发布置信度 | 自动发布最小置信度 | `0.8` |
 | 启用人工审批 | 发布前要求人工确认 | `true` |

+当前 Agent 审查执行模型：
+
+- `skip`：文档/资源/纯重命名等低风险改动可直接跳过 specialist。
+- `light`：低风险代码改动执行最小化、按路径范围限定的 specialist 审查。
+- `full`：敏感路径或中大型改动执行完整任务审查，并可按配置升级到 reflection/debate。
+- Triage 输出任务（`paths`、`riskTags`、`mode`、`tokenBudget`），Orchestrator 按任务范围派发，不再默认全量扇出。
+
 #### 记忆与学习（实验性）

 | 配置项 | 描述 | 默认值 |
--- a/docs/design/pluggable-llm-providers.md
+++ b/docs/design/pluggable-llm-providers.md
@@ -132,11 +132,10 @@ CREATE TABLE llm_secrets (
 -- ============================================================
 -- 表3: model_role_assignments — 场景 → 模型映射
 -- ============================================================
-- 每个业务场景（如 planner/specialist/judge/legacy/embedding）绑定到
+-- 每个业务场景（如 planner/specialist/judge/embedding）绑定到
 -- 一个 provider + 具体 model，支持不同场景用不同 provider。
 CREATE TABLE model_role_assignments (
  role          TEXT PRIMARY KEY CHECK (role IN (
-                  'legacy',          -- 旧版单次审查（ai-review.ts）
                  'planner',         -- Agent 审查 planner
                  'specialist',      -- Agent 审查 specialist
                  'judge',           -- Agent 审查 judge
@@ -184,7 +183,7 @@ CREATE INDEX idx_providers_enabled ON llm_providers(is_enabled);
 // ── src/llm/types.ts ────────────────────────────────────────

 /** 模型角色枚举 */
-export type ModelRole = 'legacy' | 'planner' | 'specialist' | 'judge' | 'embedding';
+export type ModelRole = 'planner' | 'specialist' | 'judge' | 'embedding';

 /** 统一消息格式（内部表达，不暴露 provider 差异） */
 export interface LLMMessage {
@@ -346,7 +345,7 @@ export class LLMGateway {

  /**
   * 按业务角色调用 LLM
-   * @param role 业务角色（legacy/planner/specialist/judge/embedding）
+ * @param role 业务角色（planner/specialist/judge/embedding）
   * @param request 请求（不含 model，由角色映射决定）
   */
  async chatForRole(
@@ -686,19 +685,19 @@ Settings 页面
 │   │   ├── ▸ 高级配置 (collapsible, JSON key-value editor)
 │   │   └── [测试连接] [保存] [取消]
 │   │
-│   └── 🧩 角色分配 区域
+│   └── 🧩 角色分配与分级审查映射 区域
 │       ┌──────────────────────────────────────────────────────────────┐
-│       │ 角色         │ Provider 下拉        │ 模型 ID              │
+│       │ 角色/阶段            │ Provider 下拉        │ 模型 ID              │
 │       ├──────────────┼──────────────────────┼──────────────────────┤
-│       │ Legacy 审查  │ [公司 OpenAI 代理 ▾] │ [gpt-4o-mini      ] │
-│       │ Planner      │ [公司 OpenAI 代理 ▾] │ [gpt-4o-mini      ] │
-│       │ Specialist   │ [Anthropic Claude ▾] │ [claude-sonnet-4   ] │
-│       │ Judge        │ [公司 OpenAI 代理 ▾] │ [gpt-4o           ] │
-│       │ Embedding    │ [公司 OpenAI 代理 ▾] │ [text-embedding-3  ] │
+│       │ Planner(Triage)      │ [公司 OpenAI 代理 ▾] │ [gpt-4o-mini      ] │
+│       │ Specialist(任务执行) │ [Anthropic Claude ▾] │ [claude-sonnet-4   ] │
+│       │ Judge(汇总裁决)      │ [公司 OpenAI 代理 ▾] │ [gpt-4o           ] │
+│       │ Embedding(记忆检索)  │ [公司 OpenAI 代理 ▾] │ [text-embedding-3  ] │
 │       └──────────────────────────────────────────────────────────────┘
 │       [保存角色分配]
 │
 ├── ⚙️ 通用设置（现有 Gitea / 飞书 / App / Review 参数）
+│   ├── Agent 分级审查参数：small/medium 阈值、token budget、triage 开关
 │   └── (复用现有 ConfigManager 组件，数据源统一为 DB)
 ```

@@ -734,9 +733,9 @@ const MODEL_SUGGESTIONS: Record<string, string[]> = {
 | # | 文件 | 当前代码 | 改造为 | 影响范围 |
 |---|---|---|---|---|
 | 1 | `src/index.ts:69-71` | `const openaiClient = new OpenAI({baseURL, apiKey})` | 删除；初始化 `LLMGateway` 单例并传入业务层 | 入口 |
-| 2 | `src/services/ai-review.ts:8-10` | `const openai = new OpenAI({...})` | 删除模块级 client；函数接收 `LLMGateway` 参数；`openai.chat.completions.create()` → `gateway.chatForRole('legacy', ...)` | Legacy 审查 |
-| 3 | `src/review/orchestrator.ts:45,61-63` | `private readonly openai: OpenAI` + `this.openai = new OpenAI(...)` | 构造函数改接收 `LLMGateway`；传给各 agent | Agent 编排 |
-| 4 | `src/review/agents/specialist-agent.ts:93` | `protected readonly openai: OpenAI` | → `protected readonly gateway: LLMGateway`；`reviewLegacy()` 和 `reviewWithReAct()` 中的 `this.openai.chat.completions.create()` 改为 `this.gateway.chatForRole('specialist', ...)` | 核心 agent |
+| 2 | `src/controllers/review.ts` | 旧版 webhook 存在回退分支 | 删除回退分支，仅保留 `agent` / `codex` 入队逻辑 | 审查主入口 |
+| 3 | `src/review/orchestrator.ts:45,61-63` | `private readonly openai: OpenAI` + `this.openai = new OpenAI(...)` | 构造函数改接收 `LLMGateway`；传给各 agent（任务化分级编排：skip/light/full） | Agent 编排 |
+| 4 | `src/review/agents/specialist-agent.ts:93` | `protected readonly openai: OpenAI` | → `protected readonly gateway: LLMGateway`；`reviewWithOptions()` 与 ReAct 调用改为 `this.gateway.chatForRole('specialist', ...)` | 核心 agent |
 | 5 | `src/review/agents/critic-agent.ts:23` | `private openai: OpenAI` | 同上 | 评审 agent |
 | 6 | `src/review/agents/reflexion-agent.ts:24` | `constructor(openai: OpenAI, ...)` | 构造传 gateway | 反思 agent |
 | 7 | `src/review/agents/debate-orchestrator.ts:17` | `private openai: OpenAI` | 同上 | 辩论 agent |