felo-superAgent

Felo SuperAgent 技能

约束（请先阅读）

这些规则为强制要求。违反任何一条都会导致行为错误。

1. 始终使用 --json 标志。 脚本必须以 JSON 模式（--json）运行。在 Claude Code 的 Bash 工具中，stdout 始终会被捕获，不会直接流式输出给用户。JSON 模式会以结构化响应的形式返回完整答案，Claude 随后可以将其作为文本输出。状态 ID 从 JSON 响应字段 thread_short_id 和 live_doc_short_id 中提取。

2. 始终直接以文本形式输出答案。 脚本运行结束后，从 JSON 输出中读取 data.answer，并将其原样打印为响应文本。不要总结、改述，也不要在其周围添加说明。必须原样输出，让用户看到完整内容。然后，如果 data.image_urls 非空，紧接着附上图片链接，每张图片单独一行，格式为：[title](url)。

3. 创建对话时必须提供 --live-doc-id。 调用 run_superagent.mjs 时绝不可省略 --live-doc-id。如果尚未获取，请先获取（见下文步骤 2）。

4. 复用任何来源的 live_doc_id。 如果本次会话之前的任何操作已提供 live_doc_id，无论它来自之前的 SuperAgent 调用、felo-livedoc 技能操作、用户提供的输入，还是其他技能，都要直接使用。不要再次请求 LiveDoc 列表。只有在任何来源都没有 live_doc_id 时，才获取列表。（注意：live_doc_id 对应 API 字段 live_doc_short_id 和 [state] 输出键 live_doc_short_id。）

5. 每个会话使用一个 LiveDoc。 会话中的所有对话都必须使用相同的 --live-doc-id。除非用户明确要求“打开新画布”／“开始新的 LiveDoc”／“创建新的工作区”，否则不要创建新的 LiveDoc。

6. 默认行为是跟进，而不是开始新对话。 用户提出第一个问题后，之后的每条消息都是跟进。必须传入上一个响应中的 --thread-id。只有在以下情况才省略 --thread-id（在同一个 LiveDoc 上开始新线程）：

   • 用户明确说“新主题”／“换个话题”／“重新开始”
   • 用户的意图需要指定特定的 --skill-id（例如撰写推文、设计徽标、制作产品图片），而当前线程创建时没有使用该技能，因为 --skill-id 仅在新对话中生效

7. 始终保存状态。 每次调用后，都要从 stderr 的 [state] 行中提取 thread_short_id 和 live_doc_id（其输出键为 live_doc_short_id）。在下一次调用时使用它们。丢失这些 ID 会中断对话连续性。

8. 选择技能 ID（仅限新对话）。 创建新对话（未提供 --thread-id）时，分析用户意图并判断其是否符合受支持的技能 ID：

   可用技能 ID：

   • twitter-writer — 用于撰写、起草或发布推文／X 帖子
   • logo-and-branding — 用于创建徽标、品牌设计或视觉识别
   • ecommerce-product-image — 用于生成电商产品图片

   选择逻辑：

   • 如果用户明确指定了某个技能 ID，使用其指定的值
   • 如果用户意图明显符合上述某项技能，传入对应的 --skill-id 值
   • 如果都不符合，则不要传入 --skill-id（使用通用对话模式）
   • --skill-id 仅在创建新对话时生效。在跟进模式（--thread-id）下会被忽略。

9. 基于技能的新对话需要选择品牌风格。 开始使用技能 ID（twitter-writer、logo-and-branding、ecommerce-product-image）的新对话时，必须先获取风格库，并在调用 run_superagent.mjs 之前让用户选择风格。通过 --ext '{"brand_style_requirement":"<style_string>"}' 传入选定的风格。完整流程见步骤 4.5。

   • 样式字符串是 run_style_library.mjs 为该条目输出的确切文本块。字段因类别而异：
     • TWITTER：Style name + Style labels（根据语言返回）+ Style DNA + Cover file ID（若为 null 则省略）
     • IMAGE：Style name + Style labels + Style DNA 或 Cover file ID（取决于实际存在的字段）
   • 使用与技能匹配的类别：twitter-writer 使用 TWITTER，logo-and-branding 和 ecommerce-product-image 使用 IMAGE。
   • 始终向 run_style_library.mjs 传入 --accept-language，以便标签以用户的语言返回。
   • 如果用户已经指定样式（通过名称指定或粘贴样式块），则跳过获取步骤，直接使用用户选择的样式。
   • 如果样式库没有返回任何条目，则在不使用 --ext 的情况下继续。
   • --ext 仅对新对话有效。后续模式（--thread-id）中切勿传入该参数。

