UltimeLam · Nov 10, 2026 · Nov 10, 2026 · Nov 10, 2026 · Nov 10, 2026
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -9,7 +9,11 @@
 - [ ] 没有新增第二份正文、重复入口或第二套默认值
 - [ ] 协议 / 导出 / 序列化变更已有测试与影响说明
 - [ ] 没有引入领域包依赖或 UI / IO 逻辑
-- [ ] 已跑 `pnpm check`、`pnpm test`、`pnpm typecheck`、`npm pack --dry-run`
+- [ ] 包体边界：`npm pack --dry-run` 不含 `tests` / `scripts` / `rules` / 包根 `AGENTS.md` / 构建配置 / lockfile
+- [ ] Node 基线：`engines.node >= 22.18`、产物 `target: node22` 未偏离
+- [ ] 包质量：`pnpm build` 的 `publint` / `attw` / `unused` 通过
+- [ ] 体积报告已看（`pnpm size`，只报告、不设门禁）
+- [ ] 已跑 `pnpm check`、`pnpm test`、`pnpm build`、`npm pack --dry-run`
 
 ## 审核重点
 

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -15,20 +15,24 @@ concurrency:
 jobs:
   ci:
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node: [22, 24]
     steps:
       - uses: actions/checkout@v4
 
-      - uses: pnpm/action-setup@v4
+      - uses: voidzero-dev/setup-vp@v1.22.0
         with:
-          version: 12.6.0
+          node-version: ${{ matrix.node }}
+          cache: true
 
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 22
-          cache: pnpm
+      - run: pnpm check
 
-      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+        if: matrix.node == 24
 
-      - run: pnpm check
+      - run: pnpm size
+        if: matrix.node == 24
 
       - run: pnpm test
diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,6 @@ coverage/
 *.log
 *.tsbuildinfo
 .DS_Store
+
+# Vite+ 生成的 Git hook dispatcher（项目自己的 hook 在 .vite-hooks/ 下）
+.vite-hooks/_/
diff --git a/.node-version b/.node-version
@@ -0,0 +1 @@
+24.22.2
diff --git a/.vite-hooks/pre-commit b/.vite-hooks/pre-commit
@@ -0,0 +1,26 @@
+#!/bin/sh
+# ============================================================================
+# pre-commit — 提交前闸门（静态检查，不起浏览器）
+# ----------------------------------------------------------------------------
+# 先 `vp staged` 处理暂存文件，再跑包内 `check`；需要浏览器的检查不进钩子。
+# 环境不具备（没有 node）时放行并提示，不算不合格。
+# 手动安装：pnpm exec vp config --no-agent；诊断：vp hooks status
+# ============================================================================
+set -e
+ROOT="$(git rev-parse --show-toplevel)"
+cd "$ROOT"
+
+if ! command -v node >/dev/null 2>&1; then
+  echo "⚠ pre-commit：未找到 node，跳过静态闸门（PATH=$PATH）"
+  exit 0
+fi
+
+VP="$ROOT/node_modules/.bin/vp"
+
+echo "── pre-commit：Vite+ staged（fmt / lint）─────────────────────────────"
+"$VP" staged || exit 1
+
+echo "── pre-commit：包内静态检查 ───────────────────────────────────────────"
+"$VP" run check || exit 1
+
+echo "✓ 静态闸门通过"
diff --git a/AGENTS.md b/AGENTS.md
@@ -38,7 +38,6 @@
 ```bash
 pnpm check
 pnpm test
-pnpm typecheck
 ```
 
 - 改协议：同步 README、`SKILLS.md`、受影响的领域包与版本戳；

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.1 - 2026-11-11
+
+- 构建改用 `vp pack`，产物同时生成 `dist/index.js` 与 `dist/index.d.ts`。
+- `exports.types` 指向 `dist/index.d.ts`，包体不再包含 `src/`；安装后类型解析不依赖源码。
+- `PreviewModel` 新增可选 `diagnostics`，用于承载预览生成失败的原因。
+
 ## 0.2.0 - 2026-11-10
 
 - **行为变更**：字段范围分两层——`min` / `max` 是合法域，越界给 `error` 并阻断导出（API 侧防乱传）；新增 `suggested` 建议区间，越界只给 `warn`。类型 / 枚举 / 缺失仍是 `error`。

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -27,6 +27,8 @@
 - **冗余**：同一事实只有一份正文；新增说明先改真源，其他位置只留指针。
 - **缺漏**：新增能力是否有入口、示例与验证命令。
 - **漂移**：`package.json` / README / `CHANGELOG` / VERSION（及适用的 AI 文档）版本是否一致。
