Code Guardian

Code Guardian 是一个 MCP (Model Context Protocol) Server，为 AI 编码助手（如 Claude Code、Trae、Cursor、Windsurf 等）提供代码质量检查能力。它能在 AI 修改代码前后自动检查文件大小、ESLint、架构分层合规、反模式扫描和注释规范，确保 AI 生成的代码符合项目团队的编码标准。

目录

• 前置要求
• 安装
• 快速开始
• 工作原理
• 7 个检查工具
• 配置参考
• 与 AI 规则联动
• 四层防御体系
• 运行测试
• 项目结构
• 贡献指南
• 常见问题
• License

前置要求

• Node.js >= 18.0.0（MCP SDK 依赖）
• ESLint >= 9.0.0（可选，run_eslint 工具需要）
• 项目需要有一个 .code-guardian.json 配置文件（详见配置参考）

安装

方式一：从 npm 安装（推荐）

当前版本已发布到 npm 公共仓库，无需额外配置：

npm install @xueca/code-guardian --save-dev

使用 MCP 配置时可直接通过 npx -y @xueca/code-guardian 运行，无需配置 scope registry 或 Token。

方式二：从 GitHub 源码安装

npm install --save-dev github:xueca/code-guardian

需要 Git 已安装且可访问 GitHub。

方式三：本地开发安装

git clone https://github.com/xueca/code-guardian.git
cd code-guardian
npm install
npm run build

快速开始

1. 创建项目配置文件

在项目根目录创建 .code-guardian.json：

{
  "version": "1.0",
  "fileSizeLimits": {
    "**/controllers/**/*.js": 150,
    "**/routes/**/*.js": 50,
    "**/*.vue": 200,
    "**/*.js": 150
  },
  "antiPatterns": {
    "directApiInView": true,
    "bareAsync": true,
    "resourceLeak": true
  }
}

完整配置项见下方 配置参考。

2. 配置 MCP 客户端

Claude Code（.claude/settings.json）：

{
  "mcpServers": {
    "code-guardian": {
      "command": "npx",
      "args": [
        "-y",
        "@xueca/code-guardian",
        "--project-root",
        "."
      ]
    }
  }
}

Trae（.trae/mcp.json）：

{
  "mcpServers": {
    "code-guardian": {
      "command": "npx",
      "args": [
        "-y",
        "@xueca/code-guardian",
        "--project-root",
        "/absolute/path/to/project"
      ]
    }
  }
}

Cursor / Windsurf（.cursor/mcp.json 或 .windsurf/mcp.json）：

{
  "mcpServers": {
    "code-guardian": {
      "command": "npx",
      "args": [
        "-y",
        "@xueca/code-guardian",
        "--project-root",
        "."
      ]
    }
  }
}

关于 npx -y @xueca/code-guardian：-y 参数表示自动确认安装，首次运行会自动从 npm 拉取最新版本。如果你更倾向于使用 node 直接运行，可将 args 替换为 ["./node_modules/@xueca/code-guardian/dist/index.js", "--project-root", "."]。

关于 --project-root：Code Guardian 需要知道项目根目录来定位 .code-guardian.json 配置文件和待检查的文件。如果省略此参数，默认使用 Node.js 进程的当前工作目录（process.cwd()）。对于 Trae 等需要绝对路径的客户端，必须显式指定。

3. 使用

在 AI 对话中直接调用 Tool：

code-guardian:full_health_check({ filePath: "src/views/Home.vue" })
code-guardian:check_file_size({ filePath: "backend/controllers/userController.js" })

工作原理

Code Guardian 是一个基于 JSON-RPC 2.0 协议、通过 stdio 传输的 MCP Server。它的工作流程如下：

AI 编码助手（Client）
  │
  │  JSON-RPC Request（via stdio）
  ▼
index.ts（MCP Server 入口）
  │
  │  解析 --project-root → 定位项目根目录
  │  路由 Tool Name → 对应 handler
  ▼
