itch (J Redeker)

痒

用于苏格拉底式提问的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"]
}

配置（可选）：

看 插件/README.md 了解更多详情。

用法

CLI演示

尝试交互式演示，看看它是如何工作的：

uv run itch demo learning
uv run itch demo "machine learning" --max 5

问题类型

Itch支持五种问题类型，以实现多样化的苏格拉底式探索：

这 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"}
      ]
    }
  ]
}

问题模式

选择模式

响应架构

{
  "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}
  ]
}

按类型列出的答案值格式：

• select：所选选项的 value
• confirm: "true" 或 "false"
• text：输入的文本字符串
• scale: "1" 通过 "5"
• checkbox：逗号分隔的值，例如。， "a,b,c"

验证规则

• 主题：必填，非空字符串
• 问题：需要1-20个问题
• 选择问题：必须至少有2个选项
• 复选框问题：必须至少有一个选择
• 每一个选择：必须具有非空标签和值
• 刻度标签：如果提供，必须恰好是2个元素

从MCP服务器迁移

如果您使用的是MCP服务器(itch-server)在0.2.0之前的版本中，您需要迁移到OpenCode插件：

1. 删除MCP服务器配置 从您的Claude Desktop或其他MCP客户端配置
2. 安装OpenCode插件 通过将插件路径添加到您的 opencode.json:

   {
     "plugins": ["/path/to/itch/plugin"]
   }

1. 更新您的依赖关系：运行 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