使用手册 v0.2.0

# 使用手册

OpenDesk CLI 是运行在终端中的 AI 助手，面向办公和生产力场景，提供一站式 AI 服务。
用智能重新定义生产力，让工作更高效、生活更便捷。

快速开始
GitCode 仓库

## 简介

OpenDesk CLI 是 OpenDesk（一站式跨平台 AI 办公套件）的命令行版本。它提供了基于终端的文本用户界面（TUI），让您可以在不启动桌面应用的情况下使用 OpenDesk 的全部核心功能：AI 对话、任务管理、文件操作、邮件收发、日程管理等。

### 终端优先体验

基于差分渲染的 TUI 界面，超长任务仍保持顺畅的流式输出。

### 完善的 Agent 能力

标准 Agentic Loop、丰富内置工具、面向 Agent 的文件系统与混合搜索。

### 丰富的生态集成

主流大模型、搜索 API、MCP Server、技能（Skills）一键接入。

### 对话式配置

不知道怎么用？直接问 AI 助手，一切都在自由的对话中完成。

## 安装与启动

### 通过 npm 安装

运行以下命令安装最新稳定版本：

    $ npm install -g @bitclub.ai/opendesk-cli
    $ opendesk

或安装 Nightly（每日构建）版本以体验最新功能：

    $ npm install -g @bitclub.ai/opendesk-cli@nightly
    $ opendesk

提示：Nightly 版本能持续获取最新功能，但由于未经充分测试，可能存在稳定性问题。

### 命令行参数

    opendesk [workspace] [选项]

参数 | 说明 | 默认值
--- | --- | ---
`workspace` | 工作区目录路径 | 当前目录 `.`
`--model <alias>` | 指定要使用的模型别名 | 配置的默认模型
`-c, --command <cmd>` | 一次性执行命令后退出（非交互模式） | 无
`-v, --version` | 显示版本信息 | 无

### 使用示例

    # 在当前目录启动
    $ opendesk

    # 在指定目录启动
    $ opendesk /path/to/workspace

    # 使用特定模型启动
    $ opendesk --model gpt-4

    # 一次性执行命令
    $ opendesk -c "分析当前目录的代码结构"

[截图] CLI 启动界面

展示 OpenDesk CLI 的完整 TUI 界面布局

## 模型配置

OpenDesk 通过集中式配置管理 AI 模型。您需要先配置模型服务商（Provider），再添加模型（Model），最后设置默认模型。

### 首次配置流程

1. 1 输入 `/config` 打开配置菜单
2. 2 选择 "模型服务商配置"，添加一个模型服务商（如 OpenRouter、OpenAI 等）
3. 3 选择 "模型配置"，添加一个具体的模型
4. 4 选择 "默认模型配置"，选择您要使用的默认模型

[截图] /config 配置菜单界面

展示模型服务商配置、模型配置、默认模型配置选项

### 服务商配置

每个服务商需要配置以下信息：

字段 | 说明 | 示例
--- | --- | ---
`name` | 服务商名称 | `openrouter`
`base_url` | API 基础地址 | `https://openrouter.ai/api/v1`
`api_key` | API 密钥 | `sk-xxx...`
`no_proxy` | 是否禁用代理 | `false`

### 模型配置

每个模型需要配置以下信息：

字段 | 说明 | 示例
--- | --- | ---
`alias` | 本地使用的模型别名 | `gemini-2.5-flash`
`provider_name` | 关联的服务商名称 | `openrouter`
`model_name` | 服务商侧的模型 ID | `google/gemini-2.5-flash`

### 默认模型类型

OpenDesk 支持为不同场景配置独立的默认模型：

模型类型 | 用途
--- | ---
`default_model` | 对话、任务等主要场景中使用的默认模型
`default_intent_parsing_model` | 意图解析使用的多模态模型
`default_embedding_model` | 知识库检索使用的向量嵌入模型
`default_reranker_model` | 检索结果重排序使用的模型
`default_vision_model` | 图片分析使用的多模态模型

### 配置文件位置

配置以 JSON 格式存储在用户数据目录中：

操作系统 | 路径
--- | ---
Windows | `%APPDATA%/opendesk/setting.json`
Linux / macOS | `~/.opendesk/setting.json`

### 配置文件示例

    {
      "default_model": "gemini-2.5-flash",
      "default_intent_parsing_model": "gemini-2.0-flash",
      "default_embedding_model": "text-embedding-3-small",
      "default_reranker_model": "rerank-english-v3.0",
      "default_vision_model": "gemini-2.0-flash",
      "providers": [
        {
          "name": "openrouter",
          "base_url": "https://openrouter.ai/api/v1",
          "api_key": "sk-xxx...",
          "no_proxy": false
        }
      ],
      "models": [
        {
          "alias": "gemini-2.5-flash",
          "provider_name": "openrouter",
          "model_name": "google/gemini-2.5-flash"
        }
      ]
    }