10. 切勿随意创建新的 LiveDoc。 重用现有 LiveDoc。唯一例外是用户明确要求创建新的画布或工作区。

适用场景

当用户希望进行以下操作时，触发此技能：

• SuperAgent 对话： 与 Felo SuperAgent 进行 AI 对话，并实时流式输出
• 连续对话： 在持久化的 LiveDoc 画布上进行多轮问答
• Logo 与品牌设计： 创建 Logo 或品牌设计（自动选择 logo-and-branding 技能）
• 电商图片： 生成产品图片（自动选择 ecommerce-product-image 技能）
• 工具增强型回答： 回答中可能包含图像生成、文档创建、PPT 生成或 Twitter/X 搜索
• 流式响应： 通过服务器发送事件（SSE）实时生成回答

触发词：

• 英语：superagent, super agent, stream chat, streaming conversation, livedoc conversation, continuous chat, follow-up question, create a logo, brand design, product image, e-commerce image
• 简体中文（拼音）：chao ji zhu shou, liu shi dui hua, lian xu dui hua, zhui wen, she ji logo, pin pai she ji, dian shang tu pian
• 繁体中文（拼音）：chao ji zhu shou, liu shi dui hua, lian xu dui hua, zhui wen, she ji logo, pin pai she ji, dian shang tu pian
• 日语（罗马字）：suupaa eejento, sutoriimingu kaiwa, keizoku kaiwa, rogo sakusei, shouhin gazou

明确命令： /felo-superAgent、"use felo superagent"、"felo superagent"

以下情况请勿使用：

• 撰写任何类型的 Tweet/X 帖子（改用 felo-twitter-writer）
• 简单的一次性问答或实时信息查询（优先使用 felo-search）
• 仅获取网页内容（使用 felo-web-fetch）
• 仅生成 PPT/幻灯片（使用 felo-slides）
• 仅管理 LiveDoc 知识库（使用 felo-livedoc）
• 仅搜索 Twitter/X（使用 felo-x-search）

设置

1. 获取 API 密钥

1. 访问 felo.ai 并登录（或注册）
2. 点击右上角的头像 → Settings
3. 进入 "API Keys" 标签页
4. 点击 "Create New Key" 生成新的 API Key
5. 复制并安全保存 API Key

2. 配置 API 密钥

这些脚本（run_superagent.mjs、run_style_library.mjs）仅从 FELO_API_KEY 环境变量读取 API 密钥。felo config set CLI 命令会将密钥写入 ~/.felo/config.json，但这些脚本不会读取该文件——唯一受支持的方式是使用环境变量。

Linux/macOS：

export FELO_API_KEY="your-api-key-here"

如需永久配置，请添加到 shell 配置文件（~/.bashrc 或 ~/.zshrc）：

echo 'export FELO_API_KEY="your-api-key-here"' >> ~/.zshrc
source ~/.zshrc

Windows（PowerShell）：

$env:FELO_API_KEY="your-api-key-here"

Windows（CMD）：

set FELO_API_KEY=your-api-key-here

3. 依赖项：felo-livedoc

此技能依赖 felo-livedoc 技能来获取和创建 LiveDoc。请确保 felo-livedoc/scripts/run_livedoc.mjs 与 felo-superAgent/ 位于同一层级。

执行方法

触发此技能后，请严格按顺序执行以下步骤。使用 Bash 工具执行所有命令。

步骤 1：检查 API 密钥

if [ -z "$FELO_API_KEY" ]; then
  echo "ERROR: FELO_API_KEY not set"
  exit 1
fi

如果未设置，请停止并向用户显示上述设置说明。

步骤 2：获取 live_doc_id

此步骤可确保你在创建任何对话前始终拥有有效的 --live-doc-id。（注意：live_doc_id 对应 API 字段 live_doc_short_id。）

2a. 如果你在本次会话的任意来源中已经有 live_doc_id： 跳转到步骤 3。重复使用同一个 ID。来源包括：之前一次 SuperAgent 调用的 [state] 输出（live_doc_short_id 字段）、felo-livedoc 技能操作（创建、列表等）、用户提供的输入，或任何其他返回 LiveDoc ID 的技能。

