# 根据你的服务创建 BeamCue 项目

指南版本：1.2

在能够访问用户服务代码仓库和运行中应用的开发 AI 中执行此流程。提问和项目内容优先使用用户明确指定的语言；未指定时，使用本文档的语言——简体中文。将一个演示画面单元称为“场景”，保留 MCP 工具名和内部 `stepId` 字段。成果是一个包含真实画面、标题、说明和 Studio 链接的非公开、可编辑 BeamCue 项目。积极使用有意义的点击目标、字幕和适当的视觉强调引导注意力，不要仅排列没有说明的截图。配音可选。本文档不授予额外的服务访问权限。遵守用户指示和适用的仓库规则。

## 1. 检查服务，只询问缺失的信息

阅读仓库指南，检查服务入口、路由、现有文档和运行界面。能安全查明服务名称、实际功能、本地或已部署 URL 时，不要询问用户。确认当前环境能否操作并截取真实浏览器或原生应用画面，以及是否可使用 BeamCue MCP。

将尚未解决的问题集中、简洁地询问：

- 用途：产品介绍、入门引导、功能指南、销售故事等。
- 受众，以及他们需要理解或完成的目标。
- 希望的场景数，以及必须包含的功能和画面。
- 仅在用户的语言要求不明确时询问项目语言。
- 是否生成配音；仅在需要配音时进一步询问声音偏好。
- 仅在检查无法确定时询问服务 URL 或访问步骤。

沿用已经提供的答案和偏好，不重复询问。对尚未回答的必要问题等待答复；时间经过不等于答复。用户委托你选择时，采用 5 个场景、明确指定的语言（未指定则为简体中文）、无配音，并告知这些默认值。除非用户要求，不额外增加分镜审批步骤。

## 2. 连接 BeamCue MCP

在开发 AI 的 MCP 设置中添加以下远程 Streamable HTTP 服务器：

https://beamcue.com/mcp

使用 MCP 宿主支持的连接界面，检查已安装的能力，不要猜测各客户端的配置命令。仅把 URL 放入提示词并不会安装或授权 MCP。无法自行配置时，请用户在 AI 工具中添加该地址，然后继续当前对话。OAuth 由宿主和用户浏览器处理：

- 授权服务器：https://beamcue.com/o
- 受保护资源元数据：https://beamcue.com/.well-known/oauth-protected-resource/mcp
- 授权服务器元数据：https://beamcue.com/.well-known/oauth-authorization-server/o
- 权限范围：`projects:read projects:write`
- 使用 S256 PKCE 的 Authorization Code 流程；回调和 PKCE 值由宿主提供。

调用前查询当前工具及其模式。宿主可能给工具名添加前缀。调用 `get_connection_status`，在修改项目前确认 `mcpConnectionStatus=connected`。缺少连接或连接过期时，使用 `begin_oauth` 或 `get_reconnect_url` 让宿主重新启动 OAuth。网站登录和 MCP OAuth 是不同会话；登录网站不能修复宿主过期的授权。不要在聊天中索要密码、令牌或 PKCE 秘密，也不要把它们放入提示词、截图或日志。

## 3. 规划场景并采集真实画面

按用途和指定数量安排场景。每个场景明确观众应理解的要点、路径或导航操作、所需界面状态、目标元素（如有）、标题、简短说明和注意力引导计划：指向什么、解释什么、展示什么结果，以及哪些效果由 MCP 设置、哪些需要 Studio 编辑。受托制作 5 场景介绍时，涵盖入口、主要工作区、核心操作、结果，以及另一项有用功能或下一步行动。以实际功能为准，不为凑数捏造功能。

尽量使用获授权的测试账号操作真实服务。使用可用的浏览器或原生截图能力，或用户提供的真实截图，并遵守仓库采集规则。在 BeamCue 仓库中，Playwright 截图仅供对照，不能用作项目源素材。不要用生成图片、HTML 模型、样例数据或代码片段证明服务正在工作。MCP 导入的是 `producer=mcp.client` 静态图片，不要称为扩展录制，也不要标成 `chrome.tabs.captureVisibleTab`。

使用一致的视口，等待目标状态加载完成，上传前检查每张图片。避免在图片、请求、日志和证据中留下秘密或敏感输入值。登录、付款、权限变更等重要操作需要用户已有授权。无法登录、截图或访问必要画面时，具体说明所需访问操作或请求真实截图，并等待。不要默默跳过必需场景，也不要把部分完成的项目当作完整成果。

