hyperscribe

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Hyperscribe

Hyperscribe turns an A2UI-style JSON envelope into a single, self-contained HTML file. You — the model — emit semantic data only, never HTML, CSS, or styling decisions. A zero-dependency Node renderer handles presentation. The file opens offline in any browser with no build step.

Use this skill when a visual explanation would be clearer than terminal text. Prefer Hyperscribe over hand-written HTML, Mermaid fences in chat, or ASCII tables whenever the reader will benefit from structure or interactivity.

Hyperscribe可将A2UI格式的JSON包转换为单个独立的HTML文件。作为模型，你只需生成语义数据，无需编写HTML、CSS或做样式决策。一个零依赖的Node渲染器会负责处理展示部分。生成的文件可在任何浏览器中离线打开，无需构建步骤。

当可视化解释比终端文本更清晰时，使用此技能。只要读者能从结构化内容或交互性中获益，就优先使用Hyperscribe，而非手写HTML、聊天中的Mermaid代码块或ASCII表格。

When to use

使用场景

Use Hyperscribe when any of these hold:

The user asks for a diagram, flowchart, architecture, process view, slide deck, comparison, or visual explainer.
You are about to render a markdown table with 4+ rows OR 3+ columns in a chat reply — render a
```
DataTable
```
instead.
You are about to render ASCII art of a system, flow, or state machine — use
```
Mermaid
```
or
```
ArchitectureGrid
```
instead.
The user asks for a "slide deck", "presentation", "recap", or "summary with sections".
Reviewing a PR / diff and a before-after view plus impacted-module map would help — use
```
/hyperscribe:diff
```
.
The user wants to share a result with others — render then call
```
/hyperscribe:share
```
.

Do not use Hyperscribe when:

The answer is one or two sentences.
The user explicitly asks to stay in the terminal.
The task is pure code editing with no explanation artifact needed.

在以下任意场景中使用Hyperscribe：

用户要求制作图表、流程图、架构图、流程视图、幻灯片、对比内容或可视化讲解材料。
你准备在聊天回复中渲染4行及以上或3列及以上的Markdown表格——改用
```
DataTable
```
组件。
你准备渲染表示系统、流程或状态机的ASCII图形——改用
```
Mermaid
```
或
```
ArchitectureGrid
```
组件。
用户要求制作“幻灯片”“演示文稿”“回顾内容”或“带章节的摘要”。
评审PR/代码差异时，前后对比视图及受影响模块图会有所帮助——使用
```
/hyperscribe:diff
```
命令。
用户想要与他人分享结果——生成内容后调用
```
/hyperscribe:share
```
命令。

请勿在以下场景中使用Hyperscribe：

答案仅为一两句话。
用户明确要求保留在终端中展示。
任务为纯代码编辑，无需解释性内容。

Step 0 — resolve the user's theme preference (always run first)

步骤0 — 确定用户的主题偏好（必须首先执行）

Before building any envelope, resolve the user's theme + mode. If no preference file exists yet, prompt once, save, then proceed. This runs on every invocation of the main skill and its variants.

bash

undefined

构建任何JSON包之前，先确定用户的主题和模式。如果偏好文件尚未存在，先提示用户一次，保存设置后再继续。每次调用主技能及其变体时都需执行此步骤。

bash

undefined

1. Resolve preference path: project-local first, then global.

1. 解析偏好文件路径：优先项目本地，其次全局。

PREF="" for p in ./.hyperscribe/preference.md ~/.hyperscribe/preference.md; do [ -f "$p" ] && { PREF="$p"; break; } done

2. First run — prompt and save defaults to ~/.hyperscribe/preference.md

2. 首次运行 — 提示用户并将默认设置保存到 ~/.hyperscribe/preference.md

if [ -z "$PREF" ]; then

Claude Code: ask via AskUserQuestion (theme 4-choice, mode 3-choice).

Other agents: print the prompt below and wait for a single-line answer.

cat <<'PROMPT' Hyperscribe first-run setup. Pick a theme and mode.

Themes: 1) studio (Airtable — clean enterprise canvas + Airtable Blue) 2) midnight (Cal.com — grayscale monochrome + Cal Sans display) 3) void (Bugatti — architectural black + 3-color discipline) 4) gallery (Apple — cinematic binary surfaces + SF Pro)

Modes: light / dark / auto

Reply with "<theme> <mode>" (e.g., "studio light"), a single theme name (mode=light), or "skip" to use studio + light. PROMPT

Parse the user's answer into $THEME and $MODE.

If unparseable or empty, fall back to defaults silently.

THEME="studio" MODE="light"

(Agents with AskUserQuestion populate $THEME and $MODE from the structured answer.)

mkdir -p /.hyperscribe PREF=/.hyperscribe/preference.md cat > "$PREF" <<EOF

theme: $THEME mode: $MODE created_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)

if [ -z "$PREF" ]; then

Claude Code：通过AskUserQuestion询问（主题4选1，模式3选1）。

其他Agent：打印下方提示并等待用户单行回复。

cat <<'PROMPT' Hyperscribe首次运行设置。请选择主题和模式。

主题： 1) studio (Airtable风格 — 简洁的企业画布 + Airtable蓝色) 2) midnight (Cal.com风格 — 灰度单色 + Cal Sans字体) 3) void (Bugatti风格 — 建筑黑 + 三色体系) 4) gallery (Apple风格 — 电影级二元界面 + SF Pro字体)

模式： light / dark / auto

请回复 "<主题> <模式>"（例如："studio light"），或仅回复主题名称（模式默认light），或回复"skip"使用默认的studio + light。 PROMPT

将用户的回答解析为 $THEME 和 $MODE。

若无法解析或为空，静默回退到默认值。

THEME="studio" MODE="light"

支持AskUserQuestion的Agent会从结构化回答中填充$THEME和$MODE。

mkdir -p /.hyperscribe PREF=/.hyperscribe/preference.md cat > "$PREF" <<EOF

theme: $THEME mode: $MODE created_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)

