CodeSpectra — 开源代码管控系统

项目简介

基于 Python Flask + SQLite 构建的轻量级代码审查管控系统。 通过 Webhook 接收 GitCode 平台的 PR 事件，自动执行多维度的代码检查和审查管控， 支持审查权力拆分、自动化检查、AI 代码检视等功能。

项目结构

backend/               # 后端
├── server.py          # Flask Web Server（Webhook 入口 + 管理端点）
├── api/               # API 路由层
│   ├── auth.py        # 认证（登录/登出/session/管理员初始化）
│   ├── users.py       # 用户 CRUD
│   ├── groups.py      # 组成员管理
│   ├── event_whitelist.py  # 检查白名单配置
│   ├── check_configs.py    # 检查项开关配置
│   ├── public.py      # 公开 API（成员/组列表、AI 统计）
│   ├── webhook.py     # Webhook 接收端点
│   ├── health.py      # 健康检查 + 监控
│   ├── static.py      # 前端静态文件
│   └── decorators.py  # 认证装饰器
├── core/              # 基础设施
│   ├── database.py    # 数据库引擎（SQLite WAL）
│   ├── git_client.py  # GitCode API 客户端
│   ├── exceptions.py  # 异常定义
│   └── logger.py      # 日志
├── dispatcher/        # 事件调度框架
│   ├── dispatcher.py  # 主调度器（路由匹配 → worker pool 执行）
│   ├── base_event.py  # handler 基类
│   ├── registry.py    # handler 注册表
│   ├── routes.toml    # 路由配置（评论触发 + PR 生命周期触发）
│   ├── routes.py      # 路由加载器
│   ├── worker.py      # ThreadPoolExecutor 任务池
│   ├── context.py     # EventContext
│   ├── webhook.py     # WebHook 数据对象
│   ├── results.py     # CheckStatus 枚举 + CheckResult
│   └── monitor.py     # 请求监控统计
├── models/            # SQLAlchemy ORM 模型（Mapped 类型注解）
├── services/          # 业务 Service 层
├── handlers/          # 检查/行动事件处理器（24 个）
└── utils/             # 工具函数
frontend/              # Vue 3 + Vite + Tailwind CSS v4 Dashboard
├── src/
│   ├── App.vue        # 根组件（导航 + KeepAlive + 暗色模式）
│   ├── style.css      # 设计令牌 + 暗色模式 + 全局样式
│   ├── views/         # 页面视图
│   │   ├── Dashboard.vue      # 监控面板
│   │   ├── AiReviewView.vue   # AI 检视统计
│   │   ├── MembersView.vue    # 成员（组-成员主从卡片视图）
│   │   └── ManageView.vue     # 管理（5 个子 tab）
│   ├── components/
│   │   ├── ui/        # 共享 UI 组件库（10 个）
│   │   │   ├── BaseCard.vue      # 卡片容器
│   │   │   ├── BaseTable.vue     # 表格（含移动端卡片模式）
│   │   │   ├── BaseBadge.vue     # 状态标签（8 色）
│   │   │   ├── BaseDialog.vue    # 模态框（focus trap + ESC）
│   │   │   ├── BaseNavBar.vue    # 响应式导航（桌面 tab + 移动汉堡菜单）
│   │   │   ├── BaseToast.vue     # 全局 Toast 通知
│   │   │   ├── BasePagination.vue  # 分页栏
│   │   │   ├── BaseInput.vue     # 输入框
│   │   │   ├── BaseSelect.vue    # 下拉选择
│   │   │   └── BaseSearchDropdown.vue  # 搜索下拉
│   │   ├── manage/    # 管理面板子组件
│   │   └── monitor/   # 监控面板子组件
│   ├── composables/   # Vue Composables（useToast）
│   └── utils/         # API 请求封装（fetchApi/fetchJson）
├── package.json
└── vite.config.js
knowledge/              # 知识库
├── common/
│   ├── coding_standards.md  # 编码规范
│   ├── architecture.md      # 架构约束
│   └── security.md          # 安全规范
└── tdd/
    └── unittest_basics.md   # C++ 单元测试规范
tests/                  # 单元测试（pytest，317 个用例）

核心功能

审查权力拆分

通过成立多个逻辑小组，每个小组拥有独立的平台账号，负责各自责任模块的代码文件。 PR 只允许组账号进行加分，个人账号评论 pass 后由系统代为执行组账号审查。

graph TD
    A[个人账号评论 pass] --> B[触发 Webhook]
    B --> C{管控检查通过?}
    C -->|是| D[使用所属组账号审查加分]
    C -->|否| E[检查未通过，不允许加分]

事件调度

所有检查和行动通过路由配置驱动，支持两类触发方式：

