feat!: 收紧出口与配置器契约，发布 0.8.0

.gitignore

@@ -5,5 +5,5 @@ coverage/
 *.tsbuildinfo
 .DS_Store
 
-# Vite+ 生成的 Git hook dispatcher（项目自己的 hook 在 .githooks/pre-commit）
-.githooks/_/
+# Vite+ 生成的 Git hook dispatcher（项目自己的 hook 在 .vite-hooks/pre-commit）
+.vite-hooks/_/

.githooks/pre-commit → .vite-hooks/pre-commit

@@ -6,7 +6,7 @@
 #   · build.ts --check 在内存重算产物并与工作区逐字节比对；
 #   · 检出不同步时改源后重跑 `pnpm build:tokens`，不要手改产物。
 # 环境不具备（没有 node）时放行并提示，不算不合格。
-# 手动安装：pnpm exec vp hooks enable --hooks-dir .githooks
+# 手动安装：pnpm exec vp hooks enable
 # ============================================================================
 set -e
 ROOT="$(git rev-parse --show-toplevel)"

AGENTS.md

@@ -1,20 +1,33 @@
 # AGENTS.md — @ultime/core
 
-> 给在本仓库工作的 AI 与协作者：只放入口与红线，不复述 README。
-> 适用版本：0.7.x
+> 给在本仓库工作的 AI 与协作者：入口、可写 / 只读、红线与验收。
+> 适用版本：0.8.x
 
 ## 先读
 
 1. [`README.md`](./README.md) — 用法、出口、产物与边界。
 2. [`DESIGN.md`](./DESIGN.md) — 设计理念与数值出处；判断某内容该不该进 core。
 3. [`rules/README.md`](./rules/README.md) — 本包开发规范。
-4. [`llms.txt`](./llms.txt) — AI 索引；能力表见 [`skills.md`](./skills.md)，操作约束见 [`agent.md`](./agent.md)。
+4. [`llms.txt`](./llms.txt) — AI 索引；能力表见 [`SKILLS.md`](./SKILLS.md)。
 5. [`src/build.ts`](./src/build.ts) — seed → 树 → 合同 → manifest 的唯一装配点。
 6. [`src/tools/project.ts`](./src/tools/project.ts) — `planProject`：一次派生 → artifacts / manifest / diagnostics。
 7. [`src/studio/selection.ts`](./src/studio/selection.ts) — 配置器选择模型：类别 / 档位过滤与定制产物。
 8. [`src/studio/derivation.ts`](./src/studio/derivation.ts) — 配置器自定义派生：只调参数化引擎函数。
 9. [`scripts/check-model.ts`](./scripts/check-model.ts) — 结构与依赖方向守卫。
 
+## 可写 / 只读
+
+| 路径 | 条件 |
+|---|---|
+| `src/seed.ts` / `src/model/**` | 值或派生规则变更；必须有合同或测试 |
+| `src/exporters/**` | 只改翻译写法，不改值与派生 |
+| `src/tools/**` / `src/studio/**` | 工具层 / 配置器定义；不引入文件 IO 或 DOM |
+| `tests/**` | 与代码改动同批 |
+| `scripts/**` | 守卫或构建入口；不放业务逻辑 |
+| `rules/` / `llms.txt` / `SKILLS.md` | 随版本同批更新 |
+
+只读：`tokens.css` / `tokens.json` / `tokens.dtcg.json` / `kernel.json`（生成物，改源后重跑）；`dist/**`；`node_modules/**`。
+
 ## 红线
 
 - **功能变更同批更新**：测试、README、`CHANGELOG.md` 与 AI 文档；没有功能性更新时只改文档并写明。
@@ -27,6 +40,8 @@
 - **派生优先**：能由 seed 参数算出的值不写第二份名单；同一事实只保留一份。
 - **不带载体语法**：模型只产出值、量纲与 `$type`；`px` / `rem` / `var()` / `color-mix` 只出现在出口。
 - **不引第三方运行时依赖**：`@ultime/studio` 仅在 `src/studio/**` 使用。
