山东大学软件学院创新实训——项目博客（一）

一、工作进度与整体介绍

到目前位置 CodeGuard AI 项目已经更新迭代到8.1版本，而本博客将会详细介绍1到4版本的内容。

本项目的技术选型采用的是前后端分离架构，技术选型偏向“成熟、清晰、易于迭代”。

后端

• Python 3.11
• FastAPI
• SQLAlchemy 2.x
• Pydantic v2
• Celery

数据库

• MySQL

前端

• Vue 3
• Vite
• TypeScript
• Pinia
• Vue Router
• Element Plus

审查相关能力

• Semgrep：静态分析
• tree-sitter：代码上下文提取
• OpenAI 兼容接口：LLM 能力接入

技术栈确定好之后，下一个目标就是搭建好项目的基本架构：

将整个仓库按职责拆开，形成了基础目录结构：

• backend/：后端服务、模型、适配器、任务、测试
• frontend/：前端后台界面
• docs/：架构与开发文档
• scripts/：本地演示和辅助脚本

围绕审查主链路，建立了几类核心数据模型：

• Project
• RepositoryBinding
• PullRequestSnapshot
• ReviewTask
• ChangedFile
• Finding
• DraftComment
• ReviewSummary
• RuleConfig
• NormKeywordMapping
• AuditLog

这些模型覆盖了从仓库绑定、PR 快照、审查任务，到问题、评论草稿、规则配置和审计记录的核心数据。

实现了 GitHub PR Webhook 的接收接口，当 webhook 进入系统时，会完成下面几件事：

• 解析仓库和 Pull Request 信息
• 如果项目或仓库绑定不存在，则自动创建
• 创建一个新的ReviewTask
• 写入审计日志
• 投递异步任务进入审查流水线

到这里为止，系统已经不再是一个“静态后台”，而是有了真正的业务触发入口。

搭建了前端管理后台

这一版前端不是摆设，而是完整接上了后端读取接口。

目前已经完成的页面包括：

• 总览页
• 项目页
• 审查任务列表页
• 审查任务详情页
• 评论确认中心
• 规则与技能页
• 规范映射页

这些页面的作用，是让整个系统具备“可观察性”和“可演示性”。

完成了 MySQL 适配和本地联调

把数据库默认切换成了 MySQL，并实际用本地 MySQL 环境完成了联调。

以上是本项目的基础搭建部分，下讲具体版本的内容。

二、阶段内容

V1 核心成果

一、完成端到端审查流程

整个系统在 V1 阶段打通了从代码提交到意见生成的全链路：

1. 触发层：GitHub Webhook 接收 PR 事件，自动创建审查任务

2. 执行层：异步任务调度（Celery）执行代码分析

3. 分析层：静态分析（Semgrep）+ 代码解析（tree-sitter）+ AI 分析（大模型）三层信号融合

4. 输出层：结构化 Findings 转化为可确认/可忽略的评论草稿

5. 展示层：Web 管理后台提供任务追踪、问题确认、规则查看等能力

二、四人分工实现的模块能力

三、关键技术决策回顾

1. AI 输出结构化优先于自由文本

不做“看起来聪明”的自由文本，而是强制输出 JSON，让 findings 可去重、可评分、可进入工程流程。

2. 异步任务解耦 Webhook 接收与审查执行

审查不是同步操作，必须用 Celery 解耦，否则 HTTP 响应超时，用户体验差。

3. 静态分析 + AI 双信号融合

不迷信大模型万能，也不放弃规则能力。Semgrep 发现候选问题，tree-sitter 提供上下文，AI 做综合判断。

4. Mock 模式保证演示独立性

无论 Semgrep、GitHub 凭据还是 LLM 密钥，都支持 Mock 回退，确保项目在任何环境下都能完整演示。

5. 评论草稿 → 确认/发布 → 回写 GitHub

AI 输出不是最终意见，必须先进入“草稿”状态，经人工确认或忽略后再回写平台，保留人机协作空间。

四、V1 已能实现

• GitHub Pull Request Webhook 接收与解析

• 审查任务创建与异步调度（Celery + Redis）

• Semgrep 静态分析接入（Python/Java，支持 Mock 回退）

• tree-sitter 代码上下文提取

• OpenAI 兼容接口调用 + Mock Provider

• 结构化 Findings 生成（JSON 格式，含严重等级、分类、行号等）

• 评论草稿生成与确认链路

• 内置技能信号（SQL 注入、异常吞掉、可读性提示）

• 轻量规范映射（关键词 → 规范说明）