+- **包体**：`npm pack --dry-run` 不含 `tests` / `scripts` / `rules` / 包根 `AGENTS.md` / 构建配置 / lockfile；`exports` 与类型入口一致。
+- **基线**：`engines.node >= 22.18`、`build.target: node22` 未偏离；开发端脚本与依赖不进入发布包。
 
 机械检查交给 CI；人审看架构、边界、语义与取舍。
 
@@ -35,7 +37,8 @@
 ```bash
 pnpm check
 pnpm test
-pnpm typecheck
+pnpm build          # 含 publint / attw / unused
+pnpm size           # 体积只报告，不设门禁
 npm pack --dry-run
 ```
 

diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@
 pnpm add @ultime/studio
 ```
 
-- 运行环境 Node >= 22.18，或任何支持 ESM 的打包器（Vite / esbuild 等）；包发的是编译后的 ESM（`dist/`），类型来自 `src/*.ts`。
+- 运行环境 Node >= 22.18，或任何支持 ESM 的打包器（Vite / esbuild 等）；包发的是编译后的 ESM（`dist/`），类型来自 `dist/*.d.ts`。
 - 本包**不 import** 任何领域包；领域定义放在各包的 `/studio` 子入口，本包只认通用协议。
 
 ## 入口
@@ -119,7 +119,6 @@ tests/
 
 ```bash
 pnpm test
-pnpm typecheck
 ```
 
 ## 边界

diff --git a/checks.config.mjs b/checks.config.mjs
@@ -0,0 +1,19 @@
+/** 通过 @ultime/checks 运行；规则与词表按本包维护。 */
+export default {
+  roots: ['.'],
+  ignore: ['node_modules', 'dist', 'coverage', '.vite-hooks', '.tmp', 'checks.config.mjs'],
+  rules: [
+    { use: 'imports', severity: 'error', options: { packageRoots: ['.'], packages: ['@ultime/'] } },
+    { use: 'unresolved', severity: 'warn', options: { scope: ['src/**', 'scripts/**'] } },
+    {
+      use: 'text',
+      severity: 'error',
+      options: {
+        include: 'all',
+        deny: ['docs/', 'roadmap/', 'design-system/\\d', 'references', '小巨蛋', 'xiaojudan', '归序札记'],
+        warn: ['以前|上一版|旧值|下一轮|待补|待实现|未实现|不再用|TODO|FIXME'],
+      },
+    },
+    { use: 'doc-set', severity: 'error', options: { packages: ['.'] } },
+  ],
+}
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@ultime/studio",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Ultime · studio：配置器无头运行时（定义 / 状态 / 规范化 / 诊断 / 预览模型 / 导出清单），纯 TS、零依赖、不碰 DOM 与文件系统",
   "keywords": [
     "configuration",
@@ -23,7 +23,6 @@
   },
   "files": [
     "dist",
-    "src",
     "README.md",
     "llms.txt",
     "SKILLS.md",
@@ -34,25 +33,40 @@
   "type": "module",
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "vp build",
-    "check": "vp check",
+    "build": "vp pack",
+    "check": "vp check && checks run && pnpm cycles",
+    "checks": "checks run",
+    "cycles": "vp lint --import-plugin --deny=import/no-cycle src",
     "test": "vp test",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "pnpm check && pnpm test && pnpm build"
+    "size": "size-limit --json",
+    "prepublishOnly": "pnpm check && pnpm test && pnpm build",
+    "prepare": "vp config --no-agent"
   },
   "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.5",
+    "@size-limit/preset-small-lib": "^14.3.0",
     "@types/node": "^22.20.5",
+    "@ultime/checks": "^0.2.0",
+    "publint": "^0.3.25",
+    "size-limit": "^14.3.0",
     "typescript": "^5.9.3",
+    "unplugin-unused": "^0.6.0",
     "vite-plus": "1.5.1"
   },
+  "size-limit": [
+    {
+      "name": "@ultime/studio",
+      "path": "dist/index.js"
+    }
+  ],
   "engines": {
     "node": ">=22.18"
   },