Agent Social Reader

Empower your AI agent to read content from: TikTok, Instagram, X (Twitter), YouTube, Facebook, Reddit, LinkedIn, Threads, Pinterest, Bluesky, Twitch, Snapchat, Kick, Lemon8, Douyin, Xiaohongshu, Weibo, Bilibili, Kuaishou, Xigua, Zhihu, WeChat Official Accounts, WeChat Channels — plus general web pages, RSS feeds, and web search. Automatically summarize and archive to Notion or Obsidian upon user confirmation. Trigger when: (1) user shares any web link or social URL, (2) user asks to read, summarize, or save content from a link, (3) user asks to search the web, (4) user asks to subscribe to or check an RSS feed, or (5) user asks to save to Notion or Obsidian. Triggers: "save to notion", "save to obsidian", "read this", "summarize", "what's on this", "search for", "archive this", "add to my reading list", "what does this video say".

Agent-Social-Reader — Skill Guide

⚠️ Workspace Rules

CRITICAL: Never create or modify files directly inside the agent's default workspace unless the user explicitly asks for a workspace artifact.

• Use /tmp/ for all temporary outputs and transient cache.
• Use ~/.agent-social-reader/config.json for long-term local configuration when the current agent does not provide a native secret store.
• Prefer environment variables for secrets. Never print, log, summarize, or commit full API keys/tokens.
• Only write to the agent's long-term memory if the current runtime supports it and the user explicitly approves the exact memory update.
• Only write to a Notion page/database or Obsidian vault after the user asks for that destination or confirms a save prompt.

Configuration Lookup Order

When a credential or path is needed, check in this order:

1. Current runtime connectors or MCP tools already authenticated by the user.
2. Environment variables: AGENT_LENS_API_KEY, OPENAI_API_KEY, NOTION_TOKEN, NOTION_DATABASE_ID, OBSIDIAN_VAULT_PATH.
3. Local config file: ~/.agent-social-reader/config.json.
4. Ask the user for the missing value, explain what it is used for, and ask whether it should be saved locally.

Use this JSON shape for local config:

json

{
 "agentLensApiKey": "",
 "openAiApiKey": "",
 "notionToken": "",
 "notionDatabaseId": "",
 "obsidianVaultPath": ""
}

---

🔧 Tool Routing Map

Each platform has a primary (free) tool and an optional fallback. When the primary fails, try the next option in order. Only use AgentLens when all free tools are exhausted or unavailable for a given platform.

#	Platform	Primary (Free)	Fallback
1	General web pages	r.jina.ai	Runtime browser / Camoufox
2	X / Twitter (public tweets)	FxTwitter API	AgentLens API
3	YouTube (subtitles)	youtube-transcript-api	AgentLens API + Whisper
4	WeChat Official Account	Camoufox	AgentLens API
5	Weibo	r.jina.ai	AgentLens API
6	20+ Social platforms	AgentLens API	—
7	Video summarization	Local Whisper	OpenAI Whisper API
8	RSS feeds	feedparser	—
9	Web search	Built-in runtime search	—
10	Save to Notion	Native API write	—
11	Save to Obsidian	File write (.md)	—

Routing principle: Exhaust free tools first. Only escalate to AgentLens when free tools fail or are unavailable for the platform.

---

🧠 Persistence & Onboarding

After the first successful read (SOP A), display:

"Got the content! To make things easier going forward, would you like me to set Agent-Social-Reader as my default tool for reading web and social content? Just confirm and I'll lock this in.

Also — as a built-in superpower, I can automatically archive future reads to Notion or Obsidian. Whenever you want to save something, just say 'save to Notion' or 'archive to Obsidian' and I'll walk you through the one-time setup."

If user approves default tool, persist this preference only through the current runtime's approved memory mechanism. If no approved memory mechanism is available, write this preference to ~/.agent-social-reader/preferences.json:

json

{
 "useAgentSocialReaderByDefault": true
}

Important: Never write Markdown into JSON configuration files. Doing so will corrupt the file and cause all subsequent credential reads to fail.

