felo-ai 0.2.7 → 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

@@ -1,78 +1,127 @@
-# Felo Web Fetch Skill
-
-Fetch webpage content from a URL using the [Felo Web Extract API](https://openapi.felo.ai/docs/api-reference/v2/web-extract.html).
-
-## Features
-
-- Fetch content from any URL as **html**, **text**, or **markdown** (`--format`)
-- **Target one element** with a CSS selector (`--target-selector`, e.g. `article.main`, `#content`)
-- Optional **readability** mode for main article content only
-- Crawl modes: `fast` (default) or `fine`
-- Same `FELO_API_KEY` as other Felo skills
-
-## Quick Start
-
-### 1) Configure API key
-
-At [felo.ai](https://felo.ai) -> Settings -> API Keys, create a key, then:
-
-```bash
-# Linux/macOS
-export FELO_API_KEY="your-api-key-here"
-```
-
-```powershell
-# Windows PowerShell
-$env:FELO_API_KEY="your-api-key-here"
-```
-
-### 2) Run fetch
-
-```bash
-# Fetch as Markdown (default)
-node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com/article"
-
-# With readability for clean article text
-node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --readability --format markdown
-
-# Full JSON response
-node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --json
-
-# Only a specific element (CSS selector) and output format
-node felo-web-fetch/scripts/run_web_fetch.mjs --url "https://example.com" --target-selector "article.main" --format markdown
-```
-
-## 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
-```
-
-## When to use (Agent)
-
-Trigger keywords: fetch webpage, scrape URL, fetch page content, url to markdown, `/felo-web-fetch`.
-
-See [SKILL.md](SKILL.md) for full agent instructions and API parameters.
+# 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.