AI导哈

AI终端助手

一款支持多LLM提供商和工具执行的AI命令行助手，适用于开发者和技术专家。

  • by cameronrye
  • Swift
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 cameronrye/clarissa

使用说明

Clarissa

An AI-powered terminal assistant with tool execution capabilities

Clarissa是一个命令行AI代理，使用 包子 和 墨水它支持多个LLM提供商，包括云服务（OpenRouter、OpenAI、Anthropic）和本地模型（Apple Intelligence、LM Studio、GGUF通过节点llama cpp）。代理可以执行工具、管理文件、运行shell命令，并通过模型上下文协议（MCP）与外部服务集成。

特性

  • 多提供商支持 -云（OpenRouter、OpenAI、Anthropic）和本地（Apple Intelligence、LM Studio、GGUF）提供商
  • 多型号支持 -在Claude、GPT-4、Gemini、Llama、DeepSeek和100多种型号之间切换
  • 苹果智能 -在macOS 26+上使用Apple Foundation Models的设备上AI，具有完整的工具调用功能
  • 局部模型推理 -直接通过节点llama cpp下载并运行GGUF模型
  • 流媒体响应 -响应式对话的实时令牌流
  • 内置工具 -文件操作、Git集成、shell命令、web获取等
  • MCP集成 -连接到外部MCP服务器以扩展功能
  • 会话管理 -保存和恢复对话历史记录
  • 内存持久性 -在会话中记住事实 /remember 和 /memories
  • 上下文管理 -自动令牌跟踪和上下文截断
  • 工具确认 -批准或拒绝潜在危险操作
  • 一次性模式 -直接从shell运行单个命令
  • 管道输入 -来自其他命令的管道内容用于处理
  • 自动更新 -检查并安装更新 clarissa upgrade

运作原理

Clarissa实施 ReAct（推理+代理）代理模式，其中LLM通过迭代循环中的工具执行来推理任务并采取行动。

架构概述

flowchart LR
    subgraph Input
        A[User Message]
        B[Piped Content]
    end

    subgraph Clarissa
        C[Agent Loop]
        D[LLM Client]
        E[Tool Registry]
        F[Context Manager]
        G[Provider Registry]
    end

    subgraph Cloud Providers
        H[OpenRouter]
        I[OpenAI]
        J[Anthropic]
    end

    subgraph Local Providers
        K[Apple Intelligence]
        L[LM Studio]
        M[Local GGUF]
    end

    subgraph External
        N[MCP Servers]
    end

    A --> C
    B --> C
    C <--> D
    C <--> E
    C <--> F
    D <--> G
    G <--> H
    G <--> I
    G <--> J
    G <--> K
    G <--> L
    G <--> M
    E <-.-> N

该系统将您的终端连接到各种LLM提供商。当你要求Clarissa执行任务时，它：

  1. 将您的消息与可用的工具定义一起发送到LLM
  2. 接收可能包括工具调用的响应（例如，读取文件、运行命令）
  3. 执行请求的工具并将结果反馈给LLM
  4. 重复，直到LLM提供最终答案

ReAct循环

flowchart TD
    A[User Input] --> B[Add to Conversation]
    B --> C[Send to LLM]
    C --> D{Response Type?}
    D -->|Tool Calls| E[Execute Tools]
    E --> F[Add Results to History]
    F --> C
    D -->|Final Answer| G[Display Response]

这个循环会一直持续到LLM在不请求任何工具的情况下做出响应，表明它已经完成了任务。最大迭代限制可防止无限循环。

关键概念

概念 描述
工具确认 潜在危险的工具（文件写入、shell命令）在执行前需要获得批准。使用 /yolo 自动批准。
上下文管理 Clarissa跟踪令牌使用情况，并在接近模型的上下文限制时自动截断旧消息。
会话保持 对话可以保存到 ~/.clarissa/sessions/ 后来又恢复了 /save 和 /load.
存储器系统 使用 /remember 存储在会话中持续存在并包含在每个对话中的事实。
MCP可扩展性 连接到 模型上下文协议 服务器可以添加自定义工具，而无需修改Clarissa的代码。

有关详细的体系结构文档，请参阅 架构指南.

需求

安装

来自npm（推荐）

# Using bun
bun install -g clarissa

# Using npm
npm install -g clarissa

来源

git clone https://github.com/cameronrye/clarissa.git
cd clarissa
bun install
bun link

独立二进制

从下载预构建的二进制文件 发布页面 并将其添加到您的PATH中：

# Example for macOS ARM
chmod +x clarissa-macos-arm64
mv clarissa-macos-arm64 /usr/local/bin/clarissa

配置

快速设置

运行交互式设置以配置API密钥：

clarissa init

这将提示您输入OpenRouter、OpenAI和Anthropic的API密钥。您可以跳过任何不想使用的提供商。

手动配置

在以下位置创建配置文件 ~/.clarissa/config.json:

{
  "openrouterApiKey": "sk-or-...",
  "openaiApiKey": "sk-...",
  "anthropicApiKey": "sk-ant-...",
  "provider": "openrouter",
  "model": "anthropic/claude-sonnet-4"
}

或者将API键设置为环境变量：

export OPENROUTER_API_KEY=sk-or-...
export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...

配置选项

