@ultime/codecraft 1.2.1 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 1.4.0 - 2026-10-27
+
+- 仓库改为 `skills/codecraft` 标准集合布局，可被 `skills` CLI 直接发现。
+- 移除 `codecraft install`、agent 注册表与自定义 agent；安装改由 `npx skills add ultime-space/skills --skill codecraft` 或 `skills-npm` 负责。
+- 发布 workflow、README、适配器与评测路径同步到集合布局。
+
+## 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

@@ -43,44 +43,33 @@
 
 ## 安装
 
-### 方式 A：npm + skills-npm（推荐，多项目 / 团队）
+### 方式 A：skills CLI（推荐）
 
 ```bash
-npm i -D @ultime/codecraft skills-npm
-npx skills-npm setup
+npx skills add ultime-space/skills --skill codecraft
 ```
 
-之后每次 `npm install` 都会把 `node_modules/@ultime/codecraft` 里的 skill 同步到 agent 目录：`.agents/skills/codecraft`，以及检测到的 Claude / Trae / Cursor 目录。需要 Node.js >= 22.20（`skills-npm` 的要求）。
-
-### 方式 B：Codecraft 自带安装器（单次，无额外依赖）
-
-```bash
-npx @ultime/codecraft install
-```
+不传 `-a` 时，CLI 会检测本机 agent 并让你多选；`-g` 装到用户目录，`-a` 指定 agent。agent 支持由 `skills` CLI 维护，本 skill 不枚举。
 
-自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.cursor/skills`、`.trae/skills`、`.trae-cn/skills`）。不传 `--agent` 时只按检测结果安装，不优先任何一家。
+### 方式 B：npm + skills-npm（多项目 / 团队）
 
 ```bash
-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                  # 覆盖已有目录
+npm i -D @ultime/codecraft skills-npm
+npx skills-npm setup
 ```
 
-可选 agent：`generic` / `claude` / `cursor` / `trae` / `trae-cn`；未知目录用 `--dest`。
+之后每次 `npm install` 都会把 `node_modules/@ultime/codecraft` 里的 skill 同步到 agent 目录：`.agents/skills/codecraft`，以及检测到的 agent 目录。需要 Node.js >= 22.20（`skills-npm` 的要求）。
 
 ### 方式 C：手动指针
 
 不复制文件，只在项目规则里留一行：
 
-- Trae：`.trae/rules/codecraft.md`
+- 通用：`AGENTS.md`
 - Claude：`CLAUDE.md` 或 `~/.claude/CLAUDE.md`
-- 其他：`AGENTS.md`
+- Trae：`.trae/rules/codecraft.md`
 
 ```md
-代码任务先读 <Codecraft 路径>/codecraft/adapters/trae/SKILL.md
+代码任务先读 <Codecraft 仓库路径>/skills/codecraft/adapters/trae/SKILL.md
 ```
 
 平台入口：
@@ -88,8 +77,8 @@ npx @ultime/codecraft install --force                  # 覆盖已有目录
 | 平台 | 入口文件 |
 |---|---|
 | 通用（读 `AGENTS.md`） | [`adapters/generic/AGENTS.md`](./adapters/generic/AGENTS.md) |
-| Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
 | Claude | [`adapters/claude/SKILL.md`](./adapters/claude/SKILL.md) |
+| Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
 
 ## 第一次使用
 
@@ -136,7 +125,6 @@ codecraft <command> [options]
 | `audit` | 内置规则 + `codecraft.config.json` 里的 gates，出只读报告 |
 | `plan` | 把 findings 转成只读升级计划；默认不跑 gates |
 | `init` | 生成 app / library 骨架；默认 dry-run |
-| `install` | 把 skill 安装到 agent skills 目录；默认写入，`--dry-run` 只看计划 |
 | `version` | 输出版本号 |
 
 ### 常用
@@ -151,9 +139,6 @@ codecraft audit --config codecraft.config.json --fail-fast
 codecraft plan --root . --with-gates
 codecraft init --root . --name demo              # dry-run
 codecraft init --root . --name demo --apply      # 写盘
-codecraft install                                # 自动检测并安装
-codecraft install --agent trae,claude --force
-codecraft install --dry-run
 ```
 
 ### 参数
@@ -171,18 +156,13 @@ codecraft install --dry-run
 | `--with-gates` | — | 关 | `plan` 执行 gates |
 | `--name <name>` | 字符串 | — | `init` 的 app / package 名称；`--apply` 时必填 |
 | `--apply` | — | 关 | `init` 写盘；已存在路径跳过，不覆盖 |
