Claw2UI — Agent 到 UI 的桥梁

基于 TypeScript DSL 规范生成交互式网页，并通过公开 URL 提供服务。页面默认集成 Tailwind CSS、Alpine.js 和 Chart.js，支持可插拔主题、类型检查及响应式移动端布局。

源码：GitHub · npm · HF Space · 许可证：MIT

数据安全与用户确认

每个已发布的页面均可通过公开 URL 访问。未经用户明确授权，严禁发布。

• 发布前必须获得用户确认——清晰说明将要发布的内容，并等待用户明确回复“yes”或“go ahead”。静默发布绝对不可接受
• 禁止在页面内容中包含密钥、凭证、API 密钥、令牌、PII（个人身份信息）或内部端点
• 对所有用户提供的数据进行清洗后再嵌入——html 组件会在服务端自动清洗，但应避免将未经信任的原始输入直接传给其他组件
• 对临时性或敏感数据使用 TTL（生存时间），使页面自动过期：--ttl 3600000（1 小时）
• 发布前务必人工审核内容——检查表格行、统计值、图表标签等位置是否意外泄露敏感信息

安装配置

Claw2UI 默认使用公共服务器 https://0xsegfaulted-claw2ui.hf.space，无需本地部署服务端。

npm install -g claw2ui
claw2ui register --server https://0xsegfaulted-claw2ui.hf.space
# 完成！Token 已自动保存至 ~/.claw2ui.json

自托管：如需自行部署 Claw2UI 服务端（本地、Docker 或 HF Space），请参阅自托管指南。

工作流程

步骤 1：确保连接正常

# 仅需注册一次（Token 自动保存至 ~/.claw2ui.json）
claw2ui register --server https://0xsegfaulted-claw2ui.hf.space

步骤 2：编写 TypeScript DSL 规范

编写一个 .ts 文件，内容必须包裹在 container 中。该文件将自动进行类型检查。

cat > /tmp/claw2ui_page.ts << 'SPECEOF'
import { page, container, header, row, stat, card, chart, dataset } from "claw2ui/dsl"

export default page("Page Title", [
  container(
    header("Title", "Description"),
    row(3,
      stat("Metric 1", "100", { change: 5.2, icon: "trending_up" }),
      stat("Metric 2", "200"),
      stat("Metric 3", "300"),
    ),
    card("Trend",
      chart("line", {
        labels: ["Jan", "Feb", "Mar"],
        datasets: [dataset("Value", [10, 20, 15], { borderColor: "#3b82f6", tension: 0.3 })],
      }),
    ),
  ),
], { style: "anthropic" })
SPECEOF

步骤 3：向用户确认

发布前，请向用户说明将要发布的内容，并确认其是否同意继续操作。该页面将可通过公开 URL访问。例如：

“我已为您准备了一个仪表盘，内容包括：[内容摘要]。是否确认发布至公开 URL？（可添加 --ttl 3600000 参数，使页面 1 小时后自动过期。）”

步骤 4：发布

仅在获得用户明确确认后执行：

claw2ui publish --spec-file /tmp/claw2ui_page.ts --title "Dashboard"
# 对于敏感或临时数据，始终设置 TTL：
claw2ui publish --spec-file /tmp/claw2ui_page.ts --title "Dashboard" --ttl 3600000
# 跳过类型检查以加速发布（不推荐）：
claw2ui publish --spec-file /tmp/claw2ui_page.ts --title "Dashboard" --no-check

命令将输出公开 URL。

步骤 5：分享 URL

将生成的 URL 包含在您对用户的响应中。

CLI 命令

# 连接管理
claw2ui register --server          # 自助注册
claw2ui init --server  --token  # 手动配置

# 发布
claw2ui publish --spec-file  --title "Title"    # 从 TS DSL 发布（带类型检查）
claw2ui publish --spec-file  --no-check         # 跳过类型检查
claw2ui publish --spec-file  --title "Title"  # 从 JSON 规范发布（遗留支持）
claw2ui publish --html "
Hi
" --title "Test"      # 原生 HTML
claw2ui publish --spec-file  --style anthropic     # 指定主题
claw2ui publish --spec-file  --ttl 3600000         # 设置 TTL（毫秒）

# 主题管理
claw2ui themes                          # 列出可用主题

