> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用 Bosi 进行开发

> 在 Bosi 桌面应用中通过项目组织开发工作，使用内置的本机 Shell 逐条审批并执行命令，在云电脑中打开编程工具，连接自己的 Xpert 服务，并配置自动化。

在日常开发中，你可能希望助手围绕一个项目的资料持续工作，帮你查看本机环境、在指定目录中执行命令、生成文件，或者每天定时汇总项目进展。Bosi 桌面应用把这些能力放在同一个窗口里：助手和它的默认沙箱仍然运行在 Xpert 服务端，只有在你明确批准后，命令才会在你的电脑上执行。

本教程介绍在 Bosi 中进行开发的三种方式：通过 **项目** 组织开发资料和会话，通过 Bosi 内置的 **本机 Shell** 让助手在你的电脑上执行命令，以及在 **云电脑** 的 **编程工具** 中打开编程命令行工具。教程以“让助手在本机测试目录中执行命令并核对结果”为例，演示命令的审批流程，并介绍如何连接自己的 Xpert 服务和配置自动化。

## 完成本教程后，你可以

* 在 Bosi 中与助手协作处理开发任务，使用插件和交付文件。
* 在 Bosi 的对话中使用项目，并理解项目会话的切换规则。
* 通过“创建你的 Bosi”开启本机 Shell，或使用已启用 Desktop Shell 的助手。
* 配置本机终端，并理解三种执行权限的区别。
* 在对话中审批或拒绝助手请求的本机命令。
* 在云电脑中打开编程工具，并理解“模型兼容”等标签的含义。
* 区分本机命令、服务端沙箱命令和云电脑三种执行位置。
* 将 Bosi 连接到自行部署或本地开发的 Xpert 服务。
* 为助手配置定时计划等自动化。

如果还没有安装 Bosi，请先阅读 [Bosi 桌面应用使用指南](/zh-Hans/ai/tutorial/bosi-desktop-user-guide)。

## 三种开发方式

| 方式 | 适合的场景 | 运行位置 |
| - | - | - |
| 通过项目开发 | 围绕同一个项目集中管理资料、工具和会话，让助手基于共享上下文持续推进任务 | Xpert 服务端 |
| 通过内置本机 Shell 开发 | 让助手在你的电脑上查看目录、运行构建或测试命令、写入文件 | 你的 Mac，每条命令按执行权限审批 |
| 通过云电脑的编程工具开发 | 在云电脑中打开 Codex、Claude Code 等编程命令行工具，使用本会话的模型处理代码 | 服务端的云电脑 |

这些方式可以一起使用：在项目会话中处理任务，需要操作本机时再由助手请求本机命令，需要编程命令行工具时在云电脑中打开。

## 开始前的准备

| 准备事项 | 如何确认 |
| - | - |
| 已登录的 Bosi | 能在 Bosi 中选择组织和助手并正常对话 |
| 匹配的服务端版本 | Xpert 服务端、Bosi 和 ChatKit 的版本相互匹配 |
| 项目功能（使用项目时） | 所连接的 Xpert 服务和 ChatKit 提供项目功能，你有权访问目标项目 |
| macOS 原生应用（使用本机 Shell 时） | 本机 Shell 仅在 macOS 原生应用中可用 |
| 支持工具调用的模型（使用本机 Shell 时） | 组织为助手配置的模型支持工具调用 |
| 一个测试目录（使用本机 Shell 时） | 准备一个可以随意写入文件的目录，用于首次验证 |
| 云电脑（使用编程工具时） | 所连接的服务端为助手提供云电脑，助手的工作台中可以打开 **电脑** 视图 |

项目、本机 Shell 和云电脑的功能和限制可能随版本调整，以你所用版本的界面提示为准。

## 与助手协作处理开发任务

在 Bosi 中选择助手后，右侧的对话区域提供消息、附件、历史会话、工具、技能、连接器和工作台。处理开发任务时，常用的方式有：

