@ultime/codecraft 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 1.0.3 - 2026-10-27
+
+- 文档从 v0 草稿固化为 v1 稳定版。
+- 示例门禁改为通用 typecheck / test / lint，不再出现项目专用命令。
+- 适配器描述加入中文触发词，不读文档时也能更准确地触发。
+- README 增加 5 分钟上手教程；Skills 集合 README 去除自用表述。
+- CI 使用 Node 22，并在发布前检查版本是否已存在。
+- 新增 CLI 测试：version / help / 未知命令 / `--ci` / init 参数校验。
+
 ## 1.0.2 - 2026-10-27
 
 - 新增 `docs/07-ai-prompts.md`：可直接复制的 AI 提示词，覆盖审计 / 报告 / 新项目 / 评审 / 架构 / 模式 / 脚手架 / Design System。

package/README.md

@@ -19,21 +19,51 @@
 
 规则正文只在 [`docs/`](./docs/)；其它位置只放入口与指针，避免第二份真源。
 
-## 快速开始
+> 第一次用：直接看 [5 分钟上手](#5-分钟上手)。
 
-### 1. 直接运行
+## 5 分钟上手
 
-```bash
-# 在 codecraft 目录内
-node bin/codecraft.mjs check --root .
+Codecraft 有两种用法：**让 AI 按规范工作**（skill）和**在本地跑检查**（CLI）。先完成第 1、2 步就能用起来。
+
+### 第 1 步：把入口接到 agent
+
+Codecraft 不是装完 npm 包就自动出现在 agent 里。选一种方式接入：
+
+**方式 A：指针式（推荐）**
+
+在项目规则里留一行，让 agent 做代码任务时来读：
+
+- Trae：项目 `.trae/rules/codecraft.md`
+- Claude：项目 `CLAUDE.md` 或 `~/.claude/CLAUDE.md`
+- 其他 agent：项目 `AGENTS.md`
+
+```md
+代码任务先读 <Codecraft 路径>/codecraft/adapters/trae/SKILL.md
+```
+
+平台对应的入口文件：
+
+| 平台 | 入口文件 |
+|---|---|
+| 通用（读 `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) |
+
+**方式 B：复制到 skills 目录**
+
+把对应平台的入口文件放进 agent 的 skills 目录。必须让 `docs/`、`scenarios/`、`prompts/` 与该文件保持 `../../` 的相对位置（符号链接即可），否则入口里的路径会失效。
 
-# 检查任意项目
-node /path/to/codecraft/bin/codecraft.mjs check --root /path/to/project
+### 第 2 步：对 AI 说第一句话
+
+```text
+用 Codecraft 审计本项目，只读，不改文件。
 ```
 
-### 2. 安装 / 运行
+只启用 skill、不说 Codecraft 时，agent 可能按普通项目分析处理，不保证走 Audit 模式。带上名字最稳。
+
+更多场景（只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System）见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)。
 
-包名 `@ultime/codecraft`，命令 `codecraft`。发布到 npm 后可直接运行：
+### 第 3 步：需要本地检查时再装 CLI
 
 ```bash
 npx @ultime/codecraft check --root .
@@ -55,33 +85,9 @@ npm i -D /path/to/ultime-codecraft-<version>.tgz
 npx codecraft check --root .
 ```
 
-也可以直接 `pnpm link --global /path/to/codecraft`，之后在任意目录使用 `codecraft`。
-
-### 3. 接入 agent（作为 skill）
-
-适配器只做入口，不复制规则：
-
-| 平台 | 入口文件 |
-|---|---|
-| 通用（读 `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：在项目 `.trae/rules/codecraft.md` 写一行「代码任务先读 `<本仓库绝对路径>/adapters/trae/SKILL.md`」。
-- Claude：在 `~/.claude/CLAUDE.md` 或项目 `CLAUDE.md` 加同一行。
-- 其他 agent：在项目 `AGENTS.md` 加同一行。
-
-如果确实要把 `SKILL.md` 复制到 agent 的 skills 目录，必须让 `docs/`、`scenarios/`、`prompts/` 与该文件保持 `../../` 的相对位置（符号链接即可），否则入口里的路径会失效。
-
-### 4. 让 AI 怎么说
-
-可直接复制的提示词见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)：审计、只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System 审计。
-
-提示词只负责「怎么说」；模式、范围和规则仍以 `docs/` 为准。
+也可以 `pnpm link --global /path/to/codecraft`，之后在任意目录使用 `codecraft`。
 
-## 三种模式
+## 模式
 
 | 模式 | 是否改文件 | 对应命令 |
 |---|---|---|
@@ -174,7 +180,7 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
   "pack": "auto",
   "gates": [
     { "name": "typecheck", "run": "pnpm typecheck", "timeoutMs": 120000 },
-    { "name": "kit", "run": "pnpm kit:check", "timeoutMs": 120000 }
+    { "name": "test", "run": "pnpm test", "timeoutMs": 120000 }
   ]
 }
 ```