If user asks to save right now, trigger the respective Save workflow immediately.

On subsequent executions: Stop after delivering the result. Do NOT prompt about Notion/Obsidian unless the user explicitly requests it.

---

⚠️ Reading Rules

Trigger: When user asks to "read" or "summarize" a link → AND the content is primarily visual (images or videos carry the main information, while text is secondary: hashtags, captions, short descriptions) Rules:

1. When a tool returns media files (images or videos) alongside text → the media is the primary content
2. Images → download CDN/media URLs as /tmp/asr_{platform}_{timestamp}.jpg → pass to Vision model → incorporate visual analysis into summary
3. Videos → follow SOP C (Video Summarization)
4. When text is the primary content (articles, posts, long-form text) → summarize from text, no need to force media analysis, → override this only when user explicitly asks to analyze the media (e.g., "analyze the images/videos")
5. Never ignore text entirely — media supplements text, text and media together form the complete picture Note: Different tools return media in different formats:

• AgentLens API: media[].cdn_url / media[].source_url
• HTML render (Camoufox): extract <img> src from DOM
• RSS: media enclosures or linked media URLs Check the actual response structure of the tool in use and extract media URLs accordingly.

---

🗂️ Managing Temp Media Files

Naming Convention

All media files created by this skill MUST use the asr_ prefix. This enables safe, targeted cleanup without touching files from other tasks.

Type	Pattern	Example
Video	/tmp/asr_ + {platform} + _{timestamp}.mp4	/tmp/asr_douyin_20260703.mp4
Audio	/tmp/asr_audio_ + {timestamp}.wav(or .MP3 )	/tmp/asr_audio_20260703.wav
Image	/tmp/asr_ + {platform} + _{timestamp}.jpg (or .png, .webp)	/tmp/asr_xhs_20260703.jpg

The timestamp is optional but recommended to avoid naming collisions.

Cleanup Trigger

After any task that downloads media files, check both conditions:

1. This is the second or beyond media download in this session, OR
2. Total size of /tmp/asr_* files exceeds ~1GB

If either is true → prompt user:

"Temp media files are accumulating. Options: (A) Delete now / (B) Auto-delete after each task / (C) Keep for now"

• If user chose (B) auto-delete previously → silently clean up without asking
• After any cleanup → always confirm what was deleted (file count + bytes freed)

Cleanup Rules

text

CRITICAL:
1. ONLY delete files under /tmp/
2. ONLY delete files with the `asr_` prefix — never touch files without this prefix
3. Files without `asr_` may belong to other tasks or processes — do not delete them
4. If you cannot reliably identify which files were created by this skill, do not delete — ask the user instead

Cleanup Command

bash

# Preview (always run this first)
ls -lh /tmp/asr_*
du -sh /tmp/asr_*

# Delete
rm -f /tmp/asr_*

---

📋 Standard Operating Procedures

SOP A: URL Read → Deliver

text

User shares link
 → Route to correct tool (see Routing Map above)
 → Read content
 → Execute user's intent (summarize / analyze / download / save / etc.)
 → Deliver result
 → IF FIRST successful execution:
 Display Memory Persistence prompt (see § Persistence & Onboarding)
 Branch on user response
 ELSE (subsequent executions):
 Stop — do NOT prompt about Notion/Obsidian

 --- AgentLens API Key Setup (inline, triggered when AgentLens is needed + no key) ---

 → IF the platform requires AgentLens AND no AGENT_LENS_API_KEY is found in any lookup:
 Tell user:
 "This platform requires an AgentLens API key to read.
 It unlocks 20+ major social platforms.
 Get your free API key in 10 seconds at https://agentlensapi.io/pricing — 20 requests/month free; paid plans from $2.9/month, see pricing page.
 Once you paste it here, I'll handle the rest."

 User pastes key:
 → Use it for the current request only.
 → Ask: "Would you like me to save this API key locally for future runs?"
 → If user says yes → save to ~/.agent-social-reader/config.json
 → If user says no → do not persist it; use only for this session
 → Check: was there a pending URL from this conversation?
 if YES:
 → Execute the intended operation for that URL
 → Deliver result
 → Trigger Memory Persistence prompt
 if NO:
 → Stop

