open-index/open-npm huggingface dataset:
npm package: @liu_jimmy/blocks-compiler
Description: Compile BlockSpec to Vue/React/Svelte source. Part of fe-kit AI Code Cache.
Latest version: 1.1.5

# @liu_jimmy/blocks-compiler

将 **BlockSpec** 编译为 Vue / React / Svelte 组件源码，仅使用 fe-kit 语义类（`bg-bg`、`text-fg`、`border-border`、`bg-primary`、`rounded-xl` 等）。fe-kit AI Code Cache 的编译层。

## 安装

```bash
pnpm add @liu_jimmy/blocks-spec @liu_jimmy/blocks-compiler
```

## API

### `compile(spec, framework, options?)`

- **spec**: 符合 block.v1 的 BlockSpec（对象即可，内部会校验）
- **framework**: `'vue' | 'react' | 'svelte'`
- **options**: 可选，如 `{ componentName?: string }`
- **返回**: 组件源码字符串（`.vue` / `.tsx` / `.svelte` 文件内容）

编译前会调用 `assertBlockSpec(spec)`，不符合 schema 会抛错。

### 按框架的编译函数

- `compileToVue(spec)` → Vue SFC 字符串
- `compileToReact(spec)` → React TSX 字符串
- `compileToSvelte(spec)` → Svelte 组件字符串

## 当前支持的块

| name   | variant   | 说明 |
|--------|-----------|------|
| hero   | split     | 标题、副标题、主/次 CTA |
| faq    | accordion | 标题 + 手风琴列表 |
| footer | default   | 版权 + 链接列表 |

未支持的 `name`/`variant` 会走通用占位模板（展示 `props` JSON）。

## 示例

```ts
import { compile } from "@liu_jimmy/blocks-compiler";
import heroSpec from "@liu_jimmy/blocks-spec/registry/hero.spec.json";

const vueSource = compile(heroSpec, "vue");
const reactSource = compile(heroSpec, "react");
const svelteSource = compile(heroSpec, "svelte");
// 可将 vueSource 写入 .vue 文件，在已接入 fe-kit preset 的项目中直接使用
```

## 带缓存的编译（测是否命中）

```ts
import { compileWithCache, cacheKey } from "@liu_jimmy/blocks-compiler";
import { memoryCache } from "@liu_jimmy/fe-kit-cache";
import heroSpec from "@liu_jimmy/blocks-spec/registry/hero.spec.json";

const r1 = compileWithCache(heroSpec, "vue", memoryCache);
console.log(r1.fromCache); // false，首次编译

const r2 = compileWithCache(heroSpec, "vue", memoryCache);
console.log(r2.fromCache); // true，从缓存读取
```

- 传入任意实现 `BlockCache`（get/set）的对象即可；可用 `@liu_jimmy/fe-kit-cache` 的 `memoryCache` 或 `createMemoryCache()`。
- 缓存 key 仅含 `name + variant + framework`，不含 props，便于同结构命中。

## 依赖

- **@liu_jimmy/blocks-spec**：类型与校验
- 生成的项目需使用 **Tailwind v3 + @liu_jimmy/fe-kit-tailwind-preset**，才能正确解析语义类。
npm package: @liu_jimmy/blocks-spec
Description: BlockSpec protocol: AI ↔ code generator (schema, validator, registry). Part of fe-kit AI Code Cache layer.
Latest version: 1.1.4

# @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** 生成框架代码

## 安装

```bash
pnpm add @liu_jimmy/blocks-spec
```

## BlockSpec 格式（block.v1）

```json
{
  "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 |

## 用法

### 校验

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

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

### 断言（用于编译前）

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

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

### 类型

```ts
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
npm package: @liu_jimmy/fe-kit-cache
Description: Minimal cache for compiled blocks (block:variant:framework). Part of fe-kit AI Code Cache.
Latest version: 1.0.3

# @liu_jimmy/fe-kit-cache

最小缓存层：key = `block:variant:framework`，value = 编译后的组件源码。**props 不进 key**，便于同一 block 多次命中。

## 安装

```bash
pnpm add @liu_jimmy/fe-kit-cache
```

## API

- **`cacheKey(blockName, variant, framework)`** — 生成 key 字符串
- **`memoryCache`** — 默认单例**内存**缓存（进程内有效，进程结束即清空）
- **`createMemoryCache()`** — 新建独立内存缓存（测试/隔离用）
- **`createDiskCache()`** — **磁盘**缓存：读写 `~/.fe-kit/block-cache.json`（可通过环境变量 `FE_KIT_CACHE_DIR` 指定目录）。**跨项目、跨进程共享**，同一台机器上多次编译同一 block 会命中。
- 实现均为 `BlockCache`：**`get(key)`** → `{ hit: true, source } | { hit: false }`，**`set(key, source)`**，**`has(key)`**

与 `@liu_jimmy/blocks-compiler` 的 `compileWithCache(spec, framework, cache)` 配合使用；传 `memoryCache` 仅当前进程复用，传 `createDiskCache()` 可跨项目复用。
npm package: @liu_jimmy/fe-kit-cli
Description: fe-kit CLI: ai stats, ai record. Track cache hits and token usage.
Latest version: 1.0.4

# @liu_jimmy/fe-kit-cli

CLI：`ai stats` 查看缓存与 token 统计，`ai record` 在每次请求后追加一条数据。

## 安装

```bash
pnpm add -D @liu_jimmy/fe-kit-cli
# 或全局
pnpm add -g @liu_jimmy/fe-kit-cli
```

## 命令

### ai stats

输出示例：

```
AI Cache Stats
--------------
Requests:    128
Cache hits:  92
Hit rate:    71.8%

Tokens used:  24,300
Tokens saved: 78,200

Cost saved: $0.39
```

数据来自 `~/.fe-kit/stats.json`（可通过环境变量 `FE_KIT_STATS_DIR` 指定目录）。

### ai record

在**每次 Cursor / AI 请求完成后**执行一次，用于更新统计。

```bash
# 一次未命中缓存的请求，消耗了 800 tokens
ai record --request --tokens-used 800

# 一次命中缓存的请求，相当于节省了 1200 tokens
ai record --request --cache-hit --tokens-saved 1200
```

简写：`-r` = `--request`，`-c` = `--cache-hit`。

### 在 Cursor 里接上「请求完成后记录」（推荐方式 B）

- **方式 B（推荐）**：用 create-fe-kit 生成的项目已自带规则：AI 会在回复末尾提示你执行一次 `ai record ...`（命中缓存则带 `--cache-hit --tokens-saved <估算>`，否则 `--tokens-used <估算>`），你复制到终端执行即可。
- **手动**：也可在需要时自己执行 `ai record --request --cache-hit --tokens-saved 1200` 或 `ai record --request --tokens-used 500`。
- **程序内记录**：若在脚本里调用 `compileWithCache`，可同时调用：

   ```ts
   import { recordStats } from "@liu_jimmy/fe-kit-cli";
   const result = compileWithCache(spec, "vue", cache);
   recordStats({
     request: true,
     cacheHit: result.fromCache,
     tokensUsed: result.fromCache ? 0 : 500,
     tokensSaved: result.fromCache ? 500 : 0,
   });
   ```

Cost saved 仅作记录参考，按每百万 tokens 粗算；可选环境变量 `FE_KIT_COST_PER_MILLION` 调整单价。