+- **不放宽守卫**：不为让检查通过而改守卫或跳过；守卫缺口按缺陷登记。
+- **文档不抄数值**：数值从 `ultime schema --json` 或 `kernel.json` 查，不从 Markdown 抄。
 
 ## 验证
 
@@ -36,8 +51,14 @@ pnpm test
 pnpm typecheck
 ```
 
-没跑或没跑通时，必须说明是哪一条、为什么。
+- 改了 seed / model：再跑 `pnpm build:tokens`，看产物 diff；
+- 改了导出面：同步 `README.md`、`SKILLS.md` 与版本戳；
+- 没跑或没跑通时，必须说明是哪一条、为什么。
 
 ## 提交
 
 一个主题一个提交；源与生成物同改同提。
+
+## 不确定时
+
+先查 `DESIGN.md` 的五问；仍不确定就停下来问，不猜默认值、不新造 token。

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.8.0 - 2026-11-10
+
+- **Breaking**：`./tools` 出口移除 `require` 条件，全包统一 ESM-only；不再承诺 `require('@ultime/core/tools')` 这条 CJS 路径。
+- 配置器只为 core 原版配置（`THEME_DEFAULTS`，无 selection / derivation）缓存一份派生，进程内只算一次；用户自定义配置每次独立派生。`inspect` 返回的 manifest / counts / diagnostics 是副本，调用方改动不会污染基线。
+- 配置器字段区分**合法域**与**建议区间**：`min` / `max` 越界给 `error` 并阻断导出（API 侧防乱传），新增 `suggested` 越界只给 `warn`；core 字段按安全边界重新分配（alpha 0–1、档数 ≥ 1 等为合法域，常用取值落在建议区间）。
+- 合同补齐结构非空校验：`radius` / `duration` / `loop` / `delay` 档数为 0 时判失败并阻断导出。
+- 合同诊断不再整体截断：`error` 永不截断，非 error 合同诊断最多展示 12 条，超出追加 `core/contract.truncated` 摘要，避免阻断判定被截掉。
+- 收紧 npm 包内容：`AGENTS.md`（含可写 / 只读与操作约束）/ `rules/` 留仓；`llms.txt` / `SKILLS.md` 作为消费侧 AI 入口随包发布，并与 `exports` 对齐。
+- `README` 补 AI 入口与 ESM-only 说明；`DESIGN.md` 的玻璃条目改为只描述归属，不带实现状态。
+- `engineVersion` 保持 0.7.0（派生结果未变）。
+
 ## 0.7.0 - 2026-11-09
 
 - 新增 `@ultime/core/studio` 无头选择 API：`selectBuild` / `selectTree`，按类别与档位从完整树导出定制 tokens。

DESIGN.md

@@ -96,7 +96,7 @@
 | 图表分类 / 连续 / 发散色板 | 组件层 / 风格包 | 与状态语义混淆，属独立维度 |
 | 交互反馈改几何 | kit / 风格包 | 状态反馈恒定几何是上层契约 |
 
-**玻璃是唯一例外**：它作为填充角色进入 core（`blur` + 透明度，待实现），不算材质轴；渗色、噪点与其余材质仍归风格层。
+**玻璃不单独成轴**：它只是填充的一种（`blur` + 透明度），不算材质轴；渗色、噪点与其余材质仍归风格层。
 
 判断口诀：**它是「值 / 参数」还是「用法 / 策略」？** 值进内核；用法归语义表或组件层。
 

README.md

@@ -28,6 +28,8 @@ pnpm add @ultime/core
 Node.js >= 22.18。内核的 `.` / `./exporters` / `./tools` / `./seed` 出口是编译后的 JS，零第三方依赖；
 `./studio` 出口（配置器）依赖 `@ultime/studio`，`ultime` bin 依赖 `@ultime/cli`；不用配置器 / CLI 时不会进入你的产物。
 
+所有出口 **ESM-only**：用 `import` / `import()` 消费，不提供 `require` 入口。
+
 ## 快速开始
 
 ```js
