AI Coding Alignment Inspector

AI Coding Alignment Inspector（AI 编码产出对齐预筛查工具）是面向 AI Coding（AI 编码）流程的阶段性产出源文档对齐预筛查工具。

它用于把源文档抽取成 Requirement List（要求清单），再对当前 AI 产出文件做规则式预筛查，输出 Scope Declaration（当前审查范围声明）、Coverage Matrix（覆盖矩阵）、ReviewIssue（审查问题）和 fix_prompt（修正提示词）。

本项目不是 AI 自动验收系统、代码质量检测平台、通用 AI 质检平台、自动测试系统、完整代码审查系统或多 Agent（多智能体）系统。它不替代人工 review（人工审查）和测试。

当前状态

当前项目已完成：

• Phase 0（第 0 阶段）：工程骨架、Mock（模拟返回）接口、Pydantic Schema（数据结构定义）、Storage（存储）、Streamlit（Python 快速网页演示工具）调试页、基础测试。
• Phase 1（第 1 阶段）：可选 Qwen / DashScope（通义千问模型服务）Requirement Extraction（要求抽取）和 Source Reviewability（源文档可审查性）生成。
• Phase 2（第 2 阶段）：规则式 Scope Detector（范围检测器）、Scope Declaration（当前审查范围声明）、scope_override（范围纠偏）。
• Phase 3（第 3 阶段）：规则式 Coverage Checker（覆盖检查器）、Coverage Matrix（覆盖矩阵）、user_task_instruction（用户给 AI 的原始任务指令）、not_checked_in_current_review（本轮未检查）、unknown（未知）。
• Phase 4（第 4 阶段）：Rule Engine（规则引擎）、ReviewIssue（审查问题）、fix_prompt（修正提示词）、no_issue_summary（无明显问题摘要）。
• Phase 5（第 5 阶段）：评测样例、文档同步、演示页修正、仓库清理和最终测试。

默认 Mock 模式

默认运行模式是 Mock（模拟返回）：

• ENABLE_REAL_EXTRACTION=false
• 不需要 DASHSCOPE_API_KEY
• /api/source/extract 使用 Mock（模拟返回）抽取结果
• 本地 Demo（演示）和基础测试可以直接运行

真实抽取模式说明

如需启用真实 Qwen / DashScope（通义千问模型服务）抽取：

ENABLE_REAL_EXTRACTION=true
DASHSCOPE_API_KEY=your_real_dashscope_api_key
QWEN_MODEL=qwen-turbo
REAL_EXTRACTION_TIMEOUT_SECONDS=90
MAX_SOURCE_CHARS_FOR_REAL_EXTRACTION=3000

启用后，/api/source/extract 会调用真实 LLM（大语言模型）生成 Requirement List（要求清单）和 Source Reviewability（源文档可审查性）。这仍然只属于 Phase 1（第 1 阶段）的源文档抽取能力。

默认测试使用 Mock（模拟）模式，不需要真实模型服务。真实演示可以开启 ENABLE_REAL_EXTRACTION，并需要配置 DASHSCOPE_API_KEY。建议演示源文档控制在 3000 字以内；真实模型输出不等于人工确认结果，要求清单仍建议人工确认。

真实抽取默认输出关键要求，最多 8 条，不追求穷尽所有细节；演示时建议优先使用 500 字以内的源文档，中短源文档建议不超过 900 字。

当前项目使用 dashscope.Generation.call（文本生成接口调用），默认真实抽取模型为 qwen-turbo（通义千问 Turbo），原因是它在当前账号和调用方式下文本、JSON（结构化数据格式）和项目 llm_service（大模型调用服务）验证均通过，响应速度适合演示。qwen-plus（通义千问 Plus）可作为备选；qwen3.5-plus（通义千问 3.5 Plus）和 qwen3.6-flash（通义千问 3.6 Flash）不兼容当前文本生成接口，本项目当前不接入多模态调用路径。

如果真实模型超时、失败、配置不完整或源文档过长，系统会返回中文错误提示和空要求清单，不会伪装成 Mock（模拟）成功结果。

真实演示启动示例：

export ENABLE_REAL_EXTRACTION=true
export QWEN_MODEL=qwen-turbo
.venv/bin/uvicorn backend.main:app --host 127.0.0.1 --port 8010

BACKEND_URL=http://127.0.0.1:8010 .venv/bin/streamlit run frontend/streamlit_app.py

LLM（大语言模型）当前只允许用于 /api/source/extract 的源文档抽取，不用于 Scope Detector（范围检测器）、Coverage Matrix（覆盖矩阵）或 Rule Engine（规则引擎）。

启动后端

cd ai-coding-alignment-inspector
uvicorn backend.main:app --reload --host 127.0.0.1 --port 8000

启动 Streamlit 调试页

cd ai-coding-alignment-inspector
streamlit run frontend/streamlit_app.py

运行测试

cd ai-coding-alignment-inspector
pytest

当前主链路

源文档
→ Requirement List（要求清单）
→ extraction_id（抽取编号）
→ current_output_files（当前 AI 产出文件）
→ Scope Declaration（当前审查范围声明）
→ Coverage Matrix（覆盖矩阵）
→ Rule Engine（规则引擎）
→ ReviewIssue（审查问题）
→ fix_prompt（修正提示词）

review_mode（审查模式） 支持：

• normal（普通模式）
• conservative（保守模式）
• milestone（里程碑审查）

当没有生成 ReviewIssue（审查问题）时，只表示：

本次未发现明显源文档对齐问题，建议继续人工 review（人工审查）或运行测试。

这不是验收结论，也不是代码质量结论。

明确边界

当前不接入：

• LangChain（大模型应用开发框架）
• LangGraph（大模型工作流编排框架）真实流程
• RAG（检索增强生成）
• 向量数据库或新增数据库
• 登录系统
• 历史记录
• React（前端框架）正式前端
• PDF / Word 解析
• 完整项目压缩包自动审查
• 多 Agent（多智能体）系统

评测与测试

当前 pytest 共 48 个用例全部通过。evaluation_cases/ 目录包含 12 个结构化评测样例，覆盖覆盖矩阵和规则引擎的典型场景。

评测样例中包含 false positive 控制设计，例如：

• 注释中提到关键词不算实现（避免字符串子串匹配误判）
• PostgreSQL vs sqlite 不误判为 covered（技术栈路径区分）
• Redis 禁止项冲突（检测明确冲突而非关键词表面匹配）

运行评测：

.venv/bin/pytest -q
.venv/bin/python scripts/evaluation_runner.py

backend/rules/*.yaml 是 YAML Rule（YAML 规则配置）的预留/占位文件，当前主判断仍在规则式 Python 服务中完成，不应描述成复杂规则加载系统。