ray-so-code-snippet

ray.so 代码片段图片生成器

使用 ray.so 生成精美的代码片段图片，并保存到本地。

要求

• 用户必须提供代码片段，可以直接提供，也可以指定上下文中的文件／选区
• 生成前必须询问用户所有样式参数，并列出所有可用选项
• 必须使用 agent-browser 截取图像（先检查是否可用）

工作流

步骤 1：确认 agent-browser 是否可用

继续操作前，确认 agent-browser 是否可用：

which agent-browser

如果 PATH 中找不到 agent-browser，请告知用户此技能需要 agent-browser，没有它无法继续。

步骤 2：获取可用选项

使用 curl 从 ray.so 的 GitHub 仓库获取当前主题和语言：

# Fetch and parse available themes
curl -s "https://raw.githubusercontent.com/raycast/ray-so/main/app/(navigation)/(code)/store/themes.ts" | grep -oE 'id:\s*"[^"]+"' | sed 's/id:\s*"//;s/"//' | sort -u

# Fetch and parse available languages
curl -s "https://raw.githubusercontent.com/raycast/ray-so/main/app/(navigation)/(code)/util/languages.ts" | grep -oE '^[[:space:]]*"?[a-zA-Z0-9+#-]+"?\s*:\s*\{' | sed 's/[[:space:]]*"//g;s/".*//;s/:.*//' | sort -u

步骤 3：询问用户所有参数

必须使用 AskUserQuestion 询问每个参数，并列出所有可用选项。按以下顺序询问参数：

3.1 主题选择

列出所有可用主题。在问题中列出从步骤 2 获取的每个主题。示例：

Question: "Which theme would you like?"
Description: "Available themes: [list ALL themes from curl output]"
Options (pick 4 popular ones for quick select):
- breeze (default, purple gradient)
- midnight (cyan-blue)
- vercel (minimalist dark)
- sunset (warm orange)
Note: User can select "Other" to type any theme from the full list

3.2 语言选择

尽可能推断语言。 以下情况跳过此问题：

• 用户明确指定了语言
• 代码来自扩展名明确的文件（例如，.py → python、.js → javascript、.ts → typescript、.rs → rust、.go → go 等）
• 语法特征明确无误（例如，def／import → python、func／package → go、fn／let mut → rust）

仅在无法自信地推断语言时才询问：

Question: "Which language for syntax highlighting?"
Description: "Available languages: [list ALL languages from curl output]"
Options:
- auto (auto-detect)
- javascript
- python
- typescript
Note: User can select "Other" to type any language from the full list

3.3 深色／浅色模式

Question: "Dark or light mode?"
Options:
- Dark mode (default)
- Light mode

3.4 背景

Question: "Show the gradient background?"
Options:
- Yes, show background (default)
- No, transparent/minimal background

3.5 内边距

Question: "How much padding around the code?"
Options:
- 16 (compact)
- 32 (small)
- 64 (medium, default)
- 128 (large)

3.6 行号

Question: "Show line numbers?"
Options:
- No (default)
- Yes

3.7 标题

Question: "Add a title above the code? (e.g., filename)"
Options:
- No title (default)
- Yes, add title
If yes, ask for the title text.

注意：不要询问输出路径／文件名。保存到当前工作目录，并使用合适的文件名（例如，rayso-snippet.png，或者根据提供的标题命名，如 fibonacci.png）。只有当用户在原始请求中明确指定了其他路径时，才使用不同路径。

步骤 4：构建 ray.so URL

重要：所有参数都必须放在 URL 哈希部分（# 后），而不是查询字符串中。

使用 shell 命令构建 URL：

# 1. Base64 encode the code
CODE_BASE64=$(echo -n 'YOUR_CODE_HERE' | base64)

# 2. URL encode the base64 string
CODE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$CODE_BASE64'))")

# 3. Build the URL with ALL parameters in the hash
# Format: https://ray.so/#param1=value1&param2=value2&code=ENCODED_CODE
# Do NOT include width parameter - let ray.so auto-size to fit content
URL="https://ray.so/#theme=THEME&padding=PADDING&background=BACKGROUND&darkMode=DARKMODE&language=LANGUAGE&code=${CODE_ENCODED}"

