@liu_jimmy/blocks-spec

BlockSpec = AI 与代码生成器之间的 API，是 fe-kit AI Code Cache 的中间协议层。

位置 in 三层体系

规范层（tokens + eslint-preset）
    ↓
抽象层（BlockSpec）  ← 本包
    ↓
缓存层（AI Cache Store）+ Compiler → Vue/React/Svelte

• AI 输出 BlockSpec JSON
• 本包 提供 schema 校验 + TypeScript 类型
• 插件 / CLI 校验通过后写入缓存，再由 Compiler 生成框架代码

安装

pnpm add @liu_jimmy/blocks-spec

BlockSpec 格式（block.v1）

{
  "specVersion": "block.v1",
  "kind": "block",
  "name": "hero",
  "variant": "split",
  "props": {
    "title": "Build faster",
    "subtitle": "Ship modern web apps"
  }
}

| 字段 | 必填 | 说明 | |------|------|------| | specVersion | ✅ | 固定 "block.v1" | | kind | ✅ | 固定 "block" | | name | ✅ | 块类型：hero, faq, footer, cta, nav... | | variant | | 变体：split, centered, accordion... | | props | | 块级数据，由 name/variant 决定结构 | | slots | | 具名插槽内容 | | meta | | description, tags |

用法

校验

import { validateBlockSpec, assertBlockSpec } from "@liu_jimmy/blocks-spec";

const result = validateBlockSpec(aiOutput);
if (!result.valid) {
  console.error(result.errors);
  return;
}
// 通过后可写入缓存或交给 Compiler

断言（用于编译前）

import { assertBlockSpec } from "@liu_jimmy/blocks-spec";

assertBlockSpec(spec); // 抛错则 invalid
// spec 此处为 BlockSpec 类型，可传给 compiler

类型

import type { BlockSpec } from "@liu_jimmy/blocks-spec";

插件流程建议

1. 用户输入（如 “Generate hero section”）
2. 查缓存（key = hash(BlockSpec 或 name+variant+props)）
3. 命中 → 直接取已生成代码
4. 未命中 → 调 AI 生成 BlockSpec（不要直接生成 Vue/React 代码）
5. validateBlockSpec(spec) 校验
6. 保存到 AI Cache Store
7. Compiler(spec, framework) → 生成 Vue/React/Svelte 代码并写入项目

文件结构

blocks-spec/
  schema/
    block.v1.schema.json   # JSON Schema
  registry/                 # Block Library：按 block/variant 组织
    blocks.json             # block 与 variant 列表
    hero/
      split.json
      centered.json
    faq/accordion.json
    footer/default.json
    navbar/default.json
    features/grid.json
    pricing/default.json
    cta/banner.json
    hero.spec.json          # 兼容旧路径
    faq.spec.json
    footer.spec.json
  patches/
    registry.json           # Patch Library：各 block 支持的修改动作（add_faq_item、replace_text 等）
  validator.ts
  types.ts
  index.ts

Block Library

• 目录约定：registry/<block>/<variant>.json，参见 registry/blocks.json。
• 当前支持：hero(split/centered)、faq(accordion)、footer(default)、navbar(default)、features(grid)、pricing(default)、cta(banner)。

Patch Library

• patches/registry.json 列出各 block 可用的 patch 名称（如 add_faq_item、replace_text）。
• 对源码的修改动作（AST/模板级）由 @liu_jimmy/blocks-compiler 的 applyPatch(source, payload) 实现；初版仅实现 replace_text，其余留二期。

后续

• Compiler：根据 BlockSpec + framework 输出 .vue / .tsx / .svelte（可放在独立包如 @liu_jimmy/blocks-compiler）
• AI Cache Store：持久化 BlockSpec ↔ 生成代码，减少重复调用 AI