@brms/ai-skills 0.1.0

package/README.md

@@ -0,0 +1,256 @@
+# BRMS AI Skills
+
+BRMS 共享 AI Skill 工具包。
+
+这个仓库维护 BRMS 项目可复用的 Claude/Codex skills，并提供 `brms-skills` CLI，把包内 skills 同步到业务项目的 `.claude/skills/` 目录。
+
+## Skill 清单
+
+| Skill | 用途 |
+| --- | --- |
+| `brms-prototype-generator` | 从产品 Markdown 生成 BRMS/eplat-vue-base mock-first 原型页面。 |
+| `brms-vxe-plus-developer` | 面向真实 `project/*` 开发的 VxePlus、EiInfo、业务页面开发规则。 |
+
+包内结构：
+
+```text
+@brms/ai-skills/
+|-- bin/
+|   `-- brms-skills.mjs
+`-- skills/
+    |-- brms-prototype-generator/
+    `-- brms-vxe-plus-developer/
+```
+
+同步后的业务项目结构：
+
+```text
+<project>/.claude/skills/
+|-- brms-prototype-generator/
+|-- brms-vxe-plus-developer/
+`-- .brms-ai-skills-lock.json
+```
+
+## 命令清单
+
+在本仓库内直接运行：
+
+```bash
+node ./bin/brms-skills.mjs list
+node ./bin/brms-skills.mjs sync --project D:/Git/AI/eplat-vue-base
+node ./bin/brms-skills.mjs status --project D:/Git/AI/eplat-vue-base
+```
+
+在业务项目安装依赖后运行：
+
+```bash
+pnpm brms-skills list
+pnpm brms-skills sync
+pnpm brms-skills sync --link
+pnpm brms-skills status
+pnpm brms-skills clean --force
+```
+
+Skill 执行前的项目检查命令：
+
+```bash
+node .claude/skills/brms-prototype-generator/scripts/check-project.mjs --repo-root . --target-project project/<name> --format both
+node .claude/skills/brms-vxe-plus-developer/scripts/check-project.mjs --repo-root . --target-project project/<name> --format both
+```
+
+检查结果分为 `Blockers`、`Warnings`、`Signals`。只有 `Blockers` 需要停止执行；`Warnings` 用来提醒当前项目可能采用不同的路由、菜单或文档布局。
+如果当前仓库里有多个有效的 `project/*` 子项目，检查会阻断执行并列出候选项目；此时需要先让用户确认目标项目，再带上 `--target-project project/<name>` 重新运行。
+
+命令说明：
+
+| 命令 | 说明 |
+| --- | --- |
+| `brms-skills list` | 列出当前包内 skills。 |
+| `brms-skills sync` | 复制 skills 到当前项目 `.claude/skills/`。 |
+| `brms-skills sync --link` | 用链接模式同步，适合维护者本地调试。 |
+| `brms-skills status` | 检查当前项目 skills 是否已同步、过期或被改动。 |
+| `brms-skills clean --force` | 删除 lock 文件记录过的 managed skills。 |
+
+推荐在业务项目 `package.json` 中添加脚本：
+
+```json
+{
+  "scripts": {
+    "skills:sync": "brms-skills sync",
+    "skills:status": "brms-skills status"
+  }
+}
+```
+
+## 本地维护流程
+
+适用于维护 `D:/Git/AI/brms-ai-skills` 的人。
+
+先在业务项目里安装本地包：
+
+```bash
+cd D:/Git/AI/eplat-vue-base
+pnpm add -D D:/Git/AI/brms-ai-skills
+```
+
+然后用 link 模式同步：
+
+```bash
+pnpm brms-skills sync --link
+pnpm brms-skills status
+```
+
+这时链路大致是：
+
+```text
+<project>/node_modules/@brms/ai-skills
+  -> D:/Git/AI/brms-ai-skills
+
+<project>/.claude/skills/brms-prototype-generator
+  -> <project>/node_modules/@brms/ai-skills/skills/brms-prototype-generator
+
+<project>/.claude/skills/brms-vxe-plus-developer
+  -> <project>/node_modules/@brms/ai-skills/skills/brms-vxe-plus-developer
+```
+
+之后只需要修改：
+
+```text
+D:/Git/AI/brms-ai-skills/skills/...
+```
+
+业务项目里的 `.claude/skills/...` 会立即看到变化，不需要每次重新复制。
+
+准备发布、打版本，或给其他项目正式使用前，再用复制模式做一次冒烟验证：
+
+```bash
+pnpm brms-skills sync
+pnpm brms-skills status
+```
+
+## 新项目接入流程
+
+适用于业务项目首次接入这套 skills。
+
+1. 安装工具包。
+
+本地调试阶段：
+
+```bash
+pnpm add -D D:/Git/AI/brms-ai-skills
+```
+
+正式团队使用时，建议改成内部 npm 包、Git tag 依赖，或其他团队成员都能访问的来源：
+
+```bash
+pnpm add -D @brms/ai-skills
+```
+
+2. 添加项目脚本。
+
+```json
+{
+  "scripts": {
+    "skills:sync": "brms-skills sync",
+    "skills:status": "brms-skills status"
+  }
+}
+```
+
+3. 添加 `.gitignore`。
+
+业务项目不要提交同步出来的 skill 内容，否则会重新变成“每个项目复制一份”的版本漂移模式。
+
+建议忽略：
+
+```gitignore
+.claude/skills/brms-prototype-generator/
+.claude/skills/brms-vxe-plus-developer/
+.claude/skills/.brms-ai-skills-lock.json
+```
+
+业务项目只提交依赖声明和锁定文件：
+
+```text
+package.json
+pnpm-lock.yaml
+```
+
+`package.json` 声明依赖和脚本；`pnpm-lock.yaml` 锁定实际安装到的精确版本或来源。
+
+4. 同步 skills。
+
+```bash
+pnpm install
+pnpm skills:sync
+pnpm skills:status
+```
+
+团队正式使用建议走默认复制模式。复制后的 `.claude/skills/...` 是本地生成物，不进入业务项目 Git。
+
+## 同步模式
+
+默认复制模式：
+
+```bash
+pnpm brms-skills sync
+```
+
+复制模式最稳。即使业务项目删除了 `node_modules`，`.claude/skills` 里的 skills 仍然可用。团队正式使用时，建议默认走复制模式。
+
+本地 link 模式：
+
+```bash
+pnpm brms-skills sync --link
+```
+
+Windows 下 link 模式会创建目录 junction；macOS/Linux 下会创建目录 symlink。它适合维护者本地快速调试 skill 内容。
+
+## 锁文件和状态
+
+`sync` 会写入：
+
+```text
+.claude/skills/.brms-ai-skills-lock.json
+```
+
+锁文件记录包名、包版本、同步模式、同步时间、来源路径、目标路径和每个 skill 的内容 hash。
+
+`status` 状态说明：
+
+| 状态 | 含义 |
+| --- | --- |
+| `ok` | 目标内容和当前包版本一致。 |
+| `outdated` | 包版本或包内 skill 内容已经变化，但目标项目还没重新同步。 |
+| `modified` | 目标项目 `.claude/skills` 里的 skill 同步后被改过。 |
+| `missing` | lock 记录了该 skill，但目标目录已经不存在。 |
+| `unmanaged` | 目标目录存在 skill，但它不在 BRMS lock 里。 |
+| `not-synced` | 包里有该 skill，但目标项目还没有同步。 |
+
+## 清理
+
+`clean` 只删除 BRMS lock 文件记录过的 managed skills：
+
+```bash
+pnpm brms-skills clean --force
+```
+
+该命令必须显式加 `--force`，避免误删项目文件。
+
+## 版本策略
+
+当前包仍然是：
+
+```json
+{
+  "private": true
+}
+```
+
+如果后续要发布到内部 npm registry，再移除 `private`，配置 registry，并按语义化版本维护：
+
+| 版本 | 场景 |
+| --- | --- |
+| `patch` | 修 skill 规则、校验器、文档、示例。 |
+| `minor` | 新增 skill，或新增向后兼容的 CLI 能力。 |
+| `major` | 改变 skill 发现方式、同步布局、命令语义等破坏性行为。 |

