hanabi-cli

Uma interface de chat de terminal para qualquer

GitHub
7
Experimente este MCPPatrocinado

Documentação

hanabi-cli

⟡ Uma interface de chat de IA para terminal para qualquer modelo de LLM, com contexto de arquivos, suporte a MCP e implantação.

  • Agente local multi-habilidoso com suporte a arquivos, área de transferência e MCP
  • Escopo por pasta de projeto - agente diferente por projeto
  • Hospede sua interface web de chat do agente (Next.js) a partir da linha de comando em segundos e pronta para implantação
  • Crie um cluster multi-agente com estratégias predefinidas.
  • Consulte o Arquivo de Configuração do Hanabi para a lista completa de recursos.

Interface de linha de comando

Chat demo

Interface Web de Chat

Web Chat UI

Sumário

Instalação

$ npm install -g hanabi-cli

CLI

Obter Ajuda

$ hanabi --help

Iniciar sessão de chat do hanabi

$ hanabi

Redefinir arquivo de configuração

$ hanabi reset

Fazer uma única pergunta e imprimir o resultado. (Sim, o Hanabi injeta automaticamente a data e o fuso horário de hoje como contexto para você)

$ hanabi ask "how's the weather tomorrow?"
$ hanabi ask "generate a react todo app" > ./todo-app-instructions.md

Modelo Padrão

O modelo padrão é o modelo ativo a ser usado pelo hanabi-cli. Isso deve ser configurado para você através da interface CLI. Observe que a temperatura padrão é 0.5. Alguns modelos como GPT-5 exigem que a temperatura seja definida como 1. A configuração de temperatura é adicionada em hanabi-cli na versão 1.4.6.

Você também pode modificar o modelo diretamente. No seu <user home folder>/.hanabi.json, adicione ou modifique o objeto defaultModel:

{
	"llms": [
		{
      "id": "fdd1abc5-6791-4c29-b754-4f1174692c22",
      "provider": "OpenAI",
      "apiKey": "your-api-key",
      "apiVersion": "2025-01-01-preview"
    },
	],
	"defaultModel": {
		"provider": "openai",
		"model": "gpt-4",
		"temperature": 0.7
	}
}

Servidores MCP

No seu <user home folder>/.hanabi.json, adicione a configuração mcpServers.

{
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	},
	"mcpServers": {
		"home-ai": {
			"name": "Home AI",
			"transport": "stdio",
			"command": "node",
			"args": ["c:/folder/home-mcp.js"]
		},
		"context7": {
			"name": "context7",
			"transport": "stdio",
			"command": "npx",
			"args": ["-y", "@upstash/context7-mcp@latest"]
		},
		"browser-use": {
			"name": "Browser-use automation",
			"transport": "sse",
			"url": "http://172.17.0.1:3003/sse",
			"headers": {
				"authentication": "Bearer api-token"
			}
		},
		// npx stdio approach is flaky & slow. highly recommend
		// to npm install -g <mcp-server> and use the following.
		// see https://github.com/modelcontextprotocol/servers/issues/64
        // "file-system": {
        // 	"name": "file system",
        // 	"transport": "stdio",
        // 	"command": "path/to/your/node.exe",
        // 	"args": [
		// "path/to/global/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js", "."]
        // },
		"tavily": {
			"name": "Tavily Search",
			"transport": "stdio",
			"command": "npx",
			"env": {
				"TAVILY_API_KEY": "your-api-key"
			},
			"args": ["-y", "tavily-mcp@0.1.4"]
		},
		// npx is slow! use above recommendation
		"file-system": {
			"name": "file system",
			"transport": "stdio",
			"command": "npx",
			"args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
		},
		"my-calendar": {
			"name": "My Calendar",
			"transport": "streamable_http",
			"url": "http://172.17.0.1:3001/mcp",
			"headers": {
				"authentication": "Bearer my-auth-token"
			}
		}
	}
}

Excluir arquivos

Para impedir que arquivos sejam acessados, adicione padrões globby na configuração