* **描述目标，让助手拆解**：直接说明要完成的工作和验收方式，例如“检查当前项目目录结构，并说明如何运行测试”。
* **上传附件**：把需要分析的文件作为附件发送给助手。
* **选择插件**：在 **发现与添加 → 插件** 中可以查看租户或组织内已安装的插件及其包含的能力。已安装的插件可以直接在会话的 **插件** 菜单中选择使用，所需的连接仍按现有流程配置和授权。
* **查看交付文件**：助手生成文件后，点击对话中的交付卡片，可以预览交付时保存的文件版本并下载。暂不支持预览的格式可以直接下载。

如果你有工作空间的编辑权限，可以在助手的 **编辑资料** 中调整模型、能力和提示词，点击 **保存并发布** 后生效。这些专家配置会影响此专家的所有使用者；个人资料则只保存在本机。需要更复杂的编排时，选择 **在 Xpert Studio 中编排**。

## 方式一：通过项目进行开发

项目是 Xpert 平台的协作功能，可以把数字专家、工具集、文件资源和会话记录集中在一起，让参与的智能体基于共享的文件和项目级指令完成任务。项目本身的创建、成员、文件、工具集和执行模式，见[项目](/zh-Hans/ai/agent/conversation/projects)。

### 在 Bosi 中使用项目

Bosi 的对话区域嵌入了 Xpert ChatKit，并在输入框中启用了项目功能。因此，你可以在 Bosi 的对话中直接使用项目，无需切换到网页端。项目相关的按钮、菜单和确认步骤由 ChatKit 提供，具体名称和位置以所连接的 ChatKit 版本为准。

使用项目进行开发时，建议：

1. 把需求文档、接口说明等资料作为项目文件上传，让项目中的智能体都能读取。
2. 为项目添加需要的工具集，并设置项目级指令，例如代码规范、目录约定和提交要求。
3. 在项目会话中描述开发目标，让助手拆解任务并逐步推进。
4. 需要在本机查看代码或运行命令时，使用下文的本机 Shell。

### 打开项目与切换会话

* 从工作台或对话中打开某个项目时，Bosi 会切换到该项目的会话，并使用该项目绑定的助手。
* 打开一个属于项目的历史会话时，Bosi 会在该会话所属的项目和助手下继续对话。
* 项目的访问权限由服务端检查。没有权限时，打开项目会失败，Bosi 保持当前助手不变，不会改用其他助手打开该项目。
* 重新打开会话时，会话中尚未确认的项目操作会保留，可以继续处理。

如果项目绑定的助手启用了 Desktop Shell，在项目会话中同样可以请求本机命令，审批方式与普通会话相同。

## 方式二：通过内置本机 Shell 进行开发

Bosi 内置了“此电脑的 Shell”（设置中显示为 **本机终端**）。助手在对话中请求执行命令后，命令在你的 Mac 上运行，输出和退出码返回到对话中。

本机 Shell 不提供可以手动输入命令的交互式终端窗口。每条命令都由助手发起，在一个新的非交互 Shell 中执行，并按你设置的执行权限审批。需要直接使用编程命令行工具时，可以使用云电脑中的编程工具，见下文的方式三。

### 第一步：为助手开启本机 Shell

可以通过以下任一方式，让助手具备本机命令能力。

**通过“创建你的 Bosi”开启**

在所连接的服务端支持、并且你在当前组织中还没有创建个人 Bosi 时，登录后主区域会显示 **创建你的 Bosi**：

1. 阅读介绍后点击 **继续**。
2. 在 **让 Bosi 更懂你的工作** 中选择需要的能力并连接账号，也可以点击 **稍后设置**。
3. 在 **选择 Bosi 的工作方式** 中打开需要的能力：
   * **Bosi 的电脑**：使用服务端电脑及其中的应用。服务端提供此能力时默认开启。
   * **此电脑的 Shell**：运行本机命令，沿用现有命令审批。只能在 macOS 原生应用中开启。
4. 选择助手模型。开启 Bosi 的电脑时，需要选择支持视觉和工具调用的兼容模型。
5. 点击 **创建 Bosi**。初始化中断后，可以点击 **恢复初始化** 继续。

开启“此电脑的 Shell”不会放宽执行权限：默认仍然是每条命令先询问。能力不可用时，开关下方会显示原因，例如当前服务端未提供此能力。

**使用已启用 Desktop Shell 的助手**