Hyperscribe preferences

Hyperscribe偏好设置

Edit the values above to change your defaults. Delete this file to re-run the first-run setup on the next hyperscribe invocation.

修改上方的值即可更改默认设置。删除此文件可在下次调用Hyperscribe时重新运行首次设置。

3. Read preference into env vars (every run)

3. 将偏好设置读取到环境变量（每次运行都执行）

THEME=$(awk -F': *' '/^theme:/{print $2; exit}' "$PREF") MODE=$(awk -F': *' '/^mode:/{print $2; exit}' "$PREF") [ -z "$THEME" ] && THEME=studio [ -z "$MODE" ] && MODE=light


When invoking the renderer in later steps, always pass `--theme "$THEME"` and — when `$MODE` is `light` or `dark` — `--mode "$MODE"`. When `$MODE` is `auto`, omit `--mode` so the page follows `prefers-color-scheme` and localStorage at load time.

THEME=$(awk -F': *' '/^theme:/{print $2; exit}' "$PREF") MODE=$(awk -F': *' '/^mode:/{print $2; exit}' "$PREF") [ -z "$THEME" ] && THEME=studio [ -z "$MODE" ] && MODE=light


在后续步骤调用渲染器时，始终传递`--theme "$THEME"`参数，当`$MODE`为`light`或`dark`时，还需传递`--mode "$MODE"`参数。当`$MODE`为`auto`时，省略`--mode`参数，页面会在加载时遵循`prefers-color-scheme`和localStorage设置。

How to use

使用方法

Understand intent. Classify the request: (a) documentation page, (b) comparison/table, (c) slide deck, (d) diff review, (e) metrics/status page. The classification picks the root component and commands.
Pick components. Consult
```
references/catalog.md
```
for exact prop schemas and choose the smallest set that covers the content. Compose, don't reinvent — e.g. "overview + 3 modules + risks" =
```
Page
```
>
```
Section
```
>
```
ArchitectureGrid
```
+
```
Callout
```
.

Build the envelope. Emit the A2UI JSON envelope (shape below). Every component node is

{ "component": "hyperscribe/X", "props": {...}, "children": [...] }

parts[0]

must be

hyperscribe/Page

(or

hyperscribe/SlideDeck

in slides mode).

Call the CLI. Pipe the JSON into the wrapper via Bash:

bash

HS=$(for p in \
  ./.claude/skills/hyperscribe ~/.claude/skills/hyperscribe \
  ./.codex/skills/hyperscribe ~/.codex/skills/hyperscribe \
  ./.cursor/skills/hyperscribe ~/.cursor/skills/hyperscribe \
  ./.opencode/skills/hyperscribe ~/.opencode/skills/hyperscribe \
  ~/.claude/plugins/cache/hyperscribe-marketplace/*/plugins/hyperscribe \
  ./plugins/hyperscribe
do [ -x "$p/scripts/hyperscribe" ] && { echo "$p/scripts/hyperscribe"; break; }; done)

MODE_FLAG=""
[ "$MODE" = "light" ] && MODE_FLAG="--mode light"
[ "$MODE" = "dark" ]  && MODE_FLAG="--mode dark"

mkdir -p ~/.hyperscribe/out
echo '<json>' | "$HS" --theme "$THEME" $MODE_FLAG --out ~/.hyperscribe/out/<slug>.html

Omit

--out

to let the CLI write

~/.hyperscribe/out/<slug-from-title>-<timestamp>.html

and print the path.

Open it for the user. On macOS:
```
open <path>
```
. On Linux:
```
xdg-open <path>
```
.
Report the path. Reply with the absolute path and a one-line summary of what's inside. Don't dump the JSON back to the user.

理解意图：对请求进行分类：(a) 文档页面，(b) 对比/表格，(c) 幻灯片，(d) 差异评审，(e) 指标/状态页面。分类结果将决定根组件和使用的命令。
选择组件：参考
```
references/catalog.md
```
获取确切的属性 schema，选择能覆盖内容的最小组件集合。组合使用，而非重复造轮子——例如“概览 + 3个模块 + 风险提示”可组合为
```
Page
```
>
```
Section
```
>
```
ArchitectureGrid
```
+
```
Callout
```
。
构建JSON包：生成A2UI格式的JSON包（格式如下）。每个组件节点的格式为
```
{ "component": "hyperscribe/X", "props": {...}, "children": [...] }
```
。
```
parts[0]
```
必须是
```
hyperscribe/Page
```
（幻灯片模式下为
```
hyperscribe/SlideDeck
```
）。

调用CLI：通过Bash将JSON传入包装器：

bash

HS=$(for p in \
  ./.claude/skills/hyperscribe ~/.claude/skills/hyperscribe \
  ./.codex/skills/hyperscribe ~/.codex/skills/hyperscribe \
  ./.cursor/skills/hyperscribe ~/.cursor/skills/hyperscribe \
  ./.opencode/skills/hyperscribe ~/.opencode/skills/hyperscribe \
  ~/.claude/plugins/cache/hyperscribe-marketplace/*/plugins/hyperscribe \
  ./plugins/hyperscribe
do [ -x "$p/scripts/hyperscribe" ] && { echo "$p/scripts/hyperscribe"; break; }; done)

MODE_FLAG=""
[ "$MODE" = "light" ] && MODE_FLAG="--mode light"
[ "$MODE" = "dark" ]  && MODE_FLAG="--mode dark"

mkdir -p ~/.hyperscribe/out
echo '<json>' | "$HS" --theme "$THEME" $MODE_FLAG --out ~/.hyperscribe/out/<slug>.html

省略

--out

参数可让CLI自动生成

~/.hyperscribe/out/<slug-from-title>-<timestamp>.html

文件并打印路径。

为用户打开文件：在macOS上执行：
```
open <path>
```
；在Linux上执行：
```
xdg-open <path>
```
。
报告文件路径：回复用户文件的绝对路径，并简要说明内容。不要将JSON内容返回给用户。

