felo-ai 0.2.6 → 0.2.9

package/felo-slides/scripts/run_ppt_task.mjs

@@ -1,251 +1,251 @@
-#!/usr/bin/env node
-
-const DEFAULT_API_BASE = 'https://openapi.felo.ai';
-const DEFAULT_INTERVAL_SEC = 10;
-const DEFAULT_MAX_WAIT_SEC = 1800;
-const DEFAULT_TIMEOUT_SEC = 60;
-
-function usage() {
-  console.error(
-    [
-      'Usage:',
-      '  node felo-slides/scripts/run_ppt_task.mjs --query "your prompt" [options]',
-      '',
-      'Options:',
-      '  --query <text>        PPT prompt (required)',
-      '  --interval <seconds>  Poll interval, default 10',
-      '  --max-wait <seconds>  Max wait time, default 1800',
-      '  --timeout <seconds>   Request timeout, default 60',
-      '  --json                Print JSON output',
-      '  --verbose             Print polling status to stderr',
-      '  --help                Show this help',
-    ].join('\n')
-  );
-}
-
-function parseArgs(argv) {
-  const out = {
-    query: '',
-    intervalSec: DEFAULT_INTERVAL_SEC,
-    maxWaitSec: DEFAULT_MAX_WAIT_SEC,
-    timeoutSec: DEFAULT_TIMEOUT_SEC,
-    json: false,
-    verbose: false,
-  };
-
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i];
-    if (a === '--help' || a === '-h') {
-      out.help = true;
-    } else if (a === '--json') {
-      out.json = true;
-    } else if (a === '--verbose' || a === '-v') {
-      out.verbose = true;
-    } else if (a === '--query') {
-      out.query = argv[i + 1] ?? '';
-      i += 1;
-    } else if (a === '--interval') {
-      out.intervalSec = Number.parseInt(argv[i + 1] ?? '', 10);
-      i += 1;
-    } else if (a === '--max-wait') {
-      out.maxWaitSec = Number.parseInt(argv[i + 1] ?? '', 10);
-      i += 1;
-    } else if (a === '--timeout') {
-      out.timeoutSec = Number.parseInt(argv[i + 1] ?? '', 10);
-      i += 1;
-    } else if (!a.startsWith('-') && !out.query) {
-      out.query = a;
-    }
-  }
-
-  if (!Number.isFinite(out.intervalSec) || out.intervalSec <= 0) out.intervalSec = DEFAULT_INTERVAL_SEC;
-  if (!Number.isFinite(out.maxWaitSec) || out.maxWaitSec <= 0) out.maxWaitSec = DEFAULT_MAX_WAIT_SEC;
-  if (!Number.isFinite(out.timeoutSec) || out.timeoutSec <= 0) out.timeoutSec = DEFAULT_TIMEOUT_SEC;
-  return out;
-}
-
-function normalizeStatus(v) {
-  return String(v ?? '').trim().toUpperCase();
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-function getMessage(payload) {
-  return (
-    payload?.message ||
-    payload?.error ||
-    payload?.msg ||
-    payload?.code ||
-    'Unknown error'
-  );
-}
-
-function isApiError(payload) {
-  const status = payload?.status;
-  const code = payload?.code;
-  if (typeof status === 'string' && status.toLowerCase() === 'error') return true;
-  if (typeof code === 'string' && code && code.toUpperCase() !== 'OK') return true;
-  return false;
-}
-
-async function fetchJson(url, init, timeoutMs) {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    const res = await fetch(url, { ...init, signal: controller.signal });
-    let body = {};
-    try {
-      body = await res.json();
-    } catch {
-      body = {};
-    }
-
-    if (!res.ok) {
-      throw new Error(`HTTP ${res.status}: ${getMessage(body)}`);
-    }
-    if (isApiError(body)) {
-      throw new Error(getMessage(body));
-    }
-    return body;
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-function extractTaskUrls(historicalData, createData) {
-  const pptUrl = historicalData?.ppt_url || '';
-  const liveDocUrl =
-    historicalData?.live_doc_url ||
-    (historicalData?.live_doc_short_id || historicalData?.livedoc_short_id || createData?.livedoc_short_id
-      ? `https://felo.ai/livedoc/${historicalData?.live_doc_short_id || historicalData?.livedoc_short_id || createData?.livedoc_short_id}`
-      : '');
-  return {
-    pptUrl,
-    liveDocUrl,
-    displayUrl: pptUrl || liveDocUrl,
-  };
-}
-
-async function createTask(apiKey, apiBase, query, timeoutMs) {
-  const payload = await fetchJson(
-    `${apiBase}/v2/ppts`,
-    {
-      method: 'POST',
-      headers: {
-        Accept: 'application/json',
-        Authorization: `Bearer ${apiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({ query }),
-    },
-    timeoutMs
-  );
-  const data = payload?.data ?? {};
-  if (!data.task_id) {
-    throw new Error('Unexpected response: missing task_id');
-  }
-  return data;
-}
-
-async function queryHistorical(apiKey, apiBase, taskId, timeoutMs) {
-  const payload = await fetchJson(
-    `${apiBase}/v2/tasks/${encodeURIComponent(taskId)}/historical`,
-    {
-      method: 'GET',
-      headers: {
-        Accept: 'application/json',
-        Authorization: `Bearer ${apiKey}`,
-      },
-    },
-    timeoutMs
-  );
-  return payload?.data ?? {};
-}
-
-async function main() {
-  const args = parseArgs(process.argv.slice(2));
-  if (args.help) {
-    usage();
-    process.exit(0);
-  }
-  if (!args.query) {
-    usage();
-    process.exit(1);
-  }
-
-  const apiKey = process.env.FELO_API_KEY?.trim();
-  if (!apiKey) {
-    console.error('ERROR: FELO_API_KEY not set');
-    process.exit(1);
-  }
-
-  const apiBase = (process.env.FELO_API_BASE?.trim() || DEFAULT_API_BASE).replace(/\/$/, '');
-  const timeoutMs = args.timeoutSec * 1000;
-  const intervalMs = args.intervalSec * 1000;
-  const maxWaitMs = args.maxWaitSec * 1000;
-
-  const createData = await createTask(apiKey, apiBase, args.query, timeoutMs);
-  const taskId = createData.task_id;
-  if (args.verbose) {
-    console.error(`Task ID: ${taskId}`);
-  }
-
-  const startAt = Date.now();
-  let lastStatus = '';
-
-  while (Date.now() - startAt <= maxWaitMs) {
-    const historicalData = await queryHistorical(apiKey, apiBase, taskId, timeoutMs);
-    const taskStatus = normalizeStatus(historicalData.task_status || historicalData.status);
-    const urls = extractTaskUrls(historicalData, createData);
-    lastStatus = taskStatus || 'UNKNOWN';
-
-    if (args.verbose) {
-      const elapsedSec = Math.floor((Date.now() - startAt) / 1000);
-      console.error(`[${elapsedSec}s] Status: ${lastStatus}`);
-    }
-
-    if (taskStatus === 'COMPLETED' || taskStatus === 'SUCCESS') {
-      if (!urls.displayUrl) {
-        throw new Error('Task completed but no ppt_url/live_doc_url is available');
-      }
-      if (args.json) {
-        console.log(
-          JSON.stringify(
-            {
-              status: 'ok',
-              data: {
-                task_id: taskId,
-                task_status: taskStatus,
-                ppt_url: urls.pptUrl || null,
-                live_doc_url: urls.liveDocUrl || null,
-                livedoc_short_id: createData.livedoc_short_id ?? historicalData.live_doc_short_id ?? historicalData.livedoc_short_id ?? null,
-                ppt_business_id: createData.ppt_business_id ?? null,
-              },
-            },
-            null,
-            2
-          )
-        );
-      } else {
-        console.log(urls.displayUrl);
-      }
-      return;
-    }
-
-    if (taskStatus === 'FAILED' || taskStatus === 'ERROR') {
-      throw new Error(`Task finished with status: ${taskStatus}`);
-    }
-
-    await sleep(intervalMs);
-  }
-
-  throw new Error(`Timed out after ${args.maxWaitSec}s. Last status: ${lastStatus || 'UNKNOWN'}`);
-}
-
-main().catch((err) => {
-  console.error(`ERROR: ${err?.message || err}`);
-  process.exit(1);
-});
-
+#!/usr/bin/env node
+
+const DEFAULT_API_BASE = 'https://openapi.felo.ai';
+const DEFAULT_INTERVAL_SEC = 10;
+const DEFAULT_MAX_WAIT_SEC = 1800;
+const DEFAULT_TIMEOUT_SEC = 60;
+
+function usage() {
+  console.error(
+    [
+      'Usage:',
+      '  node felo-slides/scripts/run_ppt_task.mjs --query "your prompt" [options]',
+      '',
+      'Options:',
+      '  --query <text>        PPT prompt (required)',
+      '  --interval <seconds>  Poll interval, default 10',
+      '  --max-wait <seconds>  Max wait time, default 1800',
+      '  --timeout <seconds>   Request timeout, default 60',
+      '  --json                Print JSON output',
+      '  --verbose             Print polling status to stderr',
+      '  --help                Show this help',
+    ].join('\n')
+  );
+}
+
+function parseArgs(argv) {
+  const out = {
+    query: '',
+    intervalSec: DEFAULT_INTERVAL_SEC,
+    maxWaitSec: DEFAULT_MAX_WAIT_SEC,
+    timeoutSec: DEFAULT_TIMEOUT_SEC,
+    json: false,
+    verbose: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--help' || a === '-h') {
+      out.help = true;
+    } else if (a === '--json') {
+      out.json = true;
+    } else if (a === '--verbose' || a === '-v') {
+      out.verbose = true;
+    } else if (a === '--query') {
+      out.query = argv[i + 1] ?? '';
+      i += 1;
+    } else if (a === '--interval') {
+      out.intervalSec = Number.parseInt(argv[i + 1] ?? '', 10);
+      i += 1;
+    } else if (a === '--max-wait') {
+      out.maxWaitSec = Number.parseInt(argv[i + 1] ?? '', 10);
+      i += 1;
+    } else if (a === '--timeout') {
+      out.timeoutSec = Number.parseInt(argv[i + 1] ?? '', 10);
+      i += 1;
+    } else if (!a.startsWith('-') && !out.query) {
+      out.query = a;
+    }
+  }
+
+  if (!Number.isFinite(out.intervalSec) || out.intervalSec <= 0) out.intervalSec = DEFAULT_INTERVAL_SEC;
+  if (!Number.isFinite(out.maxWaitSec) || out.maxWaitSec <= 0) out.maxWaitSec = DEFAULT_MAX_WAIT_SEC;
+  if (!Number.isFinite(out.timeoutSec) || out.timeoutSec <= 0) out.timeoutSec = DEFAULT_TIMEOUT_SEC;
+  return out;
+}
+
+function normalizeStatus(v) {
+  return String(v ?? '').trim().toUpperCase();
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function getMessage(payload) {
+  return (
+    payload?.message ||
+    payload?.error ||
+    payload?.msg ||
+    payload?.code ||
+    'Unknown error'
+  );
+}
+
+function isApiError(payload) {
+  const status = payload?.status;
+  const code = payload?.code;
+  if (typeof status === 'string' && status.toLowerCase() === 'error') return true;
+  if (typeof code === 'string' && code && code.toUpperCase() !== 'OK') return true;
+  return false;
+}
+
+async function fetchJson(url, init, timeoutMs) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, { ...init, signal: controller.signal });
+    let body = {};
+    try {
+      body = await res.json();
+    } catch {
+      body = {};
+    }
+
+    if (!res.ok) {
+      throw new Error(`HTTP ${res.status}: ${getMessage(body)}`);
+    }
+    if (isApiError(body)) {
+      throw new Error(getMessage(body));
+    }
+    return body;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function extractTaskUrls(historicalData, createData) {
+  const pptUrl = historicalData?.ppt_url || '';
+  const liveDocUrl =
+    historicalData?.live_doc_url ||
+    (historicalData?.live_doc_short_id || historicalData?.livedoc_short_id || createData?.livedoc_short_id
+      ? `https://felo.ai/livedoc/${historicalData?.live_doc_short_id || historicalData?.livedoc_short_id || createData?.livedoc_short_id}`
+      : '');
+  return {
+    pptUrl,
+    liveDocUrl,
+    displayUrl: pptUrl || liveDocUrl,
+  };
+}
+
+async function createTask(apiKey, apiBase, query, timeoutMs) {
+  const payload = await fetchJson(
+    `${apiBase}/v2/ppts`,
+    {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({ query }),
+    },
+    timeoutMs
+  );
+  const data = payload?.data ?? {};
+  if (!data.task_id) {
+    throw new Error('Unexpected response: missing task_id');
+  }
+  return data;
+}
+
+async function queryHistorical(apiKey, apiBase, taskId, timeoutMs) {
+  const payload = await fetchJson(
+    `${apiBase}/v2/tasks/${encodeURIComponent(taskId)}/historical`,
+    {
+      method: 'GET',
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${apiKey}`,
+      },
+    },
+    timeoutMs
+  );
+  return payload?.data ?? {};
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) {
+    usage();
+    process.exit(0);
+  }
+  if (!args.query) {
+    usage();
+    process.exit(1);
+  }
+
+  const apiKey = process.env.FELO_API_KEY?.trim();
+  if (!apiKey) {
+    console.error('ERROR: FELO_API_KEY not set');
+    process.exit(1);
+  }
+
+  const apiBase = (process.env.FELO_API_BASE?.trim() || DEFAULT_API_BASE).replace(/\/$/, '');
+  const timeoutMs = args.timeoutSec * 1000;
+  const intervalMs = args.intervalSec * 1000;
+  const maxWaitMs = args.maxWaitSec * 1000;
+
+  const createData = await createTask(apiKey, apiBase, args.query, timeoutMs);
+  const taskId = createData.task_id;
+  if (args.verbose) {
+    console.error(`Task ID: ${taskId}`);
+  }
+
+  const startAt = Date.now();
+  let lastStatus = '';
+
+  while (Date.now() - startAt <= maxWaitMs) {
+    const historicalData = await queryHistorical(apiKey, apiBase, taskId, timeoutMs);
+    const taskStatus = normalizeStatus(historicalData.task_status || historicalData.status);
+    const urls = extractTaskUrls(historicalData, createData);
+    lastStatus = taskStatus || 'UNKNOWN';
+
+    if (args.verbose) {
+      const elapsedSec = Math.floor((Date.now() - startAt) / 1000);
+      console.error(`[${elapsedSec}s] Status: ${lastStatus}`);
+    }
+
+    if (taskStatus === 'COMPLETED' || taskStatus === 'SUCCESS') {
+      if (!urls.displayUrl) {
+        throw new Error('Task completed but no ppt_url/live_doc_url is available');
+      }
+      if (args.json) {
+        console.log(
+          JSON.stringify(
+            {
+              status: 'ok',
+              data: {
+                task_id: taskId,
+                task_status: taskStatus,
+                ppt_url: urls.pptUrl || null,
+                live_doc_url: urls.liveDocUrl || null,
+                livedoc_short_id: createData.livedoc_short_id ?? historicalData.live_doc_short_id ?? historicalData.livedoc_short_id ?? null,
+                ppt_business_id: createData.ppt_business_id ?? null,
+              },
+            },
+            null,
+            2
+          )
+        );
+      } else {
+        console.log(urls.displayUrl);
+      }
+      return;
+    }
+
+    if (taskStatus === 'FAILED' || taskStatus === 'ERROR') {
+      throw new Error(`Task finished with status: ${taskStatus}`);
+    }
+
+    await sleep(intervalMs);
+  }
+
+  throw new Error(`Timed out after ${args.maxWaitSec}s. Last status: ${lastStatus || 'UNKNOWN'}`);
+}
+
+main().catch((err) => {
+  console.error(`ERROR: ${err?.message || err}`);
+  process.exit(1);
+});
+

package/felo-superAgent/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felo SuperAgent Skill Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/felo-superAgent/README.md

@@ -0,0 +1,125 @@
+# Felo SuperAgent Skill for Claude Code
+
+**AI 对话与流式输出，支持 LiveDoc 与连续会话。**
+
+通过 Felo Open Platform 的 SuperAgent API，在 Claude Code 中发起与 SuperAgent 的对话、接收 SSE 流式回复，并可关联 LiveDoc、查询会话详情与资源。
+
+---
+
+## 功能
+
+- **流式对话**：创建会话后通过 SSE 实时接收 AI 回复
+- **LiveDoc 关联**：每次会话对应一个 LiveDoc，可后续查看资源
+- **连续对话**：通过 `live_doc_short_id` 在已有 LiveDoc 上继续提问
+- **多语言**：支持 `accept_language`（如 zh / en）
+
+**适用场景：**
+
+- 需要 SuperAgent 流式回答
+- 需要与 LiveDoc 关联、可追溯资源的对话
+- 多轮/连续对话（复用同一 LiveDoc）
+
+**不适用：**
+
+- 仅需单次实时信息检索 → 使用 `felo-search`
+- 仅需抓取网页正文 → 使用 `felo-web-fetch`
+- 仅需生成 PPT → 使用 `felo-slides`
+
+---
+
+## 快速开始
+
+### 1. 安装
+
+```bash
+npx @claude/skills add felo-superAgent
+```
+
+（若为本地 skill，确保 Cursor/Claude Code 已配置该 skill 路径。）
+
+### 2. 配置 API Key
+
+与其它 Felo skills 相同，使用同一 API Key：
+
+1. 打开 [felo.ai](https://felo.ai) 登录
+2. 头像 → **Settings** → **API Keys** → 创建并复制 Key
+3. 设置环境变量：
+
+```bash
+# Linux/macOS
+export FELO_API_KEY="your-api-key-here"
+
+# Windows PowerShell
+$env:FELO_API_KEY="your-api-key-here"
+```
+
+### 3. 使用方式
+
+**在对话中触发：**
+
+- 明确指令：`/felo-superagent`、"use felo super agent"
+- 描述意图：SuperAgent 对话、流式对话、LiveDoc 对话、连续对话
+
+**命令行直接跑脚本：**
+
+```bash
+node felo-superAgent/scripts/run_superagent.mjs --query "What is the latest news about AI?"
+```
+
+输出为流式汇总后的完整回答正文。加 `--json` 可得到包含 `thread_short_id`、`live_doc_short_id` 的 JSON。
+
+---
+
+## 脚本参数
+
+| 参数                       | 说明                                                       |
+| -------------------------- | ---------------------------------------------------------- |
+| `--query <text>`           | 用户问题（必填，1–2000 字符）                              |
+| `--live-doc-id <id>`       | 复用已有 LiveDoc short_id（连续对话）                      |
+| `--accept-language <lang>` | 语言偏好，如 zh / en                                       |
+| `--timeout <seconds>`      | 请求/流超时，默认 60                                       |
+| `--json`                   | 输出 JSON（含 answer、thread_short_id、live_doc_short_id） |
+| `--verbose`                | 将流连接信息打到 stderr                                    |
+| `--help`                   | 显示帮助                                                   |
+
+---
+
+## 输出格式
+
+**默认（纯文本）：**  
+脚本 stdout 为完整回答内容（由 SSE `message` 事件拼接）。
+
+**`--json`：**  
+单行 JSON 对象，例如：
+
+```json
+{
+  "status": "ok",
+  "data": {
+    "answer": "完整回答内容...",
+    "thread_short_id": "TvyKouzJirXjFdst4uKRK3",
+    "live_doc_short_id": "PvyKouzJirXjFdst4uKRK3"
+  }
+}
+```
+
+可用 `thread_short_id` 调用「查询会话详情」接口，用 `live_doc_short_id` 调用「列举 LiveDoc 资源」等接口。
+
+---
+
+## 错误处理
+
+常见错误码参见 [SuperAgent API 文档](https://openapi.felo.ai/docs/api-reference/v2/superagent.html)：
+
+- `INVALID_API_KEY` (401)：Key 无效或已撤销
+- `SUPER_AGENT_CONVERSATION_CREATE_FAILED` (502)：创建会话失败
+- 其它 502：下游服务异常，可重试或联系支持
+
+若未配置 `FELO_API_KEY`，脚本会报错并提示配置方法。
+
+---
+
+## 参考链接
+
+- [SuperAgent API 文档](https://openapi.felo.ai/docs/api-reference/v2/superagent.html)
+- [Felo Open Platform](https://openapi.felo.ai/docs/)