Skip to content

nispc/knock_and_ask

BranchesTags

Repository files navigation

Knock and Ask

繁體中文 | English | Tiếng Việt

繁體中文

Gemini CLI 的 GUI 彈窗擴充功能 — 類似 Claude Code 的 AskUserQuestion

Knock and Ask 截圖

功能特色

  • 單選/多選問答：支援 RadioButton 單選和 CheckBox 多選模式
  • 多頁籤支援：一次詢問多個問題，以頁籤形式呈現（最多 7 個問題）
  • 鍵盤導航：完整的鍵盤操作支援
    • ↑↓：切換選項
    • Space：切換選取狀態（多選模式）
    • Ctrl+Enter：確認送出
    • Escape：取消
    • Ctrl+←/→：切換頁籤
  • 補充說明輸入：可輸入自訂文字作為額外說明
  • 暗黑模式：符合現代開發者習慣的深色主題
  • 系統托盤常駐：快速回應，視窗顯示時間 < 100ms

系統架構

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   Gemini CLI                                                    │
│       │                                                         │
│       │ stdio (MCP Protocol)                                    │
│       ▼                                                         │
│   ┌──────────────────┐       HTTP (localhost)   ┌───────────┐  │
│   │   MCP Server     │ ◄──────────────────────► │ Electron  │  │
│   │   (Node.js)      │                          │ GUI App   │  │
│   │                  │                          │ (常駐)    │  │
│   │   生命週期：     │                          │           │  │
│   │   隨 Gemini CLI  │                          │ 生命週期： │  │
│   │   會話啟動/結束  │                          │ 系統托盤  │  │
│   └──────────────────┘                          │ 常駐運行  │  │
│         進程 1                                  └───────────┘  │
│                                                     進程 2     │
└─────────────────────────────────────────────────────────────────┘

安裝

前置需求

  • Node.js >= 20.0.0
  • Gemini CLI（已安裝並設定完成）

安裝步驟

# 1. Clone 專案
git clone https://github.com/nispc/knock_and_ask.git
cd knock_and_ask

# 2. 安裝依賴
npm install

# 3. 建置專案
npm run build

# 4. 安裝為 Gemini CLI Extension
gemini extensions install .

使用方式

安裝完成後，當 Gemini CLI 的 AI 模型需要詢問使用者時，會自動呼叫 ask_user_question 工具，彈出 GUI 視窗讓使用者回答。

MCP 工具：ask_user_question

{
  "questions": [
    {
      "question": "你想使用哪種認證方式？",
      "header": "認證方式",
      "multiSelect": false,
      "options": [
        { "label": "OAuth 2.0", "description": "使用 Google 帳號登入" },
        { "label": "API Key", "description": "使用 API 金鑰認證" },
        { "label": "其他", "description": "手動輸入認證方式" }
      ]
    }
  ]
}

回傳格式

{
  "status": "success",
  "answers": {
    "認證方式": {
      "selected": ["OAuth 2.0"],
      "customText": ""
    }
  }
}

開發

# 開發模式（Electron GUI）
npm run dev

# 開發模式（僅 MCP Server）
npm run dev:mcp

# 執行測試
npm test

# 建置
npm run build

專案結構

knock-and-ask/
├── src/
│   ├── electron/          # Electron GUI 應用
│   │   ├── main/          # 主進程
│   │   ├── preload/       # 預載腳本
│   │   └── renderer/      # 渲染進程（React）
│   ├── mcp-server/        # MCP Server
│   └── shared/            # 共用型別定義
├── specs/                 # 功能規格文件
├── dist/                  # 建置產出
└── app/                   # 打包後的 Electron 應用

設定

環境變數

變數名稱 預設值 說明
KNOCK_AND_ASK_PORT 3456 MCP Server 與 GUI 通訊的 HTTP 端口

限制

  • 單一問題最多 10 個選項
  • 多頁籤最多 7 個問題
  • 使用者回應逾時：5 分鐘

授權

MIT License

致謝

English

GUI Dialog Extension for Gemini CLI — Similar to Claude Code's AskUserQuestion

Knock and Ask Screenshot

