code-guardian
by xueca
README.md
# Code Guardian
[](https://github.com/xueca/code-guardian/pkgs/npm/code-guardian)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
Code Guardian 是一个 MCP (Model Context Protocol) Server，为 AI 编码助手（如 Claude Code、Trae、Cursor、Windsurf 等）提供代码质量检查能力。它能在 AI 修改代码前后自动检查文件大小、ESLint、架构分层合规、反模式扫描和注释规范，确保 AI 生成的代码符合项目团队的编码标准。
## 目录
- [前置要求](#前置要求)
- [安装](#安装)
- [快速开始](#快速开始)
- [工作原理](#工作原理)
- [7 个检查工具](#7-个检查工具)
- [配置参考](#配置参考)
- [与 AI 规则联动](#与-ai-规则联动)
- [四层防御体系](#四层防御体系)
- [运行测试](#运行测试)
- [项目结构](#项目结构)
- [贡献指南](#贡献指南)
- [常见问题](#常见问题)
- [License](#license)
## 前置要求
- **Node.js** >= 18.0.0（MCP SDK 依赖）
- **ESLint** >= 9.0.0（可选，`run_eslint` 工具需要）
- 项目需要有一个 `.code-guardian.json` 配置文件（详见[配置参考](#配置参考)）
## 安装
### 方式一：从 GitHub Packages 安装（推荐）
**首次使用需配置 scope registry**（一次性操作）：
```bash
# 配置 @xueca scope 指向 GitHub Packages
npm config set @xueca:registry https://npm.pkg.github.com
# 配置认证 Token（需 GitHub Personal Access Token，勾选 read:packages 权限）
npm config set //npm.pkg.github.com/:_authToken YOUR_GITHUB_TOKEN
```
**安装**：
```bash
npm install @xueca/code-guardian --save-dev
```
> Token 生成地址：https://github.com/settings/tokens（Classic Token，勾选 `read:packages`）
### 方式二：从 GitHub 源码安装
```bash
npm install --save-dev github:xueca/code-guardian
```
> 需要 [Git](https://git-scm.com/) 已安装且可访问 GitHub。
### 方式三：本地开发安装
```bash
git clone https://github.com/xueca/code-guardian.git
cd code-guardian
npm install
```
## 快速开始
### 1. 创建项目配置文件
在项目根目录创建 `.code-guardian.json`：
```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`）：
```json
{
"mcpServers": {
"code-guardian": {
"command": "npx",
"args": [
"-y",
"@xueca/code-guardian",
"--project-root",
"."
]
}
}
}
```
**Trae**（`.trae/mcp.json`）：
```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`）：
```json
{
"mcpServers": {
"code-guardian": {
"command": "npx",
"args": [
"-y",
"@xueca/code-guardian",
"--project-root",
"."
]
}
}
}
```
> **关于 `npx -y @xueca/code-guardian`**：首次使用前需完成[方式一](#方式一从-github-packages-安装推荐)中的 scope registry 配置。`-y` 参数表示自动确认安装。如果你更倾向于使用 `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](https://www.jsonrpc.org/specification) 协议、通过 `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 模式从上到下匹配，第一个匹配的规则生效。
**返回示例**：
```json
{
"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`。
**返回示例**：
```json
{
"ok": true,
"filePath": "src/views/Home.vue",
"errorCount": 0,
"warningCount": 3,
"messages": [
{ "line": 42, "severity": "warning", "message": "...", "ruleId": "vue/attributes-order" }
]
}
```
**如果 ESLint 未安装或配置缺失**：
```json
{
"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 未配对清理
**返回示例**：
```json
{
"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` |
**返回示例**：
```json
{
"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`）
- **函数注释**：检查函数定义前是否有注释（支持单行 `//` 和块注释 `/** */`）
**返回示例**：
```json
{
"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 项检查，输出结构化的一键报告：
```json
{
"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 原样保留，异常时中止不写入
**返回示例**：
```json
{
"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` 配置项：
```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`）：
```markdown
# 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`）：
```markdown
# 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）** 是最后一道防线，在代码提交前确保所有文件通过检查。
## 运行测试
```bash
# 运行所有测试（含编译）
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
### 开发环境
```bash
# 克隆仓库
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 及其插件：
```bash
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 行：
```json
{
"fileSizeLimits": {
"**/*.vue": 300
}
}
```
注意：规则从上到下匹配，第一个匹配的生效。建议将更具体的规则放在前面。
### Q: 如何关闭某个反模式检测？
A: 在 `.code-guardian.json` 的 `antiPatterns` 中将对应检测项设为 `false`：
```json
{
"antiPatterns": {
"duplicateCode": false
}
}
```
### Q: 支持哪些文件类型？
A: 支持 `.vue`、`.js`、`.ts`、`.tsx` 文件。ESLint 和注释检查针对 `.vue` 和 `.js` 文件功能完整，`.ts` / `.tsx` 文件的 `check_file_size`、`validate_architecture`、`detect_anti_patterns` 均可正常工作。
## License
[MIT](LICENSE)
This server cannot be deployed
Maintenance
ActivitySlowing
ResponsivenessNo issues