# 页面管理
claw2ui list                            # 列出所有已发布页面
claw2ui delete                # 删除指定页面
claw2ui status                          # 检查服务端状态

DSL 函数参考

所有函数均从 "claw2ui/dsl" 导入。

页面入口

page(title, components[], opts?)  // opts: { theme?: "light"|"dark"|"auto", style?: "anthropic"|"classic" }

布局组件（接受 ...children）

container(...children)              // 最外层容器，必须使用
row(cols, ...children)              // 网格行：row(3, stat(...), stat(...), stat(...))
column(span, ...children)           // 行内网格列
card(title, ...children)            // 带边框/阴影的卡片
list(direction, ...children)        // "vertical" 或 "horizontal"
modal(title, ...children)           // 弹出式对话框

特殊容器

tabs(                               // 标签页
  tab("id", "Label", ...children),
  tab("id2", "Label 2", ...children),
)

accordion(                          // 可折叠区域
  section("Title", ...children),
  section("Title 2", ...children),
)

数据展示

stat(label, value, opts?)           // opts: { change?: number, icon?: string }
chart(chartType, data, opts?)       // opts: { height?, options?, legendPosition?, title? }
table(columns, rows, opts?)         // opts: { searchable?, perPage? }

辅助函数（用于图表与表格）

dataset(label, data[], opts?)       // Chart.js 数据集：dataset("Rev", [1,2,3], { borderColor: "red" })
col(key, label?, format?)           // 列定义：col("name", "Name", "currency")
badge(key, label, badgeMap)         // Badge 列：badge("status", "Status", { Active: "success" })
months(n)                           // 月份标签：months(6) → ["Jan","Feb","Mar","Apr","May","Jun"]

输入控件

button(label, variant?)             // variant: "primary"|"secondary"|"danger"|"outline"
textField(label?, opts?)            // opts: { placeholder?, value?, inputType? }
select(label, options)              // options: [{ value: "a", label: "Option A" }]
checkbox(label, value?)
choicePicker(label, options, opts?) // opts: { value?, variant?, displayStyle? }
slider(label, opts?)                // opts: { min?, max?, value? }
dateTimeInput(label, opts?)         // opts: { value?, enableDate?, enableTime?, min?, max? }

媒体与文本

markdown(content)                   // 渲染 Markdown 为样式化 HTML（富文本首选）
text(content, opts?)                // opts: { size?, bold?, class? }
code(content, language?)            // 带语法高亮的代码块
html(content)                       // 原生 HTML（服务端自动清洗）
icon(name, size?)                   // Material Icon：icon("settings", 24)
image(src, alt?)
video(url, poster?)
audioPlayer(url, description?)
divider()
spacer(size?)

导航

header(title, subtitle?)            // 页面标题栏
link(href, label?, target?)         // 超链接

可用主题（style 字段）

最佳实践

始终使用 TypeScript DSL，而非 JSON

DSL 支持类型检查，约节省 60% token 消耗，并可嵌入逻辑。JSON 规范仍受支持，但属于遗留方案。

善用循环与条件语句

// 基于数据动态生成 stats
const metrics = [
  { label: "CPU", value: "42%", icon: "monitor" },
  { label: "Memory", value: "6.2 GB", icon: "memory" },
  { label: "Disk", value: "120 MB/s", icon: "storage" },
]
row(3, ...metrics.map(m => stat(m.label, m.value, { icon: m.icon })))

// 条件渲染
container(
  header("Report"),
  data.length > 0
    ? card("Trend", chart("line", chartData))
    : text("No data available"),
)

// 过滤 falsy 值
container(
  header("Dashboard"),
  showMetrics && row(3, stat("A", "1"), stat("B", "2"), stat("C", "3")),
  card("Details", table(cols, rows)),
)

优先使用 col() / badge() / dataset() 辅助函数

// 推荐 —— 简洁且可读性强
table(
  [col("name", "Name"), col("rev", "Revenue", "currency"), badge("status", "Status", { Active: "success" })],
  rows,
)

// 避免 —— 冗长的原始对象
table(
  [{ key: "name", label: "Name" }, { key: "rev", label: "Revenue", format: "currency" }, { key: "status", label: "Status", format: "badge", badgeMap: { Active: "success" } }],
  rows,
)

富文本请使用 markdown()

