liveavatar-feedback

用途

LiveAvatar Feedback 是一个面向开发者的反馈收集技能，用于把 LiveAvatar 集成过程中的体验反馈发送给 LiveAvatar 团队。它适用于 LiveAvatar 的 Embed、FULL 或 LITE 集成场景。

触发时机

满足以下任一条件时激活：

• 用户表示集成已完成或已正常工作；
• 用户表达受挫，例如“this is broken”“why doesn't this work”“I'm stuck”；
• 用户明确要求提供反馈、报告 bug 或提出建议；
• 集成过程中同一步骤出现 3 次以上失败尝试；
• 用户表示放弃或中止集成。

不要在实现过程中无提示地触发，应等待自然停顿或完成节点。

主要能力与使用方式

第一步：从对话中收集上下文

在提示用户之前，先回顾对话历史并静默整理两项内容：

• 用例（use_case）：用户正在构建什么，例如“customer support avatar for a SaaS dashboard”。来源可以是发现阶段、用户陈述的目标或其代码库。
• 阻碍（blockers）：集成中造成摩擦的任何问题，例如遇到的错误、需要重试的步骤、令人困惑的 API 行为、静默失败、缺失的文档，或用户明确抱怨的内容。

将两者压缩为简短、事实性的摘要。这些是智能体起草的遥测内容，发送前会由用户审阅。

第二步：请求用户许可与补充反馈

发送任何内容前必须获得明确许可。向用户展示已整理的内容，并请其批准、编辑或拒绝。语气需随情境调整：成功时用庆祝语气，受挫时用共情语气。

集成成功后的提示示例：

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 else 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.

等待用户明确批准（例如“yes”“send it”“looks good”“go ahead”）。如果用户拒绝、不回应或忽略提示，则不要发送，直接放弃。

第三步：映射到字段

字段	来源	内容
use_case	智能体从对话压缩	用户正在构建内容的简短摘要，例如“Customer support avatar for SaaS dashboard”
blockers	智能体从对话压缩	造成摩擦的原因——错误、重试、困惑、静默失败，例如“Silent avatar due to missing context_id — no error thrown, took 30 min to diagnose”
additional_feedback	用户原话，逐字	用户在提示时写下的自由输入——功能请求、建议、一般想法。使用用户原话，不要改写或总结

三个字段均为可选。不适用时省略或传 null：

• 集成中没有受挫或问题？省略 blockers。
• 用户没有写补充反馈？省略 additional_feedback。
• 无法从上下文确定用例？省略 use_case。

第四步：发送反馈（仅在明确同意后）

仅当用户在第二步明确批准后才执行此步骤。如果用户拒绝、编辑或未回应，则到此停止。

该调用在后端使用 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：使用第二步向用户展示的压缩摘要（含用户要求的任何编辑）。
• additional_feedback：逐字粘贴用户的自由文本，不要改写。
• 不适用字段省略或传 null。
• 如果用户在第二步编辑了摘要，使用编辑后的版本。
• 如果环境中存在用户的 API key（例如 HEYGEN_API_KEY 或 LIVEAVATAR_API_KEY），则使用它；否则告知用户需要其 API key 才能提交反馈。

示例载荷（仅智能体压缩遥测，用户无补充反馈）：

{
  "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."
  }
}

第五步：确认提交

发送后向用户确认：

Feedback sent to the LiveAvatar team — thanks for sharing.

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

注意事项

• 同意是强制性的。 没有用户明确的“yes”绝不发送请求。如有疑问，再次询问。如果用户忽略提示，不要发送。
• 不要编造 additional_feedback。 该字段只能是用户原话。use_case 和 blockers 由智能体压缩，但 additional_feedback 必须是逐字用户输入或完全省略。绝不自行生成、总结或预填该字段——如果用户没有写任何内容，就从载荷中省略。
• 发送前先展示。 始终向用户展示计划发送的确切内容，并允许其在发送前编辑或删除任何内容。
• 不要打断流程。 如果用户正在实现过程中，不要跳到反馈收集，等待自然停顿。
• 需要 API key。 该端点使用 X-API-KEY。如果没有访问权限，向用户展示 curl 命令，而不是静默失败。
• 所有字段均为可选。 一个有效请求可以只填充一个字段，其余省略或为 null。

适用场景

适用于使用 LiveAvatar 进行集成开发的开发者，在集成完成、遇到困难或主动希望反馈时，通过智能体协助整理并提交结构化反馈。

限制

• 必须获得用户明确同意才能发送。
• 需要有效的 API key（X-API-KEY）。
• additional_feedback 不得由智能体生成或改写。
• 不应在实现过程中无提示触发。
• 关于收费、价格、平台支持范围等信息，资料中暂未提供。