2b. 如果任何来源都没有可用的 live_doc_id — 获取 LiveDoc 列表：

node felo-livedoc/scripts/run_livedoc.mjs list --json

解析 JSON 输出。响应包含 data.items——一个按修改时间降序排列的 LiveDoc 对象数组。找到第一个 is_shared === false 的项目，并将其 short_id 用作你的 live_doc_id。绝不可选择 is_shared === true 的项目——共享的 LiveDoc 属于其他项目，会导致 502 错误。

示例响应：

{
  "status": "ok",
  "data": {
    "total": 3,
    "items": [
      { "short_id": "abc123", "name": "Shared Project", "is_shared": true, "modified_at": "..." },
      { "short_id": "QPetunwpGnkKuZHStP7gwt", "name": "My Workspace", "is_shared": false, "modified_at": "..." },
      ...
    ]
  }
}

使用：live_doc_id = data.items.find(i => !i.is_shared)?.short_id

2c. 如果不存在 is_shared === false 的项目（或列表为空）— 创建一个：

node felo-livedoc/scripts/run_livedoc.mjs create --name "SuperAgent Workspace" --json

解析 JSON 输出，并提取 data.short_id 作为你的 live_doc_id。

示例响应：

{
  "status": "ok",
  "data": {
    "short_id": "NewDocId123abc",
    "name": "SuperAgent Workspace",
    ...
  }
}

2d. 如果用户明确要求创建新的画布/工作区：

创建一个新的 LiveDoc（与 2c 相同），然后在后续所有调用中使用新的 ID。丢弃旧的 live_doc_id。

步骤 3：确定对话模式

判断这是新对话还是后续对话：

条件	模式	传入内容
会话中的第一个问题（尚无 thread_short_id）	新对话	仅传入 --live-doc-id
用户提出后续问题/继续当前主题（默认）	后续对话	同时传入 --thread-id 和 --live-doc-id
用户明确表示“新主题”/“更换主题”	新对话	仅传入 --live-doc-id（同一个 LiveDoc）
用户意图需要的 --skill-id 与当前线程不匹配	新对话	--live-doc-id + --skill-id（同一个 LiveDoc）
用户明确表示“新画布”/“新 LiveDoc”	新对话	使用步骤 2d 获取新的 --live-doc-id

重要： 用户在第一条消息之后发送的任何消息，默认都始终视为后续对话。只有用户明确提出要求时，才将其视为新对话。

步骤 4：确定 Skill ID（仅限新对话）

如果这是新对话（没有 --thread-id），请分析用户的意图：

可用的 skill ID：

• twitter-writer — 用于撰写、起草或发布推文/X 帖子
• logo-and-branding — 用于创建徽标、品牌设计或视觉形象
• ecommerce-product-image — 用于生成电商用途的商品图片

判断方法：

1. 如果用户明确指定了 skill-id，请使用该值
2. 否则，分析用户的请求，判断是否与上述某个选项匹配
3. 如果都不匹配，请勿传入 --skill-id

如果这是后续对话（已设置 --thread-id），则完全跳过此步骤。在后续对话模式中，--skill-id 会被忽略。

步骤 4.5：获取并选择品牌风格（仅限新技能对话）

何时运行此步骤： 仅当这是一次新对话，且已在步骤 4 中确定技能 ID（twitter-writer、logo-and-branding 或 ecommerce-product-image）时运行。后续对话或一般对话（无技能）中完全跳过。

类别映射：

技能 ID	风格类别
twitter-writer	TWITTER
logo-and-branding	IMAGE
ecommerce-product-image	IMAGE

4.5a. 如果用户已指定风格（通过名称指定，或粘贴风格块），请直接使用 — 跳至 4.5d。

4.5b. 获取风格列表（仅名称）：

重要：Style DNA 内容非常庞大。始终使用 --json，并通过 Node.js 仅提取名称/标签，以避免 Bash 工具输出被截断。列出风格时，切勿在不带 --json 的情况下调用 run_style_library.mjs。

