reveal-feedback

与 Reveal 反馈基础设施交互，以管理产品、创建审核任务、阅读 AI 分析的用户反馈、获取情绪洞察、查看提交、管理通知、注册 Webhooks 以及生成营销内容（脚本、图像、视频）。当用户询问产品反馈、用户评论、测试任务、情绪分析、热门问题、评论提交、营销视频、营销图像、视频脚本或与其 Reveal 帐户相关的任何内容时使用。

## 概述（中文）

与 Reveal 反馈基础设施交互，以管理产品、创建审核任务、阅读 AI 分析的用户反馈、获取情绪洞察、查看提交、管理通知、注册 Webhooks 以及生成营销内容（脚本、图像、视频）。当用户询问产品反馈、用户评论、测试任务、情绪分析、热门问题、评论提交、营销视频、营销图像、视频脚本或与其 Reveal 帐户相关的任何内容时使用。

## 原文

# Reveal Feedback Infrastructure

Reveal is a universal feedback platform where human reviewers screen-record themselves using products and provide AI-analyzed feedback. This skill connects to the Reveal REST API to manage the full feedback lifecycle — from collecting reviews to generating marketing content from that feedback.

## Authentication

All API calls require the `REVEAL_API_KEY` environment variable. The key is a vendor API key generated from the Reveal dashboard under Settings → API Keys.

Every request uses this header:
```
Authorization: Bearer $REVEAL_API_KEY
```

Base URL: `https://www.testreveal.ai/api/v1`
(Override with `REVEAL_BASE_URL` env var if set.)

## Capabilities

### 1. Check dashboard overview

Fetch products, active review tasks, and unread notifications to give the user a quick status update.

Steps:
1. GET `/products` to list vendor products
2. GET `/review-tasks?status=active` to list active tasks
3. GET `/notifications?unread=true&limit=5` to get unread notifications
4. Summarize: product count, active tasks with submission progress, and recent notifications

### 2. Get feedback insights for a product

Fetch AI-aggregated insights: top issues, top positives, sentiment distribution, and suggestions.

Steps:
1. GET `/products` to find the product ID matching the user's request
2. GET `/insights/{productId}` to get aggregated insights
3. Present: sentiment breakdown, top issues ranked by frequency, top positives, unique issue count

### 3. Get product analytics

Fetch quantitative metrics for a product.

Steps:
1. GET `/products/{productId}/analytics`
2. Present: total submissions, analyzed count, average completion rate, sentiment distribution, top issues, top positives

### 4. View review submissions

Get individual review submissions with transcripts, AI analysis, sentiment, and issue counts.

Steps:
1. GET `/review-tasks?status=active&limit=5` to find the relevant task (or use a task ID if provided)
2. GET `/review-tasks/{taskId}/submissions` to get all submissions
3. For each submission, present: status, sentiment, issue count, positive count, transcript preview

### 5. Create a review task

Create a new user-testing task so reviewers can test a product.

Steps:
1. GET `/products` to find the product matching the user's description
2. Extract from the user's message: title, objective, steps, feedback focus, reviewer count
3. POST `/review-tasks` with body:
```json
{
  "title": "extracted title",
  "productId": "matched product ID",
  "requiredReviewers": 5,
  "instructions": {
    "objective": "what the reviewer should accomplish",
    "steps": "step-by-step instructions",
    "feedback": "what feedback to focus on"
  }
}
```
4. Confirm creation with task ID and details

### 6. Update a review task

Close, pause, or modify an existing review task.

Steps:
1. PATCH `/review-tasks/{taskId}` with fields to update (status, title, description, requiredReviewers)
2. Confirm the update

### 7. List products

Show all products registered on the vendor's Reveal account.

Steps:
1. GET `/products?limit=50`
2. Present each product: name, category, platform support (web/mobile), website

### 8. Get notifications

Check for new activity on Reveal.

Steps:
1. GET `/notifications?unread=true&limit=20`
2. Present notification messages with timestamps
3. If user says to mark as read: PATCH `/notifications` with `{"markAllRead": true}`

### 9. Register a webhook

Set up real-time event notifications.

