qa-discussion

Q&A 讨论引导器

概述

系统化地与用户开展结构化的问答讨论。支持多种问题类型、跟踪进度、验证回答，并生成全面的总结报告。非常适用于评估、入门引导、反馈收集或教育互动。

核心功能

问题类型：

• 多选题：从选项中选择一个或多个正确答案
• 单选题：从选项中恰好选择一个正确答案
• 开放题：自由作答，可选进行验证

会话功能：

• 跟踪进度（第 X 题，共 Y 题）
• 一次只问一个问题，确保清晰易懂
• 对无效回答智能重新提问并提供有用反馈
• 完整记录回答及其验证状态
• 讨论完成后生成总结报告

适用场景

在以下情况使用此技能：

• 开展结构化评估或测验
• 通过系统化提问收集反馈
• 通过经过验证的知识检查引导用户熟悉内容
• 创建可跟踪进度的教育互动
• 开展需要记录回答的审计或合规检查

不适用场景：

• 问题较为随意或偏向对话式交流（自然聊天即可）
• 无需验证或跟踪回答
• 讨论以探索为主，而非结构化问答

流程

步骤 1：定义问题

创建包含所有必要元数据的结构化问题数组：

const questions: Question[] = [
  {
    id: 'q1',
    text: 'What is the capital of France?',
    type: 'single',
    options: ['London', 'Paris', 'Berlin', 'Madrid'],
    correctAnswer: 'Paris'
  },
  {
    id: 'q2',
    text: 'Select all that apply: Which are JavaScript frameworks?',
    type: 'multiple',
    options: ['React', 'Django', 'Vue', 'Laravel'],
    correctAnswers: ['React', 'Vue']
  },
  {
    id: 'q3',
    text: 'Explain why you chose your answer above',
    type: 'open',
    validation: (answer) => answer.length >= 10
  }
];

步骤 2：开展讨论

调用主函数以开始：

const session = await conductDiscussion(questions);

此技能将：

1. 清晰显示每个问题及进度指示器
2. 等待用户回答
3. 根据问题标准验证回答
4. 如果回答无效，则重新提问并提供有用反馈
5. 保存经过验证的回答
6. 转到下一个问题
7. 全部完成后生成总结

步骤 3：查看结果

访问会话数据以生成报告：

// Session structure:
{
  totalQuestions: number;
  completedQuestions: number;
  responses: Array<{
    questionId: string;
    text: string;
    answer: string;
    isValid: boolean;
    attempts: number;
  }>;
  summary: {
    totalAttempts: number;
    validResponses: number;
    invalidResponses: number;
    completionTime: number;
  };
}

显示约定

问题呈现：

• 清晰显示题号和总题数（例如，“第 1 题，共 5 题”）
• 突出显示问题文本
• 为选项编号，方便引用（1、2、3……）
• 根据问题类型提供不同说明：
  • 单选题：“请选择一个选项（输入编号）”
  • 多选题：“请选择所有适用选项（输入以逗号分隔的编号）”
  • 开放题：“请输入回答（至少 10 个字符）”

验证反馈：

• 输入无效：“选择无效。请输入 1、2、3 或 4”
• 多选题格式错误：“格式无效。请使用：1,2,3”
• 开放题验证失败：“回答太短。请提供更多细节”
• 输入为空：“回答不能为空”

进度显示：

• 每道题显示：“第 2 题，共 7 题”
• 问题之间留出明显间距，确保清晰易读
• 最后一道题后显示总结

错误处理

输入验证：

• 选择超出范围 → 重新提问并提示有效范围
• 格式错误（单选题输入了多个选项）→ 说明预期格式
• 回答为空 → 请用户作答
• 自定义验证失败 → 通过有用的消息说明标准

会话错误：

• 未提供问题 → 抛出清晰的错误
• 问题类型无效 → 在设置过程中验证
• 超时或中断 → 保存进度并允许恢复

核心原则

• 一次只问一个问题——绝不同时显示多个问题
• 清晰反馈——始终解释回答无效的原因
• 完整跟踪——记录每个回答及其验证状态
• 灵活验证——支持精确匹配、列表验证和自定义函数
• 方便用户——选项编号清晰、说明明确、消息有帮助
• 可恢复——支持根据需要暂停和恢复

使用示例

参见 @index.ts，查看完整实现，其中包括：

• 所有问题类型的完整 TypeScript 类型
• 全面的错误处理
• 实际应用示例
• 集成模式