@ai-slot/proxy 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iannil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,227 @@
+# @ai-slot/proxy
+
+> AI-rendered page content — without leaked API keys, invalid LLM output, or white screens.
+
+The server side of the **ai-slot-component** SDK (private monorepo, not yet on npm): one stateless handler that turns a slot ID into a **validated component tree**. It speaks Web standard `Request → Response`, so it deploys unchanged to Cloudflare Workers, Deno, Bun, Vercel Edge, or a plain Node server.
+
+```text
+PromptCompiler → LLM Client (retry, 8s timeout) → OutputValidator → Cache (fresh → stale → 503)
+```
+
+中文文档：[仓库 CLAUDE.md](../../CLAUDE.md) · [总体设计](../../docs/superpowers/specs/2026-09-24-ai-native-rendering-sdk-design.md)
+
+## Quick start
+
+Workspace install (Node ≥ 18): `pnpm install && pnpm build` at the repo root, then `import ... from "@ai-slot/proxy"` in any workspace package.
+
+```ts
+import { createAiRenderHandler, createOpenAIClient } from "@ai-slot/proxy";
+import { defineRegistry } from "@ai-slot/registry";
+
+// 1. Declare the only components the LLM may ever output.
+const registry = defineRegistry({
+  components: {
+    "hero-banner": {
+      description: "Page hero section",
+      props: { title: { type: "string", maxLength: 60 }, subtitle: { type: "string", maxLength: 120 } },
+      required: ["title"],
+    },
+  },
+});
+
+// 2. Map slot IDs to the original page content you want enhanced.
+const slots = new Map([
+  ["hero", {
+    slotId: "hero",
+    originalContent: "<h1>Our product</h1><p>A plain product intro.</p>",
+    developerPrompt: "Audience: developers. Emphasize the 5-minute integration.",
+    contentVersion: "v1", // bump to bust the L1 cache
+  }],
+]);
+
+// 3. Assemble the handler. Your key stays here, on the server.
+const handler = createAiRenderHandler({
+  registry,
+  llm: createOpenAIClient({ apiKey: process.env.OPENAI_API_KEY! }),
+  resolveSlot: (slotId) => slots.get(slotId) ?? null,
+});
+
+export default handler;
+// Serve it: Deno.serve(handler) · Bun.serve({ fetch: handler })
+// · or wrap in node:http like examples/plain-html/server.mjs
+```
+
+```bash
+curl "http://localhost:8000/ai-render/hero"
+```
+
+```json
+{
+  "version": 1,
+  "slot": "hero",
+  "tree": { "component": "hero-banner", "props": { "title": "Ship AI-enhanced pages in 5 minutes" } },
+  "meta": { "reason": "developer-prompt" }
+}
+```
+
+That `tree` is what [`<ai-slot>` in packages/runtime](../runtime/) renders; the element's original content stays on the page as the fallback.
+
+## Two paths, one endpoint
+
+| | `GET /ai-render/:slotId` | `POST /ai-render/:slotId` |
+|---|---|---|
+| Who calls it | You, at build time | End users, at runtime |
+| Prompt | Developer prompt, from `resolveSlot()` | User prompt, request body `{ "prompt": "..." }` |
+| Cache | L1 — fresh 1 h, key = slot + `contentVersion` + `promptVersion` | L2 — fresh 10 min, key = slot + normalized prompt (trim/lowercase/collapse whitespace, so "  Big   Title " and "big title" share an entry) |
+| Guardrails | — | 10 requests/min/IP (`x-forwarded-for`), prompt sanitized to ≤500 chars with control characters stripped |
+| Typical use | `prewarm()` in CI, then serve static | `<ai-slot editable>` live rewriting |
+
+Model tiers follow the paths: `models.developer` for GET (default `gpt-4o-mini`), `models.user` for POST — point the cheap model at live user traffic.
+
+## Why it is safe to put an LLM on your page
+
+- **The model never outputs HTML.** It may only compose components from your registry; `validateComponentTree` (from `@ai-slot/registry`, shared with the client runtime) enforces component names, prop schemas, slot nesting, depth, and node count. Anything else is discarded.
+- **Keys never reach the browser.** Every LLM call happens inside this handler.
+- **Failure is invisible.** Retry once → fall back to stale cache (1 day window) → `503 ai_unavailable`. The `<ai-slot>` element keeps its original content either way: no white screen, no user-facing error.
+- **User prompts are untrusted input.** They are sanitized, then injected as constrained context — never as instructions — and the validator has the final say.
+- **Budgets are enforced, not hoped for.** 8 s timeout, `maxTokens` cap (default 2000), per-IP rate limit, and an `onUsage` hook for billing/tuning logs.
+
+## Streaming: skeleton first, tree second
+
+Send `Accept: text/event-stream` and the same endpoint responds with two SSE frames — the skeleton is derived from the final tree, so the placeholder already has the exact shape the real render will take:
+
+```text
+event: skeleton
+data: {"version":1,"slot":"hero","tree":{"component":"hero-banner","props":{"title":"","subtitle":""}},"meta":{"phase":"skeleton"}}
+
+event: tree
+data: {"version":1,"slot":"hero","tree":{...full tree...},"meta":{"reason":"developer-prompt"}}
+```
+
+Client side: `<ai-slot stream>`. Cached hits are re-framed as SSE too, so streaming and caching never disagree.
+
+## Pregenerate in CI ("AI static pages")
+
+```ts
+const store = new MemoryCacheStore();
+const handler = createAiRenderHandler({
+  registry, llm, store, resolveSlot,
+  developerTtlMs: 24 * 3600_000, staleMs: 7 * 24 * 3600_000,
+});
+
+const { ok, failed } = await prewarm(handler, ["hero", "pricing"]); // one slot failing won't abort the rest
+await writeFile("ai-cache.json", store.dump());
+```
+
+Ship `ai-cache.json` with your build, then hydrate at boot:
+
+```ts
+const store = MemoryCacheStore.load(await readFile("ai-cache.json", "utf8"), Date.now());
+```
+
+Expired entries are dropped on load; your live path inherits the prewarmed cache with zero extra code.
+
+## Push invalidation when your data changes
+
+`createInvalidationChannel()` gives you an SSE endpoint plus a broadcast function; you decide what triggers it (CMS webhook, cron diff, admin route).
+
+```ts
+const invalidation = createInvalidationChannel(); // { handler, invalidate, subscriberCount }
+// route GET /ai-invalidate to invalidation.handler
+invalidation.invalidate("hero"); // → event: invalidate / data: {"slot":"hero"} to every subscriber
+```
+
+`?slot=<id>` filter, `: ping` heartbeat every 25 s (configurable via `heartbeatMs`), subscribers cleaned up on disconnect. Client side: `<ai-slot live live-src="/ai-invalidate">`.
+
+## How it works
+
+```mermaid
+flowchart TD
+    A["Request: /ai-render/:slotId"] --> B{"POST?"}
+    B -- "user prompt" --> C["rate limit + sanitize"]
+    B -- "build time" --> D["resolveSlot()"]
+    C --> D
+    D --> E{"fresh cache hit?"}
+    E -- "yes" --> F["return cached tree"]
+    E -- "no" --> G["compilePrompt → LLM → validateComponentTree"]
+    G -- "valid" --> F
+    G -- "invalid / LLM down" --> H["stale cache → 503"]
+```
+
+## API
+
+### `createAiRenderHandler(opts)`
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `registry` | `Registry` | — | required — the component allowlist |
+| `llm` | `LLMClient` | — | required — any provider; wrapped in `withRetry` (1 retry) for you |
+| `resolveSlot` | `(slotId) => SlotSource \| null` | — | required — return `null` for unknown slots |
+| `models` | `{ developer?, user? }` | `gpt-4o-mini` / `gpt-4o-mini` | per-path model tiers |
+| `maxTokens` | `number` | `2000` | token budget per call |
+| `store` | `MemoryCacheStore` | new instance | pass one to share with `prewarm()` or hydrate from disk |
+| `developerTtlMs` | `number` | `3_600_000` | L1 fresh window |
+| `userTtlMs` | `number` | `600_000` | L2 fresh window |
+| `staleMs` | `number` | `86_400_000` | how long a stale entry may still serve as fallback |
+| `rateLimit` | `{ limit, windowMs } \| false` | `{ 10, 60_000 }` | POST only; in-process, swap in a shared store for multi-instance |
+| `onUsage` | `(entry: UsageLogEntry) => void` | — | called after every successful LLM call; callback errors are swallowed |
+| `now` | `() => number` | `Date.now` | injectable clock for tests |
+
+Errors are plain JSON, and every failure mode is distinct:
+
+| Status | `error` | When |
+|---|---|---|
+| 400 | `invalid_prompt` | missing/empty/oversized user prompt |
+| 404 | `not_found` | path is not `/ai-render/:slotId` |
+| 404 | `unknown_slot` | `resolveSlot` returned `null` |
+| 405 | `method_not_allowed` | anything but GET/POST |
+| 429 | `rate_limited` | POST over the per-IP limit |
+| 503 | `ai_unavailable` | LLM failed or output invalid, with no stale cache to serve |
+
+### Bring your own model
+
+`LLMClient` is one method — point it at Anthropic, a local model, or a fixture:
+
+```ts
+const llm = {
+  async complete({ model, system, user, maxTokens }) {
+    return { text: JSON.stringify({ version: 1, slot: "hero", tree: { component: "hero-banner", props: { title: "Hello" } } }) };
+  },
+};
+```
+
+`createOpenAIClient({ apiKey, baseUrl?, fetchImpl? })` covers any OpenAI-compatible endpoint (DeepSeek, vLLM, gateways) with zero SDK dependency and JSON-mode output.
+
+### Module map
+
+| Module | What it is |
+|---|---|
+| `handler.ts` | `createAiRenderHandler` — routing, caching, degradation chain, SSE negotiation |
+| `cache.ts` | `MemoryCacheStore` (+ `dump`/`load`), `prewarm` cache keys, fresh/stale `lookup` |
+| `prewarm.ts` | CI pregeneration over the developer path |
+| `prompt-compiler.ts` | layered prompt: system rules → registry constraints → developer prompt → user prompt (narrowest last) |
+| `llm-client.ts` | `LLMClient` interface, `LLMError`, `withRetry` |
+| `openai-client.ts` | fetch-based OpenAI-compatible adapter |
+| `sanitize.ts` | user prompt filter (type, length, control characters) |
+| `rate-limit.ts` | in-process sliding-window limiter |
+| `invalidate.ts` | `createInvalidationChannel` — SSE invalidation push |
+
+## Development
+
+```bash
+pnpm --filter @ai-slot/proxy test        # all unit tests, no network access needed
+cd packages/proxy && npx vitest run src/handler.test.ts -t "降级"   # one file / one case
+pnpm --filter @ai-slot/proxy typecheck   # run pnpm build first on a clean checkout
+```
+
+Every LLM in the test suite is a fixture or a mock — nothing here calls a real API, so the package is safe to explore and modify with a coding agent. The spec of record is [`docs/superpowers/specs/2026-09-24-ai-native-rendering-sdk-design.md`](../../docs/superpowers/specs/2026-09-24-ai-native-rendering-sdk-design.md).
+
+## The monorepo
+
+| Package | Role |
+|---|---|
+| [`@ai-slot/registry`](../registry/) | protocol + `OutputValidator` — the security boundary, consumed by proxy, runtime, and build tooling |
+| **`@ai-slot/proxy`** | this package — stateless render proxy |
+| [`@ai-slot/runtime`](../runtime/) | zero-dependency `<ai-slot>` element (`stream`, `live`, `editable`) |
+| [`@ai-slot/adapter-dom`](../adapter-dom/) / [`adapter-react`](../adapter-react/) / [`adapter-vue`](../adapter-vue/) | map validated trees onto your real components |
+| [`examples/plain-html`](../../examples/plain-html/) | end-to-end demo: legacy page, editable + streaming + live slots, Playwright e2e |

