feat!: 字段校验分合法域与建议区间，发布 0.2.0

AGENTS.md

@@ -1,15 +1,28 @@
 # AGENTS.md — @ultime/studio
 
-> 给在本仓库工作的 AI 与协作者：只放入口与红线，不复述 README。
-> 适用版本：0.1.x
+> 给在本仓库工作的 AI 与协作者：入口、可写 / 只读、红线与验收。
+> 适用版本：0.2.x
 
 ## 先读
 
 1. [`README.md`](./README.md) — 协议、控制器、导出与边界。
 2. [`rules/README.md`](./rules/README.md) — 本包开发规范。
-3. [`llms.txt`](./llms.txt) — AI 索引；能力表见 [`skills.md`](./skills.md)，操作约束见 [`agent.md`](./agent.md)。
+3. [`llms.txt`](./llms.txt) — AI 索引；能力表见 [`SKILLS.md`](./SKILLS.md)。
 4. [`src/definition.ts`](./src/definition.ts) — 定义协议；先看它再改运行时。
 
+## 可写 / 只读
+
+| 路径 | 条件 |
+|---|---|
+| `src/definition.ts` | 协议变更；必须同步所有领域包与契约测试 |
+| `src/controller.ts` | 状态 / 历史 / 校验 / 导出编排 |
+| `src/normalize.ts` / `src/diagnostics.ts` | 规范化与通用校验 |
+| `src/persistence.ts` / `src/preview.ts` / `src/export.ts` | 纯编解码 / 预览模型 / 导出编排 |
+| `tests/**` | 与改动同批 |
+| `rules/` / `llms.txt` / `SKILLS.md` | 随版本同批更新 |
+
+只读：`node_modules/**`；领域包的源码与产物（只在定义层消费，不跨包改）。
+
 ## 红线
 
 - **本包是上游通用运行时**：只放协议与运行时；领域字段 / 默认值 / 示例 / UI 都在上层包，不进入本包。
@@ -18,6 +31,7 @@
 - **不决定布局与控件形态**：运行时只处理配置数据。
 - **导出确定性**：同输入逐字节相同，lock 不含时间戳。
 - **字段是唯一 schema 载体**：不在别处维护第二份字段表。
+- **不改已发布版本元数据**：版本、许可与作者信息随新版本生效。
 
 ## 验证
 
@@ -27,4 +41,5 @@ pnpm test
 pnpm typecheck
 ```
 
-没跑或没跑通时，必须说明是哪一条、为什么。
+- 改协议：同步 README、`SKILLS.md`、受影响的领域包与版本戳；
+- 没跑或没跑通时，必须说明是哪一条、为什么。

CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0 - 2026-11-10
+
+- **行为变更**：字段范围分两层——`min` / `max` 是合法域，越界给 `error` 并阻断导出（API 侧防乱传）；新增 `suggested` 建议区间，越界只给 `warn`。类型 / 枚举 / 缺失仍是 `error`。
+- `hue` 明确为控件提示：运行时等同 `number`，不强制 0–360，也不隐式回绕。
+- 包内新增 `llms.txt` / `SKILLS.md` 作为消费侧 AI 入口，并与 `exports` 对齐；`rules/` 留仓，操作约束并入 `AGENTS.md`。
+- 协议注释与 README 同步上述口径。
+
 ## 0.1.2 - 2026-11-09
 
 - 测试与文档领域中立化：fixture 改为通用 `theme` 配置，不再使用任何具体领域的路径或字段。

README.md

@@ -23,6 +23,8 @@ pnpm add @ultime/studio
 
 领域定义不在这里：各领域包自行提供 `/studio` 子入口，本包只认通用协议。
 
+AI 入口：[`llms.txt`](./llms.txt)（路由）与 [`SKILLS.md`](./SKILLS.md)（能力表）随包发布。
+
 ## 三层分工
 
 | 层 | 谁写 | 内容 |
@@ -63,12 +65,15 @@ const direct = await exportConfig(configurator, config)
 | 项 | 约定 |
 |---|---|
 | `fields` | 唯一 schema 载体；`type` 只是 UI 提示，运行时只做通用类型 / 枚举 / 范围校验 |
+| `hue` | 只是控件提示（色相盘）；运行时等同 `number`，不强制 0–360，也不隐式回绕 |
+| `min` / `max` | 合法域；越界给 `error` 并阻断导出（防乱传导致产物不可用） |
+| `suggested` | 建议区间；越界只给 `warn`，不阻断导出 —— 风格好不好看由用户决定 |
 | `custom` | 通用校验跳过，语义交给定义的 `validate()` |
 | `set(path, value)` | 只改一个 JSON Pointer，做字段级取值修正；不自动重算诊断 |
 | `patch(patch)` | `add` / `remove` / `replace` 子集；AI 与诊断 fix 都产出 patch，可审阅 |
 | `replace` / `applyPreset` | 整体替换 config，baseline 不变 |
 | `reset` | 默认回 baseline；`mode: 'defaults'` 回定义默认值；带 `path` 只复位一个字段 |
-| `validate()` | 通用字段校验 + 定义 `validate()`；`error` 阻断导出，`warn` / `info` 不阻断 |
+| `validate()` | 通用字段校验 + 定义 `validate()`；类型 / 枚举 / 缺失 / 合法域越界 / 领域阻断给 `error`，建议类给 `warn` / `info` |
 | `export()` | 规范化 → 校验 → 定义 `export()`；返回 `ExportOutcome`，无文件 IO / 下载 |
 | `serialize()` | 稳定 JSON（对象键排序），可直接落项目配置（字段由定义包决定），不含派生值 |
 | `toURL()` / `fromURL()` | 纯编解码，`#studio=v1.…`，版本随串走；不依赖 `btoa` / `Buffer` / localStorage |