• Web 管理后台（任务列表/详情、问题查看、评论确认、规则/规范映射展示）

• 基础 API（项目、任务、问题、评论、审计日志等）

五、技术栈总览

六、V1 阶段的主要挑战与解决思路

挑战 1：大模型输出不稳定，难以直接入库

• 解决：强制 JSON Schema 约束 Prompt，结合 Pydantic 二次校验，过滤格式异常输出。

挑战 2：不同环境下依赖不一致（Semgrep、LLM 密钥等）

• 解决：所有外部依赖均设计 Provider 接口 + Mock 实现，保证主流程不被阻断。

挑战 3：前端需要展示复杂的多文件、多问题结构

• 解决：后端 findings 结构定义清晰，前端直接映射展示，减少二次加工。

挑战 4：审查任务可能因代码量大而耗时较长

• 解决：Celery 异步执行 + 任务状态持久化，前端轮询展示进度，避免用户等待焦虑。

七、V1 阶段留给后续版本的演进空间

1. 技能机制增强：从内置技能演进为skills.md可配置技能包，支持团队自定义检测规则

2. RAG 知识库接入：从轻量关键词映射演进为向量检索，支持更复杂的规范匹配

3. 更多语言支持：从 Python/Java 扩展到 Go、TypeScript、Rust 等

4. GitLab / Gitee 接入：GitProvider 接口已预留，可快速扩展

5. 评论回写 GitHub：V1 已完成接口抽象，V2 可实现真实回写

八、总结

CodeGuard AI 的 V1 阶段完成了一个“最小可行但闭环完整”的智能代码审查系统。它不是在单个点上“堆功能”，而是围绕“结构化输出、异步任务、多信号融合、人机协作确认”四条主线，构建了一个可演示、可扩展、可落地到真实研发流程中的基础版本。

V2 核心成果

一、从“被动展示”到“主动配置”的跨越

二、四人分工实现的模块能力

三、关键技术决策与演进

1. 技能从代码逻辑演进为配置对象

V1 的技能是硬编码在代码里的，V2 建立了 SkillConfig 表，内置技能通过种子数据写入，用户可新增自定义关键词技能。这一步让技能具备了运行期可配置能力。

2. 规则、技能、规范映射三类配置统一管理

规则可以绑定技能，技能命中影响 finding，规范映射追加评论说明。三类配置不再是孤立的，而是形成联动链路。

3. 手动绑定仓库解决“无 PR 无法演示”问题

V1 依赖 webhook，没有真实 PR 事件时后台是空的。V2 支持手动录入仓库信息，让系统在有真实 GitHub 接入前就能完整演示。

4. 审计日志覆盖配置操作

仓库绑定、规则操作、规范操作、技能操作全部纳入审计日志，确保“谁改了配置”可追溯。

5. 前端从展示型页面彻底转向管理型工作台

规则页、技能页、规范映射页全部升级为完整 CRUD 页面，用户可以增删改查、启用停用，体验接近真实后台产品。

四、V2 相比 V1 新增能力如下

• 手动绑定 GitHub 仓库（后台表单录入）

• 规则配置 CRUD（规则标识、名称、严重级别、关联技能、启用状态）

• 技能配置 CRUD（检测模式、关键词、适用语言、严重级别、建议信息）

• 自定义关键词技能（用户可在后台新增，命中后触发 skill signal）

• 规范映射 CRUD（规范名称、关键词列表、引用说明）

• 内置技能可启停（不再硬编码启用）

• 技能信号进入 LLM 审查链路

• 规范映射实时生效（匹配关键词后追加评论说明）

• 审计日志扩展（覆盖配置类操作）

• 后端接口测试保障（配置相关接口有回归测试）

• 前端项目页手动绑定表单

• 前端规则与技能双管理页面

• 前端规范映射 CRUD 页面

• 弹窗表单、删除确认、消息提示等交互完善

五、V2 阶段的主要挑战与解决思路

挑战 1：技能从硬编码到配置化，如何保证向后兼容？

• 解决：内置技能通过种子数据写入数据库，代码中保留默认值兜底；技能执行时先查配置，若无配置则回退默认行为。

挑战 2：规则绑定技能后，如何在流水线中传递？

• 解决：审查流水线启动时加载当前启用的规则和技能配置，分析阶段按配置执行，而非按固定逻辑。

挑战 3：规范映射如何做到“实时生效”？

• 解决：规范映射在 finding 生成阶段动态匹配，不依赖预缓存；评论生成时调用最新配置。

挑战 4：前端同时管理规则和技能，页面复杂度上升

