feat: 整合功能恢复与技能学习闭环(含 ECC v2.1 parity + Opus 4.7 接入 + prompt 工程优化)

主要变更: - Skill Learning 闭环系统 (9/9 AC) - Opus 4.7 模型层接入 + adaptive thinking - Prompt 工程优化 (64 审计测试) - Agent Teams 简化门控 (默认启用) - Windows Terminal 后端修复 (EncodedCommand/WT_SESSION) - TF-IDF 技能搜索精准化 (字段加权/CJK 优化) - Autonomy 系统 (/autonomy 命令) - ACP 协议完整实现 - mock.module 泄漏修复 (CI 全绿) - 152+ lint/type 修复
2026-06-22 00:05:51 +00:00 · 2026-04-22 16:07:42 +08:00
parent 711927f01b
commit 95fece4b51
316 changed files with 39611 additions and 14298 deletions
--- a/docs/features/ultrareview-system-analysis.md
+++ b/docs/features/ultrareview-system-analysis.md
@@ -0,0 +1,703 @@
+# Ultra Review 系统完整分析
+
+## 1. 概述
+
+Ultra Review（内部代号 `tengu_review`）是 Claude Code 的**云端代码审查**功能。用户通过 `/ultrareview` 斜杠命令发起，系统将当前仓库（PR 或 branch diff）传送到 CCR（Claude Code on the web）远程环境，在云端运行 "bughunter" 编排器（一个多 agent 舰队）来查找、验证和去重 bug，最终将审查结果通过 task-notification 管道注入回本地会话。
+
+整个过程约 10–20 分钟，完全在云端异步执行，本地 CLI 通过轮询获取进度和结果。
+
+---
+
+## 2. 文件清单
+
+### 2.1 核心文件（8 个）
+
+| 文件路径 | 行数 | 职责 |
+|----------|------|------|
+| `src/commands/review.ts` | 57 | 入口文件，注册 `/review`（本地）和 `/ultrareview`（云端）两个 Command |
+| `src/commands/review/ultrareviewEnabled.ts` | 14 | GrowthBook 运行时门控函数 |
+| `src/commands/review/ultrareviewCommand.tsx` | 74 | `/ultrareview` 命令的 `call` 处理器，管理计费门控和对话框流程 |
+| `src/commands/review/reviewRemote.ts` | 320 | 核心引擎：计费检查 + PR/Branch 两种模式的远程会话创建 |
+| `src/commands/review/UltrareviewOverageDialog.tsx` | 56 | Ink 超额计费确认对话框组件 |
+| `src/services/api/ultrareviewQuota.ts` | 38 | 配额查询 API 客户端（`/v1/ultrareview/quota`） |
+| `src/utils/ultraplan/keyword.ts` (101–112 行) | 12 | 输入框 rainbow 关键词检测（复用 ultraplan 的关键词框架） |
+| `src/components/tasks/RemoteSessionProgress.tsx` | 183 | 远程审查会话的进度展示组件（◇/◆ + rainbow text + 计数） |
+
+### 2.2 深度关联文件
+
+| 文件路径 | 与 Ultra Review 的关系 |
+|----------|----------------------|
+| `src/tasks/RemoteAgentTask/RemoteAgentTask.tsx` | 远程任务框架：任务注册、轮询引擎、日志解析、进度提取、通知生发 |
+| `src/components/tasks/RemoteSessionDetailDialog.tsx` | 远程会话详情对话框（含 "Stop ultrareview" 交互） |
+| `src/utils/teleport.tsx` | `teleportToRemote()` — 将仓库传送到 CCR 环境的传输层 |
+| `src/services/api/usage.ts` | `fetchUtilization()` — Extra Usage 余额查询 |
+| `src/components/PromptInput/PromptInput.tsx` | 输入框中 "ultrareview" 关键词的 rainbow 高亮和提示通知 |
+| `src/constants/figures.ts` (26–29) | 状态图标：◇ DIAMOND_OPEN（运行中）、◆ DIAMOND_FILLED（已完成/失败） |
+| `src/constants/xml.ts` (44–49) | XML 标签常量：`remote-review`、`remote-review-progress` |
+| `src/commands.ts` (41, 352) | 命令注册表：导入并注册 `ultrareview` 命令 |
+| `src/commands/bughunter/index.js` | **Stub** — `/bughunter` 本地命令（`isEnabled: () => false`） |
+
+---
+
+## 3. 架构详解
+
+### 3.1 命令注册
+
+```
+src/commands.ts
+  ├── import review, { ultrareview } from './commands/review.js'
+  └── allCommands = [ ..., review, ultrareview, ... ]
+```
+
+`review.ts` 导出两个 Command 对象：
+
+- **`review`**（type: `'prompt'`）— 纯本地审查。向 Claude 发送 prompt 让模型调用 `gh pr diff` 做本地代码审查。
+- **`ultrareview`**（type: `'local-jsx'`）— 云端审查。`isEnabled()` 由 GrowthBook 门控，`load()` 懒加载 `ultrareviewCommand.tsx`。
+
+```typescript
+// review.ts
+const ultrareview: Command = {
+  type: 'local-jsx',
+  name: 'ultrareview',
+  description: `~10–20 min · Finds and verifies bugs in your branch. Runs in Claude Code on the web.`,
+  isEnabled: () => isUltrareviewEnabled(),
+  load: () => import('./review/ultrareviewCommand.js'),
+}
+```
+
+### 3.2 门控层
+
+#### 3.2.1 可见性门控（GrowthBook）
+
+```typescript
+// ultrareviewEnabled.ts
+export function isUltrareviewEnabled(): boolean {
+  const cfg = getFeatureValue_CACHED_MAY_BE_STALE<Record<string, unknown> | null>(
+    'tengu_review_bughunter_config', null
+  )
+  return cfg?.enabled === true
+}
+```
+
+- 从 GrowthBook 远程配置读取 `tengu_review_bughunter_config` feature flag
+- 当 `cfg.enabled !== true` 时，`/ultrareview` 命令在 `getCommands()` 中被过滤掉，用户完全看不到
+- **fork 环境问题**：GrowthBook 连接通常返回空值，导致命令永远不可见
+
+#### 3.2.2 计费门控（OverageGate）
+
+```typescript
+// reviewRemote.ts
+export type OverageGate =
+  | { kind: 'proceed'; billingNote: string }
+  | { kind: 'not-enabled' }
+  | { kind: 'low-balance'; available: number }
+  | { kind: 'needs-confirm' }
+```
+
+`checkOverageGate()` 的决策树：
+
+```
+checkOverageGate()
+  │
+  ├─ Team/Enterprise 订阅 → proceed（免费包含）
+  │
+  ├─ 并行获取 quota + utilization
+  │   ├─ quota 不可用（非订阅/API 失败）→ proceed（服务端处理）
+  │   ├─ reviews_remaining > 0 → proceed + billingNote（"免费第 N/M 次"）
+  │   ├─ utilization 不可用 → proceed（降级容错）
+  │   ├─ Extra Usage 未启用 → not-enabled
+  │   ├─ 余额 < $10 → low-balance
+  │   ├─ 未在本会话确认过 → needs-confirm
+  │   └─ 已确认 → proceed + billingNote（"Extra Usage 计费"）
+  │
+  └─ 会话级确认标志 sessionOverageConfirmed（一次确认，全会话生效）
+```
+
+### 3.3 命令处理器
+
+```typescript
+// ultrareviewCommand.tsx — call() 函数
+export const call: LocalJSXCommandCall = async (onDone, context, args) => {
+  const gate = await checkOverageGate()
+
+  switch (gate.kind) {
+    case 'not-enabled':
+      // 显示 "启用 Extra Usage" 提示
+      onDone('Free ultrareviews used...', { display: 'system' })
+
+    case 'low-balance':
+      // 显示余额不足提示
+      onDone(`Balance too low ($X.XX available, $10 minimum)...`)
+
+    case 'needs-confirm':
+      // 渲染 UltrareviewOverageDialog 组件
+      return <UltrareviewOverageDialog
+        onProceed={async (signal) => {
+          await launchAndDone(args, context, onDone, billingNote, signal)
+          if (!signal.aborted) confirmOverage()  // 持久化确认
+        }}
+        onCancel={() => onDone('Ultrareview cancelled.')}
+      />
+
+    case 'proceed':
+      // 直接启动
+      await launchAndDone(args, context, onDone, gate.billingNote)
+  }
+}
+```
+
+### 3.4 超额计费对话框
+
+```
+UltrareviewOverageDialog.tsx
+  ┌──────────────────────────────────────────┐
+  │  Ultrareview billing                     │
+  │                                          │
+  │  Your free ultrareviews for this         │
+  │  organization are used. Further          │
+  │  reviews bill as Extra Usage.            │
+  │                                          │
+  │  > Proceed with Extra Usage billing      │
+  │    Cancel                                │
+  └──────────────────────────────────────────┘
+```
+
+特性：
+- Escape 键取消并通过 AbortController signal 中止正在进行的 launch
+- launch 失败（`onProceed` reject）恢复 Select 让用户重试
+- 只有非中止的成功 launch 才调用 `confirmOverage()`
+
+### 3.5 远程会话启动（reviewRemote.ts）
+
+`launchRemoteReview()` 是核心引擎，支持两种模式：
+
+#### 3.5.1 PR 模式
+
+```
+用户输入: /ultrareview 123
+  → args = "123", isPrNumber = true
+  → detectCurrentRepositoryWithHost()
+    → 必须是 github.com（其他 host 返回 null）
+  → teleportToRemote({
+      branchName: "refs/pull/123/head",
+      environmentId: CODE_REVIEW_ENV_ID,
+      environmentVariables: {
+        BUGHUNTER_PR_NUMBER: "123",
+        BUGHUNTER_REPOSITORY: "owner/repo",
+        ...commonEnvVars
+      }
+    })
+```
+
+#### 3.5.2 Branch 模式
+
+```
+用户输入: /ultrareview（无参数）
+  → isPrNumber = false
+  → getDefaultBranch() || "main"
+  → git merge-base <baseBranch> HEAD → mergeBaseSha
+    ├─ 失败 → "Could not find merge-base"
+    └─ 成功 → git diff --shortstat <sha>
+        ├─ 无变更 → "No changes against fork point"
+        └─ 有变更 → teleportToRemote({
+              useBundle: true,    // 打包工作树
+              environmentId: CODE_REVIEW_ENV_ID,
+              environmentVariables: {
+                BUGHUNTER_BASE_BRANCH: mergeBaseSha,
+                ...commonEnvVars
+              }
+            })
+            ├─ 返回 null → "Repo is too large, use PR mode"
+            └─ 成功 → 注册任务
+```
+
+#### 3.5.3 Bughunter 配置参数
+
+从 GrowthBook `tengu_review_bughunter_config` 读取，带安全上限：
+
+| 环境变量 | 含义 | 默认值 | 上限 |
+|----------|------|--------|------|
+| `BUGHUNTER_DRY_RUN` | 干运行标志 | `"1"` | — |
+| `BUGHUNTER_FLEET_SIZE` | agent 舰队大小 | 5 | 20 |
+| `BUGHUNTER_MAX_DURATION` | 单 agent 最大运行时间（分钟） | 10 | 25 |
+| `BUGHUNTER_AGENT_TIMEOUT` | 单 agent 超时（秒） | 600 | 1800 |
+| `BUGHUNTER_TOTAL_WALLCLOCK` | 总运行时间上限（分钟） | 22 | 27 |
+| `BUGHUNTER_DEV_BUNDLE_B64` | 开发用 bundle（可选） | — | — |
+
+`posInt()` 辅助函数对每个参数做类型检查、正整数验证和上限约束。wallclock 上限 27 分钟留出 ~3 分钟给合成阶段，以适配 RemoteAgentTask 的 30 分钟轮询超时。
+
+#### 3.5.4 远程环境 ID
+
+```typescript
+const CODE_REVIEW_ENV_ID = 'env_011111111111111111111113'
+```
+
+这是一个合成的 CCR 环境 ID（Go 的 `taggedid.FromUUID` 编码），不需要 per-org CCR 环境配置即可工作。
+
+#### 3.5.5 前置条件检查
+
+`checkRemoteAgentEligibility()` 检查 6 种前置条件：
+
+| 前置条件 | 说明 | ultrareview 处理 |
+|----------|------|-----------------|
+| `not_logged_in` | 未登录 Claude.ai OAuth | 阻止启动 |
+| `no_remote_environment` | 无云端环境 | **跳过**（合成 env ID 绕过） |
+| `not_in_git_repo` | 不在 git 仓库中 | 阻止启动 |
+| `no_git_remote` | 无 GitHub remote | 阻止启动 |
+| `github_app_not_installed` | Claude GitHub App 未安装 | 阻止启动 |
+| `policy_blocked` | 组织策略禁止远程会话 | 阻止启动 |
+
+### 3.6 任务注册与轮询
+
+#### 3.6.1 任务注册
+
+```typescript
+// reviewRemote.ts 末尾
+registerRemoteAgentTask({
+  remoteTaskType: 'ultrareview',  // 任务类型
+  session,                        // { id, title }
+  command,                        // "/ultrareview" 或 "/ultrareview 123"
+  context,                        // ToolUseContext
+  isRemoteReview: true,           // 启用 review 专用逻辑
+})
+```
+
+`registerRemoteAgentTask()` 执行：
+1. 生成 `taskId`（`generateTaskId('remote_agent')`）
+2. 初始化磁盘输出文件（`initTaskOutput(taskId)`）
+3. 创建 `RemoteAgentTaskState`（初始 status: `'running'`）
+4. 注册到全局任务框架（`registerTask()`）
+5. 持久化到 session sidecar（支持 `--resume`）
+6. 启动轮询循环（`startRemoteSessionPolling()`）
+
+#### 3.6.2 RemoteAgentTaskState（review 相关字段）
+
+```typescript
+type RemoteAgentTaskState = TaskStateBase & {
+  type: 'remote_agent'
+  remoteTaskType: 'ultrareview'
+  sessionId: string
+  command: string
+  title: string
+  todoList: TodoList
+  log: SDKMessage[]
+  pollStartedAt: number
+  isRemoteReview: true            // review 专用标志
+  reviewProgress?: {              // 实时进度
+    stage?: 'finding' | 'verifying' | 'synthesizing'
+    bugsFound: number
+    bugsVerified: number
+    bugsRefuted: number
+  }
+}
+```
+
+#### 3.6.3 轮询引擎
+
+`startRemoteSessionPolling()` 是一个 1 秒间隔的异步轮询循环：
+
+```
+每 1 秒轮询一次:
+  │
+  ├─ pollRemoteSessionEvents(sessionId, lastEventId)
+  │   → 获取新事件 + 会话状态
+  │
+  ├─ 事件增量扫描:
+  │   ├─ 追加到 accumulatedLog
+  │   ├─ 写入磁盘输出文件
+  │   ├─ 提取 <remote-review-progress> → reviewProgress
+  │   └─ 提取 <remote-review> 标签 → cachedReviewContent
+  │
+  ├─ 会话状态 = archived → 完成
+  │
+  ├─ 完成条件判断:
+  │   ├─ cachedReviewContent !== null → 有审查输出
+  │   ├─ stableIdle (5 次连续 idle + 有 assistant 输出 + 非 bughunter 模式)
+  │   └─ reviewTimedOut (pollStartedAt + 30min)
+  │
+  ├─ 成功完成:
+  │   → enqueueRemoteReviewNotification(reviewContent)
+  │   → evictTaskOutput() + removeRemoteAgentMetadata()
+  │
+  └─ 失败:
+      → updateTaskState(status: 'failed')
+      → enqueueRemoteReviewFailureNotification(reason)
+      失败原因:
+        - "remote session returned an error"
+        - "remote session exceeded 30 minutes"
+        - "no review output — orchestrator may have exited early"
+```
+
+**Bughunter 模式 vs Prompt 模式的区别**：
+
+| 特征 | Bughunter 模式 | Prompt 模式 |
+|------|---------------|------------|
+| 产出位置 | SessionStart hook 的 stdout | assistant 消息 |
+| 完成信号 | `<remote-review>` 标签出现 | stableIdle（5 次连续 idle） |
+| 进度来源 | `<remote-review-progress>` 心跳 | 无 |
+| 判别依据 | `hook_event === 'SessionStart'` 存在 | 不存在 |
+
+#### 3.6.4 进度数据格式
+
+```xml
+<remote-review-progress>
+{"stage":"finding","bugs_found":3,"bugs_verified":1,"bugs_refuted":0}
+</remote-review-progress>
+```
+
+轮询器从 `hook_progress` / `hook_response` 事件的 stdout 中提取最后一个此标签（`lastIndexOf`），解析 JSON 并映射到 `reviewProgress`。
+
+#### 3.6.5 审查输出提取
+
+`extractReviewFromLog()` 按优先级扫描 4 个来源：
+
+1. **hook stdout 逐条扫描**（`hook_progress` / `hook_response` 的 `<remote-review>` 标签）
+2. **assistant 消息逐条扫描**（`<remote-review>` 标签）
+3. **hook stdout 拼接回退**（处理大 JSON 跨两个事件的情况）
+4. **全部 assistant 文本拼接回退**（无标签时的兜底）
+
+`extractReviewTagFromLog()` 是增量扫描变体，**不使用第 4 个回退**，避免早期 assistant 消息（如 "I'm analyzing the diff..."）误触发完成。
+
+### 3.7 通知管道
+
+#### 3.7.1 成功通知
+
+```xml
+<task-notification>
+<task-id>{taskId}</task-id>
+<task-type>remote_agent</task-type>
+<status>completed</status>
+<summary>Remote review completed</summary>
+</task-notification>
+The remote review produced the following findings:
+
+{reviewContent}
+```
+
+- 审查内容**直接注入**消息队列（`task-notification` mode），不通过文件间接引用
+- 远程会话**不归档**（保持 alive），用户可通过 claude.ai URL 随时回看
+- TTL 自动清理过期会话
+
+#### 3.7.2 失败通知
+
+```xml
+<task-notification>
+<task-id>{taskId}</task-id>
+<task-type>remote_agent</task-type>
+<status>failed</status>
+<summary>Remote review failed: {reason}</summary>
+</task-notification>
+Remote review did not produce output ({reason}).
+Tell the user to retry /ultrareview, or use /review for a local review instead.
+```
+
+### 3.8 配额 API
+
+```typescript
+// ultrareviewQuota.ts
+type UltrareviewQuotaResponse = {
+  reviews_used: number      // 已使用的免费次数
+  reviews_limit: number     // 免费次数上限
+  reviews_remaining: number // 剩余免费次数
+  is_overage: boolean       // 是否已超额
+}
+
+// GET /v1/ultrareview/quota
+// Headers: OAuth + x-organization-uuid
+// Timeout: 5000ms
+// 前置条件: isClaudeAISubscriber()
+```
+
+### 3.9 UI 层
+
+#### 3.9.1 进度展示（RemoteSessionProgress.tsx）
+
+Review 任务使用 `ReviewRainbowLine` 子组件，呈现三种状态：
+
+**运行中**：
+```
+◇ ultrareview · finding / 3 found · 1 verified
+```
+- ◇ 菱形为 teal 色
+- "ultrareview" 文字带 rainbow 渐变动画（每 3 帧推进一个相位）
+- 计数用 `useSmoothCount` 逐帧递增（2→5 显示为 2→3→4→5）
+
+**已完成**：
+```
+◆ ultrareview ready · shift+↓ to view
+```
+
+**失败**：
+```
+◆ ultrareview · error
+```
+
+#### 3.9.2 阶段计数格式化
+
+```typescript
+formatReviewStageCounts(stage, found, verified, refuted):
+  stage='finding'      → "3 found"  或  "finding"（0 时）
+  stage='verifying'    → "3 found · 1 verified"  + refuted（>0 时）
+  stage='synthesizing' → "1 verified · deduping"  + refuted（>0 时）
+  stage=undefined      → "3 found · 1 verified"（pre-stage 编排器）
+```
+
+#### 3.9.3 详情对话框（RemoteSessionDetailDialog.tsx）
+
+展示完整的远程会话信息，包含：
+- 标题栏：◇/◆ + "ultrareview" + 运行时间 + 状态
+- 会话消息流（标准化后的 Message 组件）
+- 操作菜单：
+  - "Open in Claude Code on the web"（打开浏览器）
+  - "Stop ultrareview"（运行中时，需二次确认）
+  - "Back" / "Dismiss"
+
+停止确认对话框：
+```
+┌──────────────────────────────────────────┐
+│  Stop ultrareview?                       │
+│                                          │
+│  This archives the remote session and    │
+│  stops local tracking. The review will   │
+│  not complete and any findings so far    │
+│  are discarded.                          │
+│                                          │
+│  > Stop ultrareview                      │
+│    Back                                  │
+└──────────────────────────────────────────┘
+```
+
+#### 3.9.4 输入框 Rainbow 高亮（PromptInput.tsx）
+
+```typescript
+// 在用户输入中检测 "ultrareview" 关键词
+const ultrareviewTriggers = useMemo(
+  () => isUltrareviewEnabled()
+    ? findUltrareviewTriggerPositions(displayedValue)
+    : [],
+  [displayedValue]
+)
+
+// 对关键词应用 per-character rainbow 渐变
+for (const trigger of ultrareviewTriggers) {
+  // 与 ultraplan 相同的 rainbow 处理
+}
+
+// 显示提示通知
+useEffect(() => {
+  if (isUltrareviewEnabled() && ultrareviewTriggers.length) {
+    addNotification({
+      key: 'ultrareview-active',
+      text: 'Run /ultrareview after Claude finishes to review these changes in the cloud',
+      priority: 'immediate',
+      timeoutMs: 5000,
+    })
+  }
+}, [ultrareviewTriggers.length])
+```
+
+---
+
+## 4. 数据流全景
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           用户输入 /ultrareview [PR#]                        │
+└────────────────────────────────────┬────────────────────────────────────────┘
+                                     │
+                                     ▼
+                         ┌──────────────────────┐
+                         │  ultrareviewEnabled   │
+                         │  GrowthBook 门控      │
+                         │  tengu_review_        │
+                         │  bughunter_config     │
+                         └──────────┬───────────┘
+                                    │ enabled === true
+                                    ▼
+                     ┌───────────────────────────────┐
+                     │  ultrareviewCommand.tsx        │
+                     │  checkOverageGate()            │
+                     └──────────┬────────────────────┘
+                                │
+               ┌────────────────┼────────────────┐
+               │                │                │
+               ▼                ▼                ▼
+         ┌──────────┐   ┌──────────────┐  ┌───────────┐
+         │ proceed   │   │ needs-confirm│  │ not-      │
+         │           │   │              │  │ enabled / │
+         │           │   │ Overage      │  │ low-      │
+         │           │   │ Dialog       │  │ balance   │
+         └─────┬─────┘   └──────┬───────┘  └───────────┘
+               │                │                  ×
+               │      用户确认   │
+               ▼                ▼
+        ┌──────────────────────────────┐
+        │  reviewRemote.ts             │
+        │  launchRemoteReview()        │
+        └──────────┬───────────────────┘
+                   │
+        ┌──────────┼──────────┐
+        │ PR 模式               │ Branch 模式
+        ▼                      ▼
+  ┌────────────────┐   ┌──────────────────────┐
+  │ detect repo    │   │ merge-base + diff     │
+  │ github.com only│   │ empty diff → 中止     │
+  │                │   │ useBundle: true       │
+  └───────┬────────┘   └──────────┬───────────┘
+          │                       │
+          └───────────┬───────────┘
+                      ▼
+           ┌──────────────────────┐
+           │  teleportToRemote()  │
+           │  → CCR 远程环境       │
+           │  env_01...13         │
+           │  BUGHUNTER_* 环境变量 │
+           └──────────┬───────────┘
+                      │
+                      ▼
+        ┌──────────────────────────────┐
+        │  registerRemoteAgentTask()   │
+        │  type: 'ultrareview'         │
+        │  isRemoteReview: true        │
+        └──────────┬───────────────────┘
+                   │
+                   ▼
+     ┌────────────────────────────────────┐
+     │  startRemoteSessionPolling()       │
+     │  每 1 秒轮询                        │
+     │                                    │
+     │  ┌───────────────────────────┐     │
+     │  │ pollRemoteSessionEvents() │     │
+     │  │ → 增量事件 + 会话状态      │     │
+     │  └───────────┬───────────────┘     │
+     │              │                     │
+     │     ┌────────┼────────┐            │
+     │     ▼        ▼        ▼            │
+     │  progress  review   timeout        │
+     │  心跳解析   标签提取   30 min       │
+     │                                    │
+     │  finding → verifying → synth.      │
+     └──────────┬─────────────────────────┘
+                │ 完成
+                ▼
+  ┌──────────────────────────────────────┐
+  │  enqueueRemoteReviewNotification()   │
+  │  → task-notification 消息队列         │
+  │  → 本地 Claude 模型接收并叙述结果      │
+  └──────────────────────────────────────┘
+```
+
+---
+
+## 5. 遥测事件
+
+| 事件名 | 触发时机 |
+|--------|---------|
+| `tengu_review_overage_not_enabled` | 免费次数用完且 Extra Usage 未启用 |
+| `tengu_review_overage_low_balance` | Extra Usage 余额 < $10 |
+| `tengu_review_overage_dialog_shown` | 超额确认对话框弹出 |
+| `tengu_review_remote_precondition_failed` | 前置条件检查失败（含 `precondition_errors` 字段） |
+| `tengu_review_remote_teleport_failed` | teleport 传输失败（session = null） |
+| `tengu_review_remote_launched` | 远程会话成功创建 |
+
+---
+
+## 6. 缺失与问题分析
+
+### 6.1 Stub：`/bughunter` 命令
+
+```javascript
+// src/commands/bughunter/index.js
+export default { isEnabled: () => false, isHidden: true, name: 'stub' }
+```
+
+这是 bughunter 编排器的**本地调试入口**，完全被 stub 掉。在生产环境中 bughunter 逻辑运行在 CCR 远端容器（`run_hunt.sh`），所以这个 stub 不影响 ultrareview 功能。但如果需要本地调试 bughunter 编排器，需要恢复此命令。
+
+### 6.2 零测试覆盖
+
+`src/commands/review/` 目录下没有 `__tests__/` 目录。以下函数完全无测试：
+
+- `isUltrareviewEnabled()` — 门控函数
+- `checkOverageGate()` — 计费决策树（4 个分支 × 多种 quota/utilization 组合）
+- `launchRemoteReview()` — 核心引擎（PR/Branch 两条路径 + 多种失败场景）
+- `UltrareviewOverageDialog` — React 组件（用户交互 + abort 信号 + 错误恢复）
+- `fetchUltrareviewQuota()` — API 客户端
+- `extractReviewFromLog()` / `extractReviewTagFromLog()` — 日志解析（4 个回退层级）
+- `formatReviewStageCounts()` — 阶段格式化
+- `ReviewRainbowLine` / `useSmoothCount` — 动画组件
+
+其中 `checkOverageGate()` 和 `extractReview*FromLog()` 的分支复杂度最高，最需要测试。
+
+### 6.3 GrowthBook 门控无本地回退
+
+`isUltrareviewEnabled()` 完全依赖远程 GrowthBook 配置。与 ultraplan 等功能不同，没有 `LOCAL_GATE_DEFAULTS` 或环境变量覆盖。在 fork 环境中：
+
+- GrowthBook 连接返回 `null`
+- `cfg?.enabled === true` 永远为 `false`
+- `/ultrareview` 命令对用户完全不可见
+
+**修复方案**：添加环境变量回退，如 `FEATURE_ULTRAREVIEW=1` → `true`。
+
+### 6.4 CCR 依赖
+
+Ultra Review 整条链路依赖 Claude Code on the web（CCR）：
+
+- `teleportToRemote()` — 需要 OAuth 认证 + CCR 会话 API
+- `isClaudeAISubscriber()` — 配额查询的前提
+- `pollRemoteSessionEvents()` — 需要 CCR 事件流 API
+- 合成环境 ID `env_011111111111111111111113` — CCR 服务端识别
+
+对于非 Anthropic 订阅用户或离线环境，ultrareview 不可用。`/review` 命令作为本地回退方案。
+
+### 6.5 TODO 项
+
+代码中存在一个未完成的 TODO：
+
+```
+// reviewRemote.ts:9
+// TODO(#22051): pass useBundleMode once landed so local-only / uncommitted
+// repo state is captured. The GitHub-clone path (current) only works for
+// pushed branches on repos with the Claude GitHub app installed.
+```
+
+Branch 模式已经实现了 `useBundle: true`（打包工作树），但 PR 模式仍然只通过 GitHub 克隆，不能捕获本地未提交的改动。
+
+---
+
+## 7. 与 `/review` 的对比
+
+| 维度 | `/review` | `/ultrareview` |
+|------|-----------|---------------|
+| 类型 | `prompt` | `local-jsx` |
+| 执行位置 | 本地 | CCR 云端 |
+| 时间 | 即时（取决于模型速度） | 10–20 分钟 |
+| 机制 | 发送 prompt 让 Claude 调用 `gh pr diff` | teleport + bughunter 多 agent 舰队 |
+| 门控 | 无 | GrowthBook + 计费门控 |
+| 依赖 | `gh` CLI + GitHub token | OAuth + CCR + Claude GitHub App |
+| 输出 | 模型直接回复 | task-notification 异步注入 |
+| 适用场景 | 快速轻量审查 | 深度 bug 挖掘 + 验证 |
+
+---
+
+## 8. 与 `/ultraplan` 的共享基础设施
+
+Ultra Review 大量复用了 ultraplan 建立的基础设施：
+
+| 共享模块 | 用途 |
+|----------|------|
+| `teleportToRemote()` | 仓库传送到 CCR |
+| `registerRemoteAgentTask()` | 远程任务注册 |
+| `startRemoteSessionPolling()` | 轮询引擎 |
+| `RemoteAgentTaskState` | 任务状态类型 |
+| `RemoteSessionDetailDialog` | 详情对话框 |
+| `findKeywordTriggerPositions()` | 输入框关键词检测 |
+| `RainbowText` / `getRainbowColor()` | rainbow 渐变动画 |
+| `checkRemoteAgentEligibility()` | 前置条件检查 |
+| `persistRemoteAgentMetadata()` | session sidecar 持久化 |
+| `restoreRemoteAgentTasks()` | `--resume` 恢复 |
+
+差异点：
+- ultrareview 使用 `isRemoteReview: true` 标志走 review 专用分支
+- ultrareview 有自己的轮询完成逻辑（`<remote-review>` 标签 vs ultraplan 的 `ExitPlanMode` 扫描）
+- ultrareview 有配额 + 计费门控（ultraplan 没有）
+- ultrareview 有 bughunter 环境变量配置层（ultraplan 没有）