hacknots-cli

demo

HackNotts 2025的交互式人工智能命令行界面-通过优雅的终端界面与多个人工智能提供商聊天。

概述

hacknots-cli 是一个复杂的人工智能交互工具，可将多个人工智能提供商带到您的终端。它采用React和Ink构建，提供了一种美丽的交互式聊天体验，支持10多个AI提供商、一个可扩展的插件系统和MCP（模型上下文协议）集成。

特性

多提供商支持 -在OpenAI、Anthropic、Google、xAI、DeepSeek、Azure、OpenRouter等之间无缝切换
交互式终端用户界面 -漂亮的基于React的界面，由Ink提供动画和流式响应
情境感知AI -针对特定于项目的对话自动加载HACKNOTTS.md上下文
可扩展插件系统 -预/后挂钩架构，内置工具、网络搜索和日志插件
内置命令 - /help, /provider, /export, /model, /init, /about，以及更多
聊天历史导出 -将对话保存为JSON或Markdown格式
MCP集成 -用于获取、文件系统、内存、时间和顺序思维的内置工具
提供商仪表板 -可视化提供程序状态，易于切换和配置
流媒体响应 -来自具有动画显示的AI模型的实时消息流
配置持久性 -保存首选项、默认提供程序和工作目录
工作目录管理 -更改上下文 /cd 文件操作命令
美丽的动画 -渐变效果、加载旋转器和平滑过渡
完全支持TypeScript -所有软件包的类型安全开发经验

安装

git clone https://github.com/Pleasurecruise/hacknotts-cli.git
cd hacknotts-cli
npm install
npm run build

CLI将作为全局安装 hacknotts 命令。

快速开始

配置API密钥 -创建一个 .env 项目根目录中的文件：

# OpenAI
OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-4

# Anthropic
ANTHROPIC_API_KEY=your-anthropic-api-key
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# Google
GOOGLE_API_KEY=your-google-api-key
GOOGLE_MODEL=gemini-1.5-pro

# DeepSeek
DEEPSEEK_API_KEY=your-deepseek-api-key
DEEPSEEK_MODEL=deepseek-chat

# Add other providers as needed

运行命令行界面:

hacknotts

开始聊天:

Welcome to the HackNotts 2025 CLI!

> hi
Hello! How can I assist you with your HackNotts 2025 project submission today?

> /help
Available commands:
  /help (h, ?)          - Show this help message
  /provider (p)         - Switch AI provider
  /model (m)            - Switch model
  /export (save)        - Export chat history
  /clear (cls, c)       - Clear chat
  /exit (quit, q)       - Exit application

可用命令

命令	别名	描述
`/help`	`h`, `?`	显示可用命令
`/provider`	`p`, `providers`	打开提供商仪表板以切换提供商
`/model`	`m`	暂时切换到特定型号
`/export [format]`	`save`, `download`	导出聊天记录（json或markdown）
`/clear`	`cls`, `c`	清除聊天记录
`/cd
`	`chdir`	更改工作目录
`/init`	`initialize`	初始化当前目录中的HACKNOTTS.md上下文文件
`/about`	`info`	显示申请信息和学分
`/exit`	`quit`, `q`	退出应用程序

支持的AI提供商

hacknots-cli支持以下AI提供程序：

开放人工智能 -GPT-4、GPT-3.5和定制型号
Anthropic -克劳德3.5十四行诗，克劳德3作品集/俳句
谷歌 -Gemini 1.5 Pro/Flash
扩展应用识别 -Grok模型
深度求索 -DeepSeek聊天
Azure OpenAI -Azure托管的OpenAI模型
OpenRouter -通过OpenRouter访问多种型号
OpenAI 兼容 -与OpenAI API兼容的自定义端点

每个提供程序都可以配置：

API密钥
自定义基本URL
违约模型
提供商特定选项

HACKNOTTS.md上下文系统

CLI具有智能上下文加载系统，通过 HACKNOTTS.md 文件夹：

自动上下文加载

当您启动聊天会话时，CLI会自动搜索并加载 HACKNOTTS.md 发件人：