Visualization planning

可视化规划

Before choosing components, make one fast pass over the content and decide what kind of visual this should be.

在选择组件之前，先快速梳理内容，确定可视化类型。

1. Classify the content

1. 内容分类

Topology — systems, modules, services, ownership boundaries, dependencies.
Flow — pipelines, request lifecycles, state changes, ordered handoffs.
Comparison — options, before/after, trade-offs, audits, matrices.
Evidence — metrics, tables, file inventories, code excerpts.
Narrative — recap, walkthrough, phased explanation, summary for humans.

Most useful pages mix 2-3 of these, but one should dominate.

拓扑结构——系统、模块、服务、所有权边界、依赖关系。
流程——流水线、请求生命周期、状态变化、有序交接。
对比——选项、前后对比、权衡、审计、矩阵。
证据——指标、表格、文件清单、代码片段。
叙事——回顾、演练、分阶段讲解、面向用户的摘要。

大多数实用页面会混合2-3种类型，但应有一种主导类型。

2. Pick the dominant visual surface first

2. 首先选择主导可视化组件

Use
```
ArchitectureGrid
```
when card content matters more than exact edge routing.
Use
```
Mermaid
```
as the compatibility fallback for diagram types the native catalog does not cover.
Use
```
Sequence
```
for actor-message timelines and request/response traces.
Use
```
FlowChart
```
for simple pipelines with ranked stages and explicit decisions.
Use
```
Swimlane
```
when the same process must be grouped by role, team, service, or lane.
Use
```
Quadrant
```
for 2x2 prioritization, risk, or positioning matrices.
Use
```
Comparison
```
or
```
DataTable
```
when the user needs side-by-side evaluation rather than a diagram.
Use
```
Chart
```
only when the numbers themselves carry the point; do not chart tiny or mostly categorical data just to make the page feel visual.
Use
```
StepList
```
when sequence matters but a diagram would add noise.

当卡片内容比精确的连线更重要时，使用
```
ArchitectureGrid
```
。
当原生组件库不支持某些图表类型时，使用
```
Mermaid
```
作为兼容性备选。
对于参与者-消息时间线和请求/响应追踪，使用
```
Sequence
```
。
对于带有排序阶段和明确决策的简单流水线，使用
```
FlowChart
```
。
当同一流程需按角色、团队、服务或分组展示时，使用
```
Swimlane
```
。
对于2x2优先级、风险或定位矩阵，使用
```
Quadrant
```
。
当用户需要并排评估而非图表时，使用
```
Comparison
```
或
```
DataTable
```
。
仅当数字本身是核心信息时使用
```
Chart
```
；不要为了让页面看起来更可视化而对少量或主要为分类的数据制作图表。
当顺序很重要但图表会增加噪音时，使用
```
StepList
```
。

2.1 Resolve close calls

2.1 处理模糊场景

If deciding between	Prefer this	When
`Sequence` vs `Swimlane`	`Sequence`	Actors exchange messages over time.
`Sequence` vs `Swimlane`	`Swimlane`	Work moves across lanes and ownership is the point.
`FlowChart` vs `Swimlane`	`FlowChart`	The stages are ordered and lane ownership is secondary.
`ArchitectureGrid` vs `FlowChart`	`ArchitectureGrid`	The user needs module/service shape, responsibilities, or boundaries.
`ArchitectureGrid` vs `FlowChart`	`FlowChart`	The user needs a pipeline, decision path, or lifecycle.
`Comparison` vs `Quadrant`	`Comparison`	Options need bullets, trade-offs, or verdicts.
`Comparison` vs `Quadrant`	`Quadrant`	Positioning on two axes is the main message.
`DataTable` vs `Chart`	`DataTable`	Exact values, labels, or rows matter.
`DataTable` vs `Chart`	`Chart`	Shape, trend, or magnitude is the main point.
`CodeBlock` vs `AnnotatedCode`	`AnnotatedCode`	Specific lines need explanation.
`CodeBlock` vs `CodeDiff`	`CodeDiff`	The change itself is the point.

需在两者间选择	优先选择	适用场景
`Sequence` vs `Swimlane`	`Sequence`	参与者随时间交换消息。
`Sequence` vs `Swimlane`	`Swimlane`	工作跨分组流转，且所有权是核心信息。
`FlowChart` vs `Swimlane`	`FlowChart`	阶段有序，分组所有权为次要信息。
`ArchitectureGrid` vs `FlowChart`	`ArchitectureGrid`	用户需要模块/服务的形态、职责或边界。
`ArchitectureGrid` vs `FlowChart`	`FlowChart`	用户需要流水线、决策路径或生命周期。
`Comparison` vs `Quadrant`	`Comparison`	选项需要要点、权衡或结论。
`Comparison` vs `Quadrant`	`Quadrant`	在两个轴上的定位是核心信息。
`DataTable` vs `Chart`	`DataTable`	精确值、标签或行很重要。
`DataTable` vs `Chart`	`Chart`	形态、趋势或量级是核心信息。
`CodeBlock` vs `AnnotatedCode`	`AnnotatedCode`	特定行需要解释。
`CodeBlock` vs `CodeDiff`	`CodeDiff`	变更本身是核心信息。

3. Compose around that surface

3. 围绕主导组件组合内容

Prefer these page recipes:

Architecture explainer:

Page

Section

overview with

Prose

Callout

-> supporting

ArchitectureGrid

FlowChart

Swimlane

FileTree

, or

FileCard