# Add optional parameters if needed:
# If lineNumbers: add "&lineNumbers=true" before &code=
# If title: add "&title=URL_ENCODED_TITLE" before &code=

URL 哈希参数：

参数	值	默认值
theme	列表中的任意主题	breeze
padding	16、32、64、128	64
background	true、false	true
darkMode	true、false	true
language	列表中的任意语言，或 "auto"	auto
lineNumbers	true、false	false
title	URL 编码后的字符串	（无）
width	数字（像素）	auto
code	Base64 编码后再进行 URL 编码	（必填）

关于 width 的说明： 除非确实需要固定宽度，否则不要包含 width 参数。不包含该参数时，ray.so 会自动调整画布大小以适应代码内容，避免出现不必要的空白。

URL 构建示例：

# For code: for i in range(23):\n    print(i)
# Theme: midnight, Padding: 64, Dark mode: true, Background: true, Language: python, Title: test.py

CODE='for i in range(23):
    print(i)'
CODE_BASE64=$(echo -n "$CODE" | base64)
CODE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$CODE_BASE64'))")
TITLE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('test.py'))")
URL="https://ray.so/#theme=midnight&padding=64&background=true&darkMode=true&language=python&title=${TITLE_ENCODED}&code=${CODE_ENCODED}"
echo "$URL"

步骤 5：使用 agent-browser 截取高质量图片

必须使用 agent-browser（已在步骤 1 中确认）。此方法使用 html-to-image 库（与 ray.so 内部导出功能使用的库相同），并设置较高的 pixelRatio，以便清晰、锐利地渲染文本。

重要： 始终使用 --session 指定唯一的会话名称，以避免会话过期问题。

# Generate unique session name
SESSION="rayso-$(date +%s)"

# 1. Set viewport
agent-browser --session $SESSION set viewport 1400 900

# 2. Open the URL
agent-browser --session $SESSION open "$URL"

# 3. Wait for the page to fully render
agent-browser --session $SESSION wait --load networkidle
agent-browser --session $SESSION wait 3000

# 4. Load html-to-image library (same library ray.so uses internally)
agent-browser --session $SESSION eval 'new Promise((r,e)=>{const s=document.createElement("script");s.src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html-to-image.js";s.onload=r;s.onerror=e;document.head.appendChild(s)})'

# 5. Capture at 4x resolution using html-to-image (produces crisp text)
agent-browser --session $SESSION eval 'htmlToImage.toPng(document.querySelector("#frame > div"),{pixelRatio:4,skipAutoScale:true})' > /tmp/rayso-dataurl-$SESSION.txt

# 6. Close the browser
agent-browser --session $SESSION close

# 7. Convert data URL to PNG file
DATAURL=$(cat /tmp/rayso-dataurl-$SESSION.txt | tr -d '"' | tr -d '\n')
echo "$DATAURL" | sed 's/data:image\/png;base64,//' | base64 -d > /path/to/output.png

# 8. Clean up temp file
rm /tmp/rayso-dataurl-$SESSION.txt

重要说明：

• 使用 html-to-image 库，ray.so 自身的导出功能也使用此库
• pixelRatio: 4 可生成清晰、锐利的高 DPI 图片（原生分辨率的 4 倍）
• 数据 URL 由该库直接捕获，而不是从屏幕截图中获取
• 无需 ImageMagick——完全通过浏览器进行高分辨率渲染
• 输出尺寸正确，不含额外空白

步骤 6：确认输出并停止

向用户报告已保存文件的位置。任务到此完成——保存截图后不要再执行任何其他检查、探索或验证。

完整示例

用户：“为这个 Python 函数创建一张代码片段图片”

def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

1. 检查 which agent-browser——确认可用

2. 获取主题和语言：

curl -s "https://raw.githubusercontent.com/raycast/ray-so/main/app/(navigation)/(code)/store/themes.ts" | grep -oE 'id:\s*"[^"]+"' | sed 's/id:\s*"//;s/"//' | sort -u