# For twitter-writer
node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language en --json | node -e "
const d=require('fs').readFileSync('/dev/stdin','utf8');
const j=JSON.parse(d);
const list=j.list||[];
const user=list.filter(s=>!s.recommended);
const rec=list.filter(s=>s.recommended);
if(user.length){console.log('[Your styles]');user.forEach((s,i)=>{const labels=(s.content?.labels?.en||[]).join(', ');console.log((i+1)+'. '+s.name+(labels?' — '+labels:''));});}
if(rec.length){console.log('[Recommended styles]');rec.forEach((s,i)=>{const labels=(s.content?.labels?.en||[]).join(', ');console.log((user.length+i+1)+'. '+s.name+(labels?' — '+labels:''));});}
if(!list.length)console.log('(No styles found)');
"

# For logo-and-branding or ecommerce-product-image
node felo-superAgent/scripts/run_style_library.mjs --category IMAGE --accept-language en --json | node -e "
const d=require('fs').readFileSync('/dev/stdin','utf8');
const j=JSON.parse(d);
const list=j.list||[];
if(list.length){list.forEach((s,i)=>{const labels=(s.content?.labels?.en||s.content?.tags?.en||[]).join(', ');console.log((i+1)+'. '+s.name+(labels?' — '+labels:''));});}
else console.log('(No styles found)');
"

将 en 替换为与用户语言对应的 --accept-language 值（zh、ja、ko、en）。同时更新 Node 脚本中的 .labels?.en 引用，使其与之匹配（例如，中文使用 .labels?.zh）。

4.5c. 向用户展示风格并请其选择：

以纯文本输出完整列表 — 返回的每种风格都必须列出，并按顺序编号。切勿使用 AskUserQuestion 工具（它最多只支持 4 个选项，并会静默丢弃其余风格）。切勿代替用户预选或筛选风格。最后始终附加一个“无偏好”选项。继续之前，请等待用户以纯文本回复。

输出示例：

Here are the available writing styles — choosing one will make the output more accurate:

[Your styles]
1. My Bold Voice — bold, provocative

[Recommended styles]
2. darioamodei — Thoughtful long-form essays
3. Casual & Witty — humor, relatable
...(ALL styles listed, none omitted)

0. No preference — use default style

如果用户选择“无偏好”（0），或列表为空，则不带 --ext 继续步骤 5。

4.5d. 构建 --ext 值：

获取所选风格的完整文本块（与脚本输出完全一致），并将其作为 brand_style_requirement 的值。文本块可能包含多行 — 将其序列化为单个 JSON 字符串，换行符使用 \n，字段值中的双引号使用 \"：

风格块输出示例：

Style name: darioamodei
Style labels: Thoughtful long-form essays
Style DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA\n\n## Style Overview\nDario writes like a serious intellectual...

序列化为 --ext：

--ext '{"brand_style_requirement":"Style name: darioamodei\nStyle labels: Thoughtful long-form essays\nStyle DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA\n\n## Style Overview\nDario writes like a serious intellectual..."}'

重要： 完整且原样地传递 brand_style_requirement 值 — 不要截断 Style DNA。不完整的风格内容会降低输出质量。

步骤 5：运行脚本

构造并执行命令。始终使用 --json——在 Claude Code 的 Bash 工具中，stdout 会被捕获，而不会流式传输给用户。JSON 模式会以结构化响应返回完整答案。

重要： SSE 流可能需要很长时间（尤其是图像生成、研究报告等）。执行脚本时，必须将 Bash 工具超时设置为至少 600000ms（10 分钟），以防提前终止。

**--accept-language 的选择：**默认值为 en。应与用户使用的语言一致——如果用户用中文交流，则使用 zh；用日语交流，则使用 ja；用韩语交流，则使用 ko，以此类推。

**--query 的构造：**不要直接照搬用户的原始输入。应丰富并完善查询，使其对 SuperAgent 更完整、更有效：

• **添加上下文：**如果对话中有先前的上下文（例如，用户之前讨论过某个主题），请融入相关细节，让 SuperAgent 了解完整情况。
• **澄清模糊的请求：**如果用户说得很简短，例如“继续”或“接着说”，请展开说明要继续的内容（例如，“请继续上面的量子计算分析，并详细介绍其现实应用”）。
• **补充缺失的细节：**如果用户的请求隐含了他们之前提到的信息（例如品牌名称、产品类型、风格偏好），请将这些细节加入查询。
• **保留用户意图：**绝不要改变用户的核心意图。只添加上下文并使表达更清晰，不要加入个人观点或转移话题。
• **保持简洁：**查询长度上限为 2000 个字符。丰富内容的同时保持重点，避免不必要的赘述。

示例：