Process walkthrough:
```
Page
```
->
```
Section
```
summary ->
```
Sequence
```
or
```
FlowChart
```
->
```
StepList
```
->
```
Callout
```
for failure modes or decisions
Comparison / decision memo:
```
Page
```
->
```
Section
```
framing ->
```
Comparison
```
or
```
DataTable
```
->
```
Callout
```
recommendation -> optional
```
Chart
```
Code / diff explainer:
```
Page
```
-> architecture or flow context ->
```
CodeDiff
```
/
```
AnnotatedCode
```
/
```
CodeBlock
```
->
```
Callout
```
risks ->
```
StepList
```
next actions
Repo / system recap:
```
Page
```
-> short
```
Prose
```
summary -> one dominant diagram -> one evidence block (
```
FileTree
```
,
```
FileCard
```
,
```
DataTable
```
, or
```
Comparison
```
) For repo explainers, the first content section should usually be diagram-led, anchored by
```
ArchitectureGrid
```
,
```
FlowChart
```
,
```
Swimlane
```
, or
```
Sequence
```
. Use
```
FileTree
```
,
```
FileCard
```
, or
```
AnnotatedCode
```
as evidence surfaces instead of long explanatory prose.

推荐以下页面组合方案：

架构讲解：

Page

Section

概览（搭配

Prose

或

Callout

） -> 辅助组件

ArchitectureGrid

、

FlowChart

、

Swimlane

、

FileTree

或

FileCard

流程演练：
```
Page
```
->
```
Section
```
摘要 ->
```
Sequence
```
或
```
FlowChart
```
->
```
StepList
```
->
```
Callout
```
（用于说明失败模式或决策点）
对比/决策备忘录：
```
Page
```
->
```
Section
```
框架 ->
```
Comparison
```
或
```
DataTable
```
->
```
Callout
```
推荐 -> 可选
```
Chart
```
代码/差异讲解：
```
Page
```
-> 架构或流程上下文 ->
```
CodeDiff
```
/
```
AnnotatedCode
```
/
```
CodeBlock
```
->
```
Callout
```
风险提示 ->
```
StepList
```
下一步行动
仓库/系统回顾：
```
Page
```
-> 简短
```
Prose
```
摘要 -> 一个主导图表 -> 一个证据块（
```
FileTree
```
、
```
FileCard
```
、
```
DataTable
```
或
```
Comparison
```
）对于仓库讲解，第一个内容部分通常应以图表为主，以
```
ArchitectureGrid
```
、
```
FlowChart
```
、
```
Swimlane
```
或
```
Sequence
```
为核心。使用
```
FileTree
```
、
```
FileCard
```
或
```
AnnotatedCode
```
作为证据展示组件，而非冗长的解释性文本。

4. Scale information density deliberately

4. 合理控制信息密度

If the page has one key idea, use one dominant visual and keep supporting content sparse.
If the page has multiple sections, each section should have one job: overview, topology, evidence, or next steps.
If the content is dense, prefer multiple focused sections over one overloaded mega-diagram.
If labels would become long paragraphs inside nodes, use
```
ArchitectureGrid
```
+ surrounding prose instead of forcing everything into
```
Mermaid
```
.
For repo explainers, architecture explainers, and system walkthroughs, use no more than 2 Prose blocks unless the user explicitly asks for a prose-heavy artifact.
For repo explainers, include at least one of
```
ArchitectureGrid
```
,
```
FlowChart
```
,
```
Swimlane
```
,
```
Sequence
```
, or
```
Comparison
```
as the dominant visual surface.

如果页面只有一个核心观点，使用一个主导可视化组件，并保持辅助内容简洁。
如果页面有多个章节，每个章节应只承担一个任务：概览、拓扑结构、证据或下一步行动。
如果内容密集，优先使用多个聚焦的章节，而非一个过载的大型图表。
如果节点内的标签会变成冗长段落，使用
```
ArchitectureGrid
```
搭配周围文本，而非强行将所有内容塞进
```
Mermaid
```
。
对于仓库讲解、架构讲解和系统演练，除非用户明确要求文本密集型内容，否则使用不超过2个Prose块。
对于仓库讲解，至少包含一个
```
ArchitectureGrid
```
、
```
FlowChart
```
、
```
Swimlane
```
、
```
Sequence
```
或
```
Comparison
```
作为主导可视化组件。

5. Avoid weak compositions

5. 避免不当组合

Do not stack unrelated components just to show variety.
Do not use both
```
Mermaid
```
and
```
FlowChart
```
for the same exact relationship unless they tell different stories.
Do not use both
```
Sequence
```
and
```
Swimlane
```
for the same exact process unless one shows messages and the other shows ownership.
Do not open with a table when a diagram would explain the system faster.
Do not open with long prose when the user asked for something visual.
Do not use
```
Chart
```
where a
```
DataTable
```
or
```
Comparison
```
would be more legible.
Avoid
```
Comparison
```
as the dominant visual for repo explainers unless the source is explicitly about alternatives, trade-offs, or before/after states.
Do not create a page where every section has equal visual weight; decide what the eye should land on first.
Use inline code sparingly. Reserve backticks for real file paths, commands, identifiers, and schema keys.
No more than 1-2 inline code spans per paragraph or list item. If a section needs many identifiers, switch to
```
FileCard
```
,
```
CodeBlock
```
,
```
AnnotatedCode
```
, or a diagram label instead.
Do not wrap every tool, noun, or phrase in backticks just because it is technical.

The test: if you removed one component and the page got clearer, it probably did not belong there.

不要为了展示多样性而堆叠无关组件。
除非它们讲述不同的故事，否则不要为同一关系同时使用
```
Mermaid
```
和
```
FlowChart
```
。
除非一个展示消息，另一个展示所有权，否则不要为同一流程同时使用
```
Sequence
```
和
```
Swimlane
```
。
当图表能更快解释系统时，不要以表格开头。
当用户要求可视化内容时，不要以冗长文本开头。
在
```
DataTable
```
或
```
Comparison
```
更易读的场景下，不要使用
```
Chart
```
。
除非内容明确涉及备选方案、权衡或前后状态，否则不要将
```
Comparison
```
作为仓库讲解的主导可视化组件。
不要创建每个章节视觉权重都相同的页面；确定用户的视线应首先落在何处。
谨慎使用内联代码。仅将反引号用于真实文件路径、命令、标识符和schema键。
每个段落或列表项最多使用1-2个内联代码片段。如果一个章节需要多个标识符，改用
```
FileCard
```
、
```
CodeBlock
```
、
```
AnnotatedCode
```
或图表标签。
不要因为内容是技术性的，就将每个工具、名词或短语都用反引号包裹。