对于其他助手，需要管理员在 Xpert Studio 中为该助手连接 **Desktop Shell** 中间件并发布。助手需要同时在服务端执行命令时，可以保留 **Sandbox Shell** 中间件。

### 第二步：配置本机终端

打开 **设置 → 本机终端**，在这里管理这台电脑上的命令执行：

| 设置项 | 说明 |
| - | - |
| 执行权限 | 每条命令先询问（默认）、始终允许此组织的命令、禁止执行。选择后立即生效 |
| 电脑名称 | 审批卡片和命令结果中显示的电脑名称 |
| Shell | 选择 zsh 或 bash |
| 默认工作目录 | 命令的起始目录。首次验证时建议设置为测试目录 |
| 命令搜索路径 | 执行命令时查找可执行程序的路径 |

修改电脑名称、Shell、默认工作目录或命令搜索路径后，点击 **应用 Shell 设置**。这些更改需要在本机终端中单独应用，不受设置页底部 **保存设置** 的影响。应用 Shell 设置会断开当前连接并撤销尚未执行的授权，下一次命令请求时按新设置重新连接。

三种执行权限的区别：

| 执行权限 | 效果 |
| - | - |
| 每条命令先询问 | 默认选项。每条命令执行前都会在消息中显示审批卡片，批准一次只执行这一条命令 |
| 始终允许此组织的命令 | 不再逐条询问，后续命令直接执行 |
| 禁止执行 | 不显示审批卡片，也不执行任何本机命令；正在运行的命令会被停止 |

执行权限仅适用于当前账号、当前组织和这台电脑。除非你完全信任该组织中会请求本机命令的助手，否则建议保留 **每条命令先询问**。

无需手动连接或为会话单独授权：助手请求本机命令时，Bosi 会按需自动连接。本机终端页面会显示当前状态，例如按需自动连接、正在连接或已连接。

### 第三步：请求并审批本机命令

在已开启本机 Shell 的助手对话中发送：

```text theme={null}
请在本机执行命令：查看当前操作系统和当前目录，
然后在当前目录写入一个名为 bosi-test.txt 的文件，内容为 hello。
完成后告诉我命令的退出码。
```

使用默认的 **每条命令先询问** 时：

1. 助手请求本机命令后，消息中会出现审批卡片，写明要执行的命令、电脑、工作目录和访问说明。
2. 核对命令内容。在你作出选择之前，命令不会执行。
3. 在卡片上选择只允许这一次执行，或者拒绝。卡片上的权限入口会打开 **本机执行权限** 窗口，内容与本机终端设置相同。
4. 批准后，命令在本机执行，输出和退出码返回给助手。下一条命令需要再次审批。
5. 拒绝后，命令不会执行。助手应停止这次操作，不会改用服务端 Shell 代替执行。

完成后，在测试目录中打开 `bosi-test.txt`，确认文件内容与预期一致。以实际文件和退出码为准，不要只看助手的文字描述。

对话页头可以显示助手可以使用的电脑及其状态。从对话中打开本机电脑时，Bosi 同样会弹出 **本机执行权限** 窗口。

### 查看和停止命令

在 **设置 → 本机终端** 或 **本机执行权限** 窗口中，可以查看最近的命令，包括工作目录、状态（等待中、运行中、正在停止、已成功、已失败、已取消、已超时、已拒绝、未知）和最近的输出。需要中断正在运行的命令时，点击 **停止命令**。

状态为“未知”时，表示无法确认命令是否完成。Bosi 不会重复执行这条命令；请自行检查实际结果，再决定是否重新请求。

### 了解本机命令的执行方式

**安全边界**

* 命令以你当前登录的操作系统用户权限执行。工作目录只是起始目录，不是隔离沙箱，不会限制文件访问范围。
* 命令的输出会发送给 Xpert，并保存在服务端。输出中可能包含业务数据，请避免执行会输出敏感信息的命令。
* 每条命令使用一个新的非交互 Shell，只继承少量环境变量，不会继承平台账号或设备凭证。
* 不提供交互式终端（PTY）、交互输入、持续的 Shell 会话、文件同步或本地智能体运行时。需要交互输入的命令无法正常使用。

**使用限制**

