@ultime/codecraft 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 1.3.0 - 2026-10-27
+
+- 新增 agent 注册表：内置 generic / claude / cursor / trae / trae-cn，`--list-agents` 查看项目 / 全局路径与检测结果。
+- 支持项目级 `codecraft.agents.json` 与用户级 `~/.codecraft/agents.json` 自定义 agent（project / global / markers），项目级覆盖用户级。
+- `auto` 按注册表检测所有匹配的 agent，不优先任何一家；重复目标的 agent 自动合并，避免重复复制。
+- 仍保留 `--dest` 作为临时目录逃生口。
+
+## 1.2.1 - 2026-10-27
+
+- 修复 pack 自动判定：识别 Nuxt 2 的 `pages/`、Nuxt 3 的 `app/`、uni-app 的 `manifest.json + pages.json`、Taro / uni-app 依赖，以及 workspace 内的嵌套应用。
+- 新增 `trae-cn` 安装目标（`~/.trae-cn/skills`）；`--agent` 顺序改为 generic / claude / cursor / trae / trae-cn，不再默认优先 Trae。
+- 扫描 0 个源文件时输出警告并以 2 退出，避免把空扫描当成通过。
+- README 补充 agent 列表、`--dest`、`Files: 0` 与 Trae CN 的说明。
+
 ## 1.2.0 - 2026-10-27
 
 - 新增 `ignore` 例外配置（A12）：`rule` / `file` / `reason` 必填，`expires` 可选；支持 `*` / `**` / `?` 路径匹配；安全规则 `A21` 不可豁免。

package/README.md

@@ -58,15 +58,37 @@ npx skills-npm setup
 npx @ultime/codecraft install
 ```
 
-自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.trae/skills`、`.cursor/skills`）。
+自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.cursor/skills`、`.trae/skills`、`.trae-cn/skills`）。不传 `--agent` 时只按检测结果安装，不优先任何一家。
 
 ```bash