检验标准：如果移除某个组件后页面变得更清晰，那么该组件很可能不属于这里。

Envelope format

JSON包格式

Canonical shape — always this exact structure:

json

{
  "a2ui_version": "0.9",
  "catalog": "hyperscribe/v1",
  "is_task_complete": true,
  "parts": [
    {
      "component": "hyperscribe/Page",
      "props": { "title": "Auth Flow", "toc": true },
      "children": [
        {
          "component": "hyperscribe/Section",
          "props": { "id": "overview", "title": "Overview" },
          "children": [
            { "component": "hyperscribe/Prose", "props": { "markdown": "..." } }
          ]
        }
      ]
    }
  ]
}

Rules:

a2ui_version

catalog

parts

are required.

catalog

is always

"hyperscribe/v1"

Exactly one element in
```
parts
```
. Its
```
component
```
is
```
hyperscribe/Page
```
(default) or
```
hyperscribe/SlideDeck
```
(slide mode only). Multiple pages per envelope are not supported.
Container components use
```
children: []
```
. Leaf components omit
```
children
```
.
Any unknown component name or missing required prop fails validation with exit 2.

标准格式——必须严格遵循此结构：

json

{
  "a2ui_version": "0.9",
  "catalog": "hyperscribe/v1",
  "is_task_complete": true,
  "parts": [
    {
      "component": "hyperscribe/Page",
      "props": { "title": "Auth Flow", "toc": true },
      "children": [
        {
          "component": "hyperscribe/Section",
          "props": { "id": "overview", "title": "Overview" },
          "children": [
            { "component": "hyperscribe/Prose", "props": { "markdown": "..." } }
          ]
        }
      ]
    }
  ]
}

规则：

a2ui_version

、

catalog

、

parts

为必填项。

catalog

必须为

"hyperscribe/v1"

。

```
parts
```
中必须有且仅有一个元素。其
```
component
```
为
```
hyperscribe/Page
```
（默认）或
```
hyperscribe/SlideDeck
```
（仅幻灯片模式）。不支持在一个JSON包中包含多个页面。
容器组件使用
```
children: []
```
。叶子组件省略
```
children
```
。
任何未知组件名称或缺失必填属性都会导致验证失败，退出码为2。

Component inventory

组件清单

23 default components across 7 categories. See

references/catalog.md

for full prop schemas and examples.

hyperscribe/SlideDeck

and

hyperscribe/Slide

are slide-mode-only components owned by

/hyperscribe:slides

. They are intentionally excluded from the default page-mode inventory below.

Category	Component	Purpose
Structure	`hyperscribe/Page`	Root container. Exactly one per envelope. Props: `title` , `subtitle?` , `toc?` .
Structure	`hyperscribe/Section`	Titled section with auto TOC anchor. Props: `id` , `title` , `lead?` .
Structure	`hyperscribe/Heading`	In-section h2/h3/h4. Props: `level` , `text` , `anchor?` .
Structure	`hyperscribe/Prose`	Markdown paragraph block (CommonMark + GFM). Props: `markdown` .
Media	`hyperscribe/Image`	Inline image. `src` accepts https:// URL (passthrough) or local path (base64 inlined). Props: `src` , `alt` , `caption?` , `width?` , `height?` .
Emphasis	`hyperscribe/Callout`	Boxed highlight. Props: `severity` ( `info` \| `note` \| `warn` \| `success` \| `danger` ), `title?` , `body` .
Emphasis	`hyperscribe/KPICard`	Metric card with optional delta. Props: `label` , `value` , `delta?` , `hint?` .
Code	`hyperscribe/CodeBlock`	Single snippet with optional line highlights. Props: `lang` , `code` , `filename?` , `highlight?` .
Code	`hyperscribe/CodeDiff`	Before/after unified diff hunks. Props: `filename` , `lang` , `hunks[]` .
Diagrams	`hyperscribe/Mermaid`	Mermaid.js diagram with zoom/pan. Props: `kind` , `source` , `direction?` .
Diagrams	`hyperscribe/Sequence`	Native SVG sequence diagram (Notion-styled, no CDN). Props: `participants[]` , `messages[]` (kind: sync/async/return/self/note). Prefer over `Mermaid` with `kind:sequence` for consistent design.
Diagrams	`hyperscribe/FlowChart`	Native SVG directed graph with box/pill/diamond nodes. Caller supplies `ranks` (arrays of node ids) — no auto-layout. Props: `layout` (TD/LR), `nodes[]` , `edges[]` , `ranks[][]` . Prefer over Mermaid flowchart for simple pipelines.
Diagrams	`hyperscribe/ArchitectureGrid`	Card-based architecture with SVG connectors. Props: `nodes[]` , `edges?[]` , `layout` , `groups?[]` .
Diagrams	`hyperscribe/Quadrant`	2x2 prioritization matrix with plotted points. Props: `xLabel` , `yLabel` , `quadrants[]` , `points?[]` .
Diagrams	`hyperscribe/Swimlane`	Lane-based process diagram across roles on a shared sequence. Props: `lanes[]` , `steps[]` , `edges?[]` .
Data	`hyperscribe/DataTable`	Semantic HTML table. Props: `columns[]` , `rows[]` , `caption?` , `footer?` , `density?` .
Data	`hyperscribe/Chart`	Chart.js wrapper. Props: `kind` , `data` , `xLabel?` , `yLabel?` , `unit?` .
Data	`hyperscribe/Comparison`	N-way comparison. Props: `items[]` , `mode` ( `vs` \| `grid` ).
Narrative	`hyperscribe/StepList`	Ordered steps / checklist. Props: `steps[]` , `numbered?` .
Structure	`hyperscribe/FileTree`	Directory/file structure. Props: `nodes` (recursive), `showIcons?` , `caption?` .
Structure	`hyperscribe/FileCard`	Per-file summary card. Props: `name` , `path?` , `loc?` , `responsibility` , `exports?[]` , `state?` .
Code	`hyperscribe/AnnotatedCode`	Code with pinned side annotations. Props: `lang` , `code` , `annotations[]` , `pinStyle?` .
Diagrams	`hyperscribe/ERDDiagram`	DB/type ERD. Props: `entities[]` , `relationships[]` , `layout?` .

