# @lousy-agents/lint 中文文档

规范地址：https://npmcn.com/package/%40lousy-agents/lint/

版本：5\.22\.24
npm 元数据更新时间：2026-11-01T17:41:21.441Z
中文译文更新时间：2026-11-01T19:07:20.500Z
软件包许可：BSD-2-Clause-Patent

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

原始 npm 页面：https://www.npmjs.com/package/%40lousy-agents/lint
原文对照：https://npmcn.com/package/%40lousy-agents/lint/?lang=original
项目主页：https://github.com/zpratt/lousy-agents/tree/main/packages/lint#readme
源码仓库：https://github.com/zpratt/lousy-agents

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

- 包体积（解压后）：3.1 MB，16 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2026-04-15T12:08:41.769Z
- 最新版本发布：2026-11-01T17:41:21.138Z
- 已发布版本数：117（近 12 个月 117 个）

## 中文简介

用于验证AI编码助手配置的编程lint API -技能，代理，钩子和指令

## 安装

```sh
npm install @lousy-agents/lint
```

也可以使用：`pnpm add @lousy-agents/lint`、`yarn add @lousy-agents/lint`、`bun add @lousy-agents/lint`

## README

# @lousy-agents /线头

用于AI代理技能、代理、钩子和指令文件的编程lint API。使用这个包可以在没有CLI的情况下，将低级代理的lint检查集成到您自己的工具、web应用程序或CI管道中。

有关基于cli的检测，请参见 [`lint` 命令文件](https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md).

## 安装

```bash
npm install @lousy-agents/lint
```

## 快速入门

```typescript
import { runLint } from '@lousy-agents/lint';

const result = await runLint({ directory: '/path/to/project' });

if (result.hasErrors) {
  console.error('Lint failed');
  for (const output of result.outputs) {
    for (const diagnostic of output.diagnostics) {
      console.error(`${diagnostic.filePath}:${diagnostic.line} [${diagnostic.severity}] ${diagnostic.message}`);
    }
  }
}
```

## API

### `runLint(options): Promise<LintResult>`

在项目目录上运行所有lint检查并返回结构化结果。

```typescript
import { runLint, LintValidationError } from '@lousy-agents/lint';

try {
  const result = await runLint({
    directory: '/path/to/project',
    targets: {
      skills: true,
      agents: true,
      hooks: false,       // skip hook linting
      instructions: false, // skip instruction linting
    },
  });

  console.log('Has errors:', result.hasErrors);
  console.log('Outputs:', result.outputs.length);
} catch (error) {
  if (error instanceof LintValidationError) {
    console.error('Invalid input:', error.message);
  } else {
    throw error;
  }
}
```

**选项:**

| 财产 | 类型 | 要求 | 描述 |
| --- | --- | --- | --- |
| `directory` | `string` | ✅ | 要检测的项目目录的绝对或相对路径 |
| `targets.skills` | `boolean` | \- - - - - - | 绒线技能： `.github/skills/*/SKILL.md`， `.claude/skills/*/SKILL.md`， `.agents/skills/*/SKILL.md`， `.pi/skills/*/SKILL.md`， `.pi/prompts/*/SKILL.md` (技能列在根 `skills-lock.json` 省略了) |
| `targets.agents` | `boolean` | \- - - - - - | 棉绒剂前料在 `.github/agents/**/*.md` |
| `targets.subagents` | `boolean` | \- - - - - - | **仅标记（非GA）** -把克劳德代码子代理的前体物塞进去 `.claude/agents/**/*.md`． 除非显式地运行，否则永远不会运行 `true`，即使在 `targets` 完全省略了 |
| `targets.hooks` | `boolean` | \- - - - - - | 绒钩配置： `.github/hooks/agent-shell/hooks.json` (副驾驶), `.claude/settings.json` 和 `.claude/settings.local.json` (Claude);只有当内容 `preToolUse` / `PreToolUse`;符号链接跳过 |
| `targets.instructions` | `boolean` | \- - - - - - | 棉绒指导质量： `.github/copilot-instructions.md`， `.github/instructions/*.md`， `.github/agents/*.md` （两用同剂），根 `AGENTS.md`、根 `CLAUDE.md` |
| `targets.mcpServers` | `boolean` | \- - - - - - | **仅标记（非GA）** -验证MCP服务器配置文件： `.mcp.json`， `.vscode/mcp.json`． 除非显式地运行，否则永远不会运行 `true`，即使在 `targets` 完全省略了 |
| `logger` | `LintLogger` | \- - - - - - | 用于网关诊断的自定义记录器(必须具有 `.warn` 方法);默认为 `consola` |

