# cmdc_tui
基于 [ExRatatui](https://hex.pm/packages/ex_ratatui) 的 [CMDC](https://hex.pm/packages/cmdc) AI Agent 终端交互界面（TUI）。
在终端内与 AI Agent 实时对话，实时查看工具调用过程、Todo 列表、Token 用量。
```
┌─────────────────────────────────┬──────────────────┐
│ │ Tools [Tab] │
│ 对话 (3) │ ────────────── │
│ ◆ AI │ read_file done │
│ 你好！需要帮忙吗？ │ shell running │
│ ├──────────────────┤
│ ▶ You │ │
│ 帮我列出当前目录的文件 │ │
│ │ │
│─────────────────────────────────┤ │
│ 输入 ────────────────────────── │ │
│ 输入消息... (Ctrl+S 发送) │ │
└─────────────────────────────────┴──────────────────┘
│ idle │ session: live │ MiniMax-M2.7 │ Ctrl+S:发送 │
└──────────────────────────────────────────────────────┘
```
---
## 安装
在 `mix.exs` 中添加依赖：
```elixir
def deps do
[
{:cmdc_tui, "~> 0.1"}
]
end
```
---
## 快速启动（命令行）
`cmdc_tui` 内置 `mix tui` 任务，通过环境变量配置后直接运行：
```bash
# 无 Agent（纯输入测试）
mix tui
# 带 Agent（无工具）
LLM_API_KEY="sk-xxx" \
LLM_BASE_URL="https://api.minimaxi.com/anthropic" \
mix tui
# 带 Agent + 工具（推荐）
LLM_API_KEY="sk-xxx" \
LLM_BASE_URL="https://api.minimaxi.com/anthropic" \
LLM_TOOLS="shell,read_file,write_file,list_dir,glob,grep" \
LLM_WORKING_DIR="/your/project" \
mix tui
```
### 环境变量说明
| 变量 | 必填 | 说明 | 默认值 |
|------|------|------|--------|
| `LLM_API_KEY` | 连接 Agent 时必填 | LLM API 密钥 | — |
| `LLM_BASE_URL` | 否 | API 地址（自定义端点时填写） | Anthropic 官方 |
| `LLM_MODEL_ID` | 否 | 模型 ID | `MiniMax-M2.7` |
| `LLM_SYSTEM_PROMPT` | 否 | 系统提示词 | `你是一个 AI 助手。` |
| `LLM_TOOLS` | 否 | 启用工具，逗号分隔 | 无 |
| `LLM_WORKING_DIR` | 否 | Agent 工作目录（文件工具的根路径） | 当前目录 |
### 可用工具
| 工具名 | 功能 |
|--------|------|
| `shell` | 执行 shell 命令 |
| `read_file` | 读取文件 |
| `write_file` | 写入文件 |
| `edit_file` | 编辑文件（字符串替换） |
| `list_dir` | 列出目录 |
| `glob` | 文件模式匹配 |
| `grep` | 搜索文件内容 |
| `ask_user` | Agent 向用户提问（触发弹窗） |
| `write_todos` | Agent 写入 Todo 列表 |
| `compact_conversation` | 压缩对话历史 |
| `task` | 创建子任务 |
---
## 代码集成
如果需要在 Elixir 代码中嵌入 TUI：
```elixir
# 最简集成
{:ok, session} = CMDC.create_agent(
model: "anthropic:claude-sonnet-4-5",
tools: [CMDC.Tool.Shell, CMDC.Tool.ReadFile],
provider_opts: [api_key: System.get_env("ANTHROPIC_API_KEY")],
working_dir: "/my/project"
)
CmdcTui.start(session: session)
# 也可以不传 session，仅用作本地输入测试
CmdcTui.start()
```
### `CmdcTui.start/1` 参数
| 参数 | 类型 | 说明 |
|------|------|------|
| `:session` | `pid` | CMDC Agent session pid |
| `:session_id` | `String.t()` | 会话 ID（显示在状态栏） |
| `:model_name` | `String.t()` | 模型名称（显示在状态栏） |
---
## 界面说明
### 布局
```
┌──────────────────────────┬─────────────────┐
│ ChatPanel │ 侧栏 (Tools / │
│ （消息列表 + 输入框） │ Todo) │
├──────────────────────────┴─────────────────┤
│ StatusBar │
└─────────────────────────────────────────────┘
```
> 侧栏在终端宽度 **≥ 80 列**时自动显示。
### ChatPanel
- **◆ AI** — AI 回复，自动检测并渲染 Markdown（代码块、标题、列表等）
- **▶ You** — 用户消息
- **⚙ tool_name** — 工具执行结果摘要
- **AI is thinking...** — Agent 思考中的动态 spinner
- **◆ AI (streaming…)** — 流式输出进行中
### Tools 面板（侧栏）
按 `Tab` 切换到 Tools 面板，显示每次工具调用的：
| 列 | 内容 |
|----|------|
| Name | 工具名称 |
| Args | 参数摘要（前 30 字符） |
| Status | `⏳ running` / `✓ done` / `✗ error` / `⊘ blocked` |
| Time | 耗时（ms 或 s） |
### Todo 面板（侧栏）
按 `Tab` 切换到 Todo 面板，显示 Agent 的任务列表（需 Agent 调用 `write_todos` 工具）：
- ☐ 未开始（白色）
- **▶ 进行中**（黄色加粗）
- ✓ 已完成（绿色）
- ✗ 已取消（灰色）
### StatusBar
底部状态栏从左到右依次显示：
```
│ idle │ session: live │ MiniMax-M2.7 │ in: 1024 / out: 256 │ $0.001 │ Enter:发送 ...
```
---
## 快捷键
### 全局
| 快捷键 | 功能 |
|--------|------|
| `Enter` | 发送消息 |
| `Shift+Enter` | 换行（多行输入） |
| `Ctrl+S` | 发送消息（备用） |
| `Ctrl+P` | 打开命令面板 |
| `Tab` | 切换侧栏（Tools ↔ Todo） |
| `↑ / ↓` | 滚动消息历史 |
| `PgUp / PgDn` | 快速滚动（每次 5 条） |
| `Ctrl+C` | 退出 TUI |
### 命令面板（Ctrl+P）
| 操作 | 功能 |
|------|------|
| 输入文字 | 过滤命令（前缀匹配） |
| `↑ / ↓` | 上下选择 |
| `Enter` | 执行选中命令 |
| `Esc` | 关闭面板 |
### Slash 命令（输入框）
在输入框中输入 `/` 触发内联自动补全，继续输入过滤：
| 命令 | 别名 | 功能 |
|------|------|------|
| `/help` | `/h`, `/?` | 显示帮助 |
| `/clear` | `/cls` | 清空对话历史 |
| `/model` | `/m` | 查看当前模型 |
| `/compact` | — | 压缩对话历史 |
| `/stop` | `/abort`, `/cancel` | 终止 Agent |
| `/tools` | — | 切换到 Tools 面板 |
| `/todos` | — | 切换到 Todo 面板 |
| `/quit` | `/exit`, `/q` | 退出 TUI |
### HITL 审批弹窗（ApprovalDialog）
当 Agent 请求操作审批时弹出：
| 按键 | 功能 |
|------|------|
| `y` | 批准 |
| `n` | 拒绝 |
| `Esc` | 拒绝并关闭 |
### Agent 提问弹窗（AskUserDialog）
当 Agent 调用 `ask_user` 工具时弹出：
| 按键 | 功能 |
|------|------|
| 输入文字 | 回答内容 |
| `1`~`9` | 快速选择选项（有选项时） |
| `Enter` | 提交回答 |
| `Esc` | 取消（提交空字符串） |
---
## 要求
- Elixir `~> 1.17`
- [CMDC](https://hex.pm/packages/cmdc) `~> 0.1`
- [ExRatatui](https://hex.pm/packages/ex_ratatui) `~> 0.5.1`（含预编译 NIF，无需 Rust 工具链）
- 终端支持 256 色 / TrueColor（推荐）
- 终端宽度 **≥ 80 列**可显示侧栏
---
## 常见问题
**Q: 侧栏没有显示？**
终端宽度不足 80 列时侧栏自动隐藏。请把终端窗口拉宽后重启 TUI。
**Q: 工具面板没有内容？**
需要在创建 Agent 时配置 `tools` 参数，或在 `mix tui` 时设置 `LLM_TOOLS` 环境变量。Agent 调用工具后侧栏才会有数据。
**Q: 输入中文有延迟？**
请使用 `mix tui` 直接启动，不要用 `iex -S mix`。`iex` 的 IO 系统会与 TUI 争抢终端控制权，导致输入延迟。
**Q: Shift+Enter 无法换行（跟 Enter 一样发送了）？**
你的终端不支持 Kitty keyboard protocol（CSI u）。TUI 启动时会自动尝试启用该协议，但部分终端不支持：
- **macOS Terminal.app** — 不支持，Enter 和 Shift+Enter 无法区分，请用 `Ctrl+S` 发送
- **iTerm2** — 需手动开启：Preferences → Profiles → Keys → 勾选 "Report modifiers using CSI u"
- **WezTerm / Kitty** — 原生支持，无需配置
如果 Shift+Enter 始终无法换行，可以用 `Ctrl+S` 作为备用发送键。
**Q: AI 回复没有渲染 Markdown？**
只有包含换行、代码块（` ``` `）、加粗（`**`）、列表（`- `）或标题（`#`）的内容才会用 Markdown 渲染，纯文本直接显示。