@@ -315,7 +317,7 @@ pnpm build:tokens -- --seed path/to/theme.json
 
 - 机器入口是 `kernel.json` 与 `ultime schema --json`；不要让 agent 从 Markdown 里抄数值。
 - 完整设计规范（取值理由、对比度与配对判据）不随包分发：安装 [`@ultime/designcraft`](https://www.npmjs.com/package/@ultime/designcraft) skill（`npx skills add ultime-space/skills --skill designcraft`）阅读。
-- 在本仓库内工作的约定见 [AGENTS.md](./AGENTS.md)。
+- 包内 AI 入口是 [`llms.txt`](./llms.txt)（路由）与 [`SKILLS.md`](./SKILLS.md)（能力表）；`AGENTS.md` / `rules/` 只在仓库内维护。
 
 ---
 

skills.md → SKILLS.md

@@ -1,8 +1,8 @@
 # @ultime/core · 可调用能力
 
 > 定位：AI 可调用的入口、产物与错误语义。字段清单以 `ultime schema --json` 为准，本文件不手抄。
-> 适用版本：0.7.x
-> 同步基线：0.7.x（手写；导出面或 schema 变化时同批更新）
+> 适用版本：0.8.x
+> 同步基线：0.8.x（手写；导出面或 schema 变化时同批更新）
 
 ---
 

llms.txt

@@ -1,25 +1,21 @@
 # @ultime/core · AI 索引
 
-适用版本：0.7.x
+适用版本：0.8.x
 
 ## 去哪找
 
 - 怎么用：[README.md](./README.md)
 - 为什么这样设计：[DESIGN.md](./DESIGN.md)
-- 开发规则：[rules/README.md](./rules/README.md)
-- 可调用能力：[skills.md](./skills.md)
-- 操作约束：[agent.md](./agent.md)
-- 仓库入口：[AGENTS.md](./AGENTS.md)
+- 可调用能力：[SKILLS.md](./SKILLS.md)
 
 ## 机器入口
 
 - 快照与合同：`kernel.json`
 - 字段 / 出口 / 语义表：`ultime schema --json`
-- 产物同源：`pnpm build:tokens --check`
-- 全量校验：`pnpm check && pnpm test`
+- 产物同源：`ultime build --check`
 
 ## 边界
 
 - 只给档、参数与合同；语义表、布局、目标尺寸、交互归上层。
-- 不手改生成物；改 seed / model 后重跑。
+- 不手改生成物；改 seed / model 后重跑构建。
 - 数值不抄进文档；需要时跑查询命令。

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Ultime · core：平台无关的设计系统内核（seed → 树 → 快照）；Web 的 CSS 只是它的一个出口",
   "keywords": [
     "color-system",
@@ -35,14 +35,11 @@
     "theme.example.json",
     "README.md",
     "DESIGN.md",
+    "llms.txt",
+    "SKILLS.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
-    "SECURITY.md",
-    "AGENTS.md",
-    "rules",
-    "llms.txt",
-    "skills.md",
-    "agent.md"
+    "SECURITY.md"
   ],
   "type": "module",
   "sideEffects": [
@@ -63,8 +60,7 @@
     },
     "./tools": {
       "types": "./src/tools/index.ts",
-      "import": "./dist/tools.js",
-      "require": "./dist/tools.js"
+      "import": "./dist/tools.js"
     },
     "./seed": {
       "types": "./src/seed.ts",
@@ -90,17 +86,17 @@
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vp test",
     "prepublishOnly": "pnpm check && pnpm test && pnpm build",
-    "prepare": "node -e \"if (require('fs').existsSync('.git')) require('child_process').execSync('vp hooks enable --hooks-dir .githooks', { stdio: 'inherit' })\""
+    "prepare": "vp config --no-agent"
   },
   "dependencies": {
     "@ultime/cli": "^0.1.0",
-    "@ultime/studio": "^0.1.0"
+    "@ultime/studio": "^0.2.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.5",
     "tsx": "^4.23.15",
     "typescript": "^5.9.3",
-    "vite-plus": "1.4.0"
+    "vite-plus": "1.5.1"
   },
   "engines": {
     "node": ">=22.18"