• 评论触发：PR 下评论特定关键词（如 check tdd、pass、ai review）
• 生命周期触发：PR 创建（open）、更新（update）、合入（merge）时自动执行

路由配置位于 backend/dispatcher/routes.toml，示例：

# 评论触发：评论 "pass" 时执行检查 + 加分
[[route]]
pattern = "pass"
desc = "审核通过(Approve)"
checks = ["check tdd", "check cts", "check msg", "check static"]
actions = ["review"]

# 生命周期触发：PR 创建时自动检查 + AI 检视
[[route]]
hook = "lifecycle"
action = "open"
checks = ["check tdd", "check cts", "check msg", "check static"]
actions = ["add code owners", "ai review"]

Dashboard 前端

Vue 3 单页应用，4 个视图：

视图	说明
监控	请求统计（总/峰值/平均耗时/路由耗时）+ 系统运行时长
AI统计	AI 检视意见接纳率（总体/按人/按组/最近 PR）
成员	组-成员主从视图，CSS 头像卡片网格展示，支持搜索分页
管理	管理员/用户/组成员/白名单/检查项配置（需登录）

前端特性：

• 设计令牌体系：语义化颜色/圆角/阴影，CSS 自定义属性驱动
• 暗色模式：自动跟随系统 + 手动切换，localStorage 持久化
• 响应式布局：移动端汉堡菜单、表格自动转卡片、网格自适应
• 可访问性：aria-label/role/aria-current/focus trap/键盘导航
• 共享 UI 组件库：10 个组件覆盖卡片、表格、弹窗、导航、Toast 等

已有事件

事件	类型	说明
check tdd	check	TDD 单元测试检查
check cts	check	评论意见数量检查
check msg	check	提交说明信息检查
check static	check	代码静态分析检查（多线程映射/不安全 API 等）
check hdf	check	头文件传播数量检查
review	action	组账号加分
review all	action	全部组账号加分
ai review	action	AI 代码检视（后台异步执行）
deep review	action	Claude CLI 本地深度检视
auto review passed	action	AI 检视通过后自动加分
check hdf result	action	头文件检查结果回调
add code owners	action	添加 CODEOWNERS 归属
update owner pass	action	更新 owner 加分状态
pr merged	action	PR 合入处理
force check	action	强制通过指定检查
list cmds	action	列出可用命令
show owners	action	显示负责人
show file owner	action	查看文件归属人
show wlist	action	查看检查白名单
summon dragon	action	召唤神龙（彩蛋）
fortune	action	求签（彩蛋）
moyu	action	摸鱼（彩蛋）

快速开始

前置条件

• Python >= 3.14
• Node.js（前端构建）

安装依赖

pip install uv
uv sync
cd frontend && npm install && cd ..

启动服务

notifier 账户需要在 GitCode 平台上提前注册，并拥有对应仓库的评论和检视权限。

./start.sh <notifier账户名> <notifier_access_token>

服务默认监听 0.0.0.0:8080，可通过环境变量覆盖：

CODESPECTRA_HOST=127.0.0.1 CODESPECTRA_PORT=9090 ./start.sh <账户名> <token>

Webhook 端点

端点	方法	说明
/webhook	POST	GitCode Webhook 回调
/health	GET	健康检查
/monitor	GET	监控数据
/api/v1/*	GET/POST/PUT/DELETE	管理 API

数据库

• 引擎：SQLite（WAL 模式，通过 SQLAlchemy）
• 自动建表，无需手动创建

开发新的 handler

所有 handler 继承 BaseEvent，注册到 registry 后即可在 routes.toml 中使用。

必须设置的类属性

• event_key：事件唯一键，如 "check tdd"、"ai review"
• event_type："check" 或 "action"
• event_name_zh：中文名
• event_name_en：英文名

必须实现的方法

• execute()：事件执行逻辑

可选重写的方法

• pre_execute(all_checks_passed)：前置校验，返回 False 跳过执行
• get_check_type()：返回 check_type（仅 check 类事件需要）

示例

from backend.dispatcher.base_event import BaseEvent

class MyCheckEvent(BaseEvent):
    event_key = "check my"
    event_type = "check"
    event_name_zh = "我的检查"
    event_name_en = "My Check"

    @classmethod
    def get_check_type(cls) -> str:
        return "my"

    def pre_execute(self, all_checks_passed: bool = True) -> bool:
        return True

    def execute(self) -> None:
        self.failed = False  # True 表示检查失败
        self.comment = "检查结果说明"  # 失败时的提示信息

在 backend/handlers/__init__.py 中注册，然后在 backend/dispatcher/routes.toml 中配置路由即可生效。

运行测试

# 后端测试
uv run pytest

# 前端构建
cd frontend && npm run build