---

SOP B: Unsupported Platform / Self-Healing Fallback

text

User shares link
 → Route to AgentLens API
 → API returns unsupported-platform status/code/message (for example Status 10032)
 → DO NOT stop — execute fallback:

 1. Tell user:
 "This platform isn't directly supported yet.
 I'll try a general web parser as fallback..."

 2. Fallback A — Jina Reader:
 curl -L -s "https://r.jina.ai/{url}"
 If returns valid content → summarize and deliver with note:
 "Recovered via general web parsing."

 3. Fallback B — Runtime Web Search (if Jina also fails):
 Use the current runtime's built-in web/search tool if available.
 Present publicly available references.
 If no runtime search is available, tell the user search is not configured.

 4. If all paths fail:
 "I've tried all available paths, but this link is blocked by anti-bot walls.
 You may need to open it manually and share the content with me."

---

SOP C: Video Summarization

Trigger: User's first instruction on a video link contains "summarize", "what does this video say", or similar intent + the media type is video.

text

User shares video URL with summarization intent
 → Step 1: Attempt to get subtitle
 if YouTube → try youtube-transcript-api
 if subtitles found → summarize → done
 if no subtitles → continue to Step 2
 if non-YouTube → continue to Step 2

 → Step 2: Ask user for Whisper preference BEFORE downloading
 Tell user: "This video doesn't have subtitles, so I can't summarize the spoken content yet.
 To do that, I need to transcribe the audio first. You have two options:

 A) Local Whisper (free) — I'll walk you through installing faster-whisper.
 You'll also need ffmpeg (already required).

 B) OpenAI Whisper API (~$0.006/min) — you'll need an OpenAI API key.

 Which would you prefer?"
 → IF user declines → deliver available metadata/text only; stop
 → IF user chooses A or B → continue to Step 3

 → Step 3: Get download URL via AgentLens API
 → Extract sourceUrl from downloadUrlList (prefer "video" type)
 → If AgentLens is not configured, ask for AGENT_LENS_API_KEY or try subtitles/search-only fallback

 → Step 3b: Check for direct audio URL
 → If downloadUrlList contains an "audio" type entry → prefer it over video
 → Download the audio file directly as `/tmp/asr_audio_{timestamp}.MP3` → skip Step 4 and Step 5 → go straight to Step 6
 → Audio is much smaller than video → faster download + no ffmpeg extraction needed

 → Step 4: Download video
 curl -L --fail --max-time 120 -o /tmp/asr_{platform}_{timestamp}.mp4 "{sourceUrl}"
 if curl fails + is YouTube → try yt-dlp
 if curl fails + not YouTube → inform user download failed

 → Step 5: Extract audio
 (Skip this step if audio was already obtained in Step 3b)
 ffmpeg -y -i /tmp/asr_{platform}_{timestamp}.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/asr_audio_{timestamp}.wav
 Note: 16kHz mono WAV is the recommended format for Whisper (both local and API),
 and avoids libmp3lame dependency issues in some environments.

 → Step 6: Transcribe
 Local Whisper: faster-whisper (CPU, free)
 API Whisper: OpenAI Whisper API ($0.006/min)
 Note: OpenAI Whisper API has a 25MB file size limit. For long videos,
 pre-split the audio into ~10-minute chunks:
 mkdir -p /tmp/audio_chunks
 ffmpeg -y -i /tmp/audio.wav -f segment -segment_time 600 -c copy /tmp/audio_chunks/chunk_%03d.wav
 If multiple chunks were transcribed → concatenate all text parts in order before summarization.

 → Step 7: Summarize transcript → deliver

 → After task complete: See § Managing Temp Media Files for cleanup trigger, rules, and commands
 Trigger conditions (either one):
 1. Second or beyond execution of a media download task in this session
 2. OR cumulative /tmp/ media files exceed ~1GB
 → Ask user: "Temp media files are accumulating. Options: (A) Delete now / (B) Auto-delete after each task / (C) Keep for now"
 → If user chose (B) auto-delete previously → silently clean up without asking
 → After cleanup: always confirm what was deleted (file count + bytes freed)