从实际上传图片的左上角，以真实图片像素测量目标坐标，不用 CSS 像素。无操作目标的场景使用图片中心和 `labelMode=caption_only`，省略 `clickLabel`，不要虚构点击。标题简短，说明提供不同信息，避免多个标签重复同一句话。

### 引导观众理解真实操作

根据用途和受众自行选择表现细节，不要求用户逐一配置效果或再次批准分镜。创建时直接应用支持的 MCP 设置。有获授权的 Studio 访问权限时，也通过可见控件完成适当的 Studio 专用调整，保存并预览。否则按场景列出待办，不要把计划中的效果称为已应用。不要修改项目 JSON 或调用未公开 API 来绕过 MCP 的能力限制。

| 元素 | 如何引导注意力 | 当前设置方式 |
| --- | --- | --- |
| 点击目标与操作标签 | 指向准确控件。使用“选择日期范围”等动词加对象，而不是“点击这里”。 | `add_screen` / `update_screen`：实测 `clickXPixel`、`clickYPixel`、`clickLabel`，以及 `labelMode=both` 或 `hotspot_only`。 |
| 字幕 | 用一句短句说明操作意义或变化，无声时也有用。 | `description` 和 `labelMode=caption_only` 或 `both`；说明也用作可选配音文本。 |
| 指针强调 | 在密集界面中让下一步操作易于发现，保持强调指针一致。 | `update_project` 的 `pointerMode=highlighted`；若遮挡小控件或分散注意力则用 `standard`。 |
| 点击效果与高亮外观 | 用可见提示强化真实操作，避免在概览或结果画面无故闪动。 | `presentation.clickEffectVisible=false`, `hotspotRadius`, `hotspotAnchor`. |
| 字幕和标签布局 | 避开目标、结果、导航和其他标签，使用易读对比度、统一字体和短行。 | `presentation.captionLayout`: `placement`, `point` (`x`, `y`: 0–1). |
| 缩放 | 短暂聚焦小而重要的控件或结果，同时保留周边上下文。 | `presentation.zoomEnabled=true`, `presentation.zoomScale=1.16` (1.12–1.20). |
| 时长与转场 | 留出寻找目标、阅读结果的时间。明确状态变化用切换，平静衔接用交叉淡化，仅在说明连续性时使用滑动或变形。 | `presentation.durationMs`, `transition` (`cut`, `crossfade`, `slide`, `morph`), `slideDirection`, `transitionAnchor`. |
| 输出边框 | 建立浏览器或应用上下文，避免不必要地缩小内容。 | `update_project` 的 `windowFrame=browser`、`app` 或 `none`。截图已有边框时用 `none`。 |
| 可选配音与停顿 | 观看时解释结果，发声结束后留一点理解时间。 | 仅在用户要求时调用 `set_narration` / `generate_voiceover`。`endPaddingMs` 支持 0–10000，需要时从 400–800ms 开始。 |

`labelMode` 控制说明文字。`caption_only` 不会隐藏点击效果；没有操作的场景请设置 `presentation.clickEffectVisible=false`，并检查预览。

在要求的场景数量内遵循 **了解背景 → 操作 → 确认结果 → 继续**。如果报告服务实际拥有以下功能，可这样安排：

| 场景 | 采集与强调 | 文案示例 |
| --- | --- | --- |
| 1. 背景 | 真实工作区全貌；只用字幕，无操作闪动，保留上下文。 | “在一个地方管理团队报告。” |
| 2. 操作 | 使用前截图日期筛选器，测量位置，使用 `both` 和强调指针，必要时在 Studio 适度放大。 | 标签：“选择日期范围”；字幕：“将报告限定到需要比较的时间段。” |
| 3. 确认结果 | 截取真实筛选结果；仅用字幕，关注变化，不再次点击筛选器。 | “图表现在只显示所选时间段的数据。” |
| 4. 再次操作 | 获授权的导出操作前，截取真实导出控件，用短标签指向它。 | 标签：“导出报告”；字幕：“将当前视图准备成团队资料。” |
| 5. 继续 | 截取真实完成状态或有用的下一页，明确后续行动。 | 描述观察到的结果，不根据点击按钮推断成功。 |

