@ultime/codecraft 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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。
+- README 增加「让 AI 怎么说」入口；adapters 增加提示词指针。
+
 ## 1.0.1 - 2026-10-27
 
 - 规范化 `bin` 路径，源码与发布元数据一致。

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：指针式（推荐）**
 
-# 检查任意项目
-node /path/to/codecraft/bin/codecraft.mjs check --root /path/to/project
+在项目规则里留一行，让 agent 做代码任务时来读：
+
+- Trae：项目 `.trae/rules/codecraft.md`
+- Claude：项目 `CLAUDE.md` 或 `~/.claude/CLAUDE.md`
+- 其他 agent：项目 `AGENTS.md`
+
+```md
+代码任务先读 <Codecraft 路径>/codecraft/adapters/trae/SKILL.md
 ```
 
-### 2. 安装 / 运行
+平台对应的入口文件：
+
+| 平台 | 入口文件 |
+|---|---|
+| 通用（读 `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/` 与该文件保持 `../../` 的相对位置（符号链接即可），否则入口里的路径会失效。
 
-包名 `@ultime/codecraft`，命令 `codecraft`。发布到 npm 后可直接运行：
+### 第 2 步：对 AI 说第一句话
+
+```text
+用 Codecraft 审计本项目，只读，不改文件。
+```
+
+只启用 skill、不说 Codecraft 时，agent 可能按普通项目分析处理，不保证走 Audit 模式。带上名字最稳。
+
+更多场景（只出报告、新项目、重构评审、架构设计、模式选型、脚手架、Design System）见 [docs/07-ai-prompts.md](./docs/07-ai-prompts.md)。
+
+### 第 3 步：需要本地检查时再装 CLI
 
 ```bash
 npx @ultime/codecraft check --root .
@@ -55,27 +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/` 与该文件保持 `../../` 的相对位置（符号链接即可），否则入口里的路径会失效。
+也可以 `pnpm link --global /path/to/codecraft`，之后在任意目录使用 `codecraft`。
 
-## 三种模式
+## 模式
 
 | 模式 | 是否改文件 | 对应命令 |
 |---|---|---|
@@ -168,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 }
   ]
 }
 ```
@@ -182,7 +194,7 @@ A4（单一收口）属于结构判断，由 review 与项目门禁负责，不
 ## 目录
 
 ```text
-docs/         宪法、族卡、AI 契约、风格总图、模式、架构、门禁
+docs/         宪法、族卡、AI 契约、风格总图、模式、架构、AI 提示词、门禁
 scenarios/    新项目 / 旧项目审计 / 只出报告 / 重构评审
 adapters/     generic / Trae / Claude 入口
 prompts/      输出格式

package/VERSION

@@ -1 +1 @@
-1.0.1
+1.0.3

package/adapters/README.md

@@ -8,3 +8,5 @@ Core 是 `docs/` + `scenarios/` + `scripts/`；adapters 只做入口，不复制
 - 未来：Cursor / Copilot / Gemini 等
 
 规则：adapter 只写“读什么、按什么流程、输出什么”，规则正文留在 `docs/`。
+
+使用者提示词（怎么对 AI 说）：[`../docs/07-ai-prompts.md`](../docs/07-ai-prompts.md)。

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/docs/07-ai-prompts.md