| 项目 | 限制 |
| - | - |
| 并发命令 | 每台电脑同时只执行 1 条命令，其他请求会被拒绝 |
| 电脑离线 | 直接返回离线，不会排队，也不会改用服务端沙箱 |
| 同步等待 | 10 秒；超过后助手通过查询状态获取最终结果 |
| 命令超时 | 默认 60 秒，单条命令最长 600 秒 |
| 单条命令保留的输出 | 1 MiB，超出部分会被丢弃 |

**何时会停止**

* 关闭 macOS 窗口后，应用和本机终端仍在运行。
* 切换组织、修改服务连接、退出登录或退出应用，都会停止本机终端。
* 重启应用后，已选择的执行权限会保留，但临时授权不会保留。
* 已过期的审批无法执行。请拒绝或停止这次请求，再发起新的请求。

### 区分三种执行位置

同一个助手可以同时具备多种执行能力。请在提问时说明希望在哪里执行，并核对返回结果中的执行位置。

| 执行位置 | 由什么提供 | 适合的任务 |
| - | - | - |
| 本机电脑 | 此电脑的 Shell（Desktop Shell 中间件 + Bosi 本机终端） | 查看或操作你电脑上的项目和文件，需要你审批 |
| 服务端沙箱 | **Sandbox Shell** 中间件 | 在服务端隔离环境中执行代码和命令，详见[沙箱功能](/zh-Hans/ai/agent/sandbox) |
| 云电脑 | Bosi 的电脑或其他云电脑类助手 | 让助手操作服务端电脑及其中的应用，或在其中打开编程工具 |

验证本机执行时，服务端沙箱返回的结果不算作本机执行。云电脑类任务需要支持视觉和工具调用的模型，组织中是否提供此能力以服务端配置为准。

## 方式三：通过云电脑的编程工具进行开发

云电脑是服务端为你提供的私有 Ubuntu 桌面，你和 Agent 可以同时操作。云电脑面板中的 **编程工具** 列出本会话可以使用的编程命令行工具（CLI），例如 Codex、OpenCode、Aider、Claude Code、Qwen Code、Kimi Code 和 CodeBuddy。实际列出的工具以组织的配置为准。

与本机 Shell 不同，编程工具运行在云电脑中，使用当前会话助手的模型，你可以直接打开这些工具处理代码。

### 连接并操作云电脑

1. 在助手的工作台中打开 **电脑** 视图，进入 **云电脑** 面板。
2. 点击 **连接查看**。连接后，桌面上方会显示 **人类与 Agent 共享桌面**，底部显示控制栏。
3. 需要操作桌面时，点击控制栏中的 **开始操作**。控制栏左侧显示 **你可以操作**。
4. 只想观看时，点击 **仅查看**。

输入会话最长 15 分钟，5 分钟没有输入后结束。断开查看不会删除云电脑中已安装的软件或文件。

### 打开编程工具

1. 点击控制栏中的终端图标，打开 **编程工具**。
2. 面板顶部显示提示“使用本会话可用的模型。退出电脑接管后，任务仍可继续运行。”，以及当前助手、模型和工作目录。
3. 在列表中找到需要的工具，查看它的标签，然后点击 **打开**。

**打开** 只有在你已点击 **开始操作**、并且该工具可用时才能点击。工具不可用时，按钮上会提示“本会话没有已启用的兼容模型”。

如果当前助手还没有会话，面板会提示“先为当前 Assistant 创建会话，即可使用编程工具，无需发送聊天消息。”，点击 **创建会话** 即可。

在项目会话中，编程工具的默认工作目录是项目的文件根目录，与项目中的其他助手共享代码和文件。

### 了解工具标签

每个工具下方显示三个标签：

| 标签 | 含义 |
| - | - |
| 已安装 / 未安装 / 版本不匹配 / 安装状态未知 | 该工具在云电脑中的安装情况 |
| 模型兼容 | 当前会话的默认模型可以用于该工具 |
| 模型不兼容 | 当前会话的模型不能用于该工具 |
| 支持受管任务 | 该工具可以作为受管任务在后台运行 |
| 仅交互运行 | 该工具只能交互使用，不支持受管的后台任务 |

