# 赛道二：IDE+开发范式创新赛 — 评审系统设计文档

**版本**：v1.2
**最后更新**：2026-07-27

---

## 目录

1. [概述](#1-概述)
2. [Standard 定义](#2-standard-定义)
3. [dimGuidelines 设计](#3-dimguidelines-设计)
4. [DIM_FILE_FILTERS 修改](#4-dim_file_filters-修改)
5. [其他代码修改](#5-其他代码修改)
6. [验证方案](#6-验证方案)

---

## 1. 概述

### 核心改动点

| 改动 | 说明 | 文件 |
|------|------|------|
| 新增 category_tag | `track2-ide-new` / `track2-ide-upgrade` | 运行时 |
| 新增 Standard | 7维度，满分100 | 通过 API 创建 |
| 新增 dimGuidelines | 7个赛道二维度（不修改现有key） | `review.service.ts` |
| 新增 file filter | 赛道二专用 filter（不修改现有filter） | `review.service.ts` |
| filterFilesForDim exact-match | 精确匹配优先，避免key名冲突 | `review.service.ts` |
| runSubAgent exact-match | 精确匹配优先 | `review.service.ts` |
| dimGuidelines 模板求值 | `${dim.maxScore}` 替换为实际分数 | `review.service.ts` |
| 赛道二版 演示与文档/AI使用日志 | categoryTag分支逻辑，避免覆盖赛道一 | `review.service.ts` |
| 赛道二硬规则 | 6条赛道二专用硬规则 | `review.service.ts` |
| base_branch diff获取 | `fetchBaseBranchDiff()` | `review.service.ts` 新模块 |

---

## 2. Standard 定义

### 2.1 category_tag

```
赛道二·新规项目：track2-ide-new
```

### 2.2 维度定义（Standard content）

```markdown
## 开发范式设计清晰度（20分）

检查以下4项（满分20分）：
1. 范式完整性（6分）
   - 是否有完整的范式工作流描述（每个步骤有输入→处理→输出）
   - 完整6分，部分完整3-4分，无描述0分

2. 自评等级合理性（6分）
   - A级：有指令文件+Skill+规则且内容完整
   - B级：有指令文件或Skill且非空
   - C级：无硬件要求，据实填写
   - 虚高（自评与证据不匹配）扣分，谦虚不扣

3. 范式与日志一致性（5分）
   - 范式步骤名称与AI使用日志中的"范式步骤"列完全一致
   - 全一致5分，部分匹配2-3分，不一致0分

4. 反馈回路（3分）
   - 范式描述中是否有反馈/迭代机制
   - 有反馈回路3分，无0分

## IDE集成深度（20分）

分层评分：
- 基础层（0-6分）：注册了至少1个命令/触发词，声明与实际一致
- 进阶层（0-13分）：基础+有快捷键/菜单+有上下文获取实现
- 深度层（0-20分）：进阶+多触发方式+自动上下文+跨IDE/CLI支持

验证方式：逐条检查声明中的文件路径和函数名是否在源码中存在

## 提效设计合理性（20分）

检查以下4项（满分20分）：
1. 问题定义是否明确（5分）
   - 有具体的开发效率问题描述，包含环节和瓶颈
   - 明确5分，模糊2-3分，无0分

2. 改进前后流程对比（6分）
   - 有改进前和改进后的完整步骤对比
   - 完整6分，部分对比3-4分，无0分

3. 自动化覆盖环节合理（5分）
   - 自动化覆盖的环节在源码中有对应实现
   - 合理5分，部分合理2-3分，不合理0分

4. 局限性说明（4分）
   - 有明确的适用条件和局限性描述
   - 完整4分，有描述1-2分，无0分

## 稳定性与易用性（15分）

检查以下3项（满分15分）：
1. 安装方式清晰（5分）
   - 有明确的安装命令和依赖说明
   - 清晰5分，有说明2-3分，无0分

2. 错误处理覆盖（5分）
   - 声明中的异常场景在源码中有对应处理（try-catch/错误码）
   - 全覆盖5分，部分覆盖2-3分，无0分

3. 重试与降级机制（5分）
   - 声明中的重试/降级机制在源码中有对应实现
   - 有实现5分，部分实现2-3分，无0分

## 规模、功能点、技术难度（10分）

检查以下3项（满分10分）：
1. 范式复杂度（3分）
   - 范式步骤数、Skill/规则数与项目实际匹配
   - 匹配3分，部分匹配1-2分，不匹配0分

2. 覆盖面（3分）
   - 覆盖开发环节数与AI日志记录一致
   - 一致3分，部分一致1-2分，不一致0分

3. 集成方式与技术难度（4分）
   - 声明中的集成方式在源码中有对应实现
   - 全实现4分，部分实现1-2分，无0分

## 演示与文档（5分）

检查以下4项（满分5分）：
1. README 完整性（2分）
   - 是否有 README.md（若无→0分）
   - 是否包含：项目说明、安装步骤、使用示例

2. API/架构文档（1分）

3. 启动与构建说明（1分）

4. 文档一致性（1分）

## AI使用日志（10分）

检查以下4项（满分10分）：
1. AI使用记录（4分）
2. 调用细节（2分）
3. 效率数据（2分）
4. 真实性验证（2分）
```

### 2.3 维度汇总

| 维度 | 分值 | 来源 |
|------|:---:|------|
| 开发范式设计清晰度 | 20 | 新增 |
| IDE集成深度 | 20 | 新增 |
| 提效设计合理性 | 20 | 新增 |
| 稳定性与易用性 | 15 | 新增 |
| 规模、功能点、技术难度 | 10 | 新增独立key（不修改现有"规模"） |
| 演示与文档 | 5 | 复用现有 |
| AI使用日志 | 10 | 复用现有 |
| **合计** | **100** | |

---

## 3. dimGuidelines 设计

### 3.1 确保 `${dim.maxScore}` 被正确求值

dimGuidelines 内容中大量使用 `${dim.maxScore}` 模板变量。需要在 `runSubAgent` 中将 guideline 字符串做模板求值：

```typescript
// 在 runSubAgent 中，获取 guideline 后：
const resolvedGuideline = guideline.replace(/\$\{dim\.maxScore\}/g, String(dim.maxScore));
```

确认 `review.service.ts` 中 guideline 使用处是否已做此处理。如果当前代码直接将 guideline 作为字符串传递给 LLM 而未做替换，所有 `${dim.maxScore}` 会原样出现在 prompt 中。

### 3.2 修改 `runSubAgent` 中的 dimGuidelines 匹配逻辑

```typescript
const guideline = dimGuidelines[Object.keys(dimGuidelines).find(k => dim.name.includes(k)) || ''];
```

因为已有的 keys（如"开发范式"）会匹配赛道二的新维度名（如"开发范式设计清晰度"），所以需要**exact-match-first**策略：

```typescript
// Exact match first (for Track 2 specific dim names)
const exactGuideline = dimGuidelines[dim.name];
const guideline = exactGuideline || dimGuidelines[Object.keys(dimGuidelines).find(k => dim.name.includes(k)) || ''];
```

### 3.3 新增 dimGuidelines entries

在 `dimGuidelines` Record 中新增以下 keys：

```typescript
'开发范式设计清晰度': `检查以下4项（满分${dim.maxScore}分）：
1. 范式完整性（6分）
   - 范式工作流是否有完整步骤描述（输入→处理→输出）→ 5-6分
   - 部分完整 → 2-4分
   - 无描述 → 0分

2. 自评等级合理性（6分）
   - A级：有指令文件+Skill+规则且内容完整 → 5-6分（自评合理）／1-3分（虚高）
   - B级：有指令文件或Skill且非空 → 4-5分（自评合理）／1-2分（虚高）
   - C级：无硬件要求 → 3-4分（据实）／1分（虚高）
   - 自评合理但证据略多（谦虚）→ 不扣分

3. 范式与日志一致性（5分）
   - 范式步骤名称与AI日志完全一致 → 4-5分
   - 部分匹配 → 2-3分
   - 不一致 → 0分

4. 反馈回路（3分）
   - 范式中包含反馈/迭代机制 → 3分
   - 无反馈回路 → 0分`,

'IDE集成深度': `分层评分（满分${dim.maxScore}分）：
按以下层级判定，取最高达标层级的得分区间：

🥉 基础层（0-6分）：
- 注册了至少1个命令/触发词
- 声明中的文件路径和配置键在源码中存在

🥈 进阶层（0-13分）：
- 满足基础层条件
- 有快捷键/菜单配置
- 有上下文获取实现（声明中函数名在源码中存在）

🥇 深度层（0-20分）：
- 满足进阶层条件
- 声明了自动上下文获取（alwaysApply等）
- 有2种及以上集成方式（VS Code + CLI / OpenCode等）

评分规则：
- 达标层的高分段：证据全面+实现完整
- 达标层的低分段：证据存在但实现不完整（如只有声明无源码）
- 未达标层：该层评审项有一项不符即不达标`,

'提效设计合理性': `检查以下4项（满分${dim.maxScore}分）：
1. 问题定义明确性（5分）
   - 有具体的开发效率问题和瓶颈描述 → 4-5分
   - 描述模糊 → 1-3分
   - 无问题定义 → 0分

2. 改进前后流程对比（6分）
   - 有改进前和改进后的完整步骤对比 → 5-6分
   - 有对比但不完整 → 2-4分
   - 无对比 → 0分

3. 自动化覆盖环节合理性（5分）
   - 声明的自动化环节在源码中有对应实现 → 4-5分
   - 部分有实现 → 2-3分
   - 声明但无源码支撑 → 0分

4. 局限性说明（4分）
   - 包含适用条件和局限性描述 → 4分
   - 仅有描述但不完整 → 1-3分
   - 无局限性说明 → 0分`,

'稳定性与易用性': `检查以下3项（满分${dim.maxScore}分）：
1. 安装方式清晰（5分）
   - README和design.md中安装说明一致，依赖数合理 → 4-5分
   - 有说明但不完整 → 2-3分
   - 无安装说明 → 0分

2. 错误处理覆盖（5分）
   - 声明的异常场景在源码中有对应处理 → 4-5分
   - 部分场景有处理 → 2-3分
   - 声明但无对应实现 → 0分

3. 重试与降级机制（5分）
   - 声明的重试/降级机制在源码中有对应实现 → 4-5分
   - 部分有实现 → 2-3分
   - 声明但无源码 → 0分`,
```

### 3.4 新增"规模、功能点、技术难度"维度的 dimGuidelines（不修改现有"规模"key）

现有 `'规模'` key 在 Track 1 中用作代码行数和语言多样性的评审指南，**不能修改**，否则 Track 1 评审会错乱。

赛道二的维度名是"规模、功能点、技术难度"，在 exact-match-first 策略下会优先匹配精确 key。因此新增独立的 key：

```typescript
'规模、功能点、技术难度': `检查以下3项（满分${dim.maxScore}分）：

1. 范式复杂度（3分）
   - 自评的范式步骤数与design.md中的实际步骤数匹配 → 2-3分
   - 部分匹配 → 1分
   - 不匹配 → 0分

2. 覆盖面（3分）
   - 自评的覆盖率（需求/设计/编码/测试/审查）与AI日志中的步骤分布一致 → 3分
   - 部分一致 → 1-2分
   - 不一致 → 0分

3. 集成方式与技术难度（4分）
   - 声明的集成方式在源码中有对应实现且功能完整 → 4分
   - 部分实现 → 1-3分
   - 声明但无实现 → 0分`,
```

---

## 4. DIM_FILE_FILTERS 修改

### 4.1 filterFilesForDim 也需要 exact-match-first

`filterFilesForDim` 中通过 `dim.name.includes(key)` 匹配 filter key。和 `runSubAgent` 相同的问题：`'规模'` filter 会错误匹配赛道二的 `'规模、功能点、技术难度'`。

**修改 `filterFilesForDim` 的匹配逻辑**：

```typescript
// 修改前（现有逻辑）
const matchedKey = Object.keys(DIM_FILE_FILTERS).find(k => dim.name.includes(k));

// 修改后（exact-match-first）
const exactKey = DIM_FILE_FILTERS[dim.name] ? dim.name : undefined;
const matchedKey = exactKey || Object.keys(DIM_FILE_FILTERS).find(k => dim.name.includes(k));
```

**安全确认**：此修改对 Track 1 无影响。Track 1 的维度名是"规模""开发范式与架构设计"等短名称，不会被赛道二的新 filter key 精确匹配（因为赛道二的 filter key 如"规模、功能点、技术难度"不是 Track 1 维度名的精确值）。Track 1 的现有 filter 继续通过 `includes` 回退逻辑工作。

### 4.2 新增 filter

新增 `efficiency-report.md` 文件需要被"提效设计合理性"维度读取：

```typescript
'提效设计合理性': (f) => /efficiency-report|README/i.test(f.path),
```

### 4.3 新增"规模、功能点、技术难度"的 filter（不修改现有"规模"filter）

现有 `'规模'` filter 匹配源码文件用于行数统计，Track 1 需要它保持不变。

赛道二的"规模、功能点、技术难度"需要读取 `_PROJECT_OVERVIEW.md`（自评信息）和 `docs/design.md`（范式步骤数），因此新增独立 filter：

```typescript
'规模、功能点、技术难度': (f) => /_PROJECT_OVERVIEW|docs\/design/i.test(f.path) && !/node_modules/i.test(f.path),
```

### 4.4 IDE集成深度的 filter

IDE集成深度需要读取 `docs/design.md` 和 `package.json` 以及 skill/rule 文件：

```typescript
'IDE集成': (f) => /docs\/design|package\.json|\.cursor|\.vscode|\.mdc|SKILL\.md|AGENTS\.md|CLAUDE\.md/i.test(f.path) && !/node_modules/i.test(f.path),
```

注意：这个 key `'IDE集成'` 会通过 `dim.name.includes('IDE集成')` 匹配赛道二的维度名 `'IDE集成深度'`，同时不会影响 Track 1（其维度名中不包含"IDE集成"）。

> **安全防护**：如果未来修改维度名（如将"IDE集成深度"改为"IDE工具集成"），必须同步修改此 filter key，否则 `includes` 匹配会静默失效。建议在 DIM_FILE_FILTERS 上方添加注释：`// 此 key 通过 includes 匹配"IDE集成深度"维度，修改维度名时需同步`。

---

## 5. 其他代码修改

### 5.1 hard rules 调整

赛道二的硬规则与赛道一不同：

```typescript
// 在硬规则循环中增加赛道二特殊规则
if (entry.category_tag?.startsWith('track2-ide')) {
  // 硬规则1：install 失败 → 稳定性与易用性扣分
  if (buildFailed && name.includes('稳定性与易用性')) {
    cap = Math.min(cap, Math.floor(d.maxScore * 0.33));
  }

  // 硬规则2：start 失败 → 稳定性与易用性扣分
  if (startFailed && name.includes('稳定性与易用性')) {
    cap = Math.min(cap, Math.floor(d.maxScore * 0.33));
  }

  // 硬规则3：base_branch diff 未通过交叉验证 → 稳定性与易用性扣分
  if (diffValidationFailed && name.includes('稳定性与易用性')) {
    cap = Math.min(cap, Math.floor(d.maxScore * 0.5));
  }

  // 硬规则4：efficiency-report.md 不存在 → 提效设计合理性扣分
  if (efficiencyReportMissing && name.includes('提效设计合理性')) {
    cap = Math.min(cap, Math.floor(d.maxScore * 0.5));
  }

  // 硬规则5：AI使用日志少于3条 → 赛道二升级项目门槛
  if (aiLogCount < 3 && name.includes('AI使用日志')) {
    cap = Math.min(cap, Math.floor(d.maxScore * 0.3));
  }

  // 硬规则6：自评等级虚高 → 开发范式设计清晰度扣分
  if (selfRatingOverclaim && name.includes('开发范式设计清晰度')) {
    cap = Math.min(cap, Math.floor(d.maxScore * 0.6));
  }
} else {
  // 赛道一逻辑保持不变
}
```

### 5.2 赛道二版"演示与文档"和"AI使用日志" dimGuidelines

现有 Track 1 的"演示与文档"和"AI使用日志" dimGuideline 可能引用"场景价值""Agent闭环"等赛道一术语。但这两个维度在赛道一和赛道二中的维度名**完全相同**（都是"演示与文档"和"AI使用日志"），所以不能通过新增 key + exact-match-first 来区分。

**解决方案**：在 dimGuidelines 的 value 中使用 `categoryTag` 参数做分支逻辑：

```typescript
'演示与文档': categoryTag?.startsWith('track1') 
  ? `Track 1 版本：...`  // 保持现有内容
  : `检查以下4项（满分${dim.maxScore}分）：
1. README 完整性（2分）
   - 有 README.md → 1分
   - 包含：项目说明、安装步骤、使用示例 → 各0.33分
   - 若无 README.md → 0分

2. 文档结构（1分）
   - 有清晰的目录分层
   - 有配置文件说明或架构说明

3. 启动与构建说明（1分）
   - 有运行环境要求和安装命令
   - 命令可复现（有具体版本号）

4. 文档一致性（1分）
   - 文档中提到的文件路径、函数名在源码中存在
   - 声明与实现一致`,
```

注意：`categoryTag` 通过 `runSubAgent` 的 `categoryTag` 参数传入（详见 5.4）。

```typescript
'AI使用日志': categoryTag?.startsWith('track1')
  ? `Track 1 版本：...`  // 保持现有内容
  : `检查以下4项（满分${dim.maxScore}分）：
1. AI使用记录完整性（4分）
   - 日志完整覆盖开发全过程 → 4分
   - 覆盖主要环节但部分缺失 → 2-3分
   - 少量记录或无记录 → 0-1分

2. 修改摘要清晰度（2分）
   - 每次记录有清晰的修改摘要 → 2分
   - 摘要模糊 → 1分
   - 无摘要 → 0分

3. 涉及文件可追溯（2分）
   - 日志中涉及文件在源码中存在 → 2分
   - 部分存在 → 1分
   - 不存在 → 0分

4. 步骤名称与范式一致（2分）
   - 日志中"范式步骤"与 design.md 中步骤名称完全一致 → 2分
   - 部分一致 → 1分
   - 不一致 → 0分`,
```

> 注意：如果现有 Track 1 的"演示与文档"和"AI使用日志" dimGuideline 已经足够通用（不包含赛道一特有术语），则不需要使用分支逻辑，直接保持现有 key 不变即可。实现时需先审查现有内容再做决定。

### 5.3 category_tag 传递

需要确保 `entry.category_tag` 在 `executeReview` 中能被 `runSubAgent` 访问到。当前 `runSubAgent` 不接收 category_tag 参数。

```typescript
// 修改 runSubAgent 签名
async function runSubAgent(dim: any, projectContext: string, files, buildResult, startResult?, browseResult?, categoryTag?: string): Promise<any>

// 调用时传入
const r = await runSubAgent(dim, projectContext, files, buildResult, startResult, browseResult, entry.category_tag);
```

---

### 5.4 base_branch 实现（升级项目diff获取）

升级项目需要从 `base_branch` 拉取旧代码做 diff。实现方案：

```typescript
async function fetchBaseBranchDiff(workDir: string, baseBranch: string): Promise<{files: string[], diffContent: string} | null> {
  try {
    // 1. 确认当前目录是 git 仓库
    const isGit = await exec('git rev-parse --git-dir', { cwd: workDir });
    if (!isGit) return null;

    // 2. fetch 目标分支
    await exec(`git fetch origin ${baseBranch}`, { cwd: workDir, timeout: 30000 });

    // 3. 获取 diff 文件列表（仅文件名，不含行数统计）
    const diffOutput = await exec(`git diff ${baseBranch}...HEAD --name-only`, { cwd: workDir });
    const changedFiles = diffOutput.trim().split('\n').filter(Boolean);

    // 4. 获取完整 diff 内容（供 AI 验证改造对照表）
    const diffContent = await exec(`git diff ${baseBranch}...HEAD`, { cwd: workDir });

    return { files: changedFiles, diffContent };
  } catch (err) {
    console.warn(`[base_branch] Failed to fetch diff for ${baseBranch}:`, err.message);
    return null; // 不阻断评审流程
  }
}
```

**关键行为**：
- fetch 失败或分支不存在 → 返回 null，评审继续（不扣分，但改造对照表纯文本验证）
- diff 结果**仅**传递给 `runSubAgent` 作为改造验证的上下文，不参与代码行数统计
- diff 内容达到 `guideline` 字符串中追加到 prompt，如："改造对照表 diff 验证：以下为 base_branch 与当前分支的差异文件列表：\n{文件列表}"

**调用时机**：在 `executeReview` 中，创建评审阶段，获取 diff 后缓存，在 `runSubAgent` 中传给各维度。

---

## 6. 验证方案

### 6.1 测试步骤

1. 创建项目 + Standard（category_tag = `track2-ide-new`）
2. 创建一个赛道二 Entry（提交一个合规的IDE项目）
3. 启动评审
4. 验证评审日志维度数和分值分配

### 6.2 验证标准

| 检查项 | 预期结果 |
|--------|---------|
| 维度数 | 7个维度 |
| 总分 | 100 |
| 每个维度分值 | 与 Standard 定义一致 |
| IDE集成深度 分层判定 | 按输入项目判定正确层级 |
| 提效设计合理性 读取文件 | 正确读取 efficiency-report.md |
| 自评等级验证 | 虚高场景扣分准确 |

### 6.3 自动化 E2E 测试用例

在现有 Playwright 测试套件（`web/e2e/`）中新增以下测试：

| 测试名 | 测试内容 | 依赖 |
|--------|---------|------|
| `track2-standard.spec.ts` | 创建赛道二 Standard（7维度，100分），验证维度名和分值正确 | DeepSeek API |
| `track2-entry-submit.spec.ts` | 创建一个赛道二 Entry，提交后验证 category_tag 持久化 | DeepSeek API |
| `track2-review-dimensions.spec.ts` | 启动评审，验证 7 个维度的 prompt 都包含对应的 dimGuidelines | DeepSeek API + Ollama |
| `track2-ide-tiering.spec.ts` | 提交含 package.json 命令配置的 IDE 项目，验证基础层判定正确 | DeepSeek API |
| `track2-upgrade-entry.spec.ts` | 创建 upgrade Entry + base_branch，验证 diff fetch 行为 | 需两个 git 分支 |
| `track2-missing-efficiency-report.spec.ts` | 提效报告不存在时，验证硬规则生效 | DeepSeek API |