felo-ai 0.2.6 → 0.2.9

package/felo-superAgent/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: felo-superAgent
+description: "Felo SuperAgent API: AI conversation with real-time SSE streaming and LiveDoc. Use when users want SuperAgent chat, continuous conversation, or LiveDoc-backed answers. Explicit commands: /felo-superagent."
+---
+
+# Felo SuperAgent Skill
+
+## When to Use
+
+Trigger this skill for:
+
+- **SuperAgent 对话**：需要与 Felo SuperAgent 进行 AI 对话、流式输出
+- **LiveDoc 集成**：希望回答与 LiveDoc 关联、可追溯资源
+- **连续对话**：在已有会话/文档上继续提问（传入 `live_doc_short_id`）
+- **多轮对话**：需要 thread_short_id / live_doc_short_id 以便后续查询会话详情或 LiveDoc 资源
+
+**Trigger words / 触发词：**
+
+- 简体中文：SuperAgent、超级助手、流式对话、LiveDoc、连续对话
+- English: superagent, super agent, stream chat, livedoc, conversation
+- **Explicit commands:** `/felo-superagent`, "use felo superagent", "felo superagent"
+
+**Do NOT use for:**
+
+- 简单单次问答、实时信息查询（优先用 `felo-search`）
+- 仅需抓取网页内容（用 `felo-web-fetch`）
+- 仅需生成 PPT（用 `felo-slides`）
+
+## Setup
+
+### 1. Get API Key
+
+1. Visit [felo.ai](https://felo.ai) and log in (or register)
+2. Click your avatar (top right) → **Settings**
+3. Open **API Keys** tab → Create and copy your API key
+
+### 2. Configure
+
+Set the `FELO_API_KEY` environment variable:
+
+**Linux/macOS:**
+
+```bash
+export FELO_API_KEY="your-api-key-here"
+```
+
+**Windows (PowerShell):**
+
+```powershell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+**Windows (CMD):**
+
+```cmd
+set FELO_API_KEY=your-api-key-here
+```
+
+## How to Execute
+
+Use the Bash tool and follow this workflow.
+
+### Step 1: Check API Key
+
+```bash
+if [ -z "$FELO_API_KEY" ]; then
+  echo "ERROR: FELO_API_KEY not set"
+  exit 1
+fi
+```
+
+If not set, stop and show the user the setup instructions above.
+
+### Step 2: Run Node Script
+
+From the project root (or ensure script path is correct):
+
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "USER_QUERY_HERE" \
+  --timeout 60
+```
+
+Optional:
+
+- **Reuse LiveDoc (连续对话):** `--live-doc-id "PvyKouzJirXjFdst4uKRK3"`
+- **Language:** `--accept-language zh` or `--accept-language en`
+- **JSON output:** `--json` (includes thread_short_id, live_doc_short_id, full answer)
+- **Verbose:** `--verbose` (logs stream connection to stderr)
+
+Example with options:
+
+```bash
+node felo-superAgent/scripts/run_superagent.mjs \
+  --query "What is the latest news about AI?" \
+  --accept-language en \
+  --timeout 90 \
+  --json
+```
+
+### Step 3: Parse and Present
+
+- **Default:** script prints the full answer text (from SSE `message` events) to stdout.
+- **With `--json`:** script prints one JSON object with `answer`, `thread_short_id`, `live_doc_short_id`, etc.
+
+Present to the user in this format:
+
+```markdown
+## SuperAgent Answer
+
+[Full answer text from stream]
+
+## Metadata (optional, when using --json)
+
+- Thread ID: <thread_short_id>
+- LiveDoc ID: <live_doc_short_id>
+```
+
+If the user asked for conversation detail or LiveDoc resources, you can call the REST APIs (see API Reference below) with `thread_short_id` / `live_doc_short_id`.
+
+## API Workflow (Reference)
+
+1. **POST** `/v2/conversations` → get `stream_key`, `thread_short_id`, `live_doc_short_id`
+2. **GET** `/v2/conversations/stream/{stream_key}` → consume SSE until `done` or `error`
+3. Optionally: **GET** `/v2/conversations/{thread_short_id}` → conversation detail
+4. Optionally: **GET** `/v2/livedocs` → list LiveDocs
+5. Optionally: **GET** `/v2/livedocs/{live_doc_short_id}/resources` → list resources
+
+Base URL: `https://openapi.felo.ai` (override with `FELO_API_BASE` if needed).
+
+## Error Handling
+
+| Code                                   | HTTP | Description              |
+| -------------------------------------- | ---- | ------------------------ |
+| INVALID_API_KEY                        | 401  | API Key 无效或已撤销     |
+| SUPER_AGENT_CONVERSATION_CREATE_FAILED | 502  | 创建会话失败（下游错误） |
+| SUPER_AGENT_CONVERSATION_QUERY_FAILED  | 502  | 查询会话详情失败         |
+| SUPER_AGENT_LIVEDOC_LIST_FAILED        | 502  | 列举 LiveDocs 失败       |
+| SUPER_AGENT_LIVEDOC_RESOURCES_FAILED   | 502  | 列举 LiveDoc 资源失败    |
+
+SSE stream may send:
+
+- `event: error` with `data: {"message": "..."}` — treat as failure and show message.
+
+If `FELO_API_KEY` is not set, show:
+
+```
+❌ Felo API Key 未配置
+
+请设置环境变量 FELO_API_KEY：
+1. 在 https://felo.ai 获取 API Key（Settings → API Keys）
+2. 设置后重启 Claude Code 或重新加载环境
+```
+
+## Important Notes
+
+- Execute this skill when the user clearly wants SuperAgent / 流式对话 / LiveDoc 能力。
+- After create, connect to the stream **immediately** — `stream_key` 有效期有限。
+- Use the bundled Node script to consume SSE; do not assume `jq` or other tools for parsing SSE.
+- Same API key as other Felo skills (`FELO_API_KEY`).
+
+## References
+
+- [SuperAgent API (Felo Open Platform)](https://openapi.felo.ai/docs/api-reference/v2/superagent.html)
+- [Felo Open Platform](https://openapi.felo.ai/docs/)

package/felo-web-fetch/README.md

@@ -0,0 +1,127 @@
+# Felo Web Fetch Skill for Claude Code
+
+Extract structured webpage content from URLs with the Felo Web Extract API.
+
+## Features
+
+- URL content extraction (required)
+- Output format: `html`, `markdown`, `text`
+- Crawl mode: `fast`, `fine`
+- CSS selector extraction (`target_selector`)
+- Advanced options: cookies, user-agent, timeout, readability and link/image summary flags
+- Spinner progress indicator during fetch
+
+## Quick Start
+
+### 1) Install the skill
+
+```bash
+npx @claude/skills add felo-web-fetch
+```
+
+Or install manually from this repository:
+
+```bash
+# Linux/macOS
+cp -r felo-web-fetch ~/.claude/skills/
+
+# Windows (PowerShell)
+Copy-Item -Recurse felo-web-fetch "$env:USERPROFILE\.claude\skills\"
+```
+
+### 2) Configure API key
+
+Create API key at [felo.ai](https://felo.ai) -> Settings -> API Keys, then set:
+
+```bash
+# Linux/macOS
+export FELO_API_KEY="your-api-key-here"
+```
+
+```powershell
+# Windows PowerShell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+### 3) Trigger the skill
+
+- Intent trigger: "Extract this article as markdown"
+- Explicit trigger: `/felo-web-fetch https://example.com/article`
+
+## Using the packaged CLI (`felo web-fetch`)
+
+After `npm install -g felo-ai`, you can run:
+
+```bash
+felo web-fetch --url "https://example.com"
+```
+
+**All parameters (how to pass)**
+
+| Parameter                       | Option                | Example                                   |
+| ------------------------------- | --------------------- | ----------------------------------------- |
+| URL (required)                  | `-u`, `--url`         | `--url "https://example.com"`             |
+| Output format                   | `-f`, `--format`      | `--format text`, `-f markdown`, `-f html` |
+| Target element (CSS selector)   | `--target-selector`   | `--target-selector "article.main"`        |
+| Wait for selector               | `--wait-for-selector` | `--wait-for-selector ".content"`          |
+| Readability (main content only) | `--readability`       | `--readability`                           |
+| Crawl mode                      | `--crawl-mode`        | `--crawl-mode fine` (default: `fast`)     |
+| Timeout (seconds)               | `-t`, `--timeout`     | `--timeout 120`, `-t 90`                  |
+| Full JSON response              | `-j`, `--json`        | `-j` or `--json`                          |
+
+**Examples with multiple options**
+
+```bash
+felo web-fetch -u "https://example.com" -f text --readability
+felo web-fetch --url "https://example.com" --target-selector "#content" --format markdown --timeout 90
+felo web-fetch --url "https://example.com" --wait-for-selector "main" --readability -j
+```
+
+## Script Usage
+
+The skill uses:
+
+```bash
+node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com"
+```
+
+Common examples:
+
+```bash
+node felo-web-fetch/scripts/run_web_fetch.mjs \
+  --url "https://example.com/post" \
+  --output-format markdown \
+  --crawl-mode fine
+```
+
+```bash
+node felo-web-fetch/scripts/run_web_fetch.mjs \
+  --url "https://example.com" \
+  --target-selector "article.main" \
+  --output-format text \
+  --user-agent "Mozilla/5.0" \
+  --request-timeout-ms 20000
+```
+
+```bash
+node felo-web-fetch/scripts/run_web_fetch.mjs \
+  --url "https://example.com/private" \
+  --cookie "session_id=abc123" \
+  --with-readability true \
+  --json
+```
+
+## Error Handling
+
+- Missing key: `FELO_API_KEY not set`
+- Invalid key: `INVALID_API_KEY`
+- Invalid params / URL: `HTTP 400`
+- Upstream extraction failure: `WEB_EXTRACT_FAILED` (`HTTP 500/502`)
+
+## Links
+
+- [Web Extract API](https://openapi.felo.ai/docs/api-reference/v2/web-extract.html)
+- [Felo Open Platform](https://openapi.felo.ai/docs/)
+- [Get API Key](https://felo.ai)
+
+See [SKILL.md](SKILL.md) for full agent instructions and API parameters.

package/felo-web-fetch/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: felo-web-fetch
+description: "Extract webpage content with Felo Web Extract API. Use for turning URLs into html/markdown/text, selecting specific page areas with CSS selectors, and controlling extraction options like crawl mode, cookies, user-agent, and timeout."
+---
+
+# Felo Web Fetch Skill
+
+## When to Use
+
+Trigger this skill when users want to extract or convert webpage content from a URL:
+
+- Fetch or scrape content from a webpage URL
+- Convert webpage content to `html`, `markdown`, or `text`
+- Extract specific blocks using CSS selector
+- Get article/main text from a link with readability mode
+- Tune extraction behavior with crawl mode (`fast`/`fine`)
+- Pass request details such as cookies, user-agent, timeout
+
+Trigger keywords (examples):
+
+- fetch webpage, scrape URL, fetch page content, web fetch, url to markdown
+- Explicit: `/felo-web-fetch`, "use felo web fetch", "extract this URL with felo"
+- Same intent in other languages (e.g. 网页抓取, 提取网页内容) also triggers this skill
+
+Do NOT use this skill for:
+
+- Real-time Q&A search summaries (use `felo-search`)
+- Slide generation tasks (use `felo-slides`)
+- Local file parsing in current workspace
+
+## Setup
+
+### 1. Get API key
+
+1. Visit [felo.ai](https://felo.ai)
+2. Open Settings -> API Keys
+3. Create and copy your API key
+
+### 2. Configure environment variable
+
+Linux/macOS:
+```bash
+export FELO_API_KEY="your-api-key-here"
+```
+
+Windows PowerShell:
+```powershell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+## How to Execute
+
+### Option A: Use the bundled script or packaged CLI
+
+**Script** (from repo):
+
+```bash
+node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article" [options]
+```
+
+**Packaged CLI** (after `npm install -g felo-ai`): same options, with short forms allowed:
+
+```bash
+felo web-fetch -u "https://example.com" [options]
+# Short forms: -u (url), -f (format), -t (timeout, seconds), -j (json)
+```
+
+Required parameter:
+- `--url`
+
+Core optional parameters:
+- `--output-format html|markdown|text`
+- `--crawl-mode fast|fine`
+- `--target-selector "article.main-content"`
+- `--wait-for-selector ".content-ready"`
+
+Other key optional parameters:
+- `--cookie "session_id=xxx"` (repeatable)
+- `--set-cookies-json '[{"name":"sid","value":"xxx","domain":"example.com"}]'`
+- `--user-agent "Mozilla/5.0 ..."`
+- `--timeout 60` (HTTP request timeout in seconds)
+- `--request-timeout-ms 15000` (API payload `timeout` in ms)
+- `--with-readability true`
+- `--with-links-summary true`
+- `--with-images-summary true`
+- `--with-images-readability true`
+- `--with-images true`
+- `--with-links true`
+- `--ignore-empty-text-image true`
+- `--with-cache false`
+- `--with-stypes true`
+- `--json` (print full JSON response)
+
+### How to write instructions (target_selector + output_format)
+
+When the user wants a **specific part** of the page or a **specific output format**, phrase the command like this:
+
+- **Output format**: "Fetch as **text**" / "Get **markdown**" / "Return **html**" → use `--output-format text`, `--output-format markdown`, or `--output-format html`.
+- **Target one element**: "Only the **main article**" / "Just the **content inside** `#main`" / "Fetch only **article.main-content**" → use `--target-selector "article.main"` or the selector they give.
+
+Examples:
+
+```bash
+# Basic: fetch as Markdown
+node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --output-format markdown
+
+# Article-style with readability
+node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article" --with-readability true --output-format markdown
+
+# Only the element matching a CSS selector
+node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --target-selector "article.main" --output-format markdown
+
+# With cookies and custom user-agent
+node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/private" --cookie "session_id=abc123" --with-readability true --json
+
+# Full JSON response
+node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --output-format text --json
+```
+
+### Option B: Call API with curl
+
+```bash
+curl -X POST "https://openapi.felo.ai/v2/web/extract" \
+  -H "Authorization: Bearer $FELO_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com", "output_format": "markdown", "with_readability": true}'
+```
+
+## API Reference (summary)
+
+- **Endpoint**: `POST /v2/web/extract`
+- **Base URL**: `https://openapi.felo.ai`. Override with `FELO_API_BASE` env if needed.
+- **Auth**: `Authorization: Bearer YOUR_API_KEY`
+
+### Request body (JSON)
+
+| Parameter | Type | Required | Default | Description |
+|-----------|------|----------|---------|-------------|
+| url | string | Yes | - | Webpage URL to fetch |
+| crawl_mode | string | No | fast | `fast` or `fine` |
+| output_format | string | No | html | `html`, `text`, `markdown` |
+| with_readability | boolean | No | - | Use readability (main content) |
+| with_links_summary | boolean | No | - | Include links summary |
+| with_images_summary | boolean | No | - | Include images summary |
+| target_selector | string | No | - | CSS selector for target element |
+| wait_for_selector | string | No | - | Wait for selector before fetch |
+| timeout | integer | No | - | Timeout in milliseconds |
+| with_cache | boolean | No | true | Use cache |
+| set_cookies | array | No | - | Cookie entries |
+| user_agent | string | No | - | Custom user-agent |
+
+### Response
+
+Success (200):
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "content": { ... }
+  }
+}
+```
+
+Fetched content is in `data.content`; structure depends on `output_format`.
+
+### Error codes
+
+| HTTP | Code | Description |
+|------|------|-------------|
+| 400 | - | Parameter validation failed |
+| 401 | INVALID_API_KEY | API key invalid or revoked |
+| 500/502 | WEB_EXTRACT_FAILED | Fetch failed (server or page error) |
+
+## Output Format
+
+- Default output is extracted content only (for direct use or piping).
+- If response content is not a string, script prints JSON.
+- Use `--json` when user needs metadata and full response object.
+
+Error response format:
+
+```markdown
+## Web Fetch Failed
+- Message: <error message>
+- Suggested Action: verify URL/parameters and retry
+```
+
+## Important Notes
+
+- Always require URL before running.
+- Validate enum values:
+  - `output_format`: `html`, `markdown`, `text`
+  - `crawl_mode`: `fast`, `fine`
+- Use `--target-selector` when users only want a specific part of the page.
+- Use `--request-timeout-ms` for page rendering/extraction wait, and `--timeout` for local HTTP timeout.
+- For long articles or slow sites, consider increasing `--timeout`.
+- API may cache results; use `--with-cache false` only when fresh content is required.
+
+## References
+
+- [Web Extract API](https://openapi.felo.ai/docs/api-reference/v2/web-extract.html)
+- [Felo Open Platform](https://openapi.felo.ai/docs/)