widget-forms

Widget Forms Host Adapter

规范 Agent 中的原始 <widget>、<choices/> 和 <visual-option> 标签仅在 ChatCut 内渲染。绝不要从已发布的 Codex 或 Claude Code 插件发出这些标签。

语义契约映射

此适配器负责定义插件宿主如何实现调用方与宿主无关的表单契约。它不决定工作流需要哪些字段。

按以下方式映射语义字段类型：

• short_text：一个文本输入框。
• explicit_consent：一个明确且初始未选中的确认控件，使用调用方提供的完整本地化文案。附件或其他已提交字段都不算作同意。
• audio_reference：插件表单无法录制或上传媒体。渲染其他字段，提示用户将音频附加到对话中，然后加载 asset-import。将导入的 ChatCut 音频 assetId 返回给调用工作流；绝不要将本地路径、附件 URL 或原始字节作为资源 ID 返回。
• playable_single_choice：一个选择界面，包含稳定的选项值、本地化标签，以及宿主支持时可播放的媒体。若宿主返回可见标签，则在上下文中保留值到标签的映射。
• playable_preview：一个仅用于展示、不提交的音频界面，使用调用方提供的确切运行时媒体 URL。只能使用宿主支持的安全媒体渲染器；绝不要发出原始 <audio> HTML，也不要将 URL 作为普通文字展示。

Codex

调用 ChatCut MCP 工具 ask_followup_questions。将相关字段放入同一个表单，使用用户的语言编写可见文字；调用后暂停，直到已提交的答案出现在聊天中。字段和选项的形状以当前工具架构为准。

将 playable_single_choice 映射为一个 single 字段，并设置 variant:"voice"。将每个稳定值用作选项 ID，并确保其本地化标签、说明和 audioUrl 与调用方提供的同一条目关联。没有可播放媒体的操作项不设置 audioUrl。

将 MG 参考风格选择映射为一个 single 字段，并设置 variant:"visual"。将参考 ID 用作选项 ID，短标题用作标签，并将所选详情中的 heroPreview.url 用作 preview。添加一个标签为用户所用语言中的“其他”的 __other__ 选项；工具会提供其文本输入框。该分支接受新的偏好或再要一批结果的请求；不要另加一个“显示更多”选项。将所选参考 ID 返回给 MG 技能；由该技能负责应用。不要将 apply_preset 直接绑定到参考 ID。

示例字段：将参考占位符替换为获取的候选列表，并将标签本地化：

{
  "id": "mg_style",
  "label": "Choose a Motion Graphics style",
  "type": "single",
  "variant": "visual",
  "options": [
    { "id": "REFERENCE_ID", "label": "TITLE", "preview": "HERO_PREVIEW_URL" },
    { "id": "__other__", "label": "Other" }
  ]
}

“其他”答案会返回发现流程，不会应用风格或开始制作。在下一步中保持图像选项 ID 不变。

将 AI 头像身份选择映射为一个 single 字段，并设置 variant:"visual"。将实时的 identityId 用作选项 ID，将返回的 name 用作标签，将 previewVideoUrl 用作 previewVideo，并将 previewImageUrl 用作 preview。图像仍作为封面图，并在视频加载失败时自动回退。将 create_avatar 保留为仅含标签的选项。选择它时，将该值返回给工作流；它不会打开 ChatCut 的原生头像对话框，因此请另行请求源附件并使用 asset-import。

不要仅为展示 playable_preview 而调用 ask_followup_questions，因为被动预览不是问题。可用时使用 Codex 支持的音频附件／媒体渲染功能。如果此宿主会话没有安全的运行时 URL 音频渲染器，请说明可在 ChatCut 项目资源中查看预览，并继续执行调用方单独的分支决策；不要输出 HTML、裸 URL 或伪造的 widget 标签。

将 explicit_consent 映射为一个仅包含一个确认选项的单选字段。将调用方提供的完整确认文案用作其标签，且不要预先选中。将每个阻塞字段标记为必填，并在提交后核验所有必填答案，再继续。

Claude Code

遵循 chatcut-plugin-basics-claude 中的结构化输入方案：使用一个 visualize.show_widget Elicitation 表单，仅通过 .elicit-submit 提交，并等待用户发送填写好的提示词。不要在 Claude Code 中调用 ChatCut 的 ask_followup_questions，因为该宿主不会呈现其 MCP-App 结果。

将 explicit_consent 映射为未勾选的复选框，并使用调用方提供的完整本地化文案。不要为 audio_reference 添加文件选择器；在表单外请求用户附加对话，然后在用户发送附件后加载 asset-import。

对于 playable_single_choice，通过 ${CLAUDE_PLUGIN_ROOT}/assets/widget-media/manifest.json 解析捆绑媒体键；如果键不存在，则使用仅含标签的卡片，且绝不嵌入或处理原始源 URL。将稳定值保存在标签到 ID 的映射中，而不是将其暴露为 DOM 音频键。运行时媒体 URL 不在捆绑清单中：不要将其嵌入 Elicitation HTML。通过宿主常规的安全链接／音频界面展示，然后使用仅含标签的确认控件。

AI 头像预览属于运行时目录媒体，未捆绑在插件清单中。将每个权威 identityId 映射到其返回的 name，在 Elicitation 中使用仅含标签的可选卡片，并告知用户可在 ChatCut 的 AI Avatars 库中查看实时视频预览。绝不嵌入或打印提供方预览 URL。create_avatar 选择会返回工作流，然后按常规的对话附件加 asset-import 路径处理。

对于 MG 参考选项，在同一清单中查找确切的参考 ID（entries[referenceId]，例如 mg-reference:style:… 键）。图像条目会提供 path；将其与清单中不可变的 baseUrl 组合解析，并在 Elicitation 表单中将图像显示在简短标题旁边。将参考 ID 映射到显示标签。不要用名称相似的预设替代。

清单可能尚未包含新添加的参考项。对于缺失条目，使用仅含标签的选项，并说明可在 ChatGPT 中查看这些选项的图像预览；不要臆造 CDN 路径，不要在对话期间下载或重新发布媒体，也不要嵌入运行时 S3 URL。添加一个仅含标签的“其他”选项，并附带文本输入框。对其他批次的偏好或请求应返回发现阶段，而不是应用样式。