Steps:
1. POST `/webhooks` with body:
```json
{
  "url": "https://user-provided-url",
  "events": ["review.submitted", "review.analyzed", "task.completed", "video.generated"]
}
```
2. Return the webhook ID and signing secret. Instruct user to store the secret securely.

### 10. List webhooks

Steps:
1. GET `/webhooks`
2. Present each webhook: URL, subscribed events, active status

### 11. Summarize feedback into marketing highlights

Turn raw user feedback into polished, persuasive marketing statements.

Steps:
1. Collect the positive feedback strings (from insights or submissions)
2. POST `/marketing/summarize-highlights` with body:
```json
{
  "highlights": ["feedback string 1", "feedback string 2", "..."]
}
```
3. Response contains `summary` — an array of marketing-ready highlight strings

### 12. Generate a marketing video script

Generate a 30-second video script from product feedback or the product description.

Steps:
1. GET `/products` to find the product ID
2. Optionally GET `/insights/{productId}` to extract positive highlights
3. POST `/marketing/generate-script` with body:
```json
{
  "productId": "the product ID",
  "positiveHighlights": ["highlight 1", "highlight 2"],
  "scriptType": "problem-solution"
}
```
   - `positiveHighlights` is optional; if omitted the product description is used
   - `scriptType` options: `problem-solution`, `empathetic`, `aspirational`, `story-driven`
4. Response contains `script` — a formatted script with `[Scene X: Title]` headers, Visual and Narration per scene

### 13. Generate a marketing image

Create a marketing image for a product with AI.

Steps:
1. GET `/products` to find the product ID
2. POST `/marketing/generate-image` with body:
```json
{
  "productId": "the product ID",
  "prompt": "Modern dashboard showcasing the key analytics features",
  "styleName": "Modern Gradient",
  "tagline": "Insights that drive growth"
}
```
   - `prompt` is required — the creative direction for the image
   - `styleName` and `tagline` are optional
3. Response contains `imageUrl` — a public URL to the generated image

### 14. Edit and refine a script

Parse a script into structured scenes and apply edits — change narration/visuals, add new scenes, or remove scenes.

Steps:
1. POST `/marketing/edit-script` with body:
```json
{
  "script": "the current script text",
  "operations": [
    { "action": "edit", "sceneNumber": 3, "narration": "Updated narration text" },
    { "action": "add", "position": 4, "title": "New CTA", "visual": "Happy customer using phone", "narration": "Try it free today!" },
    { "action": "remove", "sceneNumber": 6 }
  ]
}
```
   - `operations` is optional — omit it to just parse the script into structured scenes
   - `action: "edit"` — update title, visual, or narration of an existing scene (only include fields to change)
   - `action: "add"` — insert a new scene at `position` (or append if omitted)
   - `action: "remove"` — delete a scene by number (scenes renumber automatically)
2. Response contains both the updated `script` string and a `scenes` array with structured scene objects

### 15. Search stock media for video scenes

Find stock images and videos from the Pictory library to use in specific video scenes.

Steps:
1. GET `/marketing/media-search?keyword=business+meeting&page=1`
   - `keyword` is required — the search term
   - `category` and `page` are optional
2. Response contains `results` — array of `{ url, type, thumbnail }`
3. Use the `url` values in the `customMediaUrls` field of generate-video to assign media to specific scenes

### 16. Generate a marketing video (full pipeline)

Create a full marketing video from a script. This is a multi-step async workflow.

Steps:
1. Generate a script first (capability 12) or have the user provide one
2. Optionally refine the script (capability 14) — edit scenes, add/remove as needed
3. Optionally search for stock media (capability 15) to use in specific scenes
4. POST `/marketing/generate-video` with body:
```json
{
  "productId": "the product ID",
  "script": "the full script with [Scene X: Title] headers",
  "voiceOver": { "speaker": "Jackson", "speed": 100 },
  "musicVolume": 0.4,
  "customMediaUrls": {
    "1": "https://stock-media-url-for-scene-1",
    "3": "https://stock-media-url-for-scene-3"
  }
}
```
   - `customMediaUrls` is optional