tools/*.ts（检查执行层）
  │
  │  读取 .code-guardian.json 配置
  │  读取目标文件内容
  │  执行检查逻辑
  ▼
结构化 JSON 报告 → 返回给 AI 编码助手

关键设计决策：

• 无状态：每次 Tool 调用独立执行，不维护跨调用状态
• 配置驱动：所有检查参数（行数上限、分层规则、反模式开关）均从 .code-guardian.json 读取，不硬编码
• Glob 模式匹配：文件路径通过 glob 模式匹配对应配置项，支持 **/ 和 /** 通配符
• Graceful Degradation：ESLint 不可用时（未安装或配置缺失），run_eslint 返回 { ok: true, skipped: true } 而非报错

7 个检查工具

| 工具 | 功能 | 输入 | 输出 | |------|------|------|------| | check_file_size | 检查文件行数是否超限 | filePath | { ok, lines, limit, exceeded } | | run_eslint | 运行 ESLint 检查 | filePath | { ok, errorCount, warningCount, messages } | | validate_architecture | 检查分层与依赖方向 | filePath | { ok, issues: [...] } | | detect_anti_patterns | 扫描 16 种反模式 | filePath | { ok, findings: [...] } | | check_comment_compliance | 检查注释规范 | filePath | { ok, issues: [...] } | | full_health_check | 一键运行全部检查 | filePath | { ok, summary, details } | | auto_fix | 自动修复代码规范问题 | filePath | { ok, summary, fixes, postCheck } |

check_file_size

检查文件是否超过 .code-guardian.json 中 fileSizeLimits 定义的行数上限。使用 glob 模式从上到下匹配，第一个匹配的规则生效。

返回示例：

{
  "ok": true,
  "filePath": "src/views/Home.vue",
  "lines": 165,
  "limit": 200,
  "exceeded": 0
}

匹配逻辑：例如文件 src/views/Home.vue 会依次匹配 fileSizeLimits 中的 glob 模式：

1. **/controllers/**/*.js → 不匹配，跳过
2. **/routes/**/*.js → 不匹配，跳过
3. **/*.vue → 匹配，限制 = 200

run_eslint

对文件运行 ESLint 检查。ESLint 及其插件为可选依赖（peerDependencies），Code Guardian 通过 Module.globalPaths 确保 ESLint 能正确解析插件依赖。支持 ESLint 9 flat config（eslint.config.js）：生成的临时配置会自动将 @eslint/js、eslint-plugin-vue、globals 等裸导入改写为基于项目 node_modules 解析的绝对 file URL，避免从系统临时目录解析失败。

前置条件：项目需安装 eslint 及相关插件，并在 .code-guardian.json 中配置 eslint.configPath 和 eslint.frontendDir。

返回示例：

{
  "ok": true,
  "filePath": "src/views/Home.vue",
  "errorCount": 0,
  "warningCount": 3,
  "messages": [
    { "line": 42, "severity": "warning", "message": "...", "ruleId": "vue/attributes-order" }
  ]
}

如果 ESLint 未安装或配置缺失：

{
  "ok": true,
  "skipped": true,
  "reason": "ESLint 未安装或配置缺失"
}

validate_architecture

检查架构分层合规性，基于 .code-guardian.json 中 architecture.layers 配置：

• 视图层检查（forbidden）：检测匹配文件中是否包含禁止的 API 调用关键字（如 fetch、axios、EventSource）
• 依赖方向检查（forbiddenImports）：检测匹配文件中是否 import 了禁止的模块路径前缀
• 资源泄露检测：检测 composable / views 中是否存在 timer/SSE/AbortController 未配对清理

返回示例：

{
  "ok": false,
  "filePath": "src/views/Home.vue",
  "issues": [
    {
      "type": "forbidden_api_call",
      "message": "视图层禁止直接调用 fetch",
      "line": 42
    }
  ]
}

detect_anti_patterns

扫描 16 种反模式，每种可通过 .code-guardian.json 中 antiPatterns 配置独立开关：

| 反模式 | 检测内容 | 严重程度 | 配置键 | |--------|---------|---------|--------| | 视图层直接 API 调用 | .vue 文件中直接调用 fetch/axios/EventSource | P0 | directApiInView | | 裸 async 无 catch | async 函数缺少 try-catch 包裹 | P0 | bareAsync | | 资源未清理 | setInterval/EventSource/AbortController 未在 onUnmounted 中清理 | P0 | resourceLeak | | 模块级状态变量 | composable 文件顶层存在模块级响应式状态变量 | P1 | moduleLevelState | | 组件内长数据转换 | 组件内存在超过 3 行的链式数据转换（map/filter/reduce） | P1 | longTransformInView | | 重复代码块 | script 中存在 4 行以上的重复代码块 | P2 | duplicateCode | | const 应改 let | 声明后重新赋值的变量使用了 const | P2 | constLet | | 命名规范 | 变量/函数命名不符合 camelCase 或 PascalCase 规范 | P2 | naming | | 同步方法 | 使用了 fs.writeFileSync 等同步 I/O 方法 | P1 | syncMethod | | 禁止 fs.promises | 应使用 require('fs').promises 而非 fs.promises | P2 | noFsPromises | | 下标直接操作 | 使用 obj['key'] 而非 obj.key 访问属性 | P2 | bracketAccess | | JSON 深拷贝 | 使用 JSON.parse(JSON.stringify()) 进行深拷贝 | P2 | deepCopy | | 空值保底 | 缺少 || [] 或 || {} 空值保底 | P2 | nullGuard | | 数据清洗 | 在视图层做 API 返回值清洗（应在 composable 中处理） | P1 | dataCleansing | | 行尾分号 | 代码行末尾有多余分号 | P2 | semi | | Tab 缩进 | 使用 Tab 而非空格进行缩进 | P2 | indent |

返回示例：

{
  "ok": false,
  "filePath": "src/views/Home.vue",
  "findings": [
    {
      "type": "bareAsync",
      "severity": "P0",
      "message": "async 函数缺少 try-catch 错误处理",
      "line": 28
    }
  ]
}

check_comment_compliance

检查文件头注释和函数注释是否符合项目注释规范（参考 .code-guardian.json 中 commentStandard 配置）：

• .vue 文件：检查 HTML 文件头注释（<!-- 页面功能: xxx → useXxx() -->）
• .js 文件：检查文件头注释（// 文件功能: xxx | 数据流: xxx）
• 函数注释：检查函数定义前是否有注释（支持单行 // 和块注释 /** */）

