@ultime/codecraft 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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 内的嵌套应用。

package/README.md

@@ -69,7 +69,25 @@ npx @ultime/codecraft install --dry-run                # 只看计划
 npx @ultime/codecraft install --force                  # 覆盖已有目录
 ```
 
-可选 agent：`generic` / `claude` / `cursor` / `trae` / `trae-cn`；未知目录用 `--dest`。
+可选内置 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：手动指针
 
@@ -270,6 +288,7 @@ ROADMAP.md    后续版本计划与交接说明
 - **静态检查误报怎么办？** 在 `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 为什么被判成 app / library？** 有 `pages/`、`app/`、`manifest.json + pages.json`、Taro / uni-app 依赖或嵌套应用时按 `app`；有 `packages/` 或 `src/` 时按 `library`；仍不确定就显式传 `--pack`。

package/VERSION

@@ -1 +1 @@
-1.2.1
+1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.2.1",
+  "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,7 +24,8 @@ 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|generic|claude|cursor|trae|trae-cn  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), e.g. .trae-cn/skills
   --force                  Replace an existing codecraft skill directory
@@ -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,
@@ -248,6 +266,7 @@ function parseArgs(argv) {
     dest: '',
     force: false,
     dryRun: false,
+    listAgents: false,
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -267,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] ?? ''
@@ -501,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',

package/src/install.mjs

@@ -7,53 +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 = {
-  generic: '.agents/skills',
-  claude: '.claude/skills',
-  cursor: '.cursor/skills',
-  trae: '.trae/skills',
-  'trae-cn': '.trae-cn/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 = {
-  generic: ['.agents'],
-  claude: ['.claude', 'CLAUDE.md'],
-  cursor: ['.cursor'],
-  trae: ['.trae'],
-  'trae-cn': ['.trae-cn'],
+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',
+    }
   })
 }
 
@@ -85,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))) {