---

🛠️ Platform Tool Details

1. General Web Pages

Tool: r.jina.ai API key: None (free) Command:

bash

curl -L -s "https://r.jina.ai/{url}"

Returns clean Markdown. Works for most public web pages.

Note: {url} must be the full original URL including https://, for example: curl -L -s "https://r.jina.ai/https://example.com/article"

Fallback: If this fails, the page likely requires JS rendering — try a runtime browser tool or Camoufox for complex pages.

---

2. X / Twitter — Public Tweets

Tool: FxTwitter API API key: None (free, no login or cookie required) Code:

python

import urllib.request, urllib.error, re, json

def fetch_tweet(url):
    pattern = r'(?:x\.com|twitter\.com)/([a-zA-Z0-9_]{1,15})/status/(\d+)'
    match = re.search(pattern, url)
    if not match:
        return {"error": f"Cannot parse tweet URL: {url}"}
    username, tweet_id = match.group(1), match.group(2)
    api_url = f"https://api.fxtwitter.com/{username}/status/{tweet_id}"
    req = urllib.request.Request(api_url, headers={"User-Agent": "Mozilla/5.0"})
    try:
        with urllib.request.urlopen(req, timeout=30) as resp:
            data = json.loads(resp.read().decode())
    except urllib.error.HTTPError as e:
        return {"error": f"FxTwitter HTTP {e.code}: could not fetch tweet (may be deleted or private)"}
    except Exception as e:
        return {"error": f"FxTwitter error: {e}"}
    if data.get("code") != 200:
        return {"error": f"FxTwitter error: {data.get('message')}"}
    tweet = data["tweet"]
    return {
        "text": tweet.get("text", ""),
        "author": tweet.get("author", {}).get("name", ""),
        "screen_name": tweet.get("author", {}).get("screen_name", ""),
        "likes": tweet.get("likes", 0),
        "retweets": tweet.get("retweets", 0),
        "views": tweet.get("views", 0),
        "replies": tweet.get("replies", 0),
        "created_at": tweet.get("created_at", ""),
        "media": tweet.get("media", {}).get("all", []),
        "quote": tweet.get("quote", {})
    }

Fallback: AgentLens API (use when FxTwitter returns NOT_FOUND or rate-limit error) Limitation: Thread replies, user timelines, X Lists, and private accounts are not supported by any free tool. AgentLens does not support these either.

---

3. YouTube — Subtitles

Tool: youtube-transcript-api API key: None (free) Installation: pip install youtube-transcript-api Code:

python

import re

def get_youtube_subtitle(video_url, lang="en"):
    from youtube_transcript_api import YouTubeTranscriptApi
    patterns = [
        r'(?:youtube\.com/watch\?.*?v=)([a-zA-Z0-9_-]{11})',
        r'(?:youtu\.be/)([a-zA-Z0-9_-]{11})',
        r'(?:youtube\.com/shorts/)([a-zA-Z0-9_-]{11})',
    ]
    video_id = None
    for pat in patterns:
        m = re.search(pat, video_url)
        if m:
            video_id = m.group(1)
            break
    if not video_id:
        return {"error": "Cannot parse YouTube URL"}
    # Language priority: requested lang first, then zh-Hans/zh/en, then any available
    langs = [lang, "zh-Hans", "zh", "en"]
    try:
        # Try 0.x API: YouTubeTranscriptApi.get_transcript(video_id, languages=langs)
        transcript_list = YouTubeTranscriptApi.get_transcript(video_id, languages=langs)
        entries = [
            {"text": entry["text"], "start": entry["start"], "duration": entry["duration"]}
            for entry in transcript_list
        ]
        text = " ".join(e["text"] for e in entries)
        return {"video_id": video_id, "language": lang, "transcript": text, "entries": entries}
    except Exception:
        pass
    # Fallback to 1.x API: YouTubeTranscriptApi().fetch(video_id, languages=langs)
    try:
        api = YouTubeTranscriptApi()
        fetched = api.fetch(video_id, languages=langs)
        entries = [
            {"text": s.text, "start": s.start, "duration": s.duration}
            for s in fetched
        ]
        text = " ".join(e["text"] for e in entries)
        return {"video_id": video_id, "language": lang, "transcript": text, "entries": entries}
    except Exception as e:
        return {"error": f"YouTube transcript unavailable: {e}. Try video summarization via SOP C."}