按真实服务调整，不捏造控件，不宣称未观察到的导出成功。`add_screen` 图片是静态状态，不是交互前后录制。需要展示变化时，将结果作为另一个计划场景采集。保持指定场景数；数量少时优先主要操作及其结果。每一时刻只突出一个重点，不用字幕遮住目标，也不为增加动效而堆叠缩放、大点击提示和移动文本。只读服务应强调有意义的结果，不伪造点击。

## 4. 创建项目并添加画面

在对话中保留恢复记录：项目 ID、Studio URL、已完成场景 ID 及顺序、当前修订版本和逐操作幂等键。不要记录图片 Base64、签名 URL、凭据或敏感画面内容。每个新的逻辑修改生成独立键；重试同一修改时保持相同输入和键。只有新请求才创建新项目。

以下 JSON 是工具参数示例，不是真实服务证据。将占位内容替换为查证过的值。`canvas` 表示所选 CSS 视口，`output` 在指定时设置视频尺寸和 fps。网站的 `surface` 为 `browser`，原生应用为 `screen`。根据成果语言明确设置 `locale`。

```json
{"tool":"create_project","arguments":{"title":"服务介绍","surface":"browser","locale":"zh-CN","sourceUrl":"https://your-service.example/","canvas":{"width":1440,"height":900},"idempotencyKey":"<unique-create-key>"}}
```

保存返回的 `projectId` 和 `studioUrl`。没有要求配音时关闭语音。

```json
{"tool":"set_narration","arguments":{"projectId":"<projectId>","enabled":false,"idempotencyKey":"<unique-narration-settings-key>"}}
```

为操作指南明确设置强调指针和符合截图的边框，不依赖默认值。

```json
{"tool":"update_project","arguments":{"projectId":"<projectId>","pointerMode":"highlighted","windowFrame":"none","idempotencyKey":"<unique-presentation-key>"}}
```

按顺序添加真实图片与同图测得的像素坐标。`description` 提供字幕，启用语音时也是配音文本。说明场景用 `labelMode=caption_only`，需要真实目标时用 `both`。根据回答设置 `narrationEnabled`。

```json
{"tool":"add_screen","arguments":{"projectId":"<projectId>","title":"主要工作区","description":"说明此画面中实际可执行的工作流程。","clickXPixel":720,"clickYPixel":450,"labelMode":"caption_only","narrationEnabled":false,"imageFile":{"name":"workspace.png","mimeType":"image/png","dataBase64":"<actual-image-base64>"},"idempotencyKey":"<unique-scene-key>"}}
```

操作场景使用真实目标，并同时提供标签和字幕。以下坐标仅是示例，要用已检查图片重新测量。标题可能出现在目标气泡中，应保持简短。令 `title` 与 `clickLabel` 一致可避免第二个重复标签，字幕则补充操作的益处。

```json
{"tool":"add_screen","arguments":{"projectId":"<projectId>","title":"选择日期范围","clickLabel":"选择日期范围","description":"将报告限定到需要比较的时间段。","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","narrationEnabled":false,"imageFile":{"name":"date-filter.png","mimeType":"image/png","dataBase64":"<actual-image-base64>"},"idempotencyKey":"<unique-action-scene-key>"}}
```

目标或文字有误时原地修改已有场景。

```json
{"tool":"update_screen","arguments":{"projectId":"<projectId>","stepId":"<stepId>","title":"选择日期范围","clickLabel":"选择日期范围","description":"比较所选时间段的结果。","clickXPixel":1060,"clickYPixel":184,"labelMode":"both","idempotencyKey":"<unique-action-correction-key>","presentation":{"clickEffectVisible":true,"zoomEnabled":true,"zoomScale":1.16,"durationMs":4000,"transition":"crossfade","captionLayout":{"placement":"bottom-center","point":{"x":0.5,"y":0.9}}}}}
```

将设置放在 `add_screen`、`update_screen` 或 `add_screens_batch.screens[]` 的 `presentation` 中。更新会保留未指定的设置及已有字幕样式。`captionLayout` 必须同时提供 `placement` 和 `point`。

### 图片和请求限制