• 用户说“继续” → --query "Please continue the analysis above on quantum computing, expanding on real-world applications"
• 用户说“再来一个” → --query "Please generate another product image in a similar style, white background"
• 用户说“修正它” → --query "Please revise the tweet generated above, make the tone more casual and add some emojis"

新对话（第一个问题，没有技能）：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "USER_QUERY_HERE" \
  --live-doc-id "LIVE_DOC_ID" \
  --accept-language en \
  --json

包含技能 ID、尚未选择风格的新对话：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "Write a tweet about the latest AI trends" \
  --live-doc-id "LIVE_DOC_ID" \
  --skill-id twitter-writer \
  --accept-language en \
  --json

包含技能 ID 和品牌风格（来自步骤 4.5）的新对话：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "Write a tweet about the latest AI trends" \
  --live-doc-id "LIVE_DOC_ID" \
  --skill-id twitter-writer \
  --ext '{"brand_style_requirement":"Style name: darioamodei\nStyle labels: Thoughtful long-form essays\nStyle DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA\n\n## Style Overview\nDario writes like a serious intellectual...（full content）"}' \
  --accept-language en \
  --json

后续问题（第 2 条及之后的消息默认使用）：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "USER_FOLLOW_UP_QUERY" \
  --thread-id "THREAD_SHORT_ID_FROM_PREVIOUS" \
  --live-doc-id "LIVE_DOC_ID" \
  --json

步骤 6：提取状态并输出答案

脚本执行完毕后，解析 JSON 输出：

{
  "status": "ok",
  "data": {
    "answer": "...",
    "thread_short_id": "CmYpuGwBgCnrUdDx5ZtmxA",
    "live_doc_short_id": "QPetunwpGnkKuZHStP7gwt",
    "live_doc_url": "https://felo.ai/livedoc/QPetunwpGnkKuZHStP7gwt",
    "image_urls": [
      {
        "url": "https://...",
        "title": "Image title",
        "file_id": "b9e5be11-7686-4aa8-ae6c-9876511a7b5c"
      }
    ]
  }
}

1. 原样输出 data.answer 作为响应文本——逐字打印，确保用户能看到完整内容。

2. 提取并保存 data.thread_short_id 和 data.live_doc_short_id——下次调用时必须使用这两个值。

3. 可选择显示 data.live_doc_url，供用户在浏览器中查看 LiveDoc 画布。