7个类别共23个默认组件。完整的属性schema和示例请参考

references/catalog.md

。

hyperscribe/SlideDeck

和

hyperscribe/Slide

是仅幻灯片模式的组件，由

/hyperscribe:slides

命令管理。它们被有意排除在以下默认页面模式组件清单之外。

类别	组件	用途
结构	`hyperscribe/Page`	根容器。每个JSON包必须有且仅有一个。属性： `title` 、 `subtitle?` 、 `toc?` 。
结构	`hyperscribe/Section`	带自动TOC锚点的标题章节。属性： `id` 、 `title` 、 `lead?` 。
结构	`hyperscribe/Heading`	章节内的h2/h3/h4标题。属性： `level` 、 `text` 、 `anchor?` 。
结构	`hyperscribe/Prose`	Markdown段落块（支持CommonMark + GFM）。属性： `markdown` 。
媒体	`hyperscribe/Image`	内联图片。 `src` 支持https:// URL（直接传递）或本地路径（转换为base64嵌入）。属性： `src` 、 `alt` 、 `caption?` 、 `width?` 、 `height?` 。
强调	`hyperscribe/Callout`	带边框的高亮块。属性： `severity` （ `info` \| `note` \| `warn` \| `success` \| `danger` ）、 `title?` 、 `body` 。
强调	`hyperscribe/KPICard`	带可选变化量的指标卡片。属性： `label` 、 `value` 、 `delta?` 、 `hint?` 。
代码	`hyperscribe/CodeBlock`	单个代码片段，支持可选行高亮。属性： `lang` 、 `code` 、 `filename?` 、 `highlight?` 。
代码	`hyperscribe/CodeDiff`	前后对比的统一差异块。属性： `filename` 、 `lang` 、 `hunks[]` 。
图表	`hyperscribe/Mermaid`	Mermaid.js图表，支持缩放/平移。属性： `kind` 、 `source` 、 `direction?` 。
图表	`hyperscribe/Sequence`	原生SVG序列图（Notion风格，无需CDN）。属性： `participants[]` 、 `messages[]` （类型：sync/async/return/self/note）。对于序列图，优先使用此组件而非 `Mermaid` 的 `kind:sequence` ，因为它是原生SVG，风格统一且无需CDN。
图表	`hyperscribe/FlowChart`	原生SVG有向图，支持矩形/圆角矩形/菱形节点。调用者需提供 `ranks` （节点ID数组）——无自动布局。属性： `layout` （TD/LR）、 `nodes[]` 、 `edges[]` 、 `ranks[][]` 。对于简单流水线，优先使用此组件而非Mermaid流程图。
图表	`hyperscribe/ArchitectureGrid`	基于卡片的架构图，带SVG连接线。属性： `nodes[]` 、 `edges?[]` 、 `layout` 、 `groups?[]` 。
图表	`hyperscribe/Quadrant`	2x2优先级矩阵，带绘制点。属性： `xLabel` 、 `yLabel` 、 `quadrants[]` 、 `points?[]` 。
图表	`hyperscribe/Swimlane`	基于分组的流程图表，跨角色展示共享序列。属性： `lanes[]` 、 `steps[]` 、 `edges?[]` 。
数据	`hyperscribe/DataTable`	语义化HTML表格。属性： `columns[]` 、 `rows[]` 、 `caption?` 、 `footer?` 、 `density?` 。
数据	`hyperscribe/Chart`	Chart.js包装器。属性： `kind` 、 `data` 、 `xLabel?` 、 `yLabel?` 、 `unit?` 。
数据	`hyperscribe/Comparison`	N项对比。属性： `items[]` 、 `mode` （ `vs` \| `grid` ）。
叙事	`hyperscribe/StepList`	有序步骤/检查清单。属性： `steps[]` 、 `numbered?` 。
结构	`hyperscribe/FileTree`	目录/文件结构。属性： `nodes` （递归）、 `showIcons?` 、 `caption?` 。
结构	`hyperscribe/FileCard`	单个文件的摘要卡片。属性： `name` 、 `path?` 、 `loc?` 、 `responsibility` 、 `exports?[]` 、 `state?` 。
代码	`hyperscribe/AnnotatedCode`	带侧边固定注释的代码。属性： `lang` 、 `code` 、 `annotations[]` 、 `pinStyle?` 。
图表	`hyperscribe/ERDDiagram`	数据库/类型ER图。属性： `entities[]` 、 `relationships[]` 、 `layout?` 。

Slide mode only

仅幻灯片模式

Use these only through

/hyperscribe:slides

Category	Component	Purpose
Slides	`hyperscribe/SlideDeck`	Slide container. Props: `aspect` , `transition?` , `footer?` . Children: Slide[].
Slides	`hyperscribe/Slide`	Single slide. Props: `layout` ( `title` \| `content` \| `two-col` \| `quote` \| `image` \| `section` ), `title?` , `subtitle?` , `bullets?` , `image?` , `quote?` .

仅通过

/hyperscribe:slides

命令使用以下组件：

类别	组件	用途
幻灯片	`hyperscribe/SlideDeck`	幻灯片容器。属性： `aspect` 、 `transition?` 、 `footer?` 。子组件：Slide[]。
幻灯片	`hyperscribe/Slide`	单张幻灯片。属性： `layout` （ `title` \| `content` \| `two-col` \| `quote` \| `image` \| `section` ）、 `title?` 、 `subtitle?` 、 `bullets?` 、 `image?` 、 `quote?` 。

Semantic-only props — NEVER style

仅语义属性 — 禁止样式设置

