@ultime/codecraft 1.0.3 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 1.1.0 - 2026-10-27
+
+- 新增根 `SKILL.md`，兼容 Agent Skills / `skills-npm`；安装 `@ultime/codecraft` 后可被自动发现。
+- 新增 `codecraft install`：自动检测 Claude / Trae / Cursor，写入 `.agents/skills` 与对应目录；支持 `--agent` / `--global` / `--dest` / `--force` / `--dry-run`。
+- README 增加三种安装方式：`skills-npm`、内置安装器、手动指针。
+- `docs/07-ai-prompts.md` 与 adapters 补充安装入口。
+
 ## 1.0.3 - 2026-10-27
 
 - 文档从 v0 草稿固化为 v1 稳定版。

package/README.md

@@ -19,29 +19,47 @@
 
 规则正文只在 [`docs/`](./docs/)；其它位置只放入口与指针，避免第二份真源。
 
-> 第一次用：直接看 [5 分钟上手](#5-分钟上手)。
+> 第一次用：直接看 [安装](#安装) 和 [第一次使用](#第一次使用)。
 
-## 5 分钟上手
+## 安装
 
-Codecraft 有两种用法：**让 AI 按规范工作**（skill）和**在本地跑检查**（CLI）。先完成第 1、2 步就能用起来。
+### 方式 A：npm + skills-npm（推荐，多项目 / 团队）
 
-### 第 1 步：把入口接到 agent
+```bash
+npm i -D @ultime/codecraft skills-npm
+npx skills-npm setup
+```
+
+之后每次 `npm install` 都会把 `node_modules/@ultime/codecraft` 里的 skill 同步到 agent 目录：`.agents/skills/codecraft`，以及检测到的 Claude / Trae / Cursor 目录。需要 Node.js >= 22.20（`skills-npm` 的要求）。
 
-Codecraft 不是装完 npm 包就自动出现在 agent 里。选一种方式接入：
+### 方式 B：Codecraft 自带安装器（单次，无额外依赖）
+
+```bash
+npx @ultime/codecraft install
+```
+
+自动检测当前项目的 agent，把 `SKILL.md`、`docs/`、`scenarios/`、`prompts/` 复制到 `.agents/skills/codecraft` 和对应 agent 目录（`.claude/skills`、`.trae/skills`、`.cursor/skills`）。
+
+```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                 # 覆盖已有目录
+```
 
-**方式 A：指针式（推荐）**
+### 方式 C：手动指针
 
-在项目规则里留一行，让 agent 做代码任务时来读：
+不复制文件，只在项目规则里留一行：
 
-- Trae：项目 `.trae/rules/codecraft.md`
-- Claude：项目 `CLAUDE.md` 或 `~/.claude/CLAUDE.md`
-- 其他 agent：项目 `AGENTS.md`
+- Trae：`.trae/rules/codecraft.md`
+- Claude：`CLAUDE.md` 或 `~/.claude/CLAUDE.md`
+- 其他：`AGENTS.md`
 
 ```md
 代码任务先读 <Codecraft 路径>/codecraft/adapters/trae/SKILL.md
 ```
 
-平台对应的入口文件：
+平台入口：
 
 | 平台 | 入口文件 |
 |---|---|
@@ -49,11 +67,7 @@ Codecraft 不是装完 npm 包就自动出现在 agent 里。选一种方式接
 | Trae | [`adapters/trae/SKILL.md`](./adapters/trae/SKILL.md) |
 | Claude | [`adapters/claude/SKILL.md`](./adapters/claude/SKILL.md) |
 
-**方式 B：复制到 skills 目录**
-
-把对应平台的入口文件放进 agent 的 skills 目录。必须让 `docs/`、`scenarios/`、`prompts/` 与该文件保持 `../../` 的相对位置（符号链接即可），否则入口里的路径会失效。
-
-### 第 2 步：对 AI 说第一句话
+## 第一次使用
 
 ```text
 用 Codecraft 审计本项目，只读，不改文件。
@@ -63,18 +77,11 @@ Codecraft 不是装完 npm 包就自动出现在 agent 里。选一种方式接
 
 更多场景（只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System）见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)。
 
-### 第 3 步：需要本地检查时再装 CLI
+需要本地检查时再装 CLI：
 
 ```bash
 npx @ultime/codecraft check --root .
-npx @ultime/codecraft@latest check --root .
-```
-
-安装为项目依赖：
-
-```bash
-npm i -D @ultime/codecraft
-npx codecraft check --root .
+npx codecraft check --root .        # 已安装为项目依赖时
 ```
 
 本地开发 / 未发布时用 tarball：
@@ -85,8 +92,6 @@ npm i -D /path/to/ultime-codecraft-<version>.tgz
 npx codecraft check --root .
 ```
 
-也可以 `pnpm link --global /path/to/codecraft`，之后在任意目录使用 `codecraft`。
-
 ## 模式
 
 | 模式 | 是否改文件 | 对应命令 |
@@ -107,6 +112,7 @@ codecraft <command> [options]
 | `audit` | 内置规则 + `codecraft.config.json` 里的 gates，出只读报告 |
 | `plan` | 把 findings 转成只读升级计划；默认不跑 gates |
 | `init` | 生成 app / library 骨架；默认 dry-run |
+| `install` | 把 skill 安装到 agent skills 目录；默认写入，`--dry-run` 只看计划 |
 | `version` | 输出版本号 |
 
 ### 常用
@@ -121,6 +127,9 @@ 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
 ```
 
 ### 参数
@@ -138,13 +147,18 @@ codecraft init --root . --name demo --apply      # 写盘
 | `--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，或有 gate 失败 |
+| `1` | 有 error findings、install 失败，或有 gate 失败 |
 | `2` | 用法错误、root 不存在、配置非法 |
 
 ### 输出
@@ -194,14 +208,16 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
 ## 目录
 
 ```text
+SKILL.md      标准 agent skill 入口（skills-npm / install 使用）
 docs/         宪法、族卡、AI 契约、风格总图、模式、架构、AI 提示词、门禁
 scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
-adapters/     generic / Trae / Claude 入口
+adapters/     generic / Trae / Claude 手动指针
 prompts/      输出格式
-src/ + bin/   CLI
+src/ + bin/   CLI（含 install）
 tests/        node:test 用例
 templates/    init --apply 的 app / library 骨架
 evals/        golden tasks（人工回归）
+ROADMAP.md    后续版本计划与交接说明
 ```
 
 ## 版本与稳定承诺
@@ -209,6 +225,7 @@ evals/        golden tasks（人工回归）
 - semver；当前版本见 [VERSION](./VERSION)。
 - 规则 ID `A1–A21` 稳定；增删规则属于 minor 以上的变更。
 - 报告始终携带版本号；跨版本对比以 JSON 为准。
+- 后续计划：[ROADMAP.md](https://github.com/ultime-space/skills/blob/main/codecraft/ROADMAP.md)。
 
 ## 边界
 

package/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: codecraft
+description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
+---
+
+# Codecraft（代码手艺）
+
+## 先读
+
+1. 项目 `AGENTS.md` / `rules/`
+2. `docs/00-constitution.md`
+3. 只读相关族卡：`docs/01-family-cards.md`
+4. 设计架构时：`docs/06-architecture.md`
+5. 需要选型时：`docs/05-patterns.md`
+6. 选一个场景：`scenarios/`
+7. 按 `docs/02-ai-contract.md` 执行
+8. 按 `prompts/output.md` 输出
+9. 不知道怎么说时：`docs/07-ai-prompts.md`
+
+## 模式
+
+- **Audit（审计）**：只读，出报告。
+- **Plan（计划）**：只读，出架构 / 升级计划。
+- **Apply（执行）**：改代码 + 跑门禁。
+
+## 工作流
+
+1. 判定任务属于哪个场景。
+2. 只读相关族卡，不要一次加载全部。
+3. 先出计划；Apply 前确认范围。
+4. 跑项目验证命令；不能跑要说明原因。
+5. 按 `prompts/output.md` 输出。
+
+## 禁止
+
+- Audit / Plan 模式改文件。
+- 把业务逻辑放进 Transport 或 Page。
+- 内部代码 import `external/` 或生成类型。
+- 手改生成物。
+- 写敏感信息；发现即停止、脱敏、提示轮换。
+- 安全红线登记例外。
+
+规则正文只在 `docs/`；本文件只做入口。

package/VERSION

@@ -1 +1 @@
-1.0.3
+1.1.0

package/adapters/README.md

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

package/docs/07-ai-prompts.md

@@ -6,7 +6,22 @@
 
 ## 1. 先让 AI 找到 Codecraft
 
-在项目的 agent 入口里留一条指针，不要复制规则：
+最快的方式：
+
+```bash
+npx @ultime/codecraft install
+```
+
+或走 npm 同步：
+
+```bash
+npm i -D @ultime/codecraft skills-npm
+npx skills-npm setup
+```
+
+装好后项目里会有 `.agents/skills/codecraft/SKILL.md`（以及检测到的 agent 目录）。
+
+也可以手动在 agent 入口里留一条指针，不要复制规则：
 
 - Trae：项目 `.trae/rules/codecraft.md`
 - Claude：`CLAUDE.md`

package/evals/golden-tasks.md

@@ -107,6 +107,13 @@
 - 期望：命中 A21；只报文件与行号，不回显密钥；提示轮换。
 - 失败信号：漏报；把密钥原文打印到报告；把普通变量名误报为密钥。
 
+## 16. 安装到 agent
+
+- 输入：空项目，无 agent 配置目录。
+- 命令：`codecraft install --root . --agent generic`；再执行一次；最后 `--force`。
+- 期望：生成 `.agents/skills/codecraft/SKILL.md`、`docs/`、`scenarios/`、`prompts/`；第二次 skip；`--force` 覆盖。
+- 失败信号：复制到错误目录；覆盖用户已有内容；`SKILL.md` 引用断链。
+
 ## 评分
 
 - 每条任务：pass / fail。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Language-agnostic code standard as an installable skill package.",
   "keywords": [
     "ai",
@@ -10,7 +10,8 @@
     "audit",
     "architecture",
     "review",
-    "scaffold"
+    "scaffold",
+    "agent-skills"
   ],
   "author": "UltimeLam",
   "license": "MIT",
@@ -30,6 +31,7 @@
     "codecraft": "bin/codecraft.mjs"
   },
   "files": [
+    "SKILL.md",
     "bin",
     "src",
     "docs",

package/src/cli.mjs

@@ -4,6 +4,7 @@ import { check } from './check.mjs'
 import { loadConfig, runGates } from './gates.mjs'
 import { buildPlan, summarizePlan } from './plan.mjs'
 import { applyInitPlan, buildInitPlan } from './init.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
@@ -15,12 +16,18 @@ 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|claude|trae|cursor|generic  Install target, comma-separated (default: auto)
+  --global                 Install into the home directory
+  --dest <path>            Explicit destination (relative to root / home)
+  --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
@@ -51,7 +58,7 @@ export function main(argv) {
   }
 
   const command = args.command || 'check'
-  if (!['check', 'audit', 'plan', 'init'].includes(command)) {
+  if (!['check', 'audit', 'plan', 'init', 'install'].includes(command)) {
     console.error(`codecraft: unknown command "${command}"`)
     return 2
   }
@@ -62,6 +69,42 @@ 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)
@@ -180,6 +223,11 @@ function parseArgs(argv) {
     failFast: false,
     name: '',
     apply: false,
+    agent: 'auto',
+    global: false,
+    dest: '',
+    force: false,
+    dryRun: false,
     format: 'md',
     severity: 'warn',
     ci: false,
@@ -196,7 +244,12 @@ 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] ?? ''
@@ -329,6 +382,49 @@ 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

@@ -0,0 +1,100 @@
+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 = {
+  claude: '.claude/skills',
+  trae: '.trae/skills',
+  cursor: '.cursor/skills',
+  generic: '.agents/skills',
+}
+
+const AGENT_MARKERS = {
+  claude: ['.claude', 'CLAUDE.md'],
+  trae: ['.trae'],
+  cursor: ['.cursor'],
+  generic: ['.agents'],
+}
+
+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}`)
+    }
+  }
+}