MistAgent CLI

基于 React + Ink 的终端 AI 对话客户端，连接 WebAgent 后端服务。

功能特性

• 终端原生 UI：基于 React 19 + Ink 的终端界面，支持 Markdown 渲染、语法高亮、加载动画
• SSE 流式对话：通过 Server-Sent Events 实时接收 LLM 流式响应
• 多会话管理：创建、切换、删除对话会话
• 模型切换：运行时动态切换 LLM 模型
• 文件上传：支持通过 @file 引用本地文件注入对话上下文
• 斜杠命令：/help、/model、/session、/tools 等快捷命令
• 代码分析：内置 tree-sitter 多语言代码结构分析工具
• 文件穿透：当后端启用 ENABLE_FILE_TUNNEL=true 时，LLM 调用的文件操作在客户端本地执行

技术栈

| 层级 | 技术 | |---|---| | UI 框架 | React 19 + Ink 6 | | Markdown | marked + marked-terminal | | 代码分析 | tree-sitter（支持 10 种语言） | | HTTP 客户端 | 内置 fetch（eventsource-parser 解析 SSE） | | CLI 参数 | yargs | | 图结构 | graphology（代码分析依赖图） |

项目结构

MistAgentcli/
├── index.ts                    # 入口文件
├── src/
│   ├── main.tsx                # React 渲染入口
│   ├── api/                    # 后端 API 客户端
│   │   ├── client.ts           # HTTP 客户端（baseURL + token）
│   │   ├── auth.ts             # 登录/认证 API
│   │   ├── chat.ts             # 对话 API（SSE 流式）
│   │   ├── sessions.ts         # 会话管理 API
│   │   ├── models.ts           # 模型列表/切换 API
│   │   ├── tools.ts            # 工具列表 API
│   │   └── tunnel.ts           # 文件穿透结果回传 API
│   ├── components/             # UI 组件
│   │   ├── App.tsx             # 根组件
│   │   ├── AppLayout.tsx       # 布局
│   │   ├── Composer.tsx        # 输入编辑器
│   │   ├── MainContent.tsx     # 主内容区
│   │   ├── Header.tsx          # 顶栏
│   │   ├── Footer.tsx          # 底栏
│   │   ├── LoginPrompt.tsx     # 登录界面
│   │   ├── ModelPicker.tsx     # 模型选择器
│   │   ├── SessionPicker.tsx   # 会话选择器
│   │   ├── messages/           # 消息类型组件
│   │   └── shared/             # 通用组件
│   ├── contexts/               # React Context
│   │   ├── AppContext.tsx      # 应用级状态
│   │   ├── ChatContext.tsx     # 对话状态
│   │   ├── SessionContext.tsx  # 会话状态
│   │   ├── ModelContext.tsx    # 模型状态
│   │   ├── UIContext.tsx       # UI 状态
│   │   └── KeypressContext.tsx # 键盘输入
│   ├── hooks/                  # 自定义 Hooks
│   │   ├── useChat.ts          # 核心：SSE 流解析 + 消息状态管理
│   │   ├── useSlashCommand.ts  # 斜杠命令处理
│   │   ├── useTextBuffer.ts    # 文本缓冲区
│   │   └── ...
│   ├── tools/                  # 本地工具
│   │   └── code-analyzer/      # 代码结构分析（tree-sitter）
│   ├── types/                  # TypeScript 类型定义
│   │   ├── api.ts              # 后端 API 类型（含 SSEToolExecuteRequest）
│   │   └── history.ts          # 消息历史类型
│   └── utils/                  # 工具函数
│       ├── fileTunnel.ts       # 文件穿透：本地文件操作执行器
│       ├── fileRef.ts          # 文件引用处理
│       ├── config.ts           # 配置管理
│       └── ...
├── vendor/                     # 第三方依赖
├── package.json
└── tsconfig.json

快速开始

1. 安装依赖

npm install

需要 Node.js >= 20。

2. 配置后端地址

编辑 src/utils/config.ts 或通过环境变量设置后端 URL：

export MIST_API_URL=http://your-server:8000

3. 开发模式

npm run dev

4. 构建 & 运行

npm run build
npm start
# 或直接
npx mist

文件穿透（File Tool Tunneling）

当后端 WebAgent 设置 ENABLE_FILE_TUNNEL=true 时，LLM Agent 调用的文件操作工具（read_file、write_file 等）不在服务器执行，而是穿透到 CLI 客户端在用户 PC 上本地执行。

工作流程

后端 LLM 调用 read_file
    ↓
ProxyFileTool 创建 PendingRequest，await asyncio.Event
    ↓
SSE 推送 tool_execute_request 事件到 CLI
    ↓
useChat.ts 收到事件 → 调用 fileTunnel.executeFileOperation()
    ↓
本地 Node.js fs 执行文件操作
    ↓
POST /api/v1/tunnel/result 回传结果
    ↓
后端 PendingRequest 被唤醒 → LangGraph 继续执行

涉及文件

| 文件 | 作用 | |---|---| | src/utils/fileTunnel.ts | 本地文件操作执行器（read_file、write_file、list_directory、copy_file、move_file、file_delete、file_search） | | src/api/tunnel.ts | submitTunnelResult() — 将本地执行结果 POST 回服务端 | | src/hooks/useChat.ts | 处理 SSE tool_execute_request 事件，调度本地执行 + 回传 | | src/types/api.ts | SSEToolExecuteRequest 接口定义 |

SSE 事件格式

{
  "event": "tool_execute_request",
  "data": {
    "request_id": "uuid",
    "tool_name": "read_file",
    "args": { "file_path": "/path/to/file" },
    "thread_id": "uuid"
  }
}

回传格式

POST /api/v1/tunnel/result
{
  "request_id": "uuid",
  "success": true,
  "result": "文件内容或操作结果",
  "error": ""
}

支持的工具

| 工具名 | 操作 | |---|---| | read_file | 读取文件内容 | | write_file | 写入文件（自动创建目录） | | list_directory | 列出目录内容 | | copy_file | 复制文件 | | move_file | 移动/重命名文件 | | file_delete | 删除文件 | | file_search | 递归搜索匹配文件名的文件 |

超时

客户端需在 120 秒 内完成操作并回传结果，否则后端 ProxyFileTool 返回超时错误。

与 WebAgent 后端的关系

MistAgent CLI 是 WebAgent 的终端客户端。WebAgent 提供 REST + SSE + WebSocket API，MistAgent CLI 通过这些接口与后端交互。

• 后端仓库：../WebAgent/
• API 文档：参见 WebAgent README.md 的 API 接口 部分