| 项目 | 定义 |
|---|---|
| 产品名称 | 辩证熔炉 DialecticForge |
| 产品类型 | AI 驱动的工业级工程能力训练 SaaS / 开源训练靶场 |
| 产品目标 | 训练开发者在真实工程约束下高密度调用 API、形成语法肌肉记忆、通过事故复盘建立底层理解 |
| 核心机制 | 代码实战 + 极限压测 + AI Code Review + 线上灾难拷问 + 技能地图推进 |
| 目标用户 | 初中级工程师、进阶型 Python/Go/Rust/Java 开发者、企业内部训练营、技术面试训练平台 |
| 首版定位 | 全 Python 工业级训练靶场，优先服务 Python API、异步编程、并发、文件流、网络请求、数据处理等场景 |
| 差异化结论 | 普通平台训练“能不能写对”，DialecticForge 训练“能不能在生产环境活下来” |
| 原则 | 产品化解释 | 系统约束 |
|---|---|---|
| 代码是打出来的，不是看出来的 | 用户必须亲手补全 TODO，不能只看讲解 | 平台不直接输出最终答案，只输出骨架、约束、压测 |
| 高密度 API 轰炸 | 每个关卡围绕 1 个核心 API 群，覆盖正常调用、毒药参数、边界返回、异常恢复 | 任务生成器必须强制生成 API 兵器谱 |
| 强制语法肌肉记忆 | 每关绑定 1-2 个目标语言高级特性 | 判题器和 AI Review 必须检查是否使用指定语法 |
| 快思考阶段剥夺源码阅读权 | 初始任务只给输入、输出、副作用、错误行为，不给底层源码解释 | GENERATION 阶段禁止输出源码原理和完整答案 |
| 慢思考阶段残酷拷问 | 代码通过后才触发底层事故复盘 | DISASTER_SIMULATION 只能在测试和 Review 通过后进入 |
| 不跨阶段 | 必须等待用户完成当前阶段，不能一次性输出全流程 | LangGraph 状态机强制阶段锁定 |
| Show me the code | 所有训练最终落到可运行代码和可验证压测 | 每关必须带可本地运行的 QA Crucible |
V6.0 提示词的本质是一个严格的人机交互协议。产品化之后，它不应该由用户手动复制 Prompt 驱动，而应该被固化为后端状态机。
| Prompt 阶段 | SaaS 状态 | 系统行为 | 是否调用 LLM |
|---|---|---|---|
| 阶段零：地图注入与战前确认 | BOOTSTRAP / NODE_CONFIRMATION |
等待用户选择学习节点，例如 Python async generator、contextlib、FastAPI dependency |
低频调用或不调用 |
| 阶段一：下发工业级军令状 | TASK_GENERATION |
生成 Hardcore Industrial Schema、代码骨架、测试代码、语法约束 | 调用 |
| 阶段二：提交 PR | CODING_WAIT / RUNNING_CRUCIBLE |
用户手写 TODO，系统执行压测，失败则返回日志 | 不调用或低频调用 |
| 阶段三：Code Review & 事故拷问 | AI_REVIEW / DISASTER_SIMULATION / SOCRATIC_TRIAL |
Review 代码质量，生成线上事故，逼问根因与 Hotfix | 调用 |
| 阶段四：里程碑拔旗 | MILESTONE_ACHIEVED |
更新技能地图、记录薄弱点、解锁下一节点 | 调用或规则执行 |
关键设计结论：AI 不应该全程在线。 AI 只在任务生成、PR Review、事故模拟、复盘评估四个关键节点出现。用户编码、运行压测、查看错误日志阶段应该由普通后端和执行器完成，以降低 Token 成本、提升响应速度，并避免平台退化为“聊天套壳”。
用户进入平台后，不是看到“题目列表”，而是进入一个类似工程战区的学习地图。每个节点对应一个明确工程技能，例如：
| 技能节点 | API 训练目标 | 强制语法特性 | 典型事故 |
|---|---|---|---|
| Python 文件流式处理 | open, read, iter, pathlib.Path |
with 上下文管理器、生成器 yield |
大文件一次性读取导致 OOM |
| Python 异步任务调度 | asyncio.create_task, gather, wait_for |
async/await、异步上下文管理器 |
协程泄漏、任务未取消 |
| FastAPI 依赖注入 | Depends, Request, BackgroundTasks |
类型注解、依赖函数组合 | 请求级状态污染 |
| SQLAlchemy 会话管理 | Session, commit, rollback |
上下文管理器、异常恢复 | 连接池耗尽、事务悬挂 |
| Redis 缓存防击穿 | get, set, setnx, expire |
装饰器、闭包 | 缓存雪崩、锁未释放 |
| 日志解析与聚合 | re, json, collections.Counter |
生成器、模式匹配 | 正则灾难性回溯 |
一次完整训练流程如下：
| 步骤 | 用户动作 | 系统动作 | 通过条件 |
|---|---|---|---|
| 1 | 选择学习节点 | 系统进入战前确认 | 用户点击“开干” |
| 2 | 阅读军令状 | 系统展示 API 兵器谱、语法约束、代码骨架 | 用户理解输入输出与副作用 |
| 3 | 手写 TODO | 用户只能修改 TODO 区域 | 代码语法合法 |
| 4 | 点击 Run | 执行 QA Crucible | 所有测试通过 |
| 5 | 提交 PR | AI Review 代码 | 无明显代码异味，符合语法约束 |
| 6 | 接收事故日志 | AI 生成线上灾难 | 用户进入复盘 |
| 7 | 回答根因与 Hotfix | AI 追问并评分 | 底层解释合格 |
| 8 | 拔旗 | 系统更新学习地图 | 节点完成 |
平台中的每一道题都必须由统一结构生成，不能自由散文式输出。该结构既是用户看到的任务模板，也是后端数据模型的基础。
| Schema 区块 | 产品含义 | 后端字段 |
|---|---|---|
0. 军令状与 API 兵器谱 |
场景、黑盒直觉、核心 API、毒药参数、极端返回 | scenario, api_briefing, dangerous_params, edge_returns |
1. 弹药库准备 |
合法 import、依赖限制、禁止库 | allowed_imports, blocked_imports |
2. 死亡实战场 |
反面教材、TODO 任务、函数签名 | rookie_code, skeleton_code, todo_contract |
3. 极限 QA 压测 |
可运行测试代码、断言、异常模拟 | test_code, test_cases, mock_failure_cases |
4. PR Review 规则 |
代码质量、复杂度、语法约束检查项 | review_rubric |
5. 灾难模拟规则 |
可触发的事故类型与根因方向 | disaster_seed, expected_root_cause |
6. 里程碑判定 |
通过标准、技能地图更新规则 | milestone_rule |
平台生成任务时，必须严格输出一份结构化 TaskPackage，前端再将其渲染为军令状界面，而不是直接把 LLM Markdown 原样作为业务对象。
DialecticForge 的系统架构应拆成五层：前端战场、API 服务、费曼状态机、判题熔炉、数据与技能地图。
| 层级 | 模块 | 技术选型 | 职责 |
|---|---|---|---|
| 前端战场 | Battlefield UI | Reflex MVP，后续 React + Monaco | 展示任务、代码编辑、日志、事故拷问、技能地图 |
| API 服务 | Gateway | FastAPI | 会话管理、任务接口、判题接口、PR 提交、流式输出 |
| 费曼状态机 | Feynman Engine | LangGraph | 强制阶段流转，防止跨阶段输出 |
| 判题熔炉 | Crucible Executor | Celery + Redis + subprocess | 异步运行代码、捕获日志、超时截断 |
| AI 教官 | Devil Agent | LLM Provider | 生成任务、Review、事故模拟、复盘评分 |
| 数据层 | Memory Store | SQLAlchemy + SQLite/PostgreSQL | 用户、会话、提交、任务、事故、技能地图 |
| 安全层 | Safety Guard | AST 检查、黑名单、超时限制 | MVP 级安全执行，后续升级容器隔离 |
状态机必须强制执行 V6.0 的纪律：不能一次性输出完整答案，不能提前进入事故复盘，不能在用户未提交代码时主动 Review，不能在代码未通过压测时进入里程碑。
| 状态 | 描述 | 进入条件 | 退出条件 |
|---|---|---|---|
BOOTSTRAP |
魔鬼教官上线，只要求用户出示学习节点 | 用户进入训练页 | 用户选择技能节点 |
NODE_CONFIRMATION |
确认学习节点与语言 | 已选择节点 | 用户点击“开干” |
TASK_GENERATION |
生成 Hardcore Industrial Schema | 用户发令开干 | 任务包生成成功 |
CODING_WAIT |
用户手写 TODO，AI 休眠 | 任务下发完成 | 用户点击 Run 或 Submit PR |
RUNNING_CRUCIBLE |
执行 QA 压测 | 用户点击 Run | 测试完成 |
CRUCIBLE_FAILED |
返回失败日志 | 测试失败 | 用户修改代码后重新 Run |
PR_READY |
测试通过，允许提交 PR | 所有测试通过 | 用户提交 PR |
AI_REVIEW |
检查代码质量与语法约束 | 用户提交 PR | Review 通过或打回 |
REJECTED_REWRITE |
垃圾代码打回 | Review 不通过 | 用户重写 |
DISASTER_SIMULATION |
生成线上事故日志 | Review 通过 | 事故生成完成 |
SOCRATIC_TRIAL |
用户回答根因与 Hotfix | 事故下发完成 | AI 判断合格 |
MILESTONE_ACHIEVED |
节点拔旗，更新学习地图 | 复盘合格 | 用户选择下一节点 |
关键流转规则：
| 规则 | 系统实现 |
|---|---|
| 没有学习节点，不生成任务 | BOOTSTRAP -> NODE_CONFIRMATION 必须存在 |
| 没有“开干”，不进入阶段一 | 前端按钮触发 TASK_GENERATION |
| 没有压测通过，不允许提交 PR | PR Submit 按钮置灰 |
| 没有 PR Review 通过，不生成事故 | DISASTER_SIMULATION 只能从 AI_REVIEW:passed 进入 |
| 回答不合格，不解锁节点 | SOCRATIC_TRIAL 可循环追问 |
| AI 不直接给答案 | Review 失败时只给文档关键词、失败方向、约束提醒 |
Devil Agent 不应该是一个单一 Prompt，而应拆成多个职责明确的 Agent Node。
| Agent Node | 输入 | 输出 | 约束 |
|---|---|---|---|
TaskGeneratorAgent |
技能节点、语言、难度、用户历史薄弱点 | Hardcore Industrial Schema | 不能泄露完整答案 |
ConstraintCheckerAgent |
用户代码、强制语法特性 | 是否满足 idiomatic constraints | 不满足直接打回 |
CodeReviewAgent |
用户代码、测试结果、任务要求 | Review 结论、代码异味、重写方向 | 禁止给完整修正版 |
DisasterAgent |
用户代码、API 类型、潜在风险 | 线上事故日志、错误堆栈、现场描述 | 必须与用户代码相关 |
SocraticTrialAgent |
用户回答、事故根因、预期 Hotfix | 追问、评分、是否通过 | 以问题逼用户反查底层 |
MilestoneAgent |
训练记录、失败次数、回答质量 | 技能地图更新、下一节点建议 | 只在复盘通过后触发 |
设计重点：CodeReviewAgent 的输出必须克制。 如果用户代码能跑但很差，系统不能直接给正确答案，只能输出类似：
| 问题类型 | 允许输出 | 禁止输出 |
|---|---|---|
| 未使用强制语法 | “检索关键词：Python generator lazy evaluation / contextlib context manager” | 直接给出完整生成器实现 |
| 复杂度过高 | “你的实现存在 O(n²) 聚合风险，重新审视 collections.Counter 的使用场景” | 直接贴优化后代码 |
| 资源泄漏 | “检查文件句柄生命周期，检索关键词：Python with statement resource management” | 直接写出最终代码 |
| 异常处理缺失 | “考虑 API 在空输入和非法 JSON 时的返回路径” | 直接补全 try/except |
MVP 阶段必须先实现轻量级判题，而不是过早陷入容器化。核心目标是快速验证训练闭环。
| 能力 | MVP 实现 | 后续升级 |
|---|---|---|
| 执行方式 | subprocess.run() 执行临时 Python 文件 |
Docker / gVisor / Firecracker |
| 异步调度 | Celery Worker | Kubernetes Job / Ray |
| 队列系统 | Redis Broker | RabbitMQ / Redis Cluster |
| 超时控制 | timeout=3~5s |
cgroup CPU 限额 |
| 输出捕获 | stdout、stderr、exit code、runtime | 结构化日志事件 |
| 危险代码检测 | AST 扫描 + import 黑名单 | seccomp / syscall filter |
| 资源限制 | 临时目录、文件大小限制、进程超时 | namespace / rootless container |
| 测试拼接 | 用户代码 + QA Crucible | 多文件项目模板 |
MVP 阶段的执行流程：
| 步骤 | 行为 |
|---|---|
| 1 | FastAPI 接收 session_id、task_id、user_code |
| 2 | 后端检查用户只能修改 TODO 区域 |
| 3 | AST Guard 检查危险 import 和危险调用 |
| 4 | 拼接 user_code 与 test_code |
| 5 | Celery 投递任务 |
| 6 | Worker 创建临时目录和临时代码文件 |
| 7 | subprocess.run() 执行 |
| 8 | 捕获 stdout、stderr、return code、runtime |
| 9 | 写入 submissions 表 |
| 10 | API 返回结构化结果 |
MVP 数据库不需要复杂，但必须覆盖状态机、任务包、代码提交、事故复盘和技能地图。
| 表 | 核心字段 | 说明 |
|---|---|---|
users |
id, email, name, created_at |
用户 |
skill_nodes |
id, language, name, api_family, difficulty, prerequisites |
技能地图节点 |
training_sessions |
id, user_id, skill_node_id, state, started_at, updated_at |
一次训练会话 |
task_packages |
id, session_id, scenario, api_briefing, constraints, skeleton_code, test_code |
AI 生成任务 |
submissions |
id, session_id, code, status, stdout, stderr, runtime_ms, created_at |
用户代码提交 |
review_reports |
id, submission_id, passed, issues, doc_keywords, created_at |
AI Review |
disaster_cases |
id, submission_id, incident_log, expected_root_cause, expected_hotfix |
线上事故模拟 |
trial_turns |
id, session_id, question, answer, score, passed |
夺命拷问记录 |
user_progress |
id, user_id, skill_node_id, status, completed_at, attempt_count |
学习地图状态 |
| 接口 | 方法 | 职责 |
|---|---|---|
/api/sessions/bootstrap |
POST | 创建会话，进入 BOOTSTRAP |
/api/sessions/{id}/select-node |
POST | 选择学习节点 |
/api/sessions/{id}/start |
POST | 用户点击“开干”，触发任务生成 |
/api/tasks/{id} |
GET | 获取任务包 |
/api/code/run |
POST | 提交代码进行 QA Crucible |
/api/code/result/{job_id} |
GET | 查询异步判题结果 |
/api/pr/submit |
POST | 压测通过后提交 PR |
/api/review/{submission_id} |
GET | 获取 Review 结果 |
/api/disaster/{session_id} |
GET | 获取事故日志 |
/api/trial/answer |
POST | 提交事故根因和 Hotfix |
/api/progress/map |
GET | 获取技能地图 |
/api/sessions/{id}/state |
GET | 获取当前状态 |
前端不应做成普通题库页，而应做成“战场界面”。
| 区域 | 内容 | 交互限制 |
|---|---|---|
| 顶部状态栏 | 当前状态、技能节点、难度、尝试次数 | 显示状态机进度 |
| 左侧军令状面板 | 工业场景、API 兵器谱、毒药参数、极端返回、语法约束 | 不展示源码原理 |
| 中央代码区 | Monaco Editor / 文本编辑器 | 只允许编辑 TODO 区域 |
| 底部控制台 | QA 输出、stderr、结构化错误、运行耗时 | 支持日志折叠 |
| 右侧教官区 | Review 反馈、事故日志、夺命追问 | 阶段未到时锁定 |
| 技能地图 | 节点状态、已解锁路径、薄弱点 | 仅复盘通过后更新 |
MVP 可以先用 Reflex 快速实现，后续再迁移为更细粒度的 React 前端。
| 任务 | 交付物 |
|---|---|
| 初始化 FastAPI 项目 | app/main.py, api/, services/, models/, schemas/ |
| 配置 SQLAlchemy | 基础数据库连接 |
| 配置 Redis + Celery | 本地异步任务队列 |
| 定义状态枚举 | TrainingStateEnum |
| 定义 TaskPackage Schema | Pydantic 模型 |
| 建立测试框架 | Pytest + 基础 API 测试 |
推荐目录：
dialecticforge/
app/
main.py
api/
sessions.py
tasks.py
code.py
review.py
progress.py
core/
config.py
security.py
states.py
engine/
graph.py
nodes.py
prompts.py
executor/
runner.py
guard.py
assembler.py
workers/
celery_app.py
tasks.py
models/
schemas/
services/
tests/
docker-compose.yml
pyproject.toml
README.md
目标：先证明平台能跑代码、能压测、能截断、能返回日志。
| 子任务 | 说明 |
|---|---|
runner.py |
使用 subprocess.run() 执行临时 Python 文件 |
guard.py |
AST 检测危险 import 和危险函数 |
assembler.py |
拼接用户代码与 QA Crucible |
| Celery Worker | 异步执行判题任务 |
/api/code/run |
提交判题 |
/api/code/result/{job_id} |
查询结果 |
| 结构化返回 | status, stdout, stderr, exit_code, runtime_ms |
验收标准：
用户提交一段 Python TODO 实现
系统拼接测试代码
Celery Worker 异步执行
超时自动 kill
返回 stdout / stderr / exit_code / runtime_ms
失败日志能在前端展示
目标：不依赖动态生成，先做一个手写固定训练关卡，打通完整产品闭环。
| 子任务 | 说明 |
|---|---|
| 固定 TaskPackage | 例如 Python 生成器流式处理大日志 |
| 前端展示军令状 | 场景、API、语法约束、TODO |
| 用户运行压测 | 调用 Phase 1 判题器 |
| PR 提交 | 只有测试通过后允许提交 |
| 固定事故模板 | 例如“大文件一次性读取导致 OOM” |
| 复盘问答 | 用户输入根因和 Hotfix |
| 技能节点更新 | 通过后标记完成 |
验收标准：
从进入关卡到完成拔旗，全流程不依赖人工干预
用户必须写代码、跑测试、提交 PR、回答事故复盘
目标：将 V6.0 阶段纪律固化进系统。
| 子任务 | 说明 |
|---|---|
定义 TrainingGraphState |
包含会话、任务、提交、Review、事故、问答历史 |
实现 bootstrap_node |
教官上线，只等待学习节点 |
实现 generate_task_node |
生成 Hardcore Industrial Schema |
实现 review_node |
检查代码质量与语法约束 |
实现 disaster_node |
生成线上事故 |
实现 trial_node |
苏格拉底追问与评分 |
| 实现条件边 | 通过、失败、打回、继续追问 |
| 状态持久化 | 每次节点执行写数据库 |
验收标准：
系统不能跨阶段
用户未点击开干不会生成任务
压测未通过不能提交 PR
Review 未通过不能触发事故
复盘未通过不能点亮技能节点
目标：把固定关卡升级为 AI 动态生成任务包。
| 子任务 | 说明 |
|---|---|
| Prompt 模板化 | 把 Hardcore Industrial Schema 变成稳定生成模板 |
| JSON Schema 输出 | LLM 必须返回结构化 TaskPackage |
| 任务校验器 | 校验 skeleton/test 是否可运行 |
| 自动修复循环 | 生成失败时让 LLM 修复测试代码 |
| 任务缓存 | 同一技能节点生成多个变体 |
| 难度控制 | 初级、中级、高压工业级 |
验收标准：
输入 language + skill_node + difficulty
系统生成可运行任务包
任务包包含 API 兵器谱、强制语法约束、TODO 骨架、QA Crucible
测试代码能够本地执行
| 模块 | 增强方向 |
|---|---|
| 安全执行 | 从 subprocess 升级 Docker/gVisor |
| 静态分析 | 接入 Ruff、Mypy、Bandit |
| 日志真实感 | 生成 Trace ID、线程 ID、时间戳、服务名、请求链路 |
| 技能地图 | 支持依赖图、薄弱点统计、复习计划 |
| 多语言 | Go、Rust、Java、TypeScript |
| 企业版 | 团队训练营、排行榜、能力雷达图 |
| 开源版 | 开放核心状态机、执行器、任务模板 |
| 商业版 | 托管执行环境、高级模型、团队管理、私有题库 |
必须避免一开始做成“大而全平台”。MVP 只保留能验证产品灵魂的部分。
| 功能 | MVP 是否做 | 备注 |
|---|---|---|
| Python 单语言训练 | 做 | 首版聚焦 |
| FastAPI 后端 | 做 | 主服务 |
| Celery + Redis | 做 | 判题异步化 |
| subprocess 执行器 | 做 | MVP 轻量方案 |
| SQLite | 做 | 本地快速落地 |
| LangGraph 状态机 | 做 | 产品核心 |
| 固定关卡 | 先做 | 比动态生成更稳 |
| 动态任务生成 | 第二阶段做 | 需校验生成质量 |
| Monaco Editor | 可后置 | 初版 textarea 也能跑 |
| Docker 沙盒 | 后置 | SaaS 上线前必须补 |
| 多语言支持 | 后置 | 先验证 Python |
| 支付系统 | 不做 | 过早商业化 |
| 企业团队版 | 不做 | 后续扩展 |
第一版最好选择一个能充分体现 V6.0 机制的 Python 关卡：大日志文件流式解析。
| 设计项 | 内容 |
|---|---|
| 工业场景 | 每秒写入十万行的服务日志，需要低内存聚合错误码 |
| 核心 API | open, Path, json.loads, collections.Counter |
| 毒药参数 | 一次性 readlines() 导致内存爆炸 |
| 强制语法 | with 上下文管理器 + yield 生成器 |
| TODO 目标 | 实现流式读取、异常行跳过、错误码聚合 |
| QA Crucible | 正常日志、空文件、坏 JSON、大量数据模拟 |
| 事故拷问 | 线上 OOM，根因是一次性加载文件或生成器被错误消费 |
| Hotfix 方向 | 流式处理、背压、批处理、异常隔离、资源释放 |
这个关卡能同时验证：代码骨架、API 兵器谱、强制语法、压测、事故模拟、慢思考拷问、技能节点更新，适合作为产品第一块地基。
| 优先级 | 要做什么 | 为什么 |
|---|---|---|
| P0 | 轻量判题器 | 没有执行器，平台就是空壳 |
| P0 | 固定关卡闭环 | 先验证训练机制，不急着动态生成 |
| P0 | 状态机纪律 | 产品的灵魂是“不许跨阶段” |
| P1 | AI Review | 保证不是单测通过就放行 |
| P1 | 事故模拟 | 形成与 LeetCode 的根本差异 |
| P1 | 复盘评分 | 让用户进入慢思考 |
| P2 | 动态任务生成 | 扩展内容规模 |
| P2 | 前端体验优化 | 提升训练压迫感 |
| P3 | 容器沙盒 | SaaS 化前必须做 |
| P3 | 多语言与企业版 | 商业化扩展 |