package/bin/brms-skills.mjs

@@ -0,0 +1,411 @@
+#!/usr/bin/env node
+import crypto from 'node:crypto'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const PACKAGE_NAME = '@brms/ai-skills'
+const LOCK_FILE = '.brms-ai-skills-lock.json'
+
+const rootDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const packageJsonPath = path.join(rootDir, 'package.json')
+const skillsSourceRoot = path.join(rootDir, 'skills')
+
+function readPackageJson() {
+  return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'))
+}
+
+function usage() {
+  return `BRMS AI Skills
+
+Usage:
+  brms-skills list [--json]
+  brms-skills sync [--project <dir>] [--target <dir>] [--copy|--link] [--force] [--json]
+  brms-skills status [--project <dir>] [--target <dir>] [--json]
+  brms-skills clean [--project <dir>] [--target <dir>] [--force] [--json]
+
+Defaults:
+  project: current working directory
+  target:  <project>/.claude/skills
+  mode:    copy
+`
+}
+
+function parseArgs(argv) {
+  const parsed = {
+    command: argv[0] || 'help',
+    project: process.cwd(),
+    target: '',
+    mode: 'copy',
+    force: false,
+    json: false,
+  }
+
+  for (let i = 1; i < argv.length; i += 1) {
+    const arg = argv[i]
+    if (arg === '--project') {
+      parsed.project = argv[i + 1] || ''
+      i += 1
+    }
+    else if (arg === '--target') {
+      parsed.target = argv[i + 1] || ''
+      i += 1
+    }
+    else if (arg === '--copy') {
+      parsed.mode = 'copy'
+    }
+    else if (arg === '--link') {
+      parsed.mode = 'link'
+    }
+    else if (arg === '--force') {
+      parsed.force = true
+    }
+    else if (arg === '--json') {
+      parsed.json = true
+    }
+    else if (arg === '--help' || arg === '-h') {
+      parsed.command = 'help'
+    }
+    else {
+      throw new Error(`Unknown argument: ${arg}`)
+    }
+  }
+
+  parsed.project = path.resolve(parsed.project || process.cwd())
+  parsed.target = path.resolve(parsed.target || path.join(parsed.project, '.claude', 'skills'))
+  return parsed
+}
+
+function listSkills() {
+  if (!fs.existsSync(skillsSourceRoot))
+    return []
+
+  return fs.readdirSync(skillsSourceRoot, { withFileTypes: true })
+    .filter(entry => entry.isDirectory())
+    .map(entry => {
+      const dir = path.join(skillsSourceRoot, entry.name)
+      return {
+        name: entry.name,
+        source: dir,
+        hasSkillMd: fs.existsSync(path.join(dir, 'SKILL.md')),
+        hash: hashDirectory(dir),
+      }
+    })
+    .filter(skill => skill.hasSkillMd)
+    .sort((a, b) => a.name.localeCompare(b.name))
+}
+
+function hashDirectory(dir) {
+  const hash = crypto.createHash('sha256')
+  const files = []
+
+  function walk(current) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      if (entry.name === '.DS_Store')
+        continue
+
+      const fullPath = path.join(current, entry.name)
+      if (entry.isDirectory()) {
+        walk(fullPath)
+      }
+      else if (entry.isFile()) {
+        files.push(fullPath)
+      }
+    }
+  }
+
+  walk(dir)
+  files.sort()
+
+  for (const file of files) {
+    const rel = path.relative(dir, file).replaceAll(path.sep, '/')
+    hash.update(rel)
+    hash.update('\0')
+    hash.update(fs.readFileSync(file))
+    hash.update('\0')
+  }
+
+  return hash.digest('hex')
+}
+
+function removePath(target) {
+  fs.rmSync(target, { recursive: true, force: true })
+}
+
+function copyDirectory(source, target) {
+  removePath(target)
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  fs.cpSync(source, target, {
+    recursive: true,
+    filter: src => !src.endsWith(`${path.sep}.DS_Store`),
+  })
+}
+
+function linkDirectory(source, target) {
+  removePath(target)
+  fs.mkdirSync(path.dirname(target), { recursive: true })
+  const linkType = process.platform === 'win32' ? 'junction' : 'dir'
+  fs.symlinkSync(source, target, linkType)
+}
+
+function readLock(targetRoot) {
+  const lockPath = path.join(targetRoot, LOCK_FILE)
+  if (!fs.existsSync(lockPath))
+    return null
+
+  try {
+    return JSON.parse(fs.readFileSync(lockPath, 'utf8'))
+  }
+  catch {
+    return null
+  }
+}
+
+function writeLock(targetRoot, lock) {
+  fs.mkdirSync(targetRoot, { recursive: true })
+  fs.writeFileSync(path.join(targetRoot, LOCK_FILE), `${JSON.stringify(lock, null, 2)}\n`)
+}
+
+function ensureSafeTarget(source, target) {
+  const resolvedSource = path.resolve(source)
+  const resolvedTarget = path.resolve(target)
+  if (resolvedSource === resolvedTarget)
+    throw new Error(`Refusing to sync ${target}: source and target are the same path.`)
+  if (resolvedTarget.startsWith(`${resolvedSource}${path.sep}`))
+    throw new Error(`Refusing to sync ${target}: target is inside source.`)
+}
+
+function canOverwriteSkill(targetRoot, skillName, force) {
+  const target = path.join(targetRoot, skillName)
+  if (!fs.existsSync(target))
+    return true
+
+  const lock = readLock(targetRoot)
+  if (lock?.skills?.[skillName])
+    return true
+
+  if (force)
+    return true
+
+  return false
+}
+
+function commandList(args) {
+  const pkg = readPackageJson()
+  const skills = listSkills()
+  const result = {
+    packageName: pkg.name || PACKAGE_NAME,
+    packageVersion: pkg.version,
+    skills: skills.map(({ name, source, hash }) => ({ name, source, hash })),
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  console.log(`BRMS AI Skills ${result.packageVersion}`)
+  console.log('')
+  for (const skill of result.skills)
+    console.log(`- ${skill.name}`)
+}
+
+function commandSync(args) {
+  const pkg = readPackageJson()
+  const skills = listSkills()
+  if (!skills.length)
+    throw new Error(`No skills found under ${skillsSourceRoot}`)
+
+  fs.mkdirSync(args.target, { recursive: true })
+
+  const synced = []
+  for (const skill of skills) {
+    const target = path.join(args.target, skill.name)
+    ensureSafeTarget(skill.source, target)
+
+    if (!canOverwriteSkill(args.target, skill.name, args.force)) {
+      throw new Error(
+        `Refusing to overwrite unmanaged skill ${target}. Re-run with --force if this is intentional.`,
+      )
+    }
+
+    if (args.mode === 'link')
+      linkDirectory(skill.source, target)
+    else
+      copyDirectory(skill.source, target)
+
+    synced.push({
+      name: skill.name,
+      version: pkg.version,
+      mode: args.mode,
+      source: path.relative(args.project, skill.source).replaceAll(path.sep, '/'),
+      target: path.relative(args.project, target).replaceAll(path.sep, '/'),
+      hash: skill.hash,
+    })
+  }
+
+  const lock = {
+    packageName: pkg.name || PACKAGE_NAME,
+    packageVersion: pkg.version,
+    syncMode: args.mode,
+    syncedAt: new Date().toISOString(),
+    targetRoot: path.relative(args.project, args.target).replaceAll(path.sep, '/'),
+    skills: Object.fromEntries(synced.map(skill => [skill.name, {
+      version: skill.version,
+      mode: skill.mode,
+      source: skill.source,
+      target: skill.target,
+      hash: skill.hash,
+    }])),
+  }
+  writeLock(args.target, lock)
+
+  const result = { status: 'ok', target: args.target, synced, lockFile: path.join(args.target, LOCK_FILE) }
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  console.log(`Synced ${synced.length} skills to ${args.target}`)
+  for (const skill of synced)
+    console.log(`- ${skill.name} ${pkg.version} ${args.mode}`)
+  console.log(`Lock: ${path.join(args.target, LOCK_FILE)}`)
+}
+
+function skillStatus(args) {
+  const pkg = readPackageJson()
+  const lock = readLock(args.target)
+  const sourceSkills = new Map(listSkills().map(skill => [skill.name, skill]))
+
+  const names = Array.from(new Set([
+    ...sourceSkills.keys(),
+    ...Object.keys(lock?.skills || {}),
+  ])).sort()
+
+  const skills = names.map(name => {
+    const source = sourceSkills.get(name)
+    const target = path.join(args.target, name)
+    const locked = lock?.skills?.[name] || null
+    const exists = fs.existsSync(target)
+    const currentHash = exists && fs.statSync(target).isDirectory() ? hashDirectory(target) : ''
+    let status = 'missing'
+
+    if (!source) {
+      status = 'unknown'
+    }
+    else if (!locked) {
+      status = exists ? 'unmanaged' : 'not-synced'
+    }
+    else if (!exists) {
+      status = 'missing'
+    }
+    else if (locked.hash !== currentHash) {
+      status = 'modified'
+    }
+    else if (locked.hash !== source.hash || locked.version !== pkg.version) {
+      status = 'outdated'
+    }
+    else {
+      status = 'ok'
+    }
+
+    return {
+      name,
+      status,
+      syncedVersion: locked?.version || null,
+      packageVersion: source ? pkg.version : null,
+      mode: locked?.mode || null,
+      target,
+    }
+  })
+
+  const overall = skills.every(skill => skill.status === 'ok') ? 'up to date' : 'attention needed'
+  return {
+    packageName: pkg.name || PACKAGE_NAME,
+    packageVersion: pkg.version,
+    project: args.project,
+    target: args.target,
+    lockFile: path.join(args.target, LOCK_FILE),
+    lockFound: Boolean(lock),
+    overall,
+    skills,
+  }
+}
+
+function commandStatus(args) {
+  const result = skillStatus(args)
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  console.log('BRMS AI Skills')
+  console.log('')
+  console.log(`Package: ${result.packageName} ${result.packageVersion}`)
+  console.log(`Project: ${result.project}`)
+  console.log(`Target:  ${result.target}`)
+  console.log(`Lock:    ${result.lockFound ? result.lockFile : 'not found'}`)
+  console.log('')
+  for (const skill of result.skills) {
+    const version = skill.syncedVersion || '-'
+    console.log(`${skill.name.padEnd(28)} ${version.padEnd(8)} ${skill.status}`)
+  }
+  console.log('')
+  console.log(`Status: ${result.overall}`)
+}
+
+function commandClean(args) {
+  const lock = readLock(args.target)
+  const names = Object.keys(lock?.skills || {})
+  if (!names.length)
+    throw new Error(`No managed skills found in ${path.join(args.target, LOCK_FILE)}`)
+
+  if (!args.force)
+    throw new Error('Clean removes managed skill directories. Re-run with --force if this is intentional.')
+
+  for (const name of names)
+    removePath(path.join(args.target, name))
+
+  removePath(path.join(args.target, LOCK_FILE))
+
+  const result = { status: 'ok', removed: names, target: args.target }
+  if (args.json) {
+    console.log(JSON.stringify(result, null, 2))
+    return
+  }
+
+  console.log(`Removed ${names.length} managed skills from ${args.target}`)
+  for (const name of names)
+    console.log(`- ${name}`)
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2))
+  switch (args.command) {
+    case 'list':
+      commandList(args)
+      break
+    case 'sync':
+      commandSync(args)
+      break
+    case 'status':
+      commandStatus(args)
+      break
+    case 'clean':
+      commandClean(args)
+      break
+    case 'help':
+      console.log(usage())
+      break
+    default:
+      throw new Error(`Unknown command: ${args.command}\n\n${usage()}`)
+  }
+}
+
+try {
+  main()
+}
+catch (error) {
+  console.error(error instanceof Error ? error.message : String(error))
+  process.exit(1)
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@brms/ai-skills",
+  "version": "0.1.0",
+  "description": "Shared BRMS AI skills and project sync tooling.",
+  "type": "module",
+  "bin": {
+    "brms-skills": "./bin/brms-skills.mjs"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "README.md"
+  ],
+  "scripts": {
+    "skills:list": "node ./bin/brms-skills.mjs list",
+    "skills:status": "node ./bin/brms-skills.mjs status",
+    "skills:sync": "node ./bin/brms-skills.mjs sync",
+    "skills:clean": "node ./bin/brms-skills.mjs clean"
+  },
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/YOUR_USERNAME/brms-ai-skills.git"
+  },
+  "keywords": ["ai", "skills", "brms"],
+  "author": "池樱千幻"
+}