• 解决：采用 Tab 切换 + 独立表格组件，保持两个管理区域逻辑分离但视觉统一。

挑战 5：配置类操作如何保证数据一致性？

• 解决：后端增加校验逻辑（如删除规则前检查是否被引用），前端配合二次确认。

六、V2 阶段留给后续版本的演进空间

1. 技能机制进一步演进：从关键词型技能升级为skills.md风格的 Prompt 能力包，支持更复杂的 AI 行为定制

2. 仓库级策略：支持不同仓库使用不同规则集和技能组合

3. 真实 GitHub 绑定：从手动录入 repo 信息升级为 OAuth / GitHub App 完整接入流程

4. 更多检测模式：自定义技能从关键词匹配扩展为正则、AST pattern 等

5. 配置导入/导出：支持规则、技能、规范映射的批量迁移和备份

七、V2 阶段总结

CodeGuard AI 的 V2 阶段完成了一次重要的“产品化跃迁”：

• V1 回答的是：“系统能不能跑通审查流程？”

• V2 回答的是：“用户能不能自己配置系统行为？”

V2 阶段保持了清晰的模块边界，同时实现了跨模块的深度联动——技能配置不只是后端的一张表，而是从前端页面到 AI 引擎的完整链路；规则绑定不只是一个数据库外键，而是影响分析阶段如何产生信号。这种“配置驱动”的架构思路，为后续版本继续演进到仓库级策略、skills.md Prompt 注入等更复杂的能力打下了坚实基础。

V3 核心成果

一、从“全局统一配置”到“仓库级差异化策略”

二、四人分工实现的模块能力

三、关键技术决策与演进

1. 仓库级作用域：不做覆盖，做选择

V3 的仓库级策略不是“继承全局后再覆盖个别参数”，而是“选择使用哪套配置集合”。仓库可以选择沿用全局默认，也可以选择自己的规则集、技能集、规范映射集。这个决策降低了实现复杂度，同时满足了差异化需求。

2. 任务重跑：让策略调整可验证

仓库级策略上线后，用户需要快速验证“改了配置到底有没有用”。任务重跑允许对已有任务重新执行审查流水线，结果会随新策略更新。这形成了“配置→验证”的闭环体验。

3. 配置与执行解耦：流水线动态加载

审查流水线不再假设配置是静态的，而是在每个任务执行时动态读取当前仓库的策略配置。这保证了策略调整后立即生效，无需重启服务。

4. 关联表设计：清晰的仓库-配置关系

RepositoryBinding 通过关联表与 Rule、SkillConfig、NormMapping 建立关系，支持多对多映射。仓库启用定制后，流水线通过关联表读取配置集合，未启用则回退全局默认。

5. 前端策略入口内聚到项目页

仓库策略配置不再散落在多个页面，而是统一放在项目页的仓库绑定条目上。用户在一个地方完成“仓库 + 策略 + 验证”的完整操作链路。

四、V3 相比 V2 新增能力如下

• 仓库级策略作用域（每个仓库可选择全局默认或定制配置）

• 仓库与规则关联（多对多，定制模式下按关联规则执行）

• 仓库与技能关联（多对多，定制模式下按关联技能执行）

• 仓库与规范映射关联（多对多，定制模式下按关联映射执行）

• 审查流水线动态加载仓库配置（按仓库读取规则/技能/规范集合）

• 任务重跑能力（状态重置 + 重新入队 + 审计日志）

• 前端项目页策略配置弹窗（模式切换 + 多选配置）

• 前端策略模式标签展示（全局默认 / 仓库定制）

• 前端任务重跑按钮（任务列表 + 任务详情）

• 差异化配置的测试验证（两个仓库不同配置，输出不同结果）

五、核心数据模型变化

V2 模型关系（松散）：

RepositoryBinding ──（无直接关联）── Rule ──（无直接关联）── SkillConfig ──（无直接关联）── NormMapping

V3 模型关系（显式）：

RepositoryBinding ├── use_custom_strategy (bool) ├── rules (many-to-many) ├── skill_configs (many-to-many) └── norm_mappings (many-to-many)

六、V3 阶段的主要挑战与解决思路

挑战 1：如何判断一个任务应该使用哪套配置？

• 解决：流水线启动时读取RepositoryBinding.use_custom_strategy，若为 true 则加载关联表配置，否则加载全局默认配置（原有逻辑）

挑战 2：任务重跑时如何处理已有 findings？

• 解决：先清空该任务关联的旧 findings 和 draft_comments，重置状态为 pending，清空错误信息，然后投递到 Celery 队列

