trek-ai-rules

Multi-client AI agent rules templates (Claude Code / Cursor / Codex / Copilot / Trae) with {{project.X}} placeholder syntax that the CLI renders from the host's ai.config.ts.

Node ≥ 22 · MIT · Pure ESM

Install

pnpm add trek-ai-rules

通常你不需要直接装这个包 —— 它是 trek-ai-cli 的内部依赖,通过 ai-agent rules sync 命令使用。但是如果你要做自定义 rules 渲染(比如 嵌进 IDE 插件里),可以直接用它的 API。

Subpath exports

| Subpath | 内容 | 用途 | |---|---|---| | trek-ai-rules | barrel: getTemplatesDir / renderClientRules / clientMirrorDir / listClientTemplates / SupportedClient / RulesContext / RenderResult | 程序化调用 | | trek-ai-rules/templates/* | 原始 .md / .mdc 模板文件 | 手工编辑 / fork 单个模板 |

5 个内置 client

| SupportedClient | 模板源目录 | 渲染到宿主目录 | |---|---|---| | 'claude' | templates/claude/ | .claude/agents/ | | 'cursor' | templates/cursor/ | .cursor/rules/ | | 'codex' | templates/codex/ | .codex/ | | 'copilot' | templates/copilot/ | .github/agents/ | | 'trae' | templates/trae/ | .trae/rules/ |

'claude'、'cursor' 这些不是字符串字面量 —— TS 5.x 的 string literal union,拼错会编译失败。DEMO_CLIENT = '_demo' 是保留名,不会被自动 渲染(用来在测试 fixture 里放占位模板)。

占位符语法

模板里所有 {{project.<field>}} 会被替换成 RulesContext.project[field]。 当前支持的字段(RulesContext.project):

interface RulesContext {
  project: {
    name: string              // {{project.name}}
    displayName: string       // {{project.displayName}}
    componentRoot: string     // {{project.componentRoot}}
    docRoot: string           // {{project.docRoot}}
    exampleRoot: string       // {{project.exampleRoot}}
    i18nPath?: string         // {{project.i18nPath}}
    testCommand: string       // {{project.testCommand}}
    e2eCommand: string        // {{project.e2eCommand}}
    lintCommand: string       // {{project.lintCommand}}
    typecheckCommand: string  // {{project.typecheckCommand}}
    docsBuildCommand: string  // {{project.docsBuildCommand}}
    docsDevCommand: string    // {{project.docsDevCommand}}
    buildCommand: string      // {{project.buildCommand}}
    devCommand: string        // {{project.devCommand}}
    cleanCommand: string      // {{project.cleanCommand}}
    packagePrefix: string     // {{project.packagePrefix}}
    packageScope: string      // {{project.packageScope}}
    registry: string          // {{project.registry}}
    sidebarConfig: string     // {{project.sidebarConfig}}
  }
}

如果模板里写了 {{project.foo}} 但 ctx.project.foo 是 undefined, 占位符原样保留(不报错),方便你在审查渲染结果时一眼看到缺失的字段。

快速上手

1. 程序化调用(自定义集成)

import {
  renderClientRules,
  getTemplatesDir,
  listClientTemplates,
  clientMirrorDir,
} from 'trek-ai-rules'

// 看 claude client 都有哪些模板
const files = await listClientTemplates('claude')
// → [
//     'element-plus-architect.md',
//     'element-plus-developer.md',
//     'element-plus-reviewer.md',
//     ...
//   ]

// 模板目录在哪?(npm 装完后定位)
const tmplDir = getTemplatesDir()
// → '/your/project/node_modules/trek-ai-rules/templates'

// 渲染到指定宿主根目录
const results = await renderClientRules('claude', '/path/to/host/repo', {
  project: {
    name: 'element-plus',
    displayName: 'Element Plus',
    componentRoot: 'packages/components',
    docRoot: 'docs/en-US/component',
    exampleRoot: 'docs/examples',
    testCommand: 'pnpm exec ai-agent test',
    e2eCommand: 'pnpm exec ai-agent test:e2e',
    lintCommand: 'pnpm exec ai-agent lint',
    typecheckCommand: 'pnpm exec ai-agent typecheck',
    docsBuildCommand: 'pnpm exec ai-agent docs:build',
    docsDevCommand: 'pnpm exec ai-agent docs:dev',
    buildCommand: 'pnpm exec ai-agent build',
    devCommand: 'pnpm exec ai-agent dev',
    cleanCommand: 'pnpm exec ai-agent clean',
    packagePrefix: '@element-plus/components',
    packageScope: '@element-plus',
    registry: 'packages/element-plus/component.ts',
    sidebarConfig: 'docs/.vitepress/i18n/pages/component.json',
  },
})

results.forEach(r => {
  console.log(`${r.outputPath}  (${r.substitutions} substitutions)`)
})
// → /path/to/host/repo/.claude/agents/element-plus-architect.md  (12 substitutions)
// → /path/to/host/repo/.claude/agents/element-plus-developer.md  (15 substitutions)
// → ...

2. 通过 ai-agent rules sync 调用(常用)

# 在你的项目根目录
npx ai-agent rules sync

# 看每个 client 都有哪些模板
npx ai-agent rules list

CLI 会自动从 ai.config.ts 构造 RulesContext,不需要你手写。

3. 单独渲染一个 client(调试用)

npx ai-agent rules sync --only=claude
npx ai-agent rules sync --only=cursor,trae

完整 API 速查

| 导出 | 类型 | 说明 | |---|---|---| | renderClientRules | (client, hostRoot, ctx) => Promise<RenderResult[]> | 递归渲染某个 client 的所有模板 | | renderGuides | (hostRoot, ctx) => Promise<RenderResult[]> | 递归渲染根级 AI 指南(AGENTS.md + AI_AGENT_*.md)到宿主仓库根 | | getTemplatesDir | () => string | 模板根目录(包内的 templates/) | | clientMirrorDir | (client) => string | client 渲染到宿主哪个子目录(.claude/agents 等) | | listClientTemplates | (client) => Promise<string[]> | 列出某个 client 的所有模板文件(相对路径) | | SupportedClient | 'claude' \| 'cursor' \| 'codex' \| 'copilot' \| 'trae' | 5 个内置 client 的字面量联合 | | DEMO_CLIENT | '_demo' | 保留名,不会自动渲染 | | GUIDE_CLIENT | 'guides' | templates/guides/ 的保留 client 键(不是真实 AI client) | | RulesContext | interface | 渲染时需要的上下文 | | RenderResult | { outputPath: string, substitutions: number } | 每次写入的结果 |

根级指南渲染(guides)

templates/guides/ 下存放面向宿主仓库根的 AI 上下文指南——AGENTS.md、 AI_AGENT_COMPLETE_GUIDE.md、AI_AGENT_GUIDE.md、AI_AGENT_ARCHITECTURE.md。 这些文件描述一个仓库所有 AI client 的"宪法 + 架构 + 工作流",由 trek-ai-cli 的 rules sync 一并渲染,宿主不应把它们纳入版本管理:

import { renderGuides } from 'trek-ai-rules'
const results = await renderGuides(hostRoot, ctx)
// results → [{ outputPath: '<hostRoot>/AGENTS.md', ... }, ...]

• 占位符语法、substitute / resolveKey 语义与 client 模板完全一致({{project.X}})
• cli 侧对应的用户命令是 ai-agent rules sync(cli README 的"项目命令"一节)
• 如果你想改指南内容,编辑 templates/guides/* 后重跑 rules sync,不要在宿主里手改

添加新 client

1. 在 templates/<new-client>/ 下加 .md / .mdc 文件
2. 在 src/index.ts 的 SupportedClient union 加新字面量
3. 在 clientMirrorDir() 加一个 case

// src/index.ts
export type SupportedClient =
  | 'claude'
  | 'cursor'
  | 'codex'
  | 'copilot'
  | 'trae'
  | 'aider'  // ← 新增

export function clientMirrorDir(client: SupportedClient): string {
  switch (client) {
    // ... 已有 case
    case 'aider':
      return '.aider/rules'
    // ...
  }
}

下次 ai-agent rules sync 会自动发现新 client。

添加新占位符字段

1. 改 RulesContext.project 的 type
2. 在 trek-ai-cli 的 toRulesContext(cfg) 里读 cfg.commands.xxx 之类塞进去
3. 在模板里写 {{project.xxx}}

不能做的事:占位符不能跨层级访问({{a.b.c.d}})。resolveKey() 只支持 ctx.project.field 形式的扁平访问,深层访问会被原样保留。

License

MIT.