nicobailon/pi-interview-tool

解决的问题

当代理需要用户澄清时，通常必须内联提问，这可能很笨拙。此工具将其转变为专用的交互式表单：它让代理呈现带有丰富上下文的结构化问题，让用户按自己的节奏收集答案，并接收结构化结果。它能优雅地处理中断，自动保存进度，并允许用户恢复放弃或超时的会话。

工作原理

代理通过 interview() 函数调用该工具，传入定义问题的 JSON 文件。该工具启动本地服务器，并在 macOS 上的原生 Glimpse 窗口（或其他地方的浏览器标签页）中打开表单。用户填写表单，自动保存到 localStorage，并有一个倒计时器，任何活动都会重置。用户提交后，响应返回给代理；如果取消或超时，代理收到 null。该工具还支持多个并发访谈：只有第一个会自动打开窗口，其他则排队以避免抢占焦点。如果会话是远程的（ssh/mosh），该工具会打印表单 URL 和访问提示，而不是打开本地窗口。超时和放弃的访谈会将其问题保存到恢复目录，以便稍后重试。

适用对象

使用 pi-agent 的开发者和用户，需要从实时用户那里收集结构化、交互式反馈——例如，澄清项目需求、收集偏好或在代理驱动的工作流中审查选项。当代理需要提出一系列带有丰富上下文（如代码片段、图表或表格）的问题时，它尤其有用。

亮点

• 支持单选、多选、文本、图片上传和信息面板——全程支持键盘导航
• 直接在问题中嵌入富媒体：图片、Chart.js 图表、Mermaid 图、表格和原始 HTML
• 推荐带有可配置的置信度（强/弱）和视觉权重（关键/次要）以指导决策
• 自动保存到 localStorage，并带有警告覆盖层的会话超时；进度永远不会意外丢失
• 会话恢复：放弃或超时的访谈保存到恢复文件夹，可稍后重试
• 多代理支持：并发访谈排队而不是争夺窗口，带有队列会话的 toast 切换器
• 支持 LLM 的“生成更多”和“审查选项”按钮可以创建新选项或重写问题以提高清晰度
• “询问选项”打开内联助手面板，带有提示芯片和自由形式的后续问题
• 可自定义主题（深色/浅色/自动），支持用户定义的 CSS 覆盖和切换热键
• 启动器选择：在 Glimpse、浏览器标签页或 Orca 管理的浏览器标签页中打开表单

工作原理

以下是流程的快速概述（更多细节在 README 中）：

1. 代理调用 interview() 并传入问题 JSON 文件。
2. 本地服务器启动，表单在所选启动器（Glimpse、浏览器或 Orca）中打开。
3. 用户按自己的节奏回答；每次更改都会自动保存并重置超时。
4. 提交时，响应发送回代理。取消或超时时，代理收到 null（或工具可以返回访谈 ID 以进行异步传递）。
5. 如果会话是远程的（ssh/mosh），该工具会打印表单 URL 和访问提示，而不是打开本地窗口。

生命周期

• 提交（⌘+Enter）：响应返回给代理。
• 超时：倒计时徽章在任何活动时重置；当它过期时，警告覆盖层让用户继续或关闭。
• Escape × 2：快速取消。

会话恢复

如果访谈超时或被放弃（标签页关闭、连接丢失），问题将保存到 ~/.pi/interview-recovery/，文件名如 2026-01-02_093000_myproject_main_65bec3f4.json。您可以稍后通过将该文件传递给 interview() 来重试。超过 7 天的文件会自动清理。

多代理行为

当多个代理同时运行访谈时，只有第一个会自动打开窗口。后续访谈排队并作为工具输出中的 URL 显示。提交活动访谈会自动重定向到下一个排队的访谈。右上角的 toast 带有下拉菜单，可让您打开排队的会话。会话状态栏显示项目路径、git 分支和会话 ID 以进行识别。

超时行为

倒计时（在角落可见）在任何活动时重置——打字、点击或鼠标移动。当它过期时，会出现一个覆盖层，让用户有机会继续。由于 localStorage 自动保存，进度永远不会丢失。

适用对象

构建或使用需要交互式用户输入的 pi-agent 工作流的开发者。它非常适合代理需要澄清项目细节、偏好、设计决策或其他参数的情况——以及结构化表单比自由形式聊天更可靠的情况。对于需要一致地收集反馈并从中断中恢复的团队也很有用。

亮点

• 丰富的问题类型：单选、多选、文本输入、图片上传/相机捕获和信息面板。
• 嵌入媒体：问题中的图片、Chart.js 图表、Mermaid 图、表格和 HTML。
• 带有置信度和权重的推荐：控制选项的建议强度及其视觉突出性。
• 自动保存和超时恢复：响应保存到 localStorage；放弃/超时的访谈可恢复。
• 多代理支持：并发访谈排队而不是抢占焦点，带有 toast 切换器。
• LLM 驱动的助手：使用可配置模型生成更多选项或审查/重写问题。
• 询问选项：内联助手面板，带有提示芯片和自由形式的后续问题。
• 主题：深色/浅色/自动主题，加上自定义 CSS 覆盖和切换热键。
• 启动器选项：选择 Glimpse、浏览器或 Orca 来显示表单。
• 键盘导航：完整的键盘支持，包括导航、选择和提交的快捷键。