-npx @ultime/codecraft install --agent claude          # 指定 agent，可逗号分隔
-npx @ultime/codecraft install --global --agent claude # 装到用户目录
-npx @ultime/codecraft install --dry-run               # 只看计划
-npx @ultime/codecraft install --force                 # 覆盖已有目录
+npx @ultime/codecraft install --agent generic          # 指定 agent，可逗号分隔
+npx @ultime/codecraft install --global --agent claude  # 装到用户目录
+npx @ultime/codecraft install --global --agent trae-cn # Trae CN 的全局目录
+npx @ultime/codecraft install --global --dest .trae-cn/skills  # 自定义目录
+npx @ultime/codecraft install --dry-run                # 只看计划
+npx @ultime/codecraft install --force                  # 覆盖已有目录
 ```
 
+可选内置 agent：`generic` / `claude` / `cursor` / `trae` / `trae-cn`；用 `--list-agents` 查看实际路径与检测结果。
+
+自定义 agent 放在项目级 `codecraft.agents.json` 或用户级 `~/.codecraft/agents.json`（项目级覆盖用户级）：
+
+```json
+{
+  "agents": {
+    "my-agent": {
+      "project": ".my/skills",
+      "global": ".my/skills",
+      "markers": [".my"]
+    }
+  }
+}
+```
+
+- `project` / `global`：项目内与全局的目标目录；`global` 省略时复用 `project`。
+- `markers`：`auto` 检测用的目录或文件；不填则只能显式 `--agent my-agent`。
+- 未知或临时目录仍可用 `--dest`，不必先写配置。
+
 ### 方式 C：手动指针
 
 不复制文件，只在项目规则里留一行：
@@ -264,9 +286,12 @@ ROADMAP.md    后续版本计划与交接说明
 ## FAQ
 
 - **静态检查误报怎么办？** 在 `codecraft.config.json` 的 `ignore` 里登记 `rule` + `file` + `reason`，必要时加 `expires`；不要直接删规则。
+- **`Files: 0` 是什么意思？** 没有扫到源文件，命令会输出警告并以 2 退出；用 `--pack app|library` 指定正确类型，或检查 `--root`。
+- **Trae CN 装到哪？** 用 `--agent trae-cn`（`~/.trae-cn/skills`）；未知目录用 `--dest`。
+- **怎么支持新的 agent？** 在 `codecraft.agents.json` 里加 `project` / `global` / `markers`，再跑 `--list-agents` 确认；不需要等 Codecraft 发版。
 - **`check` / `audit` / `plan` 有什么区别？** `check` 只跑内置规则；`audit` 额外跑 config 里的 gates；`plan` 只读，把 findings 转成计划，默认不跑 gates。
 - **为什么不自动跑 typecheck / test？** 门禁由项目提供，Codecraft 只编排，避免第二套实现。
-- **monorepo 为什么被判成 library？** 有 `packages/` 或根 `package.json` 即按 library；可用 `--pack` 显式覆盖。
+- **monorepo 为什么被判成 app / library？** 有 `pages/`、`app/`、`manifest.json + pages.json`、Taro / uni-app 依赖或嵌套应用时按 `app`；有 `packages/` 或 `src/` 时按 `library`；仍不确定就显式传 `--pack`。
 - **支持哪些文件？** 只扫 JS/TS 相关扩展名与 `package.json`；其它语言不覆盖。
 
 ## 边界

package/VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "面向 JS/TS 的代码规范与架构设计（前端默认，Node 后端可复用结构规则），作为可安装的 skill 包。",
   "keywords": [
     "ai",

package/src/cli.mjs

@@ -5,7 +5,7 @@ import { loadConfig, runGates } from './gates.mjs'
 import { buildPlan, summarizePlan } from './plan.mjs'
 import { applyInitPlan, buildInitPlan } from './init.mjs'
 import { applyIgnores } from './ignore.mjs'
-import { applyInstallPlan, buildInstallPlan, parseAgents } from './install.mjs'
+import { applyInstallPlan, buildInstallPlan, listAgents, loadAgents, parseAgents } from './install.mjs'
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
 const VERSION = PACKAGE.version
@@ -24,9 +24,10 @@ Options:
   --root <path>            Project root (default: cwd)
   --pack app|library|design-system|auto  Rule pack (default: auto)
   --config <path>          Config file (default: codecraft.config.json)
-  --agent auto|claude|trae|cursor|generic  Install target, comma-separated (default: auto)
+  --agent <name>[,<name>]  Install target (default: auto; see --list-agents)
+  --list-agents            List registered agents, paths and detection
   --global                 Install into the home directory
-  --dest <path>            Explicit destination (relative to root / home)
+  --dest <path>            Explicit destination (relative to root / home), e.g. .trae-cn/skills
   --force                  Replace an existing codecraft skill directory
   --dry-run                Show the install plan without writing
   --no-gates               Skip gates in audit / plan
@@ -70,16 +71,33 @@ export function main(argv) {
     return 2
   }
 
+  if (args.listAgents) {
+    try {
+      const agents = listAgents(root, { global: args.global })
+      if (args.format === 'json') {
+        console.log(JSON.stringify({ version: VERSION, agents }, null, 2))
+      } else {
+        console.log(formatAgents(agents))
+      }
+      return 0
+    } catch (error) {
+      console.error(`codecraft: ${error.message}`)
+      return 2
+    }
+  }
+
   if (command === 'install') {
     let agents
+    let registry
     try {
-      agents = parseAgents(args.agent)
+      registry = loadAgents(root, { global: args.global })
+      agents = parseAgents(args.agent, [...registry.keys()])
     } catch (error) {
       console.error(`codecraft: ${error.message}`)
       return 2
     }
     try {
-      const plan = buildInstallPlan(root, { agents, global: args.global, dest: args.dest })
+      const plan = buildInstallPlan(root, { agents, global: args.global, dest: args.dest, registry })
       const applied = args.dryRun ? null : applyInstallPlan(plan, { force: args.force })
       const meta = {
         version: VERSION,
@@ -154,6 +172,11 @@ export function main(argv) {
   const findings = result.findings.map((finding) => ({ ...finding, severity }))
   const filtered = applyIgnores(findings, config.config.ignore ?? [])
   const activeFindings = filtered.findings
+  const warnings = []
+  if (result.files === 0 && result.findings.length === 0) {
+    warnings.push(`0 source files scanned under ${root}; pass --pack app|library or check --root`)
+    console.error(`codecraft: warning: ${warnings[0]}`)
+  }
   const gates = shouldRunGates(command, args)
     ? runGates(root, config.config.gates ?? [], { failFast: args.failFast })
     : []
@@ -170,6 +193,7 @@ export function main(argv) {
     findings: activeFindings.length,
     ignored: filtered.ignored.length,
     expired: filtered.expired.length,
+    warnings,
     plan: plan.length,
     gates: gates.length,
   }
@@ -207,6 +231,7 @@ export function main(argv) {
   const failed =
     activeFindings.some((finding) => finding.severity === 'error') ||
     gates.some((gate) => gate.exitCode !== 0)
+  if (warnings.length) return 2
   return failed ? 1 : 0
 }
 
@@ -241,6 +266,7 @@ function parseArgs(argv) {
     dest: '',
     force: false,
     dryRun: false,
+    listAgents: false,
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -260,6 +286,7 @@ function parseArgs(argv) {
     else if (arg === '--global') args.global = true
     else if (arg === '--force') args.force = true
     else if (arg === '--dry-run') args.dryRun = true
+    else if (arg === '--list-agents') args.listAgents = true
     else if (arg === '--name') args.name = argv[++i] ?? ''
     else if (arg === '--agent') args.agent = argv[++i] ?? 'auto'
     else if (arg === '--dest') args.dest = argv[++i] ?? ''
@@ -281,13 +308,83 @@ function parseArgs(argv) {
   return args
 }
 
-function detectPack(root) {
-  if (isDir(path.join(root, 'apps')) || isDir(path.join(root, 'src', 'pages'))) return 'app'
+export function detectPack(root) {
+  if (isDir(path.join(root, 'apps'))) return 'app'
+  if (hasAppMarkers(root)) return 'app'
   if (isDir(path.join(root, 'packages'))) return 'library'
+  if (hasNestedApp(root)) return 'app'
+  if (isDir(path.join(root, 'src'))) return 'library'
   if (fs.existsSync(path.join(root, 'package.json'))) return 'library'
   return 'app'
 }
 
+const APP_DIR_MARKERS = ['src/pages', 'pages', 'app', 'src/app']
+const APP_FILE_MARKERS = [
+  'nuxt.config.js',
+  'nuxt.config.ts',
+  'nuxt.config.mjs',
+  'app.config.js',
+  'app.config.ts',
+  'src/app.config.js',
+  'src/app.config.ts',
+  'taro.config.js',
+  'taro.config.ts',
+]
+const APP_DEPS = ['nuxt', '@tarojs/taro', '@dcloudio/uni-app', 'uni-app', 'next']
+
+function hasAppMarkers(root) {
+  if (APP_DIR_MARKERS.some((dir) => isDir(path.join(root, dir)))) return true
+  if (APP_FILE_MARKERS.some((file) => isFile(path.join(root, file)))) return true
+  if (hasUniAppFiles(root)) return true
+  return hasAppDependency(root)
+}
+
+function hasNestedApp(root) {
+  let entries
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true })
+  } catch {
+    return false
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    if (['node_modules', 'dist', 'build', 'target', '.git', '.nuxt', '.output', 'coverage'].includes(entry.name)) {
+      continue
+    }
+    const child = path.join(root, entry.name)
+    if (APP_DIR_MARKERS.some((dir) => isDir(path.join(child, dir)))) return true
+    if (APP_FILE_MARKERS.some((file) => isFile(path.join(child, file)))) return true
+    if (hasUniAppFiles(child)) return true
+    if (hasAppDependency(child)) return true
+  }
+  return false
+}
+
+function hasUniAppFiles(root) {
+  const atRoot = isFile(path.join(root, 'manifest.json')) && isFile(path.join(root, 'pages.json'))
+  const atSrc = isFile(path.join(root, 'src', 'manifest.json')) && isFile(path.join(root, 'src', 'pages.json'))
+  return atRoot || atSrc
+}
+
+function hasAppDependency(root) {
+  let manifest
+  try {
+    manifest = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'))
+  } catch {
+    return false
+  }
+  const deps = { ...(manifest.dependencies ?? {}), ...(manifest.devDependencies ?? {}) }
+  return APP_DEPS.some((dep) => dep in deps)
+}
+
+function isFile(target) {
+  try {
+    return fs.statSync(target).isFile()
+  } catch {
+    return false
+  }
+}
+
 function fail(message) {
   console.error(`codecraft: ${message}\n\n${HELP}`)
   process.exit(2)
@@ -424,6 +521,24 @@ function formatInit(meta, plan, applied) {
   return lines.filter((line, index) => !(line === '' && lines[index - 1] === '')).join('\n')
 }
 
+function formatAgents(agents) {
+  const lines = [
+    '# Codecraft Agents',
+    '',
+    `- Version: ${VERSION}`,
+    '',
+    '| Name | Source | Project | Global | Detected |',
+    '|---|---|---|---|---|',
+  ]
+  for (const agent of agents) {
+    const detected =
+      [agent.detected.project ? 'project' : '', agent.detected.global ? 'global' : ''].filter(Boolean).join(', ') ||
+      '—'
+    lines.push(`| ${agent.name} | ${agent.source} | ${agent.project} | ${agent.global} | ${detected} |`)
+  }
+  return lines.join('\n')
+}
+
 function formatInstall(meta, plan, applied) {
   const lines = [
     '# Codecraft Install',
@@ -482,6 +597,7 @@ function header(meta) {
     `- Findings: ${meta.findings}`,
     `- Ignored: ${meta.ignored ?? 0}`,
     `- Expired exceptions: ${meta.expired ?? 0}`,
+    `- Warnings: ${meta.warnings?.length ?? 0}`,
     `- Gates: ${meta.gates}`,
     '',
   ]

package/src/install.mjs

@@ -7,51 +7,88 @@ const PACKAGE_ROOT = fileURLToPath(new URL('..', import.meta.url))
 const SKILL_FILES = ['SKILL.md']
 const SKILL_DIRS = ['docs', 'scenarios', 'prompts']
 
-const AGENT_DIRS = {
-  claude: '.claude/skills',
-  trae: '.trae/skills',
-  cursor: '.cursor/skills',
-  generic: '.agents/skills',
+const USER_AGENTS_FILE = path.join(os.homedir(), '.codecraft', 'agents.json')
+const PROJECT_AGENTS_FILE = 'codecraft.agents.json'
+
+const BUILTIN_AGENTS = {
+  generic: { project: '.agents/skills', global: '.agents/skills', markers: ['.agents'] },
+  claude: { project: '.claude/skills', global: '.claude/skills', markers: ['.claude', 'CLAUDE.md'] },
+  cursor: { project: '.cursor/skills', global: '.cursor/skills', markers: ['.cursor'] },
+  trae: { project: '.trae/skills', global: '.trae/skills', markers: ['.trae'] },
+  'trae-cn': { project: '.trae-cn/skills', global: '.trae-cn/skills', markers: ['.trae-cn'] },
 }
 
-const AGENT_MARKERS = {
-  claude: ['.claude', 'CLAUDE.md'],
-  trae: ['.trae'],
-  cursor: ['.cursor'],
-  generic: ['.agents'],
+export const AGENTS = Object.keys(BUILTIN_AGENTS)
+
+export function loadAgents(root, options = {}) {
+  const registry = new Map(
+    Object.entries(BUILTIN_AGENTS).map(([name, definition]) => [name, { ...definition, source: 'builtin' }]),
+  )
+  mergeAgentFile(registry, options.userFile ?? USER_AGENTS_FILE, 'user')
+  mergeAgentFile(registry, options.projectFile ?? path.join(root, PROJECT_AGENTS_FILE), 'project')
+  return registry
 }
 
-export const AGENTS = Object.keys(AGENT_DIRS)
+export function listAgents(root, options = {}) {
+  const registry = loadAgents(root, options)
+  return [...registry.entries()].map(([name, definition]) => ({
+    name,
+    project: definition.project,
+    global: definition.global,
+    source: definition.source,
+    detected: {
+      project: isDetected(root, definition.markers),
+      global: isDetected(os.homedir(), definition.markers),
+    },
+  }))
+}
 
-export function parseAgents(value) {
+export function parseAgents(value, names = AGENTS) {
   if (!value || value === 'auto') return []
   const agents = [...new Set(value.split(',').map((item) => item.trim()).filter(Boolean))]
-  const invalid = agents.filter((agent) => !AGENTS.includes(agent))
+  const invalid = agents.filter((agent) => !names.includes(agent))
   if (invalid.length) {
-    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：auto, ${AGENTS.join(', ')}）`)
+    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：${names.join(', ')}；用 --list-agents 查看）`)
   }
   return agents
 }
 
 export function buildInstallPlan(root, options = {}) {
+  const registry = options.registry ?? loadAgents(root, options)
   const base = options.global ? os.homedir() : path.resolve(root)
+  const names = [...registry.keys()]
   const explicit = options.agents ?? []
-  const invalid = explicit.filter((agent) => !AGENTS.includes(agent))
+  const invalid = explicit.filter((agent) => !registry.has(agent))
   if (invalid.length) {
-    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：${AGENTS.join(', ')}）`)
+    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：${names.join(', ')}；用 --list-agents 查看）`)
   }
 
-  const agents = explicit.length ? explicit : detectAgents(base, options.global)
+  const agents = explicit.length ? explicit : detectAgents(base, registry, options.global)
   const destinations = options.dest
     ? [{ agent: 'custom', dir: path.resolve(base, options.dest) }]
-    : agents.map((agent) => ({ agent, dir: path.join(base, AGENT_DIRS[agent]) }))
+    : agents.map((agent) => {
+        const definition = registry.get(agent)
+        return { agent, dir: path.join(base, options.global ? definition.global : definition.project) }
+      })
 
   assertSource()
 
-  return destinations.map(({ agent, dir }) => {
+  const byTarget = new Map()
+  for (const { agent, dir } of destinations) {
     const target = path.join(dir, 'codecraft')
+    if (!byTarget.has(target)) byTarget.set(target, { target, agents: [] })
+    byTarget.get(target).agents.push(agent)
+  }
+
+  return [...byTarget.values()].map(({ target, agents: targetAgents }) => {
     const exists = fs.existsSync(target)
-    return { agent, target, exists, action: exists ? 'exists' : 'create' }
+    return {
+      agent: targetAgents.join(','),
+      agents: targetAgents,
+      target,
+      exists,
+      action: exists ? 'exists' : 'create',
+    }
   })
 }
 
@@ -83,14 +120,49 @@ export function applyInstallPlan(plan, options = {}) {
   return { created, skipped, replaced }
 }
 
-function detectAgents(base, global) {
-  const found = AGENTS.filter((agent) =>
-    AGENT_MARKERS[agent].some((marker) => fs.existsSync(path.join(base, marker))),
-  )
+function mergeAgentFile(registry, file, source) {
+  if (!fs.existsSync(file)) return
+
+  let parsed
+  try {
+    parsed = JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch (error) {
+    throw new Error(`invalid agents file ${file}: ${error.message} (fix the JSON syntax or remove the file)`)
+  }
+
+  const agents = parsed?.agents
+  if (!agents || typeof agents !== 'object' || Array.isArray(agents)) {
+    throw new Error(`invalid agents file ${file}: expected { "agents": { "<name>": { project, global, markers } } }`)
+  }
+
+  for (const [name, definition] of Object.entries(agents)) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+      throw new Error(`invalid agents file ${file}: agent name "${name}" must be lowercase kebab-case`)
+    }
+    const project = typeof definition?.project === 'string' ? definition.project.trim() : ''
+    if (!project) {
+      throw new Error(`invalid agents file ${file}: agent "${name}" needs a non-empty "project" path`)
+    }
+    const global = typeof definition?.global === 'string' && definition.global.trim() ? definition.global.trim() : project
+    const markers = Array.isArray(definition?.markers)
+      ? definition.markers.filter((marker) => typeof marker === 'string' && marker.trim())
+      : []
+    registry.set(name, { project, global, markers, source })
+  }
+}
+
+function detectAgents(base, registry, global) {
+  const found = [...registry.entries()]
+    .filter(([, definition]) => isDetected(base, definition.markers))
+    .map(([name]) => name)
   if (global) return found.length ? found : ['generic']
   return [...new Set([...found, 'generic'])]
 }
 
+function isDetected(base, markers) {
+  return markers.some((marker) => fs.existsSync(path.join(base, marker)))
+}
+
 function assertSource() {
   for (const file of SKILL_FILES) {
     if (!fs.existsSync(path.join(PACKAGE_ROOT, file))) {