lilimozi/ask-user-cards/ask-user-cards

Ask User Cards · 把请教做成一张安静的卡片

打断式提问（弹窗、模态、追问刷屏）抢走了用户的焦点，是不礼貌的。这张卡片是另一种礼仪：把整组问题一次排好，留在对话流里，像桌角的一本便签。用户什么时候答、答几题、跳不跳过，都由用户决定；答完点一次提交，答案自己回到会话里叫醒你。

何时铸卡

• 答案会改变产出结构：体裁、受众、深度、格式、技术选型——不同答案做出的是两样东西。
• 决策点有界且成组：两三个以上的有限选择可以同时收集时，一次铸卡胜过逐条追问。
• 校准类问题：语气 / 受众 / 篇幅 / 审美方向，选项可以预先穷举。
• 不可撤销动作之前：删除、外发、覆盖——把「确认 / 调整 / 取消」连同关键选项一起给出。
• 诊断类问题：「哪种症状最像你遇到的」比「描述一下你的问题」更快收敛。

何时不铸

• 只有一个简单问题：直接在对话里问，更轻。卡片是给「一组问题」的。
• 查得到的事实：自己查，不要拿检索能回答的事麻烦用户。
• 低风险的假设：选一个最合理的直接做，顺带说明假设即可。
• 用户正在流畅表达时：等他说完。卡片随时能发，话头断了接不回来。
• 开放式深谈：没有有界选项的问题（「你想表达什么」）属于对话，不属于表单。

如何出题

一张卡 2–6 题：6 是硬上限，超过说明任务该拆，不是卡片该加长。但默认朝 3 题以内努力——三题之内的卡片轻盈，一眼看完；写到第四题时先问自己：是真的需要，还是只是顺便问问。顺便问问的，咽回去。

• 题干是人话：「这篇内容主要写给谁看？」，而不是「请确定目标受众画像」。
• 选项 2–5 个，每个带一行 hint 说清代价或方向（「可以放开用术语，重架构细节」）。hint 是这张卡的灵魂：用户点的不是答案，是他理解的后果。
• `type` 三种：single 单选、multi 多选、text 自由文本。能用 single/multi 就别用 text——点一下永远比打一行字便宜。text 留给真正开放的（「还有什么一定要提到的？」）。
• `allowNote: true` 给选项题留一个「补充一句」的口子，列表困不住人的时候有出口。
• 所有题都可跳过。跳过不是失败，是用户把判断权交还给你——按你的品味继续，并在交付时说明你选了什么。
• 卡片内置一个「都交给你决定」按钮，一键全权委托。不要把它当成失败，那常常是最高的信任。

如何铸造

{
  "title": "动手之前，想先问你三件事",
  "template": "ask-user-cards/assets/ask-user.card.html",
  "state": {
    "uiLanguage": "zh",
    "title": "动手之前，想先问你三件事",
    "questions": [
      {
        "id": "audience",
        "text": "这篇内容主要写给谁看？",
        "type": "single",
        "allowNote": true,
        "options": [
          { "label": "泛读者", "hint": "多比喻少术语，重直觉与故事——这是你读者最多的一层", "recommended": true },
          { "label": "同行开发者", "hint": "可以放开用术语，重架构与细节" }
        ]
      }
    ],
    "answers": {},
    "submittedAt": null,
    "allDefault": false
  }
}

state 契约（铸造时整体替换模板默认快照，字段缺一不可）：

title / intro / questions 是定稿内容，铸造后不变；答案由卡片自己持久化。题干的 id 用短英文，答案 payload 以它为键。

发出卡片后：说一句「问题都在卡里，不急」，然后继续做不依赖答案的部分，或安静停下。不要催促，不要复述卡片内容——卡片自己会说话。

提交之后

用户点提交，卡片 emit ask-user-answers，事件带着 payload 落回会话：

{
  "title": "…",
  "allDefault": false,
  "submittedAt": "…",
  "answers": {
    "audience": { "question": "…", "answer": "同行开发者", "note": "…", "skipped": false }
  }
}

收到后：用一句短话确认理解，然后直接干活。skipped: true 的题按你的判断来；allDefault: true 就是全权委托。不要把答案逐条复述给用户听——他刚填完，不聋。

用户可以「修改答案」后再次提交，你会收到新的 ask-user-answers 事件，以最新一次为准。

卡片侧行为（无需你管，知道即可）

• 整卡固定高度，一次一题，左右翻页；页间切换布局纹丝不动，内容超出在题区内滚动。
• 底部圆点一身三职：位置、已答变绿、点击跳题；作答实时持久化到 card state，重开回到上次翻到的那页。
• 「都交给你决定」放在最后一题的选项之后——它是回答的一部分，不是界面 chrome。
• 提交后切换为答案摘要，同高不推挤对话流；可「修改答案」后再次提交。
• 在 Hana 之外（standalone）打开时，提交降级为「复制回答」：答案序列化成文本，用户粘贴回对话，你照常收下继续。
• 所有交互在卡片本地完成，无网络请求；唯一出卡通道是提交时的那一次 emit。