4. 图像结果（data.image_urls）：如果此数组非空，请紧接在 data.answer 后附上图像链接，格式为每张图像占一行：

   [title](url)
   

   输出示例：

   [Giant panda eating bamboo](https://...)
   [Giant panda dancing](https://...)
   [Blue whale leaping out of the water](https://...)
   

   每张图像都包含 url（有时效限制的签名 S3 URL）、title 和 file_id（稳定的文件标识符）。注意：同一张图像可能会同时出现在 tools_result_stream 和 tools_result 事件中，并带有不同的签名 URL——系统会自动根据 file_id 去重。在后续查询中引用先前生成的图像时，请在 --query 中包含其 file_id，以便 SuperAgent 找到该文件（例如，"Please generate a variation of file_id=b9e5be11-..."）。

除非用户要求，否则不要向用户显示 thread_short_id 或 live_doc_short_id。

完整工作流示例

示例 A：多轮对话（最常见）

User: "What is quantum computing?"

步骤 2b： 获取 LiveDoc 列表 → 获取 live_doc_id = "QPetunwpGnkKuZHStP7gwt" 步骤 3： 第一个问题 → 新建对话 步骤 4： 没有特殊技能 → 不使用 --skill-id 步骤 5：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "What is quantum computing?" \
  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
  --accept-language en \
  --json

步骤 6： 解析 JSON 输出。将 data.answer 原样作为回复输出。从 data 中保存 thread_short_id = "CmYpuGwBgCnrUdDx5ZtmxA"、live_doc_id = "QPetunwpGnkKuZHStP7gwt"。

User: "What are its practical applications?"

步骤 2a： 已有 live_doc_id → 跳过 步骤 3： 后续问题（默认）→ 使用已保存的 thread_short_id 步骤 5：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "What are its practical applications?" \
  --thread-id "CmYpuGwBgCnrUdDx5ZtmxA" \
  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
  --json

步骤 6： 解析 JSON 输出。将 data.answer 原样输出。从 data 中保存更新后的 thread_short_id（可能相同），保留 live_doc_id。

User: "Tell me more about quantum error correction"

步骤 3： 仍是后续问题（主题相同）→ 使用已保存的 thread_short_id 步骤 5： 按照上述相同模式使用新查询

示例 B：选择风格撰写推文

User: "Help me write a tweet about AI trends"

步骤 2a： 已有 live_doc_id → 复用 步骤 3： 新建对话 步骤 4： 用户意图符合“撰写推文” → --skill-id twitter-writer 步骤 4.5： 获取 TWITTER 风格（传入与用户语言匹配的 --accept-language）：

node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language en

输出：

Style name: My Bold Voice
Style labels: bold, provocative
Style DNA: # My Bold Voice Style DNA
...（full content）

Style name: darioamodei
Style labels: Thoughtful long-form essays
Style DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA
...（full content）

向用户展示：“您想要哪种写作风格？1. My Bold Voice（您的风格）2. darioamodei（推荐）3. 不限”

用户选择：“1. My Bold Voice”

步骤 5：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "Help me write a tweet about AI trends" \
  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
  --skill-id twitter-writer \
  --ext '{"brand_style_requirement":"Style name: My Bold Voice\nStyle labels: bold, provocative\nStyle DNA: # My Bold Voice Style DNA\n...（full content）"}' \
  --accept-language en \
  --json

步骤 6： 解析 JSON 输出。将 data.answer 原样输出。从 data 中保存新的 thread_short_id，保留相同的 live_doc_id。

User: "Make it more casual and add some emojis"

步骤 3： 后续问题 → 使用已保存的 thread_short_id（不要再次传入 --ext） 步骤 5：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "Make it more casual and add some emojis" \
  --thread-id "NEW_THREAD_FROM_TWEET" \
  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
  --json

示例 C：选择风格设计徽标

User: "Design a logo for my coffee shop called Bean & Brew"

步骤 4： 检测到“设计徽标” → --skill-id logo-and-branding 步骤 4.5： 获取 IMAGE 风格：

node felo-superAgent/scripts/run_style_library.mjs --category IMAGE --accept-language en

输出示例：

Style name: Minimalist Modern
Style labels: clean, monochrome
Style DNA: ...（full content）
Cover file ID: file_333

向用户展示风格并等待选择。假设用户选择“Minimalist Modern”：

步骤 5：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "Design a logo for my coffee shop called Bean & Brew" \
  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
  --skill-id logo-and-branding \
  --ext '{"brand_style_requirement":"Style name: Minimalist Modern\nStyle labels: clean, monochrome\nStyle DNA: ...（full content）\nCover file ID: file_333"}' \
  --accept-language en \
  --json

示例 D：选择风格制作电商产品图片

User: "Generate a product image for a wireless headphone on white background"

步骤 4： 检测到“产品图片” → --skill-id ecommerce-product-image 步骤 4.5： 获取 IMAGE 风格：

node felo-superAgent/scripts/run_style_library.mjs --category IMAGE --accept-language en

向用户展示风格。假设用户选择“不限”：

步骤 5：（用户选择不限，因此不使用 --ext）

node felo-superAgent/scripts/run_superagent.mjs \
  --query "Generate a product image for a wireless headphone on white background" \
  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
  --skill-id ecommerce-product-image \
  --accept-language en \
  --json

示例 E：用户请求新建画布

User: "Open a new canvas for a different project"

步骤 2d： 创建新的 LiveDoc：

node felo-livedoc/scripts/run_livedoc.mjs create --name "New Project" --json

提取新的 live_doc_id。丢弃旧 ID。之后所有调用都使用新 ID。

示例 F：用户直接指定风格

User: "Write a tweet about AI trends using the 'darioamodei' style"

步骤 4： --skill-id twitter-writer 步骤 4.5a： 用户已指定风格名称 → 获取列表以取得完整内容块：

node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language en

找到 Style name: darioamodei 对应的条目，并原样提取其完整内容块。无需再次询问用户。

步骤 5：

node felo-superAgent/scripts/run_superagent.mjs \
  --query "Write a tweet about AI trends" \
  --live-doc-id "QPetunwpGnkKuZHStP7gwt" \
  --skill-id twitter-writer \
  --ext '{"brand_style_requirement":"Style name: darioamodei\nStyle labels: Thoughtful long-form essays\nStyle DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA\n\n## Style Overview\nDario writes like a serious intellectual...（full content, do NOT truncate）"}' \
  --accept-language en \
  --json

可用脚本选项

核心参数：

• --query <text>（必填）— 用户问题，1-2000 个字符
• --live-doc-id <id>（新建对话时必填）— 要关联的 LiveDoc ID（live_doc_id）
• --thread-id <id> — 来自先前响应的 Thread ID，用于后续对话

技能参数（仅限新建对话，在后续对话中会被忽略）：

• --skill-id <id> — 技能 ID（可用技能 ID 见约束 #9）
• --selected-resource-ids <ids> — 要包含的资源 ID，以逗号分隔
• --ext <json> — 以 JSON 对象形式传入的额外参数。对于基于技能的对话，按以下格式传入品牌风格： --ext '{"brand_style_requirement":"Style name: <name>\nStyle labels: <labels>\nStyle DNA: <full styleDna text>\nCover file ID: <id>"}' 包含的字段取决于类别类型。值为 null 时省略 Cover file ID。不要截断 Style DNA。

输出控制：

• --json / -j — 以 JSON 格式输出完整元数据（在 Claude Code 中始终使用此选项 — 标准输出由 Bash 工具捕获，不会流式传输给用户）
• --verbose / -v — 将流连接详细信息记录到 stderr（仅用于调试，正常使用时无需设置）
• --accept-language <lang> — 语言偏好（例如 en、ja、ko）

API 工作流（参考）

脚本会自动处理此工作流：

1. 创建对话：

   • 新建：POST /v2/conversations（请求正文中需要包含 live_doc_short_id）
   • 后续对话：POST /v2/conversations/{threadId}/follow_up
   • 返回：stream_key、thread_short_id、live_doc_short_id

2. 接收 SSE 流：

   • GET /v2/conversations/stream/{stream_key}
   • 支持通过 offset 参数恢复：?offset={lastOffset}
   • 如果连接中断，会自动重连（延迟 2 秒）

3. 解析事件：

   • message — 直接文本内容
   • stream — 包含类型信息的封装内容
   • heartbeat — 保持连接的信号
   • done / completed / complete — 流已结束
   • error — 错误事件（非终止事件，会继续读取）

4. 提取工具结果：

   • 图像生成（generate_images）
   • 研究报告（generate_discovery）
   • 文档生成（generate_document）
   • PPT 生成（generate_ppt）
   • HTML 生成（generate_html）
   • Twitter/X 搜索（search_x）

基础 URL：https://openapi.felo.ai（如有需要，可通过 FELO_API_BASE 覆盖）。

工具支持

SuperAgent 可能会在对话期间调用工具。脚本会自动提取并显示：

图像生成：

• 工具：generate_images
• 输出：图像 URL 和标题

研究与探索：

• 工具：generate_discovery
• 输出：研究报告标题和状态

文档生成：

• 工具：generate_document
• 输出：文档标题和状态

演示文稿生成：

• 工具：generate_ppt
• 输出：PPT 标题和状态

HTML 生成：

• 工具：generate_html
• 输出：HTML 页面标题和状态

Twitter/X 搜索：

• 工具：search_x
• 输出：推文内容、作者信息、互动数据（点赞数、转发数、浏览量）

错误处理

常见错误代码

Code	HTTP	Description
INVALID_API_KEY	401	API Key 无效或已被撤销
SUPER_AGENT_CONVERSATION_CREATE_FAILED	502	创建对话失败（上游错误）
SUPER_AGENT_CONVERSATION_QUERY_FAILED	502	查询对话详情失败

SSE 流错误

流可能会发送：

• event: error，并附带 data: {"message": "..."} — 视为失败并显示消息
• 连接超时 — 脚本会自动重连，延迟 2 秒
• 空闲超时（2 小时）— 如果未收到数据，流将中止

缺少 API 密钥

如果未设置 FELO_API_KEY，显示此消息：

ERROR: FELO_API_KEY not set

To use this skill, you need to set up your Felo API Key:

1. Get your API key from https://felo.ai (Settings -> API Keys)
2. Set the environment variable:

   Linux/macOS:
   export FELO_API_KEY="your-api-key-here"

   Windows (PowerShell):
   $env:FELO_API_KEY="your-api-key-here"

3. Restart Claude Code or reload the environment

超时处理

• SSE 流有自己的空闲超时：2 小时（未收到数据）。只要数据持续传输，流就会保持打开状态。
• Bash 工具超时： 执行脚本时必须将超时设为至少 600000ms（10 分钟），因为 SSE 流可能会持续很长时间。

重要说明

• 立即使用 Bash 工具执行此技能，不要只描述你会怎么做
• 始终使用 --json——在 Claude Code 的 Bash 工具中，stdout 会被捕获，而不是流式传输。JSON 模式会以结构化响应的形式返回答案，Claude 会将其作为文本输出
• 始终原样输出 data.answer——将其一字不差地打印为响应文本，让用户看到完整内容
• 创建后，脚本会立即连接到流——stream_key 的有效期有限
• 使用随附的 Node 脚本接收 SSE；不要假定有 jq 或其他工具可用于解析 SSE
• 与其他 Felo 技能使用相同的 API 密钥（FELO_API_KEY）
• 如果流中断，脚本会自动重新连接
• 工具结果会去重，避免多次显示同一资源
• 如果已通过任何来源（其他技能、用户输入、先前的调用）获取 live_doc_id，请直接使用，不要再次获取 LiveDoc 列表
• 多语言支持：完整支持简体中文、繁体中文、日语和英语
• 在可能的情况下，API 会以与查询相同的语言返回结果

决策流程图

User sends a message
        |
        v
Have live_doc_id from ANY source?
   NO  --> Step 2b: fetch list --> got is_shared=false item?
              YES --> use data.items.find(i => !i.is_shared)?.short_id as live_doc_id
              NO  --> Step 2c: create new LiveDoc
   YES --> continue (reuse it, do NOT fetch list)
        |
        v
Have thread_short_id from previous call?
   NO  --> This is a NEW conversation
              --> Step 4: determine skill-id by analyzing user intent
              --> skill-id found (twitter-writer / logo-and-branding / ecommerce-product-image)?
                    YES --> Step 4.5: fetch style library for matching category
                              --> styles available?
                                    YES --> present to user, wait for selection
                                              --> user picked a style?
                                                    YES --> build --ext '{"brand_style_requirement":"..."}'
                                                    NO  --> no --ext
                                    NO  --> no --ext
                    NO  --> no --ext, no --skill-id
              --> Step 5: run WITHOUT --thread-id (with --skill-id and --ext if determined above)
   YES --> Does user's intent require a skill-id not matching current thread?
              YES --> NEW conversation (same live-doc-id, with --skill-id, repeat Step 4.5)
              NO  --> Is user explicitly starting a new topic?
                        YES --> NEW conversation (same live-doc-id, no --thread-id)
                        NO  --> FOLLOW-UP (pass --thread-id, NO --ext)
        |
        v
Run script (WITH --json, Bash timeout >= 600000ms) --> parse JSON, output data.answer verbatim
        |
        v
Extract thread_short_id + live_doc_id from stderr [state] line
        |
        v
Do NOT repeat or summarize the answer (already shown)

风格库脚本（run_style_library.mjs）

获取指定类别的风格库列表。先返回用户风格，再返回推荐风格。

node felo-superAgent/scripts/run_style_library.mjs --category TWITTER --accept-language en

选项：

• --category <category>（必需）——可选值：TWITTER、INSTAGRAM、LEMON8、NOTECOM、WEBSITE、IMAGE
• --accept-language <lang>——标签/标记所用的语言（例如 en、zh-Hans、ja）。默认值：en。始终传入此参数，使其与用户的语言一致。
• --json / -j——输出原始 JSON
• --timeout <seconds>——请求超时时间（默认值为 60 秒）

默认文本输出格式（每种风格占一个区块，区块之间空一行）：

对于 TWITTER 类别：

Style name: darioamodei
Style labels: Thoughtful long-form essays
Style DNA: # Dario Amodei (@DarioAmodei) Tweet Writing Style DNA
...（full styleDna content）

每个条目包含的字段（值为 null 或空的字段会省略）：

• Style name——始终包含（name 字段）
• Style labels——来自 content.labels（TWITTER）或 content.tags（其他类别），使用指定语言，以逗号分隔；不存在时省略
• Style DNA——来自 content.styleDna（TWITTER 类型）；不存在时省略
• Cover file ID——来自 coverFileId；为 null 或空时省略

用户创建的风格会显示在推荐风格之前。

参考资料

• SuperAgent API（Felo 开放平台）
• Felo 开放平台
• 获取 API 密钥（设置 -> API 密钥）