挑战 3：前端如何直观表达仓库策略状态？

• 解决：项目页表格增加“策略模式”列，显示“全局默认”或“仓库定制”标签；提供策略配置弹窗，支持模式切换和多选配置

挑战 4：重跑是否会影响审计追踪？

• 解决：每次重跑写入审计日志，记录操作人、操作时间、任务 ID、重跑前后状态，确保操作可追溯

挑战 5：仓库级策略下，如何保证测试覆盖？

• 解决：新增测试场景——仓库 A 启用定制（含自定义技能），仓库 B 使用全局默认（不含该技能），验证两个仓库同一份代码产生不同的 findings

七、V2 → V3 演进对比

八、V3 阶段留给后续版本的演进空间

1. 策略继承与合并：当前是“全局默认 or 仓库定制”二选一，后续可支持“继承全局 + 局部覆盖”

2. 团队/组织级策略：在仓库之上增加组织层，支持批量配置

3. 更细粒度的参数覆盖：同一条规则在不同仓库可以有不同严重级别或行为

4. 批量重跑：支持按仓库、按时间范围批量重跑任务

5. 策略变更通知：仓库策略变更时自动触发相关任务重跑或提醒

6. 真实 GitHub 授权接入：从手动绑定仓库升级为 OAuth / GitHub App 完整流程

九、V3 阶段总结

CodeGuard AI 的 V3 阶段完成了一次关键的“平台化跃迁”：

• V1 回答的是：“系统能不能跑通审查流程？”

• V2 回答的是：“用户能不能自己配置系统行为？”

• V3 回答的是：“配置能不能按仓库差异化生效并快速验证？”

三人分工在 V3 阶段实现了跨模块的深度协同：

• 后端（杨海跃）建立了仓库级策略的数据模型和 API

• AI 引擎（李传烨）让审查流水线按仓库动态加载配置

• 分析层（张明彧）确保信号生成遵循仓库策略作用域

• 前端（张岩）将策略配置和验证入口内聚到统一工作台

V3 的完成标志着 CodeGuard AI 已经从一个“能跑通演示”的系统，成长为真正具备平台化特征的代码审查工具——支持多仓库、多策略、可配置、可验证。

V4 核心成果

一、从“检测器”到“能力包”的升级

二、四人分工实现的模块能力

三、关键技术决策与演进

1. 混合存储：内置技能用文件，自定义技能用数据库

内置技能使用 Markdown 文件保存在仓库中，支持版本管理和代码审查；自定义技能使用数据库存储，支持网页编辑。两者在运行时统一加载，互不干扰。

2. Prompt 注入 ≠ 替换系统 Prompt

技能 Prompt 不是覆盖系统主 Prompt，而是作为“补充上下文”注入。每个命中的技能贡献一段审查指导，多个技能可以叠加影响模型输出。

3. 结构化 Prompt 组织

技能 Prompt 按“审查目标、重点关注、误报排除、输出建议”等部分组织，既保证质量，又便于后续扩展为 skills.md 体系。

4. 运行时解耦：统一的 SkillPromptContext

后端提供统一加载模块，无论来源是文件还是数据库，都输出相同格式的 SkillPromptContext。流水线不关心存储细节。

5. 前端可编辑 + 可理解

用户可以看到技能的 Prompt 来源（builtin_file / database）和内容摘要；自定义技能支持直接编辑 Markdown，降低使用门槛。

四、V4 能力清单（相比 V3 新增）

• 技能 Prompt 注入机制（命中技能后加载 Prompt 上下文送入 LLM）

• 混合存储方案（内置技能 = 文件，自定义技能 = 数据库）

• SkillConfig 模型扩展（增加 prompt_source、prompt_markdown 字段）

• 内置技能 Markdown 文件（仓库内维护）

• 自定义技能 Prompt 自动生成（基于关键词/描述自动生成默认 Markdown）

• 运行时统一 Prompt 加载模块

• Mock LLM 模式下显示 Prompt 注入效果（任务摘要 + finding 建议）

• 前端技能列表显示 Prompt 来源和摘要

• 前端技能编辑弹窗升级（Prompt 编辑区，内置技能只读）

• 测试覆盖（自定义 Prompt 创建 → 绑定仓库 → 执行任务 → 验证输出）

五、核心数据模型变化

V3 SkillConfig 模型：

​ class SkillConfig: name: str keywords: List[str] language: str severity: str suggestion: str ​

V4 SkillConfig 模型扩展：

class SkillConfig: # ... V3 字段 ... prompt_source: str # "builtin_file" | "database" prompt_markdown: str # Prompt 内容（文件路径或数据库字段）

