first commit
This commit is contained in:
eeymoo
@@ -0,0 +1,59 @@
|
||||
# Spec: analysis-metrics
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 缺陷检出率（Recall）
|
||||
系统 SHALL 计算缺陷检出率：模型正确指出的预埋缺陷数 ÷ 预埋缺陷总数；模型输出与 Ground Truth 自动比对，位置命中 + 类型匹配视为检出。
|
||||
|
||||
#### Scenario: 自动比对计算 Recall
|
||||
- **WHEN** 一个 run 的输出解析成功
|
||||
- **THEN** 系统与 Ground Truth 比对并计算该 run 的检出率
|
||||
|
||||
### Requirement: 误报率（FPR）
|
||||
系统 SHALL 计算误报率：模型指出的"问题"中未命中任何预埋缺陷的比例。
|
||||
|
||||
#### Scenario: 计算 FPR
|
||||
- **WHEN** 模型指出了若干问题项
|
||||
- **THEN** 系统计算其中未命中任何预埋缺陷的比例
|
||||
|
||||
### Requirement: 审查覆盖率
|
||||
系统 SHALL 计算审查覆盖率：模型指出的问题行号对预埋缺陷行号的覆盖程度。
|
||||
|
||||
#### Scenario: 计算覆盖率
|
||||
- **WHEN** 模型输出包含指出问题的行号
|
||||
- **THEN** 系统计算其对预埋缺陷行号的覆盖程度
|
||||
|
||||
### Requirement: 建议可操作性（李克特五级量表）
|
||||
系统 SHALL 支持研究者按统一 rubric 对每条修复建议人工盲评打分（1 不可操作 / 2 方向性 / 3 部分可操作 / 4 基本可操作 / 5 完全可操作），并按"模型 × 提示词级别"聚合计算算术均值与各等级频数分布。
|
||||
|
||||
#### Scenario: 录入并聚合李克特评分
|
||||
- **WHEN** 研究者在分析页录入某条建议的 1–5 分评分
|
||||
- **THEN** 系统保存评分并按模型 × 级别聚合输出均值与频数分布
|
||||
|
||||
### Requirement: 输出稳定性
|
||||
系统 SHALL 计算输出稳定性：同一配置三次重复实验输出的一致性度量，具体为三次输出的指出项集合两两（共 3 对）Jaccard 相似度的平均值。
|
||||
|
||||
#### Scenario: 三次重复稳定性
|
||||
- **WHEN** 同一配置的三个独立 run_id 均有结果
|
||||
- **THEN** 系统计算三个指出项集合两两 Jaccard 相似度并取平均值作为稳定性得分
|
||||
|
||||
### Requirement: 统计分析
|
||||
系统 SHALL 提供描述性统计、方差分析（ANOVA）与配对 t 检验（pandas + scipy）。
|
||||
|
||||
#### Scenario: 统计检验输出
|
||||
- **WHEN** 对实验结果发起统计分析
|
||||
- **THEN** 系统输出描述性统计、ANOVA 与配对 t 检验结果
|
||||
|
||||
### Requirement: 论文用静态图
|
||||
系统 SHALL 用 matplotlib 生成交叉对比热力图、箱线图、分组柱状图，样式统一、支持中文显示、可直接插入学位论文。
|
||||
|
||||
#### Scenario: 生成三类论文图
|
||||
- **WHEN** 研究者触发论文图表导出
|
||||
- **THEN** 系统产出热力图、箱线图、分组柱状图三类图片文件
|
||||
|
||||
### Requirement: 前端数据接口
|
||||
系统 SHALL 以 JSON 形式向前端提供与静态图同口径的统计数据，供 ECharts 渲染交互图表；所有指标计算 MUST 在后端完成，前端 MUST NOT 内置业务计算。
|
||||
|
||||
#### Scenario: 同口径 JSON 数据
|
||||
- **WHEN** 前端按模型/提示词级别/语言维度请求统计数据
|
||||
- **THEN** 后端返回同口径 JSON，前端仅做渲染与筛选交互
|
||||
@@ -0,0 +1,42 @@
|
||||
# Spec: backend-access
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: RESTful API 与 CLI 等价接入
|
||||
系统 SHALL 提供 FastAPI RESTful API 与 Typer CLI 两种等价调用方式；对同一实验配置，二者 MUST 产生等价的执行结果与一致的落库结构。
|
||||
|
||||
#### Scenario: API 与 CLI 等价
|
||||
- **WHEN** 分别通过 API 与 CLI 下发同一实验配置
|
||||
- **THEN** 二者落库结构一致、执行结果等价
|
||||
|
||||
### Requirement: API 作为前端唯一数据源
|
||||
API SHALL 承担 Web 前端的数据源职责：前后端分离，前端只通过 API 与后端交互；API MUST NOT 返回任何 HTML；前端 MUST NOT 直连数据库；接入层 MUST NOT 跨层直接写库绕过服务层。
|
||||
|
||||
#### Scenario: 前端仅经 API 取数
|
||||
- **WHEN** 前端任意页面加载数据或下发指令
|
||||
- **THEN** 全部经由 RESTful API JSON 交互，无模板渲染混排
|
||||
|
||||
### Requirement: 本地与 Docker 两种启动方式
|
||||
系统 SHALL 支持两种运行方式：本地开发（后端一条命令、前端一条命令分别启动）；Docker（`docker compose up` 一条命令拉起 PostgreSQL + 后端 + 前端，PostgreSQL 数据 volume 持久化，容器重建不丢实验数据）。
|
||||
|
||||
#### Scenario: Docker 一键拉起
|
||||
- **WHEN** 执行 `docker compose up`
|
||||
- **THEN** db + backend + frontend(nginx) 全部启动，浏览器访问即可使用
|
||||
|
||||
#### Scenario: 容器重建数据不丢
|
||||
- **WHEN** 删除并重建容器后重新启动
|
||||
- **THEN** 历史实验数据仍在（volume 持久化）
|
||||
|
||||
### Requirement: CLI 冒烟实验
|
||||
CLI SHALL 支持一条命令跑通小规模冒烟实验（如 1 模型 × L1 × 1 commit × 1 重复）。
|
||||
|
||||
#### Scenario: 冒烟实验
|
||||
- **WHEN** 通过 CLI 下发 1×1×1×1 配置
|
||||
- **THEN** 生成 1 个实验单元并执行落库
|
||||
|
||||
### Requirement: 基础设施白名单
|
||||
系统 MUST NOT 引入消息队列（RabbitMQ/Kafka）、Redis、Kubernetes 等未列明中间件；允许且仅允许 Docker/docker-compose、PostgreSQL、Nginx（仅托管前端静态文件与反向代理）。新增第三方依赖前须在代码注释或文档中说明理由。
|
||||
|
||||
#### Scenario: 依赖检查
|
||||
- **WHEN** 审查部署与依赖清单
|
||||
- **THEN** 不存在白名单之外的中间件，新增依赖均有理由说明
|
||||
@@ -0,0 +1,49 @@
|
||||
# Spec: dataset-management
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Git 仓库解析与候选 commit 筛选
|
||||
系统 SHALL 接受开源 Git 仓库地址作为输入，遍历提交历史，按"变更规模适中、语言分布均衡、提交信息完整"规则筛选候选 commit。
|
||||
|
||||
#### Scenario: 筛选候选 commit
|
||||
- **WHEN** 用户提供开源 Git 仓库地址并触发数据集构建
|
||||
- **THEN** 系统遍历提交历史并输出符合筛选规则的候选 commit 列表
|
||||
|
||||
### Requirement: Unidiff 提取
|
||||
系统 SHALL 为每个入选 commit 提取统一 Unidiff 格式变更文本，并保留变更前后文件上下文。
|
||||
|
||||
#### Scenario: 提取 diff 与上下文
|
||||
- **WHEN** 一个 commit 被选中为样本
|
||||
- **THEN** 系统产出 Unidiff 变更文本及变更前后文件上下文并持久化
|
||||
|
||||
### Requirement: 可插拔缺陷预埋
|
||||
系统 SHALL 按可插拔缺陷规则在真实 diff 中预埋缺陷。内置缺陷类型 MUST 至少包括：空指针引用、资源未关闭、边界条件错误（含边界条件错乱）、逻辑运算符误用、并发安全问题。每种缺陷 MUST 为一条独立规则文件并按语言组织；用户新增规则文件即可自定义缺陷类型而无需改动框架代码。所有语言的规则 MUST 基于语法解析做 AST 级变换，MUST NOT 使用正则/纯文本级替换：Python 用标准库 `ast`；Java 用 `javalang`；JavaScript 用 `esprima`（新增依赖须在代码注释或文档中说明理由）。禁止引入重型多语言解析框架（如 tree-sitter、ANTLR）。无论内置或自定义规则，植入位置 MUST 精确可知。
|
||||
|
||||
#### Scenario: 内置规则预埋缺陷
|
||||
- **WHEN** 对一个样本执行缺陷预埋
|
||||
- **THEN** 系统按适用语言的规则植入缺陷，并记录缺陷类型与精确植入位置
|
||||
|
||||
#### Scenario: 自定义规则即插即用
|
||||
- **WHEN** 用户新增一条自定义缺陷规则文件且不改动框架代码
|
||||
- **THEN** 新样本可预埋该自定义缺陷并被正确标注
|
||||
|
||||
### Requirement: Ground Truth 标注
|
||||
系统 SHALL 为每个样本生成含缺陷位置、缺陷类型、参考修复建议、语言类型的 Ground Truth 记录。
|
||||
|
||||
#### Scenario: 生成 Ground Truth
|
||||
- **WHEN** 缺陷预埋完成
|
||||
- **THEN** 系统产出与预埋一致的 Ground Truth 记录（缺陷类型/位置/参考修复/语言），抽查可复验
|
||||
|
||||
### Requirement: 实验数据集交付
|
||||
系统 SHALL 交付 12 个 commit 样本的实验数据集，覆盖至少 3 种主流编程语言且语言分布均衡。
|
||||
|
||||
#### Scenario: 数据集构建完成
|
||||
- **WHEN** 数据集构建流程结束
|
||||
- **THEN** 产出 12 个带标注样本，覆盖 ≥3 种语言且分布均衡
|
||||
|
||||
### Requirement: 排除真实缺陷挖掘
|
||||
系统 MUST NOT 做真实缺陷的自动挖掘（不做静态分析告警收集、不做历史 bug commit 自动识别），缺陷一律采用预埋方式。
|
||||
|
||||
#### Scenario: 仅预埋来源
|
||||
- **WHEN** 检查数据集中任意缺陷记录
|
||||
- **THEN** 该缺陷均来源于内置或自定义预埋规则，且有对应规则标识
|
||||
@@ -0,0 +1,45 @@
|
||||
# Spec: experiment-orchestration
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 全因子实验矩阵生成
|
||||
系统 SHALL 根据实验配置生成全因子实验矩阵：3 模型 × N 级提示词 × 12 commit × 3 次重复（N 为当前启用的提示词级别数），每个单元具有唯一 `run_id`。
|
||||
|
||||
#### Scenario: 生成 324 个单元
|
||||
- **WHEN** 配置 3 模型 × 3 级别 × 12 commit × 3 重复并创建实验
|
||||
- **THEN** 系统生成恰好 324 个实验单元且各自 `run_id` 唯一
|
||||
|
||||
### Requirement: 异步调度执行
|
||||
系统 SHALL 基于 asyncio 的异步任务队列，按适配层并发额度分批执行实验单元。单次实验为五步流水线：加载样本 diff → 渲染提示词 → 调用模型适配层 → 采集原始结果 → 落库并更新进度。
|
||||
|
||||
#### Scenario: 批次执行完毕
|
||||
- **WHEN** 一批实验单元被调度执行
|
||||
- **THEN** 全部单元执行完毕（允许重试），进度实时更新
|
||||
|
||||
### Requirement: 完整调用记录落库
|
||||
系统 SHALL 完整记录每次调用：模型标识、策略标识与版本、commit 标识、重复序号、原始输出、token 用量、耗时、调用状态。模型采样参数（温度等）MUST 固定并随 run 记录持久化；每次重复实验 MUST 使用独立 `run_id`；原始输出 MUST 全量留痕。
|
||||
|
||||
#### Scenario: 还原历史实验
|
||||
- **WHEN** 查询任意一次历史实验的数据库记录
|
||||
- **THEN** 可还原其模型、采样参数、提示词模板及版本、样本与原始输出
|
||||
|
||||
### Requirement: 失败重试与隔离
|
||||
失败调用 SHALL 按指数退避自动重试；超过阈值标记失败并隔离；单个实验单元失败 MUST NOT 中断整体批次。
|
||||
|
||||
#### Scenario: 单单元失败不中断批次
|
||||
- **WHEN** 人为制造 API 限流/超时导致部分单元持续失败
|
||||
- **THEN** 失败单元重试后被标记失败并隔离，其余单元正常完成
|
||||
|
||||
### Requirement: 断点续跑
|
||||
系统 SHALL 支持断点续跑：批次执行中进程被强杀后重启，能从断点继续，已完成单元 MUST NOT 重复调用模型。
|
||||
|
||||
#### Scenario: 强杀后续跑
|
||||
- **WHEN** 批次执行到一半强杀进程并重启
|
||||
- **THEN** 系统从断点续跑，已完成单元不重复调用模型
|
||||
|
||||
### Requirement: 异常输出处理
|
||||
模型返回空内容或不合约定结构的内容时，该单元 SHALL 被标记为失败/无效并保留原文，MUST NOT 导致程序崩溃，MUST NOT 做模糊补救式猜测解析。
|
||||
|
||||
#### Scenario: 不合约定输出
|
||||
- **WHEN** 模型返回无法按约定结构解析的内容
|
||||
- **THEN** 该单元标记失败/无效并保留原文，批次继续
|
||||
@@ -0,0 +1,38 @@
|
||||
# Spec: model-adapters
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 统一模型适配器抽象
|
||||
系统 SHALL 定义抽象基类 `ModelAdapter`，统一 `chat(prompt, params)` 接口，返回结构固定为：审查文本 + token 用量 + 耗时。
|
||||
|
||||
#### Scenario: 统一返回结构
|
||||
- **WHEN** 任一适配器完成一次调用
|
||||
- **THEN** 返回结构包含审查文本、token 用量与耗时三个字段
|
||||
|
||||
### Requirement: 三厂商 OpenAI 兼容适配器
|
||||
系统 SHALL 实现 DeepSeek、Kimi、通义千问三个适配器，三者 MUST 统一按 OpenAI 兼容格式对接（统一 base_url + api_key + model 调用约定，可基于 OpenAI SDK），厂商差异只允许体现在配置项上，MUST NOT 为某厂商单独发明调用协议。
|
||||
|
||||
#### Scenario: 真实 API 调用
|
||||
- **WHEN** 配置好任一厂商的 base_url 与 api_key 后发起调用
|
||||
- **THEN** 该适配器以 OpenAI 兼容格式完成一次真实调用并返回统一结构
|
||||
|
||||
### Requirement: 工厂模式创建模型实例
|
||||
系统 SHALL 通过工厂按配置创建模型实例，上层只传模型标识即可运行时切换。
|
||||
|
||||
#### Scenario: 运行时切换模型
|
||||
- **WHEN** 上层以不同模型标识请求模型实例
|
||||
- **THEN** 工厂返回对应厂商的适配器实例，上层代码无需改动
|
||||
|
||||
### Requirement: 并发控制与指数退避重试
|
||||
适配层 SHALL 内置基于信号量的并发控制器与指数退避重试器，限流与网络抖动对上层透明。
|
||||
|
||||
#### Scenario: 限流自动重试
|
||||
- **WHEN** API 返回限流或超时错误
|
||||
- **THEN** 适配器自动按指数退避重试，超过阈值后向上报告失败
|
||||
|
||||
### Requirement: 密钥管理
|
||||
系统 MUST NOT 在代码中硬编码任何 API Key；密钥一律走环境变量或 `.env`，不入库、不进 Git、不进前端 bundle。
|
||||
|
||||
#### Scenario: 密钥来源检查
|
||||
- **WHEN** 检查仓库代码与前端构建产物
|
||||
- **THEN** 不存在任何硬编码密钥，密钥仅从环境变量或 `.env` 读取
|
||||
@@ -0,0 +1,35 @@
|
||||
# Spec: prompt-strategies
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 难度递增的内置提示词级别
|
||||
系统 SHALL 内置至少 3 级难度逐级升高的提示词策略：L1 直接指令（仅要求检测代码变更中的错误）；L2 增强指令（要求指出错误类型与具体行号）；L3 增强指令（在 L2 基础上要求给出修复建议）。策略从简，MUST NOT 涉及 RAG、检索增强等重型策略。L4+ 允许后续扩展但本期非必需。
|
||||
|
||||
#### Scenario: 按级别渲染提示词
|
||||
- **WHEN** 用同一份 diff 分别渲染 L1/L2/L3 模板
|
||||
- **THEN** 三份提示词各自符合级别特征且完整可发送
|
||||
|
||||
### Requirement: Jinja2 模板配置化
|
||||
每级提示词 SHALL 以 Jinja2 模板配置化存储，模板携带策略/级别标识、版本号与变量 schema。
|
||||
|
||||
#### Scenario: 模板元数据完整
|
||||
- **WHEN** 读取任一内置模板
|
||||
- **THEN** 其包含策略/级别标识、版本号与变量 schema
|
||||
|
||||
### Requirement: 模板版本管理与在线编辑
|
||||
模板 SHALL 可在 Web 配置页面在线编辑；保存即生成新版本号；历史实验记录始终绑定其执行时的模板版本；已存在版本只读、MUST NOT 被覆盖。用户可新增自定义提示词模板。
|
||||
|
||||
#### Scenario: 编辑生成新版本
|
||||
- **WHEN** 用户在配置页编辑一个已有模板并保存
|
||||
- **THEN** 系统生成新版本号，旧版本保持只读，历史实验仍显示其执行时的旧版本内容
|
||||
|
||||
#### Scenario: 新增自定义模板
|
||||
- **WHEN** 用户在配置页新增自定义模板
|
||||
- **THEN** 新实验可选用该模板/新版本
|
||||
|
||||
### Requirement: 统一渲染接口
|
||||
模块对外 SHALL 只暴露 `render(strategy_id, version, context)` 渲染接口。
|
||||
|
||||
#### Scenario: 经统一接口渲染
|
||||
- **WHEN** 调用方以 strategy_id、version 与上下文调用 render
|
||||
- **THEN** 返回按指定版本模板渲染后的提示词文本
|
||||
@@ -0,0 +1,53 @@
|
||||
# Spec: web-frontend
|
||||
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: 技术栈固定
|
||||
前端 SHALL 为独立 SPA，技术栈固定为 React 18 + Tailwind CSS 3 + shadcn/ui + Vite；图表 MUST 一律使用 ECharts 渲染，全项目统一，MUST NOT 混用其他图表库；与后端仅通过 RESTful API 通信，禁止模板渲染混排；不做移动端适配与 SSR，不做用户系统。
|
||||
|
||||
#### Scenario: 技术栈合规
|
||||
- **WHEN** 审查前端依赖与页面实现
|
||||
- **THEN** 仅使用规定技术栈，图表库只有 ECharts
|
||||
|
||||
### Requirement: 数据集管理页
|
||||
系统 SHALL 提供数据集管理页：样本列表、Ground Truth 详情（缺陷类型/位置/语言/参考修复）、数据集构建入口。
|
||||
|
||||
#### Scenario: 查看样本与标注
|
||||
- **WHEN** 用户打开数据集管理页
|
||||
- **THEN** 可浏览样本列表并查看每个样本的 Ground Truth 详情，可触发数据集构建
|
||||
|
||||
### Requirement: 实验配置页
|
||||
系统 SHALL 提供实验配置页：勾选模型集合、提示词级别集合、样本集合、重复次数，实时预览将生成的实验单元数量；提示词模板在本页可查看与在线编辑（编辑保存 = 新版本），并可新增自定义提示词模板。
|
||||
|
||||
#### Scenario: 实时预览单元数量
|
||||
- **WHEN** 用户勾选 3 模型、3 级别、12 样本、3 重复
|
||||
- **THEN** 页面实时预览将生成 324 个实验单元
|
||||
|
||||
#### Scenario: 在线编辑模板
|
||||
- **WHEN** 用户编辑已有模板并保存
|
||||
- **THEN** 生成新版本号，历史实验记录仍显示旧版本内容
|
||||
|
||||
### Requirement: 实验监控页
|
||||
系统 SHALL 提供实验监控页：批次进度（总数/完成/失败）、单条 run 状态与原始输出查看、断点续跑触发。
|
||||
|
||||
#### Scenario: 监控与续跑
|
||||
- **WHEN** 用户打开实验监控页
|
||||
- **THEN** 可见批次进度与单条 run 状态/原始输出，并可触发断点续跑
|
||||
|
||||
### Requirement: 结果分析页
|
||||
系统 SHALL 提供结果分析页：五维指标的 ECharts 交互式交叉对比图表（热力图、箱线图、分组柱状图），支持按模型/提示词级别/语言维度筛选；并提供李克特量表人工打分录入界面。
|
||||
|
||||
#### Scenario: 交互图表与筛选
|
||||
- **WHEN** 用户在分析页按维度筛选
|
||||
- **THEN** ECharts 图表按筛选条件刷新展示五维指标
|
||||
|
||||
#### Scenario: 李克特打分录入
|
||||
- **WHEN** 用户在分析页对某条修复建议录入 1–5 分
|
||||
- **THEN** 评分提交后端保存并反映到聚合统计
|
||||
|
||||
### Requirement: 异常态展示
|
||||
前端 SHALL 在后端离线、API 报错、数据为空三种情况下均有明确提示，MUST NOT 出现白屏或假死。
|
||||
|
||||
#### Scenario: 后端离线提示
|
||||
- **WHEN** 后端不可达
|
||||
- **THEN** 页面显示明确错误提示而非白屏
|
||||
Reference in New Issue
Block a user