代码质量检查工具 - 免费版

概述

代码质量检查工具免费版为独立开发者提供基础的代码规范校验能力。工具聚焦于最常用的编码风格规则、基础安全检查和可访问性要点,帮助开发者在编码阶段就发现潜在问题,减少后期返工. 本版本适合个人项目、学习用途和小型团队日常代码评审。所有规则均以 Markdown 指令形式呈现,无需安装额外插件,直接在 AI Agent 中即可使用.

核心能力

1. 编码风格规范

提供主流语言的命名约定、格式化标准和注释规范.

规范类别	规则说明	示例
命名约定	变量/函数使用 camelCase,类/类型使用 PascalCase	`userName`、`UserService`
格式化	4 空格缩进,单行不超过 80 字符	智能换行处理
注释规范	注释需有意义且与代码同步,删除过时注释	避免冗余注释
文件组织	相关函数集中放置,公共接口置顶	模块化组织

处理: 解析编码风格规范的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回编码风格规范的响应数据,包含状态码、结果和日志.

2. 基础安全检查

覆盖最常见的代码安全风险点. 具体操作方式与参数说明请参考下方示例代码.

输入格式

参数名	类型	必填	说明
input	string	是	代码质量检查基础版处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

# 检查代码中是否存在硬编码密钥
grep -rnE "(password|secret|api_key|token)\s*=\s*['\"][^'\"]+['\"]" src/
# ...
# 检查是否使用了不安全的随机数
grep -rn "Math.random" src/
# ...
# 检查是否禁用了证书验证
grep -rn "rejectUnauthorized\s*:\s*false" src/

处理: 解析基础安全检查的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回基础安全检查的响应数据,包含状态码、结果和日志.

执行此能力时使用input_params参数,支持创建/查询/导出操作

3. 可访问性要点

提供基础的可访问性检查清单.

语义化 HTML 标签使用(<button>、<nav>、<main>)
图片需包含 alt 属性
表单元素需关联 label
键盘导航可用性验证
响应式断点检查:375px、768px、1024px、1440px

处理: 解析可访问性要点的输入参数,完成核心逻辑,返回结构化响应. 输出: 返回可访问性要点的响应数据,包含状态码、结果和日志. 能力覆盖范围：本skill的核心能力覆盖以下场景关键词：提供代码风格规范、安全基础检查与可、适合个人开发者快、速校验代码质量、面向独立开发者与、小团队的代码质量、辅助工具、涵盖命名规范、基础安全检查与可、核心能力、代码风格规范校验、密钥泄露、输入验证、可访问性要点提示、单文件快速审查等。这些关键词对应description中声明的使用场景,均已在上述能力点中提供对应的操作支持.

使用场景

场景一:个人项目代码自检

开发者在提交代码前进行快速自检.

# 对当前目录的源码进行基础检查
echo "=== 硬编码密钥检查 ==="
grep -rnE "(password|secret|api_key)\s*=\s*['\"]" . --include="*.js" --include="*.py"
# ...
echo "=== 详情见说明 检查 ==="
grep -rn "详情见说明\|详情见说明\|HACK" . --include="*.js" --include="*.py"
# ...
echo "=== 调试代码检查 ==="
grep -rn "console.log\|debugger\|print(" . --include="*.js" --include="*.py"

场景二:代码评审参考

在团队代码评审时作为检查清单使用.

# 代码评审检查清单(免费版)
review_checklist = {
    "命名规范": [
        "变量名是否使用 camelCase",
        "类名是否使用 PascalCase",
        "常量是否使用 UPPER_SNAKE_CASE",
    ],
    "安全检查": [
        "是否存在硬编码密钥",
        "是否验证用户输入",
        "是否使用参数化查询",
    ],
    "可访问性": [
        "图片是否有 alt 属性",
        "表单是否有关联 label",
        "颜色对比度是否达标",
    ],
}
# ...
for category, items in review_checklist.items():
    print(f"\n=== {category} ===")
    for item in items:
        print(f"  [ ] {item}")

场景三:学习编码规范

新手开发者学习并应用编码规范.

# 生成代码风格报告
echo "=== 代码风格统计 ==="
echo "文件数: $(find . -name '*.js' -o -name '*.py' | wc -l)"
echo "总行数: $(find . -name '*.js' -o -name '*.py' -exec cat {} + | wc -l)"
echo "详情见说明 数: $(grep -rn '详情见说明' . --include="*.js" --include="*.py" | wc -l)"
echo "注释数: $(grep -rn '^\s*//' . --include="*.js" | wc -l)"

