mcpField
D
debugging-output-and-previewing-html-using-ray

debugging-output-and-previewing-html-using-ray

github.com/coollabsio开发65.2k49 次安装今天更新
代码仓库

关于 debugging-output-and-previewing-html-using-ray

该技能通过本地 HTTP 服务将调试数据和视觉内容发送到 Spatie 的 Ray 桌面应用，并说明日志、预览及窗口信息的请求格式和接口。

主要功能

  1. 01向 Ray 发送日志和值
  2. 02显示自定义 HTML 或文本
  3. 03以表格展示数据
  4. 04为条目添加标签、颜色和尺寸
  5. 05发送通知和计时数据
  6. 06查询窗口与主题颜色

适用场景

  1. 01调试时检查应用数据
  2. 02在 Ray 中预览 HTML 或视觉素材
  3. 03用标签和颜色整理相关条目
  4. 04使自定义预览匹配 Ray 主题

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/coollabsio/coolify --skill debugging-output-and-previewing-html-using-ray

安装后在 Claude Code 中输入/debugging-output-and-previewing-html-using-ray确认已加载。

详细介绍

Ray 技能

概述

Ray 是 Spatie 为开发者打造的桌面调试应用。向其本地服务器发送 HTTP 请求，即可直接将数据发送到 Ray。

这对于调试应用，或预览设计、徽标及其他视觉内容都很有帮助。

PHP 函数 ray() 底层执行的就是这些操作。

连接详情

设置默认值环境变量
主机localhostRAY_HOST
端口23517RAY_PORT
URLhttp://localhost:23517/-

请求格式

方法： POST Content-Type： application/json User-Agent： Ray 1.0

基本请求结构
{
  "uuid": "unique-identifier-for-this-ray-instance",
  "payloads": [
    {
      "type": "log",
      "content": { },
      "origin": {
        "file": "/path/to/file.php",
        "line_number": 42,
        "hostname": "my-machine"
      }
    }
  ],
  "meta": {
    "ray_package_version": "1.0.0"
  }
}
字段
字段类型说明
uuid字符串此 Ray 实例的唯一标识符。使用相同的 UUID 可更新已有条目。
payloads数组要发送的负载对象数组
meta对象可选元数据（ray_package_version、project_name、php_version）
Origin 对象

每个负载都包含来源信息：

{
  "file": "/Users/dev/project/app/Controller.php",
  "line_number": 42,
  "hostname": "dev-machine"
}

负载类型

