pi-生成式-ui

Claude.ai 的生成式 UI——经过逆向工程后，为 pi 重新构建。

只需让 pi 回答“给我展示复利是如何工作的”，你就能获得一个实时交互式组件：滑块、图表、动画——全部渲染在一个原生 macOS 窗口中。这不是截图，也不是代码块，而是一个真正的 HTML 应用程序，带有 JavaScript，并随着 LLM 的生成过程实时流式传输。

工作原理

在 claude.ai 上，当你请求 Claude 展示某种可视化内容时，它会调用一个名为 show_widget 的工具，在对话中内联渲染 HTML。这些 HTML 是实时流式的——随着 token 不断到达，你会看到卡片、图表和滑块逐渐出现。

这个扩展为 pi 复现了同样的系统：

1. LLM 调用 visualize_read_me —— 加载设计指南（惰性加载，仅加载相关模块）
2. LLM 调用 show_widget —— 作为工具调用参数生成一个 HTML 片段
3. 扩展拦截流式数据 —— 通过 Glimpse 打开一个原生 macOS 窗口，并在 token 到达时逐步注入部分 HTML
4. morphdom 对 DOM 进行差异比较 —— 新元素平滑淡入，未变化的元素保持不变
5. 脚本在完成时执行 —— Chart.js、D3、Three.js，以及任何来自 CDN 的库

该组件窗口具备完整的浏览器功能（WKWebView），并提供双向桥接——window.glimpse.send(data) 可将数据回传给代理。

安装

pi install git:github.com/Michaelliv/pi-generative-ui

仅适用于 macOS。需要 Swift 工具链（随 Xcode 或 Xcode 命令行工具一起提供）。

使用方法

只需让 pi 来进行可视化即可。该扩展添加了两个工具，LLM 会自动调用它们：

• “给我展示复利是如何工作的” → 带有滑块和 Chart.js 的交互式解释器
• “可视化 Transformer 的架构” → 带有标注组件的 SVG 图
• “为这些数据创建仪表盘” → 指标卡片、图表、表格
• “绘制粒子系统” → Canvas 动画

LLM 会根据请求的内容决定是使用小部件还是纯文本。解释性或视觉相关的请求会触发小部件；而代码或文本类请求则会保留在终端中。

内部构成

指南——直接从 Claude 提取

这些设计指南并非手写而成，而是完全照搬自 claude.ai。

诀窍在于：你可以将任意 claude.ai 对话导出为 JSON 格式。导出文件包含了完整的工具调用负载——包括 Anthropic 实际设计系统的完整 read_me 工具结果。总计 72KB 的生产级规则，涵盖了排版、颜色方案、适合流式的 CSS 模式、Chart.js 配置、SVG 图解设计等。

我们针对每种模块组合触发了 read_me，导出了对话，解析了 JSON，将响应拆分为去重后的部分，并与原始内容进行了字节级验证。最终结果是：我们的 LLM 获得了与 Claude 在 claude.ai 上完全相同的指令。

五个按需加载的模块：

模块	大小	涵盖内容
interactive	19KB	滑块、指标卡片、实时计算
chart	22KB	Chart.js 设置、自定义图例、数字格式化
mockup	19KB	UI 组件样式、卡片、表单、骨架加载
art	17KB	SVG 插画、Canvas 动画、创意图案
diagram	59KB	流程图、架构图、SVG 箭头系统

流式架构

该扩展会拦截 pi 的流式事件（toolcall_start / toolcall_delta / toolcall_end），以便在 token 到达时实时渲染小部件：

toolcall_start    → 初始化流式状态
toolcall_delta    → 延迟 150ms，打开窗口，使用 morphdom 进行差异比较
toolcall_end      → 最终差异比较 + 执行 <script> 标签
execute()         → 重复使用窗口，等待交互或关闭

关键细节：

• Shell HTML + JS eval —— 窗口以空壳打开；内容通过 win.send() 注入，而非 setHTML()，以避免全页闪烁
• morphdom DOM 差异比较 —— 只有发生变化的节点才会更新；新节点会有一个 0.3 秒的淡入动画
• pi-ai 的 parseStreamingJson —— 无需部分 JSON 解析器；pi 已经在每个 delta 中提供了解析好的 arguments
• 150ms 延迟 —— 将快速到达的 token 更新批量处理，以实现流畅的视觉呈现
• 默认深色模式 —— 背景为 #1a1a1a，专为 macOS WKWebView 设计