Features

  • Single/Multiple Choice: Supports RadioButton (single) and CheckBox (multiple) selection modes
  • Multi-Tab Support: Ask multiple questions at once, presented as tabs (up to 7 questions)
  • Keyboard Navigation: Full keyboard support
    • ↑↓: Navigate options
    • Space: Toggle selection (multi-select mode)
    • Ctrl+Enter: Confirm and submit
    • Escape: Cancel
    • Ctrl+←/→: Switch tabs
  • Custom Input: Text field for additional comments
  • Dark Mode: Modern dark theme for developers
  • System Tray: Stays resident for fast response, window appears in < 100ms

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   Gemini CLI                                                    │
│       │                                                         │
│       │ stdio (MCP Protocol)                                    │
│       ▼                                                         │
│   ┌──────────────────┐       HTTP (localhost)   ┌───────────┐  │
│   │   MCP Server     │ ◄──────────────────────► │ Electron  │  │
│   │   (Node.js)      │                          │ GUI App   │  │
│   │                  │                          │ (Resident)│  │
│   │   Lifecycle:     │                          │           │  │
│   │   Starts/ends    │                          │ Lifecycle:│  │
│   │   with Gemini    │                          │ System    │  │
│   │   CLI session    │                          │ tray      │  │
│   └──────────────────┘                          └───────────┘  │
│         Process 1                                   Process 2  │
└─────────────────────────────────────────────────────────────────┘

Installation

Prerequisites

  • Node.js >= 20.0.0
  • Gemini CLI (installed and configured)

Installation Steps

# 1. Clone the repository
git clone https://github.com/nispc/knock_and_ask.git
cd knock_and_ask

# 2. Install dependencies
npm install

# 3. Build the project
npm run build

# 4. Install as Gemini CLI Extension
gemini extensions install .

Usage

After installation, when Gemini CLI's AI model needs to ask the user a question, it will automatically invoke the ask_user_question tool and display a GUI dialog for the user to respond.

MCP Tool: ask_user_question

{
  "questions": [
    {
      "question": "Which authentication method do you want to use?",
      "header": "Auth Method",
      "multiSelect": false,
      "options": [
        { "label": "OAuth 2.0", "description": "Sign in with Google account" },
        { "label": "API Key", "description": "Use API key authentication" },
        { "label": "Other", "description": "Enter custom authentication method" }
      ]
    }
  ]
}

Response Format

{
  "status": "success",
  "answers": {
    "Auth Method": {
      "selected": ["OAuth 2.0"],
      "customText": ""
    }
  }
}

Development

# Development mode (Electron GUI)
npm run dev

# Development mode (MCP Server only)
npm run dev:mcp

# Run tests
npm test

# Build
npm run build

Project Structure

knock-and-ask/
├── src/
│   ├── electron/          # Electron GUI application
│   │   ├── main/          # Main process
│   │   ├── preload/       # Preload scripts
│   │   └── renderer/      # Renderer process (React)
│   ├── mcp-server/        # MCP Server
│   └── shared/            # Shared type definitions
├── specs/                 # Feature specifications
├── dist/                  # Build output
└── app/                   # Packaged Electron app

Configuration

Environment Variables

Variable Default Description
KNOCK_AND_ASK_PORT 3456 HTTP port for MCP Server and GUI communication

Limitations

  • Maximum 10 options per question
  • Maximum 7 questions (tabs)
  • User response timeout: 5 minutes

License

MIT License

Acknowledgements

  • Claude Code - Inspired by AskUserQuestion feature
  • Gemini CLI - MCP Extension architecture
  • Electron - Cross-platform desktop application framework

Tiếng Việt

Extension GUI Dialog cho Gemini CLI — Tương tự AskUserQuestion của Claude Code

Knock and Ask Screenshot

Tính năng

  • Chọn đơn/Chọn nhiều: Hỗ trợ RadioButton (chọn đơn) và CheckBox (chọn nhiều)
  • Hỗ trợ nhiều tab: Đặt nhiều câu hỏi cùng lúc, hiển thị dưới dạng tab (tối đa 7 câu hỏi)
  • Điều hướng bàn phím: Hỗ trợ đầy đủ bàn phím
    • ↑↓: Di chuyển giữa các tùy chọn
    • Space: Chuyển đổi trạng thái chọn (chế độ chọn nhiều)
    • Ctrl+Enter: Xác nhận và gửi
    • Escape: Hủy bỏ
    • Ctrl+←/→: Chuyển tab
  • Nhập tùy chỉnh: Ô văn bản cho nhận xét bổ sung
  • Chế độ tối: Giao diện tối hiện đại cho lập trình viên
  • Khay hệ thống: Chạy nền để phản hồi nhanh, cửa sổ xuất hiện trong < 100ms

