Sema Code CLI 用户指南

版本: 0.1.0
Sema Code CLI 是一个运行在终端中的 AI 编程助手，提供 Claude Code 风格的 REPL 交互体验。

1. 安装与启动

前提条件

Node.js >= 20
pnpm 包管理器（推荐）

安装

pnpm install        # 安装依赖
pnpm build          # 编译 TypeScript

启动

# 开发模式（支持热重载）
pnpm dev

# 生产模式
pnpm start

# 调试模式（支持 React DevTools）
pnpm dev:debug

启动后，终端进入全屏模式，显示欢迎界面。

2. 首次启动 — 配置模型

首次启动时，系统未配置任何 AI 模型，界面会提示你输入 /model 进入模型配置。

添加预置模型

输入 /model 进入模型管理界面
按 a 添加模型
从预置列表中选择一个模型（如 Claude Sonnet, GPT-4o 等）
输入你的 API Key
系统自动测试连接并保存

添加自定义模型

进入模型管理后按 a
选择 "自定义模型"
填写模型名称、Provider、Base URL、API Key
系统测试连接并保存

切换主模型

在模型列表页，用 ↑↓ 选择模型，按 Enter 设为主模型（标有 ● 和 "← 主模型" 即为当前使用的模型）。

编辑 / 删除模型

按 e — 编辑所选模型的 API Key
按 d — 删除所选模型
按 Esc — 返回聊天界面

3. 基础对话

配置好模型后，你会看到绿色的 ❯ 输入提示符。在这里输入问题，按 Enter 发送。

基本交互

❯ 帮我写一个 TypeScript 排序函数

AI 收到请求后，输入区域会显示动画提示（如 ⠋ 思考中...），处理完成后显示回复。

粘贴多行文本

支持直接粘贴多行文本到输入框，粘贴的换行会自动保留，显示为多行输入：

❯ 解释以下代码：
  function foo() {
    return bar();
  }
█

中断处理

在处理过程中按 Esc 可以中断 AI 的当前操作，回到输入状态。

历史记录

↑ — 上一条历史输入
↓ — 下一条历史输入（按到最后回到空白输入）

4. 斜杠命令

在输入框输入 / 会触发命令菜单，显示可用命令及自动补全下拉框。

命令	说明
`/model`	进入模型管理界面
`/mcp`	进入 MCP Server 管理界面
`/clear`	清空当前会话
`/exit`	退出程序

自动补全

输入 / 后，匹配的命令会以下拉列表显示
↑↓ — 在补全列表中上下选择
Tab 或 Enter — 确认选择
Esc — 关闭补全列表
输入空格后自动关闭补全列表，进入正常输入模式

5. 模型管理

输入 /model 进入模型管理界面。

模型管理快捷键

按键	功能
`a`	添加新模型
`e`	编辑当前选中模型的 API Key
`d`	删除当前选中模型
`Enter`	切换主模型
`↑↓`	上下选择
`Esc`	返回聊天

API Key 编辑视图

输入新的 API Key
Enter — 测试连接并保存
Esc — 取消返回

6. MCP Server 管理

输入 /mcp 进入 MCP Server 管理界面。MCP (Model Context Protocol) 是一种标准协议，允许 AI 调用外部工具和服务。

MCP 列表页

列表显示所有已配置的 MCP Server 及其连接状态：

图标	状态
`●` 绿色	已连接
`◐` 黄色	连接中
`○` 白色	未连接
`✗` 红色	连接错误

快捷键：

Enter — 进入选中 Server 的详情页
↑↓ — 上下选择
Esc — 返回聊天

MCP 详情页

显示 Server 的完整配置信息：名称、描述、传输方式、连接状态、命令/URL、错误信息、可用工具列表。

快捷键：

e — 启用/禁用当前 Server
r — 重新连接当前 Server
Esc — 返回列表

7. 键盘快捷键

全局

快捷键	功能
`Esc`	中断 AI 处理 / 关闭弹窗 / 返回上级
`Ctrl+C`	强制退出程序

聊天输入

快捷键	功能
`Enter`	发送消息
`Esc`	中断 AI 处理
`↑`	上一条历史
`↓`	下一条历史
`/`	触发命令菜单
`Tab`	命令补全

权限确认

快捷键	功能
`y`	同意本次操作
`a`	始终允许
`n`	拒绝

表单交互

快捷键	功能
`↑↓`	选择选项（单选/多选时）
`Enter`	确认 / 下一步
`Tab`	跳到下一个问题
`Esc`	取消

8. 功能说明

状态栏

界面底部始终显示一行状态栏，包含：

模型名称 — 当前使用的 AI 模型
模式 — Agent 模式
Token 用量 — 本次会话的 Token 消耗
状态 — 空闲 / 处理中

消息展示

用户消息 — 绿色 ❯ 标识
AI 回复 — 支持 Markdown 渲染（标题、代码块、列表、引用等）
工具调用 — 显示工具名称、执行状态（运行中/完成/错误）
Agent 任务 — 子 Agent 的执行状态
思考过程 — AI 的推理过程以灰色斜体显示

权限系统

当 AI 需要执行文件操作、运行命令等工具时，会在消息流中内联显示权限确认，包含工具名称和操作内容，你需要在三个选项中做出选择。

Todo 列表

AI 在执行复杂任务时会生成 Todo 列表，在输入区域上方显示。每项 Todo 显示状态图标（✓ 已完成，○ 待办）和任务描述。

上下文压缩

当会话上下文超出 Token 限制时，系统会自动压缩历史消息。压缩完成后会在界面显示通知，告知压缩前后的 Token 数量及压缩比例。

9. 常见问题

Q: 启动后显示"请先输入 /model 配置模型"

首次使用需要配置 AI 模型。输入 /model 进入模型管理界面，添加你的 API Key。

Q: 如何切换不同的 AI 模型？

输入 /model，用 ↑↓ 选择目标模型，按 Enter 切换。标有 ● 的为当前主模型。

Q: 如何退出程序？

输入 /exit 或按 Ctrl+C。

Q: 粘贴文本后输入框显示异常？

程序支持粘贴多行文本。如果粘贴内容被自动提交，可能是因为粘贴内容中包含回车符。请在粘贴前确保输入框处于正常输入状态。

Q: MCP Server 连接失败？

进入 /mcp 管理页，选中失败的 Server 按 Enter 查看详情和错误信息，检查命令路径或 URL 是否正确，然后按 r 重新连接。

Q: AI 回复被中断了怎么办？

中断后输入框恢复正常，可以继续输入新的请求。注意：中断前的部分回复仍然保留在对话中。

FilesExpand file tree

UserGuide.md

Latest commit

History