使用说明
痒
用于苏格拉底式提问的CLI工具和OpenCode插件-帮助人工智能代理通过引导式查询与用户交互式地探索主题。
特性
- 交互式终端用户界面，用于回答问题（通过 问卷)
- 多种问题类型：选择（多选）、确认（是/否）、文本（自由格式）、比例（1-5级）、复选框（多选）
- 选择/复选框问题的可选自定义“其他”答案
- 用于AI代理消费的结构化JSON响应
- 与无缝集成 OpenCode
安装
OpenCode插件
OpenCode插件提供了与 OpenCode.
步骤1：克隆并安装
git clone https://github.com/JRedeker/itch.git
cd itch
uv sync
步骤2：添加到opencode.json
{
"plugins": ["/path/to/itch/plugin"]
}
配置（可选）：
| 环境变量 | 默认值 | 描述 |
|---|---|---|
ITCH_PATH |
（自动检测） | itch可执行文件的显式路径 |
ITCH_TIMEOUT |
300000 （5分钟） |
子进程超时（毫秒） |
ITCH_DEBUG |
false |
启用调试日志记录 |
看 插件/README.md 了解更多详情。
用法
CLI演示
尝试交互式演示，看看它是如何工作的：
uv run itch demo learning
uv run itch demo "machine learning" --max 5
问题类型
Itch支持五种问题类型，以实现多样化的苏格拉底式探索：
| 类型 | 描述 | 必填项 |
|---|---|---|
select |
多选（默认） | 是（2+） |
confirm |
是/否布尔值 | 否 |
text |
自由形式文本输入 | 否 |
scale |
1-5级，可选标签 | 否 |
checkbox |
多选 | 是（1+） |
这 itch 工具
这 itch 该工具接受一个主题和预先生成的问题，然后以交互方式呈现给用户。
重要：AI代理在调用工具之前必须生成问题。该工具不生成问题，它只呈现问题并收集答案。
示例工具调用
{
"topic": "machine learning",
"questions": [
{
"text": "What interests you most about ML?",
"type": "select",
"choices": [
{"label": "Practical applications", "value": "practical"},
{"label": "Theoretical foundations", "value": "theory"},
{"label": "Career opportunities", "value": "career"}
]
},
{
"text": "Would you like to explore this topic further?",
"type": "confirm"
},
{
"text": "What specific questions do you have?",
"type": "text"
},
{
"text": "How confident are you with the basics?",
"type": "scale",
"scale_labels": ["Not at all", "Very confident"]
},
{
"text": "Which learning resources do you prefer?",
"type": "checkbox",
"choices": [
{"label": "Online courses", "value": "courses"},
{"label": "Books", "value": "books"},
{"label": "Hands-on projects", "value": "projects"},
{"label": "Tutorials", "value": "tutorials"}
]
}
]
}
问题模式
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
text |
string | 是 | 要显示的问题 |
type |
string | 否 | 问题类型： select （默认）， confirm, text, scale, checkbox |
choices |
array | 条件 | 必需 select （2+）和 checkbox (1+) |
id |
int | 否 | 问题ID（如果未提供，则自动分配） |
allows_custom |
bool | 否 | 显示自定义答案的“其他”选项（默认值：true，仅选择/复选框） |
scale_labels |
[string，string] | 否 | 刻度端点的标签，例如。， ["Low", "High"] |
选择模式
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
label |
string | 是 | 显示显示给用户的文本 |
value |
string | 是 | 选择时返回标识符 |
响应架构
{
"status": "complete",
"topic": "machine learning",
"questions": [...],
"answers": [
{"question_id": 1, "selected_value": "practical", "is_custom": false},
{"question_id": 2, "selected_value": "true", "is_custom": false},
{"question_id": 3, "selected_value": "How do neural networks work?", "is_custom": false},
{"question_id": 4, "selected_value": "3", "is_custom": false},
{"question_id": 5, "selected_value": "courses,projects", "is_custom": false}
]
}
| 字段 | 类型 | 描述 |
|---|---|---|
status |
字符串 | "complete", "cancelled"，或 "error" |
topic |
string | 所探讨的主题 |
questions |
array | 被问到的问题（回应） |
answers |
array | 用户对每个问题的答案 |
error |
弦？ | 错误消息（仅当状态为 "error") |
按类型列出的答案值格式：
select：所选选项的valueconfirm:"true"或"false"text：输入的文本字符串scale:"1"通过"5"checkbox：逗号分隔的值，例如。，"a,b,c"
验证规则
- 主题：必填，非空字符串
- 问题：需要1-20个问题
- 选择问题：必须至少有2个选项
- 复选框问题：必须至少有一个选择
- 每一个选择：必须具有非空标签和值
- 刻度标签：如果提供，必须恰好是2个元素
从MCP服务器迁移
如果您使用的是MCP服务器(itch-server)在0.2.0之前的版本中，您需要迁移到OpenCode插件：
- 删除MCP服务器配置 从您的Claude Desktop或其他MCP客户端配置
- 安装OpenCode插件 通过将插件路径添加到您的
opencode.json:{ "plugins": ["/path/to/itch/plugin"] } - 更新您的依赖关系：运行
uv sync删除未使用的mcp依赖
这 itch 工具功能保持不变，只是集成方法发生了变化。
发展
先决条件
- Python 3.11+
- 紫外线 用于Python依赖管理
- Node.js 22+（用于插件开发）
设置
# Clone the repository
git clone https://github.com/JRedeker/itch.git
cd itch
# Install Python dependencies
uv sync
# Install plugin dependencies (optional)
cd plugin && npm install
运行测试
# Python tests
uv run pytest
# All quality checks
uv run ruff check src/ tests/ && uv run ty check src/ && uv run pytest
# TypeScript checks (in plugin/)
cd plugin && npm run check
许可证
麻省理工学院
仓库
https://github.com/JRedeker/itch
