@lvxiaohui/ai-rule
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 的配置、命令别名和输出目录。
安装与使用
npm install -D @lvxiaohui/ai-rule需要 Node.js 18 或更高版本。
先创建 .ai-rules/rules/project.mdc，例如写入 # Project rules 和项目约定，再执行：
npx ai-rule compile --target=cursor,codex,trae当前插件状态为 preview：已完成本地编译测试，真实编辑器和跨平台验收进度见能力矩阵。
默认源目录：
.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：
{
"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
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 --versionvalidate 只检查源文件模型；检查目标映射和输出冲突请使用 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
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() 在同一进程加载，纯编译是开发约定，并非执行沙箱；只加载信任的插件。可在配置中显式加载：
{ "plugins": ["my-ai-rule-plugin"] }License
MIT