first commit

2026-09-19 12:54:45 +08:00
commit 6fc5b64077
126 changed files with 8601 additions and 0 deletions
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-08-02
@@ -0,0 +1,71 @@
+# Design: init-promptcr-platform
+
+## Context
+
+仓库当前为空。本设计为"面向代码审查的大语言模型实验支撑平台"（PromptCR-Lab）从零搭建的技术方案。平台服务单研究者毕业设计场景，核心负载是 3 模型 × N 级提示词 × 12 commit × 3 重复的全因子对照实验（N=3 时 324 个单元），要求全流程自动化、结果可复现、Docker 一键部署。
+
+**硬约束**：Python 3.11 + FastAPI + Typer + SQLAlchemy + PostgreSQL + asyncio；前端 React 18 + Tailwind 3 + shadcn/ui + Vite + ECharts；基础设施仅允许 Docker / docker-compose / PostgreSQL / Nginx；密钥走环境变量；禁止重型多语言解析框架、禁止消息队列与 Redis。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 五模块（F1 数据集 / F2 模型适配 / F3 提示词 / F4 调度采集 / F5 分析）+ 接入层（F6）+ 前端（F7）的完整落地。
+- 三条解耦红线：模型接入 ↔ 提示词策略解耦；实验执行 ↔ 结果评价解耦；数据生产 ↔ 数据消费解耦。
+- 可复现性：采样参数随 run 持久化、重复实验独立 `run_id`、原始输出全量留痕、实验绑定模板版本且历史版本只读。
+- 本地开发与 Docker 两种运行方式均可用；后端 pytest 覆盖率 ≥90%。
+
+**Non-Goals:**
+- 用户系统、多租户、移动端、SSR。
+- 模型训练/微调、真实缺陷挖掘、缺陷自动修复。
+- 任意语言即插即用（只覆盖数据集实际语言）、RAG 等重型提示词策略。
+- 模型输出的模糊"猜测式"补救解析。
+
+## Decisions
+
+### D1 单体后端 + 分层模块，而非微服务
+单个 FastAPI 进程内按 `dataset / models / prompts / experiments / analysis` 划分包，模块间只通过标准数据接口（DTO/服务层函数）交互，禁止跨模块读内部实现、接入层与前端禁止直连数据库。
+- 备选：微服务/任务队列（Celery + Redis）——被约束显式排除；单机毕业设计场景无需此复杂度。
+
+### D2 asyncio 进程内调度，数据库即队列
+实验单元落库为 `experiment_runs`（status: pending/running/done/failed），调度器用 `asyncio.Semaphore` 按适配器并发额度取 pending 单元执行。**断点续跑 = 重启后扫描 pending/failed 可重试单元继续**，无需额外中间件。
+- 备选：RQ/Celery——引入 Redis，违反约束。
+
+### D3 三厂商统一 OpenAI 兼容适配器
+抽象基类 `ModelAdapter.chat(prompt, params) -> {text, token_usage, latency_ms}`；DeepSeek/Kimi/通义均基于 openai SDK，仅 `base_url / api_key / model` 配置不同；工厂按模型标识创建。并发信号量与指数退避重试器封装在基类，对上层透明。
+
+### D4 可插拔缺陷规则：目录扫描 + 注册表
+规则按语言组织为独立文件（如 `backend/dataset/rules/python/null_pointer.py`），每条规则实现统一接口（`detect_and_mutate(source) -> Mutation | None`，返回植入位置/类型/参考修复），框架启动时扫描目录自动注册。**所有语言的规则一律基于语法解析做 AST 级变换，不使用正则/纯文本级替换**：Python 用标准库 `ast`；Java 用 `javalang`（纯 Python 轻量 Java 解析器）；JavaScript 用 `esprima`（Python 移植版）。引入 `javalang`/`esprima` 属新增第三方依赖，按约束在代码注释与文档中说明理由（保证植入位置精确可知、缺陷语义真实）。若数据集后续纳入 TypeScript，再单独评估对应解析方案。仍禁止 tree-sitter / ANTLR 等重型多语言解析框架。新增规则文件即扩展，满足 A1b。
+
+### D5 提示词模板版本化存储于数据库
+`prompt_templates`（strategy_id, level）+ `prompt_template_versions`（version, body, variables_schema, created_at）。渲染走 `render(strategy_id, version, context)`；Web 编辑保存 = 插入新版本行，旧版本只读；`experiment_runs` 记录 `template_version_id` 保证 C1。
+
+### D6 五维指标半自动计算
+检出率/误报率/覆盖率：模型输出按约定结构（L2/L3 要求类型+行号）解析后与 Ground Truth 自动比对，解析失败标记失败并留原文（不猜测）。建议可操作性：前端录入李克特 1–5 分人工盲评结果，后端按"模型 × 级别"聚合均值+频数分布。稳定性：同一配置三次重复输出的指出项集合，两两（3 对）Jaccard 相似度取平均值。统计用 pandas + scipy（ANOVA、配对 t 检验）；论文图用 matplotlib（中文字体、统一样式），前端图用同口径 JSON + ECharts。
+
+### D7 前后端严格分离，Nginx 托管前端
+前端 Vite SPA 构建产物由 Nginx 托管并反代 `/api` 到后端；API 只返回 JSON。本地开发：后端 `uvicorn` 一条命令、前端 `vite dev` 一条命令；Docker：`docker compose up` 拉起 db + backend + frontend(nginx)，PG 数据挂 volume。
+
+### D8 核心数据模型
+- `samples`（commit 样本：repo、commit_sha、language、diff、上下文）
+- `defects`（预埋缺陷：sample 外键、类型、位置行号、参考修复）→ 与样本共同构成 Ground Truth
+- `prompt_templates` / `prompt_template_versions`
+- `experiments`（批次配置快照：模型集合、级别集合、样本集合、重复次数、采样参数）
+- `experiment_runs`（`run_id` 主键；外键关联实验、模型、模板版本、样本；重复序号、状态、重试次数、采样参数快照）
+- `results`（与 `experiment_runs` 一对一：原始输出、token、耗时、解析出的指出项、五维指标得分、李克特人工分）
+
+## Risks / Trade-offs
+
+- [模型输出不按约定结构返回，自动比对失败率高] → L2/L3 模板中强约束输出格式；解析失败标记失败留原文（B3），并在分析中区分"解析失败"与"未检出"。
+- [非 Python 语言的文本级缺陷变换可能产生不自然代码] → 规则内置语义校验（植入后位置精确可知、样本可编译性抽查）；数据集仅 12 样本，允许人工抽检修正规则。
+- [进程内调度在强杀后丢失 in-flight 状态] → run 状态先落库再执行；重启时将 running 但无结果的单元重置为 pending（B2）。
+- [真实 API 调用有费用与限流] → CLI 提供 1×1×1×1 冒烟配置；重试器指数退避 + 单单元失败不中断批次（B1）。
+- [单进程 asyncio 吞吐有限] → 可接受：实验总量数百单元，瓶颈在模型 API 而非本机。
+
+## Migration Plan
+
+全新项目，无迁移。首先初始化 Git 仓库（`.gitignore` 排除 `.env`、密钥、构建产物），按 M1–M7 里程碑推进（骨架 → F1 → F2/F3 → F4 → F5 → F7 → 测试/Docker/文档），每里程碑自验对应验收项，**验收通过后创建一个 Git commit 作为里程碑存档点**，再进入下一阶段。
+
+## Open Questions
+
+- 具体选用哪三个开源仓库（须覆盖 Python/Java/JS 且 commit 质量适合）——M2 启动时确定。
+- ~~输出稳定性的具体一致性度量~~ **已确定**：同一配置三次重复实验的输出指出项集合，计算两两（共 3 对）Jaccard 相似度后取平均值，作为该配置的输出稳定性得分。
@@ -0,0 +1,39 @@
+# Proposal: init-promptcr-platform
+
+## Why
+
+毕业设计研究需要开展"多模型 × 多提示词策略"的代码审查对照实验，目前缺少一个能覆盖**数据集构建 → 模型调用 → 结果采集 → 指标计算 → 图表产出**全流程自动化的实验支撑平台。手工执行 324+ 个实验单元不可行，且无法保证可复现性。本平台面向单研究者、Docker 一键部署、单机可运行。
+
+## What Changes
+
+从零搭建整个平台（仓库当前为空），包含以下新能力：
+
+- **数据集管理（F1）**：从开源 Git 仓库筛选 commit、提取 Unidiff、按可插拔缺陷规则预埋缺陷（Python 基于 `ast`，其他语言轻量变换）、生成 Ground Truth 标注；交付 12 个样本、覆盖 ≥3 种语言且分布均衡；缺陷规则可插拔（新增规则文件即可扩展，无需改框架代码）。
+- **模型接入（F2）**：适配器模式抽象基类 `ModelAdapter`，DeepSeek / Kimi / 通义千问三个适配器统一走 OpenAI 兼容格式；工厂模式创建；内置信号量并发控制与指数退避重试。
+- **提示词策略（F3）**：内置 L1（检测错误）→ L2（定位类型与行号）→ L3（修复建议）三级难度递增策略；Jinja2 模板配置化、带版本号；Web 在线编辑保存即新版本，历史版本只读；对外仅暴露 `render(strategy_id, version, context)`。
+- **实验调度与采集（F4）**：全因子矩阵 3 模型 × N 级 × 12 commit × 3 重复（N=3 时 324 单元），唯一 `run_id`；asyncio 异步队列五步流水线；失败重试 + 隔离 + 断点续跑；原始输出、token、耗时、状态全量落库。
+- **数据分析与可视化（F5）**：五维指标（缺陷检出率、误报率、审查覆盖率、建议可操作性李克特五级量表、输出稳定性）；描述性统计 + ANOVA + 配对 t 检验；matplotlib 论文静态图（热力图/箱线图/分组柱状图，支持中文）+ 前端 JSON 数据接口。
+- **后端接入层（F6）**：FastAPI RESTful API 与 Typer CLI 两种等价调用方式；API 兼作前端数据源。
+- **Web 前端（F7）**：React 18 + Tailwind CSS 3 + shadcn/ui + Vite，ECharts 唯一图表库；四个页面：数据集管理、实验配置（含模板在线编辑）、实验监控（进度/原始输出/断点续跑）、结果分析（交互图表 + 李克特打分录入）。
+- **部署**：后端/前端/PostgreSQL 各自容器化，`docker compose up` 一键拉起，PostgreSQL volume 持久化。
+
+## Capabilities
+
+### New Capabilities
+- `dataset-management`: Git 仓库解析、diff 提取、可插拔缺陷预埋、Ground Truth 标注与数据集交付
+- `model-adapters`: OpenAI 兼容格式的三厂商模型适配器、工厂创建、并发控制与重试
+- `prompt-strategies`: 分级提示词模板、版本管理、在线编辑、统一渲染接口
+- `experiment-orchestration`: 全因子实验矩阵生成、异步调度执行、结果落库、断点续跑
+- `analysis-metrics`: 五维评价指标计算、统计分析、论文图表与前端数据接口
+- `backend-access`: FastAPI RESTful API 与 Typer CLI 等价接入
+- `web-frontend`: React SPA 四页面、ECharts 图表、与后端仅经 API 交互
+
+### Modified Capabilities
+（无——仓库为空，全部为新增能力。）
+
+## Impact
+
+- **新增代码**：`backend/`（Python 3.11，FastAPI + SQLAlchemy + asyncio）、`frontend/`（React 18 + Vite）、`docker-compose.yml`、各服务 Dockerfile、README（含 ER 说明）。
+- **外部依赖**：PostgreSQL（唯一中间件）、三个大模型厂商 API（DeepSeek / Kimi / 通义千问，密钥走环境变量）。
+- **明确排除**：无用户系统、无移动端/SSR、无 MQ/Redis/K8s、不训练模型、不做真实缺陷挖掘与自动修复、不硬编码密钥、不覆盖历史模板版本、前端不直连数据库。
+- **验收基线**：功能 A1–A7、健壮性 B1–B4、可复现性 C1–C2、工程 D1–D4（含后端 pytest 覆盖率 ≥90%）。
@@ -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** 页面显示明确错误提示而非白屏
@@ -0,0 +1,70 @@
+# Tasks: init-promptcr-platform
+
+## 1. M1 项目骨架与基础设施
+
+- [x] 1.1 初始化 Git 仓库与 `.gitignore`（排除 `.env`、密钥、node_modules、构建产物）
+- [x] 1.2 创建后端目录结构（`backend/`，按 dataset / models / prompts / experiments / analysis / api / cli 分包）与单一 `requirements.txt`
+- [x] 1.3 创建前端骨架（Vite + React 18 + Tailwind CSS 3 + shadcn/ui，ECharts 依赖）
+- [x] 1.4 用 SQLAlchemy 定义核心表（samples、defects、prompt_templates、prompt_template_versions、experiments、experiment_runs、results）并建库迁移
+- [x] 1.5 编写配置管理（环境变量 / `.env` 读取密钥与连接串，零硬编码）
+- [x] 1.6 编写 docker-compose 骨架（db + backend + frontend/nginx）与各 Dockerfile，PostgreSQL 挂 volume
+- [x] 1.7 M1 自验后创建 git commit（里程碑存档点）
+
+## 2. M2 F1 数据集管理模块
+
+- [x] 2.1 实现 Git 解析（GitPython）：遍历提交历史并按"变更规模适中、语言分布均衡、提交信息完整"筛选候选 commit
+- [x] 2.2 实现 Unidiff 提取（保留变更前后文件上下文）并落库 samples
+- [x] 2.3 实现缺陷规则框架：统一规则接口 + 目录扫描注册表（按语言组织，新增文件即插拔）
+- [x] 2.4 实现 Python 内置规则（基于标准库 `ast` AST 级变换）：空指针引用、资源未关闭、边界条件错误（含边界条件错乱）、逻辑运算符误用、并发安全问题
+- [x] 2.5 实现 Java 内置规则（基于 `javalang` 解析做 AST 级变换，同类五型，位置精确可知，注释/文档说明引入理由，禁止正则/纯文本替换）
+- [x] 2.6 实现 JavaScript 内置规则（基于 `esprima` 解析做 AST 级变换，同类五型，位置精确可知，注释/文档说明引入理由，禁止正则/纯文本替换）
+- [x] 2.7 实现 Ground Truth 标注生成（缺陷位置/类型/参考修复/语言）落库 defects
+- [x] 2.8 构建并交付 12 个 commit 样本数据集（≥3 语言、分布均衡），自验 A1；新增一条自定义规则验证 A1b
+- [x] 2.9 M2 自验后创建 git commit（里程碑存档点）
+
+## 3. M3 F2 模型适配 + F3 提示词策略
+
+- [x] 3.1 实现 `ModelAdapter` 抽象基类（统一 `chat(prompt, params)` 返回审查文本 + token + 耗时，内置信号量并发控制与指数退避重试）
+- [x] 3.2 实现 DeepSeek / Kimi / 通义千问三适配器（统一 OpenAI 兼容格式，仅配置差异）与工厂模式，自验 A2
+- [x] 3.3 实现提示词模板存储与版本管理（模板表 + 版本表，旧版本只读）
+- [x] 3.4 内置 L1/L2/L3 三级 Jinja2 模板（含策略/级别标识、版本号、变量 schema）并实现 `render(strategy_id, version, context)`，自验 A3
+- [x] 3.5 M3 自验后创建 git commit（里程碑存档点）
+
+## 4. M4 F4 实验调度与结果采集
+
+- [x] 4.1 实现全因子矩阵生成（3 模型 × N 级 × 12 commit × 3 重复，唯一 run_id，采样参数快照落库），自验 A4
+- [x] 4.2 实现 asyncio 异步调度器（按并发额度分批，五步流水线：加载 diff → 渲染 → 调用 → 采集 → 落库更新进度）
+- [x] 4.3 实现失败重试、阈值隔离、单单元失败不中断批次，自验 B1
+- [x] 4.4 实现断点续跑（重启扫描 pending/中断单元继续，已完成不重复调用），自验 B2
+- [x] 4.5 实现异常输出处理（空/不合约定 → 标记失败留原文不崩溃、不猜测解析），自验 B3、C1、C2
+- [x] 4.6 全因子矩阵小规模真实跑通，自验 A5
+- [x] 4.7 M4 自验后创建 git commit（里程碑存档点）
+
+## 5. M5 F5 数据分析与可视化（后端）
+
+- [x] 5.1 实现输出解析与 Ground Truth 自动比对，计算检出率 / 误报率 / 覆盖率
+- [x] 5.2 实现李克特五级量表评分存储与"模型 × 级别"聚合（均值 + 频数分布）
+- [x] 5.3 实现输出稳定性度量（三次重复输出指出项集合两两 Jaccard 相似度取平均值）
+- [x] 5.4 实现统计分析（pandas + scipy：描述性统计、ANOVA、配对 t 检验）
+- [x] 5.5 实现 matplotlib 论文图（热力图 / 箱线图 / 分组柱状图，中文显示、样式统一）与前端同口径 JSON 接口，自验 A6
+- [x] 5.6 M5 自验后创建 git commit（里程碑存档点）
+
+## 6. M6 F6 接入层 + F7 Web 前端
+
+- [x] 6.1 实现 FastAPI RESTful API（数据集 / 模板 / 实验下发 / 进度 / 结果 / 统计 / 李克特打分），仅返回 JSON
+- [x] 6.2 实现 Typer CLI 与 API 等价（含 1×1×1×1 冒烟命令），自验 D4 等价性
+- [x] 6.3 实现数据集管理页（样本列表、Ground Truth 详情、构建入口）
+- [x] 6.4 实现实验配置页（模型/级别/样本/重复勾选、单元数量实时预览、模板在线编辑与新增），自验 A3b
+- [x] 6.5 实现实验监控页（批次进度、单条 run 状态与原始输出、断点续跑触发）
+- [x] 6.6 实现结果分析页（ECharts 热力图/箱线图/分组柱状图、维度筛选、李克特打分录入），自验 A7
+- [x] 6.7 实现前端三异常态（后端离线 / API 报错 / 数据为空）明确提示，自验 B4
+- [x] 6.8 M6 自验后创建 git commit（里程碑存档点）
+
+## 7. M7 测试、Docker 与文档收尾
+
+- [x] 7.1 后端 pytest + pytest-cov 覆盖率提升至 ≥90%，自验 D2
+- [x] 7.2 前端核心交互逻辑 Vitest 测试全部通过
+- [x] 7.3 Docker 全栈联调：`docker compose up` 一键可用、容器重建数据不丢，自验 D1b
+- [x] 7.4 密钥审计（仓库无硬编码密钥）
+- [x] 7.5 编写 README（安装、配置、本地与 Docker 两种启动、断点续跑方法、数据库 ER 说明），自验 D1、D3
+- [x] 7.6 M7 自验后创建 git commit（里程碑存档点）