render-json-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Render JSON UI

渲染JSON UI

Turn unknown JSON into a readable presentation without assuming domain knowledge or a browser surface. Inspect shape first, emit structural evidence, and let the LLM derive a declarative UI spec from that evidence.

将未知结构的JSON转换为可读的呈现形式，无需依赖领域知识或浏览器环境。先检查数据结构，输出结构特征，再让大语言模型基于这些特征生成声明式UI规范。

Quick Start

快速开始

Identify the input.
If needed, run the shell command that generates or refreshes the JSON artifact.
Run
```
scripts/profile_json.py <path>
```
to classify the payload and extract structural evidence.
Build a declarative UI spec using
```
references/ui-schema.md
```
.
Render that spec natively in the harness, or through the terminal reference renderer.

确定输入内容。
如有需要，运行生成或刷新JSON制品的Shell命令。
执行
```
scripts/profile_json.py <path>
```
对负载进行分类并提取结构特征。
参考
```
references/ui-schema.md
```
构建声明式UI规范。
在harness中原生渲染该规范，或通过终端参考渲染器进行渲染。

Workflow

工作流

1. Locate the JSON artifact

1. 定位JSON制品

Prefer explicit file paths. If the user gives a shell command instead, run it first and then locate the resulting JSON file.

If multiple JSON files are plausible candidates, prefer the file that best matches:

the user’s wording
recent modification time
recognizable output names such as
```
*_data.json
```
,
```
results.json
```
,
```
report.json
```

优先使用明确的文件路径。如果用户提供的是Shell命令，先执行该命令，再定位生成的JSON文件。

如果有多个可能的JSON文件候选，优先选择以下匹配度最高的文件：

与用户描述匹配
最近修改的
易识别的输出名称，如
```
*_data.json
```
、
```
results.json
```
、
```
report.json
```

2. Profile before rendering

2. 渲染前先分析结构

Run:

bash

python3 <skill-dir>/scripts/profile_json.py path/to/file.json

Use the profile to answer:

Is this an array of records, a record map, metadata plus row arrays, a nested document, or a scalar?
How many rows or entities exist?
Which fields look numeric, date-like, nested, or overly verbose?
Which branches are sections, and which arrays form repeated child records?

Treat the profiler output as factual evidence, not as a UI recommendation.

执行：

bash

python3 <skill-dir>/scripts/profile_json.py path/to/file.json

利用分析结果回答以下问题：

这是记录数组、记录映射、元数据加行数组、嵌套文档还是标量？
存在多少行或实体？
哪些字段看起来是数值型、类日期型、嵌套型或过于冗长？
哪些分支是章节，哪些数组构成重复子记录？

将分析器输出视为事实依据，而非UI建议。

3. Choose the surface

3. 选择渲染载体

Use this fixed order:

Harness-native generative UI via declarative spec
Terminal-native reference renderer
Inline Markdown only as a fallback

Read

references/surface-selection.md

before selecting the output path.

遵循以下固定顺序：

通过声明式规范实现的Harness原生生成式UI
终端原生参考渲染器
仅在万不得已时使用内嵌Markdown

选择输出方式前，请阅读

references/surface-selection.md

。

4. Render conservatively

4. 保守渲染

Start with:

one-sentence dataset description
row or entity count
the most useful dimensions and metrics
a compact primary section or table

Then add detail sections only if they improve usability.

Do not dump raw JSON unless the shape is too irregular to summarize safely.

从以下内容开始：

一句话数据集描述
行或实体数量
最有用的维度和指标
紧凑的主章节或表格

仅当添加细节章节能提升可用性时，再进行补充。

除非数据结构过于不规则而无法安全总结，否则不要直接输出原始JSON。

Rendering Rules

渲染规则

Arrays of objects

对象数组

Render:

summary metrics
a compact table with the most informative columns
optional ranked slices for notable numeric fields

渲染内容包括：

汇总指标
包含最具信息性列的紧凑表格
针对重要数值字段的可选排名切片

Metadata plus data payloads

元数据加数据负载

Resolve row arrays into labeled columns before presenting them. If the payload contains:

```
metadata.<section>
```
as column names
```
data.<entity>.<section>
```
as row arrays

then use the profiler's

detected_sections

to build sections such as

data.api

data.xbrl

在呈现前，将行数组解析为带标签的列。如果负载包含：

```
metadata.<section>
```
作为列名
```
data.<entity>.<section>
```
作为行数组

则使用分析器的

detected_sections

构建如

data.api

或

data.xbrl

的章节。

Record maps

记录映射

Promote the map key into an explicit

entity_key

column before rendering.

在渲染前，将映射键提升为显式的

entity_key

列。

Nested objects

嵌套对象

Prefer sectioned summaries first. Show the most informative branches and avoid flattening deeply nested structures into unreadable tables.

优先选择分章节的汇总展示。显示最具信息性的分支，避免将深度嵌套结构扁平化为难以阅读的表格。

Repeated child records

重复子记录

When aligned arrays describe repeated entities, convert them into child rows or child tables. Do not leave them as opaque arrays inside a parent record when the alignment is strong.

当对齐数组描述重复实体时，将其转换为子行或子表格。当对齐关系明确时，不要将它们作为父记录中的不透明数组保留。

Large or noisy fields

大型或冗余字段

Truncate long strings in overview views. Summarize arrays and nested objects by size or type unless they qualify as repeated child records.

在概览视图中截断长字符串。除非它们属于重复子记录，否则按大小或类型对数组和嵌套对象进行汇总。

Shell Guidance

Shell命令处理指南

When the user gives a shell command instead of a path:

run the command
locate the JSON artifact it generated
profile the artifact
derive a declarative UI spec
render the result using the native harness or the terminal renderer

If the command produces multiple JSON files, summarize the candidates and pick the best match using recency and filename relevance.

当用户提供的是Shell命令而非文件路径：

执行该命令
定位其生成的JSON制品
分析该制品的结构
生成声明式UI规范
使用Harness原生渲染器或终端渲染器渲染结果

如果命令生成多个JSON文件，汇总候选文件并根据修改时间和文件名相关性选择最佳匹配。

Resources

资源

Use
```
scripts/profile_json.py
```
for deterministic shape inspection.
Read
```
references/ui-schema.md
```
for the declarative UI contract.
Read
```
references/surface-selection.md
```
for the exact rendering order and environment heuristics.
Read
```
references/presentation-patterns.md
```
for layout patterns by JSON shape.

使用
```
scripts/profile_json.py
```
进行确定性结构检查。
阅读
```
references/ui-schema.md
```
了解声明式UI契约。
阅读
```
references/surface-selection.md
```
了解确切的渲染顺序和环境判定规则。
阅读
```
references/presentation-patterns.md
```
了解基于JSON结构的布局模式。