只有同时显示 **已安装** 和 **模型兼容** 的工具才可以打开。

编程工具不使用单独的模型，而是使用当前会话的模型，并且该模型需要支持此工具所用的协议。显示 **模型不兼容** 时，该工具无法使用本会话的模型，即使已安装也不能打开。例如，Codex 显示模型不兼容时，在本会话中运行它可能会返回错误“requested model is not available for this execution”。需要使用这类工具时，请为助手选择该工具兼容的模型后再试。

模型由平台按会话提供，不需要在云电脑中配置自己的模型 API Key。

### 管理编程会话

打开工具后，编程会话会显示在面板下方的列表中，包括工具名称、状态、助手和模型以及工作目录。状态包括正在启动、运行中、正在停止、已退出和状态未知。还没有会话时，列表显示 **暂无编程会话**。

* 需要结束某个会话时，点击该会话旁的 **停止**。已退出的会话不再显示停止按钮。
* 点击 **仅查看** 退出电脑接管后，编程任务仍可继续运行。

### 推荐的编程助手指令

云电脑的默认镜像中内置了云编程技能 `/opt/xpert/skills/cloud-coding/SKILL.md`，提供以命令行工具为主的任务、审批、恢复和交付指引。希望助手在处理开发任务时遵循这套流程，可以在助手的 **编辑资料** 中，将下面的内容加入提示词，然后点击 **保存并发布**：

```text theme={null}
当任务涉及代码开发、修改、调试或测试时，先使用 sandbox_shell 读取 /opt/xpert/skills/cloud-coding/SKILL.md，然后按其中的流程完成任务。需要补充说明时，再按该文件的指引读取 references/ 中的相关文件。
```

加入后，遇到代码开发、修改、调试或测试任务时，助手会先在沙箱中读取云编程技能，再按其中的流程完成任务。此指令依赖 **Sandbox Shell** 中间件提供的 `sandbox_shell` 工具。创建 Bosi 时开启了 **Bosi 的电脑**，Bosi 的提示词中已经包含云编程技能的指引，无需重复添加。

## 连接自己的 Xpert 服务

开发或测试时，可以把 Bosi 连接到自行部署或本地运行的 Xpert 服务：

1. 在登录页点击 **连接设置**，或在登录后打开 **设置 → 服务连接**。
2. 填写 API 服务地址、Xpert 网页地址和 ChatKit 地址。远程服务需要使用 HTTPS；本机 `localhost` 地址可以使用 HTTP。
3. 等待页面检查地址和证书。使用你信任的自签名证书时，开启 **允许不受信任的服务证书**。此设置同样作用于本机终端到所配置 API 服务的连接。
4. 保存设置，重新登录。

部署方需要注意：

* 本机终端通过 API 服务的 Socket.IO 端点（`/socket.io/`）建立 WebSocket 连接。反向代理需要允许 WebSocket 升级。
* 本机电脑不会开放任何监听端口，连接由 Bosi 主动发起。
* 升级时，请同时部署匹配版本的服务端、Bosi 和 ChatKit。只更新 Bosi 不会让旧的 ChatKit 获得新能力。

## 配置自动化

自动化让助手在指定时间、按计划或事件发生时自动开始工作，并复用助手已发布的指令、技能、工具和连接器。管理自动化需要助手已经发布，并且你拥有工作空间的编辑权限。

1. 将鼠标停在侧栏中的助手头像上，打开助手资料面板，切换到 **自动化**。

2. 新建一个自动化。

3. 选择触发方式：

   | 触发方式 | 何时运行 |
   | - | - |
   | 定时计划 | 在指定时间或按计划运行 |
   | 应用事件 | 应用中发生指定事件时运行 |
   | Webhook | 收到 HTTP 请求时运行 |
   | Email | 收到新邮件时运行 |

   定时计划以外的触发方式，需要先在 Xpert 中安装对应类型的 Provider 插件。

4. 设置条件和范围。定时计划可以选择每小时、每天、每个工作日、每周，或者使用自定义计划填写 Cron 表达式（依次为分钟、小时、日期、月份、星期）。定时计划使用 Xpert 服务器的时区。