返回示例：

{
  "ok": false,
  "filePath": "src/views/Home.vue",
  "issues": [
    {
      "type": "missing_file_header",
      "message": "缺少文件头注释"
    },
    {
      "type": "missing_function_comment",
      "function": "handleSubmit",
      "line": 42
    }
  ]
}

full_health_check

聚合以上 5 项检查，输出结构化的一键报告：

{
  "ok": false,
  "filePath": "src/views/Home.vue",
  "summary": {
    "fileSize": "✅",
    "eslint": "✅",
    "architecture": "❌",
    "antiPatterns": "❌",
    "comments": "✅"
  },
  "details": {
    "size": { "ok": true, "lines": 165, "limit": 200 },
    "eslint": { "ok": true, "errorCount": 0 },
    "architecture": { "ok": false, "issues": [...] },
    "antiPatterns": { "ok": false, "findings": [...] },
    "comments": { "ok": true, "issues": [] }
  }
}

注意：full_health_check 使用 Promise.all 并行执行 5 项检查，以提高性能。

auto_fix

自动修复代码规范问题。基于 full_health_check 的基线报告，依次应用 4 个修复器，修复后自动进行语法校验和兜底检查。

修复器列表：

| 修复器 | 修复内容 | 是否改变行数 | |--------|---------|-------------| | semi_fixer | 删除行尾多余分号 | 否 | | const_to_let_fixer | 将重新赋值的 const 改为 let | 否 | | trim_fixer | 添加空值保底 || [] 或 || {} | 否 | | chain_call_fixer | 拆分过长的链式调用为多行 | 是（可能增加） |

安全机制：

• 修复前自动创建备份文件，语法校验失败时自动回滚
• 修复后重新运行 full_health_check 验证修复效果
• 不可自动修复的问题列入 manualAttention 供手动处理
• 修复后如果文件超行，在 manualAttention 中给出提示
• .vue 文件分段处理：semi 检测/修复排除 <style> 块内 CSS，script 定位按文件级行号，修复写盘前校验 template/style 原样保留，异常时中止不写入

返回示例：

{
  "ok": true,
  "filePath": "src/views/Home.vue",
  "summary": {
    "totalIssues": 5,
    "fixed": 3,
    "skipped": 2,
    "remaining": 2
  },
  "fixes": [
    { "content": "...", "fixed": 2, "skipped": 0 }
  ],
  "syntaxVerified": true,
  "postCheck": { "ok": true, "summary": {...} },
  "manualAttention": [
    { "line": 42, "pattern": "bare-async", "message": "async 函数缺少 try-catch 错误处理" }
  ]
}

配置参考

完整 .code-guardian.json 配置项：

