# jsonkb

**Repository Path**: ArlenBoy/jsonkb

## Basic Information

- **Project Name**: jsonkb
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-09
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# jsonkb — AI 即刻渲染引擎

> 让 LLM 输出的 JSON 在用户阅读文字的同时，一行一行变成真实可交互的界面。

jsonkb 是一套 **UI 中间语言（UI DSL）+ 增量渲染运行时**：LLM 输出 NDJSON 节点流（一行一个 op），引擎逐行上屏，用户 1 秒内就能看到能点、能填、能查的真实页面——不是静态图片。流结束后可导出完整 PageDoc JSON 保存，重新加载渲染结果一致。

## 特性

- **即刻渲染** — NDJSON op 流逐行应用，token 边到界面边出；括号错只坏一行，不影响已上屏内容
- **双格式** — 传输态 NDJSON ⇄ 持久态 PageDoc JSON，双向无损转换
- **框架无关** — 引擎零 DOM / 零框架依赖；`@jsonkb/adapter-dom` 是参考实现，Vue/React 适配器可按同一注册表协议接入
- **安全红线** — 组件白名单降级不崩页、表达式沙箱禁 eval 防原型链穿透、action URL 白名单、style 白名单键
- **19 个精简组件** — 每个组件 props ≤ 5 个，把 LLM 生成准确率从 60% 提到 90%+
- **多轮增量修改** — update op 按 id 做局部 patch，改标题不用重新生成整页

## 包结构

```
packages/
├── schema/        # 类型 + 19 组件元数据 + 永不 throw 的校验器 + JSON Schema 生成
├── parser/        # NDJSON 流式解析器 + PageDoc ⇄ op 流双向转换
├── engine/        # IR 树 + 表达式沙箱 + ActionRunner（url 白名单）
├── registry/      # 框架无关的组件注册表
├── adapter-dom/   # DOM 适配器（19 组件实现 + 默认样式表）
└── llm/           # 系统提示词自动生成 + OpenAI 兼容流式客户端
playground/        # 本地调试台：整体渲染 / 模拟流式 / LLM 对话生成
```

依赖方向严格单向：`schema ← parser ← engine ← registry ← adapter`。

## 快速上手

### 1. 渲染一个页面（3 行代码）

```ts
import { mount } from "@jsonkb/adapter-dom";
import "@jsonkb/adapter-dom/styles.css"; // 默认中后台观感，一行引入

const app = mount(document.querySelector("#app")!);
app.load(pageDocJson); // 完整 PageDoc JSON 一次性渲染
```

### 2. 流式渲染（LLM 输出边到边上屏）

```ts
import { mount } from "@jsonkb/adapter-dom";

const app = mount(document.querySelector("#app")!);

// 每拿到一行 LLM 输出就喂进来，界面即时增长
for await (const op of iterateNdjson(llmStream)) {
  app.applyOp(op);
}
```

### 3. 接真实 LLM（OpenAI 兼容服务：DeepSeek / vLLM / Ollama…）

```ts
import { mount, fetchAdapter } from "@jsonkb/adapter-dom";
import { ActionRunner } from "@jsonkb/engine";
import { buildSystemPrompt, chatStream } from "@jsonkb/llm";

const app = mount(el, { runner: new ActionRunner(fetchAdapter) });
const system = buildSystemPrompt({ extraRules: ["界面文案用简体中文"] });

await chatStream(
  { baseUrl: "https://api.deepseek.com/v1", apiKey: "sk-…", model: "deepseek-chat", system, user: "做一个订单查询页" },
  (op) => app.applyOp(op), // 每个 op 就绪即上屏
);
```

提示词由组件元数据自动生成——组件集升级时，喂给 LLM 的白名单自动跟随，不会漂移。

### 4. 交互与数据

```jsonc
// PageDoc 片段：按钮触发 action，响应写入 state，表格自动更新
{
  "state": { "orders": [] },
  "actions": {
    "search": { "kind": "request", "method": "POST", "url": "/admin-api/erp/order/page", "assignTo": "orders" }
  },
  "children": [
    { "type": "Button", "id": "go", "props": { "text": "查询", "onClick": "search" } },
    { "type": "Table", "id": "t", "props": { "dataRef": "orders", "columns": [{ "key": "no", "title": "单号" }] } }
  ]
}
```

url 仅允许 `/admin-api/`、`/app-api/` 前缀（构造 ActionRunner 时可配置）。

## 命令

```bash
npm install          # 安装
npm run dev          # 启动 playground（默认 5180）
npm test             # vitest 全量测试
npm run typecheck    # TS 检查
npm run emit:schema  # 导出 JSON Schema（喂给 LLM constrained decoding）
```

## 文档

- [docs/立项方案.md](docs/立项方案.md) — 技术决策、Schema v1 规范、NDJSON 设计
- [docs/设计文档.md](docs/设计文档.md) — 函数级设计（签名/行为/错误/边界/测试映射）
- [docs/PRD.md](docs/PRD.md) — 功能需求、验收标准、代码示例、安全红线

## License

Private / 内部项目