# @lvxiaohui/ai-rule

> Compile one source of AI rules and Skills through editor plugins

Latest version **2.0.0** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @lvxiaohui/ai-rule
pnpm add @lvxiaohui/ai-rule
yarn add @lvxiaohui/ai-rule
bun add @lvxiaohui/ai-rule
```

Provides the command `ai-rule`.

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-09-24 |
| First published | 2026-06-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 0 |
| Unpacked size | 82.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | lvxiaohui |
| Maintainers | lvxiaohui |
| Keywords | ai-rule, codex, trae, cursor, plugin, skills |

## Links

- npm: https://www.npmjs.com/package/@lvxiaohui/ai-rule
- Repository: https://gitee.com/changyuxiaohui/ai-rule
- Homepage: https://gitee.com/changyuxiaohui/ai-rule#readme
- Issues: https://gitee.com/changyuxiaohui/ai-rule/issues
- npm.io page: https://npm.io/package/@lvxiaohui/ai-rule

## Recent versions

- 2.0.0 (latest) — 2026-09-24
- 1.0.3 — 2026-06-11
- 1.0.2 — 2026-06-11

## README

# ai-rule 2.x

`ai-rule` 将项目中的规则和 Agent Skills 编译到多个 AI 编辑器的项目配置格式。2.x 使用插件架构：核心只处理源文件、统一中间模型、校验和安全写入；每个编辑器由独立插件负责。

2.0 首发支持 Cursor、Codex、Trae。MCP 不属于 2.0，发现 `.ai-rules/mcp/` 会诊断并在严格模式下阻止构建。2.x 不兼容 1.x 的配置、命令别名和输出目录。

## 安装与使用

```bash
npm install -D @lvxiaohui/ai-rule
```

需要 Node.js 18 或更高版本。

先创建 `.ai-rules/rules/project.mdc`，例如写入 `# Project rules` 和项目约定，再执行：

```bash
npx ai-rule compile --target=cursor,codex,trae
```

当前插件状态为 `preview`：已完成本地编译测试，真实编辑器和跨平台验收进度见[能力矩阵](./docs/agent-capability-matrix.md)。

默认源目录：

```text
.ai-rules/
├── rules/**/*.mdc
├── skills/**/SKILL.md
└── workflows/**/*.md
```

规则和 Skill 的 frontmatter 会被解析并保留；Skill 目录中的附属资源（含隐藏资源和二进制文件）会复制，并保留脚本执行权限。VCS 元数据目录和 `.DS_Store` 不复制。未知字段不会静默删除。Workflow 在 2.0 先进入统一模型，三个首发插件暂不生成对应文件。

frontmatter 使用 YAML 子集，支持标量、字符串列表和 `|` / `>` 多行文本（含 `+` / `-` 换行保留标记）；不承诺完整 YAML 语法。Skill 必须显式提供与目录名一致的 `name` 和非空 `description`。

## 配置

在项目根目录创建 `.ai-rules.config.json`：

```json
{
  "sourceDir": ".ai-rules",
  "targets": ["cursor", "codex", "trae"],
  "strict": true,
  "plugins": [],
  "targetVersions": {}
}
```

`plugins` 只接受显式 npm 包名或相对本地路径，不会自动遍历 `node_modules`。`strict` 会把目标端无法表达的语义损失升级为错误。

`targetVersions` 仅在插件声明可验证版本边界时使用，值须为完整语义版本，例如 `1.2.3` 或 `1.2.3-rc.1`；当前内置插件未声明最低版本，通常保留空对象。

例如带 Cursor `globs`/`alwaysApply` 的规则编译到 Codex 时会产生 scope loss 诊断；确认接受该差异后可使用 `--no-strict`。

## CLI

```text
ai-rule compile [--target=cursor,codex,trae] [--clean] [--dry-run]
ai-rule validate [--strict|--no-strict]
ai-rule capabilities [--target=cursor]
ai-rule plugins
ai-rule --version
```

`validate` 只检查源文件模型；检查目标映射和输出冲突请使用 `compile --dry-run`。默认严格模式下，不支持的 Workflow 会阻止编译；只有明确接受不输出该内容时才使用 `--no-strict`。

生成文件由 `.ai-rules/.generated-manifest.json` 跟踪。再次编译只同步本次选择的目标，保留其他目标的文件与清单记录。源文件删除后，本次目标中对应的旧生成文件会在确认未被用户修改后清理；未跟踪的手写文件与修改过的过期文件会保留，不会整目录删除。

普通编译已经包含上述过期文件清理。`--clean` 保留为显式清理选项，执行同样的事务流程，不会在校验之前提前删除。插件失败或写入失败时保留/恢复旧输出。`--dry-run` 列出计划生成的文件且不写磁盘；`--force` 才允许覆盖冲突的现有输出文件。`--target cursor` 和 `--target=cursor` 均支持，`--target=all` 包含显式加载的第三方插件。

## 输出位置

- Cursor：`.cursor/rules/**/*.mdc`、`.cursor/skills/**`
- Codex：根目录 `AGENTS.md`、`.agents/skills/**`
- Trae：`.trae/rules/**/*.md`、`.trae/skills/**`

## API

```js
const { compileProject, listPlugins } = require('@lvxiaohui/ai-rule');

const result = compileProject({
  cwd: process.cwd(),
  target: ['cursor', 'codex', 'trae']
});
if (result.failed.length) process.exitCode = 1;
```

## 开发插件

插件是普通 CommonJS 模块，必须导出 `id`、`apiVersion: "1"`、目标 Agent 版本元数据、`getCapabilities()` 和同步的 `compile({ ir, ... })` 函数。插件应只返回 `{ files, diagnostics }`，不直接修改用户项目；任何 error 诊断都会阻止整轮写入。插件通过 Node.js `require()` 在同一进程加载，纯编译是开发约定，并非执行沙箱；只加载信任的插件。可在配置中显式加载：

```json
{ "plugins": ["my-ai-rule-plugin"] }
```

详见[插件开发](./docs/plugin-development.md)、[能力矩阵](./docs/agent-capability-matrix.md)和[发布流程](./docs/releasing.md)。

详见[插件开发](./docs/plugin-development.md)、[能力矩阵](./docs/agent-capability-matrix.md)和[发布流程](./docs/releasing.md)。

## License

MIT

---
_Source: https://npm.io/package/@lvxiaohui/ai-rule · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._