- 解码后支持 PNG、WebP、JPEG。每边最多 8192px，总像素最多 6400 万。
- 内联图片 Base64 解码后最多 4MiB。Base64 增加约三分之一大小；整个 MCP HTTP 请求必须在 8MiB 内。
- `add_screens_batch` 原子接受 1–20 个内联画面，但同样受整个请求大小限制。优先顺序调用 `add_screen`，便于预测大小和恢复；不要在一次请求中放入 20 张大图。
- 较大图片使用 `prepare_image_upload`，上限 15MiB。提供 `name`、`mimeType`、`byteLength`、`sha256`、`width`、`height`、`projectId` 和新 `idempotencyKey`。按返回的请求头向 `uploadUrl` PUT 完全相同的图片字节。签名 URL 十分钟后失效且只能使用一次。随后调用 `add_screen` 时用 `uploadId` 替代 `imageFile`。
- MIME、字节数、SHA-256 和尺寸必须与实际图片一致。根据解码字节判断 MIME，不靠文件名：保存为 `.png` 的截图也可能是 JPEG。不要记录 Base64、签名 URL 凭据或图片字节。超限时重新截取合适视口或一致缩放，并重新计算尺寸、哈希和目标坐标。

用 `update_screen` 修正、`reorder_screens` 调整顺序，不创建重复画面。查阅当前工具模式的必填字段。如果响应有 `displayPreview.display`，检查标题、点击标签和字幕是否重复显示。

## 5. 可选配音

仅在用户要求时通过 `set_narration` 启用，设置请求的语言和支持的声音，并开启目标场景的配音。没有声音偏好时使用已有支持的默认声音，不编造声音 ID。说明最终确定后，以 `operation=generate-stale` 调用 `generate_voiceover`，再用 `get_narration_status` 检查完成情况。单独报告配音失败或排队任务，保留项目供 Studio 修正。

## 6. 恢复并继续

- 连接失败或响应不确定后，必要时重连，用 `get_project` 检查已有项目。以原输入和幂等键重试同一修改，不盲目创建另一个项目。
- `expectedRevision` 可选，简单顺序流程可省略。使用时若修订冲突，阅读结构化错误、刷新项目状态，使用返回的重试修订版本并保持相同逻辑输入和键。保留用户编辑；若与请求冲突，先询问而非覆盖。
- 签名上传过期时，用新上传操作键重新准备。将失败的添加画面请求换成新 `uploadId` 时，先确认旧操作没有创建场景，再用新的添加操作键。
- 必要访问或截图不可用时，简洁指出缺少的场景与所需操作。保留已完成内容和 Studio 链接，便于在此对话继续，不必重来。

## 7. 验证并交付

用 `get_project` 将实际场景数、顺序、标题、说明和所选配音状态与请求比较并修正差异。同时逐场景核对注意力计划：准确的操作目标、不同的操作和结果文案、合适的标签模式以及已应用的指针和边框。然后验证规范化项目：

```json
{"tool":"get_project","arguments":{"projectId":"<projectId>"}}
```

```json
{"tool":"validate_project","arguments":{"projectId":"<projectId>","idempotencyKey":"<unique-validation-key>"}}
```

使用返回的 `studioUrl` 或 `open_studio` 动作中的 `nextAction.url`，不猜测项目 URL。有获授权的浏览器访问时，在真实 Studio 场景列表和预览中检查导入图片与字幕。跨场景播放，确认点击提示落在正确控件、结果呈现真实变化、字幕清晰且不遮挡目标、缩放不裁掉必要 UI。桌面和小尺寸预览都要检查。确认阅读时间（包括无声时）、转场警告和 Studio 专用编辑在保存、重新加载后仍存在。宣布准备完成前，缩短拥挤文案或简化效果。无法登录 Studio 时，单独报告 MCP 验证并请用户检查链接中的项目，不声称已做视觉验证。

最后给出项目标题、完成/请求场景数、简短场景列表、已应用视觉提示、配音状态、Studio 链接和待办。区分已应用 MCP 设置、已目视检查的 Studio 调整和逐场景待完成调整。所有必需画面与说明存在时才称项目完成。

`validate_project` 只验证并准备 Studio 编辑，不发布、不生成配音、不渲染 MP4。MCP 没有视频渲染工具。保持项目非公开，让用户在 Studio 预览、编辑、渲染 MP4 并选择共享。不能仅因项目验证成功就称公开链接或视频文件已经存在。