## 斜杠命令

在输入框中输入 `/` 即可查看可用命令列表并触发自动补全。所有命令均以 `/` 开头。

### 全局命令

命令 | 说明 | 用法 | 快捷键
--- | --- | --- | ---
`/new` | 启动新任务并发送消息 | `/new [消息]` | `Ctrl+N`
`/switch` | 切换到其他任务 | `/switch` | `Ctrl+L`
`/help` | 显示快捷键与指令帮助 | `/help` |
`/config` | 打开系统设置 | `/config` |
`/export` | 导出当前会话为 HTML 文件 | `/export [文件名]` |
`/dashboard` | 查看系统仪表盘 | `/dashboard` |
`/compact` | 手动压缩当前任务的上下文 | `/compact` |
`/fork` | 复制当前会话并切换到新会话 | `/fork` |
`/rename` | 重命名当前任务 | `/rename <新名称>` |
`/bookmark` | 管理任务书签 | `/bookmark add|list|remove` |
`/log` | 显示日志面板 | `/log [off|last|all]` |
`/debug` | 调试命令 | `/debug log [on|off]` 或 `/debug taskid` |
`/stop` | 停止当前正在执行的任务 | `/stop` |
`/cancel` | 撤销消息队列中的待发送消息 | `/cancel` |
`/clear` | 删除所有任务历史 | `/clear` |
`/upgrade` | 升级 CLI 到最新版本 | `/upgrade` |
`/exit` | 退出 OpenDesk | `/exit` |
`/quit` | 退出 OpenDesk（与 /exit 相同） | `/quit` |
`/manual` | 打开使用手册 | `/manual` |
`/memory` | 记忆管理（添加、搜索、删除、列表） | `/memory add|search|forget|list` |
`/quickpass` | 导出快捷口令（设置分享） | `/quickpass config base|all` |

### 应用命令

以下命令来自内置应用，用于打开对应的应用界面：

命令 | 说明 | 来源应用
--- | --- | ---
`/mail` | 打开邮箱 | 邮箱 (Mailbox)
`/calendar` | 打开日历 | 日历 (Calendar)
`/skills` | 打开技能管理界面 | 技能管理器 (SkillMgr)

### 命令详细说明

#### `/new` — 新建任务

创建一个新的任务会话，可选地立即发送一条消息。

    /new
    /new 分析这个项目的代码结构

#### `/export` — 导出会话

将当前会话导出为 HTML 文件。可自定义文件名，不指定则自动生成带时间戳的文件名。

    /export my-session.html
    /export

#### `/bookmark` — 任务书签

管理重要任务的书签，方便快速跳转。支持 Tab 自动补全参数。

    /bookmark add       # 将当前任务添加到书签
    /bookmark list      # 查看所有书签
    /bookmark remove    # 从书签中移除当前任务

#### `/log` — 日志控制

控制日志面板的显示。支持 Tab 自动补全参数。

    /log all     # 显示所有日志
    /log last    # 显示最后 10 条日志
    /log off     # 关闭日志显示

#### `/debug` — 调试命令

调试相关命令，包含日志开关和任务ID显示功能。支持 Tab 自动补全参数。

    /debug log on    # 开启调试日志
    /debug log off   # 关闭调试日志
    /debug log       # 查看当前调试日志状态
    /debug taskid    # 显示当前任务ID

#### `/memory` — 记忆管理

管理 AI 的长期记忆。支持全局记忆与工作区记忆两种范围，可由 AI 自动调用或通过斜杠命令手动操作。记忆操作基于大模型进行语义去重、合并与智能搜索。同一时刻只允许一个记忆操作执行。

    /memory add         # 从当前对话中提取并保存有价值的记忆（后台执行）
    /memory search 关键词  # 语义搜索相关记忆并注入对话上下文
    /memory forget 描述   # 根据描述智能删除匹配的记忆
    /memory list        # 打开记忆浏览面板，查看/筛选所有记忆

记忆类型：用户偏好、重要事实、关键决策、有用上下文

存储范围：全局记忆（跨项目共享）、工作区记忆（仅限当前项目）

AI 在对话中也会自动使用 `addMemory` 和 `searchMemory` 工具来管理记忆。

#### `/quickpass` — 快捷口令

将当前设置导出为口令字符串，方便通过微信、邮件等渠道分享给其他 OpenDesk 用户。口令内置完整性校验，确保传输过程中数据不被意外修改。

    /quickpass config base  # 导出基础设置口令（不含应用配置）
    /quickpass config all   # 导出全部设置口令（含应用配置）