props

carries data, not presentation. The renderer and

assets/base.css

own every visual decision.

Do not emit

color

backgroundColor

fontSize

fontFamily

padding

margin

className

style

, or any CSS-like prop.

Do not pass inline HTML in markdown fields beyond what CommonMark/GFM allows. Script tags are stripped.
Do not try to reorder the page with custom containers — use
```
Section
```
+
```
Heading
```
hierarchy.
Do not specify chart colors, table widths, or slide transitions as decoration. Pick the right component; trust the renderer.

If you find yourself reaching for a styling prop, the correct answer is usually a different component (e.g. use

Callout severity="warn"

instead of "red box", use

KPICard delta.direction="down"

instead of "red number").

props

仅承载数据，不涉及展示。所有视觉决策由渲染器和

assets/base.css

负责。

请勿生成

color

、

backgroundColor

、

fontSize

、

fontFamily

、

padding

、

margin

、

className

、

style

或任何类似CSS的属性。

请勿在markdown字段中插入超出CommonMark/GFM允许范围的内联HTML。脚本标签会被自动移除。
请勿使用自定义容器来调整页面顺序——使用
```
Section
```
+
```
Heading
```
层级结构。
请勿指定图表颜色、表格宽度或幻灯片过渡效果作为装饰。选择合适的组件即可，信任渲染器的处理。

如果你发现自己想要设置样式属性，正确的做法通常是选择另一个组件（例如，使用

Callout severity="warn"

而非“红色框”，使用

KPICard delta.direction="down"

而非“红色数字”）。

Commands

命令

Command	Use when
`/hyperscribe`	General-purpose page. Default choice for diagrams, docs, tables, architectures, and metric summaries.
`/hyperscribe:slides`	Slide deck mode. Forces `SlideDeck` root; extracts slides from a topic or outline.
`/hyperscribe:diff`	Diff / PR review. Combines `ArchitectureGrid` (impacted modules) + `CodeDiff` + `Callout` (risks).
`/hyperscribe:share`	Deploys an existing HTML output to Vercel and returns a live URL. Input: path to a previously rendered file.

命令	使用场景
`/hyperscribe`	通用页面。图表、文档、表格、架构图和指标摘要的默认选择。
`/hyperscribe:slides`	幻灯片模式。强制使用 `SlideDeck` 作为根组件；从主题或大纲中提取幻灯片内容。
`/hyperscribe:diff`	差异/PR评审。组合 `ArchitectureGrid` （受影响模块） + `CodeDiff` + `Callout` （风险提示）。
`/hyperscribe:share`	将已生成的HTML输出部署到Vercel并返回在线URL。输入：之前生成的文件路径。

Auto-trigger logic

自动触发逻辑

Apply these rules proactively — do not wait for the user to say the word "Hyperscribe":

Table auto-trigger. If you are about to emit a markdown/ASCII table in a chat reply with
```
rows >= 4
```
OR
```
columns >= 3
```
, switch to
```
hyperscribe/DataTable
```
inside a minimal
```
Page
```
envelope.
Diagram auto-trigger. If you are about to draw ASCII boxes-and-arrows of a system, pipeline, or state machine, emit
```
hyperscribe/Sequence
```
(for actor-message diagrams),
```
hyperscribe/Mermaid
```
(flowchart / state / er / mindmap / class), or
```
hyperscribe/ArchitectureGrid
```
(for module/service topology). Prefer
```
Sequence
```
over
```
Mermaid
```
with
```
kind:sequence
```
— it is native SVG with consistent Notion styling and no CDN.
Slide auto-trigger. If the user says "slides", "deck", "presentation", "walk me through", or asks for a 5+ step recap, route through
```
/hyperscribe:slides
```
.
Diff auto-trigger. If the user pastes
```
git diff
```
output or a PR URL and asks for review, route through
```
/hyperscribe:diff
```
.
Escape hatch. If the user explicitly asks to keep it in terminal ("just tell me", "don't open a browser"), skip Hyperscribe and reply in plain text.

Modeled after

nicobailon/visual-explainer

's proactive-rendering behavior, but emitting semantic JSON instead of raw HTML.

主动应用以下规则——无需等待用户明确提及“Hyperscribe”：

表格自动触发：如果你准备在聊天回复中渲染4行及以上或3列及以上的Markdown/ASCII表格，切换为在最小
```
Page
```
包中使用
```
hyperscribe/DataTable
```
。
图表自动触发：如果你准备绘制表示系统、流水线或状态机的ASCII方框箭头图，生成
```
hyperscribe/Sequence
```
（用于参与者-消息图表）、
```
hyperscribe/Mermaid
```
（流程图/状态图/ER图/思维导图/类图）或
```
hyperscribe/ArchitectureGrid
```
（用于模块/服务拓扑）。对于序列图，优先使用
```
Sequence
```
而非
```
Mermaid
```
的
```
kind:sequence
```
——它是原生SVG，风格统一且无需CDN。
幻灯片自动触发：如果用户提到“slides”“deck”“presentation”“walk me through”，或要求5步及以上的回顾内容，通过
```
/hyperscribe:slides
```
命令处理。
差异自动触发：如果用户粘贴
```
git diff
```
输出或PR URL并要求评审，通过
```
/hyperscribe:diff
```
命令处理。
退出机制：如果用户明确要求保留在终端中展示（“直接告诉我”“不要打开浏览器”），跳过Hyperscribe，以纯文本回复。

此逻辑参考了

nicobailon/visual-explainer

的主动渲染行为，但改为生成语义JSON而非原始HTML。

Error handling

错误处理

The CLI validates before rendering. Exit codes:

Code	Meaning
0	Success
1	JSON parse error
2	Schema validation failure (stderr lists `path: message` per error)
3	IO error (cannot write output)
4	Render runtime error (partial fragment saved to `<out>.partial` )

On exit 2, read stderr, diagnose, retry. Common failures:

```
parts[0].props.title: required
```
—
```
Page
```
is missing
```
title
```
.