六、V4 审查流水线变化

V3 流水线输入：

代码变更 + 静态分析信号 + 技能信号 → LLM → Findings

V4 流水线输入：

代码变更 + 静态分析信号 + 技能信号 + 技能 Prompt 上下文 → LLM → Findings

其中技能 Prompt 上下文包含：

• Prompt 全文（审查目标、重点关注、误报排除、输出建议）

• 技能来源（builtin / custom）

• 触发信息（文件路径、行号、关键词）

七、V4 阶段的主要挑战与解决思路

挑战 1：如何存储技能 Prompt 才能兼顾可维护性和可编辑性？

• 解决：混合模式——内置技能使用仓库内 Markdown 文件，支持版本管理；自定义技能使用数据库存储，支持网页编辑。运行时统一加载。

挑战 2：Prompt 注入后如何避免上下文过长？

• 解决：只注入命中技能的 Prompt，而非全部技能；每个技能的 Prompt 控制在合理长度（200-500 词），聚焦核心指导。

挑战 3：自定义技能用户不写 Prompt 怎么办？

• 解决：后端根据技能名称、关键词、适用语言、严重级别、建议处理方式自动生成默认 Markdown 模板，用户可选修改。

挑战 4：没有真实 LLM 时如何验证 Prompt 注入生效？

• 解决：Mock LLM 模式下显式输出 Prompt 注入摘要，并在 finding 建议中体现 Prompt 内容，保证可验证。

挑战 5：前端如何让非技术人员理解 Prompt 的作用？

• 解决：技能列表直接显示 Prompt 来源标签和内容摘要；编辑弹窗区分内置/自定义，内置技能只读展示，降低困惑。

八、V3 → V4 演进对比

九、V4 阶段留给后续版本的演进空间

1. skills.md 完整规范：当前已具备 Prompt 注入基础，后续可演进为标准的 skills.md 格式，支持更复杂的能力定义

2. 技能 Prompt 版本管理：支持技能 Prompt 的历史版本追溯和回滚

3. Prompt 模板市场：团队可分享和复用高质量技能 Prompt

4. 仓库级 Prompt 覆盖：同一技能在不同仓库可使用不同 Prompt 版本

5. A/B 测试能力：对比不同 Prompt 版本对审查质量的影响

6. 技能 Prompt 效果评估：基于人工反馈评估 Prompt 质量，持续优化

十、V4 阶段总结

CodeGuard AI 的 V4 阶段完成了一次关键的“能力深化”：

• V1 回答的是：“系统能不能跑通审查流程？”

• V2 回答的是：“用户能不能自己配置系统行为？”

• V3 回答的是：“配置能不能按仓库差异化生效？”

• V4 回答的是：“技能能不能真正影响 AI 怎么审查？”

V4 的技术亮点在于“混合存储 + Prompt 注入”的务实设计：

• 混合存储兼顾了内置能力的版本可控性和自定义能力的交互可编辑性，没有过度工程化

• Prompt 注入让技能从“检测器”升级为“审查能力包”，模型获得的不是“命中了什么规则”，而是“应该如何审查这类问题”

• Mock 模式验证确保了即使没有真实 LLM 凭据，也能演示和测试 Prompt 注入效果

四人分工在 V4 阶段形成了清晰的协作链路：

• AI 引擎（李传烨）设计了 Prompt 注入机制和混合存储方案

• 后端（杨海跃）落地了数据模型扩展和运行时加载模块

• 分析层（张明彧）将 Prompt 上下文接入审查流水线

• 前端（张岩）让技能 Prompt 变得可查看、可编辑、可理解

V4 的完成标志着 CodeGuard AI 的系统能力从“配置管理”深入到“AI 行为定制”，为后续演进为完整的 skills.md 体系奠定了坚实基础。

三、总结

CodeGuard AI 从一个“能跑通审查流程的原型”起步，经过四个阶段的迭代，成长为一个具备以下特征的完整系统：

1. 可运行：完整的 GitHub → 后端 → AI → 前端链路

2. 可配置：规则、技能、规范映射全部可后台管理

3. 可差异化：不同仓库可配置不同审查策略

4. 可深化：技能可注入 Prompt，真正影响 AI 审查行为

5. 可验证：任务重跑让配置修改的效果立即可见

6. 可演示：Mock 模式保证项目独立可运行

更重要的是，整个项目的演进路径清晰、阶段目标明确、分工协作有序。每一阶段的成果都建立在上一阶段的基础之上，没有出现推倒重来或方向漂移。