> For AI agents: the complete documentation index is available at https://docs.danqiuos.com/llms.txt, the full documentation bundle is available at https://docs.danqiuos.com/llms-full.txt.

# 连接 WorkBuddy 或 Codex

你可以让 WorkBuddy 或 Codex 在本地开发项目中使用 `octopus-cli`，连接企业 Octopus 环境并构建应用。本页完成后，AI 开发工具应能识别开发 Skill、核对登录上下文，并在你指定的团队内开展已授权工作。

**选择一个工具即可。** WorkBuddy 与 Codex 使用同一份 Workbench 开发 Skill，只是安装目标不同。这里的 AI 工具是开发助手；后续销售助理、报销助理是部署在企业 Team 内的业务数字员工。

## 1. 准备环境和企业信息

| 准备项                             | 从哪里获得或怎样确认                           |
| ------------------------------- | ------------------------------------ |
| WorkBuddy 或 Codex               | 使用可访问本地项目、运行终端并加载 Skill 的工作环境        |
| Node.js / npm、Git、Bash、Python 3 | 用于 CLI 安装、克隆与官方 Skill 安装校验；按官方依赖要求准备 |
| 企业 Portal 地址                    | 从企业管理员获取或复制实际 Portal 的来源地址，不使用本文示例代替 |
| 账号与目标 Team ID                   | 由管理员确认账号权限及需要装配的团队                   |
| 开发目录                            | 新应用选择空目录；已有应用打开原工程，保留现有改动            |
| 业务权限                            | 明确谁可以创建数据应用、配置员工，以及进行样例写入和发布         |

以下安装命令使用 Bash。Windows 用户应使用可供所选 AI 工具访问的 Bash 环境，并确认安装位置、CLI 与项目位于同一执行环境；不要把装在另一个用户或环境中的 Skill 当作已加载。

## 2. 安装并连接 Octopus CLI

可在 AI 工具的终端运行，也可以让 AI 工具协助检查和执行。先检查是否已有 CLI；没有安装时再安装：

```bash
octopus-cli --version
```

```bash
npm install -g @syngy/octopus-cli
```

把下方占位内容替换为企业提供的真实值。`<profile>` 是你为该企业环境选择的本地配置名称：

```bash
octopus-cli auth login --profile "<profile>" --web-url "<企业 Portal 来源地址>"
octopus-cli configure team use "<teamId>"
octopus-cli auth whoami --json
```

按照 CLI 提示在浏览器中完成登录授权，再核对返回的 Profile、Host、账号和 Team。CLI 登录和团队绑定成功，不代表该身份自动获得全部业务资源权限。

已有多个配置时，先选择正确的 Profile，再切换团队并复核：

```bash
octopus-cli auth profiles list
octopus-cli auth profiles use "<profile>"
octopus-cli configure team use "<teamId>"
octopus-cli auth whoami --json
```

缺少地址、团队或必要权限时向管理员补齐；不要根据公司简称猜测域名或 Team ID。具体参数以当前命令 `--help` 为准。本文连接命令已与官方开发契约及本机 CLI 0.1.13 帮助核对，未代替你的企业登录验证。

## 3. 安装 Workbench 开发 Skill

开发流程由 [Workbench App Development Skill](https://github.com/syngy-ai/workbench-app-development-skill) 统一维护。首次安装，在你选择的工具资料目录中克隆仓库：

```bash
git clone https://github.com/syngy-ai/workbench-app-development-skill.git
cd workbench-app-development-skill
```

按你使用的 AI 工具，**只执行对应一条**：

```bash
# 使用 Codex
./scripts/install-local.sh codex
```

```bash
# 使用 WorkBuddy
./scripts/install-local.sh workbuddy
```

默认安装位置分别为 `~/.codex/skills/workbench-app-development` 与 `~/.workbuddy/skills/workbench-app-development`；Codex 配置了 `CODEX_HOME` 时，安装脚本遵循该配置。脚本先用 Python 3 校验，再复制 Skill。已有该仓库时复用并核对版本，不要在非空业务应用目录中重复克隆或脚手架化。

安装完成后新建 AI 会话或重新加载技能，并打开你自己的业务应用项目目录。可以发送：

```text
请确认你能读取 workbench-app-development Skill 及其引用的命令和本地验收契约。
检查当前项目目录：新应用应为空，已有应用应保留现有工程和改动。
通过 octopus-cli auth whoami --json 核对当前 Profile、Host、账号和 Team，
并与我提供的企业信息比较。现在只检查，不创建应用、数据或远端项目。
请告诉我已具备哪些条件，以及还缺什么。
```

如果 AI 无法发现 Skill，核对所选客户端、运行用户和安装目录，再重新加载。不要仅因为安装输出显示成功，就假定当前会话已读取技能。

## 4. 确认可以开始开发

继续之前，应得到四项明确结果：

- AI 工具已读取 `workbench-app-development`，包括实际命令与本地验证契约。
- CLI 返回的企业环境、账号与目标 Team 一致。
- 业务应用目录已确定，新旧项目路径没有混淆。
- 需要使用的资源与管理权限已确认，尚未执行未授权写入。

浏览器中的 Workbench 本地开发登录是下一阶段的独立检查。CLI 已登录，并不代表本地应用浏览器已经有登录会话；后续应使用脚手架提供的开发登录 / JCode 流程，授权后返回业务页面。

## 常见卡点

| 现象            | 下一步                                          |
| ------------- | -------------------------------------------- |
| 找不到 CLI       | 检查安装是否成功，以及 AI 终端与安装终端的 PATH 和执行环境是否一致       |
| 登录到了其他企业或团队   | 选择正确 Profile 和 Team，再运行 `auth whoami --json` |
| Skill 不可见     | 检查客户端安装目标与运行用户，重新加载或新建会话                     |
| 能登录但不能建表或配置员工 | 请管理员授予明确的装配权限，或由授权人员完成配置                     |
| 本地应用要求再次登录    | 完成官方脚手架的开发登录；不要手写 token 存储或第二套登录页            |

准备完成后进入[快速开始：构建 CRM 场景方案](https://docs.danqiuos.com/start/quickstart.md)，从应用、数据和员工的分工开始。