BuddyDew/ai-code-evaluation-suite

# AI 代码评估套件 AI 代码评估套件是一款开源开发者工具，用于测试、解释和改进由人类和 AI 生成的 Python 代码。选择一个任务，提交源代码，即可获得由可见测试和隐藏测试支持的确定性报告。提交的代码会在一次性的、禁用网络连接的 Docker 容器中运行；FastAPI 服务器绝不会导入它。 该项目的存在是为了展示围绕评估系统的工程判断力：清晰的契约、真实的边缘情况、值得信赖的报告、故障处理、隔离以及客观的局限性。 ## 为什么这很重要 - **AI 生成的代码需要证据，而非看似合理。** 该套件将代码建议转化为可重复的结果，并由可见测试、隐藏测试统计和捕获的运行时证据提供支持。 - **评估应该是可检查的。** 确定性评分和结构化报告使得成功、失败和权衡在 UI、API 或 CI 工作流中易于审查。 - **不受信任的代码需要一个边界。** 提交的代码在具有资源限制的、禁用网络的一次性容器中运行，而 API 始终是受信任的控制平面。 ## 界面预览  桌面工作区将任务契约、提交的 Python 代码和评估证据集中展示。 | 通过的评估 | 具有指导意义的失败反馈 | | --- | --- | |  |  | | 包含可见和隐藏测试摘要的完整 `100/100` 运行。 | `70/100` 运行，识别失败的用例以及接下来需要审查的边缘情况。 | ## 评估报告示例 一个刻意不完整的回文提交仍然会产生一个有用的、机器可读的结果。为了提高可读性，此缩短后的响应保留了真实的评分、公开的失败证据、隐藏测试摘要和评估器反馈，同时省略了传输元数据： ``` { "task_id": "palindrome-normalization", "status": "completed", "score": 70, "score_breakdown": { "correctness": 50, "instruction_adherence": 10, "execution_signals": 10 }, "passed": false, "summary": "The solution passed 5 of 8 tests.", "hidden_test_summary": { "passed": 3, "failed": 1, "total": 4 }, "feedback": [ { "severity": "warning", "message": "Review the failing visible cases: Mixed punctuation and case, Only ignored characters." }, { "severity": "warning", "message": "1 hidden case(s) failed. Re-check edge cases in the Palindrome normalization contract." } ] } ``` 隐藏测试的实现细节保持私密；报告仅公开诊断行为所需的摘要，而不会泄露基准测试。 ## MVP 包含的内容 - 五个 Python 任务，包括 API 转换、重试和分页。 - 十个精心挑选的错误提交，带有明确的失败分类和变异风格的基准验证。 - 类型化的 FastAPI 任务和评估 endpoint。 - 可见的测试细节和隐藏测试总数，且不暴露隐藏的源代码。 - Docker 隔离，无网络连接，非 root 用户执行，资源限制，只读挂载，超时和清理。 - 响应式 Next.js 工作区，带有预填写的提交和结构化报告 UI。 - 评估器单元/API/集成测试、仪表板组件测试、代码检查、严格类型检查、生产构建以及 GitHub Actions CI。 - 架构、评分、安全、路线图和贡献文档。 ## 架构  monorepo 将浏览器、受信任的评估器、不受信任的运行时、任务内容和共享契约明显区分开。API 是受信任的控制平面；提交的代码绝不会在仪表板或评估器进程中执行。阅读完整的[架构和威胁模型指南](docs/architecture.md)。 ## 项目结构 ``` . ├── apps/dashboard/ # Next.js App Router UI ├── services/evaluator/ # FastAPI service and Docker orchestration ├── packages/shared-types/ # Public API TypeScript types ├── benchmarks/python/ # Five tasks and reference solutions ├── docker/runner/ # Minimal untrusted Python image ├── docs/ # Architecture, scoring, security, roadmap ├── .github/workflows/ci.yml └── docker-compose.yml ``` ## 环境要求 - Docker Desktop 或 Linux Docker daemon - 用于主机端评估器开发的 Python 3.12 或更高版本 - Node.js 22 或更高版本以及 npm 评估器镜像和提交运行器使用固定版本的 Python 3.12 基础镜像，因此完整的 Compose 工作流不依赖于主机端的 Python。 ## 使用 Docker Compose 快速开始 ``` docker compose up --build ``` 打开 `http://localhost:3000`。API 文档位于 `http://localhost:8000/docs`；健康检查位于 `http://localhost:8000/health`。 Compose 在启动评估器之前会构建运行器镜像。评估器仅为了创建一次性的提交容器而拥有对 Docker daemon 的访问权限。使用以下命令停止堆栈： ``` docker compose down ``` ## 本地开发 ### 1. 评估器 ``` python -m venv .venv ``` 激活它： ``` # macOS / Linux source .venv/bin/activate # Windows PowerShell .venv\Scripts\Activate.ps1 ``` 安装并构建沙箱镜像： ``` python -m pip install -e "services/evaluator[dev]" docker build -t ai-code-evaluator-runner:local -f docker/runner/Dockerfile . uvicorn ai_code_evaluator.api:app --reload --port 8000 ``` ### 2. 仪表板 在另一个终端中： ``` npm ci npm run dashboard:dev ``` 如果评估器不在 `http://localhost:8000`，请将 `apps/dashboard/.env.example` 复制到 `apps/dashboard/.env.local` 并修改 `NEXT_PUBLIC_EVALUATOR_URL`。 ## 评估示例 ``` curl -X POST http://localhost:8000/api/evaluations \ -H "Content-Type: application/json" \ -d '{ "task_id": "palindrome-normalization", "source_code": "def is_normalized_palindrome(value):\n normalized = [c.casefold() for c in value if c.isalnum()]\n return normalized == normalized[::-1]\n" }' ``` 响应包含评分及其明细、可见用例结果、隐藏通过/失败总数、运行时、输出流和反馈。隐藏测试的名称、输入、预期值和源代码不会出现。 ## 开发检查 ``` ruff check services/evaluator ruff format --check services/evaluator mypy services/evaluator/src pytest services/evaluator/tests npm run dashboard:lint npm run dashboard:typecheck npm run dashboard:test npm run dashboard:build ``` 标记为 Docker 的测试在 daemon 或运行器镜像不可用时会跳过。CI 会构建镜像并运行它们。 ## 评估模型 分数由 80% 的功能正确性、10% 的指令依从性和 10% 的基本执行信号组成。每个信号都是客观且有据可查的；本项目并不宣称这是一个完整的代码质量度量标准。请参阅 [evaluation-model.md](docs/evaluation-model.md)。 基准质量是针对看似合理的错误提交进行验证的，而不仅仅是参考解决方案。请参阅 [benchmark-quality.md](docs/benchmark-quality.md)。 ## 安全模型 运行器禁用网络连接，使用非 root 用户和只读挂载，丢弃 capabilities，防止权限提升，并应用 CPU、内存、PID 和实际时间限制。这些控制措施使其适用于本地演示，但对于充满敌意的公共多租户环境并不安全。Docker socket、共享内核和隐藏测试的暂存模型是重要的残余风险。在公开评估器之前，请阅读 [security.md](docs/security.md)。 ## API endpoint | 方法 | 路径 | 用途 | | --- | --- | --- | | `GET` | `/health` | 服务和运行器可用性 | | `GET` | `/api/tasks` | 公共任务目录 | | `GET` | `/api/tasks/{task_id}` | 说明、起始代码和可见用例 | | `POST` | `/api/evaluations` | 运行提交并返回报告 | FastAPI 在 `/openapi.json` 发布确切的 OpenAPI schema。检入的 schema 和生成的 TypeScript 契约会在 CI 中进行偏差验证。 ## 技术 - Python 3.12, FastAPI, Pydantic, pytest, Ruff 和 mypy - Docker 和 Docker Compose - Next.js App Router, React, TypeScript 和 Tailwind CSS - Vitest, Testing Library, Biome 和 GitHub Actions ## 路线图 当前的里程碑有意停留在评估器 MVP 阶段。计划阶段涵盖损坏的存储库调试基准测试、与供应商无关的迭代编码 agent，以及持久化历史/比较功能。请参阅 [roadmap.md](docs/roadmap.md)。 ## 贡献与许可 在添加任务或更改评分语义之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。该项目基于 [MIT License](LICENSE) 提供。

标签：AI代码评估, AV绕过, Docker隔离, FastAPI, Python, SOC Prime, 安全规则引擎, 开发工具, 无后门, 版权保护, 请求拦截, 逆向工具