快速开始

Step 1:触发检查

在 AI Agent 中输入以下指令触发代码质量检查:

请检查当前项目的代码质量,包括命名规范、安全风险和可访问性.

Step 2:查看报告

Agent 会输出结构化的检查报告,包含问题分类、严重级别和修复建议.

Step 3:应用修复

根据报告中的建议逐项修复,或让 Agent 自动生成修复补丁.

示例

在项目根目录创建 .codequality.yml 进行个性化配置:

# 代码质量检查配置(免费版)
version: "1.0"
# ...
# 编码风格
style:
  indentation: 4
  max_line_length: 80
  naming:
    variables: camelCase
    classes: PascalCase
    constants: UPPER_SNAKE_CASE
# ...
# 安全检查
security:
  check_hardcoded_secrets: true
  check_insecure_random: true
  check_disabled_cert_validation: true
# ...
# 可访问性
accessibility:
  check_alt_text: true
  check_label_association: true
  responsive_breakpoints:
    - 375
    - 768
    - 1024
    - 1440

优秀实践

提交前必检:在 git commit 前运行代码质量检查,避免问题进入仓库
增量检查:聚焦本次修改的文件,提升检查效率
配合 Git Hook:将检查集成到 pre-commit 钩子中实现自动化

# 配置 pre-commit 钩子
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
echo "运行代码质量检查..."
 --include="*.js" --include="*.py"
if [ $? -eq 0 ]; then
    echo "发现硬编码密钥,请修复后再提交"
    exit 1
fi
echo "检查通过"
EOF
chmod +x .git/hooks/pre-commit

聚焦核心问题:免费版优先关注安全风险和命名规范,风格细节可后续优化

常见问题

Q1:免费版支持哪些编程语言?

免费版支持主流编程语言的通用规范检查,包括 JavaScript、TypeScript、Python、Java、Go 等。语言特定的深度检查需要专业版.

Q2:如何处理大量误报?

建议通过 .codequality.yml 配置文件调整检查规则,关闭不适用的规则。对于特定文件或目录,可以使用注释标记跳过检查:

// codequality-ignore-next-line
const demoToken = "test-token-for-demo";

Q3:免费版与专业版有何区别?

能力维度	免费版	专业版
检查范围	单文件/单目录	全项目批量
安全深度	基础规则	OWASP Top 10
报告格式	文本输出	HTML/JSON/SARIF
自定义规则	不支持	支持
CI/CD 集成	手动触发	自动化流水线
团队协作	单人	多租户协同

Q4:检查速度慢怎么办?

# 仅检查最近修改的文件
git diff --name-only HEAD | xargs grep -rnE "(password|secret)" 2>/dev/null
# ...
# 依赖说明
grep -rnE "(password|secret)" . --include="*.js" --exclude-dir=node_modules --exclude-dir=dist

依赖说明

运行环境

Agent 平台:支持 SKILL.md 的任意 AI Agent(Claude Code / Cursor / Codex / Gemini CLI 等)
操作系统:Windows / macOS / Linux
运行时:Bash 或 PowerShell(用于执行检查脚本)

第三方依赖

依赖项	类型	是否必需	获取方式
grep	系统工具	必需	系统自带
find	系统工具	必需	系统自带
LLM API	API	必需	由 Agent 内置 LLM 提供

API Key 配置

本 Skill 基于 Markdown 指令,无需额外 API Key
所有检查均在本地执行,代码不会上传到外部服务

可用性分类

分类:MD+EXEC模式纯 Markdown 指令,部分功能需要 exec 命令行执行能力)
说明:基于 Markdown 的 AI Skill,通过自然语言指令驱动 Agent 执行代码质量检查任务
适用规模:单文件到中小型项目(文件数 < 500)

错误处理

错误场景	原因	处理方式
配置错误	参数缺失或格式错误	检查依赖说明中的配置要求
运行时错误	运行环境不满足	确认运行环境符合依赖说明
网络错误	连接超时或不可达	执行ping命令测试网络连通性,检查防火墙和代理设置连接后执行ping命令测试网络连通性,检查防火墙和代理设置连接后重新执行命令，参考国内替代方案

已知限制

需LLM支持,无LLM环境不可用
复杂业务场景建议结合人工经验判断
执行效率受模型能力与网络环境影响

输出格式

处理结果以结构化格式返回, 包含状态码、消息和数据字段.

代码质量检查基础版

安装到 Tokeny（自动）

SKILL.md