-| `--agent <list>` | `auto` / `claude` / `trae` / `cursor` / `generic` | `auto` | `install` 目标，可逗号分隔 |
-| `--global` | — | 关 | `install` 写入用户目录 |
-| `--dest <path>` | 目录 | — | `install` 的显式目标 |
-| `--force` | — | 关 | `install` 覆盖已有 codecraft 目录 |
-| `--dry-run` | — | 关 | `install` 只输出计划，不写盘 |
 
 ### 退出码
 
 | 码 | 含义 |
 |---|---|
 | `0` | 通过；warning 不阻断 |
-| `1` | 有 error findings、install 失败，或有 gate 失败 |
+| `1` | 有 error findings，或有 gate 失败 |
 | `2` | 用法错误、root 不存在、配置非法 |
 
 ### 输出
@@ -247,7 +227,7 @@ docs/         宪法、族卡、AI 契约、风格总图、模式、架构、AI
 scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
 adapters/     generic / Trae / Claude 手动指针
 prompts/      输出格式
-src/ + bin/   CLI（含 install）
+src/ + bin/   CLI（check / audit / plan / init）
 tests/        node:test 用例
 templates/    init --apply 的 app / library 骨架
 evals/        golden tasks（人工回归）
@@ -263,13 +243,13 @@ ROADMAP.md    后续版本计划与交接说明
 - 不按「感觉重要」升 major；`2.0` 不设时间表。
 - 规则 ID `A1–A21` 稳定；增删规则属于 minor 以上的变更。
 - 报告始终携带版本号；跨版本对比以 JSON 为准。