@@ -0,0 +1,148 @@
+# AI 使用提示词（Prompts）
+
+> 用途：给使用者一份可以直接复制的说法，让 AI 按 Codecraft 的模式工作。
+> 读法：先看「最小开场」，再按场景复制；提示词不替代规则，规则正文仍在 `docs/`。
+> 关系：入口见 `adapters/`；输出格式见 `prompts/output.md`；约束见 `02-ai-contract.md`。
+
+## 1. 先让 AI 找到 Codecraft
+
+在项目的 agent 入口里留一条指针，不要复制规则：
+
+- Trae：项目 `.trae/rules/codecraft.md`
+- Claude：`CLAUDE.md`
+- 通用：`AGENTS.md`
+
+```md
+代码任务先读 <Codecraft 仓库路径>/codecraft/adapters/<平台>/...
+```
+
+平台对应：Trae → `adapters/trae/SKILL.md`，Claude → `adapters/claude/SKILL.md`，其他 → `adapters/generic/AGENTS.md`。
+
+## 2. 最小开场
+
+任何任务都可以先用这段，再补场景：
+
+```text
+使用 Codecraft（<Codecraft 仓库路径>/codecraft）。
+模式：Audit / Plan / Apply。
+范围：<目录 / 包 / 文件 / diff>。
+任务：<一句话>。
+要求：先读 docs/00-constitution.md 和相关族卡；Audit / Plan 不改文件；按 prompts/output.md 输出。
+```
+
+模式：
+
+- **Audit**：只读，出报告。
+- **Plan**：只读，出计划。
+- **Apply**：改代码 + 跑门禁，先确认范围。
+
+## 3. 场景模板
+
+### 3.1 旧项目审计（Audit）
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Audit，只读，不改文件。
+范围：当前仓库。
+任务：按 scenarios/audit-existing.md 做一次体检。
+要求：逐条对照 A1–A21，标 pass / warn / fail；每条结论给文件路径、行号和 A-ID；最后给差距清单和分阶段升级计划。
+```
+
+### 3.2 只出报告（Report Only）
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Audit。
+范围：<目录>。
+任务：只出 findings，不做升级计划，不写文件。
+要求：按 scenarios/report-only.md 输出；每条 finding 有 severity、证据、影响、一句话建议；附版本号和扫描范围。
+```
+
+### 3.3 新项目设计（Plan）
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Plan，只读。
+输入：业务目标 <...>；端 <mp/app/web/admin>；团队规模 <...>；交付周期 <...>。
+任务：按 scenarios/new-project.md 设计架构。
+要求：先选规模档位（L0/L1/L2），再选环节、目录、契约；给分阶段计划，每阶段一个可验收的垂直切片。
+```
+
+### 3.4 重构 / 评审（Review / Apply）
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Review（只评审）或 Apply（执行）。
+范围：<diff / 文件 / 模块>。
+任务：按 scenarios/refactor-review.md 评审。
+要求：先列问题（边界 / 状态 / 错误 / 命名 / 注释 / 生成物），再给最小改动计划；能不改就不改；Apply 后跑门禁。
+```
+
+### 3.5 架构设计
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Plan。
+任务：按 docs/06-architecture.md 给候选架构。
+要求：先定档位和边界，再给 2–3 个候选方案与代价表；不要直接替我做决定；需要时用 ADR 记录取舍。
+```
+
+### 3.6 模式选型
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Plan。
+任务：在 <场景> 下按 docs/05-patterns.md 选型。
+要求：先说明要解决的「力」（变化点 / 约束 / 代价），再给候选模式；不要按模式名字反推需求。
+```
+
+### 3.7 脚手架
+
+CLI：
+
+```bash
+npx @ultime/codecraft init --root . --name <name>
+npx @ultime/codecraft init --root . --name <name> --apply
+```
+
+对 AI 说：
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Apply。
+任务：按 codecraft init 的 app / library 骨架创建 <name>；先给 dry-run 清单，确认后再 --apply；已存在路径不覆盖。
+```
+
+### 3.8 Design System 审计
+
+CLI：
+
+```bash
+npx @ultime/codecraft check --pack design-system --root .
+```
+
+对 AI 说：
+
+```text
+使用 Codecraft（<路径>/codecraft）。
+模式：Audit。
+范围：packages/。
+任务：按 design-system pack 审计包依赖、生成物标记、密钥和公开文档路径。
+要求：不要改文件；按 A2 / A11 / A21 归类；给最小修复计划。
+```
+
+## 4. 说法上的要点
+
+- 先说模式，不要让 AI 猜。
+- 给范围：目录 / 包 / 文件 / diff。
+- 要求「先读后做」，只读相关族卡，不要一次加载全部。
+- 要求证据和验证命令；结论要能反解到 A-ID。
+- 不要用「优化一下」「看着改」这类没有范围的说法。
+- 安全红线不可豁免；发现密钥立即停止并提示轮换。
+
+## 5. 参考
+
+- [02-ai-contract.md](./02-ai-contract.md)
+- [04-gates.md](./04-gates.md)
+- [../prompts/output.md](../prompts/output.md)
+- [../scenarios/](../scenarios/)

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.1",
+  "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",