配置键 环境变量 描述
openrouterApiKey OPENROUTER_API_KEY OpenRouter API密钥（100多种型号）
openaiApiKey OPENAI_API_KEY OpenAI API密钥（GPT模型）
anthropicApiKey ANTHROPIC_API_KEY Anthropic API键（Claude型号）
provider - 首选提供程序（如果未设置，则自动检测）
model OPENROUTER_MODEL 要使用的默认模型
localModelPath - 本地GGUF模型文件的路径
maxIterations MAX_ITERATIONS 最大工具迭代次数（默认值：10）
debug DEBUG 启用调试日志记录
mcpServers - MCP服务器自动加载

提供商

Clarissa会根据您的配置自动选择最佳可用提供商：

提供者 类型 要求
openrouter 云 API密钥
openai 云 API密钥
anthropic 云 API密钥
apple-ai 本地 macOS 26+，苹果硅
lmstudio 本地 LM Studio在本地主机上运行：1234
local-llama 本地 已下载GGUF模型

使用以下选项切换提供商：

clarissa providers anthropic    # CLI
/provider anthropic             # Interactive

MCP服务器配置

将MCP服务器添加到配置文件中，以便在启动时自动加载它们：

{
  "apiKey": "your_api_key_here",
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "your_token" }
    }
  }
}

使用 /mcp 查看连接的服务器和 /tools 查看可用工具。

用法

交互模式

以交互模式启动Clarissa：

clarissa

一次性模式

运行一个命令并退出：

clarissa "What files are in this directory?"

管道输入

其他命令中的管道内容：

cat error.log | clarissa "Explain this error"
git diff | clarissa "Write a commit message for these changes"

CLI命令

命令 描述
clarissa 启动交互模式
clarissa "<message>" 一次性查询模式
clarissa init 交互式设置API密钥
clarissa upgrade 升级至最新版本
clarissa config 查看当前配置
clarissa history 显示单次查询历史记录
clarissa providers [NAME] 列出提供商或切换到一个提供商
clarissa download [ID] 下载本地GGUF模型
clarissa models 列出已下载的型号
clarissa use <FILE> 将下载的模型设置为活动
clarissa app "<message>" 使用可选问题打开macOS应用程序

CLI选项

选项 描述
-c, --continue 继续上一次会话
-m, --model MODEL 使用特定型号
--list-models 列出可用型号
--check-update 检查可用更新
--debug 启用调试输出
-h, --help 显示帮助
-v, --version 显示版本

交互式命令

命令 描述
/help 显示可用命令
/new 开始新的对话
/last 加载最近的会话
/save [NAME] 保存当前会话
/sessions 列出已保存的会话
/load ID 加载已保存的会话
/delete ID 删除已保存的会话
/remember <fact> 保存内存
/memories 列出已保存的记忆
/forget <#|ID> 忘记记忆
/model [NAME] 显示或切换当前型号
/provider [NAME] 显示或切换LLM提供程序
/mcp CMD ARGS 连接到stdio MCP服务器
/mcp sse URL 连接到HTTP/SSE MCP服务器
/tools 列出可用工具
/context 显示上下文窗口使用情况
/yolo 切换自动审批模式
/version 显示版本信息
/upgrade 升级至最新版本
/exit 离开克拉丽莎

键盘快捷键

快捷方式 操作
Ctrl+C 取消当前操作/退出
Ctrl+P 使用AI增强提示
Up/Down 浏览输入历史记录

内置工具

文件操作

  • read_file -读取文件内容
  • write_file -写入或创建文件
  • patch_file -将补丁应用于文件
  • list_directory -列出目录内容
  • search_files -按模式搜索文件

Git集成

  • git_status -显示存储库状态
  • git_diff -显示更改
  • git_log -查看提交历史记录
  • git_add -舞台文件
  • git_commit -提交更改
  • git_branch -管理分支机构

系统

  • bash -执行shell命令
  • calculator -执行计算

网络

  • web_fetch -获取并解析网页

文件上下文引用

使用以下命令直接在提示中引用文件 @filename 语法：

Explain what @src/index.ts does
Review @package.json:1-20 for issues
Compare @README.md with @CHANGELOG.md

MCP集成

连接到模型上下文协议服务器，使用其他工具扩展Clarissa：

# Stdio server (local process)
/mcp npx -y @modelcontextprotocol/server-filesystem /path/to/directory

# HTTP/SSE server (remote URL)
/mcp sse https://mcp.example.com/api

发展

使用热重新加载运行：

bun run dev

运行测试：

bun test

构建二进制文件

为您当前的平台构建：

bun run build:current

为所有平台构建：

bun run build:all

二进制文件输出到 dist/ 目录。

发布到npm

npm publish

项目结构

src/
  index.tsx        # CLI entry point
  agent.ts         # ReAct agent loop implementation
  update.ts        # Auto-update functionality
  config/          # Environment configuration
  history/         # One-shot query history
  llm/             # LLM client and context management
    providers/     # Multi-provider abstraction (OpenRouter, OpenAI, Anthropic, Apple, etc.)
  mcp/             # MCP client integration
  memory/          # Long-term memory persistence
  models/          # Local model download and management
  preferences/     # User preferences persistence
  session/         # Session persistence
  tools/           # Tool definitions
  ui/              # Ink UI components

许可证

麻省理工学院

由以下材料制成❤️ 通过 Cameron Rye

相关 MCP