5. 按需填写补充指令，例如“汇总昨天合并的代码变更和未关闭的问题”。助手的职责、技能、工具和连接器会自动继承，无需重复配置。

6. 确认配置并保存。

保存后，可以在自动化列表中查看最近运行时间，并暂停或启用自动化。每个 Provider 在一个助手上只能配置一个触发器；需要修改时，请编辑已有配置。

## 确认已经可以使用

| 检查内容 | 操作 | 完成标志 |
| - | - | - |
| 项目会话 | 在 Bosi 中打开一个有权访问的项目 | 对话切换到该项目，并使用项目绑定的助手 |
| 本机终端设置 | 在设置中设置测试目录并应用 Shell 设置 | 设置已应用，没有错误提示 |
| 审批流程 | 请求一条本机命令 | 消息中出现审批卡片，批准前命令未执行 |
| 本机执行 | 批准后检查测试目录 | 文件内容与预期一致，退出码为 0 |
| 拒绝流程 | 再请求一条命令并拒绝 | 命令未执行，助手停止这次操作 |
| 编程工具 | 在云电脑中点击 **开始操作**，打开一个显示已安装和模型兼容的工具 | 面板的编程会话列表中出现该工具，状态为正在启动或运行中 |
| 自动化 | 创建一个定时计划 | 自动化列表中显示该计划 |

## 常见问题

### 在 Bosi 的对话中找不到项目入口

项目相关的界面由所连接的 ChatKit 提供。请管理员确认 Xpert 服务端和 ChatKit 已部署支持项目功能的匹配版本。

### 打开项目时提示没有权限

项目的访问权限由服务端检查。请联系项目成员或管理员授予访问权限。没有权限时，Bosi 会保持当前助手不变。

### 没有看到“创建你的 Bosi”

该流程只在服务端支持、并且你在当前组织中还没有个人 Bosi 时显示。提示“当前服务端尚不支持 Bosi 初始化”时，需要更新 Xpert 服务端。也可以改用已启用 Desktop Shell 的助手。

### 设置中提示桌面 Shell 需要在 macOS 原生应用中使用

本机 Shell 目前只能在 macOS 原生应用中使用。请在 Mac 上安装并登录 Bosi。

### 助手没有请求本机命令

确认助手已开启此电脑的 Shell，或管理员已为该助手连接 **Desktop Shell** 中间件并重新发布；同时确认模型支持工具调用，并且你提问时明确要求在本机执行。

### 提示本机 Shell 已在权限设置中禁用

执行权限被设置为 **禁止执行**。在 **设置 → 本机终端** 中修改执行权限，再发起新的命令。

### 提示此电脑已离线

Bosi 当前没有连接，命令不会排队等待。确认 Bosi 正在运行并已登录，然后重新请求，不要让助手自动重试。

### 提示命令授权已过期或撤销

审批有有效期，应用 Shell 设置也会撤销尚未执行的授权。请在当前对话中重新请求命令。

### 账号或组织切换后命令无法执行

切换账号或组织会停止本机终端。请在当前对话中重新请求授权。

### 云电脑中没有显示编程工具图标

当前会话没有可用的编程工具、编程会话或提示信息时，控制栏不显示编程工具图标。请联系管理员确认组织已为云电脑配置编程工具。

### 编程工具的“打开”按钮无法点击

确认你已点击 **开始操作**，并且该工具同时显示 **已安装** 和 **模型兼容**。显示 **模型不兼容** 时，当前会话的模型不能用于该工具，请为助手选择兼容的模型。

### 自动化列表中无法新建

确认助手已经发布，并且你拥有工作空间的编辑权限。定时计划以外的触发方式需要先安装对应的 Provider 插件。

## 相关文档

* [Bosi 桌面应用使用指南](/zh-Hans/ai/tutorial/bosi-desktop-user-guide)
* [项目](/zh-Hans/ai/agent/conversation/projects)
* [发现与添加](/zh-Hans/ai/agent/conversation/discover-and-add)
* [沙箱功能](/zh-Hans/ai/agent/sandbox)
* [人机协同中间件](/zh-Hans/ai/middleware/built-in/human-in-the-loop)
* [Assistant 资料卡](/zh-Hans/ai/agent/assistant-profile)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.