package/dist/index.d.ts

@@ -0,0 +1,189 @@
+import { Registry } from '@ai-slot/registry';
+
+/** 双层缓存：fresh TTL 内直接返回；超过 TTL 但在 stale 窗口内可作为降级结果返回。 */
+interface CacheEntry<T> {
+    value: T;
+    /** fresh 截止时刻（ms 时间戳） */
+    expiresAt: number;
+    /** stale 截止时刻，之后彻底删除 */
+    staleUntil: number;
+}
+declare class MemoryCacheStore {
+    private map;
+    get<T>(key: string, now: number): CacheEntry<T> | undefined;
+    set<T>(key: string, value: T, ttlMs: number, staleMs: number, now: number): void;
+    /** 序列化为 JSON（绝对毫秒时间戳；CI 与部署时钟需一致）。 */
+    dump(): string;
+    /** 反序列化；剔除调用时已彻底过期或形状非法（缺时间戳）的条目。非法 JSON 抛错（SyntaxError/TypeError）。 */
+    static load(json: string, now: number): MemoryCacheStore;
+}
+interface CacheLookup<T> {
+    value: T;
+    status: "fresh" | "stale";
+}
+declare function lookup<T>(store: MemoryCacheStore, key: string, now: number): CacheLookup<T> | undefined;
+/** djb2 哈希：同步、零依赖，足够做缓存 key（非安全用途）。 */
+declare function hashKey(input: string): string;
+/** 用户提示词规范化：trim + 小写 + 合并空白，提高 L2 缓存命中率。 */
+declare function normalizeUserPrompt(prompt: string): string;
+/** L1 开发者路径 key：hash(slotId + 内容版本 + 提示词版本)。 */
+declare function developerCacheKey(slotId: string, contentVersion: string, promptVersion: string): string;
+/** L2 用户路径 key：hash(slotId + 规范化用户提示词)。 */
+declare function userCacheKey(slotId: string, userPrompt: string): string;
+
+/** LLM 调用的最小抽象：输入分层提示词，输出 JSON 文本。 */
+interface LLMRequest {
+    model: string;
+    system: string;
+    user: string;
+    /** token 预算上限 */
+    maxTokens?: number;
+    /** 超时（ms），默认 8000 */
+    timeoutMs?: number;
+}
+interface LLMResponse {
+    text: string;
+    usage?: {
+        promptTokens?: number;
+        completionTokens?: number;
+    };
+}
+interface LLMClient {
+    complete(req: LLMRequest): Promise<LLMResponse>;
+}
+declare class LLMError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** 失败重试：默认重试 1 次（共 2 次尝试）。 */
+declare function withRetry(client: LLMClient, retries?: number): LLMClient;
+
+interface SlotSource {
+    slotId: string;
+    /** 原始兜底内容摘要 */
+    originalContent: string;
+    developerPrompt?: string;
+    /** 内容版本，进入 L1 缓存 key */
+    contentVersion: string;
+    /** 提示词版本，默认 "1" */
+    promptVersion?: string;
+    /** 数据源解析后的实时数据 */
+    data?: Record<string, unknown>;
+}
+interface ProxyOptions {
+    registry: Registry;
+    llm: LLMClient;
+    resolveSlot: (slotId: string) => SlotSource | null | Promise<SlotSource | null>;
+    /** 双模型档位：开发者预生成可用大模型，用户实时路径默认小模型 */
+    models?: {
+        developer?: string;
+        user?: string;
+    };
+    /** token 预算上限，默认 2000 */
+    maxTokens?: number;
+    store?: MemoryCacheStore;
+    /** L1 缓存 TTL，默认 1 小时 */
+    developerTtlMs?: number;
+    /** L2 缓存 TTL，默认 10 分钟 */
+    userTtlMs?: number;
+    /** stale 窗口，默认 1 天 */
+    staleMs?: number;
+    /** 用户路径限流，默认 10 次/分钟；传 false 关闭。进程内单实例语义，多实例部署需外部存储（见 rate-limit.ts） */
+    rateLimit?: {
+        limit: number;
+        windowMs: number;
+    } | false;
+    /** 用量日志：每次 LLM 调用成功后回调（供计费与调优） */
+    onUsage?: (entry: UsageLogEntry) => void;
+    /** 测试注入用 */
+    now?: () => number;
+}
+/** 用量日志条目（设计文档 §4.2：全部调用记录用量日志）。 */
+interface UsageLogEntry {
+    slotId: string;
+    model: string;
+    reason: "developer-prompt" | "user-prompt";
+    usage?: LLMResponse["usage"];
+    at: number;
+}
+/** 无状态渲染代理：GET 开发者路径（长缓存）/ POST 用户路径（实时 + 限流 + 短 TTL）。 */
+declare function createAiRenderHandler(opts: ProxyOptions): (req: Request) => Promise<Response>;
+
+interface InvalidationChannel {
+    /** GET /ai-invalidate?slot=<slotId> 的 SSE 订阅端点 */
+    handler: (req: Request) => Response;
+    /** 向某槽位的所有订阅者广播失效信号 */
+    invalidate: (slotId: string) => void;
+    /** 当前订阅者数（测试与观测用） */
+    subscriberCount: (slotId: string) => number;
+}
+/**
+ * 失效推送通道（SSE）。协议：订阅后服务端按 slotId 过滤广播
+ * `event: invalidate\ndata: {"slot":"<slotId>"}\n\n`，心跳为 `: ping` 注释行。
+ * 接入方自行决定 invalidate() 的触发时机（数据源 webhook、定时 diff、管理端点等）。
+ */
+declare function createInvalidationChannel(opts?: {
+    heartbeatMs?: number;
+}): InvalidationChannel;
+
+interface OpenAIClientOptions {
+    apiKey: string;
+    /** 默认 https://api.openai.com/v1，可指向任何 OpenAI 兼容端点 */
+    baseUrl?: string;
+    /** 测试注入用 */
+    fetchImpl?: typeof fetch;
+}
+/** 基于 fetch 的 OpenAI 兼容适配器：零 SDK 依赖，JSON mode 结构化输出。 */
+declare function createOpenAIClient(opts: OpenAIClientOptions): LLMClient;
+
+interface PrewarmResult {
+    ok: string[];
+    failed: string[];
+}
+/**
+ * CI 构建时预生成（「AI 静态化」）：复用渲染代理 handler 逐槽位跑开发者路径，
+ * 结果写入 handler 自带的缓存 store；之后 dump() 序列化随产物部署。
+ * 单个槽位失败不中断整体。
+ */
+declare function prewarm(handler: (req: Request) => Promise<Response>, slotIds: string[]): Promise<PrewarmResult>;
+
+interface CompileInput {
+    registry: Registry;
+    slotId: string;
+    /** 槽位的原始兜底内容（摘要） */
+    originalContent: string;
+    developerPrompt?: string;
+    /** 已经过 sanitize 的用户提示词 */
+    userPrompt?: string;
+    /** 数据源解析后的实时数据 */
+    data?: Record<string, unknown>;
+}
+interface CompiledPrompt {
+    system: string;
+    user: string;
+}
+/**
+ * 分层提示词组装。层级：系统提示（框架内置）→ 注册表约束 → 开发者提示词 → 用户提示词，
+ * 越往下权限越窄；用户提示词只能以受限上下文的形式注入。
+ */
+declare function compilePrompt(input: CompileInput): CompiledPrompt;
+
+/** 进程内滑动窗口限流（Edge 单实例语义；多实例部署需换外部存储，接口保持不变）。 */
+declare class RateLimiter {
+    private opts;
+    private hits;
+    constructor(opts: {
+        limit: number;
+        windowMs: number;
+    });
+    check(key: string, now: number): boolean;
+}
+
+/**
+ * 用户提示词提交前过滤：类型、长度、控制字符。
+ * 返回 null 表示非法输入；通过过滤的提示词仍会经 OutputValidator 最终兜底。
+ */
+declare function sanitizeUserPrompt(raw: unknown, maxLength?: number): string | null;
+
+export { type CacheEntry, type CacheLookup, type CompileInput, type CompiledPrompt, type InvalidationChannel, type LLMClient, LLMError, type LLMRequest, type LLMResponse, MemoryCacheStore, type OpenAIClientOptions, type PrewarmResult, type ProxyOptions, RateLimiter, type SlotSource, type UsageLogEntry, compilePrompt, createAiRenderHandler, createInvalidationChannel, createOpenAIClient, developerCacheKey, hashKey, lookup, normalizeUserPrompt, prewarm, sanitizeUserPrompt, userCacheKey, withRetry };