这为AI助手提供了关键的项目背景，包括：

项目概况和目标
技术栈
现状和进展
团队信息
重要说明和决定

创建上下文文件

使用 /init 生成模板的命令：

> /init
Created HACKNOTTS.md in /your/project/path

生成的模板包括以下部分：

项目概述
技术栈
项目目标
当前状态（已完成/正在进行/待办事项）
重要提示
团队成员

益处

更好地理解AI -人工智能全面了解您的项目
一致的响应 -所有团队成员的AI交互都使用相同的上下文
进度跟踪 -记录您的项目状态
无缝协作 -在整个团队中分享项目知识

配置

环境变量

通过配置提供程序 .env 文件：

# Provider API Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
XAI_API_KEY=...
DEEPSEEK_API_KEY=...
AZURE_OPENAI_API_KEY=...

# Custom Models (optional)
OPENAI_MODEL=gpt-4
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022
GOOGLE_MODEL=gemini-1.5-pro

# Custom Endpoints (optional)
OPENAI_BASE_URL=https://api.openai.com/v1

用户配置

用户偏好存储在 ~/.hacknotts-cli/config.json:

{
  "defaultProvider": "openai",
  "defaultModel": "gpt-4",
  "theme": "default",
  "workingDirectory": "/path/to/project"
}

配置由CLI自动管理：

默认提供程序 -通过提供商仪表板设置或 /provider 命令
默认模型 -为每个提供商保留您偏好的模型
工作目录 -使用时保存 /cd 持久上下文命令

高级提供程序配置

对于自定义或自托管提供商：

# OpenAI Compatible Provider
OPENAI_COMPATIBLE_API_KEY=your-key
OPENAI_COMPATIBLE_BASE_URL=https://your-endpoint.com/v1
OPENAI_COMPATIBLE_MODEL=your-model

# Azure OpenAI
AZURE_OPENAI_API_KEY=your-azure-key
AZURE_OPENAI_RESOURCE_NAME=your-resource-name
AZURE_OPENAI_DEPLOYMENT_NAME=your-deployment
AZURE_OPENAI_API_VERSION=2024-02-15-preview

# OpenRouter
OPENROUTER_API_KEY=your-openrouter-key
OPENROUTER_MODEL=anthropic/claude-3.5-sonnet

插件系统

hacknots-cli具有可扩展的插件架构：

插件挂钩

插件可以实现各种钩子：

第一钩 - resolveModel, loadTemplate （返回第一个有效结果）
顺序挂钩 - configureContext, transformParams, transformResult （链转换）
平行钩 - onRequestStart, onRequestEnd, onError （副作用）
流钩 - transformStream （流处理）

内置插件

CLI包括几个预构建的插件：

工具使用插件

使AI模型能够在对话中使用工具并执行功能。配置为 createPromptToolUsePlugin 添加自定义工具功能。

Web搜索插件

将web搜索功能与特定于提供商的配置集成在一起：

OpenAI网络搜索
人工网络搜索
谷歌搜索
xAI搜索
OpenRouter搜索

谷歌工具插件

提供对Google特定工具的访问和与Gemini模型的集成，以增强功能。

日志记录插件

添加了全面的日志记录功能，用于调试和监控AI交互。使用可自定义的日志级别跟踪请求、响应和错误。

中间件系统

插件系统建立在灵活的中间件架构之上：

命名中间件 -组织和管理多个中间件层
中间件包装 -将转换应用于模型输入/输出
链条加工 -通过上下文传递顺序执行中间件
错误处理 -优雅的错误捕获和恢复

创建自定义插件

使用 definePlugin 创建自己的插件：

import { definePlugin } from '@cherrystudio/ai-core'

const myPlugin = definePlugin({
  id: 'my-custom-plugin',
  name: 'My Custom Plugin',
  hooks: {
    configureContext: async (context) => {
      // Modify request context
      return context
    },
    transformResult: async (result, context) => {
      // Transform AI response
      return result
    }
  }
})

MCP集成

用于扩展功能的内置MCP工具：

提取工具 -使用自定义标头和身份验证发出HTTP请求
文件系统工具 -读取、写入、列出和管理工作区中的文件
记忆工具 -跨会话数据的持久键值存储
时间工具 -获取当前时间、时区信息和格式化时间戳
顺序思维工具 -具有内存和会话管理的多步推理

MCP服务器集成

工具包提供MCP服务器功能：

服务器管理 -启动和管理MCP服务器
工具发现 -自动从服务器中发现可用工具
工具执行 -执行具有适当参数验证的工具
会话处理 -跨交互管理持久会话

使用创建自定义MCP插件 createMcpPlugin:

import { createMcpPlugin } from 'toolkit'

const mcpPlugin = createMcpPlugin({
  enabled: true,
  servers: [
    {
      name: 'my-server',
      command: 'node',
      args: ['server.js']
    }
  ]
})

导出功能

以多种格式导出您的聊天记录：

# Export to JSON
> /export json

# Export to Markdown
> /export markdown

# Default export (JSON)
> /export

导出的文件包括：

完整消息历史记录
时间戳
角色指标
消息元数据

用户界面功能

终端动画

CLI包括几个视觉增强功能，可提供高级用户体验：

动画徽标 -启动时流畅的徽标动画，带有渐变效果
加载Spinner -AI处理过程中的上下文感知加载指示器
渐变效果 -整个界面都有美丽的动画渐变
平滑过渡 -聊天、帮助和提供商仪表板之间的流畅视图转换
实时流媒体 -AI响应的逐个字符显示

交互式组件

提供商仪表板 -使用键盘控件浏览提供商（↑/↓箭头）
命令列表 -可搜索的命令列表，语法突出显示
状态栏 -显示当前提供程序、型号和工作目录的持久状态显示
帮助系统 -包含命令文档和示例的全面帮助视图
关于查看 -申请信息、版本和学分

键盘控制

Ctrl+C -中断当前AI生成或取消输入
↑/↓ -浏览命令历史记录或提供程序列表
选项卡 -命令自动完成（如果可用）
退出键 -关闭模态视图（帮助、提供者仪表板、关于）

发展

项目结构

hacknotts-cli/
├── packages/
│   ├── cli/              # Main CLI application
│   │   ├── src/
│   │   │   ├── index.tsx # Entry point
│   │   │   ├── app.tsx   # Main app component
│   │   │   ├── components/
│   │   │   │   ├── ChatSession.tsx      # Main chat session logic
│   │   │   │   ├── ChatInterface.tsx    # Chat UI component
│   │   │   │   ├── ProviderView.tsx     # Provider dashboard
│   │   │   │   ├── HelpView.tsx         # Help command view
│   │   │   │   ├── AboutView.tsx        # About information
│   │   │   │   ├── StatusBar.tsx        # Status display
│   │   │   │   ├── LoadingSpinner.tsx   # Loading animation
│   │   │   │   ├── LogoAnimation.tsx    # Logo with animations
│   │   │   │   └── AnimatedGradient.tsx # Gradient effects
│   │   │   ├── commands/
│   │   │   │   ├── CommandRegistry.ts   # Command system
│   │   │   │   └── builtInCommands.ts   # Built-in commands
│   │   │   ├── services/
│   │   │   │   ├── aiService.ts         # AI provider service
│   │   │   │   └── configService.ts     # Configuration management
│   │   │   └── utils/
│   ├── aiCore/           # AI provider and plugin system
│   │   ├── src/
│   │   │   ├── core/
│   │   │   │   ├── providers/           # Provider implementations
│   │   │   │   ├── plugins/             # Plugin system
│   │   │   │   │   └── built-in/        # Built-in plugins
│   │   │   │   ├── middleware/          # Middleware architecture
│   │   │   │   ├── models/              # Model resolution
│   │   │   │   ├── options/             # Provider options
│   │   │   │   └── runtime/             # Execution runtime
│   └── toolkit/          # MCP utilities
│       └── src/
│           ├── manager.ts   # MCP manager
│           ├── plugin.ts    # MCP plugin integration
│           ├── servers/     # MCP server implementations
│           └── tools/       # Built-in MCP tools
├── docs/
├── .env                  # Provider configuration
└── package.json

