cmdc_tui

基于 ExRatatui 的 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 中添加依赖：

def deps do
  [
    {:cmdc_tui, "~> 0.1"}
  ]
end

快速启动（命令行）

cmdc_tui 内置 mix tui 任务，通过环境变量配置后直接运行：

# 无 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：

# 最简集成
{: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~> 0.1
ExRatatui~> 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 渲染，纯文本直接显示。