felo-ai 0.2.3 → 0.2.5

package/README.en.md

@@ -21,12 +21,9 @@ Search the web for up-to-date information and get AI-synthesized answers. Ideal
 - **Claude Code**: After installing the skill, it triggers automatically, or type `/felo-ai your question`
 - **Examples**: `felo search "Tokyo weather"`, `felo search "React 19 new features" --verbose`
 
-### Capability 2: Generate PPT
+### Capability 2: Generate PPT (Felo Slides)
 
-Describe a topic in one sentence and Felo generates a slideshow. The job runs in the cloud; when done, you get an **online document link** to open in your browser.
-
-- **Terminal**: `felo slides "your topic or description"`
-- **Examples**: `felo slides "Felo product intro, 3 slides"`, `felo slides "Introduction to React" --poll-timeout 300`
+Terminal: `felo slides "your topic"`. In Claude Code: install `npx @claude/skills add felo-slides`, then `/felo-slides your topic`. You get an online document link when done. Examples: `felo slides "Felo product intro, 3 slides"`, `felo slides "Introduction to React"`.
 
 ---
 
@@ -62,17 +59,39 @@ Get your API key at [felo.ai](https://felo.ai) (Settings → API Keys).
 | `felo config set FELO_API_KEY <key>` | Save API key |
 | `felo config get/list/path/unset` | View / list / path / remove config |
 
+### Examples
+
+**Search**
+
+```bash
+felo search "Tokyo weather"
+felo search "MacBook Air M3 price"
+felo search "React 19 new features" --verbose
+npx felo-ai search "Tokyo weather"
+```
+
+**Slides**
+
+```bash
+felo slides "Felo product intro, 3 slides"
+felo slides "Introduction to React"
+felo slides "Q4 2024 business review, 10 pages" --poll-timeout 300
+npx felo-ai slides "Tokyo travel guide, 5 slides"
+```
+
 ---
 
-## Claude Code Skill
+## Claude Code Skills
 
-Install the skill:
+**Search** — Install and use real-time search:
 
 ```bash
-npx @claude/skills add felo-ai
+npx @claude/skills add felo-search
 ```
 
-After setting `FELO_API_KEY`, ask Claude things like “What’s the weather in Tokyo today?” or “React 19 new features” and search will trigger automatically. PPT generation is available only via the terminal with `felo slides`.
+After setting `FELO_API_KEY`, ask Claude things like “What’s the weather in Tokyo today?” or “React 19 new features”; the search skill triggers automatically (or use `/felo-search your question`).
+
+**Slides (PPT)** — `npx @claude/skills add felo-slides`, then `/felo-slides your topic`. Same `FELO_API_KEY`. [Details →](./felo-slides/README.md)
 
 ---
 

package/README.md

@@ -1,30 +1,27 @@
-# Felo Skills for Claude Code
+# Felo AI CLI
 
-**Ask anything. Get current answers powered by AI.**
+**Ask anything. Get current answers. Generate slides from a prompt.**
 
-Real-time web search powered by Felo AI. Works in Chinese, English, Japanese, and Korean.
+[npm package: **felo-ai**](https://www.npmjs.com/package/felo-ai) — Real-time search and PPT generation from the terminal. Also works as Claude Code skills. Supports Chinese, English, Japanese, and Korean.
 
-[![Setup Time](https://img.shields.io/badge/setup-2%20minutes-blue)]() [![License](https://img.shields.io/badge/license-MIT-green)]()
+[![npm version](https://img.shields.io/npm/v/felo-ai.svg)](https://www.npmjs.com/package/felo-ai) [![License](https://img.shields.io/badge/license-MIT-green)]()
 
 ---
 
-## Felo CLI (Terminal)
-
-Use Felo search from the terminal without opening Claude Code.
-
-### Install
+## Install (CLI)
 
 ```bash
-npm install -g felo-search
+npm install -g felo-ai
 ```
 
-Or run without installing (uses latest published version):
+Run without installing:
 
 ```bash
-npx felo-search search "Tokyo weather"
+npx felo-ai search "Tokyo weather"
+npx felo-ai slides "Introduction to React, 5 slides"
 ```
 
-After install, the command is `felo` (from the package name `felo-search`).
+After install, the command is `felo` (package name: **felo-ai**).
 
 ### Configure API key
 
@@ -53,32 +50,47 @@ Get your API key from [felo.ai](https://felo.ai) (Settings → API Keys). Enviro
 | Command                              | Description                                           |
 | ------------------------------------ | ----------------------------------------------------- |
 | `felo search "<query>"`              | Search for current info (weather, news, prices, etc.) |
+| `felo slides "<prompt>"`             | Generate PPT; returns link when done                 |
 | `felo config set FELO_API_KEY <key>` | Save API key to config                                |
 | `felo config get FELO_API_KEY`       | Print stored key                                      |
 | `felo config list`                   | List config keys                                      |
 | `felo config path`                   | Show config file path                                 |
-| `felo summarize` / `felo translate`  | Planned; use `felo search` for now                    |
 
 ### Examples
 
+**Search**
+
 ```bash
 felo search "Tokyo weather"
 felo search "MacBook Air M3 price"
 felo search "React 19 new features" --verbose
 felo search "Hangzhou tomorrow weather" --json
-npx felo-search search "Tokyo weather"
+npx felo-ai search "Tokyo weather"
+```
+
+**Slides**
+
+```bash
+felo slides "Felo product intro, 3 slides"
+felo slides "Introduction to React"
+felo slides "Q4 2024 business review, 10 pages" --poll-timeout 300
+npx felo-ai slides "Tokyo travel guide, 5 slides"
 ```
 
 ### CLI FAQ
 
 - **Key not found?** Run `felo config set FELO_API_KEY <key>` or set the `FELO_API_KEY` environment variable.
 - **Request timeout?** Use `felo search "query" --timeout 120` (default 60 seconds). 5xx errors are retried automatically with backoff.
+- **Slides taking long?** Use `felo slides "topic" --poll-timeout 300` (default 1200s) to limit wait.
 - **Where is config stored?** Run `felo config path` to see the file (e.g. `~/.felo/config.json`).
-- **Streaming?** Not yet; when the Felo API supports streaming, the CLI can be updated to stream output.
 
 ---
 
-## Quick Start (Claude Code Skill)
+## Claude Code Skills (optional)
+
+This repo also provides **Claude Code** skills. If you use [Claude Code](https://claude.ai/code), you can install search and/or slides as skills so Claude can run them in chat.
+
+### Quick Start (Search skill)
 
 Install the skill:
 
@@ -110,6 +122,8 @@ Ask Claude: "What's the weather in Tokyo today?"
 
 **You're done!** The skill triggers automatically for any question needing current information.
 
+**Felo Slides (PPT):** In terminal run `felo slides "your topic"`. In Claude Code install with `npx @claude/skills add felo-slides`, then use `/felo-slides your topic`. See [felo-slides](./felo-slides/README.md).
+
 ---
 
 ## Usage Examples
@@ -284,6 +298,10 @@ Real-time web search with AI-generated answers.
 
 **[View skill documentation →](./felo-search/)**
 
+### felo-slides
+
+Generate PPT: in terminal use `felo slides "your topic"`, in Claude Code use `/felo-slides your topic`. **[View skill documentation →](./felo-slides/)**
+
 ---
 
 ## Contributing
@@ -302,6 +320,7 @@ Run CLI tests: `npm test`
 
 ## Links
 
+- **[npm: felo-ai](https://www.npmjs.com/package/felo-ai)** — CLI package
 - **[Felo Open Platform](https://openapi.felo.ai/docs/)** — Get your API key
 - **[API Documentation](https://openapi.felo.ai/docs/api-reference/v2/chat.html)** — API reference
 - **[Claude Code](https://claude.ai/code)** — AI assistant CLI
@@ -321,7 +340,7 @@ Run CLI tests: `npm test`
 
 ## License
 
-MIT License — see [LICENSE](./felo-search/LICENSE) for details.
+MIT — see [LICENSE](./felo-search/LICENSE) in the repo for details.
 
 ---
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "felo-ai",
-  "version": "0.2.3",
-  "description": "Felo AI CLI - real-time search from the terminal",
+  "version": "0.2.5",
+  "description": "Felo AI CLI - real-time search and PPT generation from the terminal",
   "type": "module",
   "main": "src/cli.js",
   "bin": {

package/src/cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { createRequire } from 'module';
 import { Command } from 'commander';

package/src/slides.js

@@ -1,22 +1,26 @@
-import { getApiKey, fetchWithTimeoutAndRetry, NO_KEY_MESSAGE } from './search.js';
+import {
+  getApiKey,
+  fetchWithTimeoutAndRetry,
+  NO_KEY_MESSAGE,
+} from "./search.js";
 
-const DEFAULT_API_BASE = 'https://openapi.felo.ai';
+const DEFAULT_API_BASE = "https://openapi.felo.ai";
 const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 const POLL_INTERVAL_MS = 10_000;
 const MAX_POLL_TIMEOUT_MS = 1_200_000; // 20 minutes max wait
 
-const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 const STATUS_LINE_PAD = 50;
 
 /** API base URL (default https://openapi.felo.ai). Override via FELO_API_BASE env or config if needed. */
 async function getApiBase() {
   let base = process.env.FELO_API_BASE?.trim();
   if (!base) {
-    const { getConfigValue } = await import('./config.js');
-    const v = await getConfigValue('FELO_API_BASE');
-    base = typeof v === 'string' ? v.trim() : '';
+    const { getConfigValue } = await import("./config.js");
+    const v = await getConfigValue("FELO_API_BASE");
+    base = typeof v === "string" ? v.trim() : "";
   }
-  const normalized = (base || DEFAULT_API_BASE).replace(/\/$/, '');
+  const normalized = (base || DEFAULT_API_BASE).replace(/\/$/, "");
   return normalized;
 }
 
@@ -24,19 +28,21 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-/** Write a single overwritable status line: spinner + elapsed. Call clearStatusLine() before next stdout. */
-function writeStatusLine(spinnerFrame, elapsedSec) {
+/** Write status line: spinner + elapsed. When overwrite is true use \\r (TTY); else use \\n so non-TTY still shows animation. */
+function writeStatusLine(spinnerFrame, elapsedSec, overwrite = true) {
   const s = `Generating slides... ${spinnerFrame} ${elapsedSec}s`;
-  const padded = s.padEnd(STATUS_LINE_PAD, ' ');
-  process.stderr.write(`\r${padded}`);
+  const padded = s.padEnd(STATUS_LINE_PAD, " ");
+  process.stderr.write(overwrite ? `\r${padded}` : `${padded}\n`);
 }
 
 function clearStatusLine() {
-  process.stderr.write(`\r${' '.repeat(STATUS_LINE_PAD)}\r`);
+  process.stderr.write(`\r${" ".repeat(STATUS_LINE_PAD)}\r`);
 }
 
 function normalizeTaskStatus(status) {
-  return String(status || '').trim().toUpperCase();
+  return String(status || "")
+    .trim()
+    .toUpperCase();
 }
 
 /**
@@ -48,11 +54,11 @@ async function createPptTask(apiKey, query, timeoutMs, apiBase) {
   const res = await fetchWithTimeoutAndRetry(
     url,
     {
-      method: 'POST',
+      method: "POST",
       headers: {
-        'Accept': 'application/json',
-        'Authorization': `Bearer ${apiKey}`,
-        'Content-Type': 'application/json',
+        Accept: "application/json",
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
       },
       body: JSON.stringify({ query: query.trim() }),
     },
@@ -61,19 +67,20 @@ async function createPptTask(apiKey, query, timeoutMs, apiBase) {
 
   const data = await res.json().catch(() => ({}));
 
-  if (data.status === 'error') {
-    const msg = data.message || data.code || 'Unknown error';
+  if (data.status === "error") {
+    const msg = data.message || data.code || "Unknown error";
     throw new Error(msg);
   }
 
   if (!res.ok) {
-    const msg = data.message || data.error || res.statusText || `HTTP ${res.status}`;
+    const msg =
+      data.message || data.error || res.statusText || `HTTP ${res.status}`;
     throw new Error(msg);
   }
 
   const payload = data.data;
   if (!payload || !payload.task_id) {
-    throw new Error('Unexpected response: missing task_id');
+    throw new Error("Unexpected response: missing task_id");
   }
 
   return payload;
@@ -88,10 +95,10 @@ async function getTaskHistorical(apiKey, taskId, timeoutMs, apiBase) {
   const res = await fetchWithTimeoutAndRetry(
     url,
     {
-      method: 'GET',
+      method: "GET",
       headers: {
-        'Accept': 'application/json',
-        'Authorization': `Bearer ${apiKey}`,
+        Accept: "application/json",
+        Authorization: `Bearer ${apiKey}`,
       },
     },
     timeoutMs
@@ -99,19 +106,20 @@ async function getTaskHistorical(apiKey, taskId, timeoutMs, apiBase) {
 
   const data = await res.json().catch(() => ({}));
 
-  if (data.status === 'error') {
-    const msg = data.message || data.code || 'Unknown error';
+  if (data.status === "error") {
+    const msg = data.message || data.code || "Unknown error";
     throw new Error(msg);
   }
 
   if (!res.ok) {
-    const msg = data.message || data.error || res.statusText || `HTTP ${res.status}`;
+    const msg =
+      data.message || data.error || res.statusText || `HTTP ${res.status}`;
     throw new Error(msg);
   }
 
   const payload = data.data;
   if (!payload) {
-    throw new Error('Unexpected response: missing data');
+    throw new Error("Unexpected response: missing data");
   }
 
   return {
@@ -120,6 +128,7 @@ async function getTaskHistorical(apiKey, taskId, timeoutMs, apiBase) {
     ppt_biz_id: payload.ppt_biz_id,
     live_doc_url: payload.live_doc_url,
     live_doc_short_id: payload.live_doc_short_id ?? payload.livedoc_short_id,
+    error_message: payload.error_message,
   };
 }
 
@@ -141,64 +150,85 @@ export async function slides(query, options = {}) {
   try {
     const apiBase = await getApiBase();
 
-    process.stderr.write('Creating PPT task...\n');
+    process.stderr.write("Creating PPT task...\n");
 
-    const createResult = await createPptTask(apiKey, query, requestTimeoutMs, apiBase);
+    const createResult = await createPptTask(
+      apiKey,
+      query,
+      requestTimeoutMs,
+      apiBase
+    );
     const taskId = createResult.task_id;
 
     if (options.json && options.verbose) {
       process.stderr.write(`Task ID: ${taskId}\n`);
     }
 
-    const useLiveStatus =
-      process.stderr.isTTY && !options.verbose && !options.json;
+    // 默认显示 spinner 动画；仅在使用 -v/--json 时改为逐行状态输出
+    const useLiveStatus = !options.verbose && !options.json;
+    const canOverwriteLine = process.stderr.isTTY && useLiveStatus;
     if (!useLiveStatus) {
-      process.stderr.write('Generating slides (this may take a minute)...\n');
+      process.stderr.write("Generating slides (this may take a minute)...\n");
     }
 
     const startTime = Date.now();
     let lastStatus;
     let spinIndex = 0;
-    if (useLiveStatus) writeStatusLine(SPINNER_FRAMES[0], 0);
+    if (useLiveStatus) writeStatusLine(SPINNER_FRAMES[0], 0, canOverwriteLine);
 
     while (Date.now() - startTime < pollTimeoutMs) {
       await sleep(pollIntervalMs);
 
-      const historical = await getTaskHistorical(apiKey, taskId, requestTimeoutMs, apiBase);
+      const historical = await getTaskHistorical(
+        apiKey,
+        taskId,
+        requestTimeoutMs,
+        apiBase
+      );
       const normalizedStatus = normalizeTaskStatus(historical.task_status);
       lastStatus = normalizedStatus || historical.task_status;
 
       const elapsed = Math.floor((Date.now() - startTime) / 1000);
       if (useLiveStatus) {
         spinIndex = (spinIndex + 1) % SPINNER_FRAMES.length;
-        writeStatusLine(SPINNER_FRAMES[spinIndex], elapsed);
+        writeStatusLine(SPINNER_FRAMES[spinIndex], elapsed, canOverwriteLine);
       } else if (!options.verbose && !options.json) {
         process.stderr.write(`  Generating... ${elapsed}s\n`);
       }
 
-      const done = normalizedStatus === 'COMPLETED' || normalizedStatus === 'SUCCESS';
+      const done =
+        normalizedStatus === "COMPLETED" || normalizedStatus === "SUCCESS";
       if (done) {
-        if (useLiveStatus) clearStatusLine();
+        if (useLiveStatus && canOverwriteLine) clearStatusLine();
         const pptUrl =
           historical.ppt_url ||
-          (historical.ppt_biz_id ? `https://dev.felo.ai/slides/${historical.ppt_biz_id}` : null);
+          (historical.ppt_biz_id
+            ? `https://dev.felo.ai/slides/${historical.ppt_biz_id}`
+            : null);
         const liveDocUrl =
           historical.live_doc_url ||
-          (historical.live_doc_short_id ? `https://felo.ai/livedoc/${historical.live_doc_short_id}` : null) ||
-          (createResult.livedoc_short_id ? `https://felo.ai/livedoc/${createResult.livedoc_short_id}` : null);
+          (historical.live_doc_short_id
+            ? `https://felo.ai/livedoc/${historical.live_doc_short_id}`
+            : null) ||
+          (createResult.livedoc_short_id
+            ? `https://felo.ai/livedoc/${createResult.livedoc_short_id}`
+            : null);
         const url = pptUrl || liveDocUrl;
         if (options.json) {
           console.log(
             JSON.stringify(
               {
-                status: 'ok',
+                status: "ok",
                 data: {
                   task_id: taskId,
                   task_status: normalizedStatus || historical.task_status,
                   ppt_url: pptUrl,
-                  ppt_biz_id: historical.ppt_biz_id ?? createResult.ppt_business_id,
+                  ppt_biz_id:
+                    historical.ppt_biz_id ?? createResult.ppt_business_id,
                   live_doc_url: liveDocUrl,
-                  livedoc_short_id: historical.live_doc_short_id ?? createResult.livedoc_short_id,
+                  livedoc_short_id:
+                    historical.live_doc_short_id ??
+                    createResult.livedoc_short_id,
                   ppt_business_id: createResult.ppt_business_id,
                 },
               },
@@ -209,40 +239,94 @@ export async function slides(query, options = {}) {
         } else {
           if (url) {
             if (pptUrl && !options.json) {
-              process.stderr.write('PPT ready. Open this link to preview:\n');
+              process.stderr.write("PPT ready. Open this link to preview:\n");
             }
             console.log(pptUrl || liveDocUrl);
           } else {
             if (useLiveStatus) clearStatusLine();
-            console.error('Error: Completed but no ppt_url or live_doc_url in response');
+            console.error(
+              "Error: Completed but no ppt_url or live_doc_url in response"
+            );
             return 1;
           }
         }
         return 0;
       }
 
-      if (
-        normalizedStatus === 'FAILED' ||
-        normalizedStatus === 'ERROR'
-      ) {
-        if (useLiveStatus) clearStatusLine();
-        console.error(`Error: Task finished with status: ${normalizedStatus || historical.task_status}`);
+      const terminalErrorStatuses = [
+        "FAILED",
+        "PENDING",
+        "EXPIRED",
+        "CANCELED",
+      ];
+
+      if (terminalErrorStatuses.includes(normalizedStatus)) {
+        if (useLiveStatus && canOverwriteLine) clearStatusLine();
+
+        const liveDocUrl =
+          historical.live_doc_url ||
+          (historical.live_doc_short_id
+            ? `https://felo.ai/livedoc/${historical.live_doc_short_id}`
+            : null) ||
+          (createResult.livedoc_short_id
+            ? `https://felo.ai/livedoc/${createResult.livedoc_short_id}`
+            : null);
+
+        const errorMessage =
+          historical.error_message ||
+          `Task finished with status: ${
+            normalizedStatus || historical.task_status
+          }`;
+
+        if (options.json) {
+          console.log(
+            JSON.stringify(
+              {
+                status: "error",
+                data: {
+                  task_id: taskId,
+                  task_status: normalizedStatus || historical.task_status,
+                  live_doc_url: liveDocUrl,
+                  livedoc_short_id:
+                    historical.live_doc_short_id ??
+                    createResult.livedoc_short_id,
+                  error_message: errorMessage,
+                },
+              },
+              null,
+              2
+            )
+          );
+        } else {
+          if (liveDocUrl) {
+            console.log(liveDocUrl);
+          }
+          console.error(errorMessage);
+        }
+
         return 1;
       }
 
       if (options.verbose) {
-        process.stderr.write(`  Status: ${normalizedStatus || historical.task_status || 'UNKNOWN'}\n`);
+        process.stderr.write(
+          `  Status: ${
+            normalizedStatus || historical.task_status || "UNKNOWN"
+          }\n`
+        );
       }
     }
 
-    if (useLiveStatus) clearStatusLine();
+    if (useLiveStatus && canOverwriteLine) clearStatusLine();
     console.error(
-      `Error: Timed out after ${pollTimeoutMs / 1000}s. Last status: ${lastStatus ?? 'unknown'}`
+      `Error: Timed out after ${pollTimeoutMs / 1000}s. Last status: ${
+        lastStatus ?? "unknown"
+      }`
     );
     return 1;
   } catch (err) {
-    if (process.stderr.isTTY && !options.verbose && !options.json) clearStatusLine();
-    console.error('Error:', err.message || err);
+    if (process.stderr.isTTY && !options.verbose && !options.json)
+      clearStatusLine();
+    console.error("Error:", err.message || err);
     return 1;
   }
 }