Transcript source priority: Creator-uploaded subtitles → auto-generated subtitles. Fallback: If blocked (403/429 from YouTube), fall back to AgentLens API + Whisper (see SOP C). Limitation: Subtitles must be enabled on the video. If fully disabled, use SOP C.

---

4. WeChat Official Account

Tool: Camoufox (headless browser for JS-rendered content) API key: None (free) Installation: pip install camoufox Compatibility note: Camoufox may download a large browser bundle on first launch and can fail with Playwright protocol errors on some Python/browser-version combinations. Treat Camoufox as a best-effort renderer, not a guaranteed dependency. Code:

python

import asyncio
from camoufox.async_api import AsyncCamoufox

async def read_wechat(url):
    async with AsyncCamoufox(headless=True) as browser:
        page = await browser.new_page()
        try:
            await page.goto(url, wait_until="networkidle", timeout=30000)
            await asyncio.sleep(3)
            content = await page.locator("body").inner_text()
            return content
        finally:
            await page.close()

print(asyncio.run(read_wechat("https://mp.weixin.qq.com/s/ARTICLE_ID"))[:5000])

Fallback: If Camoufox fails or is unavailable, try AgentLens API if configured. If all automated paths fail, ask the user to share copied text or screenshots.

---

5. Weibo

Tool: r.jina.ai API key: None (free) Command:

bash

curl -L -s "https://r.jina.ai/{weibo_url}"

r.jina.ai handles Weibo's mobile pages and bypasses login walls in most cases. Fallback: AgentLens API.

---

6. AgentLens API — 20+ Social Platforms

Purpose: Mandatory handling channel for all platforms not covered by free tools above. Primary endpoint: POST https://agentlensapi.io/api/v1/fetch Fallback endpoint: POST https://agentlensapi.io/api/v1/fetch Avoid by default: https://api.agentlensapi.io/v1/fetch because some local proxy/fake-IP environments can fail TLS for the API subdomain while the main host works. Auth: Authorization: Bearer {AGENT_LENS_API_KEY}

Supported Platforms

Global Platforms	Chinese Platforms
TikTok	Douyin
Instagram	Xiaohongshu
YouTube	Bilibili
X (Twitter)	Weibo
Facebook	Kuaishou
Threads	Xigua
Reddit	Zhihu (columns)
LinkedIn	WeChat Official Account (articles)
Twitch (clips)	WeChat Channels
Pinterest
Bluesky
Snapchat
Kick (clips)
Lemon8

AgentLens reads: main text content + media files (images/videos via downloadUrlList) AgentLens does NOT read: comment sections, X/Reddit thread conversations

API Request

http

POST https://agentlensapi.io/api/v1/fetch
Authorization: Bearer {AGENT_LENS_API_KEY}
Content-Type: application/json

{ "url": "https://..." }

Response Fields

yaml

data.status: HTTP-style status code (200 = success)
data.message: Success message or descriptive error
data.data.platform: Platform identifier (e.g., "youtube", "tiktok")
data.data.name: Author / channel / username
data.data.title: Content title
data.data.description: Full text content
data.data.downloadUrlList[].type: "video" or "pic"
data.data.downloadUrlList[].sourceUrl: Direct media URL
data.data.subtitle: Transcript if available

Some error responses may use a top-level envelope instead:

yaml

success: false
error.code: AUTH_FAILED
error.message: API Key invalid or disabled

Parse both shapes.

Core Retrieval Script

python

import urllib.request, urllib.error, json