当 `targets` 省略或所有标志都是 `false`, **default-enabled** 目标运行：技能，特工，诱饵，指令。 `subagents` 和 `mcpServers` 仅标记是分阶段推出的一部分吗 [构建覆盖](https://github.com/zpratt/lousy-agents/issues/1039)) -并且仅在显式设置为时运行 `true`，即使没有设置其他标志。

发现路径来自中的规范代理位置目录 `@lousy-agents/core`，与…分享 `doctor`． Doctor可能会列出其他尚未验证的构造（插件、多线束指令树等）。有意的差异: `skills-lock.json` 过滤（仅限lint），钩子 `PreToolUse` / `preToolUse` 内容启发式（仅限lint），仅适用于两者 `.claude/settings*.json` / `.github/hooks/agent-shell/hooks.json` 精确的路径（保留，而不是放松，对于这次推出），以及符号链接策略（lint跳过；医生遵循repo）。

**抛出 `LintValidationError`** 当 `directory` 为空、包含控制字符、路径遍历序列、不存在或不是目录。

* * *

### `createFormatter(format): LintFormatter`

创建用于呈现的输出格式化程序 `LintOutput[]` 到一个字符串。

```typescript
import { runLint, createFormatter } from '@lousy-agents/lint';

const result = await runLint({ directory: '/path/to/project' });
const formatter = createFormatter('human');
console.log(formatter.format(result.outputs));
```

| 格式 | 描述 |
| --- | --- |
| `'human'` | 人类可读的文本，每行一个诊断 |
| `'json'` | 所有诊断的JSON数组 |
| `'rdjsonl'` | [Reviewdog诊断格式](https://github.com/reviewdog/reviewdog) JSONL（每行一个JSON对象）——用于CI集成 |

* * *

### `DEFAULT_LINT_RULES`

没有时使用的默认规则配置 `lousy-agents.config.ts` 是礼物。使用它来检查或扩展默认规则集。

```typescript
import { DEFAULT_LINT_RULES } from '@lousy-agents/lint';

console.log(DEFAULT_LINT_RULES.skills);
// { 'skill/missing-name': 'error', 'skill/missing-description': 'error', ... }
```

* * *

### `LintValidationError`

当用户提供的输入验证失败时抛出。捕获此错误以区分用户输入错误和系统错误。

```typescript
import { runLint, LintValidationError } from '@lousy-agents/lint';

try {
  await runLint({ directory: '' });
} catch (error) {
  if (error instanceof LintValidationError) {
    // directory was empty, missing, or not a directory
    console.error(error.message);
  }
}
```

* * *

## 类型

```typescript
import type {
  LintResult,
  LintOutput,
  LintDiagnostic,
  LintSeverity,
  LintTarget,
  LintOptions,
  LintLogger,
  LintRulesConfig,
  LintFormatType,
  LintFormatter,
  InstructionQualityResult,
} from '@lousy-agents/lint';
```

**主要类型:**

| 类型 | 描述 |
| --- | --- |
| `LintResult` | 顶级的结果: `outputs` 阵列+ `hasErrors` 布尔 |
| `LintOutput` | Per-target结果: `diagnostics`， `filesAnalyzed`， `summary`、可选 `qualityResult` |
| `LintDiagnostic` | 单一的诊断: `filePath`， `line`， `severity`， `message`， `ruleId`， `target` |
| `LintSeverity` | `"error" | "warning" | "info"` |
| `LintTarget` | `"skill" | "agent" | "subagent" | "instruction" | "hook" | "mcp-server"` |
| `InstructionQualityResult` | 教学质量分数和建议（填充时） `instructions` 目标运行) |

* * *

## 自定义日志记录器

传递任何带有 `.warn` 抑制或重定向网关诊断的方法：

```typescript
import { runLint } from '@lousy-agents/lint';
import { createLogger } from 'your-logger';

const logger = createLogger('lint');
await runLint({
  directory: '/path/to/project',
  logger: { warn: (msg, ...args) => logger.warn(msg, ...args) },
});
```

* * *

## CI集成（rdjsonl）

基于注释的CI反馈以Reviewdog诊断格式输出：

```bash
node -e "
const { runLint, createFormatter } = require('@lousy-agents/lint');
runLint({ directory: '.' }).then(r => {
  process.stdout.write(createFormatter('rdjsonl').format(r.outputs));
  process.exit(r.hasErrors ? 1 : 0);
});
"
```

* * *

## 相关的文档

-   [`lint` CLI命令](https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md) -基于cli的检测 `npx @lousy-agents/cli lint`
-   [GitHub行动](https://github.com/zpratt/lousy-agents/blob/main/docs/lint.md#github-action) -在GitHub Actions中运行linting而无需安装Node.js

## 常见问题

### @lousy-agents/lint 是什么？

用于验证AI编码助手配置的编程lint API -技能，代理，钩子和指令

### 如何安装 @lousy-agents/lint？

在项目目录运行 npm install @lousy-agents/lint，或使用 pnpm add / yarn add / bun add。

### @lousy-agents/lint 支持 TypeScript 吗？

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

### @lousy-agents/lint 支持 ESM 还是 CommonJS？

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

### @lousy-agents/lint 可以商用吗？

@lousy-agents/lint 使用 BSD-2-Clause-Patent 许可。声明的许可为 BSD-2-Clause-Patent，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @lousy-agents/lint 还在维护吗？

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