visual-qna

视觉问答

概述

在由 Playwright 驱动的浏览器中，将一组结构化问题呈现为交互式表单，让用户点击选择答案（单选或多选，每题都包含“其他”选项和自由文本备注），然后将答案作为结构化数据读取。适用于需要批量做出决策的场景，因为原生的一次一个问题的终端流程速度较慢。

核心思路：通过 Playwright MCP 将可复用的表单引擎注入 about:blank——无需服务、文件或端口。

适用场景

• 一批（约 3 个或更多）选择题：头脑风暴决策、选项选择、问卷、A/B/C 选项。
• 希望每题都能填写备注，并能在固定选项之外选择“其他”。
• 希望将答案作为结构化数据交回，以便采取后续行动。

不适用场景

• 模型、线框图、示意图、视觉设计对比 → 这些属于视觉伴侣的工作，不适用于此技能。此技能用于回答问题，而不是查看图片。
• 一两个简单问题 → 直接在终端提问，或使用原生的 AskUserQuestion 工具。
• Playwright MCP 不可用 → 请参阅“要求”。

要求（硬性依赖）

此技能需要 Playwright MCP 浏览器工具（browser_navigate、browser_evaluate、browser_take_screenshot）。如果这些工具不可用，请停止并告知用户启用 Playwright MCP 插件——不要尝试变通方案。（Playwright 会阻止 file:// URL，而沙箱也经常会阻止本地 HTTP 服务，因此没有可靠的替代方案；此技能在设计上只能使用 Playwright。）

工作流程

1. 确认 Playwright MCP 可用。 如果不可用，请报错并停止（参阅“要求”）。
2. 使用 browser_navigate 导航到 about:blank。
3. Read 同级文件 qa-form.js，并将其完整内容作为 function 参数传给 browser_evaluate。（它已经是一个 () => {} 箭头函数；运行后会在页面上定义 window.__qaInit、__qaToggle、__qaNote、__qaResults。）
4. 使用 browser_evaluate 执行 () => window.__qaInit(CONFIG)，其中 CONFIG 是你的问题集（参阅“配置架构”）。这会渲染表单。
5. 使用 browser_take_screenshot，让用户看到表单。
6. 在聊天中以简短文本列表列出问题，供用户参考，然后告知用户：“在浏览器中点击选择答案，完成后回复我。” 随后结束本轮。
7. 下一轮中，使用 browser_evaluate 执行 () => window.__qaResults()，并解析返回的 JSON。合并用户补充的任何终端文本，然后将结构化结果交给请求这些结果的一方。

如需重新提问或修改：再次调用 window.__qaInit(newConfig)（这会重置状态），或者在用户继续编辑后直接重新读取结果。

配置架构

{
  title: "Sub-project 6 — Dashboard Composition",
  questions: [
    {
      id: "q1",                       // stable, simple slug (no quotes/spaces)
      title: "Layout model",
      detail: "Optional one-line context.",
      options: [
        { letter: "A", text: "...", recommended: true },
        { letter: "B", text: "..." }
      ],
      multi: false,                   // true = allow multiple selections
      allowOther: true                // default true; appends a dashed "O — Other"
    }
  ]
}

结果格式

window.__qaResults() 返回 JSON：

{
  selections: { q1: "B", q2: ["A", "C"], q3: "O" },  // string (single) or array (multi)
  notes:      { q3: "free text the user typed" }
}

• 当问题的选择值为真值时，即视为“已回答”（多选题需为非空数组）。
• "O" 表示用户选择了其他——请读取 notes[id] 获取具体内容。

不干扰视觉伴侣

此技能与任何头脑风暴用的“视觉伴侣”刻意分开：

• 它只使用 Playwright MCP 浏览器。它不会启动 HTTP 服务、开放端口，也不会写入 .superpowers/（或任何其他伴侣的会话目录）。
• 不要在有活跃视觉伴侣会话的同一轮中运行此技能——它们会在不同浏览器中争夺用户的注意力。
• 分工：视觉伴侣 =“看看这个模型/示意图”；visual-qna =“回答这些问题”。

常见错误

错误	修正方法
在页面中手写引擎	始终原样 Read 并注入 qa-form.js——不要重新实现。
尝试使用 file:// URL 或本地服务	会被阻止（Playwright / 沙盒）。只能使用 about:blank + 注入。
在用户回复前读取结果	渲染表单并结束本轮；只有在用户表示完成后，才读取 __qaResults()。
将其用于模型图或示意图	工具用错了——那是可视化配套工具。
id 中包含空格或引号	使用简单的 slug；它们会嵌入内联 onclick 处理程序中。
在 selections[id] 不存在时假定答案	不存在 = 未回答；请提问或视为未决定，不要推断。