# tui-agent

**Repository Path**: cshi/tui-agent

## Basic Information

- **Project Name**: tui-agent
- **Description**: 公司ai考试训练
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 最小可用的 TUI 终端编码 Agent

一个运行在终端内的 AI 编码助手，支持自然语言交互，可自主理解代码仓库上下文、调用工具执行操作，并展示完整推理过程。

## 技术栈

| 类别 | 技术 |
|------|------|
| 语言 | Rust (edition 2021) |
| 异步运行时 | Tokio |
| TUI 框架 | ratatui + crossterm |
| HTTP 客户端 | reqwest (rustls-tls) |
| 序列化 | serde + serde_json |
| LLM 协议 | Anthropic Messages API (SSE 流式) |
| 配置 | JSON 双层级（用户级 + 项目级） |
| 会话持久化 | JSONL |

## 快速开始

### 前置要求

- Rust 工具链（1.70+）
- Anthropic API Key

### 安装与构建

```bash
# 克隆项目
git clone <repo-url>
cd tui-agent

# 构建（debug）
cargo build

# 构建（release）
cargo build --release

# 运行测试
cargo test

# 运行集成测试
cargo test --test integration_tests

# 格式化代码
cargo fmt

# Lint 检查
cargo clippy
```

### 配置

**用户级配置** `~/.config/tui-agent/config.json`（可选，有默认值）：

```json
{
  "provider": "anthropic",
  "model": "claude-sonnet-4-6",
  "api_base_url": "https://api.anthropic.com",
  "api_key": "sk-ant-xxxxxxxxxxxxx",
  "timeout_secs": 120,
  "max_rounds": 20,
  "max_retries": 3,
  "shell": {
    "blacklist": ["rm -rf /", "sudo rm -rf"],
    "confirm_patterns": ["rm ", "mv ", "cp ", "git push", "cargo publish"]
  }
}
```

**项目级配置** `./.tui-agent.json`（覆盖用户级配置）：

```json
{
  "model": "claude-opus-4-8",
  "max_rounds": 10
}
```

### 启动

```bash
# 确保已配置 API Key（用户级或项目级）
cargo run

# 或使用 release 构建
cargo run --release
```

启动后进入 TUI 交互界面，在底部输入栏输入内容即可与 Agent 对话。

## 使用方式

### 基本交互

在输入栏 `> ` 后输入任何内容，按 `Enter` 发送给 AI Agent。Agent 会自主分析、调用工具并返回结果。

### 内置命令

| 命令 | 功能 |
|------|------|
| `/help` | 显示所有可用命令 |
| `/help <cmd>` | 查看指定命令的详细帮助 |
| `/clear` | 清空当前对话（仅内存，不删文件） |
| `/model` | 查看当前使用的模型 |
| `/model <name>` | 切换到指定模型 |
| `/status` | 查看运行状态（模型、轮次、消息数） |
| `/exit` | 保存会话并退出 |

### 键盘快捷键

| 按键 | 功能 |
|------|------|
| `Enter` | 发送消息 |
| `Backspace` | 删除字符 |
| `←` `→` | 移动光标 |
| `Home` `End` | 跳转行首/行尾 |
| `↑` `↓` | 滚动聊天视图 |
| `PageUp` `PageDown` | 快速滚动 |
| `Ctrl+C` | 退出（自动保存会话） |
| `Esc` | 取消权限确认提示 |

### 可用工具

Agent 可自主调用以下工具：

| 工具 | 风险等级 | 功能 |
|------|---------|------|
| `read_file` | Read | 读取文件内容，支持行偏移和行数限制 |
| `list_directory` | Read | 列出目录结构 |
| `search_content` | Read | 正则搜索文件内容 |
| `execute_shell` | Shell | 执行 Shell 命令 |

### 权限模型

- **Read** 工具：自动允许
- **Shell** 命令：
  - 匹配 `blacklist` 正则 → 自动拒绝
  - 匹配 `confirm_patterns` 正则 → 弹窗确认（y/n）
  - 其余 → 自动允许

## 项目结构

```
tui-agent/
├── Cargo.toml              # 项目元数据与依赖
├── CLAUDE.md               # AI 助手开发指引
├── README.md               # 项目介绍
├── src/
│   ├── lib.rs              # 库根节点（供集成测试引用）
│   ├── main.rs             # 入口点 + App 编排
│   ├── agent/              # Agent 核心
│   │   ├── context.rs      # 上下文管理器（system prompt + 消息收集）
│   │   ├── events.rs       # AgentEvent 枚举定义
│   │   ├── loop_.rs        # Agent 循环状态机
│   │   └── provider/       # LLM Provider 抽象层
│   │       ├── anthropic.rs# Anthropic Messages API + SSE 流式
│   │       ├── traits.rs   # LlmProvider trait
│   │       └── types.rs    # ProviderError / StreamEvent
│   ├── commands/           # 内置命令
│   │   ├── parser.rs       # 命令解析器（/ 前缀识别）
│   │   └── handler.rs      # 命令处理器（/help /clear 等）
│   ├── config/             # 配置系统
│   │   ├── types.rs        # Config / ShellConfig 结构体
│   │   └── loader.rs       # 双层级加载 + 浅合并
│   ├── logger/             # 日志系统
│   │   └── writer.rs       # Q&A Markdown 文件写入
│   ├── permission/         # 权限控制
│   │   ├── types.rs        # PermissionDecision 枚举
│   │   └── engine.rs       # 三级权限引擎（Allow/Deny/Ask）
│   ├── session/            # 会话管理
│   │   ├── types.rs        # Message / Session 结构体
│   │   └── store.rs        # JSONL 持久化 + 项目 Hash 隔离
│   ├── tools/              # 工具系统
│   │   ├── traits.rs       # Tool trait 定义
│   │   ├── types.rs        # RiskLevel / ToolOutput / ToolError
│   │   ├── registry.rs     # ToolRegistry 注册表
│   │   ├── read_file.rs    # 文件读取工具
│   │   ├── list_directory.rs # 目录浏览工具
│   │   ├── search_content.rs # 内容搜索工具
│   │   └── execute_shell.rs  # Shell 执行工具
│   └── tui/                # TUI 界面
│       ├── app.rs          # TuiApp 状态 + 事件循环 + 布局
│       ├── chat_view.rs    # 聊天视图组件
│       ├── input_bar.rs    # 输入栏组件
│       ├── permission_prompt.rs # 权限确认提示组件
│       └── status_bar.rs   # 状态栏组件
├── tests/
│   └── integration_tests.rs # 集成测试（Mock Provider）
└── .ai_history/logs/       # 问答历史记录
```

## 架构

```
┌────────────────────────────────────────────┐
│  main.rs → App (全局状态 + 事件循环)         │
├────────────┬───────────────┬───────────────┤
│   TUI      │  Agent Loop   │  Commands     │
│  (ratatui) │  (状态机)      │  (内置命令)    │
├────────────┴───────────────┴───────────────┤
│  Provider  │  Tool System  │  Permission   │
│  (trait)   │  (trait+reg)  │  Engine       │
├────────────────────────────────────────────┤
│  Config    │  Session Store │  Logger      │
└────────────────────────────────────────────┘
```

## 数据文件

| 路径 | 用途 |
|------|------|
| `~/.config/tui-agent/config.json` | 用户级配置 |
| `./.tui-agent.json` | 项目级配置（覆盖用户级） |
| `~/.local/share/tui-agent/project/<hash>/session.jsonl` | 会话持久化 |
| `./.ai_history/logs/<n>-<YYYYMMDD>-<HHMM>.md` | 问答历史记录 |

## License

MIT