-- 后续计划：[ROADMAP.md](https://github.com/ultime-space/skills/blob/main/codecraft/ROADMAP.md)。
+- 后续计划：[ROADMAP.md](https://github.com/ultime-space/skills/blob/main/skills/codecraft/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？** `npx skills add ultime-space/skills --skill codecraft`；交互选 agent，或用 `-a <agent>` 非交互。安装路径由 `skills` CLI 维护，本 skill 不枚举。
 - **`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.4.0

package/adapters/README.md

@@ -9,6 +9,6 @@ Core 是 `docs/` + `scenarios/` + `scripts/`；adapters 只做入口，不复制
 
 规则：adapter 只写“读什么、按什么流程、输出什么”，规则正文留在 `docs/`。
 
-包根的 [`SKILL.md`](../SKILL.md) 是标准 agent skill 入口（`skills-npm` / `codecraft install` 使用）；本目录的平台文件用于手动指针接入。两者二选一，不要同时维护两套正文。
+包根的 [`SKILL.md`](../SKILL.md) 是标准 agent skill 入口（`skills add` / `skills-npm` 使用）；本目录的平台文件用于手动指针接入。两者二选一，不要同时维护两套正文。
 
 使用者提示词（怎么对 AI 说）：[`../docs/07-ai-prompts.md`](../docs/07-ai-prompts.md)。

package/docs/07-ai-prompts.md

@@ -10,9 +10,11 @@
 最快的方式：
 
 ```bash
-npx @ultime/codecraft install
+npx skills add ultime-space/skills --skill codecraft
 ```
 
+交互选择 agent；非交互用 `-a <agent>`，全局加 `-g`。
+
 或走 npm 同步：
 
 ```bash
@@ -24,12 +26,12 @@ npx skills-npm setup
 
 也可以手动在 agent 入口里留一条指针，不要复制规则：
 
-- Trae：项目 `.trae/rules/codecraft.md`
-- Claude：`CLAUDE.md`
 - 通用：`AGENTS.md`
+- Claude：`CLAUDE.md`
+- Trae：项目 `.trae/rules/codecraft.md`
 
 ```md
-代码任务先读 <Codecraft 仓库路径>/codecraft/adapters/<平台>/...
+代码任务先读 <Codecraft 仓库路径>/skills/codecraft/adapters/<平台>/...
 ```
 
 平台对应：Trae → `adapters/trae/SKILL.md`，Claude → `adapters/claude/SKILL.md`，其他 → `adapters/generic/AGENTS.md`。
@@ -39,7 +41,7 @@ npx skills-npm setup
 任何任务都可以先用这段，再补场景：
 
 ```text
-使用 Codecraft（<Codecraft 仓库路径>/codecraft）。
+使用 Codecraft（<Codecraft 仓库路径>/skills/codecraft）。
 模式：Audit / Plan / Apply。
 范围：<目录 / 包 / 文件 / diff>。
 任务：<一句话>。

package/evals/golden-tasks.md

@@ -109,12 +109,10 @@
 - 期望：命中 A21；只报文件与行号，不回显密钥；提示轮换。
 - 失败信号：漏报；把密钥原文打印到报告；把普通变量名误报为密钥。
 
-## 16. 安装到 agent
+## 16. 安装（已移出本 skill）
 
-- 输入：空项目，无 agent 配置目录。
-- 命令：`codecraft install --root . --agent generic`；再执行一次；最后 `--force`。
-- 期望：生成 `.agents/skills/codecraft/SKILL.md`、`docs/`、`scenarios/`、`prompts/`；第二次 skip；`--force` 覆盖。
-- 失败信号：复制到错误目录；覆盖用户已有内容；`SKILL.md` 引用断链。
+- 安装由 `skills` CLI 负责：`npx skills add ultime-space/skills --skill codecraft`。
+- 不在 Codecraft 规则评估范围内；本文件不再评估安装器行为。
 
 ## 评分
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "面向 JS/TS 的代码规范与架构设计（前端默认，Node 后端可复用结构规则），作为可安装的 skill 包。",
   "keywords": [
     "ai",
@@ -18,9 +18,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ultime-space/skills.git",
-    "directory": "codecraft"
+    "directory": "skills/codecraft"
   },
-  "homepage": "https://github.com/ultime-space/skills/tree/main/codecraft",
+  "homepage": "https://github.com/ultime-space/skills/tree/main/skills/codecraft",
   "bugs": {
     "url": "https://github.com/ultime-space/skills/issues"
   },

package/src/cli.mjs

@@ -5,7 +5,6 @@ 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'
 
 const PACKAGE = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
 const VERSION = PACKAGE.version
@@ -17,18 +16,12 @@ Commands:
   audit       check + configured gates; read-only report
   plan        Read-only upgrade plan from findings
   init        Scaffold an app or package (dry-run unless --apply)
-  install     Install the skill into agent skills directories
   version     Print version
 
 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)
-  --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
-  --dry-run                Show the install plan without writing
   --no-gates               Skip gates in audit / plan
   --with-gates             Run configured gates in plan
   --fail-fast              Stop gates after the first failure
@@ -59,7 +52,7 @@ export function main(argv) {
   }
 
   const command = args.command || 'check'
-  if (!['check', 'audit', 'plan', 'init', 'install'].includes(command)) {
+  if (!['check', 'audit', 'plan', 'init'].includes(command)) {
     console.error(`codecraft: unknown command "${command}"\n  next: run codecraft --help`)
     return 2
   }
@@ -70,42 +63,6 @@ export function main(argv) {
     return 2
   }
 
-  if (command === 'install') {
-    let agents
-    try {
-      agents = parseAgents(args.agent)
-    } catch (error) {
-      console.error(`codecraft: ${error.message}`)
-      return 2
-    }
-    try {
-      const plan = buildInstallPlan(root, { agents, global: args.global, dest: args.dest })
-      const applied = args.dryRun ? null : applyInstallPlan(plan, { force: args.force })
-      const meta = {
-        version: VERSION,
-        mode: 'install',
-        root,
-        scope: args.global ? 'global' : 'project',
-        agent: args.agent,
-        dest: args.dest || null,
-        dryRun: args.dryRun,
-        targets: plan.length,
-        created: applied?.created.length ?? 0,
-        replaced: applied?.replaced.length ?? 0,
-        skipped: applied?.skipped.length ?? 0,
-      }
-      if (args.format === 'json') {
-        console.log(JSON.stringify({ ...meta, plan, applied }, null, 2))
-      } else {
-        console.log(formatInstall(meta, plan, applied))
-      }
-      return plan.length ? 0 : 1
-    } catch (error) {
-      console.error(`codecraft: ${error.message}`)
-      return 1
-    }
-  }
-
   let config
   try {
     config = loadConfig(root, args.config)
@@ -243,11 +200,6 @@ function parseArgs(argv) {
     failFast: false,
     name: '',
     apply: false,
-    agent: 'auto',
-    global: false,
-    dest: '',
-    force: false,
-    dryRun: false,
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -264,12 +216,7 @@ function parseArgs(argv) {
     else if (arg === '--with-gates') args.withGates = true
     else if (arg === '--fail-fast') args.failFast = true
     else if (arg === '--apply') args.apply = true
-    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 === '--name') args.name = argv[++i] ?? ''
-    else if (arg === '--agent') args.agent = argv[++i] ?? 'auto'
-    else if (arg === '--dest') args.dest = argv[++i] ?? ''
     else if (arg === '--root') args.root = argv[++i] ?? '.'
     else if (arg === '--pack') args.pack = argv[++i] ?? 'auto'
     else if (arg === '--config') args.config = argv[++i] ?? ''
@@ -501,49 +448,6 @@ function formatInit(meta, plan, applied) {
   return lines.filter((line, index) => !(line === '' && lines[index - 1] === '')).join('\n')
 }
 
-function formatInstall(meta, plan, applied) {
-  const lines = [
-    '# Codecraft Install',
-    '',
-    `- Version: ${meta.version}`,
-    `- Mode: install`,
-    `- Scope: ${meta.scope}`,
-    `- Agent: ${meta.agent}`,
-    `- Root: ${meta.root}`,
-    `- Dest: ${meta.dest ?? '（auto）'}`,
-    `- Dry run: ${meta.dryRun}`,
-    `- Targets: ${meta.targets}`,
-  ]
-
-  if (applied) {
-    lines.push(
-      `- Created: ${meta.created}`,
-      `- Replaced: ${meta.replaced}`,
-      `- Skipped: ${meta.skipped}`,
-    )
-  }
-
-  if (!plan.length) {
-    lines.push('', '未找到可安装的目标；请用 `--agent` 指定，或先创建 agent 配置目录。')
-  } else {
-    lines.push('', '## Plan', '', '| Agent | Target | Action |', '|---|---|---|')
-    for (const entry of plan) {
-      lines.push(`| ${entry.agent} | ${entry.target} | ${entry.action} |`)
-    }
-  }
-
-  lines.push(
-    '',
-    '## Next',
-    '',
-    meta.dryRun
-      ? '- Re-run without `--dry-run` to write the skill.'
-      : '- Restart the agent or reload skills；然后说：`用 Codecraft 审计本项目，只读，不改文件。`',
-  )
-
-  return lines.join('\n')
-}
-
 function header(meta) {
   return [
     `# Codecraft ${title(meta.mode)}`,

package/src/install.mjs

@@ -1,102 +0,0 @@
-import fs from 'node:fs'
-import os from 'node:os'
-import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-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 AGENT_MARKERS = {
-  generic: ['.agents'],
-  claude: ['.claude', 'CLAUDE.md'],
-  cursor: ['.cursor'],
-  trae: ['.trae'],
-  'trae-cn': ['.trae-cn'],
-}
-
-export const AGENTS = Object.keys(AGENT_DIRS)
-
-export function parseAgents(value) {
-  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))
-  if (invalid.length) {
-    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：auto, ${AGENTS.join(', ')}）`)
-  }
-  return agents
-}
-
-export function buildInstallPlan(root, options = {}) {
-  const base = options.global ? os.homedir() : path.resolve(root)
-  const explicit = options.agents ?? []
-  const invalid = explicit.filter((agent) => !AGENTS.includes(agent))
-  if (invalid.length) {
-    throw new Error(`unknown agent: ${invalid.join(', ')}（可选：${AGENTS.join(', ')}）`)
-  }
-
-  const agents = explicit.length ? explicit : detectAgents(base, 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]) }))
-
-  assertSource()
-
-  return destinations.map(({ agent, dir }) => {
-    const target = path.join(dir, 'codecraft')
-    const exists = fs.existsSync(target)
-    return { agent, target, exists, action: exists ? 'exists' : 'create' }
-  })
-}
-
-export function applyInstallPlan(plan, options = {}) {
-  const created = []
-  const skipped = []
-  const replaced = []
-
-  for (const entry of plan) {
-    if (entry.exists && !options.force) {
-      skipped.push(entry.target)
-      continue
-    }
-    if (entry.exists) {
-      fs.rmSync(entry.target, { recursive: true, force: true })
-      replaced.push(entry.target)
-    }
-
-    fs.mkdirSync(entry.target, { recursive: true })
-    for (const file of SKILL_FILES) {
-      fs.copyFileSync(path.join(PACKAGE_ROOT, file), path.join(entry.target, file))
-    }
-    for (const dir of SKILL_DIRS) {
-      fs.cpSync(path.join(PACKAGE_ROOT, dir), path.join(entry.target, dir), { recursive: true })
-    }
-    created.push(entry.target)
-  }
-
-  return { created, skipped, replaced }
-}
-
-function detectAgents(base, global) {
-  const found = AGENTS.filter((agent) =>
-    AGENT_MARKERS[agent].some((marker) => fs.existsSync(path.join(base, marker))),
-  )
-  if (global) return found.length ? found : ['generic']
-  return [...new Set([...found, 'generic'])]
-}
-
-function assertSource() {
-  for (const file of SKILL_FILES) {
-    if (!fs.existsSync(path.join(PACKAGE_ROOT, file))) {
-      throw new Error(`skill source is incomplete: missing ${file}`)
-    }
-  }
-}