Kiến trúc

┌─────────────────────────────────────────────────────────────────┐
│                                                                 │
│   Gemini CLI                                                    │
│       │                                                         │
│       │ stdio (MCP Protocol)                                    │
│       ▼                                                         │
│   ┌──────────────────┐       HTTP (localhost)   ┌───────────┐  │
│   │   MCP Server     │ ◄──────────────────────► │ Electron  │  │
│   │   (Node.js)      │                          │ GUI App   │  │
│   │                  │                          │ (Thường   │  │
│   │   Vòng đời:      │                          │  trú)     │  │
│   │   Bắt đầu/kết    │                          │           │  │
│   │   thúc cùng      │                          │ Vòng đời: │  │
│   │   phiên Gemini   │                          │ Khay hệ   │  │
│   │   CLI            │                          │ thống     │  │
│   └──────────────────┘                          └───────────┘  │
│         Tiến trình 1                               Tiến trình 2│
└─────────────────────────────────────────────────────────────────┘

Cài đặt

Yêu cầu

  • Node.js >= 20.0.0
  • Gemini CLI (đã cài đặt và cấu hình)

Các bước cài đặt

# 1. Clone repository
git clone https://github.com/nispc/knock_and_ask.git
cd knock_and_ask

# 2. Cài đặt dependencies
npm install

# 3. Build dự án
npm run build

# 4. Cài đặt như Gemini CLI Extension
gemini extensions install .

Cách sử dụng

Sau khi cài đặt, khi mô hình AI của Gemini CLI cần hỏi người dùng một câu hỏi, nó sẽ tự động gọi công cụ ask_user_question và hiển thị hộp thoại GUI để người dùng trả lời.

Công cụ MCP: ask_user_question

{
  "questions": [
    {
      "question": "Bạn muốn sử dụng phương thức xác thực nào?",
      "header": "Xác thực",
      "multiSelect": false,
      "options": [
        { "label": "OAuth 2.0", "description": "Đăng nhập bằng tài khoản Google" },
        { "label": "API Key", "description": "Sử dụng xác thực bằng API key" },
        { "label": "Khác", "description": "Nhập phương thức xác thực tùy chỉnh" }
      ]
    }
  ]
}

Định dạng phản hồi

{
  "status": "success",
  "answers": {
    "Xác thực": {
      "selected": ["OAuth 2.0"],
      "customText": ""
    }
  }
}

Phát triển

# Chế độ phát triển (Electron GUI)
npm run dev

# Chế độ phát triển (chỉ MCP Server)
npm run dev:mcp

# Chạy tests
npm test

# Build
npm run build

Cấu trúc dự án

knock-and-ask/
├── src/
│   ├── electron/          # Ứng dụng Electron GUI
│   │   ├── main/          # Tiến trình chính
│   │   ├── preload/       # Scripts preload
│   │   └── renderer/      # Tiến trình renderer (React)
│   ├── mcp-server/        # MCP Server
│   └── shared/            # Định nghĩa kiểu dùng chung
├── specs/                 # Tài liệu đặc tả tính năng
├── dist/                  # Đầu ra build
└── app/                   # Ứng dụng Electron đã đóng gói

Cấu hình

Biến môi trường

Biến Mặc định Mô tả
KNOCK_AND_ASK_PORT 3456 Cổng HTTP cho giao tiếp giữa MCP Server và GUI

Giới hạn

  • Tối đa 10 tùy chọn mỗi câu hỏi
  • Tối đa 7 câu hỏi (tabs)
  • Timeout phản hồi người dùng: 5 phút

Giấy phép

MIT License

Lời cảm ơn

  • Claude Code - Lấy cảm hứng từ tính năng AskUserQuestion
  • Gemini CLI - Kiến trúc MCP Extension
  • Electron - Framework ứng dụng desktop đa nền tảng

About

A Gemini CLI extension that provides GUI dialogs for interactive user clarification during AI-assisted coding sessions.

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages