aiter

一个基于终端的AI聊天界面，使用OpenTUI和React构建，具有模块化的代理系统，并集成了模型上下文协议（MCP）。

建立在**Vercel AI SDK** 和 **OpenTUI**之上，结合了无提供商偏见的人工智能工具和现代终端UI框架。

为什么选择aiter？

虽然像Claude Code和其他CLI AI代理提供了强大的AI辅助，但aiter给你的是不同的东西：完全控制与AI交互的方式。

基于三个原则构建

可控性：拥有整个代理循环的所有权——决定迭代限制、控制工具执行流程并自定义流式传输行为。构建符合你的思维模式而不是供应商的AI工作流。

可扩展性：通过Vercel AI SDK运行任何模型。轻松配置MCP服务器。定义自定义工具和命令。为不同任务创建专门的代理。没有黑盒，没有专有抽象。

可定制性：以终端为中心意味着可脚本化、管道化和CI/CD就绪。使用React修改UI。直接检查和编辑对话JSON。完全本地控制，无需遥测。

对于想要使用AI进行构建，而不仅仅是使用它的开发者来说。非常适合实验、MCP测试、自定义工作流以及理解AI交互的实际工作原理。

---

快速开始

安装

创建一个新的aiter应用程序：

bunx @aiter/cli create app my-chat-app
cd my-chat-app
bun install
# 设置环境变量
cp .env.template .env

运行

# 使用示例代理启动
bun run src/index.tsx --agent example
# 恢复现有聊天
bun run src/index.tsx --agent example --chat chats/abc123.json
# 使用初始提示启动
bun run src/index.tsx --agent example --prompt "你好，你好吗？"
# 从标准输入管道提示
echo "解释TypeScript泛型" | bun run src/index.tsx --agent example -

---

功能

核心能力

• 终端用户界面（TUI）：由OpenTUI驱动的美丽、交互式的聊天界面
• 多代理系统：创建并切换具有不同配置的自定义AI代理
• 持久聊天会话：所有对话都保存为JSON文件以便轻松恢复
• MCP集成：通过模型上下文协议连接到外部工具和服务
  • 支持stdio、SSE和HTTP传输类型
  • 从MCP服务器动态加载工具
  • 每个代理的简单配置

可扩展性

• 基于文件系统的代理组织：类似于Next.js的约定结构——代理按目录组织，具有标准化的文件夹（commands/、tools/、mcps/、system-prompts/）
• 自定义斜杠命令：使用yargs风格的参数解析定义特定于代理或全局的斜杠命令
• 自定义AI工具：添加AI可以在对话中使用的本地工具
• 灵活的系统提示：使用基于markdown的系统提示自定义AI行为
• 自定义UI组件：用你自己的React组件覆盖聊天界面中的任何组件
• 自定义数据模式：为特定于代理的状态管理定义类型化的数据结构
• 支持标准输入：直接从shell命令或脚本管道提示

---

创建自定义代理

向项目添加新的代理：

# 交互模式（提示进行自定义）
bunx @aiter/cli add agent my-agent
# 非交互模式，指定自定义
bunx @aiter/cli add agent my-agent --customize commands,tools,mcps
# 添加所有自定义
bunx @aiter/cli add agent my-agent --customize all --interactive false

代理结构

每个代理目录包含：

src/ai/agents/<AGENT_NAME>/
├── commands/           # 自定义斜杠命令
│   └── index.ts       # 导出所有命令
├── mcps/              # MCP服务器配置
│   └── main.json      # 此代理的MCP服务器
├── system-prompts/    # 系统提示
│   └── main.md        # 主系统提示
├── tools/             # 自定义AI工具
│   └── index.ts       # 导出所有工具
├── schema.ts          # 代理状态的数据模式
└── stream-function.ts # 自定义流处理逻辑

---

自定义指南

添加自定义工具

在src/ai/agents/<AGENT_NAME>/tools/中使用AI SDK的tool()函数创建工具。参考src/ai/agents/template了解基本结构，参考src/ai/agents/example了解实现示例。

