liveavatar-feedback

LiveAvatar 反馈收集

此技能用于收集集成反馈并发送给 LiveAvatar 团队。它会在以下三种情况下触发：

1. 实施完成后 — 用户刚完成集成（Embed、FULL 或 LITE）
2. 检测到挫败情绪 — 反复出错、明确抱怨或明显遇到阻碍
3. 用户明确提出请求 — 用户要求提供反馈或报告问题

何时触发

满足以下任一条件时，启用此技能：

• 用户表示已完成，或集成已正常运行
• 用户表达挫败情绪（“这坏了”“为什么不起作用”“我卡住了”）
• 用户明确要求提供反馈、报告 bug 或分享建议
• 集成过程中，你看到同一步骤有 3 次或更多失败尝试
• 用户表示要放弃或中止集成

不要在实现过程中途主动触发。 等待自然的暂停时机或完成节点。

步骤 1：从对话中收集上下文

在提示用户之前，查看对话历史并在内部整理：

• 用例 — 用户正在构建什么（例如，“用于 SaaS 仪表板的客户支持虚拟形象”）。信息可来自需求探索阶段、用户陈述的目标或其代码库。
• 阻碍 — 集成过程中导致不顺畅的任何因素。留意：遇到的错误、需要重试的步骤、令人困惑的 API 行为、无提示的失败、缺失的文档，或用户明确抱怨的任何问题。

将两项内容分别整理成简短、客观的摘要。这些是由 Agent 起草的遥测信息——发送前会由用户审核。

步骤 2：征求用户许可并收集其他反馈

发送任何内容之前，必须获得用户明确许可。 展示你整理的内容，并请用户批准、修改或拒绝。

根据上下文调整语气——成功后可以表达祝贺，用户感到挫败时则应表示理解。

成功实施后：

Your LiveAvatar integration is working! The LiveAvatar team collects anonymous integration feedback to improve the developer experience. Would you be okay with me sending a short summary?

Here's what I'd send:
- **Use case:** <your compacted summary>
- **Blockers:** <your compacted summary, or "None">

Want to add anything else in your own words? (Feature requests, suggestions, general thoughts — totally optional.)

**Nothing is sent until you say yes.** You can also edit or remove anything above.

检测到挫败情绪时：

It looks like this has been a rough integration. The LiveAvatar team actively collects developer feedback to fix exactly these kinds of pain points. Would you be okay with me sending them a summary of what happened?

Here's what I'd send:
- **Use case:** <your compacted summary>
- **Blockers:** <your compacted summary of what went wrong>

Want to add anything in your own words? (No pressure — but this goes directly to the team that can fix it.)

**Nothing is sent until you say yes.** You can edit or remove any of the above.

用户明确要求提供反馈时：

I can send feedback directly to the LiveAvatar team. Based on our conversation, here's what I've gathered:

- **Use case:** <your compacted summary>
- **Blockers:** <your compacted summary, or "None">

Want to add anything else in your own words?

**Nothing is sent until you give the go-ahead.** Feel free to edit any of the above.

等待用户明确批准（例如，“是”“发送吧”“看起来不错”“继续”）。如果用户拒绝、表示不同意或忽略提示，不要发送请求。直接放弃。

步骤 3：映射到字段

字段	来源	内容
use_case	Agent 根据对话整理	简短概述用户正在构建的内容（例如，“用于 SaaS 仪表板的客户支持虚拟形象”）
blockers	Agent 根据对话整理	导致不顺畅的问题——错误、重试、困惑、无提示的失败（例如，“因缺少 context_id 导致虚拟形象静默无响应——未抛出错误，花了 30 分钟才查明原因”）
additional_feedback	用户原话，逐字照录	提示用户时，用户写下的自由文本——功能请求、建议、一般想法。请使用用户的原话，不要改写或总结。

这三个字段均为可选字段。不适用的内容可省略或传入 null：

• 集成过程中没有遇到挫折或问题？省略 blockers。
• 用户没有写其他反馈？省略 additional_feedback。
• 无法根据上下文确定用例？省略 use_case。

步骤 4：发送反馈（仅在获得明确同意后）

只有用户在步骤 2 中明确批准后，才能执行此步骤。 如果用户拒绝、修改内容或未作回应，就到此为止。

此调用通过 X-API-KEY 在后端执行。

curl -X POST https://api.liveavatar.com/v1/feedback/agents \
  -H "X-API-KEY: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback_data": {
      "use_case": "Customer support avatar",
      "blockers": "Latency issues with long responses",
      "additional_feedback": "Would love multi-language support"
    }
  }'

构造请求

• use_case 和 blockers：使用步骤 2 中向用户展示的整理摘要（包含用户要求的任何修改）。
• additional_feedback：逐字粘贴用户的自由文本。不要改写。
• 不适用的字段可省略或传入 null。
• 如果用户在步骤 2 中修改了摘要，请使用修改后的版本。
• 如果环境中有用户的 API 密钥（例如，HEYGEN_API_KEY 或 LIVEAVATAR_API_KEY），请使用该密钥。否则，告诉用户提交反馈需要其 API 密钥。

示例载荷

仅包含 Agent 精简后的遥测数据（用户没有提供其他反馈）：

{
  "feedback_data": {
    "use_case": "Customer support avatar for e-commerce site",
    "blockers": "Silent avatar due to missing context_id — no error thrown, took 30 min to diagnose"
  }
}

包含用户原话的完整载荷：

{
  "feedback_data": {
    "use_case": "Real-time sales coach avatar for CRM",
    "blockers": "Custom LLM setup required 3 separate API calls (secret, config, session token) before first test",
    "additional_feedback": "The sandbox is great. Would be nice if sessions lasted longer than 1 min. Also would love multi-language support."
  }
}

第 5 步：确认提交

发送后，向用户确认：

Feedback sent to the LiveAvatar team — thanks for sharing.

保持简短。如果请求失败（例如 API 密钥无效），请告知用户，并提出向其展示 curl 命令，供其手动发送。

注意事项

1. 必须征得同意。 未获得用户明确的“同意”前，绝不发送请求。如有疑问，请再次询问。如果用户忽略提示，请勿发送。
2. 不要捏造 additional_feedback。 该字段只能包含用户原话。use_case 和 blockers 可以由 Agent 精简，但 additional_feedback 必须是用户输入的原文，否则就完全省略。绝不要自行生成、总结或预填此字段——如果用户没有写任何内容，就从载荷中省略该字段。
3. 发送前先展示。 始终向用户展示你计划发送的确切内容，并允许其在发送请求前编辑或删除任何内容。
4. 不要打断流程。 如果用户正在进行实现工作，不要突然开始收集反馈。请等待合适的间隙。
5. 需要 API 密钥。 此端点使用 X-API-KEY。如果你无法访问该密钥，请向用户展示 curl 命令，而不是悄无声息地失败。
6. 所有字段均为可选。 有效请求可以只填写一个字段，其余字段省略或设为 null。