package/VERSION

@@ -1 +1 @@
-1.0.2
+1.0.3

package/adapters/claude/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codecraft
-description: Language-agnostic code standard for designing, auditing, reviewing, and refactoring code. Use when the user asks to design a project architecture, audit an existing project, produce a code review, or scaffold code under a project's code constitution.
+description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
 ---
 
 # Codecraft（代码手艺）

package/adapters/trae/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: codecraft
-description: Language-agnostic code standard for designing, auditing, reviewing, and refactoring code. Use when the user asks to design a project architecture, audit an existing project, produce a code review, or scaffold code under a project's code constitution.
+description: 语言无关的代码规范（Codecraft）。用于项目代码审计与分析、架构设计、重构评审、代码规范检查和脚手架。Language-agnostic code standard for auditing, reviewing, designing, and scaffolding code.
 ---
 
 # Codecraft（代码手艺）

package/codecraft.config.example.json

@@ -7,8 +7,8 @@
       "timeoutMs": 120000
     },
     {
-      "name": "kit",
-      "run": "pnpm kit:check",
+      "name": "test",
+      "run": "pnpm test",
       "timeoutMs": 120000
     }
   ]

package/docs/00-constitution.md

@@ -1,7 +1,7 @@
-# 代码宪法 v0（语言无关）
+# 代码宪法 v1（语言无关）
 
-> 2026-10-26 · v0 草稿，等确认后固化为 v1。
-> 用途：给人和 AI 的共同约束；语言无关，具体语法见《代码族卡 v0》。
+> 2026-10-27 · v1 稳定版。
+> 用途：给人和 AI 的共同约束；语言无关，具体语法见《代码族卡 v1》。
 > 读者：团队 / AI（Design Specification）。
 > 术语：English（中文）。
 

package/docs/01-family-cards.md

@@ -1,7 +1,7 @@
-# 代码族卡 v0（11 个环节）
+# 代码族卡 v1（11 个环节）
 
-> 2026-10-26 · v0 草稿。
-> 用途：把《代码宪法 v0》落到每个代码族（环节）；不同族可以不同形状，族内必须同形。
+> 2026-10-27 · v1 稳定版。
+> 用途：把《代码宪法 v1》落到每个代码族（环节）；不同族可以不同形状，族内必须同形。
 > 术语：English（中文）。
 
 ## 0. 卡模板
@@ -72,7 +72,7 @@
   - UI 类型（`XxxProps / XxxEmits`）放组件目录或 `types/<domain>`。
 - **项目决策**：`shared` 不是强制层；后端非 TS 时用 external + Wrapper；只有一个消费者时不建 shared。
 - **特殊**：`shared/types/` 不能变成杂物间；跨应用业务类型用 `packages/domain-<x>`。
-- **命名**：按《代码宪法 v0》§3.1（外部保持原名；通用中性；业务后缀角色；不用 `I` / `model_xxx`）；本卡不重复全表。
+- **命名**：按《代码宪法 v1》§3.1（外部保持原名；通用中性；业务后缀角色；不用 `I` / `model_xxx`）；本卡不重复全表。
 - **依赖**：General ← Business；Business 不 import External；UI 只消费 Business / General。
 - **契约**：外部类型只被 Wrapper import；页面 / 组件 / 行为层只用内部类型。
 - **状态与错误**：类型里不允许不可能组合；互斥状态用联合类型。

package/docs/02-ai-contract.md

@@ -1,13 +1,13 @@
-# AI 生成契约 v0
+# AI 生成契约 v1
 
