questions-form

questions-form 是一个专为 Telegram 平台设计的结构化多问题表单交互协议 Skill。它通过标准化的内联按钮（Inline Buttons）机制，允许 AI Agent 在单次会话中同时抛出多个澄清性问题，用户可自主选择回答顺序，最终统一提交，极大提升了复杂需求收集的效率与用户体验。

核心用法遵循严格的六步协议：首先，Agent 内部定义问题对象（包含 ID、文本、选项列表）并初始化状态追踪器；随后发送表单引导语，接着为每个问题单独发送带内联按钮的消息（每行 2-3 个选项，"Other" 选项独立成行），并提供自由文本回退机制；待所有问题展示完毕后，发送包含"提交"与"取消"按钮的确认消息；在回调处理阶段，通过 form:<question_id>:<value> 格式的回调数据识别用户选择，记录状态变更，支持随时修改答案；最后，在提交时验证完整性，将收集到的结构化数据用于后续任务流程。

该 Skill 的显著优点在于其卓越的用户体验设计：相比传统的逐问等待模式，用户可自主控制回答节奏，减少了会话回合数；预定义选项与"Other"自由文本的混合模式兼顾了效率与灵活性；标准化的回调协议（form: 前缀）便于 Agent 快速识别与处理；清晰的按钮布局规范（每行 2-3 个按钮，明确的提交/取消标识）确保了移动端交互的友好性。

然而，该 Skill 也存在明显的局限性与缺点。首先是严格的平台锁定：协议深度依赖 Telegram Bot API 的内联键盘机制，无法迁移至其他即时通讯平台。其次是实现复杂度：开发者需要自行维护表单状态机（form_state）、处理自由文本输入的异步等待（awaiting_freetext）以及超时逻辑，增加了开发负担。此外，Telegram 对 callback_data 有 64 字节的严格长度限制，要求问题 ID 和选项值必须极度精简（建议使用 2-8 字符的 ID 和下划线连接的值）。最后，该模式明确不适用于单问题场景，对于简单的 yes/no 询问显得过于笨重。

该 Skill 适合以下群体：Telegram Bot 开发者构建复杂的用户 onboarding 流程；产品经理设计多维度需求收集系统；客服自动化场景中需要结构化收集用户偏好或问题详情的场景；以及任何需要通过枚举选项减少自由文本歧义、提升数据标准化程度的交互设计。

潜在风险主要包括：状态管理风险，若 Agent 实例重启或会话中断，未提交的表单状态可能丢失（尽管文档提到在 references/form-patterns.md 中处理中断恢复，但核心实现仍需开发者自行保证状态持久化）；平台依赖风险，Telegram API 的变更可能导致按钮渲染或回调机制失效；用户体验风险，若问题数量过多（超过 3-4 个），一次性发送多条消息可能造成信息过载；以及回调数据截断风险，若开发者未严格遵守短 ID 规范，可能导致回调数据被截断而引发逻辑错误。