导出：执行命令后，口令会在全宽弹窗中显示，方便复制。

导入：在 TUI 聊天输入框中粘贴完整口令并按回车，系统自动识别并导入。

口令格式：`[[Opendesk 名称 -- <base64+校验和>]]`

## 快捷键

快捷键 | 功能
--- | ---
`Ctrl + N` | 新建任务
`Ctrl + L` | 切换任务
`Ctrl + C` | 清空输入框 / 显示帮助提示
`Tab` | 自动补全命令
`Enter` | 提交输入
`↑ / ↓` | 浏览历史输入

## 上下文压缩

在长时间的对话中，上下文会不断增长并可能接近模型的上下文窗口限制。OpenDesk 提供了两级上下文压缩机制，可以自动或手动压缩上下文，确保对话流畅进行。

### 自动触发

当已使用的 prompt tokens 达到模型上下文窗口的 80% 时，系统会自动触发上下文压缩。OpenDesk 会先查询内置的模型上下文大小表，如果查不到则通过 API 获取。

### 手动触发

您可以随时使用 `/compact` 命令手动触发上下文压缩。

### 两级压缩机制

L1

#### Level 1 — 工具调用压缩

标记较旧的工具调用为"已压缩"，在构建发送给 LLM 的消息时跳过其详细内容。保留最近 30%（但不低于 10 个）的工具调用不压缩，其余标记 `compress_id`。

L2

#### Level 2 — 结构化总结

当 Level 1 不再有效果时，系统调用 LLM 对较旧的消息生成一份结构化总结，并以 `CompactSeparatorMessage` 的形式插入消息序列中。总结采用 XML 格式，包含以下信息：

- overall_goal：用户的核心目标
- key_knowledge：必须记住的关键事实与约束
- file_system_state：文件操作记录
- recent_actions：近期操作及结果
- current_plan：当前分步计划及各步状态

### 压缩流程

1 检测 `prompt_tokens ≥ contextSize × 80%`，触发压缩
2 执行 Level 1：压缩旧的工具调用详情
3 若 Level 1 无新增效果，升级到 Level 2：调用 LLM 生成结构化总结
4 插入 `CompactSeparatorMessage`，后续请求仅发送总结 + 近期消息

## 安装 MCP Server

MCP (Model Context Protocol) 是一种标准协议，用于让 AI 模型使用外部工具和数据源。OpenDesk 支持自动搜索、下载、安装和管理 MCP Server，无需手动编写配置文件。

### 对话式安装

最简单的方式是直接告诉 AI 助手您需要什么功能，它会自动搜索并安装合适的 MCP Server。

    # 直接用自然语言描述需求
    帮我安装一个可以操作文件系统的 MCP Server
    帮我安装一个 GitHub MCP Server

[截图] MCP Server 安装过程

展示对话式安装 MCP Server 的交互过程

### MCP Server 配置参数

每个 MCP Server 支持以下配置：

字段 | 说明 | 适用传输方式
--- | --- | ---
`name` | 显示名称 | 全部
`transport` | 传输方式 | `stdio` / `sse` / `streamableHttp`
`enabled` | 是否启用 | 全部
`command` | 启动命令（如 `npx`、`node`） | `stdio`
`args` | 命令参数列表 | `stdio`
`cwd` | 工作目录 | `stdio`
`url` | 远程服务 URL | `sse` / `streamableHttp`
`headers` | 自定义 HTTP 请求头 | `sse` / `streamableHttp`
`env` | 环境变量 | `stdio`

### 管理工具

AI 助手内置了以下 MCP 管理工具，您可以通过自然语言调用：

`installMcpServer`

安装新的 MCP Server

`listMcpServers`

列出已安装的 MCP Server 及其状态

`deleteMcpServer`

删除指定的 MCP Server

`toggleMcpServer`

启用或禁用指定的 MCP Server

### 从其他工具导入

OpenDesk 支持从 Claude Desktop 或 Cursor 的 MCP 配置 JSON 文件中批量导入 MCP Server 配置。

## 安装 Skill 技能

Skill（技能）是 OpenDesk 的扩展能力单元，每个技能是一个包含 `SKILL.md` 文件的目录，兼容 Anthropic Agent Skills 格式。技能可以从在线平台或本地路径安装。

### 安装来源

#### 在线平台

从 Skill0.io、SkillsMP、ClawHub 等平台搜索和安装技能。

#### GitHub

通过 GitHub 仓库 URL 直接安装技能。

#### 本地路径

从本地目录安装，适合开发自定义技能。

#### URL 下载