Log（发送值）
{
  "type": "log",
  "content": {
    "values": ["Hello World", 42, {"key": "value"}]
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
Custom（HTML／文本内容）
{
  "type": "custom",
  "content": {
    "content": "<h1>HTML Content</h1><p>With formatting</p>",
    "label": "My Label"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
Table
{
  "type": "table",
  "content": {
    "values": {"name": "John", "email": "[email protected]", "age": 30},
    "label": "User Data"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
Color

设置前一条日志条目的颜色：

{
  "type": "color",
  "content": {
    "color": "green"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

可用颜色： green、orange、red、purple、blue、gray

Screen Color

设置屏幕的背景颜色：

{
  "type": "screen_color",
  "content": {
    "color": "green"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
Label

为条目添加标签：

{
  "type": "label",
  "content": {
    "label": "Important"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
Size

设置条目的大小：

{
  "type": "size",
  "content": {
    "size": "lg"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

可用大小： sm、lg

Notify（桌面通知）
{
  "type": "notify",
  "content": {
    "value": "Task completed!"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
New Screen
{
  "type": "new_screen",
  "content": {
    "name": "Debug Session"
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
Measure（计时）
{
  "type": "measure",
  "content": {
    "name": "my-timer",
    "is_new_timer": true,
    "total_time": 0,
    "time_since_last_call": 0,
    "max_memory_usage_during_total_time": 0,
    "max_memory_usage_since_last_call": 0
  },
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}

后续测量时，将 is_new_timer: false，并提供实际计时值。

简单负载（无内容）

这些负载只需要 type 和空的 content：

{
  "type": "separator",
  "content": {},
  "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
}
类型用途
separator添加视觉分隔线
clear_all清除所有条目
hide隐藏此条目
remove移除此条目
confetti显示彩纸动画
show_app将 Ray 窗口置于前台
hide_app隐藏 Ray 窗口

组合多个负载

在一个请求中发送多个负载。使用相同的 uuid，即可对日志条目应用修饰项（颜色、标签、大小）：

{
  "uuid": "abc-123",
  "payloads": [
    {
      "type": "log",
      "content": { "values": ["Important message"] },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "color",
      "content": { "color": "red" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "label",
      "content": { "label": "ERROR" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    },
    {
      "type": "size",
      "content": { "size": "lg" },
      "origin": { "file": "test.php", "line_number": 1, "hostname": "localhost" }
    }
  ],
  "meta": {}
}

示例：完整请求

发送一条绿色且带标签的日志消息：

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -H "User-Agent: Ray 1.0" \
  -d '{
    "uuid": "my-unique-id-123",
    "payloads": [
      {
        "type": "log",
        "content": {
          "values": ["User logged in", {"user_id": 42, "name": "John"}]
        },
        "origin": {
          "file": "/app/AuthController.php",
          "line_number": 55,
          "hostname": "dev-server"
        }
      },
      {
        "type": "color",
        "content": { "color": "green" },
        "origin": { "file": "/app/AuthController.php", "line_number": 55, "hostname": "dev-server" }
      },
      {
        "type": "label",
        "content": { "label": "Auth" },
        "origin": { "file": "/app/AuthController.php", "line_number": 55, "hostname": "dev-server" }
      }
    ],
    "meta": {
      "project_name": "my-app"
    }
  }'

可用性检查

发送数据前，可以检查 Ray 是否正在运行：

GET http://localhost:23517/_availability_check

Ray 在可用时会返回 HTTP 404（该端点不存在，但服务器正在运行）。

获取 Ray 信息

获取窗口

获取所有已打开 Ray 窗口的信息：

GET http://localhost:23517/windows

返回包含窗口 ID 和名称的窗口对象数组：

[
  {"id": 1, "name": "Window 1"},
  {"id": 2, "name": "Debug Session"}
]
获取主题颜色

获取 Ray 当前使用的主题颜色：

GET http://localhost:23517/theme

返回包含调色板的主题信息：

{
  "name": "Dark",
  "colors": {
    "primary": "#000000",
    "secondary": "#1a1a1a",
    "accent": "#3b82f6"
  }
}

使用场景： 向 Ray 发送自定义 HTML 内容时，可使用这些主题颜色，使内容与 Ray 当前主题相匹配并自然融入界面。

示例： 发送颜色相匹配的 HTML：


# First, get the theme

THEME=$(curl -s http://localhost:23517/theme)
PRIMARY_COLOR=$(echo $THEME | jq -r '.colors.primary')

# Then send HTML using those colors

curl -X POST http://localhost:23517/ \
  -H "Content-Type: application/json" \
  -d '{
    "uuid": "theme-matched-html",
    "payloads": [{
      "type": "custom",
      "content": {
        "content": "<div style=\"background: '"$PRIMARY_COLOR"'; padding: 20px;\"><h1>Themed Content</h1></div>",
        "label": "Themed HTML"
      },
      "origin": {"file": "script.sh", "line_number": 1, "hostname": "localhost"}
    }]
  }'

负载类型参考

类型内容字段用途
logvalues（数组）向 Ray 发送值
customcontent、labelHTML 或文本内容
tablevalues、label以表格形式显示
colorcolor设置条目颜色
screen_colorcolor设置屏幕背景
labellabel为条目添加标签
sizesize设置条目大小（sm/lg）
notifyvalue桌面通知
new_screenname创建新屏幕
measurename、is_new_timer、计时字段性能计时
separator（空）视觉分隔线
clear_all（空）清除所有条目
hide（空）隐藏条目
remove（空）移除条目
confetti（空）彩纸动画
show_app（空）显示 Ray 窗口
hide_app（空）隐藏 Ray 窗口

评论

支持 Markdown