Glimpse

Glimpse 是一个原生 macOS 微型 UI 库。它通过一个小型 Swift 二进制文件，在不到 50 毫秒内打开一个 WKWebView 窗口。无需 Electron、浏览器标签页，也不依赖系统 WebKit 之外的运行时环境。

Swift 源代码会在执行 npm install 时，通过 postinstall 自动编译。

项目结构

pi-generative-ui/
├── .pi/extensions/generative-ui/
│   ├── index.ts              # 扩展：工具、流式处理、Glimpse 集成
│   ├── guidelines.ts         # 72KB 的 claude.ai 设计指南原文
│   └── claude-guidelines/    # 原始提取的 Markdown（参考）
│       ├── art.md
│       ├── chart.md
│       ├── diagram.md
│       ├── interactive.md
│       ├── mockup.md
│       └── sections/         # 去重后的部分
└── package.json              # pi 包清单

指南的提取过程

1. 在 claude.ai 上开始一次触发 show_widget 的对话
2. 分别对每个模块组合（art、chart、diagram、interactive、mockup）调用 read_me
3. 从 claude.ai 设置中将对话导出为 JSON
4. 解析 JSON——每个 tool_result for visualize:read_me 都包含完整的指南
5. 按照 ## 标题分隔线拆分每条响应
6. 去除重复的部分（例如，“颜色方案”同时出现在 chart、mockup、interactive 和 diagram 中）
7. 验证重构内容是否与原文一致（4/5 完全一致，1 个仅有一个空格字符的差异）

原始的 read_me 响应被保存在 claude-guidelines/ 文件夹中——即 claude.ai 返回的原始 Markdown，在拆分和去重之前的样子。此仓库不包含对话导出的 JSON 文件。

致谢

• pi —— 这一可扩展的编码代理使这一切成为可能
• Glimpse —— 原生 macOS 的 WKWebView 窗口
• morphdom —— 用于平滑流式的 DOM 差异比较
• Anthropic —— 构建了我们所逆向工程的生成式 UI 系统

许可证

MIT

pi-generative-ui 快速上手指南

pi-generative-ui 是一个为 pi 智能体打造的生成式 UI 扩展。它复刻了 Claude.ai 的原生交互体验，让 pi 能够直接在你的 macOS 桌面上渲染出可交互的 HTML 应用（如滑块、图表、动画），而非仅仅输出代码块或文本截图。

环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统：仅限 macOS。
• 核心依赖：必须安装 Swift 工具链。
  • 如果你已安装完整版的 Xcode，则默认包含。
  • 如果未安装 Xcode，可通过终端安装轻量级的 Xcode Command Line Tools：

    xcode-select --install
    

• 前置软件：确保已安装并配置好 pi 智能体框架。

安装步骤

使用 pi 包管理器直接从 GitHub 安装该扩展。安装过程中会自动编译所需的 Swift 二进制文件（基于 Glimpse 库）。

pi install git:github.com/Michaelliv/pi-generative-ui

注意：首次安装时，系统可能会提示确认 Swift 编译操作，请耐心等待编译完成。

基本使用

安装完成后无需额外配置。你只需像平常一样与 pi 对话，当请求涉及可视化或交互内容时，扩展会自动拦截并调用原生窗口进行渲染。

使用示例

直接在终端向 pi 发送以下类型的指令：

1. 交互式原理解析

show me how compound interest works

效果：弹出一个原生窗口，展示带有滑块的复利计算器，拖动滑块可实时看到 Chart.js 绘制的曲线变化。

2. 架构可视化

Visualize the architecture of a transformer

效果：生成一个带有标注组件的 SVG 架构图，支持缩放和悬停交互。

3. 数据仪表盘

Create a dashboard for this data

效果：渲染包含指标卡片、动态图表和数据表格的完整仪表盘界面。

4. 创意动画

Draw a particle system

效果：在窗口中运行基于 Canvas 的粒子系统动画。

工作原理简述

• 自动触发：LLM 会根据你的请求意图，自动决定是输出文本还是调用 show_widget 工具生成界面。
• 流式渲染：界面随着 Token 的生成实时“流”入窗口，新元素会以淡入动画平滑出现。
• 双向交互：生成的界面是全功能的浏览器环境（WKWebView），支持执行 JavaScript，并可通过 window.glimpse.send(data) 将用户交互数据回传给智能体。