{
  "version": "1.0",
  "fileSizeLimits": {
    "**/controllers/**/*.js": 150,
    "**/routes/**/*.js": 50,
    "**/middleware/**/*.js": 80,
    "**/*.vue": 200,
    "**/*.js": 150
  },
  "architecture": {
    "layers": [
      {
        "name": "views",
        "path": "**/*.vue",
        "forbidden": ["fetch", "axios", "EventSource"]
      },
      {
        "name": "api",
        "path": "**/api/**/*.js",
        "forbiddenImports": ["composables/", "stores/"]
      },
      {
        "name": "composables",
        "path": "**/composables/**/*.js",
        "forbiddenImports": ["views/"]
      },
      {
        "name": "backend",
        "path": "**/controllers/**/*.js",
        "forbiddenImports": ["views/", "stores/", "composables/"]
      }
    ]
  },
  "antiPatterns": {
    "directApiInView": true,
    "longTransformInView": true,
    "bareAsync": true,
    "resourceLeak": true,
    "moduleLevelState": true,
    "duplicateCode": true,
    "constLet": true,
    "naming": true,
    "syncMethod": true,
    "noFsPromises": true,
    "bracketAccess": true,
    "deepCopy": true,
    "nullGuard": true,
    "dataCleansing": true,
    "semi": true,
    "indent": true
  },
  "eslint": {
    "configPath": "frontend/eslint.config.js",
    "frontendDir": "frontend"
  },
  "commentStandard": {
    "fileHeaderRequired": true,
    "functionCommentRequired": true,
    "vueTemplateCommentRecommended": true
  }
}

fileSizeLimits