建筑

三层设计：

CLI层 (packages/cli)-用户界面、命令和交互逻辑
AI核心层 (packages/aiCore)-提供者抽象、插件系统和执行运行时
工具包层 (packages/toolkit)-MCP集成和工具实施

构建命令

# Development with watch mode
npm run dev

# Production build
npm run build

# Run tests
npm test

# Lint and format
npm run lint
npm run format

测试

# Run tests once
npm test

# Watch mode
npm run test:watch

使用示例

基本会话

> What is the capital of France?
The capital of France is Paris.

> /model gpt-3.5-turbo
✓ Switched to model: gpt-3.5-turbo

> Tell me more about it
Paris is the largest city in France and has been the country's capital since...

使用文件

> /cd ./my-project
✓ Changed working directory to: ./my-project

> Can you read the README.md file?
[AI uses filesystem tool to read and analyze README.md]

> /init
✓ Created HACKNOTTS.md in /path/to/my-project

切换提供商

> /provider
# Opens provider dashboard
# Use ↑/↓ to navigate, Enter to select

> Tell me a joke
[Response from newly selected provider]

导出对话

> This is important information I want to save

> /export markdown
✓ Exported 12 messages to chat-history-2025-10-26.md (MARKDOWN)

> /export json
✓ Exported 12 messages to chat-history-2025-10-26.json (JSON)

最佳实践

面向开发者

使用HACKNOTTS.md -为你的项目创建上下文文件，让人工智能更好地理解
按目录组织 -使用 /cd 在项目上下文之间切换
导出重要会话 -保存突破性对话 /export
测试多个提供商 -不同的供应商擅长不同的任务
利用插件 -启用网络搜索和工具以增强功能

对于黑客马拉松

边走边记录 -根据进度更新HACKNOTTS.md
快速提供商切换 -跨不同模型测试想法
代码审查 -使用AI来审查和改进您的代码
建筑规划 -用情境感知AI讨论系统设计
一起调试 -粘贴错误并获得即时帮助

性能提示

API密钥管理 -把钥匙放在里面 .env，永远不要承诺
模型选择 -使用更快的模型完成快速任务，使用高级模型解决复杂问题
清除历史记录 -使用 /clear 在长会话中释放内存
工作目录 -为文件操作设置正确的目录

需求

Node.js>=22.12.0
npm或纱线
至少一个人工智能提供商的API密钥

故障排除

常见问题

安装后找不到CLI

# Reinstall globally
npm run build
# Or manually link
npm link

API密钥错误

# Verify .env file exists in project root
ls -la .env

# Check environment variables are loaded
cat .env

提供程序未初始化

确保API密钥有效且格式正确
如果使用自定义端点，请检查基本URL
验证网络连接
检查模型名称拼写

流媒体问题

某些提供商可能有费率限制
检查终端是否支持ANSI颜色
如果出现显示问题，请尝试不同的终端模拟器

文件操作错误

验证工作目录是否存在： /cd /path/to/dir
检查文件权限
确保路径是绝对路径还是相对于工作目录的路径

调试模式

通过设置环境变量启用详细日志记录：

DEBUG=hacknotts:* hacknotts

获取帮助

检查 /help 用于命令文档
审查 /about 有关版本信息
访问问题对于已知问题
加入HackNotts Discord以获得社区支持

贡献

欢迎投稿！该项目是为HackNotts 2025创建的。

作者

欢乐巡游 -
伊万汉洛斯 -

许可证

MIT许可证-请参阅许可证详细信息文件

参考文献

樱桃工作室 -AI核心架构的灵感
Vercel AI SDK -基础AI SDK
墨水 -React用于终端接口
模型上下文协议 -MCP规范

致谢

创建于 黑客诺茨2025 -一个展示CLI应用程序中高级AI集成的黑客马拉松项目。

______________________________________________________________________

快乐黑客！ 🚀

hacknotts-CLI

快速接入

详细介绍