# @carlrannaberg/cclint 中文文档

规范地址：https://npmcn.com/package/%40carlrannaberg/cclint/

版本：0\.2\.10
npm 元数据更新时间：2025-09-10T12:46:26.599Z
中文译文更新时间：2026-11-09T04:24:26.039Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40carlrannaberg/cclint
原文对照：https://npmcn.com/package/%40carlrannaberg/cclint/?lang=original
项目主页：https://github.com/carlrannaberg/cclint#readme
源码仓库：https://github.com/carlrannaberg/cclint

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：179 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：7 个
- 首次发布：2025-08-23T21:52:33.593Z
- 最新版本发布：2025-09-10T12:46:26.433Z
- 近 30 天下载量：27954（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 0 个）

## 中文简介

Claude Code Lint - Claude Code 工程的综合林入工具

## 安装

```sh
npm install @carlrannaberg/cclint
```

也可以使用：`pnpm add @carlrannaberg/cclint`、`yarn add @carlrannaberg/cclint`、`bun add @carlrannaberg/cclint`

## README

# cclint (克劳德代码 Lint) Name

[![npm version](https://img.shields.io/npm/v/@carlrannaberg/cclint.svg)](https://www.npmjs.com/package/@carlrannaberg/cclint) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js Version](https://img.shields.io/node/v/@carlrannaberg/cclint.svg)](https://nodejs.org/)

用于Claude Code项目的综合林入工具,用于验证代理定义,命令配置,设置文件和项目文档.

## 特征

-   **代理/副代理Linting**: 验证前题、工具配置和命名惯例
-   **启动命令**: 检查斜线命令定义和工具权限
-   **设置验证**: 验证 `.claude/settings.json` 钩形配置
-   **文档 Linting**:确保CLAUDE.md遵循最佳做法和模板结构
-   **自定义外观支持**: 与 Zod 一起扩展基准计划, 用于特定项目的验证
-   **项目自动检测**: 使用目录爬升自动查找工程根
-   **多个输出格式**: 控制台、 JSON和Markdown报告
-   **CI/CD 友好组织**: 配置退出代码和静态模式

## 安装

```bash
# Install globally
npm install -g @carlrannaberg/cclint

# Install as dev dependency
npm install --save-dev @carlrannaberg/cclint

# Use without installing
npx @carlrannaberg/cclint
```

## 使用量

### 基本线性

```bash
# Lint current project (auto-detects root)
cclint

# Lint specific directory
cclint --root /path/to/project

# Quiet mode (minimal output)
cclint --quiet

# Verbose mode (show all files)
cclint --verbose
```

### 专业林廷

Lint 仅用于更快,有重点的验证的特定文件类型 :

```bash
# Lint only agent definition files
cclint agents

# Lint only command definition files  
cclint commands

# Lint only settings.json files
cclint settings

# Lint only CLAUDE.md context files
cclint context

# Use with options for specialized linting
cclint agents --verbose --follow-symlinks
cclint commands --root /path/to/project --quiet
```

### 报表生成

```bash
# Generate JSON report
cclint --format json --output lint-report.json

# Generate Markdown report
cclint --format markdown --output reports/lint-report.md
```

### CI/CD 一体化

```bash
# Fail on errors only (default)
cclint --fail-on error

# Fail on warnings or errors
cclint --fail-on warning

# Fail on suggestions, warnings, or errors
cclint --fail-on suggestion

# Disable custom schema validation
cclint --no-custom-schemas
```

### 共线支持

```bash
# Follow symlinks when discovering files (secure by default)
cclint --follow-symlinks

# Symlinks are NOT followed by default for security
# When enabled, validates that symlink targets remain within project root
# Useful for projects with shared agent/command definitions
```

## SDK/方案使用法

CCLint可以在您的节点.js应用程序中程序化地使用:

```javascript
import CClint from '@carlrannaberg/cclint';

// Create linter instance
const linter = new CClint();

// Lint entire project
const summary = await linter.lintProject('./my-project', {
  quiet: true,
  followSymlinks: true  // Enable symlink support
});

// Lint specific file types
const agentResults = await linter.lintAgents('./my-project');
const commandResults = await linter.lintCommands('./my-project');
```

### 返回类型已解释

**`lintProject()`** 返回 a `LintSummary`数字 :

```javascript
{
  totalFiles: 35,
  validFiles: 24,
  totalErrors: 11,
  totalWarnings: 2,
  totalSuggestions: 0,
  duration: 150,
  results: [...] // Array of all individual file results
}
```

**`lintAgents()`, (中文(简体) ), `lintCommands()`等 (中文(简体) ).** 返回时 `LintResult[]`数字 :

```javascript
[
  {
    file: '/path/to/agent.md',
    valid: true,
    errors: [],
    warnings: [],
    suggestions: [],
    missingFields: []
  },
  // ... more individual file results
]
```

### 使用大小写

-   **`lintProject()`**: 项目全面审定、CI/CD整合、综合报告
-   **`lintAgents()`**: 仅验证代理人定义,对以代理人为重点的工具有用
-   **`lintCommands()`**: 只验证命令定义, 对命令管理工具有用
-   **`lintSettings()`**: 验证设置.json,用于配置工具

## 它检查什么

### 克洛德官方代码字段

cclint对照克洛德代码的官方规格进行验证. 任何额外的字段必须通过自定义的图案扩展来添加.

#### 代理/代理前题字段

**要求 :**

-   `name` - 代理标识符(小写,有连字符的字母数字)
-   `description` - 关于何时援引的自然语言说明

**可选 :**

-   `tools` 或者说 `allowed-tools` - 工具访问: "\*" 面向所有人,或一系列工具名称
-   `model` - 首选模式:相声、相声、相声、相声、相声、相声
-   `color` - UI颜色(必须是:红色、蓝色、绿色、黄色、紫色、橙色、粉色、青色等颜色之一)

#### 命令前题字段

**所有字段都是可选的 :**

-   `description` - 命令描述( 默认从内容中第一个标题或行)
-   `allowed-tools` - 命令可以使用的工具(字符串格式:“工具1,工具2”)
-   `argument-hint` - UI 中显示的命令参数提示
-   `model` - 使用模型(与剂值相同)

### 代理/代理文件 (\*. md 有前题)

-   所需字段 : `name`, (中文(简体) ), `description`
-   QQ 工具配置和语法
-   • 颜色验证(8个有效的克洛德编码颜色:红色、蓝色、绿色、黄色、紫色、橙色、粉红色、青色)
-   ✅ 命名公约和文件名匹配
-   未知工具和已贬值的字段
-   内容优化建议

### 命令文件 (\*. md 有前题)

-   QQ 前题方案验证
-   工具权限 : `allowed-tools`
-   Bash 命令用途验证
-   文件参考模式
-   未知的工具和语法错误
-   缺少描述和参数提示

### 设置文件 (. claude/ settings.json)

-   JSON 语法和计划验证
-   虎克配置结构
-   活动类型和匹配者
-   命令语法验证
-   未知的钩子事件和工具
-   QQ 配置优化建议

### 文件(CLAUDE.md/AGENTS.md)

-   · 所需各科的存在
-   文件结构验证
-   QQ 模板遵守性检查
-   缺少的章节和内容
-   内容质量改进

## 项目结构检测

cclint 通过爬升目录自动检测您的工程根 :

-   `.git` 目录
-   `package.json` 文件
-   `.claude` 目录

然后扫描常见位置的文件:

```
project-root/
├── .claude/
│   ├── settings.json     # Settings validation
│   ├── agents/           # Agent definitions
│   └── commands/         # Command definitions
├── src/
│   ├── agents/           # Alternative agent location
│   └── commands/         # Alternative command location
├── CLAUDE.md             # Documentation validation
└── AGENTS.md             # Alternative documentation
```

## 配置

cclint通过使用合理默认和自动检测来进行不配置的工作. 对于高级用途,可以:

1.  **指定自定义路径** 与 `--root`
2.  **控制输出动词** 与 `--quiet`编号 :`--verbose`
3.  **选择输出格式** 与 `--format`
4.  **设定失败阈值** 与 `--fail-on`
5.  **创建自定义计划** 带有配置文件

### 自定义外观配置

cclint支持用你自己的Zod schemas来扩展基础验证计划,以满足项目的特定要求.

#### 配置文件

cclint 在以下文件中查找配置( 按优先级排序) :

-   `cclint.config.js` - Java脚本配置
-   `cclint.config.mjs` - ES模块配置
-   `cclint.config.ts` - 类型脚本配置(需要汇编)
-   `.cclintrc.json` - JSON配置
-   `.cclintrc.js` - Java脚本配置
-   `.cclintrc.mjs` - ES模块配置

#### JSON 配置示例

```json
{
  "agentSchema": {
    "extend": {
      "priority": "number",
      "tags": "array",
      "experimental": "boolean"
    }
  },
  "commandSchema": {
    "extend": {
      "timeout": "number",
      "retryCount": "number"
    }
  },
  "rules": {
    "unknownFields": "warning",
    "strict": true,
    "excludePatterns": ["**/legacy/**"]
  }
}
```

#### JavaScript 配置示例

```javascript
// cclint.config.js
import { z } from 'zod';

export default {
  agentSchema: {
    extend: {
      // Custom fields for agents
      priority: z.number().min(1).max(5).describe('Agent priority level'),
      tags: z.array(z.string()).optional().describe('Categorization tags'),
      experimental: z.boolean().optional().describe('Experimental feature flag'),
      owner: z.string().email().describe('Agent maintainer email')
    },
    customValidation: (data) => {
      const errors = [];
      
      // Custom validation logic
      if (data.experimental && !data.description?.includes('EXPERIMENTAL')) {
        errors.push('Experimental agents must include "EXPERIMENTAL" in description');
      }
      
      if (data.priority > 3 && !data.owner) {
        errors.push('High priority agents must have an owner assigned');
      }
      
      return errors;
    }
  },
  
  commandSchema: {
    extend: {
      timeout: z.number().positive().describe('Command timeout in milliseconds'),
      retryCount: z.number().min(0).max(3).default(0),
      async: z.boolean().optional().describe('Run command asynchronously')
    },
    customValidation: (data) => {
      const errors = [];
      
      if (data.async && !data.timeout) {
        errors.push('Async commands must specify a timeout');
      }
      
      return errors;
    }
  },
  
  settingsSchema: {
    extend: {
      // Custom settings fields
      customHooks: z.record(z.array(z.string())),
      teamSettings: z.object({
        lead: z.string(),
        members: z.array(z.string())
      }).optional()
    }
  },
  
  claudeMdRules: {
    requiredSections: [
      'project overview',
      'setup instructions', 
      'development workflow',
      'testing strategy'
    ],
    customValidation: (content, sections) => {
      const errors = [];
      
      if (!content.includes('## Security')) {
        errors.push('CLAUDE.md must include a Security section');
      }
      
      return errors;
    }
  },
  
  rules: {
    unknownFields: 'error',
    strict: true,
    includePatterns: ['custom-agents/**'],
    excludePatterns: ['**/legacy/**', '**/deprecated/**']
  }
};
```

#### 类型脚本配置示例

```typescript
// cclint.config.ts
import { z } from 'zod';
import type { CclintConfig } from 'cclint';

const AgentPriority = z.enum(['low', 'medium', 'high', 'critical']);

const config: CclintConfig = {
  agentSchema: {
    extend: {
      priority: AgentPriority,
      team: z.string().min(1),
      version: z.string().regex(/^\d+\.\d+\.\d+$/)
    }
  }
};

export default config;
```

#### Schema 覆盖示例

为了完全控制,您可以覆盖整个计划:

```javascript
// cclint.config.js
import { z } from 'zod';

export default {
  agentSchema: {
    override: z.object({
      // Completely custom schema
      id: z.string().uuid(),
      name: z.string().min(1),
      version: z.string(),
      config: z.record(z.unknown())
    }).strict()
  }
};
```

#### 配置选项

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `agentSchema.extend` | `Record<string, ZodType>` | 代理前题的额外字段 |
| `agentSchema.override` | `ZodType` | 完全替换剂剂计划a |
| `agentSchema.customValidation` | `(data) => string[]` | 自定义验证功能 |
| `commandSchema.*` | 与代理人相同 | 自定义命令计划配置 |
| `settingsSchema.*` | 与代理人相同 | 自定义设置方案配置 |
| `claudeMdRules.requiredSections` | `string[]` | CLAUDE.md 所需各款 |
| `claudeMdRules.recommendedSections` | `string[]` | 建议的款次 |
| `claudeMdRules.customValidation` | `(content, sections) => string[]` | 自定义验证 |
| `rules.unknownFields` | `'error' | 'warning' | 'suggestion' | 'ignore'` | 如何处理未知字段 |
| `rules.strict` | `boolean` | 启用严格的模式验证 |
| `rules.includePatterns` | `string[]` | 要包含的其他文件模式 |
| `rules.excludePatterns` | `string[]` | 要排除的文件模式 |

## 实例

### GitHub 动作集成

```yaml
name: Claude Code Lint
on: [push, pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      - run: npm install -g @carlrannaberg/cclint
      - run: cclint --fail-on warning
```

### 承诺前虎克

```bash
#!/bin/sh
# .git/hooks/pre-commit
cclint --quiet --fail-on error
```

### 报表生成脚本

```bash
#!/bin/bash
# scripts/lint-report.sh
mkdir -p reports
cclint --format markdown --output reports/claude-lint-$(date +%Y%m%d).md
echo "Lint report generated in reports/"
```

## 退出代码

-   `0`: 成功(无超过故障阈值的问题)
-   `1`: 故障(发现的问题高于故障阈值)

## 捐款

1.  叉子存储器
2.  创建特性分支
3.  做你的改变
4.  在适用的情况下添加测试
5.  提交拉动请求

## 许可证

麻省理工学院

## 相关项目

-   [克劳德代码](https://claude.ai/code) - AI动力编码助理

## 常见问题

### @carlrannaberg/cclint 是什么？

Claude Code Lint - Claude Code 工程的综合林入工具

### 如何安装 @carlrannaberg/cclint？

在项目目录运行 npm install @carlrannaberg/cclint，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cclint，可以用 npx cclint 直接运行。

### @carlrannaberg/cclint 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @carlrannaberg/cclint 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @carlrannaberg/cclint 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @carlrannaberg/cclint 可以商用吗？

@carlrannaberg/cclint 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @carlrannaberg/cclint 的下载量有多少？

根据 npm 官方下载统计，@carlrannaberg/cclint 在 2026/10/09 – 2026/11/07 这 30 天内被下载 27,954 次，日均约 932 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @carlrannaberg/cclint 还在维护吗？

最新版本 0\.2\.10 发布于 2025/09/10（1\.2 年前）；至今共发布 12 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/08/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。