Todos os arquivos incluídos no .gitignore também serão excluídos automaticamente.

// <user home folder>/.hanabi.json
{
	"exclude": ["certificates", "screenshots/**/*", "passwords/*", "*.pid"],
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Variáveis de Ambiente Locais

O Hanabi suporta arquivos de ambiente locais (.env). Você também pode adicionar o campo envs ao .hanabi.json. Use o prefixo de URL file:// para injetar o conteúdo do arquivo como variável de ambiente Suporta apenas arquivos de texto simples, por exemplo, *.json, *.txt, *.html, etc. Para injetar o conteúdo de arquivos PDF no process.env, converta-os em arquivos de texto usando algo como pdf2json.

adicione a variável de ambiente ALLOWED_ORIGIN para adicionar proteção CORS para o servidor de API.

// .hanabi.json
{
	"envs": {
		"FOO": "bar",
		"MY_DOC: "file://./README.md",
		"ALLOWED_ORIGIN": "http://localhost:3042"
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Se você não quiser armazenar a chave de API do provedor ou quaisquer outros tokens no .hanabi.json, exclua os campos apiKey e salve-os no diretório de trabalho .env em vez disso. Os nomes das chaves são os seguintes. Consulte Provedores ou .env.example para os nomes das variáveis de ambiente das chaves de API.

OPENAI_API_KEY=xxx
GOOGLE_GENERATIVE_AI_API_KEY=xxx
DEEPSEEK_API_KEY=xxx
ANTHROPIC_API_KEY=xxx
GROQ_API_KEY=xxx
XAI_API_KEY=xxx

# MCP keys
TAVILY_API_KEY=xxx

Prompt de Sistema Personalizado

O Hanabi vem com um prompt de sistema simples predefinido para mostrar documentação sobre comandos de terminal e fornecer contexto de data e fuso horário. Você pode fornecer um prompt de sistema extra em hanabi.system.prompt.md no diretório de trabalho. Use o handle /gen ou hanabi gen para gerar um para você.

Variáveis são suportadas via sintaxe ${VAR_NAME}, elas são lidas do process.env. Consulte Variáveis de ambiente locais.

exemplo hanabi.system.prompt.md

# act as a polite chat bot collecting user feedback via conversational loop.

## context

Product name is ${PRODUCT_NAME}

## ask user the follwing questions one by one and prints a well formatted report

- What is your name
- How do you feel about our product? (classify answer as "Bad" | "OK" | "great")
- What is your company

Substituição do arquivo de configuração local

Você pode copiar <user home folder>/.hanabi.json para o seu diretório de trabalho (por exemplo, nível de projeto) para substituir a configuração de nível de usuário. Os LLMs são mesclados por nome do provedor. Use o handle /gen ou hanabi gen para gerar um para você.

Modo de streaming

Alterne "streaming":true em <user home folder>/.hanabi.json ou no diretório de trabalho.

Esquema de Resposta

É muito importante que o agente de fluxo de trabalho produza respostas em um esquema determinístico, por exemplo, ao pedir ao agente para gerar um payload de chamada de API. Para conseguir isso, defina answerSchema que seja compatível com o esquema Zod no arquivo de configuração.

// .hanabi.json
{
	"answerSchema": {
		"type": "object",
		"required": ["answer"],
		"properties": {
			"reason": {
				"type": "string",
				"description": "detailed reasoning for the final output."
			},
			"answer": {
				"type": "string",
				"description": "the final output without reasoning details. For math related question, this is the final output number."
			}
		}
	},
	"serve": {
 		...
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Servidor da Interface Web de Chat

É recomendado criar um .hanabi.json local para um servidor de chat independente

No CLI do Hanabi, use /serve para iniciar o servidor web com o contexto atual (MCPs e prompt de sistema). Isso salvará a configuração serve no seu .hanabi.json.

Use hanabi serve para iniciar o servidor da interface web diretamente - útil para implantações. Use apiOnly para desativar a interface de chat.

Consulte os detalhes da API do servidor aqui

// .hanabi.json
{
	"serve": {
 		"mcpKeys": ["home-ai"],
    	"port": 3041,
		/** name of the agent */
		name?: string;
		/** disable chat UI and only expose API endpoints */
		apiOnly?: boolean;
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Sistema Multi-Agentes

Você pode orquestrar múltiplos agentes (remotos) em várias estratégias ou padrões

Observe:

  • No chat da CLI, use o handle @agents para ativar.
  • No chat da interface web, o modo multi-agentes está sempre habilitado se definido em .hanabi.json
    • Apenas a resposta do agente trabalhador final será transmitida para a interface.

Atualmente, o hanabi suporta os seguintes tipos de estratégia

roteamento (ou seja, classificação de consultas)

Consulte o Arquivo de Configuração do Hanabi para mais detalhes sobre esta estratégia.

  • Use o handle /gen ou hanabi gen para gerar um para você.
// .hanabi.json
{
	"multiAgents": {
		"strategy": "routing",
		/** default false - question with no classification
		* will be passed through to routing agent */
		"force": false,
		"agents": [
			{
				"name": "calendars",
				"apiUrl": "http://localhost:3051/api",
				"classification": "school calendar events and UK public holiday"
			},
			{
				"name": "math",
				"apiUrl": "http://localhost:3052/api",
				"classification": "math problem"
			},
			{
				"name": "api-doc",
				"apiUrl": "http://localhost:3053/api",
				"classification": "API document"
			}
		]
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

fluxo de trabalho (ou seja, executar agentes trabalhadores sequencialmente)

Consulte o Arquivo de Configuração do Hanabi para mais detalhes sobre esta estratégia.

  • neste modo, o histórico do chat é ignorado. Cada mensagem do usuário aciona um novo fluxo de trabalho independente.
  • Use o handle /gen ou hanabi gen para gerar um para você.
// .hanabi.json
{
	"multiAgents": {
		"strategy": "workflow",
		"steps": [
			{
				"apiUrl": "http://localhost:3051/api",
				"name": "process user email into trade instruction"
			},
			{
				"apiUrl": "http://localhost:3052/api",
				"name": "trade booking with payload"
			}
		]
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

paralelo (ou seja, multitarefa)

Consulte o Arquivo de Configuração do Hanabi para mais detalhes sobre esta estratégia.

  • envie a consulta do usuário para múltiplos agentes para diferentes tipos de tarefas em paralelo e produza um resumo agregado.
  • Use o handle /gen ou hanabi gen para gerar um para você.
// .hanabi.json
{
	"multiAgents": {
		strategy: 'parallel',
		agents: [
			{
				name: 'code quality agent',
				apiUrl: 'http://localhost:3051/api',
				prompt:
					'Review code structure, readability, and adherence to best practices.',
			},
			{
				name: 'code performance agent',
				apiUrl: 'http://localhost:3052/api',
				prompt: 'Identify performance bottlenecks & memory leaks.',
			},
			{
				name: 'code security agent',
				apiUrl: 'http://localhost:3053/api',
				prompt:
					'Identify security vulnerabilities, injection risks, and authentication issues',
			},
		],
	},
	"llms": [
		// ...
	],
	"defaultModel": {
		// ...
	}
}

Implantação com Docker

Consulte a pasta docker-agent-example para ver como implantar seu agente como uma imagem docker.

TAREFAS PENDENTES

  • incluir arquivos locais no chat
  • suporte a mcp
  • adicionar configuração para excluir padrões de arquivos personalizados
  • suporte para prompt de sistema personalizado (via arquivo .md local)
  • suporte para substituição de .hanabi.json no nível do diretório de trabalho, semelhante a como o .npmrc funciona
  • modo de streaming
  • adicionar modo de bot de chat no servidor web (ou seja, API e interface web)
  • melhorar o modo de servidor web (chaves de API, melhorias de UX, atualizar o modo de interface no readme)
  • Sistema Multi-Agentes (EM ANDAMENTO)
  • suporte a arquivos na interface web