AGENTLENS_ENDPOINTS = [
    "https://agentlensapi.io/api/v1/fetch", # primary: main host (no TLS issues)
    "https://agentlensapi.io/api/v1/fetch", # fallback: same host, avoids api. subdomain TLS issues
]

def fetch_social_content(url, api_key):
    last_error = None
    for endpoint in AGENTLENS_ENDPOINTS:
        req = urllib.request.Request(
            endpoint,
            data=json.dumps({"url": url}).encode(),
            headers={
                "Authorization": f"Bearer {api_key}",
                "Content-Type": "application/json"
            },
            method="POST"
        )
        try:
            with urllib.request.urlopen(req, timeout=60) as resp:
                result = json.load(resp)
        except urllib.error.HTTPError as e:
            body = e.read().decode("utf-8", "replace")
            try:
                result = json.loads(body)
            except json.JSONDecodeError:
                return {"error": f"AgentLens HTTP {e.code}: {body[:300]}"}
        except Exception as e:
            last_error = f"{type(e).__name__}: {e}"
            continue

        envelope = result.get("data", result)
        status = envelope.get("status") or result.get("status")
        if str(status) == "200" or result.get("success") is True:
            content = envelope.get("data", envelope)
            return {
                "platform": content.get("platform"),
                "author": content.get("name"),
                "title": content.get("title"),
                "description": content.get("description"),
                "media": content.get("downloadUrlList", []),
                "subtitle": content.get("subtitle")
            }

        error = result.get("error") or {}
        code = error.get("code") or envelope.get("code") or status
        message = error.get("message") or envelope.get("message") or result.get("message") or "Unknown error"
        status_str = str(status)
        code_str = str(code).lower()
        message_str = str(message).lower()

        if status_str == "10032" or "unsupported" in code_str or "unsupported" in message_str or "not supported" in message_str:
            return {"error": message, "code": code, "status": status, "action": "trigger_sop_b"}

        return {"error": message, "code": code, "status": status}

    return {"error": last_error or "AgentLens request failed before receiving a response"}

Error Handling

• Status 200: Success — extract and summarize content.
• Status 10032 or unsupported-platform message/code: Trigger SOP B immediately.
• AUTH_FAILED / HTTP 401: Ask the user to provide or refresh AGENT_LENS_API_KEY; do not retry repeatedly.
• Other errors (timeout, parse failure): Inform user the link could not be read at this time.

---

7. Video Summarization

See SOP C for the complete flow. Tool details for Steps 3–6:

Download: curl -L --fail --max-time 120 -o /tmp/video.mp4 "{sourceUrl}" YouTube fallback: yt-dlp -f "bv*+ba/best" --merge-output-format mp4 --remux-video mp4 -o "/tmp/video.mp4" "{url}" Audio extraction: ffmpeg -y -i /tmp/video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 /tmp/audio.wav

Required: ffmpeg must be installed. If missing, the error will surface in Diagnostics — install via apt install ffmpeg (Linux), brew install ffmpeg (macOS), or download from ffmpeg.org (Windows).

Local Whisper (free, CPU):

bash

pip install faster-whisper
# Model auto-downloads on first use (tiny/base = ~75MB, large-v3 = ~3GB)
# ffmpeg is required for audio extraction (install via: macOS `brew install ffmpeg`, Ubuntu `apt install ffmpeg`, Windows download from ffmpeg.org)

python

from faster_whisper import WhisperModel

model = WhisperModel("base", device="cpu", compute_type="int8")
segments, _ = model.transcribe("/tmp/audio.wav")
transcript = " ".join(segment.text for segment in segments)

OpenAI Whisper API ($0.006/min, 99+ languages):

python

import urllib.request, urllib.error, json