parts[0].children[2].props.title: required

—

Section

needs both

id

and

title

...props.severity: must be one of info|note|warn|success|danger

— wrong

Callout

severity enum.

...component: unknown component "hyperscribe/Flowchart"

— wrong name; did you mean

hyperscribe/Mermaid

with

kind: "flowchart"

```
...props.level: must be one of 2,3,4
```
—
```
Heading.level
```
only accepts 2/3/4; use
```
Page.title
```
for h1. Retry policy: up to 2 automatic retries adjusting the JSON each time. After the 3rd failure, surface the original JSON and stderr to the user so they can intervene.

CLI会在渲染前进行验证。退出码含义：

代码	含义
0	成功
1	JSON解析错误
2	Schema验证失败（stderr会列出每个错误的 `path: message` ）
3	IO错误（无法写入输出文件）
4	渲染运行时错误（部分片段保存到 `<out>.partial` ）

如果退出码为2，读取stderr内容，诊断问题后重试。常见失败原因：

```
parts[0].props.title: required
```
—
```
Page
```
组件缺少
```
title
```
属性。

parts[0].children[2].props.title: required

—

Section

组件同时需要

id

和

title

属性。

...props.severity: must be one of info|note|warn|success|danger

—

Callout

组件的

severity

枚举值错误。

...component: unknown component "hyperscribe/Flowchart"

— 组件名称错误；是否应为

hyperscribe/Mermaid

并设置

kind: "flowchart"

？

```
...props.level: must be one of 2,3,4
```
—
```
Heading.level
```
仅接受2/3/4；使用
```
Page.title
```
作为h1标题。重试策略：最多自动重试2次，每次调整JSON内容。第3次失败后，将原始JSON和stderr内容展示给用户，以便他们介入处理。

Limitations (v1)

v1版本限制

No streaming render — full JSON is produced, then rendered end-to-end.
No custom / third-party components — catalog is fixed at 23 default page components plus 2 slide-only components.
No direct styling overrides in props. Users may place
```
~/.hyperscribe/theme.json
```
to override CSS token values at the renderer level.
Themeable renderer. Built-in themes are
```
studio
```
,
```
midnight
```
,
```
void
```
, and
```
gallery
```
.
No multi-page envelopes — one
```
Page
```
per default invocation. Slide mode uses one
```
SlideDeck
```
.
Fonts:
```
NotionInter
```
is not bundled; fallback chain uses Inter / system-ui.

无流式渲染——需生成完整JSON后，再进行端到端渲染。
无自定义/第三方组件——组件库固定为23个默认页面组件加2个仅幻灯片模式组件。
属性中无法直接覆盖样式。用户可通过放置
```
~/.hyperscribe/theme.json
```
文件在渲染器层面覆盖CSS令牌值。
渲染器支持主题切换。内置主题包括
```
studio
```
、
```
midnight
```
、
```
void
```
和
```
gallery
```
。
不支持多页面包——默认每次调用只能包含一个
```
Page
```
。幻灯片模式使用一个
```
SlideDeck
```
。
字体：未捆绑
```
NotionInter
```
；回退字体链为Inter / system-ui。

Quick example

快速示例

A minimal envelope that renders a page with a callout:

json

{
  "a2ui_version": "0.9",
  "catalog": "hyperscribe/v1",
  "is_task_complete": true,
  "parts": [
    {
      "component": "hyperscribe/Page",
      "props": { "title": "Deploy checklist", "toc": false },
      "children": [
        {
          "component": "hyperscribe/Section",
          "props": { "id": "pre", "title": "Before merging" },
          "children": [
            {
              "component": "hyperscribe/StepList",
              "props": {
                "numbered": true,
                "steps": [
                  { "title": "Run tests", "body": "`pnpm test` locally.", "state": "done" },
                  { "title": "Check migrations", "body": "Review `prisma/migrations/`.", "state": "doing" },
                  { "title": "Smoke DEV", "body": "Hit `/api/health`.", "state": "todo" }
                ]
              }
            },
            {
              "component": "hyperscribe/Callout",
              "props": {
                "severity": "warn",
                "title": "Do not merge to main directly",
                "body": "Use the `preview` branch and open a PR."
              }
            }
          ]
        }
      ]
    }
  ]
}

Pipe it to the CLI:

bash

echo '<json-above>' | ~/.claude/plugins/hyperscribe/plugins/hyperscribe/scripts/hyperscribe \
  --out ~/.hyperscribe/out/deploy-checklist.html && \
  open ~/.hyperscribe/out/deploy-checklist.html

Then report the path to the user.

一个渲染包含提示框的页面的最小JSON包：

json

{
  "a2ui_version": "0.9",
  "catalog": "hyperscribe/v1",
  "is_task_complete": true,
  "parts": [
    {
      "component": "hyperscribe/Page",
      "props": { "title": "Deploy checklist", "toc": false },
      "children": [
        {
          "component": "hyperscribe/Section",
          "props": { "id": "pre", "title": "Before merging" },
          "children": [
            {
              "component": "hyperscribe/StepList",
              "props": {
                "numbered": true,
                "steps": [
                  { "title": "Run tests", "body": "`pnpm test` locally.", "state": "done" },
                  { "title": "Check migrations", "body": "Review `prisma/migrations/`.", "state": "doing" },
                  { "title": "Smoke DEV", "body": "Hit `/api/health`.", "state": "todo" }
                ]
              }
            },
            {
              "component": "hyperscribe/Callout",
              "props": {
                "severity": "warn",
                "title": "Do not merge to main directly",
                "body": "Use the `preview` branch and open a PR."
              }
            }
          ]
        }
      ]
    }
  ]
}

将其传入CLI：

bash

echo '<json-above>' | ~/.claude/plugins/hyperscribe/plugins/hyperscribe/scripts/hyperscribe \
  --out ~/.hyperscribe/out/deploy-checklist.html && \
  open ~/.hyperscribe/out/deploy-checklist.html

然后将文件路径报告给用户。