AI Agent-Readable GIFs — Machine Layer Documentation

المشكلة

صور GIF معتمة أمام وكلاء الذكاء الاصطناعي. عندما يحتوي README على تسجيل طرفية بصيغة GIF، يرى وكيل الذكاء الاصطناعي بيانات بكسل ثنائية — لا يمكنه استخراج الأوامر أو فهم المخرجات أو الإشارة إلى خطوات محددة. هذا قيد أساسي للتوثيق المستند إلى الصور.

يحل AgentGIF هذا بإرفاق بيانات منظمة قابلة للقراءة آلياً مع كل تسجيل.

بنية الطبقة المزدوجة

كل تسجيل على AgentGIF له طبقتان تتعايشان في نفس الرابط:

يرى الإنسان طرفية متحركة. يرى وكيل الذكاء الاصطناعي بيانات منظمة: الأوامر والمخرجات والطوابع الزمنية والبيانات الوصفية ورموز التضمين.

ملفات Cast (Asciinema v2)

The cast file is the richest data source. It's an asciinema v2 recording with precise timestamps for every terminal event.

الوصول إلى الـ Cast

curl -s https://agentgif.com/api/v1/gifs/{id}/cast/

بنية ملف Cast

السطر الأول هو ترويسة JSON مع بيانات وصفية للطرفية:

{"version": 2, "width": 120, "height": 40, "timestamp": 1710000000, "env": {"SHELL": "/bin/zsh", "TERM": "xterm-256color"}}

الأسطر التالية عبارة عن مجموعات أحداث:

[0.0, "o", "$ "]
[0.5, "o", "docker compose up -d\r\n"]
[1.2, "o", "\u001b[32mCreating network...\u001b[0m\r\n"]
[2.8, "o", "Container app-1  Started\r\n"]

كل مجموعة هي [timestamp_seconds, event_type, data]:

• "o" — output event (text written to the terminal screen)
• "i" — input event (user keystrokes, if captured)
• الطوابع الزمنية بالثواني من بداية التسجيل
• قد تحتوي البيانات على رموز إفلات ANSI للألوان

تحليل ملف Cast

import json

# Read cast file
lines = cast_data.strip().split("\n")
header = json.loads(lines[0])
events = [json.loads(line) for line in lines[1:]]

# Extract all output text
output = "".join(data for ts, typ, data in events if typ == "o")

# Find commands (lines starting with $ or % prompt)
commands = [line for line in output.split("\n") if line.startswith("$ ")]

النصوص

في حالات الاستخدام الأبسط، تعيد نقطة نهاية النص نصاً عادياً نظيفاً:

curl -s https://agentgif.com/api/v1/gifs/{id}/transcript/

تحذف النصوص رموز الإفلات ANSI وتضغط المسافة البيضاء وتقدم جلسة الطرفية كنص قابل للقراءة. وهي مثالية لـ:

• التضمين في نوافذ سياق النماذج اللغوية الكبيرة (رموز دلالية قليلة)
• فهرسة البحث النصي الكامل
• توليد التوثيق من الجلسات المسجّلة
• مقارنة مخرجات الطرفية عبر التسجيلات

نقاط نهاية .md

كل صفحة على AgentGIF لها نسخة Markdown. أضف .md إلى أي رابط:

# GIF detail → structured summary
curl https://agentgif.com/@agentgif/docker-compose/.md

# Tag listing → all GIFs with this tag
curl https://agentgif.com/explore/tags/docker/.md

# Tool page → all GIFs for this CLI tool
curl https://agentgif.com/tools/git/.md

# Collection → ordered GIF list
curl https://agentgif.com/@agentgif/collections/devops-essentials/.md

الاستجابة هي text/markdown; charset=utf-8 — نص نظيف منظم يمكن للنماذج اللغوية الكبيرة تحليله مباشرةً.

JSON API

يوفر REST API بيانات منظمة كاملة. لا تتطلب عمليات القراءة مصادقة:

# Search for GIFs about a topic
curl -s "https://agentgif.com/api/v1/search/?q=kubernetes" | jq '.results[:3] | .[].title'

# Get full metadata for a specific GIF
curl -s "https://agentgif.com/api/v1/gifs/{id}/" | jq '{title, command, tags, gif_url}'

# Browse by tag
curl -s "https://agentgif.com/api/v1/tags/docker/gifs/" | jq '.count'

See the complete API Reference for all 30+ endpoints.

اكتشاف المحتوى

يمكن لوكلاء الذكاء الاصطناعي اكتشاف محتوى AgentGIF عبر قنوات متعددة:

أمثلة من الواقع

Agent: "Find a Docker demo and explain the steps"

# 1. Search for Docker GIFs
curl -s "https://agentgif.com/api/v1/search/?q=docker+compose" | jq '.results[0].id'
# → "xK9mQ2pL"

# 2. Get the transcript
curl -s "https://agentgif.com/api/v1/gifs/xK9mQ2pL/transcript/"
# → $ docker compose up -d
#   Creating network...
#   Container app-1  Started

# 3. Agent can now explain: "The demo shows docker compose up -d,
#    which starts services in detached mode..."

Agent: "Add a demo GIF to a README"

# 1. Search for the right tool
curl -s "https://agentgif.com/api/v1/search/?q=ripgrep" | jq '.results[0] | {id, gif_url, title}'

# 2. Generate embed code
# → [![ripgrep demo](https://media.agentgif.com/ID.gif)](https://agentgif.com/ID)

Agent: "Compare two terminal tools"

# Get GIFs for both tools
curl -s "https://agentgif.com/api/v1/tags/grep/gifs/" | jq '.results[].command'
curl -s "https://agentgif.com/api/v1/tags/ripgrep/gifs/" | jq '.results[].command'

# Compare the transcripts to understand different syntax