@@ -126,7 +131,7 @@ pnpm typecheck
 
 ## 版本与兼容
 
-- 当前 `0.1.x`；0.x 阶段 `ConfiguratorDefinition` 仍可能调整。
+- 当前 `0.2.x`；0.x 阶段 `ConfiguratorDefinition` 仍可能调整。
 - 破坏性变更写进 [CHANGELOG](./CHANGELOG.md)，并在本节目说明迁移方式；协议变更先发 studio，再发依赖包。
 - 零第三方运行时依赖。
 

skills.md → SKILLS.md

@@ -1,8 +1,8 @@
 # @ultime/studio · 可调用能力
 
 > 定位：AI 可调用的协议、方法与错误语义。字段与预设内容由领域包定义，本文件不手抄。
-> 适用版本：0.1.x
-> 同步基线：0.1.x（手写；导出面或协议变化时同批更新）
+> 适用版本：0.2.x
+> 同步基线：0.2.x（手写；导出面或协议变化时同批更新）
 
 ---
 
@@ -28,7 +28,7 @@ import {
 
 ## 错误语义
 
-- `validate()` 返回诊断数组：`error` 阻断导出，`warn` / `info` 不阻断。
+- `validate()` 返回诊断数组：类型 / 枚举 / 缺失 / `min`·`max` 合法域越界 / 领域阻断是 `error` 并阻断导出；`suggested` 建议区间与提示是 `warn` / `info`，不阻断。
 - `export()` 不抛异常；失败时返回 `ok: false` 与诊断。
 - 未知字段按 `unknownPolicy` 处理，只查对象键、不深入数组元素。
 - `$schema` / `$version` 视为元信息，不参与未知字段判定。

llms.txt

@@ -1,18 +1,15 @@
 # @ultime/studio · AI 索引
 
-适用版本：0.1.x
+适用版本：0.2.x
 
 ## 去哪找
 
 - 怎么用：[README.md](./README.md)
-- 开发规则：[rules/README.md](./rules/README.md)
-- 可调用能力：[skills.md](./skills.md)
-- 操作约束：[agent.md](./agent.md)
-- 仓库入口：[AGENTS.md](./AGENTS.md)
+- 可调用能力：[SKILLS.md](./SKILLS.md)
 
 ## 机器入口
 
-- 协议形状：`src/definition.ts`
+- 公共出口：`@ultime/studio` 的 `defineConfigurator` / `createConfigurator` / `exportConfig` / `normalizeConfig` / `assertContract`
 - 契约测试：`assertContract(definition)`
 - 校验 / 导出：`createConfigurator` / `exportConfig`
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultime/studio",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Ultime · studio：配置器无头运行时（定义 / 状态 / 规范化 / 诊断 / 预览模型 / 导出清单），纯 TS、零依赖、不碰 DOM 与文件系统",
   "keywords": [
     "configuration",
@@ -25,6 +25,8 @@
     "dist",
     "src",
     "README.md",
+    "llms.txt",
+    "SKILLS.md",
     "CHANGELOG.md",
     "CONTRIBUTING.md",
     "SECURITY.md"
@@ -49,7 +51,7 @@
   "devDependencies": {
     "@types/node": "^22.20.5",
     "typescript": "^5.9.3",
-    "vite-plus": "1.4.0"
+    "vite-plus": "1.5.1"
   },
   "engines": {
     "node": ">=22.18"