trek-ai-cli

trek-ai-cli

40+ 个 ai-agent 子命令 + MCP stdio server，适用于任何 Vue 组件库项目。装上之后 在项目根目录跑 npx ai-agent init 生成 ai.config.ts,所有命令都从 这个文件读宿主布局。

Node ≥ 22 · MIT · 安装即得 ai-agent 二进制

Install

pnpm add -D trek-ai-cli

(trek-ai-cli 是个 dev tool,不应该装成 production 依赖。)

装完会有一个 ai-agent bin 在 node_modules/.bin/,或者直接 npx ai-agent ...。

一行快速开始

# 1. 初始化(在项目根目录生成 ai.config.ts)
npx ai-agent init

# 2. 编辑 ai.config.ts,告诉 CLI 项目布局(component 根、docs 根、测试命令等)

# 3. 装 pre-commit / pre-push hooks(可选)
npx ai-agent hook install

# 4. 跑一条命令试试
npx ai-agent check docs-render

ai.config.ts 配置契约

ai-agent init 生成的文件长这样(通用 Vue 组件库,字段按你的项目改):

import { defineConfig } from 'trek-ai-cli'

export default defineConfig({
  // 1. 项目标识(模板里 {{project.name}} 用)
  name: 'my-component-lib',
  // displayName: 'My Component Lib', // 可选,展示名(默认=name)

  // 2. 项目根(默认 = 配置文件所在目录)
  // root: '/abs/path/to/repo',

  // 3. 项目形态
  profile: {
    kind: 'vue3-component-lib',
    componentRoot: 'packages/components',
    componentsIndex: 'packages/my-lib/component.ts',
    docRoot: 'docs/en-US/component',
    exampleRoot: 'docs/examples',
    sidebarConfig: 'docs/.vitepress/i18n/pages/component.json',
    i18nPath: 'packages/locale/lang',     // 可选
    packagePrefix: '@my-scope/components', // 可选,组件导入前缀
    // componentNamePattern: 'fancy-{name}',  // 可选,默认 kebab-case
    // namespaceHook: 'useNamespace',          // 可选
  } as const,

  // 4. shell 命令注册表
  commands: {
    test: 'pnpm exec vitest',
    e2e: 'playwright test --project=chromium --headed --workers=1',
    lint: 'pnpm exec eslint .',
    typecheck: 'pnpm exec tsc -p tsconfig.json --noEmit',
    docsBuild: 'pnpm run -C docs build',
    docsDev: 'pnpm run -C docs dev',
  },

  // 5. LLM 配置(可选,默认读 env)
  // llm: { provider: 'openai', model: 'gpt-4o-mini' },
})

defineConfig 是个 identity function —— 只是为了让你在 ai.config.ts 里有 IntelliSense,值原样透传。

不要改成 CJS:ai.config.ts 会被 CLI 用 tsx 当 ESM 加载, 写 module.exports 会被解析失败。

子命令(按场景分组)

完整列表跑 npx ai-agent --help。

🚀 起步(不需要 ai.config.ts)

🪝 Git hooks

🧭 MCP server

📚 Rules(给 AI agent 写规则)

🏗 项目命令(跑宿主 build/test/docs 等)

把 ai.config.ts 里 commands 注册的宿主命令暴露成 ai-agent 子命令， 统一从 ai-agent 入口执行。commands 持有完整实现（宿主高频脚本已迁到此，package.json 不再重复定义）:

解析顺序：先查 ai.config.ts#commands 的精确键（含 test:coverage/publish:npmjs 等带冒号任意键，可含 shell 语法如 &&/正则，经 shell 执行），再查别名归一化，最后回落读宿主 package.json#scripts（pnpm run <script>）。ai-agent 直接持有/spawn 命令，不回环、透传退出码。

🛠 Env 检查

🔍 知识库 & 检索(需要 ai.config.ts)

📦 组件增删改(per-component)

✅ 质量门(check 4 件套)

🤖 Agent 编排(高阶)

💾 缓存 & 指标

公共参数(大多数 check / generate 都支持)

程序化调用(trek-ai-cli 作为库)

trek-ai-cli 也导出几个函数,方便你在自己的 bin / IDE 插件里复用:

import {
  loadConfig,
  findConfigPath,
  loadConfigFromPath,
  toRulesContext,
  defineConfig,
  STARTER_CONFIG,
  type AIConfig,
  type ProjectProfile,
  type ComponentLibProfile,
  type AppProfile,
  type CommandRegistry,
} from 'trek-ai-cli'

// 1. 找 + 加载 ai.config.ts(从 cwd 往上找)
const cfg = await loadConfig()

// 2. 加载指定路径
const cfg2 = await loadConfigFromPath('/abs/path/to/ai.config.ts')

// 3. 找而不加载
const p = await findConfigPath()  // '/abs/.../ai.config.ts' or null

// 4. 渲染给 trek-ai-rules 用
const ctx = toRulesContext(cfg)
// → RulesContext(见 trek-ai-rules README)

// 5. 拿到 init 命令的 starter 配置(可以基于它再定制)
const starter: AIConfig = STARTER_CONFIG

类型化你的 ai.config.ts

import { defineConfig, type AIConfig } from 'trek-ai-cli'

export default defineConfig<AIConfig>({
  // 完整 IntelliSense
})

内嵌 MCP server

ai-agent mcp 启动一个 stdio JSON-RPC server,暴露 26 个 tool。 任何支持 MCP 的客户端(Claude Desktop / Cursor / Cline / 自研 agent) 都能接上。tool 列表见 packages/cli/src/mcp/handlers/ (每个 *.ts 一个 tool 实现)。

// .mcp.json(MCP client 配置)
{
  "mcpServers": {
    "my-lib-agent": {
      "command": "npx",
      "args": ["ai-agent", "mcp"]
    }
  }
}

AI-augmented advisor(LLM 修复建议)

ai-agent check * 输出里如果有 issue,会带 llmHint 字段 —— 这是 CLI 调 trek-ai-core 的 LLMClient 给每条 issue 生成的 2-3 句 上下文相关的修复建议。带(rule + 上下文)的缓存,重复调用免费。

LLM 没配(LLM_DISABLED=1 或没设 OPENAI_API_KEY / DEEPSEEK_API_KEY) 时,advisor 还是返回静态字段(summary / rationale / fixCommand / referencePath),只是没有 llmHint。

License

MIT.