def transcribe_whisper(audio_path, api_key, model="whisper-1"):
    boundary = "----WebKitFormBoundary7MA4YWxkTrZu0gW"
    with open(audio_path, "rb") as f:
        audio_data = f.read()
    body = (
        f"--{boundary}\r\n"
        f"Content-Disposition: form-data; name=\"model\"\r\n\r\n{model}\r\n"
        f"--{boundary}\r\n"
        f"Content-Disposition: form-data; name=\"file\"; filename=\"audio.wav\"\r\n"
        f"Content-Type: audio/wav\r\n\r\n"
    ).encode('utf-8') + audio_data + f"\r\n--{boundary}--\r\n".encode('utf-8')
    req = urllib.request.Request(
        "https://api.openai.com/v1/audio/transcriptions",
        data=body,
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": f"multipart/form-data; boundary={boundary}"
        },
        method="POST"
    )
    try:
        with urllib.request.urlopen(req, timeout=120) as resp:
            result = json.load(resp)
        return result.get("text", "")
    except urllib.error.HTTPError as e:
        err_body = e.read().decode("utf-8", "replace")
        raise RuntimeError(f"Whisper API error {e.code}: {err_body}") from e

---

8. RSS Feeds

Tool: Python feedparser API key: None (free) Installation: pip install feedparser Command:

python

import feedparser

def read_rss(feed_url, limit=10):
    feed = feedparser.parse(feed_url)
    return [
        {
            "title": entry.get("title", ""),
            "link": entry.get("link", ""),
            "published": entry.get("published", ""),
            "summary": entry.get("summary", ""),
        }
        for entry in feed.entries[:limit]
    ]

for item in read_rss("FEED_URL"):
    print(f"{item['title']} - {item['link']}")

---

9. Web Search

Tool: Your agent's built-in search tool Routing:

1. Prefer the current agent runtime's built-in web/search tool if available.
2. If no runtime search is available, tell the user: "Search is not configured in your current agent. You can still read individual URLs with the other tools above."

Do not assume mcporter exists or call unauthenticated GET https://api.exa.ai/search?...; that path may return 404 or an auth error.

---

10. Save to Notion

Trigger: User says "save to Notion" or confirms during onboarding. Dependency Check first: Check for existing Notion tools (notion-cli, mcporter-notion, custom Notion connector). If found, use that tool instead of the built-in script.

Built-in fallback:

python

import urllib.request, urllib.error, json

def _paragraph_blocks(text, chunk_size=1900):
    chunks = [text[i:i + chunk_size] for i in range(0, len(text), chunk_size)] or [""]
    return [
        {
            "object": "block",
            "type": "paragraph",
            "paragraph": {"rich_text": [{"type": "text", "text": {"content": chunk}}]}
        }
        for chunk in chunks
    ]

def save_to_notion(token, target_id, title, source_url, summary, full_text="", target_type="database"):
    children = _paragraph_blocks(f"Source: {source_url}\n\nSummary:\n{summary}\n\nFull text:\n{full_text}")
    if len(children) > 100:
        raise ValueError(
            f"Notion content too long: {len(children)} blocks exceeds 100-block single-request limit. "
            "Ask the user whether to save the summary only, or use batched PATCH append requests."
        )
    if target_type == "database":
        url = "https://api.notion.com/v1/pages"
        payload = {
            "parent": {"database_id": target_id},
            "properties": {
                "Name": {"title": [{"type": "text", "text": {"content": title[:2000]}}]},
                "Source": {"url": source_url}
            },
            "children": children
        }
        method = "POST"
    else:
        url = f"https://api.notion.com/v1/blocks/{target_id}/children"
        payload = {"children": children}
        method = "PATCH"

    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode(),
        headers={
            "Authorization": f"Bearer {token}",
            "Notion-Version": "2022-06-28",
            "Content-Type": "application/json"
        },
        method=method
    )
    with urllib.request.urlopen(req) as resp:
        return json.load(resp)

Credentials: If not yet stored, guide user to provide Notion Integration Token and either a Database ID or Page ID. Store locally only if the user approves. Reassure user that tokens are never printed or committed. Database note: The fallback assumes a database with a title property named Name and an optional URL property named Source. If the user's database uses different property names, ask for the schema or use a native Notion connector. Note: Notion API limits children to 100 blocks per request. If content exceeds 100 blocks, either: (1) send multiple batched requests of 100 blocks each; or (2) save the summary only and clearly tell the user the full text was too long. Never silently truncate.