3. 通过 AskUserQuestion 向用户询问参数：

   • 主题：用户选择“midnight”
   • 语言：根据 def 语法推断为 python——未询问
   • 深色模式：用户选择“深色模式”
   • 背景：用户选择“是”
   • 内边距：用户选择“64”
   • 行号：用户选择“否”
   • 标题：用户选择“无标题”

4. 构建 URL（所有参数都在哈希中，不设置宽度以自动调整尺寸）：

CODE='def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)'
CODE_BASE64=$(echo -n "$CODE" | base64)
CODE_ENCODED=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$CODE_BASE64'))")
URL="https://ray.so/#theme=midnight&padding=64&background=true&darkMode=true&language=python&code=${CODE_ENCODED}"

5. 捕获高质量图片：

SESSION="rayso-$(date +%s)"

agent-browser --session $SESSION set viewport 1400 900
agent-browser --session $SESSION open "$URL"
agent-browser --session $SESSION wait --load networkidle
agent-browser --session $SESSION wait 3000

# Load html-to-image library
agent-browser --session $SESSION eval 'new Promise((r,e)=>{const s=document.createElement("script");s.src="https://cdn.jsdelivr.net/npm/[email protected]/dist/html-to-image.js";s.onload=r;s.onerror=e;document.head.appendChild(s)})'

# Capture at 4x resolution
agent-browser --session $SESSION eval 'htmlToImage.toPng(document.querySelector("#frame > div"),{pixelRatio:4,skipAutoScale:true})' > /tmp/rayso-dataurl-$SESSION.txt
agent-browser --session $SESSION close

# Save as PNG
DATAURL=$(cat /tmp/rayso-dataurl-$SESSION.txt | tr -d '"' | tr -d '\n')
echo "$DATAURL" | sed 's/data:image\/png;base64,//' | base64 -d > ./fibonacci.png
rm /tmp/rayso-dataurl-$SESSION.txt

6. 报告：“代码片段图片已保存到 ./fibonacci.png”

图片分辨率和质量

此技能使用 html-to-image 库，并将 pixelRatio 设为 4，以生成清晰锐利的高质量图片。这与 ray.so 内置导出功能使用的渲染方式相同。

输出质量：

• 默认：原生分辨率的 4 倍（画面自动适应内容尺寸，然后以 4 倍分辨率渲染）
• 文本以高 DPI 渲染，而非从低分辨率放大
• 渐变背景和所有 CSS 样式均会保留
• 没有多余空白（画面自动调整尺寸以适应代码）

调整分辨率：

• 文件较小时：在 eval 命令中将 pixelRatio:4 改为 pixelRatio:2
• 追求最高质量时：使用 pixelRatio:6（与 ray.so 的“6x”导出选项相同）

指定固定宽度：

• 只有需要固定宽度时（例如，确保多张图片尺寸一致），才在 URL 中添加 &width=NUMBER

故障排除

• **如果 agent-browser 不可用：**告知用户并停止操作
• 如果 curl 获取主题或语言失败，请使用以下常见默认值：
  • 主题：breeze、midnight、candy、crimson、falcon、meadow、raindrop、sunset、vercel、supabase、tailwind
  • 语言：auto、javascript、typescript、python、rust、go、java、ruby、swift、kotlin、css、html、json、yaml、bash
• **如果参数未生效：**确保所有参数都位于 URL 哈希中（# 之后），而非查询字符串中
• **如果标题未显示：**标题参数必须位于哈希中：#title=filename.py&code=...
• **如果 html-to-image 加载失败：**检查网络连接；该库从 jsdelivr CDN 加载
• **如果捕获结果为空：**帧选择器 #frame > div 可能已更改；检查页面结构
• 对于很长的代码片段，ray.so 可能会截断内容；可以考虑拆分成多张图片
• 如果页面未能正常加载，请延长等待时间（尝试 4000ms 或更长）
• **如果页面为空白：**使用 --session 标志指定一个全新的唯一会话名称
• **如果数据 URL 格式错误：**确保在进行 base64 解码前移除引号和换行符