Xiao Zhi CLI（小智）

小智（Xiao Zhi）——一个带 OpenTUI 界面的终端 AI Agent，TypeScript 编写，支持任意 OpenAI 兼容接口和工具调用。

特性

• OpenTUI 黑色终端界面：滚动对话区、输入框和底部当前目录状态栏
• 流式输出到终端，支持 Ctrl+C 中断当前生成
• 支持 thinking 模型（如 qwen3.5、deepseek-r1），推理过程灰色显示、不混入最终回复
• 工具调用循环：read_file / write_file / run_command
• 多模型可配置：Ollama / DeepSeek / Kimi / 通义 / 本地任意 OpenAI 兼容服务，改配置即换
• 危险命令（rm -rf、format、dd if= 等）执行前人工确认
• 上下文自动精简、工具输出自动截断

快速开始

项目是根目录 pnpm workspace（packages/*）的一部分，依赖在根目录统一安装：

OpenTUI 需要 Node.js 26.4+（启用 FFI） 或 Bun 1.3+。当前启动脚本已带上 Node FFI 参数。

# 在仓库根目录首次安装依赖（含 xiao-zhi-cli）
pnpm install

cd packages/xiao-zhi-cli
pnpm start

复制 .env.example 为 .env，然后按实际服务配置。示例使用本机 Ollama，不包含任何真实服务地址或密钥：

AGENT_BASE_URL=http://localhost:11434/v1
AGENT_API_KEY=your-api-key
AGENT_MODEL=qwen3
# 可选：开启 thinking，默认关闭
AGENT_THINKING=1

也可以指定模型启动：

pnpm start -- --model llama3.1

连接其他模型

通过环境变量或启动参数配置（OpenAI 兼容格式）：

| 服务 | AGENT_BASE_URL | AGENT_API_KEY | 示例模型 | |------|---------------|---------------|---------| | Ollama（本机） | http://localhost:11434/v1 | 任意值 | qwen3 | | Ollama（本机） | http://localhost:11434/v1 | 任意值 | qwen3 | | DeepSeek | https://api.deepseek.com/v1 | 你的 key | deepseek-chat | | Kimi | https://api.moonshot.cn/v1 | 你的 key | moonshot-v1-8k |

# 环境变量方式
export AGENT_BASE_URL=https://api.deepseek.com/v1
export AGENT_API_KEY=your-api-key
export AGENT_MODEL=deepseek-chat
pnpm start

# 或启动时开启 thinking
pnpm start -- --thinking

# 或命令行参数方式
node src/index.ts --base-url https://api.deepseek.com/v1 --api-key your-api-key --model deepseek-chat

对话内命令

| 命令 | 说明 | |------|------| | /help | 帮助 | | /exit /quit | 退出 | | /clear | 清空会话上下文 | | /models | 从模型服务获取并列出所有模型 | | /model | 列出模型 | | /model <序号\|名称> | 按序号或名称切换模型 | | /tools | 列出可用工具 |

输入 /models 后，可以使用 /model 1 这样的序号，或直接输入 /model qwen3.5:9b 切换模型。模型列表来自当前 AGENT_BASE_URL 的 OpenAI 兼容 /models 接口。

发布到 npm

cd packages/xiao-zhi-cli
npm login
npm version patch
npm publish --access public

如果你还没有准备好公开发布，可以先本地验证：

npm pack --dry-run

测试

node scripts/smoke.mjs   # 本地 mock 接口验证流式解析 + 工具循环，无需真实模型
pnpm typecheck           # TypeScript 类型检查

项目结构

src/
  index.ts    入口：参数解析、OpenTUI 事件和斜杠命令
  ui.ts       OpenTUI 界面：对话滚动区、输入框、底部目录状态栏
  config.ts   配置加载（环境变量 + 命令行参数）
  provider.ts OpenAI 兼容流式调用（SSE 解析、工具调用累积）
  agent.ts    Agent 主循环（推理 → 工具 → 回填，最多 8 轮）
  tools.ts    工具实现：read_file / write_file / run_command + 危险命令拦截
  types.ts    共享类型
scripts/
  smoke.mjs   冒烟测试（mock 模型接口）

已知限制

• 会话上下文固定保留最近 30 条消息，长任务中间过程会被丢弃
• 工具仅 3 个基础操作，需要更多能力（联网、搜索等）自行在 tools.ts 扩展
• write_file 不限制路径，注意模型可能写任意位置