hangshuo652/L2keka
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
c16aa70aae79d560c5e490277d246e168400d522
L2keka/server/docs/track2-implementation.md
T

20 KiB
Raw Blame History

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

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

目录

  1. 概述
  2. Standard 定义
  3. dimGuidelines 设计
  4. DIM_FILE_FILTERS 修改
  5. 其他代码修改
  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）

## 开发范式设计清晰度（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 字符串做模板求值：

// 在 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 匹配逻辑

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

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

// 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：

'开发范式设计清晰度': `检查以下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：

'规模、功能点、技术难度': `检查以下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 的匹配逻辑：

// 修改前（现有逻辑）
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 文件需要被"提效设计合理性"维度读取：

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

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

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

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

'规模、功能点、技术难度': (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 文件：

'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 调整

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

// 在硬规则循环中增加赛道二特殊规则
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 参数做分支逻辑：

'演示与文档': 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）。

'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 参数。

// 修改 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。实现方案：

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
Reference in New Issue View Git Blame Copy Permalink