通过 URL 下载 zip / tar.gz 格式的技能包。

### 对话式安装

    # 搜索并安装技能
    帮我搜索一个可以创建 Cursor Rule 的技能并安装

    # 从 GitHub 安装
    帮我安装这个技能：https://github.com/user/my-skill

    # 查看已安装技能
    列出所有已安装的技能

### 管理工具

工具 | 说明
--- | ---
`addSkillFromPath` | 从本地目录安装技能
`addSkillFromUrl` | 从 URL 下载安装技能
`addSkillFromGitHubUrl` | 从 GitHub 仓库安装技能
`listSkills` | 列出已安装的技能
`deleteSkill` | 删除指定技能
`refreshSkills` | 刷新技能列表
`getSkillsDirectory` | 查看技能存储目录

### 使用 /skills 命令

输入 `/skills` 命令可以打开技能管理界面，查看和管理所有已安装的技能。

## 邮箱配置

OpenDesk CLI 内置了邮箱应用，支持收发邮件。您可以通过对话式配置来添加邮箱账户，系统会自动识别常见的邮箱服务商并使用预设配置。

### 对话式配置

    # 添加邮箱账户
    帮我配置 QQ 邮箱，邮箱地址是 user@qq.com

    # 查看已配置的邮箱
    列出我的邮箱账户

    # 切换默认邮箱
    切换到我的 163 邮箱

### 支持的邮箱服务商

OpenDesk 预置了以下邮箱服务商的服务器配置：

QQ 邮箱 163 邮箱 126 邮箱 yeah.net Outlook Gmail 139 邮箱 新浪邮箱 搜狐邮箱 阿里邮箱 华为邮箱

### 邮箱账户配置参数

字段 | 说明 | 备注
--- | --- | ---
`name` | 账户显示名称 |
`email` | 邮箱地址 |
`password` | 密码或授权码 | 部分邮箱需使用应用专用密码
`inbox.protocol` | 收件协议 | `pop3` 或 `imap`
`inbox.host / port` | 收件服务器地址和端口 | 预设服务商自动填充
`outbox.host / port` | 发件服务器 (SMTP) 地址和端口 | 预设服务商自动填充

### 使用邮箱

配置完成后，可以使用 `/mail` 命令打开邮箱界面查看和管理邮件，也可以直接通过自然语言让 AI 助手帮您收发邮件。

    # 查看邮件
    帮我看看最新的邮件

    # 发送邮件
    帮我给 colleague@example.com 发一封邮件，主题是"会议安排"

## 日历配置

OpenDesk 内置日历应用，支持本地日程管理，并可选择同步 Outlook 日历数据（仅 Windows 平台）。

### 数据源

#### 本地数据库

默认使用 NeDB 本地数据库存储日程，数据保存在 `apps/calendar/calendar.db` 中，无需额外配置。

#### Outlook 同步仅 Windows

可选启用 Outlook 日历同步，通过 PowerShell 读取本地 Outlook 日程数据。

### 配置 Outlook 同步

进入 `/config` 配置菜单，在日历应用的配置中启用 Outlook 数据源：

    {
      "applications": {
        "calendar": {
          "dataSources": {
            "outlook": {
              "enabled": true
            }
          }
        }
      }
    }

### 使用日历

使用 `/calendar` 命令打开日历界面，或通过自然语言让 AI 助手管理日程。

    # 查看今天的日程
    今天有什么安排？

    # 添加日程
    帮我在明天下午 2 点添加一个会议，主题是"项目评审"

    # 删除日程
    帮我取消今天下午的会议

### 日程参数

字段 | 说明
--- | ---
`subject` | 日程主题
`date` | 日期（YYYY-MM-DD 格式）
`startTime / endTime` | 开始 / 结束时间
`location` | 地点
`isAllDay` | 是否为全天事件

## 应用概览

OpenDesk 桌面版包含丰富的内置应用，以下是各应用的简要介绍。详细使用文档正在编写中。

### AI Agent Center

多 Agent 聊天、OpenAI API 兼容、流式输出和工具调用。

### 智能邮箱

POP3/IMAP 收件和 SMTP 发件，AI 辅助邮件处理。

### 日历

日程管理，支持 Outlook 同步。

### 新闻聚合

Hacker News 等多来源新闻聚合。

### 文件管理器

文件浏览、搜索，AI 驱动的文件操作。

### 统一搜索

向量索引 + BM25 + 关键字混合搜索。

### 快速录屏 (Recall)

屏幕录制与回放。

### 待办管理

任务和待办事项的 AI 辅助管理。

### PPT / Designer

AI 驱动的演示文稿和设计工具。

提示：桌面应用的详细使用文档正在编写中，敬请期待。