card("About",
  markdown(`
## Features
- **Fast** — sub-second rendering
- **Secure** — sanitized HTML output
- **Responsive** — mobile-first layouts

> Built with Claw2UI
  `),
)

图表标签请使用 months()

chart("bar", {
  labels: months(6),
  datasets: [dataset("Revenue", [100, 200, 150, 300, 250, 400])],
})

设计模式

仪表盘（Dashboard）

import { page, container, header, row, stat, card, chart, table, col, badge, dataset } from "claw2ui/dsl"

export default page("Dashboard", [
  container(
    header("Dashboard", "Overview"),
    row(3,
      stat("Revenue", "$1.2M", { change: 15.3, icon: "payments" }),
      stat("Orders", "8,432", { change: 8.1, icon: "shopping_cart" }),
      stat("Customers", "2,847", { change: -2.5, icon: "group" }),
    ),
    card("Trend",
      chart("line", {
        labels: months(6),
        datasets: [dataset("Revenue", [320, 410, 380, 450, 480, 520], {
          borderColor: "#3b82f6", tension: 0.3, fill: true,
          backgroundColor: "rgba(59,130,246,0.1)",
        })],
      }, { height: 280 }),
    ),
    card("Details",
      table(
        [col("name", "Name"), col("value", "Value", "currency"), badge("status", "Status", { Active: "success", Inactive: "error" })],
        [
          { name: "Product A", value: 450000, status: "Active" },
          { name: "Product B", value: 320000, status: "Active" },
          { name: "Product C", value: 0, status: "Inactive" },
        ],
      ),
    ),
  ),
], { style: "anthropic" })

带标签页的报告（Report with Tabs）

import { page, container, header, row, stat, card, chart, table, tabs, tab, text, markdown, col, dataset, months } from "claw2ui/dsl"

export default page("Monthly Report", [
  container(
    header("Monthly Report", "March 2026"),
    tabs(
      tab("overview", "Overview",
        row(3,
          stat("Users", "12,847", { change: 18.5, icon: "group" }),
          stat("Revenue", "$89K", { change: 24.3, icon: "payments" }),
          stat("Churn", "3.2%", { change: -1.1, icon: "trending_down" }),
        ),
        card("Growth",
          chart("line", {
            labels: months(6),
            datasets: [
              dataset("Users", [8000, 9200, 10100, 11000, 11800, 12847], { borderColor: "#3b82f6" }),
              dataset("Revenue", [52, 58, 65, 72, 81, 89], { borderColor: "#10b981", yAxisID: "y1" }),
            ],
          }),
        ),
      ),
      tab("details", "Details",
        table(
          [col("page", "Page"), col("views", "Views"), col("bounce", "Bounce", "percent")],
          [
            { page: "/", views: "23,456", bounce: 28 },
            { page: "/pricing", views: "12,567", bounce: 22 },
            { page: "/docs", views: "9,876", bounce: 18 },
          ],
        ),
      ),
      tab("notes", "Notes",
        markdown("## Key Takeawaysnn- Revenue up **24.3%** MoMn- Churn improved by 1.1ppn- `/pricing` page has lowest bounce rate"),
      ),
    ),
  ),
], { style: "anthropic" })

对比方案（Comparison）

import { page, container, header, row, card, stat, text, table, col } from "claw2ui/dsl"

export default page("Plan Comparison", [
  container(
    header("Plan Comparison", "Choose the right plan"),
    row(3,
      card("Starter",
        stat("Price", "$9/mo"),
        text("5 users, 10 GB storage"),
      ),
      card("Pro",
        stat("Price", "$29/mo", { icon: "star" }),
        text("25 users, 100 GB storage"),
      ),
      card("Enterprise",
        stat("Price", "Custom", { icon: "business" }),
        text("Unlimited users, 1 TB storage"),
      ),
    ),
    card("Feature Matrix",
      table(
        [col("feature", "Feature"), col("starter", "Starter"), col("pro", "Pro"), col("enterprise", "Enterprise")],
        [
          { feature: "Users", starter: "5", pro: "25", enterprise: "Unlimited" },
          { feature: "Storage", starter: "10 GB", pro: "100 GB", enterprise: "1 TB" },
          { feature: "Support", starter: "Email", pro: "Priority", enterprise: "Dedicated" },
        ],
      ),
    ),
  ),
], { style: "anthropic" })