• 键：glob 模式，支持 **/ 匹配任意前缀目录，/** 匹配任意后缀目录
• 值：最大行数（整数）
• 匹配规则：从上到下，第一个匹配的模式生效。建议将更具体的规则放在前面，通用规则放在最后
• 默认值（当无匹配时）：**/*.js = 150, **/*.vue = 200
• 注意：路径分隔符统一使用 /（Windows 路径中的 \ 会被自动转换）

architecture.layers

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | name | string | 是 | 分层名称（用于报告中的标识） | | path | string | 是 | glob 模式，匹配该层包含的文件 | | forbidden | string[] | 否 | 禁止在匹配文件中出现的关键字列表 | | forbiddenImports | string[] | 否 | 禁止在匹配文件中 import 的路径前缀列表 |

forbidden 检测：逐行扫描文件内容，检测是否包含禁止关键字。适用于检测直接 API 调用（fetch、axios、EventSource）。

forbiddenImports 检测：扫描 import 语句和 require() 调用，检测是否引用了禁止的模块路径前缀。适用于检测反向依赖。

antiPatterns

• 每个键值对："检测项名称": true/false
• 设为 false 可关闭某项检测
• 默认全部开启
• 如果配置中缺少某个键，则该检测项默认开启

eslint

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | configPath | string | 是 | ESLint 配置文件相对于项目根目录的路径 | | frontendDir | string | 是 | 前端代码目录（run_eslint 仅处理此目录下的文件） |

commentStandard

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | fileHeaderRequired | boolean | true | 是否要求文件头注释；false 时跳过 .js/.ts/.tsx/.vue 文件头检查 | | functionCommentRequired | boolean | true | 是否要求函数注释；false 时跳过函数注释检查 | | vueTemplateCommentRecommended | boolean | true | 是否建议 Vue 模板区域注释；false 时不检查模板区域注释 |

字段缺省或未配置 commentStandard 时按上表默认值生效（与旧版硬编码行为一致）。

与 AI 规则联动

推荐在项目中创建 AI 规则文件，强制 AI 在修改代码时调用 Code Guardian。以下为各 AI 编码助手的规则文件路径：

Trae（.trae/rules/07-mcp-code-guardian.md）：

# MCP Code Guardian 强制调用规则

修改任何 .vue / .js 文件时：
1. 修改前：调用 full_health_check 了解当前状态
2. 修改中：调用 check_file_size 防止超行
3. 修改后：调用 full_health_check 验证无新问题
4. 如果 ok: false，先修复再报告完成

Claude Code（.claude/rules/code-guardian.md）：

# Code Guardian — Mandatory Pre/Post Code Change Checks

Before modifying any .vue / .js file:
- Call code-guardian:full_health_check({ filePath }) to baseline

After modifying:
- Call code-guardian:full_health_check({ filePath }) to verify
- If any check fails, fix before marking task complete

通用规则（适用于 Cursor、Windsurf 等）：将上述规则文件放置在项目的 .cursorrules 或 .windsurfrules 中。

四层防御体系

Code Guardian 设计为多层防御，确保代码质量检查不会遗漏：

| 层级 | 机制 | 触发方式 | 失败行为 | |------|------|---------|---------| | Layer 1 | MCP Tools | AI 主动调用 | 返回 ok: false + 详细问题列表 | | Layer 2 | after-write Hook | 文件写入后自动触发 | process.exit(1) 阻止写入 | | Layer 3 | /review Command | 用户手动触发 | 输出结构化报告 | | Layer 4 | Husky pre-commit | git commit 前触发 | 阻止提交 |

Layer 1（MCP Tools） 是最核心的防御层，由 AI 在修改代码前后主动调用，提供即时反馈。

Layer 2（after-write Hook） 是兜底机制，当 AI 忘记调用 Code Guardian 时，文件写入后自动触发检查。实现方式：在 .claude/hooks/after-write.cjs 中调用 code-guardian:full_health_check。

Layer 3（/review Command） 允许用户随时手动触发全面检查，无需等待 AI 自动调用。

Layer 4（Husky pre-commit） 是最后一道防线，在代码提交前确保所有文件通过检查。

运行测试

# 运行所有测试（含编译）
npm run test

# 运行指定测试文件
npm run build && node --test dist/__tests__/check_file_size.test.js

# 带覆盖率
npm run test:coverage

测试框架：Node.js 原生 node:test（无需额外依赖）。

测试文件：

• check_file_size.test.ts：文件大小检查
• validate_architecture.test.ts：架构合规检查
• detect_anti_patterns.test.ts：反模式扫描
• auto_fix.test.ts：自动修复
• extreme_boundary.test.ts：边界条件极限测试
• extreme_detectors.test.ts：检测器极限测试
• extreme_config_utils.test.ts：配置工具极限测试
• extreme_resource_arch.test.ts：资源与架构极限测试
• new_detectors.test.ts：新增检测器测试
• mcp_integration.test.ts：MCP 集成测试
• eslint_integration.test.ts：真实 ESLint 集成（flat config 裸导入改写）
• vue_line_offset.test.ts：.vue script 行号补偿
• comment_standard.test.ts：注释规范配置开关

当前共 319 个测试用例（46 个 suite），覆盖检测器、修复器、MCP 入口与真实 ESLint 集成。

项目结构

code-guardian/
├── .code-guardian.json          # 自带默认配置
├── .github/
│   └── workflows/
│       └── ci.yml               # GitHub Actions CI 配置
├── .gitignore                   # Git 忽略规则
├── CHANGELOG.md                 # 变更日志
├── CODE_OF_CONDUCT.md           # 行为准则
├── CONTRIBUTING.md              # 贡献指南
├── SECURITY.md                  # 安全策略
├── index.ts                     # MCP Server 入口（JSON-RPC over stdio）
├── package.json
├── README.md
├── tsconfig.json                # TypeScript 编译配置
├── __tests__/                   # 测试（node:test 框架）
│   ├── check_file_size.test.ts
│   ├── validate_architecture.test.ts
│   ├── detect_anti_patterns.test.ts
│   ├── auto_fix.test.ts
│   ├── extreme_boundary.test.ts
│   ├── extreme_detectors.test.ts
│   ├── extreme_config_utils.test.ts
│   ├── extreme_resource_arch.test.ts
│   ├── new_detectors.test.ts
│   └── mcp_integration.test.ts
└── tools/
    ├── auto_fix.ts                   # 自动修复主入口
    ├── check_file_size.ts            # 行数检查
    ├── check_comment_compliance.ts   # 注释规范检查
    ├── detect_anti_patterns.ts       # 反模式扫描（入口）
    ├── full_health_check.ts          # 一键聚合检查
    ├── run_eslint.ts                 # ESLint 集成
    ├── types.ts                      # 共享类型定义
    ├── validate_architecture.ts      # 架构分层检查
    └── lib/
        ├── ast-parser.ts             # AST 解析引擎
        ├── ast-utils.ts              # AST 遍历工具
        ├── bare_async_detector.ts    # 裸 async 无 catch 检测
        ├── bracket_access_detector.ts # 下标直接操作检测
        ├── config-loader.ts          # 配置加载 + glob 匹配引擎
        ├── config-migrator.ts        # 配置版本迁移
        ├── config-schema.ts          # 配置 schema 校验
        ├── const_let_detector.ts     # const 应改 let 检测
        ├── data_cleansing_detector.ts # 数据清洗检测
        ├── deep_copy_detector.ts     # JSON 深拷贝检测
        ├── direct_api_detector.ts    # 视图层直接 API 调用检测
        ├── duplicate_code_detector.ts # 重复代码块检测
        ├── eslint-helpers.ts         # ESLint 辅助工具
        ├── fix-utils.ts              # 修复工具函数
        ├── function_body.ts          # 函数体提取工具
        ├── indent_detector.ts        # Tab 缩进检测
        ├── logger.ts                 # 日志工具
        ├── long_transform_detector.ts # 组件内长数据转换检测
        ├── module_state_detector.ts  # 模块级状态变量检测
        ├── naming_detector.ts        # 命名规范检测
        ├── no_fs_promises_detector.ts # 禁止 fs.promises 检测
        ├── null_guard_detector.ts    # 空值保底检测
        ├── resource_leak_detector.ts # 资源未清理检测
        ├── semi_detector.ts          # 行尾分号检测
        ├── sync_method_detector.ts   # 同步方法检测
        └── fixers/
            ├── chain_call_fixer.ts   # 链式调用拆分修复器
            ├── const_to_let_fixer.ts # const 转 let 修复器
            ├── semi_fixer.ts         # 行尾分号删除修复器
            └── trim_fixer.ts         # 空值保底修复器

贡献指南

欢迎贡献！请遵循以下流程：

1. Fork 本仓库
2. 创建分支：git checkout -b feat/your-feature
3. 编写代码：确保通过所有现有测试
4. 添加测试：新功能或 bug 修复需要添加对应测试用例
5. 运行测试：npm run test
6. 提交 PR：提交前请确保：
   • 所有测试通过
   • 代码符合项目编码规范（文件头注释、函数注释）
   • 新工具或配置变更需要更新 README.md

开发环境

# 克隆仓库
git clone https://github.com/xueca/code-guardian.git
cd code-guardian

# 安装依赖
npm install

# 运行测试
npm run test

# 本地测试 MCP Server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | node dist/index.js --project-root .

新增检查工具

1. 在 tools/ 下创建新的检查模块，导出 async function(projectRoot, filePath)
2. 在 tools/lib/ 下创建检测器子模块（如需要）
3. 在 index.ts 中注册工具（添加到 TOOLS 数组和 handleToolCall switch）
4. 在 full_health_check.ts 中集成
5. 在 __tests__/ 中添加测试
6. 更新 README.md 的工具列表

常见问题

Q: Code Guardian 和 ESLint/Prettier 有什么区别？

A: Code Guardian 不是 ESLint 的替代品，而是互补层。ESLint 检查 JavaScript 语法和风格规则，Code Guardian 检查更高层次的架构问题（分层合规、反模式、文件行数）。Code Guardian 的 run_eslint 工具实际上是对 ESLint 的封装，将其集成到 AI 工作流中。

Q: 为什么选择 MCP 协议而不是直接作为 CLI 工具？

A: MCP（Model Context Protocol）是 AI 编码助手的标准协议。通过 MCP Server，AI 可以在修改代码时主动调用检查工具，无需人工干预。这比传统的 CLI 工具（需要手动运行）更高效，也比 Hook 机制（只能被动触发）更灵活。

Q: 必须在每个项目中配置 .code-guardian.json 吗？

A: 是的。Code Guardian 的设计原则是"每个项目有自己的编码标准"。.code-guardian.json 允许团队根据项目特点自定义文件行数限制、分层架构规则和反模式开关。Code Guardian 自带一个默认配置作为参考模板。

Q: run_eslint 工具报错怎么办？

A: 首先确认项目已安装 ESLint 及其插件：

npm install --save-dev eslint @eslint/js eslint-plugin-vue globals

然后检查 .code-guardian.json 中 eslint.configPath 是否指向了正确的 ESLint 配置文件。如果不需要 ESLint 检查，可以移除 eslint 配置项使其优雅降级。

Q: 如何自定义文件行数限制？

A: 在 .code-guardian.json 的 fileSizeLimits 中添加或修改 glob 模式。例如，如果希望 Vue 组件的行数上限为 300 行：

{
  "fileSizeLimits": {
    "**/*.vue": 300
  }
}

注意：规则从上到下匹配，第一个匹配的生效。建议将更具体的规则放在前面。

Q: 如何关闭某个反模式检测？

A: 在 .code-guardian.json 的 antiPatterns 中将对应检测项设为 false：

{
  "antiPatterns": {
    "duplicateCode": false
  }
}

Q: 支持哪些文件类型？

A: 支持 .vue、.js、.ts、.tsx 文件。ESLint 和注释检查针对 .vue 和 .js 文件功能完整，.ts / .tsx 文件的 check_file_size、validate_architecture、detect_anti_patterns 均可正常工作。

License

MIT