-> 2026-10-26 · v0 草稿。
-> 用途：所有模型 / agent 生成或修改代码前先读；与《代码宪法 v0》《代码族卡 v0》配套。
+> 2026-10-27 · v1 稳定版。
+> 用途：所有模型 / agent 生成或修改代码前先读；与《代码宪法 v1》《代码族卡 v1》配套。
 > 术语：English（中文）。
 
 ## 1. 先读
 
-1. 《代码宪法 v0》
-2. 相关《代码族卡 v0》
+1. 《代码宪法 v1》
+2. 相关《代码族卡 v1》
 3. 设计架构时：`06-architecture.md`（档位 / 七步法 / 边界 / ADR）
 4. 需要选型时：`05-patterns.md`（按力选，不按名字选）
 5. 项目覆盖：`AGENTS.md` / `rules/` / `README`
@@ -23,7 +23,7 @@
 - 禁止手改生成物。
 - 禁止空 catch / 静默失败。
 - 禁止跨族复制而不登记母版与分叉点。
-- 禁止复制项目门禁（如 `kit:check`）；只通过 config 调用。
+- 禁止复制项目门禁（如 typecheck / lint / test）；只通过 config 调用。
 - 禁止在 Plan 模式改文件；只输出计划。
 - 禁止把密码 / 密钥 / 令牌 / AK/SK / 连接串 / 客户隐私写进代码、文档、示例或提示词；发现即脱敏并提醒。
 - 禁止外部文档引用内部文档 / 内部路径 / 内部主机名。

package/docs/04-gates.md

@@ -6,8 +6,8 @@
 
 | 层 | 负责 | 例子 | 是否内置 |
 |---|---|---|---|
-| **Universal（通用）** | Codecraft | A2 / A4 / A11 / A17、密钥扫描、文档路径 | 是 |
-| **Business（业务）** | 项目 | typecheck、单测、`kit:check`、契约测试、视觉回归、迁移检查 | 否，通过 config 调用 |
+| **Universal（通用）** | Codecraft | A2 / A11 / A17、密钥扫描、文档路径 | 是 |
+| **Business（业务）** | 项目 | typecheck、单测、lint、契约测试、视觉回归、迁移检查 | 否，通过 config 调用 |
 
 原则：**通用规则内置，业务门禁编排。** 不复制项目门禁，避免第二套实现。
 
@@ -29,7 +29,7 @@
   "pack": "auto",
   "gates": [
     { "name": "typecheck", "run": "pnpm typecheck", "timeoutMs": 120000 },
-    { "name": "kit", "run": "pnpm kit:check", "timeoutMs": 120000 }
+    { "name": "test", "run": "pnpm test", "timeoutMs": 120000 }
   ]
 }
 ```
@@ -44,7 +44,7 @@
 |---|---|---|
 | **App** | A17 / A21（A4 人工评审） | typecheck、单测、e2e、视觉回归 |
 | **Library** | A2 / A11 / A21 | build、单测、exports 检查、依赖对账 |
-| **Design System** | A2 / A11 / A21 | `kit:check`、契约快照、视觉回归、a11y |
+| **Design System** | A2 / A11 / A21 | 构建、契约快照、视觉回归、a11y |
 | **Docs** | A21 | 死链、三线头、交付白名单 |
 
 ### 4.1 内置规则

package/evals/golden-tasks.md

@@ -97,7 +97,7 @@
 
 - 输入：`packages/` 下的 UI 包，README 引用了内部 `docs/开发计划/...`，`dist/tokens.css` 缺标记。
 - 模式：Audit（`--pack design-system`）。
-- 期望：命中 A11 / A21；不重复实现 `kit:check`；给出改为自洽文档的最小改法。
+- 期望：命中 A11 / A21；不重复实现项目的 typecheck / lint / test 门禁；给出改为自洽文档的最小改法。
 - 失败信号：只报 library 规则；把内部文档路径当正常引用；建议复制项目门禁。
 
 ## 15. 密钥扫描

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@ultime/codecraft",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Language-agnostic code standard as an installable skill package.",
   "keywords": [
     "ai",
     "code-standard",
     "lint",
-    "skill"
+    "skill",
+    "audit",
+    "architecture",
+    "review",
+    "scaffold"
   ],
+  "author": "UltimeLam",
   "license": "MIT",
   "repository": {
     "type": "git",