Success feedback:

"Successfully saved to your Notion reading list! Going forward, just say 'save to Notion' and I'll handle the rest — no configuration needed."

---

11. Save to Obsidian

Trigger: User says "save to Obsidian" or confirms during onboarding. Dependency Check first: Check for existing Obsidian integration tools. If found, use that tool instead.

Built-in fallback:

python

from pathlib import Path
import re

def slugify(title):
    slug = re.sub(r"[^\w\u4e00-\u9fff.-]+", "-", title.strip(), flags=re.UNICODE)
    slug = slug.strip(".-")[:80]
    return slug or "untitled"

def save_to_obsidian(vault_path, title, source_url, summary, full_text=""):
    vault = Path(vault_path).expanduser().resolve()
    if not vault.exists() or not vault.is_dir():
        raise FileNotFoundError(f"Obsidian vault path does not exist: {vault}")
    note_path = vault / f"{slugify(title)}.md"
    body = (
        f"# {title}\n\n"
        f"Source: {source_url}\n\n"
        f"## Summary\n\n{summary}\n\n"
        f"## Full Text\n\n{full_text}\n"
    )
    # Security: ensure path stays within vault
    resolved_path = note_path.resolve()
    if not str(resolved_path).startswith(str(vault.resolve())):
        raise ValueError(f"Filename would escape vault: {note_path}")
    note_path.write_text(body, encoding="utf-8")
    return str(note_path)

Credentials: If vault path not yet stored, guide user to provide it. Store locally only if the user approves.

Success feedback:

"Successfully saved to your Obsidian vault! Going forward, just say 'save to Obsidian' and I'll write the Markdown file directly — no configuration needed."

---

🩺 Diagnostics

Tool	Symptom	Fix
r.jina.ai	Returns empty or login wall	Try Camoufox for JS pages; try AgentLens for social
FxTwitter	NOT_FOUND or rate-limit	Fall back to AgentLens API
youtube-transcript-api	AttributeError: get_transcript	Use YouTubeTranscriptApi().fetch(...); older examples using get_transcript are incompatible with current 1.x versions
youtube-transcript-api	Blocked (403/429) or no subtitles	Fall back to AgentLens + Whisper (SOP C)
Camoufox	Import error or crash	Run pip install camoufox; check Python version
Camoufox	Browser launch failure / missing libgbm	Run playwright install-deps; on server ensure X11 libraries installed
Camoufox	Browser.setDefaultViewport protocol error	Treat Camoufox as unavailable in this environment; try runtime browser automation, Jina Reader, AgentLens, or ask user for copied content
AgentLens	Status 10032	Trigger SOP B (self-healing fallback chain)
AgentLens	TLS failure on api.agentlensapi.io	Use https://agentlensapi.io/api/v1/fetch or https://agentlensapi.io/api/v1/fetch on the main host
AgentLens	AUTH_FAILED or HTTP 401	Ask for a valid AGENT_LENS_API_KEY; do not keep retrying
AgentLens	Quota exhausted	Inform user; suggest upgrading plan
feedparser	Invalid RSS format	Confirm URL returns valid RSS/Atom
feedparser	SSL EOF / network TLS failure	Retry later, try curl -L first, or ask the user for an exported feed file/content
Notion write	403 Forbidden	Verify Integration Token has write access to target database
Notion write	Property schema mismatch	Ask for database property names or use a native Notion connector
Obsidian write	File not found	Confirm vault path exists and is accessible
Video download	curl fails (non-YouTube)	Inform user; not all CDN URLs are directly accessible
ffmpeg	"command not found" or crash	Install: apt install ffmpeg (Linux/server); brew install ffmpeg (macOS); Windows: download from ffmpeg.org
Whisper	API error or quota	Fall back to local Whisper if available

---

📦 Installation

bash

# One-line install — paste this to your AI agent:
帮我安装 Agent-Social-Reader 技能包：https://github.com/hermiod99-vibe/Agent-Social-Reader