# CLI Slash 命令设计规范（草案） > 目标：定义 CLI 中 `/` 命令的命名、交互方式、显示方式与最小功能集。 > 关联文档：`docs/cli_ui_display_spec.md` ## 1. 总体原则 1. **所有主动操作都从 `/` 命令进入**：避免额外快捷键过多导致记忆负担。 2. **命令面板统一交互**：输入过滤、上下选择、Enter 确认。 3. **没有必要的命令不做**：后台内部操作、配置文件管理、文件浏览等不暴露成命令。 4. **审批不做独立命令**：有审批时直接占用输入栏显示审批交互。 5. **命令只负责 UI 入口**：真正执行仍通过后端 API / CLI 适配层完成。 --- ## 2. 启动命令与工作区初始化 ### 2.1 启动命令 正式启动命令建议为： ```bash agents ``` 开发期或兼容别名可保留： ```bash agents-cli ``` 命名理由： - 和项目名一致 - 短、好记 - 类似 `codex` / `claude` 的产品级 CLI 命令 - 比 `agent` 更不容易和泛称混淆 ### 2.2 默认工作区目录 用户在任意目录执行： ```bash cd /Users/jojo/Desktop/test agents ``` CLI 默认使用 `process.cwd()` 作为本次启动的工作区目录。 ### 2.3 当前目录已是工作区 如果当前目录已经存在于工作区列表中： 1. 自动选择该工作区 2. 进入 CLI 主界面 ### 2.4 当前目录不是工作区 如果当前目录不在工作区列表中，启动时先显示确认提示： ```text 当前目录尚未添加为工作区： /Users/jojo/Desktop/test Agent 将在此目录中读取文件、执行命令和修改内容。 是否将此目录添加为工作区？ › 1. 确认，添加并继续 2. 拒绝，退出 ``` 选择 `确认`： ```text • 已添加工作区 test └ /Users/jojo/Desktop/test ``` 然后进入 CLI 主界面。 选择 `拒绝`： ```text 已取消，退出 Agents CLI。 ``` 并退出程序。 ### 2.5 工作区匹配规则 v1 只做精确路径匹配： - 当前目录路径与已有工作区路径完全一致：视为已有工作区 - 当前目录是已有工作区的子目录：仍视为新目录，需要确认是否添加 这样可以保证行为明确： > 在哪个目录启动，Agent 就在哪个目录工作。 ### 2.6 自动工作区名称 自动创建工作区时： - 默认名称使用目录 basename - 如 `/Users/jojo/Desktop/test` → `test` - 如果名称重复，可自动追加序号，例如 `test-2` --- ## 3. 命令面板交互 ### 3.1 触发 用户在输入栏输入 `/` 后打开命令面板。 ```text › / ``` 输入更多字符后实时过滤： ```text › /a /compact 压缩当前对话上下文 › /path 管理路径授权 /permission 切换权限模式 ``` ### 3.2 选择 - `↑` / `↓` 切换当前选中项 - 当前选中项使用高亮颜色 - `Enter` 执行当前命令 - `Esc` 关闭命令面板 ### 3.3 展示格式 ```text › /mo › /model 切换模型与思考模式 ``` 格式规则： - 左侧显示命令名 - 右侧显示简短说明 - 说明必须短，不超过一行 --- ## 4. 最终命令清单 | 命令 | 说明 | 类型 | |---|---|---| | `/new` | 新建对话 | 立即执行 / 可确认 | | `/resume` | 查看对话列表并切换对话 | 选择器 | | `/model` | 切换模型与思考模式 | 选择器 | | `/versioning` | 管理版本控制 | 选择器 | | `/permission` | 切换权限模式 | 选择器 | | `/execution` | 切换执行环境 | 选择器 | | `/workspace` | 选择或切换工作区 | 选择器 | | `/compact` | 压缩当前对话上下文 | 立即执行 / 可确认 | | `/tools` | 启用或禁用工具 | 选择器 | | `/path` | 管理路径授权 | 选择器 / 表单 | | `/skill` | 选择本轮要使用的 skill | 选择器 | | `/status` | 查看当前状态 | 信息面板 | | `/help` | 查看命令帮助 | 信息面板 | | `/clear` | 清空当前 CLI 显示 | 立即执行 | | `/exit` | 退出 CLI | 立即执行 / 可确认 | --- ## 5. 不做的命令 以下命令不做： | 命令 | 不做原因 | |---|---| | `/approval` | 有待审批内容时直接在输入栏显示审批交互，无需手动进入 | | `/memory` | 属于后端/Agent 内部操作，不作为 CLI 常用入口 | | `/files` | CLI 不做文件浏览器，文件操作由 Agent 工具执行 | | `/tasks` | 后台任务数量放在底部状态栏；详细逻辑先不暴露 | | `/focus` | 暂不做额外显示模式 | --- ## 6. 各命令详细设计 ### 6.1 `/new` 说明： ```text /new 新建对话 ``` 行为： - 创建一个空白对话 - 清空当前 CLI 消息区 - 切换到底部输入待命态 如果当前有未完成任务： ```text 当前任务仍在运行，是否新建对话？ › 1. 新建并停止当前任务 2. 等待当前任务完成 3. 取消 ``` --- ### 6.2 `/resume` 说明： ```text /resume 查看对话列表并切换对话 ``` 行为： - 打开历史对话选择器 - 显示最近对话 - 选择后切换当前会话 显示示例： ```text Resume conversation › 今天 14:32 修复 CLI 设计文档 今天 13:10 调研 Claude Code CLI 昨天 22:45 Android 发布联动 ``` 字段建议： - 时间 - 对话标题 / 首条用户消息摘要 - 当前工作区（可选） - 模型（可选） --- ### 6.3 `/model` 说明： ```text /model 切换模型与思考模式 ``` 行为： - 打开模型选择器 - 支持模型和运行模式一起切换 显示示例： ```text Model › 1. 示例模型 当前模型 2. gpt-5.5 高质量编码 3. gpt-5.4-mini 快速低成本 Run mode › 1. thinking 思考模式 2. fast 快速模式 3. deep 深度思考 ``` 规则： - 当前选中项标记为 `current` - 被管理员禁用的模型显示为 disabled，不可选 - fast-only / deep-only 模型需要显示提示 --- ### 6.4 `/versioning` 说明： ```text /versioning 管理版本控制 ``` 为什么用 `versioning`： - 比 `/version` 更明确是“版本控制” - 避免和模型版本混淆 行为： - 打开版本控制设置 / 恢复面板 显示示例： ```text Versioning › 1. 开启版本控制 2. 关闭版本控制 3. 查看版本记录 4. 恢复到选定版本 ``` 字段建议： - 当前是否开启 - 当前跟踪模式 - 最近版本点 - 是否与当前工作区匹配 --- ### 6.5 `/permission` 说明： ```text /permission 切换权限模式 ``` 行为： - 打开权限模式选择器 显示示例： ```text Permission Mode › 1. Readonly 只读，不允许写入 2. Approval 需要审批后执行写入/敏感操作 3. Auto Approval 由自动审批智能体审核 4. Unrestricted 不做权限拦截 ``` 规则： - 当前权限模式显示 `current` - 高风险项需要二次确认 --- ### 6.6 `/execution` 说明： ```text /execution 切换执行环境 ``` 为什么用 `execution`： - 覆盖 `sandbox` 与 `direct` - 比 `/env` 更明确 - 比 `/runtime` 更贴近用户动作 行为： - 打开执行环境选择器 显示示例： ```text Execution Environment › 1. Sandbox 使用 OS 沙箱执行命令 2. Direct 在宿主机直接执行命令 ``` 规则： - `Direct` 需要风险提示 - 如果 direct 有 TTL，显示剩余时间 --- ### 6.7 `/workspace` 说明： ```text /workspace 选择或切换工作区 ``` 行为： - 打开工作区列表 - 支持选择已有工作区 - 支持新建工作区 显示示例： ```text Workspace › 1. agents /Users/jojo/Desktop/agents/正在修复中/agents current 2. test /Users/jojo/Desktop/test 3. 新建工作区... ``` 新建工作区时，输入栏切换成表单： ```text Workspace path › /Users/jojo/Desktop/new-project ``` 可选第二步： ```text Workspace name › new-project ``` --- ### 6.8 `/compact` 说明： ```text /compact 压缩当前对话上下文 ``` 行为： - 触发当前对话压缩 - 压缩前可确认 显示示例： ```text 确认压缩当前对话上下文？ › 1. 压缩 2. 取消 ``` 完成后： ```text • 对话已压缩 └ 当前上下文 24k/200k ``` --- ### 6.9 `/tools` 说明： ```text /tools 启用或禁用工具 ``` 行为： - 打开工具分类选择器 - 支持启用/禁用工具分类 显示示例： ```text Tools › [x] terminal 终端命令 [x] file 文件读写 [ ] web 网络访问 [x] sub_agent 子智能体 ``` 规则： - 空格切换选中 - Enter 保存 - Esc 取消 --- ### 6.10 `/path` 说明： ```text /path 管理路径授权 ``` 行为： - 查看已授权路径 - 添加可读写路径 - 添加只读路径 - 删除授权路径 显示示例： ```text Authorized Paths › 1. 添加可读写路径 2. 添加只读路径 3. 删除授权路径 Current rw /Users/jojo/Desktop/agents ro /Users/jojo/Downloads ``` 添加路径表单： ```text Path › /Users/jojo/Desktop/project ``` --- ### 6.11 `/skill` 说明： ```text /skill 选择本轮要使用的 skill ``` 这是 CLI 新增能力，Web 端暂无对应入口。 行为： - 打开 skill 列表 - 用户选择一个 skill - 下一次发送用户消息时，CLI 在用户消息下方附加一条 user 消息： ```text 先阅读 docs skill ``` ### 显示示例 ```text Skill › docs 阅读文档相关技能 frontend 前端开发相关技能 backend 后端开发相关技能 ``` 选择后输入栏状态栏显示： ```text skill: docs ``` 发送消息时： ```text › 帮我整理一下 CLI 文档 + 先阅读 docs skill ``` 规则： - v1 先做单选 - 选择后只作用于下一条用户消息 - 消息发送后清空当前 skill - 后续可扩展为多选 --- ### 6.12 `/status` 说明： ```text /status 查看当前状态 ``` 行为： - 打开状态信息面板 - 类似 Codex CLI 的状态卡 显示示例： ```text ╭────────────────────────────────────────────────────────────────────╮ │ >_ Agents CLI │ │ │ │ Model: 示例模型 │ │ Directory: ~/Desktop/agents/正在修复中/agents │ │ Workspace: agents │ │ Permissions: auto_approval │ │ Execution: sandbox │ │ Session: 019e253e-7310-7330-ac02-859338456535 │ │ Context window: 99% left (14.6K used / 258K) │ ╰────────────────────────────────────────────────────────────────────╯ ``` #### 字段说明 | 字段 | 说明 | |---|---| | `Model` | 当前模型 | | `Directory` | 当前工作目录 | | `Workspace` | 当前工作区名称 | | `Permissions` | 当前权限模式 | | `Execution` | 当前执行环境 | | `Session` | 当前会话 ID | | `Context window` | 上下文窗口使用情况 | --- ### 6.13 `/help` 说明： ```text /help 查看命令帮助 ``` 显示命令列表： ```text Commands /new 新建对话 /resume 查看对话列表并切换对话 /model 切换模型与思考模式 /versioning 管理版本控制 /permission 切换权限模式 /execution 切换执行环境 /workspace 选择或切换工作区 /compact 压缩当前对话上下文 /tools 启用或禁用工具 /path 管理路径授权 /skill 选择本轮要使用的 skill /status 查看当前状态 /clear 清空当前 CLI 显示 /exit 退出 CLI ``` --- ### 6.14 `/clear` 说明： ```text /clear 清空当前 CLI 显示 ``` 行为： - 只清空 CLI 当前显示区 - 不删除对话历史 - 不影响后端会话 --- ### 6.15 `/exit` 说明： ```text /exit 退出 CLI ``` 行为： - 如果当前无任务，直接退出 - 如果有运行任务，显示确认： ```text 当前任务仍在运行，是否退出？ › 1. 退出并停止当前任务 2. 后台继续运行并退出 3. 取消 ``` --- ## 7. 审批交互与命令系统的关系 审批不是 `/approval` 命令。 当有待审批操作时，输入栏临时切换为审批态： ```text 需要批准：运行 rm -rf dist › 1. 允许一次 2. 切换到无限制 3. 拒绝 ``` 审批完成后恢复普通输入态。 --- ## 8. 底部状态栏与 `/status` 的关系 底部状态栏只显示短信息： ```text 5 后台智能体 3 后台指令 版本控制: 开 自动审批 沙箱 24k/200k ``` `/status` 显示完整信息卡。 --- ## 9. 实现建议 ### 9.1 命令定义结构 ```ts type SlashCommand = { name: string; aliases?: string[]; description: string; kind: 'immediate' | 'picker' | 'panel' | 'form'; run: () => void | Promise; }; ``` ### 9.2 命令状态 ```ts type CliInputMode = | 'composer' | 'slash_menu' | 'picker' | 'approval' | 'form' | 'status_panel' | 'help_panel'; ``` ### 9.3 命令过滤 - 前缀匹配优先 - 模糊匹配其次 - 当前项默认选第一条 --- ## 10. 一句话总结 CLI 的 `/` 命令系统目标是： > 用一个统一命令入口覆盖 Web 对话页的主要直接操作，同时保持终端交互简单、可键盘驱动、低噪声。