package/dist/index.js

@@ -0,0 +1,419 @@
+// src/cache.ts
+var MemoryCacheStore = class _MemoryCacheStore {
+  map = /* @__PURE__ */ new Map();
+  get(key, now) {
+    const entry = this.map.get(key);
+    if (!entry) return void 0;
+    if (now >= entry.staleUntil) {
+      this.map.delete(key);
+      return void 0;
+    }
+    return entry;
+  }
+  set(key, value, ttlMs, staleMs, now) {
+    this.map.set(key, { value, expiresAt: now + ttlMs, staleUntil: now + ttlMs + staleMs });
+  }
+  /** 序列化为 JSON（绝对毫秒时间戳；CI 与部署时钟需一致）。 */
+  dump() {
+    return JSON.stringify(Object.fromEntries(this.map));
+  }
+  /** 反序列化；剔除调用时已彻底过期或形状非法（缺时间戳）的条目。非法 JSON 抛错（SyntaxError/TypeError）。 */
+  static load(json2, now) {
+    const raw = JSON.parse(json2);
+    const store = new _MemoryCacheStore();
+    for (const [key, entry] of Object.entries(raw)) {
+      if (typeof entry?.staleUntil !== "number" || typeof entry?.expiresAt !== "number") continue;
+      if (now < entry.staleUntil) {
+        store.map.set(key, entry);
+      }
+    }
+    return store;
+  }
+};
+function lookup(store, key, now) {
+  const entry = store.get(key, now);
+  if (!entry) return void 0;
+  return { value: entry.value, status: now < entry.expiresAt ? "fresh" : "stale" };
+}
+function hashKey(input) {
+  let h = 5381;
+  for (let i = 0; i < input.length; i++) {
+    h = (h << 5) + h + input.charCodeAt(i) >>> 0;
+  }
+  return h.toString(36);
+}
+function normalizeUserPrompt(prompt) {
+  return prompt.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function developerCacheKey(slotId, contentVersion, promptVersion) {
+  return `dev:${hashKey(`${slotId}|${contentVersion}|${promptVersion}`)}`;
+}
+function userCacheKey(slotId, userPrompt) {
+  return `usr:${hashKey(`${slotId}|${normalizeUserPrompt(userPrompt)}`)}`;
+}
+
+// src/handler.ts
+import {
+  deriveSkeleton,
+  validateComponentTree
+} from "@ai-slot/registry";
+
+// src/llm-client.ts
+var LLMError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "LLMError";
+  }
+};
+function withRetry(client, retries = 1) {
+  return {
+    async complete(req) {
+      let lastError;
+      for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+          return await client.complete(req);
+        } catch (error) {
+          lastError = error;
+        }
+      }
+      throw lastError;
+    }
+  };
+}
+
+// src/prompt-compiler.ts
+function compilePrompt(input) {
+  const system = [
+    "\u4F60\u662F\u4E00\u4E2A\u9875\u9762\u5185\u5BB9\u589E\u5F3A\u5F15\u64CE\u3002\u4F60\u53EA\u80FD\u8F93\u51FA\u7B26\u5408\u7ED9\u5B9A\u7EC4\u4EF6\u6CE8\u518C\u8868\u7684\u7EC4\u4EF6\u6811 JSON\uFF0C\u7981\u6B62\u8F93\u51FA HTML\u3001CSS \u6216\u4EFB\u4F55\u4EE3\u7801\u3002",
+    "\u6240\u6709\u6587\u672C\u5185\u5BB9\u5FC5\u987B\u662F\u7EAF\u6587\u672C\uFF1B\u7EC4\u4EF6\u540D\u5FC5\u987B\u6765\u81EA\u6CE8\u518C\u8868\uFF1Bprops \u5FC5\u987B\u6EE1\u8DB3 Schema \u7EA6\u675F\u3002",
+    '\u8F93\u51FA\u534F\u8BAE\uFF1A{"version":1,"slot":"<\u69FD\u4F4D\u540D>","tree":{"component":"<\u7EC4\u4EF6\u540D>","props":{...},"children":[...],"slots":{"<\u69FD\u4F4D\u540D>":[...]}}}',
+    "children \u5BF9\u5E94\u7EC4\u4EF6\u58F0\u660E\u7684 default \u69FD\u4F4D\uFF1B\u672A\u58F0\u660E\u69FD\u4F4D\u7684\u7EC4\u4EF6\u4E0D\u5141\u8BB8\u5305\u542B\u5B50\u8282\u70B9\u3002",
+    "\u7EC4\u4EF6\u6CE8\u518C\u8868\uFF08JSON\uFF09\uFF1A",
+    JSON.stringify(serializeRegistry(input.registry), null, 2)
+  ].join("\n");
+  const userParts = [
+    `\u69FD\u4F4D\uFF1A${input.slotId}`,
+    `\u539F\u59CB\u5185\u5BB9\uFF1A
+${input.originalContent}`
+  ];
+  if (input.data && Object.keys(input.data).length > 0) {
+    userParts.push(`\u5B9E\u65F6\u6570\u636E\uFF1A
+${JSON.stringify(input.data)}`);
+  }
+  if (input.developerPrompt) {
+    userParts.push(`\u5F00\u53D1\u8005\u8981\u6C42\uFF1A${input.developerPrompt}`);
+  }
+  if (input.userPrompt) {
+    userParts.push(`\u5728\u4FDD\u6301\u4E0A\u8FF0\u7EC4\u4EF6\u7EA6\u675F\u7684\u524D\u63D0\u4E0B\uFF0C\u6309\u7528\u6237\u8981\u6C42\u8C03\u6574\uFF1A${input.userPrompt}`);
+  }
+  return { system, user: userParts.join("\n\n") };
+}
+function serializeRegistry(registry) {
+  const out = {};
+  for (const [name, def] of Object.entries(registry.components)) {
+    out[name] = { description: def.description, props: def.props, required: def.required, slots: def.slots };
+  }
+  return out;
+}
+
+// src/rate-limit.ts
+var RateLimiter = class {
+  constructor(opts) {
+    this.opts = opts;
+  }
+  opts;
+  hits = /* @__PURE__ */ new Map();
+  check(key, now) {
+    const windowStart = now - this.opts.windowMs;
+    const list = (this.hits.get(key) ?? []).filter((t) => t > windowStart);
+    if (list.length >= this.opts.limit) {
+      this.hits.set(key, list);
+      return false;
+    }
+    list.push(now);
+    this.hits.set(key, list);
+    return true;
+  }
+};
+
+// src/sanitize.ts
+function sanitizeUserPrompt(raw, maxLength = 500) {
+  if (typeof raw !== "string") return null;
+  const cleaned = raw.replace(/[\u0000-\u001F\u007F]/g, " ").replace(/[\u0080-\u009F]/g, "").trim();
+  if (cleaned.length === 0 || cleaned.length > maxLength) return null;
+  return cleaned;
+}
+
+// src/handler.ts
+function json(body, status) {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+function sse(response) {
+  const skeleton = {
+    ...response,
+    tree: deriveSkeleton(response.tree),
+    meta: { ...response.meta, phase: "skeleton" }
+  };
+  const body = `event: skeleton
+data: ${JSON.stringify(skeleton)}
+
+event: tree
+data: ${JSON.stringify(response)}
+
+`;
+  return new Response(body, {
+    status: 200,
+    headers: { "content-type": "text/event-stream; charset=utf-8", "cache-control": "no-cache" }
+  });
+}
+function createAiRenderHandler(opts) {
+  const store = opts.store ?? new MemoryCacheStore();
+  const now = opts.now ?? (() => Date.now());
+  const limiter = opts.rateLimit === false ? null : new RateLimiter(opts.rateLimit ?? { limit: 10, windowMs: 6e4 });
+  const llm = withRetry(opts.llm);
+  return async function handler(req) {
+    const match = new URL(req.url).pathname.match(/\/ai-render\/([\w-]+)\/?$/);
+    if (!match) return json({ error: "not_found" }, 404);
+    const slotId = match[1];
+    const wantsSSE = req.headers.get("accept")?.includes("text/event-stream") ?? false;
+    let userPrompt;
+    if (req.method === "POST") {
+      if (limiter) {
+        const ip = req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ?? "anonymous";
+        if (!limiter.check(ip, now())) return json({ error: "rate_limited" }, 429);
+      }
+      const body = await req.json().catch(() => null);
+      const cleaned = sanitizeUserPrompt(body?.prompt);
+      if (!cleaned) return json({ error: "invalid_prompt" }, 400);
+      userPrompt = cleaned;
+    } else if (req.method !== "GET") {
+      return json({ error: "method_not_allowed" }, 405);
+    }
+    let hit;
+    if (userPrompt !== void 0) {
+      hit = lookup(store, userCacheKey(slotId, userPrompt), now());
+      if (hit?.status === "fresh") return wantsSSE ? sse(hit.value) : json(hit.value, 200);
+    }
+    let slot;
+    try {
+      slot = await opts.resolveSlot(slotId);
+    } catch (error) {
+      console.warn("[ai-render] \u69FD\u4F4D\u89E3\u6790\u5931\u8D25", error);
+      return hit ? wantsSSE ? sse(hit.value) : json(hit.value, 200) : json({ error: "ai_unavailable" }, 503);
+    }
+    if (!slot) return json({ error: "unknown_slot" }, 404);
+    if (userPrompt === void 0) {
+      hit = lookup(
+        store,
+        developerCacheKey(slotId, slot.contentVersion, slot.promptVersion ?? "1"),
+        now()
+      );
+      if (hit?.status === "fresh") return wantsSSE ? sse(hit.value) : json(hit.value, 200);
+    }
+    const isUserPath = userPrompt !== void 0;
+    const key = userPrompt !== void 0 ? userCacheKey(slotId, userPrompt) : developerCacheKey(slotId, slot.contentVersion, slot.promptVersion ?? "1");
+    const ttlMs = isUserPath ? opts.userTtlMs ?? 6e5 : opts.developerTtlMs ?? 36e5;
+    const staleMs = opts.staleMs ?? 864e5;
+    const staleOr503 = () => {
+      if (hit) return wantsSSE ? sse(hit.value) : json(hit.value, 200);
+      return json({ error: "ai_unavailable" }, 503);
+    };
+    try {
+      const compiled = compilePrompt({
+        registry: opts.registry,
+        slotId,
+        originalContent: slot.originalContent,
+        developerPrompt: slot.developerPrompt,
+        userPrompt,
+        data: slot.data
+      });
+      const model = isUserPath ? opts.models?.user ?? "gpt-4o-mini" : opts.models?.developer ?? "gpt-4o-mini";
+      const llmRes = await llm.complete({
+        model,
+        system: compiled.system,
+        user: compiled.user,
+        maxTokens: opts.maxTokens ?? 2e3,
+        timeoutMs: 8e3
+      });
+      try {
+        opts.onUsage?.({
+          slotId,
+          model,
+          reason: isUserPath ? "user-prompt" : "developer-prompt",
+          usage: llmRes.usage,
+          at: now()
+        });
+      } catch (error) {
+        console.warn("[ai-render] \u7528\u91CF\u65E5\u5FD7\u56DE\u8C03\u5931\u8D25\uFF0C\u5DF2\u5FFD\u7565", error);
+      }
+      const parsed = JSON.parse(llmRes.text);
+      const tree = parsed?.tree;
+      const result = validateComponentTree(opts.registry, tree);
+      if (!result.ok) {
+        console.warn("[ai-render] \u8F93\u51FA\u6821\u9A8C\u5931\u8D25\uFF0C\u5DF2\u4E22\u5F03", result.errors, llmRes.text.slice(0, 500));
+        return staleOr503();
+      }
+      const response = {
+        version: 1,
+        slot: slotId,
+        tree,
+        meta: { reason: isUserPath ? "user-prompt" : "developer-prompt" }
+      };
+      store.set(key, response, ttlMs, staleMs, now());
+      return wantsSSE ? sse(response) : json(response, 200);
+    } catch (error) {
+      console.warn("[ai-render] LLM \u8C03\u7528\u5931\u8D25", error);
+      return staleOr503();
+    }
+  };
+}
+
+// src/invalidate.ts
+var encoder = new TextEncoder();
+function createInvalidationChannel(opts = {}) {
+  const heartbeatMs = opts.heartbeatMs ?? 25e3;
+  const subscribers = /* @__PURE__ */ new Map();
+  function subscribe(slotId, controller) {
+    let set = subscribers.get(slotId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      subscribers.set(slotId, set);
+    }
+    set.add(controller);
+  }
+  function unsubscribe(slotId, controller) {
+    subscribers.get(slotId)?.delete(controller);
+  }
+  return {
+    handler(req) {
+      const slotId = new URL(req.url).searchParams.get("slot");
+      if (!slotId) {
+        return new Response(JSON.stringify({ error: "missing_slot" }), {
+          status: 400,
+          headers: { "content-type": "application/json; charset=utf-8" }
+        });
+      }
+      let controller;
+      let heartbeat;
+      const body = new ReadableStream({
+        start(c) {
+          controller = c;
+          subscribe(slotId, c);
+        },
+        cancel() {
+          unsubscribe(slotId, controller);
+          if (heartbeat !== void 0) clearInterval(heartbeat);
+        }
+      });
+      heartbeat = setInterval(() => {
+        try {
+          controller.enqueue(encoder.encode(": ping\n\n"));
+        } catch {
+          if (heartbeat !== void 0) clearInterval(heartbeat);
+        }
+      }, heartbeatMs);
+      return new Response(body, {
+        status: 200,
+        headers: {
+          "content-type": "text/event-stream; charset=utf-8",
+          "cache-control": "no-cache",
+          connection: "keep-alive"
+        }
+      });
+    },
+    invalidate(slotId) {
+      const frame = encoder.encode(`event: invalidate
+data: ${JSON.stringify({ slot: slotId })}
+
+`);
+      for (const controller of subscribers.get(slotId) ?? []) {
+        try {
+          controller.enqueue(frame);
+        } catch {
+          unsubscribe(slotId, controller);
+        }
+      }
+    },
+    subscriberCount(slotId) {
+      return subscribers.get(slotId)?.size ?? 0;
+    }
+  };
+}
+
+// src/openai-client.ts
+function createOpenAIClient(opts) {
+  const baseUrl = opts.baseUrl ?? "https://api.openai.com/v1";
+  const doFetch = opts.fetchImpl ?? fetch;
+  return {
+    async complete(req) {
+      const timeoutMs = req.timeoutMs ?? 8e3;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const res = await doFetch(`${baseUrl}/chat/completions`, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${opts.apiKey}`,
+            "content-type": "application/json"
+          },
+          body: JSON.stringify({
+            model: req.model,
+            messages: [
+              { role: "system", content: req.system },
+              { role: "user", content: req.user }
+            ],
+            response_format: { type: "json_object" },
+            ...req.maxTokens !== void 0 ? { max_tokens: req.maxTokens } : {}
+          }),
+          signal: controller.signal
+        });
+        if (!res.ok) throw new LLMError(`LLM HTTP ${res.status}`);
+        const data = await res.json();
+        const text = data.choices?.[0]?.message?.content;
+        if (typeof text !== "string") throw new LLMError("LLM \u54CD\u5E94\u7F3A\u5C11\u5185\u5BB9");
+        return {
+          text,
+          usage: { promptTokens: data.usage?.prompt_tokens, completionTokens: data.usage?.completion_tokens }
+        };
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+  };
+}
+
+// src/prewarm.ts
+async function prewarm(handler, slotIds) {
+  const ok = [];
+  const failed = [];
+  for (const slotId of slotIds) {
+    try {
+      const res = await handler(new Request(`https://prewarm.local/ai-render/${slotId}`));
+      if (res.ok) ok.push(slotId);
+      else failed.push(slotId);
+    } catch {
+      failed.push(slotId);
+    }
+  }
+  return { ok, failed };
+}
+export {
+  LLMError,
+  MemoryCacheStore,
+  RateLimiter,
+  compilePrompt,
+  createAiRenderHandler,
+  createInvalidationChannel,
+  createOpenAIClient,
+  developerCacheKey,
+  hashKey,
+  lookup,
+  normalizeUserPrompt,
+  prewarm,
+  sanitizeUserPrompt,
+  userCacheKey,
+  withRetry
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@ai-slot/proxy",
+  "version": "0.1.0",
+  "license": "MIT",
+  "description": "Stateless AI render proxy: prompt compiler, LLM client with retry, output validator, and two-tier cache.",
+  "keywords": [
+    "ai",
+    "llm",
+    "proxy",
+    "edge",
+    "serverless",
+    "cache",
+    "rate-limit"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iannil/ai-slot-component.git",
+    "directory": "packages/proxy"
+  },
+  "bugs": "https://github.com/iannil/ai-slot-component/issues",
+  "homepage": "https://github.com/iannil/ai-slot-component/tree/master/packages/proxy#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@ai-slot/registry": "0.1.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}