添加自定义斜杠命令

在src/ai/agents/<AGENT_NAME>/commands/中实现SlashCommand接口，使用yargs风格的选项创建命令。参考src/ai/agents/template了解基本结构，参考src/ai/agents/example了解实现示例。

配置MCP服务器

cp src/ai/agents/<AGENT_NAME>/mcps/templates/main.json.template src/ai/agents/<AGENT_NAME>/mcps/main.json

编辑src/ai/agents/<AGENT_NAME>/mcps/main.json：

{
  "mcpServers": {
    "server0": {
      "type": "stdio",
      "command": "npx",
      "args": ["path/to/server.js"],
      "env": {}
    },
    "server1": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer token"
      }
    },
    "server2": {
      "type": "sse",
      "url": "https://api.example.com/sse",
      "headers": {}
    }
  }
}

自定义系统提示

编辑src/ai/agents/<AGENT_NAME>/system-prompts/main.md来定义AI的行为和个性。

自定义组件

你可以通过在src/components/中创建自定义版本来覆盖任何UI组件。组件系统自动合并你的自定义组件与核心组件。

自定义数据模式

编辑src/ai/agents/<AGENT_NAME>/schema.ts来定义用于特定于代理的状态管理的类型化数据结构。

---

命令行参考

命令行参数

选项	别名	类型	默认值	描述
--agent	-a	字符串	example	指定要使用的代理（必须存在于src/ai/agents/中）
--chat	-c	字符串	null	要恢复的现有聊天会话文件路径
--prompt	-p	字符串	null	开始聊天时发送的初始提示
--help	-h	-	-	显示帮助信息

特殊输入

使用-作为位置参数从标准输入读取提示：

cat question.txt | bun run src/index.tsx -
echo "我的问题" | bun run src/index.tsx -

注意：不能与--prompt组合使用

---

架构

包

• @aiter/core - 提供UI组件、触发系统、MCP管理和聊天会话处理的核心运行库
• @aiter/cli - 用于搭建新应用和代理的CLI工具

关键组件

• 聊天容器：管理聊天界面的主要UI组件
• 触发系统：可扩展的输入处理（命令、上下文等）
• MCP管理器：管理模型上下文协议客户端和工具的单例
• 命令注册表：内置命令和特定于代理命令的动态加载
• 自定义传输：UI和AI流之间的桥梁
• 组件上下文：合并核心和自定义组件的系统

代理系统

每个代理都是隔离的，有自己的：

• 工具集（MCP工具+本地工具）
• 命令注册表（内置+特定于代理）
• 系统提示和配置
• 状态模式

组件系统

组件遵循合并模式：

1. 核心组件由@aiter/core提供
2. 你在src/components/中的自定义组件覆盖匹配名称
3. ComponentsProvider通过useComponents()使所有组件可用
4. 任何组件都可以被定制而不影响其他组件

---

贡献

我们欢迎贡献！这是一个使用Bun工作区管理的单仓库。

仓库结构

aiter/
├── packages/
│   ├── core/          # @aiter/core - 核心运行库
│   ├── cli/           # @aiter/cli - CLI工具
│   │   └── template/  # 新项目的模板（也是开发工作区）
└── scripts/           # 构建脚本

开发设置

# 克隆仓库
git clone https://github.com/pranftw/aiter.git
cd aiter
# 安装依赖
bun install
# 从模板创建.env
cp packages/cli/template/.env.template packages/cli/template/.env

开发工作流程

此单仓库使用直接源导入——开发期间不需要构建步骤！

# 运行模板工作区（开发环境）
bun dev -a example
# 对packages/core/src/*或packages/cli/template/src/*进行更改
# 更改立即反映出来——无需重新构建！
# 检查所有包的类型
bun run typecheck
# 构建包（仅发布时需要）
bun run build
# 清理所有构建
bun run clean

测试CLI命令

# 测试创建命令
bun run dev:cli create app test-app

---

许可证

查看每个包中的LICENSE文件。